VirtualBox.xidl@ 2034

Last change on this file since 2034 was 2029, checked in by vboxsync, 18 years ago
Main: Added IVirtualBox::findHardDisk(). VBoxSDL: Fixed so that .vmdk images can be passed using the -hda switch.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 290.6 KB

Line
1	<?xml version="1.0" ?>
2
3	<!--
4	* Master declaration for VirtualBox's public COM/XPCOM API.
5	* From this document, the build system generates several files
6	* that are then used during the build process:
7	*
8	* - out/<platform>/bin/sdk/idl/VirtualBox[_XPCOM].idl, a
9	* pseudo-IDL file that represents the interfaces in IDL;
10	*
11	* - out/<platform>/bin/sdk/include/VirtualBox[_XPCOM].h, which
12	* gets included from the include/VBox/com/VirtualBox.h
13	* wrapper, to allow clients to access the API;
14	*
15	* - also, another intermediate file that is then used to
16	* produce the official Doxygen documentation of the API.
17	*
18	* Copyright (C) 2006 InnoTek Systemberatung GmbH
19	*
20	* This file is part of VirtualBox Open Source Edition (OSE), as
21	* available from http://www.virtualbox.org. This file is free software;
22	* you can redistribute it and/or modify it under the terms of the GNU
23	* General Public License as published by the Free Software Foundation,
24	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
25	* distribution. VirtualBox OSE is distributed in the hope that it will
26	* be useful, but WITHOUT ANY WARRANTY of any kind.
27	*
28	* If you received this file as part of a commercial VirtualBox
29	* distribution, then only the terms of your commercial VirtualBox
30	* license agreement apply instead of the previous paragraph.
31	-->
32
33	<idl>
34
35	<if target="midl">
36	<cpp line="enum {"/>
37	<cpp line=" kTypeLibraryMajorVersion = 1,"/>
38	<cpp line=" kTypeLibraryMinorVersion = 0"/>
39	<cpp line="};"/>
40	</if>
41
42	<if target="xpidl">
43	<!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
44	<cpp>
45	// currenty, nsISupportsImpl.h lacks the below-like macros
46	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
47	#define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
48	NS_IMPL_THREADSAFE_ADDREF(_class) \
49	NS_IMPL_THREADSAFE_RELEASE(_class) \
50	NS_IMPL_QUERY_INTERFACE1_CI(_class, _interface) \
51	NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
52	#endif
53	#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
54	#define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
55	NS_IMPL_THREADSAFE_ADDREF(_class) \
56	NS_IMPL_THREADSAFE_RELEASE(_class) \
57	NS_IMPL_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
58	NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
59	#endif
60	</cpp>
61	</if>
62
63	<module
64	name="VirtualBox"
65	uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
66	version="1.3"
67	desc="InnoTek VirtualBox Type Library"
68	supportsErrorInfo="yes"
69	>
70
71	<!--
72	// all common enums
73	/////////////////////////////////////////////////////////////////////////
74	-->
75
76	<enum
77	name="TriStateBool"
78	uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
79	>
80	<desc>
81	This represents a boolean variable having a third state, default.
82	</desc>
83
84	<const name="False" value="0"/>
85	<const name="True" value="1"/>
86	<const name="Default" value="2"/>
87	</enum>
88
89	<enum
90	name="MachineState"
91	uuid="b8bb15f7-4fa2-4e84-87a8-b4677dd87deb"
92	>
93	<desc>
94	Virtual machine execution state. This enumeration represents possible
95	values of the <link to="IMachine::state"/> attribute.
96	</desc>
97
98	<const name="InvalidMachineState" value="0"/>
99	<const name="PoweredOff" value="1">
100	<desc>
101	The machine is not running.
102	</desc>
103	</const>
104	<const name="Saved" value="2">
105	<desc>
106	The machine is not currently running, but the execution state
107	of the machine has been saved to an external file when it
108	was running.
109	<note>
110	No any machine settings can be altered when the machine
111	is in this state.
112	</note>
113	</desc>
114	</const>
115	<const name="Aborted" value="3">
116	<desc>
117	A process that run the machine has abnormally terminated.
118	Other than that, this value is equivalent to #PoweredOff.
119	</desc>
120	</const>
121	<const name="Running" value="4">
122	<desc>
123	The machine is currently being executed.
124	<note>
125	This value can be used in comparison expressions:
126	all state values below it describe a virtual machine that is
127	not currently being executed (i.e., it is completely out of
128	action).
129	</note>
130	</desc>
131	</const>
132	<const name="Paused" value="5">
133	<desc>
134	The execution of the machine has been paused.
135	<note>
136	This value can be used in comparison expressions:
137	all state values above it represent unstable states of the
138	virtual machine. No any settings can be altered when the
139	VM is in one of the unstable sates.
140	</note>
141	</desc>
142	</const>
143	<const name="Starting" value="6">
144	<desc>
145	The machine is being started after
146	<link to="IConsole::powerUp">powering it on</link> from a
147	zero execution state.
148	</desc>
149	</const>
150	<const name="Stopping" value="7">
151	<desc>
152	The machine is being normally stopped
153	(after explicitly <link to="IConsole::powerDown">powering it off</link>,
154	or after the guest OS has initiated a shutdown sequence).
155	</desc>
156	</const>
157	<const name="Saving" value="8">
158	<desc>
159	The machine is saving its execution state to a file as a
160	result of calling <link to="IConsole::saveState"/> or an online
161	snapshot of the machine is being taken using
162	<link to="IConsole::takeSnapshot"/>.
163	</desc>
164	</const>
165	<const name="Restoring" value="9">
166	<desc>
167	The execution state of the machine is being restored from a file
168	after <link to="IConsole::powerUp">powering it on</link> from
169	a saved execution state.
170	</desc>
171	</const>
172	<const name="Discarding" value="10">
173	<desc>
174	A snapshot of the machine is being discarded after calling
175	<link to="IConsole::discardSnapshot"/> or its current state is
176	being discarded after <link to="IConsole::discardCurrentState"/>.
177	</desc>
178	</const>
179	</enum>
180
181	<enum
182	name="SessionState"
183	uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
184	>
185	<desc>
186	Session state. This enumeration represents possible values of
187	<link to="IMachine::sessionState"/> and <link to="ISession::state"/>
188	attributes. Idividual value descriptions contain the appropriate
189	meaning for every case.
190	</desc>
191
192	<const name="InvalidSessionState" value="0"/>
193	<const name="SessionClosed" value="1">
194	<desc>
195	The machine has no open sessions (<link to="IMachine::sessionState"/>);
196	the session is closed (<link to="ISession::state"/>)
197	</desc>
198	</const>
199	<const name="SessionOpen" value="2">
200	<desc>
201	The machine has an open direct session (<link to="IMachine::sessionState"/>);
202	the session is open (<link to="ISession::state"/>)
203	</desc>
204	</const>
205	<const name="SessionSpawning" value="3">
206	<desc>
207	A new (direct) session is being opened for the machine
208	as a result of <link to="IVirtualBox::openRemoteSession()"/>
209	call (<link to="IMachine::sessionState"/>);
210	the session is currently being opened
211	as a result of <link to="IVirtualBox::openRemoteSession()"/>
212	call (<link to="ISession::state"/>)
213	</desc>
214	</const>
215	<const name="SessionClosing" value="4">
216	<desc>
217	The direct session is being closed (<link to="IMachine::sessionState"/>);
218	the session is being closed (<link to="ISession::state"/>)
219	</desc>
220	</const>
221	</enum>
222
223	<enum
224	name="SessionType"
225	uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
226	>
227	<desc>
228	Session type. This enumeration represents possible values of the
229	<link to="ISession::type"/> attribute.
230	</desc>
231
232	<const name="InvalidSessionType" value="0"/>
233	<const name="DirectSession" value="1">
234	<desc>
235	Direct session
236	(opened by <link to="IVirtualBox::openSession()"/>)
237	</desc>
238	</const>
239	<const name="RemoteSession" value="2">
240	<desc>
241	Remote session
242	(opened by <link to="IVirtualBox::openRemoteSession()"/>)
243	</desc>
244	</const>
245	<const name="ExistingSession" value="3">
246	<desc>
247	Existing session
248	(opened by <link to="IVirtualBox::openExistingSession()"/>)
249	</desc>
250	</const>
251	</enum>
252
253	<enum
254	name="DeviceType"
255	uuid="8B7F8ADE-E8F7-42a4-9661-9F5092C4DB4C"
256	>
257	<desc>
258	Device type.
259	</desc>
260	<const name="NoDevice" value="0">
261	<desc>
262	No Device. This value is not used by
263	<link to="IConsole::getDeviceActivity"/>
264	</desc>
265	</const>
266	<const name="FloppyDevice" value="1">
267	<desc>Floppy device.</desc>
268	</const>
269	<const name="DVDDevice" value="2">
270	<desc>CD/DVD-ROM device.</desc>
271	</const>
272	<const name="HardDiskDevice" value="3">
273	<desc>Hard disk device.</desc>
274	</const>
275	<const name="NetworkDevice" value="4">
276	<desc>Network device.</desc>
277	</const>
278	<const name="USBDevice" value="5">
279	<desc>USB device.</desc>
280	</const>
281	</enum>
282
283	<enum
284	name="DeviceActivity"
285	uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
286	>
287	<const name="InvalidActivity" value="0"/>
288	<const name="DeviceIdle" value="1"/>
289	<const name="DeviceReading" value="2"/>
290	<const name="DeviceWriting" value="3"/>
291	</enum>
292
293	<enum
294	name="ResourceUsage"
295	uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
296	>
297	<desc>
298	Usage type constants for
299	<link to="IVirtualBox::getDVDImageUsage"/> and
300	<link to="IVirtualBox::getFloppyImageUsage"/>.
301	</desc>
302	<const name="InvalidUsage" value="0"/>
303	<const name="PermanentUsage" value="1">
304	<desc>
305	Scopes the VMs that use the resource permanently
306	(the information about this usage is stored in the VM
307	settings file).
308	</desc>
309	</const>
310	<const name="TemporaryUsage" value="2">
311	<desc>
312	Scopes the VMs that are temporarily using the resource
313	(the information about the usage is not yet saved in the VM
314	settings file). Temporary usage can take place only in the
315	context of an open session.
316	</desc>
317	</const>
318	<const name="AllUsage" value="3">
319	<desc>
320	Combines PermanentUsage and TemporaryUsage.
321	</desc>
322	</const>
323	</enum>
324
325	<enum
326	name="DiskControllerType"
327	uuid="1115b810-2ee7-4ebd-8b39-92e98c9a2b48"
328	>
329	<const name="InvalidController" value="0"/>
330	<const name="IDE0Controller" value="1"/>
331	<const name="IDE1Controller" value="2"/>
332	</enum>
333
334	<enum
335	name="ClipboardMode"
336	uuid="33364716-4008-4701-8f14-be0fa3d62950"
337	>
338	<const name="ClipDisabled" value="0"/>
339	<const name="ClipHostToGuest" value="1"/>
340	<const name="ClipGuestToHost" value="2"/>
341	<const name="ClipBidirectional" value="3"/>
342	</enum>
343
344	<!--
345	// IVirtualBoxErrorInfo
346	/////////////////////////////////////////////////////////////////////////
347	-->
348
349	<interface
350	name="IVirtualBoxErrorInfo" extends="$errorinfo"
351	uuid="37EDE76D-6E16-4CE4-9D48-2C5A87AFFEA2"
352	supportsErrorInfo="no"
353	>
354	<desc>
355	The IVirtualBoxErrorInfo interface represents extended error information
356	that can be set by components after unsuccessful method invocation and
357	returned to the client in addition to the result code.
358
359	In MS COM, this interface extends the IErrorInfo interface,
360	in XPCOM, it extends the nsIException interface. In both cases,
361	it provides a set of common attributes to retrieve error information.
362	</desc>
363
364	<attribute name="resultCode" type="result" readonly="yes">
365	<desc>
366	Result code of the error.
367	Usually, it will be the same as the result code returned
368	by the method that provided this error information, but not
369	always. For example, on Win32, CoCreateInstance() will most
370	likely return E_NOINTERFACE upon unsuccessful component
371	instantiation attempt, but not the value the component factory
372	returned.
373	<note>
374	In MS COM, there is no equivalent.
375	In XPCOM, it is the same as to nsIException::result.
376	</note>
377	</desc>
378	</attribute>
379
380	<attribute name="interfaceID" type="uuid" readonly="yes">
381	<desc>
382	UUID of the interface that defined the error.
383	<note>
384	In MS COM, it is the same as to IErrorInfo::GetGUID.
385	In XPCOM, there is no equivalent.
386	</note>
387	</desc>
388	</attribute>
389
390	<attribute name="component" type="wstring" readonly="yes">
391	<desc>
392	Name of the component that generated the error.
393	<note>
394	In MS COM, it is the same as to IErrorInfo::GetSource.
395	In XPCOM, there is no eqiuvalent.
396	</note>
397	</desc>
398	</attribute>
399
400	<attribute name="text" type="wstring" readonly="yes">
401	<desc>
402	Text description of the error.
403	<note>
404	In MS COM, it is the same as IErrorInfo::GetDescription.
405	In XPCOM, it is the same as to nsIException::message.
406	</note>
407	</desc>
408	</attribute>
409
410	</interface>
411
412
413	<!--
414	// IVirtualBox
415	/////////////////////////////////////////////////////////////////////////
416	-->
417
418	<interface
419	name="IVirtualBoxCallback" extends="$unknown"
420	uuid="1293842f-0380-47cf-80b5-e4f821861b26"
421	>
422	<method name="onMachineStateChange">
423	<desc>
424	The execution state of the given machine has changed.
425	<see>IMachine::state</see>
426	</desc>
427	<param name="machineId" type="uuid" dir="in">
428	<desc>ID of the machine this event relates to.</desc>
429	</param>
430	<param name="state" type="MachineState" dir="in">
431	<desc>New execution state.</desc>
432	</param>
433	</method>
434
435	<method name="onMachineDataChange">
436	<desc>
437	Any of the settings of the given machine has changed.
438	</desc>
439	<param name="machineId" type="uuid" dir="in">
440	<desc>ID of the machine this event relates to.</desc>
441	</param>
442	</method>
443
444	<method name="onExtraDataCanChange">
445	<desc>
446	Notification when someone tries to change extra data for
447	either the given machine or (if null) global extra data.
448	This gives the chance to veto against changes.
449	</desc>
450	<param name="machineId" type="uuid" dir="in">
451	<desc>
452	ID of the machine this event relates to.
453	Nul for global extra data change requests.
454	</desc>
455	</param>
456	<param name="key" type="wstring" dir="in">
457	<desc>
458	Extra data key for the attempted write.
459	</desc>
460	</param>
461	<param name="value" type="wstring" dir="in">
462	<desc>
463	Extra data value for the given key.
464	</desc>
465	</param>
466	<param name="allowChange" type="boolean" dir="return">
467	<desc>
468	Flag to indicate whether the callee agrees (true)
469	or vetoes against the change (false).
470	</desc>
471	</param>
472	</method>
473
474	<method name="onExtraDataChange">
475	<desc>
476	Notification when machine specific or global extra data
477	has changed.
478	</desc>
479	<param name="machineId" type="uuid" dir="in">
480	<desc>
481	ID of the machine this event relates to.
482	Null for global extra data changes.
483	</desc>
484	</param>
485	<param name="key" type="wstring" dir="in">
486	<desc>
487	Extra data key that has changed.
488	</desc>
489	</param>
490	<param name="value" type="wstring" dir="in">
491	<desc>
492	Extra data value for the given key.
493	</desc>
494	</param>
495	</method>
496
497	<method name="onMediaRegistered">
498	<desc>
499	The given media was registered or unregistered
500	within this VirtualBox installation.
501
502	The @a mediaType parameter describes what type of
503	media the specified @a mediaId refers to. Possible
504	values are:
505
506	- <link to="HardDiskDevice"/>: the media is a hard disk
507	that, if registered, can be obtained using the
508	<link to="IVirtualBox::getHardDisk"/> call.
509	- <link to="DVDDevice"/>: the media is a CD/DVD image
510	that, if registered, can be obtained using the
511	<link to="IVirtualBox::getDVDImage"/> call.
512	- <link to="FloppyDevice"/>: the media is a Floppy image
513	that, if registered, can be obtained using the
514	<link to="IVirtualBox::getFloppyImage"/> call.
515
516	Note that if this is a deregistration notification,
517	there is no way to access the object representing the
518	unregistered media. It is supposed that the
519	application will do required cleanup based on the @a
520	mediaId value.
521	</desc>
522	<param name="mediaId" type="uuid" dir="in">
523	<desc>ID of the media this event relates to.</desc>
524	</param>
525	<param name="mediaType" type="DeviceType" dir="in">
526	<desc>Type of the media this event relates to.</desc>
527	</param>
528	<param name="registered" type="boolean" dir="in">
529	<desc>
530	If true, the media was registered, otherwise it was
531	unregistered.
532	</desc>
533	</param>
534	</method>
535
536	<method name="onMachineRegistered">
537	<desc>
538	The given machine was registered or unregistered
539	within this VirtualBox installation.
540	</desc>
541	<param name="machineId" type="uuid" dir="in">
542	<desc>ID of the machine this event relates to.</desc>
543	</param>
544	<param name="registered" type="boolean" dir="in">
545	<desc>
546	If true, the machine was registered, otherwise it was
547	unregistered.
548	</desc>
549	</param>
550	</method>
551
552	<method name="onSessionStateChange">
553	<desc>
554	The state of the session for the given machine was changed.
555	<see>IMachine::sessionState</see>
556	</desc>
557	<param name="machineId" type="uuid" dir="in">
558	<desc>ID of the machine this event relates to.</desc>
559	</param>
560	<param name="state" type="SessionState" dir="in">
561	<desc>New session state.</desc>
562	</param>
563	</method>
564
565	<method name="onSnapshotTaken">
566	<desc>
567	A new snapshot of the machine has been taken.
568	<see>ISnapshot</see>
569	</desc>
570	<param name="machineId" type="uuid" dir="in">
571	<desc>ID of the machine this event relates to.</desc>
572	</param>
573	<param name="snapshotId" type="uuid" dir="in">
574	<desc>ID of the new snapshot.</desc>
575	</param>
576	</method>
577
578	<method name="onSnapshotDiscarded">
579	<desc>
580	Snapshot of the given machine has been discarded.
581
582	<note>
583	This notification is delivered <b>after</b> the snapshot
584	object has been uninitialized on the server (so that any
585	attempt to call its methods will return an error).
586	</note>
587
588	<see>ISnapshot</see>
589	</desc>
590	<param name="machineId" type="uuid" dir="in">
591	<desc>ID of the machine this event relates to.</desc>
592	</param>
593	<param name="snapshotId" type="uuid" dir="in">
594	<desc>
595	ID of the discarded snapshot. <tt>null</tt> means the
596	current machine state has been discarded (restored from
597	the current snapshot).
598	</desc>
599	</param>
600	</method>
601
602	<method name="onSnapshotChange">
603	<desc>
604	Snapshot properties (name and/or description) have been changed.
605	<see>ISnapshot</see>
606	</desc>
607	<param name="machineId" type="uuid" dir="in">
608	<desc>ID of the machine this event relates to.</desc>
609	</param>
610	<param name="snapshotId" type="uuid" dir="in">
611	<desc>ID of the changed snapshot.</desc>
612	</param>
613	</method>
614
615	</interface>
616
617	<interface
618	name="IVirtualBox" extends="$dispatched"
619	uuid="ce54ff3d-0e46-41ae-a0de-202ed0c3c668"
620	>
621	<desc> The main interface exposed by the product that provides virtual
622	machine management.
623
624	An instance of IVirtualBox is required for the product to do anything
625	useful. Even though the interface does not expose this, internally, IVirtualBox
626	is implemented as a singleton and actually lives in the process of the
627	VirtualBox server (VBoxSVC.exe). This makes sure that IVirtualBox can
628	track the state of all virtual machines on a particular host, regardless
629	of which frontend started them.
630
631	To enumerate all the virtual machines on the host, use the <link to="IVirtualBox::machines" />
632	attribute.</desc>
633
634	<attribute name="version" type="wstring" readonly="yes">
635	<desc>
636	A string representing the version number of the product. The
637	format is 3 integer numbers divided by dots (e.g. 1.0.1). The
638	last number represents the build number and will frequently change.
639	</desc>
640	</attribute>
641
642	<attribute name="homeFolder" type="wstring" readonly="yes">
643	<desc>
644	Full path to the directory where the global settings file,
645	<tt>VirtualBox.xml</tt>, is stored.
646
647	In this version of VirtualBox, the value of this property is
648	always <tt><user_dir>/.VirtualBox</tt> (where
649	<tt><user_dir></tt> is the path to the user directory,
650	as determined by the host OS), and cannot be changed.
651
652	This path is also used as the base to resolve relative paths in
653	places where relative paths are allowed (unless otherwise
654	expressly indicated).
655	</desc>
656	</attribute>
657
658	<attribute name="host" type="IHost" readonly="yes">
659	<desc>Associated host object.</desc>
660	</attribute>
661
662	<attribute name="systemProperties" type="ISystemProperties" readonly="yes">
663	<desc>Associated system information object.</desc>
664	</attribute>
665
666	<attribute name="machines" type="IMachineCollection" readonly="yes"/>
667
668	<attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
669	<desc>
670	A collection of hard disk objects registered within this
671	VirtualBox instance.
672	This collection contains only "top-level" (basic or independent)
673	hard disk images, but not differencing ones. All differencing
674	images of the given top-level image (i.e. all its children) can
675	be enumerated using <link to="IHardDisk::children"/>.
676	</desc>
677	</attribute>
678
679	<attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
680
681	<attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
682
683	<attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
684
685	<attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
686
687	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
688	<desc>
689	Collection of globally shared folders. These folders
690	are shared automatically upon VirtualBox server startup and
691	available only to every virtual machine.
692
693	New folders to share are added to the collection using
694	<link to="#createSharedFolder"/>. An existing shared folder can
695	be removed using <link to="#removeSharedFolder"/>.
696	</desc>
697	</attribute>
698
699	<method name="createMachine">
700	<desc>
701	Creates a new virtual machine.
702
703	Every machine has a <i>settings file</i> that is used to store
704	the machine configuration. This file is stored in the directory
705	called <i>machine settings subfolder</i>. Both the subfolder
706	and the settings file have the same name that corresponds to the
707	name of the virtual machine. You can specify where
708	to create the machine settings subfolder using the @a
709	baseFolder argument. The base folder can be absolute (full path)
710	or relative to the <link to="IVirtualBox::homeFolder">
711	VirtualBox home directory</link>.
712
713	If a null or empty string is given as the base folder (which is
714	recommended), the <link to="ISystemProperties::defaultMachineFolder">
715	default machine settings folder</link> will be used as the base
716	folder to create the machine settings subfolder and file. In
717	any case, the full path to the settings file will look like:
718	<pre>
719	<base_folder>/<machine_name>/<machine_name>.xml</pre>
720
721	Note that the configuration of the newly created machine is not
722	saved to disk (and therefore no settings subfolder and file are
723	created) until <link to="IMachine::saveSettings()"/> is called.
724
725	You should also specify a valid name for the machine.
726	See the <link to="IMachine::name"/> property
727	description for more details about the machine name.
728
729	The created machine remains
730	unregistered until you call <link to="#registerMachine()"/>.
731
732	<note>
733	There is no way to change the name of the settings file or
734	subfolder of the created machine directly.
735	</note>
736	</desc>
737	<param name="baseFolder" type="wstring" dir="in">
738	<desc>
739	Name of the folder where to create the machine settings
740	subfolder containing the settings file.
741	</desc>
742	</param>
743	<param name="name" type="wstring" dir="in">
744	<desc>Machine name.</desc>
745	</param>
746	<param name="machine" type="IMachine" dir="return">
747	<desc>Created machine object.</desc>
748	</param>
749	</method>
750
751	<method name="createLegacyMachine">
752	<desc>
753	Creates a new virtual machine in "legacy" mode, using the
754	specified settings file to store machine settings.
755
756	As opposed to machines created by <link to="#createMachine()"/>,
757	the settings file of the machine created in "legacy" mode
758	is not authomatically renamed when the machine name is
759	changed -- it will always remain the same as specified in this
760	method call.
761
762	The specified settings file name can be absolute
763	(full path) or relative to the <link to="IVirtualBox::homeFolder">
764	VirtualBox home directory</link>. If the file name doesn't
765	contain an extension, the default extension (.xml) will be
766	appended.
767
768	Note that the configuration of the newly created machine is not
769	saved to disk (and therefore no settings file is created)
770	until <link to="IMachine::saveSettings()"/> is called. If the
771	specified settings file already exists,
772	<link to="IMachine::saveSettings()"/> will return an error.
773
774	You should also specify a valid name for the machine.
775	See the <link to="IMachine::name"/> property
776	description for more details about the machine name.
777
778	The created machine remains
779	unregistered until you call <link to="#registerMachine()"/>.
780
781	@deprecated This method may be removed later. It is better
782	to use <link to="IVirtualBox::createMachine()"/>.
783
784	<note>
785	There is no way to change the name of the settings file
786	of the created machine.
787	</note>
788	</desc>
789	<param name="settingsFile" type="wstring" dir="in">
790	<desc>
791	Name of the file where to store machine settings.
792	</desc>
793	</param>
794	<param name="name" type="wstring" dir="in">
795	<desc>Machine name.</desc>
796	</param>
797	<param name="machine" type="IMachine" dir="return">
798	<desc>Created machine object.</desc>
799	</param>
800	</method>
801
802	<method name="openMachine">
803	<desc>
804	Opens a virtual machine from the existing settings file.
805	The opened machine remains unregistered until you call
806	<link to="#registerMachine()"/>.
807
808	The specified settings file name can be absolute
809	(full path) or relative to the <link to="IVirtualBox::homeFolder">
810	VirtualBox home directory</link>. This file must exist
811	and must be a valid machine settings file whose contents
812	will be used to construct the machine object.
813
814	@deprecated Will be removed soon.
815	</desc>
816	<param name="settingsFile" type="wstring" dir="in">
817	<desc>
818	Name of the machine settings file.
819	</desc>
820	</param>
821	<param name="machine" type="IMachine" dir="return">
822	<desc>Opened machine object.</desc>
823	</param>
824	<note>
825	<link to="IMachine::settingsModified"/> will return
826	false for the created machine, until any of machine settigs
827	are changed.
828	</note>
829	</method>
830
831	<method name="registerMachine">
832	<desc>
833
834	Registers the machine previously created using <link
835	to="#createMachine()"/> or opened using <link to="#openMachine()"/>
836	within this VirtualBox installation. After successful method
837	invocation, the <link
838	to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
839	to all registered callbacks.
840
841	<note>This method implicitly calls <link
842	to="IMachine::saveSettings"/> to save all current machine
843	settings before registering it.</note>
844
845	</desc>
846	<param name="machine" type="IMachine" dir="in"/>
847	</method>
848
849	<method name="getMachine">
850	<param name="id" type="uuid" dir="in"/>
851	<param name="machine" type="IMachine" dir="return"/>
852	</method>
853
854	<method name="findMachine">
855	<param name="name" type="wstring" dir="in"/>
856	<param name="machine" type="IMachine" dir="return"/>
857	</method>
858
859	<method name="unregisterMachine">
860	<desc>
861
862	Unregisters the machine previously registered using <link
863	to="#registerMachine"/>. After successful method invocation, the
864	<link to="IVirtualBoxCallback::onMachineRegistered"/> signal is
865	sent to all registered callbacks.
866
867	<note> The specified machine must not be in the Saved state,
868	have an open (or a spawning) direct session associated with it,
869	have snapshots or have hard disks attached.</note>
870
871	<note>This method implicitly calls <link
872	to="IMachine::saveSettings"/> to save all current machine
873	settings before unregistering it.</note>
874
875	<note>If the given machine is inaccessible (see
876	<link to="IMachine::accessible"/>), it will be unregistered
877	and fully uninitialized right afterwards. As a result, the
878	returned machine object will be unusable and an attempt to call
879	<b>any</b> method will return the "Object not ready" error.
880	</note>
881
882	</desc>
883	<param name="id" type="uuid" dir="in">
884	<desc>UUID of the machine to unregister.</desc>
885	</param>
886	<param name="machine" type="IMachine" dir="return">
887	<desc>Unregistered machine object.</desc>
888	</param>
889	</method>
890
891	<method name="createHardDisk">
892	<desc>
893
894	Creates a new unregistered hard disk that will use the given
895	storage type.
896
897	Most properties of the created hard disk object are
898	uninitialized. Valid values must be assigned to them (and
899	probalby some actions performed) to make the actual usage of
900	this hard disk (<link to="#registerHardDisk()">register</link>,
901	attach to a virtual machine, etc.). See the description of <link
902	to="IHardDisk"/> and descriptions of storage type specific
903	interfaces for more information.
904
905	<note>For hard disks using the <link
906	to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
907	storage type, an image file is not actually created until you
908	call <link to="IVirtualDiskImage::createDynamicImage()"/> or
909	<link to="IVirtualDiskImage::createFixedImage()"/>.</note>
910
911	</desc>
912
913	<param name="storageType" type="HardDiskStorageType" dir="in">
914	<desc>Storage type of the hard disk image to create.</desc>
915	</param>
916	<param name="hardDisk" type="IHardDisk" dir="return">
917	<desc>Created hard disk object of the given storage type.</desc>
918	</param>
919
920	</method>
921
922	<method name="openHardDisk">
923	<desc>
924
925	Opens a hard disk from an existing location.
926
927	This method tries to guess the
928	<link to="HardDiskStorageType">hard disk storage
929	type</link>
930	from the format of the location string and from the
931	contens of the resource the location points
932	to. Currently, a <i>file path</i> is the only supported
933	format for the location string which must point to
934	either a VDI file or to a VMDK file. On success,
935	an IHardDisk object will be returned that also
936	implements the corresponding interface (IVirtualDiskImage
937	or IVMDKImage, respectively). The <link
938	to="IHardDisk::storageType"/> property may also be
939	used to determine the storage type of the returned
940	object (instead of trying to query one of these interfaces).
941
942	<note>The specified file path can be absolute (full path) or
943	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
944	home directory</link>. If only a file name without any path is
945	given, the <link to="ISystemProperties::defaultVDIFolder">
946	default VDI folder</link> will be used as a path to the image
947	file.</note>
948
949	The opened hard disk remains unregistered
950	until <link to="#registerHardDisk()"/> is called.
951
952	</desc>
953
954	<param name="location" type="wstring" dir="in">
955	<desc>
956	Location of the resource that contains a valid hard disk.
957	</desc>
958	</param>
959	<param name="hardDisk" type="IHardDisk" dir="return">
960	<desc>Opened hard disk object.</desc>
961	</param>
962	</method>
963
964	<method name="openVirtualDiskImage">
965	<desc>
966
967	Opens a hard disk from an existing Virtual Disk Image file.
968	The opened hard disk remains unregistered
969	until <link to="#registerHardDisk()"/> is called.
970
971	@deprecated Use <link to="#openHardDisk()"/> instead.
972
973	<note>Opening differencing images is not supported.</note>
974
975	<note>The specified file path can be absolute (full path) or
976	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
977	home directory</link>. If only a file name without any path is
978	given, the <link to="ISystemProperties::defaultVDIFolder">
979	default VDI folder</link> will be used as a path to the image
980	file.</note>
981
982	</desc>
983
984	<param name="filePath" type="wstring" dir="in">
985	<desc>
986	Name of the file that contains a valid Virtual Disk Image.
987	</desc>
988	</param>
989	<param name="image" type="IVirtualDiskImage" dir="return">
990	<desc>Opened hard disk object.</desc>
991	</param>
992	</method>
993
994	<method name="registerHardDisk">
995	<desc>
996
997	Registers the given hard disk within this VirtualBox
998	installation. The hard disk must not be registered, must be
999	<link to="IHardDisk::accessible"/> and must not be a
1000	differencing hard disk, otherwise the registration will fail.
1001
1002	</desc>
1003	<param name="hardDisk" type="IHardDisk" dir="in">
1004	<desc>Hard disk object to register.</desc>
1005	</param>
1006	</method>
1007
1008	<method name="getHardDisk" const="yes">
1009	<desc>
1010	Returns the registered hard disk with the given UUID.
1011	</desc>
1012	<param name="id" type="uuid" dir="in">
1013	<desc>UUID of the hard disk to look for.</desc>
1014	</param>
1015	<param name="hardDisk" type="IHardDisk" dir="return">
1016	<desc>Found hard disk object.</desc>
1017	</param>
1018	</method>
1019
1020	<method name="findHardDisk">
1021	<desc>
1022
1023	Returns a registered hard disk that uses the given location to
1024	store data. The search is done by comparing the
1025	value of the @a location argument to the
1026	<link to="IHardDisk::location"/> attribute of each registered
1027	hard disk.
1028
1029	For locations repesented by file paths (such as VDI and VMDK
1030	images), the specified location can be either an absolute file
1031	path or a path relative to
1032	the <link to="IVirtualBox::homeFolder"> VirtualBox home
1033	directory</link>. If only a file name without any path is
1034	given, the <link to="ISystemProperties::defaultVDIFolder">
1035	default VDI folder</link> will be used as a path to construct
1036	the absolute image file name to search for. Note that on host
1037	systems with case sensitive filesystems, a case sensitive
1038	comparison is performed, otherwise the case of symbols in the
1039	file path is ignored.
1040
1041	</desc>
1042	<param name="location" type="wstring" dir="in">
1043	<desc>Hard disk location specification to search for.</desc>
1044	</param>
1045	<param name="hardDisk" type="IHardDisk" dir="return">
1046	<desc>Found hard disk object.</desc>
1047	</param>
1048	</method>
1049
1050	<method name="findVirtualDiskImage">
1051	<desc>
1052
1053	Returns a registered hard disk that uses the given image file.
1054
1055	@deprecated Use <link to="#findHardDisk()"/> instead.
1056
1057	<note>The specified file path can be absolute (full path) or
1058	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
1059	home directory</link>. If only a file name without any path is
1060	given, the <link to="ISystemProperties::defaultVDIFolder">
1061	default VDI folder</link> will be used as a path to the image
1062	file.</note>
1063
1064	<note>On host systems with case sensitive filesystems, a case
1065	sensitive comparison is performed, otherwise the case of symbols
1066	in the file path is ignored.</note>
1067
1068	</desc>
1069	<param name="filePath" type="wstring" dir="in">
1070	<desc>Virtual Disk Image file path to look for.</desc>
1071	</param>
1072	<param name="image" type="IVirtualDiskImage" dir="return">
1073	<desc>Found hard disk object.</desc>
1074	</param>
1075	</method>
1076
1077	<method name="unregisterHardDisk">
1078	<desc>
1079	Unregisters a hard disk previously registered using
1080	<link to="#registerHardDisk()"/>.
1081	<note>
1082	The specified hard disk must not be attached to any of
1083	the existing virtual machines and must not have children
1084	(differencing) hard disks.
1085	</note>
1086	</desc>
1087	<param name="id" type="uuid" dir="in">
1088	<desc>UUID of the hard disk to unregister.</desc>
1089	</param>
1090	<param name="hardDisk" type="IHardDisk" dir="return">
1091	<desc>Unregistered hard disk object.</desc>
1092	</param>
1093	</method>
1094
1095	<method name="openDVDImage">
1096	<desc>
1097	Opens the CD/DVD image contained in the specified file of
1098	the supported format and assigns it the given UUID. The opened
1099	image remains unregistered
1100	until <link to="#registerDVDImage()"/> is called.
1101	</desc>
1102	<param name="filePath" type="wstring" dir="in">
1103	<desc>
1104	Full name of the file that contains a valid
1105	CD/DVD image. Currently, only ISO images are supported.
1106	<note>
1107	The specified file name can be absolute or relative
1108	to the <link to="IVirtualBox::homeFolder">
1109	VirtualBox home directory</link>.
1110	</note>
1111	</desc>
1112	</param>
1113	<param name="id" type="uuid" dir="in">
1114	<desc>
1115	UUID to assign to the given image file within this
1116	VirtualBox installation. If an empty (null) UUID is
1117	specified, the system will randomly generate an UUID.
1118	</desc>
1119	</param>
1120	<param name="image" type="IDVDImage" dir="return">
1121	<desc>Opened CD/DVD image object.</desc>
1122	</param>
1123	</method>
1124
1125	<method name="registerDVDImage">
1126	<desc>
1127	Registers a CD/DVD image within this VirtualBox
1128	installation. The image must not be registered and must not
1129	be associated with the same image file as any of the already
1130	registered images, otherwise the registration will fail.
1131	</desc>
1132	<param name="image" type="IDVDImage" dir="in">
1133	<desc>CD/DVD image object to register.</desc>
1134	</param>
1135	</method>
1136
1137	<method name="getDVDImage">
1138	<desc>
1139	Returns a registered CD/DVD image with the given UUID.
1140	</desc>
1141	<param name="id" type="uuid" dir="in">
1142	<desc>UUID of the image to look for.</desc>
1143	</param>
1144	<param name="image" type="IDVDImage" dir="return">
1145	<desc>Found CD/DVD image object.</desc>
1146	</param>
1147	</method>
1148
1149	<method name="findDVDImage">
1150	<desc>
1151	Returns a registered CD/DVD image with the given image file.
1152	<note>
1153	On host systems with case sensitive filesystems, a case
1154	sensitive comparison is performed, otherwise the case of
1155	symbols in the file path is ignored.
1156	</note>
1157	</desc>
1158	<param name="filePath" type="wstring" dir="in">
1159	<desc>CD/DVD image file path to look for.</desc>
1160	</param>
1161	<param name="image" type="IDVDImage" dir="return">
1162	<desc>Found CD/DVD image object.</desc>
1163	</param>
1164	</method>
1165
1166	<method name="getDVDImageUsage">
1167	<desc>
1168	Returns the list of of UUIDs of all virtual machines that use
1169	the given CD/DVD image.
1170	</desc>
1171	<param name="id" type="uuid" dir="in">
1172	<desc>UUID of the image to get the usage information for.</desc>
1173	</param>
1174	<param name="usage" type="ResourceUsage" dir="in">
1175	<desc>Type of the usage (permanent, temporary or all).</desc>
1176	</param>
1177	<param name="machineIDs" type="wstring" dir="return">
1178	<desc>
1179	List of UUIDs of all machines that use the given image
1180	in the way specified by the usage parameter.
1181	The list is returned as a string containing UUIDs separated
1182	by spaces. A null string means that the image is not used.
1183	<note>
1184	When the usage type is <link to="ResourceUsage::AllUsage"/>
1185	and the image is used by the VM both permanently
1186	and temporarily, the VM's UUID will be present only
1187	once in the list.
1188	</note>
1189	</desc>
1190	</param>
1191	</method>
1192
1193	<method name="unregisterDVDImage">
1194	<desc>
1195	Unregisters the CD/DVD image previously registered using
1196	<link to="#registerDVDImage()"/>.
1197	<note>
1198	The specified image must not be mounted to any of
1199	the existing virtual machines.
1200	</note>
1201	</desc>
1202	<param name="id" type="uuid" dir="in">
1203	<desc>UUID of the CD/DVD image to unregister.</desc>
1204	</param>
1205	<param name="image" type="IDVDImage" dir="return">
1206	<desc>Unregistered image object.</desc>
1207	</param>
1208	</method>
1209
1210	<method name="openFloppyImage">
1211	<desc>
1212	Opens a floppy image contained in the specified file of
1213	the supported format and assigns it the given UUID. The opened
1214	image remains unregistered
1215	until <link to="#registerFloppyImage()"/> is called.
1216	</desc>
1217	<param name="filePath" type="wstring" dir="in">
1218	<desc>
1219	Full name of the file that contains a valid
1220	floppy image.
1221	<note>
1222	The specified file name can be absolute or relative
1223	to the <link to="IVirtualBox::homeFolder">
1224	VirtualBox home directory</link>.
1225	</note>
1226	</desc>
1227	</param>
1228	<param name="id" type="uuid" dir="in">
1229	<desc>
1230	UUID to assign to the given image file within this
1231	VirtualBox installation. If an empty (null) UUID is
1232	specified, the system will randomly generate an UUID.
1233	</desc>
1234	</param>
1235	<param name="image" type="IFloppyImage" dir="return">
1236	<desc>Opened CD/DVD image object.</desc>
1237	</param>
1238	</method>
1239
1240	<method name="registerFloppyImage">
1241	<desc>
1242	Registers a floppy image within this VirtualBox
1243	installation. The image must not be registered and must not
1244	be associated with the same image file as any of the already
1245	registered images, otherwise the registration will fail.
1246	</desc>
1247	<param name="image" type="IFloppyImage" dir="in">
1248	<desc>Floppy image object to register.</desc>
1249	</param>
1250	</method>
1251
1252	<method name="getFloppyImage">
1253	<desc>
1254	Returns a registered floppy image with the given UUID.
1255	</desc>
1256	<param name="id" type="uuid" dir="in">
1257	<desc>UUID of the image to look for.</desc>
1258	</param>
1259	<param name="image" type="IFloppyImage" dir="return">
1260	<desc>Found floppy image object.</desc>
1261	</param>
1262	</method>
1263
1264	<method name="findFloppyImage">
1265	<desc>
1266	Returns a registered floppy image with the given image file.
1267	<note>
1268	On host systems with case sensitive filesystems, a case
1269	sensitive comparison is performed, otherwise the case of
1270	symbols in the file path is ignored.
1271	</note>
1272	</desc>
1273	<param name="filePath" type="wstring" dir="in">
1274	<desc>Floppy image file path to look for.</desc>
1275	</param>
1276	<param name="image" type="IFloppyImage" dir="return">
1277	<desc>Found floppy image object.</desc>
1278	</param>
1279	</method>
1280
1281	<method name="getFloppyImageUsage">
1282	<desc>
1283	Returns the list of of UUIDs of all virtual machines that use
1284	the given floppy image.
1285	</desc>
1286	<param name="id" type="uuid" dir="in">
1287	<desc>UUID of the image to get the usage information for.</desc>
1288	</param>
1289	<param name="usage" type="ResourceUsage" dir="in">
1290	<desc>Type of the usage (permanent, temporary or all).</desc>
1291	</param>
1292	<param name="machineIDs" type="wstring" dir="return">
1293	<desc>
1294	List of UUIDs of all machines that use the given image
1295	in the way specified by the usage parameter.
1296	The list is returned as a string containing UUIDs separated
1297	by spaces. A null string means that the image is not used.
1298	<note>
1299	When the usage type is <link to="ResourceUsage::AllUsage"/>
1300	and the image is used by the VM both permanently
1301	and temporarily, the VM's UUID will be present only
1302	once in the list.
1303	</note>
1304	</desc>
1305	</param>
1306	</method>
1307
1308	<method name="unregisterFloppyImage">
1309	<desc>
1310	Unregisters the floppy image previously registered using
1311	<link to="#registerFloppyImage()"/>.
1312	<note>
1313	The specified image must not be mounted to any of
1314	the existing virtual machines.
1315	</note>
1316	</desc>
1317	<param name="id" type="uuid" dir="in">
1318	<desc>UUID of the floppy image to unregister.</desc>
1319	</param>
1320	<param name="image" type="IFloppyImage" dir="return">
1321	<desc>Unregistered image object.</desc>
1322	</param>
1323	</method>
1324
1325	<method name="findGuestOSType">
1326	<param name="id" type="wstring" dir="in"/>
1327	<param name="type" type="IGuestOSType" dir="return"/>
1328	</method>
1329
1330	<method name="createSharedFolder">
1331	<desc>
1332	Creates a new shared folder by associating the given logical
1333	name with the given host path, adds it to the collection of
1334	shared folders and starts sharing it.
1335	Refer to the description of <link to="ISharedFolder"/> to read
1336	about logical name unicity.
1337	</desc>
1338	<param name="name" type="wstring" dir="in">
1339	<desc>Unique logical name of the shared folder.</desc>
1340	</param>
1341	<param name="hostPath" type="wstring" dir="in">
1342	<desc>Full path to the shared folder in the host file system.</desc>
1343	</param>
1344	</method>
1345
1346	<method name="removeSharedFolder">
1347	<desc>
1348	Removes a shared folder with the given name previously created
1349	by <link to="#createSharedFolder"/> from the collection of
1350	shared folders and stops sharing it.
1351	</desc>
1352	<param name="name" type="wstring" dir="in">
1353	<desc>Logical name of the shared folder to remove.</desc>
1354	</param>
1355	</method>
1356
1357	<method name="getNextExtraDataKey">
1358	<desc>
1359	Returns the extra data key name following the supplied key.
1360	An error is returned if the supplied key does not exist.
1361	NULL is returned if the supplied key is the last key.
1362	When supplying NULL for the key, the first item is returned.
1363	NextValue is an optional parameter and if supplied, the next
1364	key's value is returned as well.
1365	</desc>
1366	<param name="key" type="wstring" dir="in"/>
1367	<param name="nextKey" type="wstring" dir="out"/>
1368	<param name="nextValue" type="wstring" dir="out"/>
1369	</method>
1370
1371	<method name="getExtraData">
1372	<desc>Returns associated extra data.</desc>
1373	<param name="key" type="wstring" dir="in"/>
1374	<param name="value" type="wstring" dir="return"/>
1375	</method>
1376
1377	<method name="setExtraData">
1378	<desc>Sets associated extra data.</desc>
1379	<param name="key" type="wstring" dir="in"/>
1380	<param name="value" type="wstring" dir="in"/>
1381	</method>
1382
1383	<method name="openSession">
1384	<desc>
1385	<p>Opens a new direct session with the given virtual machine.
1386	Within the direct session context, it is possible to change
1387	all VM settings, as well as to execute the VM in the process
1388	space of the session object. There can be only one direct
1389	session open at a time for every virtual machine.</p>
1390	<p>Upon successful return, the session object can be used to
1391	get access to the machine and to the VM console.
1392	</p>
1393	</desc>
1394	<param name="session" type="ISession" dir="in">
1395	<desc>
1396	Session object that will represent the opened session after
1397	successful method invocation. This object must not represent
1398	the already open session.
1399	<note>
1400	This session will be automatically closed if the
1401	VirtualBox server is terminated for some reason.
1402	</note>
1403	</desc>
1404	</param>
1405	<param name="machineId" type="uuid" dir="in">
1406	<desc>ID of the virtual machine to open a session with.</desc>
1407	</param>
1408	</method>
1409
1410	<method name="openRemoteSession">
1411	<desc>
1412	<p>Opens a new remote session with the given virtual
1413	machine. Opening the remote session causes the server to start
1414	a new process that opens a direct session with the given VM.
1415	The remote session provides some level of control over the VM
1416	execution (using the IConsole interface) to the caller. Within
1417	the remote session context, it is not possible to change any
1418	static VM settings (such as name, HDD configuration, etc.).</p>
1419	<p>This operation can take some time, so the progress object
1420	is returned to let the caller be informed when the session is
1421	actually open. Until then, the remote session object remains in
1422	the closed state and accessing the machine or its console through
1423	it is invalid.
1424	</p>
1425
1426	Currently supported session types (values of the @a type
1427	parameter) are:
1428	<ul>
1429	<li><tt>gui</tt>: VirtualBox Qt GUI session</li>
1430	<li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
1431	</ul>
1432
1433	<note>
1434	It is impossible to open a remote session with the machine
1435	that already has an open direct session or waits until the
1436	previous request to open the remote session is completed
1437	(see <link to="IMachine::sessionState"/>).
1438	</note>
1439
1440	<note>
1441	The opened @a session will be automatically closed when
1442	the corresponding direct session dies or gets closed.
1443	</note>
1444
1445	<see>openExistingSession</see>
1446	</desc>
1447	<param name="session" type="ISession" dir="in">
1448	<desc>
1449	Session object that will represent the opened remote session
1450	after successful method invocation (this object must not
1451	represent an already open session).
1452	</desc>
1453	</param>
1454	<param name="machineId" type="uuid" dir="in">
1455	<desc>ID of the virtual machine to open a session with.</desc>
1456	</param>
1457	<param name="type" type="wstring" dir="in">
1458	<desc>
1459	Type of the remote session (case sensitive).
1460	</desc>
1461	</param>
1462	<param name="progress" type="IProgress" dir="return">
1463	<desc>Progress object to track the operation completion.</desc>
1464	</param>
1465	</method>
1466
1467	<method name="openExistingSession">
1468	<desc>
1469	<p>Opens a new remote session with the virtual machine for
1470	which a direct session is already open.
1471	The remote session provides some level of control over the VM
1472	execution (using the IConsole interface) to the caller. Within
1473	the remote session context, it is not possible to change any
1474	static VM settings (such as name, HDD configuration, etc.).</p>
1475	<p>As opposed to <link to="#openRemoteSession()"/>, the number of
1476	remote sessions opened this way is not limited by the API.</p>
1477	<note>
1478	It is impossible to open a remote session with the machine
1479	that doesn't have an open direct session.
1480	</note>
1481	<see>openRemoteSession</see>
1482	</desc>
1483	<param name="session" type="ISession" dir="in">
1484	<desc>
1485	Session object that will represent the open remote session
1486	after successful method invocation. This object must not
1487	represent an already open session.
1488	<note>
1489	This session will be automatically closed when the peer
1490	(direct) session dies or gets closed.
1491	</note>
1492	</desc>
1493	</param>
1494	<param name="machineId" type="uuid" dir="in">
1495	<desc>ID of the virtual machine to open a session with.</desc>
1496	</param>
1497	</method>
1498
1499	<method name="registerCallback">
1500	<param name="callback" type="IVirtualBoxCallback" dir="in"/>
1501	</method>
1502
1503	<method name="unregisterCallback">
1504	<param name="callback" type="IVirtualBoxCallback" dir="in"/>
1505	</method>
1506
1507	</interface>
1508
1509	<class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
1510	namespace="virtualbox.org">
1511	<interface name="IVirtualBox" default="yes"/>
1512	</class>
1513
1514	<!--
1515	// IMachine
1516	/////////////////////////////////////////////////////////////////////////
1517	-->
1518
1519	<enumerator
1520	name="IMachineEnumerator" type="IMachine"
1521	uuid="1b554149-be0a-4465-9252-9ff8f420af55"
1522	/>
1523
1524	<collection
1525	name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
1526	uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
1527	readonly="yes"
1528	/>
1529
1530	<interface
1531	name="IInternalMachineControl" extends="$unknown"
1532	uuid="F466BF2E-BD6B-4af0-9C08-46DD42B28A44"
1533	internal="yes"
1534	>
1535	<method name="updateState">
1536	<desc>
1537	Updates the VM state.
1538	<note>
1539	This operation will also update the settings file with
1540	the correct information about the saved state file
1541	and delete this file from disk when appropriate.
1542	</note>
1543	</desc>
1544	<param name="state" type="MachineState" dir="in"/>
1545	</method>
1546
1547	<method name="getIPCId">
1548	<param name="id" type="wstring" dir="return"/>
1549	</method>
1550
1551	<method name="getLogFolder">
1552	<desc>
1553	Returns the full name of the directory where to store
1554	log files created during this machine's executoin.
1555	</desc>
1556	<param name="logFolder" type="wstring" dir="return"/>
1557	</method>
1558
1559	<method name="runUSBDeviceFilters">
1560	<desc>
1561	Asks the server to run USB devices filters of the associated
1562	machine against the given USB device and tell if there is
1563	a match.
1564	<note>
1565	Intended to be used only for remote USB devices. Local
1566	ones don't require to call this method (this is done
1567	implicitly by the Host and USBProxyService).
1568	</note>
1569	</desc>
1570	<param name="device" type="IUSBDevice" dir="in"/>
1571	<param name="matched" type="boolean" dir="return"/>
1572	</method>
1573
1574	<method name="captureUSBDevice">
1575	<desc>
1576	Requests a capture of the given host USB device, and returns
1577	the captured device (as IUSBDevice) to the caller.
1578	<note>
1579	The server must mark the device as USBDeviceCaptured
1580	during this call.
1581
1582	This method must return extended error info in case of any
1583	eroror (<link to="IConsole::detachUSBDevice()"/>) relies
1584	on this.
1585	</note>
1586	</desc>
1587	<param name="id" type="uuid" dir="in"/>
1588	<param name="hostDevice" type="IUSBDevice" dir="return"/>
1589	</method>
1590
1591	<method name="releaseUSBDevice">
1592	<desc>
1593	Releases the given USB device.
1594	<note>
1595	The server must run its own filters and filters of all VMs
1596	but this one on the given device as if it were just attached
1597	to the host computer.
1598	</note>
1599	</desc>
1600	<param name="id" type="uuid" dir="in"/>
1601	</method>
1602
1603	<method name="autoCaptureUSBDevices">
1604	<desc>
1605	Queries the list of available devices that must be auto-captured
1606	according to this VM's filters. Devices returned as IUSBDevice
1607	instances.
1608	<note>
1609	The server must mark all returned devices as USBDeviceCaptured
1610	during this call.
1611	</note>
1612	</desc>
1613	<param name="hostDevices" type="IUSBDeviceCollection" dir="return"/>
1614	</method>
1615
1616	<method name="releaseAllUSBDevices">
1617	<desc>
1618	Releases all USB devices that are captured by this VM because
1619	the VM has been terminated.
1620	<note>
1621	The server must run its own filters and filters of all VMs
1622	but this one on all released devices as if they were just
1623	attached to the host computer.
1624	</note>
1625	</desc>
1626	</method>
1627
1628	<method name="onSessionEnd">
1629	<desc>
1630	Triggered by the given session object when the session is about
1631	to close normally.
1632	</desc>
1633	<param name="session" type="ISession" dir="in">
1634	<desc>Session that is being closed</desc>
1635	</param>
1636	<param name="progress" type="IProgress" dir="return">
1637	<desc>
1638	Used to wait until the corresponding machine is actually
1639	deassociated from the given session on the server.
1640	Returned only when this session is a direct one.
1641	</desc>
1642	</param>
1643	</method>
1644
1645	<method name="beginSavingState">
1646	<desc>
1647	Called by the VM process to inform the server it wants to
1648	save the current state and stop the VM execution.
1649	</desc>
1650	<param name="progress" type="IProgress" dir="in">
1651	<desc>
1652	Progress object created by the VM process to wait until
1653	the state is saved.
1654	</desc>
1655	</param>
1656	<param name="stateFilePath" type="wstring" dir="out">
1657	<desc>
1658	File path the VM process must save the execution state to.
1659	</desc>
1660	</param>
1661	</method>
1662
1663	<method name="endSavingState">
1664	<desc>
1665	Called by the VM process to inform the server that saving
1666	the state previously requested by #beginSavingState is either
1667	successfully finished or there was a failure.
1668	</desc>
1669
1670	<param name="success" type="boolean" dir="in">
1671	<desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
1672	</param>
1673	</method>
1674
1675	<method name="beginTakingSnapshot">
1676	<desc>
1677	Called by the VM process to inform the server it wants to
1678	take a snapshot.
1679	</desc>
1680	<param name="initiator" type="IConsole" dir="in">
1681	<desc>The console object that initiated this call.</desc>
1682	</param>
1683	<param name="name" type="wstring" dir="in">
1684	<desc>Snapshot name</desc>
1685	</param>
1686	<param name="description" type="wstring" dir="in">
1687	<desc>Snapshot description</desc>
1688	</param>
1689	<param name="progress" type="IProgress" dir="in">
1690	<desc>
1691	Progress object created by the VM process to wait until
1692	the state is saved (only for online snapshots).
1693	</desc>
1694	</param>
1695	<param name="stateFilePath" type="wstring" dir="out">
1696	<desc>
1697	File path the VM process must save the execution state to.
1698	</desc>
1699	</param>
1700	<param name="serverProgress" type="IProgress" dir="out">
1701	<desc>
1702	Progress object created by the server process to wait until
1703	the snapshot is taken (VDI diff creation, etc.).
1704	</desc>
1705	</param>
1706	</method>
1707
1708	<method name="endTakingSnapshot">
1709	<desc>
1710	Called by the VM process to inform the server that the snapshot
1711	previously requested by #beginTakingSnapshot is either
1712	successfully taken or there was a failure.
1713	</desc>
1714
1715	<param name="success" type="boolean" dir="in">
1716	<desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
1717	</param>
1718	</method>
1719
1720	<method name="discardSnapshot">
1721	<desc>
1722	Gets called by IConsole::discardSnapshot.
1723	</desc>
1724	<param name="initiator" type="IConsole" dir="in">
1725	<desc>The console object that initiated this call.</desc>
1726	</param>
1727	<param name="id" type="uuid" dir="in">
1728	<desc>UUID of the snapshot to discard.</desc>
1729	</param>
1730	<param name="machineState" type="MachineState" dir="out">
1731	<desc>New machine state after this operation is started.</desc>
1732	</param>
1733	<param name="progress" type="IProgress" dir="return">
1734	<desc>Progress object to track the operation completion.</desc>
1735	</param>
1736	</method>
1737
1738	<method name="discardCurrentState">
1739	<desc>
1740	Gets called by IConsole::discardCurrentState.
1741	</desc>
1742	<param name="initiator" type="IConsole" dir="in">
1743	<desc>The console object that initiated this call.</desc>
1744	</param>
1745	<param name="machineState" type="MachineState" dir="out">
1746	<desc>New machine state after this operation is started.</desc>
1747	</param>
1748	<param name="progress" type="IProgress" dir="return">
1749	<desc>Progress object to track the operation completion.</desc>
1750	</param>
1751	</method>
1752
1753	<method name="discardCurrentSnapshotAndState">
1754	<desc>
1755	Gets called by IConsole::discardCurrentSnapshotAndState.
1756	</desc>
1757	<param name="initiator" type="IConsole" dir="in">
1758	<desc>The console object that initiated this call.</desc>
1759	</param>
1760	<param name="machineState" type="MachineState" dir="out">
1761	<desc>New machine state after this operation is started.</desc>
1762	</param>
1763	<param name="progress" type="IProgress" dir="return">
1764	<desc>Progress object to track the operation completion.</desc>
1765	</param>
1766	</method>
1767
1768	</interface>
1769
1770	<enum
1771	name="BIOSBootMenuMode"
1772	uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1773	>
1774	<desc>
1775	This represents the BIOS boot menu state.
1776	</desc>
1777
1778	<const name="Disabled" value="0"/>
1779	<const name="MenuOnly" value="1"/>
1780	<const name="MessageAndMenu" value="2"/>
1781	</enum>
1782
1783	<interface
1784	name="IBIOSSettings" extends="$unknown"
1785	uuid="00fff9d7-983e-462d-a1aa-4cc26de4f0d4"
1786	>
1787	<attribute name="LogoFadeIn" type="boolean">
1788	<desc>Fade in flag for BIOS logo animation.</desc>
1789	</attribute>
1790
1791	<attribute name="LogoFadeOut" type="boolean">
1792	<desc>Fade out flag for BIOS logo animation.</desc>
1793	</attribute>
1794
1795	<attribute name="LogoDisplayTime" type="unsigned long">
1796	<desc>BIOS logo display time in milliseconds (0 = default).</desc>
1797	</attribute>
1798
1799	<attribute name="LogoImagePath" type="wstring">
1800	<desc>Local file system path for external BIOS image.</desc>
1801	</attribute>
1802
1803	<attribute name="BootMenuMode" type="BIOSBootMenuMode">
1804	<desc>Mode of the BIOS boot device menu.</desc>
1805	</attribute>
1806
1807	<attribute name="ACPIEnabled" type="boolean">
1808	<desc>ACPI support flag.</desc>
1809	</attribute>
1810
1811	<attribute name="IOAPICEnabled" type="boolean">
1812	<desc>
1813	IO APIC support flag. If set, VirtualBox will provide an IO APIC
1814	and support IRQs above 15.
1815	</desc>
1816	</attribute>
1817
1818	</interface>
1819
1820	<interface
1821	name="IMachine" extends="$unknown"
1822	uuid="50fa9181-d2d4-45ca-bf0e-742677b9c707"
1823	>
1824	<attribute name="parent" type="IVirtualBox" readonly="yes">
1825	<desc>Associated parent obect.</desc>
1826	</attribute>
1827
1828	<attribute name="accessible" type="boolean" readonly="yes">
1829	<desc>
1830	Whether this virtual machine is currently accessible or not.
1831
1832	The machine is considered to be inaccessible when:
1833	<ul>
1834	<li>It is a registered virtual machine, and
1835	</li>
1836	<li>Its settings file is inaccessible (for example, it is
1837	located on a network share that is not accessible during
1838	VirtualBox startup, or becomes inaccessible later, or if
1839	the settings file can be read but is invalid).
1840	</li>
1841	</ul>
1842
1843	Otherwise, the value of this property is always <tt>true</tt>.
1844
1845	Every time this property is read, the accessibility state of
1846	this machine is re-evaluated. If the returned value is \|false\|,
1847	the <link to="#accessError"/> property may be used to get the
1848	detailed error information describing the reason of
1849	inaccessibility.
1850
1851	When the machine is inaccessible, only the following properties
1852	can be used on it:
1853	<ul>
1854	<li><link to="#parent"/></li>
1855	<li><link to="#id"/></li>
1856	<li><link to="#settingsFilePath"/></li>
1857	<li><link to="#accessible"/></li>
1858	<li><link to="#accessError"/></li>
1859	</ul>
1860
1861	An attempt to access any other property or method will return
1862	an error.
1863
1864	The only possible action you can perform on an inaccessible
1865	machine is to unregister it using the
1866	<link to="IVirtualBox::unregisterMachine"/> call (or, to check
1867	for the accessibility state once more by querying this
1868	property).
1869
1870	<note>
1871	In the current implementation, once this property returns
1872	<tt>true</tt>, the machine will never become inaccessible
1873	later, even if its settings file cannot be successfully
1874	read/written any more (at least, until the VirtualBox
1875	server is restarted). This limitation may be removed in
1876	future releases.
1877	</note>
1878	</desc>
1879	</attribute>
1880
1881	<attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
1882	<desc>
1883	Error information describing the reason of machine
1884	inaccessibility.
1885
1886	Reading this property is only valid after the last call to
1887	<link to="#accessible"/> returned <tt>false</tt> (i.e. the
1888	machine is currently unaccessible). Otherwise, a null
1889	IVirtualBoxErrorInfo object will be returned.
1890	</desc>
1891	</attribute>
1892
1893	<attribute name="name" type="wstring">
1894	<desc>
1895	Name of the virtual machine.
1896
1897	Besides being used for human-readable identification purposes
1898	everywhere in VirtualBox, the virtual machine name is also used
1899	as a name of the machine's settings file and as a name of the
1900	subdirectory this settings file resides in. Thus, every time you
1901	change the value of this property, the settings file will be
1902	renamed once you call <link to="#saveSettings()"/> to confirm the
1903	change. The containing subdirectory will be also renamed, but
1904	only if it has exactly the same name as the settings file
1905	itself prior to changing this property (for backward compatibility
1906	with previous API releases). The above implies the following
1907	limitations:
1908	<ul>
1909	<li>The machine name cannot be empty.</li>
1910	<li>The machine name can contain only characters that are valid
1911	file name characters according to the rules of the file
1912	system used to store VirtualBox configuration.</li>
1913	<li>You cannot have two or more machines with the same name
1914	if they use the same subdirectory for storing the machine
1915	settings files.</li>
1916	<li>You cannot change the name of the machine if it is running,
1917	or if any file in the directory containing the settings file
1918	is being used by another running machine or by any other
1919	process in the host operating system at a time when
1920	<link to="#saveSettings()"/> is called.
1921	</li>
1922	</ul>
1923	If any of the above limitations are hit, <link to="#saveSettings()"/>
1924	will return an appropriate error message explaining the exact
1925	reason and the changes you made to this machine will not be
1926	saved.
1927	<note>
1928	For "legacy" machines created using the
1929	<link to="IVirtualBox::createLegacyMachine()"/> call,
1930	the above naming limitations do not apply because the
1931	machine name does not affect the settings file name.
1932	The settings file name remains the same as it was specified
1933	during machine creation and never changes.
1934	</note>
1935	</desc>
1936	</attribute>
1937
1938	<attribute name="description" type="wstring">
1939	<desc>
1940	Description of the virtual machine.
1941
1942	The description attribute can contain any text and is
1943	typically used to describe the hardware and software
1944	configuration of the virtual machine in detail (i.e. network
1945	settings, versions of the installed software and so on).
1946	</desc>
1947	</attribute>
1948
1949	<attribute name="id" type="uuid" readonly="yes">
1950	<desc>UUID of the virtual machine.</desc>
1951	</attribute>
1952
1953	<attribute name="OSType" type="IGuestOSType">
1954	<desc>
1955	Guest OS type configured by the user.
1956	<note>
1957	This value may differ from the value returned by
1958	<link to="IGuest::OSType"/> if Guest Additions are
1959	installed to the guest OS.
1960	</note>
1961	</desc>
1962	</attribute>
1963
1964	<attribute name="memorySize" type="unsigned long">
1965	<desc>Sytem memory size in megabytes.</desc>
1966	</attribute>
1967
1968	<attribute name="VRAMSize" type="unsigned long">
1969	<desc>Video memory size in megabytes.</desc>
1970	</attribute>
1971
1972	<attribute name="MonitorCount" type="unsigned long">
1973	<desc>
1974	Number of virtual monitors.
1975	<note>
1976	Only effective on Windows XP and later guests with
1977	Guest Additions installed.
1978	</note>
1979	</desc>
1980	</attribute>
1981
1982	<attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
1983	<desc>Object containing all BIOS settings.</desc>
1984	</attribute>
1985
1986	<attribute name="HWVirtExEnabled" type="TriStateBool">
1987	<desc>
1988	This setting determines whether VirtualBox will try to make use of
1989	the host CPU's hardware virtualization extensions such as Intel VT-x
1990	and AMD SVM. Note that in case such extensions are not available,
1991	they will not be used.
1992	</desc>
1993	</attribute>
1994
1995	<attribute name="snapshotFolder" type="wstring">
1996	<desc>
1997	Full path to the directory used to store snapshot data
1998	(difrerencing hard disks and saved state files) of this machine.
1999
2000	The initial value of this property is
2001	<tt><</tt><link to="#settingsFilePath">
2002	path_to_settings_file</link><tt>>/<</tt>
2003	<link to="#id">machine_uuid</link>
2004	<tt>></tt>.
2005
2006	Currently, it is an error to try to change this property on
2007	a machine that has snapshots (because this would require to
2008	move possibly large files to a different location).
2009	A separate method will be available for this purpose later.
2010
2011	<note>
2012	Setting this property to <tt>null</tt> will restore the
2013	initial value.
2014	</note>
2015	<note>
2016	When setting this property, the specified path can be
2017	absolute (full path) or relative to the directory where the
2018	<link to="#settingsFilePath">machine settings file</link>
2019	is located. When reading this property, a full path is
2020	always returned.
2021	</note>
2022	<note>
2023	The specified path may not exist, it will be created
2024	when necessary.
2025	</note>
2026	</desc>
2027	</attribute>
2028
2029	<attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
2030	<desc>VRDP server object.</desc>
2031	</attribute>
2032
2033	<attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
2034	<desc>Collection of hard disks attached to the machine.</desc>
2035	</attribute>
2036
2037	<attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
2038	<desc>Associated DVD drive object.</desc>
2039	</attribute>
2040
2041	<attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
2042	<desc>Associated floppy drive object.</desc>
2043	</attribute>
2044
2045	<attribute name="USBController" type="IUSBController" readonly="yes">
2046	<desc>Associated USB controller object.</desc>
2047	</attribute>
2048
2049	<attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
2050	<desc>Associated audio adapter, always present.</desc>
2051	</attribute>
2052
2053	<attribute name="settingsFilePath" type="wstring" readonly="yes">
2054	<desc>
2055	Full name of the file containing machine settings data.
2056	</desc>
2057	</attribute>
2058
2059	<attribute name="settingsModified" type="boolean" readonly="yes">
2060	<desc>
2061	Whether the settings of this machine have been modified
2062	(but neither yet saved nor discarded).
2063	<note>
2064	Reading this property is only valid on instances returned
2065	by <link to="ISession::machine"/> and on new machines
2066	created by <link to="IVirtualBox::createMachine"/> or opened
2067	by <link to="IVirtualBox::openMachine"/> but not
2068	yet registered, or on unregistered machines after calling
2069	<link to="IVirtualBox::unregisterMachine"/>. For all other
2070	cases, the settigs can never be modified.
2071	</note>
2072	<note>
2073	For newly created unregistered machines, the value of this
2074	property is always TRUE until <link to="#saveSettings"/>
2075	is called (no matter if any machine settings have been
2076	changed after the creation or not). For opened machines
2077	the value is set to FALSE (and then follows to normal rules).
2078	</note>
2079	</desc>
2080	</attribute>
2081
2082	<attribute name="sessionState" type="SessionState" readonly="yes">
2083	<desc>Current session state for this machine.</desc>
2084	</attribute>
2085
2086	<attribute name="sessionType" type="wstring" readonly="yes">
2087	<desc>
2088	Type of the session. If <link to="#sessionState"/> is
2089	SessionSpawning or SessionOpen, this attribute contains the
2090	same value as passed to the
2091	<link to="IVirtualBox::openRemoteSession()"/> method in the @a
2092	type parameter. If the session was opened directly using
2093	<link to="IVirtualBox::openSession()"/>, or if
2094	<link to="#sessionState"/> is SessionClosed, the value of this
2095	attribute is @c null.
2096	</desc>
2097	</attribute>
2098
2099	<attribute name="sessionPid" type="unsigned long" readonly="yes">
2100	<desc>
2101	Identifier of the session process. This attribute contains the
2102	platform-dependent identifier of the process that has opened a
2103	direct session for this machine using the
2104	<link to="IVirtualBox::openSession()"/> call. The returned value
2105	is only valid if <link to="#sessionState"/> is SessionOpen or
2106	SessionClosing (i.e. a session is currently open or being
2107	closed) by the time this property is read.
2108	</desc>
2109	</attribute>
2110
2111	<attribute name="state" type="MachineState" readonly="yes">
2112	<desc>Current execution state of this machine.</desc>
2113	</attribute>
2114
2115	<attribute name="lastStateChange" type="long long" readonly="yes">
2116	<desc>
2117	Time stamp of the last execution state change,
2118	in milliseconds since 1970-01-01 UTC.
2119	</desc>
2120	</attribute>
2121
2122	<attribute name="stateFilePath" type="wstring" readonly="yes">
2123	<desc>
2124	Full path to the file that stores the execution state of
2125	the machine when it is in the <link to="MachineState::Saved"/>
2126	state.
2127	<note>
2128	When the machine is not in the Saved state, this attribute
2129	<tt>null</tt>.
2130	</note>
2131	</desc>
2132	</attribute>
2133
2134	<attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
2135	<desc>
2136	Current snapshot of this machine.
2137	<note>
2138	A <tt>null</tt> object is returned if the machine doesn't
2139	have snapshots.
2140	</note>
2141	<see><link to="ISnapshot"/></see>
2142	</desc>
2143	</attribute>
2144
2145	<attribute name="snapshotCount" type="unsigned long" readonly="yes">
2146	<desc>
2147	Number of snapshots taken on this machine. Zero means the
2148	machine doesn't have any snapshots.
2149	</desc>
2150	</attribute>
2151
2152	<attribute name="currentStateModified" type="boolean" readonly="yes">
2153	<desc>
2154	Returns <tt>true</tt> if the current state of the machine is not
2155	identical to the state stored in the current snapshot.
2156
2157	The current state is identical to the current snapshot right
2158	after one of the following calls are made:
2159	<ul>
2160	<li><link to="IConsole::discardCurrentState"/> or
2161	<link to="IConsole::discardCurrentSnapshotAndState"/>
2162	</li>
2163	<li><link to="IConsole::takeSnapshot"/> (issued on a
2164	powered off or saved machine, for which
2165	<link to="#settingsModified"/> returns <tt>false</tt>)
2166	</li>
2167	<li><link to="IMachine::setCurrentSnapshot"/>
2168	</li>
2169	</ul>
2170
2171	The current state remains identical until one of the following
2172	happens:
2173	<ul>
2174	<li>settings of the machine are changed</li>
2175	<li>the saved state is discarded</li>
2176	<li>the current snapshot is discarded</li>
2177	<li>an attempt to execute the machine is made</li>
2178	</ul>
2179
2180	<note>
2181	For machines that don't have snapshots, this property is
2182	always <tt>false</tt>.
2183	</note>
2184	</desc>
2185	</attribute>
2186
2187	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
2188	<desc>
2189	Collection of shared folders for this machine. These folders
2190	are shared automatically upon machine startup and available only
2191	to the guest OS installed within this machine.
2192
2193	New folders to share are added to the collection using
2194	<link to="#createSharedFolder"/>. An existing shared folder can
2195	be removed using <link to="#removeSharedFolder"/>.
2196	</desc>
2197	</attribute>
2198
2199	<attribute name="clipboardMode" type="ClipboardMode">
2200	<desc>
2201	Synchronization mode between the host OS clipboard
2202	and the guest OS clipboard.
2203	</desc>
2204	</attribute>
2205
2206	<method name="setBootOrder">
2207	<desc>
2208	Puts the given device to the specified position in
2209	the boot order.
2210
2211	@todo [remove?]
2212	If the machine can have more than one device of the given type
2213	(such as hard disks), then a separate method should be used to
2214	specify the boot order for individual devices. Using this method
2215	in such cases will put the first device in the group
2216	(for example, a hard disk attached as Master on the primary
2217	IDE controller) to the given position.
2218
2219	To indicate that no any device is associated with the
2220	given position, <link to="DeviceType::NoDevice"/> should be used.
2221
2222	@todo setHardDiskBootOrder(), setNetworkBootOrder()
2223	</desc>
2224	<param name="position" type="unsigned long" dir="in">
2225	<desc>
2226	Position in the boot order (<tt>1</tt> to the total number of
2227	devices the machine can boot from, as returned by
2228	<link to="ISystemProperties::maxBootPosition"/>).
2229	</desc>
2230	</param>
2231	<param name="device" type="DeviceType" dir="in">
2232	<desc>
2233	The type of the device used to boot at the given position.
2234	</desc>
2235	</param>
2236	</method>
2237
2238	<method name="getBootOrder" const="yes">
2239	<desc>
2240	Returns the device type that occupies the specified
2241	position in the boot order.
2242
2243	@todo [remove?]
2244	If the machine can have more than one device of the returned type
2245	(such as hard disks), then a separate method should be used to
2246	retrieve the individual device that occupies the given position.
2247
2248	If here are no devices at the given position, then
2249	<link to="DeviceType::NoDevice"/> is returned.
2250
2251	@todo getHardDiskBootOrder(), getNetworkBootOrder()
2252	</desc>
2253	<param name="order" type="unsigned long" dir="in">
2254	<desc>
2255	Position in the boot order (<tt>1</tt> to the total number of
2256	devices the machine can boot from, as returned by
2257	<link to="ISystemProperties::maxBootPosition"/>).
2258	</desc>
2259	</param>
2260	<param name="device" type="DeviceType" dir="return">
2261	<desc>
2262	Device at the given position.
2263	</desc>
2264	</param>
2265	</method>
2266
2267	<method name="attachHardDisk">
2268	<desc>
2269
2270	Attaches a virtual hard disk identified by the given UUID to the
2271	given device slot of the given controller. The specified device
2272	must not have another disk attached and the given hard disk must
2273	not be already attached to this machine.
2274
2275	See <link to="IHardDisk"/> for detailed information about
2276	attaching hard disks.
2277
2278	<note>You cannot attach a hard disk to a running machine. Also,
2279	you cannot attach a hard disk to a newly created machine until
2280	it is registered.</note>
2281
2282	<note>Attaching a hard disk to a machine creates a <i>lazy</i>
2283	attachment. In particular, no differeincing images are
2284	actually created until <link to="#saveSettings"/> is called to
2285	commit all changed settings.</note>
2286
2287	</desc>
2288	<param name="diskID" type="uuid" dir="in">
2289	<desc>UUID of the hard disk to attach.</desc>
2290	</param>
2291	<param name="controller" type="DiskControllerType" dir="in">
2292	<desc>Controller to attach the hard disk to.</desc>
2293	</param>
2294	<param name="device" type="long" dir="in">
2295	<desc>Device slot to attach the hard disk to.</desc>
2296	</param>
2297	</method>
2298
2299	<method name="getHardDisk" const="yes">
2300	<desc>
2301	Returns the hard disk attached to the
2302	given controller under the specified device number.
2303	</desc>
2304	<param name="controller" type="DiskControllerType" dir="in"/>
2305	<param name="deviceNumber" type="long" dir="in"/>
2306	<param name="hardDisk" type="IHardDisk" dir="return"/>
2307	</method>
2308
2309	<method name="detachHardDisk">
2310	<desc>
2311
2312	Detaches the hard disk drive attached to the given device slot
2313	of the given controller.
2314
2315	See <link to="IHardDisk"/> for detailed information about
2316	attaching hard disks.
2317
2318	<note>You cannot detach a hard disk from a running
2319	machine.</note>
2320
2321	<note>Detaching a hard disk from a machine creates a <i>lazy</i>
2322	detachment. In particular, if the detached hard disk is a
2323	differencing hard disk, it is not actually deleted until <link
2324	to="#saveSettings"/> is called to commit all changed settings.
2325	Keep in mind, that doing <link to="#saveSettings"/> will
2326	<b>physically delete</b> all detached differencing hard disks,
2327	so be careful.</note>
2328
2329	</desc>
2330	<param name="controller" type="DiskControllerType" dir="in">
2331	<desc>Controller to dettach the hard disk from.</desc>
2332	</param>
2333	<param name="device" type="long" dir="in">
2334	<desc>Device slot to dettach the hard disk from.</desc>
2335	</param>
2336	</method>
2337
2338	<method name="getNetworkAdapter" const="yes">
2339	<desc>
2340	Returns the network adapter associated with the given slot.
2341	Slots are numbered sequentially, starting with zero. The total
2342	number of adapters per every machine is defined by the
2343	<link to="ISystemProperties::networkAdapterCount"/> property,
2344	so the maximum slot number is one less than that property's value.
2345	</desc>
2346	<param name="slot" type="unsigned long" dir="in"/>
2347	<param name="adapter" type="INetworkAdapter" dir="return"/>
2348	</method>
2349
2350	<method name="getNextExtraDataKey">
2351	<desc>
2352	Returns the extra data key name following the supplied key.
2353	An error is returned if the supplied key does not exist.
2354	NULL is returned if the supplied key is the last key.
2355	When supplying NULL for the key, the first item is returned.
2356	NextValue is an optional parameter and if supplied, the next
2357	key's value is returned as well.
2358	</desc>
2359	<param name="key" type="wstring" dir="in"/>
2360	<param name="nextKey" type="wstring" dir="out"/>
2361	<param name="nextValue" type="wstring" dir="out"/>
2362	</method>
2363
2364	<method name="getExtraData">
2365	<desc>Returns associated extra data.</desc>
2366	<param name="key" type="wstring" dir="in"/>
2367	<param name="value" type="wstring" dir="return"/>
2368	</method>
2369
2370	<method name="setExtraData">
2371	<desc>Sets associated extra data.</desc>
2372	<param name="key" type="wstring" dir="in"/>
2373	<param name="value" type="wstring" dir="in"/>
2374	</method>
2375
2376	<method name="saveSettings">
2377	<desc>
2378	Saves any changes to machine settings made since the session
2379	has been opened or a new machine has been created, or since the
2380	last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
2381	For registered machines, new settings become visible to all
2382	other VirtualBox clients after successful invocation of this
2383	method.
2384	<note>
2385	The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
2386	notification event after the configuration has been successfully
2387	saved (only for registered machines).
2388	</note>
2389	<note>
2390	Calling this method is only valid on instances returned
2391	by <link to="ISession::machine"/> and on new machines
2392	created by <link to="IVirtualBox::createMachine"/> but not
2393	yet registered, or on unregistered machines after calling
2394	<link to="IVirtualBox::unregisterMachine"/>.
2395	</note>
2396	</desc>
2397	</method>
2398
2399	<method name="discardSettings">
2400	<desc>
2401	Discards any changes to the machine settings made since the session
2402	has been opened or since the last call to <link to="#saveSettings"/>
2403	or <link to="#discardSettings"/>.
2404	<note>
2405	Calling this method is only valid on instances returned
2406	by <link to="ISession::machine"/> and on new machines
2407	created by <link to="IVirtualBox::createMachine"/> or
2408	opened by <link to="IVirtualBox::openMachine"/> but not
2409	yet registered, or on unregistered machines after calling
2410	<link to="IVirtualBox::unregisterMachine"/>.
2411	</note>
2412	</desc>
2413	</method>
2414
2415	<method name="deleteSettings">
2416	<desc>
2417	Deletes the settings file of this machine from disk.
2418	The machine must not be registered in order for this operation
2419	to succeed.
2420	<note>
2421	<link to="#settingsModified"/> will return TRUE after this
2422	method successfully returns.
2423	</note>
2424	<note>
2425	Calling this method is only valid on instances returned
2426	by <link to="ISession::machine"/> and on new machines
2427	created by <link to="IVirtualBox::createMachine"/> or
2428	opened by <link to="IVirtualBox::openMachine"/> but not
2429	yet registered, or on unregistered machines after calling
2430	<link to="IVirtualBox::unregisterMachine"/>.
2431	</note>
2432	<note>
2433	The deleted machine settings file can be restored (saved again)
2434	by calling <link to="#saveSettings"/>.
2435	</note>
2436	</desc>
2437	</method>
2438
2439	<method name="getSnapshot">
2440	<desc>
2441	Returns a snapshot of this machine with the given UUID.
2442	A <tt>null</tt> UUID can be used to obtain the first snapshot
2443	taken on this machine. This is useful if you want to traverse
2444	the whole tree of snapshots starting from the root.
2445	</desc>
2446	<param name="id" type="uuid" dir="in">
2447	<desc>UUID of the snapshot to get</desc>
2448	</param>
2449	<param name="snapshot" type="ISnapshot" dir="return">
2450	<desc>Snapshot object with the given UUID.</desc>
2451	</param>
2452	</method>
2453
2454	<method name="findSnapshot">
2455	<desc>
2456	Returns a snapshot of this machine with the given name.
2457	</desc>
2458	<param name="name" type="wstring" dir="in">
2459	<desc>Name of the snapshot to find</desc>
2460	</param>
2461	<param name="snapshot" type="ISnapshot" dir="return">
2462	<desc>Snapshot object with the given name.</desc>
2463	</param>
2464	</method>
2465
2466	<method name="setCurrentSnapshot">
2467	<desc>
2468	Sets the current snapshot of this machine.
2469	<note>
2470	In the current implementation, this operation is not
2471	implemented.
2472	</note>
2473	</desc>
2474	<param name="id" type="uuid" dir="in">
2475	<desc>UUID of the snapshot to set as the current snapshot.</desc>
2476	</param>
2477	</method>
2478
2479	<method name="createSharedFolder">
2480	<desc>
2481	Creates a new shared folder by associating the given logical
2482	name with the given host path, adds it to the collection of
2483	shared folders and starts sharing it.
2484	Refer to the description of <link to="ISharedFolder"/> to read
2485	about logical name unicity.
2486	</desc>
2487	<param name="name" type="wstring" dir="in">
2488	<desc>Unique logical name of the shared folder.</desc>
2489	</param>
2490	<param name="hostPath" type="wstring" dir="in">
2491	<desc>Full path to the shared folder in the host file system.</desc>
2492	</param>
2493	</method>
2494
2495	<method name="removeSharedFolder">
2496	<desc>
2497	Removes a shared folder with the given name previously created
2498	by <link to="#createSharedFolder"/> from the collection of
2499	shared folders and stops sharing it.
2500	</desc>
2501	<param name="name" type="wstring" dir="in">
2502	<desc>Logical name of the shared folder to remove.</desc>
2503	</param>
2504	</method>
2505
2506	</interface>
2507
2508	<!--
2509	// IConsole
2510	/////////////////////////////////////////////////////////////////////////
2511	-->
2512
2513	<interface
2514	name="IConsoleCallback" extends="$unknown"
2515	uuid="05D3DD3F-0550-4953-BB3C-4ECB3EBF7C2E"
2516	>
2517
2518	<method name="onMousePointerShapeChange">
2519	<desc>
2520	Notification when the guest mouse pointer shape has
2521	changed. The new shape data is given.
2522	</desc>
2523	<param name="visible" type="boolean" dir="in">
2524	<desc>
2525	Flag whether the pointer is visible.
2526	</desc>
2527	</param>
2528	<param name="alpha" type="boolean" dir="in">
2529	<desc>
2530	Flag whether the pointer has an alpha channel.
2531	</desc>
2532	</param>
2533	<param name="xHot" type="unsigned long" dir="in">
2534	<desc>
2535	The pointer hot spot x coordinate.
2536	</desc>
2537	</param>
2538	<param name="yHot" type="unsigned long" dir="in">
2539	<desc>
2540	The pointer hot spot y coordinate.
2541	</desc>
2542	</param>
2543	<param name="width" type="unsigned long" dir="in">
2544	<desc>
2545	Width of the pointer shape in pixels.
2546	</desc>
2547	</param>
2548	<param name="height" type="unsigned long" dir="in">
2549	<desc>
2550	Height of the pointer shape in pixels.
2551	</desc>
2552	</param>
2553	<param name="shape" type="octet" mod="ptr" dir="in">
2554	<desc>
2555	Address of the shape buffer.
2556
2557	The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
2558
2559	For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
2560	For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
2561
2562	AND mask presents for pointers with alpha channel, so if the callback does not
2563	support alpha, the pointer could be displayed as a normal color pointer.
2564
2565	The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
2566	therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
2567	end of any scanline are undefined.
2568
2569	The XOR mask follows the AND mask on the next 4 bytes aligned offset:
2570	<tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>
2571	Bytes in the gap between the AND and the XOR mask are undefined.
2572	XOR mask scanlines have no gap between them and size of XOR mask is:
2573	<tt>cXor = width * 4 * height</tt>.
2574
2575	<note>
2576	If 'shape' is equal to 0, only pointer visibility is being changed.
2577	</note>
2578	</desc>
2579	</param>
2580	</method>
2581
2582	<method name="onMouseCapabilityChange">
2583	<desc>
2584	Notification when the mouse capabilities reported by the
2585	guest have changed. The new capabilities are passed.
2586	</desc>
2587	<param name="supportsAbsolute" type="boolean" dir="in"/>
2588	<param name="needsHostCursor" type="boolean" dir="in"/>
2589	</method>
2590
2591	<method name="onKeyboardLedsChange">
2592	<desc>
2593	Notification of the host if the guest executed the KBD_CMD_SET_LEDS
2594	command to alter the state of the keyboard LEDs.
2595	</desc>
2596	<param name="numLock" type="boolean" dir="in"/>
2597	<param name="capsLock" type="boolean" dir="in"/>
2598	<param name="scrollLock" type="boolean" dir="in"/>
2599	</method>
2600
2601	<method name="onStateChange">
2602	<desc>
2603	Notification when the execution state of the machine has changed.
2604	The new state will be given.
2605	</desc>
2606	<param name="state" type="MachineState" dir="in"/>
2607	</method>
2608
2609	<method name="onAdditionsStateChange">
2610	<desc>
2611	Notification when a Guest Additions property changes.
2612	Interested callees should query IGuest's properties to
2613	find out what has changed.
2614	</desc>
2615	</method>
2616
2617	<method name="onRuntimeError">
2618	<desc>
2619	Notification when an error happens during the virtual
2620	machine execution.
2621
2622	There are three kinds of runtime errors:
2623	<ul>
2624	<li><i>fatal</i></li>
2625	<li><i>non-fatal with retry</i></li>
2626	<li><i>non-fatal warnings</i></li>
2627	</ul>
2628
2629	<b>Fatal</b> errors are indicated by the @a fatal parameter set
2630	to <tt>true</tt>. In case of fatal errors, the virtual machine
2631	execution is always paused before calling this notification, and
2632	the notification handler is supposed either to immediately save
2633	the virtual machine state using <link to="IConsole::saveState()"/>
2634	or power it off using <link to="IConsole::powerDown()"/>.
2635	Resuming the execution can lead to unpredictable results.
2636
2637	<b>Non-fatal</b> errors and warnings are indicated by the
2638	@a fatal parameter set to <tt>false</tt>. If the virtual machine
2639	is in the Paused state by the time the error notification is
2640	received, it means that the user can <i>try to resume</i> the machine
2641	execution after attempting to solve the probem that caused the
2642	error. In this case, the notification handler is supposed
2643	to show an appropriate message to the user (depending on the
2644	value of the @a id parameter) that offers several actions such
2645	as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
2646	wants to retry, the notification handler should continue
2647	the machine execution using the <link to="IConsole::resume()"/>
2648	call. If the machine execution is not Paused during this
2649	notification, then it means this notification is a <i>warning</i>
2650	(for example, about a fatal condition that can happen very soon);
2651	no immediate action is required from the user, the machine
2652	continues its normal execution.
2653
2654	Note that in either case the notification handler
2655	<b>must not</b> perform any action directly on a thread
2656	where this notification is called. Everything it is allowed to
2657	do is to post a message to another thread that will then talk
2658	to the user and take the corresponding action.
2659
2660	Currently, the following error identificators are known:
2661	<ul>
2662	<li><tt>"HostMemoryLow"</tt></li>
2663	<li><tt>"HostAudioNotResponding"</tt></li>
2664	<li><tt>"VDIStorageFull"</tt></li>
2665	</ul>
2666
2667	<note>
2668	This notification is not designed to be implemented by more
2669	than one callback at a time. If you have multiple
2670	IConsoleCallback instances registered on the given
2671	IConsole object, make sure you just return S_OK from all but
2672	one of them that does actual user notification and performs
2673	necessary actions.
2674	</note>
2675
2676	</desc>
2677	<param name="fatal" type="boolean" dir="in">
2678	<desc>Whether the error is fatal or not</desc>
2679	</param>
2680	<param name="id" type="wstring" dir="in">
2681	<desc>Error identificator</desc>
2682	</param>
2683	<param name="message" type="wstring" dir="in">
2684	<desc>Optional error message</desc>
2685	</param>
2686	</method>
2687
2688	</interface>
2689
2690	<interface
2691	name="IRemoteDisplayInfo" extends="$unknown"
2692	uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
2693	>
2694	<attribute name="active" type="boolean" readonly="yes">
2695	<desc>
2696	Whether the remote display connection is active.
2697	</desc>
2698	</attribute>
2699
2700	<attribute name="numberOfClients" type="unsigned long" readonly="yes">
2701	<desc>
2702	How many times a client connected.
2703	</desc>
2704	</attribute>
2705
2706	<attribute name="beginTime" type="long long" readonly="yes">
2707	<desc>
2708	When the last connection was established, in milliseconds since 1970-01-01 UTC.
2709	</desc>
2710	</attribute>
2711
2712	<attribute name="endTime" type="long long" readonly="yes">
2713	<desc>
2714	When the last connection was terminated or the current time, if
2715	connection is still active, in milliseconds since 1970-01-01 UTC.
2716	</desc>
2717	</attribute>
2718
2719	<attribute name="bytesSent" type="unsigned long long" readonly="yes">
2720	<desc>
2721	How many bytes were sent in last or current, if still active, connection.
2722	</desc>
2723	</attribute>
2724
2725	<attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
2726	<desc>
2727	How many bytes were sent in all connections.
2728	</desc>
2729	</attribute>
2730
2731	<attribute name="bytesReceived" type="unsigned long long" readonly="yes">
2732	<desc>
2733	How many bytes were received in last or current, if still active, connection.
2734	</desc>
2735	</attribute>
2736
2737	<attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
2738	<desc>
2739	How many bytes were received in all connections.
2740	</desc>
2741	</attribute>
2742
2743	<attribute name="user" type="wstring" readonly="yes">
2744	<desc>
2745	Login user name supplied by the client.
2746	</desc>
2747	</attribute>
2748
2749	<attribute name="domain" type="wstring" readonly="yes">
2750	<desc>
2751	Login domain name supplied by the client.
2752	</desc>
2753	</attribute>
2754
2755	<attribute name="clientName" type="wstring" readonly="yes">
2756	<desc>
2757	The client name supplied by the client.
2758	</desc>
2759	</attribute>
2760
2761	<attribute name="clientIP" type="wstring" readonly="yes">
2762	<desc>
2763	The IP address of the client.
2764	</desc>
2765	</attribute>
2766
2767	<attribute name="clientVersion" type="unsigned long" readonly="yes">
2768	<desc>
2769	The client software version number.
2770	</desc>
2771	</attribute>
2772
2773	<attribute name="encryptionStyle" type="unsigned long" readonly="yes">
2774	<desc>
2775	Public key exchange method used when connection was established.
2776	Values: 0 - RDP4 public key exchange scheme.
2777	1 - X509 sertificates were sent to client.
2778	</desc>
2779	</attribute>
2780
2781	</interface>
2782
2783	<interface
2784	name="IConsole" extends="$unknown"
2785	uuid="1DEA5C4B-0753-4193-B909-22330F64EC45"
2786	>
2787	<attribute name="machine" type="IMachine" readonly="yes">
2788	<desc>
2789	Machine object this console is sessioned with.
2790	<note>
2791	This is a convenience property, it has the same value as
2792	<link to="ISession::machine"/> of the corresponding session
2793	object.
2794	</note>
2795	</desc>
2796	</attribute>
2797
2798	<attribute name="state" type="MachineState" readonly="yes">
2799	<desc>
2800	Current execution state of the machine.
2801	<note>
2802	This property always returns the same value as the corresponding
2803	property of the IMachine object this console is sessioned with.
2804	For the process, that owns (executes) the VM, this is the
2805	preferrable way of quierying the VM state, because no IPC
2806	calls are made.
2807	</note>
2808	</desc>
2809	</attribute>
2810
2811	<attribute name="guest" type="IGuest" readonly="yes">
2812	<desc>Guest object.</desc>
2813	</attribute>
2814
2815	<attribute name="keyboard" type="IKeyboard" readonly="yes">
2816	<desc>
2817	Virtual keyboard object.
2818	<note>
2819	If the machine is not running, any attempt to use
2820	the returned object will result in an error.
2821	</note>
2822	</desc>
2823	</attribute>
2824
2825	<attribute name="mouse" type="IMouse" readonly="yes">
2826	<desc>
2827	Virtual mouse object.
2828	<note>
2829	If the machine is not running, any attempt to use
2830	the returned object will result in an error.
2831	</note>
2832	</desc>
2833	</attribute>
2834
2835	<attribute name="display" type="IDisplay" readonly="yes">
2836	<desc>Virtual display object.
2837	<note>
2838	If the machine is not running, any attempt to use
2839	the returned object will result in an error.
2840	</note>
2841	</desc>
2842	</attribute>
2843
2844	<attribute name="debugger" type="IMachineDebugger" readonly="yes">
2845	<desc>Debugging interface.</desc>
2846	</attribute>
2847
2848	<attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
2849	<desc>
2850	Collection of USB devices currently attached to the virtual
2851	USB controller.
2852	<note>
2853	The collection is empty if the machine is not running.
2854	</note>
2855	</desc>
2856	</attribute>
2857
2858	<attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
2859	<desc>
2860	List of USB devices currently attached to the remote VRDP client.
2861	Once a new device is physically attached to the remote host computer,
2862	it appears in this list and remains there until detached.
2863	</desc>
2864	</attribute>
2865
2866	<attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
2867	<desc>
2868	Collection of shared folders for the current session.
2869	This collection is initially empty and is cleared once the
2870	session is closed. On other words, this collection represents
2871	transient shares (as opposed to <link to="IMachine::sharedFolders"/>
2872	that stores permanent shares stored in the settings file).
2873
2874	New folders to share are added to the collection using
2875	<link to="#createSharedFolder"/>. An existing shared folder can
2876	be removed using <link to="#removeSharedFolder"/>.
2877	</desc>
2878	</attribute>
2879
2880	<attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
2881	<desc>
2882	Interface that provides information on Remote Display (VRDP) connection.
2883	</desc>
2884	</attribute>
2885
2886	<method name="powerUp">
2887	<desc>
2888	Starts the virtual machine execution using the current machine
2889	state (i.e. its current execution state, current settings and
2890	current hard disks).
2891
2892	If the machine is powered off or aborted, the execution will
2893	start from the beginning (as if the real hardware were just
2894	powered on).
2895
2896	If the machine is in the <link to="MachineState::Saved"/> state,
2897	it will continue its execution the point where the state has
2898	beem saved.
2899
2900	<see>#saveState</see>
2901	</desc>
2902	<param name="progress" type="IProgress" dir="return">
2903	<desc>Progress object to track the operation completion.</desc>
2904	</param>
2905	</method>
2906
2907	<method name="powerDown">
2908	<desc>
2909	Stops the virtual machine execution.
2910	After this operation completes, the machine will go to the
2911	PoweredOff state.
2912	</desc>
2913	</method>
2914
2915	<method name="reset">
2916	<desc>Resets the virtual machine.</desc>
2917	</method>
2918
2919	<method name="pause">
2920	<desc>Pauses the virtual machine execution.</desc>
2921	</method>
2922
2923	<method name="resume">
2924	<desc>Resumes the virtual machine execution.</desc>
2925	</method>
2926
2927	<method name="powerButton">
2928	<desc>Send the ACPI power button event to the guest.</desc>
2929	</method>
2930
2931	<method name="saveState">
2932	<desc>
2933	Saves the current execution state of a running virtual machine
2934	and stops its executiuon.
2935
2936	After this operation completes, the machine will go to the
2937	Saved state. Next time it is powered up, this state will
2938	be restored and the machine will continue its execution from
2939	the place where it was saved.
2940
2941	This operation differs from taking a snapshot to the effect
2942	that it doesn't create new differencing hard disks. Also, once
2943	the machine is powered up from the state saved using this method,
2944	the saved state is deleted, so it will be impossible to return
2945	to this state later.
2946
2947	<note>On success, this method implicitly calls <link
2948	to="IMachine::saveSettings"/> to save all current machine
2949	settings (including runtime changes to the DVD drive, etc.).
2950	Together with the impossibility to change any VM settings when
2951	it is in the Saved state, this guarantees the adequate hardware
2952	configuration of the machine when it is restored from the saved
2953	state file.</note>
2954
2955	<note>
2956	The machine must be in the Running or Paused state, otherwise
2957	the operation will fail.
2958	</note>
2959
2960	<see><link to="#takeSnapshot"/></see>
2961	</desc>
2962	<param name="progress" type="IProgress" dir="return">
2963	<desc>Progress object to track the operation completion.</desc>
2964	</param>
2965	</method>
2966
2967	<method name="discardSavedState">
2968	<desc>
2969	Discards (deletes) the saved state of the virtual machine
2970	previously created by <link to="#saveState"/>. Next time the
2971	machine is powered up, a clean boot will occur.
2972	<note>
2973	This operation is equivalent to resetting or powering off
2974	the machine without doing a proper shutdown in the guest OS.
2975	</note>
2976	</desc>
2977	</method>
2978
2979	<method name="getDeviceActivity">
2980	<desc>
2981	Gets the current activity type of a given device or device group.
2982	</desc>
2983	<param name="type" type="DeviceType" dir="in"/>
2984	<param name="activity" type="DeviceActivity" dir="return"/>
2985	</method>
2986
2987	<method name="attachUSBDevice">
2988	<desc>
2989	Attaches a host USB device with the given UUID to the
2990	USB controller of the virtual machine.
2991
2992	The device needs to be in one of the following states:
2993	<link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
2994	<link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link> or
2995	<link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>,
2996	otherwise an error is immediately returned.
2997
2998	When the device state is
2999	<link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
3000	an error may also be returned if the host computer
3001	refuses to release it for some reason.
3002
3003	<see>IUSBController::DeviceFilters, USBDeviceState</see>
3004	</desc>
3005	<param name="id" type="uuid" dir="in">
3006	<desc>UUID of the host USB device to attach.</desc>
3007	</param>
3008	</method>
3009
3010	<method name="detachUSBDevice">
3011	<desc>
3012	Detaches an USB device with the given UUID from the USB controller
3013	oif the virtual machine.
3014
3015	After this method succeeds, the VirtualBox server reinitiates
3016	all USB filters as if the device were just physically attached
3017	to the host, but filters of this machine are ignored to avoid
3018	a possible automatic reattachment.
3019
3020	<see>IUSBController::DeviceFilters, USBDeviceState</see>
3021	</desc>
3022	<param name="id" type="uuid" dir="in">
3023	<desc>UUID of the USB device to detach.</desc>
3024	</param>
3025	<param name="device" type="IUSBDevice" dir="return">
3026	<desc>Detached USB device.</desc>
3027	</param>
3028	</method>
3029
3030	<method name="createSharedFolder">
3031	<desc>
3032	Creates a new shared folder by associating the given logical
3033	name with the given host path, adds it to the collection of
3034	shared folders and starts sharing it.
3035	Refer to the description of <link to="ISharedFolder"/> to read
3036	about logical name unicity.
3037	</desc>
3038	<param name="name" type="wstring" dir="in">
3039	<desc>Unique logical name of the shared folder.</desc>
3040	</param>
3041	<param name="hostPath" type="wstring" dir="in">
3042	<desc>Full path to the shared folder in the host file system.</desc>
3043	</param>
3044	</method>
3045
3046	<method name="removeSharedFolder">
3047	<desc>
3048	Removes a shared folder with the given name previously created
3049	by <link to="#createSharedFolder"/> from the collection of
3050	shared folders and stops sharing it.
3051	</desc>
3052	<param name="name" type="wstring" dir="in">
3053	<desc>Logical name of the shared folder to remove.</desc>
3054	</param>
3055	</method>
3056
3057	<method name="takeSnapshot">
3058	<desc>
3059	Saves the current execution state and all settings of the
3060	machine and creates differencing images for all
3061	normal (non-independent) hard disks.
3062
3063	This method can be called for a PoweredOff, Saved, Running or
3064	Paused virtual machine. When the machine is PoweredOff, an
3065	offline <link to="ISnapshot">snapshot</link> is created,
3066	in all other cases -- an online snapshot.
3067
3068	The taken snapshot is always based on the
3069	<link to="IMachine::currentSnapshot">current
3070	snapshot</link> of the associated virtual machine and becomes
3071	a new current snapshot.
3072
3073	<note>This method implicitly calls <link
3074	to="IMachine::saveSettings"/> to save all current machine
3075	settings before taking an offline snapshot.</note>
3076
3077	<see>ISnapshot, <link to="#saveState"/></see>
3078	</desc>
3079	<param name="name" type="wstring" dir="in">
3080	<desc>Short name for the snapshot.</desc>
3081	</param>
3082	<param name="description" type="wstring" dir="in">
3083	<desc>Optional description of the snapshot.</desc>
3084	</param>
3085	<param name="progress" type="IProgress" dir="return">
3086	<desc>Progress object to track the operation completion.</desc>
3087	</param>
3088	</method>
3089
3090	<method name="discardSnapshot">
3091	<desc>
3092
3093	Starts discarding the specified snapshot. The execution state
3094	and settings of the associated machine stored in the snapshot
3095	will be deleted. The contents of all differencing hard disks of
3096	this snapshot will be merged with the contents of their
3097	dependent child hard disks to keep the, disks valid (in other
3098	words, all changes represented by hard disks being discarded
3099	will be propagated to their child hard disks). After that, this
3100	snapshot's differencing hard disks will be deleted. The parent
3101	of this snapshot will become a new parent for all its child
3102	snapshots.
3103
3104	If the discarded snapshot is the current one, its parent
3105	snapshot will become a new current snapshot. The current machine
3106	state is not directly affected in this case, except that
3107	currently attached differencing hard disks based on hard disks
3108	of the discarded snapshot will be also merged as described
3109	above.
3110
3111	If the discarded snapshot is the first one (the root snapshot)
3112	and it has exactly one child snapshot, this child snapshot will
3113	become the first snapshot after discarding. If there are no
3114	children at all (i.e. the first snapshot is the only snapshot of
3115	the machine), both the current and the first snapshot of the
3116	machine will be set to null. In all other cases, the first
3117	snapshot cannot be discarded.
3118
3119	You cannot discard the snapshot if it stores <link
3120	to="HardDiskType::NormalHardDisk">normal</link>
3121	(non-differencing) hard disks that have differencing hard disks
3122	based on them. Snapshots of such kind can be discarded only when
3123	every normal hard disk has either no children at all or exactly
3124	one child. In the former case, the normal hard disk simply
3125	becomes unused (i.e. not attached to any VM). In the latter
3126	case, it receives all the changes strored in the child hard
3127	disk, and then it replaces the child hard disk in the
3128	configuration of the corresponding snapshot or machine.
3129
3130	Also, you cannot discard the snapshot if it stores hard disks
3131	(of any type) having differencing child hard disks that belong
3132	to other machines. Such snapshots can be only discarded after
3133	you discard all snapshots of other machines containing "foreign"
3134	child disks, or detach these "foreign" child disks from machines
3135	they are attached to.
3136
3137	One particular example of the snapshot storing normal hard disks
3138	is the first snapshot of a virtual machine that had normal hard
3139	disks attached when taking the snapshot. Be careful when
3140	discarding such snapshots because this implicitly commits
3141	changes (made since the snapshot being discarded has been taken)
3142	to normal hard disks (as described above), which may be not what
3143	you want.
3144
3145	The virtual machine is put to the <link
3146	to="MachineState::Discarding">Discarding</link> state until the
3147	discard operation is completed.
3148
3149	<note>The machine must not be running, otherwise the operation
3150	will fail.</note>
3151
3152	<note>
3153	Child hard disks of all normal hard disks of the
3154	discarded snapshot must be <link to="IHardDisk::accessible">
3155	accessible</link> for this operation to succeed.
3156	In particular, this means that all virtual machines,
3157	whose hard disks are directly or indirectly based on
3158	the hard disks of discarded snapshot, must be powered off.
3159	</note>
3160	<note>
3161	Merging hard disk contents can be very time and disk space
3162	consuming, if these disks are big in size and have many
3163	children. However, if the snapshot being discarded is the last
3164	(head) snapshot on the branch, the operation will be rather
3165	quick.
3166	</note>
3167	<note>
3168	Note that discarding the current snapshot
3169	will imlicitly call <link to="IMachine::saveSettings()"/> to
3170	make all current machine settings permanent.
3171	</note>
3172	</desc>
3173	<param name="id" type="uuid" dir="in">
3174	<desc>UUID of the snapshot to discard.</desc>
3175	</param>
3176	<param name="progress" type="IProgress" dir="return">
3177	<desc>Progress object to track the operation completion.</desc>
3178	</param>
3179	</method>
3180
3181	<method name="discardCurrentState">
3182	<desc>
3183	This operation is similar to <link to="#discardSnapshot()"/> but
3184	affects the current machine state. This means that the state stored
3185	in the current snapshot will become a new current state, and
3186	all current settings of the machine and changes stored in
3187	differencing hard disks will be lost.
3188
3189	After this operation is successfully completed, new empty
3190	differencing hard disks are created for all normal hard disks
3191	of the machine.
3192
3193	If the current snapshot of the machine is an online snapshot,
3194	the machine will go to the <link to="MachineState::Saved">
3195	saved state</link>, so that the next time it is powered on,
3196	the execution state will be restored from the current snapshot.
3197
3198	<note>The machine must not be running, otherwise the operation
3199	will fail.</note>
3200
3201	<note>If the machine state is <link
3202	to="MachineState::Saved">Saved</link> prior to this operation,
3203	the saved state file will be implicitly discarded (as if <link
3204	to="IConsole::discardSavedState()"/> were called).</note>
3205
3206	</desc>
3207	<param name="progress" type="IProgress" dir="return">
3208	<desc>Progress object to track the operation completion.</desc>
3209	</param>
3210	</method>
3211
3212	<method name="discardCurrentSnapshotAndState">
3213	<desc>
3214
3215	This method is equivalent to doing <link
3216	to="#discardSnapshot">discardSnapshot</link> (<link
3217	to="IMachine::currentSnapshot">currentSnapshot</link>.<link
3218	to="ISnapshot::id">id()</link>, ...) followed by <link
3219	to="#discardCurrentState()"/>.
3220
3221	As a result, the machine will be fully restored from the
3222	snapshot preceeding the current snapshot, while both the current
3223	snapshot and the current machine state will be discarded.
3224
3225	If the current snapshot is the first snapshot of the machine
3226	(i.e. it has the only snapshot), the current machine state will
3227	be discarded <b>before</b> discarding the snapshot. In other
3228	words, the machine will be restored from its last snapshot,
3229	before discarding it. This differs from performing a single
3230	<link to="#discardSnapshot()"/> call (note that no <link
3231	to="#discardCurrentState()"/> will be possible after it) to the
3232	effect that the latter will preserve the current state instead
3233	of discarding it.
3234
3235	Unless explicitly mentioned otherwise, all remarks and
3236	limitations of the above two methods also apply to this method.
3237
3238	<note>The machine must not be running, otherwise the operation
3239	will fail.</note>
3240
3241	<note>If the machine state is <link
3242	to="MachineState::Saved">Saved</link> prior to this operation,
3243	the saved state file will be implicitly discarded (as if <link
3244	to="IConsole::discardSavedState()"/> were called).</note>
3245
3246	<note>
3247	This method is more efficient than calling two above
3248	methods separately: it requires less IPC calls and provides
3249	a single progress object.
3250	</note>
3251
3252	</desc>
3253	<param name="progress" type="IProgress" dir="return">
3254	<desc>Progress object to track the operation completion.</desc>
3255	</param>
3256	</method>
3257
3258	<method name="registerCallback">
3259	<desc>
3260	Registers a new console callback on this instance. The methods of the
3261	callback interface will be called by this instance when the appropriate
3262	event occurs.
3263	</desc>
3264	<param name="callback" type="IConsoleCallback" dir="in"/>
3265	</method>
3266
3267	<method name="unregisterCallback">
3268	<desc>
3269	Unregisters the console callback previously registered using
3270	<link to="#registerCallback"/>.
3271	</desc>
3272	<param name="callback" type="IConsoleCallback" dir="in"/>
3273	</method>
3274
3275	</interface>
3276
3277	<!--
3278	// IHost
3279	/////////////////////////////////////////////////////////////////////////
3280	-->
3281
3282	<interface
3283	name="IHostDVDDrive" extends="$unknown"
3284	uuid="c2308775-85f3-45ab-ade5-97f02d1e61e0"
3285	>
3286	<attribute name="name" type="wstring" readonly="yes">
3287	<desc>Returns the platform device identifier.</desc>
3288	</attribute>
3289
3290	</interface>
3291
3292	<enumerator
3293	name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
3294	uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
3295	/>
3296
3297	<collection
3298	name="IHostDVDDriveCollection" type="IHostDVDDrive"
3299	enumerator="IHostDVDDriveEnumerator"
3300	uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
3301	readonly="yes"
3302	>
3303	<method name="findByName">
3304	<desc>
3305	Searches this collection for a host drive with the given name.
3306	<note>
3307	The method returns an error if the given name does not
3308	correspond to any host drive in the collection.
3309	</note>
3310	</desc>
3311	<param name="name" type="wstring" dir="in">
3312	<desc>Name of the host drive to search for</desc>
3313	</param>
3314	<param name="drive" type="IHostDVDDrive" dir="return">
3315	<desc>Found host drive object</desc>
3316	</param>
3317	</method>
3318	</collection>
3319
3320	<interface
3321	name="IHostFloppyDrive" extends="$unknown"
3322	uuid="2b2ad1ab-2ea9-4cf8-be3c-2a76677d8725"
3323	>
3324	<attribute name="name" type="wstring" readonly="yes">
3325	<desc>Returns the platform device identifier.</desc>
3326	</attribute>
3327	</interface>
3328
3329	<enumerator
3330	name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
3331	uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
3332	/>
3333
3334	<collection
3335	name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
3336	enumerator="IHostFloppyDriveEnumerator"
3337	uuid="fd84bb86-c59a-4037-a557-755ff263a460"
3338	readonly="yes"
3339	>
3340	<method name="findByName">
3341	<desc>
3342	Searches this collection for a host drive with the given name.
3343	<note>
3344	The method returns an error if the given name does not
3345	correspond to any host drive in the collection.
3346	</note>
3347	</desc>
3348	<param name="name" type="wstring" dir="in">
3349	<desc>Name of the host drive to search for</desc>
3350	</param>
3351	<param name="drive" type="IHostFloppyDrive" dir="return">
3352	<desc>Found host drive object</desc>
3353	</param>
3354	</method>
3355	</collection>
3356
3357	<if target="midl">
3358	<interface
3359	name="IHostNetworkInterface" extends="$unknown"
3360	uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
3361	>
3362	<attribute name="name" type="wstring" readonly="yes">
3363	<desc>Returns the host network interface name.</desc>
3364	</attribute>
3365
3366	<attribute name="id" type="uuid" readonly="yes">
3367	<desc>Returns the interface UUID.</desc>
3368	</attribute>
3369	</interface>
3370
3371	<enumerator
3372	name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
3373	uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
3374	/>
3375
3376	<collection
3377	name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
3378	enumerator="IHostNetworkInterfaceEnumerator"
3379	uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
3380	readonly="yes"
3381	>
3382	<method name="findByName">
3383	<desc>
3384	Searches this collection for a host network interface with the given name.
3385	<note>
3386	The method returns an error if the given name does not
3387	correspond to any host network interface in the collection.
3388	</note>
3389	</desc>
3390	<param name="name" type="wstring" dir="in">
3391	<desc>Name of the host network interface to search for.</desc>
3392	</param>
3393	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
3394	<desc>Found host network interface object.</desc>
3395	</param>
3396	</method>
3397	<method name="findById">
3398	<desc>
3399	Searches this collection for a host network interface with the given GUID.
3400	<note>
3401	The method returns an error if the given GUID does not
3402	correspond to any host network interface in the collection.
3403	</note>
3404	</desc>
3405	<param name="id" type="uuid" dir="in">
3406	<desc>GUID of the host network interface to search for.</desc>
3407	</param>
3408	<param name="networkInterface" type="IHostNetworkInterface" dir="return">
3409	<desc>Found host network interface object.</desc>
3410	</param>
3411	</method>
3412	</collection>
3413	</if>
3414
3415	<interface
3416	name="IHost" extends="$unknown"
3417	uuid="FD443EC1-000B-4F5B-9282-D72760A66916"
3418	>
3419	<attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
3420	<desc>List of DVD drives available on the host.</desc>
3421	</attribute>
3422
3423	<attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
3424	<desc>List of floppy drives available on the host.</desc>
3425	</attribute>
3426
3427	<attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
3428	<desc>
3429	List of USB devices currently attached to the host.
3430	Once a new device is physically attached to the host computer,
3431	it appears in this list and remains there until detached.
3432	</desc>
3433	</attribute>
3434
3435	<attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
3436	<desc>
3437	List of USB device filters in action.
3438	When a new device is physically attached to the host computer,
3439	filters from this list are applied to it (in order they are stored
3440	in the list). The first matched filter will determine the
3441	<link to="IHostUSBDeviceFilter::action">action</link>
3442	performed on the device.
3443
3444	Unless the device is ignored by these filters, filters of all
3445	currently running virtual machines
3446	(<link to="IUSBController::DeviceFilters"/>) are applied to it.
3447
3448	<see>IHostUSBDeviceFilter, USBDeviceState</see>
3449	</desc>
3450	</attribute>
3451
3452	<if target="midl">
3453	<attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
3454	<desc>List of host network interfaces currently defined on the host.</desc>
3455	</attribute>
3456	</if>
3457
3458	<attribute name="processorCount" type="unsigned long" readonly="yes">
3459	<desc>Number of (logical) CPUs installed in the host system.</desc>
3460	</attribute>
3461
3462	<attribute name="processorSpeed" type="unsigned long" readonly="yes">
3463	<desc>(Approximate) speed of the host CPU in Megahertz.</desc>
3464	</attribute>
3465
3466	<attribute name="processorDescription" type="wstring" readonly="yes">
3467	<desc>Description string of the host CPU.</desc>
3468	</attribute>
3469
3470	<attribute name="memorySize" type="unsigned long" readonly="yes">
3471	<desc>Amount of system memory in megabytes installed in the host system.</desc>
3472	</attribute>
3473
3474	<attribute name="memoryAvailable" type="unsigned long" readonly="yes">
3475	<desc>Available system memory in the host system.</desc>
3476	</attribute>
3477
3478	<attribute name="operatingSystem" type="wstring" readonly="yes">
3479	<desc>Name of the host system's operating system.</desc>
3480	</attribute>
3481
3482	<attribute name="OSVersion" type="wstring" readonly="yes">
3483	<desc>Host operating system's version string.</desc>
3484	</attribute>
3485
3486	<attribute name="UTCTime" type="long long" readonly="yes">
3487	<desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
3488	</attribute>
3489
3490	<if target="midl">
3491	<method name="createHostNetworkInterface">
3492	<desc>
3493	Creates a new adapter for Host Interface Networking.
3494	</desc>
3495	<param name="name" type="wstring" dir="in">
3496	<desc>
3497	Adapter name.
3498	</desc>
3499	</param>
3500	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
3501	<desc>
3502	Created host interface object.
3503	</desc>
3504	</param>
3505	<param name="progress" type="IProgress" dir="return">
3506	<desc>
3507	Progress object to track the operation completion.
3508	</desc>
3509	</param>
3510	</method>
3511	<method name="removeHostNetworkInterface">
3512	<desc>
3513	Removes the given host network interface.
3514	</desc>
3515	<param name="id" type="uuid" dir="in">
3516	<desc>
3517	Adapter GUID.
3518	</desc>
3519	</param>
3520	<param name="hostInterface" type="IHostNetworkInterface" dir="out">
3521	<desc>
3522	Removed host interface object.
3523	</desc>
3524	</param>
3525	<param name="progress" type="IProgress" dir="return">
3526	<desc>
3527	Progress object to track the operation completion.
3528	</desc>
3529	</param>
3530	</method>
3531	</if>
3532
3533	<method name="createUSBDeviceFilter">
3534	<desc>
3535	Creates a new USB device filter. All attributes except
3536	the filter name are set to <tt>null</tt> (any match),
3537	<i>active</i> is <tt>false</tt> (the filter is not active).
3538
3539	The created filter can be added to the list of filters using
3540	<link to="#insertUSBDeviceFilter()"/>.
3541
3542	<see>#USBDeviceFilters</see>
3543	</desc>
3544	<param name="name" type="wstring" dir="in">
3545	<desc>
3546	Filter name. See <link to="IHostUSBDeviceFilter::name"/>
3547	for more info.
3548	</desc>
3549	</param>
3550	<param name="filter" type="IHostUSBDeviceFilter" dir="out">
3551	<desc>Created filter object.</desc>
3552	</param>
3553	</method>
3554
3555	<method name="insertUSBDeviceFilter">
3556	<desc>
3557	Inserts the given USB device to the specified position
3558	in the list of filters.
3559
3560	Positions are numbered starting from <tt>0</tt>. If the specified
3561	position is equal to or greater than the number of elements in
3562	the list, the filter is added to the end of the collection.
3563
3564	<note>
3565	Duplicates are not allowed, so an attempt to insert a
3566	filter that is already in the list, will return an
3567	error.
3568	</note>
3569
3570	<see>#USBDeviceFilters</see>
3571	</desc>
3572	<param name="position" type="unsigned long" dir="in">
3573	<desc>Position to insert the filter to.</desc>
3574	</param>
3575	<param name="filter" type="IHostUSBDeviceFilter" dir="in">
3576	<desc>USB device filter to insert.</desc>
3577	</param>
3578	</method>
3579
3580	<method name="removeUSBDeviceFilter">
3581	<desc>
3582	Removes a USB device filter from the specified position in the
3583	list of filters.
3584
3585	Positions are numbered starting from <tt>0</tt>. Specifying a
3586	position equal to or greater than the number of elements in
3587	the list will produce an error.
3588
3589	<see>#USBDeviceFilters</see>
3590	</desc>
3591	<param name="position" type="unsigned long" dir="in">
3592	<desc>Position to remove the filter from.</desc>
3593	</param>
3594	<param name="filter" type="IHostUSBDeviceFilter" dir="out">
3595	<desc>Removed USB device filter.</desc>
3596	</param>
3597	</method>
3598
3599	</interface>
3600
3601	<!--
3602	// ISystemProperties
3603	/////////////////////////////////////////////////////////////////////////
3604	-->
3605
3606	<interface
3607	name="ISystemProperties" extends="$unknown"
3608	uuid="6dc28c62-7924-43de-8336-fa754aa531d7"
3609	>
3610	<desc>
3611	The ISystemProperties interface represents global properties
3612	of the given VirtualBox installation.
3613
3614	These properties define limits and default values for various
3615	attributes and parameters.
3616
3617	Most of the properties are read-only, but some can be changed by
3618	a user.
3619	</desc>
3620
3621	<attribute name="minGuestRAM" type="unsigned long" readonly="yes">
3622	<desc>Minium guest system memory in Megabytes.</desc>
3623	</attribute>
3624
3625	<attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
3626	<desc>Maximum guest system memory in Megabytes.</desc>
3627	</attribute>
3628
3629	<attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
3630	<desc>Minimum guest video memory in Megabytes.</desc>
3631	</attribute>
3632
3633	<attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
3634	<desc>Maximum guest video memory in Megabytes.</desc>
3635	</attribute>
3636
3637	<attribute name="maxVDISize" type="unsigned long long" readonly="yes">
3638	<desc>Maximum size of a virtual disk image in Megabytes.</desc>
3639	</attribute>
3640
3641	<attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
3642	<desc>
3643	Number of network adapters associated with every
3644	<link to="IMachine"/> instance.
3645	</desc>
3646	</attribute>
3647
3648	<attribute name="maxBootPosition" type="unsigned long" readonly="yes">
3649	<desc>
3650	Maximum device position in the boot order. This value corresponds
3651	to the total number of devices a machine can boot from, to make it
3652	possible to include all possible devices to the boot list.
3653	<see><link to="IMachine::setBootOrder()"/></see>
3654	</desc>
3655	</attribute>
3656
3657	<attribute name="defaultVDIFolder" type="wstring">
3658	<desc>
3659	Full path to the default directory used to create new or open
3660	existing virtual disk images when an image file name contains no
3661	path.
3662
3663	The initial value of this property is
3664	<tt><</tt><link to="IVirtualBox::homeFolder">
3665	VirtualBox_home</link><tt>>/VDI</tt>.
3666
3667	<note>
3668	Setting this property to <tt>null</tt> will restore the
3669	initial value.
3670	</note>
3671	<note>
3672	When settings this property, the specified path can be
3673	absolute (full path) or relative
3674	to the <link to="IVirtualBox::homeFolder">
3675	VirtualBox home directory</link>.
3676	When reading this property, a full path is
3677	always returned.
3678	</note>
3679	<note>
3680	The specified path may not exist, it will be created
3681	when necessary.
3682	</note>
3683
3684	<see>
3685	<link to="IVirtualBox::createHardDisk()"/>,
3686	<link to="IVirtualBox::openVirtualDiskImage()"/>
3687	</see>
3688	</desc>
3689	</attribute>
3690
3691	<attribute name="defaultMachineFolder" type="wstring">
3692	<desc>
3693	Full path to the default directory used to create new or open
3694	existing machines when a settings file name contains no
3695	path.
3696
3697	The initial value of this property is
3698	<tt><</tt><link to="IVirtualBox::homeFolder">
3699	VirtualBox_home</link><tt>>/Machines</tt>.
3700
3701	<note>
3702	Setting this property to <tt>null</tt> will restore the
3703	initial value.
3704	</note>
3705	<note>
3706	When settings this property, the specified path can be
3707	absolute (full path) or relative
3708	to the <link to="IVirtualBox::homeFolder">
3709	VirtualBox home directory</link>.
3710	When reading this property, a full path is
3711	always returned.
3712	</note>
3713	<note>
3714	The specified path may not exist, it will be created
3715	when necessary.
3716	</note>
3717
3718	<see>
3719	<link to="IVirtualBox::createMachine()"/>,
3720	<link to="IVirtualBox::openMachine()"/>
3721	</see>
3722	</desc>
3723	</attribute>
3724
3725	<attribute name="remoteDisplayAuthLibrary" type="wstring">
3726	<desc>
3727	Path to the library that provides authentication
3728	for VRDP clients. The library is used if authentication
3729	type is set to "external" in the VM RemoteDisplay
3730	configuration.
3731
3732	The initial value of this property is <tt>VRDPAuth</tt>.
3733	That is library called VRDPAuth in one of default library
3734	directories. A full path can be used as well.
3735
3736	<note>
3737	The library name does not include the file extension.
3738	</note>
3739	<note>
3740	Setting this property to <tt>null</tt> will restore the
3741	initial value.
3742	</note>
3743	</desc>
3744	</attribute>
3745
3746	<attribute name="HWVirtExEnabled" type="boolean">
3747	<desc>
3748	This specifies the default value for hardware virtualization
3749	extensions. If enabled, virtual machines will make use of
3750	hardware virtualization extensions such as Intel VT-x and
3751	AMD SVM by default. This value can be overridden by each VM
3752	using their <link to="IMachine::HWVirtExEnabled"/> property.
3753	</desc>
3754	</attribute>
3755
3756	</interface>
3757
3758	<!--
3759	// IGuest
3760	/////////////////////////////////////////////////////////////////////////
3761	-->
3762
3763	<interface
3764	name="IGuestOSType" extends="$unknown"
3765	uuid="da94f478-1f37-4726-b750-2235950dc2fe"
3766	>
3767	<attribute name="id" type="wstring" readonly="yes">
3768	<desc>Guest OS identifier string.</desc>
3769	</attribute>
3770
3771	<attribute name="description" type="wstring" readonly="yes">
3772	<desc>Human readable description of the guest OS.</desc>
3773	</attribute>
3774
3775	<attribute name="recommendedRAM" type="unsigned long" readonly="yes">
3776	<desc>Recommended RAM size in Megabytes.</desc>
3777	</attribute>
3778
3779	<attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
3780	<desc>Recommended video RAM size in Megabytes.</desc>
3781	</attribute>
3782
3783	<attribute name="recommendedHDD" type="unsigned long" readonly="yes">
3784	<desc>Recommended hard disk size in Megabytes.</desc>
3785	</attribute>
3786	</interface>
3787
3788
3789	<enumerator
3790	name="IGuestOSTypeEnumerator" type="IGuestOSType"
3791	uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
3792	/>
3793
3794	<collection
3795	name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
3796	uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
3797	readonly="yes"
3798	/>
3799
3800	<interface
3801	name="IGuest" extends="$unknown"
3802	uuid="FD443EC1-000E-4F5B-9282-D72760A66916"
3803	>
3804	<desc>
3805	The IGuest interface represents a guest (virtual machine's) operating
3806	system. It provides information about the Guest Additions and other
3807	guest OS properties.
3808
3809	<see>IConsole::guest</see>
3810	</desc>
3811
3812	<attribute name="OSType" type="IGuestOSType" readonly="yes">
3813	<desc>
3814	Guest OS type as reported by the Guest Additions.
3815	<note>
3816	If Guest Additions are not installed, this value will be
3817	the same as <link to="IMachine::OSType"/>.
3818	</note>
3819	</desc>
3820	</attribute>
3821
3822	<attribute name="additionsActive" type="boolean" readonly="yes">
3823	<desc>
3824	Flag whether the Guest Additions are installed and active
3825	in which case their version will be returned by the
3826	<link to="#additionsVersion"/> property.
3827	</desc>
3828	</attribute>
3829
3830	<attribute name="additionsVersion" type="wstring" readonly="yes">
3831	<desc>
3832	Version of the Guest Additions (3 decimal numbers separated
3833	by dots) or empty when the Additions are not installed. The
3834	Additions may also report a version but yet not be active as
3835	the version might be refused by VirtualBox (incompatible) or
3836	other failures occured.
3837	</desc>
3838	</attribute>
3839
3840	<method name="setCredentials">
3841	<desc>
3842	Store login credentials that can be queried by guest operating
3843	systems with Additions installed. The credentials are transient
3844	to the session and the guest may also choose to erase them. Note
3845	that the caller cannot determine whether the guest operating system
3846	has queried or made use of the credentials.
3847	</desc>
3848	<param name="userName" type="wstring" dir="in">
3849	<desc>User name string, can be empty</desc>
3850	</param>
3851	<param name="password" type="wstring" dir="in">
3852	<desc>Password string, can be empty</desc>
3853	</param>
3854	<param name="domain" type="wstring" dir="in">
3855	<desc>Domain name (guest logon scheme specific), can be emtpy</desc>
3856	</param>
3857	<param name="allowInteractiveLogon" type="boolean" dir="in">
3858	<desc>
3859	Flag whether the guest should alternatively allow the user to
3860	interactively specify different credentials. This flag might
3861	not be supported by all versions of the Additions.
3862	</desc>
3863	</param>
3864	</method>
3865
3866	</interface>
3867
3868
3869	<!--
3870	// IProgress
3871	/////////////////////////////////////////////////////////////////////////
3872	-->
3873
3874	<enumerator
3875	name="IProgressEnumerator" type="IProgress"
3876	uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
3877	/>
3878
3879	<collection
3880	name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
3881	uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
3882	readonly="yes"
3883	/>
3884
3885	<interface
3886	name="IProgress" extends="$unknown"
3887	uuid="10CC03A1-717E-429b-992D-C67B56175A51"
3888	>
3889	<desc>
3890	The IProgress interface represents a task progress object that allows
3891	to wait for the completion of some asynchronous task.
3892
3893	The task consists of one or more operations that run sequentially,
3894	one after one. There is an individual percent of completion of the
3895	current operation and the percent of completion of the task as a
3896	whole. Similarly, you can wait for the completion of a particular
3897	operation or for the completion of the whole task.
3898
3899	Every operation is identified by a number (starting from 0)
3900	and has a separate description.
3901	</desc>
3902
3903	<attribute name="id" type="uuid" readonly="yes">
3904	<desc>ID of the task.</desc>
3905	</attribute>
3906
3907	<attribute name="description" type="wstring" readonly="yes">
3908	<desc>Description of the task.</desc>
3909	</attribute>
3910
3911	<attribute name="initiator" type="$unknown" readonly="yes">
3912	<desc>Initiator of the task.</desc>
3913	</attribute>
3914
3915	<attribute name="cancelable" type="boolean" readonly="yes">
3916	<desc>Whether the task can be interrupted.</desc>
3917	</attribute>
3918
3919	<attribute name="percent" type="long" readonly="yes">
3920	<desc>
3921	Current task progress value in percent.
3922	This value depends on how many operations are already complete.
3923	</desc>
3924	</attribute>
3925
3926	<attribute name="completed" type="boolean" readonly="yes">
3927	<desc>Whether the task has been completed.</desc>
3928	</attribute>
3929
3930	<attribute name="canceled" type="boolean" readonly="yes">
3931	<desc>Whether the task has been canceled.</desc>
3932	</attribute>
3933
3934	<attribute name="resultCode" type="result" readonly="yes">
3935	<desc>
3936	Result code of the progress task.
3937	Valid only if <link to="#completed"/> is true.
3938	</desc>
3939	</attribute>
3940
3941	<attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
3942	<desc>
3943	Extended information about the unsuccessful result of the
3944	progress operation. May be NULL when no extended information
3945	is available.
3946	Valid only if <link to="#completed"/> is true and
3947	<link to="#resultCode"/> indicates a failure.
3948	</desc>
3949	</attribute>
3950
3951	<attribute name="operationCount" type="unsigned long" readonly="yes">
3952	<desc>
3953	Number of operations this task is divided into.
3954	Every task consists of at least one operation.
3955	</desc>
3956	</attribute>
3957
3958	<attribute name="operation" type="unsigned long" readonly="yes">
3959	<desc>Number of the operation being currently executed.</desc>
3960	</attribute>
3961
3962	<attribute name="operationDescription" type="wstring" readonly="yes">
3963	<desc>
3964	Description of the operation being currently executed.
3965	</desc>
3966	</attribute>
3967
3968	<attribute name="operationPercent" type="long" readonly="yes">
3969	<desc>Current operation progress value in percent.</desc>
3970	</attribute>
3971
3972	<method name="waitForCompletion">
3973	<desc>
3974	Waits until the task is done (including all operations) with a
3975	given timeout.
3976	</desc>
3977	<param name="timeout" type="long" dir="in">
3978	<desc>
3979	Timeout value in milliseconds.
3980	Specify -1 for an indefinite wait.
3981	</desc>
3982	</param>
3983	</method>
3984
3985	<method name="waitForOperationCompletion">
3986	<desc>
3987	Waits until the given operation is done with a given timeout.
3988	</desc>
3989	<param name="operation" type="unsigned long" dir="in">
3990	<desc>
3991	Number of the operation to wait for.
3992	Must be less than <link to="#operationCount"/>.
3993	</desc>
3994	</param>
3995	<param name="timeout" type="long" dir="in">
3996	<desc>
3997	Timeout value in milliseconds.
3998	Specify -1 for an indefinite wait.
3999	</desc>
4000	</param>
4001	</method>
4002
4003	<method name="cancel">
4004	<desc>
4005	Cancels the task.
4006	<note>
4007	If <link to="#cancelable"/> is <tt>false</tt>, then
4008	this method will fail.
4009	</note>
4010	</desc>
4011	</method>
4012
4013	</interface>
4014
4015
4016	<!--
4017	// ISnapshot
4018	/////////////////////////////////////////////////////////////////////////
4019	-->
4020
4021	<enumerator
4022	name="ISnapshotEnumerator" type="ISnapshot"
4023	uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
4024	/>
4025
4026	<collection
4027	name="ISnapshotCollection" type="ISnapshot"
4028	enumerator="ISnapshotEnumerator"
4029	uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
4030	readonly="yes"
4031	/>
4032
4033	<interface
4034	name="ISnapshot" extends="$unknown"
4035	uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
4036	>
4037	<desc>
4038	The ISnapshot interface represents a snapshot of the virtual
4039	machine.
4040
4041	The <i>snapshot</i> stores all the information about a virtual
4042	machine necessary to bring it to exactly the same state as it was at
4043	the time of taking the snapshot. The snapshot includes:
4044
4045	<ul>
4046	<li>all settings of the virtual machine (i.e. its hardware
4047	configuration: RAM size, attached hard disks, etc.)
4048	</li>
4049	<li>the execution state of the virtual machine (memory contents,
4050	CPU state, etc.).
4051	</li>
4052	</ul>
4053
4054	Snapshots can be <i>offline</i> (taken when the VM is powered off)
4055	or <i>online</i> (taken when the VM is running). The execution
4056	state of the offline snapshot is called a <i>zero execution state</i>
4057	(it doesn't actually contain any information about memory contents
4058	or the CPU state, assuming that all hardware is just powered off).
4059
4060	<h3>Snapshot branches</h3>
4061
4062	Snapshots can be chained. Chained snapshots form a branch where
4063	every next snapshot is based on the previous one. This chaining is
4064	mostly related to hard disk branching (see <link to="IHardDisk"/>
4065	description). This means that every time a new snapshot is created,
4066	a new differencing hard disk is implicitly created for all normal
4067	hard disks attached to the given virtual machine. This allows to
4068	fully restore hard disk contents when the machine is later reverted
4069	to a particular snapshot.
4070
4071	In the current implelemtation, multiple snapshot branches within one
4072	virtual machine are not allowed. Every machine has a signle branch,
4073	and <link to="IConsole::takeSnapshot()"/> operation adds a new
4074	snapshot to the top of that branch.
4075
4076	Existings snapshots can be discarded using
4077	<link to="IConsole::discardSnapshot()"/>.
4078
4079	<h3>Current snapshot</h3>
4080
4081	Every virtual machine has a current snapshot, identified by
4082	<link to="IMachine::currentSnapshot"/>. This snapshot is used as
4083	a base for the <i>current machine state</i> (see below), to the effect
4084	that all normal hard disks of the machine and its execution
4085	state are based on this snapshot.
4086
4087	In the current implementation, the current snapshot is always the
4088	last taken snapshot (i.e. the head snapshot on the branch) and it
4089	cannot be changed.
4090
4091	The current snapshot is <tt>null</tt> if the machine doesn't have
4092	snapshots at all; in this case the current machine state is just
4093	current settings of this machine plus its current execution state.
4094
4095	<h3>Current machine state</h3>
4096
4097	The current machine state is what represened by IMachine instances
4098	got directly from IVirtualBox using <link
4099	to="IVirtualBox::getMachine()">getMachine()</link>, <link
4100	to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as
4101	opposed to instances returned by <link to="ISnapshot::machine"/>).
4102	This state is always used when the machine is <link
4103	to="IConsole::powerUp"> powered on</link>.
4104
4105	The current machine state also includes the current execution state.
4106	If the machine is being currently executed
4107	(<link to="IMachine::state"/> is <link to="MachineState::Running"/>
4108	and above), its execution state is just what's happening now.
4109	If it is powered off (<link to="MachineState::PoweredOff"/> or
4110	<link to="MachineState::Aborted"/>), it has a zero execution state.
4111	If the machine is saved (<link to="MachineState::Saved"/>), its
4112	execution state is what saved in the execution state file
4113	(<link to="IMachine::stateFilePath"/>).
4114
4115	If the machine is in the saved state, then, next time it is powered
4116	on, its execution state will be fully restored from the saved state
4117	file and the execution will continue from the point where the state
4118	was saved.
4119
4120	Similarly to snapshots, the current machine state can be discarded
4121	using <link to="IConsole::discardCurrentState()"/>.
4122
4123	<h3>Taking and discarding snapshots</h3>
4124
4125	The table below briefly explains the meaning of every snapshot
4126	operation:
4127
4128	<table>
4129	<tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
4130
4131	<tr><td><link to="IConsole::takeSnapshot()"/></td>
4132
4133	<td>Save the current state of the virtual machine, including all
4134	settings, contents of normal hard disks and the current modifications
4135	to immutable hard disks (for online snapshots)</td>
4136
4137	<td>The current state is not changed (the machine will continue
4138	execution if it is being executed when the snapshot is
4139	taken)</td></tr>
4140
4141	<tr><td><link to="IConsole::discardSnapshot()"/></td>
4142
4143	<td>Forget the state of the virtual machine stored in the snapshot:
4144	dismiss all saved settings and delete the saved execution state (for
4145	online snapshots)</td>
4146
4147	<td>Other snapshots (including child snapshots, if any) and the
4148	current state are not directly affected</td></tr>
4149
4150	<tr><td><link to="IConsole::discardCurrentState()"/></td>
4151
4152	<td>Restore the current state of the virtual machine from the state
4153	stored in the current snapshot, including all settings and hard disk
4154	contents</td>
4155
4156	<td>The current state of the machine existed prior to this operation
4157	is lost</td></tr>
4158
4159	<tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
4160
4161	<td>Completely revert the virtual machine to the state it was in
4162	before the current snapshot has been taken</td>
4163
4164	<td>The current state, as well as the current snapshot, are
4165	lost</td></tr>
4166
4167	</table>
4168
4169	</desc>
4170
4171	<attribute name="id" type="uuid" readonly="yes">
4172	<desc>UUID of the snapshot.</desc>
4173	</attribute>
4174
4175	<attribute name="name" type="wstring">
4176	<desc>Short name of the snapshot.</desc>
4177	</attribute>
4178
4179	<attribute name="description" type="wstring">
4180	<desc>Optional description of the snapshot.</desc>
4181	</attribute>
4182
4183	<attribute name="timeStamp" type="long long" readonly="yes">
4184	<desc>
4185	Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
4186	</desc>
4187	</attribute>
4188
4189	<attribute name="online" type="boolean" readonly="yes">
4190	<desc>
4191	<tt>true</tt> if this snapshot is an online snapshot and
4192	<tt>false</tt> otherwise.
4193
4194	<note>
4195	When this attribute is <tt>true</tt>, the
4196	<link to="IMachine::stateFilePath"/> attribute of the
4197	<link to="#machine"/> object associated with this snapshot
4198	will point to the saved state file. Otherwise, it will be
4199	<tt>null</tt>.
4200	</note>
4201	</desc>
4202	</attribute>
4203
4204	<attribute name="machine" type="IMachine" readonly="yes">
4205	<desc>
4206	Virtual machine this snapshot is taken on. This object
4207	stores all settings the machine had when taking this snapshot.
4208	<note>
4209	The returned machine object is immutable, i.e. no
4210	any settings can be changed.
4211	</note>
4212	</desc>
4213	</attribute>
4214
4215	<attribute name="parent" type="ISnapshot" readonly="yes">
4216	<desc>
4217	Parent snapshot (a snapshot this one is based on).
4218	<note>
4219	It's not an error to read this attribute on a snapshot
4220	that doesn't have a parent -- a null object will be
4221	returned to indicate this.
4222	</note>
4223	</desc>
4224	</attribute>
4225
4226	<attribute name="children" type="ISnapshotCollection" readonly="yes">
4227	<desc>
4228	Child snapshots (all snapshots having this one as a parent).
4229	<note>
4230	In the current implementation, there can be only one
4231	child snapshot, or no children at all, meaning this is the
4232	last (head) snapshot.
4233	</note>
4234	</desc>
4235	</attribute>
4236
4237	</interface>
4238
4239	<!--
4240	// IHardDisk
4241	/////////////////////////////////////////////////////////////////////////
4242	-->
4243
4244	<enum
4245	name="HardDiskStorageType"
4246	uuid="48138584-ad99-479d-a36f-eb82a7663685"
4247	>
4248	<desc>
4249	Virtual hard disk storage type.
4250	<see>IHardDisk</see>
4251	</desc>
4252	<const name="VirtualDiskImage" value="0">
4253	<desc>
4254	Virtual Disk Image, VDI (a regular file in the file
4255	system of the host OS, see <link to="IVirtualDiskImage"/>)
4256	</desc>
4257	</const>
4258	<const name="ISCSIHardDisk" value="1">
4259	<desc>
4260	iSCSI Remote Disk (a disk accessed via the Internet
4261	SCSI protocol over a TCP/IP network, see
4262	<link to="IISCSIHardDisk"/>)
4263	</desc>
4264	</const>
4265	<const name="VMDKImage" value="2">
4266	<desc>
4267	WMware Virtual Machine Disk image (a regular file in the file
4268	system of the host OS, see <link to="IVMDKImage"/>)
4269	</desc>
4270	</const>
4271	</enum>
4272
4273	<enum
4274	name="HardDiskType"
4275	uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
4276	>
4277	<desc>
4278	Virtual hard disk type.
4279	<see>IHardDisk</see>
4280	</desc>
4281	<const name="NormalHardDisk" value="0">
4282	<desc>
4283	Normal hard disk (attached directly or indirectly, preserved
4284	when taking snapshots).
4285	</desc>
4286	</const>
4287	<const name="ImmutableHardDisk" value="1">
4288	<desc>
4289	Immutable hard disk (attached indirectly, changes are wiped out
4290	after powering off the virtual machine).
4291	</desc>
4292	</const>
4293	<const name="WritethroughHardDisk" value="2">
4294	<desc>
4295	Write through hard disk (attached directly, ignored when
4296	taking snapshots).
4297	</desc>
4298	</const>
4299	</enum>
4300
4301	<interface
4302	name="IHardDiskAttachment" extends="$unknown"
4303	uuid="c0ffe596-21c6-4797-8d8a-b47b66881e7a"
4304	>
4305	<attribute name="hardDisk" type="IHardDisk" readonly="yes">
4306	<desc>Harddisk object this attachment is about.</desc>
4307	</attribute>
4308
4309	<attribute name="controller" type="DiskControllerType" readonly="yes">
4310	<desc>Disk controller ID of this attachment.</desc>
4311	</attribute>
4312
4313	<attribute name="deviceNumber" type="long" readonly="yes">
4314	<desc>Device number of the attachment.</desc>
4315	</attribute>
4316
4317	</interface>
4318
4319	<enumerator
4320	name="IHardDiskAttachmentEnumerator" type="IHardDiskAttachment"
4321	uuid="9955e486-2f0b-432a-99e4-0ebbd338875e"
4322	/>
4323
4324	<collection
4325	name="IHardDiskAttachmentCollection" type="IHardDiskAttachment"
4326	enumerator="IHardDiskAttachmentEnumerator"
4327	uuid="8f727842-bb77-45d4-92de-4ec14bf613c9"
4328	readonly="yes"
4329	/>
4330
4331	<enumerator
4332	name="IHardDiskEnumerator" type="IHardDisk"
4333	uuid="b976f97b-cdb8-47e3-9860-084031cbd533"
4334	/>
4335
4336	<collection
4337	name="IHardDiskCollection" type="IHardDisk"
4338	enumerator="IHardDiskEnumerator"
4339	uuid="43EAC2BC-5C61-40fa-BC38-46DE2C7DB6BB"
4340	readonly="yes"
4341	/>
4342
4343	<interface
4344	name="IHardDisk" extends="$unknown"
4345	uuid="FD443EC1-000F-4F5B-9282-D72760A66916"
4346	>
4347	<desc>
4348	The IHardDisk interface represents a virtual hard disk drive
4349	used by virtual machines.
4350
4351	The virtual hard disk drive virtualizes the hard disk hardware and
4352	looks like a regular hard disk inside the virtual machine and
4353	the guest OS.
4354
4355	<h3>Storage Types</h3>
4356
4357	The <link to="HardDiskStorageType">storage type</link> of the
4358	virtual hard disk determines where and how it stores its data
4359	(sectors). Currently, the following storage types are supported:
4360
4361	<ul>
4362
4363	<li><i>Virtual Disk Image (VDI)</i>, a regular file in the file
4364	system of the host OS (represented by the <link
4365	to="IVirtualDiskImage"/> interface). This file has a special
4366	format optimized so that unused sectors of data occupy much less
4367	space than on a physical hard disk.</li>
4368
4369	<li><i>iSCSI Remote Disk</i>, a disk accessed via the Internet
4370	SCSI protocol over a TCP/IP network link (represented by the
4371	<link to="IISCSIHardDisk"/> interface).</li>
4372
4373	<li><i>WMware VMDK Image</i>, a regular file in the file
4374	system of the host OS (represented by the <link
4375	to="IVMDKImage"/> interface).</li>
4376
4377	</ul>
4378
4379	The storage type of the particular hard disk object is indicated by
4380	the <link to="#storageType"/> property.
4381
4382	Each storage type is represented by its own interface (as shown
4383	above), that allows to query and set properties and perform
4384	operations specific to that storage type. When an IHardDisk object
4385	reports it uses some particular storage type, it also guaranteed to
4386	support the corresponding interface which you can query. And vice
4387	versa, every object that supports a storage-specific interface, also
4388	supports IHardDisk.
4389
4390	<h3>Virtual Hard Disk Types</h3>
4391
4392	The <link to="HardDiskType">type</link> of the virtual hard disk
4393	determines how it is attached to the virtual machine when you call
4394	<link to="IMachine::attachHardDisk()"/> and what happens to it when
4395	a <link to="ISnapshot">snapshot</link> of the virtual machine is
4396	taken.
4397
4398	There are three types of virtual hard disks:
4399
4400	<ul>
4401	<li><i>Normal</i></li>
4402	<li><i>Immutable</i></li>
4403	<li><i>Writethrough</i></li>
4404	</ul>
4405
4406	The virtual disk type is indicated by the <link to="#type"/>
4407	property. Each of the above types is described in detail further
4408	down.
4409
4410	There is also a forth, "hidden" virtual disk type:
4411	<i>Differencing</i>. It is "hidden" because you cannot directly
4412	create hard disks of this type -- they are automatically created by
4413	VirtualBox when necessary.
4414
4415	<b>Differencing Hard Disks</b>
4416
4417	Unlike disks of other types (that are similar to real hard disks),
4418	the differencing hard disk does not store the full range of data
4419	sectors. Instead, it stores only a subset of sectors of some other
4420	disk that were changed since the differencing hard disk has been
4421	created. Thus, every differencing hard disk has a parent hard disk
4422	it is linked to, and represents the difference between the initial
4423	and the current hard disk state. A differencing hard disk can be
4424	linked to another differencing hard disk -- this way, differencing
4425	hard disks can form a branch of changes. More over, a given virtual
4426	hard disk can have more than one differencing hard disk linked to
4427	it.
4428
4429	A disk the differencing hard disk is linked to (or, in other
4430	words, based on) is called a <i>parent</i> hard disk and is
4431	accessible through the <link to="#parent"/> property. Similarly, all
4432	existing differencing hard disks for a given parent hard disk are
4433	called its <i>child</i> hard disks (and accessible through the <link
4434	to="#children"/> property).
4435
4436	All differencing hard disks use Virtual Disk Image files to store
4437	changed sectors. They have the <link to="#type"/> property set to
4438	Normal, but can be easily distinguished from normal hard disks using
4439	the <link to="#parent"/> property: all differencing hard disks have
4440	a parent, while all normal hard disks don't.
4441
4442	When the virtual machine makes an attempt to read a sector that is
4443	missing in a differencing hard disk, its parent is accessed to
4444	resolve the sector in question. This process continues until the
4445	sector is found, or until the root hard disk is encountered, which
4446	always contains all sectors. As a consequence,
4447
4448	<ul>
4449
4450	<li>The virtual hard disk geometry seen by the guest OS is
4451	always defined by the root hard disk.</li>
4452
4453	<li>All hard disks on a branch, up to the root, must be <link
4454	to="#accessible"/> for a given differencing hard disk in order
4455	to let it function properly when the virtual machine is
4456	running.</li>
4457
4458	</ul>
4459
4460	Differencing hard disks can be implicitly created by VirtualBox in
4461	the following cases:
4462
4463	<ul>
4464
4465	<li>When a hard disk is <i>indirectly</i> attached to the
4466	virtual machine using <link to="IMachine::attachHardDisk()"/>.
4467	In this case, all disk writes performed by the guest OS will go
4468	to the created diffferencing hard disk, as opposed to the
4469	<i>direct</i> attachment, where all changes are written to the
4470	attached hard disk itself.</li>
4471
4472	<li>When a <link to="ISnapshot">snapshot</link> of the virtual
4473	machine is taken. After that, disk writes to hard disks the
4474	differencing ones have been created for, will be directed to
4475	those differencing hard disks, to preserve the contents of the
4476	original disks.</li>
4477
4478	</ul>
4479
4480	Whether to create a differencing hard disk or not depends on the
4481	type of the hard disk attached to the virtual machine. This is
4482	explained below.
4483
4484	Note that in the current implementation, only the
4485	<link to="VirtualDiskImage"/> storage type is used to
4486	represent differencing hard disks. In other words, all
4487	differencing hard disks are <link to="IVirtualDiskImage"/>
4488	objects.
4489
4490	<b>Normal Hard Disks</b>
4491
4492	Normal hard disks are the most commonly used virtual hard disk. A
4493	normal hard disk is attached to the machine directly if it is not
4494	already attached to some other machine. Otherwise, an attempt to
4495	make an indirect attachment through a differencing hard disk will be
4496	made. This attempt will fail if the hard disk is attached to a
4497	virtual machine without snapshots (because it's impossible to create
4498	a differencing hard disk based on a hard disk that is subject to
4499	change).
4500
4501	When an indirect attachment takes place, in the simplest case, where
4502	the machine the hard disk is being attached to doesn't have
4503	snapshots, the differencing hard disk will be based on the normal
4504	hard disk being attached. Otherwise, the first (i.e. the most
4505	recent) descendant of the given normal hard disk found in the
4506	current snapshot branch (starting from the current snapshot and
4507	going up to the root) will be actually used as a base.
4508
4509	Note that when you detach an indirectly attached hard disk from the
4510	machine, the created differencing hard disk image is simply
4511	<b>deleted</b>, so <b>all changes are lost</b>. If you attach the
4512	same disk again, a clean differencing disk will be created based on
4513	the most recent child, as described above.
4514
4515	When taking a snapshot, the contents of all normal hard disks (and
4516	all differencing disks whose roots are normal hard disks) currently
4517	attached to the virtual machine is preserved by creating
4518	differencing hard disks based on them.
4519
4520	<b>Immutable Hard Disks</b>
4521
4522	Immutable hard disks can be used to provide a sort of read-only
4523	access. An immutable hard disk is always attached indirectly. The
4524	created differencing hard disk is automatically wiped out (recreated
4525	from scratch) every time you power off the virtual machine. Thus,
4526	the contents of the immutable disk remains unchanged between runs.
4527
4528	Detaching an immutable hard disk deletes the differencing disk
4529	created for it, with the same effect as in case with normal hard
4530	disks.
4531
4532	When taking a snapshot, the differencing part of the immutable
4533	hard disk is cloned (i.e. copied to a separate Virtual Disk Image
4534	file) without any changes. This is necessary to preserve the exact
4535	virtual machine state when you create an online snapshot.
4536
4537	<b>Writethrough Hard Disks</b>
4538
4539	Hard disks of this type are always attached directly. This means
4540	that every given writethrough hard disk can be attached only to one
4541	virtual machine at a time.
4542
4543	It is impossible to take a snapshot of a virtual machine with the
4544	writethrough hard disk attached, because taking a snapshot implies
4545	saving the execution state and preserving the contents of all hard
4546	disks, but writethrough hard disks cannot be preserved. Preserving
4547	hard disk contents is necessary to ensure the guest OS stored in the
4548	snapshot will get the same hard disk state when restored, which is
4549	especially important when it has open file handles or when there are
4550	cached files and directories stored in memory.
4551
4552	<h3>Creating, Opening and Registering Hard Disks</h3>
4553
4554	Non-differencing hard disks are either created from scratch using
4555	<link to="IVirtualBox::createHardDisk()"/> or opened from a VDI file
4556	using <link to="IVirtualBox::openVirtualDiskImage()"/> (only for
4557	hard disks using the VirtualDiskImage storage type). Once a hard
4558	disk is created or opened, it needs to be registered using <link
4559	to="IVirtualBox::registerHardDisk()"/> to make it available for
4560	attaching to virtual machines. See the documentation of individual
4561	interfaces for various storage types to get more information.
4562
4563	Differencing hard disks are never created explicitly and cannot
4564	be registered or unregistered; they are automatically registered
4565	upon creation and deregistered when deleted.
4566
4567	<h3>More about Indirect Hard Disk Attachments</h3>
4568
4569	Normally, when you attach a hard disk to the virtual machine, and
4570	then query the corresponding attachment using <link
4571	to="IMachine::getHardDisk()"/> or <link
4572	to="IMachine::hardDiskAttachments"/> you will get the same hard disk
4573	object, whose UUID you passed earlier to <link
4574	to="IMachine::attachHardDisk()"/>. However, when an indirect
4575	attachment takes place, calling <link to="IMachine::getHardDisk()"/>
4576	will return a differencing hard disk object, that is either based on
4577	the attached hard disk or on another differencing hard disk, the
4578	attached hard disk is eventually a root for (as described above). In
4579	both cases the returned hard disk object is the object the virtual
4580	machine actually uses to perform disk writes to.
4581
4582	Regardless of whether the attachment is direct or indirect, the
4583	<link to="#machineId"/> property of the attached disk will contain an
4584	UUID of the machine object <link to="IMachine::attachHardDisk()"/>
4585	has been called on.
4586
4587	Note that both <link to="IMachine::attachHardDisk()"/> and <link
4588	to="IMachine::detachHardDisk()"/> are <i>lazy</i> operations. In
4589	particular, this means that when an indirect attachment is made,
4590	differencing hard disks are not created until machine settings are
4591	committed using <link to="IMachine::saveSettings()"/>. Similarly,
4592	when a differencing hard disk is detached, it is not deleted until
4593	<link to="IMachine::saveSettings()"/> is called. Calling <link
4594	to="IMachine::discardSettings()"/> cancels all lazy attachments or
4595	detachments made since the last commit and effectively restores the
4596	previous set of hard disks.
4597
4598	<h3>Hard Disk Accessibility</h3>
4599
4600	The <link to="#accessible"/> attribute of the hard disk object
4601	defines the accessibility state of the respective hard disk storage
4602	(for example, the VDI file for IVirtualDiskImage objects). If the
4603	value of this attribute is <tt>false</tt> then some hard disk
4604	attributes may contain invalid or outdated values (for example, the
4605	virtual or the actual hard disk size) until a new accessibility
4606	check is done that returns <tt>true</tt> (see the attribute
4607	description for more details).
4608
4609	<note>
4610	Because of the possible slowness of the accessibility check,
4611	it is not implicitly performed upon the VirtualBox server startup
4612	(to prevent the application freeze). In partcular, this means that
4613	if you try to read hard disk properties that depend on the
4614	accessibility state without first reading the value of the
4615	<link to="#accessible"/> attribute and ensuring it's value is
4616	<tt>true</tt>, you will get wrong (zero) values.
4617	</note>
4618
4619	</desc>
4620
4621	<attribute name="id" type="uuid" readonly="yes">
4622	<desc>
4623
4624	UUID of the hard disk. For newly created hard disk objects,
4625	this value is a randomly generated UUID.
4626
4627	</desc>
4628	</attribute>
4629
4630	<attribute name="description" type="wstring">
4631	<desc>
4632
4633	Optional description of the hard disk. For a newly created hard
4634	disk, this value is <tt>null</tt>.
4635
4636	<note>For some storage types, reading this property is
4637	meaningless when <link to="#accessible"/> is <tt>false</tt>.
4638	Also, you cannot assign it a new value in this case.</note>
4639
4640	</desc>
4641	</attribute>
4642
4643	<attribute name="storageType" type="HardDiskStorageType" readonly="yes">
4644	<desc>
4645
4646	Storage type of this hard disk.
4647
4648	Storage type is defined when you open or create a new hard disk
4649	object.
4650
4651	</desc>
4652	</attribute>
4653
4654	<attribute name="location" type="wstring" readonly="yes">
4655	<desc>
4656
4657	Storage location of this hard disk. The returned string serves
4658	for informational purposes only. To access detailed information
4659	about the storage, query the appropriate storage-specific
4660	interface.
4661
4662	</desc>
4663	</attribute>
4664
4665	<attribute name="type" type="HardDiskType">
4666	<desc>
4667
4668	Type (behavior) of this hard disk. For a newly created or opened
4669	hard disk, this value is <link
4670	to="HardDiskType::NormalHardDisk"/>.
4671
4672	<note>In the current implementation, this property can be
4673	changed only on an unregistered hard disk object. This may be
4674	changed later.</note>
4675
4676	</desc>
4677	</attribute>
4678
4679	<attribute name="parent" type="IHardDisk" readonly="yes">
4680	<desc>
4681
4682	Parent of this hard disk (a hard disk this one is directly based
4683	on).
4684
4685	Only differencing hard disks have parents, so a <tt>null</tt>
4686	object is returned for a hard disk of any other type.
4687	</desc>
4688	</attribute>
4689
4690	<attribute name="children" type="IHardDiskCollection" readonly="yes">
4691	<desc>
4692
4693	Children of this hard disk (all differencing hard disks for
4694	those this one is a parent). An empty collection is returned, if
4695	this hard disk doesn't have any children.
4696
4697	</desc>
4698	</attribute>
4699
4700	<attribute name="root" type="IHardDisk" readonly="yes">
4701	<desc>
4702
4703	Root hard disk of this hard disk. If this hard disk is a
4704	differencing hard disk, its root hard disk is the first disk on
4705	the branch. For all other types of hard disks, this property
4706	returns the hard disk object itself (i.e. the same object you
4707	read this property on).
4708
4709	</desc>
4710	</attribute>
4711
4712	<attribute name="accessible" type="boolean" readonly="yes">
4713	<desc>
4714
4715	Whether the hard disk storage is currently accessible or not.
4716	The storage, for example, can be unaccessible if it doesn't exist
4717	or if it is placed on a network resource that is not available
4718	by the time this attribute is read.
4719
4720	In the current implementation, the value of this property is
4721	also <tt>false</tt> if this hard disk is attached to a running
4722	virtual machine.
4723
4724	The accessibility check is performed automatically every time
4725	this attribute is read. You should keep it in mind that this check
4726	may be slow and can block the calling thread for a long time (for
4727	example, if the network resourse where the hard disk storage is
4728	located is down).
4729
4730	The following attributes of the hard disk object are considered
4731	to be invalid when this attribute is <tt>false</tt>:
4732	<ul>
4733	<li><link to="#size"/></li>
4734	<li><link to="#actualSize"/></li>
4735	</ul>
4736	Individual hard disk storage type interfaces may define
4737	additional attributes that depend on the accessibility state.
4738	</desc>
4739	</attribute>
4740
4741	<attribute name="allAccessible" type="boolean" readonly="yes">
4742	<desc>
4743
4744	Whether the whole hard disk branch, starting from this image and
4745	going through its ancestors up to the root, is accessible or
4746	not.
4747
4748	This property makes sense only for differencing hard disks. For
4749	all other types of hard disks it returns the same value as
4750	<link to="#accessible"/>.
4751
4752	</desc>
4753	</attribute>
4754
4755	<attribute name="lastAccessError" type="wstring" readonly="yes">
4756	<desc>
4757
4758	String describing the reason of inaccessibility of this hard
4759	disk after the last call to <link to="#accessible"/> that
4760	returned <tt>false</tt>. A <tt>null</tt> value of this property
4761	means that the last accessibility check returned <tt>true</tt>.
4762
4763	</desc>
4764	</attribute>
4765
4766	<attribute name="size" type="unsigned long long" readonly="yes">
4767	<desc>
4768
4769	Logical size of this hard disk (in megabytes), as reported to the
4770	guest OS running inside the vurtual machine this disk is
4771	attached to. The logical size is defined when the hard disk is
4772	created.
4773
4774	<note>Reading this property on a differencing hard disk will
4775	return the size of its root hard disk.</note>
4776
4777	<note>Reading this property is meaningless when
4778	<link to="#accessible"/> is <tt>false</tt></note>
4779
4780	</desc>
4781	</attribute>
4782
4783	<attribute name="actualSize" type="unsigned long long" readonly="yes">
4784	<desc>
4785
4786	Physical size of the storage used to store hard disk data (in
4787	bytes). This size is usually less than the logical size of the
4788	hard disk, depending on the storage type and on the size
4789	optimization method used for that storage.
4790
4791	<note>Reading this property is meaningless when
4792	<link to="#accessible"/> is <tt>false</tt></note>
4793
4794	</desc>
4795	</attribute>
4796
4797	<attribute name="machineId" type="uuid" readonly="yes">
4798	<desc>
4799
4800	UUID of the machine this hard disk is attached to (or a
4801	<tt>null</tt> UUID if it is not attached).
4802
4803	<note>Immutable hard disks are never attached directly, so this
4804	attribute is always <tt>null</tt> in this case.</note>
4805
4806	</desc>
4807	</attribute>
4808
4809	<attribute name="snapshotId" type="uuid" readonly="yes">
4810	<desc>
4811
4812	UUID of the <link to="ISnapshot">snapshot</link> this hard disk
4813	is associated with (or <tt>null</tt> UUID if it is not
4814	associated with any snapshot).
4815
4816	<note>This attribute is always <tt>null</tt> if <link
4817	to="#machineId"/> is <tt>null</tt>.</note>
4818
4819	<note>Writethrough hard disks are always attached directly and
4820	cannot be involved when taking snapshots, so this attribute is
4821	meaningless and therefore always <tt>null</tt>.</note>
4822
4823	</desc>
4824	</attribute>
4825
4826	<method name="cloneToImage">
4827
4828	<desc>
4829
4830	Starts creating a clone of this hard disk. The cloned hard disk
4831	will use the specified Virtual Disk Image file as a storage and
4832	will contain exactly the same sector data as the hard disk being
4833	cloned, except that a new UUID for the clone will be randomly
4834	generated.
4835
4836	The specified image file path can be absolute (full path) or
4837	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
4838	home directory</link>. If only a file name without any path is
4839	given, the <link to="ISystemProperties::defaultVDIFolder">
4840	default VDI folder</link> will be used as a path to the image
4841	file.
4842
4843	It is an error to use the object returned in the @a image
4844	parameter until the returned @a progress object reports success.
4845
4846	<note>In the current implementation, only non-differencing hard
4847	disks can be cloned.</note>
4848
4849	</desc>
4850
4851	<param name="filePath" type="wstring" dir="in">
4852	<desc>Path to a file where to store the cloned hard disk.</desc>
4853	</param>
4854	<param name="image" type="IVirtualDiskImage" dir="out">
4855	<desc>Cloned hard disk object.</desc>
4856	</param>
4857	<param name="progress" type="IProgress" dir="return">
4858	<desc>Progress object to track the operation completion.</desc>
4859	</param>
4860
4861	</method>
4862
4863	</interface>
4864
4865	<!--
4866	// IVirtualDiskImage
4867	/////////////////////////////////////////////////////////////////////////
4868	-->
4869
4870	<interface
4871	name="IVirtualDiskImage" extends="$unknown"
4872	uuid="a8265b5a-0d20-4a46-a02f-65693a4e8239"
4873	>
4874
4875	<desc>
4876
4877	The IVirtualDiskImage interface represents <link
4878	to="IHardDisk">virtual hard disks</link> that use virtual disk image
4879	files to store hard disk data.
4880
4881	Hard disks using virtual disk images can be either opened using
4882	<link to="IVirtualBox::openVirtualDiskImage()"/> or created from
4883	scratch using <link to="IVirtualBox::createHardDisk()"/>.
4884
4885	Objects that support this interface also support the <link
4886	to="IHardDisk"/> interface.
4887
4888	When a new hard disk object is created from scatch, an image file
4889	for it is not automatically created. To do it, you need to specify a
4890	valid <link to="#filePath">file path</link>, and call <link
4891	to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
4892	When it is done, the hard disk object can be registered by calling
4893	<link to="IVirtualBox::registerHardDisk()"/> and then
4894	<link to="IMachine::attachHardDisk()">attached</link> to
4895	virtual machines.
4896
4897	The <link to="IHardDisk::description">description</link> of the
4898	Virtual Disk Image is stored in the image file. For this reason,
4899	changing the value of this property requires the hard disk to be
4900	<link to="IHardDisk::accessible">accessible</link>. The description
4901	of a registered hard disk can be changed only if a virtual machine
4902	using it is not running.
4903
4904	</desc>
4905
4906	<attribute name="filePath" type="wstring">
4907	<desc>
4908
4909	Full file name of the virtual disk image of this hard disk. For
4910	newly created hard disk objects, this value is <tt>null</tt>.
4911
4912	When assigning a new path, it can be absolute (full path) or
4913	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
4914	home directory</link>. If only a file name without any path is
4915	given, the <link to="ISystemProperties::defaultVDIFolder">
4916	default VDI folder</link> will be used as a path to the image
4917	file.
4918
4919	When reading this propery, a full path is always returned.
4920
4921	<note>This property cannot be changed when <link to="#created"/>
4922	returns <tt>true</tt>. In this case, the specified file name can
4923	be absolute (full path) or relative to the <link
4924	to="IVirtualBox::homeFolder"> VirtualBox home directory</link>.
4925	If only a file name without any path is given, the <link
4926	to="ISystemProperties::defaultVDIFolder"> default VDI
4927	folder</link> will be used as a path to the image file.</note>
4928
4929	</desc>
4930	</attribute>
4931
4932	<attribute name="created" type="boolean" readonly="yes">
4933	<desc>
4934
4935	Whether the virual disk image is created or not. For newly
4936	created hard disk objects or after a successful invocation of
4937	<link to="#deleteImage()"/>, this value is <tt>false</tt> until
4938	<link to="#createFixedImage()"/> or <link
4939	to="#createDynamicImage()"/> is called.
4940
4941	</desc>
4942	</attribute>
4943
4944	<method name="createDynamicImage">
4945
4946	<desc>
4947
4948	Starts creating a dymically expanding hard disk image in the
4949	background. The previous image associated with this object, if
4950	any, must be deleted using <link to="#deleteImage"/>, otherwise
4951	the operation will fail.
4952
4953	<note>After the returned progress object reports that the
4954	operation is complete, this hard disk object can be
4955	<link to="IVirtualBox::registerHardDisk()">registered</link>
4956	within this VirtualBox installation.</note>
4957
4958	</desc>
4959
4960	<param name="size" type="unsigned long long" dir="in">
4961	<desc>Maximum logical size of the hard disk in megabytes.</desc>
4962	</param>
4963	<param name="progress" type="IProgress" dir="return">
4964	<desc>Progress object to track the operation completion.</desc>
4965	</param>
4966
4967	</method>
4968
4969	<method name="createFixedImage">
4970	<desc>
4971
4972	Starts creating a fixed-size hard disk image in the background.
4973	The previous image, if any, must be deleted using <link
4974	to="#deleteImage"/>, otherwise the operation will fail.
4975
4976	<note>After the returned progress object reports that the
4977	operation is complete, this hard disk object can be
4978	<link to="IVirtualBox::registerHardDisk()">registered</link>
4979	within this VirtualBox installation.</note>
4980
4981	</desc>
4982
4983	<param name="size" type="unsigned long long" dir="in">
4984	<desc>Logical size of the hard disk in megabytes.</desc>
4985	</param>
4986	<param name="progress" type="IProgress" dir="return">
4987	<desc>Progress object to track the operation completion.</desc>
4988	</param>
4989
4990	</method>
4991
4992	<method name="deleteImage">
4993	<desc>
4994
4995	Deletes the existing hard disk image. The hard disk must not be
4996	registered within this VirtualBox installation, otherwise the
4997	operation will fail.
4998
4999	<note>After this operation succeeds, it will be impossible to
5000	register the hard disk until the image file is created
5001	again.</note>
5002
5003	<note>This operation is valid only for non-differencing hard
5004	disks, after they are unregistered using <link
5005	to="IVirtualBox::unregisterHardDisk()"/>.</note>
5006
5007	</desc>
5008	</method>
5009
5010	</interface>
5011
5012	<!--
5013	// IISCSIHardDisk
5014	/////////////////////////////////////////////////////////////////////////
5015	-->
5016
5017	<interface
5018	name="IISCSIHardDisk" extends="$unknown"
5019	uuid="003f6ca9-3257-4ef9-99c9-c66ce44576cb"
5020	>
5021
5022	<desc>
5023
5024	The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
5025	hard disks</link> that use the Internet SCSI (iSCSI) protocol to
5026	store hard disk data on remote machines.
5027
5028	iSCSI hard disks can be created using <link
5029	to="IVirtualBox::createHardDisk()"/>. When a new hard disk object is
5030	created, all its properties are uninitialized. After you assign some
5031	meaningful values to them, the hard disk object can be registered by
5032	calling <link to="IVirtualBox::registerHardDisk()"/> and then <link
5033	to="IMachine::attachHardDisk()">attached</link> to virtual machines.
5034
5035	Objects that support this interface also support the <link
5036	to="IHardDisk"/> interface.
5037
5038	The <link to="IHardDisk::description">description</link>
5039	of the iSCSI hard disk is stored in the VirtualBox
5040	configuration file, so it can be changed (at appropriate
5041	times) even when
5042	<link to="IHardDisk::accessible">accessible</link> returns
5043	<tt>false</tt>. However, the hard disk must not be
5044	attached to a running virtual machine.
5045
5046	<note>In the current imlementation, the type of all iSCSI hard disks
5047	is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
5048	and cannot be changed.</note>
5049
5050	</desc>
5051
5052	<attribute name="server" type="wstring">
5053	<desc>
5054
5055	iSCSI Server name (either a host name or an IP address). For
5056	newly created hard disk objects, this value is <tt>null</tt>.
5057
5058	</desc>
5059	</attribute>
5060
5061	<attribute name="port" type="unsigned short">
5062	<desc>
5063
5064	iSCSI Server port. For newly created hard disk objects, this
5065	value is <tt>0</tt>, which means the default port.
5066
5067	</desc>
5068	</attribute>
5069
5070	<attribute name="target" type="wstring">
5071	<desc>
5072
5073	iSCSI target name. For newly created hard disk objects, this
5074	value is <tt>null</tt>.
5075
5076	</desc>
5077	</attribute>
5078
5079	<attribute name="lun" type="unsigned long long">
5080	<desc>
5081
5082	Logical unit number for this iSCSI disk. For newly created hard
5083	disk objects, this value is <tt>0</tt>.
5084
5085	</desc>
5086	</attribute>
5087
5088	<attribute name="userName" type="wstring">
5089	<desc>
5090
5091	User name for accessing this iSCSI disk. For newly created hard
5092	disk objects, this value is <tt>null</tt>.
5093
5094	</desc>
5095	</attribute>
5096
5097	<attribute name="password" type="wstring">
5098	<desc>
5099
5100	User password for accessing this iSCSI disk. For newly created
5101	hard disk objects, this value is <tt>null</tt>.
5102
5103	</desc>
5104	</attribute>
5105
5106	</interface>
5107
5108	<!--
5109	// IVMDKImage
5110	/////////////////////////////////////////////////////////////////////////
5111	-->
5112
5113	<interface
5114	name="IVMDKImage" extends="$unknown"
5115	uuid="178398f5-8559-4fee-979e-420af5b53eef"
5116	>
5117	<desc>
5118
5119	The IVMDKImage interface represents <link
5120	to="IHardDisk">virtual hard disks</link> that use
5121	WMware Virtual Machine Disk image files to store hard disk data.
5122
5123	Hard disks using VMDK images can be either opened using
5124	<link to="IVirtualBox::openHardDisk()"/> or created from
5125	scratch using <link to="IVirtualBox::createHardDisk()"/>.
5126
5127	Objects that support this interface also support the <link
5128	to="IHardDisk"/> interface.
5129
5130	When a new hard disk object is created from scatch, an image file
5131	for it is not automatically created. To do it, you need to specify a
5132	valid <link to="#filePath">file path</link>, and call <link
5133	to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
5134	When it is done, the hard disk object can be registered by calling
5135	<link to="IVirtualBox::registerHardDisk()"/> and then
5136	<link to="IMachine::attachHardDisk()">attached</link> to
5137	virtual machines.
5138
5139	The <link to="IHardDisk::description">description</link>
5140	of the VMDK hard disk is stored in the VirtualBox
5141	configuration file, so it can be changed (at appropriate
5142	times) even when
5143	<link to="IHardDisk::accessible">accessible</link> returns
5144	<tt>false</tt>. However, the hard disk must not be
5145	attached to a running virtual machine.
5146
5147	<note>In the current imlementation, the type of all VMDK hard disks
5148	is <link to="HardDiskType::WritethroughHardDisk">Writethrough</link>
5149	and cannot be changed.</note>
5150
5151	</desc>
5152
5153	<attribute name="filePath" type="wstring">
5154	<desc>
5155
5156	Full file name of the VMDK image of this hard disk. For
5157	newly created hard disk objects, this value is <tt>null</tt>.
5158
5159	When assigning a new path, it can be absolute (full path) or
5160	relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
5161	home directory</link>. If only a file name without any path is
5162	given, the <link to="ISystemProperties::defaultVDIFolder">
5163	default VDI folder</link> will be used as a path to the image
5164	file.
5165
5166	When reading this propery, a full path is always returned.
5167
5168	<note>This property cannot be changed when <link to="#created"/>
5169	returns <tt>true</tt>. In this case, the specified file name can
5170	be absolute (full path) or relative to the <link
5171	to="IVirtualBox::homeFolder"> VirtualBox home directory</link>.
5172	If only a file name without any path is given, the <link
5173	to="ISystemProperties::defaultVDIFolder"> default VDI
5174	folder</link> will be used as a path to the image file.</note>
5175
5176	</desc>
5177	</attribute>
5178
5179	<attribute name="created" type="boolean" readonly="yes">
5180	<desc>
5181
5182	Whether the virual disk image is created or not. For newly
5183	created hard disk objects or after a successful invocation of
5184	<link to="#deleteImage()"/>, this value is <tt>false</tt> until
5185	<link to="#createFixedImage()"/> or <link
5186	to="#createDynamicImage()"/> is called.
5187
5188	</desc>
5189	</attribute>
5190
5191	<method name="createDynamicImage">
5192
5193	<desc>
5194
5195	Starts creating a dymically expanding hard disk image in the
5196	background. The previous image associated with this object, if
5197	any, must be deleted using <link to="#deleteImage"/>, otherwise
5198	the operation will fail.
5199
5200	<note>After the returned progress object reports that the
5201	operation is complete, this hard disk object can be
5202	<link to="IVirtualBox::registerHardDisk()">registered</link>
5203	within this VirtualBox installation.</note>
5204
5205	</desc>
5206
5207	<param name="size" type="unsigned long long" dir="in">
5208	<desc>Maximum logical size of the hard disk in megabytes.</desc>
5209	</param>
5210	<param name="progress" type="IProgress" dir="return">
5211	<desc>Progress object to track the operation completion.</desc>
5212	</param>
5213
5214	</method>
5215
5216	<method name="createFixedImage">
5217	<desc>
5218
5219	Starts creating a fixed-size hard disk image in the background.
5220	The previous image, if any, must be deleted using <link
5221	to="#deleteImage"/>, otherwise the operation will fail.
5222
5223	<note>After the returned progress object reports that the
5224	operation is complete, this hard disk object can be
5225	<link to="IVirtualBox::registerHardDisk()">registered</link>
5226	within this VirtualBox installation.</note>
5227
5228	</desc>
5229
5230	<param name="size" type="unsigned long long" dir="in">
5231	<desc>Logical size of the hard disk in megabytes.</desc>
5232	</param>
5233	<param name="progress" type="IProgress" dir="return">
5234	<desc>Progress object to track the operation completion.</desc>
5235	</param>
5236
5237	</method>
5238
5239	<method name="deleteImage">
5240	<desc>
5241
5242	Deletes the existing hard disk image. The hard disk must not be
5243	registered within this VirtualBox installation, otherwise the
5244	operation will fail.
5245
5246	<note>After this operation succeeds, it will be impossible to
5247	register the hard disk until the image file is created
5248	again.</note>
5249
5250	<note>This operation is valid only for non-differencing hard
5251	disks, after they are unregistered using <link
5252	to="IVirtualBox::unregisterHardDisk()"/>.</note>
5253
5254	</desc>
5255	</method>
5256
5257	</interface>
5258
5259	<!--
5260	// IDVDImage
5261	/////////////////////////////////////////////////////////////////////////
5262	-->
5263
5264	<enumerator
5265	name="IDVDImageEnumerator" type="IDVDImage"
5266	uuid="9BE77C8D-E1BE-4bf2-A67B-B4DD3D2B0F28"
5267	/>
5268
5269	<collection
5270	name="IDVDImageCollection" type="IDVDImage"
5271	enumerator="IDVDImageEnumerator"
5272	uuid="AE7053FA-ADD2-4ea4-AFCF-24D5F8DDED64"
5273	readonly="yes"
5274	>
5275	<method name="findByPath">
5276	<desc>
5277	Searches this collection for a DVD image with the given disk path.
5278	<note>
5279	The method returns an error if the given name does not
5280	correspond to any DVD image in the collection.
5281	</note>
5282	</desc>
5283	<param name="path" type="wstring" dir="in">
5284	<desc>Name of the DVD image's file system location.</desc>
5285	</param>
5286	<param name="image" type="IDVDImage" dir="return">
5287	<desc>Found DVD image object</desc>
5288	</param>
5289	</method>
5290	</collection>
5291
5292	<interface
5293	name="IDVDImage" extends="$unknown"
5294	uuid="140FFF03-E479-4194-8562-ABC4F8171009"
5295	>
5296	<desc>
5297
5298	The IDVDImage interface represents a file containing the image
5299	of the DVD or CD disk.
5300
5301	<h3>Image Accessibility</h3>
5302
5303	The <link to="#accessible"/> attribute of the image object
5304	defines the accessibility state of the image file. If the
5305	value of this attribute is <tt>false</tt> then some image
5306	attributes may contain invalid or outdated values (for example, the
5307	the image file size) until a new accessibility
5308	check is done that returns <tt>true</tt>.
5309
5310	<note>
5311	Because of the possible slowness of the accessibility check,
5312	it is not implicitly performed upon the VirtualBox server startup
5313	(to prevent the application freeze). In partcular, this means that
5314	if you try to read image properties that depend on the
5315	accessibility state without first reading the value of the
5316	<link to="#accessible"/> attribute and ensuring it's value is
5317	<tt>true</tt>, you will get wrong (zero) values.
5318	</note>
5319
5320	</desc>
5321	<attribute name="id" type="uuid" readonly="yes">
5322	<desc>UUID of the CD/DVD image.</desc>
5323	</attribute>
5324
5325	<attribute name="filePath" type="wstring" readonly="yes">
5326	<desc>Full file name of the CD/DVD image.</desc>
5327	</attribute>
5328
5329	<attribute name="accessible" type="boolean" readonly="yes">
5330	<desc>
5331
5332	Whether the CD/DVD image is currently accessible or not.
5333	The image, for example, can be unaccessible if it is placed
5334	on a network share that is not available by the time
5335	this property is read.
5336
5337	The accessibility check is performed automatically every time
5338	this attribute is read. You should keep it in mind that this check
5339	may be slow and can block the calling thread for a long time (for
5340	example, if the network share where the image is located is down).
5341
5342	The following attributes of the image object are considered
5343	to be invalid when this attribute is <tt>false</tt>:
5344	<ul>
5345	<li><link to="#size"/></li>
5346	</ul>
5347
5348	</desc>
5349	</attribute>
5350
5351	<attribute name="size" type="unsigned long long" readonly="yes">
5352	<desc>Size of the ISO image in bytes.</desc>
5353	</attribute>
5354
5355	</interface>
5356
5357
5358	<!--
5359	// IDVDDrive
5360	/////////////////////////////////////////////////////////////////////////
5361	-->
5362
5363	<enum
5364	name="DriveState"
5365	uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
5366	>
5367	<const name="InvalidDriveState" value="0"/>
5368	<const name="NotMounted" value="1"/>
5369	<const name="ImageMounted" value="2"/>
5370	<const name="HostDriveCaptured" value="3"/>
5371	</enum>
5372
5373	<interface
5374	name="IDVDDrive" extends="$unknown"
5375	uuid="d9bd101a-8079-4fb9-bad1-31bf32482b75"
5376	>
5377	<attribute name="state" type="DriveState" readonly="yes">
5378	<desc>Current drive state.</desc>
5379	</attribute>
5380
5381	<attribute name="passthrough" type="boolean">
5382	<desc>
5383	When a host drive is mounted and passthrough is enabled
5384	the guest will be able to directly send SCSI commands to
5385	the host drive. This enables the guest to use CD/DVD writers
5386	but is potentially dangerous.
5387	</desc>
5388	</attribute>
5389
5390	<method name="mountImage">
5391	<desc>Mounts the specified image.</desc>
5392	<param name="imageId" type="uuid" dir="in"/>
5393	</method>
5394
5395	<method name="captureHostDrive">
5396	<desc>Captures the specified host drive.</desc>
5397	<param name="drive" type="IHostDVDDrive" dir="in"/>
5398	</method>
5399
5400	<method name="unmount">
5401	<desc>Unmounts the currently mounted image/device.</desc>
5402	</method>
5403
5404	<method name="getImage">
5405	<desc>Gets the currently mounted image ID.</desc>
5406	<param name="image" type="IDVDImage" dir="return"/>
5407	</method>
5408
5409	<method name="getHostDrive">
5410	<desc>Gets the currently mounted image ID.</desc>
5411	<param name="drive" type="IHostDVDDrive" dir="return"/>
5412	</method>
5413
5414	</interface>
5415
5416	<!--
5417	// IFloppyImage
5418	/////////////////////////////////////////////////////////////////////////
5419	-->
5420
5421	<enumerator
5422	name="IFloppyImageEnumerator" type="IFloppyImage"
5423	uuid="902C4089-76B7-41f1-91E8-49A261A28A2C"
5424	/>
5425
5426	<collection
5427	name="IFloppyImageCollection" type="IFloppyImage"
5428	enumerator="IFloppyImageEnumerator"
5429	uuid="327A8928-8572-446e-AD9A-18FE30E81F3F"
5430	readonly="yes">
5431	<method name="findByPath">
5432	<desc>
5433	Searches this collection for a floppy image with the given disk path.
5434	<note>
5435	The method returns an error if the given name does not
5436	correspond to any floppy image in the collection.
5437	</note>
5438	</desc>
5439	<param name="path" type="wstring" dir="in">
5440	<desc>Name of the floppy image's file system location.</desc>
5441	</param>
5442	<param name="image" type="IFloppyImage" dir="return">
5443	<desc>Found Floppy image object</desc>
5444	</param>
5445	</method>
5446	</collection>
5447
5448	<interface
5449	name="IFloppyImage" extends="$unknown"
5450	uuid="CC696755-EA98-4ffe-9DC5-C003047034AB"
5451	>
5452	<desc>
5453
5454	The IFloppyImage interface represents a file containing the image
5455	of a floppy disk.
5456
5457	<h3>Image Accessibility</h3>
5458
5459	The <link to="#accessible"/> attribute of the image object
5460	defines the accessibility state of the image file. If the
5461	value of this attribute is <tt>false</tt> then some image
5462	attributes may contain invalid or outdated values (for example, the
5463	the image file size) until a new accessibility
5464	check is done that returns <tt>true</tt>.
5465
5466	<note>
5467	Because of the possible slowness of the accessibility check,
5468	it is not implicitly performed upon the VirtualBox server startup
5469	(to prevent the application freeze). In partcular, this means that
5470	if you try to read image properties that depend on the
5471	accessibility state without first reading the value of the
5472	<link to="#accessible"/> attribute and ensuring it's value is
5473	<tt>true</tt>, you will get wrong (zero) values.
5474	</note>
5475
5476	</desc>
5477	<attribute name="id" type="uuid" readonly="yes">
5478	<desc>UUID of the floppy image.</desc>
5479	</attribute>
5480
5481	<attribute name="filePath" type="wstring" readonly="yes">
5482	<desc>Full file name of the floppy image.</desc>
5483	</attribute>
5484
5485	<attribute name="accessible" type="boolean" readonly="yes">
5486	<desc>
5487
5488	Whether the floppy image is currently accessible or not.
5489	The image, for example, can be unaccessible if it is placed
5490	on a network share that is not available by the time
5491	this property is read.
5492
5493	The accessibility check is performed automatically every time
5494	this attribute is read. You should keep it in mind that this check
5495	may be slow and can block the calling thread for a long time (for
5496	example, if the network share where the image is located is down).
5497
5498	The following attributes of the image object are considered
5499	to be invalid when this attribute is <tt>false</tt>:
5500	<ul>
5501	<li><link to="#size"/></li>
5502	</ul>
5503
5504	</desc>
5505	</attribute>
5506
5507	<attribute name="size" type="unsigned long" readonly="yes">
5508	<desc>Size of the floppy image in bytes.</desc>
5509	</attribute>
5510
5511	</interface>
5512
5513
5514	<!--
5515	// IFloppyDrive
5516	/////////////////////////////////////////////////////////////////////////
5517	-->
5518
5519	<interface
5520	name="IFloppyDrive" extends="$unknown"
5521	uuid="E9318F71-78D2-4b00-863C-B7CB0030A2D9"
5522	>
5523	<attribute name="enabled" type="boolean">
5524	<desc>
5525	Flag whether the floppy drive is enabled. If it is disabled,
5526	the floppy drive will not be reported to the guest.
5527	</desc>
5528	</attribute>
5529
5530	<attribute name="state" type="DriveState" readonly="yes">
5531	<desc>Current drive state.</desc>
5532	</attribute>
5533
5534	<method name="mountImage">
5535	<desc>Mounts the specified image.</desc>
5536	<param name="imageId" type="uuid" dir="in"/>
5537	</method>
5538
5539	<method name="captureHostDrive">
5540	<desc>Captures the specified host drive.</desc>
5541	<param name="drive" type="IHostFloppyDrive" dir="in"/>
5542	</method>
5543
5544	<method name="unmount">
5545	<desc>Unmounts the currently mounted image/device.</desc>
5546	</method>
5547
5548	<method name="getImage">
5549	<desc>Gets the currently mounted image ID.</desc>
5550	<param name="image" type="IFloppyImage" dir="return"/>
5551	</method>
5552
5553	<method name="getHostDrive">
5554	<desc>Gets the currently mounted image ID.</desc>
5555	<param name="drive" type="IHostFloppyDrive" dir="return"/>
5556	</method>
5557
5558	</interface>
5559
5560
5561	<!--
5562	// IKeyboard
5563	/////////////////////////////////////////////////////////////////////////
5564	-->
5565
5566	<interface
5567	name="IKeyboard" extends="$unknown"
5568	uuid="FD443EC1-000A-4F5B-9282-D72760A66916"
5569	>
5570	<method name="putScancode">
5571	<desc>Sends a scancode to the keyboard.</desc>
5572	<param name="scancode" type="long" dir="in"/>
5573	</method>
5574
5575	<method name="putScancodes">
5576	<desc>Sends an array of scancode to the keyboard.</desc>
5577	<param name="scancodes" type="long" dir="in" array="count"/>
5578	<param name="count" type="unsigned long" dir="in"/>
5579	<param name="codesStored" type="unsigned long" dir="return"/>
5580	</method>
5581
5582	<method name="putCAD">
5583	<desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
5584	</method>
5585
5586	</interface>
5587
5588
5589	<!--
5590	// IMouse
5591	/////////////////////////////////////////////////////////////////////////
5592	-->
5593
5594	<enum
5595	name="MouseButtonState"
5596	uuid="03131722-2EC5-4173-9794-0DACA46673EF"
5597	>
5598	<const name="LeftButton" value="0x01"/>
5599	<const name="RightButton" value="0x02"/>
5600	<const name="MiddleButton" value="0x04"/>
5601	<const name="WheelUp" value="0x08"/>
5602	<const name="WheelDown" value="0x10"/>
5603	<const name="MouseStateMask" value="0x1F"/>
5604	</enum>
5605
5606	<interface
5607	name="IMouse" extends="$unknown"
5608	uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
5609	>
5610	<desc>
5611	The IMouse interface represents a virtual mouse device.
5612	</desc>
5613
5614	<attribute name="absoluteSupported" type="boolean" readonly="yes">
5615	<desc>
5616	Whether the guest OS supports absolute mouse pointer positioning
5617	or not.
5618	<note>
5619	VirtualBox Guest Tools need to be installed to the guest OS
5620	in order to enable absolute mouse positioning support.
5621	You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
5622	callback to be instantly informed about changes of this attribute
5623	during virtual machine execution.
5624	</note>
5625	<see><link to="#putMouseEventAbsolute"/></see>
5626	</desc>
5627	</attribute>
5628
5629	<method name="putMouseEvent">
5630	<desc>
5631	Initiates a mouse event using relative pointer movements
5632	along x and y axis.
5633	</desc>
5634
5635	<param name="dx" type="long" dir="in">
5636	<desc>
5637	Amout of pixels the mouse should move to the right.
5638	Negative values move the mouse to the left.
5639	</desc>
5640	</param>
5641	<param name="dy" type="long" dir="in">
5642	<desc>
5643	Amout of pixels the mouse should move downwards.
5644	Negative values move the mouse upwards.
5645	</desc>
5646	</param>
5647	<param name="dz" type="long" dir="in">
5648	<desc>
5649	Amount of mouse wheel moves.
5650	Positive values describe clockwize wheel rotations,
5651	negative values describe counterclockwise rotations.
5652	</desc>
5653	</param>
5654	<param name="buttonState" type="long" dir="in">
5655	<desc>
5656	The current state of mouse buttons. Every bit represents
5657	a mouse button as follows:
5658	<table>
5659	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
5660	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
5661	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
5662	</table>
5663	A value of <tt>1</tt> means the corresponding button is pressed.
5664	otherwise it is released.
5665	</desc>
5666	</param>
5667	</method>
5668
5669	<method name="putMouseEventAbsolute">
5670	<desc>
5671	Positions the mouse pointer using absolute x and y coordinates.
5672	These coordinates are expressed in pixels and
5673	start from <tt>[1,1]</tt> which corresponds to the top left
5674	corner of the virtual display.
5675
5676	<note>
5677	This method will have effect only if absolute mouse
5678	positioning is supported by the guest OS.
5679	</note>
5680
5681	<see><link to="#absoluteSupported"/></see>
5682	</desc>
5683
5684	<param name="x" type="long" dir="in">
5685	<desc>
5686	X coordinate of the pointer in pixels, starting from <tt>1</tt>.
5687	</desc>
5688	</param>
5689	<param name="y" type="long" dir="in">
5690	<desc>
5691	Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
5692	</desc>
5693	</param>
5694	<param name="dz" type="long" dir="in">
5695	<desc>
5696	Amout of mouse wheel moves.
5697	Positive values describe clockwize wheel rotations,
5698	negative values describe counterclockwise rotations.
5699	</desc>
5700	</param>
5701	<param name="buttonState" type="long" dir="in">
5702	<desc>
5703	The current state of mouse buttons. Every bit represents
5704	a mouse button as follows:
5705	<table>
5706	<tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
5707	<tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
5708	<tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
5709	</table>
5710	A value of <tt>1</tt> means the corresponding button is pressed.
5711	otherwise it is released.
5712	</desc>
5713	</param>
5714	</method>
5715
5716	</interface>
5717
5718
5719	<!--
5720	// IDisplay
5721	/////////////////////////////////////////////////////////////////////////
5722	-->
5723
5724	<enum
5725	name="FramebufferAccelerationOperation"
5726	uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
5727	>
5728	<const name="SolidFillAcceleration" value="1"/>
5729	<const name="ScreenCopyAcceleration" value="2"/>
5730	</enum>
5731
5732	<enum
5733	name="FramebufferPixelFormat"
5734	uuid="d15f9c8b-bd7e-4003-981c-4ca14f49f2c3"
5735	>
5736	<const name="PixelFormatDefault" value="0"/>
5737	<const name="PixelFormatRGB16" value="1"/>
5738	<const name="PixelFormatRGB24" value="2"/>
5739	<const name="PixelFormatRGB32" value="3"/>
5740	</enum>
5741
5742	<interface
5743	name="IFramebuffer" extends="$unknown"
5744	uuid="4481F27F-5C79-48d9-86C1-A2EC6747034D"
5745	>
5746	<attribute name="address" type="octet" mod="ptr" readonly="yes">
5747	<desc>Address of the start byte of the framebuffer.</desc>
5748	</attribute>
5749
5750	<attribute name="width" type="unsigned long" readonly="yes">
5751	<desc>Framebuffer width.</desc>
5752	</attribute>
5753
5754	<attribute name="height" type="unsigned long" readonly="yes">
5755	<desc>Framebuffer height.</desc>
5756	</attribute>
5757
5758	<attribute name="colorDepth" type="unsigned long" readonly="yes">
5759	<desc>Framebuffer color depth.</desc>
5760	</attribute>
5761
5762	<attribute name="lineSize" type="unsigned long" readonly="yes">
5763	<desc>framebuffer scan line size in bytes.</desc>
5764	</attribute>
5765
5766	<attribute name="pixelFormat" type="FramebufferPixelFormat" readonly="yes">
5767	<desc>Framebuffer pixel format.</desc>
5768	</attribute>
5769
5770	<attribute name="heightReduction" type="unsigned long" readonly="yes">
5771	<desc>
5772	Hint from the framebuffer about how much of the standard
5773	screen height it wants to use for itself. This information is
5774	exposed to the guest through the VESA BIOS and VMMDev interface
5775	so that it can use it for determining its video mode table. It
5776	is not guaranteed that the guest respects the value.
5777	</desc>
5778	</attribute>
5779
5780	<attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
5781	<desc>
5782	An alpha-blended overlay which is superposed over the framebuffer.
5783	The initial purpose is to allow the display of icons providing
5784	information about the VM state, including disk activity, in front
5785	ends which do not have other means of doing that. The overlay is
5786	designed to controlled exclusively by IDisplay. It has no locking
5787	of its own, and any changes made to it are not guaranteed to be
5788	visible until the affected portion of IFramebuffer is updated. The
5789	overlay can be created lazily the first time it is requested. This
5790	attribute can also return NULL to signal that the overlay is not
5791	implemented.
5792	</desc>
5793	</attribute>
5794
5795	<method name="lock">
5796	<desc>
5797	Locks the framebuffer.
5798	Gets called by the display object where this buffer is
5799	registered.
5800	</desc>
5801	</method>
5802
5803	<method name="unlock">
5804	<desc>
5805	Unlocks the framebuffer.
5806	Gets called by the display object where this buffer is
5807	registered.
5808	</desc>
5809	</method>
5810
5811	<method name="notifyUpdate">
5812	<desc>
5813	Informs about an update.
5814	Gets called by the display object where this buffer is
5815	registered.
5816	</desc>
5817	<param name="x" type="unsigned long" dir="in"/>
5818	<param name="y" type="unsigned long" dir="in"/>
5819	<param name="width" type="unsigned long" dir="in"/>
5820	<param name="height" type="unsigned long" dir="in"/>
5821	<param name="finished" type="boolean" dir="return"/>
5822	</method>
5823
5824	<method name="requestResize">
5825	<desc>
5826	Requests a size and pixel format change.
5827
5828	The IFramebuffer implementation should try to setup
5829	a memory buffer suitable for the given pixel format
5830	and line size.
5831	The buffer must be page aligned, must contain
5832	whole number of pages, and one should be able
5833	to lock it to obtain physical addresses of pages.
5834	(Note: this method is currently not supported,
5835	use the below mentioned vram pointer!)
5836
5837	If the requested pixel format is not supported,
5838	or a PixelFormatDefault is requested,
5839	a default format is set. In that case the memory
5840	buffer does not have to be aligned and lockable.
5841
5842	The callee is also allowed to use the guest video memory
5843	buffer (pointed to by the @a vram parameter) directly instead
5844	of allocating its own buffer. To indicate that the framebuffer
5845	wants to use the guest video memory, its <link to="#address"/>
5846	implementation must return the same address as it gets in
5847	the @a vram parameter of this method.
5848
5849	For non linear modes (such as text and standard VGA), the
5850	@vram parameter is NULL and must not be used. When it's not
5851	NULL, it is recommended to use it to access the guest video
5852	memory instead of creating a separate buffer as it will at
5853	least remove one copy operation.
5854
5855	The caller checks if the call was successful
5856	via the <link to="#pixelFormat"/> property.
5857
5858	<note>
5859	This method is called by IDisplay under the IFramebuffer
5860	lock.
5861	</note>
5862	</desc>
5863	<param name="pixelFormat" type="FramebufferPixelFormat" dir="in">
5864	<desc>Pixel format of the surface (BPP and layout)</desc>
5865	</param>
5866	<param name="vram" type="octet" mod="ptr" dir="in">
5867	<desc>Pointer to the guest VRAM (NULL for non linear modes)</desc>
5868	</param>
5869	<param name="lineSize" type="unsigned long" dir="in"/>
5870	<param name="width" type="unsigned long" dir="in"/>
5871	<param name="height" type="unsigned long" dir="in"/>
5872	<param name="finished" type="boolean" dir="return"/>
5873	</method>
5874
5875	<method name="operationSupported">
5876	<desc>
5877	Returns whether the given acceleration operation is supported
5878	by the IFramebuffer implementation. If not, the display object
5879	will not attempt to call the corresponding IFramebuffer entry
5880	point. Even if an operation is indicated to supported, the
5881	IFramebuffer implementation always has the option to return non
5882	supported from the corresponding acceleration method in which
5883	case the operation will be performed by the display engine. This
5884	allows for reduced IFramebuffer implementation complexity where
5885	only common cases are handled.
5886	</desc>
5887	<param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
5888	<param name="supported" type="boolean" dir="return"/>
5889	</method>
5890
5891	<method name="videoModeSupported">
5892	<desc>
5893	Returns whether the framebuffer implementation is willing to
5894	support a given video mode. In case it is not able to render
5895	the video mode (or for some reason not willing), it should
5896	return false. Usually this method is called when the guest
5897	asks the VMM device whether a given video mode is supported
5898	so the information returned is directly exposed to the guest.
5899	It is important that this method returns very quickly.
5900	</desc>
5901	<param name="width" type="unsigned long" dir="in"/>
5902	<param name="height" type="unsigned long" dir="in"/>
5903	<param name="bpp" type="unsigned long" dir="in"/>
5904	<param name="supported" type="boolean" dir="return"/>
5905	</method>
5906
5907	<method name="solidFill">
5908	<desc>
5909	Fill the specified rectangle on screen with a solid color.
5910	</desc>
5911	<param name="x" type="unsigned long" dir="in"/>
5912	<param name="y" type="unsigned long" dir="in"/>
5913	<param name="width" type="unsigned long" dir="in"/>
5914	<param name="height" type="unsigned long" dir="in"/>
5915	<param name="color" type="unsigned long" dir="in"/>
5916	<param name="handled" type="boolean" dir="return"/>
5917	</method>
5918
5919	<method name="copyScreenBits">
5920	<desc>
5921	Copy specified rectangle on the screen.
5922	</desc>
5923	<param name="xDst" type="unsigned long" dir="in"/>
5924	<param name="yDst" type="unsigned long" dir="in"/>
5925	<param name="xSrc" type="unsigned long" dir="in"/>
5926	<param name="ySrc" type="unsigned long" dir="in"/>
5927	<param name="width" type="unsigned long" dir="in"/>
5928	<param name="height" type="unsigned long" dir="in"/>
5929	<param name="handled" type="boolean" dir="return"/>
5930	</method>
5931
5932	</interface>
5933
5934	<interface
5935	name="IFramebufferOverlay" extends="IFrameBuffer"
5936	uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
5937	>
5938	<desc>
5939	An alpha blended overlay for displaying status icons above an IFramebuffer.
5940	It is always created not visible, so that it must be explicitly shown. It
5941	only covers a portion of the IFramebuffer, determined by its width, height
5942	and co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
5943	that order) format, and may be written to directly. Do re-read the width
5944	though, after setting it, as it may be adjusted (increased) to make it more
5945	suitable for the front end.
5946	</desc>
5947	<attribute name="x" type="unsigned long" readonly="yes">
5948	<desc>X position of the overlay, relative to the framebuffer.</desc>
5949	</attribute>
5950
5951	<attribute name="y" type="unsigned long" readonly="yes">
5952	<desc>Y position of the overlay, relative to the framebuffer.</desc>
5953	</attribute>
5954
5955	<attribute name="visible" type="boolean" readonly="no">
5956	<desc>
5957	Whether the overlay is currently visible.
5958	</desc>
5959	</attribute>
5960
5961	<attribute name="alpha" type="unsigned long" readonly="no">
5962	<desc>
5963	The global alpha value for the overlay. This may or may not be
5964	supported by a given front end.
5965	</desc>
5966	</attribute>
5967
5968	<method name="move">
5969	<desc>
5970	Changes the overlay's position relative to the IFramebuffer.
5971	</desc>
5972	<param name="x" type="unsigned long" dir="in"/>
5973	<param name="y" type="unsigned long" dir="in"/>
5974	</method>
5975
5976	</interface>
5977
5978	<interface
5979	name="IDisplay" extends="$unknown"
5980	uuid="FD443EC1-0012-4F5B-9282-D72760A66916"
5981	>
5982	<attribute name="width" type="unsigned long" readonly="yes">
5983	<desc>Current display width.</desc>
5984	</attribute>
5985
5986	<attribute name="height" type="unsigned long" readonly="yes">
5987	<desc>Current display height.</desc>
5988	</attribute>
5989
5990	<attribute name="colorDepth" type="unsigned long" readonly="yes">
5991	<desc>
5992	Current guest display color depth. Note that this may differ
5993	from <link to="IFramebuffer::colorDepth">IFramebuffer::colorDepth</link>.
5994	</desc>
5995	</attribute>
5996
5997	<method name="setupInternalFramebuffer">
5998	<desc>
5999	Prepares an internally managed framebuffer.
6000	</desc>
6001	<param name="depth" type="unsigned long" dir="in"/>
6002	</method>
6003
6004	<method name="lockFramebuffer">
6005	<desc>
6006	Requests access to the internal framebuffer.
6007	</desc>
6008	<param name="address" type="octet" mod="ptr" dir="return"/>
6009	</method>
6010
6011	<method name="unlockFramebuffer">
6012	<desc>
6013	Releases access to the internal framebuffer.
6014	</desc>
6015	</method>
6016
6017	<method name="registerExternalFramebuffer">
6018	<desc>
6019	Registers an external framebuffer.
6020	</desc>
6021	<param name="framebuffer" type="IFramebuffer" dir="in"/>
6022	</method>
6023
6024	<method name="setVideoModeHint">
6025	<desc>
6026	Asks VirtualBox to request the given video mode from
6027	the guest. This is just a hint and it cannot be guaranteed
6028	that the requested resolution will be used. Guest Additions
6029	are required for the request to be seen by guests. The caller
6030	should issue the request and wait for a resolution change and
6031	after a timeout retry.
6032	Specifying "0" for either width and height or the color depth
6033	means that the dimensions or color depth should not be changed.
6034	</desc>
6035	<param name="width" type="unsigned long" dir="in"/>
6036	<param name="height" type="unsigned long" dir="in"/>
6037	<param name="colorDepth" type="unsigned long" dir="in"/>
6038	</method>
6039
6040	<method name="takeScreenShot">
6041	<desc>
6042	Takes a screen shot of the requested size and copies it to the
6043	32-bpp buffer allocated by the caller.
6044	</desc>
6045	<param name="address" type="octet" mod="ptr" dir="in"/>
6046	<param name="width" type="unsigned long" dir="in"/>
6047	<param name="height" type="unsigned long" dir="in"/>
6048	</method>
6049
6050	<method name="drawToScreen">
6051	<desc>
6052	Draws a 32-bpp image of the specified size from the given buffer
6053	to the given point on the VM display.
6054	</desc>
6055	<param name="address" type="octet" mod="ptr" dir="in"/>
6056	<param name="x" type="unsigned long" dir="in"/>
6057	<param name="y" type="unsigned long" dir="in"/>
6058	<param name="width" type="unsigned long" dir="in"/>
6059	<param name="height" type="unsigned long" dir="in"/>
6060	</method>
6061
6062	<method name="invalidateAndUpdate">
6063	<desc>
6064	Does a full invalidation of the VM display and instructs the VM
6065	to update it.
6066	</desc>
6067	</method>
6068
6069	<method name="resizeCompleted">
6070	<desc>
6071	Signals that a framebuffer has completed the resize operation.
6072	</desc>
6073	</method>
6074
6075	<method name="updateCompleted">
6076	<desc>
6077	Signals that a framebuffer has completed the update operation.
6078	</desc>
6079	</method>
6080
6081	</interface>
6082
6083	<!--
6084	// INetworkAdapter
6085	/////////////////////////////////////////////////////////////////////////
6086	-->
6087
6088	<enum
6089	name="NetworkAttachmentType"
6090	uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
6091	>
6092	<const name="NoNetworkAttachment" value="0"/>
6093	<const name="NATNetworkAttachment" value="1"/>
6094	<const name="HostInterfaceNetworkAttachment" value="2"/>
6095	<const name="InternalNetworkAttachment" value="3"/>
6096	</enum>
6097
6098	<enum
6099	name="NetworkAdapterType"
6100	uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
6101	>
6102	<const name="InvalidNetworkAdapterType" value="0"/>
6103	<const name="NetworkAdapterAm79C970A" value="1"/>
6104	<const name="NetworkAdapterAm79C973" value="2"/>
6105	</enum>
6106
6107	<interface
6108	name="INetworkAdapter" extends="$unknown"
6109	uuid="78dfc978-ecb0-44ee-8b20-54549dd4539e"
6110	>
6111	<attribute name="adapterType" type="NetworkAdapterType">
6112	<desc>
6113	Type of the virtual network adapter. Depending on this value,
6114	VirtualBox will provide a different virtual network hardware
6115	to the guest.
6116	</desc>
6117	</attribute>
6118
6119	<attribute name="slot" type="unsigned long" readonly="yes">
6120	<desc>
6121	Slot number this adapter is plugged into. Corresponds to
6122	the value you pass to <link to="IMachine::getNetworkAdapter"/>
6123	to obtain this instance.
6124	</desc>
6125	</attribute>
6126
6127	<attribute name="enabled" type="boolean">
6128	<desc>
6129	Flag whether the network adapter is present in the
6130	guest system. If disabled, the virtual guest hardware will
6131	not contain this network adapter. Can only be changed when
6132	the VM is not running.
6133	</desc>
6134	</attribute>
6135
6136	<attribute name="MACAddress" type="wstring">
6137	<desc>
6138	Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
6139	it to NULL, VirtualBox will generate a unique MAC address.
6140	</desc>
6141	</attribute>
6142
6143	<attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
6144
6145	<attribute name="hostInterface" type="wstring">
6146	<desc>
6147	Name of the Host Network Interface that is currently in use. NULL will be returned
6148	if no device has been allocated. On Linux, setting this refers to a permanent TAP
6149	device. However, a file descriptor has precedence over the interface name on Linux.
6150	Note that when VBox allocates a TAP device, this property will not be set, i.e. the
6151	interface name would have to be determined using the file descriptor and /proc/self/fd.
6152	</desc>
6153	</attribute>
6154
6155	<if target="xpidl">
6156	<attribute name="TAPFileDescriptor" type="long">
6157	<desc>
6158	File descriptor of the TAP device. It can either be setup by the caller
6159	which has to supply an existing valid file handle allocated in the parent
6160	process of the VM process or allocated by VirtualBox. The value is -1 if it
6161	has not been defined. This property is non persistent, i.e. it will not be
6162	stored in the VM's configuration data and thus has to be set at each startup.
6163	</desc>
6164	</attribute>
6165	<attribute name="TAPSetupApplication" type="wstring">
6166	<desc>
6167	Application to start to configure the TAP device.
6168	It is being passed two parameters, 1) the file handle (as ascii),
6169	2) the TAP device name if it is available.
6170	</desc>
6171	</attribute>
6172	<attribute name="TAPTerminateApplication" type="wstring">
6173	<desc>
6174	Application to start before closing a TAP device.
6175	It is being passed two parameters, 1) the file handle (as ascii),
6176	2) the TAP device name if it is available.
6177	</desc>
6178	</attribute>
6179	</if>
6180
6181	<attribute name="internalNetwork" type="wstring">
6182	<desc>
6183	Name of the internal network the VM is attached to.
6184	</desc>
6185	</attribute>
6186
6187	<attribute name="cableConnected" type="boolean">
6188	<desc>
6189	Flag whether the adapter reports the cable as connected or not.
6190	It can be used to report offline situations to a VM.
6191	</desc>
6192	</attribute>
6193
6194	<attribute name="traceEnabled" type="boolean">
6195	<desc>
6196	Flag whether network traffic from/to the network card should be traced.
6197	Can only be toggled when the VM is turned off.
6198	</desc>
6199	</attribute>
6200
6201	<attribute name="traceFile" type="wstring">
6202	<desc>
6203	Filename where a network trace will be stored. If not set, VBox-pid.pcap
6204	will be used.
6205	</desc>
6206	</attribute>
6207
6208	<method name="attachToNAT">
6209	<desc>
6210	Attach the network adapter to the Network Address Translation (NAT) interface.
6211	</desc>
6212	</method>
6213
6214	<method name="attachToHostInterface">
6215	<desc>
6216	Attach the network adapter to a host interface. On Linux, the TAP
6217	setup application will be executed if configured and unless a device
6218	name and/or file descriptor has been set, a new TAP interface will be
6219	created.
6220	</desc>
6221	</method>
6222
6223	<method name="attachToInternalNetwork">
6224	<desc>
6225	Attach the network adapter to an internal network.
6226	</desc>
6227	</method>
6228
6229	<method name="detach">
6230	<desc>
6231	Detach the network adapter
6232	</desc>
6233	</method>
6234	</interface>
6235
6236
6237	<!--
6238	// IMachineDebugger
6239	/////////////////////////////////////////////////////////////////////////
6240	-->
6241
6242	<interface
6243	name="IMachineDebugger" extends="$unknown"
6244	uuid="288da658-74fa-4877-ab5c-dafdad19a1cd"
6245	>
6246	<method name="resetStats">
6247	<desc>
6248	Reset VM statistics.
6249	</desc>
6250	</method>
6251
6252	<method name="dumpStats">
6253	<desc>
6254	Dumps VM statistics.
6255	</desc>
6256	</method>
6257
6258	<attribute name="singlestep" type="boolean">
6259	<desc>Switch for enabling singlestepping.</desc>
6260	</attribute>
6261
6262	<attribute name="recompileUser" type="boolean">
6263	<desc>Switch for forcing code recompilation for user mode code.</desc>
6264	</attribute>
6265
6266	<attribute name="recompileSupervisor" type="boolean">
6267	<desc>Switch for forcing code recompilation for supervisor mode code.</desc>
6268	</attribute>
6269
6270	<attribute name="PATMEnabled" type="boolean">
6271	<desc>Switch for enabling and disabling the PATM component.</desc>
6272	</attribute>
6273
6274	<attribute name="CSAMEnabled" type="boolean">
6275	<desc>Switch for enabling and disabling the CSAM component.</desc>
6276	</attribute>
6277
6278	<attribute name="LogEnabled" type="boolean">
6279	<desc>Switch for enabling and disabling logging.</desc>
6280	</attribute>
6281
6282	<attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
6283	<desc>
6284	Flag indicating whether the VM is currently making use of CPU hardware
6285	virtualization extensions
6286	</desc>
6287	</attribute>
6288
6289	<attribute name="VirtualTimeRate" type="unsigned long">
6290	<desc>
6291	The rate at which the virtual time runs expressed as a percentage.
6292	The accepted range is 2% to 20000%.
6293	</desc>
6294	</attribute>
6295
6296	<!-- @todo method for setting log flags, groups and destination! -->
6297
6298	<attribute name="VM" type="unsigned long long" readonly="yes">
6299	<desc>
6300	Gets the VM handle. This is only for internal use while
6301	we carve the details of this interface.
6302	</desc>
6303	</attribute>
6304
6305	</interface>
6306
6307	<!--
6308	// IUSBController
6309	/////////////////////////////////////////////////////////////////////////
6310	-->
6311
6312	<interface
6313	name="IUSBController" extends="$unknown"
6314	uuid="9a110c34-93c2-46b0-8ac2-b09d1067be56"
6315	>
6316	<attribute name="enabled" type="boolean">
6317	<desc>
6318	Flag whether the USB controller is present in the
6319	guest system. If disabled, the virtual guest hardware will
6320	not contain any USB controller. Can only be changed when
6321	the VM is powered off.
6322	</desc>
6323	</attribute>
6324
6325	<attribute name="USBStandard" type="unsigned short" readonly="yes">
6326	<desc>
6327	USB standard version which the controller implements.
6328	This is a BCD which means that the major version is in the
6329	high byte and minor version is in the low byte.
6330	</desc>
6331	</attribute>
6332
6333	<attribute name="DeviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
6334	<desc>
6335	List of USB device filters associated with the machine.
6336
6337	If the machine is currently running, these filters are activated
6338	every time a new (supported) USB device is attached to the host
6339	computer that was not ignored by global filters
6340	(<link to="IHost::USBDeviceFilters"/>).
6341
6342	These filters are also activated when the machine is powered up.
6343	They are run against a list of all currently available USB
6344	devices (in states
6345	<link to="USBDeviceState::USBDeviceAvailable">USBDeviceAvailable</link>,
6346	<link to="USBDeviceState::USBDeviceBusy">USBDeviceBusy</link>,
6347	<link to="USBDeviceState::USBDeviceHeld">USBDeviceHeld</link>)
6348	that were not previously ignored by global filters.
6349
6350	If at least one filter matches the USB device in question, this
6351	device is automatically captured (attached to) the virtual USB
6352	controller of this machine.
6353
6354	<see>IUSBDeviceFilter, ::IUSBController</see>
6355	</desc>
6356	</attribute>
6357
6358	<method name="createDeviceFilter">
6359	<desc>
6360	Creates a new USB device filter. All attributes except
6361	the filter name are set to <tt>null</tt> (any match),
6362	<i>active</i> is <tt>false</tt> (the filter is not active).
6363
6364	The created filter can then be added to the list of filters using
6365	<link to="#insertDeviceFilter()"/>.
6366
6367	<see>#DeviceFilters</see>
6368	</desc>
6369	<param name="name" type="wstring" dir="in">
6370	<desc>
6371	Filter name. See <link to="IUSBDeviceFilter::name"/>
6372	for more info.
6373	</desc>
6374	</param>
6375	<param name="filter" type="IUSBDeviceFilter" dir="return">
6376	<desc>Created filter object.</desc>
6377	</param>
6378	</method>
6379
6380	<method name="insertDeviceFilter">
6381	<desc>
6382	Inserts the given USB device to the specified position
6383	in the list of filters.
6384
6385	Positions are numbered starting from <tt>0</tt>. If the specified
6386	position is equal to or greater than the number of elements in
6387	the list, the filter is added to the end of the collection.
6388
6389	<note>
6390	Duplicates are not allowed, so an attempt to inster a
6391	filter that is already in the collection, will return an
6392	error.
6393	</note>
6394
6395	<see>#DeviceFilters</see>
6396	</desc>
6397	<param name="position" type="unsigned long" dir="in">
6398	<desc>Position to insert the filter to.</desc>
6399	</param>
6400	<param name="filter" type="IUSBDeviceFilter" dir="in">
6401	<desc>USB device filter to insert.</desc>
6402	</param>
6403	</method>
6404
6405	<method name="removeDeviceFilter">
6406	<desc>
6407	Removes a USB device filter from the specified position in the
6408	list of filters.
6409
6410	Positions are numbered starting from <tt>0</tt>. Specifying a
6411	position equal to or greater than the number of elements in
6412	the list will produce an error.
6413
6414	<see>#DeviceFilters</see>
6415	</desc>
6416	<param name="position" type="unsigned long" dir="in">
6417	<desc>Position to remove the filter from.</desc>
6418	</param>
6419	<param name="filter" type="IUSBDeviceFilter" dir="return">
6420	<desc>Removed USB device filter.</desc>
6421	</param>
6422	</method>
6423
6424	</interface>
6425
6426
6427	<!--
6428	// IUSBDevice
6429	/////////////////////////////////////////////////////////////////////////
6430	-->
6431
6432	<enumerator
6433	name="IUSBDeviceEnumerator" type="IUSBDevice"
6434	uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
6435	/>
6436
6437	<collection
6438	name="IUSBDeviceCollection" type="IUSBDevice"
6439	enumerator="IUSBDeviceEnumerator"
6440	uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
6441	readonly="yes"
6442	>
6443	<method name="findById">
6444	<desc>
6445	Searches this collection for a USB device with the given UUID.
6446	<note>
6447	The method returns an error if the given UUID does not
6448	correspond to any USB device in the collection.
6449	</note>
6450	<see>IUSBDevice::id</see>
6451	</desc>
6452	<param name="id" type="uuid" dir="in">
6453	<desc>UUID of the USB device to search for.</desc>
6454	</param>
6455	<param name="device" type="IUSBDevice" dir="return">
6456	<desc>Found USB device object.</desc>
6457	</param>
6458	</method>
6459
6460	<method name="findByAddress">
6461	<desc>
6462	Searches this collection for a USB device with the given
6463	host address.
6464	<note>
6465	The method returns an error if the given address does not
6466	correspond to any USB device in the collection.
6467	</note>
6468	<see>IUSBDevice::address</see>
6469	</desc>
6470	<param name="name" type="wstring" dir="in">
6471	<desc>
6472	Address of the USB device (as assigned by the host) to
6473	search for.
6474	</desc>
6475	</param>
6476	<param name="device" type="IUSBDevice" dir="return">
6477	<desc>Found USB device object.</desc>
6478	</param>
6479	</method>
6480
6481	</collection>
6482
6483	<interface
6484	name="IUSBDevice" extends="$unknown"
6485	uuid="c5ab8d05-1999-4e48-ae34-cdeb235aacf0"
6486	>
6487	<desc>
6488	The IUSBDevice interface represents a USB device captured by
6489	(attached to) a running virtual machine's USB controller.
6490	<see>IConsole::USBDevices</see>
6491	</desc>
6492
6493	<attribute name="id" type="uuid" readonly="yes">
6494	<desc>
6495	Unique USB device ID. This ID is built from #vendorId,
6496	#productId, #revision and #serialNumber.
6497	</desc>
6498	</attribute>
6499
6500	<attribute name="vendorId" type="unsigned short" readonly="yes">
6501	<desc>Vendor ID.</desc>
6502	</attribute>
6503
6504	<attribute name="productId" type="unsigned short" readonly="yes">
6505	<desc>Product ID.</desc>
6506	</attribute>
6507
6508	<attribute name="revision" type="unsigned short" readonly="yes">
6509	<desc>
6510	Product revision number. This is a packed BCD represented as
6511	unsigned short. The high byte is the integer part and the low
6512	byte is the decimal.
6513	</desc>
6514	</attribute>
6515
6516	<attribute name="manufacturer" type="wstring" readonly="yes">
6517	<desc>Manufacturer string.</desc>
6518	</attribute>
6519
6520	<attribute name="product" type="wstring" readonly="yes">
6521	<desc>Product string.</desc>
6522	</attribute>
6523
6524	<attribute name="serialNumber" type="wstring" readonly="yes">
6525	<desc>Serial number string.</desc>
6526	</attribute>
6527
6528	<attribute name="address" type="wstring" readonly="yes">
6529	<desc>Host specific address of the device.</desc>
6530	</attribute>
6531
6532	<attribute name="port" type="unsigned short" readonly="yes">
6533	<desc>
6534	Host USB port number the device is physically
6535	coonected to.
6536	</desc>
6537	</attribute>
6538
6539	<attribute name="remote" type="boolean" readonly="yes">
6540	<desc>
6541	Whether the device is physically connected to a remote VRDP
6542	client or to a local host machine.
6543	</desc>
6544	</attribute>
6545
6546	</interface>
6547
6548
6549	<!--
6550	// IUSBDeviceFilter
6551	/////////////////////////////////////////////////////////////////////////
6552	-->
6553
6554	<enumerator
6555	name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
6556	uuid="8d066d8b-3576-4a22-a387-847840937453"
6557	/>
6558
6559	<collection
6560	name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
6561	enumerator="IUSBDeviceFilterEnumerator"
6562	uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
6563	readonly="yes"
6564	/>
6565
6566	<interface
6567	name="IUSBDeviceFilter" extends="$unknown"
6568	uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
6569	>
6570	<desc>
6571	The IUSBDeviceFilter interface represents an USB device filter used
6572	to perform actions on a group of USB devices.
6573
6574	This type of filters is used by running virtual machines to
6575	automatically capture selected USB devices once they are physically
6576	attached to the host computer.
6577
6578	A USB device is matched to the given device filter if and only if all
6579	attributes of the device match the corresponding attributes of the
6580	filter (that is, attributes are joined together using the logical AND
6581	operation). On the other hand, all together, filters in the list of
6582	filters carry the semantics of the logical OR operation. So if it is
6583	desirable to create a match like "this vendor id OR this product id",
6584	one needs to create two filters and specify "any match" (see below)
6585	for unused attributes.
6586
6587	All filter attributes used for matching are strings. Each string
6588	is an expression representing a set of values of the corresponding
6589	device attribute, that will match the given filter. Currently, the
6590	following filtering expressions are supported:
6591
6592	<ul>
6593	<li><i>Interval filters</i>. Used to specify valid intervals for
6594	integer device attributes (Vendor ID, Product ID and Revision).
6595	The format of the string is:
6596
6597	<tt>int:((m)\|([m]-[n]))(,(m)\|([m]-[n]))*</tt>
6598
6599	where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
6600	(starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
6601	or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
6602	is ommitted before a dash (<tt>-</tt>), the minimum possible integer
6603	is assumed; if <tt>n</tt> is ommitted after a dash, the maximum
6604	possible integer is assummed.
6605	</li>
6606	<li><i>Boolean filters</i>. Used to specify acceptable values for
6607	boolean device attributes. The format of the string is:
6608
6609	<tt>true\|false\|yes\|no\|0\|1</tt>
6610
6611	</li>
6612	<li><i>Exact match</i>. Used to specify a single value for the given
6613	device attribute. Any string that does't start with <tt>int:</tt>
6614	represents the exact match. String device attributes are compared to
6615	this string including case of symbols. Integer attributes are first
6616	converted to a string (see individual filter attributes) and then
6617	compared ignoring case.
6618
6619	</li>
6620	<li><i>Any match</i>. Any value of the corresponding device attribute
6621	will match the given filter. An empty or <tt>null</tt> string is
6622	used to construct this type of filtering expressions.
6623
6624	</li>
6625	</ul>
6626
6627	<note>
6628	On the Windows host platform, interval filters are not currently
6629	available. Also all string filter attributes
6630	(<link to="#manufacturer"/>, <link to="#product"/>,
6631	<link to="#serialNumber"/>) are ignored, so they behave as
6632	<i>any match</i> no matter what string expression is specified.
6633	</note>
6634
6635	<see>IUSBController::DeviceFilters, IHostUSBDeviceFilter</see>
6636	</desc>
6637
6638	<attribute name="name" type="wstring">
6639	<desc>
6640	Visible name for this filter.
6641	This name is used to visually distungish one filter from another,
6642	so it can neither be <tt>null</tt> nor an empty string.
6643	</desc>
6644	</attribute>
6645
6646	<attribute name="active" type="boolean">
6647	<desc>Whether this filter active or has been temporarily disabled.</desc>
6648	</attribute>
6649
6650	<attribute name="vendorId" type="wstring">
6651	<desc>
6652	<link to="IUSBDevice::vendorId">Vendor ID</link> filter.
6653	The string representation for the <i>exact matching</i>
6654	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
6655	(including leading zeroes).
6656	</desc>
6657	</attribute>
6658
6659	<attribute name="productId" type="wstring">
6660	<desc>
6661	<link to="IUSBDevice::productId">Product ID</link> filter.
6662	The string representation for the <i>exact matching</i>
6663	has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
6664	(including leading zeroes).
6665	</desc>
6666	</attribute>
6667
6668	<attribute name="revision" type="wstring">
6669	<desc>
6670	<link to="IUSBDevice::productId">Product revision number</link>
6671	filter. The string representation for the <i>exact matching</i>
6672	has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
6673	of the integer part of the revision, and <tt>F</tt> is the
6674	decimal digit of its fractional part (including leading and
6675	trailing zeroes).
6676	Note that for interval filters, it's best to use the hexadecimal
6677	form, because the revision is stored as a 16 bit packed BCD value;
6678	so the expression <tt>int:0x0100-0x0199</tt> will match any
6679	revision from <tt>1.0</tt> to <tt>1.99</tt>.
6680	</desc>
6681	</attribute>
6682
6683	<attribute name="manufacturer" type="wstring">
6684	<desc>
6685	<link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
6686	</desc>
6687	</attribute>
6688
6689	<attribute name="product" type="wstring">
6690	<desc>
6691	<link to="IUSBDevice::product">Product</link> filter.
6692	</desc>
6693	</attribute>
6694
6695	<attribute name="serialNumber" type="wstring">
6696	<desc>
6697	<link to="IUSBDevice::serialNumber">Serial number</link> filter.
6698	</desc>
6699	</attribute>
6700
6701	<attribute name="port" type="wstring">
6702	<desc>
6703	<link to="IUSBDevice::port">Host USB port</link> filter.
6704	</desc>
6705	</attribute>
6706
6707	<attribute name="remote" type="wstring">
6708	<desc>
6709	<link to="IUSBDevice::remote">Remote state</link> filter.
6710	<note>
6711	This filter makes sense only for machine USB filters,
6712	i.e. it is ignored by IHostUSBDeviceFilter objects.
6713	</note>
6714	</desc>
6715	</attribute>
6716
6717	</interface>
6718
6719
6720	<!--
6721	// IHostUSBDevice
6722	/////////////////////////////////////////////////////////////////////////
6723	-->
6724
6725	<enum
6726	name="USBDeviceState"
6727	uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
6728	>
6729	<desc>
6730	USB device state. This enumeration represents all possible states
6731	of the USB device physically attached to the host computer regarding
6732	its state on the host computer and availability to guest computers
6733	(all currently running virtual machines).
6734
6735	Once a supported USB device is attached to the host, global USB
6736	filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
6737	either ignore the device, or put ot to #USBDeviceHeld state, or do
6738	nothing. Unless the device is ignored by global filters, filters of
6739	all currently running guests (<link to="IUSBController::DeviceFilters"/>)
6740	are activated that can put it to #USBDeviceCaptured state.
6741
6742	If the device was ignored by global filters, or didn't match
6743	any filters at all (including guest ones), it is handled by the host
6744	in a normal way. In this case, the device state is determined by
6745	the host and can be one of #USBDeviceUnavailable, #USBDeviceBusy or
6746	#USBDeviceAvailable, depending on the current device usage.
6747
6748	Besides auto-capturing based on filters, the device can be manually
6749	captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
6750	state is #USBDeviceBusy, #USBDeviceAvailable or #USBDeviceHeld.
6751
6752	<note>
6753	Due to differences in USB stack implementations in Linux and Win32,
6754	states #USBDeviceBusy and #USBDeviceAvailable are applicable
6755	only to the Linux version of the product. This also means that
6756	(<link to="IConsole::attachUSBDevice()"/>) can only succeed
6757	on Win32 if the device state is #USBDeviceHeld.
6758	</note>
6759
6760	<see>IHostUSBDevice, IHostUSBDeviceFilter</see>
6761	</desc>
6762
6763	<const name="USBDeviceNotSupported" value="0">
6764	<desc>
6765	Not supported by the VirtualBox server, not available to guests.
6766	</desc>
6767	</const>
6768	<const name="USBDeviceUnavailable" value="1">
6769	<desc>
6770	Being used by the host computer exclusively,
6771	not available to guests.
6772	</desc>
6773	</const>
6774	<const name="USBDeviceBusy" value="2">
6775	<desc>
6776	Being used by the host computer, potentially available to guests.
6777	</desc>
6778	</const>
6779	<const name="USBDeviceAvailable" value="3">
6780	<desc>
6781	Not used by the host computer, available to guests.
6782	The host computer can also start using the device at any time.
6783	</desc>
6784	</const>
6785	<const name="USBDeviceHeld" value="4">
6786	<desc>
6787	Held by the VirtualBox server (ignored by the host computer),
6788	available to guests.
6789	</desc>
6790	</const>
6791	<const name="USBDeviceCaptured" value="5">
6792	<desc>
6793	Captured by one of the guest computers, not available
6794	to anybody else.
6795	</desc>
6796	</const>
6797	</enum>
6798
6799	<enumerator
6800	name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
6801	uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
6802	/>
6803
6804	<collection
6805	name="IHostUSBDeviceCollection" type="IHostUSBDevice"
6806	enumerator="IHostUSBDeviceEnumerator"
6807	uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
6808	readonly="yes"
6809	>
6810	<method name="findById">
6811	<desc>
6812	Searches this collection for a USB device with the given UUID.
6813	<note>
6814	The method returns an error if the given UUID does not
6815	correspond to any USB device in the collection.
6816	</note>
6817	<see>IHostUSBDevice::id</see>
6818	</desc>
6819	<param name="id" type="uuid" dir="in">
6820	<desc>UUID of the USB device to search for.</desc>
6821	</param>
6822	<param name="device" type="IHostUSBDevice" dir="return">
6823	<desc>Found USB device object.</desc>
6824	</param>
6825	</method>
6826
6827	<method name="findByAddress">
6828	<desc>
6829	Searches this collection for a USB device with the given
6830	host address.
6831	<note>
6832	The method returns an error if the given address does not
6833	correspond to any USB device in the collection.
6834	</note>
6835	<see>IHostUSBDevice::address</see>
6836	</desc>
6837	<param name="name" type="wstring" dir="in">
6838	<desc>
6839	Address of the USB device (as assigned by the host) to
6840	search for.
6841	</desc>
6842	</param>
6843	<param name="device" type="IHostUSBDevice" dir="return">
6844	<desc>Found USB device object.</desc>
6845	</param>
6846	</method>
6847
6848	</collection>
6849
6850	<interface
6851	name="IHostUSBDevice" extends="IUSBDevice"
6852	uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
6853	>
6854	<desc>
6855	The IHostUSBDevice interface represents a USB device attached to
6856	the host computer.
6857
6858	Among with properties inherited from IUSBDevice,
6859	this interface adds the <link to="#state"/> property
6860	that holds the courrent state of the USB device.
6861
6862	<see>IHost::USBDevices, IHost::USBDeviceFilters</see>
6863	</desc>
6864
6865	<attribute name="state" type="USBDeviceState" readonly="yes">
6866	<desc>
6867	Current state of the device.
6868	</desc>
6869	</attribute>
6870
6871	<!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
6872
6873	</interface>
6874
6875
6876	<!--
6877	// IHostUSBDeviceFilter
6878	/////////////////////////////////////////////////////////////////////////
6879	-->
6880
6881	<enum
6882	name="USBDeviceFilterAction"
6883	uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
6884	>
6885	<desc>
6886	Actions for host USB device filters.
6887	<see>IHostUSBDeviceFilter, USBDeviceState</see>
6888	</desc>
6889
6890	<const name="InvalidUSBDeviceFilterAction" value="0"/>
6891	<const name="USBDeviceFilterIgnore" value="1">
6892	<desc>Ignore the matched USB device.</desc>
6893	</const>
6894	<const name="USBDeviceFilterHold" value="2">
6895	<desc>Hold the matched USB device.</desc>
6896	</const>
6897	</enum>
6898
6899	<enumerator
6900	name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
6901	uuid="ff735211-903e-4642-9c37-189eb44579fe"
6902	/>
6903
6904	<collection
6905	name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
6906	enumerator="IHostUSBDeviceFilterEnumerator"
6907	uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
6908	readonly="yes"
6909	/>
6910
6911	<interface
6912	name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
6913	uuid="4cc70246-d74a-400f-8222-3900489c0374"
6914	>
6915	<desc>
6916	The IHostUSBDeviceFilter interface represents a USB device filter used
6917	by the host computer.
6918
6919	Using filters of this type, the host computer determines the initial
6920	state of the USB device after it is physically attached to the
6921	host's USB controller.
6922
6923	<note>
6924	The <link to="#remote"/> attribute is ignored by this type of
6925	filters, because it makes sense only for
6926	<link to="IUSBController::DeviceFilters">machine USB filters</link>.
6927	</note>
6928
6929	<see>IHost::USBDeviceFilters</see>
6930	</desc>
6931
6932	<attribute name="action" type="USBDeviceFilterAction">
6933	<desc>
6934	Action performed by the host when an attached USB device
6935	matches this filter.
6936	</desc>
6937	</attribute>
6938
6939	</interface>
6940
6941	<!--
6942	// IAudioAdapter
6943	/////////////////////////////////////////////////////////////////////////
6944	-->
6945
6946	<enum
6947	name="AudioDriverType"
6948	uuid="0194b900-7233-42d3-b7a1-097bbf53febd"
6949	>
6950	<const name="NullAudioDriver" value="0"/>
6951	<const name="WINMMAudioDriver" value="1"/>
6952	<const name="OSSAudioDriver" value="2"/>
6953	<const name="ALSAAudioDriver" value="3"/>
6954	<const name="DSOUNDAudioDriver" value="4"/>
6955	<const name="CoreAudioDriver" value="5"/>
6956	</enum>
6957
6958	<interface
6959	name="IAudioAdapter" extends="$unknown"
6960	uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
6961	>
6962	<attribute name="enabled" type="boolean">
6963	<desc>
6964	Flag whether the audio adapter is present in the
6965	guest system. If disabled, the virtual guest hardware will
6966	not contain any audio adapter. Can only be changed when
6967	the VM is not running.
6968	</desc>
6969	</attribute>
6970	<attribute name="audioDriver" type="AudioDriverType">
6971	<desc>
6972	Audio driver the adapter is connected to. This setting
6973	can only be changed when the VM is not running.
6974	</desc>
6975	</attribute>
6976	</interface>
6977
6978	<!--
6979	// IVRDPServer
6980	/////////////////////////////////////////////////////////////////////////
6981	-->
6982
6983	<enum
6984	name="VRDPAuthType"
6985	uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
6986	>
6987	<const name="VRDPAuthNull" value="0"/>
6988	<const name="VRDPAuthExternal" value="1"/>
6989	<const name="VRDPAuthGuest" value="2"/>
6990	</enum>
6991
6992	<interface
6993	name="IVRDPServer" extends="$unknown"
6994	uuid="2e88bf9e-2085-421f-9aa2-32088b0378b3"
6995	>
6996	<attribute name="enabled" type="boolean">
6997	<desc>VRDP server status.</desc>
6998	</attribute>
6999
7000	<attribute name="port" type="unsigned long">
7001	<desc>VRDP server port.</desc>
7002	</attribute>
7003
7004	<attribute name="netAddress" type="wstring">
7005	<desc>VRDP server address.</desc>
7006	</attribute>
7007
7008	<attribute name="authType" type="VRDPAuthType">
7009	<desc>VRDP authentication method.</desc>
7010	</attribute>
7011
7012	<attribute name="authTimeout" type="unsigned long">
7013	<desc>Timeout for guest authentication. Milliseconds.</desc>
7014	</attribute>
7015
7016	</interface>
7017
7018
7019	<!--
7020	// ISharedFolder
7021	/////////////////////////////////////////////////////////////////////////
7022	-->
7023
7024	<enumerator
7025	name="ISharedFolderEnumerator" type="ISharedFolder"
7026	uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
7027	/>
7028
7029	<collection
7030	name="ISharedFolderCollection" type="ISharedFolder"
7031	enumerator="ISharedFolderEnumerator"
7032	uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
7033	readonly="yes">
7034
7035	<method name="findByName">
7036	<desc>
7037	Searches this collection for a shared folder drive with the
7038	given logical name.
7039	<note>
7040	The method returns an error if the given name does not
7041	correspond to any shared folder in the collection.
7042	</note>
7043	</desc>
7044	<param name="name" type="wstring" dir="in">
7045	<desc>Logical name of the shared folder to search for</desc>
7046	</param>
7047	<param name="sharedFolder" type="ISharedFolder" dir="return">
7048	<desc>Found shared folder object</desc>
7049	</param>
7050	</method>
7051
7052	</collection>
7053
7054	<interface
7055	name="ISharedFolder" extends="$unknown"
7056	uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
7057	>
7058	<desc>
7059	The ISharedFolder interface represents a folder in the host
7060	computer's file system accessible from a guest OS running inside a
7061	virtual machine using an associated logical name.
7062
7063	There are three types of shared folders:
7064	<ul>
7065	<li>permanent (<link to="IMachine::sharedFolders"/>)</li>
7066	<li>transient (<link to="IConsole::sharedFolders"/>)</li>
7067	<li>global (<link to="IVirtualBox::sharedFolders"/>)</li>
7068	</ul>
7069
7070	For a given virtual machine, both permanently and transiently
7071	shared folders have the same logical name space which also includes
7072	all globally shared folders. Thus, every folder in this name space
7073	must have an unique logical name. Note that permanent and transient
7074	shares of other machines are in different name spaces, so they don't
7075	have to have unique names.
7076	</desc>
7077
7078	<attribute name="name" type="wstring" readonly="yes">
7079	<desc>Logical name of the shared folder.</desc>
7080	</attribute>
7081
7082	<attribute name="hostPath" type="wstring" readonly="yes">
7083	<desc>Full path to the shared folder in the host file system.</desc>
7084	</attribute>
7085
7086	<attribute name="accessible" type="boolean" readonly="yes">
7087	<desc>
7088	Whether the folder defined by the host path is currently
7089	accessible or not.
7090	For example, the folder can be unaccessible if it is placed
7091	on the network share that is not available by the time
7092	this property is read.
7093	</desc>
7094	</attribute>
7095
7096	</interface>
7097
7098	<!--
7099	// ISession
7100	/////////////////////////////////////////////////////////////////////////
7101	-->
7102
7103	<interface
7104	name="IInternalSessionControl" extends="$unknown"
7105	uuid="A99D5EB3-02DE-48e4-B059-91A8A41B4DA1"
7106	internal="yes"
7107	>
7108	<method name="getPID">
7109	<desc>PID of the process that has created this Session object.
7110	</desc>
7111	<param name="pid" type="unsigned long" dir="return"/>
7112	</method>
7113
7114	<method name="getRemoteConsole">
7115	<desc>Returns the console object suitable for remote control.</desc>
7116	<param name="console" type="IConsole" dir="return"/>
7117	</method>
7118
7119	<method name="assignMachine">
7120	<desc>
7121	Assigns the machine object associated with this direct-type
7122	session or informs the session that it will be a remote one
7123	(if machine = NULL).
7124	</desc>
7125	<param name="machine" type="IMachine" dir="in"/>
7126	</method>
7127
7128	<method name="assignRemoteMachine">
7129	<desc>
7130	Assigns the machine and the (remote) console object associated with
7131	this remote-type session.
7132	</desc>
7133	<param name="machine" type="IMachine" dir="in"/>
7134	<param name="console" type="IConsole" dir="in"/>
7135	</method>
7136
7137	<method name="updateMachineState">
7138	<desc>
7139	Updates the machine state in the VM process.
7140	Must be called only in certain cases
7141	(see the method implementation).
7142	</desc>
7143	<param name="aMachineState" type="MachineState" dir="in"/>
7144	</method>
7145
7146	<method name="uninitialize">
7147	<desc>
7148	Uninitializes (closes) this session. Used by VirtualBox to close
7149	the corresponding remote session when the direct session dies
7150	or gets closed.
7151	</desc>
7152	</method>
7153
7154	<method name="onDVDDriveChange">
7155	<desc>
7156	Triggered when settings of the DVD drive object of the
7157	associated virtual machine have changed.
7158	</desc>
7159	</method>
7160
7161	<method name="onFloppyDriveChange">
7162	<desc>
7163	Triggered when settings of the floppy drive object of the
7164	associated virtual machine have changed.
7165	</desc>
7166	</method>
7167
7168	<method name="onNetworkAdapterChange">
7169	<desc>
7170	Triggered when settions of a network adapter of the
7171	associated virtual machine have changed.
7172	</desc>
7173	<param name="networkAdapter" type="INetworkAdapter" dir="in"/>
7174	</method>
7175
7176	<method name="onVRDPServerChange">
7177	<desc>
7178	Triggered when settings of the VRDP server object of the
7179	associated virtual machine have changed.
7180	</desc>
7181	</method>
7182
7183	<method name="onUSBControllerChange">
7184	<desc>
7185	Triggered when settings of the USB controller object of the
7186	associated virtual machine have changed.
7187	</desc>
7188	</method>
7189
7190	<method name="onUSBDeviceAttach">
7191	<desc>
7192	Triggered when a USB device has just been attached to the host
7193	computer and is to be auto-captured by the machine according
7194	to its USB filters.
7195	</desc>
7196	<param name="device" type="IUSBDevice" dir="in"/>
7197	</method>
7198
7199	<method name="onUSBDeviceDetach">
7200	<desc>
7201	Triggered when a USB device has just been detached from the host
7202	computer and needs to be detached from the machine.
7203	</desc>
7204	<param name="id" type="uuid" dir="in"/>
7205	</method>
7206
7207	</interface>
7208
7209	<interface
7210	name="ISession" extends="$dispatched"
7211	uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
7212	>
7213	<attribute name="state" type="SessionState" readonly="yes">
7214	<desc>Current state of this session.</desc>
7215	</attribute>
7216
7217	<attribute name="type" type="SessionType" readonly="yes">
7218	<desc>
7219	Type of this session. The value of this attribute is valid only
7220	if the session is currently open (i.e. its #state is SessionType::SessionOpen),
7221	otherwise an error will be returned.
7222	</desc>
7223	</attribute>
7224
7225	<attribute name="machine" type="IMachine" readonly="yes">
7226	<desc>Machine object associated with this session.</desc>
7227	</attribute>
7228
7229	<attribute name="console" type="IConsole" readonly="yes">
7230	<desc>Console object associated with this session.</desc>
7231	</attribute>
7232
7233	<method name="close">
7234	<desc>
7235	Closes this session.
7236	<note>
7237	If a direct session for a machine opened with
7238	<link to="IVirtualBox::openSession()"/> is not explicitly
7239	closed when the application terminates, the state of the
7240	machine will be set to <link to="MachineState::Aborted"/>
7241	on the server. Generally, it is recommended to close all
7242	open sessions explicitly before terminating the application
7243	(no matter what is the reason of the termination).
7244	</note>
7245	</desc>
7246	</method>
7247
7248	</interface>
7249
7250	<class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
7251	namespace="virtualbox.org">
7252	<interface name="ISession" default="yes"/>
7253	</class>
7254
7255
7256	</module>
7257
7258	</idl>

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

Download in other formats:

Original Format