VirtualBox.xidl@ 45971

Last change on this file since 45971 was 45971, checked in by vboxsync, 12 years ago
Main, VMM: Added an API seting to disable VT-x unrestricted execution.
Property svn:eol-style set to `native`
File size: 757.4 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="55bf39d3-ac8f-4a77-90d8-1e2c726170ce"
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="VideoCaptureFile" type="wstring" default="Test.webm">
4245	<desc>
4246	This setting determines the filename VirtualBox uses to save
4247	the recorded content.</desc>
4248	</attribute>
4249
4250	<attribute name="VideoCaptureWidth" type="unsigned long" default="640">
4251	<desc>
4252	This setting determines the horizontal resolution of the recorded video.</desc>
4253	</attribute>
4254
4255	<attribute name="VideoCaptureHeight" type="unsigned long" default="480">
4256	<desc>
4257	This setting determines the vertical resolution of the recorded video.</desc>
4258	</attribute>
4259
4260	<attribute name="VideoCaptureRate" type="unsigned long" default="512">
4261	<desc>
4262	This setting determines the bitrate in kilobits per second.
4263	Increasing this value makes the video look better for the
4264	cost of an increased file size.
4265	</desc>
4266	</attribute>
4267
4268	<attribute name="VideoCaptureFps" type="unsigned long" default="25">
4269	<desc>
4270	This setting determines the maximum number of frames per second.
4271	Frames with a higher frequency will be skipped. Reducing this
4272	value increses the number of skipped frames but reduces the
4273	file size.
4274	</desc>
4275	</attribute>
4276
4277	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4278	<desc>Object containing all BIOS settings.</desc>
4279	</attribute>
4280
4281	<attribute name="firmwareType" type="FirmwareType">
4282	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4283	bootstrap in this VM.</desc>
4284	</attribute>
4285
4286	<attribute name="pointingHIDType" type="PointingHIDType">
4287	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4288	The default is typically "PS2Mouse" but can vary depending on the
4289	requirements of the guest operating system.</desc>
4290	</attribute>
4291
4292	<attribute name="keyboardHIDType" type="KeyboardHIDType">
4293	<desc>Type of keyboard HID used in this VM.
4294	The default is typically "PS2Keyboard" but can vary depending on the
4295	requirements of the guest operating system.</desc>
4296	</attribute>
4297
4298	<attribute name="HPETEnabled" type="boolean">
4299	<desc>This attribute controls if High Precision Event Timer (HPET) is
4300	enabled in this VM. Use this property if you want to provide guests
4301	with additional time source, or if guest requires HPET to function correctly.
4302	Default is false.</desc>
4303	</attribute>
4304
4305	<attribute name="chipsetType" type="ChipsetType">
4306	<desc>Chipset type used in this VM.</desc>
4307	</attribute>
4308
4309	<attribute name="snapshotFolder" type="wstring">
4310	<desc>
4311	Full path to the directory used to store snapshot data
4312	(differencing media and saved state files) of this machine.
4313
4314	The initial value of this property is
4315	<tt><</tt><link to="#settingsFilePath">
4316	path_to_settings_file</link><tt>>/<</tt>
4317	<link to="#id">machine_uuid</link>
4318	<tt>></tt>.
4319
4320	Currently, it is an error to try to change this property on
4321	a machine that has snapshots (because this would require to
4322	move possibly large files to a different location).
4323	A separate method will be available for this purpose later.
4324
4325	<note>
4326	Setting this property to @c null or to an empty string will restore
4327	the initial value.
4328	</note>
4329	<note>
4330	When setting this property, the specified path can be
4331	absolute (full path) or relative to the directory where the
4332	<link to="#settingsFilePath">machine settings file</link>
4333	is located. When reading this property, a full path is
4334	always returned.
4335	</note>
4336	<note>
4337	The specified path may not exist, it will be created
4338	when necessary.
4339	</note>
4340	</desc>
4341	</attribute>
4342
4343	<attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
4344	<desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
4345	</attribute>
4346
4347	<attribute name="emulatedUSBWebcameraEnabled" type="boolean" default="false"/>
4348	<attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/>
4349
4350	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4351	<desc>Array of media attached to this machine.</desc>
4352	</attribute>
4353
4354	<attribute name="USBController" type="IUSBController" readonly="yes">
4355	<desc>
4356	Associated USB controller object.
4357
4358	<note>
4359	If USB functionality is not available in the given edition of
4360	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4361	</note>
4362	</desc>
4363	</attribute>
4364
4365	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4366	<desc>Associated audio adapter, always present.</desc>
4367	</attribute>
4368
4369	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4370	<desc>Array of storage controllers attached to this machine.</desc>
4371	</attribute>
4372
4373	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4374	<desc>
4375	Full name of the file containing machine settings data.
4376	</desc>
4377	</attribute>
4378
4379	<attribute name="settingsModified" type="boolean" readonly="yes">
4380	<desc>
4381	Whether the settings of this machine have been modified
4382	(but neither yet saved nor discarded).
4383	<note>
4384	Reading this property is only valid on instances returned
4385	by <link to="ISession::machine"/> and on new machines
4386	created by <link to="IVirtualBox::createMachine"/> or opened
4387	by <link to="IVirtualBox::openMachine"/> but not
4388	yet registered, or on unregistered machines after calling
4389	<link to="IMachine::unregister"/>. For all other
4390	cases, the settings can never be modified.
4391	</note>
4392	<note>
4393	For newly created unregistered machines, the value of this
4394	property is always @c true until <link to="#saveSettings"/>
4395	is called (no matter if any machine settings have been
4396	changed after the creation or not). For opened machines
4397	the value is set to @c false (and then follows to normal rules).
4398	</note>
4399	</desc>
4400	</attribute>
4401
4402	<attribute name="sessionState" type="SessionState" readonly="yes">
4403	<desc>Current session state for this machine.</desc>
4404	</attribute>
4405
4406	<attribute name="sessionType" type="wstring" readonly="yes">
4407	<desc>
4408	Type of the session. If <link to="#sessionState"/> is
4409	Spawning or Locked, this attribute contains the
4410	same value as passed to the
4411	<link to="IMachine::launchVMProcess"/> method in the
4412	@a type parameter. If the session was used with
4413	<link to="IMachine::lockMachine" />, or if
4414	<link to="#sessionState"/> is SessionClosed, the value of this
4415	attribute is an empty string.
4416	</desc>
4417	</attribute>
4418
4419	<attribute name="sessionPID" type="unsigned long" readonly="yes">
4420	<desc>
4421	Identifier of the session process. This attribute contains the
4422	platform-dependent identifier of the process whose session was
4423	used with <link to="IMachine::lockMachine" /> call. The returned
4424	value is only valid if <link to="#sessionState"/> is Locked or
4425	Unlocking by the time this property is read.
4426	</desc>
4427	</attribute>
4428
4429	<attribute name="state" type="MachineState" readonly="yes">
4430	<desc>Current execution state of this machine.</desc>
4431	</attribute>
4432
4433	<attribute name="lastStateChange" type="long long" readonly="yes">
4434	<desc>
4435	Time stamp of the last execution state change,
4436	in milliseconds since 1970-01-01 UTC.
4437	</desc>
4438	</attribute>
4439
4440	<attribute name="stateFilePath" type="wstring" readonly="yes">
4441	<desc>
4442	Full path to the file that stores the execution state of
4443	the machine when it is in the <link to="MachineState_Saved"/> state.
4444	<note>
4445	When the machine is not in the Saved state, this attribute is
4446	an empty string.
4447	</note>
4448	</desc>
4449	</attribute>
4450
4451	<attribute name="logFolder" type="wstring" readonly="yes">
4452	<desc>
4453	Full path to the folder that stores a set of rotated log files
4454	recorded during machine execution. The most recent log file is
4455	named <tt>VBox.log</tt>, the previous log file is
4456	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4457	in the current version).
4458	</desc>
4459	</attribute>
4460
4461	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4462	<desc>
4463	Current snapshot of this machine. This is @c null if the machine
4464	currently has no snapshots. If it is not @c null, then it was
4465	set by one of <link to="IConsole::takeSnapshot" />,
4466	<link to="IConsole::deleteSnapshot" />
4467	or <link to="IConsole::restoreSnapshot" />, depending on which
4468	was called last. See <link to="ISnapshot"/> for details.
4469	</desc>
4470	</attribute>
4471
4472	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4473	<desc>
4474	Number of snapshots taken on this machine. Zero means the
4475	machine doesn't have any snapshots.
4476	</desc>
4477	</attribute>
4478
4479	<attribute name="currentStateModified" type="boolean" readonly="yes">
4480	<desc>
4481	Returns @c true if the current state of the machine is not
4482	identical to the state stored in the current snapshot.
4483
4484	The current state is identical to the current snapshot only
4485	directly after one of the following calls are made:
4486
4487	<ul>
4488	<li><link to="IConsole::restoreSnapshot"/>
4489	</li>
4490	<li><link to="IConsole::takeSnapshot"/> (issued on a
4491	"powered off" or "saved" machine, for which
4492	<link to="#settingsModified"/> returns @c false)
4493	</li>
4494	</ul>
4495
4496	The current state remains identical until one of the following
4497	happens:
4498	<ul>
4499	<li>settings of the machine are changed</li>
4500	<li>the saved state is deleted</li>
4501	<li>the current snapshot is deleted</li>
4502	<li>an attempt to execute the machine is made</li>
4503	</ul>
4504
4505	<note>
4506	For machines that don't have snapshots, this property is
4507	always @c false.
4508	</note>
4509	</desc>
4510	</attribute>
4511
4512	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4513	<desc>
4514	Collection of shared folders for this machine (permanent shared
4515	folders). These folders are shared automatically at machine startup
4516	and available only to the guest OS installed within this machine.
4517
4518	New shared folders are added to the collection using
4519	<link to="#createSharedFolder"/>. Existing shared folders can be
4520	removed using <link to="#removeSharedFolder"/>.
4521	</desc>
4522	</attribute>
4523
4524	<attribute name="clipboardMode" type="ClipboardMode">
4525	<desc>
4526	Synchronization mode between the host OS clipboard
4527	and the guest OS clipboard.
4528	</desc>
4529	</attribute>
4530
4531	<attribute name="dragAndDropMode" type="DragAndDropMode">
4532	<desc>
4533	Which mode is allowed for drag'n'drop.
4534	</desc>
4535	</attribute>
4536
4537	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4538	<desc>
4539	A comma-separated list of simple glob patterns. Changes to guest
4540	properties whose name matches one of the patterns will generate an
4541	<link to="IGuestPropertyChangedEvent"/> signal.
4542	</desc>
4543	</attribute>
4544
4545	<attribute name="teleporterEnabled" type="boolean">
4546	<desc>
4547	When set to @a true, the virtual machine becomes a target teleporter
4548	the next time it is powered on. This can only set to @a true when the
4549	VM is in the @a PoweredOff or @a Aborted state.
4550
4551	<!-- This property is automatically set to @a false when the VM is powered
4552	on. (bird: This doesn't work yet ) -->
4553	</desc>
4554	</attribute>
4555
4556	<attribute name="teleporterPort" type="unsigned long">
4557	<desc>
4558	The TCP port the target teleporter will listen for incoming
4559	teleportations on.
4560
4561	0 means the port is automatically selected upon power on. The actual
4562	value can be read from this property while the machine is waiting for
4563	incoming teleportations.
4564	</desc>
4565	</attribute>
4566
4567	<attribute name="teleporterAddress" type="wstring">
4568	<desc>
4569	The address the target teleporter will listen on. If set to an empty
4570	string, it will listen on all addresses.
4571	</desc>
4572	</attribute>
4573
4574	<attribute name="teleporterPassword" type="wstring">
4575	<desc>
4576	The password to check for on the target teleporter. This is just a
4577	very basic measure to prevent simple hacks and operators accidentally
4578	beaming a virtual machine to the wrong place.
4579
4580	Note that you SET a plain text password while reading back a HASHED
4581	password. Setting a hashed password is currently not supported.
4582	</desc>
4583	</attribute>
4584
4585	<attribute name="faultToleranceState" type="FaultToleranceState">
4586	<desc>
4587	Fault tolerance state; disabled, source or target.
4588	This property can be changed at any time. If you change it for a running
4589	VM, then the fault tolerance address and port must be set beforehand.
4590	</desc>
4591	</attribute>
4592
4593	<attribute name="faultTolerancePort" type="unsigned long">
4594	<desc>
4595	The TCP port the fault tolerance source or target will use for
4596	communication.
4597	</desc>
4598	</attribute>
4599
4600	<attribute name="faultToleranceAddress" type="wstring">
4601	<desc>
4602	The address the fault tolerance source or target.
4603	</desc>
4604	</attribute>
4605
4606	<attribute name="faultTolerancePassword" type="wstring">
4607	<desc>
4608	The password to check for on the standby VM. This is just a
4609	very basic measure to prevent simple hacks and operators accidentally
4610	choosing the wrong standby VM.
4611	</desc>
4612	</attribute>
4613
4614	<attribute name="faultToleranceSyncInterval" type="unsigned long">
4615	<desc>
4616	The interval in ms used for syncing the state between source and target.
4617	</desc>
4618	</attribute>
4619
4620	<attribute name="RTCUseUTC" type="boolean">
4621	<desc>
4622	When set to @a true, the RTC device of the virtual machine will run
4623	in UTC time, otherwise in local time. Especially Unix guests prefer
4624	the time in UTC.
4625	</desc>
4626	</attribute>
4627
4628	<attribute name="IOCacheEnabled" type="boolean">
4629	<desc>
4630	When set to @a true, the builtin I/O cache of the virtual machine
4631	will be enabled.
4632	</desc>
4633	</attribute>
4634
4635	<attribute name="IOCacheSize" type="unsigned long">
4636	<desc>
4637	Maximum size of the I/O cache in MB.
4638	</desc>
4639	</attribute>
4640
4641	<attribute name="PCIDeviceAssignments" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
4642	<desc>Array of PCI devices assigned to this machine, to get list of all
4643	PCI devices attached to the machine use
4644	<link to="IConsole::attachedPCIDevices"/> attribute, as this attribute
4645	is intended to list only devices additional to what described in
4646	virtual hardware config. Usually, this list keeps host's physical
4647	devices assigned to the particular machine.
4648	</desc>
4649	</attribute>
4650
4651	<attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes">
4652	<desc>
4653	Bandwidth control manager.
4654	</desc>
4655	</attribute>
4656
4657	<attribute name="tracingEnabled" type="boolean">
4658	<desc>
4659	Enables the tracing facility in the VMM (including PDM devices +
4660	drivers). The VMM will consume about 0.5MB of more memory when
4661	enabled and there may be some extra overhead from tracepoints that are
4662	always enabled.
4663	</desc>
4664	</attribute>
4665
4666	<attribute name="tracingConfig" type="wstring">
4667	<desc>
4668	Tracepoint configuration to apply at startup when
4669	<link to="IMachine::tracingEnabled" /> is true. The string specifies
4670	a space separated of tracepoint group names to enable. The special
4671	group 'all' enables all tracepoints. Check DBGFR3TracingConfig for
4672	more details on available tracepoint groups and such.
4673
4674	Note that on hosts supporting DTrace (or similar), a lot of the
4675	tracepoints may be implemented exclusivly as DTrace probes. So, the
4676	effect of the same config may differ between Solaris and Windows for
4677	example.
4678	</desc>
4679	</attribute>
4680
4681	<attribute name="allowTracingToAccessVM" type="boolean">
4682	<desc>
4683	Enables tracepoints in PDM devices and drivers to use the VMCPU or VM
4684	structures when firing off trace points. This is especially useful
4685	with DTrace tracepoints, as it allows you to use the VMCPU or VM
4686	pointer to obtain useful information such as guest register state.
4687
4688	This is disabled by default because devices and drivers normally has no
4689	business accessing the VMCPU or VM structures, and are therefore unable
4690	to get any pointers to these.
4691	</desc>
4692	</attribute>
4693
4694	<attribute name="autostartEnabled" type="boolean">
4695	<desc>
4696	Enables autostart of the VM during system boot.
4697	</desc>
4698	</attribute>
4699
4700	<attribute name="autostartDelay" type="unsigned long">
4701	<desc>
4702	Number of seconds to wait until the VM should be started during system boot.
4703	</desc>
4704	</attribute>
4705
4706	<attribute name="autostopType" type="AutostopType">
4707	<desc>
4708	Action type to do when the system is shutting down.
4709	</desc>
4710	</attribute>
4711
4712	<attribute name="defaultFrontend" type="wstring">
4713	<desc>
4714	Selects which VM frontend should be used by default when launching
4715	this VM through the <link to="IMachine::launchVMProcess" /> method.
4716	Empty or @c null strings do not define a particular default, it is up
4717	to <link to="IMachine::launchVMProcess" /> to select one. See the
4718	description of <link to="IMachine::launchVMProcess" /> for the valid
4719	frontend types.
4720
4721	This per-VM setting overrides the default defined by
4722	<link to="ISystemProperties::defaultFrontend" /> attribute, and is
4723	overridden by a frontend type passed to
4724	<link to="IMachine::launchVMProcess" />.
4725	</desc>
4726	</attribute>
4727
4728	<method name="lockMachine">
4729	<desc>
4730	Locks the machine for the given session to enable the caller
4731	to make changes to the machine or start the VM or control
4732	VM execution.
4733
4734	There are two ways to lock a machine for such uses:
4735
4736	<ul>
4737	<li>If you want to make changes to the machine settings,
4738	you must obtain an exclusive write lock on the machine
4739	by setting @a lockType to @c Write.
4740
4741	This will only succeed if no other process has locked
4742	the machine to prevent conflicting changes. Only after
4743	an exclusive write lock has been obtained using this method, one
4744	can change all VM settings or execute the VM in the process
4745	space of the session object. (Note that the latter is only of
4746	interest if you actually want to write a new front-end for
4747	virtual machines; but this API gets called internally by
4748	the existing front-ends such as VBoxHeadless and the VirtualBox
4749	GUI to acquire a write lock on the machine that they are running.)
4750
4751	On success, write-locking the machine for a session creates
4752	a second copy of the IMachine object. It is this second object
4753	upon which changes can be made; in VirtualBox terminology, the
4754	second copy is "mutable". It is only this second, mutable machine
4755	object upon which you can call methods that change the
4756	machine state. After having called this method, you can
4757	obtain this second, mutable machine object using the
4758	<link to="ISession::machine" /> attribute.
4759	</li>
4760	<li>If you only want to check the machine state or control
4761	machine execution without actually changing machine
4762	settings (e.g. to get access to VM statistics or take
4763	a snapshot or save the machine state), then set the
4764	@a lockType argument to @c Shared.
4765
4766	If no other session has obtained a lock, you will obtain an
4767	exclusive write lock as described above. However, if another
4768	session has already obtained such a lock, then a link to that
4769	existing session will be established which allows you
4770	to control that existing session.
4771
4772	To find out which type of lock was obtained, you can
4773	inspect <link to="ISession::type" />, which will have been
4774	set to either @c WriteLock or @c Shared.
4775	</li>
4776	</ul>
4777
4778	In either case, you can get access to the <link to="IConsole" />
4779	object which controls VM execution.
4780
4781	Also in all of the above cases, one must always call
4782	<link to="ISession::unlockMachine" /> to release the lock on the machine, or
4783	the machine's state will eventually be set to "Aborted".
4784
4785	To change settings on a machine, the following sequence is typically
4786	performed:
4787
4788	<ol>
4789	<li>Call this method to obtain an exclusive write lock for the current session.</li>
4790
4791	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
4792
4793	<li>Change the settings of the machine by invoking IMachine methods.</li>
4794
4795	<li>Call <link to="IMachine::saveSettings" />.</li>
4796
4797	<li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
4798	</ol>
4799
4800	<result name="E_UNEXPECTED">
4801	Virtual machine not registered.
4802	</result>
4803	<result name="E_ACCESSDENIED">
4804	Process not started by OpenRemoteSession.
4805	</result>
4806	<result name="VBOX_E_INVALID_OBJECT_STATE">
4807	Session already open or being opened.
4808	</result>
4809	<result name="VBOX_E_VM_ERROR">
4810	Failed to assign machine to session.
4811	</result>
4812	</desc>
4813	<param name="session" type="ISession" dir="in">
4814	<desc>
4815	Session object for which the machine will be locked.
4816	</desc>
4817	</param>
4818	<param name="lockType" type="LockType" dir="in">
4819	<desc>
4820	If set to @c Write, then attempt to acquire an exclusive write lock or fail.
4821	If set to @c Shared, then either acquire an exclusive write lock or establish
4822	a link to an existing session.
4823	</desc>
4824	</param>
4825	</method>
4826
4827	<method name="launchVMProcess">
4828	<desc>
4829	Spawns a new process that will execute the virtual machine and obtains a shared
4830	lock on the machine for the calling session.
4831
4832	If launching the VM succeeds, the new VM process will create its own session
4833	and write-lock the machine for it, preventing conflicting changes from other
4834	processes. If the machine is already locked (because it is already running or
4835	because another session has a write lock), launching the VM process will therefore
4836	fail. Reversely, future attempts to obtain a write lock will also fail while the
4837	machine is running.
4838
4839	The caller's session object remains separate from the session opened by the new
4840	VM process. It receives its own <link to="IConsole" /> object which can be used
4841	to control machine execution, but it cannot be used to change all VM settings
4842	which would be available after a <link to="#lockMachine" /> call.
4843
4844	The caller must eventually release the session's shared lock by calling
4845	<link to="ISession::unlockMachine" /> on the local session object once this call
4846	has returned. However, the session's state (see <link to="ISession::state" />)
4847	will not return to "Unlocked" until the remote session has also unlocked
4848	the machine (i.e. the machine has stopped running).
4849
4850	Launching a VM process can take some time (a new VM is started in a new process,
4851	for which memory and other resources need to be set up). Because of this,
4852	an <link to="IProgress" /> object is returned to allow the caller to wait
4853	for this asynchronous operation to be completed. Until then, the caller's
4854	session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
4855	and <link to="ISession::console" /> attributes cannot be accessed.
4856	It is recommended to use <link to="IProgress::waitForCompletion" /> or
4857	similar calls to wait for completion. Completion is signalled when the VM
4858	is powered on. If launching the VM fails, error messages can be queried
4859	via the progress object, if available.
4860
4861	The progress object will have at least 2 sub-operations. The first
4862	operation covers the period up to the new VM process calls powerUp.
4863	The subsequent operations mirror the <link to="IConsole::powerUp"/>
4864	progress object. Because <link to="IConsole::powerUp"/> may require
4865	some extra sub-operations, the <link to="IProgress::operationCount"/>
4866	may change at the completion of operation.
4867
4868	For details on the teleportation progress operation, see
4869	<link to="IConsole::powerUp"/>.
4870
4871	The @a environment argument is a string containing definitions of
4872	environment variables in the following format:
4873	<pre>
4874	NAME[=VALUE]\n
4875	NAME[=VALUE]\n
4876	...
4877	</pre>
4878	where <tt>\\n</tt> is the new line character. These environment
4879	variables will be appended to the environment of the VirtualBox server
4880	process. If an environment variable exists both in the server process
4881	and in this list, the value from this list takes precedence over the
4882	server's variable. If the value of the environment variable is
4883	omitted, this variable will be removed from the resulting environment.
4884	If the environment string is @c null or empty, the server environment
4885	is inherited by the started process as is.
4886
4887	<result name="E_UNEXPECTED">
4888	Virtual machine not registered.
4889	</result>
4890	<result name="E_INVALIDARG">
4891	Invalid session type @a type.
4892	</result>
4893	<result name="VBOX_E_OBJECT_NOT_FOUND">
4894	No machine matching @a machineId found.
4895	</result>
4896	<result name="VBOX_E_INVALID_OBJECT_STATE">
4897	Session already open or being opened.
4898	</result>
4899	<result name="VBOX_E_IPRT_ERROR">
4900	Launching process for machine failed.
4901	</result>
4902	<result name="VBOX_E_VM_ERROR">
4903	Failed to assign machine to session.
4904	</result>
4905	</desc>
4906	<param name="session" type="ISession" dir="in">
4907	<desc>
4908	Client session object to which the VM process will be connected (this
4909	must be in "Unlocked" state).
4910	</desc>
4911	</param>
4912	<param name="type" type="wstring" dir="in">
4913	<desc>
4914	Front-end to use for the new VM process. The following are currently supported:
4915	<ul>
4916	<li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
4917	<li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
4918	<li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
4919	<li><tt>"emergencystop"</tt>: reserved value, used for aborting
4920	the currently running VM or session owner. In this case the
4921	@a session parameter may be @c null (if it is non-null it isn't
4922	used in any way), and the @a progress return value will be always
4923	@c null. The operation completes immediately.</li>
4924	<li><tt>""</tt>: use the per-VM default frontend if set, otherwise
4925	the global default defined in the system properties. If neither
4926	are set, the API will launch a <tt>"gui"</tt> session, which may
4927	fail if there is no windowing environment available. See
4928	<link to="IMachine::defaultFrontend"/> and
4929	<link to="ISystemProperties::defaultFrontend"/>.</li>
4930	</ul>
4931	</desc>
4932	</param>
4933	<param name="environment" type="wstring" dir="in">
4934	<desc>
4935	Environment to pass to the VM process.
4936	</desc>
4937	</param>
4938	<param name="progress" type="IProgress" dir="return">
4939	<desc>Progress object to track the operation completion.</desc>
4940	</param>
4941	</method>
4942
4943	<method name="setBootOrder">
4944	<desc>
4945	Puts the given device to the specified position in
4946	the boot order.
4947
4948	To indicate that no device is associated with the given position,
4949	<link to="DeviceType_Null"/> should be used.
4950
4951	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4952
4953	<result name="E_INVALIDARG">
4954	Boot @a position out of range.
4955	</result>
4956	<result name="E_NOTIMPL">
4957	Booting from USB @a device currently not supported.
4958	</result>
4959
4960	</desc>
4961	<param name="position" type="unsigned long" dir="in">
4962	<desc>
4963	Position in the boot order (@c 1 to the total number of
4964	devices the machine can boot from, as returned by
4965	<link to="ISystemProperties::maxBootPosition"/>).
4966	</desc>
4967	</param>
4968	<param name="device" type="DeviceType" dir="in">
4969	<desc>
4970	The type of the device used to boot at the given position.
4971	</desc>
4972	</param>
4973	</method>
4974
4975	<method name="getBootOrder" const="yes">
4976	<desc>
4977	Returns the device type that occupies the specified
4978	position in the boot order.
4979
4980	@todo [remove?]
4981	If the machine can have more than one device of the returned type
4982	(such as hard disks), then a separate method should be used to
4983	retrieve the individual device that occupies the given position.
4984
4985	If here are no devices at the given position, then
4986	<link to="DeviceType_Null"/> is returned.
4987
4988	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4989
4990	<result name="E_INVALIDARG">
4991	Boot @a position out of range.
4992	</result>
4993
4994	</desc>
4995	<param name="position" type="unsigned long" dir="in">
4996	<desc>
4997	Position in the boot order (@c 1 to the total number of
4998	devices the machine can boot from, as returned by
4999	<link to="ISystemProperties::maxBootPosition"/>).
5000	</desc>
5001	</param>
5002	<param name="device" type="DeviceType" dir="return">
5003	<desc>
5004	Device at the given position.
5005	</desc>
5006	</param>
5007	</method>
5008
5009	<method name="attachDevice">
5010	<desc>
5011	Attaches a device and optionally mounts a medium to the given storage
5012	controller (<link to="IStorageController" />, identified by @a name),
5013	at the indicated port and device.
5014
5015	This method is intended for managing storage devices in general while a
5016	machine is powered off. It can be used to attach and detach fixed
5017	and removable media. The following kind of media can be attached
5018	to a machine:
5019
5020	<ul>
5021	<li>For fixed and removable media, you can pass in a medium that was
5022	previously opened using <link to="IVirtualBox::openMedium" />.
5023	</li>
5024
5025	<li>Only for storage devices supporting removable media (such as
5026	DVDs and floppies), you can also specify a null pointer to
5027	indicate an empty drive or one of the medium objects listed
5028	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5029	arrays to indicate a host drive.
5030	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5031	to change the media while the machine is running.
5032	</li>
5033	</ul>
5034
5035	In a VM's default configuration of virtual machines, the secondary
5036	master of the IDE controller is used for a CD/DVD drive.
5037
5038	After calling this returns successfully, a new instance of
5039	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5040	attachments (see <link to="IMachine::mediumAttachments"/>).
5041
5042	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5043	information about attaching media.
5044
5045	The specified device slot must not have a device attached to it,
5046	or this method will fail.
5047
5048	<note>
5049	You cannot attach a device to a newly created machine until
5050	this machine's settings are saved to disk using
5051	<link to="#saveSettings"/>.
5052	</note>
5053	<note>
5054	If the medium is being attached indirectly, a new differencing medium
5055	will implicitly be created for it and attached instead. If the
5056	changes made to the machine settings (including this indirect
5057	attachment) are later cancelled using <link to="#discardSettings"/>,
5058	this implicitly created differencing medium will implicitly
5059	be deleted.
5060	</note>
5061
5062	<result name="E_INVALIDARG">
5063	SATA device, SATA port, IDE port or IDE slot out of range, or
5064	file or UUID not found.
5065	</result>
5066	<result name="VBOX_E_INVALID_OBJECT_STATE">
5067	Machine must be registered before media can be attached.
5068	</result>
5069	<result name="VBOX_E_INVALID_VM_STATE">
5070	Invalid machine state.
5071	</result>
5072	<result name="VBOX_E_OBJECT_IN_USE">
5073	A medium is already attached to this or another virtual machine.
5074	</result>
5075
5076	</desc>
5077	<param name="name" type="wstring" dir="in">
5078	<desc>Name of the storage controller to attach the device to.</desc>
5079	</param>
5080	<param name="controllerPort" type="long" dir="in">
5081	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5082	the primary controller and 1 specifies the secondary controller.
5083	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5084	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5085	</param>
5086	<param name="device" type="long" dir="in">
5087	<desc>Device slot in the given port to attach the device to. This is only
5088	relevant for IDE controllers, for which 0 specifies the master device and
5089	1 specifies the slave device. For all other controller types, this must
5090	be 0.</desc>
5091	</param>
5092	<param name="type" type="DeviceType" dir="in">
5093	<desc>Device type of the attached device. For media opened by
5094	<link to="IVirtualBox::openMedium" />, this must match the device type
5095	specified there.</desc>
5096	</param>
5097	<param name="medium" type="IMedium" dir="in">
5098	<desc>Medium to mount or @c null for an empty drive.</desc>
5099	</param>
5100	</method>
5101
5102	<method name="attachDeviceWithoutMedium">
5103	<desc>
5104	Attaches a device and optionally mounts a medium to the given storage
5105	controller (<link to="IStorageController" />, identified by @a name),
5106	at the indicated port and device.
5107
5108	This method is intended for managing storage devices in general while a
5109	machine is powered off. It can be used to attach and detach fixed
5110	and removable media. The following kind of media can be attached
5111	to a machine:
5112	<ul>
5113	<li>
5114	For fixed and removable media, you can pass in a medium that was
5115	previously opened using <link to="IVirtualBox::openMedium" />.
5116	</li>
5117
5118	<li>Only for storage devices supporting removable media (such as
5119	DVDs and floppies) with an empty drive or one of the medium objects listed
5120	in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
5121	arrays to indicate a host drive.
5122	For removable devices, you can also use <link to="IMachine::mountMedium"/>
5123	to change the media while the machine is running.
5124	</li>
5125	</ul>
5126
5127	In a VM's default configuration of virtual machines, the secondary
5128	master of the IDE controller is used for a CD/DVD drive.
5129	<link to="IMediumAttachment"/> will appear in the machine's list of medium
5130	attachments (see <link to="IMachine::mediumAttachments"/>).
5131
5132	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
5133	information about attaching media.
5134
5135	The specified device slot must not have a device attached to it,
5136	or this method will fail.
5137	<note>
5138	You cannot attach a device to a newly created machine until
5139	this machine's settings are saved to disk using
5140	<link to="#saveSettings"/>.
5141	</note>
5142	<note>
5143	If the medium is being attached indirectly, a new differencing medium
5144	will implicitly be created for it and attached instead. If the
5145	changes made to the machine settings (including this indirect
5146	attachment) are later cancelled using <link to="#discardSettings"/>,
5147	this implicitly created differencing medium will implicitly
5148	be deleted.
5149	</note>
5150
5151	<result name="E_INVALIDARG">
5152	SATA device, SATA port, IDE port or IDE slot out of range, or
5153	file or UUID not found.
5154	</result>
5155	<result name="VBOX_E_INVALID_OBJECT_STATE">
5156	Machine must be registered before media can be attached.
5157	</result>
5158	<result name="VBOX_E_INVALID_VM_STATE">
5159	Invalid machine state.
5160	</result>
5161	<result name="VBOX_E_OBJECT_IN_USE">
5162	A medium is already attached to this or another virtual machine.
5163	</result>
5164	</desc>
5165	<param name="name" type="wstring" dir="in">
5166	<desc>Name of the storage controller to attach the device to.</desc>
5167	</param>
5168	<param name="controllerPort" type="long" dir="in">
5169	<desc>Port to attach the device to. For an IDE controller, 0 specifies
5170	the primary controller and 1 specifies the secondary controller.
5171	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
5172	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
5173	</param>
5174	<param name="device" type="long" dir="in">
5175	<desc>Device slot in the given port to attach the device to. This is only
5176	relevant for IDE controllers, for which 0 specifies the master device and
5177	1 specifies the slave device. For all other controller types, this must
5178	be 0.</desc>
5179	</param>
5180	<param name="type" type="DeviceType" dir="in">
5181	<desc>Device type of the attached device. For media opened by
5182	<link to="IVirtualBox::openMedium" />, this must match the device type
5183	specified there.</desc>
5184	</param>
5185	</method>
5186
5187	<method name="detachDevice">
5188	<desc>
5189	Detaches the device attached to a device slot of the specified bus.
5190
5191	Detaching the device from the virtual machine is deferred. This means
5192	that the medium remains associated with the machine when this method
5193	returns and gets actually de-associated only after a successful
5194	<link to="#saveSettings"/> call. See <link to="IMedium"/>
5195	for more detailed information about attaching media.
5196
5197	<note>
5198	You cannot detach a device from a running machine.
5199	</note>
5200	<note>
5201	Detaching differencing media implicitly created by <link
5202	to="#attachDevice"/> for the indirect attachment using this
5203	method will <b>not</b> implicitly delete them. The
5204	<link to="IMedium::deleteStorage"/> operation should be
5205	explicitly performed by the caller after the medium is successfully
5206	detached and the settings are saved with
5207	<link to="#saveSettings"/>, if it is the desired action.
5208	</note>
5209
5210	<result name="VBOX_E_INVALID_VM_STATE">
5211	Attempt to detach medium from a running virtual machine.
5212	</result>
5213	<result name="VBOX_E_OBJECT_NOT_FOUND">
5214	No medium attached to given slot/bus.
5215	</result>
5216	<result name="VBOX_E_NOT_SUPPORTED">
5217	Medium format does not support storage deletion (only for implicitly
5218	created differencing media, should not happen).
5219	</result>
5220
5221	</desc>
5222	<param name="name" type="wstring" dir="in">
5223	<desc>Name of the storage controller to detach the medium from.</desc>
5224	</param>
5225	<param name="controllerPort" type="long" dir="in">
5226	<desc>Port number to detach the medium from.</desc>
5227	</param>
5228	<param name="device" type="long" dir="in">
5229	<desc>Device slot number to detach the medium from.</desc>
5230	</param>
5231	</method>
5232
5233	<method name="passthroughDevice">
5234	<desc>
5235	Sets the passthrough mode of an existing DVD device. Changing the
5236	setting while the VM is running is forbidden. The setting is only used
5237	if at VM start the device is configured as a host DVD drive, in all
5238	other cases it is ignored. The device must already exist; see
5239	<link to="IMachine::attachDevice"/> for how to attach a new device.
5240
5241	The @a controllerPort and @a device parameters specify the device slot and
5242	have have the same meaning as with <link to="IMachine::attachDevice" />.
5243
5244	<result name="E_INVALIDARG">
5245	SATA device, SATA port, IDE port or IDE slot out of range.
5246	</result>
5247	<result name="VBOX_E_INVALID_OBJECT_STATE">
5248	Attempt to modify an unregistered virtual machine.
5249	</result>
5250	<result name="VBOX_E_INVALID_VM_STATE">
5251	Invalid machine state.
5252	</result>
5253
5254	</desc>
5255	<param name="name" type="wstring" dir="in">
5256	<desc>Name of the storage controller.</desc>
5257	</param>
5258	<param name="controllerPort" type="long" dir="in">
5259	<desc>Storage controller port.</desc>
5260	</param>
5261	<param name="device" type="long" dir="in">
5262	<desc>Device slot in the given port.</desc>
5263	</param>
5264	<param name="passthrough" type="boolean" dir="in">
5265	<desc>New value for the passthrough setting.</desc>
5266	</param>
5267	</method>
5268
5269	<method name="temporaryEjectDevice">
5270	<desc>
5271	Sets the behavior for guest-triggered medium eject. In some situations
5272	it is desirable that such ejects update the VM configuration, and in
5273	others the eject should keep the VM configuration. The device must
5274	already exist; see <link to="IMachine::attachDevice"/> for how to
5275	attach a new device.
5276
5277	The @a controllerPort and @a device parameters specify the device slot and
5278	have have the same meaning as with <link to="IMachine::attachDevice" />.
5279
5280	<result name="E_INVALIDARG">
5281	SATA device, SATA port, IDE port or IDE slot out of range.
5282	</result>
5283	<result name="VBOX_E_INVALID_OBJECT_STATE">
5284	Attempt to modify an unregistered virtual machine.
5285	</result>
5286	<result name="VBOX_E_INVALID_VM_STATE">
5287	Invalid machine state.
5288	</result>
5289
5290	</desc>
5291	<param name="name" type="wstring" dir="in">
5292	<desc>Name of the storage controller.</desc>
5293	</param>
5294	<param name="controllerPort" type="long" dir="in">
5295	<desc>Storage controller port.</desc>
5296	</param>
5297	<param name="device" type="long" dir="in">
5298	<desc>Device slot in the given port.</desc>
5299	</param>
5300	<param name="temporaryEject" type="boolean" dir="in">
5301	<desc>New value for the eject behavior.</desc>
5302	</param>
5303	</method>
5304
5305	<method name="nonRotationalDevice">
5306	<desc>
5307	Sets a flag in the device information which indicates that the medium
5308	is not based on rotational technology, i.e. that the access times are
5309	more or less independent of the position on the medium. This may or may
5310	not be supported by a particular drive, and is silently ignored in the
5311	latter case. At the moment only hard disks (which is a misnomer in this
5312	context) accept this setting. Changing the setting while the VM is
5313	running is forbidden. The device must already exist; see
5314	<link to="IMachine::attachDevice"/> for how to attach a new device.
5315
5316	The @a controllerPort and @a device parameters specify the device slot and
5317	have have the same meaning as with <link to="IMachine::attachDevice" />.
5318
5319	<result name="E_INVALIDARG">
5320	SATA device, SATA port, IDE port or IDE slot out of range.
5321	</result>
5322	<result name="VBOX_E_INVALID_OBJECT_STATE">
5323	Attempt to modify an unregistered virtual machine.
5324	</result>
5325	<result name="VBOX_E_INVALID_VM_STATE">
5326	Invalid machine state.
5327	</result>
5328
5329	</desc>
5330	<param name="name" type="wstring" dir="in">
5331	<desc>Name of the storage controller.</desc>
5332	</param>
5333	<param name="controllerPort" type="long" dir="in">
5334	<desc>Storage controller port.</desc>
5335	</param>
5336	<param name="device" type="long" dir="in">
5337	<desc>Device slot in the given port.</desc>
5338	</param>
5339	<param name="nonRotational" type="boolean" dir="in">
5340	<desc>New value for the non-rotational device flag.</desc>
5341	</param>
5342	</method>
5343
5344	<method name="setAutoDiscardForDevice">
5345	<desc>
5346	Sets a flag in the device information which indicates that the medium
5347	supports discarding unsused blocks (called trimming for SATA or unmap
5348	for SCSI devices) .This may or may not be supported by a particular drive,
5349	and is silently ignored in the latter case. At the moment only hard disks
5350	(which is a misnomer in this context) accept this setting. Changing the
5351	setting while the VM is running is forbidden. The device must already
5352	exist; see <link to="IMachine::attachDevice"/> for how to attach a new
5353	device.
5354
5355	The @a controllerPort and @a device parameters specify the device slot and
5356	have have the same meaning as with <link to="IMachine::attachDevice" />.
5357
5358	<result name="E_INVALIDARG">
5359	SATA device, SATA port, SCSI port out of range.
5360	</result>
5361	<result name="VBOX_E_INVALID_OBJECT_STATE">
5362	Attempt to modify an unregistered virtual machine.
5363	</result>
5364	<result name="VBOX_E_INVALID_VM_STATE">
5365	Invalid machine state.
5366	</result>
5367
5368	</desc>
5369	<param name="name" type="wstring" dir="in">
5370	<desc>Name of the storage controller.</desc>
5371	</param>
5372	<param name="controllerPort" type="long" dir="in">
5373	<desc>Storage controller port.</desc>
5374	</param>
5375	<param name="device" type="long" dir="in">
5376	<desc>Device slot in the given port.</desc>
5377	</param>
5378	<param name="discard" type="boolean" dir="in">
5379	<desc>New value for the discard device flag.</desc>
5380	</param>
5381	</method>
5382
5383	<method name="setBandwidthGroupForDevice">
5384	<desc>
5385	Sets the bandwidth group of an existing storage device.
5386	The device must already exist; see <link to="IMachine::attachDevice"/>
5387	for how to attach a new device.
5388
5389	The @a controllerPort and @a device parameters specify the device slot and
5390	have have the same meaning as with <link to="IMachine::attachDevice" />.
5391
5392	<result name="E_INVALIDARG">
5393	SATA device, SATA port, IDE port or IDE slot out of range.
5394	</result>
5395	<result name="VBOX_E_INVALID_OBJECT_STATE">
5396	Attempt to modify an unregistered virtual machine.
5397	</result>
5398	<result name="VBOX_E_INVALID_VM_STATE">
5399	Invalid machine state.
5400	</result>
5401
5402	</desc>
5403	<param name="name" type="wstring" dir="in">
5404	<desc>Name of the storage controller.</desc>
5405	</param>
5406	<param name="controllerPort" type="long" dir="in">
5407	<desc>Storage controller port.</desc>
5408	</param>
5409	<param name="device" type="long" dir="in">
5410	<desc>Device slot in the given port.</desc>
5411	</param>
5412	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
5413	<desc>New value for the bandwidth group or @c null for no group.</desc>
5414	</param>
5415	</method>
5416
5417	<method name="setNoBandwidthGroupForDevice">
5418	<desc>
5419	Sets no bandwidth group for an existing storage device.
5420	The device must already exist; see <link to="IMachine::attachDevice"/>
5421	for how to attach a new device.
5422	The @a controllerPort and @a device parameters specify the device slot and
5423	have have the same meaning as with <link to="IMachine::attachDevice" />.
5424	<result name="E_INVALIDARG">
5425	SATA device, SATA port, IDE port or IDE slot out of range.
5426	</result>
5427	<result name="VBOX_E_INVALID_OBJECT_STATE">
5428	Attempt to modify an unregistered virtual machine.
5429	</result>
5430	<result name="VBOX_E_INVALID_VM_STATE">
5431	Invalid machine state.
5432	</result>
5433
5434	</desc>
5435	<param name="name" type="wstring" dir="in">
5436	<desc>Name of the storage controller.</desc>
5437	</param>
5438	<param name="controllerPort" type="long" dir="in">
5439	<desc>Storage controller port.</desc>
5440	</param>
5441	<param name="device" type="long" dir="in">
5442	<desc>Device slot in the given port.</desc>
5443	</param>
5444	</method>
5445
5446
5447	<method name="unmountMedium">
5448	<desc>
5449	Unmounts any currently mounted medium (<link to="IMedium" />,
5450	identified by the given UUID @a id) to the given storage controller
5451	(<link to="IStorageController" />, identified by @a name),
5452	at the indicated port and device. The device must already exist;
5453
5454	This method is intended only for managing removable media, where the
5455	device is fixed but media is changeable at runtime (such as DVDs
5456	and floppies). It cannot be used for fixed media such as hard disks.
5457
5458	The @a controllerPort and @a device parameters specify the device slot
5459	and have have the same meaning as with
5460	<link to="IMachine::attachDevice" />.
5461
5462	The specified device slot must have a medium mounted, which will be
5463	unmounted. If there is no mounted medium it will do nothing.
5464	See <link to="IMedium"/> for more detailed information about
5465	attaching/unmounting media.
5466
5467	<result name="E_INVALIDARG">
5468	SATA device, SATA port, IDE port or IDE slot out of range.
5469	</result>
5470	<result name="VBOX_E_INVALID_OBJECT_STATE">
5471	Attempt to unmount medium that is not removeable - not dvd or floppy.
5472	</result>
5473	<result name="VBOX_E_INVALID_VM_STATE">
5474	Invalid machine state.
5475	</result>
5476	<result name="VBOX_E_OBJECT_IN_USE">
5477	Medium already attached to this or another virtual machine.
5478	</result>
5479	<result name="VBOX_E_OBJECT_NOT_FOUND">
5480	Medium not attached to specified port, device, controller.
5481	</result>
5482
5483	</desc>
5484	<param name="name" type="wstring" dir="in">
5485	<desc>Name of the storage controller to unmount the medium from.</desc>
5486	</param>
5487	<param name="controllerPort" type="long" dir="in">
5488	<desc>Port to unmount the medium from.</desc>
5489	</param>
5490	<param name="device" type="long" dir="in">
5491	<desc>Device slot in the given port to unmount the medium from.</desc>
5492	</param>
5493	<param name="force" type="boolean" dir="in">
5494	<desc>Allows to force unmount of a medium which is locked by
5495	the device slot in the given port medium is attached to.</desc>
5496	</param>
5497	</method>
5498
5499	<method name="mountMedium">
5500	<desc>
5501	Mounts a medium (<link to="IMedium" />, identified
5502	by the given UUID @a id) to the given storage controller
5503	(<link to="IStorageController" />, identified by @a name),
5504	at the indicated port and device. The device must already exist;
5505	see <link to="IMachine::attachDevice"/> for how to attach a new device.
5506
5507	This method is intended only for managing removable media, where the
5508	device is fixed but media is changeable at runtime (such as DVDs
5509	and floppies). It cannot be used for fixed media such as hard disks.
5510
5511	The @a controllerPort and @a device parameters specify the device slot and
5512	have have the same meaning as with <link to="IMachine::attachDevice" />.
5513
5514	The specified device slot can have a medium mounted, which will be
5515	unmounted first. Specifying a zero UUID (or an empty string) for
5516	@a medium does just an unmount.
5517
5518	See <link to="IMedium"/> for more detailed information about
5519	attaching media.
5520
5521	<result name="E_INVALIDARG">
5522	SATA device, SATA port, IDE port or IDE slot out of range.
5523	</result>
5524	<result name="VBOX_E_INVALID_OBJECT_STATE">
5525	Attempt to attach medium to an unregistered virtual machine.
5526	</result>
5527	<result name="VBOX_E_INVALID_VM_STATE">
5528	Invalid machine state.
5529	</result>
5530	<result name="VBOX_E_OBJECT_IN_USE">
5531	Medium already attached to this or another virtual machine.
5532	</result>
5533
5534	</desc>
5535	<param name="name" type="wstring" dir="in">
5536	<desc>Name of the storage controller to attach the medium to.</desc>
5537	</param>
5538	<param name="controllerPort" type="long" dir="in">
5539	<desc>Port to attach the medium to.</desc>
5540	</param>
5541	<param name="device" type="long" dir="in">
5542	<desc>Device slot in the given port to attach the medium to.</desc>
5543	</param>
5544	<param name="medium" type="IMedium" dir="in">
5545	<desc>Medium to mount or @c null for an empty drive.</desc>
5546	</param>
5547	<param name="force" type="boolean" dir="in">
5548	<desc>Allows to force unmount/mount of a medium which is locked by
5549	the device slot in the given port to attach the medium to.</desc>
5550	</param>
5551	</method>
5552
5553	<method name="getMedium" const="yes">
5554	<desc>
5555	Returns the virtual medium attached to a device slot of the specified
5556	bus.
5557
5558	Note that if the medium was indirectly attached by
5559	<link to="#mountMedium"/> to the given device slot then this
5560	method will return not the same object as passed to the
5561	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5562	more detailed information about mounting a medium.
5563
5564	<result name="VBOX_E_OBJECT_NOT_FOUND">
5565	No medium attached to given slot/bus.
5566	</result>
5567
5568	</desc>
5569	<param name="name" type="wstring" dir="in">
5570	<desc>Name of the storage controller the medium is attached to.</desc>
5571	</param>
5572	<param name="controllerPort" type="long" dir="in">
5573	<desc>Port to query.</desc>
5574	</param>
5575	<param name="device" type="long" dir="in">
5576	<desc>Device slot in the given port to query.</desc>
5577	</param>
5578	<param name="medium" type="IMedium" dir="return">
5579	<desc>Attached medium object.</desc>
5580	</param>
5581	</method>
5582
5583	<method name="getMediumAttachmentsOfController" const="yes">
5584	<desc>
5585	Returns an array of medium attachments which are attached to the
5586	the controller with the given name.
5587
5588	<result name="VBOX_E_OBJECT_NOT_FOUND">
5589	A storage controller with given name doesn't exist.
5590	</result>
5591	</desc>
5592	<param name="name" type="wstring" dir="in"/>
5593	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5594	</method>
5595
5596	<method name="getMediumAttachment" const="yes">
5597	<desc>
5598	Returns a medium attachment which corresponds to the controller with
5599	the given name, on the given port and device slot.
5600
5601	<result name="VBOX_E_OBJECT_NOT_FOUND">
5602	No attachment exists for the given controller/port/device combination.
5603	</result>
5604	</desc>
5605	<param name="name" type="wstring" dir="in"/>
5606	<param name="controllerPort" type="long" dir="in"/>
5607	<param name="device" type="long" dir="in"/>
5608	<param name="attachment" type="IMediumAttachment" dir="return"/>
5609	</method>
5610
5611	<method name="attachHostPCIDevice">
5612	<desc>
5613	Attaches host PCI device with the given (host) PCI address to the
5614	PCI bus of the virtual machine. Please note, that this operation
5615	is two phase, as real attachment will happen when VM will start,
5616	and most information will be delivered as IHostPCIDevicePlugEvent
5617	on IVirtualBox event source.
5618
5619	<see><link to="IHostPCIDevicePlugEvent"/></see>
5620
5621	<result name="VBOX_E_INVALID_VM_STATE">
5622	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5623	</result>
5624	<result name="VBOX_E_PDM_ERROR">
5625	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5626	</result>
5627	<result name="VBOX_E_NOT_SUPPORTED">
5628	Hardware or host OS doesn't allow PCI device passthrought.
5629	</result>
5630	</desc>
5631	<param name="hostAddress" type="long" dir="in">
5632	<desc>Address of the host PCI device.</desc>
5633	</param>
5634	<param name="desiredGuestAddress" type="long" dir="in">
5635	<desc>Desired position of this device on guest PCI bus.</desc>
5636	</param>
5637	<param name="tryToUnbind" type="boolean" dir="in">
5638	<desc>If VMM shall try to unbind existing drivers from the
5639	device before attaching it to the guest.</desc>
5640	</param>
5641	</method>
5642
5643	<method name="detachHostPCIDevice">
5644	<desc>
5645	Detach host PCI device from the virtual machine.
5646	Also HostPCIDevicePlugEvent on IVirtualBox event source
5647	will be delivered. As currently we don't support hot device
5648	unplug, IHostPCIDevicePlugEvent event is delivered immediately.
5649
5650	<see><link to="IHostPCIDevicePlugEvent"/></see>
5651
5652	<result name="VBOX_E_INVALID_VM_STATE">
5653	Virtual machine state is not stopped (PCI hotplug not yet implemented).
5654	</result>
5655	<result name="VBOX_E_OBJECT_NOT_FOUND">
5656	This host device is not attached to this machine.
5657	</result>
5658	<result name="VBOX_E_PDM_ERROR">
5659	Virtual machine does not have a PCI controller allowing attachment of physical devices.
5660	</result>
5661	<result name="VBOX_E_NOT_SUPPORTED">
5662	Hardware or host OS doesn't allow PCI device passthrought.
5663	</result>
5664	</desc>
5665	<param name="hostAddress" type="long" dir="in">
5666	<desc>Address of the host PCI device.</desc>
5667	</param>
5668	</method>
5669
5670	<method name="getNetworkAdapter" const="yes">
5671	<desc>
5672	Returns the network adapter associated with the given slot.
5673	Slots are numbered sequentially, starting with zero. The total
5674	number of adapters per machine is defined by the
5675	<link to="ISystemProperties::getMaxNetworkAdapters"/> property,
5676	so the maximum slot number is one less than that property's value.
5677
5678	<result name="E_INVALIDARG">
5679	Invalid @a slot number.
5680	</result>
5681
5682	</desc>
5683	<param name="slot" type="unsigned long" dir="in"/>
5684	<param name="adapter" type="INetworkAdapter" dir="return"/>
5685	</method>
5686
5687	<method name="addStorageController">
5688	<desc>
5689	Adds a new storage controller (SCSI, SAS or SATA controller) to the
5690	machine and returns it as an instance of
5691	<link to="IStorageController" />.
5692
5693	@a name identifies the controller for subsequent calls such as
5694	<link to="#getStorageControllerByName" />,
5695	<link to="#getStorageControllerByInstance" />,
5696	<link to="#removeStorageController" />,
5697	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5698
5699	After the controller has been added, you can set its exact
5700	type by setting the <link to="IStorageController::controllerType" />.
5701
5702	<result name="VBOX_E_OBJECT_IN_USE">
5703	A storage controller with given name exists already.
5704	</result>
5705	<result name="E_INVALIDARG">
5706	Invalid @a controllerType.
5707	</result>
5708	</desc>
5709	<param name="name" type="wstring" dir="in"/>
5710	<param name="connectionType" type="StorageBus" dir="in"/>
5711	<param name="controller" type="IStorageController" dir="return"/>
5712	</method>
5713
5714	<method name="getStorageControllerByName" const="yes">
5715	<desc>
5716	Returns a storage controller with the given name.
5717
5718	<result name="VBOX_E_OBJECT_NOT_FOUND">
5719	A storage controller with given name doesn't exist.
5720	</result>
5721	</desc>
5722	<param name="name" type="wstring" dir="in"/>
5723	<param name="storageController" type="IStorageController" dir="return"/>
5724	</method>
5725
5726	<method name="getStorageControllerByInstance" const="yes">
5727	<desc>
5728	Returns a storage controller with the given instance number.
5729
5730	<result name="VBOX_E_OBJECT_NOT_FOUND">
5731	A storage controller with given instance number doesn't exist.
5732	</result>
5733	</desc>
5734	<param name="instance" type="unsigned long" dir="in"/>
5735	<param name="storageController" type="IStorageController" dir="return"/>
5736	</method>
5737
5738	<method name="removeStorageController">
5739	<desc>
5740	Removes a storage controller from the machine with all devices attached to it.
5741
5742	<result name="VBOX_E_OBJECT_NOT_FOUND">
5743	A storage controller with given name doesn't exist.
5744	</result>
5745	<result name="VBOX_E_NOT_SUPPORTED">
5746	Medium format does not support storage deletion (only for implicitly
5747	created differencing media, should not happen).
5748	</result>
5749	</desc>
5750	<param name="name" type="wstring" dir="in"/>
5751	</method>
5752
5753	<method name="setStorageControllerBootable">
5754	<desc>
5755	Sets the bootable flag of the storage controller with the given name.
5756
5757	<result name="VBOX_E_OBJECT_NOT_FOUND">
5758	A storage controller with given name doesn't exist.
5759	</result>
5760	<result name="VBOX_E_OBJECT_IN_USE">
5761	Another storage controller is marked as bootable already.
5762	</result>
5763	</desc>
5764	<param name="name" type="wstring" dir="in"/>
5765	<param name="bootable" type="boolean" dir="in"/>
5766	</method>
5767
5768	<method name="getSerialPort" const="yes">
5769	<desc>
5770	Returns the serial port associated with the given slot.
5771	Slots are numbered sequentially, starting with zero. The total
5772	number of serial ports per machine is defined by the
5773	<link to="ISystemProperties::serialPortCount"/> property,
5774	so the maximum slot number is one less than that property's value.
5775
5776	<result name="E_INVALIDARG">
5777	Invalid @a slot number.
5778	</result>
5779
5780	</desc>
5781	<param name="slot" type="unsigned long" dir="in"/>
5782	<param name="port" type="ISerialPort" dir="return"/>
5783	</method>
5784
5785	<method name="getParallelPort" const="yes">
5786	<desc>
5787	Returns the parallel port associated with the given slot.
5788	Slots are numbered sequentially, starting with zero. The total
5789	number of parallel ports per machine is defined by the
5790	<link to="ISystemProperties::parallelPortCount"/> property,
5791	so the maximum slot number is one less than that property's value.
5792
5793	<result name="E_INVALIDARG">
5794	Invalid @a slot number.
5795	</result>
5796
5797	</desc>
5798	<param name="slot" type="unsigned long" dir="in"/>
5799	<param name="port" type="IParallelPort" dir="return"/>
5800	</method>
5801
5802	<method name="getExtraDataKeys">
5803	<desc>
5804	Returns an array representing the machine-specific extra data keys
5805	which currently have values defined.
5806	</desc>
5807	<param name="keys" type="wstring" dir="return" safearray="yes">
5808	<desc>Array of extra data keys.</desc>
5809	</param>
5810	</method>
5811
5812	<method name="getExtraData">
5813	<desc>
5814	Returns associated machine-specific extra data.
5815
5816	If the requested data @a key does not exist, this function will
5817	succeed and return an empty string in the @a value argument.
5818
5819	<result name="VBOX_E_FILE_ERROR">
5820	Settings file not accessible.
5821	</result>
5822	<result name="VBOX_E_XML_ERROR">
5823	Could not parse the settings file.
5824	</result>
5825
5826	</desc>
5827	<param name="key" type="wstring" dir="in">
5828	<desc>Name of the data key to get.</desc>
5829	</param>
5830	<param name="value" type="wstring" dir="return">
5831	<desc>Value of the requested data key.</desc>
5832	</param>
5833	</method>
5834
5835	<method name="setExtraData">
5836	<desc>
5837	Sets associated machine-specific extra data.
5838
5839	If you pass @c null or an empty string as a key @a value, the given
5840	@a key will be deleted.
5841
5842	<note>
5843	Before performing the actual data change, this method will ask all
5844	registered listeners using the
5845	<link to="IExtraDataCanChangeEvent"/>
5846	notification for a permission. If one of the listeners refuses the
5847	new value, the change will not be performed.
5848	</note>
5849	<note>
5850	On success, the
5851	<link to="IExtraDataChangedEvent"/> notification
5852	is called to inform all registered listeners about a successful data
5853	change.
5854	</note>
5855	<note>
5856	This method can be called outside the machine session and therefore
5857	it's a caller's responsibility to handle possible race conditions
5858	when several clients change the same key at the same time.
5859	</note>
5860
5861	<result name="VBOX_E_FILE_ERROR">
5862	Settings file not accessible.
5863	</result>
5864	<result name="VBOX_E_XML_ERROR">
5865	Could not parse the settings file.
5866	</result>
5867
5868	</desc>
5869	<param name="key" type="wstring" dir="in">
5870	<desc>Name of the data key to set.</desc>
5871	</param>
5872	<param name="value" type="wstring" dir="in">
5873	<desc>Value to assign to the key.</desc>
5874	</param>
5875	</method>
5876
5877	<method name="getCPUProperty" const="yes">
5878	<desc>
5879	Returns the virtual CPU boolean value of the specified property.
5880
5881	<result name="E_INVALIDARG">
5882	Invalid property.
5883	</result>
5884
5885	</desc>
5886	<param name="property" type="CPUPropertyType" dir="in">
5887	<desc>
5888	Property type to query.
5889	</desc>
5890	</param>
5891	<param name="value" type="boolean" dir="return">
5892	<desc>
5893	Property value.
5894	</desc>
5895	</param>
5896	</method>
5897
5898	<method name="setCPUProperty">
5899	<desc>
5900	Sets the virtual CPU boolean value of the specified property.
5901
5902	<result name="E_INVALIDARG">
5903	Invalid property.
5904	</result>
5905
5906	</desc>
5907	<param name="property" type="CPUPropertyType" dir="in">
5908	<desc>
5909	Property type to query.
5910	</desc>
5911	</param>
5912	<param name="value" type="boolean" dir="in">
5913	<desc>
5914	Property value.
5915	</desc>
5916	</param>
5917	</method>
5918
5919	<method name="getCPUIDLeaf" const="yes">
5920	<desc>
5921	Returns the virtual CPU cpuid information for the specified leaf.
5922
5923	Currently supported index values for cpuid:
5924	Standard CPUID leafs: 0 - 0xA
5925	Extended CPUID leafs: 0x80000000 - 0x8000000A
5926
5927	See the Intel and AMD programmer's manuals for detailed information
5928	about the cpuid instruction and its leafs.
5929	<result name="E_INVALIDARG">
5930	Invalid id.
5931	</result>
5932
5933	</desc>
5934	<param name="id" type="unsigned long" dir="in">
5935	<desc>
5936	CPUID leaf index.
5937	</desc>
5938	</param>
5939	<param name="valEax" type="unsigned long" dir="out">
5940	<desc>
5941	CPUID leaf value for register eax.
5942	</desc>
5943	</param>
5944	<param name="valEbx" type="unsigned long" dir="out">
5945	<desc>
5946	CPUID leaf value for register ebx.
5947	</desc>
5948	</param>
5949	<param name="valEcx" type="unsigned long" dir="out">
5950	<desc>
5951	CPUID leaf value for register ecx.
5952	</desc>
5953	</param>
5954	<param name="valEdx" type="unsigned long" dir="out">
5955	<desc>
5956	CPUID leaf value for register edx.
5957	</desc>
5958	</param>
5959	</method>
5960
5961	<method name="setCPUIDLeaf">
5962	<desc>
5963	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5964	are not passed unmodified. VirtualBox clears features that it doesn't support.
5965
5966	Currently supported index values for cpuid:
5967	Standard CPUID leafs: 0 - 0xA
5968	Extended CPUID leafs: 0x80000000 - 0x8000000A
5969
5970	See the Intel and AMD programmer's manuals for detailed information
5971	about the cpuid instruction and its leafs.
5972
5973	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5974	random crashes inside VMs.
5975	<result name="E_INVALIDARG">
5976	Invalid id.
5977	</result>
5978
5979	</desc>
5980	<param name="id" type="unsigned long" dir="in">
5981	<desc>
5982	CPUID leaf index.
5983	</desc>
5984	</param>
5985	<param name="valEax" type="unsigned long" dir="in">
5986	<desc>
5987	CPUID leaf value for register eax.
5988	</desc>
5989	</param>
5990	<param name="valEbx" type="unsigned long" dir="in">
5991	<desc>
5992	CPUID leaf value for register ebx.
5993	</desc>
5994	</param>
5995	<param name="valEcx" type="unsigned long" dir="in">
5996	<desc>
5997	CPUID leaf value for register ecx.
5998	</desc>
5999	</param>
6000	<param name="valEdx" type="unsigned long" dir="in">
6001	<desc>
6002	CPUID leaf value for register edx.
6003	</desc>
6004	</param>
6005	</method>
6006
6007	<method name="removeCPUIDLeaf">
6008	<desc>
6009	Removes the virtual CPU cpuid leaf for the specified index
6010
6011	<result name="E_INVALIDARG">
6012	Invalid id.
6013	</result>
6014
6015	</desc>
6016	<param name="id" type="unsigned long" dir="in">
6017	<desc>
6018	CPUID leaf index.
6019	</desc>
6020	</param>
6021	</method>
6022
6023	<method name="removeAllCPUIDLeaves">
6024	<desc>
6025	Removes all the virtual CPU cpuid leaves
6026	</desc>
6027	</method>
6028
6029	<method name="getHWVirtExProperty" const="yes">
6030	<desc>
6031	Returns the value of the specified hardware virtualization boolean property.
6032
6033	<result name="E_INVALIDARG">
6034	Invalid property.
6035	</result>
6036
6037	</desc>
6038	<param name="property" type="HWVirtExPropertyType" dir="in">
6039	<desc>
6040	Property type to query.
6041	</desc>
6042	</param>
6043	<param name="value" type="boolean" dir="return">
6044	<desc>
6045	Property value.
6046	</desc>
6047	</param>
6048	</method>
6049
6050	<method name="setHWVirtExProperty">
6051	<desc>
6052	Sets a new value for the specified hardware virtualization boolean property.
6053
6054	<result name="E_INVALIDARG">
6055	Invalid property.
6056	</result>
6057
6058	</desc>
6059	<param name="property" type="HWVirtExPropertyType" dir="in">
6060	<desc>
6061	Property type to set.
6062	</desc>
6063	</param>
6064	<param name="value" type="boolean" dir="in">
6065	<desc>
6066	New property value.
6067	</desc>
6068	</param>
6069	</method>
6070
6071	<method name="saveSettings">
6072	<desc>
6073	Saves any changes to machine settings made since the session
6074	has been opened or a new machine has been created, or since the
6075	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
6076	For registered machines, new settings become visible to all
6077	other VirtualBox clients after successful invocation of this
6078	method.
6079	<note>
6080	The method sends <link to="IMachineDataChangedEvent"/>
6081	notification event after the configuration has been successfully
6082	saved (only for registered machines).
6083	</note>
6084	<note>
6085	Calling this method is only valid on instances returned
6086	by <link to="ISession::machine"/> and on new machines
6087	created by <link to="IVirtualBox::createMachine"/> but not
6088	yet registered, or on unregistered machines after calling
6089	<link to="IMachine::unregister"/>.
6090	</note>
6091
6092	<result name="VBOX_E_FILE_ERROR">
6093	Settings file not accessible.
6094	</result>
6095	<result name="VBOX_E_XML_ERROR">
6096	Could not parse the settings file.
6097	</result>
6098	<result name="E_ACCESSDENIED">
6099	Modification request refused.
6100	</result>
6101
6102	</desc>
6103	</method>
6104
6105	<method name="discardSettings">
6106	<desc>
6107	Discards any changes to the machine settings made since the session
6108	has been opened or since the last call to <link to="#saveSettings"/>
6109	or <link to="#discardSettings"/>.
6110	<note>
6111	Calling this method is only valid on instances returned
6112	by <link to="ISession::machine"/> and on new machines
6113	created by <link to="IVirtualBox::createMachine"/> or
6114	opened by <link to="IVirtualBox::openMachine"/> but not
6115	yet registered, or on unregistered machines after calling
6116	<link to="IMachine::unregister"/>.
6117	</note>
6118
6119	<result name="VBOX_E_INVALID_VM_STATE">
6120	Virtual machine is not mutable.
6121	</result>
6122
6123	</desc>
6124	</method>
6125
6126	<method name="unregister">
6127	<desc>
6128	Unregisters a machine previously registered with
6129	<link to="IVirtualBox::registerMachine"/> and optionally do additional
6130	cleanup before the machine is unregistered.
6131
6132	This method does not delete any files. It only changes the machine configuration and
6133	the list of registered machines in the VirtualBox object. To delete the files which
6134	belonged to the machine, including the XML file of the machine itself, call
6135	<link to="#deleteConfig"/>, optionally with the array of IMedium objects which was returned
6136	from this method.
6137
6138	How thoroughly this method cleans up the machine configuration before unregistering
6139	the machine depends on the @a cleanupMode argument.
6140
6141	<ul>
6142	<li>With "UnregisterOnly", the machine will only be unregistered, but no additional
6143	cleanup will be performed. The call will fail if the machine is in "Saved" state
6144	or has any snapshots or any media attached (see <link to="IMediumAttachment" />).
6145	It is the responsibility of the caller to delete all such configuration in this mode.
6146	In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
6147	which it replaces.</li>
6148	<li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
6149	state or if it has snapshots or media attached. All media attached to the current machine
6150	state or in snapshots will be detached. No medium objects will be returned;
6151	all of the machine's media will remain open.</li>
6152	<li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
6153	except that all the hard disk medium objects which were detached from the machine will
6154	be returned as an array. This allows for quickly passing them to the <link to="#deleteConfig" />
6155	API for closing and deletion.</li>
6156	<li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
6157	that all media will be returned in the array, including removable media like DVDs and
6158	floppies. This might be useful if the user wants to inspect in detail which media were
6159	attached to the machine. Be careful when passing the media array to <link to="#deleteConfig" />
6160	in that case because users will typically want to preserve ISO and RAW image files.</li>
6161	</ul>
6162
6163	A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
6164	resulting IMedium array to <link to="#deleteConfig"/>. This way, the machine is completely
6165	deleted with all its saved states and hard disk images, but images for removable
6166	drives (such as ISO and RAW files) will remain on disk.
6167
6168	This API does not verify whether the media files returned in the array are still
6169	attached to other machines (i.e. shared between several machines). If such a shared
6170	image is passed to <link to="#deleteConfig" /> however, closing the image will fail there
6171	and the image will be silently skipped.
6172
6173	This API may, however, move media from this machine's media registry to other media
6174	registries (see <link to="IMedium" /> for details on media registries). For machines
6175	created with VirtualBox 4.0 or later, if media from this machine's media registry
6176	are also attached to another machine (shared attachments), each such medium will be
6177	moved to another machine's registry. This is because without this machine's media
6178	registry, the other machine cannot find its media any more and would become inaccessible.
6179
6180	This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
6181	before unregistering it. It may also silently call <link to="#saveSettings"/> on other machines
6182	if media are moved to other machines' media registries.
6183
6184	After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
6185	is fired.
6186
6187	The call will fail if the machine is currently locked (see <link to="ISession" />).
6188
6189	<note>
6190	If the given machine is inaccessible (see <link to="#accessible"/>), it
6191	will be unregistered and fully uninitialized right afterwards. As a result,
6192	the returned machine object will be unusable and an attempt to call
6193	<b>any</b> method will return the "Object not ready" error.
6194	</note>
6195
6196	<result name="VBOX_E_INVALID_OBJECT_STATE">
6197	Machine is currently locked for a session.
6198	</result>
6199	</desc>
6200
6201	<param name="cleanupMode" type="CleanupMode" dir="in">
6202	<desc>How to clean up after the machine has been unregistered.</desc>
6203	</param>
6204	<param name="media" type="IMedium" safearray="yes" dir="return">
6205	<desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
6206	</param>
6207	</method>
6208
6209	<method name="deleteConfig">
6210	<desc>
6211	Deletes the files associated with this machine from disk. If medium objects are passed
6212	in with the @a aMedia argument, they are closed and, if closing was successful, their
6213	storage files are deleted as well. For convenience, this array of media files can be
6214	the same as the one returned from a previous <link to="#unregister" /> call.
6215
6216	This method must only be called on machines which are either write-locked (i.e. on instances
6217	returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
6218	registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
6219	<link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
6220
6221	The following files will be deleted by this method:
6222	<ul>
6223	<li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
6224	argument other than "UnregisterOnly", this will delete all saved state files that
6225	the machine had in use; possibly one if the machine was in "Saved" state and one
6226	for each online snapshot that the machine had.</li>
6227	<li>On each medium object passed in the @a aMedia array, this will call
6228	<link to="IMedium::close" />. If that succeeds, this will attempt to delete the
6229	medium's storage on disk. Since the <link to="IMedium::close"/> call will fail if the medium is still
6230	in use, e.g. because it is still attached to a second machine; in that case the
6231	storage will not be deleted.</li>
6232	<li>Finally, the machine's own XML file will be deleted.</li>
6233	</ul>
6234
6235	Since deleting large disk image files can be a time-consuming I/O operation, this
6236	method operates asynchronously and returns an IProgress object to allow the caller
6237	to monitor the progress. There will be one sub-operation for each file that is
6238	being deleted (saved state or medium storage file).
6239
6240	<note>
6241	<link to="#settingsModified"/> will return @c true after this
6242	method successfully returns.
6243	</note>
6244
6245	<result name="VBOX_E_INVALID_VM_STATE">
6246	Machine is registered but not write-locked.
6247	</result>
6248	<result name="VBOX_E_IPRT_ERROR">
6249	Could not delete the settings file.
6250	</result>
6251	</desc>
6252	<param name="media" type="IMedium" safearray="yes" dir="in">
6253	<desc>List of media to be closed and whose storage files will be deleted.</desc>
6254	</param>
6255	<param name="progress" type="IProgress" dir="return">
6256	<desc>Progress object to track the operation completion.</desc>
6257	</param>
6258	</method>
6259
6260	<method name="exportTo">
6261	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
6262	steps required to export VirtualBox machines to OVF.
6263	</desc>
6264
6265	<param name="appliance" type="IAppliance" dir="in">
6266	<desc>Appliance to export this machine to.</desc>
6267	</param>
6268	<param name="location" type="wstring" dir="in">
6269	<desc>The target location.</desc>
6270	</param>
6271	<param name="description" type="IVirtualSystemDescription" dir="return">
6272	<desc>VirtualSystemDescription object which is created for this machine.</desc>
6273	</param>
6274	</method >
6275
6276	<method name="findSnapshot">
6277	<desc>
6278	Returns a snapshot of this machine with the given name or UUID.
6279
6280	Returns a snapshot of this machine with the given UUID.
6281	A @c null argument can be used to obtain the first snapshot
6282	taken on this machine. To traverse the whole tree of snapshots
6283	starting from the root, inspect the root snapshot's
6284	<link to="ISnapshot::children" /> attribute and recurse over those children.
6285
6286	<result name="VBOX_E_OBJECT_NOT_FOUND">
6287	Virtual machine has no snapshots or snapshot not found.
6288	</result>
6289
6290	</desc>
6291	<param name="nameOrId" type="wstring" dir="in">
6292	<desc>What to search for. Name or UUID of the snapshot to find</desc>
6293	</param>
6294	<param name="snapshot" type="ISnapshot" dir="return">
6295	<desc>Snapshot object with the given name.</desc>
6296	</param>
6297	</method>
6298
6299	<method name="createSharedFolder">
6300	<desc>
6301	Creates a new permanent shared folder by associating the given logical
6302	name with the given host path, adds it to the collection of shared
6303	folders and starts sharing it. Refer to the description of
6304	<link to="ISharedFolder"/> to read more about logical names.
6305
6306	<result name="VBOX_E_OBJECT_IN_USE">
6307	Shared folder already exists.
6308	</result>
6309	<result name="VBOX_E_FILE_ERROR">
6310	Shared folder @a hostPath not accessible.
6311	</result>
6312
6313	</desc>
6314	<param name="name" type="wstring" dir="in">
6315	<desc>Unique logical name of the shared folder.</desc>
6316	</param>
6317	<param name="hostPath" type="wstring" dir="in">
6318	<desc>Full path to the shared folder in the host file system.</desc>
6319	</param>
6320	<param name="writable" type="boolean" dir="in">
6321	<desc>Whether the share is writable or readonly.</desc>
6322	</param>
6323	<param name="automount" type="boolean" dir="in">
6324	<desc>Whether the share gets automatically mounted by the guest
6325	or not.</desc>
6326	</param>
6327	</method>
6328
6329	<method name="removeSharedFolder">
6330	<desc>
6331	Removes the permanent shared folder with the given name previously
6332	created by <link to="#createSharedFolder"/> from the collection of
6333	shared folders and stops sharing it.
6334
6335	<result name="VBOX_E_INVALID_VM_STATE">
6336	Virtual machine is not mutable.
6337	</result>
6338	<result name="VBOX_E_OBJECT_NOT_FOUND">
6339	Shared folder @a name does not exist.
6340	</result>
6341
6342	</desc>
6343	<param name="name" type="wstring" dir="in">
6344	<desc>Logical name of the shared folder to remove.</desc>
6345	</param>
6346	</method>
6347
6348	<method name="canShowConsoleWindow">
6349	<desc>
6350	Returns @c true if the VM console process can activate the
6351	console window and bring it to foreground on the desktop of
6352	the host PC.
6353	<note>
6354	This method will fail if a session for this machine is not
6355	currently open.
6356	</note>
6357
6358	<result name="VBOX_E_INVALID_VM_STATE">
6359	Machine session is not open.
6360	</result>
6361
6362	</desc>
6363	<param name="canShow" type="boolean" dir="return">
6364	<desc>
6365	@c true if the console window can be shown and @c false otherwise.
6366	</desc>
6367	</param>
6368	</method>
6369
6370	<method name="showConsoleWindow">
6371	<desc>
6372	Activates the console window and brings it to foreground on
6373	the desktop of the host PC. Many modern window managers on
6374	many platforms implement some sort of focus stealing
6375	prevention logic, so that it may be impossible to activate
6376	a window without the help of the currently active
6377	application. In this case, this method will return a non-zero
6378	identifier that represents the top-level window of the VM
6379	console process. The caller, if it represents a currently
6380	active process, is responsible to use this identifier (in a
6381	platform-dependent manner) to perform actual window
6382	activation.
6383	<note>
6384	This method will fail if a session for this machine is not
6385	currently open.
6386	</note>
6387
6388	<result name="VBOX_E_INVALID_VM_STATE">
6389	Machine session is not open.
6390	</result>
6391
6392	</desc>
6393	<param name="winId" type="long long" dir="return">
6394	<desc>
6395	Platform-dependent identifier of the top-level VM console
6396	window, or zero if this method has performed all actions
6397	necessary to implement the <i>show window</i> semantics for
6398	the given platform and/or VirtualBox front-end.
6399	</desc>
6400	</param>
6401	</method>
6402
6403	<method name="getGuestProperty" const="yes">
6404	<desc>
6405	Reads an entry from the machine's guest property store.
6406
6407	<result name="VBOX_E_INVALID_VM_STATE">
6408	Machine session is not open.
6409	</result>
6410
6411	</desc>
6412	<param name="name" type="wstring" dir="in">
6413	<desc>
6414	The name of the property to read.
6415	</desc>
6416	</param>
6417	<param name="value" type="wstring" dir="out">
6418	<desc>
6419	The value of the property. If the property does not exist then this
6420	will be empty.
6421	</desc>
6422	</param>
6423	<param name="timestamp" type="long long" dir="out">
6424	<desc>
6425	The time at which the property was last modified, as seen by the
6426	server process.
6427	</desc>
6428	</param>
6429	<param name="flags" type="wstring" dir="out">
6430	<desc>
6431	Additional property parameters, passed as a comma-separated list of
6432	"name=value" type entries.
6433	</desc>
6434	</param>
6435	</method>
6436
6437	<method name="getGuestPropertyValue" const="yes">
6438	<desc>
6439	Reads a value from the machine's guest property store.
6440
6441	<result name="VBOX_E_INVALID_VM_STATE">
6442	Machine session is not open.
6443	</result>
6444
6445	</desc>
6446	<param name="property" type="wstring" dir="in">
6447	<desc>
6448	The name of the property to read.
6449	</desc>
6450	</param>
6451	<param name="value" type="wstring" dir="return">
6452	<desc>
6453	The value of the property. If the property does not exist then this
6454	will be empty.
6455	</desc>
6456	</param>
6457	</method>
6458
6459	<method name="getGuestPropertyTimestamp" const="yes">
6460	<desc>
6461	Reads a property timestamp from the machine's guest property store.
6462
6463	<result name="VBOX_E_INVALID_VM_STATE">
6464	Machine session is not open.
6465	</result>
6466
6467	</desc>
6468	<param name="property" type="wstring" dir="in">
6469	<desc>
6470	The name of the property to read.
6471	</desc>
6472	</param>
6473	<param name="value" type="long long" dir="return">
6474	<desc>
6475	The timestamp. If the property does not exist then this will be
6476	empty.
6477	</desc>
6478	</param>
6479	</method>
6480
6481	<method name="setGuestProperty">
6482	<desc>
6483	Sets, changes or deletes an entry in the machine's guest property
6484	store.
6485
6486	<result name="E_ACCESSDENIED">
6487	Property cannot be changed.
6488	</result>
6489	<result name="E_INVALIDARG">
6490	Invalid @a flags.
6491	</result>
6492	<result name="VBOX_E_INVALID_VM_STATE">
6493	Virtual machine is not mutable or session not open.
6494	</result>
6495	<result name="VBOX_E_INVALID_OBJECT_STATE">
6496	Cannot set transient property when machine not running.
6497	</result>
6498
6499	</desc>
6500	<param name="property" type="wstring" dir="in">
6501	<desc>
6502	The name of the property to set, change or delete.
6503	</desc>
6504	</param>
6505	<param name="value" type="wstring" dir="in">
6506	<desc>
6507	The new value of the property to set, change or delete. If the
6508	property does not yet exist and value is non-empty, it will be
6509	created. If the value is @c null or empty, the property will be
6510	deleted if it exists.
6511	</desc>
6512	</param>
6513	<param name="flags" type="wstring" dir="in">
6514	<desc>
6515	Additional property parameters, passed as a comma-separated list of
6516	"name=value" type entries.
6517	</desc>
6518	</param>
6519	</method>
6520
6521	<method name="setGuestPropertyValue">
6522	<desc>
6523	Sets or changes a value in the machine's guest property
6524	store. The flags field will be left unchanged or created empty for a
6525	new property.
6526
6527	<result name="E_ACCESSDENIED">
6528	Property cannot be changed.
6529	</result>
6530	<result name="VBOX_E_INVALID_VM_STATE">
6531	Virtual machine is not mutable or session not open.
6532	</result>
6533	<result name="VBOX_E_INVALID_OBJECT_STATE">
6534	Cannot set transient property when machine not running.
6535	</result>
6536	</desc>
6537
6538	<param name="property" type="wstring" dir="in">
6539	<desc>
6540	The name of the property to set or change.
6541	</desc>
6542	</param>
6543	<param name="value" type="wstring" dir="in">
6544	<desc>
6545	The new value of the property to set or change. If the
6546	property does not yet exist and value is non-empty, it will be
6547	created.
6548	</desc>
6549	</param>
6550	</method>
6551
6552	<method name="deleteGuestProperty" const="yes">
6553	<desc>
6554	Deletes an entry from the machine's guest property store.
6555
6556	<result name="VBOX_E_INVALID_VM_STATE">
6557	Machine session is not open.
6558	</result>
6559
6560	</desc>
6561	<param name="name" type="wstring" dir="in">
6562	<desc>
6563	The name of the property to delete.
6564	</desc>
6565	</param>
6566	</method>
6567
6568	<method name="enumerateGuestProperties" const="yes">
6569	<desc>
6570	Return a list of the guest properties matching a set of patterns along
6571	with their values, time stamps and flags.
6572	</desc>
6573	<param name="patterns" type="wstring" dir="in">
6574	<desc>
6575	The patterns to match the properties against, separated by '\|'
6576	characters. If this is empty or @c null, all properties will match.
6577	</desc>
6578	</param>
6579	<param name="names" type="wstring" dir="out" safearray="yes">
6580	<desc>
6581	The names of the properties returned.
6582	</desc>
6583	</param>
6584	<param name="values" type="wstring" dir="out" safearray="yes">
6585	<desc>
6586	The values of the properties returned. The array entries match the
6587	corresponding entries in the @a name array.
6588	</desc>
6589	</param>
6590	<param name="timestamps" type="long long" dir="out" safearray="yes">
6591	<desc>
6592	The time stamps of the properties returned. The array entries match
6593	the corresponding entries in the @a name array.
6594	</desc>
6595	</param>
6596	<param name="flags" type="wstring" dir="out" safearray="yes">
6597	<desc>
6598	The flags of the properties returned. The array entries match the
6599	corresponding entries in the @a name array.
6600	</desc>
6601	</param>
6602	</method>
6603
6604	<method name="querySavedGuestScreenInfo" const="yes">
6605	<desc>
6606	Returns the guest dimensions from the saved state.
6607	</desc>
6608	<param name="screenId" type="unsigned long" dir="in">
6609	<desc>
6610	Saved guest screen to query info from.
6611	</desc>
6612	</param>
6613	<param name="originX" type="unsigned long" dir="out">
6614	<desc>
6615	The X position of the guest monitor top left corner.
6616	</desc>
6617	</param>
6618	<param name="originY" type="unsigned long" dir="out">
6619	<desc>
6620	The Y position of the guest monitor top left corner.
6621	</desc>
6622	</param>
6623	<param name="width" type="unsigned long" dir="out">
6624	<desc>
6625	Guest width at the time of the saved state was taken.
6626	</desc>
6627	</param>
6628	<param name="height" type="unsigned long" dir="out">
6629	<desc>
6630	Guest height at the time of the saved state was taken.
6631	</desc>
6632	</param>
6633	<param name="enabled" type="boolean" dir="out">
6634	<desc>
6635	Whether the monitor is enabled in the guest.
6636	</desc>
6637	</param>
6638	</method>
6639
6640	<method name="querySavedThumbnailSize">
6641	<desc>
6642	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
6643	</desc>
6644	<param name="screenId" type="unsigned long" dir="in">
6645	<desc>
6646	Saved guest screen to query info from.
6647	</desc>
6648	</param>
6649	<param name="size" type="unsigned long" dir="out">
6650	<desc>
6651	Size of buffer required to store the bitmap.
6652	</desc>
6653	</param>
6654	<param name="width" type="unsigned long" dir="out">
6655	<desc>
6656	Bitmap width.
6657	</desc>
6658	</param>
6659	<param name="height" type="unsigned long" dir="out">
6660	<desc>
6661	Bitmap height.
6662	</desc>
6663	</param>
6664	</method>
6665
6666	<method name="readSavedThumbnailToArray">
6667	<desc>
6668	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
6669	</desc>
6670	<param name="screenId" type="unsigned long" dir="in">
6671	<desc>
6672	Saved guest screen to read from.
6673	</desc>
6674	</param>
6675	<param name="BGR" type="boolean" dir="in">
6676	<desc>
6677	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
6678	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
6679	</desc>
6680	</param>
6681	<param name="width" type="unsigned long" dir="out">
6682	<desc>
6683	Bitmap width.
6684	</desc>
6685	</param>
6686	<param name="height" type="unsigned long" dir="out">
6687	<desc>
6688	Bitmap height.
6689	</desc>
6690	</param>
6691	<param name="data" type="octet" safearray="yes" dir="return">
6692	<desc>
6693	Array with resulting bitmap data.
6694	</desc>
6695	</param>
6696	</method>
6697
6698	<method name="readSavedThumbnailPNGToArray">
6699	<desc>
6700	Thumbnail in PNG format is retrieved to an array of bytes.
6701	</desc>
6702	<param name="screenId" type="unsigned long" dir="in">
6703	<desc>
6704	Saved guest screen to read from.
6705	</desc>
6706	</param>
6707	<param name="width" type="unsigned long" dir="out">
6708	<desc>
6709	Image width.
6710	</desc>
6711	</param>
6712	<param name="height" type="unsigned long" dir="out">
6713	<desc>
6714	Image height.
6715	</desc>
6716	</param>
6717	<param name="data" type="octet" dir="return" safearray="yes">
6718	<desc>
6719	Array with resulting PNG data.
6720	</desc>
6721	</param>
6722	</method>
6723
6724	<method name="querySavedScreenshotPNGSize">
6725	<desc>
6726	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
6727	</desc>
6728	<param name="screenId" type="unsigned long" dir="in">
6729	<desc>
6730	Saved guest screen to query info from.
6731	</desc>
6732	</param>
6733	<param name="size" type="unsigned long" dir="out">
6734	<desc>
6735	Size of buffer required to store the PNG binary data.
6736	</desc>
6737	</param>
6738	<param name="width" type="unsigned long" dir="out">
6739	<desc>
6740	Image width.
6741	</desc>
6742	</param>
6743	<param name="height" type="unsigned long" dir="out">
6744	<desc>
6745	Image height.
6746	</desc>
6747	</param>
6748	</method>
6749
6750	<method name="readSavedScreenshotPNGToArray">
6751	<desc>
6752	Screenshot in PNG format is retrieved to an array of bytes.
6753	</desc>
6754	<param name="screenId" type="unsigned long" dir="in">
6755	<desc>
6756	Saved guest screen to read from.
6757	</desc>
6758	</param>
6759	<param name="width" type="unsigned long" dir="out">
6760	<desc>
6761	Image width.
6762	</desc>
6763	</param>
6764	<param name="height" type="unsigned long" dir="out">
6765	<desc>
6766	Image height.
6767	</desc>
6768	</param>
6769	<param name="data" type="octet" dir="return" safearray="yes">
6770	<desc>
6771	Array with resulting PNG data.
6772	</desc>
6773	</param>
6774	</method>
6775
6776	<method name="hotPlugCPU">
6777	<desc>
6778	Plugs a CPU into the machine.
6779	</desc>
6780	<param name="cpu" type="unsigned long" dir="in">
6781	<desc>
6782	The CPU id to insert.
6783	</desc>
6784	</param>
6785	</method>
6786
6787	<method name="hotUnplugCPU">
6788	<desc>
6789	Removes a CPU from the machine.
6790	</desc>
6791	<param name="cpu" type="unsigned long" dir="in">
6792	<desc>
6793	The CPU id to remove.
6794	</desc>
6795	</param>
6796	</method>
6797
6798	<method name="getCPUStatus">
6799	<desc>
6800	Returns the current status of the given CPU.
6801	</desc>
6802	<param name="cpu" type="unsigned long" dir="in">
6803	<desc>
6804	The CPU id to check for.
6805	</desc>
6806	</param>
6807	<param name="attached" type="boolean" dir="return">
6808	<desc>
6809	Status of the CPU.
6810	</desc>
6811	</param>
6812	</method>
6813
6814	<method name="queryLogFilename">
6815	<desc>
6816	Queries for the VM log file name of an given index. Returns an empty
6817	string if a log file with that index doesn't exists.
6818	</desc>
6819	<param name="idx" type="unsigned long" dir="in">
6820	<desc>
6821	Which log file name to query. 0=current log file.
6822	</desc>
6823	</param>
6824	<param name="filename" type="wstring" dir="return">
6825	<desc>
6826	On return the full path to the log file or an empty string on error.
6827	</desc>
6828	</param>
6829	</method>
6830
6831	<method name="readLog">
6832	<desc>
6833	Reads the VM log file. The chunk size is limited, so even if you
6834	ask for a big piece there might be less data returned.
6835	</desc>
6836	<param name="idx" type="unsigned long" dir="in">
6837	<desc>
6838	Which log file to read. 0=current log file.
6839	</desc>
6840	</param>
6841	<param name="offset" type="long long" dir="in">
6842	<desc>
6843	Offset in the log file.
6844	</desc>
6845	</param>
6846	<param name="size" type="long long" dir="in">
6847	<desc>
6848	Chunk size to read in the log file.
6849	</desc>
6850	</param>
6851	<param name="data" type="octet" dir="return" safearray="yes">
6852	<desc>
6853	Data read from the log file. A data size of 0 means end of file
6854	if the requested chunk size was not 0. This is the unprocessed
6855	file data, i.e. the line ending style depends on the platform of
6856	the system the server is running on.
6857	</desc>
6858	</param>
6859	</method>
6860
6861	<method name="cloneTo">
6862	<desc>
6863	Creates a clone of this machine, either as a full clone (which means
6864	creating independent copies of the hard disk media, save states and so
6865	on), or as a linked clone (which uses its own differencing media,
6866	sharing the parent media with the source machine).
6867
6868	The target machine object must have been created previously with <link
6869	to="IVirtualBox::createMachine"/>, and all the settings will be
6870	transferred except the VM name and the hardware UUID. You can set the
6871	VM name and the new hardware UUID when creating the target machine. The
6872	network MAC addresses are newly created for all newtwork adapters. You
6873	can change that behaviour with the options parameter. The operation is
6874	performed asynchronously, so the machine object will be not be usable
6875	until the @a progress object signals completion.
6876
6877	<result name="E_INVALIDARG">
6878	@a target is @c null.
6879	</result>
6880	</desc>
6881
6882	<param name="target" type="IMachine" dir="in">
6883	<desc>Target machine object.</desc>
6884	</param>
6885	<param name="mode" type="CloneMode" dir="in">
6886	<desc>Which states should be cloned.</desc>
6887	</param>
6888	<param name="options" type="CloneOptions" dir="in" safearray="yes">
6889	<desc>Options for the cloning operation.</desc>
6890	</param>
6891	<param name="progress" type="IProgress" dir="return">
6892	<desc>Progress object to track the operation completion.</desc>
6893	</param>
6894	</method>
6895
6896	</interface>
6897
6898	<!--
6899	// IConsole
6900	/////////////////////////////////////////////////////////////////////////
6901	-->
6902
6903	<interface
6904	name="IVRDEServerInfo" extends="$unknown"
6905	uuid="714434a1-58c3-4aab-9049-7652c5df113b"
6906	wsmap="struct"
6907	>
6908	<desc>
6909	Contains information about the remote desktop (VRDE) server capabilities and status.
6910	This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
6911	</desc>
6912
6913	<attribute name="active" type="boolean" readonly="yes">
6914	<desc>
6915	Whether the remote desktop connection is active.
6916	</desc>
6917	</attribute>
6918
6919	<attribute name="port" type="long" readonly="yes">
6920	<desc>
6921	VRDE server port number. If this property is equal to <tt>0</tt>, then
6922	the VRDE server failed to start, usually because there are no free IP
6923	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
6924	server has not yet been started.
6925	</desc>
6926	</attribute>
6927
6928	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6929	<desc>
6930	How many times a client connected.
6931	</desc>
6932	</attribute>
6933
6934	<attribute name="beginTime" type="long long" readonly="yes">
6935	<desc>
6936	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6937	</desc>
6938	</attribute>
6939
6940	<attribute name="endTime" type="long long" readonly="yes">
6941	<desc>
6942	When the last connection was terminated or the current time, if
6943	connection is still active, in milliseconds since 1970-01-01 UTC.
6944	</desc>
6945	</attribute>
6946
6947	<attribute name="bytesSent" type="long long" readonly="yes">
6948	<desc>
6949	How many bytes were sent in last or current, if still active, connection.
6950	</desc>
6951	</attribute>
6952
6953	<attribute name="bytesSentTotal" type="long long" readonly="yes">
6954	<desc>
6955	How many bytes were sent in all connections.
6956	</desc>
6957	</attribute>
6958
6959	<attribute name="bytesReceived" type="long long" readonly="yes">
6960	<desc>
6961	How many bytes were received in last or current, if still active, connection.
6962	</desc>
6963	</attribute>
6964
6965	<attribute name="bytesReceivedTotal" type="long long" readonly="yes">
6966	<desc>
6967	How many bytes were received in all connections.
6968	</desc>
6969	</attribute>
6970
6971	<attribute name="user" type="wstring" readonly="yes">
6972	<desc>
6973	Login user name supplied by the client.
6974	</desc>
6975	</attribute>
6976
6977	<attribute name="domain" type="wstring" readonly="yes">
6978	<desc>
6979	Login domain name supplied by the client.
6980	</desc>
6981	</attribute>
6982
6983	<attribute name="clientName" type="wstring" readonly="yes">
6984	<desc>
6985	The client name supplied by the client.
6986	</desc>
6987	</attribute>
6988
6989	<attribute name="clientIP" type="wstring" readonly="yes">
6990	<desc>
6991	The IP address of the client.
6992	</desc>
6993	</attribute>
6994
6995	<attribute name="clientVersion" type="unsigned long" readonly="yes">
6996	<desc>
6997	The client software version number.
6998	</desc>
6999	</attribute>
7000
7001	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
7002	<desc>
7003	Public key exchange method used when connection was established.
7004	Values: 0 - RDP4 public key exchange scheme.
7005	1 - X509 certificates were sent to client.
7006	</desc>
7007	</attribute>
7008
7009	</interface>
7010
7011	<interface
7012	name="IConsole" extends="$unknown"
7013	uuid="db7ab4ca-2a3f-4183-9243-c1208da92392"
7014	wsmap="managed"
7015	>
7016	<desc>
7017	The IConsole interface represents an interface to control virtual
7018	machine execution.
7019
7020	A console object gets created when a machine has been locked for a
7021	particular session (client process) using <link to="IMachine::lockMachine" />
7022	or <link to="IMachine::launchVMProcess"/>. The console object can
7023	then be found in the session's <link to="ISession::console" /> attribute.
7024
7025	Methods of the IConsole interface allow the caller to query the current
7026	virtual machine execution state, pause the machine or power it down, save
7027	the machine state or take a snapshot, attach and detach removable media
7028	and so on.
7029
7030	<see><link to="ISession"/></see>
7031	</desc>
7032
7033	<attribute name="machine" type="IMachine" readonly="yes">
7034	<desc>
7035	Machine object for this console session.
7036	<note>
7037	This is a convenience property, it has the same value as
7038	<link to="ISession::machine"/> of the corresponding session
7039	object.
7040	</note>
7041	</desc>
7042	</attribute>
7043
7044	<attribute name="state" type="MachineState" readonly="yes">
7045	<desc>
7046	Current execution state of the machine.
7047	<note>
7048	This property always returns the same value as the corresponding
7049	property of the IMachine object for this console session.
7050	For the process that owns (executes) the VM, this is the
7051	preferable way of querying the VM state, because no IPC
7052	calls are made.
7053	</note>
7054	</desc>
7055	</attribute>
7056
7057	<attribute name="guest" type="IGuest" readonly="yes">
7058	<desc>Guest object.</desc>
7059	</attribute>
7060
7061	<attribute name="keyboard" type="IKeyboard" readonly="yes">
7062	<desc>
7063	Virtual keyboard object.
7064	<note>
7065	If the machine is not running, any attempt to use
7066	the returned object will result in an error.
7067	</note>
7068	</desc>
7069	</attribute>
7070
7071	<attribute name="mouse" type="IMouse" readonly="yes">
7072	<desc>
7073	Virtual mouse object.
7074	<note>
7075	If the machine is not running, any attempt to use
7076	the returned object will result in an error.
7077	</note>
7078	</desc>
7079	</attribute>
7080
7081	<attribute name="display" type="IDisplay" readonly="yes">
7082	<desc>Virtual display object.
7083	<note>
7084	If the machine is not running, any attempt to use
7085	the returned object will result in an error.
7086	</note>
7087	</desc>
7088	</attribute>
7089
7090	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
7091	<desc>Debugging interface.</desc>
7092	</attribute>
7093
7094	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
7095	<desc>
7096	Collection of USB devices currently attached to the virtual
7097	USB controller.
7098	<note>
7099	The collection is empty if the machine is not running.
7100	</note>
7101	</desc>
7102	</attribute>
7103
7104	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7105	<desc>
7106	List of USB devices currently attached to the remote VRDE client.
7107	Once a new device is physically attached to the remote host computer,
7108	it appears in this list and remains there until detached.
7109	</desc>
7110	</attribute>
7111
7112	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
7113	<desc>
7114	Collection of shared folders for the current session. These folders
7115	are called transient shared folders because they are available to the
7116	guest OS running inside the associated virtual machine only for the
7117	duration of the session (as opposed to
7118	<link to="IMachine::sharedFolders"/> which represent permanent shared
7119	folders). When the session is closed (e.g. the machine is powered down),
7120	these folders are automatically discarded.
7121
7122	New shared folders are added to the collection using
7123	<link to="#createSharedFolder"/>. Existing shared folders can be
7124	removed using <link to="#removeSharedFolder"/>.
7125	</desc>
7126	</attribute>
7127
7128	<attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
7129	<desc>
7130	Interface that provides information on Remote Desktop Extension (VRDE) connection.
7131	</desc>
7132	</attribute>
7133
7134	<attribute name="eventSource" type="IEventSource" readonly="yes">
7135	<desc>
7136	Event source for console events.
7137	</desc>
7138	</attribute>
7139
7140	<attribute name="attachedPCIDevices" type="IPCIDeviceAttachment" readonly="yes" safearray="yes">
7141	<desc>Array of PCI devices attached to this machine.</desc>
7142	</attribute>
7143
7144	<attribute name="useHostClipboard" type="boolean">
7145	<desc>
7146	Whether the guest clipboard should be connected to the host one or
7147	whether it should only be allowed access to the VRDE clipboard. This
7148	setting may not affect existing guest clipboard connections which
7149	are already connected to the host clipboard.
7150	</desc>
7151	</attribute>
7152
7153	<method name="powerUp">
7154	<desc>
7155	Starts the virtual machine execution using the current machine
7156	state (that is, its current execution state, current settings and
7157	current storage devices).
7158
7159	<note>
7160	This method is only useful for front-ends that want to actually
7161	execute virtual machines in their own process (like the VirtualBox
7162	or VBoxSDL front-ends). Unless you are intending to write such a
7163	front-end, do not call this method. If you simply want to
7164	start virtual machine execution using one of the existing front-ends
7165	(for example the VirtualBox GUI or headless server), use
7166	<link to="IMachine::launchVMProcess"/> instead; these
7167	front-ends will power up the machine automatically for you.
7168	</note>
7169
7170	If the machine is powered off or aborted, the execution will
7171	start from the beginning (as if the real hardware were just
7172	powered on).
7173
7174	If the machine is in the <link to="MachineState_Saved"/> state,
7175	it will continue its execution the point where the state has
7176	been saved.
7177
7178	If the machine <link to="IMachine::teleporterEnabled"/> property is
7179	enabled on the machine being powered up, the machine will wait for an
7180	incoming teleportation in the <link to="MachineState_TeleportingIn"/>
7181	state. The returned progress object will have at least three
7182	operations where the last three are defined as: (1) powering up and
7183	starting TCP server, (2) waiting for incoming teleportations, and
7184	(3) perform teleportation. These operations will be reflected as the
7185	last three operations of the progress objected returned by
7186	<link to="IMachine::launchVMProcess"/> as well.
7187
7188	<see><link to="#saveState"/></see>
7189
7190	<result name="VBOX_E_INVALID_VM_STATE">
7191	Virtual machine already running.
7192	</result>
7193	<result name="VBOX_E_HOST_ERROR">
7194	Host interface does not exist or name not set.
7195	</result>
7196	<result name="VBOX_E_FILE_ERROR">
7197	Invalid saved state file.
7198	</result>
7199	</desc>
7200	<param name="progress" type="IProgress" dir="return">
7201	<desc>Progress object to track the operation completion.</desc>
7202	</param>
7203	</method>
7204
7205	<method name="powerUpPaused">
7206	<desc>
7207	Identical to powerUp except that the VM will enter the
7208	<link to="MachineState_Paused"/> state, instead of
7209	<link to="MachineState_Running"/>.
7210
7211	<see><link to="#powerUp"/></see>
7212	<result name="VBOX_E_INVALID_VM_STATE">
7213	Virtual machine already running.
7214	</result>
7215	<result name="VBOX_E_HOST_ERROR">
7216	Host interface does not exist or name not set.
7217	</result>
7218	<result name="VBOX_E_FILE_ERROR">
7219	Invalid saved state file.
7220	</result>
7221	</desc>
7222	<param name="progress" type="IProgress" dir="return">
7223	<desc>Progress object to track the operation completion.</desc>
7224	</param>
7225	</method>
7226
7227	<method name="powerDown">
7228	<desc>
7229	Initiates the power down procedure to stop the virtual machine
7230	execution.
7231
7232	The completion of the power down procedure is tracked using the returned
7233	IProgress object. After the operation is complete, the machine will go
7234	to the PoweredOff state.
7235	<result name="VBOX_E_INVALID_VM_STATE">
7236	Virtual machine must be Running, Paused or Stuck to be powered down.
7237	</result>
7238	</desc>
7239	<param name="progress" type="IProgress" dir="return">
7240	<desc>Progress object to track the operation completion.</desc>
7241	</param>
7242	</method>
7243
7244	<method name="reset">
7245	<desc>Resets the virtual machine.
7246	<result name="VBOX_E_INVALID_VM_STATE">
7247	Virtual machine not in Running state.
7248	</result>
7249	<result name="VBOX_E_VM_ERROR">
7250	Virtual machine error in reset operation.
7251	</result>
7252	</desc>
7253	</method>
7254
7255	<method name="pause">
7256	<desc>Pauses the virtual machine execution.
7257	<result name="VBOX_E_INVALID_VM_STATE">
7258	Virtual machine not in Running state.
7259	</result>
7260	<result name="VBOX_E_VM_ERROR">
7261	Virtual machine error in suspend operation.
7262	</result>
7263	</desc>
7264	</method>
7265
7266	<method name="resume">
7267	<desc>Resumes the virtual machine execution.
7268	<result name="VBOX_E_INVALID_VM_STATE">
7269	Virtual machine not in Paused state.
7270	</result>
7271	<result name="VBOX_E_VM_ERROR">
7272	Virtual machine error in resume operation.
7273	</result>
7274	</desc>
7275	</method>
7276
7277	<method name="powerButton">
7278	<desc>Sends the ACPI power button event to the guest.
7279	<result name="VBOX_E_INVALID_VM_STATE">
7280	Virtual machine not in Running state.
7281	</result>
7282	<result name="VBOX_E_PDM_ERROR">
7283	Controlled power off failed.
7284	</result>
7285	</desc>
7286	</method>
7287
7288	<method name="sleepButton">
7289	<desc>Sends the ACPI sleep button event to the guest.
7290	<result name="VBOX_E_INVALID_VM_STATE">
7291	Virtual machine not in Running state.
7292	</result>
7293	<result name="VBOX_E_PDM_ERROR">
7294	Sending sleep button event failed.
7295	</result>
7296	</desc>
7297	</method>
7298
7299	<method name="getPowerButtonHandled">
7300	<desc>Checks if the last power button event was handled by guest.
7301	<result name="VBOX_E_PDM_ERROR">
7302	Checking if the event was handled by the guest OS failed.
7303	</result>
7304	</desc>
7305	<param name="handled" type="boolean" dir="return"/>
7306	</method>
7307
7308	<method name="getGuestEnteredACPIMode">
7309	<desc>Checks if the guest entered the ACPI mode G0 (working) or
7310	G1 (sleeping). If this method returns @c false, the guest will
7311	most likely not respond to external ACPI events.
7312	<result name="VBOX_E_INVALID_VM_STATE">
7313	Virtual machine not in Running state.
7314	</result>
7315	</desc>
7316	<param name="entered" type="boolean" dir="return"/>
7317	</method>
7318
7319	<method name="saveState">
7320	<desc>
7321	Saves the current execution state of a running virtual machine
7322	and stops its execution.
7323
7324	After this operation completes, the machine will go to the
7325	Saved state. Next time it is powered up, this state will
7326	be restored and the machine will continue its execution from
7327	the place where it was saved.
7328
7329	This operation differs from taking a snapshot to the effect
7330	that it doesn't create new differencing media. Also, once
7331	the machine is powered up from the state saved using this method,
7332	the saved state is deleted, so it will be impossible to return
7333	to this state later.
7334
7335	<note>
7336	On success, this method implicitly calls
7337	<link to="IMachine::saveSettings"/> to save all current machine
7338	settings (including runtime changes to the DVD medium, etc.).
7339	Together with the impossibility to change any VM settings when it is
7340	in the Saved state, this guarantees adequate hardware
7341	configuration of the machine when it is restored from the saved
7342	state file.
7343	</note>
7344
7345	<note>
7346	The machine must be in the Running or Paused state, otherwise
7347	the operation will fail.
7348	</note>
7349	<result name="VBOX_E_INVALID_VM_STATE">
7350	Virtual machine state neither Running nor Paused.
7351	</result>
7352	<result name="VBOX_E_FILE_ERROR">
7353	Failed to create directory for saved state file.
7354	</result>
7355
7356	<see><link to="#takeSnapshot"/></see>
7357	</desc>
7358	<param name="progress" type="IProgress" dir="return">
7359	<desc>Progress object to track the operation completion.</desc>
7360	</param>
7361	</method>
7362
7363	<method name="adoptSavedState">
7364	<desc>
7365	Associates the given saved state file to the virtual machine.
7366
7367	On success, the machine will go to the Saved state. Next time it is
7368	powered up, it will be restored from the adopted saved state and
7369	continue execution from the place where the saved state file was
7370	created.
7371
7372	The specified saved state file path may be absolute or relative to the
7373	folder the VM normally saves the state to (usually,
7374	<link to="IMachine::snapshotFolder"/>).
7375
7376	<note>
7377	It's a caller's responsibility to make sure the given saved state
7378	file is compatible with the settings of this virtual machine that
7379	represent its virtual hardware (memory size, storage disk configuration
7380	etc.). If there is a mismatch, the behavior of the virtual machine
7381	is undefined.
7382	</note>
7383	<result name="VBOX_E_INVALID_VM_STATE">
7384	Virtual machine state neither PoweredOff nor Aborted.
7385	</result>
7386	</desc>
7387	<param name="savedStateFile" type="wstring" dir="in">
7388	<desc>Path to the saved state file to adopt.</desc>
7389	</param>
7390	</method>
7391
7392	<method name="discardSavedState">
7393	<desc>
7394	Forcibly resets the machine to "Powered Off" state if it is
7395	currently in the "Saved" state (previously created by <link to="#saveState"/>).
7396	Next time the machine is powered up, a clean boot will occur.
7397	<note>
7398	This operation is equivalent to resetting or powering off
7399	the machine without doing a proper shutdown of the guest
7400	operating system; as with resetting a running phyiscal
7401	computer, it can can lead to data loss.
7402	</note>
7403	If @a fRemoveFile is @c true, the file in the machine directory
7404	into which the machine state was saved is also deleted. If
7405	this is @c false, then the state can be recovered and later
7406	re-inserted into a machine using <link to="#adoptSavedState" />.
7407	The location of the file can be found in the
7408	<link to="IMachine::stateFilePath" /> attribute.
7409	<result name="VBOX_E_INVALID_VM_STATE">
7410	Virtual machine not in state Saved.
7411	</result>
7412	</desc>
7413	<param name="fRemoveFile" type="boolean" dir="in" >
7414	<desc>Whether to also remove the saved state file.</desc>
7415	</param>
7416	</method>
7417
7418	<method name="getDeviceActivity">
7419	<desc>
7420	Gets the current activity type of a given device or device group.
7421	<result name="E_INVALIDARG">
7422	Invalid device type.
7423	</result>
7424	</desc>
7425	<param name="type" type="DeviceType" dir="in"/>
7426	<param name="activity" type="DeviceActivity" dir="return"/>
7427	</method>
7428
7429	<method name="attachUSBDevice">
7430	<desc>
7431	Attaches a host USB device with the given UUID to the
7432	USB controller of the virtual machine.
7433
7434	The device needs to be in one of the following states:
7435	<link to="USBDeviceState_Busy"/>,
7436	<link to="USBDeviceState_Available"/> or
7437	<link to="USBDeviceState_Held"/>,
7438	otherwise an error is immediately returned.
7439
7440	When the device state is
7441	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7442	be returned if the host computer refuses to release it for some reason.
7443
7444	<see><link to="IUSBController::deviceFilters"/>,
7445	<link to="USBDeviceState"/></see>
7446	<result name="VBOX_E_INVALID_VM_STATE">
7447	Virtual machine state neither Running nor Paused.
7448	</result>
7449	<result name="VBOX_E_PDM_ERROR">
7450	Virtual machine does not have a USB controller.
7451	</result>
7452	</desc>
7453	<param name="id" type="uuid" mod="string" dir="in">
7454	<desc>UUID of the host USB device to attach.</desc>
7455	</param>
7456	</method>
7457
7458	<method name="detachUSBDevice">
7459	<desc>
7460	Detaches an USB device with the given UUID from the USB controller
7461	of the virtual machine.
7462
7463	After this method succeeds, the VirtualBox server re-initiates
7464	all USB filters as if the device were just physically attached
7465	to the host, but filters of this machine are ignored to avoid
7466	a possible automatic re-attachment.
7467
7468	<see><link to="IUSBController::deviceFilters"/>,
7469	<link to="USBDeviceState"/></see>
7470
7471	<result name="VBOX_E_PDM_ERROR">
7472	Virtual machine does not have a USB controller.
7473	</result>
7474	<result name="E_INVALIDARG">
7475	USB device not attached to this virtual machine.
7476	</result>
7477	</desc>
7478	<param name="id" type="uuid" mod="string" dir="in">
7479	<desc>UUID of the USB device to detach.</desc>
7480	</param>
7481	<param name="device" type="IUSBDevice" dir="return">
7482	<desc>Detached USB device.</desc>
7483	</param>
7484	</method>
7485
7486	<method name="findUSBDeviceByAddress">
7487	<desc>
7488	Searches for a USB device with the given host address.
7489
7490	<result name="VBOX_E_OBJECT_NOT_FOUND">
7491	Given @c name does not correspond to any USB device.
7492	</result>
7493
7494	<see><link to="IUSBDevice::address"/></see>
7495	</desc>
7496	<param name="name" type="wstring" dir="in">
7497	<desc>
7498	Address of the USB device (as assigned by the host) to
7499	search for.
7500	</desc>
7501	</param>
7502	<param name="device" type="IUSBDevice" dir="return">
7503	<desc>Found USB device object.</desc>
7504	</param>
7505	</method>
7506
7507	<method name="findUSBDeviceById">
7508	<desc>
7509	Searches for a USB device with the given UUID.
7510
7511	<result name="VBOX_E_OBJECT_NOT_FOUND">
7512	Given @c id does not correspond to any USB device.
7513	</result>
7514
7515	<see><link to="IUSBDevice::id"/></see>
7516	</desc>
7517	<param name="id" type="uuid" mod="string" dir="in">
7518	<desc>UUID of the USB device to search for.</desc>
7519	</param>
7520	<param name="device" type="IUSBDevice" dir="return">
7521	<desc>Found USB device object.</desc>
7522	</param>
7523	</method>
7524
7525	<method name="createSharedFolder">
7526	<desc>
7527	Creates a transient new shared folder by associating the given logical
7528	name with the given host path, adds it to the collection of shared
7529	folders and starts sharing it. Refer to the description of
7530	<link to="ISharedFolder"/> to read more about logical names.
7531
7532	<result name="VBOX_E_INVALID_VM_STATE">
7533	Virtual machine in Saved state or currently changing state.
7534	</result>
7535	<result name="VBOX_E_FILE_ERROR">
7536	Shared folder already exists or not accessible.
7537	</result>
7538	</desc>
7539	<param name="name" type="wstring" dir="in">
7540	<desc>Unique logical name of the shared folder.</desc>
7541	</param>
7542	<param name="hostPath" type="wstring" dir="in">
7543	<desc>Full path to the shared folder in the host file system.</desc>
7544	</param>
7545	<param name="writable" type="boolean" dir="in">
7546	<desc>Whether the share is writable or readonly</desc>
7547	</param>
7548	<param name="automount" type="boolean" dir="in">
7549	<desc>Whether the share gets automatically mounted by the guest
7550	or not.</desc>
7551	</param>
7552	</method>
7553
7554	<method name="removeSharedFolder">
7555	<desc>
7556	Removes a transient shared folder with the given name previously
7557	created by <link to="#createSharedFolder"/> from the collection of
7558	shared folders and stops sharing it.
7559	<result name="VBOX_E_INVALID_VM_STATE">
7560	Virtual machine in Saved state or currently changing state.
7561	</result>
7562	<result name="VBOX_E_FILE_ERROR">
7563	Shared folder does not exists.
7564	</result>
7565	</desc>
7566	<param name="name" type="wstring" dir="in">
7567	<desc>Logical name of the shared folder to remove.</desc>
7568	</param>
7569	</method>
7570
7571	<method name="takeSnapshot">
7572	<desc>
7573	Saves the current execution state
7574	and all settings of the machine and creates differencing images
7575	for all normal (non-independent) media.
7576	See <link to="ISnapshot" /> for an introduction to snapshots.
7577
7578	This method can be called for a PoweredOff, Saved (see
7579	<link to="#saveState"/>), Running or
7580	Paused virtual machine. When the machine is PoweredOff, an
7581	offline snapshot is created. When the machine is Running a live
7582	snapshot is created, and an online snapshot is created when Paused.
7583
7584	The taken snapshot is always based on the
7585	<link to="IMachine::currentSnapshot">current snapshot</link>
7586	of the associated virtual machine and becomes a new current snapshot.
7587
7588	<note>
7589	This method implicitly calls <link to="IMachine::saveSettings"/> to
7590	save all current machine settings before taking an offline snapshot.
7591	</note>
7592
7593	<result name="VBOX_E_INVALID_VM_STATE">
7594	Virtual machine currently changing state.
7595	</result>
7596	</desc>
7597	<param name="name" type="wstring" dir="in">
7598	<desc>Short name for the snapshot.</desc>
7599	</param>
7600	<param name="description" type="wstring" dir="in">
7601	<desc>Optional description of the snapshot.</desc>
7602	</param>
7603	<param name="progress" type="IProgress" dir="return">
7604	<desc>Progress object to track the operation completion.</desc>
7605	</param>
7606	</method>
7607
7608	<method name="deleteSnapshot">
7609	<desc>
7610	Starts deleting the specified snapshot asynchronously.
7611	See <link to="ISnapshot" /> for an introduction to snapshots.
7612
7613	The execution state and settings of the associated machine stored in
7614	the snapshot will be deleted. The contents of all differencing media of
7615	this snapshot will be merged with the contents of their dependent child
7616	media to keep the medium chain valid (in other words, all changes
7617	represented by media being deleted will be propagated to their child
7618	medium). After that, this snapshot's differencing medium will be
7619	deleted. The parent of this snapshot will become a new parent for all
7620	its child snapshots.
7621
7622	If the deleted snapshot is the current one, its parent snapshot will
7623	become a new current snapshot. The current machine state is not directly
7624	affected in this case, except that currently attached differencing
7625	media based on media of the deleted snapshot will be also merged as
7626	described above.
7627
7628	If the deleted snapshot is the first or current snapshot, then the
7629	respective IMachine attributes will be adjusted. Deleting the current
7630	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7631	to make all current machine settings permanent.
7632
7633	Deleting a snapshot has the following preconditions:
7634
7635	<ul>
7636	<li>Child media of all normal media of the deleted snapshot
7637	must be accessible (see <link to="IMedium::state"/>) for this
7638	operation to succeed. If only one running VM refers to all images
7639	which participates in merging the operation can be performed while
7640	the VM is running. Otherwise all virtual machines whose media are
7641	directly or indirectly based on the media of deleted snapshot must
7642	be powered off. In any case, online snapshot deleting usually is
7643	slower than the same operation without any running VM.</li>
7644
7645	<li>You cannot delete the snapshot if a medium attached to it has
7646	more than one child medium (differencing images) because otherwise
7647	merging would be impossible. This might be the case if there is
7648	more than one child snapshot or differencing images were created
7649	for other reason (e.g. implicitly because of multiple machine
7650	attachments).</li>
7651	</ul>
7652
7653	The virtual machine's <link to="IMachine::state">state</link> is
7654	changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
7655	"DeletingSnapshotPaused" while this operation is in progress.
7656
7657	<note>
7658	Merging medium contents can be very time and disk space
7659	consuming, if these media are big in size and have many
7660	children. However, if the snapshot being deleted is the last
7661	(head) snapshot on the branch, the operation will be rather
7662	quick.
7663	</note>
7664	<result name="VBOX_E_INVALID_VM_STATE">
7665	The running virtual machine prevents deleting this snapshot. This
7666	happens only in very specific situations, usually snapshots can be
7667	deleted without trouble while a VM is running. The error message
7668	text explains the reason for the failure.
7669	</result>
7670	</desc>
7671	<param name="id" type="uuid" mod="string" dir="in">
7672	<desc>UUID of the snapshot to delete.</desc>
7673	</param>
7674	<param name="progress" type="IProgress" dir="return">
7675	<desc>Progress object to track the operation completion.</desc>
7676	</param>
7677	</method>
7678
7679	<method name="deleteSnapshotAndAllChildren">
7680	<desc>
7681	Starts deleting the specified snapshot and all its children
7682	asynchronously. See <link to="ISnapshot" /> for an introduction to
7683	snapshots. The conditions and many details are the same as with
7684	<link to="#deleteSnapshot"/>.
7685
7686	This operation is very fast if the snapshot subtree does not include
7687	the current state. It is still significantly faster than deleting the
7688	snapshots one by one if the current state is in the subtree and there
7689	are more than one snapshots from current state to the snapshot which
7690	marks the subtree, since it eliminates the incremental image merging.
7691
7692	<note>This API method is right now not implemented!</note>
7693
7694	<result name="VBOX_E_INVALID_VM_STATE">
7695	The running virtual machine prevents deleting this snapshot. This
7696	happens only in very specific situations, usually snapshots can be
7697	deleted without trouble while a VM is running. The error message
7698	text explains the reason for the failure.
7699	</result>
7700	<result name="E_NOTIMPL">
7701	The method is not implemented yet.
7702	</result>
7703	</desc>
7704	<param name="id" type="uuid" mod="string" dir="in">
7705	<desc>UUID of the snapshot to delete, including all its children.</desc>
7706	</param>
7707	<param name="progress" type="IProgress" dir="return">
7708	<desc>Progress object to track the operation completion.</desc>
7709	</param>
7710	</method>
7711
7712	<method name="deleteSnapshotRange">
7713	<desc>
7714	Starts deleting the specified snapshot range. This is limited to
7715	linear snapshot lists, which means there may not be any other child
7716	snapshots other than the direct sequence between the start and end
7717	snapshot. If the start and end snapshot point to the same snapshot this
7718	method is completely equivalent to <link to="#deleteSnapshot"/>. See
7719	<link to="ISnapshot" /> for an introduction to snapshots. The
7720	conditions and many details are the same as with
7721	<link to="#deleteSnapshot"/>.
7722
7723	This operation is generally faster than deleting snapshots one by one
7724	and often also needs less extra disk space before freeing up disk space
7725	by deleting the removed disk images corresponding to the snapshot.
7726
7727	<note>This API method is right now not implemented!</note>
7728
7729	<result name="VBOX_E_INVALID_VM_STATE">
7730	The running virtual machine prevents deleting this snapshot. This
7731	happens only in very specific situations, usually snapshots can be
7732	deleted without trouble while a VM is running. The error message
7733	text explains the reason for the failure.
7734	</result>
7735	<result name="E_NOTIMPL">
7736	The method is not implemented yet.
7737	</result>
7738	</desc>
7739	<param name="startId" type="uuid" mod="string" dir="in">
7740	<desc>UUID of the first snapshot to delete.</desc>
7741	</param>
7742	<param name="endId" type="uuid" mod="string" dir="in">
7743	<desc>UUID of the last snapshot to delete.</desc>
7744	</param>
7745	<param name="progress" type="IProgress" dir="return">
7746	<desc>Progress object to track the operation completion.</desc>
7747	</param>
7748	</method>
7749
7750	<method name="restoreSnapshot">
7751	<desc>
7752	Starts resetting the machine's current state to the state contained
7753	in the given snapshot, asynchronously. All current settings of the
7754	machine will be reset and changes stored in differencing media
7755	will be lost.
7756	See <link to="ISnapshot" /> for an introduction to snapshots.
7757
7758	After this operation is successfully completed, new empty differencing
7759	media are created for all normal media of the machine.
7760
7761	If the given snapshot is an online snapshot, the machine will go to
7762	the <link to="MachineState_Saved"> saved state</link>, so that the
7763	next time it is powered on, the execution state will be restored
7764	from the state of the snapshot.
7765
7766	<note>
7767	The machine must not be running, otherwise the operation will fail.
7768	</note>
7769
7770	<note>
7771	If the machine state is <link to="MachineState_Saved">Saved</link>
7772	prior to this operation, the saved state file will be implicitly
7773	deleted (as if <link to="IConsole::discardSavedState"/> were
7774	called).
7775	</note>
7776
7777	<result name="VBOX_E_INVALID_VM_STATE">
7778	Virtual machine is running.
7779	</result>
7780	</desc>
7781	<param name="snapshot" type="ISnapshot" dir="in">
7782	<desc>The snapshot to restore the VM state from.</desc>
7783	</param>
7784	<param name="progress" type="IProgress" dir="return">
7785	<desc>Progress object to track the operation completion.</desc>
7786	</param>
7787	</method>
7788
7789	<method name="teleport">
7790	<desc>
7791	Teleport the VM to a different host machine or process.
7792
7793	TODO explain the details.
7794
7795	<result name="VBOX_E_INVALID_VM_STATE">
7796	Virtual machine not running or paused.
7797	</result>
7798	</desc>
7799	<param name="hostname" type="wstring" dir="in">
7800	<desc>The name or IP of the host to teleport to.</desc>
7801	</param>
7802	<param name="tcpport" type="unsigned long" dir="in">
7803	<desc>The TCP port to connect to (1..65535).</desc>
7804	</param>
7805	<param name="password" type="wstring" dir="in">
7806	<desc>The password.</desc>
7807	</param>
7808	<param name="maxDowntime" type="unsigned long" dir="in">
7809	<desc>
7810	The maximum allowed downtime given as milliseconds. 0 is not a valid
7811	value. Recommended value: 250 ms.
7812
7813	The higher the value is, the greater the chance for a successful
7814	teleportation. A small value may easily result in the teleportation
7815	process taking hours and eventually fail.
7816
7817	<note>
7818	The current implementation treats this a guideline, not as an
7819	absolute rule.
7820	</note>
7821	</desc>
7822	</param>
7823	<param name="progress" type="IProgress" dir="return">
7824	<desc>Progress object to track the operation completion.</desc>
7825	</param>
7826	</method>
7827
7828	</interface>
7829
7830	<!--
7831	// IHost
7832	/////////////////////////////////////////////////////////////////////////
7833	-->
7834
7835	<enum
7836	name="HostNetworkInterfaceMediumType"
7837	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7838	>
7839	<desc>
7840	Type of encapsulation. Ethernet encapsulation includes both wired and
7841	wireless Ethernet connections.
7842	<see><link to="IHostNetworkInterface"/></see>
7843	</desc>
7844
7845	<const name="Unknown" value="0">
7846	<desc>
7847	The type of interface cannot be determined.
7848	</desc>
7849	</const>
7850	<const name="Ethernet" value="1">
7851	<desc>
7852	Ethernet frame encapsulation.
7853	</desc>
7854	</const>
7855	<const name="PPP" value="2">
7856	<desc>
7857	Point-to-point protocol encapsulation.
7858	</desc>
7859	</const>
7860	<const name="SLIP" value="3">
7861	<desc>
7862	Serial line IP encapsulation.
7863	</desc>
7864	</const>
7865	</enum>
7866
7867	<enum
7868	name="HostNetworkInterfaceStatus"
7869	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7870	>
7871	<desc>
7872	Current status of the interface.
7873	<see><link to="IHostNetworkInterface"/></see>
7874	</desc>
7875
7876	<const name="Unknown" value="0">
7877	<desc>
7878	The state of interface cannot be determined.
7879	</desc>
7880	</const>
7881	<const name="Up" value="1">
7882	<desc>
7883	The interface is fully operational.
7884	</desc>
7885	</const>
7886	<const name="Down" value="2">
7887	<desc>
7888	The interface is not functioning.
7889	</desc>
7890	</const>
7891	</enum>
7892
7893	<enum
7894	name="HostNetworkInterfaceType"
7895	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7896	>
7897	<desc>
7898	Network interface type.
7899	</desc>
7900	<const name="Bridged" value="1"/>
7901	<const name="HostOnly" value="2"/>
7902	</enum>
7903
7904	<interface
7905	name="IHostNetworkInterface" extends="$unknown"
7906	uuid="87a4153d-6889-4dd6-9654-2e9ff0ae8dec"
7907	wsmap="managed"
7908	>
7909	<desc>
7910	Represents one of host's network interfaces. IP V6 address and network
7911	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7912	separated by colons.
7913	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7914	</desc>
7915	<attribute name="name" type="wstring" readonly="yes">
7916	<desc>Returns the host network interface name.</desc>
7917	</attribute>
7918
7919	<attribute name="id" type="uuid" mod="string" readonly="yes">
7920	<desc>Returns the interface UUID.</desc>
7921	</attribute>
7922
7923	<attribute name="networkName" type="wstring" readonly="yes">
7924	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7925	</attribute>
7926
7927	<attribute name="DHCPEnabled" type="boolean" readonly="yes">
7928	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7929	</attribute>
7930
7931	<attribute name="IPAddress" type="wstring" readonly="yes">
7932	<desc>Returns the IP V4 address of the interface.</desc>
7933	</attribute>
7934
7935	<attribute name="networkMask" type="wstring" readonly="yes">
7936	<desc>Returns the network mask of the interface.</desc>
7937	</attribute>
7938
7939	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7940	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7941	</attribute>
7942
7943	<attribute name="IPV6Address" type="wstring" readonly="yes">
7944	<desc>Returns the IP V6 address of the interface.</desc>
7945	</attribute>
7946
7947	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7948	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7949	</attribute>
7950
7951	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7952	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7953	</attribute>
7954
7955	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7956	<desc>Type of protocol encapsulation used.</desc>
7957	</attribute>
7958
7959	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7960	<desc>Status of the interface.</desc>
7961	</attribute>
7962
7963	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7964	<desc>specifies the host interface type.</desc>
7965	</attribute>
7966
7967	<method name="enableStaticIPConfig">
7968	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7969	<param name="IPAddress" type="wstring" dir="in">
7970	<desc>
7971	IP address.
7972	</desc>
7973	</param>
7974	<param name="networkMask" type="wstring" dir="in">
7975	<desc>
7976	network mask.
7977	</desc>
7978	</param>
7979	</method>
7980
7981	<method name="enableStaticIPConfigV6">
7982	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7983	<param name="IPV6Address" type="wstring" dir="in">
7984	<desc>
7985	IP address.
7986	</desc>
7987	</param>
7988	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7989	<desc>
7990	network mask.
7991	</desc>
7992	</param>
7993	</method>
7994
7995	<method name="enableDynamicIPConfig">
7996	<desc>enables the dynamic IP configuration.</desc>
7997	</method>
7998
7999	<method name="DHCPRediscover">
8000	<desc>refreshes the IP configuration for DHCP-enabled interface.</desc>
8001	</method>
8002
8003	</interface>
8004
8005	<interface
8006	name="IHost" extends="$unknown"
8007	uuid="30678943-32df-4830-b413-931b25ac86a0"
8008	wsmap="managed"
8009	>
8010	<desc>
8011	The IHost interface represents the physical machine that this VirtualBox
8012	installation runs on.
8013
8014	An object implementing this interface is returned by the
8015	<link to="IVirtualBox::host" /> attribute. This interface contains
8016	read-only information about the host's physical hardware (such as what
8017	processors and disks are available, what the host operating system is,
8018	and so on) and also allows for manipulating some of the host's hardware,
8019	such as global USB device filters and host interface networking.
8020
8021	</desc>
8022	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
8023	<desc>List of DVD drives available on the host.</desc>
8024	</attribute>
8025
8026	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
8027	<desc>List of floppy drives available on the host.</desc>
8028	</attribute>
8029
8030	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
8031	<desc>
8032	List of USB devices currently attached to the host.
8033	Once a new device is physically attached to the host computer,
8034	it appears in this list and remains there until detached.
8035
8036	<note>
8037	If USB functionality is not available in the given edition of
8038	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8039	</note>
8040	</desc>
8041	</attribute>
8042
8043	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
8044	<desc>
8045	List of USB device filters in action.
8046	When a new device is physically attached to the host computer,
8047	filters from this list are applied to it (in order they are stored
8048	in the list). The first matched filter will determine the
8049	<link to="IHostUSBDeviceFilter::action">action</link>
8050	performed on the device.
8051
8052	Unless the device is ignored by these filters, filters of all
8053	currently running virtual machines
8054	(<link to="IUSBController::deviceFilters"/>) are applied to it.
8055
8056	<note>
8057	If USB functionality is not available in the given edition of
8058	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8059	</note>
8060
8061	<see><link to="IHostUSBDeviceFilter"/>,
8062	<link to="USBDeviceState"/></see>
8063	</desc>
8064	</attribute>
8065
8066	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
8067	<desc>List of host network interfaces currently defined on the host.</desc>
8068	</attribute>
8069
8070	<attribute name="processorCount" type="unsigned long" readonly="yes">
8071	<desc>Number of (logical) CPUs installed in the host system.</desc>
8072	</attribute>
8073
8074	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
8075	<desc>Number of (logical) CPUs online in the host system.</desc>
8076	</attribute>
8077
8078	<attribute name="processorCoreCount" type="unsigned long" readonly="yes">
8079	<desc>Number of physical processor cores installed in the host system.</desc>
8080	</attribute>
8081
8082	<method name="getProcessorSpeed">
8083	<desc>Query the (approximate) maximum speed of a specified host CPU in
8084	Megahertz.
8085	</desc>
8086	<param name="cpuId" type="unsigned long" dir="in">
8087	<desc>
8088	Identifier of the CPU.
8089	</desc>
8090	</param>
8091	<param name="speed" type="unsigned long" dir="return">
8092	<desc>
8093	Speed value. 0 is returned if value is not known or @a cpuId is
8094	invalid.
8095	</desc>
8096	</param>
8097	</method>
8098
8099	<method name="getProcessorFeature">
8100	<desc>Query whether a CPU feature is supported or not.</desc>
8101	<param name="feature" type="ProcessorFeature" dir="in">
8102	<desc>
8103	CPU Feature identifier.
8104	</desc>
8105	</param>
8106	<param name="supported" type="boolean" dir="return">
8107	<desc>
8108	Feature is supported or not.
8109	</desc>
8110	</param>
8111	</method>
8112
8113	<method name="getProcessorDescription">
8114	<desc>Query the model string of a specified host CPU.
8115	</desc>
8116	<param name="cpuId" type="unsigned long" dir="in">
8117	<desc>
8118	Identifier of the CPU.
8119	<note>
8120	The current implementation might not necessarily return the
8121	description for this exact CPU.
8122	</note>
8123	</desc>
8124	</param>
8125	<param name="description" type="wstring" dir="return">
8126	<desc>
8127	Model string. An empty string is returned if value is not known or
8128	@a cpuId is invalid.
8129	</desc>
8130	</param>
8131	</method>
8132
8133	<method name="getProcessorCPUIDLeaf">
8134	<desc>
8135	Returns the CPU cpuid information for the specified leaf.
8136	</desc>
8137	<param name="cpuId" type="unsigned long" dir="in">
8138	<desc>
8139	Identifier of the CPU. The CPU most be online.
8140	<note>
8141	The current implementation might not necessarily return the
8142	description for this exact CPU.
8143	</note>
8144	</desc>
8145	</param>
8146	<param name="leaf" type="unsigned long" dir="in">
8147	<desc>
8148	CPUID leaf index (eax).
8149	</desc>
8150	</param>
8151	<param name="subLeaf" type="unsigned long" dir="in">
8152	<desc>
8153	CPUID leaf sub index (ecx). This currently only applies to cache
8154	information on Intel CPUs. Use 0 if retrieving values for
8155	<link to="IMachine::setCPUIDLeaf"/>.
8156	</desc>
8157	</param>
8158	<param name="valEax" type="unsigned long" dir="out">
8159	<desc>
8160	CPUID leaf value for register eax.
8161	</desc>
8162	</param>
8163	<param name="valEbx" type="unsigned long" dir="out">
8164	<desc>
8165	CPUID leaf value for register ebx.
8166	</desc>
8167	</param>
8168	<param name="valEcx" type="unsigned long" dir="out">
8169	<desc>
8170	CPUID leaf value for register ecx.
8171	</desc>
8172	</param>
8173	<param name="valEdx" type="unsigned long" dir="out">
8174	<desc>
8175	CPUID leaf value for register edx.
8176	</desc>
8177	</param>
8178	</method>
8179
8180	<attribute name="memorySize" type="unsigned long" readonly="yes">
8181	<desc>Amount of system memory in megabytes installed in the host system.</desc>
8182	</attribute>
8183
8184	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
8185	<desc>Available system memory in the host system.</desc>
8186	</attribute>
8187
8188	<attribute name="operatingSystem" type="wstring" readonly="yes">
8189	<desc>Name of the host system's operating system.</desc>
8190	</attribute>
8191
8192	<attribute name="OSVersion" type="wstring" readonly="yes">
8193	<desc>Host operating system's version string.</desc>
8194	</attribute>
8195
8196	<attribute name="UTCTime" type="long long" readonly="yes">
8197	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
8198	</attribute>
8199
8200	<attribute name="acceleration3DAvailable" type="boolean" readonly="yes">
8201	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
8202	</attribute>
8203
8204	<method name="createHostOnlyNetworkInterface">
8205	<desc>
8206	Creates a new adapter for Host Only Networking.
8207	<result name="E_INVALIDARG">
8208	Host network interface @a name already exists.
8209	</result>
8210	</desc>
8211	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
8212	<desc>
8213	Created host interface object.
8214	</desc>
8215	</param>
8216	<param name="progress" type="IProgress" dir="return">
8217	<desc>
8218	Progress object to track the operation completion.
8219	</desc>
8220	</param>
8221	</method>
8222
8223	<method name="removeHostOnlyNetworkInterface">
8224	<desc>
8225	Removes the given Host Only Networking interface.
8226	<result name="VBOX_E_OBJECT_NOT_FOUND">
8227	No host network interface matching @a id found.
8228	</result>
8229	</desc>
8230	<param name="id" type="uuid" mod="string" dir="in">
8231	<desc>
8232	Adapter GUID.
8233	</desc>
8234	</param>
8235	<param name="progress" type="IProgress" dir="return">
8236	<desc>
8237	Progress object to track the operation completion.
8238	</desc>
8239	</param>
8240	</method>
8241
8242	<method name="createUSBDeviceFilter">
8243	<desc>
8244	Creates a new USB device filter. All attributes except
8245	the filter name are set to empty (any match),
8246	<i>active</i> is @c false (the filter is not active).
8247
8248	The created filter can be added to the list of filters using
8249	<link to="#insertUSBDeviceFilter"/>.
8250
8251	<see><link to="#USBDeviceFilters"/></see>
8252	</desc>
8253	<param name="name" type="wstring" dir="in">
8254	<desc>
8255	Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
8256	</desc>
8257	</param>
8258	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
8259	<desc>Created filter object.</desc>
8260	</param>
8261	</method>
8262
8263	<method name="insertUSBDeviceFilter">
8264	<desc>
8265	Inserts the given USB device to the specified position
8266	in the list of filters.
8267
8268	Positions are numbered starting from @c 0. If the specified
8269	position is equal to or greater than the number of elements in
8270	the list, the filter is added at the end of the collection.
8271
8272	<note>
8273	Duplicates are not allowed, so an attempt to insert a
8274	filter already in the list is an error.
8275	</note>
8276	<note>
8277	If USB functionality is not available in the given edition of
8278	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8279	</note>
8280
8281	<see><link to="#USBDeviceFilters"/></see>
8282
8283	<result name="VBOX_E_INVALID_OBJECT_STATE">
8284	USB device filter is not created within this VirtualBox instance.
8285	</result>
8286	<result name="E_INVALIDARG">
8287	USB device filter already in list.
8288	</result>
8289
8290	</desc>
8291	<param name="position" type="unsigned long" dir="in">
8292	<desc>Position to insert the filter to.</desc>
8293	</param>
8294	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
8295	<desc>USB device filter to insert.</desc>
8296	</param>
8297	</method>
8298
8299	<method name="removeUSBDeviceFilter">
8300	<desc>
8301	Removes a USB device filter from the specified position in the
8302	list of filters.
8303
8304	Positions are numbered starting from @c 0. Specifying a
8305	position equal to or greater than the number of elements in
8306	the list will produce an error.
8307
8308	<note>
8309	If USB functionality is not available in the given edition of
8310	VirtualBox, this method will set the result code to @c E_NOTIMPL.
8311	</note>
8312
8313	<see><link to="#USBDeviceFilters"/></see>
8314
8315	<result name="E_INVALIDARG">
8316	USB device filter list empty or invalid @a position.
8317	</result>
8318
8319	</desc>
8320	<param name="position" type="unsigned long" dir="in">
8321	<desc>Position to remove the filter from.</desc>
8322	</param>
8323	</method>
8324
8325	<method name="findHostDVDDrive">
8326	<desc>
8327	Searches for a host DVD drive with the given @c name.
8328
8329	<result name="VBOX_E_OBJECT_NOT_FOUND">
8330	Given @c name does not correspond to any host drive.
8331	</result>
8332
8333	</desc>
8334	<param name="name" type="wstring" dir="in">
8335	<desc>Name of the host drive to search for</desc>
8336	</param>
8337	<param name="drive" type="IMedium" dir="return">
8338	<desc>Found host drive object</desc>
8339	</param>
8340	</method>
8341
8342	<method name="findHostFloppyDrive">
8343	<desc>
8344	Searches for a host floppy drive with the given @c name.
8345
8346	<result name="VBOX_E_OBJECT_NOT_FOUND">
8347	Given @c name does not correspond to any host floppy drive.
8348	</result>
8349
8350	</desc>
8351	<param name="name" type="wstring" dir="in">
8352	<desc>Name of the host floppy drive to search for</desc>
8353	</param>
8354	<param name="drive" type="IMedium" dir="return">
8355	<desc>Found host floppy drive object</desc>
8356	</param>
8357	</method>
8358
8359	<method name="findHostNetworkInterfaceByName">
8360	<desc>
8361	Searches through all host network interfaces for an interface with
8362	the given @c name.
8363	<note>
8364	The method returns an error if the given @c name does not
8365	correspond to any host network interface.
8366	</note>
8367	</desc>
8368	<param name="name" type="wstring" dir="in">
8369	<desc>Name of the host network interface to search for.</desc>
8370	</param>
8371	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8372	<desc>Found host network interface object.</desc>
8373	</param>
8374	</method>
8375	<method name="findHostNetworkInterfaceById">
8376	<desc>
8377	Searches through all host network interfaces for an interface with
8378	the given GUID.
8379	<note>
8380	The method returns an error if the given GUID does not
8381	correspond to any host network interface.
8382	</note>
8383	</desc>
8384	<param name="id" type="uuid" mod="string" dir="in">
8385	<desc>GUID of the host network interface to search for.</desc>
8386	</param>
8387	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8388	<desc>Found host network interface object.</desc>
8389	</param>
8390	</method>
8391	<method name="findHostNetworkInterfacesOfType">
8392	<desc>
8393	Searches through all host network interfaces and returns a list of interfaces of the specified type
8394	</desc>
8395	<param name="type" type="HostNetworkInterfaceType" dir="in">
8396	<desc>type of the host network interfaces to search for.</desc>
8397	</param>
8398	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
8399	<desc>Found host network interface objects.</desc>
8400	</param>
8401	</method>
8402
8403	<method name="findUSBDeviceById">
8404	<desc>
8405	Searches for a USB device with the given UUID.
8406
8407	<result name="VBOX_E_OBJECT_NOT_FOUND">
8408	Given @c id does not correspond to any USB device.
8409	</result>
8410
8411	<see><link to="IUSBDevice::id"/></see>
8412	</desc>
8413	<param name="id" type="uuid" mod="string" dir="in">
8414	<desc>UUID of the USB device to search for.</desc>
8415	</param>
8416	<param name="device" type="IHostUSBDevice" dir="return">
8417	<desc>Found USB device object.</desc>
8418	</param>
8419	</method>
8420
8421	<method name="findUSBDeviceByAddress">
8422	<desc>
8423	Searches for a USB device with the given host address.
8424
8425	<result name="VBOX_E_OBJECT_NOT_FOUND">
8426	Given @c name does not correspond to any USB device.
8427	</result>
8428
8429	<see><link to="IUSBDevice::address"/></see>
8430	</desc>
8431	<param name="name" type="wstring" dir="in">
8432	<desc>
8433	Address of the USB device (as assigned by the host) to
8434	search for.
8435	</desc>
8436	</param>
8437	<param name="device" type="IHostUSBDevice" dir="return">
8438	<desc>Found USB device object.</desc>
8439	</param>
8440	</method>
8441
8442	<method name="generateMACAddress">
8443	<desc>
8444	Generates a valid Ethernet MAC address, 12 hexadecimal characters.
8445	</desc>
8446	<param name="address" type="wstring" dir="return">
8447	<desc>New Ethernet MAC address.</desc>
8448	</param>
8449	</method>
8450
8451	</interface>
8452
8453	<!--
8454	// ISystemProperties
8455	/////////////////////////////////////////////////////////////////////////
8456	-->
8457
8458	<interface
8459	name="ISystemProperties"
8460	extends="$unknown"
8461	uuid="413ea94c-efd9-491e-81fc-5df0c4d864bb"
8462	wsmap="managed"
8463	>
8464	<desc>
8465	The ISystemProperties interface represents global properties of the given
8466	VirtualBox installation.
8467
8468	These properties define limits and default values for various attributes
8469	and parameters. Most of the properties are read-only, but some can be
8470	changed by a user.
8471	</desc>
8472
8473	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
8474	<desc>Minimum guest system memory in Megabytes.</desc>
8475	</attribute>
8476
8477	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
8478	<desc>Maximum guest system memory in Megabytes.</desc>
8479	</attribute>
8480
8481	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
8482	<desc>Minimum guest video memory in Megabytes.</desc>
8483	</attribute>
8484
8485	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
8486	<desc>Maximum guest video memory in Megabytes.</desc>
8487	</attribute>
8488
8489	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
8490	<desc>Minimum CPU count.</desc>
8491	</attribute>
8492
8493	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
8494	<desc>Maximum CPU count.</desc>
8495	</attribute>
8496
8497	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8498	<desc>Maximum of monitors which could be connected.</desc>
8499	</attribute>
8500
8501	<attribute name="infoVDSize" type="long long" readonly="yes">
8502	<desc>Maximum size of a virtual disk image in bytes. Informational value,
8503	does not reflect the limits of any virtual disk image format.</desc>
8504	</attribute>
8505
8506	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8507	<desc>
8508	Maximum number of serial ports associated with every
8509	<link to="IMachine"/> instance.
8510	</desc>
8511	</attribute>
8512
8513	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8514	<desc>
8515	Maximum number of parallel ports associated with every
8516	<link to="IMachine"/> instance.
8517	</desc>
8518	</attribute>
8519
8520	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8521	<desc>
8522	Maximum device position in the boot order. This value corresponds
8523	to the total number of devices a machine can boot from, to make it
8524	possible to include all possible devices to the boot list.
8525	<see><link to="IMachine::setBootOrder"/></see>
8526	</desc>
8527	</attribute>
8528
8529	<attribute name="defaultMachineFolder" type="wstring">
8530	<desc>
8531	Full path to the default directory used to create new or open
8532	existing machines when a machine settings file name contains no
8533	path.
8534
8535	Starting with VirtualBox 4.0, by default, this attribute contains
8536	the full path of folder named "VirtualBox VMs" in the user's
8537	home directory, which depends on the host platform.
8538
8539	When setting this attribute, a full path must be specified.
8540	Setting this property to @c null or an empty string or the
8541	special value "Machines" (for compatibility reasons) will restore
8542	that default value.
8543
8544	If the folder specified herein does not exist, it will be created
8545	automatically as needed.
8546
8547	<see>
8548	<link to="IVirtualBox::createMachine"/>,
8549	<link to="IVirtualBox::openMachine"/>
8550	</see>
8551	</desc>
8552	</attribute>
8553
8554	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8555	<desc>
8556	List of all medium storage formats supported by this VirtualBox
8557	installation.
8558
8559	Keep in mind that the medium format identifier
8560	(<link to="IMediumFormat::id"/>) used in other API calls like
8561	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8562	medium format is a case-insensitive string. This means that, for
8563	example, all of the following strings:
8564	<pre>
8565	"VDI"
8566	"vdi"
8567	"VdI"</pre>
8568	refer to the same medium format.
8569
8570	Note that the virtual medium framework is backend-based, therefore
8571	the list of supported formats depends on what backends are currently
8572	installed.
8573
8574	<see><link to="IMediumFormat"/></see>
8575	</desc>
8576	</attribute>
8577
8578	<attribute name="defaultHardDiskFormat" type="wstring">
8579	<desc>
8580	Identifier of the default medium format used by VirtualBox.
8581
8582	The medium format set by this attribute is used by VirtualBox
8583	when the medium format was not specified explicitly. One example is
8584	<link to="IVirtualBox::createHardDisk"/> with the empty
8585	format argument. A more complex example is implicit creation of
8586	differencing media when taking a snapshot of a virtual machine:
8587	this operation will try to use a format of the parent medium first
8588	and if this format does not support differencing media the default
8589	format specified by this argument will be used.
8590
8591	The list of supported medium formats may be obtained by the
8592	<link to="#mediumFormats"/> call. Note that the default medium
8593	format must have a capability to create differencing media;
8594	otherwise operations that create media implicitly may fail
8595	unexpectedly.
8596
8597	The initial value of this property is <tt>"VDI"</tt> in the current
8598	version of the VirtualBox product, but may change in the future.
8599
8600	<note>
8601	Setting this property to @c null or empty string will restore the
8602	initial value.
8603	</note>
8604
8605	<see>
8606	<link to="#mediumFormats"/>,
8607	<link to="IMediumFormat::id"/>,
8608	<link to="IVirtualBox::createHardDisk"/>
8609	</see>
8610	</desc>
8611	</attribute>
8612
8613	<attribute name="freeDiskSpaceWarning" type="long long">
8614	<desc>Issue a warning if the free disk space is below (or in some disk
8615	intensive operation is expected to go below) the given size in
8616	bytes.</desc>
8617	</attribute>
8618
8619	<attribute name="freeDiskSpacePercentWarning" type="unsigned 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 percentage.</desc>
8622	</attribute>
8623
8624	<attribute name="freeDiskSpaceError" type="long long">
8625	<desc>Issue an error if the free disk space is below (or in some disk
8626	intensive operation is expected to go below) the given size in
8627	bytes.</desc>
8628	</attribute>
8629
8630	<attribute name="freeDiskSpacePercentError" type="unsigned 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 percentage.</desc>
8633	</attribute>
8634
8635	<attribute name="VRDEAuthLibrary" type="wstring">
8636	<desc>
8637	Library that provides authentication for Remote Desktop clients. The library
8638	is used if a virtual machine's authentication type is set to "external"
8639	in the VM RemoteDisplay configuration.
8640
8641	The system library extension (".DLL" or ".so") must be omitted.
8642	A full path can be specified; if not, then the library must reside on the
8643	system's default library path.
8644
8645	The default value of this property is <tt>"VBoxAuth"</tt>. There is a library
8646	of that name in one of the default VirtualBox library directories.
8647
8648	For details about VirtualBox authentication libraries and how to implement
8649	them, please refer to the VirtualBox manual.
8650
8651	<note>
8652	Setting this property to @c null or empty string will restore the
8653	initial value.
8654	</note>
8655	</desc>
8656	</attribute>
8657
8658	<attribute name="webServiceAuthLibrary" type="wstring">
8659	<desc>
8660	Library that provides authentication for webservice clients. The library
8661	is used if a virtual machine's authentication type is set to "external"
8662	in the VM RemoteDisplay configuration and will be called from
8663	within the <link to="IWebsessionManager::logon" /> implementation.
8664
8665	As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
8666	there is no per-VM setting for this, as the webservice is a global
8667	resource (if it is running). Only for this setting (for the webservice),
8668	setting this value to a literal <tt>"null"</tt> string disables authentication,
8669	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8670	no matter what user name and password are supplied.
8671
8672	The initial value of this property is <tt>"VBoxAuth"</tt>,
8673	meaning that the webservice will use the same authentication
8674	library that is used by default for VRDE (again, see
8675	<link to="ISystemProperties::VRDEAuthLibrary" />).
8676	The format and calling convention of authentication libraries
8677	is the same for the webservice as it is for VRDE.
8678
8679	<note>
8680	Setting this property to @c null or empty string will restore the
8681	initial value.
8682	</note>
8683	</desc>
8684	</attribute>
8685
8686	<attribute name="defaultVRDEExtPack" type="wstring">
8687	<desc>
8688	The name of the extension pack providing the default VRDE.
8689
8690	This attribute is for choosing between multiple extension packs
8691	providing VRDE. If only one is installed, it will automatically be the
8692	default one. The attribute value can be empty if no VRDE extension
8693	pack is installed.
8694
8695	For details about VirtualBox Remote Desktop Extension and how to
8696	implement one, please refer to the VirtualBox SDK.
8697	</desc>
8698	</attribute>
8699
8700	<attribute name="logHistoryCount" type="unsigned long">
8701	<desc>
8702	This value specifies how many old release log files are kept.
8703	</desc>
8704	</attribute>
8705
8706	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8707	<desc>This value hold the default audio driver for the current
8708	system.</desc>
8709	</attribute>
8710
8711	<attribute name="autostartDatabasePath" type="wstring">
8712	<desc>
8713	The path to the autostart database. Depending on the host this might
8714	be a filesystem path or something else.
8715	</desc>
8716	</attribute>
8717
8718	<attribute name="defaultAdditionsISO" type="wstring">
8719	<desc>
8720	The path to the default Guest Additions ISO image. Can be empty if
8721	the location is not known in this installation.
8722	</desc>
8723	</attribute>
8724
8725	<attribute name="defaultFrontend" type="wstring">
8726	<desc>
8727	Selects which VM frontend should be used by default when launching
8728	a VM through the <link to="IMachine::launchVMProcess" /> method.
8729	Empty or @c null strings do not define a particular default, it is up
8730	to <link to="IMachine::launchVMProcess" /> to select one. See the
8731	description of <link to="IMachine::launchVMProcess" /> for the valid
8732	frontend types.
8733
8734	This global setting is overridden by the per-VM attribute
8735	<link to="IMachine::defaultFrontend" /> or a frontend type
8736	passed to <link to="IMachine::launchVMProcess" />.
8737	</desc>
8738	</attribute>
8739
8740	<method name="getMaxNetworkAdapters">
8741	<desc>
8742	Maximum total number of network adapters associated with every
8743	<link to="IMachine"/> instance.
8744	</desc>
8745
8746	<param name="chipset" type="ChipsetType" dir="in">
8747	<desc>The chipset type to get the value for.</desc>
8748	</param>
8749
8750
8751	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8752	<desc>The maximum total number of network adapters allowed.</desc>
8753	</param>
8754
8755	</method>
8756
8757	<method name="getMaxNetworkAdaptersOfType">
8758	<desc>
8759	Maximum number of network adapters of a given attachment type,
8760	associated with every <link to="IMachine"/> instance.
8761	</desc>
8762
8763	<param name="chipset" type="ChipsetType" dir="in">
8764	<desc>The chipset type to get the value for.</desc>
8765	</param>
8766
8767	<param name="type" type="NetworkAttachmentType" dir="in">
8768	<desc>Type of attachment.</desc>
8769	</param>
8770
8771	<param name="maxNetworkAdapters" type="unsigned long" dir="return">
8772	<desc>The maximum number of network adapters allowed for
8773	particular chipset and attachment type.</desc>
8774	</param>
8775
8776	</method>
8777
8778
8779	<method name="getMaxDevicesPerPortForStorageBus">
8780	<desc>Returns the maximum number of devices which can be attached to a port
8781	for the given storage bus.</desc>
8782
8783	<param name="bus" type="StorageBus" dir="in">
8784	<desc>The storage bus type to get the value for.</desc>
8785	</param>
8786
8787	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8788	<desc>The maximum number of devices which can be attached to the port for the given
8789	storage bus.</desc>
8790	</param>
8791	</method>
8792
8793	<method name="getMinPortCountForStorageBus">
8794	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8795
8796	<param name="bus" type="StorageBus" dir="in">
8797	<desc>The storage bus type to get the value for.</desc>
8798	</param>
8799
8800	<param name="minPortCount" type="unsigned long" dir="return">
8801	<desc>The minimum number of ports for the given storage bus.</desc>
8802	</param>
8803	</method>
8804
8805	<method name="getMaxPortCountForStorageBus">
8806	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8807
8808	<param name="bus" type="StorageBus" dir="in">
8809	<desc>The storage bus type to get the value for.</desc>
8810	</param>
8811
8812	<param name="maxPortCount" type="unsigned long" dir="return">
8813	<desc>The maximum number of ports for the given storage bus.</desc>
8814	</param>
8815	</method>
8816
8817	<method name="getMaxInstancesOfStorageBus">
8818	<desc>Returns the maximum number of storage bus instances which
8819	can be configured for each VM. This corresponds to the number of
8820	storage controllers one can have. Value may depend on chipset type
8821	used.</desc>
8822
8823	<param name="chipset" type="ChipsetType" dir="in">
8824	<desc>The chipset type to get the value for.</desc>
8825	</param>
8826
8827	<param name="bus" type="StorageBus" dir="in">
8828	<desc>The storage bus type to get the value for.</desc>
8829	</param>
8830
8831	<param name="maxInstances" type="unsigned long" dir="return">
8832	<desc>The maximum number of instances for the given storage bus.</desc>
8833	</param>
8834	</method>
8835
8836	<method name="getDeviceTypesForStorageBus">
8837	<desc>Returns list of all the supported device types
8838	(<link to="DeviceType"/>) for the given type of storage
8839	bus.</desc>
8840
8841	<param name="bus" type="StorageBus" dir="in">
8842	<desc>The storage bus type to get the value for.</desc>
8843	</param>
8844
8845	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8846	<desc>The list of all supported device types for the given storage bus.</desc>
8847	</param>
8848	</method>
8849
8850	<method name="getDefaultIoCacheSettingForStorageController">
8851	<desc>Returns the default I/O cache setting for the
8852	given storage controller</desc>
8853
8854	<param name="controllerType" type="StorageControllerType" dir="in">
8855	<desc>The storage controller to the setting for.</desc>
8856	</param>
8857
8858	<param name="enabled" type="boolean" dir="return">
8859	<desc>Returned flag indicating the default value</desc>
8860	</param>
8861	</method>
8862	</interface>
8863
8864	<!--
8865	// IGuest
8866	/////////////////////////////////////////////////////////////////////////
8867	-->
8868
8869	<interface
8870	name="IGuestOSType" extends="$unknown"
8871	uuid="6d968f9a-858b-4c50-bf17-241f069e94c2"
8872	wsmap="struct"
8873	>
8874	<desc>
8875	</desc>
8876
8877	<attribute name="familyId" type="wstring" readonly="yes">
8878	<desc>Guest OS family identifier string.</desc>
8879	</attribute>
8880
8881	<attribute name="familyDescription" type="wstring" readonly="yes">
8882	<desc>Human readable description of the guest OS family.</desc>
8883	</attribute>
8884
8885	<attribute name="id" type="wstring" readonly="yes">
8886	<desc>Guest OS identifier string.</desc>
8887	</attribute>
8888
8889	<attribute name="description" type="wstring" readonly="yes">
8890	<desc>Human readable description of the guest OS.</desc>
8891	</attribute>
8892
8893	<attribute name="is64Bit" type="boolean" readonly="yes">
8894	<desc>Returns @c true if the given OS is 64-bit</desc>
8895	</attribute>
8896
8897	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8898	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8899	</attribute>
8900
8901	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8902	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8903	</attribute>
8904
8905	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8906	<desc>Recommended RAM size in Megabytes.</desc>
8907	</attribute>
8908
8909	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8910	<desc>Recommended video RAM size in Megabytes.</desc>
8911	</attribute>
8912
8913	<attribute name="recommended2DVideoAcceleration" type="boolean" readonly="yes">
8914	<desc>Returns @c true if 2D video acceleration is recommended for this OS type.</desc>
8915	</attribute>
8916
8917	<attribute name="recommended3DAcceleration" type="boolean" readonly="yes">
8918	<desc>Returns @c true if 3D acceleration is recommended for this OS type.</desc>
8919	</attribute>
8920
8921	<attribute name="recommendedHDD" type="long long" readonly="yes">
8922	<desc>Recommended hard disk size in bytes.</desc>
8923	</attribute>
8924
8925	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8926	<desc>Returns recommended network adapter for this OS type.</desc>
8927	</attribute>
8928
8929	<attribute name="recommendedPAE" type="boolean" readonly="yes">
8930	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8931	</attribute>
8932
8933	<attribute name="recommendedDVDStorageController" type="StorageControllerType" readonly="yes">
8934	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8935	</attribute>
8936
8937	<attribute name="recommendedDVDStorageBus" type="StorageBus" readonly="yes">
8938	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8939	</attribute>
8940
8941	<attribute name="recommendedHDStorageController" type="StorageControllerType" readonly="yes">
8942	<desc>Recommended storage controller type for HD drives.</desc>
8943	</attribute>
8944
8945	<attribute name="recommendedHDStorageBus" type="StorageBus" readonly="yes">
8946	<desc>Recommended storage bus type for HD drives.</desc>
8947	</attribute>
8948
8949	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8950	<desc>Recommended firmware type.</desc>
8951	</attribute>
8952
8953	<attribute name="recommendedUSBHID" type="boolean" readonly="yes">
8954	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8955	</attribute>
8956
8957	<attribute name="recommendedHPET" type="boolean" readonly="yes">
8958	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8959	</attribute>
8960
8961	<attribute name="recommendedUSBTablet" type="boolean" readonly="yes">
8962	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8963	</attribute>
8964
8965	<attribute name="recommendedRTCUseUTC" type="boolean" readonly="yes">
8966	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8967	</attribute>
8968
8969	<attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
8970	<desc>Recommended chipset type.</desc>
8971	</attribute>
8972
8973	<attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
8974	<desc>Recommended audio type.</desc>
8975	</attribute>
8976
8977	<attribute name="recommendedFloppy" type="boolean" readonly="yes">
8978	<desc>Returns @c true a floppy drive is recommended for this OS type.</desc>
8979	</attribute>
8980
8981	<attribute name="recommendedUSB" type="boolean" readonly="yes">
8982	<desc>Returns @c true a USB controller is recommended for this OS type.</desc>
8983	</attribute>
8984
8985	</interface>
8986
8987	<enum
8988	name="AdditionsFacilityType"
8989	uuid="98f7f957-89fb-49b6-a3b1-31e3285eb1d8"
8990	>
8991	<desc>
8992	Guest Additions facility IDs.
8993	</desc>
8994
8995	<const name="None" value="0">
8996	<desc>No/invalid facility.</desc>
8997	</const>
8998	<const name="VBoxGuestDriver" value="20">
8999	<desc>VirtualBox base driver (VBoxGuest).</desc>
9000	</const>
9001	<const name="AutoLogon" value="90">
9002	<desc>Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox).</desc>
9003	</const>
9004	<const name="VBoxService" value="100">
9005	<desc>VirtualBox system service (VBoxService).</desc>
9006	</const>
9007	<const name="VBoxTrayClient" value="101">
9008	<desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc>
9009	</const>
9010	<const name="Seamless" value="1000">
9011	<desc>Seamless guest desktop integration.</desc>
9012	</const>
9013	<const name="Graphics" value="1100">
9014	<desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints
9015	are not immediately acted on and guest display resizes are probably not initiated by
9016	the guest additions.
9017	</desc>
9018	</const>
9019	<const name="All" value="2147483646">
9020	<desc>All facilities selected.</desc>
9021	</const>
9022	</enum>
9023
9024	<enum
9025	name="AdditionsFacilityClass"
9026	uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f"
9027	>
9028	<desc>
9029	Guest Additions facility classes.
9030	</desc>
9031
9032	<const name="None" value="0">
9033	<desc>No/invalid class.</desc>
9034	</const>
9035	<const name="Driver" value="10">
9036	<desc>Driver.</desc>
9037	</const>
9038	<const name="Service" value="30">
9039	<desc>System service.</desc>
9040	</const>
9041	<const name="Program" value="50">
9042	<desc>Program.</desc>
9043	</const>
9044	<const name="Feature" value="100">
9045	<desc>Feature.</desc>
9046	</const>
9047	<const name="ThirdParty" value="999">
9048	<desc>Third party.</desc>
9049	</const>
9050	<const name="All" value="2147483646">
9051	<desc>All facility classes selected.</desc>
9052	</const>
9053	</enum>
9054
9055	<enum
9056	name="AdditionsFacilityStatus"
9057	uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde"
9058	>
9059	<desc>
9060	Guest Additions facility states.
9061	</desc>
9062
9063	<const name="Inactive" value="0">
9064	<desc>Facility is not active.</desc>
9065	</const>
9066	<const name="Paused" value="1">
9067	<desc>Facility has been paused.</desc>
9068	</const>
9069	<const name="PreInit" value="20">
9070	<desc>Facility is preparing to initialize.</desc>
9071	</const>
9072	<const name="Init" value="30">
9073	<desc>Facility is initializing.</desc>
9074	</const>
9075	<const name="Active" value="50">
9076	<desc>Facility is up and running.</desc>
9077	</const>
9078	<const name="Terminating" value="100">
9079	<desc>Facility is shutting down.</desc>
9080	</const>
9081	<const name="Terminated" value="101">
9082	<desc>Facility successfully shut down.</desc>
9083	</const>
9084	<const name="Failed" value="800">
9085	<desc>Facility failed to start.</desc>
9086	</const>
9087	<const name="Unknown" value="999">
9088	<desc>Facility status is unknown.</desc>
9089	</const>
9090	</enum>
9091
9092	<interface
9093	name="IAdditionsFacility" extends="$unknown"
9094	uuid="54992946-6af1-4e49-98ec-58b558b7291e"
9095	wsmap="struct"
9096	>
9097	<desc>
9098	Structure representing a Guest Additions facility.
9099	</desc>
9100
9101	<attribute name="classType" type="AdditionsFacilityClass" readonly="yes">
9102	<desc>The class this facility is part of.</desc>
9103	</attribute>
9104
9105	<attribute name="lastUpdated" type="long long" readonly="yes">
9106	<desc>
9107	Time stamp of the last status update,
9108	in milliseconds since 1970-01-01 UTC.
9109	</desc>
9110	</attribute>
9111
9112	<attribute name="name" type="wstring" readonly="yes">
9113	<desc>The facility's friendly name.</desc>
9114	</attribute>
9115
9116	<attribute name="status" type="AdditionsFacilityStatus" readonly="yes">
9117	<desc>The current status.</desc>
9118	</attribute>
9119
9120	<attribute name="type" type="AdditionsFacilityType" readonly="yes">
9121	<desc>The facility's type ID.</desc>
9122	</attribute>
9123	</interface>
9124
9125	<enum
9126	name="AdditionsRunLevelType"
9127	uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
9128	>
9129	<desc>
9130	Guest Additions run level type.
9131	</desc>
9132
9133	<const name="None" value="0">
9134	<desc>Guest Additions are not loaded.</desc>
9135	</const>
9136	<const name="System" value="1">
9137	<desc>Guest drivers are loaded.</desc>
9138	</const>
9139	<const name="Userland" value="2">
9140	<desc>Common components (such as application services) are loaded.</desc>
9141	</const>
9142	<const name="Desktop" value="3">
9143	<desc>Per-user desktop components are loaded.</desc>
9144	</const>
9145	</enum>
9146
9147	<enum
9148	name="AdditionsUpdateFlag"
9149	uuid="726a818d-18d6-4389-94e8-3e9e6826171a"
9150	>
9151	<desc>
9152	Guest Additions update flags.
9153	</desc>
9154
9155	<const name="None" value="0">
9156	<desc>No flag set.</desc>
9157	</const>
9158	<const name="WaitForUpdateStartOnly" value="1">
9159	<desc>Starts the regular updating process and waits until the
9160	actual Guest Additions update inside the guest was started.
9161	This can be necessary due to needed interaction with the guest
9162	OS during the installation phase.</desc>
9163	</const>
9164	</enum>
9165
9166	<enum
9167	name="GuestSessionStatus"
9168	uuid="ac2669da-4624-44f2-85b5-0b0bfb8d8673"
9169	>
9170	<desc>
9171	Guest session status. This enumeration represents possible values of
9172	the <link to="IGuestSession::status"/> attribute.
9173	</desc>
9174	<const name="Undefined" value="0">
9175	<desc>Guest session is in an undefined state.</desc>
9176	</const>
9177	<const name="Starting" value="10">
9178	<desc>Guest session is being started.</desc>
9179	</const>
9180	<const name="Started" value="100">
9181	<desc>Guest session has been started.</desc>
9182	</const>
9183	<const name="Terminating" value="480">
9184	<desc>Guest session is being terminated.</desc>
9185	</const>
9186	<const name="Terminated" value="500">
9187	<desc>Guest session terminated normally.</desc>
9188	</const>
9189	<const name="TimedOutKilled" value="512">
9190	<desc>Guest session timed out and was killed.</desc>
9191	</const>
9192	<const name="TimedOutAbnormally" value="513">
9193	<desc>Guest session timed out and was not killed successfully.</desc>
9194	</const>
9195	<const name="Down" value="600">
9196	<desc>Service/OS is stopping, guest session was killed.</desc>
9197	</const>
9198	<const name="Error" value="800">
9199	<desc>Something went wrong.</desc>
9200	</const>
9201	</enum>
9202
9203	<enum
9204	name="GuestSessionWaitForFlag"
9205	uuid="bb7a372a-f635-4e11-a81a-e707f3a52ef5"
9206	>
9207	<desc>
9208	Guest session waiting flags. Multiple flags can be combined.
9209	</desc>
9210
9211	<const name="None" value="0">
9212	<desc>No waiting flags specified. Do not use this.</desc>
9213	</const>
9214	<const name="Start" value="1">
9215	<desc>Wait for the guest session being started.</desc>
9216	</const>
9217	<const name="Terminate" value="2">
9218	<desc>Wait for the guest session being terminated.</desc>
9219	</const>
9220	<const name="Status" value="4">
9221	<desc>Wait for the next guest session status change.</desc>
9222	</const>
9223	</enum>
9224
9225	<enum
9226	name="GuestSessionWaitResult"
9227	uuid="c0f6a8a5-fdb6-42bf-a582-56c6f82bcd2d"
9228	>
9229	<desc>
9230	Guest session waiting results. Depending on the session waiting flags (for
9231	more information see <link to="GuestSessionWaitForFlag"/>) the waiting result
9232	can vary based on the session's current status.
9233
9234	To wait for a guest session to terminate after it has been
9235	created by <link to="IGuest::createSession"/> one would specify
9236	GuestSessionWaitResult_Terminate.
9237	</desc>
9238
9239	<const name="None" value="0">
9240	<desc>No result was returned. Not being used.</desc>
9241	</const>
9242	<const name="Start" value="1">
9243	<desc>The guest session has been started.</desc>
9244	</const>
9245	<const name="Terminate" value="2">
9246	<desc>The guest session has been terminated.</desc>
9247	</const>
9248	<const name="Status" value="3">
9249	<desc>
9250	The guest session has changed its status. The status then can
9251	be retrieved via <link to="IGuestSession::status"/>.
9252	</desc>
9253	</const>
9254	<const name="Error" value="4">
9255	<desc>Error while executing the process.</desc>
9256	</const>
9257	<const name="Timeout" value="5">
9258	<desc>
9259	The waiting operation timed out. This also will happen
9260	when no event has been occured matching the
9261	current waiting flags in a <link to="IGuestSession::waitFor"/> call.
9262	</desc>
9263	</const>
9264	<const name="WaitFlagNotSupported" value="6">
9265	<desc>
9266	A waiting flag specified in the <link to="IGuestSession::waitFor"/> call
9267	is not supported by the guest.
9268	</desc>
9269	</const>
9270	</enum>
9271
9272	<enum
9273	name="FileSeekType"
9274	uuid="1b73f4f3-3515-4073-a506-76878d9e2541"
9275	>
9276	<desc>
9277	File seeking types.
9278	</desc>
9279
9280	<const name="Set" value="0">
9281	<desc>Seek from the start of the file.</desc>
9282	</const>
9283	<const name="Current" value="1">
9284	<desc>Seek from the current file position.</desc>
9285	</const>
9286	</enum>
9287
9288	<enum
9289	name="ProcessInputFlag"
9290	uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
9291	>
9292	<desc>
9293	Guest process input flags.
9294	</desc>
9295	<const name="None" value="0">
9296	<desc>No flag set.</desc>
9297	</const>
9298	<const name="EndOfFile" value="1">
9299	<desc>End of file (input) reached.</desc>
9300	</const>
9301	</enum>
9302
9303	<enum
9304	name="ProcessOutputFlag"
9305	uuid="9979e85a-52bb-40b7-870c-57115e27e0f1"
9306	>
9307	<desc>
9308	Guest process output flags for specifying which
9309	type of output to retrieve.
9310	</desc>
9311	<const name="None" value="0">
9312	<desc>No flags set. Get output from stdout.</desc>
9313	</const>
9314	<const name="StdErr" value="1">
9315	<desc>Get output from stderr.</desc>
9316	</const>
9317	</enum>
9318
9319	<enum
9320	name="ProcessWaitForFlag"
9321	uuid="23b550c7-78e1-437e-98f0-65fd9757bcd2"
9322	>
9323	<desc>
9324	Process waiting flags. Multiple flags can be combined.
9325	</desc>
9326
9327	<const name="None" value="0">
9328	<desc>No waiting flags specified. Do not use this.</desc>
9329	</const>
9330	<const name="Start" value="1">
9331	<desc>Wait for the process being started.</desc>
9332	</const>
9333	<const name="Terminate" value="2">
9334	<desc>Wait for the process being terminated.</desc>
9335	</const>
9336	<const name="StdIn" value="4">
9337	<desc>Wait for stdin becoming available.</desc>
9338	</const>
9339	<const name="StdOut" value="8">
9340	<desc>Wait for data becoming available on stdout.</desc>
9341	</const>
9342	<const name="StdErr" value="16">
9343	<desc>Wait for data becoming available on stderr.</desc>
9344	</const>
9345	</enum>
9346
9347	<enum
9348	name="ProcessWaitResult"
9349	uuid="40719cbe-f192-4fe9-a231-6697b3c8e2b4"
9350	>
9351	<desc>
9352	Process waiting results. Depending on the process waiting flags (for
9353	more information see <link to="ProcessWaitForFlag"/>) the waiting result
9354	can vary based on the processes' current status.
9355
9356	To wait for a guest process to terminate after it has been
9357	created by <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>
9358	one would specify ProcessWaitResult_Terminate.
9359
9360	If a guest process has been started with ProcessCreateFlag_WaitForStdOut
9361	a client can wait with ProcessWaitResult_StdOut for new data to arrive on
9362	stdout; same applies for ProcessCreateFlag_WaitForStdErr and
9363	ProcessWaitResult_StdErr.
9364	</desc>
9365
9366	<const name="None" value="0">
9367	<desc>No result was returned. Not being used.</desc>
9368	</const>
9369	<const name="Start" value="1">
9370	<desc>The process has been started.</desc>
9371	</const>
9372	<const name="Terminate" value="2">
9373	<desc>The process has been terminated.</desc>
9374	</const>
9375	<const name="Status" value="3">
9376	<desc>
9377	The process has changed its status. The status then can
9378	be retrieved via <link to="IProcess::status"/>.
9379	</desc>
9380	</const>
9381	<const name="Error" value="4">
9382	<desc>Error while executing the process.</desc>
9383	</const>
9384	<const name="Timeout" value="5">
9385	<desc>
9386	The waiting operation timed out. This also will happen
9387	when no event has been occured matching the
9388	current waiting flags in a <link to="IProcess::waitFor"/> call.
9389	</desc>
9390	</const>
9391	<const name="StdIn" value="6">
9392	<desc>
9393	The process signalled that stdin became available for writing
9394	and that the process awaits input now.</desc>
9395	</const>
9396	<const name="StdOut" value="7">
9397	<desc>Data on stdout became available for reading.</desc>
9398	</const>
9399	<const name="StdErr" value="8">
9400	<desc>Data on stderr became available for reading.</desc>
9401	</const>
9402	<const name="WaitFlagNotSupported" value="9">
9403	<desc>
9404	A waiting flag specified in the <link to="IProcess::waitFor"/> call
9405	is not supported by the guest.
9406	</desc>
9407	</const>
9408	</enum>
9409
9410	<enum
9411	name="CopyFileFlag"
9412	uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
9413	>
9414	<desc>
9415	File copying flags.
9416	</desc>
9417	<const name="None" value="0">
9418	<desc>No flag set.</desc>
9419	</const>
9420	<const name="Recursive" value="1">
9421	<desc>Copy directories recursively.</desc>
9422	</const>
9423	<const name="Update" value="2">
9424	<desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc>
9425	</const>
9426	<const name="FollowLinks" value="4">
9427	<desc>Follow symbolic links.</desc>
9428	</const>
9429	</enum>
9430
9431	<enum
9432	name="DirectoryCreateFlag"
9433	uuid="bd721b0e-ced5-4f79-b368-249897c32a36"
9434	>
9435	<desc>
9436	Directory creation flags.
9437	</desc>
9438	<const name="None" value="0">
9439	<desc>No flag set.</desc>
9440	</const>
9441	<const name="Parents" value="1">
9442	<desc>No error if existing, make parent directories as needed.</desc>
9443	</const>
9444	</enum>
9445
9446	<enum
9447	name="DirectoryRemoveRecFlag"
9448	uuid="455aabf0-7692-48f6-9061-f21579b65769"
9449	>
9450	<desc>
9451	Directory recursive removement flags.
9452	</desc>
9453
9454	<const name="None" value="0">
9455	<desc>No flag set.</desc>
9456	</const>
9457	<const name="ContentAndDir" value="1">
9458	<desc>Delete the content of the directory and the directory itself.</desc>
9459	</const>
9460	<const name="ContentOnly" value="2">
9461	<desc>Only delete the content of the directory, omit the directory it self.</desc>
9462	</const>
9463	</enum>
9464
9465	<enum
9466	name="PathRenameFlag"
9467	uuid="f3baa09f-c758-453d-b91c-c7787d76351d"
9468	>
9469	<desc>
9470	Path renaming flags.
9471	</desc>
9472
9473	<const name="None" value="0">
9474	<desc>No flag set.</desc>
9475	</const>
9476	<const name="NoReplace" value="1">
9477	<desc>Do not replace anything.</desc>
9478	</const>
9479	<const name="Replace" value="2">
9480	<desc>This will replace attempt any target which isn't a directory.</desc>
9481	</const>
9482	<const name="NoSymlinks" value="4">
9483	<desc>Don't allow symbolic links as part of the path.</desc>
9484	</const>
9485	</enum>
9486
9487	<enum
9488	name="ProcessCreateFlag"
9489	uuid="35192799-bfde-405d-9bea-c735ab9998e4"
9490	>
9491	<desc>
9492	Guest process execution flags.
9493	</desc>
9494
9495	<const name="None" value="0">
9496	<desc>No flag set.</desc>
9497	</const>
9498	<const name="WaitForProcessStartOnly" value="1">
9499	<desc>Only use the specified timeout value to wait for starting the guest process - the guest
9500	process itself then uses an infinite timeout.</desc>
9501	</const>
9502	<const name="IgnoreOrphanedProcesses" value="2">
9503	<desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
9504	</const>
9505	<const name="Hidden" value="4">
9506	<desc>Do not show the started process according to the guest OS guidelines.</desc>
9507	</const>
9508	<const name="NoProfile" value="8">
9509	<desc>Do not use the user's profile data when exeuting a process. Only available for Windows guests.</desc>
9510	</const>
9511	<const name="WaitForStdOut" value="16">
9512	<desc>The guest process waits until all data from stdout is read out.</desc>
9513	</const>
9514	<const name="WaitForStdErr" value="32">
9515	<desc>The guest process waits until all data from stderr is read out.</desc>
9516	</const>
9517	<const name="ExpandArguments" value="64">
9518	<desc>Expands environment variables in process arguments.</desc>
9519	</const>
9520	</enum>
9521
9522	<enum
9523	name="ProcessPriority"
9524	uuid="ee8cac50-e232-49fe-806b-d1214d9c2e49"
9525	>
9526	<desc>
9527	Process priorities.
9528	</desc>
9529
9530	<const name="Invalid" value="0">
9531	<desc>Invalid priority, do not use.</desc>
9532	</const>
9533	<const name="Default" value="1">
9534	<desc>Default process priority determined by the OS.</desc>
9535	</const>
9536	</enum>
9537
9538	<enum
9539	name="SymlinkType"
9540	uuid="37794668-f8f1-4714-98a5-6f8fa2ed0118"
9541	>
9542	<desc>
9543	Symbolic link types.
9544	</desc>
9545
9546	<const name="Unknown" value="0">
9547	<desc>It is not known what is being targeted.</desc>
9548	</const>
9549	<const name="Directory" value="1">
9550	<desc>The link targets a directory.</desc>
9551	</const>
9552	<const name="File" value="2">
9553	<desc>The link targets a file (or whatever else).</desc>
9554	</const>
9555	</enum>
9556
9557	<enum
9558	name="SymlinkReadFlag"
9559	uuid="b7fe2b9d-790e-4b25-8adf-1ca33026931f"
9560	>
9561	<desc>
9562	Symbolic link reading flags.
9563	</desc>
9564
9565	<const name="None" value="0">
9566	<desc>No flags set.</desc>
9567	</const>
9568	<const name="NoSymlinks" value="1">
9569	<desc>Don't allow symbolic links as part of the path.</desc>
9570	</const>
9571	</enum>
9572
9573	<enum
9574	name="ProcessStatus"
9575	uuid="4d52368f-5b48-4bfe-b486-acf89139b52f"
9576	>
9577	<desc>
9578	Process execution statuses.
9579	</desc>
9580
9581	<const name="Undefined" value="0">
9582	<desc>Process is in an undefined state.</desc>
9583	</const>
9584	<const name="Starting" value="10">
9585	<desc>Process is being started.</desc>
9586	</const>
9587	<const name="Started" value="100">
9588	<desc>Process has been started.</desc>
9589	</const>
9590	<const name="Paused" value="110">
9591	<desc>Process has been paused.</desc>
9592	</const>
9593	<const name="Terminating" value="480">
9594	<desc>Process is being terminated.</desc>
9595	</const>
9596	<const name="TerminatedNormally" value="500">
9597	<desc>Process terminated normally.</desc>
9598	</const>
9599	<const name="TerminatedSignal" value="510">
9600	<desc>Process terminated via signal.</desc>
9601	</const>
9602	<const name="TerminatedAbnormally" value="511">
9603	<desc>Process terminated abnormally.</desc>
9604	</const>
9605	<const name="TimedOutKilled" value="512">
9606	<desc>Process timed out and was killed.</desc>
9607	</const>
9608	<const name="TimedOutAbnormally" value="513">
9609	<desc>Process timed out and was not killed successfully.</desc>
9610	</const>
9611	<const name="Down" value="600">
9612	<desc>Service/OS is stopping, process was killed.</desc>
9613	</const>
9614	<const name="Error" value="800">
9615	<desc>Something went wrong.</desc>
9616	</const>
9617	</enum>
9618
9619	<enum
9620	name="ProcessInputStatus"
9621	uuid="a4a0ef9c-29cc-4805-9803-c8215ae9da6c"
9622	>
9623	<desc>
9624	Process input statuses.
9625	</desc>
9626
9627	<const name="Undefined" value="0">
9628	<desc>Undefined state.</desc>
9629	</const>
9630	<const name="Broken" value="1">
9631	<desc>Input pipe is broken.</desc>
9632	</const>
9633	<const name="Available" value="10">
9634	<desc>Input pipe became available for writing.</desc>
9635	</const>
9636	<const name="Written" value="50">
9637	<desc>Data has been successfully written.</desc>
9638	</const>
9639	<const name="Overflow" value="100">
9640	<desc>Too much input data supplied, data overflow.</desc>
9641	</const>
9642	</enum>
9643
9644	<enum
9645	name="FileStatus"
9646	uuid="8c86468b-b97b-4080-8914-e29f5b0abd2c"
9647	>
9648	<desc>
9649	File statuses.
9650	</desc>
9651
9652	<const name="Undefined" value="0">
9653	<desc>File is in an undefined state.</desc>
9654	</const>
9655	<const name="Opening" value="10">
9656	<desc>Guest file is opening.</desc>
9657	</const>
9658	<const name="Open" value="100">
9659	<desc>Guest file has been successfully opened.</desc>
9660	</const>
9661	<const name="Closing" value="150">
9662	<desc>Guest file closing.</desc>
9663	</const>
9664	<const name="Closed" value="200">
9665	<desc>Guest file has been closed.</desc>
9666	</const>
9667	<const name="Down" value="600">
9668	<desc>Service/OS is stopping, guest file was closed.</desc>
9669	</const>
9670	<const name="Error" value="800">
9671	<desc>Something went wrong.</desc>
9672	</const>
9673	</enum>
9674
9675	<enum
9676	name="FsObjType"
9677	uuid="a1ed437c-b3c3-4ca2-b19c-4239d658d5e8"
9678	>
9679	<desc>
9680	File system object type.
9681	</desc>
9682
9683	<const name="Undefined" value="0">
9684	<desc>Type is undefined / unknown.</desc>
9685	</const>
9686	<const name="FIFO" value="1">
9687	<desc>Named pipe.</desc>
9688	</const>
9689	<const name="DevChar" value="10">
9690	<desc>Character device.</desc>
9691	</const>
9692	<const name="DevBlock" value="11">
9693	<desc>Block device.</desc>
9694	</const>
9695	<const name="Directory" value="50">
9696	<desc>Directory.</desc>
9697	</const>
9698	<const name="File" value="80">
9699	<desc>File.</desc>
9700	</const>
9701	<const name="Symlink" value="100">
9702	<desc>Symlink.</desc>
9703	</const>
9704	<const name="Socket" value="200">
9705	<desc>Socket.</desc>
9706	</const>
9707	<const name="Whiteout" value="400">
9708	<desc>Whiteout.</desc>
9709	</const>
9710	</enum>
9711
9712	<enum
9713	name="DragAndDropAction"
9714	uuid="47f3b162-c107-4fcd-bfa7-54b8135c441e"
9715	>
9716	<desc>
9717	Possible actions within an Drag and Drop operation.
9718	</desc>
9719
9720	<const name="Ignore" value="0">
9721	<desc>Do nothing.</desc>
9722	</const>
9723
9724	<const name="Copy" value="1">
9725	<desc>Copy the item to the target.</desc>
9726	</const>
9727
9728	<const name="Move" value="2">
9729	<desc>Move the item to the target.</desc>
9730	</const>
9731
9732	<const name="Link" value="3">
9733	<desc>Link the item from within the target.</desc>
9734	</const>
9735	</enum>
9736
9737	<enum
9738	name="DirectoryOpenFlag"
9739	uuid="5138837a-8fd2-4194-a1b0-08f7bc3949d0"
9740	>
9741	<desc>
9742	Directory open flags.
9743	</desc>
9744	<const name="None" value="0">
9745	<desc>No flag set.</desc>
9746	</const>
9747	<const name="NoSymlinks" value="1">
9748	<desc>Don't allow symbolic links as part of the path.</desc>
9749	</const>
9750	</enum>
9751
9752	<interface
9753	name="IGuestSession" extends="$unknown"
9754	uuid="c8e8607b-5e67-4073-8f14-146515d0c1ff"
9755	wsmap="managed"
9756	>
9757	<desc>
9758	A guest session represents one impersonated user account on the guest, so
9759	every operation will use the same credentials specified when creating
9760	the session object via <link to="IGuest::createSession"/>.
9761
9762	There can be a maximum of 32 sessions at once per VM. Each session keeps
9763	track of its started guest processes, opened guest files or guest directories.
9764	To work on guest files or directories a guest session offers methods to open
9765	or create such objects (see <link to="IGuestSession::fileOpen"/> or
9766	<link to="IGuestSession::directoryOpen"/> for example).
9767
9768	When done with either of these objects, including the guest session itself,
9769	use the appropriate close() method to let the object do its cleanup work.
9770
9771	Every guest session has its own environment variable block which gets
9772	automatically applied when starting a new guest process via
9773	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
9774	To override (or unset) certain environment variables already set by the
9775	guest session, one can specify a per-process environment block when using
9776	one of the both above mentioned process creation calls.
9777	</desc>
9778
9779	<attribute name="user" type="wstring" readonly="yes">
9780	<desc>Returns the user name used by this session to impersonate
9781	users on the guest.
9782	</desc>
9783	</attribute>
9784	<attribute name="domain" type="wstring" readonly="yes">
9785	<desc>Returns the domain name used by this session to impersonate
9786	users on the guest.
9787	</desc>
9788	</attribute>
9789	<attribute name="name" type="wstring" readonly="yes">
9790	<desc>Returns the session's friendly name.</desc>
9791	</attribute>
9792	<attribute name="id" type="unsigned long" readonly="yes">
9793	<desc>Returns the internal session ID.</desc>
9794	</attribute>
9795	<attribute name="timeout" type="unsigned long">
9796	<desc>
9797	Returns the session timeout (in ms).
9798	<result name="E_NOTIMPL">
9799	The method is not implemented yet.
9800	</result>
9801	</desc>
9802	</attribute>
9803	<attribute name="status" type="GuestSessionStatus" readonly="yes">
9804	<desc>Returns the current session status.</desc>
9805	</attribute>
9806	<attribute name="environment" type="wstring" safearray="yes">
9807	<desc>
9808	Returns the current session environment.
9809	</desc>
9810	</attribute>
9811	<attribute name="processes" type="IGuestProcess" readonly="yes" safearray="yes">
9812	<desc>
9813	Returns all current guest processes.
9814	</desc>
9815	</attribute>
9816	<attribute name="directories" type="IGuestDirectory" readonly="yes" safearray="yes">
9817	<desc>
9818	Returns all currently opened guest directories.
9819	</desc>
9820	</attribute>
9821	<attribute name="files" type="IGuestFile" readonly="yes" safearray="yes">
9822	<desc>
9823	Returns all currently opened guest files.
9824	</desc>
9825	</attribute>
9826	<attribute name="eventSource" type="IEventSource" readonly="yes">
9827	<desc>
9828	Event source for guest session events.
9829	</desc>
9830	</attribute>
9831
9832	<method name="close">
9833	<desc>
9834	Closes this session. All opened guest directories, files and
9835	processes which are not referenced by clients anymore will be
9836	uninitialized.
9837	</desc>
9838	</method>
9839
9840	<method name="copyFrom">
9841	<desc>
9842	Copies a file from guest to the host.
9843
9844	<result name="VBOX_E_IPRT_ERROR">
9845	Error starting the copy operation.
9846	</result>
9847	</desc>
9848	<param name="source" type="wstring" dir="in">
9849	<desc>Source file on the guest to copy to the host.</desc>
9850	</param>
9851	<param name="dest" type="wstring" dir="in">
9852	<desc>Destination file name on the host.</desc>
9853	</param>
9854	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9855	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9856	</param>
9857	<param name="progress" type="IProgress" dir="return">
9858	<desc>Progress object to track the operation completion.</desc>
9859	</param>
9860	</method>
9861
9862	<method name="copyTo">
9863	<desc>
9864	Copies a file from host to the guest.
9865
9866	<result name="VBOX_E_IPRT_ERROR">
9867	Error starting the copy operation.
9868	</result>
9869	</desc>
9870	<param name="source" type="wstring" dir="in">
9871	<desc>Source file on the host to copy to the guest.</desc>
9872	</param>
9873	<param name="dest" type="wstring" dir="in">
9874	<desc>Destination file name on the guest.</desc>
9875	</param>
9876	<param name="flags" type="CopyFileFlag" dir="in" safearray="yes">
9877	<desc>Copy flags; see <link to="CopyFileFlag"/> for more information.</desc>
9878	</param>
9879	<param name="progress" type="IProgress" dir="return">
9880	<desc>Progress object to track the operation completion.</desc>
9881	</param>
9882	</method>
9883
9884	<method name="directoryCreate">
9885	<desc>
9886	Create a directory on the guest.
9887
9888	<result name="VBOX_E_IPRT_ERROR">
9889	Error while creating the directory.
9890	</result>
9891	</desc>
9892	<param name="path" type="wstring" dir="in">
9893	<desc>Full path of directory to create.</desc>
9894	</param>
9895	<param name="mode" type="unsigned long" dir="in">
9896	<desc>File creation mode.</desc>
9897	</param>
9898	<param name="flags" type="DirectoryCreateFlag" dir="in" safearray="yes">
9899	<desc>Creation flags; see <link to="DirectoryCreateFlag"/> for more information.</desc>
9900	</param>
9901	</method>
9902
9903	<method name="directoryCreateTemp">
9904	<desc>
9905	Create a temporary directory on the guest.
9906
9907	<result name="VBOX_E_NOT_SUPPORTED">
9908	The operation is not possible as requested on this particular
9909	guest type.
9910	</result>
9911	<result name="E_INVALIDARG">
9912	Invalid argument. This includes an incorrectly formatted template,
9913	or a non-absolute path.
9914	</result>
9915	<result name="VBOX_E_IPRT_ERROR">
9916	The temporary directory could not be created. Possible reasons
9917	include a non-existing path or an insecure path when the secure
9918	option was requested.
9919	</result>
9920	</desc>
9921	<param name="templateName" type="wstring" dir="in">
9922	<desc>Template for the name of the directory to create. This must
9923	contain at least one 'X' character. The first group of consecutive
9924	'X' characters in the template will be replaced by a random
9925	alphanumeric string to produce a unique name.</desc>
9926	</param>
9927	<param name="mode" type="unsigned long" dir="in">
9928	<desc>The mode of the directory to create. Use 0700 unless there are
9929	reasons not to. This parameter is ignored if "secure" is specified.
9930	</desc>
9931	</param>
9932	<param name="path" type="wstring" dir="in">
9933	<desc>The absolute path to create the temporary directory in.</desc>
9934	</param>
9935	<param name="secure" type="boolean" dir="in">
9936	<desc>Whether to fail if the directory can not be securely created.
9937	Currently this means that another unprivileged user cannot
9938	manipulate the path specified or remove the temporary directory
9939	after it has been created. Also causes the mode specified to be
9940	ignored. May not be supported on all guest types.</desc>
9941	</param>
9942	<param name="directory" type="wstring" dir="return">
9943	<desc>On success this will contain the name of the directory created
9944	with full path.</desc>
9945	</param>
9946	</method>
9947
9948	<method name="directoryExists">
9949	<desc>
9950	Checks whether a directory exists on the guest or not.
9951
9952	<result name="VBOX_E_IPRT_ERROR">
9953	Error while checking existence of the directory specified.
9954	</result>
9955	</desc>
9956	<param name="path" type="wstring" dir="in">
9957	<desc>Directory to check existence for.</desc>
9958	</param>
9959	<param name="exists" type="boolean" dir="return">
9960	<desc>Returns @c true if the directory exists, @c false if not.</desc>
9961	</param>
9962	</method>
9963
9964	<method name="directoryOpen">
9965	<desc>
9966	Opens a directory and creates a <link to="IGuestDirectory"/> object that
9967	can be used for further operations.
9968
9969	<result name="VBOX_E_OBJECT_NOT_FOUND">
9970	Directory to open was not found.
9971	</result>
9972	<result name="VBOX_E_IPRT_ERROR">
9973	Error while opening the directory.
9974	</result>
9975	</desc>
9976	<param name="path" type="wstring" dir="in">
9977	<desc>Full path to file to open.</desc>
9978	</param>
9979	<param name="filter" type="wstring" dir="in">
9980	<desc>Open filter to apply. This can include wildcards like ? and *.</desc>
9981	</param>
9982	<param name="flags" type="DirectoryOpenFlag" dir="in" safearray="yes">
9983	<desc>Open flags; see <link to="DirectoryOpenFlag"/> for more information.</desc>
9984	</param>
9985	<param name="directory" type="IGuestDirectory" dir="return">
9986	<desc><link to="IGuestDirectory"/> object containing the opened directory.</desc>
9987	</param>
9988	</method>
9989
9990	<method name="directoryQueryInfo">
9991	<desc>
9992	Queries information of a directory on the guest.
9993
9994	<result name="VBOX_E_OBJECT_NOT_FOUND">
9995	Directory to query information for was not found.
9996	</result>
9997	<result name="VBOX_E_IPRT_ERROR">
9998	Error querying information.
9999	</result>
10000	</desc>
10001	<param name="path" type="wstring" dir="in">
10002	<desc>Directory to query information for.</desc>
10003	</param>
10004	<param name="info" type="IGuestFsObjInfo" dir="return">
10005	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10006	</param>
10007	</method>
10008
10009	<method name="directoryRemove">
10010	<desc>
10011	Removes a guest directory if not empty.
10012
10013	<result name="E_NOTIMPL">
10014	The method is not implemented yet.
10015	</result>
10016	</desc>
10017	<param name="path" type="wstring" dir="in">
10018	<desc>Full path of directory to remove.</desc>
10019	</param>
10020	</method>
10021
10022	<method name="directoryRemoveRecursive">
10023	<desc>
10024	Removes a guest directory recursively.
10025
10026	<result name="E_NOTIMPL">
10027	The method is not implemented yet.
10028	</result>
10029	</desc>
10030	<param name="path" type="wstring" dir="in">
10031	<desc>Full path of directory to remove recursively.</desc>
10032	</param>
10033	<param name="flags" type="DirectoryRemoveRecFlag" dir="in" safearray="yes">
10034	<desc>Remove flags; see <link to="DirectoryRemoveRecFlag"/> for more information.</desc>
10035	</param>
10036	<param name="progress" type="IProgress" dir="return">
10037	<desc>Progress object to track the operation completion.</desc>
10038	</param>
10039	</method>
10040
10041	<method name="directoryRename">
10042	<desc>
10043	Renames a directory on the guest.
10044
10045	<result name="E_NOTIMPL">
10046	The method is not implemented yet.
10047	</result>
10048	</desc>
10049	<param name="source" type="wstring" dir="in">
10050	<desc>Source directory to rename.</desc>
10051	</param>
10052	<param name="dest" type="wstring" dir="in">
10053	<desc>Destination directory to rename the source to.</desc>
10054	</param>
10055	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10056	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10057	</param>
10058	</method>
10059
10060	<method name="directorySetACL">
10061	<desc>
10062	Sets the ACL (Access Control List) of a guest directory.
10063
10064	<result name="E_NOTIMPL">
10065	The method is not implemented yet.
10066	</result>
10067	</desc>
10068	<param name="path" type="wstring" dir="in">
10069	<desc>Full path of directory to set the ACL for.</desc>
10070	</param>
10071	<param name="acl" type="wstring" dir="in">
10072	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10073	</param>
10074	</method>
10075
10076	<method name="environmentClear">
10077	<desc>
10078	Clears (deletes) all session environment variables.
10079
10080	<result name="VBOX_E_IPRT_ERROR">
10081	Error while clearing the session environment variables.
10082	</result>
10083	</desc>
10084	</method>
10085
10086	<method name="environmentGet">
10087	<desc>
10088	Gets the value of a session environment variable.
10089
10090	<result name="VBOX_E_IPRT_ERROR">
10091	Error while getting the value of the session environment variable.
10092	</result>
10093	</desc>
10094	<param name="name" type="wstring" dir="in">
10095	<desc>Name of session environment variable to get the value for.</desc>
10096	</param>
10097	<param name="value" type="wstring" dir="return">
10098	<desc>
10099	Value of the session environment variable specified. If this variable
10100	does not exist and empty value will be returned.
10101	</desc>
10102	</param>
10103	</method>
10104
10105	<method name="environmentSet">
10106	<desc>
10107	Sets a session environment variable.
10108
10109	<result name="VBOX_E_IPRT_ERROR">
10110	Error while setting the session environment variable.
10111	</result>
10112	</desc>
10113	<param name="name" type="wstring" dir="in">
10114	<desc>Name of session environment variable to set.</desc>
10115	</param>
10116	<param name="value" type="wstring" dir="in">
10117	<desc>Value to set the session environment variable to.</desc>
10118	</param>
10119	</method>
10120
10121	<method name="environmentUnset">
10122	<desc>
10123	Unsets session environment variable.
10124
10125	<result name="VBOX_E_IPRT_ERROR">
10126	Error while unsetting the session environment variable.
10127	</result>
10128	</desc>
10129	<param name="name" type="wstring" dir="in">
10130	<desc>Name of session environment variable to unset (clear).</desc>
10131	</param>
10132	</method>
10133
10134	<method name="fileCreateTemp">
10135	<desc>
10136	Creates a temporary file on the guest.
10137
10138	<result name="VBOX_E_NOT_SUPPORTED">
10139	The operation is not possible as requested on this particular
10140	guest type.
10141	</result>
10142	<result name="E_INVALIDARG">
10143	Invalid argument. This includes an incorrectly formatted template,
10144	or a non-absolute path.
10145	</result>
10146	<result name="VBOX_E_IPRT_ERROR">
10147	The temporary file could not be created. Possible reasons include
10148	a non-existing path or an insecure path when the secure
10149	option was requested.
10150	</result>
10151	</desc>
10152	<param name="templateName" type="wstring" dir="in">
10153	<desc>Template for the name of the file to create. This must contain
10154	at least one 'X' character. The first group of consecutive 'X'
10155	characters in the template will be replaced by a random
10156	alphanumeric string to produce a unique name.
10157	</desc>
10158	</param>
10159	<param name="mode" type="unsigned long" dir="in">
10160	<desc>The mode of the file to create. Use 0700 unless there are
10161	reasons not to. This parameter is ignored if "secure" is specified.
10162	</desc>
10163	</param>
10164	<param name="path" type="wstring" dir="in">
10165	<desc>The absolute path to create the temporary file in.</desc>
10166	</param>
10167	<param name="secure" type="boolean" dir="in">
10168	<desc>Whether to fail if the file can not be securely created.
10169	Currently this means that another unprivileged user cannot
10170	manipulate the path specified or remove the temporary file after
10171	it has been created. Also causes the mode specified to be ignored.
10172	May not be supported on all guest types.</desc>
10173	</param>
10174	<param name="file" type="IGuestFile" dir="return">
10175	<desc>On success this will contain an open file object for the new
10176	temporary file.
10177	</desc>
10178	</param>
10179	</method>
10180
10181	<method name="fileExists">
10182	<desc>
10183	Checks whether a file exists on the guest or not.
10184
10185	<result name="VBOX_E_IPRT_ERROR">
10186	Error while checking existence of the file specified.
10187	</result>
10188	</desc>
10189	<param name="path" type="wstring" dir="in">
10190	<desc>File to check existence for.</desc>
10191	</param>
10192	<param name="exists" type="boolean" dir="return">
10193	<desc>Returns @c true if the file exists, @c false if not.</desc>
10194	</param>
10195	</method>
10196
10197	<method name="fileRemove">
10198	<desc>
10199	Removes a single file on the guest.
10200
10201	<result name="VBOX_E_OBJECT_NOT_FOUND">
10202	File to remove was not found.
10203	</result>
10204	<result name="VBOX_E_IPRT_ERROR">
10205	Error while removing the file.
10206	</result>
10207	</desc>
10208	<param name="path" type="wstring" dir="in">
10209	<desc>Path to the file to remove.</desc>
10210	</param>
10211	</method>
10212
10213	<method name="fileOpen">
10214	<desc>
10215	Opens a file and creates a <link to="IGuestFile"/> object that
10216	can be used for further operations.
10217
10218	<result name="VBOX_E_OBJECT_NOT_FOUND">
10219	File to open was not found.
10220	</result>
10221	<result name="VBOX_E_IPRT_ERROR">
10222	Error while opening the file.
10223	</result>
10224	</desc>
10225	<param name="path" type="wstring" dir="in">
10226	<desc>Full path to file to open.</desc>
10227	</param>
10228	<param name="openMode" type="wstring" dir="in">
10229	<desc>The file open mode.</desc>
10230	</param>
10231	<param name="disposition" type="wstring" dir="in">
10232	<desc>The file disposition.</desc>
10233	</param>
10234	<param name="creationMode" type="unsigned long" dir="in">
10235	<desc>The file creation mode.</desc>
10236	</param>
10237	<param name="offset" type="long long" dir="in">
10238	<desc>The initial read/write offset.</desc>
10239	</param>
10240	<param name="file" type="IGuestFile" dir="return">
10241	<desc><link to="IGuestFile"/> object representing the opened file.</desc>
10242	</param>
10243	</method>
10244
10245	<method name="fileQueryInfo">
10246	<desc>
10247	Queries information of a file on the guest.
10248
10249	<result name="VBOX_E_OBJECT_NOT_FOUND">
10250	File to query information for was not found.
10251	</result>
10252	<result name="VBOX_E_IPRT_ERROR">
10253	Error querying information.
10254	</result>
10255	</desc>
10256	<param name="path" type="wstring" dir="in">
10257	<desc>File to query information for.</desc>
10258	</param>
10259	<param name="info" type="IGuestFsObjInfo" dir="return">
10260	<desc><link to="IGuestFsObjInfo"/> object containing the queried information.</desc>
10261	</param>
10262	</method>
10263
10264	<method name="fileQuerySize">
10265	<desc>
10266	Queries the size of a file on the guest.
10267
10268	<result name="VBOX_E_OBJECT_NOT_FOUND">
10269	File to rename was not found.
10270	</result>
10271	<result name="VBOX_E_IPRT_ERROR">
10272	Error querying file size.
10273	</result>
10274	</desc>
10275	<param name="path" type="wstring" dir="in">
10276	<desc>File to query the size for.</desc>
10277	</param>
10278	<param name="size" type="long long" dir="return">
10279	<desc>Queried file size.</desc>
10280	</param>
10281	</method>
10282
10283	<method name="fileRename">
10284	<desc>
10285	Renames a file on the guest.
10286
10287	<result name="E_NOTIMPL">
10288	The method is not implemented yet.
10289	</result>
10290	</desc>
10291	<param name="source" type="wstring" dir="in">
10292	<desc>Source file to rename.</desc>
10293	</param>
10294	<param name="dest" type="wstring" dir="in">
10295	<desc>Destination file to rename the source to.</desc>
10296	</param>
10297	<param name="flags" type="PathRenameFlag" dir="in" safearray="yes">
10298	<desc>Rename flags; see <link to="PathRenameFlag"/> for more information.</desc>
10299	</param>
10300	</method>
10301
10302	<method name="fileSetACL">
10303	<desc>
10304	Sets the ACL (Access Control List) of a file on the guest.
10305
10306	<result name="E_NOTIMPL">
10307	The method is not implemented yet.
10308	</result>
10309	</desc>
10310	<param name="file" type="wstring" dir="in">
10311	<desc>Full path of file to set the ACL for.</desc>
10312	</param>
10313	<param name="acl" type="wstring" dir="in">
10314	<desc>Actual ACL string to set. Must comply with the guest OS.</desc>
10315	</param>
10316	</method>
10317
10318	<method name="processCreate">
10319	<desc>
10320	Creates a new process running on the guest. The new process will be
10321	started asynchronously, meaning on return of this function it is not
10322	guaranteed that the guest process is in a started state. To wait for
10323	successful startup, use the <link to="IProcess::waitFor"/> call.
10324
10325	<note>
10326	Starting at VirtualBox 4.2 guest process execution by default is limited
10327	to serve up to 255 guest processes at a time. If all 255 guest processes
10328	are still active and running, creating a new guest process will result in an
10329	appropriate error message.
10330
10331	If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr
10332	is / are set, the guest process will not exit until all data from the specified
10333	stream(s) is / are read out.
10334
10335	To raise or lower the guest process execution limit, either the guest property
10336	"/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService'
10337	command line by specifying "--control-procs-max-kept" needs to be modified.
10338	A restart of the guest OS is required afterwards. To serve unlimited guest
10339	processes, a value of "0" needs to be set (not recommended).
10340	</note>
10341
10342	<result name="VBOX_E_IPRT_ERROR">
10343	Error creating guest process.
10344	</result>
10345	</desc>
10346	<param name="command" type="wstring" dir="in">
10347	<desc>
10348	Full path name of the command to execute on the guest; the
10349	commands has to exists in the guest VM in order to be executed.
10350	</desc>
10351	</param>
10352	<param name="arguments" type="wstring" dir="in" safearray="yes">
10353	<desc>Array of arguments passed to the execution command.</desc>
10354	</param>
10355	<param name="environment" type="wstring" dir="in" safearray="yes">
10356	<desc>
10357	<para>Environment variables that can be set while the command is being
10358	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10359	variable just set its name ("NAME") without a value.</para>
10360	<para>This parameter can be used to override environment variables set by
10361	the guest session, which will be applied to the newly started process
10362	in any case.</para>
10363	</desc>
10364	</param>
10365	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10366	<desc>
10367	Process creation flags;
10368	see <link to="ProcessCreateFlag"/> for more information.
10369	</desc>
10370	</param>
10371	<param name="timeoutMS" type="unsigned long" dir="in">
10372	<desc>
10373	Timeout (in ms) for limiting the guest process' running time.
10374	Pass 0 for an infinite timeout. On timeout the guest process will be
10375	killed and its status will be put to an appropriate value. See
10376	<link to="ProcessStatus"/> for more information.
10377	</desc>
10378	</param>
10379	<param name="guestProcess" type="IGuestProcess" dir="return">
10380	<desc>Guest process object of the newly created process.</desc>
10381	</param>
10382	</method>
10383
10384	<method name="processCreateEx">
10385	<desc>
10386	<para>Creates a new process running on the guest. Extended version for
10387	also setting the process priority and affinity.</para>
10388
10389	<para>See <link to="IGuestSession::processCreate"/> for more
10390	information.</para>
10391	</desc>
10392	<param name="command" type="wstring" dir="in">
10393	<desc>
10394	Full path name of the command to execute on the guest; the
10395	commands has to exists in the guest VM in order to be executed.
10396	</desc>
10397	</param>
10398	<param name="arguments" type="wstring" dir="in" safearray="yes">
10399	<desc>Array of arguments passed to the execution command.</desc>
10400	</param>
10401	<param name="environment" type="wstring" dir="in" safearray="yes">
10402	<desc>
10403	<para>Environment variables that can be set while the command is being
10404	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
10405	variable just set its name ("NAME") without a value.</para>
10406	<para>This parameter can be used to override environment variables set by
10407	the guest session, which will be applied to the newly started process
10408	in any case.</para>
10409	</desc>
10410	</param>
10411	<param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes">
10412	<desc>
10413	Process creation flags;
10414	see <link to="ProcessCreateFlag"/> for more information.
10415	</desc>
10416	</param>
10417	<param name="timeoutMS" type="unsigned long" dir="in">
10418	<desc>
10419	Timeout (in ms) for limiting the guest process' running time.
10420	Pass 0 for an infinite timeout. On timeout the guest process will be
10421	killed and its status will be put to an appropriate value. See
10422	<link to="ProcessStatus"/> for more information.
10423	</desc>
10424	</param>
10425	<param name="priority" type="ProcessPriority" dir="in">
10426	<desc>
10427	Process priority to use for execution;
10428	see see <link to="ProcessPriority"/> for more information.</desc>
10429	</param>
10430	<param name="affinity" type="long" dir="in" safearray="yes">
10431	<desc>
10432	Process affinity to use for execution. This parameter
10433	is not implemented yet.
10434	</desc>
10435	</param>
10436	<param name="guestProcess" type="IGuestProcess" dir="return">
10437	<desc>Guest process object of the newly created process.</desc>
10438	</param>
10439	</method>
10440
10441	<method name="processGet">
10442	<desc>
10443	Gets a certain guest process by its process ID (PID).
10444	</desc>
10445	<param name="pid" type="unsigned long" dir="in">
10446	<desc>Process ID (PID) to get guest process for.</desc>
10447	</param>
10448	<param name="guestProcess" type="IGuestProcess" dir="return">
10449	<desc>Guest process of specified process ID (PID).</desc>
10450	</param>
10451	</method>
10452
10453	<method name="symlinkCreate">
10454	<desc>
10455	Creates a symbolic link on the guest.
10456
10457	<result name="E_NOTIMPL">
10458	The method is not implemented yet.
10459	</result>
10460	</desc>
10461	<param name="source" type="wstring" dir="in">
10462	<desc>The name of the symbolic link.</desc>
10463	</param>
10464	<param name="target" type="wstring" dir="in">
10465	<desc>The path to the symbolic link target.</desc>
10466	</param>
10467	<param name="type" type="SymlinkType" dir="in">
10468	<desc>
10469	The symbolic link type;
10470	see <link to="SymlinkReadFlag"/> for more information.
10471	</desc>
10472	</param>
10473	</method>
10474
10475	<method name="symlinkExists">
10476	<desc>
10477	Checks whether a symbolic link exists on the guest or not.
10478
10479	<result name="E_NOTIMPL">
10480	The method is not implemented yet.
10481	</result>
10482	</desc>
10483	<param name="symlink" type="wstring" dir="in">
10484	<desc>Symbolic link to check existence for.</desc>
10485	</param>
10486	<param name="exists" type="boolean" dir="return">
10487	<desc>Returns @c true if the symbolic link exists, @c false if not.</desc>
10488	</param>
10489	</method>
10490
10491	<method name="symlinkRead">
10492	<desc>
10493	Reads a symbolic link on the guest.
10494
10495	<result name="E_NOTIMPL">
10496	The method is not implemented yet.
10497	</result>
10498	</desc>
10499	<param name="symlink" type="wstring" dir="in">
10500	<desc>Full path to symbolic link to read.</desc>
10501	</param>
10502	<param name="flags" type="SymlinkReadFlag" dir="in" safearray="yes">
10503	<desc>
10504	Read flags; see <link to="SymlinkReadFlag"/> for more information.
10505	</desc>
10506	</param>
10507	<param name="target" type="wstring" dir="return">
10508	<desc>
10509	Target of the symbolic link pointing to, if found.
10510	</desc>
10511	</param>
10512	</method>
10513
10514	<method name="symlinkRemoveDirectory">
10515	<desc>
10516	Removes a symbolic link on the guest if it's a directory.
10517
10518	<result name="E_NOTIMPL">
10519	The method is not implemented yet.
10520	</result>
10521	</desc>
10522	<param name="path" type="wstring" dir="in">
10523	<desc>Symbolic link to remove.</desc>
10524	</param>
10525	</method>
10526
10527	<method name="symlinkRemoveFile">
10528	<desc>
10529	Removes a symbolic link on the guest if it's a file.
10530
10531	<result name="E_NOTIMPL">
10532	The method is not implemented yet.
10533	</result>
10534	</desc>
10535	<param name="file" type="wstring" dir="in">
10536	<desc>Symbolic link to remove.</desc>
10537	</param>
10538	</method>
10539
10540	<method name="waitFor">
10541	<desc>
10542	Waits for one more events to happen.
10543	</desc>
10544	<param name="waitFor" type="unsigned long" dir="in">
10545	<desc>
10546	Specifies what to wait for;
10547	see <link to="GuestSessionWaitForFlag"/> for more information.
10548	</desc>
10549	</param>
10550	<param name="timeoutMS" type="unsigned long" dir="in">
10551	<desc>
10552	Timeout (in ms) to wait for the operation to complete.
10553	Pass 0 for an infinite timeout.
10554	</desc>
10555	</param>
10556	<param name="reason" type="GuestSessionWaitResult" dir="return">
10557	<desc>
10558	The overall wait result;
10559	see <link to="GuestSessionWaitResult"/> for more information.
10560	</desc>
10561	</param>
10562	</method>
10563
10564	<method name="waitForArray">
10565	<desc>
10566	Waits for one more events to happen.
10567	Scriptable version of <link to="#waitFor" />.
10568	</desc>
10569	<param name="waitFor" type="GuestSessionWaitForFlag" dir="in" safearray="yes">
10570	<desc>
10571	Specifies what to wait for;
10572	see <link to="GuestSessionWaitForFlag"/> for more information.
10573	</desc>
10574	</param>
10575	<param name="timeoutMS" type="unsigned long" dir="in">
10576	<desc>
10577	Timeout (in ms) to wait for the operation to complete.
10578	Pass 0 for an infinite timeout.
10579	</desc>
10580	</param>
10581	<param name="reason" type="GuestSessionWaitResult" dir="return">
10582	<desc>
10583	The overall wait result;
10584	see <link to="GuestSessionWaitResult"/> for more information.
10585	</desc>
10586	</param>
10587	</method>
10588
10589	</interface>
10590
10591	<interface
10592	name="IProcess" extends="$unknown"
10593	uuid="5a4fe06d-8cb1-40ff-ac9e-9676e32f706e"
10594	wsmap="managed"
10595	>
10596	<desc>
10597	Abstract parent interface for processes handled by VirtualBox.
10598	</desc>
10599
10600	<attribute name="arguments" type="wstring" readonly="yes" safearray="yes">
10601	<desc>
10602	The arguments this process is using for execution.
10603	</desc>
10604	</attribute>
10605	<attribute name="environment" type="wstring" readonly="yes" safearray="yes">
10606	<desc>
10607	The environment block this process is using during execution.
10608	</desc>
10609	</attribute>
10610	<attribute name="eventSource" type="IEventSource" readonly="yes">
10611	<desc>
10612	Event source for VirtualBox events.
10613	</desc>
10614	</attribute>
10615	<attribute name="executablePath" type="wstring" readonly="yes">
10616	<desc>Full path of the actual executable image.</desc>
10617	</attribute>
10618	<attribute name="exitCode" type="long" readonly="yes">
10619	<desc>
10620	The exit code. Only available when the process has been
10621	terminated normally.
10622	</desc>
10623	</attribute>
10624	<attribute name="name" type="wstring" readonly="yes">
10625	<desc>
10626	The friendly name of this process.
10627	</desc>
10628	</attribute>
10629	<attribute name="PID" type="unsigned long" readonly="yes">
10630	<desc>
10631	The process ID (PID).
10632	</desc>
10633	</attribute>
10634	<attribute name="status" type="ProcessStatus" readonly="yes">
10635	<desc>
10636	The current process status; see <link to="ProcessStatus"/>
10637	for more information.
10638	</desc>
10639	</attribute>
10640
10641	<method name="waitFor">
10642	<desc>
10643	Waits for one more events to happen.
10644	</desc>
10645	<param name="waitFor" type="unsigned long" dir="in">
10646	<desc>
10647	Specifies what to wait for;
10648	see <link to="ProcessWaitForFlag"/> for more information.
10649	</desc>
10650	</param>
10651	<param name="timeoutMS" type="unsigned long" dir="in">
10652	<desc>
10653	Timeout (in ms) to wait for the operation to complete.
10654	Pass 0 for an infinite timeout.
10655	</desc>
10656	</param>
10657	<param name="reason" type="ProcessWaitResult" dir="return">
10658	<desc>
10659	The overall wait result;
10660	see <link to="ProcessWaitResult"/> for more information.
10661	</desc>
10662	</param>
10663	</method>
10664
10665	<method name="waitForArray">
10666	<desc>
10667	Waits for one more events to happen.
10668	Scriptable version of <link to="#waitFor" />.
10669	</desc>
10670	<param name="waitFor" type="ProcessWaitForFlag" dir="in" safearray="yes">
10671	<desc>
10672	Specifies what to wait for;
10673	see <link to="ProcessWaitForFlag"/> for more information.
10674	</desc>
10675	</param>
10676	<param name="timeoutMS" type="unsigned long" dir="in">
10677	<desc>
10678	Timeout (in ms) to wait for the operation to complete.
10679	Pass 0 for an infinite timeout.
10680	</desc>
10681	</param>
10682	<param name="reason" type="ProcessWaitResult" dir="return">
10683	<desc>
10684	The overall wait result;
10685	see <link to="ProcessWaitResult"/> for more information.
10686	</desc>
10687	</param>
10688	</method>
10689
10690	<method name="read">
10691	<desc>
10692	Reads data from a running process.
10693	</desc>
10694	<param name="handle" type="unsigned long" dir="in">
10695	<desc>Handle to read from. Usually 0 is stdin.</desc>
10696	</param>
10697	<param name="toRead" type="unsigned long" dir="in">
10698	<desc>Number of bytes to read.</desc>
10699	</param>
10700	<param name="timeoutMS" type="unsigned long" dir="in">
10701	<desc>
10702	Timeout (in ms) to wait for the operation to complete.
10703	Pass 0 for an infinite timeout.
10704	</desc>
10705	</param>
10706	<param name="data" type="octet" dir="return" safearray="yes">
10707	<desc>Array of data read.</desc>
10708	</param>
10709	</method>
10710
10711	<method name="write">
10712	<desc>
10713	Writes data to a running process.
10714	</desc>
10715	<param name="handle" type="unsigned long" dir="in">
10716	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10717	</param>
10718	<param name="flags" type="unsigned long" dir="in">
10719	<desc>
10720	A combination of <link to="ProcessInputFlag"/> flags.
10721	</desc>
10722	</param>
10723	<param name="data" type="octet" dir="in" safearray="yes">
10724	<desc>
10725	Array of bytes to write. The size of the array also specifies
10726	how much to write.
10727	</desc>
10728	</param>
10729	<param name="timeoutMS" type="unsigned long" dir="in">
10730	<desc>
10731	Timeout (in ms) to wait for the operation to complete.
10732	Pass 0 for an infinite timeout.
10733	</desc>
10734	</param>
10735	<param name="written" type="unsigned long" dir="return">
10736	<desc>How much bytes were written.</desc>
10737	</param>
10738	</method>
10739
10740	<method name="writeArray">
10741	<desc>
10742	Writes data to a running process.
10743	Scriptable version of <link to="#write" />.
10744	</desc>
10745	<param name="handle" type="unsigned long" dir="in">
10746	<desc>Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr.</desc>
10747	</param>
10748	<param name="flags" type="ProcessInputFlag" dir="in" safearray="yes">
10749	<desc>
10750	A combination of <link to="ProcessInputFlag"/> flags.
10751	</desc>
10752	</param>
10753	<param name="data" type="octet" dir="in" safearray="yes">
10754	<desc>
10755	Array of bytes to write. The size of the array also specifies
10756	how much to write.
10757	</desc>
10758	</param>
10759	<param name="timeoutMS" type="unsigned long" dir="in">
10760	<desc>
10761	Timeout (in ms) to wait for the operation to complete.
10762	Pass 0 for an infinite timeout.
10763	</desc>
10764	</param>
10765	<param name="written" type="unsigned long" dir="return">
10766	<desc>How much bytes were written.</desc>
10767	</param>
10768	</method>
10769
10770	<method name="terminate">
10771	<desc>
10772	Terminates (kills) a running process.
10773	</desc>
10774	</method>
10775	</interface>
10776
10777	<interface
10778	name="IGuestProcess" extends="IProcess"
10779	uuid="dfa39a36-5d43-4840-a025-67ea956b3111"
10780	wsmap="managed"
10781	>
10782	<desc>
10783	Implementation of the <link to="IProcess" /> object
10784	for processes on the guest.
10785	</desc>
10786	</interface>
10787
10788	<interface
10789	name="IDirectory" extends="$unknown"
10790	uuid="1b70dd03-26d7-483a-8877-89bbb0f87b70"
10791	wsmap="managed"
10792	>
10793	<desc>
10794	Abstract parent interface for directories handled by VirtualBox.
10795	</desc>
10796
10797	<attribute name="directoryName" type="wstring" readonly="yes">
10798	<desc>
10799	Full path of directory.
10800	</desc>
10801	</attribute>
10802
10803	<attribute name="filter" type="wstring" readonly="yes">
10804	<desc>
10805	The open filter.
10806	</desc>
10807	</attribute>
10808
10809	<method name="close">
10810	<desc>
10811	Closes this directory. After closing operations like reading the next
10812	directory entry will not be possible anymore.
10813	</desc>
10814	</method>
10815
10816	<method name="read">
10817	<desc>
10818	Reads the next directory entry of this directory.
10819	<result name="VBOX_E_OBJECT_NOT_FOUND">
10820	No more directory entries to read.
10821	</result>
10822	</desc>
10823	<param name="objInfo" type="IFsObjInfo" dir="return">
10824	<desc>Object information of the current directory entry read. Also see
10825	<link to="IFsObjInfo"/>.</desc>
10826	</param>
10827	</method>
10828	</interface>
10829
10830	<interface
10831	name="IGuestDirectory" extends="IDirectory"
10832	uuid="af4a8ce0-0725-42b7-8826-46e3c7ba7357"
10833	wsmap="managed"
10834	>
10835	<desc>
10836	Implementation of the <link to="IDirectory" /> object
10837	for directories on the guest.
10838	</desc>
10839	</interface>
10840
10841	<interface
10842	name="IFile" extends="$unknown"
10843	uuid="ceb895d7-8b2d-4a39-8f7c-7d2270f341d5"
10844	wsmap="managed"
10845	>
10846	<desc>
10847	Abstract parent interface for files handled by VirtualBox.
10848	</desc>
10849	<attribute name="creationMode" type="unsigned long" readonly="yes">
10850	<desc>
10851	The creation mode.
10852	</desc>
10853	</attribute>
10854	<attribute name="disposition" type="unsigned long" readonly="yes">
10855	<desc>
10856	The disposition mode.
10857	</desc>
10858	</attribute>
10859	<attribute name="eventSource" type="IEventSource" readonly="yes">
10860	<desc>
10861	Event source for guest session events.
10862	</desc>
10863	</attribute>
10864	<attribute name="fileName" type="wstring" readonly="yes">
10865	<desc>
10866	Full path of the actual file name of this file.
10867	</desc>
10868	</attribute>
10869	<attribute name="initialSize" type="long long" readonly="yes">
10870	<desc>
10871	The initial size in bytes when opened.
10872	</desc>
10873	</attribute>
10874	<attribute name="openMode" type="unsigned long" readonly="yes">
10875	<desc>
10876	The open mode.
10877	</desc>
10878	</attribute>
10879	<attribute name="offset" type="long long" readonly="yes">
10880	<desc>
10881	Current read/write offset in bytes.
10882	</desc>
10883	</attribute>
10884	<attribute name="status" type="FileStatus" readonly="yes">
10885	<desc>
10886	Current file status.
10887	</desc>
10888	</attribute>
10889
10890	<method name="close">
10891	<desc>
10892	Closes this file. After closing operations like reading data,
10893	writing data or querying information will not be possible anymore.
10894	</desc>
10895	</method>
10896
10897	<method name="queryInfo">
10898	<desc>
10899	Queries information about this file.
10900
10901	<result name="E_NOTIMPL">
10902	The method is not implemented yet.
10903	</result>
10904	</desc>
10905	<param name="objInfo" type="IFsObjInfo" dir="return">
10906	<desc>Object information of this file. Also see
10907	<link to="IFsObjInfo"/>.</desc>
10908	</param>
10909	</method>
10910
10911	<method name="read">
10912	<desc>
10913	Reads data from this file.
10914
10915	<result name="E_NOTIMPL">
10916	The method is not implemented yet.
10917	</result>
10918	</desc>
10919	<param name="toRead" type="unsigned long" dir="in">
10920	<desc>Number of bytes to read.</desc>
10921	</param>
10922	<param name="timeoutMS" type="unsigned long" dir="in">
10923	<desc>
10924	Timeout (in ms) to wait for the operation to complete.
10925	Pass 0 for an infinite timeout.
10926	</desc>
10927	</param>
10928	<param name="data" type="octet" dir="return" safearray="yes">
10929	<desc>Array of data read.</desc>
10930	</param>
10931	</method>
10932
10933	<method name="readAt">
10934	<desc>
10935	Reads data from an offset of this file.
10936
10937	<result name="E_NOTIMPL">
10938	The method is not implemented yet.
10939	</result>
10940	</desc>
10941	<param name="offset" type="long long" dir="in">
10942	<desc>Offset in bytes to start reading.</desc>
10943	</param>
10944	<param name="toRead" type="unsigned long" dir="in">
10945	<desc>Number of bytes to read.</desc>
10946	</param>
10947	<param name="timeoutMS" type="unsigned long" dir="in">
10948	<desc>
10949	Timeout (in ms) to wait for the operation to complete.
10950	Pass 0 for an infinite timeout.
10951	</desc>
10952	</param>
10953	<param name="data" type="octet" dir="return" safearray="yes">
10954	<desc>Array of data read.</desc>
10955	</param>
10956	</method>
10957
10958	<method name="seek">
10959	<desc>
10960	Changes the read and write position of this file.
10961
10962	<result name="E_NOTIMPL">
10963	The method is not implemented yet.
10964	</result>
10965	</desc>
10966	<param name="offset" type="long long" dir="in">
10967	<desc>Offset to seek.</desc>
10968	</param>
10969	<param name="whence" type="FileSeekType" dir="in">
10970	<desc>
10971	Seek mode; see <link to="FileSeekType"/> for more information.
10972	</desc>
10973	</param>
10974	</method>
10975
10976	<method name="setACL">
10977	<desc>
10978	Sets the ACL of this file.
10979
10980	<result name="E_NOTIMPL">
10981	The method is not implemented yet.
10982	</result>
10983	</desc>
10984	<param name="acl" type="wstring" dir="in">
10985	<desc>ACL string to set.</desc>
10986	</param>
10987	</method>
10988
10989	<method name="write">
10990	<desc>
10991	Writes bytes to this file.
10992	</desc>
10993	<param name="data" type="octet" dir="in" safearray="yes">
10994	<desc>
10995	Array of bytes to write. The size of the array also specifies
10996	how much to write.
10997	</desc>
10998	</param>
10999	<param name="timeoutMS" type="unsigned long" dir="in">
11000	<desc>
11001	Timeout (in ms) to wait for the operation to complete.
11002	Pass 0 for an infinite timeout.
11003	</desc>
11004	</param>
11005	<param name="written" type="unsigned long" dir="return">
11006	<desc>How much bytes were written.</desc>
11007	</param>
11008	</method>
11009
11010	<method name="writeAt">
11011	<desc>
11012	Writes bytes at a certain offset to this file.
11013
11014	<result name="E_NOTIMPL">
11015	The method is not implemented yet.
11016	</result>
11017	</desc>
11018	<param name="offset" type="long long" dir="in">
11019	<desc>Offset in bytes to start writing.</desc>
11020	</param>
11021	<param name="data" type="octet" dir="in" safearray="yes">
11022	<desc>
11023	Array of bytes to write. The size of the array also specifies
11024	how much to write.
11025	</desc>
11026	</param>
11027	<param name="timeoutMS" type="unsigned long" dir="in">
11028	<desc>
11029	Timeout (in ms) to wait for the operation to complete.
11030	Pass 0 for an infinite timeout.
11031	</desc>
11032	</param>
11033	<param name="written" type="unsigned long" dir="return">
11034	<desc>How much bytes were written.</desc>
11035	</param>
11036	</method>
11037
11038	</interface>
11039
11040	<interface
11041	name="IGuestFile" extends="IFile"
11042	uuid="60661aec-145f-4d11-b80e-8ea151598093"
11043	wsmap="managed"
11044	>
11045	<desc>
11046	Implementation of the <link to="IFile" /> object
11047	for files on the guest.
11048	</desc>
11049	</interface>
11050
11051	<interface
11052	name="IFsObjInfo" extends="$unknown"
11053	uuid="4047ba30-7006-4966-ae86-94164e5e20eb"
11054	wsmap="managed"
11055	>
11056	<desc>
11057	Abstract parent interface for VirtualBox file system object information.
11058	This can be information about a file or a directory, for example.
11059	</desc>
11060
11061	<attribute name="accessTime" type="long long" readonly="yes">
11062	<desc>
11063	Time of last access (st_atime).
11064	</desc>
11065	</attribute>
11066	<attribute name="allocatedSize" type="long long" readonly="yes">
11067	<desc>
11068	Disk allocation size (st_blocks * DEV_BSIZE).
11069	</desc>
11070	</attribute>
11071	<attribute name="birthTime" type="long long" readonly="yes">
11072	<desc>
11073	Time of file birth (st_birthtime).
11074	</desc>
11075	</attribute>
11076	<attribute name="changeTime" type="long long" readonly="yes">
11077	<desc>
11078	Time of last status change (st_ctime).
11079	</desc>
11080	</attribute>
11081	<attribute name="deviceNumber" type="unsigned long" readonly="yes">
11082	<desc>
11083	The device number of a character or block device type object (st_rdev).
11084	</desc>
11085	</attribute>
11086	<attribute name="fileAttributes" type="wstring" readonly="yes">
11087	<desc>
11088	File attributes. Not implemented yet.
11089	</desc>
11090	</attribute>
11091	<attribute name="generationId" type="unsigned long" readonly="yes">
11092	<desc>
11093	The current generation number (st_gen).
11094	</desc>
11095	</attribute>
11096	<attribute name="GID" type="unsigned long" readonly="yes">
11097	<desc>
11098	The group the filesystem object is assigned (st_gid).
11099	</desc>
11100	</attribute>
11101	<attribute name="groupName" type="wstring" readonly="yes">
11102	<desc>
11103	The group name.
11104	</desc>
11105	</attribute>
11106	<attribute name="hardLinks" type="unsigned long" readonly="yes">
11107	<desc>
11108	Number of hard links to this filesystem object (st_nlink).
11109	</desc>
11110	</attribute>
11111	<attribute name="modificationTime" type="long long" readonly="yes">
11112	<desc>
11113	Time of last data modification (st_mtime).
11114	</desc>
11115	</attribute>
11116	<attribute name="name" type="wstring" readonly="yes">
11117	<desc>
11118	The object's name.
11119	</desc>
11120	</attribute>
11121	<attribute name="nodeId" type="long long" readonly="yes">
11122	<desc>
11123	The unique identifier (within the filesystem) of this filesystem object (st_ino).
11124	</desc>
11125	</attribute>
11126	<attribute name="nodeIdDevice" type="unsigned long" readonly="yes">
11127	<desc>
11128	The device number of the device which this filesystem object resides on (st_dev).
11129	</desc>
11130	</attribute>
11131	<attribute name="objectSize" type="long long" readonly="yes">
11132	<desc>
11133	The logical size (st_size). For normal files this is the size of the file.
11134	For symbolic links, this is the length of the path name contained in the
11135	symbolic link. For other objects this fields needs to be specified.
11136	</desc>
11137	</attribute>
11138	<attribute name="type" type="FsObjType" readonly="yes">
11139	<desc>
11140	The object type. See <link to="FsObjType" /> for more.
11141	</desc>
11142	</attribute>
11143	<attribute name="UID" type="unsigned long" readonly="yes">
11144	<desc>
11145	The user owning the filesystem object (st_uid).
11146	</desc>
11147	</attribute>
11148	<attribute name="userFlags" type="unsigned long" readonly="yes">
11149	<desc>
11150	User flags (st_flags).
11151	</desc>
11152	</attribute>
11153	<attribute name="userName" type="wstring" readonly="yes">
11154	<desc>
11155	The user name.
11156	</desc>
11157	</attribute>
11158
11159	</interface>
11160
11161	<interface
11162	name="IGuestFsObjInfo" extends="IFsObjInfo"
11163	uuid="d5cf678e-3484-4e4a-ac55-329e15462e18"
11164	wsmap="managed"
11165	>
11166	<desc>
11167	Represents the guest implementation of the
11168	<link to="IFsObjInfo" /> object.
11169	</desc>
11170	</interface>
11171
11172	<interface
11173	name="IGuest" extends="$unknown"
11174	uuid="19c32350-0618-4ede-b0c3-2b4311bf0d9b"
11175	wsmap="managed"
11176	>
11177	<desc>
11178	The IGuest interface represents information about the operating system
11179	running inside the virtual machine. Used in
11180	<link to="IConsole::guest"/>.
11181
11182	IGuest provides information about the guest operating system, whether
11183	Guest Additions are installed and other OS-specific virtual machine
11184	properties.
11185	</desc>
11186
11187	<attribute name="OSTypeId" type="wstring" readonly="yes">
11188	<desc>
11189	Identifier of the Guest OS type as reported by the Guest
11190	Additions.
11191	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
11192	an IGuestOSType object representing details about the given
11193	Guest OS type.
11194	<note>
11195	If Guest Additions are not installed, this value will be
11196	the same as <link to="IMachine::OSTypeId"/>.
11197	</note>
11198	</desc>
11199	</attribute>
11200
11201	<attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
11202	<desc>
11203	Current run level of the Guest Additions.
11204	</desc>
11205	</attribute>
11206
11207	<attribute name="additionsVersion" type="wstring" readonly="yes">
11208	<desc>
11209	Version of the Guest Additions in the same format as
11210	<link to="IVirtualBox::version"/>.
11211	</desc>
11212	</attribute>
11213
11214	<attribute name="additionsRevision" type="unsigned long" readonly="yes">
11215	<desc>
11216	The internal build revision number of the additions.
11217
11218	See also <link to="IVirtualBox::revision"/>.
11219	</desc>
11220	</attribute>
11221
11222	<attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes">
11223	<desc>
11224	Array of current known facilities. Only returns facilities where a status is known,
11225	e.g. facilities with an unknown status will not be returned.
11226	</desc>
11227	</attribute>
11228
11229	<attribute name="sessions" type="IGuestSession" readonly="yes" safearray="yes">
11230	<desc>Returns a collection of all opened guest sessions.</desc>
11231	</attribute>
11232
11233	<attribute name="memoryBalloonSize" type="unsigned long">
11234	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
11235	</attribute>
11236
11237	<attribute name="statisticsUpdateInterval" type="unsigned long">
11238	<desc>Interval to update guest statistics in seconds.</desc>
11239	</attribute>
11240
11241	<method name="internalGetStatistics">
11242	<desc>
11243	Internal method; do not use as it might change at any time.
11244	</desc>
11245	<param name="cpuUser" type="unsigned long" dir="out">
11246	<desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
11247	</param>
11248	<param name="cpuKernel" type="unsigned long" dir="out">
11249	<desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
11250	</param>
11251	<param name="cpuIdle" type="unsigned long" dir="out">
11252	<desc>Percentage of processor time spent idling as seen by the guest.</desc>
11253	</param>
11254	<param name="memTotal" type="unsigned long" dir="out">
11255	<desc>Total amount of physical guest RAM.</desc>
11256	</param>
11257	<param name="memFree" type="unsigned long" dir="out">
11258	<desc>Free amount of physical guest RAM.</desc>
11259	</param>
11260	<param name="memBalloon" type="unsigned long" dir="out">
11261	<desc>Amount of ballooned physical guest RAM.</desc>
11262	</param>
11263	<param name="memShared" type="unsigned long" dir="out">
11264	<desc>Amount of shared physical guest RAM.</desc>
11265	</param>
11266	<param name="memCache" type="unsigned long" dir="out">
11267	<desc>Total amount of guest (disk) cache memory.</desc>
11268	</param>
11269	<param name="pagedTotal" type="unsigned long" dir="out">
11270	<desc>Total amount of space in the page file.</desc>
11271	</param>
11272	<param name="memAllocTotal" type="unsigned long" dir="out">
11273	<desc>Total amount of memory allocated by the hypervisor.</desc>
11274	</param>
11275	<param name="memFreeTotal" type="unsigned long" dir="out">
11276	<desc>Total amount of free memory available in the hypervisor.</desc>
11277	</param>
11278	<param name="memBalloonTotal" type="unsigned long" dir="out">
11279	<desc>Total amount of memory ballooned by the hypervisor.</desc>
11280	</param>
11281	<param name="memSharedTotal" type="unsigned long" dir="out">
11282	<desc>Total amount of shared memory in the hypervisor.</desc>
11283	</param>
11284	</method>
11285
11286	<method name="getFacilityStatus">
11287	<desc>
11288	Get the current status of a Guest Additions facility.
11289	</desc>
11290	<param name="facility" type="AdditionsFacilityType" dir="in">
11291	<desc>Facility to check status for.</desc>
11292	</param>
11293	<param name="timestamp" type="long long" dir="out">
11294	<desc>Timestamp (in ms) of last status update seen by the host.</desc>
11295	</param>
11296	<param name="status" type="AdditionsFacilityStatus" dir="return">
11297	<desc>The current (latest) facility status.</desc>
11298	</param>
11299	</method>
11300
11301	<method name="getAdditionsStatus">
11302	<desc>
11303	Retrieve the current status of a certain Guest Additions run level.
11304
11305	<result name="VBOX_E_NOT_SUPPORTED">
11306	Wrong status level specified.
11307	</result>
11308
11309	</desc>
11310	<param name="level" type="AdditionsRunLevelType" dir="in">
11311	<desc>Status level to check</desc>
11312	</param>
11313	<param name="active" type="boolean" dir="return">
11314	<desc>Flag whether the status level has been reached or not</desc>
11315	</param>
11316	</method>
11317
11318	<method name="setCredentials">
11319	<desc>
11320	Store login credentials that can be queried by guest operating
11321	systems with Additions installed. The credentials are transient
11322	to the session and the guest may also choose to erase them. Note
11323	that the caller cannot determine whether the guest operating system
11324	has queried or made use of the credentials.
11325
11326	<result name="VBOX_E_VM_ERROR">
11327	VMM device is not available.
11328	</result>
11329
11330	</desc>
11331	<param name="userName" type="wstring" dir="in">
11332	<desc>User name string, can be empty</desc>
11333	</param>
11334	<param name="password" type="wstring" dir="in">
11335	<desc>Password string, can be empty</desc>
11336	</param>
11337	<param name="domain" type="wstring" dir="in">
11338	<desc>Domain name (guest logon scheme specific), can be empty</desc>
11339	</param>
11340	<param name="allowInteractiveLogon" type="boolean" dir="in">
11341	<desc>
11342	Flag whether the guest should alternatively allow the user to
11343	interactively specify different credentials. This flag might
11344	not be supported by all versions of the Additions.
11345	</desc>
11346	</param>
11347	</method>
11348
11349	<method name="dragHGEnter">
11350	<desc>
11351	Informs the guest about a Drag and Drop enter event.
11352
11353	This is used in Host - Guest direction.
11354
11355	<result name="VBOX_E_VM_ERROR">
11356	VMM device is not available.
11357	</result>
11358
11359	</desc>
11360	<param name="screenId" type="unsigned long" dir="in">
11361	<desc>The screen id where the Drag and Drop event occured.</desc>
11362	</param>
11363	<param name="y" type="unsigned long" dir="in">
11364	<desc>y-position of the event.</desc>
11365	</param>
11366	<param name="x" type="unsigned long" dir="in">
11367	<desc>x-position of the event.</desc>
11368	</param>
11369	<param name="defaultAction" type="DragAndDropAction" dir="in">
11370	<desc>The default action to use.</desc>
11371	</param>
11372	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11373	<desc>The actions which are allowed.</desc>
11374	</param>
11375	<param name="formats" type="wstring" dir="in" safearray="yes">
11376	<desc>The supported mime types.</desc>
11377	</param>
11378	<param name="resultAction" type="DragAndDropAction" dir="return">
11379	<desc>The resulting action of this event.</desc>
11380	</param>
11381	</method>
11382
11383	<method name="dragHGMove">
11384	<desc>
11385	Informs the guest about a Drag and Drop move event.
11386
11387	This is used in Host - Guest direction.
11388
11389	<result name="VBOX_E_VM_ERROR">
11390	VMM device is not available.
11391	</result>
11392
11393	</desc>
11394	<param name="screenId" type="unsigned long" dir="in">
11395	<desc>The screen id where the Drag and Drop event occured.</desc>
11396	</param>
11397	<param name="x" type="unsigned long" dir="in">
11398	<desc>x-position of the event.</desc>
11399	</param>
11400	<param name="y" type="unsigned long" dir="in">
11401	<desc>y-position of the event.</desc>
11402	</param>
11403	<param name="defaultAction" type="DragAndDropAction" dir="in">
11404	<desc>The default action to use.</desc>
11405	</param>
11406	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11407	<desc>The actions which are allowed.</desc>
11408	</param>
11409	<param name="formats" type="wstring" dir="in" safearray="yes">
11410	<desc>The supported mime types.</desc>
11411	</param>
11412	<param name="resultAction" type="DragAndDropAction" dir="return">
11413	<desc>The resulting action of this event.</desc>
11414	</param>
11415	</method>
11416
11417	<method name="dragHGLeave">
11418	<desc>
11419	Informs the guest about a Drag and Drop leave event.
11420
11421	This is used in Host - Guest direction.
11422
11423	<result name="VBOX_E_VM_ERROR">
11424	VMM device is not available.
11425	</result>
11426
11427	</desc>
11428	<param name="screenId" type="unsigned long" dir="in">
11429	<desc>The screen id where the Drag and Drop event occured.</desc>
11430	</param>
11431	</method>
11432
11433	<method name="dragHGDrop">
11434	<desc>
11435	Informs the guest about a drop event.
11436
11437	This is used in Host - Guest direction.
11438
11439	<result name="VBOX_E_VM_ERROR">
11440	VMM device is not available.
11441	</result>
11442
11443	</desc>
11444	<param name="screenId" type="unsigned long" dir="in">
11445	<desc>The screen id where the Drag and Drop event occured.</desc>
11446	</param>
11447	<param name="x" type="unsigned long" dir="in">
11448	<desc>x-position of the event.</desc>
11449	</param>
11450	<param name="y" type="unsigned long" dir="in">
11451	<desc>y-position of the event.</desc>
11452	</param>
11453	<param name="defaultAction" type="DragAndDropAction" dir="in">
11454	<desc>The default action to use.</desc>
11455	</param>
11456	<param name="allowedActions" type="DragAndDropAction" dir="in" safearray="yes">
11457	<desc>The actions which are allowed.</desc>
11458	</param>
11459	<param name="formats" type="wstring" dir="in" safearray="yes">
11460	<desc>The supported mime types.</desc>
11461	</param>
11462	<param name="format" type="wstring" dir="out">
11463	<desc>The resulting format of this event.</desc>
11464	</param>
11465	<param name="resultAction" type="DragAndDropAction" dir="return">
11466	<desc>The resulting action of this event.</desc>
11467	</param>
11468	</method>
11469
11470	<method name="dragHGPutData">
11471	<desc>
11472	Informs the guest about a drop data event.
11473
11474	This is used in Host - Guest direction.
11475
11476	<result name="VBOX_E_VM_ERROR">
11477	VMM device is not available.
11478	</result>
11479
11480	</desc>
11481	<param name="screenId" type="unsigned long" dir="in">
11482	<desc>The screen id where the Drag and Drop event occured.</desc>
11483	</param>
11484	<param name="format" type="wstring" dir="in">
11485	<desc>The mime type the data is in.</desc>
11486	</param>
11487	<param name="data" type="octet" dir="in" safearray="yes">
11488	<desc>The actual data.</desc>
11489	</param>
11490	<param name="progress" type="IProgress" dir="return">
11491	<desc>Progress object to track the operation completion.</desc>
11492	</param>
11493	</method>
11494
11495	<method name="dragGHPending">
11496	<desc>
11497	Ask the guest if there is any Drag and Drop operation pending in the guest.
11498
11499	If no Drag and Drop operation is pending currently, Ignore is returned.
11500
11501	This is used in Guest - Host direction.
11502
11503	<result name="VBOX_E_VM_ERROR">
11504	VMM device is not available.
11505	</result>
11506
11507	</desc>
11508	<param name="screenId" type="unsigned long" dir="in">
11509	<desc>The screen id where the Drag and Drop event occured.</desc>
11510	</param>
11511	<param name="formats" type="wstring" dir="out" safearray="yes">
11512	<desc>On return the supported mime types.</desc>
11513	</param>
11514	<param name="allowedActions" type="DragAndDropAction" dir="out" safearray="yes">
11515	<desc>On return the actions which are allowed.</desc>
11516	</param>
11517	<param name="defaultAction" type="DragAndDropAction" dir="return">
11518	<desc>On return the default action to use.</desc>
11519	</param>
11520	</method>
11521
11522	<method name="dragGHDropped">
11523	<desc>
11524	Informs the guest that a drop event occured for a pending Drag and Drop event.
11525
11526	This is used in Guest - Host direction.
11527
11528	<result name="VBOX_E_VM_ERROR">
11529	VMM device is not available.
11530	</result>
11531
11532	</desc>
11533
11534	<param name="format" type="wstring" dir="in">
11535	<desc>The mime type the data must be in.</desc>
11536	</param>
11537	<param name="action" type="DragAndDropAction" dir="in">
11538	<desc>The action to use.</desc>
11539	</param>
11540	<param name="progress" type="IProgress" dir="return">
11541	<desc>Progress object to track the operation completion.</desc>
11542	</param>
11543	</method>
11544
11545	<method name="dragGHGetData">
11546	<desc>
11547	Fetch the data of a previously Drag and Drop event from the guest.
11548
11549	This is used in Guest - Host direction.
11550
11551	<result name="VBOX_E_VM_ERROR">
11552	VMM device is not available.
11553	</result>
11554
11555	</desc>
11556
11557	<param name="data" type="octet" safearray="yes" dir="return">
11558	<desc>The actual data.</desc>
11559	</param>
11560	</method>
11561
11562	<method name="createSession">
11563	<desc>
11564	Creates a new guest session for controlling the guest.
11565
11566	A guest session represents one impersonated user account on the guest, so
11567	every operation will use the same credentials specified when creating
11568	the session object via <link to="IGuest::createSession"/>. Anonymous
11569	sessions, that is, sessions without specifying a valid
11570	user account on the guest are not allowed due to security reasons.
11571
11572	There can be a maximum of 32 sessions at once per VM. Each session keeps
11573	track of its started guest processes, opened guest files or guest directories.
11574	To work on guest files or directories a guest session offers methods to open
11575	or create such objects (see <link to="IGuestSession::fileOpen"/> or
11576	<link to="IGuestSession::directoryOpen"/> for example).
11577
11578	When done with either of these objects, including the guest session itself,
11579	use the appropriate close() method to let the object do its cleanup work.
11580
11581	Every guest session has its own environment variable block which gets
11582	automatically applied when starting a new guest process via
11583	<link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/>.
11584	To override (or unset) certain environment variables already set by the
11585	guest session, one can specify a per-process environment block when using
11586	one of the both above mentioned process creation calls.
11587
11588	Closing a session via <link to="IGuestSession::close" /> will try to close
11589	all the mentioned objects above unless these objects are still used by
11590	a client.
11591	</desc>
11592	<param name="user" type="wstring" dir="in">
11593	<desc>
11594	User name this session will be using to control the guest; has to exist
11595	and have the appropriate rights to execute programs in the VM. Must not
11596	be empty.
11597	</desc>
11598	</param>
11599	<param name="password" type="wstring" dir="in">
11600	<desc>
11601	Password of the user account to be used. Empty passwords are allowed.
11602	</desc>
11603	</param>
11604	<param name="domain" type="wstring" dir="in">
11605	<desc>
11606	Domain name of the user account to be used if the guest is part of
11607	a domain. Optional. This feature is not implemented yet.
11608	</desc>
11609	</param>
11610	<param name="sessionName" type="wstring" dir="in">
11611	<desc>
11612	The session's friendly name. Optional, can be empty.
11613	</desc>
11614	</param>
11615	<param name="guestSession" type="IGuestSession" dir="return">
11616	<desc>
11617	The newly created session object.
11618	</desc>
11619	</param>
11620	</method>
11621
11622	<method name="findSession">
11623	<desc>
11624	Finds guest sessions by their friendly name and returns an interface
11625	array with all found guest sessions.
11626	</desc>
11627	<param name="sessionName" type="wstring" dir="in">
11628	<desc>
11629	The session's friendly name to find. Wildcards like ? and * are allowed.
11630	</desc>
11631	</param>
11632	<param name="sessions" type="IGuestSession" safearray="yes" dir="return">
11633	<desc>
11634	Array with all guest sessions found matching the name specified.
11635	</desc>
11636	</param>
11637	</method>
11638
11639	<method name="updateGuestAdditions">
11640	<desc>
11641	Automatically updates already installed Guest Additions in a VM.
11642
11643	At the moment only Windows guests are supported.
11644
11645	Because the VirtualBox Guest Additions drivers are not WHQL-certified
11646	yet there might be warning dialogs during the actual Guest Additions
11647	update. These need to be confirmed manually in order to continue the
11648	installation process. This applies to Windows 2000 and Windows XP guests
11649	and therefore these guests can't be updated in a fully automated fashion
11650	without user interaction. However, to start a Guest Additions update for
11651	the mentioned Windows versions anyway, the flag
11652	AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See
11653	<link to="AdditionsUpdateFlag"/> for more information.
11654
11655	<result name="VBOX_E_NOT_SUPPORTED">
11656	Guest OS is not supported for automated Guest Additions updates or the
11657	already installed Guest Additions are not ready yet.
11658	</result>
11659
11660	<result name="VBOX_E_IPRT_ERROR">
11661	Error while updating.
11662	</result>
11663
11664	</desc>
11665	<param name="source" type="wstring" dir="in">
11666	<desc>
11667	Path to the Guest Additions .ISO file to use for the upate.
11668	</desc>
11669	</param>
11670	<param name="flags" type="AdditionsUpdateFlag" dir="in" safearray="yes">
11671	<desc>
11672	<link to="AdditionsUpdateFlag"/> flags.
11673	</desc>
11674	</param>
11675	<param name="progress" type="IProgress" dir="return">
11676	<desc>Progress object to track the operation completion.</desc>
11677	</param>
11678	</method>
11679
11680	</interface>
11681
11682
11683	<!--
11684	// IProgress
11685	/////////////////////////////////////////////////////////////////////////
11686	-->
11687
11688	<interface
11689	name="IProgress" extends="$unknown"
11690	uuid="c20238e4-3221-4d3f-8891-81ce92d9f913"
11691	wsmap="managed"
11692	>
11693	<desc>
11694	The IProgress interface is used to track and control
11695	asynchronous tasks within VirtualBox.
11696
11697	An instance of this is returned every time VirtualBox starts
11698	an asynchronous task (in other words, a separate thread) which
11699	continues to run after a method call returns. For example,
11700	<link to="IConsole::saveState" />, which saves the state of
11701	a running virtual machine, can take a long time to complete.
11702	To be able to display a progress bar, a user interface such as
11703	the VirtualBox graphical user interface can use the IProgress
11704	object returned by that method.
11705
11706	Note that IProgress is a "read-only" interface in the sense
11707	that only the VirtualBox internals behind the Main API can
11708	create and manipulate progress objects, whereas client code
11709	can only use the IProgress object to monitor a task's
11710	progress and, if <link to="#cancelable" /> is @c true,
11711	cancel the task by calling <link to="#cancel" />.
11712
11713	A task represented by IProgress consists of either one or
11714	several sub-operations that run sequentially, one by one (see
11715	<link to="#operation" /> and <link to="#operationCount" />).
11716	Every operation is identified by a number (starting from 0)
11717	and has a separate description.
11718
11719	You can find the individual percentage of completion of the current
11720	operation in <link to="#operationPercent" /> and the
11721	percentage of completion of the task as a whole
11722	in <link to="#percent" />.
11723
11724	Similarly, you can wait for the completion of a particular
11725	operation via <link to="#waitForOperationCompletion" /> or
11726	for the completion of the whole task via
11727	<link to="#waitForCompletion" />.
11728	</desc>
11729
11730	<attribute name="id" type="uuid" mod="string" readonly="yes">
11731	<desc>ID of the task.</desc>
11732	</attribute>
11733
11734	<attribute name="description" type="wstring" readonly="yes">
11735	<desc>Description of the task.</desc>
11736	</attribute>
11737
11738	<attribute name="initiator" type="$unknown" readonly="yes">
11739	<desc>Initiator of the task.</desc>
11740	</attribute>
11741
11742	<attribute name="cancelable" type="boolean" readonly="yes">
11743	<desc>Whether the task can be interrupted.</desc>
11744	</attribute>
11745
11746	<attribute name="percent" type="unsigned long" readonly="yes">
11747	<desc>
11748	Current progress value of the task as a whole, in percent.
11749	This value depends on how many operations are already complete.
11750	Returns 100 if <link to="#completed" /> is @c true.
11751	</desc>
11752	</attribute>
11753
11754	<attribute name="timeRemaining" type="long" readonly="yes">
11755	<desc>
11756	Estimated remaining time until the task completes, in
11757	seconds. Returns 0 once the task has completed; returns -1
11758	if the remaining time cannot be computed, in particular if
11759	the current progress is 0.
11760
11761	Even if a value is returned, the estimate will be unreliable
11762	for low progress values. It will become more reliable as the
11763	task progresses; it is not recommended to display an ETA
11764	before at least 20% of a task have completed.
11765	</desc>
11766	</attribute>
11767
11768	<attribute name="completed" type="boolean" readonly="yes">
11769	<desc>Whether the task has been completed.</desc>
11770	</attribute>
11771
11772	<attribute name="canceled" type="boolean" readonly="yes">
11773	<desc>Whether the task has been canceled.</desc>
11774	</attribute>
11775
11776	<attribute name="resultCode" type="long" readonly="yes">
11777	<desc>
11778	Result code of the progress task.
11779	Valid only if <link to="#completed"/> is @c true.
11780	</desc>
11781	</attribute>
11782
11783	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
11784	<desc>
11785	Extended information about the unsuccessful result of the
11786	progress operation. May be @c null if no extended information
11787	is available.
11788	Valid only if <link to="#completed"/> is @c true and
11789	<link to="#resultCode"/> indicates a failure.
11790	</desc>
11791	</attribute>
11792
11793	<attribute name="operationCount" type="unsigned long" readonly="yes">
11794	<desc>
11795	Number of sub-operations this task is divided into.
11796	Every task consists of at least one suboperation.
11797	</desc>
11798	</attribute>
11799
11800	<attribute name="operation" type="unsigned long" readonly="yes">
11801	<desc>Number of the sub-operation being currently executed.</desc>
11802	</attribute>
11803
11804	<attribute name="operationDescription" type="wstring" readonly="yes">
11805	<desc>
11806	Description of the sub-operation being currently executed.
11807	</desc>
11808	</attribute>
11809
11810	<attribute name="operationPercent" type="unsigned long" readonly="yes">
11811	<desc>Progress value of the current sub-operation only, in percent.</desc>
11812	</attribute>
11813
11814	<attribute name="operationWeight" type="unsigned long" readonly="yes">
11815	<desc>Weight value of the current sub-operation only.</desc>
11816	</attribute>
11817
11818	<attribute name="timeout" type="unsigned long">
11819	<desc>
11820	When non-zero, this specifies the number of milliseconds after which
11821	the operation will automatically be canceled. This can only be set on
11822	cancelable objects.
11823	</desc>
11824	</attribute>
11825
11826	<method name="setCurrentOperationProgress">
11827	<desc>Internal method, not to be called externally.</desc>
11828	<param name="percent" type="unsigned long" dir="in" />
11829	</method>
11830	<method name="setNextOperation">
11831	<desc>Internal method, not to be called externally.</desc>
11832	<param name="nextOperationDescription" type="wstring" dir="in" />
11833	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
11834	</method>
11835
11836	<method name="waitForCompletion">
11837	<desc>
11838	Waits until the task is done (including all sub-operations)
11839	with a given timeout in milliseconds; specify -1 for an indefinite wait.
11840
11841	Note that the VirtualBox/XPCOM/COM/native event queues of the calling
11842	thread are not processed while waiting. Neglecting event queues may
11843	have dire consequences (degrade performance, resource hogs,
11844	deadlocks, etc.), this is specially so for the main thread on
11845	platforms using XPCOM. Callers are adviced wait for short periods
11846	and service their event queues between calls, or to create a worker
11847	thread to do the waiting.
11848
11849	<result name="VBOX_E_IPRT_ERROR">
11850	Failed to wait for task completion.
11851	</result>
11852	</desc>
11853
11854	<param name="timeout" type="long" dir="in">
11855	<desc>
11856	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11857	</desc>
11858	</param>
11859	</method>
11860
11861	<method name="waitForOperationCompletion">
11862	<desc>
11863	Waits until the given operation is done with a given timeout in
11864	milliseconds; specify -1 for an indefinite wait.
11865
11866	See <link to="#waitForCompletion"> for event queue considerations.</link>
11867
11868	<result name="VBOX_E_IPRT_ERROR">
11869	Failed to wait for operation completion.
11870	</result>
11871
11872	</desc>
11873	<param name="operation" type="unsigned long" dir="in">
11874	<desc>
11875	Number of the operation to wait for.
11876	Must be less than <link to="#operationCount"/>.
11877	</desc>
11878	</param>
11879	<param name="timeout" type="long" dir="in">
11880	<desc>
11881	Maximum time in milliseconds to wait or -1 to wait indefinitely.
11882	</desc>
11883	</param>
11884	</method>
11885
11886	<method name="waitForAsyncProgressCompletion">
11887	<desc>
11888	Waits until the other task is completed (including all
11889	sub-operations) and forward all changes from the other progress to
11890	this progress. This means sub-operation number, description, percent
11891	and so on.
11892
11893	You have to take care on setting up at least the same count on
11894	sub-operations in this progress object like there are in the other
11895	progress object.
11896
11897	If the other progress object supports cancel and this object gets any
11898	cancel request (when here enabled as well), it will be forwarded to
11899	the other progress object.
11900
11901	If there is an error in the other progress, this error isn't
11902	automatically transfered to this progress object. So you have to
11903	check any operation error within the other progress object, after
11904	this method returns.
11905	</desc>
11906
11907	<param name="pProgressAsync" type="IProgress" dir="in">
11908	<desc>
11909	The progress object of the asynchrony process.
11910	</desc>
11911	</param>
11912	</method>
11913
11914	<method name="cancel">
11915	<desc>
11916	Cancels the task.
11917	<note>
11918	If <link to="#cancelable"/> is @c false, then this method will fail.
11919	</note>
11920
11921	<result name="VBOX_E_INVALID_OBJECT_STATE">
11922	Operation cannot be canceled.
11923	</result>
11924
11925	</desc>
11926	</method>
11927
11928	</interface>
11929
11930	<!--
11931	// ISnapshot
11932	/////////////////////////////////////////////////////////////////////////
11933	-->
11934
11935	<interface
11936	name="ISnapshot" extends="$unknown"
11937	uuid="0472823b-c6e7-472a-8e9f-d732e86b8463"
11938	wsmap="managed"
11939	>
11940	<desc>
11941	The ISnapshot interface represents a snapshot of the virtual
11942	machine.
11943
11944	Together with the differencing media that are created
11945	when a snapshot is taken, a machine can be brought back to
11946	the exact state it was in when the snapshot was taken.
11947
11948	The ISnapshot interface has no methods, only attributes; snapshots
11949	are controlled through methods of the <link to="IConsole" /> interface
11950	which also manage the media associated with the snapshot.
11951	The following operations exist:
11952
11953	<ul>
11954	<li><link to="IConsole::takeSnapshot"/> creates a new snapshot
11955	by creating new, empty differencing images for the machine's
11956	media and saving the VM settings and (if the VM is running)
11957	the current VM state in the snapshot.
11958
11959	The differencing images will then receive all data written to
11960	the machine's media, while their parent (base) images
11961	remain unmodified after the snapshot has been taken (see
11962	<link to="IMedium" /> for details about differencing images).
11963	This simplifies restoring a machine to the state of a snapshot:
11964	only the differencing images need to be deleted.
11965
11966	The current machine state is not changed by taking a snapshot
11967	except that <link to="IMachine::currentSnapshot" /> is set to
11968	the newly created snapshot, which is also added to the machine's
11969	snapshots tree.
11970	</li>
11971
11972	<li><link to="IConsole::restoreSnapshot"/> resets a machine to
11973	the state of a previous snapshot by deleting the differencing
11974	image of each of the machine's media and setting the machine's
11975	settings and state to the state that was saved in the snapshot (if any).
11976
11977	This destroys the machine's current state. After calling this,
11978	<link to="IMachine::currentSnapshot" /> points to the snapshot
11979	that was restored.
11980	</li>
11981
11982	<li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
11983	without affecting the current machine state.
11984
11985	This does not change the current machine state, but instead frees the
11986	resources allocated when the snapshot was taken: the settings and machine
11987	state file are deleted (if any), and the snapshot's differencing image for
11988	each of the machine's media gets merged with its parent image.
11989
11990	Neither the current machine state nor other snapshots are affected
11991	by this operation, except that parent media will be modified
11992	to contain the disk data associated with the snapshot being deleted.
11993
11994	When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
11995	attribute is set to the current snapshot's parent or @c null if it
11996	has no parent. Otherwise the attribute is unchanged.
11997	</li>
11998	</ul>
11999
12000	Each snapshot contains a copy of virtual machine's settings (hardware
12001	configuration etc.). This copy is contained in an immutable (read-only)
12002	instance of <link to="IMachine" /> which is available from the snapshot's
12003	<link to="#machine" /> attribute. When restoring the snapshot, these
12004	settings are copied back to the original machine.
12005
12006	In addition, if the machine was running when the
12007	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
12008	the current VM state is saved in the snapshot (similarly to what happens
12009	when a VM's state is saved). The snapshot is then said to be <i>online</i>
12010	because when restoring it, the VM will be running.
12011
12012	If the machine was in <link to="MachineState_Saved">saved</link> saved,
12013	the snapshot receives a copy of the execution state file
12014	(<link to="IMachine::stateFilePath"/>).
12015
12016	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
12017	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
12018	it then contains a so-called "zero execution state", representing a
12019	machine that is powered off.
12020	</desc>
12021
12022	<attribute name="id" type="uuid" mod="string" readonly="yes">
12023	<desc>UUID of the snapshot.</desc>
12024	</attribute>
12025
12026	<attribute name="name" type="wstring">
12027	<desc>Short name of the snapshot.
12028	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12029	be called implicitly.</note>
12030	</desc>
12031	</attribute>
12032
12033	<attribute name="description" type="wstring">
12034	<desc>Optional description of the snapshot.
12035	<note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
12036	be called implicitly.</note>
12037	</desc>
12038	</attribute>
12039
12040	<attribute name="timeStamp" type="long long" readonly="yes">
12041	<desc>
12042	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
12043	</desc>
12044	</attribute>
12045
12046	<attribute name="online" type="boolean" readonly="yes">
12047	<desc>
12048	@c true if this snapshot is an online snapshot and @c false otherwise.
12049
12050	When this attribute is @c true, the
12051	<link to="IMachine::stateFilePath"/> attribute of the
12052	<link to="#machine"/> object associated with this snapshot
12053	will point to the saved state file. Otherwise, it will be
12054	an empty string.
12055	</desc>
12056	</attribute>
12057
12058	<attribute name="machine" type="IMachine" readonly="yes">
12059	<desc>
12060	Virtual machine this snapshot is taken on. This object
12061	stores all settings the machine had when taking this snapshot.
12062	<note>
12063	The returned machine object is immutable, i.e. no
12064	any settings can be changed.
12065	</note>
12066	</desc>
12067	</attribute>
12068
12069	<attribute name="parent" type="ISnapshot" readonly="yes">
12070	<desc>
12071	Parent snapshot (a snapshot this one is based on), or
12072	@c null if the snapshot has no parent (i.e. is the first snapshot).
12073	</desc>
12074	</attribute>
12075
12076	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
12077	<desc>
12078	Child snapshots (all snapshots having this one as a parent).
12079	By inspecting this attribute starting with a machine's root snapshot
12080	(which can be obtained by calling <link to="IMachine::findSnapshot" />
12081	with a @c null UUID), a machine's snapshots tree can be iterated over.
12082	</desc>
12083	</attribute>
12084
12085	<method name="getChildrenCount" const="yes">
12086	<desc>
12087	Returns the number of direct childrens of this snapshot.
12088	</desc>
12089	<param name="childrenCount" type="unsigned long" dir="return">
12090	<desc>
12091	</desc>
12092	</param>
12093	</method>
12094
12095	</interface>
12096
12097
12098	<!--
12099	// IMedium
12100	/////////////////////////////////////////////////////////////////////////
12101	-->
12102
12103	<enum
12104	name="MediumState"
12105	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
12106	>
12107	<desc>
12108	Virtual medium state.
12109	<see><link to="IMedium"/></see>
12110	</desc>
12111
12112	<const name="NotCreated" value="0">
12113	<desc>
12114	Associated medium storage does not exist (either was not created yet or
12115	was deleted).
12116	</desc>
12117	</const>
12118	<const name="Created" value="1">
12119	<desc>
12120	Associated storage exists and accessible; this gets set if the
12121	accessibility check performed by <link to="IMedium::refreshState" />
12122	was successful.
12123	</desc>
12124	</const>
12125	<const name="LockedRead" value="2">
12126	<desc>
12127	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
12128	no data modification is possible.
12129	</desc>
12130	</const>
12131	<const name="LockedWrite" value="3">
12132	<desc>
12133	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
12134	no concurrent data reading or modification is possible.
12135	</desc>
12136	</const>
12137	<const name="Inaccessible" value="4">
12138	<desc>
12139	Medium accessibility check (see <link to="IMedium::refreshState" />) has
12140	not yet been performed, or else, associated medium storage is not
12141	accessible. In the first case, <link to="IMedium::lastAccessError"/>
12142	is empty, in the second case, it describes the error that occurred.
12143	</desc>
12144	</const>
12145	<const name="Creating" value="5">
12146	<desc>
12147	Associated medium storage is being created.
12148	</desc>
12149	</const>
12150	<const name="Deleting" value="6">
12151	<desc>
12152	Associated medium storage is being deleted.
12153	</desc>
12154	</const>
12155	</enum>
12156
12157	<enum
12158	name="MediumType"
12159	uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04"
12160	>
12161	<desc>
12162	Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
12163	attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
12164	when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
12165	the medium attached. At the moment DVD and floppy media are always of type "writethrough".
12166	</desc>
12167
12168	<const name="Normal" value="0">
12169	<desc>
12170	Normal medium (attached directly or indirectly, preserved
12171	when taking snapshots).
12172	</desc>
12173	</const>
12174	<const name="Immutable" value="1">
12175	<desc>
12176	Immutable medium (attached indirectly, changes are wiped out
12177	the next time the virtual machine is started).
12178	</desc>
12179	</const>
12180	<const name="Writethrough" value="2">
12181	<desc>
12182	Write through medium (attached directly, ignored when
12183	taking snapshots).
12184	</desc>
12185	</const>
12186	<const name="Shareable" value="3">
12187	<desc>
12188	Allow using this medium concurrently by several machines.
12189	<note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
12190	</desc>
12191	</const>
12192	<const name="Readonly" value="4">
12193	<desc>
12194	A readonly medium, which can of course be used by several machines.
12195	<note>Present and accepted since VirtualBox 4.0.</note>
12196	</desc>
12197	</const>
12198	<const name="MultiAttach" value="5">
12199	<desc>
12200	A medium which is indirectly attached, so that one base medium can
12201	be used for several VMs which have their own differencing medium to
12202	store their modifications. In some sense a variant of Immutable
12203	with unset AutoReset flag in each differencing medium.
12204	<note>Present and accepted since VirtualBox 4.0.</note>
12205	</desc>
12206	</const>
12207	</enum>
12208
12209	<enum
12210	name="MediumVariant"
12211	uuid="80685b6b-e42f-497d-8271-e77bf3c61ada"
12212	>
12213	<desc>
12214	Virtual medium image variant. More than one flag may be set.
12215	<see><link to="IMedium"/></see>
12216	</desc>
12217
12218	<const name="Standard" value="0">
12219	<desc>
12220	No particular variant requested, results in using the backend default.
12221	</desc>
12222	</const>
12223	<const name="VmdkSplit2G" value="0x01">
12224	<desc>
12225	VMDK image split in chunks of less than 2GByte.
12226	</desc>
12227	</const>
12228	<const name="VmdkRawDisk" value="0x02">
12229	<desc>
12230	VMDK image representing a raw disk.
12231	</desc>
12232	</const>
12233	<const name="VmdkStreamOptimized" value="0x04">
12234	<desc>
12235	VMDK streamOptimized image. Special import/export format which is
12236	read-only/append-only.
12237	</desc>
12238	</const>
12239	<const name="VmdkESX" value="0x08">
12240	<desc>
12241	VMDK format variant used on ESX products.
12242	</desc>
12243	</const>
12244	<const name="Fixed" value="0x10000">
12245	<desc>
12246	Fixed image. Only allowed for base images.
12247	</desc>
12248	</const>
12249	<const name="Diff" value="0x20000">
12250	<desc>
12251	Differencing image. Only allowed for child images.
12252	</desc>
12253	</const>
12254	<const name="NoCreateDir" value="0x40000000">
12255	<desc>
12256	Special flag which suppresses automatic creation of the subdirectory.
12257	Only used when passing the medium variant as an input parameter.
12258	</desc>
12259	</const>
12260	</enum>
12261
12262	<interface
12263	name="IMediumAttachment" extends="$unknown"
12264	uuid="5ee464d6-0613-4331-b154-7ce12170ef9f"
12265	wsmap="struct"
12266	>
12267	<desc>
12268	The IMediumAttachment interface links storage media to virtual machines.
12269	For each medium (<link to="IMedium"/>) which has been attached to a
12270	storage controller (<link to="IStorageController"/>) of a machine
12271	(<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
12272	method, one instance of IMediumAttachment is added to the machine's
12273	<link to="IMachine::mediumAttachments"/> array attribute.
12274
12275	Each medium attachment specifies the storage controller as well as a
12276	port and device number and the IMedium instance representing a virtual
12277	hard disk or floppy or DVD image.
12278
12279	For removable media (DVDs or floppies), there are two additional
12280	options. For one, the IMedium instance can be @c null to represent
12281	an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
12282	secondly, the medium can be one of the pseudo-media for host drives
12283	listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
12284
12285	<h3>Attaching Hard Disks</h3>
12286
12287	Hard disks are attached to virtual machines using the
12288	<link to="IMachine::attachDevice"/> method and detached using the
12289	<link to="IMachine::detachDevice"/> method. Depending on a medium's
12290	type (see <link to="IMedium::type" />), hard disks are attached either
12291	<i>directly</i> or <i>indirectly</i>.
12292
12293	When a hard disk is being attached directly, it is associated with the
12294	virtual machine and used for hard disk operations when the machine is
12295	running. When a hard disk is being attached indirectly, a new differencing
12296	hard disk linked to it is implicitly created and this differencing hard
12297	disk is associated with the machine and used for hard disk operations.
12298	This also means that if <link to="IMachine::attachDevice"/> performs
12299	a direct attachment then the same hard disk will be returned in response
12300	to the subsequent <link to="IMachine::getMedium"/> call; however if
12301	an indirect attachment is performed then
12302	<link to="IMachine::getMedium"/> will return the implicitly created
12303	differencing hard disk, not the original one passed to <link
12304	to="IMachine::attachDevice"/>. In detail:
12305
12306	<ul>
12307	<li><b>Normal base</b> hard disks that do not have children (i.e.
12308	differencing hard disks linked to them) and that are not already
12309	attached to virtual machines in snapshots are attached <b>directly</b>.
12310	Otherwise, they are attached <b>indirectly</b> because having
12311	dependent children or being part of the snapshot makes it impossible
12312	to modify hard disk contents without breaking the integrity of the
12313	dependent party. The <link to="IMedium::readOnly"/> attribute allows to
12314	quickly determine the kind of the attachment for the given hard
12315	disk. Note that if a normal base hard disk is to be indirectly
12316	attached to a virtual machine with snapshots then a special
12317	procedure called <i>smart attachment</i> is performed (see below).</li>
12318	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
12319	they are attached <b>directly</b> if they do not have children and are
12320	not attached to virtual machines in snapshots, and <b>indirectly</b>
12321	otherwise. Note that the smart attachment procedure is never performed
12322	for differencing hard disks.</li>
12323	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
12324	they are designed to be non-writable. If an immutable hard disk is
12325	attached to a virtual machine with snapshots then a special
12326	procedure called smart attachment is performed (see below).</li>
12327	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
12328	also as designed. This also means that writethrough hard disks cannot
12329	have other hard disks linked to them at all.</li>
12330	<li><b>Shareable</b> hard disks are always attached <b>directly</b>,
12331	also as designed. This also means that shareable hard disks cannot
12332	have other hard disks linked to them at all. They behave almost
12333	like writethrough hard disks, except that shareable hard disks can
12334	be attached to several virtual machines which are running, allowing
12335	concurrent accesses. You need special cluster software running in
12336	the virtual machines to make use of such disks.</li>
12337	</ul>
12338
12339	Note that the same hard disk, regardless of its type, may be attached to
12340	more than one virtual machine at a time. In this case, the machine that is
12341	started first gains exclusive access to the hard disk and attempts to
12342	start other machines having this hard disk attached will fail until the
12343	first machine is powered down.
12344
12345	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
12346	that the given hard disk remains associated with the given machine after a
12347	successful <link to="IMachine::detachDevice"/> call until
12348	<link to="IMachine::saveSettings"/> is called to save all changes to
12349	machine settings to disk. This deferring is necessary to guarantee that
12350	the hard disk configuration may be restored at any time by a call to
12351	<link to="IMachine::discardSettings"/> before the settings
12352	are saved (committed).
12353
12354	Note that if <link to="IMachine::discardSettings"/> is called after
12355	indirectly attaching some hard disks to the machine but before a call to
12356	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
12357	all differencing hard disks implicitly created by
12358	<link to="IMachine::attachDevice"/> for these indirect attachments.
12359	Such implicitly created hard disks will also be immediately deleted when
12360	detached explicitly using the <link to="IMachine::detachDevice"/>
12361	call if it is made before <link to="IMachine::saveSettings"/>. This
12362	implicit deletion is safe because newly created differencing hard
12363	disks do not contain any user data.
12364
12365	However, keep in mind that detaching differencing hard disks that were
12366	implicitly created by <link to="IMachine::attachDevice"/>
12367	before the last <link to="IMachine::saveSettings"/> call will
12368	<b>not</b> implicitly delete them as they may already contain some data
12369	(for example, as a result of virtual machine execution). If these hard
12370	disks are no more necessary, the caller can always delete them explicitly
12371	using <link to="IMedium::deleteStorage"/> after they are actually de-associated
12372	from this machine by the <link to="IMachine::saveSettings"/> call.
12373
12374	<h3>Smart Attachment</h3>
12375
12376	When normal base or immutable hard disks are indirectly attached to a
12377	virtual machine then some additional steps are performed to make sure the
12378	virtual machine will have the most recent "view" of the hard disk being
12379	attached. These steps include walking through the machine's snapshots
12380	starting from the current one and going through ancestors up to the first
12381	snapshot. Hard disks attached to the virtual machine in all
12382	of the encountered snapshots are checked whether they are descendants of
12383	the given normal base or immutable hard disk. The first found child (which
12384	is the differencing hard disk) will be used instead of the normal base or
12385	immutable hard disk as a parent for creating a new differencing hard disk
12386	that will be actually attached to the machine. And only if no descendants
12387	are found or if the virtual machine does not have any snapshots then the
12388	normal base or immutable hard disk will be used itself as a parent for
12389	this differencing hard disk.
12390
12391	It is easier to explain what smart attachment does using the
12392	following example:
12393	<pre>
12394	BEFORE attaching B.vdi: AFTER attaching B.vdi:
12395
12396	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
12397	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
12398	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
12399	Snapshot 4 (none) Snapshot 4 (none)
12400	CurState (none) CurState (D3->D2.vdi)
12401
12402	NOT
12403	...
12404	CurState (D3->B.vdi)
12405	</pre>
12406	The first column is the virtual machine configuration before the base hard
12407	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
12408	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
12409	mean that the hard disk that is actually attached to the machine is a
12410	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
12411	another hard disk, <tt>B.vdi</tt>.
12412
12413	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
12414	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
12415	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
12416	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
12417	it cannot be attached directly and needs an indirect attachment (i.e.
12418	implicit creation of a new differencing hard disk). Due to the smart
12419	attachment procedure, the new differencing hard disk
12420	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
12421	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
12422	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
12423	machine.
12424
12425	Note that if there is more than one descendant hard disk of the given base
12426	hard disk found in a snapshot, and there is an exact device, channel and
12427	bus match, then this exact match will be used. Otherwise, the youngest
12428	descendant will be picked up.
12429
12430	There is one more important aspect of the smart attachment procedure which
12431	is not related to snapshots at all. Before walking through the snapshots
12432	as described above, the backup copy of the current list of hard disk
12433	attachment is searched for descendants. This backup copy is created when
12434	the hard disk configuration is changed for the first time after the last
12435	<link to="IMachine::saveSettings"/> call and used by
12436	<link to="IMachine::discardSettings"/> to undo the recent hard disk
12437	changes. When such a descendant is found in this backup copy, it will be
12438	simply re-attached back, without creating a new differencing hard disk for
12439	it. This optimization is necessary to make it possible to re-attach the
12440	base or immutable hard disk to a different bus, channel or device slot
12441	without losing the contents of the differencing hard disk actually
12442	attached to the machine in place of it.
12443
12444	</desc>
12445
12446	<attribute name="medium" type="IMedium" readonly="yes">
12447	<desc>Medium object associated with this attachment; it
12448	can be @c null for removable devices.</desc>
12449	</attribute>
12450
12451	<attribute name="controller" type="wstring" readonly="yes">
12452	<desc>Name of the storage controller of this attachment; this
12453	refers to one of the controllers in <link to="IMachine::storageControllers" />
12454	by name.</desc>
12455	</attribute>
12456
12457	<attribute name="port" type="long" readonly="yes">
12458	<desc>Port number of this attachment.
12459	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
12460	</desc>
12461	</attribute>
12462
12463	<attribute name="device" type="long" readonly="yes">
12464	<desc>Device slot 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="type" type="DeviceType" readonly="yes">
12470	<desc>Device type of this attachment.</desc>
12471	</attribute>
12472
12473	<attribute name="passthrough" type="boolean" readonly="yes">
12474	<desc>Pass I/O requests through to a device on the host.</desc>
12475	</attribute>
12476
12477	<attribute name="temporaryEject" type="boolean" readonly="yes">
12478	<desc>Whether guest-triggered eject results in unmounting the medium.</desc>
12479	</attribute>
12480
12481	<attribute name="isEjected" type="boolean" readonly="yes">
12482	<desc>Signals that the removable medium has been ejected. This is not
12483	necessarily equivalent to having a @c null medium association.</desc>
12484	</attribute>
12485
12486	<attribute name="nonRotational" type="boolean" readonly="yes">
12487	<desc>Whether the associated medium is non-rotational.</desc>
12488	</attribute>
12489
12490	<attribute name="discard" type="boolean" readonly="yes">
12491	<desc>Whether the associated medium supports discarding unused blocks.</desc>
12492	</attribute>
12493
12494	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
12495	<desc>The bandwidth group this medium attachment is assigned to.</desc>
12496	</attribute>
12497
12498	</interface>
12499
12500	<interface
12501	name="IMedium" extends="$unknown"
12502	uuid="86fd6208-4c8c-40c2-a4e3-f6b47ac6ef07"
12503	wsmap="managed"
12504	>
12505	<desc>
12506	The IMedium interface represents virtual storage for a machine's
12507	hard disks, CD/DVD or floppy drives. It will typically represent
12508	a disk image on the host, for example a VDI or VMDK file representing
12509	a virtual hard disk, or an ISO or RAW file representing virtual
12510	removable media, but can also point to a network location (e.g.
12511	for iSCSI targets).
12512
12513	Instances of IMedium are connected to virtual machines by way of medium
12514	attachments, which link the storage medium to a particular device slot
12515	of a storage controller of the virtual machine.
12516	In the VirtualBox API, virtual storage is therefore always represented
12517	by the following chain of object links:
12518
12519	<ul>
12520	<li><link to="IMachine::storageControllers"/> contains an array of
12521	storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
12522	these are instances of <link to="IStorageController"/>).</li>
12523	<li><link to="IMachine::mediumAttachments"/> contains an array of
12524	medium attachments (instances of <link to="IMediumAttachment"/>
12525	created by <link to="IMachine::attachDevice" />),
12526	each containing a storage controller from the above array, a
12527	port/device specification, and an instance of IMedium representing
12528	the medium storage (image file).
12529
12530	For removable media, the storage medium is optional; a medium
12531	attachment with no medium represents a CD/DVD or floppy drive
12532	with no medium inserted. By contrast, hard disk attachments
12533	will always have an IMedium object attached.</li>
12534	<li>Each IMedium in turn points to a storage unit (such as a file
12535	on the host computer or a network resource) that holds actual
12536	data. This location is represented by the <link to="#location"/>
12537	attribute.</li>
12538	</ul>
12539
12540	Existing media are opened using <link to="IVirtualBox::openMedium"/>;
12541	new hard disk media can be created with the VirtualBox API using the
12542	<link to="IVirtualBox::createHardDisk"/> method. Differencing hard
12543	disks (see below) are usually implicitly created by VirtualBox as
12544	needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
12545	VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
12546	should be created with external tools and then opened from within VirtualBox.
12547
12548	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
12549	drive. In that case the <link to="#id" /> attribute contains the UUID of
12550	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
12551
12552	<h3>Media registries</h3>
12553
12554	When a medium has been opened or created using one of the aforementioned
12555	APIs, it becomes "known" to VirtualBox. Known media can be attached
12556	to virtual machines and re-found through <link to="IVirtualBox::openMedium"/>.
12557	They also appear in the global
12558	<link to="IVirtualBox::hardDisks" />,
12559	<link to="IVirtualBox::DVDImages" /> and
12560	<link to="IVirtualBox::floppyImages" /> arrays.
12561
12562	Prior to VirtualBox 4.0, opening a medium added it to a global media registry
12563	in the VirtualBox.xml file, which was shared between all machines and made
12564	transporting machines and their media from one host to another difficult.
12565
12566	Starting with VirtualBox 4.0, media are only added to a registry when they are
12567	<i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
12568	backwards compatibility, which registry a medium is added to depends on which
12569	VirtualBox version created a machine:
12570
12571	<ul>
12572	<li>If the medium has first been attached to a machine which was created by
12573	VirtualBox 4.0 or later, it is added to that machine's media registry in
12574	the machine XML settings file. This way all information about a machine's
12575	media attachments is contained in a single file and can be transported
12576	easily.</li>
12577	<li>For older media attachments (i.e. if the medium was first attached to a
12578	machine which was created with a VirtualBox version before 4.0), media
12579	continue to be registered in the global VirtualBox settings file, for
12580	backwards compatibility.</li>
12581	</ul>
12582
12583	See <link to="IVirtualBox::openMedium" /> for more information.
12584
12585	Media are removed from media registries by the <link to="IMedium::close"/>,
12586	<link to="#deleteStorage"/> and <link to="#mergeTo"/> methods.
12587
12588	<h3>Accessibility checks</h3>
12589
12590	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
12591	method is called explicitly on a medium. This is done to make the VirtualBox object
12592	ready for serving requests as fast as possible and let the end-user
12593	application decide if it needs to check media accessibility right away or not.
12594
12595	As a result, when VirtualBox starts up (e.g. the VirtualBox
12596	object gets created for the first time), all known media are in the
12597	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
12598	attribute is an empty string because no actual accessibility check has
12599	been made yet.
12600
12601	After calling <link to="#refreshState" />, a medium is considered
12602	<i>accessible</i> if its storage unit can be read. In that case, the
12603	<link to="#state"/> attribute has a value of "Created". If the storage
12604	unit cannot be read (for example, because it is located on a disconnected
12605	network resource, or was accidentally deleted outside VirtualBox),
12606	the medium is considered <i>inaccessible</i>, which is indicated by the
12607	"Inaccessible" state. The exact reason why the medium is inaccessible can be
12608	obtained by reading the <link to="#lastAccessError"/> attribute.
12609
12610	<h3>Medium types</h3>
12611
12612	There are five types of medium behavior which are stored in the
12613	<link to="#type"/> attribute (see <link to="MediumType" />) and
12614	which define the medium's behavior with attachments and snapshots.
12615
12616	All media can be also divided in two groups: <i>base</i> media and
12617	<i>differencing</i> media. A base medium contains all sectors of the
12618	medium data in its own storage and therefore can be used independently.
12619	In contrast, a differencing medium is a "delta" to some other medium and
12620	contains only those sectors which differ from that other medium, which is
12621	then called a <i>parent</i>. The differencing medium is said to be
12622	<i>linked to</i> that parent. The parent may be itself a differencing
12623	medium, thus forming a chain of linked media. The last element in that
12624	chain must always be a base medium. Note that several differencing
12625	media may be linked to the same parent medium.
12626
12627	Differencing media can be distinguished from base media by querying the
12628	<link to="#parent"/> attribute: base media do not have parents they would
12629	depend on, so the value of this attribute is always @c null for them.
12630	Using this attribute, it is possible to walk up the medium tree (from the
12631	child medium to its parent). It is also possible to walk down the tree
12632	using the <link to="#children"/> attribute.
12633
12634	Note that the type of all differencing media is "normal"; all other
12635	values are meaningless for them. Base media may be of any type.
12636
12637	<h3>Automatic composition of the file name part</h3>
12638
12639	Another extension to the <link to="IMedium::location"/> attribute is that
12640	there is a possibility to cause VirtualBox to compose a unique value for
12641	the file name part of the location using the UUID of the hard disk. This
12642	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
12643	e.g. before the storage unit is created, and works as follows. You set the
12644	value of the <link to="IMedium::location"/> attribute to a location
12645	specification which only contains the path specification but not the file
12646	name part and ends with either a forward slash or a backslash character.
12647	In response, VirtualBox will generate a new UUID for the hard disk and
12648	compose the file name using the following pattern:
12649	<pre>
12650	<path>/{<uuid>}.<ext>
12651	</pre>
12652	where <tt><path></tt> is the supplied path specification,
12653	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
12654	is the default extension for the storage format of this hard disk. After
12655	that, you may call any of the methods that create a new hard disk storage
12656	unit and they will use the generated UUID and file name.
12657	</desc>
12658
12659	<attribute name="id" type="uuid" mod="string" readonly="yes">
12660	<desc>
12661	UUID of the medium. For a newly created medium, this value is a randomly
12662	generated UUID.
12663
12664	<note>
12665	For media in one of MediumState_NotCreated, MediumState_Creating or
12666	MediumState_Deleting states, the value of this property is undefined
12667	and will most likely be an empty UUID.
12668	</note>
12669	</desc>
12670	</attribute>
12671
12672	<attribute name="description" type="wstring">
12673	<desc>
12674	Optional description of the medium. For a newly created medium the value
12675	of this attribute is an empty string.
12676
12677	Medium types that don't support this attribute will return E_NOTIMPL in
12678	attempt to get or set this attribute's value.
12679
12680	<note>
12681	For some storage types, reading this attribute may return an outdated
12682	(last known) value when <link to="#state"/> is <link
12683	to="MediumState_Inaccessible"/> or <link
12684	to="MediumState_LockedWrite"/> because the value of this attribute is
12685	stored within the storage unit itself. Also note that changing the
12686	attribute value is not possible in such case, as well as when the
12687	medium is the <link to="MediumState_LockedRead"/> state.
12688	</note>
12689	</desc>
12690	</attribute>
12691
12692	<attribute name="state" type="MediumState" readonly="yes">
12693	<desc>
12694	Returns the current medium state, which is the last state set by
12695	the accessibility check performed by <link to="#refreshState"/>.
12696	If that method has not yet been called on the medium, the state
12697	is "Inaccessible"; as opposed to truly inaccessible media, the
12698	value of <link to="#lastAccessError"/> will be an empty string in
12699	that case.
12700
12701	<note>As of version 3.1, this no longer performs an accessibility check
12702	automatically; call <link to="#refreshState"/> for that.
12703	</note>
12704	</desc>
12705	</attribute>
12706
12707	<attribute name="variant" type="MediumVariant" safearray="yes" readonly="yes">
12708	<desc>
12709	Returns the storage format variant information for this medium
12710	as an aaray of the flags described at <link to="MediumVariant" />.
12711	Before <link to="#refreshState"/> is called this method returns
12712	an undefined value.
12713	</desc>
12714	</attribute>
12715
12716	<attribute name="location" type="wstring">
12717	<desc>
12718	Location of the storage unit holding medium data.
12719
12720	The format of the location string is medium type specific. For medium
12721	types using regular files in a host's file system, the location
12722	string is the full file name.
12723
12724	Some medium types may support changing the storage unit location by
12725	simply changing the value of this property. If this operation is not
12726	supported, the implementation will return E_NOTIMPL in attempt to set
12727	this attribute's value.
12728
12729	When setting a value of the location attribute which is a regular file
12730	in the host's file system, the given file name may be either relative to
12731	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
12732	absolute. Note that if the given location specification does not contain
12733	the file extension part then a proper default extension will be
12734	automatically appended by the implementation depending on the medium type.
12735	</desc>
12736	</attribute>
12737
12738	<attribute name="name" type="wstring" readonly="yes">
12739	<desc>
12740	Name of the storage unit holding medium data.
12741
12742	The returned string is a short version of the <link to="#location"/>
12743	attribute that is suitable for representing the medium in situations
12744	where the full location specification is too long (such as lists
12745	and comboboxes in GUI frontends). This string is also used by frontends
12746	to sort the media list alphabetically when needed.
12747
12748	For example, for locations that are regular files in the host's file
12749	system, the value of this attribute is just the file name (+ extension),
12750	without the path specification.
12751
12752	Note that as opposed to the <link to="#location"/> attribute, the name
12753	attribute will not necessary be unique for a list of media of the
12754	given type and format.
12755	</desc>
12756	</attribute>
12757
12758	<attribute name="deviceType" type="DeviceType" readonly="yes">
12759	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
12760	medium.</desc>
12761	</attribute>
12762
12763	<attribute name="hostDrive" type="boolean" readonly="yes">
12764	<desc>True if this corresponds to a drive on the host.</desc>
12765	</attribute>
12766
12767	<attribute name="size" type="long long" readonly="yes">
12768	<desc>
12769	Physical size of the storage unit used to hold medium data (in bytes).
12770
12771	<note>
12772	For media whose <link to="#state"/> is <link
12773	to="MediumState_Inaccessible"/>, the value of this property is the
12774	last known size. For <link to="MediumState_NotCreated"/> media,
12775	the returned value is zero.
12776	</note>
12777	</desc>
12778	</attribute>
12779
12780	<attribute name="format" type="wstring" readonly="yes">
12781	<desc>
12782	Storage format of this medium.
12783
12784	The value of this attribute is a string that specifies a backend used
12785	to store medium data. The storage format is defined when you create a
12786	new medium or automatically detected when you open an existing medium,
12787	and cannot be changed later.
12788
12789	The list of all storage formats supported by this VirtualBox
12790	installation can be obtained using
12791	<link to="ISystemProperties::mediumFormats"/>.
12792	</desc>
12793	</attribute>
12794
12795	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
12796	<desc>
12797	Storage medium format object corresponding to this medium.
12798
12799	The value of this attribute is a reference to the medium format object
12800	that specifies the backend properties used to store medium data. The
12801	storage format is defined when you create a new medium or automatically
12802	detected when you open an existing medium, and cannot be changed later.
12803
12804	<note>@c null is returned if there is no associated medium format
12805	object. This can e.g. happen for medium objects representing host
12806	drives and other special medium objects.</note>
12807	</desc>
12808	</attribute>
12809
12810	<attribute name="type" type="MediumType">
12811	<desc>
12812	Type (role) of this medium.
12813
12814	The following constraints apply when changing the value of this
12815	attribute:
12816	<ul>
12817	<li>If a medium is attached to a virtual machine (either in the
12818	current state or in one of the snapshots), its type cannot be
12819	changed.
12820	</li>
12821	<li>As long as the medium has children, its type cannot be set
12822	to <link to="MediumType_Writethrough"/>.
12823	</li>
12824	<li>The type of all differencing media is
12825	<link to="MediumType_Normal"/> and cannot be changed.
12826	</li>
12827	</ul>
12828
12829	The type of a newly created or opened medium is set to
12830	<link to="MediumType_Normal"/>, except for DVD and floppy media,
12831	which have a type of <link to="MediumType_Writethrough"/>.
12832	</desc>
12833	</attribute>
12834
12835	<attribute name="allowedTypes" type="MediumType" safearray="yes" readonly="yes">
12836	<desc>
12837	Returns which medium types can selected for this medium.
12838
12839	<result name="E_NOTIMPL">
12840	This attribute is not implemented at the moment.
12841	</result>
12842	</desc>
12843	</attribute>
12844
12845	<attribute name="parent" type="IMedium" readonly="yes">
12846	<desc>
12847	Parent of this medium (the medium this medium is directly based
12848	on).
12849
12850	Only differencing media have parents. For base (non-differencing)
12851	media, @c null is returned.
12852	</desc>
12853	</attribute>
12854
12855	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
12856	<desc>
12857	Children of this medium (all differencing media directly based
12858	on this medium). A @c null array is returned if this medium
12859	does not have any children.
12860	</desc>
12861	</attribute>
12862
12863	<attribute name="base" type="IMedium" readonly="yes">
12864	<desc>
12865	Base medium of this medium.
12866
12867	If this is a differencing medium, its base medium is the medium
12868	the given medium branch starts from. For all other types of media, this
12869	property returns the medium object itself (i.e. the same object this
12870	property is read on).
12871	</desc>
12872	</attribute>
12873
12874	<attribute name="readOnly" type="boolean" readonly="yes">
12875	<desc>
12876	Returns @c true if this medium is read-only and @c false otherwise.
12877
12878	A medium is considered to be read-only when its contents cannot be
12879	modified without breaking the integrity of other parties that depend on
12880	this medium such as its child media or snapshots of virtual machines
12881	where this medium is attached to these machines. If there are no
12882	children and no such snapshots then there is no dependency and the
12883	medium is not read-only.
12884
12885	The value of this attribute can be used to determine the kind of the
12886	attachment that will take place when attaching this medium to a
12887	virtual machine. If the value is @c false then the medium will
12888	be attached directly. If the value is @c true then the medium
12889	will be attached indirectly by creating a new differencing child
12890	medium for that. See the interface description for more information.
12891
12892	Note that all <link to="MediumType_Immutable">Immutable</link> media
12893	are always read-only while all
12894	<link to="MediumType_Writethrough">Writethrough</link> media are
12895	always not.
12896
12897	<note>
12898	The read-only condition represented by this attribute is related to
12899	the medium type and usage, not to the current
12900	<link to="IMedium::state">medium state</link> and not to the read-only
12901	state of the storage unit.
12902	</note>
12903	</desc>
12904	</attribute>
12905
12906	<attribute name="logicalSize" type="long long" readonly="yes">
12907	<desc>
12908	Logical size of this medium (in bytes), as reported to the
12909	guest OS running inside the virtual machine this medium is
12910	attached to. The logical size is defined when the medium is created
12911	and cannot be changed later.
12912
12913	<note>
12914	For media whose state is <link to="#state"/> is <link
12915	to="MediumState_Inaccessible"/>, the value of this property is the
12916	last known logical size. For <link to="MediumState_NotCreated"/>
12917	media, the returned value is zero.
12918	</note>
12919	</desc>
12920	</attribute>
12921
12922	<attribute name="autoReset" type="boolean">
12923	<desc>
12924	Whether this differencing medium will be automatically reset each
12925	time a virtual machine it is attached to is powered up. This
12926	attribute is automatically set to @c true for the last
12927	differencing image of an "immutable" medium (see
12928	<link to="MediumType" />).
12929
12930	See <link to="#reset"/> for more information about resetting
12931	differencing media.
12932
12933	<note>
12934	Reading this property on a base (non-differencing) medium will
12935	always @c false. Changing the value of this property in this
12936	case is not supported.
12937	</note>
12938
12939	<result name="VBOX_E_NOT_SUPPORTED">
12940	This is not a differencing medium (when changing the attribute
12941	value).
12942	</result>
12943	</desc>
12944	</attribute>
12945
12946	<attribute name="lastAccessError" type="wstring" readonly="yes">
12947	<desc>
12948	Text message that represents the result of the last accessibility
12949	check performed by <link to="#refreshState"/>.
12950
12951	An empty string is returned if the last accessibility check
12952	was successful or has not yet been called. As a result, if
12953	<link to="#state" /> is "Inaccessible" and this attribute is empty,
12954	then <link to="#refreshState"/> has yet to be called; this is the
12955	default value of media after VirtualBox initialization.
12956	A non-empty string indicates a failure and should normally describe
12957	a reason of the failure (for example, a file read error).
12958	</desc>
12959	</attribute>
12960
12961	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
12962	<desc>
12963	Array of UUIDs of all machines this medium is attached to.
12964
12965	A @c null array is returned if this medium is not attached to any
12966	machine or to any machine's snapshot.
12967
12968	<note>
12969	The returned array will include a machine even if this medium is not
12970	attached to that machine in the current state but attached to it in
12971	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
12972	details.
12973	</note>
12974	</desc>
12975	</attribute>
12976
12977	<method name="setIds">
12978	<desc>
12979	Changes the UUID and parent UUID for a hard disk medium.
12980	</desc>
12981	<param name="setImageId" type="boolean" dir="in">
12982	<desc>
12983	Select whether a new image UUID is set or not.
12984	</desc>
12985	</param>
12986	<param name="imageId" type="uuid" mod="string" dir="in">
12987	<desc>
12988	New UUID for the image. If an empty string is passed, then a new
12989	UUID is automatically created, provided that @a setImageId is @c true.
12990	Specifying a zero UUID is not allowed.
12991	</desc>
12992	</param>
12993	<param name="setParentId" type="boolean" dir="in">
12994	<desc>
12995	Select whether a new parent UUID is set or not.
12996	</desc>
12997	</param>
12998	<param name="parentId" type="uuid" mod="string" dir="in">
12999	<desc>
13000	New parent UUID for the image. If an empty string is passed, then a
13001	new UUID is automatically created, provided @a setParentId is
13002	@c true. A zero UUID is valid.
13003	</desc>
13004	</param>
13005	<result name="E_INVALIDARG">
13006	Invalid parameter combination.
13007	</result>
13008	<result name="VBOX_E_NOT_SUPPORTED">
13009	Medium is not a hard disk medium.
13010	</result>
13011	</method>
13012
13013	<method name="refreshState">
13014	<desc>
13015	If the current medium state (see <link to="MediumState"/>) is one of
13016	"Created", "Inaccessible" or "LockedRead", then this performs an
13017	accessibility check on the medium and sets the value of the <link to="#state"/>
13018	attribute accordingly; that value is also returned for convenience.
13019
13020	For all other state values, this does not perform a refresh but returns
13021	the state only.
13022
13023	The refresh, if performed, may take a long time (several seconds or even
13024	minutes, depending on the storage unit location and format) because it performs an
13025	accessibility check of the storage unit. This check may cause a significant
13026	delay if the storage unit of the given medium is, for example, a file located
13027	on a network share which is not currently accessible due to connectivity
13028	problems. In that case, the call will not return until a timeout
13029	interval defined by the host OS for this operation expires. For this reason,
13030	it is recommended to never read this attribute on the main UI thread to avoid
13031	making the UI unresponsive.
13032
13033	If the last known state of the medium is "Created" and the accessibility
13034	check fails, then the state would be set to "Inaccessible", and
13035	<link to="#lastAccessError"/> may be used to get more details about the
13036	failure. If the state of the medium is "LockedRead", then it remains the
13037	same, and a non-empty value of <link to="#lastAccessError"/> will
13038	indicate a failed accessibility check in this case.
13039
13040	Note that not all medium states are applicable to all medium types.
13041	</desc>
13042	<param name="state" type="MediumState" dir="return">
13043	<desc>
13044	New medium state.
13045	</desc>
13046	</param>
13047	</method>
13048
13049	<method name="getSnapshotIds">
13050	<desc>
13051	Returns an array of UUIDs of all snapshots of the given machine where
13052	this medium is attached to.
13053
13054	If the medium is attached to the machine in the current state, then the
13055	first element in the array will always be the ID of the queried machine
13056	(i.e. the value equal to the @c machineId argument), followed by
13057	snapshot IDs (if any).
13058
13059	If the medium is not attached to the machine in the current state, then
13060	the array will contain only snapshot IDs.
13061
13062	The returned array may be @c null if this medium is not attached
13063	to the given machine at all, neither in the current state nor in one of
13064	the snapshots.
13065	</desc>
13066	<param name="machineId" type="uuid" mod="string" dir="in">
13067	<desc>
13068	UUID of the machine to query.
13069	</desc>
13070	</param>
13071	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
13072	<desc>
13073	Array of snapshot UUIDs of the given machine using this medium.
13074	</desc>
13075	</param>
13076	</method>
13077
13078	<method name="lockRead">
13079	<desc>
13080	Locks this medium for reading.
13081
13082	A read lock is shared: many clients can simultaneously lock the
13083	same medium for reading unless it is already locked for writing (see
13084	<link to="#lockWrite"/>) in which case an error is returned.
13085
13086	When the medium is locked for reading, it cannot be modified
13087	from within VirtualBox. This means that any method that changes
13088	the properties of this medium or contents of the storage unit
13089	will return an error (unless explicitly stated otherwise). That
13090	includes an attempt to start a virtual machine that wants to
13091	write to the the medium.
13092
13093	When the virtual machine is started up, it locks for reading all
13094	media it uses in read-only mode. If some medium cannot be locked
13095	for reading, the startup procedure will fail.
13096	A medium is typically locked for reading while it is used by a running
13097	virtual machine but has a depending differencing image that receives
13098	the actual write operations. This way one base medium can have
13099	multiple child differencing images which can be written to
13100	simultaneously. Read-only media such as DVD and floppy images are
13101	also locked for reading only (so they can be in use by multiple
13102	machines simultaneously).
13103
13104	A medium is also locked for reading when it is the source of a
13105	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13106
13107	The medium locked for reading must be unlocked using the <link
13108	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
13109	can be nested and must be followed by the same number of paired
13110	<link to="#unlockRead"/> calls.
13111
13112	This method sets the medium state (see <link to="#state"/>) to
13113	"LockedRead" on success. The medium's previous state must be
13114	one of "Created", "Inaccessible" or "LockedRead".
13115
13116	Locking an inaccessible medium is not an error; this method performs
13117	a logical lock that prevents modifications of this medium through
13118	the VirtualBox API, not a physical file-system lock of the underlying
13119	storage unit.
13120
13121	This method returns the current state of the medium
13122	<i>before</i> the operation.
13123
13124	<result name="VBOX_E_INVALID_OBJECT_STATE">
13125	Invalid medium state (e.g. not created, locked, inaccessible,
13126	creating, deleting).
13127	</result>
13128
13129	</desc>
13130	<param name="state" type="MediumState" dir="return">
13131	<desc>
13132	State of the medium after the operation.
13133	</desc>
13134	</param>
13135	</method>
13136
13137	<method name="unlockRead">
13138	<desc>
13139	Cancels the read lock previously set by <link to="#lockRead"/>.
13140
13141	For both success and failure, this method returns the current state
13142	of the medium <i>after</i> the operation.
13143
13144	See <link to="#lockRead"/> for more details.
13145
13146	<result name="VBOX_E_INVALID_OBJECT_STATE">
13147	Medium not locked for reading.
13148	</result>
13149
13150	</desc>
13151	<param name="state" type="MediumState" dir="return">
13152	<desc>
13153	State of the medium after the operation.
13154	</desc>
13155	</param>
13156	</method>
13157
13158	<method name="lockWrite">
13159	<desc>
13160	Locks this medium for writing.
13161
13162	A write lock, as opposed to <link to="#lockRead"/>, is
13163	exclusive: there may be only one client holding a write lock,
13164	and there may be no read locks while the write lock is held.
13165	As a result, read-locking fails if a write lock is held, and
13166	write-locking fails if either a read or another write lock is held.
13167
13168	When a medium is locked for writing, it cannot be modified
13169	from within VirtualBox, and it is not guaranteed that the values
13170	of its properties are up-to-date. Any method that changes the
13171	properties of this medium or contents of the storage unit will
13172	return an error (unless explicitly stated otherwise).
13173
13174	When a virtual machine is started up, it locks for writing all
13175	media it uses to write data to. If any medium could not be locked
13176	for writing, the startup procedure will fail. If a medium has
13177	differencing images, then while the machine is running, only
13178	the last ("leaf") differencing image is locked for writing,
13179	whereas its parents are locked for reading only.
13180
13181	A medium is also locked for writing when it is the target of a
13182	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
13183
13184	The medium locked for writing must be unlocked using the <link
13185	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
13186
13187	This method sets the medium state (see <link to="#state"/>) to
13188	"LockedWrite" on success. The medium's previous state must be
13189	either "Created" or "Inaccessible".
13190
13191	Locking an inaccessible medium is not an error; this method performs
13192	a logical lock that prevents modifications of this medium through
13193	the VirtualBox API, not a physical file-system lock of the underlying
13194	storage unit.
13195
13196	For both, success and failure, this method returns the current
13197	state of the medium <i>before</i> the operation.
13198
13199	<result name="VBOX_E_INVALID_OBJECT_STATE">
13200	Invalid medium state (e.g. not created, locked, inaccessible,
13201	creating, deleting).
13202	</result>
13203
13204	</desc>
13205	<param name="state" type="MediumState" dir="return">
13206	<desc>
13207	State of the medium after the operation.
13208	</desc>
13209	</param>
13210	</method>
13211
13212	<method name="unlockWrite">
13213	<desc>
13214	Cancels the write lock previously set by <link to="#lockWrite"/>.
13215
13216	For both success and failure, this method returns the current
13217	state of the medium <i>after</i> the operation.
13218
13219	See <link to="#lockWrite"/> for more details.
13220
13221	<result name="VBOX_E_INVALID_OBJECT_STATE">
13222	Medium not locked for writing.
13223	</result>
13224
13225	</desc>
13226	<param name="state" type="MediumState" dir="return">
13227	<desc>
13228	State of the medium after the operation.
13229	</desc>
13230	</param>
13231	</method>
13232
13233	<method name="close">
13234	<desc>
13235	Closes this medium.
13236
13237	The medium must not be attached to any known virtual machine
13238	and must not have any known child media, otherwise the
13239	operation will fail.
13240
13241	When the medium is successfully closed, it is removed from
13242	the list of registered media, but its storage unit is not
13243	deleted. In particular, this means that this medium can
13244	later be opened again using the <link to="IVirtualBox::openMedium"/>
13245	call.
13246
13247	Note that after this method successfully returns, the given medium
13248	object becomes uninitialized. This means that any attempt
13249	to call any of its methods or attributes will fail with the
13250	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
13251
13252	<result name="VBOX_E_INVALID_OBJECT_STATE">
13253	Invalid medium state (other than not created, created or
13254	inaccessible).
13255	</result>
13256	<result name="VBOX_E_OBJECT_IN_USE">
13257	Medium attached to virtual machine.
13258	</result>
13259	<result name="VBOX_E_FILE_ERROR">
13260	Settings file not accessible.
13261	</result>
13262	<result name="VBOX_E_XML_ERROR">
13263	Could not parse the settings file.
13264	</result>
13265
13266	</desc>
13267	</method>
13268
13269	<!-- property methods -->
13270
13271	<method name="getProperty" const="yes">
13272	<desc>
13273	Returns the value of the custom medium property with the given name.
13274
13275	The list of all properties supported by the given medium format can
13276	be obtained with <link to="IMediumFormat::describeProperties"/>.
13277
13278	<note>If this method returns an empty string in @a value, the requested
13279	property is supported but currently not assigned any value.</note>
13280
13281	<result name="VBOX_E_OBJECT_NOT_FOUND">
13282	Requested property does not exist (not supported by the format).
13283	</result>
13284	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13285	</desc>
13286	<param name="name" type="wstring" dir="in">
13287	<desc>Name of the property to get.</desc>
13288	</param>
13289	<param name="value" type="wstring" dir="return">
13290	<desc>Current property value.</desc>
13291	</param>
13292	</method>
13293
13294	<method name="setProperty">
13295	<desc>
13296	Sets the value of the custom medium property with the given name.
13297
13298	The list of all properties supported by the given medium format can
13299	be obtained with <link to="IMediumFormat::describeProperties"/>.
13300
13301	<note>Setting the property value to @c null or an empty string is
13302	equivalent to deleting the existing value. A default value (if it is
13303	defined for this property) will be used by the format backend in this
13304	case.</note>
13305
13306	<result name="VBOX_E_OBJECT_NOT_FOUND">
13307	Requested property does not exist (not supported by the format).
13308	</result>
13309	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
13310	</desc>
13311	<param name="name" type="wstring" dir="in">
13312	<desc>Name of the property to set.</desc>
13313	</param>
13314	<param name="value" type="wstring" dir="in">
13315	<desc>Property value to set.</desc>
13316	</param>
13317	</method>
13318
13319	<method name="getProperties" const="yes">
13320	<desc>
13321	Returns values for a group of properties in one call.
13322
13323	The names of the properties to get are specified using the @a names
13324	argument which is a list of comma-separated property names or
13325	an empty string if all properties are to be returned.
13326	<note>Currently the value of this argument is ignored and the method
13327	always returns all existing properties.</note>
13328
13329	The list of all properties supported by the given medium format can
13330	be obtained with <link to="IMediumFormat::describeProperties"/>.
13331
13332	The method returns two arrays, the array of property names corresponding
13333	to the @a names argument and the current values of these properties.
13334	Both arrays have the same number of elements with each element at the
13335	given index in the first array corresponds to an element at the same
13336	index in the second array.
13337
13338	For properties that do not have assigned values, an empty string is
13339	returned at the appropriate index in the @a returnValues array.
13340
13341	</desc>
13342	<param name="names" type="wstring" dir="in">
13343	<desc>
13344	Names of properties to get.
13345	</desc>
13346	</param>
13347	<param name="returnNames" type="wstring" safearray="yes" dir="out">
13348	<desc>Names of returned properties.</desc>
13349	</param>
13350	<param name="returnValues" type="wstring" safearray="yes" dir="return">
13351	<desc>Values of returned properties.</desc>
13352	</param>
13353	</method>
13354
13355	<method name="setProperties">
13356	<desc>
13357	Sets values for a group of properties in one call.
13358
13359	The names of the properties to set are passed in the @a names
13360	array along with the new values for them in the @a values array. Both
13361	arrays have the same number of elements with each element at the given
13362	index in the first array corresponding to an element at the same index
13363	in the second array.
13364
13365	If there is at least one property name in @a names that is not valid,
13366	the method will fail before changing the values of any other properties
13367	from the @a names array.
13368
13369	Using this method over <link to="#setProperty"/> is preferred if you
13370	need to set several properties at once since it is more efficient.
13371
13372	The list of all properties supported by the given medium format can
13373	be obtained with <link to="IMediumFormat::describeProperties"/>.
13374
13375	Setting the property value to @c null or an empty string is equivalent
13376	to deleting the existing value. A default value (if it is defined for
13377	this property) will be used by the format backend in this case.
13378	</desc>
13379	<param name="names" type="wstring" safearray="yes" dir="in">
13380	<desc>Names of properties to set.</desc>
13381	</param>
13382	<param name="values" type="wstring" safearray="yes" dir="in">
13383	<desc>Values of properties to set.</desc>
13384	</param>
13385	</method>
13386
13387	<!-- storage methods -->
13388
13389	<method name="createBaseStorage">
13390	<desc>
13391	Starts creating a hard disk storage unit (fixed/dynamic, according
13392	to the variant flags) in in the background. The previous storage unit
13393	created for this object, if any, must first be deleted using
13394	<link to="#deleteStorage"/>, otherwise the operation will fail.
13395
13396	Before the operation starts, the medium is placed in
13397	<link to="MediumState_Creating"/> state. If the create operation
13398	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
13399	state.
13400
13401	After the returned progress object reports that the operation has
13402	successfully completed, the medium state will be set to <link
13403	to="MediumState_Created"/>, the medium will be remembered by this
13404	VirtualBox installation and may be attached to virtual machines.
13405
13406	<result name="VBOX_E_NOT_SUPPORTED">
13407	The variant of storage creation operation is not supported. See <link
13408	to="IMediumFormat::capabilities"/>.
13409	</result>
13410	</desc>
13411	<param name="logicalSize" type="long long" dir="in">
13412	<desc>Maximum logical size of the medium in bytes.</desc>
13413	</param>
13414	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13415	<desc>Exact image variant which should be created (as a combination of
13416	<link to="MediumVariant" /> flags).</desc>
13417	</param>
13418	<param name="progress" type="IProgress" dir="return">
13419	<desc>Progress object to track the operation completion.</desc>
13420	</param>
13421	</method>
13422
13423	<method name="deleteStorage">
13424	<desc>
13425	Starts deleting the storage unit of this medium.
13426
13427	The medium must not be attached to any known virtual machine and must
13428	not have any known child media, otherwise the operation will fail.
13429	It will also fail if there is no storage unit to delete or if deletion
13430	is already in progress, or if the medium is being in use (locked for
13431	read or for write) or inaccessible. Therefore, the only valid state for
13432	this operation to succeed is <link to="MediumState_Created"/>.
13433
13434	Before the operation starts, the medium is placed in
13435	<link to="MediumState_Deleting"/> state and gets removed from the list
13436	of remembered hard disks (media registry). If the delete operation
13437	fails, the medium will be remembered again and placed back to
13438	<link to="MediumState_Created"/> state.
13439
13440	After the returned progress object reports that the operation is
13441	complete, the medium state will be set to
13442	<link to="MediumState_NotCreated"/> and you will be able to use one of
13443	the storage creation methods to create it again.
13444
13445	<see><link to="#close"/></see>
13446
13447	<result name="VBOX_E_OBJECT_IN_USE">
13448	Medium is attached to a virtual machine.
13449	</result>
13450	<result name="VBOX_E_NOT_SUPPORTED">
13451	Storage deletion is not allowed because neither of storage creation
13452	operations are supported. See
13453	<link to="IMediumFormat::capabilities"/>.
13454	</result>
13455
13456	<note>
13457	If the deletion operation fails, it is not guaranteed that the storage
13458	unit still exists. You may check the <link to="IMedium::state"/> value
13459	to answer this question.
13460	</note>
13461	</desc>
13462	<param name="progress" type="IProgress" dir="return">
13463	<desc>Progress object to track the operation completion.</desc>
13464	</param>
13465	</method>
13466
13467	<!-- diff methods -->
13468
13469	<method name="createDiffStorage">
13470	<desc>
13471	Starts creating an empty differencing storage unit based on this
13472	medium in the format and at the location defined by the @a target
13473	argument.
13474
13475	The target medium must be in <link to="MediumState_NotCreated"/>
13476	state (i.e. must not have an existing storage unit). Upon successful
13477	completion, this operation will set the type of the target medium to
13478	<link to="MediumType_Normal"/> and create a storage unit necessary to
13479	represent the differencing medium data in the given format (according
13480	to the storage format of the target object).
13481
13482	After the returned progress object reports that the operation is
13483	successfully complete, the target medium gets remembered by this
13484	VirtualBox installation and may be attached to virtual machines.
13485
13486	<note>
13487	The medium will be set to <link to="MediumState_LockedRead"/>
13488	state for the duration of this operation.
13489	</note>
13490	<result name="VBOX_E_OBJECT_IN_USE">
13491	Medium not in @c NotCreated state.
13492	</result>
13493	</desc>
13494	<param name="target" type="IMedium" dir="in">
13495	<desc>Target medium.</desc>
13496	</param>
13497	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13498	<desc>Exact image variant which should be created (as a combination of
13499	<link to="MediumVariant" /> flags).</desc>
13500	</param>
13501	<param name="progress" type="IProgress" dir="return">
13502	<desc>Progress object to track the operation completion.</desc>
13503	</param>
13504	</method>
13505
13506	<method name="mergeTo">
13507	<desc>
13508	Starts merging the contents of this medium and all intermediate
13509	differencing media in the chain to the given target medium.
13510
13511	The target medium must be either a descendant of this medium or
13512	its ancestor (otherwise this method will immediately return a failure).
13513	It follows that there are two logical directions of the merge operation:
13514	from ancestor to descendant (<i>forward merge</i>) and from descendant to
13515	ancestor (<i>backward merge</i>). Let us consider the following medium
13516	chain:
13517
13518	<pre>Base <- Diff_1 <- Diff_2</pre>
13519
13520	Here, calling this method on the <tt>Base</tt> medium object with
13521	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
13522	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
13523	merge. Note that in both cases the contents of the resulting medium
13524	will be the same, the only difference is the medium object that takes
13525	the result of the merge operation. In case of the forward merge in the
13526	above example, the result will be written to <tt>Diff_2</tt>; in case of
13527	the backward merge, the result will be written to <tt>Base</tt>. In
13528	other words, the result of the operation is always stored in the target
13529	medium.
13530
13531	Upon successful operation completion, the storage units of all media in
13532	the chain between this (source) medium and the target medium, including
13533	the source medium itself, will be automatically deleted and the
13534	relevant medium objects (including this medium) will become
13535	uninitialized. This means that any attempt to call any of
13536	their methods or attributes will fail with the
13537	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
13538	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
13539	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
13540	Note that <tt>Diff_2</tt> in this case will become a base medium
13541	itself since it will no longer be based on any other medium.
13542
13543	Considering the above, all of the following conditions must be met in
13544	order for the merge operation to succeed:
13545	<ul>
13546	<li>
13547	Neither this (source) medium nor any intermediate
13548	differencing medium in the chain between it and the target
13549	medium is attached to any virtual machine.
13550	</li>
13551	<li>
13552	Neither the source medium nor the target medium is an
13553	<link to="MediumType_Immutable"/> medium.
13554	</li>
13555	<li>
13556	The part of the medium tree from the source medium to the
13557	target medium is a linear chain, i.e. all medium in this
13558	chain have exactly one child which is the next medium in this
13559	chain. The only exception from this rule is the target medium in
13560	the forward merge operation; it is allowed to have any number of
13561	child media because the merge operation will not change its
13562	logical contents (as it is seen by the guest OS or by children).
13563	</li>
13564	<li>
13565	None of the involved media are in
13566	<link to="MediumState_LockedRead"/> or
13567	<link to="MediumState_LockedWrite"/> state.
13568	</li>
13569	</ul>
13570
13571	<note>
13572	This (source) medium and all intermediates will be placed to <link
13573	to="MediumState_Deleting"/> state and the target medium will be
13574	placed to <link to="MediumState_LockedWrite"/> state and for the
13575	duration of this operation.
13576	</note>
13577	</desc>
13578	<param name="target" type="IMedium" dir="in">
13579	<desc>Target medium.</desc>
13580	</param>
13581	<param name="progress" type="IProgress" dir="return">
13582	<desc>Progress object to track the operation completion.</desc>
13583	</param>
13584	</method>
13585
13586	<!-- clone method -->
13587
13588	<method name="cloneTo">
13589	<desc>
13590	Starts creating a clone of this medium in the format and at the
13591	location defined by the @a target argument.
13592
13593	The target medium must be either in <link to="MediumState_NotCreated"/>
13594	state (i.e. must not have an existing storage unit) or in
13595	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13596	big enough to hold the data or else the copy will be partial). Upon
13597	successful completion, the cloned medium will contain exactly the
13598	same sector data as the medium being cloned, except that in the
13599	first case a new UUID for the clone will be randomly generated, and in
13600	the second case the UUID will remain unchanged.
13601
13602	The @a parent argument defines which medium will be the parent
13603	of the clone. Passing a @c null reference indicates that the clone will
13604	be a base image, i.e. completely independent. It is possible to specify
13605	an arbitrary medium for this parameter, including the parent of the
13606	medium which is being cloned. Even cloning to a child of the source
13607	medium is possible. Note that when cloning to an existing image, the
13608	@a parent argument is ignored.
13609
13610	After the returned progress object reports that the operation is
13611	successfully complete, the target medium gets remembered by this
13612	VirtualBox installation and may be attached to virtual machines.
13613
13614	<note>
13615	This medium will be placed to <link to="MediumState_LockedRead"/>
13616	state for the duration of this operation.
13617	</note>
13618	<result name="E_NOTIMPL">
13619	The specified cloning variant is not supported at the moment.
13620	</result>
13621	</desc>
13622	<param name="target" type="IMedium" dir="in">
13623	<desc>Target medium.</desc>
13624	</param>
13625	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13626	<desc>Exact image variant which should be created (as a combination of
13627	<link to="MediumVariant" /> flags).</desc>
13628	</param>
13629	<param name="parent" type="IMedium" dir="in">
13630	<desc>Parent of the cloned medium.</desc>
13631	</param>
13632	<param name="progress" type="IProgress" dir="return">
13633	<desc>Progress object to track the operation completion.</desc>
13634	</param>
13635	</method>
13636
13637	<method name="cloneToBase">
13638	<desc>
13639	Starts creating a clone of this medium in the format and at the
13640	location defined by the @a target argument.
13641
13642	The target medium must be either in <link to="MediumState_NotCreated"/>
13643	state (i.e. must not have an existing storage unit) or in
13644	<link to="MediumState_Created"/> state (i.e. created and not locked, and
13645	big enough to hold the data or else the copy will be partial). Upon
13646	successful completion, the cloned medium will contain exactly the
13647	same sector data as the medium being cloned, except that in the
13648	first case a new UUID for the clone will be randomly generated, and in
13649	the second case the UUID will remain unchanged.
13650
13651	The @a parent argument defines which medium will be the parent
13652	of the clone. In this case the clone will be a base image, i.e.
13653	completely independent. It is possible to specify an arbitrary
13654	medium for this parameter, including the parent of the
13655	medium which is being cloned. Even cloning to a child of the source
13656	medium is possible. Note that when cloning to an existing image, the
13657	@a parent argument is ignored.
13658
13659	After the returned progress object reports that the operation is
13660	successfully complete, the target medium gets remembered by this
13661	VirtualBox installation and may be attached to virtual machines.
13662
13663	<note>
13664	This medium will be placed to <link to="MediumState_LockedRead"/>
13665	state for the duration of this operation.
13666	</note>
13667	<result name="E_NOTIMPL">
13668	The specified cloning variant is not supported at the moment.
13669	</result>
13670	</desc>
13671	<param name="target" type="IMedium" dir="in">
13672	<desc>Target medium.</desc>
13673	</param>
13674	<param name="variant" type="MediumVariant" safearray="yes" dir="in">
13675	<desc><link to="MediumVariant" /> flags).</desc>
13676	</param>
13677	<param name="progress" type="IProgress" dir="return">
13678	<desc>Progress object to track the operation completion.</desc>
13679	</param>
13680	</method>
13681
13682	<!-- other methods -->
13683
13684	<method name="compact">
13685	<desc>
13686	Starts compacting of this medium. This means that the medium is
13687	transformed into a possibly more compact storage representation.
13688	This potentially creates temporary images, which can require a
13689	substantial amount of additional disk space.
13690
13691	This medium will be placed to <link to="MediumState_LockedWrite"/>
13692	state and all its parent media (if any) will be placed to
13693	<link to="MediumState_LockedRead"/> state for the duration of this
13694	operation.
13695
13696	Please note that the results can be either returned straight away,
13697	or later as the result of the background operation via the object
13698	returned via the @a progress parameter.
13699
13700	<result name="VBOX_E_NOT_SUPPORTED">
13701	Medium format does not support compacting (but potentially
13702	needs it).
13703	</result>
13704	</desc>
13705	<param name="progress" type="IProgress" dir="return">
13706	<desc>Progress object to track the operation completion.</desc>
13707	</param>
13708	</method>
13709
13710	<method name="resize">
13711	<desc>
13712	Starts resizing this medium. This means that the nominal size of the
13713	medium is set to the new value. Both increasing and decreasing the
13714	size is possible, and there are no safety checks, since VirtualBox
13715	does not make any assumptions about the medium contents.
13716
13717	Resizing usually needs additional disk space, and possibly also
13718	some temporary disk space. Note that resize does not create a full
13719	temporary copy of the medium, so the additional disk space requirement
13720	is usually much lower than using the clone operation.
13721
13722	This medium will be placed to <link to="MediumState_LockedWrite"/>
13723	state for the duration of this operation.
13724
13725	Please note that the results can be either returned straight away,
13726	or later as the result of the background operation via the object
13727	returned via the @a progress parameter.
13728
13729	<result name="VBOX_E_NOT_SUPPORTED">
13730	Medium format does not support resizing.
13731	</result>
13732	</desc>
13733	<param name="logicalSize" type="long long" dir="in">
13734	<desc>New nominal capacity of the medium in bytes.</desc>
13735	</param>
13736	<param name="progress" type="IProgress" dir="return">
13737	<desc>Progress object to track the operation completion.</desc>
13738	</param>
13739	</method>
13740
13741	<method name="reset">
13742	<desc>
13743	Starts erasing the contents of this differencing medium.
13744
13745	This operation will reset the differencing medium to its initial
13746	state when it does not contain any sector data and any read operation is
13747	redirected to its parent medium. This automatically gets called
13748	during VM power-up for every medium whose <link to="#autoReset" />
13749	attribute is @c true.
13750
13751	The medium will be write-locked for the duration of this operation (see
13752	<link to="#lockWrite" />).
13753
13754	<result name="VBOX_E_NOT_SUPPORTED">
13755	This is not a differencing medium.
13756	</result>
13757	<result name="VBOX_E_INVALID_OBJECT_STATE">
13758	Medium is not in <link to="MediumState_Created"/> or
13759	<link to="MediumState_Inaccessible"/> state.
13760	</result>
13761	</desc>
13762	<param name="progress" type="IProgress" dir="return">
13763	<desc>Progress object to track the operation completion.</desc>
13764	</param>
13765	</method>
13766
13767	</interface>
13768
13769
13770	<!--
13771	// IMediumFormat
13772	/////////////////////////////////////////////////////////////////////////
13773	-->
13774
13775	<enum
13776	name="DataType"
13777	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
13778	>
13779	<const name="Int32" value="0"/>
13780	<const name="Int8" value="1"/>
13781	<const name="String" value="2"/>
13782	</enum>
13783
13784	<enum
13785	name="DataFlags"
13786	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
13787	>
13788	<const name="None" value="0x00"/>
13789	<const name="Mandatory" value="0x01"/>
13790	<const name="Expert" value="0x02"/>
13791	<const name="Array" value="0x04"/>
13792	<const name="FlagMask" value="0x07"/>
13793	</enum>
13794
13795	<enum
13796	name="MediumFormatCapabilities"
13797	uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
13798	>
13799	<desc>
13800	Medium format capability flags.
13801	</desc>
13802
13803	<const name="Uuid" value="0x01">
13804	<desc>
13805	Supports UUIDs as expected by VirtualBox code.
13806	</desc>
13807	</const>
13808
13809	<const name="CreateFixed" value="0x02">
13810	<desc>
13811	Supports creating fixed size images, allocating all space instantly.
13812	</desc>
13813	</const>
13814
13815	<const name="CreateDynamic" value="0x04">
13816	<desc>
13817	Supports creating dynamically growing images, allocating space on
13818	demand.
13819	</desc>
13820	</const>
13821
13822	<const name="CreateSplit2G" value="0x08">
13823	<desc>
13824	Supports creating images split in chunks of a bit less than 2 GBytes.
13825	</desc>
13826	</const>
13827
13828	<const name="Differencing" value="0x10">
13829	<desc>
13830	Supports being used as a format for differencing media (see <link
13831	to="IMedium::createDiffStorage"/>).
13832	</desc>
13833	</const>
13834
13835	<const name="Asynchronous" value="0x20">
13836	<desc>
13837	Supports asynchronous I/O operations for at least some configurations.
13838	</desc>
13839	</const>
13840
13841	<const name="File" value="0x40">
13842	<desc>
13843	The format backend operates on files (the <link to="IMedium::location"/>
13844	attribute of the medium specifies a file used to store medium
13845	data; for a list of supported file extensions see
13846	<link to="IMediumFormat::describeFileExtensions"/>).
13847	</desc>
13848	</const>
13849
13850	<const name="Properties" value="0x80">
13851	<desc>
13852	The format backend uses the property interface to configure the storage
13853	location and properties (the <link to="IMediumFormat::describeProperties"/>
13854	method is used to get access to properties supported by the given medium format).
13855	</desc>
13856	</const>
13857
13858	<const name="TcpNetworking" value="0x100">
13859	<desc>
13860	The format backend uses the TCP networking interface for network access.
13861	</desc>
13862	</const>
13863
13864	<const name="VFS" value="0x200">
13865	<desc>
13866	The format backend supports virtual filesystem functionality.
13867	</desc>
13868	</const>
13869
13870	<const name="CapabilityMask" value="0x3FF"/>
13871	</enum>
13872
13873	<interface
13874	name="IMediumFormat" extends="$unknown"
13875	uuid="6238e1cf-a17d-4ec1-8172-418bfb22b93a"
13876	wsmap="managed"
13877	>
13878	<desc>
13879	The IMediumFormat interface represents a medium format.
13880
13881	Each medium format has an associated backend which is used to handle
13882	media stored in this format. This interface provides information
13883	about the properties of the associated backend.
13884
13885	Each medium format is identified by a string represented by the
13886	<link to="#id"/> attribute. This string is used in calls like
13887	<link to="IVirtualBox::createHardDisk"/> to specify the desired
13888	format.
13889
13890	The list of all supported medium formats can be obtained using
13891	<link to="ISystemProperties::mediumFormats"/>.
13892
13893	<see><link to="IMedium"/></see>
13894	</desc>
13895
13896	<attribute name="id" type="wstring" readonly="yes">
13897	<desc>
13898	Identifier of this format.
13899
13900	The format identifier is a non-@c null non-empty ASCII string. Note that
13901	this string is case-insensitive. This means that, for example, all of
13902	the following strings:
13903	<pre>
13904	"VDI"
13905	"vdi"
13906	"VdI"</pre>
13907	refer to the same medium format.
13908
13909	This string is used in methods of other interfaces where it is necessary
13910	to specify a medium format, such as
13911	<link to="IVirtualBox::createHardDisk"/>.
13912	</desc>
13913	</attribute>
13914
13915	<attribute name="name" type="wstring" readonly="yes">
13916	<desc>
13917	Human readable description of this format.
13918
13919	Mainly for use in file open dialogs.
13920	</desc>
13921	</attribute>
13922
13923	<attribute name="capabilities" type="MediumFormatCapabilities" safearray="yes" readonly="yes">
13924	<desc>
13925	Capabilities of the format as an array of the flags.
13926
13927	For the meaning of individual capability flags see
13928	<link to="MediumFormatCapabilities"/>.
13929	</desc>
13930	</attribute>
13931
13932	<method name="describeFileExtensions">
13933	<desc>
13934	Returns two arrays describing the supported file extensions.
13935
13936	The first array contains the supported extensions and the seconds one
13937	the type each extension supports. Both have the same size.
13938
13939	Note that some backends do not work on files, so this array may be
13940	empty.
13941
13942	<see><link to="IMediumFormat::capabilities"/></see>
13943	</desc>
13944	<param name="extensions" type="wstring" safearray="yes" dir="out">
13945	<desc>The array of supported extensions.</desc>
13946	</param>
13947	<param name="types" type="DeviceType" safearray="yes" dir="out">
13948	<desc>The array which indicates the device type for every given extension.</desc>
13949	</param>
13950	</method>
13951
13952	<method name="describeProperties" const="yes">
13953	<desc>
13954	Returns several arrays describing the properties supported by this
13955	format.
13956
13957	An element with the given index in each array describes one
13958	property. Thus, the number of elements in each returned array is the
13959	same and corresponds to the number of supported properties.
13960
13961	The returned arrays are filled in only if the
13962	<link to="MediumFormatCapabilities_Properties"/> flag is set.
13963	All arguments must be non-@c null.
13964
13965	<see><link to="DataType"/>, <link to="DataFlags"/></see>
13966	</desc>
13967
13968	<param name="names" type="wstring" safearray="yes" dir="out">
13969	<desc>Array of property names.</desc>
13970	</param>
13971	<param name="descriptions" type="wstring" safearray="yes" dir="out">
13972	<desc>Array of property descriptions.</desc>
13973	</param>
13974	<param name="types" type="DataType" safearray="yes" dir="out">
13975	<desc>Array of property types.</desc>
13976	</param>
13977	<param name="flags" type="unsigned long" safearray="yes" dir="out">
13978	<desc>Array of property flags.</desc>
13979	</param>
13980	<param name="defaults" type="wstring" safearray="yes" dir="out">
13981	<desc>Array of default property values.</desc>
13982	</param>
13983	</method>
13984
13985	</interface>
13986
13987
13988	<!--
13989	// IKeyboard
13990	/////////////////////////////////////////////////////////////////////////
13991	-->
13992
13993	<interface
13994	name="IKeyboard" extends="$unknown"
13995	uuid="f6916ec5-a881-4237-898f-7de58cf88672"
13996	wsmap="managed"
13997	>
13998	<desc>
13999	The IKeyboard interface represents the virtual machine's keyboard. Used
14000	in <link to="IConsole::keyboard"/>.
14001
14002	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
14003	to the virtual machine.
14004
14005	</desc>
14006	<method name="putScancode">
14007	<desc>Sends a scancode to the keyboard.
14008
14009	<result name="VBOX_E_IPRT_ERROR">
14010	Could not send scan code to virtual keyboard.
14011	</result>
14012
14013	</desc>
14014	<param name="scancode" type="long" dir="in"/>
14015	</method>
14016
14017	<method name="putScancodes">
14018	<desc>Sends an array of scancodes to the keyboard.
14019
14020	<result name="VBOX_E_IPRT_ERROR">
14021	Could not send all scan codes to virtual keyboard.
14022	</result>
14023
14024	</desc>
14025	<param name="scancodes" type="long" dir="in" safearray="yes"/>
14026	<param name="codesStored" type="unsigned long" dir="return"/>
14027	</method>
14028
14029	<method name="putCAD">
14030	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
14031	function is nothing special, it is just a convenience function
14032	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
14033
14034	<result name="VBOX_E_IPRT_ERROR">
14035	Could not send all scan codes to virtual keyboard.
14036	</result>
14037
14038	</desc>
14039	</method>
14040
14041	<attribute name="eventSource" type="IEventSource" readonly="yes">
14042	<desc>
14043	Event source for keyboard events.
14044	</desc>
14045	</attribute>
14046
14047	</interface>
14048
14049
14050	<!--
14051	// IMouse
14052	/////////////////////////////////////////////////////////////////////////
14053	-->
14054
14055	<enum
14056	name="MouseButtonState"
14057	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
14058	>
14059	<desc>
14060	Mouse button state.
14061	</desc>
14062
14063	<const name="LeftButton" value="0x01"/>
14064	<const name="RightButton" value="0x02"/>
14065	<const name="MiddleButton" value="0x04"/>
14066	<const name="WheelUp" value="0x08"/>
14067	<const name="WheelDown" value="0x10"/>
14068	<const name="XButton1" value="0x20"/>
14069	<const name="XButton2" value="0x40"/>
14070	<const name="MouseStateMask" value="0x7F"/>
14071	</enum>
14072
14073	<interface
14074	name="IMouse" extends="$unknown"
14075	uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
14076	wsmap="managed"
14077	>
14078	<desc>
14079	The IMouse interface represents the virtual machine's mouse. Used in
14080	<link to="IConsole::mouse"/>.
14081
14082	Through this interface, the virtual machine's virtual mouse can be
14083	controlled.
14084	</desc>
14085
14086	<attribute name="absoluteSupported" type="boolean" readonly="yes">
14087	<desc>
14088	Whether the guest OS supports absolute mouse pointer positioning
14089	or not.
14090	<note>
14091	You can use the <link to="IMouseCapabilityChangedEvent"/>
14092	event to be instantly informed about changes of this attribute
14093	during virtual machine execution.
14094	</note>
14095	<see><link to="#putMouseEventAbsolute"/></see>
14096	</desc>
14097	</attribute>
14098
14099	<attribute name="relativeSupported" type="boolean" readonly="yes">
14100	<desc>
14101	Whether the guest OS supports relative mouse pointer positioning
14102	or not.
14103	<note>
14104	You can use the <link to="IMouseCapabilityChangedEvent"/>
14105	event to be instantly informed about changes of this attribute
14106	during virtual machine execution.
14107	</note>
14108	<see><link to="#putMouseEvent"/></see>
14109	</desc>
14110	</attribute>
14111
14112	<attribute name="needsHostCursor" type="boolean" readonly="yes">
14113	<desc>
14114	Whether the guest OS can currently switch to drawing it's own mouse
14115	cursor on demand.
14116	<note>
14117	You can use the <link to="IMouseCapabilityChangedEvent"/>
14118	event to be instantly informed about changes of this attribute
14119	during virtual machine execution.
14120	</note>
14121	<see><link to="#putMouseEvent"/></see>
14122	</desc>
14123	</attribute>
14124
14125	<method name="putMouseEvent">
14126	<desc>
14127	Initiates a mouse event using relative pointer movements
14128	along x and y axis.
14129
14130	<result name="E_ACCESSDENIED">
14131	Console not powered up.
14132	</result>
14133	<result name="VBOX_E_IPRT_ERROR">
14134	Could not send mouse event to virtual mouse.
14135	</result>
14136
14137	</desc>
14138
14139	<param name="dx" type="long" dir="in">
14140	<desc>
14141	Amount of pixels the mouse should move to the right.
14142	Negative values move the mouse to the left.
14143	</desc>
14144	</param>
14145	<param name="dy" type="long" dir="in">
14146	<desc>
14147	Amount of pixels the mouse should move downwards.
14148	Negative values move the mouse upwards.
14149	</desc>
14150	</param>
14151	<param name="dz" type="long" dir="in">
14152	<desc>
14153	Amount of mouse wheel moves.
14154	Positive values describe clockwise wheel rotations,
14155	negative values describe counterclockwise rotations.
14156	</desc>
14157	</param>
14158	<param name="dw" type="long" dir="in">
14159	<desc>
14160	Amount of horizontal mouse wheel moves.
14161	Positive values describe a movement to the left,
14162	negative values describe a movement to the right.
14163	</desc>
14164	</param>
14165	<param name="buttonState" type="long" dir="in">
14166	<desc>
14167	The current state of mouse buttons. Every bit represents
14168	a mouse button as follows:
14169	<table>
14170	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14171	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14172	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14173	</table>
14174	A value of <tt>1</tt> means the corresponding button is pressed.
14175	otherwise it is released.
14176	</desc>
14177	</param>
14178	</method>
14179
14180	<method name="putMouseEventAbsolute">
14181	<desc>
14182	Positions the mouse pointer using absolute x and y coordinates.
14183	These coordinates are expressed in pixels and
14184	start from <tt>[1,1]</tt> which corresponds to the top left
14185	corner of the virtual display.
14186
14187	<result name="E_ACCESSDENIED">
14188	Console not powered up.
14189	</result>
14190	<result name="VBOX_E_IPRT_ERROR">
14191	Could not send mouse event to virtual mouse.
14192	</result>
14193
14194	<note>
14195	This method will have effect only if absolute mouse
14196	positioning is supported by the guest OS.
14197	</note>
14198
14199	<see><link to="#absoluteSupported"/></see>
14200	</desc>
14201
14202	<param name="x" type="long" dir="in">
14203	<desc>
14204	X coordinate of the pointer in pixels, starting from @c 1.
14205	</desc>
14206	</param>
14207	<param name="y" type="long" dir="in">
14208	<desc>
14209	Y coordinate of the pointer in pixels, starting from @c 1.
14210	</desc>
14211	</param>
14212	<param name="dz" type="long" dir="in">
14213	<desc>
14214	Amount of mouse wheel moves.
14215	Positive values describe clockwise wheel rotations,
14216	negative values describe counterclockwise rotations.
14217	</desc>
14218	</param>
14219	<param name="dw" type="long" dir="in">
14220	<desc>
14221	Amount of horizontal mouse wheel moves.
14222	Positive values describe a movement to the left,
14223	negative values describe a movement to the right.
14224	</desc>
14225	</param>
14226	<param name="buttonState" type="long" dir="in">
14227	<desc>
14228	The current state of mouse buttons. Every bit represents
14229	a mouse button as follows:
14230	<table>
14231	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
14232	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
14233	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
14234	</table>
14235	A value of @c 1 means the corresponding button is pressed.
14236	otherwise it is released.
14237	</desc>
14238	</param>
14239	</method>
14240
14241	<attribute name="eventSource" type="IEventSource" readonly="yes">
14242	<desc>
14243	Event source for mouse events.
14244	</desc>
14245	</attribute>
14246
14247	</interface>
14248
14249	<!--
14250	// IDisplay
14251	/////////////////////////////////////////////////////////////////////////
14252	-->
14253
14254	<enum
14255	name="FramebufferPixelFormat"
14256	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
14257	>
14258	<desc>
14259	Format of the video memory buffer. Constants represented by this enum can
14260	be used to test for particular values of <link
14261	to="IFramebuffer::pixelFormat"/>. See also <link
14262	to="IFramebuffer::requestResize"/>.
14263
14264	See also www.fourcc.org for more information about FOURCC pixel formats.
14265	</desc>
14266
14267	<const name="Opaque" value="0">
14268	<desc>
14269	Unknown buffer format (the user may not assume any particular format of
14270	the buffer).
14271	</desc>
14272	</const>
14273	<const name="FOURCC_RGB" value="0x32424752">
14274	<desc>
14275	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
14276	bit layout).
14277	</desc>
14278	</const>
14279	</enum>
14280
14281	<interface
14282	name="IFramebuffer" extends="$unknown"
14283	uuid="e3f122c0-adab-4fc9-a8dc-da112fb48428"
14284	wsmap="suppress"
14285	>
14286	<attribute name="address" type="octet" mod="ptr" readonly="yes">
14287	<desc>Address of the start byte of the frame buffer.</desc>
14288	</attribute>
14289
14290	<attribute name="width" type="unsigned long" readonly="yes">
14291	<desc>Frame buffer width, in pixels.</desc>
14292	</attribute>
14293
14294	<attribute name="height" type="unsigned long" readonly="yes">
14295	<desc>Frame buffer height, in pixels.</desc>
14296	</attribute>
14297
14298	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
14299	<desc>
14300	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
14301	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
14302	are: 8, 15, 16, 24 and 32.
14303	</desc>
14304	</attribute>
14305
14306	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
14307	<desc>
14308	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
14309	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
14310	size of the scan line must be aligned to 32 bits.
14311	</desc>
14312	</attribute>
14313
14314	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
14315	<desc>
14316	Frame buffer pixel format. It's either one of the values defined by <link
14317	to="FramebufferPixelFormat"/> or a raw FOURCC code.
14318	<note>
14319	This attribute must never return <link
14320	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
14321	<link to="#address"/> points to must be always known.
14322	</note>
14323	</desc>
14324	</attribute>
14325
14326	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
14327	<desc>
14328	Defines whether this frame buffer uses the virtual video card's memory
14329	buffer (guest VRAM) directly or not. See <link
14330	to="IFramebuffer::requestResize"/> for more information.
14331	</desc>
14332	</attribute>
14333
14334	<attribute name="heightReduction" type="unsigned long" readonly="yes">
14335	<desc>
14336	Hint from the frame buffer about how much of the standard
14337	screen height it wants to use for itself. This information is
14338	exposed to the guest through the VESA BIOS and VMMDev interface
14339	so that it can use it for determining its video mode table. It
14340	is not guaranteed that the guest respects the value.
14341	</desc>
14342	</attribute>
14343
14344	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
14345	<desc>
14346	An alpha-blended overlay which is superposed over the frame buffer.
14347	The initial purpose is to allow the display of icons providing
14348	information about the VM state, including disk activity, in front
14349	ends which do not have other means of doing that. The overlay is
14350	designed to controlled exclusively by IDisplay. It has no locking
14351	of its own, and any changes made to it are not guaranteed to be
14352	visible until the affected portion of IFramebuffer is updated. The
14353	overlay can be created lazily the first time it is requested. This
14354	attribute can also return @c null to signal that the overlay is not
14355	implemented.
14356	</desc>
14357	</attribute>
14358
14359	<attribute name="winId" type="long long" readonly="yes">
14360	<desc>
14361	Platform-dependent identifier of the window where context of this
14362	frame buffer is drawn, or zero if there's no such window.
14363	</desc>
14364	</attribute>
14365
14366	<method name="lock">
14367	<desc>
14368	Locks the frame buffer.
14369	Gets called by the IDisplay object where this frame buffer is
14370	bound to.
14371	</desc>
14372	</method>
14373
14374	<method name="unlock">
14375	<desc>
14376	Unlocks the frame buffer.
14377	Gets called by the IDisplay object where this frame buffer is
14378	bound to.
14379	</desc>
14380	</method>
14381
14382	<method name="notifyUpdate">
14383	<desc>
14384	Informs about an update.
14385	Gets called by the display object where this buffer is
14386	registered.
14387	</desc>
14388	<param name="x" type="unsigned long" dir="in"/>
14389	<param name="y" type="unsigned long" dir="in"/>
14390	<param name="width" type="unsigned long" dir="in"/>
14391	<param name="height" type="unsigned long" dir="in"/>
14392	</method>
14393
14394	<method name="requestResize">
14395	<desc>
14396	Requests a size and pixel format change.
14397
14398	There are two modes of working with the video buffer of the virtual
14399	machine. The <i>indirect</i> mode implies that the IFramebuffer
14400	implementation allocates a memory buffer for the requested display mode
14401	and provides it to the virtual machine. In <i>direct</i> mode, the
14402	IFramebuffer implementation uses the memory buffer allocated and owned
14403	by the virtual machine. This buffer represents the video memory of the
14404	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
14405	usually faster because the implementation gets a raw pointer to the
14406	guest VRAM buffer which it can directly use for visualizing the contents
14407	of the virtual display, as opposed to the indirect mode where the
14408	contents of guest VRAM are copied to the memory buffer provided by
14409	the implementation every time a display update occurs.
14410
14411	It is important to note that the direct mode is really fast only when
14412	the implementation uses the given guest VRAM buffer directly, for
14413	example, by blitting it to the window representing the virtual machine's
14414	display, which saves at least one copy operation comparing to the
14415	indirect mode. However, using the guest VRAM buffer directly is not
14416	always possible: the format and the color depth of this buffer may be
14417	not supported by the target window, or it may be unknown (opaque) as in
14418	case of text or non-linear multi-plane VGA video modes. In this case,
14419	the indirect mode (that is always available) should be used as a
14420	fallback: when the guest VRAM contents are copied to the
14421	implementation-provided memory buffer, color and format conversion is
14422	done automatically by the underlying code.
14423
14424	The @a pixelFormat parameter defines whether the direct mode is
14425	available or not. If @a pixelFormat is <link
14426	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
14427	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
14428	@a bytesPerLine parameters must be ignored and the implementation must use
14429	the indirect mode (where it provides its own buffer in one of the
14430	supported formats). In all other cases, @a pixelFormat together with
14431	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
14432	buffer pointed to by the @a VRAM parameter and the implementation is
14433	free to choose which mode to use. To indicate that this frame buffer uses
14434	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
14435	attribute must return @c true and <link to="#address"/> must
14436	return exactly the same address that is passed in the @a VRAM parameter
14437	of this method; otherwise it is assumed that the indirect strategy is
14438	chosen.
14439
14440	The @a width and @a height parameters represent the size of the
14441	requested display mode in both modes. In case of indirect mode, the
14442	provided memory buffer should be big enough to store data of the given
14443	display mode. In case of direct mode, it is guaranteed that the given
14444	@a VRAM buffer contains enough space to represent the display mode of the
14445	given size. Note that this frame buffer's <link to="#width"/> and <link
14446	to="#height"/> attributes must return exactly the same values as
14447	passed to this method after the resize is completed (see below).
14448
14449	The @a finished output parameter determines if the implementation has
14450	finished resizing the frame buffer or not. If, for some reason, the
14451	resize cannot be finished immediately during this call, @a finished
14452	must be set to @c false, and the implementation must call
14453	<link to="IDisplay::resizeCompleted"/> after it has returned from
14454	this method as soon as possible. If @a finished is @c false, the
14455	machine will not call any frame buffer methods until
14456	<link to="IDisplay::resizeCompleted"/> is called.
14457
14458	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
14459	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
14460	this frame buffer must return exactly the same values as specified in the
14461	parameters of this method, after the resize is completed. If the
14462	indirect mode is chosen, these attributes must return values describing
14463	the format of the implementation's own memory buffer <link
14464	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
14465	value must always correlate with <link to="#pixelFormat"/>. Note that
14466	the <link to="#pixelFormat"/> attribute must never return <link
14467	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
14468
14469	<note>
14470	This method is called by the IDisplay object under the
14471	<link to="#lock"/> provided by this IFramebuffer
14472	implementation. If this method returns @c false in @a finished, then
14473	this lock is not released until
14474	<link to="IDisplay::resizeCompleted"/> is called.
14475	</note>
14476	</desc>
14477	<param name="screenId" type="unsigned long" dir="in">
14478	<desc>
14479	Logical screen number. Must be used in the corresponding call to
14480	<link to="IDisplay::resizeCompleted"/> if this call is made.
14481	</desc>
14482	</param>
14483	<param name="pixelFormat" type="unsigned long" dir="in">
14484	<desc>
14485	Pixel format of the memory buffer pointed to by @a VRAM.
14486	See also <link to="FramebufferPixelFormat"/>.
14487	</desc>
14488	</param>
14489	<param name="VRAM" type="octet" mod="ptr" dir="in">
14490	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
14491	</param>
14492	<param name="bitsPerPixel" type="unsigned long" dir="in">
14493	<desc>Color depth, bits per pixel.</desc>
14494	</param>
14495	<param name="bytesPerLine" type="unsigned long" dir="in">
14496	<desc>Size of one scan line, in bytes.</desc>
14497	</param>
14498	<param name="width" type="unsigned long" dir="in">
14499	<desc>Width of the guest display, in pixels.</desc>
14500	</param>
14501	<param name="height" type="unsigned long" dir="in">
14502	<desc>Height of the guest display, in pixels.</desc>
14503	</param>
14504	<param name="finished" type="boolean" dir="return">
14505	<desc>
14506	Can the VM start using the new frame buffer immediately
14507	after this method returns or it should wait for
14508	<link to="IDisplay::resizeCompleted"/>.
14509	</desc>
14510	</param>
14511	</method>
14512
14513	<method name="videoModeSupported">
14514	<desc>
14515	Returns whether the frame buffer implementation is willing to
14516	support a given video mode. In case it is not able to render
14517	the video mode (or for some reason not willing), it should
14518	return @c false. Usually this method is called when the guest
14519	asks the VMM device whether a given video mode is supported
14520	so the information returned is directly exposed to the guest.
14521	It is important that this method returns very quickly.
14522	</desc>
14523	<param name="width" type="unsigned long" dir="in"/>
14524	<param name="height" type="unsigned long" dir="in"/>
14525	<param name="bpp" type="unsigned long" dir="in"/>
14526	<param name="supported" type="boolean" dir="return"/>
14527	</method>
14528
14529	<method name="getVisibleRegion">
14530	<desc>
14531	Returns the visible region of this frame buffer.
14532
14533	If the @a rectangles parameter is @c null then the value of the
14534	@a count parameter is ignored and the number of elements necessary to
14535	describe the current visible region is returned in @a countCopied.
14536
14537	If @a rectangles is not @c null but @a count is less
14538	than the required number of elements to store region data, the method
14539	will report a failure. If @a count is equal or greater than the
14540	required number of elements, then the actual number of elements copied
14541	to the provided array will be returned in @a countCopied.
14542
14543	<note>
14544	The address of the provided array must be in the process space of
14545	this IFramebuffer object.
14546	</note>
14547	<note>
14548	Method not yet implemented.
14549	</note>
14550	</desc>
14551	<param name="rectangles" type="octet" mod="ptr" dir="in">
14552	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
14553	</param>
14554	<param name="count" type="unsigned long" dir="in">
14555	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14556	</param>
14557	<param name="countCopied" type="unsigned long" dir="return">
14558	<desc>Number of elements copied to the @a rectangles array.</desc>
14559	</param>
14560	</method>
14561
14562	<method name="setVisibleRegion">
14563	<desc>
14564	Suggests a new visible region to this frame buffer. This region
14565	represents the area of the VM display which is a union of regions of
14566	all top-level windows of the guest operating system running inside the
14567	VM (if the Guest Additions for this system support this
14568	functionality). This information may be used by the frontends to
14569	implement the seamless desktop integration feature.
14570
14571	<note>
14572	The address of the provided array must be in the process space of
14573	this IFramebuffer object.
14574	</note>
14575	<note>
14576	The IFramebuffer implementation must make a copy of the provided
14577	array of rectangles.
14578	</note>
14579	<note>
14580	Method not yet implemented.
14581	</note>
14582	</desc>
14583	<param name="rectangles" type="octet" mod="ptr" dir="in">
14584	<desc>Pointer to the @c RTRECT array.</desc>
14585	</param>
14586	<param name="count" type="unsigned long" dir="in">
14587	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
14588	</param>
14589	</method>
14590
14591	<method name="processVHWACommand">
14592	<desc>
14593	Posts a Video HW Acceleration Command to the frame buffer for processing.
14594	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
14595	are posted from quest to the host to be processed by the host hardware.
14596
14597	<note>
14598	The address of the provided command must be in the process space of
14599	this IFramebuffer object.
14600	</note>
14601	</desc>
14602
14603	<param name="command" type="octet" mod="ptr" dir="in">
14604	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
14605	</param>
14606	</method>
14607
14608	<method name="notify3DEvent">
14609	<desc>
14610	Notifies framebuffer about 3D backend event.
14611	</desc>
14612
14613	<param name="type" type="unsigned long" dir="in">
14614	<desc>event type. Currently only VBOX3D_NOTIFY_EVENT_TYPE_VISIBLE_WINDOW is supported.</desc>
14615	</param>
14616	<param name="reserved" type="octet" mod="ptr" dir="in">
14617	<desc>Reserved for future use, must be NULL.</desc>
14618	</param>
14619	</method>
14620
14621	</interface>
14622
14623	<interface
14624	name="IFramebufferOverlay" extends="IFramebuffer"
14625	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
14626	wsmap="suppress"
14627	>
14628	<desc>
14629	The IFramebufferOverlay interface represents an alpha blended overlay
14630	for displaying status icons above an IFramebuffer. It is always created
14631	not visible, so that it must be explicitly shown. It only covers a
14632	portion of the IFramebuffer, determined by its width, height and
14633	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
14634	that order) format, and may be written to directly. Do re-read the
14635	width though, after setting it, as it may be adjusted (increased) to
14636	make it more suitable for the front end.
14637	</desc>
14638	<attribute name="x" type="unsigned long" readonly="yes">
14639	<desc>X position of the overlay, relative to the frame buffer.</desc>
14640	</attribute>
14641
14642	<attribute name="y" type="unsigned long" readonly="yes">
14643	<desc>Y position of the overlay, relative to the frame buffer.</desc>
14644	</attribute>
14645
14646	<attribute name="visible" type="boolean">
14647	<desc>
14648	Whether the overlay is currently visible.
14649	</desc>
14650	</attribute>
14651
14652	<attribute name="alpha" type="unsigned long">
14653	<desc>
14654	The global alpha value for the overlay. This may or may not be
14655	supported by a given front end.
14656	</desc>
14657	</attribute>
14658
14659	<method name="move">
14660	<desc>
14661	Changes the overlay's position relative to the IFramebuffer.
14662	</desc>
14663	<param name="x" type="unsigned long" dir="in"/>
14664	<param name="y" type="unsigned long" dir="in"/>
14665	</method>
14666
14667	</interface>
14668
14669	<interface
14670	name="IDisplay" extends="$unknown"
14671	uuid="b83ee395-8679-40ca-8d60-1a0cbe724930"
14672	wsmap="managed"
14673	>
14674	<desc>
14675	The IDisplay interface represents the virtual machine's display.
14676
14677	The object implementing this interface is contained in each
14678	<link to="IConsole::display"/> attribute and represents the visual
14679	output of the virtual machine.
14680
14681	The virtual display supports pluggable output targets represented by the
14682	IFramebuffer interface. Examples of the output target are a window on
14683	the host computer or an RDP session's display on a remote computer.
14684	</desc>
14685	<method name="getScreenResolution">
14686	<desc>Queries display width, height and color depth for given screen.</desc>
14687	<param name="screenId" type="unsigned long" dir="in"/>
14688	<param name="width" type="unsigned long" dir="out"/>
14689	<param name="height" type="unsigned long" dir="out"/>
14690	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
14691	</method>
14692
14693	<method name="setFramebuffer">
14694	<desc>
14695	Sets the framebuffer for given screen.
14696	</desc>
14697	<param name="screenId" type="unsigned long" dir="in"/>
14698	<param name="framebuffer" type="IFramebuffer" dir="in"/>
14699	</method>
14700
14701	<method name="getFramebuffer">
14702	<desc>
14703	Queries the framebuffer for given screen.
14704	</desc>
14705	<param name="screenId" type="unsigned long" dir="in"/>
14706	<param name="framebuffer" type="IFramebuffer" dir="out"/>
14707	<param name="xOrigin" type="long" dir="out"/>
14708	<param name="yOrigin" type="long" dir="out"/>
14709	</method>
14710
14711	<method name="setVideoModeHint">
14712	<desc>
14713	Asks VirtualBox to request the given video mode from
14714	the guest. This is just a hint and it cannot be guaranteed
14715	that the requested resolution will be used. Guest Additions
14716	are required for the request to be seen by guests. The caller
14717	should issue the request and wait for a resolution change and
14718	after a timeout retry.
14719
14720	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
14721	parameters means that the corresponding values should be taken from the
14722	current video mode (i.e. left unchanged).
14723
14724	If the guest OS supports multi-monitor configuration then the @a display
14725	parameter specifies the number of the guest display to send the hint to:
14726	@c 0 is the primary display, @c 1 is the first secondary and
14727	so on. If the multi-monitor configuration is not supported, @a display
14728	must be @c 0.
14729
14730	<result name="E_INVALIDARG">
14731	The @a display is not associated with any monitor.
14732	</result>
14733
14734	</desc>
14735	<param name="display" type="unsigned long" dir="in">
14736	<desc>
14737	The number of the guest display to send the hint to.
14738	</desc>
14739	</param>
14740	<param name="enabled" type="boolean" dir="in">
14741	<desc>
14742	@c True, if this guest screen is enabled,
14743	@c False otherwise.
14744	</desc>
14745	</param>
14746	<param name="changeOrigin" type="boolean" dir="in">
14747	<desc>
14748	@c True, if the origin of the guest screen should be changed,
14749	@c False otherwise.
14750	</desc>
14751	</param>
14752	<param name="originX" type="long" dir="in">
14753	<desc>
14754	The X origin of the guest screen.
14755	</desc>
14756	</param>
14757	<param name="originY" type="long" dir="in">
14758	<desc>
14759	The Y origin of the guest screen.
14760	</desc>
14761	</param>
14762	<param name="width" type="unsigned long" dir="in"/>
14763	<param name="height" type="unsigned long" dir="in"/>
14764	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
14765	</method>
14766
14767	<method name="setSeamlessMode">
14768	<desc>
14769	Enables or disables seamless guest display rendering (seamless desktop
14770	integration) mode.
14771	<note>
14772	Calling this method has no effect if <link
14773	to="IGuest::getFacilityStatus"/> with facility @c Seamless
14774	does not return @c Active.
14775	</note>
14776	</desc>
14777	<param name="enabled" type="boolean" dir="in"/>
14778	</method>
14779
14780	<method name="takeScreenShot">
14781	<desc>
14782	Takes a screen shot of the requested size and copies it to the
14783	32-bpp buffer allocated by the caller and pointed to by @a address.
14784	A pixel consists of 4 bytes in order: B, G, R, 0.
14785
14786	<note>This API can be used only locally by a VM process through the
14787	COM/XPCOM C++ API as it requires pointer support. It is not
14788	available for scripting langages, Java or any webservice clients.
14789	Unless you are writing a new VM frontend use
14790	<link to="#takeScreenShotToArray" />.
14791	</note>
14792
14793	<result name="E_NOTIMPL">
14794	Feature not implemented.
14795	</result>
14796	<result name="VBOX_E_IPRT_ERROR">
14797	Could not take a screenshot.
14798	</result>
14799
14800	</desc>
14801	<param name="screenId" type="unsigned long" dir="in"/>
14802	<param name="address" type="octet" mod="ptr" dir="in"/>
14803	<param name="width" type="unsigned long" dir="in"/>
14804	<param name="height" type="unsigned long" dir="in"/>
14805	</method>
14806
14807	<method name="takeScreenShotToArray">
14808	<desc>
14809	Takes a guest screen shot of the requested size and returns it as
14810	an array of bytes in uncompressed 32-bpp RGBA format.
14811	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
14812
14813	This API is slow, but could be the only option to get guest screenshot
14814	for scriptable languages not allowed to manipulate with addresses
14815	directly.
14816
14817	<result name="E_NOTIMPL">
14818	Feature not implemented.
14819	</result>
14820	<result name="VBOX_E_IPRT_ERROR">
14821	Could not take a screenshot.
14822	</result>
14823	</desc>
14824	<param name="screenId" type="unsigned long" dir="in">
14825	<desc>
14826	Monitor to take screenshot from.
14827	</desc>
14828	</param>
14829	<param name="width" type="unsigned long" dir="in">
14830	<desc>
14831	Desired image width.
14832	</desc>
14833	</param>
14834	<param name="height" type="unsigned long" dir="in">
14835	<desc>
14836	Desired image height.
14837	</desc>
14838	</param>
14839	<param name="screenData" type="octet" dir="return" safearray="yes">
14840	<desc>
14841	Array with resulting screen data.
14842	</desc>
14843	</param>
14844	</method>
14845
14846	<method name="takeScreenShotPNGToArray">
14847	<desc>
14848	Takes a guest screen shot of the requested size and returns it as
14849	PNG image in array.
14850
14851	<result name="E_NOTIMPL">
14852	Feature not implemented.
14853	</result>
14854	<result name="VBOX_E_IPRT_ERROR">
14855	Could not take a screenshot.
14856	</result>
14857	</desc>
14858	<param name="screenId" type="unsigned long" dir="in">
14859	<desc>
14860	Monitor to take the screenshot from.
14861	</desc>
14862	</param>
14863	<param name="width" type="unsigned long" dir="in">
14864	<desc>
14865	Desired image width.
14866	</desc>
14867	</param>
14868	<param name="height" type="unsigned long" dir="in">
14869	<desc>
14870	Desired image height.
14871	</desc>
14872	</param>
14873	<param name="screenData" type="octet" dir="return" safearray="yes">
14874	<desc>
14875	Array with resulting screen data.
14876	</desc>
14877	</param>
14878	</method>
14879
14880	<method name="drawToScreen">
14881	<desc>
14882	Draws a 32-bpp image of the specified size from the given buffer
14883	to the given point on the VM display.
14884
14885	<result name="E_NOTIMPL">
14886	Feature not implemented.
14887	</result>
14888	<result name="VBOX_E_IPRT_ERROR">
14889	Could not draw to screen.
14890	</result>
14891
14892	</desc>
14893	<param name="screenId" type="unsigned long" dir="in">
14894	<desc>
14895	Monitor to take the screenshot from.
14896	</desc>
14897	</param>
14898	<param name="address" type="octet" mod="ptr" dir="in">
14899	<desc>
14900	Address to store the screenshot to
14901	</desc>
14902	</param>
14903	<param name="x" type="unsigned long" dir="in">
14904	<desc>
14905	Relative to the screen top left corner.
14906	</desc>
14907	</param>
14908	<param name="y" type="unsigned long" dir="in">
14909	<desc>
14910	Relative to the screen top left corner.
14911	</desc>
14912	</param>
14913	<param name="width" type="unsigned long" dir="in">
14914	<desc>
14915	Desired image width.
14916	</desc>
14917	</param>
14918	<param name="height" type="unsigned long" dir="in">
14919	<desc>
14920	Desired image height.
14921	</desc>
14922	</param>
14923	</method>
14924
14925	<method name="invalidateAndUpdate">
14926	<desc>
14927	Does a full invalidation of the VM display and instructs the VM
14928	to update it.
14929
14930	<result name="VBOX_E_IPRT_ERROR">
14931	Could not invalidate and update screen.
14932	</result>
14933
14934	</desc>
14935	</method>
14936
14937	<method name="resizeCompleted">
14938	<desc>
14939	Signals that a framebuffer has completed the resize operation.
14940
14941	<result name="VBOX_E_NOT_SUPPORTED">
14942	Operation only valid for external frame buffers.
14943	</result>
14944
14945	</desc>
14946	<param name="screenId" type="unsigned long" dir="in"/>
14947	</method>
14948
14949	<method name="completeVHWACommand">
14950	<desc>
14951	Signals that the Video HW Acceleration command has completed.
14952	</desc>
14953
14954	<param name="command" type="octet" mod="ptr" dir="in">
14955	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
14956	</param>
14957	</method>
14958
14959	<method name="viewportChanged">
14960	<desc>
14961	Signals that framebuffer window viewport has changed.
14962
14963	<result name="E_INVALIDARG">
14964	The specified viewport data is invalid.
14965	</result>
14966
14967	</desc>
14968
14969	<param name="screenId" type="unsigned long" dir="in">
14970	<desc>
14971	Monitor to take the screenshot from.
14972	</desc>
14973	</param>
14974	<param name="x" type="unsigned long" dir="in">
14975	<desc>
14976	Framebuffer x offset.
14977	</desc>
14978	</param>
14979	<param name="y" type="unsigned long" dir="in">
14980	<desc>
14981	Framebuffer y offset.
14982	</desc>
14983	</param>
14984	<param name="width" type="unsigned long" dir="in">
14985	<desc>
14986	Viewport width.
14987	</desc>
14988	</param>
14989	<param name="height" type="unsigned long" dir="in">
14990	<desc>
14991	Viewport height.
14992	</desc>
14993	</param>
14994	</method>
14995	</interface>
14996
14997	<!--
14998	// INetworkAdapter
14999	/////////////////////////////////////////////////////////////////////////
15000	-->
15001
15002	<enum
15003	name="NetworkAttachmentType"
15004	uuid="2ac4bc71-6b82-417a-acd1-f7426d2570d6"
15005	>
15006	<desc>
15007	Network attachment type.
15008	</desc>
15009
15010	<const name="Null" value="0">
15011	<desc>Null value, also means "not attached".</desc>
15012	</const>
15013	<const name="NAT" value="1"/>
15014	<const name="Bridged" value="2"/>
15015	<const name="Internal" value="3"/>
15016	<const name="HostOnly" value="4"/>
15017	<const name="Generic" value="5"/>
15018	</enum>
15019
15020	<enum
15021	name="NetworkAdapterType"
15022	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
15023	>
15024	<desc>
15025	Network adapter type.
15026	</desc>
15027
15028	<const name="Null" value="0">
15029	<desc>Null value (never used by the API).</desc>
15030	</const>
15031	<const name="Am79C970A" value="1">
15032	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
15033	</const>
15034	<const name="Am79C973" value="2">
15035	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
15036	</const>
15037	<const name="I82540EM" value="3">
15038	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
15039	</const>
15040	<const name="I82543GC" value="4">
15041	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
15042	</const>
15043	<const name="I82545EM" value="5">
15044	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
15045	</const>
15046	<const name="Virtio" value="6">
15047	<desc>Virtio network device.</desc>
15048	</const>
15049	</enum>
15050
15051	<enum
15052	name="NetworkAdapterPromiscModePolicy"
15053	uuid="c963768a-376f-4c85-8d84-d8ced4b7269e"
15054	>
15055	<desc>
15056	The promiscuous mode policy of an interface.
15057	</desc>
15058
15059	<const name="Deny" value="1">
15060	<desc>Deny promiscuous mode requests.</desc>
15061	</const>
15062	<const name="AllowNetwork" value="2">
15063	<desc>
15064	Allow promicuous mode, but restrict the scope it to the internal
15065	network so that it only applies to other VMs.
15066	</desc>
15067	</const>
15068	<const name="AllowAll" value="3">
15069	<desc>
15070	Allow promicuous mode, include unrelated traffic going over the wire
15071	and internally on the host.
15072	</desc>
15073	</const>
15074	</enum>
15075
15076	<interface
15077	name="INetworkAdapter" extends="$unknown"
15078	uuid="efa0f965-63c7-4c60-afdf-b1cc9943b9c0"
15079	wsmap="managed"
15080	>
15081	<desc>
15082	Represents a virtual network adapter that is attached to a virtual machine.
15083	Each virtual machine has a fixed number of network adapter slots with one
15084	instance of this attached to each of them. Call
15085	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
15086	is attached to a given slot in a given machine.
15087
15088	Each network adapter can be in one of five attachment modes, which are
15089	represented by the <link to="NetworkAttachmentType" /> enumeration;
15090	see the <link to="#attachmentType" /> attribute.
15091	</desc>
15092
15093	<attribute name="adapterType" type="NetworkAdapterType">
15094	<desc>
15095	Type of the virtual network adapter. Depending on this value,
15096	VirtualBox will provide a different virtual network hardware
15097	to the guest.
15098	</desc>
15099	</attribute>
15100
15101	<attribute name="slot" type="unsigned long" readonly="yes">
15102	<desc>
15103	Slot number this adapter is plugged into. Corresponds to
15104	the value you pass to <link to="IMachine::getNetworkAdapter"/>
15105	to obtain this instance.
15106	</desc>
15107	</attribute>
15108
15109	<attribute name="enabled" type="boolean">
15110	<desc>
15111	Flag whether the network adapter is present in the
15112	guest system. If disabled, the virtual guest hardware will
15113	not contain this network adapter. Can only be changed when
15114	the VM is not running.
15115	</desc>
15116	</attribute>
15117
15118	<attribute name="MACAddress" type="wstring">
15119	<desc>
15120	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
15121	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
15122	</desc>
15123	</attribute>
15124
15125	<attribute name="attachmentType" type="NetworkAttachmentType">
15126	<desc>
15127	Sets/Gets network attachment type of this network adapter.
15128	</desc>
15129	</attribute>
15130
15131	<attribute name="bridgedInterface" type="wstring">
15132	<desc>
15133	Name of the network interface the VM should be bridged to.
15134	</desc>
15135	</attribute>
15136
15137	<attribute name="hostOnlyInterface" type="wstring">
15138	<desc>
15139	Name of the host only network interface the VM is attached to.
15140	</desc>
15141	</attribute>
15142
15143	<attribute name="internalNetwork" type="wstring">
15144	<desc>
15145	Name of the internal network the VM is attached to.
15146	</desc>
15147	</attribute>
15148
15149	<attribute name="NATNetwork" type="wstring">
15150	<desc>
15151	Name of the NAT network the VM is attached to.
15152	</desc>
15153	</attribute>
15154
15155	<attribute name="genericDriver" type="wstring">
15156	<desc>
15157	Name of the driver to use for the "Generic" network attachment type.
15158	</desc>
15159	</attribute>
15160
15161	<attribute name="cableConnected" type="boolean">
15162	<desc>
15163	Flag whether the adapter reports the cable as connected or not.
15164	It can be used to report offline situations to a VM.
15165	</desc>
15166	</attribute>
15167
15168	<attribute name="lineSpeed" type="unsigned long">
15169	<desc>
15170	Line speed reported by custom drivers, in units of 1 kbps.
15171	</desc>
15172	</attribute>
15173
15174	<attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy">
15175	<desc>
15176	The promiscuous mode policy of the network adapter when attached to an
15177	internal network, host only network or a bridge.
15178	</desc>
15179	</attribute>
15180
15181	<attribute name="traceEnabled" type="boolean">
15182	<desc>
15183	Flag whether network traffic from/to the network card should be traced.
15184	Can only be toggled when the VM is turned off.
15185	</desc>
15186	</attribute>
15187
15188	<attribute name="traceFile" type="wstring">
15189	<desc>
15190	Filename where a network trace will be stored. If not set, VBox-pid.pcap
15191	will be used.
15192	</desc>
15193	</attribute>
15194
15195	<attribute name="NATEngine" type="INATEngine" readonly="yes">
15196	<desc>
15197	Points to the NAT engine which handles the network address translation
15198	for this interface. This is active only when the interface actually uses
15199	NAT.
15200	</desc>
15201	</attribute>
15202
15203	<attribute name="bootPriority" type="unsigned long">
15204	<desc>
15205	Network boot priority of the adapter. Priority 1 is highest. If not set,
15206	the priority is considered to be at the lowest possible setting.
15207	</desc>
15208	</attribute>
15209
15210	<attribute name="bandwidthGroup" type="IBandwidthGroup">
15211	<desc>The bandwidth group this network adapter is assigned to.</desc>
15212	</attribute>
15213
15214	<!-- property methods -->
15215
15216	<method name="getProperty" const="yes">
15217	<desc>
15218	Returns the value of the network attachment property with the given name.
15219
15220	If the requested data @a key does not exist, this function will
15221	succeed and return an empty string in the @a value argument.
15222
15223	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15224	</desc>
15225	<param name="key" type="wstring" dir="in">
15226	<desc>Name of the property to get.</desc>
15227	</param>
15228	<param name="value" type="wstring" dir="return">
15229	<desc>Current property value.</desc>
15230	</param>
15231	</method>
15232
15233	<method name="setProperty">
15234	<desc>
15235	Sets the value of the network attachment property with the given name.
15236
15237	Setting the property value to @c null or an empty string is equivalent
15238	to deleting the existing value.
15239
15240	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
15241	</desc>
15242	<param name="key" type="wstring" dir="in">
15243	<desc>Name of the property to set.</desc>
15244	</param>
15245	<param name="value" type="wstring" dir="in">
15246	<desc>Property value to set.</desc>
15247	</param>
15248	</method>
15249
15250	<method name="getProperties" const="yes">
15251	<desc>
15252	Returns values for a group of properties in one call.
15253
15254	The names of the properties to get are specified using the @a names
15255	argument which is a list of comma-separated property names or
15256	an empty string if all properties are to be returned.
15257	<note>Currently the value of this argument is ignored and the method
15258	always returns all existing properties.</note>
15259
15260	The method returns two arrays, the array of property names corresponding
15261	to the @a names argument and the current values of these properties.
15262	Both arrays have the same number of elements with each element at the
15263	given index in the first array corresponds to an element at the same
15264	index in the second array.
15265	</desc>
15266	<param name="names" type="wstring" dir="in">
15267	<desc>
15268	Names of properties to get.
15269	</desc>
15270	</param>
15271	<param name="returnNames" type="wstring" safearray="yes" dir="out">
15272	<desc>Names of returned properties.</desc>
15273	</param>
15274	<param name="returnValues" type="wstring" safearray="yes" dir="return">
15275	<desc>Values of returned properties.</desc>
15276	</param>
15277	</method>
15278
15279	</interface>
15280
15281
15282	<!--
15283	// ISerialPort
15284	/////////////////////////////////////////////////////////////////////////
15285	-->
15286
15287	<enum
15288	name="PortMode"
15289	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
15290	>
15291	<desc>
15292	The PortMode enumeration represents possible communication modes for
15293	the virtual serial port device.
15294	</desc>
15295
15296	<const name="Disconnected" value="0">
15297	<desc>Virtual device is not attached to any real host device.</desc>
15298	</const>
15299	<const name="HostPipe" value="1">
15300	<desc>Virtual device is attached to a host pipe.</desc>
15301	</const>
15302	<const name="HostDevice" value="2">
15303	<desc>Virtual device is attached to a host device.</desc>
15304	</const>
15305	<const name="RawFile" value="3">
15306	<desc>Virtual device is attached to a raw file.</desc>
15307	</const>
15308	</enum>
15309
15310	<interface
15311	name="ISerialPort" extends="$unknown"
15312	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
15313	wsmap="managed"
15314	>
15315
15316	<desc>
15317	The ISerialPort interface represents the virtual serial port device.
15318
15319	The virtual serial port device acts like an ordinary serial port
15320	inside the virtual machine. This device communicates to the real
15321	serial port hardware in one of two modes: host pipe or host device.
15322
15323	In host pipe mode, the #path attribute specifies the path to the pipe on
15324	the host computer that represents a serial port. The #server attribute
15325	determines if this pipe is created by the virtual machine process at
15326	machine startup or it must already exist before starting machine
15327	execution.
15328
15329	In host device mode, the #path attribute specifies the name of the
15330	serial port device on the host computer.
15331
15332	There is also a third communication mode: the disconnected mode. In this
15333	mode, the guest OS running inside the virtual machine will be able to
15334	detect the serial port, but all port write operations will be discarded
15335	and all port read operations will return no data.
15336
15337	<see><link to="IMachine::getSerialPort"/></see>
15338	</desc>
15339
15340	<attribute name="slot" type="unsigned long" readonly="yes">
15341	<desc>
15342	Slot number this serial port is plugged into. Corresponds to
15343	the value you pass to <link to="IMachine::getSerialPort"/>
15344	to obtain this instance.
15345	</desc>
15346	</attribute>
15347
15348	<attribute name="enabled" type="boolean">
15349	<desc>
15350	Flag whether the serial port is enabled. If disabled,
15351	the serial port will not be reported to the guest OS.
15352	</desc>
15353	</attribute>
15354
15355	<attribute name="IOBase" type="unsigned long">
15356	<desc>Base I/O address of the serial port.</desc>
15357	</attribute>
15358
15359	<attribute name="IRQ" type="unsigned long">
15360	<desc>IRQ number of the serial port.</desc>
15361	</attribute>
15362
15363	<attribute name="hostMode" type="PortMode">
15364	<desc>
15365	How is this port connected to the host.
15366	<note>
15367	Changing this attribute may fail if the conditions for
15368	<link to="#path"/> are not met.
15369	</note>
15370	</desc>
15371	</attribute>
15372
15373	<attribute name="server" type="boolean">
15374	<desc>
15375	Flag whether this serial port acts as a server (creates a new pipe on
15376	the host) or as a client (uses the existing pipe). This attribute is
15377	used only when <link to="#hostMode"/> is PortMode_HostPipe.
15378	</desc>
15379	</attribute>
15380
15381	<attribute name="path" type="wstring">
15382	<desc>
15383	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
15384	PortMode_HostPipe, or the host serial device name when
15385	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
15386	cases, setting a @c null or empty string as the attribute's value
15387	is an error. Otherwise, the value of this property is ignored.
15388	</desc>
15389	</attribute>
15390
15391	</interface>
15392
15393	<!--
15394	// IParallelPort
15395	/////////////////////////////////////////////////////////////////////////
15396	-->
15397
15398	<interface
15399	name="IParallelPort" extends="$unknown"
15400	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
15401	wsmap="managed"
15402	>
15403
15404	<desc>
15405	The IParallelPort interface represents the virtual parallel port device.
15406
15407	The virtual parallel port device acts like an ordinary parallel port
15408	inside the virtual machine. This device communicates to the real
15409	parallel port hardware using the name of the parallel device on the host
15410	computer specified in the #path attribute.
15411
15412	Each virtual parallel port device is assigned a base I/O address and an
15413	IRQ number that will be reported to the guest operating system and used
15414	to operate the given parallel port from within the virtual machine.
15415
15416	<see><link to="IMachine::getParallelPort"/></see>
15417	</desc>
15418
15419	<attribute name="slot" type="unsigned long" readonly="yes">
15420	<desc>
15421	Slot number this parallel port is plugged into. Corresponds to
15422	the value you pass to <link to="IMachine::getParallelPort"/>
15423	to obtain this instance.
15424	</desc>
15425	</attribute>
15426
15427	<attribute name="enabled" type="boolean">
15428	<desc>
15429	Flag whether the parallel port is enabled. If disabled,
15430	the parallel port will not be reported to the guest OS.
15431	</desc>
15432	</attribute>
15433
15434	<attribute name="IOBase" type="unsigned long">
15435	<desc>Base I/O address of the parallel port.</desc>
15436	</attribute>
15437
15438	<attribute name="IRQ" type="unsigned long">
15439	<desc>IRQ number of the parallel port.</desc>
15440	</attribute>
15441
15442	<attribute name="path" type="wstring">
15443	<desc>
15444	Host parallel device name. If this parallel port is enabled, setting a
15445	@c null or an empty string as this attribute's value will result in
15446	an error.
15447	</desc>
15448	</attribute>
15449
15450	</interface>
15451
15452
15453	<!--
15454	// IMachineDebugger
15455	/////////////////////////////////////////////////////////////////////////
15456	-->
15457
15458	<interface
15459	name="IMachineDebugger" extends="$unknown"
15460	uuid="1eeeb3c2-0089-4448-878e-414aee00e03b"
15461	wsmap="managed"
15462	>
15463	<method name="dumpGuestCore">
15464	<desc>
15465	Takes a core dump of the guest.
15466
15467	See include/VBox/dbgfcorefmt.h for details on the file format.
15468	</desc>
15469	<param name="filename" type="wstring" dir="in">
15470	<desc>
15471	The name of the output file. The file must not exist.
15472	</desc>
15473	</param>
15474	<param name="compression" type="wstring" dir="in">
15475	<desc>
15476	Reserved for future compression method indicator.
15477	</desc>
15478	</param>
15479	</method>
15480
15481	<method name="dumpHostProcessCore">
15482	<desc>
15483	Takes a core dump of the VM process on the host.
15484
15485	This feature is not implemented in the 4.0.0 release but it may show up
15486	in a dot release.
15487	</desc>
15488	<param name="filename" type="wstring" dir="in">
15489	<desc>
15490	The name of the output file. The file must not exist.
15491	</desc>
15492	</param>
15493	<param name="compression" type="wstring" dir="in">
15494	<desc>
15495	Reserved for future compression method indicator.
15496	</desc>
15497	</param>
15498	</method>
15499
15500	<method name="info">
15501	<desc>
15502	Interfaces with the info dumpers (DBGFInfo).
15503
15504	This feature is not implemented in the 4.0.0 release but it may show up
15505	in a dot release.
15506	</desc>
15507	<param name="name" type="wstring" dir="in">
15508	<desc>
15509	The name of the info item.
15510	</desc>
15511	</param>
15512	<param name="args" type="wstring" dir="in">
15513	<desc>
15514	Arguments to the info dumper.
15515	</desc>
15516	</param>
15517	<param name="info" type="wstring" dir="return">
15518	<desc>
15519	The into string.
15520	</desc>
15521	</param>
15522	</method>
15523
15524	<method name="injectNMI">
15525	<desc>
15526	Inject an NMI into a running VT-x/AMD-V VM.
15527	</desc>
15528	</method>
15529
15530	<method name="modifyLogGroups">
15531	<desc>
15532	Modifies the group settings of the debug or release logger.
15533	</desc>
15534	<param name="settings" type="wstring" dir="in">
15535	<desc>
15536	The group settings string. See iprt/log.h for details. To target the
15537	release logger, prefix the string with "release:".
15538	</desc>
15539	</param>
15540	</method>
15541
15542	<method name="modifyLogFlags">
15543	<desc>
15544	Modifies the debug or release logger flags.
15545	</desc>
15546	<param name="settings" type="wstring" dir="in">
15547	<desc>
15548	The flags settings string. See iprt/log.h for details. To target the
15549	release logger, prefix the string with "release:".
15550	</desc>
15551	</param>
15552	</method>
15553
15554	<method name="modifyLogDestinations">
15555	<desc>
15556	Modifies the debug or release logger destinations.
15557	</desc>
15558	<param name="settings" type="wstring" dir="in">
15559	<desc>
15560	The destination settings string. See iprt/log.h for details. To target the
15561	release logger, prefix the string with "release:".
15562	</desc>
15563	</param>
15564	</method>
15565
15566	<method name="readPhysicalMemory">
15567	<desc>
15568	Reads guest physical memory, no side effects (MMIO++).
15569
15570	This feature is not implemented in the 4.0.0 release but may show up
15571	in a dot release.
15572	</desc>
15573	<param name="address" type="long long" dir="in">
15574	<desc>The guest physical address.</desc>
15575	</param>
15576	<param name="size" type="unsigned long" dir="in">
15577	<desc>The number of bytes to read.</desc>
15578	</param>
15579	<param name="bytes" type="octet" safearray="yes" dir="return">
15580	<desc>The bytes read.</desc>
15581	</param>
15582	</method>
15583
15584	<method name="writePhysicalMemory">
15585	<desc>
15586	Writes guest physical memory, access handles (MMIO++) are ignored.
15587
15588	This feature is not implemented in the 4.0.0 release but may show up
15589	in a dot release.
15590	</desc>
15591	<param name="address" type="long long" dir="in">
15592	<desc>The guest physical address.</desc>
15593	</param>
15594	<param name="size" type="unsigned long" dir="in">
15595	<desc>The number of bytes to read.</desc>
15596	</param>
15597	<param name="bytes" type="octet" safearray="yes" dir="in">
15598	<desc>The bytes to write.</desc>
15599	</param>
15600	</method>
15601
15602	<method name="readVirtualMemory">
15603	<desc>
15604	Reads guest virtual memory, no side effects (MMIO++).
15605
15606	This feature is not implemented in the 4.0.0 release but may show up
15607	in a dot release.
15608	</desc>
15609	<param name="cpuId" type="unsigned long" dir="in">
15610	<desc>The identifier of the Virtual CPU.</desc>
15611	</param>
15612	<param name="address" type="long long" dir="in">
15613	<desc>The guest virtual address.</desc>
15614	</param>
15615	<param name="size" type="unsigned long" dir="in">
15616	<desc>The number of bytes to read.</desc>
15617	</param>
15618	<param name="bytes" type="octet" safearray="yes" dir="return">
15619	<desc>The bytes read.</desc>
15620	</param>
15621	</method>
15622
15623	<method name="writeVirtualMemory">
15624	<desc>
15625	Writes guest virtual memory, access handles (MMIO++) are ignored.
15626
15627	This feature is not implemented in the 4.0.0 release but may show up
15628	in a dot release.
15629	</desc>
15630	<param name="cpuId" type="unsigned long" dir="in">
15631	<desc>The identifier of the Virtual CPU.</desc>
15632	</param>
15633	<param name="address" type="long long" dir="in">
15634	<desc>The guest virtual address.</desc>
15635	</param>
15636	<param name="size" type="unsigned long" dir="in">
15637	<desc>The number of bytes to read.</desc>
15638	</param>
15639	<param name="bytes" type="octet" safearray="yes" dir="in">
15640	<desc>The bytes to write.</desc>
15641	</param>
15642	</method>
15643
15644	<method name="detectOS">
15645	<desc>
15646	Tries to (re-)detect the guest OS kernel.
15647
15648	This feature is not implemented in the 4.0.0 release but may show up
15649	in a dot release.
15650	</desc>
15651	<param name="os" type="wstring" dir="return">
15652	<desc>
15653	The detected OS kernel on success.
15654	</desc>
15655	</param>
15656	</method>
15657
15658	<method name="getRegister">
15659	<desc>
15660	Gets one register.
15661
15662	This feature is not implemented in the 4.0.0 release but may show up
15663	in a dot release.
15664	</desc>
15665	<param name="cpuId" type="unsigned long" dir="in">
15666	<desc>The identifier of the Virtual CPU.</desc>
15667	</param>
15668	<param name="name" type="wstring" dir="in">
15669	<desc>The register name, case is ignored.</desc>
15670	</param>
15671	<param name="value" type="wstring" dir="return">
15672	<desc>
15673	The register value. This is usually a hex value (always 0x prefixed)
15674	but other format may be used for floating point registers (TBD).
15675	</desc>
15676	</param>
15677	</method>
15678
15679	<method name="getRegisters">
15680	<desc>
15681	Gets all the registers for the given CPU.
15682
15683	This feature is not implemented in the 4.0.0 release but may show up
15684	in a dot release.
15685	</desc>
15686	<param name="cpuId" type="unsigned long" dir="in">
15687	<desc>The identifier of the Virtual CPU.</desc>
15688	</param>
15689	<param name="names" type="wstring" dir="out" safearray="yes">
15690	<desc>Array containing the lowercase register names.</desc>
15691	</param>
15692	<param name="values" type="wstring" dir="out" safearray="yes">
15693	<desc>
15694	Array paralell to the names holding the register values as if the
15695	register was returned by <link to="IMachineDebugger::getRegister"/>.
15696	</desc>
15697	</param>
15698	</method>
15699
15700	<method name="setRegister">
15701	<desc>
15702	Gets one register.
15703
15704	This feature is not implemented in the 4.0.0 release but may show up
15705	in a dot release.
15706	</desc>
15707	<param name="cpuId" type="unsigned long" dir="in">
15708	<desc>The identifier of the Virtual CPU.</desc>
15709	</param>
15710	<param name="name" type="wstring" dir="in">
15711	<desc>The register name, case is ignored.</desc>
15712	</param>
15713	<param name="value" type="wstring" dir="in">
15714	<desc>
15715	The new register value. Hexadecimal, decimal and octal formattings
15716	are supported in addition to any special formattings returned by
15717	the getters.
15718	</desc>
15719	</param>
15720	</method>
15721
15722	<method name="setRegisters">
15723	<desc>
15724	Sets zero or more registers atomically.
15725
15726	This feature is not implemented in the 4.0.0 release but may show up
15727	in a dot release.
15728	</desc>
15729	<param name="cpuId" type="unsigned long" dir="in">
15730	<desc>The identifier of the Virtual CPU.</desc>
15731	</param>
15732	<param name="names" type="wstring" dir="in" safearray="yes">
15733	<desc>Array containing the register names, case ignored.</desc>
15734	</param>
15735	<param name="values" type="wstring" dir="in" safearray="yes">
15736	<desc>
15737	Array paralell to the names holding the register values. See
15738	<link to="IMachineDebugger::setRegister"/> for formatting
15739	guidelines.
15740	</desc>
15741	</param>
15742	</method>
15743
15744	<method name="dumpGuestStack">
15745	<desc>
15746	Produce a simple stack dump using the current guest state.
15747
15748	This feature is not implemented in the 4.0.0 release but may show up
15749	in a dot release.
15750	</desc>
15751	<param name="cpuId" type="unsigned long" dir="in">
15752	<desc>The identifier of the Virtual CPU.</desc>
15753	</param>
15754	<param name="stack" type="wstring" dir="return">
15755	<desc>String containing the formatted stack dump.</desc>
15756	</param>
15757	</method>
15758
15759	<method name="resetStats">
15760	<desc>
15761	Reset VM statistics.
15762	</desc>
15763	<param name="pattern" type="wstring" dir="in">
15764	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15765	</param>
15766	</method>
15767
15768	<method name="dumpStats">
15769	<desc>
15770	Dumps VM statistics.
15771	</desc>
15772	<param name="pattern" type="wstring" dir="in">
15773	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15774	</param>
15775	</method>
15776
15777	<method name="getStats">
15778	<desc>
15779	Get the VM statistics in a XMLish format.
15780	</desc>
15781	<param name="pattern" type="wstring" dir="in">
15782	<desc>The selection pattern. A bit similar to filename globbing.</desc>
15783	</param>
15784	<param name="withDescriptions" type="boolean" dir="in">
15785	<desc>Whether to include the descriptions.</desc>
15786	</param>
15787	<param name="stats" type="wstring" dir="return">
15788	<desc>The XML document containing the statistics.</desc>
15789	</param>
15790	</method>
15791
15792	<attribute name="singleStep" type="boolean">
15793	<desc>Switch for enabling single-stepping.</desc>
15794	</attribute>
15795
15796	<attribute name="recompileUser" type="boolean">
15797	<desc>Switch for forcing code recompilation for user mode code.</desc>
15798	</attribute>
15799
15800	<attribute name="recompileSupervisor" type="boolean">
15801	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
15802	</attribute>
15803
15804	<attribute name="PATMEnabled" type="boolean">
15805	<desc>Switch for enabling and disabling the PATM component.</desc>
15806	</attribute>
15807
15808	<attribute name="CSAMEnabled" type="boolean">
15809	<desc>Switch for enabling and disabling the CSAM component.</desc>
15810	</attribute>
15811
15812	<attribute name="logEnabled" type="boolean">
15813	<desc>Switch for enabling and disabling the debug logger.</desc>
15814	</attribute>
15815
15816	<attribute name="logDbgFlags" type="wstring" readonly="yes">
15817	<desc>The debug logger flags.</desc>
15818	</attribute>
15819
15820	<attribute name="logDbgGroups" type="wstring" readonly="yes">
15821	<desc>The debug logger's group settings.</desc>
15822	</attribute>
15823
15824	<attribute name="logDbgDestinations" type="wstring" readonly="yes">
15825	<desc>The debug logger's destination settings.</desc>
15826	</attribute>
15827
15828	<attribute name="logRelFlags" type="wstring" readonly="yes">
15829	<desc>The release logger flags.</desc>
15830	</attribute>
15831
15832	<attribute name="logRelGroups" type="wstring" readonly="yes">
15833	<desc>The release logger's group settings.</desc>
15834	</attribute>
15835
15836	<attribute name="logRelDestinations" type="wstring" readonly="yes">
15837	<desc>The relase logger's destination settings.</desc>
15838	</attribute>
15839
15840	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
15841	<desc>
15842	Flag indicating whether the VM is currently making use of CPU hardware
15843	virtualization extensions.
15844	</desc>
15845	</attribute>
15846
15847	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
15848	<desc>
15849	Flag indicating whether the VM is currently making use of the nested paging
15850	CPU hardware virtualization extension.
15851	</desc>
15852	</attribute>
15853
15854	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
15855	<desc>
15856	Flag indicating whether the VM is currently making use of the VPID
15857	VT-x extension.
15858	</desc>
15859	</attribute>
15860
15861	<attribute name="HWVirtExUXEnabled" type="boolean" readonly="yes">
15862	<desc>
15863	Flag indicating whether the VM is currently making use of the
15864	unrestricted execution feature of VT-x.
15865	</desc>
15866	</attribute>
15867
15868	<attribute name="OSName" type="wstring" readonly="yes">
15869	<desc>
15870	Query the guest OS kernel name as detected by the DBGF.
15871
15872	This feature is not implemented in the 4.0.0 release but may show up
15873	in a dot release.
15874	</desc>
15875	</attribute>
15876
15877	<attribute name="OSVersion" type="wstring" readonly="yes">
15878	<desc>
15879	Query the guest OS kernel version string as detected by the DBGF.
15880
15881	This feature is not implemented in the 4.0.0 release but may show up
15882	in a dot release.
15883	</desc>
15884	</attribute>
15885
15886	<attribute name="PAEEnabled" type="boolean" readonly="yes">
15887	<desc>
15888	Flag indicating whether the VM is currently making use of the Physical
15889	Address Extension CPU feature.
15890	</desc>
15891	</attribute>
15892
15893	<attribute name="virtualTimeRate" type="unsigned long">
15894	<desc>
15895	The rate at which the virtual time runs expressed as a percentage.
15896	The accepted range is 2% to 20000%.
15897	</desc>
15898	</attribute>
15899
15900	<attribute name="VM" type="long long" readonly="yes" wsmap="suppress">
15901	<desc>
15902	Gets the user-mode VM handle, with a reference. Must be passed to
15903	VMR3ReleaseUVM when done. This is only for internal use while we carve
15904	the details of this interface.
15905	</desc>
15906	</attribute>
15907
15908	</interface>
15909
15910	<!--
15911	// IUSBController
15912	/////////////////////////////////////////////////////////////////////////
15913	-->
15914
15915	<interface
15916	name="IUSBController" extends="$unknown"
15917	uuid="01e6f13a-0580-452f-a40f-74e32a5e4921"
15918	wsmap="managed"
15919	>
15920	<attribute name="enabled" type="boolean">
15921	<desc>
15922	Flag whether the USB controller is present in the
15923	guest system. If disabled, the virtual guest hardware will
15924	not contain any USB controller. Can only be changed when
15925	the VM is powered off.
15926	</desc>
15927	</attribute>
15928
15929	<attribute name="enabledEHCI" type="boolean">
15930	<desc>
15931	Flag whether the USB EHCI controller is present in the
15932	guest system. If disabled, the virtual guest hardware will
15933	not contain a USB EHCI controller. Can only be changed when
15934	the VM is powered off.
15935	</desc>
15936	</attribute>
15937
15938	<attribute name="proxyAvailable" type="boolean" readonly="yes">
15939	<desc>
15940	Flag whether there is an USB proxy available.
15941	</desc>
15942	</attribute>
15943
15944	<attribute name="USBStandard" type="unsigned short" readonly="yes">
15945	<desc>
15946	USB standard version which the controller implements.
15947	This is a BCD which means that the major version is in the
15948	high byte and minor version is in the low byte.
15949	</desc>
15950	</attribute>
15951
15952	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
15953	<desc>
15954	List of USB device filters associated with the machine.
15955
15956	If the machine is currently running, these filters are activated
15957	every time a new (supported) USB device is attached to the host
15958	computer that was not ignored by global filters
15959	(<link to="IHost::USBDeviceFilters"/>).
15960
15961	These filters are also activated when the machine is powered up.
15962	They are run against a list of all currently available USB
15963	devices (in states
15964	<link to="USBDeviceState_Available"/>,
15965	<link to="USBDeviceState_Busy"/>,
15966	<link to="USBDeviceState_Held"/>) that were not previously
15967	ignored by global filters.
15968
15969	If at least one filter matches the USB device in question, this
15970	device is automatically captured (attached to) the virtual USB
15971	controller of this machine.
15972
15973	<see><link to="IUSBDeviceFilter"/>, <link to="IUSBController"/></see>
15974	</desc>
15975	</attribute>
15976
15977	<method name="createDeviceFilter">
15978	<desc>
15979	Creates a new USB device filter. All attributes except
15980	the filter name are set to empty (any match),
15981	<i>active</i> is @c false (the filter is not active).
15982
15983	The created filter can then be added to the list of filters using
15984	<link to="#insertDeviceFilter"/>.
15985
15986	<result name="VBOX_E_INVALID_VM_STATE">
15987	The virtual machine is not mutable.
15988	</result>
15989
15990	<see><link to="#deviceFilters"/></see>
15991	</desc>
15992	<param name="name" type="wstring" dir="in">
15993	<desc>
15994	Filter name. See <link to="IUSBDeviceFilter::name"/>
15995	for more info.
15996	</desc>
15997	</param>
15998	<param name="filter" type="IUSBDeviceFilter" dir="return">
15999	<desc>Created filter object.</desc>
16000	</param>
16001	</method>
16002
16003	<method name="insertDeviceFilter">
16004	<desc>
16005	Inserts the given USB device to the specified position
16006	in the list of filters.
16007
16008	Positions are numbered starting from <tt>0</tt>. If the specified
16009	position is equal to or greater than the number of elements in
16010	the list, the filter is added to the end of the collection.
16011
16012	<note>
16013	Duplicates are not allowed, so an attempt to insert a
16014	filter that is already in the collection, will return an
16015	error.
16016	</note>
16017
16018	<result name="VBOX_E_INVALID_VM_STATE">
16019	Virtual machine is not mutable.
16020	</result>
16021	<result name="E_INVALIDARG">
16022	USB device filter not created within this VirtualBox instance.
16023	</result>
16024	<result name="VBOX_E_INVALID_OBJECT_STATE">
16025	USB device filter already in list.
16026	</result>
16027
16028	<see><link to="#deviceFilters"/></see>
16029	</desc>
16030	<param name="position" type="unsigned long" dir="in">
16031	<desc>Position to insert the filter to.</desc>
16032	</param>
16033	<param name="filter" type="IUSBDeviceFilter" dir="in">
16034	<desc>USB device filter to insert.</desc>
16035	</param>
16036	</method>
16037
16038	<method name="removeDeviceFilter">
16039	<desc>
16040	Removes a USB device filter from the specified position in the
16041	list of filters.
16042
16043	Positions are numbered starting from <tt>0</tt>. Specifying a
16044	position equal to or greater than the number of elements in
16045	the list will produce an error.
16046
16047	<see><link to="#deviceFilters"/></see>
16048
16049	<result name="VBOX_E_INVALID_VM_STATE">
16050	Virtual machine is not mutable.
16051	</result>
16052	<result name="E_INVALIDARG">
16053	USB device filter list empty or invalid @a position.
16054	</result>
16055
16056	</desc>
16057	<param name="position" type="unsigned long" dir="in">
16058	<desc>Position to remove the filter from.</desc>
16059	</param>
16060	<param name="filter" type="IUSBDeviceFilter" dir="return">
16061	<desc>Removed USB device filter.</desc>
16062	</param>
16063	</method>
16064
16065	</interface>
16066
16067
16068	<!--
16069	// IUSBDevice
16070	/////////////////////////////////////////////////////////////////////////
16071	-->
16072
16073	<interface
16074	name="IUSBDevice" extends="$unknown"
16075	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
16076	wsmap="managed"
16077	>
16078	<desc>
16079	The IUSBDevice interface represents a virtual USB device attached to the
16080	virtual machine.
16081
16082	A collection of objects implementing this interface is stored in the
16083	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
16084	attached to a running virtual machine's USB controller.
16085	</desc>
16086
16087	<attribute name="id" type="uuid" mod="string" readonly="yes">
16088	<desc>
16089	Unique USB device ID. This ID is built from #vendorId,
16090	#productId, #revision and #serialNumber.
16091	</desc>
16092	</attribute>
16093
16094	<attribute name="vendorId" type="unsigned short" readonly="yes">
16095	<desc>Vendor ID.</desc>
16096	</attribute>
16097
16098	<attribute name="productId" type="unsigned short" readonly="yes">
16099	<desc>Product ID.</desc>
16100	</attribute>
16101
16102	<attribute name="revision" type="unsigned short" readonly="yes">
16103	<desc>
16104	Product revision number. This is a packed BCD represented as
16105	unsigned short. The high byte is the integer part and the low
16106	byte is the decimal.
16107	</desc>
16108	</attribute>
16109
16110	<attribute name="manufacturer" type="wstring" readonly="yes">
16111	<desc>Manufacturer string.</desc>
16112	</attribute>
16113
16114	<attribute name="product" type="wstring" readonly="yes">
16115	<desc>Product string.</desc>
16116	</attribute>
16117
16118	<attribute name="serialNumber" type="wstring" readonly="yes">
16119	<desc>Serial number string.</desc>
16120	</attribute>
16121
16122	<attribute name="address" type="wstring" readonly="yes">
16123	<desc>Host specific address of the device.</desc>
16124	</attribute>
16125
16126	<attribute name="port" type="unsigned short" readonly="yes">
16127	<desc>
16128	Host USB port number the device is physically
16129	connected to.
16130	</desc>
16131	</attribute>
16132
16133	<attribute name="version" type="unsigned short" readonly="yes">
16134	<desc>
16135	The major USB version of the device - 1 or 2.
16136	</desc>
16137	</attribute>
16138
16139	<attribute name="portVersion" type="unsigned short" readonly="yes">
16140	<desc>
16141	The major USB version of the host USB port the device is
16142	physically connected to - 1 or 2. For devices not connected to
16143	anything this will have the same value as the version attribute.
16144	</desc>
16145	</attribute>
16146
16147	<attribute name="remote" type="boolean" readonly="yes">
16148	<desc>
16149	Whether the device is physically connected to a remote VRDE
16150	client or to a local host machine.
16151	</desc>
16152	</attribute>
16153
16154	</interface>
16155
16156
16157	<!--
16158	// IUSBDeviceFilter
16159	/////////////////////////////////////////////////////////////////////////
16160	-->
16161
16162	<interface
16163	name="IUSBDeviceFilter" extends="$unknown"
16164	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
16165	wsmap="managed"
16166	>
16167	<desc>
16168	The IUSBDeviceFilter interface represents an USB device filter used
16169	to perform actions on a group of USB devices.
16170
16171	This type of filters is used by running virtual machines to
16172	automatically capture selected USB devices once they are physically
16173	attached to the host computer.
16174
16175	A USB device is matched to the given device filter if and only if all
16176	attributes of the device match the corresponding attributes of the
16177	filter (that is, attributes are joined together using the logical AND
16178	operation). On the other hand, all together, filters in the list of
16179	filters carry the semantics of the logical OR operation. So if it is
16180	desirable to create a match like "this vendor id OR this product id",
16181	one needs to create two filters and specify "any match" (see below)
16182	for unused attributes.
16183
16184	All filter attributes used for matching are strings. Each string
16185	is an expression representing a set of values of the corresponding
16186	device attribute, that will match the given filter. Currently, the
16187	following filtering expressions are supported:
16188
16189	<ul>
16190	<li><i>Interval filters</i>. Used to specify valid intervals for
16191	integer device attributes (Vendor ID, Product ID and Revision).
16192	The format of the string is:
16193
16194	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
16195
16196	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
16197	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
16198	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
16199	is omitted before a dash (<tt>-</tt>), the minimum possible integer
16200	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
16201	possible integer is assumed.
16202	</li>
16203	<li><i>Boolean filters</i>. Used to specify acceptable values for
16204	boolean device attributes. The format of the string is:
16205
16206	<tt>true\|false\|yes\|no\|0\|1</tt>
16207
16208	</li>
16209	<li><i>Exact match</i>. Used to specify a single value for the given
16210	device attribute. Any string that doesn't start with <tt>int:</tt>
16211	represents the exact match. String device attributes are compared to
16212	this string including case of symbols. Integer attributes are first
16213	converted to a string (see individual filter attributes) and then
16214	compared ignoring case.
16215
16216	</li>
16217	<li><i>Any match</i>. Any value of the corresponding device attribute
16218	will match the given filter. An empty or @c null string is
16219	used to construct this type of filtering expressions.
16220
16221	</li>
16222	</ul>
16223
16224	<note>
16225	On the Windows host platform, interval filters are not currently
16226	available. Also all string filter attributes
16227	(<link to="#manufacturer"/>, <link to="#product"/>,
16228	<link to="#serialNumber"/>) are ignored, so they behave as
16229	<i>any match</i> no matter what string expression is specified.
16230	</note>
16231
16232	<see><link to="IUSBController::deviceFilters"/>,
16233	<link to="IHostUSBDeviceFilter"/></see>
16234	</desc>
16235
16236	<attribute name="name" type="wstring">
16237	<desc>
16238	Visible name for this filter.
16239	This name is used to visually distinguish one filter from another,
16240	so it can neither be @c null nor an empty string.
16241	</desc>
16242	</attribute>
16243
16244	<attribute name="active" type="boolean">
16245	<desc>Whether this filter active or has been temporarily disabled.</desc>
16246	</attribute>
16247
16248	<attribute name="vendorId" type="wstring">
16249	<desc>
16250	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
16251	The string representation for the <i>exact matching</i>
16252	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16253	(including leading zeroes).
16254	</desc>
16255	</attribute>
16256
16257	<attribute name="productId" type="wstring">
16258	<desc>
16259	<link to="IUSBDevice::productId">Product ID</link> filter.
16260	The string representation for the <i>exact matching</i>
16261	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
16262	(including leading zeroes).
16263	</desc>
16264	</attribute>
16265
16266	<attribute name="revision" type="wstring">
16267	<desc>
16268	<link to="IUSBDevice::productId">Product revision number</link>
16269	filter. The string representation for the <i>exact matching</i>
16270	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
16271	of the integer part of the revision, and <tt>F</tt> is the
16272	decimal digit of its fractional part (including leading and
16273	trailing zeros).
16274	Note that for interval filters, it's best to use the hexadecimal
16275	form, because the revision is stored as a 16 bit packed BCD value;
16276	so the expression <tt>int:0x0100-0x0199</tt> will match any
16277	revision from <tt>1.0</tt> to <tt>1.99</tt>.
16278	</desc>
16279	</attribute>
16280
16281	<attribute name="manufacturer" type="wstring">
16282	<desc>
16283	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
16284	</desc>
16285	</attribute>
16286
16287	<attribute name="product" type="wstring">
16288	<desc>
16289	<link to="IUSBDevice::product">Product</link> filter.
16290	</desc>
16291	</attribute>
16292
16293	<attribute name="serialNumber" type="wstring">
16294	<desc>
16295	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
16296	</desc>
16297	</attribute>
16298
16299	<attribute name="port" type="wstring">
16300	<desc>
16301	<link to="IUSBDevice::port">Host USB port</link> filter.
16302	</desc>
16303	</attribute>
16304
16305	<attribute name="remote" type="wstring">
16306	<desc>
16307	<link to="IUSBDevice::remote">Remote state</link> filter.
16308	<note>
16309	This filter makes sense only for machine USB filters,
16310	i.e. it is ignored by IHostUSBDeviceFilter objects.
16311	</note>
16312	</desc>
16313	</attribute>
16314
16315	<attribute name="maskedInterfaces" type="unsigned long">
16316	<desc>
16317	This is an advanced option for hiding one or more USB interfaces
16318	from the guest. The value is a bit mask where the bits that are set
16319	means the corresponding USB interface should be hidden, masked off
16320	if you like.
16321	This feature only works on Linux hosts.
16322	</desc>
16323	</attribute>
16324
16325	</interface>
16326
16327
16328	<!--
16329	// IHostUSBDevice
16330	/////////////////////////////////////////////////////////////////////////
16331	-->
16332
16333	<enum
16334	name="USBDeviceState"
16335	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
16336	>
16337	<desc>
16338	USB device state. This enumeration represents all possible states
16339	of the USB device physically attached to the host computer regarding
16340	its state on the host computer and availability to guest computers
16341	(all currently running virtual machines).
16342
16343	Once a supported USB device is attached to the host, global USB
16344	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
16345	either ignore the device, or put it to USBDeviceState_Held state, or do
16346	nothing. Unless the device is ignored by global filters, filters of all
16347	currently running guests (<link to="IUSBController::deviceFilters"/>) are
16348	activated that can put it to USBDeviceState_Captured state.
16349
16350	If the device was ignored by global filters, or didn't match
16351	any filters at all (including guest ones), it is handled by the host
16352	in a normal way. In this case, the device state is determined by
16353	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
16354	or USBDeviceState_Available, depending on the current device usage.
16355
16356	Besides auto-capturing based on filters, the device can be manually
16357	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
16358	state is USBDeviceState_Busy, USBDeviceState_Available or
16359	USBDeviceState_Held.
16360
16361	<note>
16362	Due to differences in USB stack implementations in Linux and Win32,
16363	states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
16364	only to the Linux version of the product. This also means that (<link
16365	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
16366	device state is USBDeviceState_Held.
16367	</note>
16368
16369	<see><link to="IHostUSBDevice"/>, <link to="IHostUSBDeviceFilter"/></see>
16370	</desc>
16371
16372	<const name="NotSupported" value="0">
16373	<desc>
16374	Not supported by the VirtualBox server, not available to guests.
16375	</desc>
16376	</const>
16377	<const name="Unavailable" value="1">
16378	<desc>
16379	Being used by the host computer exclusively,
16380	not available to guests.
16381	</desc>
16382	</const>
16383	<const name="Busy" value="2">
16384	<desc>
16385	Being used by the host computer, potentially available to guests.
16386	</desc>
16387	</const>
16388	<const name="Available" value="3">
16389	<desc>
16390	Not used by the host computer, available to guests (the host computer
16391	can also start using the device at any time).
16392	</desc>
16393	</const>
16394	<const name="Held" value="4">
16395	<desc>
16396	Held by the VirtualBox server (ignored by the host computer),
16397	available to guests.
16398	</desc>
16399	</const>
16400	<const name="Captured" value="5">
16401	<desc>
16402	Captured by one of the guest computers, not available
16403	to anybody else.
16404	</desc>
16405	</const>
16406	</enum>
16407
16408	<interface
16409	name="IHostUSBDevice" extends="IUSBDevice"
16410	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
16411	wsmap="managed"
16412	>
16413	<desc>
16414	The IHostUSBDevice interface represents a physical USB device attached
16415	to the host computer.
16416
16417	Besides properties inherited from IUSBDevice, this interface adds the
16418	<link to="#state"/> property that holds the current state of the USB
16419	device.
16420
16421	<see><link to="IHost::USBDevices"/>,
16422	<link to="IHost::USBDeviceFilters"/></see>
16423	</desc>
16424
16425	<attribute name="state" type="USBDeviceState" readonly="yes">
16426	<desc>
16427	Current state of the device.
16428	</desc>
16429	</attribute>
16430
16431	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
16432
16433	</interface>
16434
16435
16436	<!--
16437	// IHostUSBDeviceFilter
16438	/////////////////////////////////////////////////////////////////////////
16439	-->
16440
16441	<enum
16442	name="USBDeviceFilterAction"
16443	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
16444	>
16445	<desc>
16446	Actions for host USB device filters.
16447	<see><link to="IHostUSBDeviceFilter"/>, <link to="USBDeviceState"/></see>
16448	</desc>
16449
16450	<const name="Null" value="0">
16451	<desc>Null value (never used by the API).</desc>
16452	</const>
16453	<const name="Ignore" value="1">
16454	<desc>Ignore the matched USB device.</desc>
16455	</const>
16456	<const name="Hold" value="2">
16457	<desc>Hold the matched USB device.</desc>
16458	</const>
16459	</enum>
16460
16461	<interface
16462	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
16463	uuid="4cc70246-d74a-400f-8222-3900489c0374"
16464	wsmap="managed"
16465	>
16466	<desc>
16467	The IHostUSBDeviceFilter interface represents a global filter for a
16468	physical USB device used by the host computer. Used indirectly in
16469	<link to="IHost::USBDeviceFilters"/>.
16470
16471	Using filters of this type, the host computer determines the initial
16472	state of the USB device after it is physically attached to the
16473	host's USB controller.
16474
16475	<note>
16476	The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
16477	filters, because it makes sense only for
16478	<link to="IUSBController::deviceFilters">machine USB filters</link>.
16479	</note>
16480
16481	<see><link to="IHost::USBDeviceFilters"/></see>
16482	</desc>
16483
16484	<attribute name="action" type="USBDeviceFilterAction">
16485	<desc>
16486	Action performed by the host when an attached USB device
16487	matches this filter.
16488	</desc>
16489	</attribute>
16490
16491	</interface>
16492
16493	<!--
16494	// IAudioAdapter
16495	/////////////////////////////////////////////////////////////////////////
16496	-->
16497
16498	<enum
16499	name="AudioDriverType"
16500	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
16501	>
16502	<desc>
16503	Host audio driver type.
16504	</desc>
16505
16506	<const name="Null" value="0">
16507	<desc>Null value, also means "dummy audio driver".</desc>
16508	</const>
16509	<const name="WinMM" value="1">
16510	<desc>Windows multimedia (Windows hosts only).</desc>
16511	</const>
16512	<const name="OSS" value="2">
16513	<desc>Open Sound System (Linux hosts only).</desc>
16514	</const>
16515	<const name="ALSA" value="3">
16516	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
16517	</const>
16518	<const name="DirectSound" value="4">
16519	<desc>DirectSound (Windows hosts only).</desc>
16520	</const>
16521	<const name="CoreAudio" value="5">
16522	<desc>CoreAudio (Mac hosts only).</desc>
16523	</const>
16524	<const name="MMPM" value="6">
16525	<desc>Reserved for historical reasons.</desc>
16526	</const>
16527	<const name="Pulse" value="7">
16528	<desc>PulseAudio (Linux hosts only).</desc>
16529	</const>
16530	<const name="SolAudio" value="8">
16531	<desc>Solaris audio (Solaris hosts only).</desc>
16532	</const>
16533	</enum>
16534
16535	<enum
16536	name="AudioControllerType"
16537	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
16538	>
16539	<desc>
16540	Virtual audio controller type.
16541	</desc>
16542
16543	<const name="AC97" value="0"/>
16544	<const name="SB16" value="1"/>
16545	<const name="HDA" value="2"/>
16546	</enum>
16547
16548	<interface
16549	name="IAudioAdapter" extends="$unknown"
16550	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
16551	wsmap="managed"
16552	>
16553	<desc>
16554	The IAudioAdapter interface represents the virtual audio adapter of
16555	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
16556	</desc>
16557	<attribute name="enabled" type="boolean">
16558	<desc>
16559	Flag whether the audio adapter is present in the
16560	guest system. If disabled, the virtual guest hardware will
16561	not contain any audio adapter. Can only be changed when
16562	the VM is not running.
16563	</desc>
16564	</attribute>
16565	<attribute name="audioController" type="AudioControllerType">
16566	<desc>
16567	The audio hardware we emulate.
16568	</desc>
16569	</attribute>
16570	<attribute name="audioDriver" type="AudioDriverType">
16571	<desc>
16572	Audio driver the adapter is connected to. This setting
16573	can only be changed when the VM is not running.
16574	</desc>
16575	</attribute>
16576	</interface>
16577
16578	<enum
16579	name="AuthType"
16580	uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
16581	>
16582	<desc>
16583	VirtualBox authentication type.
16584	</desc>
16585
16586	<const name="Null" value="0">
16587	<desc>Null value, also means "no authentication".</desc>
16588	</const>
16589	<const name="External" value="1"/>
16590	<const name="Guest" value="2"/>
16591	</enum>
16592
16593	<!--
16594	// IVRDEServer
16595	/////////////////////////////////////////////////////////////////////////
16596	-->
16597
16598	<interface
16599	name="IVRDEServer" extends="$unknown"
16600	uuid="d38de40a-c2c1-4e95-b5a4-167b05f5694c"
16601	wsmap="managed"
16602	>
16603
16604	<attribute name="enabled" type="boolean">
16605	<desc>Flag if VRDE server is enabled.</desc>
16606	</attribute>
16607
16608	<attribute name="authType" type="AuthType">
16609	<desc>VRDE authentication method.</desc>
16610	</attribute>
16611
16612	<attribute name="authTimeout" type="unsigned long">
16613	<desc>Timeout for guest authentication. Milliseconds.</desc>
16614	</attribute>
16615
16616	<attribute name="allowMultiConnection" type="boolean">
16617	<desc>
16618	Flag whether multiple simultaneous connections to the VM are permitted.
16619	Note that this will be replaced by a more powerful mechanism in the future.
16620	</desc>
16621	</attribute>
16622
16623	<attribute name="reuseSingleConnection" type="boolean">
16624	<desc>
16625	Flag whether the existing connection must be dropped and a new connection
16626	must be established by the VRDE server, when a new client connects in single
16627	connection mode.
16628	</desc>
16629	</attribute>
16630
16631	<attribute name="VRDEExtPack" type="wstring">
16632	<desc>
16633	The name of Extension Pack providing VRDE for this VM. Overrides
16634	<link to="ISystemProperties::defaultVRDEExtPack"/>.
16635	</desc>
16636	</attribute>
16637
16638	<attribute name="authLibrary" type="wstring">
16639	<desc>
16640	Library used for authentication of RDP clients by this VM. Overrides
16641	<link to="ISystemProperties::VRDEAuthLibrary"/>.
16642	</desc>
16643	</attribute>
16644
16645	<attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes">
16646	<desc>
16647	Array of names of properties, which are supported by this VRDE server.
16648	</desc>
16649	</attribute>
16650
16651	<method name="setVRDEProperty">
16652	<desc>
16653	Sets a VRDE specific property string.
16654
16655	If you pass @c null or empty string as a key @a value, the given @a key
16656	will be deleted.
16657
16658	</desc>
16659	<param name="key" type="wstring" dir="in">
16660	<desc>Name of the key to set.</desc>
16661	</param>
16662	<param name="value" type="wstring" dir="in">
16663	<desc>Value to assign to the key.</desc>
16664	</param>
16665	</method>
16666
16667	<method name="getVRDEProperty" const="yes">
16668	<desc>
16669	Returns a VRDE specific property string.
16670
16671	If the requested data @a key does not exist, this function will
16672	succeed and return an empty string in the @a value argument.
16673
16674	</desc>
16675	<param name="key" type="wstring" dir="in">
16676	<desc>Name of the key to get.</desc>
16677	</param>
16678	<param name="value" type="wstring" dir="return">
16679	<desc>Value of the requested key.</desc>
16680	</param>
16681	</method>
16682
16683	</interface>
16684
16685
16686	<!--
16687	// ISharedFolder
16688	/////////////////////////////////////////////////////////////////////////
16689	-->
16690
16691	<interface
16692	name="ISharedFolder" extends="$unknown"
16693	uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
16694	wsmap="struct"
16695	>
16696	<desc>
16697	The ISharedFolder interface represents a folder in the host computer's
16698	file system accessible from the guest OS running inside a virtual
16699	machine using an associated logical name.
16700
16701	There are three types of shared folders:
16702	<ul>
16703	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
16704	folders available to all virtual machines.</li>
16705	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
16706	VM-specific shared folders available to the given virtual machine at
16707	startup.</li>
16708	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
16709	VM-specific shared folders created in the session context (for
16710	example, when the virtual machine is running) and automatically
16711	discarded when the session is closed (the VM is powered off).</li>
16712	</ul>
16713
16714	Logical names of shared folders must be unique within the given scope
16715	(global, permanent or transient). However, they do not need to be unique
16716	across scopes. In this case, the definition of the shared folder in a
16717	more specific scope takes precedence over definitions in all other
16718	scopes. The order of precedence is (more specific to more general):
16719	<ol>
16720	<li>Transient definitions</li>
16721	<li>Permanent definitions</li>
16722	<li>Global definitions</li>
16723	</ol>
16724
16725	For example, if MyMachine has a shared folder named
16726	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
16727	transient shared folder named <tt>C_DRIVE</tt> (that points
16728	to <tt>C:\\\\WINDOWS</tt>) will change the definition
16729	of <tt>C_DRIVE</tt> in the guest OS so
16730	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
16731	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
16732	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
16733	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
16734	to <tt>C:\\</tt> if it still exists.
16735
16736	Note that permanent and transient shared folders of different machines
16737	are in different name spaces, so they don't overlap and don't need to
16738	have unique logical names.
16739
16740	<note>
16741	Global shared folders are not implemented in the current version of the
16742	product.
16743	</note>
16744	</desc>
16745
16746	<attribute name="name" type="wstring" readonly="yes">
16747	<desc>Logical name of the shared folder.</desc>
16748	</attribute>
16749
16750	<attribute name="hostPath" type="wstring" readonly="yes">
16751	<desc>Full path to the shared folder in the host file system.</desc>
16752	</attribute>
16753
16754	<attribute name="accessible" type="boolean" readonly="yes">
16755	<desc>
16756	Whether the folder defined by the host path is currently
16757	accessible or not.
16758	For example, the folder can be inaccessible if it is placed
16759	on the network share that is not available by the time
16760	this property is read.
16761	</desc>
16762	</attribute>
16763
16764	<attribute name="writable" type="boolean" readonly="yes">
16765	<desc>
16766	Whether the folder defined by the host path is writable or
16767	not.
16768	</desc>
16769	</attribute>
16770
16771	<attribute name="autoMount" type="boolean" readonly="yes">
16772	<desc>
16773	Whether the folder gets automatically mounted by the guest or not.
16774	</desc>
16775	</attribute>
16776
16777	<attribute name="lastAccessError" type="wstring" readonly="yes">
16778	<desc>
16779	Text message that represents the result of the last accessibility
16780	check.
16781
16782	Accessibility checks are performed each time the <link to="#accessible"/>
16783	attribute is read. An empty string is returned if the last
16784	accessibility check was successful. A non-empty string indicates a
16785	failure and should normally describe a reason of the failure (for
16786	example, a file read error).
16787	</desc>
16788	</attribute>
16789
16790	</interface>
16791
16792	<!--
16793	// ISession
16794	/////////////////////////////////////////////////////////////////////////
16795	-->
16796
16797	<interface
16798	name="IInternalSessionControl" extends="$unknown"
16799	uuid="0ba8d8b3-204b-448e-99c2-242eaa666ea8"
16800	internal="yes"
16801	wsmap="suppress"
16802	>
16803	<method name="getPID">
16804	<desc>PID of the process that has created this Session object.
16805	</desc>
16806	<param name="pid" type="unsigned long" dir="return"/>
16807	</method>
16808
16809	<method name="getRemoteConsole">
16810	<desc>
16811	Returns the console object suitable for remote control.
16812
16813	<result name="VBOX_E_INVALID_VM_STATE">
16814	Session state prevents operation.
16815	</result>
16816	<result name="VBOX_E_INVALID_OBJECT_STATE">
16817	Session type prevents operation.
16818	</result>
16819
16820	</desc>
16821	<param name="console" type="IConsole" dir="return"/>
16822	</method>
16823
16824	<method name="assignMachine">
16825	<desc>
16826	Assigns the machine object associated with this direct-type
16827	session or informs the session that it will be a remote one
16828	(if @a machine == @c null).
16829
16830	<result name="VBOX_E_INVALID_VM_STATE">
16831	Session state prevents operation.
16832	</result>
16833	<result name="VBOX_E_INVALID_OBJECT_STATE">
16834	Session type prevents operation.
16835	</result>
16836
16837	</desc>
16838	<param name="machine" type="IMachine" dir="in"/>
16839	<param name="lockType" type="LockType" dir="in"/>
16840	</method>
16841
16842	<method name="assignRemoteMachine">
16843	<desc>
16844	Assigns the machine and the (remote) console object associated with
16845	this remote-type session.
16846
16847	<result name="VBOX_E_INVALID_VM_STATE">
16848	Session state prevents operation.
16849	</result>
16850
16851	</desc>
16852	<param name="machine" type="IMachine" dir="in"/>
16853	<param name="console" type="IConsole" dir="in"/>
16854	</method>
16855
16856	<method name="updateMachineState">
16857	<desc>
16858	Updates the machine state in the VM process.
16859	Must be called only in certain cases
16860	(see the method implementation).
16861
16862	<result name="VBOX_E_INVALID_VM_STATE">
16863	Session state prevents operation.
16864	</result>
16865	<result name="VBOX_E_INVALID_OBJECT_STATE">
16866	Session type prevents operation.
16867	</result>
16868
16869	</desc>
16870	<param name="machineState" type="MachineState" dir="in"/>
16871	</method>
16872
16873	<method name="uninitialize">
16874	<desc>
16875	Uninitializes (closes) this session. Used by VirtualBox to close
16876	the corresponding remote session when the direct session dies
16877	or gets closed.
16878
16879	<result name="VBOX_E_INVALID_VM_STATE">
16880	Session state prevents operation.
16881	</result>
16882
16883	</desc>
16884	</method>
16885
16886	<method name="onNetworkAdapterChange">
16887	<desc>
16888	Triggered when settings of a network adapter of the
16889	associated virtual machine have changed.
16890
16891	<result name="VBOX_E_INVALID_VM_STATE">
16892	Session state prevents operation.
16893	</result>
16894	<result name="VBOX_E_INVALID_OBJECT_STATE">
16895	Session type prevents operation.
16896	</result>
16897
16898	</desc>
16899	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
16900	<param name="changeAdapter" type="boolean" dir="in"/>
16901	</method>
16902
16903	<method name="onSerialPortChange">
16904	<desc>
16905	Triggered when settings of a serial port of the
16906	associated virtual machine have changed.
16907
16908	<result name="VBOX_E_INVALID_VM_STATE">
16909	Session state prevents operation.
16910	</result>
16911	<result name="VBOX_E_INVALID_OBJECT_STATE">
16912	Session type prevents operation.
16913	</result>
16914
16915	</desc>
16916	<param name="serialPort" type="ISerialPort" dir="in"/>
16917	</method>
16918
16919	<method name="onParallelPortChange">
16920	<desc>
16921	Triggered when settings of a parallel port of the
16922	associated virtual machine have changed.
16923
16924	<result name="VBOX_E_INVALID_VM_STATE">
16925	Session state prevents operation.
16926	</result>
16927	<result name="VBOX_E_INVALID_OBJECT_STATE">
16928	Session type prevents operation.
16929	</result>
16930
16931	</desc>
16932	<param name="parallelPort" type="IParallelPort" dir="in"/>
16933	</method>
16934
16935	<method name="onStorageControllerChange">
16936	<desc>
16937	Triggered when settings of a storage controller of the
16938	associated virtual machine have changed.
16939
16940	<result name="VBOX_E_INVALID_VM_STATE">
16941	Session state prevents operation.
16942	</result>
16943	<result name="VBOX_E_INVALID_OBJECT_STATE">
16944	Session type prevents operation.
16945	</result>
16946
16947	</desc>
16948	</method>
16949
16950	<method name="onMediumChange">
16951	<desc>
16952	Triggered when attached media of the
16953	associated virtual machine have changed.
16954
16955	<result name="VBOX_E_INVALID_VM_STATE">
16956	Session state prevents operation.
16957	</result>
16958	<result name="VBOX_E_INVALID_OBJECT_STATE">
16959	Session type prevents operation.
16960	</result>
16961
16962	</desc>
16963
16964	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
16965	<desc>The medium attachment which changed.</desc>
16966	</param>
16967	<param name="force" type="boolean" dir="in">
16968	<desc>If the medium change was forced.</desc>
16969	</param>
16970	</method>
16971
16972	<method name="onStorageDeviceChange">
16973	<desc>
16974	Triggered when attached storage devices of the
16975	associated virtual machine have changed.
16976
16977	<result name="VBOX_E_INVALID_VM_STATE">
16978	Session state prevents operation.
16979	</result>
16980	<result name="VBOX_E_INVALID_OBJECT_STATE">
16981	Session type prevents operation.
16982	</result>
16983
16984	</desc>
16985
16986	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
16987	<desc>The medium attachment which changed.</desc>
16988	</param>
16989	<param name="remove" type="boolean" dir="in">
16990	<desc>TRUE if the device is removed, FALSE if it was added.</desc>
16991	</param>
16992	<param name="silent" type="boolean" dir="in">
16993	<desc>TRUE if the device is is silently reconfigured without
16994	notifying the guest about it.</desc>
16995	</param>
16996	</method>
16997
16998	<method name="onClipboardModeChange">
16999	<desc>
17000	Notification when the shared clipboard mode changes.
17001	</desc>
17002	<param name="clipboardMode" type="ClipboardMode" dir="in">
17003	<desc>The new shared clipboard mode.</desc>
17004	</param>
17005	</method>
17006
17007	<method name="onDragAndDropModeChange">
17008	<desc>
17009	Notification when the drag'n'drop mode changes.
17010	</desc>
17011	<param name="dragAndDropMode" type="DragAndDropMode" dir="in">
17012	<desc>The new mode for drag'n'drop.</desc>
17013	</param>
17014	</method>
17015
17016	<method name="onCPUChange">
17017	<desc>
17018	Notification when a CPU changes.
17019	</desc>
17020	<param name="cpu" type="unsigned long" dir="in">
17021	<desc>The CPU which changed</desc>
17022	</param>
17023	<param name="add" type="boolean" dir="in">
17024	<desc>Flag whether the CPU was added or removed</desc>
17025	</param>
17026	</method>
17027
17028	<method name="onCPUExecutionCapChange">
17029	<desc>
17030	Notification when the CPU execution cap changes.
17031	</desc>
17032	<param name="executionCap" type="unsigned long" dir="in">
17033	<desc>The new CPU execution cap value. (1-100)</desc>
17034	</param>
17035	</method>
17036
17037	<method name="onVRDEServerChange">
17038	<desc>
17039	Triggered when settings of the VRDE server object of the
17040	associated virtual machine have changed.
17041
17042	<result name="VBOX_E_INVALID_VM_STATE">
17043	Session state prevents operation.
17044	</result>
17045	<result name="VBOX_E_INVALID_OBJECT_STATE">
17046	Session type prevents operation.
17047	</result>
17048
17049	</desc>
17050	<param name="restart" type="boolean" dir="in">
17051	<desc>Flag whether the server must be restarted</desc>
17052	</param>
17053	</method>
17054
17055	<method name="onUSBControllerChange">
17056	<desc>
17057	Triggered when settings of the USB controller object of the
17058	associated virtual machine have changed.
17059
17060	<result name="VBOX_E_INVALID_VM_STATE">
17061	Session state prevents operation.
17062	</result>
17063	<result name="VBOX_E_INVALID_OBJECT_STATE">
17064	Session type prevents operation.
17065	</result>
17066
17067	</desc>
17068	</method>
17069
17070	<method name="onSharedFolderChange">
17071	<desc>
17072	Triggered when a permanent (global or machine) shared folder has been
17073	created or removed.
17074	<note>
17075	We don't pass shared folder parameters in this notification because
17076	the order in which parallel notifications are delivered is not defined,
17077	therefore it could happen that these parameters were outdated by the
17078	time of processing this notification.
17079	</note>
17080
17081	<result name="VBOX_E_INVALID_VM_STATE">
17082	Session state prevents operation.
17083	</result>
17084	<result name="VBOX_E_INVALID_OBJECT_STATE">
17085	Session type prevents operation.
17086	</result>
17087
17088	</desc>
17089	<param name="global" type="boolean" dir="in"/>
17090	</method>
17091
17092	<method name="onUSBDeviceAttach">
17093	<desc>
17094	Triggered when a request to capture a USB device (as a result
17095	of matched USB filters or direct call to
17096	<link to="IConsole::attachUSBDevice"/>) has completed.
17097	A @c null @a error object means success, otherwise it
17098	describes a failure.
17099
17100	<result name="VBOX_E_INVALID_VM_STATE">
17101	Session state prevents operation.
17102	</result>
17103	<result name="VBOX_E_INVALID_OBJECT_STATE">
17104	Session type prevents operation.
17105	</result>
17106
17107	</desc>
17108	<param name="device" type="IUSBDevice" dir="in"/>
17109	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17110	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
17111	</method>
17112
17113	<method name="onUSBDeviceDetach">
17114	<desc>
17115	Triggered when a request to release the USB device (as a result
17116	of machine termination or direct call to
17117	<link to="IConsole::detachUSBDevice"/>) has completed.
17118	A @c null @a error object means success, otherwise it
17119	describes a failure.
17120
17121	<result name="VBOX_E_INVALID_VM_STATE">
17122	Session state prevents operation.
17123	</result>
17124	<result name="VBOX_E_INVALID_OBJECT_STATE">
17125	Session type prevents operation.
17126	</result>
17127
17128	</desc>
17129	<param name="id" type="uuid" mod="string" dir="in"/>
17130	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
17131	</method>
17132
17133	<method name="onShowWindow">
17134	<desc>
17135	Called by <link to="IMachine::canShowConsoleWindow"/> and by
17136	<link to="IMachine::showConsoleWindow"/> in order to notify
17137	console listeners
17138	<link to="ICanShowWindowEvent"/>
17139	and <link to="IShowWindowEvent"/>.
17140
17141	<result name="VBOX_E_INVALID_OBJECT_STATE">
17142	Session type prevents operation.
17143	</result>
17144
17145	</desc>
17146	<param name="check" type="boolean" dir="in"/>
17147	<param name="canShow" type="boolean" dir="out"/>
17148	<param name="winId" type="long long" dir="out"/>
17149	</method>
17150
17151	<method name="onBandwidthGroupChange">
17152	<desc>
17153	Notification when one of the bandwidth groups change.
17154	</desc>
17155	<param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
17156	<desc>The bandwidth group which changed.</desc>
17157	</param>
17158	</method>
17159
17160	<method name="accessGuestProperty">
17161	<desc>
17162	Called by <link to="IMachine::getGuestProperty"/> and by
17163	<link to="IMachine::setGuestProperty"/> in order to read and
17164	modify guest properties.
17165
17166	<result name="VBOX_E_INVALID_VM_STATE">
17167	Machine session is not open.
17168	</result>
17169	<result name="VBOX_E_INVALID_OBJECT_STATE">
17170	Session type is not direct.
17171	</result>
17172
17173	</desc>
17174	<param name="name" type="wstring" dir="in"/>
17175	<param name="value" type="wstring" dir="in"/>
17176	<param name="flags" type="wstring" dir="in"/>
17177	<param name="isSetter" type="boolean" dir="in"/>
17178	<param name="retValue" type="wstring" dir="out"/>
17179	<param name="retTimestamp" type="long long" dir="out"/>
17180	<param name="retFlags" type="wstring" dir="out"/>
17181	</method>
17182
17183	<method name="enumerateGuestProperties" const="yes">
17184	<desc>
17185	Return a list of the guest properties matching a set of patterns along
17186	with their values, time stamps and flags.
17187
17188	<result name="VBOX_E_INVALID_VM_STATE">
17189	Machine session is not open.
17190	</result>
17191	<result name="VBOX_E_INVALID_OBJECT_STATE">
17192	Session type is not direct.
17193	</result>
17194
17195	</desc>
17196	<param name="patterns" type="wstring" dir="in">
17197	<desc>
17198	The patterns to match the properties against as a comma-separated
17199	string. If this is empty, all properties currently set will be
17200	returned.
17201	</desc>
17202	</param>
17203	<param name="keys" type="wstring" dir="out" safearray="yes">
17204	<desc>
17205	The key names of the properties returned.
17206	</desc>
17207	</param>
17208	<param name="values" type="wstring" dir="out" safearray="yes">
17209	<desc>
17210	The values of the properties returned. The array entries match the
17211	corresponding entries in the @a key array.
17212	</desc>
17213	</param>
17214	<param name="timestamps" type="long long" dir="out" safearray="yes">
17215	<desc>
17216	The time stamps of the properties returned. The array entries match
17217	the corresponding entries in the @a key array.
17218	</desc>
17219	</param>
17220	<param name="flags" type="wstring" dir="out" safearray="yes">
17221	<desc>
17222	The flags of the properties returned. The array entries match the
17223	corresponding entries in the @a key array.
17224	</desc>
17225	</param>
17226	</method>
17227
17228	<method name="onlineMergeMedium">
17229	<desc>
17230	Triggers online merging of a hard disk. Used internally when deleting
17231	a snapshot while a VM referring to the same hard disk chain is running.
17232
17233	<result name="VBOX_E_INVALID_VM_STATE">
17234	Machine session is not open.
17235	</result>
17236	<result name="VBOX_E_INVALID_OBJECT_STATE">
17237	Session type is not direct.
17238	</result>
17239
17240	</desc>
17241	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
17242	<desc>The medium attachment to identify the medium chain.</desc>
17243	</param>
17244	<param name="sourceIdx" type="unsigned long" dir="in">
17245	<desc>The index of the source image in the chain.
17246	Redundant, but drastically reduces IPC.</desc>
17247	</param>
17248	<param name="targetIdx" type="unsigned long" dir="in">
17249	<desc>The index of the target image in the chain.
17250	Redundant, but drastically reduces IPC.</desc>
17251	</param>
17252	<param name="source" type="IMedium" dir="in">
17253	<desc>Merge source medium.</desc>
17254	</param>
17255	<param name="target" type="IMedium" dir="in">
17256	<desc>Merge target medium.</desc>
17257	</param>
17258	<param name="mergeForward" type="boolean" dir="in">
17259	<desc>Merge direction.</desc>
17260	</param>
17261	<param name="parentForTarget" type="IMedium" dir="in">
17262	<desc>For forward merges: new parent for target medium.</desc>
17263	</param>
17264	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
17265	<desc>For backward merges: list of media which need their parent UUID
17266	updated.</desc>
17267	</param>
17268	<param name="progress" type="IProgress" dir="in">
17269	<desc>
17270	Progress object for this operation.
17271	</desc>
17272	</param>
17273	</method>
17274
17275	<method name="enableVMMStatistics">
17276	<desc>
17277	Enables or disables collection of VMM RAM statistics.
17278
17279	<result name="VBOX_E_INVALID_VM_STATE">
17280	Machine session is not open.
17281	</result>
17282	<result name="VBOX_E_INVALID_OBJECT_STATE">
17283	Session type is not direct.
17284	</result>
17285
17286	</desc>
17287	<param name="enable" type="boolean" dir="in">
17288	<desc>True enables statistics collection.</desc>
17289	</param>
17290	</method>
17291
17292	</interface>
17293
17294	<interface
17295	name="ISession" extends="$unknown"
17296	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
17297	wsmap="managed"
17298	>
17299	<desc>
17300	The ISession interface represents a client process and allows for locking
17301	virtual machines (represented by IMachine objects) to prevent conflicting
17302	changes to the machine.
17303
17304	Any caller wishing to manipulate a virtual machine needs to create a session
17305	object first, which lives in its own process space. Such session objects are
17306	then associated with <link to="IMachine" /> objects living in the VirtualBox
17307	server process to coordinate such changes.
17308
17309	There are two typical scenarios in which sessions are used:
17310
17311	<ul>
17312	<li>To alter machine settings or control a running virtual machine, one
17313	needs to lock a machine for a given session (client process) by calling
17314	<link to="IMachine::lockMachine"/>.
17315
17316	Whereas multiple sessions may control a running virtual machine, only
17317	one process can obtain a write lock on the machine to prevent conflicting
17318	changes. A write lock is also needed if a process wants to actually run a
17319	virtual machine in its own context, such as the VirtualBox GUI or
17320	VBoxHeadless front-ends. They must also lock a machine for their own
17321	sessions before they are allowed to power up the virtual machine.
17322
17323	As a result, no machine settings can be altered while another process is
17324	already using it, either because that process is modifying machine settings
17325	or because the machine is running.
17326	</li>
17327	<li>
17328	To start a VM using one of the existing VirtualBox front-ends (e.g. the
17329	VirtualBox GUI or VBoxHeadless), one would use
17330	<link to="IMachine::launchVMProcess"/>, which also takes a session object
17331	as its first parameter. This session then identifies the caller and lets the
17332	caller control the started machine (for example, pause machine execution or
17333	power it down) as well as be notified about machine execution state changes.
17334	</li>
17335	</ul>
17336
17337	How sessions objects are created in a client process depends on whether you use
17338	the Main API via COM or via the webservice:
17339
17340	<ul>
17341	<li>When using the COM API directly, an object of the Session class from the
17342	VirtualBox type library needs to be created. In regular COM C++ client code,
17343	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
17344	This object will then act as a local session object in further calls to open
17345	a session.
17346	</li>
17347
17348	<li>In the webservice, the session manager (IWebsessionManager) instead creates
17349	a session object automatically whenever <link to="IWebsessionManager::logon" />
17350	is called. A managed object reference to that session object can be retrieved by
17351	calling <link to="IWebsessionManager::getSessionObject" />.
17352	</li>
17353	</ul>
17354	</desc>
17355
17356	<attribute name="state" type="SessionState" readonly="yes">
17357	<desc>Current state of this session.</desc>
17358	</attribute>
17359
17360	<attribute name="type" type="SessionType" readonly="yes">
17361	<desc>
17362	Type of this session. The value of this attribute is valid only
17363	if the session currently has a machine locked (i.e. its
17364	<link to="#state" /> is Locked), otherwise an error will be returned.
17365	</desc>
17366	</attribute>
17367
17368	<attribute name="machine" type="IMachine" readonly="yes">
17369	<desc>Machine object associated with this session.</desc>
17370	</attribute>
17371
17372	<attribute name="console" type="IConsole" readonly="yes">
17373	<desc>Console object associated with this session.</desc>
17374	</attribute>
17375
17376	<method name="unlockMachine">
17377	<desc>
17378	Unlocks a machine that was previously locked for the current session.
17379
17380	Calling this method is required every time a machine has been locked
17381	for a particular session using the <link to="IMachine::launchVMProcess" />
17382	or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
17383	the machine will be set to <link to="MachineState_Aborted" /> on the
17384	server, and changes made to the machine settings will be lost.
17385
17386	Generally, it is recommended to unlock all machines explicitly
17387	before terminating the application (regardless of the reason for
17388	the termination).
17389
17390	<note>
17391	Do not expect the session state (<link to="ISession::state" />
17392	to return to "Unlocked" immediately after you invoke this method,
17393	particularly if you have started a new VM process. The session
17394	state will automatically return to "Unlocked" once the VM is no
17395	longer executing, which can of course take a very long time.
17396	</note>
17397
17398	<result name="E_UNEXPECTED">
17399	Session is not locked.
17400	</result>
17401
17402	</desc>
17403	</method>
17404
17405	</interface>
17406
17407	<!--
17408	// IStorageController
17409	/////////////////////////////////////////////////////////////////////////
17410	-->
17411
17412	<enum
17413	name="StorageBus"
17414	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
17415	>
17416	<desc>
17417	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
17418	see <link to="IStorageController::bus" />.
17419	</desc>
17420	<const name="Null" value="0">
17421	<desc>@c null value. Never used by the API.</desc>
17422	</const>
17423	<const name="IDE" value="1"/>
17424	<const name="SATA" value="2"/>
17425	<const name="SCSI" value="3"/>
17426	<const name="Floppy" value="4"/>
17427	<const name="SAS" value="5"/>
17428	</enum>
17429
17430	<enum
17431	name="StorageControllerType"
17432	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
17433	>
17434	<desc>
17435	The exact variant of storage controller hardware presented
17436	to the guest; see <link to="IStorageController::controllerType" />.
17437	</desc>
17438
17439	<const name="Null" value="0">
17440	<desc>@c null value. Never used by the API.</desc>
17441	</const>
17442	<const name="LsiLogic" value="1">
17443	<desc>A SCSI controller of the LsiLogic variant.</desc>
17444	</const>
17445	<const name="BusLogic" value="2">
17446	<desc>A SCSI controller of the BusLogic variant.</desc>
17447	</const>
17448	<const name="IntelAhci" value="3">
17449	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
17450	</const>
17451	<const name="PIIX3" value="4">
17452	<desc>An IDE controller of the PIIX3 variant.</desc>
17453	</const>
17454	<const name="PIIX4" value="5">
17455	<desc>An IDE controller of the PIIX4 variant.</desc>
17456	</const>
17457	<const name="ICH6" value="6">
17458	<desc>An IDE controller of the ICH6 variant.</desc>
17459	</const>
17460	<const name="I82078" value="7">
17461	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
17462	</const>
17463	<const name="LsiLogicSas" value="8">
17464	<desc>A variant of the LsiLogic controller using SAS.</desc>
17465	</const>
17466	</enum>
17467
17468	<enum
17469	name="ChipsetType"
17470	uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
17471	>
17472	<desc>
17473	Type of emulated chipset (mostly southbridge).
17474	</desc>
17475
17476	<const name="Null" value="0">
17477	<desc>@c null value. Never used by the API.</desc>
17478	</const>
17479	<const name="PIIX3" value="1">
17480	<desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
17481	</const>
17482	<const name="ICH9" value="2">
17483	<desc>A ICH9 (I/O Controller Hub) chipset.</desc>
17484	</const>
17485	</enum>
17486
17487	<interface
17488	name="IStorageController" extends="$unknown"
17489	uuid="a1556333-09b6-46d9-bfb7-fc239b7fbe1e"
17490	wsmap="managed"
17491	>
17492	<desc>
17493	Represents a storage controller that is attached to a virtual machine
17494	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
17495	attached to storage controllers in a real computer, virtual drives
17496	(represented by <link to="IMediumAttachment" />) are attached to virtual
17497	storage controllers, represented by this interface.
17498
17499	As opposed to physical hardware, VirtualBox has a very generic concept
17500	of a storage controller, and for purposes of the Main API, all virtual
17501	storage is attached to virtual machines via instances of this interface.
17502	There are five types of such virtual storage controllers: IDE, SCSI, SATA,
17503	SAS and Floppy (see <link to="#bus" />). Depending on which of these four
17504	is used, certain sub-types may be available and can be selected in
17505	<link to="#controllerType" />.
17506
17507	Depending on these settings, the guest operating system might see
17508	significantly different virtual hardware.
17509	</desc>
17510
17511	<attribute name="name" type="wstring" readonly="yes">
17512	<desc>
17513	Name of the storage controller, as originally specified with
17514	<link to="IMachine::addStorageController" />. This then uniquely
17515	identifies this controller with other method calls such as
17516	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
17517	</desc>
17518	</attribute>
17519
17520	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
17521	<desc>
17522	Maximum number of devices which can be attached to one port.
17523	</desc>
17524	</attribute>
17525
17526	<attribute name="minPortCount" type="unsigned long" readonly="yes">
17527	<desc>
17528	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
17529	</desc>
17530	</attribute>
17531
17532	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
17533	<desc>
17534	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
17535	</desc>
17536	</attribute>
17537
17538	<attribute name="instance" type="unsigned long">
17539	<desc>
17540	The instance number of the device in the running VM.
17541	</desc>
17542	</attribute>
17543
17544	<attribute name="portCount" type="unsigned long">
17545	<desc>
17546	The number of currently usable ports on the controller.
17547	The minimum and maximum number of ports for one controller are
17548	stored in <link to="IStorageController::minPortCount"/>
17549	and <link to="IStorageController::maxPortCount"/>.
17550	</desc>
17551	</attribute>
17552
17553	<attribute name="bus" type="StorageBus" readonly="yes">
17554	<desc>
17555	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
17556	</desc>
17557	</attribute>
17558
17559	<attribute name="controllerType" type="StorageControllerType">
17560	<desc>
17561	The exact variant of storage controller hardware presented
17562	to the guest.
17563	Depending on this value, VirtualBox will provide a different
17564	virtual storage controller hardware to the guest.
17565	For SATA, SAS and floppy controllers, only one variant is
17566	available, but for IDE and SCSI, there are several.
17567
17568	For SCSI controllers, the default type is LsiLogic.
17569	</desc>
17570	</attribute>
17571
17572	<attribute name="useHostIOCache" type="boolean">
17573	<desc>
17574	If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
17575	caches and use synchronous file APIs on the host. This was the only option in the API before
17576	VirtualBox 3.2 and is still the default for IDE controllers.
17577
17578	If false, the host I/O cache will be disabled for image files attached to this storage controller.
17579	Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
17580	it possible to turn off the host I/O caches because the emulation can handle unaligned access to
17581	the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
17582	virtual machines are running at the same time to prevent I/O cache related hangs.
17583	This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
17584	</desc>
17585	</attribute>
17586
17587	<attribute name="bootable" type="boolean" readonly="yes">
17588	<desc>
17589	Returns whether it is possible to boot from disks attached to this controller.
17590	</desc>
17591	</attribute>
17592	</interface>
17593
17594	<if target="wsdl">
17595
17596	<!--
17597	// IManagedObjectRef
17598	/////////////////////////////////////////////////////////////////////////
17599	-->
17600
17601	<interface
17602	name="IManagedObjectRef" extends="$unknown"
17603	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
17604	internal="yes"
17605	wsmap="managed"
17606	wscpp="hardcoded"
17607	>
17608	<desc>
17609	Managed object reference.
17610
17611	Only within the webservice, a managed object reference (which is really
17612	an opaque number) allows a webservice client to address an object
17613	that lives in the address space of the webservice server.
17614
17615	Behind each managed object reference, there is a COM object that lives
17616	in the webservice server's address space. The COM object is not freed
17617	until the managed object reference is released, either by an explicit
17618	call to <link to="IManagedObjectRef::release" /> or by logging off from
17619	the webservice (<link to="IWebsessionManager::logoff" />), which releases
17620	all objects created during the webservice session.
17621
17622	Whenever a method call of the VirtualBox API returns a COM object, the
17623	webservice representation of that method will instead return a
17624	managed object reference, which can then be used to invoke methods
17625	on that object.
17626	</desc>
17627
17628	<method name="getInterfaceName">
17629	<desc>
17630	Returns the name of the interface that this managed object represents,
17631	for example, "IMachine", as a string.
17632	</desc>
17633	<param name="return" type="wstring" dir="return"/>
17634	</method>
17635
17636	<method name="release">
17637	<desc>
17638	Releases this managed object reference and frees the resources that
17639	were allocated for it in the webservice server process. After calling
17640	this method, the identifier of the reference can no longer be used.
17641	</desc>
17642	</method>
17643
17644	</interface>
17645
17646	<!--
17647	// IWebsessionManager
17648	/////////////////////////////////////////////////////////////////////////
17649	-->
17650
17651	<interface
17652	name="IWebsessionManager" extends="$unknown"
17653	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
17654	internal="yes"
17655	wsmap="global"
17656	wscpp="hardcoded"
17657	>
17658	<desc>
17659	Websession manager. This provides essential services
17660	to webservice clients.
17661	</desc>
17662	<method name="logon">
17663	<desc>
17664	Logs a new client onto the webservice and returns a managed object reference to
17665	the IVirtualBox instance, which the client can then use as a basis to further
17666	queries, since all calls to the VirtualBox API are based on the IVirtualBox
17667	interface, in one way or the other.
17668	</desc>
17669	<param name="username" type="wstring" dir="in"/>
17670	<param name="password" type="wstring" dir="in"/>
17671	<param name="return" type="IVirtualBox" dir="return"/>
17672	</method>
17673
17674	<method name="getSessionObject">
17675	<desc>
17676	Returns a managed object reference to the internal ISession object that was created
17677	for this web service session when the client logged on.
17678
17679	<see><link to="ISession"/></see>
17680	</desc>
17681	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17682	<param name="return" type="ISession" dir="return"/>
17683	</method>
17684
17685	<method name="logoff">
17686	<desc>
17687	Logs off the client who has previously logged on with <link to="IWebsessionManager::logon" />
17688	and destroys all resources associated with the session (most importantly, all
17689	managed objects created in the server while the session was active).
17690	</desc>
17691	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
17692	</method>
17693
17694	</interface>
17695
17696	</if>
17697
17698	<!--
17699	// IPerformanceCollector & friends
17700	/////////////////////////////////////////////////////////////////////////
17701	-->
17702
17703	<interface
17704	name="IPerformanceMetric" extends="$unknown"
17705	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
17706	>
17707	<desc>
17708	The IPerformanceMetric interface represents parameters of the given
17709	performance metric.
17710	</desc>
17711
17712	<attribute name="metricName" type="wstring" readonly="yes">
17713	<desc>
17714	Name of the metric.
17715	</desc>
17716	</attribute>
17717
17718	<attribute name="object" type="$unknown" readonly="yes">
17719	<desc>
17720	Object this metric belongs to.
17721	</desc>
17722	</attribute>
17723
17724	<attribute name="description" type="wstring" readonly="yes">
17725	<desc>
17726	Textual description of the metric.
17727	</desc>
17728	</attribute>
17729
17730	<attribute name="period" type="unsigned long" readonly="yes">
17731	<desc>
17732	Time interval between samples, measured in seconds.
17733	</desc>
17734	</attribute>
17735
17736	<attribute name="count" type="unsigned long" readonly="yes">
17737	<desc>
17738	Number of recent samples retained by the performance collector for this
17739	metric.
17740
17741	When the collected sample count exceeds this number, older samples
17742	are discarded.
17743	</desc>
17744	</attribute>
17745
17746	<attribute name="unit" type="wstring" readonly="yes">
17747	<desc>
17748	Unit of measurement.
17749	</desc>
17750	</attribute>
17751
17752	<attribute name="minimumValue" type="long" readonly="yes">
17753	<desc>
17754	Minimum possible value of this metric.
17755	</desc>
17756	</attribute>
17757
17758	<attribute name="maximumValue" type="long" readonly="yes">
17759	<desc>
17760	Maximum possible value of this metric.
17761	</desc>
17762	</attribute>
17763	</interface>
17764
17765	<interface
17766	name="IPerformanceCollector" extends="$unknown"
17767	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
17768	wsmap="managed"
17769	>
17770	<desc>
17771	The IPerformanceCollector interface represents a service that collects
17772	and stores performance metrics data.
17773
17774	Performance metrics are associated with objects of interfaces like IHost
17775	and IMachine. Each object has a distinct set of performance metrics. The
17776	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
17777
17778	Metric data is collected at the specified intervals and is retained
17779	internally. The interval and the number of retained samples can be set
17780	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
17781	and collection settings are not persistent, they are discarded as soon as
17782	VBoxSVC process terminates. Moreover, metric settings and data associated
17783	with a particular VM only exist while VM is running. They disappear as
17784	soon as VM shuts down. It is not possible to set up metrics for machines
17785	that are powered off. One needs to start VM first, then set up metric
17786	collection parameters.
17787
17788	Metrics are organized hierarchically, with each level separated by a
17789	slash (/) character. Generally, the scheme for metric names is like this:
17790
17791	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
17792
17793	"Category/Metric" together form the base metric name. A base metric is
17794	the smallest unit for which a sampling interval and the number of
17795	retained samples can be set. Only base metrics can be enabled and
17796	disabled. All sub-metrics are collected when their base metric is
17797	collected. Collected values for any set of sub-metrics can be queried
17798	with <link to="IPerformanceCollector::queryMetricsData" />.
17799
17800	For example "CPU/Load/User:avg" metric name stands for the "CPU"
17801	category, "Load" metric, "User" submetric, "average" aggregate. An
17802	aggregate function is computed over all retained data. Valid aggregate
17803	functions are:
17804
17805	<ul>
17806	<li>avg -- average</li>
17807	<li>min -- minimum</li>
17808	<li>max -- maximum</li>
17809	</ul>
17810
17811	When setting up metric parameters, querying metric data, enabling or
17812	disabling metrics wildcards can be used in metric names to specify a
17813	subset of metrics. For example, to select all CPU-related metrics
17814	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
17815	so on. To query metric values without aggregates <tt>*:</tt> can be used.
17816
17817	The valid names for base metrics are:
17818
17819	<ul>
17820	<li>CPU/Load</li>
17821	<li>CPU/MHz</li>
17822	<li>RAM/Usage</li>
17823	<li>RAM/VMM</li>
17824	</ul>
17825
17826	The general sequence for collecting and retrieving the metrics is:
17827	<ul>
17828	<li>
17829	Obtain an instance of IPerformanceCollector with
17830	<link to="IVirtualBox::performanceCollector" />
17831	</li>
17832	<li>
17833	Allocate and populate an array with references to objects the metrics
17834	will be collected for. Use references to IHost and IMachine objects.
17835	</li>
17836	<li>
17837	Allocate and populate an array with base metric names the data will
17838	be collected for.
17839	</li>
17840	<li>
17841	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
17842	the metric data will be collected and stored.
17843	</li>
17844	<li>
17845	Wait for the data to get collected.
17846	</li>
17847	<li>
17848	Allocate and populate an array with references to objects the metric
17849	values will be queried for. You can re-use the object array used for
17850	setting base metrics.
17851	</li>
17852	<li>
17853	Allocate and populate an array with metric names the data will be
17854	collected for. Note that metric names differ from base metric names.
17855	</li>
17856	<li>
17857	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
17858	that have been collected so far are returned. Note that the values
17859	are still retained internally and data collection continues.
17860	</li>
17861	</ul>
17862
17863	For an example of usage refer to the following files in VirtualBox SDK:
17864	<ul>
17865	<li>
17866	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
17867	</li>
17868	<li>
17869	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
17870	</li>
17871	</ul>
17872	</desc>
17873
17874	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
17875	<desc>
17876	Array of unique names of metrics.
17877
17878	This array represents all metrics supported by the performance
17879	collector. Individual objects do not necessarily support all of them.
17880	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
17881	list of supported metrics for a particular object.
17882	</desc>
17883	</attribute>
17884
17885	<method name="getMetrics">
17886	<desc>
17887	Returns parameters of specified metrics for a set of objects.
17888	<note>
17889	@c Null metrics array means all metrics. @c Null object array means
17890	all existing objects.
17891	</note>
17892	</desc>
17893	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17894	<desc>
17895	Metric name filter. Currently, only a comma-separated list of metrics
17896	is supported.
17897	</desc>
17898	</param>
17899	<param name="objects" type="$unknown" dir="in" safearray="yes">
17900	<desc>
17901	Set of objects to return metric parameters for.
17902	</desc>
17903	</param>
17904	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
17905	<desc>
17906	Array of returned metric parameters.
17907	</desc>
17908	</param>
17909	</method>
17910
17911	<method name="setupMetrics">
17912	<desc>
17913	Sets parameters of specified base metrics for a set of objects. Returns
17914	an array of <link to="IPerformanceMetric" /> describing the metrics
17915	have been affected.
17916	<note>
17917	@c Null or empty metric name array means all metrics. @c Null or
17918	empty object array means all existing objects. If metric name array
17919	contains a single element and object array contains many, the single
17920	metric name array element is applied to each object array element to
17921	form metric/object pairs.
17922	</note>
17923	</desc>
17924	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17925	<desc>
17926	Metric name filter. Comma-separated list of metrics with wildcard
17927	support.
17928	</desc>
17929	</param>
17930	<param name="objects" type="$unknown" dir="in" safearray="yes">
17931	<desc>
17932	Set of objects to setup metric parameters for.
17933	</desc>
17934	</param>
17935	<param name="period" type="unsigned long" dir="in">
17936	<desc>
17937	Time interval in seconds between two consecutive samples of
17938	performance data.
17939	</desc>
17940	</param>
17941	<param name="count" type="unsigned long" dir="in">
17942	<desc>
17943	Number of samples to retain in performance data history. Older
17944	samples get discarded.
17945	</desc>
17946	</param>
17947	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
17948	<desc>
17949	Array of metrics that have been modified by the call to this method.
17950	</desc>
17951	</param>
17952	</method>
17953
17954	<method name="enableMetrics">
17955	<desc>
17956	Turns on collecting specified base metrics. Returns an array of
17957	<link to="IPerformanceMetric" /> describing the metrics have been
17958	affected.
17959	<note>
17960	@c Null or empty metric name array means all metrics. @c Null or
17961	empty object array means all existing objects. If metric name array
17962	contains a single element and object array contains many, the single
17963	metric name array element is applied to each object array element to
17964	form metric/object pairs.
17965	</note>
17966	</desc>
17967	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17968	<desc>
17969	Metric name filter. Comma-separated list of metrics with wildcard
17970	support.
17971	</desc>
17972	</param>
17973	<param name="objects" type="$unknown" dir="in" safearray="yes">
17974	<desc>
17975	Set of objects to enable metrics for.
17976	</desc>
17977	</param>
17978	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
17979	<desc>
17980	Array of metrics that have been modified by the call to this method.
17981	</desc>
17982	</param>
17983	</method>
17984
17985	<method name="disableMetrics">
17986	<desc>
17987	Turns off collecting specified base metrics. Returns an array of
17988	<link to="IPerformanceMetric" /> describing the metrics have been
17989	affected.
17990	<note>
17991	@c Null or empty metric name array means all metrics. @c Null or
17992	empty object array means all existing objects. If metric name array
17993	contains a single element and object array contains many, the single
17994	metric name array element is applied to each object array element to
17995	form metric/object pairs.
17996	</note>
17997	</desc>
17998	<param name="metricNames" type="wstring" dir="in" safearray="yes">
17999	<desc>
18000	Metric name filter. Comma-separated list of metrics with wildcard
18001	support.
18002	</desc>
18003	</param>
18004	<param name="objects" type="$unknown" dir="in" safearray="yes">
18005	<desc>
18006	Set of objects to disable metrics for.
18007	</desc>
18008	</param>
18009	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
18010	<desc>
18011	Array of metrics that have been modified by the call to this method.
18012	</desc>
18013	</param>
18014	</method>
18015
18016	<method name="queryMetricsData">
18017	<desc>
18018	Queries collected metrics data for a set of objects.
18019
18020	The data itself and related metric information are returned in seven
18021	parallel and one flattened array of arrays. Elements of
18022	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
18023	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
18024	the same index describe one set of values corresponding to a single
18025	metric.
18026
18027	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
18028	start and length of a sub-array is indicated by
18029	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
18030	value for metric <tt>metricNames[i]</tt> is at
18031	<tt>returnData[returnIndices[i]]</tt>.
18032
18033	<note>
18034	@c Null or empty metric name array means all metrics. @c Null or
18035	empty object array means all existing objects. If metric name array
18036	contains a single element and object array contains many, the single
18037	metric name array element is applied to each object array element to
18038	form metric/object pairs.
18039	</note>
18040	<note>
18041	Data collection continues behind the scenes after call to @c
18042	queryMetricsData. The return data can be seen as the snapshot of the
18043	current state at the time of @c queryMetricsData call. The internally
18044	kept metric values are not cleared by the call. This makes possible
18045	querying different subsets of metrics or aggregates with subsequent
18046	calls. If periodic querying is needed it is highly suggested to query
18047	the values with @c interval*count period to avoid confusion. This way
18048	a completely new set of data values will be provided by each query.
18049	</note>
18050	</desc>
18051	<param name="metricNames" type="wstring" dir="in" safearray="yes">
18052	<desc>
18053	Metric name filter. Comma-separated list of metrics with wildcard
18054	support.
18055	</desc>
18056	</param>
18057	<param name="objects" type="$unknown" dir="in" safearray="yes">
18058	<desc>
18059	Set of objects to query metrics for.
18060	</desc>
18061	</param>
18062	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
18063	<desc>
18064	Names of metrics returned in @c returnData.
18065	</desc>
18066	</param>
18067	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
18068	<desc>
18069	Objects associated with metrics returned in @c returnData.
18070	</desc>
18071	</param>
18072	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
18073	<desc>
18074	Units of measurement for each returned metric.
18075	</desc>
18076	</param>
18077	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
18078	<desc>
18079	Divisor that should be applied to return values in order to get
18080	floating point values. For example:
18081	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
18082	will retrieve the floating point value of i-th sample of the first
18083	metric.
18084	</desc>
18085	</param>
18086	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
18087	<desc>
18088	Sequence numbers of the first elements of value sequences of
18089	particular metrics returned in @c returnData. For aggregate metrics
18090	it is the sequence number of the sample the aggregate started
18091	calculation from.
18092	</desc>
18093	</param>
18094	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
18095	<desc>
18096	Indices of the first elements of value sequences of particular
18097	metrics returned in @c returnData.
18098	</desc>
18099	</param>
18100	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
18101	<desc>
18102	Lengths of value sequences of particular metrics.
18103	</desc>
18104	</param>
18105	<param name="returnData" type="long" dir="return" safearray="yes">
18106	<desc>
18107	Flattened array of all metric data containing sequences of values for
18108	each metric.
18109	</desc>
18110	</param>
18111	</method>
18112
18113	</interface>
18114
18115	<enum
18116	name="NATAliasMode"
18117	uuid="67772168-50d9-11df-9669-7fb714ee4fa1"
18118	>
18119	<desc></desc>
18120	<const name="AliasLog" value="0x1">
18121	<desc></desc>
18122	</const>
18123	<const name="AliasProxyOnly" value="0x02">
18124	<desc></desc>
18125	</const>
18126	<const name="AliasUseSamePorts" value="0x04">
18127	<desc></desc>
18128	</const>
18129	</enum>
18130
18131	<enum
18132	name="NATProtocol"
18133	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
18134	>
18135	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
18136	<const name="UDP" value="0">
18137	<desc>Port-forwarding uses UDP protocol.</desc>
18138	</const>
18139	<const name="TCP" value="1">
18140	<desc>Port-forwarding uses TCP protocol.</desc>
18141	</const>
18142	</enum>
18143
18144	<interface
18145	name="INATEngine" extends="$unknown"
18146	uuid="26451b99-3b2d-4dcb-8e4b-d63654218175"
18147	wsmap="managed"
18148	>
18149	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
18150	allows for changing NAT behavior such as port-forwarding rules. This interface is
18151	used in the <link to="INetworkAdapter::NATEngine" /> attribute.</desc>
18152	<attribute name="network" type="wstring">
18153	<desc>The network attribute of the NAT engine (the same value is used with built-in
18154	DHCP server to fill corresponding fields of DHCP leases).</desc>
18155	</attribute>
18156	<attribute name="hostIP" type="wstring">
18157	<desc>IP of host interface to bind all opened sockets to.
18158	<note>Changing this does not change binding of port forwarding.</note>
18159	</desc>
18160	</attribute>
18161	<attribute name="TFTPPrefix" type="wstring">
18162	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
18163	the corresponding fields of DHCP leases.</desc>
18164	</attribute>
18165	<attribute name="TFTPBootFile" type="wstring">
18166	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
18167	the corresponding fields of DHCP leases.</desc>
18168	</attribute>
18169	<attribute name="TFTPNextServer" type="wstring">
18170	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
18171	the corresponding fields of DHCP leases.
18172	<note>The preferred form is IPv4 addresses.</note>
18173	</desc>
18174	</attribute>
18175	<attribute name="aliasMode" type="unsigned long">
18176	<desc></desc>
18177	</attribute>
18178	<attribute name="DNSPassDomain" type="boolean">
18179	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
18180	</attribute>
18181	<attribute name="DNSProxy" type="boolean">
18182	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18183	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
18184	</attribute>
18185	<attribute name="DNSUseHostResolver" type="boolean">
18186	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
18187	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
18188	</attribute>
18189	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
18190	<desc>Array of NAT port-forwarding rules in string representation, in the following
18191	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
18192	</attribute>
18193	<method name="setNetworkSettings">
18194	<desc>Sets network configuration of the NAT engine.</desc>
18195	<param name="mtu" type="unsigned long" dir="in">
18196	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
18197	</param>
18198	<param name="sockSnd" type="unsigned long" dir="in">
18199	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
18200	</param>
18201	<param name="sockRcv" type="unsigned long" dir="in">
18202	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
18203	</param>
18204	<param name="TcpWndSnd" type="unsigned long" dir="in">
18205	<desc>Initial size of the NAT engine's sending TCP window in bytes when
18206	establishing a new TCP connection.</desc>
18207	</param>
18208	<param name="TcpWndRcv" type="unsigned long" dir="in">
18209	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
18210	establishing a new TCP connection.</desc>
18211	</param>
18212	</method>
18213	<method name="getNetworkSettings">
18214	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
18215	for parameter descriptions.</desc>
18216	<param name="mtu" type="unsigned long" dir="out" />
18217	<param name="sockSnd" type="unsigned long" dir="out" />
18218	<param name="sockRcv" type="unsigned long" dir="out" />
18219	<param name="TcpWndSnd" type="unsigned long" dir="out" />
18220	<param name="TcpWndRcv" type="unsigned long" dir="out" />
18221	</method>
18222	<method name="addRedirect">
18223	<desc>Adds a new NAT port-forwarding rule.</desc>
18224	<param name="name" type="wstring" dir="in">
18225	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
18226	auto-generates one using the other parameters.</desc>
18227	</param>
18228	<param name="proto" type="NATProtocol" dir="in">
18229	<desc>Protocol handled with the rule.</desc>
18230	</param>
18231	<param name="hostIP" type="wstring" dir="in">
18232	<desc>IP of the host interface to which the rule should apply. An empty ip address is
18233	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
18234	</param>
18235	<param name="hostPort" type="unsigned short" dir="in">
18236	<desc>The port number to listen on.</desc>
18237	</param>
18238	<param name="guestIP" type="wstring" dir="in">
18239	<desc>The IP address of the guest which the NAT engine will forward matching packets
18240	to. An empty IP address is acceptable, in which case the NAT engine will forward
18241	packets to the first DHCP lease (x.x.x.15).</desc>
18242	</param>
18243	<param name="guestPort" type="unsigned short" dir="in">
18244	<desc>The port number to forward.</desc>
18245	</param>
18246	</method>
18247	<method name="removeRedirect">
18248	<desc>Removes a port-forwarding rule that was previously registered.</desc>
18249	<param name="name" type="wstring" dir="in">
18250	<desc>The name of the rule to delete.</desc>
18251	</param>
18252	</method>
18253	</interface>
18254
18255	<!--
18256	// IExtPackManager
18257	/////////////////////////////////////////////////////////////////////////
18258	-->
18259
18260	<interface
18261	name="IExtPackPlugIn" extends="$unknown"
18262	uuid="58000040-e718-4746-bbce-4b86d96da461"
18263	wsmap="suppress"
18264	>
18265	<desc>
18266	Interface for keeping information about a plug-in that ships with an
18267	extension pack.
18268	</desc>
18269	<attribute name="name" type="wstring" readonly="yes">
18270	<desc>The plug-in name.</desc>
18271	</attribute>
18272	<attribute name="description" type="wstring" readonly="yes">
18273	<desc>The plug-in description.</desc>
18274	</attribute>
18275	<attribute name="frontend" type="wstring" readonly="yes">
18276	<desc>
18277	The name of the frontend or component name this plug-in plugs into.
18278	</desc>
18279	</attribute>
18280	<attribute name="modulePath" type="wstring" readonly="yes">
18281	<desc> The module path. </desc>
18282	</attribute>
18283	</interface>
18284
18285	<interface
18286	name="IExtPackBase" extends="$unknown"
18287	uuid="f79b75d8-2890-4f34-ffff-ffffa144e82c"
18288	wsmap="suppress"
18289	>
18290	<desc>
18291	Interface for querying information about an extension pack as well as
18292	accessing COM objects within it.
18293	</desc>
18294	<attribute name="name" type="wstring" readonly="yes">
18295	<desc>The extension pack name. This is unique.</desc>
18296	</attribute>
18297	<attribute name="description" type="wstring" readonly="yes">
18298	<desc>The extension pack description.</desc>
18299	</attribute>
18300	<attribute name="version" type="wstring" readonly="yes">
18301	<desc>
18302	The extension pack version string. This is restricted to the dotted
18303	version number and optionally a build indicator. No tree revision or
18304	tag will be included in the string as those things are available as
18305	separate properties. An optional publisher tag may be present like for
18306	<link to="IVirtualBox::version"/>.
18307
18308	Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2".
18309	</desc>
18310	</attribute>
18311	<attribute name="revision" type="unsigned long" readonly="yes">
18312	<desc>The extension pack internal revision number.</desc>
18313	</attribute>
18314	<attribute name="edition" type="wstring" readonly="yes">
18315	<desc>
18316	Edition indicator. This is usually empty.
18317
18318	Can for instance be used to help distinguishing between two editions
18319	of the same extension pack where only the license, service contract or
18320	something differs.
18321	</desc>
18322	</attribute>
18323	<attribute name="VRDEModule" type="wstring" readonly="yes">
18324	<desc>The name of the VRDE module if the extension pack sports one.</desc>
18325	</attribute>
18326	<attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes">
18327	<desc>Plug-ins provided by this extension pack.</desc>
18328	</attribute>
18329	<attribute name="usable" type="boolean" readonly="yes">
18330	<desc>
18331	Indicates whether the extension pack is usable or not.
18332
18333	There are a number of reasons why an extension pack might be unusable,
18334	typical examples would be broken installation/file or that it is
18335	incompatible with the current VirtualBox version.
18336	</desc>
18337	</attribute>
18338	<attribute name="whyUnusable" type="wstring" readonly="yes">
18339	<desc>
18340	String indicating why the extension pack is not usable. This is an
18341	empty string if usable and always a non-empty string if not usable.
18342	</desc>
18343	</attribute>
18344	<attribute name="showLicense" type="boolean" readonly="yes">
18345	<desc>Whether to show the license before installation</desc>
18346	</attribute>
18347	<attribute name="license" type="wstring" readonly="yes">
18348	<desc>
18349	The default HTML license text for the extension pack. Same as
18350	calling <link to="#queryLicense">queryLicense</link> with
18351	preferredLocale and preferredLanguage as empty strings and format set
18352	to html.
18353	</desc>
18354	</attribute>
18355
18356	<method name="queryLicense">
18357	<desc>
18358	Full feature version of the license attribute.
18359	</desc>
18360	<param name="preferredLocale" type="wstring" dir="in">
18361	<desc>
18362	The preferred license locale. Pass an empty string to get the default
18363	license.
18364	</desc>
18365	</param>
18366	<param name="preferredLanguage" type="wstring" dir="in">
18367	<desc>
18368	The preferred license language. Pass an empty string to get the
18369	default language for the locale.
18370	</desc>
18371	</param>
18372	<param name="format" type="wstring" dir="in">
18373	<desc>
18374	The license format: html, rtf or txt. If a license is present there
18375	will always be an HTML of it, the rich text format (RTF) and plain
18376	text (txt) versions are optional. If
18377	</desc>
18378	</param>
18379	<param name="licenseText" type="wstring" dir="return">
18380	<desc>The license text.</desc>
18381	</param>
18382	</method>
18383
18384	</interface>
18385
18386	<interface
18387	name="IExtPack" extends="IExtPackBase"
18388	uuid="431685da-3618-4ebc-b038-833ba829b4b2"
18389	wsmap="suppress"
18390	>
18391	<desc>
18392	Interface for querying information about an extension pack as well as
18393	accessing COM objects within it.
18394	</desc>
18395	<method name="queryObject">
18396	<desc>
18397	Queries the IUnknown interface to an object in the extension pack
18398	main module. This allows plug-ins and others to talk directly to an
18399	extension pack.
18400	</desc>
18401	<param name="objUuid" type="wstring" dir="in">
18402	<desc>The object ID. What exactly this is </desc>
18403	</param>
18404	<param name="returnInterface" type="$unknown" dir="return">
18405	<desc>The queried interface.</desc>
18406	</param>
18407	</method>
18408	</interface>
18409
18410	<interface
18411	name="IExtPackFile" extends="IExtPackBase"
18412	uuid="b6b49f55-efcc-4f08-b486-56e8d8afb10b"
18413	wsmap="suppress"
18414	>
18415	<desc>
18416	Extension pack file (aka tarball, .vbox-extpack) representation returned
18417	by <link to="IExtPackManager::openExtPackFile"/>. This provides the base
18418	extension pack information with the addition of the file name.
18419	</desc>
18420	<attribute name="filePath" type="wstring" readonly="yes">
18421	<desc>
18422	The path to the extension pack file.
18423	</desc>
18424	</attribute>
18425
18426	<method name="install">
18427	<desc>
18428	Install the extension pack.
18429	</desc>
18430	<param name="replace" type="boolean" dir="in">
18431	<desc>
18432	Set this to automatically uninstall any existing extension pack with
18433	the same name as the one being installed.
18434	</desc>
18435	</param>
18436	<param name="displayInfo" type="wstring" dir="in">
18437	<desc>
18438	Platform specific display information. Reserved for future hacks.
18439	</desc>
18440	</param>
18441	<param name="progess" type="IProgress" dir="return">
18442	<desc>
18443	Progress object for the operation.
18444	</desc>
18445	</param>
18446	</method>
18447	</interface>
18448
18449	<interface
18450	name="IExtPackManager" extends="$unknown"
18451	uuid="3295e6ce-b051-47b2-9514-2c588bfe7554"
18452	wsmap="suppress"
18453	>
18454	<desc>
18455	Interface for managing VirtualBox Extension Packs.
18456
18457	TODO: Describe extension packs, how they are managed and how to create
18458	one.
18459	</desc>
18460
18461	<attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
18462	<desc>
18463	List of the installed extension packs.
18464	</desc>
18465	</attribute>
18466
18467	<method name="find">
18468	<desc>
18469	Returns the extension pack with the specified name if found.
18470
18471	<result name="VBOX_E_OBJECT_NOT_FOUND">
18472	No extension pack matching @a name was found.
18473	</result>
18474	</desc>
18475	<param name="name" type="wstring" dir="in">
18476	<desc>The name of the extension pack to locate.</desc>
18477	</param>
18478	<param name="returnData" type="IExtPack" dir="return">
18479	<desc>The extension pack if found.</desc>
18480	</param>
18481	</method>
18482
18483	<method name="openExtPackFile">
18484	<desc>
18485	Attempts to open an extension pack file in preparation for
18486	installation.
18487	</desc>
18488	<param name="path" type="wstring" dir="in">
18489	<desc>The path of the extension pack tarball. This can optionally be
18490	followed by a "::SHA-256=hex-digit" of the tarball. </desc>
18491	</param>
18492	<param name="file" type="IExtPackFile" dir="return">
18493	<desc>The interface of the extension pack file object.</desc>
18494	</param>
18495	</method>
18496
18497	<method name="uninstall">
18498	<desc>Uninstalls an extension pack, removing all related files.</desc>
18499	<param name="name" type="wstring" dir="in">
18500	<desc>The name of the extension pack to uninstall.</desc>
18501	</param>
18502	<param name="forcedRemoval" type="boolean" dir="in">
18503	<desc>
18504	Forced removal of the extension pack. This means that the uninstall
18505	hook will not be called.
18506	</desc>
18507	</param>
18508	<param name="displayInfo" type="wstring" dir="in">
18509	<desc>
18510	Platform specific display information. Reserved for future hacks.
18511	</desc>
18512	</param>
18513	<param name="progess" type="IProgress" dir="return">
18514	<desc>
18515	Progress object for the operation.
18516	</desc>
18517	</param>
18518	</method>
18519
18520	<method name="cleanup">
18521	<desc>Cleans up failed installs and uninstalls</desc>
18522	</method>
18523
18524	<method name="queryAllPlugInsForFrontend">
18525	<desc>
18526	Gets the path to all the plug-in modules for a given frontend.
18527
18528	This is a convenience method that is intended to simplify the plug-in
18529	loading process for a frontend.
18530	</desc>
18531	<param name="frontendName" type="wstring" dir="in">
18532	<desc>The name of the frontend or component.</desc>
18533	</param>
18534	<param name="plugInModules" type="wstring" dir="return" safearray="yes">
18535	<desc>Array containing the plug-in modules (full paths).</desc>
18536	</param>
18537	</method>
18538
18539	<method name="isExtPackUsable">
18540	<desc>Check if the given extension pack is loaded and usable.</desc>
18541	<param name="name" type="wstring" dir="in">
18542	<desc>The name of the extension pack to check for.</desc>
18543	</param>
18544	<param name="usable" type="boolean" dir="return">
18545	<desc>Is the given extension pack loaded and usable.</desc>
18546	</param>
18547	</method>
18548
18549	</interface>
18550
18551	<!--
18552	// BandwidthGroupType
18553	/////////////////////////////////////////////////////////////////////////
18554	-->
18555	<enum
18556	name="BandwidthGroupType"
18557	uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e">
18558
18559	<desc>
18560	Type of a bandwidth control group.
18561	</desc>
18562
18563	<const name="Null" value="0">
18564	<desc>
18565	Null type, must be first.
18566	</desc>
18567	</const>
18568
18569	<const name="Disk" value="1">
18570	<desc>
18571	The bandwidth group controls disk I/O.
18572	</desc>
18573	</const>
18574
18575	<const name="Network" value="2">
18576	<desc>
18577	The bandwidth group controls network I/O.
18578	</desc>
18579	</const>
18580
18581	</enum>
18582
18583	<!--
18584	// IBandwidthGroup
18585	/////////////////////////////////////////////////////////////////////////
18586	-->
18587	<interface
18588	name="IBandwidthGroup" extends="$unknown"
18589	uuid="badea2d7-0261-4146-89f0-6a57cc34833d"
18590	wsmap="managed"
18591	>
18592	<desc>Represents one bandwidth group.</desc>
18593
18594	<attribute name="name" type="wstring" readonly="yes">
18595	<desc>Name of the group.</desc>
18596	</attribute>
18597
18598	<attribute name="type" type="BandwidthGroupType" readonly="yes">
18599	<desc>Type of the group.</desc>
18600	</attribute>
18601
18602	<attribute name="reference" type="unsigned long" readonly="yes">
18603	<desc>How many devices/medium attachements use this group.</desc>
18604	</attribute>
18605
18606	<attribute name="maxBytesPerSec" type="long long">
18607	<desc>The maximum number of bytes which can be transfered by all
18608	entities attached to this group during one second.</desc>
18609	</attribute>
18610
18611	</interface>
18612
18613	<!--
18614	// IBandwidthControl
18615	/////////////////////////////////////////////////////////////////////////
18616	-->
18617	<interface
18618	name="IBandwidthControl" extends="$unknown"
18619	uuid="e2eb3930-d2f4-4f87-be17-0707e30f019f"
18620	wsmap="managed"
18621	>
18622	<desc>
18623	Controls the bandwidth groups of one machine used to cap I/O done by a VM.
18624	This includes network and disk I/O.
18625	</desc>
18626
18627	<attribute name="numGroups" type="unsigned long" readonly="yes">
18628	<desc>
18629	The current number of existing bandwidth groups managed.
18630	</desc>
18631	</attribute>
18632
18633	<method name="createBandwidthGroup">
18634	<desc>
18635	Creates a new bandwidth group.
18636	</desc>
18637
18638	<param name="name" type="wstring" dir="in">
18639	<desc>Name of the bandwidth group.</desc>
18640	</param>
18641	<param name="type" type="BandwidthGroupType" dir="in">
18642	<desc>The type of the bandwidth group (network or disk).</desc>
18643	</param>
18644	<param name="maxBytesPerSec" type="long long" dir="in">
18645	<desc>The maximum number of bytes which can be transfered by all
18646	entities attached to this group during one second.</desc>
18647	</param>
18648	</method>
18649
18650	<method name="deleteBandwidthGroup">
18651	<desc>
18652	Deletes a new bandwidth group.
18653	</desc>
18654
18655	<param name="name" type="wstring" dir="in">
18656	<desc>Name of the bandwidth group to delete.</desc>
18657	</param>
18658	</method>
18659
18660	<method name="getBandwidthGroup" const="yes">
18661	<desc>
18662	Get a bandwidth group by name.
18663	</desc>
18664
18665	<param name="name" type="wstring" dir="in">
18666	<desc>Name of the bandwidth group to get.</desc>
18667	</param>
18668	<param name="bandwidthGroup" type="IBandwidthGroup" dir="return">
18669	<desc>Where to store the bandwidth group on success.</desc>
18670	</param>
18671	</method>
18672
18673	<method name="getAllBandwidthGroups" const="yes">
18674	<desc>
18675	Get all managed bandwidth groups.
18676	</desc>
18677
18678	<param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes">
18679	<desc>The array of managed bandwidth groups.</desc>
18680	</param>
18681	</method>
18682	</interface>
18683
18684	<!--
18685	// IVirtualBoxClient
18686	/////////////////////////////////////////////////////////////////////////
18687	-->
18688
18689	<interface
18690	name="IVirtualBoxClient" extends="$unknown"
18691	uuid="d191281f-b0cb-4d83-a8fa-0d9fd6ba234c"
18692	wsmap="suppress"
18693	>
18694	<desc>
18695	Convenience interface for client applications. Treat this as a
18696	singleton, i.e. never create more than one instance of this interface.
18697
18698	At the moment only available for clients of the local API (not usable
18699	via the webservice). Once the session logic is redesigned this might
18700	change.
18701	</desc>
18702
18703	<attribute name="virtualBox" type="IVirtualBox" readonly="yes">
18704	<desc>
18705	Reference to the server-side API root object.
18706	</desc>
18707	</attribute>
18708
18709	<attribute name="session" type="ISession" readonly="yes">
18710	<desc>
18711	Create a new session object and return the reference to it.
18712	</desc>
18713	</attribute>
18714
18715	<attribute name="eventSource" type="IEventSource" readonly="yes">
18716	<desc>
18717	Event source for VirtualBoxClient events.
18718	</desc>
18719	</attribute>
18720
18721	<method name="checkMachineError">
18722	<desc>
18723	Perform error checking before using an <link to="IMachine"/> object.
18724	Generally useful before starting a VM and all other uses. If anything
18725	is not as it should be then this method will return an appropriate
18726	error.
18727	</desc>
18728
18729	<param name="machine" type="IMachine" dir="in">
18730	<desc>The machine object to check.</desc>
18731	</param>
18732	</method>
18733	</interface>
18734
18735	<!--
18736	// Events
18737	/////////////////////////////////////////////////////////////////////////
18738	-->
18739	<enum
18740	name="VBoxEventType"
18741	uuid="c51645b3-7108-4dce-b5a3-bbf5e4f69ed2"
18742	>
18743
18744	<desc>
18745	Type of an event.
18746	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
18747	</desc>
18748
18749	<const name="Invalid" value="0">
18750	<desc>
18751	Invalid event, must be first.
18752	</desc>
18753	</const>
18754
18755	<const name="Any" value="1">
18756	<desc>
18757	Wildcard for all events.
18758	Events of this type are never delivered, and only used in
18759	<link to="IEventSource::registerListener"/> call to simplify registration.
18760	</desc>
18761	</const>
18762
18763	<const name="Vetoable" value="2">
18764	<desc>
18765	Wildcard for all vetoable events. Events of this type are never delivered, and only
18766	used in <link to="IEventSource::registerListener"/> call to simplify registration.
18767	</desc>
18768	</const>
18769
18770	<const name="MachineEvent" value="3">
18771	<desc>
18772	Wildcard for all machine events. Events of this type are never delivered, and only used in
18773	<link to="IEventSource::registerListener"/> call to simplify registration.
18774	</desc>
18775	</const>
18776
18777	<const name="SnapshotEvent" value="4">
18778	<desc>
18779	Wildcard for all snapshot events. Events of this type are never delivered, and only used in
18780	<link to="IEventSource::registerListener"/> call to simplify registration.
18781	</desc>
18782	</const>
18783
18784	<const name="InputEvent" value="5">
18785	<desc>
18786	Wildcard for all input device (keyboard, mouse) events.
18787	Events of this type are never delivered, and only used in
18788	<link to="IEventSource::registerListener"/> call to simplify registration.
18789	</desc>
18790	</const>
18791
18792	<const name="LastWildcard" value="31">
18793	<desc>
18794	Last wildcard.
18795	</desc>
18796	</const>
18797
18798	<const name="OnMachineStateChanged" value="32">
18799	<desc>
18800	See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
18801	</desc>
18802	</const>
18803	<const name="OnMachineDataChanged" value="33">
18804	<desc>
18805	See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
18806	</desc>
18807	</const>
18808	<const name="OnExtraDataChanged" value="34">
18809	<desc>
18810	See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
18811	</desc>
18812	</const>
18813	<const name="OnExtraDataCanChange" value="35">
18814	<desc>
18815	See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
18816	</desc>
18817	</const>
18818	<const name="OnMediumRegistered" value="36">
18819	<desc>
18820	See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
18821	</desc>
18822	</const>
18823	<const name="OnMachineRegistered" value="37">
18824	<desc>
18825	See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
18826	</desc>
18827	</const>
18828	<const name="OnSessionStateChanged" value="38">
18829	<desc>
18830	See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
18831	</desc>
18832	</const>
18833	<const name="OnSnapshotTaken" value="39">
18834	<desc>
18835	See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
18836	</desc>
18837	</const>
18838	<const name="OnSnapshotDeleted" value="40">
18839	<desc>
18840	See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
18841	</desc>
18842	</const>
18843	<const name="OnSnapshotChanged" value="41">
18844	<desc>
18845	See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
18846	</desc>
18847	</const>
18848	<const name="OnGuestPropertyChanged" value="42">
18849	<desc>
18850	See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
18851	</desc>
18852	</const>
18853	<!-- Console events -->
18854	<const name="OnMousePointerShapeChanged" value="43">
18855	<desc>
18856	See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
18857	</desc>
18858	</const>
18859	<const name="OnMouseCapabilityChanged" value="44">
18860	<desc>
18861	See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
18862	</desc>
18863	</const>
18864	<const name="OnKeyboardLedsChanged" value="45">
18865	<desc>
18866	See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
18867	</desc>
18868	</const>
18869	<const name="OnStateChanged" value="46">
18870	<desc>
18871	See <link to="IStateChangedEvent">IStateChangedEvent</link>.
18872	</desc>
18873	</const>
18874	<const name="OnAdditionsStateChanged" value="47">
18875	<desc>
18876	See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
18877	</desc>
18878	</const>
18879	<const name="OnNetworkAdapterChanged" value="48">
18880	<desc>
18881	See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
18882	</desc>
18883	</const>
18884	<const name="OnSerialPortChanged" value="49">
18885	<desc>
18886	See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
18887	</desc>
18888	</const>
18889	<const name="OnParallelPortChanged" value="50">
18890	<desc>
18891	See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
18892	</desc>
18893	</const>
18894	<const name="OnStorageControllerChanged" value="51">
18895	<desc>
18896	See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
18897	</desc>
18898	</const>
18899	<const name="OnMediumChanged" value="52">
18900	<desc>
18901	See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
18902	</desc>
18903	</const>
18904	<const name="OnVRDEServerChanged" value="53">
18905	<desc>
18906	See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
18907	</desc>
18908	</const>
18909	<const name="OnUSBControllerChanged" value="54">
18910	<desc>
18911	See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
18912	</desc>
18913	</const>
18914	<const name="OnUSBDeviceStateChanged" value="55">
18915	<desc>
18916	See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
18917	</desc>
18918	</const>
18919	<const name="OnSharedFolderChanged" value="56">
18920	<desc>
18921	See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
18922	</desc>
18923	</const>
18924	<const name="OnRuntimeError" value="57">
18925	<desc>
18926	See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
18927	</desc>
18928	</const>
18929	<const name="OnCanShowWindow" value="58">
18930	<desc>
18931	See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
18932	</desc>
18933	</const>
18934	<const name="OnShowWindow" value="59">
18935	<desc>
18936	See <link to="IShowWindowEvent">IShowWindowEvent</link>.
18937	</desc>
18938	</const>
18939	<const name="OnCPUChanged" value="60">
18940	<desc>
18941	See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
18942	</desc>
18943	</const>
18944	<const name="OnVRDEServerInfoChanged" value="61">
18945	<desc>
18946	See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
18947	</desc>
18948	</const>
18949	<const name="OnEventSourceChanged" value="62">
18950	<desc>
18951	See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
18952	</desc>
18953	</const>
18954	<const name="OnCPUExecutionCapChanged" value="63">
18955	<desc>
18956	See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
18957	</desc>
18958	</const>
18959	<const name="OnGuestKeyboard" value="64">
18960	<desc>
18961	See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
18962	</desc>
18963	</const>
18964	<const name="OnGuestMouse" value="65">
18965	<desc>
18966	See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
18967	</desc>
18968	</const>
18969	<const name="OnNATRedirect" value="66">
18970	<desc>
18971	See <link to="INATRedirectEvent">INATRedirectEvent</link>.
18972	</desc>
18973	</const>
18974	<const name="OnHostPCIDevicePlug" value="67">
18975	<desc>
18976	See <link to="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link>.
18977	</desc>
18978	</const>
18979	<const name="OnVBoxSVCAvailabilityChanged" value="68">
18980	<desc>
18981	See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>.
18982	</desc>
18983	</const>
18984	<const name="OnBandwidthGroupChanged" value="69">
18985	<desc>
18986	See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>.
18987	</desc>
18988	</const>
18989	<const name="OnGuestMonitorChanged" value="70">
18990	<desc>
18991	See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>.
18992	</desc>
18993	</const>
18994	<const name="OnStorageDeviceChanged" value="71">
18995	<desc>
18996	See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>.
18997	</desc>
18998	</const>
18999	<const name="OnClipboardModeChanged" value="72">
19000	<desc>
19001	See <link to="IClipboardModeChangedEvent">IClipboardModeChangedEvent</link>.
19002	</desc>
19003	</const>
19004	<const name="OnDragAndDropModeChanged" value="73">
19005	<desc>
19006	See <link to="IDragAndDropModeChangedEvent">IDragAndDropModeChangedEvent</link>.
19007	</desc>
19008	</const>
19009	<const name="OnNATNetworkChanged" value="74">
19010	<desc>
19011	See <link to="INATNetworkChangedEvent">INATNetworkChangedEvent</link>.
19012	</desc>
19013	</const>
19014	<const name="OnNATNetworkStartStop" value="75">
19015	<desc>
19016	See <link to="INATNetworkStartStopEvent">INATNetworkStartStopEvent</link>.
19017	</desc>
19018	</const>
19019	<const name="OnNATNetworkAlter" value="76">
19020	<desc>
19021	See <link to="INATNetworkAlterEvent">INATNetworkAlterEvent</link>.
19022	</desc>
19023	</const>
19024	<const name="OnNATNetworkCreationDeletion" value="77">
19025	<desc>
19026	See <link to="INATNetworkCreationDeletionEvent">INATNetworkCreationDeletionEvent</link>.
19027	</desc>
19028	</const>
19029	<const name="OnNATNetworkSetting" value="78">
19030	<desc>
19031	See <link to="INATNetworkSettingEvent">INATNetworkSettingEvent</link>.
19032	</desc>
19033	</const>
19034	<const name="OnNATNetworkPortForward" value="79">
19035	<desc>
19036	See <link to="INATNetworkPortForwardEvent">INATNetworkPortForwardEvent</link>.
19037	</desc>
19038	</const>
19039	<const name="OnGuestSessionStateChanged" value="80">
19040	<desc>
19041	See <link to="IGuestSessionStateChangedEvent">IGuestSessionStateChangedEvent</link>.
19042	</desc>
19043	</const>
19044	<const name="OnGuestSessionRegistered" value="81">
19045	<desc>
19046	See <link to="IGuestSessionRegisteredEvent">IGuestSessionRegisteredEvent</link>.
19047	</desc>
19048	</const>
19049	<const name="OnGuestProcessRegistered" value="82">
19050	<desc>
19051	See <link to="IGuestProcessRegisteredEvent">IGuestProcessRegisteredEvent</link>.
19052	</desc>
19053	</const>
19054	<const name="OnGuestProcessStateChanged" value="83">
19055	<desc>
19056	See <link to="IGuestProcessStateChangedEvent">IGuestProcessStateChangedEvent</link>.
19057	</desc>
19058	</const>
19059	<const name="OnGuestProcessInputNotify" value="84">
19060	<desc>
19061	See <link to="IGuestProcessInputNotifyEvent">IGuestProcessInputNotifyEvent</link>.
19062	</desc>
19063	</const>
19064	<const name="OnGuestProcessOutput" value="85">
19065	<desc>
19066	See <link to="IGuestProcessOutputEvent">IGuestProcessOutputEvent</link>.
19067	</desc>
19068	</const>
19069	<const name="OnGuestFileRegistered" value="86">
19070	<desc>
19071	See <link to="IGuestFileRegisteredEvent">IGuestFileRegisteredEvent</link>.
19072	</desc>
19073	</const>
19074	<const name="OnGuestFileStateChanged" value="87">
19075	<desc>
19076	See <link to="IGuestFileStateChangedEvent">IGuestFileStateChangedEvent</link>.
19077	</desc>
19078	</const>
19079	<const name="OnGuestFileOffsetChanged" value="88">
19080	<desc>
19081	See <link to="IGuestFileOffsetChangedEvent">IGuestFileOffsetChangedEvent</link>.
19082	</desc>
19083	</const>
19084	<const name="OnGuestFileRead" value="89">
19085	<desc>
19086	See <link to="IGuestFileReadEvent">IGuestFileReadEvent</link>.
19087
19088	<note internal="yes">For performance reasons this is a separate event to
19089	not unnecessarily overflow the event queue.</note>
19090	</desc>
19091	</const>
19092	<const name="OnGuestFileWrite" value="90">
19093	<desc>
19094	See <link to="IGuestFileWriteEvent">IGuestFileWriteEvent</link>.
19095
19096	<note internal="yes">For performance reasons this is a separate event to
19097	not unnecessarily overflow the event queue.</note>
19098	</desc>
19099	</const>
19100	<!-- Last event marker -->
19101	<const name="Last" value="91">
19102	<desc>
19103	Must be last event, used for iterations and structures relying on numerical event values.
19104	</desc>
19105	</const>
19106
19107	</enum>
19108
19109	<interface
19110	name="IEventSource" extends="$unknown"
19111	uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
19112	wsmap="managed"
19113	>
19114	<desc>
19115	Event source. Generally, any object which could generate events can be an event source,
19116	or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
19117	an event source can work with listeners in either active or passive mode. In active mode it is up to
19118	the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
19119	event source keeps track of pending events for each listener and returns available events on demand.
19120
19121	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19122	</desc>
19123
19124	<method name="createListener">
19125	<desc>
19126	Creates a new listener object, useful for passive mode.
19127	</desc>
19128	<param name="listener" type="IEventListener" dir="return"/>
19129	</method>
19130
19131	<method name="createAggregator">
19132	<desc>
19133	Creates an aggregator event source, collecting events from multiple sources.
19134	This way a single listener can listen for events coming from multiple sources,
19135	using a single blocking <link to="#getEvent"/> on the returned aggregator.
19136	</desc>
19137	<param name="subordinates" type="IEventSource" dir="in" safearray="yes">
19138	<desc>
19139	Subordinate event source this one aggregatres.
19140	</desc>
19141	</param>
19142	<param name="result" type="IEventSource" dir="return">
19143	<desc>
19144	Event source aggregating passed sources.
19145	</desc>
19146	</param>
19147	</method>
19148
19149	<method name="registerListener">
19150	<desc>
19151	Register an event listener.
19152
19153	<note>
19154	To avoid system overload, the VirtualBox server process checks if passive event
19155	listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
19156	current implementation, if more than 500 pending events are detected for a passive
19157	event listener, it is forcefully unregistered by the system, and further
19158	<link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
19159	</note>
19160	</desc>
19161	<param name="listener" type="IEventListener" dir="in">
19162	<desc>Listener to register.</desc>
19163	</param>
19164	<param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
19165	<desc>
19166	Event types listener is interested in. One can use wildcards like -
19167	<link to="VBoxEventType_Any"/> to specify wildcards, matching more
19168	than one event.
19169	</desc>
19170	</param>
19171	<param name="active" type="boolean" dir="in">
19172	<desc>
19173	Which mode this listener is operating in.
19174	In active mode, <link to="IEventListener::handleEvent" /> is called directly.
19175	In passive mode, an internal event queue is created for this this IEventListener.
19176	For each event coming in, it is added to queues for all interested registered passive
19177	listeners. It is then up to the external code to call the listener's
19178	<link to="IEventListener::handleEvent" /> method. When done with an event, the
19179	external code must call <link to="#eventProcessed" />.
19180	</desc>
19181	</param>
19182	</method>
19183
19184	<method name="unregisterListener">
19185	<desc>
19186	Unregister an event listener. If listener is passive, and some waitable events are still
19187	in queue they are marked as processed automatically.
19188	</desc>
19189	<param name="listener" type="IEventListener" dir="in">
19190	<desc>Listener to unregister.</desc>
19191	</param>
19192	</method>
19193
19194	<method name="fireEvent">
19195	<desc>
19196	Fire an event for this source.
19197	</desc>
19198	<param name="event" type="IEvent" dir="in">
19199	<desc>Event to deliver.</desc>
19200	</param>
19201	<param name="timeout" type="long" dir="in">
19202	<desc>
19203	Maximum time to wait for event processing (if event is waitable), in ms;
19204	0 = no wait, -1 = indefinite wait.
19205	</desc>
19206	</param>
19207	<param name="result" type="boolean" dir="return">
19208	<desc>true if an event was delivered to all targets, or is non-waitable.</desc>
19209	</param>
19210	</method>
19211
19212	<method name="getEvent">
19213	<desc>
19214	Get events from this peer's event queue (for passive mode). Calling this method
19215	regularly is required for passive event listeners to avoid system overload;
19216	see <link to="IEventSource::registerListener" /> for details.
19217
19218	<result name="VBOX_E_OBJECT_NOT_FOUND">
19219	Listener is not registered, or autounregistered.
19220	</result>
19221	</desc>
19222	<param name="listener" type="IEventListener" dir="in">
19223	<desc>Which listener to get data for.</desc>
19224	</param>
19225	<param name="timeout" type="long" dir="in">
19226	<desc>
19227	Maximum time to wait for events, in ms;
19228	0 = no wait, -1 = indefinite wait.
19229	</desc>
19230	</param>
19231	<param name="event" type="IEvent" dir="return">
19232	<desc>Event retrieved, or null if none available.</desc>
19233	</param>
19234	</method>
19235
19236	<method name="eventProcessed">
19237	<desc>
19238	Must be called for waitable events after a particular listener finished its
19239	event processing. When all listeners of a particular event have called this
19240	method, the system will then call <link to="IEvent::setProcessed" />.
19241	</desc>
19242	<param name="listener" type="IEventListener" dir="in">
19243	<desc>Which listener processed event.</desc>
19244	</param>
19245	<param name="event" type="IEvent" dir="in">
19246	<desc>Which event.</desc>
19247	</param>
19248	</method>
19249
19250	</interface>
19251
19252	<interface
19253	name="IEventListener" extends="$unknown"
19254	uuid="67099191-32e7-4f6c-85ee-422304c71b90"
19255	wsmap="managed"
19256	>
19257	<desc>
19258	Event listener. An event listener can work in either active or passive mode, depending on the way
19259	it was registered.
19260	See <link to="IEvent" /> for an introduction to VirtualBox event handling.
19261	</desc>
19262
19263	<method name="handleEvent">
19264	<desc>
19265	Handle event callback for active listeners. It is not called for
19266	passive listeners. After calling <link to="#handleEvent"/> on all active listeners
19267	and having received acknowledgement from all passive listeners via
19268	<link to="IEventSource::eventProcessed"/>, the event is marked as
19269	processed and <link to="IEvent::waitProcessed"/> will return
19270	immediately.
19271	</desc>
19272	<param name="event" type="IEvent" dir="in">
19273	<desc>Event available.</desc>
19274	</param>
19275	</method>
19276
19277	</interface>
19278
19279	<interface
19280	name="IEvent" extends="$unknown"
19281	uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
19282	wsmap="managed"
19283	>
19284	<desc>
19285	Abstract parent interface for VirtualBox events. Actual events will typically implement
19286	a more specific interface which derives from this (see below).
19287
19288	<b>Introduction to VirtualBox events</b>
19289
19290	Generally speaking, an event (represented by this interface) signals that something
19291	happened, while an event listener (see <link to="IEventListener" />) represents an
19292	entity that is interested in certain events. In order for this to work with
19293	unidirectional protocols (i.e. web services), the concepts of passive and active
19294	listener are used.
19295
19296	Event consumers can register themselves as listeners, providing an array of
19297	events they are interested in (see <link to="IEventSource::registerListener" />).
19298	When an event triggers, the listener is notified about the event. The exact
19299	mechanism of the notification depends on whether the listener was registered as
19300	an active or passive listener:
19301
19302	<ul>
19303	<li>An active listener is very similar to a callback: it is a function invoked
19304	by the API. As opposed to the callbacks that were used in the API before
19305	VirtualBox 4.0 however, events are now objects with an interface hierarchy.
19306	</li>
19307
19308	<li>Passive listeners are somewhat trickier to implement, but do not require
19309	a client function to be callable, which is not an option with scripting
19310	languages or web service clients. Internally the <link to="IEventSource" />
19311	implementation maintains an event queue for each passive listener, and
19312	newly arrived events are put in this queue. When the listener calls
19313	<link to="IEventSource::getEvent"/>, first element from its internal event
19314	queue is returned. When the client completes processing of an event,
19315	the <link to="IEventSource::eventProcessed" /> function must be called,
19316	acknowledging that the event was processed. It supports implementing
19317	waitable events. On passive listener unregistration, all events from its
19318	queue are auto-acknowledged.
19319	</li>
19320	</ul>
19321
19322	Waitable events are useful in situations where the event generator wants to track
19323	delivery or a party wants to wait until all listeners have completed the event. A
19324	typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
19325	listeners might veto a certain action, and thus the event producer has to make
19326	sure that all listeners have processed the event and not vetoed before taking
19327	the action.
19328
19329	A given event may have both passive and active listeners at the same time.
19330
19331	<b>Using events</b>
19332
19333	Any VirtualBox object capable of producing externally visible events provides an
19334	@c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
19335	This event source object is notified by VirtualBox once something has happened, so
19336	consumers may register event listeners with this event source. To register a listener,
19337	an object implementing the <link to="IEventListener" /> interface must be provided.
19338	For active listeners, such an object is typically created by the consumer, while for
19339	passive listeners <link to="IEventSource::createListener" /> should be used. Please
19340	note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener.
19341
19342	Once created, the listener must be registered to listen for the desired events
19343	(see <link to="IEventSource::registerListener" />), providing an array of
19344	<link to="VBoxEventType" /> enums. Those elements can either be the individual
19345	event IDs or wildcards matching multiple event IDs.
19346
19347	After registration, the callback's <link to="IEventListener::handleEvent" /> method is
19348	called automatically when the event is triggered, while passive listeners have to call
19349	<link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
19350	an event processing loop.
19351
19352	The IEvent interface is an abstract parent interface for all such VirtualBox events
19353	coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
19354	or the event processing loop is to check the <link to="#type" /> attribute of the event and
19355	then cast to the appropriate specific interface using @c QueryInterface().
19356	</desc>
19357
19358	<attribute name="type" readonly="yes" type="VBoxEventType">
19359	<desc>
19360	Event type.
19361	</desc>
19362	</attribute>
19363
19364	<attribute name="source" readonly="yes" type="IEventSource">
19365	<desc>
19366	Source of this event.
19367	</desc>
19368	</attribute>
19369
19370	<attribute name="waitable" readonly="yes" type="boolean">
19371	<desc>
19372	If we can wait for this event being processed. If false, <link to="#waitProcessed"/> returns immediately,
19373	and <link to="#setProcessed"/> doesn't make sense. Non-waitable events are generally better performing,
19374	as no additional overhead associated with waitability imposed.
19375	Waitable events are needed when one need to be able to wait for particular event processed,
19376	for example for vetoable changes, or if event refers to some resource which need to be kept immutable
19377	until all consumers confirmed events.
19378	</desc>
19379	</attribute>
19380
19381	<method name="setProcessed">
19382	<desc>
19383	Internal method called by the system when all listeners of a particular event have called
19384	<link to="IEventSource::eventProcessed" />. This should not be called by client code.
19385	</desc>
19386	</method>
19387
19388	<method name="waitProcessed">
19389	<desc>
19390	Wait until time outs, or this event is processed. Event must be waitable for this operation to have
19391	described semantics, for non-waitable returns true immediately.
19392	</desc>
19393	<param name="timeout" type="long" dir="in">
19394	<desc>
19395	Maximum time to wait for event processeing, in ms;
19396	0 = no wait, -1 = indefinite wait.
19397	</desc>
19398	</param>
19399	<param name="result" type="boolean" dir="return">
19400	<desc>If this event was processed before timeout.</desc>
19401	</param>
19402	</method>
19403	</interface>
19404
19405
19406	<interface
19407	name="IReusableEvent" extends="IEvent"
19408	uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
19409	wsmap="managed"
19410	>
19411	<desc>Base abstract interface for all reusable events.</desc>
19412
19413	<attribute name="generation" readonly="yes" type="unsigned long">
19414	<desc>Current generation of event, incremented on reuse.</desc>
19415	</attribute>
19416
19417	<method name="reuse">
19418	<desc>
19419	Marks an event as reused, increments 'generation', fields shall no
19420	longer be considered valid.
19421	</desc>
19422	</method>
19423	</interface>
19424
19425	<interface
19426	name="IMachineEvent" extends="IEvent"
19427	uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
19428	wsmap="managed" id="MachineEvent"
19429	>
19430	<desc>Base abstract interface for all machine events.</desc>
19431
19432	<attribute name="machineId" readonly="yes" type="uuid" mod="string">
19433	<desc>ID of the machine this event relates to.</desc>
19434	</attribute>
19435
19436	</interface>
19437
19438	<interface
19439	name="IMachineStateChangedEvent" extends="IMachineEvent"
19440	uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
19441	wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
19442	>
19443	<desc>Machine state change event.</desc>
19444
19445	<attribute name="state" readonly="yes" type="MachineState">
19446	<desc>New execution state.</desc>
19447	</attribute>
19448	</interface>
19449
19450	<interface
19451	name="IMachineDataChangedEvent" extends="IMachineEvent"
19452	uuid="abe94809-2e88-4436-83d7-50f3e64d0503"
19453	wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
19454	>
19455	<desc>
19456	Any of the settings of the given machine has changed.
19457	</desc>
19458
19459	<attribute name="temporary" readonly="yes" type="boolean">
19460	<desc>@c true if the settings change is temporary. All permanent
19461	settings changes will trigger an event, and only temporary settings
19462	changes for running VMs will trigger an event. Note: sending events
19463	for temporary changes is NOT IMPLEMENTED.</desc>
19464	</attribute>
19465	</interface>
19466
19467	<interface
19468	name="IMediumRegisteredEvent" extends="IEvent"
19469	uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
19470	wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
19471	>
19472	<desc>
19473	The given medium was registered or unregistered
19474	within this VirtualBox installation.
19475	</desc>
19476
19477	<attribute name="mediumId" readonly="yes" type="uuid" mod="string">
19478	<desc>ID of the medium this event relates to.</desc>
19479	</attribute>
19480
19481	<attribute name="mediumType" readonly="yes" type="DeviceType">
19482	<desc>Type of the medium this event relates to.</desc>
19483	</attribute>
19484
19485	<attribute name="registered" type="boolean" readonly="yes">
19486	<desc>
19487	If @c true, the medium was registered, otherwise it was
19488	unregistered.
19489	</desc>
19490	</attribute>
19491	</interface>
19492
19493	<interface
19494	name="IMachineRegisteredEvent" extends="IMachineEvent"
19495	uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
19496	wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
19497	>
19498	<desc>
19499	The given machine was registered or unregistered
19500	within this VirtualBox installation.
19501	</desc>
19502
19503	<attribute name="registered" type="boolean" readonly="yes">
19504	<desc>
19505	If @c true, the machine was registered, otherwise it was
19506	unregistered.
19507	</desc>
19508	</attribute>
19509	</interface>
19510
19511	<interface
19512	name="ISessionStateChangedEvent" extends="IMachineEvent"
19513	uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
19514	wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
19515	>
19516	<desc>
19517	The state of the session for the given machine was changed.
19518	<see><link to="IMachine::sessionState"/></see>
19519	</desc>
19520
19521	<attribute name="state" type="SessionState" readonly="yes">
19522	<desc>
19523	New session state.
19524	</desc>
19525	</attribute>
19526	</interface>
19527
19528	<interface
19529	name="IGuestPropertyChangedEvent" extends="IMachineEvent"
19530	uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
19531	wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
19532	>
19533	<desc>
19534	Notification when a guest property has changed.
19535	</desc>
19536
19537	<attribute name="name" readonly="yes" type="wstring">
19538	<desc>
19539	The name of the property that has changed.
19540	</desc>
19541	</attribute>
19542
19543	<attribute name="value" readonly="yes" type="wstring">
19544	<desc>
19545	The new property value.
19546	</desc>
19547	</attribute>
19548
19549	<attribute name="flags" readonly="yes" type="wstring">
19550	<desc>
19551	The new property flags.
19552	</desc>
19553	</attribute>
19554
19555	</interface>
19556
19557	<interface
19558	name="ISnapshotEvent" extends="IMachineEvent"
19559	uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
19560	wsmap="managed" id="SnapshotEvent"
19561	>
19562	<desc>Base interface for all snapshot events.</desc>
19563
19564	<attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
19565	<desc>ID of the snapshot this event relates to.</desc>
19566	</attribute>
19567
19568	</interface>
19569
19570	<interface
19571	name="ISnapshotTakenEvent" extends="ISnapshotEvent"
19572	uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
19573	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
19574	>
19575	<desc>
19576	A new snapshot of the machine has been taken.
19577	<see><link to="ISnapshot"/></see>
19578	</desc>
19579	</interface>
19580
19581	<interface
19582	name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
19583	uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
19584	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
19585	>
19586	<desc>
19587	Snapshot of the given machine has been deleted.
19588
19589	<note>
19590	This notification is delivered <b>after</b> the snapshot
19591	object has been uninitialized on the server (so that any
19592	attempt to call its methods will return an error).
19593	</note>
19594
19595	<see><link to="ISnapshot"/></see>
19596	</desc>
19597	</interface>
19598
19599	<interface
19600	name="ISnapshotChangedEvent" extends="ISnapshotEvent"
19601	uuid="07541941-8079-447a-a33e-47a69c7980db"
19602	wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
19603	>
19604	<desc>
19605	Snapshot properties (name and/or description) have been changed.
19606	<see><link to="ISnapshot"/></see>
19607	</desc>
19608	</interface>
19609
19610	<interface
19611	name="IMousePointerShapeChangedEvent" extends="IEvent"
19612	uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
19613	wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
19614	>
19615	<desc>
19616	Notification when the guest mouse pointer shape has
19617	changed. The new shape data is given.
19618	</desc>
19619
19620	<attribute name="visible" type="boolean" readonly="yes">
19621	<desc>
19622	Flag whether the pointer is visible.
19623	</desc>
19624	</attribute>
19625	<attribute name="alpha" type="boolean" readonly="yes">
19626	<desc>
19627	Flag whether the pointer has an alpha channel.
19628	</desc>
19629	</attribute>
19630	<attribute name="xhot" type="unsigned long" readonly="yes">
19631	<desc>
19632	The pointer hot spot X coordinate.
19633	</desc>
19634	</attribute>
19635	<attribute name="yhot" type="unsigned long" readonly="yes">
19636	<desc>
19637	The pointer hot spot Y coordinate.
19638	</desc>
19639	</attribute>
19640	<attribute name="width" type="unsigned long" readonly="yes">
19641	<desc>
19642	Width of the pointer shape in pixels.
19643	</desc>
19644	</attribute>
19645	<attribute name="height" type="unsigned long" readonly="yes">
19646	<desc>
19647	Height of the pointer shape in pixels.
19648	</desc>
19649	</attribute>
19650	<attribute name="shape" type="octet" safearray="yes" readonly="yes">
19651	<desc>
19652	Shape buffer arrays.
19653
19654	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
19655	followed by a 32-bpp XOR (color) mask.
19656
19657	For pointers without alpha channel the XOR mask pixels are
19658	32-bit values: (lsb)BGR0(msb). For pointers with alpha channel
19659	the XOR mask consists of (lsb)BGRA(msb) 32-bit values.
19660
19661	An AND mask is used for pointers with alpha channel, so if the
19662	callback does not support alpha, the pointer could be
19663	displayed as a normal color pointer.
19664
19665	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
19666	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
19667	height</tt>. The padding bits at the end of each scanline are
19668	undefined.
19669
19670	The XOR mask follows the AND mask on the next 4-byte aligned
19671	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
19672	Bytes in the gap between the AND and the XOR mask are undefined.
19673	The XOR mask scanlines have no gap between them and the size of
19674	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
19675
19676	<note>
19677	If @a shape is 0, only the pointer visibility is changed.
19678	</note>
19679	</desc>
19680	</attribute>
19681	</interface>
19682
19683	<interface
19684	name="IMouseCapabilityChangedEvent" extends="IEvent"
19685	uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
19686	wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
19687	>
19688	<desc>
19689	Notification when the mouse capabilities reported by the
19690	guest have changed. The new capabilities are passed.
19691	</desc>
19692	<attribute name="supportsAbsolute" type="boolean" readonly="yes">
19693	<desc>
19694	Supports absolute coordinates.
19695	</desc>
19696	</attribute>
19697	<attribute name="supportsRelative" type="boolean" readonly="yes">
19698	<desc>
19699	Supports relative coordinates.
19700	</desc>
19701	</attribute>
19702	<attribute name="needsHostCursor" type="boolean" readonly="yes">
19703	<desc>
19704	If host cursor is needed.
19705	</desc>
19706	</attribute>
19707	</interface>
19708
19709	<interface
19710	name="IKeyboardLedsChangedEvent" extends="IEvent"
19711	uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
19712	wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
19713	>
19714	<desc>
19715	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
19716	to alter the state of the keyboard LEDs.
19717	</desc>
19718	<attribute name="numLock" type="boolean" readonly="yes">
19719	<desc>
19720	NumLock status.
19721	</desc>
19722	</attribute>
19723	<attribute name="capsLock" type="boolean" readonly="yes">
19724	<desc>
19725	CapsLock status.
19726	</desc>
19727	</attribute>
19728	<attribute name="scrollLock" type="boolean" readonly="yes">
19729	<desc>
19730	ScrollLock status.
19731	</desc>
19732	</attribute>
19733	</interface>
19734
19735	<interface
19736	name="IStateChangedEvent" extends="IEvent"
19737	uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
19738	wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
19739	>
19740	<desc>
19741	Notification when the execution state of the machine has changed.
19742	The new state is given.
19743	</desc>
19744	<attribute name="state" type="MachineState" readonly="yes">
19745	<desc>
19746	New machine state.
19747	</desc>
19748	</attribute>
19749	</interface>
19750
19751	<interface
19752	name="IAdditionsStateChangedEvent" extends="IEvent"
19753	uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
19754	wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
19755	>
19756	<desc>
19757	Notification when a Guest Additions property changes.
19758	Interested callees should query IGuest attributes to
19759	find out what has changed.
19760	</desc>
19761	</interface>
19762
19763	<interface
19764	name="INetworkAdapterChangedEvent" extends="IEvent"
19765	uuid="08889892-1EC6-4883-801D-77F56CFD0103"
19766	wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
19767	>
19768	<desc>
19769	Notification when a property of one of the
19770	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
19771	changes. Interested callees should use INetworkAdapter methods and
19772	attributes to find out what has changed.
19773	</desc>
19774	<attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
19775	<desc>
19776	Network adapter that is subject to change.
19777	</desc>
19778	</attribute>
19779	</interface>
19780
19781	<interface
19782	name="ISerialPortChangedEvent" extends="IEvent"
19783	uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
19784	wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
19785	>
19786	<desc>
19787	Notification when a property of one of the
19788	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
19789	Interested callees should use ISerialPort methods and attributes
19790	to find out what has changed.
19791	</desc>
19792	<attribute name="serialPort" type="ISerialPort" readonly="yes">
19793	<desc>
19794	Serial port that is subject to change.
19795	</desc>
19796	</attribute>
19797	</interface>
19798
19799	<interface
19800	name="IParallelPortChangedEvent" extends="IEvent"
19801	uuid="813C99FC-9849-4F47-813E-24A75DC85615"
19802	wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
19803	>
19804	<desc>
19805	Notification when a property of one of the
19806	virtual <link to="IMachine::getParallelPort">parallel ports</link>
19807	changes. Interested callees should use ISerialPort methods and
19808	attributes to find out what has changed.
19809	</desc>
19810	<attribute name="parallelPort" type="IParallelPort" readonly="yes">
19811	<desc>
19812	Parallel port that is subject to change.
19813	</desc>
19814	</attribute>
19815	</interface>
19816
19817	<interface
19818	name="IStorageControllerChangedEvent" extends="IEvent"
19819	uuid="715212BF-DA59-426E-8230-3831FAA52C56"
19820	wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
19821	>
19822	<desc>
19823	Notification when a
19824	<link to="IMachine::mediumAttachments">medium attachment</link>
19825	changes.
19826	</desc>
19827	</interface>
19828
19829	<interface
19830	name="IMediumChangedEvent" extends="IEvent"
19831	uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
19832	wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
19833	>
19834	<desc>
19835	Notification when a
19836	<link to="IMachine::mediumAttachments">medium attachment</link>
19837	changes.
19838	</desc>
19839	<attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
19840	<desc>
19841	Medium attachment that is subject to change.
19842	</desc>
19843	</attribute>
19844	</interface>
19845
19846	<interface
19847	name="IClipboardModeChangedEvent" extends="IEvent"
19848	uuid="cac21692-7997-4595-a731-3a509db604e5"
19849	wsmap="managed" autogen="VBoxEvent" id="OnClipboardModeChanged"
19850	>
19851	<desc>
19852	Notification when the shared clipboard mode changes.
19853	</desc>
19854	<attribute name="clipboardMode" type="ClipboardMode" readonly="yes">
19855	<desc>
19856	The new clipboard mode.
19857	</desc>
19858	</attribute>
19859	</interface>
19860
19861	<interface
19862	name="IDragAndDropModeChangedEvent" extends="IEvent"
19863	uuid="e90b8850-ac8e-4dff-8059-4100ae2c3c3d"
19864	wsmap="managed" autogen="VBoxEvent" id="OnDragAndDropModeChanged"
19865	>
19866	<desc>
19867	Notification when the drag'n'drop mode changes.
19868	</desc>
19869	<attribute name="dragAndDropMode" type="DragAndDropMode" readonly="yes">
19870	<desc>
19871	The new drag'n'drop mode.
19872	</desc>
19873	</attribute>
19874	</interface>
19875
19876	<interface
19877	name="ICPUChangedEvent" extends="IEvent"
19878	uuid="4da2dec7-71b2-4817-9a64-4ed12c17388e"
19879	wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
19880	>
19881	<desc>
19882	Notification when a CPU changes.
19883	</desc>
19884	<attribute name="CPU" type="unsigned long" readonly="yes">
19885	<desc>
19886	The CPU which changed.
19887	</desc>
19888	</attribute>
19889	<attribute name="add" type="boolean" readonly="yes">
19890	<desc>
19891	Flag whether the CPU was added or removed.
19892	</desc>
19893	</attribute>
19894	</interface>
19895
19896	<interface
19897	name="ICPUExecutionCapChangedEvent" extends="IEvent"
19898	uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
19899	wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
19900	>
19901	<desc>
19902	Notification when the CPU execution cap changes.
19903	</desc>
19904	<attribute name="executionCap" type="unsigned long" readonly="yes">
19905	<desc>
19906	The new CPU execution cap value. (1-100)
19907	</desc>
19908	</attribute>
19909	</interface>
19910
19911	<interface
19912	name="IGuestKeyboardEvent" extends="IEvent"
19913	uuid="88394258-7006-40d4-b339-472ee3801844"
19914	wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard"
19915	>
19916	<desc>
19917	Notification when guest keyboard event happens.
19918	</desc>
19919	<attribute name="scancodes" type="long" safearray="yes" readonly="yes">
19920	<desc>
19921	Array of scancodes.
19922	</desc>
19923	</attribute>
19924	</interface>
19925
19926	<interface
19927	name="IGuestMouseEvent" extends="IReusableEvent"
19928	uuid="1f85d35c-c524-40ff-8e98-307000df0992"
19929	wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse"
19930	>
19931	<desc>
19932	Notification when guest mouse event happens.
19933	</desc>
19934
19935	<attribute name="absolute" type="boolean" readonly="yes">
19936	<desc>
19937	If this event is relative or absolute.
19938	</desc>
19939	</attribute>
19940
19941	<attribute name="x" type="long" readonly="yes">
19942	<desc>
19943	New X position, or X delta.
19944	</desc>
19945	</attribute>
19946
19947	<attribute name="y" type="long" readonly="yes">
19948	<desc>
19949	New Y position, or Y delta.
19950	</desc>
19951	</attribute>
19952
19953	<attribute name="z" type="long" readonly="yes">
19954	<desc>
19955	Z delta.
19956	</desc>
19957	</attribute>
19958
19959	<attribute name="w" type="long" readonly="yes">
19960	<desc>
19961	W delta.
19962	</desc>
19963	</attribute>
19964
19965	<attribute name="buttons" type="long" readonly="yes">
19966	<desc>
19967	Button state bitmask.
19968	</desc>
19969	</attribute>
19970
19971	</interface>
19972
19973	<interface
19974	name="IGuestSessionEvent" extends="IEvent"
19975	uuid="b9acd33f-647d-45ac-8fe9-f49b3183ba37"
19976	wsmap="managed"
19977	>
19978	<desc>Base abstract interface for all guest session events.</desc>
19979
19980	<attribute name="session" type="IGuestSession" readonly="yes">
19981	<desc>Guest session that is subject to change.</desc>
19982	</attribute>
19983
19984	</interface>
19985
19986	<interface
19987	name="IGuestSessionStateChangedEvent" extends="IGuestSessionEvent"
19988	uuid="327e3c00-ee61-462f-aed3-0dff6cbf9904"
19989	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionStateChanged"
19990	>
19991	<desc>
19992	Notification when a guest session changed its state.
19993	</desc>
19994
19995	<attribute name="id" type="unsigned long" readonly="yes">
19996	<desc>
19997	Session ID of guest session which was changed.
19998	</desc>
19999	</attribute>
20000	<attribute name="status" type="GuestSessionStatus" readonly="yes">
20001	<desc>
20002	New session status.
20003	</desc>
20004	</attribute>
20005	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20006	<desc>
20007	Error information in case of new session status is indicating an error.
20008
20009	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20010	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20011	include/VBox/err.h for details.
20012	</desc>
20013	</attribute>
20014
20015	</interface>
20016
20017	<interface
20018	name="IGuestSessionRegisteredEvent" extends="IGuestSessionEvent"
20019	uuid="b79de686-eabd-4fa6-960a-f1756c99ea1c"
20020	wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionRegistered"
20021	>
20022	<desc>
20023	Notification when a guest session was registered or unregistered.
20024	</desc>
20025
20026	<attribute name="registered" type="boolean" readonly="yes">
20027	<desc>
20028	If @c true, the guest session was registered, otherwise it was
20029	unregistered.
20030	</desc>
20031	</attribute>
20032
20033	</interface>
20034
20035	<interface
20036	name="IGuestProcessEvent" extends="IGuestSessionEvent"
20037	uuid="2405f0e5-6588-40a3-9b0a-68c05ba52c4b"
20038	wsmap="managed"
20039	>
20040	<desc>Base abstract interface for all guest process events.</desc>
20041
20042	<attribute name="process" type="IGuestProcess" readonly="yes">
20043	<desc>
20044	Guest process object which is related to this event.
20045	</desc>
20046	</attribute>
20047	<attribute name="pid" type="unsigned long" readonly="yes">
20048	<desc>
20049	Guest process ID (PID).
20050	</desc>
20051	</attribute>
20052
20053	</interface>
20054
20055	<interface
20056	name="IGuestProcessRegisteredEvent" extends="IGuestProcessEvent"
20057	uuid="1d89e2b3-c6ea-45b6-9d43-dc6f70cc9f02"
20058	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessRegistered"
20059	>
20060	<desc>
20061	Notification when a guest process was registered or unregistered.
20062	</desc>
20063
20064	<attribute name="registered" type="boolean" readonly="yes">
20065	<desc>
20066	If @c true, the guest process was registered, otherwise it was
20067	unregistered.
20068	</desc>
20069	</attribute>
20070
20071	</interface>
20072
20073	<interface
20074	name="IGuestProcessStateChangedEvent" extends="IGuestProcessEvent"
20075	uuid="c365fb7b-4430-499f-92c8-8bed814a567a"
20076	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessStateChanged"
20077	>
20078	<desc>
20079	Notification when a guest process changed its state.
20080	</desc>
20081
20082	<attribute name="status" type="ProcessStatus" readonly="yes">
20083	<desc>
20084	New guest process status.
20085	</desc>
20086	</attribute>
20087	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20088	<desc>
20089	Error information in case of new session status is indicating an error.
20090
20091	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20092	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20093	include/VBox/err.h for details.
20094	</desc>
20095	</attribute>
20096
20097	</interface>
20098
20099	<interface
20100	name="IGuestProcessIOEvent" extends="IGuestProcessEvent"
20101	uuid="9ea9227c-e9bb-49b3-bfc7-c5171e93ef38"
20102	wsmap="managed"
20103	>
20104	<desc>
20105	Base abstract interface for all guest process input/output (IO) events.
20106	</desc>
20107
20108	<attribute name="handle" type="unsigned long" readonly="yes">
20109	<desc>
20110	Input/output (IO) handle involved in this event. Usually 0 is stdin,
20111	1 is stdout and 2 is stderr.
20112	</desc>
20113	</attribute>
20114
20115	<attribute name="processed" type="unsigned long" readonly="yes">
20116	<desc>
20117	Processed input or output (in bytes).
20118	</desc>
20119	</attribute>
20120
20121	</interface>
20122
20123	<interface
20124	name="IGuestProcessInputNotifyEvent" extends="IGuestProcessIOEvent"
20125	uuid="0de887f2-b7db-4616-aac6-cfb94d89ba78"
20126	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessInputNotify"
20127	>
20128	<desc>
20129	Notification when a guest process' stdin became available.
20130	<note>This event is right now not implemented!</note>
20131	</desc>
20132
20133	<attribute name="status" type="ProcessInputStatus" readonly="yes">
20134	<desc>
20135	Current process input status.
20136	</desc>
20137	</attribute>
20138
20139	</interface>
20140
20141	<interface
20142	name="IGuestProcessOutputEvent" extends="IGuestProcessIOEvent"
20143	uuid="d3d5f1ee-bcb2-4905-a7ab-cc85448a742b"
20144	wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessOutput"
20145	>
20146	<desc>
20147	Notification when there is guest process output available for reading.
20148	</desc>
20149
20150	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20151	<desc>
20152	Actual output data.
20153	</desc>
20154	</attribute>
20155
20156	</interface>
20157
20158	<interface
20159	name="IGuestFileEvent" extends="IGuestSessionEvent"
20160	uuid="c8adb7b0-057d-4391-b928-f14b06b710c5"
20161	wsmap="managed"
20162	>
20163	<desc>Base abstract interface for all guest file events.</desc>
20164
20165	<attribute name="file" type="IGuestFile" readonly="yes">
20166	<desc>
20167	Guest file object which is related to this event.
20168	</desc>
20169	</attribute>
20170
20171	</interface>
20172
20173	<interface
20174	name="IGuestFileRegisteredEvent" extends="IGuestFileEvent"
20175	uuid="d0d93830-70a2-487e-895e-d3fc9679f7b3"
20176	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRegistered"
20177	>
20178	<desc>
20179	Notification when a guest file was registered or unregistered.
20180	</desc>
20181
20182	<attribute name="registered" type="boolean" readonly="yes">
20183	<desc>
20184	If @c true, the guest file was registered, otherwise it was
20185	unregistered.
20186	</desc>
20187	</attribute>
20188
20189	</interface>
20190
20191	<interface
20192	name="IGuestFileStateChangedEvent" extends="IGuestFileEvent"
20193	uuid="d37fe88f-0979-486c-baa1-3abb144dc82d"
20194	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileStateChanged"
20195	>
20196	<desc>
20197	Notification when a guest file changed its state.
20198	</desc>
20199
20200	<attribute name="status" type="FileStatus" readonly="yes">
20201	<desc>
20202	New guest file status.
20203	</desc>
20204	</attribute>
20205	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20206	<desc>
20207	Error information in case of new session status is indicating an error.
20208
20209	The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain
20210	the runtime (IPRT) error code from the guest. See include/iprt/err.h and
20211	include/VBox/err.h for details.
20212	</desc>
20213	</attribute>
20214	<!-- Note: No events for reads/writes for performance reasons.
20215	See dedidcated events IGuestFileReadEvent and
20216	IGuestFileWriteEvent. -->
20217
20218	</interface>
20219
20220	<interface
20221	name="IGuestFileIOEvent" extends="IGuestFileEvent"
20222	uuid="b5191a7c-9536-4ef8-820e-3b0e17e5bbc8"
20223	wsmap="managed"
20224	>
20225	<desc>
20226	Base abstract interface for all guest file input/output (IO) events.
20227	</desc>
20228
20229	<attribute name="offset" type="long long" readonly="yes">
20230	<desc>
20231	Current offset (in bytes).
20232	</desc>
20233	</attribute>
20234	<attribute name="processed" type="unsigned long" readonly="yes">
20235	<desc>
20236	Processed input or output (in bytes).
20237	</desc>
20238	</attribute>
20239
20240	</interface>
20241
20242	<interface
20243	name="IGuestFileOffsetChangedEvent" extends="IGuestFileIOEvent"
20244	uuid="e8f79a21-1207-4179-94cf-ca250036308f"
20245	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileOffsetChanged"
20246	>
20247	<desc>
20248	Notification when a guest file changed its current offset.
20249	</desc>
20250
20251	</interface>
20252
20253	<interface
20254	name="IGuestFileReadEvent" extends="IGuestFileIOEvent"
20255	uuid="4ee3cbcb-486f-40db-9150-deee3fd24189"
20256	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRead"
20257	>
20258	<desc>
20259	Notification when data has been read from a guest file.
20260	</desc>
20261
20262	<attribute name="data" type="octet" safearray="yes" readonly="yes">
20263	<desc>
20264	Actual data read.
20265	</desc>
20266	</attribute>
20267
20268	</interface>
20269
20270	<interface
20271	name="IGuestFileWriteEvent" extends="IGuestFileIOEvent"
20272	uuid="e062a915-3cf5-4c0a-bc90-9b8d4cc94d89"
20273	wsmap="managed" autogen="VBoxEvent" id="OnGuestFileWrite"
20274	>
20275	<desc>
20276	Notification when data has been written to a guest file.
20277	</desc>
20278
20279	</interface>
20280
20281	<interface
20282	name="IVRDEServerChangedEvent" extends="IEvent"
20283	uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
20284	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
20285	>
20286	<desc>
20287	Notification when a property of the
20288	<link to="IMachine::VRDEServer">VRDE server</link> changes.
20289	Interested callees should use IVRDEServer methods and attributes to
20290	find out what has changed.
20291	</desc>
20292	</interface>
20293
20294	<interface
20295	name="IVRDEServerInfoChangedEvent" extends="IEvent"
20296	uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
20297	wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
20298	>
20299	<desc>
20300	Notification when the status of the VRDE server changes. Interested callees
20301	should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
20302	attributes to find out what is the current status.
20303	</desc>
20304	</interface>
20305
20306	<interface
20307	name="IUSBControllerChangedEvent" extends="IEvent"
20308	uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
20309	wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
20310	>
20311	<desc>
20312	Notification when a property of the virtual
20313	<link to="IMachine::USBController">USB controller</link> changes.
20314	Interested callees should use IUSBController methods and attributes to
20315	find out what has changed.
20316	</desc>
20317	</interface>
20318
20319	<interface
20320	name="IUSBDeviceStateChangedEvent" extends="IEvent"
20321	uuid="806da61b-6679-422a-b629-51b06b0c6d93"
20322	wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
20323	>
20324	<desc>
20325	Notification when a USB device is attached to or detached from
20326	the virtual USB controller.
20327
20328	This notification is sent as a result of the indirect
20329	request to attach the device because it matches one of the
20330	machine USB filters, or as a result of the direct request
20331	issued by <link to="IConsole::attachUSBDevice"/> or
20332	<link to="IConsole::detachUSBDevice"/>.
20333
20334	This notification is sent in case of both a succeeded and a
20335	failed request completion. When the request succeeds, the
20336	@a error parameter is @c null, and the given device has been
20337	already added to (when @a attached is @c true) or removed from
20338	(when @a attached is @c false) the collection represented by
20339	<link to="IConsole::USBDevices"/>. On failure, the collection
20340	doesn't change and the @a error parameter represents the error
20341	message describing the failure.
20342	</desc>
20343	<attribute name="device" type="IUSBDevice" readonly="yes">
20344	<desc>
20345	Device that is subject to state change.
20346	</desc>
20347	</attribute>
20348	<attribute name="attached" type="boolean" readonly="yes">
20349	<desc>
20350	@c true if the device was attached and @c false otherwise.
20351	</desc>
20352	</attribute>
20353	<attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
20354	<desc>
20355	@c null on success or an error message object on failure.
20356	</desc>
20357	</attribute>
20358	</interface>
20359
20360	<interface
20361	name="ISharedFolderChangedEvent" extends="IEvent"
20362	uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
20363	wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
20364	>
20365	<desc>
20366	Notification when a shared folder is added or removed.
20367	The @a scope argument defines one of three scopes:
20368	<link to="IVirtualBox::sharedFolders">global shared folders</link>
20369	(<link to="Scope_Global">Global</link>),
20370	<link to="IMachine::sharedFolders">permanent shared folders</link> of
20371	the machine (<link to="Scope_Machine">Machine</link>) or <link
20372	to="IConsole::sharedFolders">transient shared folders</link> of the
20373	machine (<link to="Scope_Session">Session</link>). Interested callees
20374	should use query the corresponding collections to find out what has
20375	changed.
20376	</desc>
20377	<attribute name="scope" type="Scope" readonly="yes">
20378	<desc>
20379	Scope of the notification.
20380	</desc>
20381	</attribute>
20382	</interface>
20383
20384	<interface
20385	name="IRuntimeErrorEvent" extends="IEvent"
20386	uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
20387	wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
20388	>
20389	<desc>
20390	Notification when an error happens during the virtual
20391	machine execution.
20392
20393	There are three kinds of runtime errors:
20394	<ul>
20395	<li><i>fatal</i></li>
20396	<li><i>non-fatal with retry</i></li>
20397	<li><i>non-fatal warnings</i></li>
20398	</ul>
20399
20400	<b>Fatal</b> errors are indicated by the @a fatal parameter set
20401	to @c true. In case of fatal errors, the virtual machine
20402	execution is always paused before calling this notification, and
20403	the notification handler is supposed either to immediately save
20404	the virtual machine state using <link to="IConsole::saveState"/>
20405	or power it off using <link to="IConsole::powerDown"/>.
20406	Resuming the execution can lead to unpredictable results.
20407
20408	<b>Non-fatal</b> errors and warnings are indicated by the
20409	@a fatal parameter set to @c false. If the virtual machine
20410	is in the Paused state by the time the error notification is
20411	received, it means that the user can <i>try to resume</i> the machine
20412	execution after attempting to solve the problem that caused the
20413	error. In this case, the notification handler is supposed
20414	to show an appropriate message to the user (depending on the
20415	value of the @a id parameter) that offers several actions such
20416	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
20417	wants to retry, the notification handler should continue
20418	the machine execution using the <link to="IConsole::resume"/>
20419	call. If the machine execution is not Paused during this
20420	notification, then it means this notification is a <i>warning</i>
20421	(for example, about a fatal condition that can happen very soon);
20422	no immediate action is required from the user, the machine
20423	continues its normal execution.
20424
20425	Note that in either case the notification handler
20426	<b>must not</b> perform any action directly on a thread
20427	where this notification is called. Everything it is allowed to
20428	do is to post a message to another thread that will then talk
20429	to the user and take the corresponding action.
20430
20431	Currently, the following error identifiers are known:
20432	<ul>
20433	<li><tt>"HostMemoryLow"</tt></li>
20434	<li><tt>"HostAudioNotResponding"</tt></li>
20435	<li><tt>"VDIStorageFull"</tt></li>
20436	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
20437	</ul>
20438	</desc>
20439	<attribute name="fatal" type="boolean" readonly="yes">
20440	<desc>
20441	Whether the error is fatal or not.
20442	</desc>
20443	</attribute>
20444	<attribute name="id" type="wstring" readonly="yes">
20445	<desc>
20446	Error identifier.
20447	</desc>
20448	</attribute>
20449	<attribute name="message" type="wstring" readonly="yes">
20450	<desc>
20451	Optional error message.
20452	</desc>
20453	</attribute>
20454	</interface>
20455
20456
20457	<interface
20458	name="IEventSourceChangedEvent" extends="IEvent"
20459	uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
20460	waitable="yes"
20461	wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
20462	>
20463	<desc>
20464	Notification when an event source state changes (listener added or removed).
20465	</desc>
20466
20467	<attribute name="listener" type="IEventListener" readonly="yes">
20468	<desc>
20469	Event listener which has changed.
20470	</desc>
20471	</attribute>
20472
20473	<attribute name="add" type="boolean" readonly="yes">
20474	<desc>
20475	Flag whether listener was added or removed.
20476	</desc>
20477	</attribute>
20478	</interface>
20479
20480	<interface
20481	name="IExtraDataChangedEvent" extends="IEvent"
20482	uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
20483	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
20484	>
20485	<desc>
20486	Notification when machine specific or global extra data
20487	has changed.
20488	</desc>
20489	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20490	<desc>
20491	ID of the machine this event relates to.
20492	Null for global extra data changes.
20493	</desc>
20494	</attribute>
20495	<attribute name="key" type="wstring" readonly="yes">
20496	<desc>
20497	Extra data key that has changed.
20498	</desc>
20499	</attribute>
20500	<attribute name="value" type="wstring" readonly="yes">
20501	<desc>
20502	Extra data value for the given key.
20503	</desc>
20504	</attribute>
20505	</interface>
20506
20507	<interface
20508	name="IVetoEvent" extends="IEvent"
20509	uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
20510	wsmap="managed"
20511	>
20512	<desc>Base abstract interface for veto events.</desc>
20513
20514	<method name="addVeto">
20515	<desc>
20516	Adds a veto on this event.
20517	</desc>
20518	<param name="reason" type="wstring" dir="in">
20519	<desc>
20520	Reason for veto, could be null or empty string.
20521	</desc>
20522	</param>
20523	</method>
20524
20525	<method name="isVetoed">
20526	<desc>
20527	If this event was vetoed.
20528	</desc>
20529	<param name="result" type="boolean" dir="return">
20530	<desc>
20531	Reason for veto.
20532	</desc>
20533	</param>
20534	</method>
20535
20536	<method name="getVetos">
20537	<desc>
20538	Current veto reason list, if size is 0 - no veto.
20539	</desc>
20540	<param name="result" type="wstring" dir="return" safearray="yes">
20541	<desc>
20542	Array of reasons for veto provided by different event handlers.
20543	</desc>
20544	</param>
20545	</method>
20546
20547	</interface>
20548
20549	<interface
20550	name="IExtraDataCanChangeEvent" extends="IVetoEvent"
20551	uuid="245d88bd-800a-40f8-87a6-170d02249a55"
20552	wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
20553	waitable="true"
20554	>
20555	<desc>
20556	Notification when someone tries to change extra data for
20557	either the given machine or (if @c null) global extra data.
20558	This gives the chance to veto against changes.
20559	</desc>
20560	<attribute name="machineId" type="uuid" mod="string" readonly="yes">
20561	<desc>
20562	ID of the machine this event relates to.
20563	Null for global extra data changes.
20564	</desc>
20565	</attribute>
20566	<attribute name="key" type="wstring" readonly="yes">
20567	<desc>
20568	Extra data key that has changed.
20569	</desc>
20570	</attribute>
20571	<attribute name="value" type="wstring" readonly="yes">
20572	<desc>
20573	Extra data value for the given key.
20574	</desc>
20575	</attribute>
20576	</interface>
20577
20578	<interface
20579	name="ICanShowWindowEvent" extends="IVetoEvent"
20580	uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
20581	wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
20582	waitable="true"
20583	>
20584	<desc>
20585	Notification when a call to
20586	<link to="IMachine::canShowConsoleWindow"/> is made by a
20587	front-end to check if a subsequent call to
20588	<link to="IMachine::showConsoleWindow"/> can succeed.
20589
20590	The callee should give an answer appropriate to the current
20591	machine state using event veto. This answer must
20592	remain valid at least until the next
20593	<link to="IConsole::state">machine state</link> change.
20594	</desc>
20595	</interface>
20596
20597	<interface
20598	name="IShowWindowEvent" extends="IEvent"
20599	uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
20600	wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
20601	waitable="true"
20602	>
20603	<desc>
20604	Notification when a call to
20605	<link to="IMachine::showConsoleWindow"/>
20606	requests the console window to be activated and brought to
20607	foreground on the desktop of the host PC.
20608
20609	This notification should cause the VM console process to
20610	perform the requested action as described above. If it is
20611	impossible to do it at a time of this notification, this
20612	method should return a failure.
20613
20614	Note that many modern window managers on many platforms
20615	implement some sort of focus stealing prevention logic, so
20616	that it may be impossible to activate a window without the
20617	help of the currently active application (which is supposedly
20618	an initiator of this notification). In this case, this method
20619	must return a non-zero identifier that represents the
20620	top-level window of the VM console process. The caller, if it
20621	represents a currently active process, is responsible to use
20622	this identifier (in a platform-dependent manner) to perform
20623	actual window activation.
20624
20625	This method must set @a winId to zero if it has performed all
20626	actions necessary to complete the request and the console
20627	window is now active and in foreground, to indicate that no
20628	further action is required on the caller's side.
20629	</desc>
20630	<attribute name="winId" type="long long">
20631	<desc>
20632	Platform-dependent identifier of the top-level VM console
20633	window, or zero if this method has performed all actions
20634	necessary to implement the <i>show window</i> semantics for
20635	the given platform and/or this VirtualBox front-end.
20636	</desc>
20637	</attribute>
20638	</interface>
20639
20640	<interface
20641	name="INATRedirectEvent" extends="IMachineEvent"
20642	uuid="24eef068-c380-4510-bc7c-19314a7352f1"
20643	wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect"
20644	>
20645	<desc>
20646	Notification when NAT redirect rule added or removed.
20647	</desc>
20648	<attribute name="slot" type="unsigned long" readonly="yes">
20649	<desc>
20650	Adapter which NAT attached to.
20651	</desc>
20652	</attribute>
20653	<attribute name="remove" type="boolean" readonly="yes">
20654	<desc>
20655	Whether rule remove or add.
20656	</desc>
20657	</attribute>
20658	<attribute name="name" type="wstring" readonly="yes">
20659	<desc>
20660	Name of the rule.
20661	</desc>
20662	</attribute>
20663	<attribute name="proto" type="NATProtocol" readonly="yes">
20664	<desc>
20665	Protocol (TCP or UDP) of the redirect rule.
20666	</desc>
20667	</attribute>
20668	<attribute name="hostIP" type="wstring" readonly="yes">
20669	<desc>
20670	Host ip address to bind socket on.
20671	</desc>
20672	</attribute>
20673	<attribute name="hostPort" type="long" readonly="yes">
20674	<desc>
20675	Host port to bind socket on.
20676	</desc>
20677	</attribute>
20678	<attribute name="guestIP" type="wstring" readonly="yes">
20679	<desc>
20680	Guest ip address to redirect to.
20681	</desc>
20682	</attribute>
20683	<attribute name="guestPort" type="long" readonly="yes">
20684	<desc>
20685	Guest port to redirect to.
20686	</desc>
20687	</attribute>
20688	</interface>
20689
20690	<interface
20691	name="IHostPCIDevicePlugEvent" extends="IMachineEvent"
20692	waitable="yes"
20693	uuid="a0bad6df-d612-47d3-89d4-db3992533948"
20694	wsmap="managed" autogen="VBoxEvent" id="OnHostPCIDevicePlug"
20695	>
20696	<desc>
20697	Notification when host PCI device is plugged/unplugged. Plugging
20698	usually takes place on VM startup, unplug - when
20699	<link to="IMachine::detachHostPCIDevice"/> is called.
20700
20701	<see><link to="IMachine::detachHostPCIDevice"/></see>
20702
20703	</desc>
20704
20705	<attribute name="plugged" type="boolean" readonly="yes">
20706	<desc>
20707	If device successfully plugged or unplugged.
20708	</desc>
20709	</attribute>
20710
20711	<attribute name="success" type="boolean" readonly="yes">
20712	<desc>
20713	If operation was successful, if false - 'message' attribute
20714	may be of interest.
20715	</desc>
20716	</attribute>
20717
20718	<attribute name="attachment" type="IPCIDeviceAttachment" readonly="yes">
20719	<desc>
20720	Attachment info for this device.
20721	</desc>
20722	</attribute>
20723
20724	<attribute name="message" type="wstring" readonly="yes">
20725	<desc>
20726	Optional error message.
20727	</desc>
20728	</attribute>
20729
20730	</interface>
20731
20732	<interface
20733	name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent"
20734	uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc"
20735	wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged"
20736	>
20737	<desc>
20738	Notification when VBoxSVC becomes unavailable (due to a crash or similar
20739	unexpected circumstances) or available again.
20740	</desc>
20741
20742	<attribute name="available" type="boolean" readonly="yes">
20743	<desc>
20744	Whether VBoxSVC is available now.
20745	</desc>
20746	</attribute>
20747	</interface>
20748
20749	<interface
20750	name="IBandwidthGroupChangedEvent" extends="IEvent"
20751	uuid="334df94a-7556-4cbc-8c04-043096b02d82"
20752	wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged"
20753	>
20754	<desc>
20755	Notification when one of the bandwidth groups changed
20756	</desc>
20757	<attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
20758	<desc>
20759	The changed bandwidth group.
20760	</desc>
20761	</attribute>
20762	</interface>
20763
20764	<enum
20765	name="GuestMonitorChangedEventType"
20766	uuid="ef172985-7e36-4297-95be-e46396968d66"
20767	>
20768
20769	<desc>
20770	How the guest monitor has been changed.
20771	</desc>
20772
20773	<const name="Enabled" value="0">
20774	<desc>
20775	The guest monitor has been enabled by the guest.
20776	</desc>
20777	</const>
20778
20779	<const name="Disabled" value="1">
20780	<desc>
20781	The guest monitor has been disabled by the guest.
20782	</desc>
20783	</const>
20784
20785	<const name="NewOrigin" value="2">
20786	<desc>
20787	The guest monitor origin has changed in the guest.
20788	</desc>
20789	</const>
20790	</enum>
20791
20792	<interface
20793	name="IGuestMonitorChangedEvent" extends="IEvent"
20794	uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090"
20795	wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged"
20796	>
20797	<desc>
20798	Notification when the guest enables one of its monitors.
20799	</desc>
20800
20801	<attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes">
20802	<desc>
20803	What was changed for this guest monitor.
20804	</desc>
20805	</attribute>
20806
20807	<attribute name="screenId" type="unsigned long" readonly="yes">
20808	<desc>
20809	The monitor which was changed.
20810	</desc>
20811	</attribute>
20812
20813	<attribute name="originX" type="unsigned long" readonly="yes">
20814	<desc>
20815	Physical X origin relative to the primary screen.
20816	Valid for Enabled and NewOrigin.
20817	</desc>
20818	</attribute>
20819
20820	<attribute name="originY" type="unsigned long" readonly="yes">
20821	<desc>
20822	Physical Y origin relative to the primary screen.
20823	Valid for Enabled and NewOrigin.
20824	</desc>
20825	</attribute>
20826
20827	<attribute name="width" type="unsigned long" readonly="yes">
20828	<desc>
20829	Width of the screen.
20830	Valid for Enabled.
20831	</desc>
20832	</attribute>
20833
20834	<attribute name="height" type="unsigned long" readonly="yes">
20835	<desc>
20836	Height of the screen.
20837	Valid for Enabled.
20838	</desc>
20839	</attribute>
20840
20841	</interface>
20842
20843	<interface
20844	name="IStorageDeviceChangedEvent" extends="IEvent"
20845	uuid="232e9151-ae84-4b8e-b0f3-5c20c35caac9"
20846	wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged"
20847	>
20848	<desc>
20849	Notification when a
20850	<link to="IMachine::mediumAttachments">storage device</link>
20851	is attached or removed.
20852	</desc>
20853	<attribute name="storageDevice" type="IMediumAttachment" readonly="yes">
20854	<desc>
20855	Storage device that is subject to change.
20856	</desc>
20857	</attribute>
20858	<attribute name="removed" type="boolean" readonly="yes">
20859	<desc>
20860	Flag whether the device was removed or added to the VM.
20861	</desc>
20862	</attribute>
20863	<attribute name="silent" type="boolean" readonly="yes">
20864	<desc>
20865	Flag whether the guest should be notified about the change.
20866	</desc>
20867	</attribute>
20868	</interface>
20869	<interface
20870	name="INATNetworkChangedEvent" extends="IEvent"
20871	uuid="101ae042-1a29-4a19-92cf-02285773f3b5"
20872	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkChanged"
20873	>
20874	<!-- network name is common setting for all event types -->
20875	<attribute name="NetworkName" type="wstring" readonly="yes"/>
20876	</interface>
20877	<!-- base class for start/stop events -->
20878	<interface name="INATNetworkStartStopEvent" extends="INATNetworkChangedEvent"
20879	uuid="269d8f6b-fa1e-4cee-91c7-6d8496bea3c1"
20880	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkStartStop">
20881	<attribute name="startEvent" type="boolean" readonly="yes">
20882	<desc>
20883	IsStartEvent is true when NAT network is started and false on stopping.
20884	</desc>
20885	</attribute>
20886	</interface>
20887
20888	<!-- base class for modification events -->
20889	<interface name="INATNetworkAlterEvent" extends="INATNetworkChangedEvent"
20890	uuid="3f5a0822-163a-43b1-ad16-8d58b0ef6e75"
20891	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkAlter"/>
20892
20893	<interface name="INATNetworkCreationDeletionEvent" extends="INATNetworkAlterEvent"
20894	uuid="8d984a7e-b855-40b8-ab0c-44d3515b4528"
20895	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkCreationDeletion">
20896	<attribute name="creationEvent" type="boolean" readonly="yes"/>
20897	</interface>
20898	<interface name="INATNetworkSettingEvent" extends="INATNetworkAlterEvent"
20899	uuid="9db3a9e6-7f29-4aae-a627-5a282c83092c"
20900	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkSetting">
20901	<attribute name="enabled" type="boolean" readonly="yes"/>
20902	<attribute name="network" type="wstring" readonly="yes"/>
20903	<attribute name="gateway" type="wstring" readonly="yes"/>
20904	<attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" readonly="yes"/>
20905	<attribute name="needDhcpServer" type="boolean" readonly="yes"/>
20906	</interface>
20907	<interface name="INATNetworkPortForwardEvent" extends="INATNetworkAlterEvent"
20908	uuid="2514881b-23d0-430a-a7ff-7ed7f05534bc"
20909	wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkPortForward">
20910	<attribute name="create" type="boolean" readonly="yes"/>
20911	<attribute name="ipv6" type="boolean" readonly="yes"/>
20912	<attribute name="name" type="wstring" readonly="yes"/>
20913	<attribute name="proto" type="NATProtocol" readonly="yes"/>
20914	<attribute name="hostIp" type="wstring" readonly="yes"/>
20915	<attribute name="hostPort" type="long" readonly="yes"/>
20916	<attribute name="guestIp" type="wstring" readonly="yes"/>
20917	<attribute name="guestPort" type="long" readonly="yes"/>
20918	</interface>
20919
20920	<module name="VBoxSVC" context="LocalServer">
20921	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
20922	namespace="virtualbox.org">
20923	<interface name="IVirtualBox" default="yes"/>
20924	</class>
20925	</module>
20926
20927	<module name="VBoxC" context="InprocServer" threadingModel="Free">
20928	<class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba"
20929	namespace="virtualbox.org">
20930	<interface name="IVirtualBoxClient" default="yes"/>
20931	</class>
20932
20933	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
20934	namespace="virtualbox.org">
20935	<interface name="ISession" default="yes"/>
20936	</class>
20937	</module>
20938
20939	</library>
20940
20941	</idl>
20942
20943	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format