VirtualBox.xidl@ 14658

Last change on this file since 14658 was 14644, checked in by vboxsync, 16 years ago
Document result codes for IHardDisk2::getProperties().
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 405.8 KB

Line
1	<?xml version="1.0" ?>
2
3	<!--
4	* $Id: VirtualBox.xidl 14644 2008-11-26 13:56:52Z vboxsync $ *
5	*
6	* :tabSize=2:indentSize=2:noTabs=true:
7	* :folding=explicit:collapseFolds=1:
8	*
9	* Master declaration for VirtualBox's Main API, represented
10	* by COM/XPCOM and web service interfaces.
11	*
12	* From this document, the build system generates several files
13	* via XSLT that are then used during the build process.
14	*
15	* Below is the list of XSL templates that operate on this file and
16	* output files they generate. These XSL templates must be updated
17	* whenever the schema of this file changes:
18	*
19	* 1. src/VBox/Main/idl/midl.xsl =>
20	* out/<platform>/bin/sdk/idl/VirtualBox.idl
21	* (MS COM interface definition file for Main API)
22	*
23	* 2. src/VBox/Main/idl/xpidl.xsl =>
24	* out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
25	* (XPCOM interface definition file for Main API)
26	*
27	* 3. src/VBox/Main/idl/doxygen.xsl =>
28	* out/<platform>/obj/src/VBox/Main/VirtualBox.idl
29	* (pseudo-IDL for Doxygen to generate the official Main API
30	* documentation)
31	*
32	* 4. src/VBox/Main/webservice/*.xsl =>
33	* a bunch of WSDL and C++ files
34	* (VirtualBox web service sources and SOAP mappers;
35	* see src/VBox/Main/webservice/Makefile.kmk for details)
36	*
37	* 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
38	* out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
39	* (smart Qt-based C++ wrapper classes for COM interfaces
40	* of the Main API)
41	*
42	* 6. src/VBox/Frontends/VirtualBox4/include/COMWrappers.xsl =>
43	* out/<platform>/obj/src/VBox/Frontends/VirtualBox4/VirtualBox/include/COMWrappers.h
44	* (smart Qt-based C++ wrapper classes for COM interfaces
45	* of the Main API)
46	*
47	* 7. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
48	* out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
49	* (Main API TypeLib block for the WiX installer)
50	*
51	* 8. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
52	* out/<platform>/obj/src/VBox/Runtime/errmsgvboxcomdata.h
53	* (<result> extraction for the %Rhrc format specifier)
54	*
55	Copyright (C) 2006-2007 Sun Microsystems, Inc.
56
57	This file is part of VirtualBox Open Source Edition (OSE), as
58	available from http://www.virtualbox.org. This file is free software;
59	you can redistribute it and/or modify it under the terms of the GNU
60	General Public License (GPL) as published by the Free Software
61	Foundation, in version 2 as it comes in the "COPYING" file of the
62	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
63	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
64
65	Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
66	Clara, CA 95054 USA or visit http://www.sun.com if you need
67	additional information or have any questions.
68	-->
69
70	<idl>
71
72	<desc>
73	Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
74	describes the so-called <i>VirtualBox Main API</i> which comprises all public
75	COM interfaces and components provided by the VirtualBox server and by the
76	VirtualBox client library.
77
78	VirtualBox employs a client-server design, meaning that whenever any part of
79	VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
80	interface or any virtual machine --, a dedicated server process named
81	VBoxSVC runs in the background. This allows multiple processes working with
82	VirtualBox to cooperate without conflicts. These processes communicate to each
83	other using inter-process communication facilities provided by the COM
84	implementation of the host computer.
85
86	On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
87	implementation. On all other platforms, Mozilla XPCOM, an open-source COM
88	implementation, is used.
89
90	All the parts that a typical VirtualBox user interacts with (the Qt GUI,
91	the VBoxManage command-line interface and the VBoxVRDP server) are technically
92	front-ends to the Main API and only use the interfaces that are documented
93	in this Main API documentation. This ensures that, with any given release
94	version of VirtualBox, all capabilities of the product that could be useful
95	to an external client program are always exposed by way of this API.
96
97	The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
98	contains two public component classes:
99	<tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
100	implement IVirtualBox and ISession interfaces respectively. These two classes
101	are of supreme importance and will be needed in order for any front-end
102	program to do anything useful. It is recommended to read the documentation of
103	the mentioned interfaces first.
104
105	The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
106	there can be only one object of this class on the local machine at any given
107	time. This object is a parent of many other objects ih the VirtualBox COM
108	library and lives in the VBoxSVC process. In fact, when you create an instance
109	of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
110	process is already running, starts it if not, and returns you a reference to
111	the<tt>VirtualBox</tt> object created in this process. When the last reference
112	to this object is released, the VBoxSVC process ends (with a 5 second delay to
113	protect from too frequent restarts).
114
115	The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
116	as many <tt>Session</tt> objects as you need but all of them will live in a
117	process which issues the object instantiation call. <tt>Session</tt> objects
118	represent virtual machine sessions which are used to configure virtual
119	machines and control their execution.
120	</desc>
121
122	<if target="midl">
123	<cpp line="enum {"/>
124	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
125	<cpp line=" kTypeLibraryMinorVersion = 0"/>
126	<cpp line="};"/>
127	</if>
128
129	<if target="xpidl">
130	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
131	<cpp>
132	/* currently, nsISupportsImpl.h lacks the below-like macros */
133
134	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
135	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
136
137	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
138	# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
139	NS_IMPL_THREADSAFE_ADDREF(_class) \
140	NS_IMPL_THREADSAFE_RELEASE(_class) \
141	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
142	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
143	#endif
144
145	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
146	# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
147	NS_IMPL_THREADSAFE_ADDREF(_class) \
148	NS_IMPL_THREADSAFE_RELEASE(_class) \
149	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
150	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
151	#endif
152
153	#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
154	# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
155	NS_INTERFACE_MAP_BEGIN(_class) \
156	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
157	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
158	NS_IMPL_QUERY_CLASSINFO(_class) \
159	NS_INTERFACE_MAP_END
160	#endif
161
162	#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
163	# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
164	_i2, _ic2) \
165	NS_INTERFACE_MAP_BEGIN(_class) \
166	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
167	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
168	NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
169	NS_IMPL_QUERY_CLASSINFO(_class) \
170	NS_INTERFACE_MAP_END
171	#endif
172
173	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
174	#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
175
176	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
177	# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
178	NS_IMPL_THREADSAFE_ADDREF(_class) \
179	NS_IMPL_THREADSAFE_RELEASE(_class) \
180	NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
181	NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
182	#endif
183
184	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
185	# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
186	_i2, _ic2) \
187	NS_IMPL_THREADSAFE_ADDREF(_class) \
188	NS_IMPL_THREADSAFE_RELEASE(_class) \
189	NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
190	_i2, _ic2) \
191	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
192	#endif
193	</cpp>
194	</if>
195
196	<library
197	name="VirtualBox"
198	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
199	version="1.3"
200	desc="VirtualBox Type Library"
201	appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
202	supportsErrorInfo="yes"
203	>
204
205
206	<!--
207	// COM result codes for VirtualBox
208	/////////////////////////////////////////////////////////////////////////
209	-->
210
211	<descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
212	<desc>
213	This section describes all VirtualBox-specific COM result codes that may
214	be returned by methods of VirtualBox COM interfaces in addition to
215	standard COM result codes.
216
217	Note that along with the result code, every VirtualBox method returns
218	extended error information through the IVirtualBoxErrorInfo interface on
219	failure. This interface is a preferred way to present the error to the end
220	user because it contains a human readable description of the error. Raw
221	result codes, both standard and described in this section, are intended to
222	be used by programs to analyze the reason of a failure and select an
223	appropriate course of action without involving the end user (for example,
224	retry the operation later or make a different call).
225
226	The standard COM result codes that may originate from our methods include:
227
228	<table>
229	<tr><td>E_INVALIDARG</td>
230	<td>
231	Returned when the value of the method's argument is not within the range
232	of valid values. This should not be confused with situations when the
233	value is within the range but simply doesn't suit the current object
234	state and there is a possibility that it will be accepted later (in such
235	cases VirtualBox-specific codes are returned, for example,
236	<link to="VBOX_E_OBJECT_NOT_FOUND"/>).
237	</td>
238	</tr>
239	<tr><td>E_POINTER</td>
240	<td>
241	Returned if a memory pointer for the output argument is invalid (for
242	example, <tt>NULL</tt>). Note that when pointers representing input
243	arguments (such as strings) are invalid, E_INVALIDARG is returned.
244	</td>
245	</tr>
246	<tr><td>E_ACCESSDENIED</td>
247	<td>
248	Returned when the called object is not ready. Since the lifetime of a
249	public COM object cannot be fully controlled by the implementation,
250	VirtualBox maintains the readiness state for all objects it creates and
251	returns this code in response to any method call on the object that was
252	deactivated by VirtualBox and is not functioning any more.
253	</td>
254	</tr>
255	<tr><td>E_OUTOFMEMORY</td>
256	<td>
257	Returned when a memory allocation operation fails.
258	</td>
259	</tr>
260	</table>
261	</desc>
262	</descGroup>
263
264	<!--
265	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
266	everything in <result>/<desc> after (and including) the first dot, so express
267	the matter of the error code in the first sentence and keep it short.
268	-->
269
270	<result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
271	<desc>
272	Object corresponding to the supplied arguments does not exist.
273	</desc>
274	</result>
275
276	<result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
277	<desc>
278	Current virtual machine state prevents the operation.
279	</desc>
280	</result>
281
282	<result name="VBOX_E_VM_ERROR" value="0x80BB0003">
283	<desc>
284	Virtual machine error occurred attempting the operation.
285	</desc>
286	</result>
287
288	<result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
289	<desc>
290	File not accessible or erroneous file contents.
291	</desc>
292	</result>
293
294	<result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
295	<desc>
296	Runtime subsystem error.
297	</desc>
298	</result>
299
300	<result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
301	<desc>
302	Pluggable Device Manager error.
303	</desc>
304	</result>
305
306	<!--
307	Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
308	everything in <result>/<desc> after (and including) the first dot, so express
309	the matter of the error code in the first sentence and keep it short.
310	-->
311
312	<descGroup/>
313
314	<!--
315	// all common enums
316	/////////////////////////////////////////////////////////////////////////
317	-->
318
319	<enum
320	name="TSBool"
321	uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
322	>
323	<desc>
324	Boolean variable having a third state, default.
325	</desc>
326
327	<const name="False" value="0"/>
328	<const name="True" value="1"/>
329	<const name="Default" value="2"/>
330	</enum>
331
332	<enum
333	name="MachineState"
334	uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
335	>
336	<desc>
337	Virtual machine execution state. This enumeration represents possible
338	values of the <link to="IMachine::state"/> attribute.
339	</desc>
340
341	<const name="Null" value="0">
342	<desc><tt>null</tt> value. Never used by the API.</desc>
343	</const>
344	<const name="PoweredOff" value="1">
345	<desc>
346	The machine is not running.
347	</desc>
348	</const>
349	<const name="Saved" value="2">
350	<desc>
351	The machine is not currently running, but the execution state
352	of the machine has been saved to an external file when it
353	was running.
354	<note>
355	Only a few machine settings can be altered when the machine
356	is in this state.
357	</note>
358	</desc>
359	</const>
360	<const name="Aborted" value="3">
361	<desc>
362	A process running the machine has terminated abnormally.
363	Other than that, this value is equivalent to #PoweredOff.
364	</desc>
365	</const>
366	<const name="Running" value="4">
367	<desc>
368	The machine is currently being executed.
369	<note>
370	This value can be used in relational expressions:
371	all state values less than Running describe a virtual machine that is
372	not currently being executed (i.e., it is completely out of
373	action).
374	</note>
375	<note internal="yes">
376	For whoever decides to touch this enum: In order to keep the
377	aforementioned comparisons valid, this state must immediately
378	precede the Paused state.
379	</note>
380	</desc>
381	</const>
382	<const name="Paused" value="5">
383	<desc>
384	Execution of the machine has been paused.
385	<note>
386	This value can be used in relational expressions: all state values
387	greater than Paused represent unstable states of the running virtual
388	machine. Unless explicitly stated otherwise, no machine settings can
389	be altered when it is in one of the unstable states.
390	</note>
391	<note internal="yes">
392	For whoever decides to touch this enum: In order to keep the
393	aforementioned comparisons valid, this state must immediately
394	follow the Running state.
395	</note>
396	</desc>
397	</const>
398	<const name="Stuck" value="6">
399	<desc>
400	Execution of the machine has reached the "Guru Meditation"
401	condition. This condition indicates an internal VMM failure which may
402	happen as a result of either an unhandled low-level virtual hardware
403	exception or one of the recompiler exceptions (such as
404	the <i>too-many-traps</i> condition).
405	</desc>
406	</const>
407	<const name="Starting" value="7">
408	<desc>
409	Machine is being started after
410	<link to="IConsole::powerUp">powering it on</link> from a
411	zero execution state.
412	</desc>
413	</const>
414	<const name="Stopping" value="8">
415	<desc>
416	Machine is being normally stopped
417	(after explicitly <link to="IConsole::powerDown">powering it off</link>,
418	or after the guest OS has initiated a shutdown sequence).
419	</desc>
420	</const>
421	<const name="Saving" value="9">
422	<desc>
423	Machine is saving its execution state to a file as a
424	result of calling <link to="IConsole::saveState"/> or an online
425	snapshot of the machine is being taken using
426	<link to="IConsole::takeSnapshot"/>.
427	</desc>
428	</const>
429	<const name="Restoring" value="10">
430	<desc>
431	Execution state of the machine is being restored from a file
432	after <link to="IConsole::powerUp">powering it on</link> from
433	a saved execution state.
434	</desc>
435	</const>
436	<const name="Discarding" value="11">
437	<desc>
438	Snapshot of the machine is being discarded after calling
439	<link to="IConsole::discardSnapshot"/> or its current state is
440	being discarded after <link to="IConsole::discardCurrentState"/>.
441	</desc>
442	</const>
443	<const name="SettingUp" value="12">
444	<desc>
445	Lengthy setup operation is in progress (e.g.
446	<link to="IMachine::attachHardDisk2"/>).
447	</desc>
448	</const>
449	</enum>
450
451	<enum
452	name="SessionState"
453	uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
454	>
455	<desc>
456	Session state. This enumeration represents possible values of
457	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
458	attributes. Individual value descriptions contain the appropriate
459	meaning for every case.
460	</desc>
461
462	<const name="Null" value="0">
463	<desc><tt>null</tt> value. Never used by the API.</desc>
464	</const>
465	<const name="Closed" value="1">
466	<desc>
467	The machine has no open sessions (<link to="IMachine::sessionState"/>);
468	the session is closed (<link to="ISession::state"/>)
469	</desc>
470	</const>
471	<const name="Open" value="2">
472	<desc>
473	The machine has an open direct session (<link to="IMachine::sessionState"/>);
474	the session is open (<link to="ISession::state"/>)
475	</desc>
476	</const>
477	<const name="Spawning" value="3">
478	<desc>
479	A new (direct) session is being opened for the machine
480	as a result of <link to="IVirtualBox::openRemoteSession()"/>
481	call (<link to="IMachine::sessionState"/>);
482	the session is currently being opened
483	as a result of <link to="IVirtualBox::openRemoteSession()"/>
484	call (<link to="ISession::state"/>)
485	</desc>
486	</const>
487	<const name="Closing" value="4">
488	<desc>
489	The direct session is being closed (<link to="IMachine::sessionState"/>);
490	the session is being closed (<link to="ISession::state"/>)
491	</desc>
492	</const>
493	</enum>
494
495	<enum
496	name="SessionType"
497	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
498	>
499	<desc>
500	Session type. This enumeration represents possible values of the
501	<link to="ISession::type"/> attribute.
502	</desc>
503
504	<const name="Null" value="0">
505	<desc><tt>null</tt> value. Never used by the API.</desc>
506	</const>
507	<const name="Direct" value="1">
508	<desc>
509	Direct session
510	(opened by <link to="IVirtualBox::openSession()"/>)
511	</desc>
512	</const>
513	<const name="Remote" value="2">
514	<desc>
515	Remote session
516	(opened by <link to="IVirtualBox::openRemoteSession()"/>)
517	</desc>
518	</const>
519	<const name="Existing" value="3">
520	<desc>
521	Existing session
522	(opened by <link to="IVirtualBox::openExistingSession()"/>)
523	</desc>
524	</const>
525	</enum>
526
527	<enum
528	name="DeviceType"
529	uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
530	>
531	<desc>
532	Device type.
533	</desc>
534	<const name="Null" value="0">
535	<desc>
536	<tt>null</tt> value which may also mean "no device".
537	<note>
538	This value is not allowed for
539	<link to="IConsole::getDeviceActivity"/>
540	</note>
541	</desc>
542	</const>
543	<const name="Floppy" value="1">
544	<desc>Floppy device.</desc>
545	</const>
546	<const name="DVD" value="2">
547	<desc>CD/DVD-ROM device.</desc>
548	</const>
549	<const name="HardDisk" value="3">
550	<desc>Hard disk device.</desc>
551	</const>
552	<const name="Network" value="4">
553	<desc>Network device.</desc>
554	</const>
555	<const name="USB" value="5">
556	<desc>USB device.</desc>
557	</const>
558	<const name="SharedFolder" value="6">
559	<desc>Shared folder device.</desc>
560	</const>
561	</enum>
562
563	<enum
564	name="DeviceActivity"
565	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
566	>
567	<desc>
568	Device activity for <link to="IConsole::getDeviceActivity"/>.
569	</desc>
570
571	<const name="Null" value="0"/>
572	<const name="Idle" value="1"/>
573	<const name="Reading" value="2"/>
574	<const name="Writing" value="3"/>
575	</enum>
576
577	<enum
578	name="StorageBus"
579	uuid="715984a5-093c-43bb-aa42-a16ed16828dd"
580	>
581	<desc>Interface bus type for storage devices.</desc>
582
583	<const name="Null" value="0">
584	<desc><tt>null</tt> value. Never used by the API.</desc>
585	</const>
586
587	<const name="IDE" value="1"/>
588	<const name="SATA" value="2"/>
589	</enum>
590
591	<enum
592	name="ClipboardMode"
593	uuid="33364716-4008-4701-8f14-be0fa3d62950"
594	>
595	<desc>
596	Host-Guest clipboard interchange mode.
597	</desc>
598
599	<const name="Disabled" value="0"/>
600	<const name="HostToGuest" value="1"/>
601	<const name="GuestToHost" value="2"/>
602	<const name="Bidirectional" value="3"/>
603	</enum>
604
605	<enum
606	name="Scope"
607	uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
608	>
609	<desc>
610	Scope of the operation.
611
612	A generic enumeration used in various methods to define the action or
613	argument scope.
614	</desc>
615
616	<const name="Global" value="0"/>
617	<const name="Machine" value="1"/>
618	<const name="Session" value="2"/>
619	</enum>
620
621	<enum
622	name="GuestStatisticType"
623	uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
624	>
625	<desc>
626	Statistics type for <link to="IGuest::getStatistic"/>.
627	</desc>
628
629	<const name="CPULoad_Idle" value="0">
630	<desc>
631	Idle CPU load (0-100%) for last interval.
632	</desc>
633	</const>
634	<const name="CPULoad_Kernel" value="1">
635	<desc>
636	Kernel CPU load (0-100%) for last interval.
637	</desc>
638	</const>
639	<const name="CPULoad_User" value="2">
640	<desc>
641	User CPU load (0-100%) for last interval.
642	</desc>
643	</const>
644	<const name="Threads" value="3">
645	<desc>
646	Total number of threads in the system.
647	</desc>
648	</const>
649	<const name="Processes" value="4">
650	<desc>
651	Total number of processes in the system.
652	</desc>
653	</const>
654	<const name="Handles" value="5">
655	<desc>
656	Total number of handles in the system.
657	</desc>
658	</const>
659	<const name="MemoryLoad" value="6">
660	<desc>
661	Memory load (0-100%).
662	</desc>
663	</const>
664	<const name="PhysMemTotal" value="7">
665	<desc>
666	Total physical memory in megabytes.
667	</desc>
668	</const>
669	<const name="PhysMemAvailable" value="8">
670	<desc>
671	Free physical memory in megabytes.
672	</desc>
673	</const>
674	<const name="PhysMemBalloon" value="9">
675	<desc>
676	Ballooned physical memory in megabytes.
677	</desc>
678	</const>
679	<const name="MemCommitTotal" value="10">
680	<desc>
681	Total amount of memory in the committed state in megabytes.
682	</desc>
683	</const>
684	<const name="MemKernelTotal" value="11">
685	<desc>
686	Total amount of memory used by the guest OS's kernel in megabytes.
687	</desc>
688	</const>
689	<const name="MemKernelPaged" value="12">
690	<desc>
691	Total amount of paged memory used by the guest OS's kernel in megabytes.
692	</desc>
693	</const>
694	<const name="MemKernelNonpaged" value="13">
695	<desc>
696	Total amount of non-paged memory used by the guest OS's kernel in megabytes.
697	</desc>
698	</const>
699	<const name="MemSystemCache" value="14">
700	<desc>
701	Total amount of memory used by the guest OS's system cache in megabytes.
702	</desc>
703	</const>
704	<const name="PageFileSize" value="15">
705	<desc>
706	Pagefile size in megabytes.
707	</desc>
708	</const>
709	<const name="SampleNumber" value="16">
710	<desc>
711	Statistics sample number
712	</desc>
713	</const>
714	<const name="MaxVal" value="17"/>
715	</enum>
716
717	<enum
718	name="BIOSBootMenuMode"
719	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
720	>
721	<desc>
722	BIOS boot menu mode.
723	</desc>
724
725	<const name="Disabled" value="0"/>
726	<const name="MenuOnly" value="1"/>
727	<const name="MessageAndMenu" value="2"/>
728	</enum>
729
730	<enum
731	name="IDEControllerType"
732	uuid="445330e3-202a-4dab-854f-ce22e6cb9715"
733	>
734	<desc>
735	IDE controller type.
736	</desc>
737
738	<const name="Null" value="0">
739	<desc><tt>null</tt> value. Never used by the API.</desc>
740	</const>
741	<const name="PIIX3" value="1"/>
742	<const name="PIIX4" value="2"/>
743	</enum>
744
745	<enum
746	name="DriveState"
747	uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
748	>
749	<const name="Null" value="0">
750	<desc><tt>null</tt> value. Never used by the API.</desc>
751	</const>
752	<const name="NotMounted" value="1"/>
753	<const name="ImageMounted" value="2"/>
754	<const name="HostDriveCaptured" value="3"/>
755	</enum>
756
757	<enum
758	name="ProcessorFeature"
759	uuid="b8353b35-705d-4796-9967-ebfb7ba54af4"
760	>
761	<desc>
762	CPU features.
763	</desc>
764
765	<const name="HWVirtEx" value="0"/>
766	<const name="PAE" value="1"/>
767	<const name="LongMode" value="2"/>
768	</enum>
769
770
771	<!--
772	// IVirtualBoxErrorInfo
773	/////////////////////////////////////////////////////////////////////////
774	-->
775
776	<interface
777	name="IVirtualBoxErrorInfo" extends="$errorinfo"
778	uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
779	supportsErrorInfo="no"
780	wsmap="suppress"
781	>
782	<desc>
783	The IVirtualBoxErrorInfo interface represents extended error information.
784
785	Extended error information can be set by VirtualBox components after
786	unsuccessful or partially successful method invocation. This information
787	can be retrieved by the calling party as an IVirtualBoxErrorInfo object
788	and then shown to the client in addition to the plain 32-bit result code.
789
790	In MS COM, this interface extends the IErrorInfo interface,
791	in XPCOM, it extends the nsIException interface. In both cases,
792	it provides a set of common attributes to retrieve error
793	information.
794
795	Sometimes invocation of some component's method may involve methods of
796	other components that may also fail (independently of this method's
797	failure), or a series of non-fatal errors may precede a fatal error that
798	causes method failure. In cases like that, it may be desirable to preserve
799	information about all errors happened during method invocation and deliver
800	it to the caller. The <link to="#next"/> attribute is intended
801	specifically for this purpose and allows to represent a chain of errors
802	through a single IVirtualBoxErrorInfo object set after method invocation.
803
804	Note that errors are stored to a chain in the reverse order, i.e. the
805	initial error object you query right after method invocation is the last
806	error set by the callee, the object it points to in the @a next attribute
807	is the previous error and so on, up to the first error (which is the last
808	in the chain).
809	</desc>
810
811	<attribute name="resultCode" type="result" readonly="yes">
812	<desc>
813	Result code of the error.
814	Usually, it will be the same as the result code returned
815	by the method that provided this error information, but not
816	always. For example, on Win32, CoCreateInstance() will most
817	likely return E_NOINTERFACE upon unsuccessful component
818	instantiation attempt, but not the value the component factory
819	returned.
820	<note>
821	In MS COM, there is no equivalent.
822	In XPCOM, it is the same as nsIException::result.
823	</note>
824	</desc>
825	</attribute>
826
827	<attribute name="interfaceID" type="uuid" readonly="yes">
828	<desc>
829	UUID of the interface that defined the error.
830	<note>
831	In MS COM, it is the same as IErrorInfo::GetGUID.
832	In XPCOM, there is no equivalent.
833	</note>
834	</desc>
835	</attribute>
836
837	<attribute name="component" type="wstring" readonly="yes">
838	<desc>
839	Name of the component that generated the error.
840	<note>
841	In MS COM, it is the same as IErrorInfo::GetSource.
842	In XPCOM, there is no equivalent.
843	</note>
844	</desc>
845	</attribute>
846
847	<attribute name="text" type="wstring" readonly="yes">
848	<desc>
849	Text description of the error.
850	<note>
851	In MS COM, it is the same as IErrorInfo::GetDescription.
852	In XPCOM, it is the same as nsIException::message.
853	</note>
854	</desc>
855	</attribute>
856
857	<attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
858	<desc>
859	Next error object if there is any, or @c null otherwise.
860	<note>
861	In MS COM, there is no equivalent.
862	In XPCOM, it is the same as nsIException::inner.
863	</note>
864	</desc>
865	</attribute>
866
867	</interface>
868
869
870	<!--
871	// IVirtualBox
872	/////////////////////////////////////////////////////////////////////////
873	-->
874
875	<interface
876	name="IVirtualBoxCallback" extends="$unknown"
877	uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
878	wsmap="suppress"
879	>
880	<method name="onMachineStateChange">
881	<desc>
882	The execution state of the given machine has changed.
883	<see>IMachine::state</see>
884	</desc>
885	<param name="machineId" type="uuid" dir="in">
886	<desc>ID of the machine this event relates to.</desc>
887	</param>
888	<param name="state" type="MachineState" dir="in">
889	<desc>New execution state.</desc>
890	</param>
891	</method>
892
893	<method name="onMachineDataChange">
894	<desc>
895	Any of the settings of the given machine has changed.
896	</desc>
897	<param name="machineId" type="uuid" dir="in">
898	<desc>ID of the machine this event relates to.</desc>
899	</param>
900	</method>
901
902	<method name="onExtraDataCanChange">
903	<desc>
904	Notification when someone tries to change extra data for
905	either the given machine or (if null) global extra data.
906	This gives the chance to veto against changes.
907	</desc>
908	<param name="machineId" type="uuid" dir="in">
909	<desc>
910	ID of the machine this event relates to
911	(null ID for global extra data change requests).
912	</desc>
913	</param>
914	<param name="key" type="wstring" dir="in">
915	<desc>
916	Extra data key for the attempted write.
917	</desc>
918	</param>
919	<param name="value" type="wstring" dir="in">
920	<desc>
921	Extra data value for the given key.
922	</desc>
923	</param>
924	<param name="error" type="wstring" dir="out">
925	<desc>
926	Optional error message describing the reason of the
927	veto (ignored if this notification returns @c true).
928	</desc>
929	</param>
930	<param name="allowChange" type="boolean" dir="return">
931	<desc>
932	Flag to indicate whether the callee agrees (@c true)
933	or vetoes against the change (@c false).
934	</desc>
935	</param>
936	</method>
937
938	<method name="onExtraDataChange">
939	<desc>
940	Notification when machine specific or global extra data
941	has changed.
942	</desc>
943	<param name="machineId" type="uuid" dir="in">
944	<desc>
945	ID of the machine this event relates to.
946	Null for global extra data changes.
947	</desc>
948	</param>
949	<param name="key" type="wstring" dir="in">
950	<desc>
951	Extra data key that has changed.
952	</desc>
953	</param>
954	<param name="value" type="wstring" dir="in">
955	<desc>
956	Extra data value for the given key.
957	</desc>
958	</param>
959	</method>
960
961	<method name="onMediaRegistered">
962	<desc>
963	The given media was registered or unregistered
964	within this VirtualBox installation.
965
966	The @a mediaType parameter describes what type of
967	media the specified @a mediaId refers to. Possible
968	values are:
969
970	<ul>
971	<li><link to="DeviceType::HardDisk"/>: the media is a hard disk
972	that, if registered, can be obtained using the
973	<link to="IVirtualBox::getHardDisk2()"/> call.</li>
974	<li><link to="DeviceType::DVD"/>: the media is a CD/DVD image
975	that, if registered, can be obtained using the
976	<link to="IVirtualBox::getDVDImage()"/> call.</li>
977	<li><link to="DeviceType::Floppy"/>: the media is a Floppy image
978	that, if registered, can be obtained using the
979	<link to="IVirtualBox::getFloppyImage()"/> call.</li>
980	</ul>
981
982	Note that if this is a deregistration notification,
983	there is no way to access the object representing the
984	unregistered media. It is supposed that the
985	application will do required cleanup based on the @a
986	mediaId value.
987	</desc>
988	<param name="mediaId" type="uuid" dir="in">
989	<desc>ID of the media this event relates to.</desc>
990	</param>
991	<param name="mediaType" type="DeviceType" dir="in">
992	<desc>Type of the media this event relates to.</desc>
993	</param>
994	<param name="registered" type="boolean" dir="in">
995	<desc>
996	If true, the media was registered, otherwise it was
997	unregistered.
998	</desc>
999	</param>
1000	</method>
1001
1002	<method name="onMachineRegistered">
1003	<desc>
1004	The given machine was registered or unregistered
1005	within this VirtualBox installation.
1006	</desc>
1007	<param name="machineId" type="uuid" dir="in">
1008	<desc>ID of the machine this event relates to.</desc>
1009	</param>
1010	<param name="registered" type="boolean" dir="in">
1011	<desc>
1012	If true, the machine was registered, otherwise it was
1013	unregistered.
1014	</desc>
1015	</param>
1016	</method>
1017
1018	<method name="onSessionStateChange">
1019	<desc>
1020	The state of the session for the given machine was changed.
1021	<see>IMachine::sessionState</see>
1022	</desc>
1023	<param name="machineId" type="uuid" dir="in">
1024	<desc>ID of the machine this event relates to.</desc>
1025	</param>
1026	<param name="state" type="SessionState" dir="in">
1027	<desc>New session state.</desc>
1028	</param>
1029	</method>
1030
1031	<method name="onSnapshotTaken">
1032	<desc>
1033	A new snapshot of the machine has been taken.
1034	<see>ISnapshot</see>
1035	</desc>
1036	<param name="machineId" type="uuid" dir="in">
1037	<desc>ID of the machine this event relates to.</desc>
1038	</param>
1039	<param name="snapshotId" type="uuid" dir="in">
1040	<desc>ID of the new snapshot.</desc>
1041	</param>
1042	</method>
1043
1044	<method name="onSnapshotDiscarded">
1045	<desc>
1046	Snapshot of the given machine has been discarded.
1047
1048	<note>
1049	This notification is delivered <b>after</b> the snapshot
1050	object has been uninitialized on the server (so that any
1051	attempt to call its methods will return an error).
1052	</note>
1053
1054	<see>ISnapshot</see>
1055	</desc>
1056	<param name="machineId" type="uuid" dir="in">
1057	<desc>ID of the machine this event relates to.</desc>
1058	</param>
1059	<param name="snapshotId" type="uuid" dir="in">
1060	<desc>
1061	ID of the discarded snapshot. <tt>null</tt> means the
1062	current machine state has been discarded (restored from
1063	the current snapshot).
1064	</desc>
1065	</param>
1066	</method>
1067
1068	<method name="onSnapshotChange">
1069	<desc>
1070	Snapshot properties (name and/or description) have been changed.
1071	<see>ISnapshot</see>
1072	</desc>
1073	<param name="machineId" type="uuid" dir="in">
1074	<desc>ID of the machine this event relates to.</desc>
1075	</param>
1076	<param name="snapshotId" type="uuid" dir="in">
1077	<desc>ID of the changed snapshot.</desc>
1078	</param>
1079	</method>
1080
1081	<method name="onGuestPropertyChange">
1082	<desc>
1083	Notification when a guest property has changed.
1084	</desc>
1085	<param name="machineId" type="uuid" dir="in">
1086	<desc>
1087	ID of the machine this event relates to.
1088	</desc>
1089	</param>
1090	<param name="name" type="wstring" dir="in">
1091	<desc>
1092	The name of the property that has changed.
1093	</desc>
1094	</param>
1095	<param name="value" type="wstring" dir="in">
1096	<desc>
1097	The new property value.
1098	</desc>
1099	</param>
1100	<param name="flags" type="wstring" dir="in">
1101	<desc>
1102	The new property flags.
1103	</desc>
1104	</param>
1105	</method>
1106
1107	</interface>
1108
1109	<interface
1110	name="IVirtualBox" extends="$dispatched"
1111	uuid="2aa11223-ba64-4610-84b8-066d2a89384f"
1112	wsmap="managed"
1113	>
1114	<desc>
1115	The IVirtualBox interface represents the main interface exposed by the
1116	product that provides virtual machine management.
1117
1118	An instance of IVirtualBox is required for the product to do anything
1119	useful. Even though the interface does not expose this, internally,
1120	IVirtualBox is implemented as a singleton and actually lives in the
1121	process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1122	IVirtualBox can track the state of all virtual machines on a particular
1123	host, regardless of which frontend started them.
1124
1125	To enumerate all the virtual machines on the host, use the
1126	<link to="IVirtualBox::machines2"/> attribute.
1127	</desc>
1128
1129	<attribute name="version" type="wstring" readonly="yes">
1130	<desc>
1131	A string representing the version number of the product. The
1132	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1133	last number represents the build number and will frequently change.
1134	</desc>
1135	</attribute>
1136
1137	<attribute name="revision" type="unsigned long" readonly="yes">
1138	<desc>
1139	The internal build revision number of the product.
1140	</desc>
1141	</attribute>
1142
1143	<attribute name="packageType" type="wstring" readonly="yes">
1144	<desc>
1145	A string representing the package type of this product. The
1146	format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1147	SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1148	is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1149	this.
1150	</desc>
1151	</attribute>
1152
1153	<attribute name="homeFolder" type="wstring" readonly="yes">
1154	<desc>
1155	Full path to the directory where the global settings file,
1156	<tt>VirtualBox.xml</tt>, is stored.
1157
1158	In this version of VirtualBox, the value of this property is
1159	always <tt><user_dir>/.VirtualBox</tt> (where
1160	<tt><user_dir></tt> is the path to the user directory,
1161	as determined by the host OS), and cannot be changed.
1162
1163	This path is also used as the base to resolve relative paths in
1164	places where relative paths are allowed (unless otherwise
1165	expressly indicated).
1166	</desc>
1167	</attribute>
1168
1169	<attribute name="settingsFilePath" type="wstring" readonly="yes">
1170	<desc>
1171	Full name of the global settings file.
1172	The value of this property corresponds to the value of
1173	<link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1174	</desc>
1175	</attribute>
1176
1177	<attribute name="settingsFileVersion" type="wstring" readonly="yes">
1178	<desc>
1179	Current version of the format of the global VirtualBox settings file
1180	(<tt>VirtualBox.xml</tt>).
1181
1182	The version string has the following format:
1183	<pre>
1184	x.y-platform
1185	</pre>
1186	where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1187	versions, and <tt>platform</tt> is the platform identifier.
1188
1189	The current version usually matches the value of the
1190	<link to="#settingsFormatVersion"/> attribute unless the
1191	settings file was created by an older version of VirtualBox and there
1192	was a change of the settings file format since then.
1193
1194	Note that VirtualBox automatically converts settings files from older
1195	versions to the most recent version when reading them (usually at
1196	VirtualBox startup) but it doesn't save the changes back until
1197	you call a method that implicitly saves settings (such as
1198	<link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
1199	explicitly. Therefore, if the value of this attribute differs from the
1200	value of <link to="#settingsFormatVersion"/>, then it
1201	means that the settings file was converted but the result of the
1202	conversion is not yet saved to disk.
1203
1204	The above feature may be used by interactive front-ends to inform users
1205	about the settings file format change and offer them to explicitly save
1206	all converted settings files (the global and VM-specific ones),
1207	optionally create backup copies of the old settings files before saving,
1208	etc.
1209
1210	<see>settingsFormatVersion, saveSettingsWithBackup()</see>
1211	</desc>
1212	</attribute>
1213
1214	<attribute name="settingsFormatVersion" type="wstring" readonly="yes">
1215	<desc>
1216	Most recent version of the settings file format.
1217
1218	The version string has the following format:
1219	<pre>
1220	x.y-platform
1221	</pre>
1222	where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1223	versions, and <tt>platform</tt> is the platform identifier.
1224
1225	VirtualBox uses this version of the format when saving settings files
1226	(either as a result of method calls that require to save settings or as
1227	a result of an explicit call to <link to="#saveSettings()"/>).
1228
1229	<see>settingsFileVersion</see>
1230	</desc>
1231	</attribute>
1232
1233	<attribute name="host" type="IHost" readonly="yes">
1234	<desc>Associated host object.</desc>
1235	</attribute>
1236
1237	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1238	<desc>Associated system information object.</desc>
1239	</attribute>
1240
1241	<attribute name="machines2" type="IMachine" readonly="yes" safearray="yes">
1242	<desc>
1243	Array of machine objects registered within this VirtualBox instance.
1244	</desc>
1245	</attribute>
1246
1247	<attribute name="hardDisks2" type="IHardDisk2" readonly="yes" safearray="yes">
1248	<desc>
1249	Array of hard disk objects known to this VirtualBox installation.
1250
1251	This array contains only base (root) hard disks. All differencing
1252	hard disks of the given base hard disk can be enumerated using
1253	<link to="IHardDisk2::children"/>.
1254	</desc>
1255	</attribute>
1256
1257	<attribute name="DVDImages" type="IDVDImage2" readonly="yes" safearray="yes">
1258	<desc>
1259	Array of CD/DVD image objects registered with this VirtualBox instance.
1260	</desc>
1261	</attribute>
1262
1263	<attribute name="floppyImages" type="IFloppyImage2" readonly="yes" safearray="yes">
1264	<desc>
1265	Array of floppy image objects registered with this VirtualBox instance.
1266	</desc>
1267	</attribute>
1268
1269	<attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
1270
1271	<attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
1272
1273	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
1274	<desc>
1275	Collection of global shared folders. Global shared folders are
1276	available to all virtual machines.
1277
1278	New shared folders are added to the collection using
1279	<link to="#createSharedFolder"/>. Existing shared folders can be
1280	removed using <link to="#removeSharedFolder"/>.
1281
1282	<note>
1283	In the current version of the product, global shared folders are not
1284	implemented and therefore this collection is always empty.
1285	</note>
1286	</desc>
1287	</attribute>
1288
1289	<attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1290	<desc>
1291	Associated performance collector object.
1292	</desc>
1293	</attribute>
1294
1295	<method name="createMachine">
1296	<desc>
1297	Creates a new virtual machine.
1298
1299	The new machine will have "empty" default settings and will not
1300	yet be registered. The typical sequence to create a virtual machine
1301	is therefore something like this:
1302
1303	<ol>
1304	<li>Call this method (IVirtualBox::createMachine) to have a new
1305	machine created. The machine object returned is "mutable", i.e.
1306	automatically locked for the current session, as if
1307	<link to="#openSession" /> had been called on it.</li>
1308
1309	<li>Assign meaningful settings to the new machine by calling the
1310	respective methods.</li>
1311
1312	<li>Call <link to="IMachine::saveSettings" /> to have the settings written
1313	to the machine's XML settings file. The configuration of the newly
1314	created machine will not be saved to disk (and the settings subfolder
1315	and file, as described below, will not be created) until this method
1316	is called.</li>
1317
1318	<li>Call <link to="#registerMachine" /> to have the
1319	machine show up in the list of machines registered with VirtualBox.</li>
1320	</ol>
1321
1322	Every machine has a <i>settings file</i> that is used to store
1323	the machine configuration. This file is stored in the directory
1324	called <i>machine settings subfolder</i>. Unless specified otherwise,
1325	both the subfolder and the settings file will have a name that
1326	corresponds to the name of the virtual machine. You can specify
1327	where to create the machine settings subfolder using the @a
1328	baseFolder argument. The base folder can be absolute (full path)
1329	or relative to the <link to="IVirtualBox::homeFolder">
1330	VirtualBox home directory</link>.
1331
1332	If a null or empty string is given as the base folder (which is
1333	recommended), the <link to="ISystemProperties::defaultMachineFolder">
1334	default machine settings folder</link> will be used as the base
1335	folder to create the machine settings subfolder and file. In
1336	any case, the full path to the settings file will look like:
1337	<pre>
1338	<base_folder>/<machine_name>/<machine_name>.xml
1339	</pre>
1340
1341	Optionally the UUID of the machine can be predefined. If this is
1342	not desired (i.e. a new UUID should be generated), pass just an
1343	empty or null UUID.
1344
1345	You should also specify a valid name for the machine.
1346	See the <link to="IMachine::name"/> property
1347	description for more details about the machine name.
1348
1349	The created machine remains
1350	unregistered until you call <link to="#registerMachine()"/>.
1351
1352	<note>
1353	There is no way to change the name of the settings file or
1354	subfolder of the created machine directly.
1355	</note>
1356	</desc>
1357	<param name="baseFolder" type="wstring" dir="in">
1358	<desc>
1359	Name of the folder where to create the machine settings
1360	subfolder containing the settings file.
1361	</desc>
1362	</param>
1363	<param name="name" type="wstring" dir="in">
1364	<desc>Machine name.</desc>
1365	</param>
1366	<param name="id" type="uuid" dir="in">
1367	<desc>
1368	UUID of the newly created VM, when non-null or non-empty.
1369	Otherwise a UUID is automatically generated.
1370	</desc>
1371	</param>
1372	<param name="machine" type="IMachine" dir="return">
1373	<desc>Created machine object.</desc>
1374	</param>
1375	</method>
1376
1377	<method name="createLegacyMachine">
1378	<desc>
1379	Creates a new virtual machine in "legacy" mode, using the
1380	specified settings file to store machine settings.
1381
1382	As opposed to machines created by <link to="#createMachine()"/>,
1383	the settings file of the machine created in "legacy" mode
1384	is not automatically renamed when the machine name is
1385	changed -- it will always remain the same as specified in this
1386	method call.
1387
1388	The specified settings file name can be absolute
1389	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1390	VirtualBox home directory</link>. If the file name doesn't
1391	contain an extension, the default extension (.xml) will be
1392	appended.
1393
1394	Optionally the UUID of the machine can be predefined. If this is
1395	not desired (i.e. a new UUID should be generated), pass just an
1396	empty or null UUID.
1397
1398	Note that the configuration of the newly created machine is not
1399	saved to disk (and therefore no settings file is created)
1400	until <link to="IMachine::saveSettings()"/> is called. If the
1401	specified settings file already exists,
1402	<link to="IMachine::saveSettings()"/> will return an error.
1403
1404	You should also specify a valid name for the machine.
1405	See the <link to="IMachine::name"/> property
1406	description for more details about the machine name.
1407
1408	The created machine remains
1409	unregistered until you call <link to="#registerMachine()"/>.
1410
1411	@deprecated This method may be removed later. It is better
1412	to use <link to="IVirtualBox::createMachine()"/>.
1413
1414	<note>
1415	There is no way to change the name of the settings file
1416	of the created machine.
1417	</note>
1418	</desc>
1419	<param name="settingsFile" type="wstring" dir="in">
1420	<desc>
1421	Name of the file where to store machine settings.
1422	</desc>
1423	</param>
1424	<param name="name" type="wstring" dir="in">
1425	<desc>Machine name.</desc>
1426	</param>
1427	<param name="id" type="uuid" dir="in">
1428	<desc>
1429	UUID of the newly created VM, when non-null or non-empty.
1430	Otherwise a UUID is automatically generated.
1431	</desc>
1432	</param>
1433	<param name="machine" type="IMachine" dir="return">
1434	<desc>Created machine object.</desc>
1435	</param>
1436	</method>
1437
1438	<method name="openMachine">
1439	<desc>
1440	Opens a virtual machine from the existing settings file.
1441	The opened machine remains unregistered until you call
1442	<link to="#registerMachine()"/>.
1443
1444	The specified settings file name can be absolute
1445	(full path) or relative to the <link to="IVirtualBox::homeFolder">
1446	VirtualBox home directory</link>. This file must exist
1447	and must be a valid machine settings file whose contents
1448	will be used to construct the machine object.
1449
1450	@deprecated Will be removed soon.
1451	</desc>
1452	<param name="settingsFile" type="wstring" dir="in">
1453	<desc>
1454	Name of the machine settings file.
1455	</desc>
1456	</param>
1457	<param name="machine" type="IMachine" dir="return">
1458	<desc>Opened machine object.</desc>
1459	</param>
1460	<note>
1461	<link to="IMachine::settingsModified"/> will return
1462	false for the created machine, until any of machine settings
1463	are changed.
1464	</note>
1465	</method>
1466
1467	<method name="registerMachine">
1468	<desc>
1469
1470	Registers the machine previously created using
1471	<link to="#createMachine()"/> or opened using
1472	<link to="#openMachine()"/> within this VirtualBox installation. After
1473	successful method invocation, the
1474	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1475	to all registered callbacks.
1476
1477	<note>
1478	This method implicitly calls <link to="IMachine::saveSettings"/>
1479	to save all current machine settings before registering it.
1480	</note>
1481
1482	</desc>
1483	<param name="machine" type="IMachine" dir="in"/>
1484	</method>
1485
1486	<method name="getMachine">
1487	<desc>
1488	Attempts to find a virtual machine given its UUID.
1489	To look up a machine by name, use <link to="IVirtualBox::findMachine" /> instead.
1490	</desc>
1491	<param name="id" type="uuid" dir="in"/>
1492	<param name="machine" type="IMachine" dir="return"/>
1493	</method>
1494
1495	<method name="findMachine">
1496	<desc>
1497	Attempts to find a virtual machine given its name.
1498	To look up a machine by UUID, use <link to="IVirtualBox::getMachine" /> instead.
1499	</desc>
1500	<param name="name" type="wstring" dir="in"/>
1501	<param name="machine" type="IMachine" dir="return"/>
1502	</method>
1503
1504	<method name="unregisterMachine">
1505	<desc>
1506
1507	Unregisters the machine previously registered using
1508	<link to="#registerMachine"/>. After successful method invocation, the
1509	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1510	to all registered callbacks.
1511
1512	<note>
1513	The specified machine must not be in the Saved state, have an open
1514	(or a spawning) direct session associated with it, have snapshots or
1515	have hard disks attached.
1516	</note>
1517
1518	<note>
1519	This method implicitly calls <link to="IMachine::saveSettings"/> to
1520	save all current machine settings before unregistering it.
1521	</note>
1522
1523	<note>
1524	If the given machine is inaccessible (see
1525	<link to="IMachine::accessible"/>), it will be unregistered and
1526	fully uninitialized right afterwards. As a result, the returned
1527	machine object will be unusable and an attempt to call
1528	<b>any</b> method will return the "Object not ready" error.
1529	</note>
1530
1531	</desc>
1532	<param name="id" type="uuid" dir="in">
1533	<desc>UUID of the machine to unregister.</desc>
1534	</param>
1535	<param name="machine" type="IMachine" dir="return">
1536	<desc>Unregistered machine object.</desc>
1537	</param>
1538	</method>
1539
1540	<method name="createHardDisk2">
1541	<desc>
1542	Creates a new base hard disk object that will use the given storage
1543	format and location for hard disk data.
1544
1545	Note that the actual storage unit is not created by this method. In
1546	order to do it, and before you are able to attach the created hard disk
1547	to virtual machines, you must call one of the following methods to
1548	allocate a format-specific storage unit at the specified location:
1549	<ul>
1550	<li><link to="IHardDisk2::createDynamicStorage()"/></li>
1551	<li><link to="IHardDisk2::createFixedStorage()"/></li>
1552	<li><link to="IHardDisk2::createDiffStorage()"/></li>
1553	</ul>
1554
1555	Some hard disk attributes, such as <link to="#id"/>, may remain
1556	uninitialized until the hard disk storage unit is successfully created
1557	by one of the above methods.
1558
1559	After the storage unit is successfully created, the hard disk gets
1560	remembered by this VirtualBox installation and will be accessible
1561	through <link to="#getHardDisk2()"/> and <link to="#findHardDisk2()"/>
1562	methods. Remembered root (base) hard disks are also returned as part of
1563	the <link to="#hardDisks2"/> array. See IHardDisk2 for more details.
1564
1565	The list of all storage formats supported by this VirtualBox
1566	installation can be obtained using
1567	<link to="ISystemProperties::hardDiskFormats"/>. If the @a format
1568	attribute is empty or <tt>null</tt> then the default storage format
1569	specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1570	be used for creating a storage unit of the hard disk.
1571
1572	Note that the format of the location string is storage format specific.
1573	See <link to="IMedium::location"/>, IHardDisk2 and
1574	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1575	</desc>
1576	<param name="format" type="wstring" dir="in">
1577	<desc>
1578	Identifier of the storage format to use for the new hard disk.
1579	</desc>
1580	</param>
1581	<param name="location" type="wstring" dir="in">
1582	<desc>
1583	Location of the storage unit for the new hard disk.
1584	</desc>
1585	</param>
1586	<param name="hardDisk" type="IHardDisk2" dir="return">
1587	<desc>Created hard disk object.</desc>
1588	</param>
1589	</method>
1590
1591	<method name="openHardDisk2">
1592	<desc>
1593	Opens a hard disk from an existing location.
1594
1595	After the hard disk is successfully opened by this method, it gets
1596	remembered by (known to) this VirtualBox installation and will be
1597	accessible through <link to="#getHardDisk2()"/> and
1598	<link to="#findHardDisk2()"/> methods. Remembered root (base) hard disks
1599	are also returned as part of the <link to="#hardDisks2"/> array and can
1600	be attached to virtual machines. See IHardDisk2 for more details.
1601
1602	If a differencing hard disk is to be opened by this method, the
1603	operation will succeed only if its parent hard disk and all ancestors,
1604	if any, are already known to this VirtualBox installation (for example,
1605	were opened by this method before).
1606
1607	This method tries to guess the storage format of the specified hard disk
1608	by reading hard disk data at the specified location.
1609
1610	Note that the format of the location string is storage format specific.
1611	See <link to="IMedium::location"/>, IHardDisk2 and
1612	<link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1613	</desc>
1614	<param name="location" type="wstring" dir="in">
1615	<desc>
1616	Location of the storage unit that contains hard disk data in one of
1617	the supported storage formats.
1618	</desc>
1619	</param>
1620	<param name="hardDisk" type="IHardDisk2" dir="return">
1621	<desc>Opened hard disk object.</desc>
1622	</param>
1623	</method>
1624
1625	<method name="getHardDisk2" const="yes">
1626	<desc>
1627	Returns a hard disk with the given UUID.
1628
1629	The hard disk with the given UUID must be known to this VirtualBox
1630	installation, i.e. it must be previously created by
1631	<link to="#createHardDisk2()"/> or opened by <link
1632	to="#openHardDisk2()"/>, or attached to some known virtual machine.
1633	</desc>
1634	<param name="id" type="uuid" dir="in">
1635	<desc>UUID of the hard disk to look for.</desc>
1636	</param>
1637	<param name="hardDisk" type="IHardDisk2" dir="return">
1638	<desc>Found hard disk object.</desc>
1639	</param>
1640	</method>
1641
1642	<method name="findHardDisk2">
1643	<desc>
1644	Returns a hard disk that uses the given location to store hard
1645	disk data.
1646
1647	The given hard disk must be known to this VirtualBox installation, i.e.
1648	it must be previously created by
1649	<link to="#createHardDisk2()"/> or opened by <link
1650	to="#openHardDisk2()"/>, or attached to some known virtual machine.
1651
1652	The search is done by comparing the value of the @a location argument to
1653	the <link to="IHardDisk2::location"/> attribute of each known hard
1654	disk.
1655
1656	For locations represented by file names in the host's file system, the
1657	requested location can be a path relative to the
1658	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
1659	only a file name without any path is given, the
1660	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
1661	folder</link> will be prepended to the file name before searching. Note
1662	that on case sensitive file systems, a case sensitive comparison is
1663	performed, otherwise the case of symbols in the file path is ignored.
1664	</desc>
1665	<param name="location" type="wstring" dir="in">
1666	<desc>Location string to search for.</desc>
1667	</param>
1668	<param name="hardDisk" type="IHardDisk2" dir="return">
1669	<desc>Found hard disk object.</desc>
1670	</param>
1671	</method>
1672
1673	<method name="openDVDImage">
1674	<desc>
1675	Opens a CD/DVD image contained in the specified file of the supported
1676	format and assigns it the given UUID.
1677
1678	After the image is successfully opened by this method, it gets
1679	remembered by (known to) this VirtualBox installation and will be
1680	accessible through <link to="#getDVDImage()"/> and
1681	<link to="#findDVDImage()"/> methods. Remembered images are also
1682	returned as part of the <link to="#DVDImages"/> array and can be mounted
1683	to virtual machines. See IMedium for more details.
1684
1685	See <link to="IMedium::location"/> to get more details about the format
1686	of the location string.
1687
1688	<note>
1689	Currently, only ISO CD/DVD images are supported by VirtualBox.
1690	</note>
1691	</desc>
1692	<param name="location" type="wstring" dir="in">
1693	<desc>
1694	Full path to the file that contains a valid CD/DVD image.
1695	</desc>
1696	</param>
1697	<param name="id" type="uuid" dir="in">
1698	<desc>
1699	UUID to assign to the given image within this VirtualBox installation.
1700	If an empty (null) UUID is specified, the system will randomly
1701	generate a new UUID.
1702	</desc>
1703	</param>
1704	<param name="image" type="IDVDImage2" dir="return">
1705	<desc>Opened CD/DVD image object.</desc>
1706	</param>
1707	</method>
1708
1709	<method name="getDVDImage">
1710	<desc>
1711	Returns a CD/DVD image with the given UUID.
1712
1713	The image with the given UUID must be known to this VirtualBox
1714	installation, i.e. it must be previously opened by <link
1715	to="#openDVDImage()"/>, or mounted to some known virtual machine.
1716	</desc>
1717	<param name="id" type="uuid" dir="in">
1718	<desc>UUID of the image to look for.</desc>
1719	</param>
1720	<param name="image" type="IDVDImage2" dir="return">
1721	<desc>Found CD/DVD image object.</desc>
1722	</param>
1723	</method>
1724
1725	<method name="findDVDImage">
1726	<desc>
1727	Returns a CD/DVD image with the given image location.
1728
1729	The image with the given UUID must be known to this VirtualBox
1730	installation, i.e. it must be previously opened by <link
1731	to="#openDVDImage()"/>, or mounted to some known virtual machine.
1732
1733	The search is done by comparing the value of the @a location argument to
1734	the <link to="IMedium::location"/> attribute of each known CD/DVD image.
1735
1736	The requested location can be a path relative to the
1737	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
1738	only a file name without any path is given, the
1739	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
1740	folder</link> will be prepended to the file name before searching. Note
1741	that on case sensitive file systems, a case sensitive comparison is
1742	performed, otherwise the case of symbols in the file path is ignored.
1743	</desc>
1744	<param name="location" type="wstring" dir="in">
1745	<desc>CD/DVD image file path to look for.</desc>
1746	</param>
1747	<param name="image" type="IDVDImage2" dir="return">
1748	<desc>Found CD/DVD image object.</desc>
1749	</param>
1750	</method>
1751
1752	<method name="openFloppyImage">
1753	<desc>
1754	Opens a floppy image contained in the specified file of the supported
1755	format and assigns it the given UUID.
1756
1757	After the image is successfully opened by this method, it gets
1758	remembered by (known to) this VirtualBox installation and will be
1759	accessible through <link to="#getFloppyImage()"/> and
1760	<link to="#findFloppyImage()"/> methods. Remembered images are also
1761	returned as part of the <link to="#floppyImages"/> array and can be
1762	mounted to virtual machines. See IMedium for more details.
1763
1764	See <link to="IMedium::location"/> to get more details about the format
1765	of the location string.
1766
1767	<note>
1768	Currently, only raw floppy images are supported by VirtualBox.
1769	</note>
1770	</desc>
1771	<param name="location" type="wstring" dir="in">
1772	<desc>
1773	Full path to the file that contains a valid floppy image.
1774	</desc>
1775	</param>
1776	<param name="id" type="uuid" dir="in">
1777	<desc>
1778	UUID to assign to the given image file within this VirtualBox
1779	installation. If an empty (null) UUID is specified, the system will
1780	randomly generate a new UUID.
1781	</desc>
1782	</param>
1783	<param name="image" type="IFloppyImage2" dir="return">
1784	<desc>Opened floppy image object.</desc>
1785	</param>
1786	</method>
1787
1788	<method name="getFloppyImage">
1789	<desc>
1790	Returns a floppy image with the given UUID.
1791
1792	The image with the given UUID must be known to this VirtualBox
1793	installation, i.e. it must be previously opened by <link
1794	to="#openFloppyImage()"/>, or mounted to some known virtual machine.
1795	</desc>
1796	<param name="id" type="uuid" dir="in">
1797	<desc>UUID of the image to look for.</desc>
1798	</param>
1799	<param name="image" type="IFloppyImage2" dir="return">
1800	<desc>Found floppy image object.</desc>
1801	</param>
1802	</method>
1803
1804	<method name="findFloppyImage">
1805	<desc>
1806	Returns a floppy image with the given image location.
1807
1808	The image with the given UUID must be known to this VirtualBox
1809	installation, i.e. it must be previously opened by <link
1810	to="#openFloppyImage()"/>, or mounted to some known virtual machine.
1811
1812	The search is done by comparing the value of the @a location argument to
1813	the <link to="IMedium::location"/> attribute of each known floppy image.
1814
1815	The requested location can be a path relative to the
1816	<link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
1817	only a file name without any path is given, the
1818	<link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
1819	folder</link> will be prepended to the file name before searching. Note
1820	that on case sensitive file systems, a case sensitive comparison is
1821	performed, otherwise the case of symbols in the file path is ignored.
1822	</desc>
1823	<param name="location" type="wstring" dir="in">
1824	<desc>Floppy image file path to look for.</desc>
1825	</param>
1826	<param name="image" type="IFloppyImage2" dir="return">
1827	<desc>Found floppy image object.</desc>
1828	</param>
1829	</method>
1830
1831	<method name="getGuestOSType">
1832	<desc>
1833	Returns an object describing the specified guest OS type.
1834
1835	The requested guest OS type is specified using a string which is a
1836	mnemonic identifier of the guest operating system, such as
1837	<tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
1838	particular virtual machine can be read or set using the
1839	<link to="IMachine::OSTypeId"/> attribute.
1840
1841	The <link to="IVirtualBox::guestOSTypes"/> collection contains all
1842	available guest OS type objects. Each object has an
1843	<link to="IGuestOSType::id"/> attribute which contains an identifier of
1844	the guest OS this object describes.
1845	</desc>
1846	<param name="id" type="wstring" dir="in">
1847	<desc>Guest OS type ID string.</desc>
1848	</param>
1849	<param name="type" type="IGuestOSType" dir="return">
1850	<desc>Guest OS type object.</desc>
1851	</param>
1852	</method>
1853
1854	<method name="createSharedFolder">
1855	<desc>
1856	Creates a new global shared folder by associating the given logical
1857	name with the given host path, adds it to the collection of shared
1858	folders and starts sharing it. Refer to the description of
1859	<link to="ISharedFolder"/> to read more about logical names.
1860	</desc>
1861	<param name="name" type="wstring" dir="in">
1862	<desc>Unique logical name of the shared folder.</desc>
1863	</param>
1864	<param name="hostPath" type="wstring" dir="in">
1865	<desc>Full path to the shared folder in the host file system.</desc>
1866	</param>
1867	<param name="writable" type="boolean" dir="in">
1868	<desc>Whether the share is writable or readonly</desc>
1869	</param>
1870	</method>
1871
1872	<method name="removeSharedFolder">
1873	<desc>
1874	Removes the global shared folder with the given name previously
1875	created by <link to="#createSharedFolder"/> from the collection of
1876	shared folders and stops sharing it.
1877	</desc>
1878	<param name="name" type="wstring" dir="in">
1879	<desc>Logical name of the shared folder to remove.</desc>
1880	</param>
1881	</method>
1882
1883	<method name="getNextExtraDataKey">
1884	<desc>
1885	Returns the global extra data key name following the supplied key.
1886
1887	An error is returned if the supplied @a key does not exist. @c NULL is
1888	returned in @a nextKey if the supplied key is the last key. When
1889	supplying @c NULL for the @a key, the first key item is returned in @a
1890	nextKey (if there is any). @a nextValue is an optional parameter and
1891	if supplied, the next key's value is returned in it.
1892	</desc>
1893	<param name="key" type="wstring" dir="in">
1894	<desc>Name of the data key to follow.</desc>
1895	</param>
1896	<param name="nextKey" type="wstring" dir="out">
1897	<desc>Name of the next data key.</desc>
1898	</param>
1899	<param name="nextValue" type="wstring" dir="out">
1900	<desc>Value of the next data key.</desc>
1901	</param>
1902	</method>
1903
1904	<method name="getExtraData">
1905	<desc>
1906	Returns associated global extra data.
1907
1908	If the requested data @a key does not exist, this function will
1909	succeed and return @c NULL in the @a value argument.
1910	</desc>
1911	<param name="key" type="wstring" dir="in">
1912	<desc>Name of the data key to get.</desc>
1913	</param>
1914	<param name="value" type="wstring" dir="return">
1915	<desc>Value of the requested data key.</desc>
1916	</param>
1917	</method>
1918
1919	<method name="setExtraData">
1920	<desc>
1921	Sets associated global extra data.
1922
1923	If you pass @c NULL as a key @a value, the given @a key will be
1924	deleted.
1925
1926	<note>
1927	Before performing the actual data change, this method will ask all
1928	registered callbacks using the
1929	<link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
1930	notification for a permission. If one of the callbacks refuses the
1931	new value, the change will not be performed.
1932	</note>
1933	<note>
1934	On success, the
1935	<link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
1936	is called to inform all registered callbacks about a successful data
1937	change.
1938	</note>
1939	</desc>
1940	<param name="key" type="wstring" dir="in">
1941	<desc>Name of the data key to set.</desc>
1942	</param>
1943	<param name="value" type="wstring" dir="in">
1944	<desc>Value to assign to the key.</desc>
1945	</param>
1946	</method>
1947
1948	<method name="openSession">
1949	<desc>
1950	Opens a new direct session with the given virtual machine.
1951
1952	A direct session acts as a local lock on the given VM.
1953	There can be only one direct session open at a time for every
1954	virtual machine, protecting the VM from being manipulated by
1955	conflicting actions from different processes. Only after a
1956	direct session has been opened, one can change all VM settings
1957	and execute the VM in the process space of the session object.
1958
1959	Sessions therefore can be compared to mutex semaphores that
1960	lock a given VM for modification and execution.
1961	See <link to="ISession">ISession</link> for details.
1962
1963	<note>Unless you are writing a new VM frontend, you will not
1964	want to execute a VM in the current process. To spawn a new
1965	process that executes a VM, use
1966	<link to="IVirtualBox::openRemoteSession" />
1967	instead.</note>
1968
1969	Upon successful return, the session object can be used to
1970	get access to the machine and to the VM console.
1971
1972	In VirtualBox terminology, the machine becomes "mutable" after
1973	a session has been opened. Note that the "mutable" machine
1974	object, on which you may invoke IMachine methods to change its
1975	settings, will be a different object from the immutable IMachine
1976	objects returned by various IVirtualBox methods. To obtain a
1977	mutable IMachine object (upon which you can invoke settings methods),
1978	use the <link to="ISession::machine" /> attribute.
1979
1980	One must always call <link to="ISession::close" /> to release the
1981	lock on the machine, or the machine's state will eventually be
1982	set to "Aborted".
1983
1984	In other words, to change settings on a machine, the following
1985	sequence is typically performed:
1986
1987	<ol>
1988	<li>Call this method (openSession) to have a machine locked for
1989	the current session.</li>
1990
1991	<li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
1992
1993	<li>Change the settings of the machine.</li>
1994
1995	<li>Call <link to="IMachine::saveSettings" />.</li>
1996
1997	<li>Close the session by calling <link to="ISession::close()"/>.</li>
1998	</ol>
1999	</desc>
2000	<param name="session" type="ISession" dir="in">
2001	<desc>
2002	Session object that will represent the opened session after
2003	successful method invocation. This object must not represent
2004	the already open session.
2005	<note>
2006	This session will be automatically closed if the
2007	VirtualBox server is terminated for some reason.
2008	</note>
2009	</desc>
2010	</param>
2011	<param name="machineId" type="uuid" dir="in">
2012	<desc>ID of the virtual machine to open a session with.</desc>
2013	</param>
2014	</method>
2015
2016	<method name="openRemoteSession">
2017	<desc>
2018	Spawns a new process that executes a virtual machine (called a
2019	"remote session").
2020
2021	Opening a remote session causes the VirtualBox server to start a new
2022	process that opens a direct session with the given VM. As a result, the
2023	VM is locked by that direct session in the new process, preventing
2024	conflicting changes from other processes. Since sessions act as locks
2025	that such prevent conflicting changes, one cannot open a remote session
2026	for a VM that already has another open session (direct or remote), or
2027	is currently in the process of opening one (see <link to="IMachine::sessionState"/>).
2028
2029	While the remote session still provides some level of control over the
2030	VM execution to the caller (using the <link to="IConsole" /> interface),
2031	not all VM settings are available for modification within the remote
2032	session context.
2033
2034	This operation can take some time (a new VM is started in a new process,
2035	for which memory and other resources need to be set up). Because of this,
2036	an <link to="IProgress" /> is returned to allow the caller to wait for this
2037	asynchronous operation to be completed. Until then, the remote session
2038	object remains in the closed state, and accessing the machine or its
2039	console through it is invalid. It is recommended to use
2040	<link to="IProgress::waitForCompletion" /> or similar calls to wait for
2041	completion.
2042
2043	As with all <link to="ISession" /> objects, it is recommended to call
2044	<link to="ISession::close" /> on the local session object once openRemoteSession()
2045	has been called. However, the session's state (see <link to="ISession::state" />)
2046	will not return to "Closed" until the remote session has also closed (i.e.
2047	until the VM is no longer running). In that case, however, the state of
2048	the session will automatically change back to "Closed".
2049
2050	Currently supported session types (values of the @a type
2051	argument) are:
2052	<ul>
2053	<li><tt>gui</tt>: VirtualBox Qt GUI session</li>
2054	<li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
2055	</ul>
2056
2057	The @a environment argument is a string containing definitions of
2058	environment variables in the following format:
2059	@code
2060	NAME[=VALUE]\n
2061	NAME[=VALUE]\n
2062	...
2063	@endcode
2064	where <tt>\\n</tt> is the new line character. These environment
2065	variables will be appended to the environment of the VirtualBox server
2066	process. If an environment variable exists both in the server process
2067	and in this list, the value from this list takes precedence over the
2068	server's variable. If the value of the environment variable is
2069	omitted, this variable will be removed from the resulting environment.
2070	If the environment string is @c null, the server environment is
2071	inherited by the started process as is.
2072
2073	<see>openExistingSession</see>
2074	</desc>
2075	<param name="session" type="ISession" dir="in">
2076	<desc>
2077	Session object that will represent the opened remote session
2078	after successful method invocation (this object must not
2079	represent an already open session).
2080	</desc>
2081	</param>
2082	<param name="machineId" type="uuid" dir="in">
2083	<desc>ID of the virtual machine to open a session with.</desc>
2084	</param>
2085	<param name="type" type="wstring" dir="in">
2086	<desc>
2087	Type of the remote session (case sensitive).
2088	</desc>
2089	</param>
2090	<param name="environment" type="wstring" dir="in">
2091	<desc>
2092	Environment to pass to the opened session (may be @c null).
2093	</desc>
2094	</param>
2095	<param name="progress" type="IProgress" dir="return">
2096	<desc>Progress object to track the operation completion.</desc>
2097	</param>
2098	</method>
2099
2100	<method name="openExistingSession">
2101	<desc>
2102	Opens a new remote session with the virtual machine for
2103	which a direct session is already open.
2104
2105	The remote session provides some level of control over the VM
2106	execution (using the IConsole interface) to the caller; however,
2107	within the remote session context, not all VM settings are available
2108	for modification.
2109
2110	As opposed to <link to="#openRemoteSession()"/>, the number of
2111	remote sessions opened this way is not limited by the API
2112
2113	<note>
2114	It is an error to open a remote session with the machine that
2115	doesn't have an open direct session.
2116	</note>
2117
2118	<see>openRemoteSession</see>
2119	</desc>
2120	<param name="session" type="ISession" dir="in">
2121	<desc>
2122	Session object that will represent the open remote session
2123	after successful method invocation. This object must not
2124	represent an already open session.
2125	<note>
2126	This session will be automatically closed when the peer
2127	(direct) session dies or gets closed.
2128	</note>
2129	</desc>
2130	</param>
2131	<param name="machineId" type="uuid" dir="in">
2132	<desc>ID of the virtual machine to open a session with.</desc>
2133	</param>
2134	</method>
2135
2136	<method name="registerCallback">
2137	<desc>
2138	Registers a new global VirtualBox callback. The methods of the given
2139	callback object will be called by VirtualBox when an appropriate
2140	event occurs.
2141	</desc>
2142	<param name="callback" type="IVirtualBoxCallback" dir="in">
2143	<desc>Callback object to register.</desc>
2144	</param>
2145	</method>
2146
2147	<method name="unregisterCallback">
2148	<desc>
2149	Unregisters the previously registered global VirtualBox callback.
2150	</desc>
2151	<param name="callback" type="IVirtualBoxCallback" dir="in">
2152	<desc>Callback object to unregister.</desc>
2153	</param>
2154	</method>
2155
2156	<method name="waitForPropertyChange">
2157	<desc>
2158	Blocks the caller until any of the properties represented by the @a
2159	what argument changes the value or until the given timeout interval
2160	expires.
2161
2162	The @a what argument is a comma separated list of property masks that
2163	describe properties the caller is interested in. The property mask is
2164	a string in the following format:
2165
2166	<pre>
2167	[[group.]subgroup.]name
2168	</pre>
2169
2170	where @c name is the property name and @c group, @c subgroup are zero
2171	or or more property group specifiers. Each element (group or name) in
2172	the property mask may be either a Latin string or an asterisk symbol
2173	(@c "*") which is used to match any string for the given element. A
2174	property mask that doesn't contain asterisk symbols represents a
2175	single fully qualified property name.
2176
2177	Groups in the fully qualified property name go from more generic (the
2178	left-most part) to more specific (the right-most part). The first
2179	element is usually a name of the object the property belongs to. The
2180	second element may be either a property name, or a child object name,
2181	or an index if the preceding element names an object which is one of
2182	many objects of the same type. This way, property names form a
2183	hierarchy of properties. Here are some examples of property names:
2184
2185	<table>
2186	<tr>
2187	<td><tt>VirtualBox.version</tt></td>
2188	<td><link to="IVirtualBox::version"/> property</td>
2189	</tr>
2190	<tr>
2191	<td><tt>Machine.<UUID>.name</tt></td>
2192	<td><link to="IMachine::name"/> property of the machine with the
2193	given UUID</td>
2194	</tr>
2195	</table>
2196
2197	Most property names directly correspond to the properties of objects
2198	(components) provided by the VirtualBox library and may be used to
2199	track changes to these properties. However, there may be
2200	pseudo-property names that don't correspond to any existing object's
2201	property directly, as well as there may be object properties that
2202	don't have a corresponding property name that is understood by this
2203	method, and therefore changes to such properties cannot be
2204	tracked. See individual object's property descriptions to get a
2205	fully qualified property name that can be used with this method (if
2206	any).
2207
2208	There is a special property mask @c "*" (i.e. a string consisting of a
2209	single asterisk symbol) that can be used to match all properties.
2210	Below are more examples of property masks:
2211
2212	<table>
2213	<tr>
2214	<td><tt>VirtualBox.*</tt></td>
2215	<td>Track all properties of the VirtualBox object</td>
2216	</tr>
2217	<tr>
2218	<td><tt>Machine.*.name</tt></td>
2219	<td>Track changes to the <link to="IMachine::name"/> property of
2220	all registered virtual machines</td>
2221	</tr>
2222	</table>
2223
2224	</desc>
2225	<param name="what" type="wstring" dir="in">
2226	<desc>Comma separated list of property masks.</desc>
2227	</param>
2228	<param name="timeout" type="unsigned long" dir="in">
2229	<desc>
2230	Wait timeout in milliseconds.
2231	Specify -1 for an indefinite wait.
2232	</desc>
2233	</param>
2234	<param name="changed" type="wstring" dir="out">
2235	<desc>
2236	Comma separated list of properties that have been changed and caused
2237	this method to return to the caller.
2238	</desc>
2239	</param>
2240	<param name="values" type="wstring" dir="out">
2241	<desc>Reserved, not currently used.</desc>
2242	</param>
2243	</method>
2244
2245	<method name="saveSettings">
2246	<desc>
2247	Saves the global settings to the global settings file
2248	(<link to="#settingsFilePath"/>).
2249
2250	This method is only useful for explicitly saving the global settings
2251	file after it has been auto-converted from the old format to the most
2252	recent format (see <link to="#settingsFileVersion"/> for details).
2253	Normally, the global settings file is implicitly saved when a global
2254	setting is changed.
2255	</desc>
2256	</method>
2257
2258	<method name="saveSettingsWithBackup">
2259	<desc>
2260	Creates a backup copy of the global settings file
2261	(<link to="#settingsFilePath"/>) in case of auto-conversion, and then
2262	calls <link to="#saveSettings()"/>.
2263
2264	Note that the backup copy is created <b>only</b> if the settings file
2265	auto-conversion took place (see <link to="#settingsFileVersion"/> for
2266	details). Otherwise, this call is fully equivalent to
2267	<link to="#saveSettings()"/> and no backup copying is done.
2268
2269	The backup copy is created in the same directory where the original
2270	settings file is located. It is given the following file name:
2271	<pre>
2272	original.xml.x.y-platform.bak
2273	</pre>
2274	where <tt>original.xml</tt> is the original settings file name
2275	(excluding path), and <tt>x.y-platform</tt> is the version of the old
2276	format of the settings file (before auto-conversion).
2277
2278	If the given backup file already exists, this method will try to add the
2279	<tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
2280	0 to 9) and copy it again until it succeeds. If all suffixes are
2281	occupied, or if any other copy error occurs, this method will return a
2282	failure.
2283
2284	If the copy operation succeeds, the @a bakFileName return argument will
2285	receive a full path to the created backup file (for informational
2286	purposes). Note that this will happen even if the subsequent
2287	<link to="#saveSettings()"/> call performed by this method after the
2288	copy operation, fails.
2289
2290	<note>
2291	The VirtualBox API never calls this method. It is intended purely for
2292	the purposes of creating backup copies of the settings files by
2293	front-ends before saving the results of the automatically performed
2294	settings conversion to disk.
2295	</note>
2296
2297	<see>settingsFileVersion</see>
2298	</desc>
2299	<param name="bakFileName" type="wstring" dir="return">
2300	<desc>Full path to the created backup copy.</desc>
2301	</param>
2302	</method>
2303
2304	</interface>
2305
2306	<!--
2307	// IMachine
2308	/////////////////////////////////////////////////////////////////////////
2309	-->
2310
2311	<enumerator
2312	name="IMachineEnumerator" type="IMachine"
2313	uuid="1b554149-be0a-4465-9252-9ff8f420af55"
2314	/>
2315
2316	<collection
2317	name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
2318	uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
2319	readonly="yes"
2320	/>
2321
2322	<interface
2323	name="IInternalMachineControl" extends="$unknown"
2324	uuid="4042ddf2-93d3-4749-8517-dde3f17ea630"
2325	internal="yes"
2326	wsmap="suppress"
2327	>
2328	<method name="updateState">
2329	<desc>
2330	Updates the VM state.
2331	<note>
2332	This operation will also update the settings file with
2333	the correct information about the saved state file
2334	and delete this file from disk when appropriate.
2335	</note>
2336	</desc>
2337	<param name="state" type="MachineState" dir="in"/>
2338	</method>
2339
2340	<method name="getIPCId">
2341	<param name="id" type="wstring" dir="return"/>
2342	</method>
2343
2344	<method name="runUSBDeviceFilters">
2345	<desc>
2346	Asks the server to run USB devices filters of the associated
2347	machine against the given USB device and tell if there is
2348	a match.
2349	<note>
2350	Intended to be used only for remote USB devices. Local
2351	ones don't require to call this method (this is done
2352	implicitly by the Host and USBProxyService).
2353	</note>
2354	</desc>
2355	<param name="device" type="IUSBDevice" dir="in"/>
2356	<param name="matched" type="boolean" dir="out"/>
2357	<param name="maskedInterfaces" type="unsigned long" dir="out"/>
2358	</method>
2359
2360	<method name="captureUSBDevice">
2361	<desc>
2362	Requests a capture of the given host USB device.
2363	When the request is completed, the VM process will
2364	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
2365	notification.
2366	</desc>
2367	<param name="id" type="uuid" dir="in"/>
2368	</method>
2369
2370	<method name="detachUSBDevice">
2371	<desc>
2372	Notification that a VM is going to detach (done = false) or has
2373	already detached (done = true) the given USB device.
2374	When the done = true request is completed, the VM process will
2375	get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
2376	notification.
2377	<note>
2378	In the done = true case, the server must run its own filters
2379	and filters of all VMs but this one on the detached device
2380	as if it were just attached to the host computer.
2381	</note>
2382	</desc>
2383	<param name="id" type="uuid" dir="in"/>
2384	<param name="done" type="boolean" dir="in"/>
2385	</method>
2386
2387	<method name="autoCaptureUSBDevices">
2388	<desc>
2389	Requests a capture all matching USB devices attached to the host.
2390	When the request is completed, the VM process will
2391	get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
2392	notification per every captured device.
2393	</desc>
2394	</method>
2395
2396	<method name="detachAllUSBDevices">
2397	<desc>
2398	Notification that a VM that is being powered down. The done
2399	parameter indicates whether which stage of the power down
2400	we're at. When done = false the VM is announcing its
2401	intentions, while when done = true the VM is reporting
2402	what it has done.
2403	<note>
2404	In the done = true case, the server must run its own filters
2405	and filters of all VMs but this one on all detach devices as
2406	if they were just attached to the host computer.
2407	</note>
2408	</desc>
2409	<param name="done" type="boolean" dir="in"/>
2410	</method>
2411
2412	<method name="onSessionEnd">
2413	<desc>
2414	Triggered by the given session object when the session is about
2415	to close normally.
2416	</desc>
2417	<param name="session" type="ISession" dir="in">
2418	<desc>Session that is being closed</desc>
2419	</param>
2420	<param name="progress" type="IProgress" dir="return">
2421	<desc>
2422	Used to wait until the corresponding machine is actually
2423	dissociated from the given session on the server.
2424	Returned only when this session is a direct one.
2425	</desc>
2426	</param>
2427	</method>
2428
2429	<method name="beginSavingState">
2430	<desc>
2431	Called by the VM process to inform the server it wants to
2432	save the current state and stop the VM execution.
2433	</desc>
2434	<param name="progress" type="IProgress" dir="in">
2435	<desc>
2436	Progress object created by the VM process to wait until
2437	the state is saved.
2438	</desc>
2439	</param>
2440	<param name="stateFilePath" type="wstring" dir="out">
2441	<desc>
2442	File path the VM process must save the execution state to.
2443	</desc>
2444	</param>
2445	</method>
2446
2447	<method name="endSavingState">
2448	<desc>
2449	Called by the VM process to inform the server that saving
2450	the state previously requested by #beginSavingState is either
2451	successfully finished or there was a failure.
2452	</desc>
2453
2454	<param name="success" type="boolean" dir="in">
2455	<desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
2456	</param>
2457	</method>
2458
2459	<method name="adoptSavedState">
2460	<desc>
2461	Gets called by IConsole::adoptSavedState.
2462	</desc>
2463	<param name="savedStateFile" type="wstring" dir="in">
2464	<desc>Path to the saved state file to adopt.</desc>
2465	</param>
2466	</method>
2467
2468	<method name="beginTakingSnapshot">
2469	<desc>
2470	Called by the VM process to inform the server it wants to
2471	take a snapshot.
2472	</desc>
2473	<param name="initiator" type="IConsole" dir="in">
2474	<desc>The console object that initiated this call.</desc>
2475	</param>
2476	<param name="name" type="wstring" dir="in">
2477	<desc>Snapshot name</desc>
2478	</param>
2479	<param name="description" type="wstring" dir="in">
2480	<desc>Snapshot description</desc>
2481	</param>
2482	<param name="progress" type="IProgress" dir="in">
2483	<desc>
2484	Progress object created by the VM process to wait until
2485	the state is saved (only for online snapshots).
2486	</desc>
2487	</param>
2488	<param name="stateFilePath" type="wstring" dir="out">
2489	<desc>
2490	File path the VM process must save the execution state to.
2491	</desc>
2492	</param>
2493	<param name="serverProgress" type="IProgress" dir="out">
2494	<desc>
2495	Progress object created by the server process to wait until
2496	the snapshot is taken (VDI diff creation, etc.).
2497	</desc>
2498	</param>
2499	</method>
2500
2501	<method name="endTakingSnapshot">
2502	<desc>
2503	Called by the VM process to inform the server that the snapshot
2504	previously requested by #beginTakingSnapshot is either
2505	successfully taken or there was a failure.
2506	</desc>
2507
2508	<param name="success" type="boolean" dir="in">
2509	<desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
2510	</param>
2511	</method>
2512
2513	<method name="discardSnapshot">
2514	<desc>
2515	Gets called by IConsole::discardSnapshot.
2516	</desc>
2517	<param name="initiator" type="IConsole" dir="in">
2518	<desc>The console object that initiated this call.</desc>
2519	</param>
2520	<param name="id" type="uuid" dir="in">
2521	<desc>UUID of the snapshot to discard.</desc>
2522	</param>
2523	<param name="machineState" type="MachineState" dir="out">
2524	<desc>New machine state after this operation is started.</desc>
2525	</param>
2526	<param name="progress" type="IProgress" dir="return">
2527	<desc>Progress object to track the operation completion.</desc>
2528	</param>
2529	</method>
2530
2531	<method name="discardCurrentState">
2532	<desc>
2533	Gets called by IConsole::discardCurrentState.
2534	</desc>
2535	<param name="initiator" type="IConsole" dir="in">
2536	<desc>The console object that initiated this call.</desc>
2537	</param>
2538	<param name="machineState" type="MachineState" dir="out">
2539	<desc>New machine state after this operation is started.</desc>
2540	</param>
2541	<param name="progress" type="IProgress" dir="return">
2542	<desc>Progress object to track the operation completion.</desc>
2543	</param>
2544	</method>
2545
2546	<method name="discardCurrentSnapshotAndState">
2547	<desc>
2548	Gets called by IConsole::discardCurrentSnapshotAndState.
2549	</desc>
2550	<param name="initiator" type="IConsole" dir="in">
2551	<desc>The console object that initiated this call.</desc>
2552	</param>
2553	<param name="machineState" type="MachineState" dir="out">
2554	<desc>New machine state after this operation is started.</desc>
2555	</param>
2556	<param name="progress" type="IProgress" dir="return">
2557	<desc>Progress object to track the operation completion.</desc>
2558	</param>
2559	</method>
2560
2561	<method name="pullGuestProperties">
2562	<desc>
2563	Get the list of the guest properties matching a set of patterns along
2564	with their values, time stamps and flags and give responsibility for
2565	managing properties to the console.
2566	</desc>
2567	<param name="name" type="wstring" dir="out" safearray="yes">
2568	<desc>
2569	The names of the properties returned.
2570	</desc>
2571	</param>
2572	<param name="value" type="wstring" dir="out" safearray="yes">
2573	<desc>
2574	The values of the properties returned. The array entries match the
2575	corresponding entries in the @a name array.
2576	</desc>
2577	</param>
2578	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
2579	<desc>
2580	The time stamps of the properties returned. The array entries match
2581	the corresponding entries in the @a name array.
2582	</desc>
2583	</param>
2584	<param name="flags" type="wstring" dir="out" safearray="yes">
2585	<desc>
2586	The flags of the properties returned. The array entries match the
2587	corresponding entries in the @a name array.
2588	</desc>
2589	</param>
2590	</method>
2591
2592	<method name="pushGuestProperties">
2593	<desc>
2594	Set the list of the guest properties matching a set of patterns along
2595	with their values, time stamps and flags and return responsibility for
2596	managing properties to IMachine.
2597	</desc>
2598	<param name="name" type="wstring" dir="in" safearray="yes">
2599	<desc>
2600	The names of the properties.
2601	</desc>
2602	</param>
2603	<param name="value" type="wstring" dir="in" safearray="yes">
2604	<desc>
2605	The values of the properties. The array entries match the
2606	corresponding entries in the @a name array.
2607	</desc>
2608	</param>
2609	<param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
2610	<desc>
2611	The time stamps of the properties. The array entries match
2612	the corresponding entries in the @a name array.
2613	</desc>
2614	</param>
2615	<param name="flags" type="wstring" dir="in" safearray="yes">
2616	<desc>
2617	The flags of the properties. The array entries match the
2618	corresponding entries in the @a name array.
2619	</desc>
2620	</param>
2621	</method>
2622	<method name="pushGuestProperty">
2623	<desc>
2624	Update a single guest property in IMachine.
2625	</desc>
2626	<param name="name" type="wstring" dir="in">
2627	<desc>
2628	The name of the property to be updated.
2629	</desc>
2630	</param>
2631	<param name="value" type="wstring" dir="in">
2632	<desc>
2633	The value of the property.
2634	</desc>
2635	</param>
2636	<param name="timestamp" type="unsigned long long" dir="in">
2637	<desc>
2638	The timestamp of the property.
2639	</desc>
2640	</param>
2641	<param name="flags" type="wstring" dir="in">
2642	<desc>
2643	The flags of the property.
2644	</desc>
2645	</param>
2646	</method>
2647	</interface>
2648
2649	<interface
2650	name="IBIOSSettings" extends="$unknown"
2651	uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
2652	wsmap="managed"
2653	>
2654	<desc>
2655	The IBIOSSettings interface represents BIOS settings of the virtual
2656	machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
2657	</desc>
2658	<attribute name="logoFadeIn" type="boolean">
2659	<desc>Fade in flag for BIOS logo animation.</desc>
2660	</attribute>
2661
2662	<attribute name="logoFadeOut" type="boolean">
2663	<desc>Fade out flag for BIOS logo animation.</desc>
2664	</attribute>
2665
2666	<attribute name="logoDisplayTime" type="unsigned long">
2667	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
2668	</attribute>
2669
2670	<attribute name="logoImagePath" type="wstring">
2671	<desc>Local file system path for external BIOS image.</desc>
2672	</attribute>
2673
2674	<attribute name="bootMenuMode" type="BIOSBootMenuMode">
2675	<desc>Mode of the BIOS boot device menu.</desc>
2676	</attribute>
2677
2678	<attribute name="ACPIEnabled" type="boolean">
2679	<desc>ACPI support flag.</desc>
2680	</attribute>
2681
2682	<attribute name="IOAPICEnabled" type="boolean">
2683	<desc>
2684	IO APIC support flag. If set, VirtualBox will provide an IO APIC
2685	and support IRQs above 15.
2686	</desc>
2687	</attribute>
2688
2689	<attribute name="timeOffset" type="long long">
2690	<desc>
2691	Offset in milliseconds from the host system time. This allows for
2692	guests running with a different system date/time than the host.
2693	It is equivalent to setting the system date/time in the BIOS other
2694	than it's not an absolute value but a relative one. Guest Additions
2695	time synchronization also honors this offset.
2696	</desc>
2697	</attribute>
2698
2699	<attribute name="PXEDebugEnabled" type="boolean">
2700	<desc>
2701	PXE debug logging flag. If set, VirtualBox will write extensive
2702	PXE trace information to the release log.
2703	</desc>
2704	</attribute>
2705
2706	<attribute name="IDEControllerType" type="IDEControllerType">
2707	<desc>
2708	Type of the virtual IDE controller. Depending on this value,
2709	VirtualBox will provide different virtual IDE hardware
2710	devices to the guest.
2711	</desc>
2712	</attribute>
2713
2714	</interface>
2715
2716	<interface
2717	name="IMachine" extends="$unknown"
2718	uuid="a744b229-3457-422f-8550-649c40346c55"
2719	wsmap="managed"
2720	>
2721	<desc>
2722	The IMachine interface represents a virtual machine, or guest, created
2723	in VirtualBox.
2724
2725	This interface is used in two contexts. First of all, a collection of
2726	objects implementing this interface is stored in the
2727	<link to="IVirtualBox::machines2"/> attribute which lists all the virtual
2728	machines that are currently registered with this VirtualBox
2729	installation. Also, once a session has been opened for the given virtual
2730	machine (e.g. the virtual machine is running), the machine object
2731	associated with the open session can be queried from the session object;
2732	see <link to="ISession"/> for details.
2733
2734	The main role of this interface is to expose the settings of the virtual
2735	machine and provide methods to change various aspects of the virtual
2736	machine's configuration. For machine objects stored in the
2737	<link to="IVirtualBox::machines2"/> collection, all attributes are
2738	read-only unless explicitly stated otherwise in individual attribute
2739	and method descriptions. In order to change a machine setting, a session
2740	for this machine must be opened using one of
2741	<link to="IVirtualBox::openSession"/>,
2742	<link to="IVirtualBox::openRemoteSession"/> or
2743	<link to="IVirtualBox::openExistingSession"/> methods. After the
2744	session has been successfully opened, a mutable machine object needs to
2745	be queried from the session object and then the desired settings changes
2746	can be applied to the returned object using IMachine attributes and
2747	methods. See the ISession interface description for more information
2748	about sessions.
2749
2750	Note that the IMachine interface does not provide methods to control
2751	virtual machine execution (such as start the machine, or power it
2752	down) -- these methods are grouped in a separate IConsole
2753	interface. Refer to the IConsole interface description to get more
2754	information about this topic.
2755
2756	<see>ISession, IConsole</see>
2757	</desc>
2758
2759	<attribute name="parent" type="IVirtualBox" readonly="yes">
2760	<desc>Associated parent object.</desc>
2761	</attribute>
2762
2763	<attribute name="accessible" type="boolean" readonly="yes">
2764	<desc>
2765	Whether this virtual machine is currently accessible or not.
2766
2767	The machine is considered to be inaccessible when:
2768	<ul>
2769	<li>It is a registered virtual machine, and
2770	</li>
2771	<li>Its settings file is inaccessible (for example, it is
2772	located on a network share that is not accessible during
2773	VirtualBox startup, or becomes inaccessible later, or if
2774	the settings file can be read but is invalid).
2775	</li>
2776	</ul>
2777
2778	Otherwise, the value of this property is always <tt>true</tt>.
2779
2780	Every time this property is read, the accessibility state of
2781	this machine is re-evaluated. If the returned value is \|false\|,
2782	the <link to="#accessError"/> property may be used to get the
2783	detailed error information describing the reason of
2784	inaccessibility.
2785
2786	When the machine is inaccessible, only the following properties
2787	can be used on it:
2788	<ul>
2789	<li><link to="#parent"/></li>
2790	<li><link to="#id"/></li>
2791	<li><link to="#settingsFilePath"/></li>
2792	<li><link to="#accessible"/></li>
2793	<li><link to="#accessError"/></li>
2794	</ul>
2795
2796	An attempt to access any other property or method will return
2797	an error.
2798
2799	The only possible action you can perform on an inaccessible
2800	machine is to unregister it using the
2801	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
2802	for the accessibility state once more by querying this
2803	property).
2804
2805	<note>
2806	In the current implementation, once this property returns
2807	<tt>true</tt>, the machine will never become inaccessible
2808	later, even if its settings file cannot be successfully
2809	read/written any more (at least, until the VirtualBox
2810	server is restarted). This limitation may be removed in
2811	future releases.
2812	</note>
2813	</desc>
2814	</attribute>
2815
2816	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
2817	<desc>
2818	Error information describing the reason of machine
2819	inaccessibility.
2820
2821	Reading this property is only valid after the last call to
2822	<link to="#accessible"/> returned <tt>false</tt> (i.e. the
2823	machine is currently unaccessible). Otherwise, a null
2824	IVirtualBoxErrorInfo object will be returned.
2825	</desc>
2826	</attribute>
2827
2828	<attribute name="name" type="wstring">
2829	<desc>
2830	Name of the virtual machine.
2831
2832	Besides being used for human-readable identification purposes
2833	everywhere in VirtualBox, the virtual machine name is also used
2834	as a name of the machine's settings file and as a name of the
2835	subdirectory this settings file resides in. Thus, every time you
2836	change the value of this property, the settings file will be
2837	renamed once you call <link to="#saveSettings()"/> to confirm the
2838	change. The containing subdirectory will be also renamed, but
2839	only if it has exactly the same name as the settings file
2840	itself prior to changing this property (for backward compatibility
2841	with previous API releases). The above implies the following
2842	limitations:
2843	<ul>
2844	<li>The machine name cannot be empty.</li>
2845	<li>The machine name can contain only characters that are valid
2846	file name characters according to the rules of the file
2847	system used to store VirtualBox configuration.</li>
2848	<li>You cannot have two or more machines with the same name
2849	if they use the same subdirectory for storing the machine
2850	settings files.</li>
2851	<li>You cannot change the name of the machine if it is running,
2852	or if any file in the directory containing the settings file
2853	is being used by another running machine or by any other
2854	process in the host operating system at a time when
2855	<link to="#saveSettings()"/> is called.
2856	</li>
2857	</ul>
2858	If any of the above limitations are hit, <link to="#saveSettings()"/>
2859	will return an appropriate error message explaining the exact
2860	reason and the changes you made to this machine will not be
2861	saved.
2862	<note>
2863	For "legacy" machines created using the
2864	<link to="IVirtualBox::createLegacyMachine()"/> call,
2865	the above naming limitations do not apply because the
2866	machine name does not affect the settings file name.
2867	The settings file name remains the same as it was specified
2868	during machine creation and never changes.
2869	</note>
2870	</desc>
2871	</attribute>
2872
2873	<attribute name="description" type="wstring">
2874	<desc>
2875	Description of the virtual machine.
2876
2877	The description attribute can contain any text and is
2878	typically used to describe the hardware and software
2879	configuration of the virtual machine in detail (i.e. network
2880	settings, versions of the installed software and so on).
2881	</desc>
2882	</attribute>
2883
2884	<attribute name="id" type="uuid" readonly="yes">
2885	<desc>UUID of the virtual machine.</desc>
2886	</attribute>
2887
2888	<attribute name="OSTypeId" type="wstring">
2889	<desc>
2890	User-defined identifier of the Guest OS type.
2891	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
2892	an IGuestOSType object representing details about the given
2893	Guest OS type.
2894	<note>
2895	This value may differ from the value returned by
2896	<link to="IGuest::OSTypeId"/> if Guest Additions are
2897	installed to the guest OS.
2898	</note>
2899	</desc>
2900	</attribute>
2901
2902	<attribute name="CPUCount" type="unsigned long">
2903	<desc>Number of virtual CPUs in the VM.</desc>
2904	</attribute>
2905
2906	<attribute name="memorySize" type="unsigned long">
2907	<desc>System memory size in megabytes.</desc>
2908	</attribute>
2909
2910	<attribute name="memoryBalloonSize" type="unsigned long">
2911	<desc>Initial memory balloon size in megabytes.</desc>
2912	</attribute>
2913
2914	<attribute name="statisticsUpdateInterval" type="unsigned long">
2915	<desc>Initial interval to update guest statistics in seconds.</desc>
2916	</attribute>
2917
2918	<attribute name="VRAMSize" type="unsigned long">
2919	<desc>Video memory size in megabytes.</desc>
2920	</attribute>
2921
2922	<attribute name="accelerate3DEnabled" type="boolean" default="false">
2923	<desc>
2924	This setting determines whether VirtualBox allows guests to make use
2925	of the 3D graphics support available on the host. Currently limited
2926	to OpenGL only. </desc>
2927	</attribute>
2928
2929	<attribute name="monitorCount" type="unsigned long">
2930	<desc>
2931	Number of virtual monitors.
2932	<note>
2933	Only effective on Windows XP and later guests with
2934	Guest Additions installed.
2935	</note>
2936	</desc>
2937	</attribute>
2938
2939	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
2940	<desc>Object containing all BIOS settings.</desc>
2941	</attribute>
2942
2943	<attribute name="HWVirtExEnabled" type="TSBool">
2944	<desc>
2945	This setting determines whether VirtualBox will try to make use of
2946	the host CPU's hardware virtualization extensions such as Intel VT-x
2947	and AMD-V. Note that in case such extensions are not available,
2948	they will not be used.
2949	</desc>
2950	</attribute>
2951
2952	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">
2953	<desc>
2954	This setting determines whether VirtualBox will try to make use of
2955	the nested paging extension of Intel VT-x and AMD-V. Note that in case
2956	such extensions are not available, they will not be used.
2957	</desc>
2958	</attribute>
2959
2960	<attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">
2961	<desc>
2962	This setting determines whether VirtualBox will try to make use of
2963	the VPID extension of Intel VT-x. Note that in case such extensions are
2964	not available, they will not be used.
2965	</desc>
2966	</attribute>
2967
2968	<attribute name="PAEEnabled" type="boolean" default="false">
2969	<desc>
2970	This setting determines whether VirtualBox will expose the Physical Address
2971	Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
2972	is not available, it will not be reported.
2973	</desc>
2974	</attribute>
2975
2976	<attribute name="snapshotFolder" type="wstring">
2977	<desc>
2978	Full path to the directory used to store snapshot data
2979	(differencing hard disks and saved state files) of this machine.
2980
2981	The initial value of this property is
2982	<tt><</tt><link to="#settingsFilePath">
2983	path_to_settings_file</link><tt>>/<</tt>
2984	<link to="#id">machine_uuid</link>
2985	<tt>></tt>.
2986
2987	Currently, it is an error to try to change this property on
2988	a machine that has snapshots (because this would require to
2989	move possibly large files to a different location).
2990	A separate method will be available for this purpose later.
2991
2992	<note>
2993	Setting this property to <tt>null</tt> will restore the
2994	initial value.
2995	</note>
2996	<note>
2997	When setting this property, the specified path can be
2998	absolute (full path) or relative to the directory where the
2999	<link to="#settingsFilePath">machine settings file</link>
3000	is located. When reading this property, a full path is
3001	always returned.
3002	</note>
3003	<note>
3004	The specified path may not exist, it will be created
3005	when necessary.
3006	</note>
3007	</desc>
3008	</attribute>
3009
3010	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
3011	<desc>VRDP server object.</desc>
3012	</attribute>
3013
3014	<attribute name="hardDisk2Attachments" type="IHardDisk2Attachment" readonly="yes" safearray="yes">
3015	<desc>Array of hard disks attached to this machine.</desc>
3016	</attribute>
3017
3018	<attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
3019	<desc>Associated DVD drive object.</desc>
3020	</attribute>
3021
3022	<attribute name="floppyDrive" type="IFloppyDrive" readonly="yes">
3023	<desc>Associated floppy drive object.</desc>
3024	</attribute>
3025
3026	<attribute name="USBController" type="IUSBController" readonly="yes">
3027	<desc>
3028	Associated USB controller object.
3029
3030	<note>
3031	This method may set a @ref com_warnings "warning result code".
3032	</note>
3033	<note>
3034	If USB functionality is not available in the given edition of
3035	VirtualBox, this method will set the result code to @c E_NOTIMPL.
3036	</note>
3037	</desc>
3038	</attribute>
3039
3040	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
3041	<desc>Associated audio adapter, always present.</desc>
3042	</attribute>
3043
3044	<attribute name="SATAController" type="ISATAController" readonly="yes">
3045	<desc>
3046	Associated SATA controller object.
3047	</desc>
3048	</attribute>
3049
3050	<attribute name="settingsFilePath" type="wstring" readonly="yes">
3051	<desc>
3052	Full name of the file containing machine settings data.
3053	</desc>
3054	</attribute>
3055
3056	<attribute name="settingsFileVersion" type="wstring" readonly="yes">
3057	<desc>
3058	Current version of the format of the settings file of this machine
3059	(<link to="#settingsFilePath"/>).
3060
3061	The version string has the following format:
3062	<pre>
3063	x.y-platform
3064	</pre>
3065	where <tt>x</tt> and <tt>y</tt> are the major and the minor format
3066	versions, and <tt>platform</tt> is the platform identifier.
3067
3068	The current version usually matches the value of the
3069	<link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
3070	settings file was created by an older version of VirtualBox and there
3071	was a change of the settings file format since then.
3072
3073	Note that VirtualBox automatically converts settings files from older
3074	versions to the most recent version when reading them (usually at
3075	VirtualBox startup) but it doesn't save the changes back until
3076	you call a method that implicitly saves settings (such as
3077	<link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
3078	explicitly. Therefore, if the value of this attribute differs from the
3079	value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
3080	means that the settings file was converted but the result of the
3081	conversion is not yet saved to disk.
3082
3083	The above feature may be used by interactive front-ends to inform users
3084	about the settings file format change and offer them to explicitly save
3085	all converted settings files (the global and VM-specific ones),
3086	optionally create backup copies of the old settings files before saving,
3087	etc.
3088
3089	<see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
3090	</desc>
3091	</attribute>
3092
3093	<attribute name="settingsModified" type="boolean" readonly="yes">
3094	<desc>
3095	Whether the settings of this machine have been modified
3096	(but neither yet saved nor discarded).
3097	<note>
3098	Reading this property is only valid on instances returned
3099	by <link to="ISession::machine"/> and on new machines
3100	created by <link to="IVirtualBox::createMachine"/> or opened
3101	by <link to="IVirtualBox::openMachine"/> but not
3102	yet registered, or on unregistered machines after calling
3103	<link to="IVirtualBox::unregisterMachine"/>. For all other
3104	cases, the settings can never be modified.
3105	</note>
3106	<note>
3107	For newly created unregistered machines, the value of this
3108	property is always TRUE until <link to="#saveSettings()"/>
3109	is called (no matter if any machine settings have been
3110	changed after the creation or not). For opened machines
3111	the value is set to FALSE (and then follows to normal rules).
3112	</note>
3113	</desc>
3114	</attribute>
3115
3116	<attribute name="sessionState" type="SessionState" readonly="yes">
3117	<desc>Current session state for this machine.</desc>
3118	</attribute>
3119
3120	<attribute name="sessionType" type="wstring" readonly="yes">
3121	<desc>
3122	Type of the session. If <link to="#sessionState"/> is
3123	SessionSpawning or SessionOpen, this attribute contains the
3124	same value as passed to the
3125	<link to="IVirtualBox::openRemoteSession()"/> method in the @a
3126	type parameter. If the session was opened directly using
3127	<link to="IVirtualBox::openSession()"/>, or if
3128	<link to="#sessionState"/> is SessionClosed, the value of this
3129	attribute is @c null.
3130	</desc>
3131	</attribute>
3132
3133	<attribute name="sessionPid" type="unsigned long" readonly="yes">
3134	<desc>
3135	Identifier of the session process. This attribute contains the
3136	platform-dependent identifier of the process that has opened a
3137	direct session for this machine using the
3138	<link to="IVirtualBox::openSession()"/> call. The returned value
3139	is only valid if <link to="#sessionState"/> is SessionOpen or
3140	SessionClosing (i.e. a session is currently open or being
3141	closed) by the time this property is read.
3142	</desc>
3143	</attribute>
3144
3145	<attribute name="state" type="MachineState" readonly="yes">
3146	<desc>Current execution state of this machine.</desc>
3147	</attribute>
3148
3149	<attribute name="lastStateChange" type="long long" readonly="yes">
3150	<desc>
3151	Time stamp of the last execution state change,
3152	in milliseconds since 1970-01-01 UTC.
3153	</desc>
3154	</attribute>
3155
3156	<attribute name="stateFilePath" type="wstring" readonly="yes">
3157	<desc>
3158	Full path to the file that stores the execution state of
3159	the machine when it is in the <link to="MachineState::Saved"/>
3160	state.
3161	<note>
3162	When the machine is not in the Saved state, this attribute
3163	<tt>null</tt>.
3164	</note>
3165	</desc>
3166	</attribute>
3167
3168	<attribute name="logFolder" type="wstring" readonly="yes">
3169	<desc>
3170	Full path to the folder that stores a set of rotated log files
3171	recorded during machine execution. The most recent log file is
3172	named <tt>VBox.log</tt>, the previous log file is
3173	named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
3174	in the current version).
3175	</desc>
3176	</attribute>
3177
3178	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
3179	<desc>
3180	Current snapshot of this machine.
3181	<note>
3182	A <tt>null</tt> object is returned if the machine doesn't
3183	have snapshots.
3184	</note>
3185	<see><link to="ISnapshot"/></see>
3186	</desc>
3187	</attribute>
3188
3189	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
3190	<desc>
3191	Number of snapshots taken on this machine. Zero means the
3192	machine doesn't have any snapshots.
3193	</desc>
3194	</attribute>
3195
3196	<attribute name="currentStateModified" type="boolean" readonly="yes">
3197	<desc>
3198	Returns <tt>true</tt> if the current state of the machine is not
3199	identical to the state stored in the current snapshot.
3200
3201	The current state is identical to the current snapshot right
3202	after one of the following calls are made:
3203	<ul>
3204	<li><link to="IConsole::discardCurrentState"/> or
3205	<link to="IConsole::discardCurrentSnapshotAndState"/>
3206	</li>
3207	<li><link to="IConsole::takeSnapshot"/> (issued on a
3208	powered off or saved machine, for which
3209	<link to="#settingsModified"/> returns <tt>false</tt>)
3210	</li>
3211	<li><link to="IMachine::setCurrentSnapshot"/>
3212	</li>
3213	</ul>
3214
3215	The current state remains identical until one of the following
3216	happens:
3217	<ul>
3218	<li>settings of the machine are changed</li>
3219	<li>the saved state is discarded</li>
3220	<li>the current snapshot is discarded</li>
3221	<li>an attempt to execute the machine is made</li>
3222	</ul>
3223
3224	<note>
3225	For machines that don't have snapshots, this property is
3226	always <tt>false</tt>.
3227	</note>
3228	</desc>
3229	</attribute>
3230
3231	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
3232	<desc>
3233	Collection of shared folders for this machine (permanent shared
3234	folders). These folders are shared automatically at machine startup
3235	and available only to the guest OS installed within this machine.
3236
3237	New shared folders are added to the collection using
3238	<link to="#createSharedFolder"/>. Existing shared folders can be
3239	removed using <link to="#removeSharedFolder"/>.
3240	</desc>
3241	</attribute>
3242
3243	<attribute name="clipboardMode" type="ClipboardMode">
3244	<desc>
3245	Synchronization mode between the host OS clipboard
3246	and the guest OS clipboard.
3247	</desc>
3248	</attribute>
3249
3250	<attribute name="guestPropertyNotificationPatterns" type="wstring">
3251	<desc>
3252	A comma-separated list of simple glob patterns. Changes to guest
3253	properties whose name matches one of the patterns will generate an
3254	<link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
3255	</desc>
3256	</attribute>
3257
3258	<method name="setBootOrder">
3259	<desc>
3260	Puts the given device to the specified position in
3261	the boot order.
3262
3263	To indicate that no device is associated with the given position,
3264	<link to="DeviceType::Null"/> should be used.
3265
3266	@todo setHardDiskBootOrder(), setNetworkBootOrder()
3267	</desc>
3268	<param name="position" type="unsigned long" dir="in">
3269	<desc>
3270	Position in the boot order (<tt>1</tt> to the total number of
3271	devices the machine can boot from, as returned by
3272	<link to="ISystemProperties::maxBootPosition"/>).
3273	</desc>
3274	</param>
3275	<param name="device" type="DeviceType" dir="in">
3276	<desc>
3277	The type of the device used to boot at the given position.
3278	</desc>
3279	</param>
3280	</method>
3281
3282	<method name="getBootOrder" const="yes">
3283	<desc>
3284	Returns the device type that occupies the specified
3285	position in the boot order.
3286
3287	@todo [remove?]
3288	If the machine can have more than one device of the returned type
3289	(such as hard disks), then a separate method should be used to
3290	retrieve the individual device that occupies the given position.
3291
3292	If here are no devices at the given position, then
3293	<link to="DeviceType::Null"/> is returned.
3294
3295	@todo getHardDiskBootOrder(), getNetworkBootOrder()
3296	</desc>
3297	<param name="order" type="unsigned long" dir="in">
3298	<desc>
3299	Position in the boot order (<tt>1</tt> to the total number of
3300	devices the machine can boot from, as returned by
3301	<link to="ISystemProperties::maxBootPosition"/>).
3302	</desc>
3303	</param>
3304	<param name="device" type="DeviceType" dir="return">
3305	<desc>
3306	Device at the given position.
3307	</desc>
3308	</param>
3309	</method>
3310
3311	<method name="attachHardDisk2">
3312	<desc>
3313	Attaches a virtual hard disk identified by the given UUID to a device
3314	slot of the specified bus.
3315
3316	For the IDE bus, the @a channel parameter can be either @c 0 or @c 1, to
3317	specify the primary or secondary IDE controller, respectively. The
3318	SATA bus supports 30 channels, so this parameter can be a number in
3319	range from @c 0 to @c 29.
3320
3321	For the primary controller of the IDE bus, the @a device number can be
3322	either @c 0 or @c 1, to specify the master or the slave device,
3323	respectively. For the secondary IDE controller, the device number is
3324	always @c 1 because the master device is reserved for the CD-ROM drive.
3325
3326	For the SATA bus, the @a device parameter is not currently used and
3327	must always be @c 0.
3328
3329	The specified device slot must not have another disk attached to it, or
3330	this method will fail.
3331
3332	See <link to="IHardDisk2"/> for more detailed information about
3333	attaching hard disks.
3334
3335	<note>
3336	You cannot attach a hard disk to a running machine. Also, you cannot
3337	attach a hard disk to a newly created machine until this machine's
3338	settings are saved to disk using <link to="#saveSettings()"/>.
3339	</note>
3340	<note>
3341	If the hard disk is being attached indirectly, a new differencing hard
3342	disk will be implicitly created for it and attached instead. If the
3343	changes made to the machine settings (including this indirect
3344	attachment) are later cancelled using <link to="#discardSettings()"/>,
3345	this implicitly created differencing hard disk will be implicitly
3346	deleted.
3347	</note>
3348	</desc>
3349	<param name="id" type="uuid" dir="in">
3350	<desc>UUID of the hard disk to attach.</desc>
3351	</param>
3352	<param name="bus" type="StorageBus" dir="in">
3353	<desc>Type of the storage bus to use (IDE or SATA).</desc>
3354	</param>
3355	<param name="channel" type="long" dir="in">
3356	<desc>Channel to attach the hard disk to.</desc>
3357	</param>
3358	<param name="device" type="long" dir="in">
3359	<desc>
3360	Device slot in the given channel to attach the hard disk to.
3361	</desc>
3362	</param>
3363	</method>
3364
3365	<method name="getHardDisk2" const="yes">
3366	<desc>
3367	Returns the virtual hard disk attached to a device slot of the specified
3368	bus.
3369
3370	Note that if the hard disk was indirectly attached by
3371	<link to="#attachHardDisk2()"/> to the given device slot then this
3372	method will return not the same object as passed to the
3373	<link to="#attachHardDisk2()"/> call. See <link to="IHardDisk2"/> for
3374	more detailed information about attaching hard disks.
3375	</desc>
3376	<param name="bus" type="StorageBus" dir="in">
3377	<desc>Type of the storage bus to query (IDE or SATA).</desc>
3378	</param>
3379	<param name="channel" type="long" dir="in">
3380	<desc>Channel to query.</desc>
3381	</param>
3382	<param name="device" type="long" dir="in">
3383	<desc>Device slot in the given channel to query.</desc>
3384	</param>
3385	<param name="hardDisk" type="IHardDisk2" dir="return">
3386	<desc>Attached hard disk object.</desc>
3387	</param>
3388	</method>
3389
3390	<method name="detachHardDisk2">
3391	<desc>
3392	Detaches the virtual hard disk attached to a device slot of the
3393	specified bus.
3394
3395	Detaching the hard disk from the virtual machine is deferred. This means
3396	that the hard disk remains associated with the machine when this method
3397	returns and gets actually de-associated only after a successful
3398	<link to="#saveSettings()"/> call. See <link to="IHardDisk2"/>
3399	for more detailed information about attaching hard disks.
3400
3401	<note>
3402	You cannot detach the hard disk from a running machine.
3403	</note>
3404	<note>
3405	Detaching differencing hard disks implicitly created by <link
3406	to="#attachHardDisk2()"/> for the indirect attachment using this
3407	method will <b>not</b> implicitly delete them. The
3408	<link to="IHardDisk2::deleteStorage()"/> operation should be
3409	explicitly performed by the caller after the hard disk is successfully
3410	detached and the settings are saved with
3411	<link to="#saveSettings()"/>, if it is the desired action.
3412	</note>
3413
3414	</desc>
3415	<param name="bus" type="StorageBus" dir="in">
3416	<desc>Bus to detach the hard disk from.</desc>
3417	</param>
3418	<param name="channel" type="long" dir="in">
3419	<desc>Channel number to detach the hard disk from.</desc>
3420	</param>
3421	<param name="device" type="long" dir="in">
3422	<desc>Device slot number to detach the hard disk from.</desc>
3423	</param>
3424	</method>
3425
3426	<method name="getNetworkAdapter" const="yes">
3427	<desc>
3428	Returns the network adapter associated with the given slot.
3429	Slots are numbered sequentially, starting with zero. The total
3430	number of adapters per every machine is defined by the
3431	<link to="ISystemProperties::networkAdapterCount"/> property,
3432	so the maximum slot number is one less than that property's value.
3433	</desc>
3434	<param name="slot" type="unsigned long" dir="in"/>
3435	<param name="adapter" type="INetworkAdapter" dir="return"/>
3436	</method>
3437
3438	<method name="getSerialPort" const="yes">
3439	<desc>
3440	Returns the serial port associated with the given slot.
3441	Slots are numbered sequentially, starting with zero. The total
3442	number of serial ports per every machine is defined by the
3443	<link to="ISystemProperties::serialPortCount"/> property,
3444	so the maximum slot number is one less than that property's value.
3445	</desc>
3446	<param name="slot" type="unsigned long" dir="in"/>
3447	<param name="port" type="ISerialPort" dir="return"/>
3448	</method>
3449
3450	<method name="getParallelPort" const="yes">
3451	<desc>
3452	Returns the parallel port associated with the given slot.
3453	Slots are numbered sequentially, starting with zero. The total
3454	number of parallel ports per every machine is defined by the
3455	<link to="ISystemProperties::parallelPortCount"/> property,
3456	so the maximum slot number is one less than that property's value.
3457	</desc>
3458	<param name="slot" type="unsigned long" dir="in"/>
3459	<param name="port" type="IParallelPort" dir="return"/>
3460	</method>
3461
3462	<method name="getNextExtraDataKey">
3463	<desc>
3464	Returns the machine-specific extra data key name following the
3465	supplied key.
3466
3467	An error is returned if the supplied @a key does not exist. @c NULL is
3468	returned in @a nextKey if the supplied key is the last key. When
3469	supplying @c NULL for the @a key, the first key item is returned in @a
3470	nextKey (if there is any). @a nextValue is an optional parameter and
3471	if supplied, the next key's value is returned in it.
3472	</desc>
3473	<param name="key" type="wstring" dir="in">
3474	<desc>Name of the data key to follow.</desc>
3475	</param>
3476	<param name="nextKey" type="wstring" dir="out">
3477	<desc>Name of the next data key.</desc>
3478	</param>
3479	<param name="nextValue" type="wstring" dir="out">
3480	<desc>Value of the next data key.</desc>
3481	</param>
3482	</method>
3483
3484	<method name="getExtraData">
3485	<desc>
3486	Returns associated machine-specific extra data.
3487
3488	If the requested data @a key does not exist, this function will
3489	succeed and return @c NULL in the @a value argument.
3490	</desc>
3491	<param name="key" type="wstring" dir="in">
3492	<desc>Name of the data key to get.</desc>
3493	</param>
3494	<param name="value" type="wstring" dir="return">
3495	<desc>Value of the requested data key.</desc>
3496	</param>
3497	</method>
3498
3499	<method name="setExtraData">
3500	<desc>
3501	Sets associated machine-specific extra data.
3502
3503	If you pass @c NULL as a key @a value, the given @a key will be
3504	deleted.
3505
3506	<note>
3507	Before performing the actual data change, this method will ask all
3508	registered callbacks using the
3509	<link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
3510	notification for a permission. If one of the callbacks refuses the
3511	new value, the change will not be performed.
3512	</note>
3513	<note>
3514	On success, the
3515	<link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
3516	is called to inform all registered callbacks about a successful data
3517	change.
3518	</note>
3519	<note>
3520	This method can be called outside the machine session and therefore
3521	it's a caller's responsibility to handle possible race conditions
3522	when several clients change the same key at the same time.
3523	</note>
3524	</desc>
3525	<param name="key" type="wstring" dir="in">
3526	<desc>Name of the data key to set.</desc>
3527	</param>
3528	<param name="value" type="wstring" dir="in">
3529	<desc>Value to assign to the key.</desc>
3530	</param>
3531	</method>
3532
3533	<method name="saveSettings">
3534	<desc>
3535	Saves any changes to machine settings made since the session
3536	has been opened or a new machine has been created, or since the
3537	last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>.
3538	For registered machines, new settings become visible to all
3539	other VirtualBox clients after successful invocation of this
3540	method.
3541	<note>
3542	The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/>
3543	notification event after the configuration has been successfully
3544	saved (only for registered machines).
3545	</note>
3546	<note>
3547	Calling this method is only valid on instances returned
3548	by <link to="ISession::machine"/> and on new machines
3549	created by <link to="IVirtualBox::createMachine"/> but not
3550	yet registered, or on unregistered machines after calling
3551	<link to="IVirtualBox::unregisterMachine"/>.
3552	</note>
3553	</desc>
3554	</method>
3555
3556	<method name="saveSettingsWithBackup">
3557	<desc>
3558	Creates a backup copy of the machine settings file (<link
3559	to="#settingsFilePath"/>) in case of auto-conversion, and then calls
3560	<link to="#saveSettings()"/>.
3561
3562	Note that the backup copy is created <b>only</b> if the settings file
3563	auto-conversion took place (see <link to="#settingsFileVersion"/> for
3564	details). Otherwise, this call is fully equivalent to
3565	<link to="#saveSettings()"/> and no backup copying is done.
3566
3567	The backup copy is created in the same directory where the original
3568	settings file is located. It is given the following file name:
3569	<pre>
3570	original.xml.x.y-platform.bak
3571	</pre>
3572	where <tt>original.xml</tt> is the original settings file name
3573	(excluding path), and <tt>x.y-platform</tt> is the version of the old
3574	format of the settings file (before auto-conversion).
3575
3576	If the given backup file already exists, this method will try to add the
3577	<tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
3578	0 to 9) and copy it again until it succeeds. If all suffixes are
3579	occupied, or if any other copy error occurs, this method will return a
3580	failure.
3581
3582	If the copy operation succeeds, the @a bakFileName return argument will
3583	receive a full path to the created backup file (for informational
3584	purposes). Note that this will happen even if the subsequent
3585	<link to="#saveSettings()"/> call performed by this method after the
3586	copy operation, fails.
3587
3588	<note>
3589	The VirtualBox API never calls this method. It is intended purely for
3590	the purposes of creating backup copies of the settings files by
3591	front-ends before saving the results of the automatically performed
3592	settings conversion to disk.
3593	</note>
3594
3595	<see>settingsFileVersion</see>
3596	</desc>
3597	<param name="bakFileName" type="wstring" dir="return">
3598	<desc>Full path to the created backup copy.</desc>
3599	</param>
3600	</method>
3601
3602	<method name="discardSettings">
3603	<desc>
3604	Discards any changes to the machine settings made since the session
3605	has been opened or since the last call to <link to="#saveSettings()"/>
3606	or <link to="#discardSettings"/>.
3607	<note>
3608	Calling this method is only valid on instances returned
3609	by <link to="ISession::machine"/> and on new machines
3610	created by <link to="IVirtualBox::createMachine"/> or
3611	opened by <link to="IVirtualBox::openMachine"/> but not
3612	yet registered, or on unregistered machines after calling
3613	<link to="IVirtualBox::unregisterMachine"/>.
3614	</note>
3615	</desc>
3616	</method>
3617
3618	<method name="deleteSettings">
3619	<desc>
3620	Deletes the settings file of this machine from disk.
3621	The machine must not be registered in order for this operation
3622	to succeed.
3623	<note>
3624	<link to="#settingsModified"/> will return TRUE after this
3625	method successfully returns.
3626	</note>
3627	<note>
3628	Calling this method is only valid on instances returned
3629	by <link to="ISession::machine"/> and on new machines
3630	created by <link to="IVirtualBox::createMachine"/> or
3631	opened by <link to="IVirtualBox::openMachine"/> but not
3632	yet registered, or on unregistered machines after calling
3633	<link to="IVirtualBox::unregisterMachine"/>.
3634	</note>
3635	<note>
3636	The deleted machine settings file can be restored (saved again)
3637	by calling <link to="#saveSettings()"/>.
3638	</note>
3639	</desc>
3640	</method>
3641
3642	<method name="getSnapshot">
3643	<desc>
3644	Returns a snapshot of this machine with the given UUID.
3645	A <tt>null</tt> UUID can be used to obtain the first snapshot
3646	taken on this machine. This is useful if you want to traverse
3647	the whole tree of snapshots starting from the root.
3648	</desc>
3649	<param name="id" type="uuid" dir="in">
3650	<desc>UUID of the snapshot to get</desc>
3651	</param>
3652	<param name="snapshot" type="ISnapshot" dir="return">
3653	<desc>Snapshot object with the given UUID.</desc>
3654	</param>
3655	</method>
3656
3657	<method name="findSnapshot">
3658	<desc>
3659	Returns a snapshot of this machine with the given name.
3660	</desc>
3661	<param name="name" type="wstring" dir="in">
3662	<desc>Name of the snapshot to find</desc>
3663	</param>
3664	<param name="snapshot" type="ISnapshot" dir="return">
3665	<desc>Snapshot object with the given name.</desc>
3666	</param>
3667	</method>
3668
3669	<method name="setCurrentSnapshot">
3670	<desc>
3671	Sets the current snapshot of this machine.
3672	<note>
3673	In the current implementation, this operation is not
3674	implemented.
3675	</note>
3676	</desc>
3677	<param name="id" type="uuid" dir="in">
3678	<desc>UUID of the snapshot to set as the current snapshot.</desc>
3679	</param>
3680	</method>
3681
3682	<method name="createSharedFolder">
3683	<desc>
3684	Creates a new permanent shared folder by associating the given logical
3685	name with the given host path, adds it to the collection of shared
3686	folders and starts sharing it. Refer to the description of
3687	<link to="ISharedFolder"/> to read more about logical names.
3688	</desc>
3689	<param name="name" type="wstring" dir="in">
3690	<desc>Unique logical name of the shared folder.</desc>
3691	</param>
3692	<param name="hostPath" type="wstring" dir="in">
3693	<desc>Full path to the shared folder in the host file system.</desc>
3694	</param>
3695	<param name="writable" type="boolean" dir="in">
3696	<desc>Whether the share is writable or readonly</desc>
3697	</param>
3698	</method>
3699
3700	<method name="removeSharedFolder">
3701	<desc>
3702	Removes the permanent shared folder with the given name previously
3703	created by <link to="#createSharedFolder"/> from the collection of
3704	shared folders and stops sharing it.
3705	</desc>
3706	<param name="name" type="wstring" dir="in">
3707	<desc>Logical name of the shared folder to remove.</desc>
3708	</param>
3709	</method>
3710
3711	<method name="canShowConsoleWindow">
3712	<desc>
3713	Returns @c true if the VM console process can activate the
3714	console window and bring it to foreground on the desktop of
3715	the host PC.
3716	<note>
3717	This method will fail if a session for this machine is not
3718	currently open.
3719	</note>
3720	</desc>
3721	<param name="canShow" type="boolean" dir="return">
3722	<desc>
3723	@c true if the console window can be shown and @c
3724	false otherwise.
3725	</desc>
3726	</param>
3727	</method>
3728
3729	<method name="showConsoleWindow">
3730	<desc>
3731	Activates the console window and brings it to foreground on
3732	the desktop of the host PC. Many modern window managers on
3733	many platforms implement some sort of focus stealing
3734	prevention logic, so that it may be impossible to activate
3735	a window without the help of the currently active
3736	application. In this case, this method will return a non-zero
3737	identifier that represents the top-level window of the VM
3738	console process. The caller, if it represents a currently
3739	active process, is responsible to use this identifier (in a
3740	platform-dependent manner) to perform actual window
3741	activation.
3742	<note>
3743	This method will fail if a session for this machine is not
3744	currently open.
3745	</note>
3746	</desc>
3747	<param name="winId" type="unsigned long long" dir="return">
3748	<desc>
3749	Platform-dependent identifier of the top-level VM console
3750	window, or zero if this method has performed all actions
3751	necessary to implement the <i>show window</i> semantics for
3752	the given platform and/or VirtualBox front-end.
3753	</desc>
3754	</param>
3755	</method>
3756
3757	<method name="getGuestProperty">
3758	<desc>
3759	Reads an entry from the machine's guest property store.
3760	</desc>
3761	<param name="name" type="wstring" dir="in">
3762	<desc>
3763	The name of the property to read.
3764	</desc>
3765	</param>
3766	<param name="value" type="wstring" dir="out">
3767	<desc>
3768	The value of the property. If the property does not exist then this
3769	will be empty.
3770	</desc>
3771	</param>
3772	<param name="timestamp" type="unsigned long long" dir="out">
3773	<desc>
3774	The time at which the property was last modified, as seen by the
3775	server process.
3776	</desc>
3777	</param>
3778	<param name="flags" type="wstring" dir="out">
3779	<desc>
3780	Additional property parameters, passed as a comma-separated list of
3781	"name=value" type entries.
3782	</desc>
3783	</param>
3784	</method>
3785
3786	<method name="getGuestPropertyValue">
3787	<desc>
3788	Reads a value from the machine's guest property store.
3789	</desc>
3790	<param name="property" type="wstring" dir="in">
3791	<desc>
3792	The name of the property to read.
3793	</desc>
3794	</param>
3795	<param name="value" type="wstring" dir="return">
3796	<desc>
3797	The value of the property. If the property does not exist then this
3798	will be empty.
3799	</desc>
3800	</param>
3801	</method>
3802
3803	<method name="getGuestPropertyTimestamp">
3804	<desc>
3805	Reads a property timestamp from the machine's guest property store.
3806	</desc>
3807	<param name="property" type="wstring" dir="in">
3808	<desc>
3809	The name of the property to read.
3810	</desc>
3811	</param>
3812	<param name="value" type="unsigned long long" dir="return">
3813	<desc>
3814	The timestamp. If the property does not exist then this will be
3815	empty.
3816	</desc>
3817	</param>
3818	</method>
3819
3820	<method name="setGuestProperty">
3821	<desc>
3822	Sets, changes or deletes an entry in the machine's guest property
3823	store.
3824	</desc>
3825	<param name="property" type="wstring" dir="in">
3826	<desc>
3827	The name of the property to set, change or delete.
3828	</desc>
3829	</param>
3830	<param name="value" type="wstring" dir="in">
3831	<desc>
3832	The new value of the property to set, change or delete. If the
3833	property does not yet exist and value is non-empty, it will be
3834	created. If the value is empty, the key will be deleted if it
3835	exists.
3836	</desc>
3837	</param>
3838	<param name="flags" type="wstring" dir="in">
3839	<desc>
3840	Additional property parameters, passed as a comma-separated list of
3841	"name=value" type entries.
3842	</desc>
3843	</param>
3844	</method>
3845
3846	<method name="setGuestPropertyValue">
3847	<desc>
3848	Sets, changes or deletes a value in the machine's guest property
3849	store. The flags field will be left unchanged or created empty for a
3850	new property.
3851	</desc>
3852	<param name="property" type="wstring" dir="in">
3853	<desc>
3854	The name of the property to set, change or delete.
3855	</desc>
3856	</param>
3857	<param name="value" type="wstring" dir="in">
3858	<desc>
3859	The new value of the property to set, change or delete. If the
3860	property does not yet exist and value is non-empty, it will be
3861	created. If value is empty, the property will be deleted if it
3862	exists.
3863	</desc>
3864	</param>
3865	</method>
3866
3867	<method name="enumerateGuestProperties">
3868	<desc>
3869	Return a list of the guest properties matching a set of patterns along
3870	with their values, time stamps and flags.
3871	</desc>
3872	<param name="patterns" type="wstring" dir="in">
3873	<desc>
3874	The patterns to match the properties against, separated by '\|'
3875	characters. If this is empty or NULL, all properties will match.
3876	</desc>
3877	</param>
3878	<param name="name" type="wstring" dir="out" safearray="yes">
3879	<desc>
3880	The names of the properties returned.
3881	</desc>
3882	</param>
3883	<param name="value" type="wstring" dir="out" safearray="yes">
3884	<desc>
3885	The values of the properties returned. The array entries match the
3886	corresponding entries in the @a name array.
3887	</desc>
3888	</param>
3889	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3890	<desc>
3891	The time stamps of the properties returned. The array entries match
3892	the corresponding entries in the @a name array.
3893	</desc>
3894	</param>
3895	<param name="flags" type="wstring" dir="out" safearray="yes">
3896	<desc>
3897	The flags of the properties returned. The array entries match the
3898	corresponding entries in the @a name array.
3899	</desc>
3900	</param>
3901	</method>
3902	</interface>
3903
3904	<!--
3905	// IConsole
3906	/////////////////////////////////////////////////////////////////////////
3907	-->
3908
3909	<interface
3910	name="IConsoleCallback" extends="$unknown"
3911	uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
3912	wsmap="suppress"
3913	>
3914
3915	<method name="onMousePointerShapeChange">
3916	<desc>
3917	Notification when the guest mouse pointer shape has
3918	changed. The new shape data is given.
3919	</desc>
3920	<param name="visible" type="boolean" dir="in">
3921	<desc>
3922	Flag whether the pointer is visible.
3923	</desc>
3924	</param>
3925	<param name="alpha" type="boolean" dir="in">
3926	<desc>
3927	Flag whether the pointer has an alpha channel.
3928	</desc>
3929	</param>
3930	<param name="xHot" type="unsigned long" dir="in">
3931	<desc>
3932	The pointer hot spot x coordinate.
3933	</desc>
3934	</param>
3935	<param name="yHot" type="unsigned long" dir="in">
3936	<desc>
3937	The pointer hot spot y coordinate.
3938	</desc>
3939	</param>
3940	<param name="width" type="unsigned long" dir="in">
3941	<desc>
3942	Width of the pointer shape in pixels.
3943	</desc>
3944	</param>
3945	<param name="height" type="unsigned long" dir="in">
3946	<desc>
3947	Height of the pointer shape in pixels.
3948	</desc>
3949	</param>
3950	<param name="shape" type="octet" mod="ptr" dir="in">
3951	<desc>
3952	Address of the shape buffer.
3953
3954	The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
3955
3956	For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
3957	For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
3958
3959	AND mask presents for pointers with alpha channel, so if the callback does not
3960	support alpha, the pointer could be displayed as a normal color pointer.
3961
3962	The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
3963	therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
3964	end of any scanline are undefined.
3965
3966	The XOR mask follows the AND mask on the next 4 bytes aligned offset:
3967	<tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>
3968	Bytes in the gap between the AND and the XOR mask are undefined.
3969	XOR mask scanlines have no gap between them and size of XOR mask is:
3970	<tt>cXor = width * 4 * height</tt>.
3971
3972	<note>
3973	If 'shape' is equal to 0, only pointer visibility is being changed.
3974	</note>
3975	</desc>
3976	</param>
3977	</method>
3978
3979	<method name="onMouseCapabilityChange">
3980	<desc>
3981	Notification when the mouse capabilities reported by the
3982	guest have changed. The new capabilities are passed.
3983	</desc>
3984	<param name="supportsAbsolute" type="boolean" dir="in"/>
3985	<param name="needsHostCursor" type="boolean" dir="in"/>
3986	</method>
3987
3988	<method name="onKeyboardLedsChange">
3989	<desc>
3990	Notification when the guest OS executes the KBD_CMD_SET_LEDS command
3991	to alter the state of the keyboard LEDs.
3992	</desc>
3993	<param name="numLock" type="boolean" dir="in"/>
3994	<param name="capsLock" type="boolean" dir="in"/>
3995	<param name="scrollLock" type="boolean" dir="in"/>
3996	</method>
3997
3998	<method name="onStateChange">
3999	<desc>
4000	Notification when the execution state of the machine has changed.
4001	The new state will be given.
4002	</desc>
4003	<param name="state" type="MachineState" dir="in"/>
4004	</method>
4005
4006	<method name="onAdditionsStateChange">
4007	<desc>
4008	Notification when a Guest Additions property changes.
4009	Interested callees should query IGuest attributes to
4010	find out what has changed.
4011	</desc>
4012	</method>
4013
4014	<method name="onDVDDriveChange">
4015	<desc>
4016	Notification when a property of the
4017	virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
4018	Interested callees should use IDVDDrive methods to find out what has
4019	changed.
4020	</desc>
4021	</method>
4022
4023	<method name="onFloppyDriveChange">
4024	<desc>
4025	Notification when a property of the
4026	virtual <link to="IMachine::floppyDrive">floppy drive</link> changes.
4027	Interested callees should use IFloppyDrive methods to find out what
4028	has changed.
4029	</desc>
4030	</method>
4031
4032	<method name="onNetworkAdapterChange">
4033	<desc>
4034	Notification when a property of one of the
4035	virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
4036	changes. Interested callees should use INetworkAdapter methods and
4037	attributes to find out what has changed.
4038	</desc>
4039	<param name="networkAdapter" type="INetworkAdapter" dir="in">
4040	<desc>Network adapter that is subject to change.</desc>
4041	</param>
4042	</method>
4043
4044	<method name="onSerialPortChange">
4045	<desc>
4046	Notification when a property of one of the
4047	virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
4048	Interested callees should use ISerialPort methods and attributes
4049	to find out what has changed.
4050	</desc>
4051	<param name="serialPort" type="ISerialPort" dir="in">
4052	<desc>Serial port that is subject to change.</desc>
4053	</param>
4054	</method>
4055
4056	<method name="onParallelPortChange">
4057	<desc>
4058	Notification when a property of one of the
4059	virtual <link to="IMachine::getParallelPort">parallel ports</link>
4060	changes. Interested callees should use ISerialPort methods and
4061	attributes to find out what has changed.
4062	</desc>
4063	<param name="parallelPort" type="IParallelPort" dir="in">
4064	<desc>Parallel port that is subject to change.</desc>
4065	</param>
4066	</method>
4067
4068	<method name="onVRDPServerChange">
4069	<desc>
4070	Notification when a property of the
4071	<link to="IMachine::VRDPServer">VRDP server</link> changes.
4072	Interested callees should use IVRDPServer methods and attributes to
4073	find out what has changed.
4074	</desc>
4075	</method>
4076
4077	<method name="onUSBControllerChange">
4078	<desc>
4079	Notification when a property of the virtual
4080	<link to="IMachine::USBController">USB controller</link> changes.
4081	Interested callees should use IUSBController methods and attributes to
4082	find out what has changed.
4083	</desc>
4084	</method>
4085
4086	<method name="onUSBDeviceStateChange">
4087	<desc>
4088	Notification when a USB device is attached to or detached from
4089	the virtual USB controller.
4090
4091	This notification is sent as a result of the indirect
4092	request to attach the device because it matches one of the
4093	machine USB filters, or as a result of the direct request
4094	issued by <link to="IConsole::attachUSBDevice"/> or
4095	<link to="IConsole::detachUSBDevice"/>.
4096
4097	This notification is sent in case of both a succeeded and a
4098	failed request completion. When the request succeeds, the @a
4099	error parameter is @c null, and the given device has been
4100	already added to (when @a attached is @c true) or removed from
4101	(when @a attached is @c false) the collection represented by
4102	<link to="IConsole::USBDevices"/>. On failure, the collection
4103	doesn't change and the @a error parameter represents the error
4104	message describing the failure.
4105
4106	</desc>
4107	<param name="device" type="IUSBDevice" dir="in">
4108	<desc>Device that is subject to state change.</desc>
4109	</param>
4110	<param name="attached" type="boolean" dir="in">
4111	<desc>
4112	<tt>true</tt> if the device was attached
4113	and <tt>false</tt> otherwise.
4114	</desc>
4115	</param>
4116	<param name="error" type="IVirtualBoxErrorInfo" dir="in">
4117	<desc>
4118	<tt>null</tt> on success or an error message object on
4119	failure.
4120	</desc>
4121	</param>
4122	</method>
4123
4124	<method name="onSharedFolderChange">
4125	<desc>
4126	Notification when a shared folder is added or removed.
4127	The @a scope argument defines one of three scopes:
4128	<link to="IVirtualBox::sharedFolders">global shared folders</link>
4129	(<link to="Scope::Global">Global</link>),
4130	<link to="IMachine::sharedFolders">permanent shared folders</link> of
4131	the machine (<link to="Scope::Machine">Machine</link>) or <link
4132	to="IConsole::sharedFolders">transient shared folders</link> of the
4133	machine (<link to="Scope::Session">Session</link>). Interested callees
4134	should use query the corresponding collections to find out what has
4135	changed.
4136	</desc>
4137	<param name="scope" type="Scope" dir="in">
4138	<desc>Scope of the notification.</desc>
4139	</param>
4140	</method>
4141
4142	<method name="onRuntimeError">
4143	<desc>
4144	Notification when an error happens during the virtual
4145	machine execution.
4146
4147	There are three kinds of runtime errors:
4148	<ul>
4149	<li><i>fatal</i></li>
4150	<li><i>non-fatal with retry</i></li>
4151	<li><i>non-fatal warnings</i></li>
4152	</ul>
4153
4154	<b>Fatal</b> errors are indicated by the @a fatal parameter set
4155	to <tt>true</tt>. In case of fatal errors, the virtual machine
4156	execution is always paused before calling this notification, and
4157	the notification handler is supposed either to immediately save
4158	the virtual machine state using <link to="IConsole::saveState()"/>
4159	or power it off using <link to="IConsole::powerDown()"/>.
4160	Resuming the execution can lead to unpredictable results.
4161
4162	<b>Non-fatal</b> errors and warnings are indicated by the
4163	@a fatal parameter set to <tt>false</tt>. If the virtual machine
4164	is in the Paused state by the time the error notification is
4165	received, it means that the user can <i>try to resume</i> the machine
4166	execution after attempting to solve the problem that caused the
4167	error. In this case, the notification handler is supposed
4168	to show an appropriate message to the user (depending on the
4169	value of the @a id parameter) that offers several actions such
4170	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
4171	wants to retry, the notification handler should continue
4172	the machine execution using the <link to="IConsole::resume()"/>
4173	call. If the machine execution is not Paused during this
4174	notification, then it means this notification is a <i>warning</i>
4175	(for example, about a fatal condition that can happen very soon);
4176	no immediate action is required from the user, the machine
4177	continues its normal execution.
4178
4179	Note that in either case the notification handler
4180	<b>must not</b> perform any action directly on a thread
4181	where this notification is called. Everything it is allowed to
4182	do is to post a message to another thread that will then talk
4183	to the user and take the corresponding action.
4184
4185	Currently, the following error identifiers are known:
4186	<ul>
4187	<li><tt>"HostMemoryLow"</tt></li>
4188	<li><tt>"HostAudioNotResponding"</tt></li>
4189	<li><tt>"VDIStorageFull"</tt></li>
4190	</ul>
4191
4192	<note>
4193	This notification is not designed to be implemented by
4194	more than one callback at a time. If you have multiple
4195	IConsoleCallback instances registered on the given
4196	IConsole object, make sure you simply do nothing but
4197	return @c S_OK from all but one of them that does actual
4198	user notification and performs necessary actions.
4199	</note>
4200
4201	</desc>
4202	<param name="fatal" type="boolean" dir="in">
4203	<desc>Whether the error is fatal or not</desc>
4204	</param>
4205	<param name="id" type="wstring" dir="in">
4206	<desc>Error identifier</desc>
4207	</param>
4208	<param name="message" type="wstring" dir="in">
4209	<desc>Optional error message</desc>
4210	</param>
4211	</method>
4212
4213	<method name="onCanShowWindow">
4214	<desc>
4215	Notification when a call to
4216	<link to="IMachine::canShowConsoleWindow()"/> is made by a
4217	front-end to check if a subsequent call to
4218	<link to="IMachine::showConsoleWindow()"/> can succeed.
4219
4220	The callee should give an answer appropriate to the current
4221	machine state in the @a canShow argument. This answer must
4222	remain valid at least until the next
4223	<link to="IConsole::state">machine state</link> change.
4224
4225	<note>
4226	This notification is not designed to be implemented by
4227	more than one callback at a time. If you have multiple
4228	IConsoleCallback instances registered on the given
4229	IConsole object, make sure you simply do nothing but
4230	return @c true and @c S_OK from all but one of them that
4231	actually manages console window activation.
4232	</note>
4233	</desc>
4234	<param name="canShow" type="boolean" dir="return">
4235	<desc>
4236	@c true if the console window can be shown and @c
4237	false otherwise.
4238	</desc>
4239	</param>
4240	</method>
4241
4242	<method name="onShowWindow">
4243	<desc>
4244	Notification when a call to
4245	<link to="IMachine::showConsoleWindow()"/>
4246	requests the console window to be activated and brought to
4247	foreground on the desktop of the host PC.
4248
4249	This notification should cause the VM console process to
4250	perform the requested action as described above. If it is
4251	impossible to do it at a time of this notification, this
4252	method should return a failure.
4253
4254	Note that many modern window managers on many platforms
4255	implement some sort of focus stealing prevention logic, so
4256	that it may be impossible to activate a window without the
4257	help of the currently active application (which is supposedly
4258	an initiator of this notification). In this case, this method
4259	must return a non-zero identifier that represents the
4260	top-level window of the VM console process. The caller, if it
4261	represents a currently active process, is responsible to use
4262	this identifier (in a platform-dependent manner) to perform
4263	actual window activation.
4264
4265	This method must set @a winId to zero if it has performed all
4266	actions necessary to complete the request and the console
4267	window is now active and in foreground, to indicate that no
4268	further action is required on the caller's side.
4269
4270	<note>
4271	This notification is not designed to be implemented by
4272	more than one callback at a time. If you have multiple
4273	IConsoleCallback instances registered on the given
4274	IConsole object, make sure you simply do nothing but
4275	return @c S_OK from all but one of them that actually
4276	manages console window activation.
4277	</note>
4278	</desc>
4279	<param name="winId" type="unsigned long long" dir="return">
4280	<desc>
4281	Platform-dependent identifier of the top-level VM console
4282	window, or zero if this method has performed all actions
4283	necessary to implement the <i>show window</i> semantics for
4284	the given platform and/or this VirtualBox front-end.
4285	</desc>
4286	</param>
4287	</method>
4288
4289	</interface>
4290
4291	<interface
4292	name="IRemoteDisplayInfo" extends="$unknown"
4293	uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
4294	wsmap="struct"
4295	>
4296	<desc>
4297	Contains information about the remote display (VRDP) capabilities and status.
4298	This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
4299	</desc>
4300
4301	<attribute name="active" type="boolean" readonly="yes">
4302	<desc>
4303	Whether the remote display connection is active.
4304	</desc>
4305	</attribute>
4306
4307	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
4308	<desc>
4309	How many times a client connected.
4310	</desc>
4311	</attribute>
4312
4313	<attribute name="beginTime" type="long long" readonly="yes">
4314	<desc>
4315	When the last connection was established, in milliseconds since 1970-01-01 UTC.
4316	</desc>
4317	</attribute>
4318
4319	<attribute name="endTime" type="long long" readonly="yes">
4320	<desc>
4321	When the last connection was terminated or the current time, if
4322	connection is still active, in milliseconds since 1970-01-01 UTC.
4323	</desc>
4324	</attribute>
4325
4326	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
4327	<desc>
4328	How many bytes were sent in last or current, if still active, connection.
4329	</desc>
4330	</attribute>
4331
4332	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
4333	<desc>
4334	How many bytes were sent in all connections.
4335	</desc>
4336	</attribute>
4337
4338	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
4339	<desc>
4340	How many bytes were received in last or current, if still active, connection.
4341	</desc>
4342	</attribute>
4343
4344	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
4345	<desc>
4346	How many bytes were received in all connections.
4347	</desc>
4348	</attribute>
4349
4350	<attribute name="user" type="wstring" readonly="yes">
4351	<desc>
4352	Login user name supplied by the client.
4353	</desc>
4354	</attribute>
4355
4356	<attribute name="domain" type="wstring" readonly="yes">
4357	<desc>
4358	Login domain name supplied by the client.
4359	</desc>
4360	</attribute>
4361
4362	<attribute name="clientName" type="wstring" readonly="yes">
4363	<desc>
4364	The client name supplied by the client.
4365	</desc>
4366	</attribute>
4367
4368	<attribute name="clientIP" type="wstring" readonly="yes">
4369	<desc>
4370	The IP address of the client.
4371	</desc>
4372	</attribute>
4373
4374	<attribute name="clientVersion" type="unsigned long" readonly="yes">
4375	<desc>
4376	The client software version number.
4377	</desc>
4378	</attribute>
4379
4380	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
4381	<desc>
4382	Public key exchange method used when connection was established.
4383	Values: 0 - RDP4 public key exchange scheme.
4384	1 - X509 certificates were sent to client.
4385	</desc>
4386	</attribute>
4387
4388	</interface>
4389
4390	<interface
4391	name="IConsole" extends="$unknown"
4392	uuid="e3c6d4a1-a935-47ca-b16d-f9e9c496e53e"
4393	wsmap="managed"
4394	>
4395	<desc>
4396	The IConsole interface represents an interface to control virtual
4397	machine execution.
4398
4399	The console object that implements the IConsole interface is obtained
4400	from a session object after the session for the given machine has been
4401	opened using one of <link to="IVirtualBox::openSession"/>,
4402	<link to="IVirtualBox::openRemoteSession"/> or
4403	<link to="IVirtualBox::openExistingSession"/> methods.
4404
4405	Methods of the IConsole interface allow the caller to query the current
4406	virtual machine execution state, pause the machine or power it down, save
4407	the machine state or take a snapshot, attach and detach removable media
4408	and so on.
4409
4410	<see>ISession</see>
4411	</desc>
4412
4413	<attribute name="machine" type="IMachine" readonly="yes">
4414	<desc>
4415	Machine object this console is sessioned with.
4416	<note>
4417	This is a convenience property, it has the same value as
4418	<link to="ISession::machine"/> of the corresponding session
4419	object.
4420	</note>
4421	</desc>
4422	</attribute>
4423
4424	<attribute name="state" type="MachineState" readonly="yes">
4425	<desc>
4426	Current execution state of the machine.
4427	<note>
4428	This property always returns the same value as the corresponding
4429	property of the IMachine object this console is sessioned with.
4430	For the process that owns (executes) the VM, this is the
4431	preferable way of querying the VM state, because no IPC
4432	calls are made.
4433	</note>
4434	</desc>
4435	</attribute>
4436
4437	<attribute name="guest" type="IGuest" readonly="yes">
4438	<desc>Guest object.</desc>
4439	</attribute>
4440
4441	<attribute name="keyboard" type="IKeyboard" readonly="yes">
4442	<desc>
4443	Virtual keyboard object.
4444	<note>
4445	If the machine is not running, any attempt to use
4446	the returned object will result in an error.
4447	</note>
4448	</desc>
4449	</attribute>
4450
4451	<attribute name="mouse" type="IMouse" readonly="yes">
4452	<desc>
4453	Virtual mouse object.
4454	<note>
4455	If the machine is not running, any attempt to use
4456	the returned object will result in an error.
4457	</note>
4458	</desc>
4459	</attribute>
4460
4461	<attribute name="display" type="IDisplay" readonly="yes">
4462	<desc>Virtual display object.
4463	<note>
4464	If the machine is not running, any attempt to use
4465	the returned object will result in an error.
4466	</note>
4467	</desc>
4468	</attribute>
4469
4470	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
4471	<desc>Debugging interface.</desc>
4472	</attribute>
4473
4474	<attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
4475	<desc>
4476	Collection of USB devices currently attached to the virtual
4477	USB controller.
4478	<note>
4479	The collection is empty if the machine is not running.
4480	</note>
4481	</desc>
4482	</attribute>
4483
4484	<attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
4485	<desc>
4486	List of USB devices currently attached to the remote VRDP client.
4487	Once a new device is physically attached to the remote host computer,
4488	it appears in this list and remains there until detached.
4489	</desc>
4490	</attribute>
4491
4492	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
4493	<desc>
4494	Collection of shared folders for the current session. These folders
4495	are called transient shared folders because they are available to the
4496	guest OS running inside the associated virtual machine only for the
4497	duration of the session (as opposed to
4498	<link to="IMachine::sharedFolders"/> which represent permanent shared
4499	folders). When the session is closed (e.g. the machine is powered down),
4500	these folders are automatically discarded.
4501
4502	New shared folders are added to the collection using
4503	<link to="#createSharedFolder"/>. Existing shared folders can be
4504	removed using <link to="#removeSharedFolder"/>.
4505	</desc>
4506	</attribute>
4507
4508	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
4509	<desc>
4510	Interface that provides information on Remote Display (VRDP) connection.
4511	</desc>
4512	</attribute>
4513
4514	<method name="powerUp">
4515	<desc>
4516	Starts the virtual machine execution using the current machine
4517	state (i.e. its current execution state, current settings and
4518	current hard disks).
4519
4520	If the machine is powered off or aborted, the execution will
4521	start from the beginning (as if the real hardware were just
4522	powered on).
4523
4524	If the machine is in the <link to="MachineState::Saved"/> state,
4525	it will continue its execution the point where the state has
4526	been saved.
4527
4528	<note>
4529	Unless you are trying to write a new VirtualBox front-end that
4530	performs direct machine execution (like the VirtualBox or VBoxSDL
4531	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
4532	session opened by <link to="IVirtualBox::openSession"/> and use this
4533	session only to change virtual machine settings. If you simply want to
4534	start virtual machine execution using one of the existing front-ends
4535	(for example the VirtualBox GUI or headless server), simply use
4536	<link to="IVirtualBox::openRemoteSession"/>; these front-ends will
4537	power up the machine automatically for you.
4538	</note>
4539
4540	<see>#saveState</see>
4541	</desc>
4542	<param name="progress" type="IProgress" dir="return">
4543	<desc>Progress object to track the operation completion.</desc>
4544	</param>
4545	</method>
4546
4547	<method name="powerUpPaused">
4548	<desc>
4549	Identical to powerUp except that the VM will enter the
4550	<link to="MachineState::Paused"/> state, instead of
4551	<link to="MachineState::Running"/>.
4552
4553	<see>#powerUp</see>
4554	</desc>
4555	<param name="progress" type="IProgress" dir="return">
4556	<desc>Progress object to track the operation completion.</desc>
4557	</param>
4558	</method>
4559
4560	<method name="powerDown">
4561	<desc>
4562	Stops the virtual machine execution.
4563	After this operation completes, the machine will go to the
4564	PoweredOff state.
4565
4566	@deprecated This method will be removed in VirtualBox 2.1 where the
4567	powerDownAsync() method will take its name. Do not use this method in
4568	the code.
4569	</desc>
4570	</method>
4571
4572	<method name="powerDownAsync">
4573	<desc>
4574	Initiates the power down procedure to stop the virtual machine
4575	execution.
4576
4577	The completion of the power down procedure is tracked using the returned
4578	IProgress object. After the operation is complete, the machine will go
4579	to the PoweredOff state.
4580
4581	@warning This method will be renamed to "powerDown" in VirtualBox 2.1
4582	where the original powerDown() method will be removed. You will need to
4583	rename "powerDownAsync" to "powerDown" in your sources to make them
4584	build with version 2.1.
4585	</desc>
4586	<param name="progress" type="IProgress" dir="return">
4587	<desc>Progress object to track the operation completion.</desc>
4588	</param>
4589	</method>
4590
4591	<method name="reset">
4592	<desc>Resets the virtual machine.</desc>
4593	</method>
4594
4595	<method name="pause">
4596	<desc>Pauses the virtual machine execution.</desc>
4597	</method>
4598
4599	<method name="resume">
4600	<desc>Resumes the virtual machine execution.</desc>
4601	</method>
4602
4603	<method name="powerButton">
4604	<desc>Send the ACPI power button event to the guest.</desc>
4605	</method>
4606
4607	<method name="sleepButton">
4608	<desc>Send the ACPI sleep button event to the guest.</desc>
4609	</method>
4610
4611	<method name="getPowerButtonHandled">
4612	<desc>Check if the last power button event was handled by guest.</desc>
4613	<param name="handled" type="boolean" dir="return"/>
4614	</method>
4615
4616	<method name="getGuestEnteredACPIMode">
4617	<desc>Check if the guest entered the ACPI mode G0 (working) or
4618	G1 (sleeping). If this method returns false, the guest will
4619	most likely not respond to external ACPI events.</desc>
4620	<param name="entered" type="boolean" dir="return"/>
4621	</method>
4622
4623	<method name="saveState">
4624	<desc>
4625	Saves the current execution state of a running virtual machine
4626	and stops its execution.
4627
4628	After this operation completes, the machine will go to the
4629	Saved state. Next time it is powered up, this state will
4630	be restored and the machine will continue its execution from
4631	the place where it was saved.
4632
4633	This operation differs from taking a snapshot to the effect
4634	that it doesn't create new differencing hard disks. Also, once
4635	the machine is powered up from the state saved using this method,
4636	the saved state is deleted, so it will be impossible to return
4637	to this state later.
4638
4639	<note>
4640	On success, this method implicitly calls
4641	<link to="IMachine::saveSettings()"/> to save all current machine
4642	settings (including runtime changes to the DVD drive, etc.).
4643	Together with the impossibility to change any VM settings when it is
4644	in the Saved state, this guarantees the adequate hardware
4645	configuration of the machine when it is restored from the saved
4646	state file.
4647	</note>
4648
4649	<note>
4650	The machine must be in the Running or Paused state, otherwise
4651	the operation will fail.
4652	</note>
4653
4654	<see><link to="#takeSnapshot"/></see>
4655	</desc>
4656	<param name="progress" type="IProgress" dir="return">
4657	<desc>Progress object to track the operation completion.</desc>
4658	</param>
4659	</method>
4660
4661	<method name="adoptSavedState">
4662	<desc>
4663	Associates the given saved state file to the virtual machine.
4664
4665	On success, the machine will go to the Saved state. Next time it is
4666	powered up, it will be restored from the adopted saved state and
4667	continue execution from the place where the saved state file was
4668	created.
4669
4670	The specified saved state file path may be full or relative to the
4671	folder the VM normally saves the state to (usually,
4672	<link to="IMachine::snapshotFolder"/>).
4673
4674	<note>
4675	It's a caller's responsibility to make sure the given saved state
4676	file is compatible with the settings of this virtual machine that
4677	represent its virtual hardware (memory size, hard disk configuration
4678	etc.). If there is a mismatch, the behavior of the virtual machine
4679	is undefined.
4680	</note>
4681	</desc>
4682	<param name="savedStateFile" type="wstring" dir="in">
4683	<desc>Path to the saved state file to adopt.</desc>
4684	</param>
4685	</method>
4686
4687	<method name="discardSavedState">
4688	<desc>
4689	Discards (deletes) the saved state of the virtual machine
4690	previously created by <link to="#saveState"/>. Next time the
4691	machine is powered up, a clean boot will occur.
4692	<note>
4693	This operation is equivalent to resetting or powering off
4694	the machine without doing a proper shutdown in the guest OS.
4695	</note>
4696	</desc>
4697	</method>
4698
4699	<method name="getDeviceActivity">
4700	<desc>
4701	Gets the current activity type of a given device or device group.
4702	</desc>
4703	<param name="type" type="DeviceType" dir="in"/>
4704	<param name="activity" type="DeviceActivity" dir="return"/>
4705	</method>
4706
4707	<method name="attachUSBDevice">
4708	<desc>
4709	Attaches a host USB device with the given UUID to the
4710	USB controller of the virtual machine.
4711
4712	The device needs to be in one of the following states:
4713	<link to="USBDeviceState::Busy">Busy</link>,
4714	<link to="USBDeviceState::Available">Available</link> or
4715	<link to="USBDeviceState::Held">Held</link>,
4716	otherwise an error is immediately returned.
4717
4718	When the device state is
4719	<link to="USBDeviceState::Busy">Busy</link>, an error may also
4720	be returned if the host computer refuses to release it for some reason.
4721
4722	<see>IUSBController::deviceFilters, USBDeviceState</see>
4723	</desc>
4724	<param name="id" type="uuid" dir="in">
4725	<desc>UUID of the host USB device to attach.</desc>
4726	</param>
4727	</method>
4728
4729	<method name="detachUSBDevice">
4730	<desc>
4731	Detaches an USB device with the given UUID from the USB controller
4732	of the virtual machine.
4733
4734	After this method succeeds, the VirtualBox server re-initiates
4735	all USB filters as if the device were just physically attached
4736	to the host, but filters of this machine are ignored to avoid
4737	a possible automatic re-attachment.
4738
4739	<see>IUSBController::deviceFilters, USBDeviceState</see>
4740	</desc>
4741	<param name="id" type="uuid" dir="in">
4742	<desc>UUID of the USB device to detach.</desc>
4743	</param>
4744	<param name="device" type="IUSBDevice" dir="return">
4745	<desc>Detached USB device.</desc>
4746	</param>
4747	</method>
4748
4749	<method name="createSharedFolder">
4750	<desc>
4751	Creates a transient new shared folder by associating the given logical
4752	name with the given host path, adds it to the collection of shared
4753	folders and starts sharing it. Refer to the description of
4754	<link to="ISharedFolder"/> to read more about logical names.
4755	</desc>
4756	<param name="name" type="wstring" dir="in">
4757	<desc>Unique logical name of the shared folder.</desc>
4758	</param>
4759	<param name="hostPath" type="wstring" dir="in">
4760	<desc>Full path to the shared folder in the host file system.</desc>
4761	</param>
4762	<param name="writable" type="boolean" dir="in">
4763	<desc>Whether the share is writable or readonly</desc>
4764	</param>
4765	</method>
4766
4767	<method name="removeSharedFolder">
4768	<desc>
4769	Removes a transient shared folder with the given name previously
4770	created by <link to="#createSharedFolder"/> from the collection of
4771	shared folders and stops sharing it.
4772	</desc>
4773	<param name="name" type="wstring" dir="in">
4774	<desc>Logical name of the shared folder to remove.</desc>
4775	</param>
4776	</method>
4777
4778	<method name="takeSnapshot">
4779	<desc>
4780	Saves the current execution state and all settings of the
4781	machine and creates differencing images for all
4782	normal (non-independent) hard disks.
4783
4784	This method can be called for a PoweredOff, Saved, Running or
4785	Paused virtual machine. When the machine is PoweredOff, an
4786	offline <link to="ISnapshot">snapshot</link> is created,
4787	in all other cases -- an online snapshot.
4788
4789	The taken snapshot is always based on the
4790	<link to="IMachine::currentSnapshot">current
4791	snapshot</link> of the associated virtual machine and becomes
4792	a new current snapshot.
4793
4794	<note>
4795	This method implicitly calls <link to="IMachine::saveSettings()"/> to
4796	save all current machine settings before taking an offline snapshot.
4797	</note>
4798
4799	<see>ISnapshot, <link to="#saveState"/></see>
4800	</desc>
4801	<param name="name" type="wstring" dir="in">
4802	<desc>Short name for the snapshot.</desc>
4803	</param>
4804	<param name="description" type="wstring" dir="in">
4805	<desc>Optional description of the snapshot.</desc>
4806	</param>
4807	<param name="progress" type="IProgress" dir="return">
4808	<desc>Progress object to track the operation completion.</desc>
4809	</param>
4810	</method>
4811
4812	<method name="discardSnapshot">
4813	<desc>
4814
4815	Starts discarding the specified snapshot. The execution state
4816	and settings of the associated machine stored in the snapshot
4817	will be deleted. The contents of all differencing hard disks of
4818	this snapshot will be merged with the contents of their
4819	dependent child hard disks to keep the, disks valid (in other
4820	words, all changes represented by hard disks being discarded
4821	will be propagated to their child hard disks). After that, this
4822	snapshot's differencing hard disks will be deleted. The parent
4823	of this snapshot will become a new parent for all its child
4824	snapshots.
4825
4826	If the discarded snapshot is the current one, its parent
4827	snapshot will become a new current snapshot. The current machine
4828	state is not directly affected in this case, except that
4829	currently attached differencing hard disks based on hard disks
4830	of the discarded snapshot will be also merged as described
4831	above.
4832
4833	If the discarded snapshot is the first one (the root snapshot)
4834	and it has exactly one child snapshot, this child snapshot will
4835	become the first snapshot after discarding. If there are no
4836	children at all (i.e. the first snapshot is the only snapshot of
4837	the machine), both the current and the first snapshot of the
4838	machine will be set to null. In all other cases, the first
4839	snapshot cannot be discarded.
4840
4841	You cannot discard the snapshot if it
4842	stores <link to="HardDiskType::Normal">normal</link> (non-differencing)
4843	hard disks that have differencing hard disks based on them. Snapshots of
4844	such kind can be discarded only when every normal hard disk has either
4845	no children at all or exactly one child. In the former case, the normal
4846	hard disk simply becomes unused (i.e. not attached to any VM). In the
4847	latter case, it receives all the changes stored in the child hard disk,
4848	and then it replaces the child hard disk in the configuration of the
4849	corresponding snapshot or machine.
4850
4851	Also, you cannot discard the snapshot if it stores hard disks
4852	(of any type) having differencing child hard disks that belong
4853	to other machines. Such snapshots can be only discarded after
4854	you discard all snapshots of other machines containing "foreign"
4855	child disks, or detach these "foreign" child disks from machines
4856	they are attached to.
4857
4858	One particular example of the snapshot storing normal hard disks
4859	is the first snapshot of a virtual machine that had normal hard
4860	disks attached when taking the snapshot. Be careful when
4861	discarding such snapshots because this implicitly commits
4862	changes (made since the snapshot being discarded has been taken)
4863	to normal hard disks (as described above), which may be not what
4864	you want.
4865
4866	The virtual machine is put to
4867	the <link to="MachineState::Discarding">Discarding</link> state until
4868	the discard operation is completed.
4869
4870	<note>
4871	The machine must not be running, otherwise the operation
4872	will fail.
4873	</note>
4874
4875	<note>
4876	Child hard disks of all normal hard disks of the discarded snapshot
4877	must be accessible (see <link to="IMedium::state"/>) for this
4878	operation to succeed. In particular, this means that all virtual
4879	machines, whose hard disks are directly or indirectly based on the
4880	hard disks of discarded snapshot, must be powered off.
4881	</note>
4882	<note>
4883	Merging hard disk contents can be very time and disk space
4884	consuming, if these disks are big in size and have many
4885	children. However, if the snapshot being discarded is the last
4886	(head) snapshot on the branch, the operation will be rather
4887	quick.
4888	</note>
4889	<note>
4890	Note that discarding the current snapshot
4891	will implicitly call <link to="IMachine::saveSettings()"/> to
4892	make all current machine settings permanent.
4893	</note>
4894	</desc>
4895	<param name="id" type="uuid" dir="in">
4896	<desc>UUID of the snapshot to discard.</desc>
4897	</param>
4898	<param name="progress" type="IProgress" dir="return">
4899	<desc>Progress object to track the operation completion.</desc>
4900	</param>
4901	</method>
4902
4903	<method name="discardCurrentState">
4904	<desc>
4905	This operation is similar to <link to="#discardSnapshot()"/> but
4906	affects the current machine state. This means that the state stored in
4907	the current snapshot will become a new current state, and all current
4908	settings of the machine and changes stored in differencing hard disks
4909	will be lost.
4910
4911	After this operation is successfully completed, new empty differencing
4912	hard disks are created for all normal hard disks of the machine.
4913
4914	If the current snapshot of the machine is an online snapshot, the
4915	machine will go to the <link to="MachineState::Saved"> saved
4916	state</link>, so that the next time it is powered on, the execution
4917	state will be restored from the current snapshot.
4918
4919	<note>
4920	The machine must not be running, otherwise the operation will fail.
4921	</note>
4922
4923	<note>
4924	If the machine state is <link to="MachineState::Saved">Saved</link>
4925	prior to this operation, the saved state file will be implicitly
4926	discarded (as if <link to="IConsole::discardSavedState()"/> were
4927	called).
4928	</note>
4929
4930	</desc>
4931	<param name="progress" type="IProgress" dir="return">
4932	<desc>Progress object to track the operation completion.</desc>
4933	</param>
4934	</method>
4935
4936	<method name="discardCurrentSnapshotAndState">
4937	<desc>
4938
4939	This method is equivalent to
4940	doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
4941	(currentSnapshot.id(), progress) followed by
4942	<link to="#discardCurrentState()"/>.
4943
4944	As a result, the machine will be fully restored from the
4945	snapshot preceding the current snapshot, while both the current
4946	snapshot and the current machine state will be discarded.
4947
4948	If the current snapshot is the first snapshot of the machine (i.e. it
4949	has the only snapshot), the current machine state will be
4950	discarded <b>before</b> discarding the snapshot. In other words, the
4951	machine will be restored from its last snapshot, before discarding
4952	it. This differs from performing a single
4953	<link to="#discardSnapshot()"/> call (note that no
4954	<link to="#discardCurrentState()"/> will be possible after it)
4955	to the effect that the latter will preserve the current state instead of
4956	discarding it.
4957
4958	Unless explicitly mentioned otherwise, all remarks and
4959	limitations of the above two methods also apply to this method.
4960
4961	<note>
4962	The machine must not be running, otherwise the operation
4963	will fail.
4964	</note>
4965
4966	<note>
4967	If the machine state is <link to="MachineState::Saved">Saved</link>
4968	prior to this operation, the saved state file will be implicitly
4969	discarded (as if <link to="#discardSavedState()"/> were
4970	called).
4971	</note>
4972
4973	<note>
4974	This method is more efficient than calling two above
4975	methods separately: it requires less IPC calls and provides
4976	a single progress object.
4977	</note>
4978
4979	</desc>
4980	<param name="progress" type="IProgress" dir="return">
4981	<desc>Progress object to track the operation completion.</desc>
4982	</param>
4983	</method>
4984
4985	<method name="registerCallback">
4986	<desc>
4987	Registers a new console callback on this instance. The methods of the
4988	callback interface will be called by this instance when the appropriate
4989	event occurs.
4990	</desc>
4991	<param name="callback" type="IConsoleCallback" dir="in"/>
4992	</method>
4993
4994	<method name="unregisterCallback">
4995	<desc>
4996	Unregisters the console callback previously registered using
4997	<link to="#registerCallback"/>.
4998	</desc>
4999	<param name="callback" type="IConsoleCallback" dir="in"/>
5000	</method>
5001	</interface>
5002
5003	<!--
5004	// IHost
5005	/////////////////////////////////////////////////////////////////////////
5006	-->
5007
5008	<interface
5009	name="IHostDVDDrive" extends="$unknown"
5010	uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
5011	wsmap="managed"
5012	>
5013	<desc>
5014	The IHostDVDDrive interface represents the physical CD/DVD drive
5015	hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
5016	</desc>
5017
5018	<attribute name="name" type="wstring" readonly="yes">
5019	<desc>
5020	Returns the platform-specific device identifier.
5021	On DOS-like platforms, it is a drive name (e.g. R:).
5022	On Unix-like platforms, it is a device name (e.g. /dev/hdc).
5023	</desc>
5024	</attribute>
5025	<attribute name="description" type="wstring" readonly="yes">
5026	<desc>
5027	Returns a human readable description for the drive. This
5028	description usually contains the product and vendor name. A
5029	@c null string is returned if the description is not available.
5030	</desc>
5031	</attribute>
5032	<attribute name="udi" type="wstring" readonly="yes">
5033	<desc>
5034	Returns the unique device identifier for the drive. This
5035	attribute is reserved for future use instead of
5036	<link to="#name"/>. Currently it is not used and may return
5037	@c null on some platforms.
5038	</desc>
5039	</attribute>
5040
5041	</interface>
5042
5043	<enumerator
5044	name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
5045	uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
5046	/>
5047
5048	<collection
5049	name="IHostDVDDriveCollection" type="IHostDVDDrive"
5050	enumerator="IHostDVDDriveEnumerator"
5051	uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
5052	readonly="yes"
5053	>
5054	<method name="findByName">
5055	<desc>
5056	Searches this collection for a host drive with the given name.
5057	<note>
5058	The method returns an error if the given name does not
5059	correspond to any host drive in the collection.
5060	</note>
5061	</desc>
5062	<param name="name" type="wstring" dir="in">
5063	<desc>Name of the host drive to search for</desc>
5064	</param>
5065	<param name="drive" type="IHostDVDDrive" dir="return">
5066	<desc>Found host drive object</desc>
5067	</param>
5068	</method>
5069	</collection>
5070
5071	<interface
5072	name="IHostFloppyDrive" extends="$unknown"
5073	uuid="b6a4d1a9-4221-43c3-bd52-021a5daa9ed2"
5074	wsmap="managed"
5075	>
5076	<desc>
5077	The IHostFloppyDrive interface represents the physical floppy drive
5078	hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
5079	</desc>
5080	<attribute name="name" type="wstring" readonly="yes">
5081	<desc>
5082	Returns the platform-specific device identifier.
5083	On DOS-like platforms, it is a drive name (e.g. A:).
5084	On Unix-like platforms, it is a device name (e.g. /dev/fd0).
5085	</desc>
5086	</attribute>
5087	<attribute name="description" type="wstring" readonly="yes">
5088	<desc>
5089	Returns a human readable description for the drive. This
5090	description usually contains the product and vendor name. A
5091	@c null string is returned if the description is not available.
5092	</desc>
5093	</attribute>
5094	<attribute name="udi" type="wstring" readonly="yes">
5095	<desc>
5096	Returns the unique device identifier for the drive. This
5097	attribute is reserved for future use instead of
5098	<link to="#name"/>. Currently it is not used and may return
5099	@c null on some platforms.
5100	</desc>
5101	</attribute>
5102	</interface>
5103
5104	<enumerator
5105	name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
5106	uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
5107	/>
5108
5109	<collection
5110	name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
5111	enumerator="IHostFloppyDriveEnumerator"
5112	uuid="fd84bb86-c59a-4037-a557-755ff263a460"
5113	readonly="yes"
5114	>
5115	<method name="findByName">
5116	<desc>
5117	Searches this collection for a host drive with the given name.
5118	<note>
5119	The method returns an error if the given name does not
5120	correspond to any host drive in the collection.
5121	</note>
5122	</desc>
5123	<param name="name" type="wstring" dir="in">
5124	<desc>Name of the host drive to search for</desc>
5125	</param>
5126	<param name="drive" type="IHostFloppyDrive" dir="return">
5127	<desc>Found host drive object</desc>
5128	</param>
5129	</method>
5130	</collection>
5131
5132	<interface
5133	name="IHostNetworkInterface" extends="$unknown"
5134	uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
5135	wsmap="managed"
5136	>
5137	<attribute name="name" type="wstring" readonly="yes">
5138	<desc>Returns the host network interface name.</desc>
5139	</attribute>
5140
5141	<attribute name="id" type="uuid" readonly="yes">
5142	<desc>Returns the interface UUID.</desc>
5143	</attribute>
5144	</interface>
5145
5146	<enumerator
5147	name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
5148	uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
5149	/>
5150
5151	<collection
5152	name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
5153	enumerator="IHostNetworkInterfaceEnumerator"
5154	uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
5155	readonly="yes"
5156	>
5157	<method name="findByName">
5158	<desc>
5159	Searches this collection for a host network interface with the given name.
5160	<note>
5161	The method returns an error if the given name does not
5162	correspond to any host network interface in the collection.
5163	</note>
5164	</desc>
5165	<param name="name" type="wstring" dir="in">
5166	<desc>Name of the host network interface to search for.</desc>
5167	</param>
5168	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
5169	<desc>Found host network interface object.</desc>
5170	</param>
5171	</method>
5172	<method name="findById">
5173	<desc>
5174	Searches this collection for a host network interface with the given GUID.
5175	<note>
5176	The method returns an error if the given GUID does not
5177	correspond to any host network interface in the collection.
5178	</note>
5179	</desc>
5180	<param name="id" type="uuid" dir="in">
5181	<desc>GUID of the host network interface to search for.</desc>
5182	</param>
5183	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
5184	<desc>Found host network interface object.</desc>
5185	</param>
5186	</method>
5187	</collection>
5188
5189	<interface
5190	name="IHost" extends="$unknown"
5191	uuid="4be2e85f-a54c-4bc7-8bf6-f070f9113940"
5192	wsmap="managed"
5193	>
5194	<desc>
5195	The IHost interface represents the physical machine that this VirtualBox
5196	installation runs on.
5197
5198	An object implementing this interface is returned by the
5199	<link to="IVirtualBox::host" /> attribute. This interface contains
5200	read-only information about the host's physical hardware (such as what
5201	processors, and disks are available, what the host operating system is,
5202	and so on) and also allows for manipulating some of the host's hardware,
5203	such as global USB device filters and host interface networking.
5204
5205	</desc>
5206	<attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
5207	<desc>List of DVD drives available on the host.</desc>
5208	</attribute>
5209
5210	<attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
5211	<desc>List of floppy drives available on the host.</desc>
5212	</attribute>
5213
5214	<attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
5215	<desc>
5216	List of USB devices currently attached to the host.
5217	Once a new device is physically attached to the host computer,
5218	it appears in this list and remains there until detached.
5219
5220	<note>
5221	This method may set a @ref com_warnings "warning result code".
5222	</note>
5223	<note>
5224	If USB functionality is not available in the given edition of
5225	VirtualBox, this method will set the result code to @c E_NOTIMPL.
5226	</note>
5227	</desc>
5228	</attribute>
5229
5230	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
5231	<desc>
5232	List of USB device filters in action.
5233	When a new device is physically attached to the host computer,
5234	filters from this list are applied to it (in order they are stored
5235	in the list). The first matched filter will determine the
5236	<link to="IHostUSBDeviceFilter::action">action</link>
5237	performed on the device.
5238
5239	Unless the device is ignored by these filters, filters of all
5240	currently running virtual machines
5241	(<link to="IUSBController::deviceFilters"/>) are applied to it.
5242
5243	<note>
5244	This method may set a @ref com_warnings "warning result code".
5245	</note>
5246	<note>
5247	If USB functionality is not available in the given edition of
5248	VirtualBox, this method will set the result code to @c E_NOTIMPL.
5249	</note>
5250
5251	<see>IHostUSBDeviceFilter, USBDeviceState</see>
5252	</desc>
5253	</attribute>
5254
5255	<attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
5256	<desc>List of host network interfaces currently defined on the host.</desc>
5257	</attribute>
5258
5259	<attribute name="processorCount" type="unsigned long" readonly="yes">
5260	<desc>Number of (logical) CPUs installed in the host system.</desc>
5261	</attribute>
5262
5263	<attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
5264	<desc>Number of (logical) CPUs online in the host system.</desc>
5265	</attribute>
5266
5267	<method name="getProcessorSpeed">
5268	<desc>Query the (approximate) maximum speed of a specified host CPU in Megahertz.</desc>
5269	<param name="cpuId" type="unsigned long" dir="in">
5270	<desc>
5271	Identifier of the CPU.
5272	</desc>
5273	</param>
5274	<param name="speed" type="unsigned long" dir="return">
5275	<desc>
5276	Speed value. 0 is returned if value is not known or @a cpuId is
5277	invalid.
5278	</desc>
5279	</param>
5280	</method>
5281
5282	<method name="getProcessorFeature">
5283	<desc>Query whether a CPU feature is supported or not.</desc>
5284	<param name="feature" type="ProcessorFeature" dir="in">
5285	<desc>
5286	CPU Feature identifier.
5287	</desc>
5288	</param>
5289	<param name="supported" type="boolean" dir="return">
5290	<desc>
5291	Feature is supported or not.
5292	</desc>
5293	</param>
5294	</method>
5295
5296	<method name="getProcessorDescription">
5297	<desc>Query the model string of a specified host CPU.</desc>
5298	<param name="cpuId" type="unsigned long" dir="in">
5299	<desc>
5300	Identifier of the CPU.
5301	</desc>
5302	</param>
5303	<param name="description" type="wstring" dir="return">
5304	<desc>
5305	Model string. A NULL string is returned if value is not known or
5306	@a cpuId is invalid.
5307	</desc>
5308	</param>
5309	</method>
5310
5311	<attribute name="memorySize" type="unsigned long" readonly="yes">
5312	<desc>Amount of system memory in megabytes installed in the host system.</desc>
5313	</attribute>
5314
5315	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
5316	<desc>Available system memory in the host system.</desc>
5317	</attribute>
5318
5319	<attribute name="operatingSystem" type="wstring" readonly="yes">
5320	<desc>Name of the host system's operating system.</desc>
5321	</attribute>
5322
5323	<attribute name="OSVersion" type="wstring" readonly="yes">
5324	<desc>Host operating system's version string.</desc>
5325	</attribute>
5326
5327	<attribute name="UTCTime" type="long long" readonly="yes">
5328	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
5329	</attribute>
5330
5331	<if target="midl">
5332	<method name="createHostNetworkInterface">
5333	<desc>
5334	Creates a new adapter for Host Interface Networking.
5335	</desc>
5336	<param name="name" type="wstring" dir="in">
5337	<desc>
5338	Adapter name.
5339	</desc>
5340	</param>
5341	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
5342	<desc>
5343	Created host interface object.
5344	</desc>
5345	</param>
5346	<param name="progress" type="IProgress" dir="return">
5347	<desc>
5348	Progress object to track the operation completion.
5349	</desc>
5350	</param>
5351	</method>
5352	<method name="removeHostNetworkInterface">
5353	<desc>
5354	Removes the given host network interface.
5355	</desc>
5356	<param name="id" type="uuid" dir="in">
5357	<desc>
5358	Adapter GUID.
5359	</desc>
5360	</param>
5361	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
5362	<desc>
5363	Removed host interface object.
5364	</desc>
5365	</param>
5366	<param name="progress" type="IProgress" dir="return">
5367	<desc>
5368	Progress object to track the operation completion.
5369	</desc>
5370	</param>
5371	</method>
5372	</if>
5373
5374	<method name="createUSBDeviceFilter">
5375	<desc>
5376	Creates a new USB device filter. All attributes except
5377	the filter name are set to <tt>null</tt> (any match),
5378	<i>active</i> is <tt>false</tt> (the filter is not active).
5379
5380	The created filter can be added to the list of filters using
5381	<link to="#insertUSBDeviceFilter()"/>.
5382
5383	<see>#USBDeviceFilters</see>
5384	</desc>
5385	<param name="name" type="wstring" dir="in">
5386	<desc>
5387	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
5388	for more info.
5389	</desc>
5390	</param>
5391	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
5392	<desc>Created filter object.</desc>
5393	</param>
5394	</method>
5395
5396	<method name="insertUSBDeviceFilter">
5397	<desc>
5398	Inserts the given USB device to the specified position
5399	in the list of filters.
5400
5401	Positions are numbered starting from <tt>0</tt>. If the specified
5402	position is equal to or greater than the number of elements in
5403	the list, the filter is added to the end of the collection.
5404
5405	<note>
5406	Duplicates are not allowed, so an attempt to insert a
5407	filter that is already in the list, will return an
5408	error.
5409	</note>
5410	<note>
5411	This method may set a @ref com_warnings "warning result code".
5412	</note>
5413	<note>
5414	If USB functionality is not available in the given edition of
5415	VirtualBox, this method will set the result code to @c E_NOTIMPL.
5416	</note>
5417
5418	<see>#USBDeviceFilters</see>
5419	</desc>
5420	<param name="position" type="unsigned long" dir="in">
5421	<desc>Position to insert the filter to.</desc>
5422	</param>
5423	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
5424	<desc>USB device filter to insert.</desc>
5425	</param>
5426	</method>
5427
5428	<method name="removeUSBDeviceFilter">
5429	<desc>
5430	Removes a USB device filter from the specified position in the
5431	list of filters.
5432
5433	Positions are numbered starting from <tt>0</tt>. Specifying a
5434	position equal to or greater than the number of elements in
5435	the list will produce an error.
5436
5437	<note>
5438	This method may set a @ref com_warnings "warning result code".
5439	</note>
5440	<note>
5441	If USB functionality is not available in the given edition of
5442	VirtualBox, this method will set the result code to @c E_NOTIMPL.
5443	</note>
5444
5445	<see>#USBDeviceFilters</see>
5446	</desc>
5447	<param name="position" type="unsigned long" dir="in">
5448	<desc>Position to remove the filter from.</desc>
5449	</param>
5450	<param name="filter" type="IHostUSBDeviceFilter" dir="return">
5451	<desc>Removed USB device filter.</desc>
5452	</param>
5453	</method>
5454
5455	</interface>
5456
5457	<!--
5458	// ISystemProperties
5459	/////////////////////////////////////////////////////////////////////////
5460	-->
5461
5462	<interface
5463	name="ISystemProperties"
5464	extends="$unknown"
5465	uuid="604afeba-5963-4d12-a577-902ffb96352a"
5466	wsmap="managed"
5467	>
5468	<desc>
5469	The ISystemProperties interface represents global properties of the given
5470	VirtualBox installation.
5471
5472	These properties define limits and default values for various attributes
5473	and parameters. Most of the properties are read-only, but some can be
5474	changed by a user.
5475	</desc>
5476
5477	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
5478	<desc>Minimum guest system memory in Megabytes.</desc>
5479	</attribute>
5480
5481	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
5482	<desc>Maximum guest system memory in Megabytes.</desc>
5483	</attribute>
5484
5485	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
5486	<desc>Minimum guest video memory in Megabytes.</desc>
5487	</attribute>
5488
5489	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
5490	<desc>Maximum guest video memory in Megabytes.</desc>
5491	</attribute>
5492
5493	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
5494	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
5495	</attribute>
5496
5497	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
5498	<desc>
5499	Number of network adapters associated with every
5500	<link to="IMachine"/> instance.
5501	</desc>
5502	</attribute>
5503
5504	<attribute name="serialPortCount" type="unsigned long" readonly="yes">
5505	<desc>
5506	Number of serial ports associated with every
5507	<link to="IMachine"/> instance.
5508	</desc>
5509	</attribute>
5510
5511	<attribute name="parallelPortCount" type="unsigned long" readonly="yes">
5512	<desc>
5513	Number of parallel ports associated with every
5514	<link to="IMachine"/> instance.
5515	</desc>
5516	</attribute>
5517
5518	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
5519	<desc>
5520	Maximum device position in the boot order. This value corresponds
5521	to the total number of devices a machine can boot from, to make it
5522	possible to include all possible devices to the boot list.
5523	<see><link to="IMachine::setBootOrder()"/></see>
5524	</desc>
5525	</attribute>
5526
5527	<attribute name="defaultMachineFolder" type="wstring">
5528	<desc>
5529	Full path to the default directory used to create new or open
5530	existing machines when a settings file name contains no
5531	path.
5532
5533	The initial value of this property is
5534	<tt><</tt><link to="IVirtualBox::homeFolder">
5535	VirtualBox_home</link><tt>>/Machines</tt>.
5536
5537	<note>
5538	Setting this property to <tt>null</tt> will restore the
5539	initial value.
5540	</note>
5541	<note>
5542	When settings this property, the specified path can be
5543	absolute (full path) or relative
5544	to the <link to="IVirtualBox::homeFolder">
5545	VirtualBox home directory</link>.
5546	When reading this property, a full path is
5547	always returned.
5548	</note>
5549	<note>
5550	The specified path may not exist, it will be created
5551	when necessary.
5552	</note>
5553
5554	<see>
5555	<link to="IVirtualBox::createMachine()"/>,
5556	<link to="IVirtualBox::openMachine()"/>
5557	</see>
5558	</desc>
5559	</attribute>
5560
5561	<attribute name="defaultHardDiskFolder" type="wstring">
5562	<desc>
5563	Full path to the default directory used to create new or open existing
5564	virtual disks.
5565
5566	This path is used when the storage unit of a hard disk is a regular file
5567	in the host's file system and only a file name that contains no path is
5568	given.
5569
5570	The initial value of this property is
5571	<tt><</tt>
5572	<link to="IVirtualBox::homeFolder">VirtualBox_home</link>
5573	<tt>>/HardDisks</tt>.
5574
5575	<note>
5576	Setting this property to <tt>null</tt> will restore the
5577	initial value.
5578	</note>
5579	<note>
5580	When settings this property, the specified path can be relative
5581	to the
5582	<link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
5583	absolute. When reading this property, a full path is
5584	always returned.
5585	</note>
5586	<note>
5587	The specified path may not exist, it will be created
5588	when necessary.
5589	</note>
5590
5591	<see>
5592	IHardDisk2,
5593	<link to="IVirtualBox::createHardDisk2()"/>,
5594	<link to="IVirtualBox::openHardDisk2()"/>,
5595	<link to="IMedium::location"/>
5596	</see>
5597	</desc>
5598	</attribute>
5599
5600	<attribute name="hardDiskFormats" type="IHardDiskFormat" safearray="yes" readonly="yes">
5601	<desc>
5602	List of all hard disk storage formats supported by this VirtualBox
5603	installation.
5604
5605	Note that the virtual hard disk framework is backend-based, therefore
5606	the list of supported formats depends on what backends are currently
5607	installed.
5608
5609	<see>
5610	<link to="IHardDiskFormat"/>,
5611	</see>
5612	</desc>
5613	</attribute>
5614
5615	<attribute name="defaultHardDiskFormat" type="wstring">
5616	<desc>
5617	Identifier of the default hard disk format used by VirtualBox.
5618
5619	The hard disk format set by this attribute is used by VirtualBox
5620	when the hard disk format was not specified explicitly. One example is
5621	<link to="IVirtualBox::createHardDisk2()"/> with the <tt>null</tt>
5622	format argument. A more complex example is implicit creation of
5623	differencing hard disks when taking a snapshot of a virtual machine:
5624	this operation will try to use a format of the parent hard disk first
5625	and if this format does not support differencing hard disks the default
5626	format specified by this argument will be used.
5627
5628	The list of supported hard disk formats may be obtained by the
5629	<link to="#defaultHardDiskFormats"/> call. Note that the default
5630	hard disk format must have a capability to create differencing hard
5631	disks; otherwise opeartions that create hard disks implicitly may fail
5632	unexpectedly.
5633
5634	The initial value of this property is <tt>VDI</tt> in the current
5635	version of the VirtualBox product, but may change in the future.
5636
5637	<note>
5638	Setting this property to <tt>null</tt> will restore the
5639	initial value.
5640	</note>
5641
5642	<see>
5643	<link to="#hardDiskFormats"/>,
5644	<link to="IHardDiskFormat:id"/>,
5645	<link to="IVirtualBox::createHardDisk2()"/>
5646	</see>
5647	</desc>
5648	</attribute>
5649
5650	<attribute name="remoteDisplayAuthLibrary" type="wstring">
5651	<desc>
5652	Library that provides authentication for VRDP clients. The library
5653	is used if a virtual machine's authentication type is set to "external"
5654	in the VM RemoteDisplay configuration.
5655
5656	The system library extension (".DLL" or ".so") must be omitted.
5657	A full path can be specified; if not, then the library must reside on the
5658	system's default library path.
5659
5660	The default value of this property is <tt>VRDPAuth</tt>. There is a library
5661	of that name in one of the default VirtualBox library directories.
5662
5663	For details about VirtualBox authentication libraries and how to implement
5664	them, please refer to the VirtualBox manual.
5665
5666	<note>
5667	Setting this property to <tt>null</tt> will restore the
5668	initial value.
5669	</note>
5670	</desc>
5671	</attribute>
5672
5673	<attribute name="webServiceAuthLibrary" type="wstring">
5674	<desc>
5675	Library that provides authentication for webservice clients. The library
5676	is used if a virtual machine's authentication type is set to "external"
5677	in the VM RemoteDisplay configuration and will be called from
5678	within the <link to="IWebsessionManager::logon" /> implementation.
5679
5680	As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
5681	there is no per-VM setting for this, as the webservice is a global
5682	resource (if it is running). Only for this setting (for the webservice),
5683	setting this value to a literal "null" string disables authentication,
5684	meaning that <link to="IWebsessionManager::logon" /> will always succeed,
5685	no matter what user name and password are supplied.
5686
5687	The initial value of this property is <tt>VRDPAuth</tt>,
5688	meaning that the webservice will use the same authentication
5689	library that is used by default for VBoxVRDP (again, see
5690	<link to="ISystemProperties::remoteDisplayAuthLibrary" />).
5691	The format and calling convention of authentication libraries
5692	is the same for the webservice as it is for VBoxVRDP.
5693
5694	</desc>
5695	</attribute>
5696
5697	<attribute name="HWVirtExEnabled" type="boolean">
5698	<desc>
5699	This specifies the default value for hardware virtualization
5700	extensions. If enabled, virtual machines will make use of
5701	hardware virtualization extensions such as Intel VT-x and
5702	AMD-V by default. This value can be overridden by each VM
5703	using their <link to="IMachine::HWVirtExEnabled" /> property.
5704	</desc>
5705	</attribute>
5706
5707	<attribute name="LogHistoryCount" type="unsigned long">
5708	<desc>
5709	This value specifies how many old release log files are kept.
5710	</desc>
5711	</attribute>
5712	</interface>
5713
5714	<!--
5715	// IGuest
5716	/////////////////////////////////////////////////////////////////////////
5717	-->
5718
5719	<interface
5720	name="IGuestOSType" extends="$unknown"
5721	uuid="da94f478-1f37-4726-b750-2235950dc2fe"
5722	wsmap="struct"
5723	>
5724	<desc>
5725	</desc>
5726
5727	<attribute name="familyId" type="wstring" readonly="yes">
5728	<desc>Guest OS family identifier string.</desc>
5729	</attribute>
5730
5731	<attribute name="familyDescription" type="wstring" readonly="yes">
5732	<desc>Human readable description of the guest OS family.</desc>
5733	</attribute>
5734
5735	<attribute name="id" type="wstring" readonly="yes">
5736	<desc>Guest OS identifier string.</desc>
5737	</attribute>
5738
5739	<attribute name="description" type="wstring" readonly="yes">
5740	<desc>Human readable description of the guest OS.</desc>
5741	</attribute>
5742
5743	<attribute name="is64Bit" type="boolean" readonly="yes">
5744	<desc>Returns @c true if the given OS is 64-bit</desc>
5745	</attribute>
5746
5747	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
5748	<desc>Recommended RAM size in Megabytes.</desc>
5749	</attribute>
5750
5751	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
5752	<desc>Recommended video RAM size in Megabytes.</desc>
5753	</attribute>
5754
5755	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
5756	<desc>Recommended hard disk size in Megabytes.</desc>
5757	</attribute>
5758	</interface>
5759
5760
5761	<enumerator
5762	name="IGuestOSTypeEnumerator" type="IGuestOSType"
5763	uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
5764	/>
5765
5766	<collection
5767	name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
5768	uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
5769	readonly="yes"
5770	/>
5771
5772	<interface
5773	name="IGuest" extends="$unknown"
5774	uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
5775
5776	wsmap="suppress"
5777	>
5778	<desc>
5779	The IGuest interface represents information about the operating system
5780	running inside the virtual machine. Used in
5781	<link to="IConsole::guest"/>.
5782
5783	IGuest provides information about the guest operating system, whether
5784	Guest Additions are installed and other OS-specific virtual machine
5785	properties.
5786	</desc>
5787
5788	<attribute name="OSTypeId" type="wstring" readonly="yes">
5789	<desc>
5790	Identifier of the Guest OS type as reported by the Guest
5791	Additions.
5792	You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
5793	an IGuestOSType object representing details about the given
5794	Guest OS type.
5795	<note>
5796	If Guest Additions are not installed, this value will be
5797	the same as <link to="IMachine::OSTypeId"/>.
5798	</note>
5799	</desc>
5800	</attribute>
5801
5802	<attribute name="additionsActive" type="boolean" readonly="yes">
5803	<desc>
5804	Flag whether the Guest Additions are installed and active
5805	in which case their version will be returned by the
5806	<link to="#additionsVersion"/> property.
5807	</desc>
5808	</attribute>
5809
5810	<attribute name="additionsVersion" type="wstring" readonly="yes">
5811	<desc>
5812	Version of the Guest Additions (3 decimal numbers separated
5813	by dots) or empty when the Additions are not installed. The
5814	Additions may also report a version but yet not be active as
5815	the version might be refused by VirtualBox (incompatible) or
5816	other failures occurred.
5817	</desc>
5818	</attribute>
5819
5820	<attribute name="supportsSeamless" type="boolean" readonly="yes">
5821	<desc>
5822	Flag whether seamless guest display rendering (seamless desktop
5823	integration) is supported.
5824	</desc>
5825	</attribute>
5826
5827	<attribute name="supportsGraphics" type="boolean" readonly="yes">
5828	<desc>
5829	Flag whether the guest is in graphics mode. If it is not, then
5830	seamless rendering will not work, resize hints are not immediately
5831	acted on and guest display resizes are probably not initiated by
5832	the guest additions.
5833	</desc>
5834	</attribute>
5835
5836	<attribute name="memoryBalloonSize" type="unsigned long">
5837	<desc>Guest system memory balloon size in megabytes.</desc>
5838	</attribute>
5839
5840	<attribute name="statisticsUpdateInterval" type="unsigned long">
5841	<desc>Interval to update guest statistics in seconds.</desc>
5842	</attribute>
5843
5844	<method name="setCredentials">
5845	<desc>
5846	Store login credentials that can be queried by guest operating
5847	systems with Additions installed. The credentials are transient
5848	to the session and the guest may also choose to erase them. Note
5849	that the caller cannot determine whether the guest operating system
5850	has queried or made use of the credentials.
5851	</desc>
5852	<param name="userName" type="wstring" dir="in">
5853	<desc>User name string, can be empty</desc>
5854	</param>
5855	<param name="password" type="wstring" dir="in">
5856	<desc>Password string, can be empty</desc>
5857	</param>
5858	<param name="domain" type="wstring" dir="in">
5859	<desc>Domain name (guest logon scheme specific), can be empty</desc>
5860	</param>
5861	<param name="allowInteractiveLogon" type="boolean" dir="in">
5862	<desc>
5863	Flag whether the guest should alternatively allow the user to
5864	interactively specify different credentials. This flag might
5865	not be supported by all versions of the Additions.
5866	</desc>
5867	</param>
5868	</method>
5869
5870	<method name="getStatistic">
5871	<desc>
5872	Query specified guest statistics as reported by the VirtualBox Additions.
5873	</desc>
5874	<param name="cpuId" type="unsigned long" dir="in">
5875	<desc>Virtual CPU id; not relevant for all statistic types</desc>
5876	</param>
5877	<param name="statistic" type="GuestStatisticType" dir="in">
5878	<desc>Statistic type.</desc>
5879	</param>
5880	<param name="statVal" type="unsigned long" dir="out">
5881	<desc>Statistics value</desc>
5882	</param>
5883	</method>
5884
5885	</interface>
5886
5887
5888	<!--
5889	// IProgress
5890	/////////////////////////////////////////////////////////////////////////
5891	-->
5892
5893	<enumerator
5894	name="IProgressEnumerator" type="IProgress"
5895	uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
5896	/>
5897
5898	<collection
5899	name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
5900	uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
5901	readonly="yes"
5902	/>
5903
5904	<interface
5905	name="IProgress" extends="$unknown"
5906	uuid="10CC03A1-717E-429b-992D-C67B56175A51"
5907	wsmap="managed"
5908	>
5909	<desc>
5910	The IProgress interface represents a task progress object that allows
5911	to wait for the completion of some asynchronous task.
5912
5913	The task consists of one or more operations that run sequentially,
5914	one after one. There is an individual percent of completion of the
5915	current operation and the percent of completion of the task as a
5916	whole. Similarly, you can wait for the completion of a particular
5917	operation or for the completion of the whole task.
5918
5919	Every operation is identified by a number (starting from 0)
5920	and has a separate description.
5921	</desc>
5922
5923	<attribute name="id" type="uuid" readonly="yes">
5924	<desc>ID of the task.</desc>
5925	</attribute>
5926
5927	<attribute name="description" type="wstring" readonly="yes">
5928	<desc>Description of the task.</desc>
5929	</attribute>
5930
5931	<attribute name="initiator" type="$unknown" readonly="yes">
5932	<desc>Initiator of the task.</desc>
5933	</attribute>
5934
5935	<attribute name="cancelable" type="boolean" readonly="yes">
5936	<desc>Whether the task can be interrupted.</desc>
5937	</attribute>
5938
5939	<attribute name="percent" type="long" readonly="yes">
5940	<desc>
5941	Current task progress value in percent.
5942	This value depends on how many operations are already complete.
5943	</desc>
5944	</attribute>
5945
5946	<attribute name="completed" type="boolean" readonly="yes">
5947	<desc>Whether the task has been completed.</desc>
5948	</attribute>
5949
5950	<attribute name="canceled" type="boolean" readonly="yes">
5951	<desc>Whether the task has been canceled.</desc>
5952	</attribute>
5953
5954	<attribute name="resultCode" type="result" readonly="yes">
5955	<desc>
5956	Result code of the progress task.
5957	Valid only if <link to="#completed"/> is true.
5958	</desc>
5959	</attribute>
5960
5961	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
5962	<desc>
5963	Extended information about the unsuccessful result of the
5964	progress operation. May be NULL when no extended information
5965	is available.
5966	Valid only if <link to="#completed"/> is true and
5967	<link to="#resultCode"/> indicates a failure.
5968	</desc>
5969	</attribute>
5970
5971	<attribute name="operationCount" type="unsigned long" readonly="yes">
5972	<desc>
5973	Number of operations this task is divided into.
5974	Every task consists of at least one operation.
5975	</desc>
5976	</attribute>
5977
5978	<attribute name="operation" type="unsigned long" readonly="yes">
5979	<desc>Number of the operation being currently executed.</desc>
5980	</attribute>
5981
5982	<attribute name="operationDescription" type="wstring" readonly="yes">
5983	<desc>
5984	Description of the operation being currently executed.
5985	</desc>
5986	</attribute>
5987
5988	<attribute name="operationPercent" type="long" readonly="yes">
5989	<desc>Current operation progress value in percent.</desc>
5990	</attribute>
5991
5992	<method name="waitForCompletion">
5993	<desc>
5994	Waits until the task is done (including all operations) with a
5995	given timeout.
5996	</desc>
5997	<param name="timeout" type="long" dir="in">
5998	<desc>
5999	Timeout value in milliseconds.
6000	Specify -1 for an indefinite wait.
6001	</desc>
6002	</param>
6003	</method>
6004
6005	<method name="waitForOperationCompletion">
6006	<desc>
6007	Waits until the given operation is done with a given timeout.
6008	</desc>
6009	<param name="operation" type="unsigned long" dir="in">
6010	<desc>
6011	Number of the operation to wait for.
6012	Must be less than <link to="#operationCount"/>.
6013	</desc>
6014	</param>
6015	<param name="timeout" type="long" dir="in">
6016	<desc>
6017	Timeout value in milliseconds.
6018	Specify -1 for an indefinite wait.
6019	</desc>
6020	</param>
6021	</method>
6022
6023	<method name="cancel">
6024	<desc>
6025	Cancels the task.
6026	<note>
6027	If <link to="#cancelable"/> is <tt>false</tt>, then
6028	this method will fail.
6029	</note>
6030	</desc>
6031	</method>
6032
6033	</interface>
6034
6035
6036	<!--
6037	// ISnapshot
6038	/////////////////////////////////////////////////////////////////////////
6039	-->
6040
6041	<enumerator
6042	name="ISnapshotEnumerator" type="ISnapshot"
6043	uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
6044	/>
6045
6046	<collection
6047	name="ISnapshotCollection" type="ISnapshot"
6048	enumerator="ISnapshotEnumerator"
6049	uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
6050	readonly="yes"
6051	/>
6052
6053	<interface
6054	name="ISnapshot" extends="$unknown"
6055	uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
6056	wsmap="managed"
6057	>
6058	<desc>
6059	The ISnapshot interface represents a snapshot of the virtual
6060	machine.
6061
6062	The <i>snapshot</i> stores all the information about a virtual
6063	machine necessary to bring it to exactly the same state as it was at
6064	the time of taking the snapshot. The snapshot includes:
6065
6066	<ul>
6067	<li>all settings of the virtual machine (i.e. its hardware
6068	configuration: RAM size, attached hard disks, etc.)
6069	</li>
6070	<li>the execution state of the virtual machine (memory contents,
6071	CPU state, etc.).
6072	</li>
6073	</ul>
6074
6075	Snapshots can be <i>offline</i> (taken when the VM is powered off)
6076	or <i>online</i> (taken when the VM is running). The execution
6077	state of the offline snapshot is called a <i>zero execution state</i>
6078	(it doesn't actually contain any information about memory contents
6079	or the CPU state, assuming that all hardware is just powered off).
6080
6081	<h3>Snapshot branches</h3>
6082
6083	Snapshots can be chained. Chained snapshots form a branch where
6084	every next snapshot is based on the previous one. This chaining is
6085	mostly related to hard disk branching (see <link to="IHardDisk2"/>
6086	description). This means that every time a new snapshot is created,
6087	a new differencing hard disk is implicitly created for all normal
6088	hard disks attached to the given virtual machine. This allows to
6089	fully restore hard disk contents when the machine is later reverted
6090	to a particular snapshot.
6091
6092	In the current implementation, multiple snapshot branches within one
6093	virtual machine are not allowed. Every machine has a single branch,
6094	and <link to="IConsole::takeSnapshot()"/> operation adds a new
6095	snapshot to the top of that branch.
6096
6097	Existing snapshots can be discarded using
6098	<link to="IConsole::discardSnapshot()"/>.
6099
6100	<h3>Current snapshot</h3>
6101
6102	Every virtual machine has a current snapshot, identified by
6103	<link to="IMachine::currentSnapshot"/>. This snapshot is used as
6104	a base for the <i>current machine state</i> (see below), to the effect
6105	that all normal hard disks of the machine and its execution
6106	state are based on this snapshot.
6107
6108	In the current implementation, the current snapshot is always the
6109	last taken snapshot (i.e. the head snapshot on the branch) and it
6110	cannot be changed.
6111
6112	The current snapshot is <tt>null</tt> if the machine doesn't have
6113	snapshots at all; in this case the current machine state is just
6114	current settings of this machine plus its current execution state.
6115
6116	<h3>Current machine state</h3>
6117
6118	The current machine state is what represented by IMachine instances got
6119	directly from IVirtualBox
6120	using <link
6121	to="IVirtualBox::getMachine()">getMachine()</link>, <link
6122	to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as opposed
6123	to instances returned by <link to="ISnapshot::machine"/>). This state
6124	is always used when the machine is <link to="IConsole::powerUp"> powered
6125	on</link>.
6126
6127	The current machine state also includes the current execution state.
6128	If the machine is being currently executed
6129	(<link to="IMachine::state"/> is <link to="MachineState::Running"/>
6130	and above), its execution state is just what's happening now.
6131	If it is powered off (<link to="MachineState::PoweredOff"/> or
6132	<link to="MachineState::Aborted"/>), it has a zero execution state.
6133	If the machine is saved (<link to="MachineState::Saved"/>), its
6134	execution state is what saved in the execution state file
6135	(<link to="IMachine::stateFilePath"/>).
6136
6137	If the machine is in the saved state, then, next time it is powered
6138	on, its execution state will be fully restored from the saved state
6139	file and the execution will continue from the point where the state
6140	was saved.
6141
6142	Similarly to snapshots, the current machine state can be discarded
6143	using <link to="IConsole::discardCurrentState()"/>.
6144
6145	<h3>Taking and discarding snapshots</h3>
6146
6147	The table below briefly explains the meaning of every snapshot
6148	operation:
6149
6150	<table>
6151	<tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
6152
6153	<tr><td><link to="IConsole::takeSnapshot()"/></td>
6154
6155	<td>Save the current state of the virtual machine, including all
6156	settings, contents of normal hard disks and the current modifications
6157	to immutable hard disks (for online snapshots)</td>
6158
6159	<td>The current state is not changed (the machine will continue
6160	execution if it is being executed when the snapshot is
6161	taken)</td></tr>
6162
6163	<tr><td><link to="IConsole::discardSnapshot()"/></td>
6164
6165	<td>Forget the state of the virtual machine stored in the snapshot:
6166	dismiss all saved settings and delete the saved execution state (for
6167	online snapshots)</td>
6168
6169	<td>Other snapshots (including child snapshots, if any) and the
6170	current state are not directly affected</td></tr>
6171
6172	<tr><td><link to="IConsole::discardCurrentState()"/></td>
6173
6174	<td>Restore the current state of the virtual machine from the state
6175	stored in the current snapshot, including all settings and hard disk
6176	contents</td>
6177
6178	<td>The current state of the machine existed prior to this operation
6179	is lost</td></tr>
6180
6181	<tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
6182
6183	<td>Completely revert the virtual machine to the state it was in
6184	before the current snapshot has been taken</td>
6185
6186	<td>The current state, as well as the current snapshot, are
6187	lost</td></tr>
6188
6189	</table>
6190
6191	</desc>
6192
6193	<attribute name="id" type="uuid" readonly="yes">
6194	<desc>UUID of the snapshot.</desc>
6195	</attribute>
6196
6197	<attribute name="name" type="wstring">
6198	<desc>Short name of the snapshot.</desc>
6199	</attribute>
6200
6201	<attribute name="description" type="wstring">
6202	<desc>Optional description of the snapshot.</desc>
6203	</attribute>
6204
6205	<attribute name="timeStamp" type="long long" readonly="yes">
6206	<desc>
6207	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
6208	</desc>
6209	</attribute>
6210
6211	<attribute name="online" type="boolean" readonly="yes">
6212	<desc>
6213	<tt>true</tt> if this snapshot is an online snapshot and
6214	<tt>false</tt> otherwise.
6215
6216	<note>
6217	When this attribute is <tt>true</tt>, the
6218	<link to="IMachine::stateFilePath"/> attribute of the
6219	<link to="#machine"/> object associated with this snapshot
6220	will point to the saved state file. Otherwise, it will be
6221	<tt>null</tt>.
6222	</note>
6223	</desc>
6224	</attribute>
6225
6226	<attribute name="machine" type="IMachine" readonly="yes">
6227	<desc>
6228	Virtual machine this snapshot is taken on. This object
6229	stores all settings the machine had when taking this snapshot.
6230	<note>
6231	The returned machine object is immutable, i.e. no
6232	any settings can be changed.
6233	</note>
6234	</desc>
6235	</attribute>
6236
6237	<attribute name="parent" type="ISnapshot" readonly="yes">
6238	<desc>
6239	Parent snapshot (a snapshot this one is based on).
6240	<note>
6241	It's not an error to read this attribute on a snapshot
6242	that doesn't have a parent -- a null object will be
6243	returned to indicate this.
6244	</note>
6245	</desc>
6246	</attribute>
6247
6248	<attribute name="children" type="ISnapshotCollection" readonly="yes">
6249	<desc>
6250	Child snapshots (all snapshots having this one as a parent).
6251	<note>
6252	In the current implementation, there can be only one
6253	child snapshot, or no children at all, meaning this is the
6254	last (head) snapshot.
6255	</note>
6256	</desc>
6257	</attribute>
6258
6259	</interface>
6260
6261
6262	<!--
6263	// IMedia
6264	/////////////////////////////////////////////////////////////////////////
6265	-->
6266
6267	<enum
6268	name="MediaState"
6269	uuid="8b86e03c-2f1c-412a-8fbd-326f62701200"
6270	>
6271	<desc>
6272	Virtual media state.
6273	<see>IMedia</see>
6274	</desc>
6275
6276	<const name="NotCreated" value="0">
6277	<desc>
6278	Associated media storage does not exist (either was not created yet or
6279	was deleted).
6280	</desc>
6281	</const>
6282	<const name="Created" value="1">
6283	<desc>
6284	Associated storage exists and accessible.
6285	</desc>
6286	</const>
6287	<const name="LockedRead" value="2">
6288	<desc>
6289	Media is locked for reading, no data modification is possible.
6290	</desc>
6291	</const>
6292	<const name="LockedWrite" value="3">
6293	<desc>
6294	Media is locked for writing, no concurrent data reading or modification
6295	is possible.
6296	</desc>
6297	</const>
6298	<const name="Inaccessible" value="4">
6299	<desc>
6300	Associated media storage is not accessible.
6301	</desc>
6302	</const>
6303	<const name="Creating" value="5">
6304	<desc>
6305	Associated media storage is being created.
6306	</desc>
6307	</const>
6308	<const name="Deleting" value="6">
6309	<desc>
6310	Associated media storage is being deleted.
6311	</desc>
6312	</const>
6313	</enum>
6314
6315	<interface
6316	name="IMedium" extends="$unknown"
6317	uuid="a7fb3bfb-c180-4274-bae4-7fbc89046e13"
6318	wsmap="managed"
6319	>
6320	<desc>
6321	The IMedium interface is a common interface for all objects representing
6322	virtual media such as hard disks, DVD images.
6323
6324	Each medium is associated with a storage unit (such as a file on the host
6325	computer or a network resource) that holds actual data. The location of
6326	the storage unit is represented by the #location attribute. The value of
6327	this attribute is media type dependent.
6328
6329	The exact media type may be determined by querying the appropriate
6330	interface such as:
6331	<ul>
6332	<li>IHardDisk2 (virtual hard disks)</li>
6333	<li>IDVDImage2 (standard CD/DVD ISO image files)</li>
6334	<li>IFloppyImage2 (raw floppy image files)</li>
6335	</ul>
6336
6337	Existing media are opened using the following methods, depending on the
6338	media type:
6339	<ul>
6340	<li><link to="IVirtualBox::openHardDisk2()"/></li>
6341	<li><link to="IVirtualBox::openDVDImage()"/></li>
6342	<li><link to="IVirtualBox::openFloppyImage()"/></li>
6343	</ul>
6344
6345	New hard disk media are created using the
6346	<link to="IVirtualBox::createHardDisk2()"/> method. CD/DVD and floppy
6347	images are created outside VirtualBox, usually by storing a copy
6348	of the real medium of the corresponding type in a regular file.
6349
6350	<h3>Known Media</h3>
6351
6352	When an existing medium gets opened for the first time, it gets
6353	automatically remembered by the given VirtualBox installation or, in other
6354	words, becomes a <i>known medium</i>. Known media are stored in the media
6355	registry transparently maintained by VirtualBox and stored in settings
6356	files so that this registry is preserved when VirtualBox is not running.
6357
6358	Newly created virtual hard disks get remembered only when the associated
6359	storage unit is actually created (see IHardDisk2 for more details).
6360
6361	All known media can be enumerated using
6362	<link to="IVirtualBox::hardDisks2"/>,
6363	<link to="IVirtualBox::DVDImages"/> and
6364	<link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
6365	quickly found by by UUID using <link to="IVirtualBox::getHardDisk2()"/>
6366	and similar methods or by location using
6367	<link to="IVirtualBox::findHardDisk2()"/> and similar methods.
6368
6369	Only known media can be attached to virtual machines.
6370
6371	Removing known media from the media registry is performed when the given
6372	medium is closed using the <link to="#close()"/> method or when its
6373	associated storage unit is deleted (only for hard disks).
6374
6375	<h3>Accessibility Checks</h3>
6376
6377	The given medium (with the created storage unit) is considered to be
6378	<i>accessible</i> when its storage unit can be successfully read from.
6379	Accessible media are indicated by the <link to="MediaState::Created"/>
6380	value of the <link to="#state"/> attribute. When the storage unit cannot
6381	be read (for example, because it is located on a disconnected network
6382	resource, or was accidentally deleted outside VirtualBox), the medium is
6383	considered to be <i>inaccessible</i> which is indicated by the
6384	<link to="MediaState::Inaccessible"/> state. The details about the reason
6385	of being inaccessible can be obtained using the
6386	<link to="#lastAccessError"/> attribute.
6387
6388	A new accessibility check is performed each time the <link to="#state"/>
6389	attribute is read. Please note that this check may take long time (several
6390	seconds or even minutes, depending on the storage unit location and
6391	format), and will block the calling thread until finished. For this
6392	reason, it is recommended to never read this attribute on the main UI
6393	thread to avoid making the UI unresponsive.
6394
6395	Note that when VirtualBox starts up (e.g. the VirtualBox object gets
6396	created for the first time), all known media are in the
6397	<link to="MediaState::Inaccessible"/> state but the value of the <link
6398	to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
6399	accessibility check is made on startup. This is done to make the
6400	VirtualBox object ready for serving requests as
6401	fast as possible and let the end-user application decide if it needs to
6402	check media accessibility right away or not.
6403	</desc>
6404
6405	<attribute name="id" type="uuid" readonly="yes">
6406	<desc>
6407	UUID of the medium. For a newly created medium, this value is a randomly
6408	generated UUID.
6409	</desc>
6410	</attribute>
6411
6412	<attribute name="description" type="wstring">
6413	<desc>
6414	Optional description of the medium. For newly created media, the value
6415	of this attribute value is <tt>null</tt>.
6416
6417	Media types that don't support this attribute will return E_NOTIMPL in
6418	attempt to get or set this attribute's value.
6419
6420	<note>
6421	For some storage types, reading this attribute may return an outdated
6422	(last known) value when <link to="#state"/> is <link
6423	to="MediaState::Inaccessible"/> or <link
6424	to="MediaState::LockedWrite"/> because the value of this attribute is
6425	stored within the storage unit itself. Also note that changing the
6426	attribute value is not possible in such case, as well as when the
6427	medium is the <link to="MediaState::LockedRead"/> state.
6428	</note>
6429	</desc>
6430	</attribute>
6431
6432	<attribute name="state" type="MediaState" readonly="yes">
6433	<desc>
6434	Current media state. Inspect <link to="MediaState"/> values for details.
6435
6436	Reading this attribute may take long time because a new accessibility
6437	check of the storage unit is performed every time the attribute is read.
6438	This check may cause a significant delay if the storage unit of the
6439	given medium is, for example, a file located on a network share which is
6440	not currently accessible due to connectivity problems -- the call will
6441	not return until a timeout interval defined by the host OS for this
6442	operation expires.
6443
6444	If the last known state of the medium is <link to="MediaState::Created"/>
6445	and the accessibility check fails then the state would be set to
6446	<link to="MediaState::Inaccessible"/> and <link to="#lastAccessError"/>
6447	may be used to get more details about the failure. If the state of the
6448	medium is <link to="MediaState::LockedRead"/> or
6449	<link to="MediaState::LockedWrite"/> then it remains the same, and a
6450	non-null value of <link to="#lastAccessError"/> will indicate a failed
6451	accessibility check in this case.
6452
6453	Note that not all media states are applicable to certain media types.
6454	For example, states <link to="MediaState::NotCreated"/>,
6455	<link to="MediaState::LockedWrite"/>, <link to="MediaState::Creating"/>,
6456	<link to="MediaState::Deleting"/> are meaningless for IDVDImage2 and
6457	IFloppyImage2 media.
6458	</desc>
6459	</attribute>
6460
6461	<attribute name="location" type="wstring">
6462	<desc>
6463	Location of the storage unit holding media data.
6464
6465	The format of the location string is media type specific. For media
6466	types that use regular files in a host's file system, the location
6467	string is just a full file name.
6468
6469	Some media types may support changing the storage unit location by
6470	simply changing the value of this property. If this operation is not
6471	supported, the implementation will return E_NOTIMPL in attempt to set
6472	this attribute's value.
6473
6474	When setting a value of the location attribute which is a regular file
6475	in the host's file system, the given file name may be either relative to
6476	the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
6477	absolute. Note that if the given location specification does not contain
6478	the file extension part then a proper default extension will be
6479	automatically appended by the implementation depending on the media type.
6480	</desc>
6481	</attribute>
6482
6483	<attribute name="name" type="wstring" readonly="yes">
6484	<desc>
6485	Name of the storage unit holding media data.
6486
6487	The returned string is a short version of the <link to="#location"/>
6488	attribute that is suitable for representing the medium in situations
6489	where the full location specification is too long (such as lists
6490	and comboboxes in GUI frontends). This string is also used by frontends
6491	to sort the media list alphabetically when needed.
6492
6493	For example, for locations that are regular files in the host's file
6494	system, the value of this attribute is just a file name (+ extension),
6495	without the path specification.
6496
6497	Note that as opposed to the <link to="#location"/> attribute, the name
6498	attribute will not necessary be unique for a list of media of the
6499	given type and format.
6500	</desc>
6501	</attribute>
6502
6503	<attribute name="size" type="unsigned long long" readonly="yes">
6504	<desc>
6505	Physical size of the storage unit used to hold media data (in bytes).
6506
6507	<note>
6508	For media whose <link to="#state"/> is <link
6509	to="MediaState::Inaccessible"/>, the value of this property is the
6510	last known size. For <link to="MediaState::NotCreated"/> media,
6511	the returned value is zero.
6512	</note>
6513	</desc>
6514	</attribute>
6515
6516	<attribute name="lastAccessError" type="wstring" readonly="yes">
6517	<desc>
6518	Text message that represents the result of the last accessibility
6519	check.
6520
6521	Accessibility checks are performed each time the <link to="#state"/>
6522	attribute is read. A @c null string is returned if the last
6523	accessibility check was successful. A non-null string indicates a
6524	failure and should normally describe a reason of the failure (for
6525	example, a file read error).
6526	</desc>
6527	</attribute>
6528
6529	<attribute name="machineIds" type="uuid" safearray="yes" readonly="yes">
6530	<desc>
6531	Array of UUIDs of all machines this medium is attached to.
6532
6533	A <tt>null</tt> array is returned if this medium is not attached to any
6534	machine or to any machine's snapshot.
6535
6536	<note>
6537	The returned array will include a machine even if this medium is not
6538	attached to that machine in the current state but attached to it in
6539	one of the machine's snapshots. See <link to="#getSnapshotIds()"/> for
6540	details.
6541	</note>
6542	</desc>
6543	</attribute>
6544
6545	<method name="getSnapshotIds">
6546	<desc>
6547	Returns an array of UUIDs of all snapshots of the given machine where
6548	this medium is attached to it.
6549
6550	If the medium is attached to the machine in the current state, then the
6551	first element in the array will always be the ID of the queried machine
6552	(i.e. the value equal to the @c machineId argument), followed by
6553	snapshot IDs (if any).
6554
6555	If the medium is not attached to the machine in the current state, then
6556	the array will contain only snapshot IDs.
6557
6558	The returned array may be <tt>null</tt> if this medium is not attached
6559	to the given machine at all, neither in the current state nor in one of
6560	snapshots.
6561	</desc>
6562	<param name="machineId" type="uuid" dir="in">
6563	<desc>
6564	UUID of the machine to query.
6565	</desc>
6566	</param>
6567	<param name="snapshotIds" type="uuid" safearray="yes" dir="return">
6568	<desc>
6569	Array of snapshot UUIDs of the given machine using this medium.
6570	</desc>
6571	</param>
6572	</method>
6573
6574	<method name="lockRead">
6575	<desc>
6576	Locks this medium for reading.
6577
6578	The read lock is shared: many clients can simultaneously lock the
6579	same media for reading unless it is already locked for writing (see
6580	<link to="#lockWrite()"/>) in which case an error is returned.
6581
6582	When the medium is locked for reading, it cannot be modified from within
6583	VirtualBox. This means that any method that changes the properties of
6584	this medium or contents of the storage unit will return an error (unless
6585	explicitly stated otherwise) and that an attempt to start a virtual
6586	machine that wants to modify the medium will also fail.
6587
6588	When the virtual machine is started up, it locks for reading all media
6589	it uses in read-only mode. If some media cannot be locked for reading,
6590	the startup procedure will fail.
6591
6592	The medium locked for reading must be unlocked using the
6593	<link to="#unlockRead()"/> method. Calls to <link to="#lockRead()"/> can
6594	be nested and must be followed by the same number of paired
6595	<link to="#unlockRead()"/> calls.
6596
6597	This method sets the media state to <link to="MediaState::LockedRead"/>
6598	on success. The state prior to this call must be
6599	<link to="MediaState::Created"/>,
6600	<link to="MediaState::Inaccessible"/> or
6601	<link to="MediaState::LockedRead"/>. As you can see, inaccessible media
6602	can be locked too. This is not an error; this method performs a logical
6603	lock that prevents modifications of this media through the VirtualBox
6604	API, not a physical lock of the underlying storage unit.
6605
6606	Either on success or on failure, this method returns the current state
6607	of the medium <b>before</b> the operation.
6608	</desc>
6609	<param name="state" type="MediaState" dir="return">
6610	<desc>
6611	State of the medium after the operation.
6612	</desc>
6613	</param>
6614	</method>
6615
6616	<method name="unlockRead">
6617	<desc>
6618	Cancels the read lock previously set by <link to="#lockRead()"/>.
6619
6620	Either on success or on failure, this method returns the current state
6621	of the medium <b>after</b> the operation.
6622
6623	See <link to="#lockRead()"/> for more details.
6624	</desc>
6625	<param name="state" type="MediaState" dir="return">
6626	<desc>
6627	State of the medium after the operation.
6628	</desc>
6629	</param>
6630	</method>
6631
6632	<method name="lockWrite">
6633	<desc>
6634	Locks this medium for writing.
6635
6636	The write lock, as opposed to <link to="#lockRead()"/>, is exclusive:
6637	there may be only one client that holds a write lock and there may be no
6638	read locks while the write lock is held.
6639
6640	When the medium is locked for writing, it cannot be modified from within
6641	VirtualBox and it is not guaranteed that the values of its properties
6642	are up-to-date. Any method that changes the properties of this medium or
6643	contents of the storage unit will return an error ((unless explicitly
6644	stated otherwise) and an attempt to start a virtual machine that wants
6645	to modify or to read the medium will also fail.
6646
6647	When the virtual machine is started up, it locks for writing all media
6648	it uses to write data to. If some media cannot be locked for writing,
6649	the startup procedure will fail.
6650
6651	The medium locked for writing must be unlocked using the
6652	<link to="#unlockWrite()"/> method. Calls to <link to="#lockWrite()"/>
6653	can <b>not</b> be nested and must be followed by a paired
6654	<link to="#unlockWrite()"/> call.
6655
6656	This method sets the media state to <link to="MediaState::LockedWrite"/>
6657	on success. The state prior to this call must be
6658	<link to="MediaState::Created"/> or
6659	<link to="MediaState::Inaccessible"/>. As you can see, inaccessible media
6660	can be locked too. This is not an error; this method performs a logical
6661	lock that prevents modifications of this media through the VirtualBox
6662	API, not a physical lock of the underlying storage unit.
6663
6664	Either on success or on failure, this method returns the current state
6665	of the medium <b>before</b> the operation.
6666	</desc>
6667	<param name="state" type="MediaState" dir="return">
6668	<desc>
6669	State of the medium after the operation.
6670	</desc>
6671	</param>
6672	</method>
6673
6674	<method name="unlockWrite">
6675	<desc>
6676	Cancels the write lock previously set by <link to="#lockWrite()"/>.
6677
6678	Either on success or on failure, this method returns the current state
6679	of the medium <b>after</b> the operation.
6680
6681	See <link to="#lockWrite()"/> for more details.
6682	</desc>
6683	<param name="state" type="MediaState" dir="return">
6684	<desc>
6685	State of the medium after the operation.
6686	</desc>
6687	</param>
6688	</method>
6689
6690	<method name="close">
6691	<desc>
6692	Closes this media.
6693
6694	The hard disk must not be attached to any known virtual machine and must
6695	not have any known child hard disks, otherwise the operation will fail.
6696
6697	When the hard disk is successfully closed, it gets removed from the list
6698	of remembered hard disks, but its storage unit is not deleted. In
6699	particular, this means that this hard disk can be later opened again
6700	using the <link to="IVirtualBox::openHardDisk2"/> call.
6701
6702	Note that after this method successfully returns, the given hard disk
6703	object becomes uninitialized. This means that any attempt to call any of
6704	its methods or attributes will fail with the <tt>"Object not ready"
6705	(E_ACCESSDENIED)</tt> error.
6706	</desc>
6707	</method>
6708
6709	</interface>
6710
6711
6712	<!--
6713	// IHardDisk2
6714	/////////////////////////////////////////////////////////////////////////
6715	-->
6716
6717	<enum
6718	name="HardDiskType"
6719	uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
6720	>
6721	<desc>
6722	Virtual hard disk type.
6723	<see>IHardDisk</see>
6724	</desc>
6725
6726	<const name="Normal" value="0">
6727	<desc>
6728	Normal hard disk (attached directly or indirectly, preserved
6729	when taking snapshots).
6730	</desc>
6731	</const>
6732	<const name="Immutable" value="1">
6733	<desc>
6734	Immutable hard disk (attached indirectly, changes are wiped out
6735	after powering off the virtual machine).
6736	</desc>
6737	</const>
6738	<const name="Writethrough" value="2">
6739	<desc>
6740	Write through hard disk (attached directly, ignored when
6741	taking snapshots).
6742	</desc>
6743	</const>
6744	</enum>
6745
6746	<interface
6747	name="IHardDisk2Attachment" extends="$unknown"
6748	uuid="fa2f4619-2c14-4090-869e-73b45419b7b5"
6749	wsmap="struct"
6750	>
6751	<desc>
6752	The IHardDisk2Attachment interface represents a hard disk attachment of a
6753	virtual machine.
6754
6755	Every hard disk attachment specifies a slot of the virtual hard disk
6756	controller and a virtual virtual hard disk attached to this slot.
6757
6758	The array of hard disk attachments is returned by
6759	<link to="IMachine::hardDisk2Attachments"/>.
6760
6761	<note>
6762	With the COM API, this is an interface like all the others. With the
6763	webservice, this is mapped to a structure, so querying the attribute
6764	will not return an object, but a complete structure.
6765	</note>
6766	</desc>
6767	<attribute name="hardDisk" type="IHardDisk2" readonly="yes">
6768	<desc>Hard disk object associated with this attachment.</desc>
6769	</attribute>
6770
6771	<attribute name="bus" type="StorageBus" readonly="yes">
6772	<desc>Interface bus of this attachment.</desc>
6773	</attribute>
6774
6775	<attribute name="channel" type="long" readonly="yes">
6776	<desc>Channel number of this attachment.</desc>
6777	</attribute>
6778
6779	<attribute name="device" type="long" readonly="yes">
6780	<desc>Device slot number of this attachment.</desc>
6781	</attribute>
6782
6783	</interface>
6784
6785	<interface
6786	name="IHardDisk2" extends="IMedium"
6787	uuid="4fece1c1-2a75-43ce-ba82-76d2a89b9d5d"
6788	wsmap="managed"
6789	>
6790	<desc>
6791	The IHardDisk2 interface represents a virtual hard disk drive
6792	used by a virtual machine.
6793
6794	Virtual hard disk objects virtualize the hard disk hardware and look like
6795	regular hard disks for the guest OS running inside the virtual machine.
6796
6797	<h3>Hard Disk Types</h3>
6798
6799	There are three types of hard disks:
6800	<link to="HardDiskType::Normal">Normal</link>,
6801	<link to="HardDiskType::Immutable">Immutable</link> and
6802	<link to="HardDiskType::Writethrough">Writethrough</link>. The type of the
6803	hard disk defines how the hard disk is attached to a virtual machine and
6804	what happens when a <link to="ISnapshot">snapshot</link> of the virtual
6805	machine with the attached hard disk is taken. The type of the hard disk is
6806	defined by the <link to="#type"/> attribute.
6807
6808	All hard disks can be also divided in two big groups: <i>base</i> hard
6809	disks and <i>differencing</i> hard disks. A base hard disk contains all
6810	sectors of the hard disk data in its storage unit and therefore can be
6811	used independently. On the contrary, a differencing hard disk contains
6812	only some part of the hard disk data (a subset of sectors) and needs
6813	another hard disk to get access to the missing sectors of data. This
6814	another hard disk is called a <i>parent</i> hard disk and defines a hard
6815	disk to which this differencing hard disk is known to be <i>linked to</i>.
6816	The parent hard disk may be itself a differencing hard disk. This
6817	way, differencing hard disks form a linked hard disk chain. This chain
6818	always ends with the base hard disk which is sometimes referred to as the
6819	root hard disk of this chain. Note that several differencing hard disks
6820	may be linked to the same parent hard disk. This way, all known hard disks
6821	form a hard disk tree which is based on their parent-child relationship.
6822
6823	Differencing hard disks can be distinguished from base hard disks by
6824	querying the <link to="#parent"/> attribute: base hard disks do not have
6825	parents they would depend on, so the value of this attribute is always
6826	<tt>null</tt> for them. Using this attribute, it is possible to walk up
6827	the hard disk tree (from the child hard disk to its parent). It is also
6828	possible to walk down the tree using the <link to="#children"/>
6829	attribute.
6830
6831	Note that the type of all differencing hard disks is
6832	<link to="HardDiskType::Normal">Normal</link>; all other values are
6833	meaningless for them. Base hard disks may be of any type.
6834
6835	<h3>Creating Hard Disks</h3>
6836
6837	New base hard disks are created using
6838	<link to="IVirtualBox::createHardDisk2()"/>. Existing hard disks are
6839	opened using <link to="IVirtualBox::openHardDisk2()"/>. Differencing hard
6840	disks are usually implicitly created by VirtualBox when needed but may
6841	also be created explicitly using <link to="#createDiffStorage()"/>.
6842
6843	After the hard disk is successfully created (including the storage unit)
6844	or opened, it becomes a known hard disk (remembered in the internal media
6845	registry). Known hard disks can be attached to a virtual machine, accessed
6846	through <link to="IVirtualBox::getHardDisk2()"/> and
6847	<link to="IVirtualBox::findHardDisk2()"/> methods or enumerated using the
6848	<link to="IVirtualBox::hardDisks2"/> array (only for base hard disks).
6849
6850	The following methods, besides <link to="IMedium::close()"/>,
6851	automatically remove the hard disk from the media registry:
6852	<ul>
6853	<li><link to="#deleteStorage()"/></li>
6854	<li><link to="#mergeTo()"/></li>
6855	</ul>
6856
6857	If the storage unit of the hard disk is a regular file in the host's
6858	file system then the rules stated in the description of the
6859	<link to="IMedium::location"/> attribute apply when setting its value. In
6860	addition, a plain file name without any path may be given, in which case
6861	the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
6862	folder</link> will be prepended to it.
6863
6864	<h4>Automatic composition of the file name part</h4>
6865
6866	Another extension to the <link to="IMedium::location"/> attribute is that
6867	there is a possibility to cause VirtualBox to compose a unique value for
6868	the file name part of the location using the UUID of the hard disk. This
6869	applies only to hard disks in <link to="MediaState::NotCreated"/> state,
6870	e.g. before the storage unit is created, and works as follows. You set the
6871	value of the <link to="IMedium::location"/> attribute to a location
6872	specification which only contains the path specification but not the file
6873	name part and ends with either a forward slash or a backslash character.
6874	In response, VirtualBox will generate a new UUID for the hard disk and
6875	compose the file name using the following pattern:
6876	<pre>
6877	<path>/{<uuid>}.<ext>
6878	</pre>
6879	where <tt><path></tt> is the supplied path specification,
6880	<tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
6881	is the default extension for the storage format of this hard disk. After
6882	that, you may call any of the methods that create a new hard disk storage
6883	unit and they will use the generated UUID and file name.
6884
6885	<h3>Attaching Hard Disks</h3>
6886
6887	Hard disks are attached to virtual machines using the
6888	<link to="IMachine::attachHardDisk2()"/> method and detached using the
6889	<link to="IMachine::detachHardDisk2()"/> method. Depending on their
6890	<link to="#type"/>, hard disks are attached either
6891	<i>directly</i> or <i>indirectly</i>.
6892
6893	When a hard disk is being attached directly, it is associated with the
6894	virtual machine and used for hard disk operations when the machine is
6895	running. When a hard disk is being attached indirectly, a new differencing
6896	hard disk linked to it is implicitly created and this differencing hard
6897	disk is associated with the machine and used for hard disk operations.
6898	This also means that if <link to="IMachine::attachHardDisk2()"/> performs
6899	a direct attachment then the same hard disk will be returned in response
6900	to the subsequent <link to="IMachine::getHardDisk2()"/> call; however if
6901	an indirect attachment is performed then
6902	<link to="IMachine::getHardDisk2()"/> will return the implicitly created
6903	differencing hard disk, not the original one passed to <link
6904	to="IMachine::attachHardDisk2()"/>. The following table shows the
6905	dependency of the attachment type on the hard disk type:
6906
6907	<table>
6908	<tr>
6909	<th>Hard Disk Type</th>
6910	<th>Direct or Indirect?</th>
6911	</tr>
6912	<tr>
6913	<td>Normal (Base)</td>
6914	<td>
6915	Normal base hard disks that do not have children (i.e. differencing
6916	hard disks linked to them) and that are not already attached to
6917	virtual machines in snapshots are attached <b>directly</b>.
6918	Otherwise, they are attached <b>indirectly</b> because having
6919	dependent children or being part of the snapshot makes it impossible
6920	to modify hard disk contents without breaking the integrity of the
6921	dependent party. The <link to="#readOnly"/> attribute allows to
6922	quickly determine the kind of the attachment for the given hard
6923	disk. Note that if a normal base hard disk is to be indirectly
6924	attached to a virtual machine with snapshots then a special
6925	procedure called <i>smart attachment</i> is performed (see below).
6926	</td>
6927	</tr>
6928	<tr>
6929	<td>Normal (Differencing)</td>
6930	<td>
6931	Differencing hard disks are like normal base hard disks: attached
6932	<b>directly</b> if they do not have children and are not attached to
6933	virtual machines in snapshots, and <b>indirectly</b> otherwise. Note
6934	that the smart attachment procedure is never performed for
6935	differencing hard disks.
6936	</td>
6937	</tr>
6938	<tr>
6939	<td>Immutable</td>
6940	<td>
6941	Immutable hard disks are always attached <b>indirectly</b> because
6942	they are designed to be non-writable. If an immutable hard disk is
6943	attached to a virtual machine with snapshots then a special
6944	procedure called smart attachment is performed (see below).
6945	</td>
6946	</tr>
6947	<tr>
6948	<td>Writethrough</td>
6949	<td>
6950	Writethrough hard disks are always attached <b>directly</b>, also as
6951	designed. This also means that writethrough hard disks cannot have
6952	other hard disks linked to them at all.
6953	</td>
6954	</tr>
6955	</table>
6956
6957	Note that the same hard disk, regardless of its type, may be attached to
6958	more than one virtual machine at a time. In this case, the machine that is
6959	started first gains exclusive access to the hard disk and attempts to
6960	start other machines having this hard disk attached will fail until the
6961	first machine is powered down.
6962
6963	Detaching hard disks is performed in a <i>deferred</i> fashion. This means
6964	that the given hard disk remains associated with the given machine after a
6965	successful <link to="IMachine::detachHardDisk2()"/> call until
6966	<link to="IMachine::saveSettings()"/> is called to save all changes to
6967	machine settings to disk. This deferring is necessary to guarantee that
6968	the hard disk configuration may be restored at any time by a call to
6969	<link to="IMachine::discardSettings()"/> before the settings
6970	are saved (committed).
6971
6972	Note that if <link to="IMachine::discardSettings()"/> is called after
6973	indirectly attaching some hard disks to the machine but before a call to
6974	<link to="IMachine::saveSettings()"/> is made, it will implicitly delete
6975	all differencing hard disks implicitly created by
6976	<link to="IMachine::attachHardDisk2()"/> for these indirect attachments.
6977	Such implicitly created hard disks will also be immediately deleted when
6978	detached explicitly using the <link to="IMachine::detachHardDisk2()"/>
6979	call if it is made before <link to="IMachine::saveSettings()"/>. This
6980	implicit deletion is safe because newly created differencing hard
6981	disks do not contain any user data.
6982
6983	However, keep in mind that detaching differencing hard disks that were
6984	implicitly created by <link to="IMachine::attachHardDisk2()"/>
6985	before the last <link to="IMachine::saveSettings()"/> call will
6986	<b>not</b> implicitly delete them as they may already contain some data
6987	(for example, as a result of virtual machine execution). If these hard
6988	disks are no more necessary, the caller can always delete them explicitly
6989	using <link to="#deleteStorage()"/> after they are actually de-associated
6990	from this machine by the <link to="IMachine::saveSettings()"/> call.
6991
6992	<h3>Smart Attachment</h3>
6993
6994	When normal base or immutable hard disks are indirectly attached to a
6995	virtual machine then some additional steps are performed to make sure the
6996	virtual machine will have the most recent "view" of the hard disk being
6997	attached. These steps include walking through the machine's snapshots
6998	starting from the current one and going through ancestors up to the first
6999	snapshot. Hard disks attached to the virtual machine in all
7000	of the encountered snapshots are checked whether they are descendants of
7001	the given normal base or immutable hard disk. The first found child (which
7002	is the differencing hard disk) will be used instead of the normal base or
7003	immutable hard disk as a parent for creating a new differencing hard disk
7004	that will be actually attached to the machine. And only if no descendants
7005	are found or if the virtual machine does not have any snapshots then the
7006	normal base or immutable hard disk will be used itself as a parent for
7007	this differencing hard disk.
7008
7009	It is easier to explain what smart attachment does using the
7010	following example:
7011	<pre>
7012	BEFORE attaching B.vdi: AFTER attaching B.vdi:
7013
7014	Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
7015	Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
7016	Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
7017	Snapshot 4 (none) Snapshot 4 (none)
7018	CurState (none) CurState (D3->D2.vdi)
7019
7020	NOT
7021	...
7022	CurState (D3->B.vdi)
7023	</pre>
7024	The first column is the virtual machine configuration before the base hard
7025	disk <tt>B.vdi</tt> is attached, the second column shows the machine after
7026	this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
7027	mean that the hard disk that is actually attached to the machine is a
7028	differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
7029	another hard disk, <tt>B.vdi</tt>.
7030
7031	As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
7032	from the machine before taking Snapshot 4. Later, after Snapshot 4 was
7033	taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
7034	dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
7035	it cannot be attached directly and needs an indirect attachment (i.e.
7036	implicit creation of a new differencing hard disk). Due to the smart
7037	attachment procedure, the new differencing hard disk
7038	(<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
7039	<tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
7040	<tt>B.vdi</tt> existing for this snapshot branch of the given virtual
7041	machine.
7042
7043	Note that if there is more than one descendant hard disk of the given base
7044	hard disk found in a snapshot, and there is an exact device, channel and
7045	bus match, then this exact match will be used. Otherwise, the youngest
7046	descendant will be picked up.
7047
7048	There is one more important aspect of the smart attachment procedure which
7049	is not related to snapshots at all. Before walking through the snapshots
7050	as described above, the backup copy of the current list of hard disk
7051	attachment is searched for descendants. This backup copy is created when
7052	the hard disk configuration is changed for the first time after the last
7053	<link to="IMachine::saveSettings()"/> call and used by
7054	<link to="IMachine::discardSettings()"/> to undo the recent hard disk
7055	changes. When such a descendant is found in this backup copy, it will be
7056	simply re-attached back, without creating a new differencing hard disk for
7057	it. This optimization is necessary to make it possible to re-attach the
7058	base or immutable hard disk to a different bus, channel or device slot
7059	without losing the contents of the differencing hard disk actually
7060	attached to the machine in place of it.
7061	</desc>
7062
7063	<attribute name="format" type="wstring" readonly="yes">
7064	<desc>
7065	Storage format of this hard disk.
7066
7067	The value of this attribute is a string that specifies a backend used to
7068	store hard disk data. The storage format is defined when you create a
7069	new hard disk or automatically detected when you open an existing hard
7070	disk medium, and cannot be changed later.
7071
7072	The list of all storage formats supported by this VirtualBox
7073	installation can be obtained using
7074	<link to="ISystemProperties::hardDiskFormats"/>.
7075	</desc>
7076	</attribute>
7077
7078	<attribute name="type" type="HardDiskType">
7079	<desc>
7080	Type (role) of this hard disk.
7081
7082	The following constraints apply when changing the value of this
7083	attribute:
7084	<ul>
7085	<li>If a hard disk is attached to a virtual machine (either in the
7086	current state or in one of the snapshots), its type cannot be
7087	changed.
7088	</li>
7089	<li>As long as the hard disk has children, its type cannot be set
7090	to <link to="HardDiskType::Writethrough"/>.
7091	</li>
7092	<li>The type of all differencing hard disks is
7093	<link to="HardDiskType::Normal"/> and cannot be changed.
7094	</li>
7095	</ul>
7096
7097	The type of a newly created or opened hard disk is set to
7098	<link to="HardDiskType::Normal"/>.
7099	</desc>
7100	</attribute>
7101
7102	<attribute name="parent" type="IHardDisk2" readonly="yes">
7103	<desc>
7104	Parent of this hard disk (a hard disk this hard disk is directly based
7105	on).
7106
7107	Only differencing hard disks have parents. For base (non-differencing)
7108	hard disks, <tt>null</tt> is returned.
7109	</desc>
7110	</attribute>
7111
7112	<attribute name="children" type="IHardDisk2" safearray="yes" readonly="yes">
7113	<desc>
7114	Children of this hard disk (all differencing hard disks directly based
7115	on this hard disk). A <tt>null</tt> array is returned if this hard disk
7116	does not have any children.
7117	</desc>
7118	</attribute>
7119
7120	<attribute name="root" type="IHardDisk2" readonly="yes">
7121	<desc>
7122	Root hard disk of this hard disk.
7123
7124	If this is a differencing hard disk, its root hard disk is the base hard
7125	disk the given hard disk branch starts from. For all other types of hard
7126	disks, this property returns the hard disk object itself (i.e. the same
7127	object this property is read on).
7128	</desc>
7129	</attribute>
7130
7131	<attribute name="readOnly" type="boolean" readonly="yes">
7132	<desc>
7133	Returns <tt>true</tt> if this hard disk is read-only and <tt>false</tt>
7134	otherwise.
7135
7136	A hard disk is considered to be read-only when its contents cannot be
7137	modified without breaking the integrity of other parties that depend on
7138	this hard disk such as its child hard disks or snapshots of virtual
7139	machines where this hard disk is attached to these machines. If there
7140	are no children and no such snapshots then there is no dependency and
7141	the hard disk is not read-only.
7142
7143	The value of this attribute can be used to determine the kind of the
7144	attachment that will take place when attaching this hard disk to a
7145	virtual machine. If the value is <tt>false</tt> then the hard disk will
7146	be attached directly. If the value is <tt>true</tt> then the hard disk
7147	will be attached indirectly by creating a new differencing child hard
7148	disk for that. See the interface description for more information.
7149
7150	Note that all <link to="HardDiskType::Immutable">Immutable</link> hard
7151	disks are always read-only while all
7152	<link to="HardDiskType::Writethrough">Writethrough</link> hard disks are
7153	always not.
7154
7155	<note>
7156	The read-only condition represented by this attribute is related to
7157	the hard disk type and usage, not to the current
7158	<link to="IMedium::state">media state</link> and not to the read-only
7159	state of the storage unit.
7160	</note>
7161	</desc>
7162	</attribute>
7163
7164	<attribute name="logicalSize" type="unsigned long long" readonly="yes">
7165	<desc>
7166	Logical size of this hard disk (in megabytes), as reported to the
7167	guest OS running inside the virtual machine this disk is
7168	attached to. The logical size is defined when the hard disk is created
7169	and cannot be changed later.
7170
7171	<note>
7172	Reading this property on a differencing hard disk will return the size
7173	of its <link to="#root"/> hard disk.
7174	</note>
7175	<note>
7176	For hard disks whose state is <link to="#state"/> is <link
7177	to="MediaState::Inaccessible"/>, the value of this property is the
7178	last known logical size. For <link to="MediaState::NotCreated"/> hard
7179	disks, the returned value is zero.
7180	</note>
7181	</desc>
7182	</attribute>
7183
7184	<!-- storage methods -->
7185
7186	<method name="getProperty">
7187	<desc>
7188	Returns the value of the custom hard disk property with the given name.
7189
7190	The list of all properties supported by the given hard disk format can
7191	be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
7192
7193	Note that if this method returns a <tt>null</tt> @a value, the requested
7194	property is supported but currently not assigned any value.
7195
7196	<result name="VBOX_E_OBJECT_NOT_FOUND">
7197	Requested property does not exist (not supported by the format).
7198	</result>
7199	<result name="E_INVALIDARG">@a name is NULL or empty.</result>
7200	<result name="E_POINTER">@a value points to invalid memory.</result>
7201	</desc>
7202	<param name="name" type="wstring" dir="in">
7203	<desc>Name of the property to get.</desc>
7204	</param>
7205	<param name="value" type="wstring" dir="return">
7206	<desc>Current property value.</desc>
7207	</param>
7208	</method>
7209
7210	<method name="setProperty">
7211	<desc>
7212	Sets the value of the custom hard disk property with the given name.
7213
7214	The list of all properties supported by the given hard disk format can
7215	be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
7216
7217	Note that passing <tt>null</tt> as @a value will reset the value of the
7218	property to nothing which may also be understood as deleting the
7219	property's value. For properties with no values, the format backend will
7220	use a default value if such a value is defined for the given property.
7221
7222	<result name="VBOX_E_OBJECT_NOT_FOUND">
7223	Requested property does not exist (not supported by the format).
7224	</result>
7225	<result name="E_INVALIDARG">@a name is NULL or empty.</result>
7226	</desc>
7227	<param name="name" type="wstring" dir="in">
7228	<desc>Name of the property to set.</desc>
7229	</param>
7230	<param name="value" type="wstring" dir="in">
7231	<desc>Property value to set.</desc>
7232	</param>
7233	</method>
7234
7235	<method name="getProperties">
7236	<desc>
7237	Returns values for a group of properties in one call.
7238
7239	The names of the properties to get are specified using the @a names
7240	argument which is a list of comma-separated property names or
7241	<tt>null</tt> if all properties are to be returned. Note that currently
7242	the value of this argument is ignored and the method always returns all
7243	existing properties.
7244
7245	The list of all properties supported by the given hard disk format can
7246	be obtained with <link to="IHardDiskFormat::describeProperties()"/>.
7247
7248	The method returns two arrays, the array of property names corresponding
7249	to the @a names argument and the current values of these properties.
7250	<!-- FIXME: Both arrays [sentence was cut off here. Complete. -->
7251
7252	Note that for properties that don't have values assigned to them,
7253	<tt>null</tt> is returned at the appropriate index in the @a returnValues
7254	array.
7255
7256	<result name="E_POINTER">@a returnNames or @a returnValues points to
7257	invalid memory.
7258	</result>
7259	<result name="E_ACCESSDENIED">Access to object is denied.</result>
7260	</desc>
7261	<param name="names" type="wstring" dir="in">
7262	<desc>
7263	Names of properties to get.
7264	</desc>
7265	</param>
7266	<param name="returnNames" type="wstring" safearray="yes" dir="out">
7267	<desc>Names of returned properties.</desc>
7268	</param>
7269	<param name="returnValues" type="wstring" safearray="yes" dir="return">
7270	<desc>Values of returned properties.</desc>
7271	</param>
7272	</method>
7273
7274	<!-- storage methods -->
7275
7276	<method name="createDynamicStorage">
7277	<desc>
7278	Starts creating a dynamically expanding hard disk storage unit in the
7279	background. The previous storage unit created for this this object, if
7280	any, must be first deleted using <link to="#deleteStorage"/>, otherwise
7281	the operation will fail.
7282
7283	Before the operation starts, the hard disk is placed to
7284	<link to="MediaState::Creating"/> state. If the create operation
7285	fails, the media will placed back to <link to="MediaState::NotCreated"/>
7286	state.
7287
7288	After the returned progress object reports that the operation is
7289	successfully complete, the media state will be set to <link
7290	to="MediaState::Created"/>, the hard disk will be remembered by this
7291	VirtualBox installation and may be attached to virtual machines.
7292	</desc>
7293	<param name="logicalSize" type="unsigned long long" dir="in">
7294	<desc>Maximum logical size of the hard disk in megabytes.</desc>
7295	</param>
7296	<param name="progress" type="IProgress" dir="return">
7297	<desc>Progress object to track the operation completion.</desc>
7298	</param>
7299	</method>
7300
7301	<method name="createFixedStorage">
7302	<desc>
7303	Starts creating a fixed-size hard disk storage unit in the background.
7304	The previous storage unit created for this this object, if
7305	any, must be first deleted using <link to="#deleteStorage"/>, otherwise
7306	the operation will fail.
7307
7308	Before the operation starts, the hard disk is placed to
7309	<link to="MediaState::Creating"/> state. If the create operation
7310	fails, the media will placed back to <link to="MediaState::NotCreated"/>
7311	state.
7312
7313	After the returned progress object reports that the operation is
7314	successfully complete, the media state will be set to <link
7315	to="MediaState::Created"/>, the hard disk will be remembered by this
7316	VirtualBox installation and may be attached to virtual machines.
7317	</desc>
7318	<param name="logicalSize" type="unsigned long long" dir="in">
7319	<desc>Logical size of the hard disk in megabytes.</desc>
7320	</param>
7321	<param name="progress" type="IProgress" dir="return">
7322	<desc>Progress object to track the operation completion.</desc>
7323	</param>
7324	</method>
7325
7326	<method name="deleteStorage">
7327	<desc>
7328	Starts deleting the storage unit of this hard disk.
7329
7330	The hard disk must not be attached to any known virtual machine and must
7331	not have any known child hard disks, otherwise the operation will fail.
7332	It will also fail if there is no storage unit to delete or if deletion
7333	is already in progress, or if the hard disk is being in use (locked for
7334	read or for write) or inaccessible. Therefore, the only valid state for
7335	this operation to succeed is <link to="MediaState::Created"/>.
7336
7337	Before the operation starts, the hard disk is placed to
7338	<link to="MediaState::Deleting"/> state and gets removed from the list
7339	of remembered hard disks (media registry). If the delete operation
7340	fails, the media will be remembered again and placed back to
7341	<link to="MediaState::Created"/> state.
7342
7343	After the returned progress object reports that the operation is
7344	complete, the media state will be set to
7345	<link to="MediaState::NotCreated"/> and you will be able to use one of
7346	the storage creation methods to create it again.
7347
7348	<see>#close()</see>
7349	</desc>
7350	<param name="progress" type="IProgress" dir="return">
7351	<desc>Progress object to track the operation completion.</desc>
7352	</param>
7353	</method>
7354
7355	<!-- diff methods -->
7356
7357	<method name="createDiffStorage">
7358	<desc>
7359	Starts creating an empty differencing storage unit based on this hard
7360	disk in the format and at the location defined by the @a target
7361	argument.
7362
7363	The target hard disk must be in <link to="MediaState::NotCreated"/>
7364	state (i.e. must not have an existing storage unit). Upon successful
7365	completion, this operation will set the type of the target hard disk to
7366	<link to="HardDiskType::Normal"/> and create a storage unit necessary to
7367	represent the differencing hard disk data in the given format (according
7368	to the storage format of the target object).
7369
7370	After the returned progress object reports that the operation is
7371	successfully complete, the target hard disk gets remembered by this
7372	VirtualBox installation and may be attached to virtual machines.
7373
7374	<note>
7375	The hard disk will be placed to <link to="MediaState::LockedRead"/>
7376	state for the duration of this operation.
7377	</note>
7378	</desc> <param name="target" type="IHardDisk2" dir="in">
7379	<desc>Target hard disk.</desc>
7380	</param>
7381	<param name="progress" type="IProgress" dir="return">
7382	<desc>Progress object to track the operation completion.</desc>
7383	</param>
7384	</method>
7385
7386	<method name="mergeTo">
7387	<desc>
7388	Starts merging the contents of this hard disk and all intermediate
7389	differencing hard disks in the chain to the given target hard disk.
7390
7391	The target hard disk must be either a descendant of this hard disk or
7392	its ancestor (otherwise this method will immediately return a failure).
7393	It follows that there are two logical directions of the merge operation:
7394	from ancestor to descendant (<i>forward merge</i>) and from descendant to
7395	ancestor (<i>backward merge</i>). Let us consider the following hard disk
7396	chain:
7397
7398	<pre>Base <- Diff_1 <- Diff_2</pre>
7399
7400	Here, calling this method on the <tt>Base</tt> hard disk object with
7401	<tt>Diff_2</tt> as an argument will be a forward merge; calling it on
7402	<tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
7403	merge. Note that in both cases the contents of the resulting hard disk
7404	will be the same, the only difference is the hard disk object that takes
7405	the result of the merge operation. In case of the forward merge in the
7406	above example, the result will be written to <tt>Diff_2</tt>; in case of
7407	the backward merge, the result will be written to <tt>Base</tt>. In
7408	other words, the result of the operation is always stored in the target
7409	hard disk.
7410
7411	Upon successful operation completion, the storage units of all hard
7412	disks in the chain between this (source) hard disk and the target hard
7413	disk, including the source hard disk itself, will be automatically
7414	deleted and the relevant hard disk objects (including this hard disk)
7415	will become uninitialized. This means that any attempt to call any of
7416	their methods or attributes will fail with the
7417	<tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
7418	example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
7419	delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
7420	disks. Note that <tt>Diff_2</tt> in this case will become a base hard
7421	disk itself since it will no longer be based on any other hard disk.
7422
7423	Considering the above, all of the following conditions must be met in
7424	order for the merge operation to succeed:
7425	<ul>
7426	<li>
7427	Neither this (source) hard disk nor any intermediate
7428	differencing hard disk in the chain between it and the target
7429	hard disk is attached to any virtual machine.
7430	</li>
7431	<li>
7432	Neither the source hard disk nor the target hard disk is an
7433	<link to="HardDiskType::Immutable"/> hard disk.
7434	</li>
7435	<li>
7436	The part of the hard disk tree from the source hard disk to the
7437	target hard disk is a linear chain, i.e. all hard disks in this
7438	chain have exactly one child which is the next hard disk in this
7439	chain. The only exception from this rule is the target hard disk in
7440	the forward merge operation; it is allowed to have any number of
7441	child hard disks because the merge operation will hot change its
7442	logical contents (as it is seen by the guest OS or by children).
7443	</li>
7444	<li>
7445	None of the involved hard disks are in
7446	<link to="MediaState::LockedRead"/> or
7447	<link to="MediaState::LockedWrite"/> state.
7448	</li>
7449	</ul>
7450
7451	<note>
7452	This (source) hard disk and all intermediates will be placed to <link
7453	to="MediaState::Deleting"/> state and the target hard disk will be
7454	placed to <link to="MediaState::LockedWrite"/> state and for the
7455	duration of this operation.
7456	</note>
7457	</desc>
7458	<param name="targetId" type="uuid" dir="in">
7459	<desc>UUID of the target ancestor or descendant hard disk.</desc>
7460	</param>
7461	<param name="progress" type="IProgress" dir="return">
7462	<desc>Progress object to track the operation completion.</desc>
7463	</param>
7464	</method>
7465
7466	<!-- clone methods -->
7467
7468	<method name="cloneTo">
7469	<desc>
7470	Starts creating a clone of this hard disk in the format and at the
7471	location defined by the @a target argument.
7472
7473	The target hard disk must be in <link to="MediaState::NotCreated"/>
7474	state (i.e. must not have an existing storage unit). Upon successful
7475	completion, the cloned hard disk will contain exactly the same sector
7476	data as the hard disk being cloned, except that a new UUID for the clone
7477	will be randomly generated.
7478
7479	After the returned progress object reports that the operation is
7480	successfully complete, the target hard disk gets remembered by this
7481	VirtualBox installation and may be attached to virtual machines.
7482
7483	<note>
7484	If the cloned hard disk is a differencing hard disk, it will inherit
7485	parent dependency of the original hard disk.
7486	</note>
7487	<note>
7488	This hard disk will be placed to <link to="MediaState::LockedRead"/>
7489	state for the duration of this operation.
7490	</note>
7491	</desc>
7492	<param name="target" type="IHardDisk2" dir="in">
7493	<desc>Target hard disk.</desc>
7494	</param>
7495	<param name="progress" type="IProgress" dir="return">
7496	<desc>Progress object to track the operation completion.</desc>
7497	</param>
7498	</method>
7499
7500	<method name="flattenTo">
7501	<desc>
7502	Starts creating a deep (independent) clone of this hard disk in the
7503	format and at the location defined by the @a target argument.
7504
7505	This operation is similar to <link to="#cloneTo()"/> except that when
7506	applied to a differencing hard disk, it will also copy missing hard disk
7507	data from all parent hard disks it is linked to. This will make the
7508	created clone an independent base hard disk that contains all hard disk
7509	data and does not need any other hard disks to operate.
7510
7511	After the returned progress object reports that the operation is
7512	successfully complete, the target hard disk gets remembered by this
7513	VirtualBox installation and may be attached to virtual machines.
7514
7515	<note>
7516	For base hard disks, this operation is identical to
7517	<link to="#cloneTo()"/>.
7518	</note>
7519	<note>
7520	This hard disk and all its parent hard disks will be placed to <link
7521	to="MediaState::LockedRead"/> state for the duration of this
7522	operation.
7523	</note>
7524	</desc>
7525	<param name="target" type="IHardDisk2" dir="in">
7526	<desc>Target hard disk.</desc>
7527	</param>
7528	<param name="progress" type="IProgress" dir="return">
7529	<desc>Progress object to track the operation completion.</desc>
7530	</param>
7531	</method>
7532
7533	</interface>
7534
7535
7536	<!--
7537	// IHardDiskFormat
7538	/////////////////////////////////////////////////////////////////////////
7539	-->
7540
7541	<enum
7542	name="DataType"
7543	uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
7544	>
7545	<const name="Int32" value="0"/>
7546	<const name="Int8" value="1"/>
7547	<const name="String" value="2"/>
7548	</enum>
7549
7550	<enum
7551	name="DataFlags"
7552	uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
7553	>
7554	<const name="None" value="0x00"/>
7555	<const name="Mandatory" value="0x01"/>
7556	<const name="Expert" value="0x02"/>
7557	<const name="Array" value="0x04"/>
7558	<const name="FlagMask" value="0x07"/>
7559	</enum>
7560
7561	<enum
7562	name="HardDiskFormatCapabilities"
7563	uuid="1df1e4aa-d25a-4ba6-b2a2-02f60eb5903b"
7564	>
7565	<desc>
7566	Hard disk format capability flags.
7567	</desc>
7568
7569	<const name="Uuid" value="0x01">
7570	<desc>
7571	Supports UUIDs as expected by VirtualBox code.
7572	</desc>
7573	</const>
7574
7575	<const name="CreateFixed" value="0x02">
7576	<desc>
7577	Supports creating fixed size images, allocating all space instantly.
7578	</desc>
7579	</const>
7580
7581	<const name="CreateDynamic" value="0x04">
7582	<desc>
7583	Supports creating dynamically growing images, allocating space on
7584	demand.
7585	</desc>
7586	</const>
7587
7588	<const name="CreateSplit2G" value="0x08">
7589	<desc>
7590	Supports creating images split in chunks of a bit less than 2 GBytes.
7591	</desc>
7592	</const>
7593
7594	<const name="Differencing" value="0x10">
7595	<desc>
7596	Supports being used as a format for differencing hard disks (see <link
7597	to="IHardDisk2::createDiffStorage"/>).
7598	</desc>
7599	</const>
7600
7601	<const name="Asynchronous" value="0x20">
7602	<desc>
7603	Supports asynchronous I/O operations for at least some configurations.
7604	</desc>
7605	</const>
7606
7607	<const name="File" value="0x40">
7608	<desc>
7609	The format backend operates on files. The <link to="IMedium::location"/>
7610	attribute of the hard disk specifies a file used to store hard disk
7611	data. For a list of supported file extensions see
7612	<link to="IHardDiskFormat::fileExtensions"/>.
7613	</desc>
7614	</const>
7615
7616	<const name="Properties" value="0x80">
7617	<desc>
7618	The format backend uses the property interface to configure the storage
7619	location and properties. The <link to="IHardDiskFormat::describeProperties"/>
7620	method is used to get access to properties supported by the given hard
7621	disk format.
7622	</desc>
7623	</const>
7624
7625	<const name="CapabilityMask" value="0xFF"/>
7626	</enum>
7627
7628	<interface
7629	name="IHardDiskFormat" extends="$unknown"
7630	uuid="7f3ba790-3a0b-4a8a-bac2-bb50150123c5"
7631	wsmap="managed"
7632	>
7633	<desc>
7634	The IHardDiskFormat interface represents a virtual hard disk format.
7635
7636	Each hard disk format has an associated backend which is used to handle
7637	hard disks stored in this format. This interface provides information
7638	about the properties of the associated backend.
7639
7640	Each hard disk format is identified by a string represented by the
7641	<link to="#id"/> attribute. This string is used in calls like
7642	<link to="IVirtualBox::createHardDisk2()"/> to specify the desired
7643	format.
7644
7645	The list of all supported hard disk formats can be obtained using
7646	<link to="ISystemProperties::hardDiskFormats"/>.
7647
7648	<see>IHardDisk2</see>
7649	</desc>
7650
7651	<attribute name="id" type="wstring" readonly="yes">
7652	<desc>
7653	Identifier of this format.
7654
7655	This string is used in methods of other interfaces where it is necessary
7656	to specify a hard disk format, such as
7657	<link to="IVirtualBox::createHardDisk2()"/>.
7658	</desc>
7659	</attribute>
7660
7661	<attribute name="name" type="wstring" readonly="yes">
7662	<desc>
7663	Human readable description of this format.
7664
7665	Mainly for use in file open dialogs.
7666	</desc>
7667	</attribute>
7668
7669	<attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
7670	<desc>
7671	Array of strings containing the supported file extensions.
7672
7673	The first extension in the array is the extension preferred by the
7674	backend. It is recommended to use this extension when specifying a
7675	location of the storage unit for a new hard disk.
7676
7677	Note that some backends do not work on files, so this array may be
7678	empty.
7679
7680	<see>IHardDiskFormat::capabilities</see>
7681	</desc>
7682	</attribute>
7683
7684	<attribute name="capabilities" type="unsigned long" readonly="yes">
7685	<desc>
7686	Capabilities of the format as a set of bit flags.
7687
7688	For the meaning of individual capability flags see
7689	<link to="HardDiskFormatCapabilities"/>.
7690	</desc>
7691	</attribute>
7692
7693	<method name="describeProperties">
7694	<desc>
7695	Returns several arrays describing the properties supported by this
7696	format.
7697
7698	An element with the given index in each array describes one
7699	property. Thus, the number of elements in each returned array is the
7700	same and corresponds to the number of supported properties.
7701
7702	The returned arrays are not empty only if the
7703	<link to="HardDiskFormatCapabilities::Properties"/> flag is set.
7704
7705	<see>DataType</see>
7706	<see>DataFlags</see>
7707	</desc>
7708
7709	<param name="names" type="wstring" safearray="yes" dir="out">
7710	<desc>Array of property names.</desc>
7711	</param>
7712	<param name="description" type="wstring" safearray="yes" dir="out">
7713	<desc>Array of property descriptions.</desc>
7714	</param>
7715	<param name="types" type="DataType" safearray="yes" dir="out">
7716	<desc>Array of property types.</desc>
7717	</param>
7718	<param name="flags" type="unsigned long" safearray="yes" dir="out">
7719	<desc>Array of property flags.</desc>
7720	</param>
7721	<param name="defaults" type="wstring" safearray="yes" dir="out">
7722	<desc>Array of default property values.</desc>
7723	</param>
7724	</method>
7725
7726	</interface>
7727
7728
7729	<!--
7730	// IFloppyImage2
7731	/////////////////////////////////////////////////////////////////////////
7732	-->
7733
7734	<interface
7735	name="IFloppyImage2" extends="IMedium"
7736	uuid="fcdee8f0-03f9-11dd-95ff-0800200c9a66"
7737	wsmap="managed"
7738	>
7739	<desc>
7740	The IFloppyImage2 interface represents a medium containing the image
7741	of a floppy disk.
7742	</desc>
7743
7744	</interface>
7745
7746
7747	<!--
7748	// IDVDImage2
7749	/////////////////////////////////////////////////////////////////////////
7750	-->
7751
7752	<interface
7753	name="IDVDImage2" extends="IMedium"
7754	uuid="1c5165f1-9543-478d-a117-84a1d2317068"
7755	wsmap="managed"
7756	>
7757	<desc>
7758	The IDVDImage2 interface represents a medium containing the image
7759	of a CD or DVD disk in the ISO format.
7760	</desc>
7761
7762	</interface>
7763
7764
7765	<!--
7766	// IDVDDrive
7767	/////////////////////////////////////////////////////////////////////////
7768	-->
7769
7770	<interface
7771	name="IDVDDrive" extends="$unknown"
7772	uuid="d650ef30-be9b-4dae-b463-11d5824681a5"
7773	wsmap="managed"
7774	>
7775	<desc>
7776	The IDVDDrive interface represents the virtual CD/DVD drive of the
7777	virtual machine. An object of this type is returned by
7778	<link to="IMachine::DVDDrive"/>.
7779	</desc>
7780
7781	<attribute name="state" type="DriveState" readonly="yes">
7782	<desc>Current drive state.</desc>
7783	</attribute>
7784
7785	<attribute name="passthrough" type="boolean">
7786	<desc>
7787	When a host drive is mounted and passthrough is enabled
7788	the guest OS will be able to directly send SCSI commands to
7789	the host drive. This enables the guest OS to use CD/DVD writers
7790	but is potentially dangerous.
7791	</desc>
7792	</attribute>
7793
7794	<method name="mountImage">
7795	<desc>Mounts a CD/DVD image with the specified UUID.</desc>
7796	<param name="imageId" type="uuid" dir="in"/>
7797	</method>
7798
7799	<method name="captureHostDrive">
7800	<desc>Captures the specified host CD/DVD drive.</desc>
7801	<param name="drive" type="IHostDVDDrive" dir="in"/>
7802	</method>
7803
7804	<method name="unmount">
7805	<desc>Unmounts the currently mounted image or host drive.</desc>
7806	</method>
7807
7808	<method name="getImage">
7809	<desc>Returns the currently mounted CD/DVD image.</desc>
7810	<param name="image" type="IDVDImage2" dir="return"/>
7811	</method>
7812
7813	<method name="getHostDrive">
7814	<desc>Returns the currently mounted host CD/DVD drive.</desc>
7815	<param name="drive" type="IHostDVDDrive" dir="return"/>
7816	</method>
7817
7818	</interface>
7819
7820
7821	<!--
7822	// IFloppyDrive
7823	/////////////////////////////////////////////////////////////////////////
7824	-->
7825
7826	<interface
7827	name="IFloppyDrive" extends="$unknown"
7828	uuid="159412cd-bab8-452e-8097-218a020825a6"
7829	wsmap="managed"
7830	>
7831	<desc>
7832	The IFloppyDrive interface represents the virtual floppy drive of the
7833	virtual machine. An object of this type is returned by
7834	<link to="IMachine::floppyDrive" />.
7835	</desc>
7836
7837	<attribute name="enabled" type="boolean">
7838	<desc>
7839	Flag whether the floppy drive is enabled. If it is disabled,
7840	the floppy drive will not be reported to the guest OS.
7841	</desc>
7842	</attribute>
7843
7844	<attribute name="state" type="DriveState" readonly="yes">
7845	<desc>Current drive state.</desc>
7846	</attribute>
7847
7848	<method name="mountImage">
7849	<desc>Mounts a floppy image with the specified UUID.</desc>
7850	<param name="imageId" type="uuid" dir="in"/>
7851	</method>
7852
7853	<method name="captureHostDrive">
7854	<desc>Captures the specified host floppy drive.</desc>
7855	<param name="drive" type="IHostFloppyDrive" dir="in"/>
7856	</method>
7857
7858	<method name="unmount">
7859	<desc>Unmounts the currently mounted image or host drive.</desc>
7860	</method>
7861
7862	<method name="getImage">
7863	<desc>Returns the currently mounted floppy image.</desc>
7864	<param name="image" type="IFloppyImage2" dir="return"/>
7865	</method>
7866
7867	<method name="getHostDrive">
7868	<desc>Returns the currently mounted host floppy drive.</desc>
7869	<param name="drive" type="IHostFloppyDrive" dir="return"/>
7870	</method>
7871
7872	</interface>
7873
7874
7875	<!--
7876	// IKeyboard
7877	/////////////////////////////////////////////////////////////////////////
7878	-->
7879
7880	<interface
7881	name="IKeyboard" extends="$unknown"
7882	uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
7883	wsmap="managed"
7884	>
7885	<desc>
7886	The IKeyboard interface represents the virtual machine's keyboard. Used
7887	in <link to="IConsole::keyboard"/>.
7888
7889	Through this interface, the virtual machine's virtual keyboard can be controlled. One
7890	can send keystrokes to the virtual machine and send the Ctrl-Alt-Del sequence to it.
7891	</desc>
7892	<method name="putScancode">
7893	<desc>Sends a scancode to the keyboard.</desc>
7894	<param name="scancode" type="long" dir="in"/>
7895	</method>
7896
7897	<method name="putScancodes">
7898	<desc>Sends an array of scancode to the keyboard.</desc>
7899	<param name="scancodes" type="long" dir="in" safearray="yes"/>
7900	<param name="codesStored" type="unsigned long" dir="return"/>
7901	</method>
7902
7903	<method name="putCAD">
7904	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
7905	</method>
7906
7907	</interface>
7908
7909
7910	<!--
7911	// IMouse
7912	/////////////////////////////////////////////////////////////////////////
7913	-->
7914
7915	<enum
7916	name="MouseButtonState"
7917	uuid="03131722-2EC5-4173-9794-0DACA46673EF"
7918	>
7919	<desc>
7920	Mouse button state.
7921	</desc>
7922
7923	<const name="LeftButton" value="0x01"/>
7924	<const name="RightButton" value="0x02"/>
7925	<const name="MiddleButton" value="0x04"/>
7926	<const name="WheelUp" value="0x08"/>
7927	<const name="WheelDown" value="0x10"/>
7928	<const name="MouseStateMask" value="0x1F"/>
7929	</enum>
7930
7931	<interface
7932	name="IMouse" extends="$unknown"
7933	uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
7934	wsmap="managed"
7935	>
7936	<desc>
7937	The IMouse interface represents the virtual machine's mouse. Used in
7938	<link to="IConsole::mouse"/>.
7939
7940	Through this interface, the virtual machine's virtual mouse can be
7941	controlled.
7942	</desc>
7943
7944	<attribute name="absoluteSupported" type="boolean" readonly="yes">
7945	<desc>
7946	Whether the guest OS supports absolute mouse pointer positioning
7947	or not.
7948	<note>
7949	VirtualBox Guest Tools need to be installed to the guest OS
7950	in order to enable absolute mouse positioning support.
7951	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
7952	callback to be instantly informed about changes of this attribute
7953	during virtual machine execution.
7954	</note>
7955	<see><link to="#putMouseEventAbsolute"/></see>
7956	</desc>
7957	</attribute>
7958
7959	<method name="putMouseEvent">
7960	<desc>
7961	Initiates a mouse event using relative pointer movements
7962	along x and y axis.
7963	</desc>
7964
7965	<param name="dx" type="long" dir="in">
7966	<desc>
7967	Amount of pixels the mouse should move to the right.
7968	Negative values move the mouse to the left.
7969	</desc>
7970	</param>
7971	<param name="dy" type="long" dir="in">
7972	<desc>
7973	Amount of pixels the mouse should move downwards.
7974	Negative values move the mouse upwards.
7975	</desc>
7976	</param>
7977	<param name="dz" type="long" dir="in">
7978	<desc>
7979	Amount of mouse wheel moves.
7980	Positive values describe clockwise wheel rotations,
7981	negative values describe counterclockwise rotations.
7982	</desc>
7983	</param>
7984	<param name="buttonState" type="long" dir="in">
7985	<desc>
7986	The current state of mouse buttons. Every bit represents
7987	a mouse button as follows:
7988	<table>
7989	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
7990	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
7991	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
7992	</table>
7993	A value of <tt>1</tt> means the corresponding button is pressed.
7994	otherwise it is released.
7995	</desc>
7996	</param>
7997	</method>
7998
7999	<method name="putMouseEventAbsolute">
8000	<desc>
8001	Positions the mouse pointer using absolute x and y coordinates.
8002	These coordinates are expressed in pixels and
8003	start from <tt>[1,1]</tt> which corresponds to the top left
8004	corner of the virtual display.
8005
8006	<note>
8007	This method will have effect only if absolute mouse
8008	positioning is supported by the guest OS.
8009	</note>
8010
8011	<see><link to="#absoluteSupported"/></see>
8012	</desc>
8013
8014	<param name="x" type="long" dir="in">
8015	<desc>
8016	X coordinate of the pointer in pixels, starting from <tt>1</tt>.
8017	</desc>
8018	</param>
8019	<param name="y" type="long" dir="in">
8020	<desc>
8021	Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
8022	</desc>
8023	</param>
8024	<param name="dz" type="long" dir="in">
8025	<desc>
8026	Amount of mouse wheel moves.
8027	Positive values describe clockwise wheel rotations,
8028	negative values describe counterclockwise rotations.
8029	</desc>
8030	</param>
8031	<param name="buttonState" type="long" dir="in">
8032	<desc>
8033	The current state of mouse buttons. Every bit represents
8034	a mouse button as follows:
8035	<table>
8036	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
8037	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
8038	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
8039	</table>
8040	A value of <tt>1</tt> means the corresponding button is pressed.
8041	otherwise it is released.
8042	</desc>
8043	</param>
8044	</method>
8045
8046	</interface>
8047
8048	<!--
8049	// IDisplay
8050	/////////////////////////////////////////////////////////////////////////
8051	-->
8052
8053	<enum
8054	name="FramebufferAccelerationOperation"
8055	uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
8056	>
8057	<desc>
8058	Frame buffer acceleration operation.
8059	</desc>
8060
8061	<const name="SolidFillAcceleration" value="1"/>
8062	<const name="ScreenCopyAcceleration" value="2"/>
8063	</enum>
8064
8065	<enum
8066	name="FramebufferPixelFormat"
8067	uuid="6b27d1fc-4f2c-4e9c-a166-01d06540305d"
8068	>
8069	<desc>
8070	Format of the video memory buffer. Constants represented by this enum can
8071	be used to test for particular values of <link
8072	to="IFramebuffer::pixelFormat"/>. See also <link
8073	to="IFramebuffer::requestResize()"/>.
8074
8075	See also www.fourcc.org for more information about FOURCC pixel formats.
8076	</desc>
8077
8078	<const name="Opaque" value="0xFFFFFFFF">
8079	<desc>
8080	Unknown buffer format. The user may not assume any particular
8081	format of the buffer.
8082	</desc>
8083	</const>
8084	<const name="FOURCC_RGB" value="0x32424752">
8085	<desc>
8086	Basic RGB format. <link to="IFramebuffer::bitsPerPixel"/> determines
8087	the bit layout.
8088	</desc>
8089	</const>
8090	</enum>
8091
8092	<interface
8093	name="IFramebuffer" extends="$unknown"
8094	uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
8095	wsmap="suppress"
8096	>
8097	<attribute name="address" type="octet" mod="ptr" readonly="yes">
8098	<desc>Address of the start byte of the frame buffer.</desc>
8099	</attribute>
8100
8101	<attribute name="width" type="unsigned long" readonly="yes">
8102	<desc>Frame buffer width, in pixels.</desc>
8103	</attribute>
8104
8105	<attribute name="height" type="unsigned long" readonly="yes">
8106	<desc>Frame buffer height, in pixels.</desc>
8107	</attribute>
8108
8109	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
8110	<desc>
8111	Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
8112	to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, valid values
8113	are: 8, 15, 16, 24 and 32.
8114	</desc>
8115	</attribute>
8116
8117	<attribute name="bytesPerLine" type="unsigned long" readonly="yes">
8118	<desc>
8119	Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
8120	to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, the
8121	size of the scan line must be aligned to 32 bits.
8122	</desc>
8123	</attribute>
8124
8125	<attribute name="pixelFormat" type="unsigned long" readonly="yes">
8126	<desc>
8127	Frame buffer pixel format. It's either one of the values defined by <link
8128	to="FramebufferPixelFormat"/> or a raw FOURCC code.
8129	<note>
8130	This attribute must never return <link
8131	to="PixelFormat::Opaque"/> -- the format of the buffer
8132	<link to="#address"/> points to must be always known.
8133	</note>
8134	</desc>
8135	</attribute>
8136
8137	<attribute name="usesGuestVRAM" type="boolean" readonly="yes">
8138	<desc>
8139	Defines whether this frame buffer uses the virtual video card's memory
8140	buffer (guest VRAM) directly or not. See <link
8141	to="IFramebuffer::requestResize()"/> for more information.
8142	</desc>
8143	</attribute>
8144
8145	<attribute name="heightReduction" type="unsigned long" readonly="yes">
8146	<desc>
8147	Hint from the frame buffer about how much of the standard
8148	screen height it wants to use for itself. This information is
8149	exposed to the guest through the VESA BIOS and VMMDev interface
8150	so that it can use it for determining its video mode table. It
8151	is not guaranteed that the guest respects the value.
8152	</desc>
8153	</attribute>
8154
8155	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
8156	<desc>
8157	An alpha-blended overlay which is superposed over the frame buffer.
8158	The initial purpose is to allow the display of icons providing
8159	information about the VM state, including disk activity, in front
8160	ends which do not have other means of doing that. The overlay is
8161	designed to controlled exclusively by IDisplay. It has no locking
8162	of its own, and any changes made to it are not guaranteed to be
8163	visible until the affected portion of IFramebuffer is updated. The
8164	overlay can be created lazily the first time it is requested. This
8165	attribute can also return NULL to signal that the overlay is not
8166	implemented.
8167	</desc>
8168	</attribute>
8169
8170	<attribute name="winId" type="unsigned long long" readonly="yes">
8171	<desc>
8172	Platform-dependent identifier of the window where context of this
8173	frame buffer is drawn, or zero if there's no such window.
8174	</desc>
8175	</attribute>
8176
8177	<method name="lock">
8178	<desc>
8179	Locks the frame buffer.
8180	Gets called by the IDisplay object where this frame buffer is
8181	bound to.
8182	</desc>
8183	</method>
8184
8185	<method name="unlock">
8186	<desc>
8187	Unlocks the frame buffer.
8188	Gets called by the IDisplay object where this frame buffer is
8189	bound to.
8190	</desc>
8191	</method>
8192
8193	<method name="notifyUpdate">
8194	<desc>
8195	Informs about an update.
8196	Gets called by the display object where this buffer is
8197	registered.
8198	</desc>
8199	<param name="x" type="unsigned long" dir="in"/>
8200	<param name="y" type="unsigned long" dir="in"/>
8201	<param name="width" type="unsigned long" dir="in"/>
8202	<param name="height" type="unsigned long" dir="in"/>
8203	<param name="finished" type="boolean" dir="return"/>
8204	</method>
8205
8206	<method name="requestResize">
8207	<desc>
8208	Requests a size and pixel format change.
8209
8210	There are two modes of working with the video buffer of the virtual
8211	machine. The <i>indirect</i> mode implies that the IFramebuffer
8212	implementation allocates a memory buffer for the requested display mode
8213	and provides it to the virtual machine. In <i>direct</i> mode, the
8214	IFramebuffer implementation uses the memory buffer allocated and owned
8215	by the virtual machine. This buffer represents the video memory of the
8216	emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
8217	usually faster because the implementation gets a raw pointer to the
8218	guest VRAM buffer which it can directly use for visualizing the contents
8219	of the virtual display, as opposed to the indirect mode where the
8220	contents of guest VRAM are copied to the memory buffer provided by
8221	the implementation every time a display update occurs.
8222
8223	It is important to note that the direct mode is really fast only when
8224	the implementation uses the given guest VRAM buffer directly, for
8225	example, by blitting it to the window representing the virtual machine's
8226	display, which saves at least one copy operation comparing to the
8227	indirect mode. However, using the guest VRAM buffer directly is not
8228	always possible: the format and the color depth of this buffer may be
8229	not supported by the target window, or it may be unknown (opaque) as in
8230	case of text or non-linear multi-plane VGA video modes. In this case,
8231	the indirect mode (that is always available) should be used as a
8232	fallback: when the guest VRAM contents are copied to the
8233	implementation-provided memory buffer, color and format conversion is
8234	done automatically by the underlying code.
8235
8236	The @a pixelFormat parameter defines whether the direct mode is
8237	available or not. If @a pixelFormat is <link
8238	to="PixelFormat::Opaque"/> then direct access to the guest
8239	VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and @a
8240	bytesPerLine parameters must be ignored and the implementation must use
8241	the indirect mode (where it provides its own buffer in one of the
8242	supported formats). In all other cases, @a pixelFormat together with @a
8243	bitsPerPixel and @a bytesPerLine define the format of the video memory
8244	buffer pointed to by the @a VRAM parameter and the implementation is
8245	free to choose which mode to use. To indicate that this frame buffer uses
8246	the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
8247	attribute must return <tt>true</tt> and <link to="#address"/> must
8248	return exactly the same address that is passed in the @a VRAM parameter
8249	of this method; otherwise it is assumed that the indirect strategy is
8250	chosen.
8251
8252	The @a width and @a height parameters represent the size of the
8253	requested display mode in both modes. In case of indirect mode, the
8254	provided memory buffer should be big enough to store data of the given
8255	display mode. In case of direct mode, it is guaranteed that the given @a
8256	VRAM buffer contains enough space to represent the display mode of the
8257	given size. Note that this frame buffer's <link to="#width"/> and <link
8258	to="#height"/> attributes must return exactly the same values as
8259	passed to this method after the resize is completed (see below).
8260
8261	The @a finished output parameter determines if the implementation has
8262	finished resizing the frame buffer or not. If, for some reason, the
8263	resize cannot be finished immediately during this call, @a finished
8264	must be set to @c false, and the implementation must call
8265	<link to="IDisplay::resizeCompleted()"/> after it has returned from
8266	this method as soon as possible. If @a finished is @c false, the
8267	machine will not call any frame buffer methods until
8268	<link to="IDisplay::resizeCompleted()"/> is called.
8269
8270	Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
8271	<link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
8272	this frame buffer must return exactly the same values as specified in the
8273	parameters of this method, after the resize is completed. If the
8274	indirect mode is chosen, these attributes must return values describing
8275	the format of the implementation's own memory buffer <link
8276	to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
8277	value must always correlate with <link to="#pixelFormat"/>. Note that
8278	the <link to="#pixelFormat"/> attribute must never return <link
8279	to="PixelFormat::Opaque"/> regardless of the selected mode.
8280
8281	<note>
8282	This method is called by the IDisplay object under the
8283	<link to="#lock()"/> provided by this IFramebuffer
8284	implementation. If this method returns @c false in @a finished, then
8285	this lock is not released until
8286	<link to="IDisplay::resizeCompleted()"/> is called.
8287	</note>
8288	</desc>
8289	<param name="screenId" type="unsigned long" dir="in">
8290	<desc>
8291	Logical screen number. Must be used in the corresponding call to
8292	<link to="IDisplay::resizeCompleted()"/> if this call is made.
8293	</desc>
8294	</param>
8295	<param name="pixelFormat" type="unsigned long" dir="in">
8296	<desc>
8297	Pixel format of the memory buffer pointed to by @a VRAM.
8298	See also <link to="FramebufferPixelFormat"/>.
8299	</desc>
8300	</param>
8301	<param name="VRAM" type="octet" mod="ptr" dir="in">
8302	<desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
8303	</param>
8304	<param name="bitsPerPixel" type="unsigned long" dir="in">
8305	<desc>Color depth, bits per pixel.</desc>
8306	</param>
8307	<param name="bytesPerLine" type="unsigned long" dir="in">
8308	<desc>Size of one scan line, in bytes.</desc>
8309	</param>
8310	<param name="width" type="unsigned long" dir="in">
8311	<desc>Width of the guest display, in pixels.</desc>
8312	</param>
8313	<param name="height" type="unsigned long" dir="in">
8314	<desc>Height of the guest display, in pixels.</desc>
8315	</param>
8316	<param name="finished" type="boolean" dir="return">
8317	<desc>
8318	Can the VM start using the new frame buffer immediately
8319	after this method returns or it should wait for
8320	<link to="IDisplay::resizeCompleted()"/>.
8321	</desc>
8322	</param>
8323	</method>
8324
8325	<method name="operationSupported">
8326	<desc>
8327	Returns whether the given acceleration operation is supported
8328	by the IFramebuffer implementation. If not, the display object
8329	will not attempt to call the corresponding IFramebuffer entry
8330	point. Even if an operation is indicated to supported, the
8331	IFramebuffer implementation always has the option to return non
8332	supported from the corresponding acceleration method in which
8333	case the operation will be performed by the display engine. This
8334	allows for reduced IFramebuffer implementation complexity where
8335	only common cases are handled.
8336	</desc>
8337	<param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
8338	<param name="supported" type="boolean" dir="return"/>
8339	</method>
8340
8341	<method name="videoModeSupported">
8342	<desc>
8343	Returns whether the frame buffer implementation is willing to
8344	support a given video mode. In case it is not able to render
8345	the video mode (or for some reason not willing), it should
8346	return false. Usually this method is called when the guest
8347	asks the VMM device whether a given video mode is supported
8348	so the information returned is directly exposed to the guest.
8349	It is important that this method returns very quickly.
8350	</desc>
8351	<param name="width" type="unsigned long" dir="in"/>
8352	<param name="height" type="unsigned long" dir="in"/>
8353	<param name="bpp" type="unsigned long" dir="in"/>
8354	<param name="supported" type="boolean" dir="return"/>
8355	</method>
8356
8357	<method name="solidFill">
8358	<desc>
8359	Fills the specified rectangle on screen with a solid color.
8360	</desc>
8361	<param name="x" type="unsigned long" dir="in"/>
8362	<param name="y" type="unsigned long" dir="in"/>
8363	<param name="width" type="unsigned long" dir="in"/>
8364	<param name="height" type="unsigned long" dir="in"/>
8365	<param name="color" type="unsigned long" dir="in"/>
8366	<param name="handled" type="boolean" dir="return"/>
8367	</method>
8368
8369	<method name="copyScreenBits">
8370	<desc>
8371	Copies specified rectangle on the screen.
8372	</desc>
8373	<param name="xDst" type="unsigned long" dir="in"/>
8374	<param name="yDst" type="unsigned long" dir="in"/>
8375	<param name="xSrc" type="unsigned long" dir="in"/>
8376	<param name="ySrc" type="unsigned long" dir="in"/>
8377	<param name="width" type="unsigned long" dir="in"/>
8378	<param name="height" type="unsigned long" dir="in"/>
8379	<param name="handled" type="boolean" dir="return"/>
8380	</method>
8381
8382	<method name="getVisibleRegion">
8383	<desc>
8384	Returns the visible region of this frame buffer.
8385
8386	If the @a rectangles parameter is <tt>NULL</tt> then the value of the
8387	@a count parameter is ignored and the number of elements necessary to
8388	describe the current visible region is returned in @a countCopied.
8389
8390	If @a rectangles is not <tt>NULL</tt> but @a count is less
8391	than the required number of elements to store region data, the method
8392	will report a failure. If @a count is equal or greater than the
8393	required number of elements, then the actual number of elements copied
8394	to the provided array will be returned in @a countCopied.
8395
8396	<note>
8397	The address of the provided array must be in the process space of
8398	this IFramebuffer object.
8399	</note>
8400	</desc>
8401	<param name="rectangles" type="octet" mod="ptr" dir="in">
8402	<desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
8403	</param>
8404	<param name="count" type="unsigned long" dir="in">
8405	<desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
8406	</param>
8407	<param name="countCopied" type="unsigned long" dir="return">
8408	<desc>Number of elements copied to the @a rectangles array.</desc>
8409	</param>
8410	</method>
8411
8412	<method name="setVisibleRegion">
8413	<desc>
8414	Suggests a new visible region to this frame buffer. This region
8415	represents the area of the VM display which is a union of regions of
8416	all top-level windows of the guest operating system running inside the
8417	VM (if the Guest Additions for this system support this
8418	functionality). This information may be used by the frontends to
8419	implement the seamless desktop integration feature.
8420
8421	<note>
8422	The address of the provided array must be in the process space of
8423	this IFramebuffer object.
8424	</note>
8425	<note>
8426	The IFramebuffer implementation must make a copy of the provided
8427	array of rectangles.
8428	</note>
8429	</desc>
8430	<param name="rectangles" type="octet" mod="ptr" dir="in">
8431	<desc>Pointer to the <tt>RTRECT</tt> array.</desc>
8432	</param>
8433	<param name="count" type="unsigned long" dir="in">
8434	<desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
8435	</param>
8436	</method>
8437
8438	</interface>
8439
8440	<interface
8441	name="IFramebufferOverlay" extends="IFrameBuffer"
8442	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
8443	wsmap="suppress"
8444	>
8445	<desc>
8446	The IFramebufferOverlay interface represents an alpha blended overlay
8447	for displaying status icons above an IFramebuffer. It is always created
8448	not visible, so that it must be explicitly shown. It only covers a
8449	portion of the IFramebuffer, determined by its width, height and
8450	co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
8451	that order) format, and may be written to directly. Do re-read the
8452	width though, after setting it, as it may be adjusted (increased) to
8453	make it more suitable for the front end.
8454	</desc>
8455	<attribute name="x" type="unsigned long" readonly="yes">
8456	<desc>X position of the overlay, relative to the frame buffer.</desc>
8457	</attribute>
8458
8459	<attribute name="y" type="unsigned long" readonly="yes">
8460	<desc>Y position of the overlay, relative to the frame buffer.</desc>
8461	</attribute>
8462
8463	<attribute name="visible" type="boolean" readonly="no">
8464	<desc>
8465	Whether the overlay is currently visible.
8466	</desc>
8467	</attribute>
8468
8469	<attribute name="alpha" type="unsigned long" readonly="no">
8470	<desc>
8471	The global alpha value for the overlay. This may or may not be
8472	supported by a given front end.
8473	</desc>
8474	</attribute>
8475
8476	<method name="move">
8477	<desc>
8478	Changes the overlay's position relative to the IFramebuffer.
8479	</desc>
8480	<param name="x" type="unsigned long" dir="in"/>
8481	<param name="y" type="unsigned long" dir="in"/>
8482	</method>
8483
8484	</interface>
8485
8486	<interface
8487	name="IDisplay" extends="$unknown"
8488	uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
8489	wsmap="suppress"
8490	>
8491	<desc>
8492	The IDisplay interface represents the virtual machine's display.
8493
8494	The object implementing this interface is contained in each
8495	<link to="IConsole::display"/> attribute and represents the visual
8496	output of the virtual machine.
8497
8498	The virtual display supports pluggable output targets represented by the
8499	IFramebuffer interface. Examples of the output target are a window on
8500	the host computer or an RDP session's display on a remote computer.
8501	</desc>
8502	<attribute name="width" type="unsigned long" readonly="yes">
8503	<desc>Current display width.</desc>
8504	</attribute>
8505
8506	<attribute name="height" type="unsigned long" readonly="yes">
8507	<desc>Current display height.</desc>
8508	</attribute>
8509
8510	<attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
8511	<desc>
8512	Current guest display color depth. Note that this may differ
8513	from <link to="IFramebuffer::bitsPerPixel"/>.
8514	</desc>
8515	</attribute>
8516
8517	<method name="setupInternalFramebuffer">
8518	<desc>
8519	Prepares an internally managed frame buffer.
8520	</desc>
8521	<param name="depth" type="unsigned long" dir="in"/>
8522	</method>
8523
8524	<method name="lockFramebuffer">
8525	<desc>
8526	Requests access to the internal frame buffer.
8527	</desc>
8528	<param name="address" type="octet" mod="ptr" dir="return"/>
8529	</method>
8530
8531	<method name="unlockFramebuffer">
8532	<desc>
8533	Releases access to the internal frame buffer.
8534	</desc>
8535	</method>
8536
8537	<method name="registerExternalFramebuffer">
8538	<desc>
8539	Registers an external frame buffer.
8540	</desc>
8541	<param name="framebuffer" type="IFramebuffer" dir="in"/>
8542	</method>
8543
8544	<method name="setFramebuffer">
8545	<desc>
8546	Sets the framebuffer for given screen.
8547	</desc>
8548	<param name="screenId" type="unsigned long" dir="in"/>
8549	<param name="framebuffer" type="IFramebuffer" dir="in"/>
8550	</method>
8551
8552	<method name="getFramebuffer">
8553	<desc>
8554	Queries the framebuffer for given screen.
8555	</desc>
8556	<param name="screenId" type="unsigned long" dir="in"/>
8557	<param name="framebuffer" type="IFramebuffer" dir="out"/>
8558	<param name="xOrigin" type="long" dir="out"/>
8559	<param name="yOrigin" type="long" dir="out"/>
8560	</method>
8561
8562	<method name="setVideoModeHint">
8563	<desc>
8564	Asks VirtualBox to request the given video mode from
8565	the guest. This is just a hint and it cannot be guaranteed
8566	that the requested resolution will be used. Guest Additions
8567	are required for the request to be seen by guests. The caller
8568	should issue the request and wait for a resolution change and
8569	after a timeout retry.
8570
8571	Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
8572	parameters means that the corresponding values should be taken from the
8573	current video mode (i.e. left unchanged).
8574
8575	If the guest OS supports multi-monitor configuration then the @a display
8576	parameter specifies the number of the guest display to send the hint to:
8577	<tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
8578	so on. If the multi-monitor configuration is not supported, @a display
8579	must be <tt>0</tt>.
8580
8581	</desc>
8582	<param name="width" type="unsigned long" dir="in"/>
8583	<param name="height" type="unsigned long" dir="in"/>
8584	<param name="bitsPerPixel" type="unsigned long" dir="in"/>
8585	<param name="display" type="unsigned long" dir="in"/>
8586	</method>
8587
8588	<method name="setSeamlessMode">
8589	<desc>
8590	Enables or disables seamless guest display rendering (seamless desktop
8591	integration) mode.
8592	<note>
8593	Calling this method has no effect if <link
8594	to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
8595	</note>
8596	</desc>
8597	<param name="enabled" type="boolean" dir="in"/>
8598	</method>
8599
8600	<method name="takeScreenShot">
8601	<desc>
8602	Takes a screen shot of the requested size and copies it to the
8603	32-bpp buffer allocated by the caller.
8604	</desc>
8605	<param name="address" type="octet" mod="ptr" dir="in"/>
8606	<param name="width" type="unsigned long" dir="in"/>
8607	<param name="height" type="unsigned long" dir="in"/>
8608	</method>
8609
8610	<method name="drawToScreen">
8611	<desc>
8612	Draws a 32-bpp image of the specified size from the given buffer
8613	to the given point on the VM display.
8614	</desc>
8615	<param name="address" type="octet" mod="ptr" dir="in"/>
8616	<param name="x" type="unsigned long" dir="in"/>
8617	<param name="y" type="unsigned long" dir="in"/>
8618	<param name="width" type="unsigned long" dir="in"/>
8619	<param name="height" type="unsigned long" dir="in"/>
8620	</method>
8621
8622	<method name="invalidateAndUpdate">
8623	<desc>
8624	Does a full invalidation of the VM display and instructs the VM
8625	to update it.
8626	</desc>
8627	</method>
8628
8629	<method name="resizeCompleted">
8630	<desc>
8631	Signals that a framebuffer has completed the resize operation.
8632	</desc>
8633	<param name="screenId" type="unsigned long" dir="in"/>
8634	</method>
8635
8636	<method name="updateCompleted">
8637	<desc>
8638	Signals that a framebuffer has completed the update operation.
8639	</desc>
8640	</method>
8641
8642	</interface>
8643
8644	<!--
8645	// INetworkAdapter
8646	/////////////////////////////////////////////////////////////////////////
8647	-->
8648
8649	<enum
8650	name="NetworkAttachmentType"
8651	uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
8652	>
8653	<desc>
8654	Network attachment type.
8655	</desc>
8656
8657	<const name="Null" value="0">
8658	<desc><tt>null</tt> value. Also means "not attached".</desc>
8659	</const>
8660	<const name="NAT" value="1"/>
8661	<const name="HostInterface" value="2"/>
8662	<const name="Internal" value="3"/>
8663	</enum>
8664
8665	<enum
8666	name="NetworkAdapterType"
8667	uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
8668	>
8669	<desc>
8670	Network adapter type.
8671	</desc>
8672
8673	<const name="Null" value="0">
8674	<desc><tt>null</tt> value. Never used by the API.</desc>
8675	</const>
8676	<const name="Am79C970A" value="1"/>
8677	<const name="Am79C973" value="2"/>
8678	<const name="I82540EM" value="3"/>
8679	<const name="I82543GC" value="4"/>
8680	</enum>
8681
8682	<interface
8683	name="INetworkAdapter" extends="$unknown"
8684	uuid="a876d9b1-68d9-43b1-9c68-ddea0a473663"
8685	wsmap="managed"
8686	>
8687	<attribute name="adapterType" type="NetworkAdapterType">
8688	<desc>
8689	Type of the virtual network adapter. Depending on this value,
8690	VirtualBox will provide a different virtual network hardware
8691	to the guest.
8692	</desc>
8693	</attribute>
8694
8695	<attribute name="slot" type="unsigned long" readonly="yes">
8696	<desc>
8697	Slot number this adapter is plugged into. Corresponds to
8698	the value you pass to <link to="IMachine::getNetworkAdapter"/>
8699	to obtain this instance.
8700	</desc>
8701	</attribute>
8702
8703	<attribute name="enabled" type="boolean">
8704	<desc>
8705	Flag whether the network adapter is present in the
8706	guest system. If disabled, the virtual guest hardware will
8707	not contain this network adapter. Can only be changed when
8708	the VM is not running.
8709	</desc>
8710	</attribute>
8711
8712	<attribute name="MACAddress" type="wstring">
8713	<desc>
8714	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
8715	it to NULL, VirtualBox will generate a unique MAC address.
8716	</desc>
8717	</attribute>
8718
8719	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
8720
8721	<attribute name="hostInterface" type="wstring">
8722	<desc>
8723	Name of the Host Network Interface that is currently in use. NULL will be returned
8724	if no device has been allocated. On Linux, setting this refers to a permanent TAP
8725	device. However, a file descriptor has precedence over the interface name on Linux.
8726	Note that when VirtualBox allocates a TAP device, this property will not be set, i.e. the
8727	interface name would have to be determined using the file descriptor and /proc/self/fd.
8728	</desc>
8729	</attribute>
8730
8731	<if target="xpidl">
8732	<attribute name="TAPFileDescriptor" type="long">
8733	<desc>
8734	File descriptor of the TAP device. It can either be setup by the caller
8735	which has to supply an existing valid file handle allocated in the parent
8736	process of the VM process or allocated by VirtualBox. The value is -1 if it
8737	has not been defined. This property is non persistent, i.e. it will not be
8738	stored in the VM's configuration data and thus has to be set at each startup.
8739	</desc>
8740	</attribute>
8741	<attribute name="TAPSetupApplication" type="wstring">
8742	<desc>
8743	Application to start to configure the TAP device.
8744	It is being passed two parameters, 1) the file handle (as ASCII),
8745	2) the TAP device name if it is available.
8746	</desc>
8747	</attribute>
8748	<attribute name="TAPTerminateApplication" type="wstring">
8749	<desc>
8750	Application to start before closing a TAP device.
8751	It is being passed two parameters, 1) the file handle (as ASCII),
8752	2) the TAP device name if it is available.
8753	</desc>
8754	</attribute>
8755	</if>
8756
8757	<attribute name="internalNetwork" type="wstring">
8758	<desc>
8759	Name of the internal network the VM is attached to.
8760	</desc>
8761	</attribute>
8762
8763	<attribute name="NATNetwork" type="wstring">
8764	<desc>
8765	Name of the NAT network the VM is attached to.
8766	</desc>
8767	</attribute>
8768
8769	<attribute name="cableConnected" type="boolean">
8770	<desc>
8771	Flag whether the adapter reports the cable as connected or not.
8772	It can be used to report offline situations to a VM.
8773	</desc>
8774	</attribute>
8775
8776	<attribute name="lineSpeed" type="unsigned long">
8777	<desc>
8778	Line speed reported by custom drivers, in units of 1 kbps.
8779	</desc>
8780	</attribute>
8781
8782	<attribute name="traceEnabled" type="boolean">
8783	<desc>
8784	Flag whether network traffic from/to the network card should be traced.
8785	Can only be toggled when the VM is turned off.
8786	</desc>
8787	</attribute>
8788
8789	<attribute name="traceFile" type="wstring">
8790	<desc>
8791	Filename where a network trace will be stored. If not set, VBox-pid.pcap
8792	will be used.
8793	</desc>
8794	</attribute>
8795
8796	<method name="attachToNAT">
8797	<desc>
8798	Attach the network adapter to the Network Address Translation (NAT) interface.
8799	</desc>
8800	</method>
8801
8802	<method name="attachToHostInterface">
8803	<desc>
8804	Attach the network adapter to a host interface. On Linux, the TAP
8805	setup application will be executed if configured and unless a device
8806	name and/or file descriptor has been set, a new TAP interface will be
8807	created.
8808	</desc>
8809	</method>
8810
8811	<method name="attachToInternalNetwork">
8812	<desc>
8813	Attach the network adapter to an internal network.
8814	</desc>
8815	</method>
8816
8817	<method name="detach">
8818	<desc>
8819	Detach the network adapter
8820	</desc>
8821	</method>
8822	</interface>
8823
8824
8825	<!--
8826	// ISerialPort
8827	/////////////////////////////////////////////////////////////////////////
8828	-->
8829
8830	<enum
8831	name="PortMode"
8832	uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
8833	>
8834	<desc>
8835	The PortMode enumeration represents possible communication modes for
8836	the virtual serial port device.
8837	</desc>
8838
8839	<const name="Disconnected" value="0">
8840	<desc>Virtual device is not attached to any real host device.</desc>
8841	</const>
8842	<const name="HostPipe" value="1">
8843	<desc>Virtual device is attached to a host pipe.</desc>
8844	</const>
8845	<const name="HostDevice" value="2">
8846	<desc>Virtual device is attached to a host device.</desc>
8847	</const>
8848	</enum>
8849
8850	<interface
8851	name="ISerialPort" extends="$unknown"
8852	uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
8853	wsmap="managed"
8854	>
8855
8856	<desc>
8857	The ISerialPort interface represents the virtual serial port device.
8858
8859	The virtual serial port device acts like an ordinary serial port
8860	inside the virtual machine. This device communicates to the real
8861	serial port hardware in one of two modes: host pipe or host device.
8862
8863	In host pipe mode, the #path attribute specifies the path to the pipe on
8864	the host computer that represents a serial port. The #server attribute
8865	determines if this pipe is created by the virtual machine process at
8866	machine startup or it must already exist before starting machine
8867	execution.
8868
8869	In host device mode, the #path attribute specifies the name of the
8870	serial port device on the host computer.
8871
8872	There is also a third communication mode: the disconnected mode. In this
8873	mode, the guest OS running inside the virtual machine will be able to
8874	detect the serial port, but all port write operations will be discarded
8875	and all port read operations will return no data.
8876
8877	<see>IMachine::getSerialPort</see>
8878	</desc>
8879
8880	<attribute name="slot" type="unsigned long" readonly="yes">
8881	<desc>
8882	Slot number this serial port is plugged into. Corresponds to
8883	the value you pass to <link to="IMachine::getSerialPort"/>
8884	to obtain this instance.
8885	</desc>
8886	</attribute>
8887
8888	<attribute name="enabled" type="boolean">
8889	<desc>
8890	Flag whether the serial port is enabled. If disabled,
8891	the serial port will not be reported to the guest OS.
8892	</desc>
8893	</attribute>
8894
8895	<attribute name="IOBase" type="unsigned long">
8896	<desc>Base I/O address of the serial port.</desc>
8897	</attribute>
8898
8899	<attribute name="IRQ" type="unsigned long">
8900	<desc>IRQ number of the serial port.</desc>
8901	</attribute>
8902
8903	<attribute name="hostMode" type="PortMode">
8904	<desc>How is this port connected to the host.</desc>
8905	</attribute>
8906
8907	<attribute name="server" type="boolean">
8908	<desc>
8909	Flag whether this serial port acts as a server (creates a new pipe on
8910	the host) or as a client (uses the existing pipe). This attribute is
8911	used only when <link to="#hostMode"/> is PortMode::HostPipe.
8912	</desc>
8913	</attribute>
8914
8915	<attribute name="path" type="wstring">
8916	<desc>
8917	Path to the serial port's pipe on the host when <link to="#hostMode"/> is
8918	PortMode::HostPipe, or the host serial device name when
8919	<link to="#hostMode"/> is PortMode::HostDevice. In either of the above
8920	cases, setting a @c null or an empty string as the attribute's value
8921	will result into an error. Otherwise, the value of this property is
8922	ignored.
8923	</desc>
8924	</attribute>
8925
8926	</interface>
8927
8928	<!--
8929	// IParallelPort
8930	/////////////////////////////////////////////////////////////////////////
8931	-->
8932
8933	<interface
8934	name="IParallelPort" extends="$unknown"
8935	uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
8936	wsmap="managed"
8937	>
8938
8939	<desc>
8940	The IParallelPort interface represents the virtual parallel port device.
8941
8942	The virtual parallel port device acts like an ordinary parallel port
8943	inside the virtual machine. This device communicates to the real
8944	parallel port hardware using the name of the parallel device on the host
8945	computer specified in the #path attribute.
8946
8947	Each virtual parallel port device is assigned a base I/O address and an
8948	IRQ number that will be reported to the guest operating system and used
8949	to operate the given parallel port from within the virtual machine.
8950
8951	<see>IMachine::getParallelPort</see>
8952	</desc>
8953
8954	<attribute name="slot" type="unsigned long" readonly="yes">
8955	<desc>
8956	Slot number this parallel port is plugged into. Corresponds to
8957	the value you pass to <link to="IMachine::getParallelPort"/>
8958	to obtain this instance.
8959	</desc>
8960	</attribute>
8961
8962	<attribute name="enabled" type="boolean">
8963	<desc>
8964	Flag whether the parallel port is enabled. If disabled,
8965	the parallel port will not be reported to the guest OS.
8966	</desc>
8967	</attribute>
8968
8969	<attribute name="IOBase" type="unsigned long">
8970	<desc>Base I/O address of the parallel port.</desc>
8971	</attribute>
8972
8973	<attribute name="IRQ" type="unsigned long">
8974	<desc>IRQ number of the parallel port.</desc>
8975	</attribute>
8976
8977	<attribute name="path" type="wstring">
8978	<desc>
8979	Host parallel device name. If this parallel port is enabled, setting a
8980	@c null or an empty string as this attribute's value will result into
8981	an error.
8982	</desc>
8983	</attribute>
8984
8985	</interface>
8986
8987
8988	<!--
8989	// IMachineDebugger
8990	/////////////////////////////////////////////////////////////////////////
8991	-->
8992
8993	<interface
8994	name="IMachineDebugger" extends="$unknown"
8995	uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
8996	wsmap="suppress"
8997	>
8998	<method name="resetStats">
8999	<desc>
9000	Reset VM statistics.
9001	</desc>
9002	<param name="pattern" type="wstring" dir="in">
9003	<desc>The selection pattern. A bit similar to filename globbing.</desc>
9004	</param>
9005	</method>
9006
9007	<method name="dumpStats">
9008	<desc>
9009	Dumps VM statistics.
9010	</desc>
9011	<param name="pattern" type="wstring" dir="in">
9012	<desc>The selection pattern. A bit similar to filename globbing.</desc>
9013	</param>
9014	</method>
9015
9016	<method name="getStats">
9017	<desc>
9018	Get the VM statistics in a XMLish format.
9019	</desc>
9020	<param name="pattern" type="wstring" dir="in">
9021	<desc>The selection pattern. A bit similar to filename globbing.</desc>
9022	</param>
9023	<param name="withDescriptions" type="boolean" dir="in">
9024	<desc>Whether to include the descriptions.</desc>
9025	</param>
9026	<param name="stats" type="wstring" dir="out">
9027	<desc>The XML document containing the statistics.</desc>
9028	</param>
9029	</method>
9030
9031	<method name="injectNMI">
9032	<desc>
9033	Inject an NMI into a running VT-x/AMD-V VM.
9034	</desc>
9035	</method>
9036
9037	<attribute name="singlestep" type="boolean">
9038	<desc>Switch for enabling singlestepping.</desc>
9039	</attribute>
9040
9041	<attribute name="recompileUser" type="boolean">
9042	<desc>Switch for forcing code recompilation for user mode code.</desc>
9043	</attribute>
9044
9045	<attribute name="recompileSupervisor" type="boolean">
9046	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
9047	</attribute>
9048
9049	<attribute name="PATMEnabled" type="boolean">
9050	<desc>Switch for enabling and disabling the PATM component.</desc>
9051	</attribute>
9052
9053	<attribute name="CSAMEnabled" type="boolean">
9054	<desc>Switch for enabling and disabling the CSAM component.</desc>
9055	</attribute>
9056
9057	<attribute name="logEnabled" type="boolean">
9058	<desc>Switch for enabling and disabling logging.</desc>
9059	</attribute>
9060
9061	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
9062	<desc>
9063	Flag indicating whether the VM is currently making use of CPU hardware
9064	virtualization extensions.
9065	</desc>
9066	</attribute>
9067
9068	<attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
9069	<desc>
9070	Flag indicating whether the VM is currently making use of the nested paging
9071	CPU hardware virtualization extension.
9072	</desc>
9073	</attribute>
9074
9075	<attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
9076	<desc>
9077	Flag indicating whether the VM is currently making use of the VPID
9078	VT-x extension.
9079	</desc>
9080	</attribute>
9081
9082	<attribute name="PAEEnabled" type="boolean" readonly="yes">
9083	<desc>
9084	Flag indicating whether the VM is currently making use of the Physical
9085	Address Extension CPU feature.
9086	</desc>
9087	</attribute>
9088
9089	<attribute name="virtualTimeRate" type="unsigned long">
9090	<desc>
9091	The rate at which the virtual time runs expressed as a percentage.
9092	The accepted range is 2% to 20000%.
9093	</desc>
9094	</attribute>
9095
9096	<!-- @todo method for setting log flags, groups and destination! -->
9097
9098	<attribute name="VM" type="unsigned long long" readonly="yes">
9099	<desc>
9100	Gets the VM handle. This is only for internal use while
9101	we carve the details of this interface.
9102	</desc>
9103	</attribute>
9104
9105	</interface>
9106
9107	<!--
9108	// IUSBController
9109	/////////////////////////////////////////////////////////////////////////
9110	-->
9111
9112	<interface
9113	name="IUSBController" extends="$unknown"
9114	uuid="f4c2d3dc-f109-4da7-93b1-ec28973ac89f"
9115	wsmap="managed"
9116	>
9117	<attribute name="enabled" type="boolean">
9118	<desc>
9119	Flag whether the USB controller is present in the
9120	guest system. If disabled, the virtual guest hardware will
9121	not contain any USB controller. Can only be changed when
9122	the VM is powered off.
9123	</desc>
9124	</attribute>
9125
9126	<attribute name="enabledEhci" type="boolean">
9127	<desc>
9128	Flag whether the USB EHCI controller is present in the
9129	guest system. If disabled, the virtual guest hardware will
9130	not contain a USB EHCI controller. Can only be changed when
9131	the VM is powered off.
9132	</desc>
9133	</attribute>
9134
9135	<attribute name="USBStandard" type="unsigned short" readonly="yes">
9136	<desc>
9137	USB standard version which the controller implements.
9138	This is a BCD which means that the major version is in the
9139	high byte and minor version is in the low byte.
9140	</desc>
9141	</attribute>
9142
9143	<attribute name="deviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
9144	<desc>
9145	List of USB device filters associated with the machine.
9146
9147	If the machine is currently running, these filters are activated
9148	every time a new (supported) USB device is attached to the host
9149	computer that was not ignored by global filters
9150	(<link to="IHost::USBDeviceFilters"/>).
9151
9152	These filters are also activated when the machine is powered up.
9153	They are run against a list of all currently available USB
9154	devices (in states
9155	<link to="USBDeviceState::Available">Available</link>,
9156	<link to="USBDeviceState::Busy">Busy</link>,
9157	<link to="USBDeviceState::Held">Held</link>) that were not previously
9158	ignored by global filters.
9159
9160	If at least one filter matches the USB device in question, this
9161	device is automatically captured (attached to) the virtual USB
9162	controller of this machine.
9163
9164	<see>IUSBDeviceFilter, ::IUSBController</see>
9165	</desc>
9166	</attribute>
9167
9168	<method name="createDeviceFilter">
9169	<desc>
9170	Creates a new USB device filter. All attributes except
9171	the filter name are set to <tt>null</tt> (any match),
9172	<i>active</i> is <tt>false</tt> (the filter is not active).
9173
9174	The created filter can then be added to the list of filters using
9175	<link to="#insertDeviceFilter()"/>.
9176
9177	<see>#deviceFilters</see>
9178	</desc>
9179	<param name="name" type="wstring" dir="in">
9180	<desc>
9181	Filter name. See <link to="IUSBDeviceFilter::name"/>
9182	for more info.
9183	</desc>
9184	</param>
9185	<param name="filter" type="IUSBDeviceFilter" dir="return">
9186	<desc>Created filter object.</desc>
9187	</param>
9188	</method>
9189
9190	<method name="insertDeviceFilter">
9191	<desc>
9192	Inserts the given USB device to the specified position
9193	in the list of filters.
9194
9195	Positions are numbered starting from <tt>0</tt>. If the specified
9196	position is equal to or greater than the number of elements in
9197	the list, the filter is added to the end of the collection.
9198
9199	<note>
9200	Duplicates are not allowed, so an attempt to insert a
9201	filter that is already in the collection, will return an
9202	error.
9203	</note>
9204
9205	<see>#deviceFilters</see>
9206	</desc>
9207	<param name="position" type="unsigned long" dir="in">
9208	<desc>Position to insert the filter to.</desc>
9209	</param>
9210	<param name="filter" type="IUSBDeviceFilter" dir="in">
9211	<desc>USB device filter to insert.</desc>
9212	</param>
9213	</method>
9214
9215	<method name="removeDeviceFilter">
9216	<desc>
9217	Removes a USB device filter from the specified position in the
9218	list of filters.
9219
9220	Positions are numbered starting from <tt>0</tt>. Specifying a
9221	position equal to or greater than the number of elements in
9222	the list will produce an error.
9223
9224	<see>#deviceFilters</see>
9225	</desc>
9226	<param name="position" type="unsigned long" dir="in">
9227	<desc>Position to remove the filter from.</desc>
9228	</param>
9229	<param name="filter" type="IUSBDeviceFilter" dir="return">
9230	<desc>Removed USB device filter.</desc>
9231	</param>
9232	</method>
9233
9234	</interface>
9235
9236
9237	<!--
9238	// IUSBDevice
9239	/////////////////////////////////////////////////////////////////////////
9240	-->
9241
9242	<enumerator
9243	name="IUSBDeviceEnumerator" type="IUSBDevice"
9244	uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
9245	/>
9246
9247	<collection
9248	name="IUSBDeviceCollection" type="IUSBDevice"
9249	enumerator="IUSBDeviceEnumerator"
9250	uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
9251	readonly="yes"
9252	>
9253	<method name="findById">
9254	<desc>
9255	Searches this collection for a USB device with the given UUID.
9256	<note>
9257	The method returns an error if the given UUID does not
9258	correspond to any USB device in the collection.
9259	</note>
9260	<see>IUSBDevice::id</see>
9261	</desc>
9262	<param name="id" type="uuid" dir="in">
9263	<desc>UUID of the USB device to search for.</desc>
9264	</param>
9265	<param name="device" type="IUSBDevice" dir="return">
9266	<desc>Found USB device object.</desc>
9267	</param>
9268	</method>
9269
9270	<method name="findByAddress">
9271	<desc>
9272	Searches this collection for a USB device with the given
9273	host address.
9274	<note>
9275	The method returns an error if the given address does not
9276	correspond to any USB device in the collection.
9277	</note>
9278	<see>IUSBDevice::address</see>
9279	</desc>
9280	<param name="name" type="wstring" dir="in">
9281	<desc>
9282	Address of the USB device (as assigned by the host) to
9283	search for.
9284	</desc>
9285	</param>
9286	<param name="device" type="IUSBDevice" dir="return">
9287	<desc>Found USB device object.</desc>
9288	</param>
9289	</method>
9290
9291	</collection>
9292
9293	<interface
9294	name="IUSBDevice" extends="$unknown"
9295	uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
9296	wsmap="managed"
9297	>
9298	<desc>
9299	The IUSBDevice interface represents a virtual USB device attached to the
9300	virtual machine.
9301
9302	A collection of objects implementing this interface is stored in the
9303	<link to="IConsole::USBDevices"/> attribute which lists all USB devices
9304	attached to a running virtual machine's USB controller.
9305	</desc>
9306
9307	<attribute name="id" type="uuid" readonly="yes">
9308	<desc>
9309	Unique USB device ID. This ID is built from #vendorId,
9310	#productId, #revision and #serialNumber.
9311	</desc>
9312	</attribute>
9313
9314	<attribute name="vendorId" type="unsigned short" readonly="yes">
9315	<desc>Vendor ID.</desc>
9316	</attribute>
9317
9318	<attribute name="productId" type="unsigned short" readonly="yes">
9319	<desc>Product ID.</desc>
9320	</attribute>
9321
9322	<attribute name="revision" type="unsigned short" readonly="yes">
9323	<desc>
9324	Product revision number. This is a packed BCD represented as
9325	unsigned short. The high byte is the integer part and the low
9326	byte is the decimal.
9327	</desc>
9328	</attribute>
9329
9330	<attribute name="manufacturer" type="wstring" readonly="yes">
9331	<desc>Manufacturer string.</desc>
9332	</attribute>
9333
9334	<attribute name="product" type="wstring" readonly="yes">
9335	<desc>Product string.</desc>
9336	</attribute>
9337
9338	<attribute name="serialNumber" type="wstring" readonly="yes">
9339	<desc>Serial number string.</desc>
9340	</attribute>
9341
9342	<attribute name="address" type="wstring" readonly="yes">
9343	<desc>Host specific address of the device.</desc>
9344	</attribute>
9345
9346	<attribute name="port" type="unsigned short" readonly="yes">
9347	<desc>
9348	Host USB port number the device is physically
9349	connected to.
9350	</desc>
9351	</attribute>
9352
9353	<attribute name="version" type="unsigned short" readonly="yes">
9354	<desc>
9355	The major USB version of the device - 1 or 2.
9356	</desc>
9357	</attribute>
9358
9359	<attribute name="portVersion" type="unsigned short" readonly="yes">
9360	<desc>
9361	The major USB version of the host USB port the device is
9362	physically connected to - 1 or 2. For devices not connected to
9363	anything this will have the same value as the version attribute.
9364	</desc>
9365	</attribute>
9366
9367	<attribute name="remote" type="boolean" readonly="yes">
9368	<desc>
9369	Whether the device is physically connected to a remote VRDP
9370	client or to a local host machine.
9371	</desc>
9372	</attribute>
9373
9374	</interface>
9375
9376
9377	<!--
9378	// IUSBDeviceFilter
9379	/////////////////////////////////////////////////////////////////////////
9380	-->
9381
9382	<enumerator
9383	name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
9384	uuid="d5109c61-93e7-4726-926b-0dee1020da56"
9385	/>
9386
9387	<collection
9388	name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
9389	enumerator="IUSBDeviceFilterEnumerator"
9390	uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
9391	readonly="yes"
9392	/>
9393
9394	<interface
9395	name="IUSBDeviceFilter" extends="$unknown"
9396	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
9397	wsmap="managed"
9398	>
9399	<desc>
9400	The IUSBDeviceFilter interface represents an USB device filter used
9401	to perform actions on a group of USB devices.
9402
9403	This type of filters is used by running virtual machines to
9404	automatically capture selected USB devices once they are physically
9405	attached to the host computer.
9406
9407	A USB device is matched to the given device filter if and only if all
9408	attributes of the device match the corresponding attributes of the
9409	filter (that is, attributes are joined together using the logical AND
9410	operation). On the other hand, all together, filters in the list of
9411	filters carry the semantics of the logical OR operation. So if it is
9412	desirable to create a match like "this vendor id OR this product id",
9413	one needs to create two filters and specify "any match" (see below)
9414	for unused attributes.
9415
9416	All filter attributes used for matching are strings. Each string
9417	is an expression representing a set of values of the corresponding
9418	device attribute, that will match the given filter. Currently, the
9419	following filtering expressions are supported:
9420
9421	<ul>
9422	<li><i>Interval filters</i>. Used to specify valid intervals for
9423	integer device attributes (Vendor ID, Product ID and Revision).
9424	The format of the string is:
9425
9426	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
9427
9428	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
9429	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
9430	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
9431	is omitted before a dash (<tt>-</tt>), the minimum possible integer
9432	is assumed; if <tt>n</tt> is omitted after a dash, the maximum
9433	possible integer is assumed.
9434	</li>
9435	<li><i>Boolean filters</i>. Used to specify acceptable values for
9436	boolean device attributes. The format of the string is:
9437
9438	<tt>true\|false\|yes\|no\|0\|1</tt>
9439
9440	</li>
9441	<li><i>Exact match</i>. Used to specify a single value for the given
9442	device attribute. Any string that doesn't start with <tt>int:</tt>
9443	represents the exact match. String device attributes are compared to
9444	this string including case of symbols. Integer attributes are first
9445	converted to a string (see individual filter attributes) and then
9446	compared ignoring case.
9447
9448	</li>
9449	<li><i>Any match</i>. Any value of the corresponding device attribute
9450	will match the given filter. An empty or <tt>null</tt> string is
9451	used to construct this type of filtering expressions.
9452
9453	</li>
9454	</ul>
9455
9456	<note>
9457	On the Windows host platform, interval filters are not currently
9458	available. Also all string filter attributes
9459	(<link to="#manufacturer"/>, <link to="#product"/>,
9460	<link to="#serialNumber"/>) are ignored, so they behave as
9461	<i>any match</i> no matter what string expression is specified.
9462	</note>
9463
9464	<see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
9465	</desc>
9466
9467	<attribute name="name" type="wstring">
9468	<desc>
9469	Visible name for this filter.
9470	This name is used to visually distinguish one filter from another,
9471	so it can neither be <tt>null</tt> nor an empty string.
9472	</desc>
9473	</attribute>
9474
9475	<attribute name="active" type="boolean">
9476	<desc>Whether this filter active or has been temporarily disabled.</desc>
9477	</attribute>
9478
9479	<attribute name="vendorId" type="wstring">
9480	<desc>
9481	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
9482	The string representation for the <i>exact matching</i>
9483	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
9484	(including leading zeroes).
9485	</desc>
9486	</attribute>
9487
9488	<attribute name="productId" type="wstring">
9489	<desc>
9490	<link to="IUSBDevice::productId">Product ID</link> filter.
9491	The string representation for the <i>exact matching</i>
9492	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
9493	(including leading zeroes).
9494	</desc>
9495	</attribute>
9496
9497	<attribute name="revision" type="wstring">
9498	<desc>
9499	<link to="IUSBDevice::productId">Product revision number</link>
9500	filter. The string representation for the <i>exact matching</i>
9501	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
9502	of the integer part of the revision, and <tt>F</tt> is the
9503	decimal digit of its fractional part (including leading and
9504	trailing zeros).
9505	Note that for interval filters, it's best to use the hexadecimal
9506	form, because the revision is stored as a 16 bit packed BCD value;
9507	so the expression <tt>int:0x0100-0x0199</tt> will match any
9508	revision from <tt>1.0</tt> to <tt>1.99</tt>.
9509	</desc>
9510	</attribute>
9511
9512	<attribute name="manufacturer" type="wstring">
9513	<desc>
9514	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
9515	</desc>
9516	</attribute>
9517
9518	<attribute name="product" type="wstring">
9519	<desc>
9520	<link to="IUSBDevice::product">Product</link> filter.
9521	</desc>
9522	</attribute>
9523
9524	<attribute name="serialNumber" type="wstring">
9525	<desc>
9526	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
9527	</desc>
9528	</attribute>
9529
9530	<attribute name="port" type="wstring">
9531	<desc>
9532	<link to="IUSBDevice::port">Host USB port</link> filter.
9533	</desc>
9534	</attribute>
9535
9536	<attribute name="remote" type="wstring">
9537	<desc>
9538	<link to="IUSBDevice::remote">Remote state</link> filter.
9539	<note>
9540	This filter makes sense only for machine USB filters,
9541	i.e. it is ignored by IHostUSBDeviceFilter objects.
9542	</note>
9543	</desc>
9544	</attribute>
9545
9546	<attribute name="maskedInterfaces" type="unsigned long">
9547	<desc>
9548	This is an advanced option for hiding one or more USB interfaces
9549	from the guest. The value is a bit mask where the bits that are set
9550	means the corresponding USB interface should be hidden, masked off
9551	if you like.
9552	This feature only works on Linux hosts.
9553	</desc>
9554	</attribute>
9555
9556	</interface>
9557
9558
9559	<!--
9560	// IHostUSBDevice
9561	/////////////////////////////////////////////////////////////////////////
9562	-->
9563
9564	<enum
9565	name="USBDeviceState"
9566	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
9567	>
9568	<desc>
9569	USB device state. This enumeration represents all possible states
9570	of the USB device physically attached to the host computer regarding
9571	its state on the host computer and availability to guest computers
9572	(all currently running virtual machines).
9573
9574	Once a supported USB device is attached to the host, global USB
9575	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
9576	either ignore the device, or put it to #Held state, or do nothing. Unless
9577	the device is ignored by global filters, filters of all currently running
9578	guests (<link to="IUSBController::deviceFilters"/>) are activated that can
9579	put it to #Captured state.
9580
9581	If the device was ignored by global filters, or didn't match
9582	any filters at all (including guest ones), it is handled by the host
9583	in a normal way. In this case, the device state is determined by
9584	the host and can be one of #Unavailable, #Busy or #Available, depending on
9585	the current device usage.
9586
9587	Besides auto-capturing based on filters, the device can be manually
9588	captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
9589	state is #Busy, #Available or #Held.
9590
9591	<note>
9592	Due to differences in USB stack implementations in Linux and Win32,
9593	states #Busy and #Available are applicable only to the Linux version of
9594	the product. This also means that (<link
9595	to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if
9596	the device state is #Held.
9597	</note>
9598
9599	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
9600	</desc>
9601
9602	<const name="NotSupported" value="0">
9603	<desc>
9604	Not supported by the VirtualBox server, not available to guests.
9605	</desc>
9606	</const>
9607	<const name="Unavailable" value="1">
9608	<desc>
9609	Being used by the host computer exclusively,
9610	not available to guests.
9611	</desc>
9612	</const>
9613	<const name="Busy" value="2">
9614	<desc>
9615	Being used by the host computer, potentially available to guests.
9616	</desc>
9617	</const>
9618	<const name="Available" value="3">
9619	<desc>
9620	Not used by the host computer, available to guests.
9621	The host computer can also start using the device at any time.
9622	</desc>
9623	</const>
9624	<const name="Held" value="4">
9625	<desc>
9626	Held by the VirtualBox server (ignored by the host computer),
9627	available to guests.
9628	</desc>
9629	</const>
9630	<const name="Captured" value="5">
9631	<desc>
9632	Captured by one of the guest computers, not available
9633	to anybody else.
9634	</desc>
9635	</const>
9636	</enum>
9637
9638	<enumerator
9639	name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
9640	uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
9641	/>
9642
9643	<collection
9644	name="IHostUSBDeviceCollection" type="IHostUSBDevice"
9645	enumerator="IHostUSBDeviceEnumerator"
9646	uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
9647	readonly="yes"
9648	>
9649	<method name="findById">
9650	<desc>
9651	Searches this collection for a USB device with the given UUID.
9652	<note>
9653	The method returns an error if the given UUID does not
9654	correspond to any USB device in the collection.
9655	</note>
9656	<see>IHostUSBDevice::id</see>
9657	</desc>
9658	<param name="id" type="uuid" dir="in">
9659	<desc>UUID of the USB device to search for.</desc>
9660	</param>
9661	<param name="device" type="IHostUSBDevice" dir="return">
9662	<desc>Found USB device object.</desc>
9663	</param>
9664	</method>
9665
9666	<method name="findByAddress">
9667	<desc>
9668	Searches this collection for a USB device with the given
9669	host address.
9670	<note>
9671	The method returns an error if the given address does not
9672	correspond to any USB device in the collection.
9673	</note>
9674	<see>IHostUSBDevice::address</see>
9675	</desc>
9676	<param name="name" type="wstring" dir="in">
9677	<desc>
9678	Address of the USB device (as assigned by the host) to
9679	search for.
9680	</desc>
9681	</param>
9682	<param name="device" type="IHostUSBDevice" dir="return">
9683	<desc>Found USB device object.</desc>
9684	</param>
9685	</method>
9686
9687	</collection>
9688
9689	<interface
9690	name="IHostUSBDevice" extends="IUSBDevice"
9691	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
9692	wsmap="managed"
9693	>
9694	<desc>
9695	The IHostUSBDevice interface represents a physical USB device attached
9696	to the host computer.
9697
9698	Besides properties inherited from IUSBDevice, this interface adds the
9699	<link to="#state"/> property that holds the current state of the USB
9700	device.
9701
9702	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
9703	</desc>
9704
9705	<attribute name="state" type="USBDeviceState" readonly="yes">
9706	<desc>
9707	Current state of the device.
9708	</desc>
9709	</attribute>
9710
9711	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
9712
9713	</interface>
9714
9715
9716	<!--
9717	// IHostUSBDeviceFilter
9718	/////////////////////////////////////////////////////////////////////////
9719	-->
9720
9721	<enum
9722	name="USBDeviceFilterAction"
9723	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
9724	>
9725	<desc>
9726	Actions for host USB device filters.
9727	<see>IHostUSBDeviceFilter, USBDeviceState</see>
9728	</desc>
9729
9730	<const name="Null" value="0">
9731	<desc><tt>null</tt> value. Never used by the API.</desc>
9732	</const>
9733	<const name="Ignore" value="1">
9734	<desc>Ignore the matched USB device.</desc>
9735	</const>
9736	<const name="Hold" value="2">
9737	<desc>Hold the matched USB device.</desc>
9738	</const>
9739	</enum>
9740
9741	<enumerator
9742	name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
9743	uuid="ff735211-903e-4642-9c37-189eb44579fe"
9744	/>
9745
9746	<collection
9747	name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
9748	enumerator="IHostUSBDeviceFilterEnumerator"
9749	uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
9750	readonly="yes"
9751	/>
9752
9753	<interface
9754	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
9755	uuid="4cc70246-d74a-400f-8222-3900489c0374"
9756	wsmap="managed"
9757	>
9758	<desc>
9759	The IHostUSBDeviceFilter interface represents a global filter for a
9760	physical USB device used by the host computer. Used indirectly in
9761	<link to="IHost::USBDeviceFilters"/>.
9762
9763	Using filters of this type, the host computer determines the initial
9764	state of the USB device after it is physically attached to the
9765	host's USB controller.
9766
9767	<note>
9768	The <link to="#remote"/> attribute is ignored by this type of
9769	filters, because it makes sense only for
9770	<link to="IUSBController::deviceFilters">machine USB filters</link>.
9771	</note>
9772
9773	<see>IHost::USBDeviceFilters</see>
9774	</desc>
9775
9776	<attribute name="action" type="USBDeviceFilterAction">
9777	<desc>
9778	Action performed by the host when an attached USB device
9779	matches this filter.
9780	</desc>
9781	</attribute>
9782
9783	</interface>
9784
9785	<!--
9786	// IAudioAdapter
9787	/////////////////////////////////////////////////////////////////////////
9788	-->
9789
9790	<enum
9791	name="AudioDriverType"
9792	uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
9793	>
9794	<desc>
9795	Host audio driver type.
9796	</desc>
9797
9798	<const name="Null" value="0">
9799	<desc><tt>null</tt> value. Also means "dummy audio driver".</desc>
9800	</const>
9801	<const name="WinMM" value="1"/>
9802	<const name="OSS" value="2"/>
9803	<const name="ALSA" value="3"/>
9804	<const name="DirectSound" value="4"/>
9805	<const name="CoreAudio" value="5"/>
9806	<const name="MMPM" value="6"/>
9807	<const name="Pulse" value="7"/>
9808	<const name="SolAudio" value="8"/>
9809	</enum>
9810
9811	<enum
9812	name="AudioControllerType"
9813	uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
9814	>
9815	<desc>
9816	Virtual audio controller type.
9817	</desc>
9818
9819	<const name="AC97" value="0"/>
9820	<const name="SB16" value="1"/>
9821	</enum>
9822
9823	<interface
9824	name="IAudioAdapter" extends="$unknown"
9825	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
9826	wsmap="managed"
9827	>
9828	<desc>
9829	The IAudioAdapter interface represents the virtual audio adapter of
9830	the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
9831	</desc>
9832	<attribute name="enabled" type="boolean">
9833	<desc>
9834	Flag whether the audio adapter is present in the
9835	guest system. If disabled, the virtual guest hardware will
9836	not contain any audio adapter. Can only be changed when
9837	the VM is not running.
9838	</desc>
9839	</attribute>
9840	<attribute name="audioController" type="AudioControllerType">
9841	<desc>
9842	The audio hardware we emulate.
9843	</desc>
9844	</attribute>
9845	<attribute name="audioDriver" type="AudioDriverType">
9846	<desc>
9847	Audio driver the adapter is connected to. This setting
9848	can only be changed when the VM is not running.
9849	</desc>
9850	</attribute>
9851	</interface>
9852
9853	<!--
9854	// IVRDPServer
9855	/////////////////////////////////////////////////////////////////////////
9856	-->
9857
9858	<enum
9859	name="VRDPAuthType"
9860	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
9861	>
9862	<desc>
9863	VRDP authentication type.
9864	</desc>
9865
9866	<const name="Null" value="0">
9867	<desc><tt>null</tt> value. Also means "no authentication".</desc>
9868	</const>
9869	<const name="External" value="1"/>
9870	<const name="Guest" value="2"/>
9871	</enum>
9872
9873	<interface
9874	name="IVRDPServer" extends="$unknown"
9875	uuid="f4584ae7-6bce-474b-83d6-17d235e6aa89"
9876	wsmap="managed"
9877	>
9878	<attribute name="enabled" type="boolean">
9879	<desc>VRDP server status.</desc>
9880	</attribute>
9881
9882	<attribute name="port" type="unsigned long">
9883	<desc>
9884	VRDP server port number.
9885	<note>
9886	Setting the value of this property to <tt>0</tt> will reset the port
9887	number to the default value which is
9888	currently <tt>3389</tt>. Reading this property will always return a
9889	real port number, even after it has been set to <tt>0</tt> (in which
9890	case the default port is returned).
9891	</note>
9892	</desc>
9893	</attribute>
9894
9895	<attribute name="netAddress" type="wstring">
9896	<desc>VRDP server address.</desc>
9897	</attribute>
9898
9899	<attribute name="authType" type="VRDPAuthType">
9900	<desc>VRDP authentication method.</desc>
9901	</attribute>
9902
9903	<attribute name="authTimeout" type="unsigned long">
9904	<desc>Timeout for guest authentication. Milliseconds.</desc>
9905	</attribute>
9906
9907	<attribute name="allowMultiConnection" type="boolean">
9908	<desc>
9909	Flag whether multiple simultaneous connections to the VM are permitted.
9910	Note that this will be replaced by a more powerful mechanism in the future.
9911	</desc>
9912	</attribute>
9913
9914	<attribute name="reuseSingleConnection" type="boolean">
9915	<desc>
9916	Flag whether the existing connection must be dropped and a new connection
9917	must be established by the VRDP server, when a new client connects in single
9918	connection mode.
9919	</desc>
9920	</attribute>
9921
9922	</interface>
9923
9924
9925	<!--
9926	// ISharedFolder
9927	/////////////////////////////////////////////////////////////////////////
9928	-->
9929
9930	<enumerator
9931	name="ISharedFolderEnumerator" type="ISharedFolder"
9932	uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
9933	/>
9934
9935	<collection
9936	name="ISharedFolderCollection" type="ISharedFolder"
9937	enumerator="ISharedFolderEnumerator"
9938	uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
9939	readonly="yes">
9940
9941	<method name="findByName">
9942	<desc>
9943	Searches this collection for a shared folder with the given logical
9944	name.
9945	<note>
9946	The method returns an error if the given name does not correspond to
9947	any shared folder in the collection.
9948	</note>
9949	</desc>
9950	<param name="name" type="wstring" dir="in">
9951	<desc>Logical name of the shared folder to search for</desc>
9952	</param>
9953	<param name="sharedFolder" type="ISharedFolder" dir="return">
9954	<desc>Found shared folder object</desc>
9955	</param>
9956	</method>
9957
9958	</collection>
9959
9960	<interface
9961	name="ISharedFolder" extends="$unknown"
9962	uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
9963	wsmap="struct"
9964	>
9965	<desc>
9966	The ISharedFolder interface represents a folder in the host computer's
9967	file system accessible from the guest OS running inside a virtual
9968	machine using an associated logical name.
9969
9970	There are three types of shared folders:
9971	<ul>
9972	<li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
9973	folders available to all virtual machines.</li>
9974	<li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
9975	VM-specific shared folders available to the given virtual machine at
9976	startup.</li>
9977	<li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
9978	VM-specific shared folders created in the session context (for
9979	example, when the virtual machine is running) and automatically
9980	discarded when the session is closed (the VM is powered off).</li>
9981	</ul>
9982
9983	Logical names of shared folders must be unique within the given scope
9984	(global, permanent or transient). However, they do not need to be unique
9985	across scopes. In this case, the definition of the shared folder in a
9986	more specific scope takes precedence over definitions in all other
9987	scopes. The order of precedence is (more specific to more general):
9988	<ol>
9989	<li>Transient definitions</li>
9990	<li>Permanent definitions</li>
9991	<li>Global definitions</li>
9992	</ol>
9993
9994	For example, if MyMachine has a shared folder named
9995	<tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
9996	transient shared folder named <tt>C_DRIVE</tt> (that points
9997	to <tt>C:\\\\WINDOWS</tt>) will change the definition
9998	of <tt>C_DRIVE</tt> in the guest OS so
9999	that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
10000	to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
10001	PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
10002	the previous (permanent) definition of <tt>C_DRIVE</tt> that points
10003	to <tt>C:\\</tt> if it still exists.
10004
10005	Note that permanent and transient shared folders of different machines
10006	are in different name spaces, so they don't overlap and don't need to
10007	have unique logical names.
10008
10009	<note>
10010	Global shared folders are not implemented in the current version of the
10011	product.
10012	</note>
10013	</desc>
10014
10015	<attribute name="name" type="wstring" readonly="yes">
10016	<desc>Logical name of the shared folder.</desc>
10017	</attribute>
10018
10019	<attribute name="hostPath" type="wstring" readonly="yes">
10020	<desc>Full path to the shared folder in the host file system.</desc>
10021	</attribute>
10022
10023	<attribute name="accessible" type="boolean" readonly="yes">
10024	<desc>
10025	Whether the folder defined by the host path is currently
10026	accessible or not.
10027	For example, the folder can be unaccessible if it is placed
10028	on the network share that is not available by the time
10029	this property is read.
10030	</desc>
10031	</attribute>
10032
10033	<attribute name="writable" type="boolean" readonly="yes">
10034	<desc>
10035	Whether the folder defined by the host path is writable or
10036	not.
10037	</desc>
10038	</attribute>
10039
10040	</interface>
10041
10042	<!--
10043	// ISession
10044	/////////////////////////////////////////////////////////////////////////
10045	-->
10046
10047	<interface
10048	name="IInternalSessionControl" extends="$unknown"
10049	uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
10050	internal="yes"
10051	wsmap="suppress"
10052	>
10053	<method name="getPID">
10054	<desc>PID of the process that has created this Session object.
10055	</desc>
10056	<param name="pid" type="unsigned long" dir="return"/>
10057	</method>
10058
10059	<method name="getRemoteConsole">
10060	<desc>Returns the console object suitable for remote control.</desc>
10061	<param name="console" type="IConsole" dir="return"/>
10062	</method>
10063
10064	<method name="assignMachine">
10065	<desc>
10066	Assigns the machine object associated with this direct-type
10067	session or informs the session that it will be a remote one
10068	(if machine = NULL).
10069	</desc>
10070	<param name="machine" type="IMachine" dir="in"/>
10071	</method>
10072
10073	<method name="assignRemoteMachine">
10074	<desc>
10075	Assigns the machine and the (remote) console object associated with
10076	this remote-type session.
10077	</desc>
10078	<param name="machine" type="IMachine" dir="in"/>
10079	<param name="console" type="IConsole" dir="in"/>
10080	</method>
10081
10082	<method name="updateMachineState">
10083	<desc>
10084	Updates the machine state in the VM process.
10085	Must be called only in certain cases
10086	(see the method implementation).
10087	</desc>
10088	<param name="aMachineState" type="MachineState" dir="in"/>
10089	</method>
10090
10091	<method name="uninitialize">
10092	<desc>
10093	Uninitializes (closes) this session. Used by VirtualBox to close
10094	the corresponding remote session when the direct session dies
10095	or gets closed.
10096	</desc>
10097	</method>
10098
10099	<method name="onDVDDriveChange">
10100	<desc>
10101	Triggered when settings of the DVD drive object of the
10102	associated virtual machine have changed.
10103	</desc>
10104	</method>
10105
10106	<method name="onFloppyDriveChange">
10107	<desc>
10108	Triggered when settings of the floppy drive object of the
10109	associated virtual machine have changed.
10110	</desc>
10111	</method>
10112
10113	<method name="onNetworkAdapterChange">
10114	<desc>
10115	Triggered when settings of a network adapter of the
10116	associated virtual machine have changed.
10117	</desc>
10118	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
10119	</method>
10120
10121	<method name="onSerialPortChange">
10122	<desc>
10123	Triggered when settings of a serial port of the
10124	associated virtual machine have changed.
10125	</desc>
10126	<param name="serialPort" type="ISerialPort" dir="in"/>
10127	</method>
10128
10129	<method name="onParallelPortChange">
10130	<desc>
10131	Triggered when settings of a parallel port of the
10132	associated virtual machine have changed.
10133	</desc>
10134	<param name="parallelPort" type="IParallelPort" dir="in"/>
10135	</method>
10136
10137	<method name="onVRDPServerChange">
10138	<desc>
10139	Triggered when settings of the VRDP server object of the
10140	associated virtual machine have changed.
10141	</desc>
10142	</method>
10143
10144	<method name="onUSBControllerChange">
10145	<desc>
10146	Triggered when settings of the USB controller object of the
10147	associated virtual machine have changed.
10148	</desc>
10149	</method>
10150
10151	<method name="onSharedFolderChange">
10152	<desc>
10153	Triggered when a permanent (global or machine) shared folder has been
10154	created or removed.
10155	<note>
10156	We don't pass shared folder parameters in this notification because
10157	the order in which parallel notifications are delivered is not defined,
10158	therefore it could happen that these parameters were outdated by the
10159	time of processing this notification.
10160	</note>
10161	</desc>
10162	<param name="global" type="boolean" dir="in"/>
10163	</method>
10164
10165	<method name="onUSBDeviceAttach">
10166	<desc>
10167	Triggered when a request to capture a USB device (as a result
10168	of matched USB filters or direct call to
10169	<link to="IConsole::attachUSBDevice"/>) has completed.
10170	A @c null @a error object means success, otherwise it
10171	describes a failure.
10172	</desc>
10173	<param name="device" type="IUSBDevice" dir="in"/>
10174	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
10175	<param name="maskedInterfaces" type="unsigned long" dir="in"/>
10176	</method>
10177
10178	<method name="onUSBDeviceDetach">
10179	<desc>
10180	Triggered when a request to release the USB device (as a result
10181	of machine termination or direct call to
10182	<link to="IConsole::detachUSBDevice"/>) has completed.
10183	A @c null @a error object means success, otherwise it
10184	</desc>
10185	<param name="id" type="uuid" dir="in"/>
10186	<param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
10187	</method>
10188
10189	<method name="onShowWindow">
10190	<desc>
10191	Called by <link to="IMachine::canShowConsoleWindow()"/> and by
10192	<link to="IMachine::showConsoleWindow()"/> in order to notify
10193	console callbacks
10194	<link to="IConsoleCallback::onCanShowWindow()"/>
10195	and <link to="IConsoleCallback::onShowWindow()"/>.
10196	</desc>
10197	<param name="check" type="boolean" dir="in"/>
10198	<param name="canShow" type="boolean" dir="out"/>
10199	<param name="winId" type="unsigned long long" dir="out"/>
10200	</method>
10201
10202	<method name="accessGuestProperty">
10203	<desc>
10204	Called by <link to="IMachine::getGuestProperty()"/> and by
10205	<link to="IMachine::setGuestProperty()"/> in order to read and
10206	modify guest properties.
10207	</desc>
10208	<param name="name" type="wstring" dir="in"/>
10209	<param name="value" type="wstring" dir="in"/>
10210	<param name="flags" type="wstring" dir="in"/>
10211	<param name="isSetter" type="boolean" dir="in"/>
10212	<param name="retValue" type="wstring" dir="out"/>
10213	<param name="retTimestamp" type="unsigned long long" dir="out"/>
10214	<param name="retFlags" type="wstring" dir="out"/>
10215	</method>
10216
10217	<method name="enumerateGuestProperties">
10218	<desc>
10219	Return a list of the guest properties matching a set of patterns along
10220	with their values, time stamps and flags.
10221	</desc>
10222	<param name="patterns" type="wstring" dir="in">
10223	<desc>
10224	The patterns to match the properties against as a comma-separated
10225	string. If this is empty, all properties currently set will be
10226	returned.
10227	</desc>
10228	</param>
10229	<param name="key" type="wstring" dir="out" safearray="yes">
10230	<desc>
10231	The key names of the properties returned.
10232	</desc>
10233	</param>
10234	<param name="value" type="wstring" dir="out" safearray="yes">
10235	<desc>
10236	The values of the properties returned. The array entries match the
10237	corresponding entries in the @a key array.
10238	</desc>
10239	</param>
10240	<param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
10241	<desc>
10242	The time stamps of the properties returned. The array entries match
10243	the corresponding entries in the @a key array.
10244	</desc>
10245	</param>
10246	<param name="flags" type="wstring" dir="out" safearray="yes">
10247	<desc>
10248	The flags of the properties returned. The array entries match the
10249	corresponding entries in the @a key array.
10250	</desc>
10251	</param>
10252	</method>
10253
10254	</interface>
10255
10256	<interface
10257	name="ISession" extends="$dispatched"
10258	uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
10259	wsmap="managed"
10260	>
10261	<desc>
10262	The ISession interface represents a serialization primitive for virtual
10263	machines.
10264
10265	With VirtualBox, every time one wishes to manipulate a virtual machine
10266	(e.g. change its settings or start execution), a session object is
10267	required. Such an object must be passed to one of the session methods
10268	that open the given session, which then initiates the machine manipulation.
10269
10270	A session serves several purposes: it identifies to the inter-process VirtualBox
10271	code which process is currently working with the virtual machine, and it ensures
10272	that there are no incompatible requests from several processes for the
10273	same virtual machine. Session objects can therefore be thought of as mutex
10274	semaphores that lock virtual machines to prevent conflicting accesses from
10275	several processes.
10276
10277	How sessions objects are used depends on whether you use the Main API
10278	via COM or via the webservice:
10279
10280	<ul>
10281	<li>When using the COM API directly, an object of the Session class from the
10282	VirtualBox type library needs to be created. In regular COM C++ client code,
10283	this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
10284	This object will then act as a local session object in further calls to open
10285	a session.
10286	</li>
10287
10288	<li>In the webservice, the session manager (IWebsessionManager) instead creates
10289	one session object automatically when <link to="IWebsessionManager::logon" />
10290	is called. A managed object reference to that session object can be retrieved by
10291	calling <link to="IWebsessionManager::getSessionObject" />. This session object
10292	reference can then be used to open sessions.
10293	</li>
10294	</ul>
10295
10296	Sessions are mainly used in two variations:
10297
10298	<ul>
10299	<li>
10300	To start a virtual machine in a separate process, one would call
10301	<link to="IVirtualBox::openRemoteSession"/>, which requires a session
10302	object as its first parameter. This session then identifies the caller
10303	and lets him control the started machine (for example, pause machine
10304	execution or power it down) as well as be notified about machine
10305	execution state changes.
10306	</li>
10307
10308	<li>To alter machine settings, or to start machine execution within the
10309	current process, one needs to open a direct session for the machine first by
10310	calling <link to="IVirtualBox::openSession"/>. While a direct session
10311	is open within one process, no any other process may open another direct
10312	session for the same machine. This prevents the machine from being changed
10313	by other processes while it is running or while the machine is being configured.
10314	</li>
10315	</ul>
10316
10317	One also can attach to an existing direct session already opened by
10318	another process (for example, in order to send a control request to the
10319	virtual machine such as the pause or the reset request). This is done by
10320	calling <link to="IVirtualBox::openExistingSession"/>.
10321
10322	<note>
10323	Unless you are trying to write a new VirtualBox front-end that
10324	performs direct machine execution (like the VirtualBox or VBoxSDL
10325	front-ends), don't call <link to="IConsole::powerUp"/> in a direct
10326	session opened by <link to="IVirtualBox::openSession"/> and use this
10327	session only to change virtual machine settings. If you simply want to
10328	start virtual machine execution using one of the existing front-ends
10329	(for example the VirtualBox GUI or headless server), simply use
10330	<link to="IVirtualBox::openRemoteSession"/>; these front-ends
10331	will power up the machine automatically for you.
10332	</note>
10333	</desc>
10334
10335	<attribute name="state" type="SessionState" readonly="yes">
10336	<desc>Current state of this session.</desc>
10337	</attribute>
10338
10339	<attribute name="type" type="SessionType" readonly="yes">
10340	<desc>
10341	Type of this session. The value of this attribute is valid only
10342	if the session is currently open (i.e. its #state is SessionType::SessionOpen),
10343	otherwise an error will be returned.
10344	</desc>
10345	</attribute>
10346
10347	<attribute name="machine" type="IMachine" readonly="yes">
10348	<desc>Machine object associated with this session.</desc>
10349	</attribute>
10350
10351	<attribute name="console" type="IConsole" readonly="yes">
10352	<desc>Console object associated with this session.</desc>
10353	</attribute>
10354
10355	<method name="close">
10356	<desc>
10357	Closes a session that was previously opened.
10358
10359	It is recommended that every time an "open session" method (such as
10360	<link to="IVirtualBox::openRemoteSession" /> or
10361	<link to="IVirtualBox::openSession" />) has been called to
10362	manipulate a virtual machine, the caller invoke
10363	ISession::close() when it's done doing so. Since sessions are
10364	serialization primitives much like ordinary mutexes, they are
10365	best used the same way: for each "open" call, there should be
10366	a matching "close" call, even when errors occur.
10367
10368	Otherwise, if a direct session for a machine opened with
10369	<link to="IVirtualBox::openSession()"/> is not explicitly closed
10370	when the application terminates, the state of the machine will
10371	be set to <link to="MachineState::Aborted" /> on the server.
10372
10373	Generally, it is recommended to close all open sessions explicitly
10374	before terminating the application (no matter what is the reason of
10375	the termination).
10376
10377	<note>
10378	Do not expect the session state (<link to="ISession::state" />
10379	to return to "Closed" immediately after you invoke
10380	ISession::close(), particularly if you have started a remote
10381	session to execute the VM in a new process. The session state will
10382	automatically return to "Closed" once the VM is no longer executing,
10383	which can of course take a very long time.
10384	</note>
10385	</desc>
10386	</method>
10387
10388	</interface>
10389
10390	<!--
10391	// ISATAController
10392	/////////////////////////////////////////////////////////////////////////
10393	-->
10394
10395	<interface
10396	name="ISATAController" extends="$unknown"
10397	uuid="9a4b868b-1376-4533-8ef5-065b8e8cedff"
10398	wsmap="managed"
10399	>
10400	<attribute name="enabled" type="boolean">
10401	<desc>
10402	Flag whether the SATA controller is present in the
10403	guest system. If disabled, the virtual guest hardware will
10404	not contain any SATA controller. Can only be changed when
10405	the VM is powered off.
10406	</desc>
10407	</attribute>
10408
10409	<attribute name="portCount" type="unsigned long">
10410	<desc>
10411	The number of usable ports on the SATA controller.
10412	It ranges from 1 to 30.
10413	</desc>
10414	</attribute>
10415
10416	<method name="GetIDEEmulationPort">
10417	<desc>Gets the corresponding port number which is emulated as an IDE device.</desc>
10418	<param name="devicePosition" type="long" dir="in"/>
10419	<param name="portNumber" type="long" dir="return"/>
10420	</method>
10421
10422	<method name="SetIDEEmulationPort">
10423	<desc>Sets the port number which is emulated as an IDE device.</desc>
10424	<param name="devicePosition" type="long" dir="in"/>
10425	<param name="portNumber" type="long" dir="in"/>
10426	</method>
10427
10428	</interface>
10429
10430	<if target="wsdl">
10431
10432	<!--
10433	// IManagedObjectRef
10434	/////////////////////////////////////////////////////////////////////////
10435	-->
10436
10437	<interface
10438	name="IManagedObjectRef" extends="$unknown"
10439	uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
10440	internal="yes"
10441	wsmap="managed"
10442	wscpp="hardcoded"
10443	>
10444	<desc>
10445	Managed object reference.
10446
10447	Only within the webservice, a managed object reference (which is really
10448	an opaque number) allows a webservice client to address an object
10449	that lives in the address space of the webservice server.
10450
10451	Behind each managed object reference, there is a COM object that lives
10452	in the webservice server's address space. The COM object is not freed
10453	until the managed object reference is released, either by an explicit
10454	call to <link to="IManagedObjectRef::release" /> or by logging off from
10455	the webservice (<link to="IWebsessionManager::logoff" />), which releases
10456	all objects created during the webservice session.
10457
10458	Whenever a method call of the VirtualBox API returns a COM object, the
10459	webservice representation of that method will instead return a
10460	managed object reference, which can then be used to invoke methods
10461	on that object.
10462	</desc>
10463
10464	<method name="getInterfaceName">
10465	<desc>
10466	Returns the name of the interface that this managed object represents,
10467	for example, "IMachine", as a string.
10468	</desc>
10469	<param name="return" type="wstring" dir="return"/>
10470	</method>
10471
10472	<method name="release">
10473	<desc>
10474	Releases this managed object reference and frees the resources that
10475	were allocated for it in the webservice server process. After calling
10476	this method, the identifier of the reference can no longer be used.
10477	</desc>
10478	</method>
10479
10480	</interface>
10481
10482	<!--
10483	// IWebsessionManager
10484	/////////////////////////////////////////////////////////////////////////
10485	-->
10486
10487	<interface
10488	name="IWebsessionManager" extends="$unknown"
10489	uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
10490	internal="yes"
10491	wsmap="global"
10492	wscpp="hardcoded"
10493	>
10494	<desc>
10495	Websession manager. This provides essential services
10496	to webservice clients.
10497	</desc>
10498	<method name="logon">
10499	<desc>
10500	Logs a new client onto the webservice and returns a managed object reference to
10501	the IVirtualBox instance, which the client can then use as a basis to further
10502	queries, since all calls to the VirtualBox API are based on the IVirtualBox
10503	interface, in one way or the other.
10504	</desc>
10505	<param name="username" type="wstring" dir="in"/>
10506	<param name="password" type="wstring" dir="in"/>
10507	<param name="return" type="IVirtualBox" dir="return"/>
10508	</method>
10509
10510	<method name="getSessionObject">
10511	<desc>
10512	Returns a managed object reference to the internal ISession object that was created
10513	for this web service session when the client logged on.
10514
10515	<see>ISession</see>
10516	</desc>
10517	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
10518	<param name="return" type="ISession" dir="return"/>
10519	</method>
10520
10521	<method name="logoff">
10522	<desc>
10523	Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
10524	and destroys all resources associated with the session (most importantly, all
10525	managed objects created in the server while the session was active).
10526	</desc>
10527	<param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
10528	</method>
10529
10530	</interface>
10531
10532	</if>
10533
10534	<!--
10535	// IPerformanceCollector & friends
10536	/////////////////////////////////////////////////////////////////////////
10537	-->
10538
10539	<interface
10540	name="IPerformanceMetric" extends="$unknown"
10541	uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
10542	>
10543	<desc>
10544	The IPerformanceMetric interface represents parameters of the given
10545	performance metric.
10546	</desc>
10547
10548	<attribute name="metricName" type="wstring" readonly="yes">
10549	<desc>
10550	Name of the metric.
10551	</desc>
10552	</attribute>
10553
10554	<attribute name="object" type="$unknown" readonly="yes">
10555	<desc>
10556	Object this metric belongs to.
10557	</desc>
10558	</attribute>
10559
10560	<attribute name="description" type="wstring" readonly="yes">
10561	<desc>
10562	Textual description of the metric.
10563	</desc>
10564	</attribute>
10565
10566	<attribute name="period" type="unsigned long" readonly="yes">
10567	<desc>
10568	Time interval between samples, measured in seconds.
10569	</desc>
10570	</attribute>
10571
10572	<attribute name="count" type="unsigned long" readonly="yes">
10573	<desc>
10574	Number of recent samples retained by the performance collector for this
10575	metric.
10576
10577	When the collected sample count exceeds this number, older samples
10578	are discarded.
10579	</desc>
10580	</attribute>
10581
10582	<attribute name="unit" type="wstring" readonly="yes">
10583	<desc>
10584	Unit of measurement.
10585	</desc>
10586	</attribute>
10587
10588	<attribute name="minimumValue" type="long" readonly="yes">
10589	<desc>
10590	Minimum possible value of this metric.
10591	</desc>
10592	</attribute>
10593
10594	<attribute name="maximumValue" type="long" readonly="yes">
10595	<desc>
10596	Maximum possible value of this metric.
10597	</desc>
10598	</attribute>
10599	</interface>
10600
10601	<interface
10602	name="IPerformanceCollector" extends="$unknown"
10603	uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
10604	wsmap="managed"
10605	>
10606	<desc>
10607	The IPerformanceCollector interface represents a service that collects and
10608	stores performance metrics data.
10609
10610	Performance metrics are associated with objects like IHost and
10611	IMachine. Each object has a distinct set of performance metrics.
10612	The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
10613
10614	Metric data are collected at the specified intervals and are retained
10615	internally. The interval and the number of samples retained can be set
10616	with <link to="IPerformanceCollector::setupMetrics" />.
10617
10618	Metrics are organized hierarchically, each level separated by slash (/).
10619	General scheme for metric name is
10620	"Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
10621	metric name stands for: CPU category, Load metric, User submetric, average
10622	aggregate. An aggregate function is computed over all retained data. Valid
10623	aggregate functions are:
10624
10625	<ul>
10626	<li>avg -- average</li>
10627	<li>min -- minimum</li>
10628	<li>max -- maximum</li>
10629	</ul>
10630
10631	"Category/Metric" together form base metric name. A base metric is the
10632	smallest unit for which a sampling interval and the number of retained
10633	samples can be set. Only base metrics can be enabled and disabled. All
10634	sub-metrics are collected when their base metric is collected.
10635	Collected values for any set of sub-metrics can be queried with
10636	<link to="IPerformanceCollector::queryMetricsData" />. When setting up
10637	metric parameters, querying metric data, enabling or disabling metrics
10638	wildcards can be used in metric names to specify a subset of metrics. For
10639	example, to select all CPU-related metrics use <tt>CPU/*</tt>, all
10640	averages can be queried using <tt>*:avg</tt> and so on. To query metric
10641	values without aggregates <tt>*:</tt> can be used.
10642
10643	The valid names for base metrics are:
10644
10645	<ul>
10646	<li>CPU/Load</li>
10647	<li>CPU/MHz</li>
10648	<li>RAM/Usage</li>
10649	</ul>
10650
10651	The general sequence for collecting and retrieving the metrics is:
10652	<ul>
10653	<li>
10654	Obtain an instance of IPerformanceCollector with
10655	<link to="IVirtualBox::performanceCollector" />
10656	</li>
10657	<li>
10658	Allocate and populate an array with references to objects the metrics
10659	will be collected for. Use references to IHost and IMachine objects.
10660	</li>
10661	<li>
10662	Allocate and populate an array with base metric names the data will be
10663	collected for.
10664	</li>
10665	<li>
10666	Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
10667	metric data will be collected and stored.
10668	</li>
10669	<li>
10670	Wait for the data to get collected.
10671	</li>
10672	<li>
10673	Allocate and populate an array with references to objects the metric
10674	values will be queried for. You can re-use the object array used for
10675	setting base metrics.
10676	</li>
10677	<li>
10678	Allocate and populate an array with metric names the data will be
10679	collected for. Note that metric names differ from base metric names.
10680	</li>
10681	<li>
10682	Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
10683	have been collected so far are returned. Note that the values are still
10684	retained internally and data collection continues.
10685	</li>
10686	</ul>
10687
10688	For an example of usage refer to the following files in VirtualBox SDK:
10689	<ul>
10690	<li>
10691	Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
10692	</li>
10693	<li>
10694	Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
10695	</li>
10696	</ul>
10697	</desc>
10698
10699	<attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
10700	<desc>
10701	Array of unique names of metrics.
10702
10703	This array represents all metrics supported by the performance
10704	collector. Individual objects do not necessarily support all of them.
10705	<link to="IPerformanceCollector::getMetrics"/> can be used to get the
10706	list of supported metrics for a particular object.
10707	</desc>
10708	</attribute>
10709
10710	<method name="getMetrics">
10711	<desc>
10712	Returns parameters of specified metrics for a set of objects.
10713	<note>
10714	@c Null metrics array means all metrics. @c Null object array means
10715	all existing objects.
10716	</note>
10717	</desc>
10718	<param name="metricNames" type="wstring" dir="in" safearray="yes">
10719	<desc>
10720	Metric name filter. Currently, only a comma-separated list of metrics
10721	is supported.
10722	</desc>
10723	</param>
10724	<param name="objects" type="$unknown" dir="in" safearray="yes">
10725	<desc>
10726	Set of objects to return metric parameters for.
10727	</desc>
10728	</param>
10729	<param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
10730	<desc>
10731	Array of returned metric parameters.
10732	</desc>
10733	</param>
10734	</method>
10735
10736	<method name="setupMetrics">
10737	<desc>
10738	Sets parameters of specified base metrics for a set of objects. Returns
10739	an array of <link to="IPerformanceMetric" /> describing the metrics have
10740	been affected.
10741	<note>
10742	@c Null or empty metric name array means all metrics. @c Null or empty
10743	object array means all existing objects. If metric name array contains
10744	a single element and object array contains many, the single metric
10745	name array element is applied to each object array element to form
10746	metric/object pairs.
10747	</note>
10748	</desc>
10749	<param name="metricNames" type="wstring" dir="in" safearray="yes">
10750	<desc>
10751	Metric name filter. Comma-separated list of metrics with wildcard
10752	support.
10753	</desc>
10754	</param>
10755	<param name="objects" type="$unknown" dir="in" safearray="yes">
10756	<desc>
10757	Set of objects to setup metric parameters for.
10758	</desc>
10759	</param>
10760	<param name="period" type="unsigned long" dir="in">
10761	<desc>
10762	Time interval in seconds between two consecutive samples of performance
10763	data.
10764	</desc>
10765	</param>
10766	<param name="count" type="unsigned long" dir="in">
10767	<desc>
10768	Number of samples to retain in performance data history. Older samples
10769	get discarded.
10770	</desc>
10771	</param>
10772	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
10773	<desc>
10774	Array of metrics that have been modified by the call to this method.
10775	</desc>
10776	</param>
10777	</method>
10778
10779	<method name="enableMetrics">
10780	<desc>
10781	Turns on collecting specified base metrics. Returns an array of
10782	<link to="IPerformanceMetric" /> describing the metrics have been
10783	affected.
10784	<note>
10785	@c Null or empty metric name array means all metrics. @c Null or empty
10786	object array means all existing objects. If metric name array contains
10787	a single element and object array contains many, the single metric
10788	name array element is applied to each object array element to form
10789	metric/object pairs.
10790	</note>
10791	</desc>
10792	<param name="metricNames" type="wstring" dir="in" safearray="yes">
10793	<desc>
10794	Metric name filter. Comma-separated list of metrics with wildcard
10795	support.
10796	</desc>
10797	</param>
10798	<param name="objects" type="$unknown" dir="in" safearray="yes">
10799	<desc>
10800	Set of objects to enable metrics for.
10801	</desc>
10802	</param>
10803	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
10804	<desc>
10805	Array of metrics that have been modified by the call to this method.
10806	</desc>
10807	</param>
10808	</method>
10809
10810	<method name="disableMetrics">
10811	<desc>
10812	Turns off collecting specified base metrics. Returns an array of
10813	<link to="IPerformanceMetric" /> describing the metrics have been
10814	affected.
10815	<note>
10816	@c Null or empty metric name array means all metrics. @c Null or empty
10817	object array means all existing objects. If metric name array contains
10818	a single element and object array contains many, the single metric
10819	name array element is applied to each object array element to form
10820	metric/object pairs.
10821	</note>
10822	</desc>
10823	<param name="metricNames" type="wstring" dir="in" safearray="yes">
10824	<desc>
10825	Metric name filter. Comma-separated list of metrics with wildcard
10826	support.
10827	</desc>
10828	</param>
10829	<param name="objects" type="$unknown" dir="in" safearray="yes">
10830	<desc>
10831	Set of objects to disable metrics for.
10832	</desc>
10833	</param>
10834	<param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
10835	<desc>
10836	Array of metrics that have been modified by the call to this method.
10837	</desc>
10838	</param>
10839	</method>
10840
10841	<method name="queryMetricsData">
10842	<desc>
10843	Queries collected metrics data for a set of objects.
10844
10845	The data itself and related metric information are returned in seven
10846	parallel and one flattened array of arrays. Elements of
10847	<tt>returnMetricNames, returnObjects, returnUnits, returnScales,
10848	returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
10849	the same index describe one set of values corresponding to a single
10850	metric.
10851
10852	The <tt>returnData</tt> parameter is a flattened array of arrays. Each
10853	start and length of a sub-array is indicated by
10854	<tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
10855	value for metric <tt>metricNames[i]</tt> is at
10856	<tt>returnData[returnIndices[i]]</tt>.
10857
10858	<note>
10859	@c Null or empty metric name array means all metrics. @c Null or empty
10860	object array means all existing objects. If metric name array contains
10861	a single element and object array contains many, the single metric
10862	name array element is applied to each object array element to form
10863	metric/object pairs.
10864	</note>
10865	<note>
10866	Data collection continues behind the scenes after call to @c
10867	queryMetricsData. The return data can be seen as the snapshot of
10868	the current state at the time of @c queryMetricsData call. The
10869	internally kept metric values are not cleared by the call. This makes
10870	possible querying different subsets of metrics or aggregates with
10871	subsequent calls. If periodic querying is needed it is highly
10872	suggested to query the values with @c interval*count period to avoid
10873	confusion. This way a completely new set of data values will be
10874	provided by each query.
10875	</note>
10876	</desc>
10877	<param name="metricNames" type="wstring" dir="in" safearray="yes">
10878	<desc>
10879	Metric name filter. Comma-separated list of metrics with wildcard
10880	support.
10881	</desc>
10882	</param>
10883	<param name="objects" type="$unknown" dir="in" safearray="yes">
10884	<desc>
10885	Set of objects to query metrics for.
10886	</desc>
10887	</param>
10888	<param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
10889	<desc>
10890	Names of metrics returned in @c returnData.
10891	</desc>
10892	</param>
10893	<param name="returnObjects" type="$unknown" dir="out" safearray="yes">
10894	<desc>
10895	Objects associated with metrics returned in @c returnData.
10896	</desc>
10897	</param>
10898	<param name="returnUnits" type="wstring" dir="out" safearray="yes">
10899	<desc>
10900	Units of measurement for each returned metric.
10901	</desc>
10902	</param>
10903	<param name="returnScales" type="unsigned long" dir="out" safearray="yes">
10904	<desc>
10905	Divisor that should be applied to return values in order to get
10906	floating point values. For example:
10907	<tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
10908	will retrieve the floating point value of i-th sample of the first
10909	metric.
10910	</desc>
10911	</param>
10912	<param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
10913	<desc>
10914	Sequence numbers of the first elements of value sequences of particular metrics
10915	returned in @c returnData. For aggregate metrics it is the sequence number of
10916	the sample the aggregate started calculation from.
10917	</desc>
10918	</param>
10919	<param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
10920	<desc>
10921	Indices of the first elements of value sequences of particular metrics
10922	returned in @c returnData.
10923	</desc>
10924	</param>
10925	<param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
10926	<desc>
10927	Lengths of value sequences of particular metrics.
10928	</desc>
10929	</param>
10930	<param name="returnData" type="long" dir="return" safearray="yes">
10931	<desc>
10932	Flattened array of all metric data containing sequences of values for
10933	each metric.
10934	</desc>
10935	</param>
10936	</method>
10937
10938	</interface>
10939
10940	<module name="VBoxSVC" context="LocalServer">
10941	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
10942	namespace="virtualbox.org">
10943	<interface name="IVirtualBox" default="yes"/>
10944	</class>
10945	</module>
10946
10947	<module name="VBoxC" context="InprocServer" threadingModel="Free">
10948	<class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
10949	namespace="virtualbox.org">
10950	<interface name="ISession" default="yes"/>
10951	</class>
10952	</module>
10953
10954	</library>
10955
10956	</idl>
10957	<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->

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

Download in other formats:

Original Format