VirtualBox.xidl@ 46465

Last change on this file since 46465 was 46465, checked in by vboxsync, 11 years ago
Main/VPX: introduced onVideoCaptureChange event
Property svn:eol-style set to `native`
File size: 759.5 KB

Line
1	<?xml version="1.0" encoding="utf-8"?>
2
3	<!--
4
5	Copyright (C) 2006-2013 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	and the VBoxManage command-line interface) 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
110	The naming of methods and attributes is very clearly defined: they all start
111	with a lowercase letter (except if they start with an acronym), and are using
112	CamelCase style otherwise. This naming only applies to the IDL description,
113	and is modified by the various language bindings (some convert the first
114	character to upper case, some not). See the SDK reference for more details
115	about how to call a method or attribute from a specific programming language.
116	</desc>
117
118	<if target="midl">
119	<cpp line="enum {"/>
120	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
121	<cpp line=" kTypeLibraryMinorVersion = 0"/>
122	<cpp line="};"/>
123	</if>
124
125	<if target="xpidl">
126	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
127	<cpp>
128	/* currently, nsISupportsImpl.h lacks the below-like macros */
129
130	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
131	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
132	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
133	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI
134	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI NS_IMPL_QUERY_INTERFACE5_CI
135	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI NS_IMPL_QUERY_INTERFACE6_CI
136	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI NS_IMPL_QUERY_INTERFACE7_CI
137	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI NS_IMPL_QUERY_INTERFACE8_CI
138
139
140	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
141	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
142	NS_IMPL_THREADSAFE_ADDREF(_class) \
143	NS_IMPL_THREADSAFE_RELEASE(_class) \
144	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
145	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
146	#endif
147
148	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
149	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
150	NS_IMPL_THREADSAFE_ADDREF(_class) \
151	NS_IMPL_THREADSAFE_RELEASE(_class) \
152	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
153	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
154	#endif
155
156	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
157	# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
158	NS_IMPL_THREADSAFE_ADDREF(_class) \
159	NS_IMPL_THREADSAFE_RELEASE(_class) \
160	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
161	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
162	#endif
163
164	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI
165	# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \
166	NS_IMPL_THREADSAFE_ADDREF(_class) \
167	NS_IMPL_THREADSAFE_RELEASE(_class) \
168	NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \
169	NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)
170	#endif
171
172	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS5_CI
173	# define NS_IMPL_THREADSAFE_ISUPPORTS5_CI(_class, _i1, _i2, _i3, _i4, _i5) \
174	NS_IMPL_THREADSAFE_ADDREF(_class) \
175	NS_IMPL_THREADSAFE_RELEASE(_class) \
176	NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI(_class, _i1, _i2, _i3, _i4, _i5) \
177	NS_IMPL_CI_INTERFACE_GETTER5(_class, _i1, _i2, _i3, _i4, _i5)
178	#endif
179
180	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS6_CI
181	# define NS_IMPL_THREADSAFE_ISUPPORTS6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \
182	NS_IMPL_THREADSAFE_ADDREF(_class) \
183	NS_IMPL_THREADSAFE_RELEASE(_class) \
184	NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \
185	NS_IMPL_CI_INTERFACE_GETTER6(_class, _i1, _i2, _i3, _i4, _i5, _i6)
186	#endif
187
188	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS7_CI
189	# define NS_IMPL_THREADSAFE_ISUPPORTS7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \
190	NS_IMPL_THREADSAFE_ADDREF(_class) \
191	NS_IMPL_THREADSAFE_RELEASE(_class) \
192	NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \
193	NS_IMPL_CI_INTERFACE_GETTER7(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7)
194	#endif
195
196	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS8_CI
197	# define NS_IMPL_THREADSAFE_ISUPPORTS8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \
198	NS_IMPL_THREADSAFE_ADDREF(_class) \
199	NS_IMPL_THREADSAFE_RELEASE(_class) \
200	NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \
201	NS_IMPL_CI_INTERFACE_GETTER8(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8)
202	#endif
203
204	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
205	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
206	NS_INTERFACE_MAP_BEGIN(_class) \
207	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
208	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
209	NS_IMPL_QUERY_CLASSINFO(_class) \
210	NS_INTERFACE_MAP_END
211	#endif
212
213	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
214	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
215	_i2, _ic2) \
216	NS_INTERFACE_MAP_BEGIN(_class) \
217	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
218	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
219	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
220	NS_IMPL_QUERY_CLASSINFO(_class) \
221	NS_INTERFACE_MAP_END
222	#endif
223
224	#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
225	# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
226	_i2, _ic2, _i3, _ic3) \
227	NS_INTERFACE_MAP_BEGIN(_class) \
228	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
229	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
230	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
231	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
232	NS_IMPL_QUERY_CLASSINFO(_class) \
233	NS_INTERFACE_MAP_END
234	#endif
235
236	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
237	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
238	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
239
240	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
241	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
242	NS_IMPL_THREADSAFE_ADDREF(_class) \
243	NS_IMPL_THREADSAFE_RELEASE(_class) \
244	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
245	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
246	#endif
247
248	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
249	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
250	_i2, _ic2) \
251	NS_IMPL_THREADSAFE_ADDREF(_class) \
252	NS_IMPL_THREADSAFE_RELEASE(_class) \
253	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
254	_i2, _ic2) \
255	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
256	#endif
257
258	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
259	# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
260	_i2, _ic2, _i3, _ic3) \
261	NS_IMPL_THREADSAFE_ADDREF(_class) \
262	NS_IMPL_THREADSAFE_RELEASE(_class) \
263	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
264	_i2, _ic2, _i3, _ic3) \
265	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
266	#endif
267
268	</cpp>
269	</if>
270
271	<library
272	name="VirtualBox"
273	uuid="d7569351-1750-46f0-936e-bd127d5bc264"
274	version="1.3"
275	desc="VirtualBox Type Library"
276	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
277	supportsErrorInfo="yes"
278	>
279
280
281	<!--
282	// COM result codes for VirtualBox
283	/////////////////////////////////////////////////////////////////////////
284	-->
285
286	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
287	<desc>
288	This section describes all VirtualBox-specific COM result codes that may
289	be returned by methods of VirtualBox COM interfaces in addition to
290	standard COM result codes.
291
292	Note that along with the result code, every VirtualBox method returns
293	extended error information through the IVirtualBoxErrorInfo interface on
294	failure. This interface is a preferred way to present the error to the end
295	user because it contains a human readable description of the error. Raw
296	result codes, both standard and described in this section, are intended to
297	be used by programs to analyze the reason of a failure and select an
298	appropriate course of action without involving the end user (for example,
299	retry the operation later or make a different call).
300
301	The standard COM result codes that may originate from our methods include:
302
303	<table>
304	<tr><td>E_INVALIDARG</td>
305	<td>
306	Returned when the value of the method's argument is not within the range
307	of valid values. This should not be confused with situations when the
308	value is within the range but simply doesn't suit the current object
309	state and there is a possibility that it will be accepted later (in such
310	cases VirtualBox-specific codes are returned, for example,
311	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
312	</td>
313	</tr>
314	<tr><td>E_POINTER</td>
315	<td>
316	Returned if a memory pointer for the output argument is invalid (for
317	example, @c null). When pointers representing input arguments (such
318	as strings) are invalid, E_INVALIDARG is returned.
319	</td>
320	</tr>
321	<tr><td>E_ACCESSDENIED</td>
322	<td>
323	Returned when the called object is not ready. Since the lifetime of a
324	public COM object cannot be fully controlled by the implementation,
325	VirtualBox maintains the readiness state for all objects it creates and
326	returns this code in response to any method call on the object that was
327	deactivated by VirtualBox and is not functioning any more.
328	</td>
329	</tr>
330	<tr><td>E_OUTOFMEMORY</td>
331	<td>
332	Returned when a memory allocation operation fails.
333	</td>
334	</tr>
335	</table>
336	</desc>
337	</descGroup>
338
339	<!--
340	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
341	everything in <result>/<desc> after (and including) the first dot, so express
342	the matter of the error code in the first sentence and keep it short.
343	-->
344
345	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
346	<desc>
347	Object corresponding to the supplied arguments does not exist.
348	</desc>
349	</result>
350
351	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
352	<desc>
353	Current virtual machine state prevents the operation.
354	</desc>
355	</result>
356
357	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
358	<desc>
359	Virtual machine error occurred attempting the operation.
360	</desc>
361	</result>
362
363	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
364	<desc>
365	File not accessible or erroneous file contents.
366	</desc>
367	</result>
368
369	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
370	<desc>
371	Runtime subsystem error.
372	</desc>
373	</result>
374
375	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
376	<desc>
377	Pluggable Device Manager error.
378	</desc>
379	</result>
380
381	<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
382	<desc>
383	Current object state prohibits operation.
384	</desc>
385	</result>
386
387	<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
388	<desc>
389	Host operating system related error.
390	</desc>
391	</result>
392
393	<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
394	<desc>
395	Requested operation is not supported.
396	</desc>
397	</result>
398
399	<result name="VBOX_E_XML_ERROR" value="0x80BB000A">
400	<desc>
401	Invalid XML found.
402	</desc>
403	</result>
404
405	<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
406	<desc>
407	Current session state prohibits operation.
408	</desc>
409	</result>
410
411	<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
412	<desc>
413	Object being in use prohibits operation.
414	</desc>
415	</result>
416
417	<!--
418	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
419	everything in <result>/<desc> after (and including) the first dot, so express
420	the matter of the error code in the first sentence and keep it short.
421	-->
422
423	<descGroup/>
424
425	<!--
426	// all common enums
427	/////////////////////////////////////////////////////////////////////////
428	-->
429
430	<enum
431	name="SettingsVersion"
432	uuid="d5b15ca7-3de7-46b2-a63a-ddcce42bfa3f"
433	>
434	<desc>
435	Settings version of VirtualBox settings files. This is written to
436	the "version" attribute of the root "VirtualBox" element in the settings
437	file XML and indicates which VirtualBox version wrote the file.
438	</desc>
439
440	<const name="Null" value="0">
441	<desc>Null value, indicates invalid version.</desc>
442	</const>
443	<const name="v1_0" value="1">
444	<desc>Legacy settings version, not currently supported.</desc>
445	</const>
446	<const name="v1_1" value="2">
447	<desc>Legacy settings version, not currently supported.</desc>
448	</const>
449	<const name="v1_2" value="3">
450	<desc>Legacy settings version, not currently supported.</desc>
451	</const>
452	<const name="v1_3pre" value="4">
453	<desc>Legacy settings version, not currently supported.</desc>
454	</const>
455	<const name="v1_3" value="5">
456	<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
457	<!--
458	Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
459	-->
460	</const>
461	<const name="v1_4" value="6">
462	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
463	<!--
464	VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
465	(was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
466	-->
467	</const>
468	<const name="v1_5" value="7">
469	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
470	<!--
471	2008-09-04: 2.0.0 released
472	2008-11-20: settings version 1.5 introduced
473	2008-12-17: 2.1.0 released
474	Machine changes:
475	guest OS identifiers changed;
476	Machine/Hardware/Display/MonitorCount renamed to monitorCount;
477	Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
478	Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
479	-->
480	</const>
481	<const name="v1_6" value="8">
482	<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
483	<!--
484	2008-12-17: 2.1.0 released
485	2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
486	2009-04-08: 2.2.0 released
487	Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
488	-->
489	</const>
490	<const name="v1_7" value="9">
491	<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
492	<!--
493	2008-12-17: 2.1.0 released
494	2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
495	2009-04-08: 2.2.0 released
496	VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
497	Machine changes: HardDiskAttachments is now StorageControllers (done)
498	-->
499	</const>
500	<const name="v1_8" value="10">
501	<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
502	<!--
503	Machine additions: Display/@accelerate2DVideo (done)
504	-->
505	</const>
506	<const name="v1_9" value="11">
507	<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
508	<!--
509	The big storage controller / DVD / Floppy rework (done)
510	-->
511	</const>
512	<const name="v1_10" value="12">
513	<desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
514	<!--
515	Machine changes: RTC localOrUTC (done)
516	CPU hot-plug support
517	-->
518	</const>
519	<const name="v1_11" value="13">
520	<desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc>
521	<!--
522	Machine changes: HD Audio controller, per-machine disk registries,
523	/@format attribute for DVD and floppy images.
524	-->
525	</const>
526	<const name="v1_12" value="14">
527	<desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc>
528	<!--
529	Machine changes: raw PCI device attachment;
530	NetworkAdapter changes: bandwidth group.
531	-->
532	</const>
533	<const name="v1_13" value="15">
534	<desc>Settings version "1.13", written by VirtualBox 4.2.x.</desc>
535	<!--
536	Machine changes: tracing config, groups, autostart;
537	NetworkAdapter changes: unit for bandwidth group limits.
538	-->
539	</const>
540	<const name="v1_14" value="16">
541	<desc>Settings version "1.14", written by VirtualBox 4.3.x.</desc>
542	<!--
543	Machine changes: default frontend.
544	-->
545	</const>
546
547	<const name="Future" value="99999">
548	<desc>Settings version greater than "1.13", written by a future VirtualBox version.</desc>
549	</const>
550	</enum>
551
552	<enum
553	name="AccessMode"
554	uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
555	>
556	<desc>
557	Access mode for opening files.
558	</desc>
559
560	<const name="ReadOnly" value="1"/>
561	<const name="ReadWrite" value="2"/>
562	</enum>
563
564	<enum
565	name="MachineState"
566	uuid="ec6c6a9e-113d-4ff4-b44f-0b69f21c97fe"
567	>
568	<desc>
569	Virtual machine execution state.
570
571	This enumeration represents possible values of the <link
572	to="IMachine::state"/> attribute.
573
574	Below is the basic virtual machine state diagram. It shows how the state
575	changes during virtual machine execution. The text in square braces shows
576	a method of the IConsole interface that performs the given state
577	transition.
578
579	<pre>
580	+---------[powerDown()] <- Stuck <--[failure]-+
581	V \|
582	+-> PoweredOff --+-->[powerUp()]--> Starting --+ \| +-----[resume()]-----+
583	\| \| \| \| V \|
584	\| Aborted -----+ +--> Running --[pause()]--> Paused
585	\| \| ^ \| ^ \|
586	\| Saved -----------[powerUp()]--> Restoring -+ \| \| \| \|
587	\| ^ \| \| \| \|
588	\| \| +-----------------------------------------+-\|-------------------+ +
589	\| \| \| \| \|
590	\| \| +-- Saving <--------[takeSnapshot()]<-------+---------------------+
591	\| \| \| \|
592	\| +-------- Saving <--------[saveState()]<----------+---------------------+
593	\| \| \|
594	+-------------- Stopping -------[powerDown()]<----------+---------------------+
595	</pre>
596
597	Note that states to the right from PoweredOff, Aborted and Saved in the
598	above diagram are called <i>online VM states</i>. These states
599	represent the virtual machine which is being executed in a dedicated
600	process (usually with a GUI window attached to it where you can see the
601	activity of the virtual machine and interact with it). There are two
602	special pseudo-states, FirstOnline and LastOnline, that can be used in
603	relational expressions to detect if the given machine state is online or
604	not:
605
606	<pre>
607	if (machine.GetState() >= MachineState_FirstOnline &&
608	machine.GetState() <= MachineState_LastOnline)
609	{
610	...the machine is being executed...
611	}
612	</pre>
613
614	When the virtual machine is in one of the online VM states (that is, being
615	executed), only a few machine settings can be modified. Methods working
616	with such settings contain an explicit note about that. An attempt to
617	change any other setting or perform a modifying operation during this time
618	will result in the @c VBOX_E_INVALID_VM_STATE error.
619
620	All online states except Running, Paused and Stuck are transitional: they
621	represent temporary conditions of the virtual machine that will last as
622	long as the operation that initiated such a condition.
623
624	The Stuck state is a special case. It means that execution of the machine
625	has reached the "Guru Meditation" condition. This condition indicates an
626	internal VMM (virtual machine manager) failure which may happen as a
627	result of either an unhandled low-level virtual hardware exception or one
628	of the recompiler exceptions (such as the <i>too-many-traps</i>
629	condition).
630
631	Note also that any online VM state may transit to the Aborted state. This
632	happens if the process that is executing the virtual machine terminates
633	unexpectedly (for example, crashes). Other than that, the Aborted state is
634	equivalent to PoweredOff.
635
636	There are also a few additional state diagrams that do not deal with
637	virtual machine execution and therefore are shown separately. The states
638	shown on these diagrams are called <i>offline VM states</i> (this includes
639	PoweredOff, Aborted and Saved too).
640
641	The first diagram shows what happens when a lengthy setup operation is
642	being executed (such as <link to="IMachine::attachDevice"/>).
643
644	<pre>
645	+----------------------------------(same state as before the call)------+
646	\| \|
647	+-> PoweredOff --+ \|
648	\| \| \|
649	\|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
650	\| \|
651	+-> Saved -------+
652	</pre>
653
654	The next two diagrams demonstrate the process of taking a snapshot of a
655	powered off virtual machine, restoring the state to that as of a snapshot
656	or deleting a snapshot, respectively.
657
658	<pre>
659	+----------------------------------(same state as before the call)------+
660	\| \|
661	+-> PoweredOff --+ \|
662	\| +-->[takeSnapshot()] -------------------> Saving ------+
663	+-> Aborted -----+
664
665	+-> PoweredOff --+
666	\| \|
667	\| Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
668	\| \| [deleteSnapshot() ]-------> DeletingSnapshot --+
669	+-> Saved -------+ \|
670	\| \|
671	+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
672	</pre>
673
674	Note that the Saving state is present in both the offline state group and
675	online state group. Currently, the only way to determine what group is
676	assumed in a particular case is to remember the previous machine state: if
677	it was Running or Paused, then Saving is an online state, otherwise it is
678	an offline state. This inconsistency may be removed in one of the future
679	versions of VirtualBox by adding a new state.
680
681	<note internal="yes">
682	For whoever decides to touch this enum: In order to keep the
683	comparisons involving FirstOnline and LastOnline pseudo-states valid,
684	the numeric values of these states must be correspondingly updated if
685	needed: for any online VM state, the condition
686	<tt>FirstOnline <= state <= LastOnline</tt> must be
687	@c true. The same relates to transient states for which
688	the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
689	@c true.
690	</note>
691	</desc>
692
693	<const name="Null" value="0">
694	<desc>Null value (never used by the API).</desc>
695	</const>
696	<const name="PoweredOff" value="1">
697	<desc>
698	The machine is not running and has no saved execution state; it has
699	either never been started or been shut down successfully.
700	</desc>
701	</const>
702	<const name="Saved" value="2">
703	<desc>
704	The machine is not currently running, but the execution state of the machine
705	has been saved to an external file when it was running, from where
706	it can be resumed.
707	</desc>
708	</const>
709	<const name="Teleported" value="3">
710	<desc>
711	The machine was teleported to a different host (or process) and then
712	powered off. Take care when powering it on again may corrupt resources
713	it shares with the teleportation target (e.g. disk and network).
714	</desc>
715	</const>
716	<const name="Aborted" value="4">
717	<desc>
718	The process running the machine has terminated abnormally. This may
719	indicate a crash of the VM process in host execution context, or
720	the VM process has been terminated externally.
721	</desc>
722	</const>
723	<const name="Running" value="5">
724	<desc>
725	The machine is currently being executed.
726	<note internal="yes">
727	For whoever decides to touch this enum: In order to keep the
728	comparisons in the old source code valid, this state must immediately
729	precede the Paused state.
730	TODO: Lift this spectacularly wonderful restriction.
731	</note>
732	</desc>
733	</const>
734	<const name="Paused" value="6">
735	<desc>
736	Execution of the machine has been paused.
737	<note internal="yes">
738	For whoever decides to touch this enum: In order to keep the
739	comparisons in the old source code valid, this state must immediately
740	follow the Running state.
741	TODO: Lift this spectacularly wonderful restriction.
742	</note>
743	</desc>
744	</const>
745	<const name="Stuck" value="7">
746	<desc>
747	Execution of the machine has reached the "Guru Meditation"
748	condition. This indicates a severe error in the hypervisor itself.
749	<note internal="yes">
750	bird: Why this uncool name? Could we rename it to "GuruMeditation" or
751	"Guru", perhaps? Or are there some other VMM states that are
752	intended to be lumped in here as well?
753	</note>
754	</desc>
755	</const>
756	<const name="Teleporting" value="8">
757	<desc>
758	The machine is about to be teleported to a different host or process.
759	It is possible to pause a machine in this state, but it will go to the
760	@c TeleportingPausedVM state and it will not be
761	possible to resume it again unless the teleportation fails.
762	</desc>
763	</const>
764	<const name="LiveSnapshotting" value="9">
765	<desc>
766	A live snapshot is being taken. The machine is running normally, but
767	some of the runtime configuration options are inaccessible. Also, if
768	paused while in this state it will transition to
769	@c Saving and it will not be resume the
770	execution until the snapshot operation has completed.
771	</desc>
772	</const>
773	<const name="Starting" value="10">
774	<desc>
775	Machine is being started after powering it on from a
776	zero execution state.
777	</desc>
778	</const>
779	<const name="Stopping" value="11">
780	<desc>
781	Machine is being normally stopped powering it off, or after the guest OS
782	has initiated a shutdown sequence.
783	</desc>
784	</const>
785	<const name="Saving" value="12">
786	<desc>
787	Machine is saving its execution state to a file, or an online
788	snapshot of the machine is being taken.
789	</desc>
790	</const>
791	<const name="Restoring" value="13">
792	<desc>
793	Execution state of the machine is being restored from a file
794	after powering it on from the saved execution state.
795	</desc>
796	</const>
797	<const name="TeleportingPausedVM" value="14">
798	<desc>
799	The machine is being teleported to another host or process, but it is
800	not running. This is the paused variant of the
801	@c state.
802	</desc>
803	</const>
804	<const name="TeleportingIn" value="15">
805	<desc>
806	Teleporting the machine state in from another host or process.
807	</desc>
808	</const>
809	<const name="FaultTolerantSyncing" value="16">
810	<desc>
811	The machine is being synced with a fault tolerant VM running elsewhere.
812	</desc>
813	</const>
814	<const name="DeletingSnapshotOnline" value="17">
815	<desc>
816	Like @c DeletingSnapshot, but the merging of media is ongoing in
817	the background while the machine is running.
818	</desc>
819	</const>
820	<const name="DeletingSnapshotPaused" value="18">
821	<desc>
822	Like @c DeletingSnapshotOnline, but the machine was paused when the
823	merging of differencing media was started.
824	</desc>
825	</const>
826	<const name="RestoringSnapshot" value="19">
827	<desc>
828	A machine snapshot is being restored; this typically does not take long.
829	</desc>
830	</const>
831	<const name="DeletingSnapshot" value="20">
832	<desc>
833	A machine snapshot is being deleted; this can take a long time since this
834	may require merging differencing media. This value indicates that the
835	machine is not running while the snapshot is being deleted.
836	</desc>
837	</const>
838	<const name="SettingUp" value="21">
839	<desc>
840	Lengthy setup operation is in progress.
841	</desc>
842	</const>
843
844	<const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
845	<desc>
846	Pseudo-state: first online state (for use in relational expressions).
847	</desc>
848	</const>
849	<const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
850	<desc>
851	Pseudo-state: last online state (for use in relational expressions).
852	</desc>
853	</const>
854
855	<const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
856	<desc>
857	Pseudo-state: first transient state (for use in relational expressions).
858	</desc>
859	</const>
860	<const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp -->
861	<desc>
862	Pseudo-state: last transient state (for use in relational expressions).
863	</desc>
864	</const>
865
866	</enum>
867
868	<enum
869	name="SessionState"
870	uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
871	>
872	<desc>
873	Session state. This enumeration represents possible values of
874	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
875	attributes.
876	</desc>
877
878	<const name="Null" value="0">
879	<desc>Null value (never used by the API).</desc>
880	</const>
881	<const name="Unlocked" value="1">
882	<desc>
883	In <link to="IMachine::sessionState"/>, this means that the machine
884	is not locked for any sessions.
885
886	In <link to="ISession::state"/>, this means that no machine is
887	currently locked for this session.
888	</desc>
889	</const>
890	<const name="Locked" value="2">
891	<desc>
892	In <link to="IMachine::sessionState"/>, this means that the machine
893	is currently locked for a session, whose process identifier can
894	then be found in the <link to="IMachine::sessionPID" /> attribute.
895
896	In <link to="ISession::state"/>, this means that a machine is
897	currently locked for this session, and the mutable machine object
898	can be found in the <link to="ISession::machine"/> attribute
899	(see <link to="IMachine::lockMachine" /> for details).
900	</desc>
901	</const>
902	<const name="Spawning" value="3">
903	<desc>
904	A new process is being spawned for the machine as a result of
905	<link to="IMachine::launchVMProcess"/> call. This state also occurs
906	as a short transient state during an <link to="IMachine::lockMachine"/>
907	call.
908	</desc>
909	</const>
910	<const name="Unlocking" value="4">
911	<desc>
912	The session is being unlocked.
913	</desc>
914	</const>
915	</enum>
916
917	<enum
918	name="CPUPropertyType"
919	uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
920	>
921	<desc>
922	Virtual CPU property type. This enumeration represents possible values of the
923	IMachine get- and setCPUProperty methods.
924	</desc>
925	<const name="Null" value="0">
926	<desc>Null value (never used by the API).</desc>
927	</const>
928	<const name="PAE" value="1">
929	<desc>
930	This setting determines whether VirtualBox will expose the Physical Address
931	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
932	is not available, it will not be reported.
933	</desc>
934	</const>
935	<const name="Synthetic" value="2">
936	<desc>
937	This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
938	teleporting between host systems that differ significantly.
939	</desc>
940	</const>
941	<const name="LongMode" value="3">
942	<desc>
943	This setting determines whether VirtualBox will advertice long mode
944	(i.e. 64-bit guest support) and let the guest enter it.
945	</desc>
946	</const>
947	</enum>
948
949
950	<enum
951	name="HWVirtExPropertyType"
952	uuid="39463ecd-b4b8-401f-b168-76cfa87e11f0"
953	>
954	<desc>
955	Hardware virtualization property type. This enumeration represents possible values
956	for the <link to="IMachine::getHWVirtExProperty"/> and
957	<link to="IMachine::setHWVirtExProperty"/> methods.
958	</desc>
959	<const name="Null" value="0">
960	<desc>Null value (never used by the API).</desc>
961	</const>
962	<const name="Enabled" value="1">
963	<desc>
964	Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
965	such extensions are not available, they will not be used.
966	</desc>
967	</const>
968	<const name="Exclusive" value="2">
969	<desc>
970	Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
971	VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
972	feature of the host. To share these with other hypervisors, you must disable this property.
973	</desc>
974	</const>
975	<const name="VPID" value="3">
976	<desc>
977	Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
978	</desc>
979	</const>
980	<const name="NestedPaging" value="4">
981	<desc>
982	Whether Nested Paging is enabled. If this extension is not available, it will not be used.
983	</desc>
984	</const>
985	<const name="UnrestrictedExecution" value="5">
986	<desc>
987	Whether VT-x unrestricted execution is enabled. If this feature is not available, it will not be used.
988	</desc>
989	</const>
990	<const name="LargePages" value="6">
991	<desc>
992	Whether large page allocation is enabled; requires nested paging and a 64-bit host.
993	</desc>
994	</const>
995	<const name="Force" value="7">
996	<desc>
997	Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If
998	not set, there will be an automatic fallback to software virtualization.
999	</desc>
1000	</const>
1001	</enum>
1002
1003	<enum
1004	name="FaultToleranceState"
1005	uuid="5124f7ec-6b67-493c-9dee-ee45a44114e1"
1006	>
1007	<desc>
1008	Used with <link to="IMachine::faultToleranceState" />.
1009	</desc>
1010	<const name="Inactive" value="1">
1011	<desc>No fault tolerance enabled.</desc>
1012	</const>
1013	<const name="Master" value="2">
1014	<desc>Fault tolerant master VM.</desc>
1015	</const>
1016	<const name="Standby" value="3">
1017	<desc>Fault tolerant standby VM.</desc>
1018	</const>
1019	</enum>
1020
1021	<enum
1022	name="LockType"
1023	uuid="168a6a8e-12fd-4878-a1f9-38a750a56089"
1024	>
1025	<desc>
1026	Used with <link to="IMachine::lockMachine" />.
1027	</desc>
1028	<const name="Write" value="2">
1029	<desc>Lock the machine for writing. This requests an exclusive lock, i.e.
1030	there cannot be any other API client holding any type of lock for this
1031	VM concurrently. Remember that a VM process counts as an API client
1032	which implicitly holds the equivalent of a shared lock during the
1033	entire VM runtime.</desc>
1034	</const>
1035	<const name="Shared" value="1">
1036	<desc>Request only a shared lock for remote-controlling the machine.
1037	Such a lock allows changing certain VM settings which can be safely
1038	modified for a running VM.</desc>
1039	</const>
1040	<const name="VM" value="3">
1041	<desc>Lock the machine for writing, and create objects necessary for
1042	running a VM in this process.</desc>
1043	</const>
1044	</enum>
1045
1046	<enum
1047	name="SessionType"
1048	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
1049	>
1050	<desc>
1051	Session type. This enumeration represents possible values of the
1052	<link to="ISession::type"/> attribute.
1053	</desc>
1054
1055	<const name="Null" value="0">
1056	<desc>Null value (never used by the API).</desc>
1057	</const>
1058	<const name="WriteLock" value="1">
1059	<desc>
1060	Session has acquired an exclusive write lock on a machine
1061	using <link to="IMachine::lockMachine"/>.
1062	</desc>
1063	</const>
1064	<const name="Remote" value="2">
1065	<desc>
1066	Session has launched a VM process using
1067	<link to="IMachine::launchVMProcess"/>
1068	</desc>
1069	</const>
1070	<const name="Shared" value="3">
1071	<desc>
1072	Session has obtained a link to another session using
1073	<link to="IMachine::lockMachine"/>
1074	</desc>
1075	</const>
1076	</enum>
1077
1078	<enum
1079	name="DeviceType"
1080	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
1081	>
1082	<desc>
1083	Device type.
1084	</desc>
1085	<const name="Null" value="0">
1086	<desc>
1087	Null value, may also mean "no device" (not allowed for
1088	<link to="IConsole::getDeviceActivity"/>).
1089	</desc>
1090	</const>
1091	<const name="Floppy" value="1">
1092	<desc>Floppy device.</desc>
1093	</const>
1094	<const name="DVD" value="2">
1095	<desc>CD/DVD-ROM device.</desc>
1096	</const>
1097	<const name="HardDisk" value="3">
1098	<desc>Hard disk device.</desc>
1099	</const>
1100	<const name="Network" value="4">
1101	<desc>Network device.</desc>
1102	</const>
1103	<const name="USB" value="5">
1104	<desc>USB device.</desc>
1105	</const>
1106	<const name="SharedFolder" value="6">
1107	<desc>Shared folder device.</desc>
1108	</const>
1109	</enum>
1110
1111	<enum
1112	name="DeviceActivity"
1113	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
1114	>
1115	<desc>
1116	Device activity for <link to="IConsole::getDeviceActivity"/>.
1117	</desc>
1118
1119	<const name="Null" value="0"/>
1120	<const name="Idle" value="1"/>
1121	<const name="Reading" value="2"/>
1122	<const name="Writing" value="3"/>
1123	</enum>
1124
1125	<enum
1126	name="ClipboardMode"
1127	uuid="33364716-4008-4701-8f14-be0fa3d62950"
1128	>
1129	<desc>
1130	Host-Guest clipboard interchange mode.
1131	</desc>
1132
1133	<const name="Disabled" value="0"/>
1134	<const name="HostToGuest" value="1"/>
1135	<const name="GuestToHost" value="2"/>
1136	<const name="Bidirectional" value="3"/>
1137	</enum>
1138
1139	<enum
1140	name="DragAndDropMode"
1141	uuid="b618ea0e-b6fb-4f8d-97f7-5e237e49b547"
1142	>
1143	<desc>
1144	Drag'n'Drop interchange mode.
1145	</desc>
1146
1147	<const name="Disabled" value="0"/>
1148	<const name="HostToGuest" value="1"/>
1149	<const name="GuestToHost" value="2"/>
1150	<const name="Bidirectional" value="3"/>
1151	</enum>
1152
1153	<enum
1154	name="Scope"
1155	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
1156	>
1157	<desc>
1158	Scope of the operation.
1159
1160	A generic enumeration used in various methods to define the action or
1161	argument scope.
1162	</desc>
1163
1164	<const name="Global" value="0"/>
1165	<const name="Machine" value="1"/>
1166	<const name="Session" value="2"/>
1167	</enum>
1168
1169	<enum
1170	name="BIOSBootMenuMode"
1171	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1172	>
1173	<desc>
1174	BIOS boot menu mode.
1175	</desc>
1176
1177	<const name="Disabled" value="0"/>
1178	<const name="MenuOnly" value="1"/>
1179	<const name="MessageAndMenu" value="2"/>
1180	</enum>
1181
1182	<enum
1183	name="ProcessorFeature"
1184	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1185	>
1186	<desc>
1187	CPU features.
1188	</desc>
1189
1190	<const name="HWVirtEx" value="0"/>
1191	<const name="PAE" value="1"/>
1192	<const name="LongMode" value="2"/>
1193	<const name="NestedPaging" value="3"/>
1194	</enum>
1195
1196	<enum
1197	name="FirmwareType"
1198	uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1199	>
1200	<desc>
1201	Firmware type.
1202	</desc>
1203	<const name="BIOS" value="1">
1204	<desc>BIOS Firmware.</desc>
1205	</const>
1206	<const name="EFI" value="2">
1207	<desc>EFI Firmware, bitness detected basing on OS type.</desc>
1208	</const>
1209	<const name="EFI32" value="3">
1210	<desc>Efi firmware, 32-bit.</desc>
1211	</const>
1212	<const name="EFI64" value="4">
1213	<desc>Efi firmware, 64-bit.</desc>
1214	</const>
1215	<const name="EFIDUAL" value="5">
1216	<desc>Efi firmware, combined 32 and 64-bit.</desc>
1217	</const>
1218	</enum>
1219
1220	<enum
1221	name="PointingHIDType"
1222	uuid="e44b2f7b-72ba-44fb-9e53-2186014f0d17"
1223	>
1224	<desc>
1225	Type of pointing device used in a virtual machine.
1226	</desc>
1227	<const name="None" value="1">
1228	<desc>No mouse.</desc>
1229	</const>
1230	<const name="PS2Mouse" value="2">
1231	<desc>PS/2 auxiliary device, a.k.a. mouse.</desc>
1232	</const>
1233	<const name="USBMouse" value="3">
1234	<desc>USB mouse (relative pointer).</desc>
1235	</const>
1236	<const name="USBTablet" value="4">
1237	<desc>USB tablet (absolute pointer).</desc>
1238	</const>
1239	<const name="ComboMouse" value="5">
1240	<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1241	Using of such device can have negative performance implications. </desc>
1242	</const>
1243	</enum>
1244
1245	<enum
1246	name="KeyboardHIDType"
1247	uuid="383e43d7-5c7c-4ec8-9cb8-eda1bccd6699"
1248	>
1249	<desc>
1250	Type of keyboard device used in a virtual machine.
1251	</desc>
1252	<const name="None" value="1">
1253	<desc>No keyboard.</desc>
1254	</const>
1255	<const name="PS2Keyboard" value="2">
1256	<desc>PS/2 keyboard.</desc>
1257	</const>
1258	<const name="USBKeyboard" value="3">
1259	<desc>USB keyboard.</desc>
1260	</const>
1261	<const name="ComboKeyboard" value="4">
1262	<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1263	Using of such device can have negative performance implications. </desc>
1264	</const>
1265	</enum>
1266
1267	<!--
1268	// IVirtualBoxErrorInfo
1269	/////////////////////////////////////////////////////////////////////////
1270	-->
1271
1272	<interface
1273	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1274	uuid="c1bcc6d5-7966-481d-ab0b-d0ed73e28135"
1275	supportsErrorInfo="no"
1276	wsmap="managed"
1277	>
1278	<desc>
1279	The IVirtualBoxErrorInfo interface represents extended error information.
1280
1281	Extended error information can be set by VirtualBox components after
1282	unsuccessful or partially successful method invocation. This information
1283	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1284	and then shown to the client in addition to the plain 32-bit result code.
1285
1286	In MS COM, this interface extends the IErrorInfo interface,
1287	in XPCOM, it extends the nsIException interface. In both cases,
1288	it provides a set of common attributes to retrieve error
1289	information.
1290
1291	Sometimes invocation of some component's method may involve methods of
1292	other components that may also fail (independently of this method's
1293	failure), or a series of non-fatal errors may precede a fatal error that
1294	causes method failure. In cases like that, it may be desirable to preserve
1295	information about all errors happened during method invocation and deliver
1296	it to the caller. The <link to="#next"/> attribute is intended
1297	specifically for this purpose and allows to represent a chain of errors
1298	through a single IVirtualBoxErrorInfo object set after method invocation.
1299
1300	<note>errors are stored to a chain in the reverse order, i.e. the
1301	initial error object you query right after method invocation is the last
1302	error set by the callee, the object it points to in the @a next attribute
1303	is the previous error and so on, up to the first error (which is the last
1304	in the chain).</note>
1305	</desc>
1306
1307	<attribute name="resultCode" type="long" readonly="yes">
1308	<desc>
1309	Result code of the error.
1310	Usually, it will be the same as the result code returned
1311	by the method that provided this error information, but not
1312	always. For example, on Win32, CoCreateInstance() will most
1313	likely return E_NOINTERFACE upon unsuccessful component
1314	instantiation attempt, but not the value the component factory
1315	returned. Value is typed 'long', not 'result',
1316	to make interface usable from scripting languages.
1317	<note>
1318	In MS COM, there is no equivalent.
1319	In XPCOM, it is the same as nsIException::result.
1320	</note>
1321	</desc>
1322	</attribute>
1323
1324	<attribute name="resultDetail" type="long" readonly="yes">
1325	<desc>
1326	Optional result data of this error. This will vary depending on the
1327	actual error usage. By default this attribute is not being used.
1328	</desc>
1329	</attribute>
1330
1331	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1332	<desc>
1333	UUID of the interface that defined the error.
1334	<note>
1335	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1336	data type.
1337	In XPCOM, there is no equivalent.
1338	</note>
1339	</desc>
1340	</attribute>
1341
1342	<attribute name="component" type="wstring" readonly="yes">
1343	<desc>
1344	Name of the component that generated the error.
1345	<note>
1346	In MS COM, it is the same as IErrorInfo::GetSource.
1347	In XPCOM, there is no equivalent.
1348	</note>
1349	</desc>
1350	</attribute>
1351
1352	<attribute name="text" type="wstring" readonly="yes">
1353	<desc>
1354	Text description of the error.
1355	<note>
1356	In MS COM, it is the same as IErrorInfo::GetDescription.
1357	In XPCOM, it is the same as nsIException::message.
1358	</note>
1359	</desc>
1360	</attribute>
1361
1362	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1363	<desc>
1364	Next error object if there is any, or @c null otherwise.
1365	<note>
1366	In MS COM, there is no equivalent.
1367	In XPCOM, it is the same as nsIException::inner.
1368	</note>
1369	</desc>
1370	</attribute>
1371
1372	</interface>
1373
1374	<!--
1375	// IVirtualBox
1376	/////////////////////////////////////////////////////////////////////////
1377	-->
1378	<!-- This is experimental interface to LWIP based NAT server -->
1379	<interface name="INATNetwork" extends="$unknown"
1380	uuid="03DFD6F7-1B78-48A3-8345-C785281E9523"
1381	wsmap="managed">
1382	<attribute name="NetworkName" type="wstring">
1383	<desc>
1384	TBD: the idea, technically we can start any number of the NAT networks,
1385	but we should expect that at some point we will get collisions because of
1386	port-forwanding rules. so perhaps we should support only single instance of NAT
1387	network.
1388	</desc>
1389	</attribute>
1390	<attribute name="enabled" type="boolean"/>
1391	<attribute name="network" type="wstring">
1392	<desc>
1393	This is CIDR IPv4 string. Specifiying it user defines IPv4 addresses
1394	of gateway (low address + 1) and dhcp server (= low address + 2).
1395	Note: if there're defined IPv4 port-forward rules update of network
1396	will be ignored (because new assignment could break existing rules).
1397	</desc>
1398	</attribute>
1399	<attribute name="gateway" type="wstring" readonly="yes">
1400	<desc>
1401	This attribute is read-only. It's recalculated on changing
1402	network attribute (low address of network + 1).
1403	</desc>
1404	</attribute>
1405	<attribute name="IPv6Enabled" type="boolean">
1406	<desc>
1407	This attribute define whether gateway will support IPv6 or not.
1408	</desc>
1409	</attribute>
1410	<attribute name="IPv6Prefix" type="wstring">
1411	<desc>
1412	This a CIDR IPv6 defining prefix for link-local addresses autoconfiguration within network. Note: ignored if attribute ipv6enabled is false.
1413	</desc>
1414	</attribute>
1415	<attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean"/>
1416	<attribute name="needDhcpServer" type="boolean"/>
1417	<attribute name="eventSource" type="IEventSource" readonly="yes"/>
1418	<attribute name="portForwardRules4" type="wstring" readonly="yes" safearray="yes">
1419	<desc>Array of NAT port-forwarding rules in string representation,
1420	in the following format:
1421	"name:protocolid:[host ip]:host port:[guest ip]:guest port".
1422	</desc>
1423	</attribute>
1424	<attribute name="portForwardRules6" type="wstring" readonly="yes" safearray="yes">
1425	<desc>Array of NAT port-forwarding rules in string representation, in the
1426	following format: "name:protocolid:[host ip]:host port:[guest ip]:guest port".
1427	</desc>
1428	</attribute>
1429	<method name="addPortForwardRule">
1430	<param name="isIpv6" type="boolean" dir="in"/>
1431	<param name="ruleName" type="wstring" dir="in"/>
1432	<param name="proto" type="NATProtocol" dir="in">
1433	<desc>Protocol handled with the rule.</desc>
1434	</param>
1435	<param name="hostIP" type="wstring" dir="in">
1436	<desc>IP of the host interface to which the rule should apply.
1437	An empty ip address is acceptable, in which case the NAT engine
1438	binds the handling socket to any interface.
1439	</desc>
1440	</param>
1441	<param name="hostPort" type="unsigned short" dir="in">
1442	<desc>The port number to listen on.</desc>
1443	</param>
1444	<param name="guestIP" type="wstring" dir="in">
1445	<desc>The IP address of the guest which the NAT engine will forward
1446	matching packets to. An empty IP address is not acceptable.</desc>
1447	</param>
1448	<param name="guestPort" type="unsigned short" dir="in">
1449	<desc>The port number to forward.</desc>
1450	</param>
1451	</method>
1452	<method name="removePortForwardRule">
1453	<param name="iSipv6" type="boolean" dir="in"/>
1454	<param name="ruleName" type="wstring" dir="in"/>
1455	</method>
1456	<method name="start">
1457	<param name="trunkType" type="wstring" dir="in">
1458	<desc>
1459	Type of internal network trunk.
1460	</desc>
1461	</param>
1462	</method>
1463	<method name="stop"/>
1464	</interface>
1465
1466	<interface
1467	name="IDHCPServer" extends="$unknown"
1468	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1469	wsmap="managed"
1470	>
1471	<desc>
1472	The IDHCPServer interface represents the vbox DHCP server configuration.
1473
1474	To enumerate all the DHCP servers on the host, use the
1475	<link to="IVirtualBox::DHCPServers"/> attribute.
1476	</desc>
1477
1478	<attribute name="enabled" type="boolean">
1479	<desc>
1480	specifies if the DHCP server is enabled
1481	</desc>
1482	</attribute>
1483
1484	<attribute name="IPAddress" type="wstring" readonly="yes">
1485	<desc>
1486	specifies server IP
1487	</desc>
1488	</attribute>
1489
1490	<attribute name="networkMask" type="wstring" readonly="yes">
1491	<desc>
1492	specifies server network mask
1493	</desc>
1494	</attribute>
1495
1496	<attribute name="networkName" type="wstring" readonly="yes">
1497	<desc>
1498	specifies internal network name the server is used for
1499	</desc>
1500	</attribute>
1501
1502	<attribute name="lowerIP" type="wstring" readonly="yes">
1503	<desc>
1504	specifies from IP address in server address range
1505	</desc>
1506	</attribute>
1507
1508	<attribute name="upperIP" type="wstring" readonly="yes">
1509	<desc>
1510	specifies to IP address in server address range
1511	</desc>
1512	</attribute>
1513
1514	<method name="setConfiguration">
1515	<desc>
1516	configures the server
1517	<result name="E_INVALIDARG">
1518	invalid configuration supplied
1519	</result>
1520	</desc>
1521	<param name="IPAddress" type="wstring" dir="in">
1522	<desc>
1523	server IP address
1524	</desc>
1525	</param>
1526	<param name="networkMask" type="wstring" dir="in">
1527	<desc>
1528	server network mask
1529	</desc>
1530	</param>
1531	<param name="FromIPAddress" type="wstring" dir="in">
1532	<desc>
1533	server From IP address for address range
1534	</desc>
1535	</param>
1536	<param name="ToIPAddress" type="wstring" dir="in">
1537	<desc>
1538	server To IP address for address range
1539	</desc>
1540	</param>
1541	</method>
1542
1543	<method name="start">
1544	<desc>
1545	Starts DHCP server process.
1546	<result name="E_FAIL">
1547	Failed to start the process.
1548	</result>
1549	</desc>
1550	<param name="networkName" type="wstring" dir="in">
1551	<desc>
1552	Name of internal network DHCP server should attach to.
1553	</desc>
1554	</param>
1555	<param name="trunkName" type="wstring" dir="in">
1556	<desc>
1557	Name of internal network trunk.
1558	</desc>
1559	</param>
1560	<param name="trunkType" type="wstring" dir="in">
1561	<desc>
1562	Type of internal network trunk.
1563	</desc>
1564	</param>
1565	</method>
1566
1567	<method name="stop">
1568	<desc>
1569	Stops DHCP server process.
1570	<result name="E_FAIL">
1571	Failed to stop the process.
1572	</result>
1573	</desc>
1574	</method>
1575	</interface>
1576
1577	<interface
1578	name="IVirtualBox" extends="$unknown"
1579	uuid="fafa4e17-1ee2-4905-a10e-fe7c18bf5554"
1580	wsmap="managed"
1581	>
1582	<desc>
1583	The IVirtualBox interface represents the main interface exposed by the
1584	product that provides virtual machine management.
1585
1586	An instance of IVirtualBox is required for the product to do anything
1587	useful. Even though the interface does not expose this, internally,
1588	IVirtualBox is implemented as a singleton and actually lives in the
1589	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1590	IVirtualBox can track the state of all virtual machines on a particular
1591	host, regardless of which frontend started them.
1592
1593	To enumerate all the virtual machines on the host, use the
1594	<link to="IVirtualBox::machines"/> attribute.
1595	</desc>
1596
1597	<attribute name="version" type="wstring" readonly="yes">
1598	<desc>
1599	A string representing the version number of the product. The
1600	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1601	last number represents the build number and will frequently change.
1602
1603	This may be followed by a _ALPHA[0-9], _BETA[0-9] or _RC[0-9]* tag
1604	in prerelease builds. Non-Oracle builds may (/shall) also have a
1605	publisher tag, at the end. The publisher tag starts with an underscore
1606	just like the prerelease build type tag.
1607	</desc>
1608	</attribute>
1609
1610	<attribute name="versionNormalized" type="wstring" readonly="yes">
1611	<desc>
1612	A string representing the version number of the product,
1613	without the publisher information (but still with other tags).
1614	See <link to="#version" />.
1615	</desc>
1616	</attribute>
1617
1618	<attribute name="revision" type="unsigned long" readonly="yes">
1619	<desc>
1620	The internal build revision number of the product.
1621	</desc>
1622	</attribute>
1623
1624	<attribute name="packageType" type="wstring" readonly="yes">
1625	<desc>
1626	A string representing the package type of this product. The
1627	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1628	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1629	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1630	this.
1631	</desc>
1632	</attribute>
1633
1634	<attribute name="APIVersion" type="wstring" readonly="yes">
1635	<desc>
1636	A string representing the VirtualBox API version number. The format is
1637	2 integer numbers divided by an underscore (e.g. 1_0). After the
1638	first public release of packages with a particular API version the
1639	API will not be changed in an incompatible way. Note that this
1640	guarantee does not apply to development builds, and also there is no
1641	guarantee that this version is identical to the first two integer
1642	numbers of the package version.
1643	</desc>
1644	</attribute>
1645
1646	<attribute name="homeFolder" type="wstring" readonly="yes">
1647	<desc>
1648	Full path to the directory where the global settings file,
1649	<tt>VirtualBox.xml</tt>, is stored.
1650
1651	In this version of VirtualBox, the value of this property is
1652	always <tt><user_dir>/.VirtualBox</tt> (where
1653	<tt><user_dir></tt> is the path to the user directory,
1654	as determined by the host OS), and cannot be changed.
1655
1656	This path is also used as the base to resolve relative paths in
1657	places where relative paths are allowed (unless otherwise
1658	expressly indicated).
1659	</desc>
1660	</attribute>
1661
1662	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1663	<desc>
1664	Full name of the global settings file.
1665	The value of this property corresponds to the value of
1666	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1667	</desc>
1668	</attribute>
1669
1670	<attribute name="host" type="IHost" readonly="yes">
1671	<desc>Associated host object.</desc>
1672	</attribute>
1673
1674	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1675	<desc>Associated system information object.</desc>
1676	</attribute>
1677
1678	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1679	<desc>
1680	Array of machine objects registered within this VirtualBox instance.
1681	</desc>
1682	</attribute>
1683
1684	<attribute name="machineGroups" type="wstring" readonly="yes" safearray="yes">
1685	<desc>
1686	Array of all machine group names which are used by the machines which
1687	are accessible. Each group is only listed once, however they are listed
1688	in no particular order and there is no guarantee that there are no gaps
1689	in the group hierarchy (i.e. <tt>"/"</tt>, <tt>"/group/subgroup"</tt>
1690	is a valid result).
1691	</desc>
1692	</attribute>
1693
1694	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1695	<desc>
1696	Array of medium objects known to this VirtualBox installation.
1697
1698	This array contains only base media. All differencing
1699	media of the given base medium can be enumerated using
1700	<link to="IMedium::children"/>.
1701	</desc>
1702	</attribute>
1703
1704	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1705	<desc>
1706	Array of CD/DVD image objects currently in use by this VirtualBox instance.
1707	</desc>
1708	</attribute>
1709
1710	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1711	<desc>
1712	Array of floppy image objects currently in use by this VirtualBox instance.
1713	</desc>
1714	</attribute>
1715
1716	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1717
1718	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1719
1720	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1721	<desc>
1722	Collection of global shared folders. Global shared folders are
1723	available to all virtual machines.
1724
1725	New shared folders are added to the collection using
1726	<link to="#createSharedFolder"/>. Existing shared folders can be
1727	removed using <link to="#removeSharedFolder"/>.
1728
1729	<note>
1730	In the current version of the product, global shared folders are not
1731	implemented and therefore this collection is always empty.
1732	</note>
1733	</desc>
1734	</attribute>
1735
1736	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1737	<desc>
1738	Associated performance collector object.
1739	</desc>
1740	</attribute>
1741
1742	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1743	<desc>
1744	DHCP servers.
1745	</desc>
1746	</attribute>
1747	<!-- Array of NAT networks -->
1748	<attribute name="NATNetworks" type="INATNetwork" safearray="yes" readonly="yes"/>
1749
1750	<attribute name="eventSource" type="IEventSource" readonly="yes">
1751	<desc>
1752	Event source for VirtualBox events.
1753	</desc>
1754	</attribute>
1755
1756	<attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">
1757	<desc>
1758	The extension pack manager.
1759	</desc>
1760	</attribute>
1761
1762
1763	<attribute name="internalNetworks" type="wstring" safearray="yes" readonly="yes">
1764	<desc>
1765	Names of all internal networks.
1766	</desc>
1767	</attribute>
1768
1769	<attribute name="genericNetworkDrivers" type="wstring" safearray="yes" readonly="yes">
1770	<desc>
1771	Names of all generic network drivers.
1772	</desc>
1773	</attribute>
1774
1775	<method name="composeMachineFilename">
1776	<desc>
1777	Returns a recommended full path of the settings file name for a new virtual
1778	machine.
1779
1780	This API serves two purposes:
1781
1782	<ul>
1783	<li>It gets called by <link to="#createMachine" /> if @c null or
1784	empty string (which is recommended) is specified for the
1785	@a settingsFile argument there, which means that API should use
1786	a recommended default file name.</li>
1787
1788	<li>It can be called manually by a client software before creating a machine,
1789	e.g. if that client wants to pre-create the machine directory to create
1790	virtual hard disks in that directory together with the new machine
1791	settings file. In that case, the file name should be stripped from the
1792	full settings file path returned by this function to obtain the
1793	machine directory.</li>
1794	</ul>
1795
1796	See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
1797	details about the machine name.
1798
1799	@a groupName defines which additional subdirectory levels should be
1800	included. It must be either a valid group name or @c null or empty
1801	string which designates that the machine will not be related to a
1802	machine group.
1803
1804	If @a baseFolder is a @c null or empty string (which is recommended), the
1805	default machine settings folder
1806	(see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
1807	a base folder for the created machine, resulting in a file name like
1808	"/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
1809	will be used.
1810
1811	This method does not access the host disks. In particular, it does not check
1812	for whether a machine with this name already exists.
1813	</desc>
1814	<param name="name" type="wstring" dir="in">
1815	<desc>Suggested machine name.</desc>
1816	</param>
1817	<param name="group" type="wstring" dir="in">
1818	<desc>Machine group name for the new machine or machine group. It is
1819	used to determine the right subdirectory.</desc>
1820	</param>
1821	<param name="createFlags" type="wstring" dir="in">
1822	<desc>Machine creation flags, see <link to="#createMachine" /> (optional).</desc>
1823	</param>
1824	<param name="baseFolder" type="wstring" dir="in">
1825	<desc>Base machine folder (optional).</desc>
1826	</param>
1827	<param name="file" type="wstring" dir="return">
1828	<desc>Fully qualified path where the machine would be created.</desc>
1829	</param>
1830	</method>
1831
1832	<method name="createMachine">
1833	<desc>
1834	Creates a new virtual machine by creating a machine settings file at
1835	the given location.
1836
1837	VirtualBox machine settings files use a custom XML dialect. Starting
1838	with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
1839	and machine files can be created at arbitrary locations.
1840
1841	However, it is recommended that machines are created in the default
1842	machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
1843	<link to="ISystemProperties::defaultMachineFolder" />). If you specify
1844	@c null or empty string (which is recommended) for the @a settingsFile
1845	argument, <link to="#composeMachineFilename" /> is called automatically
1846	to have such a recommended name composed based on the machine name
1847	given in the @a name argument and the primary group.
1848
1849	If the resulting settings file already exists, this method will fail,
1850	unless the forceOverwrite flag is set.
1851
1852	The new machine is created unregistered, with the initial configuration
1853	set according to the specified guest OS type. A typical sequence of
1854	actions to create a new virtual machine is as follows:
1855
1856	<ol>
1857	<li>
1858	Call this method to have a new machine created. The returned machine
1859	object will be "mutable" allowing to change any machine property.
1860	</li>
1861
1862	<li>
1863	Configure the machine using the appropriate attributes and methods.
1864	</li>
1865
1866	<li>
1867	Call <link to="IMachine::saveSettings" /> to write the settings
1868	to the machine's XML settings file. The configuration of the newly
1869	created machine will not be saved to disk until this method is
1870	called.
1871	</li>
1872
1873	<li>
1874	Call <link to="#registerMachine" /> to add the machine to the list
1875	of machines known to VirtualBox.
1876	</li>
1877	</ol>
1878
1879	The specified guest OS type identifier must match an ID of one of known
1880	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1881	array.
1882
1883	<note>
1884	There is no way to change the name of the settings file or
1885	subfolder of the created machine directly.
1886	</note>
1887
1888	<result name="VBOX_E_OBJECT_NOT_FOUND">
1889	@a osTypeId is invalid.
1890	</result>
1891	<result name="VBOX_E_FILE_ERROR">
1892	Resulting settings file name is invalid or the settings file already
1893	exists or could not be created due to an I/O error.
1894	</result>
1895	<result name="E_INVALIDARG">
1896	@a name is empty or @c null.
1897	</result>
1898	</desc>
1899
1900	<param name="settingsFile" type="wstring" dir="in">
1901	<desc>Fully qualified path where the settings file should be created,
1902	empty string or @c null for a default folder and file based on the
1903	@a name argument and the primary group.
1904	(see <link to="#composeMachineFilename" />).</desc>
1905	</param>
1906	<param name="name" type="wstring" dir="in">
1907	<desc>Machine name.</desc>
1908	</param>
1909	<param name="groups" type="wstring" safearray="yes" dir="in">
1910	<desc>Array of group names. @c null or an empty array have the same
1911	meaning as an array with just the empty string or <tt>"/"</tt>, i.e.
1912	create a machine without group association.</desc>
1913	</param>
1914	<param name="osTypeId" type="wstring" dir="in">
1915	<desc>Guest OS Type ID.</desc>
1916	</param>
1917	<param name="flags" type="wstring" dir="in">
1918	<desc>
1919	Additional property parameters, passed as a comma-separated list of
1920	"name=value" type entries. The following ones are recognized:
1921	<tt>forceOverwrite=1</tt> to overwrite an existing machine settings
1922	file, <tt>UUID=<uuid></tt> to specify a machine UUID and
1923	<tt>directoryIncludesUUID=1</tt> to switch to a special VM directory
1924	naming scheme which should not be used unless necessary.
1925	</desc>
1926	</param>
1927	<param name="machine" type="IMachine" dir="return">
1928	<desc>Created machine object.</desc>
1929	</param>
1930	</method>
1931
1932	<method name="openMachine">
1933	<desc>
1934	Opens a virtual machine from the existing settings file.
1935	The opened machine remains unregistered until you call
1936	<link to="#registerMachine"/>.
1937
1938	The specified settings file name must be fully qualified.
1939	The file must exist and be a valid machine XML settings file
1940	whose contents will be used to construct the machine object.
1941
1942	<result name="VBOX_E_FILE_ERROR">
1943	Settings file name invalid, not found or sharing violation.
1944	</result>
1945	</desc>
1946	<param name="settingsFile" type="wstring" dir="in">
1947	<desc>
1948	Name of the machine settings file.
1949	</desc>
1950	</param>
1951	<param name="machine" type="IMachine" dir="return">
1952	<desc>Opened machine object.</desc>
1953	</param>
1954	<note>
1955	<link to="IMachine::settingsModified"/> will return
1956	@c false for the created machine, until any of machine settings
1957	are changed.
1958	</note>
1959	</method>
1960
1961	<method name="registerMachine">
1962	<desc>
1963
1964	Registers the machine previously created using
1965	<link to="#createMachine"/> or opened using
1966	<link to="#openMachine"/> within this VirtualBox installation. After
1967	successful method invocation, the
1968	<link to="IMachineRegisteredEvent"/> event is fired.
1969
1970	<note>
1971	This method implicitly calls <link to="IMachine::saveSettings"/>
1972	to save all current machine settings before registering it.
1973	</note>
1974
1975	<result name="VBOX_E_OBJECT_NOT_FOUND">
1976	No matching virtual machine found.
1977	</result>
1978	<result name="VBOX_E_INVALID_OBJECT_STATE">
1979	Virtual machine was not created within this VirtualBox instance.
1980	</result>
1981
1982	</desc>
1983	<param name="machine" type="IMachine" dir="in"/>
1984	</method>
1985
1986	<method name="findMachine">
1987	<desc>
1988	Attempts to find a virtual machine given its name or UUID.
1989
1990	<note>Inaccessible machines cannot be found by name, only by UUID, because their name
1991	cannot safely be determined.</note>
1992
1993	<result name="VBOX_E_OBJECT_NOT_FOUND">
1994	Could not find registered machine matching @a nameOrId.
1995	</result>
1996
1997	</desc>
1998	<param name="nameOrId" type="wstring" dir="in">
1999	<desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>
2000	</param>
2001	<param name="machine" type="IMachine" dir="return">
2002	<desc>Machine object, if found.</desc>
2003	</param>
2004	</method>
2005
2006	<method name="getMachinesByGroups">
2007	<desc>
2008	Gets all machine references which are in one of the specified groups.
2009	</desc>
2010	<param name="groups" type="wstring" dir="in" safearray="yes">
2011	<desc>What groups to match. The usual group list rules apply, i.e.
2012	passing an empty list will match VMs in the toplevel group, likewise
2013	the empty string.</desc>
2014	</param>
2015	<param name="machines" type="IMachine" dir="return" safearray="yes">
2016	<desc>All machines which matched.</desc>
2017	</param>
2018	</method>
2019
2020	<method name="getMachineStates">
2021	<desc>
2022	Gets the state of several machines in a single operation.
2023	</desc>
2024	<param name="machines" type="IMachine" dir="in" safearray="yes">
2025	<desc>Array with the machine references.</desc>
2026	</param>
2027	<param name="states" type="MachineState" dir="return" safearray="yes">
2028	<desc>Machine states, corresponding to the machines.</desc>
2029	</param>
2030	</method>
2031
2032	<method name="createAppliance">
2033	<desc>
2034	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
2035	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
2036	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
2037	</desc>
2038	<param name="appliance" type="IAppliance" dir="return">
2039	<desc>New appliance.</desc>
2040	</param>
2041	</method>
2042
2043	<method name="createHardDisk">
2044	<desc>
2045	Creates a new base medium object that will use the given storage
2046	format and location for medium data.
2047
2048	The actual storage unit is not created by this method. In order to
2049	do it, and before you are able to attach the created medium to
2050	virtual machines, you must call one of the following methods to
2051	allocate a format-specific storage unit at the specified location:
2052	<ul>
2053	<li><link to="IMedium::createBaseStorage"/></li>
2054	<li><link to="IMedium::createDiffStorage"/></li>
2055	</ul>
2056
2057	Some medium attributes, such as <link to="IMedium::id"/>, may
2058	remain uninitialized until the medium storage unit is successfully
2059	created by one of the above methods.
2060
2061	After the storage unit is successfully created, it will be
2062	accessible through the <link to="#openMedium"/> method and can
2063	be found in the <link to="#hardDisks"/> array.
2064
2065	The list of all storage formats supported by this VirtualBox
2066	installation can be obtained using
2067	<link to="ISystemProperties::mediumFormats"/>. If the @a format
2068	attribute is empty or @c null then the default storage format
2069	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
2070	be used for creating a storage unit of the medium.
2071
2072	Note that the format of the location string is storage format specific.
2073	See <link to="IMedium::location"/> and IMedium for more details.
2074
2075	<result name="VBOX_E_OBJECT_NOT_FOUND">
2076	@a format identifier is invalid. See
2077	<link to="ISystemProperties::mediumFormats"/>.
2078	</result>
2079	<result name="VBOX_E_FILE_ERROR">
2080	@a location is a not valid file name (for file-based formats only).
2081	</result>
2082	</desc>
2083	<param name="format" type="wstring" dir="in">
2084	<desc>
2085	Identifier of the storage format to use for the new medium.
2086	</desc>
2087	</param>
2088	<param name="location" type="wstring" dir="in">
2089	<desc>
2090	Location of the storage unit for the new medium.
2091	</desc>
2092	</param>
2093	<param name="medium" type="IMedium" dir="return">
2094	<desc>Created medium object.</desc>
2095	</param>
2096	</method>
2097
2098	<method name="openMedium">
2099	<desc>
2100	Finds existing media or opens a medium from an existing storage location.
2101
2102	Once a medium has been opened, it can be passed to other VirtualBox
2103	methods, in particular to <link to="IMachine::attachDevice" />.
2104
2105	Depending on the given device type, the file at the storage location
2106	must be in one of the media formats understood by VirtualBox:
2107
2108	<ul>
2109	<li>With a "HardDisk" device type, the file must be a hard disk image
2110	in one of the formats supported by VirtualBox (see
2111	<link to="ISystemProperties::mediumFormats" />).
2112	After this method succeeds, if the medium is a base medium, it
2113	will be added to the <link to="#hardDisks"/> array attribute. </li>
2114	<li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
2115	After this method succeeds, the medium will be added to the
2116	<link to="#DVDImages"/> array attribute.</li>
2117	<li>With a "Floppy" device type, the file must be an RAW floppy image.
2118	After this method succeeds, the medium will be added to the
2119	<link to="#floppyImages"/> array attribute.</li>
2120	</ul>
2121
2122	After having been opened, the medium can be re-found by this method
2123	and can be attached to virtual machines. See <link to="IMedium" /> for
2124	more details.
2125
2126	The UUID of the newly opened medium will either be retrieved from the
2127	storage location, if the format supports it (e.g. for hard disk images),
2128	or a new UUID will be randomly generated (e.g. for ISO and RAW files).
2129	If for some reason you need to change the medium's UUID, use
2130	<link to="IMedium::setIds" />.
2131
2132	If a differencing hard disk medium is to be opened by this method, the
2133	operation will succeed only if its parent medium and all ancestors,
2134	if any, are already known to this VirtualBox installation (for example,
2135	were opened by this method before).
2136
2137	This method attempts to guess the storage format of the specified medium
2138	by reading medium data at the specified location.
2139
2140	If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
2141	the image is opened for read/write access and must have according permissions,
2142	as VirtualBox may actually write status information into the disk's metadata
2143	sections.
2144
2145	Note that write access is required for all typical hard disk usage in VirtualBox,
2146	since VirtualBox may need to write metadata such as a UUID into the image.
2147	The only exception is opening a source image temporarily for copying and
2148	cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
2149	again soon.
2150
2151	The format of the location string is storage format specific. See
2152	<link to="IMedium::location"/> and IMedium for more details.
2153
2154	<result name="VBOX_E_FILE_ERROR">
2155	Invalid medium storage file location or could not find the medium
2156	at the specified location.
2157	</result>
2158	<result name="VBOX_E_IPRT_ERROR">
2159	Could not get medium storage format.
2160	</result>
2161	<result name="E_INVALIDARG">
2162	Invalid medium storage format.
2163	</result>
2164	<result name="VBOX_E_INVALID_OBJECT_STATE">
2165	Medium has already been added to a media registry.
2166	</result>
2167	</desc>
2168	<param name="location" type="wstring" dir="in">
2169	<desc>
2170	Location of the storage unit that contains medium data in one of
2171	the supported storage formats.
2172	</desc>
2173	</param>
2174	<param name="deviceType" type="DeviceType" dir="in">
2175	<desc>
2176	Must be one of "HardDisk", "DVD" or "Floppy".
2177	</desc>
2178	</param>
2179	<param name="accessMode" type="AccessMode" dir="in">
2180	<desc>Whether to open the image in read/write or read-only mode. For
2181	a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
2182	</param>
2183	<param name="forceNewUuid" type="boolean" dir="in">
2184	<desc>Allows the caller to request a completely new medium UUID for
2185	the image which is to be opened. Useful if one intends to open an exact
2186	copy of a previously opened image, as this would normally fail due to
2187	the duplicate UUID.</desc>
2188	</param>
2189	<param name="medium" type="IMedium" dir="return">
2190	<desc>Opened medium object.</desc>
2191	</param>
2192	</method>
2193
2194	<method name="getGuestOSType">
2195	<desc>
2196	Returns an object describing the specified guest OS type.
2197
2198	The requested guest OS type is specified using a string which is a
2199	mnemonic identifier of the guest operating system, such as
2200	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2201	particular virtual machine can be read or set using the
2202	<link to="IMachine::OSTypeId"/> attribute.
2203
2204	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2205	available guest OS type objects. Each object has an
2206	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2207	the guest OS this object describes.
2208
2209	<result name="E_INVALIDARG">
2210	@a id is not a valid Guest OS type.
2211	</result>
2212
2213	</desc>
2214	<param name="id" type="uuid" mod="string" dir="in">
2215	<desc>Guest OS type ID string.</desc>
2216	</param>
2217	<param name="type" type="IGuestOSType" dir="return">
2218	<desc>Guest OS type object.</desc>
2219	</param>
2220	</method>
2221
2222	<method name="createSharedFolder">
2223	<desc>
2224	Creates a new global shared folder by associating the given logical
2225	name with the given host path, adds it to the collection of shared
2226	folders and starts sharing it. Refer to the description of
2227	<link to="ISharedFolder"/> to read more about logical names.
2228	<note>
2229	In the current implementation, this operation is not
2230	implemented.
2231	</note>
2232	</desc>
2233	<param name="name" type="wstring" dir="in">
2234	<desc>Unique logical name of the shared folder.</desc>
2235	</param>
2236	<param name="hostPath" type="wstring" dir="in">
2237	<desc>Full path to the shared folder in the host file system.</desc>
2238	</param>
2239	<param name="writable" type="boolean" dir="in">
2240	<desc>Whether the share is writable or readonly</desc>
2241	</param>
2242	<param name="automount" type="boolean" dir="in">
2243	<desc>Whether the share gets automatically mounted by the guest
2244	or not.</desc>
2245	</param>
2246	</method>
2247
2248	<method name="removeSharedFolder">
2249	<desc>
2250	Removes the global shared folder with the given name previously
2251	created by <link to="#createSharedFolder"/> from the collection of
2252	shared folders and stops sharing it.
2253	<note>
2254	In the current implementation, this operation is not
2255	implemented.
2256	</note>
2257	</desc>
2258	<param name="name" type="wstring" dir="in">
2259	<desc>Logical name of the shared folder to remove.</desc>
2260	</param>
2261	</method>
2262
2263	<method name="getExtraDataKeys">
2264	<desc>
2265	Returns an array representing the global extra data keys which currently
2266	have values defined.
2267	</desc>
2268	<param name="keys" type="wstring" dir="return" safearray="yes">
2269	<desc>Array of extra data keys.</desc>
2270	</param>
2271	</method>
2272
2273	<method name="getExtraData">
2274	<desc>
2275	Returns associated global extra data.
2276
2277	If the requested data @a key does not exist, this function will
2278	succeed and return an empty string in the @a value argument.
2279
2280	<result name="VBOX_E_FILE_ERROR">
2281	Settings file not accessible.
2282	</result>
2283	<result name="VBOX_E_XML_ERROR">
2284	Could not parse the settings file.
2285	</result>
2286
2287	</desc>
2288	<param name="key" type="wstring" dir="in">
2289	<desc>Name of the data key to get.</desc>
2290	</param>
2291	<param name="value" type="wstring" dir="return">
2292	<desc>Value of the requested data key.</desc>
2293	</param>
2294	</method>
2295
2296	<method name="setExtraData">
2297	<desc>
2298	Sets associated global extra data.
2299
2300	If you pass @c null or empty string as a key @a value, the given @a key
2301	will be deleted.
2302
2303	<note>
2304	Before performing the actual data change, this method will ask all
2305	registered event listener using the
2306	<link to="IExtraDataCanChangeEvent"/>
2307	notification for a permission. If one of the listeners refuses the
2308	new value, the change will not be performed.
2309	</note>
2310	<note>
2311	On success, the
2312	<link to="IExtraDataChangedEvent"/> notification
2313	is called to inform all registered listeners about a successful data
2314	change.
2315	</note>
2316
2317	<result name="VBOX_E_FILE_ERROR">
2318	Settings file not accessible.
2319	</result>
2320	<result name="VBOX_E_XML_ERROR">
2321	Could not parse the settings file.
2322	</result>
2323	<result name="E_ACCESSDENIED">
2324	Modification request refused.
2325	</result>
2326
2327	</desc>
2328	<param name="key" type="wstring" dir="in">
2329	<desc>Name of the data key to set.</desc>
2330	</param>
2331	<param name="value" type="wstring" dir="in">
2332	<desc>Value to assign to the key.</desc>
2333	</param>
2334	</method>
2335
2336	<method name="setSettingsSecret">
2337	<desc>
2338	Unlocks the secret data by passing the unlock password to the
2339	server. The server will cache the password for that machine.
2340
2341	<result name="VBOX_E_INVALID_VM_STATE">
2342	Virtual machine is not mutable.
2343	</result>
2344
2345	</desc>
2346	<param name="password" type="wstring" dir="in">
2347	<desc>
2348	The cipher key.
2349	</desc>
2350	</param>
2351	</method>
2352
2353	<!--method name="createDHCPServerForInterface">
2354	<desc>
2355	Creates a DHCP server settings to be used for the given interface
2356	<result name="E_INVALIDARG">
2357	Host network interface @a name already exists.
2358	</result>
2359	</desc>
2360	<param name="interface" type="IHostNetworkInterface" dir="in">
2361	<desc>Network Interface</desc>
2362	</param>
2363	<param name="server" type="IDHCPServer" dir="out">
2364	<desc>DHCP server settings</desc>
2365	</param>
2366	</method-->
2367
2368	<method name="createDHCPServer">
2369	<desc>
2370	Creates a DHCP server settings to be used for the given internal network name
2371	<result name="E_INVALIDARG">
2372	Host network interface @a name already exists.
2373	</result>
2374	</desc>
2375	<param name="name" type="wstring" dir="in">
2376	<desc>server name</desc>
2377	</param>
2378	<param name="server" type="IDHCPServer" dir="return">
2379	<desc>DHCP server settings</desc>
2380	</param>
2381	</method>
2382
2383	<method name="findDHCPServerByNetworkName">
2384	<desc>
2385	Searches a DHCP server settings to be used for the given internal network name
2386	<result name="E_INVALIDARG">
2387	Host network interface @a name already exists.
2388	</result>
2389
2390	</desc>
2391	<param name="name" type="wstring" dir="in">
2392	<desc>server name</desc>
2393	</param>
2394	<param name="server" type="IDHCPServer" dir="return">
2395	<desc>DHCP server settings</desc>
2396	</param>
2397	</method>
2398
2399	<!--method name="findDHCPServerForInterface">
2400	<desc>
2401	Searches a DHCP server settings to be used for the given interface
2402	<result name="E_INVALIDARG">
2403	Host network interface @a name already exists.
2404	</result>
2405	</desc>
2406	<param name="interface" type="IHostNetworkInterface" dir="in">
2407	<desc>Network Interface</desc>
2408	</param>
2409	<param name="server" type="IDHCPServer" dir="out">
2410	<desc>DHCP server settings</desc>
2411	</param>
2412	</method-->
2413
2414	<method name="removeDHCPServer">
2415	<desc>
2416	Removes the DHCP server settings
2417	<result name="E_INVALIDARG">
2418	Host network interface @a name already exists.
2419	</result>
2420	</desc>
2421	<param name="server" type="IDHCPServer" dir="in">
2422	<desc>DHCP server settings to be removed</desc>
2423	</param>
2424	</method>
2425
2426	<!-- bunch of metods to create NAT -->
2427	<method name="createNATNetwork">
2428	<!-- Here we create a record in NAT network array with name
2429	and gateway/network parameters this information should
2430	be enough for VBoxNet[Lwip]NAT and VBoxNetDHCP for
2431	servicing the guests.
2432	-->
2433	<param name="networkName" type="wstring" dir="in"/>
2434	<param name="network" type="INATNetwork" dir="return"/>
2435	</method>
2436
2437	<!--
2438	Returns the NATNetwork by name, e.g. for adding porforward rule or delition.
2439	-->
2440	<method name="findNATNetworkByName">
2441	<param name="networkName" type="wstring" dir="in"/>
2442	<param name="network" type="INATNetwork" dir="return"/>
2443	</method>
2444	<!--
2445	Deletes given NAT network.
2446	-->
2447	<method name="removeNATNetwork">
2448	<param name="network" type="INATNetwork" dir="in"/>
2449	</method>
2450
2451	<method name="checkFirmwarePresent">
2452	<desc>
2453	Check if this VirtualBox installation has a firmware
2454	of the given type available, either system-wide or per-user.
2455	Optionally, this may return a hint where this firmware can be
2456	downloaded from.
2457	</desc>
2458	<param name="firmwareType" type="FirmwareType" dir="in">
2459	<desc>
2460	Type of firmware to check.
2461	</desc>
2462	</param>
2463	<param name="version" type="wstring" dir="in">
2464	<desc>Expected version number, usually empty string (presently ignored).</desc>
2465	</param>
2466
2467	<param name="url" type="wstring" dir="out">
2468	<desc>
2469	Suggested URL to download this firmware from.
2470	</desc>
2471	</param>
2472
2473	<param name="file" type="wstring" dir="out">
2474	<desc>
2475	Filename of firmware, only valid if result == TRUE.
2476	</desc>
2477	</param>
2478
2479	<param name="result" type="boolean" dir="return">
2480	<desc>If firmware of this type and version is available.</desc>
2481	</param>
2482	</method>
2483
2484	</interface>
2485
2486	<!--
2487	// IVFSExplorer
2488	/////////////////////////////////////////////////////////////////////////
2489	-->
2490
2491	<enum
2492	name="VFSType"
2493	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
2494	>
2495	<desc>
2496	Virtual file systems supported by VFSExplorer.
2497	</desc>
2498
2499	<const name="File" value="1" />
2500	<const name="Cloud" value="2" />
2501	<const name="S3" value="3" />
2502	<const name="WebDav" value="4" />
2503	</enum>
2504
2505	<enum
2506	name="VFSFileType"
2507	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
2508	>
2509	<desc>
2510	File types known by VFSExplorer.
2511	</desc>
2512
2513	<const name="Unknown" value="1" />
2514	<const name="Fifo" value="2" />
2515	<const name="DevChar" value="3" />
2516	<const name="Directory" value="4" />
2517	<const name="DevBlock" value="5" />
2518	<const name="File" value="6" />
2519	<const name="SymLink" value="7" />
2520	<const name="Socket" value="8" />
2521	<const name="WhiteOut" value="9" />
2522	</enum>
2523
2524	<interface
2525	name="IVFSExplorer" extends="$unknown"
2526	uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"
2527	wsmap="managed"
2528	>
2529	<desc>
2530	The VFSExplorer interface unifies access to different file system
2531	types. This includes local file systems as well remote file systems like
2532	S3. For a list of supported types see <link to="VFSType" />.
2533	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
2534	</desc>
2535
2536	<attribute name="path" type="wstring" readonly="yes">
2537	<desc>Returns the current path in the virtual file system.</desc>
2538	</attribute>
2539
2540	<attribute name="type" type="VFSType" readonly="yes">
2541	<desc>Returns the file system type which is currently in use.</desc>
2542	</attribute>
2543
2544	<method name="update">
2545	<desc>Updates the internal list of files/directories from the
2546	current directory level. Use <link to="#entryList" /> to get the full list
2547	after a call to this method.</desc>
2548
2549	<param name="progress" type="IProgress" dir="return">
2550	<desc>Progress object to track the operation completion.</desc>
2551	</param>
2552	</method>
2553
2554	<method name="cd">
2555	<desc>Change the current directory level.</desc>
2556
2557	<param name="dir" type="wstring" dir="in">
2558	<desc>The name of the directory to go in.</desc>
2559	</param>
2560
2561	<param name="progress" type="IProgress" dir="return">
2562	<desc>Progress object to track the operation completion.</desc>
2563	</param>
2564	</method>
2565
2566	<method name="cdUp">
2567	<desc>Go one directory upwards from the current directory level.</desc>
2568
2569	<param name="progress" type="IProgress" dir="return">
2570	<desc>Progress object to track the operation completion.</desc>
2571	</param>
2572	</method>
2573
2574	<method name="entryList">
2575	<desc>Returns a list of files/directories after a call to <link
2576	to="#update" />. The user is responsible for keeping this internal
2577	list up do date.</desc>
2578
2579	<param name="names" type="wstring" safearray="yes" dir="out">
2580	<desc>The list of names for the entries.</desc>
2581	</param>
2582
2583	<param name="types" type="unsigned long" safearray="yes" dir="out">
2584	<desc>The list of types for the entries.</desc>
2585	</param>
2586
2587	<param name="sizes" type="unsigned long" safearray="yes" dir="out">
2588	<desc>The list of sizes (in bytes) for the entries.</desc>
2589	</param>
2590
2591	<param name="modes" type="unsigned long" safearray="yes" dir="out">
2592	<desc>The list of file modes (in octal form) for the entries.</desc>
2593	</param>
2594	</method>
2595
2596	<method name="exists">
2597	<desc>Checks if the given file list exists in the current directory
2598	level.</desc>
2599
2600	<param name="names" type="wstring" safearray="yes" dir="in">
2601	<desc>The names to check.</desc>
2602	</param>
2603
2604	<param name="exists" type="wstring" safearray="yes" dir="return">
2605	<desc>The names which exist.</desc>
2606	</param>
2607	</method>
2608
2609	<method name="remove">
2610	<desc>Deletes the given files in the current directory level.</desc>
2611
2612	<param name="names" type="wstring" safearray="yes" dir="in">
2613	<desc>The names to remove.</desc>
2614	</param>
2615
2616	<param name="progress" type="IProgress" dir="return">
2617	<desc>Progress object to track the operation completion.</desc>
2618	</param>
2619	</method>
2620
2621	</interface>
2622
2623	<enum
2624	name="ImportOptions" extends="$unknown"
2625	uuid="0a981523-3b20-4004-8ee3-dfd322202ace"
2626	>
2627
2628	<desc>
2629	Import options, used with <link to="IAppliance::importMachines" />.
2630	</desc>
2631
2632	<const name="KeepAllMACs" value="1">
2633	<desc>Don't generate new MAC addresses of the attached network adapters.</desc>
2634	</const>
2635	<const name="KeepNATMACs" value="2">
2636	<desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
2637	</const>
2638
2639	</enum>
2640
2641
2642	<!--
2643	// IAppliance
2644	/////////////////////////////////////////////////////////////////////////
2645	-->
2646
2647	<interface
2648	name="IAppliance" extends="$unknown"
2649	uuid="3059cf9e-25c7-4f0b-9fa5-3c42e441670b"
2650	wsmap="managed"
2651	>
2652	<desc>
2653	Represents a platform-independent appliance in OVF format. An instance of this is returned
2654	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
2655	virtual machines within an appliance with VirtualBox.
2656
2657	The OVF standard suggests two different physical file formats:
2658
2659	<ol>
2660	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
2661	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
2662	this descriptor file references other files such as disk images, as OVF appliances typically
2663	do, those additional files must be in the same directory as the descriptor file.</li>
2664
2665	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
2666	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
2667	files and optionally other files.
2668
2669	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
2670	be added with a later version.</li>
2671	</ol>
2672
2673	<b>Importing</b> an OVF appliance into VirtualBox as instances of
2674	<link to="IMachine" /> involves the following sequence of API calls:
2675
2676	<ol>
2677	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
2678	</li>
2679
2680	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
2681	would like to import. So long as this file is syntactically valid, this will succeed
2682	and fill the appliance object with the parsed data from the OVF file.
2683	</li>
2684
2685	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
2686	contents of the IAppliance attributes accordingly. These can be inspected by a
2687	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
2688	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
2689	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
2690	systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
2691	by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
2692	The GUI can then give the user the option to confirm and/or change these suggestions.
2693	</li>
2694
2695	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2696	virtual system (machine) to override the suggestions made by the <link to="#interpret" /> routine.
2697	</li>
2698
2699	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
2700	VirtualBox as instances of <link to="IMachine" /> that match the information in the
2701	virtual system descriptions. After this call succeeded, the UUIDs of the machines created
2702	can be found in the <link to="#machines" /> array attribute.
2703	</li>
2704	</ol>
2705
2706	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
2707
2708	<ol>
2709	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
2710	an empty IAppliance object.
2711	</li>
2712
2713	<li>For each machine you would like to export, call <link to="IMachine::exportTo" />
2714	with the IAppliance object you just created. Each such call creates one instance of
2715	<link to="IVirtualSystemDescription" /> inside the appliance.
2716	</li>
2717
2718	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2719	virtual system (machine) to override the suggestions made by the <link to="IMachine::exportTo"/> routine.
2720	</li>
2721
2722	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
2723	file written.</li>
2724	</ol>
2725
2726	</desc>
2727
2728	<attribute name="path" type="wstring" readonly="yes">
2729	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
2730	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
2731	<link to="#write" /> (for export).
2732	This attribute is empty until one of these methods has been called.
2733	</desc>
2734	</attribute>
2735
2736	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
2737	<desc>
2738	Array of virtual disk definitions. One such description exists for each
2739	disk definition in the OVF; each string array item represents one such piece of
2740	disk information, with the information fields separated by tab (\\t) characters.
2741
2742	The caller should be prepared for additional fields being appended to
2743	this string in future versions of VirtualBox and therefore check for
2744	the number of tabs in the strings returned.
2745
2746	In the current version, the following eight fields are returned per string
2747	in the array:
2748
2749	<ol>
2750	<li>Disk ID (unique string identifier given to disk)</li>
2751
2752	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
2753
2754	<li>Populated size (optional unsigned integer indicating the current size of the
2755	disk; can be approximate; -1 if unspecified)</li>
2756
2757	<li>Format (string identifying the disk format, typically
2758	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
2759
2760	<li>Reference (where to find the disk image, typically a file name; if empty,
2761	then the disk should be created on import)</li>
2762
2763	<li>Image size (optional unsigned integer indicating the size of the image,
2764	which need not necessarily be the same as the values specified above, since
2765	the image may be compressed or sparse; -1 if not specified)</li>
2766
2767	<li>Chunk size (optional unsigned integer if the image is split into chunks;
2768	presently unsupported and always -1)</li>
2769
2770	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
2771	</ol>
2772	</desc>
2773	</attribute>
2774
2775	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
2776	<desc> Array of virtual system descriptions. One such description is created
2777	for each virtual system (machine) found in the OVF.
2778	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::exportTo" />
2779	(for export) has been called.
2780	</desc>
2781	</attribute>
2782
2783	<attribute name="machines" type="wstring" readonly="yes" safearray="yes">
2784	<desc>
2785	Contains the UUIDs of the machines created from the information in this appliances. This is only
2786	relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
2787	succeeded.
2788	</desc>
2789	</attribute>
2790
2791	<method name="read">
2792	<desc>
2793	Reads an OVF file into the appliance object.
2794
2795	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
2796	mere fact that this method returns successfully does not mean that VirtualBox supports all
2797	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
2798	</desc>
2799	<param name="file" type="wstring" dir="in">
2800	<desc>
2801	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2802	on whether the appliance is distributed as a set of files or as a single file, respectively).
2803	</desc>
2804	</param>
2805	<param name="progress" type="IProgress" dir="return">
2806	<desc>Progress object to track the operation completion.</desc>
2807	</param>
2808	</method>
2809
2810	<method name="interpret">
2811	<desc>
2812	Interprets the OVF data that was read when the appliance was constructed. After
2813	calling this method, one can inspect the
2814	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
2815	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
2816	the appliance.
2817
2818	Calling this method is the second step of importing an appliance into VirtualBox;
2819	see <link to="IAppliance" /> for an overview.
2820
2821	After calling this method, one should call <link to="#getWarnings" /> to find out
2822	if problems were encountered during the processing which might later lead to
2823	errors.
2824	</desc>
2825	</method>
2826
2827	<method name="importMachines">
2828	<desc>
2829	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
2830	and other interfaces that match the information contained in the appliance as
2831	closely as possible, as represented by the import instructions in the
2832	<link to="#virtualSystemDescriptions" /> array.
2833
2834	Calling this method is the final step of importing an appliance into VirtualBox;
2835	see <link to="IAppliance" /> for an overview.
2836
2837	Since importing the appliance will most probably involve copying and converting
2838	disk images, which can take a long time, this method operates asynchronously and
2839	returns an IProgress object to allow the caller to monitor the progress.
2840
2841	After the import succeeded, the UUIDs of the IMachine instances created can be
2842	retrieved from the <link to="#machines" /> array attribute.
2843	</desc>
2844
2845	<param name="options" type="ImportOptions" dir="in" safearray="yes">
2846	<desc>Options for the importing operation.</desc>
2847	</param>
2848
2849	<param name="progress" type="IProgress" dir="return">
2850	<desc>Progress object to track the operation completion.</desc>
2851	</param>
2852	</method>
2853
2854	<method name="createVFSExplorer">
2855	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
2856
2857	<param name="URI" type="wstring" dir="in">
2858	<desc>The URI describing the file system to use.</desc>
2859	</param>
2860
2861	<param name="explorer" type="IVFSExplorer" dir="return">
2862	<desc></desc>
2863	</param>
2864	</method>
2865
2866	<method name="write">
2867	<desc>
2868	Writes the contents of the appliance exports into a new OVF file.
2869
2870	Calling this method is the final step of exporting an appliance from VirtualBox;
2871	see <link to="IAppliance" /> for an overview.
2872
2873	Since exporting the appliance will most probably involve copying and converting
2874	disk images, which can take a long time, this method operates asynchronously and
2875	returns an IProgress object to allow the caller to monitor the progress.
2876	</desc>
2877	<param name="format" type="wstring" dir="in">
2878	<desc>
2879	Output format, as a string. Currently supported formats are "ovf-0.9", "ovf-1.0"
2880	and "ovf-2.0"; future versions of VirtualBox may support additional formats.
2881	</desc>
2882	</param>
2883	<param name="manifest" type="boolean" dir="in">
2884	<desc>
2885	Indicate if the optional manifest file (.mf) should be written. The manifest file
2886	is used for integrity checks prior import.
2887	</desc>
2888	</param>
2889	<param name="path" type="wstring" dir="in">
2890	<desc>
2891	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2892	on whether the appliance is distributed as a set of files or as a single file, respectively).
2893	</desc>
2894	</param>
2895	<param name="progress" type="IProgress" dir="return">
2896	<desc>Progress object to track the operation completion.</desc>
2897	</param>
2898	</method>
2899
2900	<method name="getWarnings">
2901	<desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>
2902
2903	<param name="warnings" type="wstring" dir="return" safearray="yes">
2904	<desc></desc>
2905	</param>
2906	</method>
2907
2908	</interface>
2909
2910	<enum
2911	name="VirtualSystemDescriptionType"
2912	uuid="303c0900-a746-4612-8c67-79003e91f459"
2913	>
2914	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
2915	a configuration value.</desc>
2916
2917	<const name="Ignore" value="1" />
2918	<const name="OS" value="2" />
2919	<const name="Name" value="3" />
2920	<const name="Product" value="4" />
2921	<const name="Vendor" value="5" />
2922	<const name="Version" value="6" />
2923	<const name="ProductUrl" value="7" />
2924	<const name="VendorUrl" value="8" />
2925	<const name="Description" value="9" />
2926	<const name="License" value="10" />
2927	<const name="Miscellaneous" value="11" />
2928	<const name="CPU" value="12" />
2929	<const name="Memory" value="13" />
2930	<const name="HardDiskControllerIDE" value="14" />
2931	<const name="HardDiskControllerSATA" value="15" />
2932	<const name="HardDiskControllerSCSI" value="16" />
2933	<const name="HardDiskControllerSAS" value="17" />
2934	<const name="HardDiskImage" value="18" />
2935	<const name="Floppy" value="19" />
2936	<const name="CDROM" value="20" />
2937	<const name="NetworkAdapter" value="21" />
2938	<const name="USBController" value="22" />
2939	<const name="SoundCard" value="23" />
2940	<const name="SettingsFile" value="24">
2941	<desc>Not used/implemented right now, will be added later in 4.1.x.</desc>
2942	</const>
2943	</enum>
2944
2945	<enum
2946	name="VirtualSystemDescriptionValueType"
2947	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
2948	>
2949	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
2950	type to fetch.</desc>
2951
2952	<const name="Reference" value="1" />
2953	<const name="Original" value="2" />
2954	<const name="Auto" value="3" />
2955	<const name="ExtraConfig" value="4" />
2956
2957	</enum>
2958
2959	<interface
2960	name="IVirtualSystemDescription" extends="$unknown"
2961	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
2962	wsmap="managed"
2963	>
2964
2965	<desc>Represents one virtual system (machine) in an appliance. This interface is used in
2966	the <link to="IAppliance::virtualSystemDescriptions" /> array. After
2967	<link to="IAppliance::interpret" /> has been called, that array contains information
2968	about how the virtual systems described in the OVF should best be imported into
2969	VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
2970	import an OVF into VirtualBox.
2971	</desc>
2972
2973	<attribute name="count" type="unsigned long" readonly="yes">
2974	<desc>Return the number of virtual system description entries.</desc>
2975	</attribute>
2976
2977	<method name="getDescription">
2978	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
2979	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
2980
2981	The list below identifies the value sets that are possible depending on the
2982	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
2983	the array item with the same index in @a OVFValues[] will contain the original value as contained
2984	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
2985	will contain a suggested value to be used for VirtualBox. Depending on the description type,
2986	the @a aExtraConfigValues[] array item may also be used.
2987
2988	<ul>
2989	<li>
2990	"OS": the guest operating system type. There must be exactly one such array item on import. The
2991	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
2992	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
2993	item in @a OVFValues[] will contain a numerical value that described the operating system in the OVF.
2994	</li>
2995	<li>
2996	"Name": the name to give to the new virtual machine. There can be at most one such array item;
2997	if none is present on import, then an automatic name will be created from the operating system
2998	type. The corresponding item im @a OVFValues[] will contain the suggested virtual machine name
2999	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
3000	<link to="IMachine" /> name that does not exist yet.
3001	</li>
3002	<li>
3003	"Description": an arbitrary description.
3004	</li>
3005	<li>
3006	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3007	code to display such a license for agreement; the Main API does not enforce any such policy.
3008	</li>
3009	<li>
3010	Miscellaneous: reserved for future use.
3011	</li>
3012	<li>
3013	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3014	</li>
3015	<li>
3016	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3017	is present on import, then VirtualBox will set a meaningful default based on the operating system
3018	type.
3019	</li>
3020	<li>
3021	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
3022	An optional value in @a OVFValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
3023	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
3024	writes into the OVF.
3025	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
3026	type can use to specify which hard disk controller a virtual disk should be connected to.
3027	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
3028	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
3029	its virtual machines supports four channels (primary master, primary slave, secondary master,
3030	secondary slave) and thus maps to two IDE controllers in the OVF sense.
3031	</li>
3032	<li>
3033	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3034	has no value in @a OVFValues[] or @a aVBoxValues[].
3035	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3036	</li>
3037	<li>
3038	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3039	The items in @a OVFValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
3040	"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
3041	whereas VirtualBox considers it a class of storage controllers of its own; see
3042	<link to="StorageControllerType" />).
3043	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3044	</li>
3045	<li>
3046	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3047	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3048
3049	The array item in @a OVFValues[] will contain the file specification from the OVF file (without
3050	a path since the image file should be in the same location as the OVF file itself), whereas the
3051	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3052	hard disk image. This means that on import the image will be copied and converted from the
3053	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3054
3055	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
3056	format: "controller=<index>;channel=<c>"
3057	In this string, <index> must be an integer specifying the hard disk controller to connect
3058	the image to. That number must be the index of an array item with one of the hard disk controller
3059	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
3060	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3061	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
3062	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
3063	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
3064	</li>
3065	<li>
3066	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
3067	attachment information as with "HardDiskImage" items.
3068	</li>
3069	<li>
3070	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
3071	attachment information as with "HardDiskImage" items.
3072	</li>
3073	<li>
3074	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
3075	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
3076	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3077	</li>
3078	<li>
3079	"USBController": a USB controller. There can be at most one such item. If and only if such an
3080	item ispresent, USB support will be enabled for the new virtual machine.
3081	</li>
3082	<li>
3083	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3084	present, sound support will be enabled for the new virtual machine. Note that the virtual
3085	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3086	may be different from the virtual soundcard expected by the appliance.
3087	</li>
3088	</ul>
3089
3090	</desc>
3091
3092	<param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3093	<desc></desc>
3094	</param>
3095
3096	<param name="refs" type="wstring" dir="out" safearray="yes">
3097	<desc></desc>
3098	</param>
3099
3100	<param name="OVFValues" type="wstring" dir="out" safearray="yes">
3101	<desc></desc>
3102	</param>
3103
3104	<param name="VBoxValues" type="wstring" dir="out" safearray="yes">
3105	<desc></desc>
3106	</param>
3107
3108	<param name="extraConfigValues" type="wstring" dir="out" safearray="yes">
3109	<desc></desc>
3110	</param>
3111
3112	</method>
3113
3114	<method name="getDescriptionByType">
3115	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3116	should be returned.</desc>
3117
3118	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3119	<desc></desc>
3120	</param>
3121
3122	<param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3123	<desc></desc>
3124	</param>
3125
3126	<param name="refs" type="wstring" dir="out" safearray="yes">
3127	<desc></desc>
3128	</param>
3129
3130	<param name="OVFValues" type="wstring" dir="out" safearray="yes">
3131	<desc></desc>
3132	</param>
3133
3134	<param name="VBoxValues" type="wstring" dir="out" safearray="yes">
3135	<desc></desc>
3136	</param>
3137
3138	<param name="extraConfigValues" type="wstring" dir="out" safearray="yes">
3139	<desc></desc>
3140	</param>
3141
3142	</method>
3143
3144	<method name="getValuesByType">
3145	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3146	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3147	values.</desc>
3148
3149	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3150	<desc></desc>
3151	</param>
3152
3153	<param name="which" type="VirtualSystemDescriptionValueType" dir="in">
3154	<desc></desc>
3155	</param>
3156
3157	<param name="values" type="wstring" dir="return" safearray="yes">
3158	<desc></desc>
3159	</param>
3160
3161	</method>
3162
3163	<method name="setFinalValues">
3164	<desc>
3165	This method allows the appliance's user to change the configuration for the virtual
3166	system descriptions. For each array item returned from <link to="#getDescription" />,
3167	you must pass in one boolean value and one configuration value.
3168
3169	Each item in the boolean array determines whether the particular configuration item
3170	should be enabled.
3171	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3172	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3173	and SoundCard.
3174
3175	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3176	as returned in the aVBoxValues and aExtraConfigValues arrays from <link to="#getDescription"/>,
3177	the configuration remains unchanged. Please see the documentation for <link to="#getDescription"/>
3178	for valid configuration values for the individual array item types. If the
3179	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3180	</desc>
3181
3182	<param name="enabled" type="boolean" dir="in" safearray="yes">
3183	<desc></desc>
3184	</param>
3185
3186	<param name="VBoxValues" type="wstring" dir="in" safearray="yes">
3187	<desc></desc>
3188	</param>
3189
3190	<param name="extraConfigValues" type="wstring" dir="in" safearray="yes">
3191	<desc></desc>
3192	</param>
3193	</method>
3194
3195	<method name="addDescription">
3196	<desc>
3197	This method adds an additional description entry to the stack of already
3198	available descriptions for this virtual system. This is handy for writing
3199	values which aren't directly supported by VirtualBox. One example would
3200	be the License type of <link to="VirtualSystemDescriptionType" />.
3201	</desc>
3202
3203	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3204	<desc></desc>
3205	</param>
3206
3207	<param name="VBoxValue" type="wstring" dir="in">
3208	<desc></desc>
3209	</param>
3210
3211	<param name="extraConfigValue" type="wstring" dir="in">
3212	<desc></desc>
3213	</param>
3214	</method>
3215	</interface>
3216
3217
3218	<!--
3219	// IMachine
3220	/////////////////////////////////////////////////////////////////////////
3221	-->
3222
3223	<interface
3224	name="IInternalMachineControl" extends="$unknown"
3225	uuid="dca36a92-703c-4649-98a4-f40c1ef0c336"
3226	internal="yes"
3227	wsmap="suppress"
3228	>
3229	<method name="setRemoveSavedStateFile">
3230	<desc>
3231	Updates the flag whether the saved state file is removed on a
3232	machine state change from Saved to PoweredOff.
3233	</desc>
3234	<param name="remove" type="boolean" dir="in"/>
3235	</method>
3236
3237	<method name="updateState">
3238	<desc>
3239	Updates the VM state.
3240	<note>
3241	This operation will also update the settings file with the correct
3242	information about the saved state file and delete this file from disk
3243	when appropriate.
3244	</note>
3245	</desc>
3246	<param name="state" type="MachineState" dir="in"/>
3247	</method>
3248
3249	<method name="getIPCId">
3250	<param name="id" type="wstring" dir="return"/>
3251	</method>
3252
3253	<method name="beginPowerUp">
3254	<desc>
3255	Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
3256	gives it the progress object that should be part of any pending
3257	<link to="IMachine::launchVMProcess"/> operations. The progress
3258	object may be called back to reflect an early cancelation, so some care
3259	have to be taken with respect to any cancelation callbacks. The console
3260	object will call <link to="IInternalMachineControl::endPowerUp"/>
3261	to signal the completion of the progress object.
3262	</desc>
3263	<param name="progress" type="IProgress" dir="in" />
3264	</method>
3265
3266	<method name="endPowerUp">
3267	<desc>
3268	Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
3269	This method may query status information from the progress object it
3270	received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
3271	it over to any in-progress <link to="IMachine::launchVMProcess"/>
3272	call in order to complete that progress object.
3273	</desc>
3274	<param name="result" type="long" dir="in"/>
3275	</method>
3276
3277	<method name="beginPoweringDown">
3278	<desc>
3279	Called by the VM process to inform the server it wants to
3280	stop the VM execution and power down.
3281	</desc>
3282	<param name="progress" type="IProgress" dir="out">
3283	<desc>
3284	Progress object created by VBoxSVC to wait until
3285	the VM is powered down.
3286	</desc>
3287	</param>
3288	</method>
3289
3290	<method name="endPoweringDown">
3291	<desc>
3292	Called by the VM process to inform the server that powering
3293	down previously requested by #beginPoweringDown is either
3294	successfully finished or there was a failure.
3295
3296	<result name="VBOX_E_FILE_ERROR">
3297	Settings file not accessible.
3298	</result>
3299	<result name="VBOX_E_XML_ERROR">
3300	Could not parse the settings file.
3301	</result>
3302
3303	</desc>
3304
3305	<param name="result" type="long" dir="in">
3306	<desc>@c S_OK to indicate success.
3307	</desc>
3308	</param>
3309	<param name="errMsg" type="wstring" dir="in">
3310	<desc>@c human readable error message in case of failure.
3311	</desc>
3312	</param>
3313	</method>
3314
3315	<method name="runUSBDeviceFilters">
3316	<desc>
3317	Asks the server to run USB devices filters of the associated
3318	machine against the given USB device and tell if there is
3319	a match.
3320	<note>
3321	Intended to be used only for remote USB devices. Local
3322	ones don't require to call this method (this is done
3323	implicitly by the Host and USBProxyService).
3324	</note>
3325	</desc>
3326	<param name="device" type="IUSBDevice" dir="in"/>
3327	<param name="matched" type="boolean" dir="out"/>
3328	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3329	</method>
3330
3331	<method name="captureUSBDevice">
3332	<desc>
3333	Requests a capture of the given host USB device.
3334	When the request is completed, the VM process will
3335	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3336	notification.
3337	</desc>
3338	<param name="id" type="uuid" mod="string" dir="in"/>
3339	</method>
3340
3341	<method name="detachUSBDevice">
3342	<desc>
3343	Notification that a VM is going to detach (@a done = @c false) or has
3344	already detached (@a done = @c true) the given USB device.
3345	When the @a done = @c true request is completed, the VM process will
3346	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3347	notification.
3348	<note>
3349	In the @a done = @c true case, the server must run its own filters
3350	and filters of all VMs but this one on the detached device
3351	as if it were just attached to the host computer.
3352	</note>
3353	</desc>
3354	<param name="id" type="uuid" mod="string" dir="in"/>
3355	<param name="done" type="boolean" dir="in"/>
3356	</method>
3357
3358	<method name="autoCaptureUSBDevices">
3359	<desc>
3360	Requests a capture all matching USB devices attached to the host.
3361	When the request is completed, the VM process will
3362	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3363	notification per every captured device.
3364	</desc>
3365	</method>
3366
3367	<method name="detachAllUSBDevices">
3368	<desc>
3369	Notification that a VM that is being powered down. The done
3370	parameter indicates whether which stage of the power down
3371	we're at. When @a done = @c false the VM is announcing its
3372	intentions, while when @a done = @c true the VM is reporting
3373	what it has done.
3374	<note>
3375	In the @a done = @c true case, the server must run its own filters
3376	and filters of all VMs but this one on all detach devices as
3377	if they were just attached to the host computer.
3378	</note>
3379	</desc>
3380	<param name="done" type="boolean" dir="in"/>
3381	</method>
3382
3383	<method name="onSessionEnd">
3384	<desc>
3385	Triggered by the given session object when the session is about
3386	to close normally.
3387	</desc>
3388	<param name="session" type="ISession" dir="in">
3389	<desc>Session that is being closed</desc>
3390	</param>
3391	<param name="progress" type="IProgress" dir="return">
3392	<desc>
3393	Used to wait until the corresponding machine is actually
3394	dissociated from the given session on the server.
3395	Returned only when this session is a direct one.
3396	</desc>
3397	</param>
3398	</method>
3399
3400	<method name="beginSavingState">
3401	<desc>
3402	Called by the VM process to inform the server it wants to
3403	save the current state and stop the VM execution.
3404	</desc>
3405	<param name="progress" type="IProgress" dir="out">
3406	<desc>
3407	Progress object created by VBoxSVC to wait until
3408	the state is saved.
3409	</desc>
3410	</param>
3411	<param name="stateFilePath" type="wstring" dir="out">
3412	<desc>
3413	File path the VM process must save the execution state to.
3414	</desc>
3415	</param>
3416	</method>
3417
3418	<method name="endSavingState">
3419	<desc>
3420	Called by the VM process to inform the server that saving
3421	the state previously requested by #beginSavingState is either
3422	successfully finished or there was a failure.
3423
3424	<result name="VBOX_E_FILE_ERROR">
3425	Settings file not accessible.
3426	</result>
3427	<result name="VBOX_E_XML_ERROR">
3428	Could not parse the settings file.
3429	</result>
3430
3431	</desc>
3432
3433	<param name="result" type="long" dir="in">
3434	<desc>@c S_OK to indicate success.
3435	</desc>
3436	</param>
3437	<param name="errMsg" type="wstring" dir="in">
3438	<desc>@c human readable error message in case of failure.
3439	</desc>
3440	</param>
3441	</method>
3442
3443	<method name="adoptSavedState">
3444	<desc>
3445	Gets called by <link to="IConsole::adoptSavedState"/>.
3446	<result name="VBOX_E_FILE_ERROR">
3447	Invalid saved state file path.
3448	</result>
3449	</desc>
3450	<param name="savedStateFile" type="wstring" dir="in">
3451	<desc>Path to the saved state file to adopt.</desc>
3452	</param>
3453	</method>
3454
3455	<method name="beginTakingSnapshot">
3456	<desc>
3457	Called from the VM process to request from the server to perform the
3458	server-side actions of creating a snapshot (creating differencing images
3459	and the snapshot object).
3460
3461	<result name="VBOX_E_FILE_ERROR">
3462	Settings file not accessible.
3463	</result>
3464	<result name="VBOX_E_XML_ERROR">
3465	Could not parse the settings file.
3466	</result>
3467	</desc>
3468	<param name="initiator" type="IConsole" dir="in">
3469	<desc>The console object that initiated this call.</desc>
3470	</param>
3471	<param name="name" type="wstring" dir="in">
3472	<desc>Snapshot name.</desc>
3473	</param>
3474	<param name="description" type="wstring" dir="in">
3475	<desc>Snapshot description.</desc>
3476	</param>
3477	<param name="consoleProgress" type="IProgress" dir="in">
3478	<desc>
3479	Progress object created by the VM process tracking the
3480	snapshot's progress. This has the following sub-operations:
3481	<ul>
3482	<li>setting up (weight 1);</li>
3483	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3484	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3485	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3486	<li>finishing up (weight 1)</li>
3487	</ul>
3488	</desc>
3489	</param>
3490	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3491	<desc>
3492	Whether this is an online snapshot (i.e. the machine is running).
3493	</desc>
3494	</param>
3495	<param name="stateFilePath" type="wstring" dir="out">
3496	<desc>
3497	File path the VM process must save the execution state to.
3498	</desc>
3499	</param>
3500	</method>
3501
3502	<method name="endTakingSnapshot">
3503	<desc>
3504	Called by the VM process to inform the server that the snapshot
3505	previously requested by #beginTakingSnapshot is either
3506	successfully taken or there was a failure.
3507	</desc>
3508
3509	<param name="success" type="boolean" dir="in">
3510	<desc>@c true to indicate success and @c false otherwise</desc>
3511	</param>
3512	</method>
3513
3514	<method name="deleteSnapshot">
3515	<desc>
3516	Gets called by <link to="IConsole::deleteSnapshot"/>,
3517	<link to="IConsole::deleteSnapshotAndAllChildren"/> and
3518	<link to="IConsole::deleteSnapshotRange"/>.
3519	<result name="VBOX_E_INVALID_OBJECT_STATE">
3520	Snapshot has more than one child snapshot. Only possible if the
3521	delete operation does not delete all children or the range does
3522	not meet the linearity condition.
3523	</result>
3524	</desc>
3525	<param name="initiator" type="IConsole" dir="in">
3526	<desc>The console object that initiated this call.</desc>
3527	</param>
3528	<param name="startId" type="uuid" mod="string" dir="in">
3529	<desc>UUID of the first snapshot to delete.</desc>
3530	</param>
3531	<param name="endId" type="uuid" mod="string" dir="in">
3532	<desc>UUID of the last snapshot to delete.</desc>
3533	</param>
3534	<param name="deleteAllChildren" type="boolean" dir="in">
3535	<desc>Whether all children should be deleted.</desc>
3536	</param>
3537	<param name="machineState" type="MachineState" dir="out">
3538	<desc>New machine state after this operation is started.</desc>
3539	</param>
3540	<param name="progress" type="IProgress" dir="return">
3541	<desc>Progress object to track the operation completion.</desc>
3542	</param>
3543	</method>
3544
3545	<method name="finishOnlineMergeMedium">
3546	<desc>
3547	Gets called by <link to="IInternalSessionControl::onlineMergeMedium"/>.
3548	</desc>
3549	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
3550	<desc>The medium attachment which needs to be cleaned up.</desc>
3551	</param>
3552	<param name="source" type="IMedium" dir="in">
3553	<desc>Merge source medium.</desc>
3554	</param>
3555	<param name="target" type="IMedium" dir="in">
3556	<desc>Merge target medium.</desc>
3557	</param>
3558	<param name="mergeForward" type="boolean" dir="in">
3559	<desc>Merge direction.</desc>
3560	</param>
3561	<param name="parentForTarget" type="IMedium" dir="in">
3562	<desc>For forward merges: new parent for target medium.</desc>
3563	</param>
3564	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
3565	<desc>For backward merges: list of media which need their parent UUID
3566	updated.</desc>
3567	</param>
3568	</method>
3569
3570	<method name="restoreSnapshot">
3571	<desc>
3572	Gets called by <link to="IConsole::restoreSnapshot"/>.
3573	</desc>
3574	<param name="initiator" type="IConsole" dir="in">
3575	<desc>The console object that initiated this call.</desc>
3576	</param>
3577	<param name="snapshot" type="ISnapshot" dir="in">
3578	<desc>The snapshot to restore the VM state from.</desc>
3579	</param>
3580	<param name="machineState" type="MachineState" dir="out">
3581	<desc>New machine state after this operation is started.</desc>
3582	</param>
3583	<param name="progress" type="IProgress" dir="return">
3584	<desc>Progress object to track the operation completion.</desc>
3585	</param>
3586	</method>
3587
3588	<method name="pullGuestProperties">
3589	<desc>
3590	Get the list of the guest properties matching a set of patterns along
3591	with their values, time stamps and flags and give responsibility for
3592	managing properties to the console.
3593	</desc>
3594	<param name="names" type="wstring" dir="out" safearray="yes">
3595	<desc>
3596	The names of the properties returned.
3597	</desc>
3598	</param>
3599	<param name="values" type="wstring" dir="out" safearray="yes">
3600	<desc>
3601	The values of the properties returned. The array entries match the
3602	corresponding entries in the @a name array.
3603	</desc>
3604	</param>
3605	<param name="timestamps" type="long long" dir="out" safearray="yes">
3606	<desc>
3607	The time stamps of the properties returned. The array entries match
3608	the corresponding entries in the @a name array.
3609	</desc>
3610	</param>
3611	<param name="flags" type="wstring" dir="out" safearray="yes">
3612	<desc>
3613	The flags of the properties returned. The array entries match the
3614	corresponding entries in the @a name array.
3615	</desc>
3616	</param>
3617	</method>
3618
3619	<method name="pushGuestProperty">
3620	<desc>
3621	Update a single guest property in IMachine.
3622	</desc>
3623	<param name="name" type="wstring" dir="in">
3624	<desc>
3625	The name of the property to be updated.
3626	</desc>
3627	</param>
3628	<param name="value" type="wstring" dir="in">
3629	<desc>
3630	The value of the property.
3631	</desc>
3632	</param>
3633	<param name="timestamp" type="long long" dir="in">
3634	<desc>
3635	The timestamp of the property.
3636	</desc>
3637	</param>
3638	<param name="flags" type="wstring" dir="in">
3639	<desc>
3640	The flags of the property.
3641	</desc>
3642	</param>
3643	</method>
3644
3645	<method name="lockMedia">
3646	<desc>
3647	Locks all media attached to the machine for writing and parents of
3648	attached differencing media (if any) for reading. This operation is
3649	atomic so that if it fails no media is actually locked.
3650
3651	This method is intended to be called when the machine is in Starting or
3652	Restoring state. The locked media will be automatically unlocked when
3653	the machine is powered off or crashed.
3654	</desc>
3655	</method>
3656	<method name="unlockMedia">
3657	<desc>
3658	Unlocks all media previously locked using
3659	<link to="IInternalMachineControl::lockMedia"/>.
3660
3661	This method is intended to be used with teleportation so that it is
3662	possible to teleport between processes on the same machine.
3663	</desc>
3664	</method>
3665
3666	<method name="ejectMedium">
3667	<desc>
3668	Tells VBoxSVC that the guest has ejected the medium associated with
3669	the medium attachment.
3670	</desc>
3671	<param name="attachment" type="IMediumAttachment" dir="in">
3672	<desc>
3673	The medium attachment where the eject happened.
3674	</desc>
3675	</param>
3676	<param name="newAttachment" type="IMediumAttachment" dir="return">
3677	<desc>
3678	A new reference to the medium attachment, as the config change can
3679	result in the creation of a new instance.
3680	</desc>
3681	</param>
3682	</method>
3683
3684	<method name="reportVmStatistics">
3685	<desc>
3686	Passes statistics collected by VM (including guest statistics) to VBoxSVC.
3687	</desc>
3688	<param name="validStats" type="unsigned long" dir="in">
3689	<desc>
3690	Mask defining which parameters are valid. For example: 0x11 means
3691	that cpuIdle and XXX are valid. Other parameters should be ignored.
3692	</desc>
3693	</param>
3694	<param name="cpuUser" type="unsigned long" dir="in">
3695	<desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
3696	</param>
3697	<param name="cpuKernel" type="unsigned long" dir="in">
3698	<desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
3699	</param>
3700	<param name="cpuIdle" type="unsigned long" dir="in">
3701	<desc>Percentage of processor time spent idling as seen by the guest.</desc>
3702	</param>
3703	<param name="memTotal" type="unsigned long" dir="in">
3704	<desc>Total amount of physical guest RAM.</desc>
3705	</param>
3706	<param name="memFree" type="unsigned long" dir="in">
3707	<desc>Free amount of physical guest RAM.</desc>
3708	</param>
3709	<param name="memBalloon" type="unsigned long" dir="in">
3710	<desc>Amount of ballooned physical guest RAM.</desc>
3711	</param>
3712	<param name="memShared" type="unsigned long" dir="in">
3713	<desc>Amount of shared physical guest RAM.</desc>
3714	</param>
3715	<param name="memCache" type="unsigned long" dir="in">
3716	<desc>Total amount of guest (disk) cache memory.</desc>
3717	</param>
3718	<param name="pagedTotal" type="unsigned long" dir="in">
3719	<desc>Total amount of space in the page file.</desc>
3720	</param>
3721	<param name="memAllocTotal" type="unsigned long" dir="in">
3722	<desc>Total amount of memory allocated by the hypervisor.</desc>
3723	</param>
3724	<param name="memFreeTotal" type="unsigned long" dir="in">
3725	<desc>Total amount of free memory available in the hypervisor.</desc>
3726	</param>
3727	<param name="memBalloonTotal" type="unsigned long" dir="in">
3728	<desc>Total amount of memory ballooned by the hypervisor.</desc>
3729	</param>
3730	<param name="memSharedTotal" type="unsigned long" dir="in">
3731	<desc>Total amount of shared memory in the hypervisor.</desc>
3732	</param>
3733	<param name="vmNetRx" type="unsigned long" dir="in">
3734	<desc>Network receive rate for VM.</desc>
3735	</param>
3736	<param name="vmNetTx" type="unsigned long" dir="in">
3737	<desc>Network transmit rate for VM.</desc>
3738	</param>
3739	</method>
3740	</interface>
3741
3742	<interface
3743	name="IBIOSSettings" extends="$unknown"
3744	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3745	wsmap="managed"
3746	>
3747	<desc>
3748	The IBIOSSettings interface represents BIOS settings of the virtual
3749	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3750	</desc>
3751	<attribute name="logoFadeIn" type="boolean">
3752	<desc>Fade in flag for BIOS logo animation.</desc>
3753	</attribute>
3754
3755	<attribute name="logoFadeOut" type="boolean">
3756	<desc>Fade out flag for BIOS logo animation.</desc>
3757	</attribute>
3758
3759	<attribute name="logoDisplayTime" type="unsigned long">
3760	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
3761	</attribute>
3762
3763	<attribute name="logoImagePath" type="wstring">
3764	<desc>
3765	Local file system path for external BIOS splash image. Empty string
3766	means the default image is shown on boot.
3767	</desc>
3768	</attribute>
3769
3770	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
3771	<desc>Mode of the BIOS boot device menu.</desc>
3772	</attribute>
3773
3774	<attribute name="ACPIEnabled" type="boolean">
3775	<desc>ACPI support flag.</desc>
3776	</attribute>
3777
3778	<attribute name="IOAPICEnabled" type="boolean">
3779	<desc>
3780	IO APIC support flag. If set, VirtualBox will provide an IO APIC
3781	and support IRQs above 15.
3782	</desc>
3783	</attribute>
3784
3785	<attribute name="timeOffset" type="long long">
3786	<desc>
3787	Offset in milliseconds from the host system time. This allows for
3788	guests running with a different system date/time than the host.
3789	It is equivalent to setting the system date/time in the BIOS except
3790	it is not an absolute value but a relative one. Guest Additions
3791	time synchronization honors this offset.
3792	</desc>
3793	</attribute>
3794
3795	<attribute name="PXEDebugEnabled" type="boolean">
3796	<desc>
3797	PXE debug logging flag. If set, VirtualBox will write extensive
3798	PXE trace information to the release log.
3799	</desc>
3800	</attribute>
3801	</interface>
3802
3803	<interface
3804	name="IPCIAddress" extends="$unknown"
3805	uuid="D88B324F-DB19-4D3B-A1A9-BF5B127199A8"
3806	wsmap="struct"
3807	>
3808
3809	<desc>
3810	Address on the PCI bus.
3811	</desc>
3812
3813	<attribute name="bus" type="short">
3814	<desc>
3815	Bus number.
3816	</desc>
3817	</attribute>
3818
3819	<attribute name="device" type="short">
3820	<desc>
3821	Device number.
3822	</desc>
3823	</attribute>
3824
3825	<attribute name="devFunction" type="short">
3826	<desc>
3827	Device function number.
3828	</desc>
3829	</attribute>
3830
3831	<method name="asLong">
3832	<desc>
3833	Convert PCI address into long.
3834	</desc>
3835	<param name="result" type="long" dir="return" />
3836	</method>
3837
3838	<method name="fromLong">
3839	<desc>
3840	Make PCI address from long.
3841	</desc>
3842	<param name="number" type="long" dir="in" />
3843	</method>
3844	</interface>
3845
3846	<interface
3847	name="IPCIDeviceAttachment" extends="$unknown"
3848	uuid="91f33d6f-e621-4f70-a77e-15f0e3c714d5"
3849	wsmap="struct"
3850	>
3851
3852	<desc>
3853	Information about PCI attachments.
3854	</desc>
3855
3856	<attribute name="name" type="wstring" readonly="yes">
3857	<desc>
3858	Device name.
3859	</desc>
3860	</attribute>
3861
3862	<attribute name="isPhysicalDevice" type="boolean" readonly="yes">
3863	<desc>
3864	If this is physical or virtual device.
3865	</desc>
3866	</attribute>
3867
3868	<attribute name="hostAddress" type="long" readonly="yes">
3869	<desc>
3870	Address of device on the host, applicable only to host devices.
3871	</desc>
3872	</attribute>
3873
3874	<attribute name="guestAddress" type="long" readonly="yes">
3875	<desc>
3876	Address of device on the guest.
3877	</desc>
3878	</attribute>
3879
3880	</interface>
3881
3882	<enum
3883	name="GraphicsControllerType"
3884	uuid="79c96ca0-9f39-4900-948e-68c41cbe127a"
3885	>
3886	<desc>Graphics controller type, used with <link to="IMachine::unregister" />.
3887	</desc>
3888	<const name="Null" value="0">
3889	<desc>Reserved value, invalid.</desc>
3890	</const>
3891	<const name="VBoxVGA" value="1">
3892	<desc>Default VirtualBox VGA device.</desc>
3893	</const>
3894	</enum>
3895
3896	<enum
3897	name="CleanupMode"
3898	uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441"
3899	>
3900	<desc>Cleanup mode, used with <link to="IMachine::unregister" />.
3901	</desc>
3902	<const name="UnregisterOnly" value="1">
3903	<desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
3904	</const>
3905	<const name="DetachAllReturnNone" value="2">
3906	<desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
3907	</const>
3908	<const name="DetachAllReturnHardDisksOnly" value="3">
3909	<desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc>
3910	</const>
3911	<const name="Full" value="4">
3912	<desc>Delete all snapshots, detach all media and return all media for closing.</desc>
3913	</const>
3914	</enum>
3915
3916	<enum
3917	name="CloneMode" extends="$unknown"
3918	uuid="A7A159FE-5096-4B8D-8C3C-D033CB0B35A8"
3919	>
3920
3921	<desc>
3922	Clone mode, used with <link to="IMachine::cloneTo" />.
3923	</desc>
3924
3925	<const name="MachineState" value="1">
3926	<desc>Clone the state of the selected machine.</desc>
3927	</const>
3928	<const name="MachineAndChildStates" value="2">
3929	<desc>Clone the state of the selected machine and its child snapshots if present.</desc>
3930	</const>
3931	<const name="AllStates" value="3">
3932	<desc>Clone all states (including all snapshots) of the machine, regardless of the machine object used.</desc>
3933	</const>
3934
3935	</enum>
3936
3937	<enum
3938	name="CloneOptions" extends="$unknown"
3939	uuid="22243f8e-96ab-497c-8cf0-f40a566c630b"
3940	>
3941
3942	<desc>
3943	Clone options, used with <link to="IMachine::cloneTo" />.
3944	</desc>
3945
3946	<const name="Link" value="1">
3947	<desc>Create a clone VM where all virtual disks are linked to the original VM.</desc>
3948	</const>
3949	<const name="KeepAllMACs" value="2">
3950	<desc>Don't generate new MAC addresses of the attached network adapters.</desc>
3951	</const>
3952	<const name="KeepNATMACs" value="3">
3953	<desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
3954	</const>
3955	<const name="KeepDiskNames" value="4">
3956	<desc>Don't change the disk names.</desc>
3957	</const>
3958
3959	</enum>
3960
3961	<enum
3962	name="AutostopType" extends="$unknown"
3963	uuid="6bb96740-cf34-470d-aab2-2cd48ea2e10e"
3964	>
3965
3966	<desc>
3967	Autostop types, used with <link to="IMachine::autostopType" />.
3968	</desc>
3969
3970	<const name="Disabled" value="1">
3971	<desc>Stopping the VM during system shutdown is disabled.</desc>
3972	</const>
3973	<const name="SaveState" value="2">
3974	<desc>The state of the VM will be saved when the system shuts down.</desc>
3975	</const>
3976	<const name="PowerOff" value="3">
3977	<desc>The VM is powered off when the system shuts down.</desc>
3978	</const>
3979	<const name="AcpiShutdown" value="4">
3980	<desc>An ACPI shutdown event is generated.</desc>
3981	</const>
3982
3983	</enum>
3984
3985
3986	<interface
3987	name="IMachine" extends="$unknown"
3988	uuid="f6258810-a760-11e2-9e96-0800200c9a66"
3989	wsmap="managed"
3990	>
3991	<desc>
3992	The IMachine interface represents a virtual machine, or guest, created
3993	in VirtualBox.
3994
3995	This interface is used in two contexts. First of all, a collection of
3996	objects implementing this interface is stored in the
3997	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
3998	machines that are currently registered with this VirtualBox
3999	installation. Also, once a session has been opened for the given virtual
4000	machine (e.g. the virtual machine is running), the machine object
4001	associated with the open session can be queried from the session object;
4002	see <link to="ISession"/> for details.
4003
4004	The main role of this interface is to expose the settings of the virtual
4005	machine and provide methods to change various aspects of the virtual
4006	machine's configuration. For machine objects stored in the
4007	<link to="IVirtualBox::machines"/> collection, all attributes are
4008	read-only unless explicitly stated otherwise in individual attribute
4009	and method descriptions.
4010
4011	In order to change a machine setting, a session for this machine must be
4012	opened using one of the <link to="IMachine::lockMachine" /> or
4013	<link to="IMachine::launchVMProcess"/> methods. After the
4014	machine has been successfully locked for a session, a mutable machine object
4015	needs to be queried from the session object and then the desired settings
4016	changes can be applied to the returned object using IMachine attributes and
4017	methods. See the <link to="ISession"/> interface description for more
4018	information about sessions.
4019
4020	Note that IMachine does not provide methods to control virtual machine
4021	execution (such as start the machine, or power it down) -- these methods
4022	are grouped in a separate interface called <link to="IConsole" />.
4023
4024	<see><link to="ISession"/>, <link to="IConsole"/></see>
4025	</desc>
4026
4027	<attribute name="parent" type="IVirtualBox" readonly="yes">
4028	<desc>Associated parent object.</desc>
4029	</attribute>
4030
4031	<attribute name="icon" type="octet" safearray="yes">
4032	<desc>Overriden VM Icon details.</desc>
4033	</attribute>
4034
4035	<attribute name="accessible" type="boolean" readonly="yes">
4036	<desc>
4037	Whether this virtual machine is currently accessible or not.
4038
4039	A machine is always deemed accessible unless it is registered <i>and</i>
4040	its settings file cannot be read or parsed (either because the file itself
4041	is unavailable or has invalid XML contents).
4042
4043	Every time this property is read, the accessibility state of
4044	this machine is re-evaluated. If the returned value is @c false,
4045	the <link to="#accessError"/> property may be used to get the
4046	detailed error information describing the reason of
4047	inaccessibility, including XML error messages.
4048
4049	When the machine is inaccessible, only the following properties
4050	can be used on it:
4051	<ul>
4052	<li><link to="#parent"/></li>
4053	<li><link to="#id"/></li>
4054	<li><link to="#settingsFilePath"/></li>
4055	<li><link to="#accessible"/></li>
4056	<li><link to="#accessError"/></li>
4057	</ul>
4058
4059	An attempt to access any other property or method will return
4060	an error.
4061
4062	The only possible action you can perform on an inaccessible
4063	machine is to unregister it using the
4064	<link to="IMachine::unregister"/> call (or, to check
4065	for the accessibility state once more by querying this
4066	property).
4067
4068	<note>
4069	In the current implementation, once this property returns
4070	@c true, the machine will never become inaccessible
4071	later, even if its settings file cannot be successfully
4072	read/written any more (at least, until the VirtualBox
4073	server is restarted). This limitation may be removed in
4074	future releases.
4075	</note>
4076	</desc>
4077	</attribute>
4078
4079	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4080	<desc>
4081	Error information describing the reason of machine
4082	inaccessibility.
4083
4084	Reading this property is only valid after the last call to
4085	<link to="#accessible"/> returned @c false (i.e. the
4086	machine is currently inaccessible). Otherwise, a @c null
4087	IVirtualBoxErrorInfo object will be returned.
4088	</desc>
4089	</attribute>
4090
4091	<attribute name="name" type="wstring">
4092	<desc>
4093	Name of the virtual machine.
4094
4095	Besides being used for human-readable identification purposes
4096	everywhere in VirtualBox, the virtual machine name is also used
4097	as a name of the machine's settings file and as a name of the
4098	subdirectory this settings file resides in. Thus, every time you
4099	change the value of this property, the settings file will be
4100	renamed once you call <link to="#saveSettings"/> to confirm the
4101	change. The containing subdirectory will be also renamed, but
4102	only if it has exactly the same name as the settings file
4103	itself prior to changing this property (for backward compatibility
4104	with previous API releases). The above implies the following
4105	limitations:
4106	<ul>
4107	<li>The machine name cannot be empty.</li>
4108	<li>The machine name can contain only characters that are valid
4109	file name characters according to the rules of the file
4110	system used to store VirtualBox configuration.</li>
4111	<li>You cannot have two or more machines with the same name
4112	if they use the same subdirectory for storing the machine
4113	settings files.</li>
4114	<li>You cannot change the name of the machine if it is running,
4115	or if any file in the directory containing the settings file
4116	is being used by another running machine or by any other
4117	process in the host operating system at a time when
4118	<link to="#saveSettings"/> is called.
4119	</li>
4120	</ul>
4121	If any of the above limitations are hit, <link to="#saveSettings"/>
4122	will return an appropriate error message explaining the exact
4123	reason and the changes you made to this machine will not be saved.
4124
4125	Starting with VirtualBox 4.0, a ".vbox" extension of the settings
4126	file is recommended, but not enforced. (Previous versions always
4127	used a generic ".xml" extension.)
4128	</desc>
4129	</attribute>
4130
4131	<attribute name="description" type="wstring">
4132	<desc>
4133	Description of the virtual machine.
4134
4135	The description attribute can contain any text and is
4136	typically used to describe the hardware and software
4137	configuration of the virtual machine in detail (i.e. network
4138	settings, versions of the installed software and so on).
4139	</desc>
4140	</attribute>
4141
4142	<attribute name="id" type="uuid" mod="string" readonly="yes">
4143	<desc>UUID of the virtual machine.</desc>
4144	</attribute>
4145
4146	<attribute name="groups" type="wstring" safearray="yes">
4147	<desc>
4148	Array of machine group names of which this machine is a member.
4149	<tt>""</tt> and <tt>"/"</tt> are synonyms for the toplevel group. Each
4150	group is only listed once, however they are listed in no particular
4151	order and there is no guarantee that there are no gaps in the group
4152	hierarchy (i.e. <tt>"/group"</tt>,
4153	<tt>"/group/subgroup/subsubgroup"</tt> is a valid result).
4154	</desc>
4155	</attribute>
4156
4157	<attribute name="OSTypeId" type="wstring">
4158	<desc>
4159	User-defined identifier of the Guest OS type.
4160	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4161	an IGuestOSType object representing details about the given
4162	Guest OS type.
4163	<note>
4164	This value may differ from the value returned by
4165	<link to="IGuest::OSTypeId"/> if Guest Additions are
4166	installed to the guest OS.
4167	</note>
4168	</desc>
4169	</attribute>
4170
4171	<attribute name="hardwareVersion" type="wstring">
4172	<desc>Hardware version identifier. Internal use only for now.</desc>
4173	</attribute>
4174
4175	<attribute name="hardwareUUID" type="uuid" mod="string">
4176	<desc>
4177	The UUID presented to the guest via memory tables, hardware and guest
4178	properties. For most VMs this is the same as the @a id, but for VMs
4179	which have been cloned or teleported it may be the same as the source
4180	VM. The latter is because the guest shouldn't notice that it was
4181	cloned or teleported.
4182	</desc>
4183	</attribute>
4184
4185	<attribute name="CPUCount" type="unsigned long">
4186	<desc>Number of virtual CPUs in the VM.</desc>
4187	</attribute>
4188
4189	<attribute name="CPUHotPlugEnabled" type="boolean">
4190	<desc>
4191	This setting determines whether VirtualBox allows CPU
4192	hotplugging for this machine.</desc>
4193	</attribute>
4194
4195	<attribute name="CPUExecutionCap" type="unsigned long">
4196	<desc>
4197	Means to limit the number of CPU cycles a guest can use. The unit
4198	is percentage of host CPU cycles per second. The valid range
4199	is 1 - 100. 100 (the default) implies no limit.
4200	</desc>
4201	</attribute>
4202
4203	<attribute name="memorySize" type="unsigned long">
4204	<desc>System memory size in megabytes.</desc>
4205	</attribute>
4206
4207	<attribute name="memoryBalloonSize" type="unsigned long">
4208	<desc>Memory balloon size in megabytes.</desc>
4209	</attribute>
4210
4211	<attribute name="pageFusionEnabled" type="boolean">
4212	<desc>
4213	This setting determines whether VirtualBox allows page
4214	fusion for this machine (64-bit hosts only).
4215	</desc>
4216	</attribute>
4217
4218	<attribute name="graphicsControllerType" type="GraphicsControllerType">
4219	<desc>Graphics controller type.</desc>
4220	</attribute>
4221
4222	<attribute name="VRAMSize" type="unsigned long">
4223	<desc>Video memory size in megabytes.</desc>
4224	</attribute>
4225
4226	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4227	<desc>
4228	This setting determines whether VirtualBox allows this machine to make
4229	use of the 3D graphics support available on the host.</desc>
4230	</attribute>
4231
4232	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4233	<desc>
4234	This setting determines whether VirtualBox allows this machine to make
4235	use of the 2D video acceleration support available on the host.</desc>
4236	</attribute>
4237
4238	<attribute name="monitorCount" type="unsigned long">
4239	<desc>
4240	Number of virtual monitors.
4241	<note>
4242	Only effective on Windows XP and later guests with
4243	Guest Additions installed.
4244	</note>
4245	</desc>
4246	</attribute>
4247
4248	<attribute name="VideoCaptureEnabled" type="boolean" default="false">
4249	<desc>
4250	This setting determines whether VirtualBox uses video recording to
4251	record VM session.</desc>
4252	</attribute>
4253
4254	<attribute name="VideoCaptureScreens" type="boolean" safearray="yes">
4255	<desc>
4256	This setting determines for which screens video recording is
4257	enabled.</desc>
4258	</attribute>
4259
4260	<attribute name="VideoCaptureFile" type="wstring" default="Test.webm">
4261	<desc>
4262	This setting determines the filename VirtualBox uses to save
4263	the recorded content.</desc>
4264	</attribute>
4265
4266	<attribute name="VideoCaptureWidth" type="unsigned long" default="640">
4267	<desc>
4268	This setting determines the horizontal resolution of the recorded video.</desc>
4269	</attribute>
4270
4271	<attribute name="VideoCaptureHeight" type="unsigned long" default="480">
4272	<desc>
4273	This setting determines the vertical resolution of the recorded video.</desc>
4274	</attribute>
4275
4276	<attribute name="VideoCaptureRate" type="unsigned long" default="512">
4277	<desc>
4278	This setting determines the bitrate in kilobits per second.
4279	Increasing this value makes the video look better for the
4280	cost of an increased file size.
4281	</desc>
4282	</attribute>
4283
4284	<attribute name="VideoCaptureFps" type="unsigned long" default="25">
4285	<desc>
4286	This setting determines the maximum number of frames per second.
4287	Frames with a higher frequency will be skipped. Reducing this
4288	value increses the number of skipped frames but reduces the
4289	file size.
4290	</desc>
4291	</attribute>
4292
4293	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4294	<desc>Object containing all BIOS settings.</desc>
4295	</attribute>
4296
4297	<attribute name="firmwareType" type="FirmwareType">
4298	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4299	bootstrap in this VM.</desc>
4300	</attribute>
4301
4302	<attribute name="pointingHIDType" type="PointingHIDType">
4303	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4304	The default is typically "PS2Mouse" but can vary depending on the
4305	requirements of the guest operating system.</desc>
4306	</attribute>
4307
4308	<attribute name="keyboardHIDType" type="KeyboardHIDType">
4309	<desc>Type of keyboard HID used in this VM.
4310	The default is typically "PS2Keyboard" but can vary depending on the
4311	requirements of the guest operating system.</desc>
4312	</attribute>
4313
4314	<attribute name="HPETEnabled" type="boolean">
4315	<desc>This attribute controls if High Precision Event Timer (HPET) is
4316	enabled in this VM. Use this property if you want to provide guests
4317	with additional time source, or if guest requires HPET to function correctly.
4318	Default is false.</desc>
4319	</attribute>
4320
4321	<attribute name="chipsetType" type="ChipsetType">
4322	<desc>Chipset type used in this VM.</desc>
4323	</attribute>
4324
4325	<attribute name="snapshotFolder" type="wstring">
4326	<desc>
4327	Full path to the directory used to store snapshot data
4328	(differencing media and saved state files) of this machine.
4329
4330	The initial value of this property is
4331	<tt><</tt><link to="#settingsFilePath">
4332	path_to_settings_file</link><tt>>/<</tt>
4333	<link to="#id">machine_uuid</link>
4334	<tt>></tt>.
4335
4336	Currently, it is an error to try to change this property on
4337	a machine that has snapshots (because this would require to
4338	move possibly large files to a different location).
4339	A separate method will be available for this purpose later.
4340
4341	<note>
4342	Setting this property to @c null or to an empty string will restore
4343	the initial value.
4344	</note>
4345	<note>
4346	When setting this property, the specified path can be
4347	absolute (full path) or relative to the directory where the
4348	<link to="#settingsFilePath">machine settings file</link>
4349	is located. When reading this property, a full path is
4350	always returned.
4351	</note>
4352	<note>
4353	The specified path may not exist, it will be created
4354	when necessary.
4355	</note>
4356	</desc>
4357	</attribute>
4358
4359	<attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
4360	<desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
4361	</attribute>
4362
4363	<attribute name="emulatedUSBWebcameraEnabled" type="boolean" default="false"/>
4364	<attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/>
4365
4366	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4367	<desc>Array of media attached to this machine.</desc>
4368	</attribute>
4369
4370	<attribute name="USBController" type="IUSBController" readonly="yes">
4371	<desc>
4372	Associated USB controller object.
4373
4374	<note>
4375	If USB functionality is not available in the given edition of
4376	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4377	</note>
4378	</desc>
4379	</attribute>
4380
4381	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4382	<desc>Associated audio adapter, always present.</desc>
4383	</attribute>
4384
4385	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4386	<desc>Array of storage controllers attached to this machine.</desc>
4387	</attribute>
4388
4389	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4390	<desc>
4391	Full name of the file containing machine settings data.
4392	</desc>
4393	</attribute>
4394
4395	<attribute name="settingsModified" type="boolean" readonly="yes">
4396	<desc>
4397	Whether the settings of this machine have been modified
4398	(but neither yet saved nor discarded).
4399	<note>
4400	Reading this property is only valid on instances returned
4401	by <link to="ISession::machine"/> and on new machines
4402	created by <link to="IVirtualBox::createMachine"/> or opened
4403	by <link to="IVirtualBox::openMachine"/> but not
4404	yet registered, or on unregistered machines after calling
4405	<link to="IMachine::unregister"/>. For all other
4406	cases, the settings can never be modified.
4407	</note>
4408	<note>
4409	For newly created unregistered machines, the value of this
4410	property is always @c true until <link to="#saveSettings"/>
4411	is called (no matter if any machine settings have been
4412	changed after the creation or not). For opened machines
4413	the value is set to @c false (and then follows to normal rules).
4414	</note>
4415	</desc>
4416	</attribute>
4417
4418	<attribute name="sessionState" type="SessionState" readonly="yes">
4419	<desc>Current session state for this machine.</desc>
4420	</attribute>
4421
4422	<attribute name="sessionType" type="wstring" readonly="yes">
4423	<desc>
4424	Type of the session. If <link to="#sessionState"/> is
4425	Spawning or Locked, this attribute contains the
4426	same value as passed to the
4427	<link to="IMachine::launchVMProcess"/> method in the
4428	@a type parameter. If the session was used with
4429	<link to="IMachine::lockMachine" />, or if
4430	<link to="#sessionState"/> is SessionClosed, the value of this
4431	attribute is an empty string.
4432	</desc>
4433	</attribute>
4434
4435	<attribute name="sessionPID" type="unsigned long" readonly="yes">
4436	<desc>
4437	Identifier of the session process. This attribute contains the
4438	platform-dependent identifier of the process whose session was
4439	used with <link to="IMachine::lockMachine" /> call. The returned
4440	value is only valid if <link to="#sessionState"/> is Locked or
4441	Unlocking by the time this property is read.
4442	</desc>
4443	</attribute>
4444
4445	<attribute name="state" type="MachineState" readonly="yes">
4446	<desc>Current execution state of this machine.</desc>
4447	</attribute>
4448
4449	<attribute name="lastStateChange" type="long long" readonly="yes">
4450	<desc>
4451	Time stamp of the last execution state change,
4452	in milliseconds since 1970-01-01 UTC.
4453	</desc>
4454	</attribute>
4455
4456	<attribute name="stateFilePath" type="wstring" readonly="yes">
4457	<desc>
4458	Full path to the file that stores the execution state of
4459	the machine when it is in the <link to="MachineState_Saved"/> state.
4460	<note>
4461	When the machine is not in the Saved state, this attribute is
4462	an empty string.
4463	</note>
4464	</desc>
4465	</attribute>
4466
4467	<attribute name="logFolder" type="wstring" readonly="yes">
4468	<desc>
4469	Full path to the folder that stores a set of rotated log files
4470	recorded during machine execution. The most recent log file is
4471	named <tt>VBox.log</tt>, the previous log file is
4472	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4473	in the current version).
4474	</desc>
4475	</attribute>
4476
4477	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4478	<desc>
4479	Current snapshot of this machine. This is @c null if the machine
4480	currently has no snapshots. If it is not @c null, then it was
4481	set by one of <link to="IConsole::takeSnapshot" />,
4482	<link to="IConsole::deleteSnapshot" />
4483	or <link to="IConsole::restoreSnapshot" />, depending on which
4484	was called last. See <link to="ISnapshot"/> for details.
4485	</desc>
4486	</attribute>
4487
4488	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4489	<desc>
4490	Number of snapshots taken on this machine. Zero means the
4491	machine doesn't have any snapshots.
4492	</desc>
4493	</attribute>
4494
4495	<attribute name="currentStateModified" type="boolean" readonly="yes">
4496	<desc>
4497	Returns @c true if the current state of the machine is not
4498	identical to the state stored in the current snapshot.
4499
4500	The current state is identical to the current snapshot only
4501	directly after one of the following calls are made:
4502
4503	<ul>
4504	<li><link to="IConsole::restoreSnapshot"/>
4505	</li>
4506	<li><link to="IConsole::takeSnapshot"/> (issued on a
4507	"powered off" or "saved" machine, for which
4508	<link to="#settingsModified"/> returns @c false)
4509	</li>
4510	</ul>
4511
4512	The current state remains identical until one of the following
4513	happens:
4514	<ul>
4515	<li>settings of the machine are changed</li>
4516	<li>the saved state is deleted</li>
4517	<li>the current snapshot is deleted</li>
4518	<li>an attempt to execute the machine is made</li>
4519	</ul>
4520
4521	<note>
4522	For machines that don't have snapshots, this property is
4523	always @c false.
4524	</note>
4525	</desc>
4526	</attribute>
4527
4528	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4529	<desc>
4530	Collection of shared folders for this machine (permanent shared
4531	folders). These folders are shared automatically at machine startup
4532	and available only to the guest OS installed within this machine.
4533
4534	New shared folders are added to the collection using
4535	<link to="#createSharedFolder"/>. Existing shared folders can be
4536	removed using <link to="#removeSharedFolder"/>.
4537	</desc>
4538	</attribute>
4539
4540	<attribute name="clipboardMode" type="ClipboardMode">
4541	<desc>
4542	Synchronization mode between the host OS clipboard
4543	and the guest OS clipboard.
4544	</desc>
4545	</attribute>
4546
4547	<attribute name="dragAndDropMode" type="DragAndDropMode">
4548	<desc>
4549	Which mode is allowed for drag'n'drop.
4550	</desc>
4551	</attribute>
4552
4553	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4554	<desc>
4555	A comma-separated list of simple glob patterns. Changes to guest
4556	properties whose name matches one of the patterns will generate an
4557	<link to="IGuestPropertyChangedEvent"/> signal.
4558	</desc>
4559	</attribute>
4560
4561	<attribute name="teleporterEnabled" type="boolean">
4562	<desc>
4563	When set to @a true, the virtual machine becomes a target teleporter
4564	the next time it is powered on. This can only set to @a true when the
4565	VM is in the @a PoweredOff or @a Aborted state.
4566
4567	<!-- This property is automatically set to @a false when the VM is powered
4568	on. (bird: This doesn't work yet ) -->
4569	</desc>
4570	</attribute>
4571
4572	<attribute name="teleporterPort" type="unsigned long">
4573	<desc>
4574	The TCP port the target teleporter will listen for incoming
4575	teleportations on.
4576
4577	0 means the port is automatically selected upon power on. The actual
4578	value can be read from this property while the machine is waiting for
4579	incoming teleportations.
4580	</desc>
4581	</attribute>
4582
4583	<attribute name="teleporterAddress" type="wstring">
4584	<desc>
4585	The address the target teleporter will listen on. If set to an empty
4586	string, it will listen on all addresses.
4587	</desc>
4588	</attribute>
4589
4590	<attribute name="teleporterPassword" type="wstring">
4591	<desc>
4592	The password to check for on the target teleporter. This is just a
4593	very basic measure to prevent simple hacks and operators accidentally
4594	beaming a virtual machine to the wrong place.
4595
4596	Note that you SET a plain text password while reading back a HASHED
4597	password. Setting a hashed password is currently not supported.
4598	</desc>
4599	</attribute>
4600
4601	<attribute name="faultToleranceState" type="FaultToleranceState">
4602	<desc>
4603	Fault tolerance state; disabled, source or target.
4604	This property can be changed at any time. If you change it for a running
4605	VM, then the fault tolerance address and port must be set beforehand.
4606	</desc>
4607	</attribute>
4608
4609	<attribute name="faultTolerancePort" type="unsigned long">
4610	<desc>
4611	The TCP port the fault tolerance source or target will use for
4612	communication.
4613	</desc>
4614	</attribute>
4615
4616	<attribute name="faultToleranceAddress" type="wstring">
4617	<desc>
4618	The address the fault tolerance source or target.
4619	</desc>
4620	</attribute>
4621
4622	<attribute name="faultTolerancePassword" type="wstring">
4623	<desc>
4624	The password to check for on the standby VM. This is just a
4625	very basic measure to prevent simple hacks and operators accidentally
4626	choosing the wrong standby VM.
4627	</desc>
4628	</attribute>
4629
4630	<attribute name="faultToleranceSyncInterval" type="unsigned long">
4631	<desc>
4632	The interval in ms used for syncing the state between source and target.
4633	</desc>
4634	</attribute>
4635
4636	<attribute name="RTCUseUTC" type="boolean">
4637	<desc>
4638	When set to @a true, the RTC device of the virtual machine will run
4639	in UTC time, otherwise in local time. Especially Unix guests prefer
4640	the time in UTC.
4641	</desc>
4642	</attribute>
4643
4644	<attribute name="IOCacheEnabled" type="boolean">
4645	<desc>
4646	When set to @a true, the builtin I/O cache of the virtual machine
4647	will be enabled.
4648	</desc>
4649	</attribute>
4650
4651	<attribute name="IOCacheSize" type="unsigned long">
4652	<desc>
4653	Maximum size of the I/O cache in MB.
4654	</desc>
4655	</attribute>
4656
4657	<attribute name="PCIDeviceAssignments" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
4658	<desc>Array of PCI devices assigned to this machine, to get list of all
4659	PCI devices attached to the machine use
4660	<link to="IConsole::attachedPCIDevices"/> attribute, as this attribute
4661	is intended to list only devices additional to what described in
4662	virtual hardware config. Usually, this list keeps host's physical
4663	devices assigned to the particular machine.
4664	</desc>
4665	</attribute>
4666
4667	<attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes">
4668	<desc>
4669	Bandwidth control manager.
4670	</desc>
4671	</attribute>
4672
4673	<attribute name="tracingEnabled" type="boolean">
4674	<desc>
4675	Enables the tracing facility in the VMM (including PDM devices +
4676	drivers). The VMM will consume about 0.5MB of more memory when
4677	enabled and there may be some extra overhead from tracepoints that are
4678	always enabled.
4679	</desc>
4680	</attribute>
4681
4682	<attribute name="tracingConfig" type="wstring">
4683	<desc>
4684	Tracepoint configuration to apply at startup when
4685	<link to="IMachine::tracingEnabled" /> is true. The string specifies
4686	a space separated of tracepoint group names to enable. The special
4687	group 'all' enables all tracepoints. Check DBGFR3TracingConfig for
4688	more details on available tracepoint groups and such.
4689
4690	Note that on hosts supporting DTrace (or similar), a lot of the
4691	tracepoints may be implemented exclusivly as DTrace probes. So, the
4692	effect of the same config may differ between Solaris and Windows for
4693	example.
4694	</desc>
4695	</attribute>
4696
4697	<attribute name="allowTracingToAccessVM" type="boolean">
4698	<desc>
4699	Enables tracepoints in PDM devices and drivers to use the VMCPU or VM
4700	structures when firing off trace points. This is especially useful
4701	with DTrace tracepoints, as it allows you to use the VMCPU or VM
4702	pointer to obtain useful information such as guest register state.
4703
4704	This is disabled by default because devices and drivers normally has no
4705	business accessing the VMCPU or VM structures, and are therefore unable
4706	to get any pointers to these.
4707	</desc>
4708	</attribute>
4709
4710	<attribute name="autostartEnabled" type="boolean">
4711	<desc>
4712	Enables autostart of the VM during system boot.
4713	</desc>
4714	</attribute>
4715
4716	<attribute name="autostartDelay" type="unsigned long">
4717	<desc>
4718	Number of seconds to wait until the VM should be started during system boot.
4719	</desc>
4720	</attribute>
4721
4722	<attribute name="autostopType" type="AutostopType">
4723	<desc>
4724	Action type to do when the system is shutting down.
4725	</desc>
4726	</attribute>
4727
4728	<attribute name="defaultFrontend" type="wstring">
4729	<desc>
4730	Selects which VM frontend should be used by default when launching
4731	this VM through the <link to="IMachine::launchVMProcess" /> method.
4732	Empty or @c null strings do not define a particular default, it is up
4733	to <link to="IMachine::launchVMProcess" /> to select one. See the
4734	description of <link to="IMachine::launchVMProcess" /> for the valid
4735	frontend types.
4736
4737	This per-VM setting overrides the default defined by
4738	<link to="ISystemProperties::defaultFrontend" /> attribute, and is
4739	overridden by a frontend type passed to
4740	<link to="IMachine::launchVMProcess" />.
4741	</desc>
4742	</attribute>
4743
4744	<method name="lockMachine">
4745	<desc>
4746	Locks the machine for the given session to enable the caller
4747	to make changes to the machine or start the VM or control
4748	VM execution.
4749
4750	There are two ways to lock a machine for such uses:
4751
4752	<ul>
4753	<li>If you want to make changes to the machine settings,
4754	you must obtain an exclusive write lock on the machine
4755	by setting @a lockType to @c Write.
4756
4757	This will only succeed if no other process has locked
4758	the machine to prevent conflicting changes. Only after
4759	an exclusive write lock has been obtained using this method, one
4760	can change all VM settings or execute the VM in the process
4761	space of the session object. (Note that the latter is only of
4762	interest if you actually want to write a new front-end for
4763	virtual machines; but this API gets called internally by
4764	the existing front-ends such as VBoxHeadless and the VirtualBox
4765	GUI to acquire a write lock on the machine that they are running.)
4766
4767	On success, write-locking the machine for a session creates
4768	a second copy of the IMachine object. It is this second object
4769	upon which changes can be made; in VirtualBox terminology, the
4770	second copy is "mutable". It is only this second, mutable machine
4771	object upon which you can call methods that change the
4772	machine state. After having called this method, you can
4773	obtain this second, mutable machine object using the
4774	<link to="ISession::machine" /> attribute.
4775	</li>
4776	<li>If you only want to check the machine state or control
4777	machine execution without actually changing machine
4778	settings (e.g. to get access to VM statistics or take
4779	a snapshot or save the machine state), then set the
4780	@a lockType argument to @c Shared.
4781
4782	If no other session has obtained a lock, you will obtain an
4783	exclusive write lock as described above. However, if another
4784	session has already obtained such a lock, then a link to that
4785	existing session will be established which allows you
4786	to control that existing session.
4787
4788	To find out which type of lock was obtained, you can
4789	inspect <link to="ISession::type" />, which will have been
4790	set to either @c WriteLock or @c Shared.
4791	</li>
4792	</ul>
4793
4794	In either case, you can get access to the <link to="IConsole" />
4795	object which controls VM execution.
4796
4797	Also in all of the above cases, one must always call
4798	<link to="ISession::unlockMachine" /> to release the lock on the machine, or
4799	the machine's state will eventually be set to "Aborted".
4800
4801	To change settings on a machine, the following sequence is typically
4802	performed:
4803
4804	<ol>
4805	<li>Call this method to obtain an exclusive write lock for the current session.</li>
4806
4807	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
4808
4809	<li>Change the settings of the machine by invoking IMachine methods.</li>
4810
4811	<li>Call <link to="IMachine::saveSettings" />.</li>
4812
4813	<li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
4814	</ol>
4815
4816	<result name="E_UNEXPECTED">
4817	Virtual machine not registered.
4818	</result>
4819	<result name="E_ACCESSDENIED">
4820	Process not started by OpenRemoteSession.
4821	</result>
4822	<result name="VBOX_E_INVALID_OBJECT_STATE">
4823	Session already open or being opened.
4824	</result>
4825	<result name="VBOX_E_VM_ERROR">
4826	Failed to assign machine to session.
4827	</result>
4828	</desc>
4829	<param name="session" type="ISession" dir="in">
4830	<desc>
4831	Session object for which the machine will be locked.
4832	</desc>
4833	</param>
4834	<param name="lockType" type="LockType" dir="in">
4835	<desc>
4836	If set to @c Write, then attempt to acquire an exclusive write lock or fail.
4837	If set to @c Shared, then either acquire an exclusive write lock or establish
4838	a link to an existing session.
4839	</desc>
4840	</param>
4841	</method>
4842
4843	<method name="launchVMProcess">
4844	<desc>
4845	Spawns a new process that will execute the virtual machine and obtains a shared
4846	lock on the machine for the calling session.
4847
4848	If launching the VM succeeds, the new VM process will create its own session
4849	and write-lock the machine for it, preventing conflicting changes from other
4850	processes. If the machine is already locked (because it is already running or
4851	because another session has a write lock), launching the VM process will therefore
4852	fail. Reversely, future attempts to obtain a write lock will also fail while the
4853	machine is running.
4854
4855	The caller's session object remains separate from the session opened by the new
4856	VM process. It receives its own <link to="IConsole" /> object which can be used
4857	to control machine execution, but it cannot be used to change all VM settings
4858	which would be available after a <link to="#lockMachine" /> call.
4859
4860	The caller must eventually release the session's shared lock by calling
4861	<link to="ISession::unlockMachine" /> on the local session object once this call
4862	has returned. However, the session's state (see <link to="ISession::state" />)
4863	will not return to "Unlocked" until the remote session has also unlocked
4864	the machine (i.e. the machine has stopped running).
4865
4866	Launching a VM process can take some time (a new VM is started in a new process,
4867	for which memory and other resources need to be set up). Because of this,
4868	an <link to="IProgress" /> object is returned to allow the caller to wait
4869	for this asynchronous operation to be completed. Until then, the caller's
4870	session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
4871	and <link to="ISession::console" /> attributes cannot be accessed.
4872	It is recommended to use <link to="IProgress::waitForCompletion" /> or
4873	similar calls to wait for completion. Completion is signalled when the VM
4874	is powered on. If launching the VM fails, error messages can be queried
4875	via the progress object, if available.
4876
4877	The progress object will have at least 2 sub-operations. The first
4878	operation covers the period up to the new VM process calls powerUp.
4879	The subsequent operations mirror the <link to="IConsole::powerUp"/>
4880	progress object. Because <link to="IConsole::powerUp"/> may require
4881	some extra sub-operations, the <link to="IProgress::operationCount"/>
4882	may change at the completion of operation.
4883
4884	For details on the teleportation progress operation, see
4885	<link to="IConsole::powerUp"/>.
4886
4887	The @a environment argument is a string containing definitions of
4888	environment variables in the following format:
4889	<pre>
4890	NAME[=VALUE]\n
4891	NAME[=VALUE]\n
4892	...
4893	</pre>
4894	where <tt>\\n</tt> is the new line character. These environment
4895	variables will be appended to the environment of the VirtualBox server
4896	process. If an environment variable exists both in the server process
4897	and in this list, the value from this list takes precedence over the
4898	server's variable. If the value of the environment variable is
4899	omitted, this variable will be removed from the resulting environment.
4900	If the environment string is @c null or empty, the server environment
4901	is inherited by the started process as is.
4902
4903	<result name="E_UNEXPECTED">
4904	Virtual machine not registered.
4905	</result>
4906	<result name="E_INVALIDARG">
4907	Invalid session type @a type.
4908	</result>
4909	<result name="VBOX_E_OBJECT_NOT_FOUND">
4910	No machine matching @a machineId found.
4911	</result>
4912	<result name="VBOX_E_INVALID_OBJECT_STATE">
4913	Session already open or being opened.
4914	</result>
4915	<result name="VBOX_E_IPRT_ERROR">
4916	Launching process for machine failed.
4917	</result>
4918	<result name="VBOX_E_VM_ERROR">
4919	Failed to assign machine to session.
4920	</result>
4921	</desc>
4922	<param name="session" type="ISession" dir="in">
4923	<desc>
4924	Client session object to which the VM process will be connected (this
4925	must be in "Unlocked" state).
4926	</desc>
4927	</param>
4928	<param name="type" type="wstring" dir="in">
4929	<desc>
4930	Front-end to use for the new VM process. The following are currently supported:
4931	<ul>
4932	<li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
4933	<li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
4934	<li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
4935	<li><tt>"emergencystop"</tt>: reserved value, used for aborting
4936	the currently running VM or session owner. In this case the
4937	@a session parameter may be @c null (if it is non-null it isn't
4938	used in any way), and the @a progress return value will be always
4939	@c null. The operation completes immediately.</li>
4940	<li><tt>""</tt>: use the per-VM default frontend if set, otherwise
4941	the global default defined in the system properties. If neither
4942	are set, the API will launch a <tt>"gui"</tt> session, which may
4943	fail if there is no windowing environment available. See
4944	<link to="IMachine::defaultFrontend"/> and
4945	<link to="ISystemProperties::defaultFrontend"/>.</li>
4946	</ul>
4947	</desc>
4948	</param>
4949	<param name="environment" type="wstring" dir="in">
4950	<desc>
4951	Environment to pass to the VM process.
4952	</desc>
4953	</param>
4954	<param name="progress" type="IProgress" dir="return">
4955	<desc>Progress object to track the operation completion.</desc>
4956	</param>
4957	</method>
4958
4959	<method name="setBootOrder">
4960	<desc>
4961	Puts the given device to the specified position in
4962	the boot order.
4963
4964	To indicate that no device is associated with the given position,
4965	<link to="DeviceType_Null"/> should be used.
4966
4967	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4968
4969	<result name="E_INVALIDARG">
4970	Boot @a position out of range.
4971	</result>
4972	<result name="E_NOTIMPL">
4973	Booting from USB @a device currently not supported.
4974	</result>
4975
4976	</desc>
4977	<param name="position" type="unsigned long" dir="in">
4978	<desc>
4979	Position in the boot order (@c 1 to the total number of
4980	devices the machine can boot from, as returned by
4981	<link to="ISystemProperties::maxBootPosition"/>).
4982	</desc>
4983	</param>
4984	<param name="device" type="DeviceType" dir="in">
4985	<desc>
4986	The type of the device used to boot at the given position.
4987	</desc>
4988	</param>
4989	</method>
4990
4991	<method name="getBootOrder" const="yes">
4992	<desc>
4993	Returns the device type that occupies the specified
4994	position in the boot order.
4995
4996	@todo [remove?]
4997	If the machine can have more than one device of the returned type
4998	(such as hard disks), then a separate method should be used to
4999	retrieve the individual device that occupies the given position.
5000
5001	If here are no devices at the given position, then
5002	<link to="DeviceType_Null"/> is returned.
5003
5004	@todo getHardDiskBootOrder(), getNetworkBootOrder()
5005
5006	<result name="E_INVALIDARG">
5007	Boot @a position out of range.
5008	</result>
5009
5010	</desc>
5011	<param name="position" type="unsigned long" dir="in">
5012	<desc>
5013	Position in the boot order (@c 1 to the total number of
5014	devices the machine can boot from, as returned by
5015	<link to="ISystemProperties::maxBootPosition"/>).
5016	</desc>
5017	</param>
5018	<param name="device" type="DeviceType" dir="return">
5019	<desc>
5020	Device at the given position.
5021	</desc>
5022	</param>
5023	</method>
5024
5025	<method name="attachDevice">
5026	<desc>
5027	Attaches a device and optionally mounts a medium to the given storage
5028	controller (<link to="IStorageController" />, identified by @a name),
5029	at the indicated port and device.
5030
5031	This method is intended for managing storage devices in general while a
5032	machine is powered off. It can be used to attach and detach fixed
5033	and removable media. The following kind of media can be attached
5034	to a machine:
5035
5036	<ul>
5037	<li>For fixed and removable media, you can pass in a medium that was
5038	previously opened using <link to="IVirtualBox::openMedium" />.
5039	</li>
5040
5041	<li>Only for storage devices supporting removable media (such as
5042	DVDs and floppies), you can also specify a null pointer to
5043	indicate an empty drive or one of the medium objects listed
5044	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5045	arrays to indicate a host drive.
5046	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5047	to change the media while the machine is running.
5048	</li>
5049	</ul>
5050
5051	In a VM's default configuration of virtual machines, the secondary
5052	master of the IDE controller is used for a CD/DVD drive.
5053
5054	After calling this returns successfully, a new instance of
5055	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5056	attachments (see <link to="IMachine::mediumAttachments"/>).
5057
5058	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5059	information about attaching media.
5060
5061	The specified device slot must not have a device attached to it,
5062	or this method will fail.
5063
5064	<note>
5065	You cannot attach a device to a newly created machine until
5066	this machine's settings are saved to disk using
5067	<link to="#saveSettings"/>.
5068	</note>
5069	<note>
5070	If the medium is being attached indirectly, a new differencing medium
5071	will implicitly be created for it and attached instead. If the
5072	changes made to the machine settings (including this indirect
5073	attachment) are later cancelled using <link to="#discardSettings"/>,
5074	this implicitly created differencing medium will implicitly
5075	be deleted.
5076	</note>
5077
5078	<result name="E_INVALIDARG">
5079	SATA device, SATA port, IDE port or IDE slot out of range, or
5080	file or UUID not found.
5081	</result>
5082	<result name="VBOX_E_INVALID_OBJECT_STATE">
5083	Machine must be registered before media can be attached.
5084	</result>
5085	<result name="VBOX_E_INVALID_VM_STATE">
5086	Invalid machine state.
5087	</result>
5088	<result name="VBOX_E_OBJECT_IN_USE">
5089	A medium is already attached to this or another virtual machine.
5090	</result>
5091
5092	</desc>
5093	<param name="name" type="wstring" dir="in">
5094	<desc>Name of the storage controller to attach the device to.</desc>
5095	</param>
5096	<param name="controllerPort" type="long" dir="in">
5097	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5098	the primary controller and 1 specifies the secondary controller.
5099	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5100	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5101	</param>
5102	<param name="device" type="long" dir="in">
5103	<desc>Device slot in the given port to attach the device to. This is only
5104	relevant for IDE controllers, for which 0 specifies the master device and
5105	1 specifies the slave device. For all other controller types, this must
5106	be 0.</desc>
5107	</param>
5108	<param name="type" type="DeviceType" dir="in">
5109	<desc>Device type of the attached device. For media opened by
5110	<link to="IVirtualBox::openMedium" />, this must match the device type
5111	specified there.</desc>
5112	</param>
5113	<param name="medium" type="IMedium" dir="in">
5114	<desc>Medium to mount or @c null for an empty drive.</desc>
5115	</param>
5116	</method>
5117
5118	<method name="attachDeviceWithoutMedium">
5119	<desc>
5120	Attaches a device and optionally mounts a medium to the given storage
5121	controller (<link to="IStorageController" />, identified by @a name),
5122	at the indicated port and device.
5123
5124	This method is intended for managing storage devices in general while a
5125	machine is powered off. It can be used to attach and detach fixed
5126	and removable media. The following kind of media can be attached
5127	to a machine:
5128	<ul>
5129	<li>
5130	For fixed and removable media, you can pass in a medium that was
5131	previously opened using <link to="IVirtualBox::openMedium" />.
5132	</li>
5133
5134	<li>Only for storage devices supporting removable media (such as
5135	DVDs and floppies) with an empty drive or one of the medium objects listed
5136	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5137	arrays to indicate a host drive.
5138	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5139	to change the media while the machine is running.
5140	</li>
5141	</ul>
5142
5143	In a VM's default configuration of virtual machines, the secondary
5144	master of the IDE controller is used for a CD/DVD drive.
5145	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5146	attachments (see <link to="IMachine::mediumAttachments"/>).
5147
5148	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5149	information about attaching media.
5150
5151	The specified device slot must not have a device attached to it,
5152	or this method will fail.
5153	<note>
5154	You cannot attach a device to a newly created machine until
5155	this machine's settings are saved to disk using
5156	<link to="#saveSettings"/>.
5157	</note>
5158	<note>
5159	If the medium is being attached indirectly, a new differencing medium
5160	will implicitly be created for it and attached instead. If the
5161	changes made to the machine settings (including this indirect
5162	attachment) are later cancelled using <link to="#discardSettings"/>,
5163	this implicitly created differencing medium will implicitly
5164	be deleted.
5165	</note>
5166
5167	<result name="E_INVALIDARG">
5168	SATA device, SATA port, IDE port or IDE slot out of range, or
5169	file or UUID not found.
5170	</result>
5171	<result name="VBOX_E_INVALID_OBJECT_STATE">
5172	Machine must be registered before media can be attached.
5173	</result>
5174	<result name="VBOX_E_INVALID_VM_STATE">
5175	Invalid machine state.
5176	</result>
5177	<result name="VBOX_E_OBJECT_IN_USE">
5178	A medium is already attached to this or another virtual machine.
5179	</result>
5180	</desc>
5181	<param name="name" type="wstring" dir="in">
5182	<desc>Name of the storage controller to attach the device to.</desc>
5183	</param>
5184	<param name="controllerPort" type="long" dir="in">
5185	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5186	the primary controller and 1 specifies the secondary controller.
5187	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5188	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5189	</param>
5190	<param name="device" type="long" dir="in">
5191	<desc>Device slot in the given port to attach the device to. This is only
5192	relevant for IDE controllers, for which 0 specifies the master device and
5193	1 specifies the slave device. For all other controller types, this must
5194	be 0.</desc>
5195	</param>
5196	<param name="type" type="DeviceType" dir="in">
5197	<desc>Device type of the attached device. For media opened by
5198	<link to="IVirtualBox::openMedium" />, this must match the device type
5199	specified there.</desc>
5200	</param>
5201	</method>
5202
5203	<method name="detachDevice">
5204	<desc>
5205	Detaches the device attached to a device slot of the specified bus.
5206
5207	Detaching the device from the virtual machine is deferred. This means
5208	that the medium remains associated with the machine when this method
5209	returns and gets actually de-associated only after a successful
5210	<link to="#saveSettings"/> call. See <link to="IMedium"/>
5211	for more detailed information about attaching media.
5212
5213	<note>
5214	You cannot detach a device from a running machine.
5215	</note>
5216	<note>
5217	Detaching differencing media implicitly created by <link
5218	to="#attachDevice"/> for the indirect attachment using this
5219	method will <b>not</b> implicitly delete them. The
5220	<link to="IMedium::deleteStorage"/> operation should be
5221	explicitly performed by the caller after the medium is successfully
5222	detached and the settings are saved with
5223	<link to="#saveSettings"/>, if it is the desired action.
5224	</note>
5225
5226	<result name="VBOX_E_INVALID_VM_STATE">
5227	Attempt to detach medium from a running virtual machine.
5228	</result>
5229	<result name="VBOX_E_OBJECT_NOT_FOUND">
5230	No medium attached to given slot/bus.
5231	</result>
5232	<result name="VBOX_E_NOT_SUPPORTED">
5233	Medium format does not support storage deletion (only for implicitly
5234	created differencing media, should not happen).
5235	</result>
5236
5237	</desc>
5238	<param name="name" type="wstring" dir="in">
5239	<desc>Name of the storage controller to detach the medium from.</desc>
5240	</param>
5241	<param name="controllerPort" type="long" dir="in">
5242	<desc>Port number to detach the medium from.</desc>
5243	</param>
5244	<param name="device" type="long" dir="in">
5245	<desc>Device slot number to detach the medium from.</desc>
5246	</param>
5247	</method>
5248
5249	<method name="passthroughDevice">
5250	<desc>
5251	Sets the passthrough mode of an existing DVD device. Changing the
5252	setting while the VM is running is forbidden. The setting is only used
5253	if at VM start the device is configured as a host DVD drive, in all
5254	other cases it is ignored. The device must already exist; see
5255	<link to="IMachine::attachDevice"/> for how to attach a new device.
5256
5257	The @a controllerPort and @a device parameters specify the device slot and
5258	have have the same meaning as with <link to="IMachine::attachDevice" />.
5259
5260	<result name="E_INVALIDARG">
5261	SATA device, SATA port, IDE port or IDE slot out of range.
5262	</result>
5263	<result name="VBOX_E_INVALID_OBJECT_STATE">
5264	Attempt to modify an unregistered virtual machine.
5265	</result>
5266	<result name="VBOX_E_INVALID_VM_STATE">
5267	Invalid machine state.
5268	</result>
5269
5270	</desc>
5271	<param name="name" type="wstring" dir="in">
5272	<desc>Name of the storage controller.</desc>
5273	</param>
5274	<param name="controllerPort" type="long" dir="in">
5275	<desc>Storage controller port.</desc>
5276	</param>
5277	<param name="device" type="long" dir="in">
5278	<desc>Device slot in the given port.</desc>
5279	</param>
5280	<param name="passthrough" type="boolean" dir="in">
5281	<desc>New value for the passthrough setting.</desc>
5282	</param>
5283	</method>
5284
5285	<method name="temporaryEjectDevice">
5286	<desc>
5287	Sets the behavior for guest-triggered medium eject. In some situations
5288	it is desirable that such ejects update the VM configuration, and in
5289	others the eject should keep the VM configuration. The device must
5290	already exist; see <link to="IMachine::attachDevice"/> for how to
5291	attach a new device.
5292
5293	The @a controllerPort and @a device parameters specify the device slot and
5294	have have the same meaning as with <link to="IMachine::attachDevice" />.
5295
5296	<result name="E_INVALIDARG">
5297	SATA device, SATA port, IDE port or IDE slot out of range.
5298	</result>
5299	<result name="VBOX_E_INVALID_OBJECT_STATE">
5300	Attempt to modify an unregistered virtual machine.
5301	</result>
5302	<result name="VBOX_E_INVALID_VM_STATE">
5303	Invalid machine state.
5304	</result>
5305
5306	</desc>
5307	<param name="name" type="wstring" dir="in">
5308	<desc>Name of the storage controller.</desc>
5309	</param>
5310	<param name="controllerPort" type="long" dir="in">
5311	<desc>Storage controller port.</desc>
5312	</param>
5313	<param name="device" type="long" dir="in">
5314	<desc>Device slot in the given port.</desc>
5315	</param>
5316	<param name="temporaryEject" type="boolean" dir="in">
5317	<desc>New value for the eject behavior.</desc>
5318	</param>
5319	</method>
5320
5321	<method name="nonRotationalDevice">
5322	<desc>
5323	Sets a flag in the device information which indicates that the medium
5324	is not based on rotational technology, i.e. that the access times are
5325	more or less independent of the position on the medium. This may or may
5326	not be supported by a particular drive, and is silently ignored in the
5327	latter case. At the moment only hard disks (which is a misnomer in this
5328	context) accept this setting. Changing the setting while the VM is
5329	running is forbidden. The device must already exist; see
5330	<link to="IMachine::attachDevice"/> for how to attach a new device.
5331
5332	The @a controllerPort and @a device parameters specify the device slot and
5333	have have the same meaning as with <link to="IMachine::attachDevice" />.
5334
5335	<result name="E_INVALIDARG">
5336	SATA device, SATA port, IDE port or IDE slot out of range.
5337	</result>
5338	<result name="VBOX_E_INVALID_OBJECT_STATE">
5339	Attempt to modify an unregistered virtual machine.
5340	</result>
5341	<result name="VBOX_E_INVALID_VM_STATE">
5342	Invalid machine state.
5343	</result>
5344
5345	</desc>
5346	<param name="name" type="wstring" dir="in">
5347	<desc>Name of the storage controller.</desc>
5348	</param>
5349	<param name="controllerPort" type="long" dir="in">
5350	<desc>Storage controller port.</desc>
5351	</param>
5352	<param name="device" type="long" dir="in">
5353	<desc>Device slot in the given port.</desc>
5354	</param>
5355	<param name="nonRotational" type="boolean" dir="in">
5356	<desc>New value for the non-rotational device flag.</desc>
5357	</param>
5358	</method>
5359
5360	<method name="setAutoDiscardForDevice">
5361	<desc>
5362	Sets a flag in the device information which indicates that the medium
5363	supports discarding unsused blocks (called trimming for SATA or unmap
5364	for SCSI devices) .This may or may not be supported by a particular drive,
5365	and is silently ignored in the latter case. At the moment only hard disks
5366	(which is a misnomer in this context) accept this setting. Changing the
5367	setting while the VM is running is forbidden. The device must already
5368	exist; see <link to="IMachine::attachDevice"/> for how to attach a new
5369	device.
5370
5371	The @a controllerPort and @a device parameters specify the device slot and
5372	have have the same meaning as with <link to="IMachine::attachDevice" />.
5373
5374	<result name="E_INVALIDARG">
5375	SATA device, SATA port, SCSI port out of range.
5376	</result>
5377	<result name="VBOX_E_INVALID_OBJECT_STATE">
5378	Attempt to modify an unregistered virtual machine.
5379	</result>
5380	<result name="VBOX_E_INVALID_VM_STATE">
5381	Invalid machine state.
5382	</result>
5383
5384	</desc>
5385	<param name="name" type="wstring" dir="in">
5386	<desc>Name of the storage controller.</desc>
5387	</param>
5388	<param name="controllerPort" type="long" dir="in">
5389	<desc>Storage controller port.</desc>
5390	</param>
5391	<param name="device" type="long" dir="in">
5392	<desc>Device slot in the given port.</desc>
5393	</param>
5394	<param name="discard" type="boolean" dir="in">
5395	<desc>New value for the discard device flag.</desc>
5396	</param>
5397	</method>
5398
5399	<method name="setBandwidthGroupForDevice">
5400	<desc>
5401	Sets the bandwidth group of an existing storage device.
5402	The device must already exist; see <link to="IMachine::attachDevice"/>
5403	for how to attach a new device.
5404
5405	The @a controllerPort and @a device parameters specify the device slot and
5406	have have the same meaning as with <link to="IMachine::attachDevice" />.
5407
5408	<result name="E_INVALIDARG">
5409	SATA device, SATA port, IDE port or IDE slot out of range.
5410	</result>
5411	<result name="VBOX_E_INVALID_OBJECT_STATE">
5412	Attempt to modify an unregistered virtual machine.
5413	</result>
5414	<result name="VBOX_E_INVALID_VM_STATE">
5415	Invalid machine state.
5416	</result>
5417
5418	</desc>
5419	<param name="name" type="wstring" dir="in">
5420	<desc>Name of the storage controller.</desc>
5421	</param>
5422	<param name="controllerPort" type="long" dir="in">
5423	<desc>Storage controller port.</desc>
5424	</param>
5425	<param name="device" type="long" dir="in">
5426	<desc>Device slot in the given port.</desc>
5427	</param>
5428	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
5429	<desc>New value for the bandwidth group or @c null for no group.</desc>
5430	</param>
5431	</method>
5432
5433	<method name="setNoBandwidthGroupForDevice">
5434	<desc>
5435	Sets no bandwidth group for an existing storage device.
5436	The device must already exist; see <link to="IMachine::attachDevice"/>
5437	for how to attach a new device.
5438	The @a controllerPort and @a device parameters specify the device slot and
5439	have have the same meaning as with <link to="IMachine::attachDevice" />.
5440	<result name="E_INVALIDARG">
5441	SATA device, SATA port, IDE port or IDE slot out of range.
5442	</result>
5443	<result name="VBOX_E_INVALID_OBJECT_STATE">
5444	Attempt to modify an unregistered virtual machine.
5445	</result>
5446	<result name="VBOX_E_INVALID_VM_STATE">
5447	Invalid machine state.
5448	</result>
5449
5450	</desc>
5451	<param name="name" type="wstring" dir="in">
5452	<desc>Name of the storage controller.</desc>
5453	</param>
5454	<param name="controllerPort" type="long" dir="in">
5455	<desc>Storage controller port.</desc>
5456	</param>
5457	<param name="device" type="long" dir="in">
5458	<desc>Device slot in the given port.</desc>
5459	</param>
5460	</method>
5461
5462
5463	<method name="unmountMedium">
5464	<desc>
5465	Unmounts any currently mounted medium (<link to="IMedium" />,
5466	identified by the given UUID @a id) to the given storage controller
5467	(<link to="IStorageController" />, identified by @a name),
5468	at the indicated port and device. The device must already exist;
5469
5470	This method is intended only for managing removable media, where the
5471	device is fixed but media is changeable at runtime (such as DVDs
5472	and floppies). It cannot be used for fixed media such as hard disks.
5473
5474	The @a controllerPort and @a device parameters specify the device slot
5475	and have have the same meaning as with
5476	<link to="IMachine::attachDevice" />.
5477
5478	The specified device slot must have a medium mounted, which will be
5479	unmounted. If there is no mounted medium it will do nothing.
5480	See <link to="IMedium"/> for more detailed information about
5481	attaching/unmounting media.
5482
5483	<result name="E_INVALIDARG">
5484	SATA device, SATA port, IDE port or IDE slot out of range.
5485	</result>
5486	<result name="VBOX_E_INVALID_OBJECT_STATE">
5487	Attempt to unmount medium that is not removeable - not dvd or floppy.
5488	</result>
5489	<result name="VBOX_E_INVALID_VM_STATE">
5490	Invalid machine state.
5491	</result>
5492	<result name="VBOX_E_OBJECT_IN_USE">
5493	Medium already attached to this or another virtual machine.
5494	</result>
5495	<result name="VBOX_E_OBJECT_NOT_FOUND">
5496	Medium not attached to specified port, device, controller.
5497	</result>
5498
5499	</desc>
5500	<param name="name" type="wstring" dir="in">
5501	<desc>Name of the storage controller to unmount the medium from.</desc>
5502	</param>
5503	<param name="controllerPort" type="long" dir="in">
5504	<desc>Port to unmount the medium from.</desc>
5505	</param>
5506	<param name="device" type="long" dir="in">
5507	<desc>Device slot in the given port to unmount the medium from.</desc>
5508	</param>
5509	<param name="force" type="boolean" dir="in">
5510	<desc>Allows to force unmount of a medium which is locked by
5511	the device slot in the given port medium is attached to.</desc>
5512	</param>
5513	</method>
5514
5515	<method name="mountMedium">
5516	<desc>
5517	Mounts a medium (<link to="IMedium" />, identified
5518	by the given UUID @a id) to the given storage controller
5519	(<link to="IStorageController" />, identified by @a name),
5520	at the indicated port and device. The device must already exist;
5521	see <link to="IMachine::attachDevice"/> for how to attach a new device.
5522
5523	This method is intended only for managing removable media, where the
5524	device is fixed but media is changeable at runtime (such as DVDs
5525	and floppies). It cannot be used for fixed media such as hard disks.
5526
5527	The @a controllerPort and @a device parameters specify the device slot and
5528	have have the same meaning as with <link to="IMachine::attachDevice" />.
5529
5530	The specified device slot can have a medium mounted, which will be
5531	unmounted first. Specifying a zero UUID (or an empty string) for
5532	@a medium does just an unmount.
5533
5534	See <link to="IMedium"/> for more detailed information about
5535	attaching media.
5536
5537	<result name="E_INVALIDARG">
5538	SATA device, SATA port, IDE port or IDE slot out of range.
5539	</result>
5540	<result name="VBOX_E_INVALID_OBJECT_STATE">
5541	Attempt to attach medium to an unregistered virtual machine.
5542	</result>
5543	<result name="VBOX_E_INVALID_VM_STATE">
5544	Invalid machine state.
5545	</result>
5546	<result name="VBOX_E_OBJECT_IN_USE">
5547	Medium already attached to this or another virtual machine.
5548	</result>
5549
5550	</desc>
5551	<param name="name" type="wstring" dir="in">
5552	<desc>Name of the storage controller to attach the medium to.</desc>
5553	</param>
5554	<param name="controllerPort" type="long" dir="in">
5555	<desc>Port to attach the medium to.</desc>
5556	</param>
5557	<param name="device" type="long" dir="in">
5558	<desc>Device slot in the given port to attach the medium to.</desc>
5559	</param>
5560	<param name="medium" type="IMedium" dir="in">
5561	<desc>Medium to mount or @c null for an empty drive.</desc>
5562	</param>
5563	<param name="force" type="boolean" dir="in">
5564	<desc>Allows to force unmount/mount of a medium which is locked by
5565	the device slot in the given port to attach the medium to.</desc>
5566	</param>
5567	</method>
5568
5569	<method name="getMedium" const="yes">
5570	<desc>
5571	Returns the virtual medium attached to a device slot of the specified
5572	bus.
5573
5574	Note that if the medium was indirectly attached by
5575	<link to="#mountMedium"/> to the given device slot then this
5576	method will return not the same object as passed to the
5577	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5578	more detailed information about mounting a medium.
5579
5580	<result name="VBOX_E_OBJECT_NOT_FOUND">
5581	No medium attached to given slot/bus.
5582	</result>
5583
5584	</desc>
5585	<param name="name" type="wstring" dir="in">
5586	<desc>Name of the storage controller the medium is attached to.</desc>
5587	</param>
5588	<param name="controllerPort" type="long" dir="in">
5589	<desc>Port to query.</desc>
5590	</param>
5591	<param name="device" type="long" dir="in">
5592	<desc>Device slot in the given port to query.</desc>
5593	</param>
5594	<param name="medium" type="IMedium" dir="return">
5595	<desc>Attached medium object.</desc>
5596	</param>
5597	</method>
5598
5599	<method name="getMediumAttachmentsOfController" const="yes">
5600	<desc>
5601	Returns an array of medium attachments which are attached to the
5602	the controller with the given name.
5603
5604	<result name="VBOX_E_OBJECT_NOT_FOUND">
5605	A storage controller with given name doesn't exist.
5606	</result>
5607	</desc>
5608	<param name="name" type="wstring" dir="in"/>
5609	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5610	</method>
5611
5612	<method name="getMediumAttachment" const="yes">
5613	<desc>
5614	Returns a medium attachment which corresponds to the controller with
5615	the given name, on the given port and device slot.
5616
5617	<result name="VBOX_E_OBJECT_NOT_FOUND">
5618	No attachment exists for the given controller/port/device combination.
5619	</result>
5620	</desc>
5621	<param name="name" type="wstring" dir="in"/>
5622	<param name="controllerPort" type="long" dir="in"/>
5623	<param name="device" type="long" dir="in"/>
5624	<param name="attachment" type="IMediumAttachment" dir="return"/>
5625	</method>
5626
5627	<method name="attachHostPCIDevice">
5628	<desc>
5629	Attaches host PCI device with the given (host) PCI address to the
5630	PCI bus of the virtual machine. Please note, that this operation
5631	is two phase, as real attachment will happen when VM will start,
5632	and most information will be delivered as IHostPCIDevicePlugEvent
5633	on IVirtualBox event source.
5634
5635	<see><link to="IHostPCIDevicePlugEvent"/></see>
5636
5637	<result name="VBOX_E_INVALID_VM_STATE">
5638	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5639	</result>
5640	<result name="VBOX_E_PDM_ERROR">
5641	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5642	</result>
5643	<result name="VBOX_E_NOT_SUPPORTED">
5644	Hardware or host OS doesn't allow PCI device passthrought.
5645	</result>
5646	</desc>
5647	<param name="hostAddress" type="long" dir="in">
5648	<desc>Address of the host PCI device.</desc>
5649	</param>
5650	<param name="desiredGuestAddress" type="long" dir="in">
5651	<desc>Desired position of this device on guest PCI bus.</desc>
5652	</param>
5653	<param name="tryToUnbind" type="boolean" dir="in">
5654	<desc>If VMM shall try to unbind existing drivers from the
5655	device before attaching it to the guest.</desc>
5656	</param>
5657	</method>
5658
5659	<method name="detachHostPCIDevice">
5660	<desc>
5661	Detach host PCI device from the virtual machine.
5662	Also HostPCIDevicePlugEvent on IVirtualBox event source
5663	will be delivered. As currently we don't support hot device
5664	unplug, IHostPCIDevicePlugEvent event is delivered immediately.
5665
5666	<see><link to="IHostPCIDevicePlugEvent"/></see>
5667
5668	<result name="VBOX_E_INVALID_VM_STATE">
5669	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5670	</result>
5671	<result name="VBOX_E_OBJECT_NOT_FOUND">
5672	This host device is not attached to this machine.
5673	</result>
5674	<result name="VBOX_E_PDM_ERROR">
5675	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5676	</result>
5677	<result name="VBOX_E_NOT_SUPPORTED">
5678	Hardware or host OS doesn't allow PCI device passthrought.
5679	</result>
5680	</desc>
5681	<param name="hostAddress" type="long" dir="in">
5682	<desc>Address of the host PCI device.</desc>
5683	</param>
5684	</method>
5685
5686	<method name="getNetworkAdapter" const="yes">
5687	<desc>
5688	Returns the network adapter associated with the given slot.
5689	Slots are numbered sequentially, starting with zero. The total
5690	number of adapters per machine is defined by the
5691	<link to="ISystemProperties::getMaxNetworkAdapters"/> property,
5692	so the maximum slot number is one less than that property's value.
5693
5694	<result name="E_INVALIDARG">
5695	Invalid @a slot number.
5696	</result>
5697
5698	</desc>
5699	<param name="slot" type="unsigned long" dir="in"/>
5700	<param name="adapter" type="INetworkAdapter" dir="return"/>
5701	</method>
5702
5703	<method name="addStorageController">
5704	<desc>
5705	Adds a new storage controller (SCSI, SAS or SATA controller) to the
5706	machine and returns it as an instance of
5707	<link to="IStorageController" />.
5708
5709	@a name identifies the controller for subsequent calls such as
5710	<link to="#getStorageControllerByName" />,
5711	<link to="#getStorageControllerByInstance" />,
5712	<link to="#removeStorageController" />,
5713	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5714
5715	After the controller has been added, you can set its exact
5716	type by setting the <link to="IStorageController::controllerType" />.
5717
5718	<result name="VBOX_E_OBJECT_IN_USE">
5719	A storage controller with given name exists already.
5720	</result>
5721	<result name="E_INVALIDARG">
5722	Invalid @a controllerType.
5723	</result>
5724	</desc>
5725	<param name="name" type="wstring" dir="in"/>
5726	<param name="connectionType" type="StorageBus" dir="in"/>
5727	<param name="controller" type="IStorageController" dir="return"/>
5728	</method>
5729
5730	<method name="getStorageControllerByName" const="yes">
5731	<desc>
5732	Returns a storage controller with the given name.
5733
5734	<result name="VBOX_E_OBJECT_NOT_FOUND">
5735	A storage controller with given name doesn't exist.
5736	</result>
5737	</desc>
5738	<param name="name" type="wstring" dir="in"/>
5739	<param name="storageController" type="IStorageController" dir="return"/>
5740	</method>
5741
5742	<method name="getStorageControllerByInstance" const="yes">
5743	<desc>
5744	Returns a storage controller with the given instance number.
5745
5746	<result name="VBOX_E_OBJECT_NOT_FOUND">
5747	A storage controller with given instance number doesn't exist.
5748	</result>
5749	</desc>
5750	<param name="instance" type="unsigned long" dir="in"/>
5751	<param name="storageController" type="IStorageController" dir="return"/>
5752	</method>
5753
5754	<method name="removeStorageController">
5755	<desc>
5756	Removes a storage controller from the machine with all devices attached to it.
5757
5758	<result name="VBOX_E_OBJECT_NOT_FOUND">
5759	A storage controller with given name doesn't exist.
5760	</result>
5761	<result name="VBOX_E_NOT_SUPPORTED">
5762	Medium format does not support storage deletion (only for implicitly
5763	created differencing media, should not happen).
5764	</result>
5765	</desc>
5766	<param name="name" type="wstring" dir="in"/>
5767	</method>
5768
5769	<method name="setStorageControllerBootable">
5770	<desc>
5771	Sets the bootable flag of the storage controller with the given name.
5772
5773	<result name="VBOX_E_OBJECT_NOT_FOUND">
5774	A storage controller with given name doesn't exist.
5775	</result>
5776	<result name="VBOX_E_OBJECT_IN_USE">
5777	Another storage controller is marked as bootable already.
5778	</result>
5779	</desc>
5780	<param name="name" type="wstring" dir="in"/>
5781	<param name="bootable" type="boolean" dir="in"/>
5782	</method>
5783
5784	<method name="getSerialPort" const="yes">
5785	<desc>
5786	Returns the serial port associated with the given slot.
5787	Slots are numbered sequentially, starting with zero. The total
5788	number of serial ports per machine is defined by the
5789	<link to="ISystemProperties::serialPortCount"/> property,
5790	so the maximum slot number is one less than that property's value.
5791
5792	<result name="E_INVALIDARG">
5793	Invalid @a slot number.
5794	</result>
5795
5796	</desc>
5797	<param name="slot" type="unsigned long" dir="in"/>
5798	<param name="port" type="ISerialPort" dir="return"/>
5799	</method>
5800
5801	<method name="getParallelPort" const="yes">
5802	<desc>
5803	Returns the parallel port associated with the given slot.
5804	Slots are numbered sequentially, starting with zero. The total
5805	number of parallel ports per machine is defined by the
5806	<link to="ISystemProperties::parallelPortCount"/> property,
5807	so the maximum slot number is one less than that property's value.
5808
5809	<result name="E_INVALIDARG">
5810	Invalid @a slot number.
5811	</result>
5812
5813	</desc>
5814	<param name="slot" type="unsigned long" dir="in"/>
5815	<param name="port" type="IParallelPort" dir="return"/>
5816	</method>
5817
5818	<method name="getExtraDataKeys">
5819	<desc>
5820	Returns an array representing the machine-specific extra data keys
5821	which currently have values defined.
5822	</desc>
5823	<param name="keys" type="wstring" dir="return" safearray="yes">
5824	<desc>Array of extra data keys.</desc>
5825	</param>
5826	</method>
5827
5828	<method name="getExtraData">
5829	<desc>
5830	Returns associated machine-specific extra data.
5831
5832	If the requested data @a key does not exist, this function will
5833	succeed and return an empty string in the @a value argument.
5834
5835	<result name="VBOX_E_FILE_ERROR">
5836	Settings file not accessible.
5837	</result>
5838	<result name="VBOX_E_XML_ERROR">
5839	Could not parse the settings file.
5840	</result>
5841
5842	</desc>
5843	<param name="key" type="wstring" dir="in">
5844	<desc>Name of the data key to get.</desc>
5845	</param>
5846	<param name="value" type="wstring" dir="return">
5847	<desc>Value of the requested data key.</desc>
5848	</param>
5849	</method>
5850
5851	<method name="setExtraData">
5852	<desc>
5853	Sets associated machine-specific extra data.
5854
5855	If you pass @c null or an empty string as a key @a value, the given
5856	@a key will be deleted.
5857
5858	<note>
5859	Before performing the actual data change, this method will ask all
5860	registered listeners using the
5861	<link to="IExtraDataCanChangeEvent"/>
5862	notification for a permission. If one of the listeners refuses the
5863	new value, the change will not be performed.
5864	</note>
5865	<note>
5866	On success, the
5867	<link to="IExtraDataChangedEvent"/> notification
5868	is called to inform all registered listeners about a successful data
5869	change.
5870	</note>
5871	<note>
5872	This method can be called outside the machine session and therefore
5873	it's a caller's responsibility to handle possible race conditions
5874	when several clients change the same key at the same time.
5875	</note>
5876
5877	<result name="VBOX_E_FILE_ERROR">
5878	Settings file not accessible.
5879	</result>
5880	<result name="VBOX_E_XML_ERROR">
5881	Could not parse the settings file.
5882	</result>
5883
5884	</desc>
5885	<param name="key" type="wstring" dir="in">
5886	<desc>Name of the data key to set.</desc>
5887	</param>
5888	<param name="value" type="wstring" dir="in">
5889	<desc>Value to assign to the key.</desc>
5890	</param>
5891	</method>
5892
5893	<method name="getCPUProperty" const="yes">
5894	<desc>
5895	Returns the virtual CPU boolean value of the specified property.
5896
5897	<result name="E_INVALIDARG">
5898	Invalid property.
5899	</result>
5900
5901	</desc>
5902	<param name="property" type="CPUPropertyType" dir="in">
5903	<desc>
5904	Property type to query.
5905	</desc>
5906	</param>
5907	<param name="value" type="boolean" dir="return">
5908	<desc>
5909	Property value.
5910	</desc>
5911	</param>
5912	</method>
5913
5914	<method name="setCPUProperty">
5915	<desc>
5916	Sets the virtual CPU boolean value of the specified property.
5917
5918	<result name="E_INVALIDARG">
5919	Invalid property.
5920	</result>
5921
5922	</desc>
5923	<param name="property" type="CPUPropertyType" dir="in">
5924	<desc>
5925	Property type to query.
5926	</desc>
5927	</param>
5928	<param name="value" type="boolean" dir="in">
5929	<desc>
5930	Property value.
5931	</desc>
5932	</param>
5933	</method>
5934
5935	<method name="getCPUIDLeaf" const="yes">
5936	<desc>
5937	Returns the virtual CPU cpuid information for the specified leaf.
5938
5939	Currently supported index values for cpuid:
5940	Standard CPUID leafs: 0 - 0xA
5941	Extended CPUID leafs: 0x80000000 - 0x8000000A
5942
5943	See the Intel and AMD programmer's manuals for detailed information
5944	about the cpuid instruction and its leafs.
5945	<result name="E_INVALIDARG">
5946	Invalid id.
5947	</result>
5948
5949	</desc>
5950	<param name="id" type="unsigned long" dir="in">
5951	<desc>
5952	CPUID leaf index.
5953	</desc>
5954	</param>
5955	<param name="valEax" type="unsigned long" dir="out">
5956	<desc>
5957	CPUID leaf value for register eax.
5958	</desc>
5959	</param>
5960	<param name="valEbx" type="unsigned long" dir="out">
5961	<desc>
5962	CPUID leaf value for register ebx.
5963	</desc>
5964	</param>
5965	<param name="valEcx" type="unsigned long" dir="out">
5966	<desc>
5967	CPUID leaf value for register ecx.
5968	</desc>
5969	</param>
5970	<param name="valEdx" type="unsigned long" dir="out">
5971	<desc>
5972	CPUID leaf value for register edx.
5973	</desc>
5974	</param>
5975	</method>
5976
5977	<method name="setCPUIDLeaf">
5978	<desc>
5979	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5980	are not passed unmodified. VirtualBox clears features that it doesn't support.
5981
5982	Currently supported index values for cpuid:
5983	Standard CPUID leafs: 0 - 0xA
5984	Extended CPUID leafs: 0x80000000 - 0x8000000A
5985
5986	See the Intel and AMD programmer's manuals for detailed information
5987	about the cpuid instruction and its leafs.
5988
5989	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5990	random crashes inside VMs.
5991	<result name="E_INVALIDARG">
5992	Invalid id.
5993	</result>
5994
5995	</desc>
5996	<param name="id" type="unsigned long" dir="in">
5997	<desc>
5998	CPUID leaf index.
5999	</desc>
6000	</param>
6001	<param name="valEax" type="unsigned long" dir="in">
6002	<desc>
6003	CPUID leaf value for register eax.
6004	</desc>
6005	</param>
6006	<param name="valEbx" type="unsigned long" dir="in">
6007	<desc>
6008	CPUID leaf value for register ebx.
6009	</desc>
6010	</param>
6011	<param name="valEcx" type="unsigned long" dir="in">
6012	<desc>
6013	CPUID leaf value for register ecx.
6014	</desc>
6015	</param>
6016	<param name="valEdx" type="unsigned long" dir="in">
6017	<desc>
6018	CPUID leaf value for register edx.
6019	</desc>
6020	</param>
6021	</method>
6022
6023	<method name="removeCPUIDLeaf">
6024	<desc>
6025	Removes the virtual CPU cpuid leaf for the specified index
6026
6027	<result name="E_INVALIDARG">
6028	Invalid id.
6029	</result>
6030
6031	</desc>
6032	<param name="id" type="unsigned long" dir="in">
6033	<desc>
6034	CPUID leaf index.
6035	</desc>
6036	</param>
6037	</method>
6038
6039	<method name="removeAllCPUIDLeaves">
6040	<desc>
6041	Removes all the virtual CPU cpuid leaves
6042	</desc>
6043	</method>
6044
6045	<method name="getHWVirtExProperty" const="yes">
6046	<desc>
6047	Returns the value of the specified hardware virtualization boolean property.
6048
6049	<result name="E_INVALIDARG">
6050	Invalid property.
6051	</result>
6052
6053	</desc>
6054	<param name="property" type="HWVirtExPropertyType" dir="in">
6055	<desc>
6056	Property type to query.
6057	</desc>
6058	</param>
6059	<param name="value" type="boolean" dir="return">
6060	<desc>
6061	Property value.
6062	</desc>
6063	</param>
6064	</method>
6065
6066	<method name="setHWVirtExProperty">
6067	<desc>
6068	Sets a new value for the specified hardware virtualization boolean property.
6069
6070	<result name="E_INVALIDARG">
6071	Invalid property.
6072	</result>
6073
6074	</desc>
6075	<param name="property" type="HWVirtExPropertyType" dir="in">
6076	<desc>
6077	Property type to set.
6078	</desc>
6079	</param>
6080	<param name="value" type="boolean" dir="in">
6081	<desc>
6082	New property value.
6083	</desc>
6084	</param>
6085	</method>
6086
6087	<method name="saveSettings">
6088	<desc>
6089	Saves any changes to machine settings made since the session
6090	has been opened or a new machine has been created, or since the
6091	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
6092	For registered machines, new settings become visible to all
6093	other VirtualBox clients after successful invocation of this
6094	method.
6095	<note>
6096	The method sends <link to="IMachineDataChangedEvent"/>
6097	notification event after the configuration has been successfully
6098	saved (only for registered machines).
6099	</note>
6100	<note>
6101	Calling this method is only valid on instances returned
6102	by <link to="ISession::machine"/> and on new machines
6103	created by <link to="IVirtualBox::createMachine"/> but not
6104	yet registered, or on unregistered machines after calling
6105	<link to="IMachine::unregister"/>.
6106	</note>
6107
6108	<result name="VBOX_E_FILE_ERROR">
6109	Settings file not accessible.
6110	</result>
6111	<result name="VBOX_E_XML_ERROR">
6112	Could not parse the settings file.
6113	</result>
6114	<result name="E_ACCESSDENIED">
6115	Modification request refused.
6116	</result>
6117
6118	</desc>
6119	</method>
6120
6121	<method name="discardSettings">
6122	<desc>
6123	Discards any changes to the machine settings made since the session
6124	has been opened or since the last call to <link to="#saveSettings"/>
6125	or <link to="#discardSettings"/>.
6126	<note>
6127	Calling this method is only valid on instances returned
6128	by <link to="ISession::machine"/> and on new machines
6129	created by <link to="IVirtualBox::createMachine"/> or
6130	opened by <link to="IVirtualBox::openMachine"/> but not
6131	yet registered, or on unregistered machines after calling
6132	<link to="IMachine::unregister"/>.
6133	</note>
6134
6135	<result name="VBOX_E_INVALID_VM_STATE">
6136	Virtual machine is not mutable.
6137	</result>
6138
6139	</desc>
6140	</method>
6141
6142	<method name="unregister">
6143	<desc>
6144	Unregisters a machine previously registered with
6145	<link to="IVirtualBox::registerMachine"/> and optionally do additional
6146	cleanup before the machine is unregistered.
6147
6148	This method does not delete any files. It only changes the machine configuration and
6149	the list of registered machines in the VirtualBox object. To delete the files which
6150	belonged to the machine, including the XML file of the machine itself, call
6151	<link to="#deleteConfig"/>, optionally with the array of IMedium objects which was returned
6152	from this method.
6153
6154	How thoroughly this method cleans up the machine configuration before unregistering
6155	the machine depends on the @a cleanupMode argument.
6156
6157	<ul>
6158	<li>With "UnregisterOnly", the machine will only be unregistered, but no additional
6159	cleanup will be performed. The call will fail if the machine is in "Saved" state
6160	or has any snapshots or any media attached (see <link to="IMediumAttachment" />).
6161	It is the responsibility of the caller to delete all such configuration in this mode.
6162	In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
6163	which it replaces.</li>
6164	<li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
6165	state or if it has snapshots or media attached. All media attached to the current machine
6166	state or in snapshots will be detached. No medium objects will be returned;
6167	all of the machine's media will remain open.</li>
6168	<li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
6169	except that all the hard disk medium objects which were detached from the machine will
6170	be returned as an array. This allows for quickly passing them to the <link to="#deleteConfig" />
6171	API for closing and deletion.</li>
6172	<li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
6173	that all media will be returned in the array, including removable media like DVDs and
6174	floppies. This might be useful if the user wants to inspect in detail which media were
6175	attached to the machine. Be careful when passing the media array to <link to="#deleteConfig" />
6176	in that case because users will typically want to preserve ISO and RAW image files.</li>
6177	</ul>
6178
6179	A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
6180	resulting IMedium array to <link to="#deleteConfig"/>. This way, the machine is completely
6181	deleted with all its saved states and hard disk images, but images for removable
6182	drives (such as ISO and RAW files) will remain on disk.
6183
6184	This API does not verify whether the media files returned in the array are still
6185	attached to other machines (i.e. shared between several machines). If such a shared
6186	image is passed to <link to="#deleteConfig" /> however, closing the image will fail there
6187	and the image will be silently skipped.
6188
6189	This API may, however, move media from this machine's media registry to other media
6190	registries (see <link to="IMedium" /> for details on media registries). For machines
6191	created with VirtualBox 4.0 or later, if media from this machine's media registry
6192	are also attached to another machine (shared attachments), each such medium will be
6193	moved to another machine's registry. This is because without this machine's media
6194	registry, the other machine cannot find its media any more and would become inaccessible.
6195
6196	This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
6197	before unregistering it. It may also silently call <link to="#saveSettings"/> on other machines
6198	if media are moved to other machines' media registries.
6199
6200	After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
6201	is fired.
6202
6203	The call will fail if the machine is currently locked (see <link to="ISession" />).
6204
6205	<note>
6206	If the given machine is inaccessible (see <link to="#accessible"/>), it
6207	will be unregistered and fully uninitialized right afterwards. As a result,
6208	the returned machine object will be unusable and an attempt to call
6209	<b>any</b> method will return the "Object not ready" error.
6210	</note>
6211
6212	<result name="VBOX_E_INVALID_OBJECT_STATE">
6213	Machine is currently locked for a session.
6214	</result>
6215	</desc>
6216
6217	<param name="cleanupMode" type="CleanupMode" dir="in">
6218	<desc>How to clean up after the machine has been unregistered.</desc>
6219	</param>
6220	<param name="media" type="IMedium" safearray="yes" dir="return">
6221	<desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
6222	</param>
6223	</method>
6224
6225	<method name="deleteConfig">
6226	<desc>
6227	Deletes the files associated with this machine from disk. If medium objects are passed
6228	in with the @a aMedia argument, they are closed and, if closing was successful, their
6229	storage files are deleted as well. For convenience, this array of media files can be
6230	the same as the one returned from a previous <link to="#unregister" /> call.
6231
6232	This method must only be called on machines which are either write-locked (i.e. on instances
6233	returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
6234	registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
6235	<link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
6236
6237	The following files will be deleted by this method:
6238	<ul>
6239	<li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
6240	argument other than "UnregisterOnly", this will delete all saved state files that
6241	the machine had in use; possibly one if the machine was in "Saved" state and one
6242	for each online snapshot that the machine had.</li>
6243	<li>On each medium object passed in the @a aMedia array, this will call
6244	<link to="IMedium::close" />. If that succeeds, this will attempt to delete the
6245	medium's storage on disk. Since the <link to="IMedium::close"/> call will fail if the medium is still
6246	in use, e.g. because it is still attached to a second machine; in that case the
6247	storage will not be deleted.</li>
6248	<li>Finally, the machine's own XML file will be deleted.</li>
6249	</ul>
6250
6251	Since deleting large disk image files can be a time-consuming I/O operation, this
6252	method operates asynchronously and returns an IProgress object to allow the caller
6253	to monitor the progress. There will be one sub-operation for each file that is
6254	being deleted (saved state or medium storage file).
6255
6256	<note>
6257	<link to="#settingsModified"/> will return @c true after this
6258	method successfully returns.
6259	</note>
6260
6261	<result name="VBOX_E_INVALID_VM_STATE">
6262	Machine is registered but not write-locked.
6263	</result>
6264	<result name="VBOX_E_IPRT_ERROR">
6265	Could not delete the settings file.
6266	</result>
6267	</desc>
6268	<param name="media" type="IMedium" safearray="yes" dir="in">
6269	<desc>List of media to be closed and whose storage files will be deleted.</desc>
6270	</param>
6271	<param name="progress" type="IProgress" dir="return">
6272	<desc>Progress object to track the operation completion.</desc>
6273	</param>
6274	</method>
6275
6276	<method name="exportTo">
6277	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
6278	steps required to export VirtualBox machines to OVF.
6279	</desc>
6280
6281	<param name="appliance" type="IAppliance" dir="in">
6282	<desc>Appliance to export this machine to.</desc>
6283	</param>
6284	<param name="location" type="wstring" dir="in">
6285	<desc>The target location.</desc>
6286	</param>
6287	<param name="description" type="IVirtualSystemDescription" dir="return">
6288	<desc>VirtualSystemDescription object which is created for this machine.</desc>
6289	</param>
6290	</method>
6291
6292	<method name="findSnapshot">
6293	<desc>
6294	Returns a snapshot of this machine with the given name or UUID.
6295
6296	Returns a snapshot of this machine with the given UUID.
6297	A @c null argument can be used to obtain the first snapshot
6298	taken on this machine. To traverse the whole tree of snapshots
6299	starting from the root, inspect the root snapshot's
6300	<link to="ISnapshot::children" /> attribute and recurse over those children.
6301
6302	<result name="VBOX_E_OBJECT_NOT_FOUND">
6303	Virtual machine has no snapshots or snapshot not found.
6304	</result>
6305
6306	</desc>
6307	<param name="nameOrId" type="wstring" dir="in">
6308	<desc>What to search for. Name or UUID of the snapshot to find</desc>
6309	</param>
6310	<param name="snapshot" type="ISnapshot" dir="return">
6311	<desc>Snapshot object with the given name.</desc>
6312	</param>
6313	</method>
6314
6315	<method name="createSharedFolder">
6316	<desc>
6317	Creates a new permanent shared folder by associating the given logical
6318	name with the given host path, adds it to the collection of shared
6319	folders and starts sharing it. Refer to the description of
6320	<link to="ISharedFolder"/> to read more about logical names.
6321
6322	<result name="VBOX_E_OBJECT_IN_USE">
6323	Shared folder already exists.
6324	</result>
6325	<result name="VBOX_E_FILE_ERROR">
6326	Shared folder @a hostPath not accessible.
6327	</result>
6328
6329	</desc>
6330	<param name="name" type="wstring" dir="in">
6331	<desc>Unique logical name of the shared folder.</desc>
6332	</param>
6333	<param name="hostPath" type="wstring" dir="in">
6334	<desc>Full path to the shared folder in the host file system.</desc>
6335	</param>
6336	<param name="writable" type="boolean" dir="in">
6337	<desc>Whether the share is writable or readonly.</desc>
6338	</param>
6339	<param name="automount" type="boolean" dir="in">
6340	<desc>Whether the share gets automatically mounted by the guest
6341	or not.</desc>
6342	</param>
6343	</method>
6344
6345	<method name="removeSharedFolder">
6346	<desc>
6347	Removes the permanent shared folder with the given name previously
6348	created by <link to="#createSharedFolder"/> from the collection of
6349	shared folders and stops sharing it.
6350
6351	<result name="VBOX_E_INVALID_VM_STATE">
6352	Virtual machine is not mutable.
6353	</result>
6354	<result name="VBOX_E_OBJECT_NOT_FOUND">
6355	Shared folder @a name does not exist.
6356	</result>
6357
6358	</desc>
6359	<param name="name" type="wstring" dir="in">
6360	<desc>Logical name of the shared folder to remove.</desc>
6361	</param>
6362	</method>
6363
6364	<method name="canShowConsoleWindow">
6365	<desc>
6366	Returns @c true if the VM console process can activate the
6367	console window and bring it to foreground on the desktop of
6368	the host PC.
6369	<note>
6370	This method will fail if a session for this machine is not
6371	currently open.
6372	</note>
6373
6374	<result name="VBOX_E_INVALID_VM_STATE">
6375	Machine session is not open.
6376	</result>
6377
6378	</desc>
6379	<param name="canShow" type="boolean" dir="return">
6380	<desc>
6381	@c true if the console window can be shown and @c false otherwise.
6382	</desc>
6383	</param>
6384	</method>
6385
6386	<method name="showConsoleWindow">
6387	<desc>
6388	Activates the console window and brings it to foreground on
6389	the desktop of the host PC. Many modern window managers on
6390	many platforms implement some sort of focus stealing
6391	prevention logic, so that it may be impossible to activate
6392	a window without the help of the currently active
6393	application. In this case, this method will return a non-zero
6394	identifier that represents the top-level window of the VM
6395	console process. The caller, if it represents a currently
6396	active process, is responsible to use this identifier (in a
6397	platform-dependent manner) to perform actual window
6398	activation.
6399	<note>
6400	This method will fail if a session for this machine is not
6401	currently open.
6402	</note>
6403
6404	<result name="VBOX_E_INVALID_VM_STATE">
6405	Machine session is not open.
6406	</result>
6407
6408	</desc>
6409	<param name="winId" type="long long" dir="return">
6410	<desc>
6411	Platform-dependent identifier of the top-level VM console
6412	window, or zero if this method has performed all actions
6413	necessary to implement the <i>show window</i> semantics for
6414	the given platform and/or VirtualBox front-end.
6415	</desc>
6416	</param>
6417	</method>
6418
6419	<method name="getGuestProperty" const="yes">
6420	<desc>
6421	Reads an entry from the machine's guest property store.
6422
6423	<result name="VBOX_E_INVALID_VM_STATE">
6424	Machine session is not open.
6425	</result>
6426
6427	</desc>
6428	<param name="name" type="wstring" dir="in">
6429	<desc>
6430	The name of the property to read.
6431	</desc>
6432	</param>
6433	<param name="value" type="wstring" dir="out">
6434	<desc>
6435	The value of the property. If the property does not exist then this
6436	will be empty.
6437	</desc>
6438	</param>
6439	<param name="timestamp" type="long long" dir="out">
6440	<desc>
6441	The time at which the property was last modified, as seen by the
6442	server process.
6443	</desc>
6444	</param>
6445	<param name="flags" type="wstring" dir="out">
6446	<desc>
6447	Additional property parameters, passed as a comma-separated list of
6448	"name=value" type entries.
6449	</desc>
6450	</param>
6451	</method>
6452
6453	<method name="getGuestPropertyValue" const="yes">
6454	<desc>
6455	Reads a value from the machine's guest property store.
6456
6457	<result name="VBOX_E_INVALID_VM_STATE">
6458	Machine session is not open.
6459	</result>
6460
6461	</desc>
6462	<param name="property" type="wstring" dir="in">
6463	<desc>
6464	The name of the property to read.
6465	</desc>
6466	</param>
6467	<param name="value" type="wstring" dir="return">
6468	<desc>
6469	The value of the property. If the property does not exist then this
6470	will be empty.
6471	</desc>
6472	</param>
6473	</method>
6474
6475	<method name="getGuestPropertyTimestamp" const="yes">
6476	<desc>
6477	Reads a property timestamp from the machine's guest property store.
6478
6479	<result name="VBOX_E_INVALID_VM_STATE">
6480	Machine session is not open.
6481	</result>
6482
6483	</desc>
6484	<param name="property" type="wstring" dir="in">
6485	<desc>
6486	The name of the property to read.
6487	</desc>
6488	</param>
6489	<param name="value" type="long long" dir="return">
6490	<desc>
6491	The timestamp. If the property does not exist then this will be
6492	empty.
6493	</desc>
6494	</param>
6495	</method>
6496
6497	<method name="setGuestProperty">
6498	<desc>
6499	Sets, changes or deletes an entry in the machine's guest property
6500	store.
6501
6502	<result name="E_ACCESSDENIED">
6503	Property cannot be changed.
6504	</result>
6505	<result name="E_INVALIDARG">
6506	Invalid @a flags.
6507	</result>
6508	<result name="VBOX_E_INVALID_VM_STATE">
6509	Virtual machine is not mutable or session not open.
6510	</result>
6511	<result name="VBOX_E_INVALID_OBJECT_STATE">
6512	Cannot set transient property when machine not running.
6513	</result>
6514
6515	</desc>
6516	<param name="property" type="wstring" dir="in">
6517	<desc>
6518	The name of the property to set, change or delete.
6519	</desc>
6520	</param>
6521	<param name="value" type="wstring" dir="in">
6522	<desc>
6523	The new value of the property to set, change or delete. If the
6524	property does not yet exist and value is non-empty, it will be
6525	created. If the value is @c null or empty, the property will be
6526	deleted if it exists.
6527	</desc>
6528	</param>
6529	<param name="flags" type="wstring" dir="in">
6530	<desc>
6531	Additional property parameters, passed as a comma-separated list of
6532	"name=value" type entries.
6533	</desc>
6534	</param>
6535	</method>
6536
6537	<method name="setGuestPropertyValue">
6538	<desc>
6539	Sets or changes a value in the machine's guest property
6540	store. The flags field will be left unchanged or created empty for a
6541	new property.
6542
6543	<result name="E_ACCESSDENIED">
6544	Property cannot be changed.
6545	</result>
6546	<result name="VBOX_E_INVALID_VM_STATE">
6547	Virtual machine is not mutable or session not open.
6548	</result>
6549	<result name="VBOX_E_INVALID_OBJECT_STATE">
6550	Cannot set transient property when machine not running.
6551	</result>
6552	</desc>
6553
6554	<param name="property" type="wstring" dir="in">
6555	<desc>
6556	The name of the property to set or change.
6557	</desc>
6558	</param>
6559	<param name="value" type="wstring" dir="in">
6560	<desc>
6561	The new value of the property to set or change. If the
6562	property does not yet exist and value is non-empty, it will be
6563	created.
6564	</desc>
6565	</param>
6566	</method>
6567
6568	<method name="deleteGuestProperty" const="yes">
6569	<desc>
6570	Deletes an entry from the machine's guest property store.
6571
6572	<result name="VBOX_E_INVALID_VM_STATE">
6573	Machine session is not open.
6574	</result>
6575
6576	</desc>
6577	<param name="name" type="wstring" dir="in">
6578	<desc>
6579	The name of the property to delete.
6580	</desc>
6581	</param>
6582	</method>
6583
6584	<method name="enumerateGuestProperties" const="yes">
6585	<desc>
6586	Return a list of the guest properties matching a set of patterns along
6587	with their values, time stamps and flags.
6588	</desc>
6589	<param name="patterns" type="wstring" dir="in">
6590	<desc>
6591	The patterns to match the properties against, separated by '\|'
6592	characters. If this is empty or @c null, all properties will match.
6593	</desc>
6594	</param>
6595	<param name="names" type="wstring" dir="out" safearray="yes">
6596	<desc>
6597	The names of the properties returned.
6598	</desc>
6599	</param>
6600	<param name="values" type="wstring" dir="out" safearray="yes">
6601	<desc>
6602	The values of the properties returned. The array entries match the
6603	corresponding entries in the @a name array.
6604	</desc>
6605	</param>
6606	<param name="timestamps" type="long long" dir="out" safearray="yes">
6607	<desc>
6608	The time stamps of the properties returned. The array entries match
6609	the corresponding entries in the @a name array.
6610	</desc>
6611	</param>
6612	<param name="flags" type="wstring" dir="out" safearray="yes">
6613	<desc>
6614	The flags of the properties returned. The array entries match the
6615	corresponding entries in the @a name array.
6616	</desc>
6617	</param>
6618	</method>
6619
6620	<method name="querySavedGuestScreenInfo" const="yes">
6621	<desc>
6622	Returns the guest dimensions from the saved state.
6623	</desc>
6624	<param name="screenId" type="unsigned long" dir="in">
6625	<desc>
6626	Saved guest screen to query info from.
6627	</desc>
6628	</param>
6629	<param name="originX" type="unsigned long" dir="out">
6630	<desc>
6631	The X position of the guest monitor top left corner.
6632	</desc>
6633	</param>
6634	<param name="originY" type="unsigned long" dir="out">
6635	<desc>
6636	The Y position of the guest monitor top left corner.
6637	</desc>
6638	</param>
6639	<param name="width" type="unsigned long" dir="out">
6640	<desc>
6641	Guest width at the time of the saved state was taken.
6642	</desc>
6643	</param>
6644	<param name="height" type="unsigned long" dir="out">
6645	<desc>
6646	Guest height at the time of the saved state was taken.
6647	</desc>
6648	</param>
6649	<param name="enabled" type="boolean" dir="out">
6650	<desc>
6651	Whether the monitor is enabled in the guest.
6652	</desc>
6653	</param>
6654	</method>
6655
6656	<method name="querySavedThumbnailSize">
6657	<desc>
6658	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
6659	</desc>
6660	<param name="screenId" type="unsigned long" dir="in">
6661	<desc>
6662	Saved guest screen to query info from.
6663	</desc>
6664	</param>
6665	<param name="size" type="unsigned long" dir="out">
6666	<desc>
6667	Size of buffer required to store the bitmap.
6668	</desc>
6669	</param>
6670	<param name="width" type="unsigned long" dir="out">
6671	<desc>
6672	Bitmap width.
6673	</desc>
6674	</param>
6675	<param name="height" type="unsigned long" dir="out">
6676	<desc>
6677	Bitmap height.
6678	</desc>
6679	</param>
6680	</method>
6681
6682	<method name="readSavedThumbnailToArray">
6683	<desc>
6684	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
6685	</desc>
6686	<param name="screenId" type="unsigned long" dir="in">
6687	<desc>
6688	Saved guest screen to read from.
6689	</desc>
6690	</param>
6691	<param name="BGR" type="boolean" dir="in">
6692	<desc>
6693	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
6694	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
6695	</desc>
6696	</param>
6697	<param name="width" type="unsigned long" dir="out">
6698	<desc>
6699	Bitmap width.
6700	</desc>
6701	</param>
6702	<param name="height" type="unsigned long" dir="out">
6703	<desc>
6704	Bitmap height.
6705	</desc>
6706	</param>
6707	<param name="data" type="octet" safearray="yes" dir="return">
6708	<desc>
6709	Array with resulting bitmap data.
6710	</desc>
6711	</param>
6712	</method>
6713
6714	<method name="readSavedThumbnailPNGToArray">
6715	<desc>
6716	Thumbnail in PNG format is retrieved to an array of bytes.
6717	</desc>
6718	<param name="screenId" type="unsigned long" dir="in">
6719	<desc>
6720	Saved guest screen to read from.
6721	</desc>
6722	</param>
6723	<param name="width" type="unsigned long" dir="out">
6724	<desc>
6725	Image width.
6726	</desc>
6727	</param>
6728	<param name="height" type="unsigned long" dir="out">
6729	<desc>
6730	Image height.
6731	</desc>
6732	</param>
6733	<param name="data" type="octet" dir="return" safearray="yes">
6734	<desc>
6735	Array with resulting PNG data.
6736	</desc>
6737	</param>
6738	</method>
6739
6740	<method name="querySavedScreenshotPNGSize">
6741	<desc>
6742	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
6743	</desc>
6744	<param name="screenId" type="unsigned long" dir="in">
6745	<desc>
6746	Saved guest screen to query info from.
6747	</desc>
6748	</param>
6749	<param name="size" type="unsigned long" dir="out">
6750	<desc>
6751	Size of buffer required to store the PNG binary data.
6752	</desc>
6753	</param>
6754	<param name="width" type="unsigned long" dir="out">
6755	<desc>
6756	Image width.
6757	</desc>
6758	</param>
6759	<param name="height" type="unsigned long" dir="out">
6760	<desc>
6761	Image height.
6762	</desc>
6763	</param>
6764	</method>
6765
6766	<method name="readSavedScreenshotPNGToArray">
6767	<desc>
6768	Screenshot in PNG format is retrieved to an array of bytes.
6769	</desc>
6770	<param name="screenId" type="unsigned long" dir="in">
6771	<desc>
6772	Saved guest screen to read from.
6773	</desc>
6774	</param>
6775	<param name="width" type="unsigned long" dir="out">
6776	<desc>
6777	Image width.
6778	</desc>
6779	</param>
6780	<param name="height" type="unsigned long" dir="out">
6781	<desc>
6782	Image height.
6783	</desc>
6784	</param>
6785	<param name="data" type="octet" dir="return" safearray="yes">
6786	<desc>
6787	Array with resulting PNG data.
6788	</desc>
6789	</param>
6790	</method>
6791
6792	<method name="hotPlugCPU">
6793	<desc>
6794	Plugs a CPU into the machine.
6795	</desc>
6796	<param name="cpu" type="unsigned long" dir="in">
6797	<desc>
6798	The CPU id to insert.
6799	</desc>
6800	</param>
6801	</method>
6802
6803	<method name="hotUnplugCPU">
6804	<desc>
6805	Removes a CPU from the machine.
6806	</desc>
6807	<param name="cpu" type="unsigned long" dir="in">
6808	<desc>
6809	The CPU id to remove.
6810	</desc>
6811	</param>
6812	</method>
6813
6814	<method name="getCPUStatus">
6815	<desc>
6816	Returns the current status of the given CPU.
6817	</desc>
6818	<param name="cpu" type="unsigned long" dir="in">
6819	<desc>
6820	The CPU id to check for.
6821	</desc>
6822	</param>
6823	<param name="attached" type="boolean" dir="return">
6824	<desc>
6825	Status of the CPU.
6826	</desc>
6827	</param>
6828	</method>
6829
6830	<method name="queryLogFilename">
6831	<desc>
6832	Queries for the VM log file name of an given index. Returns an empty
6833	string if a log file with that index doesn't exists.
6834	</desc>
6835	<param name="idx" type="unsigned long" dir="in">
6836	<desc>
6837	Which log file name to query. 0=current log file.
6838	</desc>
6839	</param>
6840	<param name="filename" type="wstring" dir="return">
6841	<desc>
6842	On return the full path to the log file or an empty string on error.
6843	</desc>
6844	</param>
6845	</method>
6846
6847	<method name="readLog">
6848	<desc>
6849	Reads the VM log file. The chunk size is limited, so even if you
6850	ask for a big piece there might be less data returned.
6851	</desc>
6852	<param name="idx" type="unsigned long" dir="in">
6853	<desc>
6854	Which log file to read. 0=current log file.
6855	</desc>
6856	</param>
6857	<param name="offset" type="long long" dir="in">
6858	<desc>
6859	Offset in the log file.
6860	</desc>
6861	</param>
6862	<param name="size" type="long long" dir="in">
6863	<desc>
6864	Chunk size to read in the log file.
6865	</desc>
6866	</param>
6867	<param name="data" type="octet" dir="return" safearray="yes">
6868	<desc>
6869	Data read from the log file. A data size of 0 means end of file
6870	if the requested chunk size was not 0. This is the unprocessed
6871	file data, i.e. the line ending style depends on the platform of
6872	the system the server is running on.
6873	</desc>
6874	</param>
6875	</method>
6876
6877	<method name="cloneTo">
6878	<desc>
6879	Creates a clone of this machine, either as a full clone (which means
6880	creating independent copies of the hard disk media, save states and so
6881	on), or as a linked clone (which uses its own differencing media,
6882	sharing the parent media with the source machine).
6883
6884	The target machine object must have been created previously with <link
6885	to="IVirtualBox::createMachine"/>, and all the settings will be
6886	transferred except the VM name and the hardware UUID. You can set the
6887	VM name and the new hardware UUID when creating the target machine. The
6888	network MAC addresses are newly created for all newtwork adapters. You
6889	can change that behaviour with the options parameter. The operation is
6890	performed asynchronously, so the machine object will be not be usable
6891	until the @a progress object signals completion.
6892
6893	<result name="E_INVALIDARG">
6894	@a target is @c null.
6895	</result>
6896	</desc>
6897
6898	<param name="target" type="IMachine" dir="in">
6899	<desc>Target machine object.</desc>
6900	</param>
6901	<param name="mode" type="CloneMode" dir="in">
6902	<desc>Which states should be cloned.</desc>
6903	</param>
6904	<param name="options" type="CloneOptions" dir="in" safearray="yes">
6905	<desc>Options for the cloning operation.</desc>
6906	</param>
6907	<param name="progress" type="IProgress" dir="return">
6908	<desc>Progress object to track the operation completion.</desc>
6909	</param>
6910	</method>
6911
6912	</interface>
6913
6914	<!--
6915	// IConsole
6916	/////////////////////////////////////////////////////////////////////////
6917	-->
6918
6919	<interface
6920	name="IVRDEServerInfo" extends="$unknown"
6921	uuid="714434a1-58c3-4aab-9049-7652c5df113b"
6922	wsmap="struct"
6923	>
6924	<desc>
6925	Contains information about the remote desktop (VRDE) server capabilities and status.
6926	This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
6927	</desc>
6928
6929	<attribute name="active" type="boolean" readonly="yes">
6930	<desc>
6931	Whether the remote desktop connection is active.
6932	</desc>
6933	</attribute>
6934
6935	<attribute name="port" type="long" readonly="yes">
6936	<desc>
6937	VRDE server port number. If this property is equal to <tt>0</tt>, then
6938	the VRDE server failed to start, usually because there are no free IP
6939	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
6940	server has not yet been started.
6941	</desc>
6942	</attribute>
6943
6944	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6945	<desc>
6946	How many times a client connected.
6947	</desc>
6948	</attribute>
6949
6950	<attribute name="beginTime" type="long long" readonly="yes">
6951	<desc>
6952	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6953	</desc>
6954	</attribute>
6955
6956	<attribute name="endTime" type="long long" readonly="yes">
6957	<desc>
6958	When the last connection was terminated or the current time, if
6959	connection is still active, in milliseconds since 1970-01-01 UTC.
6960	</desc>
6961	</attribute>
6962
6963	<attribute name="bytesSent" type="long long" readonly="yes">
6964	<desc>
6965	How many bytes were sent in last or current, if still active, connection.
6966	</desc>
6967	</attribute>
6968
6969	<attribute name="bytesSentTotal" type="long long" readonly="yes">
6970	<desc>
6971	How many bytes were sent in all connections.
6972	</desc>
6973	</attribute>
6974
6975	<attribute name="bytesReceived" type="long long" readonly="yes">
6976	<desc>
6977	How many bytes were received in last or current, if still active, connection.
6978	</desc>
6979	</attribute>
6980
6981	<attribute name="bytesReceivedTotal" type="long long" readonly="yes">
6982	<desc>
6983	How many bytes were received in all connections.
6984	</desc>
6985	</attribute>
6986
6987	<attribute name="user" type="wstring" readonly="yes">
6988	<desc>
6989	Login user name supplied by the client.
6990	</desc>
6991	</attribute>
6992
6993	<attribute name="domain" type="wstring" readonly="yes">
6994	<desc>
6995	Login domain name supplied by the client.
6996	</desc>
6997	</attribute>
6998
6999	<attribute name="clientName" type="wstring" readonly="yes">
7000	<desc>
7001	The client name supplied by the client.
7002	</desc>
7003	</attribute>
7004
7005	<attribute name="clientIP" type="wstring" readonly="yes">
7006	<desc>
7007	The IP address of the client.
7008	</desc>
7009	</attribute>
7010
7011	<attribute name="clientVersion" type="unsigned long" readonly="yes">
7012	<desc>
7013	The client software version number.
7014	</desc>
7015	</attribute>
7016
7017	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
7018	<desc>
7019	Public key exchange method used when connection was established.
7020	Values: 0 - RDP4 public key exchange scheme.
7021	1 - X509 certificates were sent to client.
7022	</desc>
7023	</attribute>
7024
7025	</interface>
7026
7027	<interface
7028	name="IConsole" extends="$unknown"
7029	uuid="db7ab4ca-2a3f-4183-9243-c1208da92392"
7030	wsmap="managed"
7031	>
7032	<desc>
7033	The IConsole interface represents an interface to control virtual
7034	machine execution.
7035
7036	A console object gets created when a machine has been locked for a
7037	particular session (client process) using <link to="IMachine::lockMachine" />
7038	or <link to="IMachine::launchVMProcess"/>. The console object can
7039	then be found in the session's <link to="ISession::console" /> attribute.
7040
7041	Methods of the IConsole interface allow the caller to query the current
7042	virtual machine execution state, pause the machine or power it down, save
7043	the machine state or take a snapshot, attach and detach removable media
7044	and so on.
7045
7046	<see><link to="ISession"/></see>
7047	</desc>
7048
7049	<attribute name="machine" type="IMachine" readonly="yes">
7050	<desc>
7051	Machine object for this console session.
7052	<note>
7053	This is a convenience property, it has the same value as
7054	<link to="ISession::machine"/> of the corresponding session
7055	object.
7056	</note>
7057	</desc>
7058	</attribute>
7059
7060	<attribute name="state" type="MachineState" readonly="yes">
7061	<desc>
7062	Current execution state of the machine.
7063	<note>
7064	This property always returns the same value as the corresponding
7065	property of the IMachine object for this console session.
7066	For the process that owns (executes) the VM, this is the
7067	preferable way of querying the VM state, because no IPC
7068	calls are made.
7069	</note>
7070	</desc>
7071	</attribute>
7072
7073	<attribute name="guest" type="IGuest" readonly="yes">
7074	<desc>Guest object.</desc>
7075	</attribute>
7076
7077	<attribute name="keyboard" type="IKeyboard" readonly="yes">
7078	<desc>
7079	Virtual keyboard object.
7080	<note>
7081	If the machine is not running, any attempt to use
7082	the returned object will result in an error.
7083	</note>
7084	</desc>
7085	</attribute>
7086
7087	<attribute name="mouse" type="IMouse" readonly="yes">
7088	<desc>
7089	Virtual mouse object.
7090	<note>
7091	If the machine is not running, any attempt to use
7092	the returned object will result in an error.
7093	</note>
7094	</desc>
7095	</attribute>
7096
7097	<attribute name="display" type="IDisplay" readonly="yes">
7098	<desc>Virtual display object.
7099	<note>
7100	If the machine is not running, any attempt to use
7101	the returned object will result in an error.
7102	</note>
7103	</desc>
7104	</attribute>
7105
7106	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
7107	<desc>Debugging interface.</desc>
7108	</attribute>
7109
7110	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
7111	<desc>
7112	Collection of USB devices currently attached to the virtual
7113	USB controller.
7114	<note>
7115	The collection is empty if the machine is not running.
7116	</note>
7117	</desc>
7118	</attribute>
7119
7120	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7121	<desc>
7122	List of USB devices currently attached to the remote VRDE client.
7123	Once a new device is physically attached to the remote host computer,
7124	it appears in this list and remains there until detached.
7125	</desc>
7126	</attribute>
7127
7128	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
7129	<desc>
7130	Collection of shared folders for the current session. These folders
7131	are called transient shared folders because they are available to the
7132	guest OS running inside the associated virtual machine only for the
7133	duration of the session (as opposed to
7134	<link to="IMachine::sharedFolders"/> which represent permanent shared
7135	folders). When the session is closed (e.g. the machine is powered down),
7136	these folders are automatically discarded.
7137
7138	New shared folders are added to the collection using
7139	<link to="#createSharedFolder"/>. Existing shared folders can be
7140	removed using <link to="#removeSharedFolder"/>.
7141	</desc>
7142	</attribute>
7143
7144	<attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
7145	<desc>
7146	Interface that provides information on Remote Desktop Extension (VRDE) connection.
7147	</desc>
7148	</attribute>
7149
7150	<attribute name="eventSource" type="IEventSource" readonly="yes">
7151	<desc>
7152	Event source for console events.
7153	</desc>
7154	</attribute>
7155
7156	<attribute name="attachedPCIDevices" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
7157	<desc>Array of PCI devices attached to this machine.</desc>
7158	</attribute>
7159
7160	<attribute name="useHostClipboard" type="boolean">
7161	<desc>
7162	Whether the guest clipboard should be connected to the host one or
7163	whether it should only be allowed access to the VRDE clipboard. This
7164	setting may not affect existing guest clipboard connections which
7165	are already connected to the host clipboard.
7166	</desc>
7167	</attribute>
7168
7169	<method name="powerUp">
7170	<desc>
7171	Starts the virtual machine execution using the current machine
7172	state (that is, its current execution state, current settings and
7173	current storage devices).
7174
7175	<note>
7176	This method is only useful for front-ends that want to actually
7177	execute virtual machines in their own process (like the VirtualBox
7178	or VBoxSDL front-ends). Unless you are intending to write such a
7179	front-end, do not call this method. If you simply want to
7180	start virtual machine execution using one of the existing front-ends
7181	(for example the VirtualBox GUI or headless server), use
7182	<link to="IMachine::launchVMProcess"/> instead; these
7183	front-ends will power up the machine automatically for you.
7184	</note>
7185
7186	If the machine is powered off or aborted, the execution will
7187	start from the beginning (as if the real hardware were just
7188	powered on).
7189
7190	If the machine is in the <link to="MachineState_Saved"/> state,
7191	it will continue its execution the point where the state has
7192	been saved.
7193
7194	If the machine <link to="IMachine::teleporterEnabled"/> property is
7195	enabled on the machine being powered up, the machine will wait for an
7196	incoming teleportation in the <link to="MachineState_TeleportingIn"/>
7197	state. The returned progress object will have at least three
7198	operations where the last three are defined as: (1) powering up and
7199	starting TCP server, (2) waiting for incoming teleportations, and
7200	(3) perform teleportation. These operations will be reflected as the
7201	last three operations of the progress objected returned by
7202	<link to="IMachine::launchVMProcess"/> as well.
7203
7204	<see><link to="#saveState"/></see>
7205
7206	<result name="VBOX_E_INVALID_VM_STATE">
7207	Virtual machine already running.
7208	</result>
7209	<result name="VBOX_E_HOST_ERROR">
7210	Host interface does not exist or name not set.
7211	</result>
7212	<result name="VBOX_E_FILE_ERROR">
7213	Invalid saved state file.
7214	</result>
7215	</desc>
7216	<param name="progress" type="IProgress" dir="return">
7217	<desc>Progress object to track the operation completion.</desc>
7218	</param>
7219	</method>
7220
7221	<method name="powerUpPaused">
7222	<desc>
7223	Identical to powerUp except that the VM will enter the
7224	<link to="MachineState_Paused"/> state, instead of
7225	<link to="MachineState_Running"/>.
7226
7227	<see><link to="#powerUp"/></see>
7228	<result name="VBOX_E_INVALID_VM_STATE">
7229	Virtual machine already running.
7230	</result>
7231	<result name="VBOX_E_HOST_ERROR">
7232	Host interface does not exist or name not set.
7233	</result>
7234	<result name="VBOX_E_FILE_ERROR">
7235	Invalid saved state file.
7236	</result>
7237	</desc>
7238	<param name="progress" type="IProgress" dir="return">
7239	<desc>Progress object to track the operation completion.</desc>
7240	</param>
7241	</method>
7242
7243	<method name="powerDown">
7244	<desc>
7245	Initiates the power down procedure to stop the virtual machine
7246	execution.
7247
7248	The completion of the power down procedure is tracked using the returned
7249	IProgress object. After the operation is complete, the machine will go
7250	to the PoweredOff state.
7251	<result name="VBOX_E_INVALID_VM_STATE">
7252	Virtual machine must be Running, Paused or Stuck to be powered down.
7253	</result>
7254	</desc>
7255	<param name="progress" type="IProgress" dir="return">
7256	<desc>Progress object to track the operation completion.</desc>
7257	</param>
7258	</method>
7259
7260	<method name="reset">
7261	<desc>Resets the virtual machine.
7262	<result name="VBOX_E_INVALID_VM_STATE">
7263	Virtual machine not in Running state.
7264	</result>
7265	<result name="VBOX_E_VM_ERROR">
7266	Virtual machine error in reset operation.
7267	</result>
7268	</desc>
7269	</method>
7270
7271	<method name="pause">
7272	<desc>Pauses the virtual machine execution.
7273	<result name="VBOX_E_INVALID_VM_STATE">
7274	Virtual machine not in Running state.
7275	</result>
7276	<result name="VBOX_E_VM_ERROR">
7277	Virtual machine error in suspend operation.
7278	</result>
7279	</desc>
7280	</method>
7281
7282	<method name="resume">
7283	<desc>Resumes the virtual machine execution.
7284	<result name="VBOX_E_INVALID_VM_STATE">
7285	Virtual machine not in Paused state.
7286	</result>
7287	<result name="VBOX_E_VM_ERROR">
7288	Virtual machine error in resume operation.
7289	</result>
7290	</desc>
7291	</method>
7292
7293	<method name="powerButton">
7294	<desc>Sends the ACPI power button event to the guest.
7295	<result name="VBOX_E_INVALID_VM_STATE">
7296	Virtual machine not in Running state.
7297	</result>
7298	<result name="VBOX_E_PDM_ERROR">
7299	Controlled power off failed.
7300	</result>
7301	</desc>
7302	</method>
7303
7304	<method name="sleepButton">
7305	<desc>Sends the ACPI sleep button event to the guest.
7306	<result name="VBOX_E_INVALID_VM_STATE">
7307	Virtual machine not in Running state.
7308	</result>
7309	<result name="VBOX_E_PDM_ERROR">
7310	Sending sleep button event failed.
7311	</result>
7312	</desc>
7313	</method>
7314
7315	<method name="getPowerButtonHandled">
7316	<desc>Checks if the last power button event was handled by guest.
7317	<result name="VBOX_E_PDM_ERROR">
7318	Checking if the event was handled by the guest OS failed.
7319	</result>
7320	</desc>
7321	<param name="handled" type="boolean" dir="return"/>
7322	</method>
7323
7324	<method name="getGuestEnteredACPIMode">
7325	<desc>Checks if the guest entered the ACPI mode G0 (working) or
7326	G1 (sleeping). If this method returns @c false, the guest will
7327	most likely not respond to external ACPI events.
7328	<result name="VBOX_E_INVALID_VM_STATE">
7329	Virtual machine not in Running state.
7330	</result>
7331	</desc>
7332	<param name="entered" type="boolean" dir="return"/>
7333	</method>
7334
7335	<method name="saveState">
7336	<desc>
7337	Saves the current execution state of a running virtual machine
7338	and stops its execution.
7339
7340	After this operation completes, the machine will go to the
7341	Saved state. Next time it is powered up, this state will
7342	be restored and the machine will continue its execution from
7343	the place where it was saved.
7344
7345	This operation differs from taking a snapshot to the effect
7346	that it doesn't create new differencing media. Also, once
7347	the machine is powered up from the state saved using this method,
7348	the saved state is deleted, so it will be impossible to return
7349	to this state later.
7350
7351	<note>
7352	On success, this method implicitly calls
7353	<link to="IMachine::saveSettings"/> to save all current machine
7354	settings (including runtime changes to the DVD medium, etc.).
7355	Together with the impossibility to change any VM settings when it is
7356	in the Saved state, this guarantees adequate hardware
7357	configuration of the machine when it is restored from the saved
7358	state file.
7359	</note>
7360
7361	<note>
7362	The machine must be in the Running or Paused state, otherwise
7363	the operation will fail.
7364	</note>
7365	<result name="VBOX_E_INVALID_VM_STATE">
7366	Virtual machine state neither Running nor Paused.
7367	</result>
7368	<result name="VBOX_E_FILE_ERROR">
7369	Failed to create directory for saved state file.
7370	</result>
7371
7372	<see><link to="#takeSnapshot"/></see>
7373	</desc>
7374	<param name="progress" type="IProgress" dir="return">
7375	<desc>Progress object to track the operation completion.</desc>
7376	</param>
7377	</method>
7378
7379	<method name="adoptSavedState">
7380	<desc>
7381	Associates the given saved state file to the virtual machine.
7382
7383	On success, the machine will go to the Saved state. Next time it is
7384	powered up, it will be restored from the adopted saved state and
7385	continue execution from the place where the saved state file was
7386	created.
7387
7388	The specified saved state file path may be absolute or relative to the
7389	folder the VM normally saves the state to (usually,
7390	<link to="IMachine::snapshotFolder"/>).
7391
7392	<note>
7393	It's a caller's responsibility to make sure the given saved state
7394	file is compatible with the settings of this virtual machine that
7395	represent its virtual hardware (memory size, storage disk configuration
7396	etc.). If there is a mismatch, the behavior of the virtual machine
7397	is undefined.
7398	</note>
7399	<result name="VBOX_E_INVALID_VM_STATE">
7400	Virtual machine state neither PoweredOff nor Aborted.
7401	</result>
7402	</desc>
7403	<param name="savedStateFile" type="wstring" dir="in">
7404	<desc>Path to the saved state file to adopt.</desc>
7405	</param>
7406	</method>
7407
7408	<method name="discardSavedState">
7409	<desc>
7410	Forcibly resets the machine to "Powered Off" state if it is
7411	currently in the "Saved" state (previously created by <link to="#saveState"/>).
7412	Next time the machine is powered up, a clean boot will occur.
7413	<note>
7414	This operation is equivalent to resetting or powering off
7415	the machine without doing a proper shutdown of the guest
7416	operating system; as with resetting a running phyiscal
7417	computer, it can can lead to data loss.
7418	</note>
7419	If @a fRemoveFile is @c true, the file in the machine directory
7420	into which the machine state was saved is also deleted. If
7421	this is @c false, then the state can be recovered and later
7422	re-inserted into a machine using <link to="#adoptSavedState" />.
7423	The location of the file can be found in the
7424	<link to="IMachine::stateFilePath" /> attribute.
7425	<result name="VBOX_E_INVALID_VM_STATE">
7426	Virtual machine not in state Saved.
7427	</result>
7428	</desc>
7429	<param name="fRemoveFile" type="boolean" dir="in" >
7430	<desc>Whether to also remove the saved state file.</desc>
7431	</param>
7432	</method>
7433
7434	<method name="getDeviceActivity">
7435	<desc>
7436	Gets the current activity type of a given device or device group.
7437	<result name="E_INVALIDARG">
7438	Invalid device type.
7439	</result>
7440	</desc>
7441	<param name="type" type="DeviceType" dir="in"/>
7442	<param name="activity" type="DeviceActivity" dir="return"/>
7443	</method>
7444
7445	<method name="attachUSBDevice">
7446	<desc>
7447	Attaches a host USB device with the given UUID to the
7448	USB controller of the virtual machine.
7449
7450	The device needs to be in one of the following states:
7451	<link to="USBDeviceState_Busy"/>,
7452	<link to="USBDeviceState_Available"/> or
7453	<link to="USBDeviceState_Held"/>,
7454	otherwise an error is immediately returned.
7455
7456	When the device state is
7457	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7458	be returned if the host computer refuses to release it for some reason.
7459
7460	<see><link to="IUSBController::deviceFilters"/>,
7461	<link to="USBDeviceState"/></see>
7462	<result name="VBOX_E_INVALID_VM_STATE">
7463	Virtual machine state neither Running nor Paused.
7464	</result>
7465	<result name="VBOX_E_PDM_ERROR">
7466	Virtual machine does not have a USB controller.
7467	</result>
7468	</desc>
7469	<param name="id" type="uuid" mod="string" dir="in">
7470	<desc>UUID of the host USB device to attach.</desc>
7471	</param>
7472	</method>
7473
7474	<method name="detachUSBDevice">
7475	<desc>
7476	Detaches an USB device with the given UUID from the USB controller
7477	of the virtual machine.
7478
7479	After this method succeeds, the VirtualBox server re-initiates
7480	all USB filters as if the device were just physically attached
7481	to the host, but filters of this machine are ignored to avoid
7482	a possible automatic re-attachment.
7483
7484	<see><link to="IUSBController::deviceFilters"/>,
7485	<link to="USBDeviceState"/></see>
7486
7487	<result name="VBOX_E_PDM_ERROR">
7488	Virtual machine does not have a USB controller.
7489	</result>
7490	<result name="E_INVALIDARG">
7491	USB device not attached to this virtual machine.
7492	</result>
7493	</desc>
7494	<param name="id" type="uuid" mod="string" dir="in">
7495	<desc>UUID of the USB device to detach.</desc>
7496	</param>
7497	<param name="device" type="IUSBDevice" dir="return">
7498	<desc>Detached USB device.</desc>
7499	</param>
7500	</method>
7501
7502	<method name="findUSBDeviceByAddress">
7503	<desc>
7504	Searches for a USB device with the given host address.
7505
7506	<result name="VBOX_E_OBJECT_NOT_FOUND">
7507	Given @c name does not correspond to any USB device.
7508	</result>
7509
7510	<see><link to="IUSBDevice::address"/></see>
7511	</desc>
7512	<param name="name" type="wstring" dir="in">
7513	<desc>
7514	Address of the USB device (as assigned by the host) to
7515	search for.
7516	</desc>
7517	</param>
7518	<param name="device" type="IUSBDevice" dir="return">
7519	<desc>Found USB device object.</desc>
7520	</param>
7521	</method>
7522
7523	<method name="findUSBDeviceById">
7524	<desc>
7525	Searches for a USB device with the given UUID.
7526
7527	<result name="VBOX_E_OBJECT_NOT_FOUND">
7528	Given @c id does not correspond to any USB device.
7529	</result>
7530
7531	<see><link to="IUSBDevice::id"/></see>
7532	</desc>
7533	<param name="id" type="uuid" mod="string" dir="in">
7534	<desc>UUID of the USB device to search for.</desc>
7535	</param>
7536	<param name="device" type="IUSBDevice" dir="return">
7537	<desc>Found USB device object.</desc>
7538	</param>
7539	</method>
7540
7541	<method name="createSharedFolder">
7542	<desc>
7543	Creates a transient new shared folder by associating the given logical
7544	name with the given host path, adds it to the collection of shared
7545	folders and starts sharing it. Refer to the description of
7546	<link to="ISharedFolder"/> to read more about logical names.
7547
7548	<result name="VBOX_E_INVALID_VM_STATE">
7549	Virtual machine in Saved state or currently changing state.
7550	</result>
7551	<result name="VBOX_E_FILE_ERROR">
7552	Shared folder already exists or not accessible.
7553	</result>
7554	</desc>
7555	<param name="name" type="wstring" dir="in">
7556	<desc>Unique logical name of the shared folder.</desc>
7557	</param>
7558	<param name="hostPath" type="wstring" dir="in">
7559	<desc>Full path to the shared folder in the host file system.</desc>
7560	</param>
7561	<param name="writable" type="boolean" dir="in">
7562	<desc>Whether the share is writable or readonly</desc>
7563	</param>
7564	<param name="automount" type="boolean" dir="in">
7565	<desc>Whether the share gets automatically mounted by the guest
7566	or not.</desc>
7567	</param>
7568	</method>
7569
7570	<method name="removeSharedFolder">
7571	<desc>
7572	Removes a transient shared folder with the given name previously
7573	created by <link to="#createSharedFolder"/> from the collection of
7574	shared folders and stops sharing it.
7575	<result name="VBOX_E_INVALID_VM_STATE">
7576	Virtual machine in Saved state or currently changing state.
7577	</result>
7578	<result name="VBOX_E_FILE_ERROR">
7579	Shared folder does not exists.
7580	</result>
7581	</desc>
7582	<param name="name" type="wstring" dir="in">
7583	<desc>Logical name of the shared folder to remove.</desc>
7584	</param>
7585	</method>
7586
7587	<method name="takeSnapshot">
7588	<desc>
7589	Saves the current execution state
7590	and all settings of the machine and creates differencing images
7591	for all normal (non-independent) media.
7592	See <link to="ISnapshot" /> for an introduction to snapshots.
7593
7594	This method can be called for a PoweredOff, Saved (see
7595	<link to="#saveState"/>), Running or
7596	Paused virtual machine. When the machine is PoweredOff, an
7597	offline snapshot is created. When the machine is Running a live
7598	snapshot is created, and an online snapshot is created when Paused.
7599
7600	The taken snapshot is always based on the
7601	<link to="IMachine::currentSnapshot">current snapshot</link>
7602	of the associated virtual machine and becomes a new current snapshot.
7603
7604	<note>
7605	This method implicitly calls <link to="IMachine::saveSettings"/> to
7606	save all current machine settings before taking an offline snapshot.
7607	</note>
7608
7609	<result name="VBOX_E_INVALID_VM_STATE">
7610	Virtual machine currently changing state.
7611	</result>
7612	</desc>
7613	<param name="name" type="wstring" dir="in">
7614	<desc>Short name for the snapshot.</desc>
7615	</param>
7616	<param name="description" type="wstring" dir="in">
7617	<desc>Optional description of the snapshot.</desc>
7618	</param>
7619	<param name="progress" type="IProgress" dir="return">
7620	<desc>Progress object to track the operation completion.</desc>
7621	</param>
7622	</method>
7623
7624	<method name="deleteSnapshot">
7625	<desc>
7626	Starts deleting the specified snapshot asynchronously.
7627	See <link to="ISnapshot" /> for an introduction to snapshots.
7628
7629	The execution state and settings of the associated machine stored in
7630	the snapshot will be deleted. The contents of all differencing media of
7631	this snapshot will be merged with the contents of their dependent child
7632	media to keep the medium chain valid (in other words, all changes
7633	represented by media being deleted will be propagated to their child
7634	medium). After that, this snapshot's differencing medium will be
7635	deleted. The parent of this snapshot will become a new parent for all
7636	its child snapshots.
7637
7638	If the deleted snapshot is the current one, its parent snapshot will
7639	become a new current snapshot. The current machine state is not directly
7640	affected in this case, except that currently attached differencing
7641	media based on media of the deleted snapshot will be also merged as
7642	described above.
7643
7644	If the deleted snapshot is the first or current snapshot, then the
7645	respective IMachine attributes will be adjusted. Deleting the current
7646	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7647	to make all current machine settings permanent.
7648
7649	Deleting a snapshot has the following preconditions:
7650
7651	<ul>
7652	<li>Child media of all normal media of the deleted snapshot
7653	must be accessible (see <link to="IMedium::state"/>) for this
7654	operation to succeed. If only one running VM refers to all images
7655	which participates in merging the operation can be performed while
7656	the VM is running. Otherwise all virtual machines whose media are
7657	directly or indirectly based on the media of deleted snapshot must
7658	be powered off. In any case, online snapshot deleting usually is
7659	slower than the same operation without any running VM.</li>
7660
7661	<li>You cannot delete the snapshot if a medium attached to it has
7662	more than one child medium (differencing images) because otherwise
7663	merging would be impossible. This might be the case if there is
7664	more than one child snapshot or differencing images were created
7665	for other reason (e.g. implicitly because of multiple machine
7666	attachments).</li>
7667	</ul>
7668
7669	The virtual machine's <link to="IMachine::state">state</link> is
7670	changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
7671	"DeletingSnapshotPaused" while this operation is in progress.
7672
7673	<note>
7674	Merging medium contents can be very time and disk space
7675	consuming, if these media are big in size and have many
7676	children. However, if the snapshot being deleted is the last
7677	(head) snapshot on the branch, the operation will be rather
7678	quick.
7679	</note>
7680	<result name="VBOX_E_INVALID_VM_STATE">
7681	The running virtual machine prevents deleting this snapshot. This
7682	happens only in very specific situations, usually snapshots can be
7683	deleted without trouble while a VM is running. The error message
7684	text explains the reason for the failure.
7685	</result>
7686	</desc>
7687	<param name="id" type="uuid" mod="string" dir="in">
7688	<desc>UUID of the snapshot to delete.</desc>
7689	</param>
7690	<param name="progress" type="IProgress" dir="return">
7691	<desc>Progress object to track the operation completion.</desc>
7692	</param>
7693	</method>
7694
7695	<method name="deleteSnapshotAndAllChildren">
7696	<desc>
7697	Starts deleting the specified snapshot and all its children
7698	asynchronously. See <link to="ISnapshot" /> for an introduction to
7699	snapshots. The conditions and many details are the same as with
7700	<link to="#deleteSnapshot"/>.
7701
7702	This operation is very fast if the snapshot subtree does not include
7703	the current state. It is still significantly faster than deleting the
7704	snapshots one by one if the current state is in the subtree and there
7705	are more than one snapshots from current state to the snapshot which
7706	marks the subtree, since it eliminates the incremental image merging.
7707
7708	<note>This API method is right now not implemented!</note>
7709
7710	<result name="VBOX_E_INVALID_VM_STATE">
7711	The running virtual machine prevents deleting this snapshot. This
7712	happens only in very specific situations, usually snapshots can be
7713	deleted without trouble while a VM is running. The error message
7714	text explains the reason for the failure.
7715	</result>
7716	<result name="E_NOTIMPL">
7717	The method is not implemented yet.
7718	</result>
7719	</desc>
7720	<param name="id" type="uuid" mod="string" dir="in">
7721	<desc>UUID of the snapshot to delete, including all its children.</desc>
7722	</param>
7723	<param name="progress" type="IProgress" dir="return">
7724	<desc>Progress object to track the operation completion.</desc>
7725	</param>
7726	</method>
7727
7728	<method name="deleteSnapshotRange">
7729	<desc>
7730	Starts deleting the specified snapshot range. This is limited to
7731	linear snapshot lists, which means there may not be any other child
7732	snapshots other than the direct sequence between the start and end
7733	snapshot. If the start and end snapshot point to the same snapshot this
7734	method is completely equivalent to <link to="#deleteSnapshot"/>. See
7735	<link to="ISnapshot" /> for an introduction to snapshots. The
7736	conditions and many details are the same as with
7737	<link to="#deleteSnapshot"/>.
7738
7739	This operation is generally faster than deleting snapshots one by one
7740	and often also needs less extra disk space before freeing up disk space
7741	by deleting the removed disk images corresponding to the snapshot.
7742
7743	<note>This API method is right now not implemented!</note>
7744
7745	<result name="VBOX_E_INVALID_VM_STATE">
7746	The running virtual machine prevents deleting this snapshot. This
7747	happens only in very specific situations, usually snapshots can be
7748	deleted without trouble while a VM is running. The error message
7749	text explains the reason for the failure.
7750	</result>
7751	<result name="E_NOTIMPL">
7752	The method is not implemented yet.
7753	</result>
7754	</desc>
7755	<param name="startId" type="uuid" mod="string" dir="in">
7756	<desc>UUID of the first snapshot to delete.</desc>
7757	</param>
7758	<param name="endId" type="uuid" mod="string" dir="in">
7759	<desc>UUID of the last snapshot to delete.</desc>
7760	</param>
7761	<param name="progress" type="IProgress" dir="return">
7762	<desc>Progress object to track the operation completion.</desc>
7763	</param>
7764	</method>
7765
7766	<method name="restoreSnapshot">
7767	<desc>
7768	Starts resetting the machine's current state to the state contained
7769	in the given snapshot, asynchronously. All current settings of the
7770	machine will be reset and changes stored in differencing media
7771	will be lost.
7772	See <link to="ISnapshot" /> for an introduction to snapshots.
7773
7774	After this operation is successfully completed, new empty differencing
7775	media are created for all normal media of the machine.
7776
7777	If the given snapshot is an online snapshot, the machine will go to
7778	the <link to="MachineState_Saved"> saved state</link>, so that the
7779	next time it is powered on, the execution state will be restored
7780	from the state of the snapshot.
7781
7782	<note>
7783	The machine must not be running, otherwise the operation will fail.
7784	</note>
7785
7786	<note>
7787	If the machine state is <link to="MachineState_Saved">Saved</link>
7788	prior to this operation, the saved state file will be implicitly
7789	deleted (as if <link to="IConsole::discardSavedState"/> were
7790	called).
7791	</note>
7792
7793	<result name="VBOX_E_INVALID_VM_STATE">
7794	Virtual machine is running.
7795	</result>
7796	</desc>
7797	<param name="snapshot" type="ISnapshot" dir="in">
7798	<desc>The snapshot to restore the VM state from.</desc>
7799	</param>
7800	<param name="progress" type="IProgress" dir="return">
7801	<desc>Progress object to track the operation completion.</desc>
7802	</param>
7803	</method>
7804
7805	<method name="teleport">
7806	<desc>
7807	Teleport the VM to a different host machine or process.
7808
7809	TODO explain the details.
7810
7811	<result name="VBOX_E_INVALID_VM_STATE">
7812	Virtual machine not running or paused.
7813	</result>
7814	</desc>
7815	<param name="hostname" type="wstring" dir="in">
7816	<desc>The name or IP of the host to teleport to.</desc>
7817	</param>
7818	<param name="tcpport" type="unsigned long" dir="in">
7819	<desc>The TCP port to connect to (1..65535).</desc>
7820	</param>
7821	<param name="password" type="wstring" dir="in">
7822	<desc>The password.</desc>
7823	</param>
7824	<param name="maxDowntime" type="unsigned long" dir="in">
7825	<desc>
7826	The maximum allowed downtime given as milliseconds. 0 is not a valid
7827	value. Recommended value: 250 ms.
7828
7829	The higher the value is, the greater the chance for a successful
7830	teleportation. A small value may easily result in the teleportation
7831	process taking hours and eventually fail.
7832
7833	<note>
7834	The current implementation treats this a guideline, not as an
7835	absolute rule.
7836	</note>
7837	</desc>
7838	</param>
7839	<param name="progress" type="IProgress" dir="return">
7840	<desc>Progress object to track the operation completion.</desc>
7841	</param>
7842	</method>
7843
7844	</interface>
7845
7846	<!--
7847	// IHost
7848	/////////////////////////////////////////////////////////////////////////
7849	-->
7850
7851	<enum
7852	name="HostNetworkInterfaceMediumType"
7853	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7854	>
7855	<desc>
7856	Type of encapsulation. Ethernet encapsulation includes both wired and
7857	wireless Ethernet connections.
7858	<see><link to="IHostNetworkInterface"/></see>
7859	</desc>
7860
7861	<const name="Unknown" value="0">
7862	<desc>
7863	The type of interface cannot be determined.
7864	</desc>
7865	</const>
7866	<const name="Ethernet" value="1">
7867	<desc>
7868	Ethernet frame encapsulation.
7869	</desc>
7870	</const>
7871	<const name="PPP" value="2">
7872	<desc>
7873	Point-to-point protocol encapsulation.
7874	</desc>
7875	</const>
7876	<const name="SLIP" value="3">
7877	<desc>
7878	Serial line IP encapsulation.
7879	</desc>
7880	</const>
7881	</enum>
7882
7883	<enum
7884	name="HostNetworkInterfaceStatus"
7885	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7886	>
7887	<desc>
7888	Current status of the interface.
7889	<see><link to="IHostNetworkInterface"/></see>
7890	</desc>
7891
7892	<const name="Unknown" value="0">
7893	<desc>
7894	The state of interface cannot be determined.
7895	</desc>
7896	</const>
7897	<const name="Up" value="1">
7898	<desc>
7899	The interface is fully operational.
7900	</desc>
7901	</const>
7902	<const name="Down" value="2">
7903	<desc>
7904	The interface is not functioning.
7905	</desc>
7906	</const>
7907	</enum>
7908
7909	<enum
7910	name="HostNetworkInterfaceType"
7911	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7912	>
7913	<desc>
7914	Network interface type.
7915	</desc>
7916	<const name="Bridged" value="1"/>
7917	<const name="HostOnly" value="2"/>
7918	</enum>
7919
7920	<interface
7921	name="IHostNetworkInterface" extends="$unknown"
7922	uuid="87a4153d-6889-4dd6-9654-2e9ff0ae8dec"
7923	wsmap="managed"
7924	>
7925	<desc>
7926	Represents one of host's network interfaces. IP V6 address and network
7927	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7928	separated by colons.
7929	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7930	</desc>
7931	<attribute name="name" type="wstring" readonly="yes">
7932	<desc>Returns the host network interface name.</desc>
7933	</attribute>
7934
7935	<attribute name="id" type="uuid" mod="string" readonly="yes">
7936	<desc>Returns the interface UUID.</desc>
7937	</attribute>
7938
7939	<attribute name="networkName" type="wstring" readonly="yes">
7940	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7941	</attribute>
7942
7943	<attribute name="DHCPEnabled" type="boolean" readonly="yes">
7944	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7945	</attribute>
7946
7947	<attribute name="IPAddress" type="wstring" readonly="yes">
7948	<desc>Returns the IP V4 address of the interface.</desc>
7949	</attribute>
7950
7951	<attribute name="networkMask" type="wstring" readonly="yes">
7952	<desc>Returns the network mask of the interface.</desc>
7953	</attribute>
7954
7955	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7956	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7957	</attribute>
7958
7959	<attribute name="IPV6Address" type="wstring" readonly="yes">
7960	<desc>Returns the IP V6 address of the interface.</desc>
7961	</attribute>
7962
7963	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7964	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7965	</attribute>
7966
7967	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7968	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7969	</attribute>
7970
7971	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7972	<desc>Type of protocol encapsulation used.</desc>
7973	</attribute>
7974
7975	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7976	<desc>Status of the interface.</desc>
7977	</attribute>
7978
7979	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7980	<desc>specifies the host interface type.</desc>
7981	</attribute>
7982
7983	<method name="enableStaticIPConfig">
7984	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7985	<param name="IPAddress" type="wstring" dir="in">
7986	<desc>
7987	IP address.
7988	</desc>
7989	</param>
7990	<param name="networkMask" type="wstring" dir="in">
7991	<desc>
7992	network mask.
7993	</desc>
7994	</param>
7995	</method>
7996
7997	<method name="enableStaticIPConfigV6">
7998	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7999	<param name="IPV6Address" type="wstring" dir="in">
8000	<desc>
8001	IP address.
8002	</desc>
8003	</param>
8004	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
8005	<desc>
8006	network mask.
8007	</desc>
8008	</param>
8009	</method>
8010
8011	<method name="enableDynamicIPConfig">
8012	<desc>enables the dynamic IP configuration.</desc>
8013	</method>
8014
8015	<method name="DHCPRediscover">
8016	<desc>refreshes the IP configuration for DHCP-enabled interface.</desc>
8017	</method>
8018
8019	</interface>
8020
8021	<interface
8022	name="IHost" extends="$unknown"
8023	uuid="30678943-32df-4830-b413-931b25ac86a0"
8024	wsmap="managed"
8025	>
8026	<desc>
8027	The IHost interface represents the physical machine that this VirtualBox
8028	installation runs on.
8029
8030	An object implementing this interface is returned by the
8031	<link to="IVirtualBox::host" /> attribute. This interface contains
8032	read-only information about the host's physical hardware (such as what
8033	processors and disks are available, what the host operating system is,
8034	and so on) and also allows for manipulating some of the host's hardware,
8035	such as global USB device filters and host interface networking.
8036
8037	</desc>
8038	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
8039	<desc>List of DVD drives available on the host.</desc>
8040	</attribute>
8041
8042	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
8043	<desc>List of floppy drives available on the host.</desc>
8044	</attribute>
8045
8046	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
8047	<desc>
8048	List of USB devices currently attached to the host.
8049	Once a new device is physically attached to the host computer,
8050	it appears in this list and remains there until detached.
8051
8052	<note>
8053	If USB functionality is not available in the given edition of
8054	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8055	</note>
8056	</desc>
8057	</attribute>
8058
8059	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
8060	<desc>
8061	List of USB device filters in action.
8062	When a new device is physically attached to the host computer,
8063	filters from this list are applied to it (in order they are stored
8064	in the list). The first matched filter will determine the
8065	<link to="IHostUSBDeviceFilter::action">action</link>
8066	performed on the device.
8067
8068	Unless the device is ignored by these filters, filters of all
8069	currently running virtual machines
8070	(<link to="IUSBController::deviceFilters"/>) are applied to it.
8071
8072	<note>
8073	If USB functionality is not available in the given edition of
8074	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8075	</note>
8076
8077	<see><link to="IHostUSBDeviceFilter"/>,
8078	<link to="USBDeviceState"/></see>
8079	</desc>
8080	</attribute>
8081
8082	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
8083	<desc>List of host network interfaces currently defined on the host.</desc>
8084	</attribute>
8085
8086	<attribute name="processorCount" type="unsigned long" readonly="yes">
8087	<desc>Number of (logical) CPUs installed in the host system.</desc>
8088	</attribute>
8089
8090	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
8091	<desc>Number of (logical) CPUs online in the host system.</desc>
8092	</attribute>
8093
8094	<attribute name="processorCoreCount" type="unsigned long" readonly="yes">
8095	<desc>Number of physical processor cores installed in the host system.</desc>
8096	</attribute>
8097
8098	<method name="getProcessorSpeed">
8099	<desc>Query the (approximate) maximum speed of a specified host CPU in
8100	Megahertz.
8101	</desc>
8102	<param name="cpuId" type="unsigned long" dir="in">
8103	<desc>
8104	Identifier of the CPU.
8105	</desc>
8106	</param>
8107	<param name="speed" type="unsigned long" dir="return">
8108	<desc>
8109	Speed value. 0 is returned if value is not known or @a cpuId is
8110	invalid.
8111	</desc>
8112	</param>
8113	</method>
8114
8115	<method name="getProcessorFeature">
8116	<desc>Query whether a CPU feature is supported or not.</desc>
8117	<param name="feature" type="ProcessorFeature" dir="in">
8118	<desc>
8119	CPU Feature identifier.
8120	</desc>
8121	</param>
8122	<param name="supported" type="boolean" dir="return">
8123	<desc>
8124	Feature is supported or not.
8125	</desc>
8126	</param>
8127	</method>
8128
8129	<method name="getProcessorDescription">
8130	<desc>Query the model string of a specified host CPU.
8131	</desc>
8132	<param name="cpuId" type="unsigned long" dir="in">
8133	<desc>
8134	Identifier of the CPU.
8135	<note>
8136	The current implementation might not necessarily return the
8137	description for this exact CPU.
8138	</note>
8139	</desc>
8140	</param>
8141	<param name="description" type="wstring" dir="return">
8142	<desc>
8143	Model string. An empty string is returned if value is not known or
8144	@a cpuId is invalid.
8145	</desc>
8146	</param>
8147	</method>
8148
8149	<method name="getProcessorCPUIDLeaf">
8150	<desc>
8151	Returns the CPU cpuid information for the specified leaf.
8152	</desc>
8153	<param name="cpuId" type="unsigned long" dir="in">
8154	<desc>
8155	Identifier of the CPU. The CPU most be online.
8156	<note>
8157	The current implementation might not necessarily return the
8158	description for this exact CPU.
8159	</note>
8160	</desc>
8161	</param>
8162	<param name="leaf" type="unsigned long" dir="in">
8163	<desc>
8164	CPUID leaf index (eax).
8165	</desc>
8166	</param>
8167	<param name="subLeaf" type="unsigned long" dir="in">
8168	<desc>
8169	CPUID leaf sub index (ecx). This currently only applies to cache
8170	information on Intel CPUs. Use 0 if retrieving values for
8171	<link to="IMachine::setCPUIDLeaf"/>.
8172	</desc>
8173	</param>
8174	<param name="valEax" type="unsigned long" dir="out">
8175	<desc>
8176	CPUID leaf value for register eax.
8177	</desc>
8178	</param>
8179	<param name="valEbx" type="unsigned long" dir="out">
8180	<desc>
8181	CPUID leaf value for register ebx.
8182	</desc>
8183	</param>
8184	<param name="valEcx" type="unsigned long" dir="out">
8185	<desc>
8186	CPUID leaf value for register ecx.
8187	</desc>
8188	</param>
8189	<param name="valEdx" type="unsigned long" dir="out">
8190	<desc>
8191	CPUID leaf value for register edx.
8192	</desc>
8193	</param>
8194	</method>
8195
8196	<attribute name="memorySize" type="unsigned long" readonly="yes">
8197	<desc>Amount of system memory in megabytes installed in the host system.</desc>
8198	</attribute>
8199
8200	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
8201	<desc>Available system memory in the host system.</desc>
8202	</attribute>
8203
8204	<attribute name="operatingSystem" type="wstring" readonly="yes">
8205	<desc>Name of the host system's operating system.</desc>
8206	</attribute>
8207
8208	<attribute name="OSVersion" type="wstring" readonly="yes">
8209	<desc>Host operating system's version string.</desc>
8210	</attribute>
8211
8212	<attribute name="UTCTime" type="long long" readonly="yes">
8213	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
8214	</attribute>
8215
8216	<attribute name="acceleration3DAvailable" type="boolean" readonly="yes">
8217	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
8218	</attribute>
8219
8220	<method name="createHostOnlyNetworkInterface">
8221	<desc>
8222	Creates a new adapter for Host Only Networking.
8223	<result name="E_INVALIDARG">
8224	Host network interface @a name already exists.
8225	</result>
8226	</desc>
8227	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
8228	<desc>
8229	Created host interface object.
8230	</desc>
8231	</param>
8232	<param name="progress" type="IProgress" dir="return">
8233	<desc>
8234	Progress object to track the operation completion.
8235	</desc>
8236	</param>
8237	</method>
8238
8239	<method name="removeHostOnlyNetworkInterface">
8240	<desc>
8241	Removes the given Host Only Networking interface.
8242	<result name="VBOX_E_OBJECT_NOT_FOUND">
8243	No host network interface matching @a id found.
8244	</result>
8245	</desc>
8246	<param name="id" type="uuid" mod="string" dir="in">
8247	<desc>
8248	Adapter GUID.
8249	</desc>
8250	</param>
8251	<param name="progress" type="IProgress" dir="return">
8252	<desc>
8253	Progress object to track the operation completion.
8254	</desc>
8255	</param>
8256	</method>
8257
8258	<method name="createUSBDeviceFilter">
8259	<desc>
8260	Creates a new USB device filter. All attributes except
8261	the filter name are set to empty (any match),
8262	<i>active</i> is @c false (the filter is not active).
8263
8264	The created filter can be added to the list of filters using
8265	<link to="#insertUSBDeviceFilter"/>.
8266
8267	<see><link to="#USBDeviceFilters"/></see>
8268	</desc>
8269	<param name="name" type="wstring" dir="in">
8270	<desc>
8271	Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
8272	</desc>
8273	</param>
8274	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
8275	<desc>Created filter object.</desc>
8276	</param>
8277	</method>
8278
8279	<method name="insertUSBDeviceFilter">
8280	<desc>
8281	Inserts the given USB device to the specified position
8282	in the list of filters.
8283
8284	Positions are numbered starting from @c 0. If the specified
8285	position is equal to or greater than the number of elements in
8286	the list, the filter is added at the end of the collection.
8287
8288	<note>
8289	Duplicates are not allowed, so an attempt to insert a
8290	filter already in the list is an error.
8291	</note>
8292	<note>
8293	If USB functionality is not available in the given edition of
8294	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8295	</note>
8296
8297	<see><link to="#USBDeviceFilters"/></see>
8298
8299	<result name="VBOX_E_INVALID_OBJECT_STATE">
8300	USB device filter is not created within this VirtualBox instance.
8301	</result>
8302	<result name="E_INVALIDARG">
8303	USB device filter already in list.
8304	</result>
8305
8306	</desc>
8307	<param name="position" type="unsigned long" dir="in">
8308	<desc>Position to insert the filter to.</desc>
8309	</param>
8310	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
8311	<desc>USB device filter to insert.</desc>
8312	</param>
8313	</method>
8314
8315	<method name="removeUSBDeviceFilter">
8316	<desc>
8317	Removes a USB device filter from the specified position in the
8318	list of filters.
8319
8320	Positions are numbered starting from @c 0. Specifying a
8321	position equal to or greater than the number of elements in
8322	the list will produce an error.
8323
8324	<note>
8325	If USB functionality is not available in the given edition of
8326	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8327	</note>
8328
8329	<see><link to="#USBDeviceFilters"/></see>
8330
8331	<result name="E_INVALIDARG">
8332	USB device filter list empty or invalid @a position.
8333	</result>
8334
8335	</desc>
8336	<param name="position" type="unsigned long" dir="in">
8337	<desc>Position to remove the filter from.</desc>
8338	</param>
8339	</method>
8340
8341	<method name="findHostDVDDrive">
8342	<desc>
8343	Searches for a host DVD drive with the given @c name.
8344
8345	<result name="VBOX_E_OBJECT_NOT_FOUND">
8346	Given @c name does not correspond to any host drive.
8347	</result>
8348
8349	</desc>
8350	<param name="name" type="wstring" dir="in">
8351	<desc>Name of the host drive to search for</desc>
8352	</param>
8353	<param name="drive" type="IMedium" dir="return">
8354	<desc>Found host drive object</desc>
8355	</param>
8356	</method>
8357
8358	<method name="findHostFloppyDrive">
8359	<desc>
8360	Searches for a host floppy drive with the given @c name.
8361
8362	<result name="VBOX_E_OBJECT_NOT_FOUND">
8363	Given @c name does not correspond to any host floppy drive.
8364	</result>
8365
8366	</desc>
8367	<param name="name" type="wstring" dir="in">
8368	<desc>Name of the host floppy drive to search for</desc>
8369	</param>
8370	<param name="drive" type="IMedium" dir="return">
8371	<desc>Found host floppy drive object</desc>
8372	</param>
8373	</method>
8374
8375	<method name="findHostNetworkInterfaceByName">
8376	<desc>
8377	Searches through all host network interfaces for an interface with
8378	the given @c name.
8379	<note>
8380	The method returns an error if the given @c name does not
8381	correspond to any host network interface.
8382	</note>
8383	</desc>
8384	<param name="name" type="wstring" dir="in">
8385	<desc>Name of the host network interface to search for.</desc>
8386	</param>
8387	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8388	<desc>Found host network interface object.</desc>
8389	</param>
8390	</method>
8391	<method name="findHostNetworkInterfaceById">
8392	<desc>
8393	Searches through all host network interfaces for an interface with
8394	the given GUID.
8395	<note>
8396	The method returns an error if the given GUID does not
8397	correspond to any host network interface.
8398	</note>
8399	</desc>
8400	<param name="id" type="uuid" mod="string" dir="in">
8401	<desc>GUID of the host network interface to search for.</desc>
8402	</param>
8403	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8404	<desc>Found host network interface object.</desc>
8405	</param>
8406	</method>
8407	<method name="findHostNetworkInterfacesOfType">
8408	<desc>
8409	Searches through all host network interfaces and returns a list of interfaces of the specified type
8410	</desc>
8411	<param name="type" type="HostNetworkInterfaceType" dir="in">
8412	<desc>type of the host network interfaces to search for.</desc>
8413	</param>
8414	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
8415	<desc>Found host network interface objects.</desc>
8416	</param>
8417	</method>
8418
8419	<method name="findUSBDeviceById">
8420	<desc>
8421	Searches for a USB device with the given UUID.
8422
8423	<result name="VBOX_E_OBJECT_NOT_FOUND">
8424	Given @c id does not correspond to any USB device.
8425	</result>
8426
8427	<see><link to="IUSBDevice::id"/></see>
8428	</desc>
8429	<param name="id" type="uuid" mod="string" dir="in">
8430	<desc>UUID of the USB device to search for.</desc>
8431	</param>
8432	<param name="device" type="IHostUSBDevice" dir="return">
8433	<desc>Found USB device object.</desc>
8434	</param>
8435	</method>
8436
8437	<method name="findUSBDeviceByAddress">
8438	<desc>
8439	Searches for a USB device with the given host address.
8440
8441	<result name="VBOX_E_OBJECT_NOT_FOUND">
8442	Given @c name does not correspond to any USB device.
8443	</result>
8444
8445	<see><link to="IUSBDevice::address"/></see>
8446	</desc>
8447	<param name="name" type="wstring" dir="in">
8448	<desc>
8449	Address of the USB device (as assigned by the host) to
8450	search for.
8451	</desc>
8452	</param>
8453	<param name="device" type="IHostUSBDevice" dir="return">
8454	<desc>Found USB device object.</desc>
8455	</param>
8456	</method>
8457
8458	<method name="generateMACAddress">
8459	<desc>
8460	Generates a valid Ethernet MAC address, 12 hexadecimal characters.
8461	</desc>
8462	<param name="address" type="wstring" dir="return">
8463	<desc>New Ethernet MAC address.</desc>
8464	</param>
8465	</method>
8466
8467	</interface>
8468
8469	<!--
8470	// ISystemProperties
8471	/////////////////////////////////////////////////////////////////////////
8472	-->
8473
8474	<interface
8475	name="ISystemProperties"
8476	extends="$unknown"
8477	uuid="55699910-cc50-11e2-8b8b-0800200c9a66"
8478	wsmap="managed"
8479	>
8480	<desc>
8481	The ISystemProperties interface represents global properties of the given
8482	VirtualBox installation.
8483
8484	These properties define limits and default values for various attributes
8485	and parameters. Most of the properties are read-only, but some can be
8486	changed by a user.
8487	</desc>
8488
8489	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
8490	<desc>Minimum guest system memory in Megabytes.</desc>
8491	</attribute>
8492
8493	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
8494	<desc>Maximum guest system memory in Megabytes.</desc>
8495	</attribute>
8496
8497	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
8498	<desc>Minimum guest video memory in Megabytes.</desc>
8499	</attribute>
8500
8501	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
8502	<desc>Maximum guest video memory in Megabytes.</desc>
8503	</attribute>
8504
8505	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
8506	<desc>Minimum CPU count.</desc>
8507	</attribute>
8508
8509	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
8510	<desc>Maximum CPU count.</desc>
8511	</attribute>
8512
8513	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8514	<desc>Maximum of monitors which could be connected.</desc>
8515	</attribute>
8516
8517	<attribute name="infoVDSize" type="long long" readonly="yes">
8518	<desc>Maximum size of a virtual disk image in bytes. Informational value,
8519	does not reflect the limits of any virtual disk image format.</desc>
8520	</attribute>
8521
8522	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8523	<desc>
8524	Maximum number of serial ports associated with every
8525	<link to="IMachine"/> instance.
8526	</desc>
8527	</attribute>
8528
8529	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8530	<desc>
8531	Maximum number of parallel ports associated with every
8532	<link to="IMachine"/> instance.
8533	</desc>
8534	</attribute>
8535
8536	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8537	<desc>
8538	Maximum device position in the boot order. This value corresponds
8539	to the total number of devices a machine can boot from, to make it
8540	possible to include all possible devices to the boot list.
8541	<see><link to="IMachine::setBootOrder"/></see>
8542	</desc>
8543	</attribute>
8544
8545	<attribute name="defaultMachineFolder" type="wstring">
8546	<desc>
8547	Full path to the default directory used to create new or open
8548	existing machines when a machine settings file name contains no
8549	path.
8550
8551	Starting with VirtualBox 4.0, by default, this attribute contains
8552	the full path of folder named "VirtualBox VMs" in the user's
8553	home directory, which depends on the host platform.
8554
8555	When setting this attribute, a full path must be specified.
8556	Setting this property to @c null or an empty string or the
8557	special value "Machines" (for compatibility reasons) will restore
8558	that default value.
8559
8560	If the folder specified herein does not exist, it will be created
8561	automatically as needed.
8562
8563	<see>
8564	<link to="IVirtualBox::createMachine"/>,
8565	<link to="IVirtualBox::openMachine"/>
8566	</see>
8567	</desc>
8568	</attribute>
8569
8570	<attribute name="loggingLevel" type="wstring">
8571	<desc>
8572	Specifies the logging level in current use by VirtualBox.
8573	</desc>
8574	</attribute>
8575
8576	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8577	<desc>
8578	List of all medium storage formats supported by this VirtualBox
8579	installation.
8580
8581	Keep in mind that the medium format identifier
8582	(<link to="IMediumFormat::id"/>) used in other API calls like
8583	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8584	medium format is a case-insensitive string. This means that, for
8585	example, all of the following strings:
8586	<pre>
8587	"VDI"
8588	"vdi"
8589	"VdI"</pre>
8590	refer to the same medium format.
8591
8592	Note that the virtual medium framework is backend-based, therefore
8593	the list of supported formats depends on what backends are currently
8594	installed.
8595
8596	<see><link to="IMediumFormat"/></see>
8597	</desc>
8598	</attribute>
8599
8600	<attribute name="defaultHardDiskFormat" type="wstring">
8601	<desc>
8602	Identifier of the default medium format used by VirtualBox.
8603
8604	The medium format set by this attribute is used by VirtualBox
8605	when the medium format was not specified explicitly. One example is
8606	<link to="IVirtualBox::createHardDisk"/> with the empty
8607	format argument. A more complex example is implicit creation of
8608	differencing media when taking a snapshot of a virtual machine:
8609	this operation will try to use a format of the parent medium first
8610	and if this format does not support differencing media the default
8611	format specified by this argument will be used.
8612
8613	The list of supported medium formats may be obtained by the
8614	<link to="#mediumFormats"/> call. Note that the default medium
8615	format must have a capability to create differencing media;
8616	otherwise operations that create media implicitly may fail
8617	unexpectedly.
8618
8619	The initial value of this property is <tt>"VDI"</tt> in the current
8620	version of the VirtualBox product, but may change in the future.
8621
8622	<note>
8623	Setting this property to @c null or empty string will restore the
8624	initial value.
8625	</note>
8626
8627	<see>
8628	<link to="#mediumFormats"/>,
8629	<link to="IMediumFormat::id"/>,
8630	<link to="IVirtualBox::createHardDisk"/>
8631	</see>
8632	</desc>
8633	</attribute>
8634
8635	<attribute name="freeDiskSpaceWarning" type="long long">
8636	<desc>Issue a warning if the free disk space is below (or in some disk
8637	intensive operation is expected to go below) the given size in
8638	bytes.</desc>
8639	</attribute>
8640
8641	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
8642	<desc>Issue a warning if the free disk space is below (or in some disk
8643	intensive operation is expected to go below) the given percentage.</desc>
8644	</attribute>
8645
8646	<attribute name="freeDiskSpaceError" type="long long">
8647	<desc>Issue an error if the free disk space is below (or in some disk
8648	intensive operation is expected to go below) the given size in
8649	bytes.</desc>
8650	</attribute>
8651
8652	<attribute name="freeDiskSpacePercentError" type="unsigned long">
8653	<desc>Issue an error if the free disk space is below (or in some disk
8654	intensive operation is expected to go below) the given percentage.</desc>
8655	</attribute>
8656
8657	<attribute name="VRDEAuthLibrary" type="wstring">
8658	<desc>
8659	Library that provides authentication for Remote Desktop clients. The library
8660	is used if a virtual machine's authentication type is set to "external"
8661	in the VM RemoteDisplay configuration.
8662
8663	The system library extension (".DLL" or ".so") must be omitted.
8664	A full path can be specified; if not, then the library must reside on the
8665	system's default library path.
8666
8667	The default value of this property is <tt>"VBoxAuth"</tt>. There is a library
8668	of that name in one of the default VirtualBox library directories.
8669
8670	For details about VirtualBox authentication libraries and how to implement
8671	them, please refer to the VirtualBox manual.
8672
8673	<note>
8674	Setting this property to @c null or empty string will restore the
8675	initial value.
8676	</note>
8677	</desc>
8678	</attribute>
8679
8680	<attribute name="webServiceAuthLibrary" type="wstring">
8681	<desc>
8682	Library that provides authentication for webservice clients. The library
8683	is used if a virtual machine's authentication type is set to "external"
8684	in the VM RemoteDisplay configuration and will be called from
8685	within the <link to="IWebsessionManager::logon" /> implementation.
8686
8687	As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
8688	there is no per-VM setting for this, as the webservice is a global
8689	resource (if it is running). Only for this setting (for the webservice),
8690	setting this value to a literal <tt>"null"</tt> string disables authentication,
8691	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8692	no matter what user name and password are supplied.
8693
8694	The initial value of this property is <tt>"VBoxAuth"</tt>,
8695	meaning that the webservice will use the same authentication
8696	library that is used by default for VRDE (again, see
8697	<link to="ISystemProperties::VRDEAuthLibrary" />).
8698	The format and calling convention of authentication libraries
8699	is the same for the webservice as it is for VRDE.
8700
8701	<note>
8702	Setting this property to @c null or empty string will restore the
8703	initial value.
8704	</note>
8705	</desc>
8706	</attribute>
8707
8708	<attribute name="defaultVRDEExtPack" type="wstring">
8709	<desc>
8710	The name of the extension pack providing the default VRDE.
8711
8712	This attribute is for choosing between multiple extension packs
8713	providing VRDE. If only one is installed, it will automatically be the
8714	default one. The attribute value can be empty if no VRDE extension
8715	pack is installed.
8716
8717	For details about VirtualBox Remote Desktop Extension and how to
8718	implement one, please refer to the VirtualBox SDK.
8719	</desc>
8720	</attribute>
8721
8722	<attribute name="logHistoryCount" type="unsigned long">
8723	<desc>
8724	This value specifies how many old release log files are kept.
8725	</desc>
8726	</attribute>
8727
8728	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8729	<desc>This value hold the default audio driver for the current
8730	system.</desc>
8731	</attribute>
8732
8733	<attribute name="autostartDatabasePath" type="wstring">
8734	<desc>
8735	The path to the autostart database. Depending on the host this might
8736	be a filesystem path or something else.
8737	</desc>
8738	</attribute>
8739
8740	<attribute name="defaultAdditionsISO" type="wstring">
8741	<desc>
8742	The path to the default Guest Additions ISO image. Can be empty if
8743	the location is not known in this installation.
8744	</desc>
8745	</attribute>
8746
8747	<attribute name="defaultFrontend" type="wstring">
8748	<desc>
8749	Selects which VM frontend should be used by default when launching
8750	a VM through the <link to="IMachine::launchVMProcess" /> method.
8751	Empty or @c null strings do not define a particular default, it is up
8752	to <link to="IMachine::launchVMProcess" /> to select one. See the
8753	description of <link to="IMachine::launchVMProcess" /> for the valid
8754	frontend types.
8755
8756	This global setting is overridden by the per-VM attribute
8757	<link to="IMachine::defaultFrontend" /> or a frontend type
8758	passed to <link to="IMachine::launchVMProcess" />.
8759	</desc>
8760	</attribute>
8761
8762	<method name="getMaxNetworkAdapters">
8763	<desc>
8764	Maximum total number of network adapters associated with every
8765	<link to="IMachine"/> instance.
8766	</desc>
8767
8768	<param name="chipset" type="ChipsetType" dir="in">
8769	<desc>The chipset type to get the value for.</desc>
8770	</param>
8771
8772
8773	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8774	<desc>The maximum total number of network adapters allowed.</desc>
8775	</param>
8776
8777	</method>
8778
8779	<method name="getMaxNetworkAdaptersOfType">
8780	<desc>
8781	Maximum number of network adapters of a given attachment type,
8782	associated with every <link to="IMachine"/> instance.
8783	</desc>
8784
8785	<param name="chipset" type="ChipsetType" dir="in">
8786	<desc>The chipset type to get the value for.</desc>
8787	</param>
8788
8789	<param name="type" type="NetworkAttachmentType" dir="in">
8790	<desc>Type of attachment.</desc>
8791	</param>
8792
8793	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8794	<desc>The maximum number of network adapters allowed for
8795	particular chipset and attachment type.</desc>
8796	</param>
8797
8798	</method>
8799
8800
8801	<method name="getMaxDevicesPerPortForStorageBus">
8802	<desc>Returns the maximum number of devices which can be attached to a port
8803	for the given storage bus.</desc>
8804
8805	<param name="bus" type="StorageBus" dir="in">
8806	<desc>The storage bus type to get the value for.</desc>
8807	</param>
8808
8809	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8810	<desc>The maximum number of devices which can be attached to the port for the given
8811	storage bus.</desc>
8812	</param>
8813	</method>
8814
8815	<method name="getMinPortCountForStorageBus">
8816	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8817
8818	<param name="bus" type="StorageBus" dir="in">
8819	<desc>The storage bus type to get the value for.</desc>
8820	</param>
8821
8822	<param name="minPortCount" type="unsigned long" dir="return">
8823	<desc>The minimum number of ports for the given storage bus.</desc>
8824	</param>
8825	</method>
8826
8827	<method name="getMaxPortCountForStorageBus">
8828	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8829
8830	<param name="bus" type="StorageBus" dir="in">
8831	<desc>The storage bus type to get the value for.</desc>
8832	</param>
8833
8834	<param name="maxPortCount" type="unsigned long" dir="return">
8835	<desc>The maximum number of ports for the given storage bus.</desc>
8836	</param>
8837	</method>
8838
8839	<method name="getMaxInstancesOfStorageBus">
8840	<desc>Returns the maximum number of storage bus instances which
8841	can be configured for each VM. This corresponds to the number of
8842	storage controllers one can have. Value may depend on chipset type
8843	used.</desc>
8844
8845	<param name="chipset" type="ChipsetType" dir="in">
8846	<desc>The chipset type to get the value for.</desc>
8847	</param>
8848
8849	<param name="bus" type="StorageBus" dir="in">
8850	<desc>The storage bus type to get the value for.</desc>
8851	</param>
8852
8853	<param name="maxInstances" type="unsigned long" dir="return">
8854	<desc>The maximum number of instances for the given storage bus.</desc>
8855	</param>
8856	</method>
8857
8858	<method name="getDeviceTypesForStorageBus">
8859	<desc>Returns list of all the supported device types
8860	(<link to="DeviceType"/>) for the given type of storage
8861	bus.</desc>
8862
8863	<param name="bus" type="StorageBus" dir="in">
8864	<desc>The storage bus type to get the value for.</desc>
8865	</param>
8866
8867	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8868	<desc>The list of all supported device types for the given storage bus.</desc>
8869	</param>
8870	</method>
8871
8872	<method name="getDefaultIoCacheSettingForStorageController">
8873	<desc>Returns the default I/O cache setting for the
8874	given storage controller</desc>
8875
8876	<param name="controllerType" type="StorageControllerType" dir="in">
8877	<desc>The storage controller to the setting for.</desc>
8878	</param>
8879
8880	<param name="enabled" type="boolean" dir="return">
8881	<desc>Returned flag indicating the default value</desc>
8882	</param>
8883	</method>
8884	</interface>
8885
8886	<!--
8887	// IGuest
8888	/////////////////////////////////////////////////////////////////////////
8889	-->
8890
8891	<interface
8892	name="IGuestOSType" extends="$unknown"
8893	uuid="6d968f9a-858b-4c50-bf17-241f069e94c2"
8894	wsmap="struct"
8895	>
8896	<desc>
8897	</desc>
8898
8899	<attribute name="familyId" type="wstring" readonly="yes">
8900	<desc>Guest OS family identifier string.</desc>
8901	</attribute>
8902
8903	<attribute name="familyDescription" type="wstring" readonly="yes">
8904	<desc>Human readable description of the guest OS family.</desc>
8905	</attribute>
8906
8907	<attribute name="id" type="wstring" readonly="yes">
8908	<desc>Guest OS identifier string.</desc>
8909	</attribute>
8910
8911	<attribute name="description" type="wstring" readonly="yes">
8912	<desc>Human readable description of the guest OS.</desc>
8913	</attribute>
8914
8915	<attribute name="is64Bit" type="boolean" readonly="yes">
8916	<desc>Returns @c true if the given OS is 64-bit</desc>
8917	</attribute>
8918
8919	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8920	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8921	</attribute>
8922
8923	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8924	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8925	</attribute>
8926
8927	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8928	<desc>Recommended RAM size in Megabytes.</desc>
8929	</attribute>
8930
8931	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8932	<desc>Recommended video RAM size in Megabytes.</desc>
8933	</attribute>
8934
8935	<attribute name="recommended2DVideoAcceleration" type="boolean" readonly="yes">
8936	<desc>Returns @c true if 2D video acceleration is recommended for this OS type.</desc>
8937	</attribute>
8938
8939	<attribute name="recommended3DAcceleration" type="boolean" readonly="yes">
8940	<desc>Returns @c true if 3D acceleration is recommended for this OS type.</desc>
8941	</attribute>
8942
8943	<attribute name="recommendedHDD" type="long long" readonly="yes">
8944	<desc>Recommended hard disk size in bytes.</desc>
8945	</attribute>
8946
8947	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8948	<desc>Returns recommended network adapter for this OS type.</desc>
8949	</attribute>
8950
8951	<attribute name="recommendedPAE" type="boolean" readonly="yes">
8952	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8953	</attribute>
8954
8955	<attribute name="recommendedDVDStorageController" type="StorageControllerType" readonly="yes">
8956	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8957	</attribute>
8958
8959	<attribute name="recommendedDVDStorageBus" type="StorageBus" readonly="yes">
8960	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8961	</attribute>
8962
8963	<attribute name="recommendedHDStorageController" type="StorageControllerType" readonly="yes">
8964	<desc>Recommended storage controller type for HD drives.</desc>
8965	</attribute>
8966
8967	<attribute name="recommendedHDStorageBus" type="StorageBus" readonly="yes">
8968	<desc>Recommended storage bus type for HD drives.</desc>
8969	</attribute>
8970
8971	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8972	<desc>Recommended firmware type.</desc>
8973	</attribute>
8974
8975	<attribute name="recommendedUSBHID" type="boolean" readonly="yes">
8976	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8977	</attribute>
8978
8979	<attribute name="recommendedHPET" type="boolean" readonly="yes">
8980	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8981	</attribute>
8982
8983	<attribute name="recommendedUSBTablet" type="boolean" readonly="yes">
8984	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8985	</attribute>
8986
8987	<attribute name="recommendedRTCUseUTC" type="boolean" readonly="yes">
8988	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8989	</attribute>
8990
8991	<attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
8992	<desc>Recommended chipset type.</desc>
8993	</attribute>
8994
8995	<attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
8996	<desc>Recommended audio type.</desc>
8997	</attribute>
8998
8999	<attribute name="recommendedFloppy" type="boolean" readonly="yes">
9000	<desc>Returns @c true a floppy drive is recommended for this OS type.</desc>
9001	</attribute>
9002
9003	<attribute name="recommendedUSB" type="boolean" readonly="yes">
9004	<desc>Returns @c true a USB controller is recommended for this OS type.</desc>
9005	</attribute>
9006
9007	</interface>
9008
9009	<enum
9010	name="AdditionsFacilityType"
9011	uuid="98f7f957-89fb-49b6-a3b1-31e3285eb1d8"
9012	>
9013	<desc>
9014	Guest Additions facility IDs.
9015	</desc>
9016
9017	<const name="None" value="0">
9018	<desc>No/invalid facility.</desc>
9019	</const>
9020	<const name="VBoxGuestDriver" value="20">
9021	<desc>VirtualBox base driver (VBoxGuest).</desc>
9022	</const>
9023	<const name="AutoLogon" value="90">
9024	<desc>Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox).</desc>
9025	</const>
9026	<const name="VBoxService" value="100">
9027	<desc>VirtualBox system service (VBoxService).</desc>
9028	</const>
9029	<const name="VBoxTrayClient" value="101">
9030	<desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc>
9031	</const>
9032	<const name="Seamless" value="1000">
9033	<desc>Seamless guest desktop integration.</desc>
9034	</const>
9035	<const name="Graphics" value="1100">
9036	<desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints
9037	are not immediately acted on and guest display resizes are probably not initiated by
9038	the guest additions.
9039	</desc>
9040	</const>
9041	<const name="All" value="2147483646">
9042	<desc>All facilities selected.</desc>
9043	</const>
9044	</enum>
9045
9046	<enum
9047	name="AdditionsFacilityClass"
9048	uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f"
9049	>
9050	<desc>
9051	Guest Additions facility classes.
9052	</desc>
9053
9054	<const name="None" value="0">
9055	<desc>No/invalid class.</desc>
9056	</const>
9057	<const name="Driver" value="10">
9058	<desc>Driver.</desc>
9059	</const>
9060	<const name="Service" value="30">
9061	<desc>System service.</desc>
9062	</const>
9063	<const name="Program" value="50">
9064	<desc>Program.</desc>
9065	</const>
9066	<const name="Feature" value="100">
9067	<desc>Feature.</desc>
9068	</const>
9069	<const name="ThirdParty" value="999">
9070	<desc>Third party.</desc>
9071	</const>
9072	<const name="All" value="2147483646">
9073	<desc>All facility classes selected.</desc>
9074	</const>
9075	</enum>
9076
9077	<enum
9078	name="AdditionsFacilityStatus"
9079	uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde"
9080	>
9081	<desc>
9082	Guest Additions facility states.
9083	</desc>
9084
9085	<const name="Inactive" value="0">
9086	<desc>Facility is not active.</desc>
9087	</const>
9088	<const name="Paused" value="1">
9089	<desc>Facility has been paused.</desc>
9090	</const>
9091	<const name="PreInit" value="20">
9092	<desc>Facility is preparing to initialize.</desc>
9093	</const>
9094	<const name="Init" value="30">
9095	<desc>Facility is initializing.</desc>
9096	</const>
9097	<const name="Active" value="50">
9098	<desc>Facility is up and running.</desc>
9099	</const>
9100	<const name="Terminating" value="100">
9101	<desc>Facility is shutting down.</desc>
9102	</const>
9103	<const name="Terminated" value="101">
9104	<desc>Facility successfully shut down.</desc>
9105	</const>
9106	<const name="Failed" value="800">
9107	<desc>Facility failed to start.</desc>
9108	</const>
9109	<const name="Unknown" value="999">
9110	<desc>Facility status is unknown.</desc>
9111	</const>
9112	</enum>
9113
9114	<interface
9115	name="IAdditionsFacility" extends="$unknown"
9116	uuid="54992946-6af1-4e49-98ec-58b558b7291e"
9117	wsmap="struct"
9118	>
9119	<desc>
9120	Structure representing a Guest Additions facility.
9121	</desc>
9122
9123	<attribute name="classType" type="AdditionsFacilityClass" readonly="yes">
9124	<desc>The class this facility is part of.</desc>
9125	</attribute>
9126
9127	<attribute name="lastUpdated" type="long long" readonly="yes">
9128	<desc>
9129	Time stamp of the last status update,
9130	in milliseconds since 1970-01-01 UTC.
9131	</desc>
9132	</attribute>
9133
9134	<attribute name="name" type="wstring" readonly="yes">
9135	<desc>The facility's friendly name.</desc>
9136	</attribute>
9137
9138	<attribute name="status" type="AdditionsFacilityStatus" readonly="yes">
9139	<desc>The current status.</desc>
9140	</attribute>
9141
9142	<attribute name="type" type="AdditionsFacilityType" readonly="yes">
9143	<desc>The facility's type ID.</desc>
9144	</attribute>
9145	</interface>
9146
9147	<enum
9148	name="AdditionsRunLevelType"
9149	uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
9150	>
9151	<desc>
9152	Guest Additions run level type.
9153	</desc>
9154
9155	<const name="None" value="0">
9156	<desc>Guest Additions are not loaded.</desc>
9157	</const>
9158	<const name="System" value="1">
9159	<desc>Guest drivers are loaded.</desc>
9160	</const>
9161	<const name="Userland" value="2">
9162	<desc>Common components (such as application services) are loaded.</desc>
9163	</const>
9164	<const name="Desktop" value="3">
9165	<desc>Per-user desktop components are loaded.</desc>
9166	</const>
9167	</enum>
9168
9169	<enum
9170	name="AdditionsUpdateFlag"
9171	uuid="726a818d-18d6-4389-94e8-3e9e6826171a"
9172	>
9173	<desc>
9174	Guest Additions update flags.
9175	</desc>
9176
9177	<const name="None" value="0">
9178	<desc>No flag set.</desc>
9179	</const>
9180	<const name="WaitForUpdateStartOnly" value="1">
9181	<desc>Starts the regular updating process and waits until the
9182	actual Guest Additions update inside the guest was started.
9183	This can be necessary due to needed interaction with the guest
9184	OS during the installation phase.</desc>
9185	</const>
9186	</enum>
9187
9188	<enum
9189	name="GuestSessionStatus"
9190	uuid="ac2669da-4624-44f2-85b5-0b0bfb8d8673"
9191	>
9192	<desc>
9193	Guest session status. This enumeration represents possible values of
9194	the <link to="IGuestSession::status"/> attribute.
9195	</desc>
9196	<const name="Undefined" value="0">
9197	<desc>Guest session is in an undefined state.</desc>
9198	</const>
9199	<const name="Starting" value="10">
9200	<desc>Guest session is being started.</desc>
9201	</const>
9202	<const name="Started" value="100">
9203	<desc>Guest session has been started.</desc>
9204	</const>
9205	<const name="Terminating" value="480">
9206	<desc>Guest session is being terminated.</desc>
9207	</const>
9208	<const name="Terminated" value="500">
9209	<desc>Guest session terminated normally.</desc>
9210	</const>
9211	<const name="TimedOutKilled" value="512">
9212	<desc>Guest session timed out and was killed.</desc>
9213	</const>
9214	<const name="TimedOutAbnormally" value="513">
9215	<desc>Guest session timed out and was not killed successfully.</desc>
9216	</const>
9217	<const name="Down" value="600">
9218	<desc>Service/OS is stopping, guest session was killed.</desc>
9219	</const>
9220	<const name="Error" value="800">
9221	<desc>Something went wrong.</desc>
9222	</const>
9223	</enum>
9224
9225	<enum
9226	name="GuestSessionWaitForFlag"
9227	uuid="bb7a372a-f635-4e11-a81a-e707f3a52ef5"
9228	>
9229	<desc>
9230	Guest session waiting flags. Multiple flags can be combined.
9231	</desc>
9232
9233	<const name="None" value="0">
9234	<desc>No waiting flags specified. Do not use this.</desc>
9235	</const>
9236	<const name="Start" value="1">
9237	<desc>Wait for the guest session being started.</desc>
9238	</const>
9239	<const name="Terminate" value="2">
9240	<desc>Wait for the guest session being terminated.</desc>
9241	</const>
9242	<const name="Status" value="4">
9243	<desc>Wait for the next guest session status change.</desc>
9244	</const>
9245	</enum>
9246
9247	<enum
9248	name="GuestSessionWaitResult"
9249	uuid="c0f6a8a5-fdb6-42bf-a582-56c6f82bcd2d"
9250	>
9251	<desc>
9252	Guest session waiting results. Depending on the session waiting flags (for
9253	more information see <link to="GuestSessionWaitForFlag"/>) the waiting result
9254	can vary based on the session's current status.
9255
9256	To wait for a guest session to terminate after it has been
9257	created by <link to="IGuest::createSession"/> one would specify
9258	GuestSessionWaitResult_Terminate.
9259	</desc>
9260
9261	<const name="None" value="0">
9262	<desc>No result was returned. Not being used.</desc>
9263	</const>
9264	<const name="Start" value="1">
9265	<desc>The guest session has been started.</desc>
9266	</const>
9267	<const name="Terminate" value="2">
9268	<desc>The guest session has been terminated.</desc>
9269	</const>
9270	<const name="Status" value="3">
9271	<desc>
9272	The guest session has changed its status. The status then can
9273	be retrieved via <link to="IGuestSession::status"/>.
9274	</desc>
9275	</const>
9276	<const name="Error" value="4">
9277	<desc>Error while executing the process.</desc>
9278	</const>
9279	<const name="Timeout" value="5">
9280	<desc>
9281	The waiting operation timed out. This also will happen
9282	when no event has been occured matching the
9283	current waiting flags in a <link to="IGuestSession::waitFor"/> call.
9284	</desc>
9285	</const>
9286	<const name="WaitFlagNotSupported" value="6">
9287	<desc>
9288	A waiting flag specified in the <link to="IGuestSession::waitFor"/> call
9289	is not supported by the guest.
9290	</desc>
9291	</const>
9292	</enum>
9293
9294	<enum
9295	name="FileSeekType"
9296	uuid="1b73f4f3-3515-4073-a506-76878d9e2541"
9297	>
9298	<desc>
9299	File seeking types.
9300	</desc>
9301
9302	<const name="Set" value="0">
9303	<desc>Seek from the start of the file.</desc>
9304	</const>
9305	<const name="Current" value="1">
9306	<desc>Seek from the current file position.</desc>
9307	</const>
9308	</enum>
9309
9310	<enum
9311	name="ProcessInputFlag"
9312	uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
9313	>
9314	<desc>
9315	Guest process input flags.
9316	</desc>
9317	<const name="None" value="0">
9318	<desc>No flag set.</desc>
9319	</const>
9320	<const name="EndOfFile" value="1">
9321	<desc>End of file (input) reached.</desc>
9322	</const>
9323	</enum>
9324
9325	<enum
9326	name="ProcessOutputFlag"
9327	uuid="9979e85a-52bb-40b7-870c-57115e27e0f1"
9328	>
9329	<desc>
9330	Guest process output flags for specifying which
9331	type of output to retrieve.
9332	</desc>
9333	<const name="None" value="0">
9334	<desc>No flags set. Get output from stdout.</desc>
9335	</const>
9336	<const name="StdErr" value="1">
9337	<desc>Get output from stderr.</desc>
9338	</const>
9339	</enum>
9340
9341	<enum
9342	name="ProcessWaitForFlag"
9343	uuid="23b550c7-78e1-437e-98f0-65fd9757bcd2"
9344	>
9345	<desc>
9346	Process waiting flags. Multiple flags can be combined.
9347	</desc>
9348
9349	<const name="None" value="0">
9350	<desc>No waiting flags specified. Do not use this.</desc>
9351	</const>
9352	<const name="Start" value="1">
9353	<desc>Wait for the process being started.</desc>
9354	</const>
9355	<const name="Terminate" value="2">
9356	<desc>Wait for the process being terminated.</desc>
9357	</const>
9358	<const name="StdIn" value="4">
9359	<desc>Wait for stdin becoming available.</desc>
9360	</const>
9361	<const name="StdOut" value="8">
9362	<desc>Wait for data becoming available on stdout.</desc>
9363	</const>
9364	<const name="StdErr" value="16">
9365	<desc>Wait for data becoming available on stderr.</desc>
9366	</const>
9367	</enum>
9368
9369	<enum
9370	name="ProcessWaitResult"
9371	uuid="40719cbe-f192-4fe9-a231-6697b3c8e2b4"
9372	>
9373	<desc>
9374	Process waiting results. Depending on the process waiting flags (for
9375	more information see <link to="ProcessWaitForFlag"/>) the waiting result
9376	can vary based on the processes' current status.
9377
9378	To wait for a guest process to terminate after it has been
9379	created by <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>
9380	one would specify ProcessWaitResult_Terminate.
9381
9382	If a guest process has been started with ProcessCreateFlag_WaitForStdOut
9383	a client can wait with ProcessWaitResult_StdOut for new data to arrive on
9384	stdout; same applies for ProcessCreateFlag_WaitForStdErr and
9385	ProcessWaitResult_StdErr.
9386	</desc>
9387
9388	<const name="None" value="0">
9389	<desc>No result was returned. Not being used.</desc>
9390	</const>
9391	<const name="Start" value="1">
9392	<desc>The process has been started.</desc>
9393	</const>
9394	<const name="Terminate" value="2">
9395	<desc>The process has been terminated.</desc>
9396	</const>
9397	<const name="Status" value="3">
9398	<desc>
9399	The process has changed its status. The status then can
9400	be retrieved via <link to="IProcess::status"/>.
9401	</desc>
9402	</const>
9403	<const name="Error" value="4">
9404	<desc>Error while executing the process.</desc>
9405	</const>
9406	<const name="Timeout" value="5">
9407	<desc>
9408	The waiting operation timed out. This also will happen
9409	when no event has been occured matching the
9410	current waiting flags in a <link to="IProcess::waitFor"/> call.
9411	</desc>
9412	</const>
9413	<const name="StdIn" value="6">
9414	<desc>
9415	The process signalled that stdin became available for writing
9416	and that the process awaits input now.</desc>
9417	</const>
9418	<const name="StdOut" value="7">
9419	<desc>Data on stdout became available for reading.</desc>
9420	</const>
9421	<const name="StdErr" value="8">
9422	<desc>Data on stderr became available for reading.</desc>
9423	</const>
9424	<const name="WaitFlagNotSupported" value="9">
9425	<desc>
9426	A waiting flag specified in the <link to="IProcess::waitFor"/> call
9427	is not supported by the guest.
9428	</desc>
9429	</const>
9430	</enum>
9431
9432	<enum
9433	name="CopyFileFlag"
9434	uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
9435	>
9436	<desc>
9437	File copying flags.
9438	</desc>
9439	<const name="None" value="0">
9440	<desc>No flag set.</desc>
9441	</const>
9442	<const name="Recursive" value="1">
9443	<desc>Copy directories recursively.</desc>
9444	</const>
9445	<const name="Update" value="2">
9446	<desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc>
9447	</const>
9448	<const name="FollowLinks" value="4">
9449	<desc>Follow symbolic links.</desc>
9450	</const>
9451	</enum>
9452
9453	<enum
9454	name="DirectoryCreateFlag"
9455	uuid="bd721b0e-ced5-4f79-b368-249897c32a36"
9456	>
9457	<desc>
9458	Directory creation flags.
9459	</desc>
9460	<const name="None" value="0">
9461	<desc>No flag set.</desc>
9462	</const>
9463	<const name="Parents" value="1">
9464	<desc>No error if existing, make parent directories as needed.</desc>
9465	</const>
9466	</enum>
9467
9468	<enum
9469	name="DirectoryRemoveRecFlag"
9470	uuid="455aabf0-7692-48f6-9061-f21579b65769"
9471	>
9472	<desc>
9473	Directory recursive removement flags.
9474	</desc>
9475
9476	<const name="None" value="0">
9477	<desc>No flag set.</desc>
9478	</const>
9479	<const name="ContentAndDir" value="1">
9480	<desc>Delete the content of the directory and the directory itself.</desc>
9481	</const>
9482	<const name="ContentOnly" value="2">
9483	<desc>Only delete the content of the directory, omit the directory it self.</desc>
9484	</const>
9485	</enum>
9486
9487	<enum
9488	name="PathRenameFlag"
9489	uuid="f3baa09f-c758-453d-b91c-c7787d76351d"
9490	>
9491	<desc>
9492	Path renaming flags.
9493	</desc>
9494
9495	<const name="None" value="0">
9496	<desc>No flag set.</desc>
9497	</const>
9498	<const name="NoReplace" value="1">
9499	<desc>Do not replace anything.</desc>
9500	</const>
9501	<const name="Replace" value="2">
9502	<desc>This will replace attempt any target which isn't a directory.</desc>
9503	</const>
9504	<const name="NoSymlinks" value="4">
9505	<desc>Don't allow symbolic links as part of the path.</desc>
9506	</const>
9507	</enum>
9508
9509	<enum
9510	name="ProcessCreateFlag"
9511	uuid="35192799-bfde-405d-9bea-c735ab9998e4"
9512	>
9513	<desc>
9514	Guest process execution flags.
9515	</desc>
9516
9517	<const name="None" value="0">
9518	<desc>No flag set.</desc>
9519	</const>
9520	<const name="WaitForProcessStartOnly" value="1">
9521	<desc>Only use the specified timeout value to wait for starting the guest process - the guest
9522	process itself then uses an infinite timeout.</desc>
9523	</const>
9524	<const name="IgnoreOrphanedProcesses" value="2">
9525	<desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
9526	</const>
9527	<const name="Hidden" value="4">
9528	<desc>Do not show the started process according to the guest OS guidelines.</desc>
9529	</const>
9530	<const name="NoProfile" value="8">
9531	<desc>Do not use the user's profile data when exeuting a process. Only available for Windows guests.</desc>
9532	</const>
9533	<const name="WaitForStdOut" value="16">
9534	<desc>The guest process waits until all data from stdout is read out.</desc>
9535	</const>
9536	<const name="WaitForStdErr" value="32">
9537	<desc>The guest process waits until all data from stderr is read out.</desc>
9538	</const>
9539	<const name="ExpandArguments" value="64">
9540	<desc>Expands environment variables in process arguments.</desc>
9541	</const>
9542	</enum>
9543
9544	<enum
9545	name="ProcessPriority"
9546	uuid="ee8cac50-e232-49fe-806b-d1214d9c2e49"
9547	>
9548	<desc>
9549	Process priorities.
9550	</desc>
9551
9552	<const name="Invalid" value="0">
9553	<desc>Invalid priority, do not use.</desc>
9554	</const>
9555	<const name="Default" value="1">
9556	<desc>Default process priority determined by the OS.</desc>
9557	</const>
9558	</enum>
9559
9560	<enum
9561	name="SymlinkType"
9562	uuid="37794668-f8f1-4714-98a5-6f8fa2ed0118"
9563	>
9564	<desc>
9565	Symbolic link types.
9566	</desc>
9567
9568	<const name="Unknown" value="0">
9569	<desc>It is not known what is being targeted.</desc>
9570	</const>
9571	<const name="Directory" value="1">
9572	<desc>The link targets a directory.</desc>
9573	</const>
9574	<const name="File" value="2">
9575	<desc>The link targets a file (or whatever else).</desc>
9576	</const>
9577	</enum>
9578
9579	<enum
9580	name="SymlinkReadFlag"
9581	uuid="b7fe2b9d-790e-4b25-8adf-1ca33026931f"
9582	>
9583	<desc>
9584	Symbolic link reading flags.
9585	</desc>
9586
9587	<const name="None" value="0">
9588	<desc>No flags set.</desc>
9589	</const>
9590	<const name="NoSymlinks" value="1">
9591	<desc>Don't allow symbolic links as part of the path.</desc>
9592	</const>
9593	</enum>
9594
9595	<enum
9596	name="ProcessStatus"
9597	uuid="4d52368f-5b48-4bfe-b486-acf89139b52f"
9598	>
9599	<desc>
9600	Process execution statuses.
9601	</desc>
9602
9603	<const name="Undefined" value="0">
9604	<desc>Process is in an undefined state.</desc>
9605	</const>
9606	<const name="Starting" value="10">
9607	<desc>Process is being started.</desc>
9608	</const>
9609	<const name="Started" value="100">
9610	<desc>Process has been started.</desc>
9611	</const>
9612	<const name="Paused" value="110">
9613	<desc>Process has been paused.</desc>
9614	</const>
9615	<const name="Terminating" value="480">
9616	<desc>Process is being terminated.</desc>
9617	</const>
9618	<const name="TerminatedNormally" value="500">
9619	<desc>Process terminated normally.</desc>
9620	</const>
9621	<const name="TerminatedSignal" value="510">
9622	<desc>Process terminated via signal.</desc>
9623	</const>
9624	<const name="TerminatedAbnormally" value="511">
9625	<desc>Process terminated abnormally.</desc>
9626	</const>
9627	<const name="TimedOutKilled" value="512">
9628	<desc>Process timed out and was killed.</desc>
9629	</const>
9630	<const name="TimedOutAbnormally" value="513">
9631	<desc>Process timed out and was not killed successfully.</desc>
9632	</const>
9633	<const name="Down" value="600">
9634	<desc>Service/OS is stopping, process was killed.</desc>
9635	</const>
9636	<const name="Error" value="800">
9637	<desc>Something went wrong.</desc>
9638	</const>
9639	</enum>
9640
9641	<enum
9642	name="ProcessInputStatus"
9643	uuid="a4a0ef9c-29cc-4805-9803-c8215ae9da6c"
9644	>
9645	<desc>
9646	Process input statuses.
9647	</desc>
9648
9649	<const name="Undefined" value="0">
9650	<desc>Undefined state.</desc>
9651	</const>
9652	<const name="Broken" value="1">
9653	<desc>Input pipe is broken.</desc>
9654	</const>
9655	<const name="Available" value="10">
9656	<desc>Input pipe became available for writing.</desc>
9657	</const>
9658	<const name="Written" value="50">
9659	<desc>Data has been successfully written.</desc>
9660	</const>
9661	<const name="Overflow" value="100">
9662	<desc>Too much input data supplied, data overflow.</desc>
9663	</const>
9664	</enum>
9665
9666	<enum
9667	name="FileStatus"
9668	uuid="8c86468b-b97b-4080-8914-e29f5b0abd2c"
9669	>
9670	<desc>
9671	File statuses.
9672	</desc>
9673
9674	<const name="Undefined" value="0">
9675	<desc>File is in an undefined state.</desc>
9676	</const>
9677	<const name="Opening" value="10">
9678	<desc>Guest file is opening.</desc>
9679	</const>
9680	<const name="Open" value="100">
9681	<desc>Guest file has been successfully opened.</desc>
9682	</const>
9683	<const name="Closing" value="150">
9684	<desc>Guest file closing.</desc>
9685	</const>
9686	<const name="Closed" value="200">
9687	<desc>Guest file has been closed.</desc>
9688	</const>
9689	<const name="Down" value="600">
9690	<desc>Service/OS is stopping, guest file was closed.</desc>
9691	</const>
9692	<const name="Error" value="800">
9693	<desc>Something went wrong.</desc>
9694	</const>
9695	</enum>
9696
9697	<enum
9698	name="FsObjType"
9699	uuid="a1ed437c-b3c3-4ca2-b19c-4239d658d5e8"
9700	>
9701	<desc>
9702	File system object type.
9703	</desc>
9704
9705	<const name="Undefined" value="0">
9706	<desc>Type is undefined / unknown.</desc>
9707	</const>
9708	<const name="FIFO" value="1">
9709	<desc>Named pipe.</desc>
9710	</const>
9711	<const name="DevChar" value="10">
9712	<desc>Character device.</desc>
9713	</const>
9714	<const name="DevBlock" value="11">
9715	<desc>Block device.</desc>
9716	</const>
9717	<const name="Directory" value="50">
9718	<desc>Directory.</desc>
9719	</const>
9720	<const name="File" value="80">
9721	<desc>File.</desc>
9722	</const>
9723	<const name="Symlink" value="100">
9724	<desc>Symlink.</desc>
9725	</const>
9726	<const name="Socket" value="200">
9727	<desc>Socket.</desc>
9728	</const>
9729	<const name="Whiteout" value="400">
9730	<desc>Whiteout.</desc>
9731	</const>
9732	</enum>
9733
9734	<enum
9735	name="DragAndDropAction"
9736	uuid="47f3b162-c107-4fcd-bfa7-54b8135c441e"
9737	>
9738	<desc>
9739	Possible actions within an Drag and Drop operation.
9740	</desc>
9741
9742	<const name="Ignore" value="0">
9743	<desc>Do nothing.</desc>
9744	</const>
9745
9746	<const name="Copy" value="1">
9747	<desc>Copy the item to the target.</desc>
9748	</const>
9749
9750	<const name="Move" value="2">
9751	<desc>Move the item to the target.</desc>
9752	</const>
9753
9754	<const name="Link" value="3">
9755	<desc>Link the item from within the target.</desc>
9756	</const>
9757	</enum>
9758
9759	<enum
9760	name="DirectoryOpenFlag"
9761	uuid="5138837a-8fd2-4194-a1b0-08f7bc3949d0"
9762	>
9763	<desc>
9764	Directory open flags.
9765	</desc>
9766	<const name="None" value="0">
9767	<desc>No flag set.</desc>
9768	</const>
9769	<const name="NoSymlinks" value="1">
9770	<desc>Don't allow symbolic links as part of the path.</desc>
9771	</const>
9772	</enum>
9773
9774	<interface
9775	name="IGuestSession" extends="$unknown"
9776	uuid="c8e8607b-5e67-4073-8f14-146515d0c1ff"
9777	wsmap="managed"
9778	>
9779	<desc>
9780	A guest session represents one impersonated user account on the guest, so
9781	every operation will use the same credentials specified when creating
9782	the session object via <link to="IGuest::createSession"/>.
9783
9784	There can be a maximum of 32 sessions at once per VM. Each session keeps
9785	track of its started guest processes, opened guest files or guest directories.
9786	To work on guest files or directories a guest session offers methods to open
9787	or create such objects (see <link to="IGuestSession::fileOpen"/> or
9788	<link to="IGuestSession::directoryOpen"/> for example).
9789
9790	When done with either of these objects, including the guest session itself,
9791	use the appropriate close() method to let the object do its cleanup work.
9792
9793	Every guest session has its own environment variable block which gets
9794	automatically applied when starting a new guest process via
9795	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
9796	To override (or unset) certain environment variables already set by the
9797	guest session, one can specify a per-process environment block when using
9798	one of the both above mentioned process creation calls.
9799	</desc>
9800
9801	<attribute name="user" type="wstring" readonly="yes">
9802	<desc>Returns the user name used by this session to impersonate
9803	users on the guest.
9804	</desc>
9805	</attribute>
9806	<attribute name="domain" type="wstring" readonly="yes">
9807	<desc>Returns the domain name used by this session to impersonate
9808	users on the guest.
9809	</desc>
9810	</attribute>
9811	<attribute name="name" type="wstring" readonly="yes">
9812	<desc>Returns the session's friendly name.</desc>
9813	</attribute>
9814	<attribute name="id" type="unsigned long" readonly="yes">
9815	<desc>Returns the internal session ID.</desc>
9816	</attribute>
9817	<attribute name="timeout" type="unsigned long">
9818	<desc>
9819	Returns the session timeout (in ms).
9820	<result name="E_NOTIMPL">
9821	The method is not implemented yet.
9822	</result>
9823	</desc>
9824	</attribute>
9825	<attribute name="status" type="GuestSessionStatus" readonly="yes">
9826	<desc>Returns the current session status.</desc>
9827	</attribute>
9828	<attribute name="environment" type="wstring" safearray="yes">
9829	<desc>
9830	Returns the current session environment.
9831	</desc>
9832	</attribute>
9833	<attribute name="processes" type="IGuestProcess" readonly="yes" safearray="yes">
9834	<desc>
9835	Returns all current guest processes.
9836	</desc>
9837	</attribute>
9838	<attribute name="directories" type="IGuestDirectory" readonly="yes" safearray="yes">
9839	<desc>
9840	Returns all currently opened guest directories.
9841	</desc>
9842	</attribute>
9843	<attribute name="files" type="IGuestFile" readonly="yes" safearray="yes">
9844	<desc>
9845	Returns all currently opened guest files.
9846	</desc>
9847	</attribute>
9848	<attribute name="eventSource" type="IEventSource" readonly="yes">
9849	<desc>
9850	Event source for guest session events.
9851	</desc>
9852	</attribute>
9853
9854	<method name="close">
9855	<desc>
9856	Closes this session. All opened guest directories, files and
9857	processes which are not referenced by clients anymore will be
9858	uninitialized.
9859	</desc>
9860	</method>
9861
9862	<method name="copyFrom">
9863	<desc>
9864	Copies a file from guest to the host.
9865
9866	<result name="VBOX_E_IPRT_ERROR">
9867	Error starting the copy operation.
9868	</result>
9869	</desc>
9870	<param name="source" type="wstring" dir="in">
9871	<desc>Source file on the guest to copy to the host.</desc>
9872	</param>
9873	<param name="dest" type="wstring" dir="in">
9874	<desc>Destination file name on the host.</desc>
9875	</param>
9876	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9877	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9878	</param>
9879	<param name="progress" type="IProgress" dir="return">
9880	<desc>Progress object to track the operation completion.</desc>
9881	</param>
9882	</method>
9883
9884	<method name="copyTo">
9885	<desc>
9886	Copies a file from host to the guest.
9887
9888	<result name="VBOX_E_IPRT_ERROR">
9889	Error starting the copy operation.
9890	</result>
9891	</desc>
9892	<param name="source" type="wstring" dir="in">
9893	<desc>Source file on the host to copy to the guest.</desc>
9894	</param>
9895	<param name="dest" type="wstring" dir="in">
9896	<desc>Destination file name on the guest.</desc>
9897	</param>
9898	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9899	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9900	</param>
9901	<param name="progress" type="IProgress" dir="return">
9902	<desc>Progress object to track the operation completion.</desc>
9903	</param>
9904	</method>
9905
9906	<method name="directoryCreate">
9907	<desc>
9908	Create a directory on the guest.
9909
9910	<result name="VBOX_E_IPRT_ERROR">
9911	Error while creating the directory.
9912	</result>
9913	</desc>
9914	<param name="path" type="wstring" dir="in">
9915	<desc>Full path of directory to create.</desc>
9916	</param>
9917	<param name="mode" type="unsigned long" dir="in">
9918	<desc>File creation mode.</desc>
9919	</param>
9920	<param name="flags" type="DirectoryCreateFlag" dir="in" safearray="yes">
9921	<desc>Creation flags; see <link to="DirectoryCreateFlag"/> for more information.</desc>
9922	</param>
9923	</method>
9924
9925	<method name="directoryCreateTemp">
9926	<desc>
9927	Create a temporary directory on the guest.
9928
9929	<result name="VBOX_E_NOT_SUPPORTED">
9930	The operation is not possible as requested on this particular
9931	guest type.
9932	</result>
9933	<result name="E_INVALIDARG">
9934	Invalid argument. This includes an incorrectly formatted template,
9935	or a non-absolute path.
9936	</result>
9937	<result name="VBOX_E_IPRT_ERROR">
9938	The temporary directory could not be created. Possible reasons
9939	include a non-existing path or an insecure path when the secure
9940	option was requested.
9941	</result>
9942	</desc>
9943	<param name="templateName" type="wstring" dir="in">
9944	<desc>Template for the name of the directory to create. This must
9945	contain at least one 'X' character. The first group of consecutive
9946	'X' characters in the template will be replaced by a random
9947	alphanumeric string to produce a unique name.</desc>
9948	</param>
9949	<param name="mode" type="unsigned long" dir="in">
9950	<desc>The mode of the directory to create. Use 0700 unless there are
9951	reasons not to. This parameter is ignored if "secure" is specified.
9952	</desc>
9953	</param>
9954	<param name="path" type="wstring" dir="in">
9955	<desc>The absolute path to create the temporary directory in.</desc>
9956	</param>
9957	<param name="secure" type="boolean" dir="in">
9958	<desc>Whether to fail if the directory can not be securely created.
9959	Currently this means that another unprivileged user cannot
9960	manipulate the path specified or remove the temporary directory
9961	after it has been created. Also causes the mode specified to be
9962	ignored. May not be supported on all guest types.</desc>
9963	</param>
9964	<param name="directory" type="wstring" dir="return">
9965	<desc>On success this will contain the name of the directory created
9966	with full path.</desc>
9967	</param>
9968	</method>
9969
9970	<method name="directoryExists">
9971	<desc>
9972	Checks whether a directory exists on the guest or not.
9973
9974	<result name="VBOX_E_IPRT_ERROR">
9975	Error while checking existence of the directory specified.
9976	</result>
9977	</desc>
9978	<param name="path" type="wstring" dir="in">
9979	<desc>Directory to check existence for.</desc>
9980	</param>
9981	<param name="exists" type="boolean" dir="return">
9982	<desc>Returns @c true if the directory exists, @c false if not.</desc>
9983	</param>
9984	</method>
9985
9986	<method name="directoryOpen">
9987	<desc>
9988	Opens a directory and creates a <link to="IGuestDirectory"/> object that
9989	can be used for further operations.
9990
9991	<result name="VBOX_E_OBJECT_NOT_FOUND">
9992	Directory to open was not found.
9993	</result>
9994	<result name="VBOX_E_IPRT_ERROR">
9995	Error while opening the directory.
9996	</result>
9997	</desc>
9998	<param name="path" type="wstring" dir="in">
9999	<desc>Full path to file to open.</desc>
10000	</param>
10001	<param name="filter" type="wstring" dir="in">
10002	<desc>Open filter to apply. This can include wildcards like ? and *.</desc>
10003	</param>
10004	<param name="flags" type="DirectoryOpenFlag" dir="in" safearray="yes">
10005	<desc>Open flags; see <link to="DirectoryOpenFlag"/> for more information.</desc>
10006	</param>
10007	<param name="directory" type="IGuestDirectory" dir="return">
10008	<desc><link to="IGuestDirectory"/> object containing the opened directory.</desc>
10009	</param>
10010	</method>
10011
10012	<method name="directoryQueryInfo">
10013	<desc>
10014	Queries information of a directory on the guest.
10015
10016	<result name="VBOX_E_OBJECT_NOT_FOUND">
10017	Directory to query information for was not found.
10018	</result>
10019	<result name="VBOX_E_IPRT_ERROR">
10020	Error querying information.
10021	</result>
10022	</desc>
10023	<param name="path" type="wstring" dir="in">
10024	<desc>Directory to query information for.</desc>
10025	</param>
10026	<param name="info" type="IGuestFsObjInfo" dir="return">
10027	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10028	</param>
10029	</method>
10030
10031	<method name="directoryRemove">
10032	<desc>
10033	Removes a guest directory if not empty.
10034
10035	<result name="E_NOTIMPL">
10036	The method is not implemented yet.
10037	</result>
10038	</desc>
10039	<param name="path" type="wstring" dir="in">
10040	<desc>Full path of directory to remove.</desc>
10041	</param>
10042	</method>
10043
10044	<method name="directoryRemoveRecursive">
10045	<desc>
10046	Removes a guest directory recursively.
10047
10048	<result name="E_NOTIMPL">
10049	The method is not implemented yet.
10050	</result>
10051	</desc>
10052	<param name="path" type="wstring" dir="in">
10053	<desc>Full path of directory to remove recursively.</desc>
10054	</param>
10055	<param name="flags" type="DirectoryRemoveRecFlag" dir="in" safearray="yes">
10056	<desc>Remove flags; see <link to="DirectoryRemoveRecFlag"/> for more information.</desc>
10057	</param>
10058	<param name="progress" type="IProgress" dir="return">
10059	<desc>Progress object to track the operation completion.</desc>
10060	</param>
10061	</method>
10062
10063	<method name="directoryRename">
10064	<desc>
10065	Renames a directory on the guest.
10066
10067	<result name="E_NOTIMPL">
10068	The method is not implemented yet.
10069	</result>
10070	</desc>
10071	<param name="source" type="wstring" dir="in">
10072	<desc>Source directory to rename.</desc>
10073	</param>
10074	<param name="dest" type="wstring" dir="in">
10075	<desc>Destination directory to rename the source to.</desc>
10076	</param>
10077	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10078	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10079	</param>
10080	</method>
10081
10082	<method name="directorySetACL">
10083	<desc>
10084	Sets the ACL (Access Control List) of a guest directory.
10085
10086	<result name="E_NOTIMPL">
10087	The method is not implemented yet.
10088	</result>
10089	</desc>
10090	<param name="path" type="wstring" dir="in">
10091	<desc>Full path of directory to set the ACL for.</desc>
10092	</param>
10093	<param name="acl" type="wstring" dir="in">
10094	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10095	</param>
10096	</method>
10097
10098	<method name="environmentClear">
10099	<desc>
10100	Clears (deletes) all session environment variables.
10101
10102	<result name="VBOX_E_IPRT_ERROR">
10103	Error while clearing the session environment variables.
10104	</result>
10105	</desc>
10106	</method>
10107
10108	<method name="environmentGet">
10109	<desc>
10110	Gets the value of a session environment variable.
10111
10112	<result name="VBOX_E_IPRT_ERROR">
10113	Error while getting the value of the session environment variable.
10114	</result>
10115	</desc>
10116	<param name="name" type="wstring" dir="in">
10117	<desc>Name of session environment variable to get the value for.</desc>
10118	</param>
10119	<param name="value" type="wstring" dir="return">
10120	<desc>
10121	Value of the session environment variable specified. If this variable
10122	does not exist and empty value will be returned.
10123	</desc>
10124	</param>
10125	</method>
10126
10127	<method name="environmentSet">
10128	<desc>
10129	Sets a session environment variable.
10130
10131	<result name="VBOX_E_IPRT_ERROR">
10132	Error while setting the session environment variable.
10133	</result>
10134	</desc>
10135	<param name="name" type="wstring" dir="in">
10136	<desc>Name of session environment variable to set.</desc>
10137	</param>
10138	<param name="value" type="wstring" dir="in">
10139	<desc>Value to set the session environment variable to.</desc>
10140	</param>
10141	</method>
10142
10143	<method name="environmentUnset">
10144	<desc>
10145	Unsets session environment variable.
10146
10147	<result name="VBOX_E_IPRT_ERROR">
10148	Error while unsetting the session environment variable.
10149	</result>
10150	</desc>
10151	<param name="name" type="wstring" dir="in">
10152	<desc>Name of session environment variable to unset (clear).</desc>
10153	</param>
10154	</method>
10155
10156	<method name="fileCreateTemp">
10157	<desc>
10158	Creates a temporary file on the guest.
10159
10160	<result name="VBOX_E_NOT_SUPPORTED">
10161	The operation is not possible as requested on this particular
10162	guest type.
10163	</result>
10164	<result name="E_INVALIDARG">
10165	Invalid argument. This includes an incorrectly formatted template,
10166	or a non-absolute path.
10167	</result>
10168	<result name="VBOX_E_IPRT_ERROR">
10169	The temporary file could not be created. Possible reasons include
10170	a non-existing path or an insecure path when the secure
10171	option was requested.
10172	</result>
10173	</desc>
10174	<param name="templateName" type="wstring" dir="in">
10175	<desc>Template for the name of the file to create. This must contain
10176	at least one 'X' character. The first group of consecutive 'X'
10177	characters in the template will be replaced by a random
10178	alphanumeric string to produce a unique name.
10179	</desc>
10180	</param>
10181	<param name="mode" type="unsigned long" dir="in">
10182	<desc>The mode of the file to create. Use 0700 unless there are
10183	reasons not to. This parameter is ignored if "secure" is specified.
10184	</desc>
10185	</param>
10186	<param name="path" type="wstring" dir="in">
10187	<desc>The absolute path to create the temporary file in.</desc>
10188	</param>
10189	<param name="secure" type="boolean" dir="in">
10190	<desc>Whether to fail if the file can not be securely created.
10191	Currently this means that another unprivileged user cannot
10192	manipulate the path specified or remove the temporary file after
10193	it has been created. Also causes the mode specified to be ignored.
10194	May not be supported on all guest types.</desc>
10195	</param>
10196	<param name="file" type="IGuestFile" dir="return">
10197	<desc>On success this will contain an open file object for the new
10198	temporary file.
10199	</desc>
10200	</param>
10201	</method>
10202
10203	<method name="fileExists">
10204	<desc>
10205	Checks whether a file exists on the guest or not.
10206
10207	<result name="VBOX_E_IPRT_ERROR">
10208	Error while checking existence of the file specified.
10209	</result>
10210	</desc>
10211	<param name="path" type="wstring" dir="in">
10212	<desc>File to check existence for.</desc>
10213	</param>
10214	<param name="exists" type="boolean" dir="return">
10215	<desc>Returns @c true if the file exists, @c false if not.</desc>
10216	</param>
10217	</method>
10218
10219	<method name="fileRemove">
10220	<desc>
10221	Removes a single file on the guest.
10222
10223	<result name="VBOX_E_OBJECT_NOT_FOUND">
10224	File to remove was not found.
10225	</result>
10226	<result name="VBOX_E_IPRT_ERROR">
10227	Error while removing the file.
10228	</result>
10229	</desc>
10230	<param name="path" type="wstring" dir="in">
10231	<desc>Path to the file to remove.</desc>
10232	</param>
10233	</method>
10234
10235	<method name="fileOpen">
10236	<desc>
10237	Opens a file and creates a <link to="IGuestFile"/> object that
10238	can be used for further operations.
10239
10240	<result name="VBOX_E_OBJECT_NOT_FOUND">
10241	File to open was not found.
10242	</result>
10243	<result name="VBOX_E_IPRT_ERROR">
10244	Error while opening the file.
10245	</result>
10246	</desc>
10247	<param name="path" type="wstring" dir="in">
10248	<desc>Full path to file to open.</desc>
10249	</param>
10250	<param name="openMode" type="wstring" dir="in">
10251	<desc>The file open mode.</desc>
10252	</param>
10253	<param name="disposition" type="wstring" dir="in">
10254	<desc>The file disposition.</desc>
10255	</param>
10256	<param name="creationMode" type="unsigned long" dir="in">
10257	<desc>The file creation mode.</desc>
10258	</param>
10259	<param name="offset" type="long long" dir="in">
10260	<desc>The initial read/write offset.</desc>
10261	</param>
10262	<param name="file" type="IGuestFile" dir="return">
10263	<desc><link to="IGuestFile"/> object representing the opened file.</desc>
10264	</param>
10265	</method>
10266
10267	<method name="fileQueryInfo">
10268	<desc>
10269	Queries information of a file on the guest.
10270
10271	<result name="VBOX_E_OBJECT_NOT_FOUND">
10272	File to query information for was not found.
10273	</result>
10274	<result name="VBOX_E_IPRT_ERROR">
10275	Error querying information.
10276	</result>
10277	</desc>
10278	<param name="path" type="wstring" dir="in">
10279	<desc>File to query information for.</desc>
10280	</param>
10281	<param name="info" type="IGuestFsObjInfo" dir="return">
10282	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10283	</param>
10284	</method>
10285
10286	<method name="fileQuerySize">
10287	<desc>
10288	Queries the size of a file on the guest.
10289
10290	<result name="VBOX_E_OBJECT_NOT_FOUND">
10291	File to rename was not found.
10292	</result>
10293	<result name="VBOX_E_IPRT_ERROR">
10294	Error querying file size.
10295	</result>
10296	</desc>
10297	<param name="path" type="wstring" dir="in">
10298	<desc>File to query the size for.</desc>
10299	</param>
10300	<param name="size" type="long long" dir="return">
10301	<desc>Queried file size.</desc>
10302	</param>
10303	</method>
10304
10305	<method name="fileRename">
10306	<desc>
10307	Renames a file on the guest.
10308
10309	<result name="E_NOTIMPL">
10310	The method is not implemented yet.
10311	</result>
10312	</desc>
10313	<param name="source" type="wstring" dir="in">
10314	<desc>Source file to rename.</desc>
10315	</param>
10316	<param name="dest" type="wstring" dir="in">
10317	<desc>Destination file to rename the source to.</desc>
10318	</param>
10319	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10320	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10321	</param>
10322	</method>
10323
10324	<method name="fileSetACL">
10325	<desc>
10326	Sets the ACL (Access Control List) of a file on the guest.
10327
10328	<result name="E_NOTIMPL">
10329	The method is not implemented yet.
10330	</result>
10331	</desc>
10332	<param name="file" type="wstring" dir="in">
10333	<desc>Full path of file to set the ACL for.</desc>
10334	</param>
10335	<param name="acl" type="wstring" dir="in">
10336	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10337	</param>
10338	</method>
10339
10340	<method name="processCreate">
10341	<desc>
10342	Creates a new process running on the guest. The new process will be
10343	started asynchronously, meaning on return of this function it is not
10344	guaranteed that the guest process is in a started state. To wait for
10345	successful startup, use the <link to="IProcess::waitFor"/> call.
10346
10347	<note>
10348	Starting at VirtualBox 4.2 guest process execution by default is limited
10349	to serve up to 255 guest processes at a time. If all 255 guest processes
10350	are still active and running, creating a new guest process will result in an
10351	appropriate error message.
10352
10353	If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr
10354	is / are set, the guest process will not exit until all data from the specified
10355	stream(s) is / are read out.
10356
10357	To raise or lower the guest process execution limit, either the guest property
10358	"/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService'
10359	command line by specifying "--control-procs-max-kept" needs to be modified.
10360	A restart of the guest OS is required afterwards. To serve unlimited guest
10361	processes, a value of "0" needs to be set (not recommended).
10362	</note>
10363
10364	<result name="VBOX_E_IPRT_ERROR">
10365	Error creating guest process.
10366	</result>
10367	</desc>
10368	<param name="command" type="wstring" dir="in">
10369	<desc>
10370	Full path name of the command to execute on the guest; the
10371	commands has to exists in the guest VM in order to be executed.
10372	</desc>
10373	</param>
10374	<param name="arguments" type="wstring" dir="in" safearray="yes">
10375	<desc>Array of arguments passed to the execution command.</desc>
10376	</param>
10377	<param name="environment" type="wstring" dir="in" safearray="yes">
10378	<desc>
10379	<para>Environment variables that can be set while the command is being
10380	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10381	variable just set its name ("NAME") without a value.</para>
10382	<para>This parameter can be used to override environment variables set by
10383	the guest session, which will be applied to the newly started process
10384	in any case.</para>
10385	</desc>
10386	</param>
10387	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10388	<desc>
10389	Process creation flags;
10390	see <link to="ProcessCreateFlag"/> for more information.
10391	</desc>
10392	</param>
10393	<param name="timeoutMS" type="unsigned long" dir="in">
10394	<desc>
10395	Timeout (in ms) for limiting the guest process' running time.
10396	Pass 0 for an infinite timeout. On timeout the guest process will be
10397	killed and its status will be put to an appropriate value. See
10398	<link to="ProcessStatus"/> for more information.
10399	</desc>
10400	</param>
10401	<param name="guestProcess" type="IGuestProcess" dir="return">
10402	<desc>Guest process object of the newly created process.</desc>
10403	</param>
10404	</method>
10405
10406	<method name="processCreateEx">
10407	<desc>
10408	<para>Creates a new process running on the guest. Extended version for
10409	also setting the process priority and affinity.</para>
10410
10411	<para>See <link to="IGuestSession::processCreate"/> for more
10412	information.</para>
10413	</desc>
10414	<param name="command" type="wstring" dir="in">
10415	<desc>
10416	Full path name of the command to execute on the guest; the
10417	commands has to exists in the guest VM in order to be executed.
10418	</desc>
10419	</param>
10420	<param name="arguments" type="wstring" dir="in" safearray="yes">
10421	<desc>Array of arguments passed to the execution command.</desc>
10422	</param>
10423	<param name="environment" type="wstring" dir="in" safearray="yes">
10424	<desc>
10425	<para>Environment variables that can be set while the command is being
10426	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10427	variable just set its name ("NAME") without a value.</para>
10428	<para>This parameter can be used to override environment variables set by
10429	the guest session, which will be applied to the newly started process
10430	in any case.</para>
10431	</desc>
10432	</param>
10433	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10434	<desc>
10435	Process creation flags;
10436	see <link to="ProcessCreateFlag"/> for more information.
10437	</desc>
10438	</param>
10439	<param name="timeoutMS" type="unsigned long" dir="in">
10440	<desc>
10441	Timeout (in ms) for limiting the guest process' running time.
10442	Pass 0 for an infinite timeout. On timeout the guest process will be
10443	killed and its status will be put to an appropriate value. See
10444	<link to="ProcessStatus"/> for more information.
10445	</desc>
10446	</param>
10447	<param name="priority" type="ProcessPriority" dir="in">
10448	<desc>
10449	Process priority to use for execution;
10450	see see <link to="ProcessPriority"/> for more information.</desc>
10451	</param>
10452	<param name="affinity" type="long" dir="in" safearray="yes">
10453	<desc>
10454	Process affinity to use for execution. This parameter
10455	is not implemented yet.
10456	</desc>
10457	</param>
10458	<param name="guestProcess" type="IGuestProcess" dir="return">
10459	<desc>Guest process object of the newly created process.</desc>
10460	</param>
10461	</method>
10462
10463	<method name="processGet">
10464	<desc>
10465	Gets a certain guest process by its process ID (PID).
10466	</desc>
10467	<param name="pid" type="unsigned long" dir="in">
10468	<desc>Process ID (PID) to get guest process for.</desc>
10469	</param>
10470	<param name="guestProcess" type="IGuestProcess" dir="return">
10471	<desc>Guest process of specified process ID (PID).</desc>
10472	</param>
10473	</method>
10474
10475	<method name="symlinkCreate">
10476	<desc>
10477	Creates a symbolic link on the guest.
10478
10479	<result name="E_NOTIMPL">
10480	The method is not implemented yet.
10481	</result>
10482	</desc>
10483	<param name="source" type="wstring" dir="in">
10484	<desc>The name of the symbolic link.</desc>
10485	</param>
10486	<param name="target" type="wstring" dir="in">
10487	<desc>The path to the symbolic link target.</desc>
10488	</param>
10489	<param name="type" type="SymlinkType" dir="in">
10490	<desc>
10491	The symbolic link type;
10492	see <link to="SymlinkReadFlag"/> for more information.
10493	</desc>
10494	</param>
10495	</method>
10496
10497	<method name="symlinkExists">
10498	<desc>
10499	Checks whether a symbolic link exists on the guest or not.
10500
10501	<result name="E_NOTIMPL">
10502	The method is not implemented yet.
10503	</result>
10504	</desc>
10505	<param name="symlink" type="wstring" dir="in">
10506	<desc>Symbolic link to check existence for.</desc>
10507	</param>
10508	<param name="exists" type="boolean" dir="return">
10509	<desc>Returns @c true if the symbolic link exists, @c false if not.</desc>
10510	</param>
10511	</method>
10512
10513	<method name="symlinkRead">
10514	<desc>
10515	Reads a symbolic link on the guest.
10516
10517	<result name="E_NOTIMPL">
10518	The method is not implemented yet.
10519	</result>
10520	</desc>
10521	<param name="symlink" type="wstring" dir="in">
10522	<desc>Full path to symbolic link to read.</desc>
10523	</param>
10524	<param name="flags" type="SymlinkReadFlag" dir="in" safearray="yes">
10525	<desc>
10526	Read flags; see <link to="SymlinkReadFlag"/> for more information.
10527	</desc>
10528	</param>
10529	<param name="target" type="wstring" dir="return">
10530	<desc>
10531	Target of the symbolic link pointing to, if found.
10532	</desc>
10533	</param>
10534	</method>
10535
10536	<method name="symlinkRemoveDirectory">
10537	<desc>
10538	Removes a symbolic link on the guest if it's a directory.
10539
10540	<result name="E_NOTIMPL">
10541	The method is not implemented yet.
10542	</result>
10543	</desc>
10544	<param name="path" type="wstring" dir="in">
10545	<desc>Symbolic link to remove.</desc>
10546	</param>
10547	</method>
10548
10549	<method name="symlinkRemoveFile">
10550	<desc>
10551	Removes a symbolic link on the guest if it's a file.
10552
10553	<result name="E_NOTIMPL">
10554	The method is not implemented yet.
10555	</result>
10556	</desc>
10557	<param name="file" type="wstring" dir="in">
10558	<desc>Symbolic link to remove.</desc>
10559	</param>
10560	</method>
10561
10562	<method name="waitFor">
10563	<desc>
10564	Waits for one more events to happen.
10565	</desc>
10566	<param name="waitFor" type="unsigned long" dir="in">
10567	<desc>
10568	Specifies what to wait for;
10569	see <link to="GuestSessionWaitForFlag"/> for more information.
10570	</desc>
10571	</param>
10572	<param name="timeoutMS" type="unsigned long" dir="in">
10573	<desc>
10574	Timeout (in ms) to wait for the operation to complete.
10575	Pass 0 for an infinite timeout.
10576	</desc>
10577	</param>
10578	<param name="reason" type="GuestSessionWaitResult" dir="return">
10579	<desc>
10580	The overall wait result;
10581	see <link to="GuestSessionWaitResult"/> for more information.
10582	</desc>
10583	</param>
10584	</method>
10585
10586	<method name="waitForArray">
10587	<desc>
10588	Waits for one more events to happen.
10589	Scriptable version of <link to="#waitFor" />.
10590	</desc>
10591	<param name="waitFor" type="GuestSessionWaitForFlag" dir="in" safearray="yes">
10592	<desc>
10593	Specifies what to wait for;
10594	see <link to="GuestSessionWaitForFlag"/> for more information.
10595	</desc>
10596	</param>
10597	<param name="timeoutMS" type="unsigned long" dir="in">
10598	<desc>
10599	Timeout (in ms) to wait for the operation to complete.
10600	Pass 0 for an infinite timeout.
10601	</desc>
10602	</param>
10603	<param name="reason" type="GuestSessionWaitResult" dir="return">
10604	<desc>
10605	The overall wait result;
10606	see <link to="GuestSessionWaitResult"/> for more information.
10607	</desc>
10608	</param>
10609	</method>
10610
10611	</interface>
10612
10613	<interface
10614	name="IProcess" extends="$unknown"
10615	uuid="5a4fe06d-8cb1-40ff-ac9e-9676e32f706e"
10616	wsmap="managed"
10617	>
10618	<desc>
10619	Abstract parent interface for processes handled by VirtualBox.
10620	</desc>
10621
10622	<attribute name="arguments" type="wstring" readonly="yes" safearray="yes">
10623	<desc>
10624	The arguments this process is using for execution.
10625	</desc>
10626	</attribute>
10627	<attribute name="environment" type="wstring" readonly="yes" safearray="yes">
10628	<desc>
10629	The environment block this process is using during execution.
10630	</desc>
10631	</attribute>
10632	<attribute name="eventSource" type="IEventSource" readonly="yes">
10633	<desc>
10634	Event source for VirtualBox events.
10635	</desc>
10636	</attribute>
10637	<attribute name="executablePath" type="wstring" readonly="yes">
10638	<desc>Full path of the actual executable image.</desc>
10639	</attribute>
10640	<attribute name="exitCode" type="long" readonly="yes">
10641	<desc>
10642	The exit code. Only available when the process has been
10643	terminated normally.
10644	</desc>
10645	</attribute>
10646	<attribute name="name" type="wstring" readonly="yes">
10647	<desc>
10648	The friendly name of this process.
10649	</desc>
10650	</attribute>
10651	<attribute name="PID" type="unsigned long" readonly="yes">
10652	<desc>
10653	The process ID (PID).
10654	</desc>
10655	</attribute>
10656	<attribute name="status" type="ProcessStatus" readonly="yes">
10657	<desc>
10658	The current process status; see <link to="ProcessStatus"/>
10659	for more information.
10660	</desc>
10661	</attribute>
10662
10663	<method name="waitFor">
10664	<desc>
10665	Waits for one more events to happen.
10666	</desc>
10667	<param name="waitFor" type="unsigned long" dir="in">
10668	<desc>
10669	Specifies what to wait for;
10670	see <link to="ProcessWaitForFlag"/> for more information.
10671	</desc>
10672	</param>
10673	<param name="timeoutMS" type="unsigned long" dir="in">
10674	<desc>
10675	Timeout (in ms) to wait for the operation to complete.
10676	Pass 0 for an infinite timeout.
10677	</desc>
10678	</param>
10679	<param name="reason" type="ProcessWaitResult" dir="return">
10680	<desc>
10681	The overall wait result;
10682	see <link to="ProcessWaitResult"/> for more information.
10683	</desc>
10684	</param>
10685	</method>
10686
10687	<method name="waitForArray">
10688	<desc>
10689	Waits for one more events to happen.
10690	Scriptable version of <link to="#waitFor" />.
10691	</desc>
10692	<param name="waitFor" type="ProcessWaitForFlag" dir="in" safearray="yes">
10693	<desc>
10694	Specifies what to wait for;
10695	see <link to="ProcessWaitForFlag"/> for more information.
10696	</desc>
10697	</param>
10698	<param name="timeoutMS" type="unsigned long" dir="in">
10699	<desc>
10700	Timeout (in ms) to wait for the operation to complete.
10701	Pass 0 for an infinite timeout.
10702	</desc>
10703	</param>
10704	<param name="reason" type="ProcessWaitResult" dir="return">
10705	<desc>
10706	The overall wait result;
10707	see <link to="ProcessWaitResult"/> for more information.
10708	</desc>
10709	</param>
10710	</method>
10711
10712	<method name="read">
10713	<desc>
10714	Reads data from a running process.
10715	</desc>
10716	<param name="handle" type="unsigned long" dir="in">
10717	<desc>Handle to read from. Usually 0 is stdin.</desc>
10718	</param>
10719	<param name="toRead" type="unsigned long" dir="in">
10720	<desc>Number of bytes to read.</desc>
10721	</param>
10722	<param name="timeoutMS" type="unsigned long" dir="in">
10723	<desc>
10724	Timeout (in ms) to wait for the operation to complete.
10725	Pass 0 for an infinite timeout.
10726	</desc>
10727	</param>
10728	<param name="data" type="octet" dir="return" safearray="yes">
10729	<desc>Array of data read.</desc>
10730	</param>
10731	</method>
10732
10733	<method name="write">
10734	<desc>
10735	Writes data to a running process.
10736	</desc>
10737	<param name="handle" type="unsigned long" dir="in">
10738	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10739	</param>
10740	<param name="flags" type="unsigned long" dir="in">
10741	<desc>
10742	A combination of <link to="ProcessInputFlag"/> flags.
10743	</desc>
10744	</param>
10745	<param name="data" type="octet" dir="in" safearray="yes">
10746	<desc>
10747	Array of bytes to write. The size of the array also specifies
10748	how much to write.
10749	</desc>
10750	</param>
10751	<param name="timeoutMS" type="unsigned long" dir="in">
10752	<desc>
10753	Timeout (in ms) to wait for the operation to complete.
10754	Pass 0 for an infinite timeout.
10755	</desc>
10756	</param>
10757	<param name="written" type="unsigned long" dir="return">
10758	<desc>How much bytes were written.</desc>
10759	</param>
10760	</method>
10761
10762	<method name="writeArray">
10763	<desc>
10764	Writes data to a running process.
10765	Scriptable version of <link to="#write" />.
10766	</desc>
10767	<param name="handle" type="unsigned long" dir="in">
10768	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10769	</param>
10770	<param name="flags" type="ProcessInputFlag" dir="in" safearray="yes">
10771	<desc>
10772	A combination of <link to="ProcessInputFlag"/> flags.
10773	</desc>
10774	</param>
10775	<param name="data" type="octet" dir="in" safearray="yes">
10776	<desc>
10777	Array of bytes to write. The size of the array also specifies
10778	how much to write.
10779	</desc>
10780	</param>
10781	<param name="timeoutMS" type="unsigned long" dir="in">
10782	<desc>
10783	Timeout (in ms) to wait for the operation to complete.
10784	Pass 0 for an infinite timeout.
10785	</desc>
10786	</param>
10787	<param name="written" type="unsigned long" dir="return">
10788	<desc>How much bytes were written.</desc>
10789	</param>
10790	</method>
10791
10792	<method name="terminate">
10793	<desc>
10794	Terminates (kills) a running process.
10795	</desc>
10796	</method>
10797	</interface>
10798
10799	<interface
10800	name="IGuestProcess" extends="IProcess"
10801	uuid="dfa39a36-5d43-4840-a025-67ea956b3111"
10802	wsmap="managed"
10803	>
10804	<desc>
10805	Implementation of the <link to="IProcess" /> object
10806	for processes on the guest.
10807	</desc>
10808	</interface>
10809
10810	<interface
10811	name="IDirectory" extends="$unknown"
10812	uuid="1b70dd03-26d7-483a-8877-89bbb0f87b70"
10813	wsmap="managed"
10814	>
10815	<desc>
10816	Abstract parent interface for directories handled by VirtualBox.
10817	</desc>
10818
10819	<attribute name="directoryName" type="wstring" readonly="yes">
10820	<desc>
10821	Full path of directory.
10822	</desc>
10823	</attribute>
10824
10825	<attribute name="filter" type="wstring" readonly="yes">
10826	<desc>
10827	The open filter.
10828	</desc>
10829	</attribute>
10830
10831	<method name="close">
10832	<desc>
10833	Closes this directory. After closing operations like reading the next
10834	directory entry will not be possible anymore.
10835	</desc>
10836	</method>
10837
10838	<method name="read">
10839	<desc>
10840	Reads the next directory entry of this directory.
10841	<result name="VBOX_E_OBJECT_NOT_FOUND">
10842	No more directory entries to read.
10843	</result>
10844	</desc>
10845	<param name="objInfo" type="IFsObjInfo" dir="return">
10846	<desc>Object information of the current directory entry read. Also see
10847	<link to="IFsObjInfo"/>.</desc>
10848	</param>
10849	</method>
10850	</interface>
10851
10852	<interface
10853	name="IGuestDirectory" extends="IDirectory"
10854	uuid="af4a8ce0-0725-42b7-8826-46e3c7ba7357"
10855	wsmap="managed"
10856	>
10857	<desc>
10858	Implementation of the <link to="IDirectory" /> object
10859	for directories on the guest.
10860	</desc>
10861	</interface>
10862
10863	<interface
10864	name="IFile" extends="$unknown"
10865	uuid="ceb895d7-8b2d-4a39-8f7c-7d2270f341d5"
10866	wsmap="managed"
10867	>
10868	<desc>
10869	Abstract parent interface for files handled by VirtualBox.
10870	</desc>
10871	<attribute name="creationMode" type="unsigned long" readonly="yes">
10872	<desc>
10873	The creation mode.
10874	</desc>
10875	</attribute>
10876	<attribute name="disposition" type="unsigned long" readonly="yes">
10877	<desc>
10878	The disposition mode.
10879	</desc>
10880	</attribute>
10881	<attribute name="eventSource" type="IEventSource" readonly="yes">
10882	<desc>
10883	Event source for guest session events.
10884	</desc>
10885	</attribute>
10886	<attribute name="fileName" type="wstring" readonly="yes">
10887	<desc>
10888	Full path of the actual file name of this file.
10889	</desc>
10890	</attribute>
10891	<attribute name="initialSize" type="long long" readonly="yes">
10892	<desc>
10893	The initial size in bytes when opened.
10894	</desc>
10895	</attribute>
10896	<attribute name="openMode" type="unsigned long" readonly="yes">
10897	<desc>
10898	The open mode.
10899	</desc>
10900	</attribute>
10901	<attribute name="offset" type="long long" readonly="yes">
10902	<desc>
10903	Current read/write offset in bytes.
10904	</desc>
10905	</attribute>
10906	<attribute name="status" type="FileStatus" readonly="yes">
10907	<desc>
10908	Current file status.
10909	</desc>
10910	</attribute>
10911
10912	<method name="close">
10913	<desc>
10914	Closes this file. After closing operations like reading data,
10915	writing data or querying information will not be possible anymore.
10916	</desc>
10917	</method>
10918
10919	<method name="queryInfo">
10920	<desc>
10921	Queries information about this file.
10922
10923	<result name="E_NOTIMPL">
10924	The method is not implemented yet.
10925	</result>
10926	</desc>
10927	<param name="objInfo" type="IFsObjInfo" dir="return">
10928	<desc>Object information of this file. Also see
10929	<link to="IFsObjInfo"/>.</desc>
10930	</param>
10931	</method>
10932
10933	<method name="read">
10934	<desc>
10935	Reads data from this file.
10936
10937	<result name="E_NOTIMPL">
10938	The method is not implemented yet.
10939	</result>
10940	</desc>
10941	<param name="toRead" type="unsigned long" dir="in">
10942	<desc>Number of bytes to read.</desc>
10943	</param>
10944	<param name="timeoutMS" type="unsigned long" dir="in">
10945	<desc>
10946	Timeout (in ms) to wait for the operation to complete.
10947	Pass 0 for an infinite timeout.
10948	</desc>
10949	</param>
10950	<param name="data" type="octet" dir="return" safearray="yes">
10951	<desc>Array of data read.</desc>
10952	</param>
10953	</method>
10954
10955	<method name="readAt">
10956	<desc>
10957	Reads data from an offset of this file.
10958
10959	<result name="E_NOTIMPL">
10960	The method is not implemented yet.
10961	</result>
10962	</desc>
10963	<param name="offset" type="long long" dir="in">
10964	<desc>Offset in bytes to start reading.</desc>
10965	</param>
10966	<param name="toRead" type="unsigned long" dir="in">
10967	<desc>Number of bytes to read.</desc>
10968	</param>
10969	<param name="timeoutMS" type="unsigned long" dir="in">
10970	<desc>
10971	Timeout (in ms) to wait for the operation to complete.
10972	Pass 0 for an infinite timeout.
10973	</desc>
10974	</param>
10975	<param name="data" type="octet" dir="return" safearray="yes">
10976	<desc>Array of data read.</desc>
10977	</param>
10978	</method>
10979
10980	<method name="seek">
10981	<desc>
10982	Changes the read and write position of this file.
10983
10984	<result name="E_NOTIMPL">
10985	The method is not implemented yet.
10986	</result>
10987	</desc>
10988	<param name="offset" type="long long" dir="in">
10989	<desc>Offset to seek.</desc>
10990	</param>
10991	<param name="whence" type="FileSeekType" dir="in">
10992	<desc>
10993	Seek mode; see <link to="FileSeekType"/> for more information.
10994	</desc>
10995	</param>
10996	</method>
10997
10998	<method name="setACL">
10999	<desc>
11000	Sets the ACL of this file.
11001
11002	<result name="E_NOTIMPL">
11003	The method is not implemented yet.
11004	</result>
11005	</desc>
11006	<param name="acl" type="wstring" dir="in">
11007	<desc>ACL string to set.</desc>
11008	</param>
11009	</method>
11010
11011	<method name="write">
11012	<desc>
11013	Writes bytes to this file.
11014	</desc>
11015	<param name="data" type="octet" dir="in" safearray="yes">
11016	<desc>
11017	Array of bytes to write. The size of the array also specifies
11018	how much to write.
11019	</desc>
11020	</param>
11021	<param name="timeoutMS" type="unsigned long" dir="in">
11022	<desc>
11023	Timeout (in ms) to wait for the operation to complete.
11024	Pass 0 for an infinite timeout.
11025	</desc>
11026	</param>
11027	<param name="written" type="unsigned long" dir="return">
11028	<desc>How much bytes were written.</desc>
11029	</param>
11030	</method>
11031
11032	<method name="writeAt">
11033	<desc>
11034	Writes bytes at a certain offset to this file.
11035
11036	<result name="E_NOTIMPL">
11037	The method is not implemented yet.
11038	</result>
11039	</desc>
11040	<param name="offset" type="long long" dir="in">
11041	<desc>Offset in bytes to start writing.</desc>
11042	</param>
11043	<param name="data" type="octet" dir="in" safearray="yes">
11044	<desc>
11045	Array of bytes to write. The size of the array also specifies
11046	how much to write.
11047	</desc>
11048	</param>
11049	<param name="timeoutMS" type="unsigned long" dir="in">
11050	<desc>
11051	Timeout (in ms) to wait for the operation to complete.
11052	Pass 0 for an infinite timeout.
11053	</desc>
11054	</param>
11055	<param name="written" type="unsigned long" dir="return">
11056	<desc>How much bytes were written.</desc>
11057	</param>
11058	</method>
11059
11060	</interface>
11061
11062	<interface
11063	name="IGuestFile" extends="IFile"
11064	uuid="60661aec-145f-4d11-b80e-8ea151598093"
11065	wsmap="managed"
11066	>
11067	<desc>
11068	Implementation of the <link to="IFile" /> object
11069	for files on the guest.
11070	</desc>
11071	</interface>
11072
11073	<interface
11074	name="IFsObjInfo" extends="$unknown"
11075	uuid="4047ba30-7006-4966-ae86-94164e5e20eb"
11076	wsmap="managed"
11077	>
11078	<desc>
11079	Abstract parent interface for VirtualBox file system object information.
11080	This can be information about a file or a directory, for example.
11081	</desc>
11082
11083	<attribute name="accessTime" type="long long" readonly="yes">
11084	<desc>
11085	Time of last access (st_atime).
11086	</desc>
11087	</attribute>
11088	<attribute name="allocatedSize" type="long long" readonly="yes">
11089	<desc>
11090	Disk allocation size (st_blocks * DEV_BSIZE).
11091	</desc>
11092	</attribute>
11093	<attribute name="birthTime" type="long long" readonly="yes">
11094	<desc>
11095	Time of file birth (st_birthtime).
11096	</desc>
11097	</attribute>
11098	<attribute name="changeTime" type="long long" readonly="yes">
11099	<desc>
11100	Time of last status change (st_ctime).
11101	</desc>
11102	</attribute>
11103	<attribute name="deviceNumber" type="unsigned long" readonly="yes">
11104	<desc>
11105	The device number of a character or block device type object (st_rdev).
11106	</desc>
11107	</attribute>
11108	<attribute name="fileAttributes" type="wstring" readonly="yes">
11109	<desc>
11110	File attributes. Not implemented yet.
11111	</desc>
11112	</attribute>
11113	<attribute name="generationId" type="unsigned long" readonly="yes">
11114	<desc>
11115	The current generation number (st_gen).
11116	</desc>
11117	</attribute>
11118	<attribute name="GID" type="unsigned long" readonly="yes">
11119	<desc>
11120	The group the filesystem object is assigned (st_gid).
11121	</desc>
11122	</attribute>
11123	<attribute name="groupName" type="wstring" readonly="yes">
11124	<desc>
11125	The group name.
11126	</desc>
11127	</attribute>
11128	<attribute name="hardLinks" type="unsigned long" readonly="yes">
11129	<desc>
11130	Number of hard links to this filesystem object (st_nlink).
11131	</desc>
11132	</attribute>
11133	<attribute name="modificationTime" type="long long" readonly="yes">
11134	<desc>
11135	Time of last data modification (st_mtime).
11136	</desc>
11137	</attribute>
11138	<attribute name="name" type="wstring" readonly="yes">
11139	<desc>
11140	The object's name.
11141	</desc>
11142	</attribute>
11143	<attribute name="nodeId" type="long long" readonly="yes">
11144	<desc>
11145	The unique identifier (within the filesystem) of this filesystem object (st_ino).
11146	</desc>
11147	</attribute>
11148	<attribute name="nodeIdDevice" type="unsigned long" readonly="yes">
11149	<desc>
11150	The device number of the device which this filesystem object resides on (st_dev).
11151	</desc>
11152	</attribute>
11153	<attribute name="objectSize" type="long long" readonly="yes">
11154	<desc>
11155	The logical size (st_size). For normal files this is the size of the file.
11156	For symbolic links, this is the length of the path name contained in the
11157	symbolic link. For other objects this fields needs to be specified.
11158	</desc>
11159	</attribute>
11160	<attribute name="type" type="FsObjType" readonly="yes">
11161	<desc>
11162	The object type. See <link to="FsObjType" /> for more.
11163	</desc>
11164	</attribute>
11165	<attribute name="UID" type="unsigned long" readonly="yes">
11166	<desc>
11167	The user owning the filesystem object (st_uid).
11168	</desc>
11169	</attribute>
11170	<attribute name="userFlags" type="unsigned long" readonly="yes">
11171	<desc>
11172	User flags (st_flags).
11173	</desc>
11174	</attribute>
11175	<attribute name="userName" type="wstring" readonly="yes">
11176	<desc>
11177	The user name.
11178	</desc>
11179	</attribute>
11180
11181	</interface>
11182
11183	<interface
11184	name="IGuestFsObjInfo" extends="IFsObjInfo"
11185	uuid="d5cf678e-3484-4e4a-ac55-329e15462e18"
11186	wsmap="managed"
11187	>
11188	<desc>
11189	Represents the guest implementation of the
11190	<link to="IFsObjInfo" /> object.
11191	</desc>
11192	</interface>
11193
11194	<interface
11195	name="IGuest" extends="$unknown"
11196	uuid="19c32350-0618-4ede-b0c3-2b4311bf0d9b"
11197	wsmap="managed"
11198	>
11199	<desc>
11200	The IGuest interface represents information about the operating system
11201	running inside the virtual machine. Used in
11202	<link to="IConsole::guest"/>.
11203
11204	IGuest provides information about the guest operating system, whether
11205	Guest Additions are installed and other OS-specific virtual machine
11206	properties.
11207	</desc>
11208
11209	<attribute name="OSTypeId" type="wstring" readonly="yes">
11210	<desc>
11211	Identifier of the Guest OS type as reported by the Guest
11212	Additions.
11213	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
11214	an IGuestOSType object representing details about the given
11215	Guest OS type.
11216	<note>
11217	If Guest Additions are not installed, this value will be
11218	the same as <link to="IMachine::OSTypeId"/>.
11219	</note>
11220	</desc>
11221	</attribute>
11222
11223	<attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
11224	<desc>
11225	Current run level of the Guest Additions.
11226	</desc>
11227	</attribute>
11228
11229	<attribute name="additionsVersion" type="wstring" readonly="yes">
11230	<desc>
11231	Version of the Guest Additions in the same format as
11232	<link to="IVirtualBox::version"/>.
11233	</desc>
11234	</attribute>
11235
11236	<attribute name="additionsRevision" type="unsigned long" readonly="yes">
11237	<desc>
11238	The internal build revision number of the additions.
11239
11240	See also <link to="IVirtualBox::revision"/>.
11241	</desc>
11242	</attribute>
11243
11244	<attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes">
11245	<desc>
11246	Array of current known facilities. Only returns facilities where a status is known,
11247	e.g. facilities with an unknown status will not be returned.
11248	</desc>
11249	</attribute>
11250
11251	<attribute name="sessions" type="IGuestSession" readonly="yes" safearray="yes">
11252	<desc>Returns a collection of all opened guest sessions.</desc>
11253	</attribute>
11254
11255	<attribute name="memoryBalloonSize" type="unsigned long">
11256	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
11257	</attribute>
11258
11259	<attribute name="statisticsUpdateInterval" type="unsigned long">
11260	<desc>Interval to update guest statistics in seconds.</desc>
11261	</attribute>
11262
11263	<method name="internalGetStatistics">
11264	<desc>
11265	Internal method; do not use as it might change at any time.
11266	</desc>
11267	<param name="cpuUser" type="unsigned long" dir="out">
11268	<desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
11269	</param>
11270	<param name="cpuKernel" type="unsigned long" dir="out">
11271	<desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
11272	</param>
11273	<param name="cpuIdle" type="unsigned long" dir="out">
11274	<desc>Percentage of processor time spent idling as seen by the guest.</desc>
11275	</param>
11276	<param name="memTotal" type="unsigned long" dir="out">
11277	<desc>Total amount of physical guest RAM.</desc>
11278	</param>
11279	<param name="memFree" type="unsigned long" dir="out">
11280	<desc>Free amount of physical guest RAM.</desc>
11281	</param>
11282	<param name="memBalloon" type="unsigned long" dir="out">
11283	<desc>Amount of ballooned physical guest RAM.</desc>
11284	</param>
11285	<param name="memShared" type="unsigned long" dir="out">
11286	<desc>Amount of shared physical guest RAM.</desc>
11287	</param>
11288	<param name="memCache" type="unsigned long" dir="out">
11289	<desc>Total amount of guest (disk) cache memory.</desc>
11290	</param>
11291	<param name="pagedTotal" type="unsigned long" dir="out">
11292	<desc>Total amount of space in the page file.</desc>
11293	</param>
11294	<param name="memAllocTotal" type="unsigned long" dir="out">
11295	<desc>Total amount of memory allocated by the hypervisor.</desc>
11296	</param>
11297	<param name="memFreeTotal" type="unsigned long" dir="out">
11298	<desc>Total amount of free memory available in the hypervisor.</desc>
11299	</param>
11300	<param name="memBalloonTotal" type="unsigned long" dir="out">
11301	<desc>Total amount of memory ballooned by the hypervisor.</desc>
11302	</param>
11303	<param name="memSharedTotal" type="unsigned long" dir="out">
11304	<desc>Total amount of shared memory in the hypervisor.</desc>
11305	</param>
11306	</method>
11307
11308	<method name="getFacilityStatus">
11309	<desc>
11310	Get the current status of a Guest Additions facility.
11311	</desc>
11312	<param name="facility" type="AdditionsFacilityType" dir="in">
11313	<desc>Facility to check status for.</desc>
11314	</param>
11315	<param name="timestamp" type="long long" dir="out">
11316	<desc>Timestamp (in ms) of last status update seen by the host.</desc>
11317	</param>
11318	<param name="status" type="AdditionsFacilityStatus" dir="return">
11319	<desc>The current (latest) facility status.</desc>
11320	</param>
11321	</method>
11322
11323	<method name="getAdditionsStatus">
11324	<desc>
11325	Retrieve the current status of a certain Guest Additions run level.
11326
11327	<result name="VBOX_E_NOT_SUPPORTED">
11328	Wrong status level specified.
11329	</result>
11330
11331	</desc>
11332	<param name="level" type="AdditionsRunLevelType" dir="in">
11333	<desc>Status level to check</desc>
11334	</param>
11335	<param name="active" type="boolean" dir="return">
11336	<desc>Flag whether the status level has been reached or not</desc>
11337	</param>
11338	</method>
11339
11340	<method name="setCredentials">
11341	<desc>
11342	Store login credentials that can be queried by guest operating
11343	systems with Additions installed. The credentials are transient
11344	to the session and the guest may also choose to erase them. Note
11345	that the caller cannot determine whether the guest operating system
11346	has queried or made use of the credentials.
11347
11348	<result name="VBOX_E_VM_ERROR">
11349	VMM device is not available.
11350	</result>
11351
11352	</desc>
11353	<param name="userName" type="wstring" dir="in">
11354	<desc>User name string, can be empty</desc>
11355	</param>
11356	<param name="password" type="wstring" dir="in">
11357	<desc>Password string, can be empty</desc>
11358	</param>
11359	<param name="domain" type="wstring" dir="in">
11360	<desc>Domain name (guest logon scheme specific), can be empty</desc>
11361	</param>
11362	<param name="allowInteractiveLogon" type="boolean" dir="in">
11363	<desc>
11364	Flag whether the guest should alternatively allow the user to
11365	interactively specify different credentials. This flag might
11366	not be supported by all versions of the Additions.
11367	</desc>
11368	</param>
11369	</method>
11370
11371	<method name="dragHGEnter">
11372	<desc>
11373	Informs the guest about a Drag and Drop enter event.
11374
11375	This is used in Host - Guest direction.
11376
11377	<result name="VBOX_E_VM_ERROR">
11378	VMM device is not available.
11379	</result>
11380
11381	</desc>
11382	<param name="screenId" type="unsigned long" dir="in">
11383	<desc>The screen id where the Drag and Drop event occured.</desc>
11384	</param>
11385	<param name="y" type="unsigned long" dir="in">
11386	<desc>y-position of the event.</desc>
11387	</param>
11388	<param name="x" type="unsigned long" dir="in">
11389	<desc>x-position of the event.</desc>
11390	</param>
11391	<param name="defaultAction" type="DragAndDropAction" dir="in">
11392	<desc>The default action to use.</desc>
11393	</param>
11394	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11395	<desc>The actions which are allowed.</desc>
11396	</param>
11397	<param name="formats" type="wstring" dir="in" safearray="yes">
11398	<desc>The supported mime types.</desc>
11399	</param>
11400	<param name="resultAction" type="DragAndDropAction" dir="return">
11401	<desc>The resulting action of this event.</desc>
11402	</param>
11403	</method>
11404
11405	<method name="dragHGMove">
11406	<desc>
11407	Informs the guest about a Drag and Drop move event.
11408
11409	This is used in Host - Guest direction.
11410
11411	<result name="VBOX_E_VM_ERROR">
11412	VMM device is not available.
11413	</result>
11414
11415	</desc>
11416	<param name="screenId" type="unsigned long" dir="in">
11417	<desc>The screen id where the Drag and Drop event occured.</desc>
11418	</param>
11419	<param name="x" type="unsigned long" dir="in">
11420	<desc>x-position of the event.</desc>
11421	</param>
11422	<param name="y" type="unsigned long" dir="in">
11423	<desc>y-position of the event.</desc>
11424	</param>
11425	<param name="defaultAction" type="DragAndDropAction" dir="in">
11426	<desc>The default action to use.</desc>
11427	</param>
11428	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11429	<desc>The actions which are allowed.</desc>
11430	</param>
11431	<param name="formats" type="wstring" dir="in" safearray="yes">
11432	<desc>The supported mime types.</desc>
11433	</param>
11434	<param name="resultAction" type="DragAndDropAction" dir="return">
11435	<desc>The resulting action of this event.</desc>
11436	</param>
11437	</method>
11438
11439	<method name="dragHGLeave">
11440	<desc>
11441	Informs the guest about a Drag and Drop leave event.
11442
11443	This is used in Host - Guest direction.
11444
11445	<result name="VBOX_E_VM_ERROR">
11446	VMM device is not available.
11447	</result>
11448
11449	</desc>
11450	<param name="screenId" type="unsigned long" dir="in">
11451	<desc>The screen id where the Drag and Drop event occured.</desc>
11452	</param>
11453	</method>
11454
11455	<method name="dragHGDrop">
11456	<desc>
11457	Informs the guest about a drop event.
11458
11459	This is used in Host - Guest direction.
11460
11461	<result name="VBOX_E_VM_ERROR">
11462	VMM device is not available.
11463	</result>
11464
11465	</desc>
11466	<param name="screenId" type="unsigned long" dir="in">
11467	<desc>The screen id where the Drag and Drop event occured.</desc>
11468	</param>
11469	<param name="x" type="unsigned long" dir="in">
11470	<desc>x-position of the event.</desc>
11471	</param>
11472	<param name="y" type="unsigned long" dir="in">
11473	<desc>y-position of the event.</desc>
11474	</param>
11475	<param name="defaultAction" type="DragAndDropAction" dir="in">
11476	<desc>The default action to use.</desc>
11477	</param>
11478	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11479	<desc>The actions which are allowed.</desc>
11480	</param>
11481	<param name="formats" type="wstring" dir="in" safearray="yes">
11482	<desc>The supported mime types.</desc>
11483	</param>
11484	<param name="format" type="wstring" dir="out">
11485	<desc>The resulting format of this event.</desc>
11486	</param>
11487	<param name="resultAction" type="DragAndDropAction" dir="return">
11488	<desc>The resulting action of this event.</desc>
11489	</param>
11490	</method>
11491
11492	<method name="dragHGPutData">
11493	<desc>
11494	Informs the guest about a drop data event.
11495
11496	This is used in Host - Guest direction.
11497
11498	<result name="VBOX_E_VM_ERROR">
11499	VMM device is not available.
11500	</result>
11501
11502	</desc>
11503	<param name="screenId" type="unsigned long" dir="in">
11504	<desc>The screen id where the Drag and Drop event occured.</desc>
11505	</param>
11506	<param name="format" type="wstring" dir="in">
11507	<desc>The mime type the data is in.</desc>
11508	</param>
11509	<param name="data" type="octet" dir="in" safearray="yes">
11510	<desc>The actual data.</desc>
11511	</param>
11512	<param name="progress" type="IProgress" dir="return">
11513	<desc>Progress object to track the operation completion.</desc>
11514	</param>
11515	</method>
11516
11517	<method name="dragGHPending">
11518	<desc>
11519	Ask the guest if there is any Drag and Drop operation pending in the guest.
11520
11521	If no Drag and Drop operation is pending currently, Ignore is returned.
11522
11523	This is used in Guest - Host direction.
11524
11525	<result name="VBOX_E_VM_ERROR">
11526	VMM device is not available.
11527	</result>
11528
11529	</desc>
11530	<param name="screenId" type="unsigned long" dir="in">
11531	<desc>The screen id where the Drag and Drop event occured.</desc>
11532	</param>
11533	<param name="formats" type="wstring" dir="out" safearray="yes">
11534	<desc>On return the supported mime types.</desc>
11535	</param>
11536	<param name="allowedActions" type="DragAndDropAction" dir="out" safearray="yes">
11537	<desc>On return the actions which are allowed.</desc>
11538	</param>
11539	<param name="defaultAction" type="DragAndDropAction" dir="return">
11540	<desc>On return the default action to use.</desc>
11541	</param>
11542	</method>
11543
11544	<method name="dragGHDropped">
11545	<desc>
11546	Informs the guest that a drop event occured for a pending Drag and Drop event.
11547
11548	This is used in Guest - Host direction.
11549
11550	<result name="VBOX_E_VM_ERROR">
11551	VMM device is not available.
11552	</result>
11553
11554	</desc>
11555
11556	<param name="format" type="wstring" dir="in">
11557	<desc>The mime type the data must be in.</desc>
11558	</param>
11559	<param name="action" type="DragAndDropAction" dir="in">
11560	<desc>The action to use.</desc>
11561	</param>
11562	<param name="progress" type="IProgress" dir="return">
11563	<desc>Progress object to track the operation completion.</desc>
11564	</param>
11565	</method>
11566
11567	<method name="dragGHGetData">
11568	<desc>
11569	Fetch the data of a previously Drag and Drop event from the guest.
11570
11571	This is used in Guest - Host direction.
11572
11573	<result name="VBOX_E_VM_ERROR">
11574	VMM device is not available.
11575	</result>
11576
11577	</desc>
11578
11579	<param name="data" type="octet" safearray="yes" dir="return">
11580	<desc>The actual data.</desc>
11581	</param>
11582	</method>
11583
11584	<method name="createSession">
11585	<desc>
11586	Creates a new guest session for controlling the guest.
11587
11588	A guest session represents one impersonated user account on the guest, so
11589	every operation will use the same credentials specified when creating
11590	the session object via <link to="IGuest::createSession"/>. Anonymous
11591	sessions, that is, sessions without specifying a valid
11592	user account on the guest are not allowed due to security reasons.
11593
11594	There can be a maximum of 32 sessions at once per VM. Each session keeps
11595	track of its started guest processes, opened guest files or guest directories.
11596	To work on guest files or directories a guest session offers methods to open
11597	or create such objects (see <link to="IGuestSession::fileOpen"/> or
11598	<link to="IGuestSession::directoryOpen"/> for example).
11599
11600	When done with either of these objects, including the guest session itself,
11601	use the appropriate close() method to let the object do its cleanup work.
11602
11603	Every guest session has its own environment variable block which gets
11604	automatically applied when starting a new guest process via
11605	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
11606	To override (or unset) certain environment variables already set by the
11607	guest session, one can specify a per-process environment block when using
11608	one of the both above mentioned process creation calls.
11609
11610	Closing a session via <link to="IGuestSession::close" /> will try to close
11611	all the mentioned objects above unless these objects are still used by
11612	a client.
11613	</desc>
11614	<param name="user" type="wstring" dir="in">
11615	<desc>
11616	User name this session will be using to control the guest; has to exist
11617	and have the appropriate rights to execute programs in the VM. Must not
11618	be empty.
11619	</desc>
11620	</param>
11621	<param name="password" type="wstring" dir="in">
11622	<desc>
11623	Password of the user account to be used. Empty passwords are allowed.
11624	</desc>
11625	</param>
11626	<param name="domain" type="wstring" dir="in">
11627	<desc>
11628	Domain name of the user account to be used if the guest is part of
11629	a domain. Optional. This feature is not implemented yet.
11630	</desc>
11631	</param>
11632	<param name="sessionName" type="wstring" dir="in">
11633	<desc>
11634	The session's friendly name. Optional, can be empty.
11635	</desc>
11636	</param>
11637	<param name="guestSession" type="IGuestSession" dir="return">
11638	<desc>
11639	The newly created session object.
11640	</desc>
11641	</param>
11642	</method>
11643
11644	<method name="findSession">
11645	<desc>
11646	Finds guest sessions by their friendly name and returns an interface
11647	array with all found guest sessions.
11648	</desc>
11649	<param name="sessionName" type="wstring" dir="in">
11650	<desc>
11651	The session's friendly name to find. Wildcards like ? and * are allowed.
11652	</desc>
11653	</param>
11654	<param name="sessions" type="IGuestSession" safearray="yes" dir="return">
11655	<desc>
11656	Array with all guest sessions found matching the name specified.
11657	</desc>
11658	</param>
11659	</method>
11660
11661	<method name="updateGuestAdditions">
11662	<desc>
11663	Automatically updates already installed Guest Additions in a VM.
11664
11665	At the moment only Windows guests are supported.
11666
11667	Because the VirtualBox Guest Additions drivers are not WHQL-certified
11668	yet there might be warning dialogs during the actual Guest Additions
11669	update. These need to be confirmed manually in order to continue the
11670	installation process. This applies to Windows 2000 and Windows XP guests
11671	and therefore these guests can't be updated in a fully automated fashion
11672	without user interaction. However, to start a Guest Additions update for
11673	the mentioned Windows versions anyway, the flag
11674	AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See
11675	<link to="AdditionsUpdateFlag"/> for more information.
11676
11677	<result name="VBOX_E_NOT_SUPPORTED">
11678	Guest OS is not supported for automated Guest Additions updates or the
11679	already installed Guest Additions are not ready yet.
11680	</result>
11681
11682	<result name="VBOX_E_IPRT_ERROR">
11683	Error while updating.
11684	</result>
11685
11686	</desc>
11687	<param name="source" type="wstring" dir="in">
11688	<desc>
11689	Path to the Guest Additions .ISO file to use for the upate.
11690	</desc>
11691	</param>
11692	<param name="flags" type="AdditionsUpdateFlag" dir="in" safearray="yes">
11693	<desc>
11694	<link to="AdditionsUpdateFlag"/> flags.
11695	</desc>
11696	</param>
11697	<param name="progress" type="IProgress" dir="return">
11698	<desc>Progress object to track the operation completion.</desc>
11699	</param>
11700	</method>
11701
11702	</interface>
11703
11704
11705	<!--
11706	// IProgress
11707	/////////////////////////////////////////////////////////////////////////
11708	-->
11709
11710	<interface
11711	name="IProgress" extends="$unknown"
11712	uuid="c20238e4-3221-4d3f-8891-81ce92d9f913"
11713	wsmap="managed"
11714	>
11715	<desc>
11716	The IProgress interface is used to track and control
11717	asynchronous tasks within VirtualBox.
11718
11719	An instance of this is returned every time VirtualBox starts
11720	an asynchronous task (in other words, a separate thread) which
11721	continues to run after a method call returns. For example,
11722	<link to="IConsole::saveState" />, which saves the state of
11723	a running virtual machine, can take a long time to complete.
11724	To be able to display a progress bar, a user interface such as
11725	the VirtualBox graphical user interface can use the IProgress
11726	object returned by that method.
11727
11728	Note that IProgress is a "read-only" interface in the sense
11729	that only the VirtualBox internals behind the Main API can
11730	create and manipulate progress objects, whereas client code
11731	can only use the IProgress object to monitor a task's
11732	progress and, if <link to="#cancelable" /> is @c true,
11733	cancel the task by calling <link to="#cancel" />.
11734
11735	A task represented by IProgress consists of either one or
11736	several sub-operations that run sequentially, one by one (see
11737	<link to="#operation" /> and <link to="#operationCount" />).
11738	Every operation is identified by a number (starting from 0)
11739	and has a separate description.
11740
11741	You can find the individual percentage of completion of the current
11742	operation in <link to="#operationPercent" /> and the
11743	percentage of completion of the task as a whole
11744	in <link to="#percent" />.
11745
11746	Similarly, you can wait for the completion of a particular
11747	operation via <link to="#waitForOperationCompletion" /> or
11748	for the completion of the whole task via
11749	<link to="#waitForCompletion" />.
11750	</desc>
11751
11752	<attribute name="id" type="uuid" mod="string" readonly="yes">
11753	<desc>ID of the task.</desc>
11754	</attribute>
11755
11756	<attribute name="description" type="wstring" readonly="yes">
11757	<desc>Description of the task.</desc>
11758	</attribute>
11759
11760	<attribute name="initiator" type="$unknown" readonly="yes">
11761	<desc>Initiator of the task.</desc>
11762	</attribute>
11763
11764	<attribute name="cancelable" type="boolean" readonly="yes">
11765	<desc>Whether the task can be interrupted.</desc>
11766	</attribute>
11767
11768	<attribute name="percent" type="unsigned long" readonly="yes">
11769	<desc>
11770	Current progress value of the task as a whole, in percent.
11771	This value depends on how many operations are already complete.
11772	Returns 100 if <link to="#completed" /> is @c true.
11773	</desc>
11774	</attribute>
11775
11776	<attribute name="timeRemaining" type="long" readonly="yes">
11777	<desc>
11778	Estimated remaining time until the task completes, in
11779	seconds. Returns 0 once the task has completed; returns -1
11780	if the remaining time cannot be computed, in particular if
11781	the current progress is 0.
11782
11783	Even if a value is returned, the estimate will be unreliable
11784	for low progress values. It will become more reliable as the
11785	task progresses; it is not recommended to display an ETA
11786	before at least 20% of a task have completed.
11787	</desc>
11788	</attribute>
11789
11790	<attribute name="completed" type="boolean" readonly="yes">
11791	<desc>Whether the task has been completed.</desc>
11792	</attribute>
11793
11794	<attribute name="canceled" type="boolean" readonly="yes">
11795	<desc>Whether the task has been canceled.</desc>
11796	</attribute>
11797
11798	<attribute name="resultCode" type="long" readonly="yes">
11799	<desc>
11800	Result code of the progress task.
11801	Valid only if <link to="#completed"/> is @c true.
11802	</desc>
11803	</attribute>
11804
11805	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
11806	<desc>
11807	Extended information about the unsuccessful result of the
11808	progress operation. May be @c null if no extended information
11809	is available.
11810	Valid only if <link to="#completed"/> is @c true and
11811	<link to="#resultCode"/> indicates a failure.
11812	</desc>
11813	</attribute>
11814
11815	<attribute name="operationCount" type="unsigned long" readonly="yes">
11816	<desc>
11817	Number of sub-operations this task is divided into.
11818	Every task consists of at least one suboperation.
11819	</desc>
11820	</attribute>
11821
11822	<attribute name="operation" type="unsigned long" readonly="yes">
11823	<desc>Number of the sub-operation being currently executed.</desc>
11824	</attribute>
11825
11826	<attribute name="operationDescription" type="wstring" readonly="yes">
11827	<desc>
11828	Description of the sub-operation being currently executed.
11829	</desc>
11830	</attribute>
11831
11832	<attribute name="operationPercent" type="unsigned long" readonly="yes">
11833	<desc>Progress value of the current sub-operation only, in percent.</desc>
11834	</attribute>
11835
11836	<attribute name="operationWeight" type="unsigned long" readonly="yes">
11837	<desc>Weight value of the current sub-operation only.</desc>
11838	</attribute>
11839
11840	<attribute name="timeout" type="unsigned long">
11841	<desc>
11842	When non-zero, this specifies the number of milliseconds after which
11843	the operation will automatically be canceled. This can only be set on
11844	cancelable objects.
11845	</desc>
11846	</attribute>
11847
11848	<method name="setCurrentOperationProgress">
11849	<desc>Internal method, not to be called externally.</desc>
11850	<param name="percent" type="unsigned long" dir="in" />
11851	</method>
11852	<method name="setNextOperation">
11853	<desc>Internal method, not to be called externally.</desc>
11854	<param name="nextOperationDescription" type="wstring" dir="in" />
11855	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
11856	</method>
11857
11858	<method name="waitForCompletion">
11859	<desc>
11860	Waits until the task is done (including all sub-operations)
11861	with a given timeout in milliseconds; specify -1 for an indefinite wait.
11862
11863	Note that the VirtualBox/XPCOM/COM/native event queues of the calling
11864	thread are not processed while waiting. Neglecting event queues may
11865	have dire consequences (degrade performance, resource hogs,
11866	deadlocks, etc.), this is specially so for the main thread on
11867	platforms using XPCOM. Callers are adviced wait for short periods
11868	and service their event queues between calls, or to create a worker
11869	thread to do the waiting.
11870
11871	<result name="VBOX_E_IPRT_ERROR">
11872	Failed to wait for task completion.
11873	</result>
11874	</desc>
11875
11876	<param name="timeout" type="long" dir="in">
11877	<desc>
11878	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11879	</desc>
11880	</param>
11881	</method>
11882
11883	<method name="waitForOperationCompletion">
11884	<desc>
11885	Waits until the given operation is done with a given timeout in
11886	milliseconds; specify -1 for an indefinite wait.
11887
11888	See <link to="#waitForCompletion"> for event queue considerations.</link>
11889
11890	<result name="VBOX_E_IPRT_ERROR">
11891	Failed to wait for operation completion.
11892	</result>
11893
11894	</desc>
11895	<param name="operation" type="unsigned long" dir="in">
11896	<desc>
11897	Number of the operation to wait for.
11898	Must be less than <link to="#operationCount"/>.
11899	</desc>
11900	</param>
11901	<param name="timeout" type="long" dir="in">
11902	<desc>
11903	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11904	</desc>
11905	</param>
11906	</method>
11907
11908	<method name="waitForAsyncProgressCompletion">
11909	<desc>
11910	Waits until the other task is completed (including all
11911	sub-operations) and forward all changes from the other progress to
11912	this progress. This means sub-operation number, description, percent
11913	and so on.
11914
11915	You have to take care on setting up at least the same count on
11916	sub-operations in this progress object like there are in the other
11917	progress object.
11918
11919	If the other progress object supports cancel and this object gets any
11920	cancel request (when here enabled as well), it will be forwarded to
11921	the other progress object.
11922
11923	If there is an error in the other progress, this error isn't
11924	automatically transfered to this progress object. So you have to
11925	check any operation error within the other progress object, after
11926	this method returns.
11927	</desc>
11928
11929	<param name="pProgressAsync" type="IProgress" dir="in">
11930	<desc>
11931	The progress object of the asynchrony process.
11932	</desc>
11933	</param>
11934	</method>
11935
11936	<method name="cancel">
11937	<desc>
11938	Cancels the task.
11939	<note>
11940	If <link to="#cancelable"/> is @c false, then this method will fail.
11941	</note>
11942
11943	<result name="VBOX_E_INVALID_OBJECT_STATE">
11944	Operation cannot be canceled.
11945	</result>
11946
11947	</desc>
11948	</method>
11949
11950	</interface>
11951
11952	<!--
11953	// ISnapshot
11954	/////////////////////////////////////////////////////////////////////////
11955	-->
11956
11957	<interface
11958	name="ISnapshot" extends="$unknown"
11959	uuid="0472823b-c6e7-472a-8e9f-d732e86b8463"
11960	wsmap="managed"
11961	>
11962	<desc>
11963	The ISnapshot interface represents a snapshot of the virtual
11964	machine.
11965
11966	Together with the differencing media that are created
11967	when a snapshot is taken, a machine can be brought back to
11968	the exact state it was in when the snapshot was taken.
11969
11970	The ISnapshot interface has no methods, only attributes; snapshots
11971	are controlled through methods of the <link to="IConsole" /> interface
11972	which also manage the media associated with the snapshot.
11973	The following operations exist:
11974
11975	<ul>
11976	<li><link to="IConsole::takeSnapshot"/> creates a new snapshot
11977	by creating new, empty differencing images for the machine's
11978	media and saving the VM settings and (if the VM is running)
11979	the current VM state in the snapshot.
11980
11981	The differencing images will then receive all data written to
11982	the machine's media, while their parent (base) images
11983	remain unmodified after the snapshot has been taken (see
11984	<link to="IMedium" /> for details about differencing images).
11985	This simplifies restoring a machine to the state of a snapshot:
11986	only the differencing images need to be deleted.
11987
11988	The current machine state is not changed by taking a snapshot
11989	except that <link to="IMachine::currentSnapshot" /> is set to
11990	the newly created snapshot, which is also added to the machine's
11991	snapshots tree.
11992	</li>
11993
11994	<li><link to="IConsole::restoreSnapshot"/> resets a machine to
11995	the state of a previous snapshot by deleting the differencing
11996	image of each of the machine's media and setting the machine's
11997	settings and state to the state that was saved in the snapshot (if any).
11998
11999	This destroys the machine's current state. After calling this,
12000	<link to="IMachine::currentSnapshot" /> points to the snapshot
12001	that was restored.
12002	</li>
12003
12004	<li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
12005	without affecting the current machine state.
12006
12007	This does not change the current machine state, but instead frees the
12008	resources allocated when the snapshot was taken: the settings and machine
12009	state file are deleted (if any), and the snapshot's differencing image for
12010	each of the machine's media gets merged with its parent image.
12011
12012	Neither the current machine state nor other snapshots are affected
12013	by this operation, except that parent media will be modified
12014	to contain the disk data associated with the snapshot being deleted.
12015
12016	When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
12017	attribute is set to the current snapshot's parent or @c null if it
12018	has no parent. Otherwise the attribute is unchanged.
12019	</li>
12020	</ul>
12021
12022	Each snapshot contains a copy of virtual machine's settings (hardware
12023	configuration etc.). This copy is contained in an immutable (read-only)
12024	instance of <link to="IMachine" /> which is available from the snapshot's
12025	<link to="#machine" /> attribute. When restoring the snapshot, these
12026	settings are copied back to the original machine.
12027
12028	In addition, if the machine was running when the
12029	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
12030	the current VM state is saved in the snapshot (similarly to what happens
12031	when a VM's state is saved). The snapshot is then said to be <i>online</i>
12032	because when restoring it, the VM will be running.
12033
12034	If the machine was in <link to="MachineState_Saved">saved</link> saved,
12035	the snapshot receives a copy of the execution state file
12036	(<link to="IMachine::stateFilePath"/>).
12037
12038	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
12039	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
12040	it then contains a so-called "zero execution state", representing a
12041	machine that is powered off.
12042	</desc>
12043
12044	<attribute name="id" type="uuid" mod="string" readonly="yes">
12045	<desc>UUID of the snapshot.</desc>
12046	</attribute>
12047
12048	<attribute name="name" type="wstring">
12049	<desc>Short name of the snapshot.
12050	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12051	be called implicitly.</note>
12052	</desc>
12053	</attribute>
12054
12055	<attribute name="description" type="wstring">
12056	<desc>Optional description of the snapshot.
12057	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12058	be called implicitly.</note>
12059	</desc>
12060	</attribute>
12061
12062	<attribute name="timeStamp" type="long long" readonly="yes">
12063	<desc>
12064	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
12065	</desc>
12066	</attribute>
12067
12068	<attribute name="online" type="boolean" readonly="yes">
12069	<desc>
12070	@c true if this snapshot is an online snapshot and @c false otherwise.
12071
12072	When this attribute is @c true, the
12073	<link to="IMachine::stateFilePath"/> attribute of the
12074	<link to="#machine"/> object associated with this snapshot
12075	will point to the saved state file. Otherwise, it will be
12076	an empty string.
12077	</desc>
12078	</attribute>
12079
12080	<attribute name="machine" type="IMachine" readonly="yes">
12081	<desc>
12082	Virtual machine this snapshot is taken on. This object
12083	stores all settings the machine had when taking this snapshot.
12084	<note>
12085	The returned machine object is immutable, i.e. no
12086	any settings can be changed.
12087	</note>
12088	</desc>
12089	</attribute>
12090
12091	<attribute name="parent" type="ISnapshot" readonly="yes">
12092	<desc>
12093	Parent snapshot (a snapshot this one is based on), or
12094	@c null if the snapshot has no parent (i.e. is the first snapshot).
12095	</desc>
12096	</attribute>
12097
12098	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
12099	<desc>
12100	Child snapshots (all snapshots having this one as a parent).
12101	By inspecting this attribute starting with a machine's root snapshot
12102	(which can be obtained by calling <link to="IMachine::findSnapshot" />
12103	with a @c null UUID), a machine's snapshots tree can be iterated over.
12104	</desc>
12105	</attribute>
12106
12107	<method name="getChildrenCount" const="yes">
12108	<desc>
12109	Returns the number of direct childrens of this snapshot.
12110	</desc>
12111	<param name="childrenCount" type="unsigned long" dir="return">
12112	<desc>
12113	</desc>
12114	</param>
12115	</method>
12116
12117	</interface>
12118
12119
12120	<!--
12121	// IMedium
12122	/////////////////////////////////////////////////////////////////////////
12123	-->
12124
12125	<enum
12126	name="MediumState"
12127	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
12128	>
12129	<desc>
12130	Virtual medium state.
12131	<see><link to="IMedium"/></see>
12132	</desc>
12133
12134	<const name="NotCreated" value="0">
12135	<desc>
12136	Associated medium storage does not exist (either was not created yet or
12137	was deleted).
12138	</desc>
12139	</const>
12140	<const name="Created" value="1">
12141	<desc>
12142	Associated storage exists and accessible; this gets set if the
12143	accessibility check performed by <link to="IMedium::refreshState" />
12144	was successful.
12145	</desc>
12146	</const>
12147	<const name="LockedRead" value="2">
12148	<desc>
12149	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
12150	no data modification is possible.
12151	</desc>
12152	</const>
12153	<const name="LockedWrite" value="3">
12154	<desc>
12155	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
12156	no concurrent data reading or modification is possible.
12157	</desc>
12158	</const>
12159	<const name="Inaccessible" value="4">
12160	<desc>
12161	Medium accessibility check (see <link to="IMedium::refreshState" />) has
12162	not yet been performed, or else, associated medium storage is not
12163	accessible. In the first case, <link to="IMedium::lastAccessError"/>
12164	is empty, in the second case, it describes the error that occurred.
12165	</desc>
12166	</const>
12167	<const name="Creating" value="5">
12168	<desc>
12169	Associated medium storage is being created.
12170	</desc>
12171	</const>
12172	<const name="Deleting" value="6">
12173	<desc>
12174	Associated medium storage is being deleted.
12175	</desc>
12176	</const>
12177	</enum>
12178
12179	<enum
12180	name="MediumType"
12181	uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04"
12182	>
12183	<desc>
12184	Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
12185	attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
12186	when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
12187	the medium attached. At the moment DVD and floppy media are always of type "writethrough".
12188	</desc>
12189
12190	<const name="Normal" value="0">
12191	<desc>
12192	Normal medium (attached directly or indirectly, preserved
12193	when taking snapshots).
12194	</desc>
12195	</const>
12196	<const name="Immutable" value="1">
12197	<desc>
12198	Immutable medium (attached indirectly, changes are wiped out
12199	the next time the virtual machine is started).
12200	</desc>
12201	</const>
12202	<const name="Writethrough" value="2">
12203	<desc>
12204	Write through medium (attached directly, ignored when
12205	taking snapshots).
12206	</desc>
12207	</const>
12208	<const name="Shareable" value="3">
12209	<desc>
12210	Allow using this medium concurrently by several machines.
12211	<note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
12212	</desc>
12213	</const>
12214	<const name="Readonly" value="4">
12215	<desc>
12216	A readonly medium, which can of course be used by several machines.
12217	<note>Present and accepted since VirtualBox 4.0.</note>
12218	</desc>
12219	</const>
12220	<const name="MultiAttach" value="5">
12221	<desc>
12222	A medium which is indirectly attached, so that one base medium can
12223	be used for several VMs which have their own differencing medium to
12224	store their modifications. In some sense a variant of Immutable
12225	with unset AutoReset flag in each differencing medium.
12226	<note>Present and accepted since VirtualBox 4.0.</note>
12227	</desc>
12228	</const>
12229	</enum>
12230
12231	<enum
12232	name="MediumVariant"
12233	uuid="80685b6b-e42f-497d-8271-e77bf3c61ada"
12234	>
12235	<desc>
12236	Virtual medium image variant. More than one flag may be set.
12237	<see><link to="IMedium"/></see>
12238	</desc>
12239
12240	<const name="Standard" value="0">
12241	<desc>
12242	No particular variant requested, results in using the backend default.
12243	</desc>
12244	</const>
12245	<const name="VmdkSplit2G" value="0x01">
12246	<desc>
12247	VMDK image split in chunks of less than 2GByte.
12248	</desc>
12249	</const>
12250	<const name="VmdkRawDisk" value="0x02">
12251	<desc>
12252	VMDK image representing a raw disk.
12253	</desc>
12254	</const>
12255	<const name="VmdkStreamOptimized" value="0x04">
12256	<desc>
12257	VMDK streamOptimized image. Special import/export format which is
12258	read-only/append-only.
12259	</desc>
12260	</const>
12261	<const name="VmdkESX" value="0x08">
12262	<desc>
12263	VMDK format variant used on ESX products.
12264	</desc>
12265	</const>
12266	<const name="Fixed" value="0x10000">
12267	<desc>
12268	Fixed image. Only allowed for base images.
12269	</desc>
12270	</const>
12271	<const name="Diff" value="0x20000">
12272	<desc>
12273	Differencing image. Only allowed for child images.
12274	</desc>
12275	</const>
12276	<const name="NoCreateDir" value="0x40000000">
12277	<desc>
12278	Special flag which suppresses automatic creation of the subdirectory.
12279	Only used when passing the medium variant as an input parameter.
12280	</desc>
12281	</const>
12282	</enum>
12283
12284	<interface
12285	name="IMediumAttachment" extends="$unknown"
12286	uuid="5ee464d6-0613-4331-b154-7ce12170ef9f"
12287	wsmap="struct"
12288	>
12289	<desc>
12290	The IMediumAttachment interface links storage media to virtual machines.
12291	For each medium (<link to="IMedium"/>) which has been attached to a
12292	storage controller (<link to="IStorageController"/>) of a machine
12293	(<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
12294	method, one instance of IMediumAttachment is added to the machine's
12295	<link to="IMachine::mediumAttachments"/> array attribute.
12296
12297	Each medium attachment specifies the storage controller as well as a
12298	port and device number and the IMedium instance representing a virtual
12299	hard disk or floppy or DVD image.
12300
12301	For removable media (DVDs or floppies), there are two additional
12302	options. For one, the IMedium instance can be @c null to represent
12303	an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
12304	secondly, the medium can be one of the pseudo-media for host drives
12305	listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
12306
12307	<h3>Attaching Hard Disks</h3>
12308
12309	Hard disks are attached to virtual machines using the
12310	<link to="IMachine::attachDevice"/> method and detached using the
12311	<link to="IMachine::detachDevice"/> method. Depending on a medium's
12312	type (see <link to="IMedium::type" />), hard disks are attached either
12313	<i>directly</i> or <i>indirectly</i>.
12314
12315	When a hard disk is being attached directly, it is associated with the
12316	virtual machine and used for hard disk operations when the machine is
12317	running. When a hard disk is being attached indirectly, a new differencing
12318	hard disk linked to it is implicitly created and this differencing hard
12319	disk is associated with the machine and used for hard disk operations.
12320	This also means that if <link to="IMachine::attachDevice"/> performs
12321	a direct attachment then the same hard disk will be returned in response
12322	to the subsequent <link to="IMachine::getMedium"/> call; however if
12323	an indirect attachment is performed then
12324	<link to="IMachine::getMedium"/> will return the implicitly created
12325	differencing hard disk, not the original one passed to <link
12326	to="IMachine::attachDevice"/>. In detail:
12327
12328	<ul>
12329	<li><b>Normal base</b> hard disks that do not have children (i.e.
12330	differencing hard disks linked to them) and that are not already
12331	attached to virtual machines in snapshots are attached <b>directly</b>.
12332	Otherwise, they are attached <b>indirectly</b> because having
12333	dependent children or being part of the snapshot makes it impossible
12334	to modify hard disk contents without breaking the integrity of the
12335	dependent party. The <link to="IMedium::readOnly"/> attribute allows to
12336	quickly determine the kind of the attachment for the given hard
12337	disk. Note that if a normal base hard disk is to be indirectly
12338	attached to a virtual machine with snapshots then a special
12339	procedure called <i>smart attachment</i> is performed (see below).</li>
12340	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
12341	they are attached <b>directly</b> if they do not have children and are
12342	not attached to virtual machines in snapshots, and <b>indirectly</b>
12343	otherwise. Note that the smart attachment procedure is never performed
12344	for differencing hard disks.</li>
12345	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
12346	they are designed to be non-writable. If an immutable hard disk is
12347	attached to a virtual machine with snapshots then a special
12348	procedure called smart attachment is performed (see below).</li>
12349	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
12350	also as designed. This also means that writethrough hard disks cannot
12351	have other hard disks linked to them at all.</li>
12352	<li><b>Shareable</b> hard disks are always attached <b>directly</b>,
12353	also as designed. This also means that shareable hard disks cannot
12354	have other hard disks linked to them at all. They behave almost
12355	like writethrough hard disks, except that shareable hard disks can
12356	be attached to several virtual machines which are running, allowing
12357	concurrent accesses. You need special cluster software running in
12358	the virtual machines to make use of such disks.</li>
12359	</ul>
12360
12361	Note that the same hard disk, regardless of its type, may be attached to
12362	more than one virtual machine at a time. In this case, the machine that is
12363	started first gains exclusive access to the hard disk and attempts to
12364	start other machines having this hard disk attached will fail until the
12365	first machine is powered down.
12366
12367	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
12368	that the given hard disk remains associated with the given machine after a
12369	successful <link to="IMachine::detachDevice"/> call until
12370	<link to="IMachine::saveSettings"/> is called to save all changes to
12371	machine settings to disk. This deferring is necessary to guarantee that
12372	the hard disk configuration may be restored at any time by a call to
12373	<link to="IMachine::discardSettings"/> before the settings
12374	are saved (committed).
12375
12376	Note that if <link to="IMachine::discardSettings"/> is called after
12377	indirectly attaching some hard disks to the machine but before a call to
12378	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
12379	all differencing hard disks implicitly created by
12380	<link to="IMachine::attachDevice"/> for these indirect attachments.
12381	Such implicitly created hard disks will also be immediately deleted when
12382	detached explicitly using the <link to="IMachine::detachDevice"/>
12383	call if it is made before <link to="IMachine::saveSettings"/>. This
12384	implicit deletion is safe because newly created differencing hard
12385	disks do not contain any user data.
12386
12387	However, keep in mind that detaching differencing hard disks that were
12388	implicitly created by <link to="IMachine::attachDevice"/>
12389	before the last <link to="IMachine::saveSettings"/> call will
12390	<b>not</b> implicitly delete them as they may already contain some data
12391	(for example, as a result of virtual machine execution). If these hard
12392	disks are no more necessary, the caller can always delete them explicitly
12393	using <link to="IMedium::deleteStorage"/> after they are actually de-associated
12394	from this machine by the <link to="IMachine::saveSettings"/> call.
12395
12396	<h3>Smart Attachment</h3>
12397
12398	When normal base or immutable hard disks are indirectly attached to a
12399	virtual machine then some additional steps are performed to make sure the
12400	virtual machine will have the most recent "view" of the hard disk being
12401	attached. These steps include walking through the machine's snapshots
12402	starting from the current one and going through ancestors up to the first
12403	snapshot. Hard disks attached to the virtual machine in all
12404	of the encountered snapshots are checked whether they are descendants of
12405	the given normal base or immutable hard disk. The first found child (which
12406	is the differencing hard disk) will be used instead of the normal base or
12407	immutable hard disk as a parent for creating a new differencing hard disk
12408	that will be actually attached to the machine. And only if no descendants
12409	are found or if the virtual machine does not have any snapshots then the
12410	normal base or immutable hard disk will be used itself as a parent for
12411	this differencing hard disk.
12412
12413	It is easier to explain what smart attachment does using the
12414	following example:
12415	<pre>
12416	BEFORE attaching B.vdi: AFTER attaching B.vdi:
12417
12418	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
12419	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
12420	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
12421	Snapshot 4 (none) Snapshot 4 (none)
12422	CurState (none) CurState (D3->D2.vdi)
12423
12424	NOT
12425	...
12426	CurState (D3->B.vdi)
12427	</pre>
12428	The first column is the virtual machine configuration before the base hard
12429	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
12430	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
12431	mean that the hard disk that is actually attached to the machine is a
12432	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
12433	another hard disk, <tt>B.vdi</tt>.
12434
12435	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
12436	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
12437	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
12438	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
12439	it cannot be attached directly and needs an indirect attachment (i.e.
12440	implicit creation of a new differencing hard disk). Due to the smart
12441	attachment procedure, the new differencing hard disk
12442	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
12443	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
12444	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
12445	machine.
12446
12447	Note that if there is more than one descendant hard disk of the given base
12448	hard disk found in a snapshot, and there is an exact device, channel and
12449	bus match, then this exact match will be used. Otherwise, the youngest
12450	descendant will be picked up.
12451
12452	There is one more important aspect of the smart attachment procedure which
12453	is not related to snapshots at all. Before walking through the snapshots
12454	as described above, the backup copy of the current list of hard disk
12455	attachment is searched for descendants. This backup copy is created when
12456	the hard disk configuration is changed for the first time after the last
12457	<link to="IMachine::saveSettings"/> call and used by
12458	<link to="IMachine::discardSettings"/> to undo the recent hard disk
12459	changes. When such a descendant is found in this backup copy, it will be
12460	simply re-attached back, without creating a new differencing hard disk for
12461	it. This optimization is necessary to make it possible to re-attach the
12462	base or immutable hard disk to a different bus, channel or device slot
12463	without losing the contents of the differencing hard disk actually
12464	attached to the machine in place of it.
12465
12466	</desc>
12467
12468	<attribute name="medium" type="IMedium" readonly="yes">
12469	<desc>Medium object associated with this attachment; it
12470	can be @c null for removable devices.</desc>
12471	</attribute>
12472
12473	<attribute name="controller" type="wstring" readonly="yes">
12474	<desc>Name of the storage controller of this attachment; this
12475	refers to one of the controllers in <link to="IMachine::storageControllers" />
12476	by name.</desc>
12477	</attribute>
12478
12479	<attribute name="port" type="long" readonly="yes">
12480	<desc>Port number of this attachment.
12481	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
12482	</desc>
12483	</attribute>
12484
12485	<attribute name="device" type="long" readonly="yes">
12486	<desc>Device slot number of this attachment.
12487	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
12488	</desc>
12489	</attribute>
12490
12491	<attribute name="type" type="DeviceType" readonly="yes">
12492	<desc>Device type of this attachment.</desc>
12493	</attribute>
12494
12495	<attribute name="passthrough" type="boolean" readonly="yes">
12496	<desc>Pass I/O requests through to a device on the host.</desc>
12497	</attribute>
12498
12499	<attribute name="temporaryEject" type="boolean" readonly="yes">
12500	<desc>Whether guest-triggered eject results in unmounting the medium.</desc>
12501	</attribute>
12502
12503	<attribute name="isEjected" type="boolean" readonly="yes">
12504	<desc>Signals that the removable medium has been ejected. This is not
12505	necessarily equivalent to having a @c null medium association.</desc>
12506	</attribute>
12507
12508	<attribute name="nonRotational" type="boolean" readonly="yes">
12509	<desc>Whether the associated medium is non-rotational.</desc>
12510	</attribute>
12511
12512	<attribute name="discard" type="boolean" readonly="yes">
12513	<desc>Whether the associated medium supports discarding unused blocks.</desc>
12514	</attribute>
12515
12516	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
12517	<desc>The bandwidth group this medium attachment is assigned to.</desc>
12518	</attribute>
12519
12520	</interface>
12521
12522	<interface
12523	name="IMedium" extends="$unknown"
12524	uuid="86fd6208-4c8c-40c2-a4e3-f6b47ac6ef07"
12525	wsmap="managed"
12526	>
12527	<desc>
12528	The IMedium interface represents virtual storage for a machine's
12529	hard disks, CD/DVD or floppy drives. It will typically represent
12530	a disk image on the host, for example a VDI or VMDK file representing
12531	a virtual hard disk, or an ISO or RAW file representing virtual
12532	removable media, but can also point to a network location (e.g.
12533	for iSCSI targets).
12534
12535	Instances of IMedium are connected to virtual machines by way of medium
12536	attachments, which link the storage medium to a particular device slot
12537	of a storage controller of the virtual machine.
12538	In the VirtualBox API, virtual storage is therefore always represented
12539	by the following chain of object links:
12540
12541	<ul>
12542	<li><link to="IMachine::storageControllers"/> contains an array of
12543	storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
12544	these are instances of <link to="IStorageController"/>).</li>
12545	<li><link to="IMachine::mediumAttachments"/> contains an array of
12546	medium attachments (instances of <link to="IMediumAttachment"/>
12547	created by <link to="IMachine::attachDevice" />),
12548	each containing a storage controller from the above array, a
12549	port/device specification, and an instance of IMedium representing
12550	the medium storage (image file).
12551
12552	For removable media, the storage medium is optional; a medium
12553	attachment with no medium represents a CD/DVD or floppy drive
12554	with no medium inserted. By contrast, hard disk attachments
12555	will always have an IMedium object attached.</li>
12556	<li>Each IMedium in turn points to a storage unit (such as a file
12557	on the host computer or a network resource) that holds actual
12558	data. This location is represented by the <link to="#location"/>
12559	attribute.</li>
12560	</ul>
12561
12562	Existing media are opened using <link to="IVirtualBox::openMedium"/>;
12563	new hard disk media can be created with the VirtualBox API using the
12564	<link to="IVirtualBox::createHardDisk"/> method. Differencing hard
12565	disks (see below) are usually implicitly created by VirtualBox as
12566	needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
12567	VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
12568	should be created with external tools and then opened from within VirtualBox.
12569
12570	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
12571	drive. In that case the <link to="#id" /> attribute contains the UUID of
12572	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
12573
12574	<h3>Media registries</h3>
12575
12576	When a medium has been opened or created using one of the aforementioned
12577	APIs, it becomes "known" to VirtualBox. Known media can be attached
12578	to virtual machines and re-found through <link to="IVirtualBox::openMedium"/>.
12579	They also appear in the global
12580	<link to="IVirtualBox::hardDisks" />,
12581	<link to="IVirtualBox::DVDImages" /> and
12582	<link to="IVirtualBox::floppyImages" /> arrays.
12583
12584	Prior to VirtualBox 4.0, opening a medium added it to a global media registry
12585	in the VirtualBox.xml file, which was shared between all machines and made
12586	transporting machines and their media from one host to another difficult.
12587
12588	Starting with VirtualBox 4.0, media are only added to a registry when they are
12589	<i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
12590	backwards compatibility, which registry a medium is added to depends on which
12591	VirtualBox version created a machine:
12592
12593	<ul>
12594	<li>If the medium has first been attached to a machine which was created by
12595	VirtualBox 4.0 or later, it is added to that machine's media registry in
12596	the machine XML settings file. This way all information about a machine's
12597	media attachments is contained in a single file and can be transported
12598	easily.</li>
12599	<li>For older media attachments (i.e. if the medium was first attached to a
12600	machine which was created with a VirtualBox version before 4.0), media
12601	continue to be registered in the global VirtualBox settings file, for
12602	backwards compatibility.</li>
12603	</ul>
12604
12605	See <link to="IVirtualBox::openMedium" /> for more information.
12606
12607	Media are removed from media registries by the <link to="IMedium::close"/>,
12608	<link to="#deleteStorage"/> and <link to="#mergeTo"/> methods.
12609
12610	<h3>Accessibility checks</h3>
12611
12612	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
12613	method is called explicitly on a medium. This is done to make the VirtualBox object
12614	ready for serving requests as fast as possible and let the end-user
12615	application decide if it needs to check media accessibility right away or not.
12616
12617	As a result, when VirtualBox starts up (e.g. the VirtualBox
12618	object gets created for the first time), all known media are in the
12619	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
12620	attribute is an empty string because no actual accessibility check has
12621	been made yet.
12622
12623	After calling <link to="#refreshState" />, a medium is considered
12624	<i>accessible</i> if its storage unit can be read. In that case, the
12625	<link to="#state"/> attribute has a value of "Created". If the storage
12626	unit cannot be read (for example, because it is located on a disconnected
12627	network resource, or was accidentally deleted outside VirtualBox),
12628	the medium is considered <i>inaccessible</i>, which is indicated by the
12629	"Inaccessible" state. The exact reason why the medium is inaccessible can be
12630	obtained by reading the <link to="#lastAccessError"/> attribute.
12631
12632	<h3>Medium types</h3>
12633
12634	There are five types of medium behavior which are stored in the
12635	<link to="#type"/> attribute (see <link to="MediumType" />) and
12636	which define the medium's behavior with attachments and snapshots.
12637
12638	All media can be also divided in two groups: <i>base</i> media and
12639	<i>differencing</i> media. A base medium contains all sectors of the
12640	medium data in its own storage and therefore can be used independently.
12641	In contrast, a differencing medium is a "delta" to some other medium and
12642	contains only those sectors which differ from that other medium, which is
12643	then called a <i>parent</i>. The differencing medium is said to be
12644	<i>linked to</i> that parent. The parent may be itself a differencing
12645	medium, thus forming a chain of linked media. The last element in that
12646	chain must always be a base medium. Note that several differencing
12647	media may be linked to the same parent medium.
12648
12649	Differencing media can be distinguished from base media by querying the
12650	<link to="#parent"/> attribute: base media do not have parents they would
12651	depend on, so the value of this attribute is always @c null for them.
12652	Using this attribute, it is possible to walk up the medium tree (from the
12653	child medium to its parent). It is also possible to walk down the tree
12654	using the <link to="#children"/> attribute.
12655
12656	Note that the type of all differencing media is "normal"; all other
12657	values are meaningless for them. Base media may be of any type.
12658
12659	<h3>Automatic composition of the file name part</h3>
12660
12661	Another extension to the <link to="IMedium::location"/> attribute is that
12662	there is a possibility to cause VirtualBox to compose a unique value for
12663	the file name part of the location using the UUID of the hard disk. This
12664	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
12665	e.g. before the storage unit is created, and works as follows. You set the
12666	value of the <link to="IMedium::location"/> attribute to a location
12667	specification which only contains the path specification but not the file
12668	name part and ends with either a forward slash or a backslash character.
12669	In response, VirtualBox will generate a new UUID for the hard disk and
12670	compose the file name using the following pattern:
12671	<pre>
12672	<path>/{<uuid>}.<ext>
12673	</pre>
12674	where <tt><path></tt> is the supplied path specification,
12675	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
12676	is the default extension for the storage format of this hard disk. After
12677	that, you may call any of the methods that create a new hard disk storage
12678	unit and they will use the generated UUID and file name.
12679	</desc>
12680
12681	<attribute name="id" type="uuid" mod="string" readonly="yes">
12682	<desc>
12683	UUID of the medium. For a newly created medium, this value is a randomly
12684	generated UUID.
12685
12686	<note>
12687	For media in one of MediumState_NotCreated, MediumState_Creating or
12688	MediumState_Deleting states, the value of this property is undefined
12689	and will most likely be an empty UUID.
12690	</note>
12691	</desc>
12692	</attribute>
12693
12694	<attribute name="description" type="wstring">
12695	<desc>
12696	Optional description of the medium. For a newly created medium the value
12697	of this attribute is an empty string.
12698
12699	Medium types that don't support this attribute will return E_NOTIMPL in
12700	attempt to get or set this attribute's value.
12701
12702	<note>
12703	For some storage types, reading this attribute may return an outdated
12704	(last known) value when <link to="#state"/> is <link
12705	to="MediumState_Inaccessible"/> or <link
12706	to="MediumState_LockedWrite"/> because the value of this attribute is
12707	stored within the storage unit itself. Also note that changing the
12708	attribute value is not possible in such case, as well as when the
12709	medium is the <link to="MediumState_LockedRead"/> state.
12710	</note>
12711	</desc>
12712	</attribute>
12713
12714	<attribute name="state" type="MediumState" readonly="yes">
12715	<desc>
12716	Returns the current medium state, which is the last state set by
12717	the accessibility check performed by <link to="#refreshState"/>.
12718	If that method has not yet been called on the medium, the state
12719	is "Inaccessible"; as opposed to truly inaccessible media, the
12720	value of <link to="#lastAccessError"/> will be an empty string in
12721	that case.
12722
12723	<note>As of version 3.1, this no longer performs an accessibility check
12724	automatically; call <link to="#refreshState"/> for that.
12725	</note>
12726	</desc>
12727	</attribute>
12728
12729	<attribute name="variant" type="MediumVariant" safearray="yes" readonly="yes">
12730	<desc>
12731	Returns the storage format variant information for this medium
12732	as an aaray of the flags described at <link to="MediumVariant" />.
12733	Before <link to="#refreshState"/> is called this method returns
12734	an undefined value.
12735	</desc>
12736	</attribute>
12737
12738	<attribute name="location" type="wstring">
12739	<desc>
12740	Location of the storage unit holding medium data.
12741
12742	The format of the location string is medium type specific. For medium
12743	types using regular files in a host's file system, the location
12744	string is the full file name.
12745
12746	Some medium types may support changing the storage unit location by
12747	simply changing the value of this property. If this operation is not
12748	supported, the implementation will return E_NOTIMPL in attempt to set
12749	this attribute's value.
12750
12751	When setting a value of the location attribute which is a regular file
12752	in the host's file system, the given file name may be either relative to
12753	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
12754	absolute. Note that if the given location specification does not contain
12755	the file extension part then a proper default extension will be
12756	automatically appended by the implementation depending on the medium type.
12757	</desc>
12758	</attribute>
12759
12760	<attribute name="name" type="wstring" readonly="yes">
12761	<desc>
12762	Name of the storage unit holding medium data.
12763
12764	The returned string is a short version of the <link to="#location"/>
12765	attribute that is suitable for representing the medium in situations
12766	where the full location specification is too long (such as lists
12767	and comboboxes in GUI frontends). This string is also used by frontends
12768	to sort the media list alphabetically when needed.
12769
12770	For example, for locations that are regular files in the host's file
12771	system, the value of this attribute is just the file name (+ extension),
12772	without the path specification.
12773
12774	Note that as opposed to the <link to="#location"/> attribute, the name
12775	attribute will not necessary be unique for a list of media of the
12776	given type and format.
12777	</desc>
12778	</attribute>
12779
12780	<attribute name="deviceType" type="DeviceType" readonly="yes">
12781	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
12782	medium.</desc>
12783	</attribute>
12784
12785	<attribute name="hostDrive" type="boolean" readonly="yes">
12786	<desc>True if this corresponds to a drive on the host.</desc>
12787	</attribute>
12788
12789	<attribute name="size" type="long long" readonly="yes">
12790	<desc>
12791	Physical size of the storage unit used to hold medium data (in bytes).
12792
12793	<note>
12794	For media whose <link to="#state"/> is <link
12795	to="MediumState_Inaccessible"/>, the value of this property is the
12796	last known size. For <link to="MediumState_NotCreated"/> media,
12797	the returned value is zero.
12798	</note>
12799	</desc>
12800	</attribute>
12801
12802	<attribute name="format" type="wstring" readonly="yes">
12803	<desc>
12804	Storage format of this medium.
12805
12806	The value of this attribute is a string that specifies a backend used
12807	to store medium data. The storage format is defined when you create a
12808	new medium or automatically detected when you open an existing medium,
12809	and cannot be changed later.
12810
12811	The list of all storage formats supported by this VirtualBox
12812	installation can be obtained using
12813	<link to="ISystemProperties::mediumFormats"/>.
12814	</desc>
12815	</attribute>
12816
12817	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
12818	<desc>
12819	Storage medium format object corresponding to this medium.
12820
12821	The value of this attribute is a reference to the medium format object
12822	that specifies the backend properties used to store medium data. The
12823	storage format is defined when you create a new medium or automatically
12824	detected when you open an existing medium, and cannot be changed later.
12825
12826	<note>@c null is returned if there is no associated medium format
12827	object. This can e.g. happen for medium objects representing host
12828	drives and other special medium objects.</note>
12829	</desc>
12830	</attribute>
12831
12832	<attribute name="type" type="MediumType">
12833	<desc>
12834	Type (role) of this medium.
12835
12836	The following constraints apply when changing the value of this
12837	attribute:
12838	<ul>
12839	<li>If a medium is attached to a virtual machine (either in the
12840	current state or in one of the snapshots), its type cannot be
12841	changed.
12842	</li>
12843	<li>As long as the medium has children, its type cannot be set
12844	to <link to="MediumType_Writethrough"/>.
12845	</li>
12846	<li>The type of all differencing media is
12847	<link to="MediumType_Normal"/> and cannot be changed.
12848	</li>
12849	</ul>
12850
12851	The type of a newly created or opened medium is set to
12852	<link to="MediumType_Normal"/>, except for DVD and floppy media,
12853	which have a type of <link to="MediumType_Writethrough"/>.
12854	</desc>
12855	</attribute>
12856
12857	<attribute name="allowedTypes" type="MediumType" safearray="yes" readonly="yes">
12858	<desc>
12859	Returns which medium types can selected for this medium.
12860
12861	<result name="E_NOTIMPL">
12862	This attribute is not implemented at the moment.
12863	</result>
12864	</desc>
12865	</attribute>
12866
12867	<attribute name="parent" type="IMedium" readonly="yes">
12868	<desc>
12869	Parent of this medium (the medium this medium is directly based
12870	on).
12871
12872	Only differencing media have parents. For base (non-differencing)
12873	media, @c null is returned.
12874	</desc>
12875	</attribute>
12876
12877	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
12878	<desc>
12879	Children of this medium (all differencing media directly based
12880	on this medium). A @c null array is returned if this medium
12881	does not have any children.
12882	</desc>
12883	</attribute>
12884
12885	<attribute name="base" type="IMedium" readonly="yes">
12886	<desc>
12887	Base medium of this medium.
12888
12889	If this is a differencing medium, its base medium is the medium
12890	the given medium branch starts from. For all other types of media, this
12891	property returns the medium object itself (i.e. the same object this
12892	property is read on).
12893	</desc>
12894	</attribute>
12895
12896	<attribute name="readOnly" type="boolean" readonly="yes">
12897	<desc>
12898	Returns @c true if this medium is read-only and @c false otherwise.
12899
12900	A medium is considered to be read-only when its contents cannot be
12901	modified without breaking the integrity of other parties that depend on
12902	this medium such as its child media or snapshots of virtual machines
12903	where this medium is attached to these machines. If there are no
12904	children and no such snapshots then there is no dependency and the
12905	medium is not read-only.
12906
12907	The value of this attribute can be used to determine the kind of the
12908	attachment that will take place when attaching this medium to a
12909	virtual machine. If the value is @c false then the medium will
12910	be attached directly. If the value is @c true then the medium
12911	will be attached indirectly by creating a new differencing child
12912	medium for that. See the interface description for more information.
12913
12914	Note that all <link to="MediumType_Immutable">Immutable</link> media
12915	are always read-only while all
12916	<link to="MediumType_Writethrough">Writethrough</link> media are
12917	always not.
12918
12919	<note>
12920	The read-only condition represented by this attribute is related to
12921	the medium type and usage, not to the current
12922	<link to="IMedium::state">medium state</link> and not to the read-only
12923	state of the storage unit.
12924	</note>
12925	</desc>
12926	</attribute>
12927
12928	<attribute name="logicalSize" type="long long" readonly="yes">
12929	<desc>
12930	Logical size of this medium (in bytes), as reported to the
12931	guest OS running inside the virtual machine this medium is
12932	attached to. The logical size is defined when the medium is created
12933	and cannot be changed later.
12934
12935	<note>
12936	For media whose state is <link to="#state"/> is <link
12937	to="MediumState_Inaccessible"/>, the value of this property is the
12938	last known logical size. For <link to="MediumState_NotCreated"/>
12939	media, the returned value is zero.
12940	</note>
12941	</desc>
12942	</attribute>
12943
12944	<attribute name="autoReset" type="boolean">
12945	<desc>
12946	Whether this differencing medium will be automatically reset each
12947	time a virtual machine it is attached to is powered up. This
12948	attribute is automatically set to @c true for the last
12949	differencing image of an "immutable" medium (see
12950	<link to="MediumType" />).
12951
12952	See <link to="#reset"/> for more information about resetting
12953	differencing media.
12954
12955	<note>
12956	Reading this property on a base (non-differencing) medium will
12957	always @c false. Changing the value of this property in this
12958	case is not supported.
12959	</note>
12960
12961	<result name="VBOX_E_NOT_SUPPORTED">
12962	This is not a differencing medium (when changing the attribute
12963	value).
12964	</result>
12965	</desc>
12966	</attribute>
12967
12968	<attribute name="lastAccessError" type="wstring" readonly="yes">
12969	<desc>
12970	Text message that represents the result of the last accessibility
12971	check performed by <link to="#refreshState"/>.
12972
12973	An empty string is returned if the last accessibility check
12974	was successful or has not yet been called. As a result, if
12975	<link to="#state" /> is "Inaccessible" and this attribute is empty,
12976	then <link to="#refreshState"/> has yet to be called; this is the
12977	default value of media after VirtualBox initialization.
12978	A non-empty string indicates a failure and should normally describe
12979	a reason of the failure (for example, a file read error).
12980	</desc>
12981	</attribute>
12982
12983	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
12984	<desc>
12985	Array of UUIDs of all machines this medium is attached to.
12986
12987	A @c null array is returned if this medium is not attached to any
12988	machine or to any machine's snapshot.
12989
12990	<note>
12991	The returned array will include a machine even if this medium is not
12992	attached to that machine in the current state but attached to it in
12993	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
12994	details.
12995	</note>
12996	</desc>
12997	</attribute>
12998
12999	<method name="setIds">
13000	<desc>
13001	Changes the UUID and parent UUID for a hard disk medium.
13002	</desc>
13003	<param name="setImageId" type="boolean" dir="in">
13004	<desc>
13005	Select whether a new image UUID is set or not.
13006	</desc>
13007	</param>
13008	<param name="imageId" type="uuid" mod="string" dir="in">
13009	<desc>
13010	New UUID for the image. If an empty string is passed, then a new
13011	UUID is automatically created, provided that @a setImageId is @c true.
13012	Specifying a zero UUID is not allowed.
13013	</desc>
13014	</param>
13015	<param name="setParentId" type="boolean" dir="in">
13016	<desc>
13017	Select whether a new parent UUID is set or not.
13018	</desc>
13019	</param>
13020	<param name="parentId" type="uuid" mod="string" dir="in">
13021	<desc>
13022	New parent UUID for the image. If an empty string is passed, then a
13023	new UUID is automatically created, provided @a setParentId is
13024	@c true. A zero UUID is valid.
13025	</desc>
13026	</param>
13027	<result name="E_INVALIDARG">
13028	Invalid parameter combination.
13029	</result>
13030	<result name="VBOX_E_NOT_SUPPORTED">
13031	Medium is not a hard disk medium.
13032	</result>
13033	</method>
13034
13035	<method name="refreshState">
13036	<desc>
13037	If the current medium state (see <link to="MediumState"/>) is one of
13038	"Created", "Inaccessible" or "LockedRead", then this performs an
13039	accessibility check on the medium and sets the value of the <link to="#state"/>
13040	attribute accordingly; that value is also returned for convenience.
13041
13042	For all other state values, this does not perform a refresh but returns
13043	the state only.
13044
13045	The refresh, if performed, may take a long time (several seconds or even
13046	minutes, depending on the storage unit location and format) because it performs an
13047	accessibility check of the storage unit. This check may cause a significant
13048	delay if the storage unit of the given medium is, for example, a file located
13049	on a network share which is not currently accessible due to connectivity
13050	problems. In that case, the call will not return until a timeout
13051	interval defined by the host OS for this operation expires. For this reason,
13052	it is recommended to never read this attribute on the main UI thread to avoid
13053	making the UI unresponsive.
13054
13055	If the last known state of the medium is "Created" and the accessibility
13056	check fails, then the state would be set to "Inaccessible", and
13057	<link to="#lastAccessError"/> may be used to get more details about the
13058	failure. If the state of the medium is "LockedRead", then it remains the
13059	same, and a non-empty value of <link to="#lastAccessError"/> will
13060	indicate a failed accessibility check in this case.
13061
13062	Note that not all medium states are applicable to all medium types.
13063	</desc>
13064	<param name="state" type="MediumState" dir="return">
13065	<desc>
13066	New medium state.
13067	</desc>
13068	</param>
13069	</method>
13070
13071	<method name="getSnapshotIds">
13072	<desc>
13073	Returns an array of UUIDs of all snapshots of the given machine where
13074	this medium is attached to.
13075
13076	If the medium is attached to the machine in the current state, then the
13077	first element in the array will always be the ID of the queried machine
13078	(i.e. the value equal to the @c machineId argument), followed by
13079	snapshot IDs (if any).
13080
13081	If the medium is not attached to the machine in the current state, then
13082	the array will contain only snapshot IDs.
13083
13084	The returned array may be @c null if this medium is not attached
13085	to the given machine at all, neither in the current state nor in one of
13086	the snapshots.
13087	</desc>
13088	<param name="machineId" type="uuid" mod="string" dir="in">
13089	<desc>
13090	UUID of the machine to query.
13091	</desc>
13092	</param>
13093	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
13094	<desc>
13095	Array of snapshot UUIDs of the given machine using this medium.
13096	</desc>
13097	</param>
13098	</method>
13099
13100	<method name="lockRead">
13101	<desc>
13102	Locks this medium for reading.
13103
13104	A read lock is shared: many clients can simultaneously lock the
13105	same medium for reading unless it is already locked for writing (see
13106	<link to="#lockWrite"/>) in which case an error is returned.
13107
13108	When the medium is locked for reading, it cannot be modified
13109	from within VirtualBox. This means that any method that changes
13110	the properties of this medium or contents of the storage unit
13111	will return an error (unless explicitly stated otherwise). That
13112	includes an attempt to start a virtual machine that wants to
13113	write to the the medium.
13114
13115	When the virtual machine is started up, it locks for reading all
13116	media it uses in read-only mode. If some medium cannot be locked
13117	for reading, the startup procedure will fail.
13118	A medium is typically locked for reading while it is used by a running
13119	virtual machine but has a depending differencing image that receives
13120	the actual write operations. This way one base medium can have
13121	multiple child differencing images which can be written to
13122	simultaneously. Read-only media such as DVD and floppy images are
13123	also locked for reading only (so they can be in use by multiple
13124	machines simultaneously).
13125
13126	A medium is also locked for reading when it is the source of a
13127	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13128
13129	The medium locked for reading must be unlocked using the <link
13130	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
13131	can be nested and must be followed by the same number of paired
13132	<link to="#unlockRead"/> calls.
13133
13134	This method sets the medium state (see <link to="#state"/>) to
13135	"LockedRead" on success. The medium's previous state must be
13136	one of "Created", "Inaccessible" or "LockedRead".
13137
13138	Locking an inaccessible medium is not an error; this method performs
13139	a logical lock that prevents modifications of this medium through
13140	the VirtualBox API, not a physical file-system lock of the underlying
13141	storage unit.
13142
13143	This method returns the current state of the medium
13144	<i>before</i> the operation.
13145
13146	<result name="VBOX_E_INVALID_OBJECT_STATE">
13147	Invalid medium state (e.g. not created, locked, inaccessible,
13148	creating, deleting).
13149	</result>
13150
13151	</desc>
13152	<param name="state" type="MediumState" dir="return">
13153	<desc>
13154	State of the medium after the operation.
13155	</desc>
13156	</param>
13157	</method>
13158
13159	<method name="unlockRead">
13160	<desc>
13161	Cancels the read lock previously set by <link to="#lockRead"/>.
13162
13163	For both success and failure, this method returns the current state
13164	of the medium <i>after</i> the operation.
13165
13166	See <link to="#lockRead"/> for more details.
13167
13168	<result name="VBOX_E_INVALID_OBJECT_STATE">
13169	Medium not locked for reading.
13170	</result>
13171
13172	</desc>
13173	<param name="state" type="MediumState" dir="return">
13174	<desc>
13175	State of the medium after the operation.
13176	</desc>
13177	</param>
13178	</method>
13179
13180	<method name="lockWrite">
13181	<desc>
13182	Locks this medium for writing.
13183
13184	A write lock, as opposed to <link to="#lockRead"/>, is
13185	exclusive: there may be only one client holding a write lock,
13186	and there may be no read locks while the write lock is held.
13187	As a result, read-locking fails if a write lock is held, and
13188	write-locking fails if either a read or another write lock is held.
13189
13190	When a medium is locked for writing, it cannot be modified
13191	from within VirtualBox, and it is not guaranteed that the values
13192	of its properties are up-to-date. Any method that changes the
13193	properties of this medium or contents of the storage unit will
13194	return an error (unless explicitly stated otherwise).
13195
13196	When a virtual machine is started up, it locks for writing all
13197	media it uses to write data to. If any medium could not be locked
13198	for writing, the startup procedure will fail. If a medium has
13199	differencing images, then while the machine is running, only
13200	the last ("leaf") differencing image is locked for writing,
13201	whereas its parents are locked for reading only.
13202
13203	A medium is also locked for writing when it is the target of a
13204	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13205
13206	The medium locked for writing must be unlocked using the <link
13207	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
13208
13209	This method sets the medium state (see <link to="#state"/>) to
13210	"LockedWrite" on success. The medium's previous state must be
13211	either "Created" or "Inaccessible".
13212
13213	Locking an inaccessible medium is not an error; this method performs
13214	a logical lock that prevents modifications of this medium through
13215	the VirtualBox API, not a physical file-system lock of the underlying
13216	storage unit.
13217
13218	For both, success and failure, this method returns the current
13219	state of the medium <i>before</i> the operation.
13220
13221	<result name="VBOX_E_INVALID_OBJECT_STATE">
13222	Invalid medium state (e.g. not created, locked, inaccessible,
13223	creating, deleting).
13224	</result>
13225
13226	</desc>
13227	<param name="state" type="MediumState" dir="return">
13228	<desc>
13229	State of the medium after the operation.
13230	</desc>
13231	</param>
13232	</method>
13233
13234	<method name="unlockWrite">
13235	<desc>
13236	Cancels the write lock previously set by <link to="#lockWrite"/>.
13237
13238	For both success and failure, this method returns the current
13239	state of the medium <i>after</i> the operation.
13240
13241	See <link to="#lockWrite"/> for more details.
13242
13243	<result name="VBOX_E_INVALID_OBJECT_STATE">
13244	Medium not locked for writing.
13245	</result>
13246
13247	</desc>
13248	<param name="state" type="MediumState" dir="return">
13249	<desc>
13250	State of the medium after the operation.
13251	</desc>
13252	</param>
13253	</method>
13254
13255	<method name="close">
13256	<desc>
13257	Closes this medium.
13258
13259	The medium must not be attached to any known virtual machine
13260	and must not have any known child media, otherwise the
13261	operation will fail.
13262
13263	When the medium is successfully closed, it is removed from
13264	the list of registered media, but its storage unit is not
13265	deleted. In particular, this means that this medium can
13266	later be opened again using the <link to="IVirtualBox::openMedium"/>
13267	call.
13268
13269	Note that after this method successfully returns, the given medium
13270	object becomes uninitialized. This means that any attempt
13271	to call any of its methods or attributes will fail with the
13272	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
13273
13274	<result name="VBOX_E_INVALID_OBJECT_STATE">
13275	Invalid medium state (other than not created, created or
13276	inaccessible).
13277	</result>
13278	<result name="VBOX_E_OBJECT_IN_USE">
13279	Medium attached to virtual machine.
13280	</result>
13281	<result name="VBOX_E_FILE_ERROR">
13282	Settings file not accessible.
13283	</result>
13284	<result name="VBOX_E_XML_ERROR">
13285	Could not parse the settings file.
13286	</result>
13287
13288	</desc>
13289	</method>
13290
13291	<!-- property methods -->
13292
13293	<method name="getProperty" const="yes">
13294	<desc>
13295	Returns the value of the custom medium property with the given name.
13296
13297	The list of all properties supported by the given medium format can
13298	be obtained with <link to="IMediumFormat::describeProperties"/>.
13299
13300	<note>If this method returns an empty string in @a value, the requested
13301	property is supported but currently not assigned any value.</note>
13302
13303	<result name="VBOX_E_OBJECT_NOT_FOUND">
13304	Requested property does not exist (not supported by the format).
13305	</result>
13306	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13307	</desc>
13308	<param name="name" type="wstring" dir="in">
13309	<desc>Name of the property to get.</desc>
13310	</param>
13311	<param name="value" type="wstring" dir="return">
13312	<desc>Current property value.</desc>
13313	</param>
13314	</method>
13315
13316	<method name="setProperty">
13317	<desc>
13318	Sets the value of the custom medium property with the given name.
13319
13320	The list of all properties supported by the given medium format can
13321	be obtained with <link to="IMediumFormat::describeProperties"/>.
13322
13323	<note>Setting the property value to @c null or an empty string is
13324	equivalent to deleting the existing value. A default value (if it is
13325	defined for this property) will be used by the format backend in this
13326	case.</note>
13327
13328	<result name="VBOX_E_OBJECT_NOT_FOUND">
13329	Requested property does not exist (not supported by the format).
13330	</result>
13331	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13332	</desc>
13333	<param name="name" type="wstring" dir="in">
13334	<desc>Name of the property to set.</desc>
13335	</param>
13336	<param name="value" type="wstring" dir="in">
13337	<desc>Property value to set.</desc>
13338	</param>
13339	</method>
13340
13341	<method name="getProperties" const="yes">
13342	<desc>
13343	Returns values for a group of properties in one call.
13344
13345	The names of the properties to get are specified using the @a names
13346	argument which is a list of comma-separated property names or
13347	an empty string if all properties are to be returned.
13348	<note>Currently the value of this argument is ignored and the method
13349	always returns all existing properties.</note>
13350
13351	The list of all properties supported by the given medium format can
13352	be obtained with <link to="IMediumFormat::describeProperties"/>.
13353
13354	The method returns two arrays, the array of property names corresponding
13355	to the @a names argument and the current values of these properties.
13356	Both arrays have the same number of elements with each element at the
13357	given index in the first array corresponds to an element at the same
13358	index in the second array.
13359
13360	For properties that do not have assigned values, an empty string is
13361	returned at the appropriate index in the @a returnValues array.
13362
13363	</desc>
13364	<param name="names" type="wstring" dir="in">
13365	<desc>
13366	Names of properties to get.
13367	</desc>
13368	</param>
13369	<param name="returnNames" type="wstring" safearray="yes" dir="out">
13370	<desc>Names of returned properties.</desc>
13371	</param>
13372	<param name="returnValues" type="wstring" safearray="yes" dir="return">
13373	<desc>Values of returned properties.</desc>
13374	</param>
13375	</method>
13376
13377	<method name="setProperties">
13378	<desc>
13379	Sets values for a group of properties in one call.
13380
13381	The names of the properties to set are passed in the @a names
13382	array along with the new values for them in the @a values array. Both
13383	arrays have the same number of elements with each element at the given
13384	index in the first array corresponding to an element at the same index
13385	in the second array.
13386
13387	If there is at least one property name in @a names that is not valid,
13388	the method will fail before changing the values of any other properties
13389	from the @a names array.
13390
13391	Using this method over <link to="#setProperty"/> is preferred if you
13392	need to set several properties at once since it is more efficient.
13393
13394	The list of all properties supported by the given medium format can
13395	be obtained with <link to="IMediumFormat::describeProperties"/>.
13396
13397	Setting the property value to @c null or an empty string is equivalent
13398	to deleting the existing value. A default value (if it is defined for
13399	this property) will be used by the format backend in this case.
13400	</desc>
13401	<param name="names" type="wstring" safearray="yes" dir="in">
13402	<desc>Names of properties to set.</desc>
13403	</param>
13404	<param name="values" type="wstring" safearray="yes" dir="in">
13405	<desc>Values of properties to set.</desc>
13406	</param>
13407	</method>
13408
13409	<!-- storage methods -->
13410
13411	<method name="createBaseStorage">
13412	<desc>
13413	Starts creating a hard disk storage unit (fixed/dynamic, according
13414	to the variant flags) in in the background. The previous storage unit
13415	created for this object, if any, must first be deleted using
13416	<link to="#deleteStorage"/>, otherwise the operation will fail.
13417
13418	Before the operation starts, the medium is placed in
13419	<link to="MediumState_Creating"/> state. If the create operation
13420	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
13421	state.
13422
13423	After the returned progress object reports that the operation has
13424	successfully completed, the medium state will be set to <link
13425	to="MediumState_Created"/>, the medium will be remembered by this
13426	VirtualBox installation and may be attached to virtual machines.
13427
13428	<result name="VBOX_E_NOT_SUPPORTED">
13429	The variant of storage creation operation is not supported. See <link
13430	to="IMediumFormat::capabilities"/>.
13431	</result>
13432	</desc>
13433	<param name="logicalSize" type="long long" dir="in">
13434	<desc>Maximum logical size of the medium in bytes.</desc>
13435	</param>
13436	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13437	<desc>Exact image variant which should be created (as a combination of
13438	<link to="MediumVariant" /> flags).</desc>
13439	</param>
13440	<param name="progress" type="IProgress" dir="return">
13441	<desc>Progress object to track the operation completion.</desc>
13442	</param>
13443	</method>
13444
13445	<method name="deleteStorage">
13446	<desc>
13447	Starts deleting the storage unit of this medium.
13448
13449	The medium must not be attached to any known virtual machine and must
13450	not have any known child media, otherwise the operation will fail.
13451	It will also fail if there is no storage unit to delete or if deletion
13452	is already in progress, or if the medium is being in use (locked for
13453	read or for write) or inaccessible. Therefore, the only valid state for
13454	this operation to succeed is <link to="MediumState_Created"/>.
13455
13456	Before the operation starts, the medium is placed in
13457	<link to="MediumState_Deleting"/> state and gets removed from the list
13458	of remembered hard disks (media registry). If the delete operation
13459	fails, the medium will be remembered again and placed back to
13460	<link to="MediumState_Created"/> state.
13461
13462	After the returned progress object reports that the operation is
13463	complete, the medium state will be set to
13464	<link to="MediumState_NotCreated"/> and you will be able to use one of
13465	the storage creation methods to create it again.
13466
13467	<see><link to="#close"/></see>
13468
13469	<result name="VBOX_E_OBJECT_IN_USE">
13470	Medium is attached to a virtual machine.
13471	</result>
13472	<result name="VBOX_E_NOT_SUPPORTED">
13473	Storage deletion is not allowed because neither of storage creation
13474	operations are supported. See
13475	<link to="IMediumFormat::capabilities"/>.
13476	</result>
13477
13478	<note>
13479	If the deletion operation fails, it is not guaranteed that the storage
13480	unit still exists. You may check the <link to="IMedium::state"/> value
13481	to answer this question.
13482	</note>
13483	</desc>
13484	<param name="progress" type="IProgress" dir="return">
13485	<desc>Progress object to track the operation completion.</desc>
13486	</param>
13487	</method>
13488
13489	<!-- diff methods -->
13490
13491	<method name="createDiffStorage">
13492	<desc>
13493	Starts creating an empty differencing storage unit based on this
13494	medium in the format and at the location defined by the @a target
13495	argument.
13496
13497	The target medium must be in <link to="MediumState_NotCreated"/>
13498	state (i.e. must not have an existing storage unit). Upon successful
13499	completion, this operation will set the type of the target medium to
13500	<link to="MediumType_Normal"/> and create a storage unit necessary to
13501	represent the differencing medium data in the given format (according
13502	to the storage format of the target object).
13503
13504	After the returned progress object reports that the operation is
13505	successfully complete, the target medium gets remembered by this
13506	VirtualBox installation and may be attached to virtual machines.
13507
13508	<note>
13509	The medium will be set to <link to="MediumState_LockedRead"/>
13510	state for the duration of this operation.
13511	</note>
13512	<result name="VBOX_E_OBJECT_IN_USE">
13513	Medium not in @c NotCreated state.
13514	</result>
13515	</desc>
13516	<param name="target" type="IMedium" dir="in">
13517	<desc>Target medium.</desc>
13518	</param>
13519	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13520	<desc>Exact image variant which should be created (as a combination of
13521	<link to="MediumVariant" /> flags).</desc>
13522	</param>
13523	<param name="progress" type="IProgress" dir="return">
13524	<desc>Progress object to track the operation completion.</desc>
13525	</param>
13526	</method>
13527
13528	<method name="mergeTo">
13529	<desc>
13530	Starts merging the contents of this medium and all intermediate
13531	differencing media in the chain to the given target medium.
13532
13533	The target medium must be either a descendant of this medium or
13534	its ancestor (otherwise this method will immediately return a failure).
13535	It follows that there are two logical directions of the merge operation:
13536	from ancestor to descendant (<i>forward merge</i>) and from descendant to
13537	ancestor (<i>backward merge</i>). Let us consider the following medium
13538	chain:
13539
13540	<pre>Base <- Diff_1 <- Diff_2</pre>
13541
13542	Here, calling this method on the <tt>Base</tt> medium object with
13543	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
13544	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
13545	merge. Note that in both cases the contents of the resulting medium
13546	will be the same, the only difference is the medium object that takes
13547	the result of the merge operation. In case of the forward merge in the
13548	above example, the result will be written to <tt>Diff_2</tt>; in case of
13549	the backward merge, the result will be written to <tt>Base</tt>. In
13550	other words, the result of the operation is always stored in the target
13551	medium.
13552
13553	Upon successful operation completion, the storage units of all media in
13554	the chain between this (source) medium and the target medium, including
13555	the source medium itself, will be automatically deleted and the
13556	relevant medium objects (including this medium) will become
13557	uninitialized. This means that any attempt to call any of
13558	their methods or attributes will fail with the
13559	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
13560	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
13561	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
13562	Note that <tt>Diff_2</tt> in this case will become a base medium
13563	itself since it will no longer be based on any other medium.
13564
13565	Considering the above, all of the following conditions must be met in
13566	order for the merge operation to succeed:
13567	<ul>
13568	<li>
13569	Neither this (source) medium nor any intermediate
13570	differencing medium in the chain between it and the target
13571	medium is attached to any virtual machine.
13572	</li>
13573	<li>
13574	Neither the source medium nor the target medium is an
13575	<link to="MediumType_Immutable"/> medium.
13576	</li>
13577	<li>
13578	The part of the medium tree from the source medium to the
13579	target medium is a linear chain, i.e. all medium in this
13580	chain have exactly one child which is the next medium in this
13581	chain. The only exception from this rule is the target medium in
13582	the forward merge operation; it is allowed to have any number of
13583	child media because the merge operation will not change its
13584	logical contents (as it is seen by the guest OS or by children).
13585	</li>
13586	<li>
13587	None of the involved media are in
13588	<link to="MediumState_LockedRead"/> or
13589	<link to="MediumState_LockedWrite"/> state.
13590	</li>
13591	</ul>
13592
13593	<note>
13594	This (source) medium and all intermediates will be placed to <link
13595	to="MediumState_Deleting"/> state and the target medium will be
13596	placed to <link to="MediumState_LockedWrite"/> state and for the
13597	duration of this operation.
13598	</note>
13599	</desc>
13600	<param name="target" type="IMedium" dir="in">
13601	<desc>Target medium.</desc>
13602	</param>
13603	<param name="progress" type="IProgress" dir="return">
13604	<desc>Progress object to track the operation completion.</desc>
13605	</param>
13606	</method>
13607
13608	<!-- clone method -->
13609
13610	<method name="cloneTo">
13611	<desc>
13612	Starts creating a clone of this medium in the format and at the
13613	location defined by the @a target argument.
13614
13615	The target medium must be either in <link to="MediumState_NotCreated"/>
13616	state (i.e. must not have an existing storage unit) or in
13617	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13618	big enough to hold the data or else the copy will be partial). Upon
13619	successful completion, the cloned medium will contain exactly the
13620	same sector data as the medium being cloned, except that in the
13621	first case a new UUID for the clone will be randomly generated, and in
13622	the second case the UUID will remain unchanged.
13623
13624	The @a parent argument defines which medium will be the parent
13625	of the clone. Passing a @c null reference indicates that the clone will
13626	be a base image, i.e. completely independent. It is possible to specify
13627	an arbitrary medium for this parameter, including the parent of the
13628	medium which is being cloned. Even cloning to a child of the source
13629	medium is possible. Note that when cloning to an existing image, the
13630	@a parent argument is ignored.
13631
13632	After the returned progress object reports that the operation is
13633	successfully complete, the target medium gets remembered by this
13634	VirtualBox installation and may be attached to virtual machines.
13635
13636	<note>
13637	This medium will be placed to <link to="MediumState_LockedRead"/>
13638	state for the duration of this operation.
13639	</note>
13640	<result name="E_NOTIMPL">
13641	The specified cloning variant is not supported at the moment.
13642	</result>
13643	</desc>
13644	<param name="target" type="IMedium" dir="in">
13645	<desc>Target medium.</desc>
13646	</param>
13647	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13648	<desc>Exact image variant which should be created (as a combination of
13649	<link to="MediumVariant" /> flags).</desc>
13650	</param>
13651	<param name="parent" type="IMedium" dir="in">
13652	<desc>Parent of the cloned medium.</desc>
13653	</param>
13654	<param name="progress" type="IProgress" dir="return">
13655	<desc>Progress object to track the operation completion.</desc>
13656	</param>
13657	</method>
13658
13659	<method name="cloneToBase">
13660	<desc>
13661	Starts creating a clone of this medium in the format and at the
13662	location defined by the @a target argument.
13663
13664	The target medium must be either in <link to="MediumState_NotCreated"/>
13665	state (i.e. must not have an existing storage unit) or in
13666	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13667	big enough to hold the data or else the copy will be partial). Upon
13668	successful completion, the cloned medium will contain exactly the
13669	same sector data as the medium being cloned, except that in the
13670	first case a new UUID for the clone will be randomly generated, and in
13671	the second case the UUID will remain unchanged.
13672
13673	The @a parent argument defines which medium will be the parent
13674	of the clone. In this case the clone will be a base image, i.e.
13675	completely independent. It is possible to specify an arbitrary
13676	medium for this parameter, including the parent of the
13677	medium which is being cloned. Even cloning to a child of the source
13678	medium is possible. Note that when cloning to an existing image, the
13679	@a parent argument is ignored.
13680
13681	After the returned progress object reports that the operation is
13682	successfully complete, the target medium gets remembered by this
13683	VirtualBox installation and may be attached to virtual machines.
13684
13685	<note>
13686	This medium will be placed to <link to="MediumState_LockedRead"/>
13687	state for the duration of this operation.
13688	</note>
13689	<result name="E_NOTIMPL">
13690	The specified cloning variant is not supported at the moment.
13691	</result>
13692	</desc>
13693	<param name="target" type="IMedium" dir="in">
13694	<desc>Target medium.</desc>
13695	</param>
13696	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13697	<desc><link to="MediumVariant" /> flags).</desc>
13698	</param>
13699	<param name="progress" type="IProgress" dir="return">
13700	<desc>Progress object to track the operation completion.</desc>
13701	</param>
13702	</method>
13703
13704	<!-- other methods -->
13705
13706	<method name="compact">
13707	<desc>
13708	Starts compacting of this medium. This means that the medium is
13709	transformed into a possibly more compact storage representation.
13710	This potentially creates temporary images, which can require a
13711	substantial amount of additional disk space.
13712
13713	This medium will be placed to <link to="MediumState_LockedWrite"/>
13714	state and all its parent media (if any) will be placed to
13715	<link to="MediumState_LockedRead"/> state for the duration of this
13716	operation.
13717
13718	Please note that the results can be either returned straight away,
13719	or later as the result of the background operation via the object
13720	returned via the @a progress parameter.
13721
13722	<result name="VBOX_E_NOT_SUPPORTED">
13723	Medium format does not support compacting (but potentially
13724	needs it).
13725	</result>
13726	</desc>
13727	<param name="progress" type="IProgress" dir="return">
13728	<desc>Progress object to track the operation completion.</desc>
13729	</param>
13730	</method>
13731
13732	<method name="resize">
13733	<desc>
13734	Starts resizing this medium. This means that the nominal size of the
13735	medium is set to the new value. Both increasing and decreasing the
13736	size is possible, and there are no safety checks, since VirtualBox
13737	does not make any assumptions about the medium contents.
13738
13739	Resizing usually needs additional disk space, and possibly also
13740	some temporary disk space. Note that resize does not create a full
13741	temporary copy of the medium, so the additional disk space requirement
13742	is usually much lower than using the clone operation.
13743
13744	This medium will be placed to <link to="MediumState_LockedWrite"/>
13745	state for the duration of this operation.
13746
13747	Please note that the results can be either returned straight away,
13748	or later as the result of the background operation via the object
13749	returned via the @a progress parameter.
13750
13751	<result name="VBOX_E_NOT_SUPPORTED">
13752	Medium format does not support resizing.
13753	</result>
13754	</desc>
13755	<param name="logicalSize" type="long long" dir="in">
13756	<desc>New nominal capacity of the medium in bytes.</desc>
13757	</param>
13758	<param name="progress" type="IProgress" dir="return">
13759	<desc>Progress object to track the operation completion.</desc>
13760	</param>
13761	</method>
13762
13763	<method name="reset">
13764	<desc>
13765	Starts erasing the contents of this differencing medium.
13766
13767	This operation will reset the differencing medium to its initial
13768	state when it does not contain any sector data and any read operation is
13769	redirected to its parent medium. This automatically gets called
13770	during VM power-up for every medium whose <link to="#autoReset" />
13771	attribute is @c true.
13772
13773	The medium will be write-locked for the duration of this operation (see
13774	<link to="#lockWrite" />).
13775
13776	<result name="VBOX_E_NOT_SUPPORTED">
13777	This is not a differencing medium.
13778	</result>
13779	<result name="VBOX_E_INVALID_OBJECT_STATE">
13780	Medium is not in <link to="MediumState_Created"/> or
13781	<link to="MediumState_Inaccessible"/> state.
13782	</result>
13783	</desc>
13784	<param name="progress" type="IProgress" dir="return">
13785	<desc>Progress object to track the operation completion.</desc>
13786	</param>
13787	</method>
13788
13789	</interface>
13790
13791
13792	<!--
13793	// IMediumFormat
13794	/////////////////////////////////////////////////////////////////////////
13795	-->
13796
13797	<enum
13798	name="DataType"
13799	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
13800	>
13801	<const name="Int32" value="0"/>
13802	<const name="Int8" value="1"/>
13803	<const name="String" value="2"/>
13804	</enum>
13805
13806	<enum
13807	name="DataFlags"
13808	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
13809	>
13810	<const name="None" value="0x00"/>
13811	<const name="Mandatory" value="0x01"/>
13812	<const name="Expert" value="0x02"/>
13813	<const name="Array" value="0x04"/>
13814	<const name="FlagMask" value="0x07"/>
13815	</enum>
13816
13817	<enum
13818	name="MediumFormatCapabilities"
13819	uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
13820	>
13821	<desc>
13822	Medium format capability flags.
13823	</desc>
13824
13825	<const name="Uuid" value="0x01">
13826	<desc>
13827	Supports UUIDs as expected by VirtualBox code.
13828	</desc>
13829	</const>
13830
13831	<const name="CreateFixed" value="0x02">
13832	<desc>
13833	Supports creating fixed size images, allocating all space instantly.
13834	</desc>
13835	</const>
13836
13837	<const name="CreateDynamic" value="0x04">
13838	<desc>
13839	Supports creating dynamically growing images, allocating space on
13840	demand.
13841	</desc>
13842	</const>
13843
13844	<const name="CreateSplit2G" value="0x08">
13845	<desc>
13846	Supports creating images split in chunks of a bit less than 2 GBytes.
13847	</desc>
13848	</const>
13849
13850	<const name="Differencing" value="0x10">
13851	<desc>
13852	Supports being used as a format for differencing media (see <link
13853	to="IMedium::createDiffStorage"/>).
13854	</desc>
13855	</const>
13856
13857	<const name="Asynchronous" value="0x20">
13858	<desc>
13859	Supports asynchronous I/O operations for at least some configurations.
13860	</desc>
13861	</const>
13862
13863	<const name="File" value="0x40">
13864	<desc>
13865	The format backend operates on files (the <link to="IMedium::location"/>
13866	attribute of the medium specifies a file used to store medium
13867	data; for a list of supported file extensions see
13868	<link to="IMediumFormat::describeFileExtensions"/>).
13869	</desc>
13870	</const>
13871
13872	<const name="Properties" value="0x80">
13873	<desc>
13874	The format backend uses the property interface to configure the storage
13875	location and properties (the <link to="IMediumFormat::describeProperties"/>
13876	method is used to get access to properties supported by the given medium format).
13877	</desc>
13878	</const>
13879
13880	<const name="TcpNetworking" value="0x100">
13881	<desc>
13882	The format backend uses the TCP networking interface for network access.
13883	</desc>
13884	</const>
13885
13886	<const name="VFS" value="0x200">
13887	<desc>
13888	The format backend supports virtual filesystem functionality.
13889	</desc>
13890	</const>
13891
13892	<const name="CapabilityMask" value="0x3FF"/>
13893	</enum>
13894
13895	<interface
13896	name="IMediumFormat" extends="$unknown"
13897	uuid="6238e1cf-a17d-4ec1-8172-418bfb22b93a"
13898	wsmap="managed"
13899	>
13900	<desc>
13901	The IMediumFormat interface represents a medium format.
13902
13903	Each medium format has an associated backend which is used to handle
13904	media stored in this format. This interface provides information
13905	about the properties of the associated backend.
13906
13907	Each medium format is identified by a string represented by the
13908	<link to="#id"/> attribute. This string is used in calls like
13909	<link to="IVirtualBox::createHardDisk"/> to specify the desired
13910	format.
13911
13912	The list of all supported medium formats can be obtained using
13913	<link to="ISystemProperties::mediumFormats"/>.
13914
13915	<see><link to="IMedium"/></see>
13916	</desc>
13917
13918	<attribute name="id" type="wstring" readonly="yes">
13919	<desc>
13920	Identifier of this format.
13921
13922	The format identifier is a non-@c null non-empty ASCII string. Note that
13923	this string is case-insensitive. This means that, for example, all of
13924	the following strings:
13925	<pre>
13926	"VDI"
13927	"vdi"
13928	"VdI"</pre>
13929	refer to the same medium format.
13930
13931	This string is used in methods of other interfaces where it is necessary
13932	to specify a medium format, such as
13933	<link to="IVirtualBox::createHardDisk"/>.
13934	</desc>
13935	</attribute>
13936
13937	<attribute name="name" type="wstring" readonly="yes">
13938	<desc>
13939	Human readable description of this format.
13940
13941	Mainly for use in file open dialogs.
13942	</desc>
13943	</attribute>
13944
13945	<attribute name="capabilities" type="MediumFormatCapabilities" safearray="yes" readonly="yes">
13946	<desc>
13947	Capabilities of the format as an array of the flags.
13948
13949	For the meaning of individual capability flags see
13950	<link to="MediumFormatCapabilities"/>.
13951	</desc>
13952	</attribute>
13953
13954	<method name="describeFileExtensions">
13955	<desc>
13956	Returns two arrays describing the supported file extensions.
13957
13958	The first array contains the supported extensions and the seconds one
13959	the type each extension supports. Both have the same size.
13960
13961	Note that some backends do not work on files, so this array may be
13962	empty.
13963
13964	<see><link to="IMediumFormat::capabilities"/></see>
13965	</desc>
13966	<param name="extensions" type="wstring" safearray="yes" dir="out">
13967	<desc>The array of supported extensions.</desc>
13968	</param>
13969	<param name="types" type="DeviceType" safearray="yes" dir="out">
13970	<desc>The array which indicates the device type for every given extension.</desc>
13971	</param>
13972	</method>
13973
13974	<method name="describeProperties" const="yes">
13975	<desc>
13976	Returns several arrays describing the properties supported by this
13977	format.
13978
13979	An element with the given index in each array describes one
13980	property. Thus, the number of elements in each returned array is the
13981	same and corresponds to the number of supported properties.
13982
13983	The returned arrays are filled in only if the
13984	<link to="MediumFormatCapabilities_Properties"/> flag is set.
13985	All arguments must be non-@c null.
13986
13987	<see><link to="DataType"/>, <link to="DataFlags"/></see>
13988	</desc>
13989
13990	<param name="names" type="wstring" safearray="yes" dir="out">
13991	<desc>Array of property names.</desc>
13992	</param>
13993	<param name="descriptions" type="wstring" safearray="yes" dir="out">
13994	<desc>Array of property descriptions.</desc>
13995	</param>
13996	<param name="types" type="DataType" safearray="yes" dir="out">
13997	<desc>Array of property types.</desc>
13998	</param>
13999	<param name="flags" type="unsigned long" safearray="yes" dir="out">
14000	<desc>Array of property flags.</desc>
14001	</param>
14002	<param name="defaults" type="wstring" safearray="yes" dir="out">
14003	<desc>Array of default property values.</desc>
14004	</param>
14005	</method>
14006
14007	</interface>
14008
14009
14010	<!--
14011	// IKeyboard
14012	/////////////////////////////////////////////////////////////////////////
14013	-->
14014
14015	<interface
14016	name="IKeyboard" extends="$unknown"
14017	uuid="f6916ec5-a881-4237-898f-7de58cf88672"
14018	wsmap="managed"
14019	>
14020	<desc>
14021	The IKeyboard interface represents the virtual machine's keyboard. Used
14022	in <link to="IConsole::keyboard"/>.
14023
14024	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
14025	to the virtual machine.
14026
14027	</desc>
14028	<method name="putScancode">
14029	<desc>Sends a scancode to the keyboard.
14030
14031	<result name="VBOX_E_IPRT_ERROR">
14032	Could not send scan code to virtual keyboard.
14033	</result>
14034
14035	</desc>
14036	<param name="scancode" type="long" dir="in"/>
14037	</method>
14038
14039	<method name="putScancodes">
14040	<desc>Sends an array of scancodes to the keyboard.
14041
14042	<result name="VBOX_E_IPRT_ERROR">
14043	Could not send all scan codes to virtual keyboard.
14044	</result>
14045
14046	</desc>
14047	<param name="scancodes" type="long" dir="in" safearray="yes"/>
14048	<param name="codesStored" type="unsigned long" dir="return"/>
14049	</method>
14050
14051	<method name="putCAD">
14052	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
14053	function is nothing special, it is just a convenience function
14054	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
14055
14056	<result name="VBOX_E_IPRT_ERROR">
14057	Could not send all scan codes to virtual keyboard.
14058	</result>
14059
14060	</desc>
14061	</method>
14062
14063	<attribute name="eventSource" type="IEventSource" readonly="yes">
14064	<desc>
14065	Event source for keyboard events.
14066	</desc>
14067	</attribute>
14068
14069	</interface>
14070
14071
14072	<!--
14073	// IMouse
14074	/////////////////////////////////////////////////////////////////////////
14075	-->
14076
14077	<enum
14078	name="MouseButtonState"
14079	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
14080	>
14081	<desc>
14082	Mouse button state.
14083	</desc>
14084
14085	<const name="LeftButton" value="0x01"/>
14086	<const name="RightButton" value="0x02"/>
14087	<const name="MiddleButton" value="0x04"/>
14088	<const name="WheelUp" value="0x08"/>
14089	<const name="WheelDown" value="0x10"/>
14090	<const name="XButton1" value="0x20"/>
14091	<const name="XButton2" value="0x40"/>
14092	<const name="MouseStateMask" value="0x7F"/>
14093	</enum>
14094
14095	<interface
14096	name="IMouse" extends="$unknown"
14097	uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
14098	wsmap="managed"
14099	>
14100	<desc>
14101	The IMouse interface represents the virtual machine's mouse. Used in
14102	<link to="IConsole::mouse"/>.
14103
14104	Through this interface, the virtual machine's virtual mouse can be
14105	controlled.
14106	</desc>
14107
14108	<attribute name="absoluteSupported" type="boolean" readonly="yes">
14109	<desc>
14110	Whether the guest OS supports absolute mouse pointer positioning
14111	or not.
14112	<note>
14113	You can use the <link to="IMouseCapabilityChangedEvent"/>
14114	event to be instantly informed about changes of this attribute
14115	during virtual machine execution.
14116	</note>
14117	<see><link to="#putMouseEventAbsolute"/></see>
14118	</desc>
14119	</attribute>
14120
14121	<attribute name="relativeSupported" type="boolean" readonly="yes">
14122	<desc>
14123	Whether the guest OS supports relative mouse pointer positioning
14124	or not.
14125	<note>
14126	You can use the <link to="IMouseCapabilityChangedEvent"/>
14127	event to be instantly informed about changes of this attribute
14128	during virtual machine execution.
14129	</note>
14130	<see><link to="#putMouseEvent"/></see>
14131	</desc>
14132	</attribute>
14133
14134	<attribute name="needsHostCursor" type="boolean" readonly="yes">
14135	<desc>
14136	Whether the guest OS can currently switch to drawing it's own mouse
14137	cursor on demand.
14138	<note>
14139	You can use the <link to="IMouseCapabilityChangedEvent"/>
14140	event to be instantly informed about changes of this attribute
14141	during virtual machine execution.
14142	</note>
14143	<see><link to="#putMouseEvent"/></see>
14144	</desc>
14145	</attribute>
14146
14147	<method name="putMouseEvent">
14148	<desc>
14149	Initiates a mouse event using relative pointer movements
14150	along x and y axis.
14151
14152	<result name="E_ACCESSDENIED">
14153	Console not powered up.
14154	</result>
14155	<result name="VBOX_E_IPRT_ERROR">
14156	Could not send mouse event to virtual mouse.
14157	</result>
14158
14159	</desc>
14160
14161	<param name="dx" type="long" dir="in">
14162	<desc>
14163	Amount of pixels the mouse should move to the right.
14164	Negative values move the mouse to the left.
14165	</desc>
14166	</param>
14167	<param name="dy" type="long" dir="in">
14168	<desc>
14169	Amount of pixels the mouse should move downwards.
14170	Negative values move the mouse upwards.
14171	</desc>
14172	</param>
14173	<param name="dz" type="long" dir="in">
14174	<desc>
14175	Amount of mouse wheel moves.
14176	Positive values describe clockwise wheel rotations,
14177	negative values describe counterclockwise rotations.
14178	</desc>
14179	</param>
14180	<param name="dw" type="long" dir="in">
14181	<desc>
14182	Amount of horizontal mouse wheel moves.
14183	Positive values describe a movement to the left,
14184	negative values describe a movement to the right.
14185	</desc>
14186	</param>
14187	<param name="buttonState" type="long" dir="in">
14188	<desc>
14189	The current state of mouse buttons. Every bit represents
14190	a mouse button as follows:
14191	<table>
14192	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14193	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14194	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14195	</table>
14196	A value of <tt>1</tt> means the corresponding button is pressed.
14197	otherwise it is released.
14198	</desc>
14199	</param>
14200	</method>
14201
14202	<method name="putMouseEventAbsolute">
14203	<desc>
14204	Positions the mouse pointer using absolute x and y coordinates.
14205	These coordinates are expressed in pixels and
14206	start from <tt>[1,1]</tt> which corresponds to the top left
14207	corner of the virtual display.
14208
14209	<result name="E_ACCESSDENIED">
14210	Console not powered up.
14211	</result>
14212	<result name="VBOX_E_IPRT_ERROR">
14213	Could not send mouse event to virtual mouse.
14214	</result>
14215
14216	<note>
14217	This method will have effect only if absolute mouse
14218	positioning is supported by the guest OS.
14219	</note>
14220
14221	<see><link to="#absoluteSupported"/></see>
14222	</desc>
14223
14224	<param name="x" type="long" dir="in">
14225	<desc>
14226	X coordinate of the pointer in pixels, starting from @c 1.
14227	</desc>
14228	</param>
14229	<param name="y" type="long" dir="in">
14230	<desc>
14231	Y coordinate of the pointer in pixels, starting from @c 1.
14232	</desc>
14233	</param>
14234	<param name="dz" type="long" dir="in">
14235	<desc>
14236	Amount of mouse wheel moves.
14237	Positive values describe clockwise wheel rotations,
14238	negative values describe counterclockwise rotations.
14239	</desc>
14240	</param>
14241	<param name="dw" type="long" dir="in">
14242	<desc>
14243	Amount of horizontal mouse wheel moves.
14244	Positive values describe a movement to the left,
14245	negative values describe a movement to the right.
14246	</desc>
14247	</param>
14248	<param name="buttonState" type="long" dir="in">
14249	<desc>
14250	The current state of mouse buttons. Every bit represents
14251	a mouse button as follows:
14252	<table>
14253	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14254	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14255	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14256	</table>
14257	A value of @c 1 means the corresponding button is pressed.
14258	otherwise it is released.
14259	</desc>
14260	</param>
14261	</method>
14262
14263	<attribute name="eventSource" type="IEventSource" readonly="yes">
14264	<desc>
14265	Event source for mouse events.
14266	</desc>
14267	</attribute>
14268
14269	</interface>
14270
14271	<!--
14272	// IDisplay
14273	/////////////////////////////////////////////////////////////////////////
14274	-->
14275
14276	<enum
14277	name="FramebufferPixelFormat"
14278	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
14279	>
14280	<desc>
14281	Format of the video memory buffer. Constants represented by this enum can
14282	be used to test for particular values of <link
14283	to="IFramebuffer::pixelFormat"/>. See also <link
14284	to="IFramebuffer::requestResize"/>.
14285
14286	See also www.fourcc.org for more information about FOURCC pixel formats.
14287	</desc>
14288
14289	<const name="Opaque" value="0">
14290	<desc>
14291	Unknown buffer format (the user may not assume any particular format of
14292	the buffer).
14293	</desc>
14294	</const>
14295	<const name="FOURCC_RGB" value="0x32424752">
14296	<desc>
14297	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
14298	bit layout).
14299	</desc>
14300	</const>
14301	</enum>
14302
14303	<interface
14304	name="IFramebuffer" extends="$unknown"
14305	uuid="e3f122c0-adab-4fc9-a8dc-da112fb48428"
14306	wsmap="suppress"
14307	>
14308	<attribute name="address" type="octet" mod="ptr" readonly="yes">
14309	<desc>Address of the start byte of the frame buffer.</desc>
14310	</attribute>
14311
14312	<attribute name="width" type="unsigned long" readonly="yes">
14313	<desc>Frame buffer width, in pixels.</desc>
14314	</attribute>
14315
14316	<attribute name="height" type="unsigned long" readonly="yes">
14317	<desc>Frame buffer height, in pixels.</desc>
14318	</attribute>
14319
14320	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
14321	<desc>
14322	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
14323	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
14324	are: 8, 15, 16, 24 and 32.
14325	</desc>
14326	</attribute>
14327
14328	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
14329	<desc>
14330	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
14331	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
14332	size of the scan line must be aligned to 32 bits.
14333	</desc>
14334	</attribute>
14335
14336	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
14337	<desc>
14338	Frame buffer pixel format. It's either one of the values defined by <link
14339	to="FramebufferPixelFormat"/> or a raw FOURCC code.
14340	<note>
14341	This attribute must never return <link
14342	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
14343	<link to="#address"/> points to must be always known.
14344	</note>
14345	</desc>
14346	</attribute>
14347
14348	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
14349	<desc>
14350	Defines whether this frame buffer uses the virtual video card's memory
14351	buffer (guest VRAM) directly or not. See <link
14352	to="IFramebuffer::requestResize"/> for more information.
14353	</desc>
14354	</attribute>
14355
14356	<attribute name="heightReduction" type="unsigned long" readonly="yes">
14357	<desc>
14358	Hint from the frame buffer about how much of the standard
14359	screen height it wants to use for itself. This information is
14360	exposed to the guest through the VESA BIOS and VMMDev interface
14361	so that it can use it for determining its video mode table. It
14362	is not guaranteed that the guest respects the value.
14363	</desc>
14364	</attribute>
14365
14366	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
14367	<desc>
14368	An alpha-blended overlay which is superposed over the frame buffer.
14369	The initial purpose is to allow the display of icons providing
14370	information about the VM state, including disk activity, in front
14371	ends which do not have other means of doing that. The overlay is
14372	designed to controlled exclusively by IDisplay. It has no locking
14373	of its own, and any changes made to it are not guaranteed to be
14374	visible until the affected portion of IFramebuffer is updated. The
14375	overlay can be created lazily the first time it is requested. This
14376	attribute can also return @c null to signal that the overlay is not
14377	implemented.
14378	</desc>
14379	</attribute>
14380
14381	<attribute name="winId" type="long long" readonly="yes">
14382	<desc>
14383	Platform-dependent identifier of the window where context of this
14384	frame buffer is drawn, or zero if there's no such window.
14385	</desc>
14386	</attribute>
14387
14388	<method name="lock">
14389	<desc>
14390	Locks the frame buffer.
14391	Gets called by the IDisplay object where this frame buffer is
14392	bound to.
14393	</desc>
14394	</method>
14395
14396	<method name="unlock">
14397	<desc>
14398	Unlocks the frame buffer.
14399	Gets called by the IDisplay object where this frame buffer is
14400	bound to.
14401	</desc>
14402	</method>
14403
14404	<method name="notifyUpdate">
14405	<desc>
14406	Informs about an update.
14407	Gets called by the display object where this buffer is
14408	registered.
14409	</desc>
14410	<param name="x" type="unsigned long" dir="in"/>
14411	<param name="y" type="unsigned long" dir="in"/>
14412	<param name="width" type="unsigned long" dir="in"/>
14413	<param name="height" type="unsigned long" dir="in"/>
14414	</method>
14415
14416	<method name="requestResize">
14417	<desc>
14418	Requests a size and pixel format change.
14419
14420	There are two modes of working with the video buffer of the virtual
14421	machine. The <i>indirect</i> mode implies that the IFramebuffer
14422	implementation allocates a memory buffer for the requested display mode
14423	and provides it to the virtual machine. In <i>direct</i> mode, the
14424	IFramebuffer implementation uses the memory buffer allocated and owned
14425	by the virtual machine. This buffer represents the video memory of the
14426	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
14427	usually faster because the implementation gets a raw pointer to the
14428	guest VRAM buffer which it can directly use for visualizing the contents
14429	of the virtual display, as opposed to the indirect mode where the
14430	contents of guest VRAM are copied to the memory buffer provided by
14431	the implementation every time a display update occurs.
14432
14433	It is important to note that the direct mode is really fast only when
14434	the implementation uses the given guest VRAM buffer directly, for
14435	example, by blitting it to the window representing the virtual machine's
14436	display, which saves at least one copy operation comparing to the
14437	indirect mode. However, using the guest VRAM buffer directly is not
14438	always possible: the format and the color depth of this buffer may be
14439	not supported by the target window, or it may be unknown (opaque) as in
14440	case of text or non-linear multi-plane VGA video modes. In this case,
14441	the indirect mode (that is always available) should be used as a
14442	fallback: when the guest VRAM contents are copied to the
14443	implementation-provided memory buffer, color and format conversion is
14444	done automatically by the underlying code.
14445
14446	The @a pixelFormat parameter defines whether the direct mode is
14447	available or not. If @a pixelFormat is <link
14448	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
14449	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
14450	@a bytesPerLine parameters must be ignored and the implementation must use
14451	the indirect mode (where it provides its own buffer in one of the
14452	supported formats). In all other cases, @a pixelFormat together with
14453	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
14454	buffer pointed to by the @a VRAM parameter and the implementation is
14455	free to choose which mode to use. To indicate that this frame buffer uses
14456	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
14457	attribute must return @c true and <link to="#address"/> must
14458	return exactly the same address that is passed in the @a VRAM parameter
14459	of this method; otherwise it is assumed that the indirect strategy is
14460	chosen.
14461
14462	The @a width and @a height parameters represent the size of the
14463	requested display mode in both modes. In case of indirect mode, the
14464	provided memory buffer should be big enough to store data of the given
14465	display mode. In case of direct mode, it is guaranteed that the given
14466	@a VRAM buffer contains enough space to represent the display mode of the
14467	given size. Note that this frame buffer's <link to="#width"/> and <link
14468	to="#height"/> attributes must return exactly the same values as
14469	passed to this method after the resize is completed (see below).
14470
14471	The @a finished output parameter determines if the implementation has
14472	finished resizing the frame buffer or not. If, for some reason, the
14473	resize cannot be finished immediately during this call, @a finished
14474	must be set to @c false, and the implementation must call
14475	<link to="IDisplay::resizeCompleted"/> after it has returned from
14476	this method as soon as possible. If @a finished is @c false, the
14477	machine will not call any frame buffer methods until
14478	<link to="IDisplay::resizeCompleted"/> is called.
14479
14480	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
14481	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
14482	this frame buffer must return exactly the same values as specified in the
14483	parameters of this method, after the resize is completed. If the
14484	indirect mode is chosen, these attributes must return values describing
14485	the format of the implementation's own memory buffer <link
14486	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
14487	value must always correlate with <link to="#pixelFormat"/>. Note that
14488	the <link to="#pixelFormat"/> attribute must never return <link
14489	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
14490
14491	<note>
14492	This method is called by the IDisplay object under the
14493	<link to="#lock"/> provided by this IFramebuffer
14494	implementation. If this method returns @c false in @a finished, then
14495	this lock is not released until
14496	<link to="IDisplay::resizeCompleted"/> is called.
14497	</note>
14498	</desc>
14499	<param name="screenId" type="unsigned long" dir="in">
14500	<desc>
14501	Logical screen number. Must be used in the corresponding call to
14502	<link to="IDisplay::resizeCompleted"/> if this call is made.
14503	</desc>
14504	</param>
14505	<param name="pixelFormat" type="unsigned long" dir="in">
14506	<desc>
14507	Pixel format of the memory buffer pointed to by @a VRAM.
14508	See also <link to="FramebufferPixelFormat"/>.
14509	</desc>
14510	</param>
14511	<param name="VRAM" type="octet" mod="ptr" dir="in">
14512	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
14513	</param>
14514	<param name="bitsPerPixel" type="unsigned long" dir="in">
14515	<desc>Color depth, bits per pixel.</desc>
14516	</param>
14517	<param name="bytesPerLine" type="unsigned long" dir="in">
14518	<desc>Size of one scan line, in bytes.</desc>
14519	</param>
14520	<param name="width" type="unsigned long" dir="in">
14521	<desc>Width of the guest display, in pixels.</desc>
14522	</param>
14523	<param name="height" type="unsigned long" dir="in">
14524	<desc>Height of the guest display, in pixels.</desc>
14525	</param>
14526	<param name="finished" type="boolean" dir="return">
14527	<desc>
14528	Can the VM start using the new frame buffer immediately
14529	after this method returns or it should wait for
14530	<link to="IDisplay::resizeCompleted"/>.
14531	</desc>
14532	</param>
14533	</method>
14534
14535	<method name="videoModeSupported">
14536	<desc>
14537	Returns whether the frame buffer implementation is willing to
14538	support a given video mode. In case it is not able to render
14539	the video mode (or for some reason not willing), it should
14540	return @c false. Usually this method is called when the guest
14541	asks the VMM device whether a given video mode is supported
14542	so the information returned is directly exposed to the guest.
14543	It is important that this method returns very quickly.
14544	</desc>
14545	<param name="width" type="unsigned long" dir="in"/>
14546	<param name="height" type="unsigned long" dir="in"/>
14547	<param name="bpp" type="unsigned long" dir="in"/>
14548	<param name="supported" type="boolean" dir="return"/>
14549	</method>
14550
14551	<method name="getVisibleRegion">
14552	<desc>
14553	Returns the visible region of this frame buffer.
14554
14555	If the @a rectangles parameter is @c null then the value of the
14556	@a count parameter is ignored and the number of elements necessary to
14557	describe the current visible region is returned in @a countCopied.
14558
14559	If @a rectangles is not @c null but @a count is less
14560	than the required number of elements to store region data, the method
14561	will report a failure. If @a count is equal or greater than the
14562	required number of elements, then the actual number of elements copied
14563	to the provided array will be returned in @a countCopied.
14564
14565	<note>
14566	The address of the provided array must be in the process space of
14567	this IFramebuffer object.
14568	</note>
14569	<note>
14570	Method not yet implemented.
14571	</note>
14572	</desc>
14573	<param name="rectangles" type="octet" mod="ptr" dir="in">
14574	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
14575	</param>
14576	<param name="count" type="unsigned long" dir="in">
14577	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14578	</param>
14579	<param name="countCopied" type="unsigned long" dir="return">
14580	<desc>Number of elements copied to the @a rectangles array.</desc>
14581	</param>
14582	</method>
14583
14584	<method name="setVisibleRegion">
14585	<desc>
14586	Suggests a new visible region to this frame buffer. This region
14587	represents the area of the VM display which is a union of regions of
14588	all top-level windows of the guest operating system running inside the
14589	VM (if the Guest Additions for this system support this
14590	functionality). This information may be used by the frontends to
14591	implement the seamless desktop integration feature.
14592
14593	<note>
14594	The address of the provided array must be in the process space of
14595	this IFramebuffer object.
14596	</note>
14597	<note>
14598	The IFramebuffer implementation must make a copy of the provided
14599	array of rectangles.
14600	</note>
14601	<note>
14602	Method not yet implemented.
14603	</note>
14604	</desc>
14605	<param name="rectangles" type="octet" mod="ptr" dir="in">
14606	<desc>Pointer to the @c RTRECT array.</desc>
14607	</param>
14608	<param name="count" type="unsigned long" dir="in">
14609	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14610	</param>
14611	</method>
14612
14613	<method name="processVHWACommand">
14614	<desc>
14615	Posts a Video HW Acceleration Command to the frame buffer for processing.
14616	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
14617	are posted from quest to the host to be processed by the host hardware.
14618
14619	<note>
14620	The address of the provided command must be in the process space of
14621	this IFramebuffer object.
14622	</note>
14623	</desc>
14624
14625	<param name="command" type="octet" mod="ptr" dir="in">
14626	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
14627	</param>
14628	</method>
14629
14630	<method name="notify3DEvent">
14631	<desc>
14632	Notifies framebuffer about 3D backend event.
14633	</desc>
14634
14635	<param name="type" type="unsigned long" dir="in">
14636	<desc>event type. Currently only VBOX3D_NOTIFY_EVENT_TYPE_VISIBLE_WINDOW is supported.</desc>
14637	</param>
14638	<param name="reserved" type="octet" mod="ptr" dir="in">
14639	<desc>Reserved for future use, must be NULL.</desc>
14640	</param>
14641	</method>
14642
14643	</interface>
14644
14645	<interface
14646	name="IFramebufferOverlay" extends="IFramebuffer"
14647	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
14648	wsmap="suppress"
14649	>
14650	<desc>
14651	The IFramebufferOverlay interface represents an alpha blended overlay
14652	for displaying status icons above an IFramebuffer. It is always created
14653	not visible, so that it must be explicitly shown. It only covers a
14654	portion of the IFramebuffer, determined by its width, height and
14655	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
14656	that order) format, and may be written to directly. Do re-read the
14657	width though, after setting it, as it may be adjusted (increased) to
14658	make it more suitable for the front end.
14659	</desc>
14660	<attribute name="x" type="unsigned long" readonly="yes">
14661	<desc>X position of the overlay, relative to the frame buffer.</desc>
14662	</attribute>
14663
14664	<attribute name="y" type="unsigned long" readonly="yes">
14665	<desc>Y position of the overlay, relative to the frame buffer.</desc>
14666	</attribute>
14667
14668	<attribute name="visible" type="boolean">
14669	<desc>
14670	Whether the overlay is currently visible.
14671	</desc>
14672	</attribute>
14673
14674	<attribute name="alpha" type="unsigned long">
14675	<desc>
14676	The global alpha value for the overlay. This may or may not be
14677	supported by a given front end.
14678	</desc>
14679	</attribute>
14680
14681	<method name="move">
14682	<desc>
14683	Changes the overlay's position relative to the IFramebuffer.
14684	</desc>
14685	<param name="x" type="unsigned long" dir="in"/>
14686	<param name="y" type="unsigned long" dir="in"/>
14687	</method>
14688
14689	</interface>
14690
14691	<interface
14692	name="IDisplay" extends="$unknown"
14693	uuid="0598a3df-3dc0-43c7-a79c-237fb5bb633d"
14694	wsmap="managed"
14695	>
14696	<desc>
14697	The IDisplay interface represents the virtual machine's display.
14698
14699	The object implementing this interface is contained in each
14700	<link to="IConsole::display"/> attribute and represents the visual
14701	output of the virtual machine.
14702
14703	The virtual display supports pluggable output targets represented by the
14704	IFramebuffer interface. Examples of the output target are a window on
14705	the host computer or an RDP session's display on a remote computer.
14706	</desc>
14707	<method name="getScreenResolution">
14708	<desc>Queries display width, height and color depth for given screen.</desc>
14709	<param name="screenId" type="unsigned long" dir="in"/>
14710	<param name="width" type="unsigned long" dir="out"/>
14711	<param name="height" type="unsigned long" dir="out"/>
14712	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
14713	</method>
14714
14715	<method name="setFramebuffer">
14716	<desc>
14717	Sets the framebuffer for given screen.
14718	</desc>
14719	<param name="screenId" type="unsigned long" dir="in"/>
14720	<param name="framebuffer" type="IFramebuffer" dir="in"/>
14721	</method>
14722
14723	<method name="getFramebuffer">
14724	<desc>
14725	Queries the framebuffer for given screen.
14726	</desc>
14727	<param name="screenId" type="unsigned long" dir="in"/>
14728	<param name="framebuffer" type="IFramebuffer" dir="out"/>
14729	<param name="xOrigin" type="long" dir="out"/>
14730	<param name="yOrigin" type="long" dir="out"/>
14731	</method>
14732
14733	<method name="setVideoModeHint">
14734	<desc>
14735	Asks VirtualBox to request the given video mode from
14736	the guest. This is just a hint and it cannot be guaranteed
14737	that the requested resolution will be used. Guest Additions
14738	are required for the request to be seen by guests. The caller
14739	should issue the request and wait for a resolution change and
14740	after a timeout retry.
14741
14742	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
14743	parameters means that the corresponding values should be taken from the
14744	current video mode (i.e. left unchanged).
14745
14746	If the guest OS supports multi-monitor configuration then the @a display
14747	parameter specifies the number of the guest display to send the hint to:
14748	@c 0 is the primary display, @c 1 is the first secondary and
14749	so on. If the multi-monitor configuration is not supported, @a display
14750	must be @c 0.
14751
14752	<result name="E_INVALIDARG">
14753	The @a display is not associated with any monitor.
14754	</result>
14755
14756	</desc>
14757	<param name="display" type="unsigned long" dir="in">
14758	<desc>
14759	The number of the guest display to send the hint to.
14760	</desc>
14761	</param>
14762	<param name="enabled" type="boolean" dir="in">
14763	<desc>
14764	@c True, if this guest screen is enabled,
14765	@c False otherwise.
14766	</desc>
14767	</param>
14768	<param name="changeOrigin" type="boolean" dir="in">
14769	<desc>
14770	@c True, if the origin of the guest screen should be changed,
14771	@c False otherwise.
14772	</desc>
14773	</param>
14774	<param name="originX" type="long" dir="in">
14775	<desc>
14776	The X origin of the guest screen.
14777	</desc>
14778	</param>
14779	<param name="originY" type="long" dir="in">
14780	<desc>
14781	The Y origin of the guest screen.
14782	</desc>
14783	</param>
14784	<param name="width" type="unsigned long" dir="in"/>
14785	<param name="height" type="unsigned long" dir="in"/>
14786	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
14787	</method>
14788
14789	<method name="setSeamlessMode">
14790	<desc>
14791	Enables or disables seamless guest display rendering (seamless desktop
14792	integration) mode.
14793	<note>
14794	Calling this method has no effect if <link
14795	to="IGuest::getFacilityStatus"/> with facility @c Seamless
14796	does not return @c Active.
14797	</note>
14798	</desc>
14799	<param name="enabled" type="boolean" dir="in"/>
14800	</method>
14801
14802	<method name="takeScreenShot">
14803	<desc>
14804	Takes a screen shot of the requested size and copies it to the
14805	32-bpp buffer allocated by the caller and pointed to by @a address.
14806	A pixel consists of 4 bytes in order: B, G, R, 0.
14807
14808	<note>This API can be used only locally by a VM process through the
14809	COM/XPCOM C++ API as it requires pointer support. It is not
14810	available for scripting langages, Java or any webservice clients.
14811	Unless you are writing a new VM frontend use
14812	<link to="#takeScreenShotToArray" />.
14813	</note>
14814
14815	<result name="E_NOTIMPL">
14816	Feature not implemented.
14817	</result>
14818	<result name="VBOX_E_IPRT_ERROR">
14819	Could not take a screenshot.
14820	</result>
14821
14822	</desc>
14823	<param name="screenId" type="unsigned long" dir="in"/>
14824	<param name="address" type="octet" mod="ptr" dir="in"/>
14825	<param name="width" type="unsigned long" dir="in"/>
14826	<param name="height" type="unsigned long" dir="in"/>
14827	</method>
14828
14829	<method name="takeScreenShotToArray">
14830	<desc>
14831	Takes a guest screen shot of the requested size and returns it as
14832	an array of bytes in uncompressed 32-bpp RGBA format.
14833	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
14834
14835	This API is slow, but could be the only option to get guest screenshot
14836	for scriptable languages not allowed to manipulate with addresses
14837	directly.
14838
14839	<result name="E_NOTIMPL">
14840	Feature not implemented.
14841	</result>
14842	<result name="VBOX_E_IPRT_ERROR">
14843	Could not take a screenshot.
14844	</result>
14845	</desc>
14846	<param name="screenId" type="unsigned long" dir="in">
14847	<desc>
14848	Monitor to take screenshot from.
14849	</desc>
14850	</param>
14851	<param name="width" type="unsigned long" dir="in">
14852	<desc>
14853	Desired image width.
14854	</desc>
14855	</param>
14856	<param name="height" type="unsigned long" dir="in">
14857	<desc>
14858	Desired image height.
14859	</desc>
14860	</param>
14861	<param name="screenData" type="octet" dir="return" safearray="yes">
14862	<desc>
14863	Array with resulting screen data.
14864	</desc>
14865	</param>
14866	</method>
14867
14868	<method name="takeScreenShotPNGToArray">
14869	<desc>
14870	Takes a guest screen shot of the requested size and returns it as
14871	PNG image in array.
14872
14873	<result name="E_NOTIMPL">
14874	Feature not implemented.
14875	</result>
14876	<result name="VBOX_E_IPRT_ERROR">
14877	Could not take a screenshot.
14878	</result>
14879	</desc>
14880	<param name="screenId" type="unsigned long" dir="in">
14881	<desc>
14882	Monitor to take the screenshot from.
14883	</desc>
14884	</param>
14885	<param name="width" type="unsigned long" dir="in">
14886	<desc>
14887	Desired image width.
14888	</desc>
14889	</param>
14890	<param name="height" type="unsigned long" dir="in">
14891	<desc>
14892	Desired image height.
14893	</desc>
14894	</param>
14895	<param name="screenData" type="octet" dir="return" safearray="yes">
14896	<desc>
14897	Array with resulting screen data.
14898	</desc>
14899	</param>
14900	</method>
14901
14902	<method name="enableVideoCaptureScreens">
14903	<desc>
14904	Start/stop video capture on selected screens.
14905	</desc>
14906	<param name="screens" type="boolean" safearray="yes" dir="in">
14907	<desc>
14908	The screens to start/stop capturing.
14909	</desc>
14910	</param>
14911	</method>
14912
14913	<method name="drawToScreen">
14914	<desc>
14915	Draws a 32-bpp image of the specified size from the given buffer
14916	to the given point on the VM display.
14917
14918	<result name="E_NOTIMPL">
14919	Feature not implemented.
14920	</result>
14921	<result name="VBOX_E_IPRT_ERROR">
14922	Could not draw to screen.
14923	</result>
14924
14925	</desc>
14926	<param name="screenId" type="unsigned long" dir="in">
14927	<desc>
14928	Monitor to take the screenshot from.
14929	</desc>
14930	</param>
14931	<param name="address" type="octet" mod="ptr" dir="in">
14932	<desc>
14933	Address to store the screenshot to
14934	</desc>
14935	</param>
14936	<param name="x" type="unsigned long" dir="in">
14937	<desc>
14938	Relative to the screen top left corner.
14939	</desc>
14940	</param>
14941	<param name="y" type="unsigned long" dir="in">
14942	<desc>
14943	Relative to the screen top left corner.
14944	</desc>
14945	</param>
14946	<param name="width" type="unsigned long" dir="in">
14947	<desc>
14948	Desired image width.
14949	</desc>
14950	</param>
14951	<param name="height" type="unsigned long" dir="in">
14952	<desc>
14953	Desired image height.
14954	</desc>
14955	</param>
14956	</method>
14957
14958	<method name="invalidateAndUpdate">
14959	<desc>
14960	Does a full invalidation of the VM display and instructs the VM
14961	to update it.
14962
14963	<result name="VBOX_E_IPRT_ERROR">
14964	Could not invalidate and update screen.
14965	</result>
14966
14967	</desc>
14968	</method>
14969
14970	<method name="resizeCompleted">
14971	<desc>
14972	Signals that a framebuffer has completed the resize operation.
14973
14974	<result name="VBOX_E_NOT_SUPPORTED">
14975	Operation only valid for external frame buffers.
14976	</result>
14977
14978	</desc>
14979	<param name="screenId" type="unsigned long" dir="in"/>
14980	</method>
14981
14982	<method name="completeVHWACommand">
14983	<desc>
14984	Signals that the Video HW Acceleration command has completed.
14985	</desc>
14986
14987	<param name="command" type="octet" mod="ptr" dir="in">
14988	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
14989	</param>
14990	</method>
14991
14992	<method name="viewportChanged">
14993	<desc>
14994	Signals that framebuffer window viewport has changed.
14995
14996	<result name="E_INVALIDARG">
14997	The specified viewport data is invalid.
14998	</result>
14999
15000	</desc>
15001
15002	<param name="screenId" type="unsigned long" dir="in">
15003	<desc>
15004	Monitor to take the screenshot from.
15005	</desc>
15006	</param>
15007	<param name="x" type="unsigned long" dir="in">
15008	<desc>
15009	Framebuffer x offset.
15010	</desc>
15011	</param>
15012	<param name="y" type="unsigned long" dir="in">
15013	<desc>
15014	Framebuffer y offset.
15015	</desc>
15016	</param>
15017	<param name="width" type="unsigned long" dir="in">
15018	<desc>
15019	Viewport width.
15020	</desc>
15021	</param>
15022	<param name="height" type="unsigned long" dir="in">
15023	<desc>
15024	Viewport height.
15025	</desc>
15026	</param>
15027	</method>
15028	</interface>
15029
15030	<!--
15031	// INetworkAdapter
15032	/////////////////////////////////////////////////////////////////////////
15033	-->
15034
15035	<enum
15036	name="NetworkAttachmentType"
15037	uuid="2ac4bc71-6b82-417a-acd1-f7426d2570d6"
15038	>
15039	<desc>
15040	Network attachment type.
15041	</desc>
15042
15043	<const name="Null" value="0">
15044	<desc>Null value, also means "not attached".</desc>
15045	</const>
15046	<const name="NAT" value="1"/>
15047	<const name="Bridged" value="2"/>
15048	<const name="Internal" value="3"/>
15049	<const name="HostOnly" value="4"/>
15050	<const name="Generic" value="5"/>
15051	</enum>
15052
15053	<enum
15054	name="NetworkAdapterType"
15055	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
15056	>
15057	<desc>
15058	Network adapter type.
15059	</desc>
15060
15061	<const name="Null" value="0">
15062	<desc>Null value (never used by the API).</desc>
15063	</const>
15064	<const name="Am79C970A" value="1">
15065	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
15066	</const>
15067	<const name="Am79C973" value="2">
15068	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
15069	</const>
15070	<const name="I82540EM" value="3">
15071	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
15072	</const>
15073	<const name="I82543GC" value="4">
15074	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
15075	</const>
15076	<const name="I82545EM" value="5">
15077	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
15078	</const>
15079	<const name="Virtio" value="6">
15080	<desc>Virtio network device.</desc>
15081	</const>
15082	</enum>
15083
15084	<enum
15085	name="NetworkAdapterPromiscModePolicy"
15086	uuid="c963768a-376f-4c85-8d84-d8ced4b7269e"
15087	>
15088	<desc>
15089	The promiscuous mode policy of an interface.
15090	</desc>
15091
15092	<const name="Deny" value="1">
15093	<desc>Deny promiscuous mode requests.</desc>
15094	</const>
15095	<const name="AllowNetwork" value="2">
15096	<desc>
15097	Allow promicuous mode, but restrict the scope it to the internal
15098	network so that it only applies to other VMs.
15099	</desc>
15100	</const>
15101	<const name="AllowAll" value="3">
15102	<desc>
15103	Allow promicuous mode, include unrelated traffic going over the wire
15104	and internally on the host.
15105	</desc>
15106	</const>
15107	</enum>
15108
15109	<interface
15110	name="INetworkAdapter" extends="$unknown"
15111	uuid="efa0f965-63c7-4c60-afdf-b1cc9943b9c0"
15112	wsmap="managed"
15113	>
15114	<desc>
15115	Represents a virtual network adapter that is attached to a virtual machine.
15116	Each virtual machine has a fixed number of network adapter slots with one
15117	instance of this attached to each of them. Call
15118	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
15119	is attached to a given slot in a given machine.
15120
15121	Each network adapter can be in one of five attachment modes, which are
15122	represented by the <link to="NetworkAttachmentType" /> enumeration;
15123	see the <link to="#attachmentType" /> attribute.
15124	</desc>
15125
15126	<attribute name="adapterType" type="NetworkAdapterType">
15127	<desc>
15128	Type of the virtual network adapter. Depending on this value,
15129	VirtualBox will provide a different virtual network hardware
15130	to the guest.
15131	</desc>
15132	</attribute>
15133
15134	<attribute name="slot" type="unsigned long" readonly="yes">
15135	<desc>
15136	Slot number this adapter is plugged into. Corresponds to
15137	the value you pass to <link to="IMachine::getNetworkAdapter"/>
15138	to obtain this instance.
15139	</desc>
15140	</attribute>
15141
15142	<attribute name="enabled" type="boolean">
15143	<desc>
15144	Flag whether the network adapter is present in the
15145	guest system. If disabled, the virtual guest hardware will
15146	not contain this network adapter. Can only be changed when
15147	the VM is not running.
15148	</desc>
15149	</attribute>
15150
15151	<attribute name="MACAddress" type="wstring">
15152	<desc>
15153	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
15154	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
15155	</desc>
15156	</attribute>
15157
15158	<attribute name="attachmentType" type="NetworkAttachmentType">
15159	<desc>
15160	Sets/Gets network attachment type of this network adapter.
15161	</desc>
15162	</attribute>
15163
15164	<attribute name="bridgedInterface" type="wstring">
15165	<desc>
15166	Name of the network interface the VM should be bridged to.
15167	</desc>
15168	</attribute>
15169
15170	<attribute name="hostOnlyInterface" type="wstring">
15171	<desc>
15172	Name of the host only network interface the VM is attached to.
15173	</desc>
15174	</attribute>
15175
15176	<attribute name="internalNetwork" type="wstring">
15177	<desc>
15178	Name of the internal network the VM is attached to.
15179	</desc>
15180	</attribute>
15181
15182	<attribute name="NATNetwork" type="wstring">
15183	<desc>
15184	Name of the NAT network the VM is attached to.
15185	</desc>
15186	</attribute>
15187
15188	<attribute name="genericDriver" type="wstring">
15189	<desc>
15190	Name of the driver to use for the "Generic" network attachment type.
15191	</desc>
15192	</attribute>
15193
15194	<attribute name="cableConnected" type="boolean">
15195	<desc>
15196	Flag whether the adapter reports the cable as connected or not.
15197	It can be used to report offline situations to a VM.
15198	</desc>
15199	</attribute>
15200
15201	<attribute name="lineSpeed" type="unsigned long">
15202	<desc>
15203	Line speed reported by custom drivers, in units of 1 kbps.
15204	</desc>
15205	</attribute>
15206
15207	<attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy">
15208	<desc>
15209	The promiscuous mode policy of the network adapter when attached to an
15210	internal network, host only network or a bridge.
15211	</desc>
15212	</attribute>
15213
15214	<attribute name="traceEnabled" type="boolean">
15215	<desc>
15216	Flag whether network traffic from/to the network card should be traced.
15217	Can only be toggled when the VM is turned off.
15218	</desc>
15219	</attribute>
15220
15221	<attribute name="traceFile" type="wstring">
15222	<desc>
15223	Filename where a network trace will be stored. If not set, VBox-pid.pcap
15224	will be used.
15225	</desc>
15226	</attribute>
15227
15228	<attribute name="NATEngine" type="INATEngine" readonly="yes">
15229	<desc>
15230	Points to the NAT engine which handles the network address translation
15231	for this interface. This is active only when the interface actually uses
15232	NAT.
15233	</desc>
15234	</attribute>
15235
15236	<attribute name="bootPriority" type="unsigned long">
15237	<desc>
15238	Network boot priority of the adapter. Priority 1 is highest. If not set,
15239	the priority is considered to be at the lowest possible setting.
15240	</desc>
15241	</attribute>
15242
15243	<attribute name="bandwidthGroup" type="IBandwidthGroup">
15244	<desc>The bandwidth group this network adapter is assigned to.</desc>
15245	</attribute>
15246
15247	<!-- property methods -->
15248
15249	<method name="getProperty" const="yes">
15250	<desc>
15251	Returns the value of the network attachment property with the given name.
15252
15253	If the requested data @a key does not exist, this function will
15254	succeed and return an empty string in the @a value argument.
15255
15256	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15257	</desc>
15258	<param name="key" type="wstring" dir="in">
15259	<desc>Name of the property to get.</desc>
15260	</param>
15261	<param name="value" type="wstring" dir="return">
15262	<desc>Current property value.</desc>
15263	</param>
15264	</method>
15265
15266	<method name="setProperty">
15267	<desc>
15268	Sets the value of the network attachment property with the given name.
15269
15270	Setting the property value to @c null or an empty string is equivalent
15271	to deleting the existing value.
15272
15273	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15274	</desc>
15275	<param name="key" type="wstring" dir="in">
15276	<desc>Name of the property to set.</desc>
15277	</param>
15278	<param name="value" type="wstring" dir="in">
15279	<desc>Property value to set.</desc>
15280	</param>
15281	</method>
15282
15283	<method name="getProperties" const="yes">
15284	<desc>
15285	Returns values for a group of properties in one call.
15286
15287	The names of the properties to get are specified using the @a names
15288	argument which is a list of comma-separated property names or
15289	an empty string if all properties are to be returned.
15290	<note>Currently the value of this argument is ignored and the method
15291	always returns all existing properties.</note>
15292
15293	The method returns two arrays, the array of property names corresponding
15294	to the @a names argument and the current values of these properties.
15295	Both arrays have the same number of elements with each element at the
15296	given index in the first array corresponds to an element at the same
15297	index in the second array.
15298	</desc>
15299	<param name="names" type="wstring" dir="in">
15300	<desc>
15301	Names of properties to get.
15302	</desc>
15303	</param>
15304	<param name="returnNames" type="wstring" safearray="yes" dir="out">
15305	<desc>Names of returned properties.</desc>
15306	</param>
15307	<param name="returnValues" type="wstring" safearray="yes" dir="return">
15308	<desc>Values of returned properties.</desc>
15309	</param>
15310	</method>
15311
15312	</interface>
15313
15314
15315	<!--
15316	// ISerialPort
15317	/////////////////////////////////////////////////////////////////////////
15318	-->
15319
15320	<enum
15321	name="PortMode"
15322	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
15323	>
15324	<desc>
15325	The PortMode enumeration represents possible communication modes for
15326	the virtual serial port device.
15327	</desc>
15328
15329	<const name="Disconnected" value="0">
15330	<desc>Virtual device is not attached to any real host device.</desc>
15331	</const>
15332	<const name="HostPipe" value="1">
15333	<desc>Virtual device is attached to a host pipe.</desc>
15334	</const>
15335	<const name="HostDevice" value="2">
15336	<desc>Virtual device is attached to a host device.</desc>
15337	</const>
15338	<const name="RawFile" value="3">
15339	<desc>Virtual device is attached to a raw file.</desc>
15340	</const>
15341	</enum>
15342
15343	<interface
15344	name="ISerialPort" extends="$unknown"
15345	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
15346	wsmap="managed"
15347	>
15348
15349	<desc>
15350	The ISerialPort interface represents the virtual serial port device.
15351
15352	The virtual serial port device acts like an ordinary serial port
15353	inside the virtual machine. This device communicates to the real
15354	serial port hardware in one of two modes: host pipe or host device.
15355
15356	In host pipe mode, the #path attribute specifies the path to the pipe on
15357	the host computer that represents a serial port. The #server attribute
15358	determines if this pipe is created by the virtual machine process at
15359	machine startup or it must already exist before starting machine
15360	execution.
15361
15362	In host device mode, the #path attribute specifies the name of the
15363	serial port device on the host computer.
15364
15365	There is also a third communication mode: the disconnected mode. In this
15366	mode, the guest OS running inside the virtual machine will be able to
15367	detect the serial port, but all port write operations will be discarded
15368	and all port read operations will return no data.
15369
15370	<see><link to="IMachine::getSerialPort"/></see>
15371	</desc>
15372
15373	<attribute name="slot" type="unsigned long" readonly="yes">
15374	<desc>
15375	Slot number this serial port is plugged into. Corresponds to
15376	the value you pass to <link to="IMachine::getSerialPort"/>
15377	to obtain this instance.
15378	</desc>
15379	</attribute>
15380
15381	<attribute name="enabled" type="boolean">
15382	<desc>
15383	Flag whether the serial port is enabled. If disabled,
15384	the serial port will not be reported to the guest OS.
15385	</desc>
15386	</attribute>
15387
15388	<attribute name="IOBase" type="unsigned long">
15389	<desc>Base I/O address of the serial port.</desc>
15390	</attribute>
15391
15392	<attribute name="IRQ" type="unsigned long">
15393	<desc>IRQ number of the serial port.</desc>
15394	</attribute>
15395
15396	<attribute name="hostMode" type="PortMode">
15397	<desc>
15398	How is this port connected to the host.
15399	<note>
15400	Changing this attribute may fail if the conditions for
15401	<link to="#path"/> are not met.
15402	</note>
15403	</desc>
15404	</attribute>
15405
15406	<attribute name="server" type="boolean">
15407	<desc>
15408	Flag whether this serial port acts as a server (creates a new pipe on
15409	the host) or as a client (uses the existing pipe). This attribute is
15410	used only when <link to="#hostMode"/> is PortMode_HostPipe.
15411	</desc>
15412	</attribute>
15413
15414	<attribute name="path" type="wstring">
15415	<desc>
15416	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
15417	PortMode_HostPipe, or the host serial device name when
15418	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
15419	cases, setting a @c null or empty string as the attribute's value
15420	is an error. Otherwise, the value of this property is ignored.
15421	</desc>
15422	</attribute>
15423
15424	</interface>
15425
15426	<!--
15427	// IParallelPort
15428	/////////////////////////////////////////////////////////////////////////
15429	-->
15430
15431	<interface
15432	name="IParallelPort" extends="$unknown"
15433	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
15434	wsmap="managed"
15435	>
15436
15437	<desc>
15438	The IParallelPort interface represents the virtual parallel port device.
15439
15440	The virtual parallel port device acts like an ordinary parallel port
15441	inside the virtual machine. This device communicates to the real
15442	parallel port hardware using the name of the parallel device on the host
15443	computer specified in the #path attribute.
15444
15445	Each virtual parallel port device is assigned a base I/O address and an
15446	IRQ number that will be reported to the guest operating system and used
15447	to operate the given parallel port from within the virtual machine.
15448
15449	<see><link to="IMachine::getParallelPort"/></see>
15450	</desc>
15451
15452	<attribute name="slot" type="unsigned long" readonly="yes">
15453	<desc>
15454	Slot number this parallel port is plugged into. Corresponds to
15455	the value you pass to <link to="IMachine::getParallelPort"/>
15456	to obtain this instance.
15457	</desc>
15458	</attribute>
15459
15460	<attribute name="enabled" type="boolean">
15461	<desc>
15462	Flag whether the parallel port is enabled. If disabled,
15463	the parallel port will not be reported to the guest OS.
15464	</desc>
15465	</attribute>
15466
15467	<attribute name="IOBase" type="unsigned long">
15468	<desc>Base I/O address of the parallel port.</desc>
15469	</attribute>
15470
15471	<attribute name="IRQ" type="unsigned long">
15472	<desc>IRQ number of the parallel port.</desc>
15473	</attribute>
15474
15475	<attribute name="path" type="wstring">
15476	<desc>
15477	Host parallel device name. If this parallel port is enabled, setting a
15478	@c null or an empty string as this attribute's value will result in
15479	an error.
15480	</desc>
15481	</attribute>
15482
15483	</interface>
15484
15485
15486	<!--
15487	// IMachineDebugger
15488	/////////////////////////////////////////////////////////////////////////
15489	-->
15490
15491	<interface
15492	name="IMachineDebugger" extends="$unknown"
15493	uuid="5e4534dc-21b8-4f6b-8a08-eef50e1a0aa1"
15494	wsmap="managed"
15495	>
15496	<method name="dumpGuestCore">
15497	<desc>
15498	Takes a core dump of the guest.
15499
15500	See include/VBox/dbgfcorefmt.h for details on the file format.
15501	</desc>
15502	<param name="filename" type="wstring" dir="in">
15503	<desc>
15504	The name of the output file. The file must not exist.
15505	</desc>
15506	</param>
15507	<param name="compression" type="wstring" dir="in">
15508	<desc>
15509	Reserved for future compression method indicator.
15510	</desc>
15511	</param>
15512	</method>
15513
15514	<method name="dumpHostProcessCore">
15515	<desc>
15516	Takes a core dump of the VM process on the host.
15517
15518	This feature is not implemented in the 4.0.0 release but it may show up
15519	in a dot release.
15520	</desc>
15521	<param name="filename" type="wstring" dir="in">
15522	<desc>
15523	The name of the output file. The file must not exist.
15524	</desc>
15525	</param>
15526	<param name="compression" type="wstring" dir="in">
15527	<desc>
15528	Reserved for future compression method indicator.
15529	</desc>
15530	</param>
15531	</method>
15532
15533	<method name="info">
15534	<desc>
15535	Interfaces with the info dumpers (DBGFInfo).
15536
15537	This feature is not implemented in the 4.0.0 release but it may show up
15538	in a dot release.
15539	</desc>
15540	<param name="name" type="wstring" dir="in">
15541	<desc>
15542	The name of the info item.
15543	</desc>
15544	</param>
15545	<param name="args" type="wstring" dir="in">
15546	<desc>
15547	Arguments to the info dumper.
15548	</desc>
15549	</param>
15550	<param name="info" type="wstring" dir="return">
15551	<desc>
15552	The into string.
15553	</desc>
15554	</param>
15555	</method>
15556
15557	<method name="injectNMI">
15558	<desc>
15559	Inject an NMI into a running VT-x/AMD-V VM.
15560	</desc>
15561	</method>
15562
15563	<method name="modifyLogGroups">
15564	<desc>
15565	Modifies the group settings of the debug or release logger.
15566	</desc>
15567	<param name="settings" type="wstring" dir="in">
15568	<desc>
15569	The group settings string. See iprt/log.h for details. To target the
15570	release logger, prefix the string with "release:".
15571	</desc>
15572	</param>
15573	</method>
15574
15575	<method name="modifyLogFlags">
15576	<desc>
15577	Modifies the debug or release logger flags.
15578	</desc>
15579	<param name="settings" type="wstring" dir="in">
15580	<desc>
15581	The flags settings string. See iprt/log.h for details. To target the
15582	release logger, prefix the string with "release:".
15583	</desc>
15584	</param>
15585	</method>
15586
15587	<method name="modifyLogDestinations">
15588	<desc>
15589	Modifies the debug or release logger destinations.
15590	</desc>
15591	<param name="settings" type="wstring" dir="in">
15592	<desc>
15593	The destination settings string. See iprt/log.h for details. To target the
15594	release logger, prefix the string with "release:".
15595	</desc>
15596	</param>
15597	</method>
15598
15599	<method name="readPhysicalMemory">
15600	<desc>
15601	Reads guest physical memory, no side effects (MMIO++).
15602
15603	This feature is not implemented in the 4.0.0 release but may show up
15604	in a dot release.
15605	</desc>
15606	<param name="address" type="long long" dir="in">
15607	<desc>The guest physical address.</desc>
15608	</param>
15609	<param name="size" type="unsigned long" dir="in">
15610	<desc>The number of bytes to read.</desc>
15611	</param>
15612	<param name="bytes" type="octet" safearray="yes" dir="return">
15613	<desc>The bytes read.</desc>
15614	</param>
15615	</method>
15616
15617	<method name="writePhysicalMemory">
15618	<desc>
15619	Writes guest physical memory, access handles (MMIO++) are ignored.
15620
15621	This feature is not implemented in the 4.0.0 release but may show up
15622	in a dot release.
15623	</desc>
15624	<param name="address" type="long long" dir="in">
15625	<desc>The guest physical address.</desc>
15626	</param>
15627	<param name="size" type="unsigned long" dir="in">
15628	<desc>The number of bytes to read.</desc>
15629	</param>
15630	<param name="bytes" type="octet" safearray="yes" dir="in">
15631	<desc>The bytes to write.</desc>
15632	</param>
15633	</method>
15634
15635	<method name="readVirtualMemory">
15636	<desc>
15637	Reads guest virtual memory, no side effects (MMIO++).
15638
15639	This feature is not implemented in the 4.0.0 release but may show up
15640	in a dot release.
15641	</desc>
15642	<param name="cpuId" type="unsigned long" dir="in">
15643	<desc>The identifier of the Virtual CPU.</desc>
15644	</param>
15645	<param name="address" type="long long" dir="in">
15646	<desc>The guest virtual address.</desc>
15647	</param>
15648	<param name="size" type="unsigned long" dir="in">
15649	<desc>The number of bytes to read.</desc>
15650	</param>
15651	<param name="bytes" type="octet" safearray="yes" dir="return">
15652	<desc>The bytes read.</desc>
15653	</param>
15654	</method>
15655
15656	<method name="writeVirtualMemory">
15657	<desc>
15658	Writes guest virtual memory, access handles (MMIO++) are ignored.
15659
15660	This feature is not implemented in the 4.0.0 release but may show up
15661	in a dot release.
15662	</desc>
15663	<param name="cpuId" type="unsigned long" dir="in">
15664	<desc>The identifier of the Virtual CPU.</desc>
15665	</param>
15666	<param name="address" type="long long" dir="in">
15667	<desc>The guest virtual address.</desc>
15668	</param>
15669	<param name="size" type="unsigned long" dir="in">
15670	<desc>The number of bytes to read.</desc>
15671	</param>
15672	<param name="bytes" type="octet" safearray="yes" dir="in">
15673	<desc>The bytes to write.</desc>
15674	</param>
15675	</method>
15676
15677	<method name="detectOS">
15678	<desc>
15679	Tries to (re-)detect the guest OS kernel.
15680
15681	This feature is not implemented in the 4.0.0 release but may show up
15682	in a dot release.
15683	</desc>
15684	<param name="os" type="wstring" dir="return">
15685	<desc>
15686	The detected OS kernel on success.
15687	</desc>
15688	</param>
15689	</method>
15690
15691	<method name="getRegister">
15692	<desc>
15693	Gets one register.
15694
15695	This feature is not implemented in the 4.0.0 release but may show up
15696	in a dot release.
15697	</desc>
15698	<param name="cpuId" type="unsigned long" dir="in">
15699	<desc>The identifier of the Virtual CPU.</desc>
15700	</param>
15701	<param name="name" type="wstring" dir="in">
15702	<desc>The register name, case is ignored.</desc>
15703	</param>
15704	<param name="value" type="wstring" dir="return">
15705	<desc>
15706	The register value. This is usually a hex value (always 0x prefixed)
15707	but other format may be used for floating point registers (TBD).
15708	</desc>
15709	</param>
15710	</method>
15711
15712	<method name="getRegisters">
15713	<desc>
15714	Gets all the registers for the given CPU.
15715
15716	This feature is not implemented in the 4.0.0 release but may show up
15717	in a dot release.
15718	</desc>
15719	<param name="cpuId" type="unsigned long" dir="in">
15720	<desc>The identifier of the Virtual CPU.</desc>
15721	</param>
15722	<param name="names" type="wstring" dir="out" safearray="yes">
15723	<desc>Array containing the lowercase register names.</desc>
15724	</param>
15725	<param name="values" type="wstring" dir="out" safearray="yes">
15726	<desc>
15727	Array paralell to the names holding the register values as if the
15728	register was returned by <link to="IMachineDebugger::getRegister"/>.
15729	</desc>
15730	</param>
15731	</method>
15732
15733	<method name="setRegister">
15734	<desc>
15735	Gets one register.
15736
15737	This feature is not implemented in the 4.0.0 release but may show up
15738	in a dot release.
15739	</desc>
15740	<param name="cpuId" type="unsigned long" dir="in">
15741	<desc>The identifier of the Virtual CPU.</desc>
15742	</param>
15743	<param name="name" type="wstring" dir="in">
15744	<desc>The register name, case is ignored.</desc>
15745	</param>
15746	<param name="value" type="wstring" dir="in">
15747	<desc>
15748	The new register value. Hexadecimal, decimal and octal formattings
15749	are supported in addition to any special formattings returned by
15750	the getters.
15751	</desc>
15752	</param>
15753	</method>
15754
15755	<method name="setRegisters">
15756	<desc>
15757	Sets zero or more registers atomically.
15758
15759	This feature is not implemented in the 4.0.0 release but may show up
15760	in a dot release.
15761	</desc>
15762	<param name="cpuId" type="unsigned long" dir="in">
15763	<desc>The identifier of the Virtual CPU.</desc>
15764	</param>
15765	<param name="names" type="wstring" dir="in" safearray="yes">
15766	<desc>Array containing the register names, case ignored.</desc>
15767	</param>
15768	<param name="values" type="wstring" dir="in" safearray="yes">
15769	<desc>
15770	Array paralell to the names holding the register values. See
15771	<link to="IMachineDebugger::setRegister"/> for formatting
15772	guidelines.
15773	</desc>
15774	</param>
15775	</method>
15776
15777	<method name="dumpGuestStack">
15778	<desc>
15779	Produce a simple stack dump using the current guest state.
15780
15781	This feature is not implemented in the 4.0.0 release but may show up
15782	in a dot release.
15783	</desc>
15784	<param name="cpuId" type="unsigned long" dir="in">
15785	<desc>The identifier of the Virtual CPU.</desc>
15786	</param>
15787	<param name="stack" type="wstring" dir="return">
15788	<desc>String containing the formatted stack dump.</desc>
15789	</param>
15790	</method>
15791
15792	<method name="resetStats">
15793	<desc>
15794	Reset VM statistics.
15795	</desc>
15796	<param name="pattern" type="wstring" dir="in">
15797	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15798	</param>
15799	</method>
15800
15801	<method name="dumpStats">
15802	<desc>
15803	Dumps VM statistics.
15804	</desc>
15805	<param name="pattern" type="wstring" dir="in">
15806	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15807	</param>
15808	</method>
15809
15810	<method name="getStats">
15811	<desc>
15812	Get the VM statistics in a XMLish format.
15813	</desc>
15814	<param name="pattern" type="wstring" dir="in">
15815	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15816	</param>
15817	<param name="withDescriptions" type="boolean" dir="in">
15818	<desc>Whether to include the descriptions.</desc>
15819	</param>
15820	<param name="stats" type="wstring" dir="return">
15821	<desc>The XML document containing the statistics.</desc>
15822	</param>
15823	</method>
15824
15825	<attribute name="singleStep" type="boolean">
15826	<desc>Switch for enabling single-stepping.</desc>
15827	</attribute>
15828
15829	<attribute name="recompileUser" type="boolean">
15830	<desc>Switch for forcing code recompilation for user mode code.</desc>
15831	</attribute>
15832
15833	<attribute name="recompileSupervisor" type="boolean">
15834	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
15835	</attribute>
15836
15837	<attribute name="executeAllInIEM" type="boolean">
15838	<desc>
15839	Whether to execute all the code in the instruction interpreter. This
15840	is mainly for testing the interpreter and not an execution mode
15841	intended for general consumption.
15842	</desc>
15843	</attribute>
15844
15845	<attribute name="PATMEnabled" type="boolean">
15846	<desc>Switch for enabling and disabling the PATM component.</desc>
15847	</attribute>
15848
15849	<attribute name="CSAMEnabled" type="boolean">
15850	<desc>Switch for enabling and disabling the CSAM component.</desc>
15851	</attribute>
15852
15853	<attribute name="logEnabled" type="boolean">
15854	<desc>Switch for enabling and disabling the debug logger.</desc>
15855	</attribute>
15856
15857	<attribute name="logDbgFlags" type="wstring" readonly="yes">
15858	<desc>The debug logger flags.</desc>
15859	</attribute>
15860
15861	<attribute name="logDbgGroups" type="wstring" readonly="yes">
15862	<desc>The debug logger's group settings.</desc>
15863	</attribute>
15864
15865	<attribute name="logDbgDestinations" type="wstring" readonly="yes">
15866	<desc>The debug logger's destination settings.</desc>
15867	</attribute>
15868
15869	<attribute name="logRelFlags" type="wstring" readonly="yes">
15870	<desc>The release logger flags.</desc>
15871	</attribute>
15872
15873	<attribute name="logRelGroups" type="wstring" readonly="yes">
15874	<desc>The release logger's group settings.</desc>
15875	</attribute>
15876
15877	<attribute name="logRelDestinations" type="wstring" readonly="yes">
15878	<desc>The relase logger's destination settings.</desc>
15879	</attribute>
15880
15881	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
15882	<desc>
15883	Flag indicating whether the VM is currently making use of CPU hardware
15884	virtualization extensions.
15885	</desc>
15886	</attribute>
15887
15888	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
15889	<desc>
15890	Flag indicating whether the VM is currently making use of the nested paging
15891	CPU hardware virtualization extension.
15892	</desc>
15893	</attribute>
15894
15895	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
15896	<desc>
15897	Flag indicating whether the VM is currently making use of the VPID
15898	VT-x extension.
15899	</desc>
15900	</attribute>
15901
15902	<attribute name="HWVirtExUXEnabled" type="boolean" readonly="yes">
15903	<desc>
15904	Flag indicating whether the VM is currently making use of the
15905	unrestricted execution feature of VT-x.
15906	</desc>
15907	</attribute>
15908
15909	<attribute name="OSName" type="wstring" readonly="yes">
15910	<desc>
15911	Query the guest OS kernel name as detected by the DBGF.
15912
15913	This feature is not implemented in the 4.0.0 release but may show up
15914	in a dot release.
15915	</desc>
15916	</attribute>
15917
15918	<attribute name="OSVersion" type="wstring" readonly="yes">
15919	<desc>
15920	Query the guest OS kernel version string as detected by the DBGF.
15921
15922	This feature is not implemented in the 4.0.0 release but may show up
15923	in a dot release.
15924	</desc>
15925	</attribute>
15926
15927	<attribute name="PAEEnabled" type="boolean" readonly="yes">
15928	<desc>
15929	Flag indicating whether the VM is currently making use of the Physical
15930	Address Extension CPU feature.
15931	</desc>
15932	</attribute>
15933
15934	<attribute name="virtualTimeRate" type="unsigned long">
15935	<desc>
15936	The rate at which the virtual time runs expressed as a percentage.
15937	The accepted range is 2% to 20000%.
15938	</desc>
15939	</attribute>
15940
15941	<attribute name="VM" type="long long" readonly="yes" wsmap="suppress">
15942	<desc>
15943	Gets the user-mode VM handle, with a reference. Must be passed to
15944	VMR3ReleaseUVM when done. This is only for internal use while we carve
15945	the details of this interface.
15946	</desc>
15947	</attribute>
15948
15949	</interface>
15950
15951	<!--
15952	// IUSBController
15953	/////////////////////////////////////////////////////////////////////////
15954	-->
15955
15956	<interface
15957	name="IUSBController" extends="$unknown"
15958	uuid="01e6f13a-0580-452f-a40f-74e32a5e4921"
15959	wsmap="managed"
15960	>
15961	<attribute name="enabled" type="boolean">
15962	<desc>
15963	Flag whether the USB controller is present in the
15964	guest system. If disabled, the virtual guest hardware will
15965	not contain any USB controller. Can only be changed when
15966	the VM is powered off.
15967	</desc>
15968	</attribute>
15969
15970	<attribute name="enabledEHCI" type="boolean">
15971	<desc>
15972	Flag whether the USB EHCI controller is present in the
15973	guest system. If disabled, the virtual guest hardware will
15974	not contain a USB EHCI controller. Can only be changed when
15975	the VM is powered off.
15976	</desc>
15977	</attribute>
15978
15979	<attribute name="proxyAvailable" type="boolean" readonly="yes">
15980	<desc>
15981	Flag whether there is an USB proxy available.
15982	</desc>
15983	</attribute>
15984
15985	<attribute name="USBStandard" type="unsigned short" readonly="yes">
15986	<desc>
15987	USB standard version which the controller implements.
15988	This is a BCD which means that the major version is in the
15989	high byte and minor version is in the low byte.
15990	</desc>
15991	</attribute>
15992
15993	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
15994	<desc>
15995	List of USB device filters associated with the machine.
15996
15997	If the machine is currently running, these filters are activated
15998	every time a new (supported) USB device is attached to the host
15999	computer that was not ignored by global filters
16000	(<link to="IHost::USBDeviceFilters"/>).
16001
16002	These filters are also activated when the machine is powered up.
16003	They are run against a list of all currently available USB
16004	devices (in states
16005	<link to="USBDeviceState_Available"/>,
16006	<link to="USBDeviceState_Busy"/>,
16007	<link to="USBDeviceState_Held"/>) that were not previously
16008	ignored by global filters.
16009
16010	If at least one filter matches the USB device in question, this
16011	device is automatically captured (attached to) the virtual USB
16012	controller of this machine.
16013
16014	<see><link to="IUSBDeviceFilter"/>, <link to="IUSBController"/></see>
16015	</desc>
16016	</attribute>
16017
16018	<method name="createDeviceFilter">
16019	<desc>
16020	Creates a new USB device filter. All attributes except
16021	the filter name are set to empty (any match),
16022	<i>active</i> is @c false (the filter is not active).
16023
16024	The created filter can then be added to the list of filters using
16025	<link to="#insertDeviceFilter"/>.
16026
16027	<result name="VBOX_E_INVALID_VM_STATE">
16028	The virtual machine is not mutable.
16029	</result>
16030
16031	<see><link to="#deviceFilters"/></see>
16032	</desc>
16033	<param name="name" type="wstring" dir="in">
16034	<desc>
16035	Filter name. See <link to="IUSBDeviceFilter::name"/>
16036	for more info.
16037	</desc>
16038	</param>
16039	<param name="filter" type="IUSBDeviceFilter" dir="return">
16040	<desc>Created filter object.</desc>
16041	</param>
16042	</method>
16043
16044	<method name="insertDeviceFilter">
16045	<desc>
16046	Inserts the given USB device to the specified position
16047	in the list of filters.
16048
16049	Positions are numbered starting from <tt>0</tt>. If the specified
16050	position is equal to or greater than the number of elements in
16051	the list, the filter is added to the end of the collection.
16052
16053	<note>
16054	Duplicates are not allowed, so an attempt to insert a
16055	filter that is already in the collection, will return an
16056	error.
16057	</note>
16058
16059	<result name="VBOX_E_INVALID_VM_STATE">
16060	Virtual machine is not mutable.
16061	</result>
16062	<result name="E_INVALIDARG">
16063	USB device filter not created within this VirtualBox instance.
16064	</result>
16065	<result name="VBOX_E_INVALID_OBJECT_STATE">
16066	USB device filter already in list.
16067	</result>
16068
16069	<see><link to="#deviceFilters"/></see>
16070	</desc>
16071	<param name="position" type="unsigned long" dir="in">
16072	<desc>Position to insert the filter to.</desc>
16073	</param>
16074	<param name="filter" type="IUSBDeviceFilter" dir="in">
16075	<desc>USB device filter to insert.</desc>
16076	</param>
16077	</method>
16078
16079	<method name="removeDeviceFilter">
16080	<desc>
16081	Removes a USB device filter from the specified position in the
16082	list of filters.
16083
16084	Positions are numbered starting from <tt>0</tt>. Specifying a
16085	position equal to or greater than the number of elements in
16086	the list will produce an error.
16087
16088	<see><link to="#deviceFilters"/></see>
16089
16090	<result name="VBOX_E_INVALID_VM_STATE">
16091	Virtual machine is not mutable.
16092	</result>
16093	<result name="E_INVALIDARG">
16094	USB device filter list empty or invalid @a position.
16095	</result>
16096
16097	</desc>
16098	<param name="position" type="unsigned long" dir="in">
16099	<desc>Position to remove the filter from.</desc>
16100	</param>
16101	<param name="filter" type="IUSBDeviceFilter" dir="return">
16102	<desc>Removed USB device filter.</desc>
16103	</param>
16104	</method>
16105
16106	</interface>
16107
16108
16109	<!--
16110	// IUSBDevice
16111	/////////////////////////////////////////////////////////////////////////
16112	-->
16113
16114	<interface
16115	name="IUSBDevice" extends="$unknown"
16116	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
16117	wsmap="managed"
16118	>
16119	<desc>
16120	The IUSBDevice interface represents a virtual USB device attached to the
16121	virtual machine.
16122
16123	A collection of objects implementing this interface is stored in the
16124	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
16125	attached to a running virtual machine's USB controller.
16126	</desc>
16127
16128	<attribute name="id" type="uuid" mod="string" readonly="yes">
16129	<desc>
16130	Unique USB device ID. This ID is built from #vendorId,
16131	#productId, #revision and #serialNumber.
16132	</desc>
16133	</attribute>
16134
16135	<attribute name="vendorId" type="unsigned short" readonly="yes">
16136	<desc>Vendor ID.</desc>
16137	</attribute>
16138
16139	<attribute name="productId" type="unsigned short" readonly="yes">
16140	<desc>Product ID.</desc>
16141	</attribute>
16142
16143	<attribute name="revision" type="unsigned short" readonly="yes">
16144	<desc>
16145	Product revision number. This is a packed BCD represented as
16146	unsigned short. The high byte is the integer part and the low
16147	byte is the decimal.
16148	</desc>
16149	</attribute>
16150
16151	<attribute name="manufacturer" type="wstring" readonly="yes">
16152	<desc>Manufacturer string.</desc>
16153	</attribute>
16154
16155	<attribute name="product" type="wstring" readonly="yes">
16156	<desc>Product string.</desc>
16157	</attribute>
16158
16159	<attribute name="serialNumber" type="wstring" readonly="yes">
16160	<desc>Serial number string.</desc>
16161	</attribute>
16162
16163	<attribute name="address" type="wstring" readonly="yes">
16164	<desc>Host specific address of the device.</desc>
16165	</attribute>
16166
16167	<attribute name="port" type="unsigned short" readonly="yes">
16168	<desc>
16169	Host USB port number the device is physically
16170	connected to.
16171	</desc>
16172	</attribute>
16173
16174	<attribute name="version" type="unsigned short" readonly="yes">
16175	<desc>
16176	The major USB version of the device - 1 or 2.
16177	</desc>
16178	</attribute>
16179
16180	<attribute name="portVersion" type="unsigned short" readonly="yes">
16181	<desc>
16182	The major USB version of the host USB port the device is
16183	physically connected to - 1 or 2. For devices not connected to
16184	anything this will have the same value as the version attribute.
16185	</desc>
16186	</attribute>
16187
16188	<attribute name="remote" type="boolean" readonly="yes">
16189	<desc>
16190	Whether the device is physically connected to a remote VRDE
16191	client or to a local host machine.
16192	</desc>
16193	</attribute>
16194
16195	</interface>
16196
16197
16198	<!--
16199	// IUSBDeviceFilter
16200	/////////////////////////////////////////////////////////////////////////
16201	-->
16202
16203	<interface
16204	name="IUSBDeviceFilter" extends="$unknown"
16205	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
16206	wsmap="managed"
16207	>
16208	<desc>
16209	The IUSBDeviceFilter interface represents an USB device filter used
16210	to perform actions on a group of USB devices.
16211
16212	This type of filters is used by running virtual machines to
16213	automatically capture selected USB devices once they are physically
16214	attached to the host computer.
16215
16216	A USB device is matched to the given device filter if and only if all
16217	attributes of the device match the corresponding attributes of the
16218	filter (that is, attributes are joined together using the logical AND
16219	operation). On the other hand, all together, filters in the list of
16220	filters carry the semantics of the logical OR operation. So if it is
16221	desirable to create a match like "this vendor id OR this product id",
16222	one needs to create two filters and specify "any match" (see below)
16223	for unused attributes.
16224
16225	All filter attributes used for matching are strings. Each string
16226	is an expression representing a set of values of the corresponding
16227	device attribute, that will match the given filter. Currently, the
16228	following filtering expressions are supported:
16229
16230	<ul>
16231	<li><i>Interval filters</i>. Used to specify valid intervals for
16232	integer device attributes (Vendor ID, Product ID and Revision).
16233	The format of the string is:
16234
16235	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
16236
16237	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
16238	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
16239	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
16240	is omitted before a dash (<tt>-</tt>), the minimum possible integer
16241	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
16242	possible integer is assumed.
16243	</li>
16244	<li><i>Boolean filters</i>. Used to specify acceptable values for
16245	boolean device attributes. The format of the string is:
16246
16247	<tt>true\|false\|yes\|no\|0\|1</tt>
16248
16249	</li>
16250	<li><i>Exact match</i>. Used to specify a single value for the given
16251	device attribute. Any string that doesn't start with <tt>int:</tt>
16252	represents the exact match. String device attributes are compared to
16253	this string including case of symbols. Integer attributes are first
16254	converted to a string (see individual filter attributes) and then
16255	compared ignoring case.
16256
16257	</li>
16258	<li><i>Any match</i>. Any value of the corresponding device attribute
16259	will match the given filter. An empty or @c null string is
16260	used to construct this type of filtering expressions.
16261
16262	</li>
16263	</ul>
16264
16265	<note>
16266	On the Windows host platform, interval filters are not currently
16267	available. Also all string filter attributes
16268	(<link to="#manufacturer"/>, <link to="#product"/>,
16269	<link to="#serialNumber"/>) are ignored, so they behave as
16270	<i>any match</i> no matter what string expression is specified.
16271	</note>
16272
16273	<see><link to="IUSBController::deviceFilters"/>,
16274	<link to="IHostUSBDeviceFilter"/></see>
16275	</desc>
16276
16277	<attribute name="name" type="wstring">
16278	<desc>
16279	Visible name for this filter.
16280	This name is used to visually distinguish one filter from another,
16281	so it can neither be @c null nor an empty string.
16282	</desc>
16283	</attribute>
16284
16285	<attribute name="active" type="boolean">
16286	<desc>Whether this filter active or has been temporarily disabled.</desc>
16287	</attribute>
16288
16289	<attribute name="vendorId" type="wstring">
16290	<desc>
16291	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
16292	The string representation for the <i>exact matching</i>
16293	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16294	(including leading zeroes).
16295	</desc>
16296	</attribute>
16297
16298	<attribute name="productId" type="wstring">
16299	<desc>
16300	<link to="IUSBDevice::productId">Product ID</link> filter.
16301	The string representation for the <i>exact matching</i>
16302	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16303	(including leading zeroes).
16304	</desc>
16305	</attribute>
16306
16307	<attribute name="revision" type="wstring">
16308	<desc>
16309	<link to="IUSBDevice::productId">Product revision number</link>
16310	filter. The string representation for the <i>exact matching</i>
16311	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
16312	of the integer part of the revision, and <tt>F</tt> is the
16313	decimal digit of its fractional part (including leading and
16314	trailing zeros).
16315	Note that for interval filters, it's best to use the hexadecimal
16316	form, because the revision is stored as a 16 bit packed BCD value;
16317	so the expression <tt>int:0x0100-0x0199</tt> will match any
16318	revision from <tt>1.0</tt> to <tt>1.99</tt>.
16319	</desc>
16320	</attribute>
16321
16322	<attribute name="manufacturer" type="wstring">
16323	<desc>
16324	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
16325	</desc>
16326	</attribute>
16327
16328	<attribute name="product" type="wstring">
16329	<desc>
16330	<link to="IUSBDevice::product">Product</link> filter.
16331	</desc>
16332	</attribute>
16333
16334	<attribute name="serialNumber" type="wstring">
16335	<desc>
16336	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
16337	</desc>
16338	</attribute>
16339
16340	<attribute name="port" type="wstring">
16341	<desc>
16342	<link to="IUSBDevice::port">Host USB port</link> filter.
16343	</desc>
16344	</attribute>
16345
16346	<attribute name="remote" type="wstring">
16347	<desc>
16348	<link to="IUSBDevice::remote">Remote state</link> filter.
16349	<note>
16350	This filter makes sense only for machine USB filters,
16351	i.e. it is ignored by IHostUSBDeviceFilter objects.
16352	</note>
16353	</desc>
16354	</attribute>
16355
16356	<attribute name="maskedInterfaces" type="unsigned long">
16357	<desc>
16358	This is an advanced option for hiding one or more USB interfaces
16359	from the guest. The value is a bit mask where the bits that are set
16360	means the corresponding USB interface should be hidden, masked off
16361	if you like.
16362	This feature only works on Linux hosts.
16363	</desc>
16364	</attribute>
16365
16366	</interface>
16367
16368
16369	<!--
16370	// IHostUSBDevice
16371	/////////////////////////////////////////////////////////////////////////
16372	-->
16373
16374	<enum
16375	name="USBDeviceState"
16376	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
16377	>
16378	<desc>
16379	USB device state. This enumeration represents all possible states
16380	of the USB device physically attached to the host computer regarding
16381	its state on the host computer and availability to guest computers
16382	(all currently running virtual machines).
16383
16384	Once a supported USB device is attached to the host, global USB
16385	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
16386	either ignore the device, or put it to USBDeviceState_Held state, or do
16387	nothing. Unless the device is ignored by global filters, filters of all
16388	currently running guests (<link to="IUSBController::deviceFilters"/>) are
16389	activated that can put it to USBDeviceState_Captured state.
16390
16391	If the device was ignored by global filters, or didn't match
16392	any filters at all (including guest ones), it is handled by the host
16393	in a normal way. In this case, the device state is determined by
16394	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
16395	or USBDeviceState_Available, depending on the current device usage.
16396
16397	Besides auto-capturing based on filters, the device can be manually
16398	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
16399	state is USBDeviceState_Busy, USBDeviceState_Available or
16400	USBDeviceState_Held.
16401
16402	<note>
16403	Due to differences in USB stack implementations in Linux and Win32,
16404	states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
16405	only to the Linux version of the product. This also means that (<link
16406	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
16407	device state is USBDeviceState_Held.
16408	</note>
16409
16410	<see><link to="IHostUSBDevice"/>, <link to="IHostUSBDeviceFilter"/></see>
16411	</desc>
16412
16413	<const name="NotSupported" value="0">
16414	<desc>
16415	Not supported by the VirtualBox server, not available to guests.
16416	</desc>
16417	</const>
16418	<const name="Unavailable" value="1">
16419	<desc>
16420	Being used by the host computer exclusively,
16421	not available to guests.
16422	</desc>
16423	</const>
16424	<const name="Busy" value="2">
16425	<desc>
16426	Being used by the host computer, potentially available to guests.
16427	</desc>
16428	</const>
16429	<const name="Available" value="3">
16430	<desc>
16431	Not used by the host computer, available to guests (the host computer
16432	can also start using the device at any time).
16433	</desc>
16434	</const>
16435	<const name="Held" value="4">
16436	<desc>
16437	Held by the VirtualBox server (ignored by the host computer),
16438	available to guests.
16439	</desc>
16440	</const>
16441	<const name="Captured" value="5">
16442	<desc>
16443	Captured by one of the guest computers, not available
16444	to anybody else.
16445	</desc>
16446	</const>
16447	</enum>
16448
16449	<interface
16450	name="IHostUSBDevice" extends="IUSBDevice"
16451	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
16452	wsmap="managed"
16453	>
16454	<desc>
16455	The IHostUSBDevice interface represents a physical USB device attached
16456	to the host computer.
16457
16458	Besides properties inherited from IUSBDevice, this interface adds the
16459	<link to="#state"/> property that holds the current state of the USB
16460	device.
16461
16462	<see><link to="IHost::USBDevices"/>,
16463	<link to="IHost::USBDeviceFilters"/></see>
16464	</desc>
16465
16466	<attribute name="state" type="USBDeviceState" readonly="yes">
16467	<desc>
16468	Current state of the device.
16469	</desc>
16470	</attribute>
16471
16472	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
16473
16474	</interface>
16475
16476
16477	<!--
16478	// IHostUSBDeviceFilter
16479	/////////////////////////////////////////////////////////////////////////
16480	-->
16481
16482	<enum
16483	name="USBDeviceFilterAction"
16484	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
16485	>
16486	<desc>
16487	Actions for host USB device filters.
16488	<see><link to="IHostUSBDeviceFilter"/>, <link to="USBDeviceState"/></see>
16489	</desc>
16490
16491	<const name="Null" value="0">
16492	<desc>Null value (never used by the API).</desc>
16493	</const>
16494	<const name="Ignore" value="1">
16495	<desc>Ignore the matched USB device.</desc>
16496	</const>
16497	<const name="Hold" value="2">
16498	<desc>Hold the matched USB device.</desc>
16499	</const>
16500	</enum>
16501
16502	<interface
16503	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
16504	uuid="4cc70246-d74a-400f-8222-3900489c0374"
16505	wsmap="managed"
16506	>
16507	<desc>
16508	The IHostUSBDeviceFilter interface represents a global filter for a
16509	physical USB device used by the host computer. Used indirectly in
16510	<link to="IHost::USBDeviceFilters"/>.
16511
16512	Using filters of this type, the host computer determines the initial
16513	state of the USB device after it is physically attached to the
16514	host's USB controller.
16515
16516	<note>
16517	The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
16518	filters, because it makes sense only for
16519	<link to="IUSBController::deviceFilters">machine USB filters</link>.
16520	</note>
16521
16522	<see><link to="IHost::USBDeviceFilters"/></see>
16523	</desc>
16524
16525	<attribute name="action" type="USBDeviceFilterAction">
16526	<desc>
16527	Action performed by the host when an attached USB device
16528	matches this filter.
16529	</desc>
16530	</attribute>
16531
16532	</interface>
16533
16534	<!--
16535	// IAudioAdapter
16536	/////////////////////////////////////////////////////////////////////////
16537	-->
16538
16539	<enum
16540	name="AudioDriverType"
16541	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
16542	>
16543	<desc>
16544	Host audio driver type.
16545	</desc>
16546
16547	<const name="Null" value="0">
16548	<desc>Null value, also means "dummy audio driver".</desc>
16549	</const>
16550	<const name="WinMM" value="1">
16551	<desc>Windows multimedia (Windows hosts only).</desc>
16552	</const>
16553	<const name="OSS" value="2">
16554	<desc>Open Sound System (Linux hosts only).</desc>
16555	</const>
16556	<const name="ALSA" value="3">
16557	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
16558	</const>
16559	<const name="DirectSound" value="4">
16560	<desc>DirectSound (Windows hosts only).</desc>
16561	</const>
16562	<const name="CoreAudio" value="5">
16563	<desc>CoreAudio (Mac hosts only).</desc>
16564	</const>
16565	<const name="MMPM" value="6">
16566	<desc>Reserved for historical reasons.</desc>
16567	</const>
16568	<const name="Pulse" value="7">
16569	<desc>PulseAudio (Linux hosts only).</desc>
16570	</const>
16571	<const name="SolAudio" value="8">
16572	<desc>Solaris audio (Solaris hosts only).</desc>
16573	</const>
16574	</enum>
16575
16576	<enum
16577	name="AudioControllerType"
16578	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
16579	>
16580	<desc>
16581	Virtual audio controller type.
16582	</desc>
16583
16584	<const name="AC97" value="0"/>
16585	<const name="SB16" value="1"/>
16586	<const name="HDA" value="2"/>
16587	</enum>
16588
16589	<interface
16590	name="IAudioAdapter" extends="$unknown"
16591	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
16592	wsmap="managed"
16593	>
16594	<desc>
16595	The IAudioAdapter interface represents the virtual audio adapter of
16596	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
16597	</desc>
16598	<attribute name="enabled" type="boolean">
16599	<desc>
16600	Flag whether the audio adapter is present in the
16601	guest system. If disabled, the virtual guest hardware will
16602	not contain any audio adapter. Can only be changed when
16603	the VM is not running.
16604	</desc>
16605	</attribute>
16606	<attribute name="audioController" type="AudioControllerType">
16607	<desc>
16608	The audio hardware we emulate.
16609	</desc>
16610	</attribute>
16611	<attribute name="audioDriver" type="AudioDriverType">
16612	<desc>
16613	Audio driver the adapter is connected to. This setting
16614	can only be changed when the VM is not running.
16615	</desc>
16616	</attribute>
16617	</interface>
16618
16619	<enum
16620	name="AuthType"
16621	uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
16622	>
16623	<desc>
16624	VirtualBox authentication type.
16625	</desc>
16626
16627	<const name="Null" value="0">
16628	<desc>Null value, also means "no authentication".</desc>
16629	</const>
16630	<const name="External" value="1"/>
16631	<const name="Guest" value="2"/>
16632	</enum>
16633
16634	<!--
16635	// IVRDEServer
16636	/////////////////////////////////////////////////////////////////////////
16637	-->
16638
16639	<interface
16640	name="IVRDEServer" extends="$unknown"
16641	uuid="d38de40a-c2c1-4e95-b5a4-167b05f5694c"
16642	wsmap="managed"
16643	>
16644
16645	<attribute name="enabled" type="boolean">
16646	<desc>Flag if VRDE server is enabled.</desc>
16647	</attribute>
16648
16649	<attribute name="authType" type="AuthType">
16650	<desc>VRDE authentication method.</desc>
16651	</attribute>
16652
16653	<attribute name="authTimeout" type="unsigned long">
16654	<desc>Timeout for guest authentication. Milliseconds.</desc>
16655	</attribute>
16656
16657	<attribute name="allowMultiConnection" type="boolean">
16658	<desc>
16659	Flag whether multiple simultaneous connections to the VM are permitted.
16660	Note that this will be replaced by a more powerful mechanism in the future.
16661	</desc>
16662	</attribute>
16663
16664	<attribute name="reuseSingleConnection" type="boolean">
16665	<desc>
16666	Flag whether the existing connection must be dropped and a new connection
16667	must be established by the VRDE server, when a new client connects in single
16668	connection mode.
16669	</desc>
16670	</attribute>
16671
16672	<attribute name="VRDEExtPack" type="wstring">
16673	<desc>
16674	The name of Extension Pack providing VRDE for this VM. Overrides
16675	<link to="ISystemProperties::defaultVRDEExtPack"/>.
16676	</desc>
16677	</attribute>
16678
16679	<attribute name="authLibrary" type="wstring">
16680	<desc>
16681	Library used for authentication of RDP clients by this VM. Overrides
16682	<link to="ISystemProperties::VRDEAuthLibrary"/>.
16683	</desc>
16684	</attribute>
16685
16686	<attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes">
16687	<desc>
16688	Array of names of properties, which are supported by this VRDE server.
16689	</desc>
16690	</attribute>
16691
16692	<method name="setVRDEProperty">
16693	<desc>
16694	Sets a VRDE specific property string.
16695
16696	If you pass @c null or empty string as a key @a value, the given @a key
16697	will be deleted.
16698
16699	</desc>
16700	<param name="key" type="wstring" dir="in">
16701	<desc>Name of the key to set.</desc>
16702	</param>
16703	<param name="value" type="wstring" dir="in">
16704	<desc>Value to assign to the key.</desc>
16705	</param>
16706	</method>
16707
16708	<method name="getVRDEProperty" const="yes">
16709	<desc>
16710	Returns a VRDE specific property string.
16711
16712	If the requested data @a key does not exist, this function will
16713	succeed and return an empty string in the @a value argument.
16714
16715	</desc>
16716	<param name="key" type="wstring" dir="in">
16717	<desc>Name of the key to get.</desc>
16718	</param>
16719	<param name="value" type="wstring" dir="return">
16720	<desc>Value of the requested key.</desc>
16721	</param>
16722	</method>
16723
16724	</interface>
16725
16726
16727	<!--
16728	// ISharedFolder
16729	/////////////////////////////////////////////////////////////////////////
16730	-->
16731
16732	<interface
16733	name="ISharedFolder" extends="$unknown"
16734	uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
16735	wsmap="struct"
16736	>
16737	<desc>
16738	The ISharedFolder interface represents a folder in the host computer's
16739	file system accessible from the guest OS running inside a virtual
16740	machine using an associated logical name.
16741
16742	There are three types of shared folders:
16743	<ul>
16744	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
16745	folders available to all virtual machines.</li>
16746	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
16747	VM-specific shared folders available to the given virtual machine at
16748	startup.</li>
16749	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
16750	VM-specific shared folders created in the session context (for
16751	example, when the virtual machine is running) and automatically
16752	discarded when the session is closed (the VM is powered off).</li>
16753	</ul>
16754
16755	Logical names of shared folders must be unique within the given scope
16756	(global, permanent or transient). However, they do not need to be unique
16757	across scopes. In this case, the definition of the shared folder in a
16758	more specific scope takes precedence over definitions in all other
16759	scopes. The order of precedence is (more specific to more general):
16760	<ol>
16761	<li>Transient definitions</li>
16762	<li>Permanent definitions</li>
16763	<li>Global definitions</li>
16764	</ol>
16765
16766	For example, if MyMachine has a shared folder named
16767	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
16768	transient shared folder named <tt>C_DRIVE</tt> (that points
16769	to <tt>C:\\\\WINDOWS</tt>) will change the definition
16770	of <tt>C_DRIVE</tt> in the guest OS so
16771	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
16772	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
16773	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
16774	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
16775	to <tt>C:\\</tt> if it still exists.
16776
16777	Note that permanent and transient shared folders of different machines
16778	are in different name spaces, so they don't overlap and don't need to
16779	have unique logical names.
16780
16781	<note>
16782	Global shared folders are not implemented in the current version of the
16783	product.
16784	</note>
16785	</desc>
16786
16787	<attribute name="name" type="wstring" readonly="yes">
16788	<desc>Logical name of the shared folder.</desc>
16789	</attribute>
16790
16791	<attribute name="hostPath" type="wstring" readonly="yes">
16792	<desc>Full path to the shared folder in the host file system.</desc>
16793	</attribute>
16794
16795	<attribute name="accessible" type="boolean" readonly="yes">
16796	<desc>
16797	Whether the folder defined by the host path is currently
16798	accessible or not.
16799	For example, the folder can be inaccessible if it is placed
16800	on the network share that is not available by the time
16801	this property is read.
16802	</desc>
16803	</attribute>
16804
16805	<attribute name="writable" type="boolean" readonly="yes">
16806	<desc>
16807	Whether the folder defined by the host path is writable or
16808	not.
16809	</desc>
16810	</attribute>
16811
16812	<attribute name="autoMount" type="boolean" readonly="yes">
16813	<desc>
16814	Whether the folder gets automatically mounted by the guest or not.
16815	</desc>
16816	</attribute>
16817
16818	<attribute name="lastAccessError" type="wstring" readonly="yes">
16819	<desc>
16820	Text message that represents the result of the last accessibility
16821	check.
16822
16823	Accessibility checks are performed each time the <link to="#accessible"/>
16824	attribute is read. An empty string is returned if the last
16825	accessibility check was successful. A non-empty string indicates a
16826	failure and should normally describe a reason of the failure (for
16827	example, a file read error).
16828	</desc>
16829	</attribute>
16830
16831	</interface>
16832
16833	<!--
16834	// ISession
16835	/////////////////////////////////////////////////////////////////////////
16836	-->
16837
16838	<interface
16839	name="IInternalSessionControl" extends="$unknown"
16840	uuid="0ba8d8b3-204b-448e-99c2-242eaa666ea8"
16841	internal="yes"
16842	wsmap="suppress"
16843	>
16844	<method name="getPID">
16845	<desc>PID of the process that has created this Session object.
16846	</desc>
16847	<param name="pid" type="unsigned long" dir="return"/>
16848	</method>
16849
16850	<method name="getRemoteConsole">
16851	<desc>
16852	Returns the console object suitable for remote control.
16853
16854	<result name="VBOX_E_INVALID_VM_STATE">
16855	Session state prevents operation.
16856	</result>
16857	<result name="VBOX_E_INVALID_OBJECT_STATE">
16858	Session type prevents operation.
16859	</result>
16860
16861	</desc>
16862	<param name="console" type="IConsole" dir="return"/>
16863	</method>
16864
16865	<method name="assignMachine">
16866	<desc>
16867	Assigns the machine object associated with this direct-type
16868	session or informs the session that it will be a remote one
16869	(if @a machine == @c null).
16870
16871	<result name="VBOX_E_INVALID_VM_STATE">
16872	Session state prevents operation.
16873	</result>
16874	<result name="VBOX_E_INVALID_OBJECT_STATE">
16875	Session type prevents operation.
16876	</result>
16877
16878	</desc>
16879	<param name="machine" type="IMachine" dir="in"/>
16880	<param name="lockType" type="LockType" dir="in"/>
16881	</method>
16882
16883	<method name="assignRemoteMachine">
16884	<desc>
16885	Assigns the machine and the (remote) console object associated with
16886	this remote-type session.
16887
16888	<result name="VBOX_E_INVALID_VM_STATE">
16889	Session state prevents operation.
16890	</result>
16891
16892	</desc>
16893	<param name="machine" type="IMachine" dir="in"/>
16894	<param name="console" type="IConsole" dir="in"/>
16895	</method>
16896
16897	<method name="updateMachineState">
16898	<desc>
16899	Updates the machine state in the VM process.
16900	Must be called only in certain cases
16901	(see the method implementation).
16902
16903	<result name="VBOX_E_INVALID_VM_STATE">
16904	Session state prevents operation.
16905	</result>
16906	<result name="VBOX_E_INVALID_OBJECT_STATE">
16907	Session type prevents operation.
16908	</result>
16909
16910	</desc>
16911	<param name="machineState" type="MachineState" dir="in"/>
16912	</method>
16913
16914	<method name="uninitialize">
16915	<desc>
16916	Uninitializes (closes) this session. Used by VirtualBox to close
16917	the corresponding remote session when the direct session dies
16918	or gets closed.
16919
16920	<result name="VBOX_E_INVALID_VM_STATE">
16921	Session state prevents operation.
16922	</result>
16923
16924	</desc>
16925	</method>
16926
16927	<method name="onNetworkAdapterChange">
16928	<desc>
16929	Triggered when settings of a network adapter of the
16930	associated virtual machine have changed.
16931
16932	<result name="VBOX_E_INVALID_VM_STATE">
16933	Session state prevents operation.
16934	</result>
16935	<result name="VBOX_E_INVALID_OBJECT_STATE">
16936	Session type prevents operation.
16937	</result>
16938
16939	</desc>
16940	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
16941	<param name="changeAdapter" type="boolean" dir="in"/>
16942	</method>
16943
16944	<method name="onSerialPortChange">
16945	<desc>
16946	Triggered when settings of a serial port of the
16947	associated virtual machine have changed.
16948
16949	<result name="VBOX_E_INVALID_VM_STATE">
16950	Session state prevents operation.
16951	</result>
16952	<result name="VBOX_E_INVALID_OBJECT_STATE">
16953	Session type prevents operation.
16954	</result>
16955
16956	</desc>
16957	<param name="serialPort" type="ISerialPort" dir="in"/>
16958	</method>
16959
16960	<method name="onParallelPortChange">
16961	<desc>
16962	Triggered when settings of a parallel port of the
16963	associated virtual machine have changed.
16964
16965	<result name="VBOX_E_INVALID_VM_STATE">
16966	Session state prevents operation.
16967	</result>
16968	<result name="VBOX_E_INVALID_OBJECT_STATE">
16969	Session type prevents operation.
16970	</result>
16971
16972	</desc>
16973	<param name="parallelPort" type="IParallelPort" dir="in"/>
16974	</method>
16975
16976	<method name="onStorageControllerChange">
16977	<desc>
16978	Triggered when settings of a storage controller of the
16979	associated virtual machine have changed.
16980
16981	<result name="VBOX_E_INVALID_VM_STATE">
16982	Session state prevents operation.
16983	</result>
16984	<result name="VBOX_E_INVALID_OBJECT_STATE">
16985	Session type prevents operation.
16986	</result>
16987
16988	</desc>
16989	</method>
16990
16991	<method name="onMediumChange">
16992	<desc>
16993	Triggered when attached media of the
16994	associated virtual machine have changed.
16995
16996	<result name="VBOX_E_INVALID_VM_STATE">
16997	Session state prevents operation.
16998	</result>
16999	<result name="VBOX_E_INVALID_OBJECT_STATE">
17000	Session type prevents operation.
17001	</result>
17002
17003	</desc>
17004
17005	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17006	<desc>The medium attachment which changed.</desc>
17007	</param>
17008	<param name="force" type="boolean" dir="in">
17009	<desc>If the medium change was forced.</desc>
17010	</param>
17011	</method>
17012
17013	<method name="onStorageDeviceChange">
17014	<desc>
17015	Triggered when attached storage devices of the
17016	associated virtual machine have changed.
17017
17018	<result name="VBOX_E_INVALID_VM_STATE">
17019	Session state prevents operation.
17020	</result>
17021	<result name="VBOX_E_INVALID_OBJECT_STATE">
17022	Session type prevents operation.
17023	</result>
17024
17025	</desc>
17026
17027	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17028	<desc>The medium attachment which changed.</desc>
17029	</param>
17030	<param name="remove" type="boolean" dir="in">
17031	<desc>TRUE if the device is removed, FALSE if it was added.</desc>
17032	</param>
17033	<param name="silent" type="boolean" dir="in">
17034	<desc>TRUE if the device is is silently reconfigured without
17035	notifying the guest about it.</desc>
17036	</param>
17037	</method>
17038
17039	<method name="onClipboardModeChange">
17040	<desc>
17041	Notification when the shared clipboard mode changes.
17042	</desc>
17043	<param name="clipboardMode" type="ClipboardMode" dir="in">
17044	<desc>The new shared clipboard mode.</desc>
17045	</param>
17046	</method>
17047
17048	<method name="onDragAndDropModeChange">
17049	<desc>
17050	Notification when the drag'n'drop mode changes.
17051	</desc>
17052	<param name="dragAndDropMode" type="DragAndDropMode" dir="in">
17053	<desc>The new mode for drag'n'drop.</desc>
17054	</param>
17055	</method>
17056
17057	<method name="onCPUChange">
17058	<desc>
17059	Notification when a CPU changes.
17060	</desc>
17061	<param name="cpu" type="unsigned long" dir="in">
17062	<desc>The CPU which changed</desc>
17063	</param>
17064	<param name="add" type="boolean" dir="in">
17065	<desc>Flag whether the CPU was added or removed</desc>
17066	</param>
17067	</method>
17068
17069	<method name="onCPUExecutionCapChange">
17070	<desc>
17071	Notification when the CPU execution cap changes.
17072	</desc>
17073	<param name="executionCap" type="unsigned long" dir="in">
17074	<desc>The new CPU execution cap value. (1-100)</desc>
17075	</param>
17076	</method>
17077
17078	<method name="onVRDEServerChange">
17079	<desc>
17080	Triggered when settings of the VRDE server object of the
17081	associated virtual machine have changed.
17082
17083	<result name="VBOX_E_INVALID_VM_STATE">
17084	Session state prevents operation.
17085	</result>
17086	<result name="VBOX_E_INVALID_OBJECT_STATE">
17087	Session type prevents operation.
17088	</result>
17089
17090	</desc>
17091	<param name="restart" type="boolean" dir="in">
17092	<desc>Flag whether the server must be restarted</desc>
17093	</param>
17094	</method>
17095
17096	<method name="onVideoCaptureChange">
17097	<desc>
17098	Triggered when video capture settings have changed.
17099	</desc>
17100	</method>
17101
17102	<method name="onUSBControllerChange">
17103	<desc>
17104	Triggered when settings of the USB controller object of the
17105	associated virtual machine have changed.
17106
17107	<result name="VBOX_E_INVALID_VM_STATE">
17108	Session state prevents operation.
17109	</result>
17110	<result name="VBOX_E_INVALID_OBJECT_STATE">
17111	Session type prevents operation.
17112	</result>
17113
17114	</desc>
17115	</method>
17116
17117	<method name="onSharedFolderChange">
17118	<desc>
17119	Triggered when a permanent (global or machine) shared folder has been
17120	created or removed.
17121	<note>
17122	We don't pass shared folder parameters in this notification because
17123	the order in which parallel notifications are delivered is not defined,
17124	therefore it could happen that these parameters were outdated by the
17125	time of processing this notification.
17126	</note>
17127
17128	<result name="VBOX_E_INVALID_VM_STATE">
17129	Session state prevents operation.
17130	</result>
17131	<result name="VBOX_E_INVALID_OBJECT_STATE">
17132	Session type prevents operation.
17133	</result>
17134
17135	</desc>
17136	<param name="global" type="boolean" dir="in"/>
17137	</method>
17138
17139	<method name="onUSBDeviceAttach">
17140	<desc>
17141	Triggered when a request to capture a USB device (as a result
17142	of matched USB filters or direct call to
17143	<link to="IConsole::attachUSBDevice"/>) has completed.
17144	A @c null @a error object means success, otherwise it
17145	describes a failure.
17146
17147	<result name="VBOX_E_INVALID_VM_STATE">
17148	Session state prevents operation.
17149	</result>
17150	<result name="VBOX_E_INVALID_OBJECT_STATE">
17151	Session type prevents operation.
17152	</result>
17153
17154	</desc>
17155	<param name="device" type="IUSBDevice" dir="in"/>
17156	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17157	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
17158	</method>
17159
17160	<method name="onUSBDeviceDetach">
17161	<desc>
17162	Triggered when a request to release the USB device (as a result
17163	of machine termination or direct call to
17164	<link to="IConsole::detachUSBDevice"/>) has completed.
17165	A @c null @a error object means success, otherwise it
17166	describes a failure.
17167
17168	<result name="VBOX_E_INVALID_VM_STATE">
17169	Session state prevents operation.
17170	</result>
17171	<result name="VBOX_E_INVALID_OBJECT_STATE">
17172	Session type prevents operation.
17173	</result>
17174
17175	</desc>
17176	<param name="id" type="uuid" mod="string" dir="in"/>
17177	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17178	</method>
17179
17180	<method name="onShowWindow">
17181	<desc>
17182	Called by <link to="IMachine::canShowConsoleWindow"/> and by
17183	<link to="IMachine::showConsoleWindow"/> in order to notify
17184	console listeners
17185	<link to="ICanShowWindowEvent"/>
17186	and <link to="IShowWindowEvent"/>.
17187
17188	<result name="VBOX_E_INVALID_OBJECT_STATE">
17189	Session type prevents operation.
17190	</result>
17191
17192	</desc>
17193	<param name="check" type="boolean" dir="in"/>
17194	<param name="canShow" type="boolean" dir="out"/>
17195	<param name="winId" type="long long" dir="out"/>
17196	</method>
17197
17198	<method name="onBandwidthGroupChange">
17199	<desc>
17200	Notification when one of the bandwidth groups change.
17201	</desc>
17202	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
17203	<desc>The bandwidth group which changed.</desc>
17204	</param>
17205	</method>
17206
17207	<method name="accessGuestProperty">
17208	<desc>
17209	Called by <link to="IMachine::getGuestProperty"/> and by
17210	<link to="IMachine::setGuestProperty"/> in order to read and
17211	modify guest properties.
17212
17213	<result name="VBOX_E_INVALID_VM_STATE">
17214	Machine session is not open.
17215	</result>
17216	<result name="VBOX_E_INVALID_OBJECT_STATE">
17217	Session type is not direct.
17218	</result>
17219
17220	</desc>
17221	<param name="name" type="wstring" dir="in"/>
17222	<param name="value" type="wstring" dir="in"/>
17223	<param name="flags" type="wstring" dir="in"/>
17224	<param name="isSetter" type="boolean" dir="in"/>
17225	<param name="retValue" type="wstring" dir="out"/>
17226	<param name="retTimestamp" type="long long" dir="out"/>
17227	<param name="retFlags" type="wstring" dir="out"/>
17228	</method>
17229
17230	<method name="enumerateGuestProperties" const="yes">
17231	<desc>
17232	Return a list of the guest properties matching a set of patterns along
17233	with their values, time stamps and flags.
17234
17235	<result name="VBOX_E_INVALID_VM_STATE">
17236	Machine session is not open.
17237	</result>
17238	<result name="VBOX_E_INVALID_OBJECT_STATE">
17239	Session type is not direct.
17240	</result>
17241
17242	</desc>
17243	<param name="patterns" type="wstring" dir="in">
17244	<desc>
17245	The patterns to match the properties against as a comma-separated
17246	string. If this is empty, all properties currently set will be
17247	returned.
17248	</desc>
17249	</param>
17250	<param name="keys" type="wstring" dir="out" safearray="yes">
17251	<desc>
17252	The key names of the properties returned.
17253	</desc>
17254	</param>
17255	<param name="values" type="wstring" dir="out" safearray="yes">
17256	<desc>
17257	The values of the properties returned. The array entries match the
17258	corresponding entries in the @a key array.
17259	</desc>
17260	</param>
17261	<param name="timestamps" type="long long" dir="out" safearray="yes">
17262	<desc>
17263	The time stamps of the properties returned. The array entries match
17264	the corresponding entries in the @a key array.
17265	</desc>
17266	</param>
17267	<param name="flags" type="wstring" dir="out" safearray="yes">
17268	<desc>
17269	The flags of the properties returned. The array entries match the
17270	corresponding entries in the @a key array.
17271	</desc>
17272	</param>
17273	</method>
17274
17275	<method name="onlineMergeMedium">
17276	<desc>
17277	Triggers online merging of a hard disk. Used internally when deleting
17278	a snapshot while a VM referring to the same hard disk chain is running.
17279
17280	<result name="VBOX_E_INVALID_VM_STATE">
17281	Machine session is not open.
17282	</result>
17283	<result name="VBOX_E_INVALID_OBJECT_STATE">
17284	Session type is not direct.
17285	</result>
17286
17287	</desc>
17288	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17289	<desc>The medium attachment to identify the medium chain.</desc>
17290	</param>
17291	<param name="sourceIdx" type="unsigned long" dir="in">
17292	<desc>The index of the source image in the chain.
17293	Redundant, but drastically reduces IPC.</desc>
17294	</param>
17295	<param name="targetIdx" type="unsigned long" dir="in">
17296	<desc>The index of the target image in the chain.
17297	Redundant, but drastically reduces IPC.</desc>
17298	</param>
17299	<param name="source" type="IMedium" dir="in">
17300	<desc>Merge source medium.</desc>
17301	</param>
17302	<param name="target" type="IMedium" dir="in">
17303	<desc>Merge target medium.</desc>
17304	</param>
17305	<param name="mergeForward" type="boolean" dir="in">
17306	<desc>Merge direction.</desc>
17307	</param>
17308	<param name="parentForTarget" type="IMedium" dir="in">
17309	<desc>For forward merges: new parent for target medium.</desc>
17310	</param>
17311	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
17312	<desc>For backward merges: list of media which need their parent UUID
17313	updated.</desc>
17314	</param>
17315	<param name="progress" type="IProgress" dir="in">
17316	<desc>
17317	Progress object for this operation.
17318	</desc>
17319	</param>
17320	</method>
17321
17322	<method name="enableVMMStatistics">
17323	<desc>
17324	Enables or disables collection of VMM RAM statistics.
17325
17326	<result name="VBOX_E_INVALID_VM_STATE">
17327	Machine session is not open.
17328	</result>
17329	<result name="VBOX_E_INVALID_OBJECT_STATE">
17330	Session type is not direct.
17331	</result>
17332
17333	</desc>
17334	<param name="enable" type="boolean" dir="in">
17335	<desc>True enables statistics collection.</desc>
17336	</param>
17337	</method>
17338
17339	</interface>
17340
17341	<interface
17342	name="ISession" extends="$unknown"
17343	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
17344	wsmap="managed"
17345	>
17346	<desc>
17347	The ISession interface represents a client process and allows for locking
17348	virtual machines (represented by IMachine objects) to prevent conflicting
17349	changes to the machine.
17350
17351	Any caller wishing to manipulate a virtual machine needs to create a session
17352	object first, which lives in its own process space. Such session objects are
17353	then associated with <link to="IMachine" /> objects living in the VirtualBox
17354	server process to coordinate such changes.
17355
17356	There are two typical scenarios in which sessions are used:
17357
17358	<ul>
17359	<li>To alter machine settings or control a running virtual machine, one
17360	needs to lock a machine for a given session (client process) by calling
17361	<link to="IMachine::lockMachine"/>.
17362
17363	Whereas multiple sessions may control a running virtual machine, only
17364	one process can obtain a write lock on the machine to prevent conflicting
17365	changes. A write lock is also needed if a process wants to actually run a
17366	virtual machine in its own context, such as the VirtualBox GUI or
17367	VBoxHeadless front-ends. They must also lock a machine for their own
17368	sessions before they are allowed to power up the virtual machine.
17369
17370	As a result, no machine settings can be altered while another process is
17371	already using it, either because that process is modifying machine settings
17372	or because the machine is running.
17373	</li>
17374	<li>
17375	To start a VM using one of the existing VirtualBox front-ends (e.g. the
17376	VirtualBox GUI or VBoxHeadless), one would use
17377	<link to="IMachine::launchVMProcess"/>, which also takes a session object
17378	as its first parameter. This session then identifies the caller and lets the
17379	caller control the started machine (for example, pause machine execution or
17380	power it down) as well as be notified about machine execution state changes.
17381	</li>
17382	</ul>
17383
17384	How sessions objects are created in a client process depends on whether you use
17385	the Main API via COM or via the webservice:
17386
17387	<ul>
17388	<li>When using the COM API directly, an object of the Session class from the
17389	VirtualBox type library needs to be created. In regular COM C++ client code,
17390	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
17391	This object will then act as a local session object in further calls to open
17392	a session.
17393	</li>
17394
17395	<li>In the webservice, the session manager (IWebsessionManager) instead creates
17396	a session object automatically whenever <link to="IWebsessionManager::logon" />
17397	is called. A managed object reference to that session object can be retrieved by
17398	calling <link to="IWebsessionManager::getSessionObject" />.
17399	</li>
17400	</ul>
17401	</desc>
17402
17403	<attribute name="state" type="SessionState" readonly="yes">
17404	<desc>Current state of this session.</desc>
17405	</attribute>
17406
17407	<attribute name="type" type="SessionType" readonly="yes">
17408	<desc>
17409	Type of this session. The value of this attribute is valid only
17410	if the session currently has a machine locked (i.e. its
17411	<link to="#state" /> is Locked), otherwise an error will be returned.
17412	</desc>
17413	</attribute>
17414
17415	<attribute name="machine" type="IMachine" readonly="yes">
17416	<desc>Machine object associated with this session.</desc>
17417	</attribute>
17418
17419	<attribute name="console" type="IConsole" readonly="yes">
17420	<desc>Console object associated with this session.</desc>
17421	</attribute>
17422
17423	<method name="unlockMachine">
17424	<desc>
17425	Unlocks a machine that was previously locked for the current session.
17426
17427	Calling this method is required every time a machine has been locked
17428	for a particular session using the <link to="IMachine::launchVMProcess" />
17429	or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
17430	the machine will be set to <link to="MachineState_Aborted" /> on the
17431	server, and changes made to the machine settings will be lost.
17432
17433	Generally, it is recommended to unlock all machines explicitly
17434	before terminating the application (regardless of the reason for
17435	the termination).
17436
17437	<note>
17438	Do not expect the session state (<link to="ISession::state" />
17439	to return to "Unlocked" immediately after you invoke this method,
17440	particularly if you have started a new VM process. The session
17441	state will automatically return to "Unlocked" once the VM is no
17442	longer executing, which can of course take a very long time.
17443	</note>
17444
17445	<result name="E_UNEXPECTED">
17446	Session is not locked.
17447	</result>
17448
17449	</desc>
17450	</method>
17451
17452	</interface>
17453
17454	<!--
17455	// IStorageController
17456	/////////////////////////////////////////////////////////////////////////
17457	-->
17458
17459	<enum
17460	name="StorageBus"
17461	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
17462	>
17463	<desc>
17464	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
17465	see <link to="IStorageController::bus" />.
17466	</desc>
17467	<const name="Null" value="0">
17468	<desc>@c null value. Never used by the API.</desc>
17469	</const>
17470	<const name="IDE" value="1"/>
17471	<const name="SATA" value="2"/>
17472	<const name="SCSI" value="3"/>
17473	<const name="Floppy" value="4"/>
17474	<const name="SAS" value="5"/>
17475	</enum>
17476
17477	<enum
17478	name="StorageControllerType"
17479	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
17480	>
17481	<desc>
17482	The exact variant of storage controller hardware presented
17483	to the guest; see <link to="IStorageController::controllerType" />.
17484	</desc>
17485
17486	<const name="Null" value="0">
17487	<desc>@c null value. Never used by the API.</desc>
17488	</const>
17489	<const name="LsiLogic" value="1">
17490	<desc>A SCSI controller of the LsiLogic variant.</desc>
17491	</const>
17492	<const name="BusLogic" value="2">
17493	<desc>A SCSI controller of the BusLogic variant.</desc>
17494	</const>
17495	<const name="IntelAhci" value="3">
17496	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
17497	</const>
17498	<const name="PIIX3" value="4">
17499	<desc>An IDE controller of the PIIX3 variant.</desc>
17500	</const>
17501	<const name="PIIX4" value="5">
17502	<desc>An IDE controller of the PIIX4 variant.</desc>
17503	</const>
17504	<const name="ICH6" value="6">
17505	<desc>An IDE controller of the ICH6 variant.</desc>
17506	</const>
17507	<const name="I82078" value="7">
17508	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
17509	</const>
17510	<const name="LsiLogicSas" value="8">
17511	<desc>A variant of the LsiLogic controller using SAS.</desc>
17512	</const>
17513	</enum>
17514
17515	<enum
17516	name="ChipsetType"
17517	uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
17518	>
17519	<desc>
17520	Type of emulated chipset (mostly southbridge).
17521	</desc>
17522
17523	<const name="Null" value="0">
17524	<desc>@c null value. Never used by the API.</desc>
17525	</const>
17526	<const name="PIIX3" value="1">
17527	<desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
17528	</const>
17529	<const name="ICH9" value="2">
17530	<desc>A ICH9 (I/O Controller Hub) chipset.</desc>
17531	</const>
17532	</enum>
17533
17534	<interface
17535	name="IStorageController" extends="$unknown"
17536	uuid="a1556333-09b6-46d9-bfb7-fc239b7fbe1e"
17537	wsmap="managed"
17538	>
17539	<desc>
17540	Represents a storage controller that is attached to a virtual machine
17541	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
17542	attached to storage controllers in a real computer, virtual drives
17543	(represented by <link to="IMediumAttachment" />) are attached to virtual
17544	storage controllers, represented by this interface.
17545
17546	As opposed to physical hardware, VirtualBox has a very generic concept
17547	of a storage controller, and for purposes of the Main API, all virtual
17548	storage is attached to virtual machines via instances of this interface.
17549	There are five types of such virtual storage controllers: IDE, SCSI, SATA,
17550	SAS and Floppy (see <link to="#bus" />). Depending on which of these four
17551	is used, certain sub-types may be available and can be selected in
17552	<link to="#controllerType" />.
17553
17554	Depending on these settings, the guest operating system might see
17555	significantly different virtual hardware.
17556	</desc>
17557
17558	<attribute name="name" type="wstring" readonly="yes">
17559	<desc>
17560	Name of the storage controller, as originally specified with
17561	<link to="IMachine::addStorageController" />. This then uniquely
17562	identifies this controller with other method calls such as
17563	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
17564	</desc>
17565	</attribute>
17566
17567	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
17568	<desc>
17569	Maximum number of devices which can be attached to one port.
17570	</desc>
17571	</attribute>
17572
17573	<attribute name="minPortCount" type="unsigned long" readonly="yes">
17574	<desc>
17575	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
17576	</desc>
17577	</attribute>
17578
17579	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
17580	<desc>
17581	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
17582	</desc>
17583	</attribute>
17584
17585	<attribute name="instance" type="unsigned long">
17586	<desc>
17587	The instance number of the device in the running VM.
17588	</desc>
17589	</attribute>
17590
17591	<attribute name="portCount" type="unsigned long">
17592	<desc>
17593	The number of currently usable ports on the controller.
17594	The minimum and maximum number of ports for one controller are
17595	stored in <link to="IStorageController::minPortCount"/>
17596	and <link to="IStorageController::maxPortCount"/>.
17597	</desc>
17598	</attribute>
17599
17600	<attribute name="bus" type="StorageBus" readonly="yes">
17601	<desc>
17602	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
17603	</desc>
17604	</attribute>
17605
17606	<attribute name="controllerType" type="StorageControllerType">
17607	<desc>
17608	The exact variant of storage controller hardware presented
17609	to the guest.
17610	Depending on this value, VirtualBox will provide a different
17611	virtual storage controller hardware to the guest.
17612	For SATA, SAS and floppy controllers, only one variant is
17613	available, but for IDE and SCSI, there are several.
17614
17615	For SCSI controllers, the default type is LsiLogic.
17616	</desc>
17617	</attribute>
17618
17619	<attribute name="useHostIOCache" type="boolean">
17620	<desc>
17621	If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
17622	caches and use synchronous file APIs on the host. This was the only option in the API before
17623	VirtualBox 3.2 and is still the default for IDE controllers.
17624
17625	If false, the host I/O cache will be disabled for image files attached to this storage controller.
17626	Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
17627	it possible to turn off the host I/O caches because the emulation can handle unaligned access to
17628	the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
17629	virtual machines are running at the same time to prevent I/O cache related hangs.
17630	This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
17631	</desc>
17632	</attribute>
17633
17634	<attribute name="bootable" type="boolean" readonly="yes">
17635	<desc>
17636	Returns whether it is possible to boot from disks attached to this controller.
17637	</desc>
17638	</attribute>
17639	</interface>
17640
17641	<if target="wsdl">
17642
17643	<!--
17644	// IManagedObjectRef
17645	/////////////////////////////////////////////////////////////////////////
17646	-->
17647
17648	<interface
17649	name="IManagedObjectRef" extends="$unknown"
17650	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
17651	internal="yes"
17652	wsmap="managed"
17653	wscpp="hardcoded"
17654	>
17655	<desc>
17656	Managed object reference.
17657
17658	Only within the webservice, a managed object reference (which is really
17659	an opaque number) allows a webservice client to address an object
17660	that lives in the address space of the webservice server.
17661
17662	Behind each managed object reference, there is a COM object that lives
17663	in the webservice server's address space. The COM object is not freed
17664	until the managed object reference is released, either by an explicit
17665	call to <link to="IManagedObjectRef::release" /> or by logging off from
17666	the webservice (<link to="IWebsessionManager::logoff" />), which releases
17667	all objects created during the webservice session.
17668
17669	Whenever a method call of the VirtualBox API returns a COM object, the
17670	webservice representation of that method will instead return a
17671	managed object reference, which can then be used to invoke methods
17672	on that object.
17673	</desc>
17674
17675	<method name="getInterfaceName">
17676	<desc>
17677	Returns the name of the interface that this managed object represents,
17678	for example, "IMachine", as a string.
17679	</desc>
17680	<param name="return" type="wstring" dir="return"/>
17681	</method>
17682
17683	<method name="release">
17684	<desc>
17685	Releases this managed object reference and frees the resources that
17686	were allocated for it in the webservice server process. After calling
17687	this method, the identifier of the reference can no longer be used.
17688	</desc>
17689	</method>
17690
17691	</interface>
17692
17693	<!--
17694	// IWebsessionManager
17695	/////////////////////////////////////////////////////////////////////////
17696	-->
17697
17698	<interface
17699	name="IWebsessionManager" extends="$unknown"
17700	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
17701	internal="yes"
17702	wsmap="global"
17703	wscpp="hardcoded"
17704	>
17705	<desc>
17706	Websession manager. This provides essential services
17707	to webservice clients.
17708	</desc>
17709	<method name="logon">
17710	<desc>
17711	Logs a new client onto the webservice and returns a managed object reference to
17712	the IVirtualBox instance, which the client can then use as a basis to further
17713	queries, since all calls to the VirtualBox API are based on the IVirtualBox
17714	interface, in one way or the other.
17715	</desc>
17716	<param name="username" type="wstring" dir="in"/>
17717	<param name="password" type="wstring" dir="in"/>
17718	<param name="return" type="IVirtualBox" dir="return"/>
17719	</method>
17720
17721	<method name="getSessionObject">
17722	<desc>
17723	Returns a managed object reference to the internal ISession object that was created
17724	for this web service session when the client logged on.
17725
17726	<see><link to="ISession"/></see>
17727	</desc>
17728	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17729	<param name="return" type="ISession" dir="return"/>
17730	</method>
17731
17732	<method name="logoff">
17733	<desc>
17734	Logs off the client who has previously logged on with <link to="IWebsessionManager::logon" />
17735	and destroys all resources associated with the session (most importantly, all
17736	managed objects created in the server while the session was active).
17737	</desc>
17738	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17739	</method>
17740
17741	</interface>
17742
17743	</if>
17744
17745	<!--
17746	// IPerformanceCollector & friends
17747	/////////////////////////////////////////////////////////////////////////
17748	-->
17749
17750	<interface
17751	name="IPerformanceMetric" extends="$unknown"
17752	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
17753	>
17754	<desc>
17755	The IPerformanceMetric interface represents parameters of the given
17756	performance metric.
17757	</desc>
17758
17759	<attribute name="metricName" type="wstring" readonly="yes">
17760	<desc>
17761	Name of the metric.
17762	</desc>
17763	</attribute>
17764
17765	<attribute name="object" type="$unknown" readonly="yes">
17766	<desc>
17767	Object this metric belongs to.
17768	</desc>
17769	</attribute>
17770
17771	<attribute name="description" type="wstring" readonly="yes">
17772	<desc>
17773	Textual description of the metric.
17774	</desc>
17775	</attribute>
17776
17777	<attribute name="period" type="unsigned long" readonly="yes">
17778	<desc>
17779	Time interval between samples, measured in seconds.
17780	</desc>
17781	</attribute>
17782
17783	<attribute name="count" type="unsigned long" readonly="yes">
17784	<desc>
17785	Number of recent samples retained by the performance collector for this
17786	metric.
17787
17788	When the collected sample count exceeds this number, older samples
17789	are discarded.
17790	</desc>
17791	</attribute>
17792
17793	<attribute name="unit" type="wstring" readonly="yes">
17794	<desc>
17795	Unit of measurement.
17796	</desc>
17797	</attribute>
17798
17799	<attribute name="minimumValue" type="long" readonly="yes">
17800	<desc>
17801	Minimum possible value of this metric.
17802	</desc>
17803	</attribute>
17804
17805	<attribute name="maximumValue" type="long" readonly="yes">
17806	<desc>
17807	Maximum possible value of this metric.
17808	</desc>
17809	</attribute>
17810	</interface>
17811
17812	<interface
17813	name="IPerformanceCollector" extends="$unknown"
17814	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
17815	wsmap="managed"
17816	>
17817	<desc>
17818	The IPerformanceCollector interface represents a service that collects
17819	and stores performance metrics data.
17820
17821	Performance metrics are associated with objects of interfaces like IHost
17822	and IMachine. Each object has a distinct set of performance metrics. The
17823	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
17824
17825	Metric data is collected at the specified intervals and is retained
17826	internally. The interval and the number of retained samples can be set
17827	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
17828	and collection settings are not persistent, they are discarded as soon as
17829	VBoxSVC process terminates. Moreover, metric settings and data associated
17830	with a particular VM only exist while VM is running. They disappear as
17831	soon as VM shuts down. It is not possible to set up metrics for machines
17832	that are powered off. One needs to start VM first, then set up metric
17833	collection parameters.
17834
17835	Metrics are organized hierarchically, with each level separated by a
17836	slash (/) character. Generally, the scheme for metric names is like this:
17837
17838	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
17839
17840	"Category/Metric" together form the base metric name. A base metric is
17841	the smallest unit for which a sampling interval and the number of
17842	retained samples can be set. Only base metrics can be enabled and
17843	disabled. All sub-metrics are collected when their base metric is
17844	collected. Collected values for any set of sub-metrics can be queried
17845	with <link to="IPerformanceCollector::queryMetricsData" />.
17846
17847	For example "CPU/Load/User:avg" metric name stands for the "CPU"
17848	category, "Load" metric, "User" submetric, "average" aggregate. An
17849	aggregate function is computed over all retained data. Valid aggregate
17850	functions are:
17851
17852	<ul>
17853	<li>avg -- average</li>
17854	<li>min -- minimum</li>
17855	<li>max -- maximum</li>
17856	</ul>
17857
17858	When setting up metric parameters, querying metric data, enabling or
17859	disabling metrics wildcards can be used in metric names to specify a
17860	subset of metrics. For example, to select all CPU-related metrics
17861	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
17862	so on. To query metric values without aggregates <tt>*:</tt> can be used.
17863
17864	The valid names for base metrics are:
17865
17866	<ul>
17867	<li>CPU/Load</li>
17868	<li>CPU/MHz</li>
17869	<li>RAM/Usage</li>
17870	<li>RAM/VMM</li>
17871	</ul>
17872
17873	The general sequence for collecting and retrieving the metrics is:
17874	<ul>
17875	<li>
17876	Obtain an instance of IPerformanceCollector with
17877	<link to="IVirtualBox::performanceCollector" />
17878	</li>
17879	<li>
17880	Allocate and populate an array with references to objects the metrics
17881	will be collected for. Use references to IHost and IMachine objects.
17882	</li>
17883	<li>
17884	Allocate and populate an array with base metric names the data will
17885	be collected for.
17886	</li>
17887	<li>
17888	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
17889	the metric data will be collected and stored.
17890	</li>
17891	<li>
17892	Wait for the data to get collected.
17893	</li>
17894	<li>
17895	Allocate and populate an array with references to objects the metric
17896	values will be queried for. You can re-use the object array used for
17897	setting base metrics.
17898	</li>
17899	<li>
17900	Allocate and populate an array with metric names the data will be
17901	collected for. Note that metric names differ from base metric names.
17902	</li>
17903	<li>
17904	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
17905	that have been collected so far are returned. Note that the values
17906	are still retained internally and data collection continues.
17907	</li>
17908	</ul>
17909
17910	For an example of usage refer to the following files in VirtualBox SDK:
17911	<ul>
17912	<li>
17913	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
17914	</li>
17915	<li>
17916	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
17917	</li>
17918	</ul>
17919	</desc>
17920
17921	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
17922	<desc>
17923	Array of unique names of metrics.
17924
17925	This array represents all metrics supported by the performance
17926	collector. Individual objects do not necessarily support all of them.
17927	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
17928	list of supported metrics for a particular object.
17929	</desc>
17930	</attribute>
17931
17932	<method name="getMetrics">
17933	<desc>
17934	Returns parameters of specified metrics for a set of objects.
17935	<note>
17936	@c Null metrics array means all metrics. @c Null object array means
17937	all existing objects.
17938	</note>
17939	</desc>
17940	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17941	<desc>
17942	Metric name filter. Currently, only a comma-separated list of metrics
17943	is supported.
17944	</desc>
17945	</param>
17946	<param name="objects" type="$unknown" dir="in" safearray="yes">
17947	<desc>
17948	Set of objects to return metric parameters for.
17949	</desc>
17950	</param>
17951	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
17952	<desc>
17953	Array of returned metric parameters.
17954	</desc>
17955	</param>
17956	</method>
17957
17958	<method name="setupMetrics">
17959	<desc>
17960	Sets parameters of specified base metrics for a set of objects. Returns
17961	an array of <link to="IPerformanceMetric" /> describing the metrics
17962	have been affected.
17963	<note>
17964	@c Null or empty metric name array means all metrics. @c Null or
17965	empty object array means all existing objects. If metric name array
17966	contains a single element and object array contains many, the single
17967	metric name array element is applied to each object array element to
17968	form metric/object pairs.
17969	</note>
17970	</desc>
17971	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17972	<desc>
17973	Metric name filter. Comma-separated list of metrics with wildcard
17974	support.
17975	</desc>
17976	</param>
17977	<param name="objects" type="$unknown" dir="in" safearray="yes">
17978	<desc>
17979	Set of objects to setup metric parameters for.
17980	</desc>
17981	</param>
17982	<param name="period" type="unsigned long" dir="in">
17983	<desc>
17984	Time interval in seconds between two consecutive samples of
17985	performance data.
17986	</desc>
17987	</param>
17988	<param name="count" type="unsigned long" dir="in">
17989	<desc>
17990	Number of samples to retain in performance data history. Older
17991	samples get discarded.
17992	</desc>
17993	</param>
17994	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
17995	<desc>
17996	Array of metrics that have been modified by the call to this method.
17997	</desc>
17998	</param>
17999	</method>
18000
18001	<method name="enableMetrics">
18002	<desc>
18003	Turns on collecting specified base metrics. Returns an array of
18004	<link to="IPerformanceMetric" /> describing the metrics have been
18005	affected.
18006	<note>
18007	@c Null or empty metric name array means all metrics. @c Null or
18008	empty object array means all existing objects. If metric name array
18009	contains a single element and object array contains many, the single
18010	metric name array element is applied to each object array element to
18011	form metric/object pairs.
18012	</note>
18013	</desc>
18014	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18015	<desc>
18016	Metric name filter. Comma-separated list of metrics with wildcard
18017	support.
18018	</desc>
18019	</param>
18020	<param name="objects" type="$unknown" dir="in" safearray="yes">
18021	<desc>
18022	Set of objects to enable metrics for.
18023	</desc>
18024	</param>
18025	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
18026	<desc>
18027	Array of metrics that have been modified by the call to this method.
18028	</desc>
18029	</param>
18030	</method>
18031
18032	<method name="disableMetrics">
18033	<desc>
18034	Turns off collecting specified base metrics. Returns an array of
18035	<link to="IPerformanceMetric" /> describing the metrics have been
18036	affected.
18037	<note>
18038	@c Null or empty metric name array means all metrics. @c Null or
18039	empty object array means all existing objects. If metric name array
18040	contains a single element and object array contains many, the single
18041	metric name array element is applied to each object array element to
18042	form metric/object pairs.
18043	</note>
18044	</desc>
18045	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18046	<desc>
18047	Metric name filter. Comma-separated list of metrics with wildcard
18048	support.
18049	</desc>
18050	</param>
18051	<param name="objects" type="$unknown" dir="in" safearray="yes">
18052	<desc>
18053	Set of objects to disable metrics for.
18054	</desc>
18055	</param>
18056	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
18057	<desc>
18058	Array of metrics that have been modified by the call to this method.
18059	</desc>
18060	</param>
18061	</method>
18062
18063	<method name="queryMetricsData">
18064	<desc>
18065	Queries collected metrics data for a set of objects.
18066
18067	The data itself and related metric information are returned in seven
18068	parallel and one flattened array of arrays. Elements of
18069	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
18070	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
18071	the same index describe one set of values corresponding to a single
18072	metric.
18073
18074	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
18075	start and length of a sub-array is indicated by
18076	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
18077	value for metric <tt>metricNames[i]</tt> is at
18078	<tt>returnData[returnIndices[i]]</tt>.
18079
18080	<note>
18081	@c Null or empty metric name array means all metrics. @c Null or
18082	empty object array means all existing objects. If metric name array
18083	contains a single element and object array contains many, the single
18084	metric name array element is applied to each object array element to
18085	form metric/object pairs.
18086	</note>
18087	<note>
18088	Data collection continues behind the scenes after call to @c
18089	queryMetricsData. The return data can be seen as the snapshot of the
18090	current state at the time of @c queryMetricsData call. The internally
18091	kept metric values are not cleared by the call. This makes possible
18092	querying different subsets of metrics or aggregates with subsequent
18093	calls. If periodic querying is needed it is highly suggested to query
18094	the values with @c interval*count period to avoid confusion. This way
18095	a completely new set of data values will be provided by each query.
18096	</note>
18097	</desc>
18098	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18099	<desc>
18100	Metric name filter. Comma-separated list of metrics with wildcard
18101	support.
18102	</desc>
18103	</param>
18104	<param name="objects" type="$unknown" dir="in" safearray="yes">
18105	<desc>
18106	Set of objects to query metrics for.
18107	</desc>
18108	</param>
18109	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
18110	<desc>
18111	Names of metrics returned in @c returnData.
18112	</desc>
18113	</param>
18114	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
18115	<desc>
18116	Objects associated with metrics returned in @c returnData.
18117	</desc>
18118	</param>
18119	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
18120	<desc>
18121	Units of measurement for each returned metric.
18122	</desc>
18123	</param>
18124	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
18125	<desc>
18126	Divisor that should be applied to return values in order to get
18127	floating point values. For example:
18128	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
18129	will retrieve the floating point value of i-th sample of the first
18130	metric.
18131	</desc>
18132	</param>
18133	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
18134	<desc>
18135	Sequence numbers of the first elements of value sequences of
18136	particular metrics returned in @c returnData. For aggregate metrics
18137	it is the sequence number of the sample the aggregate started
18138	calculation from.
18139	</desc>
18140	</param>
18141	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
18142	<desc>
18143	Indices of the first elements of value sequences of particular
18144	metrics returned in @c returnData.
18145	</desc>
18146	</param>
18147	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
18148	<desc>
18149	Lengths of value sequences of particular metrics.
18150	</desc>
18151	</param>
18152	<param name="returnData" type="long" dir="return" safearray="yes">
18153	<desc>
18154	Flattened array of all metric data containing sequences of values for
18155	each metric.
18156	</desc>
18157	</param>
18158	</method>
18159
18160	</interface>
18161
18162	<enum
18163	name="NATAliasMode"
18164	uuid="67772168-50d9-11df-9669-7fb714ee4fa1"
18165	>
18166	<desc></desc>
18167	<const name="AliasLog" value="0x1">
18168	<desc></desc>
18169	</const>
18170	<const name="AliasProxyOnly" value="0x02">
18171	<desc></desc>
18172	</const>
18173	<const name="AliasUseSamePorts" value="0x04">
18174	<desc></desc>
18175	</const>
18176	</enum>
18177
18178	<enum
18179	name="NATProtocol"
18180	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
18181	>
18182	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
18183	<const name="UDP" value="0">
18184	<desc>Port-forwarding uses UDP protocol.</desc>
18185	</const>
18186	<const name="TCP" value="1">
18187	<desc>Port-forwarding uses TCP protocol.</desc>
18188	</const>
18189	</enum>
18190
18191	<interface
18192	name="INATEngine" extends="$unknown"
18193	uuid="26451b99-3b2d-4dcb-8e4b-d63654218175"
18194	wsmap="managed"
18195	>
18196	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
18197	allows for changing NAT behavior such as port-forwarding rules. This interface is
18198	used in the <link to="INetworkAdapter::NATEngine" /> attribute.</desc>
18199	<attribute name="network" type="wstring">
18200	<desc>The network attribute of the NAT engine (the same value is used with built-in
18201	DHCP server to fill corresponding fields of DHCP leases).</desc>
18202	</attribute>
18203	<attribute name="hostIP" type="wstring">
18204	<desc>IP of host interface to bind all opened sockets to.
18205	<note>Changing this does not change binding of port forwarding.</note>
18206	</desc>
18207	</attribute>
18208	<attribute name="TFTPPrefix" type="wstring">
18209	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
18210	the corresponding fields of DHCP leases.</desc>
18211	</attribute>
18212	<attribute name="TFTPBootFile" type="wstring">
18213	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
18214	the corresponding fields of DHCP leases.</desc>
18215	</attribute>
18216	<attribute name="TFTPNextServer" type="wstring">
18217	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
18218	the corresponding fields of DHCP leases.
18219	<note>The preferred form is IPv4 addresses.</note>
18220	</desc>
18221	</attribute>
18222	<attribute name="aliasMode" type="unsigned long">
18223	<desc></desc>
18224	</attribute>
18225	<attribute name="DNSPassDomain" type="boolean">
18226	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
18227	</attribute>
18228	<attribute name="DNSProxy" type="boolean">
18229	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18230	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
18231	</attribute>
18232	<attribute name="DNSUseHostResolver" type="boolean">
18233	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18234	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
18235	</attribute>
18236	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
18237	<desc>Array of NAT port-forwarding rules in string representation, in the following
18238	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
18239	</attribute>
18240	<method name="setNetworkSettings">
18241	<desc>Sets network configuration of the NAT engine.</desc>
18242	<param name="mtu" type="unsigned long" dir="in">
18243	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
18244	</param>
18245	<param name="sockSnd" type="unsigned long" dir="in">
18246	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
18247	</param>
18248	<param name="sockRcv" type="unsigned long" dir="in">
18249	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
18250	</param>
18251	<param name="TcpWndSnd" type="unsigned long" dir="in">
18252	<desc>Initial size of the NAT engine's sending TCP window in bytes when
18253	establishing a new TCP connection.</desc>
18254	</param>
18255	<param name="TcpWndRcv" type="unsigned long" dir="in">
18256	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
18257	establishing a new TCP connection.</desc>
18258	</param>
18259	</method>
18260	<method name="getNetworkSettings">
18261	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
18262	for parameter descriptions.</desc>
18263	<param name="mtu" type="unsigned long" dir="out" />
18264	<param name="sockSnd" type="unsigned long" dir="out" />
18265	<param name="sockRcv" type="unsigned long" dir="out" />
18266	<param name="TcpWndSnd" type="unsigned long" dir="out" />
18267	<param name="TcpWndRcv" type="unsigned long" dir="out" />
18268	</method>
18269	<method name="addRedirect">
18270	<desc>Adds a new NAT port-forwarding rule.</desc>
18271	<param name="name" type="wstring" dir="in">
18272	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
18273	auto-generates one using the other parameters.</desc>
18274	</param>
18275	<param name="proto" type="NATProtocol" dir="in">
18276	<desc>Protocol handled with the rule.</desc>
18277	</param>
18278	<param name="hostIP" type="wstring" dir="in">
18279	<desc>IP of the host interface to which the rule should apply. An empty ip address is
18280	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
18281	</param>
18282	<param name="hostPort" type="unsigned short" dir="in">
18283	<desc>The port number to listen on.</desc>
18284	</param>
18285	<param name="guestIP" type="wstring" dir="in">
18286	<desc>The IP address of the guest which the NAT engine will forward matching packets
18287	to. An empty IP address is acceptable, in which case the NAT engine will forward
18288	packets to the first DHCP lease (x.x.x.15).</desc>
18289	</param>
18290	<param name="guestPort" type="unsigned short" dir="in">
18291	<desc>The port number to forward.</desc>
18292	</param>
18293	</method>
18294	<method name="removeRedirect">
18295	<desc>Removes a port-forwarding rule that was previously registered.</desc>
18296	<param name="name" type="wstring" dir="in">
18297	<desc>The name of the rule to delete.</desc>
18298	</param>
18299	</method>
18300	</interface>
18301
18302	<!--
18303	// IExtPackManager
18304	/////////////////////////////////////////////////////////////////////////
18305	-->
18306
18307	<interface
18308	name="IExtPackPlugIn" extends="$unknown"
18309	uuid="58000040-e718-4746-bbce-4b86d96da461"
18310	wsmap="suppress"
18311	>
18312	<desc>
18313	Interface for keeping information about a plug-in that ships with an
18314	extension pack.
18315	</desc>
18316	<attribute name="name" type="wstring" readonly="yes">
18317	<desc>The plug-in name.</desc>
18318	</attribute>
18319	<attribute name="description" type="wstring" readonly="yes">
18320	<desc>The plug-in description.</desc>
18321	</attribute>
18322	<attribute name="frontend" type="wstring" readonly="yes">
18323	<desc>
18324	The name of the frontend or component name this plug-in plugs into.
18325	</desc>
18326	</attribute>
18327	<attribute name="modulePath" type="wstring" readonly="yes">
18328	<desc> The module path. </desc>
18329	</attribute>
18330	</interface>
18331
18332	<interface
18333	name="IExtPackBase" extends="$unknown"
18334	uuid="f79b75d8-2890-4f34-ffff-ffffa144e82c"
18335	wsmap="suppress"
18336	>
18337	<desc>
18338	Interface for querying information about an extension pack as well as
18339	accessing COM objects within it.
18340	</desc>
18341	<attribute name="name" type="wstring" readonly="yes">
18342	<desc>The extension pack name. This is unique.</desc>
18343	</attribute>
18344	<attribute name="description" type="wstring" readonly="yes">
18345	<desc>The extension pack description.</desc>
18346	</attribute>
18347	<attribute name="version" type="wstring" readonly="yes">
18348	<desc>
18349	The extension pack version string. This is restricted to the dotted
18350	version number and optionally a build indicator. No tree revision or
18351	tag will be included in the string as those things are available as
18352	separate properties. An optional publisher tag may be present like for
18353	<link to="IVirtualBox::version"/>.
18354
18355	Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2".
18356	</desc>
18357	</attribute>
18358	<attribute name="revision" type="unsigned long" readonly="yes">
18359	<desc>The extension pack internal revision number.</desc>
18360	</attribute>
18361	<attribute name="edition" type="wstring" readonly="yes">
18362	<desc>
18363	Edition indicator. This is usually empty.
18364
18365	Can for instance be used to help distinguishing between two editions
18366	of the same extension pack where only the license, service contract or
18367	something differs.
18368	</desc>
18369	</attribute>
18370	<attribute name="VRDEModule" type="wstring" readonly="yes">
18371	<desc>The name of the VRDE module if the extension pack sports one.</desc>
18372	</attribute>
18373	<attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes">
18374	<desc>Plug-ins provided by this extension pack.</desc>
18375	</attribute>
18376	<attribute name="usable" type="boolean" readonly="yes">
18377	<desc>
18378	Indicates whether the extension pack is usable or not.
18379
18380	There are a number of reasons why an extension pack might be unusable,
18381	typical examples would be broken installation/file or that it is
18382	incompatible with the current VirtualBox version.
18383	</desc>
18384	</attribute>
18385	<attribute name="whyUnusable" type="wstring" readonly="yes">
18386	<desc>
18387	String indicating why the extension pack is not usable. This is an
18388	empty string if usable and always a non-empty string if not usable.
18389	</desc>
18390	</attribute>
18391	<attribute name="showLicense" type="boolean" readonly="yes">
18392	<desc>Whether to show the license before installation</desc>
18393	</attribute>
18394	<attribute name="license" type="wstring" readonly="yes">
18395	<desc>
18396	The default HTML license text for the extension pack. Same as
18397	calling <link to="#queryLicense">queryLicense</link> with
18398	preferredLocale and preferredLanguage as empty strings and format set
18399	to html.
18400	</desc>
18401	</attribute>
18402
18403	<method name="queryLicense">
18404	<desc>
18405	Full feature version of the license attribute.
18406	</desc>
18407	<param name="preferredLocale" type="wstring" dir="in">
18408	<desc>
18409	The preferred license locale. Pass an empty string to get the default
18410	license.
18411	</desc>
18412	</param>
18413	<param name="preferredLanguage" type="wstring" dir="in">
18414	<desc>
18415	The preferred license language. Pass an empty string to get the
18416	default language for the locale.
18417	</desc>
18418	</param>
18419	<param name="format" type="wstring" dir="in">
18420	<desc>
18421	The license format: html, rtf or txt. If a license is present there
18422	will always be an HTML of it, the rich text format (RTF) and plain
18423	text (txt) versions are optional. If
18424	</desc>
18425	</param>
18426	<param name="licenseText" type="wstring" dir="return">
18427	<desc>The license text.</desc>
18428	</param>
18429	</method>
18430
18431	</interface>
18432
18433	<interface
18434	name="IExtPack" extends="IExtPackBase"
18435	uuid="431685da-3618-4ebc-b038-833ba829b4b2"
18436	wsmap="suppress"
18437	>
18438	<desc>
18439	Interface for querying information about an extension pack as well as
18440	accessing COM objects within it.
18441	</desc>
18442	<method name="queryObject">
18443	<desc>
18444	Queries the IUnknown interface to an object in the extension pack
18445	main module. This allows plug-ins and others to talk directly to an
18446	extension pack.
18447	</desc>
18448	<param name="objUuid" type="wstring" dir="in">
18449	<desc>The object ID. What exactly this is </desc>
18450	</param>
18451	<param name="returnInterface" type="$unknown" dir="return">
18452	<desc>The queried interface.</desc>
18453	</param>
18454	</method>
18455	</interface>
18456
18457	<interface
18458	name="IExtPackFile" extends="IExtPackBase"
18459	uuid="b6b49f55-efcc-4f08-b486-56e8d8afb10b"
18460	wsmap="suppress"
18461	>
18462	<desc>
18463	Extension pack file (aka tarball, .vbox-extpack) representation returned
18464	by <link to="IExtPackManager::openExtPackFile"/>. This provides the base
18465	extension pack information with the addition of the file name.
18466	</desc>
18467	<attribute name="filePath" type="wstring" readonly="yes">
18468	<desc>
18469	The path to the extension pack file.
18470	</desc>
18471	</attribute>
18472
18473	<method name="install">
18474	<desc>
18475	Install the extension pack.
18476	</desc>
18477	<param name="replace" type="boolean" dir="in">
18478	<desc>
18479	Set this to automatically uninstall any existing extension pack with
18480	the same name as the one being installed.
18481	</desc>
18482	</param>
18483	<param name="displayInfo" type="wstring" dir="in">
18484	<desc>
18485	Platform specific display information. Reserved for future hacks.
18486	</desc>
18487	</param>
18488	<param name="progess" type="IProgress" dir="return">
18489	<desc>
18490	Progress object for the operation.
18491	</desc>
18492	</param>
18493	</method>
18494	</interface>
18495
18496	<interface
18497	name="IExtPackManager" extends="$unknown"
18498	uuid="3295e6ce-b051-47b2-9514-2c588bfe7554"
18499	wsmap="suppress"
18500	>
18501	<desc>
18502	Interface for managing VirtualBox Extension Packs.
18503
18504	TODO: Describe extension packs, how they are managed and how to create
18505	one.
18506	</desc>
18507
18508	<attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
18509	<desc>
18510	List of the installed extension packs.
18511	</desc>
18512	</attribute>
18513
18514	<method name="find">
18515	<desc>
18516	Returns the extension pack with the specified name if found.
18517
18518	<result name="VBOX_E_OBJECT_NOT_FOUND">
18519	No extension pack matching @a name was found.
18520	</result>
18521	</desc>
18522	<param name="name" type="wstring" dir="in">
18523	<desc>The name of the extension pack to locate.</desc>
18524	</param>
18525	<param name="returnData" type="IExtPack" dir="return">
18526	<desc>The extension pack if found.</desc>
18527	</param>
18528	</method>
18529
18530	<method name="openExtPackFile">
18531	<desc>
18532	Attempts to open an extension pack file in preparation for
18533	installation.
18534	</desc>
18535	<param name="path" type="wstring" dir="in">
18536	<desc>The path of the extension pack tarball. This can optionally be
18537	followed by a "::SHA-256=hex-digit" of the tarball. </desc>
18538	</param>
18539	<param name="file" type="IExtPackFile" dir="return">
18540	<desc>The interface of the extension pack file object.</desc>
18541	</param>
18542	</method>
18543
18544	<method name="uninstall">
18545	<desc>Uninstalls an extension pack, removing all related files.</desc>
18546	<param name="name" type="wstring" dir="in">
18547	<desc>The name of the extension pack to uninstall.</desc>
18548	</param>
18549	<param name="forcedRemoval" type="boolean" dir="in">
18550	<desc>
18551	Forced removal of the extension pack. This means that the uninstall
18552	hook will not be called.
18553	</desc>
18554	</param>
18555	<param name="displayInfo" type="wstring" dir="in">
18556	<desc>
18557	Platform specific display information. Reserved for future hacks.
18558	</desc>
18559	</param>
18560	<param name="progess" type="IProgress" dir="return">
18561	<desc>
18562	Progress object for the operation.
18563	</desc>
18564	</param>
18565	</method>
18566
18567	<method name="cleanup">
18568	<desc>Cleans up failed installs and uninstalls</desc>
18569	</method>
18570
18571	<method name="queryAllPlugInsForFrontend">
18572	<desc>
18573	Gets the path to all the plug-in modules for a given frontend.
18574
18575	This is a convenience method that is intended to simplify the plug-in
18576	loading process for a frontend.
18577	</desc>
18578	<param name="frontendName" type="wstring" dir="in">
18579	<desc>The name of the frontend or component.</desc>
18580	</param>
18581	<param name="plugInModules" type="wstring" dir="return" safearray="yes">
18582	<desc>Array containing the plug-in modules (full paths).</desc>
18583	</param>
18584	</method>
18585
18586	<method name="isExtPackUsable">
18587	<desc>Check if the given extension pack is loaded and usable.</desc>
18588	<param name="name" type="wstring" dir="in">
18589	<desc>The name of the extension pack to check for.</desc>
18590	</param>
18591	<param name="usable" type="boolean" dir="return">
18592	<desc>Is the given extension pack loaded and usable.</desc>
18593	</param>
18594	</method>
18595
18596	</interface>
18597
18598	<!--
18599	// BandwidthGroupType
18600	/////////////////////////////////////////////////////////////////////////
18601	-->
18602	<enum
18603	name="BandwidthGroupType"
18604	uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e">
18605
18606	<desc>
18607	Type of a bandwidth control group.
18608	</desc>
18609
18610	<const name="Null" value="0">
18611	<desc>
18612	Null type, must be first.
18613	</desc>
18614	</const>
18615
18616	<const name="Disk" value="1">
18617	<desc>
18618	The bandwidth group controls disk I/O.
18619	</desc>
18620	</const>
18621
18622	<const name="Network" value="2">
18623	<desc>
18624	The bandwidth group controls network I/O.
18625	</desc>
18626	</const>
18627
18628	</enum>
18629
18630	<!--
18631	// IBandwidthGroup
18632	/////////////////////////////////////////////////////////////////////////
18633	-->
18634	<interface
18635	name="IBandwidthGroup" extends="$unknown"
18636	uuid="badea2d7-0261-4146-89f0-6a57cc34833d"
18637	wsmap="managed"
18638	>
18639	<desc>Represents one bandwidth group.</desc>
18640
18641	<attribute name="name" type="wstring" readonly="yes">
18642	<desc>Name of the group.</desc>
18643	</attribute>
18644
18645	<attribute name="type" type="BandwidthGroupType" readonly="yes">
18646	<desc>Type of the group.</desc>
18647	</attribute>
18648
18649	<attribute name="reference" type="unsigned long" readonly="yes">
18650	<desc>How many devices/medium attachements use this group.</desc>
18651	</attribute>
18652
18653	<attribute name="maxBytesPerSec" type="long long">
18654	<desc>The maximum number of bytes which can be transfered by all
18655	entities attached to this group during one second.</desc>
18656	</attribute>
18657
18658	</interface>
18659
18660	<!--
18661	// IBandwidthControl
18662	/////////////////////////////////////////////////////////////////////////
18663	-->
18664	<interface
18665	name="IBandwidthControl" extends="$unknown"
18666	uuid="e2eb3930-d2f4-4f87-be17-0707e30f019f"
18667	wsmap="managed"
18668	>
18669	<desc>
18670	Controls the bandwidth groups of one machine used to cap I/O done by a VM.
18671	This includes network and disk I/O.
18672	</desc>
18673
18674	<attribute name="numGroups" type="unsigned long" readonly="yes">
18675	<desc>
18676	The current number of existing bandwidth groups managed.
18677	</desc>
18678	</attribute>
18679
18680	<method name="createBandwidthGroup">
18681	<desc>
18682	Creates a new bandwidth group.
18683	</desc>
18684
18685	<param name="name" type="wstring" dir="in">
18686	<desc>Name of the bandwidth group.</desc>
18687	</param>
18688	<param name="type" type="BandwidthGroupType" dir="in">
18689	<desc>The type of the bandwidth group (network or disk).</desc>
18690	</param>
18691	<param name="maxBytesPerSec" type="long long" dir="in">
18692	<desc>The maximum number of bytes which can be transfered by all
18693	entities attached to this group during one second.</desc>
18694	</param>
18695	</method>
18696
18697	<method name="deleteBandwidthGroup">
18698	<desc>
18699	Deletes a new bandwidth group.
18700	</desc>
18701
18702	<param name="name" type="wstring" dir="in">
18703	<desc>Name of the bandwidth group to delete.</desc>
18704	</param>
18705	</method>
18706
18707	<method name="getBandwidthGroup" const="yes">
18708	<desc>
18709	Get a bandwidth group by name.
18710	</desc>
18711
18712	<param name="name" type="wstring" dir="in">
18713	<desc>Name of the bandwidth group to get.</desc>
18714	</param>
18715	<param name="bandwidthGroup" type="IBandwidthGroup" dir="return">
18716	<desc>Where to store the bandwidth group on success.</desc>
18717	</param>
18718	</method>
18719
18720	<method name="getAllBandwidthGroups" const="yes">
18721	<desc>
18722	Get all managed bandwidth groups.
18723	</desc>
18724
18725	<param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes">
18726	<desc>The array of managed bandwidth groups.</desc>
18727	</param>
18728	</method>
18729	</interface>
18730
18731	<!--
18732	// IVirtualBoxClient
18733	/////////////////////////////////////////////////////////////////////////
18734	-->
18735
18736	<interface
18737	name="IVirtualBoxClient" extends="$unknown"
18738	uuid="d191281f-b0cb-4d83-a8fa-0d9fd6ba234c"
18739	wsmap="suppress"
18740	>
18741	<desc>
18742	Convenience interface for client applications. Treat this as a
18743	singleton, i.e. never create more than one instance of this interface.
18744
18745	At the moment only available for clients of the local API (not usable
18746	via the webservice). Once the session logic is redesigned this might
18747	change.
18748	</desc>
18749
18750	<attribute name="virtualBox" type="IVirtualBox" readonly="yes">
18751	<desc>
18752	Reference to the server-side API root object.
18753	</desc>
18754	</attribute>
18755
18756	<attribute name="session" type="ISession" readonly="yes">
18757	<desc>
18758	Create a new session object and return the reference to it.
18759	</desc>
18760	</attribute>
18761
18762	<attribute name="eventSource" type="IEventSource" readonly="yes">
18763	<desc>
18764	Event source for VirtualBoxClient events.
18765	</desc>
18766	</attribute>
18767
18768	<method name="checkMachineError">
18769	<desc>
18770	Perform error checking before using an <link to="IMachine"/> object.
18771	Generally useful before starting a VM and all other uses. If anything
18772	is not as it should be then this method will return an appropriate
18773	error.
18774	</desc>
18775
18776	<param name="machine" type="IMachine" dir="in">
18777	<desc>The machine object to check.</desc>
18778	</param>
18779	</method>
18780	</interface>
18781
18782	<!--
18783	// Events
18784	/////////////////////////////////////////////////////////////////////////
18785	-->
18786	<enum
18787	name="VBoxEventType"
18788	uuid="f019b8c7-22a6-468a-9f7c-3443b7b6c40a"
18789	>
18790
18791	<desc>
18792	Type of an event.
18793	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
18794	</desc>
18795
18796	<const name="Invalid" value="0">
18797	<desc>
18798	Invalid event, must be first.
18799	</desc>
18800	</const>
18801
18802	<const name="Any" value="1">
18803	<desc>
18804	Wildcard for all events.
18805	Events of this type are never delivered, and only used in
18806	<link to="IEventSource::registerListener"/> call to simplify registration.
18807	</desc>
18808	</const>
18809
18810	<const name="Vetoable" value="2">
18811	<desc>
18812	Wildcard for all vetoable events. Events of this type are never delivered, and only
18813	used in <link to="IEventSource::registerListener"/> call to simplify registration.
18814	</desc>
18815	</const>
18816
18817	<const name="MachineEvent" value="3">
18818	<desc>
18819	Wildcard for all machine events. Events of this type are never delivered, and only used in
18820	<link to="IEventSource::registerListener"/> call to simplify registration.
18821	</desc>
18822	</const>
18823
18824	<const name="SnapshotEvent" value="4">
18825	<desc>
18826	Wildcard for all snapshot events. Events of this type are never delivered, and only used in
18827	<link to="IEventSource::registerListener"/> call to simplify registration.
18828	</desc>
18829	</const>
18830
18831	<const name="InputEvent" value="5">
18832	<desc>
18833	Wildcard for all input device (keyboard, mouse) events.
18834	Events of this type are never delivered, and only used in
18835	<link to="IEventSource::registerListener"/> call to simplify registration.
18836	</desc>
18837	</const>
18838
18839	<const name="LastWildcard" value="31">
18840	<desc>
18841	Last wildcard.
18842	</desc>
18843	</const>
18844
18845	<const name="OnMachineStateChanged" value="32">
18846	<desc>
18847	See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
18848	</desc>
18849	</const>
18850	<const name="OnMachineDataChanged" value="33">
18851	<desc>
18852	See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
18853	</desc>
18854	</const>
18855	<const name="OnExtraDataChanged" value="34">
18856	<desc>
18857	See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
18858	</desc>
18859	</const>
18860	<const name="OnExtraDataCanChange" value="35">
18861	<desc>
18862	See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
18863	</desc>
18864	</const>
18865	<const name="OnMediumRegistered" value="36">
18866	<desc>
18867	See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
18868	</desc>
18869	</const>
18870	<const name="OnMachineRegistered" value="37">
18871	<desc>
18872	See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
18873	</desc>
18874	</const>
18875	<const name="OnSessionStateChanged" value="38">
18876	<desc>
18877	See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
18878	</desc>
18879	</const>
18880	<const name="OnSnapshotTaken" value="39">
18881	<desc>
18882	See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
18883	</desc>
18884	</const>
18885	<const name="OnSnapshotDeleted" value="40">
18886	<desc>
18887	See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
18888	</desc>
18889	</const>
18890	<const name="OnSnapshotChanged" value="41">
18891	<desc>
18892	See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
18893	</desc>
18894	</const>
18895	<const name="OnGuestPropertyChanged" value="42">
18896	<desc>
18897	See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
18898	</desc>
18899	</const>
18900	<!-- Console events -->
18901	<const name="OnMousePointerShapeChanged" value="43">
18902	<desc>
18903	See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
18904	</desc>
18905	</const>
18906	<const name="OnMouseCapabilityChanged" value="44">
18907	<desc>
18908	See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
18909	</desc>
18910	</const>
18911	<const name="OnKeyboardLedsChanged" value="45">
18912	<desc>
18913	See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
18914	</desc>
18915	</const>
18916	<const name="OnStateChanged" value="46">
18917	<desc>
18918	See <link to="IStateChangedEvent">IStateChangedEvent</link>.
18919	</desc>
18920	</const>
18921	<const name="OnAdditionsStateChanged" value="47">
18922	<desc>
18923	See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
18924	</desc>
18925	</const>
18926	<const name="OnNetworkAdapterChanged" value="48">
18927	<desc>
18928	See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
18929	</desc>
18930	</const>
18931	<const name="OnSerialPortChanged" value="49">
18932	<desc>
18933	See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
18934	</desc>
18935	</const>
18936	<const name="OnParallelPortChanged" value="50">
18937	<desc>
18938	See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
18939	</desc>
18940	</const>
18941	<const name="OnStorageControllerChanged" value="51">
18942	<desc>
18943	See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
18944	</desc>
18945	</const>
18946	<const name="OnMediumChanged" value="52">
18947	<desc>
18948	See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
18949	</desc>
18950	</const>
18951	<const name="OnVRDEServerChanged" value="53">
18952	<desc>
18953	See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
18954	</desc>
18955	</const>
18956	<const name="OnUSBControllerChanged" value="54">
18957	<desc>
18958	See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
18959	</desc>
18960	</const>
18961	<const name="OnUSBDeviceStateChanged" value="55">
18962	<desc>
18963	See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
18964	</desc>
18965	</const>
18966	<const name="OnSharedFolderChanged" value="56">
18967	<desc>
18968	See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
18969	</desc>
18970	</const>
18971	<const name="OnRuntimeError" value="57">
18972	<desc>
18973	See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
18974	</desc>
18975	</const>
18976	<const name="OnCanShowWindow" value="58">
18977	<desc>
18978	See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
18979	</desc>
18980	</const>
18981	<const name="OnShowWindow" value="59">
18982	<desc>
18983	See <link to="IShowWindowEvent">IShowWindowEvent</link>.
18984	</desc>
18985	</const>
18986	<const name="OnCPUChanged" value="60">
18987	<desc>
18988	See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
18989	</desc>
18990	</const>
18991	<const name="OnVRDEServerInfoChanged" value="61">
18992	<desc>
18993	See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
18994	</desc>
18995	</const>
18996	<const name="OnEventSourceChanged" value="62">
18997	<desc>
18998	See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
18999	</desc>
19000	</const>
19001	<const name="OnCPUExecutionCapChanged" value="63">
19002	<desc>
19003	See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
19004	</desc>
19005	</const>
19006	<const name="OnGuestKeyboard" value="64">
19007	<desc>
19008	See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
19009	</desc>
19010	</const>
19011	<const name="OnGuestMouse" value="65">
19012	<desc>
19013	See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
19014	</desc>
19015	</const>
19016	<const name="OnNATRedirect" value="66">
19017	<desc>
19018	See <link to="INATRedirectEvent">INATRedirectEvent</link>.
19019	</desc>
19020	</const>
19021	<const name="OnHostPCIDevicePlug" value="67">
19022	<desc>
19023	See <link to="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link>.
19024	</desc>
19025	</const>
19026	<const name="OnVBoxSVCAvailabilityChanged" value="68">
19027	<desc>
19028	See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>.
19029	</desc>
19030	</const>
19031	<const name="OnBandwidthGroupChanged" value="69">
19032	<desc>
19033	See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>.
19034	</desc>
19035	</const>
19036	<const name="OnGuestMonitorChanged" value="70">
19037	<desc>
19038	See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>.
19039	</desc>
19040	</const>
19041	<const name="OnStorageDeviceChanged" value="71">
19042	<desc>
19043	See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>.
19044	</desc>
19045	</const>
19046	<const name="OnClipboardModeChanged" value="72">
19047	<desc>
19048	See <link to="IClipboardModeChangedEvent">IClipboardModeChangedEvent</link>.
19049	</desc>
19050	</const>
19051	<const name="OnDragAndDropModeChanged" value="73">
19052	<desc>
19053	See <link to="IDragAndDropModeChangedEvent">IDragAndDropModeChangedEvent</link>.
19054	</desc>
19055	</const>
19056	<const name="OnNATNetworkChanged" value="74">
19057	<desc>
19058	See <link to="INATNetworkChangedEvent">INATNetworkChangedEvent</link>.
19059	</desc>
19060	</const>
19061	<const name="OnNATNetworkStartStop" value="75">
19062	<desc>
19063	See <link to="INATNetworkStartStopEvent">INATNetworkStartStopEvent</link>.
19064	</desc>
19065	</const>
19066	<const name="OnNATNetworkAlter" value="76">
19067	<desc>
19068	See <link to="INATNetworkAlterEvent">INATNetworkAlterEvent</link>.
19069	</desc>
19070	</const>
19071	<const name="OnNATNetworkCreationDeletion" value="77">
19072	<desc>
19073	See <link to="INATNetworkCreationDeletionEvent">INATNetworkCreationDeletionEvent</link>.
19074	</desc>
19075	</const>
19076	<const name="OnNATNetworkSetting" value="78">
19077	<desc>
19078	See <link to="INATNetworkSettingEvent">INATNetworkSettingEvent</link>.
19079	</desc>
19080	</const>
19081	<const name="OnNATNetworkPortForward" value="79">
19082	<desc>
19083	See <link to="INATNetworkPortForwardEvent">INATNetworkPortForwardEvent</link>.
19084	</desc>
19085	</const>
19086	<const name="OnGuestSessionStateChanged" value="80">
19087	<desc>
19088	See <link to="IGuestSessionStateChangedEvent">IGuestSessionStateChangedEvent</link>.
19089	</desc>
19090	</const>
19091	<const name="OnGuestSessionRegistered" value="81">
19092	<desc>
19093	See <link to="IGuestSessionRegisteredEvent">IGuestSessionRegisteredEvent</link>.
19094	</desc>
19095	</const>
19096	<const name="OnGuestProcessRegistered" value="82">
19097	<desc>
19098	See <link to="IGuestProcessRegisteredEvent">IGuestProcessRegisteredEvent</link>.
19099	</desc>
19100	</const>
19101	<const name="OnGuestProcessStateChanged" value="83">
19102	<desc>
19103	See <link to="IGuestProcessStateChangedEvent">IGuestProcessStateChangedEvent</link>.
19104	</desc>
19105	</const>
19106	<const name="OnGuestProcessInputNotify" value="84">
19107	<desc>
19108	See <link to="IGuestProcessInputNotifyEvent">IGuestProcessInputNotifyEvent</link>.
19109	</desc>
19110	</const>
19111	<const name="OnGuestProcessOutput" value="85">
19112	<desc>
19113	See <link to="IGuestProcessOutputEvent">IGuestProcessOutputEvent</link>.
19114	</desc>
19115	</const>
19116	<const name="OnGuestFileRegistered" value="86">
19117	<desc>
19118	See <link to="IGuestFileRegisteredEvent">IGuestFileRegisteredEvent</link>.
19119	</desc>
19120	</const>
19121	<const name="OnGuestFileStateChanged" value="87">
19122	<desc>
19123	See <link to="IGuestFileStateChangedEvent">IGuestFileStateChangedEvent</link>.
19124	</desc>
19125	</const>
19126	<const name="OnGuestFileOffsetChanged" value="88">
19127	<desc>
19128	See <link to="IGuestFileOffsetChangedEvent">IGuestFileOffsetChangedEvent</link>.
19129	</desc>
19130	</const>
19131	<const name="OnGuestFileRead" value="89">
19132	<desc>
19133	See <link to="IGuestFileReadEvent">IGuestFileReadEvent</link>.
19134
19135	<note internal="yes">For performance reasons this is a separate event to
19136	not unnecessarily overflow the event queue.</note>
19137	</desc>
19138	</const>
19139	<const name="OnGuestFileWrite" value="90">
19140	<desc>
19141	See <link to="IGuestFileWriteEvent">IGuestFileWriteEvent</link>.
19142
19143	<note internal="yes">For performance reasons this is a separate event to
19144	not unnecessarily overflow the event queue.</note>
19145	</desc>
19146	</const>
19147	<const name="OnVideoCaptureChanged" value="91">
19148	<desc>
19149	See <link to="IVideoCaptureChangedEvent">IVideoCapturedChangeEvent</link>.
19150	</desc>
19151	</const>
19152	<!-- Last event marker -->
19153	<const name="Last" value="92">
19154	<desc>
19155	Must be last event, used for iterations and structures relying on numerical event values.
19156	</desc>
19157	</const>
19158
19159	</enum>
19160
19161	<interface
19162	name="IEventSource" extends="$unknown"
19163	uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
19164	wsmap="managed"
19165	>
19166	<desc>
19167	Event source. Generally, any object which could generate events can be an event source,
19168	or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
19169	an event source can work with listeners in either active or passive mode. In active mode it is up to
19170	the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
19171	event source keeps track of pending events for each listener and returns available events on demand.
19172
19173	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19174	</desc>
19175
19176	<method name="createListener">
19177	<desc>
19178	Creates a new listener object, useful for passive mode.
19179	</desc>
19180	<param name="listener" type="IEventListener" dir="return"/>
19181	</method>
19182
19183	<method name="createAggregator">
19184	<desc>
19185	Creates an aggregator event source, collecting events from multiple sources.
19186	This way a single listener can listen for events coming from multiple sources,
19187	using a single blocking <link to="#getEvent"/> on the returned aggregator.
19188	</desc>
19189	<param name="subordinates" type="IEventSource" dir="in" safearray="yes">
19190	<desc>
19191	Subordinate event source this one aggregatres.
19192	</desc>
19193	</param>
19194	<param name="result" type="IEventSource" dir="return">
19195	<desc>
19196	Event source aggregating passed sources.
19197	</desc>
19198	</param>
19199	</method>
19200
19201	<method name="registerListener">
19202	<desc>
19203	Register an event listener.
19204
19205	<note>
19206	To avoid system overload, the VirtualBox server process checks if passive event
19207	listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
19208	current implementation, if more than 500 pending events are detected for a passive
19209	event listener, it is forcefully unregistered by the system, and further
19210	<link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
19211	</note>
19212	</desc>
19213	<param name="listener" type="IEventListener" dir="in">
19214	<desc>Listener to register.</desc>
19215	</param>
19216	<param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
19217	<desc>
19218	Event types listener is interested in. One can use wildcards like -
19219	<link to="VBoxEventType_Any"/> to specify wildcards, matching more
19220	than one event.
19221	</desc>
19222	</param>
19223	<param name="active" type="boolean" dir="in">
19224	<desc>
19225	Which mode this listener is operating in.
19226	In active mode, <link to="IEventListener::handleEvent" /> is called directly.
19227	In passive mode, an internal event queue is created for this this IEventListener.
19228	For each event coming in, it is added to queues for all interested registered passive
19229	listeners. It is then up to the external code to call the listener's
19230	<link to="IEventListener::handleEvent" /> method. When done with an event, the
19231	external code must call <link to="#eventProcessed" />.
19232	</desc>
19233	</param>
19234	</method>
19235
19236	<method name="unregisterListener">
19237	<desc>
19238	Unregister an event listener. If listener is passive, and some waitable events are still
19239	in queue they are marked as processed automatically.
19240	</desc>
19241	<param name="listener" type="IEventListener" dir="in">
19242	<desc>Listener to unregister.</desc>
19243	</param>
19244	</method>
19245
19246	<method name="fireEvent">
19247	<desc>
19248	Fire an event for this source.
19249	</desc>
19250	<param name="event" type="IEvent" dir="in">
19251	<desc>Event to deliver.</desc>
19252	</param>
19253	<param name="timeout" type="long" dir="in">
19254	<desc>
19255	Maximum time to wait for event processing (if event is waitable), in ms;
19256	0 = no wait, -1 = indefinite wait.
19257	</desc>
19258	</param>
19259	<param name="result" type="boolean" dir="return">
19260	<desc>true if an event was delivered to all targets, or is non-waitable.</desc>
19261	</param>
19262	</method>
19263
19264	<method name="getEvent">
19265	<desc>
19266	Get events from this peer's event queue (for passive mode). Calling this method
19267	regularly is required for passive event listeners to avoid system overload;
19268	see <link to="IEventSource::registerListener" /> for details.
19269
19270	<result name="VBOX_E_OBJECT_NOT_FOUND">
19271	Listener is not registered, or autounregistered.
19272	</result>
19273	</desc>
19274	<param name="listener" type="IEventListener" dir="in">
19275	<desc>Which listener to get data for.</desc>
19276	</param>
19277	<param name="timeout" type="long" dir="in">
19278	<desc>
19279	Maximum time to wait for events, in ms;
19280	0 = no wait, -1 = indefinite wait.
19281	</desc>
19282	</param>
19283	<param name="event" type="IEvent" dir="return">
19284	<desc>Event retrieved, or null if none available.</desc>
19285	</param>
19286	</method>
19287
19288	<method name="eventProcessed">
19289	<desc>
19290	Must be called for waitable events after a particular listener finished its
19291	event processing. When all listeners of a particular event have called this
19292	method, the system will then call <link to="IEvent::setProcessed" />.
19293	</desc>
19294	<param name="listener" type="IEventListener" dir="in">
19295	<desc>Which listener processed event.</desc>
19296	</param>
19297	<param name="event" type="IEvent" dir="in">
19298	<desc>Which event.</desc>
19299	</param>
19300	</method>
19301
19302	</interface>
19303
19304	<interface
19305	name="IEventListener" extends="$unknown"
19306	uuid="67099191-32e7-4f6c-85ee-422304c71b90"
19307	wsmap="managed"
19308	>
19309	<desc>
19310	Event listener. An event listener can work in either active or passive mode, depending on the way
19311	it was registered.
19312	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19313	</desc>
19314
19315	<method name="handleEvent">
19316	<desc>
19317	Handle event callback for active listeners. It is not called for
19318	passive listeners. After calling <link to="#handleEvent"/> on all active listeners
19319	and having received acknowledgement from all passive listeners via
19320	<link to="IEventSource::eventProcessed"/>, the event is marked as
19321	processed and <link to="IEvent::waitProcessed"/> will return
19322	immediately.
19323	</desc>
19324	<param name="event" type="IEvent" dir="in">
19325	<desc>Event available.</desc>
19326	</param>
19327	</method>
19328
19329	</interface>
19330
19331	<interface
19332	name="IEvent" extends="$unknown"
19333	uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
19334	wsmap="managed"
19335	>
19336	<desc>
19337	Abstract parent interface for VirtualBox events. Actual events will typically implement
19338	a more specific interface which derives from this (see below).
19339
19340	<b>Introduction to VirtualBox events</b>
19341
19342	Generally speaking, an event (represented by this interface) signals that something
19343	happened, while an event listener (see <link to="IEventListener" />) represents an
19344	entity that is interested in certain events. In order for this to work with
19345	unidirectional protocols (i.e. web services), the concepts of passive and active
19346	listener are used.
19347
19348	Event consumers can register themselves as listeners, providing an array of
19349	events they are interested in (see <link to="IEventSource::registerListener" />).
19350	When an event triggers, the listener is notified about the event. The exact
19351	mechanism of the notification depends on whether the listener was registered as
19352	an active or passive listener:
19353
19354	<ul>
19355	<li>An active listener is very similar to a callback: it is a function invoked
19356	by the API. As opposed to the callbacks that were used in the API before
19357	VirtualBox 4.0 however, events are now objects with an interface hierarchy.
19358	</li>
19359
19360	<li>Passive listeners are somewhat trickier to implement, but do not require
19361	a client function to be callable, which is not an option with scripting
19362	languages or web service clients. Internally the <link to="IEventSource" />
19363	implementation maintains an event queue for each passive listener, and
19364	newly arrived events are put in this queue. When the listener calls
19365	<link to="IEventSource::getEvent"/>, first element from its internal event
19366	queue is returned. When the client completes processing of an event,
19367	the <link to="IEventSource::eventProcessed" /> function must be called,
19368	acknowledging that the event was processed. It supports implementing
19369	waitable events. On passive listener unregistration, all events from its
19370	queue are auto-acknowledged.
19371	</li>
19372	</ul>
19373
19374	Waitable events are useful in situations where the event generator wants to track
19375	delivery or a party wants to wait until all listeners have completed the event. A
19376	typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
19377	listeners might veto a certain action, and thus the event producer has to make
19378	sure that all listeners have processed the event and not vetoed before taking
19379	the action.
19380
19381	A given event may have both passive and active listeners at the same time.
19382
19383	<b>Using events</b>
19384
19385	Any VirtualBox object capable of producing externally visible events provides an
19386	@c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
19387	This event source object is notified by VirtualBox once something has happened, so
19388	consumers may register event listeners with this event source. To register a listener,
19389	an object implementing the <link to="IEventListener" /> interface must be provided.
19390	For active listeners, such an object is typically created by the consumer, while for
19391	passive listeners <link to="IEventSource::createListener" /> should be used. Please
19392	note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener.
19393
19394	Once created, the listener must be registered to listen for the desired events
19395	(see <link to="IEventSource::registerListener" />), providing an array of
19396	<link to="VBoxEventType" /> enums. Those elements can either be the individual
19397	event IDs or wildcards matching multiple event IDs.
19398
19399	After registration, the callback's <link to="IEventListener::handleEvent" /> method is
19400	called automatically when the event is triggered, while passive listeners have to call
19401	<link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
19402	an event processing loop.
19403
19404	The IEvent interface is an abstract parent interface for all such VirtualBox events
19405	coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
19406	or the event processing loop is to check the <link to="#type" /> attribute of the event and
19407	then cast to the appropriate specific interface using @c QueryInterface().
19408	</desc>
19409
19410	<attribute name="type" readonly="yes" type="VBoxEventType">
19411	<desc>
19412	Event type.
19413	</desc>
19414	</attribute>
19415
19416	<attribute name="source" readonly="yes" type="IEventSource">
19417	<desc>
19418	Source of this event.
19419	</desc>
19420	</attribute>
19421
19422	<attribute name="waitable" readonly="yes" type="boolean">
19423	<desc>
19424	If we can wait for this event being processed. If false, <link to="#waitProcessed"/> returns immediately,
19425	and <link to="#setProcessed"/> doesn't make sense. Non-waitable events are generally better performing,
19426	as no additional overhead associated with waitability imposed.
19427	Waitable events are needed when one need to be able to wait for particular event processed,
19428	for example for vetoable changes, or if event refers to some resource which need to be kept immutable
19429	until all consumers confirmed events.
19430	</desc>
19431	</attribute>
19432
19433	<method name="setProcessed">
19434	<desc>
19435	Internal method called by the system when all listeners of a particular event have called
19436	<link to="IEventSource::eventProcessed" />. This should not be called by client code.
19437	</desc>
19438	</method>
19439
19440	<method name="waitProcessed">
19441	<desc>
19442	Wait until time outs, or this event is processed. Event must be waitable for this operation to have
19443	described semantics, for non-waitable returns true immediately.
19444	</desc>
19445	<param name="timeout" type="long" dir="in">
19446	<desc>
19447	Maximum time to wait for event processeing, in ms;
19448	0 = no wait, -1 = indefinite wait.
19449	</desc>
19450	</param>
19451	<param name="result" type="boolean" dir="return">
19452	<desc>If this event was processed before timeout.</desc>
19453	</param>
19454	</method>
19455	</interface>
19456
19457
19458	<interface
19459	name="IReusableEvent" extends="IEvent"
19460	uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
19461	wsmap="managed"
19462	>
19463	<desc>Base abstract interface for all reusable events.</desc>
19464
19465	<attribute name="generation" readonly="yes" type="unsigned long">
19466	<desc>Current generation of event, incremented on reuse.</desc>
19467	</attribute>
19468
19469	<method name="reuse">
19470	<desc>
19471	Marks an event as reused, increments 'generation', fields shall no
19472	longer be considered valid.
19473	</desc>
19474	</method>
19475	</interface>
19476
19477	<interface
19478	name="IMachineEvent" extends="IEvent"
19479	uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
19480	wsmap="managed" id="MachineEvent"
19481	>
19482	<desc>Base abstract interface for all machine events.</desc>
19483
19484	<attribute name="machineId" readonly="yes" type="uuid" mod="string">
19485	<desc>ID of the machine this event relates to.</desc>
19486	</attribute>
19487
19488	</interface>
19489
19490	<interface
19491	name="IMachineStateChangedEvent" extends="IMachineEvent"
19492	uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
19493	wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
19494	>
19495	<desc>Machine state change event.</desc>
19496
19497	<attribute name="state" readonly="yes" type="MachineState">
19498	<desc>New execution state.</desc>
19499	</attribute>
19500	</interface>
19501
19502	<interface
19503	name="IMachineDataChangedEvent" extends="IMachineEvent"
19504	uuid="abe94809-2e88-4436-83d7-50f3e64d0503"
19505	wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
19506	>
19507	<desc>
19508	Any of the settings of the given machine has changed.
19509	</desc>
19510
19511	<attribute name="temporary" readonly="yes" type="boolean">
19512	<desc>@c true if the settings change is temporary. All permanent
19513	settings changes will trigger an event, and only temporary settings
19514	changes for running VMs will trigger an event. Note: sending events
19515	for temporary changes is NOT IMPLEMENTED.</desc>
19516	</attribute>
19517	</interface>
19518
19519	<interface
19520	name="IMediumRegisteredEvent" extends="IEvent"
19521	uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
19522	wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
19523	>
19524	<desc>
19525	The given medium was registered or unregistered
19526	within this VirtualBox installation.
19527	</desc>
19528
19529	<attribute name="mediumId" readonly="yes" type="uuid" mod="string">
19530	<desc>ID of the medium this event relates to.</desc>
19531	</attribute>
19532
19533	<attribute name="mediumType" readonly="yes" type="DeviceType">
19534	<desc>Type of the medium this event relates to.</desc>
19535	</attribute>
19536
19537	<attribute name="registered" type="boolean" readonly="yes">
19538	<desc>
19539	If @c true, the medium was registered, otherwise it was
19540	unregistered.
19541	</desc>
19542	</attribute>
19543	</interface>
19544
19545	<interface
19546	name="IMachineRegisteredEvent" extends="IMachineEvent"
19547	uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
19548	wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
19549	>
19550	<desc>
19551	The given machine was registered or unregistered
19552	within this VirtualBox installation.
19553	</desc>
19554
19555	<attribute name="registered" type="boolean" readonly="yes">
19556	<desc>
19557	If @c true, the machine was registered, otherwise it was
19558	unregistered.
19559	</desc>
19560	</attribute>
19561	</interface>
19562
19563	<interface
19564	name="ISessionStateChangedEvent" extends="IMachineEvent"
19565	uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
19566	wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
19567	>
19568	<desc>
19569	The state of the session for the given machine was changed.
19570	<see><link to="IMachine::sessionState"/></see>
19571	</desc>
19572
19573	<attribute name="state" type="SessionState" readonly="yes">
19574	<desc>
19575	New session state.
19576	</desc>
19577	</attribute>
19578	</interface>
19579
19580	<interface
19581	name="IGuestPropertyChangedEvent" extends="IMachineEvent"
19582	uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
19583	wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
19584	>
19585	<desc>
19586	Notification when a guest property has changed.
19587	</desc>
19588
19589	<attribute name="name" readonly="yes" type="wstring">
19590	<desc>
19591	The name of the property that has changed.
19592	</desc>
19593	</attribute>
19594
19595	<attribute name="value" readonly="yes" type="wstring">
19596	<desc>
19597	The new property value.
19598	</desc>
19599	</attribute>
19600
19601	<attribute name="flags" readonly="yes" type="wstring">
19602	<desc>
19603	The new property flags.
19604	</desc>
19605	</attribute>
19606
19607	</interface>
19608
19609	<interface
19610	name="ISnapshotEvent" extends="IMachineEvent"
19611	uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
19612	wsmap="managed" id="SnapshotEvent"
19613	>
19614	<desc>Base interface for all snapshot events.</desc>
19615
19616	<attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
19617	<desc>ID of the snapshot this event relates to.</desc>
19618	</attribute>
19619
19620	</interface>
19621
19622	<interface
19623	name="ISnapshotTakenEvent" extends="ISnapshotEvent"
19624	uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
19625	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
19626	>
19627	<desc>
19628	A new snapshot of the machine has been taken.
19629	<see><link to="ISnapshot"/></see>
19630	</desc>
19631	</interface>
19632
19633	<interface
19634	name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
19635	uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
19636	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
19637	>
19638	<desc>
19639	Snapshot of the given machine has been deleted.
19640
19641	<note>
19642	This notification is delivered <b>after</b> the snapshot
19643	object has been uninitialized on the server (so that any
19644	attempt to call its methods will return an error).
19645	</note>
19646
19647	<see><link to="ISnapshot"/></see>
19648	</desc>
19649	</interface>
19650
19651	<interface
19652	name="ISnapshotChangedEvent" extends="ISnapshotEvent"
19653	uuid="07541941-8079-447a-a33e-47a69c7980db"
19654	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
19655	>
19656	<desc>
19657	Snapshot properties (name and/or description) have been changed.
19658	<see><link to="ISnapshot"/></see>
19659	</desc>
19660	</interface>
19661
19662	<interface
19663	name="IMousePointerShapeChangedEvent" extends="IEvent"
19664	uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
19665	wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
19666	>
19667	<desc>
19668	Notification when the guest mouse pointer shape has
19669	changed. The new shape data is given.
19670	</desc>
19671
19672	<attribute name="visible" type="boolean" readonly="yes">
19673	<desc>
19674	Flag whether the pointer is visible.
19675	</desc>
19676	</attribute>
19677	<attribute name="alpha" type="boolean" readonly="yes">
19678	<desc>
19679	Flag whether the pointer has an alpha channel.
19680	</desc>
19681	</attribute>
19682	<attribute name="xhot" type="unsigned long" readonly="yes">
19683	<desc>
19684	The pointer hot spot X coordinate.
19685	</desc>
19686	</attribute>
19687	<attribute name="yhot" type="unsigned long" readonly="yes">
19688	<desc>
19689	The pointer hot spot Y coordinate.
19690	</desc>
19691	</attribute>
19692	<attribute name="width" type="unsigned long" readonly="yes">
19693	<desc>
19694	Width of the pointer shape in pixels.
19695	</desc>
19696	</attribute>
19697	<attribute name="height" type="unsigned long" readonly="yes">
19698	<desc>
19699	Height of the pointer shape in pixels.
19700	</desc>
19701	</attribute>
19702	<attribute name="shape" type="octet" safearray="yes" readonly="yes">
19703	<desc>
19704	Shape buffer arrays.
19705
19706	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
19707	followed by a 32-bpp XOR (color) mask.
19708
19709	For pointers without alpha channel the XOR mask pixels are
19710	32-bit values: (lsb)BGR0(msb). For pointers with alpha channel
19711	the XOR mask consists of (lsb)BGRA(msb) 32-bit values.
19712
19713	An AND mask is used for pointers with alpha channel, so if the
19714	callback does not support alpha, the pointer could be
19715	displayed as a normal color pointer.
19716
19717	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
19718	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
19719	height</tt>. The padding bits at the end of each scanline are
19720	undefined.
19721
19722	The XOR mask follows the AND mask on the next 4-byte aligned
19723	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
19724	Bytes in the gap between the AND and the XOR mask are undefined.
19725	The XOR mask scanlines have no gap between them and the size of
19726	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
19727
19728	<note>
19729	If @a shape is 0, only the pointer visibility is changed.
19730	</note>
19731	</desc>
19732	</attribute>
19733	</interface>
19734
19735	<interface
19736	name="IMouseCapabilityChangedEvent" extends="IEvent"
19737	uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
19738	wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
19739	>
19740	<desc>
19741	Notification when the mouse capabilities reported by the
19742	guest have changed. The new capabilities are passed.
19743	</desc>
19744	<attribute name="supportsAbsolute" type="boolean" readonly="yes">
19745	<desc>
19746	Supports absolute coordinates.
19747	</desc>
19748	</attribute>
19749	<attribute name="supportsRelative" type="boolean" readonly="yes">
19750	<desc>
19751	Supports relative coordinates.
19752	</desc>
19753	</attribute>
19754	<attribute name="needsHostCursor" type="boolean" readonly="yes">
19755	<desc>
19756	If host cursor is needed.
19757	</desc>
19758	</attribute>
19759	</interface>
19760
19761	<interface
19762	name="IKeyboardLedsChangedEvent" extends="IEvent"
19763	uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
19764	wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
19765	>
19766	<desc>
19767	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
19768	to alter the state of the keyboard LEDs.
19769	</desc>
19770	<attribute name="numLock" type="boolean" readonly="yes">
19771	<desc>
19772	NumLock status.
19773	</desc>
19774	</attribute>
19775	<attribute name="capsLock" type="boolean" readonly="yes">
19776	<desc>
19777	CapsLock status.
19778	</desc>
19779	</attribute>
19780	<attribute name="scrollLock" type="boolean" readonly="yes">
19781	<desc>
19782	ScrollLock status.
19783	</desc>
19784	</attribute>
19785	</interface>
19786
19787	<interface
19788	name="IStateChangedEvent" extends="IEvent"
19789	uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
19790	wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
19791	>
19792	<desc>
19793	Notification when the execution state of the machine has changed.
19794	The new state is given.
19795	</desc>
19796	<attribute name="state" type="MachineState" readonly="yes">
19797	<desc>
19798	New machine state.
19799	</desc>
19800	</attribute>
19801	</interface>
19802
19803	<interface
19804	name="IAdditionsStateChangedEvent" extends="IEvent"
19805	uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
19806	wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
19807	>
19808	<desc>
19809	Notification when a Guest Additions property changes.
19810	Interested callees should query IGuest attributes to
19811	find out what has changed.
19812	</desc>
19813	</interface>
19814
19815	<interface
19816	name="INetworkAdapterChangedEvent" extends="IEvent"
19817	uuid="08889892-1EC6-4883-801D-77F56CFD0103"
19818	wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
19819	>
19820	<desc>
19821	Notification when a property of one of the
19822	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
19823	changes. Interested callees should use INetworkAdapter methods and
19824	attributes to find out what has changed.
19825	</desc>
19826	<attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
19827	<desc>
19828	Network adapter that is subject to change.
19829	</desc>
19830	</attribute>
19831	</interface>
19832
19833	<interface
19834	name="ISerialPortChangedEvent" extends="IEvent"
19835	uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
19836	wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
19837	>
19838	<desc>
19839	Notification when a property of one of the
19840	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
19841	Interested callees should use ISerialPort methods and attributes
19842	to find out what has changed.
19843	</desc>
19844	<attribute name="serialPort" type="ISerialPort" readonly="yes">
19845	<desc>
19846	Serial port that is subject to change.
19847	</desc>
19848	</attribute>
19849	</interface>
19850
19851	<interface
19852	name="IParallelPortChangedEvent" extends="IEvent"
19853	uuid="813C99FC-9849-4F47-813E-24A75DC85615"
19854	wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
19855	>
19856	<desc>
19857	Notification when a property of one of the
19858	virtual <link to="IMachine::getParallelPort">parallel ports</link>
19859	changes. Interested callees should use ISerialPort methods and
19860	attributes to find out what has changed.
19861	</desc>
19862	<attribute name="parallelPort" type="IParallelPort" readonly="yes">
19863	<desc>
19864	Parallel port that is subject to change.
19865	</desc>
19866	</attribute>
19867	</interface>
19868
19869	<interface
19870	name="IStorageControllerChangedEvent" extends="IEvent"
19871	uuid="715212BF-DA59-426E-8230-3831FAA52C56"
19872	wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
19873	>
19874	<desc>
19875	Notification when a
19876	<link to="IMachine::mediumAttachments">medium attachment</link>
19877	changes.
19878	</desc>
19879	</interface>
19880
19881	<interface
19882	name="IMediumChangedEvent" extends="IEvent"
19883	uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
19884	wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
19885	>
19886	<desc>
19887	Notification when a
19888	<link to="IMachine::mediumAttachments">medium attachment</link>
19889	changes.
19890	</desc>
19891	<attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
19892	<desc>
19893	Medium attachment that is subject to change.
19894	</desc>
19895	</attribute>
19896	</interface>
19897
19898	<interface
19899	name="IClipboardModeChangedEvent" extends="IEvent"
19900	uuid="cac21692-7997-4595-a731-3a509db604e5"
19901	wsmap="managed" autogen="VBoxEvent" id="OnClipboardModeChanged"
19902	>
19903	<desc>
19904	Notification when the shared clipboard mode changes.
19905	</desc>
19906	<attribute name="clipboardMode" type="ClipboardMode" readonly="yes">
19907	<desc>
19908	The new clipboard mode.
19909	</desc>
19910	</attribute>
19911	</interface>
19912
19913	<interface
19914	name="IDragAndDropModeChangedEvent" extends="IEvent"
19915	uuid="e90b8850-ac8e-4dff-8059-4100ae2c3c3d"
19916	wsmap="managed" autogen="VBoxEvent" id="OnDragAndDropModeChanged"
19917	>
19918	<desc>
19919	Notification when the drag'n'drop mode changes.
19920	</desc>
19921	<attribute name="dragAndDropMode" type="DragAndDropMode" readonly="yes">
19922	<desc>
19923	The new drag'n'drop mode.
19924	</desc>
19925	</attribute>
19926	</interface>
19927
19928	<interface
19929	name="ICPUChangedEvent" extends="IEvent"
19930	uuid="4da2dec7-71b2-4817-9a64-4ed12c17388e"
19931	wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
19932	>
19933	<desc>
19934	Notification when a CPU changes.
19935	</desc>
19936	<attribute name="CPU" type="unsigned long" readonly="yes">
19937	<desc>
19938	The CPU which changed.
19939	</desc>
19940	</attribute>
19941	<attribute name="add" type="boolean" readonly="yes">
19942	<desc>
19943	Flag whether the CPU was added or removed.
19944	</desc>
19945	</attribute>
19946	</interface>
19947
19948	<interface
19949	name="ICPUExecutionCapChangedEvent" extends="IEvent"
19950	uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
19951	wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
19952	>
19953	<desc>
19954	Notification when the CPU execution cap changes.
19955	</desc>
19956	<attribute name="executionCap" type="unsigned long" readonly="yes">
19957	<desc>
19958	The new CPU execution cap value. (1-100)
19959	</desc>
19960	</attribute>
19961	</interface>
19962
19963	<interface
19964	name="IGuestKeyboardEvent" extends="IEvent"
19965	uuid="88394258-7006-40d4-b339-472ee3801844"
19966	wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard"
19967	>
19968	<desc>
19969	Notification when guest keyboard event happens.
19970	</desc>
19971	<attribute name="scancodes" type="long" safearray="yes" readonly="yes">
19972	<desc>
19973	Array of scancodes.
19974	</desc>
19975	</attribute>
19976	</interface>
19977
19978	<interface
19979	name="IGuestMouseEvent" extends="IReusableEvent"
19980	uuid="1f85d35c-c524-40ff-8e98-307000df0992"
19981	wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse"
19982	>
19983	<desc>
19984	Notification when guest mouse event happens.
19985	</desc>
19986
19987	<attribute name="absolute" type="boolean" readonly="yes">
19988	<desc>
19989	If this event is relative or absolute.
19990	</desc>
19991	</attribute>
19992
19993	<attribute name="x" type="long" readonly="yes">
19994	<desc>
19995	New X position, or X delta.
19996	</desc>
19997	</attribute>
19998
19999	<attribute name="y" type="long" readonly="yes">
20000	<desc>
20001	New Y position, or Y delta.
20002	</desc>
20003	</attribute>
20004
20005	<attribute name="z" type="long" readonly="yes">
20006	<desc>
20007	Z delta.
20008	</desc>
20009	</attribute>
20010
20011	<attribute name="w" type="long" readonly="yes">
20012	<desc>
20013	W delta.
20014	</desc>
20015	</attribute>
20016
20017	<attribute name="buttons" type="long" readonly="yes">
20018	<desc>
20019	Button state bitmask.
20020	</desc>
20021	</attribute>
20022
20023	</interface>
20024
20025	<interface
20026	name="IGuestSessionEvent" extends="IEvent"
20027	uuid="b9acd33f-647d-45ac-8fe9-f49b3183ba37"
20028	wsmap="managed"
20029	>
20030	<desc>Base abstract interface for all guest session events.</desc>
20031
20032	<attribute name="session" type="IGuestSession" readonly="yes">
20033	<desc>Guest session that is subject to change.</desc>
20034	</attribute>
20035
20036	</interface>
20037
20038	<interface
20039	name="IGuestSessionStateChangedEvent" extends="IGuestSessionEvent"
20040	uuid="327e3c00-ee61-462f-aed3-0dff6cbf9904"
20041	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionStateChanged"
20042	>
20043	<desc>
20044	Notification when a guest session changed its state.
20045	</desc>
20046
20047	<attribute name="id" type="unsigned long" readonly="yes">
20048	<desc>
20049	Session ID of guest session which was changed.
20050	</desc>
20051	</attribute>
20052	<attribute name="status" type="GuestSessionStatus" readonly="yes">
20053	<desc>
20054	New session status.
20055	</desc>
20056	</attribute>
20057	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20058	<desc>
20059	Error information in case of new session status is indicating an error.
20060
20061	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20062	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20063	include/VBox/err.h for details.
20064	</desc>
20065	</attribute>
20066
20067	</interface>
20068
20069	<interface
20070	name="IGuestSessionRegisteredEvent" extends="IGuestSessionEvent"
20071	uuid="b79de686-eabd-4fa6-960a-f1756c99ea1c"
20072	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionRegistered"
20073	>
20074	<desc>
20075	Notification when a guest session was registered or unregistered.
20076	</desc>
20077
20078	<attribute name="registered" type="boolean" readonly="yes">
20079	<desc>
20080	If @c true, the guest session was registered, otherwise it was
20081	unregistered.
20082	</desc>
20083	</attribute>
20084
20085	</interface>
20086
20087	<interface
20088	name="IGuestProcessEvent" extends="IGuestSessionEvent"
20089	uuid="2405f0e5-6588-40a3-9b0a-68c05ba52c4b"
20090	wsmap="managed"
20091	>
20092	<desc>Base abstract interface for all guest process events.</desc>
20093
20094	<attribute name="process" type="IGuestProcess" readonly="yes">
20095	<desc>
20096	Guest process object which is related to this event.
20097	</desc>
20098	</attribute>
20099	<attribute name="pid" type="unsigned long" readonly="yes">
20100	<desc>
20101	Guest process ID (PID).
20102	</desc>
20103	</attribute>
20104
20105	</interface>
20106
20107	<interface
20108	name="IGuestProcessRegisteredEvent" extends="IGuestProcessEvent"
20109	uuid="1d89e2b3-c6ea-45b6-9d43-dc6f70cc9f02"
20110	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessRegistered"
20111	>
20112	<desc>
20113	Notification when a guest process was registered or unregistered.
20114	</desc>
20115
20116	<attribute name="registered" type="boolean" readonly="yes">
20117	<desc>
20118	If @c true, the guest process was registered, otherwise it was
20119	unregistered.
20120	</desc>
20121	</attribute>
20122
20123	</interface>
20124
20125	<interface
20126	name="IGuestProcessStateChangedEvent" extends="IGuestProcessEvent"
20127	uuid="c365fb7b-4430-499f-92c8-8bed814a567a"
20128	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessStateChanged"
20129	>
20130	<desc>
20131	Notification when a guest process changed its state.
20132	</desc>
20133
20134	<attribute name="status" type="ProcessStatus" readonly="yes">
20135	<desc>
20136	New guest process status.
20137	</desc>
20138	</attribute>
20139	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20140	<desc>
20141	Error information in case of new session status is indicating an error.
20142
20143	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20144	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20145	include/VBox/err.h for details.
20146	</desc>
20147	</attribute>
20148
20149	</interface>
20150
20151	<interface
20152	name="IGuestProcessIOEvent" extends="IGuestProcessEvent"
20153	uuid="9ea9227c-e9bb-49b3-bfc7-c5171e93ef38"
20154	wsmap="managed"
20155	>
20156	<desc>
20157	Base abstract interface for all guest process input/output (IO) events.
20158	</desc>
20159
20160	<attribute name="handle" type="unsigned long" readonly="yes">
20161	<desc>
20162	Input/output (IO) handle involved in this event. Usually 0 is stdin,
20163	1 is stdout and 2 is stderr.
20164	</desc>
20165	</attribute>
20166
20167	<attribute name="processed" type="unsigned long" readonly="yes">
20168	<desc>
20169	Processed input or output (in bytes).
20170	</desc>
20171	</attribute>
20172
20173	</interface>
20174
20175	<interface
20176	name="IGuestProcessInputNotifyEvent" extends="IGuestProcessIOEvent"
20177	uuid="0de887f2-b7db-4616-aac6-cfb94d89ba78"
20178	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessInputNotify"
20179	>
20180	<desc>
20181	Notification when a guest process' stdin became available.
20182	<note>This event is right now not implemented!</note>
20183	</desc>
20184
20185	<attribute name="status" type="ProcessInputStatus" readonly="yes">
20186	<desc>
20187	Current process input status.
20188	</desc>
20189	</attribute>
20190
20191	</interface>
20192
20193	<interface
20194	name="IGuestProcessOutputEvent" extends="IGuestProcessIOEvent"
20195	uuid="d3d5f1ee-bcb2-4905-a7ab-cc85448a742b"
20196	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessOutput"
20197	>
20198	<desc>
20199	Notification when there is guest process output available for reading.
20200	</desc>
20201
20202	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20203	<desc>
20204	Actual output data.
20205	</desc>
20206	</attribute>
20207
20208	</interface>
20209
20210	<interface
20211	name="IGuestFileEvent" extends="IGuestSessionEvent"
20212	uuid="c8adb7b0-057d-4391-b928-f14b06b710c5"
20213	wsmap="managed"
20214	>
20215	<desc>Base abstract interface for all guest file events.</desc>
20216
20217	<attribute name="file" type="IGuestFile" readonly="yes">
20218	<desc>
20219	Guest file object which is related to this event.
20220	</desc>
20221	</attribute>
20222
20223	</interface>
20224
20225	<interface
20226	name="IGuestFileRegisteredEvent" extends="IGuestFileEvent"
20227	uuid="d0d93830-70a2-487e-895e-d3fc9679f7b3"
20228	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRegistered"
20229	>
20230	<desc>
20231	Notification when a guest file was registered or unregistered.
20232	</desc>
20233
20234	<attribute name="registered" type="boolean" readonly="yes">
20235	<desc>
20236	If @c true, the guest file was registered, otherwise it was
20237	unregistered.
20238	</desc>
20239	</attribute>
20240
20241	</interface>
20242
20243	<interface
20244	name="IGuestFileStateChangedEvent" extends="IGuestFileEvent"
20245	uuid="d37fe88f-0979-486c-baa1-3abb144dc82d"
20246	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileStateChanged"
20247	>
20248	<desc>
20249	Notification when a guest file changed its state.
20250	</desc>
20251
20252	<attribute name="status" type="FileStatus" readonly="yes">
20253	<desc>
20254	New guest file status.
20255	</desc>
20256	</attribute>
20257	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20258	<desc>
20259	Error information in case of new session status is indicating an error.
20260
20261	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20262	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20263	include/VBox/err.h for details.
20264	</desc>
20265	</attribute>
20266	<!-- Note: No events for reads/writes for performance reasons.
20267	See dedidcated events IGuestFileReadEvent and
20268	IGuestFileWriteEvent. -->
20269
20270	</interface>
20271
20272	<interface
20273	name="IGuestFileIOEvent" extends="IGuestFileEvent"
20274	uuid="b5191a7c-9536-4ef8-820e-3b0e17e5bbc8"
20275	wsmap="managed"
20276	>
20277	<desc>
20278	Base abstract interface for all guest file input/output (IO) events.
20279	</desc>
20280
20281	<attribute name="offset" type="long long" readonly="yes">
20282	<desc>
20283	Current offset (in bytes).
20284	</desc>
20285	</attribute>
20286	<attribute name="processed" type="unsigned long" readonly="yes">
20287	<desc>
20288	Processed input or output (in bytes).
20289	</desc>
20290	</attribute>
20291
20292	</interface>
20293
20294	<interface
20295	name="IGuestFileOffsetChangedEvent" extends="IGuestFileIOEvent"
20296	uuid="e8f79a21-1207-4179-94cf-ca250036308f"
20297	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileOffsetChanged"
20298	>
20299	<desc>
20300	Notification when a guest file changed its current offset.
20301	</desc>
20302
20303	</interface>
20304
20305	<interface
20306	name="IGuestFileReadEvent" extends="IGuestFileIOEvent"
20307	uuid="4ee3cbcb-486f-40db-9150-deee3fd24189"
20308	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRead"
20309	>
20310	<desc>
20311	Notification when data has been read from a guest file.
20312	</desc>
20313
20314	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20315	<desc>
20316	Actual data read.
20317	</desc>
20318	</attribute>
20319
20320	</interface>
20321
20322	<interface
20323	name="IGuestFileWriteEvent" extends="IGuestFileIOEvent"
20324	uuid="e062a915-3cf5-4c0a-bc90-9b8d4cc94d89"
20325	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileWrite"
20326	>
20327	<desc>
20328	Notification when data has been written to a guest file.
20329	</desc>
20330
20331	</interface>
20332
20333	<interface
20334	name="IVRDEServerChangedEvent" extends="IEvent"
20335	uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
20336	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
20337	>
20338	<desc>
20339	Notification when a property of the
20340	<link to="IMachine::VRDEServer">VRDE server</link> changes.
20341	Interested callees should use IVRDEServer methods and attributes to
20342	find out what has changed.
20343	</desc>
20344	</interface>
20345
20346	<interface
20347	name="IVRDEServerInfoChangedEvent" extends="IEvent"
20348	uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
20349	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
20350	>
20351	<desc>
20352	Notification when the status of the VRDE server changes. Interested callees
20353	should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
20354	attributes to find out what is the current status.
20355	</desc>
20356	</interface>
20357
20358	<interface
20359	name="IVideoCaptureChangedEvent" extends="IEvent"
20360	uuid="6215d169-25dd-4719-ab34-c908701efb58"
20361	wsmap="managed" autogen="VBoxEvent" id="OnVideoCaptureChanged"
20362	>
20363	<desc>
20364	Notification when video capture settings have changed.
20365	</desc>
20366	</interface>
20367
20368	<interface
20369	name="IUSBControllerChangedEvent" extends="IEvent"
20370	uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
20371	wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
20372	>
20373	<desc>
20374	Notification when a property of the virtual
20375	<link to="IMachine::USBController">USB controller</link> changes.
20376	Interested callees should use IUSBController methods and attributes to
20377	find out what has changed.
20378	</desc>
20379	</interface>
20380
20381	<interface
20382	name="IUSBDeviceStateChangedEvent" extends="IEvent"
20383	uuid="806da61b-6679-422a-b629-51b06b0c6d93"
20384	wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
20385	>
20386	<desc>
20387	Notification when a USB device is attached to or detached from
20388	the virtual USB controller.
20389
20390	This notification is sent as a result of the indirect
20391	request to attach the device because it matches one of the
20392	machine USB filters, or as a result of the direct request
20393	issued by <link to="IConsole::attachUSBDevice"/> or
20394	<link to="IConsole::detachUSBDevice"/>.
20395
20396	This notification is sent in case of both a succeeded and a
20397	failed request completion. When the request succeeds, the
20398	@a error parameter is @c null, and the given device has been
20399	already added to (when @a attached is @c true) or removed from
20400	(when @a attached is @c false) the collection represented by
20401	<link to="IConsole::USBDevices"/>. On failure, the collection
20402	doesn't change and the @a error parameter represents the error
20403	message describing the failure.
20404	</desc>
20405	<attribute name="device" type="IUSBDevice" readonly="yes">
20406	<desc>
20407	Device that is subject to state change.
20408	</desc>
20409	</attribute>
20410	<attribute name="attached" type="boolean" readonly="yes">
20411	<desc>
20412	@c true if the device was attached and @c false otherwise.
20413	</desc>
20414	</attribute>
20415	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20416	<desc>
20417	@c null on success or an error message object on failure.
20418	</desc>
20419	</attribute>
20420	</interface>
20421
20422	<interface
20423	name="ISharedFolderChangedEvent" extends="IEvent"
20424	uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
20425	wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
20426	>
20427	<desc>
20428	Notification when a shared folder is added or removed.
20429	The @a scope argument defines one of three scopes:
20430	<link to="IVirtualBox::sharedFolders">global shared folders</link>
20431	(<link to="Scope_Global">Global</link>),
20432	<link to="IMachine::sharedFolders">permanent shared folders</link> of
20433	the machine (<link to="Scope_Machine">Machine</link>) or <link
20434	to="IConsole::sharedFolders">transient shared folders</link> of the
20435	machine (<link to="Scope_Session">Session</link>). Interested callees
20436	should use query the corresponding collections to find out what has
20437	changed.
20438	</desc>
20439	<attribute name="scope" type="Scope" readonly="yes">
20440	<desc>
20441	Scope of the notification.
20442	</desc>
20443	</attribute>
20444	</interface>
20445
20446	<interface
20447	name="IRuntimeErrorEvent" extends="IEvent"
20448	uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
20449	wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
20450	>
20451	<desc>
20452	Notification when an error happens during the virtual
20453	machine execution.
20454
20455	There are three kinds of runtime errors:
20456	<ul>
20457	<li><i>fatal</i></li>
20458	<li><i>non-fatal with retry</i></li>
20459	<li><i>non-fatal warnings</i></li>
20460	</ul>
20461
20462	<b>Fatal</b> errors are indicated by the @a fatal parameter set
20463	to @c true. In case of fatal errors, the virtual machine
20464	execution is always paused before calling this notification, and
20465	the notification handler is supposed either to immediately save
20466	the virtual machine state using <link to="IConsole::saveState"/>
20467	or power it off using <link to="IConsole::powerDown"/>.
20468	Resuming the execution can lead to unpredictable results.
20469
20470	<b>Non-fatal</b> errors and warnings are indicated by the
20471	@a fatal parameter set to @c false. If the virtual machine
20472	is in the Paused state by the time the error notification is
20473	received, it means that the user can <i>try to resume</i> the machine
20474	execution after attempting to solve the problem that caused the
20475	error. In this case, the notification handler is supposed
20476	to show an appropriate message to the user (depending on the
20477	value of the @a id parameter) that offers several actions such
20478	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
20479	wants to retry, the notification handler should continue
20480	the machine execution using the <link to="IConsole::resume"/>
20481	call. If the machine execution is not Paused during this
20482	notification, then it means this notification is a <i>warning</i>
20483	(for example, about a fatal condition that can happen very soon);
20484	no immediate action is required from the user, the machine
20485	continues its normal execution.
20486
20487	Note that in either case the notification handler
20488	<b>must not</b> perform any action directly on a thread
20489	where this notification is called. Everything it is allowed to
20490	do is to post a message to another thread that will then talk
20491	to the user and take the corresponding action.
20492
20493	Currently, the following error identifiers are known:
20494	<ul>
20495	<li><tt>"HostMemoryLow"</tt></li>
20496	<li><tt>"HostAudioNotResponding"</tt></li>
20497	<li><tt>"VDIStorageFull"</tt></li>
20498	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
20499	</ul>
20500	</desc>
20501	<attribute name="fatal" type="boolean" readonly="yes">
20502	<desc>
20503	Whether the error is fatal or not.
20504	</desc>
20505	</attribute>
20506	<attribute name="id" type="wstring" readonly="yes">
20507	<desc>
20508	Error identifier.
20509	</desc>
20510	</attribute>
20511	<attribute name="message" type="wstring" readonly="yes">
20512	<desc>
20513	Optional error message.
20514	</desc>
20515	</attribute>
20516	</interface>
20517
20518
20519	<interface
20520	name="IEventSourceChangedEvent" extends="IEvent"
20521	uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
20522	waitable="yes"
20523	wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
20524	>
20525	<desc>
20526	Notification when an event source state changes (listener added or removed).
20527	</desc>
20528
20529	<attribute name="listener" type="IEventListener" readonly="yes">
20530	<desc>
20531	Event listener which has changed.
20532	</desc>
20533	</attribute>
20534
20535	<attribute name="add" type="boolean" readonly="yes">
20536	<desc>
20537	Flag whether listener was added or removed.
20538	</desc>
20539	</attribute>
20540	</interface>
20541
20542	<interface
20543	name="IExtraDataChangedEvent" extends="IEvent"
20544	uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
20545	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
20546	>
20547	<desc>
20548	Notification when machine specific or global extra data
20549	has changed.
20550	</desc>
20551	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20552	<desc>
20553	ID of the machine this event relates to.
20554	Null for global extra data changes.
20555	</desc>
20556	</attribute>
20557	<attribute name="key" type="wstring" readonly="yes">
20558	<desc>
20559	Extra data key that has changed.
20560	</desc>
20561	</attribute>
20562	<attribute name="value" type="wstring" readonly="yes">
20563	<desc>
20564	Extra data value for the given key.
20565	</desc>
20566	</attribute>
20567	</interface>
20568
20569	<interface
20570	name="IVetoEvent" extends="IEvent"
20571	uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
20572	wsmap="managed"
20573	>
20574	<desc>Base abstract interface for veto events.</desc>
20575
20576	<method name="addVeto">
20577	<desc>
20578	Adds a veto on this event.
20579	</desc>
20580	<param name="reason" type="wstring" dir="in">
20581	<desc>
20582	Reason for veto, could be null or empty string.
20583	</desc>
20584	</param>
20585	</method>
20586
20587	<method name="isVetoed">
20588	<desc>
20589	If this event was vetoed.
20590	</desc>
20591	<param name="result" type="boolean" dir="return">
20592	<desc>
20593	Reason for veto.
20594	</desc>
20595	</param>
20596	</method>
20597
20598	<method name="getVetos">
20599	<desc>
20600	Current veto reason list, if size is 0 - no veto.
20601	</desc>
20602	<param name="result" type="wstring" dir="return" safearray="yes">
20603	<desc>
20604	Array of reasons for veto provided by different event handlers.
20605	</desc>
20606	</param>
20607	</method>
20608
20609	</interface>
20610
20611	<interface
20612	name="IExtraDataCanChangeEvent" extends="IVetoEvent"
20613	uuid="245d88bd-800a-40f8-87a6-170d02249a55"
20614	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
20615	waitable="true"
20616	>
20617	<desc>
20618	Notification when someone tries to change extra data for
20619	either the given machine or (if @c null) global extra data.
20620	This gives the chance to veto against changes.
20621	</desc>
20622	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20623	<desc>
20624	ID of the machine this event relates to.
20625	Null for global extra data changes.
20626	</desc>
20627	</attribute>
20628	<attribute name="key" type="wstring" readonly="yes">
20629	<desc>
20630	Extra data key that has changed.
20631	</desc>
20632	</attribute>
20633	<attribute name="value" type="wstring" readonly="yes">
20634	<desc>
20635	Extra data value for the given key.
20636	</desc>
20637	</attribute>
20638	</interface>
20639
20640	<interface
20641	name="ICanShowWindowEvent" extends="IVetoEvent"
20642	uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
20643	wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
20644	waitable="true"
20645	>
20646	<desc>
20647	Notification when a call to
20648	<link to="IMachine::canShowConsoleWindow"/> is made by a
20649	front-end to check if a subsequent call to
20650	<link to="IMachine::showConsoleWindow"/> can succeed.
20651
20652	The callee should give an answer appropriate to the current
20653	machine state using event veto. This answer must
20654	remain valid at least until the next
20655	<link to="IConsole::state">machine state</link> change.
20656	</desc>
20657	</interface>
20658
20659	<interface
20660	name="IShowWindowEvent" extends="IEvent"
20661	uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
20662	wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
20663	waitable="true"
20664	>
20665	<desc>
20666	Notification when a call to
20667	<link to="IMachine::showConsoleWindow"/>
20668	requests the console window to be activated and brought to
20669	foreground on the desktop of the host PC.
20670
20671	This notification should cause the VM console process to
20672	perform the requested action as described above. If it is
20673	impossible to do it at a time of this notification, this
20674	method should return a failure.
20675
20676	Note that many modern window managers on many platforms
20677	implement some sort of focus stealing prevention logic, so
20678	that it may be impossible to activate a window without the
20679	help of the currently active application (which is supposedly
20680	an initiator of this notification). In this case, this method
20681	must return a non-zero identifier that represents the
20682	top-level window of the VM console process. The caller, if it
20683	represents a currently active process, is responsible to use
20684	this identifier (in a platform-dependent manner) to perform
20685	actual window activation.
20686
20687	This method must set @a winId to zero if it has performed all
20688	actions necessary to complete the request and the console
20689	window is now active and in foreground, to indicate that no
20690	further action is required on the caller's side.
20691	</desc>
20692	<attribute name="winId" type="long long">
20693	<desc>
20694	Platform-dependent identifier of the top-level VM console
20695	window, or zero if this method has performed all actions
20696	necessary to implement the <i>show window</i> semantics for
20697	the given platform and/or this VirtualBox front-end.
20698	</desc>
20699	</attribute>
20700	</interface>
20701
20702	<interface
20703	name="INATRedirectEvent" extends="IMachineEvent"
20704	uuid="24eef068-c380-4510-bc7c-19314a7352f1"
20705	wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect"
20706	>
20707	<desc>
20708	Notification when NAT redirect rule added or removed.
20709	</desc>
20710	<attribute name="slot" type="unsigned long" readonly="yes">
20711	<desc>
20712	Adapter which NAT attached to.
20713	</desc>
20714	</attribute>
20715	<attribute name="remove" type="boolean" readonly="yes">
20716	<desc>
20717	Whether rule remove or add.
20718	</desc>
20719	</attribute>
20720	<attribute name="name" type="wstring" readonly="yes">
20721	<desc>
20722	Name of the rule.
20723	</desc>
20724	</attribute>
20725	<attribute name="proto" type="NATProtocol" readonly="yes">
20726	<desc>
20727	Protocol (TCP or UDP) of the redirect rule.
20728	</desc>
20729	</attribute>
20730	<attribute name="hostIP" type="wstring" readonly="yes">
20731	<desc>
20732	Host ip address to bind socket on.
20733	</desc>
20734	</attribute>
20735	<attribute name="hostPort" type="long" readonly="yes">
20736	<desc>
20737	Host port to bind socket on.
20738	</desc>
20739	</attribute>
20740	<attribute name="guestIP" type="wstring" readonly="yes">
20741	<desc>
20742	Guest ip address to redirect to.
20743	</desc>
20744	</attribute>
20745	<attribute name="guestPort" type="long" readonly="yes">
20746	<desc>
20747	Guest port to redirect to.
20748	</desc>
20749	</attribute>
20750	</interface>
20751
20752	<interface
20753	name="IHostPCIDevicePlugEvent" extends="IMachineEvent"
20754	waitable="yes"
20755	uuid="a0bad6df-d612-47d3-89d4-db3992533948"
20756	wsmap="managed" autogen="VBoxEvent" id="OnHostPCIDevicePlug"
20757	>
20758	<desc>
20759	Notification when host PCI device is plugged/unplugged. Plugging
20760	usually takes place on VM startup, unplug - when
20761	<link to="IMachine::detachHostPCIDevice"/> is called.
20762
20763	<see><link to="IMachine::detachHostPCIDevice"/></see>
20764
20765	</desc>
20766
20767	<attribute name="plugged" type="boolean" readonly="yes">
20768	<desc>
20769	If device successfully plugged or unplugged.
20770	</desc>
20771	</attribute>
20772
20773	<attribute name="success" type="boolean" readonly="yes">
20774	<desc>
20775	If operation was successful, if false - 'message' attribute
20776	may be of interest.
20777	</desc>
20778	</attribute>
20779
20780	<attribute name="attachment" type="IPCIDeviceAttachment" readonly="yes">
20781	<desc>
20782	Attachment info for this device.
20783	</desc>
20784	</attribute>
20785
20786	<attribute name="message" type="wstring" readonly="yes">
20787	<desc>
20788	Optional error message.
20789	</desc>
20790	</attribute>
20791
20792	</interface>
20793
20794	<interface
20795	name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent"
20796	uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc"
20797	wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged"
20798	>
20799	<desc>
20800	Notification when VBoxSVC becomes unavailable (due to a crash or similar
20801	unexpected circumstances) or available again.
20802	</desc>
20803
20804	<attribute name="available" type="boolean" readonly="yes">
20805	<desc>
20806	Whether VBoxSVC is available now.
20807	</desc>
20808	</attribute>
20809	</interface>
20810
20811	<interface
20812	name="IBandwidthGroupChangedEvent" extends="IEvent"
20813	uuid="334df94a-7556-4cbc-8c04-043096b02d82"
20814	wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged"
20815	>
20816	<desc>
20817	Notification when one of the bandwidth groups changed
20818	</desc>
20819	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
20820	<desc>
20821	The changed bandwidth group.
20822	</desc>
20823	</attribute>
20824	</interface>
20825
20826	<enum
20827	name="GuestMonitorChangedEventType"
20828	uuid="ef172985-7e36-4297-95be-e46396968d66"
20829	>
20830
20831	<desc>
20832	How the guest monitor has been changed.
20833	</desc>
20834
20835	<const name="Enabled" value="0">
20836	<desc>
20837	The guest monitor has been enabled by the guest.
20838	</desc>
20839	</const>
20840
20841	<const name="Disabled" value="1">
20842	<desc>
20843	The guest monitor has been disabled by the guest.
20844	</desc>
20845	</const>
20846
20847	<const name="NewOrigin" value="2">
20848	<desc>
20849	The guest monitor origin has changed in the guest.
20850	</desc>
20851	</const>
20852	</enum>
20853
20854	<interface
20855	name="IGuestMonitorChangedEvent" extends="IEvent"
20856	uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090"
20857	wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged"
20858	>
20859	<desc>
20860	Notification when the guest enables one of its monitors.
20861	</desc>
20862
20863	<attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes">
20864	<desc>
20865	What was changed for this guest monitor.
20866	</desc>
20867	</attribute>
20868
20869	<attribute name="screenId" type="unsigned long" readonly="yes">
20870	<desc>
20871	The monitor which was changed.
20872	</desc>
20873	</attribute>
20874
20875	<attribute name="originX" type="unsigned long" readonly="yes">
20876	<desc>
20877	Physical X origin relative to the primary screen.
20878	Valid for Enabled and NewOrigin.
20879	</desc>
20880	</attribute>
20881
20882	<attribute name="originY" type="unsigned long" readonly="yes">
20883	<desc>
20884	Physical Y origin relative to the primary screen.
20885	Valid for Enabled and NewOrigin.
20886	</desc>
20887	</attribute>
20888
20889	<attribute name="width" type="unsigned long" readonly="yes">
20890	<desc>
20891	Width of the screen.
20892	Valid for Enabled.
20893	</desc>
20894	</attribute>
20895
20896	<attribute name="height" type="unsigned long" readonly="yes">
20897	<desc>
20898	Height of the screen.
20899	Valid for Enabled.
20900	</desc>
20901	</attribute>
20902
20903	</interface>
20904
20905	<interface
20906	name="IStorageDeviceChangedEvent" extends="IEvent"
20907	uuid="232e9151-ae84-4b8e-b0f3-5c20c35caac9"
20908	wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged"
20909	>
20910	<desc>
20911	Notification when a
20912	<link to="IMachine::mediumAttachments">storage device</link>
20913	is attached or removed.
20914	</desc>
20915	<attribute name="storageDevice" type="IMediumAttachment" readonly="yes">
20916	<desc>
20917	Storage device that is subject to change.
20918	</desc>
20919	</attribute>
20920	<attribute name="removed" type="boolean" readonly="yes">
20921	<desc>
20922	Flag whether the device was removed or added to the VM.
20923	</desc>
20924	</attribute>
20925	<attribute name="silent" type="boolean" readonly="yes">
20926	<desc>
20927	Flag whether the guest should be notified about the change.
20928	</desc>
20929	</attribute>
20930	</interface>
20931	<interface
20932	name="INATNetworkChangedEvent" extends="IEvent"
20933	uuid="101ae042-1a29-4a19-92cf-02285773f3b5"
20934	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkChanged"
20935	>
20936	<!-- network name is common setting for all event types -->
20937	<attribute name="NetworkName" type="wstring" readonly="yes"/>
20938	</interface>
20939	<!-- base class for start/stop events -->
20940	<interface name="INATNetworkStartStopEvent" extends="INATNetworkChangedEvent"
20941	uuid="269d8f6b-fa1e-4cee-91c7-6d8496bea3c1"
20942	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkStartStop">
20943	<attribute name="startEvent" type="boolean" readonly="yes">
20944	<desc>
20945	IsStartEvent is true when NAT network is started and false on stopping.
20946	</desc>
20947	</attribute>
20948	</interface>
20949
20950	<!-- base class for modification events -->
20951	<interface name="INATNetworkAlterEvent" extends="INATNetworkChangedEvent"
20952	uuid="3f5a0822-163a-43b1-ad16-8d58b0ef6e75"
20953	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkAlter"/>
20954
20955	<interface name="INATNetworkCreationDeletionEvent" extends="INATNetworkAlterEvent"
20956	uuid="8d984a7e-b855-40b8-ab0c-44d3515b4528"
20957	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkCreationDeletion">
20958	<attribute name="creationEvent" type="boolean" readonly="yes"/>
20959	</interface>
20960	<interface name="INATNetworkSettingEvent" extends="INATNetworkAlterEvent"
20961	uuid="9db3a9e6-7f29-4aae-a627-5a282c83092c"
20962	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkSetting">
20963	<attribute name="enabled" type="boolean" readonly="yes"/>
20964	<attribute name="network" type="wstring" readonly="yes"/>
20965	<attribute name="gateway" type="wstring" readonly="yes"/>
20966	<attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" readonly="yes"/>
20967	<attribute name="needDhcpServer" type="boolean" readonly="yes"/>
20968	</interface>
20969	<interface name="INATNetworkPortForwardEvent" extends="INATNetworkAlterEvent"
20970	uuid="2514881b-23d0-430a-a7ff-7ed7f05534bc"
20971	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkPortForward">
20972	<attribute name="create" type="boolean" readonly="yes"/>
20973	<attribute name="ipv6" type="boolean" readonly="yes"/>
20974	<attribute name="name" type="wstring" readonly="yes"/>
20975	<attribute name="proto" type="NATProtocol" readonly="yes"/>
20976	<attribute name="hostIp" type="wstring" readonly="yes"/>
20977	<attribute name="hostPort" type="long" readonly="yes"/>
20978	<attribute name="guestIp" type="wstring" readonly="yes"/>
20979	<attribute name="guestPort" type="long" readonly="yes"/>
20980	</interface>
20981
20982	<module name="VBoxSVC" context="LocalServer">
20983	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
20984	namespace="virtualbox.org">
20985	<interface name="IVirtualBox" default="yes"/>
20986	</class>
20987	</module>
20988
20989	<module name="VBoxC" context="InprocServer" threadingModel="Free">
20990	<class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba"
20991	namespace="virtualbox.org">
20992	<interface name="IVirtualBoxClient" default="yes"/>
20993	</class>
20994
20995	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
20996	namespace="virtualbox.org">
20997	<interface name="ISession" default="yes"/>
20998	</class>
20999	</module>
21000
21001	</library>
21002
21003	</idl>
21004
21005	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format