VirtualBox.xidl@ 29200

Last change on this file since 29200 was 29200, checked in by vboxsync, 15 years ago
more manual Oracle rebranding in headers
Property svn:eol-style set to `native`
File size: 537.3 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	<enum
1098	name="IoBackendType"
1099	uuid="2a7e16d1-4e6b-4d5d-b0c9-b9bbe6c5b2ad"
1100	>
1101	<desc>
1102	Type of I/O backend used for the image files in a virtual machine.
1103	</desc>
1104	<const name="Buffered" value="1">
1105	<desc>Image files will use the host cache if possible.
1106	The storage controller emulation will use a dedicated I/O thread, enable the host I/O cache and
1107	use synchronous file APIs on the host.
1108	This type does not work with the Async I/O manager on Linux hosts.
1109	This was the only option in the API before VirtualBox 3.2 and is still the default for IDE controllers.</desc>
1110	</const>
1111	<const name="Unbuffered" value="2">
1112	<desc>Image files will not use the host cache.
1113	The storage controller emulation will use asynchronous I/O APIs on the host. This makes it possible
1114	to turn off the host I/O caches because it can handle unaligned access to the file.
1115	This should be used on OS X and Linux hosts if a high I/O load is expected
1116	or many virtual machines are running to prevent I/O cache related hangs.
1117	This is new with the API of version 3.2 and is now the default for non-IDE storage controllers.</desc>
1118	</const>
1119	</enum>
1120
1121	<enum
1122	name="IoMgrType"
1123	uuid="35567419-4d2a-4256-a74e-efcae33493a2"
1124	>
1125	<desc>
1126	Type of the I/O manager used for the image files in a virtual machine if the backend is
1127	set to the "Unbuffered" type.
1128	</desc>
1129	<const name="Simple" value="1">
1130	<desc>Simple manager. Normally only used if the default one runs into an
1131	error. </desc>
1132	</const>
1133	<const name="Async" value="2">
1134	<desc>Asynchronous manager using the async I/O API on the host if present.
1135	This is the default manager.</desc>
1136	</const>
1137	</enum>
1138
1139	<!--
1140	// IVirtualBoxErrorInfo
1141	/////////////////////////////////////////////////////////////////////////
1142	-->
1143
1144	<interface
1145	name="IVirtualBoxErrorInfo" extends="$errorinfo"
1146	uuid="4b86d186-407e-4f9e-8be8-e50061be8725"
1147	supportsErrorInfo="no"
1148	wsmap="managed"
1149	>
1150	<desc>
1151	The IVirtualBoxErrorInfo interface represents extended error information.
1152
1153	Extended error information can be set by VirtualBox components after
1154	unsuccessful or partially successful method invocation. This information
1155	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1156	and then shown to the client in addition to the plain 32-bit result code.
1157
1158	In MS COM, this interface extends the IErrorInfo interface,
1159	in XPCOM, it extends the nsIException interface. In both cases,
1160	it provides a set of common attributes to retrieve error
1161	information.
1162
1163	Sometimes invocation of some component's method may involve methods of
1164	other components that may also fail (independently of this method's
1165	failure), or a series of non-fatal errors may precede a fatal error that
1166	causes method failure. In cases like that, it may be desirable to preserve
1167	information about all errors happened during method invocation and deliver
1168	it to the caller. The <link to="#next"/> attribute is intended
1169	specifically for this purpose and allows to represent a chain of errors
1170	through a single IVirtualBoxErrorInfo object set after method invocation.
1171
1172	Note that errors are stored to a chain in the reverse order, i.e. the
1173	initial error object you query right after method invocation is the last
1174	error set by the callee, the object it points to in the @a next attribute
1175	is the previous error and so on, up to the first error (which is the last
1176	in the chain).
1177	</desc>
1178
1179	<attribute name="resultCode" type="long" readonly="yes">
1180	<desc>
1181	Result code of the error.
1182	Usually, it will be the same as the result code returned
1183	by the method that provided this error information, but not
1184	always. For example, on Win32, CoCreateInstance() will most
1185	likely return E_NOINTERFACE upon unsuccessful component
1186	instantiation attempt, but not the value the component factory
1187	returned. Value is typed 'long', not 'result',
1188	to make interface usable from scripting languages.
1189	<note>
1190	In MS COM, there is no equivalent.
1191	In XPCOM, it is the same as nsIException::result.
1192	</note>
1193	</desc>
1194	</attribute>
1195
1196	<attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1197	<desc>
1198	UUID of the interface that defined the error.
1199	<note>
1200	In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1201	data type.
1202	In XPCOM, there is no equivalent.
1203	</note>
1204	</desc>
1205	</attribute>
1206
1207	<attribute name="component" type="wstring" readonly="yes">
1208	<desc>
1209	Name of the component that generated the error.
1210	<note>
1211	In MS COM, it is the same as IErrorInfo::GetSource.
1212	In XPCOM, there is no equivalent.
1213	</note>
1214	</desc>
1215	</attribute>
1216
1217	<attribute name="text" type="wstring" readonly="yes">
1218	<desc>
1219	Text description of the error.
1220	<note>
1221	In MS COM, it is the same as IErrorInfo::GetDescription.
1222	In XPCOM, it is the same as nsIException::message.
1223	</note>
1224	</desc>
1225	</attribute>
1226
1227	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1228	<desc>
1229	Next error object if there is any, or @c null otherwise.
1230	<note>
1231	In MS COM, there is no equivalent.
1232	In XPCOM, it is the same as nsIException::inner.
1233	</note>
1234	</desc>
1235	</attribute>
1236
1237	</interface>
1238
1239	<interface
1240	name="ILocalOwner" extends="$unknown"
1241	uuid="308FF42A-DC45-49D4-A950-B1EEE5E00BB5" wsmap="suppress"
1242	>
1243	<desc>
1244	The ILocalOwner interface allows to register local objects
1245	(created without COM calls, but with new()).
1246	Once registered, calls to methods of such objects can be made
1247	from remote COM processes.
1248	The main usecase is the event callback implementation where
1249	API clients provide callback objects.
1250	</desc>
1251	<method name="setLocalObject">
1252	<desc>
1253	Set local object.
1254	</desc>
1255	<param name="object" type="$unknown" dir="in">
1256	<desc>Local object to forward requests to.
1257	If null, clears currently set local object.</desc>
1258	</param>
1259	</method>
1260	</interface>
1261
1262	<!--
1263	// IVirtualBox
1264	/////////////////////////////////////////////////////////////////////////
1265	-->
1266
1267	<interface
1268	name="IVirtualBoxCallback" extends="$unknown"
1269	uuid="7f6a65b6-ad5d-4a67-8872-0b11cb7ea95c"
1270	wsmap="suppress"
1271	>
1272
1273	<method name="onMachineStateChange">
1274	<desc>
1275	The execution state of the given machine has changed.
1276	<see>IMachine::state</see>
1277	<result name="VBOX_E_DONT_CALL_AGAIN">
1278	Do not call again, this method is a NOP.
1279	</result>
1280	</desc>
1281	<param name="machineId" type="uuid" mod="string" dir="in">
1282	<desc>ID of the machine this event relates to.</desc>
1283	</param>
1284	<param name="state" type="MachineState" dir="in">
1285	<desc>New execution state.</desc>
1286	</param>
1287	</method>
1288
1289	<method name="onMachineDataChange">
1290	<desc>
1291	Any of the settings of the given machine has changed.
1292	<result name="VBOX_E_DONT_CALL_AGAIN">
1293	Do not call again, this method is a NOP.
1294	</result>
1295	</desc>
1296	<param name="machineId" type="uuid" mod="string" dir="in">
1297	<desc>ID of the machine this event relates to.</desc>
1298	</param>
1299	</method>
1300
1301	<method name="onExtraDataCanChange">
1302	<desc>
1303	Notification when someone tries to change extra data for
1304	either the given machine or (if @c null) global extra data.
1305	This gives the chance to veto against changes.
1306	<result name="VBOX_E_DONT_CALL_AGAIN">
1307	Do not call again, this method is a NOP. Change is allowed.
1308	</result>
1309	</desc>
1310	<param name="machineId" type="uuid" mod="string" dir="in">
1311	<desc>
1312	ID of the machine this event relates to
1313	(@c null ID for global extra data change requests).
1314	</desc>
1315	</param>
1316	<param name="key" type="wstring" dir="in">
1317	<desc>
1318	Extra data key for the attempted write.
1319	</desc>
1320	</param>
1321	<param name="value" type="wstring" dir="in">
1322	<desc>
1323	Extra data value for the given key.
1324	</desc>
1325	</param>
1326	<param name="error" type="wstring" dir="out">
1327	<desc>
1328	Optional error message describing the reason of the
1329	veto (ignored if this notification returns @c true).
1330	</desc>
1331	</param>
1332	<param name="allowChange" type="boolean" dir="return">
1333	<desc>
1334	Flag to indicate whether the callee agrees (@c true)
1335	or vetoes against the change (@c false).
1336	</desc>
1337	</param>
1338	</method>
1339
1340	<method name="onExtraDataChange">
1341	<desc>
1342	Notification when machine specific or global extra data
1343	has changed.
1344	<result name="VBOX_E_DONT_CALL_AGAIN">
1345	Do not call again, this method is a NOP.
1346	</result>
1347	</desc>
1348	<param name="machineId" type="uuid" mod="string" dir="in">
1349	<desc>
1350	ID of the machine this event relates to.
1351	Null for global extra data changes.
1352	</desc>
1353	</param>
1354	<param name="key" type="wstring" dir="in">
1355	<desc>
1356	Extra data key that has changed.
1357	</desc>
1358	</param>
1359	<param name="value" type="wstring" dir="in">
1360	<desc>
1361	Extra data value for the given key.
1362	</desc>
1363	</param>
1364	</method>
1365
1366	<method name="onMediumRegistered">
1367	<desc>
1368	The given medium was registered or unregistered
1369	within this VirtualBox installation.
1370
1371	The @a mediumType parameter describes what type of
1372	medium the specified @a mediumId refers to. Possible
1373	values are:
1374
1375	<ul>
1376	<li><link to="DeviceType_HardDisk"/>: the medium is a hard disk
1377	that, if registered, can be obtained using the
1378	<link to="IVirtualBox::getHardDisk"/> call.</li>
1379	<li><link to="DeviceType_DVD"/>: the medium is a CD/DVD image
1380	that, if registered, can be obtained using the
1381	<link to="IVirtualBox::getDVDImage"/> call.</li>
1382	<li><link to="DeviceType_Floppy"/>: the medium is a Floppy image
1383	that, if registered, can be obtained using the
1384	<link to="IVirtualBox::getFloppyImage"/> call.</li>
1385	</ul>
1386
1387	Note that if this is a deregistration notification,
1388	there is no way to access the object representing the
1389	unregistered medium. It is supposed that the
1390	application will do required cleanup based on the
1391	@a mediumId value.
1392
1393	<result name="VBOX_E_DONT_CALL_AGAIN">
1394	Do not call again, this method is a NOP.
1395	</result>
1396	</desc>
1397	<param name="mediumId" type="uuid" mod="string" dir="in">
1398	<desc>ID of the medium this event relates to.</desc>
1399	</param>
1400	<param name="mediumType" type="DeviceType" dir="in">
1401	<desc>Type of the medium this event relates to.</desc>
1402	</param>
1403	<param name="registered" type="boolean" dir="in">
1404	<desc>
1405	If @c true, the medium was registered, otherwise it was
1406	unregistered.
1407	</desc>
1408	</param>
1409	</method>
1410
1411	<method name="onMachineRegistered">
1412	<desc>
1413	The given machine was registered or unregistered
1414	within this VirtualBox installation.
1415	<result name="VBOX_E_DONT_CALL_AGAIN">
1416	Do not call again, this method is a NOP.
1417	</result>
1418	</desc>
1419	<param name="machineId" type="uuid" mod="string" dir="in">
1420	<desc>ID of the machine this event relates to.</desc>
1421	</param>
1422	<param name="registered" type="boolean" dir="in">
1423	<desc>
1424	If @c true, the machine was registered, otherwise it was
1425	unregistered.
1426	</desc>
1427	</param>
1428	</method>
1429
1430	<method name="onSessionStateChange">
1431	<desc>
1432	The state of the session for the given machine was changed.
1433	<see>IMachine::sessionState</see>
1434	<result name="VBOX_E_DONT_CALL_AGAIN">
1435	Do not call again, this method is a NOP.
1436	</result>
1437	</desc>
1438	<param name="machineId" type="uuid" mod="string" dir="in">
1439	<desc>ID of the machine this event relates to.</desc>
1440	</param>
1441	<param name="state" type="SessionState" dir="in">
1442	<desc>New session state.</desc>
1443	</param>
1444	</method>
1445
1446	<method name="onSnapshotTaken">
1447	<desc>
1448	A new snapshot of the machine has been taken.
1449	<see>ISnapshot</see>
1450	<result name="VBOX_E_DONT_CALL_AGAIN">
1451	Do not call again, this method is a NOP.
1452	</result>
1453	</desc>
1454	<param name="machineId" type="uuid" mod="string" dir="in">
1455	<desc>ID of the machine this event relates to.</desc>
1456	</param>
1457	<param name="snapshotId" type="uuid" mod="string" dir="in">
1458	<desc>ID of the new snapshot.</desc>
1459	</param>
1460	</method>
1461
1462	<method name="onSnapshotDeleted">
1463	<desc>
1464	Snapshot of the given machine has been deleted.
1465
1466	<note>
1467	This notification is delivered <b>after</b> the snapshot
1468	object has been uninitialized on the server (so that any
1469	attempt to call its methods will return an error).
1470	</note>
1471
1472	<see>ISnapshot</see>
1473
1474	<result name="VBOX_E_DONT_CALL_AGAIN">
1475	Do not call again, this method is a NOP.
1476	</result>
1477	</desc>
1478	<param name="machineId" type="uuid" mod="string" dir="in">
1479	<desc>ID of the machine this event relates to.</desc>
1480	</param>
1481	<param name="snapshotId" type="uuid" mod="string" dir="in">
1482	<desc>
1483	ID of the deleted snapshot. @c null means the current machine
1484	state has been deleted (restored from the current snapshot).
1485	</desc>
1486	</param>
1487	</method>
1488
1489	<method name="onSnapshotChange">
1490	<desc>
1491	Snapshot properties (name and/or description) have been changed.
1492	<see>ISnapshot</see>
1493	<result name="VBOX_E_DONT_CALL_AGAIN">
1494	Do not call again, this method is a NOP.
1495	</result>
1496	</desc>
1497	<param name="machineId" type="uuid" mod="string" dir="in">
1498	<desc>ID of the machine this event relates to.</desc>
1499	</param>
1500	<param name="snapshotId" type="uuid" mod="string" dir="in">
1501	<desc>ID of the changed snapshot.</desc>
1502	</param>
1503	</method>
1504
1505	<method name="onGuestPropertyChange">
1506	<desc>
1507	Notification when a guest property has changed.
1508	<result name="VBOX_E_DONT_CALL_AGAIN">
1509	Do not call again, this method is a NOP.
1510	</result>
1511	</desc>
1512	<param name="machineId" type="uuid" mod="string" dir="in">
1513	<desc>
1514	ID of the machine this event relates to.
1515	</desc>
1516	</param>
1517	<param name="name" type="wstring" dir="in">
1518	<desc>
1519	The name of the property that has changed.
1520	</desc>
1521	</param>
1522	<param name="value" type="wstring" dir="in">
1523	<desc>
1524	The new property value.
1525	</desc>
1526	</param>
1527	<param name="flags" type="wstring" dir="in">
1528	<desc>
1529	The new property flags.
1530	</desc>
1531	</param>
1532	</method>
1533
1534	</interface>
1535
1536	<interface
1537	name="IDHCPServer" extends="$unknown"
1538	uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1539	wsmap="managed"
1540	>
1541	<desc>
1542	The IDHCPServer interface represents the vbox dhcp server configuration.
1543
1544	To enumerate all the dhcp servers on the host, use the
1545	<link to="IVirtualBox::DHCPServers"/> attribute.
1546	</desc>
1547
1548	<attribute name="enabled" type="boolean">
1549	<desc>
1550	specifies if the dhcp server is enabled
1551	</desc>
1552	</attribute>
1553
1554	<attribute name="IPAddress" type="wstring" readonly="yes">
1555	<desc>
1556	specifies server IP
1557	</desc>
1558	</attribute>
1559
1560	<attribute name="networkMask" type="wstring" readonly="yes">
1561	<desc>
1562	specifies server network mask
1563	</desc>
1564	</attribute>
1565
1566	<attribute name="networkName" type="wstring" readonly="yes">
1567	<desc>
1568	specifies internal network name the server is used for
1569	</desc>
1570	</attribute>
1571
1572	<attribute name="lowerIP" type="wstring" readonly="yes">
1573	<desc>
1574	specifies from IP adrres in server address range
1575	</desc>
1576	</attribute>
1577
1578	<attribute name="upperIP" type="wstring" readonly="yes">
1579	<desc>
1580	specifies to IP adrres in server address range
1581	</desc>
1582	</attribute>
1583
1584	<method name="setConfiguration">
1585	<desc>
1586	configures the server
1587	<result name="E_INVALIDARG">
1588	invalid configuration supplied
1589	</result>
1590	</desc>
1591	<param name="IPAddress" type="wstring" dir="in">
1592	<desc>
1593	server IP address
1594	</desc>
1595	</param>
1596	<param name="networkMask" type="wstring" dir="in">
1597	<desc>
1598	server network mask
1599	</desc>
1600	</param>
1601	<param name="FromIPAddress" type="wstring" dir="in">
1602	<desc>
1603	server From IP address for address range
1604	</desc>
1605	</param>
1606	<param name="ToIPAddress" type="wstring" dir="in">
1607	<desc>
1608	server To IP address for address range
1609	</desc>
1610	</param>
1611	</method>
1612
1613	<method name="start">
1614	<desc>
1615	Starts DHCP server process.
1616	<result name="E_FAIL">
1617	Failed to start the process.
1618	</result>
1619	</desc>
1620	<param name="networkName" type="wstring" dir="in">
1621	<desc>
1622	Name of internal network DHCP server should attach to.
1623	</desc>
1624	</param>
1625	<param name="trunkName" type="wstring" dir="in">
1626	<desc>
1627	Name of internal network trunk.
1628	</desc>
1629	</param>
1630	<param name="trunkType" type="wstring" dir="in">
1631	<desc>
1632	Type of internal network trunk.
1633	</desc>
1634	</param>
1635	</method>
1636
1637	<method name="stop">
1638	<desc>
1639	Stops DHCP server process.
1640	<result name="E_FAIL">
1641	Failed to stop the process.
1642	</result>
1643	</desc>
1644	</method>
1645	</interface>
1646
1647	<interface
1648	name="IVirtualBox" extends="$unknown"
1649	uuid="3f36e024-7fed-4f20-a02c-9158a82b44e6"
1650	wsmap="managed"
1651	>
1652	<desc>
1653	The IVirtualBox interface represents the main interface exposed by the
1654	product that provides virtual machine management.
1655
1656	An instance of IVirtualBox is required for the product to do anything
1657	useful. Even though the interface does not expose this, internally,
1658	IVirtualBox is implemented as a singleton and actually lives in the
1659	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1660	IVirtualBox can track the state of all virtual machines on a particular
1661	host, regardless of which frontend started them.
1662
1663	To enumerate all the virtual machines on the host, use the
1664	<link to="IVirtualBox::machines"/> attribute.
1665	</desc>
1666
1667	<attribute name="version" type="wstring" readonly="yes">
1668	<desc>
1669	A string representing the version number of the product. The
1670	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1671	last number represents the build number and will frequently change.
1672	</desc>
1673	</attribute>
1674
1675	<attribute name="revision" type="unsigned long" readonly="yes">
1676	<desc>
1677	The internal build revision number of the product.
1678	</desc>
1679	</attribute>
1680
1681	<attribute name="packageType" type="wstring" readonly="yes">
1682	<desc>
1683	A string representing the package type of this product. The
1684	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1685	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1686	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1687	this.
1688	</desc>
1689	</attribute>
1690
1691	<attribute name="homeFolder" type="wstring" readonly="yes">
1692	<desc>
1693	Full path to the directory where the global settings file,
1694	<tt>VirtualBox.xml</tt>, is stored.
1695
1696	In this version of VirtualBox, the value of this property is
1697	always <tt><user_dir>/.VirtualBox</tt> (where
1698	<tt><user_dir></tt> is the path to the user directory,
1699	as determined by the host OS), and cannot be changed.
1700
1701	This path is also used as the base to resolve relative paths in
1702	places where relative paths are allowed (unless otherwise
1703	expressly indicated).
1704	</desc>
1705	</attribute>
1706
1707	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1708	<desc>
1709	Full name of the global settings file.
1710	The value of this property corresponds to the value of
1711	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1712	</desc>
1713	</attribute>
1714
1715	<attribute name="host" type="IHost" readonly="yes">
1716	<desc>Associated host object.</desc>
1717	</attribute>
1718
1719	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1720	<desc>Associated system information object.</desc>
1721	</attribute>
1722
1723	<attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1724	<desc>
1725	Array of machine objects registered within this VirtualBox instance.
1726	</desc>
1727	</attribute>
1728
1729	<attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1730	<desc>
1731	Array of medium objects known to this VirtualBox installation.
1732
1733	This array contains only base media. All differencing
1734	media of the given base medium can be enumerated using
1735	<link to="IMedium::children"/>.
1736	</desc>
1737	</attribute>
1738
1739	<attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1740	<desc>
1741	Array of CD/DVD image objects registered with this VirtualBox instance.
1742	</desc>
1743	</attribute>
1744
1745	<attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1746	<desc>
1747	Array of floppy image objects registered with this VirtualBox instance.
1748	</desc>
1749	</attribute>
1750
1751	<attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1752
1753	<attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1754
1755	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1756	<desc>
1757	Collection of global shared folders. Global shared folders are
1758	available to all virtual machines.
1759
1760	New shared folders are added to the collection using
1761	<link to="#createSharedFolder"/>. Existing shared folders can be
1762	removed using <link to="#removeSharedFolder"/>.
1763
1764	<note>
1765	In the current version of the product, global shared folders are not
1766	implemented and therefore this collection is always empty.
1767	</note>
1768	</desc>
1769	</attribute>
1770
1771	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1772	<desc>
1773	Associated performance collector object.
1774	</desc>
1775	</attribute>
1776
1777	<attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1778	<desc>
1779	dhcp server settings.
1780	</desc>
1781	</attribute>
1782
1783	<method name="createMachine">
1784	<desc>
1785	Creates a new virtual machine.
1786
1787	The new machine is created unregistered, with the initial configuration
1788	set according to the specified guest OS type. A typical sequence of
1789	actions to create a new virtual machine is as follows:
1790
1791	<ol>
1792	<li>
1793	Call this method to have a new machine created. The returned machine
1794	object will be "mutable" allowing to change any machine property.
1795	</li>
1796
1797	<li>
1798	Configure the machine using the appropriate attributes and methods.
1799	</li>
1800
1801	<li>
1802	Call <link to="IMachine::saveSettings" /> to write the settings
1803	to the machine's XML settings file. The configuration of the newly
1804	created machine will not be saved to disk until this method is
1805	called.
1806	</li>
1807
1808	<li>
1809	Call <link to="#registerMachine" /> to add the machine to the list
1810	of machines known to VirtualBox.
1811	</li>
1812	</ol>
1813
1814	You should specify valid name for the newly created machine when calling
1815	this method. See the <link to="IMachine::name"/> attribute description
1816	for more details about the machine name.
1817
1818	The specified guest OS type identifier must match an ID of one of known
1819	guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1820	array.
1821
1822	Every machine has a <i>settings file</i> that is used to store
1823	the machine configuration. This file is stored in a directory called the
1824	<i>machine settings subfolder</i>. Both the settings subfolder and file
1825	will have a name that corresponds to the name of the virtual machine.
1826	You can specify where to create the machine setting subfolder using the
1827	@a baseFolder argument. The base folder can be absolute (full path) or
1828	relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1829	directory</link>.
1830
1831	If @a baseFolder is a @c null or empty string (which is recommended), the
1832	<link to="ISystemProperties::defaultMachineFolder">default machine
1833	settings folder</link> will be used as a base folder for the created
1834	machine. Otherwise the given base folder will be used. In either case,
1835	the full path to the resulting settings file has the following
1836	structure:
1837	<pre>
1838	<base_folder>/<machine_name>/<machine_name>.xml
1839	</pre>
1840
1841	Note that if the resulting settings file already exists, this method
1842	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1843
1844	Optionally, you may specify an UUID of to assign to the created machine.
1845	However, this is not recommended and you should normally pass an empty
1846	(@c null) UUID to this method so that a new UUID will be automatically
1847	generated for every created machine. You can use UUID
1848	00000000-0000-0000-0000-000000000000 as @c null value.
1849
1850	<note>
1851	There is no way to change the name of the settings file or
1852	subfolder of the created machine directly.
1853	</note>
1854
1855	<result name="VBOX_E_OBJECT_NOT_FOUND">
1856	@a osTypeId is invalid.
1857	</result>
1858	<result name="VBOX_E_FILE_ERROR">
1859	Resulting settings file name is invalid or the settings file already
1860	exists or could not be created due to an I/O error.
1861	</result>
1862	<result name="E_INVALIDARG">
1863	@a name is empty or @c null.
1864	</result>
1865	</desc>
1866
1867	<param name="name" type="wstring" dir="in">
1868	<desc>Machine name.</desc>
1869	</param>
1870	<param name="osTypeId" type="wstring" dir="in">
1871	<desc>Guest OS Type ID.</desc>
1872	</param>
1873	<param name="baseFolder" type="wstring" dir="in">
1874	<desc>Base machine folder (optional).</desc>
1875	</param>
1876	<param name="id" type="uuid" mod="string" dir="in">
1877	<desc>Machine UUID (optional).</desc>
1878	</param>
1879	<param name="override" type="boolean" dir="in">
1880	<desc>Create the VM even if there are conflicting files.</desc>
1881	</param>
1882	<param name="machine" type="IMachine" dir="return">
1883	<desc>Created machine object.</desc>
1884	</param>
1885	</method>
1886
1887	<method name="createLegacyMachine">
1888	<desc>
1889	Creates a new virtual machine in "legacy" mode, using the specified
1890	settings file to store machine settings.
1891
1892	As opposed to machines created by <link to="#createMachine"/>,
1893	the settings file of the machine created in "legacy" mode is not
1894	automatically renamed when the machine name is changed -- it will always
1895	remain the same as specified in this method call.
1896
1897	The specified settings file name can be absolute (full path) or relative
1898	to the <link to="IVirtualBox::homeFolder">VirtualBox home
1899	directory</link>. If the file name doesn't contain an extension, the
1900	default extension (.xml) will be appended.
1901
1902	Note that the configuration of the newly created machine is not
1903	saved to disk (and therefore no settings file is created)
1904	until <link to="IMachine::saveSettings"/> is called. If the
1905	specified settings file already exists, this method
1906	will fail with <link to="VBOX_E_FILE_ERROR"/>.
1907
1908	See <link to="#createMachine"/> for more information.
1909
1910	@deprecated This method may be removed later. Use <link
1911	to="IVirtualBox::createMachine"/> instead.
1912
1913	<note>
1914	There is no way to change the name of the settings file
1915	of the machine created in "legacy" mode.
1916	</note>
1917
1918	<result name="VBOX_E_OBJECT_NOT_FOUND">
1919	@a osTypeId is invalid.
1920	</result>
1921	<result name="VBOX_E_FILE_ERROR">
1922	@a settingsFile is invalid or the settings file already exists or
1923	could not be created due to an I/O error.
1924	</result>
1925	<result name="E_INVALIDARG">
1926	@a name or @a settingsFile is empty or @c null.
1927	</result>
1928	</desc>
1929
1930	<param name="name" type="wstring" dir="in">
1931	<desc>Machine name.</desc>
1932	</param>
1933	<param name="osTypeId" type="wstring" dir="in">
1934	<desc>Machine OS Type ID.</desc>
1935	</param>
1936	<param name="settingsFile" type="wstring" dir="in">
1937	<desc>Name of the machine settings file.</desc>
1938	</param>
1939	<param name="id" type="uuid" mod="string" dir="in">
1940	<desc>Machine UUID (optional).</desc>
1941	</param>
1942	<param name="machine" type="IMachine" dir="return">
1943	<desc>Created machine object.</desc>
1944	</param>
1945	</method>
1946
1947	<method name="openMachine">
1948	<desc>
1949	Opens a virtual machine from the existing settings file.
1950	The opened machine remains unregistered until you call
1951	<link to="#registerMachine"/>.
1952
1953	The specified settings file name can be absolute
1954	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1955	VirtualBox home directory</link>. This file must exist
1956	and must be a valid machine settings file whose contents
1957	will be used to construct the machine object.
1958
1959	@deprecated Will be removed soon.
1960	<result name="VBOX_E_FILE_ERROR">
1961	Settings file name invalid, not found or sharing violation.
1962	</result>
1963	</desc>
1964	<param name="settingsFile" type="wstring" dir="in">
1965	<desc>
1966	Name of the machine settings file.
1967	</desc>
1968	</param>
1969	<param name="machine" type="IMachine" dir="return">
1970	<desc>Opened machine object.</desc>
1971	</param>
1972	<note>
1973	<link to="IMachine::settingsModified"/> will return
1974	@c false for the created machine, until any of machine settings
1975	are changed.
1976	</note>
1977	</method>
1978
1979	<method name="registerMachine">
1980	<desc>
1981
1982	Registers the machine previously created using
1983	<link to="#createMachine"/> or opened using
1984	<link to="#openMachine"/> within this VirtualBox installation. After
1985	successful method invocation, the
1986	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1987	to all registered callbacks.
1988
1989	<note>
1990	This method implicitly calls <link to="IMachine::saveSettings"/>
1991	to save all current machine settings before registering it.
1992	</note>
1993
1994	<result name="VBOX_E_OBJECT_NOT_FOUND">
1995	No matching virtual machine found.
1996	</result>
1997	<result name="VBOX_E_INVALID_OBJECT_STATE">
1998	Virtual machine was not created within this VirtualBox instance.
1999	</result>
2000
2001	</desc>
2002	<param name="machine" type="IMachine" dir="in"/>
2003	</method>
2004
2005	<method name="getMachine">
2006	<desc>
2007	Attempts to find a virtual machine given its UUID.
2008	To look up a machine by name, use <link to="IVirtualBox::findMachine" />
2009	instead.
2010
2011	<result name="VBOX_E_OBJECT_NOT_FOUND">
2012	Could not find registered machine matching @a id.
2013	</result>
2014
2015	</desc>
2016	<param name="id" type="uuid" mod="string" dir="in"/>
2017	<param name="machine" type="IMachine" dir="return"/>
2018	</method>
2019
2020	<method name="findMachine">
2021	<desc>
2022	Attempts to find a virtual machine given its name.
2023	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
2024	instead.
2025
2026	<result name="VBOX_E_OBJECT_NOT_FOUND">
2027	Could not find registered machine matching @a name.
2028	</result>
2029
2030	</desc>
2031	<param name="name" type="wstring" dir="in"/>
2032	<param name="machine" type="IMachine" dir="return"/>
2033	</method>
2034
2035	<method name="unregisterMachine">
2036	<desc>
2037
2038	Unregisters the machine previously registered using
2039	<link to="#registerMachine"/>. After successful method invocation, the
2040	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
2041	to all registered callbacks.
2042
2043	<note>
2044	The specified machine must not be in the Saved state, have an open
2045	(or a spawning) direct session associated with it, have snapshots or
2046	have any medium attached.
2047	</note>
2048
2049	<note>
2050	This method implicitly calls <link to="IMachine::saveSettings"/> to
2051	save all current machine settings before unregistering it.
2052	</note>
2053
2054	<note>
2055	If the given machine is inaccessible (see
2056	<link to="IMachine::accessible"/>), it will be unregistered and
2057	fully uninitialized right afterwards. As a result, the returned
2058	machine object will be unusable and an attempt to call
2059	<b>any</b> method will return the "Object not ready" error.
2060	</note>
2061
2062	<result name="VBOX_E_OBJECT_NOT_FOUND">
2063	Could not find registered machine matching @a id.
2064	</result>
2065	<result name="VBOX_E_INVALID_VM_STATE">
2066	Machine is in Saved state.
2067	</result>
2068	<result name="VBOX_E_INVALID_OBJECT_STATE">
2069	Machine has snapshot or open session or medium attached.
2070	</result>
2071
2072	</desc>
2073	<param name="id" type="uuid" mod="string" dir="in">
2074	<desc>UUID of the machine to unregister.</desc>
2075	</param>
2076	<param name="machine" type="IMachine" dir="return">
2077	<desc>Unregistered machine object.</desc>
2078	</param>
2079	</method>
2080
2081	<method name="createAppliance">
2082	<desc>
2083	Creates a new appliance object, which represents an appliance in the Open Virtual Machine
2084	Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
2085	machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
2086	</desc>
2087	<param name="appliance" type="IAppliance" dir="return">
2088	<desc>New appliance.</desc>
2089	</param>
2090	</method>
2091
2092	<method name="createHardDisk">
2093	<desc>
2094	Creates a new base medium object that will use the given storage
2095	format and location for medium data.
2096
2097	Note that the actual storage unit is not created by this method. In
2098	order to do it, and before you are able to attach the created medium
2099	to virtual machines, you must call one of the following methods to
2100	allocate a format-specific storage unit at the specified location:
2101	<ul>
2102	<li><link to="IMedium::createBaseStorage"/></li>
2103	<li><link to="IMedium::createDiffStorage"/></li>
2104	</ul>
2105
2106	Some medium attributes, such as <link to="IMedium::id"/>, may
2107	remain uninitialized until the medium storage unit is successfully
2108	created by one of the above methods.
2109
2110	After the storage unit is successfully created, the medium gets
2111	remembered by this VirtualBox installation and will be accessible
2112	through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
2113	methods. Remembered base medium are also returned as part of
2114	the <link to="#hardDisks"/> array. See IMedium for more details.
2115
2116	The list of all storage formats supported by this VirtualBox
2117	installation can be obtained using
2118	<link to="ISystemProperties::mediumFormats"/>. If the @a format
2119	attribute is empty or @c null then the default storage format
2120	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
2121	be used for creating a storage unit of the medium.
2122
2123	Note that the format of the location string is storage format specific.
2124	See <link to="IMedium::location"/>, IMedium and
2125	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2126
2127	<result name="VBOX_E_OBJECT_NOT_FOUND">
2128	@a format identifier is invalid. See
2129	<link to="ISystemProperties::mediumFormats"/>.
2130	</result>
2131	<result name="VBOX_E_FILE_ERROR">
2132	@a location is a not valid file name (for file-based formats only).
2133	</result>
2134	</desc>
2135	<param name="format" type="wstring" dir="in">
2136	<desc>
2137	Identifier of the storage format to use for the new medium.
2138	</desc>
2139	</param>
2140	<param name="location" type="wstring" dir="in">
2141	<desc>
2142	Location of the storage unit for the new medium.
2143	</desc>
2144	</param>
2145	<param name="medium" type="IMedium" dir="return">
2146	<desc>Created medium object.</desc>
2147	</param>
2148	</method>
2149
2150	<method name="openHardDisk">
2151	<desc>
2152	Opens a medium from an existing location, optionally replacing
2153	the image UUID and/or parent UUID.
2154
2155	After the medium is successfully opened by this method, it gets
2156	remembered by (known to) this VirtualBox installation and will be
2157	accessible through <link to="#getHardDisk"/> and
2158	<link to="#findHardDisk"/> methods. Remembered base media
2159	are also returned as part of the <link to="#hardDisks"/> array and can
2160	be attached to virtual machines. See IMedium for more details.
2161
2162	If a differencing medium is to be opened by this method, the
2163	operation will succeed only if its parent medium and all ancestors,
2164	if any, are already known to this VirtualBox installation (for example,
2165	were opened by this method before).
2166
2167	This method tries to guess the storage format of the specified medium
2168	by reading medium data at the specified location.
2169
2170	If @a accessMode is ReadWrite (which it should be), the image is opened
2171	for read/write access and must have according permissions, as VirtualBox
2172	may actually write status information into the disk's metadata sections.
2173
2174	Note that write access is required for all typical image usage in VirtualBox,
2175	since VirtualBox may need to write metadata such as a UUID into the image.
2176	The only exception is opening a source image temporarily for copying and
2177	cloning when the image will quickly be closed again.
2178
2179	Note that the format of the location string is storage format specific.
2180	See <link to="IMedium::location"/>, IMedium and
2181	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
2182
2183	<result name="VBOX_E_FILE_ERROR">
2184	Invalid medium storage file location or could not find the medium
2185	at the specified location.
2186	</result>
2187	<result name="VBOX_E_IPRT_ERROR">
2188	Could not get medium storage format.
2189	</result>
2190	<result name="E_INVALIDARG">
2191	Invalid medium storage format.
2192	</result>
2193
2194	</desc>
2195	<param name="location" type="wstring" dir="in">
2196	<desc>
2197	Location of the storage unit that contains medium data in one of
2198	the supported storage formats.
2199	</desc>
2200	</param>
2201	<param name="accessMode" type="AccessMode" dir="in">
2202	<desc>
2203	Determines whether to open the image in read/write or read-only mode.
2204	</desc>
2205	</param>
2206	<param name="setImageId" type="boolean" dir="in">
2207	<desc>
2208	Select whether a new image UUID is set or not.
2209	</desc>
2210	</param>
2211	<param name="imageId" type="uuid" mod="string" dir="in">
2212	<desc>
2213	New UUID for the image. If an empty string is passed, then a new
2214	UUID is automatically created. Specifying a zero UUIDs is not valid.
2215	</desc>
2216	</param>
2217	<param name="setParentId" type="boolean" dir="in">
2218	<desc>
2219	Select whether a new parent UUID is set or not.
2220	</desc>
2221	</param>
2222	<param name="parentId" type="uuid" mod="string" dir="in">
2223	<desc>
2224	New parent UUID for the image. If an empty string is passed, then a
2225	new UUID is automatically created, provided @a setParentId is
2226	@c true. A zero UUID is valid.
2227	</desc>
2228	</param>
2229	<param name="medium" type="IMedium" dir="return">
2230	<desc>Opened medium object.</desc>
2231	</param>
2232	</method>
2233
2234	<method name="getHardDisk" const="yes">
2235	<desc>
2236	Returns a medium with the given UUID.
2237
2238	The medium with the given UUID must be known to this VirtualBox
2239	installation, i.e. it must be previously created by
2240	<link to="#createHardDisk"/> or opened by <link
2241	to="#openHardDisk"/>, or attached to some known virtual machine.
2242
2243	<result name="VBOX_E_OBJECT_NOT_FOUND">
2244	No medium object matching @a id found.
2245	</result>
2246
2247	</desc>
2248	<param name="id" type="uuid" mod="string" dir="in">
2249	<desc>UUID of the medium to look for.</desc>
2250	</param>
2251	<param name="medium" type="IMedium" dir="return">
2252	<desc>Found medium object.</desc>
2253	</param>
2254	</method>
2255
2256	<method name="findHardDisk">
2257	<desc>
2258	Returns a medium that uses the given location to store medium data.
2259
2260	The given medium must be known to this VirtualBox installation, i.e.
2261	it must be previously created by
2262	<link to="#createHardDisk"/> or opened by <link
2263	to="#openHardDisk"/>, or attached to some known virtual machine.
2264
2265	The search is done by comparing the value of the @a location argument to
2266	the <link to="IMedium::location"/> attribute of each known medium.
2267
2268	For locations represented by file names in the host's file system, the
2269	requested location can be a path relative to the
2270	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2271	only a file name without any path is given, the
2272	<link to="ISystemProperties::defaultHardDiskFolder"> default medium
2273	folder</link> will be prepended to the file name before searching. Note
2274	that on case sensitive file systems, a case sensitive comparison is
2275	performed, otherwise the case of symbols in the file path is ignored.
2276
2277	<result name="VBOX_E_OBJECT_NOT_FOUND">
2278	No medium object matching @a location found.
2279	</result>
2280
2281	</desc>
2282	<param name="location" type="wstring" dir="in">
2283	<desc>Location string to search for.</desc>
2284	</param>
2285	<param name="medium" type="IMedium" dir="return">
2286	<desc>Found medium object.</desc>
2287	</param>
2288	</method>
2289
2290	<method name="openDVDImage">
2291	<desc>
2292	Opens a CD/DVD image contained in the specified file of the supported
2293	format and assigns it the given UUID.
2294
2295	After the image is successfully opened by this method, it gets
2296	remembered by (known to) this VirtualBox installation and will be
2297	accessible through <link to="#getDVDImage"/> and
2298	<link to="#findDVDImage"/> methods. Remembered images are also
2299	returned as part of the <link to="#DVDImages"/> array and can be mounted
2300	to virtual machines. See IMedium for more details.
2301
2302	See <link to="IMedium::location"/> to get more details about the format
2303	of the location string.
2304
2305	<note>
2306	Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
2307	</note>
2308
2309	<result name="VBOX_E_FILE_ERROR">
2310	Invalid CD/DVD image file location or could not find the CD/DVD
2311	image at the specified location.
2312	</result>
2313	<result name="VBOX_E_INVALID_OBJECT_STATE">
2314	CD/DVD image already exists in the media registry.
2315	</result>
2316
2317	</desc>
2318	<param name="location" type="wstring" dir="in">
2319	<desc>
2320	Full path to the file that contains a valid CD/DVD image.
2321	</desc>
2322	</param>
2323	<param name="id" type="uuid" mod="string" dir="in">
2324	<desc>
2325	UUID to assign to the given image within this VirtualBox installation.
2326	If an empty (@c null) UUID is specified, the system will randomly
2327	generate a new UUID.
2328	</desc>
2329	</param>
2330	<param name="image" type="IMedium" dir="return">
2331	<desc>Opened CD/DVD image object.</desc>
2332	</param>
2333	</method>
2334
2335	<method name="getDVDImage">
2336	<desc>
2337	Returns a CD/DVD image with the given UUID.
2338
2339	The image with the given UUID must be known to this VirtualBox
2340	installation, i.e. it must be previously opened by <link
2341	to="#openDVDImage"/>, or mounted to some known virtual machine.
2342
2343	<result name="VBOX_E_OBJECT_NOT_FOUND">
2344	No matching DVD image found in the media registry.
2345	</result>
2346
2347	</desc>
2348	<param name="id" type="uuid" mod="string" dir="in">
2349	<desc>UUID of the image to look for.</desc>
2350	</param>
2351	<param name="image" type="IMedium" dir="return">
2352	<desc>Found CD/DVD image object.</desc>
2353	</param>
2354	</method>
2355
2356	<method name="findDVDImage">
2357	<desc>
2358	Returns a CD/DVD image with the given image location.
2359
2360	The image with the given UUID must be known to this VirtualBox
2361	installation, i.e. it must be previously opened by <link
2362	to="#openDVDImage"/>, or mounted to some known virtual machine.
2363
2364	The search is done by comparing the value of the @a location argument to
2365	the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2366
2367	The requested location can be a path relative to the
2368	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2369	only a file name without any path is given, the
2370	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2371	folder</link> will be prepended to the file name before searching. Note
2372	that on case sensitive file systems, a case sensitive comparison is
2373	performed, otherwise the case in the file path is ignored.
2374
2375	<result name="VBOX_E_FILE_ERROR">
2376	Invalid image file location.
2377	</result>
2378	<result name="VBOX_E_OBJECT_NOT_FOUND">
2379	No matching DVD image found in the media registry.
2380	</result>
2381
2382	</desc>
2383	<param name="location" type="wstring" dir="in">
2384	<desc>CD/DVD image file path to look for.</desc>
2385	</param>
2386	<param name="image" type="IMedium" dir="return">
2387	<desc>Found CD/DVD image object.</desc>
2388	</param>
2389	</method>
2390
2391	<method name="openFloppyImage">
2392	<desc>
2393	Opens a floppy image contained in the specified file of the supported
2394	format and assigns it the given UUID.
2395
2396	After the image is successfully opened by this method, it gets
2397	remembered by (known to) this VirtualBox installation and will be
2398	accessible through <link to="#getFloppyImage"/> and
2399	<link to="#findFloppyImage"/> methods. Remembered images are also
2400	returned as part of the <link to="#floppyImages"/> array and can be
2401	mounted to virtual machines. See IMedium for more details.
2402
2403	See <link to="IMedium::location"/> to get more details about the format
2404	of the location string.
2405
2406	<result name="VBOX_E_FILE_ERROR">
2407	Invalid floppy image file location or could not find the floppy
2408	image at the specified location.
2409	</result>
2410	<result name="VBOX_E_INVALID_OBJECT_STATE">
2411	Floppy image already exists in the media registry.
2412	</result>
2413
2414	<note>
2415	Currently, only raw floppy images are supported by VirtualBox.
2416	</note>
2417	</desc>
2418	<param name="location" type="wstring" dir="in">
2419	<desc>
2420	Full path to the file that contains a valid floppy image.
2421	</desc>
2422	</param>
2423	<param name="id" type="uuid" mod="string" dir="in">
2424	<desc>
2425	UUID to assign to the given image file within this VirtualBox
2426	installation. If an empty (@c null) UUID is specified, the system will
2427	randomly generate a new UUID.
2428	</desc>
2429	</param>
2430	<param name="image" type="IMedium" dir="return">
2431	<desc>Opened floppy image object.</desc>
2432	</param>
2433	</method>
2434
2435	<method name="getFloppyImage">
2436	<desc>
2437	Returns a floppy image with the given UUID.
2438
2439	The image with the given UUID must be known to this VirtualBox
2440	installation, i.e. it must be previously opened by <link
2441	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2442
2443	<result name="VBOX_E_OBJECT_NOT_FOUND">
2444	No matching floppy image found in the media registry.
2445	</result>
2446
2447	</desc>
2448	<param name="id" type="uuid" mod="string" dir="in">
2449	<desc>UUID of the image to look for.</desc>
2450	</param>
2451	<param name="image" type="IMedium" dir="return">
2452	<desc>Found floppy image object.</desc>
2453	</param>
2454	</method>
2455
2456	<method name="findFloppyImage">
2457	<desc>
2458	Returns a floppy image with the given image location.
2459
2460	The image with the given UUID must be known to this VirtualBox
2461	installation, i.e. it must be previously opened by <link
2462	to="#openFloppyImage"/>, or mounted to some known virtual machine.
2463
2464	The search is done by comparing the value of the @a location argument to
2465	the <link to="IMedium::location"/> attribute of each known floppy image.
2466
2467	The requested location can be a path relative to the
2468	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2469	only a file name without any path is given, the
2470	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2471	folder</link> will be prepended to the file name before searching. Note
2472	that on case sensitive file systems, a case sensitive comparison is
2473	performed, otherwise the case of symbols in the file path is ignored.
2474
2475	<result name="VBOX_E_FILE_ERROR">
2476	Invalid image file location.
2477	</result>
2478	<result name="VBOX_E_OBJECT_NOT_FOUND">
2479	No matching floppy image found in the media registry.
2480	</result>
2481
2482	</desc>
2483	<param name="location" type="wstring" dir="in">
2484	<desc>Floppy image file path to look for.</desc>
2485	</param>
2486	<param name="image" type="IMedium" dir="return">
2487	<desc>Found floppy image object.</desc>
2488	</param>
2489	</method>
2490
2491	<method name="getGuestOSType">
2492	<desc>
2493	Returns an object describing the specified guest OS type.
2494
2495	The requested guest OS type is specified using a string which is a
2496	mnemonic identifier of the guest operating system, such as
2497	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2498	particular virtual machine can be read or set using the
2499	<link to="IMachine::OSTypeId"/> attribute.
2500
2501	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2502	available guest OS type objects. Each object has an
2503	<link to="IGuestOSType::id"/> attribute which contains an identifier of
2504	the guest OS this object describes.
2505
2506	<result name="E_INVALIDARG">
2507	@a id is not a valid Guest OS type.
2508	</result>
2509
2510	</desc>
2511	<param name="id" type="uuid" mod="string" dir="in">
2512	<desc>Guest OS type ID string.</desc>
2513	</param>
2514	<param name="type" type="IGuestOSType" dir="return">
2515	<desc>Guest OS type object.</desc>
2516	</param>
2517	</method>
2518
2519	<method name="createSharedFolder">
2520	<desc>
2521	Creates a new global shared folder by associating the given logical
2522	name with the given host path, adds it to the collection of shared
2523	folders and starts sharing it. Refer to the description of
2524	<link to="ISharedFolder"/> to read more about logical names.
2525	<note>
2526	In the current implementation, this operation is not
2527	implemented.
2528	</note>
2529	</desc>
2530	<param name="name" type="wstring" dir="in">
2531	<desc>Unique logical name of the shared folder.</desc>
2532	</param>
2533	<param name="hostPath" type="wstring" dir="in">
2534	<desc>Full path to the shared folder in the host file system.</desc>
2535	</param>
2536	<param name="writable" type="boolean" dir="in">
2537	<desc>Whether the share is writable or readonly</desc>
2538	</param>
2539	</method>
2540
2541	<method name="removeSharedFolder">
2542	<desc>
2543	Removes the global shared folder with the given name previously
2544	created by <link to="#createSharedFolder"/> from the collection of
2545	shared folders and stops sharing it.
2546	<note>
2547	In the current implementation, this operation is not
2548	implemented.
2549	</note>
2550	</desc>
2551	<param name="name" type="wstring" dir="in">
2552	<desc>Logical name of the shared folder to remove.</desc>
2553	</param>
2554	</method>
2555
2556	<method name="getExtraDataKeys">
2557	<desc>
2558	Returns an array representing the global extra data keys which currently
2559	have values defined.
2560	</desc>
2561	<param name="value" type="wstring" dir="return" safearray="yes">
2562	<desc>Array of extra data keys.</desc>
2563	</param>
2564	</method>
2565
2566	<method name="getExtraData">
2567	<desc>
2568	Returns associated global extra data.
2569
2570	If the requested data @a key does not exist, this function will
2571	succeed and return an empty string in the @a value argument.
2572
2573	<result name="VBOX_E_FILE_ERROR">
2574	Settings file not accessible.
2575	</result>
2576	<result name="VBOX_E_XML_ERROR">
2577	Could not parse the settings file.
2578	</result>
2579
2580	</desc>
2581	<param name="key" type="wstring" dir="in">
2582	<desc>Name of the data key to get.</desc>
2583	</param>
2584	<param name="value" type="wstring" dir="return">
2585	<desc>Value of the requested data key.</desc>
2586	</param>
2587	</method>
2588
2589	<method name="setExtraData">
2590	<desc>
2591	Sets associated global extra data.
2592
2593	If you pass @c null or empty string as a key @a value, the given @a key
2594	will be deleted.
2595
2596	<note>
2597	Before performing the actual data change, this method will ask all
2598	registered callbacks using the
2599	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2600	notification for a permission. If one of the callbacks refuses the
2601	new value, the change will not be performed.
2602	</note>
2603	<note>
2604	On success, the
2605	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2606	is called to inform all registered callbacks about a successful data
2607	change.
2608	</note>
2609
2610	<result name="VBOX_E_FILE_ERROR">
2611	Settings file not accessible.
2612	</result>
2613	<result name="VBOX_E_XML_ERROR">
2614	Could not parse the settings file.
2615	</result>
2616	<result name="E_ACCESSDENIED">
2617	Modification request refused.
2618	</result>
2619
2620	</desc>
2621	<param name="key" type="wstring" dir="in">
2622	<desc>Name of the data key to set.</desc>
2623	</param>
2624	<param name="value" type="wstring" dir="in">
2625	<desc>Value to assign to the key.</desc>
2626	</param>
2627	</method>
2628
2629	<method name="openSession">
2630	<desc>
2631	Opens a new direct session with the given virtual machine.
2632
2633	A direct session acts as a local lock on the given VM.
2634	There can be only one direct session open at a time for every
2635	virtual machine, protecting the VM from being manipulated by
2636	conflicting actions from different processes. Only after a
2637	direct session has been opened, one can change all VM settings
2638	and execute the VM in the process space of the session object.
2639
2640	Sessions therefore can be compared to mutex semaphores that
2641	lock a given VM for modification and execution.
2642	See <link to="ISession">ISession</link> for details.
2643
2644	<note>Unless you are writing a new VM frontend, you will not
2645	want to execute a VM in the current process. To spawn a new
2646	process that executes a VM, use
2647	<link to="IVirtualBox::openRemoteSession" />
2648	instead.</note>
2649
2650	Upon successful return, the session object can be used to
2651	get access to the machine and to the VM console.
2652
2653	In VirtualBox terminology, the machine becomes "mutable" after
2654	a session has been opened. Note that the "mutable" machine
2655	object, on which you may invoke IMachine methods to change its
2656	settings, will be a different object from the immutable IMachine
2657	objects returned by various IVirtualBox methods. To obtain a
2658	mutable IMachine object (upon which you can invoke settings methods),
2659	use the <link to="ISession::machine" /> attribute.
2660
2661	One must always call <link to="ISession::close" /> to release the
2662	lock on the machine, or the machine's state will eventually be
2663	set to "Aborted".
2664
2665	In other words, to change settings on a machine, the following
2666	sequence is typically performed:
2667
2668	<ol>
2669	<li>Call this method (openSession) to have a machine locked for
2670	the current session.</li>
2671
2672	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2673
2674	<li>Change the settings of the machine.</li>
2675
2676	<li>Call <link to="IMachine::saveSettings" />.</li>
2677
2678	<li>Close the session by calling <link to="ISession::close"/>.</li>
2679	</ol>
2680
2681	<result name="E_UNEXPECTED">
2682	Virtual machine not registered.
2683	</result>
2684	<result name="E_ACCESSDENIED">
2685	Process not started by OpenRemoteSession.
2686	</result>
2687	<result name="VBOX_E_OBJECT_NOT_FOUND">
2688	No matching virtual machine found.
2689	</result>
2690	<result name="VBOX_E_INVALID_OBJECT_STATE">
2691	Session already open or being opened.
2692	</result>
2693	<result name="VBOX_E_VM_ERROR">
2694	Failed to assign machine to session.
2695	</result>
2696
2697	</desc>
2698	<param name="session" type="ISession" dir="in">
2699	<desc>
2700	Session object that will represent the opened session after
2701	successful method invocation. This object must not represent
2702	the already open session.
2703	<note>
2704	This session will be automatically closed if the
2705	VirtualBox server is terminated for some reason.
2706	</note>
2707	</desc>
2708	</param>
2709	<param name="machineId" type="uuid" mod="string" dir="in">
2710	<desc>ID of the virtual machine to open a session with.</desc>
2711	</param>
2712	</method>
2713
2714	<method name="openRemoteSession">
2715	<desc>
2716	Spawns a new process that executes a virtual machine (called a
2717	"remote session").
2718
2719	Opening a remote session causes the VirtualBox server to start a new
2720	process that opens a direct session with the given VM. As a result, the
2721	VM is locked by that direct session in the new process, preventing
2722	conflicting changes from other processes. Since sessions act as locks
2723	that prevent conflicting changes, one cannot open a remote session
2724	for a VM that already has another open session (direct or remote), or
2725	is currently in the process of opening one (see <link
2726	to="IMachine::sessionState"/>).
2727
2728	While the remote session still provides some level of control over the
2729	VM execution to the caller (using the <link to="IConsole" /> interface),
2730	not all VM settings are available for modification within the remote
2731	session context.
2732
2733	This operation can take some time (a new VM is started in a new process,
2734	for which memory and other resources need to be set up). Because of this,
2735	an <link to="IProgress" /> is returned to allow the caller to wait for this
2736	asynchronous operation to be completed. Until then, the remote session
2737	object remains in the closed state, and accessing the machine or its
2738	console through it is invalid. It is recommended to use
2739	<link to="IProgress::waitForCompletion" /> or similar calls to wait for
2740	completion. Completion is signalled when the VM is powered on. Error
2741	messages etc. can be queried via the progress object, if available.
2742
2743	As with all <link to="ISession" /> objects, it is recommended to call
2744	<link to="ISession::close" /> on the local session object once openRemoteSession()
2745	has been called. However, the session's state (see <link to="ISession::state" />)
2746	will not return to "Closed" until the remote session has also closed (i.e.
2747	until the VM is no longer running). In that case, however, the state of
2748	the session will automatically change back to "Closed".
2749
2750	Currently supported session types (values of the @a type
2751	argument) are:
2752	<ul>
2753	<li><tt>"gui"</tt>: VirtualBox Qt GUI session</li>
2754	<li><tt>"vrdp"</tt>: VirtualBox VRDP Server session</li>
2755	<li><tt>"sdl"</tt>: VirtualBox SDL GUI session</li>
2756	</ul>
2757
2758	The @a environment argument is a string containing definitions of
2759	environment variables in the following format:
2760	@code
2761	NAME[=VALUE]\n
2762	NAME[=VALUE]\n
2763	...
2764	@endcode
2765	where <tt>\\n</tt> is the new line character. These environment
2766	variables will be appended to the environment of the VirtualBox server
2767	process. If an environment variable exists both in the server process
2768	and in this list, the value from this list takes precedence over the
2769	server's variable. If the value of the environment variable is
2770	omitted, this variable will be removed from the resulting environment.
2771	If the environment string is @c null or empty, the server environment
2772	is inherited by the started process as is.
2773
2774	<see>openExistingSession</see>
2775
2776	<result name="E_UNEXPECTED">
2777	Virtual machine not registered.
2778	</result>
2779	<result name="E_INVALIDARG">
2780	Invalid session type @a type.
2781	</result>
2782	<result name="VBOX_E_OBJECT_NOT_FOUND">
2783	No machine matching @a machineId found.
2784	</result>
2785	<result name="VBOX_E_INVALID_OBJECT_STATE">
2786	Session already open or being opened.
2787	</result>
2788	<result name="VBOX_E_IPRT_ERROR">
2789	Launching process for machine failed.
2790	</result>
2791	<result name="VBOX_E_VM_ERROR">
2792	Failed to assign machine to session.
2793	</result>
2794
2795	</desc>
2796	<param name="session" type="ISession" dir="in">
2797	<desc>
2798	Session object that will represent the opened remote session
2799	after successful method invocation (this object must not
2800	represent an already open session).
2801	</desc>
2802	</param>
2803	<param name="machineId" type="uuid" mod="string" dir="in">
2804	<desc>ID of the virtual machine to open a session with.</desc>
2805	</param>
2806	<param name="type" type="wstring" dir="in">
2807	<desc>
2808	Type of the remote session (case sensitive).
2809	</desc>
2810	</param>
2811	<param name="environment" type="wstring" dir="in">
2812	<desc>
2813	Environment to pass to the opened session.
2814	</desc>
2815	</param>
2816	<param name="progress" type="IProgress" dir="return">
2817	<desc>Progress object to track the operation completion.</desc>
2818	</param>
2819	</method>
2820
2821	<method name="openExistingSession">
2822	<desc>
2823	Opens a new remote session with the virtual machine for
2824	which a direct session is already open.
2825
2826	The remote session provides some level of control over the VM
2827	execution (using the IConsole interface) to the caller; however,
2828	within the remote session context, not all VM settings are available
2829	for modification.
2830
2831	As opposed to <link to="#openRemoteSession"/>, the number of
2832	remote sessions opened this way is not limited by the API
2833
2834	<note>
2835	It is an error to open a remote session with the machine that
2836	doesn't have an open direct session.
2837	</note>
2838
2839	<result name="E_UNEXPECTED">
2840	Virtual machine not registered.
2841	</result>
2842	<result name="VBOX_E_OBJECT_NOT_FOUND">
2843	No machine matching @a machineId found.
2844	</result>
2845	<result name="VBOX_E_INVALID_OBJECT_STATE">
2846	Session already open or being opened.
2847	</result>
2848	<result name="VBOX_E_INVALID_SESSION_STATE">
2849	Direct session state not Open.
2850	</result>
2851	<result name="VBOX_E_VM_ERROR">
2852	Failed to get console object from direct session or assign
2853	machine to session.
2854	</result>
2855
2856	<see>openRemoteSession</see>
2857	</desc>
2858	<param name="session" type="ISession" dir="in">
2859	<desc>
2860	Session object that will represent the open remote session
2861	after successful method invocation. This object must not
2862	represent an already open session.
2863	<note>
2864	This session will be automatically closed when the peer
2865	(direct) session dies or gets closed.
2866	</note>
2867	</desc>
2868	</param>
2869	<param name="machineId" type="uuid" mod="string" dir="in">
2870	<desc>ID of the virtual machine to open a session with.</desc>
2871	</param>
2872	</method>
2873
2874	<method name="registerCallback">
2875	<desc>
2876	Registers a new global VirtualBox callback. The methods of the given
2877	callback object will be called by VirtualBox when an appropriate
2878	event occurs.
2879
2880	<result name="E_INVALIDARG">
2881	A @c null callback cannot be registered.
2882	</result>
2883
2884	</desc>
2885	<param name="callback" type="IVirtualBoxCallback" dir="in">
2886	<desc>Callback object to register.</desc>
2887	</param>
2888	</method>
2889
2890	<method name="unregisterCallback">
2891	<desc>
2892	Unregisters the previously registered global VirtualBox callback.
2893
2894	<result name="E_INVALIDARG">
2895	Specified @a callback not registered.
2896	</result>
2897
2898	</desc>
2899	<param name="callback" type="IVirtualBoxCallback" dir="in">
2900	<desc>Callback object to unregister.</desc>
2901	</param>
2902	</method>
2903
2904	<method name="waitForPropertyChange">
2905	<desc>
2906	Blocks the caller until any of the properties represented by the
2907	@a what argument changes the value or until the given timeout interval
2908	expires.
2909
2910	The @a what argument is a comma separated list of property masks that
2911	describe properties the caller is interested in. The property mask is
2912	a string in the following format:
2913
2914	<pre>
2915	[[group.]subgroup.]name
2916	</pre>
2917
2918	where @c name is the property name and @c group, @c subgroup are zero
2919	or more property group specifiers. Each element (group or name) in
2920	the property mask may be either a Latin string or an asterisk symbol
2921	(@c "*") which is used to match any string for the given element. A
2922	property mask that doesn't contain asterisk symbols represents a
2923	single fully qualified property name.
2924
2925	Groups in the fully qualified property name go from more generic (the
2926	left-most part) to more specific (the right-most part). The first
2927	element is usually a name of the object the property belongs to. The
2928	second element may be either a property name, or a child object name,
2929	or an index if the preceding element names an object which is one of
2930	many objects of the same type. This way, property names form a
2931	hierarchy of properties. Here are some examples of property names:
2932
2933	<table>
2934	<tr>
2935	<td><tt>VirtualBox.version</tt></td>
2936	<td><link to="IVirtualBox::version"/> property</td>
2937	</tr>
2938	<tr>
2939	<td><tt>Machine.<UUID>.name</tt></td>
2940	<td><link to="IMachine::name"/> property of the machine with the
2941	given UUID</td>
2942	</tr>
2943	</table>
2944
2945	Most property names directly correspond to the properties of objects
2946	(components) provided by the VirtualBox library and may be used to
2947	track changes to these properties. However, there may be
2948	pseudo-property names that don't correspond to any existing object's
2949	property directly, as well as there may be object properties that
2950	don't have a corresponding property name that is understood by this
2951	method, and therefore changes to such properties cannot be
2952	tracked. See individual object's property descriptions to get a
2953	fully qualified property name that can be used with this method (if
2954	any).
2955
2956	There is a special property mask @c "*" (i.e. a string consisting of a
2957	single asterisk symbol) that can be used to match all properties.
2958	Below are more examples of property masks:
2959
2960	<table>
2961	<tr>
2962	<td><tt>VirtualBox.*</tt></td>
2963	<td>Track all properties of the VirtualBox object</td>
2964	</tr>
2965	<tr>
2966	<td><tt>Machine.*.name</tt></td>
2967	<td>Track changes to the <link to="IMachine::name"/> property of
2968	all registered virtual machines</td>
2969	</tr>
2970	</table>
2971
2972	<note>
2973	This function is not implemented in the current version of the
2974	product.
2975	</note>
2976	</desc>
2977	<param name="what" type="wstring" dir="in">
2978	<desc>Comma separated list of property masks.</desc>
2979	</param>
2980	<param name="timeout" type="unsigned long" dir="in">
2981	<desc>
2982	Wait timeout in milliseconds.
2983	Specify -1 for an indefinite wait.
2984	</desc>
2985	</param>
2986	<param name="changed" type="wstring" dir="out">
2987	<desc>
2988	Comma separated list of properties that have been changed and caused
2989	this method to return to the caller.
2990	</desc>
2991	</param>
2992	<param name="values" type="wstring" dir="out">
2993	<desc>Reserved, not currently used.</desc>
2994	</param>
2995	</method>
2996
2997	<!--method name="createDHCPServerForInterface">
2998	<desc>
2999	Creates a dhcp server settings to be used for the given interface
3000	<result name="E_INVALIDARG">
3001	Host network interface @a name already exists.
3002	</result>
3003	</desc>
3004	<param name="interface" type="IHostNetworkInterface" dir="in">
3005	<desc>Network Interface</desc>
3006	</param>
3007	<param name="server" type="IDHCPServer" dir="out">
3008	<desc>Dhcp server settings</desc>
3009	</param>
3010	</method-->
3011
3012	<method name="createDHCPServer">
3013	<desc>
3014	Creates a dhcp server settings to be used for the given internal network name
3015	<result name="E_INVALIDARG">
3016	Host network interface @a name already exists.
3017	</result>
3018	</desc>
3019	<param name="name" type="wstring" dir="in">
3020	<desc>server name</desc>
3021	</param>
3022	<param name="server" type="IDHCPServer" dir="return">
3023	<desc>Dhcp server settings</desc>
3024	</param>
3025	</method>
3026
3027	<method name="findDHCPServerByNetworkName">
3028	<desc>
3029	Searches a dhcp server settings to be used for the given internal network name
3030	<result name="E_INVALIDARG">
3031	Host network interface @a name already exists.
3032	</result>
3033
3034	</desc>
3035	<param name="name" type="wstring" dir="in">
3036	<desc>server name</desc>
3037	</param>
3038	<param name="server" type="IDHCPServer" dir="return">
3039	<desc>Dhcp server settings</desc>
3040	</param>
3041	</method>
3042
3043	<!--method name="findDHCPServerForInterface">
3044	<desc>
3045	Searches a dhcp server settings to be used for the given interface
3046	<result name="E_INVALIDARG">
3047	Host network interface @a name already exists.
3048	</result>
3049	</desc>
3050	<param name="interface" type="IHostNetworkInterface" dir="in">
3051	<desc>Network Interface</desc>
3052	</param>
3053	<param name="server" type="IDHCPServer" dir="out">
3054	<desc>Dhcp server settings</desc>
3055	</param>
3056	</method-->
3057
3058	<method name="removeDHCPServer">
3059	<desc>
3060	Removes the dhcp server settings
3061	<result name="E_INVALIDARG">
3062	Host network interface @a name already exists.
3063	</result>
3064	</desc>
3065	<param name="server" type="IDHCPServer" dir="in">
3066	<desc>Dhcp server settings to be removed</desc>
3067	</param>
3068	</method>
3069
3070
3071	<method name="checkFirmwarePresent">
3072	<desc>
3073	Check if this VirtualBox installation has a firmware
3074	of the given type available, either system-wide or per-user.
3075	Optionally, this may return a hint where this firmware can be
3076	downloaded from.
3077	</desc>
3078	<param name="firmwareType" type="FirmwareType" dir="in">
3079	<desc>
3080	Type of firmware to check.
3081	</desc>
3082	</param>
3083	<param name="version" type="wstring" dir="in">
3084	<desc>Expected version number, usually empty string (presently ignored).</desc>
3085	</param>
3086
3087	<param name="url" type="wstring" dir="out">
3088	<desc>
3089	Suggested URL to download this firmware from.
3090	</desc>
3091	</param>
3092
3093	<param name="file" type="wstring" dir="out">
3094	<desc>
3095	Filename of firmware, only valid if result == TRUE.
3096	</desc>
3097	</param>
3098
3099	<param name="result" type="boolean" dir="return">
3100	<desc>If firmware of this type and version is available.</desc>
3101	</param>
3102	</method>
3103
3104	</interface>
3105
3106	<!--
3107	// IVFSExplorer
3108	/////////////////////////////////////////////////////////////////////////
3109	-->
3110
3111	<enum
3112	name="VFSType"
3113	uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
3114	>
3115	<desc>
3116	Virtual file systems supported by VFSExplorer.
3117	</desc>
3118
3119	<const name="File" value="1" />
3120	<const name="Cloud" value="2" />
3121	<const name="S3" value="3" />
3122	<const name="WebDav" value="4" />
3123	</enum>
3124
3125	<enum
3126	name="VFSFileType"
3127	uuid="714333cd-44e2-415f-a245-d378fa9b1242"
3128	>
3129	<desc>
3130	File types known by VFSExplorer.
3131	</desc>
3132
3133	<const name="Unknown" value="1" />
3134	<const name="Fifo" value="2" />
3135	<const name="DevChar" value="3" />
3136	<const name="Directory" value="4" />
3137	<const name="DevBlock" value="5" />
3138	<const name="File" value="6" />
3139	<const name="SymLink" value="7" />
3140	<const name="Socket" value="8" />
3141	<const name="WhiteOut" value="9" />
3142	</enum>
3143
3144	<interface
3145	name="IVFSExplorer" extends="$unknown"
3146	uuid="2bb864a1-02a3-4474-a1d4-fb5f23b742e1"
3147	wsmap="managed"
3148	>
3149	<desc>
3150	The VFSExplorer interface unifies access to different file system
3151	types. This includes local file systems as well remote file systems like
3152	S3. For a list of supported types see <link to="VFSType" />.
3153	An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
3154	</desc>
3155
3156	<attribute name="path" type="wstring" readonly="yes">
3157	<desc>Returns the current path in the virtual file system.</desc>
3158	</attribute>
3159
3160	<attribute name="type" type="VFSType" readonly="yes">
3161	<desc>Returns the file system type which is currently in use.</desc>
3162	</attribute>
3163
3164	<method name="update">
3165	<desc>Updates the internal list of files/directories from the
3166	current directory level. Use <link to="#entryList" /> to get the full list
3167	after a call to this method.</desc>
3168
3169	<param name="aProgress" type="IProgress" dir="return">
3170	<desc>Progress object to track the operation completion.</desc>
3171	</param>
3172	</method>
3173
3174	<method name="cd">
3175	<desc>Change the current directory level.</desc>
3176
3177	<param name="aDir" type="wstring" dir="in">
3178	<desc>The name of the directory to go in.</desc>
3179	</param>
3180
3181	<param name="aProgress" type="IProgress" dir="return">
3182	<desc>Progress object to track the operation completion.</desc>
3183	</param>
3184	</method>
3185
3186	<method name="cdUp">
3187	<desc>Go one directory upwards from the current directory level.</desc>
3188
3189	<param name="aProgress" type="IProgress" dir="return">
3190	<desc>Progress object to track the operation completion.</desc>
3191	</param>
3192	</method>
3193
3194	<method name="entryList">
3195	<desc>Returns a list of files/directories after a call to <link
3196	to="#update" />. The user is responsible for keeping this internal
3197	list up do date.</desc>
3198
3199	<param name="aNames" type="wstring" safearray="yes" dir="out">
3200	<desc>The list of names for the entries.</desc>
3201	</param>
3202
3203	<param name="aTypes" type="unsigned long" safearray="yes" dir="out">
3204	<desc>The list of types for the entries.</desc>
3205	</param>
3206	</method>
3207
3208	<method name="exists">
3209	<desc>Checks if the given file list exists in the current directory
3210	level.</desc>
3211
3212	<param name="aNames" type="wstring" safearray="yes" dir="in">
3213	<desc>The names to check.</desc>
3214	</param>
3215
3216	<param name="aExists" type="wstring" safearray="yes" dir="return">
3217	<desc>The names which exist.</desc>
3218	</param>
3219	</method>
3220
3221	<method name="remove">
3222	<desc>Deletes the given files in the current directory level.</desc>
3223
3224	<param name="aNames" type="wstring" safearray="yes" dir="in">
3225	<desc>The names to remove.</desc>
3226	</param>
3227
3228	<param name="aProgress" type="IProgress" dir="return">
3229	<desc>Progress object to track the operation completion.</desc>
3230	</param>
3231	</method>
3232
3233	</interface>
3234
3235	<!--
3236	// IAppliance
3237	/////////////////////////////////////////////////////////////////////////
3238	-->
3239
3240	<interface
3241	name="IAppliance" extends="$unknown"
3242	uuid="e3ba9ab9-ac2c-4266-8bd2-91c4bf721ceb"
3243	wsmap="managed"
3244	>
3245	<desc>
3246	Represents a platform-independent appliance in OVF format. An instance of this is returned
3247	by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
3248	virtual machines within an appliance with VirtualBox.
3249
3250	The OVF standard suggests two different physical file formats:
3251
3252	<ol>
3253	<li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
3254	file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
3255	this descriptor file references other files such as disk images, as OVF appliances typically
3256	do, those additional files must be in the same directory as the descriptor file.</li>
3257
3258	<li>If the appliance is distributed as a single file, it must be in TAR format and have the
3259	<tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3260	files and optionally other files.
3261
3262	At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3263	be added with a later version.</li>
3264	</ol>
3265
3266	<b>Importing</b> an OVF appliance into VirtualBox as instances of
3267	<link to="IMachine" /> involves the following sequence of API calls:
3268
3269	<ol>
3270	<li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3271	</li>
3272
3273	<li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3274	would like to import. So long as this file is syntactically valid, this will succeed
3275	and fill the appliance object with the parsed data from the OVF file.
3276	</li>
3277
3278	<li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3279	contents of the IAppliance attributes accordingly. These can be inspected by a
3280	VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3281	user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3282	instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3283	systems in the OVF, which in turn describe the virtual hardware prescribed by the
3284	OVF (network and hardware adapters, virtual disk images, memory size and so on).
3285	The GUI can then give the user the option to confirm and/or change these suggestions.
3286	</li>
3287
3288	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3289	virtual system to override the suggestions made by the interpret() routine.
3290	</li>
3291
3292	<li>Finally, call <link to="#importMachines" /> to create virtual machines in
3293	VirtualBox as instances of <link to="IMachine" /> that match the information in the
3294	virtual system descriptions.
3295	</li>
3296	</ol>
3297
3298	<b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3299
3300	<ol>
3301	<li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3302	an empty IAppliance object.
3303	</li>
3304
3305	<li>For each machine you would like to export, call <link to="IMachine::export" />
3306	with the IAppliance object you just created. This creates an instance of
3307	<link to="IVirtualSystemDescription" /> inside the appliance.
3308	</li>
3309
3310	<li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3311	virtual system to override the suggestions made by the export() routine.
3312	</li>
3313
3314	<li>Finally, call <link to="#write" /> with a path specification to have the OVF
3315	file written.</li>
3316	</ol>
3317
3318	</desc>
3319
3320	<attribute name="path" type="wstring" readonly="yes">
3321	<desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3322	the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3323	<link to="#write" /> (for export).
3324	This attribute is empty until one of these methods has been called.
3325	</desc>
3326	</attribute>
3327
3328	<attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3329	<desc>
3330	Array of virtual disk definitions. One such description exists for each
3331	disk definition in the OVF; each string array item represents one such piece of
3332	disk information, with the information fields separated by tab (\t) characters.
3333
3334	The caller should be prepared for additional fields being appended to
3335	this string in future versions of VirtualBox and therefore check for
3336	the number of tabs in the strings returned.
3337
3338	In the current version, the following eight fields are returned per string
3339	in the array:
3340
3341	<ol>
3342	<li>Disk ID (unique string identifier given to disk)</li>
3343
3344	<li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3345
3346	<li>Populated size (optional unsigned integer indicating the current size of the
3347	disk; can be approximate; -1 if unspecified)</li>
3348
3349	<li>Format (string identifying the disk format, typically
3350	"http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3351
3352	<li>Reference (where to find the disk image, typically a file name; if empty,
3353	then the disk should be created on import)</li>
3354
3355	<li>Image size (optional unsigned integer indicating the size of the image,
3356	which need not necessarily be the same as the values specified above, since
3357	the image may be compressed or sparse; -1 if not specified)</li>
3358
3359	<li>Chunk size (optional unsigned integer if the image is split into chunks;
3360	presently unsupported and always -1)</li>
3361
3362	<li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3363	</ol>
3364	</desc>
3365	</attribute>
3366
3367	<attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3368	<desc> Array of virtual system descriptions. One such description is created
3369	for each virtual system found in the OVF.
3370	This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3371	(for export) has been called.
3372	</desc>
3373	</attribute>
3374
3375	<method name="read">
3376	<desc>
3377	Reads an OVF file into the appliance object.
3378
3379	This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3380	mere fact that this method returns successfully does not mean that VirtualBox supports all
3381	features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3382	</desc>
3383	<param name="file" type="wstring" dir="in">
3384	<desc>
3385	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3386	on whether the appliance is distributed as a set of files or as a single file, respectively).
3387	</desc>
3388	</param>
3389	<param name="aProgress" type="IProgress" dir="return">
3390	<desc></desc>
3391	</param>
3392	</method>
3393
3394	<method name="interpret">
3395	<desc>
3396	Interprets the OVF data that was read when the appliance was constructed. After
3397	calling this method, one can inspect the
3398	<link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3399	one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3400	the appliance.
3401
3402	Calling this method is the second step of importing an appliance into VirtualBox;
3403	see <link to="IAppliance" /> for an overview.
3404
3405	After calling this method, one should call <link to="#getWarnings" /> to find out
3406	if problems were encountered during the processing which might later lead to
3407	errors.
3408	</desc>
3409	</method>
3410
3411	<method name="importMachines">
3412	<desc>
3413	Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3414	and other interfaces that match the information contained in the appliance as
3415	closely as possible, as represented by the import instructions in the
3416	<link to="#virtualSystemDescriptions" /> array.
3417
3418	Calling this method is the final step of importing an appliance into VirtualBox;
3419	see <link to="IAppliance" /> for an overview.
3420
3421	Since importing the appliance will most probably involve copying and converting
3422	disk images, which can take a long time, this method operates asynchronously and
3423	returns an IProgress object to allow the caller to monitor the progress.
3424	</desc>
3425
3426	<param name="aProgress" type="IProgress" dir="return">
3427	<desc></desc>
3428	</param>
3429	</method>
3430
3431	<method name="createVFSExplorer">
3432	<desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
3433
3434	<param name="aUri" type="wstring" dir="in">
3435	<desc>The URI describing the file system to use.</desc>
3436	</param>
3437
3438	<param name="aExplorer" type="IVFSExplorer" dir="return">
3439	<desc></desc>
3440	</param>
3441	</method>
3442
3443	<method name="write">
3444	<desc>
3445	Writes the contents of the appliance exports into a new OVF file.
3446
3447	Calling this method is the final step of exporting an appliance from VirtualBox;
3448	see <link to="IAppliance" /> for an overview.
3449
3450	Since exporting the appliance will most probably involve copying and converting
3451	disk images, which can take a long time, this method operates asynchronously and
3452	returns an IProgress object to allow the caller to monitor the progress.
3453	</desc>
3454	<param name="format" type="wstring" dir="in">
3455	<desc>
3456	Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
3457	future versions of VirtualBox may support additional formats.
3458	</desc>
3459	</param>
3460	<param name="path" type="wstring" dir="in">
3461	<desc>
3462	Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3463	on whether the appliance is distributed as a set of files or as a single file, respectively).
3464	</desc>
3465	</param>
3466	<param name="aProgress" type="IProgress" dir="return">
3467	<desc>Progress object to track the operation completion.</desc>
3468	</param>
3469	</method>
3470
3471	<method name="getWarnings">
3472	<desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3473
3474	<param name="aWarnings" type="wstring" dir="return" safearray="yes">
3475	<desc></desc>
3476	</param>
3477	</method>
3478
3479	</interface>
3480
3481	<enum
3482	name="VirtualSystemDescriptionType"
3483	uuid="aacc58de-5b45-4f82-ae2e-dd9a824fc3b5"
3484	>
3485	<desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3486	a configuration value.</desc>
3487
3488	<const name="Ignore" value="1" />
3489	<const name="OS" value="2" />
3490	<const name="Name" value="3" />
3491	<const name="Product" value="4" />
3492	<const name="Vendor" value="5" />
3493	<const name="Version" value="6" />
3494	<const name="ProductUrl" value="7" />
3495	<const name="VendorUrl" value="8" />
3496	<const name="Description" value="9" />
3497	<const name="License" value="10" />
3498	<const name="Miscellaneous" value="11" />
3499	<const name="CPU" value="12" />
3500	<const name="Memory" value="13" />
3501	<const name="HardDiskControllerIDE" value="14" />
3502	<const name="HardDiskControllerSATA" value="15" />
3503	<const name="HardDiskControllerSCSI" value="16" />
3504	<const name="HardDiskImage" value="17" />
3505	<const name="Floppy" value="18" />
3506	<const name="CDROM" value="19" />
3507	<const name="NetworkAdapter" value="20" />
3508	<const name="USBController" value="21" />
3509	<const name="SoundCard" value="22" />
3510
3511	</enum>
3512
3513	<enum
3514	name="VirtualSystemDescriptionValueType"
3515	uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
3516	>
3517	<desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
3518	type to fetch.</desc>
3519
3520	<const name="Reference" value="1" />
3521	<const name="Original" value="2" />
3522	<const name="Auto" value="3" />
3523	<const name="ExtraConfig" value="4" />
3524
3525	</enum>
3526
3527	<interface
3528	name="IVirtualSystemDescription" extends="$unknown"
3529	uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
3530	wsmap="managed"
3531	>
3532
3533	<desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3534	After <link to="IAppliance::interpret" /> has been called, that array contains
3535	information about how the virtual systems described in the OVF should best be imported into VirtualBox
3536	virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3537	into VirtualBox.
3538	</desc>
3539
3540	<attribute name="count" type="unsigned long" readonly="yes">
3541	<desc>Return the number of virtual system description entries.</desc>
3542	</attribute>
3543
3544	<method name="getDescription">
3545	<desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3546	items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3547
3548	The list below identifies the value sets that are possible depending on the
3549	<link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
3550	the array item with the same index in @a aOvfValues[] will contain the original value as contained
3551	in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
3552	will contain a suggested value to be used for VirtualBox. Depending on the description type,
3553	the @a aExtraConfigValues[] array item may also be used.
3554
3555	<ul>
3556	<li>
3557	"OS": the guest operating system type. There must be exactly one such array item on import. The
3558	corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
3559	This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3560	item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
3561	</li>
3562	<li>
3563	"Name": the name to give to the new virtual machine. There can be at most one such array item;
3564	if none is present on import, then an automatic name will be created from the operating system
3565	type. The correponding item im @a aOvfValues[] will contain the suggested virtual machine name
3566	from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
3567	<link to="IMachine" /> name that does not exist yet.
3568	</li>
3569	<li>
3570	"Description": an arbitrary description.
3571	</li>
3572	<li>
3573	"License": the EULA section from the OVF, if present. It is the responsibility of the calling
3574	code to display such a license for agreement; the Main API does not enforce any such policy.
3575	</li>
3576	<li>
3577	Miscellaneous: reserved for future use.
3578	</li>
3579	<li>
3580	"CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3581	</li>
3582	<li>
3583	"Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3584	is present on import, then VirtualBox will set a meaningful default based on the operating system
3585	type.
3586	</li>
3587	<li>
3588	"HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
3589	An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
3590	the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
3591	writes into the OVF.
3592	The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
3593	type can use to specify which hard disk controller a virtual disk should be connected to.
3594	Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
3595	in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
3596	its virtual machines supports four channels (primary master, primary slave, secondary master,
3597	secondary slave) and thus maps to two IDE controllers in the OVF sense.
3598	</li>
3599	<li>
3600	"HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3601	has no value in @a aOvfValues[] or @a aVBoxValues[].
3602	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3603	</li>
3604	<li>
3605	"HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3606	The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
3607	"LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
3608	whereas VirtualBox considers it a class of storage controllers of its own; see
3609	<link to="StorageControllerType" />).
3610	The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
3611	</li>
3612	<li>
3613	"HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3614	arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3615
3616	The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
3617	a path since the image file should be in the same location as the OVF file itself), whereas the
3618	item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
3619	hard disk image. This means that on import the image will be copied and converted from the
3620	"ovf" location to the "vbox" location; on export, this will be handled the other way round.
3621	On import, the target image will also be registered with VirtualBox.
3622
3623	The matching item in the @a aExtraConfigValues[] array must contain a string of the following
3624	format: "controller=<index>;channel=<c>"
3625	In this string, <index> must be an integer specifying the hard disk controller to connect
3626	the image to. That number must be the index of an array item with one of the hard disk controller
3627	types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
3628	In addition, <c> must specify the channel to use on that controller. For IDE controllers,
3629	this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
3630	before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
3631	no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
3632	</li>
3633	<li>
3634	"CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
3635	attachment information as with "HardDiskImage" items.
3636	</li>
3637	<li>
3638	"CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
3639	attachment information as with "HardDiskImage" items.
3640	</li>
3641	<li>
3642	"NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
3643	for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
3644	of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
3645	</li>
3646	<li>
3647	"USBController": a USB controller. There can be at most one such item. If and only if such an
3648	item ispresent, USB support will be enabled for the new virtual machine.
3649	</li>
3650	<li>
3651	"SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3652	present, sound support will be enabled for the new virtual machine. Note that the virtual
3653	machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3654	may be different from the virtual soundcard expected by the appliance.
3655	</li>
3656	</ul>
3657
3658	</desc>
3659
3660	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3661	<desc></desc>
3662	</param>
3663
3664	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3665	<desc></desc>
3666	</param>
3667
3668	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3669	<desc></desc>
3670	</param>
3671
3672	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3673	<desc></desc>
3674	</param>
3675
3676	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3677	<desc></desc>
3678	</param>
3679
3680	</method>
3681
3682	<method name="getDescriptionByType">
3683	<desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3684	should be returned.</desc>
3685
3686	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3687	<desc></desc>
3688	</param>
3689
3690	<param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3691	<desc></desc>
3692	</param>
3693
3694	<param name="aRefs" type="wstring" dir="out" safearray="yes">
3695	<desc></desc>
3696	</param>
3697
3698	<param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3699	<desc></desc>
3700	</param>
3701
3702	<param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
3703	<desc></desc>
3704	</param>
3705
3706	<param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3707	<desc></desc>
3708	</param>
3709
3710	</method>
3711
3712	<method name="getValuesByType">
3713	<desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3714	value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3715	values.</desc>
3716
3717	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3718	<desc></desc>
3719	</param>
3720
3721	<param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
3722	<desc></desc>
3723	</param>
3724
3725	<param name="aValues" type="wstring" dir="return" safearray="yes">
3726	<desc></desc>
3727	</param>
3728
3729	</method>
3730
3731	<method name="setFinalValues">
3732	<desc>
3733	This method allows the appliance's user to change the configuration for the virtual
3734	system descriptions. For each array item returned from <link to="#getDescription" />,
3735	you must pass in one boolean value and one configuration value.
3736
3737	Each item in the boolean array determines whether the particular configuration item
3738	should be enabled.
3739	You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3740	HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3741	and SoundCard.
3742
3743	For the "vbox" and "extra configuration" values, if you pass in the same arrays
3744	as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
3745	the configuration remains unchanged. Please see the documentation for getDescription()
3746	for valid configuration values for the individual array item types. If the
3747	corresponding item in the aEnabled array is @c false, the configuration value is ignored.
3748	</desc>
3749
3750	<param name="aEnabled" type="boolean" dir="in" safearray="yes">
3751	<desc></desc>
3752	</param>
3753
3754	<param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
3755	<desc></desc>
3756	</param>
3757
3758	<param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3759	<desc></desc>
3760	</param>
3761	</method>
3762
3763	<method name="addDescription">
3764	<desc>
3765	This method adds an additional description entry to the stack of already
3766	available descriptions for this virtual system. This is handy for writing
3767	values which aren't directly supported by VirtualBox. One example would
3768	be the License type of <link to="VirtualSystemDescriptionType" />.
3769	</desc>
3770
3771	<param name="aType" type="VirtualSystemDescriptionType" dir="in">
3772	<desc></desc>
3773	</param>
3774
3775	<param name="aVBoxValue" type="wstring" dir="in">
3776	<desc></desc>
3777	</param>
3778
3779	<param name="aExtraConfigValue" type="wstring" dir="in">
3780	<desc></desc>
3781	</param>
3782	</method>
3783	</interface>
3784
3785
3786	<!--
3787	// IMachine
3788	/////////////////////////////////////////////////////////////////////////
3789	-->
3790
3791	<interface
3792	name="IInternalMachineControl" extends="$unknown"
3793	uuid="57e9a280-8d57-4331-aa31-f009f5194f52"
3794	internal="yes"
3795	wsmap="suppress"
3796	>
3797	<method name="setRemoveSavedState">
3798	<desc>
3799	Updates the flag whether saved state is removed on a machine state
3800	change from Saved to PoweredOff.
3801	</desc>
3802	<param name="aRemove" type="boolean" dir="in"/>
3803	</method>
3804
3805	<method name="updateState">
3806	<desc>
3807	Updates the VM state.
3808	<note>
3809	This operation will also update the settings file with
3810	the correct information about the saved state file
3811	and delete this file from disk when appropriate.
3812	</note>
3813	</desc>
3814	<param name="state" type="MachineState" dir="in"/>
3815	</method>
3816
3817	<method name="getIPCId">
3818	<param name="id" type="wstring" dir="return"/>
3819	</method>
3820
3821	<method name="setPowerUpInfo">
3822	<desc>
3823	Transfers success (@c null) or error information for this session.
3824	This method updates the progress object to signal completion of the
3825	<link to="IVirtualBox::openRemoteSession"/> method if appropriate,
3826	which means that the progress object returned by
3827	<link to="IConsole::powerUp"/>.
3828	</desc>
3829	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
3830	</method>
3831
3832	<method name="runUSBDeviceFilters">
3833	<desc>
3834	Asks the server to run USB devices filters of the associated
3835	machine against the given USB device and tell if there is
3836	a match.
3837	<note>
3838	Intended to be used only for remote USB devices. Local
3839	ones don't require to call this method (this is done
3840	implicitly by the Host and USBProxyService).
3841	</note>
3842	</desc>
3843	<param name="device" type="IUSBDevice" dir="in"/>
3844	<param name="matched" type="boolean" dir="out"/>
3845	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
3846	</method>
3847
3848	<method name="captureUSBDevice">
3849	<desc>
3850	Requests a capture of the given host USB device.
3851	When the request is completed, the VM process will
3852	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3853	notification.
3854	</desc>
3855	<param name="id" type="uuid" mod="string" dir="in"/>
3856	</method>
3857
3858	<method name="detachUSBDevice">
3859	<desc>
3860	Notification that a VM is going to detach (@a done = @c false) or has
3861	already detached (@a done = @c true) the given USB device.
3862	When the @a done = @c true request is completed, the VM process will
3863	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3864	notification.
3865	<note>
3866	In the @a done = @c true case, the server must run its own filters
3867	and filters of all VMs but this one on the detached device
3868	as if it were just attached to the host computer.
3869	</note>
3870	</desc>
3871	<param name="id" type="uuid" mod="string" dir="in"/>
3872	<param name="done" type="boolean" dir="in"/>
3873	</method>
3874
3875	<method name="autoCaptureUSBDevices">
3876	<desc>
3877	Requests a capture all matching USB devices attached to the host.
3878	When the request is completed, the VM process will
3879	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3880	notification per every captured device.
3881	</desc>
3882	</method>
3883
3884	<method name="detachAllUSBDevices">
3885	<desc>
3886	Notification that a VM that is being powered down. The done
3887	parameter indicates whether which stage of the power down
3888	we're at. When @a done = @c false the VM is announcing its
3889	intentions, while when @a done = @c true the VM is reporting
3890	what it has done.
3891	<note>
3892	In the @a done = @c true case, the server must run its own filters
3893	and filters of all VMs but this one on all detach devices as
3894	if they were just attached to the host computer.
3895	</note>
3896	</desc>
3897	<param name="done" type="boolean" dir="in"/>
3898	</method>
3899
3900	<method name="onSessionEnd">
3901	<desc>
3902	Triggered by the given session object when the session is about
3903	to close normally.
3904	</desc>
3905	<param name="session" type="ISession" dir="in">
3906	<desc>Session that is being closed</desc>
3907	</param>
3908	<param name="progress" type="IProgress" dir="return">
3909	<desc>
3910	Used to wait until the corresponding machine is actually
3911	dissociated from the given session on the server.
3912	Returned only when this session is a direct one.
3913	</desc>
3914	</param>
3915	</method>
3916
3917	<method name="beginSavingState">
3918	<desc>
3919	Called by the VM process to inform the server it wants to
3920	save the current state and stop the VM execution.
3921	</desc>
3922	<param name="progress" type="IProgress" dir="in">
3923	<desc>
3924	Progress object created by the VM process to wait until
3925	the state is saved.
3926	</desc>
3927	</param>
3928	<param name="stateFilePath" type="wstring" dir="out">
3929	<desc>
3930	File path the VM process must save the execution state to.
3931	</desc>
3932	</param>
3933	</method>
3934
3935	<method name="endSavingState">
3936	<desc>
3937	Called by the VM process to inform the server that saving
3938	the state previously requested by #beginSavingState is either
3939	successfully finished or there was a failure.
3940
3941	<result name="VBOX_E_FILE_ERROR">
3942	Settings file not accessible.
3943	</result>
3944	<result name="VBOX_E_XML_ERROR">
3945	Could not parse the settings file.
3946	</result>
3947
3948	</desc>
3949
3950	<param name="success" type="boolean" dir="in">
3951	<desc>@c true to indicate success and @c false otherwise.
3952	</desc>
3953	</param>
3954	</method>
3955
3956	<method name="adoptSavedState">
3957	<desc>
3958	Gets called by IConsole::adoptSavedState.
3959	<result name="VBOX_E_FILE_ERROR">
3960	Invalid saved state file path.
3961	</result>
3962	</desc>
3963	<param name="savedStateFile" type="wstring" dir="in">
3964	<desc>Path to the saved state file to adopt.</desc>
3965	</param>
3966	</method>
3967
3968	<method name="beginTakingSnapshot">
3969	<desc>
3970	Called from the VM process to request from the server to perform the
3971	server-side actions of creating a snapshot (creating differencing images
3972	and the snapshot object).
3973
3974	<result name="VBOX_E_FILE_ERROR">
3975	Settings file not accessible.
3976	</result>
3977	<result name="VBOX_E_XML_ERROR">
3978	Could not parse the settings file.
3979	</result>
3980	</desc>
3981	<param name="initiator" type="IConsole" dir="in">
3982	<desc>The console object that initiated this call.</desc>
3983	</param>
3984	<param name="name" type="wstring" dir="in">
3985	<desc>Snapshot name.</desc>
3986	</param>
3987	<param name="description" type="wstring" dir="in">
3988	<desc>Snapshot description.</desc>
3989	</param>
3990	<param name="consoleProgress" type="IProgress" dir="in">
3991	<desc>
3992	Progress object created by the VM process tracking the
3993	snapshot's progress. This has the following sub-operations:
3994	<ul>
3995	<li>setting up (weight 1);</li>
3996	<li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3997	<li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3998	<li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3999	<li>finishing up (weight 1)</li>
4000	</ul>
4001	</desc>
4002	</param>
4003	<param name="fTakingSnapshotOnline" type="boolean" dir="in">
4004	<desc>
4005	Whether this is an online snapshot (i.e. the machine is running).
4006	</desc>
4007	</param>
4008	<param name="stateFilePath" type="wstring" dir="out">
4009	<desc>
4010	File path the VM process must save the execution state to.
4011	</desc>
4012	</param>
4013	</method>
4014
4015	<method name="endTakingSnapshot">
4016	<desc>
4017	Called by the VM process to inform the server that the snapshot
4018	previously requested by #beginTakingSnapshot is either
4019	successfully taken or there was a failure.
4020	</desc>
4021
4022	<param name="success" type="boolean" dir="in">
4023	<desc>@c true to indicate success and @c false otherwise</desc>
4024	</param>
4025	</method>
4026
4027	<method name="deleteSnapshot">
4028	<desc>
4029	Gets called by IConsole::deleteSnapshot.
4030	<result name="VBOX_E_INVALID_OBJECT_STATE">
4031	Snapshot has more than one child snapshot.
4032	</result>
4033	</desc>
4034	<param name="initiator" type="IConsole" dir="in">
4035	<desc>The console object that initiated this call.</desc>
4036	</param>
4037	<param name="id" type="uuid" mod="string" dir="in">
4038	<desc>UUID of the snapshot to delete.</desc>
4039	</param>
4040	<param name="machineState" type="MachineState" dir="out">
4041	<desc>New machine state after this operation is started.</desc>
4042	</param>
4043	<param name="progress" type="IProgress" dir="return">
4044	<desc>Progress object to track the operation completion.</desc>
4045	</param>
4046	</method>
4047
4048	<method name="finishOnlineMergeMedium">
4049	<desc>
4050	Gets called by IConsole::onlineMergeMedium.
4051	</desc>
4052	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
4053	<desc>The medium attachment which needs to be cleaned up.</desc>
4054	</param>
4055	<param name="source" type="IMedium" dir="in">
4056	<desc>Merge source medium.</desc>
4057	</param>
4058	<param name="target" type="IMedium" dir="in">
4059	<desc>Merge target medium.</desc>
4060	</param>
4061	<param name="mergeForward" type="boolean" dir="in">
4062	<desc>Merge direction.</desc>
4063	</param>
4064	<param name="parentForTarget" type="IMedium" dir="in">
4065	<desc>For forward merges: new parent for target medium.</desc>
4066	</param>
4067	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
4068	<desc>For backward merges: list of media which need their parent UUID
4069	updated.</desc>
4070	</param>
4071	</method>
4072
4073	<method name="restoreSnapshot">
4074	<desc>
4075	Gets called by IConsole::RestoreSnapshot.
4076	</desc>
4077	<param name="initiator" type="IConsole" dir="in">
4078	<desc>The console object that initiated this call.</desc>
4079	</param>
4080	<param name="snapshot" type="ISnapshot" dir="in">
4081	<desc>The snapshot to restore the VM state from.</desc>
4082	</param>
4083	<param name="machineState" type="MachineState" dir="out">
4084	<desc>New machine state after this operation is started.</desc>
4085	</param>
4086	<param name="progress" type="IProgress" dir="return">
4087	<desc>Progress object to track the operation completion.</desc>
4088	</param>
4089	</method>
4090
4091	<method name="pullGuestProperties">
4092	<desc>
4093	Get the list of the guest properties matching a set of patterns along
4094	with their values, time stamps and flags and give responsibility for
4095	managing properties to the console.
4096	</desc>
4097	<param name="name" type="wstring" dir="out" safearray="yes">
4098	<desc>
4099	The names of the properties returned.
4100	</desc>
4101	</param>
4102	<param name="value" type="wstring" dir="out" safearray="yes">
4103	<desc>
4104	The values of the properties returned. The array entries match the
4105	corresponding entries in the @a name array.
4106	</desc>
4107	</param>
4108	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
4109	<desc>
4110	The time stamps of the properties returned. The array entries match
4111	the corresponding entries in the @a name array.
4112	</desc>
4113	</param>
4114	<param name="flags" type="wstring" dir="out" safearray="yes">
4115	<desc>
4116	The flags of the properties returned. The array entries match the
4117	corresponding entries in the @a name array.
4118	</desc>
4119	</param>
4120	</method>
4121
4122	<method name="pushGuestProperty">
4123	<desc>
4124	Update a single guest property in IMachine.
4125	</desc>
4126	<param name="name" type="wstring" dir="in">
4127	<desc>
4128	The name of the property to be updated.
4129	</desc>
4130	</param>
4131	<param name="value" type="wstring" dir="in">
4132	<desc>
4133	The value of the property.
4134	</desc>
4135	</param>
4136	<param name="timestamp" type="unsigned long long" dir="in">
4137	<desc>
4138	The timestamp of the property.
4139	</desc>
4140	</param>
4141	<param name="flags" type="wstring" dir="in">
4142	<desc>
4143	The flags of the property.
4144	</desc>
4145	</param>
4146	</method>
4147
4148	<method name="lockMedia">
4149	<desc>
4150	Locks all media attached to the machine for writing and parents of
4151	attached differencing media (if any) for reading. This operation is
4152	atomic so that if it fails no media is actually locked.
4153
4154	This method is intended to be called when the machine is in Starting or
4155	Restoring state. The locked media will be automatically unlocked when
4156	the machine is powered off or crashed.
4157	</desc>
4158	</method>
4159	<method name="unlockMedia">
4160	<desc>
4161	Unlocks all media previously locked using
4162	<link to="IInternalMachineControl::lockMedia"/>.
4163
4164	This method is intended to be used with teleportation so that it is
4165	possible to teleport between processes on the same machine.
4166	</desc>
4167	</method>
4168	</interface>
4169
4170	<interface
4171	name="IBIOSSettings" extends="$unknown"
4172	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
4173	wsmap="managed"
4174	>
4175	<desc>
4176	The IBIOSSettings interface represents BIOS settings of the virtual
4177	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
4178	</desc>
4179	<attribute name="logoFadeIn" type="boolean">
4180	<desc>Fade in flag for BIOS logo animation.</desc>
4181	</attribute>
4182
4183	<attribute name="logoFadeOut" type="boolean">
4184	<desc>Fade out flag for BIOS logo animation.</desc>
4185	</attribute>
4186
4187	<attribute name="logoDisplayTime" type="unsigned long">
4188	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
4189	</attribute>
4190
4191	<attribute name="logoImagePath" type="wstring">
4192	<desc>
4193	Local file system path for external BIOS splash image. Empty string
4194	means the default image is shown on boot.
4195	</desc>
4196	</attribute>
4197
4198	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
4199	<desc>Mode of the BIOS boot device menu.</desc>
4200	</attribute>
4201
4202	<attribute name="ACPIEnabled" type="boolean">
4203	<desc>ACPI support flag.</desc>
4204	</attribute>
4205
4206	<attribute name="IOAPICEnabled" type="boolean">
4207	<desc>
4208	IO APIC support flag. If set, VirtualBox will provide an IO APIC
4209	and support IRQs above 15.
4210	</desc>
4211	</attribute>
4212
4213	<attribute name="timeOffset" type="long long">
4214	<desc>
4215	Offset in milliseconds from the host system time. This allows for
4216	guests running with a different system date/time than the host.
4217	It is equivalent to setting the system date/time in the BIOS except
4218	it is not an absolute value but a relative one. Guest Additions
4219	time synchronization honors this offset.
4220	</desc>
4221	</attribute>
4222
4223	<attribute name="PXEDebugEnabled" type="boolean">
4224	<desc>
4225	PXE debug logging flag. If set, VirtualBox will write extensive
4226	PXE trace information to the release log.
4227	</desc>
4228	</attribute>
4229
4230	</interface>
4231
4232	<interface
4233	name="IMachine" extends="$unknown"
4234	uuid="b8a9324a-1042-4c78-aff6-9d1c2bfd8cd0"
4235	wsmap="managed"
4236	>
4237	<desc>
4238	The IMachine interface represents a virtual machine, or guest, created
4239	in VirtualBox.
4240
4241	This interface is used in two contexts. First of all, a collection of
4242	objects implementing this interface is stored in the
4243	<link to="IVirtualBox::machines"/> attribute which lists all the virtual
4244	machines that are currently registered with this VirtualBox
4245	installation. Also, once a session has been opened for the given virtual
4246	machine (e.g. the virtual machine is running), the machine object
4247	associated with the open session can be queried from the session object;
4248	see <link to="ISession"/> for details.
4249
4250	The main role of this interface is to expose the settings of the virtual
4251	machine and provide methods to change various aspects of the virtual
4252	machine's configuration. For machine objects stored in the
4253	<link to="IVirtualBox::machines"/> collection, all attributes are
4254	read-only unless explicitly stated otherwise in individual attribute
4255	and method descriptions. In order to change a machine setting, a session
4256	for this machine must be opened using one of
4257	<link to="IVirtualBox::openSession"/>,
4258	<link to="IVirtualBox::openRemoteSession"/> or
4259	<link to="IVirtualBox::openExistingSession"/> methods. After the
4260	session has been successfully opened, a mutable machine object needs to
4261	be queried from the session object and then the desired settings changes
4262	can be applied to the returned object using IMachine attributes and
4263	methods. See the <link to="ISession"/> interface description for more
4264	information about sessions.
4265
4266	Note that IMachine does not provide methods to control virtual machine
4267	execution (such as start the machine, or power it down) -- these methods
4268	are grouped in a separate interface called <link to="IConsole" />.
4269
4270	<see>ISession, IConsole</see>
4271	</desc>
4272
4273	<attribute name="parent" type="IVirtualBox" readonly="yes">
4274	<desc>Associated parent object.</desc>
4275	</attribute>
4276
4277	<attribute name="accessible" type="boolean" readonly="yes">
4278	<desc>
4279	Whether this virtual machine is currently accessible or not.
4280
4281	A machine is always deemed accessible unless it is registered <i>and</i>
4282	its settings file cannot be read or parsed (either because the file itself
4283	is unavailable or has invalid XML contents).
4284
4285	Every time this property is read, the accessibility state of
4286	this machine is re-evaluated. If the returned value is @c false,
4287	the <link to="#accessError"/> property may be used to get the
4288	detailed error information describing the reason of
4289	inaccessibility, including XML error messages.
4290
4291	When the machine is inaccessible, only the following properties
4292	can be used on it:
4293	<ul>
4294	<li><link to="#parent"/></li>
4295	<li><link to="#id"/></li>
4296	<li><link to="#settingsFilePath"/></li>
4297	<li><link to="#accessible"/></li>
4298	<li><link to="#accessError"/></li>
4299	</ul>
4300
4301	An attempt to access any other property or method will return
4302	an error.
4303
4304	The only possible action you can perform on an inaccessible
4305	machine is to unregister it using the
4306	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
4307	for the accessibility state once more by querying this
4308	property).
4309
4310	<note>
4311	In the current implementation, once this property returns
4312	@c true, the machine will never become inaccessible
4313	later, even if its settings file cannot be successfully
4314	read/written any more (at least, until the VirtualBox
4315	server is restarted). This limitation may be removed in
4316	future releases.
4317	</note>
4318	</desc>
4319	</attribute>
4320
4321	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4322	<desc>
4323	Error information describing the reason of machine
4324	inaccessibility.
4325
4326	Reading this property is only valid after the last call to
4327	<link to="#accessible"/> returned @c false (i.e. the
4328	machine is currently unaccessible). Otherwise, a @c null
4329	IVirtualBoxErrorInfo object will be returned.
4330	</desc>
4331	</attribute>
4332
4333	<attribute name="name" type="wstring">
4334	<desc>
4335	Name of the virtual machine.
4336
4337	Besides being used for human-readable identification purposes
4338	everywhere in VirtualBox, the virtual machine name is also used
4339	as a name of the machine's settings file and as a name of the
4340	subdirectory this settings file resides in. Thus, every time you
4341	change the value of this property, the settings file will be
4342	renamed once you call <link to="#saveSettings"/> to confirm the
4343	change. The containing subdirectory will be also renamed, but
4344	only if it has exactly the same name as the settings file
4345	itself prior to changing this property (for backward compatibility
4346	with previous API releases). The above implies the following
4347	limitations:
4348	<ul>
4349	<li>The machine name cannot be empty.</li>
4350	<li>The machine name can contain only characters that are valid
4351	file name characters according to the rules of the file
4352	system used to store VirtualBox configuration.</li>
4353	<li>You cannot have two or more machines with the same name
4354	if they use the same subdirectory for storing the machine
4355	settings files.</li>
4356	<li>You cannot change the name of the machine if it is running,
4357	or if any file in the directory containing the settings file
4358	is being used by another running machine or by any other
4359	process in the host operating system at a time when
4360	<link to="#saveSettings"/> is called.
4361	</li>
4362	</ul>
4363	If any of the above limitations are hit, <link to="#saveSettings"/>
4364	will return an appropriate error message explaining the exact
4365	reason and the changes you made to this machine will not be
4366	saved.
4367	<note>
4368	For "legacy" machines created using the
4369	<link to="IVirtualBox::createLegacyMachine"/> call,
4370	the above naming limitations do not apply because the
4371	machine name does not affect the settings file name.
4372	The settings file name remains the same as it was specified
4373	during machine creation and never changes.
4374	</note>
4375	</desc>
4376	</attribute>
4377
4378	<attribute name="description" type="wstring">
4379	<desc>
4380	Description of the virtual machine.
4381
4382	The description attribute can contain any text and is
4383	typically used to describe the hardware and software
4384	configuration of the virtual machine in detail (i.e. network
4385	settings, versions of the installed software and so on).
4386	</desc>
4387	</attribute>
4388
4389	<attribute name="id" type="uuid" mod="string" readonly="yes">
4390	<desc>UUID of the virtual machine.</desc>
4391	</attribute>
4392
4393	<attribute name="OSTypeId" type="wstring">
4394	<desc>
4395	User-defined identifier of the Guest OS type.
4396	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4397	an IGuestOSType object representing details about the given
4398	Guest OS type.
4399	<note>
4400	This value may differ from the value returned by
4401	<link to="IGuest::OSTypeId"/> if Guest Additions are
4402	installed to the guest OS.
4403	</note>
4404	</desc>
4405	</attribute>
4406
4407	<attribute name="HardwareVersion" type="wstring">
4408	<desc>Hardware version identifier. Internal use only for now.</desc>
4409	</attribute>
4410
4411	<attribute name="hardwareUUID" type="uuid" mod="string">
4412	<desc>
4413	The UUID presented to the guest via memory tables, hardware and guest
4414	properties. For most VMs this is the same as the @a id, but for VMs
4415	which have been cloned or teleported it may be the same as the source
4416	VM. This latter is because the guest shouldn't notice that it was
4417	cloned or teleported.
4418	</desc>
4419	</attribute>
4420
4421	<attribute name="CPUCount" type="unsigned long">
4422	<desc>Number of virtual CPUs in the VM.</desc>
4423	</attribute>
4424
4425	<attribute name="CPUHotPlugEnabled" type="boolean">
4426	<desc>
4427	This setting determines whether VirtualBox allows CPU
4428	hotplugging for this machine.</desc>
4429	</attribute>
4430
4431	<attribute name="memorySize" type="unsigned long">
4432	<desc>System memory size in megabytes.</desc>
4433	</attribute>
4434
4435	<attribute name="memoryBalloonSize" type="unsigned long">
4436	<desc>Memory balloon size in megabytes.</desc>
4437	</attribute>
4438
4439	<attribute name="VRAMSize" type="unsigned long">
4440	<desc>Video memory size in megabytes.</desc>
4441	</attribute>
4442
4443	<attribute name="accelerate3DEnabled" type="boolean" default="false">
4444	<desc>
4445	This setting determines whether VirtualBox allows this machine to make
4446	use of the 3D graphics support available on the host.</desc>
4447	</attribute>
4448
4449	<attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
4450	<desc>
4451	This setting determines whether VirtualBox allows this machine to make
4452	use of the 2D video acceleration support available on the host.</desc>
4453	</attribute>
4454
4455	<attribute name="monitorCount" type="unsigned long">
4456	<desc>
4457	Number of virtual monitors.
4458	<note>
4459	Only effective on Windows XP and later guests with
4460	Guest Additions installed.
4461	</note>
4462	</desc>
4463	</attribute>
4464
4465	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4466	<desc>Object containing all BIOS settings.</desc>
4467	</attribute>
4468
4469	<attribute name="firmwareType" type="FirmwareType">
4470	<desc>Type of firmware (such as legacy BIOS or EFI), used for initial
4471	bootstrap in this VM.</desc>
4472	</attribute>
4473
4474	<attribute name="pointingHidType" type="PointingHidType">
4475	<desc>Type of pointing HID (such as mouse or tablet) used in this VM.
4476	The default is typically "PS2Mouse" but can vary depending on the
4477	requirements of the guest operating system.</desc>
4478	</attribute>
4479
4480	<attribute name="keyboardHidType" type="KeyboardHidType">
4481	<desc>Type of keyboard HID used in this VM.
4482	The default is typically "PS2Keyboard" but can vary depending on the
4483	requirements of the guest operating system.</desc>
4484	</attribute>
4485
4486	<attribute name="hpetEnabled" type="boolean">
4487	<desc>This attribute controls if High Precision Event Timer (HPET) is
4488	enabled in this VM. Use this property if you want to provide guests
4489	with additional time source, or if guest requires HPET to function correctly.
4490	Default is false.</desc>
4491	</attribute>
4492
4493	<attribute name="snapshotFolder" type="wstring">
4494	<desc>
4495	Full path to the directory used to store snapshot data
4496	(differencing media and saved state files) of this machine.
4497
4498	The initial value of this property is
4499	<tt><</tt><link to="#settingsFilePath">
4500	path_to_settings_file</link><tt>>/<</tt>
4501	<link to="#id">machine_uuid</link>
4502	<tt>></tt>.
4503
4504	Currently, it is an error to try to change this property on
4505	a machine that has snapshots (because this would require to
4506	move possibly large files to a different location).
4507	A separate method will be available for this purpose later.
4508
4509	<note>
4510	Setting this property to @c null or to an empty string will restore
4511	the initial value.
4512	</note>
4513	<note>
4514	When setting this property, the specified path can be
4515	absolute (full path) or relative to the directory where the
4516	<link to="#settingsFilePath">machine settings file</link>
4517	is located. When reading this property, a full path is
4518	always returned.
4519	</note>
4520	<note>
4521	The specified path may not exist, it will be created
4522	when necessary.
4523	</note>
4524	</desc>
4525	</attribute>
4526
4527	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4528	<desc>VRDP server object.</desc>
4529	</attribute>
4530
4531	<attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
4532	<desc>Array of media attached to this machine.</desc>
4533	</attribute>
4534
4535	<attribute name="USBController" type="IUSBController" readonly="yes">
4536	<desc>
4537	Associated USB controller object.
4538
4539	<note>
4540	If USB functionality is not available in the given edition of
4541	VirtualBox, this method will set the result code to @c E_NOTIMPL.
4542	</note>
4543	</desc>
4544	</attribute>
4545
4546	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4547	<desc>Associated audio adapter, always present.</desc>
4548	</attribute>
4549
4550	<attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4551	<desc>Array of storage controllers attached to this machine.</desc>
4552	</attribute>
4553
4554	<attribute name="settingsFilePath" type="wstring" readonly="yes">
4555	<desc>
4556	Full name of the file containing machine settings data.
4557	</desc>
4558	</attribute>
4559
4560	<attribute name="settingsModified" type="boolean" readonly="yes">
4561	<desc>
4562	Whether the settings of this machine have been modified
4563	(but neither yet saved nor discarded).
4564	<note>
4565	Reading this property is only valid on instances returned
4566	by <link to="ISession::machine"/> and on new machines
4567	created by <link to="IVirtualBox::createMachine"/> or opened
4568	by <link to="IVirtualBox::openMachine"/> but not
4569	yet registered, or on unregistered machines after calling
4570	<link to="IVirtualBox::unregisterMachine"/>. For all other
4571	cases, the settings can never be modified.
4572	</note>
4573	<note>
4574	For newly created unregistered machines, the value of this
4575	property is always @c true until <link to="#saveSettings"/>
4576	is called (no matter if any machine settings have been
4577	changed after the creation or not). For opened machines
4578	the value is set to @c false (and then follows to normal rules).
4579	</note>
4580	</desc>
4581	</attribute>
4582
4583	<attribute name="sessionState" type="SessionState" readonly="yes">
4584	<desc>Current session state for this machine.</desc>
4585	</attribute>
4586
4587	<attribute name="sessionType" type="wstring" readonly="yes">
4588	<desc>
4589	Type of the session. If <link to="#sessionState"/> is
4590	SessionSpawning or SessionOpen, this attribute contains the
4591	same value as passed to the
4592	<link to="IVirtualBox::openRemoteSession"/> method in the
4593	@a type parameter. If the session was opened directly using
4594	<link to="IVirtualBox::openSession"/>, or if
4595	<link to="#sessionState"/> is SessionClosed, the value of this
4596	attribute is an empty string.
4597	</desc>
4598	</attribute>
4599
4600	<attribute name="sessionPid" type="unsigned long" readonly="yes">
4601	<desc>
4602	Identifier of the session process. This attribute contains the
4603	platform-dependent identifier of the process that has opened a
4604	direct session for this machine using the
4605	<link to="IVirtualBox::openSession"/> call. The returned value
4606	is only valid if <link to="#sessionState"/> is SessionOpen or
4607	SessionClosing (i.e. a session is currently open or being
4608	closed) by the time this property is read.
4609	</desc>
4610	</attribute>
4611
4612	<attribute name="state" type="MachineState" readonly="yes">
4613	<desc>Current execution state of this machine.</desc>
4614	</attribute>
4615
4616	<attribute name="lastStateChange" type="long long" readonly="yes">
4617	<desc>
4618	Time stamp of the last execution state change,
4619	in milliseconds since 1970-01-01 UTC.
4620	</desc>
4621	</attribute>
4622
4623	<attribute name="stateFilePath" type="wstring" readonly="yes">
4624	<desc>
4625	Full path to the file that stores the execution state of
4626	the machine when it is in the <link to="MachineState_Saved"/> state.
4627	<note>
4628	When the machine is not in the Saved state, this attribute is
4629	an empty string.
4630	</note>
4631	</desc>
4632	</attribute>
4633
4634	<attribute name="logFolder" type="wstring" readonly="yes">
4635	<desc>
4636	Full path to the folder that stores a set of rotated log files
4637	recorded during machine execution. The most recent log file is
4638	named <tt>VBox.log</tt>, the previous log file is
4639	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4640	in the current version).
4641	</desc>
4642	</attribute>
4643
4644	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4645	<desc>
4646	Current snapshot of this machine. This is @c null if the machine
4647	currently has no snapshots. If it is not @c null, then it was
4648	set by one of <link to="Console::takeSnapshot" />,
4649	<link to="Console::deleteSnapshot" />
4650	or <link to="Console::restoreSnapshot" />, depending on which
4651	was called last. See <link to="ISnapshot"/> for details.
4652	</desc>
4653	</attribute>
4654
4655	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
4656	<desc>
4657	Number of snapshots taken on this machine. Zero means the
4658	machine doesn't have any snapshots.
4659	</desc>
4660	</attribute>
4661
4662	<attribute name="currentStateModified" type="boolean" readonly="yes">
4663	<desc>
4664	Returns @c true if the current state of the machine is not
4665	identical to the state stored in the current snapshot.
4666
4667	The current state is identical to the current snapshot only
4668	directly after one of the following calls are made:
4669
4670	<ul>
4671	<li><link to="IConsole::restoreSnapshot"/>
4672	</li>
4673	<li><link to="IConsole::takeSnapshot"/> (issued on a
4674	"powered off" or "saved" machine, for which
4675	<link to="#settingsModified"/> returns @c false)
4676	</li>
4677	<li><link to="IMachine::setCurrentSnapshot"/>
4678	</li>
4679	</ul>
4680
4681	The current state remains identical until one of the following
4682	happens:
4683	<ul>
4684	<li>settings of the machine are changed</li>
4685	<li>the saved state is deleted</li>
4686	<li>the current snapshot is deleted</li>
4687	<li>an attempt to execute the machine is made</li>
4688	</ul>
4689
4690	<note>
4691	For machines that don't have snapshots, this property is
4692	always @c false.
4693	</note>
4694	</desc>
4695	</attribute>
4696
4697	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4698	<desc>
4699	Collection of shared folders for this machine (permanent shared
4700	folders). These folders are shared automatically at machine startup
4701	and available only to the guest OS installed within this machine.
4702
4703	New shared folders are added to the collection using
4704	<link to="#createSharedFolder"/>. Existing shared folders can be
4705	removed using <link to="#removeSharedFolder"/>.
4706	</desc>
4707	</attribute>
4708
4709	<attribute name="clipboardMode" type="ClipboardMode">
4710	<desc>
4711	Synchronization mode between the host OS clipboard
4712	and the guest OS clipboard.
4713	</desc>
4714	</attribute>
4715
4716	<attribute name="guestPropertyNotificationPatterns" type="wstring">
4717	<desc>
4718	A comma-separated list of simple glob patterns. Changes to guest
4719	properties whose name matches one of the patterns will generate an
4720	<link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4721	</desc>
4722	</attribute>
4723
4724	<attribute name="teleporterEnabled" type="boolean">
4725	<desc>
4726	When set to @a true, the virtual machine becomes a target teleporter
4727	the next time it is powered on. This can only set to @a true when the
4728	VM is in the @a PoweredOff or @a Aborted state.
4729
4730	<!-- This property is automatically set to @a false when the VM is powered
4731	on. (bird: This doesn't work yet ) -->
4732	</desc>
4733	</attribute>
4734
4735	<attribute name="teleporterPort" type="unsigned long">
4736	<desc>
4737	The TCP port the target teleporter will listen for incoming
4738	teleportations on.
4739
4740	0 means the port is automatically selected upon power on. The actual
4741	value can be read from this property while the machine is waiting for
4742	incoming teleportations.
4743	</desc>
4744	</attribute>
4745
4746	<attribute name="teleporterAddress" type="wstring">
4747	<desc>
4748	The address the target teleporter will listen on. If set to an empty
4749	string, it will listen on all addresses.
4750	</desc>
4751	</attribute>
4752
4753	<attribute name="teleporterPassword" type="wstring">
4754	<desc>
4755	The password the to check for on the target teleporter. This is just a
4756	very basic measure to prevent simple hacks and operators accidentally
4757	beaming a virtual machine to the wrong place.
4758	</desc>
4759	</attribute>
4760
4761	<attribute name="RTCUseUTC" type="boolean">
4762	<desc>
4763	When set to @a true, the RTC device of the virtual machine will run
4764	in UTC time, otherwise in local time. Especially Unix guests prefer
4765	the time in UTC.
4766	</desc>
4767	</attribute>
4768
4769	<attribute name="ioMgr" type="IoMgrType">
4770	<desc>
4771	Selects the I/O manager to use for the virtual machine.
4772	</desc>
4773	</attribute>
4774
4775	<attribute name="ioBackend" type="IoBackendType">
4776	<desc>
4777	Selects the I/O backend to use for the virtual machine.
4778	</desc>
4779	</attribute>
4780
4781	<attribute name="ioCacheEnabled" type="boolean">
4782	<desc>
4783	When set to @a true, the builtin I/O cache of the virtual machine
4784	will be enabled.
4785	</desc>
4786	</attribute>
4787
4788	<attribute name="ioCacheSize" type="unsigned long">
4789	<desc>
4790	Maximum size of the I/O cache in MB.
4791	</desc>
4792	</attribute>
4793
4794	<attribute name="ioBandwidthMax" type="unsigned long">
4795	<desc>
4796	The maximum number of MB the VM is allowed to transfer per second.
4797	0 means unlimited bandwidth.
4798	</desc>
4799	</attribute>
4800
4801	<method name="setBootOrder">
4802	<desc>
4803	Puts the given device to the specified position in
4804	the boot order.
4805
4806	To indicate that no device is associated with the given position,
4807	<link to="DeviceType_Null"/> should be used.
4808
4809	@todo setHardDiskBootOrder(), setNetworkBootOrder()
4810
4811	<result name="E_INVALIDARG">
4812	Boot @a position out of range.
4813	</result>
4814	<result name="E_NOTIMPL">
4815	Booting from USB @a device currently not supported.
4816	</result>
4817
4818	</desc>
4819	<param name="position" type="unsigned long" dir="in">
4820	<desc>
4821	Position in the boot order (@c 1 to the total number of
4822	devices the machine can boot from, as returned by
4823	<link to="ISystemProperties::maxBootPosition"/>).
4824	</desc>
4825	</param>
4826	<param name="device" type="DeviceType" dir="in">
4827	<desc>
4828	The type of the device used to boot at the given position.
4829	</desc>
4830	</param>
4831	</method>
4832
4833	<method name="getBootOrder" const="yes">
4834	<desc>
4835	Returns the device type that occupies the specified
4836	position in the boot order.
4837
4838	@todo [remove?]
4839	If the machine can have more than one device of the returned type
4840	(such as hard disks), then a separate method should be used to
4841	retrieve the individual device that occupies the given position.
4842
4843	If here are no devices at the given position, then
4844	<link to="DeviceType_Null"/> is returned.
4845
4846	@todo getHardDiskBootOrder(), getNetworkBootOrder()
4847
4848	<result name="E_INVALIDARG">
4849	Boot @a position out of range.
4850	</result>
4851
4852	</desc>
4853	<param name="position" type="unsigned long" dir="in">
4854	<desc>
4855	Position in the boot order (@c 1 to the total number of
4856	devices the machine can boot from, as returned by
4857	<link to="ISystemProperties::maxBootPosition"/>).
4858	</desc>
4859	</param>
4860	<param name="device" type="DeviceType" dir="return">
4861	<desc>
4862	Device at the given position.
4863	</desc>
4864	</param>
4865	</method>
4866
4867	<method name="attachDevice">
4868	<desc>
4869	Attaches a device and optionally mounts a medium to the given storage
4870	controller (<link to="IStorageController" />, identified by @a name),
4871	at the indicated port and device.
4872
4873	This method is intended for managing storage devices in general (it works
4874	for both fixed and removable media). For storage devices supporting removable
4875	media (such as DVDs and floppies), you can also use <link to="IMedium::mountMedium"/>
4876	for changing the media while the machine is running.
4877
4878	For the IDE bus, the @a controllerPort parameter can be either
4879	@c 0 or @c 1, to specify the primary or secondary IDE controller,
4880	respectively. For each of these, @a device can then be either @c 0 or @c 1,
4881	to specify the master or the slave device, respectively. (In the
4882	default configuration of virtual machines, the secondary master is
4883	used for a CD/DVD drive.)
4884
4885	For an SATA controller, @a controllerPort must be a number ranging
4886	from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
4887	be a number ranging from @c 0 to @c 15.
4888
4889	For both SCSI and SATA, the @a device parameter is unused and must
4890	be @c 0.
4891
4892	For fixed media such as hard disks, the given medium identifier cannot
4893	be a zero UUID. It may be a zero UUID for removable media such as DVDs
4894	and floppies.
4895
4896	After calling this returns successfully, a new instance of
4897	<link to="IMediumAttachment"/> will appear in the machine's list of medium
4898	attachments (<link to="IMachine::mediumAttachments"/>).
4899
4900	The specified device slot must not have a device attached to it,
4901	or this method will fail.
4902
4903	See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4904	information about attaching media.
4905
4906	<note>
4907	You cannot attach a device to a running machine. Also, you cannot
4908	attach a device to a newly created machine until this machine's
4909	settings are saved to disk using <link to="#saveSettings"/>.
4910	</note>
4911	<note>
4912	If the medium is being attached indirectly, a new differencing medium
4913	will implicitly be created for it and attached instead. If the
4914	changes made to the machine settings (including this indirect
4915	attachment) are later cancelled using <link to="#discardSettings"/>,
4916	this implicitly created differencing medium will implicitly
4917	be deleted.
4918	</note>
4919
4920	<result name="E_INVALIDARG">
4921	SATA device, SATA port, IDE port or IDE slot out of range.
4922	</result>
4923	<result name="VBOX_E_INVALID_OBJECT_STATE">
4924	Attempt to attach medium to an unregistered virtual machine.
4925	</result>
4926	<result name="VBOX_E_INVALID_VM_STATE">
4927	Invalid machine state.
4928	</result>
4929	<result name="VBOX_E_OBJECT_IN_USE">
4930	Hard disk already attached to this or another virtual machine.
4931	</result>
4932
4933	</desc>
4934	<param name="name" type="wstring" dir="in">
4935	<desc>Name of the storage controller to attach the device to.</desc>
4936	</param>
4937	<param name="controllerPort" type="long" dir="in">
4938	<desc>Port to attach the device to.</desc>
4939	</param>
4940	<param name="device" type="long" dir="in">
4941	<desc>Device slot in the given port to attach the device to.</desc>
4942	</param>
4943	<param name="type" type="DeviceType" dir="in">
4944	<desc>Device type of the attached device.</desc>
4945	</param>
4946	<param name="id" type="uuid" mod="string" dir="in">
4947	<desc>UUID of the medium to mount. Zero UUID means do not mount any
4948	medium.</desc>
4949	</param>
4950	</method>
4951
4952	<method name="detachDevice">
4953	<desc>
4954	Detaches the device attached to a device slot of the specified bus.
4955
4956	Detaching the device from the virtual machine is deferred. This means
4957	that the medium remains associated with the machine when this method
4958	returns and gets actually de-associated only after a successful
4959	<link to="#saveSettings"/> call. See <link to="IMedium"/>
4960	for more detailed information about attaching media.
4961
4962	<note>
4963	You cannot detach a device from a running machine.
4964	</note>
4965	<note>
4966	Detaching differencing media implicitly created by <link
4967	to="#attachDevice"/> for the indirect attachment using this
4968	method will <b>not</b> implicitly delete them. The
4969	<link to="IMedium::deleteStorage"/> operation should be
4970	explicitly performed by the caller after the medium is successfully
4971	detached and the settings are saved with
4972	<link to="#saveSettings"/>, if it is the desired action.
4973	</note>
4974
4975	<result name="VBOX_E_INVALID_VM_STATE">
4976	Attempt to detach medium from a running virtual machine.
4977	</result>
4978	<result name="VBOX_E_OBJECT_NOT_FOUND">
4979	No medium attached to given slot/bus.
4980	</result>
4981	<result name="VBOX_E_NOT_SUPPORTED">
4982	Medium format does not support storage deletion.
4983	</result>
4984
4985	</desc>
4986	<param name="name" type="wstring" dir="in">
4987	<desc>Name of the storage controller to detach the medium from.</desc>
4988	</param>
4989	<param name="controllerPort" type="long" dir="in">
4990	<desc>Port number to detach the medium from.</desc>
4991	</param>
4992	<param name="device" type="long" dir="in">
4993	<desc>Device slot number to detach the medium from.</desc>
4994	</param>
4995	</method>
4996
4997	<method name="passthroughDevice">
4998	<desc>
4999	Sets the passthrough mode of an existing DVD device. Changing the
5000	setting while the VM is running is forbidden. The setting is only used
5001	if at VM start the device is configured as a host DVD drive, in all
5002	other cases it is ignored. The device must already exist; see
5003	<link to="IMachine::attachDevice"/> for how to attach a new device.
5004
5005	The @a controllerPort and @a device parameters specify the device slot and
5006	have have the same meaning as with <link to="IMachine::attachDevice" />.
5007
5008	<result name="E_INVALIDARG">
5009	SATA device, SATA port, IDE port or IDE slot out of range.
5010	</result>
5011	<result name="VBOX_E_INVALID_OBJECT_STATE">
5012	Attempt to modify an unregistered virtual machine.
5013	</result>
5014	<result name="VBOX_E_INVALID_VM_STATE">
5015	Invalid machine state.
5016	</result>
5017
5018	</desc>
5019	<param name="name" type="wstring" dir="in">
5020	<desc>Name of the storage controller.</desc>
5021	</param>
5022	<param name="controllerPort" type="long" dir="in">
5023	<desc>Storage controller port.</desc>
5024	</param>
5025	<param name="device" type="long" dir="in">
5026	<desc>Device slot in the given port.</desc>
5027	</param>
5028	<param name="passthrough" type="boolean" dir="in">
5029	<desc>New value for the passthrough setting.</desc>
5030	</param>
5031	</method>
5032
5033	<method name="mountMedium">
5034	<desc>
5035	Mounts a medium (<link to="IMedium" />, identified
5036	by the given UUID @a id) to the given storage controller
5037	(<link to="IStorageController" />, identified by @a name),
5038	at the indicated port and device. The device must already exist;
5039	see <link to="IMachine::attachDevice"/> for how to attach a new device.
5040
5041	This method is intended only for managing removable media, where the
5042	device is fixed but media is changeable at runtime (such as DVDs
5043	and floppies). It cannot be used for fixed media such as hard disks.
5044
5045	The @a controllerPort and @a device parameters specify the device slot and
5046	have have the same meaning as with <link to="IMachine::attachDevice" />.
5047
5048	The specified device slot can have a medium mounted, which will be
5049	unmounted first. Specifying a zero UUID (or an empty string) for
5050	@a medium does just an unmount.
5051
5052	See <link to="IMedium"/> for more detailed information about
5053	attaching media.
5054
5055	<result name="E_INVALIDARG">
5056	SATA device, SATA port, IDE port or IDE slot out of range.
5057	</result>
5058	<result name="VBOX_E_INVALID_OBJECT_STATE">
5059	Attempt to attach medium to an unregistered virtual machine.
5060	</result>
5061	<result name="VBOX_E_INVALID_VM_STATE">
5062	Invalid machine state.
5063	</result>
5064	<result name="VBOX_E_OBJECT_IN_USE">
5065	Medium already attached to this or another virtual machine.
5066	</result>
5067
5068	</desc>
5069	<param name="name" type="wstring" dir="in">
5070	<desc>Name of the storage controller to attach the medium to.</desc>
5071	</param>
5072	<param name="controllerPort" type="long" dir="in">
5073	<desc>Port to attach the medium to.</desc>
5074	</param>
5075	<param name="device" type="long" dir="in">
5076	<desc>Device slot in the given port to attach the medium to.</desc>
5077	</param>
5078	<param name="medium" type="uuid" mod="string" dir="in">
5079	<desc>UUID of the medium to attach. A zero UUID means unmount the
5080	currently mounted medium.</desc>
5081	</param>
5082	<param name="force" type="boolean" dir="in">
5083	<desc>Allows to force unmount/mount of a medium which is locked by
5084	theDevice slot in the given port to attach the medium to.</desc>
5085	</param>
5086	</method>
5087
5088	<method name="getMedium" const="yes">
5089	<desc>
5090	Returns the virtual medium attached to a device slot of the specified
5091	bus.
5092
5093	Note that if the medium was indirectly attached by
5094	<link to="#mountMedium"/> to the given device slot then this
5095	method will return not the same object as passed to the
5096	<link to="#mountMedium"/> call. See <link to="IMedium"/> for
5097	more detailed information about mounting a medium.
5098
5099	<result name="VBOX_E_OBJECT_NOT_FOUND">
5100	No medium attached to given slot/bus.
5101	</result>
5102
5103	</desc>
5104	<param name="name" type="wstring" dir="in">
5105	<desc>Name of the storage controller the medium is attached to.</desc>
5106	</param>
5107	<param name="controllerPort" type="long" dir="in">
5108	<desc>Port to query.</desc>
5109	</param>
5110	<param name="device" type="long" dir="in">
5111	<desc>Device slot in the given port to query.</desc>
5112	</param>
5113	<param name="medium" type="IMedium" dir="return">
5114	<desc>Attached medium object.</desc>
5115	</param>
5116	</method>
5117
5118	<method name="getMediumAttachmentsOfController" const="yes">
5119	<desc>
5120	Returns an array of medium attachments which are attached to the
5121	the controller with the given name.
5122
5123	<result name="VBOX_E_OBJECT_NOT_FOUND">
5124	A storage controller with given name doesn't exist.
5125	</result>
5126	</desc>
5127	<param name="name" type="wstring" dir="in"/>
5128	<param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
5129	</method>
5130
5131	<method name="getMediumAttachment" const="yes">
5132	<desc>
5133	Returns a medium attachment which corresponds to the controller with
5134	the given name, on the given port and device slot.
5135
5136	<result name="VBOX_E_OBJECT_NOT_FOUND">
5137	No attachment exists for the given controller/port/device combination.
5138	</result>
5139	</desc>
5140	<param name="name" type="wstring" dir="in"/>
5141	<param name="controllerPort" type="long" dir="in"/>
5142	<param name="device" type="long" dir="in"/>
5143	<param name="attachment" type="IMediumAttachment" dir="return"/>
5144	</method>
5145
5146	<method name="getNetworkAdapter" const="yes">
5147	<desc>
5148	Returns the network adapter associated with the given slot.
5149	Slots are numbered sequentially, starting with zero. The total
5150	number of adapters per machine is defined by the
5151	<link to="ISystemProperties::networkAdapterCount"/> property,
5152	so the maximum slot number is one less than that property's value.
5153
5154	<result name="E_INVALIDARG">
5155	Invalid @a slot number.
5156	</result>
5157
5158	</desc>
5159	<param name="slot" type="unsigned long" dir="in"/>
5160	<param name="adapter" type="INetworkAdapter" dir="return"/>
5161	</method>
5162
5163	<method name="addStorageController">
5164	<desc>
5165	Adds a new storage controller (SCSI or SATA controller) to the
5166	machine and returns it as an instance of
5167	<link to="IStorageController" />.
5168
5169	@a name identifies the controller for subsequent calls such as
5170	<link to="#getStorageControllerByName" />,
5171	<link to="#getStorageControllerByInstance" />,
5172	<link to="#removeStorageController" />,
5173	<link to="#attachDevice" /> or <link to="#mountMedium" />.
5174
5175	After the controller has been added, you can set its exact
5176	type by setting the <link to="IStorageController::controllerType" />.
5177
5178	<result name="VBOX_E_OBJECT_IN_USE">
5179	A storage controller with given name exists already.
5180	</result>
5181	<result name="E_INVALIDARG">
5182	Invalid @a controllerType.
5183	</result>
5184	</desc>
5185	<param name="name" type="wstring" dir="in"/>
5186	<param name="connectionType" type="StorageBus" dir="in"/>
5187	<param name="controller" type="IStorageController" dir="return"/>
5188	</method>
5189
5190	<method name="getStorageControllerByName" const="yes">
5191	<desc>
5192	Returns a storage controller with the given name.
5193
5194	<result name="VBOX_E_OBJECT_NOT_FOUND">
5195	A storage controller with given name doesn't exist.
5196	</result>
5197	</desc>
5198	<param name="name" type="wstring" dir="in"/>
5199	<param name="storageController" type="IStorageController" dir="return"/>
5200	</method>
5201
5202	<method name="getStorageControllerByInstance" const="yes">
5203	<desc>
5204	Returns a storage controller with the given instance number.
5205
5206	<result name="VBOX_E_OBJECT_NOT_FOUND">
5207	A storage controller with given instance number doesn't exist.
5208	</result>
5209	</desc>
5210	<param name="instance" type="unsigned long" dir="in"/>
5211	<param name="storageController" type="IStorageController" dir="return"/>
5212	</method>
5213
5214	<method name="removeStorageController">
5215	<desc>
5216	Removes a storage controller from the machine.
5217
5218	<result name="VBOX_E_OBJECT_NOT_FOUND">
5219	A storage controller with given name doesn't exist.
5220	</result>
5221	</desc>
5222	<param name="name" type="wstring" dir="in"/>
5223	</method>
5224
5225	<method name="getSerialPort" const="yes">
5226	<desc>
5227	Returns the serial port associated with the given slot.
5228	Slots are numbered sequentially, starting with zero. The total
5229	number of serial ports per machine is defined by the
5230	<link to="ISystemProperties::serialPortCount"/> property,
5231	so the maximum slot number is one less than that property's value.
5232
5233	<result name="E_INVALIDARG">
5234	Invalid @a slot number.
5235	</result>
5236
5237	</desc>
5238	<param name="slot" type="unsigned long" dir="in"/>
5239	<param name="port" type="ISerialPort" dir="return"/>
5240	</method>
5241
5242	<method name="getParallelPort" const="yes">
5243	<desc>
5244	Returns the parallel port associated with the given slot.
5245	Slots are numbered sequentially, starting with zero. The total
5246	number of parallel ports per machine is defined by the
5247	<link to="ISystemProperties::parallelPortCount"/> property,
5248	so the maximum slot number is one less than that property's value.
5249
5250	<result name="E_INVALIDARG">
5251	Invalid @a slot number.
5252	</result>
5253
5254	</desc>
5255	<param name="slot" type="unsigned long" dir="in"/>
5256	<param name="port" type="IParallelPort" dir="return"/>
5257	</method>
5258
5259	<method name="getExtraDataKeys">
5260	<desc>
5261	Returns an array representing the machine-specific extra data keys
5262	which currently have values defined.
5263	</desc>
5264	<param name="value" type="wstring" dir="return" safearray="yes">
5265	<desc>Array of extra data keys.</desc>
5266	</param>
5267	</method>
5268
5269	<method name="getExtraData">
5270	<desc>
5271	Returns associated machine-specific extra data.
5272
5273	If the requested data @a key does not exist, this function will
5274	succeed and return an empty string in the @a value argument.
5275
5276	<result name="VBOX_E_FILE_ERROR">
5277	Settings file not accessible.
5278	</result>
5279	<result name="VBOX_E_XML_ERROR">
5280	Could not parse the settings file.
5281	</result>
5282
5283	</desc>
5284	<param name="key" type="wstring" dir="in">
5285	<desc>Name of the data key to get.</desc>
5286	</param>
5287	<param name="value" type="wstring" dir="return">
5288	<desc>Value of the requested data key.</desc>
5289	</param>
5290	</method>
5291
5292	<method name="setExtraData">
5293	<desc>
5294	Sets associated machine-specific extra data.
5295
5296	If you pass @c null or an empty string as a key @a value, the given
5297	@a key will be deleted.
5298
5299	<note>
5300	Before performing the actual data change, this method will ask all
5301	registered callbacks using the
5302	<link to="IVirtualBoxCallback::onExtraDataCanChange"/>
5303	notification for a permission. If one of the callbacks refuses the
5304	new value, the change will not be performed.
5305	</note>
5306	<note>
5307	On success, the
5308	<link to="IVirtualBoxCallback::onExtraDataChange"/> notification
5309	is called to inform all registered callbacks about a successful data
5310	change.
5311	</note>
5312	<note>
5313	This method can be called outside the machine session and therefore
5314	it's a caller's responsibility to handle possible race conditions
5315	when several clients change the same key at the same time.
5316	</note>
5317
5318	<result name="VBOX_E_FILE_ERROR">
5319	Settings file not accessible.
5320	</result>
5321	<result name="VBOX_E_XML_ERROR">
5322	Could not parse the settings file.
5323	</result>
5324
5325	</desc>
5326	<param name="key" type="wstring" dir="in">
5327	<desc>Name of the data key to set.</desc>
5328	</param>
5329	<param name="value" type="wstring" dir="in">
5330	<desc>Value to assign to the key.</desc>
5331	</param>
5332	</method>
5333
5334	<method name="getCPUProperty" const="yes">
5335	<desc>
5336	Returns the virtual CPU boolean value of the specified property.
5337
5338	<result name="E_INVALIDARG">
5339	Invalid property.
5340	</result>
5341
5342	</desc>
5343	<param name="property" type="CPUPropertyType" dir="in">
5344	<desc>
5345	Property type to query.
5346	</desc>
5347	</param>
5348	<param name="value" type="boolean" dir="return">
5349	<desc>
5350	Property value.
5351	</desc>
5352	</param>
5353	</method>
5354
5355	<method name="setCPUProperty">
5356	<desc>
5357	Sets the virtual CPU boolean value of the specified property.
5358
5359	<result name="E_INVALIDARG">
5360	Invalid property.
5361	</result>
5362
5363	</desc>
5364	<param name="property" type="CPUPropertyType" dir="in">
5365	<desc>
5366	Property type to query.
5367	</desc>
5368	</param>
5369	<param name="value" type="boolean" dir="in">
5370	<desc>
5371	Property value.
5372	</desc>
5373	</param>
5374	</method>
5375
5376	<method name="getCPUIDLeaf" const="yes">
5377	<desc>
5378	Returns the virtual CPU cpuid information for the specified leaf.
5379
5380	Currently supported index values for cpuid:
5381	Standard CPUID leafs: 0 - 0xA
5382	Extended CPUID leafs: 0x80000000 - 0x8000000A
5383
5384	See the Intel and AMD programmer's manuals for detailed information
5385	about the cpuid instruction and its leafs.
5386	<result name="E_INVALIDARG">
5387	Invalid id.
5388	</result>
5389
5390	</desc>
5391	<param name="id" type="unsigned long" dir="in">
5392	<desc>
5393	CPUID leaf index.
5394	</desc>
5395	</param>
5396	<param name="valEax" type="unsigned long" dir="out">
5397	<desc>
5398	CPUID leaf value for register eax.
5399	</desc>
5400	</param>
5401	<param name="valEbx" type="unsigned long" dir="out">
5402	<desc>
5403	CPUID leaf value for register ebx.
5404	</desc>
5405	</param>
5406	<param name="valEcx" type="unsigned long" dir="out">
5407	<desc>
5408	CPUID leaf value for register ecx.
5409	</desc>
5410	</param>
5411	<param name="valEdx" type="unsigned long" dir="out">
5412	<desc>
5413	CPUID leaf value for register edx.
5414	</desc>
5415	</param>
5416	</method>
5417
5418	<method name="setCPUIDLeaf">
5419	<desc>
5420	Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5421	are not passed unmodified. VirtualBox clears features that it doesn't support.
5422
5423	Currently supported index values for cpuid:
5424	Standard CPUID leafs: 0 - 0xA
5425	Extended CPUID leafs: 0x80000000 - 0x8000000A
5426
5427	See the Intel and AMD programmer's manuals for detailed information
5428	about the cpuid instruction and its leafs.
5429
5430	Do not use this method unless you know exactly what you're doing. Misuse can lead to
5431	random crashes inside VMs.
5432	<result name="E_INVALIDARG">
5433	Invalid id.
5434	</result>
5435
5436	</desc>
5437	<param name="id" type="unsigned long" dir="in">
5438	<desc>
5439	CPUID leaf index.
5440	</desc>
5441	</param>
5442	<param name="valEax" type="unsigned long" dir="in">
5443	<desc>
5444	CPUID leaf value for register eax.
5445	</desc>
5446	</param>
5447	<param name="valEbx" type="unsigned long" dir="in">
5448	<desc>
5449	CPUID leaf value for register ebx.
5450	</desc>
5451	</param>
5452	<param name="valEcx" type="unsigned long" dir="in">
5453	<desc>
5454	CPUID leaf value for register ecx.
5455	</desc>
5456	</param>
5457	<param name="valEdx" type="unsigned long" dir="in">
5458	<desc>
5459	CPUID leaf value for register edx.
5460	</desc>
5461	</param>
5462	</method>
5463
5464	<method name="removeCPUIDLeaf">
5465	<desc>
5466	Removes the virtual CPU cpuid leaf for the specified index
5467
5468	<result name="E_INVALIDARG">
5469	Invalid id.
5470	</result>
5471
5472	</desc>
5473	<param name="id" type="unsigned long" dir="in">
5474	<desc>
5475	CPUID leaf index.
5476	</desc>
5477	</param>
5478	</method>
5479
5480	<method name="removeAllCPUIDLeaves">
5481	<desc>
5482	Removes all the virtual CPU cpuid leaves
5483	</desc>
5484	</method>
5485
5486	<method name="getHWVirtExProperty" const="yes">
5487	<desc>
5488	Returns the value of the specified hardware virtualization boolean property.
5489
5490	<result name="E_INVALIDARG">
5491	Invalid property.
5492	</result>
5493
5494	</desc>
5495	<param name="property" type="HWVirtExPropertyType" dir="in">
5496	<desc>
5497	Property type to query.
5498	</desc>
5499	</param>
5500	<param name="value" type="boolean" dir="return">
5501	<desc>
5502	Property value.
5503	</desc>
5504	</param>
5505	</method>
5506
5507	<method name="setHWVirtExProperty">
5508	<desc>
5509	Sets a new value for the specified hardware virtualization boolean property.
5510
5511	<result name="E_INVALIDARG">
5512	Invalid property.
5513	</result>
5514
5515	</desc>
5516	<param name="property" type="HWVirtExPropertyType" dir="in">
5517	<desc>
5518	Property type to set.
5519	</desc>
5520	</param>
5521	<param name="value" type="boolean" dir="in">
5522	<desc>
5523	New property value.
5524	</desc>
5525	</param>
5526	</method>
5527
5528	<method name="saveSettings">
5529	<desc>
5530	Saves any changes to machine settings made since the session
5531	has been opened or a new machine has been created, or since the
5532	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
5533	For registered machines, new settings become visible to all
5534	other VirtualBox clients after successful invocation of this
5535	method.
5536	<note>
5537	The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
5538	notification event after the configuration has been successfully
5539	saved (only for registered machines).
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"/> but not
5545	yet registered, or on unregistered machines after calling
5546	<link to="IVirtualBox::unregisterMachine"/>.
5547	</note>
5548
5549	<result name="VBOX_E_FILE_ERROR">
5550	Settings file not accessible.
5551	</result>
5552	<result name="VBOX_E_XML_ERROR">
5553	Could not parse the settings file.
5554	</result>
5555	<result name="E_ACCESSDENIED">
5556	Modification request refused.
5557	</result>
5558
5559	</desc>
5560	</method>
5561
5562	<method name="discardSettings">
5563	<desc>
5564	Discards any changes to the machine settings made since the session
5565	has been opened or since the last call to <link to="#saveSettings"/>
5566	or <link to="#discardSettings"/>.
5567	<note>
5568	Calling this method is only valid on instances returned
5569	by <link to="ISession::machine"/> and on new machines
5570	created by <link to="IVirtualBox::createMachine"/> or
5571	opened by <link to="IVirtualBox::openMachine"/> but not
5572	yet registered, or on unregistered machines after calling
5573	<link to="IVirtualBox::unregisterMachine"/>.
5574	</note>
5575
5576	<result name="VBOX_E_INVALID_VM_STATE">
5577	Virtual machine is not mutable.
5578	</result>
5579
5580	</desc>
5581	</method>
5582
5583	<method name="deleteSettings">
5584	<desc>
5585	Deletes the settings file of this machine from disk.
5586	The machine must not be registered in order for this operation
5587	to succeed.
5588	<note>
5589	<link to="#settingsModified"/> will return @c true after this
5590	method successfully returns.
5591	</note>
5592	<note>
5593	Calling this method is only valid on instances returned
5594	by <link to="ISession::machine"/> and on new machines
5595	created by <link to="IVirtualBox::createMachine"/> or
5596	opened by <link to="IVirtualBox::openMachine"/> but not
5597	yet registered, or on unregistered machines after calling
5598	<link to="IVirtualBox::unregisterMachine"/>.
5599	</note>
5600	<note>
5601	The deleted machine settings file can be restored (saved again)
5602	by calling <link to="#saveSettings"/>.
5603	</note>
5604
5605	<result name="VBOX_E_INVALID_VM_STATE">
5606	Cannot delete settings of a registered machine or
5607	machine not mutable.
5608	</result>
5609	<result name="VBOX_E_IPRT_ERROR">
5610	Could not delete the settings file.
5611	</result>
5612
5613	</desc>
5614	</method>
5615
5616	<method name="export">
5617	<desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5618	steps required to export VirtualBox machines to OVF.
5619	</desc>
5620
5621	<param name="aAppliance" type="IAppliance" dir="in">
5622	<desc>Appliance to export this machine to.</desc>
5623	</param>
5624	<param name="aDescription" type="IVirtualSystemDescription" dir="return">
5625	<desc>VirtualSystemDescription object which is created for this machine.</desc>
5626	</param>
5627	</method >
5628
5629	<method name="getSnapshot">
5630	<desc>
5631	Returns a snapshot of this machine with the given UUID.
5632	A @c null UUID can be used to obtain the first snapshot
5633	taken on this machine. This is useful if you want to traverse
5634	the whole tree of snapshots starting from the root.
5635
5636	<result name="VBOX_E_OBJECT_NOT_FOUND">
5637	Virtual machine has no snapshots or snapshot not found.
5638	</result>
5639
5640	</desc>
5641	<param name="id" type="uuid" mod="string" dir="in">
5642	<desc>UUID of the snapshot to get</desc>
5643	</param>
5644	<param name="snapshot" type="ISnapshot" dir="return">
5645	<desc>Snapshot object with the given UUID.</desc>
5646	</param>
5647	</method>
5648
5649	<method name="findSnapshot">
5650	<desc>
5651	Returns a snapshot of this machine with the given name.
5652
5653	<result name="VBOX_E_OBJECT_NOT_FOUND">
5654	Virtual machine has no snapshots or snapshot not found.
5655	</result>
5656
5657	</desc>
5658	<param name="name" type="wstring" dir="in">
5659	<desc>Name of the snapshot to find</desc>
5660	</param>
5661	<param name="snapshot" type="ISnapshot" dir="return">
5662	<desc>Snapshot object with the given name.</desc>
5663	</param>
5664	</method>
5665
5666	<method name="setCurrentSnapshot">
5667	<desc>
5668	Sets the current snapshot of this machine.
5669	<note>
5670	In the current implementation, this operation is not
5671	implemented.
5672	</note>
5673	</desc>
5674	<param name="id" type="uuid" mod="string" dir="in">
5675	<desc>UUID of the snapshot to set as the current snapshot.</desc>
5676	</param>
5677	</method>
5678
5679	<method name="createSharedFolder">
5680	<desc>
5681	Creates a new permanent shared folder by associating the given logical
5682	name with the given host path, adds it to the collection of shared
5683	folders and starts sharing it. Refer to the description of
5684	<link to="ISharedFolder"/> to read more about logical names.
5685
5686	<result name="VBOX_E_OBJECT_IN_USE">
5687	Shared folder already exists.
5688	</result>
5689	<result name="VBOX_E_FILE_ERROR">
5690	Shared folder @a hostPath not accessible.
5691	</result>
5692
5693	</desc>
5694	<param name="name" type="wstring" dir="in">
5695	<desc>Unique logical name of the shared folder.</desc>
5696	</param>
5697	<param name="hostPath" type="wstring" dir="in">
5698	<desc>Full path to the shared folder in the host file system.</desc>
5699	</param>
5700	<param name="writable" type="boolean" dir="in">
5701	<desc>Whether the share is writable or readonly</desc>
5702	</param>
5703	</method>
5704
5705	<method name="removeSharedFolder">
5706	<desc>
5707	Removes the permanent shared folder with the given name previously
5708	created by <link to="#createSharedFolder"/> from the collection of
5709	shared folders and stops sharing it.
5710
5711	<result name="VBOX_E_INVALID_VM_STATE">
5712	Virtual machine is not mutable.
5713	</result>
5714	<result name="VBOX_E_OBJECT_NOT_FOUND">
5715	Shared folder @a name does not exist.
5716	</result>
5717
5718	</desc>
5719	<param name="name" type="wstring" dir="in">
5720	<desc>Logical name of the shared folder to remove.</desc>
5721	</param>
5722	</method>
5723
5724	<method name="canShowConsoleWindow">
5725	<desc>
5726	Returns @c true if the VM console process can activate the
5727	console window and bring it to foreground on the desktop of
5728	the host PC.
5729	<note>
5730	This method will fail if a session for this machine is not
5731	currently open.
5732	</note>
5733
5734	<result name="VBOX_E_INVALID_VM_STATE">
5735	Machine session is not open.
5736	</result>
5737
5738	</desc>
5739	<param name="canShow" type="boolean" dir="return">
5740	<desc>
5741	@c true if the console window can be shown and @c false otherwise.
5742	</desc>
5743	</param>
5744	</method>
5745
5746	<method name="showConsoleWindow">
5747	<desc>
5748	Activates the console window and brings it to foreground on
5749	the desktop of the host PC. Many modern window managers on
5750	many platforms implement some sort of focus stealing
5751	prevention logic, so that it may be impossible to activate
5752	a window without the help of the currently active
5753	application. In this case, this method will return a non-zero
5754	identifier that represents the top-level window of the VM
5755	console process. The caller, if it represents a currently
5756	active process, is responsible to use this identifier (in a
5757	platform-dependent manner) to perform actual window
5758	activation.
5759	<note>
5760	This method will fail if a session for this machine is not
5761	currently open.
5762	</note>
5763
5764	<result name="VBOX_E_INVALID_VM_STATE">
5765	Machine session is not open.
5766	</result>
5767
5768	</desc>
5769	<param name="winId" type="unsigned long long" dir="return">
5770	<desc>
5771	Platform-dependent identifier of the top-level VM console
5772	window, or zero if this method has performed all actions
5773	necessary to implement the <i>show window</i> semantics for
5774	the given platform and/or VirtualBox front-end.
5775	</desc>
5776	</param>
5777	</method>
5778
5779	<method name="getGuestProperty" const="yes">
5780	<desc>
5781	Reads an entry from the machine's guest property store.
5782
5783	<result name="VBOX_E_INVALID_VM_STATE">
5784	Machine session is not open.
5785	</result>
5786
5787	</desc>
5788	<param name="name" type="wstring" dir="in">
5789	<desc>
5790	The name of the property to read.
5791	</desc>
5792	</param>
5793	<param name="value" type="wstring" dir="out">
5794	<desc>
5795	The value of the property. If the property does not exist then this
5796	will be empty.
5797	</desc>
5798	</param>
5799	<param name="timestamp" type="unsigned long long" dir="out">
5800	<desc>
5801	The time at which the property was last modified, as seen by the
5802	server process.
5803	</desc>
5804	</param>
5805	<param name="flags" type="wstring" dir="out">
5806	<desc>
5807	Additional property parameters, passed as a comma-separated list of
5808	"name=value" type entries.
5809	</desc>
5810	</param>
5811	</method>
5812
5813	<method name="getGuestPropertyValue" const="yes">
5814	<desc>
5815	Reads a value from the machine's guest property store.
5816
5817	<result name="VBOX_E_INVALID_VM_STATE">
5818	Machine session is not open.
5819	</result>
5820
5821	</desc>
5822	<param name="property" type="wstring" dir="in">
5823	<desc>
5824	The name of the property to read.
5825	</desc>
5826	</param>
5827	<param name="value" type="wstring" dir="return">
5828	<desc>
5829	The value of the property. If the property does not exist then this
5830	will be empty.
5831	</desc>
5832	</param>
5833	</method>
5834
5835	<method name="getGuestPropertyTimestamp" const="yes">
5836	<desc>
5837	Reads a property timestamp from the machine's guest property store.
5838
5839	<result name="VBOX_E_INVALID_VM_STATE">
5840	Machine session is not open.
5841	</result>
5842
5843	</desc>
5844	<param name="property" type="wstring" dir="in">
5845	<desc>
5846	The name of the property to read.
5847	</desc>
5848	</param>
5849	<param name="value" type="unsigned long long" dir="return">
5850	<desc>
5851	The timestamp. If the property does not exist then this will be
5852	empty.
5853	</desc>
5854	</param>
5855	</method>
5856
5857	<method name="setGuestProperty">
5858	<desc>
5859	Sets, changes or deletes an entry in the machine's guest property
5860	store.
5861
5862	<result name="E_ACCESSDENIED">
5863	Property cannot be changed.
5864	</result>
5865	<result name="E_INVALIDARG">
5866	Invalid @a flags.
5867	</result>
5868	<result name="VBOX_E_INVALID_VM_STATE">
5869	Virtual machine is not mutable or session not open.
5870	</result>
5871	<result name="VBOX_E_INVALID_OBJECT_STATE">
5872	Cannot set transient property when machine not running.
5873	</result>
5874
5875	</desc>
5876	<param name="property" type="wstring" dir="in">
5877	<desc>
5878	The name of the property to set, change or delete.
5879	</desc>
5880	</param>
5881	<param name="value" type="wstring" dir="in">
5882	<desc>
5883	The new value of the property to set, change or delete. If the
5884	property does not yet exist and value is non-empty, it will be
5885	created. If the value is @c null or empty, the property will be
5886	deleted if it exists.
5887	</desc>
5888	</param>
5889	<param name="flags" type="wstring" dir="in">
5890	<desc>
5891	Additional property parameters, passed as a comma-separated list of
5892	"name=value" type entries.
5893	</desc>
5894	</param>
5895	</method>
5896
5897	<method name="setGuestPropertyValue">
5898	<desc>
5899	Sets, changes or deletes a value in the machine's guest property
5900	store. The flags field will be left unchanged or created empty for a
5901	new property.
5902
5903	<result name="E_ACCESSDENIED">
5904	Property cannot be changed.
5905	</result>
5906	<result name="VBOX_E_INVALID_VM_STATE">
5907	Virtual machine is not mutable or session not open.
5908	</result>
5909	<result name="VBOX_E_INVALID_OBJECT_STATE">
5910	Cannot set transient property when machine not running.
5911	</result>
5912	</desc>
5913
5914	<param name="property" type="wstring" dir="in">
5915	<desc>
5916	The name of the property to set, change or delete.
5917	</desc>
5918	</param>
5919	<param name="value" type="wstring" dir="in">
5920	<desc>
5921	The new value of the property to set, change or delete. If the
5922	property does not yet exist and value is non-empty, it will be
5923	created. If the value is @c null or empty, the property will be
5924	deleted if it exists.
5925	</desc>
5926	</param>
5927	</method>
5928
5929	<method name="enumerateGuestProperties">
5930	<desc>
5931	Return a list of the guest properties matching a set of patterns along
5932	with their values, time stamps and flags.
5933	</desc>
5934	<param name="patterns" type="wstring" dir="in">
5935	<desc>
5936	The patterns to match the properties against, separated by '\|'
5937	characters. If this is empty or @c null, all properties will match.
5938	</desc>
5939	</param>
5940	<param name="name" type="wstring" dir="out" safearray="yes">
5941	<desc>
5942	The names of the properties returned.
5943	</desc>
5944	</param>
5945	<param name="value" type="wstring" dir="out" safearray="yes">
5946	<desc>
5947	The values of the properties returned. The array entries match the
5948	corresponding entries in the @a name array.
5949	</desc>
5950	</param>
5951	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5952	<desc>
5953	The time stamps of the properties returned. The array entries match
5954	the corresponding entries in the @a name array.
5955	</desc>
5956	</param>
5957	<param name="flags" type="wstring" dir="out" safearray="yes">
5958	<desc>
5959	The flags of the properties returned. The array entries match the
5960	corresponding entries in the @a name array.
5961	</desc>
5962	</param>
5963	</method>
5964
5965	<method name="querySavedThumbnailSize">
5966	<desc>
5967	Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
5968	</desc>
5969	<param name="size" type="unsigned long" dir="out">
5970	<desc>
5971	Size of buffer required to store the bitmap.
5972	</desc>
5973	</param>
5974	<param name="width" type="unsigned long" dir="out">
5975	<desc>
5976	Bitmap width.
5977	</desc>
5978	</param>
5979	<param name="height" type="unsigned long" dir="out">
5980	<desc>
5981	Bitmap height.
5982	</desc>
5983	</param>
5984	</method>
5985
5986	<method name="readSavedThumbnailToArray">
5987	<desc>
5988	Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
5989	</desc>
5990	<param name="BGR" type="boolean" dir="in">
5991	<desc>
5992	How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
5993	bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
5994	</desc>
5995	</param>
5996	<param name="width" type="unsigned long" dir="out">
5997	<desc>
5998	Bitmap width.
5999	</desc>
6000	</param>
6001	<param name="height" type="unsigned long" dir="out">
6002	<desc>
6003	Bitmap height.
6004	</desc>
6005	</param>
6006	<param name="data" type="octet" dir="return" safearray="yes">
6007	<desc>
6008	Array with resulting bitmap data.
6009	</desc>
6010	</param>
6011	</method>
6012
6013	<method name="querySavedScreenshotPNGSize">
6014	<desc>
6015	Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
6016	</desc>
6017	<param name="size" type="unsigned long" dir="out">
6018	<desc>
6019	Size of buffer required to store the PNG binary data.
6020	</desc>
6021	</param>
6022	<param name="width" type="unsigned long" dir="out">
6023	<desc>
6024	Image width.
6025	</desc>
6026	</param>
6027	<param name="height" type="unsigned long" dir="out">
6028	<desc>
6029	Image height.
6030	</desc>
6031	</param>
6032	</method>
6033
6034	<method name="readSavedScreenshotPNGToArray">
6035	<desc>
6036	Screenshot in PNG format is retrieved to an array of bytes.
6037	</desc>
6038	<param name="width" type="unsigned long" dir="out">
6039	<desc>
6040	Image width.
6041	</desc>
6042	</param>
6043	<param name="height" type="unsigned long" dir="out">
6044	<desc>
6045	Image height.
6046	</desc>
6047	</param>
6048	<param name="data" type="octet" dir="return" safearray="yes">
6049	<desc>
6050	Array with resulting PNG data.
6051	</desc>
6052	</param>
6053	</method>
6054
6055	<method name="hotPlugCPU">
6056	<desc>
6057	Plugs a CPU into the machine.
6058	</desc>
6059	<param name="cpu" type="unsigned long" dir="in">
6060	<desc>
6061	The CPU id to insert.
6062	</desc>
6063	</param>
6064	</method>
6065
6066	<method name="hotUnplugCPU">
6067	<desc>
6068	Removes a CPU from the machine.
6069	</desc>
6070	<param name="cpu" type="unsigned long" dir="in">
6071	<desc>
6072	The CPU id to remove.
6073	</desc>
6074	</param>
6075	</method>
6076
6077	<method name="getCPUStatus">
6078	<desc>
6079	Returns the current status of the given CPU.
6080	</desc>
6081	<param name="cpu" type="unsigned long" dir="in">
6082	<desc>
6083	The CPU id to check for.
6084	</desc>
6085	</param>
6086	<param name="attached" type="boolean" dir="return">
6087	<desc>
6088	Status of the CPU.
6089	</desc>
6090	</param>
6091	</method>
6092
6093	<method name="queryLogFilename">
6094	<desc>
6095	Queries for the VM log file name of an given index. Returns an empty
6096	string if a log file with that index doesn't exists.
6097	</desc>
6098	<param name="idx" type="unsigned long" dir="in">
6099	<desc>
6100	Which log file name to query. 0=current log file.
6101	</desc>
6102	</param>
6103	<param name="filename" type="wstring" dir="return">
6104	<desc>
6105	On return the full path to the log file or an empty string on error.
6106	</desc>
6107	</param>
6108	</method>
6109
6110	<method name="readLog">
6111	<desc>
6112	Reads the VM log file. The chunk size is limited, so even if you
6113	ask for a big piece there might be less data returned.
6114	</desc>
6115	<param name="idx" type="unsigned long" dir="in">
6116	<desc>
6117	Which log file to read. 0=current log file.
6118	</desc>
6119	</param>
6120	<param name="offset" type="unsigned long long" dir="in">
6121	<desc>
6122	Offset in the log file.
6123	</desc>
6124	</param>
6125	<param name="size" type="unsigned long long" dir="in">
6126	<desc>
6127	Chunk size to read in the log file.
6128	</desc>
6129	</param>
6130	<param name="data" type="octet" dir="return" safearray="yes">
6131	<desc>
6132	Data read from the log file. A data size of 0 means end of file
6133	if the requested chunk size was not 0. This is the unprocessed
6134	file data, i.e. the line ending style depends on the platform of
6135	the system the server is running on.
6136	</desc>
6137	</param>
6138	</method>
6139	</interface>
6140
6141	<!--
6142	// IConsole
6143	/////////////////////////////////////////////////////////////////////////
6144	-->
6145
6146	<interface
6147	name="IConsoleCallback" extends="$unknown"
6148	uuid="60703f8d-81e4-4b45-a147-dcfd07692b19"
6149	wsmap="suppress"
6150	>
6151
6152	<desc>
6153	This interface is used by a client of the Main API that need to
6154	be notified of events. For example, a graphical user interface
6155	can use this to learn about machine state changes so they can
6156	update the list of virtual machines without having to rely
6157	on polling.
6158
6159	Whenever relevant events occur in VirtualBox, the callbacks in
6160	objects of this interface are called. In order for this to be
6161	useful, a client needs to create its own subclass that implements
6162	this interface in which the methods for the relevant callbacks
6163	are overridden. An instance of this subclass interface can then
6164	be passed to <link to="IConsole::registerCallback" />.
6165	</desc>
6166
6167	<method name="onMousePointerShapeChange">
6168	<desc>
6169	Notification when the guest mouse pointer shape has
6170	changed. The new shape data is given.
6171	<result name="VBOX_E_DONT_CALL_AGAIN">
6172	Do not call again, this method is a NOP.
6173	</result>
6174	</desc>
6175	<param name="visible" type="boolean" dir="in">
6176	<desc>
6177	Flag whether the pointer is visible.
6178	</desc>
6179	</param>
6180	<param name="alpha" type="boolean" dir="in">
6181	<desc>
6182	Flag whether the pointer has an alpha channel.
6183	</desc>
6184	</param>
6185	<param name="xHot" type="unsigned long" dir="in">
6186	<desc>
6187	The pointer hot spot x coordinate.
6188	</desc>
6189	</param>
6190	<param name="yHot" type="unsigned long" dir="in">
6191	<desc>
6192	The pointer hot spot y coordinate.
6193	</desc>
6194	</param>
6195	<param name="width" type="unsigned long" dir="in">
6196	<desc>
6197	Width of the pointer shape in pixels.
6198	</desc>
6199	</param>
6200	<param name="height" type="unsigned long" dir="in">
6201	<desc>
6202	Height of the pointer shape in pixels.
6203	</desc>
6204	</param>
6205	<param name="shape" type="octet" mod="ptr" dir="in">
6206	<desc>
6207	Address of the shape buffer.
6208
6209	The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
6210	followed by a 32-bpp XOR (color) mask.
6211
6212	For pointers without alpha channel the XOR mask pixels are 32
6213	bit values: (lsb)BGR0(msb). For pointers with alpha channel
6214	the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
6215
6216	An AND mask is used for pointers with alpha channel, so if the
6217	callback does not support alpha, the pointer could be
6218	displayed as a normal color pointer.
6219
6220	The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
6221	size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
6222	height</tt>. The padding bits at the end of each scanline are
6223	undefined.
6224
6225	The XOR mask follows the AND mask on the next 4-byte aligned
6226	offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
6227	Bytes in the gap between the AND and the XOR mask are undefined.
6228	The XOR mask scanlines have no gap between them and the size of
6229	the XOR mask is: <tt>cXor = width * 4 * height</tt>.
6230
6231	<note>
6232	If @a shape is 0, only the pointer visibility is changed.
6233	</note>
6234	</desc>
6235	</param>
6236	</method>
6237
6238	<method name="onMouseCapabilityChange">
6239	<desc>
6240	Notification when the mouse capabilities reported by the
6241	guest have changed. The new capabilities are passed.
6242	<result name="VBOX_E_DONT_CALL_AGAIN">
6243	Do not call again, this method is a NOP.
6244	</result>
6245	</desc>
6246	<param name="supportsAbsolute" type="boolean" dir="in"/>
6247	<param name="supportsRelative" type="boolean" dir="in"/>
6248	<param name="needsHostCursor" type="boolean" dir="in"/>
6249	</method>
6250
6251	<method name="onKeyboardLedsChange">
6252	<desc>
6253	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
6254	to alter the state of the keyboard LEDs.
6255	<result name="VBOX_E_DONT_CALL_AGAIN">
6256	Do not call again, this method is a NOP.
6257	</result>
6258	</desc>
6259	<param name="numLock" type="boolean" dir="in"/>
6260	<param name="capsLock" type="boolean" dir="in"/>
6261	<param name="scrollLock" type="boolean" dir="in"/>
6262	</method>
6263
6264	<method name="onStateChange">
6265	<desc>
6266	Notification when the execution state of the machine has changed.
6267	The new state will be given.
6268	<result name="VBOX_E_DONT_CALL_AGAIN">
6269	Do not call again, this method is a NOP.
6270	</result>
6271	</desc>
6272	<param name="state" type="MachineState" dir="in"/>
6273	</method>
6274
6275	<method name="onAdditionsStateChange">
6276	<desc>
6277	Notification when a Guest Additions property changes.
6278	Interested callees should query IGuest attributes to
6279	find out what has changed.
6280	</desc>
6281	</method>
6282
6283	<method name="onNetworkAdapterChange">
6284	<desc>
6285	Notification when a property of one of the
6286	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
6287	changes. Interested callees should use INetworkAdapter methods and
6288	attributes to find out what has changed.
6289	<result name="VBOX_E_DONT_CALL_AGAIN">
6290	Do not call again, this method is a NOP.
6291	</result>
6292	</desc>
6293	<param name="networkAdapter" type="INetworkAdapter" dir="in">
6294	<desc>Network adapter that is subject to change.</desc>
6295	</param>
6296	</method>
6297
6298	<method name="onSerialPortChange">
6299	<desc>
6300	Notification when a property of one of the
6301	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
6302	Interested callees should use ISerialPort methods and attributes
6303	to find out what has changed.
6304	<result name="VBOX_E_DONT_CALL_AGAIN">
6305	Do not call again, this method is a NOP.
6306	</result>
6307	</desc>
6308	<param name="serialPort" type="ISerialPort" dir="in">
6309	<desc>Serial port that is subject to change.</desc>
6310	</param>
6311	</method>
6312
6313	<method name="onParallelPortChange">
6314	<desc>
6315	Notification when a property of one of the
6316	virtual <link to="IMachine::getParallelPort">parallel ports</link>
6317	changes. Interested callees should use ISerialPort methods and
6318	attributes to find out what has changed.
6319	<result name="VBOX_E_DONT_CALL_AGAIN">
6320	Do not call again, this method is a NOP.
6321	</result>
6322	</desc>
6323	<param name="parallelPort" type="IParallelPort" dir="in">
6324	<desc>Parallel port that is subject to change.</desc>
6325	</param>
6326	</method>
6327
6328	<method name="onStorageControllerChange">
6329	<desc>
6330	Notification when a property of one of the
6331	virtual <link to="IMachine::storageControllers">storage controllers</link>
6332	changes. Interested callees should query the corresponding collections
6333	to find out what has changed.
6334	<result name="VBOX_E_DONT_CALL_AGAIN">
6335	Do not call again, this method is a NOP.
6336	</result>
6337	</desc>
6338	</method>
6339
6340	<method name="onMediumChange">
6341	<desc>
6342	Notification when a
6343	<link to="IMachine::mediumAttachments">medium attachment</link>
6344	changes.
6345	<result name="VBOX_E_DONT_CALL_AGAIN">
6346	Do not call again, this method is a NOP.
6347	</result>
6348	</desc>
6349	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
6350	<desc>Medium attachment that is subject to change.</desc>
6351	</param>
6352	</method>
6353
6354	<method name="onCPUChange">
6355	<desc>
6356	Notification when a CPU changes.
6357	<result name="VBOX_E_DONT_CALL_AGAIN">
6358	Do not call again, this method is a NOP.
6359	</result>
6360	</desc>
6361	<param name="cpu" type="unsigned long" dir="in">
6362	<desc>The CPU which changed</desc>
6363	</param>
6364	<param name="add" type="boolean" dir="in">
6365	<desc>Flag whether the CPU was added or removed</desc>
6366	</param>
6367	</method>
6368
6369	<method name="onVRDPServerChange">
6370	<desc>
6371	Notification when a property of the
6372	<link to="IMachine::VRDPServer">VRDP server</link> changes.
6373	Interested callees should use IVRDPServer methods and attributes to
6374	find out what has changed.
6375	<result name="VBOX_E_DONT_CALL_AGAIN">
6376	Do not call again, this method is a NOP.
6377	</result>
6378	</desc>
6379	</method>
6380
6381	<method name="onRemoteDisplayInfoChange">
6382	<desc>
6383	Notification when the status of the VRDP server changes. Interested callees
6384	should use <link to="IConsole::RemoteDisplayInfo">IRemoteDisplayInfo</link>
6385	attributes to find out what is the current status.
6386	<result name="VBOX_E_DONT_CALL_AGAIN">
6387	Do not call again, this method is a NOP.
6388	</result>
6389	</desc>
6390	</method>
6391
6392	<method name="onUSBControllerChange">
6393	<desc>
6394	Notification when a property of the virtual
6395	<link to="IMachine::USBController">USB controller</link> changes.
6396	Interested callees should use IUSBController methods and attributes to
6397	find out what has changed.
6398	<result name="VBOX_E_DONT_CALL_AGAIN">
6399	Do not call again, this method is a NOP.
6400	</result>
6401	</desc>
6402	</method>
6403
6404	<method name="onUSBDeviceStateChange">
6405	<desc>
6406	Notification when a USB device is attached to or detached from
6407	the virtual USB controller.
6408
6409	This notification is sent as a result of the indirect
6410	request to attach the device because it matches one of the
6411	machine USB filters, or as a result of the direct request
6412	issued by <link to="IConsole::attachUSBDevice"/> or
6413	<link to="IConsole::detachUSBDevice"/>.
6414
6415	This notification is sent in case of both a succeeded and a
6416	failed request completion. When the request succeeds, the
6417	@a error parameter is @c null, and the given device has been
6418	already added to (when @a attached is @c true) or removed from
6419	(when @a attached is @c false) the collection represented by
6420	<link to="IConsole::USBDevices"/>. On failure, the collection
6421	doesn't change and the @a error parameter represents the error
6422	message describing the failure.
6423
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="device" type="IUSBDevice" dir="in">
6429	<desc>Device that is subject to state change.</desc>
6430	</param>
6431	<param name="attached" type="boolean" dir="in">
6432	<desc>
6433	@c true if the device was attached and @c false otherwise.
6434	</desc>
6435	</param>
6436	<param name="error" type="IVirtualBoxErrorInfo" dir="in">
6437	<desc>
6438	@c null on success or an error message object on failure.
6439	</desc>
6440	</param>
6441	</method>
6442
6443	<method name="onSharedFolderChange">
6444	<desc>
6445	Notification when a shared folder is added or removed.
6446	The @a scope argument defines one of three scopes:
6447	<link to="IVirtualBox::sharedFolders">global shared folders</link>
6448	(<link to="Scope_Global">Global</link>),
6449	<link to="IMachine::sharedFolders">permanent shared folders</link> of
6450	the machine (<link to="Scope_Machine">Machine</link>) or <link
6451	to="IConsole::sharedFolders">transient shared folders</link> of the
6452	machine (<link to="Scope_Session">Session</link>). Interested callees
6453	should use query the corresponding collections to find out what has
6454	changed.
6455	<result name="VBOX_E_DONT_CALL_AGAIN">
6456	Do not call again, this method is a NOP.
6457	</result>
6458	</desc>
6459	<param name="scope" type="Scope" dir="in">
6460	<desc>Scope of the notification.</desc>
6461	</param>
6462	</method>
6463
6464	<method name="onRuntimeError">
6465	<desc>
6466	Notification when an error happens during the virtual
6467	machine execution.
6468
6469	There are three kinds of runtime errors:
6470	<ul>
6471	<li><i>fatal</i></li>
6472	<li><i>non-fatal with retry</i></li>
6473	<li><i>non-fatal warnings</i></li>
6474	</ul>
6475
6476	<b>Fatal</b> errors are indicated by the @a fatal parameter set
6477	to @c true. In case of fatal errors, the virtual machine
6478	execution is always paused before calling this notification, and
6479	the notification handler is supposed either to immediately save
6480	the virtual machine state using <link to="IConsole::saveState"/>
6481	or power it off using <link to="IConsole::powerDown"/>.
6482	Resuming the execution can lead to unpredictable results.
6483
6484	<b>Non-fatal</b> errors and warnings are indicated by the
6485	@a fatal parameter set to @c false. If the virtual machine
6486	is in the Paused state by the time the error notification is
6487	received, it means that the user can <i>try to resume</i> the machine
6488	execution after attempting to solve the problem that caused the
6489	error. In this case, the notification handler is supposed
6490	to show an appropriate message to the user (depending on the
6491	value of the @a id parameter) that offers several actions such
6492	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
6493	wants to retry, the notification handler should continue
6494	the machine execution using the <link to="IConsole::resume"/>
6495	call. If the machine execution is not Paused during this
6496	notification, then it means this notification is a <i>warning</i>
6497	(for example, about a fatal condition that can happen very soon);
6498	no immediate action is required from the user, the machine
6499	continues its normal execution.
6500
6501	Note that in either case the notification handler
6502	<b>must not</b> perform any action directly on a thread
6503	where this notification is called. Everything it is allowed to
6504	do is to post a message to another thread that will then talk
6505	to the user and take the corresponding action.
6506
6507	Currently, the following error identifiers are known:
6508	<ul>
6509	<li><tt>"HostMemoryLow"</tt></li>
6510	<li><tt>"HostAudioNotResponding"</tt></li>
6511	<li><tt>"VDIStorageFull"</tt></li>
6512	<li><tt>"3DSupportIncompatibleAdditions"</tt></li>
6513	</ul>
6514
6515	<note>
6516	This notification is not designed to be implemented by
6517	more than one callback at a time. If you have multiple
6518	IConsoleCallback instances registered on the given
6519	IConsole object, make sure you simply do nothing but
6520	return @c S_OK from all but one of them that does actual
6521	user notification and performs necessary actions.
6522	</note>
6523
6524	<result name="VBOX_E_DONT_CALL_AGAIN">
6525	Do not call again, this method is a NOP.
6526	</result>
6527	</desc>
6528	<param name="fatal" type="boolean" dir="in">
6529	<desc>Whether the error is fatal or not</desc>
6530	</param>
6531	<param name="id" type="wstring" dir="in">
6532	<desc>Error identifier</desc>
6533	</param>
6534	<param name="message" type="wstring" dir="in">
6535	<desc>Optional error message</desc>
6536	</param>
6537	</method>
6538
6539	<method name="onCanShowWindow">
6540	<desc>
6541	Notification when a call to
6542	<link to="IMachine::canShowConsoleWindow"/> is made by a
6543	front-end to check if a subsequent call to
6544	<link to="IMachine::showConsoleWindow"/> can succeed.
6545
6546	The callee should give an answer appropriate to the current
6547	machine state in the @a canShow argument. This answer must
6548	remain valid at least until the next
6549	<link to="IConsole::state">machine state</link> change.
6550
6551	<note>
6552	This notification is not designed to be implemented by
6553	more than one callback at a time. If you have multiple
6554	IConsoleCallback instances registered on the given
6555	IConsole object, make sure you simply do nothing but
6556	return @c true and @c S_OK from all but one of them that
6557	actually manages console window activation.
6558	</note>
6559
6560	<result name="VBOX_E_DONT_CALL_AGAIN">
6561	Do not call again, this method is a NOP.
6562	</result>
6563	</desc>
6564	<param name="canShow" type="boolean" dir="return">
6565	<desc>
6566	@c true if the console window can be shown and @c false otherwise.
6567	</desc>
6568	</param>
6569	</method>
6570
6571	<method name="onShowWindow">
6572	<desc>
6573	Notification when a call to
6574	<link to="IMachine::showConsoleWindow"/>
6575	requests the console window to be activated and brought to
6576	foreground on the desktop of the host PC.
6577
6578	This notification should cause the VM console process to
6579	perform the requested action as described above. If it is
6580	impossible to do it at a time of this notification, this
6581	method should return a failure.
6582
6583	Note that many modern window managers on many platforms
6584	implement some sort of focus stealing prevention logic, so
6585	that it may be impossible to activate a window without the
6586	help of the currently active application (which is supposedly
6587	an initiator of this notification). In this case, this method
6588	must return a non-zero identifier that represents the
6589	top-level window of the VM console process. The caller, if it
6590	represents a currently active process, is responsible to use
6591	this identifier (in a platform-dependent manner) to perform
6592	actual window activation.
6593
6594	This method must set @a winId to zero if it has performed all
6595	actions necessary to complete the request and the console
6596	window is now active and in foreground, to indicate that no
6597	further action is required on the caller's side.
6598
6599	<note>
6600	This notification is not designed to be implemented by
6601	more than one callback at a time. If you have multiple
6602	IConsoleCallback instances registered on the given
6603	IConsole object, make sure you simply do nothing but
6604	return @c S_OK from all but one of them that actually
6605	manages console window activation.
6606	</note>
6607
6608	<result name="VBOX_E_DONT_CALL_AGAIN">
6609	Do not call again, this method is a NOP.
6610	</result>
6611	</desc>
6612	<param name="winId" type="unsigned long long" dir="return">
6613	<desc>
6614	Platform-dependent identifier of the top-level VM console
6615	window, or zero if this method has performed all actions
6616	necessary to implement the <i>show window</i> semantics for
6617	the given platform and/or this VirtualBox front-end.
6618	</desc>
6619	</param>
6620	</method>
6621
6622	</interface>
6623
6624	<interface
6625	name="IRemoteDisplayInfo" extends="$unknown"
6626	uuid="b3741084-806f-4c3b-8c42-ebad1a81e45a"
6627	wsmap="struct"
6628	>
6629	<desc>
6630	Contains information about the remote display (VRDP) capabilities and status.
6631	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
6632	</desc>
6633
6634	<attribute name="active" type="boolean" readonly="yes">
6635	<desc>
6636	Whether the remote display connection is active.
6637	</desc>
6638	</attribute>
6639
6640	<attribute name="port" type="long" readonly="yes">
6641	<desc>
6642	VRDP server port number. If this property is equal to <tt>0</tt>, then
6643	the VRDP server failed to start, usually because there are no free TCP
6644	ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDP
6645	server has not yet been started.
6646	</desc>
6647	</attribute>
6648
6649	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
6650	<desc>
6651	How many times a client connected.
6652	</desc>
6653	</attribute>
6654
6655	<attribute name="beginTime" type="long long" readonly="yes">
6656	<desc>
6657	When the last connection was established, in milliseconds since 1970-01-01 UTC.
6658	</desc>
6659	</attribute>
6660
6661	<attribute name="endTime" type="long long" readonly="yes">
6662	<desc>
6663	When the last connection was terminated or the current time, if
6664	connection is still active, in milliseconds since 1970-01-01 UTC.
6665	</desc>
6666	</attribute>
6667
6668	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
6669	<desc>
6670	How many bytes were sent in last or current, if still active, connection.
6671	</desc>
6672	</attribute>
6673
6674	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
6675	<desc>
6676	How many bytes were sent in all connections.
6677	</desc>
6678	</attribute>
6679
6680	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
6681	<desc>
6682	How many bytes were received in last or current, if still active, connection.
6683	</desc>
6684	</attribute>
6685
6686	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
6687	<desc>
6688	How many bytes were received in all connections.
6689	</desc>
6690	</attribute>
6691
6692	<attribute name="user" type="wstring" readonly="yes">
6693	<desc>
6694	Login user name supplied by the client.
6695	</desc>
6696	</attribute>
6697
6698	<attribute name="domain" type="wstring" readonly="yes">
6699	<desc>
6700	Login domain name supplied by the client.
6701	</desc>
6702	</attribute>
6703
6704	<attribute name="clientName" type="wstring" readonly="yes">
6705	<desc>
6706	The client name supplied by the client.
6707	</desc>
6708	</attribute>
6709
6710	<attribute name="clientIP" type="wstring" readonly="yes">
6711	<desc>
6712	The IP address of the client.
6713	</desc>
6714	</attribute>
6715
6716	<attribute name="clientVersion" type="unsigned long" readonly="yes">
6717	<desc>
6718	The client software version number.
6719	</desc>
6720	</attribute>
6721
6722	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
6723	<desc>
6724	Public key exchange method used when connection was established.
6725	Values: 0 - RDP4 public key exchange scheme.
6726	1 - X509 certificates were sent to client.
6727	</desc>
6728	</attribute>
6729
6730	</interface>
6731
6732	<interface
6733	name="IConsole" extends="$unknown"
6734	uuid="6375231a-c17c-464b-92cb-ae9e128d71c3"
6735	wsmap="managed"
6736	>
6737	<desc>
6738	The IConsole interface represents an interface to control virtual
6739	machine execution.
6740
6741	The console object that implements the IConsole interface is obtained
6742	from a session object after the session for the given machine has been
6743	opened using one of <link to="IVirtualBox::openSession"/>,
6744	<link to="IVirtualBox::openRemoteSession"/> or
6745	<link to="IVirtualBox::openExistingSession"/> methods.
6746
6747	Methods of the IConsole interface allow the caller to query the current
6748	virtual machine execution state, pause the machine or power it down, save
6749	the machine state or take a snapshot, attach and detach removable media
6750	and so on.
6751
6752	<see>ISession</see>
6753	</desc>
6754
6755	<attribute name="machine" type="IMachine" readonly="yes">
6756	<desc>
6757	Machine object this console is sessioned with.
6758	<note>
6759	This is a convenience property, it has the same value as
6760	<link to="ISession::machine"/> of the corresponding session
6761	object.
6762	</note>
6763	</desc>
6764	</attribute>
6765
6766	<attribute name="state" type="MachineState" readonly="yes">
6767	<desc>
6768	Current execution state of the machine.
6769	<note>
6770	This property always returns the same value as the corresponding
6771	property of the IMachine object this console is sessioned with.
6772	For the process that owns (executes) the VM, this is the
6773	preferable way of querying the VM state, because no IPC
6774	calls are made.
6775	</note>
6776	</desc>
6777	</attribute>
6778
6779	<attribute name="guest" type="IGuest" readonly="yes">
6780	<desc>Guest object.</desc>
6781	</attribute>
6782
6783	<attribute name="keyboard" type="IKeyboard" readonly="yes">
6784	<desc>
6785	Virtual keyboard object.
6786	<note>
6787	If the machine is not running, any attempt to use
6788	the returned object will result in an error.
6789	</note>
6790	</desc>
6791	</attribute>
6792
6793	<attribute name="mouse" type="IMouse" readonly="yes">
6794	<desc>
6795	Virtual mouse object.
6796	<note>
6797	If the machine is not running, any attempt to use
6798	the returned object will result in an error.
6799	</note>
6800	</desc>
6801	</attribute>
6802
6803	<attribute name="display" type="IDisplay" readonly="yes">
6804	<desc>Virtual display object.
6805	<note>
6806	If the machine is not running, any attempt to use
6807	the returned object will result in an error.
6808	</note>
6809	</desc>
6810	</attribute>
6811
6812	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
6813	<desc>Debugging interface.</desc>
6814	</attribute>
6815
6816	<attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6817	<desc>
6818	Collection of USB devices currently attached to the virtual
6819	USB controller.
6820	<note>
6821	The collection is empty if the machine is not running.
6822	</note>
6823	</desc>
6824	</attribute>
6825
6826	<attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6827	<desc>
6828	List of USB devices currently attached to the remote VRDP client.
6829	Once a new device is physically attached to the remote host computer,
6830	it appears in this list and remains there until detached.
6831	</desc>
6832	</attribute>
6833
6834	<attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6835	<desc>
6836	Collection of shared folders for the current session. These folders
6837	are called transient shared folders because they are available to the
6838	guest OS running inside the associated virtual machine only for the
6839	duration of the session (as opposed to
6840	<link to="IMachine::sharedFolders"/> which represent permanent shared
6841	folders). When the session is closed (e.g. the machine is powered down),
6842	these folders are automatically discarded.
6843
6844	New shared folders are added to the collection using
6845	<link to="#createSharedFolder"/>. Existing shared folders can be
6846	removed using <link to="#removeSharedFolder"/>.
6847	</desc>
6848	</attribute>
6849
6850	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
6851	<desc>
6852	Interface that provides information on Remote Display (VRDP) connection.
6853	</desc>
6854	</attribute>
6855
6856	<method name="powerUp">
6857	<desc>
6858	Starts the virtual machine execution using the current machine
6859	state (that is, its current execution state, current settings and
6860	current storage devices).
6861
6862	If the machine is powered off or aborted, the execution will
6863	start from the beginning (as if the real hardware were just
6864	powered on).
6865
6866	If the machine is in the <link to="MachineState_Saved"/> state,
6867	it will continue its execution the point where the state has
6868	been saved.
6869
6870	<note>
6871	Unless you are trying to write a new VirtualBox front-end that
6872	performs direct machine execution (like the VirtualBox or VBoxSDL
6873	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
6874	session opened by <link to="IVirtualBox::openSession"/> and use this
6875	session only to change virtual machine settings. If you simply want to
6876	start virtual machine execution using one of the existing front-ends
6877	(for example the VirtualBox GUI or headless server), simply use
6878	<link to="IVirtualBox::openRemoteSession"/>; these front-ends will
6879	power up the machine automatically for you.
6880	</note>
6881
6882	<see>#saveState</see>
6883	<result name="VBOX_E_INVALID_VM_STATE">
6884	Virtual machine already running.
6885	</result>
6886	<result name="VBOX_E_HOST_ERROR">
6887	Host interface does not exist or name not set.
6888	</result>
6889	<result name="VBOX_E_FILE_ERROR">
6890	Invalid saved state file.
6891	</result>
6892	</desc>
6893	<param name="progress" type="IProgress" dir="return">
6894	<desc>Progress object to track the operation completion.</desc>
6895	</param>
6896	</method>
6897
6898	<method name="powerUpPaused">
6899	<desc>
6900	Identical to powerUp except that the VM will enter the
6901	<link to="MachineState_Paused"/> state, instead of
6902	<link to="MachineState_Running"/>.
6903
6904	<see>#powerUp</see>
6905	<result name="VBOX_E_INVALID_VM_STATE">
6906	Virtual machine already running.
6907	</result>
6908	<result name="VBOX_E_HOST_ERROR">
6909	Host interface does not exist or name not set.
6910	</result>
6911	<result name="VBOX_E_FILE_ERROR">
6912	Invalid saved state file.
6913	</result>
6914	</desc>
6915	<param name="progress" type="IProgress" dir="return">
6916	<desc>Progress object to track the operation completion.</desc>
6917	</param>
6918	</method>
6919
6920	<method name="powerDown">
6921	<desc>
6922	Initiates the power down procedure to stop the virtual machine
6923	execution.
6924
6925	The completion of the power down procedure is tracked using the returned
6926	IProgress object. After the operation is complete, the machine will go
6927	to the PoweredOff state.
6928	<result name="VBOX_E_INVALID_VM_STATE">
6929	Virtual machine must be Running, Paused or Stuck to be powered down.
6930	</result>
6931	</desc>
6932	<param name="progress" type="IProgress" dir="return">
6933	<desc>Progress object to track the operation completion.</desc>
6934	</param>
6935	</method>
6936
6937	<method name="reset">
6938	<desc>Resets the virtual machine.
6939	<result name="VBOX_E_INVALID_VM_STATE">
6940	Virtual machine not in Running state.
6941	</result>
6942	<result name="VBOX_E_VM_ERROR">
6943	Virtual machine error in reset operation.
6944	</result>
6945	</desc>
6946	</method>
6947
6948	<method name="pause">
6949	<desc>Pauses the virtual machine execution.
6950	<result name="VBOX_E_INVALID_VM_STATE">
6951	Virtual machine not in Running state.
6952	</result>
6953	<result name="VBOX_E_VM_ERROR">
6954	Virtual machine error in suspend operation.
6955	</result>
6956	</desc>
6957	</method>
6958
6959	<method name="resume">
6960	<desc>Resumes the virtual machine execution.
6961	<result name="VBOX_E_INVALID_VM_STATE">
6962	Virtual machine not in Paused state.
6963	</result>
6964	<result name="VBOX_E_VM_ERROR">
6965	Virtual machine error in resume operation.
6966	</result>
6967	</desc>
6968	</method>
6969
6970	<method name="powerButton">
6971	<desc>Sends the ACPI power button event to the guest.
6972	<result name="VBOX_E_INVALID_VM_STATE">
6973	Virtual machine not in Running state.
6974	</result>
6975	<result name="VBOX_E_PDM_ERROR">
6976	Controlled power off failed.
6977	</result>
6978	</desc>
6979	</method>
6980
6981	<method name="sleepButton">
6982	<desc>Sends the ACPI sleep button event to the guest.
6983	<result name="VBOX_E_INVALID_VM_STATE">
6984	Virtual machine not in Running state.
6985	</result>
6986	<result name="VBOX_E_PDM_ERROR">
6987	Sending sleep button event failed.
6988	</result>
6989	</desc>
6990	</method>
6991
6992	<method name="getPowerButtonHandled">
6993	<desc>Checks if the last power button event was handled by guest.
6994	<result name="VBOX_E_PDM_ERROR">
6995	Checking if the event was handled by the guest OS failed.
6996	</result>
6997	</desc>
6998	<param name="handled" type="boolean" dir="return"/>
6999	</method>
7000
7001	<method name="getGuestEnteredACPIMode">
7002	<desc>Checks if the guest entered the ACPI mode G0 (working) or
7003	G1 (sleeping). If this method returns @c false, the guest will
7004	most likely not respond to external ACPI events.
7005	<result name="VBOX_E_INVALID_VM_STATE">
7006	Virtual machine not in Running state.
7007	</result>
7008	</desc>
7009	<param name="entered" type="boolean" dir="return"/>
7010	</method>
7011
7012	<method name="saveState">
7013	<desc>
7014	Saves the current execution state of a running virtual machine
7015	and stops its execution.
7016
7017	After this operation completes, the machine will go to the
7018	Saved state. Next time it is powered up, this state will
7019	be restored and the machine will continue its execution from
7020	the place where it was saved.
7021
7022	This operation differs from taking a snapshot to the effect
7023	that it doesn't create new differencing media. Also, once
7024	the machine is powered up from the state saved using this method,
7025	the saved state is deleted, so it will be impossible to return
7026	to this state later.
7027
7028	<note>
7029	On success, this method implicitly calls
7030	<link to="IMachine::saveSettings"/> to save all current machine
7031	settings (including runtime changes to the DVD medium, etc.).
7032	Together with the impossibility to change any VM settings when it is
7033	in the Saved state, this guarantees adequate hardware
7034	configuration of the machine when it is restored from the saved
7035	state file.
7036	</note>
7037
7038	<note>
7039	The machine must be in the Running or Paused state, otherwise
7040	the operation will fail.
7041	</note>
7042	<result name="VBOX_E_INVALID_VM_STATE">
7043	Virtual machine state neither Running nor Paused.
7044	</result>
7045	<result name="VBOX_E_FILE_ERROR">
7046	Failed to create directory for saved state file.
7047	</result>
7048
7049	<see><link to="#takeSnapshot"/></see>
7050	</desc>
7051	<param name="progress" type="IProgress" dir="return">
7052	<desc>Progress object to track the operation completion.</desc>
7053	</param>
7054	</method>
7055
7056	<method name="adoptSavedState">
7057	<desc>
7058	Associates the given saved state file to the virtual machine.
7059
7060	On success, the machine will go to the Saved state. Next time it is
7061	powered up, it will be restored from the adopted saved state and
7062	continue execution from the place where the saved state file was
7063	created.
7064
7065	The specified saved state file path may be absolute or relative to the
7066	folder the VM normally saves the state to (usually,
7067	<link to="IMachine::snapshotFolder"/>).
7068
7069	<note>
7070	It's a caller's responsibility to make sure the given saved state
7071	file is compatible with the settings of this virtual machine that
7072	represent its virtual hardware (memory size, storage disk configuration
7073	etc.). If there is a mismatch, the behavior of the virtual machine
7074	is undefined.
7075	</note>
7076	<result name="VBOX_E_INVALID_VM_STATE">
7077	Virtual machine state neither PoweredOff nor Aborted.
7078	</result>
7079	</desc>
7080	<param name="savedStateFile" type="wstring" dir="in">
7081	<desc>Path to the saved state file to adopt.</desc>
7082	</param>
7083	</method>
7084
7085	<method name="forgetSavedState">
7086	<desc>
7087	Forgets the saved state of the virtual machine previously created
7088	by <link to="#saveState"/>. Next time the machine is powered up, a
7089	clean boot will occur. If @a remove is @c true the saved state file
7090	is deleted.
7091	<note>
7092	This operation is equivalent to resetting or powering off
7093	the machine without doing a proper shutdown in the guest OS.
7094	</note>
7095	<result name="VBOX_E_INVALID_VM_STATE">
7096	Virtual machine not in state Saved.
7097	</result>
7098	</desc>
7099	<param name="remove" type="boolean" dir="in">
7100	<desc>If @c true remove the saved state file.</desc>
7101	</param>
7102	</method>
7103
7104	<method name="getDeviceActivity">
7105	<desc>
7106	Gets the current activity type of a given device or device group.
7107	<result name="E_INVALIDARG">
7108	Invalid device type.
7109	</result>
7110	</desc>
7111	<param name="type" type="DeviceType" dir="in"/>
7112	<param name="activity" type="DeviceActivity" dir="return"/>
7113	</method>
7114
7115	<method name="attachUSBDevice">
7116	<desc>
7117	Attaches a host USB device with the given UUID to the
7118	USB controller of the virtual machine.
7119
7120	The device needs to be in one of the following states:
7121	<link to="USBDeviceState_Busy"/>,
7122	<link to="USBDeviceState_Available"/> or
7123	<link to="USBDeviceState_Held"/>,
7124	otherwise an error is immediately returned.
7125
7126	When the device state is
7127	<link to="USBDeviceState_Busy">Busy</link>, an error may also
7128	be returned if the host computer refuses to release it for some reason.
7129
7130	<see>IUSBController::deviceFilters, USBDeviceState</see>
7131	<result name="VBOX_E_INVALID_VM_STATE">
7132	Virtual machine state neither Running nor Paused.
7133	</result>
7134	<result name="VBOX_E_PDM_ERROR">
7135	Virtual machine does not have a USB controller.
7136	</result>
7137	</desc>
7138	<param name="id" type="uuid" mod="string" dir="in">
7139	<desc>UUID of the host USB device to attach.</desc>
7140	</param>
7141	</method>
7142
7143	<method name="detachUSBDevice">
7144	<desc>
7145	Detaches an USB device with the given UUID from the USB controller
7146	of the virtual machine.
7147
7148	After this method succeeds, the VirtualBox server re-initiates
7149	all USB filters as if the device were just physically attached
7150	to the host, but filters of this machine are ignored to avoid
7151	a possible automatic re-attachment.
7152
7153	<see>IUSBController::deviceFilters, USBDeviceState</see>
7154
7155	<result name="VBOX_E_PDM_ERROR">
7156	Virtual machine does not have a USB controller.
7157	</result>
7158	<result name="E_INVALIDARG">
7159	USB device not attached to this virtual machine.
7160	</result>
7161	</desc>
7162	<param name="id" type="uuid" mod="string" dir="in">
7163	<desc>UUID of the USB device to detach.</desc>
7164	</param>
7165	<param name="device" type="IUSBDevice" dir="return">
7166	<desc>Detached USB device.</desc>
7167	</param>
7168	</method>
7169
7170	<method name="findUSBDeviceByAddress">
7171	<desc>
7172	Searches for a USB device with the given host address.
7173
7174	<result name="VBOX_E_OBJECT_NOT_FOUND">
7175	Given @c name does not correspond to any USB device.
7176	</result>
7177
7178	<see>IUSBDevice::address</see>
7179	</desc>
7180	<param name="name" type="wstring" dir="in">
7181	<desc>
7182	Address of the USB device (as assigned by the host) to
7183	search for.
7184	</desc>
7185	</param>
7186	<param name="device" type="IUSBDevice" dir="return">
7187	<desc>Found USB device object.</desc>
7188	</param>
7189	</method>
7190
7191	<method name="findUSBDeviceById">
7192	<desc>
7193	Searches for a USB device with the given UUID.
7194
7195	<result name="VBOX_E_OBJECT_NOT_FOUND">
7196	Given @c id does not correspond to any USB device.
7197	</result>
7198
7199	<see>IUSBDevice::id</see>
7200	</desc>
7201	<param name="id" type="uuid" mod="string" dir="in">
7202	<desc>UUID of the USB device to search for.</desc>
7203	</param>
7204	<param name="device" type="IUSBDevice" dir="return">
7205	<desc>Found USB device object.</desc>
7206	</param>
7207	</method>
7208
7209	<method name="createSharedFolder">
7210	<desc>
7211	Creates a transient new shared folder by associating the given logical
7212	name with the given host path, adds it to the collection of shared
7213	folders and starts sharing it. Refer to the description of
7214	<link to="ISharedFolder"/> to read more about logical names.
7215
7216	<result name="VBOX_E_INVALID_VM_STATE">
7217	Virtual machine in Saved state or currently changing state.
7218	</result>
7219	<result name="VBOX_E_FILE_ERROR">
7220	Shared folder already exists or not accessible.
7221	</result>
7222	</desc>
7223	<param name="name" type="wstring" dir="in">
7224	<desc>Unique logical name of the shared folder.</desc>
7225	</param>
7226	<param name="hostPath" type="wstring" dir="in">
7227	<desc>Full path to the shared folder in the host file system.</desc>
7228	</param>
7229	<param name="writable" type="boolean" dir="in">
7230	<desc>Whether the share is writable or readonly</desc>
7231	</param>
7232	</method>
7233
7234	<method name="removeSharedFolder">
7235	<desc>
7236	Removes a transient shared folder with the given name previously
7237	created by <link to="#createSharedFolder"/> from the collection of
7238	shared folders and stops sharing it.
7239	<result name="VBOX_E_INVALID_VM_STATE">
7240	Virtual machine in Saved state or currently changing state.
7241	</result>
7242	<result name="VBOX_E_FILE_ERROR">
7243	Shared folder does not exists.
7244	</result>
7245	</desc>
7246	<param name="name" type="wstring" dir="in">
7247	<desc>Logical name of the shared folder to remove.</desc>
7248	</param>
7249	</method>
7250
7251	<method name="takeSnapshot">
7252	<desc>
7253	Saves the current execution state
7254	and all settings of the machine and creates differencing images
7255	for all normal (non-independent) media.
7256	See <link to="ISnapshot" /> for an introduction to snapshots.
7257
7258	This method can be called for a PoweredOff, Saved (see
7259	<link to="#saveState"/>), Running or
7260	Paused virtual machine. When the machine is PoweredOff, an
7261	offline snapshot is created. When the machine is Running a live
7262	snapshot is created, and an online snapshot is is created when Paused.
7263
7264	The taken snapshot is always based on the
7265	<link to="IMachine::currentSnapshot">current snapshot</link>
7266	of the associated virtual machine and becomes a new current snapshot.
7267
7268	<note>
7269	This method implicitly calls <link to="IMachine::saveSettings"/> to
7270	save all current machine settings before taking an offline snapshot.
7271	</note>
7272
7273	<result name="VBOX_E_INVALID_VM_STATE">
7274	Virtual machine currently changing state.
7275	</result>
7276	</desc>
7277	<param name="name" type="wstring" dir="in">
7278	<desc>Short name for the snapshot.</desc>
7279	</param>
7280	<param name="description" type="wstring" dir="in">
7281	<desc>Optional description of the snapshot.</desc>
7282	</param>
7283	<param name="progress" type="IProgress" dir="return">
7284	<desc>Progress object to track the operation completion.</desc>
7285	</param>
7286	</method>
7287
7288	<method name="deleteSnapshot">
7289	<desc>
7290	Starts deleting the specified snapshot asynchronously.
7291	See <link to="ISnapshot" /> for an introduction to snapshots.
7292
7293	The execution state and settings of the associated machine stored in
7294	the snapshot will be deleted. The contents of all differencing media of
7295	this snapshot will be merged with the contents of their dependent child
7296	media to keep the medium chain valid (in other words, all changes
7297	represented by media being deleted will be propagated to their child
7298	medium). After that, this snapshot's differencing medium will be
7299	deleted. The parent of this snapshot will become a new parent for all
7300	its child snapshots.
7301
7302	If the deleted snapshot is the current one, its parent snapshot will
7303	become a new current snapshot. The current machine state is not directly
7304	affected in this case, except that currently attached differencing
7305	media based on media of the deleted snapshot will be also merged as
7306	described above.
7307
7308	If the deleted snapshot is the first or current snapshot, then the
7309	respective IMachine attributes will be adjusted. Deleting the current
7310	snapshot will also implicitly call <link to="IMachine::saveSettings"/>
7311	to make all current machine settings permanent.
7312
7313	Deleting a snapshot has the following preconditions:
7314
7315	<ul>
7316	<li>Child media of all normal media of the deleted snapshot
7317	must be accessible (see <link to="IMedium::state"/>) for this
7318	operation to succeed. In particular, this means that all virtual
7319	machines, whose media are directly or indirectly based on the
7320	media of deleted snapshot, must be powered off.</li>
7321
7322	<li>You cannot delete the snapshot if a medium attached to it has
7323	more than once child medium (differencing images) because otherwise
7324	merging would be impossible. This might be the case if there is
7325	more than one child snapshot or differencing images were created
7326	for other reason (e.g. implicitly because of multiple machine
7327	attachments).</li>
7328	</ul>
7329
7330
7331	The virtual machine's <link to="IMachine::state">state</link> is changed to "DeletingSnapshot"
7332	while this operation is in progress.
7333
7334	<note>
7335	Merging medium contents can be very time and disk space
7336	consuming, if these media are big in size and have many
7337	children. However, if the snapshot being deleted is the last
7338	(head) snapshot on the branch, the operation will be rather
7339	quick.
7340	</note>
7341	<result name="VBOX_E_INVALID_VM_STATE">
7342	Virtual machine is running.
7343	</result>
7344	</desc>
7345	<param name="id" type="uuid" mod="string" dir="in">
7346	<desc>UUID of the snapshot to delete.</desc>
7347	</param>
7348	<param name="progress" type="IProgress" dir="return">
7349	<desc>Progress object to track the operation completion.</desc>
7350	</param>
7351	</method>
7352
7353	<method name="restoreSnapshot">
7354	<desc>
7355	Starts resetting the machine's current state to the state contained
7356	in the given snapshot, asynchronously. All current settings of the
7357	machine will be reset and changes stored in differencing media
7358	will be lost.
7359	See <link to="ISnapshot" /> for an introduction to snapshots.
7360
7361	After this operation is successfully completed, new empty differencing
7362	media are created for all normal media of the machine.
7363
7364	If the given snapshot is an online snapshot, the machine will go to
7365	the <link to="MachineState_Saved"> saved state</link>, so that the
7366	next time it is powered on, the execution state will be restored
7367	from the state of the snapshot.
7368
7369	<note>
7370	The machine must not be running, otherwise the operation will fail.
7371	</note>
7372
7373	<note>
7374	If the machine state is <link to="MachineState_Saved">Saved</link>
7375	prior to this operation, the saved state file will be implicitly
7376	deleted (as if <link to="IConsole::forgetSavedState"/> were
7377	called).
7378	</note>
7379
7380	<result name="VBOX_E_INVALID_VM_STATE">
7381	Virtual machine is running.
7382	</result>
7383	</desc>
7384	<param name="snapshot" type="ISnapshot" dir="in">
7385	<desc>The snapshot to restore the VM state from.</desc>
7386	</param>
7387	<param name="progress" type="IProgress" dir="return">
7388	<desc>Progress object to track the operation completion.</desc>
7389	</param>
7390	</method>
7391
7392	<method name="teleport">
7393	<desc>
7394	Teleport the VM to a different host machine or process.
7395
7396	TODO explain the details.
7397
7398	<result name="VBOX_E_INVALID_VM_STATE">
7399	Virtual machine not running or paused.
7400	</result>
7401	</desc>
7402	<param name="hostname" type="wstring" dir="in">
7403	<desc>The name or IP of the host to teleport to.</desc>
7404	</param>
7405	<param name="tcpport" type="unsigned long" dir="in">
7406	<desc>The TCP port to connect to (1..65535).</desc>
7407	</param>
7408	<param name="password" type="wstring" dir="in">
7409	<desc>The password.</desc>
7410	</param>
7411	<param name="maxDowntime" type="unsigned long" dir="in">
7412	<desc>
7413	The maximum allowed downtime given as milliseconds. 0 is not a valid
7414	value. Recommended value: 250 ms.
7415
7416	The higher the value is, the greater the chance for a successful
7417	teleportation. A small value may easily result in the teleportation
7418	process taking hours and eventually fail.
7419
7420	<note>
7421	The current implementation treats this a guideline, not as an
7422	absolute rule.
7423	</note>
7424	</desc>
7425	</param>
7426	<param name="progress" type="IProgress" dir="return">
7427	<desc>Progress object to track the operation completion.</desc>
7428	</param>
7429	</method>
7430
7431	<method name="registerCallback">
7432	<desc>
7433	Registers a new console callback on this instance. The methods of the
7434	callback interface will be called by this instance when the appropriate
7435	event occurs.
7436	</desc>
7437	<param name="callback" type="IConsoleCallback" dir="in"/>
7438	</method>
7439
7440	<method name="unregisterCallback">
7441	<desc>
7442	Unregisters the console callback previously registered using
7443	<link to="#registerCallback"/>.
7444	<result name="E_INVALIDARG">
7445	Given @a callback handler is not registered.
7446	</result>
7447	</desc>
7448	<param name="callback" type="IConsoleCallback" dir="in"/>
7449	</method>
7450	</interface>
7451
7452	<!--
7453	// IHost
7454	/////////////////////////////////////////////////////////////////////////
7455	-->
7456
7457	<enum
7458	name="HostNetworkInterfaceMediumType"
7459	uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7460	>
7461	<desc>
7462	Type of encapsulation. Ethernet encapsulation includes both wired and
7463	wireless Ethernet connections.
7464	<see>IHostNetworkInterface</see>
7465	</desc>
7466
7467	<const name="Unknown" value="0">
7468	<desc>
7469	The type of interface cannot be determined.
7470	</desc>
7471	</const>
7472	<const name="Ethernet" value="1">
7473	<desc>
7474	Ethernet frame encapsulation.
7475	</desc>
7476	</const>
7477	<const name="PPP" value="2">
7478	<desc>
7479	Point-to-point protocol encapsulation.
7480	</desc>
7481	</const>
7482	<const name="SLIP" value="3">
7483	<desc>
7484	Serial line IP encapsulation.
7485	</desc>
7486	</const>
7487	</enum>
7488
7489	<enum
7490	name="HostNetworkInterfaceStatus"
7491	uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7492	>
7493	<desc>
7494	Current status of the interface.
7495	<see>IHostNetworkInterface</see>
7496	</desc>
7497
7498	<const name="Unknown" value="0">
7499	<desc>
7500	The state of interface cannot be determined.
7501	</desc>
7502	</const>
7503	<const name="Up" value="1">
7504	<desc>
7505	The interface is fully operational.
7506	</desc>
7507	</const>
7508	<const name="Down" value="2">
7509	<desc>
7510	The interface is not functioning.
7511	</desc>
7512	</const>
7513	</enum>
7514
7515	<enum
7516	name="HostNetworkInterfaceType"
7517	uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7518	>
7519	<desc>
7520	Network interface type.
7521	</desc>
7522	<const name="Bridged" value="1"/>
7523	<const name="HostOnly" value="2"/>
7524	</enum>
7525
7526	<interface
7527	name="IHostNetworkInterface" extends="$unknown"
7528	uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
7529	wsmap="managed"
7530	>
7531	<desc>
7532	Represents one of host's network interfaces. IP V6 address and network
7533	mask are strings of 32 hexdecimal digits grouped by four. Groups are
7534	separated by colons.
7535	For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7536	</desc>
7537	<attribute name="name" type="wstring" readonly="yes">
7538	<desc>Returns the host network interface name.</desc>
7539	</attribute>
7540
7541	<attribute name="id" type="uuid" mod="string" readonly="yes">
7542	<desc>Returns the interface UUID.</desc>
7543	</attribute>
7544
7545	<attribute name="networkName" type="wstring" readonly="yes">
7546	<desc>Returns the name of a virtual network the interface gets attached to.</desc>
7547	</attribute>
7548
7549	<attribute name="dhcpEnabled" type="boolean" readonly="yes">
7550	<desc>Specifies whether the DHCP is enabled for the interface.</desc>
7551	</attribute>
7552
7553	<attribute name="IPAddress" type="wstring" readonly="yes">
7554	<desc>Returns the IP V4 address of the interface.</desc>
7555	</attribute>
7556
7557	<attribute name="networkMask" type="wstring" readonly="yes">
7558	<desc>Returns the network mask of the interface.</desc>
7559	</attribute>
7560
7561	<attribute name="IPV6Supported" type="boolean" readonly="yes">
7562	<desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7563	</attribute>
7564
7565	<attribute name="IPV6Address" type="wstring" readonly="yes">
7566	<desc>Returns the IP V6 address of the interface.</desc>
7567	</attribute>
7568
7569	<attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7570	<desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7571	</attribute>
7572
7573	<attribute name="hardwareAddress" type="wstring" readonly="yes">
7574	<desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7575	</attribute>
7576
7577	<attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7578	<desc>Type of protocol encapsulation used.</desc>
7579	</attribute>
7580
7581	<attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7582	<desc>Status of the interface.</desc>
7583	</attribute>
7584
7585	<attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7586	<desc>specifies the host interface type.</desc>
7587	</attribute>
7588
7589	<method name="enableStaticIpConfig">
7590	<desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7591	<param name="IPAddress" type="wstring" dir="in">
7592	<desc>
7593	IP address.
7594	</desc>
7595	</param>
7596	<param name="networkMask" type="wstring" dir="in">
7597	<desc>
7598	network mask.
7599	</desc>
7600	</param>
7601	</method>
7602
7603	<method name="enableStaticIpConfigV6">
7604	<desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7605	<param name="IPV6Address" type="wstring" dir="in">
7606	<desc>
7607	IP address.
7608	</desc>
7609	</param>
7610	<param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7611	<desc>
7612	network mask.
7613	</desc>
7614	</param>
7615	</method>
7616
7617	<method name="enableDynamicIpConfig">
7618	<desc>enables the dynamic IP configuration.</desc>
7619	</method>
7620
7621	<method name="dhcpRediscover">
7622	<desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
7623	</method>
7624
7625	</interface>
7626
7627	<interface
7628	name="IHost" extends="$unknown"
7629	uuid="e380cbfc-ae65-4fa6-899e-45ded6b3132a"
7630	wsmap="managed"
7631	>
7632	<desc>
7633	The IHost interface represents the physical machine that this VirtualBox
7634	installation runs on.
7635
7636	An object implementing this interface is returned by the
7637	<link to="IVirtualBox::host" /> attribute. This interface contains
7638	read-only information about the host's physical hardware (such as what
7639	processors and disks are available, what the host operating system is,
7640	and so on) and also allows for manipulating some of the host's hardware,
7641	such as global USB device filters and host interface networking.
7642
7643	</desc>
7644	<attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
7645	<desc>List of DVD drives available on the host.</desc>
7646	</attribute>
7647
7648	<attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
7649	<desc>List of floppy drives available on the host.</desc>
7650	</attribute>
7651
7652	<attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7653	<desc>
7654	List of USB devices currently attached to the host.
7655	Once a new device is physically attached to the host computer,
7656	it appears in this list and remains there until detached.
7657
7658	<note>
7659	If USB functionality is not available in the given edition of
7660	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7661	</note>
7662	</desc>
7663	</attribute>
7664
7665	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
7666	<desc>
7667	List of USB device filters in action.
7668	When a new device is physically attached to the host computer,
7669	filters from this list are applied to it (in order they are stored
7670	in the list). The first matched filter will determine the
7671	<link to="IHostUSBDeviceFilter::action">action</link>
7672	performed on the device.
7673
7674	Unless the device is ignored by these filters, filters of all
7675	currently running virtual machines
7676	(<link to="IUSBController::deviceFilters"/>) are applied to it.
7677
7678	<note>
7679	If USB functionality is not available in the given edition of
7680	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7681	</note>
7682
7683	<see>IHostUSBDeviceFilter, USBDeviceState</see>
7684	</desc>
7685	</attribute>
7686
7687	<attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
7688	<desc>List of host network interfaces currently defined on the host.</desc>
7689	</attribute>
7690
7691	<attribute name="processorCount" type="unsigned long" readonly="yes">
7692	<desc>Number of (logical) CPUs installed in the host system.</desc>
7693	</attribute>
7694
7695	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
7696	<desc>Number of (logical) CPUs online in the host system.</desc>
7697	</attribute>
7698
7699	<method name="getProcessorSpeed">
7700	<desc>Query the (approximate) maximum speed of a specified host CPU in
7701	Megahertz.
7702	</desc>
7703	<param name="cpuId" type="unsigned long" dir="in">
7704	<desc>
7705	Identifier of the CPU.
7706	</desc>
7707	</param>
7708	<param name="speed" type="unsigned long" dir="return">
7709	<desc>
7710	Speed value. 0 is returned if value is not known or @a cpuId is
7711	invalid.
7712	</desc>
7713	</param>
7714	</method>
7715
7716	<method name="getProcessorFeature">
7717	<desc>Query whether a CPU feature is supported or not.</desc>
7718	<param name="feature" type="ProcessorFeature" dir="in">
7719	<desc>
7720	CPU Feature identifier.
7721	</desc>
7722	</param>
7723	<param name="supported" type="boolean" dir="return">
7724	<desc>
7725	Feature is supported or not.
7726	</desc>
7727	</param>
7728	</method>
7729
7730	<method name="getProcessorDescription">
7731	<desc>Query the model string of a specified host CPU.
7732	</desc>
7733	<param name="cpuId" type="unsigned long" dir="in">
7734	<desc>
7735	Identifier of the CPU.
7736	<note>
7737	The current implementation might not necessarily return the
7738	description for this exact CPU.
7739	</note>
7740	</desc>
7741	</param>
7742	<param name="description" type="wstring" dir="return">
7743	<desc>
7744	Model string. An empty string is returned if value is not known or
7745	@a cpuId is invalid.
7746	</desc>
7747	</param>
7748	</method>
7749
7750	<method name="getProcessorCPUIDLeaf">
7751	<desc>
7752	Returns the CPU cpuid information for the specified leaf.
7753	</desc>
7754	<param name="cpuId" type="unsigned long" dir="in">
7755	<desc>
7756	Identifier of the CPU. The CPU most be online.
7757	<note>
7758	The current implementation might not necessarily return the
7759	description for this exact CPU.
7760	</note>
7761	</desc>
7762	</param>
7763	<param name="leaf" type="unsigned long" dir="in">
7764	<desc>
7765	CPUID leaf index (eax).
7766	</desc>
7767	</param>
7768	<param name="subLeaf" type="unsigned long" dir="in">
7769	<desc>
7770	CPUID leaf sub index (ecx). This currently only applies to cache
7771	information on Intel CPUs. Use 0 if retriving values for
7772	<link to="IMachine::setCPUIDLeaf"/>.
7773	</desc>
7774	</param>
7775	<param name="valEax" type="unsigned long" dir="out">
7776	<desc>
7777	CPUID leaf value for register eax.
7778	</desc>
7779	</param>
7780	<param name="valEbx" type="unsigned long" dir="out">
7781	<desc>
7782	CPUID leaf value for register ebx.
7783	</desc>
7784	</param>
7785	<param name="valEcx" type="unsigned long" dir="out">
7786	<desc>
7787	CPUID leaf value for register ecx.
7788	</desc>
7789	</param>
7790	<param name="valEdx" type="unsigned long" dir="out">
7791	<desc>
7792	CPUID leaf value for register edx.
7793	</desc>
7794	</param>
7795	</method>
7796
7797	<attribute name="memorySize" type="unsigned long" readonly="yes">
7798	<desc>Amount of system memory in megabytes installed in the host system.</desc>
7799	</attribute>
7800
7801	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7802	<desc>Available system memory in the host system.</desc>
7803	</attribute>
7804
7805	<attribute name="operatingSystem" type="wstring" readonly="yes">
7806	<desc>Name of the host system's operating system.</desc>
7807	</attribute>
7808
7809	<attribute name="OSVersion" type="wstring" readonly="yes">
7810	<desc>Host operating system's version string.</desc>
7811	</attribute>
7812
7813	<attribute name="UTCTime" type="long long" readonly="yes">
7814	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7815	</attribute>
7816
7817	<attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
7818	<desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
7819	</attribute>
7820
7821	<method name="createHostOnlyNetworkInterface">
7822	<desc>
7823	Creates a new adapter for Host Only Networking.
7824	<result name="E_INVALIDARG">
7825	Host network interface @a name already exists.
7826	</result>
7827	</desc>
7828	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
7829	<desc>
7830	Created host interface object.
7831	</desc>
7832	</param>
7833	<param name="progress" type="IProgress" dir="return">
7834	<desc>
7835	Progress object to track the operation completion.
7836	</desc>
7837	</param>
7838	</method>
7839
7840	<method name="removeHostOnlyNetworkInterface">
7841	<desc>
7842	Removes the given Host Only Networking interface.
7843	<result name="VBOX_E_OBJECT_NOT_FOUND">
7844	No host network interface matching @a id found.
7845	</result>
7846	</desc>
7847	<param name="id" type="uuid" mod="string" dir="in">
7848	<desc>
7849	Adapter GUID.
7850	</desc>
7851	</param>
7852	<param name="progress" type="IProgress" dir="return">
7853	<desc>
7854	Progress object to track the operation completion.
7855	</desc>
7856	</param>
7857	</method>
7858
7859	<method name="createUSBDeviceFilter">
7860	<desc>
7861	Creates a new USB device filter. All attributes except
7862	the filter name are set to empty (any match),
7863	<i>active</i> is @c false (the filter is not active).
7864
7865	The created filter can be added to the list of filters using
7866	<link to="#insertUSBDeviceFilter"/>.
7867
7868	<see>#USBDeviceFilters</see>
7869	</desc>
7870	<param name="name" type="wstring" dir="in">
7871	<desc>
7872	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7873	for more info.
7874	</desc>
7875	</param>
7876	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
7877	<desc>Created filter object.</desc>
7878	</param>
7879	</method>
7880
7881	<method name="insertUSBDeviceFilter">
7882	<desc>
7883	Inserts the given USB device to the specified position
7884	in the list of filters.
7885
7886	Positions are numbered starting from @c 0. If the specified
7887	position is equal to or greater than the number of elements in
7888	the list, the filter is added at the end of the collection.
7889
7890	<note>
7891	Duplicates are not allowed, so an attempt to insert a
7892	filter already in the list is an error.
7893	</note>
7894	<note>
7895	If USB functionality is not available in the given edition of
7896	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7897	</note>
7898
7899	<see>#USBDeviceFilters</see>
7900
7901	<result name="VBOX_E_INVALID_OBJECT_STATE">
7902	USB device filter is not created within this VirtualBox instance.
7903	</result>
7904	<result name="E_INVALIDARG">
7905	USB device filter already in list.
7906	</result>
7907
7908	</desc>
7909	<param name="position" type="unsigned long" dir="in">
7910	<desc>Position to insert the filter to.</desc>
7911	</param>
7912	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
7913	<desc>USB device filter to insert.</desc>
7914	</param>
7915	</method>
7916
7917	<method name="removeUSBDeviceFilter">
7918	<desc>
7919	Removes a USB device filter from the specified position in the
7920	list of filters.
7921
7922	Positions are numbered starting from @c 0. Specifying a
7923	position equal to or greater than the number of elements in
7924	the list will produce an error.
7925
7926	<note>
7927	If USB functionality is not available in the given edition of
7928	VirtualBox, this method will set the result code to @c E_NOTIMPL.
7929	</note>
7930
7931	<see>#USBDeviceFilters</see>
7932
7933	<result name="E_INVALIDARG">
7934	USB device filter list empty or invalid @a position.
7935	</result>
7936
7937	</desc>
7938	<param name="position" type="unsigned long" dir="in">
7939	<desc>Position to remove the filter from.</desc>
7940	</param>
7941	</method>
7942
7943	<method name="findHostDVDDrive">
7944	<desc>
7945	Searches for a host DVD drive with the given @c name.
7946
7947	<result name="VBOX_E_OBJECT_NOT_FOUND">
7948	Given @c name does not correspond to any host drive.
7949	</result>
7950
7951	</desc>
7952	<param name="name" type="wstring" dir="in">
7953	<desc>Name of the host drive to search for</desc>
7954	</param>
7955	<param name="drive" type="IMedium" dir="return">
7956	<desc>Found host drive object</desc>
7957	</param>
7958	</method>
7959
7960	<method name="findHostFloppyDrive">
7961	<desc>
7962	Searches for a host floppy drive with the given @c name.
7963
7964	<result name="VBOX_E_OBJECT_NOT_FOUND">
7965	Given @c name does not correspond to any host floppy drive.
7966	</result>
7967
7968	</desc>
7969	<param name="name" type="wstring" dir="in">
7970	<desc>Name of the host floppy drive to search for</desc>
7971	</param>
7972	<param name="drive" type="IMedium" dir="return">
7973	<desc>Found host floppy drive object</desc>
7974	</param>
7975	</method>
7976
7977	<method name="findHostNetworkInterfaceByName">
7978	<desc>
7979	Searches through all host network interfaces for an interface with
7980	the given @c name.
7981	<note>
7982	The method returns an error if the given @c name does not
7983	correspond to any host network interface.
7984	</note>
7985	</desc>
7986	<param name="name" type="wstring" dir="in">
7987	<desc>Name of the host network interface to search for.</desc>
7988	</param>
7989	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
7990	<desc>Found host network interface object.</desc>
7991	</param>
7992	</method>
7993	<method name="findHostNetworkInterfaceById">
7994	<desc>
7995	Searches through all host network interfaces for an interface with
7996	the given GUID.
7997	<note>
7998	The method returns an error if the given GUID does not
7999	correspond to any host network interface.
8000	</note>
8001	</desc>
8002	<param name="id" type="uuid" mod="string" dir="in">
8003	<desc>GUID of the host network interface to search for.</desc>
8004	</param>
8005	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
8006	<desc>Found host network interface object.</desc>
8007	</param>
8008	</method>
8009	<method name="findHostNetworkInterfacesOfType">
8010	<desc>
8011	Searches through all host network interfaces and returns a list of interfaces of the specified type
8012	</desc>
8013	<param name="type" type="HostNetworkInterfaceType" dir="in">
8014	<desc>type of the host network interfaces to search for.</desc>
8015	</param>
8016	<param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
8017	<desc>Found host network interface objects.</desc>
8018	</param>
8019	</method>
8020
8021	<method name="findUSBDeviceById">
8022	<desc>
8023	Searches for a USB device with the given UUID.
8024
8025	<result name="VBOX_E_OBJECT_NOT_FOUND">
8026	Given @c id does not correspond to any USB device.
8027	</result>
8028
8029	<see>IHostUSBDevice::id</see>
8030	</desc>
8031	<param name="id" type="uuid" mod="string" dir="in">
8032	<desc>UUID of the USB device to search for.</desc>
8033	</param>
8034	<param name="device" type="IHostUSBDevice" dir="return">
8035	<desc>Found USB device object.</desc>
8036	</param>
8037	</method>
8038
8039	<method name="findUSBDeviceByAddress">
8040	<desc>
8041	Searches for a USB device with the given host address.
8042
8043	<result name="VBOX_E_OBJECT_NOT_FOUND">
8044	Given @c name does not correspond to any USB device.
8045	</result>
8046
8047	<see>IHostUSBDevice::address</see>
8048	</desc>
8049	<param name="name" type="wstring" dir="in">
8050	<desc>
8051	Address of the USB device (as assigned by the host) to
8052	search for.
8053	</desc>
8054	</param>
8055	<param name="device" type="IHostUSBDevice" dir="return">
8056	<desc>Found USB device object.</desc>
8057	</param>
8058	</method>
8059
8060	</interface>
8061
8062	<!--
8063	// ISystemProperties
8064	/////////////////////////////////////////////////////////////////////////
8065	-->
8066
8067	<interface
8068	name="ISystemProperties"
8069	extends="$unknown"
8070	uuid="07c3ffd8-8f59-49cc-b608-53a332e85cc3"
8071	wsmap="managed"
8072	>
8073	<desc>
8074	The ISystemProperties interface represents global properties of the given
8075	VirtualBox installation.
8076
8077	These properties define limits and default values for various attributes
8078	and parameters. Most of the properties are read-only, but some can be
8079	changed by a user.
8080	</desc>
8081
8082	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
8083	<desc>Minimum guest system memory in Megabytes.</desc>
8084	</attribute>
8085
8086	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
8087	<desc>Maximum guest system memory in Megabytes.</desc>
8088	</attribute>
8089
8090	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
8091	<desc>Minimum guest video memory in Megabytes.</desc>
8092	</attribute>
8093
8094	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
8095	<desc>Maximum guest video memory in Megabytes.</desc>
8096	</attribute>
8097
8098	<attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
8099	<desc>Minimum CPU count.</desc>
8100	</attribute>
8101
8102	<attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
8103	<desc>Maximum CPU count.</desc>
8104	</attribute>
8105
8106	<attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
8107	<desc>Maximum of monitors which could be connected.</desc>
8108	</attribute>
8109
8110	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
8111	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
8112	</attribute>
8113
8114	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
8115	<desc>
8116	Number of network adapters associated with every
8117	<link to="IMachine"/> instance.
8118	</desc>
8119	</attribute>
8120
8121	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
8122	<desc>
8123	Number of serial ports associated with every
8124	<link to="IMachine"/> instance.
8125	</desc>
8126	</attribute>
8127
8128	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
8129	<desc>
8130	Number of parallel ports associated with every
8131	<link to="IMachine"/> instance.
8132	</desc>
8133	</attribute>
8134
8135	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
8136	<desc>
8137	Maximum device position in the boot order. This value corresponds
8138	to the total number of devices a machine can boot from, to make it
8139	possible to include all possible devices to the boot list.
8140	<see><link to="IMachine::setBootOrder"/></see>
8141	</desc>
8142	</attribute>
8143
8144	<attribute name="defaultMachineFolder" type="wstring">
8145	<desc>
8146	Full path to the default directory used to create new or open
8147	existing machines when a settings file name contains no
8148	path.
8149
8150	The initial value of this property is
8151	<tt><</tt><link to="IVirtualBox::homeFolder">
8152	VirtualBox_home</link><tt>>/Machines</tt>.
8153
8154	<note>
8155	Setting this property to @c null or an empty string will restore the
8156	initial value.
8157	</note>
8158	<note>
8159	When settings this property, the specified path can be
8160	absolute (full path) or relative
8161	to the <link to="IVirtualBox::homeFolder">
8162	VirtualBox home directory</link>.
8163	When reading this property, a full path is
8164	always returned.
8165	</note>
8166	<note>
8167	The specified path may not exist, it will be created
8168	when necessary.
8169	</note>
8170
8171	<see>
8172	<link to="IVirtualBox::createMachine"/>,
8173	<link to="IVirtualBox::openMachine"/>
8174	</see>
8175	</desc>
8176	</attribute>
8177
8178	<attribute name="defaultHardDiskFolder" type="wstring">
8179	<desc>
8180	Full path to the default directory used to create new or open existing
8181	virtual disks.
8182
8183	This path is used when the storage unit of a hard disk is a regular file
8184	in the host's file system and only a file name that contains no path is
8185	given.
8186
8187	The initial value of this property is
8188	<tt><</tt>
8189	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
8190	<tt>>/HardDisks</tt>.
8191
8192	<note>
8193	Setting this property to @c null or empty string will restore the
8194	initial value.
8195	</note>
8196	<note>
8197	When settings this property, the specified path can be relative
8198	to the
8199	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
8200	absolute. When reading this property, a full path is
8201	always returned.
8202	</note>
8203	<note>
8204	The specified path may not exist, it will be created
8205	when necessary.
8206	</note>
8207
8208	<see>
8209	IMedium,
8210	<link to="IVirtualBox::createHardDisk"/>,
8211	<link to="IVirtualBox::openHardDisk"/>,
8212	<link to="IMedium::location"/>
8213	</see>
8214	</desc>
8215	</attribute>
8216
8217	<attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
8218	<desc>
8219	List of all medium storage formats supported by this VirtualBox
8220	installation.
8221
8222	Keep in mind that the medium format identifier
8223	(<link to="IMediumFormat::id"/>) used in other API calls like
8224	<link to="IVirtualBox::createHardDisk"/> to refer to a particular
8225	medium format is a case-insensitive string. This means that, for
8226	example, all of the following strings:
8227	<pre>
8228	"VDI"
8229	"vdi"
8230	"VdI"</pre>
8231	refer to the same medium format.
8232
8233	Note that the virtual medium framework is backend-based, therefore
8234	the list of supported formats depends on what backends are currently
8235	installed.
8236
8237	<see>
8238	<link to="IMediumFormat"/>,
8239	</see>
8240	</desc>
8241	</attribute>
8242
8243	<attribute name="defaultHardDiskFormat" type="wstring">
8244	<desc>
8245	Identifier of the default medium format used by VirtualBox.
8246
8247	The medium format set by this attribute is used by VirtualBox
8248	when the medium format was not specified explicitly. One example is
8249	<link to="IVirtualBox::createHardDisk"/> with the empty
8250	format argument. A more complex example is implicit creation of
8251	differencing media when taking a snapshot of a virtual machine:
8252	this operation will try to use a format of the parent medium first
8253	and if this format does not support differencing media the default
8254	format specified by this argument will be used.
8255
8256	The list of supported medium formats may be obtained by the
8257	<link to="#mediaFormats"/> call. Note that the default medium
8258	format must have a capability to create differencing media;
8259	otherwise operations that create media implicitly may fail
8260	unexpectedly.
8261
8262	The initial value of this property is <tt>"VDI"</tt> in the current
8263	version of the VirtualBox product, but may change in the future.
8264
8265	<note>
8266	Setting this property to @c null or empty string will restore the
8267	initial value.
8268	</note>
8269
8270	<see>
8271	<link to="#mediaFormats"/>,
8272	<link to="IMediumFormat::id"/>,
8273	<link to="IVirtualBox::createHardDisk"/>
8274	</see>
8275	</desc>
8276	</attribute>
8277
8278	<attribute name="freeDiskSpaceWarning" type="unsigned long long">
8279	<desc>Issue a warning if the free disk space is below (or in some disk
8280	intensive operation is expected to go below) the given size in
8281	Megabytes.</desc>
8282	</attribute>
8283
8284	<attribute name="freeDiskSpacePercentWarning" type="unsigned long">
8285	<desc>Issue a warning if the free disk space is below (or in some disk
8286	intensive operation is expected to go below) the given percentage.</desc>
8287	</attribute>
8288
8289	<attribute name="freeDiskSpaceError" type="unsigned long long">
8290	<desc>Issue an error if the free disk space is below (or in some disk
8291	intensive operation is expected to go below) the given size in
8292	Megabytes.</desc>
8293	</attribute>
8294
8295	<attribute name="freeDiskSpacePercentError" type="unsigned long">
8296	<desc>Issue an error if the free disk space is below (or in some disk
8297	intensive operation is expected to go below) the given percentage.</desc>
8298	</attribute>
8299
8300	<attribute name="remoteDisplayAuthLibrary" type="wstring">
8301	<desc>
8302	Library that provides authentication for VRDP clients. The library
8303	is used if a virtual machine's authentication type is set to "external"
8304	in the VM RemoteDisplay configuration.
8305
8306	The system library extension (".DLL" or ".so") must be omitted.
8307	A full path can be specified; if not, then the library must reside on the
8308	system's default library path.
8309
8310	The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
8311	of that name in one of the default VirtualBox library directories.
8312
8313	For details about VirtualBox authentication libraries and how to implement
8314	them, please refer to the VirtualBox manual.
8315
8316	<note>
8317	Setting this property to @c null or empty string will restore the
8318	initial value.
8319	</note>
8320	</desc>
8321	</attribute>
8322
8323	<attribute name="webServiceAuthLibrary" type="wstring">
8324	<desc>
8325	Library that provides authentication for webservice clients. The library
8326	is used if a virtual machine's authentication type is set to "external"
8327	in the VM RemoteDisplay configuration and will be called from
8328	within the <link to="IWebsessionManager::logon" /> implementation.
8329
8330	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
8331	there is no per-VM setting for this, as the webservice is a global
8332	resource (if it is running). Only for this setting (for the webservice),
8333	setting this value to a literal <tt>"null"</tt> string disables authentication,
8334	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
8335	no matter what user name and password are supplied.
8336
8337	The initial value of this property is <tt>"VRDPAuth"</tt>,
8338	meaning that the webservice will use the same authentication
8339	library that is used by default for VBoxVRDP (again, see
8340	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
8341	The format and calling convention of authentication libraries
8342	is the same for the webservice as it is for VBoxVRDP.
8343
8344	<note>
8345	Setting this property to @c null or empty string will restore the
8346	initial value.
8347	</note>
8348	</desc>
8349	</attribute>
8350
8351	<attribute name="LogHistoryCount" type="unsigned long">
8352	<desc>
8353	This value specifies how many old release log files are kept.
8354	</desc>
8355	</attribute>
8356
8357	<attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
8358	<desc>This value hold the default audio driver for the current
8359	system.</desc>
8360	</attribute>
8361
8362	<method name="getMaxDevicesPerPortForStorageBus">
8363	<desc>Returns the maximum number of devices which can be attached to a port
8364	for the given storage bus.</desc>
8365
8366	<param name="bus" type="StorageBus" dir="in">
8367	<desc>The storage bus type to get the value for.</desc>
8368	</param>
8369
8370	<param name="maxDevicesPerPort" type="unsigned long" dir="return">
8371	<desc>The maximum number of devices which can eb attached to the port for the given
8372	storage bus.</desc>
8373	</param>
8374	</method>
8375
8376	<method name="getMinPortCountForStorageBus">
8377	<desc>Returns the minimum number of ports the given storage bus supports.</desc>
8378
8379	<param name="bus" type="StorageBus" dir="in">
8380	<desc>The storage bus type to get the value for.</desc>
8381	</param>
8382
8383	<param name="minPortCount" type="unsigned long" dir="return">
8384	<desc>The minimum number of ports for the given storage bus.</desc>
8385	</param>
8386	</method>
8387
8388	<method name="getMaxPortCountForStorageBus">
8389	<desc>Returns the maximum number of ports the given storage bus supports.</desc>
8390
8391	<param name="bus" type="StorageBus" dir="in">
8392	<desc>The storage bus type to get the value for.</desc>
8393	</param>
8394
8395	<param name="maxPortCount" type="unsigned long" dir="return">
8396	<desc>The maximum number of ports for the given storage bus.</desc>
8397	</param>
8398	</method>
8399
8400	<method name="getMaxInstancesOfStorageBus">
8401	<desc>Returns the maximum number of storage bus instances which
8402	can be configured for each VM. This corresponds to the number of
8403	storage controllers one can have.</desc>
8404
8405	<param name="bus" type="StorageBus" dir="in">
8406	<desc>The storage bus type to get the value for.</desc>
8407	</param>
8408
8409	<param name="maxInstances" type="unsigned long" dir="return">
8410	<desc>The maximum number of instances for the given storage bus.</desc>
8411	</param>
8412	</method>
8413
8414	<method name="getDeviceTypesForStorageBus">
8415	<desc>Returns list of all the supported device types
8416	(<link to="DeviceType"/>) for the given type of storage
8417	bus.</desc>
8418
8419	<param name="bus" type="StorageBus" dir="in">
8420	<desc>The storage bus type to get the value for.</desc>
8421	</param>
8422
8423	<param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8424	<desc>The list of all supported device types for the given storage bus.</desc>
8425	</param>
8426	</method>
8427	</interface>
8428
8429	<!--
8430	// IGuest
8431	/////////////////////////////////////////////////////////////////////////
8432	-->
8433
8434	<interface
8435	name="IGuestOSType" extends="$unknown"
8436	uuid="8aa950f6-668c-4388-b251-3809b404e862"
8437	wsmap="struct"
8438	>
8439	<desc>
8440	</desc>
8441
8442	<attribute name="familyId" type="wstring" readonly="yes">
8443	<desc>Guest OS family identifier string.</desc>
8444	</attribute>
8445
8446	<attribute name="familyDescription" type="wstring" readonly="yes">
8447	<desc>Human readable description of the guest OS family.</desc>
8448	</attribute>
8449
8450	<attribute name="id" type="wstring" readonly="yes">
8451	<desc>Guest OS identifier string.</desc>
8452	</attribute>
8453
8454	<attribute name="description" type="wstring" readonly="yes">
8455	<desc>Human readable description of the guest OS.</desc>
8456	</attribute>
8457
8458	<attribute name="is64Bit" type="boolean" readonly="yes">
8459	<desc>Returns @c true if the given OS is 64-bit</desc>
8460	</attribute>
8461
8462	<attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8463	<desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8464	</attribute>
8465
8466	<attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8467	<desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8468	</attribute>
8469
8470	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8471	<desc>Recommended RAM size in Megabytes.</desc>
8472	</attribute>
8473
8474	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8475	<desc>Recommended video RAM size in Megabytes.</desc>
8476	</attribute>
8477
8478	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
8479	<desc>Recommended hard disk size in Megabytes.</desc>
8480	</attribute>
8481
8482	<attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8483	<desc>Returns recommended network adapter for this OS type.</desc>
8484	</attribute>
8485
8486	<attribute name="recommendedPae" type="boolean" readonly="yes">
8487	<desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8488	</attribute>
8489
8490	<attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
8491	<desc>Recommended storage controller type for DVD/CD drives.</desc>
8492	</attribute>
8493
8494	<attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
8495	<desc>Recommended storage bus type for DVD/CD drives.</desc>
8496	</attribute>
8497
8498	<attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
8499	<desc>Recommended storage controller type for HD drives.</desc>
8500	</attribute>
8501
8502	<attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
8503	<desc>Recommended storage bus type for HD drives.</desc>
8504	</attribute>
8505
8506	<attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8507	<desc>Recommended firmware type.</desc>
8508	</attribute>
8509
8510	<attribute name="recommendedUsbHid" type="boolean" readonly="yes">
8511	<desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8512	</attribute>
8513
8514	<attribute name="recommendedHpet" type="boolean" readonly="yes">
8515	<desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8516	</attribute>
8517
8518	<attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
8519	<desc>Returns @c true if using a USB Tablet is recommended.</desc>
8520	</attribute>
8521
8522	<attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
8523	<desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8524	</attribute>
8525
8526	</interface>
8527
8528	<interface
8529	name="IGuest" extends="$unknown"
8530	uuid="d073545f-9635-489e-b36f-d468a10f8987"
8531	wsmap="managed"
8532	>
8533	<desc>
8534	The IGuest interface represents information about the operating system
8535	running inside the virtual machine. Used in
8536	<link to="IConsole::guest"/>.
8537
8538	IGuest provides information about the guest operating system, whether
8539	Guest Additions are installed and other OS-specific virtual machine
8540	properties.
8541	</desc>
8542
8543	<attribute name="OSTypeId" type="wstring" readonly="yes">
8544	<desc>
8545	Identifier of the Guest OS type as reported by the Guest
8546	Additions.
8547	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
8548	an IGuestOSType object representing details about the given
8549	Guest OS type.
8550	<note>
8551	If Guest Additions are not installed, this value will be
8552	the same as <link to="IMachine::OSTypeId"/>.
8553	</note>
8554	</desc>
8555	</attribute>
8556
8557	<attribute name="additionsActive" type="boolean" readonly="yes">
8558	<desc>
8559	Flag whether the Guest Additions are installed and active
8560	in which case their version will be returned by the
8561	<link to="#additionsVersion"/> property.
8562	</desc>
8563	</attribute>
8564
8565	<attribute name="additionsVersion" type="wstring" readonly="yes">
8566	<desc>
8567	Version of the Guest Additions (3 decimal numbers separated
8568	by dots) or empty when the Additions are not installed. The
8569	Additions may also report a version but yet not be active as
8570	the version might be refused by VirtualBox (incompatible) or
8571	other failures occurred.
8572	</desc>
8573	</attribute>
8574
8575	<attribute name="supportsSeamless" type="boolean" readonly="yes">
8576	<desc>
8577	Flag whether seamless guest display rendering (seamless desktop
8578	integration) is supported.
8579	</desc>
8580	</attribute>
8581
8582	<attribute name="supportsGraphics" type="boolean" readonly="yes">
8583	<desc>
8584	Flag whether the guest is in graphics mode. If it is not, then
8585	seamless rendering will not work, resize hints are not immediately
8586	acted on and guest display resizes are probably not initiated by
8587	the guest additions.
8588	</desc>
8589	</attribute>
8590
8591	<attribute name="memoryBalloonSize" type="unsigned long">
8592	<desc>Guest system memory balloon size in megabytes (transient property).</desc>
8593	</attribute>
8594
8595	<attribute name="statisticsUpdateInterval" type="unsigned long">
8596	<desc>Interval to update guest statistics in seconds.</desc>
8597	</attribute>
8598
8599	<method name="internalGetStatistics">
8600	<desc>
8601	Internal method; do not use as it might change at any time
8602	</desc>
8603	<param name="cpuUser" type="unsigned long" dir="out">
8604	<desc>Percentage of processor time spent in user mode as seen by the guest</desc>
8605	</param>
8606	<param name="cpuKernel" type="unsigned long" dir="out">
8607	<desc>Percentage of processor time spent in kernel mode as seen by the guest</desc>
8608	</param>
8609	<param name="cpuIdle" type="unsigned long" dir="out">
8610	<desc>Percentage of processor time spent idling as seen by the guest</desc>
8611	</param>
8612	<param name="memTotal" type="unsigned long" dir="out">
8613	<desc>Total amount of physical guest RAM</desc>
8614	</param>
8615	<param name="memFree" type="unsigned long" dir="out">
8616	<desc>Free amount of physical guest RAM</desc>
8617	</param>
8618	<param name="memBalloon" type="unsigned long" dir="out">
8619	<desc>Amount of ballooned physical guest RAM</desc>
8620	</param>
8621	<param name="memCache" type="unsigned long" dir="out">
8622	<desc>Total amount of guest (disk) cache memory</desc>
8623	</param>
8624	<param name="pagedTotal" type="unsigned long" dir="out">
8625	<desc>Total amount of space in the page file</desc>
8626	</param>
8627	<param name="memAllocTotal" type="unsigned long" dir="out">
8628	<desc>Total amount of memory allocated by the hypervisor</desc>
8629	</param>
8630	<param name="memFreeTotal" type="unsigned long" dir="out">
8631	<desc>Total amount of free memory available in the hypervisor</desc>
8632	</param>
8633	<param name="memBalloonTotal" type="unsigned long" dir="out">
8634	<desc>Total amount of memory ballooned by the hypervisor</desc>
8635	</param>
8636	</method>
8637
8638	<method name="setCredentials">
8639	<desc>
8640	Store login credentials that can be queried by guest operating
8641	systems with Additions installed. The credentials are transient
8642	to the session and the guest may also choose to erase them. Note
8643	that the caller cannot determine whether the guest operating system
8644	has queried or made use of the credentials.
8645
8646	<result name="VBOX_E_VM_ERROR">
8647	VMM device is not available.
8648	</result>
8649
8650	</desc>
8651	<param name="userName" type="wstring" dir="in">
8652	<desc>User name string, can be empty</desc>
8653	</param>
8654	<param name="password" type="wstring" dir="in">
8655	<desc>Password string, can be empty</desc>
8656	</param>
8657	<param name="domain" type="wstring" dir="in">
8658	<desc>Domain name (guest logon scheme specific), can be empty</desc>
8659	</param>
8660	<param name="allowInteractiveLogon" type="boolean" dir="in">
8661	<desc>
8662	Flag whether the guest should alternatively allow the user to
8663	interactively specify different credentials. This flag might
8664	not be supported by all versions of the Additions.
8665	</desc>
8666	</param>
8667	</method>
8668
8669	<method name="executeProcess">
8670	<desc>
8671	Executes an existing program inside the guest VM.
8672
8673	<result name="VBOX_E_IPRT_ERROR">
8674	Could not execute process.
8675	</result>
8676
8677	</desc>
8678	<param name="execName" type="wstring" dir="in">
8679	<desc>
8680	Full path name of the command to execute on the guest; the
8681	commands has to exists in the guest VM in order to be executed.
8682	</desc>
8683	</param>
8684	<param name="flags" type="unsigned long" dir="in">
8685	<desc>
8686	Execution flags - currently not supported and therefore
8687	has to be set to 0.
8688	</desc>
8689	</param>
8690	<param name="arguments" type="wstring" safearray="yes" dir="in">
8691	<desc>
8692	Array of arguments passed to the execution command.
8693	</desc>
8694	</param>
8695	<param name="environment" type="wstring" safearray="yes" dir="in">
8696	<desc>
8697	Environment variables that can be set while the command is being
8698	executed, in form of "NAME=VALUE"; one pair per entry. To unset a
8699	variable just set its name ("NAME") without a value.
8700	</desc>
8701	</param>
8702	<param name="stdIn" type="wstring" dir="in">
8703	<desc>
8704	What to do with the standard input (stdin) of the command being
8705	executed. Currently not used and has to be set to an empty value.
8706	</desc>
8707	</param>
8708	<param name="stdOut" type="wstring" dir="in">
8709	<desc>
8710	What to do with the standard output (stdout) of the command being
8711	executed. Currently not used and has to be set to an empty value.
8712	</desc>
8713	</param>
8714	<param name="stdErr" type="wstring" dir="in">
8715	<desc>
8716	What to do with the standard error (stderr) of the command being
8717	executed. Currently not used and has to be set to an empty value.
8718	</desc>
8719	</param>
8720	<param name="userName" type="wstring" dir="in">
8721	<desc>
8722	User name under which the command will be executed; has to exist
8723	and have the appropriate rights to execute programs in the VM.
8724	</desc>
8725	</param>
8726	<param name="password" type="wstring" dir="in">
8727	<desc>
8728	Password of the user account specified.
8729	</desc>
8730	</param>
8731	<param name="timeoutMS" type="unsigned long" dir="in">
8732	<desc>
8733	The maximum timeout value (in msec) to wait for finished program
8734	execution. Pass 0 for an infinite timeout.
8735	</desc>
8736	</param>
8737	<param name="pid" type="unsigned long" dir="out">
8738	<desc>
8739	The PID (process ID) of the started command for later reference.
8740	</desc>
8741	</param>
8742	<param name="progress" type="IProgress" dir="return">
8743	<desc>Progress object to track the operation completion.</desc>
8744	</param>
8745	</method>
8746
8747	<method name="getProcessOutput">
8748	<desc>
8749	Retrieves output of a formerly started process.
8750
8751	<result name="VBOX_E_IPRT_ERROR">
8752	Could not retrieve output.
8753	</result>
8754
8755	</desc>
8756	<param name="pid" type="unsigned long" dir="in">
8757	<desc>
8758	Process id returned by earlier executeProcess() call.
8759	</desc>
8760	</param>
8761	<param name="flags" type="unsigned long" dir="in">
8762	<desc>
8763	Flags describing which output to retrieve.
8764	</desc>
8765	</param>
8766	<param name="timeoutMS" type="unsigned long" dir="in">
8767	<desc>
8768	The maximum timeout value (in msec) to wait for output
8769	data. Pass 0 for an infinite timeout.
8770	</desc>
8771	</param>
8772	<param name="size" type="unsigned long long" dir="in">
8773	<desc>
8774	Size in bytes to read in the buffer.
8775	</desc>
8776	</param>
8777	<param name="data" type="octet" dir="return" safearray="yes">
8778	<desc>
8779	Buffer for retrieving the actual output. A data size of 0 means end of file
8780	if the requested size was not 0. This is the unprocessed
8781	output data, i.e. the line ending style depends on the platform of
8782	the system the server is running on.
8783	</desc>
8784	</param>
8785	</method>
8786
8787	<method name="getProcessStatus">
8788	<desc>
8789	Retrieves status, exit code and the exit reason of a formerly started process.
8790
8791	<result name="VBOX_E_IPRT_ERROR">
8792	Process with specified PID was not found.
8793	</result>
8794
8795	</desc>
8796	<param name="pid" type="unsigned long" dir="in">
8797	<desc>
8798	Process id returned by earlier executeProcess() call.
8799	</desc>
8800	</param>
8801	<param name="exitcode" type="unsigned long" dir="out">
8802	<desc>
8803	The exit code (if available).
8804	</desc>
8805	</param>
8806	<param name="flags" type="unsigned long" dir="out">
8807	<desc>
8808	Additional flags of process status (not used at the moment).
8809	</desc>
8810	</param>
8811	<param name="reason" type="unsigned long" dir="return">
8812	<desc>
8813	The current process status.
8814	</desc>
8815	</param>
8816	</method>
8817
8818	</interface>
8819
8820
8821	<!--
8822	// IProgress
8823	/////////////////////////////////////////////////////////////////////////
8824	-->
8825
8826	<interface
8827	name="IProgress" extends="$unknown"
8828	uuid="856aa038-853f-42e2-acf7-6e7b02dbe294"
8829	wsmap="managed"
8830	>
8831	<desc>
8832	The IProgress interface is used to track and control
8833	asynchronous tasks within VirtualBox.
8834
8835	An instance of this is returned every time VirtualBox starts
8836	an asynchronous task (in other words, a separate thread) which
8837	continues to run after a method call returns. For example,
8838	<link to="IConsole::saveState" />, which saves the state of
8839	a running virtual machine, can take a long time to complete.
8840	To be able to display a progress bar, a user interface such as
8841	the VirtualBox graphical user interface can use the IProgress
8842	object returned by that method.
8843
8844	Note that IProgress is a "read-only" interface in the sense
8845	that only the VirtualBox internals behind the Main API can
8846	create and manipulate progress objects, whereas client code
8847	can only use the IProgress object to monitor a task's
8848	progress and, if <link to="#cancelable" /> is @c true,
8849	cancel the task by calling <link to="#cancel" />.
8850
8851	A task represented by IProgress consists of either one or
8852	several sub-operations that run sequentially, one by one (see
8853	<link to="#operation" /> and <link to="#operationCount" />).
8854	Every operation is identified by a number (starting from 0)
8855	and has a separate description.
8856
8857	You can find the individual percentage of completion of the current
8858	operation in <link to="#operationPercent" /> and the
8859	percentage of completion of the task as a whole
8860	in <link to="#percent" />.
8861
8862	Similarly, you can wait for the completion of a particular
8863	operation via <link to="#waitForOperationCompletion" /> or
8864	for the completion of the whole task via
8865	<link to="#waitForCompletion" />.
8866	</desc>
8867
8868	<attribute name="id" type="uuid" mod="string" readonly="yes">
8869	<desc>ID of the task.</desc>
8870	</attribute>
8871
8872	<attribute name="description" type="wstring" readonly="yes">
8873	<desc>Description of the task.</desc>
8874	</attribute>
8875
8876	<attribute name="initiator" type="$unknown" readonly="yes">
8877	<desc>Initiator of the task.</desc>
8878	</attribute>
8879
8880	<attribute name="cancelable" type="boolean" readonly="yes">
8881	<desc>Whether the task can be interrupted.</desc>
8882	</attribute>
8883
8884	<attribute name="percent" type="unsigned long" readonly="yes">
8885	<desc>
8886	Current progress value of the task as a whole, in percent.
8887	This value depends on how many operations are already complete.
8888	Returns 100 if <link to="#completed" /> is @c true.
8889	</desc>
8890	</attribute>
8891
8892	<attribute name="timeRemaining" type="long" readonly="yes">
8893	<desc>
8894	Estimated remaining time until the task completes, in
8895	seconds. Returns 0 once the task has completed; returns -1
8896	if the remaining time cannot be computed, in particular if
8897	the current progress is 0.
8898
8899	Even if a value is returned, the estimate will be unreliable
8900	for low progress values. It will become more reliable as the
8901	task progresses; it is not recommended to display an ETA
8902	before at least 20% of a task have completed.
8903	</desc>
8904	</attribute>
8905
8906	<attribute name="completed" type="boolean" readonly="yes">
8907	<desc>Whether the task has been completed.</desc>
8908	</attribute>
8909
8910	<attribute name="canceled" type="boolean" readonly="yes">
8911	<desc>Whether the task has been canceled.</desc>
8912	</attribute>
8913
8914	<attribute name="resultCode" type="long" readonly="yes">
8915	<desc>
8916	Result code of the progress task.
8917	Valid only if <link to="#completed"/> is @c true.
8918	</desc>
8919	</attribute>
8920
8921	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
8922	<desc>
8923	Extended information about the unsuccessful result of the
8924	progress operation. May be @c null if no extended information
8925	is available.
8926	Valid only if <link to="#completed"/> is @c true and
8927	<link to="#resultCode"/> indicates a failure.
8928	</desc>
8929	</attribute>
8930
8931	<attribute name="operationCount" type="unsigned long" readonly="yes">
8932	<desc>
8933	Number of sub-operations this task is divided into.
8934	Every task consists of at least one suboperation.
8935	</desc>
8936	</attribute>
8937
8938	<attribute name="operation" type="unsigned long" readonly="yes">
8939	<desc>Number of the sub-operation being currently executed.</desc>
8940	</attribute>
8941
8942	<attribute name="operationDescription" type="wstring" readonly="yes">
8943	<desc>
8944	Description of the sub-operation being currently executed.
8945	</desc>
8946	</attribute>
8947
8948	<attribute name="operationPercent" type="unsigned long" readonly="yes">
8949	<desc>Progress value of the current sub-operation only, in percent.</desc>
8950	</attribute>
8951
8952	<attribute name="timeout" type="unsigned long">
8953	<desc>
8954	When non-zero, this specifies the number of milliseconds after which
8955	the operation will automatically be canceled. This can only be set on
8956	cancelable objects.
8957	</desc>
8958	</attribute>
8959
8960	<method name="setCurrentOperationProgress">
8961	<desc>Internal method, not to be called externally.</desc>
8962	<param name="percent" type="unsigned long" dir="in" />
8963	</method>
8964	<method name="setNextOperation">
8965	<desc>Internal method, not to be called externally.</desc>
8966	<param name="nextOperationDescription" type="wstring" dir="in" />
8967	<param name="nextOperationsWeight" type="unsigned long" dir="in" />
8968	</method>
8969
8970	<method name="waitForCompletion">
8971	<desc>
8972	Waits until the task is done (including all sub-operations)
8973	with a given timeout in milliseconds; specify -1 for an indefinite wait.
8974
8975	<result name="VBOX_E_IPRT_ERROR">
8976	Failed to wait for task completion.
8977	</result>
8978	</desc>
8979
8980	<param name="timeout" type="long" dir="in">
8981	<desc>
8982	Maximum time in milliseconds to wait or -1 to wait indefinitely.
8983	</desc>
8984	</param>
8985	</method>
8986
8987	<method name="waitForOperationCompletion">
8988	<desc>
8989	Waits until the given operation is done with a given timeout in
8990	milliseconds; specify -1 for an indefinite wait.
8991
8992	<result name="VBOX_E_IPRT_ERROR">
8993	Failed to wait for operation completion.
8994	</result>
8995
8996	</desc>
8997	<param name="operation" type="unsigned long" dir="in">
8998	<desc>
8999	Number of the operation to wait for.
9000	Must be less than <link to="#operationCount"/>.
9001	</desc>
9002	</param>
9003	<param name="timeout" type="long" dir="in">
9004	<desc>
9005	Maximum time in milliseconds to wait or -1 to wait indefinitely.
9006	</desc>
9007	</param>
9008	</method>
9009
9010	<method name="cancel">
9011	<desc>
9012	Cancels the task.
9013	<note>
9014	If <link to="#cancelable"/> is @c false, then this method will fail.
9015	</note>
9016
9017	<result name="VBOX_E_INVALID_OBJECT_STATE">
9018	Operation cannot be canceled.
9019	</result>
9020
9021	</desc>
9022	</method>
9023
9024	</interface>
9025
9026
9027	<!--
9028	// ISnapshot
9029	/////////////////////////////////////////////////////////////////////////
9030	-->
9031
9032	<interface
9033	name="ISnapshot" extends="$unknown"
9034	uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
9035	wsmap="managed"
9036	>
9037	<desc>
9038	The ISnapshot interface represents a snapshot of the virtual
9039	machine.
9040
9041	Together with the differencing media that are created
9042	when a snapshot is taken, a machine can be brought back to
9043	the exact state it was in when the snapshot was taken.
9044
9045	The ISnapshot interface has no methods, only attributes; snapshots
9046	are controlled through methods of the <link to="IConsole" /> interface
9047	which also manage the media associated with the snapshot.
9048	The following operations exist:
9049
9050	<ul>
9051	<li><link to="IConsole::takeSnapshot"/>: creates a new snapshot
9052	by creating new, empty differencing images for the machine's
9053	media and saving the VM settings and (if the VM is running)
9054	the current VM state in the snapshot.
9055
9056	The differencing images will then receive all data written to
9057	the machine's media, while their parent (base) images
9058	remain unmodified after the snapshot has been taken (see
9059	<link to="IMedium" /> for details about differencing images).
9060	This simplifies restoring a machine to the state of a snapshot:
9061	only the differencing images need to be deleted.
9062
9063	The current machine state is not changed by taking a snapshot.
9064	If the machine is running, it will resume execution after the
9065	snapshot has been taken.
9066	</li>
9067
9068	<li><link to="IConsole::restoreSnapshot"/>: this goes back to
9069	a previous snapshot. This resets the machine's state to that of
9070	the previous snapshot by deleting the differencing image of each
9071	of the machine's media and setting the machine's settings
9072	and state to the state that was saved in the snapshot (if any).
9073
9074	This destroys the machine's current state.
9075	</li>
9076
9077	<li><link to="IConsole::deleteSnapshot"/>: deletes a snapshot
9078	without affecting the current machine state.
9079
9080	This does not change the machine, but instead frees the resources
9081	allocated when the snapshot was taken: the settings and machine state
9082	is deleted (if any), and the snapshot's differencing image for each
9083	of the machine's media gets merged with its parent image.
9084
9085	Neither the current machine state nor other snapshots are affected
9086	by this operation, except that parent media will be modified
9087	to contain the disk data associated with the snapshot being deleted.
9088	</li>
9089	</ul>
9090
9091	Each snapshot contains the settings of the virtual machine (hardware
9092	configuration etc.). In addition, if the machine was running when the
9093	snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
9094	the current VM state is saved in the snapshot (similarly to what happens
9095	when a VM's state is saved). The snapshot is then said to
9096	be <i>online</i> because when restoring it, the VM will be running.
9097
9098	If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
9099	receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
9100
9101	Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
9102	or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
9103	it then contains a so-called "zero execution state", representing a
9104	machine that is powered off.
9105
9106	<h3>Snapshot branches and the "current" snapshot</h3>
9107
9108	Snapshots can be chained, whereby every next snapshot is based on the
9109	previous one. This chaining is related to medium branching
9110	(see the <link to="IMedium"/> description) in that every time
9111	a new snapshot is created, a new differencing medium is implicitly
9112	created for all normal media attached to the machine.
9113
9114	Each virtual machine has a "current snapshot", identified by
9115	<link to="IMachine::currentSnapshot"/>. Presently, this is always set
9116	to the last snapshot in the chain. In a future version of VirtualBox,
9117	it will be possible to reset a machine's current state to that of an
9118	earlier snapshot without deleting the current state so that it will be
9119	possible to create alternative snapshot paths in a snapshot tree.
9120
9121	In the current implementation, multiple snapshot branches within one
9122	virtual machine are not allowed. Every machine has a single branch,
9123	and <link to="IConsole::takeSnapshot"/> operation adds a new
9124	snapshot to the top of that branch.
9125	</desc>
9126
9127	<attribute name="id" type="uuid" mod="string" readonly="yes">
9128	<desc>UUID of the snapshot.</desc>
9129	</attribute>
9130
9131	<attribute name="name" type="wstring">
9132	<desc>Short name of the snapshot.</desc>
9133	</attribute>
9134
9135	<attribute name="description" type="wstring">
9136	<desc>Optional description of the snapshot.</desc>
9137	</attribute>
9138
9139	<attribute name="timeStamp" type="long long" readonly="yes">
9140	<desc>
9141	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
9142	</desc>
9143	</attribute>
9144
9145	<attribute name="online" type="boolean" readonly="yes">
9146	<desc>
9147	@c true if this snapshot is an online snapshot and @c false otherwise.
9148
9149	When this attribute is @c true, the
9150	<link to="IMachine::stateFilePath"/> attribute of the
9151	<link to="#machine"/> object associated with this snapshot
9152	will point to the saved state file. Otherwise, it will be
9153	an empty string.
9154	</desc>
9155	</attribute>
9156
9157	<attribute name="machine" type="IMachine" readonly="yes">
9158	<desc>
9159	Virtual machine this snapshot is taken on. This object
9160	stores all settings the machine had when taking this snapshot.
9161	<note>
9162	The returned machine object is immutable, i.e. no
9163	any settings can be changed.
9164	</note>
9165	</desc>
9166	</attribute>
9167
9168	<attribute name="parent" type="ISnapshot" readonly="yes">
9169	<desc>
9170	Parent snapshot (a snapshot this one is based on), or
9171	@c null if the snapshot has no parent (i.e. is the first snapshot).
9172	</desc>
9173	</attribute>
9174
9175	<attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
9176	<desc>
9177	Child snapshots (all snapshots having this one as a parent).
9178	</desc>
9179	</attribute>
9180
9181	</interface>
9182
9183
9184	<!--
9185	// IMedium
9186	/////////////////////////////////////////////////////////////////////////
9187	-->
9188
9189	<enum
9190	name="MediumState"
9191	uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
9192	>
9193	<desc>
9194	Virtual medium state.
9195	<see>IMedium</see>
9196	</desc>
9197
9198	<const name="NotCreated" value="0">
9199	<desc>
9200	Associated medium storage does not exist (either was not created yet or
9201	was deleted).
9202	</desc>
9203	</const>
9204	<const name="Created" value="1">
9205	<desc>
9206	Associated storage exists and accessible; this gets set if the
9207	accessibility check performed by <link to="IMedium::refreshState" />
9208	was successful.
9209	</desc>
9210	</const>
9211	<const name="LockedRead" value="2">
9212	<desc>
9213	Medium is locked for reading (see <link to="IMedium::lockRead"/>),
9214	no data modification is possible.
9215	</desc>
9216	</const>
9217	<const name="LockedWrite" value="3">
9218	<desc>
9219	Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
9220	no concurrent data reading or modification is possible.
9221	</desc>
9222	</const>
9223	<const name="Inaccessible" value="4">
9224	<desc>
9225	Medium accessiblity check (see <link to="IMedium::refreshState" />) has
9226	not yet been performed, or else, associated medium storage is not
9227	accessible. In the first case, <link to="IMedium::lastAccessError"/>
9228	is empty, in the second case, it describes the error that occured.
9229	</desc>
9230	</const>
9231	<const name="Creating" value="5">
9232	<desc>
9233	Associated medium storage is being created.
9234	</desc>
9235	</const>
9236	<const name="Deleting" value="6">
9237	<desc>
9238	Associated medium storage is being deleted.
9239	</desc>
9240	</const>
9241	</enum>
9242
9243	<enum
9244	name="MediumType"
9245	uuid="46bf1fd4-ad86-4ded-8c49-28bd2d148e5a"
9246	>
9247	<desc>
9248	Virtual medium type.
9249	<see>IMedium</see>
9250	</desc>
9251
9252	<const name="Normal" value="0">
9253	<desc>
9254	Normal medium (attached directly or indirectly, preserved
9255	when taking snapshots).
9256	</desc>
9257	</const>
9258	<const name="Immutable" value="1">
9259	<desc>
9260	Immutable medium (attached indirectly, changes are wiped out
9261	the next time the virtual machine is started).
9262	</desc>
9263	</const>
9264	<const name="Writethrough" value="2">
9265	<desc>
9266	Write through medium (attached directly, ignored when
9267	taking snapshots).
9268	</desc>
9269	</const>
9270	<const name="Shareable" value="3">
9271	<desc>
9272	Allow using this medium concurrently by several machines.
9273	<note>This is a stub value. Not usable until this note is removed.</note>
9274	</desc>
9275	</const>
9276	</enum>
9277
9278	<enum
9279	name="MediumVariant"
9280	uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
9281	>
9282	<desc>
9283	Virtual medium image variant. More than one flag may be set.
9284	<see>IMedium</see>
9285	</desc>
9286
9287	<const name="Standard" value="0">
9288	<desc>
9289	No particular variant requested, results in using the backend default.
9290	</desc>
9291	</const>
9292	<const name="VmdkSplit2G" value="0x01">
9293	<desc>
9294	VMDK image split in chunks of less than 2GByte.
9295	</desc>
9296	</const>
9297	<const name="VmdkStreamOptimized" value="0x04">
9298	<desc>
9299	VMDK streamOptimized image. Special import/export format which is
9300	read-only/append-only.
9301	</desc>
9302	</const>
9303	<const name="VmdkESX" value="0x08">
9304	<desc>
9305	VMDK format variant used on ESX products.
9306	</desc>
9307	</const>
9308	<const name="Fixed" value="0x10000">
9309	<desc>
9310	Fixed image. Only allowed for base images.
9311	</desc>
9312	</const>
9313	<const name="Diff" value="0x20000">
9314	<desc>
9315	Fixed image. Only allowed for base images.
9316	</desc>
9317	</const>
9318	</enum>
9319
9320	<interface
9321	name="IMediumAttachment" extends="$unknown"
9322	uuid="e58eb3eb-8627-428b-bdf8-34487c848de5"
9323	wsmap="struct"
9324	>
9325	<desc>
9326	The IMediumAttachment interface represents the attachment
9327	of a storage medium to a virtual machine. Each machine contains
9328	an array of its medium attachments in <link to="IMachine::mediumAttachments"/>.
9329
9330	Each medium attachment specifies a storage controller as well as a port
9331	and device number. Fixed media (hard disks) will always also specify
9332	an instance of IMedium in <link to="#medium" />, referring to the hard disk
9333	medium. For removeable media, the IMedia instance is optional; it can be
9334	@c null if no media is mounted (see <link to="IMachine::mountMedium" />).
9335	</desc>
9336
9337	<attribute name="medium" type="IMedium" readonly="yes">
9338	<desc>Medium object associated with this attachment; it
9339	can be @c null for removable devices.</desc>
9340	</attribute>
9341
9342	<attribute name="controller" type="wstring" readonly="yes">
9343	<desc>Name of the storage controller of this attachment; this
9344	refers to one of the controllers in <link to="IMachine::storageControllers" />
9345	by name.</desc>
9346	</attribute>
9347
9348	<attribute name="port" type="long" readonly="yes">
9349	<desc>Port number of this attachment.</desc>
9350	</attribute>
9351
9352	<attribute name="device" type="long" readonly="yes">
9353	<desc>Device slot number of this attachment.</desc>
9354	</attribute>
9355
9356	<attribute name="type" type="DeviceType" readonly="yes">
9357	<desc>Device type of this attachment.</desc>
9358	</attribute>
9359
9360	<attribute name="passthrough" type="boolean" readonly="yes">
9361	<desc>Pass I/O requests through to a device on the host.</desc>
9362	</attribute>
9363
9364	</interface>
9365
9366	<interface
9367	name="IMedium" extends="$unknown"
9368	uuid="1d578f43-5ef1-4415-b556-7592d3ccdc8f"
9369	wsmap="managed"
9370	>
9371	<desc>
9372	The IMedium interface represents virtual storage for a machine's
9373	hard disks, CD/DVD or floppy drives. It will typically represent
9374	a disk image on the host, for example a VDI or VMDK file representing
9375	a virtual hard disk, or an ISO or RAW file representing virtual
9376	removable media, but can also point to a network location (e.g.
9377	for iSCSI targets).
9378
9379	Instances of IMedium are connected to virtual machines by way of
9380	medium attachments (see <link to="IMediumAttachment" />), which link
9381	the storage medium to a particular device slot of a storage controller
9382	of the virtual machine.
9383	In the VirtualBox API, virtual storage is therefore always represented
9384	by the following chain of object links:
9385
9386	<ul>
9387	<li><link to="IMachine::storageControllers"/> contains an array of
9388	storage controllers (IDE, SATA, SCSI or a floppy controller;
9389	these are instances of <link to="IStorageController"/>).</li>
9390	<li><link to="IMachine::mediumAttachments"/> contains an array of
9391	medium attachments (instances of <link to="IMediumAttachment"/>),
9392	each containing a storage controller from the above array, a
9393	port/device specification, and an instance of IMedium representing
9394	the medium storage (image file).
9395
9396	For removable media, the storage medium is optional; a medium
9397	attachment with no medium represents a CD/DVD or floppy drive
9398	with no medium inserted. By contrast, hard disk attachments
9399	will always have an IMedium object attached.</li>
9400	<li>Each IMedium in turn points to a storage unit (such as a file
9401	on the host computer or a network resource) that holds actual
9402	data. This location is represented by the <link to="#location"/>
9403	attribute.</li>
9404	</ul>
9405
9406	Existing media are opened using the following methods, depending on the
9407	media type:
9408	<ul>
9409	<li><link to="IVirtualBox::openHardDisk"/></li>
9410	<li><link to="IVirtualBox::openDVDImage"/></li>
9411	<li><link to="IVirtualBox::openFloppyImage"/></li>
9412	</ul>
9413
9414	New hard disk media can be created with the VirtualBox API using the
9415	<link to="IVirtualBox::createHardDisk"/> method.
9416
9417	CD/DVD and floppy images (ISO and RAW files) are usually created outside
9418	VirtualBox, e.g. by storing a copy of the real medium of the corresponding
9419	type in a regular file.
9420
9421	Only for CD/DVDs and floppies, an IMedium instance can also represent a host
9422	drive; in that case the <link to="#id" /> attribute contains the UUID of
9423	one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
9424
9425	<h3>Known media</h3>
9426
9427	When an existing medium is opened for the first time, it is automatically
9428	remembered by the given VirtualBox installation or, in other words, becomes
9429	a <i>known medium</i>. Known media are stored in the media
9430	registry transparently maintained by VirtualBox and stored in settings
9431	files so that this registry is preserved when VirtualBox is not running.
9432
9433	Newly created virtual media are remembered only when the associated
9434	storage unit is actually created.
9435
9436	All known media can be enumerated using
9437	<link to="IVirtualBox::hardDisks"/>,
9438	<link to="IVirtualBox::DVDImages"/> and
9439	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
9440	quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
9441	and similar methods or by location using
9442	<link to="IVirtualBox::findHardDisk"/> and similar methods.
9443
9444	Only known media can be attached to virtual machines.
9445
9446	Removing known media from the media registry is performed when the given
9447	medium is closed using the <link to="#close"/> method or when its
9448	associated storage unit is deleted.
9449
9450	<h3>Accessibility checks</h3>
9451
9452	VirtualBox defers media accessibility checks until the <link to="#refreshState" />
9453	method is called explicitly on a medium. This is done to make the VirtualBox object
9454	ready for serving requests as fast as possible and let the end-user
9455	application decide if it needs to check media accessibility right away or not.
9456
9457	As a result, when VirtualBox starts up (e.g. the VirtualBox
9458	object gets created for the first time), all known media are in the
9459	"Inaccessible" state, but the value of the <link to="#lastAccessError"/>
9460	attribute is an empty string because no actual accessibility check has
9461	been made yet.
9462
9463	After calling <link to="#refreshState" />, a medium is considered
9464	<i>accessible</i> if its storage unit can be read. In that case, the
9465	<link to="#state"/> attribute has a value of "Created". If the storage
9466	unit cannot be read (for example, because it is located on a disconnected
9467	network resource, or was accidentally deleted outside VirtualBox),
9468	the medium is considered <i>inaccessible</i>, which is indicated by the
9469	"Inaccessible" state. The exact reason why the medium is inaccessible can be
9470	obtained by reading the <link to="#lastAccessError"/> attribute.
9471
9472	<h3>Medium types</h3>
9473
9474	There are three types of medium behavior (see <link to="MediumType" />):
9475	"normal", "immutable" and "writethrough", represented by the
9476	<link to="#type"/> attribute. The type of the medium defines how the
9477	medium is attached to a virtual machine and what happens when a
9478	<link to="ISnapshot">snapshot</link> of the virtual machine with the
9479	attached medium is taken. At the moment DVD and floppy media are always
9480	of type "writethrough".
9481
9482	All media can be also divided in two groups: <i>base</i> media and
9483	<i>differencing</i> media. A base medium contains all sectors of the
9484	medium data in its own storage and therefore can be used independently.
9485	In contrast, a differencing mediun is a "delta" to some other medium and
9486	contains only those sectors which differ from that other medium, which is
9487	then called a <i>parent</i>. The differencing medium is said to be
9488	<i>linked to</i> that parent. The parent may be itself a differencing
9489	medium, thus forming a chain of linked media. The last element in that
9490	chain must always be a base medium. Note that several differencing
9491	media may be linked to the same parent medium.
9492
9493	Differencing media can be distinguished from base media by querying the
9494	<link to="#parent"/> attribute: base media do not have parents they would
9495	depend on, so the value of this attribute is always @c null for them.
9496	Using this attribute, it is possible to walk up the medium tree (from the
9497	child medium to its parent). It is also possible to walk down the tree
9498	using the <link to="#children"/> attribute.
9499
9500	Note that the type of all differencing media is "Normal"; all other
9501	values are meaningless for them. Base media may be of any type.
9502
9503	<h3>Creating hard disks</h3>
9504
9505	New base hard disks are created using
9506	<link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
9507	opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
9508	disks are usually implicitly created by VirtualBox when needed but may
9509	also be created explicitly using <link to="#createDiffStorage"/>.
9510
9511	After the hard disk is successfully created (including the storage unit)
9512	or opened, it becomes a known hard disk (remembered in the internal media
9513	registry). Known hard disks can be attached to a virtual machine, accessed
9514	through <link to="IVirtualBox::getHardDisk"/> and
9515	<link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
9516	<link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
9517
9518	The following methods, besides <link to="IMedium::close"/>,
9519	automatically remove the hard disk from the media registry:
9520	<ul>
9521	<li><link to="#deleteStorage"/></li>
9522	<li><link to="#mergeTo"/></li>
9523	</ul>
9524
9525	If the storage unit of the hard disk is a regular file in the host's
9526	file system then the rules stated in the description of the
9527	<link to="IMedium::location"/> attribute apply when setting its value. In
9528	addition, a plain file name without any path may be given, in which case
9529	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
9530	folder</link> will be prepended to it.
9531
9532	<h4>Automatic composition of the file name part</h4>
9533
9534	Another extension to the <link to="IMedium::location"/> attribute is that
9535	there is a possibility to cause VirtualBox to compose a unique value for
9536	the file name part of the location using the UUID of the hard disk. This
9537	applies only to hard disks in <link to="MediumState_NotCreated"/> state,
9538	e.g. before the storage unit is created, and works as follows. You set the
9539	value of the <link to="IMedium::location"/> attribute to a location
9540	specification which only contains the path specification but not the file
9541	name part and ends with either a forward slash or a backslash character.
9542	In response, VirtualBox will generate a new UUID for the hard disk and
9543	compose the file name using the following pattern:
9544	<pre>
9545	<path>/{<uuid>}.<ext>
9546	</pre>
9547	where <tt><path></tt> is the supplied path specification,
9548	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
9549	is the default extension for the storage format of this hard disk. After
9550	that, you may call any of the methods that create a new hard disk storage
9551	unit and they will use the generated UUID and file name.
9552
9553	<h3>Attaching Hard Disks</h3>
9554
9555	Hard disks are attached to virtual machines using the
9556	<link to="IMachine::attachDevice"/> method and detached using the
9557	<link to="IMachine::detachDevice"/> method. Depending on their
9558	<link to="#type"/>, hard disks are attached either
9559	<i>directly</i> or <i>indirectly</i>.
9560
9561	When a hard disk is being attached directly, it is associated with the
9562	virtual machine and used for hard disk operations when the machine is
9563	running. When a hard disk is being attached indirectly, a new differencing
9564	hard disk linked to it is implicitly created and this differencing hard
9565	disk is associated with the machine and used for hard disk operations.
9566	This also means that if <link to="IMachine::attachDevice"/> performs
9567	a direct attachment then the same hard disk will be returned in response
9568	to the subsequent <link to="IMachine::getMedium"/> call; however if
9569	an indirect attachment is performed then
9570	<link to="IMachine::getMedium"/> will return the implicitly created
9571	differencing hard disk, not the original one passed to <link
9572	to="IMachine::attachDevice"/>. In detail:
9573
9574	<ul>
9575	<li><b>Normal base</b> hard disks that do not have children (i.e.
9576	differencing hard disks linked to them) and that are not already
9577	attached to virtual machines in snapshots are attached <b>directly</b>.
9578	Otherwise, they are attached <b>indirectly</b> because having
9579	dependent children or being part of the snapshot makes it impossible
9580	to modify hard disk contents without breaking the integrity of the
9581	dependent party. The <link to="#readOnly"/> attribute allows to
9582	quickly determine the kind of the attachment for the given hard
9583	disk. Note that if a normal base hard disk is to be indirectly
9584	attached to a virtual machine with snapshots then a special
9585	procedure called <i>smart attachment</i> is performed (see below).</li>
9586	<li><b>Normal differencing</b> hard disks are like normal base hard disks:
9587	they are attached <b>directly</b> if they do not have children and are
9588	not attached to virtual machines in snapshots, and <b>indirectly</b>
9589	otherwise. Note that the smart attachment procedure is never performed
9590	for differencing hard disks.</li>
9591	<li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
9592	they are designed to be non-writable. If an immutable hard disk is
9593	attached to a virtual machine with snapshots then a special
9594	procedure called smart attachment is performed (see below).</li>
9595	<li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
9596	also as designed. This also means that writethrough hard disks cannot
9597	have other hard disks linked to them at all.</li>
9598	</ul>
9599
9600	Note that the same hard disk, regardless of its type, may be attached to
9601	more than one virtual machine at a time. In this case, the machine that is
9602	started first gains exclusive access to the hard disk and attempts to
9603	start other machines having this hard disk attached will fail until the
9604	first machine is powered down.
9605
9606	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
9607	that the given hard disk remains associated with the given machine after a
9608	successful <link to="IMachine::detachDevice"/> call until
9609	<link to="IMachine::saveSettings"/> is called to save all changes to
9610	machine settings to disk. This deferring is necessary to guarantee that
9611	the hard disk configuration may be restored at any time by a call to
9612	<link to="IMachine::discardSettings"/> before the settings
9613	are saved (committed).
9614
9615	Note that if <link to="IMachine::discardSettings"/> is called after
9616	indirectly attaching some hard disks to the machine but before a call to
9617	<link to="IMachine::saveSettings"/> is made, it will implicitly delete
9618	all differencing hard disks implicitly created by
9619	<link to="IMachine::attachDevice"/> for these indirect attachments.
9620	Such implicitly created hard disks will also be immediately deleted when
9621	detached explicitly using the <link to="IMachine::detachDevice"/>
9622	call if it is made before <link to="IMachine::saveSettings"/>. This
9623	implicit deletion is safe because newly created differencing hard
9624	disks do not contain any user data.
9625
9626	However, keep in mind that detaching differencing hard disks that were
9627	implicitly created by <link to="IMachine::attachDevice"/>
9628	before the last <link to="IMachine::saveSettings"/> call will
9629	<b>not</b> implicitly delete them as they may already contain some data
9630	(for example, as a result of virtual machine execution). If these hard
9631	disks are no more necessary, the caller can always delete them explicitly
9632	using <link to="#deleteStorage"/> after they are actually de-associated
9633	from this machine by the <link to="IMachine::saveSettings"/> call.
9634
9635	<h3>Smart Attachment</h3>
9636
9637	When normal base or immutable hard disks are indirectly attached to a
9638	virtual machine then some additional steps are performed to make sure the
9639	virtual machine will have the most recent "view" of the hard disk being
9640	attached. These steps include walking through the machine's snapshots
9641	starting from the current one and going through ancestors up to the first
9642	snapshot. Hard disks attached to the virtual machine in all
9643	of the encountered snapshots are checked whether they are descendants of
9644	the given normal base or immutable hard disk. The first found child (which
9645	is the differencing hard disk) will be used instead of the normal base or
9646	immutable hard disk as a parent for creating a new differencing hard disk
9647	that will be actually attached to the machine. And only if no descendants
9648	are found or if the virtual machine does not have any snapshots then the
9649	normal base or immutable hard disk will be used itself as a parent for
9650	this differencing hard disk.
9651
9652	It is easier to explain what smart attachment does using the
9653	following example:
9654	<pre>
9655	BEFORE attaching B.vdi: AFTER attaching B.vdi:
9656
9657	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
9658	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
9659	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
9660	Snapshot 4 (none) Snapshot 4 (none)
9661	CurState (none) CurState (D3->D2.vdi)
9662
9663	NOT
9664	...
9665	CurState (D3->B.vdi)
9666	</pre>
9667	The first column is the virtual machine configuration before the base hard
9668	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
9669	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
9670	mean that the hard disk that is actually attached to the machine is a
9671	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
9672	another hard disk, <tt>B.vdi</tt>.
9673
9674	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
9675	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
9676	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
9677	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
9678	it cannot be attached directly and needs an indirect attachment (i.e.
9679	implicit creation of a new differencing hard disk). Due to the smart
9680	attachment procedure, the new differencing hard disk
9681	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
9682	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
9683	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
9684	machine.
9685
9686	Note that if there is more than one descendant hard disk of the given base
9687	hard disk found in a snapshot, and there is an exact device, channel and
9688	bus match, then this exact match will be used. Otherwise, the youngest
9689	descendant will be picked up.
9690
9691	There is one more important aspect of the smart attachment procedure which
9692	is not related to snapshots at all. Before walking through the snapshots
9693	as described above, the backup copy of the current list of hard disk
9694	attachment is searched for descendants. This backup copy is created when
9695	the hard disk configuration is changed for the first time after the last
9696	<link to="IMachine::saveSettings"/> call and used by
9697	<link to="IMachine::discardSettings"/> to undo the recent hard disk
9698	changes. When such a descendant is found in this backup copy, it will be
9699	simply re-attached back, without creating a new differencing hard disk for
9700	it. This optimization is necessary to make it possible to re-attach the
9701	base or immutable hard disk to a different bus, channel or device slot
9702	without losing the contents of the differencing hard disk actually
9703	attached to the machine in place of it.
9704	</desc>
9705
9706	<attribute name="id" type="uuid" mod="string" readonly="yes">
9707	<desc>
9708	UUID of the medium. For a newly created medium, this value is a randomly
9709	generated UUID.
9710
9711	<note>
9712	For media in one of MediumState_NotCreated, MediumState_Creating or
9713	MediumState_Deleting states, the value of this property is undefined
9714	and will most likely be an empty UUID.
9715	</note>
9716	</desc>
9717	</attribute>
9718
9719	<attribute name="description" type="wstring">
9720	<desc>
9721	Optional description of the medium. For a newly created medium the value
9722	of this attribute is an empty string.
9723
9724	Medium types that don't support this attribute will return E_NOTIMPL in
9725	attempt to get or set this attribute's value.
9726
9727	<note>
9728	For some storage types, reading this attribute may return an outdated
9729	(last known) value when <link to="#state"/> is <link
9730	to="MediumState_Inaccessible"/> or <link
9731	to="MediumState_LockedWrite"/> because the value of this attribute is
9732	stored within the storage unit itself. Also note that changing the
9733	attribute value is not possible in such case, as well as when the
9734	medium is the <link to="MediumState_LockedRead"/> state.
9735	</note>
9736	</desc>
9737	</attribute>
9738
9739	<attribute name="state" type="MediumState" readonly="yes">
9740	<desc>
9741	Returns the current medium state, which is the last state set by
9742	the accessibility check performed by <link to="#refreshState"/>.
9743	If that method has not yet been called on the medium, the state
9744	is "Inaccessible"; as opposed to truly inaccessible media, the
9745	value of <link to="#lastAccessError"/> will be an empty string in
9746	that case.
9747
9748	<note>As of version 3.1, this no longer performs an accessibility check
9749	automatically; call <link to="#refreshState"/> for that.
9750	</note>
9751	</desc>
9752	</attribute>
9753
9754	<attribute name="location" type="wstring">
9755	<desc>
9756	Location of the storage unit holding medium data.
9757
9758	The format of the location string is medium type specific. For medium
9759	types using regular files in a host's file system, the location
9760	string is the full file name.
9761
9762	Some medium types may support changing the storage unit location by
9763	simply changing the value of this property. If this operation is not
9764	supported, the implementation will return E_NOTIMPL in attempt to set
9765	this attribute's value.
9766
9767	When setting a value of the location attribute which is a regular file
9768	in the host's file system, the given file name may be either relative to
9769	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
9770	absolute. Note that if the given location specification does not contain
9771	the file extension part then a proper default extension will be
9772	automatically appended by the implementation depending on the medium type.
9773	</desc>
9774	</attribute>
9775
9776	<attribute name="name" type="wstring" readonly="yes">
9777	<desc>
9778	Name of the storage unit holding medium data.
9779
9780	The returned string is a short version of the <link to="#location"/>
9781	attribute that is suitable for representing the medium in situations
9782	where the full location specification is too long (such as lists
9783	and comboboxes in GUI frontends). This string is also used by frontends
9784	to sort the media list alphabetically when needed.
9785
9786	For example, for locations that are regular files in the host's file
9787	system, the value of this attribute is just the file name (+ extension),
9788	without the path specification.
9789
9790	Note that as opposed to the <link to="#location"/> attribute, the name
9791	attribute will not necessary be unique for a list of media of the
9792	given type and format.
9793	</desc>
9794	</attribute>
9795
9796	<attribute name="deviceType" type="DeviceType" readonly="yes">
9797	<desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
9798	medium.</desc>
9799	</attribute>
9800
9801	<attribute name="hostDrive" type="boolean" readonly="yes">
9802	<desc>True if this corresponds to a drive on the host.</desc>
9803	</attribute>
9804
9805	<attribute name="size" type="unsigned long long" readonly="yes">
9806	<desc>
9807	Physical size of the storage unit used to hold medium data (in bytes).
9808
9809	<note>
9810	For media whose <link to="#state"/> is <link
9811	to="MediumState_Inaccessible"/>, the value of this property is the
9812	last known size. For <link to="MediumState_NotCreated"/> media,
9813	the returned value is zero.
9814	</note>
9815	</desc>
9816	</attribute>
9817
9818	<attribute name="format" type="wstring" readonly="yes">
9819	<desc>
9820	Storage format of this medium.
9821
9822	The value of this attribute is a string that specifies a backend used
9823	to store medium data. The storage format is defined when you create a
9824	new medium or automatically detected when you open an existing medium,
9825	and cannot be changed later.
9826
9827	The list of all storage formats supported by this VirtualBox
9828	installation can be obtained using
9829	<link to="ISystemProperties::mediumFormats"/>.
9830	</desc>
9831	</attribute>
9832
9833	<attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
9834	<desc>
9835	Storage medium format object corresponding to this medium.
9836
9837	The value of this attribute is a reference to the medium format object
9838	that specifies the backend properties used to store medium data. The
9839	storage format is defined when you create a new medium or automatically
9840	detected when you open an existing medium, and cannot be changed later.
9841
9842	<note>@c null is returned if there is no associated medium format
9843	object. This can e.g. happen for medium objects representing host
9844	drives and other special medium objects.</note>
9845	</desc>
9846	</attribute>
9847
9848	<attribute name="type" type="MediumType">
9849	<desc>
9850	Type (role) of this medium.
9851
9852	The following constraints apply when changing the value of this
9853	attribute:
9854	<ul>
9855	<li>If a medium is attached to a virtual machine (either in the
9856	current state or in one of the snapshots), its type cannot be
9857	changed.
9858	</li>
9859	<li>As long as the medium has children, its type cannot be set
9860	to <link to="MediumType_Writethrough"/>.
9861	</li>
9862	<li>The type of all differencing media is
9863	<link to="MediumType_Normal"/> and cannot be changed.
9864	</li>
9865	</ul>
9866
9867	The type of a newly created or opened medium is set to
9868	<link to="MediumType_Normal"/>, except for DVD and floppy media,
9869	which have a type of <link to="MediumType_Writethrough"/>.
9870	</desc>
9871	</attribute>
9872
9873	<attribute name="parent" type="IMedium" readonly="yes">
9874	<desc>
9875	Parent of this medium (the medium this medium is directly based
9876	on).
9877
9878	Only differencing media have parents. For base (non-differencing)
9879	media, @c null is returned.
9880	</desc>
9881	</attribute>
9882
9883	<attribute name="children" type="IMedium" safearray="yes" readonly="yes">
9884	<desc>
9885	Children of this medium (all differencing media directly based
9886	on this medium). A @c null array is returned if this medium
9887	does not have any children.
9888	</desc>
9889	</attribute>
9890
9891	<attribute name="base" type="IMedium" readonly="yes">
9892	<desc>
9893	Base medium of this medium.
9894
9895	If this is a differencing medium, its base medium is the medium
9896	the given medium branch starts from. For all other types of media, this
9897	property returns the medium object itself (i.e. the same object this
9898	property is read on).
9899	</desc>
9900	</attribute>
9901
9902	<attribute name="readOnly" type="boolean" readonly="yes">
9903	<desc>
9904	Returns @c true if this medium is read-only and @c false otherwise.
9905
9906	A medium is considered to be read-only when its contents cannot be
9907	modified without breaking the integrity of other parties that depend on
9908	this medium such as its child media or snapshots of virtual machines
9909	where this medium is attached to these machines. If there are no
9910	children and no such snapshots then there is no dependency and the
9911	medium is not read-only.
9912
9913	The value of this attribute can be used to determine the kind of the
9914	attachment that will take place when attaching this medium to a
9915	virtual machine. If the value is @c false then the medium will
9916	be attached directly. If the value is @c true then the medium
9917	will be attached indirectly by creating a new differencing child
9918	medium for that. See the interface description for more information.
9919
9920	Note that all <link to="MediumType_Immutable">Immutable</link> media
9921	are always read-only while all
9922	<link to="MediumType_Writethrough">Writethrough</link> media are
9923	always not.
9924
9925	<note>
9926	The read-only condition represented by this attribute is related to
9927	the medium type and usage, not to the current
9928	<link to="IMedium::state">medium state</link> and not to the read-only
9929	state of the storage unit.
9930	</note>
9931	</desc>
9932	</attribute>
9933
9934	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
9935	<desc>
9936	Logical size of this medium (in megabytes), as reported to the
9937	guest OS running inside the virtual machine this medium is
9938	attached to. The logical size is defined when the medium is created
9939	and cannot be changed later.
9940
9941	<note>
9942	Reading this property on a differencing medium will return the size
9943	of its <link to="#base"/> medium.
9944	</note>
9945	<note>
9946	For media whose state is <link to="#state"/> is <link
9947	to="MediumState_Inaccessible"/>, the value of this property is the
9948	last known logical size. For <link to="MediumaState_NotCreated"/>
9949	media, the returned value is zero.
9950	</note>
9951	</desc>
9952	</attribute>
9953
9954	<attribute name="autoReset" type="boolean">
9955	<desc>
9956	Whether this differencing medium will be automatically reset each
9957	time a virtual machine it is attached to is powered up. This
9958	attribute is automatically set to @c true for the last
9959	differencing image of an "immutable" medium (see
9960	<link to="MediumType" />).
9961
9962	See <link to="#reset"/> for more information about resetting
9963	differencing media.
9964
9965	<note>
9966	Reading this property on a base (non-differencing) medium will
9967	always @c false. Changing the value of this property in this
9968	case is not supported.
9969	</note>
9970
9971	<result name="VBOX_E_NOT_SUPPORTED">
9972	This is not a differencing medium (when changing the attribute
9973	value).
9974	</result>
9975	</desc>
9976	</attribute>
9977
9978	<attribute name="lastAccessError" type="wstring" readonly="yes">
9979	<desc>
9980	Text message that represents the result of the last accessibility
9981	check performed by <link to="#refreshState"/>.
9982
9983	An empty string is returned if the last accessibility check
9984	was successful or has not yet been called. As a result, if
9985	<link to="#state" /> is "Inaccessible" and this attribute is empty,
9986	then <link to="#refreshState"/> has yet to be called; this is the
9987	default value of media after VirtualBox initialization.
9988	A non-empty string indicates a failure and should normally describe
9989	a reason of the failure (for example, a file read error).
9990	</desc>
9991	</attribute>
9992
9993	<attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
9994	<desc>
9995	Array of UUIDs of all machines this medium is attached to.
9996
9997	A @c null array is returned if this medium is not attached to any
9998	machine or to any machine's snapshot.
9999
10000	<note>
10001	The returned array will include a machine even if this medium is not
10002	attached to that machine in the current state but attached to it in
10003	one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
10004	details.
10005	</note>
10006	</desc>
10007	</attribute>
10008
10009	<method name="refreshState">
10010	<desc>
10011	If the current medium state (see <link to="MediumState"/>) is one of
10012	"Created", "Inaccessible" or "LockedRead", then this performs an
10013	accessibility check on the medium and sets the value of the <link to="#state"/>
10014	attribute accordingly; that value is also returned for convenience.
10015
10016	For all other state values, this does not perform a refresh but returns
10017	the state only.
10018
10019	The refresh, if performed, may take a long time (several seconds or even
10020	minutes, depending on the storage unit location and format) because it performs an
10021	accessibility check of the storage unit. This check may cause a significant
10022	delay if the storage unit of the given medium is, for example, a file located
10023	on a network share which is not currently accessible due to connectivity
10024	problems. In that case, the call will not return until a timeout
10025	interval defined by the host OS for this operation expires. For this reason,
10026	it is recommended to never read this attribute on the main UI thread to avoid
10027	making the UI unresponsive.
10028
10029	If the last known state of the medium is "Created" and the accessibility
10030	check fails, then the state would be set to "Inaccessible", and
10031	<link to="#lastAccessError"/> may be used to get more details about the
10032	failure. If the state of the medium is "LockedRead", then it remains the
10033	same, and a non-empty value of <link to="#lastAccessError"/> will
10034	indicate a failed accessibility check in this case.
10035
10036	Note that not all medium states are applicable to all medium types.
10037	</desc>
10038	<param name="state" type="MediumState" dir="return">
10039	<desc>
10040	New medium state.
10041	</desc>
10042	</param>
10043	</method>
10044
10045	<method name="getSnapshotIds">
10046	<desc>
10047	Returns an array of UUIDs of all snapshots of the given machine where
10048	this medium is attached to.
10049
10050	If the medium is attached to the machine in the current state, then the
10051	first element in the array will always be the ID of the queried machine
10052	(i.e. the value equal to the @c machineId argument), followed by
10053	snapshot IDs (if any).
10054
10055	If the medium is not attached to the machine in the current state, then
10056	the array will contain only snapshot IDs.
10057
10058	The returned array may be @c null if this medium is not attached
10059	to the given machine at all, neither in the current state nor in one of
10060	the snapshots.
10061	</desc>
10062	<param name="machineId" type="uuid" mod="string" dir="in">
10063	<desc>
10064	UUID of the machine to query.
10065	</desc>
10066	</param>
10067	<param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
10068	<desc>
10069	Array of snapshot UUIDs of the given machine using this medium.
10070	</desc>
10071	</param>
10072	</method>
10073
10074	<method name="lockRead">
10075	<desc>
10076	Locks this medium for reading.
10077
10078	A read lock is shared: many clients can simultaneously lock the
10079	same medium for reading unless it is already locked for writing (see
10080	<link to="#lockWrite"/>) in which case an error is returned.
10081
10082	When the medium is locked for reading, it cannot be modified
10083	from within VirtualBox. This means that any method that changes
10084	the properties of this medium or contents of the storage unit
10085	will return an error (unless explicitly stated otherwise). That
10086	includes an attempt to start a virtual machine that wants to
10087	write to the the medium.
10088
10089	When the virtual machine is started up, it locks for reading all
10090	media it uses in read-only mode. If some medium cannot be locked
10091	for reading, the startup procedure will fail.
10092	A medium is typically locked for reading while it is used by a running
10093	virtual machine but has a depending differencing image that receives
10094	the actual write operations. This way one base medium can have
10095	multiple child differencing images which can be written to
10096	simultaneously. Read-only media such as DVD and floppy images are
10097	also locked for reading only (so they can be in use by multiple
10098	machines simultaneously).
10099
10100	A medium is also locked for reading when it is the source of a
10101	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10102
10103	The medium locked for reading must be unlocked using the <link
10104	to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
10105	can be nested and must be followed by the same number of paired
10106	<link to="#unlockRead"/> calls.
10107
10108	This method sets the medium state (see <link to="#state"/>) to
10109	"LockedRead" on success. The medium's previous state must be
10110	one of "Created", "Inaccessible" or "LockedRead".
10111
10112	Locking an inaccessible medium is not an error; this method performs
10113	a logical lock that prevents modifications of this medium through
10114	the VirtualBox API, not a physical file-system lock of the underlying
10115	storage unit.
10116
10117	This method returns the current state of the medium
10118	<i>before</i> the operation.
10119
10120	<result name="VBOX_E_INVALID_OBJECT_STATE">
10121	Invalid medium state (e.g. not created, locked, inaccessible,
10122	creating, deleting).
10123	</result>
10124
10125	</desc>
10126	<param name="state" type="MediumState" dir="return">
10127	<desc>
10128	State of the medium after the operation.
10129	</desc>
10130	</param>
10131	</method>
10132
10133	<method name="unlockRead">
10134	<desc>
10135	Cancels the read lock previously set by <link to="#lockRead"/>.
10136
10137	For both success and failure, this method returns the current state
10138	of the medium <i>after</i> the operation.
10139
10140	See <link to="#lockRead"/> for more details.
10141
10142	<result name="VBOX_E_INVALID_OBJECT_STATE">
10143	Medium not locked for reading.
10144	</result>
10145
10146	</desc>
10147	<param name="state" type="MediumState" dir="return">
10148	<desc>
10149	State of the medium after the operation.
10150	</desc>
10151	</param>
10152	</method>
10153
10154	<method name="lockWrite">
10155	<desc>
10156	Locks this medium for writing.
10157
10158	A write lock, as opposed to <link to="#lockRead"/>, is
10159	exclusive: there may be only one client holding a write lock,
10160	and there may be no read locks while the write lock is held.
10161	As a result, read-locking fails if a write lock is held, and
10162	write-locking fails if either a read or another write lock is held.
10163
10164	When a medium is locked for writing, it cannot be modified
10165	from within VirtualBox, and it is not guaranteed that the values
10166	of its properties are up-to-date. Any method that changes the
10167	properties of this medium or contents of the storage unit will
10168	return an error (unless explicitly stated otherwise).
10169
10170	When a virtual machine is started up, it locks for writing all
10171	media it uses to write data to. If any medium could not be locked
10172	for writing, the startup procedure will fail. If a medium has
10173	differencing images, then while the machine is running, only
10174	the last ("leaf") differencing image is locked for writing,
10175	whereas its parents are locked for reading only.
10176
10177	A medium is also locked for writing when it is the target of a
10178	write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10179
10180	The medium locked for writing must be unlocked using the <link
10181	to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
10182
10183	This method sets the medium state (see <link to="#state"/>) to
10184	"LockedWrite" on success. The medium's previous state must be
10185	either "Created" or "Inaccessible".
10186
10187	Locking an inaccessible medium is not an error; this method performs
10188	a logical lock that prevents modifications of this medium through
10189	the VirtualBox API, not a physical file-system lock of the underlying
10190	storage unit.
10191
10192	For both, success and failure, this method returns the current
10193	state of the medium <i>before</i> the operation.
10194
10195	<result name="VBOX_E_INVALID_OBJECT_STATE">
10196	Invalid medium state (e.g. not created, locked, inaccessible,
10197	creating, deleting).
10198	</result>
10199
10200	</desc>
10201	<param name="state" type="MediumState" dir="return">
10202	<desc>
10203	State of the medium after the operation.
10204	</desc>
10205	</param>
10206	</method>
10207
10208	<method name="unlockWrite">
10209	<desc>
10210	Cancels the write lock previously set by <link to="#lockWrite"/>.
10211
10212	For both success and failure, this method returns the current
10213	state of the medium <i>after</i> the operation.
10214
10215	See <link to="#lockWrite"/> for more details.
10216
10217	<result name="VBOX_E_INVALID_OBJECT_STATE">
10218	Medium not locked for writing.
10219	</result>
10220
10221	</desc>
10222	<param name="state" type="MediumState" dir="return">
10223	<desc>
10224	State of the medium after the operation.
10225	</desc>
10226	</param>
10227	</method>
10228
10229	<method name="close">
10230	<desc>
10231	Closes this medium.
10232
10233	The medium must not be attached to any known virtual machine
10234	and must not have any known child media, otherwise the
10235	operation will fail.
10236
10237	When the medium is successfully closed, it gets removed from
10238	the list of remembered media, but its storage unit is not
10239	deleted. In particular, this means that this medium can be
10240	later opened again using the <link
10241	to="IVirtualBox::openHardDisk"/> call.
10242
10243	Note that after this method successfully returns, the given medium
10244	object becomes uninitialized. This means that any attempt
10245	to call any of its methods or attributes will fail with the
10246	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
10247
10248	<result name="VBOX_E_INVALID_OBJECT_STATE">
10249	Invalid medium state (other than not created, created or
10250	inaccessible).
10251	</result>
10252	<result name="VBOX_E_OBJECT_IN_USE">
10253	Medium attached to virtual machine.
10254	</result>
10255	<result name="VBOX_E_FILE_ERROR">
10256	Settings file not accessible.
10257	</result>
10258	<result name="VBOX_E_XML_ERROR">
10259	Could not parse the settings file.
10260	</result>
10261
10262	</desc>
10263	</method>
10264
10265	<!-- storage methods -->
10266
10267	<method name="getProperty">
10268	<desc>
10269	Returns the value of the custom medium property with the given name.
10270
10271	The list of all properties supported by the given medium format can
10272	be obtained with <link to="IMediumFormat::describeProperties"/>.
10273
10274	Note that if this method returns an empty string in @a value, the
10275	requested property is supported but currently not assigned any value.
10276
10277	<result name="VBOX_E_OBJECT_NOT_FOUND">
10278	Requested property does not exist (not supported by the format).
10279	</result>
10280	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10281	</desc>
10282	<param name="name" type="wstring" dir="in">
10283	<desc>Name of the property to get.</desc>
10284	</param>
10285	<param name="value" type="wstring" dir="return">
10286	<desc>Current property value.</desc>
10287	</param>
10288	</method>
10289
10290	<method name="setProperty">
10291	<desc>
10292	Sets the value of the custom medium property with the given name.
10293
10294	The list of all properties supported by the given medium format can
10295	be obtained with <link to="IMediumFormat::describeProperties"/>.
10296
10297	Note that setting the property value to @c null or an empty string is
10298	equivalent to deleting the existing value. A default value (if it is
10299	defined for this property) will be used by the format backend in this
10300	case.
10301
10302	<result name="VBOX_E_OBJECT_NOT_FOUND">
10303	Requested property does not exist (not supported by the format).
10304	</result>
10305	<result name="E_INVALIDARG">@a name is @c null or empty.</result>
10306	</desc>
10307	<param name="name" type="wstring" dir="in">
10308	<desc>Name of the property to set.</desc>
10309	</param>
10310	<param name="value" type="wstring" dir="in">
10311	<desc>Property value to set.</desc>
10312	</param>
10313	</method>
10314
10315	<method name="getProperties">
10316	<desc>
10317	Returns values for a group of properties in one call.
10318
10319	The names of the properties to get are specified using the @a names
10320	argument which is a list of comma-separated property names or
10321	an empty string if all properties are to be returned. Note that currently
10322	the value of this argument is ignored and the method always returns all
10323	existing properties.
10324
10325	The list of all properties supported by the given medium format can
10326	be obtained with <link to="IMediumFormat::describeProperties"/>.
10327
10328	The method returns two arrays, the array of property names corresponding
10329	to the @a names argument and the current values of these properties.
10330	Both arrays have the same number of elements with each elemend at the
10331	given index in the first array corresponds to an element at the same
10332	index in the second array.
10333
10334	Note that for properties that do not have assigned values,
10335	an empty string is returned at the appropriate index in the
10336	@a returnValues array.
10337
10338	</desc>
10339	<param name="names" type="wstring" dir="in">
10340	<desc>
10341	Names of properties to get.
10342	</desc>
10343	</param>
10344	<param name="returnNames" type="wstring" safearray="yes" dir="out">
10345	<desc>Names of returned properties.</desc>
10346	</param>
10347	<param name="returnValues" type="wstring" safearray="yes" dir="return">
10348	<desc>Values of returned properties.</desc>
10349	</param>
10350	</method>
10351
10352	<method name="setProperties">
10353	<desc>
10354	Sets values for a group of properties in one call.
10355
10356	The names of the properties to set are passed in the @a names
10357	array along with the new values for them in the @a values array. Both
10358	arrays have the same number of elements with each elemend at the given
10359	index in the first array corresponding to an element at the same index
10360	in the second array.
10361
10362	If there is at least one property name in @a names that is not valid,
10363	the method will fail before changing the values of any other properties
10364	from the @a names array.
10365
10366	Using this method over <link to="#setProperty"/> is preferred if you
10367	need to set several properties at once since it will result into less
10368	IPC calls.
10369
10370	The list of all properties supported by the given medium format can
10371	be obtained with <link to="IMediumFormat::describeProperties"/>.
10372
10373	Note that setting the property value to @c null or an empty string is
10374	equivalent to deleting the existing value. A default value (if it is
10375	defined for this property) will be used by the format backend in this
10376	case.
10377	</desc>
10378	<param name="names" type="wstring" safearray="yes" dir="in">
10379	<desc>Names of properties to set.</desc>
10380	</param>
10381	<param name="values" type="wstring" safearray="yes" dir="in">
10382	<desc>Values of properties to set.</desc>
10383	</param>
10384	</method>
10385
10386	<!-- storage methods -->
10387
10388	<method name="createBaseStorage">
10389	<desc>
10390	Starts creating a hard disk storage unit (fixed/dynamic, according
10391	to the variant flags) in in the background. The previous storage unit
10392	created for this object, if any, must first be deleted using
10393	<link to="#deleteStorage"/>, otherwise the operation will fail.
10394
10395	Before the operation starts, the medium is placed in
10396	<link to="MediumState_Creating"/> state. If the create operation
10397	fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
10398	state.
10399
10400	After the returned progress object reports that the operation has
10401	successfully completed, the medium state will be set to <link
10402	to="MediumState_Created"/>, the medium will be remembered by this
10403	VirtualBox installation and may be attached to virtual machines.
10404
10405	<result name="VBOX_E_NOT_SUPPORTED">
10406	The variant of storage creation operation is not supported. See <link
10407	to="IMediumFormat::capabilities"/>.
10408	</result>
10409	</desc>
10410	<param name="logicalSize" type="unsigned long long" dir="in">
10411	<desc>Maximum logical size of the medium in megabytes.</desc>
10412	</param>
10413	<param name="variant" type="MediumVariant" dir="in">
10414	<desc>Exact image variant which should be created.</desc>
10415	</param>
10416	<param name="progress" type="IProgress" dir="return">
10417	<desc>Progress object to track the operation completion.</desc>
10418	</param>
10419	</method>
10420
10421	<method name="deleteStorage">
10422	<desc>
10423	Starts deleting the storage unit of this medium.
10424
10425	The medium must not be attached to any known virtual machine and must
10426	not have any known child media, otherwise the operation will fail.
10427	It will also fail if there is no storage unit to delete or if deletion
10428	is already in progress, or if the medium is being in use (locked for
10429	read or for write) or inaccessible. Therefore, the only valid state for
10430	this operation to succeed is <link to="MediumState_Created"/>.
10431
10432	Before the operation starts, the medium is placed in
10433	<link to="MediumState_Deleting"/> state and gets removed from the list
10434	of remembered hard disks (media registry). If the delete operation
10435	fails, the medium will be remembered again and placed back to
10436	<link to="MediumState_Created"/> state.
10437
10438	After the returned progress object reports that the operation is
10439	complete, the medium state will be set to
10440	<link to="MediumState_NotCreated"/> and you will be able to use one of
10441	the storage creation methods to create it again.
10442
10443	<see>#close()</see>
10444
10445	<result name="VBOX_E_OBJECT_IN_USE">
10446	Medium is attached to a virtual machine.
10447	</result>
10448	<result name="VBOX_E_NOT_SUPPORTED">
10449	Storage deletion is not allowed because neither of storage creation
10450	operations are supported. See
10451	<link to="IMediumFormat::capabilities"/>.
10452	</result>
10453
10454	<note>
10455	If the deletion operation fails, it is not guaranteed that the storage
10456	unit still exists. You may check the <link to="IMedium::state"/> value
10457	to answer this question.
10458	</note>
10459	</desc>
10460	<param name="progress" type="IProgress" dir="return">
10461	<desc>Progress object to track the operation completion.</desc>
10462	</param>
10463	</method>
10464
10465	<!-- diff methods -->
10466
10467	<method name="createDiffStorage">
10468	<desc>
10469	Starts creating an empty differencing storage unit based on this
10470	medium in the format and at the location defined by the @a target
10471	argument.
10472
10473	The target medium must be in <link to="MediumState_NotCreated"/>
10474	state (i.e. must not have an existing storage unit). Upon successful
10475	completion, this operation will set the type of the target medium to
10476	<link to="MediumType_Normal"/> and create a storage unit necessary to
10477	represent the differencing medium data in the given format (according
10478	to the storage format of the target object).
10479
10480	After the returned progress object reports that the operation is
10481	successfully complete, the target medium gets remembered by this
10482	VirtualBox installation and may be attached to virtual machines.
10483
10484	<note>
10485	The medium will be set to <link to="MediumState_LockedRead"/>
10486	state for the duration of this operation.
10487	</note>
10488	<result name="VBOX_E_OBJECT_IN_USE">
10489	Medium not in @c NotCreated state.
10490	</result>
10491	</desc>
10492	<param name="target" type="IMedium" dir="in">
10493	<desc>Target medium.</desc>
10494	</param>
10495	<param name="variant" type="MediumVariant" dir="in">
10496	<desc>Exact image variant which should be created.</desc>
10497	</param>
10498	<param name="progress" type="IProgress" dir="return">
10499	<desc>Progress object to track the operation completion.</desc>
10500	</param>
10501	</method>
10502
10503	<method name="mergeTo">
10504	<desc>
10505	Starts merging the contents of this medium and all intermediate
10506	differencing media in the chain to the given target medium.
10507
10508	The target medium must be either a descendant of this medium or
10509	its ancestor (otherwise this method will immediately return a failure).
10510	It follows that there are two logical directions of the merge operation:
10511	from ancestor to descendant (<i>forward merge</i>) and from descendant to
10512	ancestor (<i>backward merge</i>). Let us consider the following medium
10513	chain:
10514
10515	<pre>Base <- Diff_1 <- Diff_2</pre>
10516
10517	Here, calling this method on the <tt>Base</tt> medium object with
10518	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
10519	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
10520	merge. Note that in both cases the contents of the resulting medium
10521	will be the same, the only difference is the medium object that takes
10522	the result of the merge operation. In case of the forward merge in the
10523	above example, the result will be written to <tt>Diff_2</tt>; in case of
10524	the backward merge, the result will be written to <tt>Base</tt>. In
10525	other words, the result of the operation is always stored in the target
10526	medium.
10527
10528	Upon successful operation completion, the storage units of all media in
10529	the chain between this (source) medium and the target medium, including
10530	the source medium itself, will be automatically deleted and the
10531	relevant medium objects (including this medium) will become
10532	uninitialized. This means that any attempt to call any of
10533	their methods or attributes will fail with the
10534	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
10535	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
10536	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
10537	Note that <tt>Diff_2</tt> in this case will become a base medium
10538	itself since it will no longer be based on any other medium.
10539
10540	Considering the above, all of the following conditions must be met in
10541	order for the merge operation to succeed:
10542	<ul>
10543	<li>
10544	Neither this (source) medium nor any intermediate
10545	differencing medium in the chain between it and the target
10546	medium is attached to any virtual machine.
10547	</li>
10548	<li>
10549	Neither the source medium nor the target medium is an
10550	<link to="MediumType_Immutable"/> medium.
10551	</li>
10552	<li>
10553	The part of the medium tree from the source medium to the
10554	target medium is a linear chain, i.e. all medium in this
10555	chain have exactly one child which is the next medium in this
10556	chain. The only exception from this rule is the target medium in
10557	the forward merge operation; it is allowed to have any number of
10558	child media because the merge operation will not change its
10559	logical contents (as it is seen by the guest OS or by children).
10560	</li>
10561	<li>
10562	None of the involved media are in
10563	<link to="MediumState_LockedRead"/> or
10564	<link to="MediumState_LockedWrite"/> state.
10565	</li>
10566	</ul>
10567
10568	<note>
10569	This (source) medium and all intermediates will be placed to <link
10570	to="MediumState_Deleting"/> state and the target medium will be
10571	placed to <link to="MediumState_LockedWrite"/> state and for the
10572	duration of this operation.
10573	</note>
10574	</desc>
10575	<param name="target" type="IMedium" dir="in">
10576	<desc>Target medium.</desc>
10577	</param>
10578	<param name="progress" type="IProgress" dir="return">
10579	<desc>Progress object to track the operation completion.</desc>
10580	</param>
10581	</method>
10582
10583	<!-- clone method -->
10584
10585	<method name="cloneTo">
10586	<desc>
10587	Starts creating a clone of this medium in the format and at the
10588	location defined by the @a target argument.
10589
10590	The target medium must be either in <link to="MediumState_NotCreated"/>
10591	state (i.e. must not have an existing storage unit) or in
10592	<link to="MediumState_Created"/> state (i.e. created and not locked, and
10593	big enough to hold the data or else the copy will be partial). Upon
10594	successful completion, the cloned medium will contain exactly the
10595	same sector data as the medium being cloned, except that in the
10596	first case a new UUID for the clone will be randomly generated, and in
10597	the second case the UUID will remain unchanged.
10598
10599	The @a parent argument defines which medium will be the parent
10600	of the clone. Passing a @c null reference indicates that the clone will
10601	be a base image, i.e. completely independent. It is possible to specify
10602	an arbitrary medium for this parameter, including the parent of the
10603	medium which is being cloned. Even cloning to a child of the source
10604	medium is possible. Note that when cloning to an existing image, the
10605	@a parent irgument is ignored.
10606
10607	After the returned progress object reports that the operation is
10608	successfully complete, the target medium gets remembered by this
10609	VirtualBox installation and may be attached to virtual machines.
10610
10611	<note>
10612	This medium will be placed to <link to="MediumState_LockedRead"/>
10613	state for the duration of this operation.
10614	</note>
10615	<result name="E_NOTIMPL">
10616	The specified cloning variant is not supported at the moment.
10617	</result>
10618	</desc>
10619	<param name="target" type="IMedium" dir="in">
10620	<desc>Target medium.</desc>
10621	</param>
10622	<param name="variant" type="MediumVariant" dir="in">
10623	<desc>Exact image variant which should be created.</desc>
10624	</param>
10625	<param name="parent" type="IMedium" dir="in">
10626	<desc>Parent of the cloned medium.</desc>
10627	</param>
10628	<param name="progress" type="IProgress" dir="return">
10629	<desc>Progress object to track the operation completion.</desc>
10630	</param>
10631	</method>
10632
10633	<!-- other methods -->
10634
10635	<method name="compact">
10636	<desc>
10637	Starts compacting of this medium. This means that the medium is
10638	transformed into a possibly more compact storage representation.
10639	This potentially creates temporary images, which can require a
10640	substantial amount of additional disk space.
10641
10642	This medium will be placed to <link to="MediumState_LockedWrite"/>
10643	state and all its parent media (if any) will be placed to
10644	<link to="MediumState_LockedRead"/> state for the duration of this
10645	operation.
10646
10647	Please note that the results can be either returned straight away,
10648	or later as the result of the background operation via the object
10649	returned via the @a progress parameter.
10650
10651	<result name="VBOX_E_NOT_SUPPORTED">
10652	Medium format does not support compacting (but potentially
10653	needs it).
10654	</result>
10655	</desc>
10656	<param name="progress" type="IProgress" dir="return">
10657	<desc>Progress object to track the operation completion.</desc>
10658	</param>
10659	</method>
10660
10661	<method name="resize">
10662	<desc>
10663	Starts resizing this medium. This means that the nominal size of the
10664	medium is set to the new value. Both increasing and decreasing the
10665	size is possible, and there are no safety checks, since VirtualBox
10666	does not make any assumptions about the medium contents.
10667
10668	Resizing usually needs additional disk space, and possibly also
10669	some temporary disk space. Note that resize does not create a full
10670	temporary copy of the medium, so the additional disk space requirement
10671	is usually much lower than using the clone operation.
10672
10673	This medium will be placed to <link to="MediumState_LockedWrite"/>
10674	state for the duration of this operation.
10675
10676	Please note that the results can be either returned straight away,
10677	or later as the result of the background operation via the object
10678	returned via the @a progress parameter.
10679
10680	<result name="VBOX_E_NOT_SUPPORTED">
10681	Medium format does not support resizing.
10682	</result>
10683	</desc>
10684	<param name="logicalSize" type="unsigned long long" dir="in">
10685	<desc>New nominal capacity of the medium in megabytes.</desc>
10686	</param>
10687	<param name="progress" type="IProgress" dir="return">
10688	<desc>Progress object to track the operation completion.</desc>
10689	</param>
10690	</method>
10691
10692	<method name="reset">
10693	<desc>
10694	Starts erasing the contents of this differencing medium.
10695
10696	This operation will reset the differencing medium to its initial
10697	state when it does not contain any sector data and any read operation is
10698	redirected to its parent medium. This automatically gets called
10699	during VM power-up for every medium whose <link to="#autoReset" />
10700	attribute is @c true.
10701
10702	The medium will be write-locked for the duration of this operation (see
10703	<link to="#lockWrite" />).
10704
10705	<result name="VBOX_E_NOT_SUPPORTED">
10706	This is not a differencing medium.
10707	</result>
10708	<result name="VBOX_E_INVALID_OBJECT_STATE">
10709	Medium is not in <link to="MediumState_Created"/> or
10710	<link to="MediumState_Inaccessible"/> state.
10711	</result>
10712	</desc>
10713	<param name="progress" type="IProgress" dir="return">
10714	<desc>Progress object to track the operation completion.</desc>
10715	</param>
10716	</method>
10717
10718	</interface>
10719
10720
10721	<!--
10722	// IMediumFormat
10723	/////////////////////////////////////////////////////////////////////////
10724	-->
10725
10726	<enum
10727	name="DataType"
10728	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
10729	>
10730	<const name="Int32" value="0"/>
10731	<const name="Int8" value="1"/>
10732	<const name="String" value="2"/>
10733	</enum>
10734
10735	<enum
10736	name="DataFlags"
10737	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
10738	>
10739	<const name="None" value="0x00"/>
10740	<const name="Mandatory" value="0x01"/>
10741	<const name="Expert" value="0x02"/>
10742	<const name="Array" value="0x04"/>
10743	<const name="FlagMask" value="0x07"/>
10744	</enum>
10745
10746	<enum
10747	name="MediumFormatCapabilities"
10748	uuid="70fcf810-99e8-4edc-aee4-7f51d489e657"
10749	>
10750	<desc>
10751	Medium format capability flags.
10752	</desc>
10753
10754	<const name="Uuid" value="0x01">
10755	<desc>
10756	Supports UUIDs as expected by VirtualBox code.
10757	</desc>
10758	</const>
10759
10760	<const name="CreateFixed" value="0x02">
10761	<desc>
10762	Supports creating fixed size images, allocating all space instantly.
10763	</desc>
10764	</const>
10765
10766	<const name="CreateDynamic" value="0x04">
10767	<desc>
10768	Supports creating dynamically growing images, allocating space on
10769	demand.
10770	</desc>
10771	</const>
10772
10773	<const name="CreateSplit2G" value="0x08">
10774	<desc>
10775	Supports creating images split in chunks of a bit less than 2 GBytes.
10776	</desc>
10777	</const>
10778
10779	<const name="Differencing" value="0x10">
10780	<desc>
10781	Supports being used as a format for differencing media (see <link
10782	to="IMedium::createDiffStorage"/>).
10783	</desc>
10784	</const>
10785
10786	<const name="Asynchronous" value="0x20">
10787	<desc>
10788	Supports asynchronous I/O operations for at least some configurations.
10789	</desc>
10790	</const>
10791
10792	<const name="File" value="0x40">
10793	<desc>
10794	The format backend operates on files (the <link to="IMedium::location"/>
10795	attribute of the medium specifies a file used to store medium
10796	data; for a list of supported file extensions see
10797	<link to="IMediumFormat::fileExtensions"/>).
10798	</desc>
10799	</const>
10800
10801	<const name="Properties" value="0x80">
10802	<desc>
10803	The format backend uses the property interface to configure the storage
10804	location and properties (the <link to="IMediumFormat::describeProperties"/>
10805	method is used to get access to properties supported by the given medium format).
10806	</desc>
10807	</const>
10808
10809	<const name="CapabilityMask" value="0xFF"/>
10810	</enum>
10811
10812	<interface
10813	name="IMediumFormat" extends="$unknown"
10814	uuid="89f52554-d469-4799-9fad-1705e86a08b1"
10815	wsmap="managed"
10816	>
10817	<desc>
10818	The IMediumFormat interface represents a medium format.
10819
10820	Each medium format has an associated backend which is used to handle
10821	media stored in this format. This interface provides information
10822	about the properties of the associated backend.
10823
10824	Each medium format is identified by a string represented by the
10825	<link to="#id"/> attribute. This string is used in calls like
10826	<link to="IVirtualBox::createHardDisk"/> to specify the desired
10827	format.
10828
10829	The list of all supported medium formats can be obtained using
10830	<link to="ISystemProperties::mediaFormats"/>.
10831
10832	<see>IMedium</see>
10833	</desc>
10834
10835	<attribute name="id" type="wstring" readonly="yes">
10836	<desc>
10837	Identifier of this format.
10838
10839	The format identifier is a non-@c null non-empty ASCII string. Note that
10840	this string is case-insensitive. This means that, for example, all of
10841	the following strings:
10842	<pre>
10843	"VDI"
10844	"vdi"
10845	"VdI"</pre>
10846	refer to the same medium format.
10847
10848	This string is used in methods of other interfaces where it is necessary
10849	to specify a medium format, such as
10850	<link to="IVirtualBox::createHardDisk"/>.
10851	</desc>
10852	</attribute>
10853
10854	<attribute name="name" type="wstring" readonly="yes">
10855	<desc>
10856	Human readable description of this format.
10857
10858	Mainly for use in file open dialogs.
10859	</desc>
10860	</attribute>
10861
10862	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
10863	<desc>
10864	Array of strings containing the supported file extensions.
10865
10866	The first extension in the array is the extension preferred by the
10867	backend. It is recommended to use this extension when specifying a
10868	location of the storage unit for a new medium.
10869
10870	Note that some backends do not work on files, so this array may be
10871	empty.
10872
10873	<see>IMediumFormat::capabilities</see>
10874	</desc>
10875	</attribute>
10876
10877	<attribute name="capabilities" type="unsigned long" readonly="yes">
10878	<desc>
10879	Capabilities of the format as a set of bit flags.
10880
10881	For the meaning of individual capability flags see
10882	<link to="MediumFormatCapabilities"/>.
10883	</desc>
10884	</attribute>
10885
10886	<method name="describeProperties">
10887	<desc>
10888	Returns several arrays describing the properties supported by this
10889	format.
10890
10891	An element with the given index in each array describes one
10892	property. Thus, the number of elements in each returned array is the
10893	same and corresponds to the number of supported properties.
10894
10895	The returned arrays are filled in only if the
10896	<link to="MediumFormatCapabilities_Properties"/> flag is set.
10897	All arguments must be non-@c null.
10898
10899	<see>DataType</see>
10900	<see>DataFlags</see>
10901	</desc>
10902
10903	<param name="names" type="wstring" safearray="yes" dir="out">
10904	<desc>Array of property names.</desc>
10905	</param>
10906	<param name="description" type="wstring" safearray="yes" dir="out">
10907	<desc>Array of property descriptions.</desc>
10908	</param>
10909	<param name="types" type="DataType" safearray="yes" dir="out">
10910	<desc>Array of property types.</desc>
10911	</param>
10912	<param name="flags" type="unsigned long" safearray="yes" dir="out">
10913	<desc>Array of property flags.</desc>
10914	</param>
10915	<param name="defaults" type="wstring" safearray="yes" dir="out">
10916	<desc>Array of default property values.</desc>
10917	</param>
10918	</method>
10919
10920	</interface>
10921
10922
10923	<!--
10924	// IKeyboard
10925	/////////////////////////////////////////////////////////////////////////
10926	-->
10927
10928	<interface
10929	name="IKeyboard" extends="$unknown"
10930	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
10931	wsmap="managed"
10932	>
10933	<desc>
10934	The IKeyboard interface represents the virtual machine's keyboard. Used
10935	in <link to="IConsole::keyboard"/>.
10936
10937	Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
10938	to the virtual machine.
10939
10940	</desc>
10941	<method name="putScancode">
10942	<desc>Sends a scancode to the keyboard.
10943
10944	<result name="VBOX_E_IPRT_ERROR">
10945	Could not send scan code to virtual keyboard.
10946	</result>
10947
10948	</desc>
10949	<param name="scancode" type="long" dir="in"/>
10950	</method>
10951
10952	<method name="putScancodes">
10953	<desc>Sends an array of scancodes to the keyboard.
10954
10955	<result name="VBOX_E_IPRT_ERROR">
10956	Could not send all scan codes to virtual keyboard.
10957	</result>
10958
10959	</desc>
10960	<param name="scancodes" type="long" dir="in" safearray="yes"/>
10961	<param name="codesStored" type="unsigned long" dir="return"/>
10962	</method>
10963
10964	<method name="putCAD">
10965	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
10966	function is nothing special, it is just a convenience function
10967	calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
10968
10969	<result name="VBOX_E_IPRT_ERROR">
10970	Could not send all scan codes to virtual keyboard.
10971	</result>
10972
10973	</desc>
10974	</method>
10975
10976	</interface>
10977
10978
10979	<!--
10980	// IMouse
10981	/////////////////////////////////////////////////////////////////////////
10982	-->
10983
10984	<enum
10985	name="MouseButtonState"
10986	uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
10987	>
10988	<desc>
10989	Mouse button state.
10990	</desc>
10991
10992	<const name="LeftButton" value="0x01"/>
10993	<const name="RightButton" value="0x02"/>
10994	<const name="MiddleButton" value="0x04"/>
10995	<const name="WheelUp" value="0x08"/>
10996	<const name="WheelDown" value="0x10"/>
10997	<const name="XButton1" value="0x20"/>
10998	<const name="XButton2" value="0x40"/>
10999	<const name="MouseStateMask" value="0x7F"/>
11000	</enum>
11001
11002	<interface
11003	name="IMouse" extends="$unknown"
11004	uuid="7c0f2eae-f92d-498c-b802-e1a3763774dc"
11005	wsmap="managed"
11006	>
11007	<desc>
11008	The IMouse interface represents the virtual machine's mouse. Used in
11009	<link to="IConsole::mouse"/>.
11010
11011	Through this interface, the virtual machine's virtual mouse can be
11012	controlled.
11013	</desc>
11014
11015	<attribute name="absoluteSupported" type="boolean" readonly="yes">
11016	<desc>
11017	Whether the guest OS supports absolute mouse pointer positioning
11018	or not.
11019	<note>
11020	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
11021	callback to be instantly informed about changes of this attribute
11022	during virtual machine execution.
11023	</note>
11024	<see><link to="#putMouseEventAbsolute"/></see>
11025	</desc>
11026	</attribute>
11027
11028	<attribute name="relativeSupported" type="boolean" readonly="yes">
11029	<desc>
11030	Whether the guest OS supports relative mouse pointer positioning
11031	or not.
11032	<note>
11033	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
11034	callback to be instantly informed about changes of this attribute
11035	during virtual machine execution.
11036	</note>
11037	<see><link to="#putMouseEvent"/></see>
11038	</desc>
11039	</attribute>
11040
11041	<attribute name="needsHostCursor" type="boolean" readonly="yes">
11042	<desc>
11043	Whether the guest OS can currently switch to drawing it's own mouse
11044	cursor on demand.
11045	<note>
11046	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
11047	callback to be instantly informed about changes of this attribute
11048	during virtual machine execution.
11049	</note>
11050	<see><link to="#putMouseEvent"/></see>
11051	</desc>
11052	</attribute>
11053
11054	<method name="putMouseEvent">
11055	<desc>
11056	Initiates a mouse event using relative pointer movements
11057	along x and y axis.
11058
11059	<result name="E_ACCESSDENIED">
11060	Console not powered up.
11061	</result>
11062	<result name="VBOX_E_IPRT_ERROR">
11063	Could not send mouse event to virtual mouse.
11064	</result>
11065
11066	</desc>
11067
11068	<param name="dx" type="long" dir="in">
11069	<desc>
11070	Amount of pixels the mouse should move to the right.
11071	Negative values move the mouse to the left.
11072	</desc>
11073	</param>
11074	<param name="dy" type="long" dir="in">
11075	<desc>
11076	Amount of pixels the mouse should move downwards.
11077	Negative values move the mouse upwards.
11078	</desc>
11079	</param>
11080	<param name="dz" type="long" dir="in">
11081	<desc>
11082	Amount of mouse wheel moves.
11083	Positive values describe clockwise wheel rotations,
11084	negative values describe counterclockwise rotations.
11085	</desc>
11086	</param>
11087	<param name="dw" type="long" dir="in">
11088	<desc>
11089	Amount of horizontal mouse wheel moves.
11090	Positive values describe a movement to the left,
11091	negative values describe a movement to the right.
11092	</desc>
11093	</param>
11094	<param name="buttonState" type="long" dir="in">
11095	<desc>
11096	The current state of mouse buttons. Every bit represents
11097	a mouse button as follows:
11098	<table>
11099	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11100	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11101	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11102	</table>
11103	A value of <tt>1</tt> means the corresponding button is pressed.
11104	otherwise it is released.
11105	</desc>
11106	</param>
11107	</method>
11108
11109	<method name="putMouseEventAbsolute">
11110	<desc>
11111	Positions the mouse pointer using absolute x and y coordinates.
11112	These coordinates are expressed in pixels and
11113	start from <tt>[1,1]</tt> which corresponds to the top left
11114	corner of the virtual display.
11115
11116	<result name="E_ACCESSDENIED">
11117	Console not powered up.
11118	</result>
11119	<result name="VBOX_E_IPRT_ERROR">
11120	Could not send mouse event to virtual mouse.
11121	</result>
11122
11123	<note>
11124	This method will have effect only if absolute mouse
11125	positioning is supported by the guest OS.
11126	</note>
11127
11128	<see><link to="#absoluteSupported"/></see>
11129	</desc>
11130
11131	<param name="x" type="long" dir="in">
11132	<desc>
11133	X coordinate of the pointer in pixels, starting from @c 1.
11134	</desc>
11135	</param>
11136	<param name="y" type="long" dir="in">
11137	<desc>
11138	Y coordinate of the pointer in pixels, starting from @c 1.
11139	</desc>
11140	</param>
11141	<param name="dz" type="long" dir="in">
11142	<desc>
11143	Amount of mouse wheel moves.
11144	Positive values describe clockwise wheel rotations,
11145	negative values describe counterclockwise rotations.
11146	</desc>
11147	</param>
11148	<param name="dw" type="long" dir="in">
11149	<desc>
11150	Amount of horizontal mouse wheel moves.
11151	Positive values describe a movement to the left,
11152	negative values describe a movement to the right.
11153	</desc>
11154	</param>
11155	<param name="buttonState" type="long" dir="in">
11156	<desc>
11157	The current state of mouse buttons. Every bit represents
11158	a mouse button as follows:
11159	<table>
11160	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11161	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11162	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11163	</table>
11164	A value of @c 1 means the corresponding button is pressed.
11165	otherwise it is released.
11166	</desc>
11167	</param>
11168	</method>
11169
11170	</interface>
11171
11172	<!--
11173	// IDisplay
11174	/////////////////////////////////////////////////////////////////////////
11175	-->
11176
11177	<enum
11178	name="FramebufferPixelFormat"
11179	uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
11180	>
11181	<desc>
11182	Format of the video memory buffer. Constants represented by this enum can
11183	be used to test for particular values of <link
11184	to="IFramebuffer::pixelFormat"/>. See also <link
11185	to="IFramebuffer::requestResize"/>.
11186
11187	See also www.fourcc.org for more information about FOURCC pixel formats.
11188	</desc>
11189
11190	<const name="Opaque" value="0">
11191	<desc>
11192	Unknown buffer format (the user may not assume any particular format of
11193	the buffer).
11194	</desc>
11195	</const>
11196	<const name="FOURCC_RGB" value="0x32424752">
11197	<desc>
11198	Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
11199	bit layout).
11200	</desc>
11201	</const>
11202	</enum>
11203
11204	<interface
11205	name="IFramebuffer" extends="$unknown"
11206	uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
11207	wsmap="suppress"
11208	>
11209	<attribute name="address" type="octet" mod="ptr" readonly="yes">
11210	<desc>Address of the start byte of the frame buffer.</desc>
11211	</attribute>
11212
11213	<attribute name="width" type="unsigned long" readonly="yes">
11214	<desc>Frame buffer width, in pixels.</desc>
11215	</attribute>
11216
11217	<attribute name="height" type="unsigned long" readonly="yes">
11218	<desc>Frame buffer height, in pixels.</desc>
11219	</attribute>
11220
11221	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
11222	<desc>
11223	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
11224	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
11225	are: 8, 15, 16, 24 and 32.
11226	</desc>
11227	</attribute>
11228
11229	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
11230	<desc>
11231	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
11232	to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
11233	size of the scan line must be aligned to 32 bits.
11234	</desc>
11235	</attribute>
11236
11237	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
11238	<desc>
11239	Frame buffer pixel format. It's either one of the values defined by <link
11240	to="FramebufferPixelFormat"/> or a raw FOURCC code.
11241	<note>
11242	This attribute must never return <link
11243	to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
11244	<link to="#address"/> points to must be always known.
11245	</note>
11246	</desc>
11247	</attribute>
11248
11249	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
11250	<desc>
11251	Defines whether this frame buffer uses the virtual video card's memory
11252	buffer (guest VRAM) directly or not. See <link
11253	to="IFramebuffer::requestResize"/> for more information.
11254	</desc>
11255	</attribute>
11256
11257	<attribute name="heightReduction" type="unsigned long" readonly="yes">
11258	<desc>
11259	Hint from the frame buffer about how much of the standard
11260	screen height it wants to use for itself. This information is
11261	exposed to the guest through the VESA BIOS and VMMDev interface
11262	so that it can use it for determining its video mode table. It
11263	is not guaranteed that the guest respects the value.
11264	</desc>
11265	</attribute>
11266
11267	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
11268	<desc>
11269	An alpha-blended overlay which is superposed over the frame buffer.
11270	The initial purpose is to allow the display of icons providing
11271	information about the VM state, including disk activity, in front
11272	ends which do not have other means of doing that. The overlay is
11273	designed to controlled exclusively by IDisplay. It has no locking
11274	of its own, and any changes made to it are not guaranteed to be
11275	visible until the affected portion of IFramebuffer is updated. The
11276	overlay can be created lazily the first time it is requested. This
11277	attribute can also return @c null to signal that the overlay is not
11278	implemented.
11279	</desc>
11280	</attribute>
11281
11282	<attribute name="winId" type="unsigned long long" readonly="yes">
11283	<desc>
11284	Platform-dependent identifier of the window where context of this
11285	frame buffer is drawn, or zero if there's no such window.
11286	</desc>
11287	</attribute>
11288
11289	<method name="lock">
11290	<desc>
11291	Locks the frame buffer.
11292	Gets called by the IDisplay object where this frame buffer is
11293	bound to.
11294	</desc>
11295	</method>
11296
11297	<method name="unlock">
11298	<desc>
11299	Unlocks the frame buffer.
11300	Gets called by the IDisplay object where this frame buffer is
11301	bound to.
11302	</desc>
11303	</method>
11304
11305	<method name="notifyUpdate">
11306	<desc>
11307	Informs about an update.
11308	Gets called by the display object where this buffer is
11309	registered.
11310	</desc>
11311	<param name="x" type="unsigned long" dir="in"/>
11312	<param name="y" type="unsigned long" dir="in"/>
11313	<param name="width" type="unsigned long" dir="in"/>
11314	<param name="height" type="unsigned long" dir="in"/>
11315	</method>
11316
11317	<method name="requestResize">
11318	<desc>
11319	Requests a size and pixel format change.
11320
11321	There are two modes of working with the video buffer of the virtual
11322	machine. The <i>indirect</i> mode implies that the IFramebuffer
11323	implementation allocates a memory buffer for the requested display mode
11324	and provides it to the virtual machine. In <i>direct</i> mode, the
11325	IFramebuffer implementation uses the memory buffer allocated and owned
11326	by the virtual machine. This buffer represents the video memory of the
11327	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
11328	usually faster because the implementation gets a raw pointer to the
11329	guest VRAM buffer which it can directly use for visualizing the contents
11330	of the virtual display, as opposed to the indirect mode where the
11331	contents of guest VRAM are copied to the memory buffer provided by
11332	the implementation every time a display update occurs.
11333
11334	It is important to note that the direct mode is really fast only when
11335	the implementation uses the given guest VRAM buffer directly, for
11336	example, by blitting it to the window representing the virtual machine's
11337	display, which saves at least one copy operation comparing to the
11338	indirect mode. However, using the guest VRAM buffer directly is not
11339	always possible: the format and the color depth of this buffer may be
11340	not supported by the target window, or it may be unknown (opaque) as in
11341	case of text or non-linear multi-plane VGA video modes. In this case,
11342	the indirect mode (that is always available) should be used as a
11343	fallback: when the guest VRAM contents are copied to the
11344	implementation-provided memory buffer, color and format conversion is
11345	done automatically by the underlying code.
11346
11347	The @a pixelFormat parameter defines whether the direct mode is
11348	available or not. If @a pixelFormat is <link
11349	to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
11350	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
11351	@a bytesPerLine parameters must be ignored and the implementation must use
11352	the indirect mode (where it provides its own buffer in one of the
11353	supported formats). In all other cases, @a pixelFormat together with
11354	@a bitsPerPixel and @a bytesPerLine define the format of the video memory
11355	buffer pointed to by the @a VRAM parameter and the implementation is
11356	free to choose which mode to use. To indicate that this frame buffer uses
11357	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
11358	attribute must return @c true and <link to="#address"/> must
11359	return exactly the same address that is passed in the @a VRAM parameter
11360	of this method; otherwise it is assumed that the indirect strategy is
11361	chosen.
11362
11363	The @a width and @a height parameters represent the size of the
11364	requested display mode in both modes. In case of indirect mode, the
11365	provided memory buffer should be big enough to store data of the given
11366	display mode. In case of direct mode, it is guaranteed that the given
11367	@a VRAM buffer contains enough space to represent the display mode of the
11368	given size. Note that this frame buffer's <link to="#width"/> and <link
11369	to="#height"/> attributes must return exactly the same values as
11370	passed to this method after the resize is completed (see below).
11371
11372	The @a finished output parameter determines if the implementation has
11373	finished resizing the frame buffer or not. If, for some reason, the
11374	resize cannot be finished immediately during this call, @a finished
11375	must be set to @c false, and the implementation must call
11376	<link to="IDisplay::resizeCompleted"/> after it has returned from
11377	this method as soon as possible. If @a finished is @c false, the
11378	machine will not call any frame buffer methods until
11379	<link to="IDisplay::resizeCompleted"/> is called.
11380
11381	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
11382	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
11383	this frame buffer must return exactly the same values as specified in the
11384	parameters of this method, after the resize is completed. If the
11385	indirect mode is chosen, these attributes must return values describing
11386	the format of the implementation's own memory buffer <link
11387	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
11388	value must always correlate with <link to="#pixelFormat"/>. Note that
11389	the <link to="#pixelFormat"/> attribute must never return <link
11390	to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
11391
11392	<note>
11393	This method is called by the IDisplay object under the
11394	<link to="#lock"/> provided by this IFramebuffer
11395	implementation. If this method returns @c false in @a finished, then
11396	this lock is not released until
11397	<link to="IDisplay::resizeCompleted"/> is called.
11398	</note>
11399	</desc>
11400	<param name="screenId" type="unsigned long" dir="in">
11401	<desc>
11402	Logical screen number. Must be used in the corresponding call to
11403	<link to="IDisplay::resizeCompleted"/> if this call is made.
11404	</desc>
11405	</param>
11406	<param name="pixelFormat" type="unsigned long" dir="in">
11407	<desc>
11408	Pixel format of the memory buffer pointed to by @a VRAM.
11409	See also <link to="FramebufferPixelFormat"/>.
11410	</desc>
11411	</param>
11412	<param name="VRAM" type="octet" mod="ptr" dir="in">
11413	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
11414	</param>
11415	<param name="bitsPerPixel" type="unsigned long" dir="in">
11416	<desc>Color depth, bits per pixel.</desc>
11417	</param>
11418	<param name="bytesPerLine" type="unsigned long" dir="in">
11419	<desc>Size of one scan line, in bytes.</desc>
11420	</param>
11421	<param name="width" type="unsigned long" dir="in">
11422	<desc>Width of the guest display, in pixels.</desc>
11423	</param>
11424	<param name="height" type="unsigned long" dir="in">
11425	<desc>Height of the guest display, in pixels.</desc>
11426	</param>
11427	<param name="finished" type="boolean" dir="return">
11428	<desc>
11429	Can the VM start using the new frame buffer immediately
11430	after this method returns or it should wait for
11431	<link to="IDisplay::resizeCompleted"/>.
11432	</desc>
11433	</param>
11434	</method>
11435
11436	<method name="videoModeSupported">
11437	<desc>
11438	Returns whether the frame buffer implementation is willing to
11439	support a given video mode. In case it is not able to render
11440	the video mode (or for some reason not willing), it should
11441	return @c false. Usually this method is called when the guest
11442	asks the VMM device whether a given video mode is supported
11443	so the information returned is directly exposed to the guest.
11444	It is important that this method returns very quickly.
11445	</desc>
11446	<param name="width" type="unsigned long" dir="in"/>
11447	<param name="height" type="unsigned long" dir="in"/>
11448	<param name="bpp" type="unsigned long" dir="in"/>
11449	<param name="supported" type="boolean" dir="return"/>
11450	</method>
11451
11452	<method name="getVisibleRegion">
11453	<desc>
11454	Returns the visible region of this frame buffer.
11455
11456	If the @a rectangles parameter is @c null then the value of the
11457	@a count parameter is ignored and the number of elements necessary to
11458	describe the current visible region is returned in @a countCopied.
11459
11460	If @a rectangles is not @c null but @a count is less
11461	than the required number of elements to store region data, the method
11462	will report a failure. If @a count is equal or greater than the
11463	required number of elements, then the actual number of elements copied
11464	to the provided array will be returned in @a countCopied.
11465
11466	<note>
11467	The address of the provided array must be in the process space of
11468	this IFramebuffer object.
11469	</note>
11470	<note>
11471	Method not yet implemented.
11472	</note>
11473	</desc>
11474	<param name="rectangles" type="octet" mod="ptr" dir="in">
11475	<desc>Pointer to the @c RTRECT array to receive region data.</desc>
11476	</param>
11477	<param name="count" type="unsigned long" dir="in">
11478	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11479	</param>
11480	<param name="countCopied" type="unsigned long" dir="return">
11481	<desc>Number of elements copied to the @a rectangles array.</desc>
11482	</param>
11483	</method>
11484
11485	<method name="setVisibleRegion">
11486	<desc>
11487	Suggests a new visible region to this frame buffer. This region
11488	represents the area of the VM display which is a union of regions of
11489	all top-level windows of the guest operating system running inside the
11490	VM (if the Guest Additions for this system support this
11491	functionality). This information may be used by the frontends to
11492	implement the seamless desktop integration feature.
11493
11494	<note>
11495	The address of the provided array must be in the process space of
11496	this IFramebuffer object.
11497	</note>
11498	<note>
11499	The IFramebuffer implementation must make a copy of the provided
11500	array of rectangles.
11501	</note>
11502	<note>
11503	Method not yet implemented.
11504	</note>
11505	</desc>
11506	<param name="rectangles" type="octet" mod="ptr" dir="in">
11507	<desc>Pointer to the @c RTRECT array.</desc>
11508	</param>
11509	<param name="count" type="unsigned long" dir="in">
11510	<desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
11511	</param>
11512	</method>
11513
11514	<method name="processVHWACommand">
11515	<desc>
11516	Posts a Video HW Acceleration Command to the frame buffer for processing.
11517	The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color covnersion, overlaying, etc.)
11518	are posted from quest to the host to be processed by the host hardware.
11519
11520	<note>
11521	The address of the provided command must be in the process space of
11522	this IFramebuffer object.
11523	</note>
11524	</desc>
11525
11526	<param name="command" type="octet" mod="ptr" dir="in">
11527	<desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
11528	</param>
11529	</method>
11530
11531	</interface>
11532
11533	<interface
11534	name="IFramebufferOverlay" extends="IFramebuffer"
11535	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
11536	wsmap="suppress"
11537	>
11538	<desc>
11539	The IFramebufferOverlay interface represents an alpha blended overlay
11540	for displaying status icons above an IFramebuffer. It is always created
11541	not visible, so that it must be explicitly shown. It only covers a
11542	portion of the IFramebuffer, determined by its width, height and
11543	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
11544	that order) format, and may be written to directly. Do re-read the
11545	width though, after setting it, as it may be adjusted (increased) to
11546	make it more suitable for the front end.
11547	</desc>
11548	<attribute name="x" type="unsigned long" readonly="yes">
11549	<desc>X position of the overlay, relative to the frame buffer.</desc>
11550	</attribute>
11551
11552	<attribute name="y" type="unsigned long" readonly="yes">
11553	<desc>Y position of the overlay, relative to the frame buffer.</desc>
11554	</attribute>
11555
11556	<attribute name="visible" type="boolean" readonly="no">
11557	<desc>
11558	Whether the overlay is currently visible.
11559	</desc>
11560	</attribute>
11561
11562	<attribute name="alpha" type="unsigned long" readonly="no">
11563	<desc>
11564	The global alpha value for the overlay. This may or may not be
11565	supported by a given front end.
11566	</desc>
11567	</attribute>
11568
11569	<method name="move">
11570	<desc>
11571	Changes the overlay's position relative to the IFramebuffer.
11572	</desc>
11573	<param name="x" type="unsigned long" dir="in"/>
11574	<param name="y" type="unsigned long" dir="in"/>
11575	</method>
11576
11577	</interface>
11578
11579	<interface
11580	name="IDisplay" extends="$unknown"
11581	uuid="1fa79e39-0cc9-4ab3-9df3-ed3e96b42496"
11582	wsmap="managed"
11583	>
11584	<desc>
11585	The IDisplay interface represents the virtual machine's display.
11586
11587	The object implementing this interface is contained in each
11588	<link to="IConsole::display"/> attribute and represents the visual
11589	output of the virtual machine.
11590
11591	The virtual display supports pluggable output targets represented by the
11592	IFramebuffer interface. Examples of the output target are a window on
11593	the host computer or an RDP session's display on a remote computer.
11594	</desc>
11595	<method name="getScreenResolution">
11596	<desc>Queries display width, height and color depth for given screen.</desc>
11597	<param name="screenId" type="unsigned long" dir="in"/>
11598	<param name="width" type="unsigned long" dir="out"/>
11599	<param name="height" type="unsigned long" dir="out"/>
11600	<param name="bitsPerPixel" type="unsigned long" dir="out"/>
11601	</method>
11602
11603	<method name="setFramebuffer">
11604	<desc>
11605	Sets the framebuffer for given screen.
11606	</desc>
11607	<param name="screenId" type="unsigned long" dir="in"/>
11608	<param name="framebuffer" type="IFramebuffer" dir="in"/>
11609	</method>
11610
11611	<method name="getFramebuffer">
11612	<desc>
11613	Queries the framebuffer for given screen.
11614	</desc>
11615	<param name="screenId" type="unsigned long" dir="in"/>
11616	<param name="framebuffer" type="IFramebuffer" dir="out"/>
11617	<param name="xOrigin" type="long" dir="out"/>
11618	<param name="yOrigin" type="long" dir="out"/>
11619	</method>
11620
11621	<method name="setVideoModeHint">
11622	<desc>
11623	Asks VirtualBox to request the given video mode from
11624	the guest. This is just a hint and it cannot be guaranteed
11625	that the requested resolution will be used. Guest Additions
11626	are required for the request to be seen by guests. The caller
11627	should issue the request and wait for a resolution change and
11628	after a timeout retry.
11629
11630	Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
11631	parameters means that the corresponding values should be taken from the
11632	current video mode (i.e. left unchanged).
11633
11634	If the guest OS supports multi-monitor configuration then the @a display
11635	parameter specifies the number of the guest display to send the hint to:
11636	@c 0 is the primary display, @c 1 is the first secondary and
11637	so on. If the multi-monitor configuration is not supported, @a display
11638	must be @c 0.
11639
11640	<result name="E_INVALIDARG">
11641	The @a display is not associated with any monitor.
11642	</result>
11643
11644	</desc>
11645	<param name="width" type="unsigned long" dir="in"/>
11646	<param name="height" type="unsigned long" dir="in"/>
11647	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
11648	<param name="display" type="unsigned long" dir="in"/>
11649	</method>
11650
11651	<method name="setSeamlessMode">
11652	<desc>
11653	Enables or disables seamless guest display rendering (seamless desktop
11654	integration) mode.
11655	<note>
11656	Calling this method has no effect if <link
11657	to="IGuest::supportsSeamless"/> returns @c false.
11658	</note>
11659	</desc>
11660	<param name="enabled" type="boolean" dir="in"/>
11661	</method>
11662
11663	<method name="takeScreenShot">
11664	<desc>
11665	Takes a screen shot of the requested size and copies it to the
11666	32-bpp buffer allocated by the caller and pointed to by @a address.
11667	A pixel consists of 4 bytes in order: B, G, R, 0.
11668
11669	<note>This API can be used only by the COM/XPCOM C++ API as it
11670	requires pointer support. Use <link to="#takeScreenShotToArray" />
11671	with other language bindings.
11672	</note>
11673
11674	<result name="E_NOTIMPL">
11675	Feature not implemented.
11676	</result>
11677	<result name="VBOX_E_IPRT_ERROR">
11678	Could not take a screenshot.
11679	</result>
11680
11681	</desc>
11682	<param name="screenId" type="unsigned long" dir="in"/>
11683	<param name="address" type="octet" mod="ptr" dir="in"/>
11684	<param name="width" type="unsigned long" dir="in"/>
11685	<param name="height" type="unsigned long" dir="in"/>
11686	</method>
11687
11688	<method name="takeScreenShotToArray">
11689	<desc>
11690	Takes a guest screen shot of the requested size and returns it as
11691	an array of bytes in uncompressed 32-bit RGBA format.
11692	A pixel consists of 4 bytes in order: R, G, B, 0xFF.
11693
11694	This API is slow, but could be the only option to get guest screenshot
11695	for scriptable languages not allowed to manipulate with addresses
11696	directly.
11697
11698	<result name="E_NOTIMPL">
11699	Feature not implemented.
11700	</result>
11701	<result name="VBOX_E_IPRT_ERROR">
11702	Could not take a screenshot.
11703	</result>
11704	</desc>
11705	<param name="screenId" type="unsigned long" dir="in">
11706	<desc>
11707	Monitor to take screenshot from.
11708	</desc>
11709	</param>
11710	<param name="width" type="unsigned long" dir="in">
11711	<desc>
11712	Desired image width.
11713	</desc>
11714	</param>
11715	<param name="height" type="unsigned long" dir="in">
11716	<desc>
11717	Desired image height.
11718	</desc>
11719	</param>
11720	<param name="screenData" type="octet" dir="return" safearray="yes">
11721	<desc>
11722	Array with resulting screen data.
11723	</desc>
11724	</param>
11725	</method>
11726
11727	<method name="drawToScreen">
11728	<desc>
11729	Draws a 32-bpp image of the specified size from the given buffer
11730	to the given point on the VM display.
11731
11732	<result name="E_NOTIMPL">
11733	Feature not implemented.
11734	</result>
11735	<result name="VBOX_E_IPRT_ERROR">
11736	Could not draw to screen.
11737	</result>
11738
11739	</desc>
11740	<param name="screenId" type="unsigned long" dir="in"/>
11741	<param name="address" type="octet" mod="ptr" dir="in"/>
11742	<param name="x" type="unsigned long" dir="in">
11743	<desc>Relative to the screen top left corner.</desc>
11744	</param>
11745	<param name="y" type="unsigned long" dir="in">
11746	<desc>Relative to the screen top left corner.</desc>
11747	</param>
11748	<param name="width" type="unsigned long" dir="in"/>
11749	<param name="height" type="unsigned long" dir="in"/>
11750	</method>
11751
11752	<method name="invalidateAndUpdate">
11753	<desc>
11754	Does a full invalidation of the VM display and instructs the VM
11755	to update it.
11756
11757	<result name="VBOX_E_IPRT_ERROR">
11758	Could not invalidate and update screen.
11759	</result>
11760
11761	</desc>
11762	</method>
11763
11764	<method name="resizeCompleted">
11765	<desc>
11766	Signals that a framebuffer has completed the resize operation.
11767
11768	<result name="VBOX_E_NOT_SUPPORTED">
11769	Operation only valid for external frame buffers.
11770	</result>
11771
11772	</desc>
11773	<param name="screenId" type="unsigned long" dir="in"/>
11774	</method>
11775
11776	<method name="completeVHWACommand">
11777	<desc>
11778	Signals that the Video HW Acceleration command has completed.
11779	</desc>
11780
11781	<param name="command" type="octet" mod="ptr" dir="in">
11782	<desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
11783	</param>
11784	</method>
11785
11786	</interface>
11787
11788	<!--
11789	// INetworkAdapter
11790	/////////////////////////////////////////////////////////////////////////
11791	-->
11792
11793	<enum
11794	name="NetworkAttachmentType"
11795	uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
11796	>
11797	<desc>
11798	Network attachment type.
11799	</desc>
11800
11801	<const name="Null" value="0">
11802	<desc>Null value, also means "not attached".</desc>
11803	</const>
11804	<const name="NAT" value="1"/>
11805	<const name="Bridged" value="2"/>
11806	<const name="Internal" value="3"/>
11807	<const name="HostOnly" value="4"/>
11808	<const name="VDE" value="5"/>
11809	</enum>
11810
11811	<enum
11812	name="NetworkAdapterType"
11813	uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
11814	>
11815	<desc>
11816	Network adapter type.
11817	</desc>
11818
11819	<const name="Null" value="0">
11820	<desc>Null value (never used by the API).</desc>
11821	</const>
11822	<const name="Am79C970A" value="1">
11823	<desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
11824	</const>
11825	<const name="Am79C973" value="2">
11826	<desc>AMD PCNet-FAST III network card (Am79C973).</desc>
11827	</const>
11828	<const name="I82540EM" value="3">
11829	<desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
11830	</const>
11831	<const name="I82543GC" value="4">
11832	<desc>Intel PRO/1000 T Server network card (82543GC).</desc>
11833	</const>
11834	<const name="I82545EM" value="5">
11835	<desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
11836	</const>
11837	<const name="Virtio" value="6">
11838	<desc>Virtio network device.</desc>
11839	</const>
11840	</enum>
11841
11842	<interface
11843	name="INetworkAdapter" extends="$unknown"
11844	uuid="5bdb9df8-a5e1-4322-a139-b7a4a734c790"
11845	wsmap="managed"
11846	>
11847	<desc>
11848	Represents a virtual network adapter that is attached to a virtual machine.
11849	Each virtual machine has a fixed number of network adapter slots with one
11850	instance of this attached to each of them. Call
11851	<link to="IMachine::getNetworkAdapter" /> to get the network adapter that
11852	is attached to a given slot in a given machine.
11853
11854	Each network adapter can be in one of five attachment modes, which are
11855	represented by the <link to="NetworkAttachmentType" /> enumeration;
11856	see the <link to="#attachmentType" /> attribute.
11857	</desc>
11858
11859	<attribute name="adapterType" type="NetworkAdapterType">
11860	<desc>
11861	Type of the virtual network adapter. Depending on this value,
11862	VirtualBox will provide a different virtual network hardware
11863	to the guest.
11864	</desc>
11865	</attribute>
11866
11867	<attribute name="slot" type="unsigned long" readonly="yes">
11868	<desc>
11869	Slot number this adapter is plugged into. Corresponds to
11870	the value you pass to <link to="IMachine::getNetworkAdapter"/>
11871	to obtain this instance.
11872	</desc>
11873	</attribute>
11874
11875	<attribute name="enabled" type="boolean">
11876	<desc>
11877	Flag whether the network adapter is present in the
11878	guest system. If disabled, the virtual guest hardware will
11879	not contain this network adapter. Can only be changed when
11880	the VM is not running.
11881	</desc>
11882	</attribute>
11883
11884	<attribute name="MACAddress" type="wstring">
11885	<desc>
11886	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
11887	it to @c null or an empty string, VirtualBox will generate a unique MAC address.
11888	</desc>
11889	</attribute>
11890
11891	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
11892
11893	<attribute name="hostInterface" type="wstring">
11894	<desc>
11895	Name of the host network interface the VM is attached to.
11896	</desc>
11897	</attribute>
11898
11899	<attribute name="internalNetwork" type="wstring">
11900	<desc>
11901	Name of the internal network the VM is attached to.
11902	</desc>
11903	</attribute>
11904
11905	<attribute name="NATNetwork" type="wstring">
11906	<desc>
11907	Name of the NAT network the VM is attached to.
11908	</desc>
11909	</attribute>
11910
11911	<attribute name="VDENetwork" type="wstring">
11912	<desc>
11913	Name of the VDE switch the VM is attached to.
11914	</desc>
11915	</attribute>
11916
11917	<attribute name="cableConnected" type="boolean">
11918	<desc>
11919	Flag whether the adapter reports the cable as connected or not.
11920	It can be used to report offline situations to a VM.
11921	</desc>
11922	</attribute>
11923
11924	<attribute name="lineSpeed" type="unsigned long">
11925	<desc>
11926	Line speed reported by custom drivers, in units of 1 kbps.
11927	</desc>
11928	</attribute>
11929
11930	<attribute name="traceEnabled" type="boolean">
11931	<desc>
11932	Flag whether network traffic from/to the network card should be traced.
11933	Can only be toggled when the VM is turned off.
11934	</desc>
11935	</attribute>
11936
11937	<attribute name="traceFile" type="wstring">
11938	<desc>
11939	Filename where a network trace will be stored. If not set, VBox-pid.pcap
11940	will be used.
11941	</desc>
11942	</attribute>
11943
11944	<attribute name="natDriver" type="INATEngine" readonly="yes">
11945	<desc>
11946	Points to the NAT engine which handles the network address translation
11947	for this interface. This is active only when the interface actually uses
11948	NAT (see <link to="#attachToNAT" />).
11949	</desc>
11950	</attribute>
11951
11952	<attribute name="bootPriority" type="unsigned long">
11953	<desc>
11954	Network boot priority of the adapter. Priority 1 is highest. If not set,
11955	the priority is considered to be at the lowest possible setting.
11956	</desc>
11957	</attribute>
11958
11959	<method name="attachToNAT">
11960	<desc>
11961	Attach the network adapter to the Network Address Translation (NAT) interface.
11962	</desc>
11963	</method>
11964
11965	<method name="attachToBridgedInterface">
11966	<desc>
11967	Attach the network adapter to a bridged host interface.
11968	</desc>
11969	</method>
11970
11971	<method name="attachToInternalNetwork">
11972	<desc>
11973	Attach the network adapter to an internal network.
11974	</desc>
11975	</method>
11976
11977	<method name="attachToHostOnlyInterface">
11978	<desc>
11979	Attach the network adapter to the host-only network.
11980	</desc>
11981	</method>
11982
11983	<method name="attachToVDE">
11984	<desc>
11985	Attach the network adapter to a VDE network.
11986	</desc>
11987	</method>
11988
11989	<method name="detach">
11990	<desc>
11991	Detach the network adapter
11992	</desc>
11993	</method>
11994	</interface>
11995
11996
11997	<!--
11998	// ISerialPort
11999	/////////////////////////////////////////////////////////////////////////
12000	-->
12001
12002	<enum
12003	name="PortMode"
12004	uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
12005	>
12006	<desc>
12007	The PortMode enumeration represents possible communication modes for
12008	the virtual serial port device.
12009	</desc>
12010
12011	<const name="Disconnected" value="0">
12012	<desc>Virtual device is not attached to any real host device.</desc>
12013	</const>
12014	<const name="HostPipe" value="1">
12015	<desc>Virtual device is attached to a host pipe.</desc>
12016	</const>
12017	<const name="HostDevice" value="2">
12018	<desc>Virtual device is attached to a host device.</desc>
12019	</const>
12020	<const name="RawFile" value="3">
12021	<desc>Virtual device is attached to a raw file.</desc>
12022	</const>
12023	</enum>
12024
12025	<interface
12026	name="ISerialPort" extends="$unknown"
12027	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
12028	wsmap="managed"
12029	>
12030
12031	<desc>
12032	The ISerialPort interface represents the virtual serial port device.
12033
12034	The virtual serial port device acts like an ordinary serial port
12035	inside the virtual machine. This device communicates to the real
12036	serial port hardware in one of two modes: host pipe or host device.
12037
12038	In host pipe mode, the #path attribute specifies the path to the pipe on
12039	the host computer that represents a serial port. The #server attribute
12040	determines if this pipe is created by the virtual machine process at
12041	machine startup or it must already exist before starting machine
12042	execution.
12043
12044	In host device mode, the #path attribute specifies the name of the
12045	serial port device on the host computer.
12046
12047	There is also a third communication mode: the disconnected mode. In this
12048	mode, the guest OS running inside the virtual machine will be able to
12049	detect the serial port, but all port write operations will be discarded
12050	and all port read operations will return no data.
12051
12052	<see>IMachine::getSerialPort</see>
12053	</desc>
12054
12055	<attribute name="slot" type="unsigned long" readonly="yes">
12056	<desc>
12057	Slot number this serial port is plugged into. Corresponds to
12058	the value you pass to <link to="IMachine::getSerialPort"/>
12059	to obtain this instance.
12060	</desc>
12061	</attribute>
12062
12063	<attribute name="enabled" type="boolean">
12064	<desc>
12065	Flag whether the serial port is enabled. If disabled,
12066	the serial port will not be reported to the guest OS.
12067	</desc>
12068	</attribute>
12069
12070	<attribute name="IOBase" type="unsigned long">
12071	<desc>Base I/O address of the serial port.</desc>
12072	</attribute>
12073
12074	<attribute name="IRQ" type="unsigned long">
12075	<desc>IRQ number of the serial port.</desc>
12076	</attribute>
12077
12078	<attribute name="hostMode" type="PortMode">
12079	<desc>
12080	How is this port connected to the host.
12081	<note>
12082	Changing this attribute may fail if the conditions for
12083	<link to="#path"/> are not met.
12084	</note>
12085	</desc>
12086	</attribute>
12087
12088	<attribute name="server" type="boolean">
12089	<desc>
12090	Flag whether this serial port acts as a server (creates a new pipe on
12091	the host) or as a client (uses the existing pipe). This attribute is
12092	used only when <link to="#hostMode"/> is PortMode_HostPipe.
12093	</desc>
12094	</attribute>
12095
12096	<attribute name="path" type="wstring">
12097	<desc>
12098	Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
12099	PortMode_HostPipe, or the host serial device name when
12100	<link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
12101	cases, setting a @c null or empty string as the attribute's value
12102	is an error. Otherwise, the value of this property is ignored.
12103	</desc>
12104	</attribute>
12105
12106	</interface>
12107
12108	<!--
12109	// IParallelPort
12110	/////////////////////////////////////////////////////////////////////////
12111	-->
12112
12113	<interface
12114	name="IParallelPort" extends="$unknown"
12115	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
12116	wsmap="managed"
12117	>
12118
12119	<desc>
12120	The IParallelPort interface represents the virtual parallel port device.
12121
12122	The virtual parallel port device acts like an ordinary parallel port
12123	inside the virtual machine. This device communicates to the real
12124	parallel port hardware using the name of the parallel device on the host
12125	computer specified in the #path attribute.
12126
12127	Each virtual parallel port device is assigned a base I/O address and an
12128	IRQ number that will be reported to the guest operating system and used
12129	to operate the given parallel port from within the virtual machine.
12130
12131	<see>IMachine::getParallelPort</see>
12132	</desc>
12133
12134	<attribute name="slot" type="unsigned long" readonly="yes">
12135	<desc>
12136	Slot number this parallel port is plugged into. Corresponds to
12137	the value you pass to <link to="IMachine::getParallelPort"/>
12138	to obtain this instance.
12139	</desc>
12140	</attribute>
12141
12142	<attribute name="enabled" type="boolean">
12143	<desc>
12144	Flag whether the parallel port is enabled. If disabled,
12145	the parallel port will not be reported to the guest OS.
12146	</desc>
12147	</attribute>
12148
12149	<attribute name="IOBase" type="unsigned long">
12150	<desc>Base I/O address of the parallel port.</desc>
12151	</attribute>
12152
12153	<attribute name="IRQ" type="unsigned long">
12154	<desc>IRQ number of the parallel port.</desc>
12155	</attribute>
12156
12157	<attribute name="path" type="wstring">
12158	<desc>
12159	Host parallel device name. If this parallel port is enabled, setting a
12160	@c null or an empty string as this attribute's value will result into
12161	an error.
12162	</desc>
12163	</attribute>
12164
12165	</interface>
12166
12167
12168	<!--
12169	// IMachineDebugger
12170	/////////////////////////////////////////////////////////////////////////
12171	-->
12172
12173	<interface
12174	name="IMachineDebugger" extends="$unknown"
12175	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
12176	wsmap="suppress"
12177	>
12178	<method name="resetStats">
12179	<desc>
12180	Reset VM statistics.
12181	</desc>
12182	<param name="pattern" type="wstring" dir="in">
12183	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12184	</param>
12185	</method>
12186
12187	<method name="dumpStats">
12188	<desc>
12189	Dumps VM statistics.
12190	</desc>
12191	<param name="pattern" type="wstring" dir="in">
12192	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12193	</param>
12194	</method>
12195
12196	<method name="getStats">
12197	<desc>
12198	Get the VM statistics in a XMLish format.
12199	</desc>
12200	<param name="pattern" type="wstring" dir="in">
12201	<desc>The selection pattern. A bit similar to filename globbing.</desc>
12202	</param>
12203	<param name="withDescriptions" type="boolean" dir="in">
12204	<desc>Whether to include the descriptions.</desc>
12205	</param>
12206	<param name="stats" type="wstring" dir="out">
12207	<desc>The XML document containing the statistics.</desc>
12208	</param>
12209	</method>
12210
12211	<method name="injectNMI">
12212	<desc>
12213	Inject an NMI into a running VT-x/AMD-V VM.
12214	</desc>
12215	</method>
12216
12217	<attribute name="singlestep" type="boolean">
12218	<desc>Switch for enabling singlestepping.</desc>
12219	</attribute>
12220
12221	<attribute name="recompileUser" type="boolean">
12222	<desc>Switch for forcing code recompilation for user mode code.</desc>
12223	</attribute>
12224
12225	<attribute name="recompileSupervisor" type="boolean">
12226	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
12227	</attribute>
12228
12229	<attribute name="PATMEnabled" type="boolean">
12230	<desc>Switch for enabling and disabling the PATM component.</desc>
12231	</attribute>
12232
12233	<attribute name="CSAMEnabled" type="boolean">
12234	<desc>Switch for enabling and disabling the CSAM component.</desc>
12235	</attribute>
12236
12237	<attribute name="logEnabled" type="boolean">
12238	<desc>Switch for enabling and disabling logging.</desc>
12239	</attribute>
12240
12241	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
12242	<desc>
12243	Flag indicating whether the VM is currently making use of CPU hardware
12244	virtualization extensions.
12245	</desc>
12246	</attribute>
12247
12248	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
12249	<desc>
12250	Flag indicating whether the VM is currently making use of the nested paging
12251	CPU hardware virtualization extension.
12252	</desc>
12253	</attribute>
12254
12255	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
12256	<desc>
12257	Flag indicating whether the VM is currently making use of the VPID
12258	VT-x extension.
12259	</desc>
12260	</attribute>
12261
12262	<attribute name="PAEEnabled" type="boolean" readonly="yes">
12263	<desc>
12264	Flag indicating whether the VM is currently making use of the Physical
12265	Address Extension CPU feature.
12266	</desc>
12267	</attribute>
12268
12269	<attribute name="virtualTimeRate" type="unsigned long">
12270	<desc>
12271	The rate at which the virtual time runs expressed as a percentage.
12272	The accepted range is 2% to 20000%.
12273	</desc>
12274	</attribute>
12275
12276	<!-- @todo method for setting log flags, groups and destination! -->
12277
12278	<attribute name="VM" type="unsigned long long" readonly="yes">
12279	<desc>
12280	Gets the VM handle. This is only for internal use while
12281	we carve the details of this interface.
12282	</desc>
12283	</attribute>
12284
12285	</interface>
12286
12287	<!--
12288	// IUSBController
12289	/////////////////////////////////////////////////////////////////////////
12290	-->
12291
12292	<interface
12293	name="IUSBController" extends="$unknown"
12294	uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
12295	wsmap="managed"
12296	>
12297	<attribute name="enabled" type="boolean">
12298	<desc>
12299	Flag whether the USB controller is present in the
12300	guest system. If disabled, the virtual guest hardware will
12301	not contain any USB controller. Can only be changed when
12302	the VM is powered off.
12303	</desc>
12304	</attribute>
12305
12306	<attribute name="enabledEhci" type="boolean">
12307	<desc>
12308	Flag whether the USB EHCI controller is present in the
12309	guest system. If disabled, the virtual guest hardware will
12310	not contain a USB EHCI controller. Can only be changed when
12311	the VM is powered off.
12312	</desc>
12313	</attribute>
12314
12315	<attribute name="proxyAvailable" type="boolean" readonly="yes">
12316	<desc>
12317	Flag whether there is an USB proxy available.
12318	</desc>
12319	</attribute>
12320
12321	<attribute name="USBStandard" type="unsigned short" readonly="yes">
12322	<desc>
12323	USB standard version which the controller implements.
12324	This is a BCD which means that the major version is in the
12325	high byte and minor version is in the low byte.
12326	</desc>
12327	</attribute>
12328
12329	<attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
12330	<desc>
12331	List of USB device filters associated with the machine.
12332
12333	If the machine is currently running, these filters are activated
12334	every time a new (supported) USB device is attached to the host
12335	computer that was not ignored by global filters
12336	(<link to="IHost::USBDeviceFilters"/>).
12337
12338	These filters are also activated when the machine is powered up.
12339	They are run against a list of all currently available USB
12340	devices (in states
12341	<link to="USBDeviceState_Available"/>,
12342	<link to="USBDeviceState_Busy"/>,
12343	<link to="USBDeviceState_Held"/>) that were not previously
12344	ignored by global filters.
12345
12346	If at least one filter matches the USB device in question, this
12347	device is automatically captured (attached to) the virtual USB
12348	controller of this machine.
12349
12350	<see>IUSBDeviceFilter, ::IUSBController</see>
12351	</desc>
12352	</attribute>
12353
12354	<method name="createDeviceFilter">
12355	<desc>
12356	Creates a new USB device filter. All attributes except
12357	the filter name are set to empty (any match),
12358	<i>active</i> is @c false (the filter is not active).
12359
12360	The created filter can then be added to the list of filters using
12361	<link to="#insertDeviceFilter"/>.
12362
12363	<result name="VBOX_E_INVALID_VM_STATE">
12364	The virtual machine is not mutable.
12365	</result>
12366
12367	<see>#deviceFilters</see>
12368	</desc>
12369	<param name="name" type="wstring" dir="in">
12370	<desc>
12371	Filter name. See <link to="IUSBDeviceFilter::name"/>
12372	for more info.
12373	</desc>
12374	</param>
12375	<param name="filter" type="IUSBDeviceFilter" dir="return">
12376	<desc>Created filter object.</desc>
12377	</param>
12378	</method>
12379
12380	<method name="insertDeviceFilter">
12381	<desc>
12382	Inserts the given USB device to the specified position
12383	in the list of filters.
12384
12385	Positions are numbered starting from <tt>0</tt>. If the specified
12386	position is equal to or greater than the number of elements in
12387	the list, the filter is added to the end of the collection.
12388
12389	<note>
12390	Duplicates are not allowed, so an attempt to insert a
12391	filter that is already in the collection, will return an
12392	error.
12393	</note>
12394
12395	<result name="VBOX_E_INVALID_VM_STATE">
12396	Virtual machine is not mutable.
12397	</result>
12398	<result name="E_INVALIDARG">
12399	USB device filter not created within this VirtualBox instance.
12400	</result>
12401	<result name="VBOX_E_INVALID_OBJECT_STATE">
12402	USB device filter already in list.
12403	</result>
12404
12405	<see>#deviceFilters</see>
12406	</desc>
12407	<param name="position" type="unsigned long" dir="in">
12408	<desc>Position to insert the filter to.</desc>
12409	</param>
12410	<param name="filter" type="IUSBDeviceFilter" dir="in">
12411	<desc>USB device filter to insert.</desc>
12412	</param>
12413	</method>
12414
12415	<method name="removeDeviceFilter">
12416	<desc>
12417	Removes a USB device filter from the specified position in the
12418	list of filters.
12419
12420	Positions are numbered starting from <tt>0</tt>. Specifying a
12421	position equal to or greater than the number of elements in
12422	the list will produce an error.
12423
12424	<see>#deviceFilters</see>
12425
12426	<result name="VBOX_E_INVALID_VM_STATE">
12427	Virtual machine is not mutable.
12428	</result>
12429	<result name="E_INVALIDARG">
12430	USB device filter list empty or invalid @a position.
12431	</result>
12432
12433	</desc>
12434	<param name="position" type="unsigned long" dir="in">
12435	<desc>Position to remove the filter from.</desc>
12436	</param>
12437	<param name="filter" type="IUSBDeviceFilter" dir="return">
12438	<desc>Removed USB device filter.</desc>
12439	</param>
12440	</method>
12441
12442	</interface>
12443
12444
12445	<!--
12446	// IUSBDevice
12447	/////////////////////////////////////////////////////////////////////////
12448	-->
12449
12450	<interface
12451	name="IUSBDevice" extends="$unknown"
12452	uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
12453	wsmap="managed"
12454	>
12455	<desc>
12456	The IUSBDevice interface represents a virtual USB device attached to the
12457	virtual machine.
12458
12459	A collection of objects implementing this interface is stored in the
12460	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
12461	attached to a running virtual machine's USB controller.
12462	</desc>
12463
12464	<attribute name="id" type="uuid" mod="string" readonly="yes">
12465	<desc>
12466	Unique USB device ID. This ID is built from #vendorId,
12467	#productId, #revision and #serialNumber.
12468	</desc>
12469	</attribute>
12470
12471	<attribute name="vendorId" type="unsigned short" readonly="yes">
12472	<desc>Vendor ID.</desc>
12473	</attribute>
12474
12475	<attribute name="productId" type="unsigned short" readonly="yes">
12476	<desc>Product ID.</desc>
12477	</attribute>
12478
12479	<attribute name="revision" type="unsigned short" readonly="yes">
12480	<desc>
12481	Product revision number. This is a packed BCD represented as
12482	unsigned short. The high byte is the integer part and the low
12483	byte is the decimal.
12484	</desc>
12485	</attribute>
12486
12487	<attribute name="manufacturer" type="wstring" readonly="yes">
12488	<desc>Manufacturer string.</desc>
12489	</attribute>
12490
12491	<attribute name="product" type="wstring" readonly="yes">
12492	<desc>Product string.</desc>
12493	</attribute>
12494
12495	<attribute name="serialNumber" type="wstring" readonly="yes">
12496	<desc>Serial number string.</desc>
12497	</attribute>
12498
12499	<attribute name="address" type="wstring" readonly="yes">
12500	<desc>Host specific address of the device.</desc>
12501	</attribute>
12502
12503	<attribute name="port" type="unsigned short" readonly="yes">
12504	<desc>
12505	Host USB port number the device is physically
12506	connected to.
12507	</desc>
12508	</attribute>
12509
12510	<attribute name="version" type="unsigned short" readonly="yes">
12511	<desc>
12512	The major USB version of the device - 1 or 2.
12513	</desc>
12514	</attribute>
12515
12516	<attribute name="portVersion" type="unsigned short" readonly="yes">
12517	<desc>
12518	The major USB version of the host USB port the device is
12519	physically connected to - 1 or 2. For devices not connected to
12520	anything this will have the same value as the version attribute.
12521	</desc>
12522	</attribute>
12523
12524	<attribute name="remote" type="boolean" readonly="yes">
12525	<desc>
12526	Whether the device is physically connected to a remote VRDP
12527	client or to a local host machine.
12528	</desc>
12529	</attribute>
12530
12531	</interface>
12532
12533
12534	<!--
12535	// IUSBDeviceFilter
12536	/////////////////////////////////////////////////////////////////////////
12537	-->
12538
12539	<interface
12540	name="IUSBDeviceFilter" extends="$unknown"
12541	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
12542	wsmap="managed"
12543	>
12544	<desc>
12545	The IUSBDeviceFilter interface represents an USB device filter used
12546	to perform actions on a group of USB devices.
12547
12548	This type of filters is used by running virtual machines to
12549	automatically capture selected USB devices once they are physically
12550	attached to the host computer.
12551
12552	A USB device is matched to the given device filter if and only if all
12553	attributes of the device match the corresponding attributes of the
12554	filter (that is, attributes are joined together using the logical AND
12555	operation). On the other hand, all together, filters in the list of
12556	filters carry the semantics of the logical OR operation. So if it is
12557	desirable to create a match like "this vendor id OR this product id",
12558	one needs to create two filters and specify "any match" (see below)
12559	for unused attributes.
12560
12561	All filter attributes used for matching are strings. Each string
12562	is an expression representing a set of values of the corresponding
12563	device attribute, that will match the given filter. Currently, the
12564	following filtering expressions are supported:
12565
12566	<ul>
12567	<li><i>Interval filters</i>. Used to specify valid intervals for
12568	integer device attributes (Vendor ID, Product ID and Revision).
12569	The format of the string is:
12570
12571	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
12572
12573	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
12574	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
12575	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
12576	is omitted before a dash (<tt>-</tt>), the minimum possible integer
12577	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
12578	possible integer is assumed.
12579	</li>
12580	<li><i>Boolean filters</i>. Used to specify acceptable values for
12581	boolean device attributes. The format of the string is:
12582
12583	<tt>true\|false\|yes\|no\|0\|1</tt>
12584
12585	</li>
12586	<li><i>Exact match</i>. Used to specify a single value for the given
12587	device attribute. Any string that doesn't start with <tt>int:</tt>
12588	represents the exact match. String device attributes are compared to
12589	this string including case of symbols. Integer attributes are first
12590	converted to a string (see individual filter attributes) and then
12591	compared ignoring case.
12592
12593	</li>
12594	<li><i>Any match</i>. Any value of the corresponding device attribute
12595	will match the given filter. An empty or @c null string is
12596	used to construct this type of filtering expressions.
12597
12598	</li>
12599	</ul>
12600
12601	<note>
12602	On the Windows host platform, interval filters are not currently
12603	available. Also all string filter attributes
12604	(<link to="#manufacturer"/>, <link to="#product"/>,
12605	<link to="#serialNumber"/>) are ignored, so they behave as
12606	<i>any match</i> no matter what string expression is specified.
12607	</note>
12608
12609	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
12610	</desc>
12611
12612	<attribute name="name" type="wstring">
12613	<desc>
12614	Visible name for this filter.
12615	This name is used to visually distinguish one filter from another,
12616	so it can neither be @c null nor an empty string.
12617	</desc>
12618	</attribute>
12619
12620	<attribute name="active" type="boolean">
12621	<desc>Whether this filter active or has been temporarily disabled.</desc>
12622	</attribute>
12623
12624	<attribute name="vendorId" type="wstring">
12625	<desc>
12626	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
12627	The string representation for the <i>exact matching</i>
12628	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12629	(including leading zeroes).
12630	</desc>
12631	</attribute>
12632
12633	<attribute name="productId" type="wstring">
12634	<desc>
12635	<link to="IUSBDevice::productId">Product ID</link> filter.
12636	The string representation for the <i>exact matching</i>
12637	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
12638	(including leading zeroes).
12639	</desc>
12640	</attribute>
12641
12642	<attribute name="revision" type="wstring">
12643	<desc>
12644	<link to="IUSBDevice::productId">Product revision number</link>
12645	filter. The string representation for the <i>exact matching</i>
12646	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
12647	of the integer part of the revision, and <tt>F</tt> is the
12648	decimal digit of its fractional part (including leading and
12649	trailing zeros).
12650	Note that for interval filters, it's best to use the hexadecimal
12651	form, because the revision is stored as a 16 bit packed BCD value;
12652	so the expression <tt>int:0x0100-0x0199</tt> will match any
12653	revision from <tt>1.0</tt> to <tt>1.99</tt>.
12654	</desc>
12655	</attribute>
12656
12657	<attribute name="manufacturer" type="wstring">
12658	<desc>
12659	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
12660	</desc>
12661	</attribute>
12662
12663	<attribute name="product" type="wstring">
12664	<desc>
12665	<link to="IUSBDevice::product">Product</link> filter.
12666	</desc>
12667	</attribute>
12668
12669	<attribute name="serialNumber" type="wstring">
12670	<desc>
12671	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
12672	</desc>
12673	</attribute>
12674
12675	<attribute name="port" type="wstring">
12676	<desc>
12677	<link to="IUSBDevice::port">Host USB port</link> filter.
12678	</desc>
12679	</attribute>
12680
12681	<attribute name="remote" type="wstring">
12682	<desc>
12683	<link to="IUSBDevice::remote">Remote state</link> filter.
12684	<note>
12685	This filter makes sense only for machine USB filters,
12686	i.e. it is ignored by IHostUSBDeviceFilter objects.
12687	</note>
12688	</desc>
12689	</attribute>
12690
12691	<attribute name="maskedInterfaces" type="unsigned long">
12692	<desc>
12693	This is an advanced option for hiding one or more USB interfaces
12694	from the guest. The value is a bit mask where the bits that are set
12695	means the corresponding USB interface should be hidden, masked off
12696	if you like.
12697	This feature only works on Linux hosts.
12698	</desc>
12699	</attribute>
12700
12701	</interface>
12702
12703
12704	<!--
12705	// IHostUSBDevice
12706	/////////////////////////////////////////////////////////////////////////
12707	-->
12708
12709	<enum
12710	name="USBDeviceState"
12711	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
12712	>
12713	<desc>
12714	USB device state. This enumeration represents all possible states
12715	of the USB device physically attached to the host computer regarding
12716	its state on the host computer and availability to guest computers
12717	(all currently running virtual machines).
12718
12719	Once a supported USB device is attached to the host, global USB
12720	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
12721	either ignore the device, or put it to USBDeviceState_Held state, or do
12722	nothing. Unless the device is ignored by global filters, filters of all
12723	currently running guests (<link to="IUSBController::deviceFilters"/>) are
12724	activated that can put it to USBDeviceState_Captured state.
12725
12726	If the device was ignored by global filters, or didn't match
12727	any filters at all (including guest ones), it is handled by the host
12728	in a normal way. In this case, the device state is determined by
12729	the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
12730	or USBDeviceState_Available, depending on the current device usage.
12731
12732	Besides auto-capturing based on filters, the device can be manually
12733	captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
12734	state is USBDeviceState_Busy, USBDeviceState_Available or
12735	USBDeviceState_Held.
12736
12737	<note>
12738	Due to differences in USB stack implementations in Linux and Win32,
12739	states USBDeviceState_Busy and USBDeviceState_vailable are applicable
12740	only to the Linux version of the product. This also means that (<link
12741	to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
12742	device state is USBDeviceState_Held.
12743	</note>
12744
12745	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
12746	</desc>
12747
12748	<const name="NotSupported" value="0">
12749	<desc>
12750	Not supported by the VirtualBox server, not available to guests.
12751	</desc>
12752	</const>
12753	<const name="Unavailable" value="1">
12754	<desc>
12755	Being used by the host computer exclusively,
12756	not available to guests.
12757	</desc>
12758	</const>
12759	<const name="Busy" value="2">
12760	<desc>
12761	Being used by the host computer, potentially available to guests.
12762	</desc>
12763	</const>
12764	<const name="Available" value="3">
12765	<desc>
12766	Not used by the host computer, available to guests (the host computer
12767	can also start using the device at any time).
12768	</desc>
12769	</const>
12770	<const name="Held" value="4">
12771	<desc>
12772	Held by the VirtualBox server (ignored by the host computer),
12773	available to guests.
12774	</desc>
12775	</const>
12776	<const name="Captured" value="5">
12777	<desc>
12778	Captured by one of the guest computers, not available
12779	to anybody else.
12780	</desc>
12781	</const>
12782	</enum>
12783
12784	<interface
12785	name="IHostUSBDevice" extends="IUSBDevice"
12786	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
12787	wsmap="managed"
12788	>
12789	<desc>
12790	The IHostUSBDevice interface represents a physical USB device attached
12791	to the host computer.
12792
12793	Besides properties inherited from IUSBDevice, this interface adds the
12794	<link to="#state"/> property that holds the current state of the USB
12795	device.
12796
12797	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
12798	</desc>
12799
12800	<attribute name="state" type="USBDeviceState" readonly="yes">
12801	<desc>
12802	Current state of the device.
12803	</desc>
12804	</attribute>
12805
12806	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
12807
12808	</interface>
12809
12810
12811	<!--
12812	// IHostUSBDeviceFilter
12813	/////////////////////////////////////////////////////////////////////////
12814	-->
12815
12816	<enum
12817	name="USBDeviceFilterAction"
12818	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
12819	>
12820	<desc>
12821	Actions for host USB device filters.
12822	<see>IHostUSBDeviceFilter, USBDeviceState</see>
12823	</desc>
12824
12825	<const name="Null" value="0">
12826	<desc>Null value (never used by the API).</desc>
12827	</const>
12828	<const name="Ignore" value="1">
12829	<desc>Ignore the matched USB device.</desc>
12830	</const>
12831	<const name="Hold" value="2">
12832	<desc>Hold the matched USB device.</desc>
12833	</const>
12834	</enum>
12835
12836	<interface
12837	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
12838	uuid="4cc70246-d74a-400f-8222-3900489c0374"
12839	wsmap="managed"
12840	>
12841	<desc>
12842	The IHostUSBDeviceFilter interface represents a global filter for a
12843	physical USB device used by the host computer. Used indirectly in
12844	<link to="IHost::USBDeviceFilters"/>.
12845
12846	Using filters of this type, the host computer determines the initial
12847	state of the USB device after it is physically attached to the
12848	host's USB controller.
12849
12850	<note>
12851	The <link to="#remote"/> attribute is ignored by this type of
12852	filters, because it makes sense only for
12853	<link to="IUSBController::deviceFilters">machine USB filters</link>.
12854	</note>
12855
12856	<see>IHost::USBDeviceFilters</see>
12857	</desc>
12858
12859	<attribute name="action" type="USBDeviceFilterAction">
12860	<desc>
12861	Action performed by the host when an attached USB device
12862	matches this filter.
12863	</desc>
12864	</attribute>
12865
12866	</interface>
12867
12868	<!--
12869	// IAudioAdapter
12870	/////////////////////////////////////////////////////////////////////////
12871	-->
12872
12873	<enum
12874	name="AudioDriverType"
12875	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
12876	>
12877	<desc>
12878	Host audio driver type.
12879	</desc>
12880
12881	<const name="Null" value="0">
12882	<desc>Null value, also means "dummy audio driver".</desc>
12883	</const>
12884	<const name="WinMM" value="1">
12885	<desc>Windows multimedia (Windows hosts only).</desc>
12886	</const>
12887	<const name="OSS" value="2">
12888	<desc>Open Sound System (Linux hosts only).</desc>
12889	</const>
12890	<const name="ALSA" value="3">
12891	<desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
12892	</const>
12893	<const name="DirectSound" value="4">
12894	<desc>DirectSound (Windows hosts only).</desc>
12895	</const>
12896	<const name="CoreAudio" value="5">
12897	<desc>CoreAudio (Mac hosts only).</desc>
12898	</const>
12899	<const name="MMPM" value="6">
12900	<desc>Reserved for historical reasons.</desc>
12901	</const>
12902	<const name="Pulse" value="7">
12903	<desc>PulseAudio (Linux hosts only).</desc>
12904	</const>
12905	<const name="SolAudio" value="8">
12906	<desc>Solaris audio (Solaris hosts only).</desc>
12907	</const>
12908	</enum>
12909
12910	<enum
12911	name="AudioControllerType"
12912	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
12913	>
12914	<desc>
12915	Virtual audio controller type.
12916	</desc>
12917
12918	<const name="AC97" value="0"/>
12919	<const name="SB16" value="1"/>
12920	</enum>
12921
12922	<interface
12923	name="IAudioAdapter" extends="$unknown"
12924	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
12925	wsmap="managed"
12926	>
12927	<desc>
12928	The IAudioAdapter interface represents the virtual audio adapter of
12929	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
12930	</desc>
12931	<attribute name="enabled" type="boolean">
12932	<desc>
12933	Flag whether the audio adapter is present in the
12934	guest system. If disabled, the virtual guest hardware will
12935	not contain any audio adapter. Can only be changed when
12936	the VM is not running.
12937	</desc>
12938	</attribute>
12939	<attribute name="audioController" type="AudioControllerType">
12940	<desc>
12941	The audio hardware we emulate.
12942	</desc>
12943	</attribute>
12944	<attribute name="audioDriver" type="AudioDriverType">
12945	<desc>
12946	Audio driver the adapter is connected to. This setting
12947	can only be changed when the VM is not running.
12948	</desc>
12949	</attribute>
12950	</interface>
12951
12952	<!--
12953	// IVRDPServer
12954	/////////////////////////////////////////////////////////////////////////
12955	-->
12956
12957	<enum
12958	name="VRDPAuthType"
12959	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
12960	>
12961	<desc>
12962	VRDP authentication type.
12963	</desc>
12964
12965	<const name="Null" value="0">
12966	<desc>Null value, also means "no authentication".</desc>
12967	</const>
12968	<const name="External" value="1"/>
12969	<const name="Guest" value="2"/>
12970	</enum>
12971
12972	<interface
12973	name="IVRDPServer" extends="$unknown"
12974	uuid="7aeeb530-0b08-41fe-835d-9be9ec1dbe5c"
12975	wsmap="managed"
12976	>
12977	<attribute name="enabled" type="boolean">
12978	<desc>VRDP server status.</desc>
12979	</attribute>
12980
12981	<attribute name="ports" type="wstring">
12982	<desc>
12983	VRDP server port numbers. The server will try to bind to one of free ports from the list.
12984	<note>
12985	This is a string of comma separated TCP port numbers or port number ranges.
12986	Example <tt>5000,5010-5012,5015</tt>
12987	</note>
12988	</desc>
12989	</attribute>
12990
12991	<attribute name="netAddress" type="wstring">
12992	<desc>VRDP server address.</desc>
12993	</attribute>
12994
12995	<attribute name="authType" type="VRDPAuthType">
12996	<desc>VRDP authentication method.</desc>
12997	</attribute>
12998
12999	<attribute name="authTimeout" type="unsigned long">
13000	<desc>Timeout for guest authentication. Milliseconds.</desc>
13001	</attribute>
13002
13003	<attribute name="allowMultiConnection" type="boolean">
13004	<desc>
13005	Flag whether multiple simultaneous connections to the VM are permitted.
13006	Note that this will be replaced by a more powerful mechanism in the future.
13007	</desc>
13008	</attribute>
13009
13010	<attribute name="reuseSingleConnection" type="boolean">
13011	<desc>
13012	Flag whether the existing connection must be dropped and a new connection
13013	must be established by the VRDP server, when a new client connects in single
13014	connection mode.
13015	</desc>
13016	</attribute>
13017
13018	<attribute name="videoChannel" type="boolean">
13019	<desc>
13020	Flag whether RDP video channel is supported.
13021	</desc>
13022	</attribute>
13023
13024	<attribute name="videoChannelQuality" type="unsigned long">
13025	<desc>
13026	Image quality in percents.
13027	</desc>
13028	</attribute>
13029
13030	</interface>
13031
13032
13033	<!--
13034	// ISharedFolder
13035	/////////////////////////////////////////////////////////////////////////
13036	-->
13037
13038	<interface
13039	name="ISharedFolder" extends="$unknown"
13040	uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
13041	wsmap="struct"
13042	>
13043	<desc>
13044	The ISharedFolder interface represents a folder in the host computer's
13045	file system accessible from the guest OS running inside a virtual
13046	machine using an associated logical name.
13047
13048	There are three types of shared folders:
13049	<ul>
13050	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
13051	folders available to all virtual machines.</li>
13052	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
13053	VM-specific shared folders available to the given virtual machine at
13054	startup.</li>
13055	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
13056	VM-specific shared folders created in the session context (for
13057	example, when the virtual machine is running) and automatically
13058	discarded when the session is closed (the VM is powered off).</li>
13059	</ul>
13060
13061	Logical names of shared folders must be unique within the given scope
13062	(global, permanent or transient). However, they do not need to be unique
13063	across scopes. In this case, the definition of the shared folder in a
13064	more specific scope takes precedence over definitions in all other
13065	scopes. The order of precedence is (more specific to more general):
13066	<ol>
13067	<li>Transient definitions</li>
13068	<li>Permanent definitions</li>
13069	<li>Global definitions</li>
13070	</ol>
13071
13072	For example, if MyMachine has a shared folder named
13073	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
13074	transient shared folder named <tt>C_DRIVE</tt> (that points
13075	to <tt>C:\\\\WINDOWS</tt>) will change the definition
13076	of <tt>C_DRIVE</tt> in the guest OS so
13077	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
13078	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
13079	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
13080	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
13081	to <tt>C:\\</tt> if it still exists.
13082
13083	Note that permanent and transient shared folders of different machines
13084	are in different name spaces, so they don't overlap and don't need to
13085	have unique logical names.
13086
13087	<note>
13088	Global shared folders are not implemented in the current version of the
13089	product.
13090	</note>
13091	</desc>
13092
13093	<attribute name="name" type="wstring" readonly="yes">
13094	<desc>Logical name of the shared folder.</desc>
13095	</attribute>
13096
13097	<attribute name="hostPath" type="wstring" readonly="yes">
13098	<desc>Full path to the shared folder in the host file system.</desc>
13099	</attribute>
13100
13101	<attribute name="accessible" type="boolean" readonly="yes">
13102	<desc>
13103	Whether the folder defined by the host path is currently
13104	accessible or not.
13105	For example, the folder can be unaccessible if it is placed
13106	on the network share that is not available by the time
13107	this property is read.
13108	</desc>
13109	</attribute>
13110
13111	<attribute name="writable" type="boolean" readonly="yes">
13112	<desc>
13113	Whether the folder defined by the host path is writable or
13114	not.
13115	</desc>
13116	</attribute>
13117
13118	<attribute name="lastAccessError" type="wstring" readonly="yes">
13119	<desc>
13120	Text message that represents the result of the last accessibility
13121	check.
13122
13123	Accessibility checks are performed each time the <link to="#accessible"/>
13124	attribute is read. An empty string is returned if the last
13125	accessibility check was successful. A non-empty string indicates a
13126	failure and should normally describe a reason of the failure (for
13127	example, a file read error).
13128	</desc>
13129	</attribute>
13130
13131	</interface>
13132
13133	<!--
13134	// ISession
13135	/////////////////////////////////////////////////////////////////////////
13136	-->
13137
13138	<interface
13139	name="IInternalSessionControl" extends="$unknown"
13140	uuid="cc8d63a0-568e-45dd-9bf6-6354049ece1e"
13141	internal="yes"
13142	wsmap="suppress"
13143	>
13144	<method name="getPID">
13145	<desc>PID of the process that has created this Session object.
13146	</desc>
13147	<param name="pid" type="unsigned long" dir="return"/>
13148	</method>
13149
13150	<method name="getRemoteConsole">
13151	<desc>
13152	Returns the console object suitable for remote control.
13153
13154	<result name="VBOX_E_INVALID_VM_STATE">
13155	Session state prevents operation.
13156	</result>
13157	<result name="VBOX_E_INVALID_OBJECT_STATE">
13158	Session type prevents operation.
13159	</result>
13160
13161	</desc>
13162	<param name="console" type="IConsole" dir="return"/>
13163	</method>
13164
13165	<method name="assignMachine">
13166	<desc>
13167	Assigns the machine object associated with this direct-type
13168	session or informs the session that it will be a remote one
13169	(if @a machine == @c null).
13170
13171	<result name="VBOX_E_INVALID_VM_STATE">
13172	Session state prevents operation.
13173	</result>
13174	<result name="VBOX_E_INVALID_OBJECT_STATE">
13175	Session type prevents operation.
13176	</result>
13177
13178	</desc>
13179	<param name="machine" type="IMachine" dir="in"/>
13180	</method>
13181
13182	<method name="assignRemoteMachine">
13183	<desc>
13184	Assigns the machine and the (remote) console object associated with
13185	this remote-type session.
13186
13187	<result name="VBOX_E_INVALID_VM_STATE">
13188	Session state prevents operation.
13189	</result>
13190
13191	</desc>
13192	<param name="machine" type="IMachine" dir="in"/>
13193	<param name="console" type="IConsole" dir="in"/>
13194	</method>
13195
13196	<method name="updateMachineState">
13197	<desc>
13198	Updates the machine state in the VM process.
13199	Must be called only in certain cases
13200	(see the method implementation).
13201
13202	<result name="VBOX_E_INVALID_VM_STATE">
13203	Session state prevents operation.
13204	</result>
13205	<result name="VBOX_E_INVALID_OBJECT_STATE">
13206	Session type prevents operation.
13207	</result>
13208
13209	</desc>
13210	<param name="aMachineState" type="MachineState" dir="in"/>
13211	</method>
13212
13213	<method name="uninitialize">
13214	<desc>
13215	Uninitializes (closes) this session. Used by VirtualBox to close
13216	the corresponding remote session when the direct session dies
13217	or gets closed.
13218
13219	<result name="VBOX_E_INVALID_VM_STATE">
13220	Session state prevents operation.
13221	</result>
13222
13223	</desc>
13224	</method>
13225
13226	<method name="onNetworkAdapterChange">
13227	<desc>
13228	Triggered when settings of a network adapter of the
13229	associated virtual machine have changed.
13230
13231	<result name="VBOX_E_INVALID_VM_STATE">
13232	Session state prevents operation.
13233	</result>
13234	<result name="VBOX_E_INVALID_OBJECT_STATE">
13235	Session type prevents operation.
13236	</result>
13237
13238	</desc>
13239	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
13240	<param name="changeAdapter" type="boolean" dir="in"/>
13241	</method>
13242
13243	<method name="onSerialPortChange">
13244	<desc>
13245	Triggered when settings of a serial port of the
13246	associated virtual machine have changed.
13247
13248	<result name="VBOX_E_INVALID_VM_STATE">
13249	Session state prevents operation.
13250	</result>
13251	<result name="VBOX_E_INVALID_OBJECT_STATE">
13252	Session type prevents operation.
13253	</result>
13254
13255	</desc>
13256	<param name="serialPort" type="ISerialPort" dir="in"/>
13257	</method>
13258
13259	<method name="onParallelPortChange">
13260	<desc>
13261	Triggered when settings of a parallel port of the
13262	associated virtual machine have changed.
13263
13264	<result name="VBOX_E_INVALID_VM_STATE">
13265	Session state prevents operation.
13266	</result>
13267	<result name="VBOX_E_INVALID_OBJECT_STATE">
13268	Session type prevents operation.
13269	</result>
13270
13271	</desc>
13272	<param name="parallelPort" type="IParallelPort" dir="in"/>
13273	</method>
13274
13275	<method name="onStorageControllerChange">
13276	<desc>
13277	Triggered when settings of a storage controller of the
13278	associated virtual machine have changed.
13279
13280	<result name="VBOX_E_INVALID_VM_STATE">
13281	Session state prevents operation.
13282	</result>
13283	<result name="VBOX_E_INVALID_OBJECT_STATE">
13284	Session type prevents operation.
13285	</result>
13286
13287	</desc>
13288	</method>
13289
13290	<method name="onMediumChange">
13291	<desc>
13292	Triggered when attached media of the
13293	associated virtual machine have changed.
13294
13295	<result name="VBOX_E_INVALID_VM_STATE">
13296	Session state prevents operation.
13297	</result>
13298	<result name="VBOX_E_INVALID_OBJECT_STATE">
13299	Session type prevents operation.
13300	</result>
13301
13302	</desc>
13303
13304	<param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
13305	<param name="force" type="boolean" dir="in"/>
13306	</method>
13307
13308	<method name="onCPUChange">
13309	<desc>
13310	Notification when a CPU changes.
13311	</desc>
13312	<param name="cpu" type="unsigned long" dir="in">
13313	<desc>The CPU which changed</desc>
13314	</param>
13315	<param name="add" type="boolean" dir="in">
13316	<desc>Flag whether the CPU was added or removed</desc>
13317	</param>
13318	</method>
13319
13320	<method name="onVRDPServerChange">
13321	<desc>
13322	Triggered when settings of the VRDP server object of the
13323	associated virtual machine have changed.
13324
13325	<result name="VBOX_E_INVALID_VM_STATE">
13326	Session state prevents operation.
13327	</result>
13328	<result name="VBOX_E_INVALID_OBJECT_STATE">
13329	Session type prevents operation.
13330	</result>
13331
13332	</desc>
13333	</method>
13334
13335	<method name="onUSBControllerChange">
13336	<desc>
13337	Triggered when settings of the USB controller object of the
13338	associated virtual machine have changed.
13339
13340	<result name="VBOX_E_INVALID_VM_STATE">
13341	Session state prevents operation.
13342	</result>
13343	<result name="VBOX_E_INVALID_OBJECT_STATE">
13344	Session type prevents operation.
13345	</result>
13346
13347	</desc>
13348	</method>
13349
13350	<method name="onSharedFolderChange">
13351	<desc>
13352	Triggered when a permanent (global or machine) shared folder has been
13353	created or removed.
13354	<note>
13355	We don't pass shared folder parameters in this notification because
13356	the order in which parallel notifications are delivered is not defined,
13357	therefore it could happen that these parameters were outdated by the
13358	time of processing this notification.
13359	</note>
13360
13361	<result name="VBOX_E_INVALID_VM_STATE">
13362	Session state prevents operation.
13363	</result>
13364	<result name="VBOX_E_INVALID_OBJECT_STATE">
13365	Session type prevents operation.
13366	</result>
13367
13368	</desc>
13369	<param name="global" type="boolean" dir="in"/>
13370	</method>
13371
13372	<method name="onUSBDeviceAttach">
13373	<desc>
13374	Triggered when a request to capture a USB device (as a result
13375	of matched USB filters or direct call to
13376	<link to="IConsole::attachUSBDevice"/>) has completed.
13377	A @c null @a error object means success, otherwise it
13378	describes a failure.
13379
13380	<result name="VBOX_E_INVALID_VM_STATE">
13381	Session state prevents operation.
13382	</result>
13383	<result name="VBOX_E_INVALID_OBJECT_STATE">
13384	Session type prevents operation.
13385	</result>
13386
13387	</desc>
13388	<param name="device" type="IUSBDevice" dir="in"/>
13389	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13390	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
13391	</method>
13392
13393	<method name="onUSBDeviceDetach">
13394	<desc>
13395	Triggered when a request to release the USB device (as a result
13396	of machine termination or direct call to
13397	<link to="IConsole::detachUSBDevice"/>) has completed.
13398	A @c null @a error object means success, otherwise it
13399	describes a failure.
13400
13401	<result name="VBOX_E_INVALID_VM_STATE">
13402	Session state prevents operation.
13403	</result>
13404	<result name="VBOX_E_INVALID_OBJECT_STATE">
13405	Session type prevents operation.
13406	</result>
13407
13408	</desc>
13409	<param name="id" type="uuid" mod="string" dir="in"/>
13410	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
13411	</method>
13412
13413	<method name="onShowWindow">
13414	<desc>
13415	Called by <link to="IMachine::canShowConsoleWindow"/> and by
13416	<link to="IMachine::showConsoleWindow"/> in order to notify
13417	console callbacks
13418	<link to="IConsoleCallback::onCanShowWindow"/>
13419	and <link to="IConsoleCallback::onShowWindow"/>.
13420
13421	<result name="VBOX_E_INVALID_OBJECT_STATE">
13422	Session type prevents operation.
13423	</result>
13424
13425	</desc>
13426	<param name="check" type="boolean" dir="in"/>
13427	<param name="canShow" type="boolean" dir="out"/>
13428	<param name="winId" type="unsigned long long" dir="out"/>
13429	</method>
13430
13431	<method name="accessGuestProperty">
13432	<desc>
13433	Called by <link to="IMachine::getGuestProperty"/> and by
13434	<link to="IMachine::setGuestProperty"/> in order to read and
13435	modify guest properties.
13436
13437	<result name="VBOX_E_INVALID_VM_STATE">
13438	Machine session is not open.
13439	</result>
13440	<result name="VBOX_E_INVALID_OBJECT_STATE">
13441	Session type is not direct.
13442	</result>
13443
13444	</desc>
13445	<param name="name" type="wstring" dir="in"/>
13446	<param name="value" type="wstring" dir="in"/>
13447	<param name="flags" type="wstring" dir="in"/>
13448	<param name="isSetter" type="boolean" dir="in"/>
13449	<param name="retValue" type="wstring" dir="out"/>
13450	<param name="retTimestamp" type="unsigned long long" dir="out"/>
13451	<param name="retFlags" type="wstring" dir="out"/>
13452	</method>
13453
13454	<method name="enumerateGuestProperties">
13455	<desc>
13456	Return a list of the guest properties matching a set of patterns along
13457	with their values, time stamps and flags.
13458
13459	<result name="VBOX_E_INVALID_VM_STATE">
13460	Machine session is not open.
13461	</result>
13462	<result name="VBOX_E_INVALID_OBJECT_STATE">
13463	Session type is not direct.
13464	</result>
13465
13466	</desc>
13467	<param name="patterns" type="wstring" dir="in">
13468	<desc>
13469	The patterns to match the properties against as a comma-separated
13470	string. If this is empty, all properties currently set will be
13471	returned.
13472	</desc>
13473	</param>
13474	<param name="key" type="wstring" dir="out" safearray="yes">
13475	<desc>
13476	The key names of the properties returned.
13477	</desc>
13478	</param>
13479	<param name="value" type="wstring" dir="out" safearray="yes">
13480	<desc>
13481	The values of the properties returned. The array entries match the
13482	corresponding entries in the @a key array.
13483	</desc>
13484	</param>
13485	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
13486	<desc>
13487	The time stamps of the properties returned. The array entries match
13488	the corresponding entries in the @a key array.
13489	</desc>
13490	</param>
13491	<param name="flags" type="wstring" dir="out" safearray="yes">
13492	<desc>
13493	The flags of the properties returned. The array entries match the
13494	corresponding entries in the @a key array.
13495	</desc>
13496	</param>
13497	</method>
13498
13499	<method name="onlineMergeMedium">
13500	<desc>
13501	Triggers online merging of a hard disk. Used internally when deleting
13502	a snapshot while a VM referring to the same hard disk chain is running.
13503
13504	<result name="VBOX_E_INVALID_VM_STATE">
13505	Machine session is not open.
13506	</result>
13507	<result name="VBOX_E_INVALID_OBJECT_STATE">
13508	Session type is not direct.
13509	</result>
13510
13511	</desc>
13512	<param name="mediumAttachment" type="IMediumAttachment" dir="in">
13513	<desc>The medium attachment to identify the medium chain.</desc>
13514	</param>
13515	<param name="sourceIdx" type="unsigned long" dir="in">
13516	<desc>The index of the source image in the chain.
13517	Redundant, but drastically reduces IPC.</desc>
13518	</param>
13519	<param name="targetIdx" type="unsigned long" dir="in">
13520	<desc>The index of the target image in the chain.
13521	Redundant, but drastically reduces IPC.</desc>
13522	</param>
13523	<param name="source" type="IMedium" dir="in">
13524	<desc>Merge source medium.</desc>
13525	</param>
13526	<param name="target" type="IMedium" dir="in">
13527	<desc>Merge target medium.</desc>
13528	</param>
13529	<param name="mergeForward" type="boolean" dir="in">
13530	<desc>Merge direction.</desc>
13531	</param>
13532	<param name="parentForTarget" type="IMedium" dir="in">
13533	<desc>For forward merges: new parent for target medium.</desc>
13534	</param>
13535	<param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
13536	<desc>For backward merges: list of media which need their parent UUID
13537	updated.</desc>
13538	</param>
13539	<param name="progress" type="IProgress" dir="in">
13540	<desc>
13541	Progress object for this operation.
13542	</desc>
13543	</param>
13544	</method>
13545
13546	</interface>
13547
13548	<interface
13549	name="ISession" extends="$unknown"
13550	uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
13551	wsmap="managed"
13552	>
13553	<desc>
13554	The ISession interface represents a serialization primitive for virtual
13555	machines.
13556
13557	With VirtualBox, every time one wishes to manipulate a virtual machine
13558	(e.g. change its settings or start execution), a session object is
13559	required. Such an object must be passed to one of the session methods
13560	that open the given session, which then initiates the machine manipulation.
13561
13562	A session serves several purposes: it identifies to the inter-process VirtualBox
13563	code which process is currently working with the virtual machine, and it ensures
13564	that there are no incompatible requests from several processes for the
13565	same virtual machine. Session objects can therefore be thought of as mutex
13566	semaphores that lock virtual machines to prevent conflicting accesses from
13567	several processes.
13568
13569	How sessions objects are used depends on whether you use the Main API
13570	via COM or via the webservice:
13571
13572	<ul>
13573	<li>When using the COM API directly, an object of the Session class from the
13574	VirtualBox type library needs to be created. In regular COM C++ client code,
13575	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
13576	This object will then act as a local session object in further calls to open
13577	a session.
13578	</li>
13579
13580	<li>In the webservice, the session manager (IWebsessionManager) instead creates
13581	one session object automatically when <link to="IWebsessionManager::logon" />
13582	is called. A managed object reference to that session object can be retrieved by
13583	calling <link to="IWebsessionManager::getSessionObject" />. This session object
13584	reference can then be used to open sessions.
13585	</li>
13586	</ul>
13587
13588	Sessions are mainly used in two variations:
13589
13590	<ul>
13591	<li>
13592	To start a virtual machine in a separate process, one would call
13593	<link to="IVirtualBox::openRemoteSession"/>, which requires a session
13594	object as its first parameter. This session then identifies the caller
13595	and lets him control the started machine (for example, pause machine
13596	execution or power it down) as well as be notified about machine
13597	execution state changes.
13598	</li>
13599
13600	<li>To alter machine settings, or to start machine execution within the
13601	current process, one needs to open a direct session for the machine first by
13602	calling <link to="IVirtualBox::openSession"/>. While a direct session
13603	is open within one process, no any other process may open another direct
13604	session for the same machine. This prevents the machine from being changed
13605	by other processes while it is running or while the machine is being configured.
13606	</li>
13607	</ul>
13608
13609	One also can attach to an existing direct session already opened by
13610	another process (for example, in order to send a control request to the
13611	virtual machine such as the pause or the reset request). This is done by
13612	calling <link to="IVirtualBox::openExistingSession"/>.
13613
13614	<note>
13615	Unless you are trying to write a new VirtualBox front-end that
13616	performs direct machine execution (like the VirtualBox or VBoxSDL
13617	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
13618	session opened by <link to="IVirtualBox::openSession"/> and use this
13619	session only to change virtual machine settings. If you simply want to
13620	start virtual machine execution using one of the existing front-ends
13621	(for example the VirtualBox GUI or headless server), simply use
13622	<link to="IVirtualBox::openRemoteSession"/>; these front-ends
13623	will power up the machine automatically for you.
13624	</note>
13625	</desc>
13626
13627	<attribute name="state" type="SessionState" readonly="yes">
13628	<desc>Current state of this session.</desc>
13629	</attribute>
13630
13631	<attribute name="type" type="SessionType" readonly="yes">
13632	<desc>
13633	Type of this session. The value of this attribute is valid only
13634	if the session is currently open (i.e. its #state is
13635	SessionType_SessionOpen), otherwise an error will be returned.
13636	</desc>
13637	</attribute>
13638
13639	<attribute name="machine" type="IMachine" readonly="yes">
13640	<desc>Machine object associated with this session.</desc>
13641	</attribute>
13642
13643	<attribute name="console" type="IConsole" readonly="yes">
13644	<desc>Console object associated with this session.</desc>
13645	</attribute>
13646
13647	<method name="close">
13648	<desc>
13649	Closes a session that was previously opened.
13650
13651	It is recommended that every time an "open session" method (such as
13652	<link to="IVirtualBox::openRemoteSession" /> or
13653	<link to="IVirtualBox::openSession" />) has been called to
13654	manipulate a virtual machine, the caller invoke
13655	ISession::close() when it's done doing so. Since sessions are
13656	serialization primitives much like ordinary mutexes, they are
13657	best used the same way: for each "open" call, there should be
13658	a matching "close" call, even when errors occur.
13659
13660	Otherwise, if a direct session for a machine opened with
13661	<link to="IVirtualBox::openSession"/> is not explicitly closed
13662	when the application terminates, the state of the machine will
13663	be set to <link to="MachineState_Aborted" /> on the server.
13664
13665	Generally, it is recommended to close all open sessions explicitly
13666	before terminating the application (regardless of the reason for
13667	the termination).
13668
13669	<note>
13670	Do not expect the session state (<link to="ISession::state" />
13671	to return to "Closed" immediately after you invoke
13672	ISession::close(), particularly if you have started a remote
13673	session to execute the VM in a new process. The session state will
13674	automatically return to "Closed" once the VM is no longer executing,
13675	which can of course take a very long time.
13676	</note>
13677
13678	<result name="E_UNEXPECTED">
13679	Session is not open.
13680	</result>
13681
13682	</desc>
13683	</method>
13684
13685	</interface>
13686
13687	<!--
13688	// IStorageController
13689	/////////////////////////////////////////////////////////////////////////
13690	-->
13691
13692	<enum
13693	name="StorageBus"
13694	uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
13695	>
13696	<desc>
13697	The bus type of the storage controller (IDE, SATA, SCSI or Floppy);
13698	see <link to="IStorageController::bus" />.
13699	</desc>
13700	<const name="Null" value="0">
13701	<desc>@c null value. Never used by the API.</desc>
13702	</const>
13703	<const name="IDE" value="1"/>
13704	<const name="SATA" value="2"/>
13705	<const name="SCSI" value="3"/>
13706	<const name="Floppy" value="4"/>
13707	<const name="SAS" value="5"/>
13708	</enum>
13709
13710	<enum
13711	name="StorageControllerType"
13712	uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
13713	>
13714	<desc>
13715	The exact variant of storage controller hardware presented
13716	to the guest; see <link to="IStorageController::controllerType" />.
13717	</desc>
13718
13719	<const name="Null" value="0">
13720	<desc>@c null value. Never used by the API.</desc>
13721	</const>
13722	<const name="LsiLogic" value="1">
13723	<desc>A SCSI controller of the LsiLogic variant.</desc>
13724	</const>
13725	<const name="BusLogic" value="2">
13726	<desc>A SCSI controller of the BusLogic variant.</desc>
13727	</const>
13728	<const name="IntelAhci" value="3">
13729	<desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
13730	</const>
13731	<const name="PIIX3" value="4">
13732	<desc>An IDE controller of the PIIX3 variant.</desc>
13733	</const>
13734	<const name="PIIX4" value="5">
13735	<desc>An IDE controller of the PIIX4 variant.</desc>
13736	</const>
13737	<const name="ICH6" value="6">
13738	<desc>An IDE controller of the ICH6 variant.</desc>
13739	</const>
13740	<const name="I82078" value="7">
13741	<desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
13742	</const>
13743	<const name="LsiLogicSas" value="8">
13744	<desc>A variant of the LsiLogic controller using SAS.</desc>
13745	</const>
13746	</enum>
13747
13748	<interface
13749	name="IStorageController" extends="$unknown"
13750	uuid="7635f4ec-8a28-44b5-9223-315a87b710fb"
13751	wsmap="managed"
13752	>
13753	<desc>
13754	Represents a storage controller that is attached to a virtual machine
13755	(<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
13756	attached to storage controllers in a real computer, virtual drives
13757	(represented by <link to="IMediumAttachment" />) are attached to virtual
13758	storage controllers, represented by this interface.
13759
13760	As opposed to physical hardware, VirtualBox has a very generic concept
13761	of a storage controller, and for purposes of the Main API, all virtual
13762	storage is attached to virtual machines via instances of this interface.
13763	There are four types of such virtual storage controllers: IDE, SCSI, SATA
13764	and Floppy (see <link to="#bus" />). Depending on which of these four is
13765	used, certain sub-types may be available and can be selected in
13766	<link to="#controllerType" />.
13767
13768	Depending on these settings, the guest operating system might see
13769	significantly different virtual hardware.
13770	</desc>
13771
13772	<attribute name="name" type="wstring" readonly="yes">
13773	<desc>
13774	Name of the storage controller, as originally specified with
13775	<link to="IMachine::addStorageController" />. This then uniquely
13776	identifies this controller with other method calls such as
13777	<link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
13778	</desc>
13779	</attribute>
13780
13781	<attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
13782	<desc>
13783	Maximum number of devices which can be attached to one port.
13784	</desc>
13785	</attribute>
13786
13787	<attribute name="minPortCount" type="unsigned long" readonly="yes">
13788	<desc>
13789	Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
13790	</desc>
13791	</attribute>
13792
13793	<attribute name="maxPortCount" type="unsigned long" readonly="yes">
13794	<desc>
13795	Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
13796	</desc>
13797	</attribute>
13798
13799	<attribute name="instance" type="unsigned long">
13800	<desc>
13801	The instance number of the device in the running VM.
13802	</desc>
13803	</attribute>
13804
13805	<attribute name="portCount" type="unsigned long">
13806	<desc>
13807	The number of currently usable ports on the controller.
13808	The minimum and maximum number of ports for one controller are
13809	stored in <link to="IStorageController::minPortCount"/>
13810	and <link to="IStorageController::maxPortCount"/>.
13811	</desc>
13812	</attribute>
13813
13814	<attribute name="bus" type="StorageBus" readonly="yes">
13815	<desc>
13816	The bus type of the storage controller (IDE, SATA, SCSI or Floppy).
13817	</desc>
13818	</attribute>
13819
13820	<attribute name="controllerType" type="StorageControllerType">
13821	<desc>
13822	The exact variant of storage controller hardware presented
13823	to the guest.
13824	Depending on this value, VirtualBox will provide a different
13825	virtual storage controller hardware to the guest.
13826	For SATA and floppy controllers, only one variant is available,
13827	but for IDE and SCSI, there are several.
13828
13829	For SCSI controllers, the default type is LsiLogic.
13830	</desc>
13831	</attribute>
13832
13833	<attribute name="ioBackend" type="IoBackendType">
13834	<desc>
13835	The I/O backend to use for the given storage controller.
13836	</desc>
13837	</attribute>
13838
13839	<method name="getIDEEmulationPort">
13840	<desc>
13841	Gets the corresponding port number which is emulated as an IDE device.
13842	Works only with SATA controllers.
13843
13844	<result name="E_INVALIDARG">
13845	The @a devicePosition is not in the range 0 to 3.
13846	</result>
13847	<result name="E_NOTIMPL">
13848	The storage controller type is not SATAIntelAhci.
13849	</result>
13850
13851	</desc>
13852	<param name="devicePosition" type="long" dir="in"/>
13853	<param name="portNumber" type="long" dir="return"/>
13854	</method>
13855
13856	<method name="setIDEEmulationPort">
13857	<desc>
13858	Sets the port number which is emulated as an IDE device.
13859	Works only with SATA controllers.
13860
13861	<result name="E_INVALIDARG">
13862	The @a devicePosition is not in the range 0 to 3 or the
13863	@a portNumber is not in the range 0 to 29.
13864	</result>
13865	<result name="E_NOTIMPL">
13866	The storage controller type is not SATAIntelAhci.
13867	</result>
13868
13869	</desc>
13870	<param name="devicePosition" type="long" dir="in"/>
13871	<param name="portNumber" type="long" dir="in"/>
13872	</method>
13873
13874	</interface>
13875
13876	<if target="wsdl">
13877
13878	<!--
13879	// IManagedObjectRef
13880	/////////////////////////////////////////////////////////////////////////
13881	-->
13882
13883	<interface
13884	name="IManagedObjectRef" extends="$unknown"
13885	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
13886	internal="yes"
13887	wsmap="managed"
13888	wscpp="hardcoded"
13889	>
13890	<desc>
13891	Managed object reference.
13892
13893	Only within the webservice, a managed object reference (which is really
13894	an opaque number) allows a webservice client to address an object
13895	that lives in the address space of the webservice server.
13896
13897	Behind each managed object reference, there is a COM object that lives
13898	in the webservice server's address space. The COM object is not freed
13899	until the managed object reference is released, either by an explicit
13900	call to <link to="IManagedObjectRef::release" /> or by logging off from
13901	the webservice (<link to="IWebsessionManager::logoff" />), which releases
13902	all objects created during the webservice session.
13903
13904	Whenever a method call of the VirtualBox API returns a COM object, the
13905	webservice representation of that method will instead return a
13906	managed object reference, which can then be used to invoke methods
13907	on that object.
13908	</desc>
13909
13910	<method name="getInterfaceName">
13911	<desc>
13912	Returns the name of the interface that this managed object represents,
13913	for example, "IMachine", as a string.
13914	</desc>
13915	<param name="return" type="wstring" dir="return"/>
13916	</method>
13917
13918	<method name="release">
13919	<desc>
13920	Releases this managed object reference and frees the resources that
13921	were allocated for it in the webservice server process. After calling
13922	this method, the identifier of the reference can no longer be used.
13923	</desc>
13924	</method>
13925
13926	</interface>
13927
13928	<!--
13929	// IWebsessionManager
13930	/////////////////////////////////////////////////////////////////////////
13931	-->
13932
13933	<interface
13934	name="IWebsessionManager" extends="$unknown"
13935	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
13936	internal="yes"
13937	wsmap="global"
13938	wscpp="hardcoded"
13939	>
13940	<desc>
13941	Websession manager. This provides essential services
13942	to webservice clients.
13943	</desc>
13944	<method name="logon">
13945	<desc>
13946	Logs a new client onto the webservice and returns a managed object reference to
13947	the IVirtualBox instance, which the client can then use as a basis to further
13948	queries, since all calls to the VirtualBox API are based on the IVirtualBox
13949	interface, in one way or the other.
13950	</desc>
13951	<param name="username" type="wstring" dir="in"/>
13952	<param name="password" type="wstring" dir="in"/>
13953	<param name="return" type="IVirtualBox" dir="return"/>
13954	</method>
13955
13956	<method name="getSessionObject">
13957	<desc>
13958	Returns a managed object reference to the internal ISession object that was created
13959	for this web service session when the client logged on.
13960
13961	<see>ISession</see>
13962	</desc>
13963	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13964	<param name="return" type="ISession" dir="return"/>
13965	</method>
13966
13967	<method name="logoff">
13968	<desc>
13969	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
13970	and destroys all resources associated with the session (most importantly, all
13971	managed objects created in the server while the session was active).
13972	</desc>
13973	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
13974	</method>
13975
13976	</interface>
13977
13978	</if>
13979
13980	<!--
13981	// IPerformanceCollector & friends
13982	/////////////////////////////////////////////////////////////////////////
13983	-->
13984
13985	<interface
13986	name="IPerformanceMetric" extends="$unknown"
13987	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
13988	>
13989	<desc>
13990	The IPerformanceMetric interface represents parameters of the given
13991	performance metric.
13992	</desc>
13993
13994	<attribute name="metricName" type="wstring" readonly="yes">
13995	<desc>
13996	Name of the metric.
13997	</desc>
13998	</attribute>
13999
14000	<attribute name="object" type="$unknown" readonly="yes">
14001	<desc>
14002	Object this metric belongs to.
14003	</desc>
14004	</attribute>
14005
14006	<attribute name="description" type="wstring" readonly="yes">
14007	<desc>
14008	Textual description of the metric.
14009	</desc>
14010	</attribute>
14011
14012	<attribute name="period" type="unsigned long" readonly="yes">
14013	<desc>
14014	Time interval between samples, measured in seconds.
14015	</desc>
14016	</attribute>
14017
14018	<attribute name="count" type="unsigned long" readonly="yes">
14019	<desc>
14020	Number of recent samples retained by the performance collector for this
14021	metric.
14022
14023	When the collected sample count exceeds this number, older samples
14024	are discarded.
14025	</desc>
14026	</attribute>
14027
14028	<attribute name="unit" type="wstring" readonly="yes">
14029	<desc>
14030	Unit of measurement.
14031	</desc>
14032	</attribute>
14033
14034	<attribute name="minimumValue" type="long" readonly="yes">
14035	<desc>
14036	Minimum possible value of this metric.
14037	</desc>
14038	</attribute>
14039
14040	<attribute name="maximumValue" type="long" readonly="yes">
14041	<desc>
14042	Maximum possible value of this metric.
14043	</desc>
14044	</attribute>
14045	</interface>
14046
14047	<interface
14048	name="IPerformanceCollector" extends="$unknown"
14049	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
14050	wsmap="managed"
14051	>
14052	<desc>
14053	The IPerformanceCollector interface represents a service that collects
14054	and stores performance metrics data.
14055
14056	Performance metrics are associated with objects of interfaces like IHost
14057	and IMachine. Each object has a distinct set of performance metrics. The
14058	set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
14059
14060	Metric data is collected at the specified intervals and is retained
14061	internally. The interval and the number of retained samples can be set
14062	with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
14063	and collection settings are not persistent, they are discarded as soon as
14064	VBoxSVC process terminates. Moreover, metric settings and data associated
14065	with a particular VM only exist while VM is running. They disappear as
14066	soon as VM shuts down. It is not possible to set up metrics for machines
14067	that are powered off. One needs to start VM first, then set up metric
14068	collection parameters.
14069
14070	Metrics are organized hierarchically, with each level separated by a
14071	slash (/) character. Generally, the scheme for metric names is like this:
14072
14073	<tt>Category/Metric[/SubMetric][:aggregation]</tt>
14074
14075	"Category/Metric" together form the base metric name. A base metric is
14076	the smallest unit for which a sampling interval and the number of
14077	retained samples can be set. Only base metrics can be enabled and
14078	disabled. All sub-metrics are collected when their base metric is
14079	collected. Collected values for any set of sub-metrics can be queried
14080	with <link to="IPerformanceCollector::queryMetricsData" />.
14081
14082	For example "CPU/Load/User:avg" metric name stands for the "CPU"
14083	category, "Load" metric, "User" submetric, "average" aggregate. An
14084	aggregate function is computed over all retained data. Valid aggregate
14085	functions are:
14086
14087	<ul>
14088	<li>avg -- average</li>
14089	<li>min -- minimum</li>
14090	<li>max -- maximum</li>
14091	</ul>
14092
14093	When setting up metric parameters, querying metric data, enabling or
14094	disabling metrics wildcards can be used in metric names to specify a
14095	subset of metrics. For example, to select all CPU-related metrics
14096	use <tt>CPU/</tt>, all averages can be queried using <tt>:avg</tt> and
14097	so on. To query metric values without aggregates <tt>*:</tt> can be used.
14098
14099	The valid names for base metrics are:
14100
14101	<ul>
14102	<li>CPU/Load</li>
14103	<li>CPU/MHz</li>
14104	<li>RAM/Usage</li>
14105	</ul>
14106
14107	The general sequence for collecting and retrieving the metrics is:
14108	<ul>
14109	<li>
14110	Obtain an instance of IPerformanceCollector with
14111	<link to="IVirtualBox::performanceCollector" />
14112	</li>
14113	<li>
14114	Allocate and populate an array with references to objects the metrics
14115	will be collected for. Use references to IHost and IMachine objects.
14116	</li>
14117	<li>
14118	Allocate and populate an array with base metric names the data will
14119	be collected for.
14120	</li>
14121	<li>
14122	Call <link to="IPerformanceCollector::setupMetrics" />. From now on
14123	the metric data will be collected and stored.
14124	</li>
14125	<li>
14126	Wait for the data to get collected.
14127	</li>
14128	<li>
14129	Allocate and populate an array with references to objects the metric
14130	values will be queried for. You can re-use the object array used for
14131	setting base metrics.
14132	</li>
14133	<li>
14134	Allocate and populate an array with metric names the data will be
14135	collected for. Note that metric names differ from base metric names.
14136	</li>
14137	<li>
14138	Call <link to="IPerformanceCollector::queryMetricsData" />. The data
14139	that have been collected so far are returned. Note that the values
14140	are still retained internally and data collection continues.
14141	</li>
14142	</ul>
14143
14144	For an example of usage refer to the following files in VirtualBox SDK:
14145	<ul>
14146	<li>
14147	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
14148	</li>
14149	<li>
14150	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
14151	</li>
14152	</ul>
14153	</desc>
14154
14155	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
14156	<desc>
14157	Array of unique names of metrics.
14158
14159	This array represents all metrics supported by the performance
14160	collector. Individual objects do not necessarily support all of them.
14161	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
14162	list of supported metrics for a particular object.
14163	</desc>
14164	</attribute>
14165
14166	<method name="getMetrics">
14167	<desc>
14168	Returns parameters of specified metrics for a set of objects.
14169	<note>
14170	@c Null metrics array means all metrics. @c Null object array means
14171	all existing objects.
14172	</note>
14173	</desc>
14174	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14175	<desc>
14176	Metric name filter. Currently, only a comma-separated list of metrics
14177	is supported.
14178	</desc>
14179	</param>
14180	<param name="objects" type="$unknown" dir="in" safearray="yes">
14181	<desc>
14182	Set of objects to return metric parameters for.
14183	</desc>
14184	</param>
14185	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
14186	<desc>
14187	Array of returned metric parameters.
14188	</desc>
14189	</param>
14190	</method>
14191
14192	<method name="setupMetrics">
14193	<desc>
14194	Sets parameters of specified base metrics for a set of objects. Returns
14195	an array of <link to="IPerformanceMetric" /> describing the metrics
14196	have been affected.
14197	<note>
14198	@c Null or empty metric name array means all metrics. @c Null or
14199	empty object array means all existing objects. If metric name array
14200	contains a single element and object array contains many, the single
14201	metric name array element is applied to each object array element to
14202	form metric/object pairs.
14203	</note>
14204	</desc>
14205	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14206	<desc>
14207	Metric name filter. Comma-separated list of metrics with wildcard
14208	support.
14209	</desc>
14210	</param>
14211	<param name="objects" type="$unknown" dir="in" safearray="yes">
14212	<desc>
14213	Set of objects to setup metric parameters for.
14214	</desc>
14215	</param>
14216	<param name="period" type="unsigned long" dir="in">
14217	<desc>
14218	Time interval in seconds between two consecutive samples of
14219	performance data.
14220	</desc>
14221	</param>
14222	<param name="count" type="unsigned long" dir="in">
14223	<desc>
14224	Number of samples to retain in performance data history. Older
14225	samples get discarded.
14226	</desc>
14227	</param>
14228	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14229	<desc>
14230	Array of metrics that have been modified by the call to this method.
14231	</desc>
14232	</param>
14233	</method>
14234
14235	<method name="enableMetrics">
14236	<desc>
14237	Turns on collecting specified base metrics. Returns an array of
14238	<link to="IPerformanceMetric" /> describing the metrics have been
14239	affected.
14240	<note>
14241	@c Null or empty metric name array means all metrics. @c Null or
14242	empty object array means all existing objects. If metric name array
14243	contains a single element and object array contains many, the single
14244	metric name array element is applied to each object array element to
14245	form metric/object pairs.
14246	</note>
14247	</desc>
14248	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14249	<desc>
14250	Metric name filter. Comma-separated list of metrics with wildcard
14251	support.
14252	</desc>
14253	</param>
14254	<param name="objects" type="$unknown" dir="in" safearray="yes">
14255	<desc>
14256	Set of objects to enable metrics for.
14257	</desc>
14258	</param>
14259	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14260	<desc>
14261	Array of metrics that have been modified by the call to this method.
14262	</desc>
14263	</param>
14264	</method>
14265
14266	<method name="disableMetrics">
14267	<desc>
14268	Turns off collecting specified base metrics. Returns an array of
14269	<link to="IPerformanceMetric" /> describing the metrics have been
14270	affected.
14271	<note>
14272	@c Null or empty metric name array means all metrics. @c Null or
14273	empty object array means all existing objects. If metric name array
14274	contains a single element and object array contains many, the single
14275	metric name array element is applied to each object array element to
14276	form metric/object pairs.
14277	</note>
14278	</desc>
14279	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14280	<desc>
14281	Metric name filter. Comma-separated list of metrics with wildcard
14282	support.
14283	</desc>
14284	</param>
14285	<param name="objects" type="$unknown" dir="in" safearray="yes">
14286	<desc>
14287	Set of objects to disable metrics for.
14288	</desc>
14289	</param>
14290	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
14291	<desc>
14292	Array of metrics that have been modified by the call to this method.
14293	</desc>
14294	</param>
14295	</method>
14296
14297	<method name="queryMetricsData">
14298	<desc>
14299	Queries collected metrics data for a set of objects.
14300
14301	The data itself and related metric information are returned in seven
14302	parallel and one flattened array of arrays. Elements of
14303	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
14304	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
14305	the same index describe one set of values corresponding to a single
14306	metric.
14307
14308	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
14309	start and length of a sub-array is indicated by
14310	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
14311	value for metric <tt>metricNames[i]</tt> is at
14312	<tt>returnData[returnIndices[i]]</tt>.
14313
14314	<note>
14315	@c Null or empty metric name array means all metrics. @c Null or
14316	empty object array means all existing objects. If metric name array
14317	contains a single element and object array contains many, the single
14318	metric name array element is applied to each object array element to
14319	form metric/object pairs.
14320	</note>
14321	<note>
14322	Data collection continues behind the scenes after call to @c
14323	queryMetricsData. The return data can be seen as the snapshot of the
14324	current state at the time of @c queryMetricsData call. The internally
14325	kept metric values are not cleared by the call. This makes possible
14326	querying different subsets of metrics or aggregates with subsequent
14327	calls. If periodic querying is needed it is highly suggested to query
14328	the values with @c interval*count period to avoid confusion. This way
14329	a completely new set of data values will be provided by each query.
14330	</note>
14331	</desc>
14332	<param name="metricNames" type="wstring" dir="in" safearray="yes">
14333	<desc>
14334	Metric name filter. Comma-separated list of metrics with wildcard
14335	support.
14336	</desc>
14337	</param>
14338	<param name="objects" type="$unknown" dir="in" safearray="yes">
14339	<desc>
14340	Set of objects to query metrics for.
14341	</desc>
14342	</param>
14343	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
14344	<desc>
14345	Names of metrics returned in @c returnData.
14346	</desc>
14347	</param>
14348	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
14349	<desc>
14350	Objects associated with metrics returned in @c returnData.
14351	</desc>
14352	</param>
14353	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
14354	<desc>
14355	Units of measurement for each returned metric.
14356	</desc>
14357	</param>
14358	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
14359	<desc>
14360	Divisor that should be applied to return values in order to get
14361	floating point values. For example:
14362	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
14363	will retrieve the floating point value of i-th sample of the first
14364	metric.
14365	</desc>
14366	</param>
14367	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
14368	<desc>
14369	Sequence numbers of the first elements of value sequences of
14370	particular metrics returned in @c returnData. For aggregate metrics
14371	it is the sequence number of the sample the aggregate started
14372	calculation from.
14373	</desc>
14374	</param>
14375	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
14376	<desc>
14377	Indices of the first elements of value sequences of particular
14378	metrics returned in @c returnData.
14379	</desc>
14380	</param>
14381	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
14382	<desc>
14383	Lengths of value sequences of particular metrics.
14384	</desc>
14385	</param>
14386	<param name="returnData" type="long" dir="return" safearray="yes">
14387	<desc>
14388	Flattened array of all metric data containing sequences of values for
14389	each metric.
14390	</desc>
14391	</param>
14392	</method>
14393
14394	</interface>
14395	<enum
14396	name="NATAliasMode"
14397	uuid="67772168-50d9-11df-9669-7fb714ee4fa1">
14398	<desc></desc>
14399	<const name="AliasLog" value="0x1">
14400	<desc></desc>
14401	</const>
14402	<const name="AliasProxyOnly" value="0x02">
14403	<desc></desc>
14404	</const>
14405	<const name="AliasUseSamePorts" value="0x04">
14406	<desc></desc>
14407	</const>
14408	</enum>
14409	<enum
14410	name="NATProtocol"
14411	uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
14412	>
14413	<desc>Protocol definitions used with NAT port-forwarding rules.</desc>
14414	<const name="UDP" value="0">
14415	<desc>Port-forwarding uses UDP protocol.</desc>
14416	</const>
14417	<const name="TCP" value="1">
14418	<desc>Port-forwarding uses TCP protocol.</desc>
14419	</const>
14420	</enum>
14421
14422	<interface
14423	name="INATEngine" extends="$unknown"
14424	uuid="4b286616-eb03-11de-b0fb-1701eca42246"
14425	wsmap="managed"
14426	>
14427	<desc>Interface for managing a NAT engine which is used with a virtual machine. This
14428	allows for changing NAT behavior such as port-forwarding rules. This interface is
14429	used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
14430	<attribute name="network" type="wstring">
14431	<desc>The network attribute of the NAT engine (the same value is used with built-in
14432	DHCP server to fill corresponding fields of DHCP leases).</desc>
14433	</attribute>
14434	<attribute name="hostIP" type="wstring">
14435	<desc>IP of host interface to bind all opened sockets to.
14436	<note>Changing this does not change binding of port forwarding.</note>
14437	</desc>
14438	</attribute>
14439	<attribute name="tftpPrefix" type="wstring">
14440	<desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
14441	the corresponding fields of DHCP leases.</desc>
14442	</attribute>
14443	<attribute name="tftpBootFile" type="wstring">
14444	<desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
14445	the corresponding fields of DHCP leases.</desc>
14446	</attribute>
14447	<attribute name="tftpNextServer" type="wstring">
14448	<desc>TFTP server attribute which is used with the built-in DHCP server to fill
14449	the corresponding fields of DHCP leases.
14450	<note>The preferred form is IPv4 addresses.</note>
14451	</desc>
14452	</attribute>
14453	<attribute name="aliasMode" type="unsigned long">
14454	<desc></desc>
14455	</attribute>
14456	<attribute name="dnsPassDomain" type="boolean">
14457	<desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
14458	</attribute>
14459	<attribute name="dnsProxy" type="boolean">
14460	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14461	of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
14462	</attribute>
14463	<attribute name="dnsUseHostResolver" type="boolean">
14464	<desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
14465	of the DNS proxy and process traffic using the host resolver mechanism.</desc>
14466	</attribute>
14467	<attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
14468	<desc>Array of NAT port-forwarding rules in string representation, in the following
14469	format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
14470	</attribute>
14471	<method name="setNetworkSettings">
14472	<desc>Sets network configuration of the NAT engine.</desc>
14473	<param name="mtu" type="unsigned long" dir="in">
14474	<desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
14475	</param>
14476	<param name="sockSnd" type="unsigned long" dir="in">
14477	<desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
14478	</param>
14479	<param name="sockRcv" type="unsigned long" dir="in">
14480	<desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
14481	</param>
14482	<param name="TcpWndSnd" type="unsigned long" dir="in">
14483	<desc>Initial size of the NAT engine's sending TCP window in bytes when
14484	establishing a new TCP connection.</desc>
14485	</param>
14486	<param name="TcpWndRcv" type="unsigned long" dir="in">
14487	<desc>Initial size of the NAT engine's receiving TCP window in bytes when
14488	establishing a new TCP connection.</desc>
14489	</param>
14490	</method>
14491	<method name="getNetworkSettings">
14492	<desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
14493	for parameter descriptions.</desc>
14494	<param name="mtu" type="unsigned long" dir="out" />
14495	<param name="sockSnd" type="unsigned long" dir="out" />
14496	<param name="sockRcv" type="unsigned long" dir="out" />
14497	<param name="TcpWndSnd" type="unsigned long" dir="out" />
14498	<param name="TcpWndRcv" type="unsigned long" dir="out" />
14499	</method>
14500	<method name="addRedirect">
14501	<desc>Adds a new NAT port-forwarding rule.</desc>
14502	<param name="name" type="wstring" dir="in">
14503	<desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
14504	auto-generates one using the other parameters.</desc>
14505	</param>
14506	<param name="proto" type="NATProtocol" dir="in">
14507	<desc>Protocol handled with the rule.</desc>
14508	</param>
14509	<param name="hostIp" type="wstring" dir="in">
14510	<desc>IP of the host interface to which the rule should apply. An empty ip address is
14511	acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
14512	</param>
14513	<param name="hostPort" type="unsigned short" dir="in">
14514	<desc>The port number to listen on.</desc>
14515	</param>
14516	<param name="guestIp" type="wstring" dir="in">
14517	<desc>The IP address of the guest which the NAT engine will forward matching packets
14518	to. An empty IP address is acceptable, in which case the NAT engine will forward
14519	packets to the first DHCP lease (x.x.x.15).</desc>
14520	</param>
14521	<param name="guestPort" type="unsigned short" dir="in">
14522	<desc>The port number to forward.</desc>
14523	</param>
14524	</method>
14525	<method name="removeRedirect">
14526	<desc>Removes a port-forwarding rule that was previously registered.</desc>
14527	<param name="name" type="wstring" dir="in">
14528	<desc>The name of the rule to delete.</desc>
14529	</param>
14530	</method>
14531	</interface>
14532
14533	<module name="VBoxSVC" context="LocalServer">
14534	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
14535	namespace="virtualbox.org">
14536	<interface name="IVirtualBox" default="yes"/>
14537	</class>
14538	</module>
14539
14540	<module name="VBoxC" context="InprocServer" threadingModel="Free">
14541	<class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
14542	namespace="virtualbox.org">
14543	<interface name="ISession" default="yes"/>
14544	</class>
14545	<class name="CallbackWrapper" uuid="49EE8561-5563-4715-B18C-A4B1A490DAFE"
14546	namespace="virtualbox.org">
14547	<interface name="ILocalOwner" default="yes"/>
14548	<interface name="IVirtualBoxCallback"/>
14549	<interface name="IConsoleCallback"/>
14550	</class>
14551	</module>
14552
14553	</library>
14554
14555	</idl>
14556
14557	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format