VirtualBox

source: vbox/trunk/src/VBox/Main/idl/VirtualBox.xidl@ 38038

Last change on this file since 38038 was 38010, checked in by vboxsync, 14 years ago

comment fix

  • Property svn:eol-style set to native
File size: 644.7 KB
Line 
1<?xml version="1.0" ?>
2
3<!--
4
5 Copyright (C) 2006-2011 Oracle Corporation
6
7 This file is part of VirtualBox Open Source Edition (OSE), as
8 available from http://www.virtualbox.org. This file is free software;
9 you can redistribute it and/or modify it under the terms of the GNU
10 General Public License (GPL) as published by the Free Software
11 Foundation, in version 2 as it comes in the "COPYING" file of the
12 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
14-->
15
16<!--
17 This is the master declaration for VirtualBox's Main API,
18 represented by COM/XPCOM and web service interfaces.
19
20 From this document, the build system generates several files
21 via XSLT that are then used during the build process.
22
23 Below is the list of XSL templates that operate on this file and
24 output files they generate. These XSL templates must be updated
25 whenever the schema of this file changes:
26
27 1. src/VBox/Main/idl/midl.xsl =>
28 out/<platform>/bin/sdk/idl/VirtualBox.idl
29 (MS COM interface definition file for Main API)
30
31 2. src/VBox/Main/idl/xpidl.xsl =>
32 out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
33 (XPCOM interface definition file for Main API)
34
35 3. src/VBox/Main/idl/doxygen.xsl =>
36 out/<platform>/obj/src/VBox/Main/VirtualBox.idl
37 (pseudo-IDL for Doxygen to generate the official Main API
38 documentation)
39
40 4. src/VBox/Main/webservice/*.xsl =>
41 a bunch of WSDL and C++ files
42 (VirtualBox web service sources and SOAP mappers;
43 see src/VBox/Main/webservice/Makefile.kmk for details)
44
45 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
46 out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
47 (smart Qt-based C++ wrapper classes for COM interfaces
48 of the Main API)
49
50 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
51 out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
52 (Main API TypeLib block for the WiX installer)
53
54 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
55 out/<platform>/obj/Runtime/errmsgvboxcomdata.h
56 (<result> extraction for the %Rhrc format specifier)
57-->
58
59<idl>
60
61<desc>
62 Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
63 describes the so-called <i>VirtualBox Main API</i> which comprises all public
64 COM interfaces and components provided by the VirtualBox server and by the
65 VirtualBox client library.
66
67 VirtualBox employs a client-server design, meaning that whenever any part of
68 VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
69 interface or any virtual machine --, a dedicated server process named
70 VBoxSVC runs in the background. This allows multiple processes working with
71 VirtualBox to cooperate without conflicts. These processes communicate to each
72 other using inter-process communication facilities provided by the COM
73 implementation of the host computer.
74
75 On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
76 implementation. On all other platforms, Mozilla XPCOM, an open-source COM
77 implementation, is used.
78
79 All the parts that a typical VirtualBox user interacts with (the Qt GUI
80 and the VBoxManage command-line interface) are technically
81 front-ends to the Main API and only use the interfaces that are documented
82 in this Main API documentation. This ensures that, with any given release
83 version of VirtualBox, all capabilities of the product that could be useful
84 to an external client program are always exposed by way of this API.
85
86 The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
87 contains two public component classes:
88 <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
89 implement IVirtualBox and ISession interfaces respectively. These two classes
90 are of supreme importance and will be needed in order for any front-end
91 program to do anything useful. It is recommended to read the documentation of
92 the mentioned interfaces first.
93
94 The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
95 there can be only one object of this class on the local machine at any given
96 time. This object is a parent of many other objects in the VirtualBox COM
97 library and lives in the VBoxSVC process. In fact, when you create an instance
98 of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
99 process is already running, starts it if not, and returns you a reference to
100 the <tt>VirtualBox</tt> object created in this process. When the last reference
101 to this object is released, the VBoxSVC process ends (with a 5 second delay to
102 protect from too frequent restarts).
103
104 The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
105 as many <tt>Session</tt> objects as you need but all of them will live in a
106 process which issues the object instantiation call. <tt>Session</tt> objects
107 represent virtual machine sessions which are used to configure virtual
108 machines and control their execution.
109</desc>
110
111<if target="midl">
112 <cpp line="enum {"/>
113 <cpp line=" kTypeLibraryMajorVersion = 1,"/>
114 <cpp line=" kTypeLibraryMinorVersion = 0"/>
115 <cpp line="};"/>
116</if>
117
118<if target="xpidl">
119 <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
120 <cpp>
121/* currently, nsISupportsImpl.h lacks the below-like macros */
122
123#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
124#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
125#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
126#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI
127
128
129#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
130# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
131 NS_IMPL_THREADSAFE_ADDREF(_class) \
132 NS_IMPL_THREADSAFE_RELEASE(_class) \
133 NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
134 NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
135#endif
136
137#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
138# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
139 NS_IMPL_THREADSAFE_ADDREF(_class) \
140 NS_IMPL_THREADSAFE_RELEASE(_class) \
141 NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
142 NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
143#endif
144
145#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
146# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
147 NS_IMPL_THREADSAFE_ADDREF(_class) \
148 NS_IMPL_THREADSAFE_RELEASE(_class) \
149 NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
150 NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
151#endif
152
153#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI
154# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \
155 NS_IMPL_THREADSAFE_ADDREF(_class) \
156 NS_IMPL_THREADSAFE_RELEASE(_class) \
157 NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \
158 NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)
159#endif
160
161#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
162# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
163 NS_INTERFACE_MAP_BEGIN(_class) \
164 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
165 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
166 NS_IMPL_QUERY_CLASSINFO(_class) \
167 NS_INTERFACE_MAP_END
168#endif
169
170#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
171# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
172 _i2, _ic2) \
173 NS_INTERFACE_MAP_BEGIN(_class) \
174 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
175 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
176 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
177 NS_IMPL_QUERY_CLASSINFO(_class) \
178 NS_INTERFACE_MAP_END
179#endif
180
181#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
182# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
183 _i2, _ic2, _i3, _ic3) \
184 NS_INTERFACE_MAP_BEGIN(_class) \
185 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
186 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
187 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
188 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
189 NS_IMPL_QUERY_CLASSINFO(_class) \
190 NS_INTERFACE_MAP_END
191#endif
192
193#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
194#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
195#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
196
197#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
198# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
199 NS_IMPL_THREADSAFE_ADDREF(_class) \
200 NS_IMPL_THREADSAFE_RELEASE(_class) \
201 NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
202 NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
203#endif
204
205#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
206# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
207 _i2, _ic2) \
208 NS_IMPL_THREADSAFE_ADDREF(_class) \
209 NS_IMPL_THREADSAFE_RELEASE(_class) \
210 NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
211 _i2, _ic2) \
212 NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
213#endif
214
215#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
216# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
217 _i2, _ic2, _i3, _ic3) \
218 NS_IMPL_THREADSAFE_ADDREF(_class) \
219 NS_IMPL_THREADSAFE_RELEASE(_class) \
220 NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
221 _i2, _ic2, _i3, _ic3) \
222 NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
223#endif
224
225 </cpp>
226</if>
227
228<library
229 name="VirtualBox"
230 uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
231 version="1.3"
232 desc="VirtualBox Type Library"
233 appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
234 supportsErrorInfo="yes"
235>
236
237
238 <!--
239 // COM result codes for VirtualBox
240 /////////////////////////////////////////////////////////////////////////
241 -->
242
243 <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
244 <desc>
245 This section describes all VirtualBox-specific COM result codes that may
246 be returned by methods of VirtualBox COM interfaces in addition to
247 standard COM result codes.
248
249 Note that along with the result code, every VirtualBox method returns
250 extended error information through the IVirtualBoxErrorInfo interface on
251 failure. This interface is a preferred way to present the error to the end
252 user because it contains a human readable description of the error. Raw
253 result codes, both standard and described in this section, are intended to
254 be used by programs to analyze the reason of a failure and select an
255 appropriate course of action without involving the end user (for example,
256 retry the operation later or make a different call).
257
258 The standard COM result codes that may originate from our methods include:
259
260 <table>
261 <tr><td>E_INVALIDARG</td>
262 <td>
263 Returned when the value of the method's argument is not within the range
264 of valid values. This should not be confused with situations when the
265 value is within the range but simply doesn't suit the current object
266 state and there is a possibility that it will be accepted later (in such
267 cases VirtualBox-specific codes are returned, for example,
268 <link to="VBOX_E_OBJECT_NOT_FOUND"/>).
269 </td>
270 </tr>
271 <tr><td>E_POINTER</td>
272 <td>
273 Returned if a memory pointer for the output argument is invalid (for
274 example, @c null). When pointers representing input arguments (such
275 as strings) are invalid, E_INVALIDARG is returned.
276 </td>
277 </tr>
278 <tr><td>E_ACCESSDENIED</td>
279 <td>
280 Returned when the called object is not ready. Since the lifetime of a
281 public COM object cannot be fully controlled by the implementation,
282 VirtualBox maintains the readiness state for all objects it creates and
283 returns this code in response to any method call on the object that was
284 deactivated by VirtualBox and is not functioning any more.
285 </td>
286 </tr>
287 <tr><td>E_OUTOFMEMORY</td>
288 <td>
289 Returned when a memory allocation operation fails.
290 </td>
291 </tr>
292 </table>
293 </desc>
294 </descGroup>
295
296 <!--
297 Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
298 everything in <result>/<desc> after (and including) the first dot, so express
299 the matter of the error code in the first sentence and keep it short.
300 -->
301
302 <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
303 <desc>
304 Object corresponding to the supplied arguments does not exist.
305 </desc>
306 </result>
307
308 <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
309 <desc>
310 Current virtual machine state prevents the operation.
311 </desc>
312 </result>
313
314 <result name="VBOX_E_VM_ERROR" value="0x80BB0003">
315 <desc>
316 Virtual machine error occurred attempting the operation.
317 </desc>
318 </result>
319
320 <result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
321 <desc>
322 File not accessible or erroneous file contents.
323 </desc>
324 </result>
325
326 <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
327 <desc>
328 Runtime subsystem error.
329 </desc>
330 </result>
331
332 <result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
333 <desc>
334 Pluggable Device Manager error.
335 </desc>
336 </result>
337
338 <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
339 <desc>
340 Current object state prohibits operation.
341 </desc>
342 </result>
343
344 <result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
345 <desc>
346 Host operating system related error.
347 </desc>
348 </result>
349
350 <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
351 <desc>
352 Requested operation is not supported.
353 </desc>
354 </result>
355
356 <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
357 <desc>
358 Invalid XML found.
359 </desc>
360 </result>
361
362 <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
363 <desc>
364 Current session state prohibits operation.
365 </desc>
366 </result>
367
368 <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
369 <desc>
370 Object being in use prohibits operation.
371 </desc>
372 </result>
373
374 <!--
375 Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
376 everything in <result>/<desc> after (and including) the first dot, so express
377 the matter of the error code in the first sentence and keep it short.
378 -->
379
380 <descGroup/>
381
382 <!--
383 // all common enums
384 /////////////////////////////////////////////////////////////////////////
385 -->
386
387 <enum
388 name="SettingsVersion"
389 uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
390 >
391 <desc>
392 Settings version of VirtualBox settings files. This is written to
393 the "version" attribute of the root "VirtualBox" element in the settings
394 file XML and indicates which VirtualBox version wrote the file.
395 </desc>
396
397 <const name="Null" value="0">
398 <desc>Null value, indicates invalid version.</desc>
399 </const>
400 <const name="v1_0" value="1">
401 <desc>Legacy settings version, not currently supported.</desc>
402 </const>
403 <const name="v1_1" value="2">
404 <desc>Legacy settings version, not currently supported.</desc>
405 </const>
406 <const name="v1_2" value="3">
407 <desc>Legacy settings version, not currently supported.</desc>
408 </const>
409 <const name="v1_3pre" value="4">
410 <desc>Legacy settings version, not currently supported.</desc>
411 </const>
412 <const name="v1_3" value="5">
413 <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
414 <!--
415 Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
416 -->
417 </const>
418 <const name="v1_4" value="6">
419 <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
420 <!--
421 VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
422 (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
423 -->
424 </const>
425 <const name="v1_5" value="7">
426 <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
427 <!--
428 2008-09-04: 2.0.0 released
429 2008-11-20: settings version 1.5 introduced
430 2008-12-17: 2.1.0 released
431 Machine changes:
432 guest OS identifiers changed;
433 Machine/Hardware/Display/MonitorCount renamed to monitorCount;
434 Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
435 Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
436 -->
437 </const>
438 <const name="v1_6" value="8">
439 <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
440 <!--
441 2008-12-17: 2.1.0 released
442 2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
443 2009-04-08: 2.2.0 released
444 Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
445 -->
446 </const>
447 <const name="v1_7" value="9">
448 <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
449 <!--
450 2008-12-17: 2.1.0 released
451 2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
452 2009-04-08: 2.2.0 released
453 VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
454 Machine changes: HardDiskAttachments is now StorageControllers (done)
455 -->
456 </const>
457 <const name="v1_8" value="10">
458 <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
459 <!--
460 Machine additions: Display/@accelerate2DVideo (done)
461 -->
462 </const>
463 <const name="v1_9" value="11">
464 <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
465 <!--
466 The big storage controller / DVD / Floppy rework (done)
467 -->
468 </const>
469 <const name="v1_10" value="12">
470 <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
471 <!--
472 Machine changes: RTC localOrUTC (done)
473 CPU hot-plug support
474 -->
475 </const>
476 <const name="v1_11" value="13">
477 <desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc>
478 <!--
479 Machine changes: HD Audio controller, per-machine disk registries,
480 /@format attribute for DVD and floppy images.
481 -->
482 </const>
483 <const name="v1_12" value="14">
484 <desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc>
485 <!--
486 Machine changes: raw PCI device attachment;
487 NetworkAdapter changes: bandwidth group.
488 -->
489 </const>
490
491 <const name="Future" value="99999">
492 <desc>Settings version greater than "1.12", written by a future VirtualBox version.</desc>
493 </const>
494 </enum>
495
496 <enum
497 name="AccessMode"
498 uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
499 >
500 <desc>
501 Access mode for opening files.
502 </desc>
503
504 <const name="ReadOnly" value="1"/>
505 <const name="ReadWrite" value="2"/>
506 </enum>
507
508 <enum
509 name="MachineState"
510 uuid="ec6c6a9e-113d-4ff4-b44f-0b69f21c97fe"
511 >
512 <desc>
513 Virtual machine execution state.
514
515 This enumeration represents possible values of the <link
516 to="IMachine::state"/> attribute.
517
518 Below is the basic virtual machine state diagram. It shows how the state
519 changes during virtual machine execution. The text in square braces shows
520 a method of the IConsole interface that performs the given state
521 transition.
522
523 <pre>
524 +---------[powerDown()] &lt;- Stuck &lt;--[failure]-+
525 V |
526 +-&gt; PoweredOff --+--&gt;[powerUp()]--&gt; Starting --+ | +-----[resume()]-----+
527 | | | | V |
528 | Aborted -----+ +--&gt; Running --[pause()]--&gt; Paused
529 | | ^ | ^ |
530 | Saved -----------[powerUp()]--&gt; Restoring -+ | | | |
531 | ^ | | | |
532 | | +-----------------------------------------+-|-------------------+ +
533 | | | | |
534 | | +-- Saving &lt;--------[takeSnapshot()]&lt;-------+---------------------+
535 | | | |
536 | +-------- Saving &lt;--------[saveState()]&lt;----------+---------------------+
537 | | |
538 +-------------- Stopping -------[powerDown()]&lt;----------+---------------------+
539 </pre>
540
541 Note that states to the right from PoweredOff, Aborted and Saved in the
542 above diagram are called <i>online VM states</i>. These states
543 represent the virtual machine which is being executed in a dedicated
544 process (usually with a GUI window attached to it where you can see the
545 activity of the virtual machine and interact with it). There are two
546 special pseudo-states, FirstOnline and LastOnline, that can be used in
547 relational expressions to detect if the given machine state is online or
548 not:
549
550 <pre>
551 if (machine.GetState() &gt;= MachineState_FirstOnline &amp;&amp;
552 machine.GetState() &lt;= MachineState_LastOnline)
553 {
554 ...the machine is being executed...
555 }
556 </pre>
557
558 When the virtual machine is in one of the online VM states (that is, being
559 executed), only a few machine settings can be modified. Methods working
560 with such settings contain an explicit note about that. An attempt to
561 change any other setting or perform a modifying operation during this time
562 will result in the @c VBOX_E_INVALID_VM_STATE error.
563
564 All online states except Running, Paused and Stuck are transitional: they
565 represent temporary conditions of the virtual machine that will last as
566 long as the operation that initiated such a condition.
567
568 The Stuck state is a special case. It means that execution of the machine
569 has reached the "Guru Meditation" condition. This condition indicates an
570 internal VMM (virtual machine manager) failure which may happen as a
571 result of either an unhandled low-level virtual hardware exception or one
572 of the recompiler exceptions (such as the <i>too-many-traps</i>
573 condition).
574
575 Note also that any online VM state may transit to the Aborted state. This
576 happens if the process that is executing the virtual machine terminates
577 unexpectedly (for example, crashes). Other than that, the Aborted state is
578 equivalent to PoweredOff.
579
580 There are also a few additional state diagrams that do not deal with
581 virtual machine execution and therefore are shown separately. The states
582 shown on these diagrams are called <i>offline VM states</i> (this includes
583 PoweredOff, Aborted and Saved too).
584
585 The first diagram shows what happens when a lengthy setup operation is
586 being executed (such as <link to="IMachine::attachDevice"/>).
587
588 <pre>
589 +----------------------------------(same state as before the call)------+
590 | |
591 +-&gt; PoweredOff --+ |
592 | | |
593 |-&gt; Aborted -----+--&gt;[lengthy VM configuration call] --&gt; SettingUp -----+
594 | |
595 +-&gt; Saved -------+
596 </pre>
597
598 The next two diagrams demonstrate the process of taking a snapshot of a
599 powered off virtual machine, restoring the state to that as of a snapshot
600 or deleting a snapshot, respectively.
601
602 <pre>
603 +----------------------------------(same state as before the call)------+
604 | |
605 +-&gt; PoweredOff --+ |
606 | +--&gt;[takeSnapshot()] -------------------&gt; Saving ------+
607 +-&gt; Aborted -----+
608
609 +-&gt; PoweredOff --+
610 | |
611 | Aborted -----+--&gt;[restoreSnapshot() ]-------&gt; RestoringSnapshot -+
612 | | [deleteSnapshot() ]-------&gt; DeletingSnapshot --+
613 +-&gt; Saved -------+ |
614 | |
615 +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
616 </pre>
617
618 Note that the Saving state is present in both the offline state group and
619 online state group. Currently, the only way to determine what group is
620 assumed in a particular case is to remember the previous machine state: if
621 it was Running or Paused, then Saving is an online state, otherwise it is
622 an offline state. This inconsistency may be removed in one of the future
623 versions of VirtualBox by adding a new state.
624
625 <note internal="yes">
626 For whoever decides to touch this enum: In order to keep the
627 comparisons involving FirstOnline and LastOnline pseudo-states valid,
628 the numeric values of these states must be correspondingly updated if
629 needed: for any online VM state, the condition
630 <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
631 @c true. The same relates to transient states for which
632 the condition <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
633 @c true.
634 </note>
635 </desc>
636
637 <const name="Null" value="0">
638 <desc>Null value (never used by the API).</desc>
639 </const>
640 <const name="PoweredOff" value="1">
641 <desc>
642 The machine is not running and has no saved execution state; it has
643 either never been started or been shut down successfully.
644 </desc>
645 </const>
646 <const name="Saved" value="2">
647 <desc>
648 The machine is not currently running, but the execution state of the machine
649 has been saved to an external file when it was running, from where
650 it can be resumed.
651 </desc>
652 </const>
653 <const name="Teleported" value="3">
654 <desc>
655 The machine was teleported to a different host (or process) and then
656 powered off. Take care when powering it on again may corrupt resources
657 it shares with the teleportation target (e.g. disk and network).
658 </desc>
659 </const>
660 <const name="Aborted" value="4">
661 <desc>
662 The process running the machine has terminated abnormally. This may
663 indicate a crash of the VM process in host execution context, or
664 the VM process has been terminated externally.
665 </desc>
666 </const>
667 <const name="Running" value="5">
668 <desc>
669 The machine is currently being executed.
670 <note internal="yes">
671 For whoever decides to touch this enum: In order to keep the
672 comparisons in the old source code valid, this state must immediately
673 precede the Paused state.
674 TODO: Lift this spectacularly wonderful restriction.
675 </note>
676 </desc>
677 </const>
678 <const name="Paused" value="6">
679 <desc>
680 Execution of the machine has been paused.
681 <note internal="yes">
682 For whoever decides to touch this enum: In order to keep the
683 comparisons in the old source code valid, this state must immediately
684 follow the Running state.
685 TODO: Lift this spectacularly wonderful restriction.
686 </note>
687 </desc>
688 </const>
689 <const name="Stuck" value="7">
690 <desc>
691 Execution of the machine has reached the "Guru Meditation"
692 condition. This indicates a severe error in the hypervisor itself.
693 <note internal="yes">
694 bird: Why this uncool name? Could we rename it to "GuruMeditation" or
695 "Guru", perhaps? Or are there some other VMM states that are
696 intended to be lumped in here as well?
697 </note>
698 </desc>
699 </const>
700 <const name="Teleporting" value="8">
701 <desc>
702 The machine is about to be teleported to a different host or process.
703 It is possible to pause a machine in this state, but it will go to the
704 @c TeleportingPausedVM state and it will not be
705 possible to resume it again unless the teleportation fails.
706 </desc>
707 </const>
708 <const name="LiveSnapshotting" value="9">
709 <desc>
710 A live snapshot is being taken. The machine is running normally, but
711 some of the runtime configuration options are inaccessible. Also, if
712 paused while in this state it will transition to
713 @c Saving and it will not be resume the
714 execution until the snapshot operation has completed.
715 </desc>
716 </const>
717 <const name="Starting" value="10">
718 <desc>
719 Machine is being started after powering it on from a
720 zero execution state.
721 </desc>
722 </const>
723 <const name="Stopping" value="11">
724 <desc>
725 Machine is being normally stopped powering it off, or after the guest OS
726 has initiated a shutdown sequence.
727 </desc>
728 </const>
729 <const name="Saving" value="12">
730 <desc>
731 Machine is saving its execution state to a file, or an online
732 snapshot of the machine is being taken.
733 </desc>
734 </const>
735 <const name="Restoring" value="13">
736 <desc>
737 Execution state of the machine is being restored from a file
738 after powering it on from the saved execution state.
739 </desc>
740 </const>
741 <const name="TeleportingPausedVM" value="14">
742 <desc>
743 The machine is being teleported to another host or process, but it is
744 not running. This is the paused variant of the
745 @c state.
746 </desc>
747 </const>
748 <const name="TeleportingIn" value="15">
749 <desc>
750 Teleporting the machine state in from another host or process.
751 </desc>
752 </const>
753 <const name="FaultTolerantSyncing" value="16">
754 <desc>
755 The machine is being synced with a fault tolerant VM running elsewhere.
756 </desc>
757 </const>
758 <const name="DeletingSnapshotOnline" value="17">
759 <desc>
760 Like @c DeletingSnapshot, but the merging of media is ongoing in
761 the background while the machine is running.
762 </desc>
763 </const>
764 <const name="DeletingSnapshotPaused" value="18">
765 <desc>
766 Like @c DeletingSnapshotOnline, but the machine was paused when the
767 merging of differencing media was started.
768 </desc>
769 </const>
770 <const name="RestoringSnapshot" value="19">
771 <desc>
772 A machine snapshot is being restored; this typically does not take long.
773 </desc>
774 </const>
775 <const name="DeletingSnapshot" value="20">
776 <desc>
777 A machine snapshot is being deleted; this can take a long time since this
778 may require merging differencing media. This value indicates that the
779 machine is not running while the snapshot is being deleted.
780 </desc>
781 </const>
782 <const name="SettingUp" value="21">
783 <desc>
784 Lengthy setup operation is in progress.
785 </desc>
786 </const>
787
788 <const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
789 <desc>
790 Pseudo-state: first online state (for use in relational expressions).
791 </desc>
792 </const>
793 <const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
794 <desc>
795 Pseudo-state: last online state (for use in relational expressions).
796 </desc>
797 </const>
798
799 <const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
800 <desc>
801 Pseudo-state: first transient state (for use in relational expressions).
802 </desc>
803 </const>
804 <const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp -->
805 <desc>
806 Pseudo-state: last transient state (for use in relational expressions).
807 </desc>
808 </const>
809
810 </enum>
811
812 <enum
813 name="SessionState"
814 uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
815 >
816 <desc>
817 Session state. This enumeration represents possible values of
818 <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
819 attributes.
820 </desc>
821
822 <const name="Null" value="0">
823 <desc>Null value (never used by the API).</desc>
824 </const>
825 <const name="Unlocked" value="1">
826 <desc>
827 In <link to="IMachine::sessionState"/>, this means that the machine
828 is not locked for any sessions.
829
830 In <link to="ISession::state"/>, this means that no machine is
831 currently locked for this session.
832 </desc>
833 </const>
834 <const name="Locked" value="2">
835 <desc>
836 In <link to="IMachine::sessionState"/>, this means that the machine
837 is currently locked for a session, whose process identifier can
838 then be found in the <link to="IMachine::sessionPid" /> attribute.
839
840 In <link to="ISession::state"/>, this means that a machine is
841 currently locked for this session, and the mutable machine object
842 can be found in the <link to="ISession::machine"/> attribute
843 (see <link to="IMachine::lockMachine" /> for details).
844 </desc>
845 </const>
846 <const name="Spawning" value="3">
847 <desc>
848 A new process is being spawned for the machine as a result of
849 <link to="IMachine::launchVMProcess"/> call. This state also occurs
850 as a short transient state during an <link to="IMachine::lockMachine"/>
851 call.
852 </desc>
853 </const>
854 <const name="Unlocking" value="4">
855 <desc>
856 The session is being unlocked.
857 </desc>
858 </const>
859 </enum>
860
861 <enum
862 name="CPUPropertyType"
863 uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
864 >
865 <desc>
866 Virtual CPU property type. This enumeration represents possible values of the
867 IMachine get- and setCPUProperty methods.
868 </desc>
869 <const name="Null" value="0">
870 <desc>Null value (never used by the API).</desc>
871 </const>
872 <const name="PAE" value="1">
873 <desc>
874 This setting determines whether VirtualBox will expose the Physical Address
875 Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
876 is not available, it will not be reported.
877 </desc>
878 </const>
879 <const name="Synthetic" value="2">
880 <desc>
881 This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
882 teleporting between host systems that differ significantly.
883 </desc>
884 </const>
885 </enum>
886
887
888 <enum
889 name="HWVirtExPropertyType"
890 uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
891 >
892 <desc>
893 Hardware virtualization property type. This enumeration represents possible values
894 for the <link to="IMachine::getHWVirtExProperty"/> and
895 <link to="IMachine::setHWVirtExProperty"/> methods.
896 </desc>
897 <const name="Null" value="0">
898 <desc>Null value (never used by the API).</desc>
899 </const>
900 <const name="Enabled" value="1">
901 <desc>
902 Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
903 such extensions are not available, they will not be used.
904 </desc>
905 </const>
906 <const name="Exclusive" value="2">
907 <desc>
908 Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
909 VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
910 feature of the host. To share these with other hypervisors, you must disable this property.
911 </desc>
912 </const>
913 <const name="VPID" value="3">
914 <desc>
915 Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
916 </desc>
917 </const>
918 <const name="NestedPaging" value="4">
919 <desc>
920 Whether Nested Paging is enabled. If this extension is not available, it will not be used.
921 </desc>
922 </const>
923 <const name="LargePages" value="5">
924 <desc>
925 Whether large page allocation is enabled; requires nested paging and a 64 bits host.
926 </desc>
927 </const>
928 <const name="Force" value="6">
929 <desc>
930 Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If
931 not set, there will be an automatic fallback to software virtualization.
932 </desc>
933 </const>
934 </enum>
935
936 <enum
937 name="FaultToleranceState"
938 uuid="5124f7ec-6b67-493c-9dee-ee45a44114e1"
939 >
940 <desc>
941 Used with <link to="IMachine::faultToleranceState" />.
942 </desc>
943 <const name="Inactive" value="1">
944 <desc>No fault tolerance enabled.</desc>
945 </const>
946 <const name="Master" value="2">
947 <desc>Fault tolerant master VM.</desc>
948 </const>
949 <const name="Standby" value="3">
950 <desc>Fault tolerant standby VM.</desc>
951 </const>
952 </enum>
953
954 <enum
955 name="LockType"
956 uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"
957 >
958 <desc>
959 Used with <link to="IMachine::lockMachine" />.
960 </desc>
961 <const name="Write" value="2">
962 <desc>Lock the machine for writing.</desc>
963 </const>
964 <const name="Shared" value="1">
965 <desc>Request only a shared read lock for remote-controlling the machine.</desc>
966 </const>
967 </enum>
968
969 <enum
970 name="SessionType"
971 uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
972 >
973 <desc>
974 Session type. This enumeration represents possible values of the
975 <link to="ISession::type"/> attribute.
976 </desc>
977
978 <const name="Null" value="0">
979 <desc>Null value (never used by the API).</desc>
980 </const>
981 <const name="WriteLock" value="1">
982 <desc>
983 Session has acquired an exclusive write lock on a machine
984 using <link to="IMachine::lockMachine"/>.
985 </desc>
986 </const>
987 <const name="Remote" value="2">
988 <desc>
989 Session has launched a VM process using
990 <link to="IMachine::launchVMProcess"/>
991 </desc>
992 </const>
993 <const name="Shared" value="3">
994 <desc>
995 Session has obtained a link to another session using
996 <link to="IMachine::lockMachine"/>
997 </desc>
998 </const>
999 </enum>
1000
1001 <enum
1002 name="DeviceType"
1003 uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
1004 >
1005 <desc>
1006 Device type.
1007 </desc>
1008 <const name="Null" value="0">
1009 <desc>
1010 Null value, may also mean "no device" (not allowed for
1011 <link to="IConsole::getDeviceActivity"/>).
1012 </desc>
1013 </const>
1014 <const name="Floppy" value="1">
1015 <desc>Floppy device.</desc>
1016 </const>
1017 <const name="DVD" value="2">
1018 <desc>CD/DVD-ROM device.</desc>
1019 </const>
1020 <const name="HardDisk" value="3">
1021 <desc>Hard disk device.</desc>
1022 </const>
1023 <const name="Network" value="4">
1024 <desc>Network device.</desc>
1025 </const>
1026 <const name="USB" value="5">
1027 <desc>USB device.</desc>
1028 </const>
1029 <const name="SharedFolder" value="6">
1030 <desc>Shared folder device.</desc>
1031 </const>
1032 </enum>
1033
1034 <enum
1035 name="DeviceActivity"
1036 uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
1037 >
1038 <desc>
1039 Device activity for <link to="IConsole::getDeviceActivity"/>.
1040 </desc>
1041
1042 <const name="Null" value="0"/>
1043 <const name="Idle" value="1"/>
1044 <const name="Reading" value="2"/>
1045 <const name="Writing" value="3"/>
1046 </enum>
1047
1048 <enum
1049 name="ClipboardMode"
1050 uuid="33364716-4008-4701-8f14-be0fa3d62950"
1051 >
1052 <desc>
1053 Host-Guest clipboard interchange mode.
1054 </desc>
1055
1056 <const name="Disabled" value="0"/>
1057 <const name="HostToGuest" value="1"/>
1058 <const name="GuestToHost" value="2"/>
1059 <const name="Bidirectional" value="3"/>
1060 </enum>
1061
1062 <enum
1063 name="Scope"
1064 uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
1065 >
1066 <desc>
1067 Scope of the operation.
1068
1069 A generic enumeration used in various methods to define the action or
1070 argument scope.
1071 </desc>
1072
1073 <const name="Global" value="0"/>
1074 <const name="Machine" value="1"/>
1075 <const name="Session" value="2"/>
1076 </enum>
1077
1078 <enum
1079 name="BIOSBootMenuMode"
1080 uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
1081 >
1082 <desc>
1083 BIOS boot menu mode.
1084 </desc>
1085
1086 <const name="Disabled" value="0"/>
1087 <const name="MenuOnly" value="1"/>
1088 <const name="MessageAndMenu" value="2"/>
1089 </enum>
1090
1091 <enum
1092 name="ProcessorFeature"
1093 uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
1094 >
1095 <desc>
1096 CPU features.
1097 </desc>
1098
1099 <const name="HWVirtEx" value="0"/>
1100 <const name="PAE" value="1"/>
1101 <const name="LongMode" value="2"/>
1102 <const name="NestedPaging" value="3"/>
1103 </enum>
1104
1105 <enum
1106 name="FirmwareType"
1107 uuid="b903f264-c230-483e-ac74-2b37ce60d371"
1108 >
1109 <desc>
1110 Firmware type.
1111 </desc>
1112 <const name="BIOS" value="1">
1113 <desc>BIOS Firmware.</desc>
1114 </const>
1115 <const name="EFI" value="2">
1116 <desc>EFI Firmware, bitness detected basing on OS type.</desc>
1117 </const>
1118 <const name="EFI32" value="3">
1119 <desc>Efi firmware, 32-bit.</desc>
1120 </const>
1121 <const name="EFI64" value="4">
1122 <desc>Efi firmware, 64-bit.</desc>
1123 </const>
1124 <const name="EFIDUAL" value="5">
1125 <desc>Efi firmware, combined 32 and 64-bit.</desc>
1126 </const>
1127 </enum>
1128
1129 <enum
1130 name="PointingHidType"
1131 uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
1132 >
1133 <desc>
1134 Type of pointing device used in a virtual machine.
1135 </desc>
1136 <const name="None" value="1">
1137 <desc>No mouse.</desc>
1138 </const>
1139 <const name="PS2Mouse" value="2">
1140 <desc>PS/2 auxiliary device, a.k.a. mouse.</desc>
1141 </const>
1142 <const name="USBMouse" value="3">
1143 <desc>USB mouse (relative pointer).</desc>
1144 </const>
1145 <const name="USBTablet" value="4">
1146 <desc>USB tablet (absolute pointer).</desc>
1147 </const>
1148 <const name="ComboMouse" value="5">
1149 <desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
1150 Using of such device can have negative performance implications. </desc>
1151 </const>
1152 </enum>
1153
1154 <enum
1155 name="KeyboardHidType"
1156 uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
1157 >
1158 <desc>
1159 Type of keyboard device used in a virtual machine.
1160 </desc>
1161 <const name="None" value="1">
1162 <desc>No keyboard.</desc>
1163 </const>
1164 <const name="PS2Keyboard" value="2">
1165 <desc>PS/2 keyboard.</desc>
1166 </const>
1167 <const name="USBKeyboard" value="3">
1168 <desc>USB keyboard.</desc>
1169 </const>
1170 <const name="ComboKeyboard" value="4">
1171 <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
1172 Using of such device can have negative performance implications. </desc>
1173 </const>
1174 </enum>
1175
1176 <!--
1177 // IVirtualBoxErrorInfo
1178 /////////////////////////////////////////////////////////////////////////
1179 -->
1180
1181 <interface
1182 name="IVirtualBoxErrorInfo" extends="$errorinfo"
1183 uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"
1184 supportsErrorInfo="no"
1185 wsmap="managed"
1186 >
1187 <desc>
1188 The IVirtualBoxErrorInfo interface represents extended error information.
1189
1190 Extended error information can be set by VirtualBox components after
1191 unsuccessful or partially successful method invocation. This information
1192 can be retrieved by the calling party as an IVirtualBoxErrorInfo object
1193 and then shown to the client in addition to the plain 32-bit result code.
1194
1195 In MS COM, this interface extends the IErrorInfo interface,
1196 in XPCOM, it extends the nsIException interface. In both cases,
1197 it provides a set of common attributes to retrieve error
1198 information.
1199
1200 Sometimes invocation of some component's method may involve methods of
1201 other components that may also fail (independently of this method's
1202 failure), or a series of non-fatal errors may precede a fatal error that
1203 causes method failure. In cases like that, it may be desirable to preserve
1204 information about all errors happened during method invocation and deliver
1205 it to the caller. The <link to="#next"/> attribute is intended
1206 specifically for this purpose and allows to represent a chain of errors
1207 through a single IVirtualBoxErrorInfo object set after method invocation.
1208
1209 <note>errors are stored to a chain in the reverse order, i.e. the
1210 initial error object you query right after method invocation is the last
1211 error set by the callee, the object it points to in the @a next attribute
1212 is the previous error and so on, up to the first error (which is the last
1213 in the chain).</note>
1214 </desc>
1215
1216 <attribute name="resultCode" type="long" readonly="yes">
1217 <desc>
1218 Result code of the error.
1219 Usually, it will be the same as the result code returned
1220 by the method that provided this error information, but not
1221 always. For example, on Win32, CoCreateInstance() will most
1222 likely return E_NOINTERFACE upon unsuccessful component
1223 instantiation attempt, but not the value the component factory
1224 returned. Value is typed 'long', not 'result',
1225 to make interface usable from scripting languages.
1226 <note>
1227 In MS COM, there is no equivalent.
1228 In XPCOM, it is the same as nsIException::result.
1229 </note>
1230 </desc>
1231 </attribute>
1232
1233 <attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
1234 <desc>
1235 UUID of the interface that defined the error.
1236 <note>
1237 In MS COM, it is the same as IErrorInfo::GetGUID, except for the
1238 data type.
1239 In XPCOM, there is no equivalent.
1240 </note>
1241 </desc>
1242 </attribute>
1243
1244 <attribute name="component" type="wstring" readonly="yes">
1245 <desc>
1246 Name of the component that generated the error.
1247 <note>
1248 In MS COM, it is the same as IErrorInfo::GetSource.
1249 In XPCOM, there is no equivalent.
1250 </note>
1251 </desc>
1252 </attribute>
1253
1254 <attribute name="text" type="wstring" readonly="yes">
1255 <desc>
1256 Text description of the error.
1257 <note>
1258 In MS COM, it is the same as IErrorInfo::GetDescription.
1259 In XPCOM, it is the same as nsIException::message.
1260 </note>
1261 </desc>
1262 </attribute>
1263
1264 <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
1265 <desc>
1266 Next error object if there is any, or @c null otherwise.
1267 <note>
1268 In MS COM, there is no equivalent.
1269 In XPCOM, it is the same as nsIException::inner.
1270 </note>
1271 </desc>
1272 </attribute>
1273
1274 </interface>
1275
1276 <!--
1277 // IVirtualBox
1278 /////////////////////////////////////////////////////////////////////////
1279 -->
1280
1281 <interface
1282 name="IDHCPServer" extends="$unknown"
1283 uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1284 wsmap="managed"
1285 >
1286 <desc>
1287 The IDHCPServer interface represents the vbox dhcp server configuration.
1288
1289 To enumerate all the dhcp servers on the host, use the
1290 <link to="IVirtualBox::DHCPServers"/> attribute.
1291 </desc>
1292
1293 <attribute name="enabled" type="boolean">
1294 <desc>
1295 specifies if the dhcp server is enabled
1296 </desc>
1297 </attribute>
1298
1299 <attribute name="IPAddress" type="wstring" readonly="yes">
1300 <desc>
1301 specifies server IP
1302 </desc>
1303 </attribute>
1304
1305 <attribute name="networkMask" type="wstring" readonly="yes">
1306 <desc>
1307 specifies server network mask
1308 </desc>
1309 </attribute>
1310
1311 <attribute name="networkName" type="wstring" readonly="yes">
1312 <desc>
1313 specifies internal network name the server is used for
1314 </desc>
1315 </attribute>
1316
1317 <attribute name="lowerIP" type="wstring" readonly="yes">
1318 <desc>
1319 specifies from IP address in server address range
1320 </desc>
1321 </attribute>
1322
1323 <attribute name="upperIP" type="wstring" readonly="yes">
1324 <desc>
1325 specifies to IP address in server address range
1326 </desc>
1327 </attribute>
1328
1329 <method name="setConfiguration">
1330 <desc>
1331 configures the server
1332 <result name="E_INVALIDARG">
1333 invalid configuration supplied
1334 </result>
1335 </desc>
1336 <param name="IPAddress" type="wstring" dir="in">
1337 <desc>
1338 server IP address
1339 </desc>
1340 </param>
1341 <param name="networkMask" type="wstring" dir="in">
1342 <desc>
1343 server network mask
1344 </desc>
1345 </param>
1346 <param name="FromIPAddress" type="wstring" dir="in">
1347 <desc>
1348 server From IP address for address range
1349 </desc>
1350 </param>
1351 <param name="ToIPAddress" type="wstring" dir="in">
1352 <desc>
1353 server To IP address for address range
1354 </desc>
1355 </param>
1356 </method>
1357
1358 <method name="start">
1359 <desc>
1360 Starts DHCP server process.
1361 <result name="E_FAIL">
1362 Failed to start the process.
1363 </result>
1364 </desc>
1365 <param name="networkName" type="wstring" dir="in">
1366 <desc>
1367 Name of internal network DHCP server should attach to.
1368 </desc>
1369 </param>
1370 <param name="trunkName" type="wstring" dir="in">
1371 <desc>
1372 Name of internal network trunk.
1373 </desc>
1374 </param>
1375 <param name="trunkType" type="wstring" dir="in">
1376 <desc>
1377 Type of internal network trunk.
1378 </desc>
1379 </param>
1380 </method>
1381
1382 <method name="stop">
1383 <desc>
1384 Stops DHCP server process.
1385 <result name="E_FAIL">
1386 Failed to stop the process.
1387 </result>
1388 </desc>
1389 </method>
1390 </interface>
1391
1392 <interface
1393 name="IVirtualBox" extends="$unknown"
1394 uuid="c28be65f-1a8f-43b4-81f1-eb60cb516e66"
1395 wsmap="managed"
1396 >
1397 <desc>
1398 The IVirtualBox interface represents the main interface exposed by the
1399 product that provides virtual machine management.
1400
1401 An instance of IVirtualBox is required for the product to do anything
1402 useful. Even though the interface does not expose this, internally,
1403 IVirtualBox is implemented as a singleton and actually lives in the
1404 process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1405 IVirtualBox can track the state of all virtual machines on a particular
1406 host, regardless of which frontend started them.
1407
1408 To enumerate all the virtual machines on the host, use the
1409 <link to="IVirtualBox::machines"/> attribute.
1410 </desc>
1411
1412 <attribute name="version" type="wstring" readonly="yes">
1413 <desc>
1414 A string representing the version number of the product. The
1415 format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1416 last number represents the build number and will frequently change.
1417 </desc>
1418 </attribute>
1419
1420 <attribute name="revision" type="unsigned long" readonly="yes">
1421 <desc>
1422 The internal build revision number of the product.
1423 </desc>
1424 </attribute>
1425
1426 <attribute name="packageType" type="wstring" readonly="yes">
1427 <desc>
1428 A string representing the package type of this product. The
1429 format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1430 SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1431 is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1432 this.
1433 </desc>
1434 </attribute>
1435
1436 <attribute name="APIVersion" type="wstring" readonly="yes">
1437 <desc>
1438 A string representing the VirtualBox API version number. The format is
1439 2 integer numbers divided by an underscore (e.g. 1_0). After the
1440 first public release of packages with a particular API version the
1441 API will not be changed in an incompatible way. Note that this
1442 guarantee does not apply to development builds, and also there is no
1443 guarantee that this version is identical to the first two integer
1444 numbers of the package version.
1445 </desc>
1446 </attribute>
1447
1448 <attribute name="homeFolder" type="wstring" readonly="yes">
1449 <desc>
1450 Full path to the directory where the global settings file,
1451 <tt>VirtualBox.xml</tt>, is stored.
1452
1453 In this version of VirtualBox, the value of this property is
1454 always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
1455 <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
1456 as determined by the host OS), and cannot be changed.
1457
1458 This path is also used as the base to resolve relative paths in
1459 places where relative paths are allowed (unless otherwise
1460 expressly indicated).
1461 </desc>
1462 </attribute>
1463
1464 <attribute name="settingsFilePath" type="wstring" readonly="yes">
1465 <desc>
1466 Full name of the global settings file.
1467 The value of this property corresponds to the value of
1468 <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1469 </desc>
1470 </attribute>
1471
1472 <attribute name="host" type="IHost" readonly="yes">
1473 <desc>Associated host object.</desc>
1474 </attribute>
1475
1476 <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1477 <desc>Associated system information object.</desc>
1478 </attribute>
1479
1480 <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1481 <desc>
1482 Array of machine objects registered within this VirtualBox instance.
1483 </desc>
1484 </attribute>
1485
1486 <attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
1487 <desc>
1488 Array of medium objects known to this VirtualBox installation.
1489
1490 This array contains only base media. All differencing
1491 media of the given base medium can be enumerated using
1492 <link to="IMedium::children"/>.
1493 </desc>
1494 </attribute>
1495
1496 <attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
1497 <desc>
1498 Array of CD/DVD image objects currently in use by this VirtualBox instance.
1499 </desc>
1500 </attribute>
1501
1502 <attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
1503 <desc>
1504 Array of floppy image objects currently in use by this VirtualBox instance.
1505 </desc>
1506 </attribute>
1507
1508 <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1509
1510 <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1511
1512 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1513 <desc>
1514 Collection of global shared folders. Global shared folders are
1515 available to all virtual machines.
1516
1517 New shared folders are added to the collection using
1518 <link to="#createSharedFolder"/>. Existing shared folders can be
1519 removed using <link to="#removeSharedFolder"/>.
1520
1521 <note>
1522 In the current version of the product, global shared folders are not
1523 implemented and therefore this collection is always empty.
1524 </note>
1525 </desc>
1526 </attribute>
1527
1528 <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1529 <desc>
1530 Associated performance collector object.
1531 </desc>
1532 </attribute>
1533
1534 <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1535 <desc>
1536 DHCP servers.
1537 </desc>
1538 </attribute>
1539
1540 <attribute name="eventSource" type="IEventSource" readonly="yes">
1541 <desc>
1542 Event source for VirtualBox events.
1543 </desc>
1544 </attribute>
1545
1546 <attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">
1547 <desc>
1548 The extension pack manager.
1549 </desc>
1550 </attribute>
1551
1552
1553 <attribute name="internalNetworks" type="wstring" safearray="yes" readonly="yes">
1554 <desc>
1555 Names of all internal networks.
1556 </desc>
1557 </attribute>
1558
1559 <attribute name="genericNetworkDrivers" type="wstring" safearray="yes" readonly="yes">
1560 <desc>
1561 Names of all generic network drivers.
1562 </desc>
1563 </attribute>
1564
1565 <method name="composeMachineFilename">
1566 <desc>
1567 Returns a recommended full path of the settings file name for a new virtual
1568 machine.
1569
1570 This API serves two purposes:
1571
1572 <ul>
1573 <li>It gets called by <link to="#createMachine" /> if NULL is specified
1574 for the @a settingsFile argument there, which means that API should use
1575 a recommended default file name.</li>
1576
1577 <li>It can be called manually by a client software before creating a machine,
1578 e.g. if that client wants to pre-create the machine directory to create
1579 virtual hard disks in that directory together with the new machine
1580 settings file. In that case, the file name should be stripped from the
1581 full settings file path returned by this function to obtain the
1582 machine directory.</li>
1583 </ul>
1584
1585 See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
1586 details about the machine name.
1587
1588 If @a baseFolder is a @c null or empty string (which is recommended), the
1589 default machine settings folder
1590 (see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
1591 a base folder for the created machine, resulting in a file name like
1592 "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
1593 will be used.
1594
1595 This method does not access the host disks. In particular, it does not check
1596 for whether a machine of this name already exists.
1597 </desc>
1598 <param name="name" type="wstring" dir="in">
1599 <desc>Suggested machine name.</desc>
1600 </param>
1601 <param name="baseFolder" type="wstring" dir="in">
1602 <desc>Base machine folder (optional).</desc>
1603 </param>
1604 <param name="file" type="wstring" dir="return">
1605 <desc>Fully qualified path where the machine would be created.</desc>
1606 </param>
1607 </method>
1608
1609 <method name="createMachine">
1610 <desc>
1611 Creates a new virtual machine by creating a machine settings file at
1612 the given location.
1613
1614 VirtualBox machine settings files use a custom XML dialect. Starting
1615 with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
1616 and machine files can be created at arbitrary locations.
1617
1618 However, it is is recommended that machines be created in the default
1619 machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
1620 <link to="ISystemProperties::defaultMachineFolder" />). If you specify
1621 NULL for the @a settingsFile argument, <link to="#composeMachineFilename" />
1622 is called automatically to have such a recommended name composed based
1623 on the machine name given in the @a name argument.
1624
1625 If the resulting settings file already exists, this method will fail,
1626 unless @a forceOverwrite is set.
1627
1628 The new machine is created unregistered, with the initial configuration
1629 set according to the specified guest OS type. A typical sequence of
1630 actions to create a new virtual machine is as follows:
1631
1632 <ol>
1633 <li>
1634 Call this method to have a new machine created. The returned machine
1635 object will be "mutable" allowing to change any machine property.
1636 </li>
1637
1638 <li>
1639 Configure the machine using the appropriate attributes and methods.
1640 </li>
1641
1642 <li>
1643 Call <link to="IMachine::saveSettings" /> to write the settings
1644 to the machine's XML settings file. The configuration of the newly
1645 created machine will not be saved to disk until this method is
1646 called.
1647 </li>
1648
1649 <li>
1650 Call <link to="#registerMachine" /> to add the machine to the list
1651 of machines known to VirtualBox.
1652 </li>
1653 </ol>
1654
1655 The specified guest OS type identifier must match an ID of one of known
1656 guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1657 array.
1658
1659 Optionally, you may specify an UUID of to assign to the created machine.
1660 However, this is not recommended and you should normally pass an empty
1661 (@c null) UUID to this method so that a new UUID will be automatically
1662 generated for every created machine. You can use UUID
1663 00000000-0000-0000-0000-000000000000 as @c null value.
1664
1665 <note>
1666 There is no way to change the name of the settings file or
1667 subfolder of the created machine directly.
1668 </note>
1669
1670 <result name="VBOX_E_OBJECT_NOT_FOUND">
1671 @a osTypeId is invalid.
1672 </result>
1673 <result name="VBOX_E_FILE_ERROR">
1674 Resulting settings file name is invalid or the settings file already
1675 exists or could not be created due to an I/O error.
1676 </result>
1677 <result name="E_INVALIDARG">
1678 @a name is empty or @c null.
1679 </result>
1680 </desc>
1681
1682 <param name="settingsFile" type="wstring" dir="in">
1683 <desc>Fully qualified path where the settings file should be created,
1684 or NULL for a default folder and file based on the @a name argument
1685 (see <link to="#composeMachineFilename" />).</desc>
1686 </param>
1687 <param name="name" type="wstring" dir="in">
1688 <desc>Machine name.</desc>
1689 </param>
1690 <param name="osTypeId" type="wstring" dir="in">
1691 <desc>Guest OS Type ID.</desc>
1692 </param>
1693 <param name="id" type="uuid" mod="string" dir="in">
1694 <desc>Machine UUID (optional).</desc>
1695 </param>
1696 <param name="forceOverwrite" type="boolean" dir="in">
1697 <desc>If true, an existing machine settings file will be overwritten.</desc>
1698 </param>
1699 <param name="machine" type="IMachine" dir="return">
1700 <desc>Created machine object.</desc>
1701 </param>
1702 </method>
1703
1704 <method name="openMachine">
1705 <desc>
1706 Opens a virtual machine from the existing settings file.
1707 The opened machine remains unregistered until you call
1708 <link to="#registerMachine"/>.
1709
1710 The specified settings file name must be fully qualified.
1711 The file must exist and be a valid machine XML settings file
1712 whose contents will be used to construct the machine object.
1713
1714 <result name="VBOX_E_FILE_ERROR">
1715 Settings file name invalid, not found or sharing violation.
1716 </result>
1717 </desc>
1718 <param name="settingsFile" type="wstring" dir="in">
1719 <desc>
1720 Name of the machine settings file.
1721 </desc>
1722 </param>
1723 <param name="machine" type="IMachine" dir="return">
1724 <desc>Opened machine object.</desc>
1725 </param>
1726 <note>
1727 <link to="IMachine::settingsModified"/> will return
1728 @c false for the created machine, until any of machine settings
1729 are changed.
1730 </note>
1731 </method>
1732
1733 <method name="registerMachine">
1734 <desc>
1735
1736 Registers the machine previously created using
1737 <link to="#createMachine"/> or opened using
1738 <link to="#openMachine"/> within this VirtualBox installation. After
1739 successful method invocation, the
1740 <link to="IMachineRegisteredEvent"/> event is fired.
1741
1742 <note>
1743 This method implicitly calls <link to="IMachine::saveSettings"/>
1744 to save all current machine settings before registering it.
1745 </note>
1746
1747 <result name="VBOX_E_OBJECT_NOT_FOUND">
1748 No matching virtual machine found.
1749 </result>
1750 <result name="VBOX_E_INVALID_OBJECT_STATE">
1751 Virtual machine was not created within this VirtualBox instance.
1752 </result>
1753
1754 </desc>
1755 <param name="machine" type="IMachine" dir="in"/>
1756 </method>
1757
1758 <method name="findMachine">
1759 <desc>
1760 Attempts to find a virtual machine given its name or UUID.
1761
1762 <note>Inaccessible machines cannot be found by name, only by UUID, because their name
1763 cannot safely be determined.</note>
1764
1765 <result name="VBOX_E_OBJECT_NOT_FOUND">
1766 Could not find registered machine matching @a nameOrId.
1767 </result>
1768
1769 </desc>
1770 <param name="nameOrId" type="wstring" dir="in">
1771 <desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>
1772 </param>
1773 <param name="machine" type="IMachine" dir="return">
1774 <desc>Machine object, if found.</desc>
1775 </param>
1776 </method>
1777
1778 <method name="createAppliance">
1779 <desc>
1780 Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1781 Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1782 machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1783 </desc>
1784 <param name="appliance" type="IAppliance" dir="return">
1785 <desc>New appliance.</desc>
1786 </param>
1787 </method>
1788
1789 <method name="createHardDisk">
1790 <desc>
1791 Creates a new base medium object that will use the given storage
1792 format and location for medium data.
1793
1794 The actual storage unit is not created by this method. In order to
1795 do it, and before you are able to attach the created medium to
1796 virtual machines, you must call one of the following methods to
1797 allocate a format-specific storage unit at the specified location:
1798 <ul>
1799 <li><link to="IMedium::createBaseStorage"/></li>
1800 <li><link to="IMedium::createDiffStorage"/></li>
1801 </ul>
1802
1803 Some medium attributes, such as <link to="IMedium::id"/>, may
1804 remain uninitialized until the medium storage unit is successfully
1805 created by one of the above methods.
1806
1807 After the storage unit is successfully created, it will be
1808 accessible through the <link to="#findMedium"/> method and can
1809 be found in the <link to="#hardDisks"/> array.
1810
1811 The list of all storage formats supported by this VirtualBox
1812 installation can be obtained using
1813 <link to="ISystemProperties::mediumFormats"/>. If the @a format
1814 attribute is empty or @c null then the default storage format
1815 specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1816 be used for creating a storage unit of the medium.
1817
1818 Note that the format of the location string is storage format specific.
1819 See <link to="IMedium::location"/> and IMedium for more details.
1820
1821 <result name="VBOX_E_OBJECT_NOT_FOUND">
1822 @a format identifier is invalid. See
1823 <link to="ISystemProperties::mediumFormats"/>.
1824 </result>
1825 <result name="VBOX_E_FILE_ERROR">
1826 @a location is a not valid file name (for file-based formats only).
1827 </result>
1828 </desc>
1829 <param name="format" type="wstring" dir="in">
1830 <desc>
1831 Identifier of the storage format to use for the new medium.
1832 </desc>
1833 </param>
1834 <param name="location" type="wstring" dir="in">
1835 <desc>
1836 Location of the storage unit for the new medium.
1837 </desc>
1838 </param>
1839 <param name="medium" type="IMedium" dir="return">
1840 <desc>Created medium object.</desc>
1841 </param>
1842 </method>
1843
1844 <method name="openMedium">
1845 <desc>
1846 Opens a medium from an existing storage location.
1847
1848 Once a medium has been opened, it can be passed to other VirtualBox
1849 methods, in particular to <link to="IMachine::attachDevice" />.
1850
1851 Depending on the given device type, the file at the storage location
1852 must be in one of the media formats understood by VirtualBox:
1853
1854 <ul>
1855 <li>With a "HardDisk" device type, the file must be a hard disk image
1856 in one of the formats supported by VirtualBox (see
1857 <link to="ISystemProperties::mediumFormats" />).
1858 After this method succeeds, if the medium is a base medium, it
1859 will be added to the <link to="#hardDisks"/> array attribute. </li>
1860 <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
1861 After this method succeeds, the medium will be added to the
1862 <link to="#DVDImages"/> array attribute.</li>
1863 <li>With a "Floppy" device type, the file must be an RAW floppy image.
1864 After this method succeeds, the medium will be added to the
1865 <link to="#floppyImages"/> array attribute.</li>
1866 </ul>
1867
1868 After having been opened, the medium can be found by the <link to="#findMedium"/>
1869 method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
1870
1871 The UUID of the newly opened medium will either be retrieved from the
1872 storage location, if the format supports it (e.g. for hard disk images),
1873 or a new UUID will be randomly generated (e.g. for ISO and RAW files).
1874 If for some reason you need to change the medium's UUID, use
1875 <link to="IMedium::setIDs" />.
1876
1877 If a differencing hard disk medium is to be opened by this method, the
1878 operation will succeed only if its parent medium and all ancestors,
1879 if any, are already known to this VirtualBox installation (for example,
1880 were opened by this method before).
1881
1882 This method attempts to guess the storage format of the specified medium
1883 by reading medium data at the specified location.
1884
1885 If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
1886 the image is opened for read/write access and must have according permissions,
1887 as VirtualBox may actually write status information into the disk's metadata
1888 sections.
1889
1890 Note that write access is required for all typical hard disk usage in VirtualBox,
1891 since VirtualBox may need to write metadata such as a UUID into the image.
1892 The only exception is opening a source image temporarily for copying and
1893 cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
1894 again soon.
1895
1896 The format of the location string is storage format specific. See
1897 <link to="IMedium::location"/> and IMedium for more details.
1898
1899 <result name="VBOX_E_FILE_ERROR">
1900 Invalid medium storage file location or could not find the medium
1901 at the specified location.
1902 </result>
1903 <result name="VBOX_E_IPRT_ERROR">
1904 Could not get medium storage format.
1905 </result>
1906 <result name="E_INVALIDARG">
1907 Invalid medium storage format.
1908 </result>
1909 <result name="VBOX_E_INVALID_OBJECT_STATE">
1910 Medium has already been added to a media registry.
1911 </result>
1912 </desc>
1913 <param name="location" type="wstring" dir="in">
1914 <desc>
1915 Location of the storage unit that contains medium data in one of
1916 the supported storage formats.
1917 </desc>
1918 </param>
1919 <param name="deviceType" type="DeviceType" dir="in">
1920 <desc>
1921 Must be one of "HardDisk", "DVD" or "Floppy".
1922 </desc>
1923 </param>
1924 <param name="accessMode" type="AccessMode" dir="in">
1925 <desc>Whether to open the image in read/write or read-only mode. For
1926 a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
1927 </param>
1928 <param name="forceNewUuid" type="boolean" dir="in">
1929 <desc>Allows the caller to request a completely new medium UUID for
1930 the image which is to be opened. Useful if one intends to open an exact
1931 copy of a previously opened image, as this would normally fail due to
1932 the duplicate UUID.</desc>
1933 </param>
1934 <param name="medium" type="IMedium" dir="return">
1935 <desc>Opened medium object.</desc>
1936 </param>
1937 </method>
1938
1939 <method name="findMedium">
1940 <desc>
1941 Returns a medium of the given type that uses the given fully qualified
1942 location or UUID to store medium data.
1943
1944 The given medium must be known to this VirtualBox installation, i.e.
1945 it must be previously created by <link to="#createHardDisk"/> or opened
1946 by <link to="#openMedium"/>.
1947
1948 The search is done by comparing the value of the @a location argument to
1949 the <link to="IMedium::location"/> and <link to="IMedium::id" />
1950 attributes of each known medium.
1951
1952 On case sensitive file systems, a case sensitive comparison is performed,
1953 otherwise the case of symbols in the file path is ignored.
1954
1955 <result name="VBOX_E_OBJECT_NOT_FOUND">
1956 No medium object matching @a location found.
1957 </result>
1958 </desc>
1959 <param name="location" type="wstring" dir="in">
1960 <desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>
1961 </param>
1962 <param name="type" type="DeviceType" dir="in">
1963 <desc>Device type (must be HardDisk, DVD or Floppy)</desc>
1964 </param>
1965 <param name="medium" type="IMedium" dir="return">
1966 <desc>Medium object, if found.</desc>
1967 </param>
1968 </method>
1969
1970 <method name="getGuestOSType">
1971 <desc>
1972 Returns an object describing the specified guest OS type.
1973
1974 The requested guest OS type is specified using a string which is a
1975 mnemonic identifier of the guest operating system, such as
1976 <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
1977 particular virtual machine can be read or set using the
1978 <link to="IMachine::OSTypeId"/> attribute.
1979
1980 The <link to="IVirtualBox::guestOSTypes"/> collection contains all
1981 available guest OS type objects. Each object has an
1982 <link to="IGuestOSType::id"/> attribute which contains an identifier of
1983 the guest OS this object describes.
1984
1985 <result name="E_INVALIDARG">
1986 @a id is not a valid Guest OS type.
1987 </result>
1988
1989 </desc>
1990 <param name="id" type="uuid" mod="string" dir="in">
1991 <desc>Guest OS type ID string.</desc>
1992 </param>
1993 <param name="type" type="IGuestOSType" dir="return">
1994 <desc>Guest OS type object.</desc>
1995 </param>
1996 </method>
1997
1998 <method name="createSharedFolder">
1999 <desc>
2000 Creates a new global shared folder by associating the given logical
2001 name with the given host path, adds it to the collection of shared
2002 folders and starts sharing it. Refer to the description of
2003 <link to="ISharedFolder"/> to read more about logical names.
2004 <note>
2005 In the current implementation, this operation is not
2006 implemented.
2007 </note>
2008 </desc>
2009 <param name="name" type="wstring" dir="in">
2010 <desc>Unique logical name of the shared folder.</desc>
2011 </param>
2012 <param name="hostPath" type="wstring" dir="in">
2013 <desc>Full path to the shared folder in the host file system.</desc>
2014 </param>
2015 <param name="writable" type="boolean" dir="in">
2016 <desc>Whether the share is writable or readonly</desc>
2017 </param>
2018 <param name="automount" type="boolean" dir="in">
2019 <desc>Whether the share gets automatically mounted by the guest
2020 or not.</desc>
2021 </param>
2022 </method>
2023
2024 <method name="removeSharedFolder">
2025 <desc>
2026 Removes the global shared folder with the given name previously
2027 created by <link to="#createSharedFolder"/> from the collection of
2028 shared folders and stops sharing it.
2029 <note>
2030 In the current implementation, this operation is not
2031 implemented.
2032 </note>
2033 </desc>
2034 <param name="name" type="wstring" dir="in">
2035 <desc>Logical name of the shared folder to remove.</desc>
2036 </param>
2037 </method>
2038
2039 <method name="getExtraDataKeys">
2040 <desc>
2041 Returns an array representing the global extra data keys which currently
2042 have values defined.
2043 </desc>
2044 <param name="value" type="wstring" dir="return" safearray="yes">
2045 <desc>Array of extra data keys.</desc>
2046 </param>
2047 </method>
2048
2049 <method name="getExtraData">
2050 <desc>
2051 Returns associated global extra data.
2052
2053 If the requested data @a key does not exist, this function will
2054 succeed and return an empty string in the @a value argument.
2055
2056 <result name="VBOX_E_FILE_ERROR">
2057 Settings file not accessible.
2058 </result>
2059 <result name="VBOX_E_XML_ERROR">
2060 Could not parse the settings file.
2061 </result>
2062
2063 </desc>
2064 <param name="key" type="wstring" dir="in">
2065 <desc>Name of the data key to get.</desc>
2066 </param>
2067 <param name="value" type="wstring" dir="return">
2068 <desc>Value of the requested data key.</desc>
2069 </param>
2070 </method>
2071
2072 <method name="setExtraData">
2073 <desc>
2074 Sets associated global extra data.
2075
2076 If you pass @c null or empty string as a key @a value, the given @a key
2077 will be deleted.
2078
2079 <note>
2080 Before performing the actual data change, this method will ask all
2081 registered event listener using the
2082 <link to="IExtraDataCanChangeEvent"/>
2083 notification for a permission. If one of the listeners refuses the
2084 new value, the change will not be performed.
2085 </note>
2086 <note>
2087 On success, the
2088 <link to="IExtraDataChangedEvent"/> notification
2089 is called to inform all registered listeners about a successful data
2090 change.
2091 </note>
2092
2093 <result name="VBOX_E_FILE_ERROR">
2094 Settings file not accessible.
2095 </result>
2096 <result name="VBOX_E_XML_ERROR">
2097 Could not parse the settings file.
2098 </result>
2099 <result name="E_ACCESSDENIED">
2100 Modification request refused.
2101 </result>
2102
2103 </desc>
2104 <param name="key" type="wstring" dir="in">
2105 <desc>Name of the data key to set.</desc>
2106 </param>
2107 <param name="value" type="wstring" dir="in">
2108 <desc>Value to assign to the key.</desc>
2109 </param>
2110 </method>
2111
2112 <!--method name="createDHCPServerForInterface">
2113 <desc>
2114 Creates a dhcp server settings to be used for the given interface
2115 <result name="E_INVALIDARG">
2116 Host network interface @a name already exists.
2117 </result>
2118 </desc>
2119 <param name="interface" type="IHostNetworkInterface" dir="in">
2120 <desc>Network Interface</desc>
2121 </param>
2122 <param name="server" type="IDHCPServer" dir="out">
2123 <desc>Dhcp server settings</desc>
2124 </param>
2125 </method-->
2126
2127 <method name="createDHCPServer">
2128 <desc>
2129 Creates a dhcp server settings to be used for the given internal network name
2130 <result name="E_INVALIDARG">
2131 Host network interface @a name already exists.
2132 </result>
2133 </desc>
2134 <param name="name" type="wstring" dir="in">
2135 <desc>server name</desc>
2136 </param>
2137 <param name="server" type="IDHCPServer" dir="return">
2138 <desc>Dhcp server settings</desc>
2139 </param>
2140 </method>
2141
2142 <method name="findDHCPServerByNetworkName">
2143 <desc>
2144 Searches a dhcp server settings to be used for the given internal network name
2145 <result name="E_INVALIDARG">
2146 Host network interface @a name already exists.
2147 </result>
2148
2149 </desc>
2150 <param name="name" type="wstring" dir="in">
2151 <desc>server name</desc>
2152 </param>
2153 <param name="server" type="IDHCPServer" dir="return">
2154 <desc>Dhcp server settings</desc>
2155 </param>
2156 </method>
2157
2158 <!--method name="findDHCPServerForInterface">
2159 <desc>
2160 Searches a dhcp server settings to be used for the given interface
2161 <result name="E_INVALIDARG">
2162 Host network interface @a name already exists.
2163 </result>
2164 </desc>
2165 <param name="interface" type="IHostNetworkInterface" dir="in">
2166 <desc>Network Interface</desc>
2167 </param>
2168 <param name="server" type="IDHCPServer" dir="out">
2169 <desc>Dhcp server settings</desc>
2170 </param>
2171 </method-->
2172
2173 <method name="removeDHCPServer">
2174 <desc>
2175 Removes the dhcp server settings
2176 <result name="E_INVALIDARG">
2177 Host network interface @a name already exists.
2178 </result>
2179 </desc>
2180 <param name="server" type="IDHCPServer" dir="in">
2181 <desc>Dhcp server settings to be removed</desc>
2182 </param>
2183 </method>
2184
2185
2186 <method name="checkFirmwarePresent">
2187 <desc>
2188 Check if this VirtualBox installation has a firmware
2189 of the given type available, either system-wide or per-user.
2190 Optionally, this may return a hint where this firmware can be
2191 downloaded from.
2192 </desc>
2193 <param name="firmwareType" type="FirmwareType" dir="in">
2194 <desc>
2195 Type of firmware to check.
2196 </desc>
2197 </param>
2198 <param name="version" type="wstring" dir="in">
2199 <desc>Expected version number, usually empty string (presently ignored).</desc>
2200 </param>
2201
2202 <param name="url" type="wstring" dir="out">
2203 <desc>
2204 Suggested URL to download this firmware from.
2205 </desc>
2206 </param>
2207
2208 <param name="file" type="wstring" dir="out">
2209 <desc>
2210 Filename of firmware, only valid if result == TRUE.
2211 </desc>
2212 </param>
2213
2214 <param name="result" type="boolean" dir="return">
2215 <desc>If firmware of this type and version is available.</desc>
2216 </param>
2217 </method>
2218
2219 </interface>
2220
2221 <!--
2222 // IVFSExplorer
2223 /////////////////////////////////////////////////////////////////////////
2224 -->
2225
2226 <enum
2227 name="VFSType"
2228 uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
2229 >
2230 <desc>
2231 Virtual file systems supported by VFSExplorer.
2232 </desc>
2233
2234 <const name="File" value="1" />
2235 <const name="Cloud" value="2" />
2236 <const name="S3" value="3" />
2237 <const name="WebDav" value="4" />
2238 </enum>
2239
2240 <enum
2241 name="VFSFileType"
2242 uuid="714333cd-44e2-415f-a245-d378fa9b1242"
2243 >
2244 <desc>
2245 File types known by VFSExplorer.
2246 </desc>
2247
2248 <const name="Unknown" value="1" />
2249 <const name="Fifo" value="2" />
2250 <const name="DevChar" value="3" />
2251 <const name="Directory" value="4" />
2252 <const name="DevBlock" value="5" />
2253 <const name="File" value="6" />
2254 <const name="SymLink" value="7" />
2255 <const name="Socket" value="8" />
2256 <const name="WhiteOut" value="9" />
2257 </enum>
2258
2259 <interface
2260 name="IVFSExplorer" extends="$unknown"
2261 uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"
2262 wsmap="managed"
2263 >
2264 <desc>
2265 The VFSExplorer interface unifies access to different file system
2266 types. This includes local file systems as well remote file systems like
2267 S3. For a list of supported types see <link to="VFSType" />.
2268 An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
2269 </desc>
2270
2271 <attribute name="path" type="wstring" readonly="yes">
2272 <desc>Returns the current path in the virtual file system.</desc>
2273 </attribute>
2274
2275 <attribute name="type" type="VFSType" readonly="yes">
2276 <desc>Returns the file system type which is currently in use.</desc>
2277 </attribute>
2278
2279 <method name="update">
2280 <desc>Updates the internal list of files/directories from the
2281 current directory level. Use <link to="#entryList" /> to get the full list
2282 after a call to this method.</desc>
2283
2284 <param name="aProgress" type="IProgress" dir="return">
2285 <desc>Progress object to track the operation completion.</desc>
2286 </param>
2287 </method>
2288
2289 <method name="cd">
2290 <desc>Change the current directory level.</desc>
2291
2292 <param name="aDir" type="wstring" dir="in">
2293 <desc>The name of the directory to go in.</desc>
2294 </param>
2295
2296 <param name="aProgress" type="IProgress" dir="return">
2297 <desc>Progress object to track the operation completion.</desc>
2298 </param>
2299 </method>
2300
2301 <method name="cdUp">
2302 <desc>Go one directory upwards from the current directory level.</desc>
2303
2304 <param name="aProgress" type="IProgress" dir="return">
2305 <desc>Progress object to track the operation completion.</desc>
2306 </param>
2307 </method>
2308
2309 <method name="entryList">
2310 <desc>Returns a list of files/directories after a call to <link
2311 to="#update" />. The user is responsible for keeping this internal
2312 list up do date.</desc>
2313
2314 <param name="aNames" type="wstring" safearray="yes" dir="out">
2315 <desc>The list of names for the entries.</desc>
2316 </param>
2317
2318 <param name="aTypes" type="unsigned long" safearray="yes" dir="out">
2319 <desc>The list of types for the entries.</desc>
2320 </param>
2321
2322 <param name="aSizes" type="unsigned long" safearray="yes" dir="out">
2323 <desc>The list of sizes (in bytes) for the entries.</desc>
2324 </param>
2325
2326 <param name="aModes" type="unsigned long" safearray="yes" dir="out">
2327 <desc>The list of file modes (in octal form) for the entries.</desc>
2328 </param>
2329 </method>
2330
2331 <method name="exists">
2332 <desc>Checks if the given file list exists in the current directory
2333 level.</desc>
2334
2335 <param name="aNames" type="wstring" safearray="yes" dir="in">
2336 <desc>The names to check.</desc>
2337 </param>
2338
2339 <param name="aExists" type="wstring" safearray="yes" dir="return">
2340 <desc>The names which exist.</desc>
2341 </param>
2342 </method>
2343
2344 <method name="remove">
2345 <desc>Deletes the given files in the current directory level.</desc>
2346
2347 <param name="aNames" type="wstring" safearray="yes" dir="in">
2348 <desc>The names to remove.</desc>
2349 </param>
2350
2351 <param name="aProgress" type="IProgress" dir="return">
2352 <desc>Progress object to track the operation completion.</desc>
2353 </param>
2354 </method>
2355
2356 </interface>
2357
2358 <enum
2359 name="ImportOptions" extends="$unknown"
2360 uuid="0a981523-3b20-4004-8ee3-dfd322202ace"
2361 >
2362
2363 <desc>
2364 Import options, used with <link to="IAppliance::importMachines" />.
2365 </desc>
2366
2367 <const name="KeepAllMACs" value="1">
2368 <desc>Don't generate new MAC addresses of the attached network adapters.</desc>
2369 </const>
2370 <const name="KeepNATMACs" value="2">
2371 <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
2372 </const>
2373
2374 </enum>
2375
2376
2377 <!--
2378 // IAppliance
2379 /////////////////////////////////////////////////////////////////////////
2380 -->
2381
2382 <interface
2383 name="IAppliance" extends="$unknown"
2384 uuid="3059cf9e-25c7-4f0b-9fa5-3c42e441670b"
2385 wsmap="managed"
2386 >
2387 <desc>
2388 Represents a platform-independent appliance in OVF format. An instance of this is returned
2389 by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
2390 virtual machines within an appliance with VirtualBox.
2391
2392 The OVF standard suggests two different physical file formats:
2393
2394 <ol>
2395 <li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
2396 file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
2397 this descriptor file references other files such as disk images, as OVF appliances typically
2398 do, those additional files must be in the same directory as the descriptor file.</li>
2399
2400 <li>If the appliance is distributed as a single file, it must be in TAR format and have the
2401 <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
2402 files and optionally other files.
2403
2404 At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
2405 be added with a later version.</li>
2406 </ol>
2407
2408 <b>Importing</b> an OVF appliance into VirtualBox as instances of
2409 <link to="IMachine" /> involves the following sequence of API calls:
2410
2411 <ol>
2412 <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
2413 </li>
2414
2415 <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
2416 would like to import. So long as this file is syntactically valid, this will succeed
2417 and fill the appliance object with the parsed data from the OVF file.
2418 </li>
2419
2420 <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
2421 contents of the IAppliance attributes accordingly. These can be inspected by a
2422 VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
2423 user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
2424 instances of <link to="IVirtualSystemDescription" /> which represent the virtual
2425 systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
2426 by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
2427 The GUI can then give the user the option to confirm and/or change these suggestions.
2428 </li>
2429
2430 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2431 virtual system (machine) to override the suggestions made by the <link to="#interpret" /> routine.
2432 </li>
2433
2434 <li>Finally, call <link to="#importMachines" /> to create virtual machines in
2435 VirtualBox as instances of <link to="IMachine" /> that match the information in the
2436 virtual system descriptions. After this call succeeded, the UUIDs of the machines created
2437 can be found in the <link to="#machines" /> array attribute.
2438 </li>
2439 </ol>
2440
2441 <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
2442
2443 <ol>
2444 <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
2445 an empty IAppliance object.
2446 </li>
2447
2448 <li>For each machine you would like to export, call <link to="IMachine::export" />
2449 with the IAppliance object you just created. Each such call creates one instance of
2450 <link to="IVirtualSystemDescription" /> inside the appliance.
2451 </li>
2452
2453 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
2454 virtual system (machine) to override the suggestions made by the <link to="IMachine::export"/> routine.
2455 </li>
2456
2457 <li>Finally, call <link to="#write" /> with a path specification to have the OVF
2458 file written.</li>
2459 </ol>
2460
2461 </desc>
2462
2463 <attribute name="path" type="wstring" readonly="yes">
2464 <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
2465 the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
2466 <link to="#write" /> (for export).
2467 This attribute is empty until one of these methods has been called.
2468 </desc>
2469 </attribute>
2470
2471 <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
2472 <desc>
2473 Array of virtual disk definitions. One such description exists for each
2474 disk definition in the OVF; each string array item represents one such piece of
2475 disk information, with the information fields separated by tab (\\t) characters.
2476
2477 The caller should be prepared for additional fields being appended to
2478 this string in future versions of VirtualBox and therefore check for
2479 the number of tabs in the strings returned.
2480
2481 In the current version, the following eight fields are returned per string
2482 in the array:
2483
2484 <ol>
2485 <li>Disk ID (unique string identifier given to disk)</li>
2486
2487 <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
2488
2489 <li>Populated size (optional unsigned integer indicating the current size of the
2490 disk; can be approximate; -1 if unspecified)</li>
2491
2492 <li>Format (string identifying the disk format, typically
2493 "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
2494
2495 <li>Reference (where to find the disk image, typically a file name; if empty,
2496 then the disk should be created on import)</li>
2497
2498 <li>Image size (optional unsigned integer indicating the size of the image,
2499 which need not necessarily be the same as the values specified above, since
2500 the image may be compressed or sparse; -1 if not specified)</li>
2501
2502 <li>Chunk size (optional unsigned integer if the image is split into chunks;
2503 presently unsupported and always -1)</li>
2504
2505 <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
2506 </ol>
2507 </desc>
2508 </attribute>
2509
2510 <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
2511 <desc> Array of virtual system descriptions. One such description is created
2512 for each virtual system (machine) found in the OVF.
2513 This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
2514 (for export) has been called.
2515 </desc>
2516 </attribute>
2517
2518 <attribute name="machines" type="wstring" readonly="yes" safearray="yes">
2519 <desc>
2520 Contains the UUIDs of the machines created from the information in this appliances. This is only
2521 relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
2522 succeeded.
2523 </desc>
2524 </attribute>
2525
2526 <method name="read">
2527 <desc>
2528 Reads an OVF file into the appliance object.
2529
2530 This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
2531 mere fact that this method returns successfully does not mean that VirtualBox supports all
2532 features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
2533 </desc>
2534 <param name="file" type="wstring" dir="in">
2535 <desc>
2536 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2537 on whether the appliance is distributed as a set of files or as a single file, respectively).
2538 </desc>
2539 </param>
2540 <param name="aProgress" type="IProgress" dir="return">
2541 <desc>Progress object to track the operation completion.</desc>
2542 </param>
2543 </method>
2544
2545 <method name="interpret">
2546 <desc>
2547 Interprets the OVF data that was read when the appliance was constructed. After
2548 calling this method, one can inspect the
2549 <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
2550 one <link to="IVirtualSystemDescription" /> for each virtual machine found in
2551 the appliance.
2552
2553 Calling this method is the second step of importing an appliance into VirtualBox;
2554 see <link to="IAppliance" /> for an overview.
2555
2556 After calling this method, one should call <link to="#getWarnings" /> to find out
2557 if problems were encountered during the processing which might later lead to
2558 errors.
2559 </desc>
2560 </method>
2561
2562 <method name="importMachines">
2563 <desc>
2564 Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
2565 and other interfaces that match the information contained in the appliance as
2566 closely as possible, as represented by the import instructions in the
2567 <link to="#virtualSystemDescriptions" /> array.
2568
2569 Calling this method is the final step of importing an appliance into VirtualBox;
2570 see <link to="IAppliance" /> for an overview.
2571
2572 Since importing the appliance will most probably involve copying and converting
2573 disk images, which can take a long time, this method operates asynchronously and
2574 returns an IProgress object to allow the caller to monitor the progress.
2575
2576 After the import succeeded, the UUIDs of the IMachine instances created can be
2577 retrieved from the <link to="#machines" /> array attribute.
2578 </desc>
2579
2580 <param name="options" type="ImportOptions" dir="in" safearray="yes">
2581 <desc>Options for the importing operation.</desc>
2582 </param>
2583
2584 <param name="aProgress" type="IProgress" dir="return">
2585 <desc>Progress object to track the operation completion.</desc>
2586 </param>
2587 </method>
2588
2589 <method name="createVFSExplorer">
2590 <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
2591
2592 <param name="aUri" type="wstring" dir="in">
2593 <desc>The URI describing the file system to use.</desc>
2594 </param>
2595
2596 <param name="aExplorer" type="IVFSExplorer" dir="return">
2597 <desc></desc>
2598 </param>
2599 </method>
2600
2601 <method name="write">
2602 <desc>
2603 Writes the contents of the appliance exports into a new OVF file.
2604
2605 Calling this method is the final step of exporting an appliance from VirtualBox;
2606 see <link to="IAppliance" /> for an overview.
2607
2608 Since exporting the appliance will most probably involve copying and converting
2609 disk images, which can take a long time, this method operates asynchronously and
2610 returns an IProgress object to allow the caller to monitor the progress.
2611 </desc>
2612 <param name="format" type="wstring" dir="in">
2613 <desc>
2614 Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
2615 future versions of VirtualBox may support additional formats.
2616 </desc>
2617 </param>
2618 <param name="manifest" type="boolean" dir="in">
2619 <desc>
2620 Indicate if the optional manifest file (.mf) should be written. The manifest file
2621 is used for integrity checks prior import.
2622 </desc>
2623 </param>
2624 <param name="path" type="wstring" dir="in">
2625 <desc>
2626 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
2627 on whether the appliance is distributed as a set of files or as a single file, respectively).
2628 </desc>
2629 </param>
2630 <param name="progress" type="IProgress" dir="return">
2631 <desc>Progress object to track the operation completion.</desc>
2632 </param>
2633 </method>
2634
2635 <method name="getWarnings">
2636 <desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>
2637
2638 <param name="aWarnings" type="wstring" dir="return" safearray="yes">
2639 <desc></desc>
2640 </param>
2641 </method>
2642
2643 </interface>
2644
2645 <enum
2646 name="VirtualSystemDescriptionType"
2647 uuid="303c0900-a746-4612-8c67-79003e91f459"
2648 >
2649 <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
2650 a configuration value.</desc>
2651
2652 <const name="Ignore" value="1" />
2653 <const name="OS" value="2" />
2654 <const name="Name" value="3" />
2655 <const name="Product" value="4" />
2656 <const name="Vendor" value="5" />
2657 <const name="Version" value="6" />
2658 <const name="ProductUrl" value="7" />
2659 <const name="VendorUrl" value="8" />
2660 <const name="Description" value="9" />
2661 <const name="License" value="10" />
2662 <const name="Miscellaneous" value="11" />
2663 <const name="CPU" value="12" />
2664 <const name="Memory" value="13" />
2665 <const name="HardDiskControllerIDE" value="14" />
2666 <const name="HardDiskControllerSATA" value="15" />
2667 <const name="HardDiskControllerSCSI" value="16" />
2668 <const name="HardDiskControllerSAS" value="17" />
2669 <const name="HardDiskImage" value="18" />
2670 <const name="Floppy" value="19" />
2671 <const name="CDROM" value="20" />
2672 <const name="NetworkAdapter" value="21" />
2673 <const name="USBController" value="22" />
2674 <const name="SoundCard" value="23" />
2675 <const name="SettingsFile" value="24">
2676 <desc>Not used/implemented right now, will be added later in 4.1.x.</desc>
2677 </const>
2678 </enum>
2679
2680 <enum
2681 name="VirtualSystemDescriptionValueType"
2682 uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
2683 >
2684 <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
2685 type to fetch.</desc>
2686
2687 <const name="Reference" value="1" />
2688 <const name="Original" value="2" />
2689 <const name="Auto" value="3" />
2690 <const name="ExtraConfig" value="4" />
2691
2692 </enum>
2693
2694 <interface
2695 name="IVirtualSystemDescription" extends="$unknown"
2696 uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
2697 wsmap="managed"
2698 >
2699
2700 <desc>Represents one virtual system (machine) in an appliance. This interface is used in
2701 the <link to="IAppliance::virtualSystemDescriptions" /> array. After
2702 <link to="IAppliance::interpret" /> has been called, that array contains information
2703 about how the virtual systems described in the OVF should best be imported into
2704 VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
2705 import an OVF into VirtualBox.
2706 </desc>
2707
2708 <attribute name="count" type="unsigned long" readonly="yes">
2709 <desc>Return the number of virtual system description entries.</desc>
2710 </attribute>
2711
2712 <method name="getDescription">
2713 <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
2714 items with the same indices correspond and jointly represent an import instruction for VirtualBox.
2715
2716 The list below identifies the value sets that are possible depending on the
2717 <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
2718 the array item with the same index in @a aOvfValues[] will contain the original value as contained
2719 in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
2720 will contain a suggested value to be used for VirtualBox. Depending on the description type,
2721 the @a aExtraConfigValues[] array item may also be used.
2722
2723 <ul>
2724 <li>
2725 "OS": the guest operating system type. There must be exactly one such array item on import. The
2726 corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
2727 This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
2728 item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
2729 </li>
2730 <li>
2731 "Name": the name to give to the new virtual machine. There can be at most one such array item;
2732 if none is present on import, then an automatic name will be created from the operating system
2733 type. The corresponding item im @a aOvfValues[] will contain the suggested virtual machine name
2734 from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
2735 <link to="IMachine" /> name that does not exist yet.
2736 </li>
2737 <li>
2738 "Description": an arbitrary description.
2739 </li>
2740 <li>
2741 "License": the EULA section from the OVF, if present. It is the responsibility of the calling
2742 code to display such a license for agreement; the Main API does not enforce any such policy.
2743 </li>
2744 <li>
2745 Miscellaneous: reserved for future use.
2746 </li>
2747 <li>
2748 "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
2749 </li>
2750 <li>
2751 "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
2752 is present on import, then VirtualBox will set a meaningful default based on the operating system
2753 type.
2754 </li>
2755 <li>
2756 "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
2757 An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
2758 the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
2759 writes into the OVF.
2760 The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
2761 type can use to specify which hard disk controller a virtual disk should be connected to.
2762 Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
2763 in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
2764 its virtual machines supports four channels (primary master, primary slave, secondary master,
2765 secondary slave) and thus maps to two IDE controllers in the OVF sense.
2766 </li>
2767 <li>
2768 "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
2769 has no value in @a aOvfValues[] or @a aVBoxValues[].
2770 The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
2771 </li>
2772 <li>
2773 "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
2774 The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
2775 "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
2776 whereas VirtualBox considers it a class of storage controllers of its own; see
2777 <link to="StorageControllerType" />).
2778 The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
2779 </li>
2780 <li>
2781 "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
2782 arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
2783
2784 The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
2785 a path since the image file should be in the same location as the OVF file itself), whereas the
2786 item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
2787 hard disk image. This means that on import the image will be copied and converted from the
2788 "ovf" location to the "vbox" location; on export, this will be handled the other way round.
2789
2790 The matching item in the @a aExtraConfigValues[] array must contain a string of the following
2791 format: "controller=&lt;index&gt;;channel=&lt;c&gt;"
2792 In this string, &lt;index&gt; must be an integer specifying the hard disk controller to connect
2793 the image to. That number must be the index of an array item with one of the hard disk controller
2794 types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
2795 In addition, &lt;c&gt; must specify the channel to use on that controller. For IDE controllers,
2796 this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
2797 before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
2798 no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
2799 </li>
2800 <li>
2801 "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
2802 attachment information as with "HardDiskImage" items.
2803 </li>
2804 <li>
2805 "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
2806 attachment information as with "HardDiskImage" items.
2807 </li>
2808 <li>
2809 "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
2810 for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
2811 of the "type=&lt;X&gt;" format, where &lt;X&gt; must be either "NAT" or "Bridged".
2812 </li>
2813 <li>
2814 "USBController": a USB controller. There can be at most one such item. If and only if such an
2815 item ispresent, USB support will be enabled for the new virtual machine.
2816 </li>
2817 <li>
2818 "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
2819 present, sound support will be enabled for the new virtual machine. Note that the virtual
2820 machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
2821 may be different from the virtual soundcard expected by the appliance.
2822 </li>
2823 </ul>
2824
2825 </desc>
2826
2827 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
2828 <desc></desc>
2829 </param>
2830
2831 <param name="aRefs" type="wstring" dir="out" safearray="yes">
2832 <desc></desc>
2833 </param>
2834
2835 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
2836 <desc></desc>
2837 </param>
2838
2839 <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
2840 <desc></desc>
2841 </param>
2842
2843 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
2844 <desc></desc>
2845 </param>
2846
2847 </method>
2848
2849 <method name="getDescriptionByType">
2850 <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
2851 should be returned.</desc>
2852
2853 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
2854 <desc></desc>
2855 </param>
2856
2857 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
2858 <desc></desc>
2859 </param>
2860
2861 <param name="aRefs" type="wstring" dir="out" safearray="yes">
2862 <desc></desc>
2863 </param>
2864
2865 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
2866 <desc></desc>
2867 </param>
2868
2869 <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
2870 <desc></desc>
2871 </param>
2872
2873 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
2874 <desc></desc>
2875 </param>
2876
2877 </method>
2878
2879 <method name="getValuesByType">
2880 <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
2881 value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
2882 values.</desc>
2883
2884 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
2885 <desc></desc>
2886 </param>
2887
2888 <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
2889 <desc></desc>
2890 </param>
2891
2892 <param name="aValues" type="wstring" dir="return" safearray="yes">
2893 <desc></desc>
2894 </param>
2895
2896 </method>
2897
2898 <method name="setFinalValues">
2899 <desc>
2900 This method allows the appliance's user to change the configuration for the virtual
2901 system descriptions. For each array item returned from <link to="#getDescription" />,
2902 you must pass in one boolean value and one configuration value.
2903
2904 Each item in the boolean array determines whether the particular configuration item
2905 should be enabled.
2906 You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
2907 HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
2908 and SoundCard.
2909
2910 For the "vbox" and "extra configuration" values, if you pass in the same arrays
2911 as returned in the aVBoxValues and aExtraConfigValues arrays from <link to="#getDescription"/>,
2912 the configuration remains unchanged. Please see the documentation for <link to="#getDescription"/>
2913 for valid configuration values for the individual array item types. If the
2914 corresponding item in the aEnabled array is @c false, the configuration value is ignored.
2915 </desc>
2916
2917 <param name="aEnabled" type="boolean" dir="in" safearray="yes">
2918 <desc></desc>
2919 </param>
2920
2921 <param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
2922 <desc></desc>
2923 </param>
2924
2925 <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
2926 <desc></desc>
2927 </param>
2928 </method>
2929
2930 <method name="addDescription">
2931 <desc>
2932 This method adds an additional description entry to the stack of already
2933 available descriptions for this virtual system. This is handy for writing
2934 values which aren't directly supported by VirtualBox. One example would
2935 be the License type of <link to="VirtualSystemDescriptionType" />.
2936 </desc>
2937
2938 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
2939 <desc></desc>
2940 </param>
2941
2942 <param name="aVBoxValue" type="wstring" dir="in">
2943 <desc></desc>
2944 </param>
2945
2946 <param name="aExtraConfigValue" type="wstring" dir="in">
2947 <desc></desc>
2948 </param>
2949 </method>
2950 </interface>
2951
2952
2953 <!--
2954 // IMachine
2955 /////////////////////////////////////////////////////////////////////////
2956 -->
2957
2958 <interface
2959 name="IInternalMachineControl" extends="$unknown"
2960 uuid="2087906d-bb92-43a0-8014-4cab009e4888"
2961 internal="yes"
2962 wsmap="suppress"
2963 >
2964 <method name="setRemoveSavedStateFile">
2965 <desc>
2966 Updates the flag whether the saved state file is removed on a
2967 machine state change from Saved to PoweredOff.
2968 </desc>
2969 <param name="aRemove" type="boolean" dir="in"/>
2970 </method>
2971
2972 <method name="updateState">
2973 <desc>
2974 Updates the VM state.
2975 <note>
2976 This operation will also update the settings file with the correct
2977 information about the saved state file and delete this file from disk
2978 when appropriate.
2979 </note>
2980 </desc>
2981 <param name="state" type="MachineState" dir="in"/>
2982 </method>
2983
2984 <method name="getIPCId">
2985 <param name="id" type="wstring" dir="return"/>
2986 </method>
2987
2988 <method name="beginPowerUp">
2989 <desc>
2990 Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
2991 gives it the progress object that should be part of any pending
2992 <link to="IMachine::launchVMProcess"/> operations. The progress
2993 object may be called back to reflect an early cancelation, so some care
2994 have to be taken with respect to any cancelation callbacks. The console
2995 object will call <link to="IInternalMachineControl::endPowerUp"/>
2996 to signal the completion of the progress object.
2997 </desc>
2998 <param name="aProgress" type="IProgress" dir="in" />
2999 </method>
3000
3001 <method name="endPowerUp">
3002 <desc>
3003 Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
3004 This method may query status information from the progress object it
3005 received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
3006 it over to any in-progress <link to="IMachine::launchVMProcess"/>
3007 call in order to complete that progress object.
3008 </desc>
3009 <param name="result" type="long" dir="in"/>
3010 </method>
3011
3012 <method name="beginPoweringDown">
3013 <desc>
3014 Called by the VM process to inform the server it wants to
3015 stop the VM execution and power down.
3016 </desc>
3017 <param name="progress" type="IProgress" dir="out">
3018 <desc>
3019 Progress object created by VBoxSVC to wait until
3020 the VM is powered down.
3021 </desc>
3022 </param>
3023 </method>
3024
3025 <method name="endPoweringDown">
3026 <desc>
3027 Called by the VM process to inform the server that powering
3028 down previously requested by #beginPoweringDown is either
3029 successfully finished or there was a failure.
3030
3031 <result name="VBOX_E_FILE_ERROR">
3032 Settings file not accessible.
3033 </result>
3034 <result name="VBOX_E_XML_ERROR">
3035 Could not parse the settings file.
3036 </result>
3037
3038 </desc>
3039
3040 <param name="result" type="long" dir="in">
3041 <desc>@c S_OK to indicate success.
3042 </desc>
3043 </param>
3044 <param name="errMsg" type="wstring" dir="in">
3045 <desc>@c human readable error message in case of failure.
3046 </desc>
3047 </param>
3048 </method>
3049
3050 <method name="runUSBDeviceFilters">
3051 <desc>
3052 Asks the server to run USB devices filters of the associated
3053 machine against the given USB device and tell if there is
3054 a match.
3055 <note>
3056 Intended to be used only for remote USB devices. Local
3057 ones don't require to call this method (this is done
3058 implicitly by the Host and USBProxyService).
3059 </note>
3060 </desc>
3061 <param name="device" type="IUSBDevice" dir="in"/>
3062 <param name="matched" type="boolean" dir="out"/>
3063 <param name="maskedInterfaces" type="unsigned long" dir="out"/>
3064 </method>
3065
3066 <method name="captureUSBDevice">
3067 <desc>
3068 Requests a capture of the given host USB device.
3069 When the request is completed, the VM process will
3070 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3071 notification.
3072 </desc>
3073 <param name="id" type="uuid" mod="string" dir="in"/>
3074 </method>
3075
3076 <method name="detachUSBDevice">
3077 <desc>
3078 Notification that a VM is going to detach (@a done = @c false) or has
3079 already detached (@a done = @c true) the given USB device.
3080 When the @a done = @c true request is completed, the VM process will
3081 get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3082 notification.
3083 <note>
3084 In the @a done = @c true case, the server must run its own filters
3085 and filters of all VMs but this one on the detached device
3086 as if it were just attached to the host computer.
3087 </note>
3088 </desc>
3089 <param name="id" type="uuid" mod="string" dir="in"/>
3090 <param name="done" type="boolean" dir="in"/>
3091 </method>
3092
3093 <method name="autoCaptureUSBDevices">
3094 <desc>
3095 Requests a capture all matching USB devices attached to the host.
3096 When the request is completed, the VM process will
3097 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3098 notification per every captured device.
3099 </desc>
3100 </method>
3101
3102 <method name="detachAllUSBDevices">
3103 <desc>
3104 Notification that a VM that is being powered down. The done
3105 parameter indicates whether which stage of the power down
3106 we're at. When @a done = @c false the VM is announcing its
3107 intentions, while when @a done = @c true the VM is reporting
3108 what it has done.
3109 <note>
3110 In the @a done = @c true case, the server must run its own filters
3111 and filters of all VMs but this one on all detach devices as
3112 if they were just attached to the host computer.
3113 </note>
3114 </desc>
3115 <param name="done" type="boolean" dir="in"/>
3116 </method>
3117
3118 <method name="onSessionEnd">
3119 <desc>
3120 Triggered by the given session object when the session is about
3121 to close normally.
3122 </desc>
3123 <param name="session" type="ISession" dir="in">
3124 <desc>Session that is being closed</desc>
3125 </param>
3126 <param name="progress" type="IProgress" dir="return">
3127 <desc>
3128 Used to wait until the corresponding machine is actually
3129 dissociated from the given session on the server.
3130 Returned only when this session is a direct one.
3131 </desc>
3132 </param>
3133 </method>
3134
3135 <method name="beginSavingState">
3136 <desc>
3137 Called by the VM process to inform the server it wants to
3138 save the current state and stop the VM execution.
3139 </desc>
3140 <param name="progress" type="IProgress" dir="out">
3141 <desc>
3142 Progress object created by VBoxSVC to wait until
3143 the state is saved.
3144 </desc>
3145 </param>
3146 <param name="stateFilePath" type="wstring" dir="out">
3147 <desc>
3148 File path the VM process must save the execution state to.
3149 </desc>
3150 </param>
3151 </method>
3152
3153 <method name="endSavingState">
3154 <desc>
3155 Called by the VM process to inform the server that saving
3156 the state previously requested by #beginSavingState is either
3157 successfully finished or there was a failure.
3158
3159 <result name="VBOX_E_FILE_ERROR">
3160 Settings file not accessible.
3161 </result>
3162 <result name="VBOX_E_XML_ERROR">
3163 Could not parse the settings file.
3164 </result>
3165
3166 </desc>
3167
3168 <param name="result" type="long" dir="in">
3169 <desc>@c S_OK to indicate success.
3170 </desc>
3171 </param>
3172 <param name="errMsg" type="wstring" dir="in">
3173 <desc>@c human readable error message in case of failure.
3174 </desc>
3175 </param>
3176 </method>
3177
3178 <method name="adoptSavedState">
3179 <desc>
3180 Gets called by <link to="IConsole::adoptSavedState"/>.
3181 <result name="VBOX_E_FILE_ERROR">
3182 Invalid saved state file path.
3183 </result>
3184 </desc>
3185 <param name="savedStateFile" type="wstring" dir="in">
3186 <desc>Path to the saved state file to adopt.</desc>
3187 </param>
3188 </method>
3189
3190 <method name="beginTakingSnapshot">
3191 <desc>
3192 Called from the VM process to request from the server to perform the
3193 server-side actions of creating a snapshot (creating differencing images
3194 and the snapshot object).
3195
3196 <result name="VBOX_E_FILE_ERROR">
3197 Settings file not accessible.
3198 </result>
3199 <result name="VBOX_E_XML_ERROR">
3200 Could not parse the settings file.
3201 </result>
3202 </desc>
3203 <param name="initiator" type="IConsole" dir="in">
3204 <desc>The console object that initiated this call.</desc>
3205 </param>
3206 <param name="name" type="wstring" dir="in">
3207 <desc>Snapshot name.</desc>
3208 </param>
3209 <param name="description" type="wstring" dir="in">
3210 <desc>Snapshot description.</desc>
3211 </param>
3212 <param name="consoleProgress" type="IProgress" dir="in">
3213 <desc>
3214 Progress object created by the VM process tracking the
3215 snapshot's progress. This has the following sub-operations:
3216 <ul>
3217 <li>setting up (weight 1);</li>
3218 <li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
3219 <li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
3220 <li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
3221 <li>finishing up (weight 1)</li>
3222 </ul>
3223 </desc>
3224 </param>
3225 <param name="fTakingSnapshotOnline" type="boolean" dir="in">
3226 <desc>
3227 Whether this is an online snapshot (i.e. the machine is running).
3228 </desc>
3229 </param>
3230 <param name="stateFilePath" type="wstring" dir="out">
3231 <desc>
3232 File path the VM process must save the execution state to.
3233 </desc>
3234 </param>
3235 </method>
3236
3237 <method name="endTakingSnapshot">
3238 <desc>
3239 Called by the VM process to inform the server that the snapshot
3240 previously requested by #beginTakingSnapshot is either
3241 successfully taken or there was a failure.
3242 </desc>
3243
3244 <param name="success" type="boolean" dir="in">
3245 <desc>@c true to indicate success and @c false otherwise</desc>
3246 </param>
3247 </method>
3248
3249 <method name="deleteSnapshot">
3250 <desc>
3251 Gets called by <link to="IConsole::deleteSnapshot"/>,
3252 <link to="IConsole::deleteSnapshotAndAllChildren"/> and
3253 <link to="IConsole::deleteSnapshotRange"/>.
3254 <result name="VBOX_E_INVALID_OBJECT_STATE">
3255 Snapshot has more than one child snapshot. Only possible if the
3256 delete operation does not delete all children or the range does
3257 not meet the linearity condition.
3258 </result>
3259 </desc>
3260 <param name="initiator" type="IConsole" dir="in">
3261 <desc>The console object that initiated this call.</desc>
3262 </param>
3263 <param name="startId" type="uuid" mod="string" dir="in">
3264 <desc>UUID of the first snapshot to delete.</desc>
3265 </param>
3266 <param name="endId" type="uuid" mod="string" dir="in">
3267 <desc>UUID of the last snapshot to delete.</desc>
3268 </param>
3269 <param name="deleteAllChildren" type="boolean" dir="in">
3270 <desc>Whether all children should be deleted.</desc>
3271 </param>
3272 <param name="machineState" type="MachineState" dir="out">
3273 <desc>New machine state after this operation is started.</desc>
3274 </param>
3275 <param name="progress" type="IProgress" dir="return">
3276 <desc>Progress object to track the operation completion.</desc>
3277 </param>
3278 </method>
3279
3280 <method name="finishOnlineMergeMedium">
3281 <desc>
3282 Gets called by <link to="IInternalSessionControl::onlineMergeMedium"/>.
3283 </desc>
3284 <param name="mediumAttachment" type="IMediumAttachment" dir="in">
3285 <desc>The medium attachment which needs to be cleaned up.</desc>
3286 </param>
3287 <param name="source" type="IMedium" dir="in">
3288 <desc>Merge source medium.</desc>
3289 </param>
3290 <param name="target" type="IMedium" dir="in">
3291 <desc>Merge target medium.</desc>
3292 </param>
3293 <param name="mergeForward" type="boolean" dir="in">
3294 <desc>Merge direction.</desc>
3295 </param>
3296 <param name="parentForTarget" type="IMedium" dir="in">
3297 <desc>For forward merges: new parent for target medium.</desc>
3298 </param>
3299 <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
3300 <desc>For backward merges: list of media which need their parent UUID
3301 updated.</desc>
3302 </param>
3303 </method>
3304
3305 <method name="restoreSnapshot">
3306 <desc>
3307 Gets called by <link to="IConsole::restoreSnapshot"/>.
3308 </desc>
3309 <param name="initiator" type="IConsole" dir="in">
3310 <desc>The console object that initiated this call.</desc>
3311 </param>
3312 <param name="snapshot" type="ISnapshot" dir="in">
3313 <desc>The snapshot to restore the VM state from.</desc>
3314 </param>
3315 <param name="machineState" type="MachineState" dir="out">
3316 <desc>New machine state after this operation is started.</desc>
3317 </param>
3318 <param name="progress" type="IProgress" dir="return">
3319 <desc>Progress object to track the operation completion.</desc>
3320 </param>
3321 </method>
3322
3323 <method name="pullGuestProperties">
3324 <desc>
3325 Get the list of the guest properties matching a set of patterns along
3326 with their values, time stamps and flags and give responsibility for
3327 managing properties to the console.
3328 </desc>
3329 <param name="name" type="wstring" dir="out" safearray="yes">
3330 <desc>
3331 The names of the properties returned.
3332 </desc>
3333 </param>
3334 <param name="value" type="wstring" dir="out" safearray="yes">
3335 <desc>
3336 The values of the properties returned. The array entries match the
3337 corresponding entries in the @a name array.
3338 </desc>
3339 </param>
3340 <param name="timestamp" type="long long" dir="out" safearray="yes">
3341 <desc>
3342 The time stamps of the properties returned. The array entries match
3343 the corresponding entries in the @a name array.
3344 </desc>
3345 </param>
3346 <param name="flags" type="wstring" dir="out" safearray="yes">
3347 <desc>
3348 The flags of the properties returned. The array entries match the
3349 corresponding entries in the @a name array.
3350 </desc>
3351 </param>
3352 </method>
3353
3354 <method name="pushGuestProperty">
3355 <desc>
3356 Update a single guest property in IMachine.
3357 </desc>
3358 <param name="name" type="wstring" dir="in">
3359 <desc>
3360 The name of the property to be updated.
3361 </desc>
3362 </param>
3363 <param name="value" type="wstring" dir="in">
3364 <desc>
3365 The value of the property.
3366 </desc>
3367 </param>
3368 <param name="timestamp" type="long long" dir="in">
3369 <desc>
3370 The timestamp of the property.
3371 </desc>
3372 </param>
3373 <param name="flags" type="wstring" dir="in">
3374 <desc>
3375 The flags of the property.
3376 </desc>
3377 </param>
3378 </method>
3379
3380 <method name="lockMedia">
3381 <desc>
3382 Locks all media attached to the machine for writing and parents of
3383 attached differencing media (if any) for reading. This operation is
3384 atomic so that if it fails no media is actually locked.
3385
3386 This method is intended to be called when the machine is in Starting or
3387 Restoring state. The locked media will be automatically unlocked when
3388 the machine is powered off or crashed.
3389 </desc>
3390 </method>
3391 <method name="unlockMedia">
3392 <desc>
3393 Unlocks all media previously locked using
3394 <link to="IInternalMachineControl::lockMedia"/>.
3395
3396 This method is intended to be used with teleportation so that it is
3397 possible to teleport between processes on the same machine.
3398 </desc>
3399 </method>
3400
3401 <method name="ejectMedium">
3402 <desc>
3403 Tells VBoxSVC that the guest has ejected the medium associated with
3404 the medium attachment.
3405 </desc>
3406 <param name="attachment" type="IMediumAttachment" dir="in">
3407 <desc>
3408 The medium attachment where the eject happened.
3409 </desc>
3410 </param>
3411 <param name="newAttachment" type="IMediumAttachment" dir="return">
3412 <desc>
3413 A new reference to the medium attachment, as the config change can
3414 result in the creation of a new instance.
3415 </desc>
3416 </param>
3417 </method>
3418 </interface>
3419
3420 <interface
3421 name="IBIOSSettings" extends="$unknown"
3422 uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3423 wsmap="managed"
3424 >
3425 <desc>
3426 The IBIOSSettings interface represents BIOS settings of the virtual
3427 machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3428 </desc>
3429 <attribute name="logoFadeIn" type="boolean">
3430 <desc>Fade in flag for BIOS logo animation.</desc>
3431 </attribute>
3432
3433 <attribute name="logoFadeOut" type="boolean">
3434 <desc>Fade out flag for BIOS logo animation.</desc>
3435 </attribute>
3436
3437 <attribute name="logoDisplayTime" type="unsigned long">
3438 <desc>BIOS logo display time in milliseconds (0 = default).</desc>
3439 </attribute>
3440
3441 <attribute name="logoImagePath" type="wstring">
3442 <desc>
3443 Local file system path for external BIOS splash image. Empty string
3444 means the default image is shown on boot.
3445 </desc>
3446 </attribute>
3447
3448 <attribute name="bootMenuMode" type="BIOSBootMenuMode">
3449 <desc>Mode of the BIOS boot device menu.</desc>
3450 </attribute>
3451
3452 <attribute name="ACPIEnabled" type="boolean">
3453 <desc>ACPI support flag.</desc>
3454 </attribute>
3455
3456 <attribute name="IOAPICEnabled" type="boolean">
3457 <desc>
3458 IO APIC support flag. If set, VirtualBox will provide an IO APIC
3459 and support IRQs above 15.
3460 </desc>
3461 </attribute>
3462
3463 <attribute name="timeOffset" type="long long">
3464 <desc>
3465 Offset in milliseconds from the host system time. This allows for
3466 guests running with a different system date/time than the host.
3467 It is equivalent to setting the system date/time in the BIOS except
3468 it is not an absolute value but a relative one. Guest Additions
3469 time synchronization honors this offset.
3470 </desc>
3471 </attribute>
3472
3473 <attribute name="PXEDebugEnabled" type="boolean">
3474 <desc>
3475 PXE debug logging flag. If set, VirtualBox will write extensive
3476 PXE trace information to the release log.
3477 </desc>
3478 </attribute>
3479
3480 </interface>
3481
3482 <enum
3483 name="CleanupMode"
3484 uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441"
3485 >
3486 <desc>Cleanup mode, used with <link to="IMachine::unregister" />.
3487 </desc>
3488 <const name="UnregisterOnly" value="1">
3489 <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
3490 </const>
3491 <const name="DetachAllReturnNone" value="2">
3492 <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
3493 </const>
3494 <const name="DetachAllReturnHardDisksOnly" value="3">
3495 <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc>
3496 </const>
3497 <const name="Full" value="4">
3498 <desc>Delete all snapshots, detach all media and return all media for closing.</desc>
3499 </const>
3500 </enum>
3501
3502 <interface
3503 name="IPciAddress" extends="$unknown"
3504 uuid="D88B324F-DB19-4D3B-A1A9-BF5B127199A8"
3505 wsmap="struct"
3506 >
3507
3508 <desc>
3509 Address on the PCI bus.
3510 </desc>
3511
3512 <attribute name="bus" type="short">
3513 <desc>
3514 Bus number.
3515 </desc>
3516 </attribute>
3517
3518 <attribute name="device" type="short">
3519 <desc>
3520 Device number.
3521 </desc>
3522 </attribute>
3523
3524 <attribute name="devFunction" type="short">
3525 <desc>
3526 Device function number.
3527 </desc>
3528 </attribute>
3529
3530 <method name="asLong">
3531 <desc>
3532 Convert PCI address into long.
3533 </desc>
3534 <param name="result" type="long" dir="return" />
3535 </method>
3536
3537 <method name="fromLong">
3538 <desc>
3539 Make PCI address from long.
3540 </desc>
3541 <param name="number" type="long" dir="in" />
3542 </method>
3543 </interface>
3544
3545 <interface
3546 name="IPciDeviceAttachment" extends="$unknown"
3547 uuid="91f33d6f-e621-4f70-a77e-15f0e3c714d5"
3548 wsmap="struct"
3549 >
3550
3551 <desc>
3552 Information about PCI attachments.
3553 </desc>
3554
3555 <attribute name="name" type="wstring" readonly="yes">
3556 <desc>
3557 Device name.
3558 </desc>
3559 </attribute>
3560
3561 <attribute name="isPhysicalDevice" type="boolean" readonly="yes">
3562 <desc>
3563 If this is physical or virtual device.
3564 </desc>
3565 </attribute>
3566
3567 <attribute name="hostAddress" type="long" readonly="yes">
3568 <desc>
3569 Address of device on the host, applicable only to host devices.
3570 </desc>
3571 </attribute>
3572
3573 <attribute name="guestAddress" type="long" readonly="yes">
3574 <desc>
3575 Address of device on the guest.
3576 </desc>
3577 </attribute>
3578
3579 </interface>
3580
3581 <enum
3582 name="CloneMode" extends="$unknown"
3583 uuid="A7A159FE-5096-4B8D-8C3C-D033CB0B35A8"
3584 >
3585
3586 <desc>
3587 Clone mode, used with <link to="IMachine::cloneTo" />.
3588 </desc>
3589
3590 <const name="MachineState" value="1">
3591 <desc>Clone the state of the selected machine.</desc>
3592 </const>
3593 <const name="MachineAndChildStates" value="2">
3594 <desc>Clone the state of the selected machine and its child snapshots if present.</desc>
3595 </const>
3596 <const name="AllStates" value="3">
3597 <desc>Clone all states (including all snapshots) of the machine, regardless of the machine object used.</desc>
3598 </const>
3599
3600 </enum>
3601
3602 <enum
3603 name="CloneOptions" extends="$unknown"
3604 uuid="22243f8e-96ab-497c-8cf0-f40a566c630b"
3605 >
3606
3607 <desc>
3608 Clone options, used with <link to="IMachine::cloneTo" />.
3609 </desc>
3610
3611 <const name="Link" value="1">
3612 <desc>Create a clone VM where all virtual disks are linked to the original VM.</desc>
3613 </const>
3614 <const name="KeepAllMACs" value="2">
3615 <desc>Don't generate new MAC addresses of the attached network adapters.</desc>
3616 </const>
3617 <const name="KeepNATMACs" value="3">
3618 <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc>
3619 </const>
3620 <const name="KeepDiskNames" value="4">
3621 <desc>Don't change the disk names.</desc>
3622 </const>
3623
3624 </enum>
3625
3626
3627 <interface
3628 name="IMachine" extends="$unknown"
3629 uuid="5eaa9319-62fc-4b0a-843c-0cb1940f8a91"
3630 wsmap="managed"
3631 >
3632 <desc>
3633 The IMachine interface represents a virtual machine, or guest, created
3634 in VirtualBox.
3635
3636 This interface is used in two contexts. First of all, a collection of
3637 objects implementing this interface is stored in the
3638 <link to="IVirtualBox::machines"/> attribute which lists all the virtual
3639 machines that are currently registered with this VirtualBox
3640 installation. Also, once a session has been opened for the given virtual
3641 machine (e.g. the virtual machine is running), the machine object
3642 associated with the open session can be queried from the session object;
3643 see <link to="ISession"/> for details.
3644
3645 The main role of this interface is to expose the settings of the virtual
3646 machine and provide methods to change various aspects of the virtual
3647 machine's configuration. For machine objects stored in the
3648 <link to="IVirtualBox::machines"/> collection, all attributes are
3649 read-only unless explicitly stated otherwise in individual attribute
3650 and method descriptions.
3651
3652 In order to change a machine setting, a session for this machine must be
3653 opened using one of the <link to="IMachine::lockMachine" /> or
3654 <link to="IMachine::launchVMProcess"/> methods. After the
3655 machine has been successfully locked for a session, a mutable machine object
3656 needs to be queried from the session object and then the desired settings
3657 changes can be applied to the returned object using IMachine attributes and
3658 methods. See the <link to="ISession"/> interface description for more
3659 information about sessions.
3660
3661 Note that IMachine does not provide methods to control virtual machine
3662 execution (such as start the machine, or power it down) -- these methods
3663 are grouped in a separate interface called <link to="IConsole" />.
3664
3665 <see><link to="ISession"/>, <link to="IConsole"/></see>
3666 </desc>
3667
3668 <attribute name="parent" type="IVirtualBox" readonly="yes">
3669 <desc>Associated parent object.</desc>
3670 </attribute>
3671
3672 <attribute name="accessible" type="boolean" readonly="yes">
3673 <desc>
3674 Whether this virtual machine is currently accessible or not.
3675
3676 A machine is always deemed accessible unless it is registered <i>and</i>
3677 its settings file cannot be read or parsed (either because the file itself
3678 is unavailable or has invalid XML contents).
3679
3680 Every time this property is read, the accessibility state of
3681 this machine is re-evaluated. If the returned value is @c false,
3682 the <link to="#accessError"/> property may be used to get the
3683 detailed error information describing the reason of
3684 inaccessibility, including XML error messages.
3685
3686 When the machine is inaccessible, only the following properties
3687 can be used on it:
3688 <ul>
3689 <li><link to="#parent"/></li>
3690 <li><link to="#id"/></li>
3691 <li><link to="#settingsFilePath"/></li>
3692 <li><link to="#accessible"/></li>
3693 <li><link to="#accessError"/></li>
3694 </ul>
3695
3696 An attempt to access any other property or method will return
3697 an error.
3698
3699 The only possible action you can perform on an inaccessible
3700 machine is to unregister it using the
3701 <link to="IMachine::unregister"/> call (or, to check
3702 for the accessibility state once more by querying this
3703 property).
3704
3705 <note>
3706 In the current implementation, once this property returns
3707 @c true, the machine will never become inaccessible
3708 later, even if its settings file cannot be successfully
3709 read/written any more (at least, until the VirtualBox
3710 server is restarted). This limitation may be removed in
3711 future releases.
3712 </note>
3713 </desc>
3714 </attribute>
3715
3716 <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
3717 <desc>
3718 Error information describing the reason of machine
3719 inaccessibility.
3720
3721 Reading this property is only valid after the last call to
3722 <link to="#accessible"/> returned @c false (i.e. the
3723 machine is currently inaccessible). Otherwise, a @c null
3724 IVirtualBoxErrorInfo object will be returned.
3725 </desc>
3726 </attribute>
3727
3728 <attribute name="name" type="wstring">
3729 <desc>
3730 Name of the virtual machine.
3731
3732 Besides being used for human-readable identification purposes
3733 everywhere in VirtualBox, the virtual machine name is also used
3734 as a name of the machine's settings file and as a name of the
3735 subdirectory this settings file resides in. Thus, every time you
3736 change the value of this property, the settings file will be
3737 renamed once you call <link to="#saveSettings"/> to confirm the
3738 change. The containing subdirectory will be also renamed, but
3739 only if it has exactly the same name as the settings file
3740 itself prior to changing this property (for backward compatibility
3741 with previous API releases). The above implies the following
3742 limitations:
3743 <ul>
3744 <li>The machine name cannot be empty.</li>
3745 <li>The machine name can contain only characters that are valid
3746 file name characters according to the rules of the file
3747 system used to store VirtualBox configuration.</li>
3748 <li>You cannot have two or more machines with the same name
3749 if they use the same subdirectory for storing the machine
3750 settings files.</li>
3751 <li>You cannot change the name of the machine if it is running,
3752 or if any file in the directory containing the settings file
3753 is being used by another running machine or by any other
3754 process in the host operating system at a time when
3755 <link to="#saveSettings"/> is called.
3756 </li>
3757 </ul>
3758 If any of the above limitations are hit, <link to="#saveSettings"/>
3759 will return an appropriate error message explaining the exact
3760 reason and the changes you made to this machine will not be saved.
3761
3762 Starting with VirtualBox 4.0, a “.vbox” extension of the settings
3763 file is recommended, but not enforced. (Previous versions always
3764 used a generic ".xml" extension.)
3765 </desc>
3766 </attribute>
3767
3768 <attribute name="description" type="wstring">
3769 <desc>
3770 Description of the virtual machine.
3771
3772 The description attribute can contain any text and is
3773 typically used to describe the hardware and software
3774 configuration of the virtual machine in detail (i.e. network
3775 settings, versions of the installed software and so on).
3776 </desc>
3777 </attribute>
3778
3779 <attribute name="id" type="uuid" mod="string" readonly="yes">
3780 <desc>UUID of the virtual machine.</desc>
3781 </attribute>
3782
3783 <attribute name="OSTypeId" type="wstring">
3784 <desc>
3785 User-defined identifier of the Guest OS type.
3786 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
3787 an IGuestOSType object representing details about the given
3788 Guest OS type.
3789 <note>
3790 This value may differ from the value returned by
3791 <link to="IGuest::OSTypeId"/> if Guest Additions are
3792 installed to the guest OS.
3793 </note>
3794 </desc>
3795 </attribute>
3796
3797 <attribute name="hardwareVersion" type="wstring">
3798 <desc>Hardware version identifier. Internal use only for now.</desc>
3799 </attribute>
3800
3801 <attribute name="hardwareUUID" type="uuid" mod="string">
3802 <desc>
3803 The UUID presented to the guest via memory tables, hardware and guest
3804 properties. For most VMs this is the same as the @a id, but for VMs
3805 which have been cloned or teleported it may be the same as the source
3806 VM. This latter is because the guest shouldn't notice that it was
3807 cloned or teleported.
3808 </desc>
3809 </attribute>
3810
3811 <attribute name="CPUCount" type="unsigned long">
3812 <desc>Number of virtual CPUs in the VM.</desc>
3813 </attribute>
3814
3815 <attribute name="CPUHotPlugEnabled" type="boolean">
3816 <desc>
3817 This setting determines whether VirtualBox allows CPU
3818 hotplugging for this machine.</desc>
3819 </attribute>
3820
3821 <attribute name="CPUExecutionCap" type="unsigned long">
3822 <desc>
3823 Means to limit the number of CPU cycles a guest can use. The unit
3824 is percentage of host CPU cycles per second. The valid range
3825 is 1 - 100. 100 (the default) implies no limit.
3826 </desc>
3827 </attribute>
3828
3829 <attribute name="memorySize" type="unsigned long">
3830 <desc>System memory size in megabytes.</desc>
3831 </attribute>
3832
3833 <attribute name="memoryBalloonSize" type="unsigned long">
3834 <desc>Memory balloon size in megabytes.</desc>
3835 </attribute>
3836
3837 <attribute name="pageFusionEnabled" type="boolean">
3838 <desc>
3839 This setting determines whether VirtualBox allows page
3840 fusion for this machine (64 bits host only).
3841 </desc>
3842 </attribute>
3843
3844 <attribute name="VRAMSize" type="unsigned long">
3845 <desc>Video memory size in megabytes.</desc>
3846 </attribute>
3847
3848 <attribute name="accelerate3DEnabled" type="boolean" default="false">
3849 <desc>
3850 This setting determines whether VirtualBox allows this machine to make
3851 use of the 3D graphics support available on the host.</desc>
3852 </attribute>
3853
3854 <attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
3855 <desc>
3856 This setting determines whether VirtualBox allows this machine to make
3857 use of the 2D video acceleration support available on the host.</desc>
3858 </attribute>
3859
3860 <attribute name="monitorCount" type="unsigned long">
3861 <desc>
3862 Number of virtual monitors.
3863 <note>
3864 Only effective on Windows XP and later guests with
3865 Guest Additions installed.
3866 </note>
3867 </desc>
3868 </attribute>
3869
3870 <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
3871 <desc>Object containing all BIOS settings.</desc>
3872 </attribute>
3873
3874 <attribute name="firmwareType" type="FirmwareType">
3875 <desc>Type of firmware (such as legacy BIOS or EFI), used for initial
3876 bootstrap in this VM.</desc>
3877 </attribute>
3878
3879 <attribute name="pointingHidType" type="PointingHidType">
3880 <desc>Type of pointing HID (such as mouse or tablet) used in this VM.
3881 The default is typically "PS2Mouse" but can vary depending on the
3882 requirements of the guest operating system.</desc>
3883 </attribute>
3884
3885 <attribute name="keyboardHidType" type="KeyboardHidType">
3886 <desc>Type of keyboard HID used in this VM.
3887 The default is typically "PS2Keyboard" but can vary depending on the
3888 requirements of the guest operating system.</desc>
3889 </attribute>
3890
3891 <attribute name="hpetEnabled" type="boolean">
3892 <desc>This attribute controls if High Precision Event Timer (HPET) is
3893 enabled in this VM. Use this property if you want to provide guests
3894 with additional time source, or if guest requires HPET to function correctly.
3895 Default is false.</desc>
3896 </attribute>
3897
3898 <attribute name="chipsetType" type="ChipsetType">
3899 <desc>Chipset type used in this VM.</desc>
3900 </attribute>
3901
3902 <attribute name="snapshotFolder" type="wstring">
3903 <desc>
3904 Full path to the directory used to store snapshot data
3905 (differencing media and saved state files) of this machine.
3906
3907 The initial value of this property is
3908 <tt>&lt;</tt><link to="#settingsFilePath">
3909 path_to_settings_file</link><tt>&gt;/&lt;</tt>
3910 <link to="#id">machine_uuid</link>
3911 <tt>&gt;</tt>.
3912
3913 Currently, it is an error to try to change this property on
3914 a machine that has snapshots (because this would require to
3915 move possibly large files to a different location).
3916 A separate method will be available for this purpose later.
3917
3918 <note>
3919 Setting this property to @c null or to an empty string will restore
3920 the initial value.
3921 </note>
3922 <note>
3923 When setting this property, the specified path can be
3924 absolute (full path) or relative to the directory where the
3925 <link to="#settingsFilePath">machine settings file</link>
3926 is located. When reading this property, a full path is
3927 always returned.
3928 </note>
3929 <note>
3930 The specified path may not exist, it will be created
3931 when necessary.
3932 </note>
3933 </desc>
3934 </attribute>
3935
3936 <attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
3937 <desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
3938 </attribute>
3939
3940 <attribute name="emulatedUSBWebcameraEnabled" type="boolean" default="false"/>
3941 <attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/>
3942
3943 <attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
3944 <desc>Array of media attached to this machine.</desc>
3945 </attribute>
3946
3947 <attribute name="USBController" type="IUSBController" readonly="yes">
3948 <desc>
3949 Associated USB controller object.
3950
3951 <note>
3952 If USB functionality is not available in the given edition of
3953 VirtualBox, this method will set the result code to @c E_NOTIMPL.
3954 </note>
3955 </desc>
3956 </attribute>
3957
3958 <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
3959 <desc>Associated audio adapter, always present.</desc>
3960 </attribute>
3961
3962 <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
3963 <desc>Array of storage controllers attached to this machine.</desc>
3964 </attribute>
3965
3966 <attribute name="settingsFilePath" type="wstring" readonly="yes">
3967 <desc>
3968 Full name of the file containing machine settings data.
3969 </desc>
3970 </attribute>
3971
3972 <attribute name="settingsModified" type="boolean" readonly="yes">
3973 <desc>
3974 Whether the settings of this machine have been modified
3975 (but neither yet saved nor discarded).
3976 <note>
3977 Reading this property is only valid on instances returned
3978 by <link to="ISession::machine"/> and on new machines
3979 created by <link to="IVirtualBox::createMachine"/> or opened
3980 by <link to="IVirtualBox::openMachine"/> but not
3981 yet registered, or on unregistered machines after calling
3982 <link to="IMachine::unregister"/>. For all other
3983 cases, the settings can never be modified.
3984 </note>
3985 <note>
3986 For newly created unregistered machines, the value of this
3987 property is always @c true until <link to="#saveSettings"/>
3988 is called (no matter if any machine settings have been
3989 changed after the creation or not). For opened machines
3990 the value is set to @c false (and then follows to normal rules).
3991 </note>
3992 </desc>
3993 </attribute>
3994
3995 <attribute name="sessionState" type="SessionState" readonly="yes">
3996 <desc>Current session state for this machine.</desc>
3997 </attribute>
3998
3999 <attribute name="sessionType" type="wstring" readonly="yes">
4000 <desc>
4001 Type of the session. If <link to="#sessionState"/> is
4002 Spawning or Locked, this attribute contains the
4003 same value as passed to the
4004 <link to="IMachine::launchVMProcess"/> method in the
4005 @a type parameter. If the session was used with
4006 <link to="IMachine::lockMachine" />, or if
4007 <link to="#sessionState"/> is SessionClosed, the value of this
4008 attribute is an empty string.
4009 </desc>
4010 </attribute>
4011
4012 <attribute name="sessionPid" type="unsigned long" readonly="yes">
4013 <desc>
4014 Identifier of the session process. This attribute contains the
4015 platform-dependent identifier of the process whose session was
4016 used with <link to="IMachine::lockMachine" /> call. The returned
4017 value is only valid if <link to="#sessionState"/> is Locked or
4018 Unlocking by the time this property is read.
4019 </desc>
4020 </attribute>
4021
4022 <attribute name="state" type="MachineState" readonly="yes">
4023 <desc>Current execution state of this machine.</desc>
4024 </attribute>
4025
4026 <attribute name="lastStateChange" type="long long" readonly="yes">
4027 <desc>
4028 Time stamp of the last execution state change,
4029 in milliseconds since 1970-01-01 UTC.
4030 </desc>
4031 </attribute>
4032
4033 <attribute name="stateFilePath" type="wstring" readonly="yes">
4034 <desc>
4035 Full path to the file that stores the execution state of
4036 the machine when it is in the <link to="MachineState_Saved"/> state.
4037 <note>
4038 When the machine is not in the Saved state, this attribute is
4039 an empty string.
4040 </note>
4041 </desc>
4042 </attribute>
4043
4044 <attribute name="logFolder" type="wstring" readonly="yes">
4045 <desc>
4046 Full path to the folder that stores a set of rotated log files
4047 recorded during machine execution. The most recent log file is
4048 named <tt>VBox.log</tt>, the previous log file is
4049 named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4050 in the current version).
4051 </desc>
4052 </attribute>
4053
4054 <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4055 <desc>
4056 Current snapshot of this machine. This is @c null if the machine
4057 currently has no snapshots. If it is not @c null, then it was
4058 set by one of <link to="IConsole::takeSnapshot" />,
4059 <link to="IConsole::deleteSnapshot" />
4060 or <link to="IConsole::restoreSnapshot" />, depending on which
4061 was called last. See <link to="ISnapshot"/> for details.
4062 </desc>
4063 </attribute>
4064
4065 <attribute name="snapshotCount" type="unsigned long" readonly="yes">
4066 <desc>
4067 Number of snapshots taken on this machine. Zero means the
4068 machine doesn't have any snapshots.
4069 </desc>
4070 </attribute>
4071
4072 <attribute name="currentStateModified" type="boolean" readonly="yes">
4073 <desc>
4074 Returns @c true if the current state of the machine is not
4075 identical to the state stored in the current snapshot.
4076
4077 The current state is identical to the current snapshot only
4078 directly after one of the following calls are made:
4079
4080 <ul>
4081 <li><link to="IConsole::restoreSnapshot"/>
4082 </li>
4083 <li><link to="IConsole::takeSnapshot"/> (issued on a
4084 "powered off" or "saved" machine, for which
4085 <link to="#settingsModified"/> returns @c false)
4086 </li>
4087 </ul>
4088
4089 The current state remains identical until one of the following
4090 happens:
4091 <ul>
4092 <li>settings of the machine are changed</li>
4093 <li>the saved state is deleted</li>
4094 <li>the current snapshot is deleted</li>
4095 <li>an attempt to execute the machine is made</li>
4096 </ul>
4097
4098 <note>
4099 For machines that don't have snapshots, this property is
4100 always @c false.
4101 </note>
4102 </desc>
4103 </attribute>
4104
4105 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4106 <desc>
4107 Collection of shared folders for this machine (permanent shared
4108 folders). These folders are shared automatically at machine startup
4109 and available only to the guest OS installed within this machine.
4110
4111 New shared folders are added to the collection using
4112 <link to="#createSharedFolder"/>. Existing shared folders can be
4113 removed using <link to="#removeSharedFolder"/>.
4114 </desc>
4115 </attribute>
4116
4117 <attribute name="clipboardMode" type="ClipboardMode">
4118 <desc>
4119 Synchronization mode between the host OS clipboard
4120 and the guest OS clipboard.
4121 </desc>
4122 </attribute>
4123
4124 <attribute name="guestPropertyNotificationPatterns" type="wstring">
4125 <desc>
4126 A comma-separated list of simple glob patterns. Changes to guest
4127 properties whose name matches one of the patterns will generate an
4128 <link to="IGuestPropertyChangedEvent"/> signal.
4129 </desc>
4130 </attribute>
4131
4132 <attribute name="teleporterEnabled" type="boolean">
4133 <desc>
4134 When set to @a true, the virtual machine becomes a target teleporter
4135 the next time it is powered on. This can only set to @a true when the
4136 VM is in the @a PoweredOff or @a Aborted state.
4137
4138 <!-- This property is automatically set to @a false when the VM is powered
4139 on. (bird: This doesn't work yet ) -->
4140 </desc>
4141 </attribute>
4142
4143 <attribute name="teleporterPort" type="unsigned long">
4144 <desc>
4145 The TCP port the target teleporter will listen for incoming
4146 teleportations on.
4147
4148 0 means the port is automatically selected upon power on. The actual
4149 value can be read from this property while the machine is waiting for
4150 incoming teleportations.
4151 </desc>
4152 </attribute>
4153
4154 <attribute name="teleporterAddress" type="wstring">
4155 <desc>
4156 The address the target teleporter will listen on. If set to an empty
4157 string, it will listen on all addresses.
4158 </desc>
4159 </attribute>
4160
4161 <attribute name="teleporterPassword" type="wstring">
4162 <desc>
4163 The password to check for on the target teleporter. This is just a
4164 very basic measure to prevent simple hacks and operators accidentally
4165 beaming a virtual machine to the wrong place.
4166 </desc>
4167 </attribute>
4168
4169 <attribute name="faultToleranceState" type="FaultToleranceState">
4170 <desc>
4171 Fault tolerance state; disabled, source or target.
4172 This property can be changed at any time. If you change it for a running
4173 VM, then the fault tolerance address and port must be set beforehand.
4174 </desc>
4175 </attribute>
4176
4177 <attribute name="faultTolerancePort" type="unsigned long">
4178 <desc>
4179 The TCP port the fault tolerance source or target will use for
4180 communication.
4181 </desc>
4182 </attribute>
4183
4184 <attribute name="faultToleranceAddress" type="wstring">
4185 <desc>
4186 The address the fault tolerance source or target.
4187 </desc>
4188 </attribute>
4189
4190 <attribute name="faultTolerancePassword" type="wstring">
4191 <desc>
4192 The password to check for on the standby VM. This is just a
4193 very basic measure to prevent simple hacks and operators accidentally
4194 choosing the wrong standby VM.
4195 </desc>
4196 </attribute>
4197
4198 <attribute name="faultToleranceSyncInterval" type="unsigned long">
4199 <desc>
4200 The interval in ms used for syncing the state between source and target.
4201 </desc>
4202 </attribute>
4203
4204 <attribute name="RTCUseUTC" type="boolean">
4205 <desc>
4206 When set to @a true, the RTC device of the virtual machine will run
4207 in UTC time, otherwise in local time. Especially Unix guests prefer
4208 the time in UTC.
4209 </desc>
4210 </attribute>
4211
4212 <attribute name="ioCacheEnabled" type="boolean">
4213 <desc>
4214 When set to @a true, the builtin I/O cache of the virtual machine
4215 will be enabled.
4216 </desc>
4217 </attribute>
4218
4219 <attribute name="ioCacheSize" type="unsigned long">
4220 <desc>
4221 Maximum size of the I/O cache in MB.
4222 </desc>
4223 </attribute>
4224
4225 <attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes">
4226 <desc>
4227 Bandwidth control manager.
4228 </desc>
4229 </attribute>
4230
4231 <attribute name="pciDeviceAssignments" type="IPciDeviceAttachment" readonly="yes" safearray="yes">
4232 <desc>Array of PCI devices assigned to this machine, to get list of all
4233 PCI devices attached to the machine use
4234 <link to="IConsole::attachedPciDevices"/> attribute, as this attribute
4235 is intended to list only devices additional to what described in
4236 virtual hardware config. Usually, this list keeps host's physical
4237 devices assigned to the particular machine.
4238 </desc>
4239 </attribute>
4240
4241 <method name="lockMachine">
4242 <desc>
4243 Locks the machine for the given session to enable the caller
4244 to make changes to the machine or start the VM or control
4245 VM execution.
4246
4247 There are two ways to lock a machine for such uses:
4248
4249 <ul>
4250 <li>If you want to make changes to the machine settings,
4251 you must obtain an exclusive write lock on the machine
4252 by setting @a lockType to @c Write.
4253
4254 This will only succeed if no other process has locked
4255 the machine to prevent conflicting changes. Only after
4256 an exclusive write lock has been obtained using this method, one
4257 can change all VM settings or execute the VM in the process
4258 space of the session object. (Note that the latter is only of
4259 interest if you actually want to write a new front-end for
4260 virtual machines; but this API gets called internally by
4261 the existing front-ends such as VBoxHeadless and the VirtualBox
4262 GUI to acquire a write lock on the machine that they are running.)
4263
4264 On success, write-locking the machine for a session creates
4265 a second copy of the IMachine object. It is this second object
4266 upon which changes can be made; in VirtualBox terminology, the
4267 second copy is "mutable". It is only this second, mutable machine
4268 object upon which you can call methods that change the
4269 machine state. After having called this method, you can
4270 obtain this second, mutable machine object using the
4271 <link to="ISession::machine" /> attribute.
4272 </li>
4273 <li>If you only want to check the machine state or control
4274 machine execution without actually changing machine
4275 settings (e.g. to get access to VM statistics or take
4276 a snapshot or save the machine state), then set the
4277 @a lockType argument to @c Shared.
4278
4279 If no other session has obtained a lock, you will obtain an
4280 exclusive write lock as described above. However, if another
4281 session has already obtained such a lock, then a link to that
4282 existing session will be established which allows you
4283 to control that existing session.
4284
4285 To find out which type of lock was obtained, you can
4286 inspect <link to="ISession::type" />, which will have been
4287 set to either @c WriteLock or @c Shared.
4288 </li>
4289 </ul>
4290
4291 In either case, you can get access to the <link to="IConsole" />
4292 object which controls VM execution.
4293
4294 Also in all of the above cases, one must always call
4295 <link to="ISession::unlockMachine" /> to release the lock on the machine, or
4296 the machine's state will eventually be set to "Aborted".
4297
4298 To change settings on a machine, the following sequence is typically
4299 performed:
4300
4301 <ol>
4302 <li>Call this method to obtain an exclusive write lock for the current session.</li>
4303
4304 <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
4305
4306 <li>Change the settings of the machine by invoking IMachine methods.</li>
4307
4308 <li>Call <link to="IMachine::saveSettings" />.</li>
4309
4310 <li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
4311 </ol>
4312
4313 <result name="E_UNEXPECTED">
4314 Virtual machine not registered.
4315 </result>
4316 <result name="E_ACCESSDENIED">
4317 Process not started by OpenRemoteSession.
4318 </result>
4319 <result name="VBOX_E_INVALID_OBJECT_STATE">
4320 Session already open or being opened.
4321 </result>
4322 <result name="VBOX_E_VM_ERROR">
4323 Failed to assign machine to session.
4324 </result>
4325 </desc>
4326 <param name="session" type="ISession" dir="in">
4327 <desc>
4328 Session object for which the machine will be locked.
4329 </desc>
4330 </param>
4331 <param name="lockType" type="LockType" dir="in">
4332 <desc>
4333 If set to @c Write, then attempt to acquire an exclusive write lock or fail.
4334 If set to @c Shared, then either acquire an exclusive write lock or establish
4335 a link to an existing session.
4336 </desc>
4337 </param>
4338 </method>
4339
4340 <method name="launchVMProcess">
4341 <desc>
4342 Spawns a new process that will execute the virtual machine and obtains a shared
4343 lock on the machine for the calling session.
4344
4345 If launching the VM succeeds, the new VM process will create its own session
4346 and write-lock the machine for it, preventing conflicting changes from other
4347 processes. If the machine is already locked (because it is already running or
4348 because another session has a write lock), launching the VM process will therefore
4349 fail. Reversely, future attempts to obtain a write lock will also fail while the
4350 machine is running.
4351
4352 The caller's session object remains separate from the session opened by the new
4353 VM process. It receives its own <link to="IConsole" /> object which can be used
4354 to control machine execution, but it cannot be used to change all VM settings
4355 which would be available after a <link to="#lockMachine" /> call.
4356
4357 The caller must eventually release the session's shared lock by calling
4358 <link to="ISession::unlockMachine" /> on the local session object once this call
4359 has returned. However, the session's state (see <link to="ISession::state" />)
4360 will not return to "Unlocked" until the remote session has also unlocked
4361 the machine (i.e. the machine has stopped running).
4362
4363 Launching a VM process can take some time (a new VM is started in a new process,
4364 for which memory and other resources need to be set up). Because of this,
4365 an <link to="IProgress" /> object is returned to allow the caller to wait
4366 for this asynchronous operation to be completed. Until then, the caller's
4367 session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
4368 and <link to="ISession::console" /> attributes cannot be accessed.
4369 It is recommended to use <link to="IProgress::waitForCompletion" /> or
4370 similar calls to wait for completion. Completion is signalled when the VM
4371 is powered on. If launching the VM fails, error messages can be queried
4372 via the progress object, if available.
4373
4374 The progress object will have at least 2 sub-operations. The first
4375 operation covers the period up to the new VM process calls powerUp.
4376 The subsequent operations mirror the <link to="IConsole::powerUp"/>
4377 progress object. Because <link to="IConsole::powerUp"/> may require
4378 some extra sub-operations, the <link to="IProgress::operationCount"/>
4379 may change at the completion of operation.
4380
4381 For details on the teleportation progress operation, see
4382 <link to="IConsole::powerUp"/>.
4383
4384 The @a environment argument is a string containing definitions of
4385 environment variables in the following format:
4386 @code
4387 NAME[=VALUE]\n
4388 NAME[=VALUE]\n
4389 ...
4390 @endcode
4391 where <tt>\\n</tt> is the new line character. These environment
4392 variables will be appended to the environment of the VirtualBox server
4393 process. If an environment variable exists both in the server process
4394 and in this list, the value from this list takes precedence over the
4395 server's variable. If the value of the environment variable is
4396 omitted, this variable will be removed from the resulting environment.
4397 If the environment string is @c null or empty, the server environment
4398 is inherited by the started process as is.
4399
4400 <result name="E_UNEXPECTED">
4401 Virtual machine not registered.
4402 </result>
4403 <result name="E_INVALIDARG">
4404 Invalid session type @a type.
4405 </result>
4406 <result name="VBOX_E_OBJECT_NOT_FOUND">
4407 No machine matching @a machineId found.
4408 </result>
4409 <result name="VBOX_E_INVALID_OBJECT_STATE">
4410 Session already open or being opened.
4411 </result>
4412 <result name="VBOX_E_IPRT_ERROR">
4413 Launching process for machine failed.
4414 </result>
4415 <result name="VBOX_E_VM_ERROR">
4416 Failed to assign machine to session.
4417 </result>
4418 </desc>
4419 <param name="session" type="ISession" dir="in">
4420 <desc>
4421 Client session object to which the VM process will be connected (this
4422 must be in "Unlocked" state).
4423 </desc>
4424 </param>
4425 <param name="type" type="wstring" dir="in">
4426 <desc>
4427 Front-end to use for the new VM process. The following are currently supported:
4428 <ul>
4429 <li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
4430 <li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
4431 <li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
4432 <li><tt>"emergencystop"</tt>: reserved value, used for aborting
4433 the currently running VM or session owner. In this case the
4434 @a session parameter may be @c NULL (if it is non-null it isn't
4435 used in any way), and the @a progress return value will be always
4436 NULL. The operation completes immediately.</li>
4437 </ul>
4438 </desc>
4439 </param>
4440 <param name="environment" type="wstring" dir="in">
4441 <desc>
4442 Environment to pass to the VM process.
4443 </desc>
4444 </param>
4445 <param name="progress" type="IProgress" dir="return">
4446 <desc>Progress object to track the operation completion.</desc>
4447 </param>
4448 </method>
4449
4450 <method name="setBootOrder">
4451 <desc>
4452 Puts the given device to the specified position in
4453 the boot order.
4454
4455 To indicate that no device is associated with the given position,
4456 <link to="DeviceType_Null"/> should be used.
4457
4458 @todo setHardDiskBootOrder(), setNetworkBootOrder()
4459
4460 <result name="E_INVALIDARG">
4461 Boot @a position out of range.
4462 </result>
4463 <result name="E_NOTIMPL">
4464 Booting from USB @a device currently not supported.
4465 </result>
4466
4467 </desc>
4468 <param name="position" type="unsigned long" dir="in">
4469 <desc>
4470 Position in the boot order (@c 1 to the total number of
4471 devices the machine can boot from, as returned by
4472 <link to="ISystemProperties::maxBootPosition"/>).
4473 </desc>
4474 </param>
4475 <param name="device" type="DeviceType" dir="in">
4476 <desc>
4477 The type of the device used to boot at the given position.
4478 </desc>
4479 </param>
4480 </method>
4481
4482 <method name="getBootOrder" const="yes">
4483 <desc>
4484 Returns the device type that occupies the specified
4485 position in the boot order.
4486
4487 @todo [remove?]
4488 If the machine can have more than one device of the returned type
4489 (such as hard disks), then a separate method should be used to
4490 retrieve the individual device that occupies the given position.
4491
4492 If here are no devices at the given position, then
4493 <link to="DeviceType_Null"/> is returned.
4494
4495 @todo getHardDiskBootOrder(), getNetworkBootOrder()
4496
4497 <result name="E_INVALIDARG">
4498 Boot @a position out of range.
4499 </result>
4500
4501 </desc>
4502 <param name="position" type="unsigned long" dir="in">
4503 <desc>
4504 Position in the boot order (@c 1 to the total number of
4505 devices the machine can boot from, as returned by
4506 <link to="ISystemProperties::maxBootPosition"/>).
4507 </desc>
4508 </param>
4509 <param name="device" type="DeviceType" dir="return">
4510 <desc>
4511 Device at the given position.
4512 </desc>
4513 </param>
4514 </method>
4515
4516 <method name="attachDevice">
4517 <desc>
4518 Attaches a device and optionally mounts a medium to the given storage
4519 controller (<link to="IStorageController" />, identified by @a name),
4520 at the indicated port and device.
4521
4522 This method is intended for managing storage devices in general while a
4523 machine is powered off. It can be used to attach and detach fixed
4524 and removable media. The following kind of media can be attached
4525 to a machine:
4526
4527 <ul>
4528 <li>For fixed and removable media, you can pass in a medium that was
4529 previously opened using <link to="IVirtualBox::openMedium" />.
4530 </li>
4531
4532 <li>Only for storage devices supporting removable media (such as
4533 DVDs and floppies), you can also specify a null pointer to
4534 indicate an empty drive or one of the medium objects listed
4535 in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
4536 arrays to indicate a host drive.
4537 For removable devices, you can also use <link to="IMachine::mountMedium"/>
4538 to change the media while the machine is running.
4539 </li>
4540 </ul>
4541
4542 In a VM's default configuration of virtual machines, the secondary
4543 master of the IDE controller is used for a CD/DVD drive.
4544
4545 After calling this returns successfully, a new instance of
4546 <link to="IMediumAttachment"/> will appear in the machine's list of medium
4547 attachments (see <link to="IMachine::mediumAttachments"/>).
4548
4549 See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
4550 information about attaching media.
4551
4552 The specified device slot must not have a device attached to it,
4553 or this method will fail.
4554
4555 <note>
4556 You cannot attach a device to a newly created machine until
4557 this machine's settings are saved to disk using
4558 <link to="#saveSettings"/>.
4559 </note>
4560 <note>
4561 If the medium is being attached indirectly, a new differencing medium
4562 will implicitly be created for it and attached instead. If the
4563 changes made to the machine settings (including this indirect
4564 attachment) are later cancelled using <link to="#discardSettings"/>,
4565 this implicitly created differencing medium will implicitly
4566 be deleted.
4567 </note>
4568
4569 <result name="E_INVALIDARG">
4570 SATA device, SATA port, IDE port or IDE slot out of range, or
4571 file or UUID not found.
4572 </result>
4573 <result name="VBOX_E_INVALID_OBJECT_STATE">
4574 Machine must be registered before media can be attached.
4575 </result>
4576 <result name="VBOX_E_INVALID_VM_STATE">
4577 Invalid machine state.
4578 </result>
4579 <result name="VBOX_E_OBJECT_IN_USE">
4580 A medium is already attached to this or another virtual machine.
4581 </result>
4582
4583 </desc>
4584 <param name="name" type="wstring" dir="in">
4585 <desc>Name of the storage controller to attach the device to.</desc>
4586 </param>
4587 <param name="controllerPort" type="long" dir="in">
4588 <desc>Port to attach the device to. For an IDE controller, 0 specifies
4589 the primary controller and 1 specifies the secondary controller.
4590 For a SCSI controller, this must range from 0 to 15; for a SATA controller,
4591 from 0 to 29; for an SAS controller, from 0 to 7.</desc>
4592 </param>
4593 <param name="device" type="long" dir="in">
4594 <desc>Device slot in the given port to attach the device to. This is only
4595 relevant for IDE controllers, for which 0 specifies the master device and
4596 1 specifies the slave device. For all other controller types, this must
4597 be 0.</desc>
4598 </param>
4599 <param name="type" type="DeviceType" dir="in">
4600 <desc>Device type of the attached device. For media opened by
4601 <link to="IVirtualBox::openMedium" />, this must match the device type
4602 specified there.</desc>
4603 </param>
4604 <param name="medium" type="IMedium" dir="in">
4605 <desc>Medium to mount or NULL for an empty drive.</desc>
4606 </param>
4607 </method>
4608
4609 <method name="detachDevice">
4610 <desc>
4611 Detaches the device attached to a device slot of the specified bus.
4612
4613 Detaching the device from the virtual machine is deferred. This means
4614 that the medium remains associated with the machine when this method
4615 returns and gets actually de-associated only after a successful
4616 <link to="#saveSettings"/> call. See <link to="IMedium"/>
4617 for more detailed information about attaching media.
4618
4619 <note>
4620 You cannot detach a device from a running machine.
4621 </note>
4622 <note>
4623 Detaching differencing media implicitly created by <link
4624 to="#attachDevice"/> for the indirect attachment using this
4625 method will <b>not</b> implicitly delete them. The
4626 <link to="IMedium::deleteStorage"/> operation should be
4627 explicitly performed by the caller after the medium is successfully
4628 detached and the settings are saved with
4629 <link to="#saveSettings"/>, if it is the desired action.
4630 </note>
4631
4632 <result name="VBOX_E_INVALID_VM_STATE">
4633 Attempt to detach medium from a running virtual machine.
4634 </result>
4635 <result name="VBOX_E_OBJECT_NOT_FOUND">
4636 No medium attached to given slot/bus.
4637 </result>
4638 <result name="VBOX_E_NOT_SUPPORTED">
4639 Medium format does not support storage deletion.
4640 </result>
4641
4642 </desc>
4643 <param name="name" type="wstring" dir="in">
4644 <desc>Name of the storage controller to detach the medium from.</desc>
4645 </param>
4646 <param name="controllerPort" type="long" dir="in">
4647 <desc>Port number to detach the medium from.</desc>
4648 </param>
4649 <param name="device" type="long" dir="in">
4650 <desc>Device slot number to detach the medium from.</desc>
4651 </param>
4652 </method>
4653
4654 <method name="passthroughDevice">
4655 <desc>
4656 Sets the passthrough mode of an existing DVD device. Changing the
4657 setting while the VM is running is forbidden. The setting is only used
4658 if at VM start the device is configured as a host DVD drive, in all
4659 other cases it is ignored. The device must already exist; see
4660 <link to="IMachine::attachDevice"/> for how to attach a new device.
4661
4662 The @a controllerPort and @a device parameters specify the device slot and
4663 have have the same meaning as with <link to="IMachine::attachDevice" />.
4664
4665 <result name="E_INVALIDARG">
4666 SATA device, SATA port, IDE port or IDE slot out of range.
4667 </result>
4668 <result name="VBOX_E_INVALID_OBJECT_STATE">
4669 Attempt to modify an unregistered virtual machine.
4670 </result>
4671 <result name="VBOX_E_INVALID_VM_STATE">
4672 Invalid machine state.
4673 </result>
4674
4675 </desc>
4676 <param name="name" type="wstring" dir="in">
4677 <desc>Name of the storage controller.</desc>
4678 </param>
4679 <param name="controllerPort" type="long" dir="in">
4680 <desc>Storage controller port.</desc>
4681 </param>
4682 <param name="device" type="long" dir="in">
4683 <desc>Device slot in the given port.</desc>
4684 </param>
4685 <param name="passthrough" type="boolean" dir="in">
4686 <desc>New value for the passthrough setting.</desc>
4687 </param>
4688 </method>
4689
4690 <method name="temporaryEjectDevice">
4691 <desc>
4692 Sets the behavior for guest-triggered medium eject. In some situations
4693 it is desirable that such ejects update the VM configuration, and in
4694 others the eject should keep the VM configuration. The device must
4695 already exist; see <link to="IMachine::attachDevice"/> for how to
4696 attach a new device.
4697
4698 The @a controllerPort and @a device parameters specify the device slot and
4699 have have the same meaning as with <link to="IMachine::attachDevice" />.
4700
4701 <result name="E_INVALIDARG">
4702 SATA device, SATA port, IDE port or IDE slot out of range.
4703 </result>
4704 <result name="VBOX_E_INVALID_OBJECT_STATE">
4705 Attempt to modify an unregistered virtual machine.
4706 </result>
4707 <result name="VBOX_E_INVALID_VM_STATE">
4708 Invalid machine state.
4709 </result>
4710
4711 </desc>
4712 <param name="name" type="wstring" dir="in">
4713 <desc>Name of the storage controller.</desc>
4714 </param>
4715 <param name="controllerPort" type="long" dir="in">
4716 <desc>Storage controller port.</desc>
4717 </param>
4718 <param name="device" type="long" dir="in">
4719 <desc>Device slot in the given port.</desc>
4720 </param>
4721 <param name="temporaryEject" type="boolean" dir="in">
4722 <desc>New value for the eject behavior.</desc>
4723 </param>
4724 </method>
4725
4726 <method name="nonRotationalDevice">
4727 <desc>
4728 Sets a flag in the device information which indicates that the medium
4729 is not based on rotational technology, i.e. that the access times are
4730 more or less independent of the position on the medium. This may or may
4731 not be supported by a particular drive, and is silently ignored in the
4732 latter case. At the moment only hard disks (which is a misnomer in this
4733 context) accept this setting. Changing the setting while the VM is
4734 running is forbidden. The device must already exist; see
4735 <link to="IMachine::attachDevice"/> for how to attach a new device.
4736
4737 The @a controllerPort and @a device parameters specify the device slot and
4738 have have the same meaning as with <link to="IMachine::attachDevice" />.
4739
4740 <result name="E_INVALIDARG">
4741 SATA device, SATA port, IDE port or IDE slot out of range.
4742 </result>
4743 <result name="VBOX_E_INVALID_OBJECT_STATE">
4744 Attempt to modify an unregistered virtual machine.
4745 </result>
4746 <result name="VBOX_E_INVALID_VM_STATE">
4747 Invalid machine state.
4748 </result>
4749
4750 </desc>
4751 <param name="name" type="wstring" dir="in">
4752 <desc>Name of the storage controller.</desc>
4753 </param>
4754 <param name="controllerPort" type="long" dir="in">
4755 <desc>Storage controller port.</desc>
4756 </param>
4757 <param name="device" type="long" dir="in">
4758 <desc>Device slot in the given port.</desc>
4759 </param>
4760 <param name="nonRotational" type="boolean" dir="in">
4761 <desc>New value for the non-rotational device flag.</desc>
4762 </param>
4763 </method>
4764
4765 <method name="setBandwidthGroupForDevice">
4766 <desc>
4767 Sets the bandwidth group of an existing storage device.
4768 The device must already exist; see <link to="IMachine::attachDevice"/>
4769 for how to attach a new device.
4770
4771 The @a controllerPort and @a device parameters specify the device slot and
4772 have have the same meaning as with <link to="IMachine::attachDevice" />.
4773
4774 <result name="E_INVALIDARG">
4775 SATA device, SATA port, IDE port or IDE slot out of range.
4776 </result>
4777 <result name="VBOX_E_INVALID_OBJECT_STATE">
4778 Attempt to modify an unregistered virtual machine.
4779 </result>
4780 <result name="VBOX_E_INVALID_VM_STATE">
4781 Invalid machine state.
4782 </result>
4783
4784 </desc>
4785 <param name="name" type="wstring" dir="in">
4786 <desc>Name of the storage controller.</desc>
4787 </param>
4788 <param name="controllerPort" type="long" dir="in">
4789 <desc>Storage controller port.</desc>
4790 </param>
4791 <param name="device" type="long" dir="in">
4792 <desc>Device slot in the given port.</desc>
4793 </param>
4794 <param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
4795 <desc>New value for the bandwidth group or NULL for no group.</desc>
4796 </param>
4797 </method>
4798
4799 <method name="mountMedium">
4800 <desc>
4801 Mounts a medium (<link to="IMedium" />, identified
4802 by the given UUID @a id) to the given storage controller
4803 (<link to="IStorageController" />, identified by @a name),
4804 at the indicated port and device. The device must already exist;
4805 see <link to="IMachine::attachDevice"/> for how to attach a new device.
4806
4807 This method is intended only for managing removable media, where the
4808 device is fixed but media is changeable at runtime (such as DVDs
4809 and floppies). It cannot be used for fixed media such as hard disks.
4810
4811 The @a controllerPort and @a device parameters specify the device slot and
4812 have have the same meaning as with <link to="IMachine::attachDevice" />.
4813
4814 The specified device slot can have a medium mounted, which will be
4815 unmounted first. Specifying a zero UUID (or an empty string) for
4816 @a medium does just an unmount.
4817
4818 See <link to="IMedium"/> for more detailed information about
4819 attaching media.
4820
4821 <result name="E_INVALIDARG">
4822 SATA device, SATA port, IDE port or IDE slot out of range.
4823 </result>
4824 <result name="VBOX_E_INVALID_OBJECT_STATE">
4825 Attempt to attach medium to an unregistered virtual machine.
4826 </result>
4827 <result name="VBOX_E_INVALID_VM_STATE">
4828 Invalid machine state.
4829 </result>
4830 <result name="VBOX_E_OBJECT_IN_USE">
4831 Medium already attached to this or another virtual machine.
4832 </result>
4833
4834 </desc>
4835 <param name="name" type="wstring" dir="in">
4836 <desc>Name of the storage controller to attach the medium to.</desc>
4837 </param>
4838 <param name="controllerPort" type="long" dir="in">
4839 <desc>Port to attach the medium to.</desc>
4840 </param>
4841 <param name="device" type="long" dir="in">
4842 <desc>Device slot in the given port to attach the medium to.</desc>
4843 </param>
4844 <param name="medium" type="IMedium" dir="in">
4845 <desc>Medium to mount or NULL for an empty drive.</desc>
4846 </param>
4847 <param name="force" type="boolean" dir="in">
4848 <desc>Allows to force unmount/mount of a medium which is locked by
4849 the device slot in the given port to attach the medium to.</desc>
4850 </param>
4851 </method>
4852
4853 <method name="getMedium" const="yes">
4854 <desc>
4855 Returns the virtual medium attached to a device slot of the specified
4856 bus.
4857
4858 Note that if the medium was indirectly attached by
4859 <link to="#mountMedium"/> to the given device slot then this
4860 method will return not the same object as passed to the
4861 <link to="#mountMedium"/> call. See <link to="IMedium"/> for
4862 more detailed information about mounting a medium.
4863
4864 <result name="VBOX_E_OBJECT_NOT_FOUND">
4865 No medium attached to given slot/bus.
4866 </result>
4867
4868 </desc>
4869 <param name="name" type="wstring" dir="in">
4870 <desc>Name of the storage controller the medium is attached to.</desc>
4871 </param>
4872 <param name="controllerPort" type="long" dir="in">
4873 <desc>Port to query.</desc>
4874 </param>
4875 <param name="device" type="long" dir="in">
4876 <desc>Device slot in the given port to query.</desc>
4877 </param>
4878 <param name="medium" type="IMedium" dir="return">
4879 <desc>Attached medium object.</desc>
4880 </param>
4881 </method>
4882
4883 <method name="getMediumAttachmentsOfController" const="yes">
4884 <desc>
4885 Returns an array of medium attachments which are attached to the
4886 the controller with the given name.
4887
4888 <result name="VBOX_E_OBJECT_NOT_FOUND">
4889 A storage controller with given name doesn't exist.
4890 </result>
4891 </desc>
4892 <param name="name" type="wstring" dir="in"/>
4893 <param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
4894 </method>
4895
4896 <method name="getMediumAttachment" const="yes">
4897 <desc>
4898 Returns a medium attachment which corresponds to the controller with
4899 the given name, on the given port and device slot.
4900
4901 <result name="VBOX_E_OBJECT_NOT_FOUND">
4902 No attachment exists for the given controller/port/device combination.
4903 </result>
4904 </desc>
4905 <param name="name" type="wstring" dir="in"/>
4906 <param name="controllerPort" type="long" dir="in"/>
4907 <param name="device" type="long" dir="in"/>
4908 <param name="attachment" type="IMediumAttachment" dir="return"/>
4909 </method>
4910
4911 <method name="attachHostPciDevice">
4912 <desc>
4913 Attaches host PCI device with the given (host) PCI address to the
4914 PCI bus of the virtual machine. Please note, that this operation
4915 is two phase, as real attachment will happen when VM will start,
4916 and most information will be delivered as IHostPciDevicePlugEvent
4917 on IVirtualBox event source.
4918
4919 <see><link to="IHostPciDevicePlugEvent"/></see>
4920
4921 <result name="VBOX_E_INVALID_VM_STATE">
4922 Virtual machine state is not stopped (PCI hotplug not yet implemented).
4923 </result>
4924 <result name="VBOX_E_PDM_ERROR">
4925 Virtual machine does not have a PCI controller allowing attachment of physical devices.
4926 </result>
4927 <result name="VBOX_E_NOT_SUPPORTED">
4928 Hardware or host OS doesn't allow PCI device passthrought.
4929 </result>
4930 </desc>
4931 <param name="hostAddress" type="long" dir="in">
4932 <desc>Address of the host PCI device.</desc>
4933 </param>
4934 <param name="desiredGuestAddress" type="long" dir="in">
4935 <desc>Desired position of this device on guest PCI bus.</desc>
4936 </param>
4937 <param name="tryToUnbind" type="boolean" dir="in">
4938 <desc>If VMM shall try to unbind existing drivers from the
4939 device before attaching it to the guest.</desc>
4940 </param>
4941 </method>
4942
4943 <method name="detachHostPciDevice">
4944 <desc>
4945 Detach host PCI device from the virtual machine.
4946 Also HostPciDevicePlugEvent on IVirtualBox event source
4947 will be delivered. As currently we don't support hot device
4948 unplug, IHostPciDevicePlugEvent event is delivered immediately.
4949
4950 <see><link to="IHostPciDevicePlugEvent"/></see>
4951
4952 <result name="VBOX_E_INVALID_VM_STATE">
4953 Virtual machine state is not stopped (PCI hotplug not yet implemented).
4954 </result>
4955 <result name="VBOX_E_OBJECT_NOT_FOUND">
4956 This host device is not attached to this machine.
4957 </result>
4958 <result name="VBOX_E_PDM_ERROR">
4959 Virtual machine does not have a PCI controller allowing attachment of physical devices.
4960 </result>
4961 <result name="VBOX_E_NOT_SUPPORTED">
4962 Hardware or host OS doesn't allow PCI device passthrought.
4963 </result>
4964 </desc>
4965 <param name="hostAddress" type="long" dir="in">
4966 <desc>Address of the host PCI device.</desc>
4967 </param>
4968 </method>
4969
4970 <method name="getNetworkAdapter" const="yes">
4971 <desc>
4972 Returns the network adapter associated with the given slot.
4973 Slots are numbered sequentially, starting with zero. The total
4974 number of adapters per machine is defined by the
4975 <link to="ISystemProperties::getMaxNetworkAdapters"/> property,
4976 so the maximum slot number is one less than that property's value.
4977
4978 <result name="E_INVALIDARG">
4979 Invalid @a slot number.
4980 </result>
4981
4982 </desc>
4983 <param name="slot" type="unsigned long" dir="in"/>
4984 <param name="adapter" type="INetworkAdapter" dir="return"/>
4985 </method>
4986
4987 <method name="addStorageController">
4988 <desc>
4989 Adds a new storage controller (SCSI, SAS or SATA controller) to the
4990 machine and returns it as an instance of
4991 <link to="IStorageController" />.
4992
4993 @a name identifies the controller for subsequent calls such as
4994 <link to="#getStorageControllerByName" />,
4995 <link to="#getStorageControllerByInstance" />,
4996 <link to="#removeStorageController" />,
4997 <link to="#attachDevice" /> or <link to="#mountMedium" />.
4998
4999 After the controller has been added, you can set its exact
5000 type by setting the <link to="IStorageController::controllerType" />.
5001
5002 <result name="VBOX_E_OBJECT_IN_USE">
5003 A storage controller with given name exists already.
5004 </result>
5005 <result name="E_INVALIDARG">
5006 Invalid @a controllerType.
5007 </result>
5008 </desc>
5009 <param name="name" type="wstring" dir="in"/>
5010 <param name="connectionType" type="StorageBus" dir="in"/>
5011 <param name="controller" type="IStorageController" dir="return"/>
5012 </method>
5013
5014 <method name="getStorageControllerByName" const="yes">
5015 <desc>
5016 Returns a storage controller with the given name.
5017
5018 <result name="VBOX_E_OBJECT_NOT_FOUND">
5019 A storage controller with given name doesn't exist.
5020 </result>
5021 </desc>
5022 <param name="name" type="wstring" dir="in"/>
5023 <param name="storageController" type="IStorageController" dir="return"/>
5024 </method>
5025
5026 <method name="getStorageControllerByInstance" const="yes">
5027 <desc>
5028 Returns a storage controller with the given instance number.
5029
5030 <result name="VBOX_E_OBJECT_NOT_FOUND">
5031 A storage controller with given instance number doesn't exist.
5032 </result>
5033 </desc>
5034 <param name="instance" type="unsigned long" dir="in"/>
5035 <param name="storageController" type="IStorageController" dir="return"/>
5036 </method>
5037
5038 <method name="removeStorageController">
5039 <desc>
5040 Removes a storage controller from the machine.
5041
5042 <result name="VBOX_E_OBJECT_NOT_FOUND">
5043 A storage controller with given name doesn't exist.
5044 </result>
5045 </desc>
5046 <param name="name" type="wstring" dir="in"/>
5047 </method>
5048
5049 <method name="setStorageControllerBootable">
5050 <desc>
5051 Sets the bootable flag of the storage controller with the given name.
5052
5053 <result name="VBOX_E_OBJECT_NOT_FOUND">
5054 A storage controller with given name doesn't exist.
5055 </result>
5056 <result name="VBOX_E_OBJECT_IN_USE">
5057 Another storage controller is marked as bootable already.
5058 </result>
5059 </desc>
5060 <param name="name" type="wstring" dir="in"/>
5061 <param name="bootable" type="boolean" dir="in"/>
5062 </method>
5063
5064 <method name="getSerialPort" const="yes">
5065 <desc>
5066 Returns the serial port associated with the given slot.
5067 Slots are numbered sequentially, starting with zero. The total
5068 number of serial ports per machine is defined by the
5069 <link to="ISystemProperties::serialPortCount"/> property,
5070 so the maximum slot number is one less than that property's value.
5071
5072 <result name="E_INVALIDARG">
5073 Invalid @a slot number.
5074 </result>
5075
5076 </desc>
5077 <param name="slot" type="unsigned long" dir="in"/>
5078 <param name="port" type="ISerialPort" dir="return"/>
5079 </method>
5080
5081 <method name="getParallelPort" const="yes">
5082 <desc>
5083 Returns the parallel port associated with the given slot.
5084 Slots are numbered sequentially, starting with zero. The total
5085 number of parallel ports per machine is defined by the
5086 <link to="ISystemProperties::parallelPortCount"/> property,
5087 so the maximum slot number is one less than that property's value.
5088
5089 <result name="E_INVALIDARG">
5090 Invalid @a slot number.
5091 </result>
5092
5093 </desc>
5094 <param name="slot" type="unsigned long" dir="in"/>
5095 <param name="port" type="IParallelPort" dir="return"/>
5096 </method>
5097
5098 <method name="getExtraDataKeys">
5099 <desc>
5100 Returns an array representing the machine-specific extra data keys
5101 which currently have values defined.
5102 </desc>
5103 <param name="value" type="wstring" dir="return" safearray="yes">
5104 <desc>Array of extra data keys.</desc>
5105 </param>
5106 </method>
5107
5108 <method name="getExtraData">
5109 <desc>
5110 Returns associated machine-specific extra data.
5111
5112 If the requested data @a key does not exist, this function will
5113 succeed and return an empty string in the @a value argument.
5114
5115 <result name="VBOX_E_FILE_ERROR">
5116 Settings file not accessible.
5117 </result>
5118 <result name="VBOX_E_XML_ERROR">
5119 Could not parse the settings file.
5120 </result>
5121
5122 </desc>
5123 <param name="key" type="wstring" dir="in">
5124 <desc>Name of the data key to get.</desc>
5125 </param>
5126 <param name="value" type="wstring" dir="return">
5127 <desc>Value of the requested data key.</desc>
5128 </param>
5129 </method>
5130
5131 <method name="setExtraData">
5132 <desc>
5133 Sets associated machine-specific extra data.
5134
5135 If you pass @c null or an empty string as a key @a value, the given
5136 @a key will be deleted.
5137
5138 <note>
5139 Before performing the actual data change, this method will ask all
5140 registered listeners using the
5141 <link to="IExtraDataCanChangeEvent"/>
5142 notification for a permission. If one of the listeners refuses the
5143 new value, the change will not be performed.
5144 </note>
5145 <note>
5146 On success, the
5147 <link to="IExtraDataChangedEvent"/> notification
5148 is called to inform all registered listeners about a successful data
5149 change.
5150 </note>
5151 <note>
5152 This method can be called outside the machine session and therefore
5153 it's a caller's responsibility to handle possible race conditions
5154 when several clients change the same key at the same time.
5155 </note>
5156
5157 <result name="VBOX_E_FILE_ERROR">
5158 Settings file not accessible.
5159 </result>
5160 <result name="VBOX_E_XML_ERROR">
5161 Could not parse the settings file.
5162 </result>
5163
5164 </desc>
5165 <param name="key" type="wstring" dir="in">
5166 <desc>Name of the data key to set.</desc>
5167 </param>
5168 <param name="value" type="wstring" dir="in">
5169 <desc>Value to assign to the key.</desc>
5170 </param>
5171 </method>
5172
5173 <method name="getCPUProperty" const="yes">
5174 <desc>
5175 Returns the virtual CPU boolean value of the specified property.
5176
5177 <result name="E_INVALIDARG">
5178 Invalid property.
5179 </result>
5180
5181 </desc>
5182 <param name="property" type="CPUPropertyType" dir="in">
5183 <desc>
5184 Property type to query.
5185 </desc>
5186 </param>
5187 <param name="value" type="boolean" dir="return">
5188 <desc>
5189 Property value.
5190 </desc>
5191 </param>
5192 </method>
5193
5194 <method name="setCPUProperty">
5195 <desc>
5196 Sets the virtual CPU boolean value of the specified property.
5197
5198 <result name="E_INVALIDARG">
5199 Invalid property.
5200 </result>
5201
5202 </desc>
5203 <param name="property" type="CPUPropertyType" dir="in">
5204 <desc>
5205 Property type to query.
5206 </desc>
5207 </param>
5208 <param name="value" type="boolean" dir="in">
5209 <desc>
5210 Property value.
5211 </desc>
5212 </param>
5213 </method>
5214
5215 <method name="getCPUIDLeaf" const="yes">
5216 <desc>
5217 Returns the virtual CPU cpuid information for the specified leaf.
5218
5219 Currently supported index values for cpuid:
5220 Standard CPUID leafs: 0 - 0xA
5221 Extended CPUID leafs: 0x80000000 - 0x8000000A
5222
5223 See the Intel and AMD programmer's manuals for detailed information
5224 about the cpuid instruction and its leafs.
5225 <result name="E_INVALIDARG">
5226 Invalid id.
5227 </result>
5228
5229 </desc>
5230 <param name="id" type="unsigned long" dir="in">
5231 <desc>
5232 CPUID leaf index.
5233 </desc>
5234 </param>
5235 <param name="valEax" type="unsigned long" dir="out">
5236 <desc>
5237 CPUID leaf value for register eax.
5238 </desc>
5239 </param>
5240 <param name="valEbx" type="unsigned long" dir="out">
5241 <desc>
5242 CPUID leaf value for register ebx.
5243 </desc>
5244 </param>
5245 <param name="valEcx" type="unsigned long" dir="out">
5246 <desc>
5247 CPUID leaf value for register ecx.
5248 </desc>
5249 </param>
5250 <param name="valEdx" type="unsigned long" dir="out">
5251 <desc>
5252 CPUID leaf value for register edx.
5253 </desc>
5254 </param>
5255 </method>
5256
5257 <method name="setCPUIDLeaf">
5258 <desc>
5259 Sets the virtual CPU cpuid information for the specified leaf. Note that these values
5260 are not passed unmodified. VirtualBox clears features that it doesn't support.
5261
5262 Currently supported index values for cpuid:
5263 Standard CPUID leafs: 0 - 0xA
5264 Extended CPUID leafs: 0x80000000 - 0x8000000A
5265
5266 See the Intel and AMD programmer's manuals for detailed information
5267 about the cpuid instruction and its leafs.
5268
5269 Do not use this method unless you know exactly what you're doing. Misuse can lead to
5270 random crashes inside VMs.
5271 <result name="E_INVALIDARG">
5272 Invalid id.
5273 </result>
5274
5275 </desc>
5276 <param name="id" type="unsigned long" dir="in">
5277 <desc>
5278 CPUID leaf index.
5279 </desc>
5280 </param>
5281 <param name="valEax" type="unsigned long" dir="in">
5282 <desc>
5283 CPUID leaf value for register eax.
5284 </desc>
5285 </param>
5286 <param name="valEbx" type="unsigned long" dir="in">
5287 <desc>
5288 CPUID leaf value for register ebx.
5289 </desc>
5290 </param>
5291 <param name="valEcx" type="unsigned long" dir="in">
5292 <desc>
5293 CPUID leaf value for register ecx.
5294 </desc>
5295 </param>
5296 <param name="valEdx" type="unsigned long" dir="in">
5297 <desc>
5298 CPUID leaf value for register edx.
5299 </desc>
5300 </param>
5301 </method>
5302
5303 <method name="removeCPUIDLeaf">
5304 <desc>
5305 Removes the virtual CPU cpuid leaf for the specified index
5306
5307 <result name="E_INVALIDARG">
5308 Invalid id.
5309 </result>
5310
5311 </desc>
5312 <param name="id" type="unsigned long" dir="in">
5313 <desc>
5314 CPUID leaf index.
5315 </desc>
5316 </param>
5317 </method>
5318
5319 <method name="removeAllCPUIDLeaves">
5320 <desc>
5321 Removes all the virtual CPU cpuid leaves
5322 </desc>
5323 </method>
5324
5325 <method name="getHWVirtExProperty" const="yes">
5326 <desc>
5327 Returns the value of the specified hardware virtualization boolean property.
5328
5329 <result name="E_INVALIDARG">
5330 Invalid property.
5331 </result>
5332
5333 </desc>
5334 <param name="property" type="HWVirtExPropertyType" dir="in">
5335 <desc>
5336 Property type to query.
5337 </desc>
5338 </param>
5339 <param name="value" type="boolean" dir="return">
5340 <desc>
5341 Property value.
5342 </desc>
5343 </param>
5344 </method>
5345
5346 <method name="setHWVirtExProperty">
5347 <desc>
5348 Sets a new value for the specified hardware virtualization boolean property.
5349
5350 <result name="E_INVALIDARG">
5351 Invalid property.
5352 </result>
5353
5354 </desc>
5355 <param name="property" type="HWVirtExPropertyType" dir="in">
5356 <desc>
5357 Property type to set.
5358 </desc>
5359 </param>
5360 <param name="value" type="boolean" dir="in">
5361 <desc>
5362 New property value.
5363 </desc>
5364 </param>
5365 </method>
5366
5367 <method name="saveSettings">
5368 <desc>
5369 Saves any changes to machine settings made since the session
5370 has been opened or a new machine has been created, or since the
5371 last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
5372 For registered machines, new settings become visible to all
5373 other VirtualBox clients after successful invocation of this
5374 method.
5375 <note>
5376 The method sends <link to="IMachineDataChangedEvent"/>
5377 notification event after the configuration has been successfully
5378 saved (only for registered machines).
5379 </note>
5380 <note>
5381 Calling this method is only valid on instances returned
5382 by <link to="ISession::machine"/> and on new machines
5383 created by <link to="IVirtualBox::createMachine"/> but not
5384 yet registered, or on unregistered machines after calling
5385 <link to="IMachine::unregister"/>.
5386 </note>
5387
5388 <result name="VBOX_E_FILE_ERROR">
5389 Settings file not accessible.
5390 </result>
5391 <result name="VBOX_E_XML_ERROR">
5392 Could not parse the settings file.
5393 </result>
5394 <result name="E_ACCESSDENIED">
5395 Modification request refused.
5396 </result>
5397
5398 </desc>
5399 </method>
5400
5401 <method name="discardSettings">
5402 <desc>
5403 Discards any changes to the machine settings made since the session
5404 has been opened or since the last call to <link to="#saveSettings"/>
5405 or <link to="#discardSettings"/>.
5406 <note>
5407 Calling this method is only valid on instances returned
5408 by <link to="ISession::machine"/> and on new machines
5409 created by <link to="IVirtualBox::createMachine"/> or
5410 opened by <link to="IVirtualBox::openMachine"/> but not
5411 yet registered, or on unregistered machines after calling
5412 <link to="IMachine::unregister"/>.
5413 </note>
5414
5415 <result name="VBOX_E_INVALID_VM_STATE">
5416 Virtual machine is not mutable.
5417 </result>
5418
5419 </desc>
5420 </method>
5421
5422 <method name="unregister">
5423 <desc>
5424 Unregisters a machine previously registered with
5425 <link to="IVirtualBox::registerMachine"/> and optionally do additional
5426 cleanup before the machine is unregistered.
5427
5428 This method does not delete any files. It only changes the machine configuration and
5429 the list of registered machines in the VirtualBox object. To delete the files which
5430 belonged to the machine, including the XML file of the machine itself, call
5431 <link to="#delete"/>, optionally with the array of IMedium objects which was returned
5432 from this method.
5433
5434 How thoroughly this method cleans up the machine configuration before unregistering
5435 the machine depends on the @a cleanupMode argument.
5436
5437 <ul>
5438 <li>With "UnregisterOnly", the machine will only be unregistered, but no additional
5439 cleanup will be performed. The call will fail if the machine is in "Saved" state
5440 or has any snapshots or any media attached (see <link to="IMediumAttachment" />).
5441 It is the responsibility of the caller to delete all such configuration in this mode.
5442 In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
5443 which it replaces.</li>
5444 <li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
5445 state or if it has snapshots or media attached. All media attached to the current machine
5446 state or in snapshots will be detached. No medium objects will be returned;
5447 all of the machine's media will remain open.</li>
5448 <li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
5449 except that all the hard disk medium objects which were detached from the machine will
5450 be returned as an array. This allows for quickly passing them to the <link to="#delete" />
5451 API for closing and deletion.</li>
5452 <li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
5453 that all media will be returned in the array, including removable media like DVDs and
5454 floppies. This might be useful if the user wants to inspect in detail which media were
5455 attached to the machine. Be careful when passing the media array to <link to="#delete" />
5456 in that case because users will typically want to preserve ISO and RAW image files.</li>
5457 </ul>
5458
5459 A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
5460 resulting IMedium array to <link to="#delete"/>. This way, the machine is completely
5461 deleted with all its saved states and hard disk images, but images for removable
5462 drives (such as ISO and RAW files) will remain on disk.
5463
5464 This API does not verify whether the media files returned in the array are still
5465 attached to other machines (i.e. shared between several machines). If such a shared
5466 image is passed to <link to="#delete" /> however, closing the image will fail there
5467 and the image will be silently skipped.
5468
5469 This API may, however, move media from this machine's media registry to other media
5470 registries (see <link to="IMedium" /> for details on media registries). For machines
5471 created with VirtualBox 4.0 or later, if media from this machine's media registry
5472 are also attached to another machine (shared attachments), each such medium will be
5473 moved to another machine's registry. This is because without this machine's media
5474 registry, the other machine cannot find its media any more and would become inaccessible.
5475
5476 This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
5477 before unregistering it. It may also silently call <link to="#saveSettings"/> on other machines
5478 if media are moved to other machines' media registries.
5479
5480 After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
5481 is fired.
5482
5483 The call will fail if the machine is currently locked (see <link to="ISession" />).
5484
5485 <note>
5486 If the given machine is inaccessible (see <link to="#accessible"/>), it
5487 will be unregistered and fully uninitialized right afterwards. As a result,
5488 the returned machine object will be unusable and an attempt to call
5489 <b>any</b> method will return the "Object not ready" error.
5490 </note>
5491
5492 <result name="VBOX_E_INVALID_OBJECT_STATE">
5493 Machine is currently locked for a session.
5494 </result>
5495 </desc>
5496
5497 <param name="cleanupMode" type="CleanupMode" dir="in">
5498 <desc>How to clean up after the machine has been unregistered.</desc>
5499 </param>
5500 <param name="aMedia" type="IMedium" safearray="yes" dir="return">
5501 <desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
5502 </param>
5503 </method>
5504
5505 <method name="delete">
5506 <desc>
5507 Deletes the files associated with this machine from disk. If medium objects are passed
5508 in with the @a aMedia argument, they are closed and, if closing was successful, their
5509 storage files are deleted as well. For convenience, this array of media files can be
5510 the same as the one returned from a previous <link to="#unregister" /> call.
5511
5512 This method must only be called on machines which are either write-locked (i.e. on instances
5513 returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
5514 registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
5515 <link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
5516
5517 The following files will be deleted by this method:
5518 <ul>
5519 <li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
5520 argument other than "UnregisterOnly", this will delete all saved state files that
5521 the machine had in use; possibly one if the machine was in "Saved" state and one
5522 for each online snapshot that the machine had.</li>
5523 <li>On each medium object passed in the @a aMedia array, this will call
5524 <link to="IMedium::close" />. If that succeeds, this will attempt to delete the
5525 medium's storage on disk. Since the <link to="IMedium::close"/> call will fail if the medium is still
5526 in use, e.g. because it is still attached to a second machine; in that case the
5527 storage will not be deleted.</li>
5528 <li>Finally, the machine's own XML file will be deleted.</li>
5529 </ul>
5530
5531 Since deleting large disk image files can be a time-consuming I/O operation, this
5532 method operates asynchronously and returns an IProgress object to allow the caller
5533 to monitor the progress. There will be one sub-operation for each file that is
5534 being deleted (saved state or medium storage file).
5535
5536 <note>
5537 <link to="#settingsModified"/> will return @c true after this
5538 method successfully returns.
5539 </note>
5540
5541 <result name="VBOX_E_INVALID_VM_STATE">
5542 Machine is registered but not write-locked.
5543 </result>
5544 <result name="VBOX_E_IPRT_ERROR">
5545 Could not delete the settings file.
5546 </result>
5547 </desc>
5548 <param name="aMedia" type="IMedium" safearray="yes" dir="in">
5549 <desc>List of media to be closed and whose storage files will be deleted.</desc>
5550 </param>
5551 <param name="aProgress" type="IProgress" dir="return">
5552 <desc>Progress object to track the operation completion.</desc>
5553 </param>
5554 </method>
5555
5556 <method name="export">
5557 <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5558 steps required to export VirtualBox machines to OVF.
5559 </desc>
5560
5561 <param name="aAppliance" type="IAppliance" dir="in">
5562 <desc>Appliance to export this machine to.</desc>
5563 </param>
5564 <param name="location" type="wstring" dir="in">
5565 <desc>The target location.</desc>
5566 </param>
5567 <param name="aDescription" type="IVirtualSystemDescription" dir="return">
5568 <desc>VirtualSystemDescription object which is created for this machine.</desc>
5569 </param>
5570 </method >
5571
5572 <method name="findSnapshot">
5573 <desc>
5574 Returns a snapshot of this machine with the given name or UUID.
5575
5576 Returns a snapshot of this machine with the given UUID.
5577 A @c null argument can be used to obtain the first snapshot
5578 taken on this machine. To traverse the whole tree of snapshots
5579 starting from the root, inspect the root snapshot's
5580 <link to="ISnapshot::children" /> attribute and recurse over those children.
5581
5582 <result name="VBOX_E_OBJECT_NOT_FOUND">
5583 Virtual machine has no snapshots or snapshot not found.
5584 </result>
5585
5586 </desc>
5587 <param name="nameOrId" type="wstring" dir="in">
5588 <desc>What to search for. Name or UUID of the snapshot to find</desc>
5589 </param>
5590 <param name="snapshot" type="ISnapshot" dir="return">
5591 <desc>Snapshot object with the given name.</desc>
5592 </param>
5593 </method>
5594
5595 <method name="createSharedFolder">
5596 <desc>
5597 Creates a new permanent shared folder by associating the given logical
5598 name with the given host path, adds it to the collection of shared
5599 folders and starts sharing it. Refer to the description of
5600 <link to="ISharedFolder"/> to read more about logical names.
5601
5602 <result name="VBOX_E_OBJECT_IN_USE">
5603 Shared folder already exists.
5604 </result>
5605 <result name="VBOX_E_FILE_ERROR">
5606 Shared folder @a hostPath not accessible.
5607 </result>
5608
5609 </desc>
5610 <param name="name" type="wstring" dir="in">
5611 <desc>Unique logical name of the shared folder.</desc>
5612 </param>
5613 <param name="hostPath" type="wstring" dir="in">
5614 <desc>Full path to the shared folder in the host file system.</desc>
5615 </param>
5616 <param name="writable" type="boolean" dir="in">
5617 <desc>Whether the share is writable or readonly.</desc>
5618 </param>
5619 <param name="automount" type="boolean" dir="in">
5620 <desc>Whether the share gets automatically mounted by the guest
5621 or not.</desc>
5622 </param>
5623 </method>
5624
5625 <method name="removeSharedFolder">
5626 <desc>
5627 Removes the permanent shared folder with the given name previously
5628 created by <link to="#createSharedFolder"/> from the collection of
5629 shared folders and stops sharing it.
5630
5631 <result name="VBOX_E_INVALID_VM_STATE">
5632 Virtual machine is not mutable.
5633 </result>
5634 <result name="VBOX_E_OBJECT_NOT_FOUND">
5635 Shared folder @a name does not exist.
5636 </result>
5637
5638 </desc>
5639 <param name="name" type="wstring" dir="in">
5640 <desc>Logical name of the shared folder to remove.</desc>
5641 </param>
5642 </method>
5643
5644 <method name="canShowConsoleWindow">
5645 <desc>
5646 Returns @c true if the VM console process can activate the
5647 console window and bring it to foreground on the desktop of
5648 the host PC.
5649 <note>
5650 This method will fail if a session for this machine is not
5651 currently open.
5652 </note>
5653
5654 <result name="VBOX_E_INVALID_VM_STATE">
5655 Machine session is not open.
5656 </result>
5657
5658 </desc>
5659 <param name="canShow" type="boolean" dir="return">
5660 <desc>
5661 @c true if the console window can be shown and @c false otherwise.
5662 </desc>
5663 </param>
5664 </method>
5665
5666 <method name="showConsoleWindow">
5667 <desc>
5668 Activates the console window and brings it to foreground on
5669 the desktop of the host PC. Many modern window managers on
5670 many platforms implement some sort of focus stealing
5671 prevention logic, so that it may be impossible to activate
5672 a window without the help of the currently active
5673 application. In this case, this method will return a non-zero
5674 identifier that represents the top-level window of the VM
5675 console process. The caller, if it represents a currently
5676 active process, is responsible to use this identifier (in a
5677 platform-dependent manner) to perform actual window
5678 activation.
5679 <note>
5680 This method will fail if a session for this machine is not
5681 currently open.
5682 </note>
5683
5684 <result name="VBOX_E_INVALID_VM_STATE">
5685 Machine session is not open.
5686 </result>
5687
5688 </desc>
5689 <param name="winId" type="long long" dir="return">
5690 <desc>
5691 Platform-dependent identifier of the top-level VM console
5692 window, or zero if this method has performed all actions
5693 necessary to implement the <i>show window</i> semantics for
5694 the given platform and/or VirtualBox front-end.
5695 </desc>
5696 </param>
5697 </method>
5698
5699 <method name="getGuestProperty" const="yes">
5700 <desc>
5701 Reads an entry from the machine's guest property store.
5702
5703 <result name="VBOX_E_INVALID_VM_STATE">
5704 Machine session is not open.
5705 </result>
5706
5707 </desc>
5708 <param name="name" type="wstring" dir="in">
5709 <desc>
5710 The name of the property to read.
5711 </desc>
5712 </param>
5713 <param name="value" type="wstring" dir="out">
5714 <desc>
5715 The value of the property. If the property does not exist then this
5716 will be empty.
5717 </desc>
5718 </param>
5719 <param name="timestamp" type="long long" dir="out">
5720 <desc>
5721 The time at which the property was last modified, as seen by the
5722 server process.
5723 </desc>
5724 </param>
5725 <param name="flags" type="wstring" dir="out">
5726 <desc>
5727 Additional property parameters, passed as a comma-separated list of
5728 "name=value" type entries.
5729 </desc>
5730 </param>
5731 </method>
5732
5733 <method name="getGuestPropertyValue" const="yes">
5734 <desc>
5735 Reads a value from the machine's guest property store.
5736
5737 <result name="VBOX_E_INVALID_VM_STATE">
5738 Machine session is not open.
5739 </result>
5740
5741 </desc>
5742 <param name="property" type="wstring" dir="in">
5743 <desc>
5744 The name of the property to read.
5745 </desc>
5746 </param>
5747 <param name="value" type="wstring" dir="return">
5748 <desc>
5749 The value of the property. If the property does not exist then this
5750 will be empty.
5751 </desc>
5752 </param>
5753 </method>
5754
5755 <method name="getGuestPropertyTimestamp" const="yes">
5756 <desc>
5757 Reads a property timestamp from the machine's guest property store.
5758
5759 <result name="VBOX_E_INVALID_VM_STATE">
5760 Machine session is not open.
5761 </result>
5762
5763 </desc>
5764 <param name="property" type="wstring" dir="in">
5765 <desc>
5766 The name of the property to read.
5767 </desc>
5768 </param>
5769 <param name="value" type="long long" dir="return">
5770 <desc>
5771 The timestamp. If the property does not exist then this will be
5772 empty.
5773 </desc>
5774 </param>
5775 </method>
5776
5777 <method name="setGuestProperty">
5778 <desc>
5779 Sets, changes or deletes an entry in the machine's guest property
5780 store.
5781
5782 <result name="E_ACCESSDENIED">
5783 Property cannot be changed.
5784 </result>
5785 <result name="E_INVALIDARG">
5786 Invalid @a flags.
5787 </result>
5788 <result name="VBOX_E_INVALID_VM_STATE">
5789 Virtual machine is not mutable or session not open.
5790 </result>
5791 <result name="VBOX_E_INVALID_OBJECT_STATE">
5792 Cannot set transient property when machine not running.
5793 </result>
5794
5795 </desc>
5796 <param name="property" type="wstring" dir="in">
5797 <desc>
5798 The name of the property to set, change or delete.
5799 </desc>
5800 </param>
5801 <param name="value" type="wstring" dir="in">
5802 <desc>
5803 The new value of the property to set, change or delete. If the
5804 property does not yet exist and value is non-empty, it will be
5805 created. If the value is @c null or empty, the property will be
5806 deleted if it exists.
5807 </desc>
5808 </param>
5809 <param name="flags" type="wstring" dir="in">
5810 <desc>
5811 Additional property parameters, passed as a comma-separated list of
5812 "name=value" type entries.
5813 </desc>
5814 </param>
5815 </method>
5816
5817 <method name="setGuestPropertyValue">
5818 <desc>
5819 Sets, changes or deletes a value in the machine's guest property
5820 store. The flags field will be left unchanged or created empty for a
5821 new property.
5822
5823 <result name="E_ACCESSDENIED">
5824 Property cannot be changed.
5825 </result>
5826 <result name="VBOX_E_INVALID_VM_STATE">
5827 Virtual machine is not mutable or session not open.
5828 </result>
5829 <result name="VBOX_E_INVALID_OBJECT_STATE">
5830 Cannot set transient property when machine not running.
5831 </result>
5832 </desc>
5833
5834 <param name="property" type="wstring" dir="in">
5835 <desc>
5836 The name of the property to set, change or delete.
5837 </desc>
5838 </param>
5839 <param name="value" type="wstring" dir="in">
5840 <desc>
5841 The new value of the property to set, change or delete. If the
5842 property does not yet exist and value is non-empty, it will be
5843 created. If the value is @c null or empty, the property will be
5844 deleted if it exists.
5845 </desc>
5846 </param>
5847 </method>
5848
5849 <method name="enumerateGuestProperties" const="yes">
5850 <desc>
5851 Return a list of the guest properties matching a set of patterns along
5852 with their values, time stamps and flags.
5853 </desc>
5854 <param name="patterns" type="wstring" dir="in">
5855 <desc>
5856 The patterns to match the properties against, separated by '|'
5857 characters. If this is empty or @c null, all properties will match.
5858 </desc>
5859 </param>
5860 <param name="name" type="wstring" dir="out" safearray="yes">
5861 <desc>
5862 The names of the properties returned.
5863 </desc>
5864 </param>
5865 <param name="value" type="wstring" dir="out" safearray="yes">
5866 <desc>
5867 The values of the properties returned. The array entries match the
5868 corresponding entries in the @a name array.
5869 </desc>
5870 </param>
5871 <param name="timestamp" type="long long" dir="out" safearray="yes">
5872 <desc>
5873 The time stamps of the properties returned. The array entries match
5874 the corresponding entries in the @a name array.
5875 </desc>
5876 </param>
5877 <param name="flags" type="wstring" dir="out" safearray="yes">
5878 <desc>
5879 The flags of the properties returned. The array entries match the
5880 corresponding entries in the @a name array.
5881 </desc>
5882 </param>
5883 </method>
5884
5885 <method name="querySavedGuestSize" const="yes">
5886 <desc>
5887 Returns the guest dimensions from the saved state.
5888 </desc>
5889 <param name="screenId" type="unsigned long" dir="in">
5890 <desc>
5891 Saved guest screen to query info from.
5892 </desc>
5893 </param>
5894 <param name="width" type="unsigned long" dir="out">
5895 <desc>
5896 Guest width at the time of the saved state was taken.
5897 </desc>
5898 </param>
5899 <param name="height" type="unsigned long" dir="out">
5900 <desc>
5901 Guest height at the time of the saved state was taken.
5902 </desc>
5903 </param>
5904 </method>
5905
5906 <method name="querySavedThumbnailSize">
5907 <desc>
5908 Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
5909 </desc>
5910 <param name="screenId" type="unsigned long" dir="in">
5911 <desc>
5912 Saved guest screen to query info from.
5913 </desc>
5914 </param>
5915 <param name="size" type="unsigned long" dir="out">
5916 <desc>
5917 Size of buffer required to store the bitmap.
5918 </desc>
5919 </param>
5920 <param name="width" type="unsigned long" dir="out">
5921 <desc>
5922 Bitmap width.
5923 </desc>
5924 </param>
5925 <param name="height" type="unsigned long" dir="out">
5926 <desc>
5927 Bitmap height.
5928 </desc>
5929 </param>
5930 </method>
5931
5932 <method name="readSavedThumbnailToArray">
5933 <desc>
5934 Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
5935 </desc>
5936 <param name="screenId" type="unsigned long" dir="in">
5937 <desc>
5938 Saved guest screen to read from.
5939 </desc>
5940 </param>
5941 <param name="BGR" type="boolean" dir="in">
5942 <desc>
5943 How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
5944 bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
5945 </desc>
5946 </param>
5947 <param name="width" type="unsigned long" dir="out">
5948 <desc>
5949 Bitmap width.
5950 </desc>
5951 </param>
5952 <param name="height" type="unsigned long" dir="out">
5953 <desc>
5954 Bitmap height.
5955 </desc>
5956 </param>
5957 <param name="data" type="octet" safearray="yes" dir="return">
5958 <desc>
5959 Array with resulting bitmap data.
5960 </desc>
5961 </param>
5962 </method>
5963
5964 <method name="readSavedThumbnailPNGToArray">
5965 <desc>
5966 Thumbnail in PNG format is retrieved to an array of bytes.
5967 </desc>
5968 <param name="screenId" type="unsigned long" dir="in">
5969 <desc>
5970 Saved guest screen to read from.
5971 </desc>
5972 </param>
5973 <param name="width" type="unsigned long" dir="out">
5974 <desc>
5975 Image width.
5976 </desc>
5977 </param>
5978 <param name="height" type="unsigned long" dir="out">
5979 <desc>
5980 Image height.
5981 </desc>
5982 </param>
5983 <param name="data" type="octet" dir="return" safearray="yes">
5984 <desc>
5985 Array with resulting PNG data.
5986 </desc>
5987 </param>
5988 </method>
5989
5990 <method name="querySavedScreenshotPNGSize">
5991 <desc>
5992 Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
5993 </desc>
5994 <param name="screenId" type="unsigned long" dir="in">
5995 <desc>
5996 Saved guest screen to query info from.
5997 </desc>
5998 </param>
5999 <param name="size" type="unsigned long" dir="out">
6000 <desc>
6001 Size of buffer required to store the PNG binary data.
6002 </desc>
6003 </param>
6004 <param name="width" type="unsigned long" dir="out">
6005 <desc>
6006 Image width.
6007 </desc>
6008 </param>
6009 <param name="height" type="unsigned long" dir="out">
6010 <desc>
6011 Image height.
6012 </desc>
6013 </param>
6014 </method>
6015
6016 <method name="readSavedScreenshotPNGToArray">
6017 <desc>
6018 Screenshot in PNG format is retrieved to an array of bytes.
6019 </desc>
6020 <param name="screenId" type="unsigned long" dir="in">
6021 <desc>
6022 Saved guest screen to read from.
6023 </desc>
6024 </param>
6025 <param name="width" type="unsigned long" dir="out">
6026 <desc>
6027 Image width.
6028 </desc>
6029 </param>
6030 <param name="height" type="unsigned long" dir="out">
6031 <desc>
6032 Image height.
6033 </desc>
6034 </param>
6035 <param name="data" type="octet" dir="return" safearray="yes">
6036 <desc>
6037 Array with resulting PNG data.
6038 </desc>
6039 </param>
6040 </method>
6041
6042 <method name="hotPlugCPU">
6043 <desc>
6044 Plugs a CPU into the machine.
6045 </desc>
6046 <param name="cpu" type="unsigned long" dir="in">
6047 <desc>
6048 The CPU id to insert.
6049 </desc>
6050 </param>
6051 </method>
6052
6053 <method name="hotUnplugCPU">
6054 <desc>
6055 Removes a CPU from the machine.
6056 </desc>
6057 <param name="cpu" type="unsigned long" dir="in">
6058 <desc>
6059 The CPU id to remove.
6060 </desc>
6061 </param>
6062 </method>
6063
6064 <method name="getCPUStatus">
6065 <desc>
6066 Returns the current status of the given CPU.
6067 </desc>
6068 <param name="cpu" type="unsigned long" dir="in">
6069 <desc>
6070 The CPU id to check for.
6071 </desc>
6072 </param>
6073 <param name="attached" type="boolean" dir="return">
6074 <desc>
6075 Status of the CPU.
6076 </desc>
6077 </param>
6078 </method>
6079
6080 <method name="queryLogFilename">
6081 <desc>
6082 Queries for the VM log file name of an given index. Returns an empty
6083 string if a log file with that index doesn't exists.
6084 </desc>
6085 <param name="idx" type="unsigned long" dir="in">
6086 <desc>
6087 Which log file name to query. 0=current log file.
6088 </desc>
6089 </param>
6090 <param name="filename" type="wstring" dir="return">
6091 <desc>
6092 On return the full path to the log file or an empty string on error.
6093 </desc>
6094 </param>
6095 </method>
6096
6097 <method name="readLog">
6098 <desc>
6099 Reads the VM log file. The chunk size is limited, so even if you
6100 ask for a big piece there might be less data returned.
6101 </desc>
6102 <param name="idx" type="unsigned long" dir="in">
6103 <desc>
6104 Which log file to read. 0=current log file.
6105 </desc>
6106 </param>
6107 <param name="offset" type="long long" dir="in">
6108 <desc>
6109 Offset in the log file.
6110 </desc>
6111 </param>
6112 <param name="size" type="long long" dir="in">
6113 <desc>
6114 Chunk size to read in the log file.
6115 </desc>
6116 </param>
6117 <param name="data" type="octet" dir="return" safearray="yes">
6118 <desc>
6119 Data read from the log file. A data size of 0 means end of file
6120 if the requested chunk size was not 0. This is the unprocessed
6121 file data, i.e. the line ending style depends on the platform of
6122 the system the server is running on.
6123 </desc>
6124 </param>
6125 </method>
6126
6127 <method name="cloneTo">
6128 <desc>
6129 Creates a clone of this machine, either as a full clone (which means
6130 creating independent copies of the hard disk media, save states and so
6131 on), or as a linked clone (which uses its own differencing media,
6132 sharing the parent media with the source machine).
6133
6134 The target machine object must have been created previously with <link
6135 to="IVirtualBox::createMachine"/>, and all the settings will be
6136 transferred except the VM name and the hardware UUID. You can set the
6137 VM name and the new hardware UUID when creating the target machine. The
6138 network MAC addresses are newly created for all newtwork adapters. You
6139 can change that behaviour with the options parameter. The operation is
6140 performed asynchronously, so the machine object will be not be usable
6141 until the @a progress object signals completion.
6142
6143 <result name="E_INVALIDARG">
6144 @a target is @c null.
6145 </result>
6146 </desc>
6147
6148 <param name="target" type="IMachine" dir="in">
6149 <desc>Target machine object.</desc>
6150 </param>
6151 <param name="mode" type="CloneMode" dir="in">
6152 <desc>Which states should be cloned.</desc>
6153 </param>
6154 <param name="options" type="CloneOptions" dir="in" safearray="yes">
6155 <desc>Options for the cloning operation.</desc>
6156 </param>
6157 <param name="progress" type="IProgress" dir="return">
6158 <desc>Progress object to track the operation completion.</desc>
6159 </param>
6160 </method>
6161
6162 </interface>
6163
6164 <!--
6165 // IConsole
6166 /////////////////////////////////////////////////////////////////////////
6167 -->
6168
6169 <interface
6170 name="IVRDEServerInfo" extends="$unknown"
6171 uuid="714434a1-58c3-4aab-9049-7652c5df113b"
6172 wsmap="struct"
6173 >
6174 <desc>
6175 Contains information about the remote desktop (VRDE) server capabilities and status.
6176 This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
6177 </desc>
6178
6179 <attribute name="active" type="boolean" readonly="yes">
6180 <desc>
6181 Whether the remote desktop connection is active.
6182 </desc>
6183 </attribute>
6184
6185 <attribute name="port" type="long" readonly="yes">
6186 <desc>
6187 VRDE server port number. If this property is equal to <tt>0</tt>, then
6188 the VRDE server failed to start, usually because there are no free IP
6189 ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
6190 server has not yet been started.
6191 </desc>
6192 </attribute>
6193
6194 <attribute name="numberOfClients" type="unsigned long" readonly="yes">
6195 <desc>
6196 How many times a client connected.
6197 </desc>
6198 </attribute>
6199
6200 <attribute name="beginTime" type="long long" readonly="yes">
6201 <desc>
6202 When the last connection was established, in milliseconds since 1970-01-01 UTC.
6203 </desc>
6204 </attribute>
6205
6206 <attribute name="endTime" type="long long" readonly="yes">
6207 <desc>
6208 When the last connection was terminated or the current time, if
6209 connection is still active, in milliseconds since 1970-01-01 UTC.
6210 </desc>
6211 </attribute>
6212
6213 <attribute name="bytesSent" type="long long" readonly="yes">
6214 <desc>
6215 How many bytes were sent in last or current, if still active, connection.
6216 </desc>
6217 </attribute>
6218
6219 <attribute name="bytesSentTotal" type="long long" readonly="yes">
6220 <desc>
6221 How many bytes were sent in all connections.
6222 </desc>
6223 </attribute>
6224
6225 <attribute name="bytesReceived" type="long long" readonly="yes">
6226 <desc>
6227 How many bytes were received in last or current, if still active, connection.
6228 </desc>
6229 </attribute>
6230
6231 <attribute name="bytesReceivedTotal" type="long long" readonly="yes">
6232 <desc>
6233 How many bytes were received in all connections.
6234 </desc>
6235 </attribute>
6236
6237 <attribute name="user" type="wstring" readonly="yes">
6238 <desc>
6239 Login user name supplied by the client.
6240 </desc>
6241 </attribute>
6242
6243 <attribute name="domain" type="wstring" readonly="yes">
6244 <desc>
6245 Login domain name supplied by the client.
6246 </desc>
6247 </attribute>
6248
6249 <attribute name="clientName" type="wstring" readonly="yes">
6250 <desc>
6251 The client name supplied by the client.
6252 </desc>
6253 </attribute>
6254
6255 <attribute name="clientIP" type="wstring" readonly="yes">
6256 <desc>
6257 The IP address of the client.
6258 </desc>
6259 </attribute>
6260
6261 <attribute name="clientVersion" type="unsigned long" readonly="yes">
6262 <desc>
6263 The client software version number.
6264 </desc>
6265 </attribute>
6266
6267 <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
6268 <desc>
6269 Public key exchange method used when connection was established.
6270 Values: 0 - RDP4 public key exchange scheme.
6271 1 - X509 certificates were sent to client.
6272 </desc>
6273 </attribute>
6274
6275 </interface>
6276
6277 <interface
6278 name="IConsole" extends="$unknown"
6279 uuid="1968b7d3-e3bf-4ceb-99e0-cb7c913317bb"
6280 wsmap="managed"
6281 >
6282 <desc>
6283 The IConsole interface represents an interface to control virtual
6284 machine execution.
6285
6286 A console object gets created when a machine has been locked for a
6287 particular session (client process) using <link to="IMachine::lockMachine" />
6288 or <link to="IMachine::launchVMProcess"/>. The console object can
6289 then be found in the session's <link to="ISession::console" /> attribute.
6290
6291 Methods of the IConsole interface allow the caller to query the current
6292 virtual machine execution state, pause the machine or power it down, save
6293 the machine state or take a snapshot, attach and detach removable media
6294 and so on.
6295
6296 <see><link to="ISession"/></see>
6297 </desc>
6298
6299 <attribute name="machine" type="IMachine" readonly="yes">
6300 <desc>
6301 Machine object for this console session.
6302 <note>
6303 This is a convenience property, it has the same value as
6304 <link to="ISession::machine"/> of the corresponding session
6305 object.
6306 </note>
6307 </desc>
6308 </attribute>
6309
6310 <attribute name="state" type="MachineState" readonly="yes">
6311 <desc>
6312 Current execution state of the machine.
6313 <note>
6314 This property always returns the same value as the corresponding
6315 property of the IMachine object for this console session.
6316 For the process that owns (executes) the VM, this is the
6317 preferable way of querying the VM state, because no IPC
6318 calls are made.
6319 </note>
6320 </desc>
6321 </attribute>
6322
6323 <attribute name="guest" type="IGuest" readonly="yes">
6324 <desc>Guest object.</desc>
6325 </attribute>
6326
6327 <attribute name="keyboard" type="IKeyboard" readonly="yes">
6328 <desc>
6329 Virtual keyboard object.
6330 <note>
6331 If the machine is not running, any attempt to use
6332 the returned object will result in an error.
6333 </note>
6334 </desc>
6335 </attribute>
6336
6337 <attribute name="mouse" type="IMouse" readonly="yes">
6338 <desc>
6339 Virtual mouse object.
6340 <note>
6341 If the machine is not running, any attempt to use
6342 the returned object will result in an error.
6343 </note>
6344 </desc>
6345 </attribute>
6346
6347 <attribute name="display" type="IDisplay" readonly="yes">
6348 <desc>Virtual display object.
6349 <note>
6350 If the machine is not running, any attempt to use
6351 the returned object will result in an error.
6352 </note>
6353 </desc>
6354 </attribute>
6355
6356 <attribute name="debugger" type="IMachineDebugger" readonly="yes">
6357 <desc>Debugging interface.</desc>
6358 </attribute>
6359
6360 <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6361 <desc>
6362 Collection of USB devices currently attached to the virtual
6363 USB controller.
6364 <note>
6365 The collection is empty if the machine is not running.
6366 </note>
6367 </desc>
6368 </attribute>
6369
6370 <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6371 <desc>
6372 List of USB devices currently attached to the remote VRDE client.
6373 Once a new device is physically attached to the remote host computer,
6374 it appears in this list and remains there until detached.
6375 </desc>
6376 </attribute>
6377
6378 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6379 <desc>
6380 Collection of shared folders for the current session. These folders
6381 are called transient shared folders because they are available to the
6382 guest OS running inside the associated virtual machine only for the
6383 duration of the session (as opposed to
6384 <link to="IMachine::sharedFolders"/> which represent permanent shared
6385 folders). When the session is closed (e.g. the machine is powered down),
6386 these folders are automatically discarded.
6387
6388 New shared folders are added to the collection using
6389 <link to="#createSharedFolder"/>. Existing shared folders can be
6390 removed using <link to="#removeSharedFolder"/>.
6391 </desc>
6392 </attribute>
6393
6394 <attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
6395 <desc>
6396 Interface that provides information on Remote Desktop Extension (VRDE) connection.
6397 </desc>
6398 </attribute>
6399
6400 <attribute name="eventSource" type="IEventSource" readonly="yes">
6401 <desc>
6402 Event source for console events.
6403 </desc>
6404 </attribute>
6405
6406 <attribute name="attachedPciDevices" type="IPciDeviceAttachment" readonly="yes" safearray="yes">
6407 <desc>Array of PCI devices attached to this machine.</desc>
6408 </attribute>
6409
6410 <attribute name="useHostClipboard" type="boolean">
6411 <desc>
6412 Whether the guest clipboard should be connected to the host one or
6413 whether it should only be allowed access to the VRDE clipboard. This
6414 setting may not affect existing guest clipboard connections which
6415 are already connected to the host clipboard.
6416 </desc>
6417 </attribute>
6418
6419 <method name="powerUp">
6420 <desc>
6421 Starts the virtual machine execution using the current machine
6422 state (that is, its current execution state, current settings and
6423 current storage devices).
6424
6425 <note>
6426 This method is only useful for front-ends that want to actually
6427 execute virtual machines in their own process (like the VirtualBox
6428 or VBoxSDL front-ends). Unless you are intending to write such a
6429 front-end, do not call this method. If you simply want to
6430 start virtual machine execution using one of the existing front-ends
6431 (for example the VirtualBox GUI or headless server), use
6432 <link to="IMachine::launchVMProcess"/> instead; these
6433 front-ends will power up the machine automatically for you.
6434 </note>
6435
6436 If the machine is powered off or aborted, the execution will
6437 start from the beginning (as if the real hardware were just
6438 powered on).
6439
6440 If the machine is in the <link to="MachineState_Saved"/> state,
6441 it will continue its execution the point where the state has
6442 been saved.
6443
6444 If the machine <link to="IMachine::teleporterEnabled"/> property is
6445 enabled on the machine being powered up, the machine will wait for an
6446 incoming teleportation in the <link to="MachineState_TeleportingIn"/>
6447 state. The returned progress object will have at least three
6448 operations where the last three are defined as: (1) powering up and
6449 starting TCP server, (2) waiting for incoming teleportations, and
6450 (3) perform teleportation. These operations will be reflected as the
6451 last three operations of the progress objected returned by
6452 <link to="IMachine::launchVMProcess"/> as well.
6453
6454 <see><link to="#saveState"/></see>
6455
6456 <result name="VBOX_E_INVALID_VM_STATE">
6457 Virtual machine already running.
6458 </result>
6459 <result name="VBOX_E_HOST_ERROR">
6460 Host interface does not exist or name not set.
6461 </result>
6462 <result name="VBOX_E_FILE_ERROR">
6463 Invalid saved state file.
6464 </result>
6465 </desc>
6466 <param name="progress" type="IProgress" dir="return">
6467 <desc>Progress object to track the operation completion.</desc>
6468 </param>
6469 </method>
6470
6471 <method name="powerUpPaused">
6472 <desc>
6473 Identical to powerUp except that the VM will enter the
6474 <link to="MachineState_Paused"/> state, instead of
6475 <link to="MachineState_Running"/>.
6476
6477 <see><link to="#powerUp"/></see>
6478 <result name="VBOX_E_INVALID_VM_STATE">
6479 Virtual machine already running.
6480 </result>
6481 <result name="VBOX_E_HOST_ERROR">
6482 Host interface does not exist or name not set.
6483 </result>
6484 <result name="VBOX_E_FILE_ERROR">
6485 Invalid saved state file.
6486 </result>
6487 </desc>
6488 <param name="progress" type="IProgress" dir="return">
6489 <desc>Progress object to track the operation completion.</desc>
6490 </param>
6491 </method>
6492
6493 <method name="powerDown">
6494 <desc>
6495 Initiates the power down procedure to stop the virtual machine
6496 execution.
6497
6498 The completion of the power down procedure is tracked using the returned
6499 IProgress object. After the operation is complete, the machine will go
6500 to the PoweredOff state.
6501 <result name="VBOX_E_INVALID_VM_STATE">
6502 Virtual machine must be Running, Paused or Stuck to be powered down.
6503 </result>
6504 </desc>
6505 <param name="progress" type="IProgress" dir="return">
6506 <desc>Progress object to track the operation completion.</desc>
6507 </param>
6508 </method>
6509
6510 <method name="reset">
6511 <desc>Resets the virtual machine.
6512 <result name="VBOX_E_INVALID_VM_STATE">
6513 Virtual machine not in Running state.
6514 </result>
6515 <result name="VBOX_E_VM_ERROR">
6516 Virtual machine error in reset operation.
6517 </result>
6518 </desc>
6519 </method>
6520
6521 <method name="pause">
6522 <desc>Pauses the virtual machine execution.
6523 <result name="VBOX_E_INVALID_VM_STATE">
6524 Virtual machine not in Running state.
6525 </result>
6526 <result name="VBOX_E_VM_ERROR">
6527 Virtual machine error in suspend operation.
6528 </result>
6529 </desc>
6530 </method>
6531
6532 <method name="resume">
6533 <desc>Resumes the virtual machine execution.
6534 <result name="VBOX_E_INVALID_VM_STATE">
6535 Virtual machine not in Paused state.
6536 </result>
6537 <result name="VBOX_E_VM_ERROR">
6538 Virtual machine error in resume operation.
6539 </result>
6540 </desc>
6541 </method>
6542
6543 <method name="powerButton">
6544 <desc>Sends the ACPI power button event to the guest.
6545 <result name="VBOX_E_INVALID_VM_STATE">
6546 Virtual machine not in Running state.
6547 </result>
6548 <result name="VBOX_E_PDM_ERROR">
6549 Controlled power off failed.
6550 </result>
6551 </desc>
6552 </method>
6553
6554 <method name="sleepButton">
6555 <desc>Sends the ACPI sleep button event to the guest.
6556 <result name="VBOX_E_INVALID_VM_STATE">
6557 Virtual machine not in Running state.
6558 </result>
6559 <result name="VBOX_E_PDM_ERROR">
6560 Sending sleep button event failed.
6561 </result>
6562 </desc>
6563 </method>
6564
6565 <method name="getPowerButtonHandled">
6566 <desc>Checks if the last power button event was handled by guest.
6567 <result name="VBOX_E_PDM_ERROR">
6568 Checking if the event was handled by the guest OS failed.
6569 </result>
6570 </desc>
6571 <param name="handled" type="boolean" dir="return"/>
6572 </method>
6573
6574 <method name="getGuestEnteredACPIMode">
6575 <desc>Checks if the guest entered the ACPI mode G0 (working) or
6576 G1 (sleeping). If this method returns @c false, the guest will
6577 most likely not respond to external ACPI events.
6578 <result name="VBOX_E_INVALID_VM_STATE">
6579 Virtual machine not in Running state.
6580 </result>
6581 </desc>
6582 <param name="entered" type="boolean" dir="return"/>
6583 </method>
6584
6585 <method name="saveState">
6586 <desc>
6587 Saves the current execution state of a running virtual machine
6588 and stops its execution.
6589
6590 After this operation completes, the machine will go to the
6591 Saved state. Next time it is powered up, this state will
6592 be restored and the machine will continue its execution from
6593 the place where it was saved.
6594
6595 This operation differs from taking a snapshot to the effect
6596 that it doesn't create new differencing media. Also, once
6597 the machine is powered up from the state saved using this method,
6598 the saved state is deleted, so it will be impossible to return
6599 to this state later.
6600
6601 <note>
6602 On success, this method implicitly calls
6603 <link to="IMachine::saveSettings"/> to save all current machine
6604 settings (including runtime changes to the DVD medium, etc.).
6605 Together with the impossibility to change any VM settings when it is
6606 in the Saved state, this guarantees adequate hardware
6607 configuration of the machine when it is restored from the saved
6608 state file.
6609 </note>
6610
6611 <note>
6612 The machine must be in the Running or Paused state, otherwise
6613 the operation will fail.
6614 </note>
6615 <result name="VBOX_E_INVALID_VM_STATE">
6616 Virtual machine state neither Running nor Paused.
6617 </result>
6618 <result name="VBOX_E_FILE_ERROR">
6619 Failed to create directory for saved state file.
6620 </result>
6621
6622 <see><link to="#takeSnapshot"/></see>
6623 </desc>
6624 <param name="progress" type="IProgress" dir="return">
6625 <desc>Progress object to track the operation completion.</desc>
6626 </param>
6627 </method>
6628
6629 <method name="adoptSavedState">
6630 <desc>
6631 Associates the given saved state file to the virtual machine.
6632
6633 On success, the machine will go to the Saved state. Next time it is
6634 powered up, it will be restored from the adopted saved state and
6635 continue execution from the place where the saved state file was
6636 created.
6637
6638 The specified saved state file path may be absolute or relative to the
6639 folder the VM normally saves the state to (usually,
6640 <link to="IMachine::snapshotFolder"/>).
6641
6642 <note>
6643 It's a caller's responsibility to make sure the given saved state
6644 file is compatible with the settings of this virtual machine that
6645 represent its virtual hardware (memory size, storage disk configuration
6646 etc.). If there is a mismatch, the behavior of the virtual machine
6647 is undefined.
6648 </note>
6649 <result name="VBOX_E_INVALID_VM_STATE">
6650 Virtual machine state neither PoweredOff nor Aborted.
6651 </result>
6652 </desc>
6653 <param name="savedStateFile" type="wstring" dir="in">
6654 <desc>Path to the saved state file to adopt.</desc>
6655 </param>
6656 </method>
6657
6658 <method name="discardSavedState">
6659 <desc>
6660 Forcibly resets the machine to "Powered Off" state if it is
6661 currently in the "Saved" state (previously created by <link to="#saveState"/>).
6662 Next time the machine is powered up, a clean boot will occur.
6663 <note>
6664 This operation is equivalent to resetting or powering off
6665 the machine without doing a proper shutdown of the guest
6666 operating system; as with resetting a running phyiscal
6667 computer, it can can lead to data loss.
6668 </note>
6669 If @a fRemoveFile is @c true, the file in the machine directory
6670 into which the machine state was saved is also deleted. If
6671 this is @c false, then the state can be recovered and later
6672 re-inserted into a machine using <link to="#adoptSavedState" />.
6673 The location of the file can be found in the
6674 <link to="IMachine::stateFilePath" /> attribute.
6675 <result name="VBOX_E_INVALID_VM_STATE">
6676 Virtual machine not in state Saved.
6677 </result>
6678 </desc>
6679 <param name="fRemoveFile" type="boolean" dir="in" >
6680 <desc>Whether to also remove the saved state file.</desc>
6681 </param>
6682 </method>
6683
6684 <method name="getDeviceActivity">
6685 <desc>
6686 Gets the current activity type of a given device or device group.
6687 <result name="E_INVALIDARG">
6688 Invalid device type.
6689 </result>
6690 </desc>
6691 <param name="type" type="DeviceType" dir="in"/>
6692 <param name="activity" type="DeviceActivity" dir="return"/>
6693 </method>
6694
6695 <method name="attachUSBDevice">
6696 <desc>
6697 Attaches a host USB device with the given UUID to the
6698 USB controller of the virtual machine.
6699
6700 The device needs to be in one of the following states:
6701 <link to="USBDeviceState_Busy"/>,
6702 <link to="USBDeviceState_Available"/> or
6703 <link to="USBDeviceState_Held"/>,
6704 otherwise an error is immediately returned.
6705
6706 When the device state is
6707 <link to="USBDeviceState_Busy">Busy</link>, an error may also
6708 be returned if the host computer refuses to release it for some reason.
6709
6710 <see><link to="IUSBController::deviceFilters"/>,
6711 <link to="USBDeviceState"/></see>
6712 <result name="VBOX_E_INVALID_VM_STATE">
6713 Virtual machine state neither Running nor Paused.
6714 </result>
6715 <result name="VBOX_E_PDM_ERROR">
6716 Virtual machine does not have a USB controller.
6717 </result>
6718 </desc>
6719 <param name="id" type="uuid" mod="string" dir="in">
6720 <desc>UUID of the host USB device to attach.</desc>
6721 </param>
6722 </method>
6723
6724 <method name="detachUSBDevice">
6725 <desc>
6726 Detaches an USB device with the given UUID from the USB controller
6727 of the virtual machine.
6728
6729 After this method succeeds, the VirtualBox server re-initiates
6730 all USB filters as if the device were just physically attached
6731 to the host, but filters of this machine are ignored to avoid
6732 a possible automatic re-attachment.
6733
6734 <see><link to="IUSBController::deviceFilters"/>,
6735 <link to="USBDeviceState"/></see>
6736
6737 <result name="VBOX_E_PDM_ERROR">
6738 Virtual machine does not have a USB controller.
6739 </result>
6740 <result name="E_INVALIDARG">
6741 USB device not attached to this virtual machine.
6742 </result>
6743 </desc>
6744 <param name="id" type="uuid" mod="string" dir="in">
6745 <desc>UUID of the USB device to detach.</desc>
6746 </param>
6747 <param name="device" type="IUSBDevice" dir="return">
6748 <desc>Detached USB device.</desc>
6749 </param>
6750 </method>
6751
6752 <method name="findUSBDeviceByAddress">
6753 <desc>
6754 Searches for a USB device with the given host address.
6755
6756 <result name="VBOX_E_OBJECT_NOT_FOUND">
6757 Given @c name does not correspond to any USB device.
6758 </result>
6759
6760 <see><link to="IUSBDevice::address"/></see>
6761 </desc>
6762 <param name="name" type="wstring" dir="in">
6763 <desc>
6764 Address of the USB device (as assigned by the host) to
6765 search for.
6766 </desc>
6767 </param>
6768 <param name="device" type="IUSBDevice" dir="return">
6769 <desc>Found USB device object.</desc>
6770 </param>
6771 </method>
6772
6773 <method name="findUSBDeviceById">
6774 <desc>
6775 Searches for a USB device with the given UUID.
6776
6777 <result name="VBOX_E_OBJECT_NOT_FOUND">
6778 Given @c id does not correspond to any USB device.
6779 </result>
6780
6781 <see><link to="IUSBDevice::id"/></see>
6782 </desc>
6783 <param name="id" type="uuid" mod="string" dir="in">
6784 <desc>UUID of the USB device to search for.</desc>
6785 </param>
6786 <param name="device" type="IUSBDevice" dir="return">
6787 <desc>Found USB device object.</desc>
6788 </param>
6789 </method>
6790
6791 <method name="createSharedFolder">
6792 <desc>
6793 Creates a transient new shared folder by associating the given logical
6794 name with the given host path, adds it to the collection of shared
6795 folders and starts sharing it. Refer to the description of
6796 <link to="ISharedFolder"/> to read more about logical names.
6797
6798 <result name="VBOX_E_INVALID_VM_STATE">
6799 Virtual machine in Saved state or currently changing state.
6800 </result>
6801 <result name="VBOX_E_FILE_ERROR">
6802 Shared folder already exists or not accessible.
6803 </result>
6804 </desc>
6805 <param name="name" type="wstring" dir="in">
6806 <desc>Unique logical name of the shared folder.</desc>
6807 </param>
6808 <param name="hostPath" type="wstring" dir="in">
6809 <desc>Full path to the shared folder in the host file system.</desc>
6810 </param>
6811 <param name="writable" type="boolean" dir="in">
6812 <desc>Whether the share is writable or readonly</desc>
6813 </param>
6814 <param name="automount" type="boolean" dir="in">
6815 <desc>Whether the share gets automatically mounted by the guest
6816 or not.</desc>
6817 </param>
6818 </method>
6819
6820 <method name="removeSharedFolder">
6821 <desc>
6822 Removes a transient shared folder with the given name previously
6823 created by <link to="#createSharedFolder"/> from the collection of
6824 shared folders and stops sharing it.
6825 <result name="VBOX_E_INVALID_VM_STATE">
6826 Virtual machine in Saved state or currently changing state.
6827 </result>
6828 <result name="VBOX_E_FILE_ERROR">
6829 Shared folder does not exists.
6830 </result>
6831 </desc>
6832 <param name="name" type="wstring" dir="in">
6833 <desc>Logical name of the shared folder to remove.</desc>
6834 </param>
6835 </method>
6836
6837 <method name="takeSnapshot">
6838 <desc>
6839 Saves the current execution state
6840 and all settings of the machine and creates differencing images
6841 for all normal (non-independent) media.
6842 See <link to="ISnapshot" /> for an introduction to snapshots.
6843
6844 This method can be called for a PoweredOff, Saved (see
6845 <link to="#saveState"/>), Running or
6846 Paused virtual machine. When the machine is PoweredOff, an
6847 offline snapshot is created. When the machine is Running a live
6848 snapshot is created, and an online snapshot is is created when Paused.
6849
6850 The taken snapshot is always based on the
6851 <link to="IMachine::currentSnapshot">current snapshot</link>
6852 of the associated virtual machine and becomes a new current snapshot.
6853
6854 <note>
6855 This method implicitly calls <link to="IMachine::saveSettings"/> to
6856 save all current machine settings before taking an offline snapshot.
6857 </note>
6858
6859 <result name="VBOX_E_INVALID_VM_STATE">
6860 Virtual machine currently changing state.
6861 </result>
6862 </desc>
6863 <param name="name" type="wstring" dir="in">
6864 <desc>Short name for the snapshot.</desc>
6865 </param>
6866 <param name="description" type="wstring" dir="in">
6867 <desc>Optional description of the snapshot.</desc>
6868 </param>
6869 <param name="progress" type="IProgress" dir="return">
6870 <desc>Progress object to track the operation completion.</desc>
6871 </param>
6872 </method>
6873
6874 <method name="deleteSnapshot">
6875 <desc>
6876 Starts deleting the specified snapshot asynchronously.
6877 See <link to="ISnapshot" /> for an introduction to snapshots.
6878
6879 The execution state and settings of the associated machine stored in
6880 the snapshot will be deleted. The contents of all differencing media of
6881 this snapshot will be merged with the contents of their dependent child
6882 media to keep the medium chain valid (in other words, all changes
6883 represented by media being deleted will be propagated to their child
6884 medium). After that, this snapshot's differencing medium will be
6885 deleted. The parent of this snapshot will become a new parent for all
6886 its child snapshots.
6887
6888 If the deleted snapshot is the current one, its parent snapshot will
6889 become a new current snapshot. The current machine state is not directly
6890 affected in this case, except that currently attached differencing
6891 media based on media of the deleted snapshot will be also merged as
6892 described above.
6893
6894 If the deleted snapshot is the first or current snapshot, then the
6895 respective IMachine attributes will be adjusted. Deleting the current
6896 snapshot will also implicitly call <link to="IMachine::saveSettings"/>
6897 to make all current machine settings permanent.
6898
6899 Deleting a snapshot has the following preconditions:
6900
6901 <ul>
6902 <li>Child media of all normal media of the deleted snapshot
6903 must be accessible (see <link to="IMedium::state"/>) for this
6904 operation to succeed. If only one running VM refers to all images
6905 which participates in merging the operation can be performed while
6906 the VM is running. Otherwise all virtual machines whose media are
6907 directly or indirectly based on the media of deleted snapshot must
6908 be powered off. In any case, online snapshot deleting usually is
6909 slower than the same operation without any running VM.</li>
6910
6911 <li>You cannot delete the snapshot if a medium attached to it has
6912 more than one child medium (differencing images) because otherwise
6913 merging would be impossible. This might be the case if there is
6914 more than one child snapshot or differencing images were created
6915 for other reason (e.g. implicitly because of multiple machine
6916 attachments).</li>
6917 </ul>
6918
6919 The virtual machine's <link to="IMachine::state">state</link> is
6920 changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
6921 "DeletingSnapshotPaused" while this operation is in progress.
6922
6923 <note>
6924 Merging medium contents can be very time and disk space
6925 consuming, if these media are big in size and have many
6926 children. However, if the snapshot being deleted is the last
6927 (head) snapshot on the branch, the operation will be rather
6928 quick.
6929 </note>
6930 <result name="VBOX_E_INVALID_VM_STATE">
6931 The running virtual machine prevents deleting this snapshot. This
6932 happens only in very specific situations, usually snapshots can be
6933 deleted without trouble while a VM is running. The error message
6934 text explains the reason for the failure.
6935 </result>
6936 </desc>
6937 <param name="id" type="uuid" mod="string" dir="in">
6938 <desc>UUID of the snapshot to delete.</desc>
6939 </param>
6940 <param name="progress" type="IProgress" dir="return">
6941 <desc>Progress object to track the operation completion.</desc>
6942 </param>
6943 </method>
6944
6945 <method name="deleteSnapshotAndAllChildren">
6946 <desc>
6947 Starts deleting the specified snapshot and all its children
6948 asynchronously. See <link to="ISnapshot" /> for an introduction to
6949 snapshots. The conditions and many details are the same as with
6950 <link to="#deleteSnapshot"/>.
6951
6952 This operation is very fast if the snapshot subtree does not include
6953 the current state. It is still significantly faster than deleting the
6954 snapshots one by one if the current state is in the subtree and there
6955 are more than one snapshots from current state to the snapshot which
6956 marks the subtree, since it eliminates the incremental image merging.
6957
6958 <note>This API method is right now not implemented!</note>
6959
6960 <result name="VBOX_E_INVALID_VM_STATE">
6961 The running virtual machine prevents deleting this snapshot. This
6962 happens only in very specific situations, usually snapshots can be
6963 deleted without trouble while a VM is running. The error message
6964 text explains the reason for the failure.
6965 </result>
6966 <result name="E_NOTIMPL">
6967 The method is not implemented yet.
6968 </result>
6969 </desc>
6970 <param name="id" type="uuid" mod="string" dir="in">
6971 <desc>UUID of the snapshot to delete, including all its children.</desc>
6972 </param>
6973 <param name="progress" type="IProgress" dir="return">
6974 <desc>Progress object to track the operation completion.</desc>
6975 </param>
6976 </method>
6977
6978 <method name="deleteSnapshotRange">
6979 <desc>
6980 Starts deleting the specified snapshot range. This is limited to
6981 linear snapshot lists, which means there may not be any other child
6982 snapshots other than the direct sequence between the start and end
6983 snapshot. If the start and end snapshot point to the same snapshot this
6984 method is completely equivalent to <link to="#deleteSnapshot"/>. See
6985 <link to="ISnapshot" /> for an introduction to snapshots. The
6986 conditions and many details are the same as with
6987 <link to="#deleteSnapshot"/>.
6988
6989 This operation is generally faster than deleting snapshots one by one
6990 and often also needs less extra disk space before freeing up disk space
6991 by deleting the removed disk images corresponding to the snapshot.
6992
6993 <note>This API method is right now not implemented!</note>
6994
6995 <result name="VBOX_E_INVALID_VM_STATE">
6996 The running virtual machine prevents deleting this snapshot. This
6997 happens only in very specific situations, usually snapshots can be
6998 deleted without trouble while a VM is running. The error message
6999 text explains the reason for the failure.
7000 </result>
7001 <result name="E_NOTIMPL">
7002 The method is not implemented yet.
7003 </result>
7004 </desc>
7005 <param name="startId" type="uuid" mod="string" dir="in">
7006 <desc>UUID of the first snapshot to delete.</desc>
7007 </param>
7008 <param name="endId" type="uuid" mod="string" dir="in">
7009 <desc>UUID of the last snapshot to delete.</desc>
7010 </param>
7011 <param name="progress" type="IProgress" dir="return">
7012 <desc>Progress object to track the operation completion.</desc>
7013 </param>
7014 </method>
7015
7016 <method name="restoreSnapshot">
7017 <desc>
7018 Starts resetting the machine's current state to the state contained
7019 in the given snapshot, asynchronously. All current settings of the
7020 machine will be reset and changes stored in differencing media
7021 will be lost.
7022 See <link to="ISnapshot" /> for an introduction to snapshots.
7023
7024 After this operation is successfully completed, new empty differencing
7025 media are created for all normal media of the machine.
7026
7027 If the given snapshot is an online snapshot, the machine will go to
7028 the <link to="MachineState_Saved"> saved state</link>, so that the
7029 next time it is powered on, the execution state will be restored
7030 from the state of the snapshot.
7031
7032 <note>
7033 The machine must not be running, otherwise the operation will fail.
7034 </note>
7035
7036 <note>
7037 If the machine state is <link to="MachineState_Saved">Saved</link>
7038 prior to this operation, the saved state file will be implicitly
7039 deleted (as if <link to="IConsole::discardSavedState"/> were
7040 called).
7041 </note>
7042
7043 <result name="VBOX_E_INVALID_VM_STATE">
7044 Virtual machine is running.
7045 </result>
7046 </desc>
7047 <param name="snapshot" type="ISnapshot" dir="in">
7048 <desc>The snapshot to restore the VM state from.</desc>
7049 </param>
7050 <param name="progress" type="IProgress" dir="return">
7051 <desc>Progress object to track the operation completion.</desc>
7052 </param>
7053 </method>
7054
7055 <method name="teleport">
7056 <desc>
7057 Teleport the VM to a different host machine or process.
7058
7059 TODO explain the details.
7060
7061 <result name="VBOX_E_INVALID_VM_STATE">
7062 Virtual machine not running or paused.
7063 </result>
7064 </desc>
7065 <param name="hostname" type="wstring" dir="in">
7066 <desc>The name or IP of the host to teleport to.</desc>
7067 </param>
7068 <param name="tcpport" type="unsigned long" dir="in">
7069 <desc>The TCP port to connect to (1..65535).</desc>
7070 </param>
7071 <param name="password" type="wstring" dir="in">
7072 <desc>The password.</desc>
7073 </param>
7074 <param name="maxDowntime" type="unsigned long" dir="in">
7075 <desc>
7076 The maximum allowed downtime given as milliseconds. 0 is not a valid
7077 value. Recommended value: 250 ms.
7078
7079 The higher the value is, the greater the chance for a successful
7080 teleportation. A small value may easily result in the teleportation
7081 process taking hours and eventually fail.
7082
7083 <note>
7084 The current implementation treats this a guideline, not as an
7085 absolute rule.
7086 </note>
7087 </desc>
7088 </param>
7089 <param name="progress" type="IProgress" dir="return">
7090 <desc>Progress object to track the operation completion.</desc>
7091 </param>
7092 </method>
7093
7094 </interface>
7095
7096 <!--
7097 // IHost
7098 /////////////////////////////////////////////////////////////////////////
7099 -->
7100
7101 <enum
7102 name="HostNetworkInterfaceMediumType"
7103 uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
7104 >
7105 <desc>
7106 Type of encapsulation. Ethernet encapsulation includes both wired and
7107 wireless Ethernet connections.
7108 <see><link to="IHostNetworkInterface"/></see>
7109 </desc>
7110
7111 <const name="Unknown" value="0">
7112 <desc>
7113 The type of interface cannot be determined.
7114 </desc>
7115 </const>
7116 <const name="Ethernet" value="1">
7117 <desc>
7118 Ethernet frame encapsulation.
7119 </desc>
7120 </const>
7121 <const name="PPP" value="2">
7122 <desc>
7123 Point-to-point protocol encapsulation.
7124 </desc>
7125 </const>
7126 <const name="SLIP" value="3">
7127 <desc>
7128 Serial line IP encapsulation.
7129 </desc>
7130 </const>
7131 </enum>
7132
7133 <enum
7134 name="HostNetworkInterfaceStatus"
7135 uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
7136 >
7137 <desc>
7138 Current status of the interface.
7139 <see><link to="IHostNetworkInterface"/></see>
7140 </desc>
7141
7142 <const name="Unknown" value="0">
7143 <desc>
7144 The state of interface cannot be determined.
7145 </desc>
7146 </const>
7147 <const name="Up" value="1">
7148 <desc>
7149 The interface is fully operational.
7150 </desc>
7151 </const>
7152 <const name="Down" value="2">
7153 <desc>
7154 The interface is not functioning.
7155 </desc>
7156 </const>
7157 </enum>
7158
7159 <enum
7160 name="HostNetworkInterfaceType"
7161 uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
7162 >
7163 <desc>
7164 Network interface type.
7165 </desc>
7166 <const name="Bridged" value="1"/>
7167 <const name="HostOnly" value="2"/>
7168 </enum>
7169
7170 <interface
7171 name="IHostNetworkInterface" extends="$unknown"
7172 uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
7173 wsmap="managed"
7174 >
7175 <desc>
7176 Represents one of host's network interfaces. IP V6 address and network
7177 mask are strings of 32 hexdecimal digits grouped by four. Groups are
7178 separated by colons.
7179 For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
7180 </desc>
7181 <attribute name="name" type="wstring" readonly="yes">
7182 <desc>Returns the host network interface name.</desc>
7183 </attribute>
7184
7185 <attribute name="id" type="uuid" mod="string" readonly="yes">
7186 <desc>Returns the interface UUID.</desc>
7187 </attribute>
7188
7189 <attribute name="networkName" type="wstring" readonly="yes">
7190 <desc>Returns the name of a virtual network the interface gets attached to.</desc>
7191 </attribute>
7192
7193 <attribute name="dhcpEnabled" type="boolean" readonly="yes">
7194 <desc>Specifies whether the DHCP is enabled for the interface.</desc>
7195 </attribute>
7196
7197 <attribute name="IPAddress" type="wstring" readonly="yes">
7198 <desc>Returns the IP V4 address of the interface.</desc>
7199 </attribute>
7200
7201 <attribute name="networkMask" type="wstring" readonly="yes">
7202 <desc>Returns the network mask of the interface.</desc>
7203 </attribute>
7204
7205 <attribute name="IPV6Supported" type="boolean" readonly="yes">
7206 <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
7207 </attribute>
7208
7209 <attribute name="IPV6Address" type="wstring" readonly="yes">
7210 <desc>Returns the IP V6 address of the interface.</desc>
7211 </attribute>
7212
7213 <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
7214 <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
7215 </attribute>
7216
7217 <attribute name="hardwareAddress" type="wstring" readonly="yes">
7218 <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
7219 </attribute>
7220
7221 <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
7222 <desc>Type of protocol encapsulation used.</desc>
7223 </attribute>
7224
7225 <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
7226 <desc>Status of the interface.</desc>
7227 </attribute>
7228
7229 <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
7230 <desc>specifies the host interface type.</desc>
7231 </attribute>
7232
7233 <method name="enableStaticIpConfig">
7234 <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
7235 <param name="IPAddress" type="wstring" dir="in">
7236 <desc>
7237 IP address.
7238 </desc>
7239 </param>
7240 <param name="networkMask" type="wstring" dir="in">
7241 <desc>
7242 network mask.
7243 </desc>
7244 </param>
7245 </method>
7246
7247 <method name="enableStaticIpConfigV6">
7248 <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
7249 <param name="IPV6Address" type="wstring" dir="in">
7250 <desc>
7251 IP address.
7252 </desc>
7253 </param>
7254 <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
7255 <desc>
7256 network mask.
7257 </desc>
7258 </param>
7259 </method>
7260
7261 <method name="enableDynamicIpConfig">
7262 <desc>enables the dynamic IP configuration.</desc>
7263 </method>
7264
7265 <method name="dhcpRediscover">
7266 <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
7267 </method>
7268
7269 </interface>
7270
7271 <interface
7272 name="IHost" extends="$unknown"
7273 uuid="dab4a2b8-c735-4f08-94fc-9bec84182e2f"
7274 wsmap="managed"
7275 >
7276 <desc>
7277 The IHost interface represents the physical machine that this VirtualBox
7278 installation runs on.
7279
7280 An object implementing this interface is returned by the
7281 <link to="IVirtualBox::host" /> attribute. This interface contains
7282 read-only information about the host's physical hardware (such as what
7283 processors and disks are available, what the host operating system is,
7284 and so on) and also allows for manipulating some of the host's hardware,
7285 such as global USB device filters and host interface networking.
7286
7287 </desc>
7288 <attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
7289 <desc>List of DVD drives available on the host.</desc>
7290 </attribute>
7291
7292 <attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
7293 <desc>List of floppy drives available on the host.</desc>
7294 </attribute>
7295
7296 <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
7297 <desc>
7298 List of USB devices currently attached to the host.
7299 Once a new device is physically attached to the host computer,
7300 it appears in this list and remains there until detached.
7301
7302 <note>
7303 If USB functionality is not available in the given edition of
7304 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7305 </note>
7306 </desc>
7307 </attribute>
7308
7309 <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
7310 <desc>
7311 List of USB device filters in action.
7312 When a new device is physically attached to the host computer,
7313 filters from this list are applied to it (in order they are stored
7314 in the list). The first matched filter will determine the
7315 <link to="IHostUSBDeviceFilter::action">action</link>
7316 performed on the device.
7317
7318 Unless the device is ignored by these filters, filters of all
7319 currently running virtual machines
7320 (<link to="IUSBController::deviceFilters"/>) are applied to it.
7321
7322 <note>
7323 If USB functionality is not available in the given edition of
7324 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7325 </note>
7326
7327 <see><link to="IHostUSBDeviceFilter"/>,
7328 <link to="USBDeviceState"/></see>
7329 </desc>
7330 </attribute>
7331
7332 <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
7333 <desc>List of host network interfaces currently defined on the host.</desc>
7334 </attribute>
7335
7336 <attribute name="processorCount" type="unsigned long" readonly="yes">
7337 <desc>Number of (logical) CPUs installed in the host system.</desc>
7338 </attribute>
7339
7340 <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
7341 <desc>Number of (logical) CPUs online in the host system.</desc>
7342 </attribute>
7343
7344 <attribute name="processorCoreCount" type="unsigned long" readonly="yes">
7345 <desc>Number of physical processor cores installed in the host system.</desc>
7346 </attribute>
7347
7348 <method name="getProcessorSpeed">
7349 <desc>Query the (approximate) maximum speed of a specified host CPU in
7350 Megahertz.
7351 </desc>
7352 <param name="cpuId" type="unsigned long" dir="in">
7353 <desc>
7354 Identifier of the CPU.
7355 </desc>
7356 </param>
7357 <param name="speed" type="unsigned long" dir="return">
7358 <desc>
7359 Speed value. 0 is returned if value is not known or @a cpuId is
7360 invalid.
7361 </desc>
7362 </param>
7363 </method>
7364
7365 <method name="getProcessorFeature">
7366 <desc>Query whether a CPU feature is supported or not.</desc>
7367 <param name="feature" type="ProcessorFeature" dir="in">
7368 <desc>
7369 CPU Feature identifier.
7370 </desc>
7371 </param>
7372 <param name="supported" type="boolean" dir="return">
7373 <desc>
7374 Feature is supported or not.
7375 </desc>
7376 </param>
7377 </method>
7378
7379 <method name="getProcessorDescription">
7380 <desc>Query the model string of a specified host CPU.
7381 </desc>
7382 <param name="cpuId" type="unsigned long" dir="in">
7383 <desc>
7384 Identifier of the CPU.
7385 <note>
7386 The current implementation might not necessarily return the
7387 description for this exact CPU.
7388 </note>
7389 </desc>
7390 </param>
7391 <param name="description" type="wstring" dir="return">
7392 <desc>
7393 Model string. An empty string is returned if value is not known or
7394 @a cpuId is invalid.
7395 </desc>
7396 </param>
7397 </method>
7398
7399 <method name="getProcessorCPUIDLeaf">
7400 <desc>
7401 Returns the CPU cpuid information for the specified leaf.
7402 </desc>
7403 <param name="cpuId" type="unsigned long" dir="in">
7404 <desc>
7405 Identifier of the CPU. The CPU most be online.
7406 <note>
7407 The current implementation might not necessarily return the
7408 description for this exact CPU.
7409 </note>
7410 </desc>
7411 </param>
7412 <param name="leaf" type="unsigned long" dir="in">
7413 <desc>
7414 CPUID leaf index (eax).
7415 </desc>
7416 </param>
7417 <param name="subLeaf" type="unsigned long" dir="in">
7418 <desc>
7419 CPUID leaf sub index (ecx). This currently only applies to cache
7420 information on Intel CPUs. Use 0 if retrieving values for
7421 <link to="IMachine::setCPUIDLeaf"/>.
7422 </desc>
7423 </param>
7424 <param name="valEax" type="unsigned long" dir="out">
7425 <desc>
7426 CPUID leaf value for register eax.
7427 </desc>
7428 </param>
7429 <param name="valEbx" type="unsigned long" dir="out">
7430 <desc>
7431 CPUID leaf value for register ebx.
7432 </desc>
7433 </param>
7434 <param name="valEcx" type="unsigned long" dir="out">
7435 <desc>
7436 CPUID leaf value for register ecx.
7437 </desc>
7438 </param>
7439 <param name="valEdx" type="unsigned long" dir="out">
7440 <desc>
7441 CPUID leaf value for register edx.
7442 </desc>
7443 </param>
7444 </method>
7445
7446 <attribute name="memorySize" type="unsigned long" readonly="yes">
7447 <desc>Amount of system memory in megabytes installed in the host system.</desc>
7448 </attribute>
7449
7450 <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7451 <desc>Available system memory in the host system.</desc>
7452 </attribute>
7453
7454 <attribute name="operatingSystem" type="wstring" readonly="yes">
7455 <desc>Name of the host system's operating system.</desc>
7456 </attribute>
7457
7458 <attribute name="OSVersion" type="wstring" readonly="yes">
7459 <desc>Host operating system's version string.</desc>
7460 </attribute>
7461
7462 <attribute name="UTCTime" type="long long" readonly="yes">
7463 <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7464 </attribute>
7465
7466 <attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
7467 <desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
7468 </attribute>
7469
7470 <method name="createHostOnlyNetworkInterface">
7471 <desc>
7472 Creates a new adapter for Host Only Networking.
7473 <result name="E_INVALIDARG">
7474 Host network interface @a name already exists.
7475 </result>
7476 </desc>
7477 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
7478 <desc>
7479 Created host interface object.
7480 </desc>
7481 </param>
7482 <param name="progress" type="IProgress" dir="return">
7483 <desc>
7484 Progress object to track the operation completion.
7485 </desc>
7486 </param>
7487 </method>
7488
7489 <method name="removeHostOnlyNetworkInterface">
7490 <desc>
7491 Removes the given Host Only Networking interface.
7492 <result name="VBOX_E_OBJECT_NOT_FOUND">
7493 No host network interface matching @a id found.
7494 </result>
7495 </desc>
7496 <param name="id" type="uuid" mod="string" dir="in">
7497 <desc>
7498 Adapter GUID.
7499 </desc>
7500 </param>
7501 <param name="progress" type="IProgress" dir="return">
7502 <desc>
7503 Progress object to track the operation completion.
7504 </desc>
7505 </param>
7506 </method>
7507
7508 <method name="createUSBDeviceFilter">
7509 <desc>
7510 Creates a new USB device filter. All attributes except
7511 the filter name are set to empty (any match),
7512 <i>active</i> is @c false (the filter is not active).
7513
7514 The created filter can be added to the list of filters using
7515 <link to="#insertUSBDeviceFilter"/>.
7516
7517 <see><link to="#USBDeviceFilters"/></see>
7518 </desc>
7519 <param name="name" type="wstring" dir="in">
7520 <desc>
7521 Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
7522 </desc>
7523 </param>
7524 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
7525 <desc>Created filter object.</desc>
7526 </param>
7527 </method>
7528
7529 <method name="insertUSBDeviceFilter">
7530 <desc>
7531 Inserts the given USB device to the specified position
7532 in the list of filters.
7533
7534 Positions are numbered starting from @c 0. If the specified
7535 position is equal to or greater than the number of elements in
7536 the list, the filter is added at the end of the collection.
7537
7538 <note>
7539 Duplicates are not allowed, so an attempt to insert a
7540 filter already in the list is an error.
7541 </note>
7542 <note>
7543 If USB functionality is not available in the given edition of
7544 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7545 </note>
7546
7547 <see><link to="#USBDeviceFilters"/></see>
7548
7549 <result name="VBOX_E_INVALID_OBJECT_STATE">
7550 USB device filter is not created within this VirtualBox instance.
7551 </result>
7552 <result name="E_INVALIDARG">
7553 USB device filter already in list.
7554 </result>
7555
7556 </desc>
7557 <param name="position" type="unsigned long" dir="in">
7558 <desc>Position to insert the filter to.</desc>
7559 </param>
7560 <param name="filter" type="IHostUSBDeviceFilter" dir="in">
7561 <desc>USB device filter to insert.</desc>
7562 </param>
7563 </method>
7564
7565 <method name="removeUSBDeviceFilter">
7566 <desc>
7567 Removes a USB device filter from the specified position in the
7568 list of filters.
7569
7570 Positions are numbered starting from @c 0. Specifying a
7571 position equal to or greater than the number of elements in
7572 the list will produce an error.
7573
7574 <note>
7575 If USB functionality is not available in the given edition of
7576 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7577 </note>
7578
7579 <see><link to="#USBDeviceFilters"/></see>
7580
7581 <result name="E_INVALIDARG">
7582 USB device filter list empty or invalid @a position.
7583 </result>
7584
7585 </desc>
7586 <param name="position" type="unsigned long" dir="in">
7587 <desc>Position to remove the filter from.</desc>
7588 </param>
7589 </method>
7590
7591 <method name="findHostDVDDrive">
7592 <desc>
7593 Searches for a host DVD drive with the given @c name.
7594
7595 <result name="VBOX_E_OBJECT_NOT_FOUND">
7596 Given @c name does not correspond to any host drive.
7597 </result>
7598
7599 </desc>
7600 <param name="name" type="wstring" dir="in">
7601 <desc>Name of the host drive to search for</desc>
7602 </param>
7603 <param name="drive" type="IMedium" dir="return">
7604 <desc>Found host drive object</desc>
7605 </param>
7606 </method>
7607
7608 <method name="findHostFloppyDrive">
7609 <desc>
7610 Searches for a host floppy drive with the given @c name.
7611
7612 <result name="VBOX_E_OBJECT_NOT_FOUND">
7613 Given @c name does not correspond to any host floppy drive.
7614 </result>
7615
7616 </desc>
7617 <param name="name" type="wstring" dir="in">
7618 <desc>Name of the host floppy drive to search for</desc>
7619 </param>
7620 <param name="drive" type="IMedium" dir="return">
7621 <desc>Found host floppy drive object</desc>
7622 </param>
7623 </method>
7624
7625 <method name="findHostNetworkInterfaceByName">
7626 <desc>
7627 Searches through all host network interfaces for an interface with
7628 the given @c name.
7629 <note>
7630 The method returns an error if the given @c name does not
7631 correspond to any host network interface.
7632 </note>
7633 </desc>
7634 <param name="name" type="wstring" dir="in">
7635 <desc>Name of the host network interface to search for.</desc>
7636 </param>
7637 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7638 <desc>Found host network interface object.</desc>
7639 </param>
7640 </method>
7641 <method name="findHostNetworkInterfaceById">
7642 <desc>
7643 Searches through all host network interfaces for an interface with
7644 the given GUID.
7645 <note>
7646 The method returns an error if the given GUID does not
7647 correspond to any host network interface.
7648 </note>
7649 </desc>
7650 <param name="id" type="uuid" mod="string" dir="in">
7651 <desc>GUID of the host network interface to search for.</desc>
7652 </param>
7653 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7654 <desc>Found host network interface object.</desc>
7655 </param>
7656 </method>
7657 <method name="findHostNetworkInterfacesOfType">
7658 <desc>
7659 Searches through all host network interfaces and returns a list of interfaces of the specified type
7660 </desc>
7661 <param name="type" type="HostNetworkInterfaceType" dir="in">
7662 <desc>type of the host network interfaces to search for.</desc>
7663 </param>
7664 <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7665 <desc>Found host network interface objects.</desc>
7666 </param>
7667 </method>
7668
7669 <method name="findUSBDeviceById">
7670 <desc>
7671 Searches for a USB device with the given UUID.
7672
7673 <result name="VBOX_E_OBJECT_NOT_FOUND">
7674 Given @c id does not correspond to any USB device.
7675 </result>
7676
7677 <see><link to="IUSBDevice::id"/></see>
7678 </desc>
7679 <param name="id" type="uuid" mod="string" dir="in">
7680 <desc>UUID of the USB device to search for.</desc>
7681 </param>
7682 <param name="device" type="IHostUSBDevice" dir="return">
7683 <desc>Found USB device object.</desc>
7684 </param>
7685 </method>
7686
7687 <method name="findUSBDeviceByAddress">
7688 <desc>
7689 Searches for a USB device with the given host address.
7690
7691 <result name="VBOX_E_OBJECT_NOT_FOUND">
7692 Given @c name does not correspond to any USB device.
7693 </result>
7694
7695 <see><link to="IUSBDevice::address"/></see>
7696 </desc>
7697 <param name="name" type="wstring" dir="in">
7698 <desc>
7699 Address of the USB device (as assigned by the host) to
7700 search for.
7701 </desc>
7702 </param>
7703 <param name="device" type="IHostUSBDevice" dir="return">
7704 <desc>Found USB device object.</desc>
7705 </param>
7706 </method>
7707
7708 <method name="generateMACAddress">
7709 <desc>
7710 Generates a valid Ethernet MAC address, 12 hexadecimal characters.
7711 </desc>
7712 <param name="address" type="wstring" dir="return">
7713 <desc>New Ethernet MAC address.</desc>
7714 </param>
7715 </method>
7716
7717 </interface>
7718
7719 <!--
7720 // ISystemProperties
7721 /////////////////////////////////////////////////////////////////////////
7722 -->
7723
7724 <interface
7725 name="ISystemProperties"
7726 extends="$unknown"
7727 uuid="8a0ab9ab-48c1-4d04-954b-4a751413d084"
7728 wsmap="managed"
7729 >
7730 <desc>
7731 The ISystemProperties interface represents global properties of the given
7732 VirtualBox installation.
7733
7734 These properties define limits and default values for various attributes
7735 and parameters. Most of the properties are read-only, but some can be
7736 changed by a user.
7737 </desc>
7738
7739 <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7740 <desc>Minimum guest system memory in Megabytes.</desc>
7741 </attribute>
7742
7743 <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7744 <desc>Maximum guest system memory in Megabytes.</desc>
7745 </attribute>
7746
7747 <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7748 <desc>Minimum guest video memory in Megabytes.</desc>
7749 </attribute>
7750
7751 <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7752 <desc>Maximum guest video memory in Megabytes.</desc>
7753 </attribute>
7754
7755 <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7756 <desc>Minimum CPU count.</desc>
7757 </attribute>
7758
7759 <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7760 <desc>Maximum CPU count.</desc>
7761 </attribute>
7762
7763 <attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
7764 <desc>Maximum of monitors which could be connected.</desc>
7765 </attribute>
7766
7767 <attribute name="infoVDSize" type="long long" readonly="yes">
7768 <desc>Maximum size of a virtual disk image in bytes. Informational value,
7769 does not reflect the limits of any virtual disk image format.</desc>
7770 </attribute>
7771
7772 <attribute name="serialPortCount" type="unsigned long" readonly="yes">
7773 <desc>
7774 Maximum number of serial ports associated with every
7775 <link to="IMachine"/> instance.
7776 </desc>
7777 </attribute>
7778
7779 <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
7780 <desc>
7781 Maximum number of parallel ports associated with every
7782 <link to="IMachine"/> instance.
7783 </desc>
7784 </attribute>
7785
7786 <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
7787 <desc>
7788 Maximum device position in the boot order. This value corresponds
7789 to the total number of devices a machine can boot from, to make it
7790 possible to include all possible devices to the boot list.
7791 <see><link to="IMachine::setBootOrder"/></see>
7792 </desc>
7793 </attribute>
7794
7795 <attribute name="defaultMachineFolder" type="wstring">
7796 <desc>
7797 Full path to the default directory used to create new or open
7798 existing machines when a machine settings file name contains no
7799 path.
7800
7801 Starting with VirtualBox 4.0, by default, this attribute contains
7802 the full path of folder named "VirtualBox VMs" in the user's
7803 home directory, which depends on the host platform.
7804
7805 When setting this attribute, a full path must be specified.
7806 Setting this property to @c null or an empty string or the
7807 special value "Machines" (for compatibility reasons) will restore
7808 that default value.
7809
7810 If the folder specified herein does not exist, it will be created
7811 automatically as needed.
7812
7813 <see>
7814 <link to="IVirtualBox::createMachine"/>,
7815 <link to="IVirtualBox::openMachine"/>
7816 </see>
7817 </desc>
7818 </attribute>
7819
7820 <attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
7821 <desc>
7822 List of all medium storage formats supported by this VirtualBox
7823 installation.
7824
7825 Keep in mind that the medium format identifier
7826 (<link to="IMediumFormat::id"/>) used in other API calls like
7827 <link to="IVirtualBox::createHardDisk"/> to refer to a particular
7828 medium format is a case-insensitive string. This means that, for
7829 example, all of the following strings:
7830 <pre>
7831 "VDI"
7832 "vdi"
7833 "VdI"</pre>
7834 refer to the same medium format.
7835
7836 Note that the virtual medium framework is backend-based, therefore
7837 the list of supported formats depends on what backends are currently
7838 installed.
7839
7840 <see><link to="IMediumFormat"/></see>
7841 </desc>
7842 </attribute>
7843
7844 <attribute name="defaultHardDiskFormat" type="wstring">
7845 <desc>
7846 Identifier of the default medium format used by VirtualBox.
7847
7848 The medium format set by this attribute is used by VirtualBox
7849 when the medium format was not specified explicitly. One example is
7850 <link to="IVirtualBox::createHardDisk"/> with the empty
7851 format argument. A more complex example is implicit creation of
7852 differencing media when taking a snapshot of a virtual machine:
7853 this operation will try to use a format of the parent medium first
7854 and if this format does not support differencing media the default
7855 format specified by this argument will be used.
7856
7857 The list of supported medium formats may be obtained by the
7858 <link to="#mediumFormats"/> call. Note that the default medium
7859 format must have a capability to create differencing media;
7860 otherwise operations that create media implicitly may fail
7861 unexpectedly.
7862
7863 The initial value of this property is <tt>"VDI"</tt> in the current
7864 version of the VirtualBox product, but may change in the future.
7865
7866 <note>
7867 Setting this property to @c null or empty string will restore the
7868 initial value.
7869 </note>
7870
7871 <see>
7872 <link to="#mediumFormats"/>,
7873 <link to="IMediumFormat::id"/>,
7874 <link to="IVirtualBox::createHardDisk"/>
7875 </see>
7876 </desc>
7877 </attribute>
7878
7879 <attribute name="freeDiskSpaceWarning" type="long long">
7880 <desc>Issue a warning if the free disk space is below (or in some disk
7881 intensive operation is expected to go below) the given size in
7882 bytes.</desc>
7883 </attribute>
7884
7885 <attribute name="freeDiskSpacePercentWarning" type="unsigned long">
7886 <desc>Issue a warning if the free disk space is below (or in some disk
7887 intensive operation is expected to go below) the given percentage.</desc>
7888 </attribute>
7889
7890 <attribute name="freeDiskSpaceError" type="long long">
7891 <desc>Issue an error if the free disk space is below (or in some disk
7892 intensive operation is expected to go below) the given size in
7893 bytes.</desc>
7894 </attribute>
7895
7896 <attribute name="freeDiskSpacePercentError" type="unsigned long">
7897 <desc>Issue an error if the free disk space is below (or in some disk
7898 intensive operation is expected to go below) the given percentage.</desc>
7899 </attribute>
7900
7901 <attribute name="VRDEAuthLibrary" type="wstring">
7902 <desc>
7903 Library that provides authentication for Remote Desktop clients. The library
7904 is used if a virtual machine's authentication type is set to "external"
7905 in the VM RemoteDisplay configuration.
7906
7907 The system library extension (".DLL" or ".so") must be omitted.
7908 A full path can be specified; if not, then the library must reside on the
7909 system's default library path.
7910
7911 The default value of this property is <tt>"VBoxAuth"</tt>. There is a library
7912 of that name in one of the default VirtualBox library directories.
7913
7914 For details about VirtualBox authentication libraries and how to implement
7915 them, please refer to the VirtualBox manual.
7916
7917 <note>
7918 Setting this property to @c null or empty string will restore the
7919 initial value.
7920 </note>
7921 </desc>
7922 </attribute>
7923
7924 <attribute name="webServiceAuthLibrary" type="wstring">
7925 <desc>
7926 Library that provides authentication for webservice clients. The library
7927 is used if a virtual machine's authentication type is set to "external"
7928 in the VM RemoteDisplay configuration and will be called from
7929 within the <link to="IWebsessionManager::logon" /> implementation.
7930
7931 As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
7932 there is no per-VM setting for this, as the webservice is a global
7933 resource (if it is running). Only for this setting (for the webservice),
7934 setting this value to a literal <tt>"null"</tt> string disables authentication,
7935 meaning that <link to="IWebsessionManager::logon" /> will always succeed,
7936 no matter what user name and password are supplied.
7937
7938 The initial value of this property is <tt>"VBoxAuth"</tt>,
7939 meaning that the webservice will use the same authentication
7940 library that is used by default for VRDE (again, see
7941 <link to="ISystemProperties::VRDEAuthLibrary" />).
7942 The format and calling convention of authentication libraries
7943 is the same for the webservice as it is for VRDE.
7944
7945 <note>
7946 Setting this property to @c null or empty string will restore the
7947 initial value.
7948 </note>
7949 </desc>
7950 </attribute>
7951
7952 <attribute name="defaultVRDEExtPack" type="wstring">
7953 <desc>
7954 The name of the extension pack providing the default VRDE.
7955
7956 This attribute is for choosing between multiple extension packs
7957 providing VRDE. If only one is installed, it will automatically be the
7958 default one. The attribute value can be empty if no VRDE extension
7959 pack is installed.
7960
7961 For details about VirtualBox Remote Desktop Extension and how to
7962 implement one, please refer to the VirtualBox SDK.
7963 </desc>
7964 </attribute>
7965
7966 <attribute name="logHistoryCount" type="unsigned long">
7967 <desc>
7968 This value specifies how many old release log files are kept.
7969 </desc>
7970 </attribute>
7971
7972 <attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
7973 <desc>This value hold the default audio driver for the current
7974 system.</desc>
7975 </attribute>
7976
7977
7978 <method name="getMaxNetworkAdapters">
7979 <desc>
7980 Maximum total number of network adapters associated with every
7981 <link to="IMachine"/> instance.
7982 </desc>
7983
7984 <param name="chipset" type="ChipsetType" dir="in">
7985 <desc>The chipset type to get the value for.</desc>
7986 </param>
7987
7988
7989 <param name="maxNetworkAdapters" type="unsigned long" dir="return">
7990 <desc>The maximum total number of network adapters allowed.</desc>
7991 </param>
7992
7993 </method>
7994
7995 <method name="getMaxNetworkAdaptersOfType">
7996 <desc>
7997 Maximum number of network adapters of a given attachment type,
7998 associated with every <link to="IMachine"/> instance.
7999 </desc>
8000
8001 <param name="chipset" type="ChipsetType" dir="in">
8002 <desc>The chipset type to get the value for.</desc>
8003 </param>
8004
8005 <param name="type" type="NetworkAttachmentType" dir="in">
8006 <desc>Type of attachment.</desc>
8007 </param>
8008
8009 <param name="maxNetworkAdapters" type="unsigned long" dir="return">
8010 <desc>The maximum number of network adapters allowed for
8011 particular chipset and attachment type.</desc>
8012 </param>
8013
8014 </method>
8015
8016
8017 <method name="getMaxDevicesPerPortForStorageBus">
8018 <desc>Returns the maximum number of devices which can be attached to a port
8019 for the given storage bus.</desc>
8020
8021 <param name="bus" type="StorageBus" dir="in">
8022 <desc>The storage bus type to get the value for.</desc>
8023 </param>
8024
8025 <param name="maxDevicesPerPort" type="unsigned long" dir="return">
8026 <desc>The maximum number of devices which can be attached to the port for the given
8027 storage bus.</desc>
8028 </param>
8029 </method>
8030
8031 <method name="getMinPortCountForStorageBus">
8032 <desc>Returns the minimum number of ports the given storage bus supports.</desc>
8033
8034 <param name="bus" type="StorageBus" dir="in">
8035 <desc>The storage bus type to get the value for.</desc>
8036 </param>
8037
8038 <param name="minPortCount" type="unsigned long" dir="return">
8039 <desc>The minimum number of ports for the given storage bus.</desc>
8040 </param>
8041 </method>
8042
8043 <method name="getMaxPortCountForStorageBus">
8044 <desc>Returns the maximum number of ports the given storage bus supports.</desc>
8045
8046 <param name="bus" type="StorageBus" dir="in">
8047 <desc>The storage bus type to get the value for.</desc>
8048 </param>
8049
8050 <param name="maxPortCount" type="unsigned long" dir="return">
8051 <desc>The maximum number of ports for the given storage bus.</desc>
8052 </param>
8053 </method>
8054
8055 <method name="getMaxInstancesOfStorageBus">
8056 <desc>Returns the maximum number of storage bus instances which
8057 can be configured for each VM. This corresponds to the number of
8058 storage controllers one can have. Value may depend on chipset type
8059 used.</desc>
8060
8061 <param name="chipset" type="ChipsetType" dir="in">
8062 <desc>The chipset type to get the value for.</desc>
8063 </param>
8064
8065 <param name="bus" type="StorageBus" dir="in">
8066 <desc>The storage bus type to get the value for.</desc>
8067 </param>
8068
8069 <param name="maxInstances" type="unsigned long" dir="return">
8070 <desc>The maximum number of instances for the given storage bus.</desc>
8071 </param>
8072 </method>
8073
8074 <method name="getDeviceTypesForStorageBus">
8075 <desc>Returns list of all the supported device types
8076 (<link to="DeviceType"/>) for the given type of storage
8077 bus.</desc>
8078
8079 <param name="bus" type="StorageBus" dir="in">
8080 <desc>The storage bus type to get the value for.</desc>
8081 </param>
8082
8083 <param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
8084 <desc>The list of all supported device types for the given storage bus.</desc>
8085 </param>
8086 </method>
8087
8088 <method name="getDefaultIoCacheSettingForStorageController">
8089 <desc>Returns the default I/O cache setting for the
8090 given storage controller</desc>
8091
8092 <param name="controllerType" type="StorageControllerType" dir="in">
8093 <desc>The storage controller to the setting for.</desc>
8094 </param>
8095
8096 <param name="enabled" type="boolean" dir="return">
8097 <desc>Returned flag indicating the default value</desc>
8098 </param>
8099 </method>
8100 </interface>
8101
8102 <!--
8103 // IGuest
8104 /////////////////////////////////////////////////////////////////////////
8105 -->
8106
8107 <interface
8108 name="IGuestOSType" extends="$unknown"
8109 uuid="432c1546-1354-4abf-bf08-878a32a373f5"
8110 wsmap="struct"
8111 >
8112 <desc>
8113 </desc>
8114
8115 <attribute name="familyId" type="wstring" readonly="yes">
8116 <desc>Guest OS family identifier string.</desc>
8117 </attribute>
8118
8119 <attribute name="familyDescription" type="wstring" readonly="yes">
8120 <desc>Human readable description of the guest OS family.</desc>
8121 </attribute>
8122
8123 <attribute name="id" type="wstring" readonly="yes">
8124 <desc>Guest OS identifier string.</desc>
8125 </attribute>
8126
8127 <attribute name="description" type="wstring" readonly="yes">
8128 <desc>Human readable description of the guest OS.</desc>
8129 </attribute>
8130
8131 <attribute name="is64Bit" type="boolean" readonly="yes">
8132 <desc>Returns @c true if the given OS is 64-bit</desc>
8133 </attribute>
8134
8135 <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
8136 <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
8137 </attribute>
8138
8139 <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
8140 <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
8141 </attribute>
8142
8143 <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
8144 <desc>Recommended RAM size in Megabytes.</desc>
8145 </attribute>
8146
8147 <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
8148 <desc>Recommended video RAM size in Megabytes.</desc>
8149 </attribute>
8150
8151 <attribute name="recommendedHDD" type="long long" readonly="yes">
8152 <desc>Recommended hard disk size in bytes.</desc>
8153 </attribute>
8154
8155 <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
8156 <desc>Returns recommended network adapter for this OS type.</desc>
8157 </attribute>
8158
8159 <attribute name="recommendedPae" type="boolean" readonly="yes">
8160 <desc>Returns @c true if using PAE is recommended for this OS type.</desc>
8161 </attribute>
8162
8163 <attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
8164 <desc>Recommended storage controller type for DVD/CD drives.</desc>
8165 </attribute>
8166
8167 <attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
8168 <desc>Recommended storage bus type for DVD/CD drives.</desc>
8169 </attribute>
8170
8171 <attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
8172 <desc>Recommended storage controller type for HD drives.</desc>
8173 </attribute>
8174
8175 <attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
8176 <desc>Recommended storage bus type for HD drives.</desc>
8177 </attribute>
8178
8179 <attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
8180 <desc>Recommended firmware type.</desc>
8181 </attribute>
8182
8183 <attribute name="recommendedUsbHid" type="boolean" readonly="yes">
8184 <desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
8185 </attribute>
8186
8187 <attribute name="recommendedHpet" type="boolean" readonly="yes">
8188 <desc>Returns @c true if using HPET is recommended for this OS type.</desc>
8189 </attribute>
8190
8191 <attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
8192 <desc>Returns @c true if using a USB Tablet is recommended.</desc>
8193 </attribute>
8194
8195 <attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
8196 <desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
8197 </attribute>
8198
8199 <attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
8200 <desc>Recommended chipset type.</desc>
8201 </attribute>
8202
8203 <attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
8204 <desc>Recommended audio type.</desc>
8205 </attribute>
8206
8207 </interface>
8208
8209 <enum
8210 name="AdditionsFacilityType"
8211 uuid="98f7f957-89fb-49b6-a3b1-31e3285eb1d8"
8212 >
8213 <desc>
8214 Guest Additions facility IDs.
8215 </desc>
8216
8217 <const name="None" value="0">
8218 <desc>No/invalid facility.</desc>
8219 </const>
8220 <const name="VBoxGuestDriver" value="20">
8221 <desc>VirtualBox base driver (VBoxGuest).</desc>
8222 </const>
8223 <const name="VBoxService" value="100">
8224 <desc>VirtualBox system service (VBoxService).</desc>
8225 </const>
8226 <const name="VBoxTrayClient" value="101">
8227 <desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc>
8228 </const>
8229 <const name="Seamless" value="1000">
8230 <desc>Seamless guest desktop integration.</desc>
8231 </const>
8232 <const name="Graphics" value="1100">
8233 <desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints
8234 are not immediately acted on and guest display resizes are probably not initiated by
8235 the guest additions.
8236 </desc>
8237 </const>
8238 <const name="All" value="2147483646">
8239 <desc>All facilities selected.</desc>
8240 </const>
8241 </enum>
8242
8243 <enum
8244 name="AdditionsFacilityClass"
8245 uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f"
8246 >
8247 <desc>
8248 Guest Additions facility classes.
8249 </desc>
8250
8251 <const name="None" value="0">
8252 <desc>No/invalid class.</desc>
8253 </const>
8254 <const name="Driver" value="10">
8255 <desc>Driver.</desc>
8256 </const>
8257 <const name="Service" value="30">
8258 <desc>System service.</desc>
8259 </const>
8260 <const name="Program" value="50">
8261 <desc>Program.</desc>
8262 </const>
8263 <const name="Feature" value="100">
8264 <desc>Feature.</desc>
8265 </const>
8266 <const name="ThirdParty" value="999">
8267 <desc>Third party.</desc>
8268 </const>
8269 <const name="All" value="2147483646">
8270 <desc>All facility classes selected.</desc>
8271 </const>
8272 </enum>
8273
8274 <enum
8275 name="AdditionsFacilityStatus"
8276 uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde"
8277 >
8278 <desc>
8279 Guest Additions facility states.
8280 </desc>
8281
8282 <const name="Inactive" value="0">
8283 <desc>Facility is not active.</desc>
8284 </const>
8285 <const name="Paused" value="1">
8286 <desc>Facility has been paused.</desc>
8287 </const>
8288 <const name="PreInit" value="20">
8289 <desc>Facility is preparing to initialize.</desc>
8290 </const>
8291 <const name="Init" value="30">
8292 <desc>Facility is initializing.</desc>
8293 </const>
8294 <const name="Active" value="50">
8295 <desc>Facility is up and running.</desc>
8296 </const>
8297 <const name="Terminating" value="100">
8298 <desc>Facility is shutting down.</desc>
8299 </const>
8300 <const name="Terminated" value="101">
8301 <desc>Facility successfully shut down.</desc>
8302 </const>
8303 <const name="Failed" value="800">
8304 <desc>Facility failed to start.</desc>
8305 </const>
8306 <const name="Unknown" value="999">
8307 <desc>Facility status is unknown.</desc>
8308 </const>
8309 </enum>
8310
8311 <interface
8312 name="IAdditionsFacility" extends="$unknown"
8313 uuid="54992946-6af1-4e49-98ec-58b558b7291e"
8314 wsmap="struct"
8315 >
8316 <desc>
8317 Structure representing a Guest Additions facility.
8318 </desc>
8319
8320 <attribute name="classType" type="AdditionsFacilityClass" readonly="yes">
8321 <desc>The class this facility is part of.</desc>
8322 </attribute>
8323
8324 <attribute name="lastUpdated" type="long long" readonly="yes">
8325 <desc>
8326 Time stamp of the last status update,
8327 in milliseconds since 1970-01-01 UTC.
8328 </desc>
8329 </attribute>
8330
8331 <attribute name="name" type="wstring" readonly="yes">
8332 <desc>The facility's friendly name.</desc>
8333 </attribute>
8334
8335 <attribute name="status" type="AdditionsFacilityStatus" readonly="yes">
8336 <desc>The current status.</desc>
8337 </attribute>
8338
8339 <attribute name="type" type="AdditionsFacilityType" readonly="yes">
8340 <desc>The facility's type ID.</desc>
8341 </attribute>
8342 </interface>
8343
8344 <enum
8345 name="AdditionsRunLevelType"
8346 uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
8347 >
8348 <desc>
8349 Guest Additions run level type.
8350 </desc>
8351
8352 <const name="None" value="0">
8353 <desc>Guest Additions are not loaded.</desc>
8354 </const>
8355 <const name="System" value="1">
8356 <desc>Guest drivers are loaded.</desc>
8357 </const>
8358 <const name="Userland" value="2">
8359 <desc>Common components (such as application services) are loaded.</desc>
8360 </const>
8361 <const name="Desktop" value="3">
8362 <desc>Per-user desktop components are loaded.</desc>
8363 </const>
8364 </enum>
8365
8366 <enum
8367 name="AdditionsUpdateFlag"
8368 uuid="726a818d-18d6-4389-94e8-3e9e6826171a"
8369 >
8370 <desc>
8371 Guest Additions update flags.
8372 </desc>
8373
8374 <const name="None" value="0">
8375 <desc>No flag set.</desc>
8376 </const>
8377 <const name="WaitForUpdateStartOnly" value="1">
8378 <desc>Only wait for the update process being started and do not
8379 wait while peforming the actual update.</desc>
8380 </const>
8381 </enum>
8382
8383 <enum
8384 name="ExecuteProcessFlag"
8385 uuid="286ceb91-5f66-4c96-9845-4483e90e00ae"
8386 >
8387 <desc>
8388 Guest process execution flags.
8389 </desc>
8390
8391 <const name="None" value="0">
8392 <desc>No flag set.</desc>
8393 </const>
8394 <const name="WaitForProcessStartOnly" value="1">
8395 <desc>Only use the specified timeout value to wait for starting the guest process - the guest
8396 process itself then uses an infinite timeout.</desc>
8397 </const>
8398 <const name="IgnoreOrphanedProcesses" value="2">
8399 <desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
8400 </const>
8401 <const name="Hidden" value="4">
8402 <desc>Don't show the started process according to the guest OS guidelines.</desc>
8403 </const>
8404 <const name="NoProfile" value="8">
8405 <desc>Do not use the user's profile data when exeuting a process.</desc>
8406 </const>
8407 </enum>
8408
8409 <enum
8410 name="ExecuteProcessStatus"
8411 uuid="153768d9-d971-4098-8b5a-c5cb1ab9ea88"
8412 >
8413 <desc>
8414 Guest process execution status.
8415 </desc>
8416 <const name="Undefined" value="0">
8417 <desc>Process is in an undefined state.</desc>
8418 </const>
8419
8420 <const name="Started" value="1">
8421 <desc>Process has been started.</desc>
8422 </const>
8423 <const name="TerminatedNormally" value="2">
8424 <desc>Process terminated normally.</desc>
8425 </const>
8426 <const name="TerminatedSignal" value="3">
8427 <desc>Process terminated via signal.</desc>
8428 </const>
8429 <const name="TerminatedAbnormally" value="4">
8430 <desc>Process terminated abnormally.</desc>
8431 </const>
8432 <const name="TimedOutKilled" value="5">
8433 <desc>Process timed out and was killed.</desc>
8434 </const>
8435 <const name="TimedOutAbnormally" value="6">
8436 <desc>Process timed out and was not killed successfully.</desc>
8437 </const>
8438 <const name="Down" value="7">
8439 <desc>Service/OS is stopping, process was killed.</desc>
8440 </const>
8441 <const name="Error" value="8">
8442 <desc>Something went wrong (error code in flags).</desc>
8443 </const>
8444 </enum>
8445
8446 <enum
8447 name="ProcessInputFlag"
8448 uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
8449 >
8450 <desc>
8451 Guest process input flags.
8452 </desc>
8453 <const name="None" value="0">
8454 <desc>No flag set.</desc>
8455 </const>
8456 <const name="EndOfFile" value="1">
8457 <desc>End of file (input) reached.</desc>
8458 </const>
8459 </enum>
8460
8461 <enum
8462 name="ProcessOutputFlag"
8463 uuid="9979e85a-52bb-40b7-870c-57115e27e0f1"
8464 >
8465 <desc>
8466 Guest process output flags for specifying which
8467 type of output to retrieve.
8468 </desc>
8469 <const name="None" value="0">
8470 <desc>No flags set. Get output from stdout.</desc>
8471 </const>
8472 <const name="StdErr" value="1">
8473 <desc>Get output from stderr.</desc>
8474 </const>
8475 </enum>
8476
8477 <enum
8478 name="CopyFileFlag"
8479 uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
8480 >
8481 <desc>
8482 Host/Guest copy flags. At the moment none of these flags
8483 are implemented.
8484 </desc>
8485 <const name="None" value="0">
8486 <desc>No flag set.</desc>
8487 </const>
8488 <const name="Recursive" value="1">
8489 <desc>Copy directories recursively.</desc>
8490 </const>
8491 <const name="Update" value="2">
8492 <desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc>
8493 </const>
8494 <const name="FollowLinks" value="4">
8495 <desc>Follow symbolic links.</desc>
8496 </const>
8497 </enum>
8498
8499 <enum
8500 name="DirectoryCreateFlag"
8501 uuid="bd721b0e-ced5-4f79-b368-249897c32a36"
8502 >
8503 <desc>
8504 Directory creation flags.
8505 </desc>
8506 <const name="None" value="0">
8507 <desc>No flag set.</desc>
8508 </const>
8509 <const name="Parents" value="1">
8510 <desc>No error if existing, make parent directories as needed.</desc>
8511 </const>
8512 </enum>
8513
8514 <enum
8515 name="DirectoryOpenFlag"
8516 uuid="fc8f6203-0072-4f34-bd08-0b35e50bf071"
8517 >
8518 <desc>
8519 Directory open flags.
8520 </desc>
8521 <const name="None" value="0">
8522 <desc>No flag set.</desc>
8523 </const>
8524 </enum>
8525
8526 <enum
8527 name="GuestDirEntryType"
8528 uuid="6d19d924-1b77-4fc8-b369-a3b2c85c8241"
8529 >
8530 <desc>
8531 Guest directory entry type.
8532 </desc>
8533 <const name="Unknown" value="0">
8534 <desc>Unknown.</desc>
8535 </const>
8536 <const name="Directory" value="4">
8537 <desc>Regular file.</desc>
8538 </const>
8539 <const name="File" value="10">
8540 <desc>Regular file.</desc>
8541 </const>
8542 <const name="Symlink" value="12">
8543 <desc>Symbolic link.</desc>
8544 </const>
8545 </enum>
8546
8547 <interface
8548 name="IGuestDirEntry" extends="$unknown"
8549 uuid="20a66efc-c2f6-4438-826f-38454c04369e"
8550 wsmap="struct"
8551 >
8552 <desc>
8553 Structure representing a directory entry on the guest OS.
8554 </desc>
8555 <attribute name="nodeId" type="long long" readonly="yes">
8556 <desc>The unique identifier (within the guest's file system) of this file system object.</desc>
8557 </attribute>
8558 <attribute name="name" type="wstring" readonly="yes">
8559 <desc>The filename.</desc>
8560 </attribute>
8561 <attribute name="type" type="GuestDirEntryType" readonly="yes">
8562 <desc>The entry type.</desc>
8563 </attribute>
8564 </interface>
8565
8566 <interface
8567 name="IGuest" extends="$unknown"
8568 uuid="ed109b6e-0578-4b17-8ace-52646789f1a0"
8569 wsmap="managed"
8570 >
8571 <desc>
8572 The IGuest interface represents information about the operating system
8573 running inside the virtual machine. Used in
8574 <link to="IConsole::guest"/>.
8575
8576 IGuest provides information about the guest operating system, whether
8577 Guest Additions are installed and other OS-specific virtual machine
8578 properties.
8579 </desc>
8580
8581 <attribute name="OSTypeId" type="wstring" readonly="yes">
8582 <desc>
8583 Identifier of the Guest OS type as reported by the Guest
8584 Additions.
8585 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
8586 an IGuestOSType object representing details about the given
8587 Guest OS type.
8588 <note>
8589 If Guest Additions are not installed, this value will be
8590 the same as <link to="IMachine::OSTypeId"/>.
8591 </note>
8592 </desc>
8593 </attribute>
8594
8595 <attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
8596 <desc>
8597 Current run level of the Guest Additions.
8598 </desc>
8599 </attribute>
8600
8601 <attribute name="additionsVersion" type="wstring" readonly="yes">
8602 <desc>
8603 Version of the Guest Additions including the revision (3 decimal numbers
8604 separated by dots + revision number) installed on the guest or empty
8605 when the Additions are not installed.
8606 </desc>
8607 </attribute>
8608
8609 <attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes">
8610 <desc>
8611 Array of current known facilities. Only returns facilities where a status is known,
8612 e.g. facilities with an unknown status will not be returned.
8613 </desc>
8614 </attribute>
8615
8616 <attribute name="memoryBalloonSize" type="unsigned long">
8617 <desc>Guest system memory balloon size in megabytes (transient property).</desc>
8618 </attribute>
8619
8620 <attribute name="statisticsUpdateInterval" type="unsigned long">
8621 <desc>Interval to update guest statistics in seconds.</desc>
8622 </attribute>
8623
8624 <method name="internalGetStatistics">
8625 <desc>
8626 Internal method; do not use as it might change at any time.
8627 </desc>
8628 <param name="cpuUser" type="unsigned long" dir="out">
8629 <desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
8630 </param>
8631 <param name="cpuKernel" type="unsigned long" dir="out">
8632 <desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
8633 </param>
8634 <param name="cpuIdle" type="unsigned long" dir="out">
8635 <desc>Percentage of processor time spent idling as seen by the guest.</desc>
8636 </param>
8637 <param name="memTotal" type="unsigned long" dir="out">
8638 <desc>Total amount of physical guest RAM.</desc>
8639 </param>
8640 <param name="memFree" type="unsigned long" dir="out">
8641 <desc>Free amount of physical guest RAM.</desc>
8642 </param>
8643 <param name="memBalloon" type="unsigned long" dir="out">
8644 <desc>Amount of ballooned physical guest RAM.</desc>
8645 </param>
8646 <param name="memShared" type="unsigned long" dir="out">
8647 <desc>Amount of shared physical guest RAM.</desc>
8648 </param>
8649 <param name="memCache" type="unsigned long" dir="out">
8650 <desc>Total amount of guest (disk) cache memory.</desc>
8651 </param>
8652 <param name="pagedTotal" type="unsigned long" dir="out">
8653 <desc>Total amount of space in the page file.</desc>
8654 </param>
8655 <param name="memAllocTotal" type="unsigned long" dir="out">
8656 <desc>Total amount of memory allocated by the hypervisor.</desc>
8657 </param>
8658 <param name="memFreeTotal" type="unsigned long" dir="out">
8659 <desc>Total amount of free memory available in the hypervisor.</desc>
8660 </param>
8661 <param name="memBalloonTotal" type="unsigned long" dir="out">
8662 <desc>Total amount of memory ballooned by the hypervisor.</desc>
8663 </param>
8664 <param name="memSharedTotal" type="unsigned long" dir="out">
8665 <desc>Total amount of shared memory in the hypervisor.</desc>
8666 </param>
8667 </method>
8668
8669 <method name="getFacilityStatus">
8670 <desc>
8671 Get the current status of a Guest Additions facility.
8672 </desc>
8673 <param name="facility" type="AdditionsFacilityType" dir="in">
8674 <desc>Facility to check status for.</desc>
8675 </param>
8676 <param name="timestamp" type="long long" dir="out">
8677 <desc>Timestamp (in ms) of last status update seen by the host.</desc>
8678 </param>
8679 <param name="status" type="AdditionsFacilityStatus" dir="return">
8680 <desc>The current (latest) facility status.</desc>
8681 </param>
8682 </method>
8683
8684 <method name="getAdditionsStatus">
8685 <desc>
8686 Retrieve the current status of a certain Guest Additions run level.
8687
8688 <result name="VBOX_E_NOT_SUPPORTED">
8689 Wrong status level specified.
8690 </result>
8691
8692 </desc>
8693 <param name="level" type="AdditionsRunLevelType" dir="in">
8694 <desc>Status level to check</desc>
8695 </param>
8696 <param name="active" type="boolean" dir="return">
8697 <desc>Flag whether the status level has been reached or not</desc>
8698 </param>
8699 </method>
8700
8701 <method name="setCredentials">
8702 <desc>
8703 Store login credentials that can be queried by guest operating
8704 systems with Additions installed. The credentials are transient
8705 to the session and the guest may also choose to erase them. Note
8706 that the caller cannot determine whether the guest operating system
8707 has queried or made use of the credentials.
8708
8709 <result name="VBOX_E_VM_ERROR">
8710 VMM device is not available.
8711 </result>
8712
8713 </desc>
8714 <param name="userName" type="wstring" dir="in">
8715 <desc>User name string, can be empty</desc>
8716 </param>
8717 <param name="password" type="wstring" dir="in">
8718 <desc>Password string, can be empty</desc>
8719 </param>
8720 <param name="domain" type="wstring" dir="in">
8721 <desc>Domain name (guest logon scheme specific), can be empty</desc>
8722 </param>
8723 <param name="allowInteractiveLogon" type="boolean" dir="in">
8724 <desc>
8725 Flag whether the guest should alternatively allow the user to
8726 interactively specify different credentials. This flag might
8727 not be supported by all versions of the Additions.
8728 </desc>
8729 </param>
8730 </method>
8731
8732 <method name="executeProcess">
8733 <desc>
8734 Executes an existing program inside the guest VM.
8735
8736 <result name="VBOX_E_IPRT_ERROR">
8737 Could not execute process.
8738 </result>
8739
8740 </desc>
8741 <param name="execName" type="wstring" dir="in">
8742 <desc>
8743 Full path name of the command to execute on the guest; the
8744 commands has to exists in the guest VM in order to be executed.
8745 </desc>
8746 </param>
8747 <param name="flags" type="unsigned long" dir="in">
8748 <desc>
8749 <link to="ExecuteProcessFlag"/> flags.
8750 </desc>
8751 </param>
8752 <param name="arguments" type="wstring" safearray="yes" dir="in">
8753 <desc>
8754 Array of arguments passed to the execution command.
8755 </desc>
8756 </param>
8757 <param name="environment" type="wstring" safearray="yes" dir="in">
8758 <desc>
8759 Environment variables that can be set while the command is being
8760 executed, in form of "NAME=VALUE"; one pair per entry. To unset a
8761 variable just set its name ("NAME") without a value.
8762 </desc>
8763 </param>
8764 <param name="userName" type="wstring" dir="in">
8765 <desc>
8766 User name under which the command will be executed; has to exist
8767 and have the appropriate rights to execute programs in the VM.
8768 </desc>
8769 </param>
8770 <param name="password" type="wstring" dir="in">
8771 <desc>
8772 Password of the user account specified.
8773 </desc>
8774 </param>
8775 <param name="timeoutMS" type="unsigned long" dir="in">
8776 <desc>
8777 The maximum timeout value (in msec) to wait for finished program
8778 execution. Pass 0 for an infinite timeout.
8779 </desc>
8780 </param>
8781 <param name="pid" type="unsigned long" dir="out">
8782 <desc>
8783 The PID (process ID) of the started command for later reference.
8784 </desc>
8785 </param>
8786 <param name="progress" type="IProgress" dir="return">
8787 <desc>Progress object to track the operation completion.</desc>
8788 </param>
8789 </method>
8790
8791 <method name="getProcessOutput">
8792 <desc>
8793 Retrieves output of a formerly started process.
8794
8795 <result name="VBOX_E_IPRT_ERROR">
8796 Could not retrieve output.
8797 </result>
8798
8799 </desc>
8800 <param name="pid" type="unsigned long" dir="in">
8801 <desc>
8802 Process id returned by earlier <link to="#executeProcess"/> call.
8803 </desc>
8804 </param>
8805 <param name="flags" type="unsigned long" dir="in">
8806 <desc>
8807 <link to="ProcessOutputFlag"/> flags.
8808 </desc>
8809 </param>
8810 <param name="timeoutMS" type="unsigned long" dir="in">
8811 <desc>
8812 The maximum timeout value (in msec) to wait for output
8813 data. Pass 0 for an infinite timeout.
8814 </desc>
8815 </param>
8816 <param name="size" type="long long" dir="in">
8817 <desc>
8818 Size in bytes to read in the buffer.
8819 </desc>
8820 </param>
8821 <param name="data" type="octet" safearray="yes" dir="return">
8822 <desc>
8823 Buffer for retrieving the actual output. A data size of 0 means end of file
8824 if the requested size was not 0. This is the unprocessed
8825 output data, i.e. the line ending style depends on the platform of
8826 the system the server is running on.
8827 </desc>
8828 </param>
8829 </method>
8830
8831 <method name="getProcessStatus">
8832 <desc>
8833 Retrieves status, exit code and the exit reason of a formerly started process.
8834
8835 <result name="VBOX_E_IPRT_ERROR">
8836 Process with specified PID was not found.
8837 </result>
8838
8839 </desc>
8840 <param name="pid" type="unsigned long" dir="in">
8841 <desc>
8842 Process id returned by earlier <link to="#executeProcess"/> call.
8843 </desc>
8844 </param>
8845 <param name="exitcode" type="unsigned long" dir="out">
8846 <desc>
8847 The exit code (if available).
8848 </desc>
8849 </param>
8850 <param name="flags" type="unsigned long" dir="out">
8851 <desc>
8852 Additional flags of process status. Not used at the moment and
8853 must be set to 0.
8854 </desc>
8855 </param>
8856 <param name="reason" type="ExecuteProcessStatus" dir="return">
8857 <desc>
8858 The current process status.
8859 </desc>
8860 </param>
8861 </method>
8862
8863 <method name="copyFromGuest">
8864 <desc>
8865 Copies files/directories from guest to the host.
8866
8867 <result name="VBOX_E_IPRT_ERROR">
8868 Error while copying.
8869 </result>
8870
8871 </desc>
8872 <param name="source" type="wstring" dir="in">
8873 <desc>
8874 Source file on the guest to copy.
8875 </desc>
8876 </param>
8877 <param name="dest" type="wstring" dir="in">
8878 <desc>
8879 Destination path on the host.
8880 </desc>
8881 </param>
8882 <param name="userName" type="wstring" dir="in">
8883 <desc>
8884 User name under which the copy command will be executed; the
8885 user has to exist and have the appropriate rights to read from
8886 the source path.
8887 </desc>
8888 </param>
8889 <param name="password" type="wstring" dir="in">
8890 <desc>
8891 Password of the user account specified.
8892 </desc>
8893 </param>
8894 <param name="flags" type="unsigned long" dir="in">
8895 <desc>
8896 <link to="CopyFileFlag"/> flags. Not used at the moment and should be set to 0.
8897 </desc>
8898 </param>
8899 <param name="progress" type="IProgress" dir="return">
8900 <desc>Progress object to track the operation completion.</desc>
8901 </param>
8902 </method>
8903
8904 <method name="copyToGuest">
8905 <desc>
8906 Copies files/directories from host to the guest.
8907
8908 <result name="VBOX_E_IPRT_ERROR">
8909 Error while copying.
8910 </result>
8911
8912 </desc>
8913 <param name="source" type="wstring" dir="in">
8914 <desc>
8915 Source file on the host to copy.
8916 </desc>
8917 </param>
8918 <param name="dest" type="wstring" dir="in">
8919 <desc>
8920 Destination path on the guest.
8921 </desc>
8922 </param>
8923 <param name="userName" type="wstring" dir="in">
8924 <desc>
8925 User name under which the copy command will be executed; the
8926 user has to exist and have the appropriate rights to write to
8927 the destination path.
8928 </desc>
8929 </param>
8930 <param name="password" type="wstring" dir="in">
8931 <desc>
8932 Password of the user account specified.
8933 </desc>
8934 </param>
8935 <param name="flags" type="unsigned long" dir="in">
8936 <desc>
8937 <link to="CopyFileFlag"/> flags. Not used at the moment and should be set to 0.
8938 </desc>
8939 </param>
8940 <param name="progress" type="IProgress" dir="return">
8941 <desc>Progress object to track the operation completion.</desc>
8942 </param>
8943 </method>
8944
8945 <method name="directoryClose">
8946 <desc>
8947 Closes a formerly opened guest directory.
8948
8949 <result name="VBOX_E_IPRT_ERROR">
8950 Error while closing directory.
8951 </result>
8952
8953 </desc>
8954 <param name="handle" type="unsigned long" dir="in">
8955 <desc>
8956 Handle of opened directory to close.
8957 </desc>
8958 </param>
8959 </method>
8960
8961 <method name="directoryCreate">
8962 <desc>
8963 Creates a directory on the guest.
8964
8965 <result name="VBOX_E_IPRT_ERROR">
8966 Error while creating directory.
8967 </result>
8968
8969 </desc>
8970 <param name="directory" type="wstring" dir="in">
8971 <desc>
8972 Directory to create.
8973 </desc>
8974 </param>
8975 <param name="userName" type="wstring" dir="in">
8976 <desc>
8977 User name under which the directory creation will be executed; the
8978 user has to exist and have the appropriate rights to create the
8979 desired directory.
8980 </desc>
8981 </param>
8982 <param name="password" type="wstring" dir="in">
8983 <desc>
8984 Password of the user account specified.
8985 </desc>
8986 </param>
8987 <param name="mode" type="unsigned long" dir="in">
8988 <desc>
8989 File mode.
8990 </desc>
8991 </param>
8992 <param name="flags" type="unsigned long" dir="in">
8993 <desc>
8994 <link to="DirectoryCreateFlag"/> flags.
8995 </desc>
8996 </param>
8997 </method>
8998
8999 <method name="directoryOpen">
9000 <desc>
9001 Opens a directory on the guest.
9002
9003 <result name="VBOX_E_IPRT_ERROR">
9004 Error while opening / reading directory.
9005 </result>
9006
9007 </desc>
9008 <param name="directory" type="wstring" dir="in">
9009 <desc>
9010 Directory to read.
9011 </desc>
9012 </param>
9013 <param name="filter" type="wstring" dir="in">
9014 <desc>
9015 Directory filter (DOS style wildcards). Set to empty
9016 string if no filter required.
9017 </desc>
9018 </param>
9019 <param name="flags" type="unsigned long" dir="in">
9020 <desc>
9021 <link to="DirectoryOpenFlag"/> flags.
9022 </desc>
9023 </param>
9024 <param name="userName" type="wstring" dir="in">
9025 <desc>
9026 User name under which the directory reading will be performed; the
9027 user has to exist and have the appropriate rights to access / read the
9028 desired directory.
9029 </desc>
9030 </param>
9031 <param name="password" type="wstring" dir="in">
9032 <desc>
9033 Password of the user account specified.
9034 </desc>
9035 </param>
9036 <param name="handle" type="unsigned long" dir="return">
9037 <desc>
9038 Handle of opened directory returned by openDirectory.
9039 </desc>
9040 </param>
9041 </method>
9042
9043 <method name="directoryRead">
9044 <desc>
9045 Reads the next directory entry of an opened guest directory.
9046
9047 <result name="VBOX_E_IPRT_ERROR">
9048 Error while opening / reading directory.
9049 </result>
9050
9051 </desc>
9052 <param name="handle" type="unsigned long" dir="in">
9053 <desc>
9054 Handle of opened directory returned by openDirectory.
9055 </desc>
9056 </param>
9057 <param name="entry" type="IGuestDirEntry" dir="return">
9058 <desc>
9059 Information about next directory entry on success.
9060 </desc>
9061 </param>
9062 </method>
9063
9064 <method name="fileExists">
9065 <desc>
9066 Checks if the specified file name exists and is a regular file.
9067
9068 <result name="VBOX_E_IPRT_ERROR">
9069 Error while looking up information.
9070 </result>
9071
9072 </desc>
9073 <param name="file" type="wstring" dir="in">
9074 <desc>
9075 Full path of file to check.
9076 </desc>
9077 </param>
9078 <param name="userName" type="wstring" dir="in">
9079 <desc>
9080 User name under which the lookup will be performed; the
9081 user has to exist and have the appropriate rights to access / read the
9082 desired directory.
9083 </desc>
9084 </param>
9085 <param name="password" type="wstring" dir="in">
9086 <desc>
9087 Password of the user account specified.
9088 </desc>
9089 </param>
9090 <param name="exists" type="boolean" dir="return">
9091 <desc>
9092 True if it's a regular file, false if it isn't (or doesn't exist).
9093 </desc>
9094 </param>
9095 </method>
9096
9097 <method name="fileQuerySize">
9098 <desc>
9099 Queries the size of a file, given the path to it.
9100
9101 <result name="VBOX_E_IPRT_ERROR">
9102 Error while looking up information.
9103 </result>
9104
9105 </desc>
9106 <param name="file" type="wstring" dir="in">
9107 <desc>
9108 Full path of file to query file size for.
9109 </desc>
9110 </param>
9111 <param name="userName" type="wstring" dir="in">
9112 <desc>
9113 User name under which the lookup will be performed; the
9114 user has to exist and have the appropriate rights to access / read the
9115 desired directory.
9116 </desc>
9117 </param>
9118 <param name="password" type="wstring" dir="in">
9119 <desc>
9120 Password of the user account specified.
9121 </desc>
9122 </param>
9123 <param name="size" type="long long" dir="return">
9124 <desc>
9125 Size (in bytes) of file specified.
9126 </desc>
9127 </param>
9128 </method>
9129
9130 <method name="setProcessInput">
9131 <desc>
9132 Sends input into a formerly started process.
9133
9134 <result name="VBOX_E_IPRT_ERROR">
9135 Could not send input.
9136 </result>
9137
9138 </desc>
9139 <param name="pid" type="unsigned long" dir="in">
9140 <desc>
9141 Process id returned by earlier <link to="#executeProcess"/> call.
9142 </desc>
9143 </param>
9144 <param name="flags" type="unsigned long" dir="in">
9145 <desc>
9146 <link to="ProcessInputFlag"/> flags.
9147 </desc>
9148 </param>
9149 <param name="timeoutMS" type="unsigned long" dir="in">
9150 <desc>
9151 The maximum timeout value (in msec) to wait for getting the
9152 data transfered to the guest. Pass 0 for an infinite timeout.
9153 </desc>
9154 </param>
9155 <param name="data" type="octet" dir="in" safearray="yes">
9156 <desc>
9157 Buffer of input data to send to the started process to.
9158 </desc>
9159 </param>
9160 <param name="written" type="unsigned long" dir="return">
9161 <desc>
9162 Number of bytes written.
9163 </desc>
9164 </param>
9165 </method>
9166
9167 <method name="updateGuestAdditions">
9168 <desc>
9169 Updates already installed Guest Additions in a VM
9170 (Windows guests only).
9171
9172 <result name="VBOX_E_IPRT_ERROR">
9173 Error while updating.
9174 </result>
9175
9176 </desc>
9177 <param name="source" type="wstring" dir="in">
9178 <desc>
9179 Path to the Guest Additions .ISO file to use for the upate.
9180 </desc>
9181 </param>
9182 <param name="flags" type="unsigned long" dir="in">
9183 <desc>
9184 <link to="AdditionsUpdateFlag"/> flags.
9185 </desc>
9186 </param>
9187 <param name="progress" type="IProgress" dir="return">
9188 <desc>Progress object to track the operation completion.</desc>
9189 </param>
9190 </method>
9191
9192 </interface>
9193
9194
9195 <!--
9196 // IProgress
9197 /////////////////////////////////////////////////////////////////////////
9198 -->
9199
9200 <interface
9201 name="IProgress" extends="$unknown"
9202 uuid="c20238e4-3221-4d3f-8891-81ce92d9f913"
9203 wsmap="managed"
9204 >
9205 <desc>
9206 The IProgress interface is used to track and control
9207 asynchronous tasks within VirtualBox.
9208
9209 An instance of this is returned every time VirtualBox starts
9210 an asynchronous task (in other words, a separate thread) which
9211 continues to run after a method call returns. For example,
9212 <link to="IConsole::saveState" />, which saves the state of
9213 a running virtual machine, can take a long time to complete.
9214 To be able to display a progress bar, a user interface such as
9215 the VirtualBox graphical user interface can use the IProgress
9216 object returned by that method.
9217
9218 Note that IProgress is a "read-only" interface in the sense
9219 that only the VirtualBox internals behind the Main API can
9220 create and manipulate progress objects, whereas client code
9221 can only use the IProgress object to monitor a task's
9222 progress and, if <link to="#cancelable" /> is @c true,
9223 cancel the task by calling <link to="#cancel" />.
9224
9225 A task represented by IProgress consists of either one or
9226 several sub-operations that run sequentially, one by one (see
9227 <link to="#operation" /> and <link to="#operationCount" />).
9228 Every operation is identified by a number (starting from 0)
9229 and has a separate description.
9230
9231 You can find the individual percentage of completion of the current
9232 operation in <link to="#operationPercent" /> and the
9233 percentage of completion of the task as a whole
9234 in <link to="#percent" />.
9235
9236 Similarly, you can wait for the completion of a particular
9237 operation via <link to="#waitForOperationCompletion" /> or
9238 for the completion of the whole task via
9239 <link to="#waitForCompletion" />.
9240 </desc>
9241
9242 <attribute name="id" type="uuid" mod="string" readonly="yes">
9243 <desc>ID of the task.</desc>
9244 </attribute>
9245
9246 <attribute name="description" type="wstring" readonly="yes">
9247 <desc>Description of the task.</desc>
9248 </attribute>
9249
9250 <attribute name="initiator" type="$unknown" readonly="yes">
9251 <desc>Initiator of the task.</desc>
9252 </attribute>
9253
9254 <attribute name="cancelable" type="boolean" readonly="yes">
9255 <desc>Whether the task can be interrupted.</desc>
9256 </attribute>
9257
9258 <attribute name="percent" type="unsigned long" readonly="yes">
9259 <desc>
9260 Current progress value of the task as a whole, in percent.
9261 This value depends on how many operations are already complete.
9262 Returns 100 if <link to="#completed" /> is @c true.
9263 </desc>
9264 </attribute>
9265
9266 <attribute name="timeRemaining" type="long" readonly="yes">
9267 <desc>
9268 Estimated remaining time until the task completes, in
9269 seconds. Returns 0 once the task has completed; returns -1
9270 if the remaining time cannot be computed, in particular if
9271 the current progress is 0.
9272
9273 Even if a value is returned, the estimate will be unreliable
9274 for low progress values. It will become more reliable as the
9275 task progresses; it is not recommended to display an ETA
9276 before at least 20% of a task have completed.
9277 </desc>
9278 </attribute>
9279
9280 <attribute name="completed" type="boolean" readonly="yes">
9281 <desc>Whether the task has been completed.</desc>
9282 </attribute>
9283
9284 <attribute name="canceled" type="boolean" readonly="yes">
9285 <desc>Whether the task has been canceled.</desc>
9286 </attribute>
9287
9288 <attribute name="resultCode" type="long" readonly="yes">
9289 <desc>
9290 Result code of the progress task.
9291 Valid only if <link to="#completed"/> is @c true.
9292 </desc>
9293 </attribute>
9294
9295 <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
9296 <desc>
9297 Extended information about the unsuccessful result of the
9298 progress operation. May be @c null if no extended information
9299 is available.
9300 Valid only if <link to="#completed"/> is @c true and
9301 <link to="#resultCode"/> indicates a failure.
9302 </desc>
9303 </attribute>
9304
9305 <attribute name="operationCount" type="unsigned long" readonly="yes">
9306 <desc>
9307 Number of sub-operations this task is divided into.
9308 Every task consists of at least one suboperation.
9309 </desc>
9310 </attribute>
9311
9312 <attribute name="operation" type="unsigned long" readonly="yes">
9313 <desc>Number of the sub-operation being currently executed.</desc>
9314 </attribute>
9315
9316 <attribute name="operationDescription" type="wstring" readonly="yes">
9317 <desc>
9318 Description of the sub-operation being currently executed.
9319 </desc>
9320 </attribute>
9321
9322 <attribute name="operationPercent" type="unsigned long" readonly="yes">
9323 <desc>Progress value of the current sub-operation only, in percent.</desc>
9324 </attribute>
9325
9326 <attribute name="operationWeight" type="unsigned long" readonly="yes">
9327 <desc>Weight value of the current sub-operation only.</desc>
9328 </attribute>
9329
9330 <attribute name="timeout" type="unsigned long">
9331 <desc>
9332 When non-zero, this specifies the number of milliseconds after which
9333 the operation will automatically be canceled. This can only be set on
9334 cancelable objects.
9335 </desc>
9336 </attribute>
9337
9338 <method name="setCurrentOperationProgress">
9339 <desc>Internal method, not to be called externally.</desc>
9340 <param name="percent" type="unsigned long" dir="in" />
9341 </method>
9342 <method name="setNextOperation">
9343 <desc>Internal method, not to be called externally.</desc>
9344 <param name="nextOperationDescription" type="wstring" dir="in" />
9345 <param name="nextOperationsWeight" type="unsigned long" dir="in" />
9346 </method>
9347
9348 <method name="waitForCompletion">
9349 <desc>
9350 Waits until the task is done (including all sub-operations)
9351 with a given timeout in milliseconds; specify -1 for an indefinite wait.
9352
9353 Note that the VirtualBox/XPCOM/COM/native event queues of the calling
9354 thread are not processed while waiting. Neglecting event queues may
9355 have dire consequences (degrade performance, resource hogs,
9356 deadlocks, etc.), this is specially so for the main thread on
9357 platforms using XPCOM. Callers are adviced wait for short periods
9358 and service their event queues between calls, or to create a worker
9359 thread to do the waiting.
9360
9361 <result name="VBOX_E_IPRT_ERROR">
9362 Failed to wait for task completion.
9363 </result>
9364 </desc>
9365
9366 <param name="timeout" type="long" dir="in">
9367 <desc>
9368 Maximum time in milliseconds to wait or -1 to wait indefinitely.
9369 </desc>
9370 </param>
9371 </method>
9372
9373 <method name="waitForOperationCompletion">
9374 <desc>
9375 Waits until the given operation is done with a given timeout in
9376 milliseconds; specify -1 for an indefinite wait.
9377
9378 See <link to="#waitForCompletion"> for event queue considerations.</link>
9379
9380 <result name="VBOX_E_IPRT_ERROR">
9381 Failed to wait for operation completion.
9382 </result>
9383
9384 </desc>
9385 <param name="operation" type="unsigned long" dir="in">
9386 <desc>
9387 Number of the operation to wait for.
9388 Must be less than <link to="#operationCount"/>.
9389 </desc>
9390 </param>
9391 <param name="timeout" type="long" dir="in">
9392 <desc>
9393 Maximum time in milliseconds to wait or -1 to wait indefinitely.
9394 </desc>
9395 </param>
9396 </method>
9397
9398 <method name="waitForAsyncProgressCompletion">
9399 <desc>
9400 Waits until the other task is completed (including all
9401 sub-operations) and forward all changes from the other progress to
9402 this progress. This means sub-operation number, description, percent
9403 and so on.
9404
9405 You have to take care on setting up at least the same count on
9406 sub-operations in this progress object like there are in the other
9407 progress object.
9408
9409 If the other progress object supports cancel and this object gets any
9410 cancel request (when here enabled as well), it will be forwarded to
9411 the other progress object.
9412
9413 If there is an error in the other progress, this error isn't
9414 automatically transfered to this progress object. So you have to
9415 check any operation error within the other progress object, after
9416 this method returns.
9417 </desc>
9418
9419 <param name="pProgressAsync" type="IProgress" dir="in">
9420 <desc>
9421 The progress object of the asynchrony process.
9422 </desc>
9423 </param>
9424 </method>
9425
9426 <method name="cancel">
9427 <desc>
9428 Cancels the task.
9429 <note>
9430 If <link to="#cancelable"/> is @c false, then this method will fail.
9431 </note>
9432
9433 <result name="VBOX_E_INVALID_OBJECT_STATE">
9434 Operation cannot be canceled.
9435 </result>
9436
9437 </desc>
9438 </method>
9439
9440 </interface>
9441
9442 <!--
9443 // ISnapshot
9444 /////////////////////////////////////////////////////////////////////////
9445 -->
9446
9447 <interface
9448 name="ISnapshot" extends="$unknown"
9449 uuid="0472823b-c6e7-472a-8e9f-d732e86b8463"
9450 wsmap="managed"
9451 >
9452 <desc>
9453 The ISnapshot interface represents a snapshot of the virtual
9454 machine.
9455
9456 Together with the differencing media that are created
9457 when a snapshot is taken, a machine can be brought back to
9458 the exact state it was in when the snapshot was taken.
9459
9460 The ISnapshot interface has no methods, only attributes; snapshots
9461 are controlled through methods of the <link to="IConsole" /> interface
9462 which also manage the media associated with the snapshot.
9463 The following operations exist:
9464
9465 <ul>
9466 <li><link to="IConsole::takeSnapshot"/> creates a new snapshot
9467 by creating new, empty differencing images for the machine's
9468 media and saving the VM settings and (if the VM is running)
9469 the current VM state in the snapshot.
9470
9471 The differencing images will then receive all data written to
9472 the machine's media, while their parent (base) images
9473 remain unmodified after the snapshot has been taken (see
9474 <link to="IMedium" /> for details about differencing images).
9475 This simplifies restoring a machine to the state of a snapshot:
9476 only the differencing images need to be deleted.
9477
9478 The current machine state is not changed by taking a snapshot
9479 except that <link to="IMachine::currentSnapshot" /> is set to
9480 the newly created snapshot, which is also added to the machine's
9481 snapshots tree.
9482 </li>
9483
9484 <li><link to="IConsole::restoreSnapshot"/> resets a machine to
9485 the state of a previous snapshot by deleting the differencing
9486 image of each of the machine's media and setting the machine's
9487 settings and state to the state that was saved in the snapshot (if any).
9488
9489 This destroys the machine's current state. After calling this,
9490 <link to="IMachine::currentSnapshot" /> points to the snapshot
9491 that was restored.
9492 </li>
9493
9494 <li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
9495 without affecting the current machine state.
9496
9497 This does not change the current machine state, but instead frees the
9498 resources allocated when the snapshot was taken: the settings and machine
9499 state file are deleted (if any), and the snapshot's differencing image for
9500 each of the machine's media gets merged with its parent image.
9501
9502 Neither the current machine state nor other snapshots are affected
9503 by this operation, except that parent media will be modified
9504 to contain the disk data associated with the snapshot being deleted.
9505
9506 When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
9507 attribute is set to the current snapshot's parent or NULL if it
9508 has no parent. Otherwise the attribute is unchanged.
9509 </li>
9510 </ul>
9511
9512 Each snapshot contains a copy of virtual machine's settings (hardware
9513 configuration etc.). This copy is contained in an immutable (read-only)
9514 instance of <link to="IMachine" /> which is available from the snapshot's
9515 <link to="#machine" /> attribute. When restoring the snapshot, these
9516 settings are copied back to the original machine.
9517
9518 In addition, if the machine was running when the
9519 snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
9520 the current VM state is saved in the snapshot (similarly to what happens
9521 when a VM's state is saved). The snapshot is then said to be <i>online</i>
9522 because when restoring it, the VM will be running.
9523
9524 If the machine was in <link to="MachineState_Saved">saved</link> saved,
9525 the snapshot receives a copy of the execution state file
9526 (<link to="IMachine::stateFilePath"/>).
9527
9528 Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
9529 or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
9530 it then contains a so-called "zero execution state", representing a
9531 machine that is powered off.
9532 </desc>
9533
9534 <attribute name="id" type="uuid" mod="string" readonly="yes">
9535 <desc>UUID of the snapshot.</desc>
9536 </attribute>
9537
9538 <attribute name="name" type="wstring">
9539 <desc>Short name of the snapshot.
9540 <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
9541 be called implicitly.</note>
9542 </desc>
9543 </attribute>
9544
9545 <attribute name="description" type="wstring">
9546 <desc>Optional description of the snapshot.
9547 <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
9548 be called implicitly.</note>
9549 </desc>
9550 </attribute>
9551
9552 <attribute name="timeStamp" type="long long" readonly="yes">
9553 <desc>
9554 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
9555 </desc>
9556 </attribute>
9557
9558 <attribute name="online" type="boolean" readonly="yes">
9559 <desc>
9560 @c true if this snapshot is an online snapshot and @c false otherwise.
9561
9562 When this attribute is @c true, the
9563 <link to="IMachine::stateFilePath"/> attribute of the
9564 <link to="#machine"/> object associated with this snapshot
9565 will point to the saved state file. Otherwise, it will be
9566 an empty string.
9567 </desc>
9568 </attribute>
9569
9570 <attribute name="machine" type="IMachine" readonly="yes">
9571 <desc>
9572 Virtual machine this snapshot is taken on. This object
9573 stores all settings the machine had when taking this snapshot.
9574 <note>
9575 The returned machine object is immutable, i.e. no
9576 any settings can be changed.
9577 </note>
9578 </desc>
9579 </attribute>
9580
9581 <attribute name="parent" type="ISnapshot" readonly="yes">
9582 <desc>
9583 Parent snapshot (a snapshot this one is based on), or
9584 @c null if the snapshot has no parent (i.e. is the first snapshot).
9585 </desc>
9586 </attribute>
9587
9588 <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
9589 <desc>
9590 Child snapshots (all snapshots having this one as a parent).
9591 By inspecting this attribute starting with a machine's root snapshot
9592 (which can be obtained by calling <link to="IMachine::findSnapshot" />
9593 with a @c null UUID), a machine's snapshots tree can be iterated over.
9594 </desc>
9595 </attribute>
9596
9597 <method name="getChildrenCount" const="yes">
9598 <desc>
9599 Returns the number of direct childrens of this snapshot.
9600 </desc>
9601 <param name="childrenCount" type="unsigned long" dir="return">
9602 <desc>
9603 </desc>
9604 </param>
9605 </method>
9606
9607 </interface>
9608
9609
9610 <!--
9611 // IMedium
9612 /////////////////////////////////////////////////////////////////////////
9613 -->
9614
9615 <enum
9616 name="MediumState"
9617 uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
9618 >
9619 <desc>
9620 Virtual medium state.
9621 <see><link to="IMedium"/></see>
9622 </desc>
9623
9624 <const name="NotCreated" value="0">
9625 <desc>
9626 Associated medium storage does not exist (either was not created yet or
9627 was deleted).
9628 </desc>
9629 </const>
9630 <const name="Created" value="1">
9631 <desc>
9632 Associated storage exists and accessible; this gets set if the
9633 accessibility check performed by <link to="IMedium::refreshState" />
9634 was successful.
9635 </desc>
9636 </const>
9637 <const name="LockedRead" value="2">
9638 <desc>
9639 Medium is locked for reading (see <link to="IMedium::lockRead"/>),
9640 no data modification is possible.
9641 </desc>
9642 </const>
9643 <const name="LockedWrite" value="3">
9644 <desc>
9645 Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
9646 no concurrent data reading or modification is possible.
9647 </desc>
9648 </const>
9649 <const name="Inaccessible" value="4">
9650 <desc>
9651 Medium accessibility check (see <link to="IMedium::refreshState" />) has
9652 not yet been performed, or else, associated medium storage is not
9653 accessible. In the first case, <link to="IMedium::lastAccessError"/>
9654 is empty, in the second case, it describes the error that occurred.
9655 </desc>
9656 </const>
9657 <const name="Creating" value="5">
9658 <desc>
9659 Associated medium storage is being created.
9660 </desc>
9661 </const>
9662 <const name="Deleting" value="6">
9663 <desc>
9664 Associated medium storage is being deleted.
9665 </desc>
9666 </const>
9667 </enum>
9668
9669 <enum
9670 name="MediumType"
9671 uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04"
9672 >
9673 <desc>
9674 Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
9675 attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
9676 when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
9677 the medium attached. At the moment DVD and floppy media are always of type "writethrough".
9678 </desc>
9679
9680 <const name="Normal" value="0">
9681 <desc>
9682 Normal medium (attached directly or indirectly, preserved
9683 when taking snapshots).
9684 </desc>
9685 </const>
9686 <const name="Immutable" value="1">
9687 <desc>
9688 Immutable medium (attached indirectly, changes are wiped out
9689 the next time the virtual machine is started).
9690 </desc>
9691 </const>
9692 <const name="Writethrough" value="2">
9693 <desc>
9694 Write through medium (attached directly, ignored when
9695 taking snapshots).
9696 </desc>
9697 </const>
9698 <const name="Shareable" value="3">
9699 <desc>
9700 Allow using this medium concurrently by several machines.
9701 <note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
9702 </desc>
9703 </const>
9704 <const name="Readonly" value="4">
9705 <desc>
9706 A readonly medium, which can of course be used by several machines.
9707 <note>Present and accepted since VirtualBox 4.0.</note>
9708 </desc>
9709 </const>
9710 <const name="MultiAttach" value="5">
9711 <desc>
9712 A medium which is is indirectly attached, so that one base medium can
9713 be used for several VMs which have their own differencing medium to
9714 store their modifications. In some sense a variant of Immutable
9715 with unset AutoReset flag in each differencing medium.
9716 <note>Present and accepted since VirtualBox 4.0.</note>
9717 </desc>
9718 </const>
9719 </enum>
9720
9721 <enum
9722 name="MediumVariant"
9723 uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
9724 >
9725 <desc>
9726 Virtual medium image variant. More than one flag may be set.
9727 <see><link to="IMedium"/></see>
9728 </desc>
9729
9730 <const name="Standard" value="0">
9731 <desc>
9732 No particular variant requested, results in using the backend default.
9733 </desc>
9734 </const>
9735 <const name="VmdkSplit2G" value="0x01">
9736 <desc>
9737 VMDK image split in chunks of less than 2GByte.
9738 </desc>
9739 </const>
9740 <const name="VmdkStreamOptimized" value="0x04">
9741 <desc>
9742 VMDK streamOptimized image. Special import/export format which is
9743 read-only/append-only.
9744 </desc>
9745 </const>
9746 <const name="VmdkESX" value="0x08">
9747 <desc>
9748 VMDK format variant used on ESX products.
9749 </desc>
9750 </const>
9751 <const name="Fixed" value="0x10000">
9752 <desc>
9753 Fixed image. Only allowed for base images.
9754 </desc>
9755 </const>
9756 <const name="Diff" value="0x20000">
9757 <desc>
9758 Differencing image. Only allowed for child images.
9759 </desc>
9760 </const>
9761 </enum>
9762
9763 <interface
9764 name="IMediumAttachment" extends="$unknown"
9765 uuid="b5dfbb8c-7498-48c3-bf10-78fc60f064e1"
9766 wsmap="struct"
9767 >
9768 <desc>
9769 The IMediumAttachment interface links storage media to virtual machines.
9770 For each medium (<link to="IMedium"/>) which has been attached to a
9771 storage controller (<link to="IStorageController"/>) of a machine
9772 (<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
9773 method, one instance of IMediumAttachment is added to the machine's
9774 <link to="IMachine::mediumAttachments"/> array attribute.
9775
9776 Each medium attachment specifies the storage controller as well as a
9777 port and device number and the IMedium instance representing a virtual
9778 hard disk or floppy or DVD image.
9779
9780 For removable media (DVDs or floppies), there are two additional
9781 options. For one, the IMedium instance can be @c null to represent
9782 an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
9783 secondly, the medium can be one of the pseudo-media for host drives
9784 listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
9785
9786 <h3>Attaching Hard Disks</h3>
9787
9788 Hard disks are attached to virtual machines using the
9789 <link to="IMachine::attachDevice"/> method and detached using the
9790 <link to="IMachine::detachDevice"/> method. Depending on a medium's
9791 type (see <link to="IMedium::type" />), hard disks are attached either
9792 <i>directly</i> or <i>indirectly</i>.
9793
9794 When a hard disk is being attached directly, it is associated with the
9795 virtual machine and used for hard disk operations when the machine is
9796 running. When a hard disk is being attached indirectly, a new differencing
9797 hard disk linked to it is implicitly created and this differencing hard
9798 disk is associated with the machine and used for hard disk operations.
9799 This also means that if <link to="IMachine::attachDevice"/> performs
9800 a direct attachment then the same hard disk will be returned in response
9801 to the subsequent <link to="IMachine::getMedium"/> call; however if
9802 an indirect attachment is performed then
9803 <link to="IMachine::getMedium"/> will return the implicitly created
9804 differencing hard disk, not the original one passed to <link
9805 to="IMachine::attachDevice"/>. In detail:
9806
9807 <ul>
9808 <li><b>Normal base</b> hard disks that do not have children (i.e.
9809 differencing hard disks linked to them) and that are not already
9810 attached to virtual machines in snapshots are attached <b>directly</b>.
9811 Otherwise, they are attached <b>indirectly</b> because having
9812 dependent children or being part of the snapshot makes it impossible
9813 to modify hard disk contents without breaking the integrity of the
9814 dependent party. The <link to="IMedium::readOnly"/> attribute allows to
9815 quickly determine the kind of the attachment for the given hard
9816 disk. Note that if a normal base hard disk is to be indirectly
9817 attached to a virtual machine with snapshots then a special
9818 procedure called <i>smart attachment</i> is performed (see below).</li>
9819 <li><b>Normal differencing</b> hard disks are like normal base hard disks:
9820 they are attached <b>directly</b> if they do not have children and are
9821 not attached to virtual machines in snapshots, and <b>indirectly</b>
9822 otherwise. Note that the smart attachment procedure is never performed
9823 for differencing hard disks.</li>
9824 <li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
9825 they are designed to be non-writable. If an immutable hard disk is
9826 attached to a virtual machine with snapshots then a special
9827 procedure called smart attachment is performed (see below).</li>
9828 <li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
9829 also as designed. This also means that writethrough hard disks cannot
9830 have other hard disks linked to them at all.</li>
9831 <li><b>Shareable</b> hard disks are always attached <b>directly</b>,
9832 also as designed. This also means that shareable hard disks cannot
9833 have other hard disks linked to them at all. They behave almost
9834 like writethrough hard disks, except that shareable hard disks can
9835 be attached to several virtual machines which are running, allowing
9836 concurrent accesses. You need special cluster software running in
9837 the virtual machines to make use of such disks.</li>
9838 </ul>
9839
9840 Note that the same hard disk, regardless of its type, may be attached to
9841 more than one virtual machine at a time. In this case, the machine that is
9842 started first gains exclusive access to the hard disk and attempts to
9843 start other machines having this hard disk attached will fail until the
9844 first machine is powered down.
9845
9846 Detaching hard disks is performed in a <i>deferred</i> fashion. This means
9847 that the given hard disk remains associated with the given machine after a
9848 successful <link to="IMachine::detachDevice"/> call until
9849 <link to="IMachine::saveSettings"/> is called to save all changes to
9850 machine settings to disk. This deferring is necessary to guarantee that
9851 the hard disk configuration may be restored at any time by a call to
9852 <link to="IMachine::discardSettings"/> before the settings
9853 are saved (committed).
9854
9855 Note that if <link to="IMachine::discardSettings"/> is called after
9856 indirectly attaching some hard disks to the machine but before a call to
9857 <link to="IMachine::saveSettings"/> is made, it will implicitly delete
9858 all differencing hard disks implicitly created by
9859 <link to="IMachine::attachDevice"/> for these indirect attachments.
9860 Such implicitly created hard disks will also be immediately deleted when
9861 detached explicitly using the <link to="IMachine::detachDevice"/>
9862 call if it is made before <link to="IMachine::saveSettings"/>. This
9863 implicit deletion is safe because newly created differencing hard
9864 disks do not contain any user data.
9865
9866 However, keep in mind that detaching differencing hard disks that were
9867 implicitly created by <link to="IMachine::attachDevice"/>
9868 before the last <link to="IMachine::saveSettings"/> call will
9869 <b>not</b> implicitly delete them as they may already contain some data
9870 (for example, as a result of virtual machine execution). If these hard
9871 disks are no more necessary, the caller can always delete them explicitly
9872 using <link to="IMedium::deleteStorage"/> after they are actually de-associated
9873 from this machine by the <link to="IMachine::saveSettings"/> call.
9874
9875 <h3>Smart Attachment</h3>
9876
9877 When normal base or immutable hard disks are indirectly attached to a
9878 virtual machine then some additional steps are performed to make sure the
9879 virtual machine will have the most recent "view" of the hard disk being
9880 attached. These steps include walking through the machine's snapshots
9881 starting from the current one and going through ancestors up to the first
9882 snapshot. Hard disks attached to the virtual machine in all
9883 of the encountered snapshots are checked whether they are descendants of
9884 the given normal base or immutable hard disk. The first found child (which
9885 is the differencing hard disk) will be used instead of the normal base or
9886 immutable hard disk as a parent for creating a new differencing hard disk
9887 that will be actually attached to the machine. And only if no descendants
9888 are found or if the virtual machine does not have any snapshots then the
9889 normal base or immutable hard disk will be used itself as a parent for
9890 this differencing hard disk.
9891
9892 It is easier to explain what smart attachment does using the
9893 following example:
9894 <pre>
9895BEFORE attaching B.vdi: AFTER attaching B.vdi:
9896
9897Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
9898 Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
9899 Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
9900 Snapshot 4 (none) Snapshot 4 (none)
9901 CurState (none) CurState (D3->D2.vdi)
9902
9903 NOT
9904 ...
9905 CurState (D3->B.vdi)
9906 </pre>
9907 The first column is the virtual machine configuration before the base hard
9908 disk <tt>B.vdi</tt> is attached, the second column shows the machine after
9909 this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
9910 mean that the hard disk that is actually attached to the machine is a
9911 differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
9912 another hard disk, <tt>B.vdi</tt>.
9913
9914 As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
9915 from the machine before taking Snapshot 4. Later, after Snapshot 4 was
9916 taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
9917 dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
9918 it cannot be attached directly and needs an indirect attachment (i.e.
9919 implicit creation of a new differencing hard disk). Due to the smart
9920 attachment procedure, the new differencing hard disk
9921 (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
9922 <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
9923 <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
9924 machine.
9925
9926 Note that if there is more than one descendant hard disk of the given base
9927 hard disk found in a snapshot, and there is an exact device, channel and
9928 bus match, then this exact match will be used. Otherwise, the youngest
9929 descendant will be picked up.
9930
9931 There is one more important aspect of the smart attachment procedure which
9932 is not related to snapshots at all. Before walking through the snapshots
9933 as described above, the backup copy of the current list of hard disk
9934 attachment is searched for descendants. This backup copy is created when
9935 the hard disk configuration is changed for the first time after the last
9936 <link to="IMachine::saveSettings"/> call and used by
9937 <link to="IMachine::discardSettings"/> to undo the recent hard disk
9938 changes. When such a descendant is found in this backup copy, it will be
9939 simply re-attached back, without creating a new differencing hard disk for
9940 it. This optimization is necessary to make it possible to re-attach the
9941 base or immutable hard disk to a different bus, channel or device slot
9942 without losing the contents of the differencing hard disk actually
9943 attached to the machine in place of it.
9944
9945 </desc>
9946
9947 <attribute name="medium" type="IMedium" readonly="yes">
9948 <desc>Medium object associated with this attachment; it
9949 can be @c null for removable devices.</desc>
9950 </attribute>
9951
9952 <attribute name="controller" type="wstring" readonly="yes">
9953 <desc>Name of the storage controller of this attachment; this
9954 refers to one of the controllers in <link to="IMachine::storageControllers" />
9955 by name.</desc>
9956 </attribute>
9957
9958 <attribute name="port" type="long" readonly="yes">
9959 <desc>Port number of this attachment.
9960 See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
9961 </desc>
9962 </attribute>
9963
9964 <attribute name="device" type="long" readonly="yes">
9965 <desc>Device slot number of this attachment.
9966 See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
9967 </desc>
9968 </attribute>
9969
9970 <attribute name="type" type="DeviceType" readonly="yes">
9971 <desc>Device type of this attachment.</desc>
9972 </attribute>
9973
9974 <attribute name="passthrough" type="boolean" readonly="yes">
9975 <desc>Pass I/O requests through to a device on the host.</desc>
9976 </attribute>
9977
9978 <attribute name="temporaryEject" type="boolean" readonly="yes">
9979 <desc>Whether guest-triggered eject results in unmounting the medium.</desc>
9980 </attribute>
9981
9982 <attribute name="isEjected" type="boolean" readonly="yes">
9983 <desc>Signals that the removable medium has been ejected. This is not
9984 necessarily equivalent to having a @c null medium association.</desc>
9985 </attribute>
9986
9987 <attribute name="nonRotational" type="boolean" readonly="yes">
9988 <desc>Whether the associated medium is non-rotational.</desc>
9989 </attribute>
9990
9991 <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
9992 <desc>The bandwidth group this medium attachment is assigned to.</desc>
9993 </attribute>
9994
9995 </interface>
9996
9997 <interface
9998 name="IMedium" extends="$unknown"
9999 uuid="53f9cc0c-e0fd-40a5-a404-a7a5272082cd"
10000 wsmap="managed"
10001 >
10002 <desc>
10003 The IMedium interface represents virtual storage for a machine's
10004 hard disks, CD/DVD or floppy drives. It will typically represent
10005 a disk image on the host, for example a VDI or VMDK file representing
10006 a virtual hard disk, or an ISO or RAW file representing virtual
10007 removable media, but can also point to a network location (e.g.
10008 for iSCSI targets).
10009
10010 Instances of IMedium are connected to virtual machines by way of medium
10011 attachments, which link the storage medium to a particular device slot
10012 of a storage controller of the virtual machine.
10013 In the VirtualBox API, virtual storage is therefore always represented
10014 by the following chain of object links:
10015
10016 <ul>
10017 <li><link to="IMachine::storageControllers"/> contains an array of
10018 storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
10019 these are instances of <link to="IStorageController"/>).</li>
10020 <li><link to="IMachine::mediumAttachments"/> contains an array of
10021 medium attachments (instances of <link to="IMediumAttachment"/>
10022 created by <link to="IMachine::attachDevice" />),
10023 each containing a storage controller from the above array, a
10024 port/device specification, and an instance of IMedium representing
10025 the medium storage (image file).
10026
10027 For removable media, the storage medium is optional; a medium
10028 attachment with no medium represents a CD/DVD or floppy drive
10029 with no medium inserted. By contrast, hard disk attachments
10030 will always have an IMedium object attached.</li>
10031 <li>Each IMedium in turn points to a storage unit (such as a file
10032 on the host computer or a network resource) that holds actual
10033 data. This location is represented by the <link to="#location"/>
10034 attribute.</li>
10035 </ul>
10036
10037 Existing media are opened using <link to="IVirtualBox::openMedium"/>;
10038 new hard disk media can be created with the VirtualBox API using the
10039 <link to="IVirtualBox::createHardDisk"/> method. Differencing hard
10040 disks (see below) are usually implicitly created by VirtualBox as
10041 needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
10042 VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
10043 should be created with external tools and then opened from within VirtualBox.
10044
10045 Only for CD/DVDs and floppies, an IMedium instance can also represent a host
10046 drive. In that case the <link to="#id" /> attribute contains the UUID of
10047 one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
10048
10049 <h3>Media registries</h3>
10050
10051 When a medium has been opened or created using one of the aforementioned
10052 APIs, it becomes "known" to VirtualBox. Known media can be attached
10053 to virtual machines and accessed through <link to="IVirtualBox::findMedium"/>.
10054 They also appear in the global
10055 <link to="IVirtualBox::hardDisks" />,
10056 <link to="IVirtualBox::DVDImages" /> and
10057 <link to="IVirtualBox::floppyImages" /> arrays.
10058
10059 Prior to VirtualBox 4.0, opening a medium added it to a global media registry
10060 in the VirtualBox.xml file, which was shared between all machines and made
10061 transporting machines and their media from one host to another difficult.
10062
10063 Starting with VirtualBox 4.0, media are only added to a registry when they are
10064 <i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
10065 backwards compatibility, which registry a medium is added to depends on which
10066 VirtualBox version created a machine:
10067
10068 <ul>
10069 <li>If the medium has first been attached to a machine which was created by
10070 VirtualBox 4.0 or later, it is added to that machine's media registry in
10071 the machine XML settings file. This way all information about a machine's
10072 media attachments is contained in a single file and can be transported
10073 easily.</li>
10074 <li>For older media attachments (i.e. if the medium was first attached to a
10075 machine which was created with a VirtualBox version before 4.0), media
10076 continue to be registered in the global VirtualBox settings file, for
10077 backwards compatibility.</li>
10078 </ul>
10079
10080 See <link to="IVirtualBox::openMedium" /> for more information.
10081
10082 Media are removed from media registries by the <link to="IMedium::close"/>,
10083 <link to="#deleteStorage"/> and <link to="#mergeTo"/> methods.
10084
10085 <h3>Accessibility checks</h3>
10086
10087 VirtualBox defers media accessibility checks until the <link to="#refreshState" />
10088 method is called explicitly on a medium. This is done to make the VirtualBox object
10089 ready for serving requests as fast as possible and let the end-user
10090 application decide if it needs to check media accessibility right away or not.
10091
10092 As a result, when VirtualBox starts up (e.g. the VirtualBox
10093 object gets created for the first time), all known media are in the
10094 "Inaccessible" state, but the value of the <link to="#lastAccessError"/>
10095 attribute is an empty string because no actual accessibility check has
10096 been made yet.
10097
10098 After calling <link to="#refreshState" />, a medium is considered
10099 <i>accessible</i> if its storage unit can be read. In that case, the
10100 <link to="#state"/> attribute has a value of "Created". If the storage
10101 unit cannot be read (for example, because it is located on a disconnected
10102 network resource, or was accidentally deleted outside VirtualBox),
10103 the medium is considered <i>inaccessible</i>, which is indicated by the
10104 "Inaccessible" state. The exact reason why the medium is inaccessible can be
10105 obtained by reading the <link to="#lastAccessError"/> attribute.
10106
10107 <h3>Medium types</h3>
10108
10109 There are five types of medium behavior which are stored in the
10110 <link to="#type"/> attribute (see <link to="MediumType" />) and
10111 which define the medium's behavior with attachments and snapshots.
10112
10113 All media can be also divided in two groups: <i>base</i> media and
10114 <i>differencing</i> media. A base medium contains all sectors of the
10115 medium data in its own storage and therefore can be used independently.
10116 In contrast, a differencing medium is a "delta" to some other medium and
10117 contains only those sectors which differ from that other medium, which is
10118 then called a <i>parent</i>. The differencing medium is said to be
10119 <i>linked to</i> that parent. The parent may be itself a differencing
10120 medium, thus forming a chain of linked media. The last element in that
10121 chain must always be a base medium. Note that several differencing
10122 media may be linked to the same parent medium.
10123
10124 Differencing media can be distinguished from base media by querying the
10125 <link to="#parent"/> attribute: base media do not have parents they would
10126 depend on, so the value of this attribute is always @c null for them.
10127 Using this attribute, it is possible to walk up the medium tree (from the
10128 child medium to its parent). It is also possible to walk down the tree
10129 using the <link to="#children"/> attribute.
10130
10131 Note that the type of all differencing media is "normal"; all other
10132 values are meaningless for them. Base media may be of any type.
10133
10134 <h3>Automatic composition of the file name part</h3>
10135
10136 Another extension to the <link to="IMedium::location"/> attribute is that
10137 there is a possibility to cause VirtualBox to compose a unique value for
10138 the file name part of the location using the UUID of the hard disk. This
10139 applies only to hard disks in <link to="MediumState_NotCreated"/> state,
10140 e.g. before the storage unit is created, and works as follows. You set the
10141 value of the <link to="IMedium::location"/> attribute to a location
10142 specification which only contains the path specification but not the file
10143 name part and ends with either a forward slash or a backslash character.
10144 In response, VirtualBox will generate a new UUID for the hard disk and
10145 compose the file name using the following pattern:
10146 <pre>
10147 &lt;path&gt;/{&lt;uuid&gt;}.&lt;ext&gt;
10148 </pre>
10149 where <tt>&lt;path&gt;</tt> is the supplied path specification,
10150 <tt>&lt;uuid&gt;</tt> is the newly generated UUID and <tt>&lt;ext&gt;</tt>
10151 is the default extension for the storage format of this hard disk. After
10152 that, you may call any of the methods that create a new hard disk storage
10153 unit and they will use the generated UUID and file name.
10154 </desc>
10155
10156 <attribute name="id" type="uuid" mod="string" readonly="yes">
10157 <desc>
10158 UUID of the medium. For a newly created medium, this value is a randomly
10159 generated UUID.
10160
10161 <note>
10162 For media in one of MediumState_NotCreated, MediumState_Creating or
10163 MediumState_Deleting states, the value of this property is undefined
10164 and will most likely be an empty UUID.
10165 </note>
10166 </desc>
10167 </attribute>
10168
10169 <attribute name="description" type="wstring">
10170 <desc>
10171 Optional description of the medium. For a newly created medium the value
10172 of this attribute is an empty string.
10173
10174 Medium types that don't support this attribute will return E_NOTIMPL in
10175 attempt to get or set this attribute's value.
10176
10177 <note>
10178 For some storage types, reading this attribute may return an outdated
10179 (last known) value when <link to="#state"/> is <link
10180 to="MediumState_Inaccessible"/> or <link
10181 to="MediumState_LockedWrite"/> because the value of this attribute is
10182 stored within the storage unit itself. Also note that changing the
10183 attribute value is not possible in such case, as well as when the
10184 medium is the <link to="MediumState_LockedRead"/> state.
10185 </note>
10186 </desc>
10187 </attribute>
10188
10189 <attribute name="state" type="MediumState" readonly="yes">
10190 <desc>
10191 Returns the current medium state, which is the last state set by
10192 the accessibility check performed by <link to="#refreshState"/>.
10193 If that method has not yet been called on the medium, the state
10194 is "Inaccessible"; as opposed to truly inaccessible media, the
10195 value of <link to="#lastAccessError"/> will be an empty string in
10196 that case.
10197
10198 <note>As of version 3.1, this no longer performs an accessibility check
10199 automatically; call <link to="#refreshState"/> for that.
10200 </note>
10201 </desc>
10202 </attribute>
10203
10204 <attribute name="variant" type="unsigned long" readonly="yes">
10205 <desc>
10206 Returns the storage format variant information for this medium
10207 as a combination of the flags described at <link to="MediumVariant" />.
10208 Before <link to="#refreshState"/> is called this method returns
10209 an undefined value.
10210 </desc>
10211 </attribute>
10212
10213 <attribute name="location" type="wstring">
10214 <desc>
10215 Location of the storage unit holding medium data.
10216
10217 The format of the location string is medium type specific. For medium
10218 types using regular files in a host's file system, the location
10219 string is the full file name.
10220
10221 Some medium types may support changing the storage unit location by
10222 simply changing the value of this property. If this operation is not
10223 supported, the implementation will return E_NOTIMPL in attempt to set
10224 this attribute's value.
10225
10226 When setting a value of the location attribute which is a regular file
10227 in the host's file system, the given file name may be either relative to
10228 the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
10229 absolute. Note that if the given location specification does not contain
10230 the file extension part then a proper default extension will be
10231 automatically appended by the implementation depending on the medium type.
10232 </desc>
10233 </attribute>
10234
10235 <attribute name="name" type="wstring" readonly="yes">
10236 <desc>
10237 Name of the storage unit holding medium data.
10238
10239 The returned string is a short version of the <link to="#location"/>
10240 attribute that is suitable for representing the medium in situations
10241 where the full location specification is too long (such as lists
10242 and comboboxes in GUI frontends). This string is also used by frontends
10243 to sort the media list alphabetically when needed.
10244
10245 For example, for locations that are regular files in the host's file
10246 system, the value of this attribute is just the file name (+ extension),
10247 without the path specification.
10248
10249 Note that as opposed to the <link to="#location"/> attribute, the name
10250 attribute will not necessary be unique for a list of media of the
10251 given type and format.
10252 </desc>
10253 </attribute>
10254
10255 <attribute name="deviceType" type="DeviceType" readonly="yes">
10256 <desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
10257 medium.</desc>
10258 </attribute>
10259
10260 <attribute name="hostDrive" type="boolean" readonly="yes">
10261 <desc>True if this corresponds to a drive on the host.</desc>
10262 </attribute>
10263
10264 <attribute name="size" type="long long" readonly="yes">
10265 <desc>
10266 Physical size of the storage unit used to hold medium data (in bytes).
10267
10268 <note>
10269 For media whose <link to="#state"/> is <link
10270 to="MediumState_Inaccessible"/>, the value of this property is the
10271 last known size. For <link to="MediumState_NotCreated"/> media,
10272 the returned value is zero.
10273 </note>
10274 </desc>
10275 </attribute>
10276
10277 <attribute name="format" type="wstring" readonly="yes">
10278 <desc>
10279 Storage format of this medium.
10280
10281 The value of this attribute is a string that specifies a backend used
10282 to store medium data. The storage format is defined when you create a
10283 new medium or automatically detected when you open an existing medium,
10284 and cannot be changed later.
10285
10286 The list of all storage formats supported by this VirtualBox
10287 installation can be obtained using
10288 <link to="ISystemProperties::mediumFormats"/>.
10289 </desc>
10290 </attribute>
10291
10292 <attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
10293 <desc>
10294 Storage medium format object corresponding to this medium.
10295
10296 The value of this attribute is a reference to the medium format object
10297 that specifies the backend properties used to store medium data. The
10298 storage format is defined when you create a new medium or automatically
10299 detected when you open an existing medium, and cannot be changed later.
10300
10301 <note>@c null is returned if there is no associated medium format
10302 object. This can e.g. happen for medium objects representing host
10303 drives and other special medium objects.</note>
10304 </desc>
10305 </attribute>
10306
10307 <attribute name="type" type="MediumType">
10308 <desc>
10309 Type (role) of this medium.
10310
10311 The following constraints apply when changing the value of this
10312 attribute:
10313 <ul>
10314 <li>If a medium is attached to a virtual machine (either in the
10315 current state or in one of the snapshots), its type cannot be
10316 changed.
10317 </li>
10318 <li>As long as the medium has children, its type cannot be set
10319 to <link to="MediumType_Writethrough"/>.
10320 </li>
10321 <li>The type of all differencing media is
10322 <link to="MediumType_Normal"/> and cannot be changed.
10323 </li>
10324 </ul>
10325
10326 The type of a newly created or opened medium is set to
10327 <link to="MediumType_Normal"/>, except for DVD and floppy media,
10328 which have a type of <link to="MediumType_Writethrough"/>.
10329 </desc>
10330 </attribute>
10331
10332 <attribute name="allowedTypes" type="MediumType" safearray="yes" readonly="yes">
10333 <desc>
10334 Returns which medium types can selected for this medium.
10335
10336 <result name="E_NOTIMPL">
10337 This attribute is not implemented at the moment.
10338 </result>
10339 </desc>
10340 </attribute>
10341
10342 <attribute name="parent" type="IMedium" readonly="yes">
10343 <desc>
10344 Parent of this medium (the medium this medium is directly based
10345 on).
10346
10347 Only differencing media have parents. For base (non-differencing)
10348 media, @c null is returned.
10349 </desc>
10350 </attribute>
10351
10352 <attribute name="children" type="IMedium" safearray="yes" readonly="yes">
10353 <desc>
10354 Children of this medium (all differencing media directly based
10355 on this medium). A @c null array is returned if this medium
10356 does not have any children.
10357 </desc>
10358 </attribute>
10359
10360 <attribute name="base" type="IMedium" readonly="yes">
10361 <desc>
10362 Base medium of this medium.
10363
10364 If this is a differencing medium, its base medium is the medium
10365 the given medium branch starts from. For all other types of media, this
10366 property returns the medium object itself (i.e. the same object this
10367 property is read on).
10368 </desc>
10369 </attribute>
10370
10371 <attribute name="readOnly" type="boolean" readonly="yes">
10372 <desc>
10373 Returns @c true if this medium is read-only and @c false otherwise.
10374
10375 A medium is considered to be read-only when its contents cannot be
10376 modified without breaking the integrity of other parties that depend on
10377 this medium such as its child media or snapshots of virtual machines
10378 where this medium is attached to these machines. If there are no
10379 children and no such snapshots then there is no dependency and the
10380 medium is not read-only.
10381
10382 The value of this attribute can be used to determine the kind of the
10383 attachment that will take place when attaching this medium to a
10384 virtual machine. If the value is @c false then the medium will
10385 be attached directly. If the value is @c true then the medium
10386 will be attached indirectly by creating a new differencing child
10387 medium for that. See the interface description for more information.
10388
10389 Note that all <link to="MediumType_Immutable">Immutable</link> media
10390 are always read-only while all
10391 <link to="MediumType_Writethrough">Writethrough</link> media are
10392 always not.
10393
10394 <note>
10395 The read-only condition represented by this attribute is related to
10396 the medium type and usage, not to the current
10397 <link to="IMedium::state">medium state</link> and not to the read-only
10398 state of the storage unit.
10399 </note>
10400 </desc>
10401 </attribute>
10402
10403 <attribute name="logicalSize" type="long long" readonly="yes">
10404 <desc>
10405 Logical size of this medium (in bytes), as reported to the
10406 guest OS running inside the virtual machine this medium is
10407 attached to. The logical size is defined when the medium is created
10408 and cannot be changed later.
10409
10410 <note>
10411 Reading this property on a differencing medium will return the size
10412 of its <link to="#base"/> medium.
10413 </note>
10414 <note>
10415 For media whose state is <link to="#state"/> is <link
10416 to="MediumState_Inaccessible"/>, the value of this property is the
10417 last known logical size. For <link to="MediumState_NotCreated"/>
10418 media, the returned value is zero.
10419 </note>
10420 </desc>
10421 </attribute>
10422
10423 <attribute name="autoReset" type="boolean">
10424 <desc>
10425 Whether this differencing medium will be automatically reset each
10426 time a virtual machine it is attached to is powered up. This
10427 attribute is automatically set to @c true for the last
10428 differencing image of an "immutable" medium (see
10429 <link to="MediumType" />).
10430
10431 See <link to="#reset"/> for more information about resetting
10432 differencing media.
10433
10434 <note>
10435 Reading this property on a base (non-differencing) medium will
10436 always @c false. Changing the value of this property in this
10437 case is not supported.
10438 </note>
10439
10440 <result name="VBOX_E_NOT_SUPPORTED">
10441 This is not a differencing medium (when changing the attribute
10442 value).
10443 </result>
10444 </desc>
10445 </attribute>
10446
10447 <attribute name="lastAccessError" type="wstring" readonly="yes">
10448 <desc>
10449 Text message that represents the result of the last accessibility
10450 check performed by <link to="#refreshState"/>.
10451
10452 An empty string is returned if the last accessibility check
10453 was successful or has not yet been called. As a result, if
10454 <link to="#state" /> is "Inaccessible" and this attribute is empty,
10455 then <link to="#refreshState"/> has yet to be called; this is the
10456 default value of media after VirtualBox initialization.
10457 A non-empty string indicates a failure and should normally describe
10458 a reason of the failure (for example, a file read error).
10459 </desc>
10460 </attribute>
10461
10462 <attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
10463 <desc>
10464 Array of UUIDs of all machines this medium is attached to.
10465
10466 A @c null array is returned if this medium is not attached to any
10467 machine or to any machine's snapshot.
10468
10469 <note>
10470 The returned array will include a machine even if this medium is not
10471 attached to that machine in the current state but attached to it in
10472 one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
10473 details.
10474 </note>
10475 </desc>
10476 </attribute>
10477
10478 <method name="setIDs">
10479 <desc>
10480 Changes the UUID and parent UUID for a hard disk medium.
10481 </desc>
10482 <param name="setImageId" type="boolean" dir="in">
10483 <desc>
10484 Select whether a new image UUID is set or not.
10485 </desc>
10486 </param>
10487 <param name="imageId" type="uuid" mod="string" dir="in">
10488 <desc>
10489 New UUID for the image. If an empty string is passed, then a new
10490 UUID is automatically created, provided that @a setImageId is @c true.
10491 Specifying a zero UUID is not allowed.
10492 </desc>
10493 </param>
10494 <param name="setParentId" type="boolean" dir="in">
10495 <desc>
10496 Select whether a new parent UUID is set or not.
10497 </desc>
10498 </param>
10499 <param name="parentId" type="uuid" mod="string" dir="in">
10500 <desc>
10501 New parent UUID for the image. If an empty string is passed, then a
10502 new UUID is automatically created, provided @a setParentId is
10503 @c true. A zero UUID is valid.
10504 </desc>
10505 </param>
10506 <result name="E_INVALIDARG">
10507 Invalid parameter combination.
10508 </result>
10509 <result name="VBOX_E_NOT_SUPPORTED">
10510 Medium is not a hard disk medium.
10511 </result>
10512 </method>
10513
10514 <method name="refreshState">
10515 <desc>
10516 If the current medium state (see <link to="MediumState"/>) is one of
10517 "Created", "Inaccessible" or "LockedRead", then this performs an
10518 accessibility check on the medium and sets the value of the <link to="#state"/>
10519 attribute accordingly; that value is also returned for convenience.
10520
10521 For all other state values, this does not perform a refresh but returns
10522 the state only.
10523
10524 The refresh, if performed, may take a long time (several seconds or even
10525 minutes, depending on the storage unit location and format) because it performs an
10526 accessibility check of the storage unit. This check may cause a significant
10527 delay if the storage unit of the given medium is, for example, a file located
10528 on a network share which is not currently accessible due to connectivity
10529 problems. In that case, the call will not return until a timeout
10530 interval defined by the host OS for this operation expires. For this reason,
10531 it is recommended to never read this attribute on the main UI thread to avoid
10532 making the UI unresponsive.
10533
10534 If the last known state of the medium is "Created" and the accessibility
10535 check fails, then the state would be set to "Inaccessible", and
10536 <link to="#lastAccessError"/> may be used to get more details about the
10537 failure. If the state of the medium is "LockedRead", then it remains the
10538 same, and a non-empty value of <link to="#lastAccessError"/> will
10539 indicate a failed accessibility check in this case.
10540
10541 Note that not all medium states are applicable to all medium types.
10542 </desc>
10543 <param name="state" type="MediumState" dir="return">
10544 <desc>
10545 New medium state.
10546 </desc>
10547 </param>
10548 </method>
10549
10550 <method name="getSnapshotIds">
10551 <desc>
10552 Returns an array of UUIDs of all snapshots of the given machine where
10553 this medium is attached to.
10554
10555 If the medium is attached to the machine in the current state, then the
10556 first element in the array will always be the ID of the queried machine
10557 (i.e. the value equal to the @c machineId argument), followed by
10558 snapshot IDs (if any).
10559
10560 If the medium is not attached to the machine in the current state, then
10561 the array will contain only snapshot IDs.
10562
10563 The returned array may be @c null if this medium is not attached
10564 to the given machine at all, neither in the current state nor in one of
10565 the snapshots.
10566 </desc>
10567 <param name="machineId" type="uuid" mod="string" dir="in">
10568 <desc>
10569 UUID of the machine to query.
10570 </desc>
10571 </param>
10572 <param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
10573 <desc>
10574 Array of snapshot UUIDs of the given machine using this medium.
10575 </desc>
10576 </param>
10577 </method>
10578
10579 <method name="lockRead">
10580 <desc>
10581 Locks this medium for reading.
10582
10583 A read lock is shared: many clients can simultaneously lock the
10584 same medium for reading unless it is already locked for writing (see
10585 <link to="#lockWrite"/>) in which case an error is returned.
10586
10587 When the medium is locked for reading, it cannot be modified
10588 from within VirtualBox. This means that any method that changes
10589 the properties of this medium or contents of the storage unit
10590 will return an error (unless explicitly stated otherwise). That
10591 includes an attempt to start a virtual machine that wants to
10592 write to the the medium.
10593
10594 When the virtual machine is started up, it locks for reading all
10595 media it uses in read-only mode. If some medium cannot be locked
10596 for reading, the startup procedure will fail.
10597 A medium is typically locked for reading while it is used by a running
10598 virtual machine but has a depending differencing image that receives
10599 the actual write operations. This way one base medium can have
10600 multiple child differencing images which can be written to
10601 simultaneously. Read-only media such as DVD and floppy images are
10602 also locked for reading only (so they can be in use by multiple
10603 machines simultaneously).
10604
10605 A medium is also locked for reading when it is the source of a
10606 write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10607
10608 The medium locked for reading must be unlocked using the <link
10609 to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
10610 can be nested and must be followed by the same number of paired
10611 <link to="#unlockRead"/> calls.
10612
10613 This method sets the medium state (see <link to="#state"/>) to
10614 "LockedRead" on success. The medium's previous state must be
10615 one of "Created", "Inaccessible" or "LockedRead".
10616
10617 Locking an inaccessible medium is not an error; this method performs
10618 a logical lock that prevents modifications of this medium through
10619 the VirtualBox API, not a physical file-system lock of the underlying
10620 storage unit.
10621
10622 This method returns the current state of the medium
10623 <i>before</i> the operation.
10624
10625 <result name="VBOX_E_INVALID_OBJECT_STATE">
10626 Invalid medium state (e.g. not created, locked, inaccessible,
10627 creating, deleting).
10628 </result>
10629
10630 </desc>
10631 <param name="state" type="MediumState" dir="return">
10632 <desc>
10633 State of the medium after the operation.
10634 </desc>
10635 </param>
10636 </method>
10637
10638 <method name="unlockRead">
10639 <desc>
10640 Cancels the read lock previously set by <link to="#lockRead"/>.
10641
10642 For both success and failure, this method returns the current state
10643 of the medium <i>after</i> the operation.
10644
10645 See <link to="#lockRead"/> for more details.
10646
10647 <result name="VBOX_E_INVALID_OBJECT_STATE">
10648 Medium not locked for reading.
10649 </result>
10650
10651 </desc>
10652 <param name="state" type="MediumState" dir="return">
10653 <desc>
10654 State of the medium after the operation.
10655 </desc>
10656 </param>
10657 </method>
10658
10659 <method name="lockWrite">
10660 <desc>
10661 Locks this medium for writing.
10662
10663 A write lock, as opposed to <link to="#lockRead"/>, is
10664 exclusive: there may be only one client holding a write lock,
10665 and there may be no read locks while the write lock is held.
10666 As a result, read-locking fails if a write lock is held, and
10667 write-locking fails if either a read or another write lock is held.
10668
10669 When a medium is locked for writing, it cannot be modified
10670 from within VirtualBox, and it is not guaranteed that the values
10671 of its properties are up-to-date. Any method that changes the
10672 properties of this medium or contents of the storage unit will
10673 return an error (unless explicitly stated otherwise).
10674
10675 When a virtual machine is started up, it locks for writing all
10676 media it uses to write data to. If any medium could not be locked
10677 for writing, the startup procedure will fail. If a medium has
10678 differencing images, then while the machine is running, only
10679 the last ("leaf") differencing image is locked for writing,
10680 whereas its parents are locked for reading only.
10681
10682 A medium is also locked for writing when it is the target of a
10683 write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
10684
10685 The medium locked for writing must be unlocked using the <link
10686 to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
10687
10688 This method sets the medium state (see <link to="#state"/>) to
10689 "LockedWrite" on success. The medium's previous state must be
10690 either "Created" or "Inaccessible".
10691
10692 Locking an inaccessible medium is not an error; this method performs
10693 a logical lock that prevents modifications of this medium through
10694 the VirtualBox API, not a physical file-system lock of the underlying
10695 storage unit.
10696
10697 For both, success and failure, this method returns the current
10698 state of the medium <i>before</i> the operation.
10699
10700 <result name="VBOX_E_INVALID_OBJECT_STATE">
10701 Invalid medium state (e.g. not created, locked, inaccessible,
10702 creating, deleting).
10703 </result>
10704
10705 </desc>
10706 <param name="state" type="MediumState" dir="return">
10707 <desc>
10708 State of the medium after the operation.
10709 </desc>
10710 </param>
10711 </method>
10712
10713 <method name="unlockWrite">
10714 <desc>
10715 Cancels the write lock previously set by <link to="#lockWrite"/>.
10716
10717 For both success and failure, this method returns the current
10718 state of the medium <i>after</i> the operation.
10719
10720 See <link to="#lockWrite"/> for more details.
10721
10722 <result name="VBOX_E_INVALID_OBJECT_STATE">
10723 Medium not locked for writing.
10724 </result>
10725
10726 </desc>
10727 <param name="state" type="MediumState" dir="return">
10728 <desc>
10729 State of the medium after the operation.
10730 </desc>
10731 </param>
10732 </method>
10733
10734 <method name="close">
10735 <desc>
10736 Closes this medium.
10737
10738 The medium must not be attached to any known virtual machine
10739 and must not have any known child media, otherwise the
10740 operation will fail.
10741
10742 When the medium is successfully closed, it is removed from
10743 the list of registered media, but its storage unit is not
10744 deleted. In particular, this means that this medium can
10745 later be opened again using the <link to="IVirtualBox::openMedium"/>
10746 call.
10747
10748 Note that after this method successfully returns, the given medium
10749 object becomes uninitialized. This means that any attempt
10750 to call any of its methods or attributes will fail with the
10751 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
10752
10753 <result name="VBOX_E_INVALID_OBJECT_STATE">
10754 Invalid medium state (other than not created, created or
10755 inaccessible).
10756 </result>
10757 <result name="VBOX_E_OBJECT_IN_USE">
10758 Medium attached to virtual machine.
10759 </result>
10760 <result name="VBOX_E_FILE_ERROR">
10761 Settings file not accessible.
10762 </result>
10763 <result name="VBOX_E_XML_ERROR">
10764 Could not parse the settings file.
10765 </result>
10766
10767 </desc>
10768 </method>
10769
10770 <!-- property methods -->
10771
10772 <method name="getProperty" const="yes">
10773 <desc>
10774 Returns the value of the custom medium property with the given name.
10775
10776 The list of all properties supported by the given medium format can
10777 be obtained with <link to="IMediumFormat::describeProperties"/>.
10778
10779 <note>If this method returns an empty string in @a value, the requested
10780 property is supported but currently not assigned any value.</note>
10781
10782 <result name="VBOX_E_OBJECT_NOT_FOUND">
10783 Requested property does not exist (not supported by the format).
10784 </result>
10785 <result name="E_INVALIDARG">@a name is @c null or empty.</result>
10786 </desc>
10787 <param name="name" type="wstring" dir="in">
10788 <desc>Name of the property to get.</desc>
10789 </param>
10790 <param name="value" type="wstring" dir="return">
10791 <desc>Current property value.</desc>
10792 </param>
10793 </method>
10794
10795 <method name="setProperty">
10796 <desc>
10797 Sets the value of the custom medium property with the given name.
10798
10799 The list of all properties supported by the given medium format can
10800 be obtained with <link to="IMediumFormat::describeProperties"/>.
10801
10802 <note>Setting the property value to @c null or an empty string is
10803 equivalent to deleting the existing value. A default value (if it is
10804 defined for this property) will be used by the format backend in this
10805 case.</note>
10806
10807 <result name="VBOX_E_OBJECT_NOT_FOUND">
10808 Requested property does not exist (not supported by the format).
10809 </result>
10810 <result name="E_INVALIDARG">@a name is @c null or empty.</result>
10811 </desc>
10812 <param name="name" type="wstring" dir="in">
10813 <desc>Name of the property to set.</desc>
10814 </param>
10815 <param name="value" type="wstring" dir="in">
10816 <desc>Property value to set.</desc>
10817 </param>
10818 </method>
10819
10820 <method name="getProperties" const="yes">
10821 <desc>
10822 Returns values for a group of properties in one call.
10823
10824 The names of the properties to get are specified using the @a names
10825 argument which is a list of comma-separated property names or
10826 an empty string if all properties are to be returned.
10827 <note>Currently the value of this argument is ignored and the method
10828 always returns all existing properties.</note>
10829
10830 The list of all properties supported by the given medium format can
10831 be obtained with <link to="IMediumFormat::describeProperties"/>.
10832
10833 The method returns two arrays, the array of property names corresponding
10834 to the @a names argument and the current values of these properties.
10835 Both arrays have the same number of elements with each element at the
10836 given index in the first array corresponds to an element at the same
10837 index in the second array.
10838
10839 For properties that do not have assigned values, an empty string is
10840 returned at the appropriate index in the @a returnValues array.
10841
10842 </desc>
10843 <param name="names" type="wstring" dir="in">
10844 <desc>
10845 Names of properties to get.
10846 </desc>
10847 </param>
10848 <param name="returnNames" type="wstring" safearray="yes" dir="out">
10849 <desc>Names of returned properties.</desc>
10850 </param>
10851 <param name="returnValues" type="wstring" safearray="yes" dir="return">
10852 <desc>Values of returned properties.</desc>
10853 </param>
10854 </method>
10855
10856 <method name="setProperties">
10857 <desc>
10858 Sets values for a group of properties in one call.
10859
10860 The names of the properties to set are passed in the @a names
10861 array along with the new values for them in the @a values array. Both
10862 arrays have the same number of elements with each element at the given
10863 index in the first array corresponding to an element at the same index
10864 in the second array.
10865
10866 If there is at least one property name in @a names that is not valid,
10867 the method will fail before changing the values of any other properties
10868 from the @a names array.
10869
10870 Using this method over <link to="#setProperty"/> is preferred if you
10871 need to set several properties at once since it is more efficient.
10872
10873 The list of all properties supported by the given medium format can
10874 be obtained with <link to="IMediumFormat::describeProperties"/>.
10875
10876 Setting the property value to @c null or an empty string is equivalent
10877 to deleting the existing value. A default value (if it is defined for
10878 this property) will be used by the format backend in this case.
10879 </desc>
10880 <param name="names" type="wstring" safearray="yes" dir="in">
10881 <desc>Names of properties to set.</desc>
10882 </param>
10883 <param name="values" type="wstring" safearray="yes" dir="in">
10884 <desc>Values of properties to set.</desc>
10885 </param>
10886 </method>
10887
10888 <!-- storage methods -->
10889
10890 <method name="createBaseStorage">
10891 <desc>
10892 Starts creating a hard disk storage unit (fixed/dynamic, according
10893 to the variant flags) in in the background. The previous storage unit
10894 created for this object, if any, must first be deleted using
10895 <link to="#deleteStorage"/>, otherwise the operation will fail.
10896
10897 Before the operation starts, the medium is placed in
10898 <link to="MediumState_Creating"/> state. If the create operation
10899 fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
10900 state.
10901
10902 After the returned progress object reports that the operation has
10903 successfully completed, the medium state will be set to <link
10904 to="MediumState_Created"/>, the medium will be remembered by this
10905 VirtualBox installation and may be attached to virtual machines.
10906
10907 <result name="VBOX_E_NOT_SUPPORTED">
10908 The variant of storage creation operation is not supported. See <link
10909 to="IMediumFormat::capabilities"/>.
10910 </result>
10911 </desc>
10912 <param name="logicalSize" type="long long" dir="in">
10913 <desc>Maximum logical size of the medium in bytes.</desc>
10914 </param>
10915 <param name="variant" type="unsigned long" dir="in">
10916 <desc>Exact image variant which should be created (as a combination of
10917 <link to="MediumVariant" /> flags).</desc>
10918 </param>
10919 <param name="progress" type="IProgress" dir="return">
10920 <desc>Progress object to track the operation completion.</desc>
10921 </param>
10922 </method>
10923
10924 <method name="deleteStorage">
10925 <desc>
10926 Starts deleting the storage unit of this medium.
10927
10928 The medium must not be attached to any known virtual machine and must
10929 not have any known child media, otherwise the operation will fail.
10930 It will also fail if there is no storage unit to delete or if deletion
10931 is already in progress, or if the medium is being in use (locked for
10932 read or for write) or inaccessible. Therefore, the only valid state for
10933 this operation to succeed is <link to="MediumState_Created"/>.
10934
10935 Before the operation starts, the medium is placed in
10936 <link to="MediumState_Deleting"/> state and gets removed from the list
10937 of remembered hard disks (media registry). If the delete operation
10938 fails, the medium will be remembered again and placed back to
10939 <link to="MediumState_Created"/> state.
10940
10941 After the returned progress object reports that the operation is
10942 complete, the medium state will be set to
10943 <link to="MediumState_NotCreated"/> and you will be able to use one of
10944 the storage creation methods to create it again.
10945
10946 <see><link to="#close"/></see>
10947
10948 <result name="VBOX_E_OBJECT_IN_USE">
10949 Medium is attached to a virtual machine.
10950 </result>
10951 <result name="VBOX_E_NOT_SUPPORTED">
10952 Storage deletion is not allowed because neither of storage creation
10953 operations are supported. See
10954 <link to="IMediumFormat::capabilities"/>.
10955 </result>
10956
10957 <note>
10958 If the deletion operation fails, it is not guaranteed that the storage
10959 unit still exists. You may check the <link to="IMedium::state"/> value
10960 to answer this question.
10961 </note>
10962 </desc>
10963 <param name="progress" type="IProgress" dir="return">
10964 <desc>Progress object to track the operation completion.</desc>
10965 </param>
10966 </method>
10967
10968 <!-- diff methods -->
10969
10970 <method name="createDiffStorage">
10971 <desc>
10972 Starts creating an empty differencing storage unit based on this
10973 medium in the format and at the location defined by the @a target
10974 argument.
10975
10976 The target medium must be in <link to="MediumState_NotCreated"/>
10977 state (i.e. must not have an existing storage unit). Upon successful
10978 completion, this operation will set the type of the target medium to
10979 <link to="MediumType_Normal"/> and create a storage unit necessary to
10980 represent the differencing medium data in the given format (according
10981 to the storage format of the target object).
10982
10983 After the returned progress object reports that the operation is
10984 successfully complete, the target medium gets remembered by this
10985 VirtualBox installation and may be attached to virtual machines.
10986
10987 <note>
10988 The medium will be set to <link to="MediumState_LockedRead"/>
10989 state for the duration of this operation.
10990 </note>
10991 <result name="VBOX_E_OBJECT_IN_USE">
10992 Medium not in @c NotCreated state.
10993 </result>
10994 </desc>
10995 <param name="target" type="IMedium" dir="in">
10996 <desc>Target medium.</desc>
10997 </param>
10998 <param name="variant" type="unsigned long" dir="in">
10999 <desc>Exact image variant which should be created (as a combination of
11000 <link to="MediumVariant" /> flags).</desc>
11001 </param>
11002 <param name="progress" type="IProgress" dir="return">
11003 <desc>Progress object to track the operation completion.</desc>
11004 </param>
11005 </method>
11006
11007 <method name="mergeTo">
11008 <desc>
11009 Starts merging the contents of this medium and all intermediate
11010 differencing media in the chain to the given target medium.
11011
11012 The target medium must be either a descendant of this medium or
11013 its ancestor (otherwise this method will immediately return a failure).
11014 It follows that there are two logical directions of the merge operation:
11015 from ancestor to descendant (<i>forward merge</i>) and from descendant to
11016 ancestor (<i>backward merge</i>). Let us consider the following medium
11017 chain:
11018
11019 <pre>Base &lt;- Diff_1 &lt;- Diff_2</pre>
11020
11021 Here, calling this method on the <tt>Base</tt> medium object with
11022 <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
11023 <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
11024 merge. Note that in both cases the contents of the resulting medium
11025 will be the same, the only difference is the medium object that takes
11026 the result of the merge operation. In case of the forward merge in the
11027 above example, the result will be written to <tt>Diff_2</tt>; in case of
11028 the backward merge, the result will be written to <tt>Base</tt>. In
11029 other words, the result of the operation is always stored in the target
11030 medium.
11031
11032 Upon successful operation completion, the storage units of all media in
11033 the chain between this (source) medium and the target medium, including
11034 the source medium itself, will be automatically deleted and the
11035 relevant medium objects (including this medium) will become
11036 uninitialized. This means that any attempt to call any of
11037 their methods or attributes will fail with the
11038 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
11039 example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
11040 delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
11041 Note that <tt>Diff_2</tt> in this case will become a base medium
11042 itself since it will no longer be based on any other medium.
11043
11044 Considering the above, all of the following conditions must be met in
11045 order for the merge operation to succeed:
11046 <ul>
11047 <li>
11048 Neither this (source) medium nor any intermediate
11049 differencing medium in the chain between it and the target
11050 medium is attached to any virtual machine.
11051 </li>
11052 <li>
11053 Neither the source medium nor the target medium is an
11054 <link to="MediumType_Immutable"/> medium.
11055 </li>
11056 <li>
11057 The part of the medium tree from the source medium to the
11058 target medium is a linear chain, i.e. all medium in this
11059 chain have exactly one child which is the next medium in this
11060 chain. The only exception from this rule is the target medium in
11061 the forward merge operation; it is allowed to have any number of
11062 child media because the merge operation will not change its
11063 logical contents (as it is seen by the guest OS or by children).
11064 </li>
11065 <li>
11066 None of the involved media are in
11067 <link to="MediumState_LockedRead"/> or
11068 <link to="MediumState_LockedWrite"/> state.
11069 </li>
11070 </ul>
11071
11072 <note>
11073 This (source) medium and all intermediates will be placed to <link
11074 to="MediumState_Deleting"/> state and the target medium will be
11075 placed to <link to="MediumState_LockedWrite"/> state and for the
11076 duration of this operation.
11077 </note>
11078 </desc>
11079 <param name="target" type="IMedium" dir="in">
11080 <desc>Target medium.</desc>
11081 </param>
11082 <param name="progress" type="IProgress" dir="return">
11083 <desc>Progress object to track the operation completion.</desc>
11084 </param>
11085 </method>
11086
11087 <!-- clone method -->
11088
11089 <method name="cloneTo">
11090 <desc>
11091 Starts creating a clone of this medium in the format and at the
11092 location defined by the @a target argument.
11093
11094 The target medium must be either in <link to="MediumState_NotCreated"/>
11095 state (i.e. must not have an existing storage unit) or in
11096 <link to="MediumState_Created"/> state (i.e. created and not locked, and
11097 big enough to hold the data or else the copy will be partial). Upon
11098 successful completion, the cloned medium will contain exactly the
11099 same sector data as the medium being cloned, except that in the
11100 first case a new UUID for the clone will be randomly generated, and in
11101 the second case the UUID will remain unchanged.
11102
11103 The @a parent argument defines which medium will be the parent
11104 of the clone. Passing a @c null reference indicates that the clone will
11105 be a base image, i.e. completely independent. It is possible to specify
11106 an arbitrary medium for this parameter, including the parent of the
11107 medium which is being cloned. Even cloning to a child of the source
11108 medium is possible. Note that when cloning to an existing image, the
11109 @a parent argument is ignored.
11110
11111 After the returned progress object reports that the operation is
11112 successfully complete, the target medium gets remembered by this
11113 VirtualBox installation and may be attached to virtual machines.
11114
11115 <note>
11116 This medium will be placed to <link to="MediumState_LockedRead"/>
11117 state for the duration of this operation.
11118 </note>
11119 <result name="E_NOTIMPL">
11120 The specified cloning variant is not supported at the moment.
11121 </result>
11122 </desc>
11123 <param name="target" type="IMedium" dir="in">
11124 <desc>Target medium.</desc>
11125 </param>
11126 <param name="variant" type="unsigned long" dir="in">
11127 <desc>Exact image variant which should be created (as a combination of
11128 <link to="MediumVariant" /> flags).</desc>
11129 </param>
11130 <param name="parent" type="IMedium" dir="in">
11131 <desc>Parent of the cloned medium.</desc>
11132 </param>
11133 <param name="progress" type="IProgress" dir="return">
11134 <desc>Progress object to track the operation completion.</desc>
11135 </param>
11136 </method>
11137
11138 <!-- other methods -->
11139
11140 <method name="compact">
11141 <desc>
11142 Starts compacting of this medium. This means that the medium is
11143 transformed into a possibly more compact storage representation.
11144 This potentially creates temporary images, which can require a
11145 substantial amount of additional disk space.
11146
11147 This medium will be placed to <link to="MediumState_LockedWrite"/>
11148 state and all its parent media (if any) will be placed to
11149 <link to="MediumState_LockedRead"/> state for the duration of this
11150 operation.
11151
11152 Please note that the results can be either returned straight away,
11153 or later as the result of the background operation via the object
11154 returned via the @a progress parameter.
11155
11156 <result name="VBOX_E_NOT_SUPPORTED">
11157 Medium format does not support compacting (but potentially
11158 needs it).
11159 </result>
11160 </desc>
11161 <param name="progress" type="IProgress" dir="return">
11162 <desc>Progress object to track the operation completion.</desc>
11163 </param>
11164 </method>
11165
11166 <method name="resize">
11167 <desc>
11168 Starts resizing this medium. This means that the nominal size of the
11169 medium is set to the new value. Both increasing and decreasing the
11170 size is possible, and there are no safety checks, since VirtualBox
11171 does not make any assumptions about the medium contents.
11172
11173 Resizing usually needs additional disk space, and possibly also
11174 some temporary disk space. Note that resize does not create a full
11175 temporary copy of the medium, so the additional disk space requirement
11176 is usually much lower than using the clone operation.
11177
11178 This medium will be placed to <link to="MediumState_LockedWrite"/>
11179 state for the duration of this operation.
11180
11181 Please note that the results can be either returned straight away,
11182 or later as the result of the background operation via the object
11183 returned via the @a progress parameter.
11184
11185 <result name="VBOX_E_NOT_SUPPORTED">
11186 Medium format does not support resizing.
11187 </result>
11188 </desc>
11189 <param name="logicalSize" type="long long" dir="in">
11190 <desc>New nominal capacity of the medium in bytes.</desc>
11191 </param>
11192 <param name="progress" type="IProgress" dir="return">
11193 <desc>Progress object to track the operation completion.</desc>
11194 </param>
11195 </method>
11196
11197 <method name="reset">
11198 <desc>
11199 Starts erasing the contents of this differencing medium.
11200
11201 This operation will reset the differencing medium to its initial
11202 state when it does not contain any sector data and any read operation is
11203 redirected to its parent medium. This automatically gets called
11204 during VM power-up for every medium whose <link to="#autoReset" />
11205 attribute is @c true.
11206
11207 The medium will be write-locked for the duration of this operation (see
11208 <link to="#lockWrite" />).
11209
11210 <result name="VBOX_E_NOT_SUPPORTED">
11211 This is not a differencing medium.
11212 </result>
11213 <result name="VBOX_E_INVALID_OBJECT_STATE">
11214 Medium is not in <link to="MediumState_Created"/> or
11215 <link to="MediumState_Inaccessible"/> state.
11216 </result>
11217 </desc>
11218 <param name="progress" type="IProgress" dir="return">
11219 <desc>Progress object to track the operation completion.</desc>
11220 </param>
11221 </method>
11222
11223 </interface>
11224
11225
11226 <!--
11227 // IMediumFormat
11228 /////////////////////////////////////////////////////////////////////////
11229 -->
11230
11231 <enum
11232 name="DataType"
11233 uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
11234 >
11235 <const name="Int32" value="0"/>
11236 <const name="Int8" value="1"/>
11237 <const name="String" value="2"/>
11238 </enum>
11239
11240 <enum
11241 name="DataFlags"
11242 uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
11243 >
11244 <const name="None" value="0x00"/>
11245 <const name="Mandatory" value="0x01"/>
11246 <const name="Expert" value="0x02"/>
11247 <const name="Array" value="0x04"/>
11248 <const name="FlagMask" value="0x07"/>
11249 </enum>
11250
11251 <enum
11252 name="MediumFormatCapabilities"
11253 uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
11254 >
11255 <desc>
11256 Medium format capability flags.
11257 </desc>
11258
11259 <const name="Uuid" value="0x01">
11260 <desc>
11261 Supports UUIDs as expected by VirtualBox code.
11262 </desc>
11263 </const>
11264
11265 <const name="CreateFixed" value="0x02">
11266 <desc>
11267 Supports creating fixed size images, allocating all space instantly.
11268 </desc>
11269 </const>
11270
11271 <const name="CreateDynamic" value="0x04">
11272 <desc>
11273 Supports creating dynamically growing images, allocating space on
11274 demand.
11275 </desc>
11276 </const>
11277
11278 <const name="CreateSplit2G" value="0x08">
11279 <desc>
11280 Supports creating images split in chunks of a bit less than 2 GBytes.
11281 </desc>
11282 </const>
11283
11284 <const name="Differencing" value="0x10">
11285 <desc>
11286 Supports being used as a format for differencing media (see <link
11287 to="IMedium::createDiffStorage"/>).
11288 </desc>
11289 </const>
11290
11291 <const name="Asynchronous" value="0x20">
11292 <desc>
11293 Supports asynchronous I/O operations for at least some configurations.
11294 </desc>
11295 </const>
11296
11297 <const name="File" value="0x40">
11298 <desc>
11299 The format backend operates on files (the <link to="IMedium::location"/>
11300 attribute of the medium specifies a file used to store medium
11301 data; for a list of supported file extensions see
11302 <link to="IMediumFormat::describeFileExtensions"/>).
11303 </desc>
11304 </const>
11305
11306 <const name="Properties" value="0x80">
11307 <desc>
11308 The format backend uses the property interface to configure the storage
11309 location and properties (the <link to="IMediumFormat::describeProperties"/>
11310 method is used to get access to properties supported by the given medium format).
11311 </desc>
11312 </const>
11313
11314 <const name="TcpNetworking" value="0x100">
11315 <desc>
11316 The format backend uses the TCP networking interface for network access.
11317 </desc>
11318 </const>
11319
11320 <const name="VFS" value="0x200">
11321 <desc>
11322 The format backend supports virtual filesystem functionality.
11323 </desc>
11324 </const>
11325
11326 <const name="CapabilityMask" value="0x3FF"/>
11327 </enum>
11328
11329 <interface
11330 name="IMediumFormat" extends="$unknown"
11331 uuid="9bd5b655-ea47-4637-99f3-aad0948be35b"
11332 wsmap="managed"
11333 >
11334 <desc>
11335 The IMediumFormat interface represents a medium format.
11336
11337 Each medium format has an associated backend which is used to handle
11338 media stored in this format. This interface provides information
11339 about the properties of the associated backend.
11340
11341 Each medium format is identified by a string represented by the
11342 <link to="#id"/> attribute. This string is used in calls like
11343 <link to="IVirtualBox::createHardDisk"/> to specify the desired
11344 format.
11345
11346 The list of all supported medium formats can be obtained using
11347 <link to="ISystemProperties::mediumFormats"/>.
11348
11349 <see><link to="IMedium"/></see>
11350 </desc>
11351
11352 <attribute name="id" type="wstring" readonly="yes">
11353 <desc>
11354 Identifier of this format.
11355
11356 The format identifier is a non-@c null non-empty ASCII string. Note that
11357 this string is case-insensitive. This means that, for example, all of
11358 the following strings:
11359 <pre>
11360 "VDI"
11361 "vdi"
11362 "VdI"</pre>
11363 refer to the same medium format.
11364
11365 This string is used in methods of other interfaces where it is necessary
11366 to specify a medium format, such as
11367 <link to="IVirtualBox::createHardDisk"/>.
11368 </desc>
11369 </attribute>
11370
11371 <attribute name="name" type="wstring" readonly="yes">
11372 <desc>
11373 Human readable description of this format.
11374
11375 Mainly for use in file open dialogs.
11376 </desc>
11377 </attribute>
11378
11379 <attribute name="capabilities" type="unsigned long" readonly="yes">
11380 <desc>
11381 Capabilities of the format as a set of bit flags.
11382
11383 For the meaning of individual capability flags see
11384 <link to="MediumFormatCapabilities"/>.
11385 </desc>
11386 </attribute>
11387
11388 <method name="describeFileExtensions">
11389 <desc>
11390 Returns two arrays describing the supported file extensions.
11391
11392 The first array contains the supported extensions and the seconds one
11393 the type each extension supports. Both have the same size.
11394
11395 Note that some backends do not work on files, so this array may be
11396 empty.
11397
11398 <see><link to="IMediumFormat::capabilities"/></see>
11399 </desc>
11400 <param name="extensions" type="wstring" safearray="yes" dir="out">
11401 <desc>The array of supported extensions.</desc>
11402 </param>
11403 <param name="type" type="DeviceType" safearray="yes" dir="out">
11404 <desc>The array which indicates the device type for every given extension.</desc>
11405 </param>
11406 </method>
11407
11408 <method name="describeProperties" const="yes">
11409 <desc>
11410 Returns several arrays describing the properties supported by this
11411 format.
11412
11413 An element with the given index in each array describes one
11414 property. Thus, the number of elements in each returned array is the
11415 same and corresponds to the number of supported properties.
11416
11417 The returned arrays are filled in only if the
11418 <link to="MediumFormatCapabilities_Properties"/> flag is set.
11419 All arguments must be non-@c null.
11420
11421 <see><link to="DataType"/>, <link to="DataFlags"/></see>
11422 </desc>
11423
11424 <param name="names" type="wstring" safearray="yes" dir="out">
11425 <desc>Array of property names.</desc>
11426 </param>
11427 <param name="description" type="wstring" safearray="yes" dir="out">
11428 <desc>Array of property descriptions.</desc>
11429 </param>
11430 <param name="types" type="DataType" safearray="yes" dir="out">
11431 <desc>Array of property types.</desc>
11432 </param>
11433 <param name="flags" type="unsigned long" safearray="yes" dir="out">
11434 <desc>Array of property flags.</desc>
11435 </param>
11436 <param name="defaults" type="wstring" safearray="yes" dir="out">
11437 <desc>Array of default property values.</desc>
11438 </param>
11439 </method>
11440
11441 </interface>
11442
11443
11444 <!--
11445 // IKeyboard
11446 /////////////////////////////////////////////////////////////////////////
11447 -->
11448
11449 <interface
11450 name="IKeyboard" extends="$unknown"
11451 uuid="f6916ec5-a881-4237-898f-7de58cf88672"
11452 wsmap="managed"
11453 >
11454 <desc>
11455 The IKeyboard interface represents the virtual machine's keyboard. Used
11456 in <link to="IConsole::keyboard"/>.
11457
11458 Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
11459 to the virtual machine.
11460
11461 </desc>
11462 <method name="putScancode">
11463 <desc>Sends a scancode to the keyboard.
11464
11465 <result name="VBOX_E_IPRT_ERROR">
11466 Could not send scan code to virtual keyboard.
11467 </result>
11468
11469 </desc>
11470 <param name="scancode" type="long" dir="in"/>
11471 </method>
11472
11473 <method name="putScancodes">
11474 <desc>Sends an array of scancodes to the keyboard.
11475
11476 <result name="VBOX_E_IPRT_ERROR">
11477 Could not send all scan codes to virtual keyboard.
11478 </result>
11479
11480 </desc>
11481 <param name="scancodes" type="long" dir="in" safearray="yes"/>
11482 <param name="codesStored" type="unsigned long" dir="return"/>
11483 </method>
11484
11485 <method name="putCAD">
11486 <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
11487 function is nothing special, it is just a convenience function
11488 calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
11489
11490 <result name="VBOX_E_IPRT_ERROR">
11491 Could not send all scan codes to virtual keyboard.
11492 </result>
11493
11494 </desc>
11495 </method>
11496
11497 <attribute name="eventSource" type="IEventSource" readonly="yes">
11498 <desc>
11499 Event source for keyboard events.
11500 </desc>
11501 </attribute>
11502
11503 </interface>
11504
11505
11506 <!--
11507 // IMouse
11508 /////////////////////////////////////////////////////////////////////////
11509 -->
11510
11511 <enum
11512 name="MouseButtonState"
11513 uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
11514 >
11515 <desc>
11516 Mouse button state.
11517 </desc>
11518
11519 <const name="LeftButton" value="0x01"/>
11520 <const name="RightButton" value="0x02"/>
11521 <const name="MiddleButton" value="0x04"/>
11522 <const name="WheelUp" value="0x08"/>
11523 <const name="WheelDown" value="0x10"/>
11524 <const name="XButton1" value="0x20"/>
11525 <const name="XButton2" value="0x40"/>
11526 <const name="MouseStateMask" value="0x7F"/>
11527 </enum>
11528
11529 <interface
11530 name="IMouse" extends="$unknown"
11531 uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
11532 wsmap="managed"
11533 >
11534 <desc>
11535 The IMouse interface represents the virtual machine's mouse. Used in
11536 <link to="IConsole::mouse"/>.
11537
11538 Through this interface, the virtual machine's virtual mouse can be
11539 controlled.
11540 </desc>
11541
11542 <attribute name="absoluteSupported" type="boolean" readonly="yes">
11543 <desc>
11544 Whether the guest OS supports absolute mouse pointer positioning
11545 or not.
11546 <note>
11547 You can use the <link to="IMouseCapabilityChangedEvent"/>
11548 event to be instantly informed about changes of this attribute
11549 during virtual machine execution.
11550 </note>
11551 <see><link to="#putMouseEventAbsolute"/></see>
11552 </desc>
11553 </attribute>
11554
11555 <attribute name="relativeSupported" type="boolean" readonly="yes">
11556 <desc>
11557 Whether the guest OS supports relative mouse pointer positioning
11558 or not.
11559 <note>
11560 You can use the <link to="IMouseCapabilityChangedEvent"/>
11561 event to be instantly informed about changes of this attribute
11562 during virtual machine execution.
11563 </note>
11564 <see><link to="#putMouseEvent"/></see>
11565 </desc>
11566 </attribute>
11567
11568 <attribute name="needsHostCursor" type="boolean" readonly="yes">
11569 <desc>
11570 Whether the guest OS can currently switch to drawing it's own mouse
11571 cursor on demand.
11572 <note>
11573 You can use the <link to="IMouseCapabilityChangedEvent"/>
11574 event to be instantly informed about changes of this attribute
11575 during virtual machine execution.
11576 </note>
11577 <see><link to="#putMouseEvent"/></see>
11578 </desc>
11579 </attribute>
11580
11581 <method name="putMouseEvent">
11582 <desc>
11583 Initiates a mouse event using relative pointer movements
11584 along x and y axis.
11585
11586 <result name="E_ACCESSDENIED">
11587 Console not powered up.
11588 </result>
11589 <result name="VBOX_E_IPRT_ERROR">
11590 Could not send mouse event to virtual mouse.
11591 </result>
11592
11593 </desc>
11594
11595 <param name="dx" type="long" dir="in">
11596 <desc>
11597 Amount of pixels the mouse should move to the right.
11598 Negative values move the mouse to the left.
11599 </desc>
11600 </param>
11601 <param name="dy" type="long" dir="in">
11602 <desc>
11603 Amount of pixels the mouse should move downwards.
11604 Negative values move the mouse upwards.
11605 </desc>
11606 </param>
11607 <param name="dz" type="long" dir="in">
11608 <desc>
11609 Amount of mouse wheel moves.
11610 Positive values describe clockwise wheel rotations,
11611 negative values describe counterclockwise rotations.
11612 </desc>
11613 </param>
11614 <param name="dw" type="long" dir="in">
11615 <desc>
11616 Amount of horizontal mouse wheel moves.
11617 Positive values describe a movement to the left,
11618 negative values describe a movement to the right.
11619 </desc>
11620 </param>
11621 <param name="buttonState" type="long" dir="in">
11622 <desc>
11623 The current state of mouse buttons. Every bit represents
11624 a mouse button as follows:
11625 <table>
11626 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11627 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11628 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11629 </table>
11630 A value of <tt>1</tt> means the corresponding button is pressed.
11631 otherwise it is released.
11632 </desc>
11633 </param>
11634 </method>
11635
11636 <method name="putMouseEventAbsolute">
11637 <desc>
11638 Positions the mouse pointer using absolute x and y coordinates.
11639 These coordinates are expressed in pixels and
11640 start from <tt>[1,1]</tt> which corresponds to the top left
11641 corner of the virtual display.
11642
11643 <result name="E_ACCESSDENIED">
11644 Console not powered up.
11645 </result>
11646 <result name="VBOX_E_IPRT_ERROR">
11647 Could not send mouse event to virtual mouse.
11648 </result>
11649
11650 <note>
11651 This method will have effect only if absolute mouse
11652 positioning is supported by the guest OS.
11653 </note>
11654
11655 <see><link to="#absoluteSupported"/></see>
11656 </desc>
11657
11658 <param name="x" type="long" dir="in">
11659 <desc>
11660 X coordinate of the pointer in pixels, starting from @c 1.
11661 </desc>
11662 </param>
11663 <param name="y" type="long" dir="in">
11664 <desc>
11665 Y coordinate of the pointer in pixels, starting from @c 1.
11666 </desc>
11667 </param>
11668 <param name="dz" type="long" dir="in">
11669 <desc>
11670 Amount of mouse wheel moves.
11671 Positive values describe clockwise wheel rotations,
11672 negative values describe counterclockwise rotations.
11673 </desc>
11674 </param>
11675 <param name="dw" type="long" dir="in">
11676 <desc>
11677 Amount of horizontal mouse wheel moves.
11678 Positive values describe a movement to the left,
11679 negative values describe a movement to the right.
11680 </desc>
11681 </param>
11682 <param name="buttonState" type="long" dir="in">
11683 <desc>
11684 The current state of mouse buttons. Every bit represents
11685 a mouse button as follows:
11686 <table>
11687 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
11688 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
11689 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
11690 </table>
11691 A value of @c 1 means the corresponding button is pressed.
11692 otherwise it is released.
11693 </desc>
11694 </param>
11695 </method>
11696
11697 <attribute name="eventSource" type="IEventSource" readonly="yes">
11698 <desc>
11699 Event source for mouse events.
11700 </desc>
11701 </attribute>
11702
11703 </interface>
11704
11705 <!--
11706 // IDisplay
11707 /////////////////////////////////////////////////////////////////////////
11708 -->
11709
11710 <enum
11711 name="FramebufferPixelFormat"
11712 uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
11713 >
11714 <desc>
11715 Format of the video memory buffer. Constants represented by this enum can
11716 be used to test for particular values of <link
11717 to="IFramebuffer::pixelFormat"/>. See also <link
11718 to="IFramebuffer::requestResize"/>.
11719
11720 See also www.fourcc.org for more information about FOURCC pixel formats.
11721 </desc>
11722
11723 <const name="Opaque" value="0">
11724 <desc>
11725 Unknown buffer format (the user may not assume any particular format of
11726 the buffer).
11727 </desc>
11728 </const>
11729 <const name="FOURCC_RGB" value="0x32424752">
11730 <desc>
11731 Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
11732 bit layout).
11733 </desc>
11734 </const>
11735 </enum>
11736
11737 <interface
11738 name="IFramebuffer" extends="$unknown"
11739 uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
11740 wsmap="suppress"
11741 >
11742 <attribute name="address" type="octet" mod="ptr" readonly="yes">
11743 <desc>Address of the start byte of the frame buffer.</desc>
11744 </attribute>
11745
11746 <attribute name="width" type="unsigned long" readonly="yes">
11747 <desc>Frame buffer width, in pixels.</desc>
11748 </attribute>
11749
11750 <attribute name="height" type="unsigned long" readonly="yes">
11751 <desc>Frame buffer height, in pixels.</desc>
11752 </attribute>
11753
11754 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
11755 <desc>
11756 Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
11757 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
11758 are: 8, 15, 16, 24 and 32.
11759 </desc>
11760 </attribute>
11761
11762 <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
11763 <desc>
11764 Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
11765 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
11766 size of the scan line must be aligned to 32 bits.
11767 </desc>
11768 </attribute>
11769
11770 <attribute name="pixelFormat" type="unsigned long" readonly="yes">
11771 <desc>
11772 Frame buffer pixel format. It's either one of the values defined by <link
11773 to="FramebufferPixelFormat"/> or a raw FOURCC code.
11774 <note>
11775 This attribute must never return <link
11776 to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
11777 <link to="#address"/> points to must be always known.
11778 </note>
11779 </desc>
11780 </attribute>
11781
11782 <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
11783 <desc>
11784 Defines whether this frame buffer uses the virtual video card's memory
11785 buffer (guest VRAM) directly or not. See <link
11786 to="IFramebuffer::requestResize"/> for more information.
11787 </desc>
11788 </attribute>
11789
11790 <attribute name="heightReduction" type="unsigned long" readonly="yes">
11791 <desc>
11792 Hint from the frame buffer about how much of the standard
11793 screen height it wants to use for itself. This information is
11794 exposed to the guest through the VESA BIOS and VMMDev interface
11795 so that it can use it for determining its video mode table. It
11796 is not guaranteed that the guest respects the value.
11797 </desc>
11798 </attribute>
11799
11800 <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
11801 <desc>
11802 An alpha-blended overlay which is superposed over the frame buffer.
11803 The initial purpose is to allow the display of icons providing
11804 information about the VM state, including disk activity, in front
11805 ends which do not have other means of doing that. The overlay is
11806 designed to controlled exclusively by IDisplay. It has no locking
11807 of its own, and any changes made to it are not guaranteed to be
11808 visible until the affected portion of IFramebuffer is updated. The
11809 overlay can be created lazily the first time it is requested. This
11810 attribute can also return @c null to signal that the overlay is not
11811 implemented.
11812 </desc>
11813 </attribute>
11814
11815 <attribute name="winId" type="long long" readonly="yes">
11816 <desc>
11817 Platform-dependent identifier of the window where context of this
11818 frame buffer is drawn, or zero if there's no such window.
11819 </desc>
11820 </attribute>
11821
11822 <method name="lock">
11823 <desc>
11824 Locks the frame buffer.
11825 Gets called by the IDisplay object where this frame buffer is
11826 bound to.
11827 </desc>
11828 </method>
11829
11830 <method name="unlock">
11831 <desc>
11832 Unlocks the frame buffer.
11833 Gets called by the IDisplay object where this frame buffer is
11834 bound to.
11835 </desc>
11836 </method>
11837
11838 <method name="notifyUpdate">
11839 <desc>
11840 Informs about an update.
11841 Gets called by the display object where this buffer is
11842 registered.
11843 </desc>
11844 <param name="x" type="unsigned long" dir="in"/>
11845 <param name="y" type="unsigned long" dir="in"/>
11846 <param name="width" type="unsigned long" dir="in"/>
11847 <param name="height" type="unsigned long" dir="in"/>
11848 </method>
11849
11850 <method name="requestResize">
11851 <desc>
11852 Requests a size and pixel format change.
11853
11854 There are two modes of working with the video buffer of the virtual
11855 machine. The <i>indirect</i> mode implies that the IFramebuffer
11856 implementation allocates a memory buffer for the requested display mode
11857 and provides it to the virtual machine. In <i>direct</i> mode, the
11858 IFramebuffer implementation uses the memory buffer allocated and owned
11859 by the virtual machine. This buffer represents the video memory of the
11860 emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
11861 usually faster because the implementation gets a raw pointer to the
11862 guest VRAM buffer which it can directly use for visualizing the contents
11863 of the virtual display, as opposed to the indirect mode where the
11864 contents of guest VRAM are copied to the memory buffer provided by
11865 the implementation every time a display update occurs.
11866
11867 It is important to note that the direct mode is really fast only when
11868 the implementation uses the given guest VRAM buffer directly, for
11869 example, by blitting it to the window representing the virtual machine's
11870 display, which saves at least one copy operation comparing to the
11871 indirect mode. However, using the guest VRAM buffer directly is not
11872 always possible: the format and the color depth of this buffer may be
11873 not supported by the target window, or it may be unknown (opaque) as in
11874 case of text or non-linear multi-plane VGA video modes. In this case,
11875 the indirect mode (that is always available) should be used as a
11876 fallback: when the guest VRAM contents are copied to the
11877 implementation-provided memory buffer, color and format conversion is
11878 done automatically by the underlying code.
11879
11880 The @a pixelFormat parameter defines whether the direct mode is
11881 available or not. If @a pixelFormat is <link
11882 to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
11883 VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
11884 @a bytesPerLine parameters must be ignored and the implementation must use
11885 the indirect mode (where it provides its own buffer in one of the
11886 supported formats). In all other cases, @a pixelFormat together with
11887 @a bitsPerPixel and @a bytesPerLine define the format of the video memory
11888 buffer pointed to by the @a VRAM parameter and the implementation is
11889 free to choose which mode to use. To indicate that this frame buffer uses
11890 the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
11891 attribute must return @c true and <link to="#address"/> must
11892 return exactly the same address that is passed in the @a VRAM parameter
11893 of this method; otherwise it is assumed that the indirect strategy is
11894 chosen.
11895
11896 The @a width and @a height parameters represent the size of the
11897 requested display mode in both modes. In case of indirect mode, the
11898 provided memory buffer should be big enough to store data of the given
11899 display mode. In case of direct mode, it is guaranteed that the given
11900 @a VRAM buffer contains enough space to represent the display mode of the
11901 given size. Note that this frame buffer's <link to="#width"/> and <link
11902 to="#height"/> attributes must return exactly the same values as
11903 passed to this method after the resize is completed (see below).
11904
11905 The @a finished output parameter determines if the implementation has
11906 finished resizing the frame buffer or not. If, for some reason, the
11907 resize cannot be finished immediately during this call, @a finished
11908 must be set to @c false, and the implementation must call
11909 <link to="IDisplay::resizeCompleted"/> after it has returned from
11910 this method as soon as possible. If @a finished is @c false, the
11911 machine will not call any frame buffer methods until
11912 <link to="IDisplay::resizeCompleted"/> is called.
11913
11914 Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
11915 <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
11916 this frame buffer must return exactly the same values as specified in the
11917 parameters of this method, after the resize is completed. If the
11918 indirect mode is chosen, these attributes must return values describing
11919 the format of the implementation's own memory buffer <link
11920 to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
11921 value must always correlate with <link to="#pixelFormat"/>. Note that
11922 the <link to="#pixelFormat"/> attribute must never return <link
11923 to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
11924
11925 <note>
11926 This method is called by the IDisplay object under the
11927 <link to="#lock"/> provided by this IFramebuffer
11928 implementation. If this method returns @c false in @a finished, then
11929 this lock is not released until
11930 <link to="IDisplay::resizeCompleted"/> is called.
11931 </note>
11932 </desc>
11933 <param name="screenId" type="unsigned long" dir="in">
11934 <desc>
11935 Logical screen number. Must be used in the corresponding call to
11936 <link to="IDisplay::resizeCompleted"/> if this call is made.
11937 </desc>
11938 </param>
11939 <param name="pixelFormat" type="unsigned long" dir="in">
11940 <desc>
11941 Pixel format of the memory buffer pointed to by @a VRAM.
11942 See also <link to="FramebufferPixelFormat"/>.
11943 </desc>
11944 </param>
11945 <param name="VRAM" type="octet" mod="ptr" dir="in">
11946 <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
11947 </param>
11948 <param name="bitsPerPixel" type="unsigned long" dir="in">
11949 <desc>Color depth, bits per pixel.</desc>
11950 </param>
11951 <param name="bytesPerLine" type="unsigned long" dir="in">
11952 <desc>Size of one scan line, in bytes.</desc>
11953 </param>
11954 <param name="width" type="unsigned long" dir="in">
11955 <desc>Width of the guest display, in pixels.</desc>
11956 </param>
11957 <param name="height" type="unsigned long" dir="in">
11958 <desc>Height of the guest display, in pixels.</desc>
11959 </param>
11960 <param name="finished" type="boolean" dir="return">
11961 <desc>
11962 Can the VM start using the new frame buffer immediately
11963 after this method returns or it should wait for
11964 <link to="IDisplay::resizeCompleted"/>.
11965 </desc>
11966 </param>
11967 </method>
11968
11969 <method name="videoModeSupported">
11970 <desc>
11971 Returns whether the frame buffer implementation is willing to
11972 support a given video mode. In case it is not able to render
11973 the video mode (or for some reason not willing), it should
11974 return @c false. Usually this method is called when the guest
11975 asks the VMM device whether a given video mode is supported
11976 so the information returned is directly exposed to the guest.
11977 It is important that this method returns very quickly.
11978 </desc>
11979 <param name="width" type="unsigned long" dir="in"/>
11980 <param name="height" type="unsigned long" dir="in"/>
11981 <param name="bpp" type="unsigned long" dir="in"/>
11982 <param name="supported" type="boolean" dir="return"/>
11983 </method>
11984
11985 <method name="getVisibleRegion">
11986 <desc>
11987 Returns the visible region of this frame buffer.
11988
11989 If the @a rectangles parameter is @c null then the value of the
11990 @a count parameter is ignored and the number of elements necessary to
11991 describe the current visible region is returned in @a countCopied.
11992
11993 If @a rectangles is not @c null but @a count is less
11994 than the required number of elements to store region data, the method
11995 will report a failure. If @a count is equal or greater than the
11996 required number of elements, then the actual number of elements copied
11997 to the provided array will be returned in @a countCopied.
11998
11999 <note>
12000 The address of the provided array must be in the process space of
12001 this IFramebuffer object.
12002 </note>
12003 <note>
12004 Method not yet implemented.
12005 </note>
12006 </desc>
12007 <param name="rectangles" type="octet" mod="ptr" dir="in">
12008 <desc>Pointer to the @c RTRECT array to receive region data.</desc>
12009 </param>
12010 <param name="count" type="unsigned long" dir="in">
12011 <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
12012 </param>
12013 <param name="countCopied" type="unsigned long" dir="return">
12014 <desc>Number of elements copied to the @a rectangles array.</desc>
12015 </param>
12016 </method>
12017
12018 <method name="setVisibleRegion">
12019 <desc>
12020 Suggests a new visible region to this frame buffer. This region
12021 represents the area of the VM display which is a union of regions of
12022 all top-level windows of the guest operating system running inside the
12023 VM (if the Guest Additions for this system support this
12024 functionality). This information may be used by the frontends to
12025 implement the seamless desktop integration feature.
12026
12027 <note>
12028 The address of the provided array must be in the process space of
12029 this IFramebuffer object.
12030 </note>
12031 <note>
12032 The IFramebuffer implementation must make a copy of the provided
12033 array of rectangles.
12034 </note>
12035 <note>
12036 Method not yet implemented.
12037 </note>
12038 </desc>
12039 <param name="rectangles" type="octet" mod="ptr" dir="in">
12040 <desc>Pointer to the @c RTRECT array.</desc>
12041 </param>
12042 <param name="count" type="unsigned long" dir="in">
12043 <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
12044 </param>
12045 </method>
12046
12047 <method name="processVHWACommand">
12048 <desc>
12049 Posts a Video HW Acceleration Command to the frame buffer for processing.
12050 The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
12051 are posted from quest to the host to be processed by the host hardware.
12052
12053 <note>
12054 The address of the provided command must be in the process space of
12055 this IFramebuffer object.
12056 </note>
12057 </desc>
12058
12059 <param name="command" type="octet" mod="ptr" dir="in">
12060 <desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
12061 </param>
12062 </method>
12063
12064 </interface>
12065
12066 <interface
12067 name="IFramebufferOverlay" extends="IFramebuffer"
12068 uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
12069 wsmap="suppress"
12070 >
12071 <desc>
12072 The IFramebufferOverlay interface represents an alpha blended overlay
12073 for displaying status icons above an IFramebuffer. It is always created
12074 not visible, so that it must be explicitly shown. It only covers a
12075 portion of the IFramebuffer, determined by its width, height and
12076 co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
12077 that order) format, and may be written to directly. Do re-read the
12078 width though, after setting it, as it may be adjusted (increased) to
12079 make it more suitable for the front end.
12080 </desc>
12081 <attribute name="x" type="unsigned long" readonly="yes">
12082 <desc>X position of the overlay, relative to the frame buffer.</desc>
12083 </attribute>
12084
12085 <attribute name="y" type="unsigned long" readonly="yes">
12086 <desc>Y position of the overlay, relative to the frame buffer.</desc>
12087 </attribute>
12088
12089 <attribute name="visible" type="boolean" readonly="no">
12090 <desc>
12091 Whether the overlay is currently visible.
12092 </desc>
12093 </attribute>
12094
12095 <attribute name="alpha" type="unsigned long" readonly="no">
12096 <desc>
12097 The global alpha value for the overlay. This may or may not be
12098 supported by a given front end.
12099 </desc>
12100 </attribute>
12101
12102 <method name="move">
12103 <desc>
12104 Changes the overlay's position relative to the IFramebuffer.
12105 </desc>
12106 <param name="x" type="unsigned long" dir="in"/>
12107 <param name="y" type="unsigned long" dir="in"/>
12108 </method>
12109
12110 </interface>
12111
12112 <interface
12113 name="IDisplay" extends="$unknown"
12114 uuid="09EED313-CD56-4D06-BD56-FAC0F716B5DD"
12115 wsmap="managed"
12116 >
12117 <desc>
12118 The IDisplay interface represents the virtual machine's display.
12119
12120 The object implementing this interface is contained in each
12121 <link to="IConsole::display"/> attribute and represents the visual
12122 output of the virtual machine.
12123
12124 The virtual display supports pluggable output targets represented by the
12125 IFramebuffer interface. Examples of the output target are a window on
12126 the host computer or an RDP session's display on a remote computer.
12127 </desc>
12128 <method name="getScreenResolution">
12129 <desc>Queries display width, height and color depth for given screen.</desc>
12130 <param name="screenId" type="unsigned long" dir="in"/>
12131 <param name="width" type="unsigned long" dir="out"/>
12132 <param name="height" type="unsigned long" dir="out"/>
12133 <param name="bitsPerPixel" type="unsigned long" dir="out"/>
12134 </method>
12135
12136 <method name="setFramebuffer">
12137 <desc>
12138 Sets the framebuffer for given screen.
12139 </desc>
12140 <param name="screenId" type="unsigned long" dir="in"/>
12141 <param name="framebuffer" type="IFramebuffer" dir="in"/>
12142 </method>
12143
12144 <method name="getFramebuffer">
12145 <desc>
12146 Queries the framebuffer for given screen.
12147 </desc>
12148 <param name="screenId" type="unsigned long" dir="in"/>
12149 <param name="framebuffer" type="IFramebuffer" dir="out"/>
12150 <param name="xOrigin" type="long" dir="out"/>
12151 <param name="yOrigin" type="long" dir="out"/>
12152 </method>
12153
12154 <method name="setVideoModeHint">
12155 <desc>
12156 Asks VirtualBox to request the given video mode from
12157 the guest. This is just a hint and it cannot be guaranteed
12158 that the requested resolution will be used. Guest Additions
12159 are required for the request to be seen by guests. The caller
12160 should issue the request and wait for a resolution change and
12161 after a timeout retry.
12162
12163 Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
12164 parameters means that the corresponding values should be taken from the
12165 current video mode (i.e. left unchanged).
12166
12167 If the guest OS supports multi-monitor configuration then the @a display
12168 parameter specifies the number of the guest display to send the hint to:
12169 @c 0 is the primary display, @c 1 is the first secondary and
12170 so on. If the multi-monitor configuration is not supported, @a display
12171 must be @c 0.
12172
12173 <result name="E_INVALIDARG">
12174 The @a display is not associated with any monitor.
12175 </result>
12176
12177 </desc>
12178 <param name="width" type="unsigned long" dir="in"/>
12179 <param name="height" type="unsigned long" dir="in"/>
12180 <param name="bitsPerPixel" type="unsigned long" dir="in"/>
12181 <param name="display" type="unsigned long" dir="in"/>
12182 </method>
12183
12184 <method name="setSeamlessMode">
12185 <desc>
12186 Enables or disables seamless guest display rendering (seamless desktop
12187 integration) mode.
12188 <note>
12189 Calling this method has no effect if <link
12190 to="IGuest::getFacilityStatus"/> with facility @c Seamless
12191 does not return @c Active.
12192 </note>
12193 </desc>
12194 <param name="enabled" type="boolean" dir="in"/>
12195 </method>
12196
12197 <method name="takeScreenShot">
12198 <desc>
12199 Takes a screen shot of the requested size and copies it to the
12200 32-bpp buffer allocated by the caller and pointed to by @a address.
12201 A pixel consists of 4 bytes in order: B, G, R, 0.
12202
12203 <note>This API can be used only locally by a VM process through the
12204 COM/XPCOM C++ API as it requires pointer support. It is not
12205 available for scripting langages, Java or any webservice clients.
12206 Unless you are writing a new VM frontend use
12207 <link to="#takeScreenShotToArray" />.
12208 </note>
12209
12210 <result name="E_NOTIMPL">
12211 Feature not implemented.
12212 </result>
12213 <result name="VBOX_E_IPRT_ERROR">
12214 Could not take a screenshot.
12215 </result>
12216
12217 </desc>
12218 <param name="screenId" type="unsigned long" dir="in"/>
12219 <param name="address" type="octet" mod="ptr" dir="in"/>
12220 <param name="width" type="unsigned long" dir="in"/>
12221 <param name="height" type="unsigned long" dir="in"/>
12222 </method>
12223
12224 <method name="takeScreenShotToArray">
12225 <desc>
12226 Takes a guest screen shot of the requested size and returns it as
12227 an array of bytes in uncompressed 32-bit RGBA format.
12228 A pixel consists of 4 bytes in order: R, G, B, 0xFF.
12229
12230 This API is slow, but could be the only option to get guest screenshot
12231 for scriptable languages not allowed to manipulate with addresses
12232 directly.
12233
12234 <result name="E_NOTIMPL">
12235 Feature not implemented.
12236 </result>
12237 <result name="VBOX_E_IPRT_ERROR">
12238 Could not take a screenshot.
12239 </result>
12240 </desc>
12241 <param name="screenId" type="unsigned long" dir="in">
12242 <desc>
12243 Monitor to take screenshot from.
12244 </desc>
12245 </param>
12246 <param name="width" type="unsigned long" dir="in">
12247 <desc>
12248 Desired image width.
12249 </desc>
12250 </param>
12251 <param name="height" type="unsigned long" dir="in">
12252 <desc>
12253 Desired image height.
12254 </desc>
12255 </param>
12256 <param name="screenData" type="octet" dir="return" safearray="yes">
12257 <desc>
12258 Array with resulting screen data.
12259 </desc>
12260 </param>
12261 </method>
12262
12263 <method name="takeScreenShotPNGToArray">
12264 <desc>
12265 Takes a guest screen shot of the requested size and returns it as
12266 PNG image in array.
12267
12268 <result name="E_NOTIMPL">
12269 Feature not implemented.
12270 </result>
12271 <result name="VBOX_E_IPRT_ERROR">
12272 Could not take a screenshot.
12273 </result>
12274 </desc>
12275 <param name="screenId" type="unsigned long" dir="in">
12276 <desc>
12277 Monitor to take the screenshot from.
12278 </desc>
12279 </param>
12280 <param name="width" type="unsigned long" dir="in">
12281 <desc>
12282 Desired image width.
12283 </desc>
12284 </param>
12285 <param name="height" type="unsigned long" dir="in">
12286 <desc>
12287 Desired image height.
12288 </desc>
12289 </param>
12290 <param name="screenData" type="octet" dir="return" safearray="yes">
12291 <desc>
12292 Array with resulting screen data.
12293 </desc>
12294 </param>
12295 </method>
12296
12297 <method name="drawToScreen">
12298 <desc>
12299 Draws a 32-bpp image of the specified size from the given buffer
12300 to the given point on the VM display.
12301
12302 <result name="E_NOTIMPL">
12303 Feature not implemented.
12304 </result>
12305 <result name="VBOX_E_IPRT_ERROR">
12306 Could not draw to screen.
12307 </result>
12308
12309 </desc>
12310 <param name="screenId" type="unsigned long" dir="in">
12311 <desc>
12312 Monitor to take the screenshot from.
12313 </desc>
12314 </param>
12315 <param name="address" type="octet" mod="ptr" dir="in">
12316 <desc>
12317 Address to store the screenshot to
12318 </desc>
12319 </param>
12320 <param name="x" type="unsigned long" dir="in">
12321 <desc>
12322 Relative to the screen top left corner.
12323 </desc>
12324 </param>
12325 <param name="y" type="unsigned long" dir="in">
12326 <desc>
12327 Relative to the screen top left corner.
12328 </desc>
12329 </param>
12330 <param name="width" type="unsigned long" dir="in">
12331 <desc>
12332 Desired image width.
12333 </desc>
12334 </param>
12335 <param name="height" type="unsigned long" dir="in">
12336 <desc>
12337 Desired image height.
12338 </desc>
12339 </param>
12340 </method>
12341
12342 <method name="invalidateAndUpdate">
12343 <desc>
12344 Does a full invalidation of the VM display and instructs the VM
12345 to update it.
12346
12347 <result name="VBOX_E_IPRT_ERROR">
12348 Could not invalidate and update screen.
12349 </result>
12350
12351 </desc>
12352 </method>
12353
12354 <method name="resizeCompleted">
12355 <desc>
12356 Signals that a framebuffer has completed the resize operation.
12357
12358 <result name="VBOX_E_NOT_SUPPORTED">
12359 Operation only valid for external frame buffers.
12360 </result>
12361
12362 </desc>
12363 <param name="screenId" type="unsigned long" dir="in"/>
12364 </method>
12365
12366 <method name="completeVHWACommand">
12367 <desc>
12368 Signals that the Video HW Acceleration command has completed.
12369 </desc>
12370
12371 <param name="command" type="octet" mod="ptr" dir="in">
12372 <desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
12373 </param>
12374 </method>
12375
12376 </interface>
12377
12378 <!--
12379 // INetworkAdapter
12380 /////////////////////////////////////////////////////////////////////////
12381 -->
12382
12383 <enum
12384 name="NetworkAttachmentType"
12385 uuid="2ac4bc71-6b82-417a-acd1-f7426d2570d6"
12386 >
12387 <desc>
12388 Network attachment type.
12389 </desc>
12390
12391 <const name="Null" value="0">
12392 <desc>Null value, also means "not attached".</desc>
12393 </const>
12394 <const name="NAT" value="1"/>
12395 <const name="Bridged" value="2"/>
12396 <const name="Internal" value="3"/>
12397 <const name="HostOnly" value="4"/>
12398 <const name="Generic" value="5"/>
12399 </enum>
12400
12401 <enum
12402 name="NetworkAdapterType"
12403 uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
12404 >
12405 <desc>
12406 Network adapter type.
12407 </desc>
12408
12409 <const name="Null" value="0">
12410 <desc>Null value (never used by the API).</desc>
12411 </const>
12412 <const name="Am79C970A" value="1">
12413 <desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
12414 </const>
12415 <const name="Am79C973" value="2">
12416 <desc>AMD PCNet-FAST III network card (Am79C973).</desc>
12417 </const>
12418 <const name="I82540EM" value="3">
12419 <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
12420 </const>
12421 <const name="I82543GC" value="4">
12422 <desc>Intel PRO/1000 T Server network card (82543GC).</desc>
12423 </const>
12424 <const name="I82545EM" value="5">
12425 <desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
12426 </const>
12427 <const name="Virtio" value="6">
12428 <desc>Virtio network device.</desc>
12429 </const>
12430 </enum>
12431
12432 <enum
12433 name="NetworkAdapterPromiscModePolicy"
12434 uuid="c963768a-376f-4c85-8d84-d8ced4b7269e"
12435 >
12436 <desc>
12437 The promiscuous mode policy of an interface.
12438 </desc>
12439
12440 <const name="Deny" value="1">
12441 <desc>Deny promiscuous mode requests.</desc>
12442 </const>
12443 <const name="AllowNetwork" value="2">
12444 <desc>
12445 Allow promicuous mode, but restrict the scope it to the internal
12446 network so that it only applies to other VMs.
12447 </desc>
12448 </const>
12449 <const name="AllowAll" value="3">
12450 <desc>
12451 Allow promicuous mode, include unrelated traffic going over the wire
12452 and internally on the host.
12453 </desc>
12454 </const>
12455 </enum>
12456
12457 <interface
12458 name="INetworkAdapter" extends="$unknown"
12459 uuid="8b2e705c-0547-4008-b7bc-788757346092"
12460 wsmap="managed"
12461 >
12462 <desc>
12463 Represents a virtual network adapter that is attached to a virtual machine.
12464 Each virtual machine has a fixed number of network adapter slots with one
12465 instance of this attached to each of them. Call
12466 <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
12467 is attached to a given slot in a given machine.
12468
12469 Each network adapter can be in one of five attachment modes, which are
12470 represented by the <link to="NetworkAttachmentType" /> enumeration;
12471 see the <link to="#attachmentType" /> attribute.
12472 </desc>
12473
12474 <attribute name="adapterType" type="NetworkAdapterType">
12475 <desc>
12476 Type of the virtual network adapter. Depending on this value,
12477 VirtualBox will provide a different virtual network hardware
12478 to the guest.
12479 </desc>
12480 </attribute>
12481
12482 <attribute name="slot" type="unsigned long" readonly="yes">
12483 <desc>
12484 Slot number this adapter is plugged into. Corresponds to
12485 the value you pass to <link to="IMachine::getNetworkAdapter"/>
12486 to obtain this instance.
12487 </desc>
12488 </attribute>
12489
12490 <attribute name="enabled" type="boolean">
12491 <desc>
12492 Flag whether the network adapter is present in the
12493 guest system. If disabled, the virtual guest hardware will
12494 not contain this network adapter. Can only be changed when
12495 the VM is not running.
12496 </desc>
12497 </attribute>
12498
12499 <attribute name="MACAddress" type="wstring">
12500 <desc>
12501 Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
12502 it to @c null or an empty string, VirtualBox will generate a unique MAC address.
12503 </desc>
12504 </attribute>
12505
12506 <attribute name="attachmentType" type="NetworkAttachmentType">
12507 <desc>
12508 Sets/Gets network attachment type of this network adapter.
12509 </desc>
12510 </attribute>
12511
12512 <attribute name="bridgedInterface" type="wstring">
12513 <desc>
12514 Name of the network interface the VM should be bridged to.
12515 </desc>
12516 </attribute>
12517
12518 <attribute name="hostOnlyInterface" type="wstring">
12519 <desc>
12520 Name of the host only network interface the VM is attached to.
12521 </desc>
12522 </attribute>
12523
12524 <attribute name="internalNetwork" type="wstring">
12525 <desc>
12526 Name of the internal network the VM is attached to.
12527 </desc>
12528 </attribute>
12529
12530 <attribute name="NATNetwork" type="wstring">
12531 <desc>
12532 Name of the NAT network the VM is attached to.
12533 </desc>
12534 </attribute>
12535
12536 <attribute name="genericDriver" type="wstring">
12537 <desc>
12538 Name of the driver to use for the "Generic" network attachment type.
12539 </desc>
12540 </attribute>
12541
12542 <attribute name="cableConnected" type="boolean">
12543 <desc>
12544 Flag whether the adapter reports the cable as connected or not.
12545 It can be used to report offline situations to a VM.
12546 </desc>
12547 </attribute>
12548
12549 <attribute name="lineSpeed" type="unsigned long">
12550 <desc>
12551 Line speed reported by custom drivers, in units of 1 kbps.
12552 </desc>
12553 </attribute>
12554
12555 <attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy">
12556 <desc>
12557 The promiscuous mode policy of the network adapter when attached to an
12558 internal network, host only network or a bridge.
12559 </desc>
12560 </attribute>
12561
12562 <attribute name="traceEnabled" type="boolean">
12563 <desc>
12564 Flag whether network traffic from/to the network card should be traced.
12565 Can only be toggled when the VM is turned off.
12566 </desc>
12567 </attribute>
12568
12569 <attribute name="traceFile" type="wstring">
12570 <desc>
12571 Filename where a network trace will be stored. If not set, VBox-pid.pcap
12572 will be used.
12573 </desc>
12574 </attribute>
12575
12576 <attribute name="natDriver" type="INATEngine" readonly="yes">
12577 <desc>
12578 Points to the NAT engine which handles the network address translation
12579 for this interface. This is active only when the interface actually uses
12580 NAT.
12581 </desc>
12582 </attribute>
12583
12584 <attribute name="bootPriority" type="unsigned long">
12585 <desc>
12586 Network boot priority of the adapter. Priority 1 is highest. If not set,
12587 the priority is considered to be at the lowest possible setting.
12588 </desc>
12589 </attribute>
12590
12591 <attribute name="bandwidthGroup" type="IBandwidthGroup">
12592 <desc>The bandwidth group this network adapter is assigned to.</desc>
12593 </attribute>
12594
12595 <!-- property methods -->
12596
12597 <method name="getProperty" const="yes">
12598 <desc>
12599 Returns the value of the network attachment property with the given name.
12600
12601 If the requested data @a key does not exist, this function will
12602 succeed and return an empty string in the @a value argument.
12603
12604 <result name="E_INVALIDARG">@a name is @c null or empty.</result>
12605 </desc>
12606 <param name="key" type="wstring" dir="in">
12607 <desc>Name of the property to get.</desc>
12608 </param>
12609 <param name="value" type="wstring" dir="return">
12610 <desc>Current property value.</desc>
12611 </param>
12612 </method>
12613
12614 <method name="setProperty">
12615 <desc>
12616 Sets the value of the network attachment property with the given name.
12617
12618 Setting the property value to @c null or an empty string is equivalent
12619 to deleting the existing value.
12620
12621 <result name="E_INVALIDARG">@a name is @c null or empty.</result>
12622 </desc>
12623 <param name="key" type="wstring" dir="in">
12624 <desc>Name of the property to set.</desc>
12625 </param>
12626 <param name="value" type="wstring" dir="in">
12627 <desc>Property value to set.</desc>
12628 </param>
12629 </method>
12630
12631 <method name="getProperties" const="yes">
12632 <desc>
12633 Returns values for a group of properties in one call.
12634
12635 The names of the properties to get are specified using the @a names
12636 argument which is a list of comma-separated property names or
12637 an empty string if all properties are to be returned.
12638 <note>Currently the value of this argument is ignored and the method
12639 always returns all existing properties.</note>
12640
12641 The method returns two arrays, the array of property names corresponding
12642 to the @a names argument and the current values of these properties.
12643 Both arrays have the same number of elements with each element at the
12644 given index in the first array corresponds to an element at the same
12645 index in the second array.
12646 </desc>
12647 <param name="names" type="wstring" dir="in">
12648 <desc>
12649 Names of properties to get.
12650 </desc>
12651 </param>
12652 <param name="returnNames" type="wstring" safearray="yes" dir="out">
12653 <desc>Names of returned properties.</desc>
12654 </param>
12655 <param name="returnValues" type="wstring" safearray="yes" dir="return">
12656 <desc>Values of returned properties.</desc>
12657 </param>
12658 </method>
12659
12660 </interface>
12661
12662
12663 <!--
12664 // ISerialPort
12665 /////////////////////////////////////////////////////////////////////////
12666 -->
12667
12668 <enum
12669 name="PortMode"
12670 uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
12671 >
12672 <desc>
12673 The PortMode enumeration represents possible communication modes for
12674 the virtual serial port device.
12675 </desc>
12676
12677 <const name="Disconnected" value="0">
12678 <desc>Virtual device is not attached to any real host device.</desc>
12679 </const>
12680 <const name="HostPipe" value="1">
12681 <desc>Virtual device is attached to a host pipe.</desc>
12682 </const>
12683 <const name="HostDevice" value="2">
12684 <desc>Virtual device is attached to a host device.</desc>
12685 </const>
12686 <const name="RawFile" value="3">
12687 <desc>Virtual device is attached to a raw file.</desc>
12688 </const>
12689 </enum>
12690
12691 <interface
12692 name="ISerialPort" extends="$unknown"
12693 uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
12694 wsmap="managed"
12695 >
12696
12697 <desc>
12698 The ISerialPort interface represents the virtual serial port device.
12699
12700 The virtual serial port device acts like an ordinary serial port
12701 inside the virtual machine. This device communicates to the real
12702 serial port hardware in one of two modes: host pipe or host device.
12703
12704 In host pipe mode, the #path attribute specifies the path to the pipe on
12705 the host computer that represents a serial port. The #server attribute
12706 determines if this pipe is created by the virtual machine process at
12707 machine startup or it must already exist before starting machine
12708 execution.
12709
12710 In host device mode, the #path attribute specifies the name of the
12711 serial port device on the host computer.
12712
12713 There is also a third communication mode: the disconnected mode. In this
12714 mode, the guest OS running inside the virtual machine will be able to
12715 detect the serial port, but all port write operations will be discarded
12716 and all port read operations will return no data.
12717
12718 <see><link to="IMachine::getSerialPort"/></see>
12719 </desc>
12720
12721 <attribute name="slot" type="unsigned long" readonly="yes">
12722 <desc>
12723 Slot number this serial port is plugged into. Corresponds to
12724 the value you pass to <link to="IMachine::getSerialPort"/>
12725 to obtain this instance.
12726 </desc>
12727 </attribute>
12728
12729 <attribute name="enabled" type="boolean">
12730 <desc>
12731 Flag whether the serial port is enabled. If disabled,
12732 the serial port will not be reported to the guest OS.
12733 </desc>
12734 </attribute>
12735
12736 <attribute name="IOBase" type="unsigned long">
12737 <desc>Base I/O address of the serial port.</desc>
12738 </attribute>
12739
12740 <attribute name="IRQ" type="unsigned long">
12741 <desc>IRQ number of the serial port.</desc>
12742 </attribute>
12743
12744 <attribute name="hostMode" type="PortMode">
12745 <desc>
12746 How is this port connected to the host.
12747 <note>
12748 Changing this attribute may fail if the conditions for
12749 <link to="#path"/> are not met.
12750 </note>
12751 </desc>
12752 </attribute>
12753
12754 <attribute name="server" type="boolean">
12755 <desc>
12756 Flag whether this serial port acts as a server (creates a new pipe on
12757 the host) or as a client (uses the existing pipe). This attribute is
12758 used only when <link to="#hostMode"/> is PortMode_HostPipe.
12759 </desc>
12760 </attribute>
12761
12762 <attribute name="path" type="wstring">
12763 <desc>
12764 Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
12765 PortMode_HostPipe, or the host serial device name when
12766 <link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
12767 cases, setting a @c null or empty string as the attribute's value
12768 is an error. Otherwise, the value of this property is ignored.
12769 </desc>
12770 </attribute>
12771
12772 </interface>
12773
12774 <!--
12775 // IParallelPort
12776 /////////////////////////////////////////////////////////////////////////
12777 -->
12778
12779 <interface
12780 name="IParallelPort" extends="$unknown"
12781 uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
12782 wsmap="managed"
12783 >
12784
12785 <desc>
12786 The IParallelPort interface represents the virtual parallel port device.
12787
12788 The virtual parallel port device acts like an ordinary parallel port
12789 inside the virtual machine. This device communicates to the real
12790 parallel port hardware using the name of the parallel device on the host
12791 computer specified in the #path attribute.
12792
12793 Each virtual parallel port device is assigned a base I/O address and an
12794 IRQ number that will be reported to the guest operating system and used
12795 to operate the given parallel port from within the virtual machine.
12796
12797 <see><link to="IMachine::getParallelPort"/></see>
12798 </desc>
12799
12800 <attribute name="slot" type="unsigned long" readonly="yes">
12801 <desc>
12802 Slot number this parallel port is plugged into. Corresponds to
12803 the value you pass to <link to="IMachine::getParallelPort"/>
12804 to obtain this instance.
12805 </desc>
12806 </attribute>
12807
12808 <attribute name="enabled" type="boolean">
12809 <desc>
12810 Flag whether the parallel port is enabled. If disabled,
12811 the parallel port will not be reported to the guest OS.
12812 </desc>
12813 </attribute>
12814
12815 <attribute name="IOBase" type="unsigned long">
12816 <desc>Base I/O address of the parallel port.</desc>
12817 </attribute>
12818
12819 <attribute name="IRQ" type="unsigned long">
12820 <desc>IRQ number of the parallel port.</desc>
12821 </attribute>
12822
12823 <attribute name="path" type="wstring">
12824 <desc>
12825 Host parallel device name. If this parallel port is enabled, setting a
12826 @c null or an empty string as this attribute's value will result in
12827 an error.
12828 </desc>
12829 </attribute>
12830
12831 </interface>
12832
12833
12834 <!--
12835 // IMachineDebugger
12836 /////////////////////////////////////////////////////////////////////////
12837 -->
12838
12839 <interface
12840 name="IMachineDebugger" extends="$unknown"
12841 uuid="1bfd2fa9-0d91-44d3-9515-368dcbb3eb4d"
12842 wsmap="suppress"
12843 >
12844 <method name="dumpGuestCore">
12845 <desc>
12846 Takes a core dump of the guest.
12847
12848 See include/VBox/dbgfcorefmt.h for details on the file format.
12849 </desc>
12850 <param name="filename" type="wstring" dir="in">
12851 <desc>
12852 The name of the output file. The file must not exist.
12853 </desc>
12854 </param>
12855 <param name="compression" type="wstring" dir="in">
12856 <desc>
12857 Reserved for future compression method indicator.
12858 </desc>
12859 </param>
12860 </method>
12861
12862 <method name="dumpHostProcessCore">
12863 <desc>
12864 Takes a core dump of the VM process on the host.
12865
12866 This feature is not implemented in the 4.0.0 release but it may show up
12867 in a dot release.
12868 </desc>
12869 <param name="filename" type="wstring" dir="in">
12870 <desc>
12871 The name of the output file. The file must not exist.
12872 </desc>
12873 </param>
12874 <param name="compression" type="wstring" dir="in">
12875 <desc>
12876 Reserved for future compression method indicator.
12877 </desc>
12878 </param>
12879 </method>
12880
12881 <method name="info">
12882 <desc>
12883 Interfaces with the info dumpers (DBGFInfo).
12884
12885 This feature is not implemented in the 4.0.0 release but it may show up
12886 in a dot release.
12887 </desc>
12888 <param name="name" type="wstring" dir="in">
12889 <desc>
12890 The name of the info item.
12891 </desc>
12892 </param>
12893 <param name="args" type="wstring" dir="in">
12894 <desc>
12895 Arguments to the info dumper.
12896 </desc>
12897 </param>
12898 <param name="info" type="wstring" dir="return">
12899 <desc>
12900 The into string.
12901 </desc>
12902 </param>
12903 </method>
12904
12905 <method name="injectNMI">
12906 <desc>
12907 Inject an NMI into a running VT-x/AMD-V VM.
12908 </desc>
12909 </method>
12910
12911 <method name="modifyLogGroups">
12912 <desc>
12913 Modifies the group settings of the debug logger.
12914
12915 This feature is not implemented in the 4.0.0 release but may show up
12916 in a dot release.
12917 </desc>
12918 <param name="settings" type="wstring" dir="in">
12919 <desc>The group settings string. See iprt/log.h for details.</desc>
12920 </param>
12921 </method>
12922
12923 <method name="modifyLogFlags">
12924 <desc>
12925 Modifies the debug logger flags.
12926
12927 This feature is not implemented in the 4.0.0 release but may show up
12928 in a dot release.
12929 </desc>
12930 <param name="settings" type="wstring" dir="in">
12931 <desc>The flags settings string. See iprt/log.h for details.</desc>
12932 </param>
12933 </method>
12934
12935 <method name="modifyLogDestinations">
12936 <desc>
12937 Modifies the debug logger destinations.
12938
12939 This feature is not implemented in the 4.0.0 release but may show up
12940 in a dot release.
12941 </desc>
12942 <param name="settings" type="wstring" dir="in">
12943 <desc>The destination settings string. See iprt/log.h for details.</desc>
12944 </param>
12945 </method>
12946
12947 <method name="readPhysicalMemory">
12948 <desc>
12949 Reads guest physical memory, no side effects (MMIO++).
12950
12951 This feature is not implemented in the 4.0.0 release but may show up
12952 in a dot release.
12953 </desc>
12954 <param name="address" type="long long" dir="in">
12955 <desc>The guest physical address.</desc>
12956 </param>
12957 <param name="size" type="unsigned long" dir="in">
12958 <desc>The number of bytes to read.</desc>
12959 </param>
12960 <param name="bytes" type="octet" safearray="yes" dir="return">
12961 <desc>The bytes read.</desc>
12962 </param>
12963 </method>
12964
12965 <method name="writePhysicalMemory">
12966 <desc>
12967 Writes guest physical memory, access handles (MMIO++) are ignored.
12968
12969 This feature is not implemented in the 4.0.0 release but may show up
12970 in a dot release.
12971 </desc>
12972 <param name="address" type="long long" dir="in">
12973 <desc>The guest physical address.</desc>
12974 </param>
12975 <param name="size" type="unsigned long" dir="in">
12976 <desc>The number of bytes to read.</desc>
12977 </param>
12978 <param name="bytes" type="octet" safearray="yes" dir="in">
12979 <desc>The bytes to write.</desc>
12980 </param>
12981 </method>
12982
12983 <method name="readVirtualMemory">
12984 <desc>
12985 Reads guest virtual memory, no side effects (MMIO++).
12986
12987 This feature is not implemented in the 4.0.0 release but may show up
12988 in a dot release.
12989 </desc>
12990 <param name="cpuId" type="unsigned long" dir="in">
12991 <desc>The identifier of the Virtual CPU.</desc>
12992 </param>
12993 <param name="address" type="long long" dir="in">
12994 <desc>The guest virtual address.</desc>
12995 </param>
12996 <param name="size" type="unsigned long" dir="in">
12997 <desc>The number of bytes to read.</desc>
12998 </param>
12999 <param name="bytes" type="octet" safearray="yes" dir="return">
13000 <desc>The bytes read.</desc>
13001 </param>
13002 </method>
13003
13004 <method name="writeVirtualMemory">
13005 <desc>
13006 Writes guest virtual memory, access handles (MMIO++) are ignored.
13007
13008 This feature is not implemented in the 4.0.0 release but may show up
13009 in a dot release.
13010 </desc>
13011 <param name="cpuId" type="unsigned long" dir="in">
13012 <desc>The identifier of the Virtual CPU.</desc>
13013 </param>
13014 <param name="address" type="long long" dir="in">
13015 <desc>The guest virtual address.</desc>
13016 </param>
13017 <param name="size" type="unsigned long" dir="in">
13018 <desc>The number of bytes to read.</desc>
13019 </param>
13020 <param name="bytes" type="octet" safearray="yes" dir="in">
13021 <desc>The bytes to write.</desc>
13022 </param>
13023 </method>
13024
13025 <method name="detectOS">
13026 <desc>
13027 Tries to (re-)detect the guest OS kernel.
13028
13029 This feature is not implemented in the 4.0.0 release but may show up
13030 in a dot release.
13031 </desc>
13032 <param name="os" type="wstring" dir="return">
13033 <desc>
13034 The detected OS kernel on success.
13035 </desc>
13036 </param>
13037 </method>
13038
13039 <method name="getRegister">
13040 <desc>
13041 Gets one register.
13042
13043 This feature is not implemented in the 4.0.0 release but may show up
13044 in a dot release.
13045 </desc>
13046 <param name="cpuId" type="unsigned long" dir="in">
13047 <desc>The identifier of the Virtual CPU.</desc>
13048 </param>
13049 <param name="name" type="wstring" dir="in">
13050 <desc>The register name, case is ignored.</desc>
13051 </param>
13052 <param name="value" type="wstring" dir="return">
13053 <desc>
13054 The register value. This is usually a hex value (always 0x prefixed)
13055 but other format may be used for floating point registers (TBD).
13056 </desc>
13057 </param>
13058 </method>
13059
13060 <method name="getRegisters">
13061 <desc>
13062 Gets all the registers for the given CPU.
13063
13064 This feature is not implemented in the 4.0.0 release but may show up
13065 in a dot release.
13066 </desc>
13067 <param name="cpuId" type="unsigned long" dir="in">
13068 <desc>The identifier of the Virtual CPU.</desc>
13069 </param>
13070 <param name="names" type="wstring" dir="out" safearray="yes">
13071 <desc>Array containing the lowercase register names.</desc>
13072 </param>
13073 <param name="values" type="wstring" dir="out" safearray="yes">
13074 <desc>
13075 Array paralell to the names holding the register values as if the
13076 register was returned by <link to="IMachineDebugger::getRegister"/>.
13077 </desc>
13078 </param>
13079 </method>
13080
13081 <method name="setRegister">
13082 <desc>
13083 Gets one register.
13084
13085 This feature is not implemented in the 4.0.0 release but may show up
13086 in a dot release.
13087 </desc>
13088 <param name="cpuId" type="unsigned long" dir="in">
13089 <desc>The identifier of the Virtual CPU.</desc>
13090 </param>
13091 <param name="name" type="wstring" dir="in">
13092 <desc>The register name, case is ignored.</desc>
13093 </param>
13094 <param name="value" type="wstring" dir="in">
13095 <desc>
13096 The new register value. Hexadecimal, decimal and octal formattings
13097 are supported in addition to any special formattings returned by
13098 the getters.
13099 </desc>
13100 </param>
13101 </method>
13102
13103 <method name="setRegisters">
13104 <desc>
13105 Sets zero or more registers atomically.
13106
13107 This feature is not implemented in the 4.0.0 release but may show up
13108 in a dot release.
13109 </desc>
13110 <param name="cpuId" type="unsigned long" dir="in">
13111 <desc>The identifier of the Virtual CPU.</desc>
13112 </param>
13113 <param name="names" type="wstring" dir="in" safearray="yes">
13114 <desc>Array containing the register names, case ignored.</desc>
13115 </param>
13116 <param name="values" type="wstring" dir="in" safearray="yes">
13117 <desc>
13118 Array paralell to the names holding the register values. See
13119 <link to="IMachineDebugger::setRegister"/> for formatting
13120 guidelines.
13121 </desc>
13122 </param>
13123 </method>
13124
13125 <method name="dumpGuestStack">
13126 <desc>
13127 Produce a simple stack dump using the current guest state.
13128
13129 This feature is not implemented in the 4.0.0 release but may show up
13130 in a dot release.
13131 </desc>
13132 <param name="cpuId" type="unsigned long" dir="in">
13133 <desc>The identifier of the Virtual CPU.</desc>
13134 </param>
13135 <param name="stack" type="wstring" dir="return">
13136 <desc>String containing the formatted stack dump.</desc>
13137 </param>
13138 </method>
13139
13140 <method name="resetStats">
13141 <desc>
13142 Reset VM statistics.
13143 </desc>
13144 <param name="pattern" type="wstring" dir="in">
13145 <desc>The selection pattern. A bit similar to filename globbing.</desc>
13146 </param>
13147 </method>
13148
13149 <method name="dumpStats">
13150 <desc>
13151 Dumps VM statistics.
13152 </desc>
13153 <param name="pattern" type="wstring" dir="in">
13154 <desc>The selection pattern. A bit similar to filename globbing.</desc>
13155 </param>
13156 </method>
13157
13158 <method name="getStats">
13159 <desc>
13160 Get the VM statistics in a XMLish format.
13161 </desc>
13162 <param name="pattern" type="wstring" dir="in">
13163 <desc>The selection pattern. A bit similar to filename globbing.</desc>
13164 </param>
13165 <param name="withDescriptions" type="boolean" dir="in">
13166 <desc>Whether to include the descriptions.</desc>
13167 </param>
13168 <param name="stats" type="wstring" dir="out">
13169 <desc>The XML document containing the statistics.</desc>
13170 </param>
13171 </method>
13172
13173 <attribute name="singlestep" type="boolean">
13174 <desc>Switch for enabling singlestepping.</desc>
13175 </attribute>
13176
13177 <attribute name="recompileUser" type="boolean">
13178 <desc>Switch for forcing code recompilation for user mode code.</desc>
13179 </attribute>
13180
13181 <attribute name="recompileSupervisor" type="boolean">
13182 <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
13183 </attribute>
13184
13185 <attribute name="PATMEnabled" type="boolean">
13186 <desc>Switch for enabling and disabling the PATM component.</desc>
13187 </attribute>
13188
13189 <attribute name="CSAMEnabled" type="boolean">
13190 <desc>Switch for enabling and disabling the CSAM component.</desc>
13191 </attribute>
13192
13193 <attribute name="logEnabled" type="boolean">
13194 <desc>Switch for enabling and disabling the debug logger.</desc>
13195 </attribute>
13196
13197 <attribute name="logFlags" type="wstring" readonly="yes">
13198 <desc>The debug logger flags.</desc>
13199 </attribute>
13200
13201 <attribute name="logGroups" type="wstring" readonly="yes">
13202 <desc>The debug logger's group settings.</desc>
13203 </attribute>
13204
13205 <attribute name="logDestinations" type="wstring" readonly="yes">
13206 <desc>The debug logger's destination settings.</desc>
13207 </attribute>
13208
13209 <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
13210 <desc>
13211 Flag indicating whether the VM is currently making use of CPU hardware
13212 virtualization extensions.
13213 </desc>
13214 </attribute>
13215
13216 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
13217 <desc>
13218 Flag indicating whether the VM is currently making use of the nested paging
13219 CPU hardware virtualization extension.
13220 </desc>
13221 </attribute>
13222
13223 <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
13224 <desc>
13225 Flag indicating whether the VM is currently making use of the VPID
13226 VT-x extension.
13227 </desc>
13228 </attribute>
13229
13230 <attribute name="OSName" type="wstring" readonly="yes">
13231 <desc>
13232 Query the guest OS kernel name as detected by the DBGF.
13233
13234 This feature is not implemented in the 4.0.0 release but may show up
13235 in a dot release.
13236 </desc>
13237 </attribute>
13238
13239 <attribute name="OSVersion" type="wstring" readonly="yes">
13240 <desc>
13241 Query the guest OS kernel version string as detected by the DBGF.
13242
13243 This feature is not implemented in the 4.0.0 release but may show up
13244 in a dot release.
13245 </desc>
13246 </attribute>
13247
13248 <attribute name="PAEEnabled" type="boolean" readonly="yes">
13249 <desc>
13250 Flag indicating whether the VM is currently making use of the Physical
13251 Address Extension CPU feature.
13252 </desc>
13253 </attribute>
13254
13255 <attribute name="virtualTimeRate" type="unsigned long">
13256 <desc>
13257 The rate at which the virtual time runs expressed as a percentage.
13258 The accepted range is 2% to 20000%.
13259 </desc>
13260 </attribute>
13261
13262 <attribute name="VM" type="long long" readonly="yes">
13263 <desc>
13264 Gets the VM handle. This is only for internal use while
13265 we carve the details of this interface.
13266 </desc>
13267 </attribute>
13268
13269 </interface>
13270
13271 <!--
13272 // IUSBController
13273 /////////////////////////////////////////////////////////////////////////
13274 -->
13275
13276 <interface
13277 name="IUSBController" extends="$unknown"
13278 uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
13279 wsmap="managed"
13280 >
13281 <attribute name="enabled" type="boolean">
13282 <desc>
13283 Flag whether the USB controller is present in the
13284 guest system. If disabled, the virtual guest hardware will
13285 not contain any USB controller. Can only be changed when
13286 the VM is powered off.
13287 </desc>
13288 </attribute>
13289
13290 <attribute name="enabledEhci" type="boolean">
13291 <desc>
13292 Flag whether the USB EHCI controller is present in the
13293 guest system. If disabled, the virtual guest hardware will
13294 not contain a USB EHCI controller. Can only be changed when
13295 the VM is powered off.
13296 </desc>
13297 </attribute>
13298
13299 <attribute name="proxyAvailable" type="boolean" readonly="yes">
13300 <desc>
13301 Flag whether there is an USB proxy available.
13302 </desc>
13303 </attribute>
13304
13305 <attribute name="USBStandard" type="unsigned short" readonly="yes">
13306 <desc>
13307 USB standard version which the controller implements.
13308 This is a BCD which means that the major version is in the
13309 high byte and minor version is in the low byte.
13310 </desc>
13311 </attribute>
13312
13313 <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
13314 <desc>
13315 List of USB device filters associated with the machine.
13316
13317 If the machine is currently running, these filters are activated
13318 every time a new (supported) USB device is attached to the host
13319 computer that was not ignored by global filters
13320 (<link to="IHost::USBDeviceFilters"/>).
13321
13322 These filters are also activated when the machine is powered up.
13323 They are run against a list of all currently available USB
13324 devices (in states
13325 <link to="USBDeviceState_Available"/>,
13326 <link to="USBDeviceState_Busy"/>,
13327 <link to="USBDeviceState_Held"/>) that were not previously
13328 ignored by global filters.
13329
13330 If at least one filter matches the USB device in question, this
13331 device is automatically captured (attached to) the virtual USB
13332 controller of this machine.
13333
13334 <see><link to="IUSBDeviceFilter"/>, <link to="IUSBController"/></see>
13335 </desc>
13336 </attribute>
13337
13338 <method name="createDeviceFilter">
13339 <desc>
13340 Creates a new USB device filter. All attributes except
13341 the filter name are set to empty (any match),
13342 <i>active</i> is @c false (the filter is not active).
13343
13344 The created filter can then be added to the list of filters using
13345 <link to="#insertDeviceFilter"/>.
13346
13347 <result name="VBOX_E_INVALID_VM_STATE">
13348 The virtual machine is not mutable.
13349 </result>
13350
13351 <see><link to="#deviceFilters"/></see>
13352 </desc>
13353 <param name="name" type="wstring" dir="in">
13354 <desc>
13355 Filter name. See <link to="IUSBDeviceFilter::name"/>
13356 for more info.
13357 </desc>
13358 </param>
13359 <param name="filter" type="IUSBDeviceFilter" dir="return">
13360 <desc>Created filter object.</desc>
13361 </param>
13362 </method>
13363
13364 <method name="insertDeviceFilter">
13365 <desc>
13366 Inserts the given USB device to the specified position
13367 in the list of filters.
13368
13369 Positions are numbered starting from <tt>0</tt>. If the specified
13370 position is equal to or greater than the number of elements in
13371 the list, the filter is added to the end of the collection.
13372
13373 <note>
13374 Duplicates are not allowed, so an attempt to insert a
13375 filter that is already in the collection, will return an
13376 error.
13377 </note>
13378
13379 <result name="VBOX_E_INVALID_VM_STATE">
13380 Virtual machine is not mutable.
13381 </result>
13382 <result name="E_INVALIDARG">
13383 USB device filter not created within this VirtualBox instance.
13384 </result>
13385 <result name="VBOX_E_INVALID_OBJECT_STATE">
13386 USB device filter already in list.
13387 </result>
13388
13389 <see><link to="#deviceFilters"/></see>
13390 </desc>
13391 <param name="position" type="unsigned long" dir="in">
13392 <desc>Position to insert the filter to.</desc>
13393 </param>
13394 <param name="filter" type="IUSBDeviceFilter" dir="in">
13395 <desc>USB device filter to insert.</desc>
13396 </param>
13397 </method>
13398
13399 <method name="removeDeviceFilter">
13400 <desc>
13401 Removes a USB device filter from the specified position in the
13402 list of filters.
13403
13404 Positions are numbered starting from <tt>0</tt>. Specifying a
13405 position equal to or greater than the number of elements in
13406 the list will produce an error.
13407
13408 <see><link to="#deviceFilters"/></see>
13409
13410 <result name="VBOX_E_INVALID_VM_STATE">
13411 Virtual machine is not mutable.
13412 </result>
13413 <result name="E_INVALIDARG">
13414 USB device filter list empty or invalid @a position.
13415 </result>
13416
13417 </desc>
13418 <param name="position" type="unsigned long" dir="in">
13419 <desc>Position to remove the filter from.</desc>
13420 </param>
13421 <param name="filter" type="IUSBDeviceFilter" dir="return">
13422 <desc>Removed USB device filter.</desc>
13423 </param>
13424 </method>
13425
13426 </interface>
13427
13428
13429 <!--
13430 // IUSBDevice
13431 /////////////////////////////////////////////////////////////////////////
13432 -->
13433
13434 <interface
13435 name="IUSBDevice" extends="$unknown"
13436 uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
13437 wsmap="managed"
13438 >
13439 <desc>
13440 The IUSBDevice interface represents a virtual USB device attached to the
13441 virtual machine.
13442
13443 A collection of objects implementing this interface is stored in the
13444 <link to="IConsole::USBDevices"/> attribute which lists all USB devices
13445 attached to a running virtual machine's USB controller.
13446 </desc>
13447
13448 <attribute name="id" type="uuid" mod="string" readonly="yes">
13449 <desc>
13450 Unique USB device ID. This ID is built from #vendorId,
13451 #productId, #revision and #serialNumber.
13452 </desc>
13453 </attribute>
13454
13455 <attribute name="vendorId" type="unsigned short" readonly="yes">
13456 <desc>Vendor ID.</desc>
13457 </attribute>
13458
13459 <attribute name="productId" type="unsigned short" readonly="yes">
13460 <desc>Product ID.</desc>
13461 </attribute>
13462
13463 <attribute name="revision" type="unsigned short" readonly="yes">
13464 <desc>
13465 Product revision number. This is a packed BCD represented as
13466 unsigned short. The high byte is the integer part and the low
13467 byte is the decimal.
13468 </desc>
13469 </attribute>
13470
13471 <attribute name="manufacturer" type="wstring" readonly="yes">
13472 <desc>Manufacturer string.</desc>
13473 </attribute>
13474
13475 <attribute name="product" type="wstring" readonly="yes">
13476 <desc>Product string.</desc>
13477 </attribute>
13478
13479 <attribute name="serialNumber" type="wstring" readonly="yes">
13480 <desc>Serial number string.</desc>
13481 </attribute>
13482
13483 <attribute name="address" type="wstring" readonly="yes">
13484 <desc>Host specific address of the device.</desc>
13485 </attribute>
13486
13487 <attribute name="port" type="unsigned short" readonly="yes">
13488 <desc>
13489 Host USB port number the device is physically
13490 connected to.
13491 </desc>
13492 </attribute>
13493
13494 <attribute name="version" type="unsigned short" readonly="yes">
13495 <desc>
13496 The major USB version of the device - 1 or 2.
13497 </desc>
13498 </attribute>
13499
13500 <attribute name="portVersion" type="unsigned short" readonly="yes">
13501 <desc>
13502 The major USB version of the host USB port the device is
13503 physically connected to - 1 or 2. For devices not connected to
13504 anything this will have the same value as the version attribute.
13505 </desc>
13506 </attribute>
13507
13508 <attribute name="remote" type="boolean" readonly="yes">
13509 <desc>
13510 Whether the device is physically connected to a remote VRDE
13511 client or to a local host machine.
13512 </desc>
13513 </attribute>
13514
13515 </interface>
13516
13517
13518 <!--
13519 // IUSBDeviceFilter
13520 /////////////////////////////////////////////////////////////////////////
13521 -->
13522
13523 <interface
13524 name="IUSBDeviceFilter" extends="$unknown"
13525 uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
13526 wsmap="managed"
13527 >
13528 <desc>
13529 The IUSBDeviceFilter interface represents an USB device filter used
13530 to perform actions on a group of USB devices.
13531
13532 This type of filters is used by running virtual machines to
13533 automatically capture selected USB devices once they are physically
13534 attached to the host computer.
13535
13536 A USB device is matched to the given device filter if and only if all
13537 attributes of the device match the corresponding attributes of the
13538 filter (that is, attributes are joined together using the logical AND
13539 operation). On the other hand, all together, filters in the list of
13540 filters carry the semantics of the logical OR operation. So if it is
13541 desirable to create a match like "this vendor id OR this product id",
13542 one needs to create two filters and specify "any match" (see below)
13543 for unused attributes.
13544
13545 All filter attributes used for matching are strings. Each string
13546 is an expression representing a set of values of the corresponding
13547 device attribute, that will match the given filter. Currently, the
13548 following filtering expressions are supported:
13549
13550 <ul>
13551 <li><i>Interval filters</i>. Used to specify valid intervals for
13552 integer device attributes (Vendor ID, Product ID and Revision).
13553 The format of the string is:
13554
13555 <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
13556
13557 where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
13558 (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
13559 or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
13560 is omitted before a dash (<tt>-</tt>), the minimum possible integer
13561 is assumed; if <tt>n</tt> is omitted after a dash, the maximum
13562 possible integer is assumed.
13563 </li>
13564 <li><i>Boolean filters</i>. Used to specify acceptable values for
13565 boolean device attributes. The format of the string is:
13566
13567 <tt>true|false|yes|no|0|1</tt>
13568
13569 </li>
13570 <li><i>Exact match</i>. Used to specify a single value for the given
13571 device attribute. Any string that doesn't start with <tt>int:</tt>
13572 represents the exact match. String device attributes are compared to
13573 this string including case of symbols. Integer attributes are first
13574 converted to a string (see individual filter attributes) and then
13575 compared ignoring case.
13576
13577 </li>
13578 <li><i>Any match</i>. Any value of the corresponding device attribute
13579 will match the given filter. An empty or @c null string is
13580 used to construct this type of filtering expressions.
13581
13582 </li>
13583 </ul>
13584
13585 <note>
13586 On the Windows host platform, interval filters are not currently
13587 available. Also all string filter attributes
13588 (<link to="#manufacturer"/>, <link to="#product"/>,
13589 <link to="#serialNumber"/>) are ignored, so they behave as
13590 <i>any match</i> no matter what string expression is specified.
13591 </note>
13592
13593 <see><link to="IUSBController::deviceFilters"/>,
13594 <link to="IHostUSBDeviceFilter"/></see>
13595 </desc>
13596
13597 <attribute name="name" type="wstring">
13598 <desc>
13599 Visible name for this filter.
13600 This name is used to visually distinguish one filter from another,
13601 so it can neither be @c null nor an empty string.
13602 </desc>
13603 </attribute>
13604
13605 <attribute name="active" type="boolean">
13606 <desc>Whether this filter active or has been temporarily disabled.</desc>
13607 </attribute>
13608
13609 <attribute name="vendorId" type="wstring">
13610 <desc>
13611 <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
13612 The string representation for the <i>exact matching</i>
13613 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
13614 (including leading zeroes).
13615 </desc>
13616 </attribute>
13617
13618 <attribute name="productId" type="wstring">
13619 <desc>
13620 <link to="IUSBDevice::productId">Product ID</link> filter.
13621 The string representation for the <i>exact matching</i>
13622 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
13623 (including leading zeroes).
13624 </desc>
13625 </attribute>
13626
13627 <attribute name="revision" type="wstring">
13628 <desc>
13629 <link to="IUSBDevice::productId">Product revision number</link>
13630 filter. The string representation for the <i>exact matching</i>
13631 has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
13632 of the integer part of the revision, and <tt>F</tt> is the
13633 decimal digit of its fractional part (including leading and
13634 trailing zeros).
13635 Note that for interval filters, it's best to use the hexadecimal
13636 form, because the revision is stored as a 16 bit packed BCD value;
13637 so the expression <tt>int:0x0100-0x0199</tt> will match any
13638 revision from <tt>1.0</tt> to <tt>1.99</tt>.
13639 </desc>
13640 </attribute>
13641
13642 <attribute name="manufacturer" type="wstring">
13643 <desc>
13644 <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
13645 </desc>
13646 </attribute>
13647
13648 <attribute name="product" type="wstring">
13649 <desc>
13650 <link to="IUSBDevice::product">Product</link> filter.
13651 </desc>
13652 </attribute>
13653
13654 <attribute name="serialNumber" type="wstring">
13655 <desc>
13656 <link to="IUSBDevice::serialNumber">Serial number</link> filter.
13657 </desc>
13658 </attribute>
13659
13660 <attribute name="port" type="wstring">
13661 <desc>
13662 <link to="IUSBDevice::port">Host USB port</link> filter.
13663 </desc>
13664 </attribute>
13665
13666 <attribute name="remote" type="wstring">
13667 <desc>
13668 <link to="IUSBDevice::remote">Remote state</link> filter.
13669 <note>
13670 This filter makes sense only for machine USB filters,
13671 i.e. it is ignored by IHostUSBDeviceFilter objects.
13672 </note>
13673 </desc>
13674 </attribute>
13675
13676 <attribute name="maskedInterfaces" type="unsigned long">
13677 <desc>
13678 This is an advanced option for hiding one or more USB interfaces
13679 from the guest. The value is a bit mask where the bits that are set
13680 means the corresponding USB interface should be hidden, masked off
13681 if you like.
13682 This feature only works on Linux hosts.
13683 </desc>
13684 </attribute>
13685
13686 </interface>
13687
13688
13689 <!--
13690 // IHostUSBDevice
13691 /////////////////////////////////////////////////////////////////////////
13692 -->
13693
13694 <enum
13695 name="USBDeviceState"
13696 uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
13697 >
13698 <desc>
13699 USB device state. This enumeration represents all possible states
13700 of the USB device physically attached to the host computer regarding
13701 its state on the host computer and availability to guest computers
13702 (all currently running virtual machines).
13703
13704 Once a supported USB device is attached to the host, global USB
13705 filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
13706 either ignore the device, or put it to USBDeviceState_Held state, or do
13707 nothing. Unless the device is ignored by global filters, filters of all
13708 currently running guests (<link to="IUSBController::deviceFilters"/>) are
13709 activated that can put it to USBDeviceState_Captured state.
13710
13711 If the device was ignored by global filters, or didn't match
13712 any filters at all (including guest ones), it is handled by the host
13713 in a normal way. In this case, the device state is determined by
13714 the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
13715 or USBDeviceState_Available, depending on the current device usage.
13716
13717 Besides auto-capturing based on filters, the device can be manually
13718 captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
13719 state is USBDeviceState_Busy, USBDeviceState_Available or
13720 USBDeviceState_Held.
13721
13722 <note>
13723 Due to differences in USB stack implementations in Linux and Win32,
13724 states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
13725 only to the Linux version of the product. This also means that (<link
13726 to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
13727 device state is USBDeviceState_Held.
13728 </note>
13729
13730 <see><link to="IHostUSBDevice"/>, <link to="IHostUSBDeviceFilter"/></see>
13731 </desc>
13732
13733 <const name="NotSupported" value="0">
13734 <desc>
13735 Not supported by the VirtualBox server, not available to guests.
13736 </desc>
13737 </const>
13738 <const name="Unavailable" value="1">
13739 <desc>
13740 Being used by the host computer exclusively,
13741 not available to guests.
13742 </desc>
13743 </const>
13744 <const name="Busy" value="2">
13745 <desc>
13746 Being used by the host computer, potentially available to guests.
13747 </desc>
13748 </const>
13749 <const name="Available" value="3">
13750 <desc>
13751 Not used by the host computer, available to guests (the host computer
13752 can also start using the device at any time).
13753 </desc>
13754 </const>
13755 <const name="Held" value="4">
13756 <desc>
13757 Held by the VirtualBox server (ignored by the host computer),
13758 available to guests.
13759 </desc>
13760 </const>
13761 <const name="Captured" value="5">
13762 <desc>
13763 Captured by one of the guest computers, not available
13764 to anybody else.
13765 </desc>
13766 </const>
13767 </enum>
13768
13769 <interface
13770 name="IHostUSBDevice" extends="IUSBDevice"
13771 uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
13772 wsmap="managed"
13773 >
13774 <desc>
13775 The IHostUSBDevice interface represents a physical USB device attached
13776 to the host computer.
13777
13778 Besides properties inherited from IUSBDevice, this interface adds the
13779 <link to="#state"/> property that holds the current state of the USB
13780 device.
13781
13782 <see><link to="IHost::USBDevices"/>,
13783 <link to="IHost::USBDeviceFilters"/></see>
13784 </desc>
13785
13786 <attribute name="state" type="USBDeviceState" readonly="yes">
13787 <desc>
13788 Current state of the device.
13789 </desc>
13790 </attribute>
13791
13792 <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
13793
13794 </interface>
13795
13796
13797 <!--
13798 // IHostUSBDeviceFilter
13799 /////////////////////////////////////////////////////////////////////////
13800 -->
13801
13802 <enum
13803 name="USBDeviceFilterAction"
13804 uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
13805 >
13806 <desc>
13807 Actions for host USB device filters.
13808 <see><link to="IHostUSBDeviceFilter"/>, <link to="USBDeviceState"/></see>
13809 </desc>
13810
13811 <const name="Null" value="0">
13812 <desc>Null value (never used by the API).</desc>
13813 </const>
13814 <const name="Ignore" value="1">
13815 <desc>Ignore the matched USB device.</desc>
13816 </const>
13817 <const name="Hold" value="2">
13818 <desc>Hold the matched USB device.</desc>
13819 </const>
13820 </enum>
13821
13822 <interface
13823 name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
13824 uuid="4cc70246-d74a-400f-8222-3900489c0374"
13825 wsmap="managed"
13826 >
13827 <desc>
13828 The IHostUSBDeviceFilter interface represents a global filter for a
13829 physical USB device used by the host computer. Used indirectly in
13830 <link to="IHost::USBDeviceFilters"/>.
13831
13832 Using filters of this type, the host computer determines the initial
13833 state of the USB device after it is physically attached to the
13834 host's USB controller.
13835
13836 <note>
13837 The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
13838 filters, because it makes sense only for
13839 <link to="IUSBController::deviceFilters">machine USB filters</link>.
13840 </note>
13841
13842 <see><link to="IHost::USBDeviceFilters"/></see>
13843 </desc>
13844
13845 <attribute name="action" type="USBDeviceFilterAction">
13846 <desc>
13847 Action performed by the host when an attached USB device
13848 matches this filter.
13849 </desc>
13850 </attribute>
13851
13852 </interface>
13853
13854 <!--
13855 // IAudioAdapter
13856 /////////////////////////////////////////////////////////////////////////
13857 -->
13858
13859 <enum
13860 name="AudioDriverType"
13861 uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
13862 >
13863 <desc>
13864 Host audio driver type.
13865 </desc>
13866
13867 <const name="Null" value="0">
13868 <desc>Null value, also means "dummy audio driver".</desc>
13869 </const>
13870 <const name="WinMM" value="1">
13871 <desc>Windows multimedia (Windows hosts only).</desc>
13872 </const>
13873 <const name="OSS" value="2">
13874 <desc>Open Sound System (Linux hosts only).</desc>
13875 </const>
13876 <const name="ALSA" value="3">
13877 <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
13878 </const>
13879 <const name="DirectSound" value="4">
13880 <desc>DirectSound (Windows hosts only).</desc>
13881 </const>
13882 <const name="CoreAudio" value="5">
13883 <desc>CoreAudio (Mac hosts only).</desc>
13884 </const>
13885 <const name="MMPM" value="6">
13886 <desc>Reserved for historical reasons.</desc>
13887 </const>
13888 <const name="Pulse" value="7">
13889 <desc>PulseAudio (Linux hosts only).</desc>
13890 </const>
13891 <const name="SolAudio" value="8">
13892 <desc>Solaris audio (Solaris hosts only).</desc>
13893 </const>
13894 </enum>
13895
13896 <enum
13897 name="AudioControllerType"
13898 uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
13899 >
13900 <desc>
13901 Virtual audio controller type.
13902 </desc>
13903
13904 <const name="AC97" value="0"/>
13905 <const name="SB16" value="1"/>
13906 <const name="HDA" value="2"/>
13907 </enum>
13908
13909 <interface
13910 name="IAudioAdapter" extends="$unknown"
13911 uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
13912 wsmap="managed"
13913 >
13914 <desc>
13915 The IAudioAdapter interface represents the virtual audio adapter of
13916 the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
13917 </desc>
13918 <attribute name="enabled" type="boolean">
13919 <desc>
13920 Flag whether the audio adapter is present in the
13921 guest system. If disabled, the virtual guest hardware will
13922 not contain any audio adapter. Can only be changed when
13923 the VM is not running.
13924 </desc>
13925 </attribute>
13926 <attribute name="audioController" type="AudioControllerType">
13927 <desc>
13928 The audio hardware we emulate.
13929 </desc>
13930 </attribute>
13931 <attribute name="audioDriver" type="AudioDriverType">
13932 <desc>
13933 Audio driver the adapter is connected to. This setting
13934 can only be changed when the VM is not running.
13935 </desc>
13936 </attribute>
13937 </interface>
13938
13939 <enum
13940 name="AuthType"
13941 uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
13942 >
13943 <desc>
13944 VirtualBox authentication type.
13945 </desc>
13946
13947 <const name="Null" value="0">
13948 <desc>Null value, also means "no authentication".</desc>
13949 </const>
13950 <const name="External" value="1"/>
13951 <const name="Guest" value="2"/>
13952 </enum>
13953
13954 <!--
13955 // IVRDEServer
13956 /////////////////////////////////////////////////////////////////////////
13957 -->
13958
13959 <interface
13960 name="IVRDEServer" extends="$unknown"
13961 uuid="d38de40a-c2c1-4e95-b5a4-167b05f5694c"
13962 wsmap="managed"
13963 >
13964 <attribute name="enabled" type="boolean">
13965 <desc>VRDE server status.</desc>
13966 </attribute>
13967
13968 <attribute name="authType" type="AuthType">
13969 <desc>VRDE authentication method.</desc>
13970 </attribute>
13971
13972 <attribute name="authTimeout" type="unsigned long">
13973 <desc>Timeout for guest authentication. Milliseconds.</desc>
13974 </attribute>
13975
13976 <attribute name="allowMultiConnection" type="boolean">
13977 <desc>
13978 Flag whether multiple simultaneous connections to the VM are permitted.
13979 Note that this will be replaced by a more powerful mechanism in the future.
13980 </desc>
13981 </attribute>
13982
13983 <attribute name="reuseSingleConnection" type="boolean">
13984 <desc>
13985 Flag whether the existing connection must be dropped and a new connection
13986 must be established by the VRDE server, when a new client connects in single
13987 connection mode.
13988 </desc>
13989 </attribute>
13990
13991 <attribute name="VRDEExtPack" type="wstring">
13992 <desc>
13993 The name of Extension Pack providing VRDE for this VM. Overrides
13994 <link to="ISystemProperties::defaultVRDEExtPack"/>.
13995 </desc>
13996 </attribute>
13997
13998 <attribute name="authLibrary" type="wstring">
13999 <desc>
14000 Library used for authentication of RDP clients by this VM. Overrides
14001 <link to="ISystemProperties::VRDEAuthLibrary"/>.
14002 </desc>
14003 </attribute>
14004
14005 <attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes">
14006 <desc>
14007 Array of names of properties, which are supported by this VRDE server.
14008 </desc>
14009 </attribute>
14010
14011 <method name="setVRDEProperty">
14012 <desc>
14013 Sets a VRDE specific property string.
14014
14015 If you pass @c null or empty string as a key @a value, the given @a key
14016 will be deleted.
14017
14018 </desc>
14019 <param name="key" type="wstring" dir="in">
14020 <desc>Name of the key to set.</desc>
14021 </param>
14022 <param name="value" type="wstring" dir="in">
14023 <desc>Value to assign to the key.</desc>
14024 </param>
14025 </method>
14026
14027 <method name="getVRDEProperty" const="yes">
14028 <desc>
14029 Returns a VRDE specific property string.
14030
14031 If the requested data @a key does not exist, this function will
14032 succeed and return an empty string in the @a value argument.
14033
14034 </desc>
14035 <param name="key" type="wstring" dir="in">
14036 <desc>Name of the key to get.</desc>
14037 </param>
14038 <param name="value" type="wstring" dir="return">
14039 <desc>Value of the requested key.</desc>
14040 </param>
14041 </method>
14042
14043 </interface>
14044
14045
14046 <!--
14047 // ISharedFolder
14048 /////////////////////////////////////////////////////////////////////////
14049 -->
14050
14051 <interface
14052 name="ISharedFolder" extends="$unknown"
14053 uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
14054 wsmap="struct"
14055 >
14056 <desc>
14057 The ISharedFolder interface represents a folder in the host computer's
14058 file system accessible from the guest OS running inside a virtual
14059 machine using an associated logical name.
14060
14061 There are three types of shared folders:
14062 <ul>
14063 <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
14064 folders available to all virtual machines.</li>
14065 <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
14066 VM-specific shared folders available to the given virtual machine at
14067 startup.</li>
14068 <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
14069 VM-specific shared folders created in the session context (for
14070 example, when the virtual machine is running) and automatically
14071 discarded when the session is closed (the VM is powered off).</li>
14072 </ul>
14073
14074 Logical names of shared folders must be unique within the given scope
14075 (global, permanent or transient). However, they do not need to be unique
14076 across scopes. In this case, the definition of the shared folder in a
14077 more specific scope takes precedence over definitions in all other
14078 scopes. The order of precedence is (more specific to more general):
14079 <ol>
14080 <li>Transient definitions</li>
14081 <li>Permanent definitions</li>
14082 <li>Global definitions</li>
14083 </ol>
14084
14085 For example, if MyMachine has a shared folder named
14086 <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
14087 transient shared folder named <tt>C_DRIVE</tt> (that points
14088 to <tt>C:\\\\WINDOWS</tt>) will change the definition
14089 of <tt>C_DRIVE</tt> in the guest OS so
14090 that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
14091 to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
14092 PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
14093 the previous (permanent) definition of <tt>C_DRIVE</tt> that points
14094 to <tt>C:\\</tt> if it still exists.
14095
14096 Note that permanent and transient shared folders of different machines
14097 are in different name spaces, so they don't overlap and don't need to
14098 have unique logical names.
14099
14100 <note>
14101 Global shared folders are not implemented in the current version of the
14102 product.
14103 </note>
14104 </desc>
14105
14106 <attribute name="name" type="wstring" readonly="yes">
14107 <desc>Logical name of the shared folder.</desc>
14108 </attribute>
14109
14110 <attribute name="hostPath" type="wstring" readonly="yes">
14111 <desc>Full path to the shared folder in the host file system.</desc>
14112 </attribute>
14113
14114 <attribute name="accessible" type="boolean" readonly="yes">
14115 <desc>
14116 Whether the folder defined by the host path is currently
14117 accessible or not.
14118 For example, the folder can be inaccessible if it is placed
14119 on the network share that is not available by the time
14120 this property is read.
14121 </desc>
14122 </attribute>
14123
14124 <attribute name="writable" type="boolean" readonly="yes">
14125 <desc>
14126 Whether the folder defined by the host path is writable or
14127 not.
14128 </desc>
14129 </attribute>
14130
14131 <attribute name="autoMount" type="boolean" readonly="yes">
14132 <desc>
14133 Whether the folder gets automatically mounted by the guest or not.
14134 </desc>
14135 </attribute>
14136
14137 <attribute name="lastAccessError" type="wstring" readonly="yes">
14138 <desc>
14139 Text message that represents the result of the last accessibility
14140 check.
14141
14142 Accessibility checks are performed each time the <link to="#accessible"/>
14143 attribute is read. An empty string is returned if the last
14144 accessibility check was successful. A non-empty string indicates a
14145 failure and should normally describe a reason of the failure (for
14146 example, a file read error).
14147 </desc>
14148 </attribute>
14149
14150 </interface>
14151
14152 <!--
14153 // ISession
14154 /////////////////////////////////////////////////////////////////////////
14155 -->
14156
14157 <interface
14158 name="IInternalSessionControl" extends="$unknown"
14159 uuid="0bdda5da-67c8-47be-a610-b83a7fa3e8b6"
14160 internal="yes"
14161 wsmap="suppress"
14162 >
14163 <method name="getPID">
14164 <desc>PID of the process that has created this Session object.
14165 </desc>
14166 <param name="pid" type="unsigned long" dir="return"/>
14167 </method>
14168
14169 <method name="getRemoteConsole">
14170 <desc>
14171 Returns the console object suitable for remote control.
14172
14173 <result name="VBOX_E_INVALID_VM_STATE">
14174 Session state prevents operation.
14175 </result>
14176 <result name="VBOX_E_INVALID_OBJECT_STATE">
14177 Session type prevents operation.
14178 </result>
14179
14180 </desc>
14181 <param name="console" type="IConsole" dir="return"/>
14182 </method>
14183
14184 <method name="assignMachine">
14185 <desc>
14186 Assigns the machine object associated with this direct-type
14187 session or informs the session that it will be a remote one
14188 (if @a machine == @c null).
14189
14190 <result name="VBOX_E_INVALID_VM_STATE">
14191 Session state prevents operation.
14192 </result>
14193 <result name="VBOX_E_INVALID_OBJECT_STATE">
14194 Session type prevents operation.
14195 </result>
14196
14197 </desc>
14198 <param name="machine" type="IMachine" dir="in"/>
14199 </method>
14200
14201 <method name="assignRemoteMachine">
14202 <desc>
14203 Assigns the machine and the (remote) console object associated with
14204 this remote-type session.
14205
14206 <result name="VBOX_E_INVALID_VM_STATE">
14207 Session state prevents operation.
14208 </result>
14209
14210 </desc>
14211 <param name="machine" type="IMachine" dir="in"/>
14212 <param name="console" type="IConsole" dir="in"/>
14213 </method>
14214
14215 <method name="updateMachineState">
14216 <desc>
14217 Updates the machine state in the VM process.
14218 Must be called only in certain cases
14219 (see the method implementation).
14220
14221 <result name="VBOX_E_INVALID_VM_STATE">
14222 Session state prevents operation.
14223 </result>
14224 <result name="VBOX_E_INVALID_OBJECT_STATE">
14225 Session type prevents operation.
14226 </result>
14227
14228 </desc>
14229 <param name="aMachineState" type="MachineState" dir="in"/>
14230 </method>
14231
14232 <method name="uninitialize">
14233 <desc>
14234 Uninitializes (closes) this session. Used by VirtualBox to close
14235 the corresponding remote session when the direct session dies
14236 or gets closed.
14237
14238 <result name="VBOX_E_INVALID_VM_STATE">
14239 Session state prevents operation.
14240 </result>
14241
14242 </desc>
14243 </method>
14244
14245 <method name="onNetworkAdapterChange">
14246 <desc>
14247 Triggered when settings of a network adapter of the
14248 associated virtual machine have changed.
14249
14250 <result name="VBOX_E_INVALID_VM_STATE">
14251 Session state prevents operation.
14252 </result>
14253 <result name="VBOX_E_INVALID_OBJECT_STATE">
14254 Session type prevents operation.
14255 </result>
14256
14257 </desc>
14258 <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
14259 <param name="changeAdapter" type="boolean" dir="in"/>
14260 </method>
14261
14262 <method name="onSerialPortChange">
14263 <desc>
14264 Triggered when settings of a serial port of the
14265 associated virtual machine have changed.
14266
14267 <result name="VBOX_E_INVALID_VM_STATE">
14268 Session state prevents operation.
14269 </result>
14270 <result name="VBOX_E_INVALID_OBJECT_STATE">
14271 Session type prevents operation.
14272 </result>
14273
14274 </desc>
14275 <param name="serialPort" type="ISerialPort" dir="in"/>
14276 </method>
14277
14278 <method name="onParallelPortChange">
14279 <desc>
14280 Triggered when settings of a parallel port of the
14281 associated virtual machine have changed.
14282
14283 <result name="VBOX_E_INVALID_VM_STATE">
14284 Session state prevents operation.
14285 </result>
14286 <result name="VBOX_E_INVALID_OBJECT_STATE">
14287 Session type prevents operation.
14288 </result>
14289
14290 </desc>
14291 <param name="parallelPort" type="IParallelPort" dir="in"/>
14292 </method>
14293
14294 <method name="onStorageControllerChange">
14295 <desc>
14296 Triggered when settings of a storage controller of the
14297 associated virtual machine have changed.
14298
14299 <result name="VBOX_E_INVALID_VM_STATE">
14300 Session state prevents operation.
14301 </result>
14302 <result name="VBOX_E_INVALID_OBJECT_STATE">
14303 Session type prevents operation.
14304 </result>
14305
14306 </desc>
14307 </method>
14308
14309 <method name="onMediumChange">
14310 <desc>
14311 Triggered when attached media of the
14312 associated virtual machine have changed.
14313
14314 <result name="VBOX_E_INVALID_VM_STATE">
14315 Session state prevents operation.
14316 </result>
14317 <result name="VBOX_E_INVALID_OBJECT_STATE">
14318 Session type prevents operation.
14319 </result>
14320
14321 </desc>
14322
14323 <param name="mediumAttachment" type="IMediumAttachment" dir="in">
14324 <desc>The medium attachment which changed.</desc>
14325 </param>
14326 <param name="force" type="boolean" dir="in">
14327 <desc>If the medium change was forced.</desc>
14328 </param>
14329 </method>
14330
14331 <method name="onStorageDeviceChange">
14332 <desc>
14333 Triggered when attached storage devices of the
14334 associated virtual machine have changed.
14335
14336 <result name="VBOX_E_INVALID_VM_STATE">
14337 Session state prevents operation.
14338 </result>
14339 <result name="VBOX_E_INVALID_OBJECT_STATE">
14340 Session type prevents operation.
14341 </result>
14342
14343 </desc>
14344
14345 <param name="mediumAttachment" type="IMediumAttachment" dir="in">
14346 <desc>The medium attachment which changed.</desc>
14347 </param>
14348 <param name="remove" type="boolean" dir="in">
14349 <desc>TRUE if the device is removed, FALSE if it was added.</desc>
14350 </param>
14351 </method>
14352
14353 <method name="onCPUChange">
14354 <desc>
14355 Notification when a CPU changes.
14356 </desc>
14357 <param name="cpu" type="unsigned long" dir="in">
14358 <desc>The CPU which changed</desc>
14359 </param>
14360 <param name="add" type="boolean" dir="in">
14361 <desc>Flag whether the CPU was added or removed</desc>
14362 </param>
14363 </method>
14364
14365 <method name="onCPUExecutionCapChange">
14366 <desc>
14367 Notification when the CPU execution cap changes.
14368 </desc>
14369 <param name="executionCap" type="unsigned long" dir="in">
14370 <desc>The new CPU execution cap value. (1-100)</desc>
14371 </param>
14372 </method>
14373
14374 <method name="onVRDEServerChange">
14375 <desc>
14376 Triggered when settings of the VRDE server object of the
14377 associated virtual machine have changed.
14378
14379 <result name="VBOX_E_INVALID_VM_STATE">
14380 Session state prevents operation.
14381 </result>
14382 <result name="VBOX_E_INVALID_OBJECT_STATE">
14383 Session type prevents operation.
14384 </result>
14385
14386 </desc>
14387 <param name="restart" type="boolean" dir="in">
14388 <desc>Flag whether the server must be restarted</desc>
14389 </param>
14390 </method>
14391
14392 <method name="onUSBControllerChange">
14393 <desc>
14394 Triggered when settings of the USB controller object of the
14395 associated virtual machine have changed.
14396
14397 <result name="VBOX_E_INVALID_VM_STATE">
14398 Session state prevents operation.
14399 </result>
14400 <result name="VBOX_E_INVALID_OBJECT_STATE">
14401 Session type prevents operation.
14402 </result>
14403
14404 </desc>
14405 </method>
14406
14407 <method name="onSharedFolderChange">
14408 <desc>
14409 Triggered when a permanent (global or machine) shared folder has been
14410 created or removed.
14411 <note>
14412 We don't pass shared folder parameters in this notification because
14413 the order in which parallel notifications are delivered is not defined,
14414 therefore it could happen that these parameters were outdated by the
14415 time of processing this notification.
14416 </note>
14417
14418 <result name="VBOX_E_INVALID_VM_STATE">
14419 Session state prevents operation.
14420 </result>
14421 <result name="VBOX_E_INVALID_OBJECT_STATE">
14422 Session type prevents operation.
14423 </result>
14424
14425 </desc>
14426 <param name="global" type="boolean" dir="in"/>
14427 </method>
14428
14429 <method name="onUSBDeviceAttach">
14430 <desc>
14431 Triggered when a request to capture a USB device (as a result
14432 of matched USB filters or direct call to
14433 <link to="IConsole::attachUSBDevice"/>) has completed.
14434 A @c null @a error object means success, otherwise it
14435 describes a failure.
14436
14437 <result name="VBOX_E_INVALID_VM_STATE">
14438 Session state prevents operation.
14439 </result>
14440 <result name="VBOX_E_INVALID_OBJECT_STATE">
14441 Session type prevents operation.
14442 </result>
14443
14444 </desc>
14445 <param name="device" type="IUSBDevice" dir="in"/>
14446 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
14447 <param name="maskedInterfaces" type="unsigned long" dir="in"/>
14448 </method>
14449
14450 <method name="onUSBDeviceDetach">
14451 <desc>
14452 Triggered when a request to release the USB device (as a result
14453 of machine termination or direct call to
14454 <link to="IConsole::detachUSBDevice"/>) has completed.
14455 A @c null @a error object means success, otherwise it
14456 describes a failure.
14457
14458 <result name="VBOX_E_INVALID_VM_STATE">
14459 Session state prevents operation.
14460 </result>
14461 <result name="VBOX_E_INVALID_OBJECT_STATE">
14462 Session type prevents operation.
14463 </result>
14464
14465 </desc>
14466 <param name="id" type="uuid" mod="string" dir="in"/>
14467 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
14468 </method>
14469
14470 <method name="onShowWindow">
14471 <desc>
14472 Called by <link to="IMachine::canShowConsoleWindow"/> and by
14473 <link to="IMachine::showConsoleWindow"/> in order to notify
14474 console listeners
14475 <link to="ICanShowWindowEvent"/>
14476 and <link to="IShowWindowEvent"/>.
14477
14478 <result name="VBOX_E_INVALID_OBJECT_STATE">
14479 Session type prevents operation.
14480 </result>
14481
14482 </desc>
14483 <param name="check" type="boolean" dir="in"/>
14484 <param name="canShow" type="boolean" dir="out"/>
14485 <param name="winId" type="long long" dir="out"/>
14486 </method>
14487
14488 <method name="onBandwidthGroupChange">
14489 <desc>
14490 Notification when one of the bandwidth groups change.
14491 </desc>
14492 <param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
14493 <desc>The bandwidth group which changed.</desc>
14494 </param>
14495 </method>
14496
14497 <method name="accessGuestProperty">
14498 <desc>
14499 Called by <link to="IMachine::getGuestProperty"/> and by
14500 <link to="IMachine::setGuestProperty"/> in order to read and
14501 modify guest properties.
14502
14503 <result name="VBOX_E_INVALID_VM_STATE">
14504 Machine session is not open.
14505 </result>
14506 <result name="VBOX_E_INVALID_OBJECT_STATE">
14507 Session type is not direct.
14508 </result>
14509
14510 </desc>
14511 <param name="name" type="wstring" dir="in"/>
14512 <param name="value" type="wstring" dir="in"/>
14513 <param name="flags" type="wstring" dir="in"/>
14514 <param name="isSetter" type="boolean" dir="in"/>
14515 <param name="retValue" type="wstring" dir="out"/>
14516 <param name="retTimestamp" type="long long" dir="out"/>
14517 <param name="retFlags" type="wstring" dir="out"/>
14518 </method>
14519
14520 <method name="enumerateGuestProperties" const="yes">
14521 <desc>
14522 Return a list of the guest properties matching a set of patterns along
14523 with their values, time stamps and flags.
14524
14525 <result name="VBOX_E_INVALID_VM_STATE">
14526 Machine session is not open.
14527 </result>
14528 <result name="VBOX_E_INVALID_OBJECT_STATE">
14529 Session type is not direct.
14530 </result>
14531
14532 </desc>
14533 <param name="patterns" type="wstring" dir="in">
14534 <desc>
14535 The patterns to match the properties against as a comma-separated
14536 string. If this is empty, all properties currently set will be
14537 returned.
14538 </desc>
14539 </param>
14540 <param name="key" type="wstring" dir="out" safearray="yes">
14541 <desc>
14542 The key names of the properties returned.
14543 </desc>
14544 </param>
14545 <param name="value" type="wstring" dir="out" safearray="yes">
14546 <desc>
14547 The values of the properties returned. The array entries match the
14548 corresponding entries in the @a key array.
14549 </desc>
14550 </param>
14551 <param name="timestamp" type="long long" dir="out" safearray="yes">
14552 <desc>
14553 The time stamps of the properties returned. The array entries match
14554 the corresponding entries in the @a key array.
14555 </desc>
14556 </param>
14557 <param name="flags" type="wstring" dir="out" safearray="yes">
14558 <desc>
14559 The flags of the properties returned. The array entries match the
14560 corresponding entries in the @a key array.
14561 </desc>
14562 </param>
14563 </method>
14564
14565 <method name="onlineMergeMedium">
14566 <desc>
14567 Triggers online merging of a hard disk. Used internally when deleting
14568 a snapshot while a VM referring to the same hard disk chain is running.
14569
14570 <result name="VBOX_E_INVALID_VM_STATE">
14571 Machine session is not open.
14572 </result>
14573 <result name="VBOX_E_INVALID_OBJECT_STATE">
14574 Session type is not direct.
14575 </result>
14576
14577 </desc>
14578 <param name="mediumAttachment" type="IMediumAttachment" dir="in">
14579 <desc>The medium attachment to identify the medium chain.</desc>
14580 </param>
14581 <param name="sourceIdx" type="unsigned long" dir="in">
14582 <desc>The index of the source image in the chain.
14583 Redundant, but drastically reduces IPC.</desc>
14584 </param>
14585 <param name="targetIdx" type="unsigned long" dir="in">
14586 <desc>The index of the target image in the chain.
14587 Redundant, but drastically reduces IPC.</desc>
14588 </param>
14589 <param name="source" type="IMedium" dir="in">
14590 <desc>Merge source medium.</desc>
14591 </param>
14592 <param name="target" type="IMedium" dir="in">
14593 <desc>Merge target medium.</desc>
14594 </param>
14595 <param name="mergeForward" type="boolean" dir="in">
14596 <desc>Merge direction.</desc>
14597 </param>
14598 <param name="parentForTarget" type="IMedium" dir="in">
14599 <desc>For forward merges: new parent for target medium.</desc>
14600 </param>
14601 <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
14602 <desc>For backward merges: list of media which need their parent UUID
14603 updated.</desc>
14604 </param>
14605 <param name="progress" type="IProgress" dir="in">
14606 <desc>
14607 Progress object for this operation.
14608 </desc>
14609 </param>
14610 </method>
14611
14612 </interface>
14613
14614 <interface
14615 name="ISession" extends="$unknown"
14616 uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
14617 wsmap="managed"
14618 >
14619 <desc>
14620 The ISession interface represents a client process and allows for locking
14621 virtual machines (represented by IMachine objects) to prevent conflicting
14622 changes to the machine.
14623
14624 Any caller wishing to manipulate a virtual machine needs to create a session
14625 object first, which lives in its own process space. Such session objects are
14626 then associated with <link to="IMachine" /> objects living in the VirtualBox
14627 server process to coordinate such changes.
14628
14629 There are two typical scenarios in which sessions are used:
14630
14631 <ul>
14632 <li>To alter machine settings or control a running virtual machine, one
14633 needs to lock a machine for a given session (client process) by calling
14634 <link to="IMachine::lockMachine"/>.
14635
14636 Whereas multiple sessions may control a running virtual machine, only
14637 one process can obtain a write lock on the machine to prevent conflicting
14638 changes. A write lock is also needed if a process wants to actually run a
14639 virtual machine in its own context, such as the VirtualBox GUI or
14640 VBoxHeadless front-ends. They must also lock a machine for their own
14641 sessions before they are allowed to power up the virtual machine.
14642
14643 As a result, no machine settings can be altered while another process is
14644 already using it, either because that process is modifying machine settings
14645 or because the machine is running.
14646 </li>
14647 <li>
14648 To start a VM using one of the existing VirtualBox front-ends (e.g. the
14649 VirtualBox GUI or VBoxHeadless), one would use
14650 <link to="IMachine::launchVMProcess"/>, which also takes a session object
14651 as its first parameter. This session then identifies the caller and lets the
14652 caller control the started machine (for example, pause machine execution or
14653 power it down) as well as be notified about machine execution state changes.
14654 </li>
14655 </ul>
14656
14657 How sessions objects are created in a client process depends on whether you use
14658 the Main API via COM or via the webservice:
14659
14660 <ul>
14661 <li>When using the COM API directly, an object of the Session class from the
14662 VirtualBox type library needs to be created. In regular COM C++ client code,
14663 this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
14664 This object will then act as a local session object in further calls to open
14665 a session.
14666 </li>
14667
14668 <li>In the webservice, the session manager (IWebsessionManager) instead creates
14669 a session object automatically whenever <link to="IWebsessionManager::logon" />
14670 is called. A managed object reference to that session object can be retrieved by
14671 calling <link to="IWebsessionManager::getSessionObject" />.
14672 </li>
14673 </ul>
14674 </desc>
14675
14676 <attribute name="state" type="SessionState" readonly="yes">
14677 <desc>Current state of this session.</desc>
14678 </attribute>
14679
14680 <attribute name="type" type="SessionType" readonly="yes">
14681 <desc>
14682 Type of this session. The value of this attribute is valid only
14683 if the session currently has a machine locked (i.e. its
14684 <link to="#state" /> is Locked), otherwise an error will be returned.
14685 </desc>
14686 </attribute>
14687
14688 <attribute name="machine" type="IMachine" readonly="yes">
14689 <desc>Machine object associated with this session.</desc>
14690 </attribute>
14691
14692 <attribute name="console" type="IConsole" readonly="yes">
14693 <desc>Console object associated with this session.</desc>
14694 </attribute>
14695
14696 <method name="unlockMachine">
14697 <desc>
14698 Unlocks a machine that was previously locked for the current session.
14699
14700 Calling this method is required every time a machine has been locked
14701 for a particular session using the <link to="IMachine::launchVMProcess" />
14702 or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
14703 the machine will be set to <link to="MachineState_Aborted" /> on the
14704 server, and changes made to the machine settings will be lost.
14705
14706 Generally, it is recommended to unlock all machines explicitly
14707 before terminating the application (regardless of the reason for
14708 the termination).
14709
14710 <note>
14711 Do not expect the session state (<link to="ISession::state" />
14712 to return to "Unlocked" immediately after you invoke this method,
14713 particularly if you have started a new VM process. The session
14714 state will automatically return to "Unlocked" once the VM is no
14715 longer executing, which can of course take a very long time.
14716 </note>
14717
14718 <result name="E_UNEXPECTED">
14719 Session is not locked.
14720 </result>
14721
14722 </desc>
14723 </method>
14724
14725 </interface>
14726
14727 <!--
14728 // IStorageController
14729 /////////////////////////////////////////////////////////////////////////
14730 -->
14731
14732 <enum
14733 name="StorageBus"
14734 uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
14735 >
14736 <desc>
14737 The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
14738 see <link to="IStorageController::bus" />.
14739 </desc>
14740 <const name="Null" value="0">
14741 <desc>@c null value. Never used by the API.</desc>
14742 </const>
14743 <const name="IDE" value="1"/>
14744 <const name="SATA" value="2"/>
14745 <const name="SCSI" value="3"/>
14746 <const name="Floppy" value="4"/>
14747 <const name="SAS" value="5"/>
14748 </enum>
14749
14750 <enum
14751 name="StorageControllerType"
14752 uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
14753 >
14754 <desc>
14755 The exact variant of storage controller hardware presented
14756 to the guest; see <link to="IStorageController::controllerType" />.
14757 </desc>
14758
14759 <const name="Null" value="0">
14760 <desc>@c null value. Never used by the API.</desc>
14761 </const>
14762 <const name="LsiLogic" value="1">
14763 <desc>A SCSI controller of the LsiLogic variant.</desc>
14764 </const>
14765 <const name="BusLogic" value="2">
14766 <desc>A SCSI controller of the BusLogic variant.</desc>
14767 </const>
14768 <const name="IntelAhci" value="3">
14769 <desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
14770 </const>
14771 <const name="PIIX3" value="4">
14772 <desc>An IDE controller of the PIIX3 variant.</desc>
14773 </const>
14774 <const name="PIIX4" value="5">
14775 <desc>An IDE controller of the PIIX4 variant.</desc>
14776 </const>
14777 <const name="ICH6" value="6">
14778 <desc>An IDE controller of the ICH6 variant.</desc>
14779 </const>
14780 <const name="I82078" value="7">
14781 <desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
14782 </const>
14783 <const name="LsiLogicSas" value="8">
14784 <desc>A variant of the LsiLogic controller using SAS.</desc>
14785 </const>
14786 </enum>
14787
14788 <enum
14789 name="ChipsetType"
14790 uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
14791 >
14792 <desc>
14793 Type of emulated chipset (mostly southbridge).
14794 </desc>
14795
14796 <const name="Null" value="0">
14797 <desc>@c null value. Never used by the API.</desc>
14798 </const>
14799 <const name="PIIX3" value="1">
14800 <desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
14801 </const>
14802 <const name="ICH9" value="2">
14803 <desc>A ICH9 (I/O Controller Hub) chipset.</desc>
14804 </const>
14805 </enum>
14806
14807 <interface
14808 name="IStorageController" extends="$unknown"
14809 uuid="a1556333-09b6-46d9-bfb7-fc239b7fbe1e"
14810 wsmap="managed"
14811 >
14812 <desc>
14813 Represents a storage controller that is attached to a virtual machine
14814 (<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
14815 attached to storage controllers in a real computer, virtual drives
14816 (represented by <link to="IMediumAttachment" />) are attached to virtual
14817 storage controllers, represented by this interface.
14818
14819 As opposed to physical hardware, VirtualBox has a very generic concept
14820 of a storage controller, and for purposes of the Main API, all virtual
14821 storage is attached to virtual machines via instances of this interface.
14822 There are five types of such virtual storage controllers: IDE, SCSI, SATA,
14823 SAS and Floppy (see <link to="#bus" />). Depending on which of these four
14824 is used, certain sub-types may be available and can be selected in
14825 <link to="#controllerType" />.
14826
14827 Depending on these settings, the guest operating system might see
14828 significantly different virtual hardware.
14829 </desc>
14830
14831 <attribute name="name" type="wstring" readonly="yes">
14832 <desc>
14833 Name of the storage controller, as originally specified with
14834 <link to="IMachine::addStorageController" />. This then uniquely
14835 identifies this controller with other method calls such as
14836 <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
14837 </desc>
14838 </attribute>
14839
14840 <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
14841 <desc>
14842 Maximum number of devices which can be attached to one port.
14843 </desc>
14844 </attribute>
14845
14846 <attribute name="minPortCount" type="unsigned long" readonly="yes">
14847 <desc>
14848 Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
14849 </desc>
14850 </attribute>
14851
14852 <attribute name="maxPortCount" type="unsigned long" readonly="yes">
14853 <desc>
14854 Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
14855 </desc>
14856 </attribute>
14857
14858 <attribute name="instance" type="unsigned long">
14859 <desc>
14860 The instance number of the device in the running VM.
14861 </desc>
14862 </attribute>
14863
14864 <attribute name="portCount" type="unsigned long">
14865 <desc>
14866 The number of currently usable ports on the controller.
14867 The minimum and maximum number of ports for one controller are
14868 stored in <link to="IStorageController::minPortCount"/>
14869 and <link to="IStorageController::maxPortCount"/>.
14870 </desc>
14871 </attribute>
14872
14873 <attribute name="bus" type="StorageBus" readonly="yes">
14874 <desc>
14875 The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
14876 </desc>
14877 </attribute>
14878
14879 <attribute name="controllerType" type="StorageControllerType">
14880 <desc>
14881 The exact variant of storage controller hardware presented
14882 to the guest.
14883 Depending on this value, VirtualBox will provide a different
14884 virtual storage controller hardware to the guest.
14885 For SATA, SAS and floppy controllers, only one variant is
14886 available, but for IDE and SCSI, there are several.
14887
14888 For SCSI controllers, the default type is LsiLogic.
14889 </desc>
14890 </attribute>
14891
14892 <attribute name="useHostIOCache" type="boolean">
14893 <desc>
14894 If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
14895 caches and use synchronous file APIs on the host. This was the only option in the API before
14896 VirtualBox 3.2 and is still the default for IDE controllers.
14897
14898 If false, the host I/O cache will be disabled for image files attached to this storage controller.
14899 Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
14900 it possible to turn off the host I/O caches because the emulation can handle unaligned access to
14901 the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
14902 virtual machines are running at the same time to prevent I/O cache related hangs.
14903 This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
14904 </desc>
14905 </attribute>
14906
14907 <attribute name="bootable" type="boolean" readonly="yes">
14908 <desc>
14909 Returns whether it is possible to boot from disks attached to this controller.
14910 </desc>
14911 </attribute>
14912
14913 <method name="getIDEEmulationPort">
14914 <desc>
14915 Gets the corresponding port number which is emulated as an IDE device.
14916 Works only with SATA controllers.
14917
14918 <result name="E_INVALIDARG">
14919 The @a devicePosition is not in the range 0 to 3.
14920 </result>
14921 <result name="E_NOTIMPL">
14922 The storage controller type is not SATAIntelAhci.
14923 </result>
14924
14925 </desc>
14926 <param name="devicePosition" type="long" dir="in"/>
14927 <param name="portNumber" type="long" dir="return"/>
14928 </method>
14929
14930 <method name="setIDEEmulationPort">
14931 <desc>
14932 Sets the port number which is emulated as an IDE device.
14933 Works only with SATA controllers.
14934
14935 <result name="E_INVALIDARG">
14936 The @a devicePosition is not in the range 0 to 3 or the
14937 @a portNumber is not in the range 0 to 29.
14938 </result>
14939 <result name="E_NOTIMPL">
14940 The storage controller type is not SATAIntelAhci.
14941 </result>
14942
14943 </desc>
14944 <param name="devicePosition" type="long" dir="in"/>
14945 <param name="portNumber" type="long" dir="in"/>
14946 </method>
14947
14948 </interface>
14949
14950<if target="wsdl">
14951
14952 <!--
14953 // IManagedObjectRef
14954 /////////////////////////////////////////////////////////////////////////
14955 -->
14956
14957 <interface
14958 name="IManagedObjectRef" extends="$unknown"
14959 uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
14960 internal="yes"
14961 wsmap="managed"
14962 wscpp="hardcoded"
14963 >
14964 <desc>
14965 Managed object reference.
14966
14967 Only within the webservice, a managed object reference (which is really
14968 an opaque number) allows a webservice client to address an object
14969 that lives in the address space of the webservice server.
14970
14971 Behind each managed object reference, there is a COM object that lives
14972 in the webservice server's address space. The COM object is not freed
14973 until the managed object reference is released, either by an explicit
14974 call to <link to="IManagedObjectRef::release" /> or by logging off from
14975 the webservice (<link to="IWebsessionManager::logoff" />), which releases
14976 all objects created during the webservice session.
14977
14978 Whenever a method call of the VirtualBox API returns a COM object, the
14979 webservice representation of that method will instead return a
14980 managed object reference, which can then be used to invoke methods
14981 on that object.
14982 </desc>
14983
14984 <method name="getInterfaceName">
14985 <desc>
14986 Returns the name of the interface that this managed object represents,
14987 for example, "IMachine", as a string.
14988 </desc>
14989 <param name="return" type="wstring" dir="return"/>
14990 </method>
14991
14992 <method name="release">
14993 <desc>
14994 Releases this managed object reference and frees the resources that
14995 were allocated for it in the webservice server process. After calling
14996 this method, the identifier of the reference can no longer be used.
14997 </desc>
14998 </method>
14999
15000 </interface>
15001
15002 <!--
15003 // IWebsessionManager
15004 /////////////////////////////////////////////////////////////////////////
15005 -->
15006
15007 <interface
15008 name="IWebsessionManager" extends="$unknown"
15009 uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
15010 internal="yes"
15011 wsmap="global"
15012 wscpp="hardcoded"
15013 >
15014 <desc>
15015 Websession manager. This provides essential services
15016 to webservice clients.
15017 </desc>
15018 <method name="logon">
15019 <desc>
15020 Logs a new client onto the webservice and returns a managed object reference to
15021 the IVirtualBox instance, which the client can then use as a basis to further
15022 queries, since all calls to the VirtualBox API are based on the IVirtualBox
15023 interface, in one way or the other.
15024 </desc>
15025 <param name="username" type="wstring" dir="in"/>
15026 <param name="password" type="wstring" dir="in"/>
15027 <param name="return" type="IVirtualBox" dir="return"/>
15028 </method>
15029
15030 <method name="getSessionObject">
15031 <desc>
15032 Returns a managed object reference to the internal ISession object that was created
15033 for this web service session when the client logged on.
15034
15035 <see><link to="ISession"/></see>
15036 </desc>
15037 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
15038 <param name="return" type="ISession" dir="return"/>
15039 </method>
15040
15041 <method name="logoff">
15042 <desc>
15043 Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
15044 and destroys all resources associated with the session (most importantly, all
15045 managed objects created in the server while the session was active).
15046 </desc>
15047 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
15048 </method>
15049
15050 </interface>
15051
15052</if>
15053
15054 <!--
15055 // IPerformanceCollector & friends
15056 /////////////////////////////////////////////////////////////////////////
15057 -->
15058
15059 <interface
15060 name="IPerformanceMetric" extends="$unknown"
15061 uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
15062 >
15063 <desc>
15064 The IPerformanceMetric interface represents parameters of the given
15065 performance metric.
15066 </desc>
15067
15068 <attribute name="metricName" type="wstring" readonly="yes">
15069 <desc>
15070 Name of the metric.
15071 </desc>
15072 </attribute>
15073
15074 <attribute name="object" type="$unknown" readonly="yes">
15075 <desc>
15076 Object this metric belongs to.
15077 </desc>
15078 </attribute>
15079
15080 <attribute name="description" type="wstring" readonly="yes">
15081 <desc>
15082 Textual description of the metric.
15083 </desc>
15084 </attribute>
15085
15086 <attribute name="period" type="unsigned long" readonly="yes">
15087 <desc>
15088 Time interval between samples, measured in seconds.
15089 </desc>
15090 </attribute>
15091
15092 <attribute name="count" type="unsigned long" readonly="yes">
15093 <desc>
15094 Number of recent samples retained by the performance collector for this
15095 metric.
15096
15097 When the collected sample count exceeds this number, older samples
15098 are discarded.
15099 </desc>
15100 </attribute>
15101
15102 <attribute name="unit" type="wstring" readonly="yes">
15103 <desc>
15104 Unit of measurement.
15105 </desc>
15106 </attribute>
15107
15108 <attribute name="minimumValue" type="long" readonly="yes">
15109 <desc>
15110 Minimum possible value of this metric.
15111 </desc>
15112 </attribute>
15113
15114 <attribute name="maximumValue" type="long" readonly="yes">
15115 <desc>
15116 Maximum possible value of this metric.
15117 </desc>
15118 </attribute>
15119 </interface>
15120
15121 <interface
15122 name="IPerformanceCollector" extends="$unknown"
15123 uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
15124 wsmap="managed"
15125 >
15126 <desc>
15127 The IPerformanceCollector interface represents a service that collects
15128 and stores performance metrics data.
15129
15130 Performance metrics are associated with objects of interfaces like IHost
15131 and IMachine. Each object has a distinct set of performance metrics. The
15132 set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
15133
15134 Metric data is collected at the specified intervals and is retained
15135 internally. The interval and the number of retained samples can be set
15136 with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
15137 and collection settings are not persistent, they are discarded as soon as
15138 VBoxSVC process terminates. Moreover, metric settings and data associated
15139 with a particular VM only exist while VM is running. They disappear as
15140 soon as VM shuts down. It is not possible to set up metrics for machines
15141 that are powered off. One needs to start VM first, then set up metric
15142 collection parameters.
15143
15144 Metrics are organized hierarchically, with each level separated by a
15145 slash (/) character. Generally, the scheme for metric names is like this:
15146
15147 <tt>Category/Metric[/SubMetric][:aggregation]</tt>
15148
15149 "Category/Metric" together form the base metric name. A base metric is
15150 the smallest unit for which a sampling interval and the number of
15151 retained samples can be set. Only base metrics can be enabled and
15152 disabled. All sub-metrics are collected when their base metric is
15153 collected. Collected values for any set of sub-metrics can be queried
15154 with <link to="IPerformanceCollector::queryMetricsData" />.
15155
15156 For example "CPU/Load/User:avg" metric name stands for the "CPU"
15157 category, "Load" metric, "User" submetric, "average" aggregate. An
15158 aggregate function is computed over all retained data. Valid aggregate
15159 functions are:
15160
15161 <ul>
15162 <li>avg -- average</li>
15163 <li>min -- minimum</li>
15164 <li>max -- maximum</li>
15165 </ul>
15166
15167 When setting up metric parameters, querying metric data, enabling or
15168 disabling metrics wildcards can be used in metric names to specify a
15169 subset of metrics. For example, to select all CPU-related metrics
15170 use <tt>CPU/*</tt>, all averages can be queried using <tt>*:avg</tt> and
15171 so on. To query metric values without aggregates <tt>*:</tt> can be used.
15172
15173 The valid names for base metrics are:
15174
15175 <ul>
15176 <li>CPU/Load</li>
15177 <li>CPU/MHz</li>
15178 <li>RAM/Usage</li>
15179 <li>RAM/VMM</li>
15180 </ul>
15181
15182 The general sequence for collecting and retrieving the metrics is:
15183 <ul>
15184 <li>
15185 Obtain an instance of IPerformanceCollector with
15186 <link to="IVirtualBox::performanceCollector" />
15187 </li>
15188 <li>
15189 Allocate and populate an array with references to objects the metrics
15190 will be collected for. Use references to IHost and IMachine objects.
15191 </li>
15192 <li>
15193 Allocate and populate an array with base metric names the data will
15194 be collected for.
15195 </li>
15196 <li>
15197 Call <link to="IPerformanceCollector::setupMetrics" />. From now on
15198 the metric data will be collected and stored.
15199 </li>
15200 <li>
15201 Wait for the data to get collected.
15202 </li>
15203 <li>
15204 Allocate and populate an array with references to objects the metric
15205 values will be queried for. You can re-use the object array used for
15206 setting base metrics.
15207 </li>
15208 <li>
15209 Allocate and populate an array with metric names the data will be
15210 collected for. Note that metric names differ from base metric names.
15211 </li>
15212 <li>
15213 Call <link to="IPerformanceCollector::queryMetricsData" />. The data
15214 that have been collected so far are returned. Note that the values
15215 are still retained internally and data collection continues.
15216 </li>
15217 </ul>
15218
15219 For an example of usage refer to the following files in VirtualBox SDK:
15220 <ul>
15221 <li>
15222 Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
15223 </li>
15224 <li>
15225 Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
15226 </li>
15227 </ul>
15228 </desc>
15229
15230 <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
15231 <desc>
15232 Array of unique names of metrics.
15233
15234 This array represents all metrics supported by the performance
15235 collector. Individual objects do not necessarily support all of them.
15236 <link to="IPerformanceCollector::getMetrics"/> can be used to get the
15237 list of supported metrics for a particular object.
15238 </desc>
15239 </attribute>
15240
15241 <method name="getMetrics">
15242 <desc>
15243 Returns parameters of specified metrics for a set of objects.
15244 <note>
15245 @c Null metrics array means all metrics. @c Null object array means
15246 all existing objects.
15247 </note>
15248 </desc>
15249 <param name="metricNames" type="wstring" dir="in" safearray="yes">
15250 <desc>
15251 Metric name filter. Currently, only a comma-separated list of metrics
15252 is supported.
15253 </desc>
15254 </param>
15255 <param name="objects" type="$unknown" dir="in" safearray="yes">
15256 <desc>
15257 Set of objects to return metric parameters for.
15258 </desc>
15259 </param>
15260 <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
15261 <desc>
15262 Array of returned metric parameters.
15263 </desc>
15264 </param>
15265 </method>
15266
15267 <method name="setupMetrics">
15268 <desc>
15269 Sets parameters of specified base metrics for a set of objects. Returns
15270 an array of <link to="IPerformanceMetric" /> describing the metrics
15271 have been affected.
15272 <note>
15273 @c Null or empty metric name array means all metrics. @c Null or
15274 empty object array means all existing objects. If metric name array
15275 contains a single element and object array contains many, the single
15276 metric name array element is applied to each object array element to
15277 form metric/object pairs.
15278 </note>
15279 </desc>
15280 <param name="metricNames" type="wstring" dir="in" safearray="yes">
15281 <desc>
15282 Metric name filter. Comma-separated list of metrics with wildcard
15283 support.
15284 </desc>
15285 </param>
15286 <param name="objects" type="$unknown" dir="in" safearray="yes">
15287 <desc>
15288 Set of objects to setup metric parameters for.
15289 </desc>
15290 </param>
15291 <param name="period" type="unsigned long" dir="in">
15292 <desc>
15293 Time interval in seconds between two consecutive samples of
15294 performance data.
15295 </desc>
15296 </param>
15297 <param name="count" type="unsigned long" dir="in">
15298 <desc>
15299 Number of samples to retain in performance data history. Older
15300 samples get discarded.
15301 </desc>
15302 </param>
15303 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
15304 <desc>
15305 Array of metrics that have been modified by the call to this method.
15306 </desc>
15307 </param>
15308 </method>
15309
15310 <method name="enableMetrics">
15311 <desc>
15312 Turns on collecting specified base metrics. Returns an array of
15313 <link to="IPerformanceMetric" /> describing the metrics have been
15314 affected.
15315 <note>
15316 @c Null or empty metric name array means all metrics. @c Null or
15317 empty object array means all existing objects. If metric name array
15318 contains a single element and object array contains many, the single
15319 metric name array element is applied to each object array element to
15320 form metric/object pairs.
15321 </note>
15322 </desc>
15323 <param name="metricNames" type="wstring" dir="in" safearray="yes">
15324 <desc>
15325 Metric name filter. Comma-separated list of metrics with wildcard
15326 support.
15327 </desc>
15328 </param>
15329 <param name="objects" type="$unknown" dir="in" safearray="yes">
15330 <desc>
15331 Set of objects to enable metrics for.
15332 </desc>
15333 </param>
15334 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
15335 <desc>
15336 Array of metrics that have been modified by the call to this method.
15337 </desc>
15338 </param>
15339 </method>
15340
15341 <method name="disableMetrics">
15342 <desc>
15343 Turns off collecting specified base metrics. Returns an array of
15344 <link to="IPerformanceMetric" /> describing the metrics have been
15345 affected.
15346 <note>
15347 @c Null or empty metric name array means all metrics. @c Null or
15348 empty object array means all existing objects. If metric name array
15349 contains a single element and object array contains many, the single
15350 metric name array element is applied to each object array element to
15351 form metric/object pairs.
15352 </note>
15353 </desc>
15354 <param name="metricNames" type="wstring" dir="in" safearray="yes">
15355 <desc>
15356 Metric name filter. Comma-separated list of metrics with wildcard
15357 support.
15358 </desc>
15359 </param>
15360 <param name="objects" type="$unknown" dir="in" safearray="yes">
15361 <desc>
15362 Set of objects to disable metrics for.
15363 </desc>
15364 </param>
15365 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
15366 <desc>
15367 Array of metrics that have been modified by the call to this method.
15368 </desc>
15369 </param>
15370 </method>
15371
15372 <method name="queryMetricsData">
15373 <desc>
15374 Queries collected metrics data for a set of objects.
15375
15376 The data itself and related metric information are returned in seven
15377 parallel and one flattened array of arrays. Elements of
15378 <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
15379 returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
15380 the same index describe one set of values corresponding to a single
15381 metric.
15382
15383 The <tt>returnData</tt> parameter is a flattened array of arrays. Each
15384 start and length of a sub-array is indicated by
15385 <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
15386 value for metric <tt>metricNames[i]</tt> is at
15387 <tt>returnData[returnIndices[i]]</tt>.
15388
15389 <note>
15390 @c Null or empty metric name array means all metrics. @c Null or
15391 empty object array means all existing objects. If metric name array
15392 contains a single element and object array contains many, the single
15393 metric name array element is applied to each object array element to
15394 form metric/object pairs.
15395 </note>
15396 <note>
15397 Data collection continues behind the scenes after call to @c
15398 queryMetricsData. The return data can be seen as the snapshot of the
15399 current state at the time of @c queryMetricsData call. The internally
15400 kept metric values are not cleared by the call. This makes possible
15401 querying different subsets of metrics or aggregates with subsequent
15402 calls. If periodic querying is needed it is highly suggested to query
15403 the values with @c interval*count period to avoid confusion. This way
15404 a completely new set of data values will be provided by each query.
15405 </note>
15406 </desc>
15407 <param name="metricNames" type="wstring" dir="in" safearray="yes">
15408 <desc>
15409 Metric name filter. Comma-separated list of metrics with wildcard
15410 support.
15411 </desc>
15412 </param>
15413 <param name="objects" type="$unknown" dir="in" safearray="yes">
15414 <desc>
15415 Set of objects to query metrics for.
15416 </desc>
15417 </param>
15418 <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
15419 <desc>
15420 Names of metrics returned in @c returnData.
15421 </desc>
15422 </param>
15423 <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
15424 <desc>
15425 Objects associated with metrics returned in @c returnData.
15426 </desc>
15427 </param>
15428 <param name="returnUnits" type="wstring" dir="out" safearray="yes">
15429 <desc>
15430 Units of measurement for each returned metric.
15431 </desc>
15432 </param>
15433 <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
15434 <desc>
15435 Divisor that should be applied to return values in order to get
15436 floating point values. For example:
15437 <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
15438 will retrieve the floating point value of i-th sample of the first
15439 metric.
15440 </desc>
15441 </param>
15442 <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
15443 <desc>
15444 Sequence numbers of the first elements of value sequences of
15445 particular metrics returned in @c returnData. For aggregate metrics
15446 it is the sequence number of the sample the aggregate started
15447 calculation from.
15448 </desc>
15449 </param>
15450 <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
15451 <desc>
15452 Indices of the first elements of value sequences of particular
15453 metrics returned in @c returnData.
15454 </desc>
15455 </param>
15456 <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
15457 <desc>
15458 Lengths of value sequences of particular metrics.
15459 </desc>
15460 </param>
15461 <param name="returnData" type="long" dir="return" safearray="yes">
15462 <desc>
15463 Flattened array of all metric data containing sequences of values for
15464 each metric.
15465 </desc>
15466 </param>
15467 </method>
15468
15469 </interface>
15470
15471 <enum
15472 name="NATAliasMode"
15473 uuid="67772168-50d9-11df-9669-7fb714ee4fa1"
15474 >
15475 <desc></desc>
15476 <const name="AliasLog" value="0x1">
15477 <desc></desc>
15478 </const>
15479 <const name="AliasProxyOnly" value="0x02">
15480 <desc></desc>
15481 </const>
15482 <const name="AliasUseSamePorts" value="0x04">
15483 <desc></desc>
15484 </const>
15485 </enum>
15486
15487 <enum
15488 name="NATProtocol"
15489 uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
15490 >
15491 <desc>Protocol definitions used with NAT port-forwarding rules.</desc>
15492 <const name="UDP" value="0">
15493 <desc>Port-forwarding uses UDP protocol.</desc>
15494 </const>
15495 <const name="TCP" value="1">
15496 <desc>Port-forwarding uses TCP protocol.</desc>
15497 </const>
15498 </enum>
15499
15500 <interface
15501 name="INATEngine" extends="$unknown"
15502 uuid="4b286616-eb03-11de-b0fb-1701eca42246"
15503 wsmap="managed"
15504 >
15505 <desc>Interface for managing a NAT engine which is used with a virtual machine. This
15506 allows for changing NAT behavior such as port-forwarding rules. This interface is
15507 used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
15508 <attribute name="network" type="wstring">
15509 <desc>The network attribute of the NAT engine (the same value is used with built-in
15510 DHCP server to fill corresponding fields of DHCP leases).</desc>
15511 </attribute>
15512 <attribute name="hostIP" type="wstring">
15513 <desc>IP of host interface to bind all opened sockets to.
15514 <note>Changing this does not change binding of port forwarding.</note>
15515 </desc>
15516 </attribute>
15517 <attribute name="tftpPrefix" type="wstring">
15518 <desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
15519 the corresponding fields of DHCP leases.</desc>
15520 </attribute>
15521 <attribute name="tftpBootFile" type="wstring">
15522 <desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
15523 the corresponding fields of DHCP leases.</desc>
15524 </attribute>
15525 <attribute name="tftpNextServer" type="wstring">
15526 <desc>TFTP server attribute which is used with the built-in DHCP server to fill
15527 the corresponding fields of DHCP leases.
15528 <note>The preferred form is IPv4 addresses.</note>
15529 </desc>
15530 </attribute>
15531 <attribute name="aliasMode" type="unsigned long">
15532 <desc></desc>
15533 </attribute>
15534 <attribute name="dnsPassDomain" type="boolean">
15535 <desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
15536 </attribute>
15537 <attribute name="dnsProxy" type="boolean">
15538 <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
15539 of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
15540 </attribute>
15541 <attribute name="dnsUseHostResolver" type="boolean">
15542 <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
15543 of the DNS proxy and process traffic using the host resolver mechanism.</desc>
15544 </attribute>
15545 <attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
15546 <desc>Array of NAT port-forwarding rules in string representation, in the following
15547 format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
15548 </attribute>
15549 <method name="setNetworkSettings">
15550 <desc>Sets network configuration of the NAT engine.</desc>
15551 <param name="mtu" type="unsigned long" dir="in">
15552 <desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
15553 </param>
15554 <param name="sockSnd" type="unsigned long" dir="in">
15555 <desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
15556 </param>
15557 <param name="sockRcv" type="unsigned long" dir="in">
15558 <desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
15559 </param>
15560 <param name="TcpWndSnd" type="unsigned long" dir="in">
15561 <desc>Initial size of the NAT engine's sending TCP window in bytes when
15562 establishing a new TCP connection.</desc>
15563 </param>
15564 <param name="TcpWndRcv" type="unsigned long" dir="in">
15565 <desc>Initial size of the NAT engine's receiving TCP window in bytes when
15566 establishing a new TCP connection.</desc>
15567 </param>
15568 </method>
15569 <method name="getNetworkSettings">
15570 <desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
15571 for parameter descriptions.</desc>
15572 <param name="mtu" type="unsigned long" dir="out" />
15573 <param name="sockSnd" type="unsigned long" dir="out" />
15574 <param name="sockRcv" type="unsigned long" dir="out" />
15575 <param name="TcpWndSnd" type="unsigned long" dir="out" />
15576 <param name="TcpWndRcv" type="unsigned long" dir="out" />
15577 </method>
15578 <method name="addRedirect">
15579 <desc>Adds a new NAT port-forwarding rule.</desc>
15580 <param name="name" type="wstring" dir="in">
15581 <desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
15582 auto-generates one using the other parameters.</desc>
15583 </param>
15584 <param name="proto" type="NATProtocol" dir="in">
15585 <desc>Protocol handled with the rule.</desc>
15586 </param>
15587 <param name="hostIp" type="wstring" dir="in">
15588 <desc>IP of the host interface to which the rule should apply. An empty ip address is
15589 acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
15590 </param>
15591 <param name="hostPort" type="unsigned short" dir="in">
15592 <desc>The port number to listen on.</desc>
15593 </param>
15594 <param name="guestIp" type="wstring" dir="in">
15595 <desc>The IP address of the guest which the NAT engine will forward matching packets
15596 to. An empty IP address is acceptable, in which case the NAT engine will forward
15597 packets to the first DHCP lease (x.x.x.15).</desc>
15598 </param>
15599 <param name="guestPort" type="unsigned short" dir="in">
15600 <desc>The port number to forward.</desc>
15601 </param>
15602 </method>
15603 <method name="removeRedirect">
15604 <desc>Removes a port-forwarding rule that was previously registered.</desc>
15605 <param name="name" type="wstring" dir="in">
15606 <desc>The name of the rule to delete.</desc>
15607 </param>
15608 </method>
15609 </interface>
15610
15611 <!--
15612 // IExtPackManager
15613 /////////////////////////////////////////////////////////////////////////
15614 -->
15615
15616 <interface
15617 name="IExtPackPlugIn" extends="$unknown"
15618 uuid="58000040-e718-4746-bbce-4b86d96da461"
15619 wsmap="suppress"
15620 >
15621 <desc>
15622 Interface for keeping information about a plug-in that ships with an
15623 extension pack.
15624 </desc>
15625 <attribute name="name" type="wstring" readonly="yes">
15626 <desc>The plug-in name.</desc>
15627 </attribute>
15628 <attribute name="description" type="wstring" readonly="yes">
15629 <desc>The plug-in description.</desc>
15630 </attribute>
15631 <attribute name="frontend" type="wstring" readonly="yes">
15632 <desc>
15633 The name of the frontend or component name this plug-in plugs into.
15634 </desc>
15635 </attribute>
15636 <attribute name="modulePath" type="wstring" readonly="yes">
15637 <desc> The module path. </desc>
15638 </attribute>
15639 </interface>
15640
15641 <interface
15642 name="IExtPackBase" extends="$unknown"
15643 uuid="5ffb0b64-0ad6-467d-af62-1157e7dc3c99"
15644 wsmap="suppress"
15645 >
15646 <desc>
15647 Interface for querying information about an extension pack as well as
15648 accessing COM objects within it.
15649 </desc>
15650 <attribute name="name" type="wstring" readonly="yes">
15651 <desc>The extension pack name. This is unique.</desc>
15652 </attribute>
15653 <attribute name="description" type="wstring" readonly="yes">
15654 <desc>The extension pack description.</desc>
15655 </attribute>
15656 <attribute name="version" type="wstring" readonly="yes">
15657 <desc>
15658 The extension pack version string. This is on the same form as
15659 other VirtualBox version strings, i.e.: "1.2.3", "1.2.3_BETA1",
15660 "1.2.3-OSE", "1.2.3r45678", "1.2.3r45678-OSE", "1.2.3_BETA1-r45678"
15661 or "1.2.3_BETA1-r45678-OSE"
15662 </desc>
15663 </attribute>
15664 <attribute name="revision" type="unsigned long" readonly="yes">
15665 <desc>The extension pack internal revision number.</desc>
15666 </attribute>
15667 <attribute name="VRDEModule" type="wstring" readonly="yes">
15668 <desc>The name of the VRDE module if the extension pack sports one.</desc>
15669 </attribute>
15670 <attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes">
15671 <desc>Plug-ins provided by this extension pack.</desc>
15672 </attribute>
15673 <attribute name="usable" type="boolean" readonly="yes">
15674 <desc>
15675 Indicates whether the extension pack is usable or not.
15676
15677 There are a number of reasons why an extension pack might be unusable,
15678 typical examples would be broken installation/file or that it is
15679 incompatible with the current VirtualBox version.
15680 </desc>
15681 </attribute>
15682 <attribute name="whyUnusable" type="wstring" readonly="yes">
15683 <desc>
15684 String indicating why the extension pack is not usable. This is an
15685 empty string if usable and always a non-empty string if not usable.
15686 </desc>
15687 </attribute>
15688 <attribute name="showLicense" type="boolean" readonly="yes">
15689 <desc>Whether to show the license before installation</desc>
15690 </attribute>
15691 <attribute name="license" type="wstring" readonly="yes">
15692 <desc>
15693 The default HTML license text for the extension pack. Same as
15694 calling <link to="#queryLicense">queryLicense</link> with
15695 preferredLocale and preferredLanguage as empty strings and format set
15696 to html.
15697 </desc>
15698 </attribute>
15699
15700 <method name="queryLicense">
15701 <desc>
15702 Full feature version of the license attribute.
15703 </desc>
15704 <param name="preferredLocale" type="wstring" dir="in">
15705 <desc>
15706 The preferred license locale. Pass an empty string to get the default
15707 license.
15708 </desc>
15709 </param>
15710 <param name="preferredLanguage" type="wstring" dir="in">
15711 <desc>
15712 The preferred license language. Pass an empty string to get the
15713 default language for the locale.
15714 </desc>
15715 </param>
15716 <param name="format" type="wstring" dir="in">
15717 <desc>
15718 The license format: html, rtf or txt. If a license is present there
15719 will always be an HTML of it, the rich text format (RTF) and plain
15720 text (txt) versions are optional. If
15721 </desc>
15722 </param>
15723 <param name="licenseText" type="wstring" dir="return">
15724 <desc>The license text.</desc>
15725 </param>
15726 </method>
15727
15728 </interface>
15729
15730 <interface
15731 name="IExtPack" extends="IExtPackBase"
15732 uuid="431685da-3618-4ebc-b038-833ba829b4b2"
15733 wsmap="suppress"
15734 >
15735 <desc>
15736 Interface for querying information about an extension pack as well as
15737 accessing COM objects within it.
15738 </desc>
15739 <method name="queryObject">
15740 <desc>
15741 Queries the IUnknown interface to an object in the extension pack
15742 main module. This allows plug-ins and others to talk directly to an
15743 extension pack.
15744 </desc>
15745 <param name="objUuid" type="wstring" dir="in">
15746 <desc>The object ID. What exactly this is </desc>
15747 </param>
15748 <param name="returnInterface" type="$unknown" dir="return">
15749 <desc>The queried interface.</desc>
15750 </param>
15751 </method>
15752 </interface>
15753
15754 <interface
15755 name="IExtPackFile" extends="IExtPackBase"
15756 uuid="b6b49f55-efcc-4f08-b486-56e8d8afb10b"
15757 wsmap="suppress"
15758 >
15759 <desc>
15760 Extension pack file (aka tarball, .vbox-extpack) representation returned
15761 by <link to="IExtPackManager::openExtPackFile"/>. This provides the base
15762 extension pack information with the addition of the file name.
15763 </desc>
15764 <attribute name="filePath" type="wstring" readonly="yes">
15765 <desc>
15766 The path to the extension pack file.
15767 </desc>
15768 </attribute>
15769
15770 <method name="install">
15771 <desc>
15772 Install the extension pack.
15773 </desc>
15774 <param name="replace" type="boolean" dir="in">
15775 <desc>
15776 Set this to automatically uninstall any existing extension pack with
15777 the same name as the one being installed.
15778 </desc>
15779 </param>
15780 <param name="displayInfo" type="wstring" dir="in">
15781 <desc>
15782 Platform specific display information. Reserved for future hacks.
15783 </desc>
15784 </param>
15785 <param name="progess" type="IProgress" dir="return">
15786 <desc>
15787 Progress object for the operation.
15788 </desc>
15789 </param>
15790 </method>
15791 </interface>
15792
15793 <interface
15794 name="IExtPackManager" extends="$unknown"
15795 uuid="3295e6ce-b051-47b2-9514-2c588bfe7554"
15796 wsmap="suppress"
15797 >
15798 <desc>
15799 Interface for managing VirtualBox Extension Packs.
15800
15801 TODO: Describe extension packs, how they are managed and how to create
15802 one.
15803 </desc>
15804
15805 <attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
15806 <desc>
15807 List of the installed extension packs.
15808 </desc>
15809 </attribute>
15810
15811 <method name="find">
15812 <desc>
15813 Returns the extension pack with the specified name if found.
15814
15815 <result name="VBOX_E_OBJECT_NOT_FOUND">
15816 No extension pack matching @a name was found.
15817 </result>
15818 </desc>
15819 <param name="name" type="wstring" dir="in">
15820 <desc>The name of the extension pack to locate.</desc>
15821 </param>
15822 <param name="returnData" type="IExtPack" dir="return">
15823 <desc>The extension pack if found.</desc>
15824 </param>
15825 </method>
15826
15827 <method name="openExtPackFile">
15828 <desc>
15829 Attempts to open an extension pack file in preparation for
15830 installation.
15831 </desc>
15832 <param name="path" type="wstring" dir="in">
15833 <desc>The path of the extension pack tarball.</desc>
15834 </param>
15835 <param name="file" type="IExtPackFile" dir="return">
15836 <desc>The interface of the extension pack file object.</desc>
15837 </param>
15838 </method>
15839
15840 <method name="uninstall">
15841 <desc>Uninstalls an extension pack, removing all related files.</desc>
15842 <param name="name" type="wstring" dir="in">
15843 <desc>The name of the extension pack to uninstall.</desc>
15844 </param>
15845 <param name="forcedRemoval" type="boolean" dir="in">
15846 <desc>
15847 Forced removal of the extension pack. This means that the uninstall
15848 hook will not be called.
15849 </desc>
15850 </param>
15851 <param name="displayInfo" type="wstring" dir="in">
15852 <desc>
15853 Platform specific display information. Reserved for future hacks.
15854 </desc>
15855 </param>
15856 <param name="progess" type="IProgress" dir="return">
15857 <desc>
15858 Progress object for the operation.
15859 </desc>
15860 </param>
15861 </method>
15862
15863 <method name="cleanup">
15864 <desc>Cleans up failed installs and uninstalls</desc>
15865 </method>
15866
15867 <method name="queryAllPlugInsForFrontend">
15868 <desc>
15869 Gets the path to all the plug-in modules for a given frontend.
15870
15871 This is a convenience method that is intended to simplify the plug-in
15872 loading process for a frontend.
15873 </desc>
15874 <param name="frontendName" type="wstring" dir="in">
15875 <desc>The name of the frontend or component.</desc>
15876 </param>
15877 <param name="plugInModules" type="wstring" dir="return" safearray="yes">
15878 <desc>Array containing the plug-in modules (full paths).</desc>
15879 </param>
15880 </method>
15881
15882 <method name="isExtPackUsable">
15883 <desc>Check if the given extension pack is loaded and usable.</desc>
15884 <param name="name" type="wstring" dir="in">
15885 <desc>The name of the extension pack to check for.</desc>
15886 </param>
15887 <param name="usable" type="boolean" dir="return">
15888 <desc>Is the given extension pack loaded and usable.</desc>
15889 </param>
15890 </method>
15891
15892 </interface>
15893
15894 <!--
15895 // BandwidthGroupType
15896 /////////////////////////////////////////////////////////////////////////
15897 -->
15898 <enum
15899 name="BandwidthGroupType"
15900 uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e">
15901
15902 <desc>
15903 Type of a bandwidth control group.
15904 </desc>
15905
15906 <const name="Null" value="0">
15907 <desc>
15908 Null type, must be first.
15909 </desc>
15910 </const>
15911
15912 <const name="Disk" value="1">
15913 <desc>
15914 The bandwidth group controls disk I/O.
15915 </desc>
15916 </const>
15917
15918 <const name="Network" value="2">
15919 <desc>
15920 The bandwidth group controls network I/O.
15921 </desc>
15922 </const>
15923
15924 </enum>
15925
15926 <!--
15927 // IBandwidthGroup
15928 /////////////////////////////////////////////////////////////////////////
15929 -->
15930 <interface
15931 name="IBandwidthGroup" extends="$unknown"
15932 uuid="badea2d7-0261-4146-89f0-6a57cc34833d"
15933 wsmap="managed"
15934 >
15935 <desc>Represents one bandwidth group.</desc>
15936
15937 <attribute name="name" type="wstring" readonly="yes">
15938 <desc>Name of the group.</desc>
15939 </attribute>
15940
15941 <attribute name="type" type="BandwidthGroupType" readonly="yes">
15942 <desc>Type of the group.</desc>
15943 </attribute>
15944
15945 <attribute name="reference" type="unsigned long" readonly="yes">
15946 <desc>How many devices/medium attachements use this group.</desc>
15947 </attribute>
15948
15949 <attribute name="maxMbPerSec" type="unsigned long">
15950 <desc>The maximum number of MBytes which can be transfered by all
15951 entities attached to this group during one second.</desc>
15952 </attribute>
15953
15954 </interface>
15955
15956 <!--
15957 // IBandwidthControl
15958 /////////////////////////////////////////////////////////////////////////
15959 -->
15960 <interface
15961 name="IBandwidthControl" extends="$unknown"
15962 uuid="e2eb3930-d2f4-4f87-be17-0707e30f019f"
15963 wsmap="managed"
15964 >
15965 <desc>
15966 Controls the bandwidth groups of one machine used to cap I/O done by a VM.
15967 This includes network and disk I/O.
15968 </desc>
15969
15970 <attribute name="numGroups" type="unsigned long" readonly="yes">
15971 <desc>
15972 The current number of existing bandwidth groups managed.
15973 </desc>
15974 </attribute>
15975
15976 <method name="createBandwidthGroup">
15977 <desc>
15978 Creates a new bandwidth group.
15979 </desc>
15980
15981 <param name="name" type="wstring" dir="in">
15982 <desc>Name of the bandwidth group.</desc>
15983 </param>
15984 <param name="type" type="BandwidthGroupType" dir="in">
15985 <desc>The type of the bandwidth group (network or disk).</desc>
15986 </param>
15987 <param name="maxMbPerSec" type="unsigned long" dir="in">
15988 <desc>The maximum number of MBytes which can be transfered by all
15989 entities attached to this group during one second.</desc>
15990 </param>
15991 </method>
15992
15993 <method name="deleteBandwidthGroup">
15994 <desc>
15995 Deletes a new bandwidth group.
15996 </desc>
15997
15998 <param name="name" type="wstring" dir="in">
15999 <desc>Name of the bandwidth group to delete.</desc>
16000 </param>
16001 </method>
16002
16003 <method name="getBandwidthGroup" const="yes">
16004 <desc>
16005 Get a bandwidth group by name.
16006 </desc>
16007
16008 <param name="name" type="wstring" dir="in">
16009 <desc>Name of the bandwidth group to get.</desc>
16010 </param>
16011 <param name="bandwidthGroup" type="IBandwidthGroup" dir="return">
16012 <desc>Where to store the bandwidth group on success.</desc>
16013 </param>
16014 </method>
16015
16016 <method name="getAllBandwidthGroups" const="yes">
16017 <desc>
16018 Get all managed bandwidth groups.
16019 </desc>
16020
16021 <param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes">
16022 <desc>The array of managed bandwidth groups.</desc>
16023 </param>
16024 </method>
16025 </interface>
16026
16027 <!--
16028 // IVirtualBoxClient
16029 /////////////////////////////////////////////////////////////////////////
16030 -->
16031
16032 <interface
16033 name="IVirtualBoxClient" extends="$unknown"
16034 uuid="5fe0bd48-1181-40d1-991f-3b02f269a823"
16035 wsmap="suppress"
16036 >
16037 <desc>
16038 Convenience interface for client applications. Treat this as a
16039 singleton, i.e. never create more than one instance of this interface.
16040
16041 At the moment only available for clients of the local API (not usable
16042 via the webservice). Once the session logic is redesigned this might
16043 change.
16044 </desc>
16045
16046 <attribute name="virtualBox" type="IVirtualBox" readonly="yes">
16047 <desc>
16048 Reference to the server-side API root object.
16049 </desc>
16050 </attribute>
16051
16052 <attribute name="session" type="ISession" readonly="yes">
16053 <desc>
16054 Create a new session object and return the reference to it.
16055 </desc>
16056 </attribute>
16057
16058 <attribute name="eventSource" type="IEventSource" readonly="yes">
16059 <desc>
16060 Event source for VirtualBoxClient events.
16061 </desc>
16062 </attribute>
16063
16064 </interface>
16065
16066 <!--
16067 // Events
16068 /////////////////////////////////////////////////////////////////////////
16069 -->
16070 <enum
16071 name="VBoxEventType"
16072 uuid="cce48db6-8561-479d-8d46-1358bab45d4e"
16073 >
16074
16075 <desc>
16076 Type of an event.
16077 See <link to="IEvent" /> for an introduction to VirtualBox event handling.
16078 </desc>
16079
16080 <const name="Invalid" value="0">
16081 <desc>
16082 Invalid event, must be first.
16083 </desc>
16084 </const>
16085
16086 <const name="Any" value="1">
16087 <desc>
16088 Wildcard for all events.
16089 Events of this type are never delivered, and only used in
16090 <link to="IEventSource::registerListener"/> call to simplify registration.
16091 </desc>
16092 </const>
16093
16094 <const name="Vetoable" value="2">
16095 <desc>
16096 Wildcard for all vetoable events. Events of this type are never delivered, and only
16097 used in <link to="IEventSource::registerListener"/> call to simplify registration.
16098 </desc>
16099 </const>
16100
16101 <const name="MachineEvent" value="3">
16102 <desc>
16103 Wildcard for all machine events. Events of this type are never delivered, and only used in
16104 <link to="IEventSource::registerListener"/> call to simplify registration.
16105 </desc>
16106 </const>
16107
16108 <const name="SnapshotEvent" value="4">
16109 <desc>
16110 Wildcard for all snapshot events. Events of this type are never delivered, and only used in
16111 <link to="IEventSource::registerListener"/> call to simplify registration.
16112 </desc>
16113 </const>
16114
16115 <const name="InputEvent" value="5">
16116 <desc>
16117 Wildcard for all input device (keyboard, mouse) events.
16118 Events of this type are never delivered, and only used in
16119 <link to="IEventSource::registerListener"/> call to simplify registration.
16120 </desc>
16121 </const>
16122
16123 <const name="LastWildcard" value="31">
16124 <desc>
16125 Last wildcard.
16126 </desc>
16127 </const>
16128
16129 <const name="OnMachineStateChanged" value="32">
16130 <desc>
16131 See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
16132 </desc>
16133 </const>
16134 <const name="OnMachineDataChanged" value="33">
16135 <desc>
16136 See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
16137 </desc>
16138 </const>
16139 <const name="OnExtraDataChanged" value="34">
16140 <desc>
16141 See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
16142 </desc>
16143 </const>
16144 <const name="OnExtraDataCanChange" value="35">
16145 <desc>
16146 See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
16147 </desc>
16148 </const>
16149 <const name="OnMediumRegistered" value="36">
16150 <desc>
16151 See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
16152 </desc>
16153 </const>
16154 <const name="OnMachineRegistered" value="37">
16155 <desc>
16156 See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
16157 </desc>
16158 </const>
16159 <const name="OnSessionStateChanged" value="38">
16160 <desc>
16161 See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
16162 </desc>
16163 </const>
16164 <const name="OnSnapshotTaken" value="39">
16165 <desc>
16166 See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
16167 </desc>
16168 </const>
16169 <const name="OnSnapshotDeleted" value="40">
16170 <desc>
16171 See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
16172 </desc>
16173 </const>
16174 <const name="OnSnapshotChanged" value="41">
16175 <desc>
16176 See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
16177 </desc>
16178 </const>
16179 <const name="OnGuestPropertyChanged" value="42">
16180 <desc>
16181 See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
16182 </desc>
16183 </const>
16184 <!-- Console events -->
16185 <const name="OnMousePointerShapeChanged" value="43">
16186 <desc>
16187 See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
16188 </desc>
16189 </const>
16190 <const name="OnMouseCapabilityChanged" value="44">
16191 <desc>
16192 See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
16193 </desc>
16194 </const>
16195 <const name="OnKeyboardLedsChanged" value="45">
16196 <desc>
16197 See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
16198 </desc>
16199 </const>
16200 <const name="OnStateChanged" value="46">
16201 <desc>
16202 See <link to="IStateChangedEvent">IStateChangedEvent</link>.
16203 </desc>
16204 </const>
16205 <const name="OnAdditionsStateChanged" value="47">
16206 <desc>
16207 See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
16208 </desc>
16209 </const>
16210 <const name="OnNetworkAdapterChanged" value="48">
16211 <desc>
16212 See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
16213 </desc>
16214 </const>
16215 <const name="OnSerialPortChanged" value="49">
16216 <desc>
16217 See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
16218 </desc>
16219 </const>
16220 <const name="OnParallelPortChanged" value="50">
16221 <desc>
16222 See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
16223 </desc>
16224 </const>
16225 <const name="OnStorageControllerChanged" value="51">
16226 <desc>
16227 See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
16228 </desc>
16229 </const>
16230 <const name="OnMediumChanged" value="52">
16231 <desc>
16232 See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
16233 </desc>
16234 </const>
16235 <const name="OnVRDEServerChanged" value="53">
16236 <desc>
16237 See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
16238 </desc>
16239 </const>
16240 <const name="OnUSBControllerChanged" value="54">
16241 <desc>
16242 See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
16243 </desc>
16244 </const>
16245 <const name="OnUSBDeviceStateChanged" value="55">
16246 <desc>
16247 See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
16248 </desc>
16249 </const>
16250 <const name="OnSharedFolderChanged" value="56">
16251 <desc>
16252 See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
16253 </desc>
16254 </const>
16255 <const name="OnRuntimeError" value="57">
16256 <desc>
16257 See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
16258 </desc>
16259 </const>
16260 <const name="OnCanShowWindow" value="58">
16261 <desc>
16262 See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
16263 </desc>
16264 </const>
16265 <const name="OnShowWindow" value="59">
16266 <desc>
16267 See <link to="IShowWindowEvent">IShowWindowEvent</link>.
16268 </desc>
16269 </const>
16270 <const name="OnCPUChanged" value="60">
16271 <desc>
16272 See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
16273 </desc>
16274 </const>
16275 <const name="OnVRDEServerInfoChanged" value="61">
16276 <desc>
16277 See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
16278 </desc>
16279 </const>
16280 <const name="OnEventSourceChanged" value="62">
16281 <desc>
16282 See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
16283 </desc>
16284 </const>
16285 <const name="OnCPUExecutionCapChanged" value="63">
16286 <desc>
16287 See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
16288 </desc>
16289 </const>
16290 <const name="OnGuestKeyboard" value="64">
16291 <desc>
16292 See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
16293 </desc>
16294 </const>
16295 <const name="OnGuestMouse" value="65">
16296 <desc>
16297 See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
16298 </desc>
16299 </const>
16300 <const name="OnNATRedirect" value="66">
16301 <desc>
16302 See <link to="INATRedirectEvent">INATRedirectEvent</link>.
16303 </desc>
16304 </const>
16305 <const name="OnHostPciDevicePlug" value="67">
16306 <desc>
16307 See <link to="IHostPciDevicePlugEvent">IHostPciDevicePlugEvent</link>.
16308 </desc>
16309 </const>
16310 <const name="OnVBoxSVCAvailabilityChanged" value="68">
16311 <desc>
16312 See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>.
16313 </desc>
16314 </const>
16315 <const name="OnBandwidthGroupChanged" value="69">
16316 <desc>
16317 See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>.
16318 </desc>
16319 </const>
16320 <const name="OnGuestMonitorChanged" value="70">
16321 <desc>
16322 See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>.
16323 </desc>
16324 </const>
16325 <const name="OnStorageDeviceChanged" value="71">
16326 <desc>
16327 See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>.
16328 </desc>
16329 </const>
16330
16331 <!-- Last event marker -->
16332 <const name="Last" value="72">
16333 <desc>
16334 Must be last event, used for iterations and structures relying on numerical event values.
16335 </desc>
16336 </const>
16337
16338 </enum>
16339
16340 <interface
16341 name="IEventSource" extends="$unknown"
16342 uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
16343 wsmap="managed"
16344 >
16345 <desc>
16346 Event source. Generally, any object which could generate events can be an event source,
16347 or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
16348 an event source can work with listeners in either active or passive mode. In active mode it is up to
16349 the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
16350 event source keeps track of pending events for each listener and returns available events on demand.
16351
16352 See <link to="IEvent" /> for an introduction to VirtualBox event handling.
16353 </desc>
16354
16355 <method name="createListener">
16356 <desc>
16357 Creates a new listener object, useful for passive mode.
16358 </desc>
16359 <param name="listener" type="IEventListener" dir="return"/>
16360 </method>
16361
16362 <method name="createAggregator">
16363 <desc>
16364 Creates an aggregator event source, collecting events from multiple sources.
16365 This way a single listener can listen for events coming from multiple sources,
16366 using a single blocking <link to="#getEvent"/> on the returned aggregator.
16367 </desc>
16368 <param name="subordinates" type="IEventSource" dir="in" safearray="yes">
16369 <desc>
16370 Subordinate event source this one aggregatres.
16371 </desc>
16372 </param>
16373 <param name="result" type="IEventSource" dir="return">
16374 <desc>
16375 Event source aggregating passed sources.
16376 </desc>
16377 </param>
16378 </method>
16379
16380 <method name="registerListener">
16381 <desc>
16382 Register an event listener.
16383
16384 <note>
16385 To avoid system overload, the VirtualBox server process checks if passive event
16386 listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
16387 current implementation, if more than 500 pending events are detected for a passive
16388 event listener, it is forcefully unregistered by the system, and further
16389 <link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
16390 </note>
16391 </desc>
16392 <param name="listener" type="IEventListener" dir="in">
16393 <desc>Listener to register.</desc>
16394 </param>
16395 <param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
16396 <desc>
16397 Event types listener is interested in. One can use wildcards like -
16398 <link to="VBoxEventType_Any"/> to specify wildcards, matching more
16399 than one event.
16400 </desc>
16401 </param>
16402 <param name="active" type="boolean" dir="in">
16403 <desc>
16404 Which mode this listener is operating in.
16405 In active mode, <link to="IEventListener::handleEvent" /> is called directly.
16406 In passive mode, an internal event queue is created for this this IEventListener.
16407 For each event coming in, it is added to queues for all interested registered passive
16408 listeners. It is then up to the external code to call the listener's
16409 <link to="IEventListener::handleEvent" /> method. When done with an event, the
16410 external code must call <link to="#eventProcessed" />.
16411 </desc>
16412 </param>
16413 </method>
16414
16415 <method name="unregisterListener">
16416 <desc>
16417 Unregister an event listener. If listener is passive, and some waitable events are still
16418 in queue they are marked as processed automatically.
16419 </desc>
16420 <param name="listener" type="IEventListener" dir="in">
16421 <desc>Listener to unregister.</desc>
16422 </param>
16423 </method>
16424
16425 <method name="fireEvent">
16426 <desc>
16427 Fire an event for this source.
16428 </desc>
16429 <param name="event" type="IEvent" dir="in">
16430 <desc>Event to deliver.</desc>
16431 </param>
16432 <param name="timeout" type="long" dir="in">
16433 <desc>
16434 Maximum time to wait for event processing (if event is waitable), in ms;
16435 0 = no wait, -1 = indefinite wait.
16436 </desc>
16437 </param>
16438 <param name="result" type="boolean" dir="return">
16439 <desc>true if an event was delivered to all targets, or is non-waitable.</desc>
16440 </param>
16441 </method>
16442
16443 <method name="getEvent">
16444 <desc>
16445 Get events from this peer's event queue (for passive mode). Calling this method
16446 regularly is required for passive event listeners to avoid system overload;
16447 see <link to="IEventSource::registerListener" /> for details.
16448
16449 <result name="VBOX_E_OBJECT_NOT_FOUND">
16450 Listener is not registered, or autounregistered.
16451 </result>
16452 </desc>
16453 <param name="listener" type="IEventListener" dir="in">
16454 <desc>Which listener to get data for.</desc>
16455 </param>
16456 <param name="timeout" type="long" dir="in">
16457 <desc>
16458 Maximum time to wait for events, in ms;
16459 0 = no wait, -1 = indefinite wait.
16460 </desc>
16461 </param>
16462 <param name="event" type="IEvent" dir="return">
16463 <desc>Event retrieved, or null if none available.</desc>
16464 </param>
16465 </method>
16466
16467 <method name="eventProcessed">
16468 <desc>
16469 Must be called for waitable events after a particular listener finished its
16470 event processing. When all listeners of a particular event have called this
16471 method, the system will then call <link to="IEvent::setProcessed" />.
16472 </desc>
16473 <param name="listener" type="IEventListener" dir="in">
16474 <desc>Which listener processed event.</desc>
16475 </param>
16476 <param name="event" type="IEvent" dir="in">
16477 <desc>Which event.</desc>
16478 </param>
16479 </method>
16480
16481 </interface>
16482
16483 <interface
16484 name="IEventListener" extends="$unknown"
16485 uuid="67099191-32e7-4f6c-85ee-422304c71b90"
16486 wsmap="managed"
16487 >
16488 <desc>
16489 Event listener. An event listener can work in either active or passive mode, depending on the way
16490 it was registered.
16491 See <link to="IEvent" /> for an introduction to VirtualBox event handling.
16492 </desc>
16493
16494 <method name="handleEvent">
16495 <desc>
16496 Handle event callback for active listeners. It is not called for
16497 passive listeners. After calling <link to="#handleEvent"/> on all active listeners
16498 and having received acknowledgement from all passive listeners via
16499 <link to="IEventSource::eventProcessed"/>, the event is marked as
16500 processed and <link to="IEvent::waitProcessed"/> will return
16501 immediately.
16502 </desc>
16503 <param name="event" type="IEvent" dir="in">
16504 <desc>Event available.</desc>
16505 </param>
16506 </method>
16507
16508 </interface>
16509
16510 <interface
16511 name="IEvent" extends="$unknown"
16512 uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
16513 wsmap="managed"
16514 >
16515 <desc>
16516 Abstract parent interface for VirtualBox events. Actual events will typically implement
16517 a more specific interface which derives from this (see below).
16518
16519 <b>Introduction to VirtualBox events</b>
16520
16521 Generally speaking, an event (represented by this interface) signals that something
16522 happened, while an event listener (see <link to="IEventListener" />) represents an
16523 entity that is interested in certain events. In order for this to work with
16524 unidirectional protocols (i.e. web services), the concepts of passive and active
16525 listener are used.
16526
16527 Event consumers can register themselves as listeners, providing an array of
16528 events they are interested in (see <link to="IEventSource::registerListener" />).
16529 When an event triggers, the listener is notified about the event. The exact
16530 mechanism of the notification depends on whether the listener was registered as
16531 an active or passive listener:
16532
16533 <ul>
16534 <li>An active listener is very similar to a callback: it is a function invoked
16535 by the API. As opposed to the callbacks that were used in the API before
16536 VirtualBox 4.0 however, events are now objects with an interface hierarchy.
16537 </li>
16538
16539 <li>Passive listeners are somewhat trickier to implement, but do not require
16540 a client function to be callable, which is not an option with scripting
16541 languages or web service clients. Internally the <link to="IEventSource" />
16542 implementation maintains an event queue for each passive listener, and
16543 newly arrived events are put in this queue. When the listener calls
16544 <link to="IEventSource::getEvent"/>, first element from its internal event
16545 queue is returned. When the client completes processing of an event,
16546 the <link to="IEventSource::eventProcessed" /> function must be called,
16547 acknowledging that the event was processed. It supports implementing
16548 waitable events. On passive listener unregistration, all events from its
16549 queue are auto-acknowledged.
16550 </li>
16551 </ul>
16552
16553 Waitable events are useful in situations where the event generator wants to track
16554 delivery or a party wants to wait until all listeners have completed the event. A
16555 typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
16556 listeners might veto a certain action, and thus the event producer has to make
16557 sure that all listeners have processed the event and not vetoed before taking
16558 the action.
16559
16560 A given event may have both passive and active listeners at the same time.
16561
16562 <b>Using events</b>
16563
16564 Any VirtualBox object capable of producing externally visible events provides an
16565 @c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
16566 This event source object is notified by VirtualBox once something has happened, so
16567 consumers may register event listeners with this event source. To register a listener,
16568 an object implementing the <link to="IEventListener" /> interface must be provided.
16569 For active listeners, such an object is typically created by the consumer, while for
16570 passive listeners <link to="IEventSource::createListener" /> should be used. Please
16571 note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener.
16572
16573 Once created, the listener must be registered to listen for the desired events
16574 (see <link to="IEventSource::registerListener" />), providing an array of
16575 <link to="VBoxEventType" /> enums. Those elements can either be the individual
16576 event IDs or wildcards matching multiple event IDs.
16577
16578 After registration, the callback's <link to="IEventListener::handleEvent" /> method is
16579 called automatically when the event is triggered, while passive listeners have to call
16580 <link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
16581 an event processing loop.
16582
16583 The IEvent interface is an abstract parent interface for all such VirtualBox events
16584 coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
16585 or the event processing loop is to check the <link to="#type" /> attribute of the event and
16586 then cast to the appropriate specific interface using @c QueryInterface().
16587 </desc>
16588
16589 <attribute name="type" readonly="yes" type="VBoxEventType">
16590 <desc>
16591 Event type.
16592 </desc>
16593 </attribute>
16594
16595 <attribute name="source" readonly="yes" type="IEventSource">
16596 <desc>
16597 Source of this event.
16598 </desc>
16599 </attribute>
16600
16601 <attribute name="waitable" readonly="yes" type="boolean">
16602 <desc>
16603 If we can wait for this event being processed. If false, <link to="#waitProcessed"/> returns immediately,
16604 and <link to="#setProcessed"/> doesn't make sense. Non-waitable events are generally better performing,
16605 as no additional overhead associated with waitability imposed.
16606 Waitable events are needed when one need to be able to wait for particular event processed,
16607 for example for vetoable changes, or if event refers to some resource which need to be kept immutable
16608 until all consumers confirmed events.
16609 </desc>
16610 </attribute>
16611
16612 <method name="setProcessed">
16613 <desc>
16614 Internal method called by the system when all listeners of a particular event have called
16615 <link to="IEventSource::eventProcessed" />. This should not be called by client code.
16616 </desc>
16617 </method>
16618
16619 <method name="waitProcessed">
16620 <desc>
16621 Wait until time outs, or this event is processed. Event must be waitable for this operation to have
16622 described semantics, for non-waitable returns true immediately.
16623 </desc>
16624 <param name="timeout" type="long" dir="in">
16625 <desc>
16626 Maximum time to wait for event processeing, in ms;
16627 0 = no wait, -1 = indefinite wait.
16628 </desc>
16629 </param>
16630 <param name="result" type="boolean" dir="return">
16631 <desc>If this event was processed before timeout.</desc>
16632 </param>
16633 </method>
16634 </interface>
16635
16636
16637 <interface
16638 name="IReusableEvent" extends="IEvent"
16639 uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
16640 wsmap="managed"
16641 >
16642 <desc>Base abstract interface for all reusable events.</desc>
16643
16644 <attribute name="generation" readonly="yes" type="unsigned long">
16645 <desc>Current generation of event, incremented on reuse.</desc>
16646 </attribute>
16647
16648 <method name="reuse">
16649 <desc>
16650 Marks an event as reused, increments 'generation', fields shall no
16651 longer be considered valid.
16652 </desc>
16653 </method>
16654 </interface>
16655
16656 <interface
16657 name="IMachineEvent" extends="IEvent"
16658 uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
16659 wsmap="managed" id="MachineEvent"
16660 >
16661 <desc>Base abstract interface for all machine events.</desc>
16662
16663 <attribute name="machineId" readonly="yes" type="uuid" mod="string">
16664 <desc>ID of the machine this event relates to.</desc>
16665 </attribute>
16666
16667 </interface>
16668
16669 <interface
16670 name="IMachineStateChangedEvent" extends="IMachineEvent"
16671 uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
16672 wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
16673 >
16674 <desc>Machine state change event.</desc>
16675
16676 <attribute name="state" readonly="yes" type="MachineState">
16677 <desc>New execution state.</desc>
16678 </attribute>
16679 </interface>
16680
16681 <interface
16682 name="IMachineDataChangedEvent" extends="IMachineEvent"
16683 uuid="abe94809-2e88-4436-83d7-50f3e64d0503"
16684 wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
16685 >
16686 <desc>
16687 Any of the settings of the given machine has changed.
16688 </desc>
16689
16690 <attribute name="temporary" readonly="yes" type="boolean">
16691 <desc>@c true if the settings change is temporary. All permanent
16692 settings changes will trigger an event, and only temporary settings
16693 changes for running VMs will trigger an event. Note: sending events
16694 for temporary changes is NOT IMPLEMENTED.</desc>
16695 </attribute>
16696 </interface>
16697
16698 <interface
16699 name="IMediumRegisteredEvent" extends="IEvent"
16700 uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
16701 wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
16702 >
16703 <desc>
16704 The given medium was registered or unregistered
16705 within this VirtualBox installation.
16706 </desc>
16707
16708 <attribute name="mediumId" readonly="yes" type="uuid" mod="string">
16709 <desc>ID of the medium this event relates to.</desc>
16710 </attribute>
16711
16712 <attribute name="mediumType" readonly="yes" type="DeviceType">
16713 <desc>Type of the medium this event relates to.</desc>
16714 </attribute>
16715
16716 <attribute name="registered" type="boolean" readonly="yes">
16717 <desc>
16718 If @c true, the medium was registered, otherwise it was
16719 unregistered.
16720 </desc>
16721 </attribute>
16722 </interface>
16723
16724 <interface
16725 name="IMachineRegisteredEvent" extends="IMachineEvent"
16726 uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
16727 wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
16728 >
16729 <desc>
16730 The given machine was registered or unregistered
16731 within this VirtualBox installation.
16732 </desc>
16733
16734 <attribute name="registered" type="boolean" readonly="yes">
16735 <desc>
16736 If @c true, the machine was registered, otherwise it was
16737 unregistered.
16738 </desc>
16739 </attribute>
16740 </interface>
16741
16742 <interface
16743 name="ISessionStateChangedEvent" extends="IMachineEvent"
16744 uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
16745 wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
16746 >
16747 <desc>
16748 The state of the session for the given machine was changed.
16749 <see><link to="IMachine::sessionState"/></see>
16750 </desc>
16751
16752 <attribute name="state" type="SessionState" readonly="yes">
16753 <desc>
16754 New session state.
16755 </desc>
16756 </attribute>
16757 </interface>
16758
16759 <interface
16760 name="IGuestPropertyChangedEvent" extends="IMachineEvent"
16761 uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
16762 wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
16763 >
16764 <desc>
16765 Notification when a guest property has changed.
16766 </desc>
16767
16768 <attribute name="name" readonly="yes" type="wstring">
16769 <desc>
16770 The name of the property that has changed.
16771 </desc>
16772 </attribute>
16773
16774 <attribute name="value" readonly="yes" type="wstring">
16775 <desc>
16776 The new property value.
16777 </desc>
16778 </attribute>
16779
16780 <attribute name="flags" readonly="yes" type="wstring">
16781 <desc>
16782 The new property flags.
16783 </desc>
16784 </attribute>
16785
16786 </interface>
16787
16788 <interface
16789 name="ISnapshotEvent" extends="IMachineEvent"
16790 uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
16791 wsmap="managed" id="SnapshotEvent"
16792 >
16793 <desc>Base interface for all snapshot events.</desc>
16794
16795 <attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
16796 <desc>ID of the snapshot this event relates to.</desc>
16797 </attribute>
16798
16799 </interface>
16800
16801 <interface
16802 name="ISnapshotTakenEvent" extends="ISnapshotEvent"
16803 uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
16804 wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
16805 >
16806 <desc>
16807 A new snapshot of the machine has been taken.
16808 <see><link to="ISnapshot"/></see>
16809 </desc>
16810 </interface>
16811
16812 <interface
16813 name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
16814 uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
16815 wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
16816 >
16817 <desc>
16818 Snapshot of the given machine has been deleted.
16819
16820 <note>
16821 This notification is delivered <b>after</b> the snapshot
16822 object has been uninitialized on the server (so that any
16823 attempt to call its methods will return an error).
16824 </note>
16825
16826 <see><link to="ISnapshot"/></see>
16827 </desc>
16828 </interface>
16829
16830 <interface
16831 name="ISnapshotChangedEvent" extends="ISnapshotEvent"
16832 uuid="07541941-8079-447a-a33e-47a69c7980db"
16833 wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
16834 >
16835 <desc>
16836 Snapshot properties (name and/or description) have been changed.
16837 <see><link to="ISnapshot"/></see>
16838 </desc>
16839 </interface>
16840
16841 <interface
16842 name="IMousePointerShapeChangedEvent" extends="IEvent"
16843 uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
16844 wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
16845 >
16846 <desc>
16847 Notification when the guest mouse pointer shape has
16848 changed. The new shape data is given.
16849 </desc>
16850
16851 <attribute name="visible" type="boolean" readonly="yes">
16852 <desc>
16853 Flag whether the pointer is visible.
16854 </desc>
16855 </attribute>
16856 <attribute name="alpha" type="boolean" readonly="yes">
16857 <desc>
16858 Flag whether the pointer has an alpha channel.
16859 </desc>
16860 </attribute>
16861 <attribute name="xhot" type="unsigned long" readonly="yes">
16862 <desc>
16863 The pointer hot spot X coordinate.
16864 </desc>
16865 </attribute>
16866 <attribute name="yhot" type="unsigned long" readonly="yes">
16867 <desc>
16868 The pointer hot spot Y coordinate.
16869 </desc>
16870 </attribute>
16871 <attribute name="width" type="unsigned long" readonly="yes">
16872 <desc>
16873 Width of the pointer shape in pixels.
16874 </desc>
16875 </attribute>
16876 <attribute name="height" type="unsigned long" readonly="yes">
16877 <desc>
16878 Height of the pointer shape in pixels.
16879 </desc>
16880 </attribute>
16881 <attribute name="shape" type="octet" safearray="yes" readonly="yes">
16882 <desc>
16883 Shape buffer arrays.
16884
16885 The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
16886 followed by a 32-bpp XOR (color) mask.
16887
16888 For pointers without alpha channel the XOR mask pixels are 32
16889 bit values: (lsb)BGR0(msb). For pointers with alpha channel
16890 the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
16891
16892 An AND mask is used for pointers with alpha channel, so if the
16893 callback does not support alpha, the pointer could be
16894 displayed as a normal color pointer.
16895
16896 The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
16897 size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
16898 height</tt>. The padding bits at the end of each scanline are
16899 undefined.
16900
16901 The XOR mask follows the AND mask on the next 4-byte aligned
16902 offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>.
16903 Bytes in the gap between the AND and the XOR mask are undefined.
16904 The XOR mask scanlines have no gap between them and the size of
16905 the XOR mask is: <tt>cXor = width * 4 * height</tt>.
16906
16907 <note>
16908 If @a shape is 0, only the pointer visibility is changed.
16909 </note>
16910 </desc>
16911 </attribute>
16912 </interface>
16913
16914 <interface
16915 name="IMouseCapabilityChangedEvent" extends="IEvent"
16916 uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
16917 wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
16918 >
16919 <desc>
16920 Notification when the mouse capabilities reported by the
16921 guest have changed. The new capabilities are passed.
16922 </desc>
16923 <attribute name="supportsAbsolute" type="boolean" readonly="yes">
16924 <desc>
16925 Supports absolute coordinates.
16926 </desc>
16927 </attribute>
16928 <attribute name="supportsRelative" type="boolean" readonly="yes">
16929 <desc>
16930 Supports relative coordinates.
16931 </desc>
16932 </attribute>
16933 <attribute name="needsHostCursor" type="boolean" readonly="yes">
16934 <desc>
16935 If host cursor is needed.
16936 </desc>
16937 </attribute>
16938 </interface>
16939
16940 <interface
16941 name="IKeyboardLedsChangedEvent" extends="IEvent"
16942 uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
16943 wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
16944 >
16945 <desc>
16946 Notification when the guest OS executes the KBD_CMD_SET_LEDS command
16947 to alter the state of the keyboard LEDs.
16948 </desc>
16949 <attribute name="numLock" type="boolean" readonly="yes">
16950 <desc>
16951 NumLock status.
16952 </desc>
16953 </attribute>
16954 <attribute name="capsLock" type="boolean" readonly="yes">
16955 <desc>
16956 CapsLock status.
16957 </desc>
16958 </attribute>
16959 <attribute name="scrollLock" type="boolean" readonly="yes">
16960 <desc>
16961 ScrollLock status.
16962 </desc>
16963 </attribute>
16964 </interface>
16965
16966 <interface
16967 name="IStateChangedEvent" extends="IEvent"
16968 uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
16969 wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
16970 >
16971 <desc>
16972 Notification when the execution state of the machine has changed.
16973 The new state is given.
16974 </desc>
16975 <attribute name="state" type="MachineState" readonly="yes">
16976 <desc>
16977 New machine state.
16978 </desc>
16979 </attribute>
16980 </interface>
16981
16982 <interface
16983 name="IAdditionsStateChangedEvent" extends="IEvent"
16984 uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
16985 wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
16986 >
16987 <desc>
16988 Notification when a Guest Additions property changes.
16989 Interested callees should query IGuest attributes to
16990 find out what has changed.
16991 </desc>
16992 </interface>
16993
16994 <interface
16995 name="INetworkAdapterChangedEvent" extends="IEvent"
16996 uuid="08889892-1EC6-4883-801D-77F56CFD0103"
16997 wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
16998 >
16999 <desc>
17000 Notification when a property of one of the
17001 virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
17002 changes. Interested callees should use INetworkAdapter methods and
17003 attributes to find out what has changed.
17004 </desc>
17005 <attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
17006 <desc>
17007 Network adapter that is subject to change.
17008 </desc>
17009 </attribute>
17010 </interface>
17011
17012 <interface
17013 name="ISerialPortChangedEvent" extends="IEvent"
17014 uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
17015 wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
17016 >
17017 <desc>
17018 Notification when a property of one of the
17019 virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
17020 Interested callees should use ISerialPort methods and attributes
17021 to find out what has changed.
17022 </desc>
17023 <attribute name="serialPort" type="ISerialPort" readonly="yes">
17024 <desc>
17025 Serial port that is subject to change.
17026 </desc>
17027 </attribute>
17028 </interface>
17029
17030 <interface
17031 name="IParallelPortChangedEvent" extends="IEvent"
17032 uuid="813C99FC-9849-4F47-813E-24A75DC85615"
17033 wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
17034 >
17035 <desc>
17036 Notification when a property of one of the
17037 virtual <link to="IMachine::getParallelPort">parallel ports</link>
17038 changes. Interested callees should use ISerialPort methods and
17039 attributes to find out what has changed.
17040 </desc>
17041 <attribute name="parallelPort" type="IParallelPort" readonly="yes">
17042 <desc>
17043 Parallel port that is subject to change.
17044 </desc>
17045 </attribute>
17046 </interface>
17047
17048 <interface
17049 name="IStorageControllerChangedEvent" extends="IEvent"
17050 uuid="715212BF-DA59-426E-8230-3831FAA52C56"
17051 wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
17052 >
17053 <desc>
17054 Notification when a
17055 <link to="IMachine::mediumAttachments">medium attachment</link>
17056 changes.
17057 </desc>
17058 </interface>
17059
17060 <interface
17061 name="IMediumChangedEvent" extends="IEvent"
17062 uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
17063 wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
17064 >
17065 <desc>
17066 Notification when a
17067 <link to="IMachine::mediumAttachments">medium attachment</link>
17068 changes.
17069 </desc>
17070 <attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
17071 <desc>
17072 Medium attachment that is subject to change.
17073 </desc>
17074 </attribute>
17075 </interface>
17076
17077 <interface
17078 name="ICPUChangedEvent" extends="IEvent"
17079 uuid="D0F0BECC-EE17-4D17-A8CC-383B0EB55E9D"
17080 wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
17081 >
17082 <desc>
17083 Notification when a CPU changes.
17084 </desc>
17085 <attribute name="cpu" type="unsigned long" readonly="yes">
17086 <desc>
17087 The CPU which changed.
17088 </desc>
17089 </attribute>
17090 <attribute name="add" type="boolean" readonly="yes">
17091 <desc>
17092 Flag whether the CPU was added or removed.
17093 </desc>
17094 </attribute>
17095 </interface>
17096
17097 <interface
17098 name="ICPUExecutionCapChangedEvent" extends="IEvent"
17099 uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
17100 wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
17101 >
17102 <desc>
17103 Notification when the CPU execution cap changes.
17104 </desc>
17105 <attribute name="executionCap" type="unsigned long" readonly="yes">
17106 <desc>
17107 The new CPU execution cap value. (1-100)
17108 </desc>
17109 </attribute>
17110 </interface>
17111
17112 <interface
17113 name="IGuestKeyboardEvent" extends="IEvent"
17114 uuid="88394258-7006-40d4-b339-472ee3801844"
17115 wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard"
17116 >
17117 <desc>
17118 Notification when guest keyboard event happens.
17119 </desc>
17120 <attribute name="scancodes" type="long" safearray="yes" readonly="yes">
17121 <desc>
17122 Array of scancodes.
17123 </desc>
17124 </attribute>
17125 </interface>
17126
17127 <interface
17128 name="IGuestMouseEvent" extends="IReusableEvent"
17129 uuid="1f85d35c-c524-40ff-8e98-307000df0992"
17130 wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse"
17131 >
17132 <desc>
17133 Notification when guest mouse event happens.
17134 </desc>
17135
17136 <attribute name="absolute" type="boolean" readonly="yes">
17137 <desc>
17138 If this event is relative or absolute.
17139 </desc>
17140 </attribute>
17141
17142 <attribute name="x" type="long" readonly="yes">
17143 <desc>
17144 New X position, or X delta.
17145 </desc>
17146 </attribute>
17147
17148 <attribute name="y" type="long" readonly="yes">
17149 <desc>
17150 New Y position, or Y delta.
17151 </desc>
17152 </attribute>
17153
17154 <attribute name="z" type="long" readonly="yes">
17155 <desc>
17156 Z delta.
17157 </desc>
17158 </attribute>
17159
17160 <attribute name="w" type="long" readonly="yes">
17161 <desc>
17162 W delta.
17163 </desc>
17164 </attribute>
17165
17166 <attribute name="buttons" type="long" readonly="yes">
17167 <desc>
17168 Button state bitmask.
17169 </desc>
17170 </attribute>
17171
17172 </interface>
17173
17174
17175 <interface
17176 name="IVRDEServerChangedEvent" extends="IEvent"
17177 uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
17178 wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
17179 >
17180 <desc>
17181 Notification when a property of the
17182 <link to="IMachine::VRDEServer">VRDE server</link> changes.
17183 Interested callees should use IVRDEServer methods and attributes to
17184 find out what has changed.
17185 </desc>
17186 </interface>
17187
17188 <interface
17189 name="IVRDEServerInfoChangedEvent" extends="IEvent"
17190 uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
17191 wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
17192 >
17193 <desc>
17194 Notification when the status of the VRDE server changes. Interested callees
17195 should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
17196 attributes to find out what is the current status.
17197 </desc>
17198 </interface>
17199
17200 <interface
17201 name="IUSBControllerChangedEvent" extends="IEvent"
17202 uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
17203 wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
17204 >
17205 <desc>
17206 Notification when a property of the virtual
17207 <link to="IMachine::USBController">USB controller</link> changes.
17208 Interested callees should use IUSBController methods and attributes to
17209 find out what has changed.
17210 </desc>
17211 </interface>
17212
17213 <interface
17214 name="IUSBDeviceStateChangedEvent" extends="IEvent"
17215 uuid="806da61b-6679-422a-b629-51b06b0c6d93"
17216 wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
17217 >
17218 <desc>
17219 Notification when a USB device is attached to or detached from
17220 the virtual USB controller.
17221
17222 This notification is sent as a result of the indirect
17223 request to attach the device because it matches one of the
17224 machine USB filters, or as a result of the direct request
17225 issued by <link to="IConsole::attachUSBDevice"/> or
17226 <link to="IConsole::detachUSBDevice"/>.
17227
17228 This notification is sent in case of both a succeeded and a
17229 failed request completion. When the request succeeds, the
17230 @a error parameter is @c null, and the given device has been
17231 already added to (when @a attached is @c true) or removed from
17232 (when @a attached is @c false) the collection represented by
17233 <link to="IConsole::USBDevices"/>. On failure, the collection
17234 doesn't change and the @a error parameter represents the error
17235 message describing the failure.
17236 </desc>
17237 <attribute name="device" type="IUSBDevice" readonly="yes">
17238 <desc>
17239 Device that is subject to state change.
17240 </desc>
17241 </attribute>
17242 <attribute name="attached" type="boolean" readonly="yes">
17243 <desc>
17244 @c true if the device was attached and @c false otherwise.
17245 </desc>
17246 </attribute>
17247 <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
17248 <desc>
17249 @c null on success or an error message object on failure.
17250 </desc>
17251 </attribute>
17252 </interface>
17253
17254 <interface
17255 name="ISharedFolderChangedEvent" extends="IEvent"
17256 uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
17257 wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
17258 >
17259 <desc>
17260 Notification when a shared folder is added or removed.
17261 The @a scope argument defines one of three scopes:
17262 <link to="IVirtualBox::sharedFolders">global shared folders</link>
17263 (<link to="Scope_Global">Global</link>),
17264 <link to="IMachine::sharedFolders">permanent shared folders</link> of
17265 the machine (<link to="Scope_Machine">Machine</link>) or <link
17266 to="IConsole::sharedFolders">transient shared folders</link> of the
17267 machine (<link to="Scope_Session">Session</link>). Interested callees
17268 should use query the corresponding collections to find out what has
17269 changed.
17270 </desc>
17271 <attribute name="scope" type="Scope" readonly="yes">
17272 <desc>
17273 Scope of the notification.
17274 </desc>
17275 </attribute>
17276 </interface>
17277
17278 <interface
17279 name="IRuntimeErrorEvent" extends="IEvent"
17280 uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
17281 wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
17282 >
17283 <desc>
17284 Notification when an error happens during the virtual
17285 machine execution.
17286
17287 There are three kinds of runtime errors:
17288 <ul>
17289 <li><i>fatal</i></li>
17290 <li><i>non-fatal with retry</i></li>
17291 <li><i>non-fatal warnings</i></li>
17292 </ul>
17293
17294 <b>Fatal</b> errors are indicated by the @a fatal parameter set
17295 to @c true. In case of fatal errors, the virtual machine
17296 execution is always paused before calling this notification, and
17297 the notification handler is supposed either to immediately save
17298 the virtual machine state using <link to="IConsole::saveState"/>
17299 or power it off using <link to="IConsole::powerDown"/>.
17300 Resuming the execution can lead to unpredictable results.
17301
17302 <b>Non-fatal</b> errors and warnings are indicated by the
17303 @a fatal parameter set to @c false. If the virtual machine
17304 is in the Paused state by the time the error notification is
17305 received, it means that the user can <i>try to resume</i> the machine
17306 execution after attempting to solve the problem that caused the
17307 error. In this case, the notification handler is supposed
17308 to show an appropriate message to the user (depending on the
17309 value of the @a id parameter) that offers several actions such
17310 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
17311 wants to retry, the notification handler should continue
17312 the machine execution using the <link to="IConsole::resume"/>
17313 call. If the machine execution is not Paused during this
17314 notification, then it means this notification is a <i>warning</i>
17315 (for example, about a fatal condition that can happen very soon);
17316 no immediate action is required from the user, the machine
17317 continues its normal execution.
17318
17319 Note that in either case the notification handler
17320 <b>must not</b> perform any action directly on a thread
17321 where this notification is called. Everything it is allowed to
17322 do is to post a message to another thread that will then talk
17323 to the user and take the corresponding action.
17324
17325 Currently, the following error identifiers are known:
17326 <ul>
17327 <li><tt>"HostMemoryLow"</tt></li>
17328 <li><tt>"HostAudioNotResponding"</tt></li>
17329 <li><tt>"VDIStorageFull"</tt></li>
17330 <li><tt>"3DSupportIncompatibleAdditions"</tt></li>
17331 </ul>
17332 </desc>
17333 <attribute name="fatal" type="boolean" readonly="yes">
17334 <desc>
17335 Whether the error is fatal or not.
17336 </desc>
17337 </attribute>
17338 <attribute name="id" type="wstring" readonly="yes">
17339 <desc>
17340 Error identifier.
17341 </desc>
17342 </attribute>
17343 <attribute name="message" type="wstring" readonly="yes">
17344 <desc>
17345 Optional error message.
17346 </desc>
17347 </attribute>
17348 </interface>
17349
17350
17351 <interface
17352 name="IEventSourceChangedEvent" extends="IEvent"
17353 uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
17354 waitable="yes"
17355 wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
17356 >
17357 <desc>
17358 Notification when an event source state changes (listener added or removed).
17359 </desc>
17360
17361 <attribute name="listener" type="IEventListener" readonly="yes">
17362 <desc>
17363 Event listener which has changed.
17364 </desc>
17365 </attribute>
17366
17367 <attribute name="add" type="boolean" readonly="yes">
17368 <desc>
17369 Flag whether listener was added or removed.
17370 </desc>
17371 </attribute>
17372 </interface>
17373
17374 <interface
17375 name="IExtraDataChangedEvent" extends="IEvent"
17376 uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
17377 wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
17378 >
17379 <desc>
17380 Notification when machine specific or global extra data
17381 has changed.
17382 </desc>
17383 <attribute name="machineId" type="uuid" mod="string" readonly="yes">
17384 <desc>
17385 ID of the machine this event relates to.
17386 Null for global extra data changes.
17387 </desc>
17388 </attribute>
17389 <attribute name="key" type="wstring" readonly="yes">
17390 <desc>
17391 Extra data key that has changed.
17392 </desc>
17393 </attribute>
17394 <attribute name="value" type="wstring" readonly="yes">
17395 <desc>
17396 Extra data value for the given key.
17397 </desc>
17398 </attribute>
17399 </interface>
17400
17401 <interface
17402 name="IVetoEvent" extends="IEvent"
17403 uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
17404 wsmap="managed"
17405 >
17406 <desc>Base abstract interface for veto events.</desc>
17407
17408 <method name="addVeto">
17409 <desc>
17410 Adds a veto on this event.
17411 </desc>
17412 <param name="reason" type="wstring" dir="in">
17413 <desc>
17414 Reason for veto, could be null or empty string.
17415 </desc>
17416 </param>
17417 </method>
17418
17419 <method name="isVetoed">
17420 <desc>
17421 If this event was vetoed.
17422 </desc>
17423 <param name="result" type="boolean" dir="return">
17424 <desc>
17425 Reason for veto.
17426 </desc>
17427 </param>
17428 </method>
17429
17430 <method name="getVetos">
17431 <desc>
17432 Current veto reason list, if size is 0 - no veto.
17433 </desc>
17434 <param name="result" type="wstring" dir="return" safearray="yes">
17435 <desc>
17436 Array of reasons for veto provided by different event handlers.
17437 </desc>
17438 </param>
17439 </method>
17440
17441 </interface>
17442
17443 <interface
17444 name="IExtraDataCanChangeEvent" extends="IVetoEvent"
17445 uuid="245d88bd-800a-40f8-87a6-170d02249a55"
17446 wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
17447 waitable="true"
17448 >
17449 <desc>
17450 Notification when someone tries to change extra data for
17451 either the given machine or (if @c null) global extra data.
17452 This gives the chance to veto against changes.
17453 </desc>
17454 <attribute name="machineId" type="uuid" mod="string" readonly="yes">
17455 <desc>
17456 ID of the machine this event relates to.
17457 Null for global extra data changes.
17458 </desc>
17459 </attribute>
17460 <attribute name="key" type="wstring" readonly="yes">
17461 <desc>
17462 Extra data key that has changed.
17463 </desc>
17464 </attribute>
17465 <attribute name="value" type="wstring" readonly="yes">
17466 <desc>
17467 Extra data value for the given key.
17468 </desc>
17469 </attribute>
17470 </interface>
17471
17472 <interface
17473 name="ICanShowWindowEvent" extends="IVetoEvent"
17474 uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
17475 wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
17476 waitable="true"
17477 >
17478 <desc>
17479 Notification when a call to
17480 <link to="IMachine::canShowConsoleWindow"/> is made by a
17481 front-end to check if a subsequent call to
17482 <link to="IMachine::showConsoleWindow"/> can succeed.
17483
17484 The callee should give an answer appropriate to the current
17485 machine state using event veto. This answer must
17486 remain valid at least until the next
17487 <link to="IConsole::state">machine state</link> change.
17488 </desc>
17489 </interface>
17490
17491 <interface
17492 name="IShowWindowEvent" extends="IEvent"
17493 uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
17494 wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
17495 waitable="true"
17496 >
17497 <desc>
17498 Notification when a call to
17499 <link to="IMachine::showConsoleWindow"/>
17500 requests the console window to be activated and brought to
17501 foreground on the desktop of the host PC.
17502
17503 This notification should cause the VM console process to
17504 perform the requested action as described above. If it is
17505 impossible to do it at a time of this notification, this
17506 method should return a failure.
17507
17508 Note that many modern window managers on many platforms
17509 implement some sort of focus stealing prevention logic, so
17510 that it may be impossible to activate a window without the
17511 help of the currently active application (which is supposedly
17512 an initiator of this notification). In this case, this method
17513 must return a non-zero identifier that represents the
17514 top-level window of the VM console process. The caller, if it
17515 represents a currently active process, is responsible to use
17516 this identifier (in a platform-dependent manner) to perform
17517 actual window activation.
17518
17519 This method must set @a winId to zero if it has performed all
17520 actions necessary to complete the request and the console
17521 window is now active and in foreground, to indicate that no
17522 further action is required on the caller's side.
17523 </desc>
17524 <attribute name="winId" type="long long">
17525 <desc>
17526 Platform-dependent identifier of the top-level VM console
17527 window, or zero if this method has performed all actions
17528 necessary to implement the <i>show window</i> semantics for
17529 the given platform and/or this VirtualBox front-end.
17530 </desc>
17531 </attribute>
17532 </interface>
17533
17534 <interface
17535 name="INATRedirectEvent" extends="IMachineEvent"
17536 uuid="57DE97D7-3CBB-42A0-888F-610D5832D16B"
17537 wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect"
17538 >
17539 <desc>
17540 Notification when NAT redirect rule added or removed.
17541 </desc>
17542 <attribute name="slot" type="unsigned long" readonly="yes">
17543 <desc>
17544 Adapter which NAT attached to.
17545 </desc>
17546 </attribute>
17547 <attribute name="remove" type="boolean" readonly="yes">
17548 <desc>
17549 Whether rule remove or add.
17550 </desc>
17551 </attribute>
17552 <attribute name="name" type="wstring" readonly="yes">
17553 <desc>
17554 Name of the rule.
17555 </desc>
17556 </attribute>
17557 <attribute name="proto" type="NATProtocol" readonly="yes">
17558 <desc>
17559 Protocol (TCP or UDP) of the redirect rule.
17560 </desc>
17561 </attribute>
17562 <attribute name="hostIp" type="wstring" readonly="yes">
17563 <desc>
17564 Host ip address to bind socket on.
17565 </desc>
17566 </attribute>
17567 <attribute name="hostPort" type="long" readonly="yes">
17568 <desc>
17569 Host port to bind socket on.
17570 </desc>
17571 </attribute>
17572 <attribute name="guestIp" type="wstring" readonly="yes">
17573 <desc>
17574 Guest ip address to redirect to.
17575 </desc>
17576 </attribute>
17577 <attribute name="guestPort" type="long" readonly="yes">
17578 <desc>
17579 Guest port to redirect to.
17580 </desc>
17581 </attribute>
17582 </interface>
17583
17584 <interface
17585 name="IHostPciDevicePlugEvent" extends="IMachineEvent"
17586 waitable="yes"
17587 uuid="9cebfc27-c579-4965-8eb7-d31794cd7dcf"
17588 wsmap="managed" autogen="VBoxEvent" id="OnHostPciDevicePlug"
17589 >
17590 <desc>
17591 Notification when host PCI device is plugged/unplugged. Plugging
17592 usually takes place on VM startup, unplug - when
17593 <link to="IMachine::detachHostPciDevice"/> is called.
17594
17595 <see><link to="IMachine::detachHostPciDevice"/></see>
17596
17597 </desc>
17598
17599 <attribute name="plugged" type="boolean" readonly="yes">
17600 <desc>
17601 If device successfully plugged or unplugged.
17602 </desc>
17603 </attribute>
17604
17605 <attribute name="success" type="boolean" readonly="yes">
17606 <desc>
17607 If operation was successful, if false - 'message' attribute
17608 may be of interest.
17609 </desc>
17610 </attribute>
17611
17612 <attribute name="attachment" type="IPciDeviceAttachment" readonly="yes">
17613 <desc>
17614 Attachment info for this device.
17615 </desc>
17616 </attribute>
17617
17618 <attribute name="message" type="wstring" readonly="yes">
17619 <desc>
17620 Optional error message.
17621 </desc>
17622 </attribute>
17623
17624 </interface>
17625
17626 <interface
17627 name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent"
17628 uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc"
17629 wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged"
17630 >
17631 <desc>
17632 Notification when VBoxSVC becomes unavailable (due to a crash or similar
17633 unexpected circumstances) or available again.
17634 </desc>
17635
17636 <attribute name="available" type="boolean" readonly="yes">
17637 <desc>
17638 Whether VBoxSVC is available now.
17639 </desc>
17640 </attribute>
17641 </interface>
17642
17643 <interface
17644 name="IBandwidthGroupChangedEvent" extends="IEvent"
17645 uuid="334df94a-7556-4cbc-8c04-043096b02d82"
17646 wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged"
17647 >
17648 <desc>
17649 Notification when one of the bandwidth groups changed
17650 </desc>
17651 <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
17652 <desc>
17653 The changed bandwidth group.
17654 </desc>
17655 </attribute>
17656 </interface>
17657
17658 <enum
17659 name="GuestMonitorChangedEventType"
17660 uuid="ef172985-7e36-4297-95be-e46396968d66"
17661 >
17662
17663 <desc>
17664 How the guest monitor has been changed.
17665 </desc>
17666
17667 <const name="Enabled" value="0">
17668 <desc>
17669 The guest monitor has been enabled by the guest.
17670 </desc>
17671 </const>
17672
17673 <const name="Disabled" value="1">
17674 <desc>
17675 The guest monitor has been disabled by the guest.
17676 </desc>
17677 </const>
17678
17679 <const name="NewOrigin" value="2">
17680 <desc>
17681 The guest monitor origin has changed in the guest.
17682 </desc>
17683 </const>
17684 </enum>
17685
17686 <interface
17687 name="IGuestMonitorChangedEvent" extends="IEvent"
17688 uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090"
17689 wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged"
17690 >
17691 <desc>
17692 Notification when the guest enables one of its monitors.
17693 </desc>
17694
17695 <attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes">
17696 <desc>
17697 What was changed for this guest monitor.
17698 </desc>
17699 </attribute>
17700
17701 <attribute name="screenId" type="unsigned long" readonly="yes">
17702 <desc>
17703 The monitor which was changed.
17704 </desc>
17705 </attribute>
17706
17707 <attribute name="originX" type="unsigned long" readonly="yes">
17708 <desc>
17709 Physical X origin relative to the primary screen.
17710 Valid for Enabled and NewOrigin.
17711 </desc>
17712 </attribute>
17713
17714 <attribute name="originY" type="unsigned long" readonly="yes">
17715 <desc>
17716 Physical Y origin relative to the primary screen.
17717 Valid for Enabled and NewOrigin.
17718 </desc>
17719 </attribute>
17720
17721 <attribute name="width" type="unsigned long" readonly="yes">
17722 <desc>
17723 Width of the screen.
17724 Valid for Enabled.
17725 </desc>
17726 </attribute>
17727
17728 <attribute name="height" type="unsigned long" readonly="yes">
17729 <desc>
17730 Height of the screen.
17731 Valid for Enabled.
17732 </desc>
17733 </attribute>
17734
17735 </interface>
17736
17737 <interface
17738 name="IStorageDeviceChangedEvent" extends="IEvent"
17739 uuid="8a5c2dce-e341-49d4-afce-c95979f7d70c"
17740 wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged"
17741 >
17742 <desc>
17743 Notification when a
17744 <link to="IMachine::mediumAttachments">storage device</link>
17745 is attached or removed.
17746 </desc>
17747 <attribute name="storageDevice" type="IMediumAttachment" readonly="yes">
17748 <desc>
17749 Storage device that is subject to change.
17750 </desc>
17751 </attribute>
17752 <attribute name="removed" type="boolean" readonly="yes">
17753 <desc>
17754 Flag whether the device was removed or added to the VM.
17755 </desc>
17756 </attribute>
17757 </interface>
17758
17759 <module name="VBoxSVC" context="LocalServer">
17760 <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
17761 namespace="virtualbox.org">
17762 <interface name="IVirtualBox" default="yes"/>
17763 </class>
17764 </module>
17765
17766 <module name="VBoxC" context="InprocServer" threadingModel="Free">
17767 <class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba"
17768 namespace="virtualbox.org">
17769 <interface name="IVirtualBoxClient" default="yes"/>
17770 </class>
17771
17772 <class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
17773 namespace="virtualbox.org">
17774 <interface name="ISession" default="yes"/>
17775 </class>
17776 </module>
17777
17778</library>
17779
17780</idl>
17781
17782<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette