VirtualBox.xidl@ 29591

Last change on this file since 29591 was 29591, checked in by vboxsync, 15 years ago
Complete API, but leave it unimplemented
Property svn:eol-style set to `native`
File size: 536.8 KB

Line
1	<?xml version="1.0" ?>
2
3	<!--
4
5	Copyright (C) 2006-2010 Oracle Corporation
6
7	This file is part of VirtualBox Open Source Edition (OSE), as
8	available from http://www.virtualbox.org. This file is free software;
9	you can redistribute it and/or modify it under the terms of the GNU
10	General Public License (GPL) as published by the Free Software
11	Foundation, in version 2 as it comes in the "COPYING" file of the
12	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
14	-->
15
16	<!--
17	This is the master declaration for VirtualBox's Main API,
18	represented by COM/XPCOM and web service interfaces.
19
20	From this document, the build system generates several files
21	via XSLT that are then used during the build process.
22
23	Below is the list of XSL templates that operate on this file and
24	output files they generate. These XSL templates must be updated
25	whenever the schema of this file changes:
26
27	1. src/VBox/Main/idl/midl.xsl =>
28	out/<platform>/bin/sdk/idl/VirtualBox.idl
29	(MS COM interface definition file for Main API)
30
31	2. src/VBox/Main/idl/xpidl.xsl =>
32	out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
33	(XPCOM interface definition file for Main API)
34
35	3. src/VBox/Main/idl/doxygen.xsl =>
36	out/<platform>/obj/src/VBox/Main/VirtualBox.idl
37	(pseudo-IDL for Doxygen to generate the official Main API
38	documentation)
39
40	4. src/VBox/Main/webservice/*.xsl =>
41	a bunch of WSDL and C++ files
42	(VirtualBox web service sources and SOAP mappers;
43	see src/VBox/Main/webservice/Makefile.kmk for details)
44
45	5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
46	out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
47	(smart Qt-based C++ wrapper classes for COM interfaces
48	of the Main API)
49
50	6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
51	out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
52	(Main API TypeLib block for the WiX installer)
53
54	7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
55	out/<platform>/obj/Runtime/errmsgvboxcomdata.h
56	(<result> extraction for the %Rhrc format specifier)
57	-->
58
59	<idl>
60
61	<desc>
62	Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
63	describes the so-called <i>VirtualBox Main API</i> which comprises all public
64	COM interfaces and components provided by the VirtualBox server and by the
65	VirtualBox client library.
66
67	VirtualBox employs a client-server design, meaning that whenever any part of
68	VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
69	interface or any virtual machine --, a dedicated server process named
70	VBoxSVC runs in the background. This allows multiple processes working with
71	VirtualBox to cooperate without conflicts. These processes communicate to each
72	other using inter-process communication facilities provided by the COM
73	implementation of the host computer.
74
75	On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
76	implementation. On all other platforms, Mozilla XPCOM, an open-source COM
77	implementation, is used.
78
79	All the parts that a typical VirtualBox user interacts with (the Qt GUI,
80	the VBoxManage command-line interface and the VBoxVRDP server) are technically
81	front-ends to the Main API and only use the interfaces that are documented
82	in this Main API documentation. This ensures that, with any given release
83	version of VirtualBox, all capabilities of the product that could be useful
84	to an external client program are always exposed by way of this API.
85
86	The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
87	contains two public component classes:
88	<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
89	implement IVirtualBox and ISession interfaces respectively. These two classes
90	are of supreme importance and will be needed in order for any front-end
91	program to do anything useful. It is recommended to read the documentation of
92	the mentioned interfaces first.
93
94	The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
95	there can be only one object of this class on the local machine at any given
96	time. This object is a parent of many other objects in the VirtualBox COM
97	library and lives in the VBoxSVC process. In fact, when you create an instance
98	of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
99	process is already running, starts it if not, and returns you a reference to
100	the <tt>VirtualBox</tt> object created in this process. When the last reference
101	to this object is released, the VBoxSVC process ends (with a 5 second delay to
102	protect from too frequent restarts).
103
104	The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
105	as many <tt>Session</tt> objects as you need but all of them will live in a
106	process which issues the object instantiation call. <tt>Session</tt> objects
107	represent virtual machine sessions which are used to configure virtual
108	machines and control their execution.
109	</desc>
110
111	<if target="midl">
112	<cpp line="enum {"/>
113	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
114	<cpp line=" kTypeLibraryMinorVersion = 0"/>
115	<cpp line="};"/>
116	</if>
117
118	<if target="xpidl">
119	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
120	<cpp>
121	/* currently, nsISupportsImpl.h lacks the below-like macros */
122
123	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
124	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
125	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
126
127	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
128	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
129	NS_IMPL_THREADSAFE_ADDREF(_class) \
130	NS_IMPL_THREADSAFE_RELEASE(_class) \
131	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
132	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
133	#endif
134
135	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
136	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
137	NS_IMPL_THREADSAFE_ADDREF(_class) \
138	NS_IMPL_THREADSAFE_RELEASE(_class) \
139	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
140	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
141	#endif
142
143	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
144	# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
145	NS_IMPL_THREADSAFE_ADDREF(_class) \
146	NS_IMPL_THREADSAFE_RELEASE(_class) \
147	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
148	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
149	#endif
150
151	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
152	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
153	NS_INTERFACE_MAP_BEGIN(_class) \
154	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
155	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
156	NS_IMPL_QUERY_CLASSINFO(_class) \
157	NS_INTERFACE_MAP_END
158	#endif
159
160	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
161	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
162	_i2, _ic2) \
163	NS_INTERFACE_MAP_BEGIN(_class) \
164	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
165	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
166	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
167	NS_IMPL_QUERY_CLASSINFO(_class) \
168	NS_INTERFACE_MAP_END
169	#endif
170
171	#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
172	# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
173	_i2, _ic2, _i3, _ic3) \
174	NS_INTERFACE_MAP_BEGIN(_class) \
175	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
176	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
177	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
178	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
179	NS_IMPL_QUERY_CLASSINFO(_class) \
180	NS_INTERFACE_MAP_END
181	#endif
182
183	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
184	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
185	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
186
187	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
188	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
189	NS_IMPL_THREADSAFE_ADDREF(_class) \
190	NS_IMPL_THREADSAFE_RELEASE(_class) \
191	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
192	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
193	#endif
194
195	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
196	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
197	_i2, _ic2) \
198	NS_IMPL_THREADSAFE_ADDREF(_class) \
199	NS_IMPL_THREADSAFE_RELEASE(_class) \
200	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
201	_i2, _ic2) \
202	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
203	#endif
204
205	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
206	# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
207	_i2, _ic2, _i3, _ic3) \
208	NS_IMPL_THREADSAFE_ADDREF(_class) \
209	NS_IMPL_THREADSAFE_RELEASE(_class) \
210	NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
211	_i2, _ic2, _i3, _ic3) \
212	NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
213	#endif
214
215	</cpp>
216	</if>
217
218	<library
219	name="VirtualBox"
220	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
221	version="1.3"
222	desc="VirtualBox Type Library"
223	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
224	supportsErrorInfo="yes"
225	>
226
227
228	<!--
229	// COM result codes for VirtualBox
230	/////////////////////////////////////////////////////////////////////////
231	-->
232
233	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
234	<desc>
235	This section describes all VirtualBox-specific COM result codes that may
236	be returned by methods of VirtualBox COM interfaces in addition to
237	standard COM result codes.
238
239	Note that along with the result code, every VirtualBox method returns
240	extended error information through the IVirtualBoxErrorInfo interface on
241	failure. This interface is a preferred way to present the error to the end
242	user because it contains a human readable description of the error. Raw
243	result codes, both standard and described in this section, are intended to
244	be used by programs to analyze the reason of a failure and select an
245	appropriate course of action without involving the end user (for example,
246	retry the operation later or make a different call).
247
248	The standard COM result codes that may originate from our methods include:
249
250	<table>
251	<tr><td>E_INVALIDARG</td>
252	<td>
253	Returned when the value of the method's argument is not within the range
254	of valid values. This should not be confused with situations when the
255	value is within the range but simply doesn't suit the current object
256	state and there is a possibility that it will be accepted later (in such
257	cases VirtualBox-specific codes are returned, for example,
258	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
259	</td>
260	</tr>
261	<tr><td>E_POINTER</td>
262	<td>
263	Returned if a memory pointer for the output argument is invalid (for
264	example, @c null). Note that when pointers representing input
265	arguments (such as strings) are invalid, E_INVALIDARG is returned.
266	</td>
267	</tr>
268	<tr><td>E_ACCESSDENIED</td>
269	<td>
270	Returned when the called object is not ready. Since the lifetime of a
271	public COM object cannot be fully controlled by the implementation,
272	VirtualBox maintains the readiness state for all objects it creates and
273	returns this code in response to any method call on the object that was
274	deactivated by VirtualBox and is not functioning any more.
275	</td>
276	</tr>
277	<tr><td>E_OUTOFMEMORY</td>
278	<td>
279	Returned when a memory allocation operation fails.
280	</td>
281	</tr>
282	</table>
283	</desc>
284	</descGroup>
285
286	<!--
287	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
288	everything in <result>/<desc> after (and including) the first dot, so express
289	the matter of the error code in the first sentence and keep it short.
290	-->
291
292	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
293	<desc>
294	Object corresponding to the supplied arguments does not exist.
295	</desc>
296	</result>
297
298	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
299	<desc>
300	Current virtual machine state prevents the operation.
301	</desc>
302	</result>
303
304	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
305	<desc>
306	Virtual machine error occurred attempting the operation.
307	</desc>
308	</result>
309
310	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
311	<desc>
312	File not accessible or erroneous file contents.
313	</desc>
314	</result>
315
316	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
317	<desc>
318	Runtime subsystem error.
319	</desc>
320	</result>
321
322	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
323	<desc>
324	Pluggable Device Manager error.
325	</desc>
326	</result>
327
328	<result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
329	<desc>
330	Current object state prohibits operation.
331	</desc>
332	</result>
333
334	<result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
335	<desc>
336	Host operating system related error.
337	</desc>
338	</result>
339
340	<result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
341	<desc>
342	Requested operation is not supported.
343	</desc>
344	</result>
345
346	<result name="VBOX_E_XML_ERROR" value="0x80BB000A">
347	<desc>
348	Invalid XML found.
349	</desc>
350	</result>
351
352	<result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
353	<desc>
354	Current session state prohibits operation.
355	</desc>
356	</result>
357
358	<result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
359	<desc>
360	Object being in use prohibits operation.
361	</desc>
362	</result>
363
364	<result name="VBOX_E_DONT_CALL_AGAIN" value="0x80BB000D">
365	<desc>
366	Returned by callback methods which does not need to be called again
367	because the client does not actually make use of them.
368	</desc>
369	</result>
370
371	<!--
372	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
373	everything in <result>/<desc> after (and including) the first dot, so express
374	the matter of the error code in the first sentence and keep it short.
375	-->
376
377	<descGroup/>
378
379	<!--
380	// all common enums
381	/////////////////////////////////////////////////////////////////////////
382	-->
383
384	<enum name="SettingsVersion"
385	uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
386	>
387	<desc>Settings version of VirtualBox settings files. This is written to
388	the "version" attribute of the root "VirtualBox" element in the settings
389	file XML and indicates which VirtualBox version wrote the file.
390	</desc>
391
392	<const name="Null" value="0">
393	<desc>Null value, indicates invalid version.</desc>
394	</const>
395	<const name="v1_0" value="1">
396	<desc>Legacy settings version, not currently supported.</desc>
397	</const>
398	<const name="v1_1" value="2">
399	<desc>Legacy settings version, not currently supported.</desc>
400	</const>
401	<const name="v1_2" value="3">
402	<desc>Legacy settings version, not currently supported.</desc>
403	</const>
404	<const name="v1_3pre" value="4">
405	<desc>Legacy settings version, not currently supported.</desc>
406	</const>
407	<const name="v1_3" value="5">
408	<desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
409	<!--
410	Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
411	-->
412	</const>
413	<const name="v1_4" value="6">
414	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
415	<!--
416	VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
417	(was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
418	-->
419	</const>
420	<const name="v1_5" value="7">
421	<desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
422	<!-- 2008-09-04: 2.0.0 released
423	2008-11-20: settings version 1.5 introduced
424	2008-12-17: 2.1.0 released
425	Machine changes:
426	guest OS identifiers changed;
427	Machine/Hardware/Display/MonitorCount renamed to monitorCount;
428	Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
429	Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
430	-->
431	</const>
432	<const name="v1_6" value="8">
433	<desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
434	<!-- 2008-12-17: 2.1.0 released
435	2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
436	2009-04-08: 2.2.0 released
437	Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
438	-->
439	</const>
440	<const name="v1_7" value="9">
441	<desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
442	<!-- 2008-12-17: 2.1.0 released
443	2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
444	2009-04-08: 2.2.0 released
445	VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
446	Machine changes: HardDiskAttachments is now StorageControllers (done)
447	-->
448	</const>
449	<const name="v1_8" value="10">
450	<desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
451	<!-- Machine additions: Display/@accelerate2DVideo (done)
452	-->
453	</const>
454	<const name="v1_9" value="11">
455	<desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
456	<!-- The big storage controller / DVD / Floppy rework (done)
457	-->
458	</const>
459	<const name="v1_10" value="12">
460	<desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
461	<!-- Machine changes: RTC localOrUTC (done)
462	CPU hot-plug support
463	-->
464	</const>
465	<const name="Future" value="13">
466	<desc>Settings version greater than "1.10", written by a future VirtualBox version.</desc>
467	</const>
468	</enum>
469
470	<enum
471	name="AccessMode"
472	uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
473	>
474	<desc>
475	Access mode for opening files.
476	</desc>
477
478	<const name="ReadOnly" value="1"/>
479	<const name="ReadWrite" value="2"/>
480	</enum>
481
482	<enum
483	name="MachineState"
484	uuid="e998d075-543a-41fc-8aa9-5ca3e92393fd"
485	>
486	<desc>
487	Virtual machine execution state.
488
489	This enumeration represents possible values of the <link
490	to="IMachine::state"/> attribute.
491
492	Below is the basic virtual machine state diagram. It shows how the state
493	changes during virtual machine execution. The text in square braces shows
494	a method of the IConsole interface that performs the given state
495	transition.
496
497	<pre>
498	+---------[powerDown()] <- Stuck <--[failure]-+
499	V \|
500	+-> PoweredOff --+-->[powerUp()]--> Starting --+ \| +-----[resume()]-----+
501	\| \| \| \| V \|
502	\| Aborted -----+ +--> Running --[pause()]--> Paused
503	\| \| ^ \| ^ \|
504	\| Saved -----------[powerUp()]--> Restoring -+ \| \| \| \|
505	\| ^ \| \| \| \|
506	\| \| +-----------------------------------------+-\|-------------------+ +
507	\| \| \| \| \|
508	\| \| +-- Saving <--------[takeSnapshot()]<-------+---------------------+
509	\| \| \| \|
510	\| +-------- Saving <--------[saveState()]<----------+---------------------+
511	\| \| \|
512	+-------------- Stopping -------[powerDown()]<----------+---------------------+
513	</pre>
514
515	Note that states to the right from PoweredOff, Aborted and Saved in the
516	above diagram are called <i>online VM states</i>. These states
517	represent the virtual machine which is being executed in a dedicated
518	process (usually with a GUI window attached to it where you can see the
519	activity of the virtual machine and interact with it). There are two
520	special pseudo-states, FirstOnline and LastOnline, that can be used in
521	relational expressions to detect if the given machine state is online or
522	not:
523
524	<pre>
525	if (machine.GetState() >= MachineState_FirstOnline &&
526	machine.GetState() <= MachineState_LastOnline)
527	{
528	...the machine is being executed...
529	}
530	</pre>
531
532	When the virtual machine is in one of the online VM states (that is, being
533	executed), only a few machine settings can be modified. Methods working
534	with such settings contain an explicit note about that. An attempt to
535	change any oter setting or perform a modifying operation during this time
536	will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
537
538	All online states except Running, Paused and Stuck are transitional: they
539	represent temporary conditions of the virtual machine that will last as
540	long as the operation that initiated such a condition.
541
542	The Stuck state is a special case. It means that execution of the machine
543	has reached the "Guru Meditation" condition. This condition indicates an
544	internal VMM (virtual machine manager) failure which may happen as a
545	result of either an unhandled low-level virtual hardware exception or one
546	of the recompiler exceptions (such as the <i>too-many-traps</i>
547	condition).
548
549	Note also that any online VM state may transit to the Aborted state. This
550	happens if the process that is executing the virtual machine terminates
551	unexpectedly (for example, crashes). Other than that, the Aborted state is
552	equivalent to PoweredOff.
553
554	There are also a few additional state diagrams that do not deal with
555	virtual machine execution and therefore are shown separately. The states
556	shown on these diagrams are called <i>offline VM states</i> (this includes
557	PoweredOff, Aborted and Saved too).
558
559	The first diagram shows what happens when a lengthy setup operation is
560	being executed (such as <link to="IMachine::attachDevice"/>).
561
562	<pre>
563	+----------------------------------(same state as before the call)------+
564	\| \|
565	+-> PoweredOff --+ \|
566	\| \| \|
567	\|-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
568	\| \|
569	+-> Saved -------+
570	</pre>
571
572	The next two diagrams demonstrate the process of taking a snapshot of a
573	powered off virtual machine, restoring the state to that as of a snapshot
574	or deleting a snapshot, respectively.
575
576	<pre>
577	+----------------------------------(same state as before the call)------+
578	\| \|
579	+-> PoweredOff --+ \|
580	\| +-->[takeSnapshot()] -------------------> Saving ------+
581	+-> Aborted -----+
582
583	+-> PoweredOff --+
584	\| \|
585	\| Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
586	\| \| [deleteSnapshot() ]-------> DeletingSnapshot --+
587	+-> Saved -------+ \|
588	\| \|
589	+---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
590	</pre>
591
592	Note that the Saving state is present in both the offline state group and
593	online state group. Currently, the only way to determine what group is
594	assumed in a particular case is to remember the previous machine state: if
595	it was Running or Paused, then Saving is an online state, otherwise it is
596	an offline state. This inconsistency may be removed in one of the future
597	versions of VirtualBox by adding a new state.
598
599	<note internal="yes">
600	For whoever decides to touch this enum: In order to keep the
601	comparisons involving FirstOnline and LastOnline pseudo-states valid,
602	the numeric values of these states must be correspondingly updated if
603	needed: for any online VM state, the condition
604	<tt>FirstOnline <= state <= LastOnline</tt> must be
605	@c true. The same relates to transient states for which
606	the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
607	@c true.
608	</note>
609	</desc>
610
611	<const name="Null" value="0">
612	<desc>Null value (never used by the API).</desc>
613	</const>
614	<const name="PoweredOff" value="1">
615	<desc>
616	The machine is not running and has no saved execution state; it has
617	either never been started or been shut down successfully.
618	</desc>
619	</const>
620	<const name="Saved" value="2">
621	<desc>
622	The machine is not currently running, but the execution state of the machine
623	has been saved to an external file when it was running, from where
624	it can be resumed.
625	</desc>
626	</const>
627	<const name="Teleported" value="3">
628	<desc>
629	The machine was teleported to a different host (or process) and then
630	powered off. Take care when powering it on again may corrupt resources
631	it shares with the teleportation target (e.g. disk and network).
632	</desc>
633	</const>
634	<const name="Aborted" value="4">
635	<desc>
636	The process running the machine has terminated abnormally. This may
637	indicate a crash of the VM process in host execution context, or
638	the VM process has been terminated externally.
639	</desc>
640	</const>
641	<const name="Running" value="5">
642	<desc>
643	The machine is currently being executed.
644	<note internal="yes">
645	For whoever decides to touch this enum: In order to keep the
646	comparisons in the old source code valid, this state must immediately
647	precede the Paused state.
648	TODO: Lift this spectacularly wonderful restriction.
649	</note>
650	</desc>
651	</const>
652	<const name="Paused" value="6">
653	<desc>
654	Execution of the machine has been paused.
655	<note internal="yes">
656	For whoever decides to touch this enum: In order to keep the
657	comparisons in the old source code valid, this state must immediately
658	follow the Running state.
659	TODO: Lift this spectacularly wonderful restriction.
660	</note>
661	</desc>
662	</const>
663	<const name="Stuck" value="7">
664	<desc>
665	Execution of the machine has reached the "Guru Meditation"
666	condition. This indicates a severe error in the hypervisor itself.
667	<note internal="yes">
668	bird: Why this uncool name? Could we rename it to "GuruMeditation" or
669	"Guru", perhaps? Or are there some other VMM states that are
670	intended to be lumped in here as well?
671	</note>
672	</desc>
673	</const>
674	<const name="Teleporting" value="8">
675	<desc>
676	The machine is about to be teleported to a different host or process.
677	It is possible to pause a machine in this state, but it will go to the
678	<link to="MachineState::PausedTeleporting"/> state and it will not be
679	possible to resume it again unless the teleportation fails.
680	</desc>
681	</const>
682	<const name="LiveSnapshotting" value="9">
683	<desc>
684	A live snapshot is being taken. The machine is running normally, but
685	some of the runtime configuration options are inaccessible. Also, if
686	paused while in this state it will transition to
687	<link to="MachineState::Saving"/> and it will not be resume the
688	execution until the snapshot operation has completed.
689	</desc>
690	</const>
691	<const name="Starting" value="10">
692	<desc>
693	Machine is being started after powering it on from a
694	zero execution state.
695	</desc>
696	</const>
697	<const name="Stopping" value="11">
698	<desc>
699	Machine is being normally stopped powering it off, or after the guest OS
700	has initiated a shutdown sequence.
701	</desc>
702	</const>
703	<const name="Saving" value="12">
704	<desc>
705	Machine is saving its execution state to a file, or an online
706	snapshot of the machine is being taken.
707	</desc>
708	</const>
709	<const name="Restoring" value="13">
710	<desc>
711	Execution state of the machine is being restored from a file
712	after powering it on from the saved execution state.
713	</desc>
714	</const>
715	<const name="TeleportingPausedVM" value="14">
716	<desc>
717	The machine is being teleported to another host or process, but it is
718	not running. This is the paused variant of the
719	<link to="MachineState::Teleporting"/> state.
720	</desc>
721	</const>
722	<const name="TeleportingIn" value="15">
723	<desc>
724	Teleporting the machine state in from another host or process.
725	</desc>
726	</const>
727	<const name="DeletingSnapshotOnline" value="16">
728	<desc>
729	Teleporting the machine state in from another host or process.
730	</desc>
731	</const>
732	<const name="DeletingSnapshotPaused" value="17">
733	<desc>
734	Teleporting the machine state in from another host or process.
735	</desc>
736	</const>
737	<const name="RestoringSnapshot" value="18">
738	<desc>
739	A machine snapshot is being restored; this typically does not take long.
740	</desc>
741	</const>
742	<const name="DeletingSnapshot" value="19">
743	<desc>
744	A machine snapshot is being deleted; this can take a long time since this
745	may require merging differencing media.
746	</desc>
747	</const>
748	<const name="SettingUp" value="20">
749	<desc>
750	Lengthy setup operation is in progress.
751	</desc>
752	</const>
753
754	<const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
755	<desc>
756	Pseudo-state: first online state (for use in relational expressions).
757	</desc>
758	</const>
759	<const name="LastOnline" value="17" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
760	<desc>
761	Pseudo-state: last online state (for use in relational expressions).
762	</desc>
763	</const>
764
765	<const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
766	<desc>
767	Pseudo-state: first transient state (for use in relational expressions).
768	</desc>
769	</const>
770	<const name="LastTransient" value="20" wsmap="suppress"> <!-- SettingUp -->
771	<desc>
772	Pseudo-state: last transient state (for use in relational expressions).
773	</desc>
774	</const>
775
776	</enum>
777
778	<enum
779	name="SessionState"
780	uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
781	>
782	<desc>
783	Session state. This enumeration represents possible values of
784	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
785	attributes. See individual enumerator descriptions for the meaning for
786	every value.
787	</desc>
788
789	<const name="Null" value="0">
790	<desc>Null value (never used by the API).</desc>
791	</const>
792	<const name="Closed" value="1">
793	<desc>
794	The machine has no open sessions (<link to="IMachine::sessionState"/>);
795	the session is closed (<link to="ISession::state"/>)
796	</desc>
797	</const>
798	<const name="Open" value="2">
799	<desc>
800	The machine has an open direct session (<link to="IMachine::sessionState"/>);
801	the session is open (<link to="ISession::state"/>)
802	</desc>
803	</const>
804	<const name="Spawning" value="3">
805	<desc>
806	A new (direct) session is being opened for the machine as a result of
807	<link to="IVirtualBox::openRemoteSession"/> call
808	(<link to="IMachine::sessionState"/> or <link to="ISession::state"/>).
809	This state also occurs as a short transient state when a new direct
810	session is opened by calling <link to="IVirtualBox::openSession"/>.
811	</desc>
812	</const>
813	<const name="Closing" value="4">
814	<desc>
815	The direct session is being closed (<link to="IMachine::sessionState"/>);
816	the session is being closed (<link to="ISession::state"/>)
817	</desc>
818	</const>
819	</enum>
820
821	<enum
822	name="CPUPropertyType"
823	uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
824	>
825	<desc>
826	Virtual CPU property type. This enumeration represents possible values of the
827	IMachine get- and setCPUProperty methods.
828	</desc>
829	<const name="Null" value="0">
830	<desc>Null value (never used by the API).</desc>
831	</const>
832	<const name="PAE" value="1">
833	<desc>
834	This setting determines whether VirtualBox will expose the Physical Address
835	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
836	is not available, it will not be reported.
837	</desc>
838	</const>
839	<const name="Synthetic" value="2">
840	<desc>
841	This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
842	teleporting between host systems that differ significantly.
843	</desc>
844	</const>
845	</enum>
846
847
848	<enum
849	name="HWVirtExPropertyType"
850	uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
851	>
852	<desc>
853	Hardware virtualization property type. This enumeration represents possible values
854	for the <link to="IMachine::getHWVirtExProperty"/> and
855	<link to="IMachine::setHWVirtExProperty"/> methods.
856	</desc>
857	<const name="Null" value="0">
858	<desc>Null value (never used by the API).</desc>
859	</const>
860	<const name="Enabled" value="1">
861	<desc>
862	Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
863	such extensions are not available, they will not be used.
864	</desc>
865	</const>
866	<const name="Exclusive" value="2">
867	<desc>
868	Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
869	VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
870	feature of the host. To share these with other hypervisors, you must disable this property.
871	</desc>
872	</const>
873	<const name="VPID" value="3">
874	<desc>
875	Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
876	</desc>
877	</const>
878	<const name="NestedPaging" value="4">
879	<desc>
880	Whether Nested Paging is enabled. If this extension is not available, it will not be used.
881	</desc>
882	</const>
883	<const name="LargePages" value="5">
884	<desc>
885	Whether large page allocation is enabled; requires nested paging and a 64 bits host.
886	</desc>
887	</const>
888	</enum>
889
890	<enum
891	name="SessionType"
892	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
893	>
894	<desc>
895	Session type. This enumeration represents possible values of the
896	<link to="ISession::type"/> attribute.
897	</desc>
898
899	<const name="Null" value="0">
900	<desc>Null value (never used by the API).</desc>
901	</const>
902	<const name="Direct" value="1">
903	<desc>
904	Direct session
905	(opened by <link to="IVirtualBox::openSession"/>)
906	</desc>
907	</const>
908	<const name="Remote" value="2">
909	<desc>
910	Remote session
911	(opened by <link to="IVirtualBox::openRemoteSession"/>)
912	</desc>
913	</const>
914	<const name="Existing" value="3">
915	<desc>
916	Existing session
917	(opened by <link to="IVirtualBox::openExistingSession"/>)
918	</desc>
919	</const>
920	</enum>
921
922	<enum
923	name="DeviceType"
924	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
925	>
926	<desc>
927	Device type.
928	</desc>
929	<const name="Null" value="0">
930	<desc>
931	Null value, may also mean "no device" (not allowed for
932	<link to="IConsole::getDeviceActivity"/>).
933	</desc>
934	</const>
935	<const name="Floppy" value="1">
936	<desc>Floppy device.</desc>
937	</const>
938	<const name="DVD" value="2">
939	<desc>CD/DVD-ROM device.</desc>
940	</const>
941	<const name="HardDisk" value="3">
942	<desc>Hard disk device.</desc>
943	</const>
944	<const name="Network" value="4">
945	<desc>Network device.</desc>
946	</const>
947	<const name="USB" value="5">
948	<desc>USB device.</desc>
949	</const>
950	<const name="SharedFolder" value="6">
951	<desc>Shared folder device.</desc>
952	</const>
953	</enum>
954
955	<enum
956	name="DeviceActivity"
957	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
958	>
959	<desc>
960	Device activity for <link to="IConsole::getDeviceActivity"/>.
961	</desc>
962
963	<const name="Null" value="0"/>
964	<const name="Idle" value="1"/>
965	<const name="Reading" value="2"/>
966	<const name="Writing" value="3"/>
967	</enum>
968
969	<enum
970	name="ClipboardMode"
971	uuid="33364716-4008-4701-8f14-be0fa3d62950"
972	>
973	<desc>
974	Host-Guest clipboard interchange mode.
975	</desc>
976
977	<const name="Disabled" value="0"/>
978	<const name="HostToGuest" value="1"/>
979	<const name="GuestToHost" value="2"/>
980	<const name="Bidirectional" value="3"/>
981	</enum>
982
983	<enum
984	name="Scope"
985	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
986	>
987	<desc>
988	Scope of the operation.
989
990	A generic enumeration used in various methods to define the action or
991	argument scope.
992	</desc>
993
994	<const name="Global" value="0"/>
995	<const name="Machine" value="1"/>
996	<const name="Session" value="2"/>
997	</enum>
998
999	<enum
1000	name="BIOSBootMenuMode"
1001	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1002	>
1003	<desc>
1004	BIOS boot menu mode.
1005	</desc>
1006
1007	<const name="Disabled" value="0"/>
1008	<const name="MenuOnly" value="1"/>
1009	<const name="MessageAndMenu" value="2"/>
1010	</enum>
1011
1012	<enum
1013	name="ProcessorFeature"
1014	uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1015	>
1016	<desc>
1017	CPU features.
1018	</desc>
1019
1020	<const name="HWVirtEx" value="0"/>
1021	<const name="PAE" value="1"/>
1022	<const name="LongMode" value="2"/>
1023	<const name="NestedPaging" value="3"/>
1024	</enum>
1025
1026	<enum
1027	name="FirmwareType"
1028	uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1029	>
1030	<desc>
1031	Firmware type.
1032	</desc>
1033	<const name="BIOS" value="1">
1034	<desc>BIOS Firmware.</desc>
1035	</const>
1036	<const name="EFI" value="2">
1037	<desc>EFI Firmware, bitness detetced basing on OS type.</desc>
1038	</const>
1039	<const name="EFI32" value="3">
1040	<desc>Efi firmware, 32-bit.</desc>
1041	</const>
1042	<const name="EFI64" value="4">
1043	<desc>Efi firmware, 64-bit.</desc>
1044	</const>
1045	<const name="EFIDUAL" value="5">
1046	<desc>Efi firmware, combined 32 and 64-bit.</desc>
1047	</const>
1048	</enum>
1049
1050	<enum
1051	name="PointingHidType"
1052	uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
1053	>
1054	<desc>
1055	Type of pointing device used in a virtual machine.
1056	</desc>
1057	<const name="None" value="1">
1058	<desc>No mouse.</desc>
1059	</const>
1060	<const name="PS2Mouse" value="2">
1061	<desc>PS/2 auxillary device, a.k.a. mouse.</desc>
1062	</const>
1063	<const name="USBMouse" value="3">
1064	<desc>USB mouse (relative pointer).</desc>
1065	</const>
1066	<const name="USBTablet" value="4">
1067	<desc>USB tablet (absolute pointer).</desc>
1068	</const>
1069	<const name="ComboMouse" value="5">
1070	<desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1071	Using of such device can have negative performance implications. </desc>
1072	</const>
1073	</enum>
1074
1075	<enum
1076	name="KeyboardHidType"
1077	uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
1078	>
1079	<desc>
1080	Type of keyboard device used in a virtual machine.
1081	</desc>
1082	<const name="None" value="1">
1083	<desc>No keyboard.</desc>
1084	</const>
1085	<const name="PS2Keyboard" value="2">
1086	<desc>PS/2 keyboard.</desc>
1087	</const>
1088	<const name="USBKeyboard" value="3">
1089	<desc>USB keyboard.</desc>
1090	</const>
1091	<const name="ComboKeyboard" value="4">
1092	<desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1093	Using of such device can have negative performance implications. </desc>
1094	</const>
1095	</enum>
1096
1097	<!--
1098	// IVirtualBoxErrorInfo
1099	/////////////////////////////////////////////////////////////////////////
1100	-->
1101
1102	<interface
1103	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1104	uuid="4b86d186-407e-4f9e-8be8-e50061be8725"
1105	supportsErrorInfo="no"
1106	wsmap="managed"
1107	>
1108	<desc>
1109	The IVirtualBoxErrorInfo interface represents extended error information.
1110
1111	Extended error information can be set by VirtualBox components after
1112	unsuccessful or partially successful method invocation. This information
1113	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1114	and then shown to the client in addition to the plain 32-bit result code.
1115
1116	In MS COM, this interface extends the IErrorInfo interface,
1117	in XPCOM, it extends the nsIException interface. In both cases,
1118	it provides a set of common attributes to retrieve error
1119	information.
1120
1121	Sometimes invocation of some component's method may involve methods of
1122	other components that may also fail (independently of this method's
1123	failure), or a series of non-fatal errors may precede a fatal error that
1124	causes method failure. In cases like that, it may be desirable to preserve
1125	information about all errors happened during method invocation and deliver
1126	it to the caller. The <link to="#next"/> attribute is intended
1127	specifically for this purpose and allows to represent a chain of errors
1128	through a single IVirtualBoxErrorInfo object set after method invocation.
1129
1130	Note that errors are stored to a chain in the reverse order, i.e. the
1131	initial error object you query right after method invocation is the last
1132	error set by the callee, the object it points to in the @a next attribute
1133	is the previous error and so on, up to the first error (which is the last
1134	in the chain).
1135	</desc>
1136
1137	<attribute name="resultCode" type="long" readonly="yes">
1138	<desc>
1139	Result code of the error.
1140	Usually, it will be the same as the result code returned
1141	by the method that provided this error information, but not
1142	always. For example, on Win32, CoCreateInstance() will most
1143	likely return E_NOINTERFACE upon unsuccessful component
1144	instantiation attempt, but not the value the component factory
1145	returned. Value is typed 'long', not 'result',
1146	to make interface usable from scripting languages.
1147	<note>
1148	In MS COM, there is no equivalent.
1149	In XPCOM, it is the same as nsIException::result.
1150	</note>
1151	</desc>
1152	</attribute>
1153
1154	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1155	<desc>
1156	UUID of the interface that defined the error.
1157	<note>
1158	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1159	data type.
1160	In XPCOM, there is no equivalent.
1161	</note>
1162	</desc>
1163	</attribute>
1164
1165	<attribute name="component" type="wstring" readonly="yes">
1166	<desc>
1167	Name of the component that generated the error.
1168	<note>
1169	In MS COM, it is the same as IErrorInfo::GetSource.
1170	In XPCOM, there is no equivalent.
1171	</note>
1172	</desc>
1173	</attribute>
1174
1175	<attribute name="text" type="wstring" readonly="yes">
1176	<desc>
1177	Text description of the error.
1178	<note>
1179	In MS COM, it is the same as IErrorInfo::GetDescription.
1180	In XPCOM, it is the same as nsIException::message.
1181	</note>
1182	</desc>
1183	</attribute>
1184
1185	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1186	<desc>
1187	Next error object if there is any, or @c null otherwise.
1188	<note>
1189	In MS COM, there is no equivalent.
1190	In XPCOM, it is the same as nsIException::inner.
1191	</note>
1192	</desc>
1193	</attribute>
1194
1195	</interface>
1196
1197	<interface
1198	name="ILocalOwner" extends="$unknown"
1199	uuid="308FF42A-DC45-49D4-A950-B1EEE5E00BB5" wsmap="suppress"
1200	>
1201	<desc>
1202	The ILocalOwner interface allows to register local objects
1203	(created without COM calls, but with new()).
1204	Once registered, calls to methods of such objects can be made
1205	from remote COM processes.
1206	The main usecase is the event callback implementation where
1207	API clients provide callback objects.
1208	</desc>
1209	<method name="setLocalObject">
1210	<desc>
1211	Set local object.
1212	</desc>
1213	<param name="object" type="$unknown" dir="in">
1214	<desc>Local object to forward requests to.
1215	If null, clears currently set local object.</desc>
1216	</param>
1217	</method>
1218	</interface>
1219
1220	<!--
1221	// IVirtualBox
1222	/////////////////////////////////////////////////////////////////////////
1223	-->
1224
1225	<interface
1226	name="IVirtualBoxCallback" extends="$unknown"
1227	uuid="7f6a65b6-ad5d-4a67-8872-0b11cb7ea95c"
1228	wsmap="suppress"
1229	>
1230
1231	<method name="onMachineStateChange">
1232	<desc>
1233	The execution state of the given machine has changed.
1234	<see>IMachine::state</see>
1235	<result name="VBOX_E_DONT_CALL_AGAIN">
1236	Do not call again, this method is a NOP.
1237	</result>
1238	</desc>
1239	<param name="machineId" type="uuid" mod="string" dir="in">
1240	<desc>ID of the machine this event relates to.</desc>
1241	</param>
1242	<param name="state" type="MachineState" dir="in">
1243	<desc>New execution state.</desc>
1244	</param>
1245	</method>
1246
1247	<method name="onMachineDataChange">
1248	<desc>
1249	Any of the settings of the given machine has changed.
1250	<result name="VBOX_E_DONT_CALL_AGAIN">
1251	Do not call again, this method is a NOP.
1252	</result>
1253	</desc>
1254	<param name="machineId" type="uuid" mod="string" dir="in">
1255	<desc>ID of the machine this event relates to.</desc>
1256	</param>
1257	</method>
1258
1259	<method name="onExtraDataCanChange">
1260	<desc>
1261	Notification when someone tries to change extra data for
1262	either the given machine or (if @c null) global extra data.
1263	This gives the chance to veto against changes.
1264	<result name="VBOX_E_DONT_CALL_AGAIN">
1265	Do not call again, this method is a NOP. Change is allowed.
1266	</result>
1267	</desc>
1268	<param name="machineId" type="uuid" mod="string" dir="in">
1269	<desc>
1270	ID of the machine this event relates to
1271	(@c null ID for global extra data change requests).
1272	</desc>
1273	</param>
1274	<param name="key" type="wstring" dir="in">
1275	<desc>
1276	Extra data key for the attempted write.
1277	</desc>
1278	</param>
1279	<param name="value" type="wstring" dir="in">
1280	<desc>
1281	Extra data value for the given key.
1282	</desc>
1283	</param>
1284	<param name="error" type="wstring" dir="out">
1285	<desc>
1286	Optional error message describing the reason of the
1287	veto (ignored if this notification returns @c true).
1288	</desc>
1289	</param>
1290	<param name="allowChange" type="boolean" dir="return">
1291	<desc>
1292	Flag to indicate whether the callee agrees (@c true)
1293	or vetoes against the change (@c false).
1294	</desc>
1295	</param>
1296	</method>
1297
1298	<method name="onExtraDataChange">
1299	<desc>
1300	Notification when machine specific or global extra data
1301	has changed.
1302	<result name="VBOX_E_DONT_CALL_AGAIN">
1303	Do not call again, this method is a NOP.
1304	</result>
1305	</desc>
1306	<param name="machineId" type="uuid" mod="string" dir="in">
1307	<desc>
1308	ID of the machine this event relates to.
1309	Null for global extra data changes.
1310	</desc>
1311	</param>
1312	<param name="key" type="wstring" dir="in">
1313	<desc>
1314	Extra data key that has changed.
1315	</desc>
1316	</param>
1317	<param name="value" type="wstring" dir="in">
1318	<desc>
1319	Extra data value for the given key.
1320	</desc>
1321	</param>
1322	</method>
1323
1324	<method name="onMediumRegistered">
1325	<desc>
1326	The given medium was registered or unregistered
1327	within this VirtualBox installation.
1328
1329	The @a mediumType parameter describes what type of
1330	medium the specified @a mediumId refers to. Possible
1331	values are:
1332
1333	<ul>
1334	<li><link to="DeviceType_HardDisk"/>: the medium is a hard disk
1335	that, if registered, can be obtained using the
1336	<link to="IVirtualBox::getHardDisk"/> call.</li>
1337	<li><link to="DeviceType_DVD"/>: the medium is a CD/DVD image
1338	that, if registered, can be obtained using the
1339	<link to="IVirtualBox::getDVDImage"/> call.</li>
1340	<li><link to="DeviceType_Floppy"/>: the medium is a Floppy image
1341	that, if registered, can be obtained using the
1342	<link to="IVirtualBox::getFloppyImage"/> call.</li>
1343	</ul>
1344
1345	Note that if this is a deregistration notification,
1346	there is no way to access the object representing the
1347	unregistered medium. It is supposed that the
1348	application will do required cleanup based on the
1349	@a mediumId value.
1350
1351	<result name="VBOX_E_DONT_CALL_AGAIN">
1352	Do not call again, this method is a NOP.
1353	</result>
1354	</desc>
1355	<param name="mediumId" type="uuid" mod="string" dir="in">
1356	<desc>ID of the medium this event relates to.</desc>
1357	</param>
1358	<param name="mediumType" type="DeviceType" dir="in">
1359	<desc>Type of the medium this event relates to.</desc>
1360	</param>
1361	<param name="registered" type="boolean" dir="in">
1362	<desc>
1363	If @c true, the medium was registered, otherwise it was
1364	unregistered.
1365	</desc>
1366	</param>
1367	</method>
1368
1369	<method name="onMachineRegistered">
1370	<desc>
1371	The given machine was registered or unregistered
1372	within this VirtualBox installation.
1373	<result name="VBOX_E_DONT_CALL_AGAIN">
1374	Do not call again, this method is a NOP.
1375	</result>
1376	</desc>
1377	<param name="machineId" type="uuid" mod="string" dir="in">
1378	<desc>ID of the machine this event relates to.</desc>
1379	</param>
1380	<param name="registered" type="boolean" dir="in">
1381	<desc>
1382	If @c true, the machine was registered, otherwise it was
1383	unregistered.
1384	</desc>
1385	</param>
1386	</method>
1387
1388	<method name="onSessionStateChange">
1389	<desc>
1390	The state of the session for the given machine was changed.
1391	<see>IMachine::sessionState</see>
1392	<result name="VBOX_E_DONT_CALL_AGAIN">
1393	Do not call again, this method is a NOP.
1394	</result>
1395	</desc>
1396	<param name="machineId" type="uuid" mod="string" dir="in">
1397	<desc>ID of the machine this event relates to.</desc>
1398	</param>
1399	<param name="state" type="SessionState" dir="in">
1400	<desc>New session state.</desc>
1401	</param>
1402	</method>
1403
1404	<method name="onSnapshotTaken">
1405	<desc>
1406	A new snapshot of the machine has been taken.
1407	<see>ISnapshot</see>
1408	<result name="VBOX_E_DONT_CALL_AGAIN">
1409	Do not call again, this method is a NOP.
1410	</result>
1411	</desc>
1412	<param name="machineId" type="uuid" mod="string" dir="in">
1413	<desc>ID of the machine this event relates to.</desc>
1414	</param>
1415	<param name="snapshotId" type="uuid" mod="string" dir="in">
1416	<desc>ID of the new snapshot.</desc>
1417	</param>
1418	</method>
1419
1420	<method name="onSnapshotDeleted">
1421	<desc>
1422	Snapshot of the given machine has been deleted.
1423
1424	<note>
1425	This notification is delivered <b>after</b> the snapshot
1426	object has been uninitialized on the server (so that any
1427	attempt to call its methods will return an error).
1428	</note>
1429
1430	<see>ISnapshot</see>
1431
1432	<result name="VBOX_E_DONT_CALL_AGAIN">
1433	Do not call again, this method is a NOP.
1434	</result>
1435	</desc>
1436	<param name="machineId" type="uuid" mod="string" dir="in">
1437	<desc>ID of the machine this event relates to.</desc>
1438	</param>
1439	<param name="snapshotId" type="uuid" mod="string" dir="in">
1440	<desc>
1441	ID of the deleted snapshot. @c null means the current machine
1442	state has been deleted (restored from the current snapshot).
1443	</desc>
1444	</param>
1445	</method>
1446
1447	<method name="onSnapshotChange">
1448	<desc>
1449	Snapshot properties (name and/or description) have been changed.
1450	<see>ISnapshot</see>
1451	<result name="VBOX_E_DONT_CALL_AGAIN">
1452	Do not call again, this method is a NOP.
1453	</result>
1454	</desc>
1455	<param name="machineId" type="uuid" mod="string" dir="in">
1456	<desc>ID of the machine this event relates to.</desc>
1457	</param>
1458	<param name="snapshotId" type="uuid" mod="string" dir="in">
1459	<desc>ID of the changed snapshot.</desc>
1460	</param>
1461	</method>
1462
1463	<method name="onGuestPropertyChange">
1464	<desc>
1465	Notification when a guest property has changed.
1466	<result name="VBOX_E_DONT_CALL_AGAIN">
1467	Do not call again, this method is a NOP.
1468	</result>
1469	</desc>
1470	<param name="machineId" type="uuid" mod="string" dir="in">
1471	<desc>
1472	ID of the machine this event relates to.
1473	</desc>
1474	</param>
1475	<param name="name" type="wstring" dir="in">
1476	<desc>
1477	The name of the property that has changed.
1478	</desc>
1479	</param>
1480	<param name="value" type="wstring" dir="in">
1481	<desc>
1482	The new property value.
1483	</desc>
1484	</param>
1485	<param name="flags" type="wstring" dir="in">
1486	<desc>
1487	The new property flags.
1488	</desc>
1489	</param>
1490	</method>
1491
1492	</interface>
1493
1494	<interface
1495	name="IDHCPServer" extends="$unknown"
1496	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1497	wsmap="managed"
1498	>
1499	<desc>
1500	The IDHCPServer interface represents the vbox dhcp server configuration.
1501
1502	To enumerate all the dhcp servers on the host, use the
1503	<link to="IVirtualBox::DHCPServers"/> attribute.
1504	</desc>
1505
1506	<attribute name="enabled" type="boolean">
1507	<desc>
1508	specifies if the dhcp server is enabled
1509	</desc>
1510	</attribute>
1511
1512	<attribute name="IPAddress" type="wstring" readonly="yes">
1513	<desc>
1514	specifies server IP
1515	</desc>
1516	</attribute>
1517
1518	<attribute name="networkMask" type="wstring" readonly="yes">
1519	<desc>
1520	specifies server network mask
1521	</desc>
1522	</attribute>
1523
1524	<attribute name="networkName" type="wstring" readonly="yes">
1525	<desc>
1526	specifies internal network name the server is used for
1527	</desc>
1528	</attribute>
1529
1530	<attribute name="lowerIP" type="wstring" readonly="yes">
1531	<desc>
1532	specifies from IP adrres in server address range
1533	</desc>
1534	</attribute>
1535
1536	<attribute name="upperIP" type="wstring" readonly="yes">
1537	<desc>
1538	specifies to IP adrres in server address range
1539	</desc>
1540	</attribute>
1541
1542	<method name="setConfiguration">
1543	<desc>
1544	configures the server
1545	<result name="E_INVALIDARG">
1546	invalid configuration supplied
1547	</result>
1548	</desc>
1549	<param name="IPAddress" type="wstring" dir="in">
1550	<desc>
1551	server IP address
1552	</desc>
1553	</param>
1554	<param name="networkMask" type="wstring" dir="in">
1555	<desc>
1556	server network mask
1557	</desc>
1558	</param>
1559	<param name="FromIPAddress" type="wstring" dir="in">
1560	<desc>
1561	server From IP address for address range
1562	</desc>
1563	</param>
1564	<param name="ToIPAddress" type="wstring" dir="in">
1565	<desc>
1566	server To IP address for address range
1567	</desc>
1568	</param>
1569	</method>
1570
1571	<method name="start">
1572	<desc>
1573	Starts DHCP server process.
1574	<result name="E_FAIL">
1575	Failed to start the process.
1576	</result>
1577	</desc>
1578	<param name="networkName" type="wstring" dir="in">
1579	<desc>
1580	Name of internal network DHCP server should attach to.
1581	</desc>
1582	</param>
1583	<param name="trunkName" type="wstring" dir="in">
1584	<desc>
1585	Name of internal network trunk.
1586	</desc>
1587	</param>
1588	<param name="trunkType" type="wstring" dir="in">
1589	<desc>
1590	Type of internal network trunk.
1591	</desc>
1592	</param>
1593	</method>
1594
1595	<method name="stop">
1596	<desc>
1597	Stops DHCP server process.
1598	<result name="E_FAIL">
1599	Failed to stop the process.
1600	</result>
1601	</desc>
1602	</method>
1603	</interface>
1604
1605	<interface
1606	name="IVirtualBox" extends="$unknown"
1607	uuid="3f36e024-7fed-4f20-a02c-9158a82b44e6"
1608	wsmap="managed"
1609	>
1610	<desc>
1611	The IVirtualBox interface represents the main interface exposed by the
1612	product that provides virtual machine management.
1613
1614	An instance of IVirtualBox is required for the product to do anything
1615	useful. Even though the interface does not expose this, internally,
1616	IVirtualBox is implemented as a singleton and actually lives in the
1617	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1618	IVirtualBox can track the state of all virtual machines on a particular
1619	host, regardless of which frontend started them.
1620
1621	To enumerate all the virtual machines on the host, use the
1622	<link to="IVirtualBox::machines"/> attribute.
1623	</desc>
1624
1625	<attribute name="version" type="wstring" readonly="yes">
1626	<desc>
1627	A string representing the version number of the product. The
1628	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1629	last number represents the build number and will frequently change.
1630	</desc>
1631	</attribute>
1632
1633	<attribute name="revision" type="unsigned long" readonly="yes">
1634	<desc>
1635	The internal build revision number of the product.
1636	</desc>
1637	</attribute>
1638
1639	<attribute name="packageType" type="wstring" readonly="yes">
1640	<desc>
1641	A string representing the package type of this product. The
1642	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1643	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1644	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1645	this.
1646	</desc>
1647	</attribute>
1648
1649	<attribute name="homeFolder" type="wstring" readonly="yes">
1650	<desc>
1651	Full path to the directory where the global settings file,
1652	<tt>VirtualBox.xml</tt>, is stored.
1653
1654	In this version of VirtualBox, the value of this property is
1655	always <tt><user_dir>/.VirtualBox</tt> (where
1656	<tt><user_dir></tt> is the path to the user directory,
1657	as determined by the host OS), and cannot be changed.
1658
1659	This path is also used as the base to resolve relative paths in
1660	places where relative paths are allowed (unless otherwise
1661	expressly indicated).
1662	</desc>
1663	</attribute>
1664
1665	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1666	<desc>
1667	Full name of the global settings file.
1668	The value of this property corresponds to the value of
1669	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1670	</desc>
1671	</attribute>
1672
1673	<attribute name="host" type="IHost" readonly="yes">
1674	<desc>Associated host object.</desc>
1675	</attribute>
1676
1677	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1678	<desc>Associated system information object.</desc>
1679	</attribute>
1680
1681	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1682	<desc>
1683	Array of machine objects registered within this VirtualBox instance.
1684	</desc>
1685	</attribute>
1686
1687	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1688	<desc>
1689	Array of medium objects known to this VirtualBox installation.
1690
1691	This array contains only base media. All differencing
1692	media of the given base medium can be enumerated using
1693	<link to="IMedium::children"/>.
1694	</desc>
1695	</attribute>
1696
1697	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1698	<desc>
1699	Array of CD/DVD image objects registered with this VirtualBox instance.
1700	</desc>
1701	</attribute>
1702
1703	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1704	<desc>
1705	Array of floppy image objects registered with this VirtualBox instance.
1706	</desc>
1707	</attribute>
1708
1709	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1710
1711	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1712
1713	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1714	<desc>
1715	Collection of global shared folders. Global shared folders are
1716	available to all virtual machines.
1717
1718	New shared folders are added to the collection using
1719	<link to="#createSharedFolder"/>. Existing shared folders can be
1720	removed using <link to="#removeSharedFolder"/>.
1721
1722	<note>
1723	In the current version of the product, global shared folders are not
1724	implemented and therefore this collection is always empty.
1725	</note>
1726	</desc>
1727	</attribute>
1728
1729	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1730	<desc>
1731	Associated performance collector object.
1732	</desc>
1733	</attribute>
1734
1735	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1736	<desc>
1737	dhcp server settings.
1738	</desc>
1739	</attribute>
1740
1741	<method name="createMachine">
1742	<desc>
1743	Creates a new virtual machine.
1744
1745	The new machine is created unregistered, with the initial configuration
1746	set according to the specified guest OS type. A typical sequence of
1747	actions to create a new virtual machine is as follows:
1748
1749	<ol>
1750	<li>
1751	Call this method to have a new machine created. The returned machine
1752	object will be "mutable" allowing to change any machine property.
1753	</li>
1754
1755	<li>
1756	Configure the machine using the appropriate attributes and methods.
1757	</li>
1758
1759	<li>
1760	Call <link to="IMachine::saveSettings" /> to write the settings
1761	to the machine's XML settings file. The configuration of the newly
1762	created machine will not be saved to disk until this method is
1763	called.
1764	</li>
1765
1766	<li>
1767	Call <link to="#registerMachine" /> to add the machine to the list
1768	of machines known to VirtualBox.
1769	</li>
1770	</ol>
1771
1772	You should specify valid name for the newly created machine when calling
1773	this method. See the <link to="IMachine::name"/> attribute description
1774	for more details about the machine name.
1775
1776	The specified guest OS type identifier must match an ID of one of known
1777	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1778	array.
1779
1780	Every machine has a <i>settings file</i> that is used to store
1781	the machine configuration. This file is stored in a directory called the
1782	<i>machine settings subfolder</i>. Both the settings subfolder and file
1783	will have a name that corresponds to the name of the virtual machine.
1784	You can specify where to create the machine setting subfolder using the
1785	@a baseFolder argument. The base folder can be absolute (full path) or
1786	relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1787	directory</link>.
1788
1789	If @a baseFolder is a @c null or empty string (which is recommended), the
1790	<link to="ISystemProperties::defaultMachineFolder">default machine
1791	settings folder</link> will be used as a base folder for the created
1792	machine. Otherwise the given base folder will be used. In either case,
1793	the full path to the resulting settings file has the following
1794	structure:
1795	<pre>
1796	<base_folder>/<machine_name>/<machine_name>.xml
1797	</pre>
1798
1799	Note that if the resulting settings file already exists, this method
1800	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1801
1802	Optionally, you may specify an UUID of to assign to the created machine.
1803	However, this is not recommended and you should normally pass an empty
1804	(@c null) UUID to this method so that a new UUID will be automatically
1805	generated for every created machine. You can use UUID
1806	00000000-0000-0000-0000-000000000000 as @c null value.
1807
1808	<note>
1809	There is no way to change the name of the settings file or
1810	subfolder of the created machine directly.
1811	</note>
1812
1813	<result name="VBOX_E_OBJECT_NOT_FOUND">
1814	@a osTypeId is invalid.
1815	</result>
1816	<result name="VBOX_E_FILE_ERROR">
1817	Resulting settings file name is invalid or the settings file already
1818	exists or could not be created due to an I/O error.
1819	</result>
1820	<result name="E_INVALIDARG">
1821	@a name is empty or @c null.
1822	</result>
1823	</desc>
1824
1825	<param name="name" type="wstring" dir="in">
1826	<desc>Machine name.</desc>
1827	</param>
1828	<param name="osTypeId" type="wstring" dir="in">
1829	<desc>Guest OS Type ID.</desc>
1830	</param>
1831	<param name="baseFolder" type="wstring" dir="in">
1832	<desc>Base machine folder (optional).</desc>
1833	</param>
1834	<param name="id" type="uuid" mod="string" dir="in">
1835	<desc>Machine UUID (optional).</desc>
1836	</param>
1837	<param name="override" type="boolean" dir="in">
1838	<desc>Create the VM even if there are conflicting files.</desc>
1839	</param>
1840	<param name="machine" type="IMachine" dir="return">
1841	<desc>Created machine object.</desc>
1842	</param>
1843	</method>
1844
1845	<method name="createLegacyMachine">
1846	<desc>
1847	Creates a new virtual machine in "legacy" mode, using the specified
1848	settings file to store machine settings.
1849
1850	As opposed to machines created by <link to="#createMachine"/>,
1851	the settings file of the machine created in "legacy" mode is not
1852	automatically renamed when the machine name is changed -- it will always
1853	remain the same as specified in this method call.
1854
1855	The specified settings file name can be absolute (full path) or relative
1856	to the <link to="IVirtualBox::homeFolder">VirtualBox home
1857	directory</link>. If the file name doesn't contain an extension, the
1858	default extension (.xml) will be appended.
1859
1860	Note that the configuration of the newly created machine is not
1861	saved to disk (and therefore no settings file is created)
1862	until <link to="IMachine::saveSettings"/> is called. If the
1863	specified settings file already exists, this method
1864	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1865
1866	See <link to="#createMachine"/> for more information.
1867
1868	@deprecated This method may be removed later. Use <link
1869	to="IVirtualBox::createMachine"/> instead.
1870
1871	<note>
1872	There is no way to change the name of the settings file
1873	of the machine created in "legacy" mode.
1874	</note>
1875
1876	<result name="VBOX_E_OBJECT_NOT_FOUND">
1877	@a osTypeId is invalid.
1878	</result>
1879	<result name="VBOX_E_FILE_ERROR">
1880	@a settingsFile is invalid or the settings file already exists or
1881	could not be created due to an I/O error.
1882	</result>
1883	<result name="E_INVALIDARG">
1884	@a name or @a settingsFile is empty or @c null.
1885	</result>
1886	</desc>
1887
1888	<param name="name" type="wstring" dir="in">
1889	<desc>Machine name.</desc>
1890	</param>
1891	<param name="osTypeId" type="wstring" dir="in">
1892	<desc>Machine OS Type ID.</desc>
1893	</param>
1894	<param name="settingsFile" type="wstring" dir="in">
1895	<desc>Name of the machine settings file.</desc>
1896	</param>
1897	<param name="id" type="uuid" mod="string" dir="in">
1898	<desc>Machine UUID (optional).</desc>
1899	</param>
1900	<param name="machine" type="IMachine" dir="return">
1901	<desc>Created machine object.</desc>
1902	</param>
1903	</method>
1904
1905	<method name="openMachine">
1906	<desc>
1907	Opens a virtual machine from the existing settings file.
1908	The opened machine remains unregistered until you call
1909	<link to="#registerMachine"/>.
1910
1911	The specified settings file name can be absolute
1912	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1913	VirtualBox home directory</link>. This file must exist
1914	and must be a valid machine settings file whose contents
1915	will be used to construct the machine object.
1916
1917	@deprecated Will be removed soon.
1918	<result name="VBOX_E_FILE_ERROR">
1919	Settings file name invalid, not found or sharing violation.
1920	</result>
1921	</desc>
1922	<param name="settingsFile" type="wstring" dir="in">
1923	<desc>
1924	Name of the machine settings file.
1925	</desc>
1926	</param>
1927	<param name="machine" type="IMachine" dir="return">
1928	<desc>Opened machine object.</desc>
1929	</param>
1930	<note>
1931	<link to="IMachine::settingsModified"/> will return
1932	@c false for the created machine, until any of machine settings
1933	are changed.
1934	</note>
1935	</method>
1936
1937	<method name="registerMachine">
1938	<desc>
1939
1940	Registers the machine previously created using
1941	<link to="#createMachine"/> or opened using
1942	<link to="#openMachine"/> within this VirtualBox installation. After
1943	successful method invocation, the
1944	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1945	to all registered callbacks.
1946
1947	<note>
1948	This method implicitly calls <link to="IMachine::saveSettings"/>
1949	to save all current machine settings before registering it.
1950	</note>
1951
1952	<result name="VBOX_E_OBJECT_NOT_FOUND">
1953	No matching virtual machine found.
1954	</result>
1955	<result name="VBOX_E_INVALID_OBJECT_STATE">
1956	Virtual machine was not created within this VirtualBox instance.
1957	</result>
1958
1959	</desc>
1960	<param name="machine" type="IMachine" dir="in"/>
1961	</method>
1962
1963	<method name="getMachine">
1964	<desc>
1965	Attempts to find a virtual machine given its UUID.
1966	To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1967	instead.
1968
1969	<result name="VBOX_E_OBJECT_NOT_FOUND">
1970	Could not find registered machine matching @a id.
1971	</result>
1972
1973	</desc>
1974	<param name="id" type="uuid" mod="string" dir="in"/>
1975	<param name="machine" type="IMachine" dir="return"/>
1976	</method>
1977
1978	<method name="findMachine">
1979	<desc>
1980	Attempts to find a virtual machine given its name.
1981	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1982	instead.
1983
1984	<result name="VBOX_E_OBJECT_NOT_FOUND">
1985	Could not find registered machine matching @a name.
1986	</result>
1987
1988	</desc>
1989	<param name="name" type="wstring" dir="in"/>
1990	<param name="machine" type="IMachine" dir="return"/>
1991	</method>
1992
1993	<method name="unregisterMachine">
1994	<desc>
1995
1996	Unregisters the machine previously registered using
1997	<link to="#registerMachine"/>. After successful method invocation, the
1998	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1999	to all registered callbacks.
2000
2001	<note>
2002	The specified machine must not be in the Saved state, have an open
2003	(or a spawning) direct session associated with it, have snapshots or
2004	have any medium attached.
2005	</note>
2006
2007	<note>
2008	This method implicitly calls <link to="IMachine::saveSettings"/> to
2009	save all current machine settings before unregistering it.
2010	</note>
2011
2012	<note>
2013	If the given machine is inaccessible (see
2014	<link to="IMachine::accessible"/>), it will be unregistered and
2015	fully uninitialized right afterwards. As a result, the returned
2016	machine object will be unusable and an attempt to call
2017	<b>any</b> method will return the "Object not ready" error.
2018	</note>
2019
2020	<result name="VBOX_E_OBJECT_NOT_FOUND">
2021	Could not find registered machine matching @a id.
2022	</result>
2023	<result name="VBOX_E_INVALID_VM_STATE">
2024	Machine is in Saved state.
2025	</result>
2026	<result name="VBOX_E_INVALID_OBJECT_STATE">
2027	Machine has snapshot or open session or medium attached.
2028	</result>
2029
2030	</desc>
2031	<param name="id" type="uuid" mod="string" dir="in">
2032	<desc>UUID of the machine to unregister.</desc>
2033	</param>
2034	<param name="machine" type="IMachine" dir="return">
2035	<desc>Unregistered machine object.</desc>
2036	</param>
2037	</method>
2038
2039	<method name="createAppliance">
2040	<desc>
2041	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
2042	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
2043	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
2044	</desc>
2045	<param name="appliance" type="IAppliance" dir="return">
2046	<desc>New appliance.</desc>
2047	</param>
2048	</method>
2049
2050	<method name="createHardDisk">
2051	<desc>
2052	Creates a new base medium object that will use the given storage
2053	format and location for medium data.
2054
2055	Note that the actual storage unit is not created by this method. In
2056	order to do it, and before you are able to attach the created medium
2057	to virtual machines, you must call one of the following methods to
2058	allocate a format-specific storage unit at the specified location:
2059	<ul>
2060	<li><link to="IMedium::createBaseStorage"/></li>
2061	<li><link to="IMedium::createDiffStorage"/></li>
2062	</ul>
2063
2064	Some medium attributes, such as <link to="IMedium::id"/>, may
2065	remain uninitialized until the medium storage unit is successfully
2066	created by one of the above methods.
2067
2068	After the storage unit is successfully created, the medium gets
2069	remembered by this VirtualBox installation and will be accessible
2070	through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
2071	methods. Remembered base medium are also returned as part of
2072	the <link to="#hardDisks"/> array. See IMedium for more details.
2073
2074	The list of all storage formats supported by this VirtualBox
2075	installation can be obtained using
2076	<link to="ISystemProperties::mediumFormats"/>. If the @a format
2077	attribute is empty or @c null then the default storage format
2078	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
2079	be used for creating a storage unit of the medium.
2080
2081	Note that the format of the location string is storage format specific.
2082	See <link to="IMedium::location"/>, IMedium and
2083	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2084
2085	<result name="VBOX_E_OBJECT_NOT_FOUND">
2086	@a format identifier is invalid. See
2087	<link to="ISystemProperties::mediumFormats"/>.
2088	</result>
2089	<result name="VBOX_E_FILE_ERROR">
2090	@a location is a not valid file name (for file-based formats only).
2091	</result>
2092	</desc>
2093	<param name="format" type="wstring" dir="in">
2094	<desc>
2095	Identifier of the storage format to use for the new medium.
2096	</desc>
2097	</param>
2098	<param name="location" type="wstring" dir="in">
2099	<desc>
2100	Location of the storage unit for the new medium.
2101	</desc>
2102	</param>
2103	<param name="medium" type="IMedium" dir="return">
2104	<desc>Created medium object.</desc>
2105	</param>
2106	</method>
2107
2108	<method name="openHardDisk">
2109	<desc>
2110	Opens a medium from an existing location, optionally replacing
2111	the image UUID and/or parent UUID.
2112
2113	After the medium is successfully opened by this method, it gets
2114	remembered by (known to) this VirtualBox installation and will be
2115	accessible through <link to="#getHardDisk"/> and
2116	<link to="#findHardDisk"/> methods. Remembered base media
2117	are also returned as part of the <link to="#hardDisks"/> array and can
2118	be attached to virtual machines. See IMedium for more details.
2119
2120	If a differencing medium is to be opened by this method, the
2121	operation will succeed only if its parent medium and all ancestors,
2122	if any, are already known to this VirtualBox installation (for example,
2123	were opened by this method before).
2124
2125	This method tries to guess the storage format of the specified medium
2126	by reading medium data at the specified location.
2127
2128	If @a accessMode is ReadWrite (which it should be), the image is opened
2129	for read/write access and must have according permissions, as VirtualBox
2130	may actually write status information into the disk's metadata sections.
2131
2132	Note that write access is required for all typical image usage in VirtualBox,
2133	since VirtualBox may need to write metadata such as a UUID into the image.
2134	The only exception is opening a source image temporarily for copying and
2135	cloning when the image will quickly be closed again.
2136
2137	Note that the format of the location string is storage format specific.
2138	See <link to="IMedium::location"/>, IMedium and
2139	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2140
2141	<result name="VBOX_E_FILE_ERROR">
2142	Invalid medium storage file location or could not find the medium
2143	at the specified location.
2144	</result>
2145	<result name="VBOX_E_IPRT_ERROR">
2146	Could not get medium storage format.
2147	</result>
2148	<result name="E_INVALIDARG">
2149	Invalid medium storage format.
2150	</result>
2151
2152	</desc>
2153	<param name="location" type="wstring" dir="in">
2154	<desc>
2155	Location of the storage unit that contains medium data in one of
2156	the supported storage formats.
2157	</desc>
2158	</param>
2159	<param name="accessMode" type="AccessMode" dir="in">
2160	<desc>
2161	Determines whether to open the image in read/write or read-only mode.
2162	</desc>
2163	</param>
2164	<param name="setImageId" type="boolean" dir="in">
2165	<desc>
2166	Select whether a new image UUID is set or not.
2167	</desc>
2168	</param>
2169	<param name="imageId" type="uuid" mod="string" dir="in">
2170	<desc>
2171	New UUID for the image. If an empty string is passed, then a new
2172	UUID is automatically created. Specifying a zero UUIDs is not valid.
2173	</desc>
2174	</param>
2175	<param name="setParentId" type="boolean" dir="in">
2176	<desc>
2177	Select whether a new parent UUID is set or not.
2178	</desc>
2179	</param>
2180	<param name="parentId" type="uuid" mod="string" dir="in">
2181	<desc>
2182	New parent UUID for the image. If an empty string is passed, then a
2183	new UUID is automatically created, provided @a setParentId is
2184	@c true. A zero UUID is valid.
2185	</desc>
2186	</param>
2187	<param name="medium" type="IMedium" dir="return">
2188	<desc>Opened medium object.</desc>
2189	</param>
2190	</method>
2191
2192	<method name="getHardDisk" const="yes">
2193	<desc>
2194	Returns a medium with the given UUID.
2195
2196	The medium with the given UUID must be known to this VirtualBox
2197	installation, i.e. it must be previously created by
2198	<link to="#createHardDisk"/> or opened by <link
2199	to="#openHardDisk"/>, or attached to some known virtual machine.
2200
2201	<result name="VBOX_E_OBJECT_NOT_FOUND">
2202	No medium object matching @a id found.
2203	</result>
2204
2205	</desc>
2206	<param name="id" type="uuid" mod="string" dir="in">
2207	<desc>UUID of the medium to look for.</desc>
2208	</param>
2209	<param name="medium" type="IMedium" dir="return">
2210	<desc>Found medium object.</desc>
2211	</param>
2212	</method>
2213
2214	<method name="findHardDisk">
2215	<desc>
2216	Returns a medium that uses the given location to store medium data.
2217
2218	The given medium must be known to this VirtualBox installation, i.e.
2219	it must be previously created by
2220	<link to="#createHardDisk"/> or opened by <link
2221	to="#openHardDisk"/>, or attached to some known virtual machine.
2222
2223	The search is done by comparing the value of the @a location argument to
2224	the <link to="IMedium::location"/> attribute of each known medium.
2225
2226	For locations represented by file names in the host's file system, the
2227	requested location can be a path relative to the
2228	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2229	only a file name without any path is given, the
2230	<link to="ISystemProperties::defaultHardDiskFolder"> default medium
2231	folder</link> will be prepended to the file name before searching. Note
2232	that on case sensitive file systems, a case sensitive comparison is
2233	performed, otherwise the case of symbols in the file path is ignored.
2234
2235	<result name="VBOX_E_OBJECT_NOT_FOUND">
2236	No medium object matching @a location found.
2237	</result>
2238
2239	</desc>
2240	<param name="location" type="wstring" dir="in">
2241	<desc>Location string to search for.</desc>
2242	</param>
2243	<param name="medium" type="IMedium" dir="return">
2244	<desc>Found medium object.</desc>
2245	</param>
2246	</method>
2247
2248	<method name="openDVDImage">
2249	<desc>
2250	Opens a CD/DVD image contained in the specified file of the supported
2251	format and assigns it the given UUID.
2252
2253	After the image is successfully opened by this method, it gets
2254	remembered by (known to) this VirtualBox installation and will be
2255	accessible through <link to="#getDVDImage"/> and
2256	<link to="#findDVDImage"/> methods. Remembered images are also
2257	returned as part of the <link to="#DVDImages"/> array and can be mounted
2258	to virtual machines. See IMedium for more details.
2259
2260	See <link to="IMedium::location"/> to get more details about the format
2261	of the location string.
2262
2263	<note>
2264	Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
2265	</note>
2266
2267	<result name="VBOX_E_FILE_ERROR">
2268	Invalid CD/DVD image file location or could not find the CD/DVD
2269	image at the specified location.
2270	</result>
2271	<result name="VBOX_E_INVALID_OBJECT_STATE">
2272	CD/DVD image already exists in the media registry.
2273	</result>
2274
2275	</desc>
2276	<param name="location" type="wstring" dir="in">
2277	<desc>
2278	Full path to the file that contains a valid CD/DVD image.
2279	</desc>
2280	</param>
2281	<param name="id" type="uuid" mod="string" dir="in">
2282	<desc>
2283	UUID to assign to the given image within this VirtualBox installation.
2284	If an empty (@c null) UUID is specified, the system will randomly
2285	generate a new UUID.
2286	</desc>
2287	</param>
2288	<param name="image" type="IMedium" dir="return">
2289	<desc>Opened CD/DVD image object.</desc>
2290	</param>
2291	</method>
2292
2293	<method name="getDVDImage">
2294	<desc>
2295	Returns a CD/DVD image with the given UUID.
2296
2297	The image with the given UUID must be known to this VirtualBox
2298	installation, i.e. it must be previously opened by <link
2299	to="#openDVDImage"/>, or mounted to some known virtual machine.
2300
2301	<result name="VBOX_E_OBJECT_NOT_FOUND">
2302	No matching DVD image found in the media registry.
2303	</result>
2304
2305	</desc>
2306	<param name="id" type="uuid" mod="string" dir="in">
2307	<desc>UUID of the image to look for.</desc>
2308	</param>
2309	<param name="image" type="IMedium" dir="return">
2310	<desc>Found CD/DVD image object.</desc>
2311	</param>
2312	</method>
2313
2314	<method name="findDVDImage">
2315	<desc>
2316	Returns a CD/DVD image with the given image location.
2317
2318	The image with the given UUID must be known to this VirtualBox
2319	installation, i.e. it must be previously opened by <link
2320	to="#openDVDImage"/>, or mounted to some known virtual machine.
2321
2322	The search is done by comparing the value of the @a location argument to
2323	the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2324
2325	The requested location can be a path relative to the
2326	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2327	only a file name without any path is given, the
2328	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2329	folder</link> will be prepended to the file name before searching. Note
2330	that on case sensitive file systems, a case sensitive comparison is
2331	performed, otherwise the case in the file path is ignored.
2332
2333	<result name="VBOX_E_FILE_ERROR">
2334	Invalid image file location.
2335	</result>
2336	<result name="VBOX_E_OBJECT_NOT_FOUND">
2337	No matching DVD image found in the media registry.
2338	</result>
2339
2340	</desc>
2341	<param name="location" type="wstring" dir="in">
2342	<desc>CD/DVD image file path to look for.</desc>
2343	</param>
2344	<param name="image" type="IMedium" dir="return">
2345	<desc>Found CD/DVD image object.</desc>
2346	</param>
2347	</method>
2348
2349	<method name="openFloppyImage">
2350	<desc>
2351	Opens a floppy image contained in the specified file of the supported
2352	format and assigns it the given UUID.
2353
2354	After the image is successfully opened by this method, it gets
2355	remembered by (known to) this VirtualBox installation and will be
2356	accessible through <link to="#getFloppyImage"/> and
2357	<link to="#findFloppyImage"/> methods. Remembered images are also
2358	returned as part of the <link to="#floppyImages"/> array and can be
2359	mounted to virtual machines. See IMedium for more details.
2360
2361	See <link to="IMedium::location"/> to get more details about the format
2362	of the location string.
2363
2364	<result name="VBOX_E_FILE_ERROR">
2365	Invalid floppy image file location or could not find the floppy
2366	image at the specified location.
2367	</result>
2368	<result name="VBOX_E_INVALID_OBJECT_STATE">
2369	Floppy image already exists in the media registry.
2370	</result>
2371
2372	<note>
2373	Currently, only raw floppy images are supported by VirtualBox.
2374	</note>
2375	</desc>
2376	<param name="location" type="wstring" dir="in">
2377	<desc>
2378	Full path to the file that contains a valid floppy image.
2379	</desc>
2380	</param>
2381	<param name="id" type="uuid" mod="string" dir="in">
2382	<desc>
2383	UUID to assign to the given image file within this VirtualBox
2384	installation. If an empty (@c null) UUID is specified, the system will
2385	randomly generate a new UUID.
2386	</desc>
2387	</param>
2388	<param name="image" type="IMedium" dir="return">
2389	<desc>Opened floppy image object.</desc>
2390	</param>
2391	</method>
2392
2393	<method name="getFloppyImage">
2394	<desc>
2395	Returns a floppy image with the given UUID.
2396
2397	The image with the given UUID must be known to this VirtualBox
2398	installation, i.e. it must be previously opened by <link
2399	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2400
2401	<result name="VBOX_E_OBJECT_NOT_FOUND">
2402	No matching floppy image found in the media registry.
2403	</result>
2404
2405	</desc>
2406	<param name="id" type="uuid" mod="string" dir="in">
2407	<desc>UUID of the image to look for.</desc>
2408	</param>
2409	<param name="image" type="IMedium" dir="return">
2410	<desc>Found floppy image object.</desc>
2411	</param>
2412	</method>
2413
2414	<method name="findFloppyImage">
2415	<desc>
2416	Returns a floppy image with the given image location.
2417
2418	The image with the given UUID must be known to this VirtualBox
2419	installation, i.e. it must be previously opened by <link
2420	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2421
2422	The search is done by comparing the value of the @a location argument to
2423	the <link to="IMedium::location"/> attribute of each known floppy image.
2424
2425	The requested location can be a path relative to the
2426	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2427	only a file name without any path is given, the
2428	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2429	folder</link> will be prepended to the file name before searching. Note
2430	that on case sensitive file systems, a case sensitive comparison is
2431	performed, otherwise the case of symbols in the file path is ignored.
2432
2433	<result name="VBOX_E_FILE_ERROR">
2434	Invalid image file location.
2435	</result>
2436	<result name="VBOX_E_OBJECT_NOT_FOUND">
2437	No matching floppy image found in the media registry.
2438	</result>
2439
2440	</desc>
2441	<param name="location" type="wstring" dir="in">
2442	<desc>Floppy image file path to look for.</desc>
2443	</param>
2444	<param name="image" type="IMedium" dir="return">
2445	<desc>Found floppy image object.</desc>
2446	</param>
2447	</method>
2448
2449	<method name="getGuestOSType">
2450	<desc>
2451	Returns an object describing the specified guest OS type.
2452
2453	The requested guest OS type is specified using a string which is a
2454	mnemonic identifier of the guest operating system, such as
2455	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2456	particular virtual machine can be read or set using the
2457	<link to="IMachine::OSTypeId"/> attribute.
2458
2459	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2460	available guest OS type objects. Each object has an
2461	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2462	the guest OS this object describes.
2463
2464	<result name="E_INVALIDARG">
2465	@a id is not a valid Guest OS type.
2466	</result>
2467
2468	</desc>
2469	<param name="id" type="uuid" mod="string" dir="in">
2470	<desc>Guest OS type ID string.</desc>
2471	</param>
2472	<param name="type" type="IGuestOSType" dir="return">
2473	<desc>Guest OS type object.</desc>
2474	</param>
2475	</method>
2476
2477	<method name="createSharedFolder">
2478	<desc>
2479	Creates a new global shared folder by associating the given logical
2480	name with the given host path, adds it to the collection of shared
2481	folders and starts sharing it. Refer to the description of
2482	<link to="ISharedFolder"/> to read more about logical names.
2483	<note>
2484	In the current implementation, this operation is not
2485	implemented.
2486	</note>
2487	</desc>
2488	<param name="name" type="wstring" dir="in">
2489	<desc>Unique logical name of the shared folder.</desc>
2490	</param>
2491	<param name="hostPath" type="wstring" dir="in">
2492	<desc>Full path to the shared folder in the host file system.</desc>
2493	</param>
2494	<param name="writable" type="boolean" dir="in">
2495	<desc>Whether the share is writable or readonly</desc>
2496	</param>
2497	</method>
2498
2499	<method name="removeSharedFolder">
2500	<desc>
2501	Removes the global shared folder with the given name previously
2502	created by <link to="#createSharedFolder"/> from the collection of
2503	shared folders and stops sharing it.
2504	<note>
2505	In the current implementation, this operation is not
2506	implemented.
2507	</note>
2508	</desc>
2509	<param name="name" type="wstring" dir="in">
2510	<desc>Logical name of the shared folder to remove.</desc>
2511	</param>
2512	</method>
2513
2514	<method name="getExtraDataKeys">
2515	<desc>
2516	Returns an array representing the global extra data keys which currently
2517	have values defined.
2518	</desc>
2519	<param name="value" type="wstring" dir="return" safearray="yes">
2520	<desc>Array of extra data keys.</desc>
2521	</param>
2522	</method>
2523
2524	<method name="getExtraData">
2525	<desc>
2526	Returns associated global extra data.
2527
2528	If the requested data @a key does not exist, this function will
2529	succeed and return an empty string in the @a value argument.
2530
2531	<result name="VBOX_E_FILE_ERROR">
2532	Settings file not accessible.
2533	</result>
2534	<result name="VBOX_E_XML_ERROR">
2535	Could not parse the settings file.
2536	</result>
2537
2538	</desc>
2539	<param name="key" type="wstring" dir="in">
2540	<desc>Name of the data key to get.</desc>
2541	</param>
2542	<param name="value" type="wstring" dir="return">
2543	<desc>Value of the requested data key.</desc>
2544	</param>
2545	</method>
2546
2547	<method name="setExtraData">
2548	<desc>
2549	Sets associated global extra data.
2550
2551	If you pass @c null or empty string as a key @a value, the given @a key
2552	will be deleted.
2553
2554	<note>
2555	Before performing the actual data change, this method will ask all
2556	registered callbacks using the
2557	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2558	notification for a permission. If one of the callbacks refuses the
2559	new value, the change will not be performed.
2560	</note>
2561	<note>
2562	On success, the
2563	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2564	is called to inform all registered callbacks about a successful data
2565	change.
2566	</note>
2567
2568	<result name="VBOX_E_FILE_ERROR">
2569	Settings file not accessible.
2570	</result>
2571	<result name="VBOX_E_XML_ERROR">
2572	Could not parse the settings file.
2573	</result>
2574	<result name="E_ACCESSDENIED">
2575	Modification request refused.
2576	</result>
2577
2578	</desc>
2579	<param name="key" type="wstring" dir="in">
2580	<desc>Name of the data key to set.</desc>
2581	</param>
2582	<param name="value" type="wstring" dir="in">
2583	<desc>Value to assign to the key.</desc>
2584	</param>
2585	</method>
2586
2587	<method name="openSession">
2588	<desc>
2589	Opens a new direct session with the given virtual machine.
2590
2591	A direct session acts as a local lock on the given VM.
2592	There can be only one direct session open at a time for every
2593	virtual machine, protecting the VM from being manipulated by
2594	conflicting actions from different processes. Only after a
2595	direct session has been opened, one can change all VM settings
2596	and execute the VM in the process space of the session object.
2597
2598	Sessions therefore can be compared to mutex semaphores that
2599	lock a given VM for modification and execution.
2600	See <link to="ISession">ISession</link> for details.
2601
2602	<note>Unless you are writing a new VM frontend, you will not
2603	want to execute a VM in the current process. To spawn a new
2604	process that executes a VM, use
2605	<link to="IVirtualBox::openRemoteSession" />
2606	instead.</note>
2607
2608	Upon successful return, the session object can be used to
2609	get access to the machine and to the VM console.
2610
2611	In VirtualBox terminology, the machine becomes "mutable" after
2612	a session has been opened. Note that the "mutable" machine
2613	object, on which you may invoke IMachine methods to change its
2614	settings, will be a different object from the immutable IMachine
2615	objects returned by various IVirtualBox methods. To obtain a
2616	mutable IMachine object (upon which you can invoke settings methods),
2617	use the <link to="ISession::machine" /> attribute.
2618
2619	One must always call <link to="ISession::close" /> to release the
2620	lock on the machine, or the machine's state will eventually be
2621	set to "Aborted".
2622
2623	In other words, to change settings on a machine, the following
2624	sequence is typically performed:
2625
2626	<ol>
2627	<li>Call this method (openSession) to have a machine locked for
2628	the current session.</li>
2629
2630	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2631
2632	<li>Change the settings of the machine.</li>
2633
2634	<li>Call <link to="IMachine::saveSettings" />.</li>
2635
2636	<li>Close the session by calling <link to="ISession::close"/>.</li>
2637	</ol>
2638
2639	<result name="E_UNEXPECTED">
2640	Virtual machine not registered.
2641	</result>
2642	<result name="E_ACCESSDENIED">
2643	Process not started by OpenRemoteSession.
2644	</result>
2645	<result name="VBOX_E_OBJECT_NOT_FOUND">
2646	No matching virtual machine found.
2647	</result>
2648	<result name="VBOX_E_INVALID_OBJECT_STATE">
2649	Session already open or being opened.
2650	</result>
2651	<result name="VBOX_E_VM_ERROR">
2652	Failed to assign machine to session.
2653	</result>
2654
2655	</desc>
2656	<param name="session" type="ISession" dir="in">
2657	<desc>
2658	Session object that will represent the opened session after
2659	successful method invocation. This object must not represent
2660	the already open session.
2661	<note>
2662	This session will be automatically closed if the
2663	VirtualBox server is terminated for some reason.
2664	</note>
2665	</desc>
2666	</param>
2667	<param name="machineId" type="uuid" mod="string" dir="in">
2668	<desc>ID of the virtual machine to open a session with.</desc>
2669	</param>
2670	</method>
2671
2672	<method name="openRemoteSession">
2673	<desc>
2674	Spawns a new process that executes a virtual machine (called a
2675	"remote session").
2676
2677	Opening a remote session causes the VirtualBox server to start a new
2678	process that opens a direct session with the given VM. As a result, the
2679	VM is locked by that direct session in the new process, preventing
2680	conflicting changes from other processes. Since sessions act as locks
2681	that prevent conflicting changes, one cannot open a remote session
2682	for a VM that already has another open session (direct or remote), or
2683	is currently in the process of opening one (see <link
2684	to="IMachine::sessionState"/>).
2685
2686	While the remote session still provides some level of control over the
2687	VM execution to the caller (using the <link to="IConsole" /> interface),
2688	not all VM settings are available for modification within the remote
2689	session context.
2690
2691	This operation can take some time (a new VM is started in a new process,
2692	for which memory and other resources need to be set up). Because of this,
2693	an <link to="IProgress" /> is returned to allow the caller to wait for this
2694	asynchronous operation to be completed. Until then, the remote session
2695	object remains in the closed state, and accessing the machine or its
2696	console through it is invalid. It is recommended to use
2697	<link to="IProgress::waitForCompletion" /> or similar calls to wait for
2698	completion. Completion is signalled when the VM is powered on. Error
2699	messages etc. can be queried via the progress object, if available.
2700
2701	As with all <link to="ISession" /> objects, it is recommended to call
2702	<link to="ISession::close" /> on the local session object once openRemoteSession()
2703	has been called. However, the session's state (see <link to="ISession::state" />)
2704	will not return to "Closed" until the remote session has also closed (i.e.
2705	until the VM is no longer running). In that case, however, the state of
2706	the session will automatically change back to "Closed".
2707
2708	Currently supported session types (values of the @a type
2709	argument) are:
2710	<ul>
2711	<li><tt>"gui"</tt>: VirtualBox Qt GUI session</li>
2712	<li><tt>"vrdp"</tt>: VirtualBox VRDP Server session</li>
2713	<li><tt>"sdl"</tt>: VirtualBox SDL GUI session</li>
2714	</ul>
2715
2716	The @a environment argument is a string containing definitions of
2717	environment variables in the following format:
2718	@code
2719	NAME[=VALUE]\n
2720	NAME[=VALUE]\n
2721	...
2722	@endcode
2723	where <tt>\\n</tt> is the new line character. These environment
2724	variables will be appended to the environment of the VirtualBox server
2725	process. If an environment variable exists both in the server process
2726	and in this list, the value from this list takes precedence over the
2727	server's variable. If the value of the environment variable is
2728	omitted, this variable will be removed from the resulting environment.
2729	If the environment string is @c null or empty, the server environment
2730	is inherited by the started process as is.
2731
2732	<see>openExistingSession</see>
2733
2734	<result name="E_UNEXPECTED">
2735	Virtual machine not registered.
2736	</result>
2737	<result name="E_INVALIDARG">
2738	Invalid session type @a type.
2739	</result>
2740	<result name="VBOX_E_OBJECT_NOT_FOUND">
2741	No machine matching @a machineId found.
2742	</result>
2743	<result name="VBOX_E_INVALID_OBJECT_STATE">
2744	Session already open or being opened.
2745	</result>
2746	<result name="VBOX_E_IPRT_ERROR">
2747	Launching process for machine failed.
2748	</result>
2749	<result name="VBOX_E_VM_ERROR">
2750	Failed to assign machine to session.
2751	</result>
2752
2753	</desc>
2754	<param name="session" type="ISession" dir="in">
2755	<desc>
2756	Session object that will represent the opened remote session
2757	after successful method invocation (this object must not
2758	represent an already open session).
2759	</desc>
2760	</param>
2761	<param name="machineId" type="uuid" mod="string" dir="in">
2762	<desc>ID of the virtual machine to open a session with.</desc>
2763	</param>
2764	<param name="type" type="wstring" dir="in">
2765	<desc>
2766	Type of the remote session (case sensitive).
2767	</desc>
2768	</param>
2769	<param name="environment" type="wstring" dir="in">
2770	<desc>
2771	Environment to pass to the opened session.
2772	</desc>
2773	</param>
2774	<param name="progress" type="IProgress" dir="return">
2775	<desc>Progress object to track the operation completion.</desc>
2776	</param>
2777	</method>
2778
2779	<method name="openExistingSession">
2780	<desc>
2781	Opens a new remote session with the virtual machine for
2782	which a direct session is already open.
2783
2784	The remote session provides some level of control over the VM
2785	execution (using the IConsole interface) to the caller; however,
2786	within the remote session context, not all VM settings are available
2787	for modification.
2788
2789	As opposed to <link to="#openRemoteSession"/>, the number of
2790	remote sessions opened this way is not limited by the API
2791
2792	<note>
2793	It is an error to open a remote session with the machine that
2794	doesn't have an open direct session.
2795	</note>
2796
2797	<result name="E_UNEXPECTED">
2798	Virtual machine not registered.
2799	</result>
2800	<result name="VBOX_E_OBJECT_NOT_FOUND">
2801	No machine matching @a machineId found.
2802	</result>
2803	<result name="VBOX_E_INVALID_OBJECT_STATE">
2804	Session already open or being opened.
2805	</result>
2806	<result name="VBOX_E_INVALID_SESSION_STATE">
2807	Direct session state not Open.
2808	</result>
2809	<result name="VBOX_E_VM_ERROR">
2810	Failed to get console object from direct session or assign
2811	machine to session.
2812	</result>
2813
2814	<see>openRemoteSession</see>
2815	</desc>
2816	<param name="session" type="ISession" dir="in">
2817	<desc>
2818	Session object that will represent the open remote session
2819	after successful method invocation. This object must not
2820	represent an already open session.
2821	<note>
2822	This session will be automatically closed when the peer
2823	(direct) session dies or gets closed.
2824	</note>
2825	</desc>
2826	</param>
2827	<param name="machineId" type="uuid" mod="string" dir="in">
2828	<desc>ID of the virtual machine to open a session with.</desc>
2829	</param>
2830	</method>
2831
2832	<method name="registerCallback">
2833	<desc>
2834	Registers a new global VirtualBox callback. The methods of the given
2835	callback object will be called by VirtualBox when an appropriate
2836	event occurs.
2837
2838	<result name="E_INVALIDARG">
2839	A @c null callback cannot be registered.
2840	</result>
2841
2842	</desc>
2843	<param name="callback" type="IVirtualBoxCallback" dir="in">
2844	<desc>Callback object to register.</desc>
2845	</param>
2846	</method>
2847
2848	<method name="unregisterCallback">
2849	<desc>
2850	Unregisters the previously registered global VirtualBox callback.
2851
2852	<result name="E_INVALIDARG">
2853	Specified @a callback not registered.
2854	</result>
2855
2856	</desc>
2857	<param name="callback" type="IVirtualBoxCallback" dir="in">
2858	<desc>Callback object to unregister.</desc>
2859	</param>
2860	</method>
2861
2862	<method name="waitForPropertyChange">
2863	<desc>
2864	Blocks the caller until any of the properties represented by the
2865	@a what argument changes the value or until the given timeout interval
2866	expires.
2867
2868	The @a what argument is a comma separated list of property masks that
2869	describe properties the caller is interested in. The property mask is
2870	a string in the following format:
2871
2872	<pre>
2873	[[group.]subgroup.]name
2874	</pre>
2875
2876	where @c name is the property name and @c group, @c subgroup are zero
2877	or more property group specifiers. Each element (group or name) in
2878	the property mask may be either a Latin string or an asterisk symbol
2879	(@c "*") which is used to match any string for the given element. A
2880	property mask that doesn't contain asterisk symbols represents a
2881	single fully qualified property name.
2882
2883	Groups in the fully qualified property name go from more generic (the
2884	left-most part) to more specific (the right-most part). The first
2885	element is usually a name of the object the property belongs to. The
2886	second element may be either a property name, or a child object name,
2887	or an index if the preceding element names an object which is one of
2888	many objects of the same type. This way, property names form a
2889	hierarchy of properties. Here are some examples of property names:
2890
2891	<table>
2892	<tr>
2893	<td><tt>VirtualBox.version</tt></td>
2894	<td><link to="IVirtualBox::version"/> property</td>
2895	</tr>
2896	<tr>
2897	<td><tt>Machine.<UUID>.name</tt></td>
2898	<td><link to="IMachine::name"/> property of the machine with the
2899	given UUID</td>
2900	</tr>
2901	</table>
2902
2903	Most property names directly correspond to the properties of objects
2904	(components) provided by the VirtualBox library and may be used to
2905	track changes to these properties. However, there may be
2906	pseudo-property names that don't correspond to any existing object's
2907	property directly, as well as there may be object properties that
2908	don't have a corresponding property name that is understood by this
2909	method, and therefore changes to such properties cannot be
2910	tracked. See individual object's property descriptions to get a
2911	fully qualified property name that can be used with this method (if
2912	any).
2913
2914	There is a special property mask @c "*" (i.e. a string consisting of a
2915	single asterisk symbol) that can be used to match all properties.
2916	Below are more examples of property masks:
2917
2918	<table>
2919	<tr>
2920	<td><tt>VirtualBox.*</tt></td>
2921	<td>Track all properties of the VirtualBox object</td>
2922	</tr>
2923	<tr>
2924	<td><tt>Machine.*.name</tt></td>
2925	<td>Track changes to the <link to="IMachine::name"/> property of
2926	all registered virtual machines</td>
2927	</tr>
2928	</table>
2929
2930	<note>
2931	This function is not implemented in the current version of the
2932	product.
2933	</note>
2934	</desc>
2935	<param name="what" type="wstring" dir="in">
2936	<desc>Comma separated list of property masks.</desc>
2937	</param>
2938	<param name="timeout" type="unsigned long" dir="in">
2939	<desc>
2940	Wait timeout in milliseconds.
2941	Specify -1 for an indefinite wait.
2942	</desc>
2943	</param>
2944	<param name="changed" type="wstring" dir="out">
2945	<desc>
2946	Comma separated list of properties that have been changed and caused
2947	this method to return to the caller.
2948	</desc>
2949	</param>
2950	<param name="values" type="wstring" dir="out">
2951	<desc>Reserved, not currently used.</desc>
2952	</param>
2953	</method>
2954
2955	<!--method name="createDHCPServerForInterface">
2956	<desc>
2957	Creates a dhcp server settings to be used for the given interface
2958	<result name="E_INVALIDARG">
2959	Host network interface @a name already exists.
2960	</result>
2961	</desc>
2962	<param name="interface" type="IHostNetworkInterface" dir="in">
2963	<desc>Network Interface</desc>
2964	</param>
2965	<param name="server" type="IDHCPServer" dir="out">
2966	<desc>Dhcp server settings</desc>
2967	</param>
2968	</method-->
2969
2970	<method name="createDHCPServer">
2971	<desc>
2972	Creates a dhcp server settings to be used for the given internal network name
2973	<result name="E_INVALIDARG">
2974	Host network interface @a name already exists.
2975	</result>
2976	</desc>
2977	<param name="name" type="wstring" dir="in">
2978	<desc>server name</desc>
2979	</param>
2980	<param name="server" type="IDHCPServer" dir="return">
2981	<desc>Dhcp server settings</desc>
2982	</param>
2983	</method>
2984
2985	<method name="findDHCPServerByNetworkName">
2986	<desc>
2987	Searches a dhcp server settings to be used for the given internal network name
2988	<result name="E_INVALIDARG">
2989	Host network interface @a name already exists.
2990	</result>
2991
2992	</desc>
2993	<param name="name" type="wstring" dir="in">
2994	<desc>server name</desc>
2995	</param>
2996	<param name="server" type="IDHCPServer" dir="return">
2997	<desc>Dhcp server settings</desc>
2998	</param>
2999	</method>
3000
3001	<!--method name="findDHCPServerForInterface">
3002	<desc>
3003	Searches a dhcp server settings to be used for the given interface
3004	<result name="E_INVALIDARG">
3005	Host network interface @a name already exists.
3006	</result>
3007	</desc>
3008	<param name="interface" type="IHostNetworkInterface" dir="in">
3009	<desc>Network Interface</desc>
3010	</param>
3011	<param name="server" type="IDHCPServer" dir="out">
3012	<desc>Dhcp server settings</desc>
3013	</param>
3014	</method-->
3015
3016	<method name="removeDHCPServer">
3017	<desc>
3018	Removes the dhcp server settings
3019	<result name="E_INVALIDARG">
3020	Host network interface @a name already exists.
3021	</result>
3022	</desc>
3023	<param name="server" type="IDHCPServer" dir="in">
3024	<desc>Dhcp server settings to be removed</desc>
3025	</param>
3026	</method>
3027
3028
3029	<method name="checkFirmwarePresent">
3030	<desc>
3031	Check if this VirtualBox installation has a firmware
3032	of the given type available, either system-wide or per-user.
3033	Optionally, this may return a hint where this firmware can be
3034	downloaded from.
3035	</desc>
3036	<param name="firmwareType" type="FirmwareType" dir="in">
3037	<desc>
3038	Type of firmware to check.
3039	</desc>
3040	</param>
3041	<param name="version" type="wstring" dir="in">
3042	<desc>Expected version number, usually empty string (presently ignored).</desc>
3043	</param>
3044
3045	<param name="url" type="wstring" dir="out">
3046	<desc>
3047	Suggested URL to download this firmware from.
3048	</desc>
3049	</param>
3050
3051	<param name="file" type="wstring" dir="out">
3052	<desc>
3053	Filename of firmware, only valid if result == TRUE.
3054	</desc>
3055	</param>
3056
3057	<param name="result" type="boolean" dir="return">
3058	<desc>If firmware of this type and version is available.</desc>
3059	</param>
3060	</method>
3061
3062	</interface>
3063
3064	<!--
3065	// IVFSExplorer
3066	/////////////////////////////////////////////////////////////////////////
3067	-->
3068
3069	<enum
3070	name="VFSType"
3071	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
3072	>
3073	<desc>
3074	Virtual file systems supported by VFSExplorer.
3075	</desc>
3076
3077	<const name="File" value="1" />
3078	<const name="Cloud" value="2" />
3079	<const name="S3" value="3" />
3080	<const name="WebDav" value="4" />
3081	</enum>
3082
3083	<enum
3084	name="VFSFileType"
3085	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
3086	>
3087	<desc>
3088	File types known by VFSExplorer.
3089	</desc>
3090
3091	<const name="Unknown" value="1" />
3092	<const name="Fifo" value="2" />
3093	<const name="DevChar" value="3" />
3094	<const name="Directory" value="4" />
3095	<const name="DevBlock" value="5" />
3096	<const name="File" value="6" />
3097	<const name="SymLink" value="7" />
3098	<const name="Socket" value="8" />
3099	<const name="WhiteOut" value="9" />
3100	</enum>
3101
3102	<interface
3103	name="IVFSExplorer" extends="$unknown"
3104	uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
3105	wsmap="managed"
3106	>
3107	<desc>
3108	The VFSExplorer interface unifies access to different file system
3109	types. This includes local file systems as well remote file systems like
3110	S3. For a list of supported types see <link to="VFSType" />.
3111	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
3112	</desc>
3113
3114	<attribute name="path" type="wstring" readonly="yes">
3115	<desc>Returns the current path in the virtual file system.</desc>
3116	</attribute>
3117
3118	<attribute name="type" type="VFSType" readonly="yes">
3119	<desc>Returns the file system type which is currently in use.</desc>
3120	</attribute>
3121
3122	<method name="update">
3123	<desc>Updates the internal list of files/directories from the
3124	current directory level. Use <link to="#entryList" /> to get the full list
3125	after a call to this method.</desc>
3126
3127	<param name="aProgress" type="IProgress" dir="return">
3128	<desc>Progress object to track the operation completion.</desc>
3129	</param>
3130	</method>
3131
3132	<method name="cd">
3133	<desc>Change the current directory level.</desc>
3134
3135	<param name="aDir" type="wstring" dir="in">
3136	<desc>The name of the directory to go in.</desc>
3137	</param>
3138
3139	<param name="aProgress" type="IProgress" dir="return">
3140	<desc>Progress object to track the operation completion.</desc>
3141	</param>
3142	</method>
3143
3144	<method name="cdUp">
3145	<desc>Go one directory upwards from the current directory level.</desc>
3146
3147	<param name="aProgress" type="IProgress" dir="return">
3148	<desc>Progress object to track the operation completion.</desc>
3149	</param>
3150	</method>
3151
3152	<method name="entryList">
3153	<desc>Returns a list of files/directories after a call to <link
3154	to="#update" />. The user is responsible for keeping this internal
3155	list up do date.</desc>
3156
3157	<param name="aNames" type="wstring" safearray="yes" dir="out">
3158	<desc>The list of names for the entries.</desc>
3159	</param>
3160
3161	<param name="aTypes" type="unsigned long" safearray="yes" dir="out">
3162	<desc>The list of types for the entries.</desc>
3163	</param>
3164	</method>
3165
3166	<method name="exists">
3167	<desc>Checks if the given file list exists in the current directory
3168	level.</desc>
3169
3170	<param name="aNames" type="wstring" safearray="yes" dir="in">
3171	<desc>The names to check.</desc>
3172	</param>
3173
3174	<param name="aExists" type="wstring" safearray="yes" dir="return">
3175	<desc>The names which exist.</desc>
3176	</param>
3177	</method>
3178
3179	<method name="remove">
3180	<desc>Deletes the given files in the current directory level.</desc>
3181
3182	<param name="aNames" type="wstring" safearray="yes" dir="in">
3183	<desc>The names to remove.</desc>
3184	</param>
3185
3186	<param name="aProgress" type="IProgress" dir="return">
3187	<desc>Progress object to track the operation completion.</desc>
3188	</param>
3189	</method>
3190
3191	</interface>
3192
3193	<!--
3194	// IAppliance
3195	/////////////////////////////////////////////////////////////////////////
3196	-->
3197
3198	<interface
3199	name="IAppliance" extends="$unknown"
3200	uuid="e3ba9ab9-ac2c-4266-8bd2-91c4bf721ceb"
3201	wsmap="managed"
3202	>
3203	<desc>
3204	Represents a platform-independent appliance in OVF format. An instance of this is returned
3205	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
3206	virtual machines within an appliance with VirtualBox.
3207
3208	The OVF standard suggests two different physical file formats:
3209
3210	<ol>
3211	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
3212	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
3213	this descriptor file references other files such as disk images, as OVF appliances typically
3214	do, those additional files must be in the same directory as the descriptor file.</li>
3215
3216	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
3217	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3218	files and optionally other files.
3219
3220	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3221	be added with a later version.</li>
3222	</ol>
3223
3224	<b>Importing</b> an OVF appliance into VirtualBox as instances of
3225	<link to="IMachine" /> involves the following sequence of API calls:
3226
3227	<ol>
3228	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3229	</li>
3230
3231	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3232	would like to import. So long as this file is syntactically valid, this will succeed
3233	and fill the appliance object with the parsed data from the OVF file.
3234	</li>
3235
3236	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3237	contents of the IAppliance attributes accordingly. These can be inspected by a
3238	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3239	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3240	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3241	systems in the OVF, which in turn describe the virtual hardware prescribed by the
3242	OVF (network and hardware adapters, virtual disk images, memory size and so on).
3243	The GUI can then give the user the option to confirm and/or change these suggestions.
3244	</li>
3245
3246	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3247	virtual system to override the suggestions made by the interpret() routine.
3248	</li>
3249
3250	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
3251	VirtualBox as instances of <link to="IMachine" /> that match the information in the
3252	virtual system descriptions.
3253	</li>
3254	</ol>
3255
3256	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3257
3258	<ol>
3259	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3260	an empty IAppliance object.
3261	</li>
3262
3263	<li>For each machine you would like to export, call <link to="IMachine::export" />
3264	with the IAppliance object you just created. This creates an instance of
3265	<link to="IVirtualSystemDescription" /> inside the appliance.
3266	</li>
3267
3268	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3269	virtual system to override the suggestions made by the export() routine.
3270	</li>
3271
3272	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
3273	file written.</li>
3274	</ol>
3275
3276	</desc>
3277
3278	<attribute name="path" type="wstring" readonly="yes">
3279	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3280	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3281	<link to="#write" /> (for export).
3282	This attribute is empty until one of these methods has been called.
3283	</desc>
3284	</attribute>
3285
3286	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3287	<desc>
3288	Array of virtual disk definitions. One such description exists for each
3289	disk definition in the OVF; each string array item represents one such piece of
3290	disk information, with the information fields separated by tab (\t) characters.
3291
3292	The caller should be prepared for additional fields being appended to
3293	this string in future versions of VirtualBox and therefore check for
3294	the number of tabs in the strings returned.
3295
3296	In the current version, the following eight fields are returned per string
3297	in the array:
3298
3299	<ol>
3300	<li>Disk ID (unique string identifier given to disk)</li>
3301
3302	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3303
3304	<li>Populated size (optional unsigned integer indicating the current size of the
3305	disk; can be approximate; -1 if unspecified)</li>
3306
3307	<li>Format (string identifying the disk format, typically
3308	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3309
3310	<li>Reference (where to find the disk image, typically a file name; if empty,
3311	then the disk should be created on import)</li>
3312
3313	<li>Image size (optional unsigned integer indicating the size of the image,
3314	which need not necessarily be the same as the values specified above, since
3315	the image may be compressed or sparse; -1 if not specified)</li>
3316
3317	<li>Chunk size (optional unsigned integer if the image is split into chunks;
3318	presently unsupported and always -1)</li>
3319
3320	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3321	</ol>
3322	</desc>
3323	</attribute>
3324
3325	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3326	<desc> Array of virtual system descriptions. One such description is created
3327	for each virtual system found in the OVF.
3328	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3329	(for export) has been called.
3330	</desc>
3331	</attribute>
3332
3333	<method name="read">
3334	<desc>
3335	Reads an OVF file into the appliance object.
3336
3337	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3338	mere fact that this method returns successfully does not mean that VirtualBox supports all
3339	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3340	</desc>
3341	<param name="file" type="wstring" dir="in">
3342	<desc>
3343	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3344	on whether the appliance is distributed as a set of files or as a single file, respectively).
3345	</desc>
3346	</param>
3347	<param name="aProgress" type="IProgress" dir="return">
3348	<desc></desc>
3349	</param>
3350	</method>
3351
3352	<method name="interpret">
3353	<desc>
3354	Interprets the OVF data that was read when the appliance was constructed. After
3355	calling this method, one can inspect the
3356	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3357	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3358	the appliance.
3359
3360	Calling this method is the second step of importing an appliance into VirtualBox;
3361	see <link to="IAppliance" /> for an overview.
3362
3363	After calling this method, one should call <link to="#getWarnings" /> to find out
3364	if problems were encountered during the processing which might later lead to
3365	errors.
3366	</desc>
3367	</method>
3368
3369	<method name="importMachines">
3370	<desc>
3371	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3372	and other interfaces that match the information contained in the appliance as
3373	closely as possible, as represented by the import instructions in the
3374	<link to="#virtualSystemDescriptions" /> array.
3375
3376	Calling this method is the final step of importing an appliance into VirtualBox;
3377	see <link to="IAppliance" /> for an overview.
3378
3379	Since importing the appliance will most probably involve copying and converting
3380	disk images, which can take a long time, this method operates asynchronously and
3381	returns an IProgress object to allow the caller to monitor the progress.
3382	</desc>
3383
3384	<param name="aProgress" type="IProgress" dir="return">
3385	<desc></desc>
3386	</param>
3387	</method>
3388
3389	<method name="createVFSExplorer">
3390	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
3391
3392	<param name="aUri" type="wstring" dir="in">
3393	<desc>The URI describing the file system to use.</desc>
3394	</param>
3395
3396	<param name="aExplorer" type="IVFSExplorer" dir="return">
3397	<desc></desc>
3398	</param>
3399	</method>
3400
3401	<method name="write">
3402	<desc>
3403	Writes the contents of the appliance exports into a new OVF file.
3404
3405	Calling this method is the final step of exporting an appliance from VirtualBox;
3406	see <link to="IAppliance" /> for an overview.
3407
3408	Since exporting the appliance will most probably involve copying and converting
3409	disk images, which can take a long time, this method operates asynchronously and
3410	returns an IProgress object to allow the caller to monitor the progress.
3411	</desc>
3412	<param name="format" type="wstring" dir="in">
3413	<desc>
3414	Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
3415	future versions of VirtualBox may support additional formats.
3416	</desc>
3417	</param>
3418	<param name="path" type="wstring" dir="in">
3419	<desc>
3420	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3421	on whether the appliance is distributed as a set of files or as a single file, respectively).
3422	</desc>
3423	</param>
3424	<param name="aProgress" type="IProgress" dir="return">
3425	<desc>Progress object to track the operation completion.</desc>
3426	</param>
3427	</method>
3428
3429	<method name="getWarnings">
3430	<desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3431
3432	<param name="aWarnings" type="wstring" dir="return" safearray="yes">
3433	<desc></desc>
3434	</param>
3435	</method>
3436
3437	</interface>
3438
3439	<enum
3440	name="VirtualSystemDescriptionType"
3441	uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"
3442	>
3443	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3444	a configuration value.</desc>
3445
3446	<const name="Ignore" value="1" />
3447	<const name="OS" value="2" />
3448	<const name="Name" value="3" />
3449	<const name="Product" value="4" />
3450	<const name="Vendor" value="5" />
3451	<const name="Version" value="6" />
3452	<const name="ProductUrl" value="7" />
3453	<const name="VendorUrl" value="8" />
3454	<const name="Description" value="9" />
3455	<const name="License" value="10" />
3456	<const name="Miscellaneous" value="11" />
3457	<const name="CPU" value="12" />
3458	<const name="Memory" value="13" />
3459	<const name="HardDiskControllerIDE" value="14" />
3460	<const name="HardDiskControllerSATA" value="15" />
3461	<const name="HardDiskControllerSCSI" value="16" />
3462	<const name="HardDiskControllerSAS" value="17" />
3463	<const name="HardDiskImage" value="18" />
3464	<const name="Floppy" value="19" />
3465	<const name="CDROM" value="20" />
3466	<const name="NetworkAdapter" value="21" />
3467	<const name="USBController" value="22" />
3468	<const name="SoundCard" value="23" />
3469
3470	</enum>
3471
3472	<enum
3473	name="VirtualSystemDescriptionValueType"
3474	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
3475	>
3476	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
3477	type to fetch.</desc>
3478
3479	<const name="Reference" value="1" />
3480	<const name="Original" value="2" />
3481	<const name="Auto" value="3" />
3482	<const name="ExtraConfig" value="4" />
3483
3484	</enum>
3485
3486	<interface
3487	name="IVirtualSystemDescription" extends="$unknown"
3488	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
3489	wsmap="managed"
3490	>
3491
3492	<desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3493	After <link to="IAppliance::interpret" /> has been called, that array contains
3494	information about how the virtual systems described in the OVF should best be imported into VirtualBox
3495	virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3496	into VirtualBox.
3497	</desc>
3498
3499	<attribute name="count" type="unsigned long" readonly="yes">
3500	<desc>Return the number of virtual system description entries.</desc>
3501	</attribute>
3502
3503	<method name="getDescription">
3504	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3505	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3506
3507	The list below identifies the value sets that are possible depending on the
3508	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
3509	the array item with the same index in @a aOvfValues[] will contain the original value as contained
3510	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
3511	will contain a suggested value to be used for VirtualBox. Depending on the description type,
3512	the @a aExtraConfigValues[] array item may also be used.
3513
3514	<ul>
3515	<li>
3516	"OS": the guest operating system type. There must be exactly one such array item on import. The
3517	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
3518	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3519	item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
3520	</li>
3521	<li>
3522	"Name": the name to give to the new virtual machine. There can be at most one such array item;
3523	if none is present on import, then an automatic name will be created from the operating system
3524	type. The correponding item im @a aOvfValues[] will contain the suggested virtual machine name
3525	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
3526	<link to="IMachine" /> name that does not exist yet.
3527	</li>
3528	<li>
3529	"Description": an arbitrary description.
3530	</li>
3531	<li>
3532	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3533	code to display such a license for agreement; the Main API does not enforce any such policy.
3534	</li>
3535	<li>
3536	Miscellaneous: reserved for future use.
3537	</li>
3538	<li>
3539	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3540	</li>
3541	<li>
3542	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3543	is present on import, then VirtualBox will set a meaningful default based on the operating system
3544	type.
3545	</li>
3546	<li>
3547	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
3548	An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
3549	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
3550	writes into the OVF.
3551	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
3552	type can use to specify which hard disk controller a virtual disk should be connected to.
3553	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
3554	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
3555	its virtual machines supports four channels (primary master, primary slave, secondary master,
3556	secondary slave) and thus maps to two IDE controllers in the OVF sense.
3557	</li>
3558	<li>
3559	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3560	has no value in @a aOvfValues[] or @a aVBoxValues[].
3561	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3562	</li>
3563	<li>
3564	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3565	The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
3566	"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
3567	whereas VirtualBox considers it a class of storage controllers of its own; see
3568	<link to="StorageControllerType" />).
3569	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3570	</li>
3571	<li>
3572	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3573	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3574
3575	The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
3576	a path since the image file should be in the same location as the OVF file itself), whereas the
3577	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3578	hard disk image. This means that on import the image will be copied and converted from the
3579	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3580	On import, the target image will also be registered with VirtualBox.
3581
3582	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
3583	format: "controller=<index>;channel=<c>"
3584	In this string, <index> must be an integer specifying the hard disk controller to connect
3585	the image to. That number must be the index of an array item with one of the hard disk controller
3586	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
3587	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3588	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
3589	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
3590	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
3591	</li>
3592	<li>
3593	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
3594	attachment information as with "HardDiskImage" items.
3595	</li>
3596	<li>
3597	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
3598	attachment information as with "HardDiskImage" items.
3599	</li>
3600	<li>
3601	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
3602	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
3603	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3604	</li>
3605	<li>
3606	"USBController": a USB controller. There can be at most one such item. If and only if such an
3607	item ispresent, USB support will be enabled for the new virtual machine.
3608	</li>
3609	<li>
3610	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3611	present, sound support will be enabled for the new virtual machine. Note that the virtual
3612	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3613	may be different from the virtual soundcard expected by the appliance.
3614	</li>
3615	</ul>
3616
3617	</desc>
3618
3619	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3620	<desc></desc>
3621	</param>
3622
3623	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3624	<desc></desc>
3625	</param>
3626
3627	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3628	<desc></desc>
3629	</param>
3630
3631	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3632	<desc></desc>
3633	</param>
3634
3635	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3636	<desc></desc>
3637	</param>
3638
3639	</method>
3640
3641	<method name="getDescriptionByType">
3642	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3643	should be returned.</desc>
3644
3645	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3646	<desc></desc>
3647	</param>
3648
3649	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3650	<desc></desc>
3651	</param>
3652
3653	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3654	<desc></desc>
3655	</param>
3656
3657	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3658	<desc></desc>
3659	</param>
3660
3661	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3662	<desc></desc>
3663	</param>
3664
3665	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3666	<desc></desc>
3667	</param>
3668
3669	</method>
3670
3671	<method name="getValuesByType">
3672	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3673	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3674	values.</desc>
3675
3676	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3677	<desc></desc>
3678	</param>
3679
3680	<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
3681	<desc></desc>
3682	</param>
3683
3684	<param name="aValues" type="wstring" dir="return" safearray="yes">
3685	<desc></desc>
3686	</param>
3687
3688	</method>
3689
3690	<method name="setFinalValues">
3691	<desc>
3692	This method allows the appliance's user to change the configuration for the virtual
3693	system descriptions. For each array item returned from <link to="#getDescription" />,
3694	you must pass in one boolean value and one configuration value.
3695
3696	Each item in the boolean array determines whether the particular configuration item
3697	should be enabled.
3698	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3699	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3700	and SoundCard.
3701
3702	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3703	as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
3704	the configuration remains unchanged. Please see the documentation for getDescription()
3705	for valid configuration values for the individual array item types. If the
3706	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3707	</desc>
3708
3709	<param name="aEnabled" type="boolean" dir="in" safearray="yes">
3710	<desc></desc>
3711	</param>
3712
3713	<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
3714	<desc></desc>
3715	</param>
3716
3717	<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3718	<desc></desc>
3719	</param>
3720	</method>
3721
3722	<method name="addDescription">
3723	<desc>
3724	This method adds an additional description entry to the stack of already
3725	available descriptions for this virtual system. This is handy for writing
3726	values which aren't directly supported by VirtualBox. One example would
3727	be the License type of <link to="VirtualSystemDescriptionType" />.
3728	</desc>
3729
3730	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3731	<desc></desc>
3732	</param>
3733
3734	<param name="aVBoxValue" type="wstring" dir="in">
3735	<desc></desc>
3736	</param>
3737
3738	<param name="aExtraConfigValue" type="wstring" dir="in">
3739	<desc></desc>
3740	</param>
3741	</method>
3742	</interface>
3743
3744
3745	<!--
3746	// IMachine
3747	/////////////////////////////////////////////////////////////////////////
3748	-->
3749
3750	<interface
3751	name="IInternalMachineControl" extends="$unknown"
3752	uuid="57e9a280-8d57-4331-aa31-f009f5194f52"
3753	internal="yes"
3754	wsmap="suppress"
3755	>
3756	<method name="setRemoveSavedState">
3757	<desc>
3758	Updates the flag whether saved state is removed on a machine state
3759	change from Saved to PoweredOff.
3760	</desc>
3761	<param name="aRemove" type="boolean" dir="in"/>
3762	</method>
3763
3764	<method name="updateState">
3765	<desc>
3766	Updates the VM state.
3767	<note>
3768	This operation will also update the settings file with
3769	the correct information about the saved state file
3770	and delete this file from disk when appropriate.
3771	</note>
3772	</desc>
3773	<param name="state" type="MachineState" dir="in"/>
3774	</method>
3775
3776	<method name="getIPCId">
3777	<param name="id" type="wstring" dir="return"/>
3778	</method>
3779
3780	<method name="setPowerUpInfo">
3781	<desc>
3782	Transfers success (@c null) or error information for this session.
3783	This method updates the progress object to signal completion of the
3784	<link to="IVirtualBox::openRemoteSession"/> method if appropriate,
3785	which means that the progress object returned by
3786	<link to="IConsole::powerUp"/>.
3787	</desc>
3788	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
3789	</method>
3790
3791	<method name="runUSBDeviceFilters">
3792	<desc>
3793	Asks the server to run USB devices filters of the associated
3794	machine against the given USB device and tell if there is
3795	a match.
3796	<note>
3797	Intended to be used only for remote USB devices. Local
3798	ones don't require to call this method (this is done
3799	implicitly by the Host and USBProxyService).
3800	</note>
3801	</desc>
3802	<param name="device" type="IUSBDevice" dir="in"/>
3803	<param name="matched" type="boolean" dir="out"/>
3804	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3805	</method>
3806
3807	<method name="captureUSBDevice">
3808	<desc>
3809	Requests a capture of the given host USB device.
3810	When the request is completed, the VM process will
3811	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3812	notification.
3813	</desc>
3814	<param name="id" type="uuid" mod="string" dir="in"/>
3815	</method>
3816
3817	<method name="detachUSBDevice">
3818	<desc>
3819	Notification that a VM is going to detach (@a done = @c false) or has
3820	already detached (@a done = @c true) the given USB device.
3821	When the @a done = @c true request is completed, the VM process will
3822	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3823	notification.
3824	<note>
3825	In the @a done = @c true case, the server must run its own filters
3826	and filters of all VMs but this one on the detached device
3827	as if it were just attached to the host computer.
3828	</note>
3829	</desc>
3830	<param name="id" type="uuid" mod="string" dir="in"/>
3831	<param name="done" type="boolean" dir="in"/>
3832	</method>
3833
3834	<method name="autoCaptureUSBDevices">
3835	<desc>
3836	Requests a capture all matching USB devices attached to the host.
3837	When the request is completed, the VM process will
3838	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3839	notification per every captured device.
3840	</desc>
3841	</method>
3842
3843	<method name="detachAllUSBDevices">
3844	<desc>
3845	Notification that a VM that is being powered down. The done
3846	parameter indicates whether which stage of the power down
3847	we're at. When @a done = @c false the VM is announcing its
3848	intentions, while when @a done = @c true the VM is reporting
3849	what it has done.
3850	<note>
3851	In the @a done = @c true case, the server must run its own filters
3852	and filters of all VMs but this one on all detach devices as
3853	if they were just attached to the host computer.
3854	</note>
3855	</desc>
3856	<param name="done" type="boolean" dir="in"/>
3857	</method>
3858
3859	<method name="onSessionEnd">
3860	<desc>
3861	Triggered by the given session object when the session is about
3862	to close normally.
3863	</desc>
3864	<param name="session" type="ISession" dir="in">
3865	<desc>Session that is being closed</desc>
3866	</param>
3867	<param name="progress" type="IProgress" dir="return">
3868	<desc>
3869	Used to wait until the corresponding machine is actually
3870	dissociated from the given session on the server.
3871	Returned only when this session is a direct one.
3872	</desc>
3873	</param>
3874	</method>
3875
3876	<method name="beginSavingState">
3877	<desc>
3878	Called by the VM process to inform the server it wants to
3879	save the current state and stop the VM execution.
3880	</desc>
3881	<param name="progress" type="IProgress" dir="in">
3882	<desc>
3883	Progress object created by the VM process to wait until
3884	the state is saved.
3885	</desc>
3886	</param>
3887	<param name="stateFilePath" type="wstring" dir="out">
3888	<desc>
3889	File path the VM process must save the execution state to.
3890	</desc>
3891	</param>
3892	</method>
3893
3894	<method name="endSavingState">
3895	<desc>
3896	Called by the VM process to inform the server that saving
3897	the state previously requested by #beginSavingState is either
3898	successfully finished or there was a failure.
3899
3900	<result name="VBOX_E_FILE_ERROR">
3901	Settings file not accessible.
3902	</result>
3903	<result name="VBOX_E_XML_ERROR">
3904	Could not parse the settings file.
3905	</result>
3906
3907	</desc>
3908
3909	<param name="success" type="boolean" dir="in">
3910	<desc>@c true to indicate success and @c false otherwise.
3911	</desc>
3912	</param>
3913	</method>
3914
3915	<method name="adoptSavedState">
3916	<desc>
3917	Gets called by IConsole::adoptSavedState.
3918	<result name="VBOX_E_FILE_ERROR">
3919	Invalid saved state file path.
3920	</result>
3921	</desc>
3922	<param name="savedStateFile" type="wstring" dir="in">
3923	<desc>Path to the saved state file to adopt.</desc>
3924	</param>
3925	</method>
3926
3927	<method name="beginTakingSnapshot">
3928	<desc>
3929	Called from the VM process to request from the server to perform the
3930	server-side actions of creating a snapshot (creating differencing images
3931	and the snapshot object).
3932
3933	<result name="VBOX_E_FILE_ERROR">
3934	Settings file not accessible.
3935	</result>
3936	<result name="VBOX_E_XML_ERROR">
3937	Could not parse the settings file.
3938	</result>
3939	</desc>
3940	<param name="initiator" type="IConsole" dir="in">
3941	<desc>The console object that initiated this call.</desc>
3942	</param>
3943	<param name="name" type="wstring" dir="in">
3944	<desc>Snapshot name.</desc>
3945	</param>
3946	<param name="description" type="wstring" dir="in">
3947	<desc>Snapshot description.</desc>
3948	</param>
3949	<param name="consoleProgress" type="IProgress" dir="in">
3950	<desc>
3951	Progress object created by the VM process tracking the
3952	snapshot's progress. This has the following sub-operations:
3953	<ul>
3954	<li>setting up (weight 1);</li>
3955	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3956	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3957	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3958	<li>finishing up (weight 1)</li>
3959	</ul>
3960	</desc>
3961	</param>
3962	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
3963	<desc>
3964	Whether this is an online snapshot (i.e. the machine is running).
3965	</desc>
3966	</param>
3967	<param name="stateFilePath" type="wstring" dir="out">
3968	<desc>
3969	File path the VM process must save the execution state to.
3970	</desc>
3971	</param>
3972	</method>
3973
3974	<method name="endTakingSnapshot">
3975	<desc>
3976	Called by the VM process to inform the server that the snapshot
3977	previously requested by #beginTakingSnapshot is either
3978	successfully taken or there was a failure.
3979	</desc>
3980
3981	<param name="success" type="boolean" dir="in">
3982	<desc>@c true to indicate success and @c false otherwise</desc>
3983	</param>
3984	</method>
3985
3986	<method name="deleteSnapshot">
3987	<desc>
3988	Gets called by IConsole::deleteSnapshot.
3989	<result name="VBOX_E_INVALID_OBJECT_STATE">
3990	Snapshot has more than one child snapshot.
3991	</result>
3992	</desc>
3993	<param name="initiator" type="IConsole" dir="in">
3994	<desc>The console object that initiated this call.</desc>
3995	</param>
3996	<param name="id" type="uuid" mod="string" dir="in">
3997	<desc>UUID of the snapshot to delete.</desc>
3998	</param>
3999	<param name="machineState" type="MachineState" dir="out">
4000	<desc>New machine state after this operation is started.</desc>
4001	</param>
4002	<param name="progress" type="IProgress" dir="return">
4003	<desc>Progress object to track the operation completion.</desc>
4004	</param>
4005	</method>
4006
4007	<method name="finishOnlineMergeMedium">
4008	<desc>
4009	Gets called by IConsole::onlineMergeMedium.
4010	</desc>
4011	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
4012	<desc>The medium attachment which needs to be cleaned up.</desc>
4013	</param>
4014	<param name="source" type="IMedium" dir="in">
4015	<desc>Merge source medium.</desc>
4016	</param>
4017	<param name="target" type="IMedium" dir="in">
4018	<desc>Merge target medium.</desc>
4019	</param>
4020	<param name="mergeForward" type="boolean" dir="in">
4021	<desc>Merge direction.</desc>
4022	</param>
4023	<param name="parentForTarget" type="IMedium" dir="in">
4024	<desc>For forward merges: new parent for target medium.</desc>
4025	</param>
4026	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
4027	<desc>For backward merges: list of media which need their parent UUID
4028	updated.</desc>
4029	</param>
4030	</method>
4031
4032	<method name="restoreSnapshot">
4033	<desc>
4034	Gets called by IConsole::RestoreSnapshot.
4035	</desc>
4036	<param name="initiator" type="IConsole" dir="in">
4037	<desc>The console object that initiated this call.</desc>
4038	</param>
4039	<param name="snapshot" type="ISnapshot" dir="in">
4040	<desc>The snapshot to restore the VM state from.</desc>
4041	</param>
4042	<param name="machineState" type="MachineState" dir="out">
4043	<desc>New machine state after this operation is started.</desc>
4044	</param>
4045	<param name="progress" type="IProgress" dir="return">
4046	<desc>Progress object to track the operation completion.</desc>
4047	</param>
4048	</method>
4049
4050	<method name="pullGuestProperties">
4051	<desc>
4052	Get the list of the guest properties matching a set of patterns along
4053	with their values, time stamps and flags and give responsibility for
4054	managing properties to the console.
4055	</desc>
4056	<param name="name" type="wstring" dir="out" safearray="yes">
4057	<desc>
4058	The names of the properties returned.
4059	</desc>
4060	</param>
4061	<param name="value" type="wstring" dir="out" safearray="yes">
4062	<desc>
4063	The values of the properties returned. The array entries match the
4064	corresponding entries in the @a name array.
4065	</desc>
4066	</param>
4067	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
4068	<desc>
4069	The time stamps of the properties returned. The array entries match
4070	the corresponding entries in the @a name array.
4071	</desc>
4072	</param>
4073	<param name="flags" type="wstring" dir="out" safearray="yes">
4074	<desc>
4075	The flags of the properties returned. The array entries match the
4076	corresponding entries in the @a name array.
4077	</desc>
4078	</param>
4079	</method>
4080
4081	<method name="pushGuestProperty">
4082	<desc>
4083	Update a single guest property in IMachine.
4084	</desc>
4085	<param name="name" type="wstring" dir="in">
4086	<desc>
4087	The name of the property to be updated.
4088	</desc>
4089	</param>
4090	<param name="value" type="wstring" dir="in">
4091	<desc>
4092	The value of the property.
4093	</desc>
4094	</param>
4095	<param name="timestamp" type="unsigned long long" dir="in">
4096	<desc>
4097	The timestamp of the property.
4098	</desc>
4099	</param>
4100	<param name="flags" type="wstring" dir="in">
4101	<desc>
4102	The flags of the property.
4103	</desc>
4104	</param>
4105	</method>
4106
4107	<method name="lockMedia">
4108	<desc>
4109	Locks all media attached to the machine for writing and parents of
4110	attached differencing media (if any) for reading. This operation is
4111	atomic so that if it fails no media is actually locked.
4112
4113	This method is intended to be called when the machine is in Starting or
4114	Restoring state. The locked media will be automatically unlocked when
4115	the machine is powered off or crashed.
4116	</desc>
4117	</method>
4118	<method name="unlockMedia">
4119	<desc>
4120	Unlocks all media previously locked using
4121	<link to="IInternalMachineControl::lockMedia"/>.
4122
4123	This method is intended to be used with teleportation so that it is
4124	possible to teleport between processes on the same machine.
4125	</desc>
4126	</method>
4127	</interface>
4128
4129	<interface
4130	name="IBIOSSettings" extends="$unknown"
4131	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
4132	wsmap="managed"
4133	>
4134	<desc>
4135	The IBIOSSettings interface represents BIOS settings of the virtual
4136	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
4137	</desc>
4138	<attribute name="logoFadeIn" type="boolean">
4139	<desc>Fade in flag for BIOS logo animation.</desc>
4140	</attribute>
4141
4142	<attribute name="logoFadeOut" type="boolean">
4143	<desc>Fade out flag for BIOS logo animation.</desc>
4144	</attribute>
4145
4146	<attribute name="logoDisplayTime" type="unsigned long">
4147	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
4148	</attribute>
4149
4150	<attribute name="logoImagePath" type="wstring">
4151	<desc>
4152	Local file system path for external BIOS splash image. Empty string
4153	means the default image is shown on boot.
4154	</desc>
4155	</attribute>
4156
4157	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
4158	<desc>Mode of the BIOS boot device menu.</desc>
4159	</attribute>
4160
4161	<attribute name="ACPIEnabled" type="boolean">
4162	<desc>ACPI support flag.</desc>
4163	</attribute>
4164
4165	<attribute name="IOAPICEnabled" type="boolean">
4166	<desc>
4167	IO APIC support flag. If set, VirtualBox will provide an IO APIC
4168	and support IRQs above 15.
4169	</desc>
4170	</attribute>
4171
4172	<attribute name="timeOffset" type="long long">
4173	<desc>
4174	Offset in milliseconds from the host system time. This allows for
4175	guests running with a different system date/time than the host.
4176	It is equivalent to setting the system date/time in the BIOS except
4177	it is not an absolute value but a relative one. Guest Additions
4178	time synchronization honors this offset.
4179	</desc>
4180	</attribute>
4181
4182	<attribute name="PXEDebugEnabled" type="boolean">
4183	<desc>
4184	PXE debug logging flag. If set, VirtualBox will write extensive
4185	PXE trace information to the release log.
4186	</desc>
4187	</attribute>
4188
4189	</interface>
4190
4191	<interface
4192	name="IMachine" extends="$unknown"
4193	uuid="6d9212cb-a5c0-48b7-bbc1-3fa2ba2ee6d2"
4194	wsmap="managed"
4195	>
4196	<desc>
4197	The IMachine interface represents a virtual machine, or guest, created
4198	in VirtualBox.
4199
4200	This interface is used in two contexts. First of all, a collection of
4201	objects implementing this interface is stored in the
4202	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
4203	machines that are currently registered with this VirtualBox
4204	installation. Also, once a session has been opened for the given virtual
4205	machine (e.g. the virtual machine is running), the machine object
4206	associated with the open session can be queried from the session object;
4207	see <link to="ISession"/> for details.
4208
4209	The main role of this interface is to expose the settings of the virtual
4210	machine and provide methods to change various aspects of the virtual
4211	machine's configuration. For machine objects stored in the
4212	<link to="IVirtualBox::machines"/> collection, all attributes are
4213	read-only unless explicitly stated otherwise in individual attribute
4214	and method descriptions. In order to change a machine setting, a session
4215	for this machine must be opened using one of
4216	<link to="IVirtualBox::openSession"/>,
4217	<link to="IVirtualBox::openRemoteSession"/> or
4218	<link to="IVirtualBox::openExistingSession"/> methods. After the
4219	session has been successfully opened, a mutable machine object needs to
4220	be queried from the session object and then the desired settings changes
4221	can be applied to the returned object using IMachine attributes and
4222	methods. See the <link to="ISession"/> interface description for more
4223	information about sessions.
4224
4225	Note that IMachine does not provide methods to control virtual machine
4226	execution (such as start the machine, or power it down) -- these methods
4227	are grouped in a separate interface called <link to="IConsole" />.
4228
4229	<see>ISession, IConsole</see>
4230	</desc>
4231
4232	<attribute name="parent" type="IVirtualBox" readonly="yes">
4233	<desc>Associated parent object.</desc>
4234	</attribute>
4235
4236	<attribute name="accessible" type="boolean" readonly="yes">
4237	<desc>
4238	Whether this virtual machine is currently accessible or not.
4239
4240	A machine is always deemed accessible unless it is registered <i>and</i>
4241	its settings file cannot be read or parsed (either because the file itself
4242	is unavailable or has invalid XML contents).
4243
4244	Every time this property is read, the accessibility state of
4245	this machine is re-evaluated. If the returned value is @c false,
4246	the <link to="#accessError"/> property may be used to get the
4247	detailed error information describing the reason of
4248	inaccessibility, including XML error messages.
4249
4250	When the machine is inaccessible, only the following properties
4251	can be used on it:
4252	<ul>
4253	<li><link to="#parent"/></li>
4254	<li><link to="#id"/></li>
4255	<li><link to="#settingsFilePath"/></li>
4256	<li><link to="#accessible"/></li>
4257	<li><link to="#accessError"/></li>
4258	</ul>
4259
4260	An attempt to access any other property or method will return
4261	an error.
4262
4263	The only possible action you can perform on an inaccessible
4264	machine is to unregister it using the
4265	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
4266	for the accessibility state once more by querying this
4267	property).
4268
4269	<note>
4270	In the current implementation, once this property returns
4271	@c true, the machine will never become inaccessible
4272	later, even if its settings file cannot be successfully
4273	read/written any more (at least, until the VirtualBox
4274	server is restarted). This limitation may be removed in
4275	future releases.
4276	</note>
4277	</desc>
4278	</attribute>
4279
4280	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4281	<desc>
4282	Error information describing the reason of machine
4283	inaccessibility.
4284
4285	Reading this property is only valid after the last call to
4286	<link to="#accessible"/> returned @c false (i.e. the
4287	machine is currently unaccessible). Otherwise, a @c null
4288	IVirtualBoxErrorInfo object will be returned.
4289	</desc>
4290	</attribute>
4291
4292	<attribute name="name" type="wstring">
4293	<desc>
4294	Name of the virtual machine.
4295
4296	Besides being used for human-readable identification purposes
4297	everywhere in VirtualBox, the virtual machine name is also used
4298	as a name of the machine's settings file and as a name of the
4299	subdirectory this settings file resides in. Thus, every time you
4300	change the value of this property, the settings file will be
4301	renamed once you call <link to="#saveSettings"/> to confirm the
4302	change. The containing subdirectory will be also renamed, but
4303	only if it has exactly the same name as the settings file
4304	itself prior to changing this property (for backward compatibility
4305	with previous API releases). The above implies the following
4306	limitations:
4307	<ul>
4308	<li>The machine name cannot be empty.</li>
4309	<li>The machine name can contain only characters that are valid
4310	file name characters according to the rules of the file
4311	system used to store VirtualBox configuration.</li>
4312	<li>You cannot have two or more machines with the same name
4313	if they use the same subdirectory for storing the machine
4314	settings files.</li>
4315	<li>You cannot change the name of the machine if it is running,
4316	or if any file in the directory containing the settings file
4317	is being used by another running machine or by any other
4318	process in the host operating system at a time when
4319	<link to="#saveSettings"/> is called.
4320	</li>
4321	</ul>
4322	If any of the above limitations are hit, <link to="#saveSettings"/>
4323	will return an appropriate error message explaining the exact
4324	reason and the changes you made to this machine will not be
4325	saved.
4326	<note>
4327	For "legacy" machines created using the
4328	<link to="IVirtualBox::createLegacyMachine"/> call,
4329	the above naming limitations do not apply because the
4330	machine name does not affect the settings file name.
4331	The settings file name remains the same as it was specified
4332	during machine creation and never changes.
4333	</note>
4334	</desc>
4335	</attribute>
4336
4337	<attribute name="description" type="wstring">
4338	<desc>
4339	Description of the virtual machine.
4340
4341	The description attribute can contain any text and is
4342	typically used to describe the hardware and software
4343	configuration of the virtual machine in detail (i.e. network
4344	settings, versions of the installed software and so on).
4345	</desc>
4346	</attribute>
4347
4348	<attribute name="id" type="uuid" mod="string" readonly="yes">
4349	<desc>UUID of the virtual machine.</desc>
4350	</attribute>
4351
4352	<attribute name="OSTypeId" type="wstring">
4353	<desc>
4354	User-defined identifier of the Guest OS type.
4355	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4356	an IGuestOSType object representing details about the given
4357	Guest OS type.
4358	<note>
4359	This value may differ from the value returned by
4360	<link to="IGuest::OSTypeId"/> if Guest Additions are
4361	installed to the guest OS.
4362	</note>
4363	</desc>
4364	</attribute>
4365
4366	<attribute name="HardwareVersion" type="wstring">
4367	<desc>Hardware version identifier. Internal use only for now.</desc>
4368	</attribute>
4369
4370	<attribute name="hardwareUUID" type="uuid" mod="string">
4371	<desc>
4372	The UUID presented to the guest via memory tables, hardware and guest
4373	properties. For most VMs this is the same as the @a id, but for VMs
4374	which have been cloned or teleported it may be the same as the source
4375	VM. This latter is because the guest shouldn't notice that it was
4376	cloned or teleported.
4377	</desc>
4378	</attribute>
4379
4380	<attribute name="CPUCount" type="unsigned long">
4381	<desc>Number of virtual CPUs in the VM.</desc>
4382	</attribute>
4383
4384	<attribute name="CPUHotPlugEnabled" type="boolean">
4385	<desc>
4386	This setting determines whether VirtualBox allows CPU
4387	hotplugging for this machine.</desc>
4388	</attribute>
4389
4390	<attribute name="memorySize" type="unsigned long">
4391	<desc>System memory size in megabytes.</desc>
4392	</attribute>
4393
4394	<attribute name="memoryBalloonSize" type="unsigned long">
4395	<desc>Memory balloon size in megabytes.</desc>
4396	</attribute>
4397
4398	<attribute name="PageFusionEnabled" type="boolean">
4399	<desc>
4400	This setting determines whether VirtualBox allows page
4401	fusion for this machine (64 bits host only).
4402	</desc>
4403	</attribute>
4404
4405	<attribute name="VRAMSize" type="unsigned long">
4406	<desc>Video memory size in megabytes.</desc>
4407	</attribute>
4408
4409	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4410	<desc>
4411	This setting determines whether VirtualBox allows this machine to make
4412	use of the 3D graphics support available on the host.</desc>
4413	</attribute>
4414
4415	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4416	<desc>
4417	This setting determines whether VirtualBox allows this machine to make
4418	use of the 2D video acceleration support available on the host.</desc>
4419	</attribute>
4420
4421	<attribute name="monitorCount" type="unsigned long">
4422	<desc>
4423	Number of virtual monitors.
4424	<note>
4425	Only effective on Windows XP and later guests with
4426	Guest Additions installed.
4427	</note>
4428	</desc>
4429	</attribute>
4430
4431	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4432	<desc>Object containing all BIOS settings.</desc>
4433	</attribute>
4434
4435	<attribute name="firmwareType" type="FirmwareType">
4436	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4437	bootstrap in this VM.</desc>
4438	</attribute>
4439
4440	<attribute name="pointingHidType" type="PointingHidType">
4441	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4442	The default is typically "PS2Mouse" but can vary depending on the
4443	requirements of the guest operating system.</desc>
4444	</attribute>
4445
4446	<attribute name="keyboardHidType" type="KeyboardHidType">
4447	<desc>Type of keyboard HID used in this VM.
4448	The default is typically "PS2Keyboard" but can vary depending on the
4449	requirements of the guest operating system.</desc>
4450	</attribute>
4451
4452	<attribute name="hpetEnabled" type="boolean">
4453	<desc>This attribute controls if High Precision Event Timer (HPET) is
4454	enabled in this VM. Use this property if you want to provide guests
4455	with additional time source, or if guest requires HPET to function correctly.
4456	Default is false.</desc>
4457	</attribute>
4458
4459	<attribute name="snapshotFolder" type="wstring">
4460	<desc>
4461	Full path to the directory used to store snapshot data
4462	(differencing media and saved state files) of this machine.
4463
4464	The initial value of this property is
4465	<tt><</tt><link to="#settingsFilePath">
4466	path_to_settings_file</link><tt>>/<</tt>
4467	<link to="#id">machine_uuid</link>
4468	<tt>></tt>.
4469
4470	Currently, it is an error to try to change this property on
4471	a machine that has snapshots (because this would require to
4472	move possibly large files to a different location).
4473	A separate method will be available for this purpose later.
4474
4475	<note>
4476	Setting this property to @c null or to an empty string will restore
4477	the initial value.
4478	</note>
4479	<note>
4480	When setting this property, the specified path can be
4481	absolute (full path) or relative to the directory where the
4482	<link to="#settingsFilePath">machine settings file</link>
4483	is located. When reading this property, a full path is
4484	always returned.
4485	</note>
4486	<note>
4487	The specified path may not exist, it will be created
4488	when necessary.
4489	</note>
4490	</desc>
4491	</attribute>
4492
4493	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4494	<desc>VRDP server object.</desc>
4495	</attribute>
4496
4497	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4498	<desc>Array of media attached to this machine.</desc>
4499	</attribute>
4500
4501	<attribute name="USBController" type="IUSBController" readonly="yes">
4502	<desc>
4503	Associated USB controller object.
4504
4505	<note>
4506	If USB functionality is not available in the given edition of
4507	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4508	</note>
4509	</desc>
4510	</attribute>
4511
4512	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4513	<desc>Associated audio adapter, always present.</desc>
4514	</attribute>
4515
4516	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4517	<desc>Array of storage controllers attached to this machine.</desc>
4518	</attribute>
4519
4520	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4521	<desc>
4522	Full name of the file containing machine settings data.
4523	</desc>
4524	</attribute>
4525
4526	<attribute name="settingsModified" type="boolean" readonly="yes">
4527	<desc>
4528	Whether the settings of this machine have been modified
4529	(but neither yet saved nor discarded).
4530	<note>
4531	Reading this property is only valid on instances returned
4532	by <link to="ISession::machine"/> and on new machines
4533	created by <link to="IVirtualBox::createMachine"/> or opened
4534	by <link to="IVirtualBox::openMachine"/> but not
4535	yet registered, or on unregistered machines after calling
4536	<link to="IVirtualBox::unregisterMachine"/>. For all other
4537	cases, the settings can never be modified.
4538	</note>
4539	<note>
4540	For newly created unregistered machines, the value of this
4541	property is always @c true until <link to="#saveSettings"/>
4542	is called (no matter if any machine settings have been
4543	changed after the creation or not). For opened machines
4544	the value is set to @c false (and then follows to normal rules).
4545	</note>
4546	</desc>
4547	</attribute>
4548
4549	<attribute name="sessionState" type="SessionState" readonly="yes">
4550	<desc>Current session state for this machine.</desc>
4551	</attribute>
4552
4553	<attribute name="sessionType" type="wstring" readonly="yes">
4554	<desc>
4555	Type of the session. If <link to="#sessionState"/> is
4556	SessionSpawning or SessionOpen, this attribute contains the
4557	same value as passed to the
4558	<link to="IVirtualBox::openRemoteSession"/> method in the
4559	@a type parameter. If the session was opened directly using
4560	<link to="IVirtualBox::openSession"/>, or if
4561	<link to="#sessionState"/> is SessionClosed, the value of this
4562	attribute is an empty string.
4563	</desc>
4564	</attribute>
4565
4566	<attribute name="sessionPid" type="unsigned long" readonly="yes">
4567	<desc>
4568	Identifier of the session process. This attribute contains the
4569	platform-dependent identifier of the process that has opened a
4570	direct session for this machine using the
4571	<link to="IVirtualBox::openSession"/> call. The returned value
4572	is only valid if <link to="#sessionState"/> is SessionOpen or
4573	SessionClosing (i.e. a session is currently open or being
4574	closed) by the time this property is read.
4575	</desc>
4576	</attribute>
4577
4578	<attribute name="state" type="MachineState" readonly="yes">
4579	<desc>Current execution state of this machine.</desc>
4580	</attribute>
4581
4582	<attribute name="lastStateChange" type="long long" readonly="yes">
4583	<desc>
4584	Time stamp of the last execution state change,
4585	in milliseconds since 1970-01-01 UTC.
4586	</desc>
4587	</attribute>
4588
4589	<attribute name="stateFilePath" type="wstring" readonly="yes">
4590	<desc>
4591	Full path to the file that stores the execution state of
4592	the machine when it is in the <link to="MachineState_Saved"/> state.
4593	<note>
4594	When the machine is not in the Saved state, this attribute is
4595	an empty string.
4596	</note>
4597	</desc>
4598	</attribute>
4599
4600	<attribute name="logFolder" type="wstring" readonly="yes">
4601	<desc>
4602	Full path to the folder that stores a set of rotated log files
4603	recorded during machine execution. The most recent log file is
4604	named <tt>VBox.log</tt>, the previous log file is
4605	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4606	in the current version).
4607	</desc>
4608	</attribute>
4609
4610	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4611	<desc>
4612	Current snapshot of this machine. This is @c null if the machine
4613	currently has no snapshots. If it is not @c null, then it was
4614	set by one of <link to="Console::takeSnapshot" />,
4615	<link to="Console::deleteSnapshot" />
4616	or <link to="Console::restoreSnapshot" />, depending on which
4617	was called last. See <link to="ISnapshot"/> for details.
4618	</desc>
4619	</attribute>
4620
4621	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4622	<desc>
4623	Number of snapshots taken on this machine. Zero means the
4624	machine doesn't have any snapshots.
4625	</desc>
4626	</attribute>
4627
4628	<attribute name="currentStateModified" type="boolean" readonly="yes">
4629	<desc>
4630	Returns @c true if the current state of the machine is not
4631	identical to the state stored in the current snapshot.
4632
4633	The current state is identical to the current snapshot only
4634	directly after one of the following calls are made:
4635
4636	<ul>
4637	<li><link to="IConsole::restoreSnapshot"/>
4638	</li>
4639	<li><link to="IConsole::takeSnapshot"/> (issued on a
4640	"powered off" or "saved" machine, for which
4641	<link to="#settingsModified"/> returns @c false)
4642	</li>
4643	<li><link to="IMachine::setCurrentSnapshot"/>
4644	</li>
4645	</ul>
4646
4647	The current state remains identical until one of the following
4648	happens:
4649	<ul>
4650	<li>settings of the machine are changed</li>
4651	<li>the saved state is deleted</li>
4652	<li>the current snapshot is deleted</li>
4653	<li>an attempt to execute the machine is made</li>
4654	</ul>
4655
4656	<note>
4657	For machines that don't have snapshots, this property is
4658	always @c false.
4659	</note>
4660	</desc>
4661	</attribute>
4662
4663	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4664	<desc>
4665	Collection of shared folders for this machine (permanent shared
4666	folders). These folders are shared automatically at machine startup
4667	and available only to the guest OS installed within this machine.
4668
4669	New shared folders are added to the collection using
4670	<link to="#createSharedFolder"/>. Existing shared folders can be
4671	removed using <link to="#removeSharedFolder"/>.
4672	</desc>
4673	</attribute>
4674
4675	<attribute name="clipboardMode" type="ClipboardMode">
4676	<desc>
4677	Synchronization mode between the host OS clipboard
4678	and the guest OS clipboard.
4679	</desc>
4680	</attribute>
4681
4682	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4683	<desc>
4684	A comma-separated list of simple glob patterns. Changes to guest
4685	properties whose name matches one of the patterns will generate an
4686	<link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4687	</desc>
4688	</attribute>
4689
4690	<attribute name="teleporterEnabled" type="boolean">
4691	<desc>
4692	When set to @a true, the virtual machine becomes a target teleporter
4693	the next time it is powered on. This can only set to @a true when the
4694	VM is in the @a PoweredOff or @a Aborted state.
4695
4696	<!-- This property is automatically set to @a false when the VM is powered
4697	on. (bird: This doesn't work yet ) -->
4698	</desc>
4699	</attribute>
4700
4701	<attribute name="teleporterPort" type="unsigned long">
4702	<desc>
4703	The TCP port the target teleporter will listen for incoming
4704	teleportations on.
4705
4706	0 means the port is automatically selected upon power on. The actual
4707	value can be read from this property while the machine is waiting for
4708	incoming teleportations.
4709	</desc>
4710	</attribute>
4711
4712	<attribute name="teleporterAddress" type="wstring">
4713	<desc>
4714	The address the target teleporter will listen on. If set to an empty
4715	string, it will listen on all addresses.
4716	</desc>
4717	</attribute>
4718
4719	<attribute name="teleporterPassword" type="wstring">
4720	<desc>
4721	The password the to check for on the target teleporter. This is just a
4722	very basic measure to prevent simple hacks and operators accidentally
4723	beaming a virtual machine to the wrong place.
4724	</desc>
4725	</attribute>
4726
4727	<attribute name="RTCUseUTC" type="boolean">
4728	<desc>
4729	When set to @a true, the RTC device of the virtual machine will run
4730	in UTC time, otherwise in local time. Especially Unix guests prefer
4731	the time in UTC.
4732	</desc>
4733	</attribute>
4734
4735	<attribute name="ioCacheEnabled" type="boolean">
4736	<desc>
4737	When set to @a true, the builtin I/O cache of the virtual machine
4738	will be enabled.
4739	</desc>
4740	</attribute>
4741
4742	<attribute name="ioCacheSize" type="unsigned long">
4743	<desc>
4744	Maximum size of the I/O cache in MB.
4745	</desc>
4746	</attribute>
4747
4748	<attribute name="ioBandwidthMax" type="unsigned long">
4749	<desc>
4750	The maximum number of MB the VM is allowed to transfer per second.
4751	0 means unlimited bandwidth.
4752	</desc>
4753	</attribute>
4754
4755	<method name="setBootOrder">
4756	<desc>
4757	Puts the given device to the specified position in
4758	the boot order.
4759
4760	To indicate that no device is associated with the given position,
4761	<link to="DeviceType_Null"/> should be used.
4762
4763	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4764
4765	<result name="E_INVALIDARG">
4766	Boot @a position out of range.
4767	</result>
4768	<result name="E_NOTIMPL">
4769	Booting from USB @a device currently not supported.
4770	</result>
4771
4772	</desc>
4773	<param name="position" type="unsigned long" dir="in">
4774	<desc>
4775	Position in the boot order (@c 1 to the total number of
4776	devices the machine can boot from, as returned by
4777	<link to="ISystemProperties::maxBootPosition"/>).
4778	</desc>
4779	</param>
4780	<param name="device" type="DeviceType" dir="in">
4781	<desc>
4782	The type of the device used to boot at the given position.
4783	</desc>
4784	</param>
4785	</method>
4786
4787	<method name="getBootOrder" const="yes">
4788	<desc>
4789	Returns the device type that occupies the specified
4790	position in the boot order.
4791
4792	@todo [remove?]
4793	If the machine can have more than one device of the returned type
4794	(such as hard disks), then a separate method should be used to
4795	retrieve the individual device that occupies the given position.
4796
4797	If here are no devices at the given position, then
4798	<link to="DeviceType_Null"/> is returned.
4799
4800	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4801
4802	<result name="E_INVALIDARG">
4803	Boot @a position out of range.
4804	</result>
4805
4806	</desc>
4807	<param name="position" type="unsigned long" dir="in">
4808	<desc>
4809	Position in the boot order (@c 1 to the total number of
4810	devices the machine can boot from, as returned by
4811	<link to="ISystemProperties::maxBootPosition"/>).
4812	</desc>
4813	</param>
4814	<param name="device" type="DeviceType" dir="return">
4815	<desc>
4816	Device at the given position.
4817	</desc>
4818	</param>
4819	</method>
4820
4821	<method name="attachDevice">
4822	<desc>
4823	Attaches a device and optionally mounts a medium to the given storage
4824	controller (<link to="IStorageController" />, identified by @a name),
4825	at the indicated port and device.
4826
4827	This method is intended for managing storage devices in general (it works
4828	for both fixed and removable media). For storage devices supporting removable
4829	media (such as DVDs and floppies), you can also use <link to="IMedium::mountMedium"/>
4830	for changing the media while the machine is running.
4831
4832	In a VM's default configuration of virtual machines, the secondary
4833	master of the IDE controller is used for a CD/DVD drive.
4834
4835	For fixed media such as hard disks, the given medium identifier cannot
4836	be a zero UUID. It may be a zero UUID for removable media such as DVDs
4837	and floppies.
4838
4839	After calling this returns successfully, a new instance of
4840	<link to="IMediumAttachment"/> will appear in the machine's list of medium
4841	attachments (<link to="IMachine::mediumAttachments"/>).
4842
4843	The specified device slot must not have a device attached to it,
4844	or this method will fail.
4845
4846	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4847	information about attaching media.
4848
4849	<note>
4850	You cannot attach a device to a running machine. Also, you cannot
4851	attach a device to a newly created machine until this machine's
4852	settings are saved to disk using <link to="#saveSettings"/>.
4853	</note>
4854	<note>
4855	If the medium is being attached indirectly, a new differencing medium
4856	will implicitly be created for it and attached instead. If the
4857	changes made to the machine settings (including this indirect
4858	attachment) are later cancelled using <link to="#discardSettings"/>,
4859	this implicitly created differencing medium will implicitly
4860	be deleted.
4861	</note>
4862
4863	<result name="E_INVALIDARG">
4864	SATA device, SATA port, IDE port or IDE slot out of range.
4865	</result>
4866	<result name="VBOX_E_INVALID_OBJECT_STATE">
4867	Attempt to attach medium to an unregistered virtual machine.
4868	</result>
4869	<result name="VBOX_E_INVALID_VM_STATE">
4870	Invalid machine state.
4871	</result>
4872	<result name="VBOX_E_OBJECT_IN_USE">
4873	Hard disk already attached to this or another virtual machine.
4874	</result>
4875
4876	</desc>
4877	<param name="name" type="wstring" dir="in">
4878	<desc>Name of the storage controller to attach the device to.</desc>
4879	</param>
4880	<param name="controllerPort" type="long" dir="in">
4881	<desc>Port to attach the device to. For an IDE controller, 0 specifies
4882	the primary controller and 1 specifies the secondary controller.
4883	For a SCSI controller, this must range from 0 to 15; for a SATA controller,
4884	from 0 to 29; for an SAS controller, from 0 to 7.</desc>
4885	</param>
4886	<param name="device" type="long" dir="in">
4887	<desc>Device slot in the given port to attach the device to. This is only
4888	relevant for IDE controllers, for which 0 specifies the master device and
4889	1 specifies the slave device. For all other controller types, this must
4890	be 0.</desc>
4891	</param>
4892	<param name="type" type="DeviceType" dir="in">
4893	<desc>Device type of the attached device.</desc>
4894	</param>
4895	<param name="id" type="uuid" mod="string" dir="in">
4896	<desc>UUID of the medium to mount. Zero UUID means do not mount any
4897	medium.</desc>
4898	</param>
4899	</method>
4900
4901	<method name="detachDevice">
4902	<desc>
4903	Detaches the device attached to a device slot of the specified bus.
4904
4905	Detaching the device from the virtual machine is deferred. This means
4906	that the medium remains associated with the machine when this method
4907	returns and gets actually de-associated only after a successful
4908	<link to="#saveSettings"/> call. See <link to="IMedium"/>
4909	for more detailed information about attaching media.
4910
4911	<note>
4912	You cannot detach a device from a running machine.
4913	</note>
4914	<note>
4915	Detaching differencing media implicitly created by <link
4916	to="#attachDevice"/> for the indirect attachment using this
4917	method will <b>not</b> implicitly delete them. The
4918	<link to="IMedium::deleteStorage"/> operation should be
4919	explicitly performed by the caller after the medium is successfully
4920	detached and the settings are saved with
4921	<link to="#saveSettings"/>, if it is the desired action.
4922	</note>
4923
4924	<result name="VBOX_E_INVALID_VM_STATE">
4925	Attempt to detach medium from a running virtual machine.
4926	</result>
4927	<result name="VBOX_E_OBJECT_NOT_FOUND">
4928	No medium attached to given slot/bus.
4929	</result>
4930	<result name="VBOX_E_NOT_SUPPORTED">
4931	Medium format does not support storage deletion.
4932	</result>
4933
4934	</desc>
4935	<param name="name" type="wstring" dir="in">
4936	<desc>Name of the storage controller to detach the medium from.</desc>
4937	</param>
4938	<param name="controllerPort" type="long" dir="in">
4939	<desc>Port number to detach the medium from.</desc>
4940	</param>
4941	<param name="device" type="long" dir="in">
4942	<desc>Device slot number to detach the medium from.</desc>
4943	</param>
4944	</method>
4945
4946	<method name="passthroughDevice">
4947	<desc>
4948	Sets the passthrough mode of an existing DVD device. Changing the
4949	setting while the VM is running is forbidden. The setting is only used
4950	if at VM start the device is configured as a host DVD drive, in all
4951	other cases it is ignored. The device must already exist; see
4952	<link to="IMachine::attachDevice"/> for how to attach a new device.
4953
4954	The @a controllerPort and @a device parameters specify the device slot and
4955	have have the same meaning as with <link to="IMachine::attachDevice" />.
4956
4957	<result name="E_INVALIDARG">
4958	SATA device, SATA port, IDE port or IDE slot out of range.
4959	</result>
4960	<result name="VBOX_E_INVALID_OBJECT_STATE">
4961	Attempt to modify an unregistered virtual machine.
4962	</result>
4963	<result name="VBOX_E_INVALID_VM_STATE">
4964	Invalid machine state.
4965	</result>
4966
4967	</desc>
4968	<param name="name" type="wstring" dir="in">
4969	<desc>Name of the storage controller.</desc>
4970	</param>
4971	<param name="controllerPort" type="long" dir="in">
4972	<desc>Storage controller port.</desc>
4973	</param>
4974	<param name="device" type="long" dir="in">
4975	<desc>Device slot in the given port.</desc>
4976	</param>
4977	<param name="passthrough" type="boolean" dir="in">
4978	<desc>New value for the passthrough setting.</desc>
4979	</param>
4980	</method>
4981
4982	<method name="mountMedium">
4983	<desc>
4984	Mounts a medium (<link to="IMedium" />, identified
4985	by the given UUID @a id) to the given storage controller
4986	(<link to="IStorageController" />, identified by @a name),
4987	at the indicated port and device. The device must already exist;
4988	see <link to="IMachine::attachDevice"/> for how to attach a new device.
4989
4990	This method is intended only for managing removable media, where the
4991	device is fixed but media is changeable at runtime (such as DVDs
4992	and floppies). It cannot be used for fixed media such as hard disks.
4993
4994	The @a controllerPort and @a device parameters specify the device slot and
4995	have have the same meaning as with <link to="IMachine::attachDevice" />.
4996
4997	The specified device slot can have a medium mounted, which will be
4998	unmounted first. Specifying a zero UUID (or an empty string) for
4999	@a medium does just an unmount.
5000
5001	See <link to="IMedium"/> for more detailed information about
5002	attaching media.
5003
5004	<result name="E_INVALIDARG">
5005	SATA device, SATA port, IDE port or IDE slot out of range.
5006	</result>
5007	<result name="VBOX_E_INVALID_OBJECT_STATE">
5008	Attempt to attach medium to an unregistered virtual machine.
5009	</result>
5010	<result name="VBOX_E_INVALID_VM_STATE">
5011	Invalid machine state.
5012	</result>
5013	<result name="VBOX_E_OBJECT_IN_USE">
5014	Medium already attached to this or another virtual machine.
5015	</result>
5016
5017	</desc>
5018	<param name="name" type="wstring" dir="in">
5019	<desc>Name of the storage controller to attach the medium to.</desc>
5020	</param>
5021	<param name="controllerPort" type="long" dir="in">
5022	<desc>Port to attach the medium to.</desc>
5023	</param>
5024	<param name="device" type="long" dir="in">
5025	<desc>Device slot in the given port to attach the medium to.</desc>
5026	</param>
5027	<param name="medium" type="uuid" mod="string" dir="in">
5028	<desc>UUID of the medium to attach. A zero UUID means unmount the
5029	currently mounted medium.</desc>
5030	</param>
5031	<param name="force" type="boolean" dir="in">
5032	<desc>Allows to force unmount/mount of a medium which is locked by
5033	theDevice slot in the given port to attach the medium to.</desc>
5034	</param>
5035	</method>
5036
5037	<method name="getMedium" const="yes">
5038	<desc>
5039	Returns the virtual medium attached to a device slot of the specified
5040	bus.
5041
5042	Note that if the medium was indirectly attached by
5043	<link to="#mountMedium"/> to the given device slot then this
5044	method will return not the same object as passed to the
5045	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5046	more detailed information about mounting a medium.
5047
5048	<result name="VBOX_E_OBJECT_NOT_FOUND">
5049	No medium attached to given slot/bus.
5050	</result>
5051
5052	</desc>
5053	<param name="name" type="wstring" dir="in">
5054	<desc>Name of the storage controller the medium is attached to.</desc>
5055	</param>
5056	<param name="controllerPort" type="long" dir="in">
5057	<desc>Port to query.</desc>
5058	</param>
5059	<param name="device" type="long" dir="in">
5060	<desc>Device slot in the given port to query.</desc>
5061	</param>
5062	<param name="medium" type="IMedium" dir="return">
5063	<desc>Attached medium object.</desc>
5064	</param>
5065	</method>
5066
5067	<method name="getMediumAttachmentsOfController" const="yes">
5068	<desc>
5069	Returns an array of medium attachments which are attached to the
5070	the controller with the given name.
5071
5072	<result name="VBOX_E_OBJECT_NOT_FOUND">
5073	A storage controller with given name doesn't exist.
5074	</result>
5075	</desc>
5076	<param name="name" type="wstring" dir="in"/>
5077	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5078	</method>
5079
5080	<method name="getMediumAttachment" const="yes">
5081	<desc>
5082	Returns a medium attachment which corresponds to the controller with
5083	the given name, on the given port and device slot.
5084
5085	<result name="VBOX_E_OBJECT_NOT_FOUND">
5086	No attachment exists for the given controller/port/device combination.
5087	</result>
5088	</desc>
5089	<param name="name" type="wstring" dir="in"/>
5090	<param name="controllerPort" type="long" dir="in"/>
5091	<param name="device" type="long" dir="in"/>
5092	<param name="attachment" type="IMediumAttachment" dir="return"/>
5093	</method>
5094
5095	<method name="getNetworkAdapter" const="yes">
5096	<desc>
5097	Returns the network adapter associated with the given slot.
5098	Slots are numbered sequentially, starting with zero. The total
5099	number of adapters per machine is defined by the
5100	<link to="ISystemProperties::networkAdapterCount"/> property,
5101	so the maximum slot number is one less than that property's value.
5102
5103	<result name="E_INVALIDARG">
5104	Invalid @a slot number.
5105	</result>
5106
5107	</desc>
5108	<param name="slot" type="unsigned long" dir="in"/>
5109	<param name="adapter" type="INetworkAdapter" dir="return"/>
5110	</method>
5111
5112	<method name="addStorageController">
5113	<desc>
5114	Adds a new storage controller (SCSI, SAS or SATA controller) to the
5115	machine and returns it as an instance of
5116	<link to="IStorageController" />.
5117
5118	@a name identifies the controller for subsequent calls such as
5119	<link to="#getStorageControllerByName" />,
5120	<link to="#getStorageControllerByInstance" />,
5121	<link to="#removeStorageController" />,
5122	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5123
5124	After the controller has been added, you can set its exact
5125	type by setting the <link to="IStorageController::controllerType" />.
5126
5127	<result name="VBOX_E_OBJECT_IN_USE">
5128	A storage controller with given name exists already.
5129	</result>
5130	<result name="E_INVALIDARG">
5131	Invalid @a controllerType.
5132	</result>
5133	</desc>
5134	<param name="name" type="wstring" dir="in"/>
5135	<param name="connectionType" type="StorageBus" dir="in"/>
5136	<param name="controller" type="IStorageController" dir="return"/>
5137	</method>
5138
5139	<method name="getStorageControllerByName" const="yes">
5140	<desc>
5141	Returns a storage controller with the given name.
5142
5143	<result name="VBOX_E_OBJECT_NOT_FOUND">
5144	A storage controller with given name doesn't exist.
5145	</result>
5146	</desc>
5147	<param name="name" type="wstring" dir="in"/>
5148	<param name="storageController" type="IStorageController" dir="return"/>
5149	</method>
5150
5151	<method name="getStorageControllerByInstance" const="yes">
5152	<desc>
5153	Returns a storage controller with the given instance number.
5154
5155	<result name="VBOX_E_OBJECT_NOT_FOUND">
5156	A storage controller with given instance number doesn't exist.
5157	</result>
5158	</desc>
5159	<param name="instance" type="unsigned long" dir="in"/>
5160	<param name="storageController" type="IStorageController" dir="return"/>
5161	</method>
5162
5163	<method name="removeStorageController">
5164	<desc>
5165	Removes a storage controller from the machine.
5166
5167	<result name="VBOX_E_OBJECT_NOT_FOUND">
5168	A storage controller with given name doesn't exist.
5169	</result>
5170	</desc>
5171	<param name="name" type="wstring" dir="in"/>
5172	</method>
5173
5174	<method name="getSerialPort" const="yes">
5175	<desc>
5176	Returns the serial port associated with the given slot.
5177	Slots are numbered sequentially, starting with zero. The total
5178	number of serial ports per machine is defined by the
5179	<link to="ISystemProperties::serialPortCount"/> property,
5180	so the maximum slot number is one less than that property's value.
5181
5182	<result name="E_INVALIDARG">
5183	Invalid @a slot number.
5184	</result>
5185
5186	</desc>
5187	<param name="slot" type="unsigned long" dir="in"/>
5188	<param name="port" type="ISerialPort" dir="return"/>
5189	</method>
5190
5191	<method name="getParallelPort" const="yes">
5192	<desc>
5193	Returns the parallel port associated with the given slot.
5194	Slots are numbered sequentially, starting with zero. The total
5195	number of parallel ports per machine is defined by the
5196	<link to="ISystemProperties::parallelPortCount"/> property,
5197	so the maximum slot number is one less than that property's value.
5198
5199	<result name="E_INVALIDARG">
5200	Invalid @a slot number.
5201	</result>
5202
5203	</desc>
5204	<param name="slot" type="unsigned long" dir="in"/>
5205	<param name="port" type="IParallelPort" dir="return"/>
5206	</method>
5207
5208	<method name="getExtraDataKeys">
5209	<desc>
5210	Returns an array representing the machine-specific extra data keys
5211	which currently have values defined.
5212	</desc>
5213	<param name="value" type="wstring" dir="return" safearray="yes">
5214	<desc>Array of extra data keys.</desc>
5215	</param>
5216	</method>
5217
5218	<method name="getExtraData">
5219	<desc>
5220	Returns associated machine-specific extra data.
5221
5222	If the requested data @a key does not exist, this function will
5223	succeed and return an empty string in the @a value argument.
5224
5225	<result name="VBOX_E_FILE_ERROR">
5226	Settings file not accessible.
5227	</result>
5228	<result name="VBOX_E_XML_ERROR">
5229	Could not parse the settings file.
5230	</result>
5231
5232	</desc>
5233	<param name="key" type="wstring" dir="in">
5234	<desc>Name of the data key to get.</desc>
5235	</param>
5236	<param name="value" type="wstring" dir="return">
5237	<desc>Value of the requested data key.</desc>
5238	</param>
5239	</method>
5240
5241	<method name="setExtraData">
5242	<desc>
5243	Sets associated machine-specific extra data.
5244
5245	If you pass @c null or an empty string as a key @a value, the given
5246	@a key will be deleted.
5247
5248	<note>
5249	Before performing the actual data change, this method will ask all
5250	registered callbacks using the
5251	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
5252	notification for a permission. If one of the callbacks refuses the
5253	new value, the change will not be performed.
5254	</note>
5255	<note>
5256	On success, the
5257	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
5258	is called to inform all registered callbacks about a successful data
5259	change.
5260	</note>
5261	<note>
5262	This method can be called outside the machine session and therefore
5263	it's a caller's responsibility to handle possible race conditions
5264	when several clients change the same key at the same time.
5265	</note>
5266
5267	<result name="VBOX_E_FILE_ERROR">
5268	Settings file not accessible.
5269	</result>
5270	<result name="VBOX_E_XML_ERROR">
5271	Could not parse the settings file.
5272	</result>
5273
5274	</desc>
5275	<param name="key" type="wstring" dir="in">
5276	<desc>Name of the data key to set.</desc>
5277	</param>
5278	<param name="value" type="wstring" dir="in">
5279	<desc>Value to assign to the key.</desc>
5280	</param>
5281	</method>
5282
5283	<method name="getCPUProperty" const="yes">
5284	<desc>
5285	Returns the virtual CPU boolean value of the specified property.
5286
5287	<result name="E_INVALIDARG">
5288	Invalid property.
5289	</result>
5290
5291	</desc>
5292	<param name="property" type="CPUPropertyType" dir="in">
5293	<desc>
5294	Property type to query.
5295	</desc>
5296	</param>
5297	<param name="value" type="boolean" dir="return">
5298	<desc>
5299	Property value.
5300	</desc>
5301	</param>
5302	</method>
5303
5304	<method name="setCPUProperty">
5305	<desc>
5306	Sets the virtual CPU boolean value of the specified property.
5307
5308	<result name="E_INVALIDARG">
5309	Invalid property.
5310	</result>
5311
5312	</desc>
5313	<param name="property" type="CPUPropertyType" dir="in">
5314	<desc>
5315	Property type to query.
5316	</desc>
5317	</param>
5318	<param name="value" type="boolean" dir="in">
5319	<desc>
5320	Property value.
5321	</desc>
5322	</param>
5323	</method>
5324
5325	<method name="getCPUIDLeaf" const="yes">
5326	<desc>
5327	Returns the virtual CPU cpuid information for the specified leaf.
5328
5329	Currently supported index values for cpuid:
5330	Standard CPUID leafs: 0 - 0xA
5331	Extended CPUID leafs: 0x80000000 - 0x8000000A
5332
5333	See the Intel and AMD programmer's manuals for detailed information
5334	about the cpuid instruction and its leafs.
5335	<result name="E_INVALIDARG">
5336	Invalid id.
5337	</result>
5338
5339	</desc>
5340	<param name="id" type="unsigned long" dir="in">
5341	<desc>
5342	CPUID leaf index.
5343	</desc>
5344	</param>
5345	<param name="valEax" type="unsigned long" dir="out">
5346	<desc>
5347	CPUID leaf value for register eax.
5348	</desc>
5349	</param>
5350	<param name="valEbx" type="unsigned long" dir="out">
5351	<desc>
5352	CPUID leaf value for register ebx.
5353	</desc>
5354	</param>
5355	<param name="valEcx" type="unsigned long" dir="out">
5356	<desc>
5357	CPUID leaf value for register ecx.
5358	</desc>
5359	</param>
5360	<param name="valEdx" type="unsigned long" dir="out">
5361	<desc>
5362	CPUID leaf value for register edx.
5363	</desc>
5364	</param>
5365	</method>
5366
5367	<method name="setCPUIDLeaf">
5368	<desc>
5369	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5370	are not passed unmodified. VirtualBox clears features that it doesn't support.
5371
5372	Currently supported index values for cpuid:
5373	Standard CPUID leafs: 0 - 0xA
5374	Extended CPUID leafs: 0x80000000 - 0x8000000A
5375
5376	See the Intel and AMD programmer's manuals for detailed information
5377	about the cpuid instruction and its leafs.
5378
5379	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5380	random crashes inside VMs.
5381	<result name="E_INVALIDARG">
5382	Invalid id.
5383	</result>
5384
5385	</desc>
5386	<param name="id" type="unsigned long" dir="in">
5387	<desc>
5388	CPUID leaf index.
5389	</desc>
5390	</param>
5391	<param name="valEax" type="unsigned long" dir="in">
5392	<desc>
5393	CPUID leaf value for register eax.
5394	</desc>
5395	</param>
5396	<param name="valEbx" type="unsigned long" dir="in">
5397	<desc>
5398	CPUID leaf value for register ebx.
5399	</desc>
5400	</param>
5401	<param name="valEcx" type="unsigned long" dir="in">
5402	<desc>
5403	CPUID leaf value for register ecx.
5404	</desc>
5405	</param>
5406	<param name="valEdx" type="unsigned long" dir="in">
5407	<desc>
5408	CPUID leaf value for register edx.
5409	</desc>
5410	</param>
5411	</method>
5412
5413	<method name="removeCPUIDLeaf">
5414	<desc>
5415	Removes the virtual CPU cpuid leaf for the specified index
5416
5417	<result name="E_INVALIDARG">
5418	Invalid id.
5419	</result>
5420
5421	</desc>
5422	<param name="id" type="unsigned long" dir="in">
5423	<desc>
5424	CPUID leaf index.
5425	</desc>
5426	</param>
5427	</method>
5428
5429	<method name="removeAllCPUIDLeaves">
5430	<desc>
5431	Removes all the virtual CPU cpuid leaves
5432	</desc>
5433	</method>
5434
5435	<method name="getHWVirtExProperty" const="yes">
5436	<desc>
5437	Returns the value of the specified hardware virtualization boolean property.
5438
5439	<result name="E_INVALIDARG">
5440	Invalid property.
5441	</result>
5442
5443	</desc>
5444	<param name="property" type="HWVirtExPropertyType" dir="in">
5445	<desc>
5446	Property type to query.
5447	</desc>
5448	</param>
5449	<param name="value" type="boolean" dir="return">
5450	<desc>
5451	Property value.
5452	</desc>
5453	</param>
5454	</method>
5455
5456	<method name="setHWVirtExProperty">
5457	<desc>
5458	Sets a new value for the specified hardware virtualization boolean property.
5459
5460	<result name="E_INVALIDARG">
5461	Invalid property.
5462	</result>
5463
5464	</desc>
5465	<param name="property" type="HWVirtExPropertyType" dir="in">
5466	<desc>
5467	Property type to set.
5468	</desc>
5469	</param>
5470	<param name="value" type="boolean" dir="in">
5471	<desc>
5472	New property value.
5473	</desc>
5474	</param>
5475	</method>
5476
5477	<method name="saveSettings">
5478	<desc>
5479	Saves any changes to machine settings made since the session
5480	has been opened or a new machine has been created, or since the
5481	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
5482	For registered machines, new settings become visible to all
5483	other VirtualBox clients after successful invocation of this
5484	method.
5485	<note>
5486	The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
5487	notification event after the configuration has been successfully
5488	saved (only for registered machines).
5489	</note>
5490	<note>
5491	Calling this method is only valid on instances returned
5492	by <link to="ISession::machine"/> and on new machines
5493	created by <link to="IVirtualBox::createMachine"/> but not
5494	yet registered, or on unregistered machines after calling
5495	<link to="IVirtualBox::unregisterMachine"/>.
5496	</note>
5497
5498	<result name="VBOX_E_FILE_ERROR">
5499	Settings file not accessible.
5500	</result>
5501	<result name="VBOX_E_XML_ERROR">
5502	Could not parse the settings file.
5503	</result>
5504	<result name="E_ACCESSDENIED">
5505	Modification request refused.
5506	</result>
5507
5508	</desc>
5509	</method>
5510
5511	<method name="discardSettings">
5512	<desc>
5513	Discards any changes to the machine settings made since the session
5514	has been opened or since the last call to <link to="#saveSettings"/>
5515	or <link to="#discardSettings"/>.
5516	<note>
5517	Calling this method is only valid on instances returned
5518	by <link to="ISession::machine"/> and on new machines
5519	created by <link to="IVirtualBox::createMachine"/> or
5520	opened by <link to="IVirtualBox::openMachine"/> but not
5521	yet registered, or on unregistered machines after calling
5522	<link to="IVirtualBox::unregisterMachine"/>.
5523	</note>
5524
5525	<result name="VBOX_E_INVALID_VM_STATE">
5526	Virtual machine is not mutable.
5527	</result>
5528
5529	</desc>
5530	</method>
5531
5532	<method name="deleteSettings">
5533	<desc>
5534	Deletes the settings file of this machine from disk.
5535	The machine must not be registered in order for this operation
5536	to succeed.
5537	<note>
5538	<link to="#settingsModified"/> will return @c true after this
5539	method successfully returns.
5540	</note>
5541	<note>
5542	Calling this method is only valid on instances returned
5543	by <link to="ISession::machine"/> and on new machines
5544	created by <link to="IVirtualBox::createMachine"/> or
5545	opened by <link to="IVirtualBox::openMachine"/> but not
5546	yet registered, or on unregistered machines after calling
5547	<link to="IVirtualBox::unregisterMachine"/>.
5548	</note>
5549	<note>
5550	The deleted machine settings file can be restored (saved again)
5551	by calling <link to="#saveSettings"/>.
5552	</note>
5553
5554	<result name="VBOX_E_INVALID_VM_STATE">
5555	Cannot delete settings of a registered machine or
5556	machine not mutable.
5557	</result>
5558	<result name="VBOX_E_IPRT_ERROR">
5559	Could not delete the settings file.
5560	</result>
5561
5562	</desc>
5563	</method>
5564
5565	<method name="export">
5566	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5567	steps required to export VirtualBox machines to OVF.
5568	</desc>
5569
5570	<param name="aAppliance" type="IAppliance" dir="in">
5571	<desc>Appliance to export this machine to.</desc>
5572	</param>
5573	<param name="aDescription" type="IVirtualSystemDescription" dir="return">
5574	<desc>VirtualSystemDescription object which is created for this machine.</desc>
5575	</param>
5576	</method >
5577
5578	<method name="getSnapshot">
5579	<desc>
5580	Returns a snapshot of this machine with the given UUID.
5581	A @c null UUID can be used to obtain the first snapshot
5582	taken on this machine. This is useful if you want to traverse
5583	the whole tree of snapshots starting from the root.
5584
5585	<result name="VBOX_E_OBJECT_NOT_FOUND">
5586	Virtual machine has no snapshots or snapshot not found.
5587	</result>
5588
5589	</desc>
5590	<param name="id" type="uuid" mod="string" dir="in">
5591	<desc>UUID of the snapshot to get</desc>
5592	</param>
5593	<param name="snapshot" type="ISnapshot" dir="return">
5594	<desc>Snapshot object with the given UUID.</desc>
5595	</param>
5596	</method>
5597
5598	<method name="findSnapshot">
5599	<desc>
5600	Returns a snapshot of this machine with the given name.
5601
5602	<result name="VBOX_E_OBJECT_NOT_FOUND">
5603	Virtual machine has no snapshots or snapshot not found.
5604	</result>
5605
5606	</desc>
5607	<param name="name" type="wstring" dir="in">
5608	<desc>Name of the snapshot to find</desc>
5609	</param>
5610	<param name="snapshot" type="ISnapshot" dir="return">
5611	<desc>Snapshot object with the given name.</desc>
5612	</param>
5613	</method>
5614
5615	<method name="setCurrentSnapshot">
5616	<desc>
5617	Sets the current snapshot of this machine.
5618	<note>
5619	In the current implementation, this operation is not
5620	implemented.
5621	</note>
5622	</desc>
5623	<param name="id" type="uuid" mod="string" dir="in">
5624	<desc>UUID of the snapshot to set as the current snapshot.</desc>
5625	</param>
5626	</method>
5627
5628	<method name="createSharedFolder">
5629	<desc>
5630	Creates a new permanent shared folder by associating the given logical
5631	name with the given host path, adds it to the collection of shared
5632	folders and starts sharing it. Refer to the description of
5633	<link to="ISharedFolder"/> to read more about logical names.
5634
5635	<result name="VBOX_E_OBJECT_IN_USE">
5636	Shared folder already exists.
5637	</result>
5638	<result name="VBOX_E_FILE_ERROR">
5639	Shared folder @a hostPath not accessible.
5640	</result>
5641
5642	</desc>
5643	<param name="name" type="wstring" dir="in">
5644	<desc>Unique logical name of the shared folder.</desc>
5645	</param>
5646	<param name="hostPath" type="wstring" dir="in">
5647	<desc>Full path to the shared folder in the host file system.</desc>
5648	</param>
5649	<param name="writable" type="boolean" dir="in">
5650	<desc>Whether the share is writable or readonly</desc>
5651	</param>
5652	</method>
5653
5654	<method name="removeSharedFolder">
5655	<desc>
5656	Removes the permanent shared folder with the given name previously
5657	created by <link to="#createSharedFolder"/> from the collection of
5658	shared folders and stops sharing it.
5659
5660	<result name="VBOX_E_INVALID_VM_STATE">
5661	Virtual machine is not mutable.
5662	</result>
5663	<result name="VBOX_E_OBJECT_NOT_FOUND">
5664	Shared folder @a name does not exist.
5665	</result>
5666
5667	</desc>
5668	<param name="name" type="wstring" dir="in">
5669	<desc>Logical name of the shared folder to remove.</desc>
5670	</param>
5671	</method>
5672
5673	<method name="canShowConsoleWindow">
5674	<desc>
5675	Returns @c true if the VM console process can activate the
5676	console window and bring it to foreground on the desktop of
5677	the host PC.
5678	<note>
5679	This method will fail if a session for this machine is not
5680	currently open.
5681	</note>
5682
5683	<result name="VBOX_E_INVALID_VM_STATE">
5684	Machine session is not open.
5685	</result>
5686
5687	</desc>
5688	<param name="canShow" type="boolean" dir="return">
5689	<desc>
5690	@c true if the console window can be shown and @c false otherwise.
5691	</desc>
5692	</param>
5693	</method>
5694
5695	<method name="showConsoleWindow">
5696	<desc>
5697	Activates the console window and brings it to foreground on
5698	the desktop of the host PC. Many modern window managers on
5699	many platforms implement some sort of focus stealing
5700	prevention logic, so that it may be impossible to activate
5701	a window without the help of the currently active
5702	application. In this case, this method will return a non-zero
5703	identifier that represents the top-level window of the VM
5704	console process. The caller, if it represents a currently
5705	active process, is responsible to use this identifier (in a
5706	platform-dependent manner) to perform actual window
5707	activation.
5708	<note>
5709	This method will fail if a session for this machine is not
5710	currently open.
5711	</note>
5712
5713	<result name="VBOX_E_INVALID_VM_STATE">
5714	Machine session is not open.
5715	</result>
5716
5717	</desc>
5718	<param name="winId" type="unsigned long long" dir="return">
5719	<desc>
5720	Platform-dependent identifier of the top-level VM console
5721	window, or zero if this method has performed all actions
5722	necessary to implement the <i>show window</i> semantics for
5723	the given platform and/or VirtualBox front-end.
5724	</desc>
5725	</param>
5726	</method>
5727
5728	<method name="getGuestProperty" const="yes">
5729	<desc>
5730	Reads an entry from the machine's guest property store.
5731
5732	<result name="VBOX_E_INVALID_VM_STATE">
5733	Machine session is not open.
5734	</result>
5735
5736	</desc>
5737	<param name="name" type="wstring" dir="in">
5738	<desc>
5739	The name of the property to read.
5740	</desc>
5741	</param>
5742	<param name="value" type="wstring" dir="out">
5743	<desc>
5744	The value of the property. If the property does not exist then this
5745	will be empty.
5746	</desc>
5747	</param>
5748	<param name="timestamp" type="unsigned long long" dir="out">
5749	<desc>
5750	The time at which the property was last modified, as seen by the
5751	server process.
5752	</desc>
5753	</param>
5754	<param name="flags" type="wstring" dir="out">
5755	<desc>
5756	Additional property parameters, passed as a comma-separated list of
5757	"name=value" type entries.
5758	</desc>
5759	</param>
5760	</method>
5761
5762	<method name="getGuestPropertyValue" const="yes">
5763	<desc>
5764	Reads a value from the machine's guest property store.
5765
5766	<result name="VBOX_E_INVALID_VM_STATE">
5767	Machine session is not open.
5768	</result>
5769
5770	</desc>
5771	<param name="property" type="wstring" dir="in">
5772	<desc>
5773	The name of the property to read.
5774	</desc>
5775	</param>
5776	<param name="value" type="wstring" dir="return">
5777	<desc>
5778	The value of the property. If the property does not exist then this
5779	will be empty.
5780	</desc>
5781	</param>
5782	</method>
5783
5784	<method name="getGuestPropertyTimestamp" const="yes">
5785	<desc>
5786	Reads a property timestamp from the machine's guest property store.
5787
5788	<result name="VBOX_E_INVALID_VM_STATE">
5789	Machine session is not open.
5790	</result>
5791
5792	</desc>
5793	<param name="property" type="wstring" dir="in">
5794	<desc>
5795	The name of the property to read.
5796	</desc>
5797	</param>
5798	<param name="value" type="unsigned long long" dir="return">
5799	<desc>
5800	The timestamp. If the property does not exist then this will be
5801	empty.
5802	</desc>
5803	</param>
5804	</method>
5805
5806	<method name="setGuestProperty">
5807	<desc>
5808	Sets, changes or deletes an entry in the machine's guest property
5809	store.
5810
5811	<result name="E_ACCESSDENIED">
5812	Property cannot be changed.
5813	</result>
5814	<result name="E_INVALIDARG">
5815	Invalid @a flags.
5816	</result>
5817	<result name="VBOX_E_INVALID_VM_STATE">
5818	Virtual machine is not mutable or session not open.
5819	</result>
5820	<result name="VBOX_E_INVALID_OBJECT_STATE">
5821	Cannot set transient property when machine not running.
5822	</result>
5823
5824	</desc>
5825	<param name="property" type="wstring" dir="in">
5826	<desc>
5827	The name of the property to set, change or delete.
5828	</desc>
5829	</param>
5830	<param name="value" type="wstring" dir="in">
5831	<desc>
5832	The new value of the property to set, change or delete. If the
5833	property does not yet exist and value is non-empty, it will be
5834	created. If the value is @c null or empty, the property will be
5835	deleted if it exists.
5836	</desc>
5837	</param>
5838	<param name="flags" type="wstring" dir="in">
5839	<desc>
5840	Additional property parameters, passed as a comma-separated list of
5841	"name=value" type entries.
5842	</desc>
5843	</param>
5844	</method>
5845
5846	<method name="setGuestPropertyValue">
5847	<desc>
5848	Sets, changes or deletes a value in the machine's guest property
5849	store. The flags field will be left unchanged or created empty for a
5850	new property.
5851
5852	<result name="E_ACCESSDENIED">
5853	Property cannot be changed.
5854	</result>
5855	<result name="VBOX_E_INVALID_VM_STATE">
5856	Virtual machine is not mutable or session not open.
5857	</result>
5858	<result name="VBOX_E_INVALID_OBJECT_STATE">
5859	Cannot set transient property when machine not running.
5860	</result>
5861	</desc>
5862
5863	<param name="property" type="wstring" dir="in">
5864	<desc>
5865	The name of the property to set, change or delete.
5866	</desc>
5867	</param>
5868	<param name="value" type="wstring" dir="in">
5869	<desc>
5870	The new value of the property to set, change or delete. If the
5871	property does not yet exist and value is non-empty, it will be
5872	created. If the value is @c null or empty, the property will be
5873	deleted if it exists.
5874	</desc>
5875	</param>
5876	</method>
5877
5878	<method name="enumerateGuestProperties">
5879	<desc>
5880	Return a list of the guest properties matching a set of patterns along
5881	with their values, time stamps and flags.
5882	</desc>
5883	<param name="patterns" type="wstring" dir="in">
5884	<desc>
5885	The patterns to match the properties against, separated by '\|'
5886	characters. If this is empty or @c null, all properties will match.
5887	</desc>
5888	</param>
5889	<param name="name" type="wstring" dir="out" safearray="yes">
5890	<desc>
5891	The names of the properties returned.
5892	</desc>
5893	</param>
5894	<param name="value" type="wstring" dir="out" safearray="yes">
5895	<desc>
5896	The values of the properties returned. The array entries match the
5897	corresponding entries in the @a name array.
5898	</desc>
5899	</param>
5900	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5901	<desc>
5902	The time stamps of the properties returned. The array entries match
5903	the corresponding entries in the @a name array.
5904	</desc>
5905	</param>
5906	<param name="flags" type="wstring" dir="out" safearray="yes">
5907	<desc>
5908	The flags of the properties returned. The array entries match the
5909	corresponding entries in the @a name array.
5910	</desc>
5911	</param>
5912	</method>
5913
5914	<method name="querySavedThumbnailSize">
5915	<desc>
5916	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
5917	</desc>
5918	<param name="screenId" type="unsigned long" dir="in">
5919	<desc>
5920	Saved guest screen to query info from.
5921	</desc>
5922	</param>
5923	<param name="size" type="unsigned long" dir="out">
5924	<desc>
5925	Size of buffer required to store the bitmap.
5926	</desc>
5927	</param>
5928	<param name="width" type="unsigned long" dir="out">
5929	<desc>
5930	Bitmap width.
5931	</desc>
5932	</param>
5933	<param name="height" type="unsigned long" dir="out">
5934	<desc>
5935	Bitmap height.
5936	</desc>
5937	</param>
5938	</method>
5939
5940	<method name="readSavedThumbnailToArray">
5941	<desc>
5942	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
5943	</desc>
5944	<param name="screenId" type="unsigned long" dir="in">
5945	<desc>
5946	Saved guest screen to read from.
5947	</desc>
5948	</param>
5949	<param name="BGR" type="boolean" dir="in">
5950	<desc>
5951	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
5952	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
5953	</desc>
5954	</param>
5955	<param name="width" type="unsigned long" dir="out">
5956	<desc>
5957	Bitmap width.
5958	</desc>
5959	</param>
5960	<param name="height" type="unsigned long" dir="out">
5961	<desc>
5962	Bitmap height.
5963	</desc>
5964	</param>
5965	<param name="data" type="octet" dir="return" safearray="yes">
5966	<desc>
5967	Array with resulting bitmap data.
5968	</desc>
5969	</param>
5970	</method>
5971
5972	<method name="querySavedScreenshotPNGSize">
5973	<desc>
5974	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
5975	</desc>
5976	<param name="screenId" type="unsigned long" dir="in">
5977	<desc>
5978	Saved guest screen to query info from.
5979	</desc>
5980	</param>
5981	<param name="size" type="unsigned long" dir="out">
5982	<desc>
5983	Size of buffer required to store the PNG binary data.
5984	</desc>
5985	</param>
5986	<param name="width" type="unsigned long" dir="out">
5987	<desc>
5988	Image width.
5989	</desc>
5990	</param>
5991	<param name="height" type="unsigned long" dir="out">
5992	<desc>
5993	Image height.
5994	</desc>
5995	</param>
5996	</method>
5997
5998	<method name="readSavedScreenshotPNGToArray">
5999	<desc>
6000	Screenshot in PNG format is retrieved to an array of bytes.
6001	</desc>
6002	<param name="screenId" type="unsigned long" dir="in">
6003	<desc>
6004	Saved guest screen to read from.
6005	</desc>
6006	</param>
6007	<param name="width" type="unsigned long" dir="out">
6008	<desc>
6009	Image width.
6010	</desc>
6011	</param>
6012	<param name="height" type="unsigned long" dir="out">
6013	<desc>
6014	Image height.
6015	</desc>
6016	</param>
6017	<param name="data" type="octet" dir="return" safearray="yes">
6018	<desc>
6019	Array with resulting PNG data.
6020	</desc>
6021	</param>
6022	</method>
6023
6024	<method name="hotPlugCPU">
6025	<desc>
6026	Plugs a CPU into the machine.
6027	</desc>
6028	<param name="cpu" type="unsigned long" dir="in">
6029	<desc>
6030	The CPU id to insert.
6031	</desc>
6032	</param>
6033	</method>
6034
6035	<method name="hotUnplugCPU">
6036	<desc>
6037	Removes a CPU from the machine.
6038	</desc>
6039	<param name="cpu" type="unsigned long" dir="in">
6040	<desc>
6041	The CPU id to remove.
6042	</desc>
6043	</param>
6044	</method>
6045
6046	<method name="getCPUStatus">
6047	<desc>
6048	Returns the current status of the given CPU.
6049	</desc>
6050	<param name="cpu" type="unsigned long" dir="in">
6051	<desc>
6052	The CPU id to check for.
6053	</desc>
6054	</param>
6055	<param name="attached" type="boolean" dir="return">
6056	<desc>
6057	Status of the CPU.
6058	</desc>
6059	</param>
6060	</method>
6061
6062	<method name="queryLogFilename">
6063	<desc>
6064	Queries for the VM log file name of an given index. Returns an empty
6065	string if a log file with that index doesn't exists.
6066	</desc>
6067	<param name="idx" type="unsigned long" dir="in">
6068	<desc>
6069	Which log file name to query. 0=current log file.
6070	</desc>
6071	</param>
6072	<param name="filename" type="wstring" dir="return">
6073	<desc>
6074	On return the full path to the log file or an empty string on error.
6075	</desc>
6076	</param>
6077	</method>
6078
6079	<method name="readLog">
6080	<desc>
6081	Reads the VM log file. The chunk size is limited, so even if you
6082	ask for a big piece there might be less data returned.
6083	</desc>
6084	<param name="idx" type="unsigned long" dir="in">
6085	<desc>
6086	Which log file to read. 0=current log file.
6087	</desc>
6088	</param>
6089	<param name="offset" type="unsigned long long" dir="in">
6090	<desc>
6091	Offset in the log file.
6092	</desc>
6093	</param>
6094	<param name="size" type="unsigned long long" dir="in">
6095	<desc>
6096	Chunk size to read in the log file.
6097	</desc>
6098	</param>
6099	<param name="data" type="octet" dir="return" safearray="yes">
6100	<desc>
6101	Data read from the log file. A data size of 0 means end of file
6102	if the requested chunk size was not 0. This is the unprocessed
6103	file data, i.e. the line ending style depends on the platform of
6104	the system the server is running on.
6105	</desc>
6106	</param>
6107	</method>
6108	</interface>
6109
6110	<!--
6111	// IConsole
6112	/////////////////////////////////////////////////////////////////////////
6113	-->
6114
6115	<interface
6116	name="IConsoleCallback" extends="$unknown"
6117	uuid="60703f8d-81e4-4b45-a147-dcfd07692b19"
6118	wsmap="suppress"
6119	>
6120
6121	<desc>
6122	This interface is used by a client of the Main API that need to
6123	be notified of events. For example, a graphical user interface
6124	can use this to learn about machine state changes so they can
6125	update the list of virtual machines without having to rely
6126	on polling.
6127
6128	Whenever relevant events occur in VirtualBox, the callbacks in
6129	objects of this interface are called. In order for this to be
6130	useful, a client needs to create its own subclass that implements
6131	this interface in which the methods for the relevant callbacks
6132	are overridden. An instance of this subclass interface can then
6133	be passed to <link to="IConsole::registerCallback" />.
6134	</desc>
6135
6136	<method name="onMousePointerShapeChange">
6137	<desc>
6138	Notification when the guest mouse pointer shape has
6139	changed. The new shape data is given.
6140	<result name="VBOX_E_DONT_CALL_AGAIN">
6141	Do not call again, this method is a NOP.
6142	</result>
6143	</desc>
6144	<param name="visible" type="boolean" dir="in">
6145	<desc>
6146	Flag whether the pointer is visible.
6147	</desc>
6148	</param>
6149	<param name="alpha" type="boolean" dir="in">
6150	<desc>
6151	Flag whether the pointer has an alpha channel.
6152	</desc>
6153	</param>
6154	<param name="xHot" type="unsigned long" dir="in">
6155	<desc>
6156	The pointer hot spot x coordinate.
6157	</desc>
6158	</param>
6159	<param name="yHot" type="unsigned long" dir="in">
6160	<desc>
6161	The pointer hot spot y coordinate.
6162	</desc>
6163	</param>
6164	<param name="width" type="unsigned long" dir="in">
6165	<desc>
6166	Width of the pointer shape in pixels.
6167	</desc>
6168	</param>
6169	<param name="height" type="unsigned long" dir="in">
6170	<desc>
6171	Height of the pointer shape in pixels.
6172	</desc>
6173	</param>
6174	<param name="shape" type="octet" safearray="yes" dir="in">
6175	<desc>
6176	Shape buffer arrays.
6177
6178	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
6179	followed by a 32-bpp XOR (color) mask.
6180
6181	For pointers without alpha channel the XOR mask pixels are 32
6182	bit values: (lsb)BGR0(msb). For pointers with alpha channel
6183	the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
6184
6185	An AND mask is used for pointers with alpha channel, so if the
6186	callback does not support alpha, the pointer could be
6187	displayed as a normal color pointer.
6188
6189	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
6190	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
6191	height</tt>. The padding bits at the end of each scanline are
6192	undefined.
6193
6194	The XOR mask follows the AND mask on the next 4-byte aligned
6195	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
6196	Bytes in the gap between the AND and the XOR mask are undefined.
6197	The XOR mask scanlines have no gap between them and the size of
6198	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
6199
6200	<note>
6201	If @a shape is 0, only the pointer visibility is changed.
6202	</note>
6203	</desc>
6204	</param>
6205	</method>
6206
6207	<method name="onMouseCapabilityChange">
6208	<desc>
6209	Notification when the mouse capabilities reported by the
6210	guest have changed. The new capabilities are passed.
6211	<result name="VBOX_E_DONT_CALL_AGAIN">
6212	Do not call again, this method is a NOP.
6213	</result>
6214	</desc>
6215	<param name="supportsAbsolute" type="boolean" dir="in"/>
6216	<param name="supportsRelative" type="boolean" dir="in"/>
6217	<param name="needsHostCursor" type="boolean" dir="in"/>
6218	</method>
6219
6220	<method name="onKeyboardLedsChange">
6221	<desc>
6222	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
6223	to alter the state of the keyboard LEDs.
6224	<result name="VBOX_E_DONT_CALL_AGAIN">
6225	Do not call again, this method is a NOP.
6226	</result>
6227	</desc>
6228	<param name="numLock" type="boolean" dir="in"/>
6229	<param name="capsLock" type="boolean" dir="in"/>
6230	<param name="scrollLock" type="boolean" dir="in"/>
6231	</method>
6232
6233	<method name="onStateChange">
6234	<desc>
6235	Notification when the execution state of the machine has changed.
6236	The new state will be given.
6237	<result name="VBOX_E_DONT_CALL_AGAIN">
6238	Do not call again, this method is a NOP.
6239	</result>
6240	</desc>
6241	<param name="state" type="MachineState" dir="in"/>
6242	</method>
6243
6244	<method name="onAdditionsStateChange">
6245	<desc>
6246	Notification when a Guest Additions property changes.
6247	Interested callees should query IGuest attributes to
6248	find out what has changed.
6249	</desc>
6250	</method>
6251
6252	<method name="onNetworkAdapterChange">
6253	<desc>
6254	Notification when a property of one of the
6255	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
6256	changes. Interested callees should use INetworkAdapter methods and
6257	attributes to find out what has changed.
6258	<result name="VBOX_E_DONT_CALL_AGAIN">
6259	Do not call again, this method is a NOP.
6260	</result>
6261	</desc>
6262	<param name="networkAdapter" type="INetworkAdapter" dir="in">
6263	<desc>Network adapter that is subject to change.</desc>
6264	</param>
6265	</method>
6266
6267	<method name="onSerialPortChange">
6268	<desc>
6269	Notification when a property of one of the
6270	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
6271	Interested callees should use ISerialPort methods and attributes
6272	to find out what has changed.
6273	<result name="VBOX_E_DONT_CALL_AGAIN">
6274	Do not call again, this method is a NOP.
6275	</result>
6276	</desc>
6277	<param name="serialPort" type="ISerialPort" dir="in">
6278	<desc>Serial port that is subject to change.</desc>
6279	</param>
6280	</method>
6281
6282	<method name="onParallelPortChange">
6283	<desc>
6284	Notification when a property of one of the
6285	virtual <link to="IMachine::getParallelPort">parallel ports</link>
6286	changes. Interested callees should use ISerialPort methods and
6287	attributes to find out what has changed.
6288	<result name="VBOX_E_DONT_CALL_AGAIN">
6289	Do not call again, this method is a NOP.
6290	</result>
6291	</desc>
6292	<param name="parallelPort" type="IParallelPort" dir="in">
6293	<desc>Parallel port that is subject to change.</desc>
6294	</param>
6295	</method>
6296
6297	<method name="onStorageControllerChange">
6298	<desc>
6299	Notification when a property of one of the
6300	virtual <link to="IMachine::storageControllers">storage controllers</link>
6301	changes. Interested callees should query the corresponding collections
6302	to find out what has changed.
6303	<result name="VBOX_E_DONT_CALL_AGAIN">
6304	Do not call again, this method is a NOP.
6305	</result>
6306	</desc>
6307	</method>
6308
6309	<method name="onMediumChange">
6310	<desc>
6311	Notification when a
6312	<link to="IMachine::mediumAttachments">medium attachment</link>
6313	changes.
6314	<result name="VBOX_E_DONT_CALL_AGAIN">
6315	Do not call again, this method is a NOP.
6316	</result>
6317	</desc>
6318	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
6319	<desc>Medium attachment that is subject to change.</desc>
6320	</param>
6321	</method>
6322
6323	<method name="onCPUChange">
6324	<desc>
6325	Notification when a CPU changes.
6326	<result name="VBOX_E_DONT_CALL_AGAIN">
6327	Do not call again, this method is a NOP.
6328	</result>
6329	</desc>
6330	<param name="cpu" type="unsigned long" dir="in">
6331	<desc>The CPU which changed</desc>
6332	</param>
6333	<param name="add" type="boolean" dir="in">
6334	<desc>Flag whether the CPU was added or removed</desc>
6335	</param>
6336	</method>
6337
6338	<method name="onVRDPServerChange">
6339	<desc>
6340	Notification when a property of the
6341	<link to="IMachine::VRDPServer">VRDP server</link> changes.
6342	Interested callees should use IVRDPServer methods and attributes to
6343	find out what has changed.
6344	<result name="VBOX_E_DONT_CALL_AGAIN">
6345	Do not call again, this method is a NOP.
6346	</result>
6347	</desc>
6348	</method>
6349
6350	<method name="onRemoteDisplayInfoChange">
6351	<desc>
6352	Notification when the status of the VRDP server changes. Interested callees
6353	should use <link to="IConsole::RemoteDisplayInfo">IRemoteDisplayInfo</link>
6354	attributes to find out what is the current status.
6355	<result name="VBOX_E_DONT_CALL_AGAIN">
6356	Do not call again, this method is a NOP.
6357	</result>
6358	</desc>
6359	</method>
6360
6361	<method name="onUSBControllerChange">
6362	<desc>
6363	Notification when a property of the virtual
6364	<link to="IMachine::USBController">USB controller</link> changes.
6365	Interested callees should use IUSBController methods and attributes to
6366	find out what has changed.
6367	<result name="VBOX_E_DONT_CALL_AGAIN">
6368	Do not call again, this method is a NOP.
6369	</result>
6370	</desc>
6371	</method>
6372
6373	<method name="onUSBDeviceStateChange">
6374	<desc>
6375	Notification when a USB device is attached to or detached from
6376	the virtual USB controller.
6377
6378	This notification is sent as a result of the indirect
6379	request to attach the device because it matches one of the
6380	machine USB filters, or as a result of the direct request
6381	issued by <link to="IConsole::attachUSBDevice"/> or
6382	<link to="IConsole::detachUSBDevice"/>.
6383
6384	This notification is sent in case of both a succeeded and a
6385	failed request completion. When the request succeeds, the
6386	@a error parameter is @c null, and the given device has been
6387	already added to (when @a attached is @c true) or removed from
6388	(when @a attached is @c false) the collection represented by
6389	<link to="IConsole::USBDevices"/>. On failure, the collection
6390	doesn't change and the @a error parameter represents the error
6391	message describing the failure.
6392
6393	<result name="VBOX_E_DONT_CALL_AGAIN">
6394	Do not call again, this method is a NOP.
6395	</result>
6396	</desc>
6397	<param name="device" type="IUSBDevice" dir="in">
6398	<desc>Device that is subject to state change.</desc>
6399	</param>
6400	<param name="attached" type="boolean" dir="in">
6401	<desc>
6402	@c true if the device was attached and @c false otherwise.
6403	</desc>
6404	</param>
6405	<param name="error" type="IVirtualBoxErrorInfo" dir="in">
6406	<desc>
6407	@c null on success or an error message object on failure.
6408	</desc>
6409	</param>
6410	</method>
6411
6412	<method name="onSharedFolderChange">
6413	<desc>
6414	Notification when a shared folder is added or removed.
6415	The @a scope argument defines one of three scopes:
6416	<link to="IVirtualBox::sharedFolders">global shared folders</link>
6417	(<link to="Scope_Global">Global</link>),
6418	<link to="IMachine::sharedFolders">permanent shared folders</link> of
6419	the machine (<link to="Scope_Machine">Machine</link>) or <link
6420	to="IConsole::sharedFolders">transient shared folders</link> of the
6421	machine (<link to="Scope_Session">Session</link>). Interested callees
6422	should use query the corresponding collections to find out what has
6423	changed.
6424	<result name="VBOX_E_DONT_CALL_AGAIN">
6425	Do not call again, this method is a NOP.
6426	</result>
6427	</desc>
6428	<param name="scope" type="Scope" dir="in">
6429	<desc>Scope of the notification.</desc>
6430	</param>
6431	</method>
6432
6433	<method name="onRuntimeError">
6434	<desc>
6435	Notification when an error happens during the virtual
6436	machine execution.
6437
6438	There are three kinds of runtime errors:
6439	<ul>
6440	<li><i>fatal</i></li>
6441	<li><i>non-fatal with retry</i></li>
6442	<li><i>non-fatal warnings</i></li>
6443	</ul>
6444
6445	<b>Fatal</b> errors are indicated by the @a fatal parameter set
6446	to @c true. In case of fatal errors, the virtual machine
6447	execution is always paused before calling this notification, and
6448	the notification handler is supposed either to immediately save
6449	the virtual machine state using <link to="IConsole::saveState"/>
6450	or power it off using <link to="IConsole::powerDown"/>.
6451	Resuming the execution can lead to unpredictable results.
6452
6453	<b>Non-fatal</b> errors and warnings are indicated by the
6454	@a fatal parameter set to @c false. If the virtual machine
6455	is in the Paused state by the time the error notification is
6456	received, it means that the user can <i>try to resume</i> the machine
6457	execution after attempting to solve the problem that caused the
6458	error. In this case, the notification handler is supposed
6459	to show an appropriate message to the user (depending on the
6460	value of the @a id parameter) that offers several actions such
6461	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
6462	wants to retry, the notification handler should continue
6463	the machine execution using the <link to="IConsole::resume"/>
6464	call. If the machine execution is not Paused during this
6465	notification, then it means this notification is a <i>warning</i>
6466	(for example, about a fatal condition that can happen very soon);
6467	no immediate action is required from the user, the machine
6468	continues its normal execution.
6469
6470	Note that in either case the notification handler
6471	<b>must not</b> perform any action directly on a thread
6472	where this notification is called. Everything it is allowed to
6473	do is to post a message to another thread that will then talk
6474	to the user and take the corresponding action.
6475
6476	Currently, the following error identifiers are known:
6477	<ul>
6478	<li><tt>"HostMemoryLow"</tt></li>
6479	<li><tt>"HostAudioNotResponding"</tt></li>
6480	<li><tt>"VDIStorageFull"</tt></li>
6481	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
6482	</ul>
6483
6484	<note>
6485	This notification is not designed to be implemented by
6486	more than one callback at a time. If you have multiple
6487	IConsoleCallback instances registered on the given
6488	IConsole object, make sure you simply do nothing but
6489	return @c S_OK from all but one of them that does actual
6490	user notification and performs necessary actions.
6491	</note>
6492
6493	<result name="VBOX_E_DONT_CALL_AGAIN">
6494	Do not call again, this method is a NOP.
6495	</result>
6496	</desc>
6497	<param name="fatal" type="boolean" dir="in">
6498	<desc>Whether the error is fatal or not</desc>
6499	</param>
6500	<param name="id" type="wstring" dir="in">
6501	<desc>Error identifier</desc>
6502	</param>
6503	<param name="message" type="wstring" dir="in">
6504	<desc>Optional error message</desc>
6505	</param>
6506	</method>
6507
6508	<method name="onCanShowWindow">
6509	<desc>
6510	Notification when a call to
6511	<link to="IMachine::canShowConsoleWindow"/> is made by a
6512	front-end to check if a subsequent call to
6513	<link to="IMachine::showConsoleWindow"/> can succeed.
6514
6515	The callee should give an answer appropriate to the current
6516	machine state in the @a canShow argument. This answer must
6517	remain valid at least until the next
6518	<link to="IConsole::state">machine state</link> change.
6519
6520	<note>
6521	This notification is not designed to be implemented by
6522	more than one callback at a time. If you have multiple
6523	IConsoleCallback instances registered on the given
6524	IConsole object, make sure you simply do nothing but
6525	return @c true and @c S_OK from all but one of them that
6526	actually manages console window activation.
6527	</note>
6528
6529	<result name="VBOX_E_DONT_CALL_AGAIN">
6530	Do not call again, this method is a NOP.
6531	</result>
6532	</desc>
6533	<param name="canShow" type="boolean" dir="return">
6534	<desc>
6535	@c true if the console window can be shown and @c false otherwise.
6536	</desc>
6537	</param>
6538	</method>
6539
6540	<method name="onShowWindow">
6541	<desc>
6542	Notification when a call to
6543	<link to="IMachine::showConsoleWindow"/>
6544	requests the console window to be activated and brought to
6545	foreground on the desktop of the host PC.
6546
6547	This notification should cause the VM console process to
6548	perform the requested action as described above. If it is
6549	impossible to do it at a time of this notification, this
6550	method should return a failure.
6551
6552	Note that many modern window managers on many platforms
6553	implement some sort of focus stealing prevention logic, so
6554	that it may be impossible to activate a window without the
6555	help of the currently active application (which is supposedly
6556	an initiator of this notification). In this case, this method
6557	must return a non-zero identifier that represents the
6558	top-level window of the VM console process. The caller, if it
6559	represents a currently active process, is responsible to use
6560	this identifier (in a platform-dependent manner) to perform
6561	actual window activation.
6562
6563	This method must set @a winId to zero if it has performed all
6564	actions necessary to complete the request and the console
6565	window is now active and in foreground, to indicate that no
6566	further action is required on the caller's side.
6567
6568	<note>
6569	This notification is not designed to be implemented by
6570	more than one callback at a time. If you have multiple
6571	IConsoleCallback instances registered on the given
6572	IConsole object, make sure you simply do nothing but
6573	return @c S_OK from all but one of them that actually
6574	manages console window activation.
6575	</note>
6576
6577	<result name="VBOX_E_DONT_CALL_AGAIN">
6578	Do not call again, this method is a NOP.
6579	</result>
6580	</desc>
6581	<param name="winId" type="unsigned long long" dir="return">
6582	<desc>
6583	Platform-dependent identifier of the top-level VM console
6584	window, or zero if this method has performed all actions
6585	necessary to implement the <i>show window</i> semantics for
6586	the given platform and/or this VirtualBox front-end.
6587	</desc>
6588	</param>
6589	</method>
6590
6591	</interface>
6592
6593	<interface
6594	name="IRemoteDisplayInfo" extends="$unknown"
6595	uuid="b3741084-806f-4c3b-8c42-ebad1a81e45a"
6596	wsmap="struct"
6597	>
6598	<desc>
6599	Contains information about the remote display (VRDP) capabilities and status.
6600	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
6601	</desc>
6602
6603	<attribute name="active" type="boolean" readonly="yes">
6604	<desc>
6605	Whether the remote display connection is active.
6606	</desc>
6607	</attribute>
6608
6609	<attribute name="port" type="long" readonly="yes">
6610	<desc>
6611	VRDP server port number. If this property is equal to <tt>0</tt>, then
6612	the VRDP server failed to start, usually because there are no free TCP
6613	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDP
6614	server has not yet been started.
6615	</desc>
6616	</attribute>
6617
6618	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6619	<desc>
6620	How many times a client connected.
6621	</desc>
6622	</attribute>
6623
6624	<attribute name="beginTime" type="long long" readonly="yes">
6625	<desc>
6626	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6627	</desc>
6628	</attribute>
6629
6630	<attribute name="endTime" type="long long" readonly="yes">
6631	<desc>
6632	When the last connection was terminated or the current time, if
6633	connection is still active, in milliseconds since 1970-01-01 UTC.
6634	</desc>
6635	</attribute>
6636
6637	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
6638	<desc>
6639	How many bytes were sent in last or current, if still active, connection.
6640	</desc>
6641	</attribute>
6642
6643	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
6644	<desc>
6645	How many bytes were sent in all connections.
6646	</desc>
6647	</attribute>
6648
6649	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
6650	<desc>
6651	How many bytes were received in last or current, if still active, connection.
6652	</desc>
6653	</attribute>
6654
6655	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
6656	<desc>
6657	How many bytes were received in all connections.
6658	</desc>
6659	</attribute>
6660
6661	<attribute name="user" type="wstring" readonly="yes">
6662	<desc>
6663	Login user name supplied by the client.
6664	</desc>
6665	</attribute>
6666
6667	<attribute name="domain" type="wstring" readonly="yes">
6668	<desc>
6669	Login domain name supplied by the client.
6670	</desc>
6671	</attribute>
6672
6673	<attribute name="clientName" type="wstring" readonly="yes">
6674	<desc>
6675	The client name supplied by the client.
6676	</desc>
6677	</attribute>
6678
6679	<attribute name="clientIP" type="wstring" readonly="yes">
6680	<desc>
6681	The IP address of the client.
6682	</desc>
6683	</attribute>
6684
6685	<attribute name="clientVersion" type="unsigned long" readonly="yes">
6686	<desc>
6687	The client software version number.
6688	</desc>
6689	</attribute>
6690
6691	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
6692	<desc>
6693	Public key exchange method used when connection was established.
6694	Values: 0 - RDP4 public key exchange scheme.
6695	1 - X509 certificates were sent to client.
6696	</desc>
6697	</attribute>
6698
6699	</interface>
6700
6701	<interface
6702	name="IConsole" extends="$unknown"
6703	uuid="6375231a-c17c-464b-92cb-ae9e128d71c3"
6704	wsmap="managed"
6705	>
6706	<desc>
6707	The IConsole interface represents an interface to control virtual
6708	machine execution.
6709
6710	The console object that implements the IConsole interface is obtained
6711	from a session object after the session for the given machine has been
6712	opened using one of <link to="IVirtualBox::openSession"/>,
6713	<link to="IVirtualBox::openRemoteSession"/> or
6714	<link to="IVirtualBox::openExistingSession"/> methods.
6715
6716	Methods of the IConsole interface allow the caller to query the current
6717	virtual machine execution state, pause the machine or power it down, save
6718	the machine state or take a snapshot, attach and detach removable media
6719	and so on.
6720
6721	<see>ISession</see>
6722	</desc>
6723
6724	<attribute name="machine" type="IMachine" readonly="yes">
6725	<desc>
6726	Machine object this console is sessioned with.
6727	<note>
6728	This is a convenience property, it has the same value as
6729	<link to="ISession::machine"/> of the corresponding session
6730	object.
6731	</note>
6732	</desc>
6733	</attribute>
6734
6735	<attribute name="state" type="MachineState" readonly="yes">
6736	<desc>
6737	Current execution state of the machine.
6738	<note>
6739	This property always returns the same value as the corresponding
6740	property of the IMachine object this console is sessioned with.
6741	For the process that owns (executes) the VM, this is the
6742	preferable way of querying the VM state, because no IPC
6743	calls are made.
6744	</note>
6745	</desc>
6746	</attribute>
6747
6748	<attribute name="guest" type="IGuest" readonly="yes">
6749	<desc>Guest object.</desc>
6750	</attribute>
6751
6752	<attribute name="keyboard" type="IKeyboard" readonly="yes">
6753	<desc>
6754	Virtual keyboard object.
6755	<note>
6756	If the machine is not running, any attempt to use
6757	the returned object will result in an error.
6758	</note>
6759	</desc>
6760	</attribute>
6761
6762	<attribute name="mouse" type="IMouse" readonly="yes">
6763	<desc>
6764	Virtual mouse object.
6765	<note>
6766	If the machine is not running, any attempt to use
6767	the returned object will result in an error.
6768	</note>
6769	</desc>
6770	</attribute>
6771
6772	<attribute name="display" type="IDisplay" readonly="yes">
6773	<desc>Virtual display object.
6774	<note>
6775	If the machine is not running, any attempt to use
6776	the returned object will result in an error.
6777	</note>
6778	</desc>
6779	</attribute>
6780
6781	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
6782	<desc>Debugging interface.</desc>
6783	</attribute>
6784
6785	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6786	<desc>
6787	Collection of USB devices currently attached to the virtual
6788	USB controller.
6789	<note>
6790	The collection is empty if the machine is not running.
6791	</note>
6792	</desc>
6793	</attribute>
6794
6795	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6796	<desc>
6797	List of USB devices currently attached to the remote VRDP client.
6798	Once a new device is physically attached to the remote host computer,
6799	it appears in this list and remains there until detached.
6800	</desc>
6801	</attribute>
6802
6803	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6804	<desc>
6805	Collection of shared folders for the current session. These folders
6806	are called transient shared folders because they are available to the
6807	guest OS running inside the associated virtual machine only for the
6808	duration of the session (as opposed to
6809	<link to="IMachine::sharedFolders"/> which represent permanent shared
6810	folders). When the session is closed (e.g. the machine is powered down),
6811	these folders are automatically discarded.
6812
6813	New shared folders are added to the collection using
6814	<link to="#createSharedFolder"/>. Existing shared folders can be
6815	removed using <link to="#removeSharedFolder"/>.
6816	</desc>
6817	</attribute>
6818
6819	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
6820	<desc>
6821	Interface that provides information on Remote Display (VRDP) connection.
6822	</desc>
6823	</attribute>
6824
6825	<method name="powerUp">
6826	<desc>
6827	Starts the virtual machine execution using the current machine
6828	state (that is, its current execution state, current settings and
6829	current storage devices).
6830
6831	If the machine is powered off or aborted, the execution will
6832	start from the beginning (as if the real hardware were just
6833	powered on).
6834
6835	If the machine is in the <link to="MachineState_Saved"/> state,
6836	it will continue its execution the point where the state has
6837	been saved.
6838
6839	<note>
6840	Unless you are trying to write a new VirtualBox front-end that
6841	performs direct machine execution (like the VirtualBox or VBoxSDL
6842	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
6843	session opened by <link to="IVirtualBox::openSession"/> and use this
6844	session only to change virtual machine settings. If you simply want to
6845	start virtual machine execution using one of the existing front-ends
6846	(for example the VirtualBox GUI or headless server), simply use
6847	<link to="IVirtualBox::openRemoteSession"/>; these front-ends will
6848	power up the machine automatically for you.
6849	</note>
6850
6851	<see>#saveState</see>
6852	<result name="VBOX_E_INVALID_VM_STATE">
6853	Virtual machine already running.
6854	</result>
6855	<result name="VBOX_E_HOST_ERROR">
6856	Host interface does not exist or name not set.
6857	</result>
6858	<result name="VBOX_E_FILE_ERROR">
6859	Invalid saved state file.
6860	</result>
6861	</desc>
6862	<param name="progress" type="IProgress" dir="return">
6863	<desc>Progress object to track the operation completion.</desc>
6864	</param>
6865	</method>
6866
6867	<method name="powerUpPaused">
6868	<desc>
6869	Identical to powerUp except that the VM will enter the
6870	<link to="MachineState_Paused"/> state, instead of
6871	<link to="MachineState_Running"/>.
6872
6873	<see>#powerUp</see>
6874	<result name="VBOX_E_INVALID_VM_STATE">
6875	Virtual machine already running.
6876	</result>
6877	<result name="VBOX_E_HOST_ERROR">
6878	Host interface does not exist or name not set.
6879	</result>
6880	<result name="VBOX_E_FILE_ERROR">
6881	Invalid saved state file.
6882	</result>
6883	</desc>
6884	<param name="progress" type="IProgress" dir="return">
6885	<desc>Progress object to track the operation completion.</desc>
6886	</param>
6887	</method>
6888
6889	<method name="powerDown">
6890	<desc>
6891	Initiates the power down procedure to stop the virtual machine
6892	execution.
6893
6894	The completion of the power down procedure is tracked using the returned
6895	IProgress object. After the operation is complete, the machine will go
6896	to the PoweredOff state.
6897	<result name="VBOX_E_INVALID_VM_STATE">
6898	Virtual machine must be Running, Paused or Stuck to be powered down.
6899	</result>
6900	</desc>
6901	<param name="progress" type="IProgress" dir="return">
6902	<desc>Progress object to track the operation completion.</desc>
6903	</param>
6904	</method>
6905
6906	<method name="reset">
6907	<desc>Resets the virtual machine.
6908	<result name="VBOX_E_INVALID_VM_STATE">
6909	Virtual machine not in Running state.
6910	</result>
6911	<result name="VBOX_E_VM_ERROR">
6912	Virtual machine error in reset operation.
6913	</result>
6914	</desc>
6915	</method>
6916
6917	<method name="pause">
6918	<desc>Pauses the virtual machine execution.
6919	<result name="VBOX_E_INVALID_VM_STATE">
6920	Virtual machine not in Running state.
6921	</result>
6922	<result name="VBOX_E_VM_ERROR">
6923	Virtual machine error in suspend operation.
6924	</result>
6925	</desc>
6926	</method>
6927
6928	<method name="resume">
6929	<desc>Resumes the virtual machine execution.
6930	<result name="VBOX_E_INVALID_VM_STATE">
6931	Virtual machine not in Paused state.
6932	</result>
6933	<result name="VBOX_E_VM_ERROR">
6934	Virtual machine error in resume operation.
6935	</result>
6936	</desc>
6937	</method>
6938
6939	<method name="powerButton">
6940	<desc>Sends the ACPI power button event to the guest.
6941	<result name="VBOX_E_INVALID_VM_STATE">
6942	Virtual machine not in Running state.
6943	</result>
6944	<result name="VBOX_E_PDM_ERROR">
6945	Controlled power off failed.
6946	</result>
6947	</desc>
6948	</method>
6949
6950	<method name="sleepButton">
6951	<desc>Sends the ACPI sleep button event to the guest.
6952	<result name="VBOX_E_INVALID_VM_STATE">
6953	Virtual machine not in Running state.
6954	</result>
6955	<result name="VBOX_E_PDM_ERROR">
6956	Sending sleep button event failed.
6957	</result>
6958	</desc>
6959	</method>
6960
6961	<method name="getPowerButtonHandled">
6962	<desc>Checks if the last power button event was handled by guest.
6963	<result name="VBOX_E_PDM_ERROR">
6964	Checking if the event was handled by the guest OS failed.
6965	</result>
6966	</desc>
6967	<param name="handled" type="boolean" dir="return"/>
6968	</method>
6969
6970	<method name="getGuestEnteredACPIMode">
6971	<desc>Checks if the guest entered the ACPI mode G0 (working) or
6972	G1 (sleeping). If this method returns @c false, the guest will
6973	most likely not respond to external ACPI events.
6974	<result name="VBOX_E_INVALID_VM_STATE">
6975	Virtual machine not in Running state.
6976	</result>
6977	</desc>
6978	<param name="entered" type="boolean" dir="return"/>
6979	</method>
6980
6981	<method name="saveState">
6982	<desc>
6983	Saves the current execution state of a running virtual machine
6984	and stops its execution.
6985
6986	After this operation completes, the machine will go to the
6987	Saved state. Next time it is powered up, this state will
6988	be restored and the machine will continue its execution from
6989	the place where it was saved.
6990
6991	This operation differs from taking a snapshot to the effect
6992	that it doesn't create new differencing media. Also, once
6993	the machine is powered up from the state saved using this method,
6994	the saved state is deleted, so it will be impossible to return
6995	to this state later.
6996
6997	<note>
6998	On success, this method implicitly calls
6999	<link to="IMachine::saveSettings"/> to save all current machine
7000	settings (including runtime changes to the DVD medium, etc.).
7001	Together with the impossibility to change any VM settings when it is
7002	in the Saved state, this guarantees adequate hardware
7003	configuration of the machine when it is restored from the saved
7004	state file.
7005	</note>
7006
7007	<note>
7008	The machine must be in the Running or Paused state, otherwise
7009	the operation will fail.
7010	</note>
7011	<result name="VBOX_E_INVALID_VM_STATE">
7012	Virtual machine state neither Running nor Paused.
7013	</result>
7014	<result name="VBOX_E_FILE_ERROR">
7015	Failed to create directory for saved state file.
7016	</result>
7017
7018	<see><link to="#takeSnapshot"/></see>
7019	</desc>
7020	<param name="progress" type="IProgress" dir="return">
7021	<desc>Progress object to track the operation completion.</desc>
7022	</param>
7023	</method>
7024
7025	<method name="adoptSavedState">
7026	<desc>
7027	Associates the given saved state file to the virtual machine.
7028
7029	On success, the machine will go to the Saved state. Next time it is
7030	powered up, it will be restored from the adopted saved state and
7031	continue execution from the place where the saved state file was
7032	created.
7033
7034	The specified saved state file path may be absolute or relative to the
7035	folder the VM normally saves the state to (usually,
7036	<link to="IMachine::snapshotFolder"/>).
7037
7038	<note>
7039	It's a caller's responsibility to make sure the given saved state
7040	file is compatible with the settings of this virtual machine that
7041	represent its virtual hardware (memory size, storage disk configuration
7042	etc.). If there is a mismatch, the behavior of the virtual machine
7043	is undefined.
7044	</note>
7045	<result name="VBOX_E_INVALID_VM_STATE">
7046	Virtual machine state neither PoweredOff nor Aborted.
7047	</result>
7048	</desc>
7049	<param name="savedStateFile" type="wstring" dir="in">
7050	<desc>Path to the saved state file to adopt.</desc>
7051	</param>
7052	</method>
7053
7054	<method name="forgetSavedState">
7055	<desc>
7056	Forgets the saved state of the virtual machine previously created
7057	by <link to="#saveState"/>. Next time the machine is powered up, a
7058	clean boot will occur. If @a remove is @c true the saved state file
7059	is deleted.
7060	<note>
7061	This operation is equivalent to resetting or powering off
7062	the machine without doing a proper shutdown in the guest OS.
7063	</note>
7064	<result name="VBOX_E_INVALID_VM_STATE">
7065	Virtual machine not in state Saved.
7066	</result>
7067	</desc>
7068	<param name="remove" type="boolean" dir="in">
7069	<desc>If @c true remove the saved state file.</desc>
7070	</param>
7071	</method>
7072
7073	<method name="getDeviceActivity">
7074	<desc>
7075	Gets the current activity type of a given device or device group.
7076	<result name="E_INVALIDARG">
7077	Invalid device type.
7078	</result>
7079	</desc>
7080	<param name="type" type="DeviceType" dir="in"/>
7081	<param name="activity" type="DeviceActivity" dir="return"/>
7082	</method>
7083
7084	<method name="attachUSBDevice">
7085	<desc>
7086	Attaches a host USB device with the given UUID to the
7087	USB controller of the virtual machine.
7088
7089	The device needs to be in one of the following states:
7090	<link to="USBDeviceState_Busy"/>,
7091	<link to="USBDeviceState_Available"/> or
7092	<link to="USBDeviceState_Held"/>,
7093	otherwise an error is immediately returned.
7094
7095	When the device state is
7096	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7097	be returned if the host computer refuses to release it for some reason.
7098
7099	<see>IUSBController::deviceFilters, USBDeviceState</see>
7100	<result name="VBOX_E_INVALID_VM_STATE">
7101	Virtual machine state neither Running nor Paused.
7102	</result>
7103	<result name="VBOX_E_PDM_ERROR">
7104	Virtual machine does not have a USB controller.
7105	</result>
7106	</desc>
7107	<param name="id" type="uuid" mod="string" dir="in">
7108	<desc>UUID of the host USB device to attach.</desc>
7109	</param>
7110	</method>
7111
7112	<method name="detachUSBDevice">
7113	<desc>
7114	Detaches an USB device with the given UUID from the USB controller
7115	of the virtual machine.
7116
7117	After this method succeeds, the VirtualBox server re-initiates
7118	all USB filters as if the device were just physically attached
7119	to the host, but filters of this machine are ignored to avoid
7120	a possible automatic re-attachment.
7121
7122	<see>IUSBController::deviceFilters, USBDeviceState</see>
7123
7124	<result name="VBOX_E_PDM_ERROR">
7125	Virtual machine does not have a USB controller.
7126	</result>
7127	<result name="E_INVALIDARG">
7128	USB device not attached to this virtual machine.
7129	</result>
7130	</desc>
7131	<param name="id" type="uuid" mod="string" dir="in">
7132	<desc>UUID of the USB device to detach.</desc>
7133	</param>
7134	<param name="device" type="IUSBDevice" dir="return">
7135	<desc>Detached USB device.</desc>
7136	</param>
7137	</method>
7138
7139	<method name="findUSBDeviceByAddress">
7140	<desc>
7141	Searches for a USB device with the given host address.
7142
7143	<result name="VBOX_E_OBJECT_NOT_FOUND">
7144	Given @c name does not correspond to any USB device.
7145	</result>
7146
7147	<see>IUSBDevice::address</see>
7148	</desc>
7149	<param name="name" type="wstring" dir="in">
7150	<desc>
7151	Address of the USB device (as assigned by the host) to
7152	search for.
7153	</desc>
7154	</param>
7155	<param name="device" type="IUSBDevice" dir="return">
7156	<desc>Found USB device object.</desc>
7157	</param>
7158	</method>
7159
7160	<method name="findUSBDeviceById">
7161	<desc>
7162	Searches for a USB device with the given UUID.
7163
7164	<result name="VBOX_E_OBJECT_NOT_FOUND">
7165	Given @c id does not correspond to any USB device.
7166	</result>
7167
7168	<see>IUSBDevice::id</see>
7169	</desc>
7170	<param name="id" type="uuid" mod="string" dir="in">
7171	<desc>UUID of the USB device to search for.</desc>
7172	</param>
7173	<param name="device" type="IUSBDevice" dir="return">
7174	<desc>Found USB device object.</desc>
7175	</param>
7176	</method>
7177
7178	<method name="createSharedFolder">
7179	<desc>
7180	Creates a transient new shared folder by associating the given logical
7181	name with the given host path, adds it to the collection of shared
7182	folders and starts sharing it. Refer to the description of
7183	<link to="ISharedFolder"/> to read more about logical names.
7184
7185	<result name="VBOX_E_INVALID_VM_STATE">
7186	Virtual machine in Saved state or currently changing state.
7187	</result>
7188	<result name="VBOX_E_FILE_ERROR">
7189	Shared folder already exists or not accessible.
7190	</result>
7191	</desc>
7192	<param name="name" type="wstring" dir="in">
7193	<desc>Unique logical name of the shared folder.</desc>
7194	</param>
7195	<param name="hostPath" type="wstring" dir="in">
7196	<desc>Full path to the shared folder in the host file system.</desc>
7197	</param>
7198	<param name="writable" type="boolean" dir="in">
7199	<desc>Whether the share is writable or readonly</desc>
7200	</param>
7201	</method>
7202
7203	<method name="removeSharedFolder">
7204	<desc>
7205	Removes a transient shared folder with the given name previously
7206	created by <link to="#createSharedFolder"/> from the collection of
7207	shared folders and stops sharing it.
7208	<result name="VBOX_E_INVALID_VM_STATE">
7209	Virtual machine in Saved state or currently changing state.
7210	</result>
7211	<result name="VBOX_E_FILE_ERROR">
7212	Shared folder does not exists.
7213	</result>
7214	</desc>
7215	<param name="name" type="wstring" dir="in">
7216	<desc>Logical name of the shared folder to remove.</desc>
7217	</param>
7218	</method>
7219
7220	<method name="takeSnapshot">
7221	<desc>
7222	Saves the current execution state
7223	and all settings of the machine and creates differencing images
7224	for all normal (non-independent) media.
7225	See <link to="ISnapshot" /> for an introduction to snapshots.
7226
7227	This method can be called for a PoweredOff, Saved (see
7228	<link to="#saveState"/>), Running or
7229	Paused virtual machine. When the machine is PoweredOff, an
7230	offline snapshot is created. When the machine is Running a live
7231	snapshot is created, and an online snapshot is is created when Paused.
7232
7233	The taken snapshot is always based on the
7234	<link to="IMachine::currentSnapshot">current snapshot</link>
7235	of the associated virtual machine and becomes a new current snapshot.
7236
7237	<note>
7238	This method implicitly calls <link to="IMachine::saveSettings"/> to
7239	save all current machine settings before taking an offline snapshot.
7240	</note>
7241
7242	<result name="VBOX_E_INVALID_VM_STATE">
7243	Virtual machine currently changing state.
7244	</result>
7245	</desc>
7246	<param name="name" type="wstring" dir="in">
7247	<desc>Short name for the snapshot.</desc>
7248	</param>
7249	<param name="description" type="wstring" dir="in">
7250	<desc>Optional description of the snapshot.</desc>
7251	</param>
7252	<param name="progress" type="IProgress" dir="return">
7253	<desc>Progress object to track the operation completion.</desc>
7254	</param>
7255	</method>
7256
7257	<method name="deleteSnapshot">
7258	<desc>
7259	Starts deleting the specified snapshot asynchronously.
7260	See <link to="ISnapshot" /> for an introduction to snapshots.
7261
7262	The execution state and settings of the associated machine stored in
7263	the snapshot will be deleted. The contents of all differencing media of
7264	this snapshot will be merged with the contents of their dependent child
7265	media to keep the medium chain valid (in other words, all changes
7266	represented by media being deleted will be propagated to their child
7267	medium). After that, this snapshot's differencing medium will be
7268	deleted. The parent of this snapshot will become a new parent for all
7269	its child snapshots.
7270
7271	If the deleted snapshot is the current one, its parent snapshot will
7272	become a new current snapshot. The current machine state is not directly
7273	affected in this case, except that currently attached differencing
7274	media based on media of the deleted snapshot will be also merged as
7275	described above.
7276
7277	If the deleted snapshot is the first or current snapshot, then the
7278	respective IMachine attributes will be adjusted. Deleting the current
7279	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7280	to make all current machine settings permanent.
7281
7282	Deleting a snapshot has the following preconditions:
7283
7284	<ul>
7285	<li>Child media of all normal media of the deleted snapshot
7286	must be accessible (see <link to="IMedium::state"/>) for this
7287	operation to succeed. In particular, this means that all virtual
7288	machines, whose media are directly or indirectly based on the
7289	media of deleted snapshot, must be powered off.</li>
7290
7291	<li>You cannot delete the snapshot if a medium attached to it has
7292	more than once child medium (differencing images) because otherwise
7293	merging would be impossible. This might be the case if there is
7294	more than one child snapshot or differencing images were created
7295	for other reason (e.g. implicitly because of multiple machine
7296	attachments).</li>
7297	</ul>
7298
7299
7300	The virtual machine's <link to="IMachine::state">state</link> is changed to "DeletingSnapshot"
7301	while this operation is in progress.
7302
7303	<note>
7304	Merging medium contents can be very time and disk space
7305	consuming, if these media are big in size and have many
7306	children. However, if the snapshot being deleted is the last
7307	(head) snapshot on the branch, the operation will be rather
7308	quick.
7309	</note>
7310	<result name="VBOX_E_INVALID_VM_STATE">
7311	Virtual machine is running.
7312	</result>
7313	</desc>
7314	<param name="id" type="uuid" mod="string" dir="in">
7315	<desc>UUID of the snapshot to delete.</desc>
7316	</param>
7317	<param name="progress" type="IProgress" dir="return">
7318	<desc>Progress object to track the operation completion.</desc>
7319	</param>
7320	</method>
7321
7322	<method name="restoreSnapshot">
7323	<desc>
7324	Starts resetting the machine's current state to the state contained
7325	in the given snapshot, asynchronously. All current settings of the
7326	machine will be reset and changes stored in differencing media
7327	will be lost.
7328	See <link to="ISnapshot" /> for an introduction to snapshots.
7329
7330	After this operation is successfully completed, new empty differencing
7331	media are created for all normal media of the machine.
7332
7333	If the given snapshot is an online snapshot, the machine will go to
7334	the <link to="MachineState_Saved"> saved state</link>, so that the
7335	next time it is powered on, the execution state will be restored
7336	from the state of the snapshot.
7337
7338	<note>
7339	The machine must not be running, otherwise the operation will fail.
7340	</note>
7341
7342	<note>
7343	If the machine state is <link to="MachineState_Saved">Saved</link>
7344	prior to this operation, the saved state file will be implicitly
7345	deleted (as if <link to="IConsole::forgetSavedState"/> were
7346	called).
7347	</note>
7348
7349	<result name="VBOX_E_INVALID_VM_STATE">
7350	Virtual machine is running.
7351	</result>
7352	</desc>
7353	<param name="snapshot" type="ISnapshot" dir="in">
7354	<desc>The snapshot to restore the VM state from.</desc>
7355	</param>
7356	<param name="progress" type="IProgress" dir="return">
7357	<desc>Progress object to track the operation completion.</desc>
7358	</param>
7359	</method>
7360
7361	<method name="teleport">
7362	<desc>
7363	Teleport the VM to a different host machine or process.
7364
7365	TODO explain the details.
7366
7367	<result name="VBOX_E_INVALID_VM_STATE">
7368	Virtual machine not running or paused.
7369	</result>
7370	</desc>
7371	<param name="hostname" type="wstring" dir="in">
7372	<desc>The name or IP of the host to teleport to.</desc>
7373	</param>
7374	<param name="tcpport" type="unsigned long" dir="in">
7375	<desc>The TCP port to connect to (1..65535).</desc>
7376	</param>
7377	<param name="password" type="wstring" dir="in">
7378	<desc>The password.</desc>
7379	</param>
7380	<param name="maxDowntime" type="unsigned long" dir="in">
7381	<desc>
7382	The maximum allowed downtime given as milliseconds. 0 is not a valid
7383	value. Recommended value: 250 ms.
7384
7385	The higher the value is, the greater the chance for a successful
7386	teleportation. A small value may easily result in the teleportation
7387	process taking hours and eventually fail.
7388
7389	<note>
7390	The current implementation treats this a guideline, not as an
7391	absolute rule.
7392	</note>
7393	</desc>
7394	</param>
7395	<param name="progress" type="IProgress" dir="return">
7396	<desc>Progress object to track the operation completion.</desc>
7397	</param>
7398	</method>
7399
7400	<method name="registerCallback">
7401	<desc>
7402	Registers a new console callback on this instance. The methods of the
7403	callback interface will be called by this instance when the appropriate
7404	event occurs.
7405	</desc>
7406	<param name="callback" type="IConsoleCallback" dir="in"/>
7407	</method>
7408
7409	<method name="unregisterCallback">
7410	<desc>
7411	Unregisters the console callback previously registered using
7412	<link to="#registerCallback"/>.
7413	<result name="E_INVALIDARG">
7414	Given @a callback handler is not registered.
7415	</result>
7416	</desc>
7417	<param name="callback" type="IConsoleCallback" dir="in"/>
7418	</method>
7419	</interface>
7420
7421	<!--
7422	// IHost
7423	/////////////////////////////////////////////////////////////////////////
7424	-->
7425
7426	<enum
7427	name="HostNetworkInterfaceMediumType"
7428	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7429	>
7430	<desc>
7431	Type of encapsulation. Ethernet encapsulation includes both wired and
7432	wireless Ethernet connections.
7433	<see>IHostNetworkInterface</see>
7434	</desc>
7435
7436	<const name="Unknown" value="0">
7437	<desc>
7438	The type of interface cannot be determined.
7439	</desc>
7440	</const>
7441	<const name="Ethernet" value="1">
7442	<desc>
7443	Ethernet frame encapsulation.
7444	</desc>
7445	</const>
7446	<const name="PPP" value="2">
7447	<desc>
7448	Point-to-point protocol encapsulation.
7449	</desc>
7450	</const>
7451	<const name="SLIP" value="3">
7452	<desc>
7453	Serial line IP encapsulation.
7454	</desc>
7455	</const>
7456	</enum>
7457
7458	<enum
7459	name="HostNetworkInterfaceStatus"
7460	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7461	>
7462	<desc>
7463	Current status of the interface.
7464	<see>IHostNetworkInterface</see>
7465	</desc>
7466
7467	<const name="Unknown" value="0">
7468	<desc>
7469	The state of interface cannot be determined.
7470	</desc>
7471	</const>
7472	<const name="Up" value="1">
7473	<desc>
7474	The interface is fully operational.
7475	</desc>
7476	</const>
7477	<const name="Down" value="2">
7478	<desc>
7479	The interface is not functioning.
7480	</desc>
7481	</const>
7482	</enum>
7483
7484	<enum
7485	name="HostNetworkInterfaceType"
7486	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7487	>
7488	<desc>
7489	Network interface type.
7490	</desc>
7491	<const name="Bridged" value="1"/>
7492	<const name="HostOnly" value="2"/>
7493	</enum>
7494
7495	<interface
7496	name="IHostNetworkInterface" extends="$unknown"
7497	uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
7498	wsmap="managed"
7499	>
7500	<desc>
7501	Represents one of host's network interfaces. IP V6 address and network
7502	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7503	separated by colons.
7504	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7505	</desc>
7506	<attribute name="name" type="wstring" readonly="yes">
7507	<desc>Returns the host network interface name.</desc>
7508	</attribute>
7509
7510	<attribute name="id" type="uuid" mod="string" readonly="yes">
7511	<desc>Returns the interface UUID.</desc>
7512	</attribute>
7513
7514	<attribute name="networkName" type="wstring" readonly="yes">
7515	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7516	</attribute>
7517
7518	<attribute name="dhcpEnabled" type="boolean" readonly="yes">
7519	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7520	</attribute>
7521
7522	<attribute name="IPAddress" type="wstring" readonly="yes">
7523	<desc>Returns the IP V4 address of the interface.</desc>
7524	</attribute>
7525
7526	<attribute name="networkMask" type="wstring" readonly="yes">
7527	<desc>Returns the network mask of the interface.</desc>
7528	</attribute>
7529
7530	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7531	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7532	</attribute>
7533
7534	<attribute name="IPV6Address" type="wstring" readonly="yes">
7535	<desc>Returns the IP V6 address of the interface.</desc>
7536	</attribute>
7537
7538	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7539	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7540	</attribute>
7541
7542	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7543	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7544	</attribute>
7545
7546	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7547	<desc>Type of protocol encapsulation used.</desc>
7548	</attribute>
7549
7550	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7551	<desc>Status of the interface.</desc>
7552	</attribute>
7553
7554	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7555	<desc>specifies the host interface type.</desc>
7556	</attribute>
7557
7558	<method name="enableStaticIpConfig">
7559	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7560	<param name="IPAddress" type="wstring" dir="in">
7561	<desc>
7562	IP address.
7563	</desc>
7564	</param>
7565	<param name="networkMask" type="wstring" dir="in">
7566	<desc>
7567	network mask.
7568	</desc>
7569	</param>
7570	</method>
7571
7572	<method name="enableStaticIpConfigV6">
7573	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7574	<param name="IPV6Address" type="wstring" dir="in">
7575	<desc>
7576	IP address.
7577	</desc>
7578	</param>
7579	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7580	<desc>
7581	network mask.
7582	</desc>
7583	</param>
7584	</method>
7585
7586	<method name="enableDynamicIpConfig">
7587	<desc>enables the dynamic IP configuration.</desc>
7588	</method>
7589
7590	<method name="dhcpRediscover">
7591	<desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
7592	</method>
7593
7594	</interface>
7595
7596	<interface
7597	name="IHost" extends="$unknown"
7598	uuid="e380cbfc-ae65-4fa6-899e-45ded6b3132a"
7599	wsmap="managed"
7600	>
7601	<desc>
7602	The IHost interface represents the physical machine that this VirtualBox
7603	installation runs on.
7604
7605	An object implementing this interface is returned by the
7606	<link to="IVirtualBox::host" /> attribute. This interface contains
7607	read-only information about the host's physical hardware (such as what
7608	processors and disks are available, what the host operating system is,
7609	and so on) and also allows for manipulating some of the host's hardware,
7610	such as global USB device filters and host interface networking.
7611
7612	</desc>
7613	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
7614	<desc>List of DVD drives available on the host.</desc>
7615	</attribute>
7616
7617	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
7618	<desc>List of floppy drives available on the host.</desc>
7619	</attribute>
7620
7621	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7622	<desc>
7623	List of USB devices currently attached to the host.
7624	Once a new device is physically attached to the host computer,
7625	it appears in this list and remains there until detached.
7626
7627	<note>
7628	If USB functionality is not available in the given edition of
7629	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7630	</note>
7631	</desc>
7632	</attribute>
7633
7634	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
7635	<desc>
7636	List of USB device filters in action.
7637	When a new device is physically attached to the host computer,
7638	filters from this list are applied to it (in order they are stored
7639	in the list). The first matched filter will determine the
7640	<link to="IHostUSBDeviceFilter::action">action</link>
7641	performed on the device.
7642
7643	Unless the device is ignored by these filters, filters of all
7644	currently running virtual machines
7645	(<link to="IUSBController::deviceFilters"/>) are applied to it.
7646
7647	<note>
7648	If USB functionality is not available in the given edition of
7649	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7650	</note>
7651
7652	<see>IHostUSBDeviceFilter, USBDeviceState</see>
7653	</desc>
7654	</attribute>
7655
7656	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
7657	<desc>List of host network interfaces currently defined on the host.</desc>
7658	</attribute>
7659
7660	<attribute name="processorCount" type="unsigned long" readonly="yes">
7661	<desc>Number of (logical) CPUs installed in the host system.</desc>
7662	</attribute>
7663
7664	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
7665	<desc>Number of (logical) CPUs online in the host system.</desc>
7666	</attribute>
7667
7668	<method name="getProcessorSpeed">
7669	<desc>Query the (approximate) maximum speed of a specified host CPU in
7670	Megahertz.
7671	</desc>
7672	<param name="cpuId" type="unsigned long" dir="in">
7673	<desc>
7674	Identifier of the CPU.
7675	</desc>
7676	</param>
7677	<param name="speed" type="unsigned long" dir="return">
7678	<desc>
7679	Speed value. 0 is returned if value is not known or @a cpuId is
7680	invalid.
7681	</desc>
7682	</param>
7683	</method>
7684
7685	<method name="getProcessorFeature">
7686	<desc>Query whether a CPU feature is supported or not.</desc>
7687	<param name="feature" type="ProcessorFeature" dir="in">
7688	<desc>
7689	CPU Feature identifier.
7690	</desc>
7691	</param>
7692	<param name="supported" type="boolean" dir="return">
7693	<desc>
7694	Feature is supported or not.
7695	</desc>
7696	</param>
7697	</method>
7698
7699	<method name="getProcessorDescription">
7700	<desc>Query the model string of a specified host CPU.
7701	</desc>
7702	<param name="cpuId" type="unsigned long" dir="in">
7703	<desc>
7704	Identifier of the CPU.
7705	<note>
7706	The current implementation might not necessarily return the
7707	description for this exact CPU.
7708	</note>
7709	</desc>
7710	</param>
7711	<param name="description" type="wstring" dir="return">
7712	<desc>
7713	Model string. An empty string is returned if value is not known or
7714	@a cpuId is invalid.
7715	</desc>
7716	</param>
7717	</method>
7718
7719	<method name="getProcessorCPUIDLeaf">
7720	<desc>
7721	Returns the CPU cpuid information for the specified leaf.
7722	</desc>
7723	<param name="cpuId" type="unsigned long" dir="in">
7724	<desc>
7725	Identifier of the CPU. The CPU most be online.
7726	<note>
7727	The current implementation might not necessarily return the
7728	description for this exact CPU.
7729	</note>
7730	</desc>
7731	</param>
7732	<param name="leaf" type="unsigned long" dir="in">
7733	<desc>
7734	CPUID leaf index (eax).
7735	</desc>
7736	</param>
7737	<param name="subLeaf" type="unsigned long" dir="in">
7738	<desc>
7739	CPUID leaf sub index (ecx). This currently only applies to cache
7740	information on Intel CPUs. Use 0 if retriving values for
7741	<link to="IMachine::setCPUIDLeaf"/>.
7742	</desc>
7743	</param>
7744	<param name="valEax" type="unsigned long" dir="out">
7745	<desc>
7746	CPUID leaf value for register eax.
7747	</desc>
7748	</param>
7749	<param name="valEbx" type="unsigned long" dir="out">
7750	<desc>
7751	CPUID leaf value for register ebx.
7752	</desc>
7753	</param>
7754	<param name="valEcx" type="unsigned long" dir="out">
7755	<desc>
7756	CPUID leaf value for register ecx.
7757	</desc>
7758	</param>
7759	<param name="valEdx" type="unsigned long" dir="out">
7760	<desc>
7761	CPUID leaf value for register edx.
7762	</desc>
7763	</param>
7764	</method>
7765
7766	<attribute name="memorySize" type="unsigned long" readonly="yes">
7767	<desc>Amount of system memory in megabytes installed in the host system.</desc>
7768	</attribute>
7769
7770	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7771	<desc>Available system memory in the host system.</desc>
7772	</attribute>
7773
7774	<attribute name="operatingSystem" type="wstring" readonly="yes">
7775	<desc>Name of the host system's operating system.</desc>
7776	</attribute>
7777
7778	<attribute name="OSVersion" type="wstring" readonly="yes">
7779	<desc>Host operating system's version string.</desc>
7780	</attribute>
7781
7782	<attribute name="UTCTime" type="long long" readonly="yes">
7783	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7784	</attribute>
7785
7786	<attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
7787	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
7788	</attribute>
7789
7790	<method name="createHostOnlyNetworkInterface">
7791	<desc>
7792	Creates a new adapter for Host Only Networking.
7793	<result name="E_INVALIDARG">
7794	Host network interface @a name already exists.
7795	</result>
7796	</desc>
7797	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
7798	<desc>
7799	Created host interface object.
7800	</desc>
7801	</param>
7802	<param name="progress" type="IProgress" dir="return">
7803	<desc>
7804	Progress object to track the operation completion.
7805	</desc>
7806	</param>
7807	</method>
7808
7809	<method name="removeHostOnlyNetworkInterface">
7810	<desc>
7811	Removes the given Host Only Networking interface.
7812	<result name="VBOX_E_OBJECT_NOT_FOUND">
7813	No host network interface matching @a id found.
7814	</result>
7815	</desc>
7816	<param name="id" type="uuid" mod="string" dir="in">
7817	<desc>
7818	Adapter GUID.
7819	</desc>
7820	</param>
7821	<param name="progress" type="IProgress" dir="return">
7822	<desc>
7823	Progress object to track the operation completion.
7824	</desc>
7825	</param>
7826	</method>
7827
7828	<method name="createUSBDeviceFilter">
7829	<desc>
7830	Creates a new USB device filter. All attributes except
7831	the filter name are set to empty (any match),
7832	<i>active</i> is @c false (the filter is not active).
7833
7834	The created filter can be added to the list of filters using
7835	<link to="#insertUSBDeviceFilter"/>.
7836
7837	<see>#USBDeviceFilters</see>
7838	</desc>
7839	<param name="name" type="wstring" dir="in">
7840	<desc>
7841	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7842	for more info.
7843	</desc>
7844	</param>
7845	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
7846	<desc>Created filter object.</desc>
7847	</param>
7848	</method>
7849
7850	<method name="insertUSBDeviceFilter">
7851	<desc>
7852	Inserts the given USB device to the specified position
7853	in the list of filters.
7854
7855	Positions are numbered starting from @c 0. If the specified
7856	position is equal to or greater than the number of elements in
7857	the list, the filter is added at the end of the collection.
7858
7859	<note>
7860	Duplicates are not allowed, so an attempt to insert a
7861	filter already in the list is an error.
7862	</note>
7863	<note>
7864	If USB functionality is not available in the given edition of
7865	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7866	</note>
7867
7868	<see>#USBDeviceFilters</see>
7869
7870	<result name="VBOX_E_INVALID_OBJECT_STATE">
7871	USB device filter is not created within this VirtualBox instance.
7872	</result>
7873	<result name="E_INVALIDARG">
7874	USB device filter already in list.
7875	</result>
7876
7877	</desc>
7878	<param name="position" type="unsigned long" dir="in">
7879	<desc>Position to insert the filter to.</desc>
7880	</param>
7881	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
7882	<desc>USB device filter to insert.</desc>
7883	</param>
7884	</method>
7885
7886	<method name="removeUSBDeviceFilter">
7887	<desc>
7888	Removes a USB device filter from the specified position in the
7889	list of filters.
7890
7891	Positions are numbered starting from @c 0. Specifying a
7892	position equal to or greater than the number of elements in
7893	the list will produce an error.
7894
7895	<note>
7896	If USB functionality is not available in the given edition of
7897	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7898	</note>
7899
7900	<see>#USBDeviceFilters</see>
7901
7902	<result name="E_INVALIDARG">
7903	USB device filter list empty or invalid @a position.
7904	</result>
7905
7906	</desc>
7907	<param name="position" type="unsigned long" dir="in">
7908	<desc>Position to remove the filter from.</desc>
7909	</param>
7910	</method>
7911
7912	<method name="findHostDVDDrive">
7913	<desc>
7914	Searches for a host DVD drive with the given @c name.
7915
7916	<result name="VBOX_E_OBJECT_NOT_FOUND">
7917	Given @c name does not correspond to any host drive.
7918	</result>
7919
7920	</desc>
7921	<param name="name" type="wstring" dir="in">
7922	<desc>Name of the host drive to search for</desc>
7923	</param>
7924	<param name="drive" type="IMedium" dir="return">
7925	<desc>Found host drive object</desc>
7926	</param>
7927	</method>
7928
7929	<method name="findHostFloppyDrive">
7930	<desc>
7931	Searches for a host floppy drive with the given @c name.
7932
7933	<result name="VBOX_E_OBJECT_NOT_FOUND">
7934	Given @c name does not correspond to any host floppy drive.
7935	</result>
7936
7937	</desc>
7938	<param name="name" type="wstring" dir="in">
7939	<desc>Name of the host floppy drive to search for</desc>
7940	</param>
7941	<param name="drive" type="IMedium" dir="return">
7942	<desc>Found host floppy drive object</desc>
7943	</param>
7944	</method>
7945
7946	<method name="findHostNetworkInterfaceByName">
7947	<desc>
7948	Searches through all host network interfaces for an interface with
7949	the given @c name.
7950	<note>
7951	The method returns an error if the given @c name does not
7952	correspond to any host network interface.
7953	</note>
7954	</desc>
7955	<param name="name" type="wstring" dir="in">
7956	<desc>Name of the host network interface to search for.</desc>
7957	</param>
7958	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7959	<desc>Found host network interface object.</desc>
7960	</param>
7961	</method>
7962	<method name="findHostNetworkInterfaceById">
7963	<desc>
7964	Searches through all host network interfaces for an interface with
7965	the given GUID.
7966	<note>
7967	The method returns an error if the given GUID does not
7968	correspond to any host network interface.
7969	</note>
7970	</desc>
7971	<param name="id" type="uuid" mod="string" dir="in">
7972	<desc>GUID of the host network interface to search for.</desc>
7973	</param>
7974	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7975	<desc>Found host network interface object.</desc>
7976	</param>
7977	</method>
7978	<method name="findHostNetworkInterfacesOfType">
7979	<desc>
7980	Searches through all host network interfaces and returns a list of interfaces of the specified type
7981	</desc>
7982	<param name="type" type="HostNetworkInterfaceType" dir="in">
7983	<desc>type of the host network interfaces to search for.</desc>
7984	</param>
7985	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7986	<desc>Found host network interface objects.</desc>
7987	</param>
7988	</method>
7989
7990	<method name="findUSBDeviceById">
7991	<desc>
7992	Searches for a USB device with the given UUID.
7993
7994	<result name="VBOX_E_OBJECT_NOT_FOUND">
7995	Given @c id does not correspond to any USB device.
7996	</result>
7997
7998	<see>IHostUSBDevice::id</see>
7999	</desc>
8000	<param name="id" type="uuid" mod="string" dir="in">
8001	<desc>UUID of the USB device to search for.</desc>
8002	</param>
8003	<param name="device" type="IHostUSBDevice" dir="return">
8004	<desc>Found USB device object.</desc>
8005	</param>
8006	</method>
8007
8008	<method name="findUSBDeviceByAddress">
8009	<desc>
8010	Searches for a USB device with the given host address.
8011
8012	<result name="VBOX_E_OBJECT_NOT_FOUND">
8013	Given @c name does not correspond to any USB device.
8014	</result>
8015
8016	<see>IHostUSBDevice::address</see>
8017	</desc>
8018	<param name="name" type="wstring" dir="in">
8019	<desc>
8020	Address of the USB device (as assigned by the host) to
8021	search for.
8022	</desc>
8023	</param>
8024	<param name="device" type="IHostUSBDevice" dir="return">
8025	<desc>Found USB device object.</desc>
8026	</param>
8027	</method>
8028
8029	</interface>
8030
8031	<!--
8032	// ISystemProperties
8033	/////////////////////////////////////////////////////////////////////////
8034	-->
8035
8036	<interface
8037	name="ISystemProperties"
8038	extends="$unknown"
8039	uuid="07c3ffd8-8f59-49cc-b608-53a332e85cc3"
8040	wsmap="managed"
8041	>
8042	<desc>
8043	The ISystemProperties interface represents global properties of the given
8044	VirtualBox installation.
8045
8046	These properties define limits and default values for various attributes
8047	and parameters. Most of the properties are read-only, but some can be
8048	changed by a user.
8049	</desc>
8050
8051	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
8052	<desc>Minimum guest system memory in Megabytes.</desc>
8053	</attribute>
8054
8055	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
8056	<desc>Maximum guest system memory in Megabytes.</desc>
8057	</attribute>
8058
8059	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
8060	<desc>Minimum guest video memory in Megabytes.</desc>
8061	</attribute>
8062
8063	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
8064	<desc>Maximum guest video memory in Megabytes.</desc>
8065	</attribute>
8066
8067	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
8068	<desc>Minimum CPU count.</desc>
8069	</attribute>
8070
8071	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
8072	<desc>Maximum CPU count.</desc>
8073	</attribute>
8074
8075	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8076	<desc>Maximum of monitors which could be connected.</desc>
8077	</attribute>
8078
8079	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
8080	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
8081	</attribute>
8082
8083	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
8084	<desc>
8085	Number of network adapters associated with every
8086	<link to="IMachine"/> instance.
8087	</desc>
8088	</attribute>
8089
8090	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8091	<desc>
8092	Number of serial ports associated with every
8093	<link to="IMachine"/> instance.
8094	</desc>
8095	</attribute>
8096
8097	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8098	<desc>
8099	Number of parallel ports associated with every
8100	<link to="IMachine"/> instance.
8101	</desc>
8102	</attribute>
8103
8104	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8105	<desc>
8106	Maximum device position in the boot order. This value corresponds
8107	to the total number of devices a machine can boot from, to make it
8108	possible to include all possible devices to the boot list.
8109	<see><link to="IMachine::setBootOrder"/></see>
8110	</desc>
8111	</attribute>
8112
8113	<attribute name="defaultMachineFolder" type="wstring">
8114	<desc>
8115	Full path to the default directory used to create new or open
8116	existing machines when a settings file name contains no
8117	path.
8118
8119	The initial value of this property is
8120	<tt><</tt><link to="IVirtualBox::homeFolder">
8121	VirtualBox_home</link><tt>>/Machines</tt>.
8122
8123	<note>
8124	Setting this property to @c null or an empty string will restore the
8125	initial value.
8126	</note>
8127	<note>
8128	When settings this property, the specified path can be
8129	absolute (full path) or relative
8130	to the <link to="IVirtualBox::homeFolder">
8131	VirtualBox home directory</link>.
8132	When reading this property, a full path is
8133	always returned.
8134	</note>
8135	<note>
8136	The specified path may not exist, it will be created
8137	when necessary.
8138	</note>
8139
8140	<see>
8141	<link to="IVirtualBox::createMachine"/>,
8142	<link to="IVirtualBox::openMachine"/>
8143	</see>
8144	</desc>
8145	</attribute>
8146
8147	<attribute name="defaultHardDiskFolder" type="wstring">
8148	<desc>
8149	Full path to the default directory used to create new or open existing
8150	virtual disks.
8151
8152	This path is used when the storage unit of a hard disk is a regular file
8153	in the host's file system and only a file name that contains no path is
8154	given.
8155
8156	The initial value of this property is
8157	<tt><</tt>
8158	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
8159	<tt>>/HardDisks</tt>.
8160
8161	<note>
8162	Setting this property to @c null or empty string will restore the
8163	initial value.
8164	</note>
8165	<note>
8166	When settings this property, the specified path can be relative
8167	to the
8168	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
8169	absolute. When reading this property, a full path is
8170	always returned.
8171	</note>
8172	<note>
8173	The specified path may not exist, it will be created
8174	when necessary.
8175	</note>
8176
8177	<see>
8178	IMedium,
8179	<link to="IVirtualBox::createHardDisk"/>,
8180	<link to="IVirtualBox::openHardDisk"/>,
8181	<link to="IMedium::location"/>
8182	</see>
8183	</desc>
8184	</attribute>
8185
8186	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8187	<desc>
8188	List of all medium storage formats supported by this VirtualBox
8189	installation.
8190
8191	Keep in mind that the medium format identifier
8192	(<link to="IMediumFormat::id"/>) used in other API calls like
8193	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8194	medium format is a case-insensitive string. This means that, for
8195	example, all of the following strings:
8196	<pre>
8197	"VDI"
8198	"vdi"
8199	"VdI"</pre>
8200	refer to the same medium format.
8201
8202	Note that the virtual medium framework is backend-based, therefore
8203	the list of supported formats depends on what backends are currently
8204	installed.
8205
8206	<see>
8207	<link to="IMediumFormat"/>,
8208	</see>
8209	</desc>
8210	</attribute>
8211
8212	<attribute name="defaultHardDiskFormat" type="wstring">
8213	<desc>
8214	Identifier of the default medium format used by VirtualBox.
8215
8216	The medium format set by this attribute is used by VirtualBox
8217	when the medium format was not specified explicitly. One example is
8218	<link to="IVirtualBox::createHardDisk"/> with the empty
8219	format argument. A more complex example is implicit creation of
8220	differencing media when taking a snapshot of a virtual machine:
8221	this operation will try to use a format of the parent medium first
8222	and if this format does not support differencing media the default
8223	format specified by this argument will be used.
8224
8225	The list of supported medium formats may be obtained by the
8226	<link to="#mediaFormats"/> call. Note that the default medium
8227	format must have a capability to create differencing media;
8228	otherwise operations that create media implicitly may fail
8229	unexpectedly.
8230
8231	The initial value of this property is <tt>"VDI"</tt> in the current
8232	version of the VirtualBox product, but may change in the future.
8233
8234	<note>
8235	Setting this property to @c null or empty string will restore the
8236	initial value.
8237	</note>
8238
8239	<see>
8240	<link to="#mediaFormats"/>,
8241	<link to="IMediumFormat::id"/>,
8242	<link to="IVirtualBox::createHardDisk"/>
8243	</see>
8244	</desc>
8245	</attribute>
8246
8247	<attribute name="freeDiskSpaceWarning" type="unsigned long long">
8248	<desc>Issue a warning if the free disk space is below (or in some disk
8249	intensive operation is expected to go below) the given size in
8250	Megabytes.</desc>
8251	</attribute>
8252
8253	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
8254	<desc>Issue a warning if the free disk space is below (or in some disk
8255	intensive operation is expected to go below) the given percentage.</desc>
8256	</attribute>
8257
8258	<attribute name="freeDiskSpaceError" type="unsigned long long">
8259	<desc>Issue an error if the free disk space is below (or in some disk
8260	intensive operation is expected to go below) the given size in
8261	Megabytes.</desc>
8262	</attribute>
8263
8264	<attribute name="freeDiskSpacePercentError" type="unsigned long">
8265	<desc>Issue an error if the free disk space is below (or in some disk
8266	intensive operation is expected to go below) the given percentage.</desc>
8267	</attribute>
8268
8269	<attribute name="remoteDisplayAuthLibrary" type="wstring">
8270	<desc>
8271	Library that provides authentication for VRDP clients. The library
8272	is used if a virtual machine's authentication type is set to "external"
8273	in the VM RemoteDisplay configuration.
8274
8275	The system library extension (".DLL" or ".so") must be omitted.
8276	A full path can be specified; if not, then the library must reside on the
8277	system's default library path.
8278
8279	The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
8280	of that name in one of the default VirtualBox library directories.
8281
8282	For details about VirtualBox authentication libraries and how to implement
8283	them, please refer to the VirtualBox manual.
8284
8285	<note>
8286	Setting this property to @c null or empty string will restore the
8287	initial value.
8288	</note>
8289	</desc>
8290	</attribute>
8291
8292	<attribute name="webServiceAuthLibrary" type="wstring">
8293	<desc>
8294	Library that provides authentication for webservice clients. The library
8295	is used if a virtual machine's authentication type is set to "external"
8296	in the VM RemoteDisplay configuration and will be called from
8297	within the <link to="IWebsessionManager::logon" /> implementation.
8298
8299	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
8300	there is no per-VM setting for this, as the webservice is a global
8301	resource (if it is running). Only for this setting (for the webservice),
8302	setting this value to a literal <tt>"null"</tt> string disables authentication,
8303	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8304	no matter what user name and password are supplied.
8305
8306	The initial value of this property is <tt>"VRDPAuth"</tt>,
8307	meaning that the webservice will use the same authentication
8308	library that is used by default for VBoxVRDP (again, see
8309	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
8310	The format and calling convention of authentication libraries
8311	is the same for the webservice as it is for VBoxVRDP.
8312
8313	<note>
8314	Setting this property to @c null or empty string will restore the
8315	initial value.
8316	</note>
8317	</desc>
8318	</attribute>
8319
8320	<attribute name="LogHistoryCount" type="unsigned long">
8321	<desc>
8322	This value specifies how many old release log files are kept.
8323	</desc>
8324	</attribute>
8325
8326	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8327	<desc>This value hold the default audio driver for the current
8328	system.</desc>
8329	</attribute>
8330
8331	<method name="getMaxDevicesPerPortForStorageBus">
8332	<desc>Returns the maximum number of devices which can be attached to a port
8333	for the given storage bus.</desc>
8334
8335	<param name="bus" type="StorageBus" dir="in">
8336	<desc>The storage bus type to get the value for.</desc>
8337	</param>
8338
8339	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8340	<desc>The maximum number of devices which can eb attached to the port for the given
8341	storage bus.</desc>
8342	</param>
8343	</method>
8344
8345	<method name="getMinPortCountForStorageBus">
8346	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8347
8348	<param name="bus" type="StorageBus" dir="in">
8349	<desc>The storage bus type to get the value for.</desc>
8350	</param>
8351
8352	<param name="minPortCount" type="unsigned long" dir="return">
8353	<desc>The minimum number of ports for the given storage bus.</desc>
8354	</param>
8355	</method>
8356
8357	<method name="getMaxPortCountForStorageBus">
8358	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8359
8360	<param name="bus" type="StorageBus" dir="in">
8361	<desc>The storage bus type to get the value for.</desc>
8362	</param>
8363
8364	<param name="maxPortCount" type="unsigned long" dir="return">
8365	<desc>The maximum number of ports for the given storage bus.</desc>
8366	</param>
8367	</method>
8368
8369	<method name="getMaxInstancesOfStorageBus">
8370	<desc>Returns the maximum number of storage bus instances which
8371	can be configured for each VM. This corresponds to the number of
8372	storage controllers one can have.</desc>
8373
8374	<param name="bus" type="StorageBus" dir="in">
8375	<desc>The storage bus type to get the value for.</desc>
8376	</param>
8377
8378	<param name="maxInstances" type="unsigned long" dir="return">
8379	<desc>The maximum number of instances for the given storage bus.</desc>
8380	</param>
8381	</method>
8382
8383	<method name="getDeviceTypesForStorageBus">
8384	<desc>Returns list of all the supported device types
8385	(<link to="DeviceType"/>) for the given type of storage
8386	bus.</desc>
8387
8388	<param name="bus" type="StorageBus" dir="in">
8389	<desc>The storage bus type to get the value for.</desc>
8390	</param>
8391
8392	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8393	<desc>The list of all supported device types for the given storage bus.</desc>
8394	</param>
8395	</method>
8396	</interface>
8397
8398	<!--
8399	// IGuest
8400	/////////////////////////////////////////////////////////////////////////
8401	-->
8402
8403	<interface
8404	name="IGuestOSType" extends="$unknown"
8405	uuid="e3f6727e-a09b-41ea-a824-864a176472f3"
8406	wsmap="struct"
8407	>
8408	<desc>
8409	</desc>
8410
8411	<attribute name="familyId" type="wstring" readonly="yes">
8412	<desc>Guest OS family identifier string.</desc>
8413	</attribute>
8414
8415	<attribute name="familyDescription" type="wstring" readonly="yes">
8416	<desc>Human readable description of the guest OS family.</desc>
8417	</attribute>
8418
8419	<attribute name="id" type="wstring" readonly="yes">
8420	<desc>Guest OS identifier string.</desc>
8421	</attribute>
8422
8423	<attribute name="description" type="wstring" readonly="yes">
8424	<desc>Human readable description of the guest OS.</desc>
8425	</attribute>
8426
8427	<attribute name="is64Bit" type="boolean" readonly="yes">
8428	<desc>Returns @c true if the given OS is 64-bit</desc>
8429	</attribute>
8430
8431	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8432	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8433	</attribute>
8434
8435	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8436	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8437	</attribute>
8438
8439	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8440	<desc>Recommended RAM size in Megabytes.</desc>
8441	</attribute>
8442
8443	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8444	<desc>Recommended video RAM size in Megabytes.</desc>
8445	</attribute>
8446
8447	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
8448	<desc>Recommended hard disk size in Megabytes.</desc>
8449	</attribute>
8450
8451	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8452	<desc>Returns recommended network adapter for this OS type.</desc>
8453	</attribute>
8454
8455	<attribute name="recommendedPae" type="boolean" readonly="yes">
8456	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8457	</attribute>
8458
8459	<attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
8460	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8461	</attribute>
8462
8463	<attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
8464	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8465	</attribute>
8466
8467	<attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
8468	<desc>Recommended storage controller type for HD drives.</desc>
8469	</attribute>
8470
8471	<attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
8472	<desc>Recommended storage bus type for HD drives.</desc>
8473	</attribute>
8474
8475	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8476	<desc>Recommended firmware type.</desc>
8477	</attribute>
8478
8479	<attribute name="recommendedUsbHid" type="boolean" readonly="yes">
8480	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8481	</attribute>
8482
8483	<attribute name="recommendedHpet" type="boolean" readonly="yes">
8484	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8485	</attribute>
8486
8487	<attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
8488	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8489	</attribute>
8490
8491	<attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
8492	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8493	</attribute>
8494
8495	</interface>
8496
8497	<interface
8498	name="IGuest" extends="$unknown"
8499	uuid="d915dff1-ed38-495a-91f1-ab6c53932468"
8500	wsmap="managed"
8501	>
8502	<desc>
8503	The IGuest interface represents information about the operating system
8504	running inside the virtual machine. Used in
8505	<link to="IConsole::guest"/>.
8506
8507	IGuest provides information about the guest operating system, whether
8508	Guest Additions are installed and other OS-specific virtual machine
8509	properties.
8510	</desc>
8511
8512	<attribute name="OSTypeId" type="wstring" readonly="yes">
8513	<desc>
8514	Identifier of the Guest OS type as reported by the Guest
8515	Additions.
8516	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
8517	an IGuestOSType object representing details about the given
8518	Guest OS type.
8519	<note>
8520	If Guest Additions are not installed, this value will be
8521	the same as <link to="IMachine::OSTypeId"/>.
8522	</note>
8523	</desc>
8524	</attribute>
8525
8526	<attribute name="additionsActive" type="boolean" readonly="yes">
8527	<desc>
8528	Flag whether the Guest Additions are installed and active
8529	in which case their version will be returned by the
8530	<link to="#additionsVersion"/> property.
8531	</desc>
8532	</attribute>
8533
8534	<attribute name="additionsVersion" type="wstring" readonly="yes">
8535	<desc>
8536	Version of the Guest Additions (3 decimal numbers separated
8537	by dots) or empty when the Additions are not installed. The
8538	Additions may also report a version but yet not be active as
8539	the version might be refused by VirtualBox (incompatible) or
8540	other failures occurred.
8541	</desc>
8542	</attribute>
8543
8544	<attribute name="supportsSeamless" type="boolean" readonly="yes">
8545	<desc>
8546	Flag whether seamless guest display rendering (seamless desktop
8547	integration) is supported.
8548	</desc>
8549	</attribute>
8550
8551	<attribute name="supportsGraphics" type="boolean" readonly="yes">
8552	<desc>
8553	Flag whether the guest is in graphics mode. If it is not, then
8554	seamless rendering will not work, resize hints are not immediately
8555	acted on and guest display resizes are probably not initiated by
8556	the guest additions.
8557	</desc>
8558	</attribute>
8559
8560	<attribute name="memoryBalloonSize" type="unsigned long">
8561	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
8562	</attribute>
8563
8564	<attribute name="pageFusionEnabled" type="boolean">
8565	<desc>Flag whether page fusion is enabled or not.</desc>
8566	</attribute>
8567
8568	<attribute name="statisticsUpdateInterval" type="unsigned long">
8569	<desc>Interval to update guest statistics in seconds.</desc>
8570	</attribute>
8571
8572	<method name="internalGetStatistics">
8573	<desc>
8574	Internal method; do not use as it might change at any time
8575	</desc>
8576	<param name="cpuUser" type="unsigned long" dir="out">
8577	<desc>Percentage of processor time spent in user mode as seen by the guest</desc>
8578	</param>
8579	<param name="cpuKernel" type="unsigned long" dir="out">
8580	<desc>Percentage of processor time spent in kernel mode as seen by the guest</desc>
8581	</param>
8582	<param name="cpuIdle" type="unsigned long" dir="out">
8583	<desc>Percentage of processor time spent idling as seen by the guest</desc>
8584	</param>
8585	<param name="memTotal" type="unsigned long" dir="out">
8586	<desc>Total amount of physical guest RAM</desc>
8587	</param>
8588	<param name="memFree" type="unsigned long" dir="out">
8589	<desc>Free amount of physical guest RAM</desc>
8590	</param>
8591	<param name="memBalloon" type="unsigned long" dir="out">
8592	<desc>Amount of ballooned physical guest RAM</desc>
8593	</param>
8594	<param name="memShared" type="unsigned long" dir="out">
8595	<desc>Amount of shared physical guest RAM</desc>
8596	</param>
8597	<param name="memCache" type="unsigned long" dir="out">
8598	<desc>Total amount of guest (disk) cache memory</desc>
8599	</param>
8600	<param name="pagedTotal" type="unsigned long" dir="out">
8601	<desc>Total amount of space in the page file</desc>
8602	</param>
8603	<param name="memAllocTotal" type="unsigned long" dir="out">
8604	<desc>Total amount of memory allocated by the hypervisor</desc>
8605	</param>
8606	<param name="memFreeTotal" type="unsigned long" dir="out">
8607	<desc>Total amount of free memory available in the hypervisor</desc>
8608	</param>
8609	<param name="memBalloonTotal" type="unsigned long" dir="out">
8610	<desc>Total amount of memory ballooned by the hypervisor</desc>
8611	</param>
8612	<param name="memSharedTotal" type="unsigned long" dir="out">
8613	<desc>Total amount of shared memory in the hypervisor</desc>
8614	</param>
8615	</method>
8616
8617	<method name="setCredentials">
8618	<desc>
8619	Store login credentials that can be queried by guest operating
8620	systems with Additions installed. The credentials are transient
8621	to the session and the guest may also choose to erase them. Note
8622	that the caller cannot determine whether the guest operating system
8623	has queried or made use of the credentials.
8624
8625	<result name="VBOX_E_VM_ERROR">
8626	VMM device is not available.
8627	</result>
8628
8629	</desc>
8630	<param name="userName" type="wstring" dir="in">
8631	<desc>User name string, can be empty</desc>
8632	</param>
8633	<param name="password" type="wstring" dir="in">
8634	<desc>Password string, can be empty</desc>
8635	</param>
8636	<param name="domain" type="wstring" dir="in">
8637	<desc>Domain name (guest logon scheme specific), can be empty</desc>
8638	</param>
8639	<param name="allowInteractiveLogon" type="boolean" dir="in">
8640	<desc>
8641	Flag whether the guest should alternatively allow the user to
8642	interactively specify different credentials. This flag might
8643	not be supported by all versions of the Additions.
8644	</desc>
8645	</param>
8646	</method>
8647
8648	<method name="executeProcess">
8649	<desc>
8650	Executes an existing program inside the guest VM.
8651
8652	<result name="VBOX_E_IPRT_ERROR">
8653	Could not execute process.
8654	</result>
8655
8656	</desc>
8657	<param name="execName" type="wstring" dir="in">
8658	<desc>
8659	Full path name of the command to execute on the guest; the
8660	commands has to exists in the guest VM in order to be executed.
8661	</desc>
8662	</param>
8663	<param name="flags" type="unsigned long" dir="in">
8664	<desc>
8665	Execution flags - currently not supported and therefore
8666	has to be set to 0.
8667	</desc>
8668	</param>
8669	<param name="arguments" type="wstring" safearray="yes" dir="in">
8670	<desc>
8671	Array of arguments passed to the execution command.
8672	</desc>
8673	</param>
8674	<param name="environment" type="wstring" safearray="yes" dir="in">
8675	<desc>
8676	Environment variables that can be set while the command is being
8677	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
8678	variable just set its name ("NAME") without a value.
8679	</desc>
8680	</param>
8681	<param name="userName" type="wstring" dir="in">
8682	<desc>
8683	User name under which the command will be executed; has to exist
8684	and have the appropriate rights to execute programs in the VM.
8685	</desc>
8686	</param>
8687	<param name="password" type="wstring" dir="in">
8688	<desc>
8689	Password of the user account specified.
8690	</desc>
8691	</param>
8692	<param name="timeoutMS" type="unsigned long" dir="in">
8693	<desc>
8694	The maximum timeout value (in msec) to wait for finished program
8695	execution. Pass 0 for an infinite timeout.
8696	</desc>
8697	</param>
8698	<param name="pid" type="unsigned long" dir="out">
8699	<desc>
8700	The PID (process ID) of the started command for later reference.
8701	</desc>
8702	</param>
8703	<param name="progress" type="IProgress" dir="return">
8704	<desc>Progress object to track the operation completion.</desc>
8705	</param>
8706	</method>
8707
8708	<method name="getProcessOutput">
8709	<desc>
8710	Retrieves output of a formerly started process.
8711
8712	<result name="VBOX_E_IPRT_ERROR">
8713	Could not retrieve output.
8714	</result>
8715
8716	</desc>
8717	<param name="pid" type="unsigned long" dir="in">
8718	<desc>
8719	Process id returned by earlier executeProcess() call.
8720	</desc>
8721	</param>
8722	<param name="flags" type="unsigned long" dir="in">
8723	<desc>
8724	Flags describing which output to retrieve.
8725	</desc>
8726	</param>
8727	<param name="timeoutMS" type="unsigned long" dir="in">
8728	<desc>
8729	The maximum timeout value (in msec) to wait for output
8730	data. Pass 0 for an infinite timeout.
8731	</desc>
8732	</param>
8733	<param name="size" type="unsigned long long" dir="in">
8734	<desc>
8735	Size in bytes to read in the buffer.
8736	</desc>
8737	</param>
8738	<param name="data" type="octet" dir="return" safearray="yes">
8739	<desc>
8740	Buffer for retrieving the actual output. A data size of 0 means end of file
8741	if the requested size was not 0. This is the unprocessed
8742	output data, i.e. the line ending style depends on the platform of
8743	the system the server is running on.
8744	</desc>
8745	</param>
8746	</method>
8747
8748	<method name="getProcessStatus">
8749	<desc>
8750	Retrieves status, exit code and the exit reason of a formerly started process.
8751
8752	<result name="VBOX_E_IPRT_ERROR">
8753	Process with specified PID was not found.
8754	</result>
8755
8756	</desc>
8757	<param name="pid" type="unsigned long" dir="in">
8758	<desc>
8759	Process id returned by earlier executeProcess() call.
8760	</desc>
8761	</param>
8762	<param name="exitcode" type="unsigned long" dir="out">
8763	<desc>
8764	The exit code (if available).
8765	</desc>
8766	</param>
8767	<param name="flags" type="unsigned long" dir="out">
8768	<desc>
8769	Additional flags of process status (not used at the moment).
8770	</desc>
8771	</param>
8772	<param name="reason" type="unsigned long" dir="return">
8773	<desc>
8774	The current process status.
8775	</desc>
8776	</param>
8777	</method>
8778
8779	</interface>
8780
8781
8782	<!--
8783	// IProgress
8784	/////////////////////////////////////////////////////////////////////////
8785	-->
8786
8787	<interface
8788	name="IProgress" extends="$unknown"
8789	uuid="856aa038-853f-42e2-acf7-6e7b02dbe294"
8790	wsmap="managed"
8791	>
8792	<desc>
8793	The IProgress interface is used to track and control
8794	asynchronous tasks within VirtualBox.
8795
8796	An instance of this is returned every time VirtualBox starts
8797	an asynchronous task (in other words, a separate thread) which
8798	continues to run after a method call returns. For example,
8799	<link to="IConsole::saveState" />, which saves the state of
8800	a running virtual machine, can take a long time to complete.
8801	To be able to display a progress bar, a user interface such as
8802	the VirtualBox graphical user interface can use the IProgress
8803	object returned by that method.
8804
8805	Note that IProgress is a "read-only" interface in the sense
8806	that only the VirtualBox internals behind the Main API can
8807	create and manipulate progress objects, whereas client code
8808	can only use the IProgress object to monitor a task's
8809	progress and, if <link to="#cancelable" /> is @c true,
8810	cancel the task by calling <link to="#cancel" />.
8811
8812	A task represented by IProgress consists of either one or
8813	several sub-operations that run sequentially, one by one (see
8814	<link to="#operation" /> and <link to="#operationCount" />).
8815	Every operation is identified by a number (starting from 0)
8816	and has a separate description.
8817
8818	You can find the individual percentage of completion of the current
8819	operation in <link to="#operationPercent" /> and the
8820	percentage of completion of the task as a whole
8821	in <link to="#percent" />.
8822
8823	Similarly, you can wait for the completion of a particular
8824	operation via <link to="#waitForOperationCompletion" /> or
8825	for the completion of the whole task via
8826	<link to="#waitForCompletion" />.
8827	</desc>
8828
8829	<attribute name="id" type="uuid" mod="string" readonly="yes">
8830	<desc>ID of the task.</desc>
8831	</attribute>
8832
8833	<attribute name="description" type="wstring" readonly="yes">
8834	<desc>Description of the task.</desc>
8835	</attribute>
8836
8837	<attribute name="initiator" type="$unknown" readonly="yes">
8838	<desc>Initiator of the task.</desc>
8839	</attribute>
8840
8841	<attribute name="cancelable" type="boolean" readonly="yes">
8842	<desc>Whether the task can be interrupted.</desc>
8843	</attribute>
8844
8845	<attribute name="percent" type="unsigned long" readonly="yes">
8846	<desc>
8847	Current progress value of the task as a whole, in percent.
8848	This value depends on how many operations are already complete.
8849	Returns 100 if <link to="#completed" /> is @c true.
8850	</desc>
8851	</attribute>
8852
8853	<attribute name="timeRemaining" type="long" readonly="yes">
8854	<desc>
8855	Estimated remaining time until the task completes, in
8856	seconds. Returns 0 once the task has completed; returns -1
8857	if the remaining time cannot be computed, in particular if
8858	the current progress is 0.
8859
8860	Even if a value is returned, the estimate will be unreliable
8861	for low progress values. It will become more reliable as the
8862	task progresses; it is not recommended to display an ETA
8863	before at least 20% of a task have completed.
8864	</desc>
8865	</attribute>
8866
8867	<attribute name="completed" type="boolean" readonly="yes">
8868	<desc>Whether the task has been completed.</desc>
8869	</attribute>
8870
8871	<attribute name="canceled" type="boolean" readonly="yes">
8872	<desc>Whether the task has been canceled.</desc>
8873	</attribute>
8874
8875	<attribute name="resultCode" type="long" readonly="yes">
8876	<desc>
8877	Result code of the progress task.
8878	Valid only if <link to="#completed"/> is @c true.
8879	</desc>
8880	</attribute>
8881
8882	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
8883	<desc>
8884	Extended information about the unsuccessful result of the
8885	progress operation. May be @c null if no extended information
8886	is available.
8887	Valid only if <link to="#completed"/> is @c true and
8888	<link to="#resultCode"/> indicates a failure.
8889	</desc>
8890	</attribute>
8891
8892	<attribute name="operationCount" type="unsigned long" readonly="yes">
8893	<desc>
8894	Number of sub-operations this task is divided into.
8895	Every task consists of at least one suboperation.
8896	</desc>
8897	</attribute>
8898
8899	<attribute name="operation" type="unsigned long" readonly="yes">
8900	<desc>Number of the sub-operation being currently executed.</desc>
8901	</attribute>
8902
8903	<attribute name="operationDescription" type="wstring" readonly="yes">
8904	<desc>
8905	Description of the sub-operation being currently executed.
8906	</desc>
8907	</attribute>
8908
8909	<attribute name="operationPercent" type="unsigned long" readonly="yes">
8910	<desc>Progress value of the current sub-operation only, in percent.</desc>
8911	</attribute>
8912
8913	<attribute name="timeout" type="unsigned long">
8914	<desc>
8915	When non-zero, this specifies the number of milliseconds after which
8916	the operation will automatically be canceled. This can only be set on
8917	cancelable objects.
8918	</desc>
8919	</attribute>
8920
8921	<method name="setCurrentOperationProgress">
8922	<desc>Internal method, not to be called externally.</desc>
8923	<param name="percent" type="unsigned long" dir="in" />
8924	</method>
8925	<method name="setNextOperation">
8926	<desc>Internal method, not to be called externally.</desc>
8927	<param name="nextOperationDescription" type="wstring" dir="in" />
8928	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
8929	</method>
8930
8931	<method name="waitForCompletion">
8932	<desc>
8933	Waits until the task is done (including all sub-operations)
8934	with a given timeout in milliseconds; specify -1 for an indefinite wait.
8935
8936	<result name="VBOX_E_IPRT_ERROR">
8937	Failed to wait for task completion.
8938	</result>
8939	</desc>
8940
8941	<param name="timeout" type="long" dir="in">
8942	<desc>
8943	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8944	</desc>
8945	</param>
8946	</method>
8947
8948	<method name="waitForOperationCompletion">
8949	<desc>
8950	Waits until the given operation is done with a given timeout in
8951	milliseconds; specify -1 for an indefinite wait.
8952
8953	<result name="VBOX_E_IPRT_ERROR">
8954	Failed to wait for operation completion.
8955	</result>
8956
8957	</desc>
8958	<param name="operation" type="unsigned long" dir="in">
8959	<desc>
8960	Number of the operation to wait for.
8961	Must be less than <link to="#operationCount"/>.
8962	</desc>
8963	</param>
8964	<param name="timeout" type="long" dir="in">
8965	<desc>
8966	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8967	</desc>
8968	</param>
8969	</method>
8970
8971	<method name="cancel">
8972	<desc>
8973	Cancels the task.
8974	<note>
8975	If <link to="#cancelable"/> is @c false, then this method will fail.
8976	</note>
8977
8978	<result name="VBOX_E_INVALID_OBJECT_STATE">
8979	Operation cannot be canceled.
8980	</result>
8981
8982	</desc>
8983	</method>
8984
8985	</interface>
8986
8987
8988	<!--
8989	// ISnapshot
8990	/////////////////////////////////////////////////////////////////////////
8991	-->
8992
8993	<interface
8994	name="ISnapshot" extends="$unknown"
8995	uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
8996	wsmap="managed"
8997	>
8998	<desc>
8999	The ISnapshot interface represents a snapshot of the virtual
9000	machine.
9001
9002	Together with the differencing media that are created
9003	when a snapshot is taken, a machine can be brought back to
9004	the exact state it was in when the snapshot was taken.
9005
9006	The ISnapshot interface has no methods, only attributes; snapshots
9007	are controlled through methods of the <link to="IConsole" /> interface
9008	which also manage the media associated with the snapshot.
9009	The following operations exist:
9010
9011	<ul>
9012	<li><link to="IConsole::takeSnapshot"/>: creates a new snapshot
9013	by creating new, empty differencing images for the machine's
9014	media and saving the VM settings and (if the VM is running)
9015	the current VM state in the snapshot.
9016
9017	The differencing images will then receive all data written to
9018	the machine's media, while their parent (base) images
9019	remain unmodified after the snapshot has been taken (see
9020	<link to="IMedium" /> for details about differencing images).
9021	This simplifies restoring a machine to the state of a snapshot:
9022	only the differencing images need to be deleted.
9023
9024	The current machine state is not changed by taking a snapshot.
9025	If the machine is running, it will resume execution after the
9026	snapshot has been taken.
9027	</li>
9028
9029	<li><link to="IConsole::restoreSnapshot"/>: this goes back to
9030	a previous snapshot. This resets the machine's state to that of
9031	the previous snapshot by deleting the differencing image of each
9032	of the machine's media and setting the machine's settings
9033	and state to the state that was saved in the snapshot (if any).
9034
9035	This destroys the machine's current state.
9036	</li>
9037
9038	<li><link to="IConsole::deleteSnapshot"/>: deletes a snapshot
9039	without affecting the current machine state.
9040
9041	This does not change the machine, but instead frees the resources
9042	allocated when the snapshot was taken: the settings and machine state
9043	is deleted (if any), and the snapshot's differencing image for each
9044	of the machine's media gets merged with its parent image.
9045
9046	Neither the current machine state nor other snapshots are affected
9047	by this operation, except that parent media will be modified
9048	to contain the disk data associated with the snapshot being deleted.
9049	</li>
9050	</ul>
9051
9052	Each snapshot contains the settings of the virtual machine (hardware
9053	configuration etc.). In addition, if the machine was running when the
9054	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
9055	the current VM state is saved in the snapshot (similarly to what happens
9056	when a VM's state is saved). The snapshot is then said to
9057	be <i>online</i> because when restoring it, the VM will be running.
9058
9059	If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
9060	receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
9061
9062	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
9063	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
9064	it then contains a so-called "zero execution state", representing a
9065	machine that is powered off.
9066
9067	<h3>Snapshot branches and the "current" snapshot</h3>
9068
9069	Snapshots can be chained, whereby every next snapshot is based on the
9070	previous one. This chaining is related to medium branching
9071	(see the <link to="IMedium"/> description) in that every time
9072	a new snapshot is created, a new differencing medium is implicitly
9073	created for all normal media attached to the machine.
9074
9075	Each virtual machine has a "current snapshot", identified by
9076	<link to="IMachine::currentSnapshot"/>. Presently, this is always set
9077	to the last snapshot in the chain. In a future version of VirtualBox,
9078	it will be possible to reset a machine's current state to that of an
9079	earlier snapshot without deleting the current state so that it will be
9080	possible to create alternative snapshot paths in a snapshot tree.
9081
9082	In the current implementation, multiple snapshot branches within one
9083	virtual machine are not allowed. Every machine has a single branch,
9084	and <link to="IConsole::takeSnapshot"/> operation adds a new
9085	snapshot to the top of that branch.
9086	</desc>
9087
9088	<attribute name="id" type="uuid" mod="string" readonly="yes">
9089	<desc>UUID of the snapshot.</desc>
9090	</attribute>
9091
9092	<attribute name="name" type="wstring">
9093	<desc>Short name of the snapshot.</desc>
9094	</attribute>
9095
9096	<attribute name="description" type="wstring">
9097	<desc>Optional description of the snapshot.</desc>
9098	</attribute>
9099
9100	<attribute name="timeStamp" type="long long" readonly="yes">
9101	<desc>
9102	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
9103	</desc>
9104	</attribute>
9105
9106	<attribute name="online" type="boolean" readonly="yes">
9107	<desc>
9108	@c true if this snapshot is an online snapshot and @c false otherwise.
9109
9110	When this attribute is @c true, the
9111	<link to="IMachine::stateFilePath"/> attribute of the
9112	<link to="#machine"/> object associated with this snapshot
9113	will point to the saved state file. Otherwise, it will be
9114	an empty string.
9115	</desc>
9116	</attribute>
9117
9118	<attribute name="machine" type="IMachine" readonly="yes">
9119	<desc>
9120	Virtual machine this snapshot is taken on. This object
9121	stores all settings the machine had when taking this snapshot.
9122	<note>
9123	The returned machine object is immutable, i.e. no
9124	any settings can be changed.
9125	</note>
9126	</desc>
9127	</attribute>
9128
9129	<attribute name="parent" type="ISnapshot" readonly="yes">
9130	<desc>
9131	Parent snapshot (a snapshot this one is based on), or
9132	@c null if the snapshot has no parent (i.e. is the first snapshot).
9133	</desc>
9134	</attribute>
9135
9136	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
9137	<desc>
9138	Child snapshots (all snapshots having this one as a parent).
9139	</desc>
9140	</attribute>
9141
9142	</interface>
9143
9144
9145	<!--
9146	// IMedium
9147	/////////////////////////////////////////////////////////////////////////
9148	-->
9149
9150	<enum
9151	name="MediumState"
9152	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
9153	>
9154	<desc>
9155	Virtual medium state.
9156	<see>IMedium</see>
9157	</desc>
9158
9159	<const name="NotCreated" value="0">
9160	<desc>
9161	Associated medium storage does not exist (either was not created yet or
9162	was deleted).
9163	</desc>
9164	</const>
9165	<const name="Created" value="1">
9166	<desc>
9167	Associated storage exists and accessible; this gets set if the
9168	accessibility check performed by <link to="IMedium::refreshState" />
9169	was successful.
9170	</desc>
9171	</const>
9172	<const name="LockedRead" value="2">
9173	<desc>
9174	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
9175	no data modification is possible.
9176	</desc>
9177	</const>
9178	<const name="LockedWrite" value="3">
9179	<desc>
9180	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
9181	no concurrent data reading or modification is possible.
9182	</desc>
9183	</const>
9184	<const name="Inaccessible" value="4">
9185	<desc>
9186	Medium accessiblity check (see <link to="IMedium::refreshState" />) has
9187	not yet been performed, or else, associated medium storage is not
9188	accessible. In the first case, <link to="IMedium::lastAccessError"/>
9189	is empty, in the second case, it describes the error that occured.
9190	</desc>
9191	</const>
9192	<const name="Creating" value="5">
9193	<desc>
9194	Associated medium storage is being created.
9195	</desc>
9196	</const>
9197	<const name="Deleting" value="6">
9198	<desc>
9199	Associated medium storage is being deleted.
9200	</desc>
9201	</const>
9202	</enum>
9203
9204	<enum
9205	name="MediumType"
9206	uuid="46bf1fd4-ad86-4ded-8c49-28bd2d148e5a"
9207	>
9208	<desc>
9209	Virtual medium type.
9210	<see>IMedium</see>
9211	</desc>
9212
9213	<const name="Normal" value="0">
9214	<desc>
9215	Normal medium (attached directly or indirectly, preserved
9216	when taking snapshots).
9217	</desc>
9218	</const>
9219	<const name="Immutable" value="1">
9220	<desc>
9221	Immutable medium (attached indirectly, changes are wiped out
9222	the next time the virtual machine is started).
9223	</desc>
9224	</const>
9225	<const name="Writethrough" value="2">
9226	<desc>
9227	Write through medium (attached directly, ignored when
9228	taking snapshots).
9229	</desc>
9230	</const>
9231	<const name="Shareable" value="3">
9232	<desc>
9233	Allow using this medium concurrently by several machines.
9234	<note>This is a stub value. Not usable until this note is removed.</note>
9235	</desc>
9236	</const>
9237	</enum>
9238
9239	<enum
9240	name="MediumVariant"
9241	uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
9242	>
9243	<desc>
9244	Virtual medium image variant. More than one flag may be set.
9245	<see>IMedium</see>
9246	</desc>
9247
9248	<const name="Standard" value="0">
9249	<desc>
9250	No particular variant requested, results in using the backend default.
9251	</desc>
9252	</const>
9253	<const name="VmdkSplit2G" value="0x01">
9254	<desc>
9255	VMDK image split in chunks of less than 2GByte.
9256	</desc>
9257	</const>
9258	<const name="VmdkStreamOptimized" value="0x04">
9259	<desc>
9260	VMDK streamOptimized image. Special import/export format which is
9261	read-only/append-only.
9262	</desc>
9263	</const>
9264	<const name="VmdkESX" value="0x08">
9265	<desc>
9266	VMDK format variant used on ESX products.
9267	</desc>
9268	</const>
9269	<const name="Fixed" value="0x10000">
9270	<desc>
9271	Fixed image. Only allowed for base images.
9272	</desc>
9273	</const>
9274	<const name="Diff" value="0x20000">
9275	<desc>
9276	Fixed image. Only allowed for base images.
9277	</desc>
9278	</const>
9279	</enum>
9280
9281	<interface
9282	name="IMediumAttachment" extends="$unknown"
9283	uuid="e58eb3eb-8627-428b-bdf8-34487c848de5"
9284	wsmap="struct"
9285	>
9286	<desc>
9287	The IMediumAttachment interface represents the attachment
9288	of a storage medium to a virtual machine. Each machine contains
9289	an array of its medium attachments in <link to="IMachine::mediumAttachments"/>.
9290
9291	Each medium attachment specifies a storage controller as well as a port
9292	and device number. Fixed media (hard disks) will always also specify
9293	an instance of IMedium in <link to="#medium" />, referring to the hard disk
9294	medium. For removeable media, the IMedia instance is optional; it can be
9295	@c null if no media is mounted (see <link to="IMachine::mountMedium" />).
9296	</desc>
9297
9298	<attribute name="medium" type="IMedium" readonly="yes">
9299	<desc>Medium object associated with this attachment; it
9300	can be @c null for removable devices.</desc>
9301	</attribute>
9302
9303	<attribute name="controller" type="wstring" readonly="yes">
9304	<desc>Name of the storage controller of this attachment; this
9305	refers to one of the controllers in <link to="IMachine::storageControllers" />
9306	by name.</desc>
9307	</attribute>
9308
9309	<attribute name="port" type="long" readonly="yes">
9310	<desc>Port number of this attachment.
9311	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
9312	</desc>
9313	</attribute>
9314
9315	<attribute name="device" type="long" readonly="yes">
9316	<desc>Device slot number of this attachment.
9317	See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
9318	</desc>
9319	</attribute>
9320
9321	<attribute name="type" type="DeviceType" readonly="yes">
9322	<desc>Device type of this attachment.</desc>
9323	</attribute>
9324
9325	<attribute name="passthrough" type="boolean" readonly="yes">
9326	<desc>Pass I/O requests through to a device on the host.</desc>
9327	</attribute>
9328
9329	</interface>
9330
9331	<interface
9332	name="IMedium" extends="$unknown"
9333	uuid="1d578f43-5ef1-4415-b556-7592d3ccdc8f"
9334	wsmap="managed"
9335	>
9336	<desc>
9337	The IMedium interface represents virtual storage for a machine's
9338	hard disks, CD/DVD or floppy drives. It will typically represent
9339	a disk image on the host, for example a VDI or VMDK file representing
9340	a virtual hard disk, or an ISO or RAW file representing virtual
9341	removable media, but can also point to a network location (e.g.
9342	for iSCSI targets).
9343
9344	Instances of IMedium are connected to virtual machines by way of
9345	medium attachments (see <link to="IMediumAttachment" />), which link
9346	the storage medium to a particular device slot of a storage controller
9347	of the virtual machine.
9348	In the VirtualBox API, virtual storage is therefore always represented
9349	by the following chain of object links:
9350
9351	<ul>
9352	<li><link to="IMachine::storageControllers"/> contains an array of
9353	storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
9354	these are instances of <link to="IStorageController"/>).</li>
9355	<li><link to="IMachine::mediumAttachments"/> contains an array of
9356	medium attachments (instances of <link to="IMediumAttachment"/>),
9357	each containing a storage controller from the above array, a
9358	port/device specification, and an instance of IMedium representing
9359	the medium storage (image file).
9360
9361	For removable media, the storage medium is optional; a medium
9362	attachment with no medium represents a CD/DVD or floppy drive
9363	with no medium inserted. By contrast, hard disk attachments
9364	will always have an IMedium object attached.</li>
9365	<li>Each IMedium in turn points to a storage unit (such as a file
9366	on the host computer or a network resource) that holds actual
9367	data. This location is represented by the <link to="#location"/>
9368	attribute.</li>
9369	</ul>
9370
9371	Existing media are opened using the following methods, depending on the
9372	media type:
9373	<ul>
9374	<li><link to="IVirtualBox::openHardDisk"/></li>
9375	<li><link to="IVirtualBox::openDVDImage"/></li>
9376	<li><link to="IVirtualBox::openFloppyImage"/></li>
9377	</ul>
9378
9379	New hard disk media can be created with the VirtualBox API using the
9380	<link to="IVirtualBox::createHardDisk"/> method.
9381
9382	CD/DVD and floppy images (ISO and RAW files) are usually created outside
9383	VirtualBox, e.g. by storing a copy of the real medium of the corresponding
9384	type in a regular file.
9385
9386	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
9387	drive; in that case the <link to="#id" /> attribute contains the UUID of
9388	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
9389
9390	<h3>Known media</h3>
9391
9392	When an existing medium is opened for the first time, it is automatically
9393	remembered by the given VirtualBox installation or, in other words, becomes
9394	a <i>known medium</i>. Known media are stored in the media
9395	registry transparently maintained by VirtualBox and stored in settings
9396	files so that this registry is preserved when VirtualBox is not running.
9397
9398	Newly created virtual media are remembered only when the associated
9399	storage unit is actually created.
9400
9401	All known media can be enumerated using
9402	<link to="IVirtualBox::hardDisks"/>,
9403	<link to="IVirtualBox::DVDImages"/> and
9404	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
9405	quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
9406	and similar methods or by location using
9407	<link to="IVirtualBox::findHardDisk"/> and similar methods.
9408
9409	Only known media can be attached to virtual machines.
9410
9411	Removing known media from the media registry is performed when the given
9412	medium is closed using the <link to="#close"/> method or when its
9413	associated storage unit is deleted.
9414
9415	<h3>Accessibility checks</h3>
9416
9417	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
9418	method is called explicitly on a medium. This is done to make the VirtualBox object
9419	ready for serving requests as fast as possible and let the end-user
9420	application decide if it needs to check media accessibility right away or not.
9421
9422	As a result, when VirtualBox starts up (e.g. the VirtualBox
9423	object gets created for the first time), all known media are in the
9424	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
9425	attribute is an empty string because no actual accessibility check has
9426	been made yet.
9427
9428	After calling <link to="#refreshState" />, a medium is considered
9429	<i>accessible</i> if its storage unit can be read. In that case, the
9430	<link to="#state"/> attribute has a value of "Created". If the storage
9431	unit cannot be read (for example, because it is located on a disconnected
9432	network resource, or was accidentally deleted outside VirtualBox),
9433	the medium is considered <i>inaccessible</i>, which is indicated by the
9434	"Inaccessible" state. The exact reason why the medium is inaccessible can be
9435	obtained by reading the <link to="#lastAccessError"/> attribute.
9436
9437	<h3>Medium types</h3>
9438
9439	There are three types of medium behavior (see <link to="MediumType" />):
9440	"normal", "immutable" and "writethrough", represented by the
9441	<link to="#type"/> attribute. The type of the medium defines how the
9442	medium is attached to a virtual machine and what happens when a
9443	<link to="ISnapshot">snapshot</link> of the virtual machine with the
9444	attached medium is taken. At the moment DVD and floppy media are always
9445	of type "writethrough".
9446
9447	All media can be also divided in two groups: <i>base</i> media and
9448	<i>differencing</i> media. A base medium contains all sectors of the
9449	medium data in its own storage and therefore can be used independently.
9450	In contrast, a differencing mediun is a "delta" to some other medium and
9451	contains only those sectors which differ from that other medium, which is
9452	then called a <i>parent</i>. The differencing medium is said to be
9453	<i>linked to</i> that parent. The parent may be itself a differencing
9454	medium, thus forming a chain of linked media. The last element in that
9455	chain must always be a base medium. Note that several differencing
9456	media may be linked to the same parent medium.
9457
9458	Differencing media can be distinguished from base media by querying the
9459	<link to="#parent"/> attribute: base media do not have parents they would
9460	depend on, so the value of this attribute is always @c null for them.
9461	Using this attribute, it is possible to walk up the medium tree (from the
9462	child medium to its parent). It is also possible to walk down the tree
9463	using the <link to="#children"/> attribute.
9464
9465	Note that the type of all differencing media is "Normal"; all other
9466	values are meaningless for them. Base media may be of any type.
9467
9468	<h3>Creating hard disks</h3>
9469
9470	New base hard disks are created using
9471	<link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
9472	opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
9473	disks are usually implicitly created by VirtualBox when needed but may
9474	also be created explicitly using <link to="#createDiffStorage"/>.
9475
9476	After the hard disk is successfully created (including the storage unit)
9477	or opened, it becomes a known hard disk (remembered in the internal media
9478	registry). Known hard disks can be attached to a virtual machine, accessed
9479	through <link to="IVirtualBox::getHardDisk"/> and
9480	<link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
9481	<link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
9482
9483	The following methods, besides <link to="IMedium::close"/>,
9484	automatically remove the hard disk from the media registry:
9485	<ul>
9486	<li><link to="#deleteStorage"/></li>
9487	<li><link to="#mergeTo"/></li>
9488	</ul>
9489
9490	If the storage unit of the hard disk is a regular file in the host's
9491	file system then the rules stated in the description of the
9492	<link to="IMedium::location"/> attribute apply when setting its value. In
9493	addition, a plain file name without any path may be given, in which case
9494	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
9495	folder</link> will be prepended to it.
9496
9497	<h4>Automatic composition of the file name part</h4>
9498
9499	Another extension to the <link to="IMedium::location"/> attribute is that
9500	there is a possibility to cause VirtualBox to compose a unique value for
9501	the file name part of the location using the UUID of the hard disk. This
9502	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
9503	e.g. before the storage unit is created, and works as follows. You set the
9504	value of the <link to="IMedium::location"/> attribute to a location
9505	specification which only contains the path specification but not the file
9506	name part and ends with either a forward slash or a backslash character.
9507	In response, VirtualBox will generate a new UUID for the hard disk and
9508	compose the file name using the following pattern:
9509	<pre>
9510	<path>/{<uuid>}.<ext>
9511	</pre>
9512	where <tt><path></tt> is the supplied path specification,
9513	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
9514	is the default extension for the storage format of this hard disk. After
9515	that, you may call any of the methods that create a new hard disk storage
9516	unit and they will use the generated UUID and file name.
9517
9518	<h3>Attaching Hard Disks</h3>
9519
9520	Hard disks are attached to virtual machines using the
9521	<link to="IMachine::attachDevice"/> method and detached using the
9522	<link to="IMachine::detachDevice"/> method. Depending on their
9523	<link to="#type"/>, hard disks are attached either
9524	<i>directly</i> or <i>indirectly</i>.
9525
9526	When a hard disk is being attached directly, it is associated with the
9527	virtual machine and used for hard disk operations when the machine is
9528	running. When a hard disk is being attached indirectly, a new differencing
9529	hard disk linked to it is implicitly created and this differencing hard
9530	disk is associated with the machine and used for hard disk operations.
9531	This also means that if <link to="IMachine::attachDevice"/> performs
9532	a direct attachment then the same hard disk will be returned in response
9533	to the subsequent <link to="IMachine::getMedium"/> call; however if
9534	an indirect attachment is performed then
9535	<link to="IMachine::getMedium"/> will return the implicitly created
9536	differencing hard disk, not the original one passed to <link
9537	to="IMachine::attachDevice"/>. In detail:
9538
9539	<ul>
9540	<li><b>Normal base</b> hard disks that do not have children (i.e.
9541	differencing hard disks linked to them) and that are not already
9542	attached to virtual machines in snapshots are attached <b>directly</b>.
9543	Otherwise, they are attached <b>indirectly</b> because having
9544	dependent children or being part of the snapshot makes it impossible
9545	to modify hard disk contents without breaking the integrity of the
9546	dependent party. The <link to="#readOnly"/> attribute allows to
9547	quickly determine the kind of the attachment for the given hard
9548	disk. Note that if a normal base hard disk is to be indirectly
9549	attached to a virtual machine with snapshots then a special
9550	procedure called <i>smart attachment</i> is performed (see below).</li>
9551	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
9552	they are attached <b>directly</b> if they do not have children and are
9553	not attached to virtual machines in snapshots, and <b>indirectly</b>
9554	otherwise. Note that the smart attachment procedure is never performed
9555	for differencing hard disks.</li>
9556	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
9557	they are designed to be non-writable. If an immutable hard disk is
9558	attached to a virtual machine with snapshots then a special
9559	procedure called smart attachment is performed (see below).</li>
9560	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
9561	also as designed. This also means that writethrough hard disks cannot
9562	have other hard disks linked to them at all.</li>
9563	</ul>
9564
9565	Note that the same hard disk, regardless of its type, may be attached to
9566	more than one virtual machine at a time. In this case, the machine that is
9567	started first gains exclusive access to the hard disk and attempts to
9568	start other machines having this hard disk attached will fail until the
9569	first machine is powered down.
9570
9571	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
9572	that the given hard disk remains associated with the given machine after a
9573	successful <link to="IMachine::detachDevice"/> call until
9574	<link to="IMachine::saveSettings"/> is called to save all changes to
9575	machine settings to disk. This deferring is necessary to guarantee that
9576	the hard disk configuration may be restored at any time by a call to
9577	<link to="IMachine::discardSettings"/> before the settings
9578	are saved (committed).
9579
9580	Note that if <link to="IMachine::discardSettings"/> is called after
9581	indirectly attaching some hard disks to the machine but before a call to
9582	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
9583	all differencing hard disks implicitly created by
9584	<link to="IMachine::attachDevice"/> for these indirect attachments.
9585	Such implicitly created hard disks will also be immediately deleted when
9586	detached explicitly using the <link to="IMachine::detachDevice"/>
9587	call if it is made before <link to="IMachine::saveSettings"/>. This
9588	implicit deletion is safe because newly created differencing hard
9589	disks do not contain any user data.
9590
9591	However, keep in mind that detaching differencing hard disks that were
9592	implicitly created by <link to="IMachine::attachDevice"/>
9593	before the last <link to="IMachine::saveSettings"/> call will
9594	<b>not</b> implicitly delete them as they may already contain some data
9595	(for example, as a result of virtual machine execution). If these hard
9596	disks are no more necessary, the caller can always delete them explicitly
9597	using <link to="#deleteStorage"/> after they are actually de-associated
9598	from this machine by the <link to="IMachine::saveSettings"/> call.
9599
9600	<h3>Smart Attachment</h3>
9601
9602	When normal base or immutable hard disks are indirectly attached to a
9603	virtual machine then some additional steps are performed to make sure the
9604	virtual machine will have the most recent "view" of the hard disk being
9605	attached. These steps include walking through the machine's snapshots
9606	starting from the current one and going through ancestors up to the first
9607	snapshot. Hard disks attached to the virtual machine in all
9608	of the encountered snapshots are checked whether they are descendants of
9609	the given normal base or immutable hard disk. The first found child (which
9610	is the differencing hard disk) will be used instead of the normal base or
9611	immutable hard disk as a parent for creating a new differencing hard disk
9612	that will be actually attached to the machine. And only if no descendants
9613	are found or if the virtual machine does not have any snapshots then the
9614	normal base or immutable hard disk will be used itself as a parent for
9615	this differencing hard disk.
9616
9617	It is easier to explain what smart attachment does using the
9618	following example:
9619	<pre>
9620	BEFORE attaching B.vdi: AFTER attaching B.vdi:
9621
9622	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
9623	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
9624	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
9625	Snapshot 4 (none) Snapshot 4 (none)
9626	CurState (none) CurState (D3->D2.vdi)
9627
9628	NOT
9629	...
9630	CurState (D3->B.vdi)
9631	</pre>
9632	The first column is the virtual machine configuration before the base hard
9633	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
9634	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
9635	mean that the hard disk that is actually attached to the machine is a
9636	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
9637	another hard disk, <tt>B.vdi</tt>.
9638
9639	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
9640	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
9641	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
9642	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
9643	it cannot be attached directly and needs an indirect attachment (i.e.
9644	implicit creation of a new differencing hard disk). Due to the smart
9645	attachment procedure, the new differencing hard disk
9646	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
9647	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
9648	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
9649	machine.
9650
9651	Note that if there is more than one descendant hard disk of the given base
9652	hard disk found in a snapshot, and there is an exact device, channel and
9653	bus match, then this exact match will be used. Otherwise, the youngest
9654	descendant will be picked up.
9655
9656	There is one more important aspect of the smart attachment procedure which
9657	is not related to snapshots at all. Before walking through the snapshots
9658	as described above, the backup copy of the current list of hard disk
9659	attachment is searched for descendants. This backup copy is created when
9660	the hard disk configuration is changed for the first time after the last
9661	<link to="IMachine::saveSettings"/> call and used by
9662	<link to="IMachine::discardSettings"/> to undo the recent hard disk
9663	changes. When such a descendant is found in this backup copy, it will be
9664	simply re-attached back, without creating a new differencing hard disk for
9665	it. This optimization is necessary to make it possible to re-attach the
9666	base or immutable hard disk to a different bus, channel or device slot
9667	without losing the contents of the differencing hard disk actually
9668	attached to the machine in place of it.
9669	</desc>
9670
9671	<attribute name="id" type="uuid" mod="string" readonly="yes">
9672	<desc>
9673	UUID of the medium. For a newly created medium, this value is a randomly
9674	generated UUID.
9675
9676	<note>
9677	For media in one of MediumState_NotCreated, MediumState_Creating or
9678	MediumState_Deleting states, the value of this property is undefined
9679	and will most likely be an empty UUID.
9680	</note>
9681	</desc>
9682	</attribute>
9683
9684	<attribute name="description" type="wstring">
9685	<desc>
9686	Optional description of the medium. For a newly created medium the value
9687	of this attribute is an empty string.
9688
9689	Medium types that don't support this attribute will return E_NOTIMPL in
9690	attempt to get or set this attribute's value.
9691
9692	<note>
9693	For some storage types, reading this attribute may return an outdated
9694	(last known) value when <link to="#state"/> is <link
9695	to="MediumState_Inaccessible"/> or <link
9696	to="MediumState_LockedWrite"/> because the value of this attribute is
9697	stored within the storage unit itself. Also note that changing the
9698	attribute value is not possible in such case, as well as when the
9699	medium is the <link to="MediumState_LockedRead"/> state.
9700	</note>
9701	</desc>
9702	</attribute>
9703
9704	<attribute name="state" type="MediumState" readonly="yes">
9705	<desc>
9706	Returns the current medium state, which is the last state set by
9707	the accessibility check performed by <link to="#refreshState"/>.
9708	If that method has not yet been called on the medium, the state
9709	is "Inaccessible"; as opposed to truly inaccessible media, the
9710	value of <link to="#lastAccessError"/> will be an empty string in
9711	that case.
9712
9713	<note>As of version 3.1, this no longer performs an accessibility check
9714	automatically; call <link to="#refreshState"/> for that.
9715	</note>
9716	</desc>
9717	</attribute>
9718
9719	<attribute name="location" type="wstring">
9720	<desc>
9721	Location of the storage unit holding medium data.
9722
9723	The format of the location string is medium type specific. For medium
9724	types using regular files in a host's file system, the location
9725	string is the full file name.
9726
9727	Some medium types may support changing the storage unit location by
9728	simply changing the value of this property. If this operation is not
9729	supported, the implementation will return E_NOTIMPL in attempt to set
9730	this attribute's value.
9731
9732	When setting a value of the location attribute which is a regular file
9733	in the host's file system, the given file name may be either relative to
9734	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
9735	absolute. Note that if the given location specification does not contain
9736	the file extension part then a proper default extension will be
9737	automatically appended by the implementation depending on the medium type.
9738	</desc>
9739	</attribute>
9740
9741	<attribute name="name" type="wstring" readonly="yes">
9742	<desc>
9743	Name of the storage unit holding medium data.
9744
9745	The returned string is a short version of the <link to="#location"/>
9746	attribute that is suitable for representing the medium in situations
9747	where the full location specification is too long (such as lists
9748	and comboboxes in GUI frontends). This string is also used by frontends
9749	to sort the media list alphabetically when needed.
9750
9751	For example, for locations that are regular files in the host's file
9752	system, the value of this attribute is just the file name (+ extension),
9753	without the path specification.
9754
9755	Note that as opposed to the <link to="#location"/> attribute, the name
9756	attribute will not necessary be unique for a list of media of the
9757	given type and format.
9758	</desc>
9759	</attribute>
9760
9761	<attribute name="deviceType" type="DeviceType" readonly="yes">
9762	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
9763	medium.</desc>
9764	</attribute>
9765
9766	<attribute name="hostDrive" type="boolean" readonly="yes">
9767	<desc>True if this corresponds to a drive on the host.</desc>
9768	</attribute>
9769
9770	<attribute name="size" type="unsigned long long" readonly="yes">
9771	<desc>
9772	Physical size of the storage unit used to hold medium data (in bytes).
9773
9774	<note>
9775	For media whose <link to="#state"/> is <link
9776	to="MediumState_Inaccessible"/>, the value of this property is the
9777	last known size. For <link to="MediumState_NotCreated"/> media,
9778	the returned value is zero.
9779	</note>
9780	</desc>
9781	</attribute>
9782
9783	<attribute name="format" type="wstring" readonly="yes">
9784	<desc>
9785	Storage format of this medium.
9786
9787	The value of this attribute is a string that specifies a backend used
9788	to store medium data. The storage format is defined when you create a
9789	new medium or automatically detected when you open an existing medium,
9790	and cannot be changed later.
9791
9792	The list of all storage formats supported by this VirtualBox
9793	installation can be obtained using
9794	<link to="ISystemProperties::mediumFormats"/>.
9795	</desc>
9796	</attribute>
9797
9798	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
9799	<desc>
9800	Storage medium format object corresponding to this medium.
9801
9802	The value of this attribute is a reference to the medium format object
9803	that specifies the backend properties used to store medium data. The
9804	storage format is defined when you create a new medium or automatically
9805	detected when you open an existing medium, and cannot be changed later.
9806
9807	<note>@c null is returned if there is no associated medium format
9808	object. This can e.g. happen for medium objects representing host
9809	drives and other special medium objects.</note>
9810	</desc>
9811	</attribute>
9812
9813	<attribute name="type" type="MediumType">
9814	<desc>
9815	Type (role) of this medium.
9816
9817	The following constraints apply when changing the value of this
9818	attribute:
9819	<ul>
9820	<li>If a medium is attached to a virtual machine (either in the
9821	current state or in one of the snapshots), its type cannot be
9822	changed.
9823	</li>
9824	<li>As long as the medium has children, its type cannot be set
9825	to <link to="MediumType_Writethrough"/>.
9826	</li>
9827	<li>The type of all differencing media is
9828	<link to="MediumType_Normal"/> and cannot be changed.
9829	</li>
9830	</ul>
9831
9832	The type of a newly created or opened medium is set to
9833	<link to="MediumType_Normal"/>, except for DVD and floppy media,
9834	which have a type of <link to="MediumType_Writethrough"/>.
9835	</desc>
9836	</attribute>
9837
9838	<attribute name="parent" type="IMedium" readonly="yes">
9839	<desc>
9840	Parent of this medium (the medium this medium is directly based
9841	on).
9842
9843	Only differencing media have parents. For base (non-differencing)
9844	media, @c null is returned.
9845	</desc>
9846	</attribute>
9847
9848	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
9849	<desc>
9850	Children of this medium (all differencing media directly based
9851	on this medium). A @c null array is returned if this medium
9852	does not have any children.
9853	</desc>
9854	</attribute>
9855
9856	<attribute name="base" type="IMedium" readonly="yes">
9857	<desc>
9858	Base medium of this medium.
9859
9860	If this is a differencing medium, its base medium is the medium
9861	the given medium branch starts from. For all other types of media, this
9862	property returns the medium object itself (i.e. the same object this
9863	property is read on).
9864	</desc>
9865	</attribute>
9866
9867	<attribute name="readOnly" type="boolean" readonly="yes">
9868	<desc>
9869	Returns @c true if this medium is read-only and @c false otherwise.
9870
9871	A medium is considered to be read-only when its contents cannot be
9872	modified without breaking the integrity of other parties that depend on
9873	this medium such as its child media or snapshots of virtual machines
9874	where this medium is attached to these machines. If there are no
9875	children and no such snapshots then there is no dependency and the
9876	medium is not read-only.
9877
9878	The value of this attribute can be used to determine the kind of the
9879	attachment that will take place when attaching this medium to a
9880	virtual machine. If the value is @c false then the medium will
9881	be attached directly. If the value is @c true then the medium
9882	will be attached indirectly by creating a new differencing child
9883	medium for that. See the interface description for more information.
9884
9885	Note that all <link to="MediumType_Immutable">Immutable</link> media
9886	are always read-only while all
9887	<link to="MediumType_Writethrough">Writethrough</link> media are
9888	always not.
9889
9890	<note>
9891	The read-only condition represented by this attribute is related to
9892	the medium type and usage, not to the current
9893	<link to="IMedium::state">medium state</link> and not to the read-only
9894	state of the storage unit.
9895	</note>
9896	</desc>
9897	</attribute>
9898
9899	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
9900	<desc>
9901	Logical size of this medium (in megabytes), as reported to the
9902	guest OS running inside the virtual machine this medium is
9903	attached to. The logical size is defined when the medium is created
9904	and cannot be changed later.
9905
9906	<note>
9907	Reading this property on a differencing medium will return the size
9908	of its <link to="#base"/> medium.
9909	</note>
9910	<note>
9911	For media whose state is <link to="#state"/> is <link
9912	to="MediumState_Inaccessible"/>, the value of this property is the
9913	last known logical size. For <link to="MediumaState_NotCreated"/>
9914	media, the returned value is zero.
9915	</note>
9916	</desc>
9917	</attribute>
9918
9919	<attribute name="autoReset" type="boolean">
9920	<desc>
9921	Whether this differencing medium will be automatically reset each
9922	time a virtual machine it is attached to is powered up. This
9923	attribute is automatically set to @c true for the last
9924	differencing image of an "immutable" medium (see
9925	<link to="MediumType" />).
9926
9927	See <link to="#reset"/> for more information about resetting
9928	differencing media.
9929
9930	<note>
9931	Reading this property on a base (non-differencing) medium will
9932	always @c false. Changing the value of this property in this
9933	case is not supported.
9934	</note>
9935
9936	<result name="VBOX_E_NOT_SUPPORTED">
9937	This is not a differencing medium (when changing the attribute
9938	value).
9939	</result>
9940	</desc>
9941	</attribute>
9942
9943	<attribute name="lastAccessError" type="wstring" readonly="yes">
9944	<desc>
9945	Text message that represents the result of the last accessibility
9946	check performed by <link to="#refreshState"/>.
9947
9948	An empty string is returned if the last accessibility check
9949	was successful or has not yet been called. As a result, if
9950	<link to="#state" /> is "Inaccessible" and this attribute is empty,
9951	then <link to="#refreshState"/> has yet to be called; this is the
9952	default value of media after VirtualBox initialization.
9953	A non-empty string indicates a failure and should normally describe
9954	a reason of the failure (for example, a file read error).
9955	</desc>
9956	</attribute>
9957
9958	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
9959	<desc>
9960	Array of UUIDs of all machines this medium is attached to.
9961
9962	A @c null array is returned if this medium is not attached to any
9963	machine or to any machine's snapshot.
9964
9965	<note>
9966	The returned array will include a machine even if this medium is not
9967	attached to that machine in the current state but attached to it in
9968	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
9969	details.
9970	</note>
9971	</desc>
9972	</attribute>
9973
9974	<method name="refreshState">
9975	<desc>
9976	If the current medium state (see <link to="MediumState"/>) is one of
9977	"Created", "Inaccessible" or "LockedRead", then this performs an
9978	accessibility check on the medium and sets the value of the <link to="#state"/>
9979	attribute accordingly; that value is also returned for convenience.
9980
9981	For all other state values, this does not perform a refresh but returns
9982	the state only.
9983
9984	The refresh, if performed, may take a long time (several seconds or even
9985	minutes, depending on the storage unit location and format) because it performs an
9986	accessibility check of the storage unit. This check may cause a significant
9987	delay if the storage unit of the given medium is, for example, a file located
9988	on a network share which is not currently accessible due to connectivity
9989	problems. In that case, the call will not return until a timeout
9990	interval defined by the host OS for this operation expires. For this reason,
9991	it is recommended to never read this attribute on the main UI thread to avoid
9992	making the UI unresponsive.
9993
9994	If the last known state of the medium is "Created" and the accessibility
9995	check fails, then the state would be set to "Inaccessible", and
9996	<link to="#lastAccessError"/> may be used to get more details about the
9997	failure. If the state of the medium is "LockedRead", then it remains the
9998	same, and a non-empty value of <link to="#lastAccessError"/> will
9999	indicate a failed accessibility check in this case.
10000
10001	Note that not all medium states are applicable to all medium types.
10002	</desc>
10003	<param name="state" type="MediumState" dir="return">
10004	<desc>
10005	New medium state.
10006	</desc>
10007	</param>
10008	</method>
10009
10010	<method name="getSnapshotIds">
10011	<desc>
10012	Returns an array of UUIDs of all snapshots of the given machine where
10013	this medium is attached to.
10014
10015	If the medium is attached to the machine in the current state, then the
10016	first element in the array will always be the ID of the queried machine
10017	(i.e. the value equal to the @c machineId argument), followed by
10018	snapshot IDs (if any).
10019
10020	If the medium is not attached to the machine in the current state, then
10021	the array will contain only snapshot IDs.
10022
10023	The returned array may be @c null if this medium is not attached
10024	to the given machine at all, neither in the current state nor in one of
10025	the snapshots.
10026	</desc>
10027	<param name="machineId" type="uuid" mod="string" dir="in">
10028	<desc>
10029	UUID of the machine to query.
10030	</desc>
10031	</param>
10032	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
10033	<desc>
10034	Array of snapshot UUIDs of the given machine using this medium.
10035	</desc>
10036	</param>
10037	</method>
10038
10039	<method name="lockRead">
10040	<desc>
10041	Locks this medium for reading.
10042
10043	A read lock is shared: many clients can simultaneously lock the
10044	same medium for reading unless it is already locked for writing (see
10045	<link to="#lockWrite"/>) in which case an error is returned.
10046
10047	When the medium is locked for reading, it cannot be modified
10048	from within VirtualBox. This means that any method that changes
10049	the properties of this medium or contents of the storage unit
10050	will return an error (unless explicitly stated otherwise). That
10051	includes an attempt to start a virtual machine that wants to
10052	write to the the medium.
10053
10054	When the virtual machine is started up, it locks for reading all
10055	media it uses in read-only mode. If some medium cannot be locked
10056	for reading, the startup procedure will fail.
10057	A medium is typically locked for reading while it is used by a running
10058	virtual machine but has a depending differencing image that receives
10059	the actual write operations. This way one base medium can have
10060	multiple child differencing images which can be written to
10061	simultaneously. Read-only media such as DVD and floppy images are
10062	also locked for reading only (so they can be in use by multiple
10063	machines simultaneously).
10064
10065	A medium is also locked for reading when it is the source of a
10066	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10067
10068	The medium locked for reading must be unlocked using the <link
10069	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
10070	can be nested and must be followed by the same number of paired
10071	<link to="#unlockRead"/> calls.
10072
10073	This method sets the medium state (see <link to="#state"/>) to
10074	"LockedRead" on success. The medium's previous state must be
10075	one of "Created", "Inaccessible" or "LockedRead".
10076
10077	Locking an inaccessible medium is not an error; this method performs
10078	a logical lock that prevents modifications of this medium through
10079	the VirtualBox API, not a physical file-system lock of the underlying
10080	storage unit.
10081
10082	This method returns the current state of the medium
10083	<i>before</i> the operation.
10084
10085	<result name="VBOX_E_INVALID_OBJECT_STATE">
10086	Invalid medium state (e.g. not created, locked, inaccessible,
10087	creating, deleting).
10088	</result>
10089
10090	</desc>
10091	<param name="state" type="MediumState" dir="return">
10092	<desc>
10093	State of the medium after the operation.
10094	</desc>
10095	</param>
10096	</method>
10097
10098	<method name="unlockRead">
10099	<desc>
10100	Cancels the read lock previously set by <link to="#lockRead"/>.
10101
10102	For both success and failure, this method returns the current state
10103	of the medium <i>after</i> the operation.
10104
10105	See <link to="#lockRead"/> for more details.
10106
10107	<result name="VBOX_E_INVALID_OBJECT_STATE">
10108	Medium not locked for reading.
10109	</result>
10110
10111	</desc>
10112	<param name="state" type="MediumState" dir="return">
10113	<desc>
10114	State of the medium after the operation.
10115	</desc>
10116	</param>
10117	</method>
10118
10119	<method name="lockWrite">
10120	<desc>
10121	Locks this medium for writing.
10122
10123	A write lock, as opposed to <link to="#lockRead"/>, is
10124	exclusive: there may be only one client holding a write lock,
10125	and there may be no read locks while the write lock is held.
10126	As a result, read-locking fails if a write lock is held, and
10127	write-locking fails if either a read or another write lock is held.
10128
10129	When a medium is locked for writing, it cannot be modified
10130	from within VirtualBox, and it is not guaranteed that the values
10131	of its properties are up-to-date. Any method that changes the
10132	properties of this medium or contents of the storage unit will
10133	return an error (unless explicitly stated otherwise).
10134
10135	When a virtual machine is started up, it locks for writing all
10136	media it uses to write data to. If any medium could not be locked
10137	for writing, the startup procedure will fail. If a medium has
10138	differencing images, then while the machine is running, only
10139	the last ("leaf") differencing image is locked for writing,
10140	whereas its parents are locked for reading only.
10141
10142	A medium is also locked for writing when it is the target of a
10143	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10144
10145	The medium locked for writing must be unlocked using the <link
10146	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
10147
10148	This method sets the medium state (see <link to="#state"/>) to
10149	"LockedWrite" on success. The medium's previous state must be
10150	either "Created" or "Inaccessible".
10151
10152	Locking an inaccessible medium is not an error; this method performs
10153	a logical lock that prevents modifications of this medium through
10154	the VirtualBox API, not a physical file-system lock of the underlying
10155	storage unit.
10156
10157	For both, success and failure, this method returns the current
10158	state of the medium <i>before</i> the operation.
10159
10160	<result name="VBOX_E_INVALID_OBJECT_STATE">
10161	Invalid medium state (e.g. not created, locked, inaccessible,
10162	creating, deleting).
10163	</result>
10164
10165	</desc>
10166	<param name="state" type="MediumState" dir="return">
10167	<desc>
10168	State of the medium after the operation.
10169	</desc>
10170	</param>
10171	</method>
10172
10173	<method name="unlockWrite">
10174	<desc>
10175	Cancels the write lock previously set by <link to="#lockWrite"/>.
10176
10177	For both success and failure, this method returns the current
10178	state of the medium <i>after</i> the operation.
10179
10180	See <link to="#lockWrite"/> for more details.
10181
10182	<result name="VBOX_E_INVALID_OBJECT_STATE">
10183	Medium not locked for writing.
10184	</result>
10185
10186	</desc>
10187	<param name="state" type="MediumState" dir="return">
10188	<desc>
10189	State of the medium after the operation.
10190	</desc>
10191	</param>
10192	</method>
10193
10194	<method name="close">
10195	<desc>
10196	Closes this medium.
10197
10198	The medium must not be attached to any known virtual machine
10199	and must not have any known child media, otherwise the
10200	operation will fail.
10201
10202	When the medium is successfully closed, it gets removed from
10203	the list of remembered media, but its storage unit is not
10204	deleted. In particular, this means that this medium can be
10205	later opened again using the <link
10206	to="IVirtualBox::openHardDisk"/> call.
10207
10208	Note that after this method successfully returns, the given medium
10209	object becomes uninitialized. This means that any attempt
10210	to call any of its methods or attributes will fail with the
10211	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
10212
10213	<result name="VBOX_E_INVALID_OBJECT_STATE">
10214	Invalid medium state (other than not created, created or
10215	inaccessible).
10216	</result>
10217	<result name="VBOX_E_OBJECT_IN_USE">
10218	Medium attached to virtual machine.
10219	</result>
10220	<result name="VBOX_E_FILE_ERROR">
10221	Settings file not accessible.
10222	</result>
10223	<result name="VBOX_E_XML_ERROR">
10224	Could not parse the settings file.
10225	</result>
10226
10227	</desc>
10228	</method>
10229
10230	<!-- storage methods -->
10231
10232	<method name="getProperty">
10233	<desc>
10234	Returns the value of the custom medium property with the given name.
10235
10236	The list of all properties supported by the given medium format can
10237	be obtained with <link to="IMediumFormat::describeProperties"/>.
10238
10239	Note that if this method returns an empty string in @a value, the
10240	requested property is supported but currently not assigned any value.
10241
10242	<result name="VBOX_E_OBJECT_NOT_FOUND">
10243	Requested property does not exist (not supported by the format).
10244	</result>
10245	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10246	</desc>
10247	<param name="name" type="wstring" dir="in">
10248	<desc>Name of the property to get.</desc>
10249	</param>
10250	<param name="value" type="wstring" dir="return">
10251	<desc>Current property value.</desc>
10252	</param>
10253	</method>
10254
10255	<method name="setProperty">
10256	<desc>
10257	Sets the value of the custom medium property with the given name.
10258
10259	The list of all properties supported by the given medium format can
10260	be obtained with <link to="IMediumFormat::describeProperties"/>.
10261
10262	Note that setting the property value to @c null or an empty string is
10263	equivalent to deleting the existing value. A default value (if it is
10264	defined for this property) will be used by the format backend in this
10265	case.
10266
10267	<result name="VBOX_E_OBJECT_NOT_FOUND">
10268	Requested property does not exist (not supported by the format).
10269	</result>
10270	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10271	</desc>
10272	<param name="name" type="wstring" dir="in">
10273	<desc>Name of the property to set.</desc>
10274	</param>
10275	<param name="value" type="wstring" dir="in">
10276	<desc>Property value to set.</desc>
10277	</param>
10278	</method>
10279
10280	<method name="getProperties">
10281	<desc>
10282	Returns values for a group of properties in one call.
10283
10284	The names of the properties to get are specified using the @a names
10285	argument which is a list of comma-separated property names or
10286	an empty string if all properties are to be returned. Note that currently
10287	the value of this argument is ignored and the method always returns all
10288	existing properties.
10289
10290	The list of all properties supported by the given medium format can
10291	be obtained with <link to="IMediumFormat::describeProperties"/>.
10292
10293	The method returns two arrays, the array of property names corresponding
10294	to the @a names argument and the current values of these properties.
10295	Both arrays have the same number of elements with each elemend at the
10296	given index in the first array corresponds to an element at the same
10297	index in the second array.
10298
10299	Note that for properties that do not have assigned values,
10300	an empty string is returned at the appropriate index in the
10301	@a returnValues array.
10302
10303	</desc>
10304	<param name="names" type="wstring" dir="in">
10305	<desc>
10306	Names of properties to get.
10307	</desc>
10308	</param>
10309	<param name="returnNames" type="wstring" safearray="yes" dir="out">
10310	<desc>Names of returned properties.</desc>
10311	</param>
10312	<param name="returnValues" type="wstring" safearray="yes" dir="return">
10313	<desc>Values of returned properties.</desc>
10314	</param>
10315	</method>
10316
10317	<method name="setProperties">
10318	<desc>
10319	Sets values for a group of properties in one call.
10320
10321	The names of the properties to set are passed in the @a names
10322	array along with the new values for them in the @a values array. Both
10323	arrays have the same number of elements with each elemend at the given
10324	index in the first array corresponding to an element at the same index
10325	in the second array.
10326
10327	If there is at least one property name in @a names that is not valid,
10328	the method will fail before changing the values of any other properties
10329	from the @a names array.
10330
10331	Using this method over <link to="#setProperty"/> is preferred if you
10332	need to set several properties at once since it will result into less
10333	IPC calls.
10334
10335	The list of all properties supported by the given medium format can
10336	be obtained with <link to="IMediumFormat::describeProperties"/>.
10337
10338	Note that setting the property value to @c null or an empty string is
10339	equivalent to deleting the existing value. A default value (if it is
10340	defined for this property) will be used by the format backend in this
10341	case.
10342	</desc>
10343	<param name="names" type="wstring" safearray="yes" dir="in">
10344	<desc>Names of properties to set.</desc>
10345	</param>
10346	<param name="values" type="wstring" safearray="yes" dir="in">
10347	<desc>Values of properties to set.</desc>
10348	</param>
10349	</method>
10350
10351	<!-- storage methods -->
10352
10353	<method name="createBaseStorage">
10354	<desc>
10355	Starts creating a hard disk storage unit (fixed/dynamic, according
10356	to the variant flags) in in the background. The previous storage unit
10357	created for this object, if any, must first be deleted using
10358	<link to="#deleteStorage"/>, otherwise the operation will fail.
10359
10360	Before the operation starts, the medium is placed in
10361	<link to="MediumState_Creating"/> state. If the create operation
10362	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
10363	state.
10364
10365	After the returned progress object reports that the operation has
10366	successfully completed, the medium state will be set to <link
10367	to="MediumState_Created"/>, the medium will be remembered by this
10368	VirtualBox installation and may be attached to virtual machines.
10369
10370	<result name="VBOX_E_NOT_SUPPORTED">
10371	The variant of storage creation operation is not supported. See <link
10372	to="IMediumFormat::capabilities"/>.
10373	</result>
10374	</desc>
10375	<param name="logicalSize" type="unsigned long long" dir="in">
10376	<desc>Maximum logical size of the medium in megabytes.</desc>
10377	</param>
10378	<param name="variant" type="MediumVariant" dir="in">
10379	<desc>Exact image variant which should be created.</desc>
10380	</param>
10381	<param name="progress" type="IProgress" dir="return">
10382	<desc>Progress object to track the operation completion.</desc>
10383	</param>
10384	</method>
10385
10386	<method name="deleteStorage">
10387	<desc>
10388	Starts deleting the storage unit of this medium.
10389
10390	The medium must not be attached to any known virtual machine and must
10391	not have any known child media, otherwise the operation will fail.
10392	It will also fail if there is no storage unit to delete or if deletion
10393	is already in progress, or if the medium is being in use (locked for
10394	read or for write) or inaccessible. Therefore, the only valid state for
10395	this operation to succeed is <link to="MediumState_Created"/>.
10396
10397	Before the operation starts, the medium is placed in
10398	<link to="MediumState_Deleting"/> state and gets removed from the list
10399	of remembered hard disks (media registry). If the delete operation
10400	fails, the medium will be remembered again and placed back to
10401	<link to="MediumState_Created"/> state.
10402
10403	After the returned progress object reports that the operation is
10404	complete, the medium state will be set to
10405	<link to="MediumState_NotCreated"/> and you will be able to use one of
10406	the storage creation methods to create it again.
10407
10408	<see>#close()</see>
10409
10410	<result name="VBOX_E_OBJECT_IN_USE">
10411	Medium is attached to a virtual machine.
10412	</result>
10413	<result name="VBOX_E_NOT_SUPPORTED">
10414	Storage deletion is not allowed because neither of storage creation
10415	operations are supported. See
10416	<link to="IMediumFormat::capabilities"/>.
10417	</result>
10418
10419	<note>
10420	If the deletion operation fails, it is not guaranteed that the storage
10421	unit still exists. You may check the <link to="IMedium::state"/> value
10422	to answer this question.
10423	</note>
10424	</desc>
10425	<param name="progress" type="IProgress" dir="return">
10426	<desc>Progress object to track the operation completion.</desc>
10427	</param>
10428	</method>
10429
10430	<!-- diff methods -->
10431
10432	<method name="createDiffStorage">
10433	<desc>
10434	Starts creating an empty differencing storage unit based on this
10435	medium in the format and at the location defined by the @a target
10436	argument.
10437
10438	The target medium must be in <link to="MediumState_NotCreated"/>
10439	state (i.e. must not have an existing storage unit). Upon successful
10440	completion, this operation will set the type of the target medium to
10441	<link to="MediumType_Normal"/> and create a storage unit necessary to
10442	represent the differencing medium data in the given format (according
10443	to the storage format of the target object).
10444
10445	After the returned progress object reports that the operation is
10446	successfully complete, the target medium gets remembered by this
10447	VirtualBox installation and may be attached to virtual machines.
10448
10449	<note>
10450	The medium will be set to <link to="MediumState_LockedRead"/>
10451	state for the duration of this operation.
10452	</note>
10453	<result name="VBOX_E_OBJECT_IN_USE">
10454	Medium not in @c NotCreated state.
10455	</result>
10456	</desc>
10457	<param name="target" type="IMedium" dir="in">
10458	<desc>Target medium.</desc>
10459	</param>
10460	<param name="variant" type="MediumVariant" dir="in">
10461	<desc>Exact image variant which should be created.</desc>
10462	</param>
10463	<param name="progress" type="IProgress" dir="return">
10464	<desc>Progress object to track the operation completion.</desc>
10465	</param>
10466	</method>
10467
10468	<method name="mergeTo">
10469	<desc>
10470	Starts merging the contents of this medium and all intermediate
10471	differencing media in the chain to the given target medium.
10472
10473	The target medium must be either a descendant of this medium or
10474	its ancestor (otherwise this method will immediately return a failure).
10475	It follows that there are two logical directions of the merge operation:
10476	from ancestor to descendant (<i>forward merge</i>) and from descendant to
10477	ancestor (<i>backward merge</i>). Let us consider the following medium
10478	chain:
10479
10480	<pre>Base <- Diff_1 <- Diff_2</pre>
10481
10482	Here, calling this method on the <tt>Base</tt> medium object with
10483	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
10484	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
10485	merge. Note that in both cases the contents of the resulting medium
10486	will be the same, the only difference is the medium object that takes
10487	the result of the merge operation. In case of the forward merge in the
10488	above example, the result will be written to <tt>Diff_2</tt>; in case of
10489	the backward merge, the result will be written to <tt>Base</tt>. In
10490	other words, the result of the operation is always stored in the target
10491	medium.
10492
10493	Upon successful operation completion, the storage units of all media in
10494	the chain between this (source) medium and the target medium, including
10495	the source medium itself, will be automatically deleted and the
10496	relevant medium objects (including this medium) will become
10497	uninitialized. This means that any attempt to call any of
10498	their methods or attributes will fail with the
10499	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
10500	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
10501	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
10502	Note that <tt>Diff_2</tt> in this case will become a base medium
10503	itself since it will no longer be based on any other medium.
10504
10505	Considering the above, all of the following conditions must be met in
10506	order for the merge operation to succeed:
10507	<ul>
10508	<li>
10509	Neither this (source) medium nor any intermediate
10510	differencing medium in the chain between it and the target
10511	medium is attached to any virtual machine.
10512	</li>
10513	<li>
10514	Neither the source medium nor the target medium is an
10515	<link to="MediumType_Immutable"/> medium.
10516	</li>
10517	<li>
10518	The part of the medium tree from the source medium to the
10519	target medium is a linear chain, i.e. all medium in this
10520	chain have exactly one child which is the next medium in this
10521	chain. The only exception from this rule is the target medium in
10522	the forward merge operation; it is allowed to have any number of
10523	child media because the merge operation will not change its
10524	logical contents (as it is seen by the guest OS or by children).
10525	</li>
10526	<li>
10527	None of the involved media are in
10528	<link to="MediumState_LockedRead"/> or
10529	<link to="MediumState_LockedWrite"/> state.
10530	</li>
10531	</ul>
10532
10533	<note>
10534	This (source) medium and all intermediates will be placed to <link
10535	to="MediumState_Deleting"/> state and the target medium will be
10536	placed to <link to="MediumState_LockedWrite"/> state and for the
10537	duration of this operation.
10538	</note>
10539	</desc>
10540	<param name="target" type="IMedium" dir="in">
10541	<desc>Target medium.</desc>
10542	</param>
10543	<param name="progress" type="IProgress" dir="return">
10544	<desc>Progress object to track the operation completion.</desc>
10545	</param>
10546	</method>
10547
10548	<!-- clone method -->
10549
10550	<method name="cloneTo">
10551	<desc>
10552	Starts creating a clone of this medium in the format and at the
10553	location defined by the @a target argument.
10554
10555	The target medium must be either in <link to="MediumState_NotCreated"/>
10556	state (i.e. must not have an existing storage unit) or in
10557	<link to="MediumState_Created"/> state (i.e. created and not locked, and
10558	big enough to hold the data or else the copy will be partial). Upon
10559	successful completion, the cloned medium will contain exactly the
10560	same sector data as the medium being cloned, except that in the
10561	first case a new UUID for the clone will be randomly generated, and in
10562	the second case the UUID will remain unchanged.
10563
10564	The @a parent argument defines which medium will be the parent
10565	of the clone. Passing a @c null reference indicates that the clone will
10566	be a base image, i.e. completely independent. It is possible to specify
10567	an arbitrary medium for this parameter, including the parent of the
10568	medium which is being cloned. Even cloning to a child of the source
10569	medium is possible. Note that when cloning to an existing image, the
10570	@a parent irgument is ignored.
10571
10572	After the returned progress object reports that the operation is
10573	successfully complete, the target medium gets remembered by this
10574	VirtualBox installation and may be attached to virtual machines.
10575
10576	<note>
10577	This medium will be placed to <link to="MediumState_LockedRead"/>
10578	state for the duration of this operation.
10579	</note>
10580	<result name="E_NOTIMPL">
10581	The specified cloning variant is not supported at the moment.
10582	</result>
10583	</desc>
10584	<param name="target" type="IMedium" dir="in">
10585	<desc>Target medium.</desc>
10586	</param>
10587	<param name="variant" type="MediumVariant" dir="in">
10588	<desc>Exact image variant which should be created.</desc>
10589	</param>
10590	<param name="parent" type="IMedium" dir="in">
10591	<desc>Parent of the cloned medium.</desc>
10592	</param>
10593	<param name="progress" type="IProgress" dir="return">
10594	<desc>Progress object to track the operation completion.</desc>
10595	</param>
10596	</method>
10597
10598	<!-- other methods -->
10599
10600	<method name="compact">
10601	<desc>
10602	Starts compacting of this medium. This means that the medium is
10603	transformed into a possibly more compact storage representation.
10604	This potentially creates temporary images, which can require a
10605	substantial amount of additional disk space.
10606
10607	This medium will be placed to <link to="MediumState_LockedWrite"/>
10608	state and all its parent media (if any) will be placed to
10609	<link to="MediumState_LockedRead"/> state for the duration of this
10610	operation.
10611
10612	Please note that the results can be either returned straight away,
10613	or later as the result of the background operation via the object
10614	returned via the @a progress parameter.
10615
10616	<result name="VBOX_E_NOT_SUPPORTED">
10617	Medium format does not support compacting (but potentially
10618	needs it).
10619	</result>
10620	</desc>
10621	<param name="progress" type="IProgress" dir="return">
10622	<desc>Progress object to track the operation completion.</desc>
10623	</param>
10624	</method>
10625
10626	<method name="resize">
10627	<desc>
10628	Starts resizing this medium. This means that the nominal size of the
10629	medium is set to the new value. Both increasing and decreasing the
10630	size is possible, and there are no safety checks, since VirtualBox
10631	does not make any assumptions about the medium contents.
10632
10633	Resizing usually needs additional disk space, and possibly also
10634	some temporary disk space. Note that resize does not create a full
10635	temporary copy of the medium, so the additional disk space requirement
10636	is usually much lower than using the clone operation.
10637
10638	This medium will be placed to <link to="MediumState_LockedWrite"/>
10639	state for the duration of this operation.
10640
10641	Please note that the results can be either returned straight away,
10642	or later as the result of the background operation via the object
10643	returned via the @a progress parameter.
10644
10645	<result name="VBOX_E_NOT_SUPPORTED">
10646	Medium format does not support resizing.
10647	</result>
10648	</desc>
10649	<param name="logicalSize" type="unsigned long long" dir="in">
10650	<desc>New nominal capacity of the medium in megabytes.</desc>
10651	</param>
10652	<param name="progress" type="IProgress" dir="return">
10653	<desc>Progress object to track the operation completion.</desc>
10654	</param>
10655	</method>
10656
10657	<method name="reset">
10658	<desc>
10659	Starts erasing the contents of this differencing medium.
10660
10661	This operation will reset the differencing medium to its initial
10662	state when it does not contain any sector data and any read operation is
10663	redirected to its parent medium. This automatically gets called
10664	during VM power-up for every medium whose <link to="#autoReset" />
10665	attribute is @c true.
10666
10667	The medium will be write-locked for the duration of this operation (see
10668	<link to="#lockWrite" />).
10669
10670	<result name="VBOX_E_NOT_SUPPORTED">
10671	This is not a differencing medium.
10672	</result>
10673	<result name="VBOX_E_INVALID_OBJECT_STATE">
10674	Medium is not in <link to="MediumState_Created"/> or
10675	<link to="MediumState_Inaccessible"/> state.
10676	</result>
10677	</desc>
10678	<param name="progress" type="IProgress" dir="return">
10679	<desc>Progress object to track the operation completion.</desc>
10680	</param>
10681	</method>
10682
10683	</interface>
10684
10685
10686	<!--
10687	// IMediumFormat
10688	/////////////////////////////////////////////////////////////////////////
10689	-->
10690
10691	<enum
10692	name="DataType"
10693	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
10694	>
10695	<const name="Int32" value="0"/>
10696	<const name="Int8" value="1"/>
10697	<const name="String" value="2"/>
10698	</enum>
10699
10700	<enum
10701	name="DataFlags"
10702	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
10703	>
10704	<const name="None" value="0x00"/>
10705	<const name="Mandatory" value="0x01"/>
10706	<const name="Expert" value="0x02"/>
10707	<const name="Array" value="0x04"/>
10708	<const name="FlagMask" value="0x07"/>
10709	</enum>
10710
10711	<enum
10712	name="MediumFormatCapabilities"
10713	uuid="70fcf810-99e8-4edc-aee4-7f51d489e657"
10714	>
10715	<desc>
10716	Medium format capability flags.
10717	</desc>
10718
10719	<const name="Uuid" value="0x01">
10720	<desc>
10721	Supports UUIDs as expected by VirtualBox code.
10722	</desc>
10723	</const>
10724
10725	<const name="CreateFixed" value="0x02">
10726	<desc>
10727	Supports creating fixed size images, allocating all space instantly.
10728	</desc>
10729	</const>
10730
10731	<const name="CreateDynamic" value="0x04">
10732	<desc>
10733	Supports creating dynamically growing images, allocating space on
10734	demand.
10735	</desc>
10736	</const>
10737
10738	<const name="CreateSplit2G" value="0x08">
10739	<desc>
10740	Supports creating images split in chunks of a bit less than 2 GBytes.
10741	</desc>
10742	</const>
10743
10744	<const name="Differencing" value="0x10">
10745	<desc>
10746	Supports being used as a format for differencing media (see <link
10747	to="IMedium::createDiffStorage"/>).
10748	</desc>
10749	</const>
10750
10751	<const name="Asynchronous" value="0x20">
10752	<desc>
10753	Supports asynchronous I/O operations for at least some configurations.
10754	</desc>
10755	</const>
10756
10757	<const name="File" value="0x40">
10758	<desc>
10759	The format backend operates on files (the <link to="IMedium::location"/>
10760	attribute of the medium specifies a file used to store medium
10761	data; for a list of supported file extensions see
10762	<link to="IMediumFormat::fileExtensions"/>).
10763	</desc>
10764	</const>
10765
10766	<const name="Properties" value="0x80">
10767	<desc>
10768	The format backend uses the property interface to configure the storage
10769	location and properties (the <link to="IMediumFormat::describeProperties"/>
10770	method is used to get access to properties supported by the given medium format).
10771	</desc>
10772	</const>
10773
10774	<const name="CapabilityMask" value="0xFF"/>
10775	</enum>
10776
10777	<interface
10778	name="IMediumFormat" extends="$unknown"
10779	uuid="89f52554-d469-4799-9fad-1705e86a08b1"
10780	wsmap="managed"
10781	>
10782	<desc>
10783	The IMediumFormat interface represents a medium format.
10784
10785	Each medium format has an associated backend which is used to handle
10786	media stored in this format. This interface provides information
10787	about the properties of the associated backend.
10788
10789	Each medium format is identified by a string represented by the
10790	<link to="#id"/> attribute. This string is used in calls like
10791	<link to="IVirtualBox::createHardDisk"/> to specify the desired
10792	format.
10793
10794	The list of all supported medium formats can be obtained using
10795	<link to="ISystemProperties::mediaFormats"/>.
10796
10797	<see>IMedium</see>
10798	</desc>
10799
10800	<attribute name="id" type="wstring" readonly="yes">
10801	<desc>
10802	Identifier of this format.
10803
10804	The format identifier is a non-@c null non-empty ASCII string. Note that
10805	this string is case-insensitive. This means that, for example, all of
10806	the following strings:
10807	<pre>
10808	"VDI"
10809	"vdi"
10810	"VdI"</pre>
10811	refer to the same medium format.
10812
10813	This string is used in methods of other interfaces where it is necessary
10814	to specify a medium format, such as
10815	<link to="IVirtualBox::createHardDisk"/>.
10816	</desc>
10817	</attribute>
10818
10819	<attribute name="name" type="wstring" readonly="yes">
10820	<desc>
10821	Human readable description of this format.
10822
10823	Mainly for use in file open dialogs.
10824	</desc>
10825	</attribute>
10826
10827	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
10828	<desc>
10829	Array of strings containing the supported file extensions.
10830
10831	The first extension in the array is the extension preferred by the
10832	backend. It is recommended to use this extension when specifying a
10833	location of the storage unit for a new medium.
10834
10835	Note that some backends do not work on files, so this array may be
10836	empty.
10837
10838	<see>IMediumFormat::capabilities</see>
10839	</desc>
10840	</attribute>
10841
10842	<attribute name="capabilities" type="unsigned long" readonly="yes">
10843	<desc>
10844	Capabilities of the format as a set of bit flags.
10845
10846	For the meaning of individual capability flags see
10847	<link to="MediumFormatCapabilities"/>.
10848	</desc>
10849	</attribute>
10850
10851	<method name="describeProperties">
10852	<desc>
10853	Returns several arrays describing the properties supported by this
10854	format.
10855
10856	An element with the given index in each array describes one
10857	property. Thus, the number of elements in each returned array is the
10858	same and corresponds to the number of supported properties.
10859
10860	The returned arrays are filled in only if the
10861	<link to="MediumFormatCapabilities_Properties"/> flag is set.
10862	All arguments must be non-@c null.
10863
10864	<see>DataType</see>
10865	<see>DataFlags</see>
10866	</desc>
10867
10868	<param name="names" type="wstring" safearray="yes" dir="out">
10869	<desc>Array of property names.</desc>
10870	</param>
10871	<param name="description" type="wstring" safearray="yes" dir="out">
10872	<desc>Array of property descriptions.</desc>
10873	</param>
10874	<param name="types" type="DataType" safearray="yes" dir="out">
10875	<desc>Array of property types.</desc>
10876	</param>
10877	<param name="flags" type="unsigned long" safearray="yes" dir="out">
10878	<desc>Array of property flags.</desc>
10879	</param>
10880	<param name="defaults" type="wstring" safearray="yes" dir="out">
10881	<desc>Array of default property values.</desc>
10882	</param>
10883	</method>
10884
10885	</interface>
10886
10887
10888	<!--
10889	// IKeyboard
10890	/////////////////////////////////////////////////////////////////////////
10891	-->
10892
10893	<interface
10894	name="IKeyboard" extends="$unknown"
10895	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
10896	wsmap="managed"
10897	>
10898	<desc>
10899	The IKeyboard interface represents the virtual machine's keyboard. Used
10900	in <link to="IConsole::keyboard"/>.
10901
10902	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
10903	to the virtual machine.
10904
10905	</desc>
10906	<method name="putScancode">
10907	<desc>Sends a scancode to the keyboard.
10908
10909	<result name="VBOX_E_IPRT_ERROR">
10910	Could not send scan code to virtual keyboard.
10911	</result>
10912
10913	</desc>
10914	<param name="scancode" type="long" dir="in"/>
10915	</method>
10916
10917	<method name="putScancodes">
10918	<desc>Sends an array of scancodes to the keyboard.
10919
10920	<result name="VBOX_E_IPRT_ERROR">
10921	Could not send all scan codes to virtual keyboard.
10922	</result>
10923
10924	</desc>
10925	<param name="scancodes" type="long" dir="in" safearray="yes"/>
10926	<param name="codesStored" type="unsigned long" dir="return"/>
10927	</method>
10928
10929	<method name="putCAD">
10930	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
10931	function is nothing special, it is just a convenience function
10932	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
10933
10934	<result name="VBOX_E_IPRT_ERROR">
10935	Could not send all scan codes to virtual keyboard.
10936	</result>
10937
10938	</desc>
10939	</method>
10940
10941	</interface>
10942
10943
10944	<!--
10945	// IMouse
10946	/////////////////////////////////////////////////////////////////////////
10947	-->
10948
10949	<enum
10950	name="MouseButtonState"
10951	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
10952	>
10953	<desc>
10954	Mouse button state.
10955	</desc>
10956
10957	<const name="LeftButton" value="0x01"/>
10958	<const name="RightButton" value="0x02"/>
10959	<const name="MiddleButton" value="0x04"/>
10960	<const name="WheelUp" value="0x08"/>
10961	<const name="WheelDown" value="0x10"/>
10962	<const name="XButton1" value="0x20"/>
10963	<const name="XButton2" value="0x40"/>
10964	<const name="MouseStateMask" value="0x7F"/>
10965	</enum>
10966
10967	<interface
10968	name="IMouse" extends="$unknown"
10969	uuid="7c0f2eae-f92d-498c-b802-e1a3763774dc"
10970	wsmap="managed"
10971	>
10972	<desc>
10973	The IMouse interface represents the virtual machine's mouse. Used in
10974	<link to="IConsole::mouse"/>.
10975
10976	Through this interface, the virtual machine's virtual mouse can be
10977	controlled.
10978	</desc>
10979
10980	<attribute name="absoluteSupported" type="boolean" readonly="yes">
10981	<desc>
10982	Whether the guest OS supports absolute mouse pointer positioning
10983	or not.
10984	<note>
10985	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10986	callback to be instantly informed about changes of this attribute
10987	during virtual machine execution.
10988	</note>
10989	<see><link to="#putMouseEventAbsolute"/></see>
10990	</desc>
10991	</attribute>
10992
10993	<attribute name="relativeSupported" type="boolean" readonly="yes">
10994	<desc>
10995	Whether the guest OS supports relative mouse pointer positioning
10996	or not.
10997	<note>
10998	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10999	callback to be instantly informed about changes of this attribute
11000	during virtual machine execution.
11001	</note>
11002	<see><link to="#putMouseEvent"/></see>
11003	</desc>
11004	</attribute>
11005
11006	<attribute name="needsHostCursor" type="boolean" readonly="yes">
11007	<desc>
11008	Whether the guest OS can currently switch to drawing it's own mouse
11009	cursor on demand.
11010	<note>
11011	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
11012	callback to be instantly informed about changes of this attribute
11013	during virtual machine execution.
11014	</note>
11015	<see><link to="#putMouseEvent"/></see>
11016	</desc>
11017	</attribute>
11018
11019	<method name="putMouseEvent">
11020	<desc>
11021	Initiates a mouse event using relative pointer movements
11022	along x and y axis.
11023
11024	<result name="E_ACCESSDENIED">
11025	Console not powered up.
11026	</result>
11027	<result name="VBOX_E_IPRT_ERROR">
11028	Could not send mouse event to virtual mouse.
11029	</result>
11030
11031	</desc>
11032
11033	<param name="dx" type="long" dir="in">
11034	<desc>
11035	Amount of pixels the mouse should move to the right.
11036	Negative values move the mouse to the left.
11037	</desc>
11038	</param>
11039	<param name="dy" type="long" dir="in">
11040	<desc>
11041	Amount of pixels the mouse should move downwards.
11042	Negative values move the mouse upwards.
11043	</desc>
11044	</param>
11045	<param name="dz" type="long" dir="in">
11046	<desc>
11047	Amount of mouse wheel moves.
11048	Positive values describe clockwise wheel rotations,
11049	negative values describe counterclockwise rotations.
11050	</desc>
11051	</param>
11052	<param name="dw" type="long" dir="in">
11053	<desc>
11054	Amount of horizontal mouse wheel moves.
11055	Positive values describe a movement to the left,
11056	negative values describe a movement to the right.
11057	</desc>
11058	</param>
11059	<param name="buttonState" type="long" dir="in">
11060	<desc>
11061	The current state of mouse buttons. Every bit represents
11062	a mouse button as follows:
11063	<table>
11064	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11065	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11066	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11067	</table>
11068	A value of <tt>1</tt> means the corresponding button is pressed.
11069	otherwise it is released.
11070	</desc>
11071	</param>
11072	</method>
11073
11074	<method name="putMouseEventAbsolute">
11075	<desc>
11076	Positions the mouse pointer using absolute x and y coordinates.
11077	These coordinates are expressed in pixels and
11078	start from <tt>[1,1]</tt> which corresponds to the top left
11079	corner of the virtual display.
11080
11081	<result name="E_ACCESSDENIED">
11082	Console not powered up.
11083	</result>
11084	<result name="VBOX_E_IPRT_ERROR">
11085	Could not send mouse event to virtual mouse.
11086	</result>
11087
11088	<note>
11089	This method will have effect only if absolute mouse
11090	positioning is supported by the guest OS.
11091	</note>
11092
11093	<see><link to="#absoluteSupported"/></see>
11094	</desc>
11095
11096	<param name="x" type="long" dir="in">
11097	<desc>
11098	X coordinate of the pointer in pixels, starting from @c 1.
11099	</desc>
11100	</param>
11101	<param name="y" type="long" dir="in">
11102	<desc>
11103	Y coordinate of the pointer in pixels, starting from @c 1.
11104	</desc>
11105	</param>
11106	<param name="dz" type="long" dir="in">
11107	<desc>
11108	Amount of mouse wheel moves.
11109	Positive values describe clockwise wheel rotations,
11110	negative values describe counterclockwise rotations.
11111	</desc>
11112	</param>
11113	<param name="dw" type="long" dir="in">
11114	<desc>
11115	Amount of horizontal mouse wheel moves.
11116	Positive values describe a movement to the left,
11117	negative values describe a movement to the right.
11118	</desc>
11119	</param>
11120	<param name="buttonState" type="long" dir="in">
11121	<desc>
11122	The current state of mouse buttons. Every bit represents
11123	a mouse button as follows:
11124	<table>
11125	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11126	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11127	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11128	</table>
11129	A value of @c 1 means the corresponding button is pressed.
11130	otherwise it is released.
11131	</desc>
11132	</param>
11133	</method>
11134
11135	</interface>
11136
11137	<!--
11138	// IDisplay
11139	/////////////////////////////////////////////////////////////////////////
11140	-->
11141
11142	<enum
11143	name="FramebufferPixelFormat"
11144	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
11145	>
11146	<desc>
11147	Format of the video memory buffer. Constants represented by this enum can
11148	be used to test for particular values of <link
11149	to="IFramebuffer::pixelFormat"/>. See also <link
11150	to="IFramebuffer::requestResize"/>.
11151
11152	See also www.fourcc.org for more information about FOURCC pixel formats.
11153	</desc>
11154
11155	<const name="Opaque" value="0">
11156	<desc>
11157	Unknown buffer format (the user may not assume any particular format of
11158	the buffer).
11159	</desc>
11160	</const>
11161	<const name="FOURCC_RGB" value="0x32424752">
11162	<desc>
11163	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
11164	bit layout).
11165	</desc>
11166	</const>
11167	</enum>
11168
11169	<interface
11170	name="IFramebuffer" extends="$unknown"
11171	uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
11172	wsmap="suppress"
11173	>
11174	<attribute name="address" type="octet" mod="ptr" readonly="yes">
11175	<desc>Address of the start byte of the frame buffer.</desc>
11176	</attribute>
11177
11178	<attribute name="width" type="unsigned long" readonly="yes">
11179	<desc>Frame buffer width, in pixels.</desc>
11180	</attribute>
11181
11182	<attribute name="height" type="unsigned long" readonly="yes">
11183	<desc>Frame buffer height, in pixels.</desc>
11184	</attribute>
11185
11186	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
11187	<desc>
11188	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
11189	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
11190	are: 8, 15, 16, 24 and 32.
11191	</desc>
11192	</attribute>
11193
11194	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
11195	<desc>
11196	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
11197	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
11198	size of the scan line must be aligned to 32 bits.
11199	</desc>
11200	</attribute>
11201
11202	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
11203	<desc>
11204	Frame buffer pixel format. It's either one of the values defined by <link
11205	to="FramebufferPixelFormat"/> or a raw FOURCC code.
11206	<note>
11207	This attribute must never return <link
11208	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
11209	<link to="#address"/> points to must be always known.
11210	</note>
11211	</desc>
11212	</attribute>
11213
11214	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
11215	<desc>
11216	Defines whether this frame buffer uses the virtual video card's memory
11217	buffer (guest VRAM) directly or not. See <link
11218	to="IFramebuffer::requestResize"/> for more information.
11219	</desc>
11220	</attribute>
11221
11222	<attribute name="heightReduction" type="unsigned long" readonly="yes">
11223	<desc>
11224	Hint from the frame buffer about how much of the standard
11225	screen height it wants to use for itself. This information is
11226	exposed to the guest through the VESA BIOS and VMMDev interface
11227	so that it can use it for determining its video mode table. It
11228	is not guaranteed that the guest respects the value.
11229	</desc>
11230	</attribute>
11231
11232	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
11233	<desc>
11234	An alpha-blended overlay which is superposed over the frame buffer.
11235	The initial purpose is to allow the display of icons providing
11236	information about the VM state, including disk activity, in front
11237	ends which do not have other means of doing that. The overlay is
11238	designed to controlled exclusively by IDisplay. It has no locking
11239	of its own, and any changes made to it are not guaranteed to be
11240	visible until the affected portion of IFramebuffer is updated. The
11241	overlay can be created lazily the first time it is requested. This
11242	attribute can also return @c null to signal that the overlay is not
11243	implemented.
11244	</desc>
11245	</attribute>
11246
11247	<attribute name="winId" type="unsigned long long" readonly="yes">
11248	<desc>
11249	Platform-dependent identifier of the window where context of this
11250	frame buffer is drawn, or zero if there's no such window.
11251	</desc>
11252	</attribute>
11253
11254	<method name="lock">
11255	<desc>
11256	Locks the frame buffer.
11257	Gets called by the IDisplay object where this frame buffer is
11258	bound to.
11259	</desc>
11260	</method>
11261
11262	<method name="unlock">
11263	<desc>
11264	Unlocks the frame buffer.
11265	Gets called by the IDisplay object where this frame buffer is
11266	bound to.
11267	</desc>
11268	</method>
11269
11270	<method name="notifyUpdate">
11271	<desc>
11272	Informs about an update.
11273	Gets called by the display object where this buffer is
11274	registered.
11275	</desc>
11276	<param name="x" type="unsigned long" dir="in"/>
11277	<param name="y" type="unsigned long" dir="in"/>
11278	<param name="width" type="unsigned long" dir="in"/>
11279	<param name="height" type="unsigned long" dir="in"/>
11280	</method>
11281
11282	<method name="requestResize">
11283	<desc>
11284	Requests a size and pixel format change.
11285
11286	There are two modes of working with the video buffer of the virtual
11287	machine. The <i>indirect</i> mode implies that the IFramebuffer
11288	implementation allocates a memory buffer for the requested display mode
11289	and provides it to the virtual machine. In <i>direct</i> mode, the
11290	IFramebuffer implementation uses the memory buffer allocated and owned
11291	by the virtual machine. This buffer represents the video memory of the
11292	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
11293	usually faster because the implementation gets a raw pointer to the
11294	guest VRAM buffer which it can directly use for visualizing the contents
11295	of the virtual display, as opposed to the indirect mode where the
11296	contents of guest VRAM are copied to the memory buffer provided by
11297	the implementation every time a display update occurs.
11298
11299	It is important to note that the direct mode is really fast only when
11300	the implementation uses the given guest VRAM buffer directly, for
11301	example, by blitting it to the window representing the virtual machine's
11302	display, which saves at least one copy operation comparing to the
11303	indirect mode. However, using the guest VRAM buffer directly is not
11304	always possible: the format and the color depth of this buffer may be
11305	not supported by the target window, or it may be unknown (opaque) as in
11306	case of text or non-linear multi-plane VGA video modes. In this case,
11307	the indirect mode (that is always available) should be used as a
11308	fallback: when the guest VRAM contents are copied to the
11309	implementation-provided memory buffer, color and format conversion is
11310	done automatically by the underlying code.
11311
11312	The @a pixelFormat parameter defines whether the direct mode is
11313	available or not. If @a pixelFormat is <link
11314	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
11315	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
11316	@a bytesPerLine parameters must be ignored and the implementation must use
11317	the indirect mode (where it provides its own buffer in one of the
11318	supported formats). In all other cases, @a pixelFormat together with
11319	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
11320	buffer pointed to by the @a VRAM parameter and the implementation is
11321	free to choose which mode to use. To indicate that this frame buffer uses
11322	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
11323	attribute must return @c true and <link to="#address"/> must
11324	return exactly the same address that is passed in the @a VRAM parameter
11325	of this method; otherwise it is assumed that the indirect strategy is
11326	chosen.
11327
11328	The @a width and @a height parameters represent the size of the
11329	requested display mode in both modes. In case of indirect mode, the
11330	provided memory buffer should be big enough to store data of the given
11331	display mode. In case of direct mode, it is guaranteed that the given
11332	@a VRAM buffer contains enough space to represent the display mode of the
11333	given size. Note that this frame buffer's <link to="#width"/> and <link
11334	to="#height"/> attributes must return exactly the same values as
11335	passed to this method after the resize is completed (see below).
11336
11337	The @a finished output parameter determines if the implementation has
11338	finished resizing the frame buffer or not. If, for some reason, the
11339	resize cannot be finished immediately during this call, @a finished
11340	must be set to @c false, and the implementation must call
11341	<link to="IDisplay::resizeCompleted"/> after it has returned from
11342	this method as soon as possible. If @a finished is @c false, the
11343	machine will not call any frame buffer methods until
11344	<link to="IDisplay::resizeCompleted"/> is called.
11345
11346	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
11347	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
11348	this frame buffer must return exactly the same values as specified in the
11349	parameters of this method, after the resize is completed. If the
11350	indirect mode is chosen, these attributes must return values describing
11351	the format of the implementation's own memory buffer <link
11352	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
11353	value must always correlate with <link to="#pixelFormat"/>. Note that
11354	the <link to="#pixelFormat"/> attribute must never return <link
11355	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
11356
11357	<note>
11358	This method is called by the IDisplay object under the
11359	<link to="#lock"/> provided by this IFramebuffer
11360	implementation. If this method returns @c false in @a finished, then
11361	this lock is not released until
11362	<link to="IDisplay::resizeCompleted"/> is called.
11363	</note>
11364	</desc>
11365	<param name="screenId" type="unsigned long" dir="in">
11366	<desc>
11367	Logical screen number. Must be used in the corresponding call to
11368	<link to="IDisplay::resizeCompleted"/> if this call is made.
11369	</desc>
11370	</param>
11371	<param name="pixelFormat" type="unsigned long" dir="in">
11372	<desc>
11373	Pixel format of the memory buffer pointed to by @a VRAM.
11374	See also <link to="FramebufferPixelFormat"/>.
11375	</desc>
11376	</param>
11377	<param name="VRAM" type="octet" mod="ptr" dir="in">
11378	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
11379	</param>
11380	<param name="bitsPerPixel" type="unsigned long" dir="in">
11381	<desc>Color depth, bits per pixel.</desc>
11382	</param>
11383	<param name="bytesPerLine" type="unsigned long" dir="in">
11384	<desc>Size of one scan line, in bytes.</desc>
11385	</param>
11386	<param name="width" type="unsigned long" dir="in">
11387	<desc>Width of the guest display, in pixels.</desc>
11388	</param>
11389	<param name="height" type="unsigned long" dir="in">
11390	<desc>Height of the guest display, in pixels.</desc>
11391	</param>
11392	<param name="finished" type="boolean" dir="return">
11393	<desc>
11394	Can the VM start using the new frame buffer immediately
11395	after this method returns or it should wait for
11396	<link to="IDisplay::resizeCompleted"/>.
11397	</desc>
11398	</param>
11399	</method>
11400
11401	<method name="videoModeSupported">
11402	<desc>
11403	Returns whether the frame buffer implementation is willing to
11404	support a given video mode. In case it is not able to render
11405	the video mode (or for some reason not willing), it should
11406	return @c false. Usually this method is called when the guest
11407	asks the VMM device whether a given video mode is supported
11408	so the information returned is directly exposed to the guest.
11409	It is important that this method returns very quickly.
11410	</desc>
11411	<param name="width" type="unsigned long" dir="in"/>
11412	<param name="height" type="unsigned long" dir="in"/>
11413	<param name="bpp" type="unsigned long" dir="in"/>
11414	<param name="supported" type="boolean" dir="return"/>
11415	</method>
11416
11417	<method name="getVisibleRegion">
11418	<desc>
11419	Returns the visible region of this frame buffer.
11420
11421	If the @a rectangles parameter is @c null then the value of the
11422	@a count parameter is ignored and the number of elements necessary to
11423	describe the current visible region is returned in @a countCopied.
11424
11425	If @a rectangles is not @c null but @a count is less
11426	than the required number of elements to store region data, the method
11427	will report a failure. If @a count is equal or greater than the
11428	required number of elements, then the actual number of elements copied
11429	to the provided array will be returned in @a countCopied.
11430
11431	<note>
11432	The address of the provided array must be in the process space of
11433	this IFramebuffer object.
11434	</note>
11435	<note>
11436	Method not yet implemented.
11437	</note>
11438	</desc>
11439	<param name="rectangles" type="octet" mod="ptr" dir="in">
11440	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
11441	</param>
11442	<param name="count" type="unsigned long" dir="in">
11443	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11444	</param>
11445	<param name="countCopied" type="unsigned long" dir="return">
11446	<desc>Number of elements copied to the @a rectangles array.</desc>
11447	</param>
11448	</method>
11449
11450	<method name="setVisibleRegion">
11451	<desc>
11452	Suggests a new visible region to this frame buffer. This region
11453	represents the area of the VM display which is a union of regions of
11454	all top-level windows of the guest operating system running inside the
11455	VM (if the Guest Additions for this system support this
11456	functionality). This information may be used by the frontends to
11457	implement the seamless desktop integration feature.
11458
11459	<note>
11460	The address of the provided array must be in the process space of
11461	this IFramebuffer object.
11462	</note>
11463	<note>
11464	The IFramebuffer implementation must make a copy of the provided
11465	array of rectangles.
11466	</note>
11467	<note>
11468	Method not yet implemented.
11469	</note>
11470	</desc>
11471	<param name="rectangles" type="octet" mod="ptr" dir="in">
11472	<desc>Pointer to the @c RTRECT array.</desc>
11473	</param>
11474	<param name="count" type="unsigned long" dir="in">
11475	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11476	</param>
11477	</method>
11478
11479	<method name="processVHWACommand">
11480	<desc>
11481	Posts a Video HW Acceleration Command to the frame buffer for processing.
11482	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
11483	are posted from quest to the host to be processed by the host hardware.
11484
11485	<note>
11486	The address of the provided command must be in the process space of
11487	this IFramebuffer object.
11488	</note>
11489	</desc>
11490
11491	<param name="command" type="octet" mod="ptr" dir="in">
11492	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
11493	</param>
11494	</method>
11495
11496	</interface>
11497
11498	<interface
11499	name="IFramebufferOverlay" extends="IFramebuffer"
11500	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
11501	wsmap="suppress"
11502	>
11503	<desc>
11504	The IFramebufferOverlay interface represents an alpha blended overlay
11505	for displaying status icons above an IFramebuffer. It is always created
11506	not visible, so that it must be explicitly shown. It only covers a
11507	portion of the IFramebuffer, determined by its width, height and
11508	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
11509	that order) format, and may be written to directly. Do re-read the
11510	width though, after setting it, as it may be adjusted (increased) to
11511	make it more suitable for the front end.
11512	</desc>
11513	<attribute name="x" type="unsigned long" readonly="yes">
11514	<desc>X position of the overlay, relative to the frame buffer.</desc>
11515	</attribute>
11516
11517	<attribute name="y" type="unsigned long" readonly="yes">
11518	<desc>Y position of the overlay, relative to the frame buffer.</desc>
11519	</attribute>
11520
11521	<attribute name="visible" type="boolean" readonly="no">
11522	<desc>
11523	Whether the overlay is currently visible.
11524	</desc>
11525	</attribute>
11526
11527	<attribute name="alpha" type="unsigned long" readonly="no">
11528	<desc>
11529	The global alpha value for the overlay. This may or may not be
11530	supported by a given front end.
11531	</desc>
11532	</attribute>
11533
11534	<method name="move">
11535	<desc>
11536	Changes the overlay's position relative to the IFramebuffer.
11537	</desc>
11538	<param name="x" type="unsigned long" dir="in"/>
11539	<param name="y" type="unsigned long" dir="in"/>
11540	</method>
11541
11542	</interface>
11543
11544	<interface
11545	name="IDisplay" extends="$unknown"
11546	uuid="1fa79e39-0cc9-4ab3-9df3-ed3e96b42496"
11547	wsmap="managed"
11548	>
11549	<desc>
11550	The IDisplay interface represents the virtual machine's display.
11551
11552	The object implementing this interface is contained in each
11553	<link to="IConsole::display"/> attribute and represents the visual
11554	output of the virtual machine.
11555
11556	The virtual display supports pluggable output targets represented by the
11557	IFramebuffer interface. Examples of the output target are a window on
11558	the host computer or an RDP session's display on a remote computer.
11559	</desc>
11560	<method name="getScreenResolution">
11561	<desc>Queries display width, height and color depth for given screen.</desc>
11562	<param name="screenId" type="unsigned long" dir="in"/>
11563	<param name="width" type="unsigned long" dir="out"/>
11564	<param name="height" type="unsigned long" dir="out"/>
11565	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
11566	</method>
11567
11568	<method name="setFramebuffer">
11569	<desc>
11570	Sets the framebuffer for given screen.
11571	</desc>
11572	<param name="screenId" type="unsigned long" dir="in"/>
11573	<param name="framebuffer" type="IFramebuffer" dir="in"/>
11574	</method>
11575
11576	<method name="getFramebuffer">
11577	<desc>
11578	Queries the framebuffer for given screen.
11579	</desc>
11580	<param name="screenId" type="unsigned long" dir="in"/>
11581	<param name="framebuffer" type="IFramebuffer" dir="out"/>
11582	<param name="xOrigin" type="long" dir="out"/>
11583	<param name="yOrigin" type="long" dir="out"/>
11584	</method>
11585
11586	<method name="setVideoModeHint">
11587	<desc>
11588	Asks VirtualBox to request the given video mode from
11589	the guest. This is just a hint and it cannot be guaranteed
11590	that the requested resolution will be used. Guest Additions
11591	are required for the request to be seen by guests. The caller
11592	should issue the request and wait for a resolution change and
11593	after a timeout retry.
11594
11595	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
11596	parameters means that the corresponding values should be taken from the
11597	current video mode (i.e. left unchanged).
11598
11599	If the guest OS supports multi-monitor configuration then the @a display
11600	parameter specifies the number of the guest display to send the hint to:
11601	@c 0 is the primary display, @c 1 is the first secondary and
11602	so on. If the multi-monitor configuration is not supported, @a display
11603	must be @c 0.
11604
11605	<result name="E_INVALIDARG">
11606	The @a display is not associated with any monitor.
11607	</result>
11608
11609	</desc>
11610	<param name="width" type="unsigned long" dir="in"/>
11611	<param name="height" type="unsigned long" dir="in"/>
11612	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
11613	<param name="display" type="unsigned long" dir="in"/>
11614	</method>
11615
11616	<method name="setSeamlessMode">
11617	<desc>
11618	Enables or disables seamless guest display rendering (seamless desktop
11619	integration) mode.
11620	<note>
11621	Calling this method has no effect if <link
11622	to="IGuest::supportsSeamless"/> returns @c false.
11623	</note>
11624	</desc>
11625	<param name="enabled" type="boolean" dir="in"/>
11626	</method>
11627
11628	<method name="takeScreenShot">
11629	<desc>
11630	Takes a screen shot of the requested size and copies it to the
11631	32-bpp buffer allocated by the caller and pointed to by @a address.
11632	A pixel consists of 4 bytes in order: B, G, R, 0.
11633
11634	<note>This API can be used only by the COM/XPCOM C++ API as it
11635	requires pointer support. Use <link to="#takeScreenShotToArray" />
11636	with other language bindings.
11637	</note>
11638
11639	<result name="E_NOTIMPL">
11640	Feature not implemented.
11641	</result>
11642	<result name="VBOX_E_IPRT_ERROR">
11643	Could not take a screenshot.
11644	</result>
11645
11646	</desc>
11647	<param name="screenId" type="unsigned long" dir="in"/>
11648	<param name="address" type="octet" mod="ptr" dir="in"/>
11649	<param name="width" type="unsigned long" dir="in"/>
11650	<param name="height" type="unsigned long" dir="in"/>
11651	</method>
11652
11653	<method name="takeScreenShotToArray">
11654	<desc>
11655	Takes a guest screen shot of the requested size and returns it as
11656	an array of bytes in uncompressed 32-bit RGBA format.
11657	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
11658
11659	This API is slow, but could be the only option to get guest screenshot
11660	for scriptable languages not allowed to manipulate with addresses
11661	directly.
11662
11663	<result name="E_NOTIMPL">
11664	Feature not implemented.
11665	</result>
11666	<result name="VBOX_E_IPRT_ERROR">
11667	Could not take a screenshot.
11668	</result>
11669	</desc>
11670	<param name="screenId" type="unsigned long" dir="in">
11671	<desc>
11672	Monitor to take screenshot from.
11673	</desc>
11674	</param>
11675	<param name="width" type="unsigned long" dir="in">
11676	<desc>
11677	Desired image width.
11678	</desc>
11679	</param>
11680	<param name="height" type="unsigned long" dir="in">
11681	<desc>
11682	Desired image height.
11683	</desc>
11684	</param>
11685	<param name="screenData" type="octet" dir="return" safearray="yes">
11686	<desc>
11687	Array with resulting screen data.
11688	</desc>
11689	</param>
11690	</method>
11691
11692	<method name="drawToScreen">
11693	<desc>
11694	Draws a 32-bpp image of the specified size from the given buffer
11695	to the given point on the VM display.
11696
11697	<result name="E_NOTIMPL">
11698	Feature not implemented.
11699	</result>
11700	<result name="VBOX_E_IPRT_ERROR">
11701	Could not draw to screen.
11702	</result>
11703
11704	</desc>
11705	<param name="screenId" type="unsigned long" dir="in"/>
11706	<param name="address" type="octet" mod="ptr" dir="in"/>
11707	<param name="x" type="unsigned long" dir="in">
11708	<desc>Relative to the screen top left corner.</desc>
11709	</param>
11710	<param name="y" type="unsigned long" dir="in">
11711	<desc>Relative to the screen top left corner.</desc>
11712	</param>
11713	<param name="width" type="unsigned long" dir="in"/>
11714	<param name="height" type="unsigned long" dir="in"/>
11715	</method>
11716
11717	<method name="invalidateAndUpdate">
11718	<desc>
11719	Does a full invalidation of the VM display and instructs the VM
11720	to update it.
11721
11722	<result name="VBOX_E_IPRT_ERROR">
11723	Could not invalidate and update screen.
11724	</result>
11725
11726	</desc>
11727	</method>
11728
11729	<method name="resizeCompleted">
11730	<desc>
11731	Signals that a framebuffer has completed the resize operation.
11732
11733	<result name="VBOX_E_NOT_SUPPORTED">
11734	Operation only valid for external frame buffers.
11735	</result>
11736
11737	</desc>
11738	<param name="screenId" type="unsigned long" dir="in"/>
11739	</method>
11740
11741	<method name="completeVHWACommand">
11742	<desc>
11743	Signals that the Video HW Acceleration command has completed.
11744	</desc>
11745
11746	<param name="command" type="octet" mod="ptr" dir="in">
11747	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
11748	</param>
11749	</method>
11750
11751	</interface>
11752
11753	<!--
11754	// INetworkAdapter
11755	/////////////////////////////////////////////////////////////////////////
11756	-->
11757
11758	<enum
11759	name="NetworkAttachmentType"
11760	uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
11761	>
11762	<desc>
11763	Network attachment type.
11764	</desc>
11765
11766	<const name="Null" value="0">
11767	<desc>Null value, also means "not attached".</desc>
11768	</const>
11769	<const name="NAT" value="1"/>
11770	<const name="Bridged" value="2"/>
11771	<const name="Internal" value="3"/>
11772	<const name="HostOnly" value="4"/>
11773	<const name="VDE" value="5"/>
11774	</enum>
11775
11776	<enum
11777	name="NetworkAdapterType"
11778	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
11779	>
11780	<desc>
11781	Network adapter type.
11782	</desc>
11783
11784	<const name="Null" value="0">
11785	<desc>Null value (never used by the API).</desc>
11786	</const>
11787	<const name="Am79C970A" value="1">
11788	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
11789	</const>
11790	<const name="Am79C973" value="2">
11791	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
11792	</const>
11793	<const name="I82540EM" value="3">
11794	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
11795	</const>
11796	<const name="I82543GC" value="4">
11797	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
11798	</const>
11799	<const name="I82545EM" value="5">
11800	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
11801	</const>
11802	<const name="Virtio" value="6">
11803	<desc>Virtio network device.</desc>
11804	</const>
11805	</enum>
11806
11807	<interface
11808	name="INetworkAdapter" extends="$unknown"
11809	uuid="5bdb9df8-a5e1-4322-a139-b7a4a734c790"
11810	wsmap="managed"
11811	>
11812	<desc>
11813	Represents a virtual network adapter that is attached to a virtual machine.
11814	Each virtual machine has a fixed number of network adapter slots with one
11815	instance of this attached to each of them. Call
11816	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
11817	is attached to a given slot in a given machine.
11818
11819	Each network adapter can be in one of five attachment modes, which are
11820	represented by the <link to="NetworkAttachmentType" /> enumeration;
11821	see the <link to="#attachmentType" /> attribute.
11822	</desc>
11823
11824	<attribute name="adapterType" type="NetworkAdapterType">
11825	<desc>
11826	Type of the virtual network adapter. Depending on this value,
11827	VirtualBox will provide a different virtual network hardware
11828	to the guest.
11829	</desc>
11830	</attribute>
11831
11832	<attribute name="slot" type="unsigned long" readonly="yes">
11833	<desc>
11834	Slot number this adapter is plugged into. Corresponds to
11835	the value you pass to <link to="IMachine::getNetworkAdapter"/>
11836	to obtain this instance.
11837	</desc>
11838	</attribute>
11839
11840	<attribute name="enabled" type="boolean">
11841	<desc>
11842	Flag whether the network adapter is present in the
11843	guest system. If disabled, the virtual guest hardware will
11844	not contain this network adapter. Can only be changed when
11845	the VM is not running.
11846	</desc>
11847	</attribute>
11848
11849	<attribute name="MACAddress" type="wstring">
11850	<desc>
11851	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
11852	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
11853	</desc>
11854	</attribute>
11855
11856	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
11857
11858	<attribute name="hostInterface" type="wstring">
11859	<desc>
11860	Name of the host network interface the VM is attached to.
11861	</desc>
11862	</attribute>
11863
11864	<attribute name="internalNetwork" type="wstring">
11865	<desc>
11866	Name of the internal network the VM is attached to.
11867	</desc>
11868	</attribute>
11869
11870	<attribute name="NATNetwork" type="wstring">
11871	<desc>
11872	Name of the NAT network the VM is attached to.
11873	</desc>
11874	</attribute>
11875
11876	<attribute name="VDENetwork" type="wstring">
11877	<desc>
11878	Name of the VDE switch the VM is attached to.
11879	</desc>
11880	</attribute>
11881
11882	<attribute name="cableConnected" type="boolean">
11883	<desc>
11884	Flag whether the adapter reports the cable as connected or not.
11885	It can be used to report offline situations to a VM.
11886	</desc>
11887	</attribute>
11888
11889	<attribute name="lineSpeed" type="unsigned long">
11890	<desc>
11891	Line speed reported by custom drivers, in units of 1 kbps.
11892	</desc>
11893	</attribute>
11894
11895	<attribute name="traceEnabled" type="boolean">
11896	<desc>
11897	Flag whether network traffic from/to the network card should be traced.
11898	Can only be toggled when the VM is turned off.
11899	</desc>
11900	</attribute>
11901
11902	<attribute name="traceFile" type="wstring">
11903	<desc>
11904	Filename where a network trace will be stored. If not set, VBox-pid.pcap
11905	will be used.
11906	</desc>
11907	</attribute>
11908
11909	<attribute name="natDriver" type="INATEngine" readonly="yes">
11910	<desc>
11911	Points to the NAT engine which handles the network address translation
11912	for this interface. This is active only when the interface actually uses
11913	NAT (see <link to="#attachToNAT" />).
11914	</desc>
11915	</attribute>
11916
11917	<attribute name="bootPriority" type="unsigned long">
11918	<desc>
11919	Network boot priority of the adapter. Priority 1 is highest. If not set,
11920	the priority is considered to be at the lowest possible setting.
11921	</desc>
11922	</attribute>
11923
11924	<method name="attachToNAT">
11925	<desc>
11926	Attach the network adapter to the Network Address Translation (NAT) interface.
11927	</desc>
11928	</method>
11929
11930	<method name="attachToBridgedInterface">
11931	<desc>
11932	Attach the network adapter to a bridged host interface.
11933	</desc>
11934	</method>
11935
11936	<method name="attachToInternalNetwork">
11937	<desc>
11938	Attach the network adapter to an internal network.
11939	</desc>
11940	</method>
11941
11942	<method name="attachToHostOnlyInterface">
11943	<desc>
11944	Attach the network adapter to the host-only network.
11945	</desc>
11946	</method>
11947
11948	<method name="attachToVDE">
11949	<desc>
11950	Attach the network adapter to a VDE network.
11951	</desc>
11952	</method>
11953
11954	<method name="detach">
11955	<desc>
11956	Detach the network adapter
11957	</desc>
11958	</method>
11959	</interface>
11960
11961
11962	<!--
11963	// ISerialPort
11964	/////////////////////////////////////////////////////////////////////////
11965	-->
11966
11967	<enum
11968	name="PortMode"
11969	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
11970	>
11971	<desc>
11972	The PortMode enumeration represents possible communication modes for
11973	the virtual serial port device.
11974	</desc>
11975
11976	<const name="Disconnected" value="0">
11977	<desc>Virtual device is not attached to any real host device.</desc>
11978	</const>
11979	<const name="HostPipe" value="1">
11980	<desc>Virtual device is attached to a host pipe.</desc>
11981	</const>
11982	<const name="HostDevice" value="2">
11983	<desc>Virtual device is attached to a host device.</desc>
11984	</const>
11985	<const name="RawFile" value="3">
11986	<desc>Virtual device is attached to a raw file.</desc>
11987	</const>
11988	</enum>
11989
11990	<interface
11991	name="ISerialPort" extends="$unknown"
11992	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
11993	wsmap="managed"
11994	>
11995
11996	<desc>
11997	The ISerialPort interface represents the virtual serial port device.
11998
11999	The virtual serial port device acts like an ordinary serial port
12000	inside the virtual machine. This device communicates to the real
12001	serial port hardware in one of two modes: host pipe or host device.
12002
12003	In host pipe mode, the #path attribute specifies the path to the pipe on
12004	the host computer that represents a serial port. The #server attribute
12005	determines if this pipe is created by the virtual machine process at
12006	machine startup or it must already exist before starting machine
12007	execution.
12008
12009	In host device mode, the #path attribute specifies the name of the
12010	serial port device on the host computer.
12011
12012	There is also a third communication mode: the disconnected mode. In this
12013	mode, the guest OS running inside the virtual machine will be able to
12014	detect the serial port, but all port write operations will be discarded
12015	and all port read operations will return no data.
12016
12017	<see>IMachine::getSerialPort</see>
12018	</desc>
12019
12020	<attribute name="slot" type="unsigned long" readonly="yes">
12021	<desc>
12022	Slot number this serial port is plugged into. Corresponds to
12023	the value you pass to <link to="IMachine::getSerialPort"/>
12024	to obtain this instance.
12025	</desc>
12026	</attribute>
12027
12028	<attribute name="enabled" type="boolean">
12029	<desc>
12030	Flag whether the serial port is enabled. If disabled,
12031	the serial port will not be reported to the guest OS.
12032	</desc>
12033	</attribute>
12034
12035	<attribute name="IOBase" type="unsigned long">
12036	<desc>Base I/O address of the serial port.</desc>
12037	</attribute>
12038
12039	<attribute name="IRQ" type="unsigned long">
12040	<desc>IRQ number of the serial port.</desc>
12041	</attribute>
12042
12043	<attribute name="hostMode" type="PortMode">
12044	<desc>
12045	How is this port connected to the host.
12046	<note>
12047	Changing this attribute may fail if the conditions for
12048	<link to="#path"/> are not met.
12049	</note>
12050	</desc>
12051	</attribute>
12052
12053	<attribute name="server" type="boolean">
12054	<desc>
12055	Flag whether this serial port acts as a server (creates a new pipe on
12056	the host) or as a client (uses the existing pipe). This attribute is
12057	used only when <link to="#hostMode"/> is PortMode_HostPipe.
12058	</desc>
12059	</attribute>
12060
12061	<attribute name="path" type="wstring">
12062	<desc>
12063	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
12064	PortMode_HostPipe, or the host serial device name when
12065	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
12066	cases, setting a @c null or empty string as the attribute's value
12067	is an error. Otherwise, the value of this property is ignored.
12068	</desc>
12069	</attribute>
12070
12071	</interface>
12072
12073	<!--
12074	// IParallelPort
12075	/////////////////////////////////////////////////////////////////////////
12076	-->
12077
12078	<interface
12079	name="IParallelPort" extends="$unknown"
12080	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
12081	wsmap="managed"
12082	>
12083
12084	<desc>
12085	The IParallelPort interface represents the virtual parallel port device.
12086
12087	The virtual parallel port device acts like an ordinary parallel port
12088	inside the virtual machine. This device communicates to the real
12089	parallel port hardware using the name of the parallel device on the host
12090	computer specified in the #path attribute.
12091
12092	Each virtual parallel port device is assigned a base I/O address and an
12093	IRQ number that will be reported to the guest operating system and used
12094	to operate the given parallel port from within the virtual machine.
12095
12096	<see>IMachine::getParallelPort</see>
12097	</desc>
12098
12099	<attribute name="slot" type="unsigned long" readonly="yes">
12100	<desc>
12101	Slot number this parallel port is plugged into. Corresponds to
12102	the value you pass to <link to="IMachine::getParallelPort"/>
12103	to obtain this instance.
12104	</desc>
12105	</attribute>
12106
12107	<attribute name="enabled" type="boolean">
12108	<desc>
12109	Flag whether the parallel port is enabled. If disabled,
12110	the parallel port will not be reported to the guest OS.
12111	</desc>
12112	</attribute>
12113
12114	<attribute name="IOBase" type="unsigned long">
12115	<desc>Base I/O address of the parallel port.</desc>
12116	</attribute>
12117
12118	<attribute name="IRQ" type="unsigned long">
12119	<desc>IRQ number of the parallel port.</desc>
12120	</attribute>
12121
12122	<attribute name="path" type="wstring">
12123	<desc>
12124	Host parallel device name. If this parallel port is enabled, setting a
12125	@c null or an empty string as this attribute's value will result into
12126	an error.
12127	</desc>
12128	</attribute>
12129
12130	</interface>
12131
12132
12133	<!--
12134	// IMachineDebugger
12135	/////////////////////////////////////////////////////////////////////////
12136	-->
12137
12138	<interface
12139	name="IMachineDebugger" extends="$unknown"
12140	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
12141	wsmap="suppress"
12142	>
12143	<method name="resetStats">
12144	<desc>
12145	Reset VM statistics.
12146	</desc>
12147	<param name="pattern" type="wstring" dir="in">
12148	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12149	</param>
12150	</method>
12151
12152	<method name="dumpStats">
12153	<desc>
12154	Dumps VM statistics.
12155	</desc>
12156	<param name="pattern" type="wstring" dir="in">
12157	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12158	</param>
12159	</method>
12160
12161	<method name="getStats">
12162	<desc>
12163	Get the VM statistics in a XMLish format.
12164	</desc>
12165	<param name="pattern" type="wstring" dir="in">
12166	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12167	</param>
12168	<param name="withDescriptions" type="boolean" dir="in">
12169	<desc>Whether to include the descriptions.</desc>
12170	</param>
12171	<param name="stats" type="wstring" dir="out">
12172	<desc>The XML document containing the statistics.</desc>
12173	</param>
12174	</method>
12175
12176	<method name="injectNMI">
12177	<desc>
12178	Inject an NMI into a running VT-x/AMD-V VM.
12179	</desc>
12180	</method>
12181
12182	<attribute name="singlestep" type="boolean">
12183	<desc>Switch for enabling singlestepping.</desc>
12184	</attribute>
12185
12186	<attribute name="recompileUser" type="boolean">
12187	<desc>Switch for forcing code recompilation for user mode code.</desc>
12188	</attribute>
12189
12190	<attribute name="recompileSupervisor" type="boolean">
12191	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
12192	</attribute>
12193
12194	<attribute name="PATMEnabled" type="boolean">
12195	<desc>Switch for enabling and disabling the PATM component.</desc>
12196	</attribute>
12197
12198	<attribute name="CSAMEnabled" type="boolean">
12199	<desc>Switch for enabling and disabling the CSAM component.</desc>
12200	</attribute>
12201
12202	<attribute name="logEnabled" type="boolean">
12203	<desc>Switch for enabling and disabling logging.</desc>
12204	</attribute>
12205
12206	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
12207	<desc>
12208	Flag indicating whether the VM is currently making use of CPU hardware
12209	virtualization extensions.
12210	</desc>
12211	</attribute>
12212
12213	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
12214	<desc>
12215	Flag indicating whether the VM is currently making use of the nested paging
12216	CPU hardware virtualization extension.
12217	</desc>
12218	</attribute>
12219
12220	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
12221	<desc>
12222	Flag indicating whether the VM is currently making use of the VPID
12223	VT-x extension.
12224	</desc>
12225	</attribute>
12226
12227	<attribute name="PAEEnabled" type="boolean" readonly="yes">
12228	<desc>
12229	Flag indicating whether the VM is currently making use of the Physical
12230	Address Extension CPU feature.
12231	</desc>
12232	</attribute>
12233
12234	<attribute name="virtualTimeRate" type="unsigned long">
12235	<desc>
12236	The rate at which the virtual time runs expressed as a percentage.
12237	The accepted range is 2% to 20000%.
12238	</desc>
12239	</attribute>
12240
12241	<!-- @todo method for setting log flags, groups and destination! -->
12242
12243	<attribute name="VM" type="unsigned long long" readonly="yes">
12244	<desc>
12245	Gets the VM handle. This is only for internal use while
12246	we carve the details of this interface.
12247	</desc>
12248	</attribute>
12249
12250	</interface>
12251
12252	<!--
12253	// IUSBController
12254	/////////////////////////////////////////////////////////////////////////
12255	-->
12256
12257	<interface
12258	name="IUSBController" extends="$unknown"
12259	uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
12260	wsmap="managed"
12261	>
12262	<attribute name="enabled" type="boolean">
12263	<desc>
12264	Flag whether the USB controller is present in the
12265	guest system. If disabled, the virtual guest hardware will
12266	not contain any USB controller. Can only be changed when
12267	the VM is powered off.
12268	</desc>
12269	</attribute>
12270
12271	<attribute name="enabledEhci" type="boolean">
12272	<desc>
12273	Flag whether the USB EHCI controller is present in the
12274	guest system. If disabled, the virtual guest hardware will
12275	not contain a USB EHCI controller. Can only be changed when
12276	the VM is powered off.
12277	</desc>
12278	</attribute>
12279
12280	<attribute name="proxyAvailable" type="boolean" readonly="yes">
12281	<desc>
12282	Flag whether there is an USB proxy available.
12283	</desc>
12284	</attribute>
12285
12286	<attribute name="USBStandard" type="unsigned short" readonly="yes">
12287	<desc>
12288	USB standard version which the controller implements.
12289	This is a BCD which means that the major version is in the
12290	high byte and minor version is in the low byte.
12291	</desc>
12292	</attribute>
12293
12294	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
12295	<desc>
12296	List of USB device filters associated with the machine.
12297
12298	If the machine is currently running, these filters are activated
12299	every time a new (supported) USB device is attached to the host
12300	computer that was not ignored by global filters
12301	(<link to="IHost::USBDeviceFilters"/>).
12302
12303	These filters are also activated when the machine is powered up.
12304	They are run against a list of all currently available USB
12305	devices (in states
12306	<link to="USBDeviceState_Available"/>,
12307	<link to="USBDeviceState_Busy"/>,
12308	<link to="USBDeviceState_Held"/>) that were not previously
12309	ignored by global filters.
12310
12311	If at least one filter matches the USB device in question, this
12312	device is automatically captured (attached to) the virtual USB
12313	controller of this machine.
12314
12315	<see>IUSBDeviceFilter, ::IUSBController</see>
12316	</desc>
12317	</attribute>
12318
12319	<method name="createDeviceFilter">
12320	<desc>
12321	Creates a new USB device filter. All attributes except
12322	the filter name are set to empty (any match),
12323	<i>active</i> is @c false (the filter is not active).
12324
12325	The created filter can then be added to the list of filters using
12326	<link to="#insertDeviceFilter"/>.
12327
12328	<result name="VBOX_E_INVALID_VM_STATE">
12329	The virtual machine is not mutable.
12330	</result>
12331
12332	<see>#deviceFilters</see>
12333	</desc>
12334	<param name="name" type="wstring" dir="in">
12335	<desc>
12336	Filter name. See <link to="IUSBDeviceFilter::name"/>
12337	for more info.
12338	</desc>
12339	</param>
12340	<param name="filter" type="IUSBDeviceFilter" dir="return">
12341	<desc>Created filter object.</desc>
12342	</param>
12343	</method>
12344
12345	<method name="insertDeviceFilter">
12346	<desc>
12347	Inserts the given USB device to the specified position
12348	in the list of filters.
12349
12350	Positions are numbered starting from <tt>0</tt>. If the specified
12351	position is equal to or greater than the number of elements in
12352	the list, the filter is added to the end of the collection.
12353
12354	<note>
12355	Duplicates are not allowed, so an attempt to insert a
12356	filter that is already in the collection, will return an
12357	error.
12358	</note>
12359
12360	<result name="VBOX_E_INVALID_VM_STATE">
12361	Virtual machine is not mutable.
12362	</result>
12363	<result name="E_INVALIDARG">
12364	USB device filter not created within this VirtualBox instance.
12365	</result>
12366	<result name="VBOX_E_INVALID_OBJECT_STATE">
12367	USB device filter already in list.
12368	</result>
12369
12370	<see>#deviceFilters</see>
12371	</desc>
12372	<param name="position" type="unsigned long" dir="in">
12373	<desc>Position to insert the filter to.</desc>
12374	</param>
12375	<param name="filter" type="IUSBDeviceFilter" dir="in">
12376	<desc>USB device filter to insert.</desc>
12377	</param>
12378	</method>
12379
12380	<method name="removeDeviceFilter">
12381	<desc>
12382	Removes a USB device filter from the specified position in the
12383	list of filters.
12384
12385	Positions are numbered starting from <tt>0</tt>. Specifying a
12386	position equal to or greater than the number of elements in
12387	the list will produce an error.
12388
12389	<see>#deviceFilters</see>
12390
12391	<result name="VBOX_E_INVALID_VM_STATE">
12392	Virtual machine is not mutable.
12393	</result>
12394	<result name="E_INVALIDARG">
12395	USB device filter list empty or invalid @a position.
12396	</result>
12397
12398	</desc>
12399	<param name="position" type="unsigned long" dir="in">
12400	<desc>Position to remove the filter from.</desc>
12401	</param>
12402	<param name="filter" type="IUSBDeviceFilter" dir="return">
12403	<desc>Removed USB device filter.</desc>
12404	</param>
12405	</method>
12406
12407	</interface>
12408
12409
12410	<!--
12411	// IUSBDevice
12412	/////////////////////////////////////////////////////////////////////////
12413	-->
12414
12415	<interface
12416	name="IUSBDevice" extends="$unknown"
12417	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
12418	wsmap="managed"
12419	>
12420	<desc>
12421	The IUSBDevice interface represents a virtual USB device attached to the
12422	virtual machine.
12423
12424	A collection of objects implementing this interface is stored in the
12425	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
12426	attached to a running virtual machine's USB controller.
12427	</desc>
12428
12429	<attribute name="id" type="uuid" mod="string" readonly="yes">
12430	<desc>
12431	Unique USB device ID. This ID is built from #vendorId,
12432	#productId, #revision and #serialNumber.
12433	</desc>
12434	</attribute>
12435
12436	<attribute name="vendorId" type="unsigned short" readonly="yes">
12437	<desc>Vendor ID.</desc>
12438	</attribute>
12439
12440	<attribute name="productId" type="unsigned short" readonly="yes">
12441	<desc>Product ID.</desc>
12442	</attribute>
12443
12444	<attribute name="revision" type="unsigned short" readonly="yes">
12445	<desc>
12446	Product revision number. This is a packed BCD represented as
12447	unsigned short. The high byte is the integer part and the low
12448	byte is the decimal.
12449	</desc>
12450	</attribute>
12451
12452	<attribute name="manufacturer" type="wstring" readonly="yes">
12453	<desc>Manufacturer string.</desc>
12454	</attribute>
12455
12456	<attribute name="product" type="wstring" readonly="yes">
12457	<desc>Product string.</desc>
12458	</attribute>
12459
12460	<attribute name="serialNumber" type="wstring" readonly="yes">
12461	<desc>Serial number string.</desc>
12462	</attribute>
12463
12464	<attribute name="address" type="wstring" readonly="yes">
12465	<desc>Host specific address of the device.</desc>
12466	</attribute>
12467
12468	<attribute name="port" type="unsigned short" readonly="yes">
12469	<desc>
12470	Host USB port number the device is physically
12471	connected to.
12472	</desc>
12473	</attribute>
12474
12475	<attribute name="version" type="unsigned short" readonly="yes">
12476	<desc>
12477	The major USB version of the device - 1 or 2.
12478	</desc>
12479	</attribute>
12480
12481	<attribute name="portVersion" type="unsigned short" readonly="yes">
12482	<desc>
12483	The major USB version of the host USB port the device is
12484	physically connected to - 1 or 2. For devices not connected to
12485	anything this will have the same value as the version attribute.
12486	</desc>
12487	</attribute>
12488
12489	<attribute name="remote" type="boolean" readonly="yes">
12490	<desc>
12491	Whether the device is physically connected to a remote VRDP
12492	client or to a local host machine.
12493	</desc>
12494	</attribute>
12495
12496	</interface>
12497
12498
12499	<!--
12500	// IUSBDeviceFilter
12501	/////////////////////////////////////////////////////////////////////////
12502	-->
12503
12504	<interface
12505	name="IUSBDeviceFilter" extends="$unknown"
12506	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
12507	wsmap="managed"
12508	>
12509	<desc>
12510	The IUSBDeviceFilter interface represents an USB device filter used
12511	to perform actions on a group of USB devices.
12512
12513	This type of filters is used by running virtual machines to
12514	automatically capture selected USB devices once they are physically
12515	attached to the host computer.
12516
12517	A USB device is matched to the given device filter if and only if all
12518	attributes of the device match the corresponding attributes of the
12519	filter (that is, attributes are joined together using the logical AND
12520	operation). On the other hand, all together, filters in the list of
12521	filters carry the semantics of the logical OR operation. So if it is
12522	desirable to create a match like "this vendor id OR this product id",
12523	one needs to create two filters and specify "any match" (see below)
12524	for unused attributes.
12525
12526	All filter attributes used for matching are strings. Each string
12527	is an expression representing a set of values of the corresponding
12528	device attribute, that will match the given filter. Currently, the
12529	following filtering expressions are supported:
12530
12531	<ul>
12532	<li><i>Interval filters</i>. Used to specify valid intervals for
12533	integer device attributes (Vendor ID, Product ID and Revision).
12534	The format of the string is:
12535
12536	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
12537
12538	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
12539	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
12540	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
12541	is omitted before a dash (<tt>-</tt>), the minimum possible integer
12542	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
12543	possible integer is assumed.
12544	</li>
12545	<li><i>Boolean filters</i>. Used to specify acceptable values for
12546	boolean device attributes. The format of the string is:
12547
12548	<tt>true\|false\|yes\|no\|0\|1</tt>
12549
12550	</li>
12551	<li><i>Exact match</i>. Used to specify a single value for the given
12552	device attribute. Any string that doesn't start with <tt>int:</tt>
12553	represents the exact match. String device attributes are compared to
12554	this string including case of symbols. Integer attributes are first
12555	converted to a string (see individual filter attributes) and then
12556	compared ignoring case.
12557
12558	</li>
12559	<li><i>Any match</i>. Any value of the corresponding device attribute
12560	will match the given filter. An empty or @c null string is
12561	used to construct this type of filtering expressions.
12562
12563	</li>
12564	</ul>
12565
12566	<note>
12567	On the Windows host platform, interval filters are not currently
12568	available. Also all string filter attributes
12569	(<link to="#manufacturer"/>, <link to="#product"/>,
12570	<link to="#serialNumber"/>) are ignored, so they behave as
12571	<i>any match</i> no matter what string expression is specified.
12572	</note>
12573
12574	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
12575	</desc>
12576
12577	<attribute name="name" type="wstring">
12578	<desc>
12579	Visible name for this filter.
12580	This name is used to visually distinguish one filter from another,
12581	so it can neither be @c null nor an empty string.
12582	</desc>
12583	</attribute>
12584
12585	<attribute name="active" type="boolean">
12586	<desc>Whether this filter active or has been temporarily disabled.</desc>
12587	</attribute>
12588
12589	<attribute name="vendorId" type="wstring">
12590	<desc>
12591	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
12592	The string representation for the <i>exact matching</i>
12593	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12594	(including leading zeroes).
12595	</desc>
12596	</attribute>
12597
12598	<attribute name="productId" type="wstring">
12599	<desc>
12600	<link to="IUSBDevice::productId">Product ID</link> filter.
12601	The string representation for the <i>exact matching</i>
12602	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12603	(including leading zeroes).
12604	</desc>
12605	</attribute>
12606
12607	<attribute name="revision" type="wstring">
12608	<desc>
12609	<link to="IUSBDevice::productId">Product revision number</link>
12610	filter. The string representation for the <i>exact matching</i>
12611	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
12612	of the integer part of the revision, and <tt>F</tt> is the
12613	decimal digit of its fractional part (including leading and
12614	trailing zeros).
12615	Note that for interval filters, it's best to use the hexadecimal
12616	form, because the revision is stored as a 16 bit packed BCD value;
12617	so the expression <tt>int:0x0100-0x0199</tt> will match any
12618	revision from <tt>1.0</tt> to <tt>1.99</tt>.
12619	</desc>
12620	</attribute>
12621
12622	<attribute name="manufacturer" type="wstring">
12623	<desc>
12624	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
12625	</desc>
12626	</attribute>
12627
12628	<attribute name="product" type="wstring">
12629	<desc>
12630	<link to="IUSBDevice::product">Product</link> filter.
12631	</desc>
12632	</attribute>
12633
12634	<attribute name="serialNumber" type="wstring">
12635	<desc>
12636	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
12637	</desc>
12638	</attribute>
12639
12640	<attribute name="port" type="wstring">
12641	<desc>
12642	<link to="IUSBDevice::port">Host USB port</link> filter.
12643	</desc>
12644	</attribute>
12645
12646	<attribute name="remote" type="wstring">
12647	<desc>
12648	<link to="IUSBDevice::remote">Remote state</link> filter.
12649	<note>
12650	This filter makes sense only for machine USB filters,
12651	i.e. it is ignored by IHostUSBDeviceFilter objects.
12652	</note>
12653	</desc>
12654	</attribute>
12655
12656	<attribute name="maskedInterfaces" type="unsigned long">
12657	<desc>
12658	This is an advanced option for hiding one or more USB interfaces
12659	from the guest. The value is a bit mask where the bits that are set
12660	means the corresponding USB interface should be hidden, masked off
12661	if you like.
12662	This feature only works on Linux hosts.
12663	</desc>
12664	</attribute>
12665
12666	</interface>
12667
12668
12669	<!--
12670	// IHostUSBDevice
12671	/////////////////////////////////////////////////////////////////////////
12672	-->
12673
12674	<enum
12675	name="USBDeviceState"
12676	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
12677	>
12678	<desc>
12679	USB device state. This enumeration represents all possible states
12680	of the USB device physically attached to the host computer regarding
12681	its state on the host computer and availability to guest computers
12682	(all currently running virtual machines).
12683
12684	Once a supported USB device is attached to the host, global USB
12685	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
12686	either ignore the device, or put it to USBDeviceState_Held state, or do
12687	nothing. Unless the device is ignored by global filters, filters of all
12688	currently running guests (<link to="IUSBController::deviceFilters"/>) are
12689	activated that can put it to USBDeviceState_Captured state.
12690
12691	If the device was ignored by global filters, or didn't match
12692	any filters at all (including guest ones), it is handled by the host
12693	in a normal way. In this case, the device state is determined by
12694	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
12695	or USBDeviceState_Available, depending on the current device usage.
12696
12697	Besides auto-capturing based on filters, the device can be manually
12698	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
12699	state is USBDeviceState_Busy, USBDeviceState_Available or
12700	USBDeviceState_Held.
12701
12702	<note>
12703	Due to differences in USB stack implementations in Linux and Win32,
12704	states USBDeviceState_Busy and USBDeviceState_vailable are applicable
12705	only to the Linux version of the product. This also means that (<link
12706	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
12707	device state is USBDeviceState_Held.
12708	</note>
12709
12710	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
12711	</desc>
12712
12713	<const name="NotSupported" value="0">
12714	<desc>
12715	Not supported by the VirtualBox server, not available to guests.
12716	</desc>
12717	</const>
12718	<const name="Unavailable" value="1">
12719	<desc>
12720	Being used by the host computer exclusively,
12721	not available to guests.
12722	</desc>
12723	</const>
12724	<const name="Busy" value="2">
12725	<desc>
12726	Being used by the host computer, potentially available to guests.
12727	</desc>
12728	</const>
12729	<const name="Available" value="3">
12730	<desc>
12731	Not used by the host computer, available to guests (the host computer
12732	can also start using the device at any time).
12733	</desc>
12734	</const>
12735	<const name="Held" value="4">
12736	<desc>
12737	Held by the VirtualBox server (ignored by the host computer),
12738	available to guests.
12739	</desc>
12740	</const>
12741	<const name="Captured" value="5">
12742	<desc>
12743	Captured by one of the guest computers, not available
12744	to anybody else.
12745	</desc>
12746	</const>
12747	</enum>
12748
12749	<interface
12750	name="IHostUSBDevice" extends="IUSBDevice"
12751	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
12752	wsmap="managed"
12753	>
12754	<desc>
12755	The IHostUSBDevice interface represents a physical USB device attached
12756	to the host computer.
12757
12758	Besides properties inherited from IUSBDevice, this interface adds the
12759	<link to="#state"/> property that holds the current state of the USB
12760	device.
12761
12762	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
12763	</desc>
12764
12765	<attribute name="state" type="USBDeviceState" readonly="yes">
12766	<desc>
12767	Current state of the device.
12768	</desc>
12769	</attribute>
12770
12771	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
12772
12773	</interface>
12774
12775
12776	<!--
12777	// IHostUSBDeviceFilter
12778	/////////////////////////////////////////////////////////////////////////
12779	-->
12780
12781	<enum
12782	name="USBDeviceFilterAction"
12783	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
12784	>
12785	<desc>
12786	Actions for host USB device filters.
12787	<see>IHostUSBDeviceFilter, USBDeviceState</see>
12788	</desc>
12789
12790	<const name="Null" value="0">
12791	<desc>Null value (never used by the API).</desc>
12792	</const>
12793	<const name="Ignore" value="1">
12794	<desc>Ignore the matched USB device.</desc>
12795	</const>
12796	<const name="Hold" value="2">
12797	<desc>Hold the matched USB device.</desc>
12798	</const>
12799	</enum>
12800
12801	<interface
12802	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
12803	uuid="4cc70246-d74a-400f-8222-3900489c0374"
12804	wsmap="managed"
12805	>
12806	<desc>
12807	The IHostUSBDeviceFilter interface represents a global filter for a
12808	physical USB device used by the host computer. Used indirectly in
12809	<link to="IHost::USBDeviceFilters"/>.
12810
12811	Using filters of this type, the host computer determines the initial
12812	state of the USB device after it is physically attached to the
12813	host's USB controller.
12814
12815	<note>
12816	The <link to="#remote"/> attribute is ignored by this type of
12817	filters, because it makes sense only for
12818	<link to="IUSBController::deviceFilters">machine USB filters</link>.
12819	</note>
12820
12821	<see>IHost::USBDeviceFilters</see>
12822	</desc>
12823
12824	<attribute name="action" type="USBDeviceFilterAction">
12825	<desc>
12826	Action performed by the host when an attached USB device
12827	matches this filter.
12828	</desc>
12829	</attribute>
12830
12831	</interface>
12832
12833	<!--
12834	// IAudioAdapter
12835	/////////////////////////////////////////////////////////////////////////
12836	-->
12837
12838	<enum
12839	name="AudioDriverType"
12840	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
12841	>
12842	<desc>
12843	Host audio driver type.
12844	</desc>
12845
12846	<const name="Null" value="0">
12847	<desc>Null value, also means "dummy audio driver".</desc>
12848	</const>
12849	<const name="WinMM" value="1">
12850	<desc>Windows multimedia (Windows hosts only).</desc>
12851	</const>
12852	<const name="OSS" value="2">
12853	<desc>Open Sound System (Linux hosts only).</desc>
12854	</const>
12855	<const name="ALSA" value="3">
12856	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
12857	</const>
12858	<const name="DirectSound" value="4">
12859	<desc>DirectSound (Windows hosts only).</desc>
12860	</const>
12861	<const name="CoreAudio" value="5">
12862	<desc>CoreAudio (Mac hosts only).</desc>
12863	</const>
12864	<const name="MMPM" value="6">
12865	<desc>Reserved for historical reasons.</desc>
12866	</const>
12867	<const name="Pulse" value="7">
12868	<desc>PulseAudio (Linux hosts only).</desc>
12869	</const>
12870	<const name="SolAudio" value="8">
12871	<desc>Solaris audio (Solaris hosts only).</desc>
12872	</const>
12873	</enum>
12874
12875	<enum
12876	name="AudioControllerType"
12877	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
12878	>
12879	<desc>
12880	Virtual audio controller type.
12881	</desc>
12882
12883	<const name="AC97" value="0"/>
12884	<const name="SB16" value="1"/>
12885	</enum>
12886
12887	<interface
12888	name="IAudioAdapter" extends="$unknown"
12889	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
12890	wsmap="managed"
12891	>
12892	<desc>
12893	The IAudioAdapter interface represents the virtual audio adapter of
12894	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
12895	</desc>
12896	<attribute name="enabled" type="boolean">
12897	<desc>
12898	Flag whether the audio adapter is present in the
12899	guest system. If disabled, the virtual guest hardware will
12900	not contain any audio adapter. Can only be changed when
12901	the VM is not running.
12902	</desc>
12903	</attribute>
12904	<attribute name="audioController" type="AudioControllerType">
12905	<desc>
12906	The audio hardware we emulate.
12907	</desc>
12908	</attribute>
12909	<attribute name="audioDriver" type="AudioDriverType">
12910	<desc>
12911	Audio driver the adapter is connected to. This setting
12912	can only be changed when the VM is not running.
12913	</desc>
12914	</attribute>
12915	</interface>
12916
12917	<!--
12918	// IVRDPServer
12919	/////////////////////////////////////////////////////////////////////////
12920	-->
12921
12922	<enum
12923	name="VRDPAuthType"
12924	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
12925	>
12926	<desc>
12927	VRDP authentication type.
12928	</desc>
12929
12930	<const name="Null" value="0">
12931	<desc>Null value, also means "no authentication".</desc>
12932	</const>
12933	<const name="External" value="1"/>
12934	<const name="Guest" value="2"/>
12935	</enum>
12936
12937	<interface
12938	name="IVRDPServer" extends="$unknown"
12939	uuid="7aeeb530-0b08-41fe-835d-9be9ec1dbe5c"
12940	wsmap="managed"
12941	>
12942	<attribute name="enabled" type="boolean">
12943	<desc>VRDP server status.</desc>
12944	</attribute>
12945
12946	<attribute name="ports" type="wstring">
12947	<desc>
12948	VRDP server port numbers. The server will try to bind to one of free ports from the list.
12949	<note>
12950	This is a string of comma separated TCP port numbers or port number ranges.
12951	Example <tt>5000,5010-5012,5015</tt>
12952	</note>
12953	</desc>
12954	</attribute>
12955
12956	<attribute name="netAddress" type="wstring">
12957	<desc>VRDP server address.</desc>
12958	</attribute>
12959
12960	<attribute name="authType" type="VRDPAuthType">
12961	<desc>VRDP authentication method.</desc>
12962	</attribute>
12963
12964	<attribute name="authTimeout" type="unsigned long">
12965	<desc>Timeout for guest authentication. Milliseconds.</desc>
12966	</attribute>
12967
12968	<attribute name="allowMultiConnection" type="boolean">
12969	<desc>
12970	Flag whether multiple simultaneous connections to the VM are permitted.
12971	Note that this will be replaced by a more powerful mechanism in the future.
12972	</desc>
12973	</attribute>
12974
12975	<attribute name="reuseSingleConnection" type="boolean">
12976	<desc>
12977	Flag whether the existing connection must be dropped and a new connection
12978	must be established by the VRDP server, when a new client connects in single
12979	connection mode.
12980	</desc>
12981	</attribute>
12982
12983	<attribute name="videoChannel" type="boolean">
12984	<desc>
12985	Flag whether RDP video channel is supported.
12986	</desc>
12987	</attribute>
12988
12989	<attribute name="videoChannelQuality" type="unsigned long">
12990	<desc>
12991	Image quality in percents.
12992	</desc>
12993	</attribute>
12994
12995	</interface>
12996
12997
12998	<!--
12999	// ISharedFolder
13000	/////////////////////////////////////////////////////////////////////////
13001	-->
13002
13003	<interface
13004	name="ISharedFolder" extends="$unknown"
13005	uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
13006	wsmap="struct"
13007	>
13008	<desc>
13009	The ISharedFolder interface represents a folder in the host computer's
13010	file system accessible from the guest OS running inside a virtual
13011	machine using an associated logical name.
13012
13013	There are three types of shared folders:
13014	<ul>
13015	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
13016	folders available to all virtual machines.</li>
13017	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
13018	VM-specific shared folders available to the given virtual machine at
13019	startup.</li>
13020	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
13021	VM-specific shared folders created in the session context (for
13022	example, when the virtual machine is running) and automatically
13023	discarded when the session is closed (the VM is powered off).</li>
13024	</ul>
13025
13026	Logical names of shared folders must be unique within the given scope
13027	(global, permanent or transient). However, they do not need to be unique
13028	across scopes. In this case, the definition of the shared folder in a
13029	more specific scope takes precedence over definitions in all other
13030	scopes. The order of precedence is (more specific to more general):
13031	<ol>
13032	<li>Transient definitions</li>
13033	<li>Permanent definitions</li>
13034	<li>Global definitions</li>
13035	</ol>
13036
13037	For example, if MyMachine has a shared folder named
13038	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
13039	transient shared folder named <tt>C_DRIVE</tt> (that points
13040	to <tt>C:\\\\WINDOWS</tt>) will change the definition
13041	of <tt>C_DRIVE</tt> in the guest OS so
13042	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
13043	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
13044	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
13045	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
13046	to <tt>C:\\</tt> if it still exists.
13047
13048	Note that permanent and transient shared folders of different machines
13049	are in different name spaces, so they don't overlap and don't need to
13050	have unique logical names.
13051
13052	<note>
13053	Global shared folders are not implemented in the current version of the
13054	product.
13055	</note>
13056	</desc>
13057
13058	<attribute name="name" type="wstring" readonly="yes">
13059	<desc>Logical name of the shared folder.</desc>
13060	</attribute>
13061
13062	<attribute name="hostPath" type="wstring" readonly="yes">
13063	<desc>Full path to the shared folder in the host file system.</desc>
13064	</attribute>
13065
13066	<attribute name="accessible" type="boolean" readonly="yes">
13067	<desc>
13068	Whether the folder defined by the host path is currently
13069	accessible or not.
13070	For example, the folder can be unaccessible if it is placed
13071	on the network share that is not available by the time
13072	this property is read.
13073	</desc>
13074	</attribute>
13075
13076	<attribute name="writable" type="boolean" readonly="yes">
13077	<desc>
13078	Whether the folder defined by the host path is writable or
13079	not.
13080	</desc>
13081	</attribute>
13082
13083	<attribute name="lastAccessError" type="wstring" readonly="yes">
13084	<desc>
13085	Text message that represents the result of the last accessibility
13086	check.
13087
13088	Accessibility checks are performed each time the <link to="#accessible"/>
13089	attribute is read. An empty string is returned if the last
13090	accessibility check was successful. A non-empty string indicates a
13091	failure and should normally describe a reason of the failure (for
13092	example, a file read error).
13093	</desc>
13094	</attribute>
13095
13096	</interface>
13097
13098	<!--
13099	// ISession
13100	/////////////////////////////////////////////////////////////////////////
13101	-->
13102
13103	<interface
13104	name="IInternalSessionControl" extends="$unknown"
13105	uuid="ab161f72-e4b3-44e6-a919-2256474bda66"
13106	internal="yes"
13107	wsmap="suppress"
13108	>
13109	<method name="getPID">
13110	<desc>PID of the process that has created this Session object.
13111	</desc>
13112	<param name="pid" type="unsigned long" dir="return"/>
13113	</method>
13114
13115	<method name="getRemoteConsole">
13116	<desc>
13117	Returns the console object suitable for remote control.
13118
13119	<result name="VBOX_E_INVALID_VM_STATE">
13120	Session state prevents operation.
13121	</result>
13122	<result name="VBOX_E_INVALID_OBJECT_STATE">
13123	Session type prevents operation.
13124	</result>
13125
13126	</desc>
13127	<param name="console" type="IConsole" dir="return"/>
13128	</method>
13129
13130	<method name="assignMachine">
13131	<desc>
13132	Assigns the machine object associated with this direct-type
13133	session or informs the session that it will be a remote one
13134	(if @a machine == @c null).
13135
13136	<result name="VBOX_E_INVALID_VM_STATE">
13137	Session state prevents operation.
13138	</result>
13139	<result name="VBOX_E_INVALID_OBJECT_STATE">
13140	Session type prevents operation.
13141	</result>
13142
13143	</desc>
13144	<param name="machine" type="IMachine" dir="in"/>
13145	</method>
13146
13147	<method name="assignRemoteMachine">
13148	<desc>
13149	Assigns the machine and the (remote) console object associated with
13150	this remote-type session.
13151
13152	<result name="VBOX_E_INVALID_VM_STATE">
13153	Session state prevents operation.
13154	</result>
13155
13156	</desc>
13157	<param name="machine" type="IMachine" dir="in"/>
13158	<param name="console" type="IConsole" dir="in"/>
13159	</method>
13160
13161	<method name="updateMachineState">
13162	<desc>
13163	Updates the machine state in the VM process.
13164	Must be called only in certain cases
13165	(see the method implementation).
13166
13167	<result name="VBOX_E_INVALID_VM_STATE">
13168	Session state prevents operation.
13169	</result>
13170	<result name="VBOX_E_INVALID_OBJECT_STATE">
13171	Session type prevents operation.
13172	</result>
13173
13174	</desc>
13175	<param name="aMachineState" type="MachineState" dir="in"/>
13176	</method>
13177
13178	<method name="uninitialize">
13179	<desc>
13180	Uninitializes (closes) this session. Used by VirtualBox to close
13181	the corresponding remote session when the direct session dies
13182	or gets closed.
13183
13184	<result name="VBOX_E_INVALID_VM_STATE">
13185	Session state prevents operation.
13186	</result>
13187
13188	</desc>
13189	</method>
13190
13191	<method name="onNetworkAdapterChange">
13192	<desc>
13193	Triggered when settings of a network adapter of the
13194	associated virtual machine have changed.
13195
13196	<result name="VBOX_E_INVALID_VM_STATE">
13197	Session state prevents operation.
13198	</result>
13199	<result name="VBOX_E_INVALID_OBJECT_STATE">
13200	Session type prevents operation.
13201	</result>
13202
13203	</desc>
13204	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
13205	<param name="changeAdapter" type="boolean" dir="in"/>
13206	</method>
13207
13208	<method name="onSerialPortChange">
13209	<desc>
13210	Triggered when settings of a serial port of the
13211	associated virtual machine have changed.
13212
13213	<result name="VBOX_E_INVALID_VM_STATE">
13214	Session state prevents operation.
13215	</result>
13216	<result name="VBOX_E_INVALID_OBJECT_STATE">
13217	Session type prevents operation.
13218	</result>
13219
13220	</desc>
13221	<param name="serialPort" type="ISerialPort" dir="in"/>
13222	</method>
13223
13224	<method name="onParallelPortChange">
13225	<desc>
13226	Triggered when settings of a parallel port of the
13227	associated virtual machine have changed.
13228
13229	<result name="VBOX_E_INVALID_VM_STATE">
13230	Session state prevents operation.
13231	</result>
13232	<result name="VBOX_E_INVALID_OBJECT_STATE">
13233	Session type prevents operation.
13234	</result>
13235
13236	</desc>
13237	<param name="parallelPort" type="IParallelPort" dir="in"/>
13238	</method>
13239
13240	<method name="onStorageControllerChange">
13241	<desc>
13242	Triggered when settings of a storage controller of the
13243	associated virtual machine have changed.
13244
13245	<result name="VBOX_E_INVALID_VM_STATE">
13246	Session state prevents operation.
13247	</result>
13248	<result name="VBOX_E_INVALID_OBJECT_STATE">
13249	Session type prevents operation.
13250	</result>
13251
13252	</desc>
13253	</method>
13254
13255	<method name="onMediumChange">
13256	<desc>
13257	Triggered when attached media of the
13258	associated virtual machine have changed.
13259
13260	<result name="VBOX_E_INVALID_VM_STATE">
13261	Session state prevents operation.
13262	</result>
13263	<result name="VBOX_E_INVALID_OBJECT_STATE">
13264	Session type prevents operation.
13265	</result>
13266
13267	</desc>
13268
13269	<param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
13270	<param name="force" type="boolean" dir="in"/>
13271	</method>
13272
13273	<method name="onCPUChange">
13274	<desc>
13275	Notification when a CPU changes.
13276	</desc>
13277	<param name="cpu" type="unsigned long" dir="in">
13278	<desc>The CPU which changed</desc>
13279	</param>
13280	<param name="add" type="boolean" dir="in">
13281	<desc>Flag whether the CPU was added or removed</desc>
13282	</param>
13283	</method>
13284
13285	<method name="onVRDPServerChange">
13286	<desc>
13287	Triggered when settings of the VRDP server object of the
13288	associated virtual machine have changed.
13289
13290	<result name="VBOX_E_INVALID_VM_STATE">
13291	Session state prevents operation.
13292	</result>
13293	<result name="VBOX_E_INVALID_OBJECT_STATE">
13294	Session type prevents operation.
13295	</result>
13296
13297	</desc>
13298	<param name="restart" type="boolean" dir="in">
13299	<desc>Flag whether the server must be restarted</desc>
13300	</param>
13301	</method>
13302
13303	<method name="onUSBControllerChange">
13304	<desc>
13305	Triggered when settings of the USB controller object of the
13306	associated virtual machine have changed.
13307
13308	<result name="VBOX_E_INVALID_VM_STATE">
13309	Session state prevents operation.
13310	</result>
13311	<result name="VBOX_E_INVALID_OBJECT_STATE">
13312	Session type prevents operation.
13313	</result>
13314
13315	</desc>
13316	</method>
13317
13318	<method name="onSharedFolderChange">
13319	<desc>
13320	Triggered when a permanent (global or machine) shared folder has been
13321	created or removed.
13322	<note>
13323	We don't pass shared folder parameters in this notification because
13324	the order in which parallel notifications are delivered is not defined,
13325	therefore it could happen that these parameters were outdated by the
13326	time of processing this notification.
13327	</note>
13328
13329	<result name="VBOX_E_INVALID_VM_STATE">
13330	Session state prevents operation.
13331	</result>
13332	<result name="VBOX_E_INVALID_OBJECT_STATE">
13333	Session type prevents operation.
13334	</result>
13335
13336	</desc>
13337	<param name="global" type="boolean" dir="in"/>
13338	</method>
13339
13340	<method name="onUSBDeviceAttach">
13341	<desc>
13342	Triggered when a request to capture a USB device (as a result
13343	of matched USB filters or direct call to
13344	<link to="IConsole::attachUSBDevice"/>) has completed.
13345	A @c null @a error object means success, otherwise it
13346	describes a failure.
13347
13348	<result name="VBOX_E_INVALID_VM_STATE">
13349	Session state prevents operation.
13350	</result>
13351	<result name="VBOX_E_INVALID_OBJECT_STATE">
13352	Session type prevents operation.
13353	</result>
13354
13355	</desc>
13356	<param name="device" type="IUSBDevice" dir="in"/>
13357	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13358	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
13359	</method>
13360
13361	<method name="onUSBDeviceDetach">
13362	<desc>
13363	Triggered when a request to release the USB device (as a result
13364	of machine termination or direct call to
13365	<link to="IConsole::detachUSBDevice"/>) has completed.
13366	A @c null @a error object means success, otherwise it
13367	describes a failure.
13368
13369	<result name="VBOX_E_INVALID_VM_STATE">
13370	Session state prevents operation.
13371	</result>
13372	<result name="VBOX_E_INVALID_OBJECT_STATE">
13373	Session type prevents operation.
13374	</result>
13375
13376	</desc>
13377	<param name="id" type="uuid" mod="string" dir="in"/>
13378	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13379	</method>
13380
13381	<method name="onShowWindow">
13382	<desc>
13383	Called by <link to="IMachine::canShowConsoleWindow"/> and by
13384	<link to="IMachine::showConsoleWindow"/> in order to notify
13385	console callbacks
13386	<link to="IConsoleCallback::onCanShowWindow"/>
13387	and <link to="IConsoleCallback::onShowWindow"/>.
13388
13389	<result name="VBOX_E_INVALID_OBJECT_STATE">
13390	Session type prevents operation.
13391	</result>
13392
13393	</desc>
13394	<param name="check" type="boolean" dir="in"/>
13395	<param name="canShow" type="boolean" dir="out"/>
13396	<param name="winId" type="unsigned long long" dir="out"/>
13397	</method>
13398
13399	<method name="accessGuestProperty">
13400	<desc>
13401	Called by <link to="IMachine::getGuestProperty"/> and by
13402	<link to="IMachine::setGuestProperty"/> in order to read and
13403	modify guest properties.
13404
13405	<result name="VBOX_E_INVALID_VM_STATE">
13406	Machine session is not open.
13407	</result>
13408	<result name="VBOX_E_INVALID_OBJECT_STATE">
13409	Session type is not direct.
13410	</result>
13411
13412	</desc>
13413	<param name="name" type="wstring" dir="in"/>
13414	<param name="value" type="wstring" dir="in"/>
13415	<param name="flags" type="wstring" dir="in"/>
13416	<param name="isSetter" type="boolean" dir="in"/>
13417	<param name="retValue" type="wstring" dir="out"/>
13418	<param name="retTimestamp" type="unsigned long long" dir="out"/>
13419	<param name="retFlags" type="wstring" dir="out"/>
13420	</method>
13421
13422	<method name="enumerateGuestProperties">
13423	<desc>
13424	Return a list of the guest properties matching a set of patterns along
13425	with their values, time stamps and flags.
13426
13427	<result name="VBOX_E_INVALID_VM_STATE">
13428	Machine session is not open.
13429	</result>
13430	<result name="VBOX_E_INVALID_OBJECT_STATE">
13431	Session type is not direct.
13432	</result>
13433
13434	</desc>
13435	<param name="patterns" type="wstring" dir="in">
13436	<desc>
13437	The patterns to match the properties against as a comma-separated
13438	string. If this is empty, all properties currently set will be
13439	returned.
13440	</desc>
13441	</param>
13442	<param name="key" type="wstring" dir="out" safearray="yes">
13443	<desc>
13444	The key names of the properties returned.
13445	</desc>
13446	</param>
13447	<param name="value" type="wstring" dir="out" safearray="yes">
13448	<desc>
13449	The values of the properties returned. The array entries match the
13450	corresponding entries in the @a key array.
13451	</desc>
13452	</param>
13453	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
13454	<desc>
13455	The time stamps of the properties returned. The array entries match
13456	the corresponding entries in the @a key array.
13457	</desc>
13458	</param>
13459	<param name="flags" type="wstring" dir="out" safearray="yes">
13460	<desc>
13461	The flags of the properties returned. The array entries match the
13462	corresponding entries in the @a key array.
13463	</desc>
13464	</param>
13465	</method>
13466
13467	<method name="onlineMergeMedium">
13468	<desc>
13469	Triggers online merging of a hard disk. Used internally when deleting
13470	a snapshot while a VM referring to the same hard disk chain is running.
13471
13472	<result name="VBOX_E_INVALID_VM_STATE">
13473	Machine session is not open.
13474	</result>
13475	<result name="VBOX_E_INVALID_OBJECT_STATE">
13476	Session type is not direct.
13477	</result>
13478
13479	</desc>
13480	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
13481	<desc>The medium attachment to identify the medium chain.</desc>
13482	</param>
13483	<param name="sourceIdx" type="unsigned long" dir="in">
13484	<desc>The index of the source image in the chain.
13485	Redundant, but drastically reduces IPC.</desc>
13486	</param>
13487	<param name="targetIdx" type="unsigned long" dir="in">
13488	<desc>The index of the target image in the chain.
13489	Redundant, but drastically reduces IPC.</desc>
13490	</param>
13491	<param name="source" type="IMedium" dir="in">
13492	<desc>Merge source medium.</desc>
13493	</param>
13494	<param name="target" type="IMedium" dir="in">
13495	<desc>Merge target medium.</desc>
13496	</param>
13497	<param name="mergeForward" type="boolean" dir="in">
13498	<desc>Merge direction.</desc>
13499	</param>
13500	<param name="parentForTarget" type="IMedium" dir="in">
13501	<desc>For forward merges: new parent for target medium.</desc>
13502	</param>
13503	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
13504	<desc>For backward merges: list of media which need their parent UUID
13505	updated.</desc>
13506	</param>
13507	<param name="progress" type="IProgress" dir="in">
13508	<desc>
13509	Progress object for this operation.
13510	</desc>
13511	</param>
13512	</method>
13513
13514	</interface>
13515
13516	<interface
13517	name="ISession" extends="$unknown"
13518	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
13519	wsmap="managed"
13520	>
13521	<desc>
13522	The ISession interface represents a serialization primitive for virtual
13523	machines.
13524
13525	With VirtualBox, every time one wishes to manipulate a virtual machine
13526	(e.g. change its settings or start execution), a session object is
13527	required. Such an object must be passed to one of the session methods
13528	that open the given session, which then initiates the machine manipulation.
13529
13530	A session serves several purposes: it identifies to the inter-process VirtualBox
13531	code which process is currently working with the virtual machine, and it ensures
13532	that there are no incompatible requests from several processes for the
13533	same virtual machine. Session objects can therefore be thought of as mutex
13534	semaphores that lock virtual machines to prevent conflicting accesses from
13535	several processes.
13536
13537	How sessions objects are used depends on whether you use the Main API
13538	via COM or via the webservice:
13539
13540	<ul>
13541	<li>When using the COM API directly, an object of the Session class from the
13542	VirtualBox type library needs to be created. In regular COM C++ client code,
13543	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
13544	This object will then act as a local session object in further calls to open
13545	a session.
13546	</li>
13547
13548	<li>In the webservice, the session manager (IWebsessionManager) instead creates
13549	one session object automatically when <link to="IWebsessionManager::logon" />
13550	is called. A managed object reference to that session object can be retrieved by
13551	calling <link to="IWebsessionManager::getSessionObject" />. This session object
13552	reference can then be used to open sessions.
13553	</li>
13554	</ul>
13555
13556	Sessions are mainly used in two variations:
13557
13558	<ul>
13559	<li>
13560	To start a virtual machine in a separate process, one would call
13561	<link to="IVirtualBox::openRemoteSession"/>, which requires a session
13562	object as its first parameter. This session then identifies the caller
13563	and lets him control the started machine (for example, pause machine
13564	execution or power it down) as well as be notified about machine
13565	execution state changes.
13566	</li>
13567
13568	<li>To alter machine settings, or to start machine execution within the
13569	current process, one needs to open a direct session for the machine first by
13570	calling <link to="IVirtualBox::openSession"/>. While a direct session
13571	is open within one process, no any other process may open another direct
13572	session for the same machine. This prevents the machine from being changed
13573	by other processes while it is running or while the machine is being configured.
13574	</li>
13575	</ul>
13576
13577	One also can attach to an existing direct session already opened by
13578	another process (for example, in order to send a control request to the
13579	virtual machine such as the pause or the reset request). This is done by
13580	calling <link to="IVirtualBox::openExistingSession"/>.
13581
13582	<note>
13583	Unless you are trying to write a new VirtualBox front-end that
13584	performs direct machine execution (like the VirtualBox or VBoxSDL
13585	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
13586	session opened by <link to="IVirtualBox::openSession"/> and use this
13587	session only to change virtual machine settings. If you simply want to
13588	start virtual machine execution using one of the existing front-ends
13589	(for example the VirtualBox GUI or headless server), simply use
13590	<link to="IVirtualBox::openRemoteSession"/>; these front-ends
13591	will power up the machine automatically for you.
13592	</note>
13593	</desc>
13594
13595	<attribute name="state" type="SessionState" readonly="yes">
13596	<desc>Current state of this session.</desc>
13597	</attribute>
13598
13599	<attribute name="type" type="SessionType" readonly="yes">
13600	<desc>
13601	Type of this session. The value of this attribute is valid only
13602	if the session is currently open (i.e. its #state is
13603	SessionType_SessionOpen), otherwise an error will be returned.
13604	</desc>
13605	</attribute>
13606
13607	<attribute name="machine" type="IMachine" readonly="yes">
13608	<desc>Machine object associated with this session.</desc>
13609	</attribute>
13610
13611	<attribute name="console" type="IConsole" readonly="yes">
13612	<desc>Console object associated with this session.</desc>
13613	</attribute>
13614
13615	<method name="close">
13616	<desc>
13617	Closes a session that was previously opened.
13618
13619	It is recommended that every time an "open session" method (such as
13620	<link to="IVirtualBox::openRemoteSession" /> or
13621	<link to="IVirtualBox::openSession" />) has been called to
13622	manipulate a virtual machine, the caller invoke
13623	ISession::close() when it's done doing so. Since sessions are
13624	serialization primitives much like ordinary mutexes, they are
13625	best used the same way: for each "open" call, there should be
13626	a matching "close" call, even when errors occur.
13627
13628	Otherwise, if a direct session for a machine opened with
13629	<link to="IVirtualBox::openSession"/> is not explicitly closed
13630	when the application terminates, the state of the machine will
13631	be set to <link to="MachineState_Aborted" /> on the server.
13632
13633	Generally, it is recommended to close all open sessions explicitly
13634	before terminating the application (regardless of the reason for
13635	the termination).
13636
13637	<note>
13638	Do not expect the session state (<link to="ISession::state" />
13639	to return to "Closed" immediately after you invoke
13640	ISession::close(), particularly if you have started a remote
13641	session to execute the VM in a new process. The session state will
13642	automatically return to "Closed" once the VM is no longer executing,
13643	which can of course take a very long time.
13644	</note>
13645
13646	<result name="E_UNEXPECTED">
13647	Session is not open.
13648	</result>
13649
13650	</desc>
13651	</method>
13652
13653	</interface>
13654
13655	<!--
13656	// IStorageController
13657	/////////////////////////////////////////////////////////////////////////
13658	-->
13659
13660	<enum
13661	name="StorageBus"
13662	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
13663	>
13664	<desc>
13665	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
13666	see <link to="IStorageController::bus" />.
13667	</desc>
13668	<const name="Null" value="0">
13669	<desc>@c null value. Never used by the API.</desc>
13670	</const>
13671	<const name="IDE" value="1"/>
13672	<const name="SATA" value="2"/>
13673	<const name="SCSI" value="3"/>
13674	<const name="Floppy" value="4"/>
13675	<const name="SAS" value="5"/>
13676	</enum>
13677
13678	<enum
13679	name="StorageControllerType"
13680	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
13681	>
13682	<desc>
13683	The exact variant of storage controller hardware presented
13684	to the guest; see <link to="IStorageController::controllerType" />.
13685	</desc>
13686
13687	<const name="Null" value="0">
13688	<desc>@c null value. Never used by the API.</desc>
13689	</const>
13690	<const name="LsiLogic" value="1">
13691	<desc>A SCSI controller of the LsiLogic variant.</desc>
13692	</const>
13693	<const name="BusLogic" value="2">
13694	<desc>A SCSI controller of the BusLogic variant.</desc>
13695	</const>
13696	<const name="IntelAhci" value="3">
13697	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
13698	</const>
13699	<const name="PIIX3" value="4">
13700	<desc>An IDE controller of the PIIX3 variant.</desc>
13701	</const>
13702	<const name="PIIX4" value="5">
13703	<desc>An IDE controller of the PIIX4 variant.</desc>
13704	</const>
13705	<const name="ICH6" value="6">
13706	<desc>An IDE controller of the ICH6 variant.</desc>
13707	</const>
13708	<const name="I82078" value="7">
13709	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
13710	</const>
13711	<const name="LsiLogicSas" value="8">
13712	<desc>A variant of the LsiLogic controller using SAS.</desc>
13713	</const>
13714	</enum>
13715
13716	<interface
13717	name="IStorageController" extends="$unknown"
13718	uuid="fd93adc0-bbaa-4256-9e6e-00e29f9151c9"
13719	wsmap="managed"
13720	>
13721	<desc>
13722	Represents a storage controller that is attached to a virtual machine
13723	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
13724	attached to storage controllers in a real computer, virtual drives
13725	(represented by <link to="IMediumAttachment" />) are attached to virtual
13726	storage controllers, represented by this interface.
13727
13728	As opposed to physical hardware, VirtualBox has a very generic concept
13729	of a storage controller, and for purposes of the Main API, all virtual
13730	storage is attached to virtual machines via instances of this interface.
13731	There are five types of such virtual storage controllers: IDE, SCSI, SATA,
13732	SAS and Floppy (see <link to="#bus" />). Depending on which of these four
13733	is used, certain sub-types may be available and can be selected in
13734	<link to="#controllerType" />.
13735
13736	Depending on these settings, the guest operating system might see
13737	significantly different virtual hardware.
13738	</desc>
13739
13740	<attribute name="name" type="wstring" readonly="yes">
13741	<desc>
13742	Name of the storage controller, as originally specified with
13743	<link to="IMachine::addStorageController" />. This then uniquely
13744	identifies this controller with other method calls such as
13745	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
13746	</desc>
13747	</attribute>
13748
13749	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
13750	<desc>
13751	Maximum number of devices which can be attached to one port.
13752	</desc>
13753	</attribute>
13754
13755	<attribute name="minPortCount" type="unsigned long" readonly="yes">
13756	<desc>
13757	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
13758	</desc>
13759	</attribute>
13760
13761	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
13762	<desc>
13763	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
13764	</desc>
13765	</attribute>
13766
13767	<attribute name="instance" type="unsigned long">
13768	<desc>
13769	The instance number of the device in the running VM.
13770	</desc>
13771	</attribute>
13772
13773	<attribute name="portCount" type="unsigned long">
13774	<desc>
13775	The number of currently usable ports on the controller.
13776	The minimum and maximum number of ports for one controller are
13777	stored in <link to="IStorageController::minPortCount"/>
13778	and <link to="IStorageController::maxPortCount"/>.
13779	</desc>
13780	</attribute>
13781
13782	<attribute name="bus" type="StorageBus" readonly="yes">
13783	<desc>
13784	The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
13785	</desc>
13786	</attribute>
13787
13788	<attribute name="controllerType" type="StorageControllerType">
13789	<desc>
13790	The exact variant of storage controller hardware presented
13791	to the guest.
13792	Depending on this value, VirtualBox will provide a different
13793	virtual storage controller hardware to the guest.
13794	For SATA, SAS and floppy controllers, only one variant is
13795	available, but for IDE and SCSI, there are several.
13796
13797	For SCSI controllers, the default type is LsiLogic.
13798	</desc>
13799	</attribute>
13800
13801	<attribute name="useHostIOCache" type="boolean">
13802	<desc>
13803	If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
13804	caches and use synchronous file APIs on the host. This was the only option in the API before
13805	VirtualBox 3.2 and is still the default for IDE controllers.
13806
13807	If false, the host I/O cache will be disabled for image files attached to this storage controller.
13808	Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
13809	it possible to turn off the host I/O caches because the emulation can handle unaligned access to
13810	the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
13811	virtual machines are running at the same time to prevent I/O cache related hangs.
13812	This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
13813	</desc>
13814	</attribute>
13815
13816	<method name="getIDEEmulationPort">
13817	<desc>
13818	Gets the corresponding port number which is emulated as an IDE device.
13819	Works only with SATA controllers.
13820
13821	<result name="E_INVALIDARG">
13822	The @a devicePosition is not in the range 0 to 3.
13823	</result>
13824	<result name="E_NOTIMPL">
13825	The storage controller type is not SATAIntelAhci.
13826	</result>
13827
13828	</desc>
13829	<param name="devicePosition" type="long" dir="in"/>
13830	<param name="portNumber" type="long" dir="return"/>
13831	</method>
13832
13833	<method name="setIDEEmulationPort">
13834	<desc>
13835	Sets the port number which is emulated as an IDE device.
13836	Works only with SATA controllers.
13837
13838	<result name="E_INVALIDARG">
13839	The @a devicePosition is not in the range 0 to 3 or the
13840	@a portNumber is not in the range 0 to 29.
13841	</result>
13842	<result name="E_NOTIMPL">
13843	The storage controller type is not SATAIntelAhci.
13844	</result>
13845
13846	</desc>
13847	<param name="devicePosition" type="long" dir="in"/>
13848	<param name="portNumber" type="long" dir="in"/>
13849	</method>
13850
13851	</interface>
13852
13853	<if target="wsdl">
13854
13855	<!--
13856	// IManagedObjectRef
13857	/////////////////////////////////////////////////////////////////////////
13858	-->
13859
13860	<interface
13861	name="IManagedObjectRef" extends="$unknown"
13862	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
13863	internal="yes"
13864	wsmap="managed"
13865	wscpp="hardcoded"
13866	>
13867	<desc>
13868	Managed object reference.
13869
13870	Only within the webservice, a managed object reference (which is really
13871	an opaque number) allows a webservice client to address an object
13872	that lives in the address space of the webservice server.
13873
13874	Behind each managed object reference, there is a COM object that lives
13875	in the webservice server's address space. The COM object is not freed
13876	until the managed object reference is released, either by an explicit
13877	call to <link to="IManagedObjectRef::release" /> or by logging off from
13878	the webservice (<link to="IWebsessionManager::logoff" />), which releases
13879	all objects created during the webservice session.
13880
13881	Whenever a method call of the VirtualBox API returns a COM object, the
13882	webservice representation of that method will instead return a
13883	managed object reference, which can then be used to invoke methods
13884	on that object.
13885	</desc>
13886
13887	<method name="getInterfaceName">
13888	<desc>
13889	Returns the name of the interface that this managed object represents,
13890	for example, "IMachine", as a string.
13891	</desc>
13892	<param name="return" type="wstring" dir="return"/>
13893	</method>
13894
13895	<method name="release">
13896	<desc>
13897	Releases this managed object reference and frees the resources that
13898	were allocated for it in the webservice server process. After calling
13899	this method, the identifier of the reference can no longer be used.
13900	</desc>
13901	</method>
13902
13903	</interface>
13904
13905	<!--
13906	// IWebsessionManager
13907	/////////////////////////////////////////////////////////////////////////
13908	-->
13909
13910	<interface
13911	name="IWebsessionManager" extends="$unknown"
13912	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
13913	internal="yes"
13914	wsmap="global"
13915	wscpp="hardcoded"
13916	>
13917	<desc>
13918	Websession manager. This provides essential services
13919	to webservice clients.
13920	</desc>
13921	<method name="logon">
13922	<desc>
13923	Logs a new client onto the webservice and returns a managed object reference to
13924	the IVirtualBox instance, which the client can then use as a basis to further
13925	queries, since all calls to the VirtualBox API are based on the IVirtualBox
13926	interface, in one way or the other.
13927	</desc>
13928	<param name="username" type="wstring" dir="in"/>
13929	<param name="password" type="wstring" dir="in"/>
13930	<param name="return" type="IVirtualBox" dir="return"/>
13931	</method>
13932
13933	<method name="getSessionObject">
13934	<desc>
13935	Returns a managed object reference to the internal ISession object that was created
13936	for this web service session when the client logged on.
13937
13938	<see>ISession</see>
13939	</desc>
13940	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13941	<param name="return" type="ISession" dir="return"/>
13942	</method>
13943
13944	<method name="logoff">
13945	<desc>
13946	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
13947	and destroys all resources associated with the session (most importantly, all
13948	managed objects created in the server while the session was active).
13949	</desc>
13950	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13951	</method>
13952
13953	</interface>
13954
13955	</if>
13956
13957	<!--
13958	// IPerformanceCollector & friends
13959	/////////////////////////////////////////////////////////////////////////
13960	-->
13961
13962	<interface
13963	name="IPerformanceMetric" extends="$unknown"
13964	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
13965	>
13966	<desc>
13967	The IPerformanceMetric interface represents parameters of the given
13968	performance metric.
13969	</desc>
13970
13971	<attribute name="metricName" type="wstring" readonly="yes">
13972	<desc>
13973	Name of the metric.
13974	</desc>
13975	</attribute>
13976
13977	<attribute name="object" type="$unknown" readonly="yes">
13978	<desc>
13979	Object this metric belongs to.
13980	</desc>
13981	</attribute>
13982
13983	<attribute name="description" type="wstring" readonly="yes">
13984	<desc>
13985	Textual description of the metric.
13986	</desc>
13987	</attribute>
13988
13989	<attribute name="period" type="unsigned long" readonly="yes">
13990	<desc>
13991	Time interval between samples, measured in seconds.
13992	</desc>
13993	</attribute>
13994
13995	<attribute name="count" type="unsigned long" readonly="yes">
13996	<desc>
13997	Number of recent samples retained by the performance collector for this
13998	metric.
13999
14000	When the collected sample count exceeds this number, older samples
14001	are discarded.
14002	</desc>
14003	</attribute>
14004
14005	<attribute name="unit" type="wstring" readonly="yes">
14006	<desc>
14007	Unit of measurement.
14008	</desc>
14009	</attribute>
14010
14011	<attribute name="minimumValue" type="long" readonly="yes">
14012	<desc>
14013	Minimum possible value of this metric.
14014	</desc>
14015	</attribute>
14016
14017	<attribute name="maximumValue" type="long" readonly="yes">
14018	<desc>
14019	Maximum possible value of this metric.
14020	</desc>
14021	</attribute>
14022	</interface>
14023
14024	<interface
14025	name="IPerformanceCollector" extends="$unknown"
14026	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
14027	wsmap="managed"
14028	>
14029	<desc>
14030	The IPerformanceCollector interface represents a service that collects
14031	and stores performance metrics data.
14032
14033	Performance metrics are associated with objects of interfaces like IHost
14034	and IMachine. Each object has a distinct set of performance metrics. The
14035	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
14036
14037	Metric data is collected at the specified intervals and is retained
14038	internally. The interval and the number of retained samples can be set
14039	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
14040	and collection settings are not persistent, they are discarded as soon as
14041	VBoxSVC process terminates. Moreover, metric settings and data associated
14042	with a particular VM only exist while VM is running. They disappear as
14043	soon as VM shuts down. It is not possible to set up metrics for machines
14044	that are powered off. One needs to start VM first, then set up metric
14045	collection parameters.
14046
14047	Metrics are organized hierarchically, with each level separated by a
14048	slash (/) character. Generally, the scheme for metric names is like this:
14049
14050	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
14051
14052	"Category/Metric" together form the base metric name. A base metric is
14053	the smallest unit for which a sampling interval and the number of
14054	retained samples can be set. Only base metrics can be enabled and
14055	disabled. All sub-metrics are collected when their base metric is
14056	collected. Collected values for any set of sub-metrics can be queried
14057	with <link to="IPerformanceCollector::queryMetricsData" />.
14058
14059	For example "CPU/Load/User:avg" metric name stands for the "CPU"
14060	category, "Load" metric, "User" submetric, "average" aggregate. An
14061	aggregate function is computed over all retained data. Valid aggregate
14062	functions are:
14063
14064	<ul>
14065	<li>avg -- average</li>
14066	<li>min -- minimum</li>
14067	<li>max -- maximum</li>
14068	</ul>
14069
14070	When setting up metric parameters, querying metric data, enabling or
14071	disabling metrics wildcards can be used in metric names to specify a
14072	subset of metrics. For example, to select all CPU-related metrics
14073	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
14074	so on. To query metric values without aggregates <tt>*:</tt> can be used.
14075
14076	The valid names for base metrics are:
14077
14078	<ul>
14079	<li>CPU/Load</li>
14080	<li>CPU/MHz</li>
14081	<li>RAM/Usage</li>
14082	</ul>
14083
14084	The general sequence for collecting and retrieving the metrics is:
14085	<ul>
14086	<li>
14087	Obtain an instance of IPerformanceCollector with
14088	<link to="IVirtualBox::performanceCollector" />
14089	</li>
14090	<li>
14091	Allocate and populate an array with references to objects the metrics
14092	will be collected for. Use references to IHost and IMachine objects.
14093	</li>
14094	<li>
14095	Allocate and populate an array with base metric names the data will
14096	be collected for.
14097	</li>
14098	<li>
14099	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
14100	the metric data will be collected and stored.
14101	</li>
14102	<li>
14103	Wait for the data to get collected.
14104	</li>
14105	<li>
14106	Allocate and populate an array with references to objects the metric
14107	values will be queried for. You can re-use the object array used for
14108	setting base metrics.
14109	</li>
14110	<li>
14111	Allocate and populate an array with metric names the data will be
14112	collected for. Note that metric names differ from base metric names.
14113	</li>
14114	<li>
14115	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
14116	that have been collected so far are returned. Note that the values
14117	are still retained internally and data collection continues.
14118	</li>
14119	</ul>
14120
14121	For an example of usage refer to the following files in VirtualBox SDK:
14122	<ul>
14123	<li>
14124	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
14125	</li>
14126	<li>
14127	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
14128	</li>
14129	</ul>
14130	</desc>
14131
14132	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
14133	<desc>
14134	Array of unique names of metrics.
14135
14136	This array represents all metrics supported by the performance
14137	collector. Individual objects do not necessarily support all of them.
14138	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
14139	list of supported metrics for a particular object.
14140	</desc>
14141	</attribute>
14142
14143	<method name="getMetrics">
14144	<desc>
14145	Returns parameters of specified metrics for a set of objects.
14146	<note>
14147	@c Null metrics array means all metrics. @c Null object array means
14148	all existing objects.
14149	</note>
14150	</desc>
14151	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14152	<desc>
14153	Metric name filter. Currently, only a comma-separated list of metrics
14154	is supported.
14155	</desc>
14156	</param>
14157	<param name="objects" type="$unknown" dir="in" safearray="yes">
14158	<desc>
14159	Set of objects to return metric parameters for.
14160	</desc>
14161	</param>
14162	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
14163	<desc>
14164	Array of returned metric parameters.
14165	</desc>
14166	</param>
14167	</method>
14168
14169	<method name="setupMetrics">
14170	<desc>
14171	Sets parameters of specified base metrics for a set of objects. Returns
14172	an array of <link to="IPerformanceMetric" /> describing the metrics
14173	have been affected.
14174	<note>
14175	@c Null or empty metric name array means all metrics. @c Null or
14176	empty object array means all existing objects. If metric name array
14177	contains a single element and object array contains many, the single
14178	metric name array element is applied to each object array element to
14179	form metric/object pairs.
14180	</note>
14181	</desc>
14182	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14183	<desc>
14184	Metric name filter. Comma-separated list of metrics with wildcard
14185	support.
14186	</desc>
14187	</param>
14188	<param name="objects" type="$unknown" dir="in" safearray="yes">
14189	<desc>
14190	Set of objects to setup metric parameters for.
14191	</desc>
14192	</param>
14193	<param name="period" type="unsigned long" dir="in">
14194	<desc>
14195	Time interval in seconds between two consecutive samples of
14196	performance data.
14197	</desc>
14198	</param>
14199	<param name="count" type="unsigned long" dir="in">
14200	<desc>
14201	Number of samples to retain in performance data history. Older
14202	samples get discarded.
14203	</desc>
14204	</param>
14205	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14206	<desc>
14207	Array of metrics that have been modified by the call to this method.
14208	</desc>
14209	</param>
14210	</method>
14211
14212	<method name="enableMetrics">
14213	<desc>
14214	Turns on collecting specified base metrics. Returns an array of
14215	<link to="IPerformanceMetric" /> describing the metrics have been
14216	affected.
14217	<note>
14218	@c Null or empty metric name array means all metrics. @c Null or
14219	empty object array means all existing objects. If metric name array
14220	contains a single element and object array contains many, the single
14221	metric name array element is applied to each object array element to
14222	form metric/object pairs.
14223	</note>
14224	</desc>
14225	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14226	<desc>
14227	Metric name filter. Comma-separated list of metrics with wildcard
14228	support.
14229	</desc>
14230	</param>
14231	<param name="objects" type="$unknown" dir="in" safearray="yes">
14232	<desc>
14233	Set of objects to enable metrics for.
14234	</desc>
14235	</param>
14236	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14237	<desc>
14238	Array of metrics that have been modified by the call to this method.
14239	</desc>
14240	</param>
14241	</method>
14242
14243	<method name="disableMetrics">
14244	<desc>
14245	Turns off collecting specified base metrics. Returns an array of
14246	<link to="IPerformanceMetric" /> describing the metrics have been
14247	affected.
14248	<note>
14249	@c Null or empty metric name array means all metrics. @c Null or
14250	empty object array means all existing objects. If metric name array
14251	contains a single element and object array contains many, the single
14252	metric name array element is applied to each object array element to
14253	form metric/object pairs.
14254	</note>
14255	</desc>
14256	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14257	<desc>
14258	Metric name filter. Comma-separated list of metrics with wildcard
14259	support.
14260	</desc>
14261	</param>
14262	<param name="objects" type="$unknown" dir="in" safearray="yes">
14263	<desc>
14264	Set of objects to disable metrics for.
14265	</desc>
14266	</param>
14267	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14268	<desc>
14269	Array of metrics that have been modified by the call to this method.
14270	</desc>
14271	</param>
14272	</method>
14273
14274	<method name="queryMetricsData">
14275	<desc>
14276	Queries collected metrics data for a set of objects.
14277
14278	The data itself and related metric information are returned in seven
14279	parallel and one flattened array of arrays. Elements of
14280	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
14281	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
14282	the same index describe one set of values corresponding to a single
14283	metric.
14284
14285	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
14286	start and length of a sub-array is indicated by
14287	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
14288	value for metric <tt>metricNames[i]</tt> is at
14289	<tt>returnData[returnIndices[i]]</tt>.
14290
14291	<note>
14292	@c Null or empty metric name array means all metrics. @c Null or
14293	empty object array means all existing objects. If metric name array
14294	contains a single element and object array contains many, the single
14295	metric name array element is applied to each object array element to
14296	form metric/object pairs.
14297	</note>
14298	<note>
14299	Data collection continues behind the scenes after call to @c
14300	queryMetricsData. The return data can be seen as the snapshot of the
14301	current state at the time of @c queryMetricsData call. The internally
14302	kept metric values are not cleared by the call. This makes possible
14303	querying different subsets of metrics or aggregates with subsequent
14304	calls. If periodic querying is needed it is highly suggested to query
14305	the values with @c interval*count period to avoid confusion. This way
14306	a completely new set of data values will be provided by each query.
14307	</note>
14308	</desc>
14309	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14310	<desc>
14311	Metric name filter. Comma-separated list of metrics with wildcard
14312	support.
14313	</desc>
14314	</param>
14315	<param name="objects" type="$unknown" dir="in" safearray="yes">
14316	<desc>
14317	Set of objects to query metrics for.
14318	</desc>
14319	</param>
14320	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
14321	<desc>
14322	Names of metrics returned in @c returnData.
14323	</desc>
14324	</param>
14325	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
14326	<desc>
14327	Objects associated with metrics returned in @c returnData.
14328	</desc>
14329	</param>
14330	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
14331	<desc>
14332	Units of measurement for each returned metric.
14333	</desc>
14334	</param>
14335	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
14336	<desc>
14337	Divisor that should be applied to return values in order to get
14338	floating point values. For example:
14339	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
14340	will retrieve the floating point value of i-th sample of the first
14341	metric.
14342	</desc>
14343	</param>
14344	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
14345	<desc>
14346	Sequence numbers of the first elements of value sequences of
14347	particular metrics returned in @c returnData. For aggregate metrics
14348	it is the sequence number of the sample the aggregate started
14349	calculation from.
14350	</desc>
14351	</param>
14352	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
14353	<desc>
14354	Indices of the first elements of value sequences of particular
14355	metrics returned in @c returnData.
14356	</desc>
14357	</param>
14358	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
14359	<desc>
14360	Lengths of value sequences of particular metrics.
14361	</desc>
14362	</param>
14363	<param name="returnData" type="long" dir="return" safearray="yes">
14364	<desc>
14365	Flattened array of all metric data containing sequences of values for
14366	each metric.
14367	</desc>
14368	</param>
14369	</method>
14370
14371	</interface>
14372	<enum
14373	name="NATAliasMode"
14374	uuid="67772168-50d9-11df-9669-7fb714ee4fa1">
14375	<desc></desc>
14376	<const name="AliasLog" value="0x1">
14377	<desc></desc>
14378	</const>
14379	<const name="AliasProxyOnly" value="0x02">
14380	<desc></desc>
14381	</const>
14382	<const name="AliasUseSamePorts" value="0x04">
14383	<desc></desc>
14384	</const>
14385	</enum>
14386	<enum
14387	name="NATProtocol"
14388	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
14389	>
14390	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
14391	<const name="UDP" value="0">
14392	<desc>Port-forwarding uses UDP protocol.</desc>
14393	</const>
14394	<const name="TCP" value="1">
14395	<desc>Port-forwarding uses TCP protocol.</desc>
14396	</const>
14397	</enum>
14398
14399	<interface
14400	name="INATEngine" extends="$unknown"
14401	uuid="4b286616-eb03-11de-b0fb-1701eca42246"
14402	wsmap="managed"
14403	>
14404	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
14405	allows for changing NAT behavior such as port-forwarding rules. This interface is
14406	used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
14407	<attribute name="network" type="wstring">
14408	<desc>The network attribute of the NAT engine (the same value is used with built-in
14409	DHCP server to fill corresponding fields of DHCP leases).</desc>
14410	</attribute>
14411	<attribute name="hostIP" type="wstring">
14412	<desc>IP of host interface to bind all opened sockets to.
14413	<note>Changing this does not change binding of port forwarding.</note>
14414	</desc>
14415	</attribute>
14416	<attribute name="tftpPrefix" type="wstring">
14417	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
14418	the corresponding fields of DHCP leases.</desc>
14419	</attribute>
14420	<attribute name="tftpBootFile" type="wstring">
14421	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
14422	the corresponding fields of DHCP leases.</desc>
14423	</attribute>
14424	<attribute name="tftpNextServer" type="wstring">
14425	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
14426	the corresponding fields of DHCP leases.
14427	<note>The preferred form is IPv4 addresses.</note>
14428	</desc>
14429	</attribute>
14430	<attribute name="aliasMode" type="unsigned long">
14431	<desc></desc>
14432	</attribute>
14433	<attribute name="dnsPassDomain" type="boolean">
14434	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
14435	</attribute>
14436	<attribute name="dnsProxy" type="boolean">
14437	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14438	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
14439	</attribute>
14440	<attribute name="dnsUseHostResolver" type="boolean">
14441	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14442	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
14443	</attribute>
14444	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
14445	<desc>Array of NAT port-forwarding rules in string representation, in the following
14446	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
14447	</attribute>
14448	<method name="setNetworkSettings">
14449	<desc>Sets network configuration of the NAT engine.</desc>
14450	<param name="mtu" type="unsigned long" dir="in">
14451	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
14452	</param>
14453	<param name="sockSnd" type="unsigned long" dir="in">
14454	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
14455	</param>
14456	<param name="sockRcv" type="unsigned long" dir="in">
14457	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
14458	</param>
14459	<param name="TcpWndSnd" type="unsigned long" dir="in">
14460	<desc>Initial size of the NAT engine's sending TCP window in bytes when
14461	establishing a new TCP connection.</desc>
14462	</param>
14463	<param name="TcpWndRcv" type="unsigned long" dir="in">
14464	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
14465	establishing a new TCP connection.</desc>
14466	</param>
14467	</method>
14468	<method name="getNetworkSettings">
14469	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
14470	for parameter descriptions.</desc>
14471	<param name="mtu" type="unsigned long" dir="out" />
14472	<param name="sockSnd" type="unsigned long" dir="out" />
14473	<param name="sockRcv" type="unsigned long" dir="out" />
14474	<param name="TcpWndSnd" type="unsigned long" dir="out" />
14475	<param name="TcpWndRcv" type="unsigned long" dir="out" />
14476	</method>
14477	<method name="addRedirect">
14478	<desc>Adds a new NAT port-forwarding rule.</desc>
14479	<param name="name" type="wstring" dir="in">
14480	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
14481	auto-generates one using the other parameters.</desc>
14482	</param>
14483	<param name="proto" type="NATProtocol" dir="in">
14484	<desc>Protocol handled with the rule.</desc>
14485	</param>
14486	<param name="hostIp" type="wstring" dir="in">
14487	<desc>IP of the host interface to which the rule should apply. An empty ip address is
14488	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
14489	</param>
14490	<param name="hostPort" type="unsigned short" dir="in">
14491	<desc>The port number to listen on.</desc>
14492	</param>
14493	<param name="guestIp" type="wstring" dir="in">
14494	<desc>The IP address of the guest which the NAT engine will forward matching packets
14495	to. An empty IP address is acceptable, in which case the NAT engine will forward
14496	packets to the first DHCP lease (x.x.x.15).</desc>
14497	</param>
14498	<param name="guestPort" type="unsigned short" dir="in">
14499	<desc>The port number to forward.</desc>
14500	</param>
14501	</method>
14502	<method name="removeRedirect">
14503	<desc>Removes a port-forwarding rule that was previously registered.</desc>
14504	<param name="name" type="wstring" dir="in">
14505	<desc>The name of the rule to delete.</desc>
14506	</param>
14507	</method>
14508	</interface>
14509
14510	<module name="VBoxSVC" context="LocalServer">
14511	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
14512	namespace="virtualbox.org">
14513	<interface name="IVirtualBox" default="yes"/>
14514	</class>
14515	</module>
14516
14517	<module name="VBoxC" context="InprocServer" threadingModel="Free">
14518	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
14519	namespace="virtualbox.org">
14520	<interface name="ISession" default="yes"/>
14521	</class>
14522	<class name="CallbackWrapper" uuid="49EE8561-5563-4715-B18C-A4B1A490DAFE"
14523	namespace="virtualbox.org">
14524	<interface name="ILocalOwner" default="yes"/>
14525	<interface name="IVirtualBoxCallback"/>
14526	<interface name="IConsoleCallback"/>
14527	</class>
14528	</module>
14529
14530	</library>
14531
14532	</idl>
14533
14534	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format