VirtualBox.xidl@ 46155

Last change on this file since 46155 was 46123, checked in by vboxsync, 12 years ago
Main/VPX, VBoxManage: added IMachine::VideoCaptureScreens and IDisplay::{enableVideoCapture,disableVideoCapture}
Property svn:eol-style set to `native`
File size: 758.2 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.</desc>
1030	</const>
1031	<const name="Shared" value="1">
1032	<desc>Request only a shared read lock for remote-controlling the machine.</desc>
1033	</const>
1034	<const name="VM" value="3">
1035	<desc>Lock the machine for writing, and create objects necessary for
1036	running a VM in this process.</desc>
1037	</const>
1038	</enum>
1039
1040	<enum
1041	name="SessionType"
1042	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
1043	>
1044	<desc>
1045	Session type. This enumeration represents possible values of the
1046	<link to="ISession::type"/> attribute.
1047	</desc>
1048
1049	<const name="Null" value="0">
1050	<desc>Null value (never used by the API).</desc>
1051	</const>
1052	<const name="WriteLock" value="1">
1053	<desc>
1054	Session has acquired an exclusive write lock on a machine
1055	using <link to="IMachine::lockMachine"/>.
1056	</desc>
1057	</const>
1058	<const name="Remote" value="2">
1059	<desc>
1060	Session has launched a VM process using
1061	<link to="IMachine::launchVMProcess"/>
1062	</desc>
1063	</const>
1064	<const name="Shared" value="3">
1065	<desc>
1066	Session has obtained a link to another session using
1067	<link to="IMachine::lockMachine"/>
1068	</desc>
1069	</const>
1070	</enum>
1071
1072	<enum
1073	name="DeviceType"
1074	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
1075	>
1076	<desc>
1077	Device type.
1078	</desc>
1079	<const name="Null" value="0">
1080	<desc>
1081	Null value, may also mean "no device" (not allowed for
1082	<link to="IConsole::getDeviceActivity"/>).
1083	</desc>
1084	</const>
1085	<const name="Floppy" value="1">
1086	<desc>Floppy device.</desc>
1087	</const>
1088	<const name="DVD" value="2">
1089	<desc>CD/DVD-ROM device.</desc>
1090	</const>
1091	<const name="HardDisk" value="3">
1092	<desc>Hard disk device.</desc>
1093	</const>
1094	<const name="Network" value="4">
1095	<desc>Network device.</desc>
1096	</const>
1097	<const name="USB" value="5">
1098	<desc>USB device.</desc>
1099	</const>
1100	<const name="SharedFolder" value="6">
1101	<desc>Shared folder device.</desc>
1102	</const>
1103	</enum>
1104
1105	<enum
1106	name="DeviceActivity"
1107	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
1108	>
1109	<desc>
1110	Device activity for <link to="IConsole::getDeviceActivity"/>.
1111	</desc>
1112
1113	<const name="Null" value="0"/>
1114	<const name="Idle" value="1"/>
1115	<const name="Reading" value="2"/>
1116	<const name="Writing" value="3"/>
1117	</enum>
1118
1119	<enum
1120	name="ClipboardMode"
1121	uuid="33364716-4008-4701-8f14-be0fa3d62950"
1122	>
1123	<desc>
1124	Host-Guest clipboard interchange mode.
1125	</desc>
1126
1127	<const name="Disabled" value="0"/>
1128	<const name="HostToGuest" value="1"/>
1129	<const name="GuestToHost" value="2"/>
1130	<const name="Bidirectional" value="3"/>
1131	</enum>
1132
1133	<enum
1134	name="DragAndDropMode"
1135	uuid="b618ea0e-b6fb-4f8d-97f7-5e237e49b547"
1136	>
1137	<desc>
1138	Drag'n'Drop interchange mode.
1139	</desc>
1140
1141	<const name="Disabled" value="0"/>
1142	<const name="HostToGuest" value="1"/>
1143	<const name="GuestToHost" value="2"/>
1144	<const name="Bidirectional" value="3"/>
1145	</enum>
1146
1147	<enum
1148	name="Scope"
1149	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
1150	>
1151	<desc>
1152	Scope of the operation.
1153
1154	A generic enumeration used in various methods to define the action or
1155	argument scope.
1156	</desc>
1157
1158	<const name="Global" value="0"/>
1159	<const name="Machine" value="1"/>
1160	<const name="Session" value="2"/>
1161	</enum>
1162
1163	<enum
1164	name="BIOSBootMenuMode"
1165	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1166	>
1167	<desc>
1168	BIOS boot menu mode.
1169	</desc>
1170
1171	<const name="Disabled" value="0"/>
1172	<const name="MenuOnly" value="1"/>
1173	<const name="MessageAndMenu" value="2"/>
1174	</enum>
1175
1176	<enum
1177	name="ProcessorFeature"
1178	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1179	>
1180	<desc>
1181	CPU features.
1182	</desc>
1183
1184	<const name="HWVirtEx" value="0"/>
1185	<const name="PAE" value="1"/>
1186	<const name="LongMode" value="2"/>
1187	<const name="NestedPaging" value="3"/>
1188	</enum>
1189
1190	<enum
1191	name="FirmwareType"
1192	uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1193	>
1194	<desc>
1195	Firmware type.
1196	</desc>
1197	<const name="BIOS" value="1">
1198	<desc>BIOS Firmware.</desc>
1199	</const>
1200	<const name="EFI" value="2">
1201	<desc>EFI Firmware, bitness detected basing on OS type.</desc>
1202	</const>
1203	<const name="EFI32" value="3">
1204	<desc>Efi firmware, 32-bit.</desc>
1205	</const>
1206	<const name="EFI64" value="4">
1207	<desc>Efi firmware, 64-bit.</desc>
1208	</const>
1209	<const name="EFIDUAL" value="5">
1210	<desc>Efi firmware, combined 32 and 64-bit.</desc>
1211	</const>
1212	</enum>
1213
1214	<enum
1215	name="PointingHIDType"
1216	uuid="e44b2f7b-72ba-44fb-9e53-2186014f0d17"
1217	>
1218	<desc>
1219	Type of pointing device used in a virtual machine.
1220	</desc>
1221	<const name="None" value="1">
1222	<desc>No mouse.</desc>
1223	</const>
1224	<const name="PS2Mouse" value="2">
1225	<desc>PS/2 auxiliary device, a.k.a. mouse.</desc>
1226	</const>
1227	<const name="USBMouse" value="3">
1228	<desc>USB mouse (relative pointer).</desc>
1229	</const>
1230	<const name="USBTablet" value="4">
1231	<desc>USB tablet (absolute pointer).</desc>
1232	</const>
1233	<const name="ComboMouse" value="5">
1234	<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1235	Using of such device can have negative performance implications. </desc>
1236	</const>
1237	</enum>
1238
1239	<enum
1240	name="KeyboardHIDType"
1241	uuid="383e43d7-5c7c-4ec8-9cb8-eda1bccd6699"
1242	>
1243	<desc>
1244	Type of keyboard device used in a virtual machine.
1245	</desc>
1246	<const name="None" value="1">
1247	<desc>No keyboard.</desc>
1248	</const>
1249	<const name="PS2Keyboard" value="2">
1250	<desc>PS/2 keyboard.</desc>
1251	</const>
1252	<const name="USBKeyboard" value="3">
1253	<desc>USB keyboard.</desc>
1254	</const>
1255	<const name="ComboKeyboard" value="4">
1256	<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1257	Using of such device can have negative performance implications. </desc>
1258	</const>
1259	</enum>
1260
1261	<!--
1262	// IVirtualBoxErrorInfo
1263	/////////////////////////////////////////////////////////////////////////
1264	-->
1265
1266	<interface
1267	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1268	uuid="c1bcc6d5-7966-481d-ab0b-d0ed73e28135"
1269	supportsErrorInfo="no"
1270	wsmap="managed"
1271	>
1272	<desc>
1273	The IVirtualBoxErrorInfo interface represents extended error information.
1274
1275	Extended error information can be set by VirtualBox components after
1276	unsuccessful or partially successful method invocation. This information
1277	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1278	and then shown to the client in addition to the plain 32-bit result code.
1279
1280	In MS COM, this interface extends the IErrorInfo interface,
1281	in XPCOM, it extends the nsIException interface. In both cases,
1282	it provides a set of common attributes to retrieve error
1283	information.
1284
1285	Sometimes invocation of some component's method may involve methods of
1286	other components that may also fail (independently of this method's
1287	failure), or a series of non-fatal errors may precede a fatal error that
1288	causes method failure. In cases like that, it may be desirable to preserve
1289	information about all errors happened during method invocation and deliver
1290	it to the caller. The <link to="#next"/> attribute is intended
1291	specifically for this purpose and allows to represent a chain of errors
1292	through a single IVirtualBoxErrorInfo object set after method invocation.
1293
1294	<note>errors are stored to a chain in the reverse order, i.e. the
1295	initial error object you query right after method invocation is the last
1296	error set by the callee, the object it points to in the @a next attribute
1297	is the previous error and so on, up to the first error (which is the last
1298	in the chain).</note>
1299	</desc>
1300
1301	<attribute name="resultCode" type="long" readonly="yes">
1302	<desc>
1303	Result code of the error.
1304	Usually, it will be the same as the result code returned
1305	by the method that provided this error information, but not
1306	always. For example, on Win32, CoCreateInstance() will most
1307	likely return E_NOINTERFACE upon unsuccessful component
1308	instantiation attempt, but not the value the component factory
1309	returned. Value is typed 'long', not 'result',
1310	to make interface usable from scripting languages.
1311	<note>
1312	In MS COM, there is no equivalent.
1313	In XPCOM, it is the same as nsIException::result.
1314	</note>
1315	</desc>
1316	</attribute>
1317
1318	<attribute name="resultDetail" type="long" readonly="yes">
1319	<desc>
1320	Optional result data of this error. This will vary depending on the
1321	actual error usage. By default this attribute is not being used.
1322	</desc>
1323	</attribute>
1324
1325	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1326	<desc>
1327	UUID of the interface that defined the error.
1328	<note>
1329	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1330	data type.
1331	In XPCOM, there is no equivalent.
1332	</note>
1333	</desc>
1334	</attribute>
1335
1336	<attribute name="component" type="wstring" readonly="yes">
1337	<desc>
1338	Name of the component that generated the error.
1339	<note>
1340	In MS COM, it is the same as IErrorInfo::GetSource.
1341	In XPCOM, there is no equivalent.
1342	</note>
1343	</desc>
1344	</attribute>
1345
1346	<attribute name="text" type="wstring" readonly="yes">
1347	<desc>
1348	Text description of the error.
1349	<note>
1350	In MS COM, it is the same as IErrorInfo::GetDescription.
1351	In XPCOM, it is the same as nsIException::message.
1352	</note>
1353	</desc>
1354	</attribute>
1355
1356	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1357	<desc>
1358	Next error object if there is any, or @c null otherwise.
1359	<note>
1360	In MS COM, there is no equivalent.
1361	In XPCOM, it is the same as nsIException::inner.
1362	</note>
1363	</desc>
1364	</attribute>
1365
1366	</interface>
1367
1368	<!--
1369	// IVirtualBox
1370	/////////////////////////////////////////////////////////////////////////
1371	-->
1372	<!-- This is experimental interface to LWIP based NAT server -->
1373	<interface name="INATNetwork" extends="$unknown"
1374	uuid="03DFD6F7-1B78-48A3-8345-C785281E9523"
1375	wsmap="managed">
1376	<attribute name="NetworkName" type="wstring">
1377	<desc>
1378	TBD: the idea, technically we can start any number of the NAT networks,
1379	but we should expect that at some point we will get collisions because of
1380	port-forwanding rules. so perhaps we should support only single instance of NAT
1381	network.
1382	</desc>
1383	</attribute>
1384	<attribute name="enabled" type="boolean"/>
1385	<attribute name="network" type="wstring">
1386	<desc>
1387	This is CIDR IPv4 string. Specifiying it user defines IPv4 addresses
1388	of gateway (low address + 1) and dhcp server (= low address + 2).
1389	Note: if there're defined IPv4 port-forward rules update of network
1390	will be ignored (because new assignment could break existing rules).
1391	</desc>
1392	</attribute>
1393	<attribute name="gateway" type="wstring" readonly="yes">
1394	<desc>
1395	This attribute is read-only. It's recalculated on changing
1396	network attribute (low address of network + 1).
1397	</desc>
1398	</attribute>
1399	<attribute name="IPv6Enabled" type="boolean">
1400	<desc>
1401	This attribute define whether gateway will support IPv6 or not.
1402	</desc>
1403	</attribute>
1404	<attribute name="IPv6Prefix" type="wstring">
1405	<desc>
1406	This a CIDR IPv6 defining prefix for link-local addresses autoconfiguration within network. Note: ignored if attribute ipv6enabled is false.
1407	</desc>
1408	</attribute>
1409	<attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean"/>
1410	<attribute name="needDhcpServer" type="boolean"/>
1411	<attribute name="eventSource" type="IEventSource" readonly="yes"/>
1412	<attribute name="portForwardRules4" type="wstring" readonly="yes" safearray="yes">
1413	<desc>Array of NAT port-forwarding rules in string representation,
1414	in the following format:
1415	"name:protocolid:[host ip]:host port:[guest ip]:guest port".
1416	</desc>
1417	</attribute>
1418	<attribute name="portForwardRules6" type="wstring" readonly="yes" safearray="yes">
1419	<desc>Array of NAT port-forwarding rules in string representation, in the
1420	following format: "name:protocolid:[host ip]:host port:[guest ip]:guest port".
1421	</desc>
1422	</attribute>
1423	<method name="addPortForwardRule">
1424	<param name="isIpv6" type="boolean" dir="in"/>
1425	<param name="ruleName" type="wstring" dir="in"/>
1426	<param name="proto" type="NATProtocol" dir="in">
1427	<desc>Protocol handled with the rule.</desc>
1428	</param>
1429	<param name="hostIP" type="wstring" dir="in">
1430	<desc>IP of the host interface to which the rule should apply.
1431	An empty ip address is acceptable, in which case the NAT engine
1432	binds the handling socket to any interface.
1433	</desc>
1434	</param>
1435	<param name="hostPort" type="unsigned short" dir="in">
1436	<desc>The port number to listen on.</desc>
1437	</param>
1438	<param name="guestIP" type="wstring" dir="in">
1439	<desc>The IP address of the guest which the NAT engine will forward
1440	matching packets to. An empty IP address is not acceptable.</desc>
1441	</param>
1442	<param name="guestPort" type="unsigned short" dir="in">
1443	<desc>The port number to forward.</desc>
1444	</param>
1445	</method>
1446	<method name="removePortForwardRule">
1447	<param name="iSipv6" type="boolean" dir="in"/>
1448	<param name="ruleName" type="wstring" dir="in"/>
1449	</method>
1450	<method name="start">
1451	<param name="trunkType" type="wstring" dir="in">
1452	<desc>
1453	Type of internal network trunk.
1454	</desc>
1455	</param>
1456	</method>
1457	<method name="stop"/>
1458	</interface>
1459
1460	<interface
1461	name="IDHCPServer" extends="$unknown"
1462	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1463	wsmap="managed"
1464	>
1465	<desc>
1466	The IDHCPServer interface represents the vbox DHCP server configuration.
1467
1468	To enumerate all the DHCP servers on the host, use the
1469	<link to="IVirtualBox::DHCPServers"/> attribute.
1470	</desc>
1471
1472	<attribute name="enabled" type="boolean">
1473	<desc>
1474	specifies if the DHCP server is enabled
1475	</desc>
1476	</attribute>
1477
1478	<attribute name="IPAddress" type="wstring" readonly="yes">
1479	<desc>
1480	specifies server IP
1481	</desc>
1482	</attribute>
1483
1484	<attribute name="networkMask" type="wstring" readonly="yes">
1485	<desc>
1486	specifies server network mask
1487	</desc>
1488	</attribute>
1489
1490	<attribute name="networkName" type="wstring" readonly="yes">
1491	<desc>
1492	specifies internal network name the server is used for
1493	</desc>
1494	</attribute>
1495
1496	<attribute name="lowerIP" type="wstring" readonly="yes">
1497	<desc>
1498	specifies from IP address in server address range
1499	</desc>
1500	</attribute>
1501
1502	<attribute name="upperIP" type="wstring" readonly="yes">
1503	<desc>
1504	specifies to IP address in server address range
1505	</desc>
1506	</attribute>
1507
1508	<method name="setConfiguration">
1509	<desc>
1510	configures the server
1511	<result name="E_INVALIDARG">
1512	invalid configuration supplied
1513	</result>
1514	</desc>
1515	<param name="IPAddress" type="wstring" dir="in">
1516	<desc>
1517	server IP address
1518	</desc>
1519	</param>
1520	<param name="networkMask" type="wstring" dir="in">
1521	<desc>
1522	server network mask
1523	</desc>
1524	</param>
1525	<param name="FromIPAddress" type="wstring" dir="in">
1526	<desc>
1527	server From IP address for address range
1528	</desc>
1529	</param>
1530	<param name="ToIPAddress" type="wstring" dir="in">
1531	<desc>
1532	server To IP address for address range
1533	</desc>
1534	</param>
1535	</method>
1536
1537	<method name="start">
1538	<desc>
1539	Starts DHCP server process.
1540	<result name="E_FAIL">
1541	Failed to start the process.
1542	</result>
1543	</desc>
1544	<param name="networkName" type="wstring" dir="in">
1545	<desc>
1546	Name of internal network DHCP server should attach to.
1547	</desc>
1548	</param>
1549	<param name="trunkName" type="wstring" dir="in">
1550	<desc>
1551	Name of internal network trunk.
1552	</desc>
1553	</param>
1554	<param name="trunkType" type="wstring" dir="in">
1555	<desc>
1556	Type of internal network trunk.
1557	</desc>
1558	</param>
1559	</method>
1560
1561	<method name="stop">
1562	<desc>
1563	Stops DHCP server process.
1564	<result name="E_FAIL">
1565	Failed to stop the process.
1566	</result>
1567	</desc>
1568	</method>
1569	</interface>
1570
1571	<interface
1572	name="IVirtualBox" extends="$unknown"
1573	uuid="fafa4e17-1ee2-4905-a10e-fe7c18bf5554"
1574	wsmap="managed"
1575	>
1576	<desc>
1577	The IVirtualBox interface represents the main interface exposed by the
1578	product that provides virtual machine management.
1579
1580	An instance of IVirtualBox is required for the product to do anything
1581	useful. Even though the interface does not expose this, internally,
1582	IVirtualBox is implemented as a singleton and actually lives in the
1583	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1584	IVirtualBox can track the state of all virtual machines on a particular
1585	host, regardless of which frontend started them.
1586
1587	To enumerate all the virtual machines on the host, use the
1588	<link to="IVirtualBox::machines"/> attribute.
1589	</desc>
1590
1591	<attribute name="version" type="wstring" readonly="yes">
1592	<desc>
1593	A string representing the version number of the product. The
1594	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1595	last number represents the build number and will frequently change.
1596
1597	This may be followed by a _ALPHA[0-9], _BETA[0-9] or _RC[0-9]* tag
1598	in prerelease builds. Non-Oracle builds may (/shall) also have a
1599	publisher tag, at the end. The publisher tag starts with an underscore
1600	just like the prerelease build type tag.
1601	</desc>
1602	</attribute>
1603
1604	<attribute name="versionNormalized" type="wstring" readonly="yes">
1605	<desc>
1606	A string representing the version number of the product,
1607	without the publisher information (but still with other tags).
1608	See <link to="#version" />.
1609	</desc>
1610	</attribute>
1611
1612	<attribute name="revision" type="unsigned long" readonly="yes">
1613	<desc>
1614	The internal build revision number of the product.
1615	</desc>
1616	</attribute>
1617
1618	<attribute name="packageType" type="wstring" readonly="yes">
1619	<desc>
1620	A string representing the package type of this product. The
1621	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1622	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1623	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1624	this.
1625	</desc>
1626	</attribute>
1627
1628	<attribute name="APIVersion" type="wstring" readonly="yes">
1629	<desc>
1630	A string representing the VirtualBox API version number. The format is
1631	2 integer numbers divided by an underscore (e.g. 1_0). After the
1632	first public release of packages with a particular API version the
1633	API will not be changed in an incompatible way. Note that this
1634	guarantee does not apply to development builds, and also there is no
1635	guarantee that this version is identical to the first two integer
1636	numbers of the package version.
1637	</desc>
1638	</attribute>
1639
1640	<attribute name="homeFolder" type="wstring" readonly="yes">
1641	<desc>
1642	Full path to the directory where the global settings file,
1643	<tt>VirtualBox.xml</tt>, is stored.
1644
1645	In this version of VirtualBox, the value of this property is
1646	always <tt><user_dir>/.VirtualBox</tt> (where
1647	<tt><user_dir></tt> is the path to the user directory,
1648	as determined by the host OS), and cannot be changed.
1649
1650	This path is also used as the base to resolve relative paths in
1651	places where relative paths are allowed (unless otherwise
1652	expressly indicated).
1653	</desc>
1654	</attribute>
1655
1656	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1657	<desc>
1658	Full name of the global settings file.
1659	The value of this property corresponds to the value of
1660	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1661	</desc>
1662	</attribute>
1663
1664	<attribute name="host" type="IHost" readonly="yes">
1665	<desc>Associated host object.</desc>
1666	</attribute>
1667
1668	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1669	<desc>Associated system information object.</desc>
1670	</attribute>
1671
1672	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1673	<desc>
1674	Array of machine objects registered within this VirtualBox instance.
1675	</desc>
1676	</attribute>
1677
1678	<attribute name="machineGroups" type="wstring" readonly="yes" safearray="yes">
1679	<desc>
1680	Array of all machine group names which are used by the machines which
1681	are accessible. Each group is only listed once, however they are listed
1682	in no particular order and there is no guarantee that there are no gaps
1683	in the group hierarchy (i.e. <tt>"/"</tt>, <tt>"/group/subgroup"</tt>
1684	is a valid result).
1685	</desc>
1686	</attribute>
1687
1688	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1689	<desc>
1690	Array of medium objects known to this VirtualBox installation.
1691
1692	This array contains only base media. All differencing
1693	media of the given base medium can be enumerated using
1694	<link to="IMedium::children"/>.
1695	</desc>
1696	</attribute>
1697
1698	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1699	<desc>
1700	Array of CD/DVD image objects currently in use by this VirtualBox instance.
1701	</desc>
1702	</attribute>
1703
1704	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1705	<desc>
1706	Array of floppy image objects currently in use by this VirtualBox instance.
1707	</desc>
1708	</attribute>
1709
1710	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1711
1712	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1713
1714	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1715	<desc>
1716	Collection of global shared folders. Global shared folders are
1717	available to all virtual machines.
1718
1719	New shared folders are added to the collection using
1720	<link to="#createSharedFolder"/>. Existing shared folders can be
1721	removed using <link to="#removeSharedFolder"/>.
1722
1723	<note>
1724	In the current version of the product, global shared folders are not
1725	implemented and therefore this collection is always empty.
1726	</note>
1727	</desc>
1728	</attribute>
1729
1730	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1731	<desc>
1732	Associated performance collector object.
1733	</desc>
1734	</attribute>
1735
1736	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1737	<desc>
1738	DHCP servers.
1739	</desc>
1740	</attribute>
1741	<!-- Array of NAT networks -->
1742	<attribute name="NATNetworks" type="INATNetwork" safearray="yes" readonly="yes"/>
1743
1744	<attribute name="eventSource" type="IEventSource" readonly="yes">
1745	<desc>
1746	Event source for VirtualBox events.
1747	</desc>
1748	</attribute>
1749
1750	<attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">
1751	<desc>
1752	The extension pack manager.
1753	</desc>
1754	</attribute>
1755
1756
1757	<attribute name="internalNetworks" type="wstring" safearray="yes" readonly="yes">
1758	<desc>
1759	Names of all internal networks.
1760	</desc>
1761	</attribute>
1762
1763	<attribute name="genericNetworkDrivers" type="wstring" safearray="yes" readonly="yes">
1764	<desc>
1765	Names of all generic network drivers.
1766	</desc>
1767	</attribute>
1768
1769	<method name="composeMachineFilename">
1770	<desc>
1771	Returns a recommended full path of the settings file name for a new virtual
1772	machine.
1773
1774	This API serves two purposes:
1775
1776	<ul>
1777	<li>It gets called by <link to="#createMachine" /> if @c null or
1778	empty string (which is recommended) is specified for the
1779	@a settingsFile argument there, which means that API should use
1780	a recommended default file name.</li>
1781
1782	<li>It can be called manually by a client software before creating a machine,
1783	e.g. if that client wants to pre-create the machine directory to create
1784	virtual hard disks in that directory together with the new machine
1785	settings file. In that case, the file name should be stripped from the
1786	full settings file path returned by this function to obtain the
1787	machine directory.</li>
1788	</ul>
1789
1790	See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
1791	details about the machine name.
1792
1793	@a groupName defines which additional subdirectory levels should be
1794	included. It must be either a valid group name or @c null or empty
1795	string which designates that the machine will not be related to a
1796	machine group.
1797
1798	If @a baseFolder is a @c null or empty string (which is recommended), the
1799	default machine settings folder
1800	(see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
1801	a base folder for the created machine, resulting in a file name like
1802	"/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
1803	will be used.
1804
1805	This method does not access the host disks. In particular, it does not check
1806	for whether a machine with this name already exists.
1807	</desc>
1808	<param name="name" type="wstring" dir="in">
1809	<desc>Suggested machine name.</desc>
1810	</param>
1811	<param name="group" type="wstring" dir="in">
1812	<desc>Machine group name for the new machine or machine group. It is
1813	used to determine the right subdirectory.</desc>
1814	</param>
1815	<param name="createFlags" type="wstring" dir="in">
1816	<desc>Machine creation flags, see <link to="#createMachine" /> (optional).</desc>
1817	</param>
1818	<param name="baseFolder" type="wstring" dir="in">
1819	<desc>Base machine folder (optional).</desc>
1820	</param>
1821	<param name="file" type="wstring" dir="return">
1822	<desc>Fully qualified path where the machine would be created.</desc>
1823	</param>
1824	</method>
1825
1826	<method name="createMachine">
1827	<desc>
1828	Creates a new virtual machine by creating a machine settings file at
1829	the given location.
1830
1831	VirtualBox machine settings files use a custom XML dialect. Starting
1832	with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
1833	and machine files can be created at arbitrary locations.
1834
1835	However, it is recommended that machines are created in the default
1836	machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
1837	<link to="ISystemProperties::defaultMachineFolder" />). If you specify
1838	@c null or empty string (which is recommended) for the @a settingsFile
1839	argument, <link to="#composeMachineFilename" /> is called automatically
1840	to have such a recommended name composed based on the machine name
1841	given in the @a name argument and the primary group.
1842
1843	If the resulting settings file already exists, this method will fail,
1844	unless the forceOverwrite flag is set.
1845
1846	The new machine is created unregistered, with the initial configuration
1847	set according to the specified guest OS type. A typical sequence of
1848	actions to create a new virtual machine is as follows:
1849
1850	<ol>
1851	<li>
1852	Call this method to have a new machine created. The returned machine
1853	object will be "mutable" allowing to change any machine property.
1854	</li>
1855
1856	<li>
1857	Configure the machine using the appropriate attributes and methods.
1858	</li>
1859
1860	<li>
1861	Call <link to="IMachine::saveSettings" /> to write the settings
1862	to the machine's XML settings file. The configuration of the newly
1863	created machine will not be saved to disk until this method is
1864	called.
1865	</li>
1866
1867	<li>
1868	Call <link to="#registerMachine" /> to add the machine to the list
1869	of machines known to VirtualBox.
1870	</li>
1871	</ol>
1872
1873	The specified guest OS type identifier must match an ID of one of known
1874	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1875	array.
1876
1877	<note>
1878	There is no way to change the name of the settings file or
1879	subfolder of the created machine directly.
1880	</note>
1881
1882	<result name="VBOX_E_OBJECT_NOT_FOUND">
1883	@a osTypeId is invalid.
1884	</result>
1885	<result name="VBOX_E_FILE_ERROR">
1886	Resulting settings file name is invalid or the settings file already
1887	exists or could not be created due to an I/O error.
1888	</result>
1889	<result name="E_INVALIDARG">
1890	@a name is empty or @c null.
1891	</result>
1892	</desc>
1893
1894	<param name="settingsFile" type="wstring" dir="in">
1895	<desc>Fully qualified path where the settings file should be created,
1896	empty string or @c null for a default folder and file based on the
1897	@a name argument and the primary group.
1898	(see <link to="#composeMachineFilename" />).</desc>
1899	</param>
1900	<param name="name" type="wstring" dir="in">
1901	<desc>Machine name.</desc>
1902	</param>
1903	<param name="groups" type="wstring" safearray="yes" dir="in">
1904	<desc>Array of group names. @c null or an empty array have the same
1905	meaning as an array with just the empty string or <tt>"/"</tt>, i.e.
1906	create a machine without group association.</desc>
1907	</param>
1908	<param name="osTypeId" type="wstring" dir="in">
1909	<desc>Guest OS Type ID.</desc>
1910	</param>
1911	<param name="flags" type="wstring" dir="in">
1912	<desc>
1913	Additional property parameters, passed as a comma-separated list of
1914	"name=value" type entries. The following ones are recognized:
1915	<tt>forceOverwrite=1</tt> to overwrite an existing machine settings
1916	file, <tt>UUID=<uuid></tt> to specify a machine UUID and
1917	<tt>directoryIncludesUUID=1</tt> to switch to a special VM directory
1918	naming scheme which should not be used unless necessary.
1919	</desc>
1920	</param>
1921	<param name="machine" type="IMachine" dir="return">
1922	<desc>Created machine object.</desc>
1923	</param>
1924	</method>
1925
1926	<method name="openMachine">
1927	<desc>
1928	Opens a virtual machine from the existing settings file.
1929	The opened machine remains unregistered until you call
1930	<link to="#registerMachine"/>.
1931
1932	The specified settings file name must be fully qualified.
1933	The file must exist and be a valid machine XML settings file
1934	whose contents will be used to construct the machine object.
1935
1936	<result name="VBOX_E_FILE_ERROR">
1937	Settings file name invalid, not found or sharing violation.
1938	</result>
1939	</desc>
1940	<param name="settingsFile" type="wstring" dir="in">
1941	<desc>
1942	Name of the machine settings file.
1943	</desc>
1944	</param>
1945	<param name="machine" type="IMachine" dir="return">
1946	<desc>Opened machine object.</desc>
1947	</param>
1948	<note>
1949	<link to="IMachine::settingsModified"/> will return
1950	@c false for the created machine, until any of machine settings
1951	are changed.
1952	</note>
1953	</method>
1954
1955	<method name="registerMachine">
1956	<desc>
1957
1958	Registers the machine previously created using
1959	<link to="#createMachine"/> or opened using
1960	<link to="#openMachine"/> within this VirtualBox installation. After
1961	successful method invocation, the
1962	<link to="IMachineRegisteredEvent"/> event is fired.
1963
1964	<note>
1965	This method implicitly calls <link to="IMachine::saveSettings"/>
1966	to save all current machine settings before registering it.
1967	</note>
1968
1969	<result name="VBOX_E_OBJECT_NOT_FOUND">
1970	No matching virtual machine found.
1971	</result>
1972	<result name="VBOX_E_INVALID_OBJECT_STATE">
1973	Virtual machine was not created within this VirtualBox instance.
1974	</result>
1975
1976	</desc>
1977	<param name="machine" type="IMachine" dir="in"/>
1978	</method>
1979
1980	<method name="findMachine">
1981	<desc>
1982	Attempts to find a virtual machine given its name or UUID.
1983
1984	<note>Inaccessible machines cannot be found by name, only by UUID, because their name
1985	cannot safely be determined.</note>
1986
1987	<result name="VBOX_E_OBJECT_NOT_FOUND">
1988	Could not find registered machine matching @a nameOrId.
1989	</result>
1990
1991	</desc>
1992	<param name="nameOrId" type="wstring" dir="in">
1993	<desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>
1994	</param>
1995	<param name="machine" type="IMachine" dir="return">
1996	<desc>Machine object, if found.</desc>
1997	</param>
1998	</method>
1999
2000	<method name="getMachinesByGroups">
2001	<desc>
2002	Gets all machine references which are in one of the specified groups.
2003	</desc>
2004	<param name="groups" type="wstring" dir="in" safearray="yes">
2005	<desc>What groups to match. The usual group list rules apply, i.e.
2006	passing an empty list will match VMs in the toplevel group, likewise
2007	the empty string.</desc>
2008	</param>
2009	<param name="machines" type="IMachine" dir="return" safearray="yes">
2010	<desc>All machines which matched.</desc>
2011	</param>
2012	</method>
2013
2014	<method name="getMachineStates">
2015	<desc>
2016	Gets the state of several machines in a single operation.
2017	</desc>
2018	<param name="machines" type="IMachine" dir="in" safearray="yes">
2019	<desc>Array with the machine references.</desc>
2020	</param>
2021	<param name="states" type="MachineState" dir="return" safearray="yes">
2022	<desc>Machine states, corresponding to the machines.</desc>
2023	</param>
2024	</method>
2025
2026	<method name="createAppliance">
2027	<desc>
2028	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
2029	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
2030	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
2031	</desc>
2032	<param name="appliance" type="IAppliance" dir="return">
2033	<desc>New appliance.</desc>
2034	</param>
2035	</method>
2036
2037	<method name="createHardDisk">
2038	<desc>
2039	Creates a new base medium object that will use the given storage
2040	format and location for medium data.
2041
2042	The actual storage unit is not created by this method. In order to
2043	do it, and before you are able to attach the created medium to
2044	virtual machines, you must call one of the following methods to
2045	allocate a format-specific storage unit at the specified location:
2046	<ul>
2047	<li><link to="IMedium::createBaseStorage"/></li>
2048	<li><link to="IMedium::createDiffStorage"/></li>
2049	</ul>
2050
2051	Some medium attributes, such as <link to="IMedium::id"/>, may
2052	remain uninitialized until the medium storage unit is successfully
2053	created by one of the above methods.
2054
2055	After the storage unit is successfully created, it will be
2056	accessible through the <link to="#openMedium"/> method and can
2057	be found in the <link to="#hardDisks"/> array.
2058
2059	The list of all storage formats supported by this VirtualBox
2060	installation can be obtained using
2061	<link to="ISystemProperties::mediumFormats"/>. If the @a format
2062	attribute is empty or @c null then the default storage format
2063	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
2064	be used for creating a storage unit of the medium.
2065
2066	Note that the format of the location string is storage format specific.
2067	See <link to="IMedium::location"/> and IMedium for more details.
2068
2069	<result name="VBOX_E_OBJECT_NOT_FOUND">
2070	@a format identifier is invalid. See
2071	<link to="ISystemProperties::mediumFormats"/>.
2072	</result>
2073	<result name="VBOX_E_FILE_ERROR">
2074	@a location is a not valid file name (for file-based formats only).
2075	</result>
2076	</desc>
2077	<param name="format" type="wstring" dir="in">
2078	<desc>
2079	Identifier of the storage format to use for the new medium.
2080	</desc>
2081	</param>
2082	<param name="location" type="wstring" dir="in">
2083	<desc>
2084	Location of the storage unit for the new medium.
2085	</desc>
2086	</param>
2087	<param name="medium" type="IMedium" dir="return">
2088	<desc>Created medium object.</desc>
2089	</param>
2090	</method>
2091
2092	<method name="openMedium">
2093	<desc>
2094	Finds existing media or opens a medium from an existing storage location.
2095
2096	Once a medium has been opened, it can be passed to other VirtualBox
2097	methods, in particular to <link to="IMachine::attachDevice" />.
2098
2099	Depending on the given device type, the file at the storage location
2100	must be in one of the media formats understood by VirtualBox:
2101
2102	<ul>
2103	<li>With a "HardDisk" device type, the file must be a hard disk image
2104	in one of the formats supported by VirtualBox (see
2105	<link to="ISystemProperties::mediumFormats" />).
2106	After this method succeeds, if the medium is a base medium, it
2107	will be added to the <link to="#hardDisks"/> array attribute. </li>
2108	<li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
2109	After this method succeeds, the medium will be added to the
2110	<link to="#DVDImages"/> array attribute.</li>
2111	<li>With a "Floppy" device type, the file must be an RAW floppy image.
2112	After this method succeeds, the medium will be added to the
2113	<link to="#floppyImages"/> array attribute.</li>
2114	</ul>
2115
2116	After having been opened, the medium can be re-found by this method
2117	and can be attached to virtual machines. See <link to="IMedium" /> for
2118	more details.
2119
2120	The UUID of the newly opened medium will either be retrieved from the
2121	storage location, if the format supports it (e.g. for hard disk images),
2122	or a new UUID will be randomly generated (e.g. for ISO and RAW files).
2123	If for some reason you need to change the medium's UUID, use
2124	<link to="IMedium::setIds" />.
2125
2126	If a differencing hard disk medium is to be opened by this method, the
2127	operation will succeed only if its parent medium and all ancestors,
2128	if any, are already known to this VirtualBox installation (for example,
2129	were opened by this method before).
2130
2131	This method attempts to guess the storage format of the specified medium
2132	by reading medium data at the specified location.
2133
2134	If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
2135	the image is opened for read/write access and must have according permissions,
2136	as VirtualBox may actually write status information into the disk's metadata
2137	sections.
2138
2139	Note that write access is required for all typical hard disk usage in VirtualBox,
2140	since VirtualBox may need to write metadata such as a UUID into the image.
2141	The only exception is opening a source image temporarily for copying and
2142	cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
2143	again soon.
2144
2145	The format of the location string is storage format specific. See
2146	<link to="IMedium::location"/> and IMedium for more details.
2147
2148	<result name="VBOX_E_FILE_ERROR">
2149	Invalid medium storage file location or could not find the medium
2150	at the specified location.
2151	</result>
2152	<result name="VBOX_E_IPRT_ERROR">
2153	Could not get medium storage format.
2154	</result>
2155	<result name="E_INVALIDARG">
2156	Invalid medium storage format.
2157	</result>
2158	<result name="VBOX_E_INVALID_OBJECT_STATE">
2159	Medium has already been added to a media registry.
2160	</result>
2161	</desc>
2162	<param name="location" type="wstring" dir="in">
2163	<desc>
2164	Location of the storage unit that contains medium data in one of
2165	the supported storage formats.
2166	</desc>
2167	</param>
2168	<param name="deviceType" type="DeviceType" dir="in">
2169	<desc>
2170	Must be one of "HardDisk", "DVD" or "Floppy".
2171	</desc>
2172	</param>
2173	<param name="accessMode" type="AccessMode" dir="in">
2174	<desc>Whether to open the image in read/write or read-only mode. For
2175	a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
2176	</param>
2177	<param name="forceNewUuid" type="boolean" dir="in">
2178	<desc>Allows the caller to request a completely new medium UUID for
2179	the image which is to be opened. Useful if one intends to open an exact
2180	copy of a previously opened image, as this would normally fail due to
2181	the duplicate UUID.</desc>
2182	</param>
2183	<param name="medium" type="IMedium" dir="return">
2184	<desc>Opened medium object.</desc>
2185	</param>
2186	</method>
2187
2188	<method name="getGuestOSType">
2189	<desc>
2190	Returns an object describing the specified guest OS type.
2191
2192	The requested guest OS type is specified using a string which is a
2193	mnemonic identifier of the guest operating system, such as
2194	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2195	particular virtual machine can be read or set using the
2196	<link to="IMachine::OSTypeId"/> attribute.
2197
2198	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2199	available guest OS type objects. Each object has an
2200	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2201	the guest OS this object describes.
2202
2203	<result name="E_INVALIDARG">
2204	@a id is not a valid Guest OS type.
2205	</result>
2206
2207	</desc>
2208	<param name="id" type="uuid" mod="string" dir="in">
2209	<desc>Guest OS type ID string.</desc>
2210	</param>
2211	<param name="type" type="IGuestOSType" dir="return">
2212	<desc>Guest OS type object.</desc>
2213	</param>
2214	</method>
2215
2216	<method name="createSharedFolder">
2217	<desc>
2218	Creates a new global shared folder by associating the given logical
2219	name with the given host path, adds it to the collection of shared
2220	folders and starts sharing it. Refer to the description of
2221	<link to="ISharedFolder"/> to read more about logical names.
2222	<note>
2223	In the current implementation, this operation is not
2224	implemented.
2225	</note>
2226	</desc>
2227	<param name="name" type="wstring" dir="in">
2228	<desc>Unique logical name of the shared folder.</desc>
2229	</param>
2230	<param name="hostPath" type="wstring" dir="in">
2231	<desc>Full path to the shared folder in the host file system.</desc>
2232	</param>
2233	<param name="writable" type="boolean" dir="in">
2234	<desc>Whether the share is writable or readonly</desc>
2235	</param>
2236	<param name="automount" type="boolean" dir="in">
2237	<desc>Whether the share gets automatically mounted by the guest
2238	or not.</desc>
2239	</param>
2240	</method>
2241
2242	<method name="removeSharedFolder">
2243	<desc>
2244	Removes the global shared folder with the given name previously
2245	created by <link to="#createSharedFolder"/> from the collection of
2246	shared folders and stops sharing it.
2247	<note>
2248	In the current implementation, this operation is not
2249	implemented.
2250	</note>
2251	</desc>
2252	<param name="name" type="wstring" dir="in">
2253	<desc>Logical name of the shared folder to remove.</desc>
2254	</param>
2255	</method>
2256
2257	<method name="getExtraDataKeys">
2258	<desc>
2259	Returns an array representing the global extra data keys which currently
2260	have values defined.
2261	</desc>
2262	<param name="keys" type="wstring" dir="return" safearray="yes">
2263	<desc>Array of extra data keys.</desc>
2264	</param>
2265	</method>
2266
2267	<method name="getExtraData">
2268	<desc>
2269	Returns associated global extra data.
2270
2271	If the requested data @a key does not exist, this function will
2272	succeed and return an empty string in the @a value argument.
2273
2274	<result name="VBOX_E_FILE_ERROR">
2275	Settings file not accessible.
2276	</result>
2277	<result name="VBOX_E_XML_ERROR">
2278	Could not parse the settings file.
2279	</result>
2280
2281	</desc>
2282	<param name="key" type="wstring" dir="in">
2283	<desc>Name of the data key to get.</desc>
2284	</param>
2285	<param name="value" type="wstring" dir="return">
2286	<desc>Value of the requested data key.</desc>
2287	</param>
2288	</method>
2289
2290	<method name="setExtraData">
2291	<desc>
2292	Sets associated global extra data.
2293
2294	If you pass @c null or empty string as a key @a value, the given @a key
2295	will be deleted.
2296
2297	<note>
2298	Before performing the actual data change, this method will ask all
2299	registered event listener using the
2300	<link to="IExtraDataCanChangeEvent"/>
2301	notification for a permission. If one of the listeners refuses the
2302	new value, the change will not be performed.
2303	</note>
2304	<note>
2305	On success, the
2306	<link to="IExtraDataChangedEvent"/> notification
2307	is called to inform all registered listeners about a successful data
2308	change.
2309	</note>
2310
2311	<result name="VBOX_E_FILE_ERROR">
2312	Settings file not accessible.
2313	</result>
2314	<result name="VBOX_E_XML_ERROR">
2315	Could not parse the settings file.
2316	</result>
2317	<result name="E_ACCESSDENIED">
2318	Modification request refused.
2319	</result>
2320
2321	</desc>
2322	<param name="key" type="wstring" dir="in">
2323	<desc>Name of the data key to set.</desc>
2324	</param>
2325	<param name="value" type="wstring" dir="in">
2326	<desc>Value to assign to the key.</desc>
2327	</param>
2328	</method>
2329
2330	<method name="setSettingsSecret">
2331	<desc>
2332	Unlocks the secret data by passing the unlock password to the
2333	server. The server will cache the password for that machine.
2334
2335	<result name="VBOX_E_INVALID_VM_STATE">
2336	Virtual machine is not mutable.
2337	</result>
2338
2339	</desc>
2340	<param name="password" type="wstring" dir="in">
2341	<desc>
2342	The cipher key.
2343	</desc>
2344	</param>
2345	</method>
2346
2347	<!--method name="createDHCPServerForInterface">
2348	<desc>
2349	Creates a DHCP server settings to be used for the given interface
2350	<result name="E_INVALIDARG">
2351	Host network interface @a name already exists.
2352	</result>
2353	</desc>
2354	<param name="interface" type="IHostNetworkInterface" dir="in">
2355	<desc>Network Interface</desc>
2356	</param>
2357	<param name="server" type="IDHCPServer" dir="out">
2358	<desc>DHCP server settings</desc>
2359	</param>
2360	</method-->
2361
2362	<method name="createDHCPServer">
2363	<desc>
2364	Creates a DHCP server settings to be used for the given internal network name
2365	<result name="E_INVALIDARG">
2366	Host network interface @a name already exists.
2367	</result>
2368	</desc>
2369	<param name="name" type="wstring" dir="in">
2370	<desc>server name</desc>
2371	</param>
2372	<param name="server" type="IDHCPServer" dir="return">
2373	<desc>DHCP server settings</desc>
2374	</param>
2375	</method>
2376
2377	<method name="findDHCPServerByNetworkName">
2378	<desc>
2379	Searches a DHCP server settings to be used for the given internal network name
2380	<result name="E_INVALIDARG">
2381	Host network interface @a name already exists.
2382	</result>
2383
2384	</desc>
2385	<param name="name" type="wstring" dir="in">
2386	<desc>server name</desc>
2387	</param>
2388	<param name="server" type="IDHCPServer" dir="return">
2389	<desc>DHCP server settings</desc>
2390	</param>
2391	</method>
2392
2393	<!--method name="findDHCPServerForInterface">
2394	<desc>
2395	Searches a DHCP server settings to be used for the given interface
2396	<result name="E_INVALIDARG">
2397	Host network interface @a name already exists.
2398	</result>
2399	</desc>
2400	<param name="interface" type="IHostNetworkInterface" dir="in">
2401	<desc>Network Interface</desc>
2402	</param>
2403	<param name="server" type="IDHCPServer" dir="out">
2404	<desc>DHCP server settings</desc>
2405	</param>
2406	</method-->
2407
2408	<method name="removeDHCPServer">
2409	<desc>
2410	Removes the DHCP server settings
2411	<result name="E_INVALIDARG">
2412	Host network interface @a name already exists.
2413	</result>
2414	</desc>
2415	<param name="server" type="IDHCPServer" dir="in">
2416	<desc>DHCP server settings to be removed</desc>
2417	</param>
2418	</method>
2419
2420	<!-- bunch of metods to create NAT -->
2421	<method name="createNATNetwork">
2422	<!-- Here we create a record in NAT network array with name
2423	and gateway/network parameters this information should
2424	be enough for VBoxNet[Lwip]NAT and VBoxNetDHCP for
2425	servicing the guests.
2426	-->
2427	<param name="networkName" type="wstring" dir="in"/>
2428	<param name="network" type="INATNetwork" dir="return"/>
2429	</method>
2430
2431	<!--
2432	Returns the NATNetwork by name, e.g. for adding porforward rule or delition.
2433	-->
2434	<method name="findNATNetworkByName">
2435	<param name="networkName" type="wstring" dir="in"/>
2436	<param name="network" type="INATNetwork" dir="return"/>
2437	</method>
2438	<!--
2439	Deletes given NAT network.
2440	-->
2441	<method name="removeNATNetwork">
2442	<param name="network" type="INATNetwork" dir="in"/>
2443	</method>
2444
2445	<method name="checkFirmwarePresent">
2446	<desc>
2447	Check if this VirtualBox installation has a firmware
2448	of the given type available, either system-wide or per-user.
2449	Optionally, this may return a hint where this firmware can be
2450	downloaded from.
2451	</desc>
2452	<param name="firmwareType" type="FirmwareType" dir="in">
2453	<desc>
2454	Type of firmware to check.
2455	</desc>
2456	</param>
2457	<param name="version" type="wstring" dir="in">
2458	<desc>Expected version number, usually empty string (presently ignored).</desc>
2459	</param>
2460
2461	<param name="url" type="wstring" dir="out">
2462	<desc>
2463	Suggested URL to download this firmware from.
2464	</desc>
2465	</param>
2466
2467	<param name="file" type="wstring" dir="out">
2468	<desc>
2469	Filename of firmware, only valid if result == TRUE.
2470	</desc>
2471	</param>
2472
2473	<param name="result" type="boolean" dir="return">
2474	<desc>If firmware of this type and version is available.</desc>
2475	</param>
2476	</method>
2477
2478	</interface>
2479
2480	<!--
2481	// IVFSExplorer
2482	/////////////////////////////////////////////////////////////////////////
2483	-->
2484
2485	<enum
2486	name="VFSType"
2487	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
2488	>
2489	<desc>
2490	Virtual file systems supported by VFSExplorer.
2491	</desc>
2492
2493	<const name="File" value="1" />
2494	<const name="Cloud" value="2" />
2495	<const name="S3" value="3" />
2496	<const name="WebDav" value="4" />
2497	</enum>
2498
2499	<enum
2500	name="VFSFileType"
2501	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
2502	>
2503	<desc>
2504	File types known by VFSExplorer.
2505	</desc>
2506
2507	<const name="Unknown" value="1" />
2508	<const name="Fifo" value="2" />
2509	<const name="DevChar" value="3" />
2510	<const name="Directory" value="4" />
2511	<const name="DevBlock" value="5" />
2512	<const name="File" value="6" />
2513	<const name="SymLink" value="7" />
2514	<const name="Socket" value="8" />
2515	<const name="WhiteOut" value="9" />
2516	</enum>
2517
2518	<interface
2519	name="IVFSExplorer" extends="$unknown"
2520	uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"
2521	wsmap="managed"
2522	>
2523	<desc>
2524	The VFSExplorer interface unifies access to different file system
2525	types. This includes local file systems as well remote file systems like
2526	S3. For a list of supported types see <link to="VFSType" />.
2527	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
2528	</desc>
2529
2530	<attribute name="path" type="wstring" readonly="yes">
2531	<desc>Returns the current path in the virtual file system.</desc>
2532	</attribute>
2533
2534	<attribute name="type" type="VFSType" readonly="yes">
2535	<desc>Returns the file system type which is currently in use.</desc>
2536	</attribute>
2537
2538	<method name="update">
2539	<desc>Updates the internal list of files/directories from the
2540	current directory level. Use <link to="#entryList" /> to get the full list
2541	after a call to this method.</desc>
2542
2543	<param name="progress" type="IProgress" dir="return">
2544	<desc>Progress object to track the operation completion.</desc>
2545	</param>
2546	</method>
2547
2548	<method name="cd">
2549	<desc>Change the current directory level.</desc>
2550
2551	<param name="dir" type="wstring" dir="in">
2552	<desc>The name of the directory to go in.</desc>
2553	</param>
2554
2555	<param name="progress" type="IProgress" dir="return">
2556	<desc>Progress object to track the operation completion.</desc>
2557	</param>
2558	</method>
2559
2560	<method name="cdUp">
2561	<desc>Go one directory upwards from the current directory level.</desc>
2562
2563	<param name="progress" type="IProgress" dir="return">
2564	<desc>Progress object to track the operation completion.</desc>
2565	</param>
2566	</method>
2567
2568	<method name="entryList">
2569	<desc>Returns a list of files/directories after a call to <link
2570	to="#update" />. The user is responsible for keeping this internal
2571	list up do date.</desc>
2572
2573	<param name="names" type="wstring" safearray="yes" dir="out">
2574	<desc>The list of names for the entries.</desc>
2575	</param>
2576
2577	<param name="types" type="unsigned long" safearray="yes" dir="out">
2578	<desc>The list of types for the entries.</desc>
2579	</param>
2580
2581	<param name="sizes" type="unsigned long" safearray="yes" dir="out">
2582	<desc>The list of sizes (in bytes) for the entries.</desc>
2583	</param>
2584
2585	<param name="modes" type="unsigned long" safearray="yes" dir="out">
2586	<desc>The list of file modes (in octal form) for the entries.</desc>
2587	</param>
2588	</method>
2589
2590	<method name="exists">
2591	<desc>Checks if the given file list exists in the current directory
2592	level.</desc>
2593
2594	<param name="names" type="wstring" safearray="yes" dir="in">
2595	<desc>The names to check.</desc>
2596	</param>
2597
2598	<param name="exists" type="wstring" safearray="yes" dir="return">
2599	<desc>The names which exist.</desc>
2600	</param>
2601	</method>
2602
2603	<method name="remove">
2604	<desc>Deletes the given files in the current directory level.</desc>
2605
2606	<param name="names" type="wstring" safearray="yes" dir="in">
2607	<desc>The names to remove.</desc>
2608	</param>
2609
2610	<param name="progress" type="IProgress" dir="return">
2611	<desc>Progress object to track the operation completion.</desc>
2612	</param>
2613	</method>
2614
2615	</interface>
2616
2617	<enum
2618	name="ImportOptions" extends="$unknown"
2619	uuid="0a981523-3b20-4004-8ee3-dfd322202ace"
2620	>
2621
2622	<desc>
2623	Import options, used with <link to="IAppliance::importMachines" />.
2624	</desc>
2625
2626	<const name="KeepAllMACs" value="1">
2627	<desc>Don't generate new MAC addresses of the attached network adapters.</desc>
2628	</const>
2629	<const name="KeepNATMACs" value="2">
2630	<desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
2631	</const>
2632
2633	</enum>
2634
2635
2636	<!--
2637	// IAppliance
2638	/////////////////////////////////////////////////////////////////////////
2639	-->
2640
2641	<interface
2642	name="IAppliance" extends="$unknown"
2643	uuid="3059cf9e-25c7-4f0b-9fa5-3c42e441670b"
2644	wsmap="managed"
2645	>
2646	<desc>
2647	Represents a platform-independent appliance in OVF format. An instance of this is returned
2648	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
2649	virtual machines within an appliance with VirtualBox.
2650
2651	The OVF standard suggests two different physical file formats:
2652
2653	<ol>
2654	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
2655	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
2656	this descriptor file references other files such as disk images, as OVF appliances typically
2657	do, those additional files must be in the same directory as the descriptor file.</li>
2658
2659	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
2660	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
2661	files and optionally other files.
2662
2663	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
2664	be added with a later version.</li>
2665	</ol>
2666
2667	<b>Importing</b> an OVF appliance into VirtualBox as instances of
2668	<link to="IMachine" /> involves the following sequence of API calls:
2669
2670	<ol>
2671	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
2672	</li>
2673
2674	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
2675	would like to import. So long as this file is syntactically valid, this will succeed
2676	and fill the appliance object with the parsed data from the OVF file.
2677	</li>
2678
2679	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
2680	contents of the IAppliance attributes accordingly. These can be inspected by a
2681	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
2682	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
2683	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
2684	systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
2685	by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
2686	The GUI can then give the user the option to confirm and/or change these suggestions.
2687	</li>
2688
2689	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2690	virtual system (machine) to override the suggestions made by the <link to="#interpret" /> routine.
2691	</li>
2692
2693	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
2694	VirtualBox as instances of <link to="IMachine" /> that match the information in the
2695	virtual system descriptions. After this call succeeded, the UUIDs of the machines created
2696	can be found in the <link to="#machines" /> array attribute.
2697	</li>
2698	</ol>
2699
2700	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
2701
2702	<ol>
2703	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
2704	an empty IAppliance object.
2705	</li>
2706
2707	<li>For each machine you would like to export, call <link to="IMachine::exportTo" />
2708	with the IAppliance object you just created. Each such call creates one instance of
2709	<link to="IVirtualSystemDescription" /> inside the appliance.
2710	</li>
2711
2712	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2713	virtual system (machine) to override the suggestions made by the <link to="IMachine::exportTo"/> routine.
2714	</li>
2715
2716	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
2717	file written.</li>
2718	</ol>
2719
2720	</desc>
2721
2722	<attribute name="path" type="wstring" readonly="yes">
2723	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
2724	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
2725	<link to="#write" /> (for export).
2726	This attribute is empty until one of these methods has been called.
2727	</desc>
2728	</attribute>
2729
2730	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
2731	<desc>
2732	Array of virtual disk definitions. One such description exists for each
2733	disk definition in the OVF; each string array item represents one such piece of
2734	disk information, with the information fields separated by tab (\\t) characters.
2735
2736	The caller should be prepared for additional fields being appended to
2737	this string in future versions of VirtualBox and therefore check for
2738	the number of tabs in the strings returned.
2739
2740	In the current version, the following eight fields are returned per string
2741	in the array:
2742
2743	<ol>
2744	<li>Disk ID (unique string identifier given to disk)</li>
2745
2746	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
2747
2748	<li>Populated size (optional unsigned integer indicating the current size of the
2749	disk; can be approximate; -1 if unspecified)</li>
2750
2751	<li>Format (string identifying the disk format, typically
2752	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
2753
2754	<li>Reference (where to find the disk image, typically a file name; if empty,
2755	then the disk should be created on import)</li>
2756
2757	<li>Image size (optional unsigned integer indicating the size of the image,
2758	which need not necessarily be the same as the values specified above, since
2759	the image may be compressed or sparse; -1 if not specified)</li>
2760
2761	<li>Chunk size (optional unsigned integer if the image is split into chunks;
2762	presently unsupported and always -1)</li>
2763
2764	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
2765	</ol>
2766	</desc>
2767	</attribute>
2768
2769	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
2770	<desc> Array of virtual system descriptions. One such description is created
2771	for each virtual system (machine) found in the OVF.
2772	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::exportTo" />
2773	(for export) has been called.
2774	</desc>
2775	</attribute>
2776
2777	<attribute name="machines" type="wstring" readonly="yes" safearray="yes">
2778	<desc>
2779	Contains the UUIDs of the machines created from the information in this appliances. This is only
2780	relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
2781	succeeded.
2782	</desc>
2783	</attribute>
2784
2785	<method name="read">
2786	<desc>
2787	Reads an OVF file into the appliance object.
2788
2789	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
2790	mere fact that this method returns successfully does not mean that VirtualBox supports all
2791	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
2792	</desc>
2793	<param name="file" type="wstring" dir="in">
2794	<desc>
2795	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2796	on whether the appliance is distributed as a set of files or as a single file, respectively).
2797	</desc>
2798	</param>
2799	<param name="progress" type="IProgress" dir="return">
2800	<desc>Progress object to track the operation completion.</desc>
2801	</param>
2802	</method>
2803
2804	<method name="interpret">
2805	<desc>
2806	Interprets the OVF data that was read when the appliance was constructed. After
2807	calling this method, one can inspect the
2808	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
2809	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
2810	the appliance.
2811
2812	Calling this method is the second step of importing an appliance into VirtualBox;
2813	see <link to="IAppliance" /> for an overview.
2814
2815	After calling this method, one should call <link to="#getWarnings" /> to find out
2816	if problems were encountered during the processing which might later lead to
2817	errors.
2818	</desc>
2819	</method>
2820
2821	<method name="importMachines">
2822	<desc>
2823	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
2824	and other interfaces that match the information contained in the appliance as
2825	closely as possible, as represented by the import instructions in the
2826	<link to="#virtualSystemDescriptions" /> array.
2827
2828	Calling this method is the final step of importing an appliance into VirtualBox;
2829	see <link to="IAppliance" /> for an overview.
2830
2831	Since importing the appliance will most probably involve copying and converting
2832	disk images, which can take a long time, this method operates asynchronously and
2833	returns an IProgress object to allow the caller to monitor the progress.
2834
2835	After the import succeeded, the UUIDs of the IMachine instances created can be
2836	retrieved from the <link to="#machines" /> array attribute.
2837	</desc>
2838
2839	<param name="options" type="ImportOptions" dir="in" safearray="yes">
2840	<desc>Options for the importing operation.</desc>
2841	</param>
2842
2843	<param name="progress" type="IProgress" dir="return">
2844	<desc>Progress object to track the operation completion.</desc>
2845	</param>
2846	</method>
2847
2848	<method name="createVFSExplorer">
2849	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
2850
2851	<param name="URI" type="wstring" dir="in">
2852	<desc>The URI describing the file system to use.</desc>
2853	</param>
2854
2855	<param name="explorer" type="IVFSExplorer" dir="return">
2856	<desc></desc>
2857	</param>
2858	</method>
2859
2860	<method name="write">
2861	<desc>
2862	Writes the contents of the appliance exports into a new OVF file.
2863
2864	Calling this method is the final step of exporting an appliance from VirtualBox;
2865	see <link to="IAppliance" /> for an overview.
2866
2867	Since exporting the appliance will most probably involve copying and converting
2868	disk images, which can take a long time, this method operates asynchronously and
2869	returns an IProgress object to allow the caller to monitor the progress.
2870	</desc>
2871	<param name="format" type="wstring" dir="in">
2872	<desc>
2873	Output format, as a string. Currently supported formats are "ovf-0.9", "ovf-1.0"
2874	and "ovf-2.0"; future versions of VirtualBox may support additional formats.
2875	</desc>
2876	</param>
2877	<param name="manifest" type="boolean" dir="in">
2878	<desc>
2879	Indicate if the optional manifest file (.mf) should be written. The manifest file
2880	is used for integrity checks prior import.
2881	</desc>
2882	</param>
2883	<param name="path" type="wstring" dir="in">
2884	<desc>
2885	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2886	on whether the appliance is distributed as a set of files or as a single file, respectively).
2887	</desc>
2888	</param>
2889	<param name="progress" type="IProgress" dir="return">
2890	<desc>Progress object to track the operation completion.</desc>
2891	</param>
2892	</method>
2893
2894	<method name="getWarnings">
2895	<desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>
2896
2897	<param name="warnings" type="wstring" dir="return" safearray="yes">
2898	<desc></desc>
2899	</param>
2900	</method>
2901
2902	</interface>
2903
2904	<enum
2905	name="VirtualSystemDescriptionType"
2906	uuid="303c0900-a746-4612-8c67-79003e91f459"
2907	>
2908	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
2909	a configuration value.</desc>
2910
2911	<const name="Ignore" value="1" />
2912	<const name="OS" value="2" />
2913	<const name="Name" value="3" />
2914	<const name="Product" value="4" />
2915	<const name="Vendor" value="5" />
2916	<const name="Version" value="6" />
2917	<const name="ProductUrl" value="7" />
2918	<const name="VendorUrl" value="8" />
2919	<const name="Description" value="9" />
2920	<const name="License" value="10" />
2921	<const name="Miscellaneous" value="11" />
2922	<const name="CPU" value="12" />
2923	<const name="Memory" value="13" />
2924	<const name="HardDiskControllerIDE" value="14" />
2925	<const name="HardDiskControllerSATA" value="15" />
2926	<const name="HardDiskControllerSCSI" value="16" />
2927	<const name="HardDiskControllerSAS" value="17" />
2928	<const name="HardDiskImage" value="18" />
2929	<const name="Floppy" value="19" />
2930	<const name="CDROM" value="20" />
2931	<const name="NetworkAdapter" value="21" />
2932	<const name="USBController" value="22" />
2933	<const name="SoundCard" value="23" />
2934	<const name="SettingsFile" value="24">
2935	<desc>Not used/implemented right now, will be added later in 4.1.x.</desc>
2936	</const>
2937	</enum>
2938
2939	<enum
2940	name="VirtualSystemDescriptionValueType"
2941	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
2942	>
2943	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
2944	type to fetch.</desc>
2945
2946	<const name="Reference" value="1" />
2947	<const name="Original" value="2" />
2948	<const name="Auto" value="3" />
2949	<const name="ExtraConfig" value="4" />
2950
2951	</enum>
2952
2953	<interface
2954	name="IVirtualSystemDescription" extends="$unknown"
2955	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
2956	wsmap="managed"
2957	>
2958
2959	<desc>Represents one virtual system (machine) in an appliance. This interface is used in
2960	the <link to="IAppliance::virtualSystemDescriptions" /> array. After
2961	<link to="IAppliance::interpret" /> has been called, that array contains information
2962	about how the virtual systems described in the OVF should best be imported into
2963	VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
2964	import an OVF into VirtualBox.
2965	</desc>
2966
2967	<attribute name="count" type="unsigned long" readonly="yes">
2968	<desc>Return the number of virtual system description entries.</desc>
2969	</attribute>
2970
2971	<method name="getDescription">
2972	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
2973	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
2974
2975	The list below identifies the value sets that are possible depending on the
2976	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
2977	the array item with the same index in @a OVFValues[] will contain the original value as contained
2978	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
2979	will contain a suggested value to be used for VirtualBox. Depending on the description type,
2980	the @a aExtraConfigValues[] array item may also be used.
2981
2982	<ul>
2983	<li>
2984	"OS": the guest operating system type. There must be exactly one such array item on import. The
2985	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
2986	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
2987	item in @a OVFValues[] will contain a numerical value that described the operating system in the OVF.
2988	</li>
2989	<li>
2990	"Name": the name to give to the new virtual machine. There can be at most one such array item;
2991	if none is present on import, then an automatic name will be created from the operating system
2992	type. The corresponding item im @a OVFValues[] will contain the suggested virtual machine name
2993	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
2994	<link to="IMachine" /> name that does not exist yet.
2995	</li>
2996	<li>
2997	"Description": an arbitrary description.
2998	</li>
2999	<li>
3000	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3001	code to display such a license for agreement; the Main API does not enforce any such policy.
3002	</li>
3003	<li>
3004	Miscellaneous: reserved for future use.
3005	</li>
3006	<li>
3007	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3008	</li>
3009	<li>
3010	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3011	is present on import, then VirtualBox will set a meaningful default based on the operating system
3012	type.
3013	</li>
3014	<li>
3015	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
3016	An optional value in @a OVFValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
3017	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
3018	writes into the OVF.
3019	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
3020	type can use to specify which hard disk controller a virtual disk should be connected to.
3021	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
3022	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
3023	its virtual machines supports four channels (primary master, primary slave, secondary master,
3024	secondary slave) and thus maps to two IDE controllers in the OVF sense.
3025	</li>
3026	<li>
3027	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3028	has no value in @a OVFValues[] or @a aVBoxValues[].
3029	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3030	</li>
3031	<li>
3032	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3033	The items in @a OVFValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
3034	"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
3035	whereas VirtualBox considers it a class of storage controllers of its own; see
3036	<link to="StorageControllerType" />).
3037	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3038	</li>
3039	<li>
3040	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3041	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3042
3043	The array item in @a OVFValues[] will contain the file specification from the OVF file (without
3044	a path since the image file should be in the same location as the OVF file itself), whereas the
3045	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3046	hard disk image. This means that on import the image will be copied and converted from the
3047	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3048
3049	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
3050	format: "controller=<index>;channel=<c>"
3051	In this string, <index> must be an integer specifying the hard disk controller to connect
3052	the image to. That number must be the index of an array item with one of the hard disk controller
3053	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
3054	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3055	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
3056	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
3057	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
3058	</li>
3059	<li>
3060	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
3061	attachment information as with "HardDiskImage" items.
3062	</li>
3063	<li>
3064	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
3065	attachment information as with "HardDiskImage" items.
3066	</li>
3067	<li>
3068	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
3069	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
3070	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3071	</li>
3072	<li>
3073	"USBController": a USB controller. There can be at most one such item. If and only if such an
3074	item ispresent, USB support will be enabled for the new virtual machine.
3075	</li>
3076	<li>
3077	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3078	present, sound support will be enabled for the new virtual machine. Note that the virtual
3079	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3080	may be different from the virtual soundcard expected by the appliance.
3081	</li>
3082	</ul>
3083
3084	</desc>
3085
3086	<param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3087	<desc></desc>
3088	</param>
3089
3090	<param name="refs" type="wstring" dir="out" safearray="yes">
3091	<desc></desc>
3092	</param>
3093
3094	<param name="OVFValues" type="wstring" dir="out" safearray="yes">
3095	<desc></desc>
3096	</param>
3097
3098	<param name="VBoxValues" type="wstring" dir="out" safearray="yes">
3099	<desc></desc>
3100	</param>
3101
3102	<param name="extraConfigValues" type="wstring" dir="out" safearray="yes">
3103	<desc></desc>
3104	</param>
3105
3106	</method>
3107
3108	<method name="getDescriptionByType">
3109	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3110	should be returned.</desc>
3111
3112	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3113	<desc></desc>
3114	</param>
3115
3116	<param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3117	<desc></desc>
3118	</param>
3119
3120	<param name="refs" type="wstring" dir="out" safearray="yes">
3121	<desc></desc>
3122	</param>
3123
3124	<param name="OVFValues" type="wstring" dir="out" safearray="yes">
3125	<desc></desc>
3126	</param>
3127
3128	<param name="VBoxValues" type="wstring" dir="out" safearray="yes">
3129	<desc></desc>
3130	</param>
3131
3132	<param name="extraConfigValues" type="wstring" dir="out" safearray="yes">
3133	<desc></desc>
3134	</param>
3135
3136	</method>
3137
3138	<method name="getValuesByType">
3139	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3140	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3141	values.</desc>
3142
3143	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3144	<desc></desc>
3145	</param>
3146
3147	<param name="which" type="VirtualSystemDescriptionValueType" dir="in">
3148	<desc></desc>
3149	</param>
3150
3151	<param name="values" type="wstring" dir="return" safearray="yes">
3152	<desc></desc>
3153	</param>
3154
3155	</method>
3156
3157	<method name="setFinalValues">
3158	<desc>
3159	This method allows the appliance's user to change the configuration for the virtual
3160	system descriptions. For each array item returned from <link to="#getDescription" />,
3161	you must pass in one boolean value and one configuration value.
3162
3163	Each item in the boolean array determines whether the particular configuration item
3164	should be enabled.
3165	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3166	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3167	and SoundCard.
3168
3169	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3170	as returned in the aVBoxValues and aExtraConfigValues arrays from <link to="#getDescription"/>,
3171	the configuration remains unchanged. Please see the documentation for <link to="#getDescription"/>
3172	for valid configuration values for the individual array item types. If the
3173	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3174	</desc>
3175
3176	<param name="enabled" type="boolean" dir="in" safearray="yes">
3177	<desc></desc>
3178	</param>
3179
3180	<param name="VBoxValues" type="wstring" dir="in" safearray="yes">
3181	<desc></desc>
3182	</param>
3183
3184	<param name="extraConfigValues" type="wstring" dir="in" safearray="yes">
3185	<desc></desc>
3186	</param>
3187	</method>
3188
3189	<method name="addDescription">
3190	<desc>
3191	This method adds an additional description entry to the stack of already
3192	available descriptions for this virtual system. This is handy for writing
3193	values which aren't directly supported by VirtualBox. One example would
3194	be the License type of <link to="VirtualSystemDescriptionType" />.
3195	</desc>
3196
3197	<param name="type" type="VirtualSystemDescriptionType" dir="in">
3198	<desc></desc>
3199	</param>
3200
3201	<param name="VBoxValue" type="wstring" dir="in">
3202	<desc></desc>
3203	</param>
3204
3205	<param name="extraConfigValue" type="wstring" dir="in">
3206	<desc></desc>
3207	</param>
3208	</method>
3209	</interface>
3210
3211
3212	<!--
3213	// IMachine
3214	/////////////////////////////////////////////////////////////////////////
3215	-->
3216
3217	<interface
3218	name="IInternalMachineControl" extends="$unknown"
3219	uuid="dca36a92-703c-4649-98a4-f40c1ef0c336"
3220	internal="yes"
3221	wsmap="suppress"
3222	>
3223	<method name="setRemoveSavedStateFile">
3224	<desc>
3225	Updates the flag whether the saved state file is removed on a
3226	machine state change from Saved to PoweredOff.
3227	</desc>
3228	<param name="remove" type="boolean" dir="in"/>
3229	</method>
3230
3231	<method name="updateState">
3232	<desc>
3233	Updates the VM state.
3234	<note>
3235	This operation will also update the settings file with the correct
3236	information about the saved state file and delete this file from disk
3237	when appropriate.
3238	</note>
3239	</desc>
3240	<param name="state" type="MachineState" dir="in"/>
3241	</method>
3242
3243	<method name="getIPCId">
3244	<param name="id" type="wstring" dir="return"/>
3245	</method>
3246
3247	<method name="beginPowerUp">
3248	<desc>
3249	Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
3250	gives it the progress object that should be part of any pending
3251	<link to="IMachine::launchVMProcess"/> operations. The progress
3252	object may be called back to reflect an early cancelation, so some care
3253	have to be taken with respect to any cancelation callbacks. The console
3254	object will call <link to="IInternalMachineControl::endPowerUp"/>
3255	to signal the completion of the progress object.
3256	</desc>
3257	<param name="progress" type="IProgress" dir="in" />
3258	</method>
3259
3260	<method name="endPowerUp">
3261	<desc>
3262	Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
3263	This method may query status information from the progress object it
3264	received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
3265	it over to any in-progress <link to="IMachine::launchVMProcess"/>
3266	call in order to complete that progress object.
3267	</desc>
3268	<param name="result" type="long" dir="in"/>
3269	</method>
3270
3271	<method name="beginPoweringDown">
3272	<desc>
3273	Called by the VM process to inform the server it wants to
3274	stop the VM execution and power down.
3275	</desc>
3276	<param name="progress" type="IProgress" dir="out">
3277	<desc>
3278	Progress object created by VBoxSVC to wait until
3279	the VM is powered down.
3280	</desc>
3281	</param>
3282	</method>
3283
3284	<method name="endPoweringDown">
3285	<desc>
3286	Called by the VM process to inform the server that powering
3287	down previously requested by #beginPoweringDown is either
3288	successfully finished or there was a failure.
3289
3290	<result name="VBOX_E_FILE_ERROR">
3291	Settings file not accessible.
3292	</result>
3293	<result name="VBOX_E_XML_ERROR">
3294	Could not parse the settings file.
3295	</result>
3296
3297	</desc>
3298
3299	<param name="result" type="long" dir="in">
3300	<desc>@c S_OK to indicate success.
3301	</desc>
3302	</param>
3303	<param name="errMsg" type="wstring" dir="in">
3304	<desc>@c human readable error message in case of failure.
3305	</desc>
3306	</param>
3307	</method>
3308
3309	<method name="runUSBDeviceFilters">
3310	<desc>
3311	Asks the server to run USB devices filters of the associated
3312	machine against the given USB device and tell if there is
3313	a match.
3314	<note>
3315	Intended to be used only for remote USB devices. Local
3316	ones don't require to call this method (this is done
3317	implicitly by the Host and USBProxyService).
3318	</note>
3319	</desc>
3320	<param name="device" type="IUSBDevice" dir="in"/>
3321	<param name="matched" type="boolean" dir="out"/>
3322	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3323	</method>
3324
3325	<method name="captureUSBDevice">
3326	<desc>
3327	Requests a capture of the given host USB device.
3328	When the request is completed, the VM process will
3329	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3330	notification.
3331	</desc>
3332	<param name="id" type="uuid" mod="string" dir="in"/>
3333	</method>
3334
3335	<method name="detachUSBDevice">
3336	<desc>
3337	Notification that a VM is going to detach (@a done = @c false) or has
3338	already detached (@a done = @c true) the given USB device.
3339	When the @a done = @c true request is completed, the VM process will
3340	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3341	notification.
3342	<note>
3343	In the @a done = @c true case, the server must run its own filters
3344	and filters of all VMs but this one on the detached device
3345	as if it were just attached to the host computer.
3346	</note>
3347	</desc>
3348	<param name="id" type="uuid" mod="string" dir="in"/>
3349	<param name="done" type="boolean" dir="in"/>
3350	</method>
3351
3352	<method name="autoCaptureUSBDevices">
3353	<desc>
3354	Requests a capture all matching USB devices attached to the host.
3355	When the request is completed, the VM process will
3356	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3357	notification per every captured device.
3358	</desc>
3359	</method>
3360
3361	<method name="detachAllUSBDevices">
3362	<desc>
3363	Notification that a VM that is being powered down. The done
3364	parameter indicates whether which stage of the power down
3365	we're at. When @a done = @c false the VM is announcing its
3366	intentions, while when @a done = @c true the VM is reporting
3367	what it has done.
3368	<note>
3369	In the @a done = @c true case, the server must run its own filters
3370	and filters of all VMs but this one on all detach devices as
3371	if they were just attached to the host computer.
3372	</note>
3373	</desc>
3374	<param name="done" type="boolean" dir="in"/>
3375	</method>
3376
3377	<method name="onSessionEnd">
3378	<desc>
3379	Triggered by the given session object when the session is about
3380	to close normally.
3381	</desc>
3382	<param name="session" type="ISession" dir="in">
3383	<desc>Session that is being closed</desc>
3384	</param>
3385	<param name="progress" type="IProgress" dir="return">
3386	<desc>
3387	Used to wait until the corresponding machine is actually
3388	dissociated from the given session on the server.
3389	Returned only when this session is a direct one.
3390	</desc>
3391	</param>
3392	</method>
3393
3394	<method name="beginSavingState">
3395	<desc>
3396	Called by the VM process to inform the server it wants to
3397	save the current state and stop the VM execution.
3398	</desc>
3399	<param name="progress" type="IProgress" dir="out">
3400	<desc>
3401	Progress object created by VBoxSVC to wait until
3402	the state is saved.
3403	</desc>
3404	</param>
3405	<param name="stateFilePath" type="wstring" dir="out">
3406	<desc>
3407	File path the VM process must save the execution state to.
3408	</desc>
3409	</param>
3410	</method>
3411
3412	<method name="endSavingState">
3413	<desc>
3414	Called by the VM process to inform the server that saving
3415	the state previously requested by #beginSavingState is either
3416	successfully finished or there was a failure.
3417
3418	<result name="VBOX_E_FILE_ERROR">
3419	Settings file not accessible.
3420	</result>
3421	<result name="VBOX_E_XML_ERROR">
3422	Could not parse the settings file.
3423	</result>
3424
3425	</desc>
3426
3427	<param name="result" type="long" dir="in">
3428	<desc>@c S_OK to indicate success.
3429	</desc>
3430	</param>
3431	<param name="errMsg" type="wstring" dir="in">
3432	<desc>@c human readable error message in case of failure.
3433	</desc>
3434	</param>
3435	</method>
3436
3437	<method name="adoptSavedState">
3438	<desc>
3439	Gets called by <link to="IConsole::adoptSavedState"/>.
3440	<result name="VBOX_E_FILE_ERROR">
3441	Invalid saved state file path.
3442	</result>
3443	</desc>
3444	<param name="savedStateFile" type="wstring" dir="in">
3445	<desc>Path to the saved state file to adopt.</desc>
3446	</param>
3447	</method>
3448
3449	<method name="beginTakingSnapshot">
3450	<desc>
3451	Called from the VM process to request from the server to perform the
3452	server-side actions of creating a snapshot (creating differencing images
3453	and the snapshot object).
3454
3455	<result name="VBOX_E_FILE_ERROR">
3456	Settings file not accessible.
3457	</result>
3458	<result name="VBOX_E_XML_ERROR">
3459	Could not parse the settings file.
3460	</result>
3461	</desc>
3462	<param name="initiator" type="IConsole" dir="in">
3463	<desc>The console object that initiated this call.</desc>
3464	</param>
3465	<param name="name" type="wstring" dir="in">
3466	<desc>Snapshot name.</desc>
3467	</param>
3468	<param name="description" type="wstring" dir="in">
3469	<desc>Snapshot description.</desc>
3470	</param>
3471	<param name="consoleProgress" type="IProgress" dir="in">
3472	<desc>
3473	Progress object created by the VM process tracking the
3474	snapshot's progress. This has the following sub-operations:
3475	<ul>
3476	<li>setting up (weight 1);</li>
3477	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3478	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3479	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3480	<li>finishing up (weight 1)</li>
3481	</ul>
3482	</desc>
3483	</param>
3484	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3485	<desc>
3486	Whether this is an online snapshot (i.e. the machine is running).
3487	</desc>
3488	</param>
3489	<param name="stateFilePath" type="wstring" dir="out">
3490	<desc>
3491	File path the VM process must save the execution state to.
3492	</desc>
3493	</param>
3494	</method>
3495
3496	<method name="endTakingSnapshot">
3497	<desc>
3498	Called by the VM process to inform the server that the snapshot
3499	previously requested by #beginTakingSnapshot is either
3500	successfully taken or there was a failure.
3501	</desc>
3502
3503	<param name="success" type="boolean" dir="in">
3504	<desc>@c true to indicate success and @c false otherwise</desc>
3505	</param>
3506	</method>
3507
3508	<method name="deleteSnapshot">
3509	<desc>
3510	Gets called by <link to="IConsole::deleteSnapshot"/>,
3511	<link to="IConsole::deleteSnapshotAndAllChildren"/> and
3512	<link to="IConsole::deleteSnapshotRange"/>.
3513	<result name="VBOX_E_INVALID_OBJECT_STATE">
3514	Snapshot has more than one child snapshot. Only possible if the
3515	delete operation does not delete all children or the range does
3516	not meet the linearity condition.
3517	</result>
3518	</desc>
3519	<param name="initiator" type="IConsole" dir="in">
3520	<desc>The console object that initiated this call.</desc>
3521	</param>
3522	<param name="startId" type="uuid" mod="string" dir="in">
3523	<desc>UUID of the first snapshot to delete.</desc>
3524	</param>
3525	<param name="endId" type="uuid" mod="string" dir="in">
3526	<desc>UUID of the last snapshot to delete.</desc>
3527	</param>
3528	<param name="deleteAllChildren" type="boolean" dir="in">
3529	<desc>Whether all children should be deleted.</desc>
3530	</param>
3531	<param name="machineState" type="MachineState" dir="out">
3532	<desc>New machine state after this operation is started.</desc>
3533	</param>
3534	<param name="progress" type="IProgress" dir="return">
3535	<desc>Progress object to track the operation completion.</desc>
3536	</param>
3537	</method>
3538
3539	<method name="finishOnlineMergeMedium">
3540	<desc>
3541	Gets called by <link to="IInternalSessionControl::onlineMergeMedium"/>.
3542	</desc>
3543	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
3544	<desc>The medium attachment which needs to be cleaned up.</desc>
3545	</param>
3546	<param name="source" type="IMedium" dir="in">
3547	<desc>Merge source medium.</desc>
3548	</param>
3549	<param name="target" type="IMedium" dir="in">
3550	<desc>Merge target medium.</desc>
3551	</param>
3552	<param name="mergeForward" type="boolean" dir="in">
3553	<desc>Merge direction.</desc>
3554	</param>
3555	<param name="parentForTarget" type="IMedium" dir="in">
3556	<desc>For forward merges: new parent for target medium.</desc>
3557	</param>
3558	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
3559	<desc>For backward merges: list of media which need their parent UUID
3560	updated.</desc>
3561	</param>
3562	</method>
3563
3564	<method name="restoreSnapshot">
3565	<desc>
3566	Gets called by <link to="IConsole::restoreSnapshot"/>.
3567	</desc>
3568	<param name="initiator" type="IConsole" dir="in">
3569	<desc>The console object that initiated this call.</desc>
3570	</param>
3571	<param name="snapshot" type="ISnapshot" dir="in">
3572	<desc>The snapshot to restore the VM state from.</desc>
3573	</param>
3574	<param name="machineState" type="MachineState" dir="out">
3575	<desc>New machine state after this operation is started.</desc>
3576	</param>
3577	<param name="progress" type="IProgress" dir="return">
3578	<desc>Progress object to track the operation completion.</desc>
3579	</param>
3580	</method>
3581
3582	<method name="pullGuestProperties">
3583	<desc>
3584	Get the list of the guest properties matching a set of patterns along
3585	with their values, time stamps and flags and give responsibility for
3586	managing properties to the console.
3587	</desc>
3588	<param name="names" type="wstring" dir="out" safearray="yes">
3589	<desc>
3590	The names of the properties returned.
3591	</desc>
3592	</param>
3593	<param name="values" type="wstring" dir="out" safearray="yes">
3594	<desc>
3595	The values of the properties returned. The array entries match the
3596	corresponding entries in the @a name array.
3597	</desc>
3598	</param>
3599	<param name="timestamps" type="long long" dir="out" safearray="yes">
3600	<desc>
3601	The time stamps of the properties returned. The array entries match
3602	the corresponding entries in the @a name array.
3603	</desc>
3604	</param>
3605	<param name="flags" type="wstring" dir="out" safearray="yes">
3606	<desc>
3607	The flags of the properties returned. The array entries match the
3608	corresponding entries in the @a name array.
3609	</desc>
3610	</param>
3611	</method>
3612
3613	<method name="pushGuestProperty">
3614	<desc>
3615	Update a single guest property in IMachine.
3616	</desc>
3617	<param name="name" type="wstring" dir="in">
3618	<desc>
3619	The name of the property to be updated.
3620	</desc>
3621	</param>
3622	<param name="value" type="wstring" dir="in">
3623	<desc>
3624	The value of the property.
3625	</desc>
3626	</param>
3627	<param name="timestamp" type="long long" dir="in">
3628	<desc>
3629	The timestamp of the property.
3630	</desc>
3631	</param>
3632	<param name="flags" type="wstring" dir="in">
3633	<desc>
3634	The flags of the property.
3635	</desc>
3636	</param>
3637	</method>
3638
3639	<method name="lockMedia">
3640	<desc>
3641	Locks all media attached to the machine for writing and parents of
3642	attached differencing media (if any) for reading. This operation is
3643	atomic so that if it fails no media is actually locked.
3644
3645	This method is intended to be called when the machine is in Starting or
3646	Restoring state. The locked media will be automatically unlocked when
3647	the machine is powered off or crashed.
3648	</desc>
3649	</method>
3650	<method name="unlockMedia">
3651	<desc>
3652	Unlocks all media previously locked using
3653	<link to="IInternalMachineControl::lockMedia"/>.
3654
3655	This method is intended to be used with teleportation so that it is
3656	possible to teleport between processes on the same machine.
3657	</desc>
3658	</method>
3659
3660	<method name="ejectMedium">
3661	<desc>
3662	Tells VBoxSVC that the guest has ejected the medium associated with
3663	the medium attachment.
3664	</desc>
3665	<param name="attachment" type="IMediumAttachment" dir="in">
3666	<desc>
3667	The medium attachment where the eject happened.
3668	</desc>
3669	</param>
3670	<param name="newAttachment" type="IMediumAttachment" dir="return">
3671	<desc>
3672	A new reference to the medium attachment, as the config change can
3673	result in the creation of a new instance.
3674	</desc>
3675	</param>
3676	</method>
3677
3678	<method name="reportVmStatistics">
3679	<desc>
3680	Passes statistics collected by VM (including guest statistics) to VBoxSVC.
3681	</desc>
3682	<param name="validStats" type="unsigned long" dir="in">
3683	<desc>
3684	Mask defining which parameters are valid. For example: 0x11 means
3685	that cpuIdle and XXX are valid. Other parameters should be ignored.
3686	</desc>
3687	</param>
3688	<param name="cpuUser" type="unsigned long" dir="in">
3689	<desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
3690	</param>
3691	<param name="cpuKernel" type="unsigned long" dir="in">
3692	<desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
3693	</param>
3694	<param name="cpuIdle" type="unsigned long" dir="in">
3695	<desc>Percentage of processor time spent idling as seen by the guest.</desc>
3696	</param>
3697	<param name="memTotal" type="unsigned long" dir="in">
3698	<desc>Total amount of physical guest RAM.</desc>
3699	</param>
3700	<param name="memFree" type="unsigned long" dir="in">
3701	<desc>Free amount of physical guest RAM.</desc>
3702	</param>
3703	<param name="memBalloon" type="unsigned long" dir="in">
3704	<desc>Amount of ballooned physical guest RAM.</desc>
3705	</param>
3706	<param name="memShared" type="unsigned long" dir="in">
3707	<desc>Amount of shared physical guest RAM.</desc>
3708	</param>
3709	<param name="memCache" type="unsigned long" dir="in">
3710	<desc>Total amount of guest (disk) cache memory.</desc>
3711	</param>
3712	<param name="pagedTotal" type="unsigned long" dir="in">
3713	<desc>Total amount of space in the page file.</desc>
3714	</param>
3715	<param name="memAllocTotal" type="unsigned long" dir="in">
3716	<desc>Total amount of memory allocated by the hypervisor.</desc>
3717	</param>
3718	<param name="memFreeTotal" type="unsigned long" dir="in">
3719	<desc>Total amount of free memory available in the hypervisor.</desc>
3720	</param>
3721	<param name="memBalloonTotal" type="unsigned long" dir="in">
3722	<desc>Total amount of memory ballooned by the hypervisor.</desc>
3723	</param>
3724	<param name="memSharedTotal" type="unsigned long" dir="in">
3725	<desc>Total amount of shared memory in the hypervisor.</desc>
3726	</param>
3727	<param name="vmNetRx" type="unsigned long" dir="in">
3728	<desc>Network receive rate for VM.</desc>
3729	</param>
3730	<param name="vmNetTx" type="unsigned long" dir="in">
3731	<desc>Network transmit rate for VM.</desc>
3732	</param>
3733	</method>
3734	</interface>
3735
3736	<interface
3737	name="IBIOSSettings" extends="$unknown"
3738	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3739	wsmap="managed"
3740	>
3741	<desc>
3742	The IBIOSSettings interface represents BIOS settings of the virtual
3743	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3744	</desc>
3745	<attribute name="logoFadeIn" type="boolean">
3746	<desc>Fade in flag for BIOS logo animation.</desc>
3747	</attribute>
3748
3749	<attribute name="logoFadeOut" type="boolean">
3750	<desc>Fade out flag for BIOS logo animation.</desc>
3751	</attribute>
3752
3753	<attribute name="logoDisplayTime" type="unsigned long">
3754	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
3755	</attribute>
3756
3757	<attribute name="logoImagePath" type="wstring">
3758	<desc>
3759	Local file system path for external BIOS splash image. Empty string
3760	means the default image is shown on boot.
3761	</desc>
3762	</attribute>
3763
3764	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
3765	<desc>Mode of the BIOS boot device menu.</desc>
3766	</attribute>
3767
3768	<attribute name="ACPIEnabled" type="boolean">
3769	<desc>ACPI support flag.</desc>
3770	</attribute>
3771
3772	<attribute name="IOAPICEnabled" type="boolean">
3773	<desc>
3774	IO APIC support flag. If set, VirtualBox will provide an IO APIC
3775	and support IRQs above 15.
3776	</desc>
3777	</attribute>
3778
3779	<attribute name="timeOffset" type="long long">
3780	<desc>
3781	Offset in milliseconds from the host system time. This allows for
3782	guests running with a different system date/time than the host.
3783	It is equivalent to setting the system date/time in the BIOS except
3784	it is not an absolute value but a relative one. Guest Additions
3785	time synchronization honors this offset.
3786	</desc>
3787	</attribute>
3788
3789	<attribute name="PXEDebugEnabled" type="boolean">
3790	<desc>
3791	PXE debug logging flag. If set, VirtualBox will write extensive
3792	PXE trace information to the release log.
3793	</desc>
3794	</attribute>
3795	</interface>
3796
3797	<interface
3798	name="IPCIAddress" extends="$unknown"
3799	uuid="D88B324F-DB19-4D3B-A1A9-BF5B127199A8"
3800	wsmap="struct"
3801	>
3802
3803	<desc>
3804	Address on the PCI bus.
3805	</desc>
3806
3807	<attribute name="bus" type="short">
3808	<desc>
3809	Bus number.
3810	</desc>
3811	</attribute>
3812
3813	<attribute name="device" type="short">
3814	<desc>
3815	Device number.
3816	</desc>
3817	</attribute>
3818
3819	<attribute name="devFunction" type="short">
3820	<desc>
3821	Device function number.
3822	</desc>
3823	</attribute>
3824
3825	<method name="asLong">
3826	<desc>
3827	Convert PCI address into long.
3828	</desc>
3829	<param name="result" type="long" dir="return" />
3830	</method>
3831
3832	<method name="fromLong">
3833	<desc>
3834	Make PCI address from long.
3835	</desc>
3836	<param name="number" type="long" dir="in" />
3837	</method>
3838	</interface>
3839
3840	<interface
3841	name="IPCIDeviceAttachment" extends="$unknown"
3842	uuid="91f33d6f-e621-4f70-a77e-15f0e3c714d5"
3843	wsmap="struct"
3844	>
3845
3846	<desc>
3847	Information about PCI attachments.
3848	</desc>
3849
3850	<attribute name="name" type="wstring" readonly="yes">
3851	<desc>
3852	Device name.
3853	</desc>
3854	</attribute>
3855
3856	<attribute name="isPhysicalDevice" type="boolean" readonly="yes">
3857	<desc>
3858	If this is physical or virtual device.
3859	</desc>
3860	</attribute>
3861
3862	<attribute name="hostAddress" type="long" readonly="yes">
3863	<desc>
3864	Address of device on the host, applicable only to host devices.
3865	</desc>
3866	</attribute>
3867
3868	<attribute name="guestAddress" type="long" readonly="yes">
3869	<desc>
3870	Address of device on the guest.
3871	</desc>
3872	</attribute>
3873
3874	</interface>
3875
3876	<enum
3877	name="GraphicsControllerType"
3878	uuid="79c96ca0-9f39-4900-948e-68c41cbe127a"
3879	>
3880	<desc>Graphics controller type, used with <link to="IMachine::unregister" />.
3881	</desc>
3882	<const name="Null" value="0">
3883	<desc>Reserved value, invalid.</desc>
3884	</const>
3885	<const name="VBoxVGA" value="1">
3886	<desc>Default VirtualBox VGA device.</desc>
3887	</const>
3888	</enum>
3889
3890	<enum
3891	name="CleanupMode"
3892	uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441"
3893	>
3894	<desc>Cleanup mode, used with <link to="IMachine::unregister" />.
3895	</desc>
3896	<const name="UnregisterOnly" value="1">
3897	<desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
3898	</const>
3899	<const name="DetachAllReturnNone" value="2">
3900	<desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
3901	</const>
3902	<const name="DetachAllReturnHardDisksOnly" value="3">
3903	<desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc>
3904	</const>
3905	<const name="Full" value="4">
3906	<desc>Delete all snapshots, detach all media and return all media for closing.</desc>
3907	</const>
3908	</enum>
3909
3910	<enum
3911	name="CloneMode" extends="$unknown"
3912	uuid="A7A159FE-5096-4B8D-8C3C-D033CB0B35A8"
3913	>
3914
3915	<desc>
3916	Clone mode, used with <link to="IMachine::cloneTo" />.
3917	</desc>
3918
3919	<const name="MachineState" value="1">
3920	<desc>Clone the state of the selected machine.</desc>
3921	</const>
3922	<const name="MachineAndChildStates" value="2">
3923	<desc>Clone the state of the selected machine and its child snapshots if present.</desc>
3924	</const>
3925	<const name="AllStates" value="3">
3926	<desc>Clone all states (including all snapshots) of the machine, regardless of the machine object used.</desc>
3927	</const>
3928
3929	</enum>
3930
3931	<enum
3932	name="CloneOptions" extends="$unknown"
3933	uuid="22243f8e-96ab-497c-8cf0-f40a566c630b"
3934	>
3935
3936	<desc>
3937	Clone options, used with <link to="IMachine::cloneTo" />.
3938	</desc>
3939
3940	<const name="Link" value="1">
3941	<desc>Create a clone VM where all virtual disks are linked to the original VM.</desc>
3942	</const>
3943	<const name="KeepAllMACs" value="2">
3944	<desc>Don't generate new MAC addresses of the attached network adapters.</desc>
3945	</const>
3946	<const name="KeepNATMACs" value="3">
3947	<desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
3948	</const>
3949	<const name="KeepDiskNames" value="4">
3950	<desc>Don't change the disk names.</desc>
3951	</const>
3952
3953	</enum>
3954
3955	<enum
3956	name="AutostopType" extends="$unknown"
3957	uuid="6bb96740-cf34-470d-aab2-2cd48ea2e10e"
3958	>
3959
3960	<desc>
3961	Autostop types, used with <link to="IMachine::autostopType" />.
3962	</desc>
3963
3964	<const name="Disabled" value="1">
3965	<desc>Stopping the VM during system shutdown is disabled.</desc>
3966	</const>
3967	<const name="SaveState" value="2">
3968	<desc>The state of the VM will be saved when the system shuts down.</desc>
3969	</const>
3970	<const name="PowerOff" value="3">
3971	<desc>The VM is powered off when the system shuts down.</desc>
3972	</const>
3973	<const name="AcpiShutdown" value="4">
3974	<desc>An ACPI shutdown event is generated.</desc>
3975	</const>
3976
3977	</enum>
3978
3979
3980	<interface
3981	name="IMachine" extends="$unknown"
3982	uuid="258f4e55-40f6-4804-a162-60c302a34d99"
3983	wsmap="managed"
3984	>
3985	<desc>
3986	The IMachine interface represents a virtual machine, or guest, created
3987	in VirtualBox.
3988
3989	This interface is used in two contexts. First of all, a collection of
3990	objects implementing this interface is stored in the
3991	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
3992	machines that are currently registered with this VirtualBox
3993	installation. Also, once a session has been opened for the given virtual
3994	machine (e.g. the virtual machine is running), the machine object
3995	associated with the open session can be queried from the session object;
3996	see <link to="ISession"/> for details.
3997
3998	The main role of this interface is to expose the settings of the virtual
3999	machine and provide methods to change various aspects of the virtual
4000	machine's configuration. For machine objects stored in the
4001	<link to="IVirtualBox::machines"/> collection, all attributes are
4002	read-only unless explicitly stated otherwise in individual attribute
4003	and method descriptions.
4004
4005	In order to change a machine setting, a session for this machine must be
4006	opened using one of the <link to="IMachine::lockMachine" /> or
4007	<link to="IMachine::launchVMProcess"/> methods. After the
4008	machine has been successfully locked for a session, a mutable machine object
4009	needs to be queried from the session object and then the desired settings
4010	changes can be applied to the returned object using IMachine attributes and
4011	methods. See the <link to="ISession"/> interface description for more
4012	information about sessions.
4013
4014	Note that IMachine does not provide methods to control virtual machine
4015	execution (such as start the machine, or power it down) -- these methods
4016	are grouped in a separate interface called <link to="IConsole" />.
4017
4018	<see><link to="ISession"/>, <link to="IConsole"/></see>
4019	</desc>
4020
4021	<attribute name="parent" type="IVirtualBox" readonly="yes">
4022	<desc>Associated parent object.</desc>
4023	</attribute>
4024
4025	<attribute name="accessible" type="boolean" readonly="yes">
4026	<desc>
4027	Whether this virtual machine is currently accessible or not.
4028
4029	A machine is always deemed accessible unless it is registered <i>and</i>
4030	its settings file cannot be read or parsed (either because the file itself
4031	is unavailable or has invalid XML contents).
4032
4033	Every time this property is read, the accessibility state of
4034	this machine is re-evaluated. If the returned value is @c false,
4035	the <link to="#accessError"/> property may be used to get the
4036	detailed error information describing the reason of
4037	inaccessibility, including XML error messages.
4038
4039	When the machine is inaccessible, only the following properties
4040	can be used on it:
4041	<ul>
4042	<li><link to="#parent"/></li>
4043	<li><link to="#id"/></li>
4044	<li><link to="#settingsFilePath"/></li>
4045	<li><link to="#accessible"/></li>
4046	<li><link to="#accessError"/></li>
4047	</ul>
4048
4049	An attempt to access any other property or method will return
4050	an error.
4051
4052	The only possible action you can perform on an inaccessible
4053	machine is to unregister it using the
4054	<link to="IMachine::unregister"/> call (or, to check
4055	for the accessibility state once more by querying this
4056	property).
4057
4058	<note>
4059	In the current implementation, once this property returns
4060	@c true, the machine will never become inaccessible
4061	later, even if its settings file cannot be successfully
4062	read/written any more (at least, until the VirtualBox
4063	server is restarted). This limitation may be removed in
4064	future releases.
4065	</note>
4066	</desc>
4067	</attribute>
4068
4069	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4070	<desc>
4071	Error information describing the reason of machine
4072	inaccessibility.
4073
4074	Reading this property is only valid after the last call to
4075	<link to="#accessible"/> returned @c false (i.e. the
4076	machine is currently inaccessible). Otherwise, a @c null
4077	IVirtualBoxErrorInfo object will be returned.
4078	</desc>
4079	</attribute>
4080
4081	<attribute name="name" type="wstring">
4082	<desc>
4083	Name of the virtual machine.
4084
4085	Besides being used for human-readable identification purposes
4086	everywhere in VirtualBox, the virtual machine name is also used
4087	as a name of the machine's settings file and as a name of the
4088	subdirectory this settings file resides in. Thus, every time you
4089	change the value of this property, the settings file will be
4090	renamed once you call <link to="#saveSettings"/> to confirm the
4091	change. The containing subdirectory will be also renamed, but
4092	only if it has exactly the same name as the settings file
4093	itself prior to changing this property (for backward compatibility
4094	with previous API releases). The above implies the following
4095	limitations:
4096	<ul>
4097	<li>The machine name cannot be empty.</li>
4098	<li>The machine name can contain only characters that are valid
4099	file name characters according to the rules of the file
4100	system used to store VirtualBox configuration.</li>
4101	<li>You cannot have two or more machines with the same name
4102	if they use the same subdirectory for storing the machine
4103	settings files.</li>
4104	<li>You cannot change the name of the machine if it is running,
4105	or if any file in the directory containing the settings file
4106	is being used by another running machine or by any other
4107	process in the host operating system at a time when
4108	<link to="#saveSettings"/> is called.
4109	</li>
4110	</ul>
4111	If any of the above limitations are hit, <link to="#saveSettings"/>
4112	will return an appropriate error message explaining the exact
4113	reason and the changes you made to this machine will not be saved.
4114
4115	Starting with VirtualBox 4.0, a ".vbox" extension of the settings
4116	file is recommended, but not enforced. (Previous versions always
4117	used a generic ".xml" extension.)
4118	</desc>
4119	</attribute>
4120
4121	<attribute name="description" type="wstring">
4122	<desc>
4123	Description of the virtual machine.
4124
4125	The description attribute can contain any text and is
4126	typically used to describe the hardware and software
4127	configuration of the virtual machine in detail (i.e. network
4128	settings, versions of the installed software and so on).
4129	</desc>
4130	</attribute>
4131
4132	<attribute name="id" type="uuid" mod="string" readonly="yes">
4133	<desc>UUID of the virtual machine.</desc>
4134	</attribute>
4135
4136	<attribute name="groups" type="wstring" safearray="yes">
4137	<desc>
4138	Array of machine group names of which this machine is a member.
4139	<tt>""</tt> and <tt>"/"</tt> are synonyms for the toplevel group. Each
4140	group is only listed once, however they are listed in no particular
4141	order and there is no guarantee that there are no gaps in the group
4142	hierarchy (i.e. <tt>"/group"</tt>,
4143	<tt>"/group/subgroup/subsubgroup"</tt> is a valid result).
4144	</desc>
4145	</attribute>
4146
4147	<attribute name="OSTypeId" type="wstring">
4148	<desc>
4149	User-defined identifier of the Guest OS type.
4150	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4151	an IGuestOSType object representing details about the given
4152	Guest OS type.
4153	<note>
4154	This value may differ from the value returned by
4155	<link to="IGuest::OSTypeId"/> if Guest Additions are
4156	installed to the guest OS.
4157	</note>
4158	</desc>
4159	</attribute>
4160
4161	<attribute name="hardwareVersion" type="wstring">
4162	<desc>Hardware version identifier. Internal use only for now.</desc>
4163	</attribute>
4164
4165	<attribute name="hardwareUUID" type="uuid" mod="string">
4166	<desc>
4167	The UUID presented to the guest via memory tables, hardware and guest
4168	properties. For most VMs this is the same as the @a id, but for VMs
4169	which have been cloned or teleported it may be the same as the source
4170	VM. The latter is because the guest shouldn't notice that it was
4171	cloned or teleported.
4172	</desc>
4173	</attribute>
4174
4175	<attribute name="CPUCount" type="unsigned long">
4176	<desc>Number of virtual CPUs in the VM.</desc>
4177	</attribute>
4178
4179	<attribute name="CPUHotPlugEnabled" type="boolean">
4180	<desc>
4181	This setting determines whether VirtualBox allows CPU
4182	hotplugging for this machine.</desc>
4183	</attribute>
4184
4185	<attribute name="CPUExecutionCap" type="unsigned long">
4186	<desc>
4187	Means to limit the number of CPU cycles a guest can use. The unit
4188	is percentage of host CPU cycles per second. The valid range
4189	is 1 - 100. 100 (the default) implies no limit.
4190	</desc>
4191	</attribute>
4192
4193	<attribute name="memorySize" type="unsigned long">
4194	<desc>System memory size in megabytes.</desc>
4195	</attribute>
4196
4197	<attribute name="memoryBalloonSize" type="unsigned long">
4198	<desc>Memory balloon size in megabytes.</desc>
4199	</attribute>
4200
4201	<attribute name="pageFusionEnabled" type="boolean">
4202	<desc>
4203	This setting determines whether VirtualBox allows page
4204	fusion for this machine (64-bit hosts only).
4205	</desc>
4206	</attribute>
4207
4208	<attribute name="graphicsControllerType" type="GraphicsControllerType">
4209	<desc>Graphics controller type.</desc>
4210	</attribute>
4211
4212	<attribute name="VRAMSize" type="unsigned long">
4213	<desc>Video memory size in megabytes.</desc>
4214	</attribute>
4215
4216	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4217	<desc>
4218	This setting determines whether VirtualBox allows this machine to make
4219	use of the 3D graphics support available on the host.</desc>
4220	</attribute>
4221
4222	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4223	<desc>
4224	This setting determines whether VirtualBox allows this machine to make
4225	use of the 2D video acceleration support available on the host.</desc>
4226	</attribute>
4227
4228	<attribute name="monitorCount" type="unsigned long">
4229	<desc>
4230	Number of virtual monitors.
4231	<note>
4232	Only effective on Windows XP and later guests with
4233	Guest Additions installed.
4234	</note>
4235	</desc>
4236	</attribute>
4237
4238	<attribute name="VideoCaptureEnabled" type="boolean" default="false">
4239	<desc>
4240	This setting determines whether VirtualBox uses video recording to
4241	record VM session.</desc>
4242	</attribute>
4243
4244	<attribute name="VideoCaptureScreens" type="boolean" safearray="yes">
4245	<desc>
4246	This setting determines for which screens video recording is
4247	enabled.</desc>
4248	</attribute>
4249
4250	<attribute name="VideoCaptureFile" type="wstring" default="Test.webm">
4251	<desc>
4252	This setting determines the filename VirtualBox uses to save
4253	the recorded content.</desc>
4254	</attribute>
4255
4256	<attribute name="VideoCaptureWidth" type="unsigned long" default="640">
4257	<desc>
4258	This setting determines the horizontal resolution of the recorded video.</desc>
4259	</attribute>
4260
4261	<attribute name="VideoCaptureHeight" type="unsigned long" default="480">
4262	<desc>
4263	This setting determines the vertical resolution of the recorded video.</desc>
4264	</attribute>
4265
4266	<attribute name="VideoCaptureRate" type="unsigned long" default="512">
4267	<desc>
4268	This setting determines the bitrate in kilobits per second.
4269	Increasing this value makes the video look better for the
4270	cost of an increased file size.
4271	</desc>
4272	</attribute>
4273
4274	<attribute name="VideoCaptureFps" type="unsigned long" default="25">
4275	<desc>
4276	This setting determines the maximum number of frames per second.
4277	Frames with a higher frequency will be skipped. Reducing this
4278	value increses the number of skipped frames but reduces the
4279	file size.
4280	</desc>
4281	</attribute>
4282
4283	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4284	<desc>Object containing all BIOS settings.</desc>
4285	</attribute>
4286
4287	<attribute name="firmwareType" type="FirmwareType">
4288	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4289	bootstrap in this VM.</desc>
4290	</attribute>
4291
4292	<attribute name="pointingHIDType" type="PointingHIDType">
4293	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4294	The default is typically "PS2Mouse" but can vary depending on the
4295	requirements of the guest operating system.</desc>
4296	</attribute>
4297
4298	<attribute name="keyboardHIDType" type="KeyboardHIDType">
4299	<desc>Type of keyboard HID used in this VM.
4300	The default is typically "PS2Keyboard" but can vary depending on the
4301	requirements of the guest operating system.</desc>
4302	</attribute>
4303
4304	<attribute name="HPETEnabled" type="boolean">
4305	<desc>This attribute controls if High Precision Event Timer (HPET) is
4306	enabled in this VM. Use this property if you want to provide guests
4307	with additional time source, or if guest requires HPET to function correctly.
4308	Default is false.</desc>
4309	</attribute>
4310
4311	<attribute name="chipsetType" type="ChipsetType">
4312	<desc>Chipset type used in this VM.</desc>
4313	</attribute>
4314
4315	<attribute name="snapshotFolder" type="wstring">
4316	<desc>
4317	Full path to the directory used to store snapshot data
4318	(differencing media and saved state files) of this machine.
4319
4320	The initial value of this property is
4321	<tt><</tt><link to="#settingsFilePath">
4322	path_to_settings_file</link><tt>>/<</tt>
4323	<link to="#id">machine_uuid</link>
4324	<tt>></tt>.
4325
4326	Currently, it is an error to try to change this property on
4327	a machine that has snapshots (because this would require to
4328	move possibly large files to a different location).
4329	A separate method will be available for this purpose later.
4330
4331	<note>
4332	Setting this property to @c null or to an empty string will restore
4333	the initial value.
4334	</note>
4335	<note>
4336	When setting this property, the specified path can be
4337	absolute (full path) or relative to the directory where the
4338	<link to="#settingsFilePath">machine settings file</link>
4339	is located. When reading this property, a full path is
4340	always returned.
4341	</note>
4342	<note>
4343	The specified path may not exist, it will be created
4344	when necessary.
4345	</note>
4346	</desc>
4347	</attribute>
4348
4349	<attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
4350	<desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
4351	</attribute>
4352
4353	<attribute name="emulatedUSBWebcameraEnabled" type="boolean" default="false"/>
4354	<attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/>
4355
4356	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4357	<desc>Array of media attached to this machine.</desc>
4358	</attribute>
4359
4360	<attribute name="USBController" type="IUSBController" readonly="yes">
4361	<desc>
4362	Associated USB controller object.
4363
4364	<note>
4365	If USB functionality is not available in the given edition of
4366	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4367	</note>
4368	</desc>
4369	</attribute>
4370
4371	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4372	<desc>Associated audio adapter, always present.</desc>
4373	</attribute>
4374
4375	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4376	<desc>Array of storage controllers attached to this machine.</desc>
4377	</attribute>
4378
4379	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4380	<desc>
4381	Full name of the file containing machine settings data.
4382	</desc>
4383	</attribute>
4384
4385	<attribute name="settingsModified" type="boolean" readonly="yes">
4386	<desc>
4387	Whether the settings of this machine have been modified
4388	(but neither yet saved nor discarded).
4389	<note>
4390	Reading this property is only valid on instances returned
4391	by <link to="ISession::machine"/> and on new machines
4392	created by <link to="IVirtualBox::createMachine"/> or opened
4393	by <link to="IVirtualBox::openMachine"/> but not
4394	yet registered, or on unregistered machines after calling
4395	<link to="IMachine::unregister"/>. For all other
4396	cases, the settings can never be modified.
4397	</note>
4398	<note>
4399	For newly created unregistered machines, the value of this
4400	property is always @c true until <link to="#saveSettings"/>
4401	is called (no matter if any machine settings have been
4402	changed after the creation or not). For opened machines
4403	the value is set to @c false (and then follows to normal rules).
4404	</note>
4405	</desc>
4406	</attribute>
4407
4408	<attribute name="sessionState" type="SessionState" readonly="yes">
4409	<desc>Current session state for this machine.</desc>
4410	</attribute>
4411
4412	<attribute name="sessionType" type="wstring" readonly="yes">
4413	<desc>
4414	Type of the session. If <link to="#sessionState"/> is
4415	Spawning or Locked, this attribute contains the
4416	same value as passed to the
4417	<link to="IMachine::launchVMProcess"/> method in the
4418	@a type parameter. If the session was used with
4419	<link to="IMachine::lockMachine" />, or if
4420	<link to="#sessionState"/> is SessionClosed, the value of this
4421	attribute is an empty string.
4422	</desc>
4423	</attribute>
4424
4425	<attribute name="sessionPID" type="unsigned long" readonly="yes">
4426	<desc>
4427	Identifier of the session process. This attribute contains the
4428	platform-dependent identifier of the process whose session was
4429	used with <link to="IMachine::lockMachine" /> call. The returned
4430	value is only valid if <link to="#sessionState"/> is Locked or
4431	Unlocking by the time this property is read.
4432	</desc>
4433	</attribute>
4434
4435	<attribute name="state" type="MachineState" readonly="yes">
4436	<desc>Current execution state of this machine.</desc>
4437	</attribute>
4438
4439	<attribute name="lastStateChange" type="long long" readonly="yes">
4440	<desc>
4441	Time stamp of the last execution state change,
4442	in milliseconds since 1970-01-01 UTC.
4443	</desc>
4444	</attribute>
4445
4446	<attribute name="stateFilePath" type="wstring" readonly="yes">
4447	<desc>
4448	Full path to the file that stores the execution state of
4449	the machine when it is in the <link to="MachineState_Saved"/> state.
4450	<note>
4451	When the machine is not in the Saved state, this attribute is
4452	an empty string.
4453	</note>
4454	</desc>
4455	</attribute>
4456
4457	<attribute name="logFolder" type="wstring" readonly="yes">
4458	<desc>
4459	Full path to the folder that stores a set of rotated log files
4460	recorded during machine execution. The most recent log file is
4461	named <tt>VBox.log</tt>, the previous log file is
4462	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4463	in the current version).
4464	</desc>
4465	</attribute>
4466
4467	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4468	<desc>
4469	Current snapshot of this machine. This is @c null if the machine
4470	currently has no snapshots. If it is not @c null, then it was
4471	set by one of <link to="IConsole::takeSnapshot" />,
4472	<link to="IConsole::deleteSnapshot" />
4473	or <link to="IConsole::restoreSnapshot" />, depending on which
4474	was called last. See <link to="ISnapshot"/> for details.
4475	</desc>
4476	</attribute>
4477
4478	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4479	<desc>
4480	Number of snapshots taken on this machine. Zero means the
4481	machine doesn't have any snapshots.
4482	</desc>
4483	</attribute>
4484
4485	<attribute name="currentStateModified" type="boolean" readonly="yes">
4486	<desc>
4487	Returns @c true if the current state of the machine is not
4488	identical to the state stored in the current snapshot.
4489
4490	The current state is identical to the current snapshot only
4491	directly after one of the following calls are made:
4492
4493	<ul>
4494	<li><link to="IConsole::restoreSnapshot"/>
4495	</li>
4496	<li><link to="IConsole::takeSnapshot"/> (issued on a
4497	"powered off" or "saved" machine, for which
4498	<link to="#settingsModified"/> returns @c false)
4499	</li>
4500	</ul>
4501
4502	The current state remains identical until one of the following
4503	happens:
4504	<ul>
4505	<li>settings of the machine are changed</li>
4506	<li>the saved state is deleted</li>
4507	<li>the current snapshot is deleted</li>
4508	<li>an attempt to execute the machine is made</li>
4509	</ul>
4510
4511	<note>
4512	For machines that don't have snapshots, this property is
4513	always @c false.
4514	</note>
4515	</desc>
4516	</attribute>
4517
4518	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4519	<desc>
4520	Collection of shared folders for this machine (permanent shared
4521	folders). These folders are shared automatically at machine startup
4522	and available only to the guest OS installed within this machine.
4523
4524	New shared folders are added to the collection using
4525	<link to="#createSharedFolder"/>. Existing shared folders can be
4526	removed using <link to="#removeSharedFolder"/>.
4527	</desc>
4528	</attribute>
4529
4530	<attribute name="clipboardMode" type="ClipboardMode">
4531	<desc>
4532	Synchronization mode between the host OS clipboard
4533	and the guest OS clipboard.
4534	</desc>
4535	</attribute>
4536
4537	<attribute name="dragAndDropMode" type="DragAndDropMode">
4538	<desc>
4539	Which mode is allowed for drag'n'drop.
4540	</desc>
4541	</attribute>
4542
4543	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4544	<desc>
4545	A comma-separated list of simple glob patterns. Changes to guest
4546	properties whose name matches one of the patterns will generate an
4547	<link to="IGuestPropertyChangedEvent"/> signal.
4548	</desc>
4549	</attribute>
4550
4551	<attribute name="teleporterEnabled" type="boolean">
4552	<desc>
4553	When set to @a true, the virtual machine becomes a target teleporter
4554	the next time it is powered on. This can only set to @a true when the
4555	VM is in the @a PoweredOff or @a Aborted state.
4556
4557	<!-- This property is automatically set to @a false when the VM is powered
4558	on. (bird: This doesn't work yet ) -->
4559	</desc>
4560	</attribute>
4561
4562	<attribute name="teleporterPort" type="unsigned long">
4563	<desc>
4564	The TCP port the target teleporter will listen for incoming
4565	teleportations on.
4566
4567	0 means the port is automatically selected upon power on. The actual
4568	value can be read from this property while the machine is waiting for
4569	incoming teleportations.
4570	</desc>
4571	</attribute>
4572
4573	<attribute name="teleporterAddress" type="wstring">
4574	<desc>
4575	The address the target teleporter will listen on. If set to an empty
4576	string, it will listen on all addresses.
4577	</desc>
4578	</attribute>
4579
4580	<attribute name="teleporterPassword" type="wstring">
4581	<desc>
4582	The password to check for on the target teleporter. This is just a
4583	very basic measure to prevent simple hacks and operators accidentally
4584	beaming a virtual machine to the wrong place.
4585
4586	Note that you SET a plain text password while reading back a HASHED
4587	password. Setting a hashed password is currently not supported.
4588	</desc>
4589	</attribute>
4590
4591	<attribute name="faultToleranceState" type="FaultToleranceState">
4592	<desc>
4593	Fault tolerance state; disabled, source or target.
4594	This property can be changed at any time. If you change it for a running
4595	VM, then the fault tolerance address and port must be set beforehand.
4596	</desc>
4597	</attribute>
4598
4599	<attribute name="faultTolerancePort" type="unsigned long">
4600	<desc>
4601	The TCP port the fault tolerance source or target will use for
4602	communication.
4603	</desc>
4604	</attribute>
4605
4606	<attribute name="faultToleranceAddress" type="wstring">
4607	<desc>
4608	The address the fault tolerance source or target.
4609	</desc>
4610	</attribute>
4611
4612	<attribute name="faultTolerancePassword" type="wstring">
4613	<desc>
4614	The password to check for on the standby VM. This is just a
4615	very basic measure to prevent simple hacks and operators accidentally
4616	choosing the wrong standby VM.
4617	</desc>
4618	</attribute>
4619
4620	<attribute name="faultToleranceSyncInterval" type="unsigned long">
4621	<desc>
4622	The interval in ms used for syncing the state between source and target.
4623	</desc>
4624	</attribute>
4625
4626	<attribute name="RTCUseUTC" type="boolean">
4627	<desc>
4628	When set to @a true, the RTC device of the virtual machine will run
4629	in UTC time, otherwise in local time. Especially Unix guests prefer
4630	the time in UTC.
4631	</desc>
4632	</attribute>
4633
4634	<attribute name="IOCacheEnabled" type="boolean">
4635	<desc>
4636	When set to @a true, the builtin I/O cache of the virtual machine
4637	will be enabled.
4638	</desc>
4639	</attribute>
4640
4641	<attribute name="IOCacheSize" type="unsigned long">
4642	<desc>
4643	Maximum size of the I/O cache in MB.
4644	</desc>
4645	</attribute>
4646
4647	<attribute name="PCIDeviceAssignments" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
4648	<desc>Array of PCI devices assigned to this machine, to get list of all
4649	PCI devices attached to the machine use
4650	<link to="IConsole::attachedPCIDevices"/> attribute, as this attribute
4651	is intended to list only devices additional to what described in
4652	virtual hardware config. Usually, this list keeps host's physical
4653	devices assigned to the particular machine.
4654	</desc>
4655	</attribute>
4656
4657	<attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes">
4658	<desc>
4659	Bandwidth control manager.
4660	</desc>
4661	</attribute>
4662
4663	<attribute name="tracingEnabled" type="boolean">
4664	<desc>
4665	Enables the tracing facility in the VMM (including PDM devices +
4666	drivers). The VMM will consume about 0.5MB of more memory when
4667	enabled and there may be some extra overhead from tracepoints that are
4668	always enabled.
4669	</desc>
4670	</attribute>
4671
4672	<attribute name="tracingConfig" type="wstring">
4673	<desc>
4674	Tracepoint configuration to apply at startup when
4675	<link to="IMachine::tracingEnabled" /> is true. The string specifies
4676	a space separated of tracepoint group names to enable. The special
4677	group 'all' enables all tracepoints. Check DBGFR3TracingConfig for
4678	more details on available tracepoint groups and such.
4679
4680	Note that on hosts supporting DTrace (or similar), a lot of the
4681	tracepoints may be implemented exclusivly as DTrace probes. So, the
4682	effect of the same config may differ between Solaris and Windows for
4683	example.
4684	</desc>
4685	</attribute>
4686
4687	<attribute name="allowTracingToAccessVM" type="boolean">
4688	<desc>
4689	Enables tracepoints in PDM devices and drivers to use the VMCPU or VM
4690	structures when firing off trace points. This is especially useful
4691	with DTrace tracepoints, as it allows you to use the VMCPU or VM
4692	pointer to obtain useful information such as guest register state.
4693
4694	This is disabled by default because devices and drivers normally has no
4695	business accessing the VMCPU or VM structures, and are therefore unable
4696	to get any pointers to these.
4697	</desc>
4698	</attribute>
4699
4700	<attribute name="autostartEnabled" type="boolean">
4701	<desc>
4702	Enables autostart of the VM during system boot.
4703	</desc>
4704	</attribute>
4705
4706	<attribute name="autostartDelay" type="unsigned long">
4707	<desc>
4708	Number of seconds to wait until the VM should be started during system boot.
4709	</desc>
4710	</attribute>
4711
4712	<attribute name="autostopType" type="AutostopType">
4713	<desc>
4714	Action type to do when the system is shutting down.
4715	</desc>
4716	</attribute>
4717
4718	<attribute name="defaultFrontend" type="wstring">
4719	<desc>
4720	Selects which VM frontend should be used by default when launching
4721	this VM through the <link to="IMachine::launchVMProcess" /> method.
4722	Empty or @c null strings do not define a particular default, it is up
4723	to <link to="IMachine::launchVMProcess" /> to select one. See the
4724	description of <link to="IMachine::launchVMProcess" /> for the valid
4725	frontend types.
4726
4727	This per-VM setting overrides the default defined by
4728	<link to="ISystemProperties::defaultFrontend" /> attribute, and is
4729	overridden by a frontend type passed to
4730	<link to="IMachine::launchVMProcess" />.
4731	</desc>
4732	</attribute>
4733
4734	<method name="lockMachine">
4735	<desc>
4736	Locks the machine for the given session to enable the caller
4737	to make changes to the machine or start the VM or control
4738	VM execution.
4739
4740	There are two ways to lock a machine for such uses:
4741
4742	<ul>
4743	<li>If you want to make changes to the machine settings,
4744	you must obtain an exclusive write lock on the machine
4745	by setting @a lockType to @c Write.
4746
4747	This will only succeed if no other process has locked
4748	the machine to prevent conflicting changes. Only after
4749	an exclusive write lock has been obtained using this method, one
4750	can change all VM settings or execute the VM in the process
4751	space of the session object. (Note that the latter is only of
4752	interest if you actually want to write a new front-end for
4753	virtual machines; but this API gets called internally by
4754	the existing front-ends such as VBoxHeadless and the VirtualBox
4755	GUI to acquire a write lock on the machine that they are running.)
4756
4757	On success, write-locking the machine for a session creates
4758	a second copy of the IMachine object. It is this second object
4759	upon which changes can be made; in VirtualBox terminology, the
4760	second copy is "mutable". It is only this second, mutable machine
4761	object upon which you can call methods that change the
4762	machine state. After having called this method, you can
4763	obtain this second, mutable machine object using the
4764	<link to="ISession::machine" /> attribute.
4765	</li>
4766	<li>If you only want to check the machine state or control
4767	machine execution without actually changing machine
4768	settings (e.g. to get access to VM statistics or take
4769	a snapshot or save the machine state), then set the
4770	@a lockType argument to @c Shared.
4771
4772	If no other session has obtained a lock, you will obtain an
4773	exclusive write lock as described above. However, if another
4774	session has already obtained such a lock, then a link to that
4775	existing session will be established which allows you
4776	to control that existing session.
4777
4778	To find out which type of lock was obtained, you can
4779	inspect <link to="ISession::type" />, which will have been
4780	set to either @c WriteLock or @c Shared.
4781	</li>
4782	</ul>
4783
4784	In either case, you can get access to the <link to="IConsole" />
4785	object which controls VM execution.
4786
4787	Also in all of the above cases, one must always call
4788	<link to="ISession::unlockMachine" /> to release the lock on the machine, or
4789	the machine's state will eventually be set to "Aborted".
4790
4791	To change settings on a machine, the following sequence is typically
4792	performed:
4793
4794	<ol>
4795	<li>Call this method to obtain an exclusive write lock for the current session.</li>
4796
4797	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
4798
4799	<li>Change the settings of the machine by invoking IMachine methods.</li>
4800
4801	<li>Call <link to="IMachine::saveSettings" />.</li>
4802
4803	<li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
4804	</ol>
4805
4806	<result name="E_UNEXPECTED">
4807	Virtual machine not registered.
4808	</result>
4809	<result name="E_ACCESSDENIED">
4810	Process not started by OpenRemoteSession.
4811	</result>
4812	<result name="VBOX_E_INVALID_OBJECT_STATE">
4813	Session already open or being opened.
4814	</result>
4815	<result name="VBOX_E_VM_ERROR">
4816	Failed to assign machine to session.
4817	</result>
4818	</desc>
4819	<param name="session" type="ISession" dir="in">
4820	<desc>
4821	Session object for which the machine will be locked.
4822	</desc>
4823	</param>
4824	<param name="lockType" type="LockType" dir="in">
4825	<desc>
4826	If set to @c Write, then attempt to acquire an exclusive write lock or fail.
4827	If set to @c Shared, then either acquire an exclusive write lock or establish
4828	a link to an existing session.
4829	</desc>
4830	</param>
4831	</method>
4832
4833	<method name="launchVMProcess">
4834	<desc>
4835	Spawns a new process that will execute the virtual machine and obtains a shared
4836	lock on the machine for the calling session.
4837
4838	If launching the VM succeeds, the new VM process will create its own session
4839	and write-lock the machine for it, preventing conflicting changes from other
4840	processes. If the machine is already locked (because it is already running or
4841	because another session has a write lock), launching the VM process will therefore
4842	fail. Reversely, future attempts to obtain a write lock will also fail while the
4843	machine is running.
4844
4845	The caller's session object remains separate from the session opened by the new
4846	VM process. It receives its own <link to="IConsole" /> object which can be used
4847	to control machine execution, but it cannot be used to change all VM settings
4848	which would be available after a <link to="#lockMachine" /> call.
4849
4850	The caller must eventually release the session's shared lock by calling
4851	<link to="ISession::unlockMachine" /> on the local session object once this call
4852	has returned. However, the session's state (see <link to="ISession::state" />)
4853	will not return to "Unlocked" until the remote session has also unlocked
4854	the machine (i.e. the machine has stopped running).
4855
4856	Launching a VM process can take some time (a new VM is started in a new process,
4857	for which memory and other resources need to be set up). Because of this,
4858	an <link to="IProgress" /> object is returned to allow the caller to wait
4859	for this asynchronous operation to be completed. Until then, the caller's
4860	session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
4861	and <link to="ISession::console" /> attributes cannot be accessed.
4862	It is recommended to use <link to="IProgress::waitForCompletion" /> or
4863	similar calls to wait for completion. Completion is signalled when the VM
4864	is powered on. If launching the VM fails, error messages can be queried
4865	via the progress object, if available.
4866
4867	The progress object will have at least 2 sub-operations. The first
4868	operation covers the period up to the new VM process calls powerUp.
4869	The subsequent operations mirror the <link to="IConsole::powerUp"/>
4870	progress object. Because <link to="IConsole::powerUp"/> may require
4871	some extra sub-operations, the <link to="IProgress::operationCount"/>
4872	may change at the completion of operation.
4873
4874	For details on the teleportation progress operation, see
4875	<link to="IConsole::powerUp"/>.
4876
4877	The @a environment argument is a string containing definitions of
4878	environment variables in the following format:
4879	<pre>
4880	NAME[=VALUE]\n
4881	NAME[=VALUE]\n
4882	...
4883	</pre>
4884	where <tt>\\n</tt> is the new line character. These environment
4885	variables will be appended to the environment of the VirtualBox server
4886	process. If an environment variable exists both in the server process
4887	and in this list, the value from this list takes precedence over the
4888	server's variable. If the value of the environment variable is
4889	omitted, this variable will be removed from the resulting environment.
4890	If the environment string is @c null or empty, the server environment
4891	is inherited by the started process as is.
4892
4893	<result name="E_UNEXPECTED">
4894	Virtual machine not registered.
4895	</result>
4896	<result name="E_INVALIDARG">
4897	Invalid session type @a type.
4898	</result>
4899	<result name="VBOX_E_OBJECT_NOT_FOUND">
4900	No machine matching @a machineId found.
4901	</result>
4902	<result name="VBOX_E_INVALID_OBJECT_STATE">
4903	Session already open or being opened.
4904	</result>
4905	<result name="VBOX_E_IPRT_ERROR">
4906	Launching process for machine failed.
4907	</result>
4908	<result name="VBOX_E_VM_ERROR">
4909	Failed to assign machine to session.
4910	</result>
4911	</desc>
4912	<param name="session" type="ISession" dir="in">
4913	<desc>
4914	Client session object to which the VM process will be connected (this
4915	must be in "Unlocked" state).
4916	</desc>
4917	</param>
4918	<param name="type" type="wstring" dir="in">
4919	<desc>
4920	Front-end to use for the new VM process. The following are currently supported:
4921	<ul>
4922	<li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
4923	<li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
4924	<li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
4925	<li><tt>"emergencystop"</tt>: reserved value, used for aborting
4926	the currently running VM or session owner. In this case the
4927	@a session parameter may be @c null (if it is non-null it isn't
4928	used in any way), and the @a progress return value will be always
4929	@c null. The operation completes immediately.</li>
4930	<li><tt>""</tt>: use the per-VM default frontend if set, otherwise
4931	the global default defined in the system properties. If neither
4932	are set, the API will launch a <tt>"gui"</tt> session, which may
4933	fail if there is no windowing environment available. See
4934	<link to="IMachine::defaultFrontend"/> and
4935	<link to="ISystemProperties::defaultFrontend"/>.</li>
4936	</ul>
4937	</desc>
4938	</param>
4939	<param name="environment" type="wstring" dir="in">
4940	<desc>
4941	Environment to pass to the VM process.
4942	</desc>
4943	</param>
4944	<param name="progress" type="IProgress" dir="return">
4945	<desc>Progress object to track the operation completion.</desc>
4946	</param>
4947	</method>
4948
4949	<method name="setBootOrder">
4950	<desc>
4951	Puts the given device to the specified position in
4952	the boot order.
4953
4954	To indicate that no device is associated with the given position,
4955	<link to="DeviceType_Null"/> should be used.
4956
4957	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4958
4959	<result name="E_INVALIDARG">
4960	Boot @a position out of range.
4961	</result>
4962	<result name="E_NOTIMPL">
4963	Booting from USB @a device currently not supported.
4964	</result>
4965
4966	</desc>
4967	<param name="position" type="unsigned long" dir="in">
4968	<desc>
4969	Position in the boot order (@c 1 to the total number of
4970	devices the machine can boot from, as returned by
4971	<link to="ISystemProperties::maxBootPosition"/>).
4972	</desc>
4973	</param>
4974	<param name="device" type="DeviceType" dir="in">
4975	<desc>
4976	The type of the device used to boot at the given position.
4977	</desc>
4978	</param>
4979	</method>
4980
4981	<method name="getBootOrder" const="yes">
4982	<desc>
4983	Returns the device type that occupies the specified
4984	position in the boot order.
4985
4986	@todo [remove?]
4987	If the machine can have more than one device of the returned type
4988	(such as hard disks), then a separate method should be used to
4989	retrieve the individual device that occupies the given position.
4990
4991	If here are no devices at the given position, then
4992	<link to="DeviceType_Null"/> is returned.
4993
4994	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4995
4996	<result name="E_INVALIDARG">
4997	Boot @a position out of range.
4998	</result>
4999
5000	</desc>
5001	<param name="position" type="unsigned long" dir="in">
5002	<desc>
5003	Position in the boot order (@c 1 to the total number of
5004	devices the machine can boot from, as returned by
5005	<link to="ISystemProperties::maxBootPosition"/>).
5006	</desc>
5007	</param>
5008	<param name="device" type="DeviceType" dir="return">
5009	<desc>
5010	Device at the given position.
5011	</desc>
5012	</param>
5013	</method>
5014
5015	<method name="attachDevice">
5016	<desc>
5017	Attaches a device and optionally mounts a medium to the given storage
5018	controller (<link to="IStorageController" />, identified by @a name),
5019	at the indicated port and device.
5020
5021	This method is intended for managing storage devices in general while a
5022	machine is powered off. It can be used to attach and detach fixed
5023	and removable media. The following kind of media can be attached
5024	to a machine:
5025
5026	<ul>
5027	<li>For fixed and removable media, you can pass in a medium that was
5028	previously opened using <link to="IVirtualBox::openMedium" />.
5029	</li>
5030
5031	<li>Only for storage devices supporting removable media (such as
5032	DVDs and floppies), you can also specify a null pointer to
5033	indicate an empty drive or one of the medium objects listed
5034	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5035	arrays to indicate a host drive.
5036	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5037	to change the media while the machine is running.
5038	</li>
5039	</ul>
5040
5041	In a VM's default configuration of virtual machines, the secondary
5042	master of the IDE controller is used for a CD/DVD drive.
5043
5044	After calling this returns successfully, a new instance of
5045	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5046	attachments (see <link to="IMachine::mediumAttachments"/>).
5047
5048	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5049	information about attaching media.
5050
5051	The specified device slot must not have a device attached to it,
5052	or this method will fail.
5053
5054	<note>
5055	You cannot attach a device to a newly created machine until
5056	this machine's settings are saved to disk using
5057	<link to="#saveSettings"/>.
5058	</note>
5059	<note>
5060	If the medium is being attached indirectly, a new differencing medium
5061	will implicitly be created for it and attached instead. If the
5062	changes made to the machine settings (including this indirect
5063	attachment) are later cancelled using <link to="#discardSettings"/>,
5064	this implicitly created differencing medium will implicitly
5065	be deleted.
5066	</note>
5067
5068	<result name="E_INVALIDARG">
5069	SATA device, SATA port, IDE port or IDE slot out of range, or
5070	file or UUID not found.
5071	</result>
5072	<result name="VBOX_E_INVALID_OBJECT_STATE">
5073	Machine must be registered before media can be attached.
5074	</result>
5075	<result name="VBOX_E_INVALID_VM_STATE">
5076	Invalid machine state.
5077	</result>
5078	<result name="VBOX_E_OBJECT_IN_USE">
5079	A medium is already attached to this or another virtual machine.
5080	</result>
5081
5082	</desc>
5083	<param name="name" type="wstring" dir="in">
5084	<desc>Name of the storage controller to attach the device to.</desc>
5085	</param>
5086	<param name="controllerPort" type="long" dir="in">
5087	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5088	the primary controller and 1 specifies the secondary controller.
5089	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5090	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5091	</param>
5092	<param name="device" type="long" dir="in">
5093	<desc>Device slot in the given port to attach the device to. This is only
5094	relevant for IDE controllers, for which 0 specifies the master device and
5095	1 specifies the slave device. For all other controller types, this must
5096	be 0.</desc>
5097	</param>
5098	<param name="type" type="DeviceType" dir="in">
5099	<desc>Device type of the attached device. For media opened by
5100	<link to="IVirtualBox::openMedium" />, this must match the device type
5101	specified there.</desc>
5102	</param>
5103	<param name="medium" type="IMedium" dir="in">
5104	<desc>Medium to mount or @c null for an empty drive.</desc>
5105	</param>
5106	</method>
5107
5108	<method name="attachDeviceWithoutMedium">
5109	<desc>
5110	Attaches a device and optionally mounts a medium to the given storage
5111	controller (<link to="IStorageController" />, identified by @a name),
5112	at the indicated port and device.
5113
5114	This method is intended for managing storage devices in general while a
5115	machine is powered off. It can be used to attach and detach fixed
5116	and removable media. The following kind of media can be attached
5117	to a machine:
5118	<ul>
5119	<li>
5120	For fixed and removable media, you can pass in a medium that was
5121	previously opened using <link to="IVirtualBox::openMedium" />.
5122	</li>
5123
5124	<li>Only for storage devices supporting removable media (such as
5125	DVDs and floppies) with an empty drive or one of the medium objects listed
5126	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5127	arrays to indicate a host drive.
5128	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5129	to change the media while the machine is running.
5130	</li>
5131	</ul>
5132
5133	In a VM's default configuration of virtual machines, the secondary
5134	master of the IDE controller is used for a CD/DVD drive.
5135	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5136	attachments (see <link to="IMachine::mediumAttachments"/>).
5137
5138	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5139	information about attaching media.
5140
5141	The specified device slot must not have a device attached to it,
5142	or this method will fail.
5143	<note>
5144	You cannot attach a device to a newly created machine until
5145	this machine's settings are saved to disk using
5146	<link to="#saveSettings"/>.
5147	</note>
5148	<note>
5149	If the medium is being attached indirectly, a new differencing medium
5150	will implicitly be created for it and attached instead. If the
5151	changes made to the machine settings (including this indirect
5152	attachment) are later cancelled using <link to="#discardSettings"/>,
5153	this implicitly created differencing medium will implicitly
5154	be deleted.
5155	</note>
5156
5157	<result name="E_INVALIDARG">
5158	SATA device, SATA port, IDE port or IDE slot out of range, or
5159	file or UUID not found.
5160	</result>
5161	<result name="VBOX_E_INVALID_OBJECT_STATE">
5162	Machine must be registered before media can be attached.
5163	</result>
5164	<result name="VBOX_E_INVALID_VM_STATE">
5165	Invalid machine state.
5166	</result>
5167	<result name="VBOX_E_OBJECT_IN_USE">
5168	A medium is already attached to this or another virtual machine.
5169	</result>
5170	</desc>
5171	<param name="name" type="wstring" dir="in">
5172	<desc>Name of the storage controller to attach the device to.</desc>
5173	</param>
5174	<param name="controllerPort" type="long" dir="in">
5175	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5176	the primary controller and 1 specifies the secondary controller.
5177	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5178	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5179	</param>
5180	<param name="device" type="long" dir="in">
5181	<desc>Device slot in the given port to attach the device to. This is only
5182	relevant for IDE controllers, for which 0 specifies the master device and
5183	1 specifies the slave device. For all other controller types, this must
5184	be 0.</desc>
5185	</param>
5186	<param name="type" type="DeviceType" dir="in">
5187	<desc>Device type of the attached device. For media opened by
5188	<link to="IVirtualBox::openMedium" />, this must match the device type
5189	specified there.</desc>
5190	</param>
5191	</method>
5192
5193	<method name="detachDevice">
5194	<desc>
5195	Detaches the device attached to a device slot of the specified bus.
5196
5197	Detaching the device from the virtual machine is deferred. This means
5198	that the medium remains associated with the machine when this method
5199	returns and gets actually de-associated only after a successful
5200	<link to="#saveSettings"/> call. See <link to="IMedium"/>
5201	for more detailed information about attaching media.
5202
5203	<note>
5204	You cannot detach a device from a running machine.
5205	</note>
5206	<note>
5207	Detaching differencing media implicitly created by <link
5208	to="#attachDevice"/> for the indirect attachment using this
5209	method will <b>not</b> implicitly delete them. The
5210	<link to="IMedium::deleteStorage"/> operation should be
5211	explicitly performed by the caller after the medium is successfully
5212	detached and the settings are saved with
5213	<link to="#saveSettings"/>, if it is the desired action.
5214	</note>
5215
5216	<result name="VBOX_E_INVALID_VM_STATE">
5217	Attempt to detach medium from a running virtual machine.
5218	</result>
5219	<result name="VBOX_E_OBJECT_NOT_FOUND">
5220	No medium attached to given slot/bus.
5221	</result>
5222	<result name="VBOX_E_NOT_SUPPORTED">
5223	Medium format does not support storage deletion (only for implicitly
5224	created differencing media, should not happen).
5225	</result>
5226
5227	</desc>
5228	<param name="name" type="wstring" dir="in">
5229	<desc>Name of the storage controller to detach the medium from.</desc>
5230	</param>
5231	<param name="controllerPort" type="long" dir="in">
5232	<desc>Port number to detach the medium from.</desc>
5233	</param>
5234	<param name="device" type="long" dir="in">
5235	<desc>Device slot number to detach the medium from.</desc>
5236	</param>
5237	</method>
5238
5239	<method name="passthroughDevice">
5240	<desc>
5241	Sets the passthrough mode of an existing DVD device. Changing the
5242	setting while the VM is running is forbidden. The setting is only used
5243	if at VM start the device is configured as a host DVD drive, in all
5244	other cases it is ignored. The device must already exist; see
5245	<link to="IMachine::attachDevice"/> for how to attach a new device.
5246
5247	The @a controllerPort and @a device parameters specify the device slot and
5248	have have the same meaning as with <link to="IMachine::attachDevice" />.
5249
5250	<result name="E_INVALIDARG">
5251	SATA device, SATA port, IDE port or IDE slot out of range.
5252	</result>
5253	<result name="VBOX_E_INVALID_OBJECT_STATE">
5254	Attempt to modify an unregistered virtual machine.
5255	</result>
5256	<result name="VBOX_E_INVALID_VM_STATE">
5257	Invalid machine state.
5258	</result>
5259
5260	</desc>
5261	<param name="name" type="wstring" dir="in">
5262	<desc>Name of the storage controller.</desc>
5263	</param>
5264	<param name="controllerPort" type="long" dir="in">
5265	<desc>Storage controller port.</desc>
5266	</param>
5267	<param name="device" type="long" dir="in">
5268	<desc>Device slot in the given port.</desc>
5269	</param>
5270	<param name="passthrough" type="boolean" dir="in">
5271	<desc>New value for the passthrough setting.</desc>
5272	</param>
5273	</method>
5274
5275	<method name="temporaryEjectDevice">
5276	<desc>
5277	Sets the behavior for guest-triggered medium eject. In some situations
5278	it is desirable that such ejects update the VM configuration, and in
5279	others the eject should keep the VM configuration. The device must
5280	already exist; see <link to="IMachine::attachDevice"/> for how to
5281	attach a new device.
5282
5283	The @a controllerPort and @a device parameters specify the device slot and
5284	have have the same meaning as with <link to="IMachine::attachDevice" />.
5285
5286	<result name="E_INVALIDARG">
5287	SATA device, SATA port, IDE port or IDE slot out of range.
5288	</result>
5289	<result name="VBOX_E_INVALID_OBJECT_STATE">
5290	Attempt to modify an unregistered virtual machine.
5291	</result>
5292	<result name="VBOX_E_INVALID_VM_STATE">
5293	Invalid machine state.
5294	</result>
5295
5296	</desc>
5297	<param name="name" type="wstring" dir="in">
5298	<desc>Name of the storage controller.</desc>
5299	</param>
5300	<param name="controllerPort" type="long" dir="in">
5301	<desc>Storage controller port.</desc>
5302	</param>
5303	<param name="device" type="long" dir="in">
5304	<desc>Device slot in the given port.</desc>
5305	</param>
5306	<param name="temporaryEject" type="boolean" dir="in">
5307	<desc>New value for the eject behavior.</desc>
5308	</param>
5309	</method>
5310
5311	<method name="nonRotationalDevice">
5312	<desc>
5313	Sets a flag in the device information which indicates that the medium
5314	is not based on rotational technology, i.e. that the access times are
5315	more or less independent of the position on the medium. This may or may
5316	not be supported by a particular drive, and is silently ignored in the
5317	latter case. At the moment only hard disks (which is a misnomer in this
5318	context) accept this setting. Changing the setting while the VM is
5319	running is forbidden. The device must already exist; see
5320	<link to="IMachine::attachDevice"/> for how to attach a new device.
5321
5322	The @a controllerPort and @a device parameters specify the device slot and
5323	have have the same meaning as with <link to="IMachine::attachDevice" />.
5324
5325	<result name="E_INVALIDARG">
5326	SATA device, SATA port, IDE port or IDE slot out of range.
5327	</result>
5328	<result name="VBOX_E_INVALID_OBJECT_STATE">
5329	Attempt to modify an unregistered virtual machine.
5330	</result>
5331	<result name="VBOX_E_INVALID_VM_STATE">
5332	Invalid machine state.
5333	</result>
5334
5335	</desc>
5336	<param name="name" type="wstring" dir="in">
5337	<desc>Name of the storage controller.</desc>
5338	</param>
5339	<param name="controllerPort" type="long" dir="in">
5340	<desc>Storage controller port.</desc>
5341	</param>
5342	<param name="device" type="long" dir="in">
5343	<desc>Device slot in the given port.</desc>
5344	</param>
5345	<param name="nonRotational" type="boolean" dir="in">
5346	<desc>New value for the non-rotational device flag.</desc>
5347	</param>
5348	</method>
5349
5350	<method name="setAutoDiscardForDevice">
5351	<desc>
5352	Sets a flag in the device information which indicates that the medium
5353	supports discarding unsused blocks (called trimming for SATA or unmap
5354	for SCSI devices) .This may or may not be supported by a particular drive,
5355	and is silently ignored in the latter case. At the moment only hard disks
5356	(which is a misnomer in this context) accept this setting. Changing the
5357	setting while the VM is running is forbidden. The device must already
5358	exist; see <link to="IMachine::attachDevice"/> for how to attach a new
5359	device.
5360
5361	The @a controllerPort and @a device parameters specify the device slot and
5362	have have the same meaning as with <link to="IMachine::attachDevice" />.
5363
5364	<result name="E_INVALIDARG">
5365	SATA device, SATA port, SCSI port out of range.
5366	</result>
5367	<result name="VBOX_E_INVALID_OBJECT_STATE">
5368	Attempt to modify an unregistered virtual machine.
5369	</result>
5370	<result name="VBOX_E_INVALID_VM_STATE">
5371	Invalid machine state.
5372	</result>
5373
5374	</desc>
5375	<param name="name" type="wstring" dir="in">
5376	<desc>Name of the storage controller.</desc>
5377	</param>
5378	<param name="controllerPort" type="long" dir="in">
5379	<desc>Storage controller port.</desc>
5380	</param>
5381	<param name="device" type="long" dir="in">
5382	<desc>Device slot in the given port.</desc>
5383	</param>
5384	<param name="discard" type="boolean" dir="in">
5385	<desc>New value for the discard device flag.</desc>
5386	</param>
5387	</method>
5388
5389	<method name="setBandwidthGroupForDevice">
5390	<desc>
5391	Sets the bandwidth group of an existing storage device.
5392	The device must already exist; see <link to="IMachine::attachDevice"/>
5393	for how to attach a new device.
5394
5395	The @a controllerPort and @a device parameters specify the device slot and
5396	have have the same meaning as with <link to="IMachine::attachDevice" />.
5397
5398	<result name="E_INVALIDARG">
5399	SATA device, SATA port, IDE port or IDE slot out of range.
5400	</result>
5401	<result name="VBOX_E_INVALID_OBJECT_STATE">
5402	Attempt to modify an unregistered virtual machine.
5403	</result>
5404	<result name="VBOX_E_INVALID_VM_STATE">
5405	Invalid machine state.
5406	</result>
5407
5408	</desc>
5409	<param name="name" type="wstring" dir="in">
5410	<desc>Name of the storage controller.</desc>
5411	</param>
5412	<param name="controllerPort" type="long" dir="in">
5413	<desc>Storage controller port.</desc>
5414	</param>
5415	<param name="device" type="long" dir="in">
5416	<desc>Device slot in the given port.</desc>
5417	</param>
5418	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
5419	<desc>New value for the bandwidth group or @c null for no group.</desc>
5420	</param>
5421	</method>
5422
5423	<method name="setNoBandwidthGroupForDevice">
5424	<desc>
5425	Sets no bandwidth group for an existing storage device.
5426	The device must already exist; see <link to="IMachine::attachDevice"/>
5427	for how to attach a new device.
5428	The @a controllerPort and @a device parameters specify the device slot and
5429	have have the same meaning as with <link to="IMachine::attachDevice" />.
5430	<result name="E_INVALIDARG">
5431	SATA device, SATA port, IDE port or IDE slot out of range.
5432	</result>
5433	<result name="VBOX_E_INVALID_OBJECT_STATE">
5434	Attempt to modify an unregistered virtual machine.
5435	</result>
5436	<result name="VBOX_E_INVALID_VM_STATE">
5437	Invalid machine state.
5438	</result>
5439
5440	</desc>
5441	<param name="name" type="wstring" dir="in">
5442	<desc>Name of the storage controller.</desc>
5443	</param>
5444	<param name="controllerPort" type="long" dir="in">
5445	<desc>Storage controller port.</desc>
5446	</param>
5447	<param name="device" type="long" dir="in">
5448	<desc>Device slot in the given port.</desc>
5449	</param>
5450	</method>
5451
5452
5453	<method name="unmountMedium">
5454	<desc>
5455	Unmounts any currently mounted medium (<link to="IMedium" />,
5456	identified by the given UUID @a id) to the given storage controller
5457	(<link to="IStorageController" />, identified by @a name),
5458	at the indicated port and device. The device must already exist;
5459
5460	This method is intended only for managing removable media, where the
5461	device is fixed but media is changeable at runtime (such as DVDs
5462	and floppies). It cannot be used for fixed media such as hard disks.
5463
5464	The @a controllerPort and @a device parameters specify the device slot
5465	and have have the same meaning as with
5466	<link to="IMachine::attachDevice" />.
5467
5468	The specified device slot must have a medium mounted, which will be
5469	unmounted. If there is no mounted medium it will do nothing.
5470	See <link to="IMedium"/> for more detailed information about
5471	attaching/unmounting media.
5472
5473	<result name="E_INVALIDARG">
5474	SATA device, SATA port, IDE port or IDE slot out of range.
5475	</result>
5476	<result name="VBOX_E_INVALID_OBJECT_STATE">
5477	Attempt to unmount medium that is not removeable - not dvd or floppy.
5478	</result>
5479	<result name="VBOX_E_INVALID_VM_STATE">
5480	Invalid machine state.
5481	</result>
5482	<result name="VBOX_E_OBJECT_IN_USE">
5483	Medium already attached to this or another virtual machine.
5484	</result>
5485	<result name="VBOX_E_OBJECT_NOT_FOUND">
5486	Medium not attached to specified port, device, controller.
5487	</result>
5488
5489	</desc>
5490	<param name="name" type="wstring" dir="in">
5491	<desc>Name of the storage controller to unmount the medium from.</desc>
5492	</param>
5493	<param name="controllerPort" type="long" dir="in">
5494	<desc>Port to unmount the medium from.</desc>
5495	</param>
5496	<param name="device" type="long" dir="in">
5497	<desc>Device slot in the given port to unmount the medium from.</desc>
5498	</param>
5499	<param name="force" type="boolean" dir="in">
5500	<desc>Allows to force unmount of a medium which is locked by
5501	the device slot in the given port medium is attached to.</desc>
5502	</param>
5503	</method>
5504
5505	<method name="mountMedium">
5506	<desc>
5507	Mounts a medium (<link to="IMedium" />, identified
5508	by the given UUID @a id) to the given storage controller
5509	(<link to="IStorageController" />, identified by @a name),
5510	at the indicated port and device. The device must already exist;
5511	see <link to="IMachine::attachDevice"/> for how to attach a new device.
5512
5513	This method is intended only for managing removable media, where the
5514	device is fixed but media is changeable at runtime (such as DVDs
5515	and floppies). It cannot be used for fixed media such as hard disks.
5516
5517	The @a controllerPort and @a device parameters specify the device slot and
5518	have have the same meaning as with <link to="IMachine::attachDevice" />.
5519
5520	The specified device slot can have a medium mounted, which will be
5521	unmounted first. Specifying a zero UUID (or an empty string) for
5522	@a medium does just an unmount.
5523
5524	See <link to="IMedium"/> for more detailed information about
5525	attaching media.
5526
5527	<result name="E_INVALIDARG">
5528	SATA device, SATA port, IDE port or IDE slot out of range.
5529	</result>
5530	<result name="VBOX_E_INVALID_OBJECT_STATE">
5531	Attempt to attach medium to an unregistered virtual machine.
5532	</result>
5533	<result name="VBOX_E_INVALID_VM_STATE">
5534	Invalid machine state.
5535	</result>
5536	<result name="VBOX_E_OBJECT_IN_USE">
5537	Medium already attached to this or another virtual machine.
5538	</result>
5539
5540	</desc>
5541	<param name="name" type="wstring" dir="in">
5542	<desc>Name of the storage controller to attach the medium to.</desc>
5543	</param>
5544	<param name="controllerPort" type="long" dir="in">
5545	<desc>Port to attach the medium to.</desc>
5546	</param>
5547	<param name="device" type="long" dir="in">
5548	<desc>Device slot in the given port to attach the medium to.</desc>
5549	</param>
5550	<param name="medium" type="IMedium" dir="in">
5551	<desc>Medium to mount or @c null for an empty drive.</desc>
5552	</param>
5553	<param name="force" type="boolean" dir="in">
5554	<desc>Allows to force unmount/mount of a medium which is locked by
5555	the device slot in the given port to attach the medium to.</desc>
5556	</param>
5557	</method>
5558
5559	<method name="getMedium" const="yes">
5560	<desc>
5561	Returns the virtual medium attached to a device slot of the specified
5562	bus.
5563
5564	Note that if the medium was indirectly attached by
5565	<link to="#mountMedium"/> to the given device slot then this
5566	method will return not the same object as passed to the
5567	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5568	more detailed information about mounting a medium.
5569
5570	<result name="VBOX_E_OBJECT_NOT_FOUND">
5571	No medium attached to given slot/bus.
5572	</result>
5573
5574	</desc>
5575	<param name="name" type="wstring" dir="in">
5576	<desc>Name of the storage controller the medium is attached to.</desc>
5577	</param>
5578	<param name="controllerPort" type="long" dir="in">
5579	<desc>Port to query.</desc>
5580	</param>
5581	<param name="device" type="long" dir="in">
5582	<desc>Device slot in the given port to query.</desc>
5583	</param>
5584	<param name="medium" type="IMedium" dir="return">
5585	<desc>Attached medium object.</desc>
5586	</param>
5587	</method>
5588
5589	<method name="getMediumAttachmentsOfController" const="yes">
5590	<desc>
5591	Returns an array of medium attachments which are attached to the
5592	the controller with the given name.
5593
5594	<result name="VBOX_E_OBJECT_NOT_FOUND">
5595	A storage controller with given name doesn't exist.
5596	</result>
5597	</desc>
5598	<param name="name" type="wstring" dir="in"/>
5599	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5600	</method>
5601
5602	<method name="getMediumAttachment" const="yes">
5603	<desc>
5604	Returns a medium attachment which corresponds to the controller with
5605	the given name, on the given port and device slot.
5606
5607	<result name="VBOX_E_OBJECT_NOT_FOUND">
5608	No attachment exists for the given controller/port/device combination.
5609	</result>
5610	</desc>
5611	<param name="name" type="wstring" dir="in"/>
5612	<param name="controllerPort" type="long" dir="in"/>
5613	<param name="device" type="long" dir="in"/>
5614	<param name="attachment" type="IMediumAttachment" dir="return"/>
5615	</method>
5616
5617	<method name="attachHostPCIDevice">
5618	<desc>
5619	Attaches host PCI device with the given (host) PCI address to the
5620	PCI bus of the virtual machine. Please note, that this operation
5621	is two phase, as real attachment will happen when VM will start,
5622	and most information will be delivered as IHostPCIDevicePlugEvent
5623	on IVirtualBox event source.
5624
5625	<see><link to="IHostPCIDevicePlugEvent"/></see>
5626
5627	<result name="VBOX_E_INVALID_VM_STATE">
5628	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5629	</result>
5630	<result name="VBOX_E_PDM_ERROR">
5631	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5632	</result>
5633	<result name="VBOX_E_NOT_SUPPORTED">
5634	Hardware or host OS doesn't allow PCI device passthrought.
5635	</result>
5636	</desc>
5637	<param name="hostAddress" type="long" dir="in">
5638	<desc>Address of the host PCI device.</desc>
5639	</param>
5640	<param name="desiredGuestAddress" type="long" dir="in">
5641	<desc>Desired position of this device on guest PCI bus.</desc>
5642	</param>
5643	<param name="tryToUnbind" type="boolean" dir="in">
5644	<desc>If VMM shall try to unbind existing drivers from the
5645	device before attaching it to the guest.</desc>
5646	</param>
5647	</method>
5648
5649	<method name="detachHostPCIDevice">
5650	<desc>
5651	Detach host PCI device from the virtual machine.
5652	Also HostPCIDevicePlugEvent on IVirtualBox event source
5653	will be delivered. As currently we don't support hot device
5654	unplug, IHostPCIDevicePlugEvent event is delivered immediately.
5655
5656	<see><link to="IHostPCIDevicePlugEvent"/></see>
5657
5658	<result name="VBOX_E_INVALID_VM_STATE">
5659	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5660	</result>
5661	<result name="VBOX_E_OBJECT_NOT_FOUND">
5662	This host device is not attached to this machine.
5663	</result>
5664	<result name="VBOX_E_PDM_ERROR">
5665	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5666	</result>
5667	<result name="VBOX_E_NOT_SUPPORTED">
5668	Hardware or host OS doesn't allow PCI device passthrought.
5669	</result>
5670	</desc>
5671	<param name="hostAddress" type="long" dir="in">
5672	<desc>Address of the host PCI device.</desc>
5673	</param>
5674	</method>
5675
5676	<method name="getNetworkAdapter" const="yes">
5677	<desc>
5678	Returns the network adapter associated with the given slot.
5679	Slots are numbered sequentially, starting with zero. The total
5680	number of adapters per machine is defined by the
5681	<link to="ISystemProperties::getMaxNetworkAdapters"/> property,
5682	so the maximum slot number is one less than that property's value.
5683
5684	<result name="E_INVALIDARG">
5685	Invalid @a slot number.
5686	</result>
5687
5688	</desc>
5689	<param name="slot" type="unsigned long" dir="in"/>
5690	<param name="adapter" type="INetworkAdapter" dir="return"/>
5691	</method>
5692
5693	<method name="addStorageController">
5694	<desc>
5695	Adds a new storage controller (SCSI, SAS or SATA controller) to the
5696	machine and returns it as an instance of
5697	<link to="IStorageController" />.
5698
5699	@a name identifies the controller for subsequent calls such as
5700	<link to="#getStorageControllerByName" />,
5701	<link to="#getStorageControllerByInstance" />,
5702	<link to="#removeStorageController" />,
5703	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5704
5705	After the controller has been added, you can set its exact
5706	type by setting the <link to="IStorageController::controllerType" />.
5707
5708	<result name="VBOX_E_OBJECT_IN_USE">
5709	A storage controller with given name exists already.
5710	</result>
5711	<result name="E_INVALIDARG">
5712	Invalid @a controllerType.
5713	</result>
5714	</desc>
5715	<param name="name" type="wstring" dir="in"/>
5716	<param name="connectionType" type="StorageBus" dir="in"/>
5717	<param name="controller" type="IStorageController" dir="return"/>
5718	</method>
5719
5720	<method name="getStorageControllerByName" const="yes">
5721	<desc>
5722	Returns a storage controller with the given name.
5723
5724	<result name="VBOX_E_OBJECT_NOT_FOUND">
5725	A storage controller with given name doesn't exist.
5726	</result>
5727	</desc>
5728	<param name="name" type="wstring" dir="in"/>
5729	<param name="storageController" type="IStorageController" dir="return"/>
5730	</method>
5731
5732	<method name="getStorageControllerByInstance" const="yes">
5733	<desc>
5734	Returns a storage controller with the given instance number.
5735
5736	<result name="VBOX_E_OBJECT_NOT_FOUND">
5737	A storage controller with given instance number doesn't exist.
5738	</result>
5739	</desc>
5740	<param name="instance" type="unsigned long" dir="in"/>
5741	<param name="storageController" type="IStorageController" dir="return"/>
5742	</method>
5743
5744	<method name="removeStorageController">
5745	<desc>
5746	Removes a storage controller from the machine with all devices attached to it.
5747
5748	<result name="VBOX_E_OBJECT_NOT_FOUND">
5749	A storage controller with given name doesn't exist.
5750	</result>
5751	<result name="VBOX_E_NOT_SUPPORTED">
5752	Medium format does not support storage deletion (only for implicitly
5753	created differencing media, should not happen).
5754	</result>
5755	</desc>
5756	<param name="name" type="wstring" dir="in"/>
5757	</method>
5758
5759	<method name="setStorageControllerBootable">
5760	<desc>
5761	Sets the bootable flag of the storage controller with the given name.
5762
5763	<result name="VBOX_E_OBJECT_NOT_FOUND">
5764	A storage controller with given name doesn't exist.
5765	</result>
5766	<result name="VBOX_E_OBJECT_IN_USE">
5767	Another storage controller is marked as bootable already.
5768	</result>
5769	</desc>
5770	<param name="name" type="wstring" dir="in"/>
5771	<param name="bootable" type="boolean" dir="in"/>
5772	</method>
5773
5774	<method name="getSerialPort" const="yes">
5775	<desc>
5776	Returns the serial port associated with the given slot.
5777	Slots are numbered sequentially, starting with zero. The total
5778	number of serial ports per machine is defined by the
5779	<link to="ISystemProperties::serialPortCount"/> property,
5780	so the maximum slot number is one less than that property's value.
5781
5782	<result name="E_INVALIDARG">
5783	Invalid @a slot number.
5784	</result>
5785
5786	</desc>
5787	<param name="slot" type="unsigned long" dir="in"/>
5788	<param name="port" type="ISerialPort" dir="return"/>
5789	</method>
5790
5791	<method name="getParallelPort" const="yes">
5792	<desc>
5793	Returns the parallel port associated with the given slot.
5794	Slots are numbered sequentially, starting with zero. The total
5795	number of parallel ports per machine is defined by the
5796	<link to="ISystemProperties::parallelPortCount"/> property,
5797	so the maximum slot number is one less than that property's value.
5798
5799	<result name="E_INVALIDARG">
5800	Invalid @a slot number.
5801	</result>
5802
5803	</desc>
5804	<param name="slot" type="unsigned long" dir="in"/>
5805	<param name="port" type="IParallelPort" dir="return"/>
5806	</method>
5807
5808	<method name="getExtraDataKeys">
5809	<desc>
5810	Returns an array representing the machine-specific extra data keys
5811	which currently have values defined.
5812	</desc>
5813	<param name="keys" type="wstring" dir="return" safearray="yes">
5814	<desc>Array of extra data keys.</desc>
5815	</param>
5816	</method>
5817
5818	<method name="getExtraData">
5819	<desc>
5820	Returns associated machine-specific extra data.
5821
5822	If the requested data @a key does not exist, this function will
5823	succeed and return an empty string in the @a value argument.
5824
5825	<result name="VBOX_E_FILE_ERROR">
5826	Settings file not accessible.
5827	</result>
5828	<result name="VBOX_E_XML_ERROR">
5829	Could not parse the settings file.
5830	</result>
5831
5832	</desc>
5833	<param name="key" type="wstring" dir="in">
5834	<desc>Name of the data key to get.</desc>
5835	</param>
5836	<param name="value" type="wstring" dir="return">
5837	<desc>Value of the requested data key.</desc>
5838	</param>
5839	</method>
5840
5841	<method name="setExtraData">
5842	<desc>
5843	Sets associated machine-specific extra data.
5844
5845	If you pass @c null or an empty string as a key @a value, the given
5846	@a key will be deleted.
5847
5848	<note>
5849	Before performing the actual data change, this method will ask all
5850	registered listeners using the
5851	<link to="IExtraDataCanChangeEvent"/>
5852	notification for a permission. If one of the listeners refuses the
5853	new value, the change will not be performed.
5854	</note>
5855	<note>
5856	On success, the
5857	<link to="IExtraDataChangedEvent"/> notification
5858	is called to inform all registered listeners about a successful data
5859	change.
5860	</note>
5861	<note>
5862	This method can be called outside the machine session and therefore
5863	it's a caller's responsibility to handle possible race conditions
5864	when several clients change the same key at the same time.
5865	</note>
5866
5867	<result name="VBOX_E_FILE_ERROR">
5868	Settings file not accessible.
5869	</result>
5870	<result name="VBOX_E_XML_ERROR">
5871	Could not parse the settings file.
5872	</result>
5873
5874	</desc>
5875	<param name="key" type="wstring" dir="in">
5876	<desc>Name of the data key to set.</desc>
5877	</param>
5878	<param name="value" type="wstring" dir="in">
5879	<desc>Value to assign to the key.</desc>
5880	</param>
5881	</method>
5882
5883	<method name="getCPUProperty" const="yes">
5884	<desc>
5885	Returns the virtual CPU boolean value of the specified property.
5886
5887	<result name="E_INVALIDARG">
5888	Invalid property.
5889	</result>
5890
5891	</desc>
5892	<param name="property" type="CPUPropertyType" dir="in">
5893	<desc>
5894	Property type to query.
5895	</desc>
5896	</param>
5897	<param name="value" type="boolean" dir="return">
5898	<desc>
5899	Property value.
5900	</desc>
5901	</param>
5902	</method>
5903
5904	<method name="setCPUProperty">
5905	<desc>
5906	Sets the virtual CPU boolean value of the specified property.
5907
5908	<result name="E_INVALIDARG">
5909	Invalid property.
5910	</result>
5911
5912	</desc>
5913	<param name="property" type="CPUPropertyType" dir="in">
5914	<desc>
5915	Property type to query.
5916	</desc>
5917	</param>
5918	<param name="value" type="boolean" dir="in">
5919	<desc>
5920	Property value.
5921	</desc>
5922	</param>
5923	</method>
5924
5925	<method name="getCPUIDLeaf" const="yes">
5926	<desc>
5927	Returns the virtual CPU cpuid information for the specified leaf.
5928
5929	Currently supported index values for cpuid:
5930	Standard CPUID leafs: 0 - 0xA
5931	Extended CPUID leafs: 0x80000000 - 0x8000000A
5932
5933	See the Intel and AMD programmer's manuals for detailed information
5934	about the cpuid instruction and its leafs.
5935	<result name="E_INVALIDARG">
5936	Invalid id.
5937	</result>
5938
5939	</desc>
5940	<param name="id" type="unsigned long" dir="in">
5941	<desc>
5942	CPUID leaf index.
5943	</desc>
5944	</param>
5945	<param name="valEax" type="unsigned long" dir="out">
5946	<desc>
5947	CPUID leaf value for register eax.
5948	</desc>
5949	</param>
5950	<param name="valEbx" type="unsigned long" dir="out">
5951	<desc>
5952	CPUID leaf value for register ebx.
5953	</desc>
5954	</param>
5955	<param name="valEcx" type="unsigned long" dir="out">
5956	<desc>
5957	CPUID leaf value for register ecx.
5958	</desc>
5959	</param>
5960	<param name="valEdx" type="unsigned long" dir="out">
5961	<desc>
5962	CPUID leaf value for register edx.
5963	</desc>
5964	</param>
5965	</method>
5966
5967	<method name="setCPUIDLeaf">
5968	<desc>
5969	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5970	are not passed unmodified. VirtualBox clears features that it doesn't support.
5971
5972	Currently supported index values for cpuid:
5973	Standard CPUID leafs: 0 - 0xA
5974	Extended CPUID leafs: 0x80000000 - 0x8000000A
5975
5976	See the Intel and AMD programmer's manuals for detailed information
5977	about the cpuid instruction and its leafs.
5978
5979	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5980	random crashes inside VMs.
5981	<result name="E_INVALIDARG">
5982	Invalid id.
5983	</result>
5984
5985	</desc>
5986	<param name="id" type="unsigned long" dir="in">
5987	<desc>
5988	CPUID leaf index.
5989	</desc>
5990	</param>
5991	<param name="valEax" type="unsigned long" dir="in">
5992	<desc>
5993	CPUID leaf value for register eax.
5994	</desc>
5995	</param>
5996	<param name="valEbx" type="unsigned long" dir="in">
5997	<desc>
5998	CPUID leaf value for register ebx.
5999	</desc>
6000	</param>
6001	<param name="valEcx" type="unsigned long" dir="in">
6002	<desc>
6003	CPUID leaf value for register ecx.
6004	</desc>
6005	</param>
6006	<param name="valEdx" type="unsigned long" dir="in">
6007	<desc>
6008	CPUID leaf value for register edx.
6009	</desc>
6010	</param>
6011	</method>
6012
6013	<method name="removeCPUIDLeaf">
6014	<desc>
6015	Removes the virtual CPU cpuid leaf for the specified index
6016
6017	<result name="E_INVALIDARG">
6018	Invalid id.
6019	</result>
6020
6021	</desc>
6022	<param name="id" type="unsigned long" dir="in">
6023	<desc>
6024	CPUID leaf index.
6025	</desc>
6026	</param>
6027	</method>
6028
6029	<method name="removeAllCPUIDLeaves">
6030	<desc>
6031	Removes all the virtual CPU cpuid leaves
6032	</desc>
6033	</method>
6034
6035	<method name="getHWVirtExProperty" const="yes">
6036	<desc>
6037	Returns the value of the specified hardware virtualization boolean property.
6038
6039	<result name="E_INVALIDARG">
6040	Invalid property.
6041	</result>
6042
6043	</desc>
6044	<param name="property" type="HWVirtExPropertyType" dir="in">
6045	<desc>
6046	Property type to query.
6047	</desc>
6048	</param>
6049	<param name="value" type="boolean" dir="return">
6050	<desc>
6051	Property value.
6052	</desc>
6053	</param>
6054	</method>
6055
6056	<method name="setHWVirtExProperty">
6057	<desc>
6058	Sets a new value for the specified hardware virtualization boolean property.
6059
6060	<result name="E_INVALIDARG">
6061	Invalid property.
6062	</result>
6063
6064	</desc>
6065	<param name="property" type="HWVirtExPropertyType" dir="in">
6066	<desc>
6067	Property type to set.
6068	</desc>
6069	</param>
6070	<param name="value" type="boolean" dir="in">
6071	<desc>
6072	New property value.
6073	</desc>
6074	</param>
6075	</method>
6076
6077	<method name="saveSettings">
6078	<desc>
6079	Saves any changes to machine settings made since the session
6080	has been opened or a new machine has been created, or since the
6081	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
6082	For registered machines, new settings become visible to all
6083	other VirtualBox clients after successful invocation of this
6084	method.
6085	<note>
6086	The method sends <link to="IMachineDataChangedEvent"/>
6087	notification event after the configuration has been successfully
6088	saved (only for registered machines).
6089	</note>
6090	<note>
6091	Calling this method is only valid on instances returned
6092	by <link to="ISession::machine"/> and on new machines
6093	created by <link to="IVirtualBox::createMachine"/> but not
6094	yet registered, or on unregistered machines after calling
6095	<link to="IMachine::unregister"/>.
6096	</note>
6097
6098	<result name="VBOX_E_FILE_ERROR">
6099	Settings file not accessible.
6100	</result>
6101	<result name="VBOX_E_XML_ERROR">
6102	Could not parse the settings file.
6103	</result>
6104	<result name="E_ACCESSDENIED">
6105	Modification request refused.
6106	</result>
6107
6108	</desc>
6109	</method>
6110
6111	<method name="discardSettings">
6112	<desc>
6113	Discards any changes to the machine settings made since the session
6114	has been opened or since the last call to <link to="#saveSettings"/>
6115	or <link to="#discardSettings"/>.
6116	<note>
6117	Calling this method is only valid on instances returned
6118	by <link to="ISession::machine"/> and on new machines
6119	created by <link to="IVirtualBox::createMachine"/> or
6120	opened by <link to="IVirtualBox::openMachine"/> but not
6121	yet registered, or on unregistered machines after calling
6122	<link to="IMachine::unregister"/>.
6123	</note>
6124
6125	<result name="VBOX_E_INVALID_VM_STATE">
6126	Virtual machine is not mutable.
6127	</result>
6128
6129	</desc>
6130	</method>
6131
6132	<method name="unregister">
6133	<desc>
6134	Unregisters a machine previously registered with
6135	<link to="IVirtualBox::registerMachine"/> and optionally do additional
6136	cleanup before the machine is unregistered.
6137
6138	This method does not delete any files. It only changes the machine configuration and
6139	the list of registered machines in the VirtualBox object. To delete the files which
6140	belonged to the machine, including the XML file of the machine itself, call
6141	<link to="#deleteConfig"/>, optionally with the array of IMedium objects which was returned
6142	from this method.
6143
6144	How thoroughly this method cleans up the machine configuration before unregistering
6145	the machine depends on the @a cleanupMode argument.
6146
6147	<ul>
6148	<li>With "UnregisterOnly", the machine will only be unregistered, but no additional
6149	cleanup will be performed. The call will fail if the machine is in "Saved" state
6150	or has any snapshots or any media attached (see <link to="IMediumAttachment" />).
6151	It is the responsibility of the caller to delete all such configuration in this mode.
6152	In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
6153	which it replaces.</li>
6154	<li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
6155	state or if it has snapshots or media attached. All media attached to the current machine
6156	state or in snapshots will be detached. No medium objects will be returned;
6157	all of the machine's media will remain open.</li>
6158	<li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
6159	except that all the hard disk medium objects which were detached from the machine will
6160	be returned as an array. This allows for quickly passing them to the <link to="#deleteConfig" />
6161	API for closing and deletion.</li>
6162	<li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
6163	that all media will be returned in the array, including removable media like DVDs and
6164	floppies. This might be useful if the user wants to inspect in detail which media were
6165	attached to the machine. Be careful when passing the media array to <link to="#deleteConfig" />
6166	in that case because users will typically want to preserve ISO and RAW image files.</li>
6167	</ul>
6168
6169	A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
6170	resulting IMedium array to <link to="#deleteConfig"/>. This way, the machine is completely
6171	deleted with all its saved states and hard disk images, but images for removable
6172	drives (such as ISO and RAW files) will remain on disk.
6173
6174	This API does not verify whether the media files returned in the array are still
6175	attached to other machines (i.e. shared between several machines). If such a shared
6176	image is passed to <link to="#deleteConfig" /> however, closing the image will fail there
6177	and the image will be silently skipped.
6178
6179	This API may, however, move media from this machine's media registry to other media
6180	registries (see <link to="IMedium" /> for details on media registries). For machines
6181	created with VirtualBox 4.0 or later, if media from this machine's media registry
6182	are also attached to another machine (shared attachments), each such medium will be
6183	moved to another machine's registry. This is because without this machine's media
6184	registry, the other machine cannot find its media any more and would become inaccessible.
6185
6186	This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
6187	before unregistering it. It may also silently call <link to="#saveSettings"/> on other machines
6188	if media are moved to other machines' media registries.
6189
6190	After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
6191	is fired.
6192
6193	The call will fail if the machine is currently locked (see <link to="ISession" />).
6194
6195	<note>
6196	If the given machine is inaccessible (see <link to="#accessible"/>), it
6197	will be unregistered and fully uninitialized right afterwards. As a result,
6198	the returned machine object will be unusable and an attempt to call
6199	<b>any</b> method will return the "Object not ready" error.
6200	</note>
6201
6202	<result name="VBOX_E_INVALID_OBJECT_STATE">
6203	Machine is currently locked for a session.
6204	</result>
6205	</desc>
6206
6207	<param name="cleanupMode" type="CleanupMode" dir="in">
6208	<desc>How to clean up after the machine has been unregistered.</desc>
6209	</param>
6210	<param name="media" type="IMedium" safearray="yes" dir="return">
6211	<desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
6212	</param>
6213	</method>
6214
6215	<method name="deleteConfig">
6216	<desc>
6217	Deletes the files associated with this machine from disk. If medium objects are passed
6218	in with the @a aMedia argument, they are closed and, if closing was successful, their
6219	storage files are deleted as well. For convenience, this array of media files can be
6220	the same as the one returned from a previous <link to="#unregister" /> call.
6221
6222	This method must only be called on machines which are either write-locked (i.e. on instances
6223	returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
6224	registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
6225	<link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
6226
6227	The following files will be deleted by this method:
6228	<ul>
6229	<li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
6230	argument other than "UnregisterOnly", this will delete all saved state files that
6231	the machine had in use; possibly one if the machine was in "Saved" state and one
6232	for each online snapshot that the machine had.</li>
6233	<li>On each medium object passed in the @a aMedia array, this will call
6234	<link to="IMedium::close" />. If that succeeds, this will attempt to delete the
6235	medium's storage on disk. Since the <link to="IMedium::close"/> call will fail if the medium is still
6236	in use, e.g. because it is still attached to a second machine; in that case the
6237	storage will not be deleted.</li>
6238	<li>Finally, the machine's own XML file will be deleted.</li>
6239	</ul>
6240
6241	Since deleting large disk image files can be a time-consuming I/O operation, this
6242	method operates asynchronously and returns an IProgress object to allow the caller
6243	to monitor the progress. There will be one sub-operation for each file that is
6244	being deleted (saved state or medium storage file).
6245
6246	<note>
6247	<link to="#settingsModified"/> will return @c true after this
6248	method successfully returns.
6249	</note>
6250
6251	<result name="VBOX_E_INVALID_VM_STATE">
6252	Machine is registered but not write-locked.
6253	</result>
6254	<result name="VBOX_E_IPRT_ERROR">
6255	Could not delete the settings file.
6256	</result>
6257	</desc>
6258	<param name="media" type="IMedium" safearray="yes" dir="in">
6259	<desc>List of media to be closed and whose storage files will be deleted.</desc>
6260	</param>
6261	<param name="progress" type="IProgress" dir="return">
6262	<desc>Progress object to track the operation completion.</desc>
6263	</param>
6264	</method>
6265
6266	<method name="exportTo">
6267	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
6268	steps required to export VirtualBox machines to OVF.
6269	</desc>
6270
6271	<param name="appliance" type="IAppliance" dir="in">
6272	<desc>Appliance to export this machine to.</desc>
6273	</param>
6274	<param name="location" type="wstring" dir="in">
6275	<desc>The target location.</desc>
6276	</param>
6277	<param name="description" type="IVirtualSystemDescription" dir="return">
6278	<desc>VirtualSystemDescription object which is created for this machine.</desc>
6279	</param>
6280	</method>
6281
6282	<method name="findSnapshot">
6283	<desc>
6284	Returns a snapshot of this machine with the given name or UUID.
6285
6286	Returns a snapshot of this machine with the given UUID.
6287	A @c null argument can be used to obtain the first snapshot
6288	taken on this machine. To traverse the whole tree of snapshots
6289	starting from the root, inspect the root snapshot's
6290	<link to="ISnapshot::children" /> attribute and recurse over those children.
6291
6292	<result name="VBOX_E_OBJECT_NOT_FOUND">
6293	Virtual machine has no snapshots or snapshot not found.
6294	</result>
6295
6296	</desc>
6297	<param name="nameOrId" type="wstring" dir="in">
6298	<desc>What to search for. Name or UUID of the snapshot to find</desc>
6299	</param>
6300	<param name="snapshot" type="ISnapshot" dir="return">
6301	<desc>Snapshot object with the given name.</desc>
6302	</param>
6303	</method>
6304
6305	<method name="createSharedFolder">
6306	<desc>
6307	Creates a new permanent shared folder by associating the given logical
6308	name with the given host path, adds it to the collection of shared
6309	folders and starts sharing it. Refer to the description of
6310	<link to="ISharedFolder"/> to read more about logical names.
6311
6312	<result name="VBOX_E_OBJECT_IN_USE">
6313	Shared folder already exists.
6314	</result>
6315	<result name="VBOX_E_FILE_ERROR">
6316	Shared folder @a hostPath not accessible.
6317	</result>
6318
6319	</desc>
6320	<param name="name" type="wstring" dir="in">
6321	<desc>Unique logical name of the shared folder.</desc>
6322	</param>
6323	<param name="hostPath" type="wstring" dir="in">
6324	<desc>Full path to the shared folder in the host file system.</desc>
6325	</param>
6326	<param name="writable" type="boolean" dir="in">
6327	<desc>Whether the share is writable or readonly.</desc>
6328	</param>
6329	<param name="automount" type="boolean" dir="in">
6330	<desc>Whether the share gets automatically mounted by the guest
6331	or not.</desc>
6332	</param>
6333	</method>
6334
6335	<method name="removeSharedFolder">
6336	<desc>
6337	Removes the permanent shared folder with the given name previously
6338	created by <link to="#createSharedFolder"/> from the collection of
6339	shared folders and stops sharing it.
6340
6341	<result name="VBOX_E_INVALID_VM_STATE">
6342	Virtual machine is not mutable.
6343	</result>
6344	<result name="VBOX_E_OBJECT_NOT_FOUND">
6345	Shared folder @a name does not exist.
6346	</result>
6347
6348	</desc>
6349	<param name="name" type="wstring" dir="in">
6350	<desc>Logical name of the shared folder to remove.</desc>
6351	</param>
6352	</method>
6353
6354	<method name="canShowConsoleWindow">
6355	<desc>
6356	Returns @c true if the VM console process can activate the
6357	console window and bring it to foreground on the desktop of
6358	the host PC.
6359	<note>
6360	This method will fail if a session for this machine is not
6361	currently open.
6362	</note>
6363
6364	<result name="VBOX_E_INVALID_VM_STATE">
6365	Machine session is not open.
6366	</result>
6367
6368	</desc>
6369	<param name="canShow" type="boolean" dir="return">
6370	<desc>
6371	@c true if the console window can be shown and @c false otherwise.
6372	</desc>
6373	</param>
6374	</method>
6375
6376	<method name="showConsoleWindow">
6377	<desc>
6378	Activates the console window and brings it to foreground on
6379	the desktop of the host PC. Many modern window managers on
6380	many platforms implement some sort of focus stealing
6381	prevention logic, so that it may be impossible to activate
6382	a window without the help of the currently active
6383	application. In this case, this method will return a non-zero
6384	identifier that represents the top-level window of the VM
6385	console process. The caller, if it represents a currently
6386	active process, is responsible to use this identifier (in a
6387	platform-dependent manner) to perform actual window
6388	activation.
6389	<note>
6390	This method will fail if a session for this machine is not
6391	currently open.
6392	</note>
6393
6394	<result name="VBOX_E_INVALID_VM_STATE">
6395	Machine session is not open.
6396	</result>
6397
6398	</desc>
6399	<param name="winId" type="long long" dir="return">
6400	<desc>
6401	Platform-dependent identifier of the top-level VM console
6402	window, or zero if this method has performed all actions
6403	necessary to implement the <i>show window</i> semantics for
6404	the given platform and/or VirtualBox front-end.
6405	</desc>
6406	</param>
6407	</method>
6408
6409	<method name="getGuestProperty" const="yes">
6410	<desc>
6411	Reads an entry from the machine's guest property store.
6412
6413	<result name="VBOX_E_INVALID_VM_STATE">
6414	Machine session is not open.
6415	</result>
6416
6417	</desc>
6418	<param name="name" type="wstring" dir="in">
6419	<desc>
6420	The name of the property to read.
6421	</desc>
6422	</param>
6423	<param name="value" type="wstring" dir="out">
6424	<desc>
6425	The value of the property. If the property does not exist then this
6426	will be empty.
6427	</desc>
6428	</param>
6429	<param name="timestamp" type="long long" dir="out">
6430	<desc>
6431	The time at which the property was last modified, as seen by the
6432	server process.
6433	</desc>
6434	</param>
6435	<param name="flags" type="wstring" dir="out">
6436	<desc>
6437	Additional property parameters, passed as a comma-separated list of
6438	"name=value" type entries.
6439	</desc>
6440	</param>
6441	</method>
6442
6443	<method name="getGuestPropertyValue" const="yes">
6444	<desc>
6445	Reads a value from the machine's guest property store.
6446
6447	<result name="VBOX_E_INVALID_VM_STATE">
6448	Machine session is not open.
6449	</result>
6450
6451	</desc>
6452	<param name="property" type="wstring" dir="in">
6453	<desc>
6454	The name of the property to read.
6455	</desc>
6456	</param>
6457	<param name="value" type="wstring" dir="return">
6458	<desc>
6459	The value of the property. If the property does not exist then this
6460	will be empty.
6461	</desc>
6462	</param>
6463	</method>
6464
6465	<method name="getGuestPropertyTimestamp" const="yes">
6466	<desc>
6467	Reads a property timestamp from the machine's guest property store.
6468
6469	<result name="VBOX_E_INVALID_VM_STATE">
6470	Machine session is not open.
6471	</result>
6472
6473	</desc>
6474	<param name="property" type="wstring" dir="in">
6475	<desc>
6476	The name of the property to read.
6477	</desc>
6478	</param>
6479	<param name="value" type="long long" dir="return">
6480	<desc>
6481	The timestamp. If the property does not exist then this will be
6482	empty.
6483	</desc>
6484	</param>
6485	</method>
6486
6487	<method name="setGuestProperty">
6488	<desc>
6489	Sets, changes or deletes an entry in the machine's guest property
6490	store.
6491
6492	<result name="E_ACCESSDENIED">
6493	Property cannot be changed.
6494	</result>
6495	<result name="E_INVALIDARG">
6496	Invalid @a flags.
6497	</result>
6498	<result name="VBOX_E_INVALID_VM_STATE">
6499	Virtual machine is not mutable or session not open.
6500	</result>
6501	<result name="VBOX_E_INVALID_OBJECT_STATE">
6502	Cannot set transient property when machine not running.
6503	</result>
6504
6505	</desc>
6506	<param name="property" type="wstring" dir="in">
6507	<desc>
6508	The name of the property to set, change or delete.
6509	</desc>
6510	</param>
6511	<param name="value" type="wstring" dir="in">
6512	<desc>
6513	The new value of the property to set, change or delete. If the
6514	property does not yet exist and value is non-empty, it will be
6515	created. If the value is @c null or empty, the property will be
6516	deleted if it exists.
6517	</desc>
6518	</param>
6519	<param name="flags" type="wstring" dir="in">
6520	<desc>
6521	Additional property parameters, passed as a comma-separated list of
6522	"name=value" type entries.
6523	</desc>
6524	</param>
6525	</method>
6526
6527	<method name="setGuestPropertyValue">
6528	<desc>
6529	Sets or changes a value in the machine's guest property
6530	store. The flags field will be left unchanged or created empty for a
6531	new property.
6532
6533	<result name="E_ACCESSDENIED">
6534	Property cannot be changed.
6535	</result>
6536	<result name="VBOX_E_INVALID_VM_STATE">
6537	Virtual machine is not mutable or session not open.
6538	</result>
6539	<result name="VBOX_E_INVALID_OBJECT_STATE">
6540	Cannot set transient property when machine not running.
6541	</result>
6542	</desc>
6543
6544	<param name="property" type="wstring" dir="in">
6545	<desc>
6546	The name of the property to set or change.
6547	</desc>
6548	</param>
6549	<param name="value" type="wstring" dir="in">
6550	<desc>
6551	The new value of the property to set or change. If the
6552	property does not yet exist and value is non-empty, it will be
6553	created.
6554	</desc>
6555	</param>
6556	</method>
6557
6558	<method name="deleteGuestProperty" const="yes">
6559	<desc>
6560	Deletes an entry from the machine's guest property store.
6561
6562	<result name="VBOX_E_INVALID_VM_STATE">
6563	Machine session is not open.
6564	</result>
6565
6566	</desc>
6567	<param name="name" type="wstring" dir="in">
6568	<desc>
6569	The name of the property to delete.
6570	</desc>
6571	</param>
6572	</method>
6573
6574	<method name="enumerateGuestProperties" const="yes">
6575	<desc>
6576	Return a list of the guest properties matching a set of patterns along
6577	with their values, time stamps and flags.
6578	</desc>
6579	<param name="patterns" type="wstring" dir="in">
6580	<desc>
6581	The patterns to match the properties against, separated by '\|'
6582	characters. If this is empty or @c null, all properties will match.
6583	</desc>
6584	</param>
6585	<param name="names" type="wstring" dir="out" safearray="yes">
6586	<desc>
6587	The names of the properties returned.
6588	</desc>
6589	</param>
6590	<param name="values" type="wstring" dir="out" safearray="yes">
6591	<desc>
6592	The values of the properties returned. The array entries match the
6593	corresponding entries in the @a name array.
6594	</desc>
6595	</param>
6596	<param name="timestamps" type="long long" dir="out" safearray="yes">
6597	<desc>
6598	The time stamps of the properties returned. The array entries match
6599	the corresponding entries in the @a name array.
6600	</desc>
6601	</param>
6602	<param name="flags" type="wstring" dir="out" safearray="yes">
6603	<desc>
6604	The flags of the properties returned. The array entries match the
6605	corresponding entries in the @a name array.
6606	</desc>
6607	</param>
6608	</method>
6609
6610	<method name="querySavedGuestScreenInfo" const="yes">
6611	<desc>
6612	Returns the guest dimensions from the saved state.
6613	</desc>
6614	<param name="screenId" type="unsigned long" dir="in">
6615	<desc>
6616	Saved guest screen to query info from.
6617	</desc>
6618	</param>
6619	<param name="originX" type="unsigned long" dir="out">
6620	<desc>
6621	The X position of the guest monitor top left corner.
6622	</desc>
6623	</param>
6624	<param name="originY" type="unsigned long" dir="out">
6625	<desc>
6626	The Y position of the guest monitor top left corner.
6627	</desc>
6628	</param>
6629	<param name="width" type="unsigned long" dir="out">
6630	<desc>
6631	Guest width at the time of the saved state was taken.
6632	</desc>
6633	</param>
6634	<param name="height" type="unsigned long" dir="out">
6635	<desc>
6636	Guest height at the time of the saved state was taken.
6637	</desc>
6638	</param>
6639	<param name="enabled" type="boolean" dir="out">
6640	<desc>
6641	Whether the monitor is enabled in the guest.
6642	</desc>
6643	</param>
6644	</method>
6645
6646	<method name="querySavedThumbnailSize">
6647	<desc>
6648	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
6649	</desc>
6650	<param name="screenId" type="unsigned long" dir="in">
6651	<desc>
6652	Saved guest screen to query info from.
6653	</desc>
6654	</param>
6655	<param name="size" type="unsigned long" dir="out">
6656	<desc>
6657	Size of buffer required to store the bitmap.
6658	</desc>
6659	</param>
6660	<param name="width" type="unsigned long" dir="out">
6661	<desc>
6662	Bitmap width.
6663	</desc>
6664	</param>
6665	<param name="height" type="unsigned long" dir="out">
6666	<desc>
6667	Bitmap height.
6668	</desc>
6669	</param>
6670	</method>
6671
6672	<method name="readSavedThumbnailToArray">
6673	<desc>
6674	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
6675	</desc>
6676	<param name="screenId" type="unsigned long" dir="in">
6677	<desc>
6678	Saved guest screen to read from.
6679	</desc>
6680	</param>
6681	<param name="BGR" type="boolean" dir="in">
6682	<desc>
6683	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
6684	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
6685	</desc>
6686	</param>
6687	<param name="width" type="unsigned long" dir="out">
6688	<desc>
6689	Bitmap width.
6690	</desc>
6691	</param>
6692	<param name="height" type="unsigned long" dir="out">
6693	<desc>
6694	Bitmap height.
6695	</desc>
6696	</param>
6697	<param name="data" type="octet" safearray="yes" dir="return">
6698	<desc>
6699	Array with resulting bitmap data.
6700	</desc>
6701	</param>
6702	</method>
6703
6704	<method name="readSavedThumbnailPNGToArray">
6705	<desc>
6706	Thumbnail in PNG format is retrieved to an array of bytes.
6707	</desc>
6708	<param name="screenId" type="unsigned long" dir="in">
6709	<desc>
6710	Saved guest screen to read from.
6711	</desc>
6712	</param>
6713	<param name="width" type="unsigned long" dir="out">
6714	<desc>
6715	Image width.
6716	</desc>
6717	</param>
6718	<param name="height" type="unsigned long" dir="out">
6719	<desc>
6720	Image height.
6721	</desc>
6722	</param>
6723	<param name="data" type="octet" dir="return" safearray="yes">
6724	<desc>
6725	Array with resulting PNG data.
6726	</desc>
6727	</param>
6728	</method>
6729
6730	<method name="querySavedScreenshotPNGSize">
6731	<desc>
6732	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
6733	</desc>
6734	<param name="screenId" type="unsigned long" dir="in">
6735	<desc>
6736	Saved guest screen to query info from.
6737	</desc>
6738	</param>
6739	<param name="size" type="unsigned long" dir="out">
6740	<desc>
6741	Size of buffer required to store the PNG binary data.
6742	</desc>
6743	</param>
6744	<param name="width" type="unsigned long" dir="out">
6745	<desc>
6746	Image width.
6747	</desc>
6748	</param>
6749	<param name="height" type="unsigned long" dir="out">
6750	<desc>
6751	Image height.
6752	</desc>
6753	</param>
6754	</method>
6755
6756	<method name="readSavedScreenshotPNGToArray">
6757	<desc>
6758	Screenshot in PNG format is retrieved to an array of bytes.
6759	</desc>
6760	<param name="screenId" type="unsigned long" dir="in">
6761	<desc>
6762	Saved guest screen to read from.
6763	</desc>
6764	</param>
6765	<param name="width" type="unsigned long" dir="out">
6766	<desc>
6767	Image width.
6768	</desc>
6769	</param>
6770	<param name="height" type="unsigned long" dir="out">
6771	<desc>
6772	Image height.
6773	</desc>
6774	</param>
6775	<param name="data" type="octet" dir="return" safearray="yes">
6776	<desc>
6777	Array with resulting PNG data.
6778	</desc>
6779	</param>
6780	</method>
6781
6782	<method name="hotPlugCPU">
6783	<desc>
6784	Plugs a CPU into the machine.
6785	</desc>
6786	<param name="cpu" type="unsigned long" dir="in">
6787	<desc>
6788	The CPU id to insert.
6789	</desc>
6790	</param>
6791	</method>
6792
6793	<method name="hotUnplugCPU">
6794	<desc>
6795	Removes a CPU from the machine.
6796	</desc>
6797	<param name="cpu" type="unsigned long" dir="in">
6798	<desc>
6799	The CPU id to remove.
6800	</desc>
6801	</param>
6802	</method>
6803
6804	<method name="getCPUStatus">
6805	<desc>
6806	Returns the current status of the given CPU.
6807	</desc>
6808	<param name="cpu" type="unsigned long" dir="in">
6809	<desc>
6810	The CPU id to check for.
6811	</desc>
6812	</param>
6813	<param name="attached" type="boolean" dir="return">
6814	<desc>
6815	Status of the CPU.
6816	</desc>
6817	</param>
6818	</method>
6819
6820	<method name="queryLogFilename">
6821	<desc>
6822	Queries for the VM log file name of an given index. Returns an empty
6823	string if a log file with that index doesn't exists.
6824	</desc>
6825	<param name="idx" type="unsigned long" dir="in">
6826	<desc>
6827	Which log file name to query. 0=current log file.
6828	</desc>
6829	</param>
6830	<param name="filename" type="wstring" dir="return">
6831	<desc>
6832	On return the full path to the log file or an empty string on error.
6833	</desc>
6834	</param>
6835	</method>
6836
6837	<method name="readLog">
6838	<desc>
6839	Reads the VM log file. The chunk size is limited, so even if you
6840	ask for a big piece there might be less data returned.
6841	</desc>
6842	<param name="idx" type="unsigned long" dir="in">
6843	<desc>
6844	Which log file to read. 0=current log file.
6845	</desc>
6846	</param>
6847	<param name="offset" type="long long" dir="in">
6848	<desc>
6849	Offset in the log file.
6850	</desc>
6851	</param>
6852	<param name="size" type="long long" dir="in">
6853	<desc>
6854	Chunk size to read in the log file.
6855	</desc>
6856	</param>
6857	<param name="data" type="octet" dir="return" safearray="yes">
6858	<desc>
6859	Data read from the log file. A data size of 0 means end of file
6860	if the requested chunk size was not 0. This is the unprocessed
6861	file data, i.e. the line ending style depends on the platform of
6862	the system the server is running on.
6863	</desc>
6864	</param>
6865	</method>
6866
6867	<method name="cloneTo">
6868	<desc>
6869	Creates a clone of this machine, either as a full clone (which means
6870	creating independent copies of the hard disk media, save states and so
6871	on), or as a linked clone (which uses its own differencing media,
6872	sharing the parent media with the source machine).
6873
6874	The target machine object must have been created previously with <link
6875	to="IVirtualBox::createMachine"/>, and all the settings will be
6876	transferred except the VM name and the hardware UUID. You can set the
6877	VM name and the new hardware UUID when creating the target machine. The
6878	network MAC addresses are newly created for all newtwork adapters. You
6879	can change that behaviour with the options parameter. The operation is
6880	performed asynchronously, so the machine object will be not be usable
6881	until the @a progress object signals completion.
6882
6883	<result name="E_INVALIDARG">
6884	@a target is @c null.
6885	</result>
6886	</desc>
6887
6888	<param name="target" type="IMachine" dir="in">
6889	<desc>Target machine object.</desc>
6890	</param>
6891	<param name="mode" type="CloneMode" dir="in">
6892	<desc>Which states should be cloned.</desc>
6893	</param>
6894	<param name="options" type="CloneOptions" dir="in" safearray="yes">
6895	<desc>Options for the cloning operation.</desc>
6896	</param>
6897	<param name="progress" type="IProgress" dir="return">
6898	<desc>Progress object to track the operation completion.</desc>
6899	</param>
6900	</method>
6901
6902	</interface>
6903
6904	<!--
6905	// IConsole
6906	/////////////////////////////////////////////////////////////////////////
6907	-->
6908
6909	<interface
6910	name="IVRDEServerInfo" extends="$unknown"
6911	uuid="714434a1-58c3-4aab-9049-7652c5df113b"
6912	wsmap="struct"
6913	>
6914	<desc>
6915	Contains information about the remote desktop (VRDE) server capabilities and status.
6916	This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
6917	</desc>
6918
6919	<attribute name="active" type="boolean" readonly="yes">
6920	<desc>
6921	Whether the remote desktop connection is active.
6922	</desc>
6923	</attribute>
6924
6925	<attribute name="port" type="long" readonly="yes">
6926	<desc>
6927	VRDE server port number. If this property is equal to <tt>0</tt>, then
6928	the VRDE server failed to start, usually because there are no free IP
6929	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
6930	server has not yet been started.
6931	</desc>
6932	</attribute>
6933
6934	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6935	<desc>
6936	How many times a client connected.
6937	</desc>
6938	</attribute>
6939
6940	<attribute name="beginTime" type="long long" readonly="yes">
6941	<desc>
6942	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6943	</desc>
6944	</attribute>
6945
6946	<attribute name="endTime" type="long long" readonly="yes">
6947	<desc>
6948	When the last connection was terminated or the current time, if
6949	connection is still active, in milliseconds since 1970-01-01 UTC.
6950	</desc>
6951	</attribute>
6952
6953	<attribute name="bytesSent" type="long long" readonly="yes">
6954	<desc>
6955	How many bytes were sent in last or current, if still active, connection.
6956	</desc>
6957	</attribute>
6958
6959	<attribute name="bytesSentTotal" type="long long" readonly="yes">
6960	<desc>
6961	How many bytes were sent in all connections.
6962	</desc>
6963	</attribute>
6964
6965	<attribute name="bytesReceived" type="long long" readonly="yes">
6966	<desc>
6967	How many bytes were received in last or current, if still active, connection.
6968	</desc>
6969	</attribute>
6970
6971	<attribute name="bytesReceivedTotal" type="long long" readonly="yes">
6972	<desc>
6973	How many bytes were received in all connections.
6974	</desc>
6975	</attribute>
6976
6977	<attribute name="user" type="wstring" readonly="yes">
6978	<desc>
6979	Login user name supplied by the client.
6980	</desc>
6981	</attribute>
6982
6983	<attribute name="domain" type="wstring" readonly="yes">
6984	<desc>
6985	Login domain name supplied by the client.
6986	</desc>
6987	</attribute>
6988
6989	<attribute name="clientName" type="wstring" readonly="yes">
6990	<desc>
6991	The client name supplied by the client.
6992	</desc>
6993	</attribute>
6994
6995	<attribute name="clientIP" type="wstring" readonly="yes">
6996	<desc>
6997	The IP address of the client.
6998	</desc>
6999	</attribute>
7000
7001	<attribute name="clientVersion" type="unsigned long" readonly="yes">
7002	<desc>
7003	The client software version number.
7004	</desc>
7005	</attribute>
7006
7007	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
7008	<desc>
7009	Public key exchange method used when connection was established.
7010	Values: 0 - RDP4 public key exchange scheme.
7011	1 - X509 certificates were sent to client.
7012	</desc>
7013	</attribute>
7014
7015	</interface>
7016
7017	<interface
7018	name="IConsole" extends="$unknown"
7019	uuid="db7ab4ca-2a3f-4183-9243-c1208da92392"
7020	wsmap="managed"
7021	>
7022	<desc>
7023	The IConsole interface represents an interface to control virtual
7024	machine execution.
7025
7026	A console object gets created when a machine has been locked for a
7027	particular session (client process) using <link to="IMachine::lockMachine" />
7028	or <link to="IMachine::launchVMProcess"/>. The console object can
7029	then be found in the session's <link to="ISession::console" /> attribute.
7030
7031	Methods of the IConsole interface allow the caller to query the current
7032	virtual machine execution state, pause the machine or power it down, save
7033	the machine state or take a snapshot, attach and detach removable media
7034	and so on.
7035
7036	<see><link to="ISession"/></see>
7037	</desc>
7038
7039	<attribute name="machine" type="IMachine" readonly="yes">
7040	<desc>
7041	Machine object for this console session.
7042	<note>
7043	This is a convenience property, it has the same value as
7044	<link to="ISession::machine"/> of the corresponding session
7045	object.
7046	</note>
7047	</desc>
7048	</attribute>
7049
7050	<attribute name="state" type="MachineState" readonly="yes">
7051	<desc>
7052	Current execution state of the machine.
7053	<note>
7054	This property always returns the same value as the corresponding
7055	property of the IMachine object for this console session.
7056	For the process that owns (executes) the VM, this is the
7057	preferable way of querying the VM state, because no IPC
7058	calls are made.
7059	</note>
7060	</desc>
7061	</attribute>
7062
7063	<attribute name="guest" type="IGuest" readonly="yes">
7064	<desc>Guest object.</desc>
7065	</attribute>
7066
7067	<attribute name="keyboard" type="IKeyboard" readonly="yes">
7068	<desc>
7069	Virtual keyboard object.
7070	<note>
7071	If the machine is not running, any attempt to use
7072	the returned object will result in an error.
7073	</note>
7074	</desc>
7075	</attribute>
7076
7077	<attribute name="mouse" type="IMouse" readonly="yes">
7078	<desc>
7079	Virtual mouse 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="display" type="IDisplay" readonly="yes">
7088	<desc>Virtual display object.
7089	<note>
7090	If the machine is not running, any attempt to use
7091	the returned object will result in an error.
7092	</note>
7093	</desc>
7094	</attribute>
7095
7096	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
7097	<desc>Debugging interface.</desc>
7098	</attribute>
7099
7100	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
7101	<desc>
7102	Collection of USB devices currently attached to the virtual
7103	USB controller.
7104	<note>
7105	The collection is empty if the machine is not running.
7106	</note>
7107	</desc>
7108	</attribute>
7109
7110	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7111	<desc>
7112	List of USB devices currently attached to the remote VRDE client.
7113	Once a new device is physically attached to the remote host computer,
7114	it appears in this list and remains there until detached.
7115	</desc>
7116	</attribute>
7117
7118	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
7119	<desc>
7120	Collection of shared folders for the current session. These folders
7121	are called transient shared folders because they are available to the
7122	guest OS running inside the associated virtual machine only for the
7123	duration of the session (as opposed to
7124	<link to="IMachine::sharedFolders"/> which represent permanent shared
7125	folders). When the session is closed (e.g. the machine is powered down),
7126	these folders are automatically discarded.
7127
7128	New shared folders are added to the collection using
7129	<link to="#createSharedFolder"/>. Existing shared folders can be
7130	removed using <link to="#removeSharedFolder"/>.
7131	</desc>
7132	</attribute>
7133
7134	<attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
7135	<desc>
7136	Interface that provides information on Remote Desktop Extension (VRDE) connection.
7137	</desc>
7138	</attribute>
7139
7140	<attribute name="eventSource" type="IEventSource" readonly="yes">
7141	<desc>
7142	Event source for console events.
7143	</desc>
7144	</attribute>
7145
7146	<attribute name="attachedPCIDevices" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
7147	<desc>Array of PCI devices attached to this machine.</desc>
7148	</attribute>
7149
7150	<attribute name="useHostClipboard" type="boolean">
7151	<desc>
7152	Whether the guest clipboard should be connected to the host one or
7153	whether it should only be allowed access to the VRDE clipboard. This
7154	setting may not affect existing guest clipboard connections which
7155	are already connected to the host clipboard.
7156	</desc>
7157	</attribute>
7158
7159	<method name="powerUp">
7160	<desc>
7161	Starts the virtual machine execution using the current machine
7162	state (that is, its current execution state, current settings and
7163	current storage devices).
7164
7165	<note>
7166	This method is only useful for front-ends that want to actually
7167	execute virtual machines in their own process (like the VirtualBox
7168	or VBoxSDL front-ends). Unless you are intending to write such a
7169	front-end, do not call this method. If you simply want to
7170	start virtual machine execution using one of the existing front-ends
7171	(for example the VirtualBox GUI or headless server), use
7172	<link to="IMachine::launchVMProcess"/> instead; these
7173	front-ends will power up the machine automatically for you.
7174	</note>
7175
7176	If the machine is powered off or aborted, the execution will
7177	start from the beginning (as if the real hardware were just
7178	powered on).
7179
7180	If the machine is in the <link to="MachineState_Saved"/> state,
7181	it will continue its execution the point where the state has
7182	been saved.
7183
7184	If the machine <link to="IMachine::teleporterEnabled"/> property is
7185	enabled on the machine being powered up, the machine will wait for an
7186	incoming teleportation in the <link to="MachineState_TeleportingIn"/>
7187	state. The returned progress object will have at least three
7188	operations where the last three are defined as: (1) powering up and
7189	starting TCP server, (2) waiting for incoming teleportations, and
7190	(3) perform teleportation. These operations will be reflected as the
7191	last three operations of the progress objected returned by
7192	<link to="IMachine::launchVMProcess"/> as well.
7193
7194	<see><link to="#saveState"/></see>
7195
7196	<result name="VBOX_E_INVALID_VM_STATE">
7197	Virtual machine already running.
7198	</result>
7199	<result name="VBOX_E_HOST_ERROR">
7200	Host interface does not exist or name not set.
7201	</result>
7202	<result name="VBOX_E_FILE_ERROR">
7203	Invalid saved state file.
7204	</result>
7205	</desc>
7206	<param name="progress" type="IProgress" dir="return">
7207	<desc>Progress object to track the operation completion.</desc>
7208	</param>
7209	</method>
7210
7211	<method name="powerUpPaused">
7212	<desc>
7213	Identical to powerUp except that the VM will enter the
7214	<link to="MachineState_Paused"/> state, instead of
7215	<link to="MachineState_Running"/>.
7216
7217	<see><link to="#powerUp"/></see>
7218	<result name="VBOX_E_INVALID_VM_STATE">
7219	Virtual machine already running.
7220	</result>
7221	<result name="VBOX_E_HOST_ERROR">
7222	Host interface does not exist or name not set.
7223	</result>
7224	<result name="VBOX_E_FILE_ERROR">
7225	Invalid saved state file.
7226	</result>
7227	</desc>
7228	<param name="progress" type="IProgress" dir="return">
7229	<desc>Progress object to track the operation completion.</desc>
7230	</param>
7231	</method>
7232
7233	<method name="powerDown">
7234	<desc>
7235	Initiates the power down procedure to stop the virtual machine
7236	execution.
7237
7238	The completion of the power down procedure is tracked using the returned
7239	IProgress object. After the operation is complete, the machine will go
7240	to the PoweredOff state.
7241	<result name="VBOX_E_INVALID_VM_STATE">
7242	Virtual machine must be Running, Paused or Stuck to be powered down.
7243	</result>
7244	</desc>
7245	<param name="progress" type="IProgress" dir="return">
7246	<desc>Progress object to track the operation completion.</desc>
7247	</param>
7248	</method>
7249
7250	<method name="reset">
7251	<desc>Resets the virtual machine.
7252	<result name="VBOX_E_INVALID_VM_STATE">
7253	Virtual machine not in Running state.
7254	</result>
7255	<result name="VBOX_E_VM_ERROR">
7256	Virtual machine error in reset operation.
7257	</result>
7258	</desc>
7259	</method>
7260
7261	<method name="pause">
7262	<desc>Pauses the virtual machine execution.
7263	<result name="VBOX_E_INVALID_VM_STATE">
7264	Virtual machine not in Running state.
7265	</result>
7266	<result name="VBOX_E_VM_ERROR">
7267	Virtual machine error in suspend operation.
7268	</result>
7269	</desc>
7270	</method>
7271
7272	<method name="resume">
7273	<desc>Resumes the virtual machine execution.
7274	<result name="VBOX_E_INVALID_VM_STATE">
7275	Virtual machine not in Paused state.
7276	</result>
7277	<result name="VBOX_E_VM_ERROR">
7278	Virtual machine error in resume operation.
7279	</result>
7280	</desc>
7281	</method>
7282
7283	<method name="powerButton">
7284	<desc>Sends the ACPI power button event to the guest.
7285	<result name="VBOX_E_INVALID_VM_STATE">
7286	Virtual machine not in Running state.
7287	</result>
7288	<result name="VBOX_E_PDM_ERROR">
7289	Controlled power off failed.
7290	</result>
7291	</desc>
7292	</method>
7293
7294	<method name="sleepButton">
7295	<desc>Sends the ACPI sleep button event to the guest.
7296	<result name="VBOX_E_INVALID_VM_STATE">
7297	Virtual machine not in Running state.
7298	</result>
7299	<result name="VBOX_E_PDM_ERROR">
7300	Sending sleep button event failed.
7301	</result>
7302	</desc>
7303	</method>
7304
7305	<method name="getPowerButtonHandled">
7306	<desc>Checks if the last power button event was handled by guest.
7307	<result name="VBOX_E_PDM_ERROR">
7308	Checking if the event was handled by the guest OS failed.
7309	</result>
7310	</desc>
7311	<param name="handled" type="boolean" dir="return"/>
7312	</method>
7313
7314	<method name="getGuestEnteredACPIMode">
7315	<desc>Checks if the guest entered the ACPI mode G0 (working) or
7316	G1 (sleeping). If this method returns @c false, the guest will
7317	most likely not respond to external ACPI events.
7318	<result name="VBOX_E_INVALID_VM_STATE">
7319	Virtual machine not in Running state.
7320	</result>
7321	</desc>
7322	<param name="entered" type="boolean" dir="return"/>
7323	</method>
7324
7325	<method name="saveState">
7326	<desc>
7327	Saves the current execution state of a running virtual machine
7328	and stops its execution.
7329
7330	After this operation completes, the machine will go to the
7331	Saved state. Next time it is powered up, this state will
7332	be restored and the machine will continue its execution from
7333	the place where it was saved.
7334
7335	This operation differs from taking a snapshot to the effect
7336	that it doesn't create new differencing media. Also, once
7337	the machine is powered up from the state saved using this method,
7338	the saved state is deleted, so it will be impossible to return
7339	to this state later.
7340
7341	<note>
7342	On success, this method implicitly calls
7343	<link to="IMachine::saveSettings"/> to save all current machine
7344	settings (including runtime changes to the DVD medium, etc.).
7345	Together with the impossibility to change any VM settings when it is
7346	in the Saved state, this guarantees adequate hardware
7347	configuration of the machine when it is restored from the saved
7348	state file.
7349	</note>
7350
7351	<note>
7352	The machine must be in the Running or Paused state, otherwise
7353	the operation will fail.
7354	</note>
7355	<result name="VBOX_E_INVALID_VM_STATE">
7356	Virtual machine state neither Running nor Paused.
7357	</result>
7358	<result name="VBOX_E_FILE_ERROR">
7359	Failed to create directory for saved state file.
7360	</result>
7361
7362	<see><link to="#takeSnapshot"/></see>
7363	</desc>
7364	<param name="progress" type="IProgress" dir="return">
7365	<desc>Progress object to track the operation completion.</desc>
7366	</param>
7367	</method>
7368
7369	<method name="adoptSavedState">
7370	<desc>
7371	Associates the given saved state file to the virtual machine.
7372
7373	On success, the machine will go to the Saved state. Next time it is
7374	powered up, it will be restored from the adopted saved state and
7375	continue execution from the place where the saved state file was
7376	created.
7377
7378	The specified saved state file path may be absolute or relative to the
7379	folder the VM normally saves the state to (usually,
7380	<link to="IMachine::snapshotFolder"/>).
7381
7382	<note>
7383	It's a caller's responsibility to make sure the given saved state
7384	file is compatible with the settings of this virtual machine that
7385	represent its virtual hardware (memory size, storage disk configuration
7386	etc.). If there is a mismatch, the behavior of the virtual machine
7387	is undefined.
7388	</note>
7389	<result name="VBOX_E_INVALID_VM_STATE">
7390	Virtual machine state neither PoweredOff nor Aborted.
7391	</result>
7392	</desc>
7393	<param name="savedStateFile" type="wstring" dir="in">
7394	<desc>Path to the saved state file to adopt.</desc>
7395	</param>
7396	</method>
7397
7398	<method name="discardSavedState">
7399	<desc>
7400	Forcibly resets the machine to "Powered Off" state if it is
7401	currently in the "Saved" state (previously created by <link to="#saveState"/>).
7402	Next time the machine is powered up, a clean boot will occur.
7403	<note>
7404	This operation is equivalent to resetting or powering off
7405	the machine without doing a proper shutdown of the guest
7406	operating system; as with resetting a running phyiscal
7407	computer, it can can lead to data loss.
7408	</note>
7409	If @a fRemoveFile is @c true, the file in the machine directory
7410	into which the machine state was saved is also deleted. If
7411	this is @c false, then the state can be recovered and later
7412	re-inserted into a machine using <link to="#adoptSavedState" />.
7413	The location of the file can be found in the
7414	<link to="IMachine::stateFilePath" /> attribute.
7415	<result name="VBOX_E_INVALID_VM_STATE">
7416	Virtual machine not in state Saved.
7417	</result>
7418	</desc>
7419	<param name="fRemoveFile" type="boolean" dir="in" >
7420	<desc>Whether to also remove the saved state file.</desc>
7421	</param>
7422	</method>
7423
7424	<method name="getDeviceActivity">
7425	<desc>
7426	Gets the current activity type of a given device or device group.
7427	<result name="E_INVALIDARG">
7428	Invalid device type.
7429	</result>
7430	</desc>
7431	<param name="type" type="DeviceType" dir="in"/>
7432	<param name="activity" type="DeviceActivity" dir="return"/>
7433	</method>
7434
7435	<method name="attachUSBDevice">
7436	<desc>
7437	Attaches a host USB device with the given UUID to the
7438	USB controller of the virtual machine.
7439
7440	The device needs to be in one of the following states:
7441	<link to="USBDeviceState_Busy"/>,
7442	<link to="USBDeviceState_Available"/> or
7443	<link to="USBDeviceState_Held"/>,
7444	otherwise an error is immediately returned.
7445
7446	When the device state is
7447	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7448	be returned if the host computer refuses to release it for some reason.
7449
7450	<see><link to="IUSBController::deviceFilters"/>,
7451	<link to="USBDeviceState"/></see>
7452	<result name="VBOX_E_INVALID_VM_STATE">
7453	Virtual machine state neither Running nor Paused.
7454	</result>
7455	<result name="VBOX_E_PDM_ERROR">
7456	Virtual machine does not have a USB controller.
7457	</result>
7458	</desc>
7459	<param name="id" type="uuid" mod="string" dir="in">
7460	<desc>UUID of the host USB device to attach.</desc>
7461	</param>
7462	</method>
7463
7464	<method name="detachUSBDevice">
7465	<desc>
7466	Detaches an USB device with the given UUID from the USB controller
7467	of the virtual machine.
7468
7469	After this method succeeds, the VirtualBox server re-initiates
7470	all USB filters as if the device were just physically attached
7471	to the host, but filters of this machine are ignored to avoid
7472	a possible automatic re-attachment.
7473
7474	<see><link to="IUSBController::deviceFilters"/>,
7475	<link to="USBDeviceState"/></see>
7476
7477	<result name="VBOX_E_PDM_ERROR">
7478	Virtual machine does not have a USB controller.
7479	</result>
7480	<result name="E_INVALIDARG">
7481	USB device not attached to this virtual machine.
7482	</result>
7483	</desc>
7484	<param name="id" type="uuid" mod="string" dir="in">
7485	<desc>UUID of the USB device to detach.</desc>
7486	</param>
7487	<param name="device" type="IUSBDevice" dir="return">
7488	<desc>Detached USB device.</desc>
7489	</param>
7490	</method>
7491
7492	<method name="findUSBDeviceByAddress">
7493	<desc>
7494	Searches for a USB device with the given host address.
7495
7496	<result name="VBOX_E_OBJECT_NOT_FOUND">
7497	Given @c name does not correspond to any USB device.
7498	</result>
7499
7500	<see><link to="IUSBDevice::address"/></see>
7501	</desc>
7502	<param name="name" type="wstring" dir="in">
7503	<desc>
7504	Address of the USB device (as assigned by the host) to
7505	search for.
7506	</desc>
7507	</param>
7508	<param name="device" type="IUSBDevice" dir="return">
7509	<desc>Found USB device object.</desc>
7510	</param>
7511	</method>
7512
7513	<method name="findUSBDeviceById">
7514	<desc>
7515	Searches for a USB device with the given UUID.
7516
7517	<result name="VBOX_E_OBJECT_NOT_FOUND">
7518	Given @c id does not correspond to any USB device.
7519	</result>
7520
7521	<see><link to="IUSBDevice::id"/></see>
7522	</desc>
7523	<param name="id" type="uuid" mod="string" dir="in">
7524	<desc>UUID of the USB device to search for.</desc>
7525	</param>
7526	<param name="device" type="IUSBDevice" dir="return">
7527	<desc>Found USB device object.</desc>
7528	</param>
7529	</method>
7530
7531	<method name="createSharedFolder">
7532	<desc>
7533	Creates a transient new shared folder by associating the given logical
7534	name with the given host path, adds it to the collection of shared
7535	folders and starts sharing it. Refer to the description of
7536	<link to="ISharedFolder"/> to read more about logical names.
7537
7538	<result name="VBOX_E_INVALID_VM_STATE">
7539	Virtual machine in Saved state or currently changing state.
7540	</result>
7541	<result name="VBOX_E_FILE_ERROR">
7542	Shared folder already exists or not accessible.
7543	</result>
7544	</desc>
7545	<param name="name" type="wstring" dir="in">
7546	<desc>Unique logical name of the shared folder.</desc>
7547	</param>
7548	<param name="hostPath" type="wstring" dir="in">
7549	<desc>Full path to the shared folder in the host file system.</desc>
7550	</param>
7551	<param name="writable" type="boolean" dir="in">
7552	<desc>Whether the share is writable or readonly</desc>
7553	</param>
7554	<param name="automount" type="boolean" dir="in">
7555	<desc>Whether the share gets automatically mounted by the guest
7556	or not.</desc>
7557	</param>
7558	</method>
7559
7560	<method name="removeSharedFolder">
7561	<desc>
7562	Removes a transient shared folder with the given name previously
7563	created by <link to="#createSharedFolder"/> from the collection of
7564	shared folders and stops sharing it.
7565	<result name="VBOX_E_INVALID_VM_STATE">
7566	Virtual machine in Saved state or currently changing state.
7567	</result>
7568	<result name="VBOX_E_FILE_ERROR">
7569	Shared folder does not exists.
7570	</result>
7571	</desc>
7572	<param name="name" type="wstring" dir="in">
7573	<desc>Logical name of the shared folder to remove.</desc>
7574	</param>
7575	</method>
7576
7577	<method name="takeSnapshot">
7578	<desc>
7579	Saves the current execution state
7580	and all settings of the machine and creates differencing images
7581	for all normal (non-independent) media.
7582	See <link to="ISnapshot" /> for an introduction to snapshots.
7583
7584	This method can be called for a PoweredOff, Saved (see
7585	<link to="#saveState"/>), Running or
7586	Paused virtual machine. When the machine is PoweredOff, an
7587	offline snapshot is created. When the machine is Running a live
7588	snapshot is created, and an online snapshot is created when Paused.
7589
7590	The taken snapshot is always based on the
7591	<link to="IMachine::currentSnapshot">current snapshot</link>
7592	of the associated virtual machine and becomes a new current snapshot.
7593
7594	<note>
7595	This method implicitly calls <link to="IMachine::saveSettings"/> to
7596	save all current machine settings before taking an offline snapshot.
7597	</note>
7598
7599	<result name="VBOX_E_INVALID_VM_STATE">
7600	Virtual machine currently changing state.
7601	</result>
7602	</desc>
7603	<param name="name" type="wstring" dir="in">
7604	<desc>Short name for the snapshot.</desc>
7605	</param>
7606	<param name="description" type="wstring" dir="in">
7607	<desc>Optional description of the snapshot.</desc>
7608	</param>
7609	<param name="progress" type="IProgress" dir="return">
7610	<desc>Progress object to track the operation completion.</desc>
7611	</param>
7612	</method>
7613
7614	<method name="deleteSnapshot">
7615	<desc>
7616	Starts deleting the specified snapshot asynchronously.
7617	See <link to="ISnapshot" /> for an introduction to snapshots.
7618
7619	The execution state and settings of the associated machine stored in
7620	the snapshot will be deleted. The contents of all differencing media of
7621	this snapshot will be merged with the contents of their dependent child
7622	media to keep the medium chain valid (in other words, all changes
7623	represented by media being deleted will be propagated to their child
7624	medium). After that, this snapshot's differencing medium will be
7625	deleted. The parent of this snapshot will become a new parent for all
7626	its child snapshots.
7627
7628	If the deleted snapshot is the current one, its parent snapshot will
7629	become a new current snapshot. The current machine state is not directly
7630	affected in this case, except that currently attached differencing
7631	media based on media of the deleted snapshot will be also merged as
7632	described above.
7633
7634	If the deleted snapshot is the first or current snapshot, then the
7635	respective IMachine attributes will be adjusted. Deleting the current
7636	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7637	to make all current machine settings permanent.
7638
7639	Deleting a snapshot has the following preconditions:
7640
7641	<ul>
7642	<li>Child media of all normal media of the deleted snapshot
7643	must be accessible (see <link to="IMedium::state"/>) for this
7644	operation to succeed. If only one running VM refers to all images
7645	which participates in merging the operation can be performed while
7646	the VM is running. Otherwise all virtual machines whose media are
7647	directly or indirectly based on the media of deleted snapshot must
7648	be powered off. In any case, online snapshot deleting usually is
7649	slower than the same operation without any running VM.</li>
7650
7651	<li>You cannot delete the snapshot if a medium attached to it has
7652	more than one child medium (differencing images) because otherwise
7653	merging would be impossible. This might be the case if there is
7654	more than one child snapshot or differencing images were created
7655	for other reason (e.g. implicitly because of multiple machine
7656	attachments).</li>
7657	</ul>
7658
7659	The virtual machine's <link to="IMachine::state">state</link> is
7660	changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
7661	"DeletingSnapshotPaused" while this operation is in progress.
7662
7663	<note>
7664	Merging medium contents can be very time and disk space
7665	consuming, if these media are big in size and have many
7666	children. However, if the snapshot being deleted is the last
7667	(head) snapshot on the branch, the operation will be rather
7668	quick.
7669	</note>
7670	<result name="VBOX_E_INVALID_VM_STATE">
7671	The running virtual machine prevents deleting this snapshot. This
7672	happens only in very specific situations, usually snapshots can be
7673	deleted without trouble while a VM is running. The error message
7674	text explains the reason for the failure.
7675	</result>
7676	</desc>
7677	<param name="id" type="uuid" mod="string" dir="in">
7678	<desc>UUID of the snapshot to delete.</desc>
7679	</param>
7680	<param name="progress" type="IProgress" dir="return">
7681	<desc>Progress object to track the operation completion.</desc>
7682	</param>
7683	</method>
7684
7685	<method name="deleteSnapshotAndAllChildren">
7686	<desc>
7687	Starts deleting the specified snapshot and all its children
7688	asynchronously. See <link to="ISnapshot" /> for an introduction to
7689	snapshots. The conditions and many details are the same as with
7690	<link to="#deleteSnapshot"/>.
7691
7692	This operation is very fast if the snapshot subtree does not include
7693	the current state. It is still significantly faster than deleting the
7694	snapshots one by one if the current state is in the subtree and there
7695	are more than one snapshots from current state to the snapshot which
7696	marks the subtree, since it eliminates the incremental image merging.
7697
7698	<note>This API method is right now not implemented!</note>
7699
7700	<result name="VBOX_E_INVALID_VM_STATE">
7701	The running virtual machine prevents deleting this snapshot. This
7702	happens only in very specific situations, usually snapshots can be
7703	deleted without trouble while a VM is running. The error message
7704	text explains the reason for the failure.
7705	</result>
7706	<result name="E_NOTIMPL">
7707	The method is not implemented yet.
7708	</result>
7709	</desc>
7710	<param name="id" type="uuid" mod="string" dir="in">
7711	<desc>UUID of the snapshot to delete, including all its children.</desc>
7712	</param>
7713	<param name="progress" type="IProgress" dir="return">
7714	<desc>Progress object to track the operation completion.</desc>
7715	</param>
7716	</method>
7717
7718	<method name="deleteSnapshotRange">
7719	<desc>
7720	Starts deleting the specified snapshot range. This is limited to
7721	linear snapshot lists, which means there may not be any other child
7722	snapshots other than the direct sequence between the start and end
7723	snapshot. If the start and end snapshot point to the same snapshot this
7724	method is completely equivalent to <link to="#deleteSnapshot"/>. See
7725	<link to="ISnapshot" /> for an introduction to snapshots. The
7726	conditions and many details are the same as with
7727	<link to="#deleteSnapshot"/>.
7728
7729	This operation is generally faster than deleting snapshots one by one
7730	and often also needs less extra disk space before freeing up disk space
7731	by deleting the removed disk images corresponding to the snapshot.
7732
7733	<note>This API method is right now not implemented!</note>
7734
7735	<result name="VBOX_E_INVALID_VM_STATE">
7736	The running virtual machine prevents deleting this snapshot. This
7737	happens only in very specific situations, usually snapshots can be
7738	deleted without trouble while a VM is running. The error message
7739	text explains the reason for the failure.
7740	</result>
7741	<result name="E_NOTIMPL">
7742	The method is not implemented yet.
7743	</result>
7744	</desc>
7745	<param name="startId" type="uuid" mod="string" dir="in">
7746	<desc>UUID of the first snapshot to delete.</desc>
7747	</param>
7748	<param name="endId" type="uuid" mod="string" dir="in">
7749	<desc>UUID of the last snapshot to delete.</desc>
7750	</param>
7751	<param name="progress" type="IProgress" dir="return">
7752	<desc>Progress object to track the operation completion.</desc>
7753	</param>
7754	</method>
7755
7756	<method name="restoreSnapshot">
7757	<desc>
7758	Starts resetting the machine's current state to the state contained
7759	in the given snapshot, asynchronously. All current settings of the
7760	machine will be reset and changes stored in differencing media
7761	will be lost.
7762	See <link to="ISnapshot" /> for an introduction to snapshots.
7763
7764	After this operation is successfully completed, new empty differencing
7765	media are created for all normal media of the machine.
7766
7767	If the given snapshot is an online snapshot, the machine will go to
7768	the <link to="MachineState_Saved"> saved state</link>, so that the
7769	next time it is powered on, the execution state will be restored
7770	from the state of the snapshot.
7771
7772	<note>
7773	The machine must not be running, otherwise the operation will fail.
7774	</note>
7775
7776	<note>
7777	If the machine state is <link to="MachineState_Saved">Saved</link>
7778	prior to this operation, the saved state file will be implicitly
7779	deleted (as if <link to="IConsole::discardSavedState"/> were
7780	called).
7781	</note>
7782
7783	<result name="VBOX_E_INVALID_VM_STATE">
7784	Virtual machine is running.
7785	</result>
7786	</desc>
7787	<param name="snapshot" type="ISnapshot" dir="in">
7788	<desc>The snapshot to restore the VM state from.</desc>
7789	</param>
7790	<param name="progress" type="IProgress" dir="return">
7791	<desc>Progress object to track the operation completion.</desc>
7792	</param>
7793	</method>
7794
7795	<method name="teleport">
7796	<desc>
7797	Teleport the VM to a different host machine or process.
7798
7799	TODO explain the details.
7800
7801	<result name="VBOX_E_INVALID_VM_STATE">
7802	Virtual machine not running or paused.
7803	</result>
7804	</desc>
7805	<param name="hostname" type="wstring" dir="in">
7806	<desc>The name or IP of the host to teleport to.</desc>
7807	</param>
7808	<param name="tcpport" type="unsigned long" dir="in">
7809	<desc>The TCP port to connect to (1..65535).</desc>
7810	</param>
7811	<param name="password" type="wstring" dir="in">
7812	<desc>The password.</desc>
7813	</param>
7814	<param name="maxDowntime" type="unsigned long" dir="in">
7815	<desc>
7816	The maximum allowed downtime given as milliseconds. 0 is not a valid
7817	value. Recommended value: 250 ms.
7818
7819	The higher the value is, the greater the chance for a successful
7820	teleportation. A small value may easily result in the teleportation
7821	process taking hours and eventually fail.
7822
7823	<note>
7824	The current implementation treats this a guideline, not as an
7825	absolute rule.
7826	</note>
7827	</desc>
7828	</param>
7829	<param name="progress" type="IProgress" dir="return">
7830	<desc>Progress object to track the operation completion.</desc>
7831	</param>
7832	</method>
7833
7834	</interface>
7835
7836	<!--
7837	// IHost
7838	/////////////////////////////////////////////////////////////////////////
7839	-->
7840
7841	<enum
7842	name="HostNetworkInterfaceMediumType"
7843	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7844	>
7845	<desc>
7846	Type of encapsulation. Ethernet encapsulation includes both wired and
7847	wireless Ethernet connections.
7848	<see><link to="IHostNetworkInterface"/></see>
7849	</desc>
7850
7851	<const name="Unknown" value="0">
7852	<desc>
7853	The type of interface cannot be determined.
7854	</desc>
7855	</const>
7856	<const name="Ethernet" value="1">
7857	<desc>
7858	Ethernet frame encapsulation.
7859	</desc>
7860	</const>
7861	<const name="PPP" value="2">
7862	<desc>
7863	Point-to-point protocol encapsulation.
7864	</desc>
7865	</const>
7866	<const name="SLIP" value="3">
7867	<desc>
7868	Serial line IP encapsulation.
7869	</desc>
7870	</const>
7871	</enum>
7872
7873	<enum
7874	name="HostNetworkInterfaceStatus"
7875	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7876	>
7877	<desc>
7878	Current status of the interface.
7879	<see><link to="IHostNetworkInterface"/></see>
7880	</desc>
7881
7882	<const name="Unknown" value="0">
7883	<desc>
7884	The state of interface cannot be determined.
7885	</desc>
7886	</const>
7887	<const name="Up" value="1">
7888	<desc>
7889	The interface is fully operational.
7890	</desc>
7891	</const>
7892	<const name="Down" value="2">
7893	<desc>
7894	The interface is not functioning.
7895	</desc>
7896	</const>
7897	</enum>
7898
7899	<enum
7900	name="HostNetworkInterfaceType"
7901	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7902	>
7903	<desc>
7904	Network interface type.
7905	</desc>
7906	<const name="Bridged" value="1"/>
7907	<const name="HostOnly" value="2"/>
7908	</enum>
7909
7910	<interface
7911	name="IHostNetworkInterface" extends="$unknown"
7912	uuid="87a4153d-6889-4dd6-9654-2e9ff0ae8dec"
7913	wsmap="managed"
7914	>
7915	<desc>
7916	Represents one of host's network interfaces. IP V6 address and network
7917	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7918	separated by colons.
7919	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7920	</desc>
7921	<attribute name="name" type="wstring" readonly="yes">
7922	<desc>Returns the host network interface name.</desc>
7923	</attribute>
7924
7925	<attribute name="id" type="uuid" mod="string" readonly="yes">
7926	<desc>Returns the interface UUID.</desc>
7927	</attribute>
7928
7929	<attribute name="networkName" type="wstring" readonly="yes">
7930	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7931	</attribute>
7932
7933	<attribute name="DHCPEnabled" type="boolean" readonly="yes">
7934	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7935	</attribute>
7936
7937	<attribute name="IPAddress" type="wstring" readonly="yes">
7938	<desc>Returns the IP V4 address of the interface.</desc>
7939	</attribute>
7940
7941	<attribute name="networkMask" type="wstring" readonly="yes">
7942	<desc>Returns the network mask of the interface.</desc>
7943	</attribute>
7944
7945	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7946	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7947	</attribute>
7948
7949	<attribute name="IPV6Address" type="wstring" readonly="yes">
7950	<desc>Returns the IP V6 address of the interface.</desc>
7951	</attribute>
7952
7953	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7954	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7955	</attribute>
7956
7957	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7958	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7959	</attribute>
7960
7961	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7962	<desc>Type of protocol encapsulation used.</desc>
7963	</attribute>
7964
7965	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7966	<desc>Status of the interface.</desc>
7967	</attribute>
7968
7969	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7970	<desc>specifies the host interface type.</desc>
7971	</attribute>
7972
7973	<method name="enableStaticIPConfig">
7974	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7975	<param name="IPAddress" type="wstring" dir="in">
7976	<desc>
7977	IP address.
7978	</desc>
7979	</param>
7980	<param name="networkMask" type="wstring" dir="in">
7981	<desc>
7982	network mask.
7983	</desc>
7984	</param>
7985	</method>
7986
7987	<method name="enableStaticIPConfigV6">
7988	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7989	<param name="IPV6Address" type="wstring" dir="in">
7990	<desc>
7991	IP address.
7992	</desc>
7993	</param>
7994	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7995	<desc>
7996	network mask.
7997	</desc>
7998	</param>
7999	</method>
8000
8001	<method name="enableDynamicIPConfig">
8002	<desc>enables the dynamic IP configuration.</desc>
8003	</method>
8004
8005	<method name="DHCPRediscover">
8006	<desc>refreshes the IP configuration for DHCP-enabled interface.</desc>
8007	</method>
8008
8009	</interface>
8010
8011	<interface
8012	name="IHost" extends="$unknown"
8013	uuid="30678943-32df-4830-b413-931b25ac86a0"
8014	wsmap="managed"
8015	>
8016	<desc>
8017	The IHost interface represents the physical machine that this VirtualBox
8018	installation runs on.
8019
8020	An object implementing this interface is returned by the
8021	<link to="IVirtualBox::host" /> attribute. This interface contains
8022	read-only information about the host's physical hardware (such as what
8023	processors and disks are available, what the host operating system is,
8024	and so on) and also allows for manipulating some of the host's hardware,
8025	such as global USB device filters and host interface networking.
8026
8027	</desc>
8028	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
8029	<desc>List of DVD drives available on the host.</desc>
8030	</attribute>
8031
8032	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
8033	<desc>List of floppy drives available on the host.</desc>
8034	</attribute>
8035
8036	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
8037	<desc>
8038	List of USB devices currently attached to the host.
8039	Once a new device is physically attached to the host computer,
8040	it appears in this list and remains there until detached.
8041
8042	<note>
8043	If USB functionality is not available in the given edition of
8044	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8045	</note>
8046	</desc>
8047	</attribute>
8048
8049	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
8050	<desc>
8051	List of USB device filters in action.
8052	When a new device is physically attached to the host computer,
8053	filters from this list are applied to it (in order they are stored
8054	in the list). The first matched filter will determine the
8055	<link to="IHostUSBDeviceFilter::action">action</link>
8056	performed on the device.
8057
8058	Unless the device is ignored by these filters, filters of all
8059	currently running virtual machines
8060	(<link to="IUSBController::deviceFilters"/>) are applied to it.
8061
8062	<note>
8063	If USB functionality is not available in the given edition of
8064	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8065	</note>
8066
8067	<see><link to="IHostUSBDeviceFilter"/>,
8068	<link to="USBDeviceState"/></see>
8069	</desc>
8070	</attribute>
8071
8072	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
8073	<desc>List of host network interfaces currently defined on the host.</desc>
8074	</attribute>
8075
8076	<attribute name="processorCount" type="unsigned long" readonly="yes">
8077	<desc>Number of (logical) CPUs installed in the host system.</desc>
8078	</attribute>
8079
8080	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
8081	<desc>Number of (logical) CPUs online in the host system.</desc>
8082	</attribute>
8083
8084	<attribute name="processorCoreCount" type="unsigned long" readonly="yes">
8085	<desc>Number of physical processor cores installed in the host system.</desc>
8086	</attribute>
8087
8088	<method name="getProcessorSpeed">
8089	<desc>Query the (approximate) maximum speed of a specified host CPU in
8090	Megahertz.
8091	</desc>
8092	<param name="cpuId" type="unsigned long" dir="in">
8093	<desc>
8094	Identifier of the CPU.
8095	</desc>
8096	</param>
8097	<param name="speed" type="unsigned long" dir="return">
8098	<desc>
8099	Speed value. 0 is returned if value is not known or @a cpuId is
8100	invalid.
8101	</desc>
8102	</param>
8103	</method>
8104
8105	<method name="getProcessorFeature">
8106	<desc>Query whether a CPU feature is supported or not.</desc>
8107	<param name="feature" type="ProcessorFeature" dir="in">
8108	<desc>
8109	CPU Feature identifier.
8110	</desc>
8111	</param>
8112	<param name="supported" type="boolean" dir="return">
8113	<desc>
8114	Feature is supported or not.
8115	</desc>
8116	</param>
8117	</method>
8118
8119	<method name="getProcessorDescription">
8120	<desc>Query the model string of a specified host CPU.
8121	</desc>
8122	<param name="cpuId" type="unsigned long" dir="in">
8123	<desc>
8124	Identifier of the CPU.
8125	<note>
8126	The current implementation might not necessarily return the
8127	description for this exact CPU.
8128	</note>
8129	</desc>
8130	</param>
8131	<param name="description" type="wstring" dir="return">
8132	<desc>
8133	Model string. An empty string is returned if value is not known or
8134	@a cpuId is invalid.
8135	</desc>
8136	</param>
8137	</method>
8138
8139	<method name="getProcessorCPUIDLeaf">
8140	<desc>
8141	Returns the CPU cpuid information for the specified leaf.
8142	</desc>
8143	<param name="cpuId" type="unsigned long" dir="in">
8144	<desc>
8145	Identifier of the CPU. The CPU most be online.
8146	<note>
8147	The current implementation might not necessarily return the
8148	description for this exact CPU.
8149	</note>
8150	</desc>
8151	</param>
8152	<param name="leaf" type="unsigned long" dir="in">
8153	<desc>
8154	CPUID leaf index (eax).
8155	</desc>
8156	</param>
8157	<param name="subLeaf" type="unsigned long" dir="in">
8158	<desc>
8159	CPUID leaf sub index (ecx). This currently only applies to cache
8160	information on Intel CPUs. Use 0 if retrieving values for
8161	<link to="IMachine::setCPUIDLeaf"/>.
8162	</desc>
8163	</param>
8164	<param name="valEax" type="unsigned long" dir="out">
8165	<desc>
8166	CPUID leaf value for register eax.
8167	</desc>
8168	</param>
8169	<param name="valEbx" type="unsigned long" dir="out">
8170	<desc>
8171	CPUID leaf value for register ebx.
8172	</desc>
8173	</param>
8174	<param name="valEcx" type="unsigned long" dir="out">
8175	<desc>
8176	CPUID leaf value for register ecx.
8177	</desc>
8178	</param>
8179	<param name="valEdx" type="unsigned long" dir="out">
8180	<desc>
8181	CPUID leaf value for register edx.
8182	</desc>
8183	</param>
8184	</method>
8185
8186	<attribute name="memorySize" type="unsigned long" readonly="yes">
8187	<desc>Amount of system memory in megabytes installed in the host system.</desc>
8188	</attribute>
8189
8190	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
8191	<desc>Available system memory in the host system.</desc>
8192	</attribute>
8193
8194	<attribute name="operatingSystem" type="wstring" readonly="yes">
8195	<desc>Name of the host system's operating system.</desc>
8196	</attribute>
8197
8198	<attribute name="OSVersion" type="wstring" readonly="yes">
8199	<desc>Host operating system's version string.</desc>
8200	</attribute>
8201
8202	<attribute name="UTCTime" type="long long" readonly="yes">
8203	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
8204	</attribute>
8205
8206	<attribute name="acceleration3DAvailable" type="boolean" readonly="yes">
8207	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
8208	</attribute>
8209
8210	<method name="createHostOnlyNetworkInterface">
8211	<desc>
8212	Creates a new adapter for Host Only Networking.
8213	<result name="E_INVALIDARG">
8214	Host network interface @a name already exists.
8215	</result>
8216	</desc>
8217	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
8218	<desc>
8219	Created host interface object.
8220	</desc>
8221	</param>
8222	<param name="progress" type="IProgress" dir="return">
8223	<desc>
8224	Progress object to track the operation completion.
8225	</desc>
8226	</param>
8227	</method>
8228
8229	<method name="removeHostOnlyNetworkInterface">
8230	<desc>
8231	Removes the given Host Only Networking interface.
8232	<result name="VBOX_E_OBJECT_NOT_FOUND">
8233	No host network interface matching @a id found.
8234	</result>
8235	</desc>
8236	<param name="id" type="uuid" mod="string" dir="in">
8237	<desc>
8238	Adapter GUID.
8239	</desc>
8240	</param>
8241	<param name="progress" type="IProgress" dir="return">
8242	<desc>
8243	Progress object to track the operation completion.
8244	</desc>
8245	</param>
8246	</method>
8247
8248	<method name="createUSBDeviceFilter">
8249	<desc>
8250	Creates a new USB device filter. All attributes except
8251	the filter name are set to empty (any match),
8252	<i>active</i> is @c false (the filter is not active).
8253
8254	The created filter can be added to the list of filters using
8255	<link to="#insertUSBDeviceFilter"/>.
8256
8257	<see><link to="#USBDeviceFilters"/></see>
8258	</desc>
8259	<param name="name" type="wstring" dir="in">
8260	<desc>
8261	Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
8262	</desc>
8263	</param>
8264	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
8265	<desc>Created filter object.</desc>
8266	</param>
8267	</method>
8268
8269	<method name="insertUSBDeviceFilter">
8270	<desc>
8271	Inserts the given USB device to the specified position
8272	in the list of filters.
8273
8274	Positions are numbered starting from @c 0. If the specified
8275	position is equal to or greater than the number of elements in
8276	the list, the filter is added at the end of the collection.
8277
8278	<note>
8279	Duplicates are not allowed, so an attempt to insert a
8280	filter already in the list is an error.
8281	</note>
8282	<note>
8283	If USB functionality is not available in the given edition of
8284	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8285	</note>
8286
8287	<see><link to="#USBDeviceFilters"/></see>
8288
8289	<result name="VBOX_E_INVALID_OBJECT_STATE">
8290	USB device filter is not created within this VirtualBox instance.
8291	</result>
8292	<result name="E_INVALIDARG">
8293	USB device filter already in list.
8294	</result>
8295
8296	</desc>
8297	<param name="position" type="unsigned long" dir="in">
8298	<desc>Position to insert the filter to.</desc>
8299	</param>
8300	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
8301	<desc>USB device filter to insert.</desc>
8302	</param>
8303	</method>
8304
8305	<method name="removeUSBDeviceFilter">
8306	<desc>
8307	Removes a USB device filter from the specified position in the
8308	list of filters.
8309
8310	Positions are numbered starting from @c 0. Specifying a
8311	position equal to or greater than the number of elements in
8312	the list will produce an error.
8313
8314	<note>
8315	If USB functionality is not available in the given edition of
8316	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8317	</note>
8318
8319	<see><link to="#USBDeviceFilters"/></see>
8320
8321	<result name="E_INVALIDARG">
8322	USB device filter list empty or invalid @a position.
8323	</result>
8324
8325	</desc>
8326	<param name="position" type="unsigned long" dir="in">
8327	<desc>Position to remove the filter from.</desc>
8328	</param>
8329	</method>
8330
8331	<method name="findHostDVDDrive">
8332	<desc>
8333	Searches for a host DVD drive with the given @c name.
8334
8335	<result name="VBOX_E_OBJECT_NOT_FOUND">
8336	Given @c name does not correspond to any host drive.
8337	</result>
8338
8339	</desc>
8340	<param name="name" type="wstring" dir="in">
8341	<desc>Name of the host drive to search for</desc>
8342	</param>
8343	<param name="drive" type="IMedium" dir="return">
8344	<desc>Found host drive object</desc>
8345	</param>
8346	</method>
8347
8348	<method name="findHostFloppyDrive">
8349	<desc>
8350	Searches for a host floppy drive with the given @c name.
8351
8352	<result name="VBOX_E_OBJECT_NOT_FOUND">
8353	Given @c name does not correspond to any host floppy drive.
8354	</result>
8355
8356	</desc>
8357	<param name="name" type="wstring" dir="in">
8358	<desc>Name of the host floppy drive to search for</desc>
8359	</param>
8360	<param name="drive" type="IMedium" dir="return">
8361	<desc>Found host floppy drive object</desc>
8362	</param>
8363	</method>
8364
8365	<method name="findHostNetworkInterfaceByName">
8366	<desc>
8367	Searches through all host network interfaces for an interface with
8368	the given @c name.
8369	<note>
8370	The method returns an error if the given @c name does not
8371	correspond to any host network interface.
8372	</note>
8373	</desc>
8374	<param name="name" type="wstring" dir="in">
8375	<desc>Name of the host network interface to search for.</desc>
8376	</param>
8377	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8378	<desc>Found host network interface object.</desc>
8379	</param>
8380	</method>
8381	<method name="findHostNetworkInterfaceById">
8382	<desc>
8383	Searches through all host network interfaces for an interface with
8384	the given GUID.
8385	<note>
8386	The method returns an error if the given GUID does not
8387	correspond to any host network interface.
8388	</note>
8389	</desc>
8390	<param name="id" type="uuid" mod="string" dir="in">
8391	<desc>GUID of the host network interface to search for.</desc>
8392	</param>
8393	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8394	<desc>Found host network interface object.</desc>
8395	</param>
8396	</method>
8397	<method name="findHostNetworkInterfacesOfType">
8398	<desc>
8399	Searches through all host network interfaces and returns a list of interfaces of the specified type
8400	</desc>
8401	<param name="type" type="HostNetworkInterfaceType" dir="in">
8402	<desc>type of the host network interfaces to search for.</desc>
8403	</param>
8404	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
8405	<desc>Found host network interface objects.</desc>
8406	</param>
8407	</method>
8408
8409	<method name="findUSBDeviceById">
8410	<desc>
8411	Searches for a USB device with the given UUID.
8412
8413	<result name="VBOX_E_OBJECT_NOT_FOUND">
8414	Given @c id does not correspond to any USB device.
8415	</result>
8416
8417	<see><link to="IUSBDevice::id"/></see>
8418	</desc>
8419	<param name="id" type="uuid" mod="string" dir="in">
8420	<desc>UUID of the USB device to search for.</desc>
8421	</param>
8422	<param name="device" type="IHostUSBDevice" dir="return">
8423	<desc>Found USB device object.</desc>
8424	</param>
8425	</method>
8426
8427	<method name="findUSBDeviceByAddress">
8428	<desc>
8429	Searches for a USB device with the given host address.
8430
8431	<result name="VBOX_E_OBJECT_NOT_FOUND">
8432	Given @c name does not correspond to any USB device.
8433	</result>
8434
8435	<see><link to="IUSBDevice::address"/></see>
8436	</desc>
8437	<param name="name" type="wstring" dir="in">
8438	<desc>
8439	Address of the USB device (as assigned by the host) to
8440	search for.
8441	</desc>
8442	</param>
8443	<param name="device" type="IHostUSBDevice" dir="return">
8444	<desc>Found USB device object.</desc>
8445	</param>
8446	</method>
8447
8448	<method name="generateMACAddress">
8449	<desc>
8450	Generates a valid Ethernet MAC address, 12 hexadecimal characters.
8451	</desc>
8452	<param name="address" type="wstring" dir="return">
8453	<desc>New Ethernet MAC address.</desc>
8454	</param>
8455	</method>
8456
8457	</interface>
8458
8459	<!--
8460	// ISystemProperties
8461	/////////////////////////////////////////////////////////////////////////
8462	-->
8463
8464	<interface
8465	name="ISystemProperties"
8466	extends="$unknown"
8467	uuid="413ea94c-efd9-491e-81fc-5df0c4d864bb"
8468	wsmap="managed"
8469	>
8470	<desc>
8471	The ISystemProperties interface represents global properties of the given
8472	VirtualBox installation.
8473
8474	These properties define limits and default values for various attributes
8475	and parameters. Most of the properties are read-only, but some can be
8476	changed by a user.
8477	</desc>
8478
8479	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
8480	<desc>Minimum guest system memory in Megabytes.</desc>
8481	</attribute>
8482
8483	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
8484	<desc>Maximum guest system memory in Megabytes.</desc>
8485	</attribute>
8486
8487	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
8488	<desc>Minimum guest video memory in Megabytes.</desc>
8489	</attribute>
8490
8491	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
8492	<desc>Maximum guest video memory in Megabytes.</desc>
8493	</attribute>
8494
8495	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
8496	<desc>Minimum CPU count.</desc>
8497	</attribute>
8498
8499	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
8500	<desc>Maximum CPU count.</desc>
8501	</attribute>
8502
8503	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8504	<desc>Maximum of monitors which could be connected.</desc>
8505	</attribute>
8506
8507	<attribute name="infoVDSize" type="long long" readonly="yes">
8508	<desc>Maximum size of a virtual disk image in bytes. Informational value,
8509	does not reflect the limits of any virtual disk image format.</desc>
8510	</attribute>
8511
8512	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8513	<desc>
8514	Maximum number of serial ports associated with every
8515	<link to="IMachine"/> instance.
8516	</desc>
8517	</attribute>
8518
8519	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8520	<desc>
8521	Maximum number of parallel ports associated with every
8522	<link to="IMachine"/> instance.
8523	</desc>
8524	</attribute>
8525
8526	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8527	<desc>
8528	Maximum device position in the boot order. This value corresponds
8529	to the total number of devices a machine can boot from, to make it
8530	possible to include all possible devices to the boot list.
8531	<see><link to="IMachine::setBootOrder"/></see>
8532	</desc>
8533	</attribute>
8534
8535	<attribute name="defaultMachineFolder" type="wstring">
8536	<desc>
8537	Full path to the default directory used to create new or open
8538	existing machines when a machine settings file name contains no
8539	path.
8540
8541	Starting with VirtualBox 4.0, by default, this attribute contains
8542	the full path of folder named "VirtualBox VMs" in the user's
8543	home directory, which depends on the host platform.
8544
8545	When setting this attribute, a full path must be specified.
8546	Setting this property to @c null or an empty string or the
8547	special value "Machines" (for compatibility reasons) will restore
8548	that default value.
8549
8550	If the folder specified herein does not exist, it will be created
8551	automatically as needed.
8552
8553	<see>
8554	<link to="IVirtualBox::createMachine"/>,
8555	<link to="IVirtualBox::openMachine"/>
8556	</see>
8557	</desc>
8558	</attribute>
8559
8560	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8561	<desc>
8562	List of all medium storage formats supported by this VirtualBox
8563	installation.
8564
8565	Keep in mind that the medium format identifier
8566	(<link to="IMediumFormat::id"/>) used in other API calls like
8567	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8568	medium format is a case-insensitive string. This means that, for
8569	example, all of the following strings:
8570	<pre>
8571	"VDI"
8572	"vdi"
8573	"VdI"</pre>
8574	refer to the same medium format.
8575
8576	Note that the virtual medium framework is backend-based, therefore
8577	the list of supported formats depends on what backends are currently
8578	installed.
8579
8580	<see><link to="IMediumFormat"/></see>
8581	</desc>
8582	</attribute>
8583
8584	<attribute name="defaultHardDiskFormat" type="wstring">
8585	<desc>
8586	Identifier of the default medium format used by VirtualBox.
8587
8588	The medium format set by this attribute is used by VirtualBox
8589	when the medium format was not specified explicitly. One example is
8590	<link to="IVirtualBox::createHardDisk"/> with the empty
8591	format argument. A more complex example is implicit creation of
8592	differencing media when taking a snapshot of a virtual machine:
8593	this operation will try to use a format of the parent medium first
8594	and if this format does not support differencing media the default
8595	format specified by this argument will be used.
8596
8597	The list of supported medium formats may be obtained by the
8598	<link to="#mediumFormats"/> call. Note that the default medium
8599	format must have a capability to create differencing media;
8600	otherwise operations that create media implicitly may fail
8601	unexpectedly.
8602
8603	The initial value of this property is <tt>"VDI"</tt> in the current
8604	version of the VirtualBox product, but may change in the future.
8605
8606	<note>
8607	Setting this property to @c null or empty string will restore the
8608	initial value.
8609	</note>
8610
8611	<see>
8612	<link to="#mediumFormats"/>,
8613	<link to="IMediumFormat::id"/>,
8614	<link to="IVirtualBox::createHardDisk"/>
8615	</see>
8616	</desc>
8617	</attribute>
8618
8619	<attribute name="freeDiskSpaceWarning" type="long long">
8620	<desc>Issue a warning if the free disk space is below (or in some disk
8621	intensive operation is expected to go below) the given size in
8622	bytes.</desc>
8623	</attribute>
8624
8625	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
8626	<desc>Issue a warning if the free disk space is below (or in some disk
8627	intensive operation is expected to go below) the given percentage.</desc>
8628	</attribute>
8629
8630	<attribute name="freeDiskSpaceError" type="long long">
8631	<desc>Issue an error if the free disk space is below (or in some disk
8632	intensive operation is expected to go below) the given size in
8633	bytes.</desc>
8634	</attribute>
8635
8636	<attribute name="freeDiskSpacePercentError" type="unsigned long">
8637	<desc>Issue an error if the free disk space is below (or in some disk
8638	intensive operation is expected to go below) the given percentage.</desc>
8639	</attribute>
8640
8641	<attribute name="VRDEAuthLibrary" type="wstring">
8642	<desc>
8643	Library that provides authentication for Remote Desktop clients. The library
8644	is used if a virtual machine's authentication type is set to "external"
8645	in the VM RemoteDisplay configuration.
8646
8647	The system library extension (".DLL" or ".so") must be omitted.
8648	A full path can be specified; if not, then the library must reside on the
8649	system's default library path.
8650
8651	The default value of this property is <tt>"VBoxAuth"</tt>. There is a library
8652	of that name in one of the default VirtualBox library directories.
8653
8654	For details about VirtualBox authentication libraries and how to implement
8655	them, please refer to the VirtualBox manual.
8656
8657	<note>
8658	Setting this property to @c null or empty string will restore the
8659	initial value.
8660	</note>
8661	</desc>
8662	</attribute>
8663
8664	<attribute name="webServiceAuthLibrary" type="wstring">
8665	<desc>
8666	Library that provides authentication for webservice clients. The library
8667	is used if a virtual machine's authentication type is set to "external"
8668	in the VM RemoteDisplay configuration and will be called from
8669	within the <link to="IWebsessionManager::logon" /> implementation.
8670
8671	As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
8672	there is no per-VM setting for this, as the webservice is a global
8673	resource (if it is running). Only for this setting (for the webservice),
8674	setting this value to a literal <tt>"null"</tt> string disables authentication,
8675	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8676	no matter what user name and password are supplied.
8677
8678	The initial value of this property is <tt>"VBoxAuth"</tt>,
8679	meaning that the webservice will use the same authentication
8680	library that is used by default for VRDE (again, see
8681	<link to="ISystemProperties::VRDEAuthLibrary" />).
8682	The format and calling convention of authentication libraries
8683	is the same for the webservice as it is for VRDE.
8684
8685	<note>
8686	Setting this property to @c null or empty string will restore the
8687	initial value.
8688	</note>
8689	</desc>
8690	</attribute>
8691
8692	<attribute name="defaultVRDEExtPack" type="wstring">
8693	<desc>
8694	The name of the extension pack providing the default VRDE.
8695
8696	This attribute is for choosing between multiple extension packs
8697	providing VRDE. If only one is installed, it will automatically be the
8698	default one. The attribute value can be empty if no VRDE extension
8699	pack is installed.
8700
8701	For details about VirtualBox Remote Desktop Extension and how to
8702	implement one, please refer to the VirtualBox SDK.
8703	</desc>
8704	</attribute>
8705
8706	<attribute name="logHistoryCount" type="unsigned long">
8707	<desc>
8708	This value specifies how many old release log files are kept.
8709	</desc>
8710	</attribute>
8711
8712	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8713	<desc>This value hold the default audio driver for the current
8714	system.</desc>
8715	</attribute>
8716
8717	<attribute name="autostartDatabasePath" type="wstring">
8718	<desc>
8719	The path to the autostart database. Depending on the host this might
8720	be a filesystem path or something else.
8721	</desc>
8722	</attribute>
8723
8724	<attribute name="defaultAdditionsISO" type="wstring">
8725	<desc>
8726	The path to the default Guest Additions ISO image. Can be empty if
8727	the location is not known in this installation.
8728	</desc>
8729	</attribute>
8730
8731	<attribute name="defaultFrontend" type="wstring">
8732	<desc>
8733	Selects which VM frontend should be used by default when launching
8734	a VM through the <link to="IMachine::launchVMProcess" /> method.
8735	Empty or @c null strings do not define a particular default, it is up
8736	to <link to="IMachine::launchVMProcess" /> to select one. See the
8737	description of <link to="IMachine::launchVMProcess" /> for the valid
8738	frontend types.
8739
8740	This global setting is overridden by the per-VM attribute
8741	<link to="IMachine::defaultFrontend" /> or a frontend type
8742	passed to <link to="IMachine::launchVMProcess" />.
8743	</desc>
8744	</attribute>
8745
8746	<method name="getMaxNetworkAdapters">
8747	<desc>
8748	Maximum total number of network adapters associated with every
8749	<link to="IMachine"/> instance.
8750	</desc>
8751
8752	<param name="chipset" type="ChipsetType" dir="in">
8753	<desc>The chipset type to get the value for.</desc>
8754	</param>
8755
8756
8757	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8758	<desc>The maximum total number of network adapters allowed.</desc>
8759	</param>
8760
8761	</method>
8762
8763	<method name="getMaxNetworkAdaptersOfType">
8764	<desc>
8765	Maximum number of network adapters of a given attachment type,
8766	associated with every <link to="IMachine"/> instance.
8767	</desc>
8768
8769	<param name="chipset" type="ChipsetType" dir="in">
8770	<desc>The chipset type to get the value for.</desc>
8771	</param>
8772
8773	<param name="type" type="NetworkAttachmentType" dir="in">
8774	<desc>Type of attachment.</desc>
8775	</param>
8776
8777	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8778	<desc>The maximum number of network adapters allowed for
8779	particular chipset and attachment type.</desc>
8780	</param>
8781
8782	</method>
8783
8784
8785	<method name="getMaxDevicesPerPortForStorageBus">
8786	<desc>Returns the maximum number of devices which can be attached to a port
8787	for the given storage bus.</desc>
8788
8789	<param name="bus" type="StorageBus" dir="in">
8790	<desc>The storage bus type to get the value for.</desc>
8791	</param>
8792
8793	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8794	<desc>The maximum number of devices which can be attached to the port for the given
8795	storage bus.</desc>
8796	</param>
8797	</method>
8798
8799	<method name="getMinPortCountForStorageBus">
8800	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8801
8802	<param name="bus" type="StorageBus" dir="in">
8803	<desc>The storage bus type to get the value for.</desc>
8804	</param>
8805
8806	<param name="minPortCount" type="unsigned long" dir="return">
8807	<desc>The minimum number of ports for the given storage bus.</desc>
8808	</param>
8809	</method>
8810
8811	<method name="getMaxPortCountForStorageBus">
8812	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8813
8814	<param name="bus" type="StorageBus" dir="in">
8815	<desc>The storage bus type to get the value for.</desc>
8816	</param>
8817
8818	<param name="maxPortCount" type="unsigned long" dir="return">
8819	<desc>The maximum number of ports for the given storage bus.</desc>
8820	</param>
8821	</method>
8822
8823	<method name="getMaxInstancesOfStorageBus">
8824	<desc>Returns the maximum number of storage bus instances which
8825	can be configured for each VM. This corresponds to the number of
8826	storage controllers one can have. Value may depend on chipset type
8827	used.</desc>
8828
8829	<param name="chipset" type="ChipsetType" dir="in">
8830	<desc>The chipset type to get the value for.</desc>
8831	</param>
8832
8833	<param name="bus" type="StorageBus" dir="in">
8834	<desc>The storage bus type to get the value for.</desc>
8835	</param>
8836
8837	<param name="maxInstances" type="unsigned long" dir="return">
8838	<desc>The maximum number of instances for the given storage bus.</desc>
8839	</param>
8840	</method>
8841
8842	<method name="getDeviceTypesForStorageBus">
8843	<desc>Returns list of all the supported device types
8844	(<link to="DeviceType"/>) for the given type of storage
8845	bus.</desc>
8846
8847	<param name="bus" type="StorageBus" dir="in">
8848	<desc>The storage bus type to get the value for.</desc>
8849	</param>
8850
8851	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8852	<desc>The list of all supported device types for the given storage bus.</desc>
8853	</param>
8854	</method>
8855
8856	<method name="getDefaultIoCacheSettingForStorageController">
8857	<desc>Returns the default I/O cache setting for the
8858	given storage controller</desc>
8859
8860	<param name="controllerType" type="StorageControllerType" dir="in">
8861	<desc>The storage controller to the setting for.</desc>
8862	</param>
8863
8864	<param name="enabled" type="boolean" dir="return">
8865	<desc>Returned flag indicating the default value</desc>
8866	</param>
8867	</method>
8868	</interface>
8869
8870	<!--
8871	// IGuest
8872	/////////////////////////////////////////////////////////////////////////
8873	-->
8874
8875	<interface
8876	name="IGuestOSType" extends="$unknown"
8877	uuid="6d968f9a-858b-4c50-bf17-241f069e94c2"
8878	wsmap="struct"
8879	>
8880	<desc>
8881	</desc>
8882
8883	<attribute name="familyId" type="wstring" readonly="yes">
8884	<desc>Guest OS family identifier string.</desc>
8885	</attribute>
8886
8887	<attribute name="familyDescription" type="wstring" readonly="yes">
8888	<desc>Human readable description of the guest OS family.</desc>
8889	</attribute>
8890
8891	<attribute name="id" type="wstring" readonly="yes">
8892	<desc>Guest OS identifier string.</desc>
8893	</attribute>
8894
8895	<attribute name="description" type="wstring" readonly="yes">
8896	<desc>Human readable description of the guest OS.</desc>
8897	</attribute>
8898
8899	<attribute name="is64Bit" type="boolean" readonly="yes">
8900	<desc>Returns @c true if the given OS is 64-bit</desc>
8901	</attribute>
8902
8903	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8904	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8905	</attribute>
8906
8907	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8908	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8909	</attribute>
8910
8911	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8912	<desc>Recommended RAM size in Megabytes.</desc>
8913	</attribute>
8914
8915	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8916	<desc>Recommended video RAM size in Megabytes.</desc>
8917	</attribute>
8918
8919	<attribute name="recommended2DVideoAcceleration" type="boolean" readonly="yes">
8920	<desc>Returns @c true if 2D video acceleration is recommended for this OS type.</desc>
8921	</attribute>
8922
8923	<attribute name="recommended3DAcceleration" type="boolean" readonly="yes">
8924	<desc>Returns @c true if 3D acceleration is recommended for this OS type.</desc>
8925	</attribute>
8926
8927	<attribute name="recommendedHDD" type="long long" readonly="yes">
8928	<desc>Recommended hard disk size in bytes.</desc>
8929	</attribute>
8930
8931	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8932	<desc>Returns recommended network adapter for this OS type.</desc>
8933	</attribute>
8934
8935	<attribute name="recommendedPAE" type="boolean" readonly="yes">
8936	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8937	</attribute>
8938
8939	<attribute name="recommendedDVDStorageController" type="StorageControllerType" readonly="yes">
8940	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8941	</attribute>
8942
8943	<attribute name="recommendedDVDStorageBus" type="StorageBus" readonly="yes">
8944	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8945	</attribute>
8946
8947	<attribute name="recommendedHDStorageController" type="StorageControllerType" readonly="yes">
8948	<desc>Recommended storage controller type for HD drives.</desc>
8949	</attribute>
8950
8951	<attribute name="recommendedHDStorageBus" type="StorageBus" readonly="yes">
8952	<desc>Recommended storage bus type for HD drives.</desc>
8953	</attribute>
8954
8955	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8956	<desc>Recommended firmware type.</desc>
8957	</attribute>
8958
8959	<attribute name="recommendedUSBHID" type="boolean" readonly="yes">
8960	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8961	</attribute>
8962
8963	<attribute name="recommendedHPET" type="boolean" readonly="yes">
8964	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8965	</attribute>
8966
8967	<attribute name="recommendedUSBTablet" type="boolean" readonly="yes">
8968	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8969	</attribute>
8970
8971	<attribute name="recommendedRTCUseUTC" type="boolean" readonly="yes">
8972	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8973	</attribute>
8974
8975	<attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
8976	<desc>Recommended chipset type.</desc>
8977	</attribute>
8978
8979	<attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
8980	<desc>Recommended audio type.</desc>
8981	</attribute>
8982
8983	<attribute name="recommendedFloppy" type="boolean" readonly="yes">
8984	<desc>Returns @c true a floppy drive is recommended for this OS type.</desc>
8985	</attribute>
8986
8987	<attribute name="recommendedUSB" type="boolean" readonly="yes">
8988	<desc>Returns @c true a USB controller is recommended for this OS type.</desc>
8989	</attribute>
8990
8991	</interface>
8992
8993	<enum
8994	name="AdditionsFacilityType"
8995	uuid="98f7f957-89fb-49b6-a3b1-31e3285eb1d8"
8996	>
8997	<desc>
8998	Guest Additions facility IDs.
8999	</desc>
9000
9001	<const name="None" value="0">
9002	<desc>No/invalid facility.</desc>
9003	</const>
9004	<const name="VBoxGuestDriver" value="20">
9005	<desc>VirtualBox base driver (VBoxGuest).</desc>
9006	</const>
9007	<const name="AutoLogon" value="90">
9008	<desc>Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox).</desc>
9009	</const>
9010	<const name="VBoxService" value="100">
9011	<desc>VirtualBox system service (VBoxService).</desc>
9012	</const>
9013	<const name="VBoxTrayClient" value="101">
9014	<desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc>
9015	</const>
9016	<const name="Seamless" value="1000">
9017	<desc>Seamless guest desktop integration.</desc>
9018	</const>
9019	<const name="Graphics" value="1100">
9020	<desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints
9021	are not immediately acted on and guest display resizes are probably not initiated by
9022	the guest additions.
9023	</desc>
9024	</const>
9025	<const name="All" value="2147483646">
9026	<desc>All facilities selected.</desc>
9027	</const>
9028	</enum>
9029
9030	<enum
9031	name="AdditionsFacilityClass"
9032	uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f"
9033	>
9034	<desc>
9035	Guest Additions facility classes.
9036	</desc>
9037
9038	<const name="None" value="0">
9039	<desc>No/invalid class.</desc>
9040	</const>
9041	<const name="Driver" value="10">
9042	<desc>Driver.</desc>
9043	</const>
9044	<const name="Service" value="30">
9045	<desc>System service.</desc>
9046	</const>
9047	<const name="Program" value="50">
9048	<desc>Program.</desc>
9049	</const>
9050	<const name="Feature" value="100">
9051	<desc>Feature.</desc>
9052	</const>
9053	<const name="ThirdParty" value="999">
9054	<desc>Third party.</desc>
9055	</const>
9056	<const name="All" value="2147483646">
9057	<desc>All facility classes selected.</desc>
9058	</const>
9059	</enum>
9060
9061	<enum
9062	name="AdditionsFacilityStatus"
9063	uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde"
9064	>
9065	<desc>
9066	Guest Additions facility states.
9067	</desc>
9068
9069	<const name="Inactive" value="0">
9070	<desc>Facility is not active.</desc>
9071	</const>
9072	<const name="Paused" value="1">
9073	<desc>Facility has been paused.</desc>
9074	</const>
9075	<const name="PreInit" value="20">
9076	<desc>Facility is preparing to initialize.</desc>
9077	</const>
9078	<const name="Init" value="30">
9079	<desc>Facility is initializing.</desc>
9080	</const>
9081	<const name="Active" value="50">
9082	<desc>Facility is up and running.</desc>
9083	</const>
9084	<const name="Terminating" value="100">
9085	<desc>Facility is shutting down.</desc>
9086	</const>
9087	<const name="Terminated" value="101">
9088	<desc>Facility successfully shut down.</desc>
9089	</const>
9090	<const name="Failed" value="800">
9091	<desc>Facility failed to start.</desc>
9092	</const>
9093	<const name="Unknown" value="999">
9094	<desc>Facility status is unknown.</desc>
9095	</const>
9096	</enum>
9097
9098	<interface
9099	name="IAdditionsFacility" extends="$unknown"
9100	uuid="54992946-6af1-4e49-98ec-58b558b7291e"
9101	wsmap="struct"
9102	>
9103	<desc>
9104	Structure representing a Guest Additions facility.
9105	</desc>
9106
9107	<attribute name="classType" type="AdditionsFacilityClass" readonly="yes">
9108	<desc>The class this facility is part of.</desc>
9109	</attribute>
9110
9111	<attribute name="lastUpdated" type="long long" readonly="yes">
9112	<desc>
9113	Time stamp of the last status update,
9114	in milliseconds since 1970-01-01 UTC.
9115	</desc>
9116	</attribute>
9117
9118	<attribute name="name" type="wstring" readonly="yes">
9119	<desc>The facility's friendly name.</desc>
9120	</attribute>
9121
9122	<attribute name="status" type="AdditionsFacilityStatus" readonly="yes">
9123	<desc>The current status.</desc>
9124	</attribute>
9125
9126	<attribute name="type" type="AdditionsFacilityType" readonly="yes">
9127	<desc>The facility's type ID.</desc>
9128	</attribute>
9129	</interface>
9130
9131	<enum
9132	name="AdditionsRunLevelType"
9133	uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
9134	>
9135	<desc>
9136	Guest Additions run level type.
9137	</desc>
9138
9139	<const name="None" value="0">
9140	<desc>Guest Additions are not loaded.</desc>
9141	</const>
9142	<const name="System" value="1">
9143	<desc>Guest drivers are loaded.</desc>
9144	</const>
9145	<const name="Userland" value="2">
9146	<desc>Common components (such as application services) are loaded.</desc>
9147	</const>
9148	<const name="Desktop" value="3">
9149	<desc>Per-user desktop components are loaded.</desc>
9150	</const>
9151	</enum>
9152
9153	<enum
9154	name="AdditionsUpdateFlag"
9155	uuid="726a818d-18d6-4389-94e8-3e9e6826171a"
9156	>
9157	<desc>
9158	Guest Additions update flags.
9159	</desc>
9160
9161	<const name="None" value="0">
9162	<desc>No flag set.</desc>
9163	</const>
9164	<const name="WaitForUpdateStartOnly" value="1">
9165	<desc>Starts the regular updating process and waits until the
9166	actual Guest Additions update inside the guest was started.
9167	This can be necessary due to needed interaction with the guest
9168	OS during the installation phase.</desc>
9169	</const>
9170	</enum>
9171
9172	<enum
9173	name="GuestSessionStatus"
9174	uuid="ac2669da-4624-44f2-85b5-0b0bfb8d8673"
9175	>
9176	<desc>
9177	Guest session status. This enumeration represents possible values of
9178	the <link to="IGuestSession::status"/> attribute.
9179	</desc>
9180	<const name="Undefined" value="0">
9181	<desc>Guest session is in an undefined state.</desc>
9182	</const>
9183	<const name="Starting" value="10">
9184	<desc>Guest session is being started.</desc>
9185	</const>
9186	<const name="Started" value="100">
9187	<desc>Guest session has been started.</desc>
9188	</const>
9189	<const name="Terminating" value="480">
9190	<desc>Guest session is being terminated.</desc>
9191	</const>
9192	<const name="Terminated" value="500">
9193	<desc>Guest session terminated normally.</desc>
9194	</const>
9195	<const name="TimedOutKilled" value="512">
9196	<desc>Guest session timed out and was killed.</desc>
9197	</const>
9198	<const name="TimedOutAbnormally" value="513">
9199	<desc>Guest session timed out and was not killed successfully.</desc>
9200	</const>
9201	<const name="Down" value="600">
9202	<desc>Service/OS is stopping, guest session was killed.</desc>
9203	</const>
9204	<const name="Error" value="800">
9205	<desc>Something went wrong.</desc>
9206	</const>
9207	</enum>
9208
9209	<enum
9210	name="GuestSessionWaitForFlag"
9211	uuid="bb7a372a-f635-4e11-a81a-e707f3a52ef5"
9212	>
9213	<desc>
9214	Guest session waiting flags. Multiple flags can be combined.
9215	</desc>
9216
9217	<const name="None" value="0">
9218	<desc>No waiting flags specified. Do not use this.</desc>
9219	</const>
9220	<const name="Start" value="1">
9221	<desc>Wait for the guest session being started.</desc>
9222	</const>
9223	<const name="Terminate" value="2">
9224	<desc>Wait for the guest session being terminated.</desc>
9225	</const>
9226	<const name="Status" value="4">
9227	<desc>Wait for the next guest session status change.</desc>
9228	</const>
9229	</enum>
9230
9231	<enum
9232	name="GuestSessionWaitResult"
9233	uuid="c0f6a8a5-fdb6-42bf-a582-56c6f82bcd2d"
9234	>
9235	<desc>
9236	Guest session waiting results. Depending on the session waiting flags (for
9237	more information see <link to="GuestSessionWaitForFlag"/>) the waiting result
9238	can vary based on the session's current status.
9239
9240	To wait for a guest session to terminate after it has been
9241	created by <link to="IGuest::createSession"/> one would specify
9242	GuestSessionWaitResult_Terminate.
9243	</desc>
9244
9245	<const name="None" value="0">
9246	<desc>No result was returned. Not being used.</desc>
9247	</const>
9248	<const name="Start" value="1">
9249	<desc>The guest session has been started.</desc>
9250	</const>
9251	<const name="Terminate" value="2">
9252	<desc>The guest session has been terminated.</desc>
9253	</const>
9254	<const name="Status" value="3">
9255	<desc>
9256	The guest session has changed its status. The status then can
9257	be retrieved via <link to="IGuestSession::status"/>.
9258	</desc>
9259	</const>
9260	<const name="Error" value="4">
9261	<desc>Error while executing the process.</desc>
9262	</const>
9263	<const name="Timeout" value="5">
9264	<desc>
9265	The waiting operation timed out. This also will happen
9266	when no event has been occured matching the
9267	current waiting flags in a <link to="IGuestSession::waitFor"/> call.
9268	</desc>
9269	</const>
9270	<const name="WaitFlagNotSupported" value="6">
9271	<desc>
9272	A waiting flag specified in the <link to="IGuestSession::waitFor"/> call
9273	is not supported by the guest.
9274	</desc>
9275	</const>
9276	</enum>
9277
9278	<enum
9279	name="FileSeekType"
9280	uuid="1b73f4f3-3515-4073-a506-76878d9e2541"
9281	>
9282	<desc>
9283	File seeking types.
9284	</desc>
9285
9286	<const name="Set" value="0">
9287	<desc>Seek from the start of the file.</desc>
9288	</const>
9289	<const name="Current" value="1">
9290	<desc>Seek from the current file position.</desc>
9291	</const>
9292	</enum>
9293
9294	<enum
9295	name="ProcessInputFlag"
9296	uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
9297	>
9298	<desc>
9299	Guest process input flags.
9300	</desc>
9301	<const name="None" value="0">
9302	<desc>No flag set.</desc>
9303	</const>
9304	<const name="EndOfFile" value="1">
9305	<desc>End of file (input) reached.</desc>
9306	</const>
9307	</enum>
9308
9309	<enum
9310	name="ProcessOutputFlag"
9311	uuid="9979e85a-52bb-40b7-870c-57115e27e0f1"
9312	>
9313	<desc>
9314	Guest process output flags for specifying which
9315	type of output to retrieve.
9316	</desc>
9317	<const name="None" value="0">
9318	<desc>No flags set. Get output from stdout.</desc>
9319	</const>
9320	<const name="StdErr" value="1">
9321	<desc>Get output from stderr.</desc>
9322	</const>
9323	</enum>
9324
9325	<enum
9326	name="ProcessWaitForFlag"
9327	uuid="23b550c7-78e1-437e-98f0-65fd9757bcd2"
9328	>
9329	<desc>
9330	Process waiting flags. Multiple flags can be combined.
9331	</desc>
9332
9333	<const name="None" value="0">
9334	<desc>No waiting flags specified. Do not use this.</desc>
9335	</const>
9336	<const name="Start" value="1">
9337	<desc>Wait for the process being started.</desc>
9338	</const>
9339	<const name="Terminate" value="2">
9340	<desc>Wait for the process being terminated.</desc>
9341	</const>
9342	<const name="StdIn" value="4">
9343	<desc>Wait for stdin becoming available.</desc>
9344	</const>
9345	<const name="StdOut" value="8">
9346	<desc>Wait for data becoming available on stdout.</desc>
9347	</const>
9348	<const name="StdErr" value="16">
9349	<desc>Wait for data becoming available on stderr.</desc>
9350	</const>
9351	</enum>
9352
9353	<enum
9354	name="ProcessWaitResult"
9355	uuid="40719cbe-f192-4fe9-a231-6697b3c8e2b4"
9356	>
9357	<desc>
9358	Process waiting results. Depending on the process waiting flags (for
9359	more information see <link to="ProcessWaitForFlag"/>) the waiting result
9360	can vary based on the processes' current status.
9361
9362	To wait for a guest process to terminate after it has been
9363	created by <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>
9364	one would specify ProcessWaitResult_Terminate.
9365
9366	If a guest process has been started with ProcessCreateFlag_WaitForStdOut
9367	a client can wait with ProcessWaitResult_StdOut for new data to arrive on
9368	stdout; same applies for ProcessCreateFlag_WaitForStdErr and
9369	ProcessWaitResult_StdErr.
9370	</desc>
9371
9372	<const name="None" value="0">
9373	<desc>No result was returned. Not being used.</desc>
9374	</const>
9375	<const name="Start" value="1">
9376	<desc>The process has been started.</desc>
9377	</const>
9378	<const name="Terminate" value="2">
9379	<desc>The process has been terminated.</desc>
9380	</const>
9381	<const name="Status" value="3">
9382	<desc>
9383	The process has changed its status. The status then can
9384	be retrieved via <link to="IProcess::status"/>.
9385	</desc>
9386	</const>
9387	<const name="Error" value="4">
9388	<desc>Error while executing the process.</desc>
9389	</const>
9390	<const name="Timeout" value="5">
9391	<desc>
9392	The waiting operation timed out. This also will happen
9393	when no event has been occured matching the
9394	current waiting flags in a <link to="IProcess::waitFor"/> call.
9395	</desc>
9396	</const>
9397	<const name="StdIn" value="6">
9398	<desc>
9399	The process signalled that stdin became available for writing
9400	and that the process awaits input now.</desc>
9401	</const>
9402	<const name="StdOut" value="7">
9403	<desc>Data on stdout became available for reading.</desc>
9404	</const>
9405	<const name="StdErr" value="8">
9406	<desc>Data on stderr became available for reading.</desc>
9407	</const>
9408	<const name="WaitFlagNotSupported" value="9">
9409	<desc>
9410	A waiting flag specified in the <link to="IProcess::waitFor"/> call
9411	is not supported by the guest.
9412	</desc>
9413	</const>
9414	</enum>
9415
9416	<enum
9417	name="CopyFileFlag"
9418	uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
9419	>
9420	<desc>
9421	File copying flags.
9422	</desc>
9423	<const name="None" value="0">
9424	<desc>No flag set.</desc>
9425	</const>
9426	<const name="Recursive" value="1">
9427	<desc>Copy directories recursively.</desc>
9428	</const>
9429	<const name="Update" value="2">
9430	<desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc>
9431	</const>
9432	<const name="FollowLinks" value="4">
9433	<desc>Follow symbolic links.</desc>
9434	</const>
9435	</enum>
9436
9437	<enum
9438	name="DirectoryCreateFlag"
9439	uuid="bd721b0e-ced5-4f79-b368-249897c32a36"
9440	>
9441	<desc>
9442	Directory creation flags.
9443	</desc>
9444	<const name="None" value="0">
9445	<desc>No flag set.</desc>
9446	</const>
9447	<const name="Parents" value="1">
9448	<desc>No error if existing, make parent directories as needed.</desc>
9449	</const>
9450	</enum>
9451
9452	<enum
9453	name="DirectoryRemoveRecFlag"
9454	uuid="455aabf0-7692-48f6-9061-f21579b65769"
9455	>
9456	<desc>
9457	Directory recursive removement flags.
9458	</desc>
9459
9460	<const name="None" value="0">
9461	<desc>No flag set.</desc>
9462	</const>
9463	<const name="ContentAndDir" value="1">
9464	<desc>Delete the content of the directory and the directory itself.</desc>
9465	</const>
9466	<const name="ContentOnly" value="2">
9467	<desc>Only delete the content of the directory, omit the directory it self.</desc>
9468	</const>
9469	</enum>
9470
9471	<enum
9472	name="PathRenameFlag"
9473	uuid="f3baa09f-c758-453d-b91c-c7787d76351d"
9474	>
9475	<desc>
9476	Path renaming flags.
9477	</desc>
9478
9479	<const name="None" value="0">
9480	<desc>No flag set.</desc>
9481	</const>
9482	<const name="NoReplace" value="1">
9483	<desc>Do not replace anything.</desc>
9484	</const>
9485	<const name="Replace" value="2">
9486	<desc>This will replace attempt any target which isn't a directory.</desc>
9487	</const>
9488	<const name="NoSymlinks" value="4">
9489	<desc>Don't allow symbolic links as part of the path.</desc>
9490	</const>
9491	</enum>
9492
9493	<enum
9494	name="ProcessCreateFlag"
9495	uuid="35192799-bfde-405d-9bea-c735ab9998e4"
9496	>
9497	<desc>
9498	Guest process execution flags.
9499	</desc>
9500
9501	<const name="None" value="0">
9502	<desc>No flag set.</desc>
9503	</const>
9504	<const name="WaitForProcessStartOnly" value="1">
9505	<desc>Only use the specified timeout value to wait for starting the guest process - the guest
9506	process itself then uses an infinite timeout.</desc>
9507	</const>
9508	<const name="IgnoreOrphanedProcesses" value="2">
9509	<desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
9510	</const>
9511	<const name="Hidden" value="4">
9512	<desc>Do not show the started process according to the guest OS guidelines.</desc>
9513	</const>
9514	<const name="NoProfile" value="8">
9515	<desc>Do not use the user's profile data when exeuting a process. Only available for Windows guests.</desc>
9516	</const>
9517	<const name="WaitForStdOut" value="16">
9518	<desc>The guest process waits until all data from stdout is read out.</desc>
9519	</const>
9520	<const name="WaitForStdErr" value="32">
9521	<desc>The guest process waits until all data from stderr is read out.</desc>
9522	</const>
9523	<const name="ExpandArguments" value="64">
9524	<desc>Expands environment variables in process arguments.</desc>
9525	</const>
9526	</enum>
9527
9528	<enum
9529	name="ProcessPriority"
9530	uuid="ee8cac50-e232-49fe-806b-d1214d9c2e49"
9531	>
9532	<desc>
9533	Process priorities.
9534	</desc>
9535
9536	<const name="Invalid" value="0">
9537	<desc>Invalid priority, do not use.</desc>
9538	</const>
9539	<const name="Default" value="1">
9540	<desc>Default process priority determined by the OS.</desc>
9541	</const>
9542	</enum>
9543
9544	<enum
9545	name="SymlinkType"
9546	uuid="37794668-f8f1-4714-98a5-6f8fa2ed0118"
9547	>
9548	<desc>
9549	Symbolic link types.
9550	</desc>
9551
9552	<const name="Unknown" value="0">
9553	<desc>It is not known what is being targeted.</desc>
9554	</const>
9555	<const name="Directory" value="1">
9556	<desc>The link targets a directory.</desc>
9557	</const>
9558	<const name="File" value="2">
9559	<desc>The link targets a file (or whatever else).</desc>
9560	</const>
9561	</enum>
9562
9563	<enum
9564	name="SymlinkReadFlag"
9565	uuid="b7fe2b9d-790e-4b25-8adf-1ca33026931f"
9566	>
9567	<desc>
9568	Symbolic link reading flags.
9569	</desc>
9570
9571	<const name="None" value="0">
9572	<desc>No flags set.</desc>
9573	</const>
9574	<const name="NoSymlinks" value="1">
9575	<desc>Don't allow symbolic links as part of the path.</desc>
9576	</const>
9577	</enum>
9578
9579	<enum
9580	name="ProcessStatus"
9581	uuid="4d52368f-5b48-4bfe-b486-acf89139b52f"
9582	>
9583	<desc>
9584	Process execution statuses.
9585	</desc>
9586
9587	<const name="Undefined" value="0">
9588	<desc>Process is in an undefined state.</desc>
9589	</const>
9590	<const name="Starting" value="10">
9591	<desc>Process is being started.</desc>
9592	</const>
9593	<const name="Started" value="100">
9594	<desc>Process has been started.</desc>
9595	</const>
9596	<const name="Paused" value="110">
9597	<desc>Process has been paused.</desc>
9598	</const>
9599	<const name="Terminating" value="480">
9600	<desc>Process is being terminated.</desc>
9601	</const>
9602	<const name="TerminatedNormally" value="500">
9603	<desc>Process terminated normally.</desc>
9604	</const>
9605	<const name="TerminatedSignal" value="510">
9606	<desc>Process terminated via signal.</desc>
9607	</const>
9608	<const name="TerminatedAbnormally" value="511">
9609	<desc>Process terminated abnormally.</desc>
9610	</const>
9611	<const name="TimedOutKilled" value="512">
9612	<desc>Process timed out and was killed.</desc>
9613	</const>
9614	<const name="TimedOutAbnormally" value="513">
9615	<desc>Process timed out and was not killed successfully.</desc>
9616	</const>
9617	<const name="Down" value="600">
9618	<desc>Service/OS is stopping, process was killed.</desc>
9619	</const>
9620	<const name="Error" value="800">
9621	<desc>Something went wrong.</desc>
9622	</const>
9623	</enum>
9624
9625	<enum
9626	name="ProcessInputStatus"
9627	uuid="a4a0ef9c-29cc-4805-9803-c8215ae9da6c"
9628	>
9629	<desc>
9630	Process input statuses.
9631	</desc>
9632
9633	<const name="Undefined" value="0">
9634	<desc>Undefined state.</desc>
9635	</const>
9636	<const name="Broken" value="1">
9637	<desc>Input pipe is broken.</desc>
9638	</const>
9639	<const name="Available" value="10">
9640	<desc>Input pipe became available for writing.</desc>
9641	</const>
9642	<const name="Written" value="50">
9643	<desc>Data has been successfully written.</desc>
9644	</const>
9645	<const name="Overflow" value="100">
9646	<desc>Too much input data supplied, data overflow.</desc>
9647	</const>
9648	</enum>
9649
9650	<enum
9651	name="FileStatus"
9652	uuid="8c86468b-b97b-4080-8914-e29f5b0abd2c"
9653	>
9654	<desc>
9655	File statuses.
9656	</desc>
9657
9658	<const name="Undefined" value="0">
9659	<desc>File is in an undefined state.</desc>
9660	</const>
9661	<const name="Opening" value="10">
9662	<desc>Guest file is opening.</desc>
9663	</const>
9664	<const name="Open" value="100">
9665	<desc>Guest file has been successfully opened.</desc>
9666	</const>
9667	<const name="Closing" value="150">
9668	<desc>Guest file closing.</desc>
9669	</const>
9670	<const name="Closed" value="200">
9671	<desc>Guest file has been closed.</desc>
9672	</const>
9673	<const name="Down" value="600">
9674	<desc>Service/OS is stopping, guest file was closed.</desc>
9675	</const>
9676	<const name="Error" value="800">
9677	<desc>Something went wrong.</desc>
9678	</const>
9679	</enum>
9680
9681	<enum
9682	name="FsObjType"
9683	uuid="a1ed437c-b3c3-4ca2-b19c-4239d658d5e8"
9684	>
9685	<desc>
9686	File system object type.
9687	</desc>
9688
9689	<const name="Undefined" value="0">
9690	<desc>Type is undefined / unknown.</desc>
9691	</const>
9692	<const name="FIFO" value="1">
9693	<desc>Named pipe.</desc>
9694	</const>
9695	<const name="DevChar" value="10">
9696	<desc>Character device.</desc>
9697	</const>
9698	<const name="DevBlock" value="11">
9699	<desc>Block device.</desc>
9700	</const>
9701	<const name="Directory" value="50">
9702	<desc>Directory.</desc>
9703	</const>
9704	<const name="File" value="80">
9705	<desc>File.</desc>
9706	</const>
9707	<const name="Symlink" value="100">
9708	<desc>Symlink.</desc>
9709	</const>
9710	<const name="Socket" value="200">
9711	<desc>Socket.</desc>
9712	</const>
9713	<const name="Whiteout" value="400">
9714	<desc>Whiteout.</desc>
9715	</const>
9716	</enum>
9717
9718	<enum
9719	name="DragAndDropAction"
9720	uuid="47f3b162-c107-4fcd-bfa7-54b8135c441e"
9721	>
9722	<desc>
9723	Possible actions within an Drag and Drop operation.
9724	</desc>
9725
9726	<const name="Ignore" value="0">
9727	<desc>Do nothing.</desc>
9728	</const>
9729
9730	<const name="Copy" value="1">
9731	<desc>Copy the item to the target.</desc>
9732	</const>
9733
9734	<const name="Move" value="2">
9735	<desc>Move the item to the target.</desc>
9736	</const>
9737
9738	<const name="Link" value="3">
9739	<desc>Link the item from within the target.</desc>
9740	</const>
9741	</enum>
9742
9743	<enum
9744	name="DirectoryOpenFlag"
9745	uuid="5138837a-8fd2-4194-a1b0-08f7bc3949d0"
9746	>
9747	<desc>
9748	Directory open flags.
9749	</desc>
9750	<const name="None" value="0">
9751	<desc>No flag set.</desc>
9752	</const>
9753	<const name="NoSymlinks" value="1">
9754	<desc>Don't allow symbolic links as part of the path.</desc>
9755	</const>
9756	</enum>
9757
9758	<interface
9759	name="IGuestSession" extends="$unknown"
9760	uuid="c8e8607b-5e67-4073-8f14-146515d0c1ff"
9761	wsmap="managed"
9762	>
9763	<desc>
9764	A guest session represents one impersonated user account on the guest, so
9765	every operation will use the same credentials specified when creating
9766	the session object via <link to="IGuest::createSession"/>.
9767
9768	There can be a maximum of 32 sessions at once per VM. Each session keeps
9769	track of its started guest processes, opened guest files or guest directories.
9770	To work on guest files or directories a guest session offers methods to open
9771	or create such objects (see <link to="IGuestSession::fileOpen"/> or
9772	<link to="IGuestSession::directoryOpen"/> for example).
9773
9774	When done with either of these objects, including the guest session itself,
9775	use the appropriate close() method to let the object do its cleanup work.
9776
9777	Every guest session has its own environment variable block which gets
9778	automatically applied when starting a new guest process via
9779	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
9780	To override (or unset) certain environment variables already set by the
9781	guest session, one can specify a per-process environment block when using
9782	one of the both above mentioned process creation calls.
9783	</desc>
9784
9785	<attribute name="user" type="wstring" readonly="yes">
9786	<desc>Returns the user name used by this session to impersonate
9787	users on the guest.
9788	</desc>
9789	</attribute>
9790	<attribute name="domain" type="wstring" readonly="yes">
9791	<desc>Returns the domain name used by this session to impersonate
9792	users on the guest.
9793	</desc>
9794	</attribute>
9795	<attribute name="name" type="wstring" readonly="yes">
9796	<desc>Returns the session's friendly name.</desc>
9797	</attribute>
9798	<attribute name="id" type="unsigned long" readonly="yes">
9799	<desc>Returns the internal session ID.</desc>
9800	</attribute>
9801	<attribute name="timeout" type="unsigned long">
9802	<desc>
9803	Returns the session timeout (in ms).
9804	<result name="E_NOTIMPL">
9805	The method is not implemented yet.
9806	</result>
9807	</desc>
9808	</attribute>
9809	<attribute name="status" type="GuestSessionStatus" readonly="yes">
9810	<desc>Returns the current session status.</desc>
9811	</attribute>
9812	<attribute name="environment" type="wstring" safearray="yes">
9813	<desc>
9814	Returns the current session environment.
9815	</desc>
9816	</attribute>
9817	<attribute name="processes" type="IGuestProcess" readonly="yes" safearray="yes">
9818	<desc>
9819	Returns all current guest processes.
9820	</desc>
9821	</attribute>
9822	<attribute name="directories" type="IGuestDirectory" readonly="yes" safearray="yes">
9823	<desc>
9824	Returns all currently opened guest directories.
9825	</desc>
9826	</attribute>
9827	<attribute name="files" type="IGuestFile" readonly="yes" safearray="yes">
9828	<desc>
9829	Returns all currently opened guest files.
9830	</desc>
9831	</attribute>
9832	<attribute name="eventSource" type="IEventSource" readonly="yes">
9833	<desc>
9834	Event source for guest session events.
9835	</desc>
9836	</attribute>
9837
9838	<method name="close">
9839	<desc>
9840	Closes this session. All opened guest directories, files and
9841	processes which are not referenced by clients anymore will be
9842	uninitialized.
9843	</desc>
9844	</method>
9845
9846	<method name="copyFrom">
9847	<desc>
9848	Copies a file from guest to the host.
9849
9850	<result name="VBOX_E_IPRT_ERROR">
9851	Error starting the copy operation.
9852	</result>
9853	</desc>
9854	<param name="source" type="wstring" dir="in">
9855	<desc>Source file on the guest to copy to the host.</desc>
9856	</param>
9857	<param name="dest" type="wstring" dir="in">
9858	<desc>Destination file name on the host.</desc>
9859	</param>
9860	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9861	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9862	</param>
9863	<param name="progress" type="IProgress" dir="return">
9864	<desc>Progress object to track the operation completion.</desc>
9865	</param>
9866	</method>
9867
9868	<method name="copyTo">
9869	<desc>
9870	Copies a file from host to the guest.
9871
9872	<result name="VBOX_E_IPRT_ERROR">
9873	Error starting the copy operation.
9874	</result>
9875	</desc>
9876	<param name="source" type="wstring" dir="in">
9877	<desc>Source file on the host to copy to the guest.</desc>
9878	</param>
9879	<param name="dest" type="wstring" dir="in">
9880	<desc>Destination file name on the guest.</desc>
9881	</param>
9882	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9883	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9884	</param>
9885	<param name="progress" type="IProgress" dir="return">
9886	<desc>Progress object to track the operation completion.</desc>
9887	</param>
9888	</method>
9889
9890	<method name="directoryCreate">
9891	<desc>
9892	Create a directory on the guest.
9893
9894	<result name="VBOX_E_IPRT_ERROR">
9895	Error while creating the directory.
9896	</result>
9897	</desc>
9898	<param name="path" type="wstring" dir="in">
9899	<desc>Full path of directory to create.</desc>
9900	</param>
9901	<param name="mode" type="unsigned long" dir="in">
9902	<desc>File creation mode.</desc>
9903	</param>
9904	<param name="flags" type="DirectoryCreateFlag" dir="in" safearray="yes">
9905	<desc>Creation flags; see <link to="DirectoryCreateFlag"/> for more information.</desc>
9906	</param>
9907	</method>
9908
9909	<method name="directoryCreateTemp">
9910	<desc>
9911	Create a temporary directory on the guest.
9912
9913	<result name="VBOX_E_NOT_SUPPORTED">
9914	The operation is not possible as requested on this particular
9915	guest type.
9916	</result>
9917	<result name="E_INVALIDARG">
9918	Invalid argument. This includes an incorrectly formatted template,
9919	or a non-absolute path.
9920	</result>
9921	<result name="VBOX_E_IPRT_ERROR">
9922	The temporary directory could not be created. Possible reasons
9923	include a non-existing path or an insecure path when the secure
9924	option was requested.
9925	</result>
9926	</desc>
9927	<param name="templateName" type="wstring" dir="in">
9928	<desc>Template for the name of the directory to create. This must
9929	contain at least one 'X' character. The first group of consecutive
9930	'X' characters in the template will be replaced by a random
9931	alphanumeric string to produce a unique name.</desc>
9932	</param>
9933	<param name="mode" type="unsigned long" dir="in">
9934	<desc>The mode of the directory to create. Use 0700 unless there are
9935	reasons not to. This parameter is ignored if "secure" is specified.
9936	</desc>
9937	</param>
9938	<param name="path" type="wstring" dir="in">
9939	<desc>The absolute path to create the temporary directory in.</desc>
9940	</param>
9941	<param name="secure" type="boolean" dir="in">
9942	<desc>Whether to fail if the directory can not be securely created.
9943	Currently this means that another unprivileged user cannot
9944	manipulate the path specified or remove the temporary directory
9945	after it has been created. Also causes the mode specified to be
9946	ignored. May not be supported on all guest types.</desc>
9947	</param>
9948	<param name="directory" type="wstring" dir="return">
9949	<desc>On success this will contain the name of the directory created
9950	with full path.</desc>
9951	</param>
9952	</method>
9953
9954	<method name="directoryExists">
9955	<desc>
9956	Checks whether a directory exists on the guest or not.
9957
9958	<result name="VBOX_E_IPRT_ERROR">
9959	Error while checking existence of the directory specified.
9960	</result>
9961	</desc>
9962	<param name="path" type="wstring" dir="in">
9963	<desc>Directory to check existence for.</desc>
9964	</param>
9965	<param name="exists" type="boolean" dir="return">
9966	<desc>Returns @c true if the directory exists, @c false if not.</desc>
9967	</param>
9968	</method>
9969
9970	<method name="directoryOpen">
9971	<desc>
9972	Opens a directory and creates a <link to="IGuestDirectory"/> object that
9973	can be used for further operations.
9974
9975	<result name="VBOX_E_OBJECT_NOT_FOUND">
9976	Directory to open was not found.
9977	</result>
9978	<result name="VBOX_E_IPRT_ERROR">
9979	Error while opening the directory.
9980	</result>
9981	</desc>
9982	<param name="path" type="wstring" dir="in">
9983	<desc>Full path to file to open.</desc>
9984	</param>
9985	<param name="filter" type="wstring" dir="in">
9986	<desc>Open filter to apply. This can include wildcards like ? and *.</desc>
9987	</param>
9988	<param name="flags" type="DirectoryOpenFlag" dir="in" safearray="yes">
9989	<desc>Open flags; see <link to="DirectoryOpenFlag"/> for more information.</desc>
9990	</param>
9991	<param name="directory" type="IGuestDirectory" dir="return">
9992	<desc><link to="IGuestDirectory"/> object containing the opened directory.</desc>
9993	</param>
9994	</method>
9995
9996	<method name="directoryQueryInfo">
9997	<desc>
9998	Queries information of a directory on the guest.
9999
10000	<result name="VBOX_E_OBJECT_NOT_FOUND">
10001	Directory to query information for was not found.
10002	</result>
10003	<result name="VBOX_E_IPRT_ERROR">
10004	Error querying information.
10005	</result>
10006	</desc>
10007	<param name="path" type="wstring" dir="in">
10008	<desc>Directory to query information for.</desc>
10009	</param>
10010	<param name="info" type="IGuestFsObjInfo" dir="return">
10011	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10012	</param>
10013	</method>
10014
10015	<method name="directoryRemove">
10016	<desc>
10017	Removes a guest directory if not empty.
10018
10019	<result name="E_NOTIMPL">
10020	The method is not implemented yet.
10021	</result>
10022	</desc>
10023	<param name="path" type="wstring" dir="in">
10024	<desc>Full path of directory to remove.</desc>
10025	</param>
10026	</method>
10027
10028	<method name="directoryRemoveRecursive">
10029	<desc>
10030	Removes a guest directory recursively.
10031
10032	<result name="E_NOTIMPL">
10033	The method is not implemented yet.
10034	</result>
10035	</desc>
10036	<param name="path" type="wstring" dir="in">
10037	<desc>Full path of directory to remove recursively.</desc>
10038	</param>
10039	<param name="flags" type="DirectoryRemoveRecFlag" dir="in" safearray="yes">
10040	<desc>Remove flags; see <link to="DirectoryRemoveRecFlag"/> for more information.</desc>
10041	</param>
10042	<param name="progress" type="IProgress" dir="return">
10043	<desc>Progress object to track the operation completion.</desc>
10044	</param>
10045	</method>
10046
10047	<method name="directoryRename">
10048	<desc>
10049	Renames a directory on the guest.
10050
10051	<result name="E_NOTIMPL">
10052	The method is not implemented yet.
10053	</result>
10054	</desc>
10055	<param name="source" type="wstring" dir="in">
10056	<desc>Source directory to rename.</desc>
10057	</param>
10058	<param name="dest" type="wstring" dir="in">
10059	<desc>Destination directory to rename the source to.</desc>
10060	</param>
10061	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10062	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10063	</param>
10064	</method>
10065
10066	<method name="directorySetACL">
10067	<desc>
10068	Sets the ACL (Access Control List) of a guest directory.
10069
10070	<result name="E_NOTIMPL">
10071	The method is not implemented yet.
10072	</result>
10073	</desc>
10074	<param name="path" type="wstring" dir="in">
10075	<desc>Full path of directory to set the ACL for.</desc>
10076	</param>
10077	<param name="acl" type="wstring" dir="in">
10078	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10079	</param>
10080	</method>
10081
10082	<method name="environmentClear">
10083	<desc>
10084	Clears (deletes) all session environment variables.
10085
10086	<result name="VBOX_E_IPRT_ERROR">
10087	Error while clearing the session environment variables.
10088	</result>
10089	</desc>
10090	</method>
10091
10092	<method name="environmentGet">
10093	<desc>
10094	Gets the value of a session environment variable.
10095
10096	<result name="VBOX_E_IPRT_ERROR">
10097	Error while getting the value of the session environment variable.
10098	</result>
10099	</desc>
10100	<param name="name" type="wstring" dir="in">
10101	<desc>Name of session environment variable to get the value for.</desc>
10102	</param>
10103	<param name="value" type="wstring" dir="return">
10104	<desc>
10105	Value of the session environment variable specified. If this variable
10106	does not exist and empty value will be returned.
10107	</desc>
10108	</param>
10109	</method>
10110
10111	<method name="environmentSet">
10112	<desc>
10113	Sets a session environment variable.
10114
10115	<result name="VBOX_E_IPRT_ERROR">
10116	Error while setting the session environment variable.
10117	</result>
10118	</desc>
10119	<param name="name" type="wstring" dir="in">
10120	<desc>Name of session environment variable to set.</desc>
10121	</param>
10122	<param name="value" type="wstring" dir="in">
10123	<desc>Value to set the session environment variable to.</desc>
10124	</param>
10125	</method>
10126
10127	<method name="environmentUnset">
10128	<desc>
10129	Unsets session environment variable.
10130
10131	<result name="VBOX_E_IPRT_ERROR">
10132	Error while unsetting the session environment variable.
10133	</result>
10134	</desc>
10135	<param name="name" type="wstring" dir="in">
10136	<desc>Name of session environment variable to unset (clear).</desc>
10137	</param>
10138	</method>
10139
10140	<method name="fileCreateTemp">
10141	<desc>
10142	Creates a temporary file on the guest.
10143
10144	<result name="VBOX_E_NOT_SUPPORTED">
10145	The operation is not possible as requested on this particular
10146	guest type.
10147	</result>
10148	<result name="E_INVALIDARG">
10149	Invalid argument. This includes an incorrectly formatted template,
10150	or a non-absolute path.
10151	</result>
10152	<result name="VBOX_E_IPRT_ERROR">
10153	The temporary file could not be created. Possible reasons include
10154	a non-existing path or an insecure path when the secure
10155	option was requested.
10156	</result>
10157	</desc>
10158	<param name="templateName" type="wstring" dir="in">
10159	<desc>Template for the name of the file to create. This must contain
10160	at least one 'X' character. The first group of consecutive 'X'
10161	characters in the template will be replaced by a random
10162	alphanumeric string to produce a unique name.
10163	</desc>
10164	</param>
10165	<param name="mode" type="unsigned long" dir="in">
10166	<desc>The mode of the file to create. Use 0700 unless there are
10167	reasons not to. This parameter is ignored if "secure" is specified.
10168	</desc>
10169	</param>
10170	<param name="path" type="wstring" dir="in">
10171	<desc>The absolute path to create the temporary file in.</desc>
10172	</param>
10173	<param name="secure" type="boolean" dir="in">
10174	<desc>Whether to fail if the file can not be securely created.
10175	Currently this means that another unprivileged user cannot
10176	manipulate the path specified or remove the temporary file after
10177	it has been created. Also causes the mode specified to be ignored.
10178	May not be supported on all guest types.</desc>
10179	</param>
10180	<param name="file" type="IGuestFile" dir="return">
10181	<desc>On success this will contain an open file object for the new
10182	temporary file.
10183	</desc>
10184	</param>
10185	</method>
10186
10187	<method name="fileExists">
10188	<desc>
10189	Checks whether a file exists on the guest or not.
10190
10191	<result name="VBOX_E_IPRT_ERROR">
10192	Error while checking existence of the file specified.
10193	</result>
10194	</desc>
10195	<param name="path" type="wstring" dir="in">
10196	<desc>File to check existence for.</desc>
10197	</param>
10198	<param name="exists" type="boolean" dir="return">
10199	<desc>Returns @c true if the file exists, @c false if not.</desc>
10200	</param>
10201	</method>
10202
10203	<method name="fileRemove">
10204	<desc>
10205	Removes a single file on the guest.
10206
10207	<result name="VBOX_E_OBJECT_NOT_FOUND">
10208	File to remove was not found.
10209	</result>
10210	<result name="VBOX_E_IPRT_ERROR">
10211	Error while removing the file.
10212	</result>
10213	</desc>
10214	<param name="path" type="wstring" dir="in">
10215	<desc>Path to the file to remove.</desc>
10216	</param>
10217	</method>
10218
10219	<method name="fileOpen">
10220	<desc>
10221	Opens a file and creates a <link to="IGuestFile"/> object that
10222	can be used for further operations.
10223
10224	<result name="VBOX_E_OBJECT_NOT_FOUND">
10225	File to open was not found.
10226	</result>
10227	<result name="VBOX_E_IPRT_ERROR">
10228	Error while opening the file.
10229	</result>
10230	</desc>
10231	<param name="path" type="wstring" dir="in">
10232	<desc>Full path to file to open.</desc>
10233	</param>
10234	<param name="openMode" type="wstring" dir="in">
10235	<desc>The file open mode.</desc>
10236	</param>
10237	<param name="disposition" type="wstring" dir="in">
10238	<desc>The file disposition.</desc>
10239	</param>
10240	<param name="creationMode" type="unsigned long" dir="in">
10241	<desc>The file creation mode.</desc>
10242	</param>
10243	<param name="offset" type="long long" dir="in">
10244	<desc>The initial read/write offset.</desc>
10245	</param>
10246	<param name="file" type="IGuestFile" dir="return">
10247	<desc><link to="IGuestFile"/> object representing the opened file.</desc>
10248	</param>
10249	</method>
10250
10251	<method name="fileQueryInfo">
10252	<desc>
10253	Queries information of a file on the guest.
10254
10255	<result name="VBOX_E_OBJECT_NOT_FOUND">
10256	File to query information for was not found.
10257	</result>
10258	<result name="VBOX_E_IPRT_ERROR">
10259	Error querying information.
10260	</result>
10261	</desc>
10262	<param name="path" type="wstring" dir="in">
10263	<desc>File to query information for.</desc>
10264	</param>
10265	<param name="info" type="IGuestFsObjInfo" dir="return">
10266	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10267	</param>
10268	</method>
10269
10270	<method name="fileQuerySize">
10271	<desc>
10272	Queries the size of a file on the guest.
10273
10274	<result name="VBOX_E_OBJECT_NOT_FOUND">
10275	File to rename was not found.
10276	</result>
10277	<result name="VBOX_E_IPRT_ERROR">
10278	Error querying file size.
10279	</result>
10280	</desc>
10281	<param name="path" type="wstring" dir="in">
10282	<desc>File to query the size for.</desc>
10283	</param>
10284	<param name="size" type="long long" dir="return">
10285	<desc>Queried file size.</desc>
10286	</param>
10287	</method>
10288
10289	<method name="fileRename">
10290	<desc>
10291	Renames a file on the guest.
10292
10293	<result name="E_NOTIMPL">
10294	The method is not implemented yet.
10295	</result>
10296	</desc>
10297	<param name="source" type="wstring" dir="in">
10298	<desc>Source file to rename.</desc>
10299	</param>
10300	<param name="dest" type="wstring" dir="in">
10301	<desc>Destination file to rename the source to.</desc>
10302	</param>
10303	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10304	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10305	</param>
10306	</method>
10307
10308	<method name="fileSetACL">
10309	<desc>
10310	Sets the ACL (Access Control List) of a file on the guest.
10311
10312	<result name="E_NOTIMPL">
10313	The method is not implemented yet.
10314	</result>
10315	</desc>
10316	<param name="file" type="wstring" dir="in">
10317	<desc>Full path of file to set the ACL for.</desc>
10318	</param>
10319	<param name="acl" type="wstring" dir="in">
10320	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10321	</param>
10322	</method>
10323
10324	<method name="processCreate">
10325	<desc>
10326	Creates a new process running on the guest. The new process will be
10327	started asynchronously, meaning on return of this function it is not
10328	guaranteed that the guest process is in a started state. To wait for
10329	successful startup, use the <link to="IProcess::waitFor"/> call.
10330
10331	<note>
10332	Starting at VirtualBox 4.2 guest process execution by default is limited
10333	to serve up to 255 guest processes at a time. If all 255 guest processes
10334	are still active and running, creating a new guest process will result in an
10335	appropriate error message.
10336
10337	If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr
10338	is / are set, the guest process will not exit until all data from the specified
10339	stream(s) is / are read out.
10340
10341	To raise or lower the guest process execution limit, either the guest property
10342	"/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService'
10343	command line by specifying "--control-procs-max-kept" needs to be modified.
10344	A restart of the guest OS is required afterwards. To serve unlimited guest
10345	processes, a value of "0" needs to be set (not recommended).
10346	</note>
10347
10348	<result name="VBOX_E_IPRT_ERROR">
10349	Error creating guest process.
10350	</result>
10351	</desc>
10352	<param name="command" type="wstring" dir="in">
10353	<desc>
10354	Full path name of the command to execute on the guest; the
10355	commands has to exists in the guest VM in order to be executed.
10356	</desc>
10357	</param>
10358	<param name="arguments" type="wstring" dir="in" safearray="yes">
10359	<desc>Array of arguments passed to the execution command.</desc>
10360	</param>
10361	<param name="environment" type="wstring" dir="in" safearray="yes">
10362	<desc>
10363	<para>Environment variables that can be set while the command is being
10364	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10365	variable just set its name ("NAME") without a value.</para>
10366	<para>This parameter can be used to override environment variables set by
10367	the guest session, which will be applied to the newly started process
10368	in any case.</para>
10369	</desc>
10370	</param>
10371	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10372	<desc>
10373	Process creation flags;
10374	see <link to="ProcessCreateFlag"/> for more information.
10375	</desc>
10376	</param>
10377	<param name="timeoutMS" type="unsigned long" dir="in">
10378	<desc>
10379	Timeout (in ms) for limiting the guest process' running time.
10380	Pass 0 for an infinite timeout. On timeout the guest process will be
10381	killed and its status will be put to an appropriate value. See
10382	<link to="ProcessStatus"/> for more information.
10383	</desc>
10384	</param>
10385	<param name="guestProcess" type="IGuestProcess" dir="return">
10386	<desc>Guest process object of the newly created process.</desc>
10387	</param>
10388	</method>
10389
10390	<method name="processCreateEx">
10391	<desc>
10392	<para>Creates a new process running on the guest. Extended version for
10393	also setting the process priority and affinity.</para>
10394
10395	<para>See <link to="IGuestSession::processCreate"/> for more
10396	information.</para>
10397	</desc>
10398	<param name="command" type="wstring" dir="in">
10399	<desc>
10400	Full path name of the command to execute on the guest; the
10401	commands has to exists in the guest VM in order to be executed.
10402	</desc>
10403	</param>
10404	<param name="arguments" type="wstring" dir="in" safearray="yes">
10405	<desc>Array of arguments passed to the execution command.</desc>
10406	</param>
10407	<param name="environment" type="wstring" dir="in" safearray="yes">
10408	<desc>
10409	<para>Environment variables that can be set while the command is being
10410	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10411	variable just set its name ("NAME") without a value.</para>
10412	<para>This parameter can be used to override environment variables set by
10413	the guest session, which will be applied to the newly started process
10414	in any case.</para>
10415	</desc>
10416	</param>
10417	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10418	<desc>
10419	Process creation flags;
10420	see <link to="ProcessCreateFlag"/> for more information.
10421	</desc>
10422	</param>
10423	<param name="timeoutMS" type="unsigned long" dir="in">
10424	<desc>
10425	Timeout (in ms) for limiting the guest process' running time.
10426	Pass 0 for an infinite timeout. On timeout the guest process will be
10427	killed and its status will be put to an appropriate value. See
10428	<link to="ProcessStatus"/> for more information.
10429	</desc>
10430	</param>
10431	<param name="priority" type="ProcessPriority" dir="in">
10432	<desc>
10433	Process priority to use for execution;
10434	see see <link to="ProcessPriority"/> for more information.</desc>
10435	</param>
10436	<param name="affinity" type="long" dir="in" safearray="yes">
10437	<desc>
10438	Process affinity to use for execution. This parameter
10439	is not implemented yet.
10440	</desc>
10441	</param>
10442	<param name="guestProcess" type="IGuestProcess" dir="return">
10443	<desc>Guest process object of the newly created process.</desc>
10444	</param>
10445	</method>
10446
10447	<method name="processGet">
10448	<desc>
10449	Gets a certain guest process by its process ID (PID).
10450	</desc>
10451	<param name="pid" type="unsigned long" dir="in">
10452	<desc>Process ID (PID) to get guest process for.</desc>
10453	</param>
10454	<param name="guestProcess" type="IGuestProcess" dir="return">
10455	<desc>Guest process of specified process ID (PID).</desc>
10456	</param>
10457	</method>
10458
10459	<method name="symlinkCreate">
10460	<desc>
10461	Creates a symbolic link on the guest.
10462
10463	<result name="E_NOTIMPL">
10464	The method is not implemented yet.
10465	</result>
10466	</desc>
10467	<param name="source" type="wstring" dir="in">
10468	<desc>The name of the symbolic link.</desc>
10469	</param>
10470	<param name="target" type="wstring" dir="in">
10471	<desc>The path to the symbolic link target.</desc>
10472	</param>
10473	<param name="type" type="SymlinkType" dir="in">
10474	<desc>
10475	The symbolic link type;
10476	see <link to="SymlinkReadFlag"/> for more information.
10477	</desc>
10478	</param>
10479	</method>
10480
10481	<method name="symlinkExists">
10482	<desc>
10483	Checks whether a symbolic link exists on the guest or not.
10484
10485	<result name="E_NOTIMPL">
10486	The method is not implemented yet.
10487	</result>
10488	</desc>
10489	<param name="symlink" type="wstring" dir="in">
10490	<desc>Symbolic link to check existence for.</desc>
10491	</param>
10492	<param name="exists" type="boolean" dir="return">
10493	<desc>Returns @c true if the symbolic link exists, @c false if not.</desc>
10494	</param>
10495	</method>
10496
10497	<method name="symlinkRead">
10498	<desc>
10499	Reads a symbolic link on the guest.
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>Full path to symbolic link to read.</desc>
10507	</param>
10508	<param name="flags" type="SymlinkReadFlag" dir="in" safearray="yes">
10509	<desc>
10510	Read flags; see <link to="SymlinkReadFlag"/> for more information.
10511	</desc>
10512	</param>
10513	<param name="target" type="wstring" dir="return">
10514	<desc>
10515	Target of the symbolic link pointing to, if found.
10516	</desc>
10517	</param>
10518	</method>
10519
10520	<method name="symlinkRemoveDirectory">
10521	<desc>
10522	Removes a symbolic link on the guest if it's a directory.
10523
10524	<result name="E_NOTIMPL">
10525	The method is not implemented yet.
10526	</result>
10527	</desc>
10528	<param name="path" type="wstring" dir="in">
10529	<desc>Symbolic link to remove.</desc>
10530	</param>
10531	</method>
10532
10533	<method name="symlinkRemoveFile">
10534	<desc>
10535	Removes a symbolic link on the guest if it's a file.
10536
10537	<result name="E_NOTIMPL">
10538	The method is not implemented yet.
10539	</result>
10540	</desc>
10541	<param name="file" type="wstring" dir="in">
10542	<desc>Symbolic link to remove.</desc>
10543	</param>
10544	</method>
10545
10546	<method name="waitFor">
10547	<desc>
10548	Waits for one more events to happen.
10549	</desc>
10550	<param name="waitFor" type="unsigned long" dir="in">
10551	<desc>
10552	Specifies what to wait for;
10553	see <link to="GuestSessionWaitForFlag"/> for more information.
10554	</desc>
10555	</param>
10556	<param name="timeoutMS" type="unsigned long" dir="in">
10557	<desc>
10558	Timeout (in ms) to wait for the operation to complete.
10559	Pass 0 for an infinite timeout.
10560	</desc>
10561	</param>
10562	<param name="reason" type="GuestSessionWaitResult" dir="return">
10563	<desc>
10564	The overall wait result;
10565	see <link to="GuestSessionWaitResult"/> for more information.
10566	</desc>
10567	</param>
10568	</method>
10569
10570	<method name="waitForArray">
10571	<desc>
10572	Waits for one more events to happen.
10573	Scriptable version of <link to="#waitFor" />.
10574	</desc>
10575	<param name="waitFor" type="GuestSessionWaitForFlag" dir="in" safearray="yes">
10576	<desc>
10577	Specifies what to wait for;
10578	see <link to="GuestSessionWaitForFlag"/> for more information.
10579	</desc>
10580	</param>
10581	<param name="timeoutMS" type="unsigned long" dir="in">
10582	<desc>
10583	Timeout (in ms) to wait for the operation to complete.
10584	Pass 0 for an infinite timeout.
10585	</desc>
10586	</param>
10587	<param name="reason" type="GuestSessionWaitResult" dir="return">
10588	<desc>
10589	The overall wait result;
10590	see <link to="GuestSessionWaitResult"/> for more information.
10591	</desc>
10592	</param>
10593	</method>
10594
10595	</interface>
10596
10597	<interface
10598	name="IProcess" extends="$unknown"
10599	uuid="5a4fe06d-8cb1-40ff-ac9e-9676e32f706e"
10600	wsmap="managed"
10601	>
10602	<desc>
10603	Abstract parent interface for processes handled by VirtualBox.
10604	</desc>
10605
10606	<attribute name="arguments" type="wstring" readonly="yes" safearray="yes">
10607	<desc>
10608	The arguments this process is using for execution.
10609	</desc>
10610	</attribute>
10611	<attribute name="environment" type="wstring" readonly="yes" safearray="yes">
10612	<desc>
10613	The environment block this process is using during execution.
10614	</desc>
10615	</attribute>
10616	<attribute name="eventSource" type="IEventSource" readonly="yes">
10617	<desc>
10618	Event source for VirtualBox events.
10619	</desc>
10620	</attribute>
10621	<attribute name="executablePath" type="wstring" readonly="yes">
10622	<desc>Full path of the actual executable image.</desc>
10623	</attribute>
10624	<attribute name="exitCode" type="long" readonly="yes">
10625	<desc>
10626	The exit code. Only available when the process has been
10627	terminated normally.
10628	</desc>
10629	</attribute>
10630	<attribute name="name" type="wstring" readonly="yes">
10631	<desc>
10632	The friendly name of this process.
10633	</desc>
10634	</attribute>
10635	<attribute name="PID" type="unsigned long" readonly="yes">
10636	<desc>
10637	The process ID (PID).
10638	</desc>
10639	</attribute>
10640	<attribute name="status" type="ProcessStatus" readonly="yes">
10641	<desc>
10642	The current process status; see <link to="ProcessStatus"/>
10643	for more information.
10644	</desc>
10645	</attribute>
10646
10647	<method name="waitFor">
10648	<desc>
10649	Waits for one more events to happen.
10650	</desc>
10651	<param name="waitFor" type="unsigned long" dir="in">
10652	<desc>
10653	Specifies what to wait for;
10654	see <link to="ProcessWaitForFlag"/> for more information.
10655	</desc>
10656	</param>
10657	<param name="timeoutMS" type="unsigned long" dir="in">
10658	<desc>
10659	Timeout (in ms) to wait for the operation to complete.
10660	Pass 0 for an infinite timeout.
10661	</desc>
10662	</param>
10663	<param name="reason" type="ProcessWaitResult" dir="return">
10664	<desc>
10665	The overall wait result;
10666	see <link to="ProcessWaitResult"/> for more information.
10667	</desc>
10668	</param>
10669	</method>
10670
10671	<method name="waitForArray">
10672	<desc>
10673	Waits for one more events to happen.
10674	Scriptable version of <link to="#waitFor" />.
10675	</desc>
10676	<param name="waitFor" type="ProcessWaitForFlag" dir="in" safearray="yes">
10677	<desc>
10678	Specifies what to wait for;
10679	see <link to="ProcessWaitForFlag"/> for more information.
10680	</desc>
10681	</param>
10682	<param name="timeoutMS" type="unsigned long" dir="in">
10683	<desc>
10684	Timeout (in ms) to wait for the operation to complete.
10685	Pass 0 for an infinite timeout.
10686	</desc>
10687	</param>
10688	<param name="reason" type="ProcessWaitResult" dir="return">
10689	<desc>
10690	The overall wait result;
10691	see <link to="ProcessWaitResult"/> for more information.
10692	</desc>
10693	</param>
10694	</method>
10695
10696	<method name="read">
10697	<desc>
10698	Reads data from a running process.
10699	</desc>
10700	<param name="handle" type="unsigned long" dir="in">
10701	<desc>Handle to read from. Usually 0 is stdin.</desc>
10702	</param>
10703	<param name="toRead" type="unsigned long" dir="in">
10704	<desc>Number of bytes to read.</desc>
10705	</param>
10706	<param name="timeoutMS" type="unsigned long" dir="in">
10707	<desc>
10708	Timeout (in ms) to wait for the operation to complete.
10709	Pass 0 for an infinite timeout.
10710	</desc>
10711	</param>
10712	<param name="data" type="octet" dir="return" safearray="yes">
10713	<desc>Array of data read.</desc>
10714	</param>
10715	</method>
10716
10717	<method name="write">
10718	<desc>
10719	Writes data to a running process.
10720	</desc>
10721	<param name="handle" type="unsigned long" dir="in">
10722	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10723	</param>
10724	<param name="flags" type="unsigned long" dir="in">
10725	<desc>
10726	A combination of <link to="ProcessInputFlag"/> flags.
10727	</desc>
10728	</param>
10729	<param name="data" type="octet" dir="in" safearray="yes">
10730	<desc>
10731	Array of bytes to write. The size of the array also specifies
10732	how much to write.
10733	</desc>
10734	</param>
10735	<param name="timeoutMS" type="unsigned long" dir="in">
10736	<desc>
10737	Timeout (in ms) to wait for the operation to complete.
10738	Pass 0 for an infinite timeout.
10739	</desc>
10740	</param>
10741	<param name="written" type="unsigned long" dir="return">
10742	<desc>How much bytes were written.</desc>
10743	</param>
10744	</method>
10745
10746	<method name="writeArray">
10747	<desc>
10748	Writes data to a running process.
10749	Scriptable version of <link to="#write" />.
10750	</desc>
10751	<param name="handle" type="unsigned long" dir="in">
10752	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10753	</param>
10754	<param name="flags" type="ProcessInputFlag" dir="in" safearray="yes">
10755	<desc>
10756	A combination of <link to="ProcessInputFlag"/> flags.
10757	</desc>
10758	</param>
10759	<param name="data" type="octet" dir="in" safearray="yes">
10760	<desc>
10761	Array of bytes to write. The size of the array also specifies
10762	how much to write.
10763	</desc>
10764	</param>
10765	<param name="timeoutMS" type="unsigned long" dir="in">
10766	<desc>
10767	Timeout (in ms) to wait for the operation to complete.
10768	Pass 0 for an infinite timeout.
10769	</desc>
10770	</param>
10771	<param name="written" type="unsigned long" dir="return">
10772	<desc>How much bytes were written.</desc>
10773	</param>
10774	</method>
10775
10776	<method name="terminate">
10777	<desc>
10778	Terminates (kills) a running process.
10779	</desc>
10780	</method>
10781	</interface>
10782
10783	<interface
10784	name="IGuestProcess" extends="IProcess"
10785	uuid="dfa39a36-5d43-4840-a025-67ea956b3111"
10786	wsmap="managed"
10787	>
10788	<desc>
10789	Implementation of the <link to="IProcess" /> object
10790	for processes on the guest.
10791	</desc>
10792	</interface>
10793
10794	<interface
10795	name="IDirectory" extends="$unknown"
10796	uuid="1b70dd03-26d7-483a-8877-89bbb0f87b70"
10797	wsmap="managed"
10798	>
10799	<desc>
10800	Abstract parent interface for directories handled by VirtualBox.
10801	</desc>
10802
10803	<attribute name="directoryName" type="wstring" readonly="yes">
10804	<desc>
10805	Full path of directory.
10806	</desc>
10807	</attribute>
10808
10809	<attribute name="filter" type="wstring" readonly="yes">
10810	<desc>
10811	The open filter.
10812	</desc>
10813	</attribute>
10814
10815	<method name="close">
10816	<desc>
10817	Closes this directory. After closing operations like reading the next
10818	directory entry will not be possible anymore.
10819	</desc>
10820	</method>
10821
10822	<method name="read">
10823	<desc>
10824	Reads the next directory entry of this directory.
10825	<result name="VBOX_E_OBJECT_NOT_FOUND">
10826	No more directory entries to read.
10827	</result>
10828	</desc>
10829	<param name="objInfo" type="IFsObjInfo" dir="return">
10830	<desc>Object information of the current directory entry read. Also see
10831	<link to="IFsObjInfo"/>.</desc>
10832	</param>
10833	</method>
10834	</interface>
10835
10836	<interface
10837	name="IGuestDirectory" extends="IDirectory"
10838	uuid="af4a8ce0-0725-42b7-8826-46e3c7ba7357"
10839	wsmap="managed"
10840	>
10841	<desc>
10842	Implementation of the <link to="IDirectory" /> object
10843	for directories on the guest.
10844	</desc>
10845	</interface>
10846
10847	<interface
10848	name="IFile" extends="$unknown"
10849	uuid="ceb895d7-8b2d-4a39-8f7c-7d2270f341d5"
10850	wsmap="managed"
10851	>
10852	<desc>
10853	Abstract parent interface for files handled by VirtualBox.
10854	</desc>
10855	<attribute name="creationMode" type="unsigned long" readonly="yes">
10856	<desc>
10857	The creation mode.
10858	</desc>
10859	</attribute>
10860	<attribute name="disposition" type="unsigned long" readonly="yes">
10861	<desc>
10862	The disposition mode.
10863	</desc>
10864	</attribute>
10865	<attribute name="eventSource" type="IEventSource" readonly="yes">
10866	<desc>
10867	Event source for guest session events.
10868	</desc>
10869	</attribute>
10870	<attribute name="fileName" type="wstring" readonly="yes">
10871	<desc>
10872	Full path of the actual file name of this file.
10873	</desc>
10874	</attribute>
10875	<attribute name="initialSize" type="long long" readonly="yes">
10876	<desc>
10877	The initial size in bytes when opened.
10878	</desc>
10879	</attribute>
10880	<attribute name="openMode" type="unsigned long" readonly="yes">
10881	<desc>
10882	The open mode.
10883	</desc>
10884	</attribute>
10885	<attribute name="offset" type="long long" readonly="yes">
10886	<desc>
10887	Current read/write offset in bytes.
10888	</desc>
10889	</attribute>
10890	<attribute name="status" type="FileStatus" readonly="yes">
10891	<desc>
10892	Current file status.
10893	</desc>
10894	</attribute>
10895
10896	<method name="close">
10897	<desc>
10898	Closes this file. After closing operations like reading data,
10899	writing data or querying information will not be possible anymore.
10900	</desc>
10901	</method>
10902
10903	<method name="queryInfo">
10904	<desc>
10905	Queries information about this file.
10906
10907	<result name="E_NOTIMPL">
10908	The method is not implemented yet.
10909	</result>
10910	</desc>
10911	<param name="objInfo" type="IFsObjInfo" dir="return">
10912	<desc>Object information of this file. Also see
10913	<link to="IFsObjInfo"/>.</desc>
10914	</param>
10915	</method>
10916
10917	<method name="read">
10918	<desc>
10919	Reads data from this file.
10920
10921	<result name="E_NOTIMPL">
10922	The method is not implemented yet.
10923	</result>
10924	</desc>
10925	<param name="toRead" type="unsigned long" dir="in">
10926	<desc>Number of bytes to read.</desc>
10927	</param>
10928	<param name="timeoutMS" type="unsigned long" dir="in">
10929	<desc>
10930	Timeout (in ms) to wait for the operation to complete.
10931	Pass 0 for an infinite timeout.
10932	</desc>
10933	</param>
10934	<param name="data" type="octet" dir="return" safearray="yes">
10935	<desc>Array of data read.</desc>
10936	</param>
10937	</method>
10938
10939	<method name="readAt">
10940	<desc>
10941	Reads data from an offset of this file.
10942
10943	<result name="E_NOTIMPL">
10944	The method is not implemented yet.
10945	</result>
10946	</desc>
10947	<param name="offset" type="long long" dir="in">
10948	<desc>Offset in bytes to start reading.</desc>
10949	</param>
10950	<param name="toRead" type="unsigned long" dir="in">
10951	<desc>Number of bytes to read.</desc>
10952	</param>
10953	<param name="timeoutMS" type="unsigned long" dir="in">
10954	<desc>
10955	Timeout (in ms) to wait for the operation to complete.
10956	Pass 0 for an infinite timeout.
10957	</desc>
10958	</param>
10959	<param name="data" type="octet" dir="return" safearray="yes">
10960	<desc>Array of data read.</desc>
10961	</param>
10962	</method>
10963
10964	<method name="seek">
10965	<desc>
10966	Changes the read and write position of this file.
10967
10968	<result name="E_NOTIMPL">
10969	The method is not implemented yet.
10970	</result>
10971	</desc>
10972	<param name="offset" type="long long" dir="in">
10973	<desc>Offset to seek.</desc>
10974	</param>
10975	<param name="whence" type="FileSeekType" dir="in">
10976	<desc>
10977	Seek mode; see <link to="FileSeekType"/> for more information.
10978	</desc>
10979	</param>
10980	</method>
10981
10982	<method name="setACL">
10983	<desc>
10984	Sets the ACL of this file.
10985
10986	<result name="E_NOTIMPL">
10987	The method is not implemented yet.
10988	</result>
10989	</desc>
10990	<param name="acl" type="wstring" dir="in">
10991	<desc>ACL string to set.</desc>
10992	</param>
10993	</method>
10994
10995	<method name="write">
10996	<desc>
10997	Writes bytes to this file.
10998	</desc>
10999	<param name="data" type="octet" dir="in" safearray="yes">
11000	<desc>
11001	Array of bytes to write. The size of the array also specifies
11002	how much to write.
11003	</desc>
11004	</param>
11005	<param name="timeoutMS" type="unsigned long" dir="in">
11006	<desc>
11007	Timeout (in ms) to wait for the operation to complete.
11008	Pass 0 for an infinite timeout.
11009	</desc>
11010	</param>
11011	<param name="written" type="unsigned long" dir="return">
11012	<desc>How much bytes were written.</desc>
11013	</param>
11014	</method>
11015
11016	<method name="writeAt">
11017	<desc>
11018	Writes bytes at a certain offset to this file.
11019
11020	<result name="E_NOTIMPL">
11021	The method is not implemented yet.
11022	</result>
11023	</desc>
11024	<param name="offset" type="long long" dir="in">
11025	<desc>Offset in bytes to start writing.</desc>
11026	</param>
11027	<param name="data" type="octet" dir="in" safearray="yes">
11028	<desc>
11029	Array of bytes to write. The size of the array also specifies
11030	how much to write.
11031	</desc>
11032	</param>
11033	<param name="timeoutMS" type="unsigned long" dir="in">
11034	<desc>
11035	Timeout (in ms) to wait for the operation to complete.
11036	Pass 0 for an infinite timeout.
11037	</desc>
11038	</param>
11039	<param name="written" type="unsigned long" dir="return">
11040	<desc>How much bytes were written.</desc>
11041	</param>
11042	</method>
11043
11044	</interface>
11045
11046	<interface
11047	name="IGuestFile" extends="IFile"
11048	uuid="60661aec-145f-4d11-b80e-8ea151598093"
11049	wsmap="managed"
11050	>
11051	<desc>
11052	Implementation of the <link to="IFile" /> object
11053	for files on the guest.
11054	</desc>
11055	</interface>
11056
11057	<interface
11058	name="IFsObjInfo" extends="$unknown"
11059	uuid="4047ba30-7006-4966-ae86-94164e5e20eb"
11060	wsmap="managed"
11061	>
11062	<desc>
11063	Abstract parent interface for VirtualBox file system object information.
11064	This can be information about a file or a directory, for example.
11065	</desc>
11066
11067	<attribute name="accessTime" type="long long" readonly="yes">
11068	<desc>
11069	Time of last access (st_atime).
11070	</desc>
11071	</attribute>
11072	<attribute name="allocatedSize" type="long long" readonly="yes">
11073	<desc>
11074	Disk allocation size (st_blocks * DEV_BSIZE).
11075	</desc>
11076	</attribute>
11077	<attribute name="birthTime" type="long long" readonly="yes">
11078	<desc>
11079	Time of file birth (st_birthtime).
11080	</desc>
11081	</attribute>
11082	<attribute name="changeTime" type="long long" readonly="yes">
11083	<desc>
11084	Time of last status change (st_ctime).
11085	</desc>
11086	</attribute>
11087	<attribute name="deviceNumber" type="unsigned long" readonly="yes">
11088	<desc>
11089	The device number of a character or block device type object (st_rdev).
11090	</desc>
11091	</attribute>
11092	<attribute name="fileAttributes" type="wstring" readonly="yes">
11093	<desc>
11094	File attributes. Not implemented yet.
11095	</desc>
11096	</attribute>
11097	<attribute name="generationId" type="unsigned long" readonly="yes">
11098	<desc>
11099	The current generation number (st_gen).
11100	</desc>
11101	</attribute>
11102	<attribute name="GID" type="unsigned long" readonly="yes">
11103	<desc>
11104	The group the filesystem object is assigned (st_gid).
11105	</desc>
11106	</attribute>
11107	<attribute name="groupName" type="wstring" readonly="yes">
11108	<desc>
11109	The group name.
11110	</desc>
11111	</attribute>
11112	<attribute name="hardLinks" type="unsigned long" readonly="yes">
11113	<desc>
11114	Number of hard links to this filesystem object (st_nlink).
11115	</desc>
11116	</attribute>
11117	<attribute name="modificationTime" type="long long" readonly="yes">
11118	<desc>
11119	Time of last data modification (st_mtime).
11120	</desc>
11121	</attribute>
11122	<attribute name="name" type="wstring" readonly="yes">
11123	<desc>
11124	The object's name.
11125	</desc>
11126	</attribute>
11127	<attribute name="nodeId" type="long long" readonly="yes">
11128	<desc>
11129	The unique identifier (within the filesystem) of this filesystem object (st_ino).
11130	</desc>
11131	</attribute>
11132	<attribute name="nodeIdDevice" type="unsigned long" readonly="yes">
11133	<desc>
11134	The device number of the device which this filesystem object resides on (st_dev).
11135	</desc>
11136	</attribute>
11137	<attribute name="objectSize" type="long long" readonly="yes">
11138	<desc>
11139	The logical size (st_size). For normal files this is the size of the file.
11140	For symbolic links, this is the length of the path name contained in the
11141	symbolic link. For other objects this fields needs to be specified.
11142	</desc>
11143	</attribute>
11144	<attribute name="type" type="FsObjType" readonly="yes">
11145	<desc>
11146	The object type. See <link to="FsObjType" /> for more.
11147	</desc>
11148	</attribute>
11149	<attribute name="UID" type="unsigned long" readonly="yes">
11150	<desc>
11151	The user owning the filesystem object (st_uid).
11152	</desc>
11153	</attribute>
11154	<attribute name="userFlags" type="unsigned long" readonly="yes">
11155	<desc>
11156	User flags (st_flags).
11157	</desc>
11158	</attribute>
11159	<attribute name="userName" type="wstring" readonly="yes">
11160	<desc>
11161	The user name.
11162	</desc>
11163	</attribute>
11164
11165	</interface>
11166
11167	<interface
11168	name="IGuestFsObjInfo" extends="IFsObjInfo"
11169	uuid="d5cf678e-3484-4e4a-ac55-329e15462e18"
11170	wsmap="managed"
11171	>
11172	<desc>
11173	Represents the guest implementation of the
11174	<link to="IFsObjInfo" /> object.
11175	</desc>
11176	</interface>
11177
11178	<interface
11179	name="IGuest" extends="$unknown"
11180	uuid="19c32350-0618-4ede-b0c3-2b4311bf0d9b"
11181	wsmap="managed"
11182	>
11183	<desc>
11184	The IGuest interface represents information about the operating system
11185	running inside the virtual machine. Used in
11186	<link to="IConsole::guest"/>.
11187
11188	IGuest provides information about the guest operating system, whether
11189	Guest Additions are installed and other OS-specific virtual machine
11190	properties.
11191	</desc>
11192
11193	<attribute name="OSTypeId" type="wstring" readonly="yes">
11194	<desc>
11195	Identifier of the Guest OS type as reported by the Guest
11196	Additions.
11197	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
11198	an IGuestOSType object representing details about the given
11199	Guest OS type.
11200	<note>
11201	If Guest Additions are not installed, this value will be
11202	the same as <link to="IMachine::OSTypeId"/>.
11203	</note>
11204	</desc>
11205	</attribute>
11206
11207	<attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
11208	<desc>
11209	Current run level of the Guest Additions.
11210	</desc>
11211	</attribute>
11212
11213	<attribute name="additionsVersion" type="wstring" readonly="yes">
11214	<desc>
11215	Version of the Guest Additions in the same format as
11216	<link to="IVirtualBox::version"/>.
11217	</desc>
11218	</attribute>
11219
11220	<attribute name="additionsRevision" type="unsigned long" readonly="yes">
11221	<desc>
11222	The internal build revision number of the additions.
11223
11224	See also <link to="IVirtualBox::revision"/>.
11225	</desc>
11226	</attribute>
11227
11228	<attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes">
11229	<desc>
11230	Array of current known facilities. Only returns facilities where a status is known,
11231	e.g. facilities with an unknown status will not be returned.
11232	</desc>
11233	</attribute>
11234
11235	<attribute name="sessions" type="IGuestSession" readonly="yes" safearray="yes">
11236	<desc>Returns a collection of all opened guest sessions.</desc>
11237	</attribute>
11238
11239	<attribute name="memoryBalloonSize" type="unsigned long">
11240	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
11241	</attribute>
11242
11243	<attribute name="statisticsUpdateInterval" type="unsigned long">
11244	<desc>Interval to update guest statistics in seconds.</desc>
11245	</attribute>
11246
11247	<method name="internalGetStatistics">
11248	<desc>
11249	Internal method; do not use as it might change at any time.
11250	</desc>
11251	<param name="cpuUser" type="unsigned long" dir="out">
11252	<desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
11253	</param>
11254	<param name="cpuKernel" type="unsigned long" dir="out">
11255	<desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
11256	</param>
11257	<param name="cpuIdle" type="unsigned long" dir="out">
11258	<desc>Percentage of processor time spent idling as seen by the guest.</desc>
11259	</param>
11260	<param name="memTotal" type="unsigned long" dir="out">
11261	<desc>Total amount of physical guest RAM.</desc>
11262	</param>
11263	<param name="memFree" type="unsigned long" dir="out">
11264	<desc>Free amount of physical guest RAM.</desc>
11265	</param>
11266	<param name="memBalloon" type="unsigned long" dir="out">
11267	<desc>Amount of ballooned physical guest RAM.</desc>
11268	</param>
11269	<param name="memShared" type="unsigned long" dir="out">
11270	<desc>Amount of shared physical guest RAM.</desc>
11271	</param>
11272	<param name="memCache" type="unsigned long" dir="out">
11273	<desc>Total amount of guest (disk) cache memory.</desc>
11274	</param>
11275	<param name="pagedTotal" type="unsigned long" dir="out">
11276	<desc>Total amount of space in the page file.</desc>
11277	</param>
11278	<param name="memAllocTotal" type="unsigned long" dir="out">
11279	<desc>Total amount of memory allocated by the hypervisor.</desc>
11280	</param>
11281	<param name="memFreeTotal" type="unsigned long" dir="out">
11282	<desc>Total amount of free memory available in the hypervisor.</desc>
11283	</param>
11284	<param name="memBalloonTotal" type="unsigned long" dir="out">
11285	<desc>Total amount of memory ballooned by the hypervisor.</desc>
11286	</param>
11287	<param name="memSharedTotal" type="unsigned long" dir="out">
11288	<desc>Total amount of shared memory in the hypervisor.</desc>
11289	</param>
11290	</method>
11291
11292	<method name="getFacilityStatus">
11293	<desc>
11294	Get the current status of a Guest Additions facility.
11295	</desc>
11296	<param name="facility" type="AdditionsFacilityType" dir="in">
11297	<desc>Facility to check status for.</desc>
11298	</param>
11299	<param name="timestamp" type="long long" dir="out">
11300	<desc>Timestamp (in ms) of last status update seen by the host.</desc>
11301	</param>
11302	<param name="status" type="AdditionsFacilityStatus" dir="return">
11303	<desc>The current (latest) facility status.</desc>
11304	</param>
11305	</method>
11306
11307	<method name="getAdditionsStatus">
11308	<desc>
11309	Retrieve the current status of a certain Guest Additions run level.
11310
11311	<result name="VBOX_E_NOT_SUPPORTED">
11312	Wrong status level specified.
11313	</result>
11314
11315	</desc>
11316	<param name="level" type="AdditionsRunLevelType" dir="in">
11317	<desc>Status level to check</desc>
11318	</param>
11319	<param name="active" type="boolean" dir="return">
11320	<desc>Flag whether the status level has been reached or not</desc>
11321	</param>
11322	</method>
11323
11324	<method name="setCredentials">
11325	<desc>
11326	Store login credentials that can be queried by guest operating
11327	systems with Additions installed. The credentials are transient
11328	to the session and the guest may also choose to erase them. Note
11329	that the caller cannot determine whether the guest operating system
11330	has queried or made use of the credentials.
11331
11332	<result name="VBOX_E_VM_ERROR">
11333	VMM device is not available.
11334	</result>
11335
11336	</desc>
11337	<param name="userName" type="wstring" dir="in">
11338	<desc>User name string, can be empty</desc>
11339	</param>
11340	<param name="password" type="wstring" dir="in">
11341	<desc>Password string, can be empty</desc>
11342	</param>
11343	<param name="domain" type="wstring" dir="in">
11344	<desc>Domain name (guest logon scheme specific), can be empty</desc>
11345	</param>
11346	<param name="allowInteractiveLogon" type="boolean" dir="in">
11347	<desc>
11348	Flag whether the guest should alternatively allow the user to
11349	interactively specify different credentials. This flag might
11350	not be supported by all versions of the Additions.
11351	</desc>
11352	</param>
11353	</method>
11354
11355	<method name="dragHGEnter">
11356	<desc>
11357	Informs the guest about a Drag and Drop enter event.
11358
11359	This is used in Host - Guest direction.
11360
11361	<result name="VBOX_E_VM_ERROR">
11362	VMM device is not available.
11363	</result>
11364
11365	</desc>
11366	<param name="screenId" type="unsigned long" dir="in">
11367	<desc>The screen id where the Drag and Drop event occured.</desc>
11368	</param>
11369	<param name="y" type="unsigned long" dir="in">
11370	<desc>y-position of the event.</desc>
11371	</param>
11372	<param name="x" type="unsigned long" dir="in">
11373	<desc>x-position of the event.</desc>
11374	</param>
11375	<param name="defaultAction" type="DragAndDropAction" dir="in">
11376	<desc>The default action to use.</desc>
11377	</param>
11378	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11379	<desc>The actions which are allowed.</desc>
11380	</param>
11381	<param name="formats" type="wstring" dir="in" safearray="yes">
11382	<desc>The supported mime types.</desc>
11383	</param>
11384	<param name="resultAction" type="DragAndDropAction" dir="return">
11385	<desc>The resulting action of this event.</desc>
11386	</param>
11387	</method>
11388
11389	<method name="dragHGMove">
11390	<desc>
11391	Informs the guest about a Drag and Drop move event.
11392
11393	This is used in Host - Guest direction.
11394
11395	<result name="VBOX_E_VM_ERROR">
11396	VMM device is not available.
11397	</result>
11398
11399	</desc>
11400	<param name="screenId" type="unsigned long" dir="in">
11401	<desc>The screen id where the Drag and Drop event occured.</desc>
11402	</param>
11403	<param name="x" type="unsigned long" dir="in">
11404	<desc>x-position of the event.</desc>
11405	</param>
11406	<param name="y" type="unsigned long" dir="in">
11407	<desc>y-position of the event.</desc>
11408	</param>
11409	<param name="defaultAction" type="DragAndDropAction" dir="in">
11410	<desc>The default action to use.</desc>
11411	</param>
11412	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11413	<desc>The actions which are allowed.</desc>
11414	</param>
11415	<param name="formats" type="wstring" dir="in" safearray="yes">
11416	<desc>The supported mime types.</desc>
11417	</param>
11418	<param name="resultAction" type="DragAndDropAction" dir="return">
11419	<desc>The resulting action of this event.</desc>
11420	</param>
11421	</method>
11422
11423	<method name="dragHGLeave">
11424	<desc>
11425	Informs the guest about a Drag and Drop leave event.
11426
11427	This is used in Host - Guest direction.
11428
11429	<result name="VBOX_E_VM_ERROR">
11430	VMM device is not available.
11431	</result>
11432
11433	</desc>
11434	<param name="screenId" type="unsigned long" dir="in">
11435	<desc>The screen id where the Drag and Drop event occured.</desc>
11436	</param>
11437	</method>
11438
11439	<method name="dragHGDrop">
11440	<desc>
11441	Informs the guest about a drop 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	<param name="x" type="unsigned long" dir="in">
11454	<desc>x-position of the event.</desc>
11455	</param>
11456	<param name="y" type="unsigned long" dir="in">
11457	<desc>y-position of the event.</desc>
11458	</param>
11459	<param name="defaultAction" type="DragAndDropAction" dir="in">
11460	<desc>The default action to use.</desc>
11461	</param>
11462	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11463	<desc>The actions which are allowed.</desc>
11464	</param>
11465	<param name="formats" type="wstring" dir="in" safearray="yes">
11466	<desc>The supported mime types.</desc>
11467	</param>
11468	<param name="format" type="wstring" dir="out">
11469	<desc>The resulting format of this event.</desc>
11470	</param>
11471	<param name="resultAction" type="DragAndDropAction" dir="return">
11472	<desc>The resulting action of this event.</desc>
11473	</param>
11474	</method>
11475
11476	<method name="dragHGPutData">
11477	<desc>
11478	Informs the guest about a drop data event.
11479
11480	This is used in Host - Guest direction.
11481
11482	<result name="VBOX_E_VM_ERROR">
11483	VMM device is not available.
11484	</result>
11485
11486	</desc>
11487	<param name="screenId" type="unsigned long" dir="in">
11488	<desc>The screen id where the Drag and Drop event occured.</desc>
11489	</param>
11490	<param name="format" type="wstring" dir="in">
11491	<desc>The mime type the data is in.</desc>
11492	</param>
11493	<param name="data" type="octet" dir="in" safearray="yes">
11494	<desc>The actual data.</desc>
11495	</param>
11496	<param name="progress" type="IProgress" dir="return">
11497	<desc>Progress object to track the operation completion.</desc>
11498	</param>
11499	</method>
11500
11501	<method name="dragGHPending">
11502	<desc>
11503	Ask the guest if there is any Drag and Drop operation pending in the guest.
11504
11505	If no Drag and Drop operation is pending currently, Ignore is returned.
11506
11507	This is used in Guest - Host direction.
11508
11509	<result name="VBOX_E_VM_ERROR">
11510	VMM device is not available.
11511	</result>
11512
11513	</desc>
11514	<param name="screenId" type="unsigned long" dir="in">
11515	<desc>The screen id where the Drag and Drop event occured.</desc>
11516	</param>
11517	<param name="formats" type="wstring" dir="out" safearray="yes">
11518	<desc>On return the supported mime types.</desc>
11519	</param>
11520	<param name="allowedActions" type="DragAndDropAction" dir="out" safearray="yes">
11521	<desc>On return the actions which are allowed.</desc>
11522	</param>
11523	<param name="defaultAction" type="DragAndDropAction" dir="return">
11524	<desc>On return the default action to use.</desc>
11525	</param>
11526	</method>
11527
11528	<method name="dragGHDropped">
11529	<desc>
11530	Informs the guest that a drop event occured for a pending Drag and Drop event.
11531
11532	This is used in Guest - Host direction.
11533
11534	<result name="VBOX_E_VM_ERROR">
11535	VMM device is not available.
11536	</result>
11537
11538	</desc>
11539
11540	<param name="format" type="wstring" dir="in">
11541	<desc>The mime type the data must be in.</desc>
11542	</param>
11543	<param name="action" type="DragAndDropAction" dir="in">
11544	<desc>The action to use.</desc>
11545	</param>
11546	<param name="progress" type="IProgress" dir="return">
11547	<desc>Progress object to track the operation completion.</desc>
11548	</param>
11549	</method>
11550
11551	<method name="dragGHGetData">
11552	<desc>
11553	Fetch the data of a previously Drag and Drop event from the guest.
11554
11555	This is used in Guest - Host direction.
11556
11557	<result name="VBOX_E_VM_ERROR">
11558	VMM device is not available.
11559	</result>
11560
11561	</desc>
11562
11563	<param name="data" type="octet" safearray="yes" dir="return">
11564	<desc>The actual data.</desc>
11565	</param>
11566	</method>
11567
11568	<method name="createSession">
11569	<desc>
11570	Creates a new guest session for controlling the guest.
11571
11572	A guest session represents one impersonated user account on the guest, so
11573	every operation will use the same credentials specified when creating
11574	the session object via <link to="IGuest::createSession"/>. Anonymous
11575	sessions, that is, sessions without specifying a valid
11576	user account on the guest are not allowed due to security reasons.
11577
11578	There can be a maximum of 32 sessions at once per VM. Each session keeps
11579	track of its started guest processes, opened guest files or guest directories.
11580	To work on guest files or directories a guest session offers methods to open
11581	or create such objects (see <link to="IGuestSession::fileOpen"/> or
11582	<link to="IGuestSession::directoryOpen"/> for example).
11583
11584	When done with either of these objects, including the guest session itself,
11585	use the appropriate close() method to let the object do its cleanup work.
11586
11587	Every guest session has its own environment variable block which gets
11588	automatically applied when starting a new guest process via
11589	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
11590	To override (or unset) certain environment variables already set by the
11591	guest session, one can specify a per-process environment block when using
11592	one of the both above mentioned process creation calls.
11593
11594	Closing a session via <link to="IGuestSession::close" /> will try to close
11595	all the mentioned objects above unless these objects are still used by
11596	a client.
11597	</desc>
11598	<param name="user" type="wstring" dir="in">
11599	<desc>
11600	User name this session will be using to control the guest; has to exist
11601	and have the appropriate rights to execute programs in the VM. Must not
11602	be empty.
11603	</desc>
11604	</param>
11605	<param name="password" type="wstring" dir="in">
11606	<desc>
11607	Password of the user account to be used. Empty passwords are allowed.
11608	</desc>
11609	</param>
11610	<param name="domain" type="wstring" dir="in">
11611	<desc>
11612	Domain name of the user account to be used if the guest is part of
11613	a domain. Optional. This feature is not implemented yet.
11614	</desc>
11615	</param>
11616	<param name="sessionName" type="wstring" dir="in">
11617	<desc>
11618	The session's friendly name. Optional, can be empty.
11619	</desc>
11620	</param>
11621	<param name="guestSession" type="IGuestSession" dir="return">
11622	<desc>
11623	The newly created session object.
11624	</desc>
11625	</param>
11626	</method>
11627
11628	<method name="findSession">
11629	<desc>
11630	Finds guest sessions by their friendly name and returns an interface
11631	array with all found guest sessions.
11632	</desc>
11633	<param name="sessionName" type="wstring" dir="in">
11634	<desc>
11635	The session's friendly name to find. Wildcards like ? and * are allowed.
11636	</desc>
11637	</param>
11638	<param name="sessions" type="IGuestSession" safearray="yes" dir="return">
11639	<desc>
11640	Array with all guest sessions found matching the name specified.
11641	</desc>
11642	</param>
11643	</method>
11644
11645	<method name="updateGuestAdditions">
11646	<desc>
11647	Automatically updates already installed Guest Additions in a VM.
11648
11649	At the moment only Windows guests are supported.
11650
11651	Because the VirtualBox Guest Additions drivers are not WHQL-certified
11652	yet there might be warning dialogs during the actual Guest Additions
11653	update. These need to be confirmed manually in order to continue the
11654	installation process. This applies to Windows 2000 and Windows XP guests
11655	and therefore these guests can't be updated in a fully automated fashion
11656	without user interaction. However, to start a Guest Additions update for
11657	the mentioned Windows versions anyway, the flag
11658	AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See
11659	<link to="AdditionsUpdateFlag"/> for more information.
11660
11661	<result name="VBOX_E_NOT_SUPPORTED">
11662	Guest OS is not supported for automated Guest Additions updates or the
11663	already installed Guest Additions are not ready yet.
11664	</result>
11665
11666	<result name="VBOX_E_IPRT_ERROR">
11667	Error while updating.
11668	</result>
11669
11670	</desc>
11671	<param name="source" type="wstring" dir="in">
11672	<desc>
11673	Path to the Guest Additions .ISO file to use for the upate.
11674	</desc>
11675	</param>
11676	<param name="flags" type="AdditionsUpdateFlag" dir="in" safearray="yes">
11677	<desc>
11678	<link to="AdditionsUpdateFlag"/> flags.
11679	</desc>
11680	</param>
11681	<param name="progress" type="IProgress" dir="return">
11682	<desc>Progress object to track the operation completion.</desc>
11683	</param>
11684	</method>
11685
11686	</interface>
11687
11688
11689	<!--
11690	// IProgress
11691	/////////////////////////////////////////////////////////////////////////
11692	-->
11693
11694	<interface
11695	name="IProgress" extends="$unknown"
11696	uuid="c20238e4-3221-4d3f-8891-81ce92d9f913"
11697	wsmap="managed"
11698	>
11699	<desc>
11700	The IProgress interface is used to track and control
11701	asynchronous tasks within VirtualBox.
11702
11703	An instance of this is returned every time VirtualBox starts
11704	an asynchronous task (in other words, a separate thread) which
11705	continues to run after a method call returns. For example,
11706	<link to="IConsole::saveState" />, which saves the state of
11707	a running virtual machine, can take a long time to complete.
11708	To be able to display a progress bar, a user interface such as
11709	the VirtualBox graphical user interface can use the IProgress
11710	object returned by that method.
11711
11712	Note that IProgress is a "read-only" interface in the sense
11713	that only the VirtualBox internals behind the Main API can
11714	create and manipulate progress objects, whereas client code
11715	can only use the IProgress object to monitor a task's
11716	progress and, if <link to="#cancelable" /> is @c true,
11717	cancel the task by calling <link to="#cancel" />.
11718
11719	A task represented by IProgress consists of either one or
11720	several sub-operations that run sequentially, one by one (see
11721	<link to="#operation" /> and <link to="#operationCount" />).
11722	Every operation is identified by a number (starting from 0)
11723	and has a separate description.
11724
11725	You can find the individual percentage of completion of the current
11726	operation in <link to="#operationPercent" /> and the
11727	percentage of completion of the task as a whole
11728	in <link to="#percent" />.
11729
11730	Similarly, you can wait for the completion of a particular
11731	operation via <link to="#waitForOperationCompletion" /> or
11732	for the completion of the whole task via
11733	<link to="#waitForCompletion" />.
11734	</desc>
11735
11736	<attribute name="id" type="uuid" mod="string" readonly="yes">
11737	<desc>ID of the task.</desc>
11738	</attribute>
11739
11740	<attribute name="description" type="wstring" readonly="yes">
11741	<desc>Description of the task.</desc>
11742	</attribute>
11743
11744	<attribute name="initiator" type="$unknown" readonly="yes">
11745	<desc>Initiator of the task.</desc>
11746	</attribute>
11747
11748	<attribute name="cancelable" type="boolean" readonly="yes">
11749	<desc>Whether the task can be interrupted.</desc>
11750	</attribute>
11751
11752	<attribute name="percent" type="unsigned long" readonly="yes">
11753	<desc>
11754	Current progress value of the task as a whole, in percent.
11755	This value depends on how many operations are already complete.
11756	Returns 100 if <link to="#completed" /> is @c true.
11757	</desc>
11758	</attribute>
11759
11760	<attribute name="timeRemaining" type="long" readonly="yes">
11761	<desc>
11762	Estimated remaining time until the task completes, in
11763	seconds. Returns 0 once the task has completed; returns -1
11764	if the remaining time cannot be computed, in particular if
11765	the current progress is 0.
11766
11767	Even if a value is returned, the estimate will be unreliable
11768	for low progress values. It will become more reliable as the
11769	task progresses; it is not recommended to display an ETA
11770	before at least 20% of a task have completed.
11771	</desc>
11772	</attribute>
11773
11774	<attribute name="completed" type="boolean" readonly="yes">
11775	<desc>Whether the task has been completed.</desc>
11776	</attribute>
11777
11778	<attribute name="canceled" type="boolean" readonly="yes">
11779	<desc>Whether the task has been canceled.</desc>
11780	</attribute>
11781
11782	<attribute name="resultCode" type="long" readonly="yes">
11783	<desc>
11784	Result code of the progress task.
11785	Valid only if <link to="#completed"/> is @c true.
11786	</desc>
11787	</attribute>
11788
11789	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
11790	<desc>
11791	Extended information about the unsuccessful result of the
11792	progress operation. May be @c null if no extended information
11793	is available.
11794	Valid only if <link to="#completed"/> is @c true and
11795	<link to="#resultCode"/> indicates a failure.
11796	</desc>
11797	</attribute>
11798
11799	<attribute name="operationCount" type="unsigned long" readonly="yes">
11800	<desc>
11801	Number of sub-operations this task is divided into.
11802	Every task consists of at least one suboperation.
11803	</desc>
11804	</attribute>
11805
11806	<attribute name="operation" type="unsigned long" readonly="yes">
11807	<desc>Number of the sub-operation being currently executed.</desc>
11808	</attribute>
11809
11810	<attribute name="operationDescription" type="wstring" readonly="yes">
11811	<desc>
11812	Description of the sub-operation being currently executed.
11813	</desc>
11814	</attribute>
11815
11816	<attribute name="operationPercent" type="unsigned long" readonly="yes">
11817	<desc>Progress value of the current sub-operation only, in percent.</desc>
11818	</attribute>
11819
11820	<attribute name="operationWeight" type="unsigned long" readonly="yes">
11821	<desc>Weight value of the current sub-operation only.</desc>
11822	</attribute>
11823
11824	<attribute name="timeout" type="unsigned long">
11825	<desc>
11826	When non-zero, this specifies the number of milliseconds after which
11827	the operation will automatically be canceled. This can only be set on
11828	cancelable objects.
11829	</desc>
11830	</attribute>
11831
11832	<method name="setCurrentOperationProgress">
11833	<desc>Internal method, not to be called externally.</desc>
11834	<param name="percent" type="unsigned long" dir="in" />
11835	</method>
11836	<method name="setNextOperation">
11837	<desc>Internal method, not to be called externally.</desc>
11838	<param name="nextOperationDescription" type="wstring" dir="in" />
11839	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
11840	</method>
11841
11842	<method name="waitForCompletion">
11843	<desc>
11844	Waits until the task is done (including all sub-operations)
11845	with a given timeout in milliseconds; specify -1 for an indefinite wait.
11846
11847	Note that the VirtualBox/XPCOM/COM/native event queues of the calling
11848	thread are not processed while waiting. Neglecting event queues may
11849	have dire consequences (degrade performance, resource hogs,
11850	deadlocks, etc.), this is specially so for the main thread on
11851	platforms using XPCOM. Callers are adviced wait for short periods
11852	and service their event queues between calls, or to create a worker
11853	thread to do the waiting.
11854
11855	<result name="VBOX_E_IPRT_ERROR">
11856	Failed to wait for task completion.
11857	</result>
11858	</desc>
11859
11860	<param name="timeout" type="long" dir="in">
11861	<desc>
11862	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11863	</desc>
11864	</param>
11865	</method>
11866
11867	<method name="waitForOperationCompletion">
11868	<desc>
11869	Waits until the given operation is done with a given timeout in
11870	milliseconds; specify -1 for an indefinite wait.
11871
11872	See <link to="#waitForCompletion"> for event queue considerations.</link>
11873
11874	<result name="VBOX_E_IPRT_ERROR">
11875	Failed to wait for operation completion.
11876	</result>
11877
11878	</desc>
11879	<param name="operation" type="unsigned long" dir="in">
11880	<desc>
11881	Number of the operation to wait for.
11882	Must be less than <link to="#operationCount"/>.
11883	</desc>
11884	</param>
11885	<param name="timeout" type="long" dir="in">
11886	<desc>
11887	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11888	</desc>
11889	</param>
11890	</method>
11891
11892	<method name="waitForAsyncProgressCompletion">
11893	<desc>
11894	Waits until the other task is completed (including all
11895	sub-operations) and forward all changes from the other progress to
11896	this progress. This means sub-operation number, description, percent
11897	and so on.
11898
11899	You have to take care on setting up at least the same count on
11900	sub-operations in this progress object like there are in the other
11901	progress object.
11902
11903	If the other progress object supports cancel and this object gets any
11904	cancel request (when here enabled as well), it will be forwarded to
11905	the other progress object.
11906
11907	If there is an error in the other progress, this error isn't
11908	automatically transfered to this progress object. So you have to
11909	check any operation error within the other progress object, after
11910	this method returns.
11911	</desc>
11912
11913	<param name="pProgressAsync" type="IProgress" dir="in">
11914	<desc>
11915	The progress object of the asynchrony process.
11916	</desc>
11917	</param>
11918	</method>
11919
11920	<method name="cancel">
11921	<desc>
11922	Cancels the task.
11923	<note>
11924	If <link to="#cancelable"/> is @c false, then this method will fail.
11925	</note>
11926
11927	<result name="VBOX_E_INVALID_OBJECT_STATE">
11928	Operation cannot be canceled.
11929	</result>
11930
11931	</desc>
11932	</method>
11933
11934	</interface>
11935
11936	<!--
11937	// ISnapshot
11938	/////////////////////////////////////////////////////////////////////////
11939	-->
11940
11941	<interface
11942	name="ISnapshot" extends="$unknown"
11943	uuid="0472823b-c6e7-472a-8e9f-d732e86b8463"
11944	wsmap="managed"
11945	>
11946	<desc>
11947	The ISnapshot interface represents a snapshot of the virtual
11948	machine.
11949
11950	Together with the differencing media that are created
11951	when a snapshot is taken, a machine can be brought back to
11952	the exact state it was in when the snapshot was taken.
11953
11954	The ISnapshot interface has no methods, only attributes; snapshots
11955	are controlled through methods of the <link to="IConsole" /> interface
11956	which also manage the media associated with the snapshot.
11957	The following operations exist:
11958
11959	<ul>
11960	<li><link to="IConsole::takeSnapshot"/> creates a new snapshot
11961	by creating new, empty differencing images for the machine's
11962	media and saving the VM settings and (if the VM is running)
11963	the current VM state in the snapshot.
11964
11965	The differencing images will then receive all data written to
11966	the machine's media, while their parent (base) images
11967	remain unmodified after the snapshot has been taken (see
11968	<link to="IMedium" /> for details about differencing images).
11969	This simplifies restoring a machine to the state of a snapshot:
11970	only the differencing images need to be deleted.
11971
11972	The current machine state is not changed by taking a snapshot
11973	except that <link to="IMachine::currentSnapshot" /> is set to
11974	the newly created snapshot, which is also added to the machine's
11975	snapshots tree.
11976	</li>
11977
11978	<li><link to="IConsole::restoreSnapshot"/> resets a machine to
11979	the state of a previous snapshot by deleting the differencing
11980	image of each of the machine's media and setting the machine's
11981	settings and state to the state that was saved in the snapshot (if any).
11982
11983	This destroys the machine's current state. After calling this,
11984	<link to="IMachine::currentSnapshot" /> points to the snapshot
11985	that was restored.
11986	</li>
11987
11988	<li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
11989	without affecting the current machine state.
11990
11991	This does not change the current machine state, but instead frees the
11992	resources allocated when the snapshot was taken: the settings and machine
11993	state file are deleted (if any), and the snapshot's differencing image for
11994	each of the machine's media gets merged with its parent image.
11995
11996	Neither the current machine state nor other snapshots are affected
11997	by this operation, except that parent media will be modified
11998	to contain the disk data associated with the snapshot being deleted.
11999
12000	When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
12001	attribute is set to the current snapshot's parent or @c null if it
12002	has no parent. Otherwise the attribute is unchanged.
12003	</li>
12004	</ul>
12005
12006	Each snapshot contains a copy of virtual machine's settings (hardware
12007	configuration etc.). This copy is contained in an immutable (read-only)
12008	instance of <link to="IMachine" /> which is available from the snapshot's
12009	<link to="#machine" /> attribute. When restoring the snapshot, these
12010	settings are copied back to the original machine.
12011
12012	In addition, if the machine was running when the
12013	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
12014	the current VM state is saved in the snapshot (similarly to what happens
12015	when a VM's state is saved). The snapshot is then said to be <i>online</i>
12016	because when restoring it, the VM will be running.
12017
12018	If the machine was in <link to="MachineState_Saved">saved</link> saved,
12019	the snapshot receives a copy of the execution state file
12020	(<link to="IMachine::stateFilePath"/>).
12021
12022	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
12023	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
12024	it then contains a so-called "zero execution state", representing a
12025	machine that is powered off.
12026	</desc>
12027
12028	<attribute name="id" type="uuid" mod="string" readonly="yes">
12029	<desc>UUID of the snapshot.</desc>
12030	</attribute>
12031
12032	<attribute name="name" type="wstring">
12033	<desc>Short name of the snapshot.
12034	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12035	be called implicitly.</note>
12036	</desc>
12037	</attribute>
12038
12039	<attribute name="description" type="wstring">
12040	<desc>Optional description of the snapshot.
12041	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12042	be called implicitly.</note>
12043	</desc>
12044	</attribute>
12045
12046	<attribute name="timeStamp" type="long long" readonly="yes">
12047	<desc>
12048	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
12049	</desc>
12050	</attribute>
12051
12052	<attribute name="online" type="boolean" readonly="yes">
12053	<desc>
12054	@c true if this snapshot is an online snapshot and @c false otherwise.
12055
12056	When this attribute is @c true, the
12057	<link to="IMachine::stateFilePath"/> attribute of the
12058	<link to="#machine"/> object associated with this snapshot
12059	will point to the saved state file. Otherwise, it will be
12060	an empty string.
12061	</desc>
12062	</attribute>
12063
12064	<attribute name="machine" type="IMachine" readonly="yes">
12065	<desc>
12066	Virtual machine this snapshot is taken on. This object
12067	stores all settings the machine had when taking this snapshot.
12068	<note>
12069	The returned machine object is immutable, i.e. no
12070	any settings can be changed.
12071	</note>
12072	</desc>
12073	</attribute>
12074
12075	<attribute name="parent" type="ISnapshot" readonly="yes">
12076	<desc>
12077	Parent snapshot (a snapshot this one is based on), or
12078	@c null if the snapshot has no parent (i.e. is the first snapshot).
12079	</desc>
12080	</attribute>
12081
12082	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
12083	<desc>
12084	Child snapshots (all snapshots having this one as a parent).
12085	By inspecting this attribute starting with a machine's root snapshot
12086	(which can be obtained by calling <link to="IMachine::findSnapshot" />
12087	with a @c null UUID), a machine's snapshots tree can be iterated over.
12088	</desc>
12089	</attribute>
12090
12091	<method name="getChildrenCount" const="yes">
12092	<desc>
12093	Returns the number of direct childrens of this snapshot.
12094	</desc>
12095	<param name="childrenCount" type="unsigned long" dir="return">
12096	<desc>
12097	</desc>
12098	</param>
12099	</method>
12100
12101	</interface>
12102
12103
12104	<!--
12105	// IMedium
12106	/////////////////////////////////////////////////////////////////////////
12107	-->
12108
12109	<enum
12110	name="MediumState"
12111	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
12112	>
12113	<desc>
12114	Virtual medium state.
12115	<see><link to="IMedium"/></see>
12116	</desc>
12117
12118	<const name="NotCreated" value="0">
12119	<desc>
12120	Associated medium storage does not exist (either was not created yet or
12121	was deleted).
12122	</desc>
12123	</const>
12124	<const name="Created" value="1">
12125	<desc>
12126	Associated storage exists and accessible; this gets set if the
12127	accessibility check performed by <link to="IMedium::refreshState" />
12128	was successful.
12129	</desc>
12130	</const>
12131	<const name="LockedRead" value="2">
12132	<desc>
12133	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
12134	no data modification is possible.
12135	</desc>
12136	</const>
12137	<const name="LockedWrite" value="3">
12138	<desc>
12139	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
12140	no concurrent data reading or modification is possible.
12141	</desc>
12142	</const>
12143	<const name="Inaccessible" value="4">
12144	<desc>
12145	Medium accessibility check (see <link to="IMedium::refreshState" />) has
12146	not yet been performed, or else, associated medium storage is not
12147	accessible. In the first case, <link to="IMedium::lastAccessError"/>
12148	is empty, in the second case, it describes the error that occurred.
12149	</desc>
12150	</const>
12151	<const name="Creating" value="5">
12152	<desc>
12153	Associated medium storage is being created.
12154	</desc>
12155	</const>
12156	<const name="Deleting" value="6">
12157	<desc>
12158	Associated medium storage is being deleted.
12159	</desc>
12160	</const>
12161	</enum>
12162
12163	<enum
12164	name="MediumType"
12165	uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04"
12166	>
12167	<desc>
12168	Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
12169	attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
12170	when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
12171	the medium attached. At the moment DVD and floppy media are always of type "writethrough".
12172	</desc>
12173
12174	<const name="Normal" value="0">
12175	<desc>
12176	Normal medium (attached directly or indirectly, preserved
12177	when taking snapshots).
12178	</desc>
12179	</const>
12180	<const name="Immutable" value="1">
12181	<desc>
12182	Immutable medium (attached indirectly, changes are wiped out
12183	the next time the virtual machine is started).
12184	</desc>
12185	</const>
12186	<const name="Writethrough" value="2">
12187	<desc>
12188	Write through medium (attached directly, ignored when
12189	taking snapshots).
12190	</desc>
12191	</const>
12192	<const name="Shareable" value="3">
12193	<desc>
12194	Allow using this medium concurrently by several machines.
12195	<note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
12196	</desc>
12197	</const>
12198	<const name="Readonly" value="4">
12199	<desc>
12200	A readonly medium, which can of course be used by several machines.
12201	<note>Present and accepted since VirtualBox 4.0.</note>
12202	</desc>
12203	</const>
12204	<const name="MultiAttach" value="5">
12205	<desc>
12206	A medium which is indirectly attached, so that one base medium can
12207	be used for several VMs which have their own differencing medium to
12208	store their modifications. In some sense a variant of Immutable
12209	with unset AutoReset flag in each differencing medium.
12210	<note>Present and accepted since VirtualBox 4.0.</note>
12211	</desc>
12212	</const>
12213	</enum>
12214
12215	<enum
12216	name="MediumVariant"
12217	uuid="80685b6b-e42f-497d-8271-e77bf3c61ada"
12218	>
12219	<desc>
12220	Virtual medium image variant. More than one flag may be set.
12221	<see><link to="IMedium"/></see>
12222	</desc>
12223
12224	<const name="Standard" value="0">
12225	<desc>
12226	No particular variant requested, results in using the backend default.
12227	</desc>
12228	</const>
12229	<const name="VmdkSplit2G" value="0x01">
12230	<desc>
12231	VMDK image split in chunks of less than 2GByte.
12232	</desc>
12233	</const>
12234	<const name="VmdkRawDisk" value="0x02">
12235	<desc>
12236	VMDK image representing a raw disk.
12237	</desc>
12238	</const>
12239	<const name="VmdkStreamOptimized" value="0x04">
12240	<desc>
12241	VMDK streamOptimized image. Special import/export format which is
12242	read-only/append-only.
12243	</desc>
12244	</const>
12245	<const name="VmdkESX" value="0x08">
12246	<desc>
12247	VMDK format variant used on ESX products.
12248	</desc>
12249	</const>
12250	<const name="Fixed" value="0x10000">
12251	<desc>
12252	Fixed image. Only allowed for base images.
12253	</desc>
12254	</const>
12255	<const name="Diff" value="0x20000">
12256	<desc>
12257	Differencing image. Only allowed for child images.
12258	</desc>
12259	</const>
12260	<const name="NoCreateDir" value="0x40000000">
12261	<desc>
12262	Special flag which suppresses automatic creation of the subdirectory.
12263	Only used when passing the medium variant as an input parameter.
12264	</desc>
12265	</const>
12266	</enum>
12267
12268	<interface
12269	name="IMediumAttachment" extends="$unknown"
12270	uuid="5ee464d6-0613-4331-b154-7ce12170ef9f"
12271	wsmap="struct"
12272	>
12273	<desc>
12274	The IMediumAttachment interface links storage media to virtual machines.
12275	For each medium (<link to="IMedium"/>) which has been attached to a
12276	storage controller (<link to="IStorageController"/>) of a machine
12277	(<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
12278	method, one instance of IMediumAttachment is added to the machine's
12279	<link to="IMachine::mediumAttachments"/> array attribute.
12280
12281	Each medium attachment specifies the storage controller as well as a
12282	port and device number and the IMedium instance representing a virtual
12283	hard disk or floppy or DVD image.
12284
12285	For removable media (DVDs or floppies), there are two additional
12286	options. For one, the IMedium instance can be @c null to represent
12287	an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
12288	secondly, the medium can be one of the pseudo-media for host drives
12289	listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
12290
12291	<h3>Attaching Hard Disks</h3>
12292
12293	Hard disks are attached to virtual machines using the
12294	<link to="IMachine::attachDevice"/> method and detached using the
12295	<link to="IMachine::detachDevice"/> method. Depending on a medium's
12296	type (see <link to="IMedium::type" />), hard disks are attached either
12297	<i>directly</i> or <i>indirectly</i>.
12298
12299	When a hard disk is being attached directly, it is associated with the
12300	virtual machine and used for hard disk operations when the machine is
12301	running. When a hard disk is being attached indirectly, a new differencing
12302	hard disk linked to it is implicitly created and this differencing hard
12303	disk is associated with the machine and used for hard disk operations.
12304	This also means that if <link to="IMachine::attachDevice"/> performs
12305	a direct attachment then the same hard disk will be returned in response
12306	to the subsequent <link to="IMachine::getMedium"/> call; however if
12307	an indirect attachment is performed then
12308	<link to="IMachine::getMedium"/> will return the implicitly created
12309	differencing hard disk, not the original one passed to <link
12310	to="IMachine::attachDevice"/>. In detail:
12311
12312	<ul>
12313	<li><b>Normal base</b> hard disks that do not have children (i.e.
12314	differencing hard disks linked to them) and that are not already
12315	attached to virtual machines in snapshots are attached <b>directly</b>.
12316	Otherwise, they are attached <b>indirectly</b> because having
12317	dependent children or being part of the snapshot makes it impossible
12318	to modify hard disk contents without breaking the integrity of the
12319	dependent party. The <link to="IMedium::readOnly"/> attribute allows to
12320	quickly determine the kind of the attachment for the given hard
12321	disk. Note that if a normal base hard disk is to be indirectly
12322	attached to a virtual machine with snapshots then a special
12323	procedure called <i>smart attachment</i> is performed (see below).</li>
12324	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
12325	they are attached <b>directly</b> if they do not have children and are
12326	not attached to virtual machines in snapshots, and <b>indirectly</b>
12327	otherwise. Note that the smart attachment procedure is never performed
12328	for differencing hard disks.</li>
12329	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
12330	they are designed to be non-writable. If an immutable hard disk is
12331	attached to a virtual machine with snapshots then a special
12332	procedure called smart attachment is performed (see below).</li>
12333	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
12334	also as designed. This also means that writethrough hard disks cannot
12335	have other hard disks linked to them at all.</li>
12336	<li><b>Shareable</b> hard disks are always attached <b>directly</b>,
12337	also as designed. This also means that shareable hard disks cannot
12338	have other hard disks linked to them at all. They behave almost
12339	like writethrough hard disks, except that shareable hard disks can
12340	be attached to several virtual machines which are running, allowing
12341	concurrent accesses. You need special cluster software running in
12342	the virtual machines to make use of such disks.</li>
12343	</ul>
12344
12345	Note that the same hard disk, regardless of its type, may be attached to
12346	more than one virtual machine at a time. In this case, the machine that is
12347	started first gains exclusive access to the hard disk and attempts to
12348	start other machines having this hard disk attached will fail until the
12349	first machine is powered down.
12350
12351	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
12352	that the given hard disk remains associated with the given machine after a
12353	successful <link to="IMachine::detachDevice"/> call until
12354	<link to="IMachine::saveSettings"/> is called to save all changes to
12355	machine settings to disk. This deferring is necessary to guarantee that
12356	the hard disk configuration may be restored at any time by a call to
12357	<link to="IMachine::discardSettings"/> before the settings
12358	are saved (committed).
12359
12360	Note that if <link to="IMachine::discardSettings"/> is called after
12361	indirectly attaching some hard disks to the machine but before a call to
12362	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
12363	all differencing hard disks implicitly created by
12364	<link to="IMachine::attachDevice"/> for these indirect attachments.
12365	Such implicitly created hard disks will also be immediately deleted when
12366	detached explicitly using the <link to="IMachine::detachDevice"/>
12367	call if it is made before <link to="IMachine::saveSettings"/>. This
12368	implicit deletion is safe because newly created differencing hard
12369	disks do not contain any user data.
12370
12371	However, keep in mind that detaching differencing hard disks that were
12372	implicitly created by <link to="IMachine::attachDevice"/>
12373	before the last <link to="IMachine::saveSettings"/> call will
12374	<b>not</b> implicitly delete them as they may already contain some data
12375	(for example, as a result of virtual machine execution). If these hard
12376	disks are no more necessary, the caller can always delete them explicitly
12377	using <link to="IMedium::deleteStorage"/> after they are actually de-associated
12378	from this machine by the <link to="IMachine::saveSettings"/> call.
12379
12380	<h3>Smart Attachment</h3>
12381
12382	When normal base or immutable hard disks are indirectly attached to a
12383	virtual machine then some additional steps are performed to make sure the
12384	virtual machine will have the most recent "view" of the hard disk being
12385	attached. These steps include walking through the machine's snapshots
12386	starting from the current one and going through ancestors up to the first
12387	snapshot. Hard disks attached to the virtual machine in all
12388	of the encountered snapshots are checked whether they are descendants of
12389	the given normal base or immutable hard disk. The first found child (which
12390	is the differencing hard disk) will be used instead of the normal base or
12391	immutable hard disk as a parent for creating a new differencing hard disk
12392	that will be actually attached to the machine. And only if no descendants
12393	are found or if the virtual machine does not have any snapshots then the
12394	normal base or immutable hard disk will be used itself as a parent for
12395	this differencing hard disk.
12396
12397	It is easier to explain what smart attachment does using the
12398	following example:
12399	<pre>
12400	BEFORE attaching B.vdi: AFTER attaching B.vdi:
12401
12402	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
12403	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
12404	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
12405	Snapshot 4 (none) Snapshot 4 (none)
12406	CurState (none) CurState (D3->D2.vdi)
12407
12408	NOT
12409	...
12410	CurState (D3->B.vdi)
12411	</pre>
12412	The first column is the virtual machine configuration before the base hard
12413	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
12414	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
12415	mean that the hard disk that is actually attached to the machine is a
12416	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
12417	another hard disk, <tt>B.vdi</tt>.
12418
12419	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
12420	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
12421	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
12422	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
12423	it cannot be attached directly and needs an indirect attachment (i.e.
12424	implicit creation of a new differencing hard disk). Due to the smart
12425	attachment procedure, the new differencing hard disk
12426	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
12427	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
12428	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
12429	machine.
12430
12431	Note that if there is more than one descendant hard disk of the given base
12432	hard disk found in a snapshot, and there is an exact device, channel and
12433	bus match, then this exact match will be used. Otherwise, the youngest
12434	descendant will be picked up.
12435
12436	There is one more important aspect of the smart attachment procedure which
12437	is not related to snapshots at all. Before walking through the snapshots
12438	as described above, the backup copy of the current list of hard disk
12439	attachment is searched for descendants. This backup copy is created when
12440	the hard disk configuration is changed for the first time after the last
12441	<link to="IMachine::saveSettings"/> call and used by
12442	<link to="IMachine::discardSettings"/> to undo the recent hard disk
12443	changes. When such a descendant is found in this backup copy, it will be
12444	simply re-attached back, without creating a new differencing hard disk for
12445	it. This optimization is necessary to make it possible to re-attach the
12446	base or immutable hard disk to a different bus, channel or device slot
12447	without losing the contents of the differencing hard disk actually
12448	attached to the machine in place of it.
12449
12450	</desc>
12451
12452	<attribute name="medium" type="IMedium" readonly="yes">
12453	<desc>Medium object associated with this attachment; it
12454	can be @c null for removable devices.</desc>
12455	</attribute>
12456
12457	<attribute name="controller" type="wstring" readonly="yes">
12458	<desc>Name of the storage controller of this attachment; this
12459	refers to one of the controllers in <link to="IMachine::storageControllers" />
12460	by name.</desc>
12461	</attribute>
12462
12463	<attribute name="port" type="long" readonly="yes">
12464	<desc>Port number of this attachment.
12465	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
12466	</desc>
12467	</attribute>
12468
12469	<attribute name="device" type="long" readonly="yes">
12470	<desc>Device slot number of this attachment.
12471	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
12472	</desc>
12473	</attribute>
12474
12475	<attribute name="type" type="DeviceType" readonly="yes">
12476	<desc>Device type of this attachment.</desc>
12477	</attribute>
12478
12479	<attribute name="passthrough" type="boolean" readonly="yes">
12480	<desc>Pass I/O requests through to a device on the host.</desc>
12481	</attribute>
12482
12483	<attribute name="temporaryEject" type="boolean" readonly="yes">
12484	<desc>Whether guest-triggered eject results in unmounting the medium.</desc>
12485	</attribute>
12486
12487	<attribute name="isEjected" type="boolean" readonly="yes">
12488	<desc>Signals that the removable medium has been ejected. This is not
12489	necessarily equivalent to having a @c null medium association.</desc>
12490	</attribute>
12491
12492	<attribute name="nonRotational" type="boolean" readonly="yes">
12493	<desc>Whether the associated medium is non-rotational.</desc>
12494	</attribute>
12495
12496	<attribute name="discard" type="boolean" readonly="yes">
12497	<desc>Whether the associated medium supports discarding unused blocks.</desc>
12498	</attribute>
12499
12500	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
12501	<desc>The bandwidth group this medium attachment is assigned to.</desc>
12502	</attribute>
12503
12504	</interface>
12505
12506	<interface
12507	name="IMedium" extends="$unknown"
12508	uuid="86fd6208-4c8c-40c2-a4e3-f6b47ac6ef07"
12509	wsmap="managed"
12510	>
12511	<desc>
12512	The IMedium interface represents virtual storage for a machine's
12513	hard disks, CD/DVD or floppy drives. It will typically represent
12514	a disk image on the host, for example a VDI or VMDK file representing
12515	a virtual hard disk, or an ISO or RAW file representing virtual
12516	removable media, but can also point to a network location (e.g.
12517	for iSCSI targets).
12518
12519	Instances of IMedium are connected to virtual machines by way of medium
12520	attachments, which link the storage medium to a particular device slot
12521	of a storage controller of the virtual machine.
12522	In the VirtualBox API, virtual storage is therefore always represented
12523	by the following chain of object links:
12524
12525	<ul>
12526	<li><link to="IMachine::storageControllers"/> contains an array of
12527	storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
12528	these are instances of <link to="IStorageController"/>).</li>
12529	<li><link to="IMachine::mediumAttachments"/> contains an array of
12530	medium attachments (instances of <link to="IMediumAttachment"/>
12531	created by <link to="IMachine::attachDevice" />),
12532	each containing a storage controller from the above array, a
12533	port/device specification, and an instance of IMedium representing
12534	the medium storage (image file).
12535
12536	For removable media, the storage medium is optional; a medium
12537	attachment with no medium represents a CD/DVD or floppy drive
12538	with no medium inserted. By contrast, hard disk attachments
12539	will always have an IMedium object attached.</li>
12540	<li>Each IMedium in turn points to a storage unit (such as a file
12541	on the host computer or a network resource) that holds actual
12542	data. This location is represented by the <link to="#location"/>
12543	attribute.</li>
12544	</ul>
12545
12546	Existing media are opened using <link to="IVirtualBox::openMedium"/>;
12547	new hard disk media can be created with the VirtualBox API using the
12548	<link to="IVirtualBox::createHardDisk"/> method. Differencing hard
12549	disks (see below) are usually implicitly created by VirtualBox as
12550	needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
12551	VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
12552	should be created with external tools and then opened from within VirtualBox.
12553
12554	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
12555	drive. In that case the <link to="#id" /> attribute contains the UUID of
12556	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
12557
12558	<h3>Media registries</h3>
12559
12560	When a medium has been opened or created using one of the aforementioned
12561	APIs, it becomes "known" to VirtualBox. Known media can be attached
12562	to virtual machines and re-found through <link to="IVirtualBox::openMedium"/>.
12563	They also appear in the global
12564	<link to="IVirtualBox::hardDisks" />,
12565	<link to="IVirtualBox::DVDImages" /> and
12566	<link to="IVirtualBox::floppyImages" /> arrays.
12567
12568	Prior to VirtualBox 4.0, opening a medium added it to a global media registry
12569	in the VirtualBox.xml file, which was shared between all machines and made
12570	transporting machines and their media from one host to another difficult.
12571
12572	Starting with VirtualBox 4.0, media are only added to a registry when they are
12573	<i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
12574	backwards compatibility, which registry a medium is added to depends on which
12575	VirtualBox version created a machine:
12576
12577	<ul>
12578	<li>If the medium has first been attached to a machine which was created by
12579	VirtualBox 4.0 or later, it is added to that machine's media registry in
12580	the machine XML settings file. This way all information about a machine's
12581	media attachments is contained in a single file and can be transported
12582	easily.</li>
12583	<li>For older media attachments (i.e. if the medium was first attached to a
12584	machine which was created with a VirtualBox version before 4.0), media
12585	continue to be registered in the global VirtualBox settings file, for
12586	backwards compatibility.</li>
12587	</ul>
12588
12589	See <link to="IVirtualBox::openMedium" /> for more information.
12590
12591	Media are removed from media registries by the <link to="IMedium::close"/>,
12592	<link to="#deleteStorage"/> and <link to="#mergeTo"/> methods.
12593
12594	<h3>Accessibility checks</h3>
12595
12596	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
12597	method is called explicitly on a medium. This is done to make the VirtualBox object
12598	ready for serving requests as fast as possible and let the end-user
12599	application decide if it needs to check media accessibility right away or not.
12600
12601	As a result, when VirtualBox starts up (e.g. the VirtualBox
12602	object gets created for the first time), all known media are in the
12603	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
12604	attribute is an empty string because no actual accessibility check has
12605	been made yet.
12606
12607	After calling <link to="#refreshState" />, a medium is considered
12608	<i>accessible</i> if its storage unit can be read. In that case, the
12609	<link to="#state"/> attribute has a value of "Created". If the storage
12610	unit cannot be read (for example, because it is located on a disconnected
12611	network resource, or was accidentally deleted outside VirtualBox),
12612	the medium is considered <i>inaccessible</i>, which is indicated by the
12613	"Inaccessible" state. The exact reason why the medium is inaccessible can be
12614	obtained by reading the <link to="#lastAccessError"/> attribute.
12615
12616	<h3>Medium types</h3>
12617
12618	There are five types of medium behavior which are stored in the
12619	<link to="#type"/> attribute (see <link to="MediumType" />) and
12620	which define the medium's behavior with attachments and snapshots.
12621
12622	All media can be also divided in two groups: <i>base</i> media and
12623	<i>differencing</i> media. A base medium contains all sectors of the
12624	medium data in its own storage and therefore can be used independently.
12625	In contrast, a differencing medium is a "delta" to some other medium and
12626	contains only those sectors which differ from that other medium, which is
12627	then called a <i>parent</i>. The differencing medium is said to be
12628	<i>linked to</i> that parent. The parent may be itself a differencing
12629	medium, thus forming a chain of linked media. The last element in that
12630	chain must always be a base medium. Note that several differencing
12631	media may be linked to the same parent medium.
12632
12633	Differencing media can be distinguished from base media by querying the
12634	<link to="#parent"/> attribute: base media do not have parents they would
12635	depend on, so the value of this attribute is always @c null for them.
12636	Using this attribute, it is possible to walk up the medium tree (from the
12637	child medium to its parent). It is also possible to walk down the tree
12638	using the <link to="#children"/> attribute.
12639
12640	Note that the type of all differencing media is "normal"; all other
12641	values are meaningless for them. Base media may be of any type.
12642
12643	<h3>Automatic composition of the file name part</h3>
12644
12645	Another extension to the <link to="IMedium::location"/> attribute is that
12646	there is a possibility to cause VirtualBox to compose a unique value for
12647	the file name part of the location using the UUID of the hard disk. This
12648	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
12649	e.g. before the storage unit is created, and works as follows. You set the
12650	value of the <link to="IMedium::location"/> attribute to a location
12651	specification which only contains the path specification but not the file
12652	name part and ends with either a forward slash or a backslash character.
12653	In response, VirtualBox will generate a new UUID for the hard disk and
12654	compose the file name using the following pattern:
12655	<pre>
12656	<path>/{<uuid>}.<ext>
12657	</pre>
12658	where <tt><path></tt> is the supplied path specification,
12659	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
12660	is the default extension for the storage format of this hard disk. After
12661	that, you may call any of the methods that create a new hard disk storage
12662	unit and they will use the generated UUID and file name.
12663	</desc>
12664
12665	<attribute name="id" type="uuid" mod="string" readonly="yes">
12666	<desc>
12667	UUID of the medium. For a newly created medium, this value is a randomly
12668	generated UUID.
12669
12670	<note>
12671	For media in one of MediumState_NotCreated, MediumState_Creating or
12672	MediumState_Deleting states, the value of this property is undefined
12673	and will most likely be an empty UUID.
12674	</note>
12675	</desc>
12676	</attribute>
12677
12678	<attribute name="description" type="wstring">
12679	<desc>
12680	Optional description of the medium. For a newly created medium the value
12681	of this attribute is an empty string.
12682
12683	Medium types that don't support this attribute will return E_NOTIMPL in
12684	attempt to get or set this attribute's value.
12685
12686	<note>
12687	For some storage types, reading this attribute may return an outdated
12688	(last known) value when <link to="#state"/> is <link
12689	to="MediumState_Inaccessible"/> or <link
12690	to="MediumState_LockedWrite"/> because the value of this attribute is
12691	stored within the storage unit itself. Also note that changing the
12692	attribute value is not possible in such case, as well as when the
12693	medium is the <link to="MediumState_LockedRead"/> state.
12694	</note>
12695	</desc>
12696	</attribute>
12697
12698	<attribute name="state" type="MediumState" readonly="yes">
12699	<desc>
12700	Returns the current medium state, which is the last state set by
12701	the accessibility check performed by <link to="#refreshState"/>.
12702	If that method has not yet been called on the medium, the state
12703	is "Inaccessible"; as opposed to truly inaccessible media, the
12704	value of <link to="#lastAccessError"/> will be an empty string in
12705	that case.
12706
12707	<note>As of version 3.1, this no longer performs an accessibility check
12708	automatically; call <link to="#refreshState"/> for that.
12709	</note>
12710	</desc>
12711	</attribute>
12712
12713	<attribute name="variant" type="MediumVariant" safearray="yes" readonly="yes">
12714	<desc>
12715	Returns the storage format variant information for this medium
12716	as an aaray of the flags described at <link to="MediumVariant" />.
12717	Before <link to="#refreshState"/> is called this method returns
12718	an undefined value.
12719	</desc>
12720	</attribute>
12721
12722	<attribute name="location" type="wstring">
12723	<desc>
12724	Location of the storage unit holding medium data.
12725
12726	The format of the location string is medium type specific. For medium
12727	types using regular files in a host's file system, the location
12728	string is the full file name.
12729
12730	Some medium types may support changing the storage unit location by
12731	simply changing the value of this property. If this operation is not
12732	supported, the implementation will return E_NOTIMPL in attempt to set
12733	this attribute's value.
12734
12735	When setting a value of the location attribute which is a regular file
12736	in the host's file system, the given file name may be either relative to
12737	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
12738	absolute. Note that if the given location specification does not contain
12739	the file extension part then a proper default extension will be
12740	automatically appended by the implementation depending on the medium type.
12741	</desc>
12742	</attribute>
12743
12744	<attribute name="name" type="wstring" readonly="yes">
12745	<desc>
12746	Name of the storage unit holding medium data.
12747
12748	The returned string is a short version of the <link to="#location"/>
12749	attribute that is suitable for representing the medium in situations
12750	where the full location specification is too long (such as lists
12751	and comboboxes in GUI frontends). This string is also used by frontends
12752	to sort the media list alphabetically when needed.
12753
12754	For example, for locations that are regular files in the host's file
12755	system, the value of this attribute is just the file name (+ extension),
12756	without the path specification.
12757
12758	Note that as opposed to the <link to="#location"/> attribute, the name
12759	attribute will not necessary be unique for a list of media of the
12760	given type and format.
12761	</desc>
12762	</attribute>
12763
12764	<attribute name="deviceType" type="DeviceType" readonly="yes">
12765	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
12766	medium.</desc>
12767	</attribute>
12768
12769	<attribute name="hostDrive" type="boolean" readonly="yes">
12770	<desc>True if this corresponds to a drive on the host.</desc>
12771	</attribute>
12772
12773	<attribute name="size" type="long long" readonly="yes">
12774	<desc>
12775	Physical size of the storage unit used to hold medium data (in bytes).
12776
12777	<note>
12778	For media whose <link to="#state"/> is <link
12779	to="MediumState_Inaccessible"/>, the value of this property is the
12780	last known size. For <link to="MediumState_NotCreated"/> media,
12781	the returned value is zero.
12782	</note>
12783	</desc>
12784	</attribute>
12785
12786	<attribute name="format" type="wstring" readonly="yes">
12787	<desc>
12788	Storage format of this medium.
12789
12790	The value of this attribute is a string that specifies a backend used
12791	to store medium data. The storage format is defined when you create a
12792	new medium or automatically detected when you open an existing medium,
12793	and cannot be changed later.
12794
12795	The list of all storage formats supported by this VirtualBox
12796	installation can be obtained using
12797	<link to="ISystemProperties::mediumFormats"/>.
12798	</desc>
12799	</attribute>
12800
12801	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
12802	<desc>
12803	Storage medium format object corresponding to this medium.
12804
12805	The value of this attribute is a reference to the medium format object
12806	that specifies the backend properties used to store medium data. The
12807	storage format is defined when you create a new medium or automatically
12808	detected when you open an existing medium, and cannot be changed later.
12809
12810	<note>@c null is returned if there is no associated medium format
12811	object. This can e.g. happen for medium objects representing host
12812	drives and other special medium objects.</note>
12813	</desc>
12814	</attribute>
12815
12816	<attribute name="type" type="MediumType">
12817	<desc>
12818	Type (role) of this medium.
12819
12820	The following constraints apply when changing the value of this
12821	attribute:
12822	<ul>
12823	<li>If a medium is attached to a virtual machine (either in the
12824	current state or in one of the snapshots), its type cannot be
12825	changed.
12826	</li>
12827	<li>As long as the medium has children, its type cannot be set
12828	to <link to="MediumType_Writethrough"/>.
12829	</li>
12830	<li>The type of all differencing media is
12831	<link to="MediumType_Normal"/> and cannot be changed.
12832	</li>
12833	</ul>
12834
12835	The type of a newly created or opened medium is set to
12836	<link to="MediumType_Normal"/>, except for DVD and floppy media,
12837	which have a type of <link to="MediumType_Writethrough"/>.
12838	</desc>
12839	</attribute>
12840
12841	<attribute name="allowedTypes" type="MediumType" safearray="yes" readonly="yes">
12842	<desc>
12843	Returns which medium types can selected for this medium.
12844
12845	<result name="E_NOTIMPL">
12846	This attribute is not implemented at the moment.
12847	</result>
12848	</desc>
12849	</attribute>
12850
12851	<attribute name="parent" type="IMedium" readonly="yes">
12852	<desc>
12853	Parent of this medium (the medium this medium is directly based
12854	on).
12855
12856	Only differencing media have parents. For base (non-differencing)
12857	media, @c null is returned.
12858	</desc>
12859	</attribute>
12860
12861	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
12862	<desc>
12863	Children of this medium (all differencing media directly based
12864	on this medium). A @c null array is returned if this medium
12865	does not have any children.
12866	</desc>
12867	</attribute>
12868
12869	<attribute name="base" type="IMedium" readonly="yes">
12870	<desc>
12871	Base medium of this medium.
12872
12873	If this is a differencing medium, its base medium is the medium
12874	the given medium branch starts from. For all other types of media, this
12875	property returns the medium object itself (i.e. the same object this
12876	property is read on).
12877	</desc>
12878	</attribute>
12879
12880	<attribute name="readOnly" type="boolean" readonly="yes">
12881	<desc>
12882	Returns @c true if this medium is read-only and @c false otherwise.
12883
12884	A medium is considered to be read-only when its contents cannot be
12885	modified without breaking the integrity of other parties that depend on
12886	this medium such as its child media or snapshots of virtual machines
12887	where this medium is attached to these machines. If there are no
12888	children and no such snapshots then there is no dependency and the
12889	medium is not read-only.
12890
12891	The value of this attribute can be used to determine the kind of the
12892	attachment that will take place when attaching this medium to a
12893	virtual machine. If the value is @c false then the medium will
12894	be attached directly. If the value is @c true then the medium
12895	will be attached indirectly by creating a new differencing child
12896	medium for that. See the interface description for more information.
12897
12898	Note that all <link to="MediumType_Immutable">Immutable</link> media
12899	are always read-only while all
12900	<link to="MediumType_Writethrough">Writethrough</link> media are
12901	always not.
12902
12903	<note>
12904	The read-only condition represented by this attribute is related to
12905	the medium type and usage, not to the current
12906	<link to="IMedium::state">medium state</link> and not to the read-only
12907	state of the storage unit.
12908	</note>
12909	</desc>
12910	</attribute>
12911
12912	<attribute name="logicalSize" type="long long" readonly="yes">
12913	<desc>
12914	Logical size of this medium (in bytes), as reported to the
12915	guest OS running inside the virtual machine this medium is
12916	attached to. The logical size is defined when the medium is created
12917	and cannot be changed later.
12918
12919	<note>
12920	For media whose state is <link to="#state"/> is <link
12921	to="MediumState_Inaccessible"/>, the value of this property is the
12922	last known logical size. For <link to="MediumState_NotCreated"/>
12923	media, the returned value is zero.
12924	</note>
12925	</desc>
12926	</attribute>
12927
12928	<attribute name="autoReset" type="boolean">
12929	<desc>
12930	Whether this differencing medium will be automatically reset each
12931	time a virtual machine it is attached to is powered up. This
12932	attribute is automatically set to @c true for the last
12933	differencing image of an "immutable" medium (see
12934	<link to="MediumType" />).
12935
12936	See <link to="#reset"/> for more information about resetting
12937	differencing media.
12938
12939	<note>
12940	Reading this property on a base (non-differencing) medium will
12941	always @c false. Changing the value of this property in this
12942	case is not supported.
12943	</note>
12944
12945	<result name="VBOX_E_NOT_SUPPORTED">
12946	This is not a differencing medium (when changing the attribute
12947	value).
12948	</result>
12949	</desc>
12950	</attribute>
12951
12952	<attribute name="lastAccessError" type="wstring" readonly="yes">
12953	<desc>
12954	Text message that represents the result of the last accessibility
12955	check performed by <link to="#refreshState"/>.
12956
12957	An empty string is returned if the last accessibility check
12958	was successful or has not yet been called. As a result, if
12959	<link to="#state" /> is "Inaccessible" and this attribute is empty,
12960	then <link to="#refreshState"/> has yet to be called; this is the
12961	default value of media after VirtualBox initialization.
12962	A non-empty string indicates a failure and should normally describe
12963	a reason of the failure (for example, a file read error).
12964	</desc>
12965	</attribute>
12966
12967	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
12968	<desc>
12969	Array of UUIDs of all machines this medium is attached to.
12970
12971	A @c null array is returned if this medium is not attached to any
12972	machine or to any machine's snapshot.
12973
12974	<note>
12975	The returned array will include a machine even if this medium is not
12976	attached to that machine in the current state but attached to it in
12977	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
12978	details.
12979	</note>
12980	</desc>
12981	</attribute>
12982
12983	<method name="setIds">
12984	<desc>
12985	Changes the UUID and parent UUID for a hard disk medium.
12986	</desc>
12987	<param name="setImageId" type="boolean" dir="in">
12988	<desc>
12989	Select whether a new image UUID is set or not.
12990	</desc>
12991	</param>
12992	<param name="imageId" type="uuid" mod="string" dir="in">
12993	<desc>
12994	New UUID for the image. If an empty string is passed, then a new
12995	UUID is automatically created, provided that @a setImageId is @c true.
12996	Specifying a zero UUID is not allowed.
12997	</desc>
12998	</param>
12999	<param name="setParentId" type="boolean" dir="in">
13000	<desc>
13001	Select whether a new parent UUID is set or not.
13002	</desc>
13003	</param>
13004	<param name="parentId" type="uuid" mod="string" dir="in">
13005	<desc>
13006	New parent UUID for the image. If an empty string is passed, then a
13007	new UUID is automatically created, provided @a setParentId is
13008	@c true. A zero UUID is valid.
13009	</desc>
13010	</param>
13011	<result name="E_INVALIDARG">
13012	Invalid parameter combination.
13013	</result>
13014	<result name="VBOX_E_NOT_SUPPORTED">
13015	Medium is not a hard disk medium.
13016	</result>
13017	</method>
13018
13019	<method name="refreshState">
13020	<desc>
13021	If the current medium state (see <link to="MediumState"/>) is one of
13022	"Created", "Inaccessible" or "LockedRead", then this performs an
13023	accessibility check on the medium and sets the value of the <link to="#state"/>
13024	attribute accordingly; that value is also returned for convenience.
13025
13026	For all other state values, this does not perform a refresh but returns
13027	the state only.
13028
13029	The refresh, if performed, may take a long time (several seconds or even
13030	minutes, depending on the storage unit location and format) because it performs an
13031	accessibility check of the storage unit. This check may cause a significant
13032	delay if the storage unit of the given medium is, for example, a file located
13033	on a network share which is not currently accessible due to connectivity
13034	problems. In that case, the call will not return until a timeout
13035	interval defined by the host OS for this operation expires. For this reason,
13036	it is recommended to never read this attribute on the main UI thread to avoid
13037	making the UI unresponsive.
13038
13039	If the last known state of the medium is "Created" and the accessibility
13040	check fails, then the state would be set to "Inaccessible", and
13041	<link to="#lastAccessError"/> may be used to get more details about the
13042	failure. If the state of the medium is "LockedRead", then it remains the
13043	same, and a non-empty value of <link to="#lastAccessError"/> will
13044	indicate a failed accessibility check in this case.
13045
13046	Note that not all medium states are applicable to all medium types.
13047	</desc>
13048	<param name="state" type="MediumState" dir="return">
13049	<desc>
13050	New medium state.
13051	</desc>
13052	</param>
13053	</method>
13054
13055	<method name="getSnapshotIds">
13056	<desc>
13057	Returns an array of UUIDs of all snapshots of the given machine where
13058	this medium is attached to.
13059
13060	If the medium is attached to the machine in the current state, then the
13061	first element in the array will always be the ID of the queried machine
13062	(i.e. the value equal to the @c machineId argument), followed by
13063	snapshot IDs (if any).
13064
13065	If the medium is not attached to the machine in the current state, then
13066	the array will contain only snapshot IDs.
13067
13068	The returned array may be @c null if this medium is not attached
13069	to the given machine at all, neither in the current state nor in one of
13070	the snapshots.
13071	</desc>
13072	<param name="machineId" type="uuid" mod="string" dir="in">
13073	<desc>
13074	UUID of the machine to query.
13075	</desc>
13076	</param>
13077	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
13078	<desc>
13079	Array of snapshot UUIDs of the given machine using this medium.
13080	</desc>
13081	</param>
13082	</method>
13083
13084	<method name="lockRead">
13085	<desc>
13086	Locks this medium for reading.
13087
13088	A read lock is shared: many clients can simultaneously lock the
13089	same medium for reading unless it is already locked for writing (see
13090	<link to="#lockWrite"/>) in which case an error is returned.
13091
13092	When the medium is locked for reading, it cannot be modified
13093	from within VirtualBox. This means that any method that changes
13094	the properties of this medium or contents of the storage unit
13095	will return an error (unless explicitly stated otherwise). That
13096	includes an attempt to start a virtual machine that wants to
13097	write to the the medium.
13098
13099	When the virtual machine is started up, it locks for reading all
13100	media it uses in read-only mode. If some medium cannot be locked
13101	for reading, the startup procedure will fail.
13102	A medium is typically locked for reading while it is used by a running
13103	virtual machine but has a depending differencing image that receives
13104	the actual write operations. This way one base medium can have
13105	multiple child differencing images which can be written to
13106	simultaneously. Read-only media such as DVD and floppy images are
13107	also locked for reading only (so they can be in use by multiple
13108	machines simultaneously).
13109
13110	A medium is also locked for reading when it is the source of a
13111	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13112
13113	The medium locked for reading must be unlocked using the <link
13114	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
13115	can be nested and must be followed by the same number of paired
13116	<link to="#unlockRead"/> calls.
13117
13118	This method sets the medium state (see <link to="#state"/>) to
13119	"LockedRead" on success. The medium's previous state must be
13120	one of "Created", "Inaccessible" or "LockedRead".
13121
13122	Locking an inaccessible medium is not an error; this method performs
13123	a logical lock that prevents modifications of this medium through
13124	the VirtualBox API, not a physical file-system lock of the underlying
13125	storage unit.
13126
13127	This method returns the current state of the medium
13128	<i>before</i> the operation.
13129
13130	<result name="VBOX_E_INVALID_OBJECT_STATE">
13131	Invalid medium state (e.g. not created, locked, inaccessible,
13132	creating, deleting).
13133	</result>
13134
13135	</desc>
13136	<param name="state" type="MediumState" dir="return">
13137	<desc>
13138	State of the medium after the operation.
13139	</desc>
13140	</param>
13141	</method>
13142
13143	<method name="unlockRead">
13144	<desc>
13145	Cancels the read lock previously set by <link to="#lockRead"/>.
13146
13147	For both success and failure, this method returns the current state
13148	of the medium <i>after</i> the operation.
13149
13150	See <link to="#lockRead"/> for more details.
13151
13152	<result name="VBOX_E_INVALID_OBJECT_STATE">
13153	Medium not locked for reading.
13154	</result>
13155
13156	</desc>
13157	<param name="state" type="MediumState" dir="return">
13158	<desc>
13159	State of the medium after the operation.
13160	</desc>
13161	</param>
13162	</method>
13163
13164	<method name="lockWrite">
13165	<desc>
13166	Locks this medium for writing.
13167
13168	A write lock, as opposed to <link to="#lockRead"/>, is
13169	exclusive: there may be only one client holding a write lock,
13170	and there may be no read locks while the write lock is held.
13171	As a result, read-locking fails if a write lock is held, and
13172	write-locking fails if either a read or another write lock is held.
13173
13174	When a medium is locked for writing, it cannot be modified
13175	from within VirtualBox, and it is not guaranteed that the values
13176	of its properties are up-to-date. Any method that changes the
13177	properties of this medium or contents of the storage unit will
13178	return an error (unless explicitly stated otherwise).
13179
13180	When a virtual machine is started up, it locks for writing all
13181	media it uses to write data to. If any medium could not be locked
13182	for writing, the startup procedure will fail. If a medium has
13183	differencing images, then while the machine is running, only
13184	the last ("leaf") differencing image is locked for writing,
13185	whereas its parents are locked for reading only.
13186
13187	A medium is also locked for writing when it is the target of a
13188	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13189
13190	The medium locked for writing must be unlocked using the <link
13191	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
13192
13193	This method sets the medium state (see <link to="#state"/>) to
13194	"LockedWrite" on success. The medium's previous state must be
13195	either "Created" or "Inaccessible".
13196
13197	Locking an inaccessible medium is not an error; this method performs
13198	a logical lock that prevents modifications of this medium through
13199	the VirtualBox API, not a physical file-system lock of the underlying
13200	storage unit.
13201
13202	For both, success and failure, this method returns the current
13203	state of the medium <i>before</i> the operation.
13204
13205	<result name="VBOX_E_INVALID_OBJECT_STATE">
13206	Invalid medium state (e.g. not created, locked, inaccessible,
13207	creating, deleting).
13208	</result>
13209
13210	</desc>
13211	<param name="state" type="MediumState" dir="return">
13212	<desc>
13213	State of the medium after the operation.
13214	</desc>
13215	</param>
13216	</method>
13217
13218	<method name="unlockWrite">
13219	<desc>
13220	Cancels the write lock previously set by <link to="#lockWrite"/>.
13221
13222	For both success and failure, this method returns the current
13223	state of the medium <i>after</i> the operation.
13224
13225	See <link to="#lockWrite"/> for more details.
13226
13227	<result name="VBOX_E_INVALID_OBJECT_STATE">
13228	Medium not locked for writing.
13229	</result>
13230
13231	</desc>
13232	<param name="state" type="MediumState" dir="return">
13233	<desc>
13234	State of the medium after the operation.
13235	</desc>
13236	</param>
13237	</method>
13238
13239	<method name="close">
13240	<desc>
13241	Closes this medium.
13242
13243	The medium must not be attached to any known virtual machine
13244	and must not have any known child media, otherwise the
13245	operation will fail.
13246
13247	When the medium is successfully closed, it is removed from
13248	the list of registered media, but its storage unit is not
13249	deleted. In particular, this means that this medium can
13250	later be opened again using the <link to="IVirtualBox::openMedium"/>
13251	call.
13252
13253	Note that after this method successfully returns, the given medium
13254	object becomes uninitialized. This means that any attempt
13255	to call any of its methods or attributes will fail with the
13256	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
13257
13258	<result name="VBOX_E_INVALID_OBJECT_STATE">
13259	Invalid medium state (other than not created, created or
13260	inaccessible).
13261	</result>
13262	<result name="VBOX_E_OBJECT_IN_USE">
13263	Medium attached to virtual machine.
13264	</result>
13265	<result name="VBOX_E_FILE_ERROR">
13266	Settings file not accessible.
13267	</result>
13268	<result name="VBOX_E_XML_ERROR">
13269	Could not parse the settings file.
13270	</result>
13271
13272	</desc>
13273	</method>
13274
13275	<!-- property methods -->
13276
13277	<method name="getProperty" const="yes">
13278	<desc>
13279	Returns the value of the custom medium property with the given name.
13280
13281	The list of all properties supported by the given medium format can
13282	be obtained with <link to="IMediumFormat::describeProperties"/>.
13283
13284	<note>If this method returns an empty string in @a value, the requested
13285	property is supported but currently not assigned any value.</note>
13286
13287	<result name="VBOX_E_OBJECT_NOT_FOUND">
13288	Requested property does not exist (not supported by the format).
13289	</result>
13290	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13291	</desc>
13292	<param name="name" type="wstring" dir="in">
13293	<desc>Name of the property to get.</desc>
13294	</param>
13295	<param name="value" type="wstring" dir="return">
13296	<desc>Current property value.</desc>
13297	</param>
13298	</method>
13299
13300	<method name="setProperty">
13301	<desc>
13302	Sets the value of the custom medium property with the given name.
13303
13304	The list of all properties supported by the given medium format can
13305	be obtained with <link to="IMediumFormat::describeProperties"/>.
13306
13307	<note>Setting the property value to @c null or an empty string is
13308	equivalent to deleting the existing value. A default value (if it is
13309	defined for this property) will be used by the format backend in this
13310	case.</note>
13311
13312	<result name="VBOX_E_OBJECT_NOT_FOUND">
13313	Requested property does not exist (not supported by the format).
13314	</result>
13315	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13316	</desc>
13317	<param name="name" type="wstring" dir="in">
13318	<desc>Name of the property to set.</desc>
13319	</param>
13320	<param name="value" type="wstring" dir="in">
13321	<desc>Property value to set.</desc>
13322	</param>
13323	</method>
13324
13325	<method name="getProperties" const="yes">
13326	<desc>
13327	Returns values for a group of properties in one call.
13328
13329	The names of the properties to get are specified using the @a names
13330	argument which is a list of comma-separated property names or
13331	an empty string if all properties are to be returned.
13332	<note>Currently the value of this argument is ignored and the method
13333	always returns all existing properties.</note>
13334
13335	The list of all properties supported by the given medium format can
13336	be obtained with <link to="IMediumFormat::describeProperties"/>.
13337
13338	The method returns two arrays, the array of property names corresponding
13339	to the @a names argument and the current values of these properties.
13340	Both arrays have the same number of elements with each element at the
13341	given index in the first array corresponds to an element at the same
13342	index in the second array.
13343
13344	For properties that do not have assigned values, an empty string is
13345	returned at the appropriate index in the @a returnValues array.
13346
13347	</desc>
13348	<param name="names" type="wstring" dir="in">
13349	<desc>
13350	Names of properties to get.
13351	</desc>
13352	</param>
13353	<param name="returnNames" type="wstring" safearray="yes" dir="out">
13354	<desc>Names of returned properties.</desc>
13355	</param>
13356	<param name="returnValues" type="wstring" safearray="yes" dir="return">
13357	<desc>Values of returned properties.</desc>
13358	</param>
13359	</method>
13360
13361	<method name="setProperties">
13362	<desc>
13363	Sets values for a group of properties in one call.
13364
13365	The names of the properties to set are passed in the @a names
13366	array along with the new values for them in the @a values array. Both
13367	arrays have the same number of elements with each element at the given
13368	index in the first array corresponding to an element at the same index
13369	in the second array.
13370
13371	If there is at least one property name in @a names that is not valid,
13372	the method will fail before changing the values of any other properties
13373	from the @a names array.
13374
13375	Using this method over <link to="#setProperty"/> is preferred if you
13376	need to set several properties at once since it is more efficient.
13377
13378	The list of all properties supported by the given medium format can
13379	be obtained with <link to="IMediumFormat::describeProperties"/>.
13380
13381	Setting the property value to @c null or an empty string is equivalent
13382	to deleting the existing value. A default value (if it is defined for
13383	this property) will be used by the format backend in this case.
13384	</desc>
13385	<param name="names" type="wstring" safearray="yes" dir="in">
13386	<desc>Names of properties to set.</desc>
13387	</param>
13388	<param name="values" type="wstring" safearray="yes" dir="in">
13389	<desc>Values of properties to set.</desc>
13390	</param>
13391	</method>
13392
13393	<!-- storage methods -->
13394
13395	<method name="createBaseStorage">
13396	<desc>
13397	Starts creating a hard disk storage unit (fixed/dynamic, according
13398	to the variant flags) in in the background. The previous storage unit
13399	created for this object, if any, must first be deleted using
13400	<link to="#deleteStorage"/>, otherwise the operation will fail.
13401
13402	Before the operation starts, the medium is placed in
13403	<link to="MediumState_Creating"/> state. If the create operation
13404	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
13405	state.
13406
13407	After the returned progress object reports that the operation has
13408	successfully completed, the medium state will be set to <link
13409	to="MediumState_Created"/>, the medium will be remembered by this
13410	VirtualBox installation and may be attached to virtual machines.
13411
13412	<result name="VBOX_E_NOT_SUPPORTED">
13413	The variant of storage creation operation is not supported. See <link
13414	to="IMediumFormat::capabilities"/>.
13415	</result>
13416	</desc>
13417	<param name="logicalSize" type="long long" dir="in">
13418	<desc>Maximum logical size of the medium in bytes.</desc>
13419	</param>
13420	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13421	<desc>Exact image variant which should be created (as a combination of
13422	<link to="MediumVariant" /> flags).</desc>
13423	</param>
13424	<param name="progress" type="IProgress" dir="return">
13425	<desc>Progress object to track the operation completion.</desc>
13426	</param>
13427	</method>
13428
13429	<method name="deleteStorage">
13430	<desc>
13431	Starts deleting the storage unit of this medium.
13432
13433	The medium must not be attached to any known virtual machine and must
13434	not have any known child media, otherwise the operation will fail.
13435	It will also fail if there is no storage unit to delete or if deletion
13436	is already in progress, or if the medium is being in use (locked for
13437	read or for write) or inaccessible. Therefore, the only valid state for
13438	this operation to succeed is <link to="MediumState_Created"/>.
13439
13440	Before the operation starts, the medium is placed in
13441	<link to="MediumState_Deleting"/> state and gets removed from the list
13442	of remembered hard disks (media registry). If the delete operation
13443	fails, the medium will be remembered again and placed back to
13444	<link to="MediumState_Created"/> state.
13445
13446	After the returned progress object reports that the operation is
13447	complete, the medium state will be set to
13448	<link to="MediumState_NotCreated"/> and you will be able to use one of
13449	the storage creation methods to create it again.
13450
13451	<see><link to="#close"/></see>
13452
13453	<result name="VBOX_E_OBJECT_IN_USE">
13454	Medium is attached to a virtual machine.
13455	</result>
13456	<result name="VBOX_E_NOT_SUPPORTED">
13457	Storage deletion is not allowed because neither of storage creation
13458	operations are supported. See
13459	<link to="IMediumFormat::capabilities"/>.
13460	</result>
13461
13462	<note>
13463	If the deletion operation fails, it is not guaranteed that the storage
13464	unit still exists. You may check the <link to="IMedium::state"/> value
13465	to answer this question.
13466	</note>
13467	</desc>
13468	<param name="progress" type="IProgress" dir="return">
13469	<desc>Progress object to track the operation completion.</desc>
13470	</param>
13471	</method>
13472
13473	<!-- diff methods -->
13474
13475	<method name="createDiffStorage">
13476	<desc>
13477	Starts creating an empty differencing storage unit based on this
13478	medium in the format and at the location defined by the @a target
13479	argument.
13480
13481	The target medium must be in <link to="MediumState_NotCreated"/>
13482	state (i.e. must not have an existing storage unit). Upon successful
13483	completion, this operation will set the type of the target medium to
13484	<link to="MediumType_Normal"/> and create a storage unit necessary to
13485	represent the differencing medium data in the given format (according
13486	to the storage format of the target object).
13487
13488	After the returned progress object reports that the operation is
13489	successfully complete, the target medium gets remembered by this
13490	VirtualBox installation and may be attached to virtual machines.
13491
13492	<note>
13493	The medium will be set to <link to="MediumState_LockedRead"/>
13494	state for the duration of this operation.
13495	</note>
13496	<result name="VBOX_E_OBJECT_IN_USE">
13497	Medium not in @c NotCreated state.
13498	</result>
13499	</desc>
13500	<param name="target" type="IMedium" dir="in">
13501	<desc>Target medium.</desc>
13502	</param>
13503	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13504	<desc>Exact image variant which should be created (as a combination of
13505	<link to="MediumVariant" /> flags).</desc>
13506	</param>
13507	<param name="progress" type="IProgress" dir="return">
13508	<desc>Progress object to track the operation completion.</desc>
13509	</param>
13510	</method>
13511
13512	<method name="mergeTo">
13513	<desc>
13514	Starts merging the contents of this medium and all intermediate
13515	differencing media in the chain to the given target medium.
13516
13517	The target medium must be either a descendant of this medium or
13518	its ancestor (otherwise this method will immediately return a failure).
13519	It follows that there are two logical directions of the merge operation:
13520	from ancestor to descendant (<i>forward merge</i>) and from descendant to
13521	ancestor (<i>backward merge</i>). Let us consider the following medium
13522	chain:
13523
13524	<pre>Base <- Diff_1 <- Diff_2</pre>
13525
13526	Here, calling this method on the <tt>Base</tt> medium object with
13527	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
13528	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
13529	merge. Note that in both cases the contents of the resulting medium
13530	will be the same, the only difference is the medium object that takes
13531	the result of the merge operation. In case of the forward merge in the
13532	above example, the result will be written to <tt>Diff_2</tt>; in case of
13533	the backward merge, the result will be written to <tt>Base</tt>. In
13534	other words, the result of the operation is always stored in the target
13535	medium.
13536
13537	Upon successful operation completion, the storage units of all media in
13538	the chain between this (source) medium and the target medium, including
13539	the source medium itself, will be automatically deleted and the
13540	relevant medium objects (including this medium) will become
13541	uninitialized. This means that any attempt to call any of
13542	their methods or attributes will fail with the
13543	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
13544	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
13545	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
13546	Note that <tt>Diff_2</tt> in this case will become a base medium
13547	itself since it will no longer be based on any other medium.
13548
13549	Considering the above, all of the following conditions must be met in
13550	order for the merge operation to succeed:
13551	<ul>
13552	<li>
13553	Neither this (source) medium nor any intermediate
13554	differencing medium in the chain between it and the target
13555	medium is attached to any virtual machine.
13556	</li>
13557	<li>
13558	Neither the source medium nor the target medium is an
13559	<link to="MediumType_Immutable"/> medium.
13560	</li>
13561	<li>
13562	The part of the medium tree from the source medium to the
13563	target medium is a linear chain, i.e. all medium in this
13564	chain have exactly one child which is the next medium in this
13565	chain. The only exception from this rule is the target medium in
13566	the forward merge operation; it is allowed to have any number of
13567	child media because the merge operation will not change its
13568	logical contents (as it is seen by the guest OS or by children).
13569	</li>
13570	<li>
13571	None of the involved media are in
13572	<link to="MediumState_LockedRead"/> or
13573	<link to="MediumState_LockedWrite"/> state.
13574	</li>
13575	</ul>
13576
13577	<note>
13578	This (source) medium and all intermediates will be placed to <link
13579	to="MediumState_Deleting"/> state and the target medium will be
13580	placed to <link to="MediumState_LockedWrite"/> state and for the
13581	duration of this operation.
13582	</note>
13583	</desc>
13584	<param name="target" type="IMedium" dir="in">
13585	<desc>Target medium.</desc>
13586	</param>
13587	<param name="progress" type="IProgress" dir="return">
13588	<desc>Progress object to track the operation completion.</desc>
13589	</param>
13590	</method>
13591
13592	<!-- clone method -->
13593
13594	<method name="cloneTo">
13595	<desc>
13596	Starts creating a clone of this medium in the format and at the
13597	location defined by the @a target argument.
13598
13599	The target medium must be either in <link to="MediumState_NotCreated"/>
13600	state (i.e. must not have an existing storage unit) or in
13601	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13602	big enough to hold the data or else the copy will be partial). Upon
13603	successful completion, the cloned medium will contain exactly the
13604	same sector data as the medium being cloned, except that in the
13605	first case a new UUID for the clone will be randomly generated, and in
13606	the second case the UUID will remain unchanged.
13607
13608	The @a parent argument defines which medium will be the parent
13609	of the clone. Passing a @c null reference indicates that the clone will
13610	be a base image, i.e. completely independent. It is possible to specify
13611	an arbitrary medium for this parameter, including the parent of the
13612	medium which is being cloned. Even cloning to a child of the source
13613	medium is possible. Note that when cloning to an existing image, the
13614	@a parent argument is ignored.
13615
13616	After the returned progress object reports that the operation is
13617	successfully complete, the target medium gets remembered by this
13618	VirtualBox installation and may be attached to virtual machines.
13619
13620	<note>
13621	This medium will be placed to <link to="MediumState_LockedRead"/>
13622	state for the duration of this operation.
13623	</note>
13624	<result name="E_NOTIMPL">
13625	The specified cloning variant is not supported at the moment.
13626	</result>
13627	</desc>
13628	<param name="target" type="IMedium" dir="in">
13629	<desc>Target medium.</desc>
13630	</param>
13631	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13632	<desc>Exact image variant which should be created (as a combination of
13633	<link to="MediumVariant" /> flags).</desc>
13634	</param>
13635	<param name="parent" type="IMedium" dir="in">
13636	<desc>Parent of the cloned medium.</desc>
13637	</param>
13638	<param name="progress" type="IProgress" dir="return">
13639	<desc>Progress object to track the operation completion.</desc>
13640	</param>
13641	</method>
13642
13643	<method name="cloneToBase">
13644	<desc>
13645	Starts creating a clone of this medium in the format and at the
13646	location defined by the @a target argument.
13647
13648	The target medium must be either in <link to="MediumState_NotCreated"/>
13649	state (i.e. must not have an existing storage unit) or in
13650	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13651	big enough to hold the data or else the copy will be partial). Upon
13652	successful completion, the cloned medium will contain exactly the
13653	same sector data as the medium being cloned, except that in the
13654	first case a new UUID for the clone will be randomly generated, and in
13655	the second case the UUID will remain unchanged.
13656
13657	The @a parent argument defines which medium will be the parent
13658	of the clone. In this case the clone will be a base image, i.e.
13659	completely independent. It is possible to specify an arbitrary
13660	medium for this parameter, including the parent of the
13661	medium which is being cloned. Even cloning to a child of the source
13662	medium is possible. Note that when cloning to an existing image, the
13663	@a parent argument is ignored.
13664
13665	After the returned progress object reports that the operation is
13666	successfully complete, the target medium gets remembered by this
13667	VirtualBox installation and may be attached to virtual machines.
13668
13669	<note>
13670	This medium will be placed to <link to="MediumState_LockedRead"/>
13671	state for the duration of this operation.
13672	</note>
13673	<result name="E_NOTIMPL">
13674	The specified cloning variant is not supported at the moment.
13675	</result>
13676	</desc>
13677	<param name="target" type="IMedium" dir="in">
13678	<desc>Target medium.</desc>
13679	</param>
13680	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13681	<desc><link to="MediumVariant" /> flags).</desc>
13682	</param>
13683	<param name="progress" type="IProgress" dir="return">
13684	<desc>Progress object to track the operation completion.</desc>
13685	</param>
13686	</method>
13687
13688	<!-- other methods -->
13689
13690	<method name="compact">
13691	<desc>
13692	Starts compacting of this medium. This means that the medium is
13693	transformed into a possibly more compact storage representation.
13694	This potentially creates temporary images, which can require a
13695	substantial amount of additional disk space.
13696
13697	This medium will be placed to <link to="MediumState_LockedWrite"/>
13698	state and all its parent media (if any) will be placed to
13699	<link to="MediumState_LockedRead"/> state for the duration of this
13700	operation.
13701
13702	Please note that the results can be either returned straight away,
13703	or later as the result of the background operation via the object
13704	returned via the @a progress parameter.
13705
13706	<result name="VBOX_E_NOT_SUPPORTED">
13707	Medium format does not support compacting (but potentially
13708	needs it).
13709	</result>
13710	</desc>
13711	<param name="progress" type="IProgress" dir="return">
13712	<desc>Progress object to track the operation completion.</desc>
13713	</param>
13714	</method>
13715
13716	<method name="resize">
13717	<desc>
13718	Starts resizing this medium. This means that the nominal size of the
13719	medium is set to the new value. Both increasing and decreasing the
13720	size is possible, and there are no safety checks, since VirtualBox
13721	does not make any assumptions about the medium contents.
13722
13723	Resizing usually needs additional disk space, and possibly also
13724	some temporary disk space. Note that resize does not create a full
13725	temporary copy of the medium, so the additional disk space requirement
13726	is usually much lower than using the clone operation.
13727
13728	This medium will be placed to <link to="MediumState_LockedWrite"/>
13729	state for the duration of this operation.
13730
13731	Please note that the results can be either returned straight away,
13732	or later as the result of the background operation via the object
13733	returned via the @a progress parameter.
13734
13735	<result name="VBOX_E_NOT_SUPPORTED">
13736	Medium format does not support resizing.
13737	</result>
13738	</desc>
13739	<param name="logicalSize" type="long long" dir="in">
13740	<desc>New nominal capacity of the medium in bytes.</desc>
13741	</param>
13742	<param name="progress" type="IProgress" dir="return">
13743	<desc>Progress object to track the operation completion.</desc>
13744	</param>
13745	</method>
13746
13747	<method name="reset">
13748	<desc>
13749	Starts erasing the contents of this differencing medium.
13750
13751	This operation will reset the differencing medium to its initial
13752	state when it does not contain any sector data and any read operation is
13753	redirected to its parent medium. This automatically gets called
13754	during VM power-up for every medium whose <link to="#autoReset" />
13755	attribute is @c true.
13756
13757	The medium will be write-locked for the duration of this operation (see
13758	<link to="#lockWrite" />).
13759
13760	<result name="VBOX_E_NOT_SUPPORTED">
13761	This is not a differencing medium.
13762	</result>
13763	<result name="VBOX_E_INVALID_OBJECT_STATE">
13764	Medium is not in <link to="MediumState_Created"/> or
13765	<link to="MediumState_Inaccessible"/> state.
13766	</result>
13767	</desc>
13768	<param name="progress" type="IProgress" dir="return">
13769	<desc>Progress object to track the operation completion.</desc>
13770	</param>
13771	</method>
13772
13773	</interface>
13774
13775
13776	<!--
13777	// IMediumFormat
13778	/////////////////////////////////////////////////////////////////////////
13779	-->
13780
13781	<enum
13782	name="DataType"
13783	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
13784	>
13785	<const name="Int32" value="0"/>
13786	<const name="Int8" value="1"/>
13787	<const name="String" value="2"/>
13788	</enum>
13789
13790	<enum
13791	name="DataFlags"
13792	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
13793	>
13794	<const name="None" value="0x00"/>
13795	<const name="Mandatory" value="0x01"/>
13796	<const name="Expert" value="0x02"/>
13797	<const name="Array" value="0x04"/>
13798	<const name="FlagMask" value="0x07"/>
13799	</enum>
13800
13801	<enum
13802	name="MediumFormatCapabilities"
13803	uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
13804	>
13805	<desc>
13806	Medium format capability flags.
13807	</desc>
13808
13809	<const name="Uuid" value="0x01">
13810	<desc>
13811	Supports UUIDs as expected by VirtualBox code.
13812	</desc>
13813	</const>
13814
13815	<const name="CreateFixed" value="0x02">
13816	<desc>
13817	Supports creating fixed size images, allocating all space instantly.
13818	</desc>
13819	</const>
13820
13821	<const name="CreateDynamic" value="0x04">
13822	<desc>
13823	Supports creating dynamically growing images, allocating space on
13824	demand.
13825	</desc>
13826	</const>
13827
13828	<const name="CreateSplit2G" value="0x08">
13829	<desc>
13830	Supports creating images split in chunks of a bit less than 2 GBytes.
13831	</desc>
13832	</const>
13833
13834	<const name="Differencing" value="0x10">
13835	<desc>
13836	Supports being used as a format for differencing media (see <link
13837	to="IMedium::createDiffStorage"/>).
13838	</desc>
13839	</const>
13840
13841	<const name="Asynchronous" value="0x20">
13842	<desc>
13843	Supports asynchronous I/O operations for at least some configurations.
13844	</desc>
13845	</const>
13846
13847	<const name="File" value="0x40">
13848	<desc>
13849	The format backend operates on files (the <link to="IMedium::location"/>
13850	attribute of the medium specifies a file used to store medium
13851	data; for a list of supported file extensions see
13852	<link to="IMediumFormat::describeFileExtensions"/>).
13853	</desc>
13854	</const>
13855
13856	<const name="Properties" value="0x80">
13857	<desc>
13858	The format backend uses the property interface to configure the storage
13859	location and properties (the <link to="IMediumFormat::describeProperties"/>
13860	method is used to get access to properties supported by the given medium format).
13861	</desc>
13862	</const>
13863
13864	<const name="TcpNetworking" value="0x100">
13865	<desc>
13866	The format backend uses the TCP networking interface for network access.
13867	</desc>
13868	</const>
13869
13870	<const name="VFS" value="0x200">
13871	<desc>
13872	The format backend supports virtual filesystem functionality.
13873	</desc>
13874	</const>
13875
13876	<const name="CapabilityMask" value="0x3FF"/>
13877	</enum>
13878
13879	<interface
13880	name="IMediumFormat" extends="$unknown"
13881	uuid="6238e1cf-a17d-4ec1-8172-418bfb22b93a"
13882	wsmap="managed"
13883	>
13884	<desc>
13885	The IMediumFormat interface represents a medium format.
13886
13887	Each medium format has an associated backend which is used to handle
13888	media stored in this format. This interface provides information
13889	about the properties of the associated backend.
13890
13891	Each medium format is identified by a string represented by the
13892	<link to="#id"/> attribute. This string is used in calls like
13893	<link to="IVirtualBox::createHardDisk"/> to specify the desired
13894	format.
13895
13896	The list of all supported medium formats can be obtained using
13897	<link to="ISystemProperties::mediumFormats"/>.
13898
13899	<see><link to="IMedium"/></see>
13900	</desc>
13901
13902	<attribute name="id" type="wstring" readonly="yes">
13903	<desc>
13904	Identifier of this format.
13905
13906	The format identifier is a non-@c null non-empty ASCII string. Note that
13907	this string is case-insensitive. This means that, for example, all of
13908	the following strings:
13909	<pre>
13910	"VDI"
13911	"vdi"
13912	"VdI"</pre>
13913	refer to the same medium format.
13914
13915	This string is used in methods of other interfaces where it is necessary
13916	to specify a medium format, such as
13917	<link to="IVirtualBox::createHardDisk"/>.
13918	</desc>
13919	</attribute>
13920
13921	<attribute name="name" type="wstring" readonly="yes">
13922	<desc>
13923	Human readable description of this format.
13924
13925	Mainly for use in file open dialogs.
13926	</desc>
13927	</attribute>
13928
13929	<attribute name="capabilities" type="MediumFormatCapabilities" safearray="yes" readonly="yes">
13930	<desc>
13931	Capabilities of the format as an array of the flags.
13932
13933	For the meaning of individual capability flags see
13934	<link to="MediumFormatCapabilities"/>.
13935	</desc>
13936	</attribute>
13937
13938	<method name="describeFileExtensions">
13939	<desc>
13940	Returns two arrays describing the supported file extensions.
13941
13942	The first array contains the supported extensions and the seconds one
13943	the type each extension supports. Both have the same size.
13944
13945	Note that some backends do not work on files, so this array may be
13946	empty.
13947
13948	<see><link to="IMediumFormat::capabilities"/></see>
13949	</desc>
13950	<param name="extensions" type="wstring" safearray="yes" dir="out">
13951	<desc>The array of supported extensions.</desc>
13952	</param>
13953	<param name="types" type="DeviceType" safearray="yes" dir="out">
13954	<desc>The array which indicates the device type for every given extension.</desc>
13955	</param>
13956	</method>
13957
13958	<method name="describeProperties" const="yes">
13959	<desc>
13960	Returns several arrays describing the properties supported by this
13961	format.
13962
13963	An element with the given index in each array describes one
13964	property. Thus, the number of elements in each returned array is the
13965	same and corresponds to the number of supported properties.
13966
13967	The returned arrays are filled in only if the
13968	<link to="MediumFormatCapabilities_Properties"/> flag is set.
13969	All arguments must be non-@c null.
13970
13971	<see><link to="DataType"/>, <link to="DataFlags"/></see>
13972	</desc>
13973
13974	<param name="names" type="wstring" safearray="yes" dir="out">
13975	<desc>Array of property names.</desc>
13976	</param>
13977	<param name="descriptions" type="wstring" safearray="yes" dir="out">
13978	<desc>Array of property descriptions.</desc>
13979	</param>
13980	<param name="types" type="DataType" safearray="yes" dir="out">
13981	<desc>Array of property types.</desc>
13982	</param>
13983	<param name="flags" type="unsigned long" safearray="yes" dir="out">
13984	<desc>Array of property flags.</desc>
13985	</param>
13986	<param name="defaults" type="wstring" safearray="yes" dir="out">
13987	<desc>Array of default property values.</desc>
13988	</param>
13989	</method>
13990
13991	</interface>
13992
13993
13994	<!--
13995	// IKeyboard
13996	/////////////////////////////////////////////////////////////////////////
13997	-->
13998
13999	<interface
14000	name="IKeyboard" extends="$unknown"
14001	uuid="f6916ec5-a881-4237-898f-7de58cf88672"
14002	wsmap="managed"
14003	>
14004	<desc>
14005	The IKeyboard interface represents the virtual machine's keyboard. Used
14006	in <link to="IConsole::keyboard"/>.
14007
14008	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
14009	to the virtual machine.
14010
14011	</desc>
14012	<method name="putScancode">
14013	<desc>Sends a scancode to the keyboard.
14014
14015	<result name="VBOX_E_IPRT_ERROR">
14016	Could not send scan code to virtual keyboard.
14017	</result>
14018
14019	</desc>
14020	<param name="scancode" type="long" dir="in"/>
14021	</method>
14022
14023	<method name="putScancodes">
14024	<desc>Sends an array of scancodes to the keyboard.
14025
14026	<result name="VBOX_E_IPRT_ERROR">
14027	Could not send all scan codes to virtual keyboard.
14028	</result>
14029
14030	</desc>
14031	<param name="scancodes" type="long" dir="in" safearray="yes"/>
14032	<param name="codesStored" type="unsigned long" dir="return"/>
14033	</method>
14034
14035	<method name="putCAD">
14036	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
14037	function is nothing special, it is just a convenience function
14038	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
14039
14040	<result name="VBOX_E_IPRT_ERROR">
14041	Could not send all scan codes to virtual keyboard.
14042	</result>
14043
14044	</desc>
14045	</method>
14046
14047	<attribute name="eventSource" type="IEventSource" readonly="yes">
14048	<desc>
14049	Event source for keyboard events.
14050	</desc>
14051	</attribute>
14052
14053	</interface>
14054
14055
14056	<!--
14057	// IMouse
14058	/////////////////////////////////////////////////////////////////////////
14059	-->
14060
14061	<enum
14062	name="MouseButtonState"
14063	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
14064	>
14065	<desc>
14066	Mouse button state.
14067	</desc>
14068
14069	<const name="LeftButton" value="0x01"/>
14070	<const name="RightButton" value="0x02"/>
14071	<const name="MiddleButton" value="0x04"/>
14072	<const name="WheelUp" value="0x08"/>
14073	<const name="WheelDown" value="0x10"/>
14074	<const name="XButton1" value="0x20"/>
14075	<const name="XButton2" value="0x40"/>
14076	<const name="MouseStateMask" value="0x7F"/>
14077	</enum>
14078
14079	<interface
14080	name="IMouse" extends="$unknown"
14081	uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
14082	wsmap="managed"
14083	>
14084	<desc>
14085	The IMouse interface represents the virtual machine's mouse. Used in
14086	<link to="IConsole::mouse"/>.
14087
14088	Through this interface, the virtual machine's virtual mouse can be
14089	controlled.
14090	</desc>
14091
14092	<attribute name="absoluteSupported" type="boolean" readonly="yes">
14093	<desc>
14094	Whether the guest OS supports absolute mouse pointer positioning
14095	or not.
14096	<note>
14097	You can use the <link to="IMouseCapabilityChangedEvent"/>
14098	event to be instantly informed about changes of this attribute
14099	during virtual machine execution.
14100	</note>
14101	<see><link to="#putMouseEventAbsolute"/></see>
14102	</desc>
14103	</attribute>
14104
14105	<attribute name="relativeSupported" type="boolean" readonly="yes">
14106	<desc>
14107	Whether the guest OS supports relative mouse pointer positioning
14108	or not.
14109	<note>
14110	You can use the <link to="IMouseCapabilityChangedEvent"/>
14111	event to be instantly informed about changes of this attribute
14112	during virtual machine execution.
14113	</note>
14114	<see><link to="#putMouseEvent"/></see>
14115	</desc>
14116	</attribute>
14117
14118	<attribute name="needsHostCursor" type="boolean" readonly="yes">
14119	<desc>
14120	Whether the guest OS can currently switch to drawing it's own mouse
14121	cursor on demand.
14122	<note>
14123	You can use the <link to="IMouseCapabilityChangedEvent"/>
14124	event to be instantly informed about changes of this attribute
14125	during virtual machine execution.
14126	</note>
14127	<see><link to="#putMouseEvent"/></see>
14128	</desc>
14129	</attribute>
14130
14131	<method name="putMouseEvent">
14132	<desc>
14133	Initiates a mouse event using relative pointer movements
14134	along x and y axis.
14135
14136	<result name="E_ACCESSDENIED">
14137	Console not powered up.
14138	</result>
14139	<result name="VBOX_E_IPRT_ERROR">
14140	Could not send mouse event to virtual mouse.
14141	</result>
14142
14143	</desc>
14144
14145	<param name="dx" type="long" dir="in">
14146	<desc>
14147	Amount of pixels the mouse should move to the right.
14148	Negative values move the mouse to the left.
14149	</desc>
14150	</param>
14151	<param name="dy" type="long" dir="in">
14152	<desc>
14153	Amount of pixels the mouse should move downwards.
14154	Negative values move the mouse upwards.
14155	</desc>
14156	</param>
14157	<param name="dz" type="long" dir="in">
14158	<desc>
14159	Amount of mouse wheel moves.
14160	Positive values describe clockwise wheel rotations,
14161	negative values describe counterclockwise rotations.
14162	</desc>
14163	</param>
14164	<param name="dw" type="long" dir="in">
14165	<desc>
14166	Amount of horizontal mouse wheel moves.
14167	Positive values describe a movement to the left,
14168	negative values describe a movement to the right.
14169	</desc>
14170	</param>
14171	<param name="buttonState" type="long" dir="in">
14172	<desc>
14173	The current state of mouse buttons. Every bit represents
14174	a mouse button as follows:
14175	<table>
14176	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14177	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14178	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14179	</table>
14180	A value of <tt>1</tt> means the corresponding button is pressed.
14181	otherwise it is released.
14182	</desc>
14183	</param>
14184	</method>
14185
14186	<method name="putMouseEventAbsolute">
14187	<desc>
14188	Positions the mouse pointer using absolute x and y coordinates.
14189	These coordinates are expressed in pixels and
14190	start from <tt>[1,1]</tt> which corresponds to the top left
14191	corner of the virtual display.
14192
14193	<result name="E_ACCESSDENIED">
14194	Console not powered up.
14195	</result>
14196	<result name="VBOX_E_IPRT_ERROR">
14197	Could not send mouse event to virtual mouse.
14198	</result>
14199
14200	<note>
14201	This method will have effect only if absolute mouse
14202	positioning is supported by the guest OS.
14203	</note>
14204
14205	<see><link to="#absoluteSupported"/></see>
14206	</desc>
14207
14208	<param name="x" type="long" dir="in">
14209	<desc>
14210	X coordinate of the pointer in pixels, starting from @c 1.
14211	</desc>
14212	</param>
14213	<param name="y" type="long" dir="in">
14214	<desc>
14215	Y coordinate of the pointer in pixels, starting from @c 1.
14216	</desc>
14217	</param>
14218	<param name="dz" type="long" dir="in">
14219	<desc>
14220	Amount of mouse wheel moves.
14221	Positive values describe clockwise wheel rotations,
14222	negative values describe counterclockwise rotations.
14223	</desc>
14224	</param>
14225	<param name="dw" type="long" dir="in">
14226	<desc>
14227	Amount of horizontal mouse wheel moves.
14228	Positive values describe a movement to the left,
14229	negative values describe a movement to the right.
14230	</desc>
14231	</param>
14232	<param name="buttonState" type="long" dir="in">
14233	<desc>
14234	The current state of mouse buttons. Every bit represents
14235	a mouse button as follows:
14236	<table>
14237	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14238	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14239	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14240	</table>
14241	A value of @c 1 means the corresponding button is pressed.
14242	otherwise it is released.
14243	</desc>
14244	</param>
14245	</method>
14246
14247	<attribute name="eventSource" type="IEventSource" readonly="yes">
14248	<desc>
14249	Event source for mouse events.
14250	</desc>
14251	</attribute>
14252
14253	</interface>
14254
14255	<!--
14256	// IDisplay
14257	/////////////////////////////////////////////////////////////////////////
14258	-->
14259
14260	<enum
14261	name="FramebufferPixelFormat"
14262	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
14263	>
14264	<desc>
14265	Format of the video memory buffer. Constants represented by this enum can
14266	be used to test for particular values of <link
14267	to="IFramebuffer::pixelFormat"/>. See also <link
14268	to="IFramebuffer::requestResize"/>.
14269
14270	See also www.fourcc.org for more information about FOURCC pixel formats.
14271	</desc>
14272
14273	<const name="Opaque" value="0">
14274	<desc>
14275	Unknown buffer format (the user may not assume any particular format of
14276	the buffer).
14277	</desc>
14278	</const>
14279	<const name="FOURCC_RGB" value="0x32424752">
14280	<desc>
14281	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
14282	bit layout).
14283	</desc>
14284	</const>
14285	</enum>
14286
14287	<interface
14288	name="IFramebuffer" extends="$unknown"
14289	uuid="e3f122c0-adab-4fc9-a8dc-da112fb48428"
14290	wsmap="suppress"
14291	>
14292	<attribute name="address" type="octet" mod="ptr" readonly="yes">
14293	<desc>Address of the start byte of the frame buffer.</desc>
14294	</attribute>
14295
14296	<attribute name="width" type="unsigned long" readonly="yes">
14297	<desc>Frame buffer width, in pixels.</desc>
14298	</attribute>
14299
14300	<attribute name="height" type="unsigned long" readonly="yes">
14301	<desc>Frame buffer height, in pixels.</desc>
14302	</attribute>
14303
14304	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
14305	<desc>
14306	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
14307	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
14308	are: 8, 15, 16, 24 and 32.
14309	</desc>
14310	</attribute>
14311
14312	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
14313	<desc>
14314	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
14315	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
14316	size of the scan line must be aligned to 32 bits.
14317	</desc>
14318	</attribute>
14319
14320	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
14321	<desc>
14322	Frame buffer pixel format. It's either one of the values defined by <link
14323	to="FramebufferPixelFormat"/> or a raw FOURCC code.
14324	<note>
14325	This attribute must never return <link
14326	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
14327	<link to="#address"/> points to must be always known.
14328	</note>
14329	</desc>
14330	</attribute>
14331
14332	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
14333	<desc>
14334	Defines whether this frame buffer uses the virtual video card's memory
14335	buffer (guest VRAM) directly or not. See <link
14336	to="IFramebuffer::requestResize"/> for more information.
14337	</desc>
14338	</attribute>
14339
14340	<attribute name="heightReduction" type="unsigned long" readonly="yes">
14341	<desc>
14342	Hint from the frame buffer about how much of the standard
14343	screen height it wants to use for itself. This information is
14344	exposed to the guest through the VESA BIOS and VMMDev interface
14345	so that it can use it for determining its video mode table. It
14346	is not guaranteed that the guest respects the value.
14347	</desc>
14348	</attribute>
14349
14350	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
14351	<desc>
14352	An alpha-blended overlay which is superposed over the frame buffer.
14353	The initial purpose is to allow the display of icons providing
14354	information about the VM state, including disk activity, in front
14355	ends which do not have other means of doing that. The overlay is
14356	designed to controlled exclusively by IDisplay. It has no locking
14357	of its own, and any changes made to it are not guaranteed to be
14358	visible until the affected portion of IFramebuffer is updated. The
14359	overlay can be created lazily the first time it is requested. This
14360	attribute can also return @c null to signal that the overlay is not
14361	implemented.
14362	</desc>
14363	</attribute>
14364
14365	<attribute name="winId" type="long long" readonly="yes">
14366	<desc>
14367	Platform-dependent identifier of the window where context of this
14368	frame buffer is drawn, or zero if there's no such window.
14369	</desc>
14370	</attribute>
14371
14372	<method name="lock">
14373	<desc>
14374	Locks the frame buffer.
14375	Gets called by the IDisplay object where this frame buffer is
14376	bound to.
14377	</desc>
14378	</method>
14379
14380	<method name="unlock">
14381	<desc>
14382	Unlocks the frame buffer.
14383	Gets called by the IDisplay object where this frame buffer is
14384	bound to.
14385	</desc>
14386	</method>
14387
14388	<method name="notifyUpdate">
14389	<desc>
14390	Informs about an update.
14391	Gets called by the display object where this buffer is
14392	registered.
14393	</desc>
14394	<param name="x" type="unsigned long" dir="in"/>
14395	<param name="y" type="unsigned long" dir="in"/>
14396	<param name="width" type="unsigned long" dir="in"/>
14397	<param name="height" type="unsigned long" dir="in"/>
14398	</method>
14399
14400	<method name="requestResize">
14401	<desc>
14402	Requests a size and pixel format change.
14403
14404	There are two modes of working with the video buffer of the virtual
14405	machine. The <i>indirect</i> mode implies that the IFramebuffer
14406	implementation allocates a memory buffer for the requested display mode
14407	and provides it to the virtual machine. In <i>direct</i> mode, the
14408	IFramebuffer implementation uses the memory buffer allocated and owned
14409	by the virtual machine. This buffer represents the video memory of the
14410	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
14411	usually faster because the implementation gets a raw pointer to the
14412	guest VRAM buffer which it can directly use for visualizing the contents
14413	of the virtual display, as opposed to the indirect mode where the
14414	contents of guest VRAM are copied to the memory buffer provided by
14415	the implementation every time a display update occurs.
14416
14417	It is important to note that the direct mode is really fast only when
14418	the implementation uses the given guest VRAM buffer directly, for
14419	example, by blitting it to the window representing the virtual machine's
14420	display, which saves at least one copy operation comparing to the
14421	indirect mode. However, using the guest VRAM buffer directly is not
14422	always possible: the format and the color depth of this buffer may be
14423	not supported by the target window, or it may be unknown (opaque) as in
14424	case of text or non-linear multi-plane VGA video modes. In this case,
14425	the indirect mode (that is always available) should be used as a
14426	fallback: when the guest VRAM contents are copied to the
14427	implementation-provided memory buffer, color and format conversion is
14428	done automatically by the underlying code.
14429
14430	The @a pixelFormat parameter defines whether the direct mode is
14431	available or not. If @a pixelFormat is <link
14432	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
14433	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
14434	@a bytesPerLine parameters must be ignored and the implementation must use
14435	the indirect mode (where it provides its own buffer in one of the
14436	supported formats). In all other cases, @a pixelFormat together with
14437	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
14438	buffer pointed to by the @a VRAM parameter and the implementation is
14439	free to choose which mode to use. To indicate that this frame buffer uses
14440	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
14441	attribute must return @c true and <link to="#address"/> must
14442	return exactly the same address that is passed in the @a VRAM parameter
14443	of this method; otherwise it is assumed that the indirect strategy is
14444	chosen.
14445
14446	The @a width and @a height parameters represent the size of the
14447	requested display mode in both modes. In case of indirect mode, the
14448	provided memory buffer should be big enough to store data of the given
14449	display mode. In case of direct mode, it is guaranteed that the given
14450	@a VRAM buffer contains enough space to represent the display mode of the
14451	given size. Note that this frame buffer's <link to="#width"/> and <link
14452	to="#height"/> attributes must return exactly the same values as
14453	passed to this method after the resize is completed (see below).
14454
14455	The @a finished output parameter determines if the implementation has
14456	finished resizing the frame buffer or not. If, for some reason, the
14457	resize cannot be finished immediately during this call, @a finished
14458	must be set to @c false, and the implementation must call
14459	<link to="IDisplay::resizeCompleted"/> after it has returned from
14460	this method as soon as possible. If @a finished is @c false, the
14461	machine will not call any frame buffer methods until
14462	<link to="IDisplay::resizeCompleted"/> is called.
14463
14464	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
14465	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
14466	this frame buffer must return exactly the same values as specified in the
14467	parameters of this method, after the resize is completed. If the
14468	indirect mode is chosen, these attributes must return values describing
14469	the format of the implementation's own memory buffer <link
14470	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
14471	value must always correlate with <link to="#pixelFormat"/>. Note that
14472	the <link to="#pixelFormat"/> attribute must never return <link
14473	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
14474
14475	<note>
14476	This method is called by the IDisplay object under the
14477	<link to="#lock"/> provided by this IFramebuffer
14478	implementation. If this method returns @c false in @a finished, then
14479	this lock is not released until
14480	<link to="IDisplay::resizeCompleted"/> is called.
14481	</note>
14482	</desc>
14483	<param name="screenId" type="unsigned long" dir="in">
14484	<desc>
14485	Logical screen number. Must be used in the corresponding call to
14486	<link to="IDisplay::resizeCompleted"/> if this call is made.
14487	</desc>
14488	</param>
14489	<param name="pixelFormat" type="unsigned long" dir="in">
14490	<desc>
14491	Pixel format of the memory buffer pointed to by @a VRAM.
14492	See also <link to="FramebufferPixelFormat"/>.
14493	</desc>
14494	</param>
14495	<param name="VRAM" type="octet" mod="ptr" dir="in">
14496	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
14497	</param>
14498	<param name="bitsPerPixel" type="unsigned long" dir="in">
14499	<desc>Color depth, bits per pixel.</desc>
14500	</param>
14501	<param name="bytesPerLine" type="unsigned long" dir="in">
14502	<desc>Size of one scan line, in bytes.</desc>
14503	</param>
14504	<param name="width" type="unsigned long" dir="in">
14505	<desc>Width of the guest display, in pixels.</desc>
14506	</param>
14507	<param name="height" type="unsigned long" dir="in">
14508	<desc>Height of the guest display, in pixels.</desc>
14509	</param>
14510	<param name="finished" type="boolean" dir="return">
14511	<desc>
14512	Can the VM start using the new frame buffer immediately
14513	after this method returns or it should wait for
14514	<link to="IDisplay::resizeCompleted"/>.
14515	</desc>
14516	</param>
14517	</method>
14518
14519	<method name="videoModeSupported">
14520	<desc>
14521	Returns whether the frame buffer implementation is willing to
14522	support a given video mode. In case it is not able to render
14523	the video mode (or for some reason not willing), it should
14524	return @c false. Usually this method is called when the guest
14525	asks the VMM device whether a given video mode is supported
14526	so the information returned is directly exposed to the guest.
14527	It is important that this method returns very quickly.
14528	</desc>
14529	<param name="width" type="unsigned long" dir="in"/>
14530	<param name="height" type="unsigned long" dir="in"/>
14531	<param name="bpp" type="unsigned long" dir="in"/>
14532	<param name="supported" type="boolean" dir="return"/>
14533	</method>
14534
14535	<method name="getVisibleRegion">
14536	<desc>
14537	Returns the visible region of this frame buffer.
14538
14539	If the @a rectangles parameter is @c null then the value of the
14540	@a count parameter is ignored and the number of elements necessary to
14541	describe the current visible region is returned in @a countCopied.
14542
14543	If @a rectangles is not @c null but @a count is less
14544	than the required number of elements to store region data, the method
14545	will report a failure. If @a count is equal or greater than the
14546	required number of elements, then the actual number of elements copied
14547	to the provided array will be returned in @a countCopied.
14548
14549	<note>
14550	The address of the provided array must be in the process space of
14551	this IFramebuffer object.
14552	</note>
14553	<note>
14554	Method not yet implemented.
14555	</note>
14556	</desc>
14557	<param name="rectangles" type="octet" mod="ptr" dir="in">
14558	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
14559	</param>
14560	<param name="count" type="unsigned long" dir="in">
14561	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14562	</param>
14563	<param name="countCopied" type="unsigned long" dir="return">
14564	<desc>Number of elements copied to the @a rectangles array.</desc>
14565	</param>
14566	</method>
14567
14568	<method name="setVisibleRegion">
14569	<desc>
14570	Suggests a new visible region to this frame buffer. This region
14571	represents the area of the VM display which is a union of regions of
14572	all top-level windows of the guest operating system running inside the
14573	VM (if the Guest Additions for this system support this
14574	functionality). This information may be used by the frontends to
14575	implement the seamless desktop integration feature.
14576
14577	<note>
14578	The address of the provided array must be in the process space of
14579	this IFramebuffer object.
14580	</note>
14581	<note>
14582	The IFramebuffer implementation must make a copy of the provided
14583	array of rectangles.
14584	</note>
14585	<note>
14586	Method not yet implemented.
14587	</note>
14588	</desc>
14589	<param name="rectangles" type="octet" mod="ptr" dir="in">
14590	<desc>Pointer to the @c RTRECT array.</desc>
14591	</param>
14592	<param name="count" type="unsigned long" dir="in">
14593	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14594	</param>
14595	</method>
14596
14597	<method name="processVHWACommand">
14598	<desc>
14599	Posts a Video HW Acceleration Command to the frame buffer for processing.
14600	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
14601	are posted from quest to the host to be processed by the host hardware.
14602
14603	<note>
14604	The address of the provided command must be in the process space of
14605	this IFramebuffer object.
14606	</note>
14607	</desc>
14608
14609	<param name="command" type="octet" mod="ptr" dir="in">
14610	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
14611	</param>
14612	</method>
14613
14614	<method name="notify3DEvent">
14615	<desc>
14616	Notifies framebuffer about 3D backend event.
14617	</desc>
14618
14619	<param name="type" type="unsigned long" dir="in">
14620	<desc>event type. Currently only VBOX3D_NOTIFY_EVENT_TYPE_VISIBLE_WINDOW is supported.</desc>
14621	</param>
14622	<param name="reserved" type="octet" mod="ptr" dir="in">
14623	<desc>Reserved for future use, must be NULL.</desc>
14624	</param>
14625	</method>
14626
14627	</interface>
14628
14629	<interface
14630	name="IFramebufferOverlay" extends="IFramebuffer"
14631	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
14632	wsmap="suppress"
14633	>
14634	<desc>
14635	The IFramebufferOverlay interface represents an alpha blended overlay
14636	for displaying status icons above an IFramebuffer. It is always created
14637	not visible, so that it must be explicitly shown. It only covers a
14638	portion of the IFramebuffer, determined by its width, height and
14639	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
14640	that order) format, and may be written to directly. Do re-read the
14641	width though, after setting it, as it may be adjusted (increased) to
14642	make it more suitable for the front end.
14643	</desc>
14644	<attribute name="x" type="unsigned long" readonly="yes">
14645	<desc>X position of the overlay, relative to the frame buffer.</desc>
14646	</attribute>
14647
14648	<attribute name="y" type="unsigned long" readonly="yes">
14649	<desc>Y position of the overlay, relative to the frame buffer.</desc>
14650	</attribute>
14651
14652	<attribute name="visible" type="boolean">
14653	<desc>
14654	Whether the overlay is currently visible.
14655	</desc>
14656	</attribute>
14657
14658	<attribute name="alpha" type="unsigned long">
14659	<desc>
14660	The global alpha value for the overlay. This may or may not be
14661	supported by a given front end.
14662	</desc>
14663	</attribute>
14664
14665	<method name="move">
14666	<desc>
14667	Changes the overlay's position relative to the IFramebuffer.
14668	</desc>
14669	<param name="x" type="unsigned long" dir="in"/>
14670	<param name="y" type="unsigned long" dir="in"/>
14671	</method>
14672
14673	</interface>
14674
14675	<interface
14676	name="IDisplay" extends="$unknown"
14677	uuid="0598a3df-3dc0-43c7-a79c-237fb5bb633d"
14678	wsmap="managed"
14679	>
14680	<desc>
14681	The IDisplay interface represents the virtual machine's display.
14682
14683	The object implementing this interface is contained in each
14684	<link to="IConsole::display"/> attribute and represents the visual
14685	output of the virtual machine.
14686
14687	The virtual display supports pluggable output targets represented by the
14688	IFramebuffer interface. Examples of the output target are a window on
14689	the host computer or an RDP session's display on a remote computer.
14690	</desc>
14691	<method name="getScreenResolution">
14692	<desc>Queries display width, height and color depth for given screen.</desc>
14693	<param name="screenId" type="unsigned long" dir="in"/>
14694	<param name="width" type="unsigned long" dir="out"/>
14695	<param name="height" type="unsigned long" dir="out"/>
14696	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
14697	</method>
14698
14699	<method name="setFramebuffer">
14700	<desc>
14701	Sets the framebuffer for given screen.
14702	</desc>
14703	<param name="screenId" type="unsigned long" dir="in"/>
14704	<param name="framebuffer" type="IFramebuffer" dir="in"/>
14705	</method>
14706
14707	<method name="getFramebuffer">
14708	<desc>
14709	Queries the framebuffer for given screen.
14710	</desc>
14711	<param name="screenId" type="unsigned long" dir="in"/>
14712	<param name="framebuffer" type="IFramebuffer" dir="out"/>
14713	<param name="xOrigin" type="long" dir="out"/>
14714	<param name="yOrigin" type="long" dir="out"/>
14715	</method>
14716
14717	<method name="setVideoModeHint">
14718	<desc>
14719	Asks VirtualBox to request the given video mode from
14720	the guest. This is just a hint and it cannot be guaranteed
14721	that the requested resolution will be used. Guest Additions
14722	are required for the request to be seen by guests. The caller
14723	should issue the request and wait for a resolution change and
14724	after a timeout retry.
14725
14726	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
14727	parameters means that the corresponding values should be taken from the
14728	current video mode (i.e. left unchanged).
14729
14730	If the guest OS supports multi-monitor configuration then the @a display
14731	parameter specifies the number of the guest display to send the hint to:
14732	@c 0 is the primary display, @c 1 is the first secondary and
14733	so on. If the multi-monitor configuration is not supported, @a display
14734	must be @c 0.
14735
14736	<result name="E_INVALIDARG">
14737	The @a display is not associated with any monitor.
14738	</result>
14739
14740	</desc>
14741	<param name="display" type="unsigned long" dir="in">
14742	<desc>
14743	The number of the guest display to send the hint to.
14744	</desc>
14745	</param>
14746	<param name="enabled" type="boolean" dir="in">
14747	<desc>
14748	@c True, if this guest screen is enabled,
14749	@c False otherwise.
14750	</desc>
14751	</param>
14752	<param name="changeOrigin" type="boolean" dir="in">
14753	<desc>
14754	@c True, if the origin of the guest screen should be changed,
14755	@c False otherwise.
14756	</desc>
14757	</param>
14758	<param name="originX" type="long" dir="in">
14759	<desc>
14760	The X origin of the guest screen.
14761	</desc>
14762	</param>
14763	<param name="originY" type="long" dir="in">
14764	<desc>
14765	The Y origin of the guest screen.
14766	</desc>
14767	</param>
14768	<param name="width" type="unsigned long" dir="in"/>
14769	<param name="height" type="unsigned long" dir="in"/>
14770	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
14771	</method>
14772
14773	<method name="setSeamlessMode">
14774	<desc>
14775	Enables or disables seamless guest display rendering (seamless desktop
14776	integration) mode.
14777	<note>
14778	Calling this method has no effect if <link
14779	to="IGuest::getFacilityStatus"/> with facility @c Seamless
14780	does not return @c Active.
14781	</note>
14782	</desc>
14783	<param name="enabled" type="boolean" dir="in"/>
14784	</method>
14785
14786	<method name="takeScreenShot">
14787	<desc>
14788	Takes a screen shot of the requested size and copies it to the
14789	32-bpp buffer allocated by the caller and pointed to by @a address.
14790	A pixel consists of 4 bytes in order: B, G, R, 0.
14791
14792	<note>This API can be used only locally by a VM process through the
14793	COM/XPCOM C++ API as it requires pointer support. It is not
14794	available for scripting langages, Java or any webservice clients.
14795	Unless you are writing a new VM frontend use
14796	<link to="#takeScreenShotToArray" />.
14797	</note>
14798
14799	<result name="E_NOTIMPL">
14800	Feature not implemented.
14801	</result>
14802	<result name="VBOX_E_IPRT_ERROR">
14803	Could not take a screenshot.
14804	</result>
14805
14806	</desc>
14807	<param name="screenId" type="unsigned long" dir="in"/>
14808	<param name="address" type="octet" mod="ptr" dir="in"/>
14809	<param name="width" type="unsigned long" dir="in"/>
14810	<param name="height" type="unsigned long" dir="in"/>
14811	</method>
14812
14813	<method name="takeScreenShotToArray">
14814	<desc>
14815	Takes a guest screen shot of the requested size and returns it as
14816	an array of bytes in uncompressed 32-bpp RGBA format.
14817	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
14818
14819	This API is slow, but could be the only option to get guest screenshot
14820	for scriptable languages not allowed to manipulate with addresses
14821	directly.
14822
14823	<result name="E_NOTIMPL">
14824	Feature not implemented.
14825	</result>
14826	<result name="VBOX_E_IPRT_ERROR">
14827	Could not take a screenshot.
14828	</result>
14829	</desc>
14830	<param name="screenId" type="unsigned long" dir="in">
14831	<desc>
14832	Monitor to take screenshot from.
14833	</desc>
14834	</param>
14835	<param name="width" type="unsigned long" dir="in">
14836	<desc>
14837	Desired image width.
14838	</desc>
14839	</param>
14840	<param name="height" type="unsigned long" dir="in">
14841	<desc>
14842	Desired image height.
14843	</desc>
14844	</param>
14845	<param name="screenData" type="octet" dir="return" safearray="yes">
14846	<desc>
14847	Array with resulting screen data.
14848	</desc>
14849	</param>
14850	</method>
14851
14852	<method name="takeScreenShotPNGToArray">
14853	<desc>
14854	Takes a guest screen shot of the requested size and returns it as
14855	PNG image in array.
14856
14857	<result name="E_NOTIMPL">
14858	Feature not implemented.
14859	</result>
14860	<result name="VBOX_E_IPRT_ERROR">
14861	Could not take a screenshot.
14862	</result>
14863	</desc>
14864	<param name="screenId" type="unsigned long" dir="in">
14865	<desc>
14866	Monitor to take the screenshot from.
14867	</desc>
14868	</param>
14869	<param name="width" type="unsigned long" dir="in">
14870	<desc>
14871	Desired image width.
14872	</desc>
14873	</param>
14874	<param name="height" type="unsigned long" dir="in">
14875	<desc>
14876	Desired image height.
14877	</desc>
14878	</param>
14879	<param name="screenData" type="octet" dir="return" safearray="yes">
14880	<desc>
14881	Array with resulting screen data.
14882	</desc>
14883	</param>
14884	</method>
14885
14886	<method name="enableVideoCapture">
14887	<desc>
14888	Start/continue video capture.
14889	</desc>
14890	<param name="screens" type="boolean" safearray="yes" dir="in">
14891	<desc>
14892	The screens to start/continue capturing.
14893	</desc>
14894	</param>
14895	</method>
14896
14897	<method name="disableVideoCapture">
14898	<desc>
14899	Stop video capture.
14900	</desc>
14901	<param name="screens" type="boolean" safearray="yes" dir="in">
14902	<desc>
14903	The screens to stop capturing.
14904	</desc>
14905	</param>
14906	</method>
14907
14908	<method name="drawToScreen">
14909	<desc>
14910	Draws a 32-bpp image of the specified size from the given buffer
14911	to the given point on the VM display.
14912
14913	<result name="E_NOTIMPL">
14914	Feature not implemented.
14915	</result>
14916	<result name="VBOX_E_IPRT_ERROR">
14917	Could not draw to screen.
14918	</result>
14919
14920	</desc>
14921	<param name="screenId" type="unsigned long" dir="in">
14922	<desc>
14923	Monitor to take the screenshot from.
14924	</desc>
14925	</param>
14926	<param name="address" type="octet" mod="ptr" dir="in">
14927	<desc>
14928	Address to store the screenshot to
14929	</desc>
14930	</param>
14931	<param name="x" type="unsigned long" dir="in">
14932	<desc>
14933	Relative to the screen top left corner.
14934	</desc>
14935	</param>
14936	<param name="y" type="unsigned long" dir="in">
14937	<desc>
14938	Relative to the screen top left corner.
14939	</desc>
14940	</param>
14941	<param name="width" type="unsigned long" dir="in">
14942	<desc>
14943	Desired image width.
14944	</desc>
14945	</param>
14946	<param name="height" type="unsigned long" dir="in">
14947	<desc>
14948	Desired image height.
14949	</desc>
14950	</param>
14951	</method>
14952
14953	<method name="invalidateAndUpdate">
14954	<desc>
14955	Does a full invalidation of the VM display and instructs the VM
14956	to update it.
14957
14958	<result name="VBOX_E_IPRT_ERROR">
14959	Could not invalidate and update screen.
14960	</result>
14961
14962	</desc>
14963	</method>
14964
14965	<method name="resizeCompleted">
14966	<desc>
14967	Signals that a framebuffer has completed the resize operation.
14968
14969	<result name="VBOX_E_NOT_SUPPORTED">
14970	Operation only valid for external frame buffers.
14971	</result>
14972
14973	</desc>
14974	<param name="screenId" type="unsigned long" dir="in"/>
14975	</method>
14976
14977	<method name="completeVHWACommand">
14978	<desc>
14979	Signals that the Video HW Acceleration command has completed.
14980	</desc>
14981
14982	<param name="command" type="octet" mod="ptr" dir="in">
14983	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
14984	</param>
14985	</method>
14986
14987	<method name="viewportChanged">
14988	<desc>
14989	Signals that framebuffer window viewport has changed.
14990
14991	<result name="E_INVALIDARG">
14992	The specified viewport data is invalid.
14993	</result>
14994
14995	</desc>
14996
14997	<param name="screenId" type="unsigned long" dir="in">
14998	<desc>
14999	Monitor to take the screenshot from.
15000	</desc>
15001	</param>
15002	<param name="x" type="unsigned long" dir="in">
15003	<desc>
15004	Framebuffer x offset.
15005	</desc>
15006	</param>
15007	<param name="y" type="unsigned long" dir="in">
15008	<desc>
15009	Framebuffer y offset.
15010	</desc>
15011	</param>
15012	<param name="width" type="unsigned long" dir="in">
15013	<desc>
15014	Viewport width.
15015	</desc>
15016	</param>
15017	<param name="height" type="unsigned long" dir="in">
15018	<desc>
15019	Viewport height.
15020	</desc>
15021	</param>
15022	</method>
15023	</interface>
15024
15025	<!--
15026	// INetworkAdapter
15027	/////////////////////////////////////////////////////////////////////////
15028	-->
15029
15030	<enum
15031	name="NetworkAttachmentType"
15032	uuid="2ac4bc71-6b82-417a-acd1-f7426d2570d6"
15033	>
15034	<desc>
15035	Network attachment type.
15036	</desc>
15037
15038	<const name="Null" value="0">
15039	<desc>Null value, also means "not attached".</desc>
15040	</const>
15041	<const name="NAT" value="1"/>
15042	<const name="Bridged" value="2"/>
15043	<const name="Internal" value="3"/>
15044	<const name="HostOnly" value="4"/>
15045	<const name="Generic" value="5"/>
15046	</enum>
15047
15048	<enum
15049	name="NetworkAdapterType"
15050	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
15051	>
15052	<desc>
15053	Network adapter type.
15054	</desc>
15055
15056	<const name="Null" value="0">
15057	<desc>Null value (never used by the API).</desc>
15058	</const>
15059	<const name="Am79C970A" value="1">
15060	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
15061	</const>
15062	<const name="Am79C973" value="2">
15063	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
15064	</const>
15065	<const name="I82540EM" value="3">
15066	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
15067	</const>
15068	<const name="I82543GC" value="4">
15069	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
15070	</const>
15071	<const name="I82545EM" value="5">
15072	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
15073	</const>
15074	<const name="Virtio" value="6">
15075	<desc>Virtio network device.</desc>
15076	</const>
15077	</enum>
15078
15079	<enum
15080	name="NetworkAdapterPromiscModePolicy"
15081	uuid="c963768a-376f-4c85-8d84-d8ced4b7269e"
15082	>
15083	<desc>
15084	The promiscuous mode policy of an interface.
15085	</desc>
15086
15087	<const name="Deny" value="1">
15088	<desc>Deny promiscuous mode requests.</desc>
15089	</const>
15090	<const name="AllowNetwork" value="2">
15091	<desc>
15092	Allow promicuous mode, but restrict the scope it to the internal
15093	network so that it only applies to other VMs.
15094	</desc>
15095	</const>
15096	<const name="AllowAll" value="3">
15097	<desc>
15098	Allow promicuous mode, include unrelated traffic going over the wire
15099	and internally on the host.
15100	</desc>
15101	</const>
15102	</enum>
15103
15104	<interface
15105	name="INetworkAdapter" extends="$unknown"
15106	uuid="efa0f965-63c7-4c60-afdf-b1cc9943b9c0"
15107	wsmap="managed"
15108	>
15109	<desc>
15110	Represents a virtual network adapter that is attached to a virtual machine.
15111	Each virtual machine has a fixed number of network adapter slots with one
15112	instance of this attached to each of them. Call
15113	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
15114	is attached to a given slot in a given machine.
15115
15116	Each network adapter can be in one of five attachment modes, which are
15117	represented by the <link to="NetworkAttachmentType" /> enumeration;
15118	see the <link to="#attachmentType" /> attribute.
15119	</desc>
15120
15121	<attribute name="adapterType" type="NetworkAdapterType">
15122	<desc>
15123	Type of the virtual network adapter. Depending on this value,
15124	VirtualBox will provide a different virtual network hardware
15125	to the guest.
15126	</desc>
15127	</attribute>
15128
15129	<attribute name="slot" type="unsigned long" readonly="yes">
15130	<desc>
15131	Slot number this adapter is plugged into. Corresponds to
15132	the value you pass to <link to="IMachine::getNetworkAdapter"/>
15133	to obtain this instance.
15134	</desc>
15135	</attribute>
15136
15137	<attribute name="enabled" type="boolean">
15138	<desc>
15139	Flag whether the network adapter is present in the
15140	guest system. If disabled, the virtual guest hardware will
15141	not contain this network adapter. Can only be changed when
15142	the VM is not running.
15143	</desc>
15144	</attribute>
15145
15146	<attribute name="MACAddress" type="wstring">
15147	<desc>
15148	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
15149	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
15150	</desc>
15151	</attribute>
15152
15153	<attribute name="attachmentType" type="NetworkAttachmentType">
15154	<desc>
15155	Sets/Gets network attachment type of this network adapter.
15156	</desc>
15157	</attribute>
15158
15159	<attribute name="bridgedInterface" type="wstring">
15160	<desc>
15161	Name of the network interface the VM should be bridged to.
15162	</desc>
15163	</attribute>
15164
15165	<attribute name="hostOnlyInterface" type="wstring">
15166	<desc>
15167	Name of the host only network interface the VM is attached to.
15168	</desc>
15169	</attribute>
15170
15171	<attribute name="internalNetwork" type="wstring">
15172	<desc>
15173	Name of the internal network the VM is attached to.
15174	</desc>
15175	</attribute>
15176
15177	<attribute name="NATNetwork" type="wstring">
15178	<desc>
15179	Name of the NAT network the VM is attached to.
15180	</desc>
15181	</attribute>
15182
15183	<attribute name="genericDriver" type="wstring">
15184	<desc>
15185	Name of the driver to use for the "Generic" network attachment type.
15186	</desc>
15187	</attribute>
15188
15189	<attribute name="cableConnected" type="boolean">
15190	<desc>
15191	Flag whether the adapter reports the cable as connected or not.
15192	It can be used to report offline situations to a VM.
15193	</desc>
15194	</attribute>
15195
15196	<attribute name="lineSpeed" type="unsigned long">
15197	<desc>
15198	Line speed reported by custom drivers, in units of 1 kbps.
15199	</desc>
15200	</attribute>
15201
15202	<attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy">
15203	<desc>
15204	The promiscuous mode policy of the network adapter when attached to an
15205	internal network, host only network or a bridge.
15206	</desc>
15207	</attribute>
15208
15209	<attribute name="traceEnabled" type="boolean">
15210	<desc>
15211	Flag whether network traffic from/to the network card should be traced.
15212	Can only be toggled when the VM is turned off.
15213	</desc>
15214	</attribute>
15215
15216	<attribute name="traceFile" type="wstring">
15217	<desc>
15218	Filename where a network trace will be stored. If not set, VBox-pid.pcap
15219	will be used.
15220	</desc>
15221	</attribute>
15222
15223	<attribute name="NATEngine" type="INATEngine" readonly="yes">
15224	<desc>
15225	Points to the NAT engine which handles the network address translation
15226	for this interface. This is active only when the interface actually uses
15227	NAT.
15228	</desc>
15229	</attribute>
15230
15231	<attribute name="bootPriority" type="unsigned long">
15232	<desc>
15233	Network boot priority of the adapter. Priority 1 is highest. If not set,
15234	the priority is considered to be at the lowest possible setting.
15235	</desc>
15236	</attribute>
15237
15238	<attribute name="bandwidthGroup" type="IBandwidthGroup">
15239	<desc>The bandwidth group this network adapter is assigned to.</desc>
15240	</attribute>
15241
15242	<!-- property methods -->
15243
15244	<method name="getProperty" const="yes">
15245	<desc>
15246	Returns the value of the network attachment property with the given name.
15247
15248	If the requested data @a key does not exist, this function will
15249	succeed and return an empty string in the @a value argument.
15250
15251	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15252	</desc>
15253	<param name="key" type="wstring" dir="in">
15254	<desc>Name of the property to get.</desc>
15255	</param>
15256	<param name="value" type="wstring" dir="return">
15257	<desc>Current property value.</desc>
15258	</param>
15259	</method>
15260
15261	<method name="setProperty">
15262	<desc>
15263	Sets the value of the network attachment property with the given name.
15264
15265	Setting the property value to @c null or an empty string is equivalent
15266	to deleting the existing value.
15267
15268	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15269	</desc>
15270	<param name="key" type="wstring" dir="in">
15271	<desc>Name of the property to set.</desc>
15272	</param>
15273	<param name="value" type="wstring" dir="in">
15274	<desc>Property value to set.</desc>
15275	</param>
15276	</method>
15277
15278	<method name="getProperties" const="yes">
15279	<desc>
15280	Returns values for a group of properties in one call.
15281
15282	The names of the properties to get are specified using the @a names
15283	argument which is a list of comma-separated property names or
15284	an empty string if all properties are to be returned.
15285	<note>Currently the value of this argument is ignored and the method
15286	always returns all existing properties.</note>
15287
15288	The method returns two arrays, the array of property names corresponding
15289	to the @a names argument and the current values of these properties.
15290	Both arrays have the same number of elements with each element at the
15291	given index in the first array corresponds to an element at the same
15292	index in the second array.
15293	</desc>
15294	<param name="names" type="wstring" dir="in">
15295	<desc>
15296	Names of properties to get.
15297	</desc>
15298	</param>
15299	<param name="returnNames" type="wstring" safearray="yes" dir="out">
15300	<desc>Names of returned properties.</desc>
15301	</param>
15302	<param name="returnValues" type="wstring" safearray="yes" dir="return">
15303	<desc>Values of returned properties.</desc>
15304	</param>
15305	</method>
15306
15307	</interface>
15308
15309
15310	<!--
15311	// ISerialPort
15312	/////////////////////////////////////////////////////////////////////////
15313	-->
15314
15315	<enum
15316	name="PortMode"
15317	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
15318	>
15319	<desc>
15320	The PortMode enumeration represents possible communication modes for
15321	the virtual serial port device.
15322	</desc>
15323
15324	<const name="Disconnected" value="0">
15325	<desc>Virtual device is not attached to any real host device.</desc>
15326	</const>
15327	<const name="HostPipe" value="1">
15328	<desc>Virtual device is attached to a host pipe.</desc>
15329	</const>
15330	<const name="HostDevice" value="2">
15331	<desc>Virtual device is attached to a host device.</desc>
15332	</const>
15333	<const name="RawFile" value="3">
15334	<desc>Virtual device is attached to a raw file.</desc>
15335	</const>
15336	</enum>
15337
15338	<interface
15339	name="ISerialPort" extends="$unknown"
15340	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
15341	wsmap="managed"
15342	>
15343
15344	<desc>
15345	The ISerialPort interface represents the virtual serial port device.
15346
15347	The virtual serial port device acts like an ordinary serial port
15348	inside the virtual machine. This device communicates to the real
15349	serial port hardware in one of two modes: host pipe or host device.
15350
15351	In host pipe mode, the #path attribute specifies the path to the pipe on
15352	the host computer that represents a serial port. The #server attribute
15353	determines if this pipe is created by the virtual machine process at
15354	machine startup or it must already exist before starting machine
15355	execution.
15356
15357	In host device mode, the #path attribute specifies the name of the
15358	serial port device on the host computer.
15359
15360	There is also a third communication mode: the disconnected mode. In this
15361	mode, the guest OS running inside the virtual machine will be able to
15362	detect the serial port, but all port write operations will be discarded
15363	and all port read operations will return no data.
15364
15365	<see><link to="IMachine::getSerialPort"/></see>
15366	</desc>
15367
15368	<attribute name="slot" type="unsigned long" readonly="yes">
15369	<desc>
15370	Slot number this serial port is plugged into. Corresponds to
15371	the value you pass to <link to="IMachine::getSerialPort"/>
15372	to obtain this instance.
15373	</desc>
15374	</attribute>
15375
15376	<attribute name="enabled" type="boolean">
15377	<desc>
15378	Flag whether the serial port is enabled. If disabled,
15379	the serial port will not be reported to the guest OS.
15380	</desc>
15381	</attribute>
15382
15383	<attribute name="IOBase" type="unsigned long">
15384	<desc>Base I/O address of the serial port.</desc>
15385	</attribute>
15386
15387	<attribute name="IRQ" type="unsigned long">
15388	<desc>IRQ number of the serial port.</desc>
15389	</attribute>
15390
15391	<attribute name="hostMode" type="PortMode">
15392	<desc>
15393	How is this port connected to the host.
15394	<note>
15395	Changing this attribute may fail if the conditions for
15396	<link to="#path"/> are not met.
15397	</note>
15398	</desc>
15399	</attribute>
15400
15401	<attribute name="server" type="boolean">
15402	<desc>
15403	Flag whether this serial port acts as a server (creates a new pipe on
15404	the host) or as a client (uses the existing pipe). This attribute is
15405	used only when <link to="#hostMode"/> is PortMode_HostPipe.
15406	</desc>
15407	</attribute>
15408
15409	<attribute name="path" type="wstring">
15410	<desc>
15411	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
15412	PortMode_HostPipe, or the host serial device name when
15413	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
15414	cases, setting a @c null or empty string as the attribute's value
15415	is an error. Otherwise, the value of this property is ignored.
15416	</desc>
15417	</attribute>
15418
15419	</interface>
15420
15421	<!--
15422	// IParallelPort
15423	/////////////////////////////////////////////////////////////////////////
15424	-->
15425
15426	<interface
15427	name="IParallelPort" extends="$unknown"
15428	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
15429	wsmap="managed"
15430	>
15431
15432	<desc>
15433	The IParallelPort interface represents the virtual parallel port device.
15434
15435	The virtual parallel port device acts like an ordinary parallel port
15436	inside the virtual machine. This device communicates to the real
15437	parallel port hardware using the name of the parallel device on the host
15438	computer specified in the #path attribute.
15439
15440	Each virtual parallel port device is assigned a base I/O address and an
15441	IRQ number that will be reported to the guest operating system and used
15442	to operate the given parallel port from within the virtual machine.
15443
15444	<see><link to="IMachine::getParallelPort"/></see>
15445	</desc>
15446
15447	<attribute name="slot" type="unsigned long" readonly="yes">
15448	<desc>
15449	Slot number this parallel port is plugged into. Corresponds to
15450	the value you pass to <link to="IMachine::getParallelPort"/>
15451	to obtain this instance.
15452	</desc>
15453	</attribute>
15454
15455	<attribute name="enabled" type="boolean">
15456	<desc>
15457	Flag whether the parallel port is enabled. If disabled,
15458	the parallel port will not be reported to the guest OS.
15459	</desc>
15460	</attribute>
15461
15462	<attribute name="IOBase" type="unsigned long">
15463	<desc>Base I/O address of the parallel port.</desc>
15464	</attribute>
15465
15466	<attribute name="IRQ" type="unsigned long">
15467	<desc>IRQ number of the parallel port.</desc>
15468	</attribute>
15469
15470	<attribute name="path" type="wstring">
15471	<desc>
15472	Host parallel device name. If this parallel port is enabled, setting a
15473	@c null or an empty string as this attribute's value will result in
15474	an error.
15475	</desc>
15476	</attribute>
15477
15478	</interface>
15479
15480
15481	<!--
15482	// IMachineDebugger
15483	/////////////////////////////////////////////////////////////////////////
15484	-->
15485
15486	<interface
15487	name="IMachineDebugger" extends="$unknown"
15488	uuid="1eeeb3c2-0089-4448-878e-414aee00e03b"
15489	wsmap="managed"
15490	>
15491	<method name="dumpGuestCore">
15492	<desc>
15493	Takes a core dump of the guest.
15494
15495	See include/VBox/dbgfcorefmt.h for details on the file format.
15496	</desc>
15497	<param name="filename" type="wstring" dir="in">
15498	<desc>
15499	The name of the output file. The file must not exist.
15500	</desc>
15501	</param>
15502	<param name="compression" type="wstring" dir="in">
15503	<desc>
15504	Reserved for future compression method indicator.
15505	</desc>
15506	</param>
15507	</method>
15508
15509	<method name="dumpHostProcessCore">
15510	<desc>
15511	Takes a core dump of the VM process on the host.
15512
15513	This feature is not implemented in the 4.0.0 release but it may show up
15514	in a dot release.
15515	</desc>
15516	<param name="filename" type="wstring" dir="in">
15517	<desc>
15518	The name of the output file. The file must not exist.
15519	</desc>
15520	</param>
15521	<param name="compression" type="wstring" dir="in">
15522	<desc>
15523	Reserved for future compression method indicator.
15524	</desc>
15525	</param>
15526	</method>
15527
15528	<method name="info">
15529	<desc>
15530	Interfaces with the info dumpers (DBGFInfo).
15531
15532	This feature is not implemented in the 4.0.0 release but it may show up
15533	in a dot release.
15534	</desc>
15535	<param name="name" type="wstring" dir="in">
15536	<desc>
15537	The name of the info item.
15538	</desc>
15539	</param>
15540	<param name="args" type="wstring" dir="in">
15541	<desc>
15542	Arguments to the info dumper.
15543	</desc>
15544	</param>
15545	<param name="info" type="wstring" dir="return">
15546	<desc>
15547	The into string.
15548	</desc>
15549	</param>
15550	</method>
15551
15552	<method name="injectNMI">
15553	<desc>
15554	Inject an NMI into a running VT-x/AMD-V VM.
15555	</desc>
15556	</method>
15557
15558	<method name="modifyLogGroups">
15559	<desc>
15560	Modifies the group settings of the debug or release logger.
15561	</desc>
15562	<param name="settings" type="wstring" dir="in">
15563	<desc>
15564	The group settings string. See iprt/log.h for details. To target the
15565	release logger, prefix the string with "release:".
15566	</desc>
15567	</param>
15568	</method>
15569
15570	<method name="modifyLogFlags">
15571	<desc>
15572	Modifies the debug or release logger flags.
15573	</desc>
15574	<param name="settings" type="wstring" dir="in">
15575	<desc>
15576	The flags settings string. See iprt/log.h for details. To target the
15577	release logger, prefix the string with "release:".
15578	</desc>
15579	</param>
15580	</method>
15581
15582	<method name="modifyLogDestinations">
15583	<desc>
15584	Modifies the debug or release logger destinations.
15585	</desc>
15586	<param name="settings" type="wstring" dir="in">
15587	<desc>
15588	The destination settings string. See iprt/log.h for details. To target the
15589	release logger, prefix the string with "release:".
15590	</desc>
15591	</param>
15592	</method>
15593
15594	<method name="readPhysicalMemory">
15595	<desc>
15596	Reads guest physical memory, no side effects (MMIO++).
15597
15598	This feature is not implemented in the 4.0.0 release but may show up
15599	in a dot release.
15600	</desc>
15601	<param name="address" type="long long" dir="in">
15602	<desc>The guest physical address.</desc>
15603	</param>
15604	<param name="size" type="unsigned long" dir="in">
15605	<desc>The number of bytes to read.</desc>
15606	</param>
15607	<param name="bytes" type="octet" safearray="yes" dir="return">
15608	<desc>The bytes read.</desc>
15609	</param>
15610	</method>
15611
15612	<method name="writePhysicalMemory">
15613	<desc>
15614	Writes guest physical memory, access handles (MMIO++) are ignored.
15615
15616	This feature is not implemented in the 4.0.0 release but may show up
15617	in a dot release.
15618	</desc>
15619	<param name="address" type="long long" dir="in">
15620	<desc>The guest physical address.</desc>
15621	</param>
15622	<param name="size" type="unsigned long" dir="in">
15623	<desc>The number of bytes to read.</desc>
15624	</param>
15625	<param name="bytes" type="octet" safearray="yes" dir="in">
15626	<desc>The bytes to write.</desc>
15627	</param>
15628	</method>
15629
15630	<method name="readVirtualMemory">
15631	<desc>
15632	Reads guest virtual memory, no side effects (MMIO++).
15633
15634	This feature is not implemented in the 4.0.0 release but may show up
15635	in a dot release.
15636	</desc>
15637	<param name="cpuId" type="unsigned long" dir="in">
15638	<desc>The identifier of the Virtual CPU.</desc>
15639	</param>
15640	<param name="address" type="long long" dir="in">
15641	<desc>The guest virtual address.</desc>
15642	</param>
15643	<param name="size" type="unsigned long" dir="in">
15644	<desc>The number of bytes to read.</desc>
15645	</param>
15646	<param name="bytes" type="octet" safearray="yes" dir="return">
15647	<desc>The bytes read.</desc>
15648	</param>
15649	</method>
15650
15651	<method name="writeVirtualMemory">
15652	<desc>
15653	Writes guest virtual memory, access handles (MMIO++) are ignored.
15654
15655	This feature is not implemented in the 4.0.0 release but may show up
15656	in a dot release.
15657	</desc>
15658	<param name="cpuId" type="unsigned long" dir="in">
15659	<desc>The identifier of the Virtual CPU.</desc>
15660	</param>
15661	<param name="address" type="long long" dir="in">
15662	<desc>The guest virtual address.</desc>
15663	</param>
15664	<param name="size" type="unsigned long" dir="in">
15665	<desc>The number of bytes to read.</desc>
15666	</param>
15667	<param name="bytes" type="octet" safearray="yes" dir="in">
15668	<desc>The bytes to write.</desc>
15669	</param>
15670	</method>
15671
15672	<method name="detectOS">
15673	<desc>
15674	Tries to (re-)detect the guest OS kernel.
15675
15676	This feature is not implemented in the 4.0.0 release but may show up
15677	in a dot release.
15678	</desc>
15679	<param name="os" type="wstring" dir="return">
15680	<desc>
15681	The detected OS kernel on success.
15682	</desc>
15683	</param>
15684	</method>
15685
15686	<method name="getRegister">
15687	<desc>
15688	Gets one register.
15689
15690	This feature is not implemented in the 4.0.0 release but may show up
15691	in a dot release.
15692	</desc>
15693	<param name="cpuId" type="unsigned long" dir="in">
15694	<desc>The identifier of the Virtual CPU.</desc>
15695	</param>
15696	<param name="name" type="wstring" dir="in">
15697	<desc>The register name, case is ignored.</desc>
15698	</param>
15699	<param name="value" type="wstring" dir="return">
15700	<desc>
15701	The register value. This is usually a hex value (always 0x prefixed)
15702	but other format may be used for floating point registers (TBD).
15703	</desc>
15704	</param>
15705	</method>
15706
15707	<method name="getRegisters">
15708	<desc>
15709	Gets all the registers for the given CPU.
15710
15711	This feature is not implemented in the 4.0.0 release but may show up
15712	in a dot release.
15713	</desc>
15714	<param name="cpuId" type="unsigned long" dir="in">
15715	<desc>The identifier of the Virtual CPU.</desc>
15716	</param>
15717	<param name="names" type="wstring" dir="out" safearray="yes">
15718	<desc>Array containing the lowercase register names.</desc>
15719	</param>
15720	<param name="values" type="wstring" dir="out" safearray="yes">
15721	<desc>
15722	Array paralell to the names holding the register values as if the
15723	register was returned by <link to="IMachineDebugger::getRegister"/>.
15724	</desc>
15725	</param>
15726	</method>
15727
15728	<method name="setRegister">
15729	<desc>
15730	Gets one register.
15731
15732	This feature is not implemented in the 4.0.0 release but may show up
15733	in a dot release.
15734	</desc>
15735	<param name="cpuId" type="unsigned long" dir="in">
15736	<desc>The identifier of the Virtual CPU.</desc>
15737	</param>
15738	<param name="name" type="wstring" dir="in">
15739	<desc>The register name, case is ignored.</desc>
15740	</param>
15741	<param name="value" type="wstring" dir="in">
15742	<desc>
15743	The new register value. Hexadecimal, decimal and octal formattings
15744	are supported in addition to any special formattings returned by
15745	the getters.
15746	</desc>
15747	</param>
15748	</method>
15749
15750	<method name="setRegisters">
15751	<desc>
15752	Sets zero or more registers atomically.
15753
15754	This feature is not implemented in the 4.0.0 release but may show up
15755	in a dot release.
15756	</desc>
15757	<param name="cpuId" type="unsigned long" dir="in">
15758	<desc>The identifier of the Virtual CPU.</desc>
15759	</param>
15760	<param name="names" type="wstring" dir="in" safearray="yes">
15761	<desc>Array containing the register names, case ignored.</desc>
15762	</param>
15763	<param name="values" type="wstring" dir="in" safearray="yes">
15764	<desc>
15765	Array paralell to the names holding the register values. See
15766	<link to="IMachineDebugger::setRegister"/> for formatting
15767	guidelines.
15768	</desc>
15769	</param>
15770	</method>
15771
15772	<method name="dumpGuestStack">
15773	<desc>
15774	Produce a simple stack dump using the current guest state.
15775
15776	This feature is not implemented in the 4.0.0 release but may show up
15777	in a dot release.
15778	</desc>
15779	<param name="cpuId" type="unsigned long" dir="in">
15780	<desc>The identifier of the Virtual CPU.</desc>
15781	</param>
15782	<param name="stack" type="wstring" dir="return">
15783	<desc>String containing the formatted stack dump.</desc>
15784	</param>
15785	</method>
15786
15787	<method name="resetStats">
15788	<desc>
15789	Reset VM statistics.
15790	</desc>
15791	<param name="pattern" type="wstring" dir="in">
15792	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15793	</param>
15794	</method>
15795
15796	<method name="dumpStats">
15797	<desc>
15798	Dumps VM statistics.
15799	</desc>
15800	<param name="pattern" type="wstring" dir="in">
15801	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15802	</param>
15803	</method>
15804
15805	<method name="getStats">
15806	<desc>
15807	Get the VM statistics in a XMLish format.
15808	</desc>
15809	<param name="pattern" type="wstring" dir="in">
15810	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15811	</param>
15812	<param name="withDescriptions" type="boolean" dir="in">
15813	<desc>Whether to include the descriptions.</desc>
15814	</param>
15815	<param name="stats" type="wstring" dir="return">
15816	<desc>The XML document containing the statistics.</desc>
15817	</param>
15818	</method>
15819
15820	<attribute name="singleStep" type="boolean">
15821	<desc>Switch for enabling single-stepping.</desc>
15822	</attribute>
15823
15824	<attribute name="recompileUser" type="boolean">
15825	<desc>Switch for forcing code recompilation for user mode code.</desc>
15826	</attribute>
15827
15828	<attribute name="recompileSupervisor" type="boolean">
15829	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
15830	</attribute>
15831
15832	<attribute name="PATMEnabled" type="boolean">
15833	<desc>Switch for enabling and disabling the PATM component.</desc>
15834	</attribute>
15835
15836	<attribute name="CSAMEnabled" type="boolean">
15837	<desc>Switch for enabling and disabling the CSAM component.</desc>
15838	</attribute>
15839
15840	<attribute name="logEnabled" type="boolean">
15841	<desc>Switch for enabling and disabling the debug logger.</desc>
15842	</attribute>
15843
15844	<attribute name="logDbgFlags" type="wstring" readonly="yes">
15845	<desc>The debug logger flags.</desc>
15846	</attribute>
15847
15848	<attribute name="logDbgGroups" type="wstring" readonly="yes">
15849	<desc>The debug logger's group settings.</desc>
15850	</attribute>
15851
15852	<attribute name="logDbgDestinations" type="wstring" readonly="yes">
15853	<desc>The debug logger's destination settings.</desc>
15854	</attribute>
15855
15856	<attribute name="logRelFlags" type="wstring" readonly="yes">
15857	<desc>The release logger flags.</desc>
15858	</attribute>
15859
15860	<attribute name="logRelGroups" type="wstring" readonly="yes">
15861	<desc>The release logger's group settings.</desc>
15862	</attribute>
15863
15864	<attribute name="logRelDestinations" type="wstring" readonly="yes">
15865	<desc>The relase logger's destination settings.</desc>
15866	</attribute>
15867
15868	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
15869	<desc>
15870	Flag indicating whether the VM is currently making use of CPU hardware
15871	virtualization extensions.
15872	</desc>
15873	</attribute>
15874
15875	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
15876	<desc>
15877	Flag indicating whether the VM is currently making use of the nested paging
15878	CPU hardware virtualization extension.
15879	</desc>
15880	</attribute>
15881
15882	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
15883	<desc>
15884	Flag indicating whether the VM is currently making use of the VPID
15885	VT-x extension.
15886	</desc>
15887	</attribute>
15888
15889	<attribute name="HWVirtExUXEnabled" type="boolean" readonly="yes">
15890	<desc>
15891	Flag indicating whether the VM is currently making use of the
15892	unrestricted execution feature of VT-x.
15893	</desc>
15894	</attribute>
15895
15896	<attribute name="OSName" type="wstring" readonly="yes">
15897	<desc>
15898	Query the guest OS kernel name as detected by the DBGF.
15899
15900	This feature is not implemented in the 4.0.0 release but may show up
15901	in a dot release.
15902	</desc>
15903	</attribute>
15904
15905	<attribute name="OSVersion" type="wstring" readonly="yes">
15906	<desc>
15907	Query the guest OS kernel version string as detected by the DBGF.
15908
15909	This feature is not implemented in the 4.0.0 release but may show up
15910	in a dot release.
15911	</desc>
15912	</attribute>
15913
15914	<attribute name="PAEEnabled" type="boolean" readonly="yes">
15915	<desc>
15916	Flag indicating whether the VM is currently making use of the Physical
15917	Address Extension CPU feature.
15918	</desc>
15919	</attribute>
15920
15921	<attribute name="virtualTimeRate" type="unsigned long">
15922	<desc>
15923	The rate at which the virtual time runs expressed as a percentage.
15924	The accepted range is 2% to 20000%.
15925	</desc>
15926	</attribute>
15927
15928	<attribute name="VM" type="long long" readonly="yes" wsmap="suppress">
15929	<desc>
15930	Gets the user-mode VM handle, with a reference. Must be passed to
15931	VMR3ReleaseUVM when done. This is only for internal use while we carve
15932	the details of this interface.
15933	</desc>
15934	</attribute>
15935
15936	</interface>
15937
15938	<!--
15939	// IUSBController
15940	/////////////////////////////////////////////////////////////////////////
15941	-->
15942
15943	<interface
15944	name="IUSBController" extends="$unknown"
15945	uuid="01e6f13a-0580-452f-a40f-74e32a5e4921"
15946	wsmap="managed"
15947	>
15948	<attribute name="enabled" type="boolean">
15949	<desc>
15950	Flag whether the USB controller is present in the
15951	guest system. If disabled, the virtual guest hardware will
15952	not contain any USB controller. Can only be changed when
15953	the VM is powered off.
15954	</desc>
15955	</attribute>
15956
15957	<attribute name="enabledEHCI" type="boolean">
15958	<desc>
15959	Flag whether the USB EHCI controller is present in the
15960	guest system. If disabled, the virtual guest hardware will
15961	not contain a USB EHCI controller. Can only be changed when
15962	the VM is powered off.
15963	</desc>
15964	</attribute>
15965
15966	<attribute name="proxyAvailable" type="boolean" readonly="yes">
15967	<desc>
15968	Flag whether there is an USB proxy available.
15969	</desc>
15970	</attribute>
15971
15972	<attribute name="USBStandard" type="unsigned short" readonly="yes">
15973	<desc>
15974	USB standard version which the controller implements.
15975	This is a BCD which means that the major version is in the
15976	high byte and minor version is in the low byte.
15977	</desc>
15978	</attribute>
15979
15980	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
15981	<desc>
15982	List of USB device filters associated with the machine.
15983
15984	If the machine is currently running, these filters are activated
15985	every time a new (supported) USB device is attached to the host
15986	computer that was not ignored by global filters
15987	(<link to="IHost::USBDeviceFilters"/>).
15988
15989	These filters are also activated when the machine is powered up.
15990	They are run against a list of all currently available USB
15991	devices (in states
15992	<link to="USBDeviceState_Available"/>,
15993	<link to="USBDeviceState_Busy"/>,
15994	<link to="USBDeviceState_Held"/>) that were not previously
15995	ignored by global filters.
15996
15997	If at least one filter matches the USB device in question, this
15998	device is automatically captured (attached to) the virtual USB
15999	controller of this machine.
16000
16001	<see><link to="IUSBDeviceFilter"/>, <link to="IUSBController"/></see>
16002	</desc>
16003	</attribute>
16004
16005	<method name="createDeviceFilter">
16006	<desc>
16007	Creates a new USB device filter. All attributes except
16008	the filter name are set to empty (any match),
16009	<i>active</i> is @c false (the filter is not active).
16010
16011	The created filter can then be added to the list of filters using
16012	<link to="#insertDeviceFilter"/>.
16013
16014	<result name="VBOX_E_INVALID_VM_STATE">
16015	The virtual machine is not mutable.
16016	</result>
16017
16018	<see><link to="#deviceFilters"/></see>
16019	</desc>
16020	<param name="name" type="wstring" dir="in">
16021	<desc>
16022	Filter name. See <link to="IUSBDeviceFilter::name"/>
16023	for more info.
16024	</desc>
16025	</param>
16026	<param name="filter" type="IUSBDeviceFilter" dir="return">
16027	<desc>Created filter object.</desc>
16028	</param>
16029	</method>
16030
16031	<method name="insertDeviceFilter">
16032	<desc>
16033	Inserts the given USB device to the specified position
16034	in the list of filters.
16035
16036	Positions are numbered starting from <tt>0</tt>. If the specified
16037	position is equal to or greater than the number of elements in
16038	the list, the filter is added to the end of the collection.
16039
16040	<note>
16041	Duplicates are not allowed, so an attempt to insert a
16042	filter that is already in the collection, will return an
16043	error.
16044	</note>
16045
16046	<result name="VBOX_E_INVALID_VM_STATE">
16047	Virtual machine is not mutable.
16048	</result>
16049	<result name="E_INVALIDARG">
16050	USB device filter not created within this VirtualBox instance.
16051	</result>
16052	<result name="VBOX_E_INVALID_OBJECT_STATE">
16053	USB device filter already in list.
16054	</result>
16055
16056	<see><link to="#deviceFilters"/></see>
16057	</desc>
16058	<param name="position" type="unsigned long" dir="in">
16059	<desc>Position to insert the filter to.</desc>
16060	</param>
16061	<param name="filter" type="IUSBDeviceFilter" dir="in">
16062	<desc>USB device filter to insert.</desc>
16063	</param>
16064	</method>
16065
16066	<method name="removeDeviceFilter">
16067	<desc>
16068	Removes a USB device filter from the specified position in the
16069	list of filters.
16070
16071	Positions are numbered starting from <tt>0</tt>. Specifying a
16072	position equal to or greater than the number of elements in
16073	the list will produce an error.
16074
16075	<see><link to="#deviceFilters"/></see>
16076
16077	<result name="VBOX_E_INVALID_VM_STATE">
16078	Virtual machine is not mutable.
16079	</result>
16080	<result name="E_INVALIDARG">
16081	USB device filter list empty or invalid @a position.
16082	</result>
16083
16084	</desc>
16085	<param name="position" type="unsigned long" dir="in">
16086	<desc>Position to remove the filter from.</desc>
16087	</param>
16088	<param name="filter" type="IUSBDeviceFilter" dir="return">
16089	<desc>Removed USB device filter.</desc>
16090	</param>
16091	</method>
16092
16093	</interface>
16094
16095
16096	<!--
16097	// IUSBDevice
16098	/////////////////////////////////////////////////////////////////////////
16099	-->
16100
16101	<interface
16102	name="IUSBDevice" extends="$unknown"
16103	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
16104	wsmap="managed"
16105	>
16106	<desc>
16107	The IUSBDevice interface represents a virtual USB device attached to the
16108	virtual machine.
16109
16110	A collection of objects implementing this interface is stored in the
16111	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
16112	attached to a running virtual machine's USB controller.
16113	</desc>
16114
16115	<attribute name="id" type="uuid" mod="string" readonly="yes">
16116	<desc>
16117	Unique USB device ID. This ID is built from #vendorId,
16118	#productId, #revision and #serialNumber.
16119	</desc>
16120	</attribute>
16121
16122	<attribute name="vendorId" type="unsigned short" readonly="yes">
16123	<desc>Vendor ID.</desc>
16124	</attribute>
16125
16126	<attribute name="productId" type="unsigned short" readonly="yes">
16127	<desc>Product ID.</desc>
16128	</attribute>
16129
16130	<attribute name="revision" type="unsigned short" readonly="yes">
16131	<desc>
16132	Product revision number. This is a packed BCD represented as
16133	unsigned short. The high byte is the integer part and the low
16134	byte is the decimal.
16135	</desc>
16136	</attribute>
16137
16138	<attribute name="manufacturer" type="wstring" readonly="yes">
16139	<desc>Manufacturer string.</desc>
16140	</attribute>
16141
16142	<attribute name="product" type="wstring" readonly="yes">
16143	<desc>Product string.</desc>
16144	</attribute>
16145
16146	<attribute name="serialNumber" type="wstring" readonly="yes">
16147	<desc>Serial number string.</desc>
16148	</attribute>
16149
16150	<attribute name="address" type="wstring" readonly="yes">
16151	<desc>Host specific address of the device.</desc>
16152	</attribute>
16153
16154	<attribute name="port" type="unsigned short" readonly="yes">
16155	<desc>
16156	Host USB port number the device is physically
16157	connected to.
16158	</desc>
16159	</attribute>
16160
16161	<attribute name="version" type="unsigned short" readonly="yes">
16162	<desc>
16163	The major USB version of the device - 1 or 2.
16164	</desc>
16165	</attribute>
16166
16167	<attribute name="portVersion" type="unsigned short" readonly="yes">
16168	<desc>
16169	The major USB version of the host USB port the device is
16170	physically connected to - 1 or 2. For devices not connected to
16171	anything this will have the same value as the version attribute.
16172	</desc>
16173	</attribute>
16174
16175	<attribute name="remote" type="boolean" readonly="yes">
16176	<desc>
16177	Whether the device is physically connected to a remote VRDE
16178	client or to a local host machine.
16179	</desc>
16180	</attribute>
16181
16182	</interface>
16183
16184
16185	<!--
16186	// IUSBDeviceFilter
16187	/////////////////////////////////////////////////////////////////////////
16188	-->
16189
16190	<interface
16191	name="IUSBDeviceFilter" extends="$unknown"
16192	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
16193	wsmap="managed"
16194	>
16195	<desc>
16196	The IUSBDeviceFilter interface represents an USB device filter used
16197	to perform actions on a group of USB devices.
16198
16199	This type of filters is used by running virtual machines to
16200	automatically capture selected USB devices once they are physically
16201	attached to the host computer.
16202
16203	A USB device is matched to the given device filter if and only if all
16204	attributes of the device match the corresponding attributes of the
16205	filter (that is, attributes are joined together using the logical AND
16206	operation). On the other hand, all together, filters in the list of
16207	filters carry the semantics of the logical OR operation. So if it is
16208	desirable to create a match like "this vendor id OR this product id",
16209	one needs to create two filters and specify "any match" (see below)
16210	for unused attributes.
16211
16212	All filter attributes used for matching are strings. Each string
16213	is an expression representing a set of values of the corresponding
16214	device attribute, that will match the given filter. Currently, the
16215	following filtering expressions are supported:
16216
16217	<ul>
16218	<li><i>Interval filters</i>. Used to specify valid intervals for
16219	integer device attributes (Vendor ID, Product ID and Revision).
16220	The format of the string is:
16221
16222	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
16223
16224	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
16225	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
16226	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
16227	is omitted before a dash (<tt>-</tt>), the minimum possible integer
16228	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
16229	possible integer is assumed.
16230	</li>
16231	<li><i>Boolean filters</i>. Used to specify acceptable values for
16232	boolean device attributes. The format of the string is:
16233
16234	<tt>true\|false\|yes\|no\|0\|1</tt>
16235
16236	</li>
16237	<li><i>Exact match</i>. Used to specify a single value for the given
16238	device attribute. Any string that doesn't start with <tt>int:</tt>
16239	represents the exact match. String device attributes are compared to
16240	this string including case of symbols. Integer attributes are first
16241	converted to a string (see individual filter attributes) and then
16242	compared ignoring case.
16243
16244	</li>
16245	<li><i>Any match</i>. Any value of the corresponding device attribute
16246	will match the given filter. An empty or @c null string is
16247	used to construct this type of filtering expressions.
16248
16249	</li>
16250	</ul>
16251
16252	<note>
16253	On the Windows host platform, interval filters are not currently
16254	available. Also all string filter attributes
16255	(<link to="#manufacturer"/>, <link to="#product"/>,
16256	<link to="#serialNumber"/>) are ignored, so they behave as
16257	<i>any match</i> no matter what string expression is specified.
16258	</note>
16259
16260	<see><link to="IUSBController::deviceFilters"/>,
16261	<link to="IHostUSBDeviceFilter"/></see>
16262	</desc>
16263
16264	<attribute name="name" type="wstring">
16265	<desc>
16266	Visible name for this filter.
16267	This name is used to visually distinguish one filter from another,
16268	so it can neither be @c null nor an empty string.
16269	</desc>
16270	</attribute>
16271
16272	<attribute name="active" type="boolean">
16273	<desc>Whether this filter active or has been temporarily disabled.</desc>
16274	</attribute>
16275
16276	<attribute name="vendorId" type="wstring">
16277	<desc>
16278	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
16279	The string representation for the <i>exact matching</i>
16280	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16281	(including leading zeroes).
16282	</desc>
16283	</attribute>
16284
16285	<attribute name="productId" type="wstring">
16286	<desc>
16287	<link to="IUSBDevice::productId">Product ID</link> filter.
16288	The string representation for the <i>exact matching</i>
16289	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16290	(including leading zeroes).
16291	</desc>
16292	</attribute>
16293
16294	<attribute name="revision" type="wstring">
16295	<desc>
16296	<link to="IUSBDevice::productId">Product revision number</link>
16297	filter. The string representation for the <i>exact matching</i>
16298	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
16299	of the integer part of the revision, and <tt>F</tt> is the
16300	decimal digit of its fractional part (including leading and
16301	trailing zeros).
16302	Note that for interval filters, it's best to use the hexadecimal
16303	form, because the revision is stored as a 16 bit packed BCD value;
16304	so the expression <tt>int:0x0100-0x0199</tt> will match any
16305	revision from <tt>1.0</tt> to <tt>1.99</tt>.
16306	</desc>
16307	</attribute>
16308
16309	<attribute name="manufacturer" type="wstring">
16310	<desc>
16311	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
16312	</desc>
16313	</attribute>
16314
16315	<attribute name="product" type="wstring">
16316	<desc>
16317	<link to="IUSBDevice::product">Product</link> filter.
16318	</desc>
16319	</attribute>
16320
16321	<attribute name="serialNumber" type="wstring">
16322	<desc>
16323	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
16324	</desc>
16325	</attribute>
16326
16327	<attribute name="port" type="wstring">
16328	<desc>
16329	<link to="IUSBDevice::port">Host USB port</link> filter.
16330	</desc>
16331	</attribute>
16332
16333	<attribute name="remote" type="wstring">
16334	<desc>
16335	<link to="IUSBDevice::remote">Remote state</link> filter.
16336	<note>
16337	This filter makes sense only for machine USB filters,
16338	i.e. it is ignored by IHostUSBDeviceFilter objects.
16339	</note>
16340	</desc>
16341	</attribute>
16342
16343	<attribute name="maskedInterfaces" type="unsigned long">
16344	<desc>
16345	This is an advanced option for hiding one or more USB interfaces
16346	from the guest. The value is a bit mask where the bits that are set
16347	means the corresponding USB interface should be hidden, masked off
16348	if you like.
16349	This feature only works on Linux hosts.
16350	</desc>
16351	</attribute>
16352
16353	</interface>
16354
16355
16356	<!--
16357	// IHostUSBDevice
16358	/////////////////////////////////////////////////////////////////////////
16359	-->
16360
16361	<enum
16362	name="USBDeviceState"
16363	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
16364	>
16365	<desc>
16366	USB device state. This enumeration represents all possible states
16367	of the USB device physically attached to the host computer regarding
16368	its state on the host computer and availability to guest computers
16369	(all currently running virtual machines).
16370
16371	Once a supported USB device is attached to the host, global USB
16372	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
16373	either ignore the device, or put it to USBDeviceState_Held state, or do
16374	nothing. Unless the device is ignored by global filters, filters of all
16375	currently running guests (<link to="IUSBController::deviceFilters"/>) are
16376	activated that can put it to USBDeviceState_Captured state.
16377
16378	If the device was ignored by global filters, or didn't match
16379	any filters at all (including guest ones), it is handled by the host
16380	in a normal way. In this case, the device state is determined by
16381	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
16382	or USBDeviceState_Available, depending on the current device usage.
16383
16384	Besides auto-capturing based on filters, the device can be manually
16385	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
16386	state is USBDeviceState_Busy, USBDeviceState_Available or
16387	USBDeviceState_Held.
16388
16389	<note>
16390	Due to differences in USB stack implementations in Linux and Win32,
16391	states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
16392	only to the Linux version of the product. This also means that (<link
16393	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
16394	device state is USBDeviceState_Held.
16395	</note>
16396
16397	<see><link to="IHostUSBDevice"/>, <link to="IHostUSBDeviceFilter"/></see>
16398	</desc>
16399
16400	<const name="NotSupported" value="0">
16401	<desc>
16402	Not supported by the VirtualBox server, not available to guests.
16403	</desc>
16404	</const>
16405	<const name="Unavailable" value="1">
16406	<desc>
16407	Being used by the host computer exclusively,
16408	not available to guests.
16409	</desc>
16410	</const>
16411	<const name="Busy" value="2">
16412	<desc>
16413	Being used by the host computer, potentially available to guests.
16414	</desc>
16415	</const>
16416	<const name="Available" value="3">
16417	<desc>
16418	Not used by the host computer, available to guests (the host computer
16419	can also start using the device at any time).
16420	</desc>
16421	</const>
16422	<const name="Held" value="4">
16423	<desc>
16424	Held by the VirtualBox server (ignored by the host computer),
16425	available to guests.
16426	</desc>
16427	</const>
16428	<const name="Captured" value="5">
16429	<desc>
16430	Captured by one of the guest computers, not available
16431	to anybody else.
16432	</desc>
16433	</const>
16434	</enum>
16435
16436	<interface
16437	name="IHostUSBDevice" extends="IUSBDevice"
16438	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
16439	wsmap="managed"
16440	>
16441	<desc>
16442	The IHostUSBDevice interface represents a physical USB device attached
16443	to the host computer.
16444
16445	Besides properties inherited from IUSBDevice, this interface adds the
16446	<link to="#state"/> property that holds the current state of the USB
16447	device.
16448
16449	<see><link to="IHost::USBDevices"/>,
16450	<link to="IHost::USBDeviceFilters"/></see>
16451	</desc>
16452
16453	<attribute name="state" type="USBDeviceState" readonly="yes">
16454	<desc>
16455	Current state of the device.
16456	</desc>
16457	</attribute>
16458
16459	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
16460
16461	</interface>
16462
16463
16464	<!--
16465	// IHostUSBDeviceFilter
16466	/////////////////////////////////////////////////////////////////////////
16467	-->
16468
16469	<enum
16470	name="USBDeviceFilterAction"
16471	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
16472	>
16473	<desc>
16474	Actions for host USB device filters.
16475	<see><link to="IHostUSBDeviceFilter"/>, <link to="USBDeviceState"/></see>
16476	</desc>
16477
16478	<const name="Null" value="0">
16479	<desc>Null value (never used by the API).</desc>
16480	</const>
16481	<const name="Ignore" value="1">
16482	<desc>Ignore the matched USB device.</desc>
16483	</const>
16484	<const name="Hold" value="2">
16485	<desc>Hold the matched USB device.</desc>
16486	</const>
16487	</enum>
16488
16489	<interface
16490	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
16491	uuid="4cc70246-d74a-400f-8222-3900489c0374"
16492	wsmap="managed"
16493	>
16494	<desc>
16495	The IHostUSBDeviceFilter interface represents a global filter for a
16496	physical USB device used by the host computer. Used indirectly in
16497	<link to="IHost::USBDeviceFilters"/>.
16498
16499	Using filters of this type, the host computer determines the initial
16500	state of the USB device after it is physically attached to the
16501	host's USB controller.
16502
16503	<note>
16504	The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
16505	filters, because it makes sense only for
16506	<link to="IUSBController::deviceFilters">machine USB filters</link>.
16507	</note>
16508
16509	<see><link to="IHost::USBDeviceFilters"/></see>
16510	</desc>
16511
16512	<attribute name="action" type="USBDeviceFilterAction">
16513	<desc>
16514	Action performed by the host when an attached USB device
16515	matches this filter.
16516	</desc>
16517	</attribute>
16518
16519	</interface>
16520
16521	<!--
16522	// IAudioAdapter
16523	/////////////////////////////////////////////////////////////////////////
16524	-->
16525
16526	<enum
16527	name="AudioDriverType"
16528	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
16529	>
16530	<desc>
16531	Host audio driver type.
16532	</desc>
16533
16534	<const name="Null" value="0">
16535	<desc>Null value, also means "dummy audio driver".</desc>
16536	</const>
16537	<const name="WinMM" value="1">
16538	<desc>Windows multimedia (Windows hosts only).</desc>
16539	</const>
16540	<const name="OSS" value="2">
16541	<desc>Open Sound System (Linux hosts only).</desc>
16542	</const>
16543	<const name="ALSA" value="3">
16544	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
16545	</const>
16546	<const name="DirectSound" value="4">
16547	<desc>DirectSound (Windows hosts only).</desc>
16548	</const>
16549	<const name="CoreAudio" value="5">
16550	<desc>CoreAudio (Mac hosts only).</desc>
16551	</const>
16552	<const name="MMPM" value="6">
16553	<desc>Reserved for historical reasons.</desc>
16554	</const>
16555	<const name="Pulse" value="7">
16556	<desc>PulseAudio (Linux hosts only).</desc>
16557	</const>
16558	<const name="SolAudio" value="8">
16559	<desc>Solaris audio (Solaris hosts only).</desc>
16560	</const>
16561	</enum>
16562
16563	<enum
16564	name="AudioControllerType"
16565	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
16566	>
16567	<desc>
16568	Virtual audio controller type.
16569	</desc>
16570
16571	<const name="AC97" value="0"/>
16572	<const name="SB16" value="1"/>
16573	<const name="HDA" value="2"/>
16574	</enum>
16575
16576	<interface
16577	name="IAudioAdapter" extends="$unknown"
16578	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
16579	wsmap="managed"
16580	>
16581	<desc>
16582	The IAudioAdapter interface represents the virtual audio adapter of
16583	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
16584	</desc>
16585	<attribute name="enabled" type="boolean">
16586	<desc>
16587	Flag whether the audio adapter is present in the
16588	guest system. If disabled, the virtual guest hardware will
16589	not contain any audio adapter. Can only be changed when
16590	the VM is not running.
16591	</desc>
16592	</attribute>
16593	<attribute name="audioController" type="AudioControllerType">
16594	<desc>
16595	The audio hardware we emulate.
16596	</desc>
16597	</attribute>
16598	<attribute name="audioDriver" type="AudioDriverType">
16599	<desc>
16600	Audio driver the adapter is connected to. This setting
16601	can only be changed when the VM is not running.
16602	</desc>
16603	</attribute>
16604	</interface>
16605
16606	<enum
16607	name="AuthType"
16608	uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
16609	>
16610	<desc>
16611	VirtualBox authentication type.
16612	</desc>
16613
16614	<const name="Null" value="0">
16615	<desc>Null value, also means "no authentication".</desc>
16616	</const>
16617	<const name="External" value="1"/>
16618	<const name="Guest" value="2"/>
16619	</enum>
16620
16621	<!--
16622	// IVRDEServer
16623	/////////////////////////////////////////////////////////////////////////
16624	-->
16625
16626	<interface
16627	name="IVRDEServer" extends="$unknown"
16628	uuid="d38de40a-c2c1-4e95-b5a4-167b05f5694c"
16629	wsmap="managed"
16630	>
16631
16632	<attribute name="enabled" type="boolean">
16633	<desc>Flag if VRDE server is enabled.</desc>
16634	</attribute>
16635
16636	<attribute name="authType" type="AuthType">
16637	<desc>VRDE authentication method.</desc>
16638	</attribute>
16639
16640	<attribute name="authTimeout" type="unsigned long">
16641	<desc>Timeout for guest authentication. Milliseconds.</desc>
16642	</attribute>
16643
16644	<attribute name="allowMultiConnection" type="boolean">
16645	<desc>
16646	Flag whether multiple simultaneous connections to the VM are permitted.
16647	Note that this will be replaced by a more powerful mechanism in the future.
16648	</desc>
16649	</attribute>
16650
16651	<attribute name="reuseSingleConnection" type="boolean">
16652	<desc>
16653	Flag whether the existing connection must be dropped and a new connection
16654	must be established by the VRDE server, when a new client connects in single
16655	connection mode.
16656	</desc>
16657	</attribute>
16658
16659	<attribute name="VRDEExtPack" type="wstring">
16660	<desc>
16661	The name of Extension Pack providing VRDE for this VM. Overrides
16662	<link to="ISystemProperties::defaultVRDEExtPack"/>.
16663	</desc>
16664	</attribute>
16665
16666	<attribute name="authLibrary" type="wstring">
16667	<desc>
16668	Library used for authentication of RDP clients by this VM. Overrides
16669	<link to="ISystemProperties::VRDEAuthLibrary"/>.
16670	</desc>
16671	</attribute>
16672
16673	<attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes">
16674	<desc>
16675	Array of names of properties, which are supported by this VRDE server.
16676	</desc>
16677	</attribute>
16678
16679	<method name="setVRDEProperty">
16680	<desc>
16681	Sets a VRDE specific property string.
16682
16683	If you pass @c null or empty string as a key @a value, the given @a key
16684	will be deleted.
16685
16686	</desc>
16687	<param name="key" type="wstring" dir="in">
16688	<desc>Name of the key to set.</desc>
16689	</param>
16690	<param name="value" type="wstring" dir="in">
16691	<desc>Value to assign to the key.</desc>
16692	</param>
16693	</method>
16694
16695	<method name="getVRDEProperty" const="yes">
16696	<desc>
16697	Returns a VRDE specific property string.
16698
16699	If the requested data @a key does not exist, this function will
16700	succeed and return an empty string in the @a value argument.
16701
16702	</desc>
16703	<param name="key" type="wstring" dir="in">
16704	<desc>Name of the key to get.</desc>
16705	</param>
16706	<param name="value" type="wstring" dir="return">
16707	<desc>Value of the requested key.</desc>
16708	</param>
16709	</method>
16710
16711	</interface>
16712
16713
16714	<!--
16715	// ISharedFolder
16716	/////////////////////////////////////////////////////////////////////////
16717	-->
16718
16719	<interface
16720	name="ISharedFolder" extends="$unknown"
16721	uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
16722	wsmap="struct"
16723	>
16724	<desc>
16725	The ISharedFolder interface represents a folder in the host computer's
16726	file system accessible from the guest OS running inside a virtual
16727	machine using an associated logical name.
16728
16729	There are three types of shared folders:
16730	<ul>
16731	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
16732	folders available to all virtual machines.</li>
16733	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
16734	VM-specific shared folders available to the given virtual machine at
16735	startup.</li>
16736	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
16737	VM-specific shared folders created in the session context (for
16738	example, when the virtual machine is running) and automatically
16739	discarded when the session is closed (the VM is powered off).</li>
16740	</ul>
16741
16742	Logical names of shared folders must be unique within the given scope
16743	(global, permanent or transient). However, they do not need to be unique
16744	across scopes. In this case, the definition of the shared folder in a
16745	more specific scope takes precedence over definitions in all other
16746	scopes. The order of precedence is (more specific to more general):
16747	<ol>
16748	<li>Transient definitions</li>
16749	<li>Permanent definitions</li>
16750	<li>Global definitions</li>
16751	</ol>
16752
16753	For example, if MyMachine has a shared folder named
16754	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
16755	transient shared folder named <tt>C_DRIVE</tt> (that points
16756	to <tt>C:\\\\WINDOWS</tt>) will change the definition
16757	of <tt>C_DRIVE</tt> in the guest OS so
16758	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
16759	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
16760	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
16761	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
16762	to <tt>C:\\</tt> if it still exists.
16763
16764	Note that permanent and transient shared folders of different machines
16765	are in different name spaces, so they don't overlap and don't need to
16766	have unique logical names.
16767
16768	<note>
16769	Global shared folders are not implemented in the current version of the
16770	product.
16771	</note>
16772	</desc>
16773
16774	<attribute name="name" type="wstring" readonly="yes">
16775	<desc>Logical name of the shared folder.</desc>
16776	</attribute>
16777
16778	<attribute name="hostPath" type="wstring" readonly="yes">
16779	<desc>Full path to the shared folder in the host file system.</desc>
16780	</attribute>
16781
16782	<attribute name="accessible" type="boolean" readonly="yes">
16783	<desc>
16784	Whether the folder defined by the host path is currently
16785	accessible or not.
16786	For example, the folder can be inaccessible if it is placed
16787	on the network share that is not available by the time
16788	this property is read.
16789	</desc>
16790	</attribute>
16791
16792	<attribute name="writable" type="boolean" readonly="yes">
16793	<desc>
16794	Whether the folder defined by the host path is writable or
16795	not.
16796	</desc>
16797	</attribute>
16798
16799	<attribute name="autoMount" type="boolean" readonly="yes">
16800	<desc>
16801	Whether the folder gets automatically mounted by the guest or not.
16802	</desc>
16803	</attribute>
16804
16805	<attribute name="lastAccessError" type="wstring" readonly="yes">
16806	<desc>
16807	Text message that represents the result of the last accessibility
16808	check.
16809
16810	Accessibility checks are performed each time the <link to="#accessible"/>
16811	attribute is read. An empty string is returned if the last
16812	accessibility check was successful. A non-empty string indicates a
16813	failure and should normally describe a reason of the failure (for
16814	example, a file read error).
16815	</desc>
16816	</attribute>
16817
16818	</interface>
16819
16820	<!--
16821	// ISession
16822	/////////////////////////////////////////////////////////////////////////
16823	-->
16824
16825	<interface
16826	name="IInternalSessionControl" extends="$unknown"
16827	uuid="0ba8d8b3-204b-448e-99c2-242eaa666ea8"
16828	internal="yes"
16829	wsmap="suppress"
16830	>
16831	<method name="getPID">
16832	<desc>PID of the process that has created this Session object.
16833	</desc>
16834	<param name="pid" type="unsigned long" dir="return"/>
16835	</method>
16836
16837	<method name="getRemoteConsole">
16838	<desc>
16839	Returns the console object suitable for remote control.
16840
16841	<result name="VBOX_E_INVALID_VM_STATE">
16842	Session state prevents operation.
16843	</result>
16844	<result name="VBOX_E_INVALID_OBJECT_STATE">
16845	Session type prevents operation.
16846	</result>
16847
16848	</desc>
16849	<param name="console" type="IConsole" dir="return"/>
16850	</method>
16851
16852	<method name="assignMachine">
16853	<desc>
16854	Assigns the machine object associated with this direct-type
16855	session or informs the session that it will be a remote one
16856	(if @a machine == @c null).
16857
16858	<result name="VBOX_E_INVALID_VM_STATE">
16859	Session state prevents operation.
16860	</result>
16861	<result name="VBOX_E_INVALID_OBJECT_STATE">
16862	Session type prevents operation.
16863	</result>
16864
16865	</desc>
16866	<param name="machine" type="IMachine" dir="in"/>
16867	<param name="lockType" type="LockType" dir="in"/>
16868	</method>
16869
16870	<method name="assignRemoteMachine">
16871	<desc>
16872	Assigns the machine and the (remote) console object associated with
16873	this remote-type session.
16874
16875	<result name="VBOX_E_INVALID_VM_STATE">
16876	Session state prevents operation.
16877	</result>
16878
16879	</desc>
16880	<param name="machine" type="IMachine" dir="in"/>
16881	<param name="console" type="IConsole" dir="in"/>
16882	</method>
16883
16884	<method name="updateMachineState">
16885	<desc>
16886	Updates the machine state in the VM process.
16887	Must be called only in certain cases
16888	(see the method implementation).
16889
16890	<result name="VBOX_E_INVALID_VM_STATE">
16891	Session state prevents operation.
16892	</result>
16893	<result name="VBOX_E_INVALID_OBJECT_STATE">
16894	Session type prevents operation.
16895	</result>
16896
16897	</desc>
16898	<param name="machineState" type="MachineState" dir="in"/>
16899	</method>
16900
16901	<method name="uninitialize">
16902	<desc>
16903	Uninitializes (closes) this session. Used by VirtualBox to close
16904	the corresponding remote session when the direct session dies
16905	or gets closed.
16906
16907	<result name="VBOX_E_INVALID_VM_STATE">
16908	Session state prevents operation.
16909	</result>
16910
16911	</desc>
16912	</method>
16913
16914	<method name="onNetworkAdapterChange">
16915	<desc>
16916	Triggered when settings of a network adapter of the
16917	associated virtual machine have changed.
16918
16919	<result name="VBOX_E_INVALID_VM_STATE">
16920	Session state prevents operation.
16921	</result>
16922	<result name="VBOX_E_INVALID_OBJECT_STATE">
16923	Session type prevents operation.
16924	</result>
16925
16926	</desc>
16927	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
16928	<param name="changeAdapter" type="boolean" dir="in"/>
16929	</method>
16930
16931	<method name="onSerialPortChange">
16932	<desc>
16933	Triggered when settings of a serial port of the
16934	associated virtual machine have changed.
16935
16936	<result name="VBOX_E_INVALID_VM_STATE">
16937	Session state prevents operation.
16938	</result>
16939	<result name="VBOX_E_INVALID_OBJECT_STATE">
16940	Session type prevents operation.
16941	</result>
16942
16943	</desc>
16944	<param name="serialPort" type="ISerialPort" dir="in"/>
16945	</method>
16946
16947	<method name="onParallelPortChange">
16948	<desc>
16949	Triggered when settings of a parallel port of the
16950	associated virtual machine have changed.
16951
16952	<result name="VBOX_E_INVALID_VM_STATE">
16953	Session state prevents operation.
16954	</result>
16955	<result name="VBOX_E_INVALID_OBJECT_STATE">
16956	Session type prevents operation.
16957	</result>
16958
16959	</desc>
16960	<param name="parallelPort" type="IParallelPort" dir="in"/>
16961	</method>
16962
16963	<method name="onStorageControllerChange">
16964	<desc>
16965	Triggered when settings of a storage controller of the
16966	associated virtual machine have changed.
16967
16968	<result name="VBOX_E_INVALID_VM_STATE">
16969	Session state prevents operation.
16970	</result>
16971	<result name="VBOX_E_INVALID_OBJECT_STATE">
16972	Session type prevents operation.
16973	</result>
16974
16975	</desc>
16976	</method>
16977
16978	<method name="onMediumChange">
16979	<desc>
16980	Triggered when attached media of the
16981	associated virtual machine have changed.
16982
16983	<result name="VBOX_E_INVALID_VM_STATE">
16984	Session state prevents operation.
16985	</result>
16986	<result name="VBOX_E_INVALID_OBJECT_STATE">
16987	Session type prevents operation.
16988	</result>
16989
16990	</desc>
16991
16992	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
16993	<desc>The medium attachment which changed.</desc>
16994	</param>
16995	<param name="force" type="boolean" dir="in">
16996	<desc>If the medium change was forced.</desc>
16997	</param>
16998	</method>
16999
17000	<method name="onStorageDeviceChange">
17001	<desc>
17002	Triggered when attached storage devices of the
17003	associated virtual machine have changed.
17004
17005	<result name="VBOX_E_INVALID_VM_STATE">
17006	Session state prevents operation.
17007	</result>
17008	<result name="VBOX_E_INVALID_OBJECT_STATE">
17009	Session type prevents operation.
17010	</result>
17011
17012	</desc>
17013
17014	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17015	<desc>The medium attachment which changed.</desc>
17016	</param>
17017	<param name="remove" type="boolean" dir="in">
17018	<desc>TRUE if the device is removed, FALSE if it was added.</desc>
17019	</param>
17020	<param name="silent" type="boolean" dir="in">
17021	<desc>TRUE if the device is is silently reconfigured without
17022	notifying the guest about it.</desc>
17023	</param>
17024	</method>
17025
17026	<method name="onClipboardModeChange">
17027	<desc>
17028	Notification when the shared clipboard mode changes.
17029	</desc>
17030	<param name="clipboardMode" type="ClipboardMode" dir="in">
17031	<desc>The new shared clipboard mode.</desc>
17032	</param>
17033	</method>
17034
17035	<method name="onDragAndDropModeChange">
17036	<desc>
17037	Notification when the drag'n'drop mode changes.
17038	</desc>
17039	<param name="dragAndDropMode" type="DragAndDropMode" dir="in">
17040	<desc>The new mode for drag'n'drop.</desc>
17041	</param>
17042	</method>
17043
17044	<method name="onCPUChange">
17045	<desc>
17046	Notification when a CPU changes.
17047	</desc>
17048	<param name="cpu" type="unsigned long" dir="in">
17049	<desc>The CPU which changed</desc>
17050	</param>
17051	<param name="add" type="boolean" dir="in">
17052	<desc>Flag whether the CPU was added or removed</desc>
17053	</param>
17054	</method>
17055
17056	<method name="onCPUExecutionCapChange">
17057	<desc>
17058	Notification when the CPU execution cap changes.
17059	</desc>
17060	<param name="executionCap" type="unsigned long" dir="in">
17061	<desc>The new CPU execution cap value. (1-100)</desc>
17062	</param>
17063	</method>
17064
17065	<method name="onVRDEServerChange">
17066	<desc>
17067	Triggered when settings of the VRDE server object of the
17068	associated virtual machine have changed.
17069
17070	<result name="VBOX_E_INVALID_VM_STATE">
17071	Session state prevents operation.
17072	</result>
17073	<result name="VBOX_E_INVALID_OBJECT_STATE">
17074	Session type prevents operation.
17075	</result>
17076
17077	</desc>
17078	<param name="restart" type="boolean" dir="in">
17079	<desc>Flag whether the server must be restarted</desc>
17080	</param>
17081	</method>
17082
17083	<method name="onUSBControllerChange">
17084	<desc>
17085	Triggered when settings of the USB controller object of the
17086	associated virtual machine have changed.
17087
17088	<result name="VBOX_E_INVALID_VM_STATE">
17089	Session state prevents operation.
17090	</result>
17091	<result name="VBOX_E_INVALID_OBJECT_STATE">
17092	Session type prevents operation.
17093	</result>
17094
17095	</desc>
17096	</method>
17097
17098	<method name="onSharedFolderChange">
17099	<desc>
17100	Triggered when a permanent (global or machine) shared folder has been
17101	created or removed.
17102	<note>
17103	We don't pass shared folder parameters in this notification because
17104	the order in which parallel notifications are delivered is not defined,
17105	therefore it could happen that these parameters were outdated by the
17106	time of processing this notification.
17107	</note>
17108
17109	<result name="VBOX_E_INVALID_VM_STATE">
17110	Session state prevents operation.
17111	</result>
17112	<result name="VBOX_E_INVALID_OBJECT_STATE">
17113	Session type prevents operation.
17114	</result>
17115
17116	</desc>
17117	<param name="global" type="boolean" dir="in"/>
17118	</method>
17119
17120	<method name="onUSBDeviceAttach">
17121	<desc>
17122	Triggered when a request to capture a USB device (as a result
17123	of matched USB filters or direct call to
17124	<link to="IConsole::attachUSBDevice"/>) has completed.
17125	A @c null @a error object means success, otherwise it
17126	describes a failure.
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="device" type="IUSBDevice" dir="in"/>
17137	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17138	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
17139	</method>
17140
17141	<method name="onUSBDeviceDetach">
17142	<desc>
17143	Triggered when a request to release the USB device (as a result
17144	of machine termination or direct call to
17145	<link to="IConsole::detachUSBDevice"/>) has completed.
17146	A @c null @a error object means success, otherwise it
17147	describes a failure.
17148
17149	<result name="VBOX_E_INVALID_VM_STATE">
17150	Session state prevents operation.
17151	</result>
17152	<result name="VBOX_E_INVALID_OBJECT_STATE">
17153	Session type prevents operation.
17154	</result>
17155
17156	</desc>
17157	<param name="id" type="uuid" mod="string" dir="in"/>
17158	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17159	</method>
17160
17161	<method name="onShowWindow">
17162	<desc>
17163	Called by <link to="IMachine::canShowConsoleWindow"/> and by
17164	<link to="IMachine::showConsoleWindow"/> in order to notify
17165	console listeners
17166	<link to="ICanShowWindowEvent"/>
17167	and <link to="IShowWindowEvent"/>.
17168
17169	<result name="VBOX_E_INVALID_OBJECT_STATE">
17170	Session type prevents operation.
17171	</result>
17172
17173	</desc>
17174	<param name="check" type="boolean" dir="in"/>
17175	<param name="canShow" type="boolean" dir="out"/>
17176	<param name="winId" type="long long" dir="out"/>
17177	</method>
17178
17179	<method name="onBandwidthGroupChange">
17180	<desc>
17181	Notification when one of the bandwidth groups change.
17182	</desc>
17183	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
17184	<desc>The bandwidth group which changed.</desc>
17185	</param>
17186	</method>
17187
17188	<method name="accessGuestProperty">
17189	<desc>
17190	Called by <link to="IMachine::getGuestProperty"/> and by
17191	<link to="IMachine::setGuestProperty"/> in order to read and
17192	modify guest properties.
17193
17194	<result name="VBOX_E_INVALID_VM_STATE">
17195	Machine session is not open.
17196	</result>
17197	<result name="VBOX_E_INVALID_OBJECT_STATE">
17198	Session type is not direct.
17199	</result>
17200
17201	</desc>
17202	<param name="name" type="wstring" dir="in"/>
17203	<param name="value" type="wstring" dir="in"/>
17204	<param name="flags" type="wstring" dir="in"/>
17205	<param name="isSetter" type="boolean" dir="in"/>
17206	<param name="retValue" type="wstring" dir="out"/>
17207	<param name="retTimestamp" type="long long" dir="out"/>
17208	<param name="retFlags" type="wstring" dir="out"/>
17209	</method>
17210
17211	<method name="enumerateGuestProperties" const="yes">
17212	<desc>
17213	Return a list of the guest properties matching a set of patterns along
17214	with their values, time stamps and flags.
17215
17216	<result name="VBOX_E_INVALID_VM_STATE">
17217	Machine session is not open.
17218	</result>
17219	<result name="VBOX_E_INVALID_OBJECT_STATE">
17220	Session type is not direct.
17221	</result>
17222
17223	</desc>
17224	<param name="patterns" type="wstring" dir="in">
17225	<desc>
17226	The patterns to match the properties against as a comma-separated
17227	string. If this is empty, all properties currently set will be
17228	returned.
17229	</desc>
17230	</param>
17231	<param name="keys" type="wstring" dir="out" safearray="yes">
17232	<desc>
17233	The key names of the properties returned.
17234	</desc>
17235	</param>
17236	<param name="values" type="wstring" dir="out" safearray="yes">
17237	<desc>
17238	The values of the properties returned. The array entries match the
17239	corresponding entries in the @a key array.
17240	</desc>
17241	</param>
17242	<param name="timestamps" type="long long" dir="out" safearray="yes">
17243	<desc>
17244	The time stamps of the properties returned. The array entries match
17245	the corresponding entries in the @a key array.
17246	</desc>
17247	</param>
17248	<param name="flags" type="wstring" dir="out" safearray="yes">
17249	<desc>
17250	The flags of the properties returned. The array entries match the
17251	corresponding entries in the @a key array.
17252	</desc>
17253	</param>
17254	</method>
17255
17256	<method name="onlineMergeMedium">
17257	<desc>
17258	Triggers online merging of a hard disk. Used internally when deleting
17259	a snapshot while a VM referring to the same hard disk chain is running.
17260
17261	<result name="VBOX_E_INVALID_VM_STATE">
17262	Machine session is not open.
17263	</result>
17264	<result name="VBOX_E_INVALID_OBJECT_STATE">
17265	Session type is not direct.
17266	</result>
17267
17268	</desc>
17269	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17270	<desc>The medium attachment to identify the medium chain.</desc>
17271	</param>
17272	<param name="sourceIdx" type="unsigned long" dir="in">
17273	<desc>The index of the source image in the chain.
17274	Redundant, but drastically reduces IPC.</desc>
17275	</param>
17276	<param name="targetIdx" type="unsigned long" dir="in">
17277	<desc>The index of the target image in the chain.
17278	Redundant, but drastically reduces IPC.</desc>
17279	</param>
17280	<param name="source" type="IMedium" dir="in">
17281	<desc>Merge source medium.</desc>
17282	</param>
17283	<param name="target" type="IMedium" dir="in">
17284	<desc>Merge target medium.</desc>
17285	</param>
17286	<param name="mergeForward" type="boolean" dir="in">
17287	<desc>Merge direction.</desc>
17288	</param>
17289	<param name="parentForTarget" type="IMedium" dir="in">
17290	<desc>For forward merges: new parent for target medium.</desc>
17291	</param>
17292	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
17293	<desc>For backward merges: list of media which need their parent UUID
17294	updated.</desc>
17295	</param>
17296	<param name="progress" type="IProgress" dir="in">
17297	<desc>
17298	Progress object for this operation.
17299	</desc>
17300	</param>
17301	</method>
17302
17303	<method name="enableVMMStatistics">
17304	<desc>
17305	Enables or disables collection of VMM RAM statistics.
17306
17307	<result name="VBOX_E_INVALID_VM_STATE">
17308	Machine session is not open.
17309	</result>
17310	<result name="VBOX_E_INVALID_OBJECT_STATE">
17311	Session type is not direct.
17312	</result>
17313
17314	</desc>
17315	<param name="enable" type="boolean" dir="in">
17316	<desc>True enables statistics collection.</desc>
17317	</param>
17318	</method>
17319
17320	</interface>
17321
17322	<interface
17323	name="ISession" extends="$unknown"
17324	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
17325	wsmap="managed"
17326	>
17327	<desc>
17328	The ISession interface represents a client process and allows for locking
17329	virtual machines (represented by IMachine objects) to prevent conflicting
17330	changes to the machine.
17331
17332	Any caller wishing to manipulate a virtual machine needs to create a session
17333	object first, which lives in its own process space. Such session objects are
17334	then associated with <link to="IMachine" /> objects living in the VirtualBox
17335	server process to coordinate such changes.
17336
17337	There are two typical scenarios in which sessions are used:
17338
17339	<ul>
17340	<li>To alter machine settings or control a running virtual machine, one
17341	needs to lock a machine for a given session (client process) by calling
17342	<link to="IMachine::lockMachine"/>.
17343
17344	Whereas multiple sessions may control a running virtual machine, only
17345	one process can obtain a write lock on the machine to prevent conflicting
17346	changes. A write lock is also needed if a process wants to actually run a
17347	virtual machine in its own context, such as the VirtualBox GUI or
17348	VBoxHeadless front-ends. They must also lock a machine for their own
17349	sessions before they are allowed to power up the virtual machine.
17350
17351	As a result, no machine settings can be altered while another process is
17352	already using it, either because that process is modifying machine settings
17353	or because the machine is running.
17354	</li>
17355	<li>
17356	To start a VM using one of the existing VirtualBox front-ends (e.g. the
17357	VirtualBox GUI or VBoxHeadless), one would use
17358	<link to="IMachine::launchVMProcess"/>, which also takes a session object
17359	as its first parameter. This session then identifies the caller and lets the
17360	caller control the started machine (for example, pause machine execution or
17361	power it down) as well as be notified about machine execution state changes.
17362	</li>
17363	</ul>
17364
17365	How sessions objects are created in a client process depends on whether you use
17366	the Main API via COM or via the webservice:
17367
17368	<ul>
17369	<li>When using the COM API directly, an object of the Session class from the
17370	VirtualBox type library needs to be created. In regular COM C++ client code,
17371	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
17372	This object will then act as a local session object in further calls to open
17373	a session.
17374	</li>
17375
17376	<li>In the webservice, the session manager (IWebsessionManager) instead creates
17377	a session object automatically whenever <link to="IWebsessionManager::logon" />
17378	is called. A managed object reference to that session object can be retrieved by
17379	calling <link to="IWebsessionManager::getSessionObject" />.
17380	</li>
17381	</ul>
17382	</desc>
17383
17384	<attribute name="state" type="SessionState" readonly="yes">
17385	<desc>Current state of this session.</desc>
17386	</attribute>
17387
17388	<attribute name="type" type="SessionType" readonly="yes">
17389	<desc>
17390	Type of this session. The value of this attribute is valid only
17391	if the session currently has a machine locked (i.e. its
17392	<link to="#state" /> is Locked), otherwise an error will be returned.
17393	</desc>
17394	</attribute>
17395
17396	<attribute name="machine" type="IMachine" readonly="yes">
17397	<desc>Machine object associated with this session.</desc>
17398	</attribute>
17399
17400	<attribute name="console" type="IConsole" readonly="yes">
17401	<desc>Console object associated with this session.</desc>
17402	</attribute>
17403
17404	<method name="unlockMachine">
17405	<desc>
17406	Unlocks a machine that was previously locked for the current session.
17407
17408	Calling this method is required every time a machine has been locked
17409	for a particular session using the <link to="IMachine::launchVMProcess" />
17410	or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
17411	the machine will be set to <link to="MachineState_Aborted" /> on the
17412	server, and changes made to the machine settings will be lost.
17413
17414	Generally, it is recommended to unlock all machines explicitly
17415	before terminating the application (regardless of the reason for
17416	the termination).
17417
17418	<note>
17419	Do not expect the session state (<link to="ISession::state" />
17420	to return to "Unlocked" immediately after you invoke this method,
17421	particularly if you have started a new VM process. The session
17422	state will automatically return to "Unlocked" once the VM is no
17423	longer executing, which can of course take a very long time.
17424	</note>
17425
17426	<result name="E_UNEXPECTED">
17427	Session is not locked.
17428	</result>
17429
17430	</desc>
17431	</method>
17432
17433	</interface>
17434
17435	<!--
17436	// IStorageController
17437	/////////////////////////////////////////////////////////////////////////
17438	-->
17439
17440	<enum
17441	name="StorageBus"
17442	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
17443	>
17444	<desc>
17445	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
17446	see <link to="IStorageController::bus" />.
17447	</desc>
17448	<const name="Null" value="0">
17449	<desc>@c null value. Never used by the API.</desc>
17450	</const>
17451	<const name="IDE" value="1"/>
17452	<const name="SATA" value="2"/>
17453	<const name="SCSI" value="3"/>
17454	<const name="Floppy" value="4"/>
17455	<const name="SAS" value="5"/>
17456	</enum>
17457
17458	<enum
17459	name="StorageControllerType"
17460	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
17461	>
17462	<desc>
17463	The exact variant of storage controller hardware presented
17464	to the guest; see <link to="IStorageController::controllerType" />.
17465	</desc>
17466
17467	<const name="Null" value="0">
17468	<desc>@c null value. Never used by the API.</desc>
17469	</const>
17470	<const name="LsiLogic" value="1">
17471	<desc>A SCSI controller of the LsiLogic variant.</desc>
17472	</const>
17473	<const name="BusLogic" value="2">
17474	<desc>A SCSI controller of the BusLogic variant.</desc>
17475	</const>
17476	<const name="IntelAhci" value="3">
17477	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
17478	</const>
17479	<const name="PIIX3" value="4">
17480	<desc>An IDE controller of the PIIX3 variant.</desc>
17481	</const>
17482	<const name="PIIX4" value="5">
17483	<desc>An IDE controller of the PIIX4 variant.</desc>
17484	</const>
17485	<const name="ICH6" value="6">
17486	<desc>An IDE controller of the ICH6 variant.</desc>
17487	</const>
17488	<const name="I82078" value="7">
17489	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
17490	</const>
17491	<const name="LsiLogicSas" value="8">
17492	<desc>A variant of the LsiLogic controller using SAS.</desc>
17493	</const>
17494	</enum>
17495
17496	<enum
17497	name="ChipsetType"
17498	uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
17499	>
17500	<desc>
17501	Type of emulated chipset (mostly southbridge).
17502	</desc>
17503
17504	<const name="Null" value="0">
17505	<desc>@c null value. Never used by the API.</desc>
17506	</const>
17507	<const name="PIIX3" value="1">
17508	<desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
17509	</const>
17510	<const name="ICH9" value="2">
17511	<desc>A ICH9 (I/O Controller Hub) chipset.</desc>
17512	</const>
17513	</enum>
17514
17515	<interface
17516	name="IStorageController" extends="$unknown"
17517	uuid="a1556333-09b6-46d9-bfb7-fc239b7fbe1e"
17518	wsmap="managed"
17519	>
17520	<desc>
17521	Represents a storage controller that is attached to a virtual machine
17522	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
17523	attached to storage controllers in a real computer, virtual drives
17524	(represented by <link to="IMediumAttachment" />) are attached to virtual
17525	storage controllers, represented by this interface.
17526
17527	As opposed to physical hardware, VirtualBox has a very generic concept
17528	of a storage controller, and for purposes of the Main API, all virtual
17529	storage is attached to virtual machines via instances of this interface.
17530	There are five types of such virtual storage controllers: IDE, SCSI, SATA,
17531	SAS and Floppy (see <link to="#bus" />). Depending on which of these four
17532	is used, certain sub-types may be available and can be selected in
17533	<link to="#controllerType" />.
17534
17535	Depending on these settings, the guest operating system might see
17536	significantly different virtual hardware.
17537	</desc>
17538
17539	<attribute name="name" type="wstring" readonly="yes">
17540	<desc>
17541	Name of the storage controller, as originally specified with
17542	<link to="IMachine::addStorageController" />. This then uniquely
17543	identifies this controller with other method calls such as
17544	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
17545	</desc>
17546	</attribute>
17547
17548	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
17549	<desc>
17550	Maximum number of devices which can be attached to one port.
17551	</desc>
17552	</attribute>
17553
17554	<attribute name="minPortCount" type="unsigned long" readonly="yes">
17555	<desc>
17556	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
17557	</desc>
17558	</attribute>
17559
17560	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
17561	<desc>
17562	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
17563	</desc>
17564	</attribute>
17565
17566	<attribute name="instance" type="unsigned long">
17567	<desc>
17568	The instance number of the device in the running VM.
17569	</desc>
17570	</attribute>
17571
17572	<attribute name="portCount" type="unsigned long">
17573	<desc>
17574	The number of currently usable ports on the controller.
17575	The minimum and maximum number of ports for one controller are
17576	stored in <link to="IStorageController::minPortCount"/>
17577	and <link to="IStorageController::maxPortCount"/>.
17578	</desc>
17579	</attribute>
17580
17581	<attribute name="bus" type="StorageBus" readonly="yes">
17582	<desc>
17583	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
17584	</desc>
17585	</attribute>
17586
17587	<attribute name="controllerType" type="StorageControllerType">
17588	<desc>
17589	The exact variant of storage controller hardware presented
17590	to the guest.
17591	Depending on this value, VirtualBox will provide a different
17592	virtual storage controller hardware to the guest.
17593	For SATA, SAS and floppy controllers, only one variant is
17594	available, but for IDE and SCSI, there are several.
17595
17596	For SCSI controllers, the default type is LsiLogic.
17597	</desc>
17598	</attribute>
17599
17600	<attribute name="useHostIOCache" type="boolean">
17601	<desc>
17602	If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
17603	caches and use synchronous file APIs on the host. This was the only option in the API before
17604	VirtualBox 3.2 and is still the default for IDE controllers.
17605
17606	If false, the host I/O cache will be disabled for image files attached to this storage controller.
17607	Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
17608	it possible to turn off the host I/O caches because the emulation can handle unaligned access to
17609	the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
17610	virtual machines are running at the same time to prevent I/O cache related hangs.
17611	This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
17612	</desc>
17613	</attribute>
17614
17615	<attribute name="bootable" type="boolean" readonly="yes">
17616	<desc>
17617	Returns whether it is possible to boot from disks attached to this controller.
17618	</desc>
17619	</attribute>
17620	</interface>
17621
17622	<if target="wsdl">
17623
17624	<!--
17625	// IManagedObjectRef
17626	/////////////////////////////////////////////////////////////////////////
17627	-->
17628
17629	<interface
17630	name="IManagedObjectRef" extends="$unknown"
17631	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
17632	internal="yes"
17633	wsmap="managed"
17634	wscpp="hardcoded"
17635	>
17636	<desc>
17637	Managed object reference.
17638
17639	Only within the webservice, a managed object reference (which is really
17640	an opaque number) allows a webservice client to address an object
17641	that lives in the address space of the webservice server.
17642
17643	Behind each managed object reference, there is a COM object that lives
17644	in the webservice server's address space. The COM object is not freed
17645	until the managed object reference is released, either by an explicit
17646	call to <link to="IManagedObjectRef::release" /> or by logging off from
17647	the webservice (<link to="IWebsessionManager::logoff" />), which releases
17648	all objects created during the webservice session.
17649
17650	Whenever a method call of the VirtualBox API returns a COM object, the
17651	webservice representation of that method will instead return a
17652	managed object reference, which can then be used to invoke methods
17653	on that object.
17654	</desc>
17655
17656	<method name="getInterfaceName">
17657	<desc>
17658	Returns the name of the interface that this managed object represents,
17659	for example, "IMachine", as a string.
17660	</desc>
17661	<param name="return" type="wstring" dir="return"/>
17662	</method>
17663
17664	<method name="release">
17665	<desc>
17666	Releases this managed object reference and frees the resources that
17667	were allocated for it in the webservice server process. After calling
17668	this method, the identifier of the reference can no longer be used.
17669	</desc>
17670	</method>
17671
17672	</interface>
17673
17674	<!--
17675	// IWebsessionManager
17676	/////////////////////////////////////////////////////////////////////////
17677	-->
17678
17679	<interface
17680	name="IWebsessionManager" extends="$unknown"
17681	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
17682	internal="yes"
17683	wsmap="global"
17684	wscpp="hardcoded"
17685	>
17686	<desc>
17687	Websession manager. This provides essential services
17688	to webservice clients.
17689	</desc>
17690	<method name="logon">
17691	<desc>
17692	Logs a new client onto the webservice and returns a managed object reference to
17693	the IVirtualBox instance, which the client can then use as a basis to further
17694	queries, since all calls to the VirtualBox API are based on the IVirtualBox
17695	interface, in one way or the other.
17696	</desc>
17697	<param name="username" type="wstring" dir="in"/>
17698	<param name="password" type="wstring" dir="in"/>
17699	<param name="return" type="IVirtualBox" dir="return"/>
17700	</method>
17701
17702	<method name="getSessionObject">
17703	<desc>
17704	Returns a managed object reference to the internal ISession object that was created
17705	for this web service session when the client logged on.
17706
17707	<see><link to="ISession"/></see>
17708	</desc>
17709	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17710	<param name="return" type="ISession" dir="return"/>
17711	</method>
17712
17713	<method name="logoff">
17714	<desc>
17715	Logs off the client who has previously logged on with <link to="IWebsessionManager::logon" />
17716	and destroys all resources associated with the session (most importantly, all
17717	managed objects created in the server while the session was active).
17718	</desc>
17719	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17720	</method>
17721
17722	</interface>
17723
17724	</if>
17725
17726	<!--
17727	// IPerformanceCollector & friends
17728	/////////////////////////////////////////////////////////////////////////
17729	-->
17730
17731	<interface
17732	name="IPerformanceMetric" extends="$unknown"
17733	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
17734	>
17735	<desc>
17736	The IPerformanceMetric interface represents parameters of the given
17737	performance metric.
17738	</desc>
17739
17740	<attribute name="metricName" type="wstring" readonly="yes">
17741	<desc>
17742	Name of the metric.
17743	</desc>
17744	</attribute>
17745
17746	<attribute name="object" type="$unknown" readonly="yes">
17747	<desc>
17748	Object this metric belongs to.
17749	</desc>
17750	</attribute>
17751
17752	<attribute name="description" type="wstring" readonly="yes">
17753	<desc>
17754	Textual description of the metric.
17755	</desc>
17756	</attribute>
17757
17758	<attribute name="period" type="unsigned long" readonly="yes">
17759	<desc>
17760	Time interval between samples, measured in seconds.
17761	</desc>
17762	</attribute>
17763
17764	<attribute name="count" type="unsigned long" readonly="yes">
17765	<desc>
17766	Number of recent samples retained by the performance collector for this
17767	metric.
17768
17769	When the collected sample count exceeds this number, older samples
17770	are discarded.
17771	</desc>
17772	</attribute>
17773
17774	<attribute name="unit" type="wstring" readonly="yes">
17775	<desc>
17776	Unit of measurement.
17777	</desc>
17778	</attribute>
17779
17780	<attribute name="minimumValue" type="long" readonly="yes">
17781	<desc>
17782	Minimum possible value of this metric.
17783	</desc>
17784	</attribute>
17785
17786	<attribute name="maximumValue" type="long" readonly="yes">
17787	<desc>
17788	Maximum possible value of this metric.
17789	</desc>
17790	</attribute>
17791	</interface>
17792
17793	<interface
17794	name="IPerformanceCollector" extends="$unknown"
17795	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
17796	wsmap="managed"
17797	>
17798	<desc>
17799	The IPerformanceCollector interface represents a service that collects
17800	and stores performance metrics data.
17801
17802	Performance metrics are associated with objects of interfaces like IHost
17803	and IMachine. Each object has a distinct set of performance metrics. The
17804	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
17805
17806	Metric data is collected at the specified intervals and is retained
17807	internally. The interval and the number of retained samples can be set
17808	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
17809	and collection settings are not persistent, they are discarded as soon as
17810	VBoxSVC process terminates. Moreover, metric settings and data associated
17811	with a particular VM only exist while VM is running. They disappear as
17812	soon as VM shuts down. It is not possible to set up metrics for machines
17813	that are powered off. One needs to start VM first, then set up metric
17814	collection parameters.
17815
17816	Metrics are organized hierarchically, with each level separated by a
17817	slash (/) character. Generally, the scheme for metric names is like this:
17818
17819	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
17820
17821	"Category/Metric" together form the base metric name. A base metric is
17822	the smallest unit for which a sampling interval and the number of
17823	retained samples can be set. Only base metrics can be enabled and
17824	disabled. All sub-metrics are collected when their base metric is
17825	collected. Collected values for any set of sub-metrics can be queried
17826	with <link to="IPerformanceCollector::queryMetricsData" />.
17827
17828	For example "CPU/Load/User:avg" metric name stands for the "CPU"
17829	category, "Load" metric, "User" submetric, "average" aggregate. An
17830	aggregate function is computed over all retained data. Valid aggregate
17831	functions are:
17832
17833	<ul>
17834	<li>avg -- average</li>
17835	<li>min -- minimum</li>
17836	<li>max -- maximum</li>
17837	</ul>
17838
17839	When setting up metric parameters, querying metric data, enabling or
17840	disabling metrics wildcards can be used in metric names to specify a
17841	subset of metrics. For example, to select all CPU-related metrics
17842	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
17843	so on. To query metric values without aggregates <tt>*:</tt> can be used.
17844
17845	The valid names for base metrics are:
17846
17847	<ul>
17848	<li>CPU/Load</li>
17849	<li>CPU/MHz</li>
17850	<li>RAM/Usage</li>
17851	<li>RAM/VMM</li>
17852	</ul>
17853
17854	The general sequence for collecting and retrieving the metrics is:
17855	<ul>
17856	<li>
17857	Obtain an instance of IPerformanceCollector with
17858	<link to="IVirtualBox::performanceCollector" />
17859	</li>
17860	<li>
17861	Allocate and populate an array with references to objects the metrics
17862	will be collected for. Use references to IHost and IMachine objects.
17863	</li>
17864	<li>
17865	Allocate and populate an array with base metric names the data will
17866	be collected for.
17867	</li>
17868	<li>
17869	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
17870	the metric data will be collected and stored.
17871	</li>
17872	<li>
17873	Wait for the data to get collected.
17874	</li>
17875	<li>
17876	Allocate and populate an array with references to objects the metric
17877	values will be queried for. You can re-use the object array used for
17878	setting base metrics.
17879	</li>
17880	<li>
17881	Allocate and populate an array with metric names the data will be
17882	collected for. Note that metric names differ from base metric names.
17883	</li>
17884	<li>
17885	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
17886	that have been collected so far are returned. Note that the values
17887	are still retained internally and data collection continues.
17888	</li>
17889	</ul>
17890
17891	For an example of usage refer to the following files in VirtualBox SDK:
17892	<ul>
17893	<li>
17894	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
17895	</li>
17896	<li>
17897	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
17898	</li>
17899	</ul>
17900	</desc>
17901
17902	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
17903	<desc>
17904	Array of unique names of metrics.
17905
17906	This array represents all metrics supported by the performance
17907	collector. Individual objects do not necessarily support all of them.
17908	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
17909	list of supported metrics for a particular object.
17910	</desc>
17911	</attribute>
17912
17913	<method name="getMetrics">
17914	<desc>
17915	Returns parameters of specified metrics for a set of objects.
17916	<note>
17917	@c Null metrics array means all metrics. @c Null object array means
17918	all existing objects.
17919	</note>
17920	</desc>
17921	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17922	<desc>
17923	Metric name filter. Currently, only a comma-separated list of metrics
17924	is supported.
17925	</desc>
17926	</param>
17927	<param name="objects" type="$unknown" dir="in" safearray="yes">
17928	<desc>
17929	Set of objects to return metric parameters for.
17930	</desc>
17931	</param>
17932	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
17933	<desc>
17934	Array of returned metric parameters.
17935	</desc>
17936	</param>
17937	</method>
17938
17939	<method name="setupMetrics">
17940	<desc>
17941	Sets parameters of specified base metrics for a set of objects. Returns
17942	an array of <link to="IPerformanceMetric" /> describing the metrics
17943	have been affected.
17944	<note>
17945	@c Null or empty metric name array means all metrics. @c Null or
17946	empty object array means all existing objects. If metric name array
17947	contains a single element and object array contains many, the single
17948	metric name array element is applied to each object array element to
17949	form metric/object pairs.
17950	</note>
17951	</desc>
17952	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17953	<desc>
17954	Metric name filter. Comma-separated list of metrics with wildcard
17955	support.
17956	</desc>
17957	</param>
17958	<param name="objects" type="$unknown" dir="in" safearray="yes">
17959	<desc>
17960	Set of objects to setup metric parameters for.
17961	</desc>
17962	</param>
17963	<param name="period" type="unsigned long" dir="in">
17964	<desc>
17965	Time interval in seconds between two consecutive samples of
17966	performance data.
17967	</desc>
17968	</param>
17969	<param name="count" type="unsigned long" dir="in">
17970	<desc>
17971	Number of samples to retain in performance data history. Older
17972	samples get discarded.
17973	</desc>
17974	</param>
17975	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
17976	<desc>
17977	Array of metrics that have been modified by the call to this method.
17978	</desc>
17979	</param>
17980	</method>
17981
17982	<method name="enableMetrics">
17983	<desc>
17984	Turns on collecting specified base metrics. Returns an array of
17985	<link to="IPerformanceMetric" /> describing the metrics have been
17986	affected.
17987	<note>
17988	@c Null or empty metric name array means all metrics. @c Null or
17989	empty object array means all existing objects. If metric name array
17990	contains a single element and object array contains many, the single
17991	metric name array element is applied to each object array element to
17992	form metric/object pairs.
17993	</note>
17994	</desc>
17995	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17996	<desc>
17997	Metric name filter. Comma-separated list of metrics with wildcard
17998	support.
17999	</desc>
18000	</param>
18001	<param name="objects" type="$unknown" dir="in" safearray="yes">
18002	<desc>
18003	Set of objects to enable metrics for.
18004	</desc>
18005	</param>
18006	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
18007	<desc>
18008	Array of metrics that have been modified by the call to this method.
18009	</desc>
18010	</param>
18011	</method>
18012
18013	<method name="disableMetrics">
18014	<desc>
18015	Turns off collecting specified base metrics. Returns an array of
18016	<link to="IPerformanceMetric" /> describing the metrics have been
18017	affected.
18018	<note>
18019	@c Null or empty metric name array means all metrics. @c Null or
18020	empty object array means all existing objects. If metric name array
18021	contains a single element and object array contains many, the single
18022	metric name array element is applied to each object array element to
18023	form metric/object pairs.
18024	</note>
18025	</desc>
18026	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18027	<desc>
18028	Metric name filter. Comma-separated list of metrics with wildcard
18029	support.
18030	</desc>
18031	</param>
18032	<param name="objects" type="$unknown" dir="in" safearray="yes">
18033	<desc>
18034	Set of objects to disable metrics for.
18035	</desc>
18036	</param>
18037	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
18038	<desc>
18039	Array of metrics that have been modified by the call to this method.
18040	</desc>
18041	</param>
18042	</method>
18043
18044	<method name="queryMetricsData">
18045	<desc>
18046	Queries collected metrics data for a set of objects.
18047
18048	The data itself and related metric information are returned in seven
18049	parallel and one flattened array of arrays. Elements of
18050	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
18051	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
18052	the same index describe one set of values corresponding to a single
18053	metric.
18054
18055	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
18056	start and length of a sub-array is indicated by
18057	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
18058	value for metric <tt>metricNames[i]</tt> is at
18059	<tt>returnData[returnIndices[i]]</tt>.
18060
18061	<note>
18062	@c Null or empty metric name array means all metrics. @c Null or
18063	empty object array means all existing objects. If metric name array
18064	contains a single element and object array contains many, the single
18065	metric name array element is applied to each object array element to
18066	form metric/object pairs.
18067	</note>
18068	<note>
18069	Data collection continues behind the scenes after call to @c
18070	queryMetricsData. The return data can be seen as the snapshot of the
18071	current state at the time of @c queryMetricsData call. The internally
18072	kept metric values are not cleared by the call. This makes possible
18073	querying different subsets of metrics or aggregates with subsequent
18074	calls. If periodic querying is needed it is highly suggested to query
18075	the values with @c interval*count period to avoid confusion. This way
18076	a completely new set of data values will be provided by each query.
18077	</note>
18078	</desc>
18079	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18080	<desc>
18081	Metric name filter. Comma-separated list of metrics with wildcard
18082	support.
18083	</desc>
18084	</param>
18085	<param name="objects" type="$unknown" dir="in" safearray="yes">
18086	<desc>
18087	Set of objects to query metrics for.
18088	</desc>
18089	</param>
18090	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
18091	<desc>
18092	Names of metrics returned in @c returnData.
18093	</desc>
18094	</param>
18095	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
18096	<desc>
18097	Objects associated with metrics returned in @c returnData.
18098	</desc>
18099	</param>
18100	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
18101	<desc>
18102	Units of measurement for each returned metric.
18103	</desc>
18104	</param>
18105	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
18106	<desc>
18107	Divisor that should be applied to return values in order to get
18108	floating point values. For example:
18109	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
18110	will retrieve the floating point value of i-th sample of the first
18111	metric.
18112	</desc>
18113	</param>
18114	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
18115	<desc>
18116	Sequence numbers of the first elements of value sequences of
18117	particular metrics returned in @c returnData. For aggregate metrics
18118	it is the sequence number of the sample the aggregate started
18119	calculation from.
18120	</desc>
18121	</param>
18122	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
18123	<desc>
18124	Indices of the first elements of value sequences of particular
18125	metrics returned in @c returnData.
18126	</desc>
18127	</param>
18128	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
18129	<desc>
18130	Lengths of value sequences of particular metrics.
18131	</desc>
18132	</param>
18133	<param name="returnData" type="long" dir="return" safearray="yes">
18134	<desc>
18135	Flattened array of all metric data containing sequences of values for
18136	each metric.
18137	</desc>
18138	</param>
18139	</method>
18140
18141	</interface>
18142
18143	<enum
18144	name="NATAliasMode"
18145	uuid="67772168-50d9-11df-9669-7fb714ee4fa1"
18146	>
18147	<desc></desc>
18148	<const name="AliasLog" value="0x1">
18149	<desc></desc>
18150	</const>
18151	<const name="AliasProxyOnly" value="0x02">
18152	<desc></desc>
18153	</const>
18154	<const name="AliasUseSamePorts" value="0x04">
18155	<desc></desc>
18156	</const>
18157	</enum>
18158
18159	<enum
18160	name="NATProtocol"
18161	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
18162	>
18163	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
18164	<const name="UDP" value="0">
18165	<desc>Port-forwarding uses UDP protocol.</desc>
18166	</const>
18167	<const name="TCP" value="1">
18168	<desc>Port-forwarding uses TCP protocol.</desc>
18169	</const>
18170	</enum>
18171
18172	<interface
18173	name="INATEngine" extends="$unknown"
18174	uuid="26451b99-3b2d-4dcb-8e4b-d63654218175"
18175	wsmap="managed"
18176	>
18177	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
18178	allows for changing NAT behavior such as port-forwarding rules. This interface is
18179	used in the <link to="INetworkAdapter::NATEngine" /> attribute.</desc>
18180	<attribute name="network" type="wstring">
18181	<desc>The network attribute of the NAT engine (the same value is used with built-in
18182	DHCP server to fill corresponding fields of DHCP leases).</desc>
18183	</attribute>
18184	<attribute name="hostIP" type="wstring">
18185	<desc>IP of host interface to bind all opened sockets to.
18186	<note>Changing this does not change binding of port forwarding.</note>
18187	</desc>
18188	</attribute>
18189	<attribute name="TFTPPrefix" type="wstring">
18190	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
18191	the corresponding fields of DHCP leases.</desc>
18192	</attribute>
18193	<attribute name="TFTPBootFile" type="wstring">
18194	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
18195	the corresponding fields of DHCP leases.</desc>
18196	</attribute>
18197	<attribute name="TFTPNextServer" type="wstring">
18198	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
18199	the corresponding fields of DHCP leases.
18200	<note>The preferred form is IPv4 addresses.</note>
18201	</desc>
18202	</attribute>
18203	<attribute name="aliasMode" type="unsigned long">
18204	<desc></desc>
18205	</attribute>
18206	<attribute name="DNSPassDomain" type="boolean">
18207	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
18208	</attribute>
18209	<attribute name="DNSProxy" type="boolean">
18210	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18211	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
18212	</attribute>
18213	<attribute name="DNSUseHostResolver" type="boolean">
18214	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18215	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
18216	</attribute>
18217	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
18218	<desc>Array of NAT port-forwarding rules in string representation, in the following
18219	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
18220	</attribute>
18221	<method name="setNetworkSettings">
18222	<desc>Sets network configuration of the NAT engine.</desc>
18223	<param name="mtu" type="unsigned long" dir="in">
18224	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
18225	</param>
18226	<param name="sockSnd" type="unsigned long" dir="in">
18227	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
18228	</param>
18229	<param name="sockRcv" type="unsigned long" dir="in">
18230	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
18231	</param>
18232	<param name="TcpWndSnd" type="unsigned long" dir="in">
18233	<desc>Initial size of the NAT engine's sending TCP window in bytes when
18234	establishing a new TCP connection.</desc>
18235	</param>
18236	<param name="TcpWndRcv" type="unsigned long" dir="in">
18237	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
18238	establishing a new TCP connection.</desc>
18239	</param>
18240	</method>
18241	<method name="getNetworkSettings">
18242	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
18243	for parameter descriptions.</desc>
18244	<param name="mtu" type="unsigned long" dir="out" />
18245	<param name="sockSnd" type="unsigned long" dir="out" />
18246	<param name="sockRcv" type="unsigned long" dir="out" />
18247	<param name="TcpWndSnd" type="unsigned long" dir="out" />
18248	<param name="TcpWndRcv" type="unsigned long" dir="out" />
18249	</method>
18250	<method name="addRedirect">
18251	<desc>Adds a new NAT port-forwarding rule.</desc>
18252	<param name="name" type="wstring" dir="in">
18253	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
18254	auto-generates one using the other parameters.</desc>
18255	</param>
18256	<param name="proto" type="NATProtocol" dir="in">
18257	<desc>Protocol handled with the rule.</desc>
18258	</param>
18259	<param name="hostIP" type="wstring" dir="in">
18260	<desc>IP of the host interface to which the rule should apply. An empty ip address is
18261	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
18262	</param>
18263	<param name="hostPort" type="unsigned short" dir="in">
18264	<desc>The port number to listen on.</desc>
18265	</param>
18266	<param name="guestIP" type="wstring" dir="in">
18267	<desc>The IP address of the guest which the NAT engine will forward matching packets
18268	to. An empty IP address is acceptable, in which case the NAT engine will forward
18269	packets to the first DHCP lease (x.x.x.15).</desc>
18270	</param>
18271	<param name="guestPort" type="unsigned short" dir="in">
18272	<desc>The port number to forward.</desc>
18273	</param>
18274	</method>
18275	<method name="removeRedirect">
18276	<desc>Removes a port-forwarding rule that was previously registered.</desc>
18277	<param name="name" type="wstring" dir="in">
18278	<desc>The name of the rule to delete.</desc>
18279	</param>
18280	</method>
18281	</interface>
18282
18283	<!--
18284	// IExtPackManager
18285	/////////////////////////////////////////////////////////////////////////
18286	-->
18287
18288	<interface
18289	name="IExtPackPlugIn" extends="$unknown"
18290	uuid="58000040-e718-4746-bbce-4b86d96da461"
18291	wsmap="suppress"
18292	>
18293	<desc>
18294	Interface for keeping information about a plug-in that ships with an
18295	extension pack.
18296	</desc>
18297	<attribute name="name" type="wstring" readonly="yes">
18298	<desc>The plug-in name.</desc>
18299	</attribute>
18300	<attribute name="description" type="wstring" readonly="yes">
18301	<desc>The plug-in description.</desc>
18302	</attribute>
18303	<attribute name="frontend" type="wstring" readonly="yes">
18304	<desc>
18305	The name of the frontend or component name this plug-in plugs into.
18306	</desc>
18307	</attribute>
18308	<attribute name="modulePath" type="wstring" readonly="yes">
18309	<desc> The module path. </desc>
18310	</attribute>
18311	</interface>
18312
18313	<interface
18314	name="IExtPackBase" extends="$unknown"
18315	uuid="f79b75d8-2890-4f34-ffff-ffffa144e82c"
18316	wsmap="suppress"
18317	>
18318	<desc>
18319	Interface for querying information about an extension pack as well as
18320	accessing COM objects within it.
18321	</desc>
18322	<attribute name="name" type="wstring" readonly="yes">
18323	<desc>The extension pack name. This is unique.</desc>
18324	</attribute>
18325	<attribute name="description" type="wstring" readonly="yes">
18326	<desc>The extension pack description.</desc>
18327	</attribute>
18328	<attribute name="version" type="wstring" readonly="yes">
18329	<desc>
18330	The extension pack version string. This is restricted to the dotted
18331	version number and optionally a build indicator. No tree revision or
18332	tag will be included in the string as those things are available as
18333	separate properties. An optional publisher tag may be present like for
18334	<link to="IVirtualBox::version"/>.
18335
18336	Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2".
18337	</desc>
18338	</attribute>
18339	<attribute name="revision" type="unsigned long" readonly="yes">
18340	<desc>The extension pack internal revision number.</desc>
18341	</attribute>
18342	<attribute name="edition" type="wstring" readonly="yes">
18343	<desc>
18344	Edition indicator. This is usually empty.
18345
18346	Can for instance be used to help distinguishing between two editions
18347	of the same extension pack where only the license, service contract or
18348	something differs.
18349	</desc>
18350	</attribute>
18351	<attribute name="VRDEModule" type="wstring" readonly="yes">
18352	<desc>The name of the VRDE module if the extension pack sports one.</desc>
18353	</attribute>
18354	<attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes">
18355	<desc>Plug-ins provided by this extension pack.</desc>
18356	</attribute>
18357	<attribute name="usable" type="boolean" readonly="yes">
18358	<desc>
18359	Indicates whether the extension pack is usable or not.
18360
18361	There are a number of reasons why an extension pack might be unusable,
18362	typical examples would be broken installation/file or that it is
18363	incompatible with the current VirtualBox version.
18364	</desc>
18365	</attribute>
18366	<attribute name="whyUnusable" type="wstring" readonly="yes">
18367	<desc>
18368	String indicating why the extension pack is not usable. This is an
18369	empty string if usable and always a non-empty string if not usable.
18370	</desc>
18371	</attribute>
18372	<attribute name="showLicense" type="boolean" readonly="yes">
18373	<desc>Whether to show the license before installation</desc>
18374	</attribute>
18375	<attribute name="license" type="wstring" readonly="yes">
18376	<desc>
18377	The default HTML license text for the extension pack. Same as
18378	calling <link to="#queryLicense">queryLicense</link> with
18379	preferredLocale and preferredLanguage as empty strings and format set
18380	to html.
18381	</desc>
18382	</attribute>
18383
18384	<method name="queryLicense">
18385	<desc>
18386	Full feature version of the license attribute.
18387	</desc>
18388	<param name="preferredLocale" type="wstring" dir="in">
18389	<desc>
18390	The preferred license locale. Pass an empty string to get the default
18391	license.
18392	</desc>
18393	</param>
18394	<param name="preferredLanguage" type="wstring" dir="in">
18395	<desc>
18396	The preferred license language. Pass an empty string to get the
18397	default language for the locale.
18398	</desc>
18399	</param>
18400	<param name="format" type="wstring" dir="in">
18401	<desc>
18402	The license format: html, rtf or txt. If a license is present there
18403	will always be an HTML of it, the rich text format (RTF) and plain
18404	text (txt) versions are optional. If
18405	</desc>
18406	</param>
18407	<param name="licenseText" type="wstring" dir="return">
18408	<desc>The license text.</desc>
18409	</param>
18410	</method>
18411
18412	</interface>
18413
18414	<interface
18415	name="IExtPack" extends="IExtPackBase"
18416	uuid="431685da-3618-4ebc-b038-833ba829b4b2"
18417	wsmap="suppress"
18418	>
18419	<desc>
18420	Interface for querying information about an extension pack as well as
18421	accessing COM objects within it.
18422	</desc>
18423	<method name="queryObject">
18424	<desc>
18425	Queries the IUnknown interface to an object in the extension pack
18426	main module. This allows plug-ins and others to talk directly to an
18427	extension pack.
18428	</desc>
18429	<param name="objUuid" type="wstring" dir="in">
18430	<desc>The object ID. What exactly this is </desc>
18431	</param>
18432	<param name="returnInterface" type="$unknown" dir="return">
18433	<desc>The queried interface.</desc>
18434	</param>
18435	</method>
18436	</interface>
18437
18438	<interface
18439	name="IExtPackFile" extends="IExtPackBase"
18440	uuid="b6b49f55-efcc-4f08-b486-56e8d8afb10b"
18441	wsmap="suppress"
18442	>
18443	<desc>
18444	Extension pack file (aka tarball, .vbox-extpack) representation returned
18445	by <link to="IExtPackManager::openExtPackFile"/>. This provides the base
18446	extension pack information with the addition of the file name.
18447	</desc>
18448	<attribute name="filePath" type="wstring" readonly="yes">
18449	<desc>
18450	The path to the extension pack file.
18451	</desc>
18452	</attribute>
18453
18454	<method name="install">
18455	<desc>
18456	Install the extension pack.
18457	</desc>
18458	<param name="replace" type="boolean" dir="in">
18459	<desc>
18460	Set this to automatically uninstall any existing extension pack with
18461	the same name as the one being installed.
18462	</desc>
18463	</param>
18464	<param name="displayInfo" type="wstring" dir="in">
18465	<desc>
18466	Platform specific display information. Reserved for future hacks.
18467	</desc>
18468	</param>
18469	<param name="progess" type="IProgress" dir="return">
18470	<desc>
18471	Progress object for the operation.
18472	</desc>
18473	</param>
18474	</method>
18475	</interface>
18476
18477	<interface
18478	name="IExtPackManager" extends="$unknown"
18479	uuid="3295e6ce-b051-47b2-9514-2c588bfe7554"
18480	wsmap="suppress"
18481	>
18482	<desc>
18483	Interface for managing VirtualBox Extension Packs.
18484
18485	TODO: Describe extension packs, how they are managed and how to create
18486	one.
18487	</desc>
18488
18489	<attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
18490	<desc>
18491	List of the installed extension packs.
18492	</desc>
18493	</attribute>
18494
18495	<method name="find">
18496	<desc>
18497	Returns the extension pack with the specified name if found.
18498
18499	<result name="VBOX_E_OBJECT_NOT_FOUND">
18500	No extension pack matching @a name was found.
18501	</result>
18502	</desc>
18503	<param name="name" type="wstring" dir="in">
18504	<desc>The name of the extension pack to locate.</desc>
18505	</param>
18506	<param name="returnData" type="IExtPack" dir="return">
18507	<desc>The extension pack if found.</desc>
18508	</param>
18509	</method>
18510
18511	<method name="openExtPackFile">
18512	<desc>
18513	Attempts to open an extension pack file in preparation for
18514	installation.
18515	</desc>
18516	<param name="path" type="wstring" dir="in">
18517	<desc>The path of the extension pack tarball. This can optionally be
18518	followed by a "::SHA-256=hex-digit" of the tarball. </desc>
18519	</param>
18520	<param name="file" type="IExtPackFile" dir="return">
18521	<desc>The interface of the extension pack file object.</desc>
18522	</param>
18523	</method>
18524
18525	<method name="uninstall">
18526	<desc>Uninstalls an extension pack, removing all related files.</desc>
18527	<param name="name" type="wstring" dir="in">
18528	<desc>The name of the extension pack to uninstall.</desc>
18529	</param>
18530	<param name="forcedRemoval" type="boolean" dir="in">
18531	<desc>
18532	Forced removal of the extension pack. This means that the uninstall
18533	hook will not be called.
18534	</desc>
18535	</param>
18536	<param name="displayInfo" type="wstring" dir="in">
18537	<desc>
18538	Platform specific display information. Reserved for future hacks.
18539	</desc>
18540	</param>
18541	<param name="progess" type="IProgress" dir="return">
18542	<desc>
18543	Progress object for the operation.
18544	</desc>
18545	</param>
18546	</method>
18547
18548	<method name="cleanup">
18549	<desc>Cleans up failed installs and uninstalls</desc>
18550	</method>
18551
18552	<method name="queryAllPlugInsForFrontend">
18553	<desc>
18554	Gets the path to all the plug-in modules for a given frontend.
18555
18556	This is a convenience method that is intended to simplify the plug-in
18557	loading process for a frontend.
18558	</desc>
18559	<param name="frontendName" type="wstring" dir="in">
18560	<desc>The name of the frontend or component.</desc>
18561	</param>
18562	<param name="plugInModules" type="wstring" dir="return" safearray="yes">
18563	<desc>Array containing the plug-in modules (full paths).</desc>
18564	</param>
18565	</method>
18566
18567	<method name="isExtPackUsable">
18568	<desc>Check if the given extension pack is loaded and usable.</desc>
18569	<param name="name" type="wstring" dir="in">
18570	<desc>The name of the extension pack to check for.</desc>
18571	</param>
18572	<param name="usable" type="boolean" dir="return">
18573	<desc>Is the given extension pack loaded and usable.</desc>
18574	</param>
18575	</method>
18576
18577	</interface>
18578
18579	<!--
18580	// BandwidthGroupType
18581	/////////////////////////////////////////////////////////////////////////
18582	-->
18583	<enum
18584	name="BandwidthGroupType"
18585	uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e">
18586
18587	<desc>
18588	Type of a bandwidth control group.
18589	</desc>
18590
18591	<const name="Null" value="0">
18592	<desc>
18593	Null type, must be first.
18594	</desc>
18595	</const>
18596
18597	<const name="Disk" value="1">
18598	<desc>
18599	The bandwidth group controls disk I/O.
18600	</desc>
18601	</const>
18602
18603	<const name="Network" value="2">
18604	<desc>
18605	The bandwidth group controls network I/O.
18606	</desc>
18607	</const>
18608
18609	</enum>
18610
18611	<!--
18612	// IBandwidthGroup
18613	/////////////////////////////////////////////////////////////////////////
18614	-->
18615	<interface
18616	name="IBandwidthGroup" extends="$unknown"
18617	uuid="badea2d7-0261-4146-89f0-6a57cc34833d"
18618	wsmap="managed"
18619	>
18620	<desc>Represents one bandwidth group.</desc>
18621
18622	<attribute name="name" type="wstring" readonly="yes">
18623	<desc>Name of the group.</desc>
18624	</attribute>
18625
18626	<attribute name="type" type="BandwidthGroupType" readonly="yes">
18627	<desc>Type of the group.</desc>
18628	</attribute>
18629
18630	<attribute name="reference" type="unsigned long" readonly="yes">
18631	<desc>How many devices/medium attachements use this group.</desc>
18632	</attribute>
18633
18634	<attribute name="maxBytesPerSec" type="long long">
18635	<desc>The maximum number of bytes which can be transfered by all
18636	entities attached to this group during one second.</desc>
18637	</attribute>
18638
18639	</interface>
18640
18641	<!--
18642	// IBandwidthControl
18643	/////////////////////////////////////////////////////////////////////////
18644	-->
18645	<interface
18646	name="IBandwidthControl" extends="$unknown"
18647	uuid="e2eb3930-d2f4-4f87-be17-0707e30f019f"
18648	wsmap="managed"
18649	>
18650	<desc>
18651	Controls the bandwidth groups of one machine used to cap I/O done by a VM.
18652	This includes network and disk I/O.
18653	</desc>
18654
18655	<attribute name="numGroups" type="unsigned long" readonly="yes">
18656	<desc>
18657	The current number of existing bandwidth groups managed.
18658	</desc>
18659	</attribute>
18660
18661	<method name="createBandwidthGroup">
18662	<desc>
18663	Creates a new bandwidth group.
18664	</desc>
18665
18666	<param name="name" type="wstring" dir="in">
18667	<desc>Name of the bandwidth group.</desc>
18668	</param>
18669	<param name="type" type="BandwidthGroupType" dir="in">
18670	<desc>The type of the bandwidth group (network or disk).</desc>
18671	</param>
18672	<param name="maxBytesPerSec" type="long long" dir="in">
18673	<desc>The maximum number of bytes which can be transfered by all
18674	entities attached to this group during one second.</desc>
18675	</param>
18676	</method>
18677
18678	<method name="deleteBandwidthGroup">
18679	<desc>
18680	Deletes a new bandwidth group.
18681	</desc>
18682
18683	<param name="name" type="wstring" dir="in">
18684	<desc>Name of the bandwidth group to delete.</desc>
18685	</param>
18686	</method>
18687
18688	<method name="getBandwidthGroup" const="yes">
18689	<desc>
18690	Get a bandwidth group by name.
18691	</desc>
18692
18693	<param name="name" type="wstring" dir="in">
18694	<desc>Name of the bandwidth group to get.</desc>
18695	</param>
18696	<param name="bandwidthGroup" type="IBandwidthGroup" dir="return">
18697	<desc>Where to store the bandwidth group on success.</desc>
18698	</param>
18699	</method>
18700
18701	<method name="getAllBandwidthGroups" const="yes">
18702	<desc>
18703	Get all managed bandwidth groups.
18704	</desc>
18705
18706	<param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes">
18707	<desc>The array of managed bandwidth groups.</desc>
18708	</param>
18709	</method>
18710	</interface>
18711
18712	<!--
18713	// IVirtualBoxClient
18714	/////////////////////////////////////////////////////////////////////////
18715	-->
18716
18717	<interface
18718	name="IVirtualBoxClient" extends="$unknown"
18719	uuid="d191281f-b0cb-4d83-a8fa-0d9fd6ba234c"
18720	wsmap="suppress"
18721	>
18722	<desc>
18723	Convenience interface for client applications. Treat this as a
18724	singleton, i.e. never create more than one instance of this interface.
18725
18726	At the moment only available for clients of the local API (not usable
18727	via the webservice). Once the session logic is redesigned this might
18728	change.
18729	</desc>
18730
18731	<attribute name="virtualBox" type="IVirtualBox" readonly="yes">
18732	<desc>
18733	Reference to the server-side API root object.
18734	</desc>
18735	</attribute>
18736
18737	<attribute name="session" type="ISession" readonly="yes">
18738	<desc>
18739	Create a new session object and return the reference to it.
18740	</desc>
18741	</attribute>
18742
18743	<attribute name="eventSource" type="IEventSource" readonly="yes">
18744	<desc>
18745	Event source for VirtualBoxClient events.
18746	</desc>
18747	</attribute>
18748
18749	<method name="checkMachineError">
18750	<desc>
18751	Perform error checking before using an <link to="IMachine"/> object.
18752	Generally useful before starting a VM and all other uses. If anything
18753	is not as it should be then this method will return an appropriate
18754	error.
18755	</desc>
18756
18757	<param name="machine" type="IMachine" dir="in">
18758	<desc>The machine object to check.</desc>
18759	</param>
18760	</method>
18761	</interface>
18762
18763	<!--
18764	// Events
18765	/////////////////////////////////////////////////////////////////////////
18766	-->
18767	<enum
18768	name="VBoxEventType"
18769	uuid="c51645b3-7108-4dce-b5a3-bbf5e4f69ed2"
18770	>
18771
18772	<desc>
18773	Type of an event.
18774	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
18775	</desc>
18776
18777	<const name="Invalid" value="0">
18778	<desc>
18779	Invalid event, must be first.
18780	</desc>
18781	</const>
18782
18783	<const name="Any" value="1">
18784	<desc>
18785	Wildcard for all events.
18786	Events of this type are never delivered, and only used in
18787	<link to="IEventSource::registerListener"/> call to simplify registration.
18788	</desc>
18789	</const>
18790
18791	<const name="Vetoable" value="2">
18792	<desc>
18793	Wildcard for all vetoable events. Events of this type are never delivered, and only
18794	used in <link to="IEventSource::registerListener"/> call to simplify registration.
18795	</desc>
18796	</const>
18797
18798	<const name="MachineEvent" value="3">
18799	<desc>
18800	Wildcard for all machine events. Events of this type are never delivered, and only used in
18801	<link to="IEventSource::registerListener"/> call to simplify registration.
18802	</desc>
18803	</const>
18804
18805	<const name="SnapshotEvent" value="4">
18806	<desc>
18807	Wildcard for all snapshot events. Events of this type are never delivered, and only used in
18808	<link to="IEventSource::registerListener"/> call to simplify registration.
18809	</desc>
18810	</const>
18811
18812	<const name="InputEvent" value="5">
18813	<desc>
18814	Wildcard for all input device (keyboard, mouse) events.
18815	Events of this type are never delivered, and only used in
18816	<link to="IEventSource::registerListener"/> call to simplify registration.
18817	</desc>
18818	</const>
18819
18820	<const name="LastWildcard" value="31">
18821	<desc>
18822	Last wildcard.
18823	</desc>
18824	</const>
18825
18826	<const name="OnMachineStateChanged" value="32">
18827	<desc>
18828	See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
18829	</desc>
18830	</const>
18831	<const name="OnMachineDataChanged" value="33">
18832	<desc>
18833	See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
18834	</desc>
18835	</const>
18836	<const name="OnExtraDataChanged" value="34">
18837	<desc>
18838	See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
18839	</desc>
18840	</const>
18841	<const name="OnExtraDataCanChange" value="35">
18842	<desc>
18843	See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
18844	</desc>
18845	</const>
18846	<const name="OnMediumRegistered" value="36">
18847	<desc>
18848	See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
18849	</desc>
18850	</const>
18851	<const name="OnMachineRegistered" value="37">
18852	<desc>
18853	See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
18854	</desc>
18855	</const>
18856	<const name="OnSessionStateChanged" value="38">
18857	<desc>
18858	See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
18859	</desc>
18860	</const>
18861	<const name="OnSnapshotTaken" value="39">
18862	<desc>
18863	See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
18864	</desc>
18865	</const>
18866	<const name="OnSnapshotDeleted" value="40">
18867	<desc>
18868	See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
18869	</desc>
18870	</const>
18871	<const name="OnSnapshotChanged" value="41">
18872	<desc>
18873	See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
18874	</desc>
18875	</const>
18876	<const name="OnGuestPropertyChanged" value="42">
18877	<desc>
18878	See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
18879	</desc>
18880	</const>
18881	<!-- Console events -->
18882	<const name="OnMousePointerShapeChanged" value="43">
18883	<desc>
18884	See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
18885	</desc>
18886	</const>
18887	<const name="OnMouseCapabilityChanged" value="44">
18888	<desc>
18889	See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
18890	</desc>
18891	</const>
18892	<const name="OnKeyboardLedsChanged" value="45">
18893	<desc>
18894	See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
18895	</desc>
18896	</const>
18897	<const name="OnStateChanged" value="46">
18898	<desc>
18899	See <link to="IStateChangedEvent">IStateChangedEvent</link>.
18900	</desc>
18901	</const>
18902	<const name="OnAdditionsStateChanged" value="47">
18903	<desc>
18904	See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
18905	</desc>
18906	</const>
18907	<const name="OnNetworkAdapterChanged" value="48">
18908	<desc>
18909	See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
18910	</desc>
18911	</const>
18912	<const name="OnSerialPortChanged" value="49">
18913	<desc>
18914	See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
18915	</desc>
18916	</const>
18917	<const name="OnParallelPortChanged" value="50">
18918	<desc>
18919	See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
18920	</desc>
18921	</const>
18922	<const name="OnStorageControllerChanged" value="51">
18923	<desc>
18924	See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
18925	</desc>
18926	</const>
18927	<const name="OnMediumChanged" value="52">
18928	<desc>
18929	See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
18930	</desc>
18931	</const>
18932	<const name="OnVRDEServerChanged" value="53">
18933	<desc>
18934	See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
18935	</desc>
18936	</const>
18937	<const name="OnUSBControllerChanged" value="54">
18938	<desc>
18939	See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
18940	</desc>
18941	</const>
18942	<const name="OnUSBDeviceStateChanged" value="55">
18943	<desc>
18944	See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
18945	</desc>
18946	</const>
18947	<const name="OnSharedFolderChanged" value="56">
18948	<desc>
18949	See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
18950	</desc>
18951	</const>
18952	<const name="OnRuntimeError" value="57">
18953	<desc>
18954	See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
18955	</desc>
18956	</const>
18957	<const name="OnCanShowWindow" value="58">
18958	<desc>
18959	See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
18960	</desc>
18961	</const>
18962	<const name="OnShowWindow" value="59">
18963	<desc>
18964	See <link to="IShowWindowEvent">IShowWindowEvent</link>.
18965	</desc>
18966	</const>
18967	<const name="OnCPUChanged" value="60">
18968	<desc>
18969	See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
18970	</desc>
18971	</const>
18972	<const name="OnVRDEServerInfoChanged" value="61">
18973	<desc>
18974	See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
18975	</desc>
18976	</const>
18977	<const name="OnEventSourceChanged" value="62">
18978	<desc>
18979	See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
18980	</desc>
18981	</const>
18982	<const name="OnCPUExecutionCapChanged" value="63">
18983	<desc>
18984	See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
18985	</desc>
18986	</const>
18987	<const name="OnGuestKeyboard" value="64">
18988	<desc>
18989	See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
18990	</desc>
18991	</const>
18992	<const name="OnGuestMouse" value="65">
18993	<desc>
18994	See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
18995	</desc>
18996	</const>
18997	<const name="OnNATRedirect" value="66">
18998	<desc>
18999	See <link to="INATRedirectEvent">INATRedirectEvent</link>.
19000	</desc>
19001	</const>
19002	<const name="OnHostPCIDevicePlug" value="67">
19003	<desc>
19004	See <link to="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link>.
19005	</desc>
19006	</const>
19007	<const name="OnVBoxSVCAvailabilityChanged" value="68">
19008	<desc>
19009	See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>.
19010	</desc>
19011	</const>
19012	<const name="OnBandwidthGroupChanged" value="69">
19013	<desc>
19014	See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>.
19015	</desc>
19016	</const>
19017	<const name="OnGuestMonitorChanged" value="70">
19018	<desc>
19019	See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>.
19020	</desc>
19021	</const>
19022	<const name="OnStorageDeviceChanged" value="71">
19023	<desc>
19024	See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>.
19025	</desc>
19026	</const>
19027	<const name="OnClipboardModeChanged" value="72">
19028	<desc>
19029	See <link to="IClipboardModeChangedEvent">IClipboardModeChangedEvent</link>.
19030	</desc>
19031	</const>
19032	<const name="OnDragAndDropModeChanged" value="73">
19033	<desc>
19034	See <link to="IDragAndDropModeChangedEvent">IDragAndDropModeChangedEvent</link>.
19035	</desc>
19036	</const>
19037	<const name="OnNATNetworkChanged" value="74">
19038	<desc>
19039	See <link to="INATNetworkChangedEvent">INATNetworkChangedEvent</link>.
19040	</desc>
19041	</const>
19042	<const name="OnNATNetworkStartStop" value="75">
19043	<desc>
19044	See <link to="INATNetworkStartStopEvent">INATNetworkStartStopEvent</link>.
19045	</desc>
19046	</const>
19047	<const name="OnNATNetworkAlter" value="76">
19048	<desc>
19049	See <link to="INATNetworkAlterEvent">INATNetworkAlterEvent</link>.
19050	</desc>
19051	</const>
19052	<const name="OnNATNetworkCreationDeletion" value="77">
19053	<desc>
19054	See <link to="INATNetworkCreationDeletionEvent">INATNetworkCreationDeletionEvent</link>.
19055	</desc>
19056	</const>
19057	<const name="OnNATNetworkSetting" value="78">
19058	<desc>
19059	See <link to="INATNetworkSettingEvent">INATNetworkSettingEvent</link>.
19060	</desc>
19061	</const>
19062	<const name="OnNATNetworkPortForward" value="79">
19063	<desc>
19064	See <link to="INATNetworkPortForwardEvent">INATNetworkPortForwardEvent</link>.
19065	</desc>
19066	</const>
19067	<const name="OnGuestSessionStateChanged" value="80">
19068	<desc>
19069	See <link to="IGuestSessionStateChangedEvent">IGuestSessionStateChangedEvent</link>.
19070	</desc>
19071	</const>
19072	<const name="OnGuestSessionRegistered" value="81">
19073	<desc>
19074	See <link to="IGuestSessionRegisteredEvent">IGuestSessionRegisteredEvent</link>.
19075	</desc>
19076	</const>
19077	<const name="OnGuestProcessRegistered" value="82">
19078	<desc>
19079	See <link to="IGuestProcessRegisteredEvent">IGuestProcessRegisteredEvent</link>.
19080	</desc>
19081	</const>
19082	<const name="OnGuestProcessStateChanged" value="83">
19083	<desc>
19084	See <link to="IGuestProcessStateChangedEvent">IGuestProcessStateChangedEvent</link>.
19085	</desc>
19086	</const>
19087	<const name="OnGuestProcessInputNotify" value="84">
19088	<desc>
19089	See <link to="IGuestProcessInputNotifyEvent">IGuestProcessInputNotifyEvent</link>.
19090	</desc>
19091	</const>
19092	<const name="OnGuestProcessOutput" value="85">
19093	<desc>
19094	See <link to="IGuestProcessOutputEvent">IGuestProcessOutputEvent</link>.
19095	</desc>
19096	</const>
19097	<const name="OnGuestFileRegistered" value="86">
19098	<desc>
19099	See <link to="IGuestFileRegisteredEvent">IGuestFileRegisteredEvent</link>.
19100	</desc>
19101	</const>
19102	<const name="OnGuestFileStateChanged" value="87">
19103	<desc>
19104	See <link to="IGuestFileStateChangedEvent">IGuestFileStateChangedEvent</link>.
19105	</desc>
19106	</const>
19107	<const name="OnGuestFileOffsetChanged" value="88">
19108	<desc>
19109	See <link to="IGuestFileOffsetChangedEvent">IGuestFileOffsetChangedEvent</link>.
19110	</desc>
19111	</const>
19112	<const name="OnGuestFileRead" value="89">
19113	<desc>
19114	See <link to="IGuestFileReadEvent">IGuestFileReadEvent</link>.
19115
19116	<note internal="yes">For performance reasons this is a separate event to
19117	not unnecessarily overflow the event queue.</note>
19118	</desc>
19119	</const>
19120	<const name="OnGuestFileWrite" value="90">
19121	<desc>
19122	See <link to="IGuestFileWriteEvent">IGuestFileWriteEvent</link>.
19123
19124	<note internal="yes">For performance reasons this is a separate event to
19125	not unnecessarily overflow the event queue.</note>
19126	</desc>
19127	</const>
19128	<!-- Last event marker -->
19129	<const name="Last" value="91">
19130	<desc>
19131	Must be last event, used for iterations and structures relying on numerical event values.
19132	</desc>
19133	</const>
19134
19135	</enum>
19136
19137	<interface
19138	name="IEventSource" extends="$unknown"
19139	uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
19140	wsmap="managed"
19141	>
19142	<desc>
19143	Event source. Generally, any object which could generate events can be an event source,
19144	or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
19145	an event source can work with listeners in either active or passive mode. In active mode it is up to
19146	the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
19147	event source keeps track of pending events for each listener and returns available events on demand.
19148
19149	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19150	</desc>
19151
19152	<method name="createListener">
19153	<desc>
19154	Creates a new listener object, useful for passive mode.
19155	</desc>
19156	<param name="listener" type="IEventListener" dir="return"/>
19157	</method>
19158
19159	<method name="createAggregator">
19160	<desc>
19161	Creates an aggregator event source, collecting events from multiple sources.
19162	This way a single listener can listen for events coming from multiple sources,
19163	using a single blocking <link to="#getEvent"/> on the returned aggregator.
19164	</desc>
19165	<param name="subordinates" type="IEventSource" dir="in" safearray="yes">
19166	<desc>
19167	Subordinate event source this one aggregatres.
19168	</desc>
19169	</param>
19170	<param name="result" type="IEventSource" dir="return">
19171	<desc>
19172	Event source aggregating passed sources.
19173	</desc>
19174	</param>
19175	</method>
19176
19177	<method name="registerListener">
19178	<desc>
19179	Register an event listener.
19180
19181	<note>
19182	To avoid system overload, the VirtualBox server process checks if passive event
19183	listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
19184	current implementation, if more than 500 pending events are detected for a passive
19185	event listener, it is forcefully unregistered by the system, and further
19186	<link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
19187	</note>
19188	</desc>
19189	<param name="listener" type="IEventListener" dir="in">
19190	<desc>Listener to register.</desc>
19191	</param>
19192	<param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
19193	<desc>
19194	Event types listener is interested in. One can use wildcards like -
19195	<link to="VBoxEventType_Any"/> to specify wildcards, matching more
19196	than one event.
19197	</desc>
19198	</param>
19199	<param name="active" type="boolean" dir="in">
19200	<desc>
19201	Which mode this listener is operating in.
19202	In active mode, <link to="IEventListener::handleEvent" /> is called directly.
19203	In passive mode, an internal event queue is created for this this IEventListener.
19204	For each event coming in, it is added to queues for all interested registered passive
19205	listeners. It is then up to the external code to call the listener's
19206	<link to="IEventListener::handleEvent" /> method. When done with an event, the
19207	external code must call <link to="#eventProcessed" />.
19208	</desc>
19209	</param>
19210	</method>
19211
19212	<method name="unregisterListener">
19213	<desc>
19214	Unregister an event listener. If listener is passive, and some waitable events are still
19215	in queue they are marked as processed automatically.
19216	</desc>
19217	<param name="listener" type="IEventListener" dir="in">
19218	<desc>Listener to unregister.</desc>
19219	</param>
19220	</method>
19221
19222	<method name="fireEvent">
19223	<desc>
19224	Fire an event for this source.
19225	</desc>
19226	<param name="event" type="IEvent" dir="in">
19227	<desc>Event to deliver.</desc>
19228	</param>
19229	<param name="timeout" type="long" dir="in">
19230	<desc>
19231	Maximum time to wait for event processing (if event is waitable), in ms;
19232	0 = no wait, -1 = indefinite wait.
19233	</desc>
19234	</param>
19235	<param name="result" type="boolean" dir="return">
19236	<desc>true if an event was delivered to all targets, or is non-waitable.</desc>
19237	</param>
19238	</method>
19239
19240	<method name="getEvent">
19241	<desc>
19242	Get events from this peer's event queue (for passive mode). Calling this method
19243	regularly is required for passive event listeners to avoid system overload;
19244	see <link to="IEventSource::registerListener" /> for details.
19245
19246	<result name="VBOX_E_OBJECT_NOT_FOUND">
19247	Listener is not registered, or autounregistered.
19248	</result>
19249	</desc>
19250	<param name="listener" type="IEventListener" dir="in">
19251	<desc>Which listener to get data for.</desc>
19252	</param>
19253	<param name="timeout" type="long" dir="in">
19254	<desc>
19255	Maximum time to wait for events, in ms;
19256	0 = no wait, -1 = indefinite wait.
19257	</desc>
19258	</param>
19259	<param name="event" type="IEvent" dir="return">
19260	<desc>Event retrieved, or null if none available.</desc>
19261	</param>
19262	</method>
19263
19264	<method name="eventProcessed">
19265	<desc>
19266	Must be called for waitable events after a particular listener finished its
19267	event processing. When all listeners of a particular event have called this
19268	method, the system will then call <link to="IEvent::setProcessed" />.
19269	</desc>
19270	<param name="listener" type="IEventListener" dir="in">
19271	<desc>Which listener processed event.</desc>
19272	</param>
19273	<param name="event" type="IEvent" dir="in">
19274	<desc>Which event.</desc>
19275	</param>
19276	</method>
19277
19278	</interface>
19279
19280	<interface
19281	name="IEventListener" extends="$unknown"
19282	uuid="67099191-32e7-4f6c-85ee-422304c71b90"
19283	wsmap="managed"
19284	>
19285	<desc>
19286	Event listener. An event listener can work in either active or passive mode, depending on the way
19287	it was registered.
19288	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19289	</desc>
19290
19291	<method name="handleEvent">
19292	<desc>
19293	Handle event callback for active listeners. It is not called for
19294	passive listeners. After calling <link to="#handleEvent"/> on all active listeners
19295	and having received acknowledgement from all passive listeners via
19296	<link to="IEventSource::eventProcessed"/>, the event is marked as
19297	processed and <link to="IEvent::waitProcessed"/> will return
19298	immediately.
19299	</desc>
19300	<param name="event" type="IEvent" dir="in">
19301	<desc>Event available.</desc>
19302	</param>
19303	</method>
19304
19305	</interface>
19306
19307	<interface
19308	name="IEvent" extends="$unknown"
19309	uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
19310	wsmap="managed"
19311	>
19312	<desc>
19313	Abstract parent interface for VirtualBox events. Actual events will typically implement
19314	a more specific interface which derives from this (see below).
19315
19316	<b>Introduction to VirtualBox events</b>
19317
19318	Generally speaking, an event (represented by this interface) signals that something
19319	happened, while an event listener (see <link to="IEventListener" />) represents an
19320	entity that is interested in certain events. In order for this to work with
19321	unidirectional protocols (i.e. web services), the concepts of passive and active
19322	listener are used.
19323
19324	Event consumers can register themselves as listeners, providing an array of
19325	events they are interested in (see <link to="IEventSource::registerListener" />).
19326	When an event triggers, the listener is notified about the event. The exact
19327	mechanism of the notification depends on whether the listener was registered as
19328	an active or passive listener:
19329
19330	<ul>
19331	<li>An active listener is very similar to a callback: it is a function invoked
19332	by the API. As opposed to the callbacks that were used in the API before
19333	VirtualBox 4.0 however, events are now objects with an interface hierarchy.
19334	</li>
19335
19336	<li>Passive listeners are somewhat trickier to implement, but do not require
19337	a client function to be callable, which is not an option with scripting
19338	languages or web service clients. Internally the <link to="IEventSource" />
19339	implementation maintains an event queue for each passive listener, and
19340	newly arrived events are put in this queue. When the listener calls
19341	<link to="IEventSource::getEvent"/>, first element from its internal event
19342	queue is returned. When the client completes processing of an event,
19343	the <link to="IEventSource::eventProcessed" /> function must be called,
19344	acknowledging that the event was processed. It supports implementing
19345	waitable events. On passive listener unregistration, all events from its
19346	queue are auto-acknowledged.
19347	</li>
19348	</ul>
19349
19350	Waitable events are useful in situations where the event generator wants to track
19351	delivery or a party wants to wait until all listeners have completed the event. A
19352	typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
19353	listeners might veto a certain action, and thus the event producer has to make
19354	sure that all listeners have processed the event and not vetoed before taking
19355	the action.
19356
19357	A given event may have both passive and active listeners at the same time.
19358
19359	<b>Using events</b>
19360
19361	Any VirtualBox object capable of producing externally visible events provides an
19362	@c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
19363	This event source object is notified by VirtualBox once something has happened, so
19364	consumers may register event listeners with this event source. To register a listener,
19365	an object implementing the <link to="IEventListener" /> interface must be provided.
19366	For active listeners, such an object is typically created by the consumer, while for
19367	passive listeners <link to="IEventSource::createListener" /> should be used. Please
19368	note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener.
19369
19370	Once created, the listener must be registered to listen for the desired events
19371	(see <link to="IEventSource::registerListener" />), providing an array of
19372	<link to="VBoxEventType" /> enums. Those elements can either be the individual
19373	event IDs or wildcards matching multiple event IDs.
19374
19375	After registration, the callback's <link to="IEventListener::handleEvent" /> method is
19376	called automatically when the event is triggered, while passive listeners have to call
19377	<link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
19378	an event processing loop.
19379
19380	The IEvent interface is an abstract parent interface for all such VirtualBox events
19381	coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
19382	or the event processing loop is to check the <link to="#type" /> attribute of the event and
19383	then cast to the appropriate specific interface using @c QueryInterface().
19384	</desc>
19385
19386	<attribute name="type" readonly="yes" type="VBoxEventType">
19387	<desc>
19388	Event type.
19389	</desc>
19390	</attribute>
19391
19392	<attribute name="source" readonly="yes" type="IEventSource">
19393	<desc>
19394	Source of this event.
19395	</desc>
19396	</attribute>
19397
19398	<attribute name="waitable" readonly="yes" type="boolean">
19399	<desc>
19400	If we can wait for this event being processed. If false, <link to="#waitProcessed"/> returns immediately,
19401	and <link to="#setProcessed"/> doesn't make sense. Non-waitable events are generally better performing,
19402	as no additional overhead associated with waitability imposed.
19403	Waitable events are needed when one need to be able to wait for particular event processed,
19404	for example for vetoable changes, or if event refers to some resource which need to be kept immutable
19405	until all consumers confirmed events.
19406	</desc>
19407	</attribute>
19408
19409	<method name="setProcessed">
19410	<desc>
19411	Internal method called by the system when all listeners of a particular event have called
19412	<link to="IEventSource::eventProcessed" />. This should not be called by client code.
19413	</desc>
19414	</method>
19415
19416	<method name="waitProcessed">
19417	<desc>
19418	Wait until time outs, or this event is processed. Event must be waitable for this operation to have
19419	described semantics, for non-waitable returns true immediately.
19420	</desc>
19421	<param name="timeout" type="long" dir="in">
19422	<desc>
19423	Maximum time to wait for event processeing, in ms;
19424	0 = no wait, -1 = indefinite wait.
19425	</desc>
19426	</param>
19427	<param name="result" type="boolean" dir="return">
19428	<desc>If this event was processed before timeout.</desc>
19429	</param>
19430	</method>
19431	</interface>
19432
19433
19434	<interface
19435	name="IReusableEvent" extends="IEvent"
19436	uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
19437	wsmap="managed"
19438	>
19439	<desc>Base abstract interface for all reusable events.</desc>
19440
19441	<attribute name="generation" readonly="yes" type="unsigned long">
19442	<desc>Current generation of event, incremented on reuse.</desc>
19443	</attribute>
19444
19445	<method name="reuse">
19446	<desc>
19447	Marks an event as reused, increments 'generation', fields shall no
19448	longer be considered valid.
19449	</desc>
19450	</method>
19451	</interface>
19452
19453	<interface
19454	name="IMachineEvent" extends="IEvent"
19455	uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
19456	wsmap="managed" id="MachineEvent"
19457	>
19458	<desc>Base abstract interface for all machine events.</desc>
19459
19460	<attribute name="machineId" readonly="yes" type="uuid" mod="string">
19461	<desc>ID of the machine this event relates to.</desc>
19462	</attribute>
19463
19464	</interface>
19465
19466	<interface
19467	name="IMachineStateChangedEvent" extends="IMachineEvent"
19468	uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
19469	wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
19470	>
19471	<desc>Machine state change event.</desc>
19472
19473	<attribute name="state" readonly="yes" type="MachineState">
19474	<desc>New execution state.</desc>
19475	</attribute>
19476	</interface>
19477
19478	<interface
19479	name="IMachineDataChangedEvent" extends="IMachineEvent"
19480	uuid="abe94809-2e88-4436-83d7-50f3e64d0503"
19481	wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
19482	>
19483	<desc>
19484	Any of the settings of the given machine has changed.
19485	</desc>
19486
19487	<attribute name="temporary" readonly="yes" type="boolean">
19488	<desc>@c true if the settings change is temporary. All permanent
19489	settings changes will trigger an event, and only temporary settings
19490	changes for running VMs will trigger an event. Note: sending events
19491	for temporary changes is NOT IMPLEMENTED.</desc>
19492	</attribute>
19493	</interface>
19494
19495	<interface
19496	name="IMediumRegisteredEvent" extends="IEvent"
19497	uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
19498	wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
19499	>
19500	<desc>
19501	The given medium was registered or unregistered
19502	within this VirtualBox installation.
19503	</desc>
19504
19505	<attribute name="mediumId" readonly="yes" type="uuid" mod="string">
19506	<desc>ID of the medium this event relates to.</desc>
19507	</attribute>
19508
19509	<attribute name="mediumType" readonly="yes" type="DeviceType">
19510	<desc>Type of the medium this event relates to.</desc>
19511	</attribute>
19512
19513	<attribute name="registered" type="boolean" readonly="yes">
19514	<desc>
19515	If @c true, the medium was registered, otherwise it was
19516	unregistered.
19517	</desc>
19518	</attribute>
19519	</interface>
19520
19521	<interface
19522	name="IMachineRegisteredEvent" extends="IMachineEvent"
19523	uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
19524	wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
19525	>
19526	<desc>
19527	The given machine was registered or unregistered
19528	within this VirtualBox installation.
19529	</desc>
19530
19531	<attribute name="registered" type="boolean" readonly="yes">
19532	<desc>
19533	If @c true, the machine was registered, otherwise it was
19534	unregistered.
19535	</desc>
19536	</attribute>
19537	</interface>
19538
19539	<interface
19540	name="ISessionStateChangedEvent" extends="IMachineEvent"
19541	uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
19542	wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
19543	>
19544	<desc>
19545	The state of the session for the given machine was changed.
19546	<see><link to="IMachine::sessionState"/></see>
19547	</desc>
19548
19549	<attribute name="state" type="SessionState" readonly="yes">
19550	<desc>
19551	New session state.
19552	</desc>
19553	</attribute>
19554	</interface>
19555
19556	<interface
19557	name="IGuestPropertyChangedEvent" extends="IMachineEvent"
19558	uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
19559	wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
19560	>
19561	<desc>
19562	Notification when a guest property has changed.
19563	</desc>
19564
19565	<attribute name="name" readonly="yes" type="wstring">
19566	<desc>
19567	The name of the property that has changed.
19568	</desc>
19569	</attribute>
19570
19571	<attribute name="value" readonly="yes" type="wstring">
19572	<desc>
19573	The new property value.
19574	</desc>
19575	</attribute>
19576
19577	<attribute name="flags" readonly="yes" type="wstring">
19578	<desc>
19579	The new property flags.
19580	</desc>
19581	</attribute>
19582
19583	</interface>
19584
19585	<interface
19586	name="ISnapshotEvent" extends="IMachineEvent"
19587	uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
19588	wsmap="managed" id="SnapshotEvent"
19589	>
19590	<desc>Base interface for all snapshot events.</desc>
19591
19592	<attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
19593	<desc>ID of the snapshot this event relates to.</desc>
19594	</attribute>
19595
19596	</interface>
19597
19598	<interface
19599	name="ISnapshotTakenEvent" extends="ISnapshotEvent"
19600	uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
19601	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
19602	>
19603	<desc>
19604	A new snapshot of the machine has been taken.
19605	<see><link to="ISnapshot"/></see>
19606	</desc>
19607	</interface>
19608
19609	<interface
19610	name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
19611	uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
19612	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
19613	>
19614	<desc>
19615	Snapshot of the given machine has been deleted.
19616
19617	<note>
19618	This notification is delivered <b>after</b> the snapshot
19619	object has been uninitialized on the server (so that any
19620	attempt to call its methods will return an error).
19621	</note>
19622
19623	<see><link to="ISnapshot"/></see>
19624	</desc>
19625	</interface>
19626
19627	<interface
19628	name="ISnapshotChangedEvent" extends="ISnapshotEvent"
19629	uuid="07541941-8079-447a-a33e-47a69c7980db"
19630	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
19631	>
19632	<desc>
19633	Snapshot properties (name and/or description) have been changed.
19634	<see><link to="ISnapshot"/></see>
19635	</desc>
19636	</interface>
19637
19638	<interface
19639	name="IMousePointerShapeChangedEvent" extends="IEvent"
19640	uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
19641	wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
19642	>
19643	<desc>
19644	Notification when the guest mouse pointer shape has
19645	changed. The new shape data is given.
19646	</desc>
19647
19648	<attribute name="visible" type="boolean" readonly="yes">
19649	<desc>
19650	Flag whether the pointer is visible.
19651	</desc>
19652	</attribute>
19653	<attribute name="alpha" type="boolean" readonly="yes">
19654	<desc>
19655	Flag whether the pointer has an alpha channel.
19656	</desc>
19657	</attribute>
19658	<attribute name="xhot" type="unsigned long" readonly="yes">
19659	<desc>
19660	The pointer hot spot X coordinate.
19661	</desc>
19662	</attribute>
19663	<attribute name="yhot" type="unsigned long" readonly="yes">
19664	<desc>
19665	The pointer hot spot Y coordinate.
19666	</desc>
19667	</attribute>
19668	<attribute name="width" type="unsigned long" readonly="yes">
19669	<desc>
19670	Width of the pointer shape in pixels.
19671	</desc>
19672	</attribute>
19673	<attribute name="height" type="unsigned long" readonly="yes">
19674	<desc>
19675	Height of the pointer shape in pixels.
19676	</desc>
19677	</attribute>
19678	<attribute name="shape" type="octet" safearray="yes" readonly="yes">
19679	<desc>
19680	Shape buffer arrays.
19681
19682	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
19683	followed by a 32-bpp XOR (color) mask.
19684
19685	For pointers without alpha channel the XOR mask pixels are
19686	32-bit values: (lsb)BGR0(msb). For pointers with alpha channel
19687	the XOR mask consists of (lsb)BGRA(msb) 32-bit values.
19688
19689	An AND mask is used for pointers with alpha channel, so if the
19690	callback does not support alpha, the pointer could be
19691	displayed as a normal color pointer.
19692
19693	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
19694	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
19695	height</tt>. The padding bits at the end of each scanline are
19696	undefined.
19697
19698	The XOR mask follows the AND mask on the next 4-byte aligned
19699	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
19700	Bytes in the gap between the AND and the XOR mask are undefined.
19701	The XOR mask scanlines have no gap between them and the size of
19702	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
19703
19704	<note>
19705	If @a shape is 0, only the pointer visibility is changed.
19706	</note>
19707	</desc>
19708	</attribute>
19709	</interface>
19710
19711	<interface
19712	name="IMouseCapabilityChangedEvent" extends="IEvent"
19713	uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
19714	wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
19715	>
19716	<desc>
19717	Notification when the mouse capabilities reported by the
19718	guest have changed. The new capabilities are passed.
19719	</desc>
19720	<attribute name="supportsAbsolute" type="boolean" readonly="yes">
19721	<desc>
19722	Supports absolute coordinates.
19723	</desc>
19724	</attribute>
19725	<attribute name="supportsRelative" type="boolean" readonly="yes">
19726	<desc>
19727	Supports relative coordinates.
19728	</desc>
19729	</attribute>
19730	<attribute name="needsHostCursor" type="boolean" readonly="yes">
19731	<desc>
19732	If host cursor is needed.
19733	</desc>
19734	</attribute>
19735	</interface>
19736
19737	<interface
19738	name="IKeyboardLedsChangedEvent" extends="IEvent"
19739	uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
19740	wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
19741	>
19742	<desc>
19743	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
19744	to alter the state of the keyboard LEDs.
19745	</desc>
19746	<attribute name="numLock" type="boolean" readonly="yes">
19747	<desc>
19748	NumLock status.
19749	</desc>
19750	</attribute>
19751	<attribute name="capsLock" type="boolean" readonly="yes">
19752	<desc>
19753	CapsLock status.
19754	</desc>
19755	</attribute>
19756	<attribute name="scrollLock" type="boolean" readonly="yes">
19757	<desc>
19758	ScrollLock status.
19759	</desc>
19760	</attribute>
19761	</interface>
19762
19763	<interface
19764	name="IStateChangedEvent" extends="IEvent"
19765	uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
19766	wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
19767	>
19768	<desc>
19769	Notification when the execution state of the machine has changed.
19770	The new state is given.
19771	</desc>
19772	<attribute name="state" type="MachineState" readonly="yes">
19773	<desc>
19774	New machine state.
19775	</desc>
19776	</attribute>
19777	</interface>
19778
19779	<interface
19780	name="IAdditionsStateChangedEvent" extends="IEvent"
19781	uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
19782	wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
19783	>
19784	<desc>
19785	Notification when a Guest Additions property changes.
19786	Interested callees should query IGuest attributes to
19787	find out what has changed.
19788	</desc>
19789	</interface>
19790
19791	<interface
19792	name="INetworkAdapterChangedEvent" extends="IEvent"
19793	uuid="08889892-1EC6-4883-801D-77F56CFD0103"
19794	wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
19795	>
19796	<desc>
19797	Notification when a property of one of the
19798	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
19799	changes. Interested callees should use INetworkAdapter methods and
19800	attributes to find out what has changed.
19801	</desc>
19802	<attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
19803	<desc>
19804	Network adapter that is subject to change.
19805	</desc>
19806	</attribute>
19807	</interface>
19808
19809	<interface
19810	name="ISerialPortChangedEvent" extends="IEvent"
19811	uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
19812	wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
19813	>
19814	<desc>
19815	Notification when a property of one of the
19816	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
19817	Interested callees should use ISerialPort methods and attributes
19818	to find out what has changed.
19819	</desc>
19820	<attribute name="serialPort" type="ISerialPort" readonly="yes">
19821	<desc>
19822	Serial port that is subject to change.
19823	</desc>
19824	</attribute>
19825	</interface>
19826
19827	<interface
19828	name="IParallelPortChangedEvent" extends="IEvent"
19829	uuid="813C99FC-9849-4F47-813E-24A75DC85615"
19830	wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
19831	>
19832	<desc>
19833	Notification when a property of one of the
19834	virtual <link to="IMachine::getParallelPort">parallel ports</link>
19835	changes. Interested callees should use ISerialPort methods and
19836	attributes to find out what has changed.
19837	</desc>
19838	<attribute name="parallelPort" type="IParallelPort" readonly="yes">
19839	<desc>
19840	Parallel port that is subject to change.
19841	</desc>
19842	</attribute>
19843	</interface>
19844
19845	<interface
19846	name="IStorageControllerChangedEvent" extends="IEvent"
19847	uuid="715212BF-DA59-426E-8230-3831FAA52C56"
19848	wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
19849	>
19850	<desc>
19851	Notification when a
19852	<link to="IMachine::mediumAttachments">medium attachment</link>
19853	changes.
19854	</desc>
19855	</interface>
19856
19857	<interface
19858	name="IMediumChangedEvent" extends="IEvent"
19859	uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
19860	wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
19861	>
19862	<desc>
19863	Notification when a
19864	<link to="IMachine::mediumAttachments">medium attachment</link>
19865	changes.
19866	</desc>
19867	<attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
19868	<desc>
19869	Medium attachment that is subject to change.
19870	</desc>
19871	</attribute>
19872	</interface>
19873
19874	<interface
19875	name="IClipboardModeChangedEvent" extends="IEvent"
19876	uuid="cac21692-7997-4595-a731-3a509db604e5"
19877	wsmap="managed" autogen="VBoxEvent" id="OnClipboardModeChanged"
19878	>
19879	<desc>
19880	Notification when the shared clipboard mode changes.
19881	</desc>
19882	<attribute name="clipboardMode" type="ClipboardMode" readonly="yes">
19883	<desc>
19884	The new clipboard mode.
19885	</desc>
19886	</attribute>
19887	</interface>
19888
19889	<interface
19890	name="IDragAndDropModeChangedEvent" extends="IEvent"
19891	uuid="e90b8850-ac8e-4dff-8059-4100ae2c3c3d"
19892	wsmap="managed" autogen="VBoxEvent" id="OnDragAndDropModeChanged"
19893	>
19894	<desc>
19895	Notification when the drag'n'drop mode changes.
19896	</desc>
19897	<attribute name="dragAndDropMode" type="DragAndDropMode" readonly="yes">
19898	<desc>
19899	The new drag'n'drop mode.
19900	</desc>
19901	</attribute>
19902	</interface>
19903
19904	<interface
19905	name="ICPUChangedEvent" extends="IEvent"
19906	uuid="4da2dec7-71b2-4817-9a64-4ed12c17388e"
19907	wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
19908	>
19909	<desc>
19910	Notification when a CPU changes.
19911	</desc>
19912	<attribute name="CPU" type="unsigned long" readonly="yes">
19913	<desc>
19914	The CPU which changed.
19915	</desc>
19916	</attribute>
19917	<attribute name="add" type="boolean" readonly="yes">
19918	<desc>
19919	Flag whether the CPU was added or removed.
19920	</desc>
19921	</attribute>
19922	</interface>
19923
19924	<interface
19925	name="ICPUExecutionCapChangedEvent" extends="IEvent"
19926	uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
19927	wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
19928	>
19929	<desc>
19930	Notification when the CPU execution cap changes.
19931	</desc>
19932	<attribute name="executionCap" type="unsigned long" readonly="yes">
19933	<desc>
19934	The new CPU execution cap value. (1-100)
19935	</desc>
19936	</attribute>
19937	</interface>
19938
19939	<interface
19940	name="IGuestKeyboardEvent" extends="IEvent"
19941	uuid="88394258-7006-40d4-b339-472ee3801844"
19942	wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard"
19943	>
19944	<desc>
19945	Notification when guest keyboard event happens.
19946	</desc>
19947	<attribute name="scancodes" type="long" safearray="yes" readonly="yes">
19948	<desc>
19949	Array of scancodes.
19950	</desc>
19951	</attribute>
19952	</interface>
19953
19954	<interface
19955	name="IGuestMouseEvent" extends="IReusableEvent"
19956	uuid="1f85d35c-c524-40ff-8e98-307000df0992"
19957	wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse"
19958	>
19959	<desc>
19960	Notification when guest mouse event happens.
19961	</desc>
19962
19963	<attribute name="absolute" type="boolean" readonly="yes">
19964	<desc>
19965	If this event is relative or absolute.
19966	</desc>
19967	</attribute>
19968
19969	<attribute name="x" type="long" readonly="yes">
19970	<desc>
19971	New X position, or X delta.
19972	</desc>
19973	</attribute>
19974
19975	<attribute name="y" type="long" readonly="yes">
19976	<desc>
19977	New Y position, or Y delta.
19978	</desc>
19979	</attribute>
19980
19981	<attribute name="z" type="long" readonly="yes">
19982	<desc>
19983	Z delta.
19984	</desc>
19985	</attribute>
19986
19987	<attribute name="w" type="long" readonly="yes">
19988	<desc>
19989	W delta.
19990	</desc>
19991	</attribute>
19992
19993	<attribute name="buttons" type="long" readonly="yes">
19994	<desc>
19995	Button state bitmask.
19996	</desc>
19997	</attribute>
19998
19999	</interface>
20000
20001	<interface
20002	name="IGuestSessionEvent" extends="IEvent"
20003	uuid="b9acd33f-647d-45ac-8fe9-f49b3183ba37"
20004	wsmap="managed"
20005	>
20006	<desc>Base abstract interface for all guest session events.</desc>
20007
20008	<attribute name="session" type="IGuestSession" readonly="yes">
20009	<desc>Guest session that is subject to change.</desc>
20010	</attribute>
20011
20012	</interface>
20013
20014	<interface
20015	name="IGuestSessionStateChangedEvent" extends="IGuestSessionEvent"
20016	uuid="327e3c00-ee61-462f-aed3-0dff6cbf9904"
20017	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionStateChanged"
20018	>
20019	<desc>
20020	Notification when a guest session changed its state.
20021	</desc>
20022
20023	<attribute name="id" type="unsigned long" readonly="yes">
20024	<desc>
20025	Session ID of guest session which was changed.
20026	</desc>
20027	</attribute>
20028	<attribute name="status" type="GuestSessionStatus" readonly="yes">
20029	<desc>
20030	New session status.
20031	</desc>
20032	</attribute>
20033	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20034	<desc>
20035	Error information in case of new session status is indicating an error.
20036
20037	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20038	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20039	include/VBox/err.h for details.
20040	</desc>
20041	</attribute>
20042
20043	</interface>
20044
20045	<interface
20046	name="IGuestSessionRegisteredEvent" extends="IGuestSessionEvent"
20047	uuid="b79de686-eabd-4fa6-960a-f1756c99ea1c"
20048	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionRegistered"
20049	>
20050	<desc>
20051	Notification when a guest session was registered or unregistered.
20052	</desc>
20053
20054	<attribute name="registered" type="boolean" readonly="yes">
20055	<desc>
20056	If @c true, the guest session was registered, otherwise it was
20057	unregistered.
20058	</desc>
20059	</attribute>
20060
20061	</interface>
20062
20063	<interface
20064	name="IGuestProcessEvent" extends="IGuestSessionEvent"
20065	uuid="2405f0e5-6588-40a3-9b0a-68c05ba52c4b"
20066	wsmap="managed"
20067	>
20068	<desc>Base abstract interface for all guest process events.</desc>
20069
20070	<attribute name="process" type="IGuestProcess" readonly="yes">
20071	<desc>
20072	Guest process object which is related to this event.
20073	</desc>
20074	</attribute>
20075	<attribute name="pid" type="unsigned long" readonly="yes">
20076	<desc>
20077	Guest process ID (PID).
20078	</desc>
20079	</attribute>
20080
20081	</interface>
20082
20083	<interface
20084	name="IGuestProcessRegisteredEvent" extends="IGuestProcessEvent"
20085	uuid="1d89e2b3-c6ea-45b6-9d43-dc6f70cc9f02"
20086	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessRegistered"
20087	>
20088	<desc>
20089	Notification when a guest process was registered or unregistered.
20090	</desc>
20091
20092	<attribute name="registered" type="boolean" readonly="yes">
20093	<desc>
20094	If @c true, the guest process was registered, otherwise it was
20095	unregistered.
20096	</desc>
20097	</attribute>
20098
20099	</interface>
20100
20101	<interface
20102	name="IGuestProcessStateChangedEvent" extends="IGuestProcessEvent"
20103	uuid="c365fb7b-4430-499f-92c8-8bed814a567a"
20104	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessStateChanged"
20105	>
20106	<desc>
20107	Notification when a guest process changed its state.
20108	</desc>
20109
20110	<attribute name="status" type="ProcessStatus" readonly="yes">
20111	<desc>
20112	New guest process status.
20113	</desc>
20114	</attribute>
20115	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20116	<desc>
20117	Error information in case of new session status is indicating an error.
20118
20119	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20120	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20121	include/VBox/err.h for details.
20122	</desc>
20123	</attribute>
20124
20125	</interface>
20126
20127	<interface
20128	name="IGuestProcessIOEvent" extends="IGuestProcessEvent"
20129	uuid="9ea9227c-e9bb-49b3-bfc7-c5171e93ef38"
20130	wsmap="managed"
20131	>
20132	<desc>
20133	Base abstract interface for all guest process input/output (IO) events.
20134	</desc>
20135
20136	<attribute name="handle" type="unsigned long" readonly="yes">
20137	<desc>
20138	Input/output (IO) handle involved in this event. Usually 0 is stdin,
20139	1 is stdout and 2 is stderr.
20140	</desc>
20141	</attribute>
20142
20143	<attribute name="processed" type="unsigned long" readonly="yes">
20144	<desc>
20145	Processed input or output (in bytes).
20146	</desc>
20147	</attribute>
20148
20149	</interface>
20150
20151	<interface
20152	name="IGuestProcessInputNotifyEvent" extends="IGuestProcessIOEvent"
20153	uuid="0de887f2-b7db-4616-aac6-cfb94d89ba78"
20154	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessInputNotify"
20155	>
20156	<desc>
20157	Notification when a guest process' stdin became available.
20158	<note>This event is right now not implemented!</note>
20159	</desc>
20160
20161	<attribute name="status" type="ProcessInputStatus" readonly="yes">
20162	<desc>
20163	Current process input status.
20164	</desc>
20165	</attribute>
20166
20167	</interface>
20168
20169	<interface
20170	name="IGuestProcessOutputEvent" extends="IGuestProcessIOEvent"
20171	uuid="d3d5f1ee-bcb2-4905-a7ab-cc85448a742b"
20172	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessOutput"
20173	>
20174	<desc>
20175	Notification when there is guest process output available for reading.
20176	</desc>
20177
20178	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20179	<desc>
20180	Actual output data.
20181	</desc>
20182	</attribute>
20183
20184	</interface>
20185
20186	<interface
20187	name="IGuestFileEvent" extends="IGuestSessionEvent"
20188	uuid="c8adb7b0-057d-4391-b928-f14b06b710c5"
20189	wsmap="managed"
20190	>
20191	<desc>Base abstract interface for all guest file events.</desc>
20192
20193	<attribute name="file" type="IGuestFile" readonly="yes">
20194	<desc>
20195	Guest file object which is related to this event.
20196	</desc>
20197	</attribute>
20198
20199	</interface>
20200
20201	<interface
20202	name="IGuestFileRegisteredEvent" extends="IGuestFileEvent"
20203	uuid="d0d93830-70a2-487e-895e-d3fc9679f7b3"
20204	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRegistered"
20205	>
20206	<desc>
20207	Notification when a guest file was registered or unregistered.
20208	</desc>
20209
20210	<attribute name="registered" type="boolean" readonly="yes">
20211	<desc>
20212	If @c true, the guest file was registered, otherwise it was
20213	unregistered.
20214	</desc>
20215	</attribute>
20216
20217	</interface>
20218
20219	<interface
20220	name="IGuestFileStateChangedEvent" extends="IGuestFileEvent"
20221	uuid="d37fe88f-0979-486c-baa1-3abb144dc82d"
20222	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileStateChanged"
20223	>
20224	<desc>
20225	Notification when a guest file changed its state.
20226	</desc>
20227
20228	<attribute name="status" type="FileStatus" readonly="yes">
20229	<desc>
20230	New guest file status.
20231	</desc>
20232	</attribute>
20233	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20234	<desc>
20235	Error information in case of new session status is indicating an error.
20236
20237	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20238	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20239	include/VBox/err.h for details.
20240	</desc>
20241	</attribute>
20242	<!-- Note: No events for reads/writes for performance reasons.
20243	See dedidcated events IGuestFileReadEvent and
20244	IGuestFileWriteEvent. -->
20245
20246	</interface>
20247
20248	<interface
20249	name="IGuestFileIOEvent" extends="IGuestFileEvent"
20250	uuid="b5191a7c-9536-4ef8-820e-3b0e17e5bbc8"
20251	wsmap="managed"
20252	>
20253	<desc>
20254	Base abstract interface for all guest file input/output (IO) events.
20255	</desc>
20256
20257	<attribute name="offset" type="long long" readonly="yes">
20258	<desc>
20259	Current offset (in bytes).
20260	</desc>
20261	</attribute>
20262	<attribute name="processed" type="unsigned long" readonly="yes">
20263	<desc>
20264	Processed input or output (in bytes).
20265	</desc>
20266	</attribute>
20267
20268	</interface>
20269
20270	<interface
20271	name="IGuestFileOffsetChangedEvent" extends="IGuestFileIOEvent"
20272	uuid="e8f79a21-1207-4179-94cf-ca250036308f"
20273	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileOffsetChanged"
20274	>
20275	<desc>
20276	Notification when a guest file changed its current offset.
20277	</desc>
20278
20279	</interface>
20280
20281	<interface
20282	name="IGuestFileReadEvent" extends="IGuestFileIOEvent"
20283	uuid="4ee3cbcb-486f-40db-9150-deee3fd24189"
20284	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRead"
20285	>
20286	<desc>
20287	Notification when data has been read from a guest file.
20288	</desc>
20289
20290	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20291	<desc>
20292	Actual data read.
20293	</desc>
20294	</attribute>
20295
20296	</interface>
20297
20298	<interface
20299	name="IGuestFileWriteEvent" extends="IGuestFileIOEvent"
20300	uuid="e062a915-3cf5-4c0a-bc90-9b8d4cc94d89"
20301	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileWrite"
20302	>
20303	<desc>
20304	Notification when data has been written to a guest file.
20305	</desc>
20306
20307	</interface>
20308
20309	<interface
20310	name="IVRDEServerChangedEvent" extends="IEvent"
20311	uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
20312	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
20313	>
20314	<desc>
20315	Notification when a property of the
20316	<link to="IMachine::VRDEServer">VRDE server</link> changes.
20317	Interested callees should use IVRDEServer methods and attributes to
20318	find out what has changed.
20319	</desc>
20320	</interface>
20321
20322	<interface
20323	name="IVRDEServerInfoChangedEvent" extends="IEvent"
20324	uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
20325	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
20326	>
20327	<desc>
20328	Notification when the status of the VRDE server changes. Interested callees
20329	should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
20330	attributes to find out what is the current status.
20331	</desc>
20332	</interface>
20333
20334	<interface
20335	name="IUSBControllerChangedEvent" extends="IEvent"
20336	uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
20337	wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
20338	>
20339	<desc>
20340	Notification when a property of the virtual
20341	<link to="IMachine::USBController">USB controller</link> changes.
20342	Interested callees should use IUSBController methods and attributes to
20343	find out what has changed.
20344	</desc>
20345	</interface>
20346
20347	<interface
20348	name="IUSBDeviceStateChangedEvent" extends="IEvent"
20349	uuid="806da61b-6679-422a-b629-51b06b0c6d93"
20350	wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
20351	>
20352	<desc>
20353	Notification when a USB device is attached to or detached from
20354	the virtual USB controller.
20355
20356	This notification is sent as a result of the indirect
20357	request to attach the device because it matches one of the
20358	machine USB filters, or as a result of the direct request
20359	issued by <link to="IConsole::attachUSBDevice"/> or
20360	<link to="IConsole::detachUSBDevice"/>.
20361
20362	This notification is sent in case of both a succeeded and a
20363	failed request completion. When the request succeeds, the
20364	@a error parameter is @c null, and the given device has been
20365	already added to (when @a attached is @c true) or removed from
20366	(when @a attached is @c false) the collection represented by
20367	<link to="IConsole::USBDevices"/>. On failure, the collection
20368	doesn't change and the @a error parameter represents the error
20369	message describing the failure.
20370	</desc>
20371	<attribute name="device" type="IUSBDevice" readonly="yes">
20372	<desc>
20373	Device that is subject to state change.
20374	</desc>
20375	</attribute>
20376	<attribute name="attached" type="boolean" readonly="yes">
20377	<desc>
20378	@c true if the device was attached and @c false otherwise.
20379	</desc>
20380	</attribute>
20381	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20382	<desc>
20383	@c null on success or an error message object on failure.
20384	</desc>
20385	</attribute>
20386	</interface>
20387
20388	<interface
20389	name="ISharedFolderChangedEvent" extends="IEvent"
20390	uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
20391	wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
20392	>
20393	<desc>
20394	Notification when a shared folder is added or removed.
20395	The @a scope argument defines one of three scopes:
20396	<link to="IVirtualBox::sharedFolders">global shared folders</link>
20397	(<link to="Scope_Global">Global</link>),
20398	<link to="IMachine::sharedFolders">permanent shared folders</link> of
20399	the machine (<link to="Scope_Machine">Machine</link>) or <link
20400	to="IConsole::sharedFolders">transient shared folders</link> of the
20401	machine (<link to="Scope_Session">Session</link>). Interested callees
20402	should use query the corresponding collections to find out what has
20403	changed.
20404	</desc>
20405	<attribute name="scope" type="Scope" readonly="yes">
20406	<desc>
20407	Scope of the notification.
20408	</desc>
20409	</attribute>
20410	</interface>
20411
20412	<interface
20413	name="IRuntimeErrorEvent" extends="IEvent"
20414	uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
20415	wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
20416	>
20417	<desc>
20418	Notification when an error happens during the virtual
20419	machine execution.
20420
20421	There are three kinds of runtime errors:
20422	<ul>
20423	<li><i>fatal</i></li>
20424	<li><i>non-fatal with retry</i></li>
20425	<li><i>non-fatal warnings</i></li>
20426	</ul>
20427
20428	<b>Fatal</b> errors are indicated by the @a fatal parameter set
20429	to @c true. In case of fatal errors, the virtual machine
20430	execution is always paused before calling this notification, and
20431	the notification handler is supposed either to immediately save
20432	the virtual machine state using <link to="IConsole::saveState"/>
20433	or power it off using <link to="IConsole::powerDown"/>.
20434	Resuming the execution can lead to unpredictable results.
20435
20436	<b>Non-fatal</b> errors and warnings are indicated by the
20437	@a fatal parameter set to @c false. If the virtual machine
20438	is in the Paused state by the time the error notification is
20439	received, it means that the user can <i>try to resume</i> the machine
20440	execution after attempting to solve the problem that caused the
20441	error. In this case, the notification handler is supposed
20442	to show an appropriate message to the user (depending on the
20443	value of the @a id parameter) that offers several actions such
20444	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
20445	wants to retry, the notification handler should continue
20446	the machine execution using the <link to="IConsole::resume"/>
20447	call. If the machine execution is not Paused during this
20448	notification, then it means this notification is a <i>warning</i>
20449	(for example, about a fatal condition that can happen very soon);
20450	no immediate action is required from the user, the machine
20451	continues its normal execution.
20452
20453	Note that in either case the notification handler
20454	<b>must not</b> perform any action directly on a thread
20455	where this notification is called. Everything it is allowed to
20456	do is to post a message to another thread that will then talk
20457	to the user and take the corresponding action.
20458
20459	Currently, the following error identifiers are known:
20460	<ul>
20461	<li><tt>"HostMemoryLow"</tt></li>
20462	<li><tt>"HostAudioNotResponding"</tt></li>
20463	<li><tt>"VDIStorageFull"</tt></li>
20464	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
20465	</ul>
20466	</desc>
20467	<attribute name="fatal" type="boolean" readonly="yes">
20468	<desc>
20469	Whether the error is fatal or not.
20470	</desc>
20471	</attribute>
20472	<attribute name="id" type="wstring" readonly="yes">
20473	<desc>
20474	Error identifier.
20475	</desc>
20476	</attribute>
20477	<attribute name="message" type="wstring" readonly="yes">
20478	<desc>
20479	Optional error message.
20480	</desc>
20481	</attribute>
20482	</interface>
20483
20484
20485	<interface
20486	name="IEventSourceChangedEvent" extends="IEvent"
20487	uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
20488	waitable="yes"
20489	wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
20490	>
20491	<desc>
20492	Notification when an event source state changes (listener added or removed).
20493	</desc>
20494
20495	<attribute name="listener" type="IEventListener" readonly="yes">
20496	<desc>
20497	Event listener which has changed.
20498	</desc>
20499	</attribute>
20500
20501	<attribute name="add" type="boolean" readonly="yes">
20502	<desc>
20503	Flag whether listener was added or removed.
20504	</desc>
20505	</attribute>
20506	</interface>
20507
20508	<interface
20509	name="IExtraDataChangedEvent" extends="IEvent"
20510	uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
20511	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
20512	>
20513	<desc>
20514	Notification when machine specific or global extra data
20515	has changed.
20516	</desc>
20517	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20518	<desc>
20519	ID of the machine this event relates to.
20520	Null for global extra data changes.
20521	</desc>
20522	</attribute>
20523	<attribute name="key" type="wstring" readonly="yes">
20524	<desc>
20525	Extra data key that has changed.
20526	</desc>
20527	</attribute>
20528	<attribute name="value" type="wstring" readonly="yes">
20529	<desc>
20530	Extra data value for the given key.
20531	</desc>
20532	</attribute>
20533	</interface>
20534
20535	<interface
20536	name="IVetoEvent" extends="IEvent"
20537	uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
20538	wsmap="managed"
20539	>
20540	<desc>Base abstract interface for veto events.</desc>
20541
20542	<method name="addVeto">
20543	<desc>
20544	Adds a veto on this event.
20545	</desc>
20546	<param name="reason" type="wstring" dir="in">
20547	<desc>
20548	Reason for veto, could be null or empty string.
20549	</desc>
20550	</param>
20551	</method>
20552
20553	<method name="isVetoed">
20554	<desc>
20555	If this event was vetoed.
20556	</desc>
20557	<param name="result" type="boolean" dir="return">
20558	<desc>
20559	Reason for veto.
20560	</desc>
20561	</param>
20562	</method>
20563
20564	<method name="getVetos">
20565	<desc>
20566	Current veto reason list, if size is 0 - no veto.
20567	</desc>
20568	<param name="result" type="wstring" dir="return" safearray="yes">
20569	<desc>
20570	Array of reasons for veto provided by different event handlers.
20571	</desc>
20572	</param>
20573	</method>
20574
20575	</interface>
20576
20577	<interface
20578	name="IExtraDataCanChangeEvent" extends="IVetoEvent"
20579	uuid="245d88bd-800a-40f8-87a6-170d02249a55"
20580	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
20581	waitable="true"
20582	>
20583	<desc>
20584	Notification when someone tries to change extra data for
20585	either the given machine or (if @c null) global extra data.
20586	This gives the chance to veto against changes.
20587	</desc>
20588	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20589	<desc>
20590	ID of the machine this event relates to.
20591	Null for global extra data changes.
20592	</desc>
20593	</attribute>
20594	<attribute name="key" type="wstring" readonly="yes">
20595	<desc>
20596	Extra data key that has changed.
20597	</desc>
20598	</attribute>
20599	<attribute name="value" type="wstring" readonly="yes">
20600	<desc>
20601	Extra data value for the given key.
20602	</desc>
20603	</attribute>
20604	</interface>
20605
20606	<interface
20607	name="ICanShowWindowEvent" extends="IVetoEvent"
20608	uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
20609	wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
20610	waitable="true"
20611	>
20612	<desc>
20613	Notification when a call to
20614	<link to="IMachine::canShowConsoleWindow"/> is made by a
20615	front-end to check if a subsequent call to
20616	<link to="IMachine::showConsoleWindow"/> can succeed.
20617
20618	The callee should give an answer appropriate to the current
20619	machine state using event veto. This answer must
20620	remain valid at least until the next
20621	<link to="IConsole::state">machine state</link> change.
20622	</desc>
20623	</interface>
20624
20625	<interface
20626	name="IShowWindowEvent" extends="IEvent"
20627	uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
20628	wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
20629	waitable="true"
20630	>
20631	<desc>
20632	Notification when a call to
20633	<link to="IMachine::showConsoleWindow"/>
20634	requests the console window to be activated and brought to
20635	foreground on the desktop of the host PC.
20636
20637	This notification should cause the VM console process to
20638	perform the requested action as described above. If it is
20639	impossible to do it at a time of this notification, this
20640	method should return a failure.
20641
20642	Note that many modern window managers on many platforms
20643	implement some sort of focus stealing prevention logic, so
20644	that it may be impossible to activate a window without the
20645	help of the currently active application (which is supposedly
20646	an initiator of this notification). In this case, this method
20647	must return a non-zero identifier that represents the
20648	top-level window of the VM console process. The caller, if it
20649	represents a currently active process, is responsible to use
20650	this identifier (in a platform-dependent manner) to perform
20651	actual window activation.
20652
20653	This method must set @a winId to zero if it has performed all
20654	actions necessary to complete the request and the console
20655	window is now active and in foreground, to indicate that no
20656	further action is required on the caller's side.
20657	</desc>
20658	<attribute name="winId" type="long long">
20659	<desc>
20660	Platform-dependent identifier of the top-level VM console
20661	window, or zero if this method has performed all actions
20662	necessary to implement the <i>show window</i> semantics for
20663	the given platform and/or this VirtualBox front-end.
20664	</desc>
20665	</attribute>
20666	</interface>
20667
20668	<interface
20669	name="INATRedirectEvent" extends="IMachineEvent"
20670	uuid="24eef068-c380-4510-bc7c-19314a7352f1"
20671	wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect"
20672	>
20673	<desc>
20674	Notification when NAT redirect rule added or removed.
20675	</desc>
20676	<attribute name="slot" type="unsigned long" readonly="yes">
20677	<desc>
20678	Adapter which NAT attached to.
20679	</desc>
20680	</attribute>
20681	<attribute name="remove" type="boolean" readonly="yes">
20682	<desc>
20683	Whether rule remove or add.
20684	</desc>
20685	</attribute>
20686	<attribute name="name" type="wstring" readonly="yes">
20687	<desc>
20688	Name of the rule.
20689	</desc>
20690	</attribute>
20691	<attribute name="proto" type="NATProtocol" readonly="yes">
20692	<desc>
20693	Protocol (TCP or UDP) of the redirect rule.
20694	</desc>
20695	</attribute>
20696	<attribute name="hostIP" type="wstring" readonly="yes">
20697	<desc>
20698	Host ip address to bind socket on.
20699	</desc>
20700	</attribute>
20701	<attribute name="hostPort" type="long" readonly="yes">
20702	<desc>
20703	Host port to bind socket on.
20704	</desc>
20705	</attribute>
20706	<attribute name="guestIP" type="wstring" readonly="yes">
20707	<desc>
20708	Guest ip address to redirect to.
20709	</desc>
20710	</attribute>
20711	<attribute name="guestPort" type="long" readonly="yes">
20712	<desc>
20713	Guest port to redirect to.
20714	</desc>
20715	</attribute>
20716	</interface>
20717
20718	<interface
20719	name="IHostPCIDevicePlugEvent" extends="IMachineEvent"
20720	waitable="yes"
20721	uuid="a0bad6df-d612-47d3-89d4-db3992533948"
20722	wsmap="managed" autogen="VBoxEvent" id="OnHostPCIDevicePlug"
20723	>
20724	<desc>
20725	Notification when host PCI device is plugged/unplugged. Plugging
20726	usually takes place on VM startup, unplug - when
20727	<link to="IMachine::detachHostPCIDevice"/> is called.
20728
20729	<see><link to="IMachine::detachHostPCIDevice"/></see>
20730
20731	</desc>
20732
20733	<attribute name="plugged" type="boolean" readonly="yes">
20734	<desc>
20735	If device successfully plugged or unplugged.
20736	</desc>
20737	</attribute>
20738
20739	<attribute name="success" type="boolean" readonly="yes">
20740	<desc>
20741	If operation was successful, if false - 'message' attribute
20742	may be of interest.
20743	</desc>
20744	</attribute>
20745
20746	<attribute name="attachment" type="IPCIDeviceAttachment" readonly="yes">
20747	<desc>
20748	Attachment info for this device.
20749	</desc>
20750	</attribute>
20751
20752	<attribute name="message" type="wstring" readonly="yes">
20753	<desc>
20754	Optional error message.
20755	</desc>
20756	</attribute>
20757
20758	</interface>
20759
20760	<interface
20761	name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent"
20762	uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc"
20763	wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged"
20764	>
20765	<desc>
20766	Notification when VBoxSVC becomes unavailable (due to a crash or similar
20767	unexpected circumstances) or available again.
20768	</desc>
20769
20770	<attribute name="available" type="boolean" readonly="yes">
20771	<desc>
20772	Whether VBoxSVC is available now.
20773	</desc>
20774	</attribute>
20775	</interface>
20776
20777	<interface
20778	name="IBandwidthGroupChangedEvent" extends="IEvent"
20779	uuid="334df94a-7556-4cbc-8c04-043096b02d82"
20780	wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged"
20781	>
20782	<desc>
20783	Notification when one of the bandwidth groups changed
20784	</desc>
20785	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
20786	<desc>
20787	The changed bandwidth group.
20788	</desc>
20789	</attribute>
20790	</interface>
20791
20792	<enum
20793	name="GuestMonitorChangedEventType"
20794	uuid="ef172985-7e36-4297-95be-e46396968d66"
20795	>
20796
20797	<desc>
20798	How the guest monitor has been changed.
20799	</desc>
20800
20801	<const name="Enabled" value="0">
20802	<desc>
20803	The guest monitor has been enabled by the guest.
20804	</desc>
20805	</const>
20806
20807	<const name="Disabled" value="1">
20808	<desc>
20809	The guest monitor has been disabled by the guest.
20810	</desc>
20811	</const>
20812
20813	<const name="NewOrigin" value="2">
20814	<desc>
20815	The guest monitor origin has changed in the guest.
20816	</desc>
20817	</const>
20818	</enum>
20819
20820	<interface
20821	name="IGuestMonitorChangedEvent" extends="IEvent"
20822	uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090"
20823	wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged"
20824	>
20825	<desc>
20826	Notification when the guest enables one of its monitors.
20827	</desc>
20828
20829	<attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes">
20830	<desc>
20831	What was changed for this guest monitor.
20832	</desc>
20833	</attribute>
20834
20835	<attribute name="screenId" type="unsigned long" readonly="yes">
20836	<desc>
20837	The monitor which was changed.
20838	</desc>
20839	</attribute>
20840
20841	<attribute name="originX" type="unsigned long" readonly="yes">
20842	<desc>
20843	Physical X origin relative to the primary screen.
20844	Valid for Enabled and NewOrigin.
20845	</desc>
20846	</attribute>
20847
20848	<attribute name="originY" type="unsigned long" readonly="yes">
20849	<desc>
20850	Physical Y origin relative to the primary screen.
20851	Valid for Enabled and NewOrigin.
20852	</desc>
20853	</attribute>
20854
20855	<attribute name="width" type="unsigned long" readonly="yes">
20856	<desc>
20857	Width of the screen.
20858	Valid for Enabled.
20859	</desc>
20860	</attribute>
20861
20862	<attribute name="height" type="unsigned long" readonly="yes">
20863	<desc>
20864	Height of the screen.
20865	Valid for Enabled.
20866	</desc>
20867	</attribute>
20868
20869	</interface>
20870
20871	<interface
20872	name="IStorageDeviceChangedEvent" extends="IEvent"
20873	uuid="232e9151-ae84-4b8e-b0f3-5c20c35caac9"
20874	wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged"
20875	>
20876	<desc>
20877	Notification when a
20878	<link to="IMachine::mediumAttachments">storage device</link>
20879	is attached or removed.
20880	</desc>
20881	<attribute name="storageDevice" type="IMediumAttachment" readonly="yes">
20882	<desc>
20883	Storage device that is subject to change.
20884	</desc>
20885	</attribute>
20886	<attribute name="removed" type="boolean" readonly="yes">
20887	<desc>
20888	Flag whether the device was removed or added to the VM.
20889	</desc>
20890	</attribute>
20891	<attribute name="silent" type="boolean" readonly="yes">
20892	<desc>
20893	Flag whether the guest should be notified about the change.
20894	</desc>
20895	</attribute>
20896	</interface>
20897	<interface
20898	name="INATNetworkChangedEvent" extends="IEvent"
20899	uuid="101ae042-1a29-4a19-92cf-02285773f3b5"
20900	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkChanged"
20901	>
20902	<!-- network name is common setting for all event types -->
20903	<attribute name="NetworkName" type="wstring" readonly="yes"/>
20904	</interface>
20905	<!-- base class for start/stop events -->
20906	<interface name="INATNetworkStartStopEvent" extends="INATNetworkChangedEvent"
20907	uuid="269d8f6b-fa1e-4cee-91c7-6d8496bea3c1"
20908	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkStartStop">
20909	<attribute name="startEvent" type="boolean" readonly="yes">
20910	<desc>
20911	IsStartEvent is true when NAT network is started and false on stopping.
20912	</desc>
20913	</attribute>
20914	</interface>
20915
20916	<!-- base class for modification events -->
20917	<interface name="INATNetworkAlterEvent" extends="INATNetworkChangedEvent"
20918	uuid="3f5a0822-163a-43b1-ad16-8d58b0ef6e75"
20919	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkAlter"/>
20920
20921	<interface name="INATNetworkCreationDeletionEvent" extends="INATNetworkAlterEvent"
20922	uuid="8d984a7e-b855-40b8-ab0c-44d3515b4528"
20923	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkCreationDeletion">
20924	<attribute name="creationEvent" type="boolean" readonly="yes"/>
20925	</interface>
20926	<interface name="INATNetworkSettingEvent" extends="INATNetworkAlterEvent"
20927	uuid="9db3a9e6-7f29-4aae-a627-5a282c83092c"
20928	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkSetting">
20929	<attribute name="enabled" type="boolean" readonly="yes"/>
20930	<attribute name="network" type="wstring" readonly="yes"/>
20931	<attribute name="gateway" type="wstring" readonly="yes"/>
20932	<attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" readonly="yes"/>
20933	<attribute name="needDhcpServer" type="boolean" readonly="yes"/>
20934	</interface>
20935	<interface name="INATNetworkPortForwardEvent" extends="INATNetworkAlterEvent"
20936	uuid="2514881b-23d0-430a-a7ff-7ed7f05534bc"
20937	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkPortForward">
20938	<attribute name="create" type="boolean" readonly="yes"/>
20939	<attribute name="ipv6" type="boolean" readonly="yes"/>
20940	<attribute name="name" type="wstring" readonly="yes"/>
20941	<attribute name="proto" type="NATProtocol" readonly="yes"/>
20942	<attribute name="hostIp" type="wstring" readonly="yes"/>
20943	<attribute name="hostPort" type="long" readonly="yes"/>
20944	<attribute name="guestIp" type="wstring" readonly="yes"/>
20945	<attribute name="guestPort" type="long" readonly="yes"/>
20946	</interface>
20947
20948	<module name="VBoxSVC" context="LocalServer">
20949	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
20950	namespace="virtualbox.org">
20951	<interface name="IVirtualBox" default="yes"/>
20952	</class>
20953	</module>
20954
20955	<module name="VBoxC" context="InprocServer" threadingModel="Free">
20956	<class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba"
20957	namespace="virtualbox.org">
20958	<interface name="IVirtualBoxClient" default="yes"/>
20959	</class>
20960
20961	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
20962	namespace="virtualbox.org">
20963	<interface name="ISession" default="yes"/>
20964	</class>
20965	</module>
20966
20967	</library>
20968
20969	</idl>
20970
20971	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format