VirtualBox

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

Last change on this file since 19134 was 19115, checked in by vboxsync, 16 years ago

Enabling create/destroy host-only interfaces in Main API for all platforms.

  • Property svn:eol-style set to native
File size: 492.0 KB
Line 
1<?xml version="1.0" ?>
2
3<!--
4 * :tabSize=2:indentSize=2:noTabs=true:
5 * :folding=explicit:collapseFolds=1:
6 *
7 * Master declaration for VirtualBox's Main API, represented
8 * by COM/XPCOM and web service interfaces.
9 *
10 * From this document, the build system generates several files
11 * via XSLT that are then used during the build process.
12 *
13 * Below is the list of XSL templates that operate on this file and
14 * output files they generate. These XSL templates must be updated
15 * whenever the schema of this file changes:
16 *
17 * 1. src/VBox/Main/idl/midl.xsl =>
18 * out/<platform>/bin/sdk/idl/VirtualBox.idl
19 * (MS COM interface definition file for Main API)
20 *
21 * 2. src/VBox/Main/idl/xpidl.xsl =>
22 * out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
23 * (XPCOM interface definition file for Main API)
24 *
25 * 3. src/VBox/Main/idl/doxygen.xsl =>
26 * out/<platform>/obj/src/VBox/Main/VirtualBox.idl
27 * (pseudo-IDL for Doxygen to generate the official Main API
28 * documentation)
29 *
30 * 4. src/VBox/Main/webservice/*.xsl =>
31 * a bunch of WSDL and C++ files
32 * (VirtualBox web service sources and SOAP mappers;
33 * see src/VBox/Main/webservice/Makefile.kmk for details)
34 *
35 * 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
36 * out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
37 * (smart Qt-based C++ wrapper classes for COM interfaces
38 * of the Main API)
39 *
40 * 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
41 * out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
42 * (Main API TypeLib block for the WiX installer)
43 *
44 * 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
45 * out/<platform>/obj/Runtime/errmsgvboxcomdata.h
46 * (<result> extraction for the %Rhrc format specifier)
47 *
48 Copyright (C) 2006-2009 Sun Microsystems, Inc.
49
50 This file is part of VirtualBox Open Source Edition (OSE), as
51 available from http://www.virtualbox.org. This file is free software;
52 you can redistribute it and/or modify it under the terms of the GNU
53 General Public License (GPL) as published by the Free Software
54 Foundation, in version 2 as it comes in the "COPYING" file of the
55 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
56 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
57
58 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
59 Clara, CA 95054 USA or visit http://www.sun.com if you need
60 additional information or have any questions.
61-->
62
63<idl>
64
65<desc>
66 Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
67 describes the so-called <i>VirtualBox Main API</i> which comprises all public
68 COM interfaces and components provided by the VirtualBox server and by the
69 VirtualBox client library.
70
71 VirtualBox employs a client-server design, meaning that whenever any part of
72 VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
73 interface or any virtual machine --, a dedicated server process named
74 VBoxSVC runs in the background. This allows multiple processes working with
75 VirtualBox to cooperate without conflicts. These processes communicate to each
76 other using inter-process communication facilities provided by the COM
77 implementation of the host computer.
78
79 On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
80 implementation. On all other platforms, Mozilla XPCOM, an open-source COM
81 implementation, is used.
82
83 All the parts that a typical VirtualBox user interacts with (the Qt GUI,
84 the VBoxManage command-line interface and the VBoxVRDP server) are technically
85 front-ends to the Main API and only use the interfaces that are documented
86 in this Main API documentation. This ensures that, with any given release
87 version of VirtualBox, all capabilities of the product that could be useful
88 to an external client program are always exposed by way of this API.
89
90 The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
91 contains two public component classes:
92 <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
93 implement IVirtualBox and ISession interfaces respectively. These two classes
94 are of supreme importance and will be needed in order for any front-end
95 program to do anything useful. It is recommended to read the documentation of
96 the mentioned interfaces first.
97
98 The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
99 there can be only one object of this class on the local machine at any given
100 time. This object is a parent of many other objects in the VirtualBox COM
101 library and lives in the VBoxSVC process. In fact, when you create an instance
102 of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
103 process is already running, starts it if not, and returns you a reference to
104 the <tt>VirtualBox</tt> object created in this process. When the last reference
105 to this object is released, the VBoxSVC process ends (with a 5 second delay to
106 protect from too frequent restarts).
107
108 The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
109 as many <tt>Session</tt> objects as you need but all of them will live in a
110 process which issues the object instantiation call. <tt>Session</tt> objects
111 represent virtual machine sessions which are used to configure virtual
112 machines and control their execution.
113</desc>
114
115<if target="midl">
116 <cpp line="enum {"/>
117 <cpp line=" kTypeLibraryMajorVersion = 1,"/>
118 <cpp line=" kTypeLibraryMinorVersion = 0"/>
119 <cpp line="};"/>
120</if>
121
122<if target="xpidl">
123 <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
124 <cpp>
125/* currently, nsISupportsImpl.h lacks the below-like macros */
126
127#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
128#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
129
130#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
131# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
132 NS_IMPL_THREADSAFE_ADDREF(_class) \
133 NS_IMPL_THREADSAFE_RELEASE(_class) \
134 NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
135 NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
136#endif
137
138#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
139# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
140 NS_IMPL_THREADSAFE_ADDREF(_class) \
141 NS_IMPL_THREADSAFE_RELEASE(_class) \
142 NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
143 NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
144#endif
145
146#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
147# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
148 NS_INTERFACE_MAP_BEGIN(_class) \
149 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
150 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
151 NS_IMPL_QUERY_CLASSINFO(_class) \
152 NS_INTERFACE_MAP_END
153#endif
154
155#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
156# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
157 _i2, _ic2) \
158 NS_INTERFACE_MAP_BEGIN(_class) \
159 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
160 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
161 NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
162 NS_IMPL_QUERY_CLASSINFO(_class) \
163 NS_INTERFACE_MAP_END
164#endif
165
166#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
167#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
168
169#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
170# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
171 NS_IMPL_THREADSAFE_ADDREF(_class) \
172 NS_IMPL_THREADSAFE_RELEASE(_class) \
173 NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
174 NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
175#endif
176
177#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
178# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
179 _i2, _ic2) \
180 NS_IMPL_THREADSAFE_ADDREF(_class) \
181 NS_IMPL_THREADSAFE_RELEASE(_class) \
182 NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
183 _i2, _ic2) \
184 NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
185#endif
186 </cpp>
187</if>
188
189<library
190 name="VirtualBox"
191 uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
192 version="1.3"
193 desc="VirtualBox Type Library"
194 appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
195 supportsErrorInfo="yes"
196>
197
198
199 <!--
200 // COM result codes for VirtualBox
201 /////////////////////////////////////////////////////////////////////////
202 -->
203
204 <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
205 <desc>
206 This section describes all VirtualBox-specific COM result codes that may
207 be returned by methods of VirtualBox COM interfaces in addition to
208 standard COM result codes.
209
210 Note that along with the result code, every VirtualBox method returns
211 extended error information through the IVirtualBoxErrorInfo interface on
212 failure. This interface is a preferred way to present the error to the end
213 user because it contains a human readable description of the error. Raw
214 result codes, both standard and described in this section, are intended to
215 be used by programs to analyze the reason of a failure and select an
216 appropriate course of action without involving the end user (for example,
217 retry the operation later or make a different call).
218
219 The standard COM result codes that may originate from our methods include:
220
221 <table>
222 <tr><td>E_INVALIDARG</td>
223 <td>
224 Returned when the value of the method's argument is not within the range
225 of valid values. This should not be confused with situations when the
226 value is within the range but simply doesn't suit the current object
227 state and there is a possibility that it will be accepted later (in such
228 cases VirtualBox-specific codes are returned, for example,
229 <link to="VBOX_E_OBJECT_NOT_FOUND"/>).
230 </td>
231 </tr>
232 <tr><td>E_POINTER</td>
233 <td>
234 Returned if a memory pointer for the output argument is invalid (for
235 example, <tt>NULL</tt>). Note that when pointers representing input
236 arguments (such as strings) are invalid, E_INVALIDARG is returned.
237 </td>
238 </tr>
239 <tr><td>E_ACCESSDENIED</td>
240 <td>
241 Returned when the called object is not ready. Since the lifetime of a
242 public COM object cannot be fully controlled by the implementation,
243 VirtualBox maintains the readiness state for all objects it creates and
244 returns this code in response to any method call on the object that was
245 deactivated by VirtualBox and is not functioning any more.
246 </td>
247 </tr>
248 <tr><td>E_OUTOFMEMORY</td>
249 <td>
250 Returned when a memory allocation operation fails.
251 </td>
252 </tr>
253 </table>
254 </desc>
255 </descGroup>
256
257 <!--
258 Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
259 everything in <result>/<desc> after (and including) the first dot, so express
260 the matter of the error code in the first sentence and keep it short.
261 -->
262
263 <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
264 <desc>
265 Object corresponding to the supplied arguments does not exist.
266 </desc>
267 </result>
268
269 <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
270 <desc>
271 Current virtual machine state prevents the operation.
272 </desc>
273 </result>
274
275 <result name="VBOX_E_VM_ERROR" value="0x80BB0003">
276 <desc>
277 Virtual machine error occurred attempting the operation.
278 </desc>
279 </result>
280
281 <result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
282 <desc>
283 File not accessible or erroneous file contents.
284 </desc>
285 </result>
286
287 <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
288 <desc>
289 Runtime subsystem error.
290 </desc>
291 </result>
292
293 <result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
294 <desc>
295 Pluggable Device Manager error.
296 </desc>
297 </result>
298
299 <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
300 <desc>
301 Current object state prohibits operation.
302 </desc>
303 </result>
304
305 <result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
306 <desc>
307 Host operating system related error.
308 </desc>
309 </result>
310
311 <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
312 <desc>
313 Requested operation is not supported.
314 </desc>
315 </result>
316
317 <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
318 <desc>
319 Invalid XML found.
320 </desc>
321 </result>
322
323 <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
324 <desc>
325 Current session state prohibits operation.
326 </desc>
327 </result>
328
329 <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
330 <desc>
331 Object being in use prohibits operation.
332 </desc>
333 </result>
334
335 <!--
336 Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
337 everything in <result>/<desc> after (and including) the first dot, so express
338 the matter of the error code in the first sentence and keep it short.
339 -->
340
341 <descGroup/>
342
343 <!--
344 // all common enums
345 /////////////////////////////////////////////////////////////////////////
346 -->
347
348 <enum
349 name="TSBool"
350 uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
351 >
352 <desc>
353 Boolean variable having a third state, default.
354 </desc>
355
356 <const name="False" value="0"/>
357 <const name="True" value="1"/>
358 <const name="Default" value="2"/>
359 </enum>
360
361 <enum
362 name="AccessMode"
363 uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
364 >
365 <desc>
366 Access mode for opening files.
367 </desc>
368
369 <const name="ReadOnly" value="1"/>
370 <const name="ReadWrite" value="2"/>
371 </enum>
372
373 <enum
374 name="MachineState"
375 uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
376 >
377 <desc>
378 Virtual machine execution state.
379
380 This enumeration represents possible values of the <link
381 to="IMachine::state"/> attribute.
382
383 Below is the basic virtual machine state diagram. It shows how the state
384 changes during virtual machine execution. The text in square braces shows
385 a method of the IConsole interface that performs the given state
386 transition.
387
388 <pre>
389 +---------[powerDown()] &lt;- Stuck &lt;--[failure]-+
390 V |
391 +-&gt; PoweredOff --+--&gt;[powerUp()]--&gt; Starting --+ | +-----[resume()]-----+
392 | | | | V |
393 | Aborted -----+ +--&gt; Running --[pause()]--&gt; Paused
394 | | ^ | ^ |
395 | Saved -----------[powerUp()]--&gt; Restoring -+ | | | |
396 | ^ | | | |
397 | | +-----------------------------------------+-|-------------------+ +
398 | | | | |
399 | | +-- Saving &lt;--------[takeSnapshot()]&lt;-------+---------------------+
400 | | | |
401 | +-------- Saving &lt;--------[saveState()]&lt;----------+---------------------+
402 | | |
403 +-------------- Stopping -------[powerDown()]&lt;----------+---------------------+
404 </pre>
405
406 Note that states to the right from PoweredOff, Aborted and Saved in the
407 above diagram are called <i>online VM states</i>. These states
408 represent the virtual machine which is being executed in a dedicated
409 process (usually with a GUI window attached to it where you can see the
410 activity of the virtual machine and interact with it). There are two
411 special pseudo-states, FirstOnline and LastOnline, that can be used in
412 relational expressions to detect if the given machine state is online or
413 not:
414
415 <pre>
416 if (machine.GetState() &gt;= MachineState_FirstOnline &amp;&amp;
417 machine.GetState() &lt;= MachineState_LastOnline)
418 {
419 ...the machine is being executed...
420 }
421 </pre>
422
423 When the virtual machine is in one of the online VM states (that is, being
424 executed), only a few machine settings can be modified. Methods working
425 with such settings contain an explicit note about that. An attempt to
426 change any oter setting or perform a modifying operation during this time
427 will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
428
429 All online states except Running, Paused and Stuck are transitional: they
430 represent temporary conditions of the virtual machine that will last as
431 long as the operation that initiated such a condition.
432
433 The Stuck state is a special case. It means that execution of the machine
434 has reached the "Guru Meditation" condition. This condition indicates an
435 internal VMM (virtual machine manager) failure which may happen as a
436 result of either an unhandled low-level virtual hardware exception or one
437 of the recompiler exceptions (such as the <i>too-many-traps</i>
438 condition).
439
440 Note also that any online VM state may transit to the Aborted state. This
441 happens if the process that is executing the virtual machine terminates
442 unexpectedly (for example, crashes). Other than that, the Aborted state is
443 equivalent to PoweredOff.
444
445 There are also a few additional state diagrams that do not deal with
446 virtual machine execution and therefore are shown separately. The states
447 shown on these diagrams are called <i>offline VM states</i> (this includes
448 PoweredOff, Aborted and Saved too).
449
450 The first diagram shows what happens when a lengthy setup operation is
451 being executed (such as <link to="IMachine::attachHardDisk"/>).
452
453 <pre>
454 +----------------------------------(same state as before the call)------+
455 | |
456 +-&gt; PoweredOff --+ |
457 | | |
458 |-&gt; Aborted -----+--&gt;[lengthy VM configuration call] --&gt; SettingUp -----+
459 | |
460 +-&gt; Saved -------+
461 </pre>
462
463 The next two diagrams demonstrate the process of taking a snapshot of a
464 powered off virtual machine and performing one of the "discard..."
465 operations, respectively.
466
467 <pre>
468 +----------------------------------(same state as before the call)------+
469 | |
470 +-&gt; PoweredOff --+ |
471 | +--&gt;[takeSnapshot()] -------------------&gt; Saving ------+
472 +-&gt; Aborted -----+
473
474 +-&gt; PoweredOff --+
475 | |
476 | Aborted -----+--&gt;[discardSnapshot() ]-------------&gt; Discarding --+
477 | | [discardCurrentState()] |
478 +-&gt; Saved -------+ [discardCurrentSnapshotAndState()] |
479 | |
480 +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
481 </pre>
482
483 Note that the Saving state is present in both the offline state group and
484 online state group. Currently, the only way to determine what group is
485 assumed in a particular case is to remember the previous machine state: if
486 it was Running or Paused, then Saving is an online state, otherwise it is
487 an offline state. This inconsistency may be removed in one of the future
488 versions of VirtualBox by adding a new state.
489
490 <note internal="yes">
491 For whoever decides to touch this enum: In order to keep the
492 comparisons involving FirstOnline and LastOnline pseudo-states valid,
493 the numeric values of these states must be correspondingly updated if
494 needed: for any online VM state, the condition
495 <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
496 <tt>true</tt>. The same relates to transient states for which
497 the condition <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
498 <tt>true</tt>.
499 </note>
500 </desc>
501
502 <const name="Null" value="0">
503 <desc>Null value (never used by the API).</desc>
504 </const>
505 <const name="PoweredOff" value="1">
506 <desc>
507 The machine is not running.
508 </desc>
509 </const>
510 <const name="Saved" value="2">
511 <desc>
512 The machine is not currently running, but the execution state of the machine
513 has been saved to an external file when it was running.
514 </desc>
515 </const>
516 <const name="Aborted" value="3">
517 <desc>
518 The process running the machine has terminated abnormally.
519 </desc>
520 </const>
521 <const name="Running" value="4">
522 <desc>
523 The machine is currently being executed.
524 <note internal="yes">
525 For whoever decides to touch this enum: In order to keep the
526 comparisons in the old source code valid, this state must immediately
527 precede the Paused state.
528 </note>
529 </desc>
530 </const>
531 <const name="Paused" value="5">
532 <desc>
533 Execution of the machine has been paused.
534 <note internal="yes">
535 For whoever decides to touch this enum: In order to keep the
536 comparisons in the old source code valid, this state must immediately
537 follow the Running state.
538 </note>
539 </desc>
540 </const>
541 <const name="Stuck" value="6">
542 <desc>
543 Execution of the machine has reached the "Guru Meditation"
544 condition.
545 </desc>
546 </const>
547 <const name="Starting" value="7">
548 <desc>
549 Machine is being started after powering it on from a
550 zero execution state.
551 </desc>
552 </const>
553 <const name="Stopping" value="8">
554 <desc>
555 Machine is being normally stopped powering it off, or after the guest OS
556 has initiated a shutdown sequence.
557 </desc>
558 </const>
559 <const name="Saving" value="9">
560 <desc>
561 Machine is saving its execution state to a file or an online
562 snapshot of the machine is being taken.
563 </desc>
564 </const>
565 <const name="Restoring" value="10">
566 <desc>
567 Execution state of the machine is being restored from a file
568 after powering it on from the saved execution state.
569 </desc>
570 </const>
571 <const name="Discarding" value="11">
572 <desc>
573 Snapshot of the machine is being discarded.
574 </desc>
575 </const>
576 <const name="SettingUp" value="12">
577 <desc>
578 Lengthy setup operation is in progress.
579 </desc>
580 </const>
581
582 <const name="FirstOnline" value="4" wsmap="suppress"> <!-- Running -->
583 <desc>
584 Pseudo-state: first online state (for use in relational expressions).
585 </desc>
586 </const>
587 <const name="LastOnline" value="10" wsmap="suppress"> <!-- Restoring -->
588 <desc>
589 Pseudo-state: last online state (for use in relational expressions).
590 </desc>
591 </const>
592
593 <const name="FirstTransient" value="7" wsmap="suppress"> <!-- Starting -->
594 <desc>
595 Pseudo-state: first transient state (for use in relational expressions).
596 </desc>
597 </const>
598 <const name="LastTransient" value="12" wsmap="suppress"> <!-- SettingUp -->
599 <desc>
600 Pseudo-state: last transient state (for use in relational expressions).
601 </desc>
602 </const>
603
604 </enum>
605
606 <enum
607 name="SessionState"
608 uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
609 >
610 <desc>
611 Session state. This enumeration represents possible values of
612 <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
613 attributes. See individual enumerator descriptions for the meaning for
614 every value.
615 </desc>
616
617 <const name="Null" value="0">
618 <desc>Null value (never used by the API).</desc>
619 </const>
620 <const name="Closed" value="1">
621 <desc>
622 The machine has no open sessions (<link to="IMachine::sessionState"/>);
623 the session is closed (<link to="ISession::state"/>)
624 </desc>
625 </const>
626 <const name="Open" value="2">
627 <desc>
628 The machine has an open direct session (<link to="IMachine::sessionState"/>);
629 the session is open (<link to="ISession::state"/>)
630 </desc>
631 </const>
632 <const name="Spawning" value="3">
633 <desc>
634 A new (direct) session is being opened for the machine
635 as a result of <link to="IVirtualBox::openRemoteSession"/>
636 call (<link to="IMachine::sessionState"/>);
637 the session is currently being opened
638 as a result of <link to="IVirtualBox::openRemoteSession"/>
639 call (<link to="ISession::state"/>)
640 </desc>
641 </const>
642 <const name="Closing" value="4">
643 <desc>
644 The direct session is being closed (<link to="IMachine::sessionState"/>);
645 the session is being closed (<link to="ISession::state"/>)
646 </desc>
647 </const>
648 </enum>
649
650 <enum
651 name="SessionType"
652 uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
653 >
654 <desc>
655 Session type. This enumeration represents possible values of the
656 <link to="ISession::type"/> attribute.
657 </desc>
658
659 <const name="Null" value="0">
660 <desc>Null value (never used by the API).</desc>
661 </const>
662 <const name="Direct" value="1">
663 <desc>
664 Direct session
665 (opened by <link to="IVirtualBox::openSession"/>)
666 </desc>
667 </const>
668 <const name="Remote" value="2">
669 <desc>
670 Remote session
671 (opened by <link to="IVirtualBox::openRemoteSession"/>)
672 </desc>
673 </const>
674 <const name="Existing" value="3">
675 <desc>
676 Existing session
677 (opened by <link to="IVirtualBox::openExistingSession"/>)
678 </desc>
679 </const>
680 </enum>
681
682 <enum
683 name="DeviceType"
684 uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
685 >
686 <desc>
687 Device type.
688 </desc>
689 <const name="Null" value="0">
690 <desc>
691 Null value, may also mean "no device" (not allowed for
692 <link to="IConsole::getDeviceActivity"/>).
693 </desc>
694 </const>
695 <const name="Floppy" value="1">
696 <desc>Floppy device.</desc>
697 </const>
698 <const name="DVD" value="2">
699 <desc>CD/DVD-ROM device.</desc>
700 </const>
701 <const name="HardDisk" value="3">
702 <desc>Hard disk device.</desc>
703 </const>
704 <const name="Network" value="4">
705 <desc>Network device.</desc>
706 </const>
707 <const name="USB" value="5">
708 <desc>USB device.</desc>
709 </const>
710 <const name="SharedFolder" value="6">
711 <desc>Shared folder device.</desc>
712 </const>
713 </enum>
714
715 <enum
716 name="DeviceActivity"
717 uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
718 >
719 <desc>
720 Device activity for <link to="IConsole::getDeviceActivity"/>.
721 </desc>
722
723 <const name="Null" value="0"/>
724 <const name="Idle" value="1"/>
725 <const name="Reading" value="2"/>
726 <const name="Writing" value="3"/>
727 </enum>
728
729 <enum
730 name="ClipboardMode"
731 uuid="33364716-4008-4701-8f14-be0fa3d62950"
732 >
733 <desc>
734 Host-Guest clipboard interchange mode.
735 </desc>
736
737 <const name="Disabled" value="0"/>
738 <const name="HostToGuest" value="1"/>
739 <const name="GuestToHost" value="2"/>
740 <const name="Bidirectional" value="3"/>
741 </enum>
742
743 <enum
744 name="Scope"
745 uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
746 >
747 <desc>
748 Scope of the operation.
749
750 A generic enumeration used in various methods to define the action or
751 argument scope.
752 </desc>
753
754 <const name="Global" value="0"/>
755 <const name="Machine" value="1"/>
756 <const name="Session" value="2"/>
757 </enum>
758
759 <enum
760 name="GuestStatisticType"
761 uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
762 >
763 <desc>
764 Statistics type for <link to="IGuest::getStatistic"/>.
765 </desc>
766
767 <const name="CPULoad_Idle" value="0">
768 <desc>
769 Idle CPU load (0-100%) for last interval.
770 </desc>
771 </const>
772 <const name="CPULoad_Kernel" value="1">
773 <desc>
774 Kernel CPU load (0-100%) for last interval.
775 </desc>
776 </const>
777 <const name="CPULoad_User" value="2">
778 <desc>
779 User CPU load (0-100%) for last interval.
780 </desc>
781 </const>
782 <const name="Threads" value="3">
783 <desc>
784 Total number of threads in the system.
785 </desc>
786 </const>
787 <const name="Processes" value="4">
788 <desc>
789 Total number of processes in the system.
790 </desc>
791 </const>
792 <const name="Handles" value="5">
793 <desc>
794 Total number of handles in the system.
795 </desc>
796 </const>
797 <const name="MemoryLoad" value="6">
798 <desc>
799 Memory load (0-100%).
800 </desc>
801 </const>
802 <const name="PhysMemTotal" value="7">
803 <desc>
804 Total physical memory in megabytes.
805 </desc>
806 </const>
807 <const name="PhysMemAvailable" value="8">
808 <desc>
809 Free physical memory in megabytes.
810 </desc>
811 </const>
812 <const name="PhysMemBalloon" value="9">
813 <desc>
814 Ballooned physical memory in megabytes.
815 </desc>
816 </const>
817 <const name="MemCommitTotal" value="10">
818 <desc>
819 Total amount of memory in the committed state in megabytes.
820 </desc>
821 </const>
822 <const name="MemKernelTotal" value="11">
823 <desc>
824 Total amount of memory used by the guest OS's kernel in megabytes.
825 </desc>
826 </const>
827 <const name="MemKernelPaged" value="12">
828 <desc>
829 Total amount of paged memory used by the guest OS's kernel in megabytes.
830 </desc>
831 </const>
832 <const name="MemKernelNonpaged" value="13">
833 <desc>
834 Total amount of non-paged memory used by the guest OS's kernel in megabytes.
835 </desc>
836 </const>
837 <const name="MemSystemCache" value="14">
838 <desc>
839 Total amount of memory used by the guest OS's system cache in megabytes.
840 </desc>
841 </const>
842 <const name="PageFileSize" value="15">
843 <desc>
844 Pagefile size in megabytes.
845 </desc>
846 </const>
847 <const name="SampleNumber" value="16">
848 <desc>
849 Statistics sample number
850 </desc>
851 </const>
852 <const name="MaxVal" value="17"/>
853 </enum>
854
855 <enum
856 name="BIOSBootMenuMode"
857 uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
858 >
859 <desc>
860 BIOS boot menu mode.
861 </desc>
862
863 <const name="Disabled" value="0"/>
864 <const name="MenuOnly" value="1"/>
865 <const name="MessageAndMenu" value="2"/>
866 </enum>
867
868 <enum
869 name="DriveState"
870 uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
871 >
872 <const name="Null" value="0">
873 <desc>Null value (never used by the API).</desc>
874 </const>
875 <const name="NotMounted" value="1"/>
876 <const name="ImageMounted" value="2"/>
877 <const name="HostDriveCaptured" value="3"/>
878 </enum>
879
880 <enum
881 name="ProcessorFeature"
882 uuid="b8353b35-705d-4796-9967-ebfb7ba54af4"
883 >
884 <desc>
885 CPU features.
886 </desc>
887
888 <const name="HWVirtEx" value="0"/>
889 <const name="PAE" value="1"/>
890 <const name="LongMode" value="2"/>
891 </enum>
892
893
894 <!--
895 // IVirtualBoxErrorInfo
896 /////////////////////////////////////////////////////////////////////////
897 -->
898
899 <interface
900 name="IVirtualBoxErrorInfo" extends="$errorinfo"
901 uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
902 supportsErrorInfo="no"
903 wsmap="suppress"
904 >
905 <desc>
906 The IVirtualBoxErrorInfo interface represents extended error information.
907
908 Extended error information can be set by VirtualBox components after
909 unsuccessful or partially successful method invocation. This information
910 can be retrieved by the calling party as an IVirtualBoxErrorInfo object
911 and then shown to the client in addition to the plain 32-bit result code.
912
913 In MS COM, this interface extends the IErrorInfo interface,
914 in XPCOM, it extends the nsIException interface. In both cases,
915 it provides a set of common attributes to retrieve error
916 information.
917
918 Sometimes invocation of some component's method may involve methods of
919 other components that may also fail (independently of this method's
920 failure), or a series of non-fatal errors may precede a fatal error that
921 causes method failure. In cases like that, it may be desirable to preserve
922 information about all errors happened during method invocation and deliver
923 it to the caller. The <link to="#next"/> attribute is intended
924 specifically for this purpose and allows to represent a chain of errors
925 through a single IVirtualBoxErrorInfo object set after method invocation.
926
927 Note that errors are stored to a chain in the reverse order, i.e. the
928 initial error object you query right after method invocation is the last
929 error set by the callee, the object it points to in the @a next attribute
930 is the previous error and so on, up to the first error (which is the last
931 in the chain).
932 </desc>
933
934 <attribute name="resultCode" type="result" readonly="yes">
935 <desc>
936 Result code of the error.
937 Usually, it will be the same as the result code returned
938 by the method that provided this error information, but not
939 always. For example, on Win32, CoCreateInstance() will most
940 likely return E_NOINTERFACE upon unsuccessful component
941 instantiation attempt, but not the value the component factory
942 returned.
943 <note>
944 In MS COM, there is no equivalent.
945 In XPCOM, it is the same as nsIException::result.
946 </note>
947 </desc>
948 </attribute>
949
950 <attribute name="interfaceID" type="uuid" readonly="yes">
951 <desc>
952 UUID of the interface that defined the error.
953 <note>
954 In MS COM, it is the same as IErrorInfo::GetGUID.
955 In XPCOM, there is no equivalent.
956 </note>
957 </desc>
958 </attribute>
959
960 <attribute name="component" type="wstring" readonly="yes">
961 <desc>
962 Name of the component that generated the error.
963 <note>
964 In MS COM, it is the same as IErrorInfo::GetSource.
965 In XPCOM, there is no equivalent.
966 </note>
967 </desc>
968 </attribute>
969
970 <attribute name="text" type="wstring" readonly="yes">
971 <desc>
972 Text description of the error.
973 <note>
974 In MS COM, it is the same as IErrorInfo::GetDescription.
975 In XPCOM, it is the same as nsIException::message.
976 </note>
977 </desc>
978 </attribute>
979
980 <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
981 <desc>
982 Next error object if there is any, or @c null otherwise.
983 <note>
984 In MS COM, there is no equivalent.
985 In XPCOM, it is the same as nsIException::inner.
986 </note>
987 </desc>
988 </attribute>
989
990 </interface>
991
992
993 <!--
994 // IVirtualBox
995 /////////////////////////////////////////////////////////////////////////
996 -->
997
998 <interface
999 name="IVirtualBoxCallback" extends="$unknown"
1000 uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
1001 wsmap="suppress"
1002 >
1003 <method name="onMachineStateChange">
1004 <desc>
1005 The execution state of the given machine has changed.
1006 <see>IMachine::state</see>
1007 </desc>
1008 <param name="machineId" type="uuid" dir="in">
1009 <desc>ID of the machine this event relates to.</desc>
1010 </param>
1011 <param name="state" type="MachineState" dir="in">
1012 <desc>New execution state.</desc>
1013 </param>
1014 </method>
1015
1016 <method name="onMachineDataChange">
1017 <desc>
1018 Any of the settings of the given machine has changed.
1019 </desc>
1020 <param name="machineId" type="uuid" dir="in">
1021 <desc>ID of the machine this event relates to.</desc>
1022 </param>
1023 </method>
1024
1025 <method name="onExtraDataCanChange">
1026 <desc>
1027 Notification when someone tries to change extra data for
1028 either the given machine or (if null) global extra data.
1029 This gives the chance to veto against changes.
1030 </desc>
1031 <param name="machineId" type="uuid" dir="in">
1032 <desc>
1033 ID of the machine this event relates to
1034 (null ID for global extra data change requests).
1035 </desc>
1036 </param>
1037 <param name="key" type="wstring" dir="in">
1038 <desc>
1039 Extra data key for the attempted write.
1040 </desc>
1041 </param>
1042 <param name="value" type="wstring" dir="in">
1043 <desc>
1044 Extra data value for the given key.
1045 </desc>
1046 </param>
1047 <param name="error" type="wstring" dir="out">
1048 <desc>
1049 Optional error message describing the reason of the
1050 veto (ignored if this notification returns @c true).
1051 </desc>
1052 </param>
1053 <param name="allowChange" type="boolean" dir="return">
1054 <desc>
1055 Flag to indicate whether the callee agrees (@c true)
1056 or vetoes against the change (@c false).
1057 </desc>
1058 </param>
1059 </method>
1060
1061 <method name="onExtraDataChange">
1062 <desc>
1063 Notification when machine specific or global extra data
1064 has changed.
1065 </desc>
1066 <param name="machineId" type="uuid" dir="in">
1067 <desc>
1068 ID of the machine this event relates to.
1069 Null for global extra data changes.
1070 </desc>
1071 </param>
1072 <param name="key" type="wstring" dir="in">
1073 <desc>
1074 Extra data key that has changed.
1075 </desc>
1076 </param>
1077 <param name="value" type="wstring" dir="in">
1078 <desc>
1079 Extra data value for the given key.
1080 </desc>
1081 </param>
1082 </method>
1083
1084 <method name="onMediaRegistered">
1085 <desc>
1086 The given media was registered or unregistered
1087 within this VirtualBox installation.
1088
1089 The @a mediaType parameter describes what type of
1090 media the specified @a mediaId refers to. Possible
1091 values are:
1092
1093 <ul>
1094 <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
1095 that, if registered, can be obtained using the
1096 <link to="IVirtualBox::getHardDisk"/> call.</li>
1097 <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
1098 that, if registered, can be obtained using the
1099 <link to="IVirtualBox::getDVDImage"/> call.</li>
1100 <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
1101 that, if registered, can be obtained using the
1102 <link to="IVirtualBox::getFloppyImage"/> call.</li>
1103 </ul>
1104
1105 Note that if this is a deregistration notification,
1106 there is no way to access the object representing the
1107 unregistered media. It is supposed that the
1108 application will do required cleanup based on the
1109 @a mediaId value.
1110 </desc>
1111 <param name="mediaId" type="uuid" dir="in">
1112 <desc>ID of the media this event relates to.</desc>
1113 </param>
1114 <param name="mediaType" type="DeviceType" dir="in">
1115 <desc>Type of the media this event relates to.</desc>
1116 </param>
1117 <param name="registered" type="boolean" dir="in">
1118 <desc>
1119 If true, the media was registered, otherwise it was
1120 unregistered.
1121 </desc>
1122 </param>
1123 </method>
1124
1125 <method name="onMachineRegistered">
1126 <desc>
1127 The given machine was registered or unregistered
1128 within this VirtualBox installation.
1129 </desc>
1130 <param name="machineId" type="uuid" dir="in">
1131 <desc>ID of the machine this event relates to.</desc>
1132 </param>
1133 <param name="registered" type="boolean" dir="in">
1134 <desc>
1135 If true, the machine was registered, otherwise it was
1136 unregistered.
1137 </desc>
1138 </param>
1139 </method>
1140
1141 <method name="onSessionStateChange">
1142 <desc>
1143 The state of the session for the given machine was changed.
1144 <see>IMachine::sessionState</see>
1145 </desc>
1146 <param name="machineId" type="uuid" dir="in">
1147 <desc>ID of the machine this event relates to.</desc>
1148 </param>
1149 <param name="state" type="SessionState" dir="in">
1150 <desc>New session state.</desc>
1151 </param>
1152 </method>
1153
1154 <method name="onSnapshotTaken">
1155 <desc>
1156 A new snapshot of the machine has been taken.
1157 <see>ISnapshot</see>
1158 </desc>
1159 <param name="machineId" type="uuid" dir="in">
1160 <desc>ID of the machine this event relates to.</desc>
1161 </param>
1162 <param name="snapshotId" type="uuid" dir="in">
1163 <desc>ID of the new snapshot.</desc>
1164 </param>
1165 </method>
1166
1167 <method name="onSnapshotDiscarded">
1168 <desc>
1169 Snapshot of the given machine has been discarded.
1170
1171 <note>
1172 This notification is delivered <b>after</b> the snapshot
1173 object has been uninitialized on the server (so that any
1174 attempt to call its methods will return an error).
1175 </note>
1176
1177 <see>ISnapshot</see>
1178 </desc>
1179 <param name="machineId" type="uuid" dir="in">
1180 <desc>ID of the machine this event relates to.</desc>
1181 </param>
1182 <param name="snapshotId" type="uuid" dir="in">
1183 <desc>
1184 ID of the discarded snapshot. <tt>null</tt> means the
1185 current machine state has been discarded (restored from
1186 the current snapshot).
1187 </desc>
1188 </param>
1189 </method>
1190
1191 <method name="onSnapshotChange">
1192 <desc>
1193 Snapshot properties (name and/or description) have been changed.
1194 <see>ISnapshot</see>
1195 </desc>
1196 <param name="machineId" type="uuid" dir="in">
1197 <desc>ID of the machine this event relates to.</desc>
1198 </param>
1199 <param name="snapshotId" type="uuid" dir="in">
1200 <desc>ID of the changed snapshot.</desc>
1201 </param>
1202 </method>
1203
1204 <method name="onGuestPropertyChange">
1205 <desc>
1206 Notification when a guest property has changed.
1207 </desc>
1208 <param name="machineId" type="uuid" dir="in">
1209 <desc>
1210 ID of the machine this event relates to.
1211 </desc>
1212 </param>
1213 <param name="name" type="wstring" dir="in">
1214 <desc>
1215 The name of the property that has changed.
1216 </desc>
1217 </param>
1218 <param name="value" type="wstring" dir="in">
1219 <desc>
1220 The new property value.
1221 </desc>
1222 </param>
1223 <param name="flags" type="wstring" dir="in">
1224 <desc>
1225 The new property flags.
1226 </desc>
1227 </param>
1228 </method>
1229
1230 </interface>
1231
1232 <interface
1233 name="IDHCPServer" extends="$unknown"
1234 uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
1235 wsmap="managed"
1236 >
1237 <desc>
1238 The IDHCPServer interface represents the vbox dhcp server configuration.
1239
1240 To enumerate all the dhcp servers on the host, use the
1241 <link to="IVirtualBox::DHCPServers"/> attribute.
1242 </desc>
1243
1244 <attribute name="enabled" type="boolean">
1245 <desc>
1246 specifies if the dhcp server is enabled
1247 </desc>
1248 </attribute>
1249
1250 <attribute name="IPAddress" type="wstring" readonly="yes">
1251 <desc>
1252 specifies server IP
1253 </desc>
1254 </attribute>
1255
1256 <attribute name="networkMask" type="wstring" readonly="yes">
1257 <desc>
1258 specifies server network mask
1259 </desc>
1260 </attribute>
1261
1262 <attribute name="networkName" type="wstring" readonly="yes">
1263 <desc>
1264 specifies internal network name the server is used for
1265 </desc>
1266 </attribute>
1267
1268 <attribute name="lowerIP" type="wstring" readonly="yes">
1269 <desc>
1270 specifies from IP adrres in server address range
1271 </desc>
1272 </attribute>
1273
1274 <attribute name="upperIP" type="wstring" readonly="yes">
1275 <desc>
1276 specifies to IP adrres in server address range
1277 </desc>
1278 </attribute>
1279
1280 <method name="setConfiguration">
1281 <desc>
1282 configures the server
1283 <result name="E_INVALIDARG">
1284 invalid configuration supplied
1285 </result>
1286 </desc>
1287 <param name="IPAddress" type="wstring" dir="in">
1288 <desc>
1289 server IP address
1290 </desc>
1291 </param>
1292 <param name="networkMask" type="wstring" dir="in">
1293 <desc>
1294 server network mask
1295 </desc>
1296 </param>
1297 <param name="FromIPAddress" type="wstring" dir="in">
1298 <desc>
1299 server From IP address for address range
1300 </desc>
1301 </param>
1302 <param name="ToIPAddress" type="wstring" dir="in">
1303 <desc>
1304 server To IP address for address range
1305 </desc>
1306 </param>
1307 </method>
1308
1309 <method name="start">
1310 <desc>
1311 Starts DHCP server process.
1312 <result name="E_FAIL">
1313 Failed to start the process.
1314 </result>
1315 </desc>
1316 <param name="networkName" type="wstring" dir="in">
1317 <desc>
1318 Name of internal network DHCP server should attach to.
1319 </desc>
1320 </param>
1321 <param name="trunkName" type="wstring" dir="in">
1322 <desc>
1323 Name of internal network trunk.
1324 </desc>
1325 </param>
1326 <param name="trunkType" type="wstring" dir="in">
1327 <desc>
1328 Type of internal network trunk.
1329 </desc>
1330 </param>
1331 </method>
1332
1333 <method name="stop">
1334 <desc>
1335 Stops DHCP server process.
1336 <result name="E_FAIL">
1337 Failed to stop the process.
1338 </result>
1339 </desc>
1340 </method>
1341 </interface>
1342
1343 <interface
1344 name="IVirtualBox" extends="$dispatched"
1345 uuid="779264f4-65ed-48ed-be39-518ca549e296"
1346 wsmap="managed"
1347 >
1348 <desc>
1349 The IVirtualBox interface represents the main interface exposed by the
1350 product that provides virtual machine management.
1351
1352 An instance of IVirtualBox is required for the product to do anything
1353 useful. Even though the interface does not expose this, internally,
1354 IVirtualBox is implemented as a singleton and actually lives in the
1355 process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1356 IVirtualBox can track the state of all virtual machines on a particular
1357 host, regardless of which frontend started them.
1358
1359 To enumerate all the virtual machines on the host, use the
1360 <link to="IVirtualBox::machines"/> attribute.
1361 </desc>
1362
1363 <attribute name="version" type="wstring" readonly="yes">
1364 <desc>
1365 A string representing the version number of the product. The
1366 format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1367 last number represents the build number and will frequently change.
1368 </desc>
1369 </attribute>
1370
1371 <attribute name="revision" type="unsigned long" readonly="yes">
1372 <desc>
1373 The internal build revision number of the product.
1374 </desc>
1375 </attribute>
1376
1377 <attribute name="packageType" type="wstring" readonly="yes">
1378 <desc>
1379 A string representing the package type of this product. The
1380 format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1381 SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1382 is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1383 this.
1384 </desc>
1385 </attribute>
1386
1387 <attribute name="homeFolder" type="wstring" readonly="yes">
1388 <desc>
1389 Full path to the directory where the global settings file,
1390 <tt>VirtualBox.xml</tt>, is stored.
1391
1392 In this version of VirtualBox, the value of this property is
1393 always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
1394 <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
1395 as determined by the host OS), and cannot be changed.
1396
1397 This path is also used as the base to resolve relative paths in
1398 places where relative paths are allowed (unless otherwise
1399 expressly indicated).
1400 </desc>
1401 </attribute>
1402
1403 <attribute name="settingsFilePath" type="wstring" readonly="yes">
1404 <desc>
1405 Full name of the global settings file.
1406 The value of this property corresponds to the value of
1407 <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1408 </desc>
1409 </attribute>
1410
1411 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
1412 <desc>
1413 Current version of the format of the global VirtualBox settings file
1414 (<tt>VirtualBox.xml</tt>).
1415
1416 The version string has the following format:
1417 <pre>
1418 x.y-platform
1419 </pre>
1420 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1421 versions, and <tt>platform</tt> is the platform identifier.
1422
1423 The current version usually matches the value of the
1424 <link to="#settingsFormatVersion"/> attribute unless the
1425 settings file was created by an older version of VirtualBox and there
1426 was a change of the settings file format since then.
1427
1428 Note that VirtualBox automatically converts settings files from older
1429 versions to the most recent version when reading them (usually at
1430 VirtualBox startup) but it doesn't save the changes back until
1431 you call a method that implicitly saves settings (such as
1432 <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
1433 explicitly. Therefore, if the value of this attribute differs from the
1434 value of <link to="#settingsFormatVersion"/>, then it
1435 means that the settings file was converted but the result of the
1436 conversion is not yet saved to disk.
1437
1438 The above feature may be used by interactive front-ends to inform users
1439 about the settings file format change and offer them to explicitly save
1440 all converted settings files (the global and VM-specific ones),
1441 optionally create backup copies of the old settings files before saving,
1442 etc.
1443
1444 <see>settingsFormatVersion, saveSettingsWithBackup()</see>
1445 </desc>
1446 </attribute>
1447
1448 <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
1449 <desc>
1450 Most recent version of the settings file format.
1451
1452 The version string has the following format:
1453 <pre>
1454 x.y-platform
1455 </pre>
1456 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1457 versions, and <tt>platform</tt> is the platform identifier.
1458
1459 VirtualBox uses this version of the format when saving settings files
1460 (either as a result of method calls that require to save settings or as
1461 a result of an explicit call to <link to="#saveSettings"/>).
1462
1463 <see>settingsFileVersion</see>
1464 </desc>
1465 </attribute>
1466
1467 <attribute name="host" type="IHost" readonly="yes">
1468 <desc>Associated host object.</desc>
1469 </attribute>
1470
1471 <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1472 <desc>Associated system information object.</desc>
1473 </attribute>
1474
1475 <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1476 <desc>
1477 Array of machine objects registered within this VirtualBox instance.
1478 </desc>
1479 </attribute>
1480
1481 <attribute name="hardDisks" type="IHardDisk" readonly="yes" safearray="yes">
1482 <desc>
1483 Array of hard disk objects known to this VirtualBox installation.
1484
1485 This array contains only base (root) hard disks. All differencing
1486 hard disks of the given base hard disk can be enumerated using
1487 <link to="IHardDisk::children"/>.
1488 </desc>
1489 </attribute>
1490
1491 <attribute name="DVDImages" type="IDVDImage" readonly="yes" safearray="yes">
1492 <desc>
1493 Array of CD/DVD image objects registered with this VirtualBox instance.
1494 </desc>
1495 </attribute>
1496
1497 <attribute name="floppyImages" type="IFloppyImage" readonly="yes" safearray="yes">
1498 <desc>
1499 Array of floppy image objects registered with this VirtualBox instance.
1500 </desc>
1501 </attribute>
1502
1503 <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1504
1505 <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1506
1507 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1508 <desc>
1509 Collection of global shared folders. Global shared folders are
1510 available to all virtual machines.
1511
1512 New shared folders are added to the collection using
1513 <link to="#createSharedFolder"/>. Existing shared folders can be
1514 removed using <link to="#removeSharedFolder"/>.
1515
1516 <note>
1517 In the current version of the product, global shared folders are not
1518 implemented and therefore this collection is always empty.
1519 </note>
1520 </desc>
1521 </attribute>
1522
1523 <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1524 <desc>
1525 Associated performance collector object.
1526 </desc>
1527 </attribute>
1528
1529 <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1530 <desc>
1531 dhcp server settings.
1532 </desc>
1533 </attribute>
1534
1535 <method name="createMachine">
1536 <desc>
1537 Creates a new virtual machine.
1538
1539 The new machine is created unregistered, with the initial configuration
1540 set according to the specified guest OS type. A typical sequence of
1541 actions to create a new virtual machine is as follows:
1542
1543 <ol>
1544 <li>
1545 Call this method to have a new machine created. The returned machine
1546 object will be "mutable" allowing to change any machine property.
1547 </li>
1548
1549 <li>
1550 Configure the machine using the appropriate attributes and methods.
1551 </li>
1552
1553 <li>
1554 Call <link to="IMachine::saveSettings" /> to write the settings
1555 to the machine's XML settings file. The configuration of the newly
1556 created machine will not be saved to disk until this method is
1557 called.
1558 </li>
1559
1560 <li>
1561 Call <link to="#registerMachine" /> to add the machine to the list
1562 of machines known to VirtualBox.
1563 </li>
1564 </ol>
1565
1566 You should specify valid name for the newly created machine when calling
1567 this method. See the <link to="IMachine::name"/> attribute description
1568 for more details about the machine name.
1569
1570 The specified guest OS type identifier must match an ID of one of known
1571 guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1572 array.
1573
1574 Every machine has a <i>settings file</i> that is used to store
1575 the machine configuration. This file is stored in a directory called the
1576 <i>machine settings subfolder</i>. Both the settings subfolder and file
1577 will have a name that corresponds to the name of the virtual machine.
1578 You can specify where to create the machine setting subfolder using the
1579 @a baseFolder argument. The base folder can be absolute (full path) or
1580 relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1581 directory</link>.
1582
1583 If @a baseFolder is a null or empty string (which is recommended), the
1584 <link to="ISystemProperties::defaultMachineFolder">default machine
1585 settings folder</link> will be used as a base folder for the created
1586 machine. Otherwise the given base folder will be used. In either case,
1587 the full path to the resulting settings file has the following
1588 structure:
1589 <pre>
1590 &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml
1591 </pre>
1592
1593 Note that if the resulting settings file already exists, this method
1594 will fail with <link to="VBOX_E_FILE_ERROR"/>.
1595
1596 Optionally, you may specify an UUID of to assign to the created machine.
1597 However, this is not recommended and you should normally pass an empty
1598 (null) UUID to this method so that a new UUID will be automatically
1599 generated for every created machine. You can use UUID
1600 00000000-0000-0000-0000-000000000000 as null value.
1601
1602 <note>
1603 There is no way to change the name of the settings file or
1604 subfolder of the created machine directly.
1605 </note>
1606
1607 <result name="VBOX_E_OBJECT_NOT_FOUND">
1608 @a osTypeId is invalid.
1609 </result>
1610 <result name="VBOX_E_FILE_ERROR">
1611 Resulting settings file name is invalid or the settings file already
1612 exists or could not be created due to an I/O error.
1613 </result>
1614 <result name="E_INVALIDARG">
1615 @a name is empty or null.
1616 </result>
1617 </desc>
1618
1619 <param name="name" type="wstring" dir="in">
1620 <desc>Machine name.</desc>
1621 </param>
1622 <param name="osTypeId" type="wstring" dir="in">
1623 <desc>Guest OS Type ID.</desc>
1624 </param>
1625 <param name="baseFolder" type="wstring" dir="in">
1626 <desc>Base machine folder (optional).</desc>
1627 </param>
1628 <param name="id" type="uuid" dir="in">
1629 <desc>Machine UUID (optional).</desc>
1630 </param>
1631 <param name="machine" type="IMachine" dir="return">
1632 <desc>Created machine object.</desc>
1633 </param>
1634 </method>
1635
1636 <method name="createLegacyMachine">
1637 <desc>
1638 Creates a new virtual machine in "legacy" mode, using the specified
1639 settings file to store machine settings.
1640
1641 As opposed to machines created by <link to="#createMachine"/>,
1642 the settings file of the machine created in "legacy" mode is not
1643 automatically renamed when the machine name is changed -- it will always
1644 remain the same as specified in this method call.
1645
1646 The specified settings file name can be absolute (full path) or relative
1647 to the <link to="IVirtualBox::homeFolder">VirtualBox home
1648 directory</link>. If the file name doesn't contain an extension, the
1649 default extension (.xml) will be appended.
1650
1651 Note that the configuration of the newly created machine is not
1652 saved to disk (and therefore no settings file is created)
1653 until <link to="IMachine::saveSettings"/> is called. If the
1654 specified settings file already exists, this method
1655 will fail with <link to="VBOX_E_FILE_ERROR"/>.
1656
1657 See <link to="#createMachine"/> for more information.
1658
1659 @deprecated This method may be removed later. Use <link
1660 to="IVirtualBox::createMachine"/> instead.
1661
1662 <note>
1663 There is no way to change the name of the settings file
1664 of the machine created in "legacy" mode.
1665 </note>
1666
1667 <result name="VBOX_E_OBJECT_NOT_FOUND">
1668 @a osTypeId is invalid.
1669 </result>
1670 <result name="VBOX_E_FILE_ERROR">
1671 @a settingsFile is invalid or the settings file already exists or
1672 could not be created due to an I/O error.
1673 </result>
1674 <result name="E_INVALIDARG">
1675 @a name or @a settingsFile is empty or null.
1676 </result>
1677 </desc>
1678
1679 <param name="name" type="wstring" dir="in">
1680 <desc>Machine name.</desc>
1681 </param>
1682 <param name="osTypeId" type="wstring" dir="in">
1683 <desc>Machine OS Type ID.</desc>
1684 </param>
1685 <param name="settingsFile" type="wstring" dir="in">
1686 <desc>Name of the machine settings file.</desc>
1687 </param>
1688 <param name="id" type="uuid" dir="in">
1689 <desc>Machine UUID (optional).</desc>
1690 </param>
1691 <param name="machine" type="IMachine" dir="return">
1692 <desc>Created machine object.</desc>
1693 </param>
1694 </method>
1695
1696 <method name="openMachine">
1697 <desc>
1698 Opens a virtual machine from the existing settings file.
1699 The opened machine remains unregistered until you call
1700 <link to="#registerMachine"/>.
1701
1702 The specified settings file name can be absolute
1703 (full path) or relative to the <link to="IVirtualBox::homeFolder">
1704 VirtualBox home directory</link>. This file must exist
1705 and must be a valid machine settings file whose contents
1706 will be used to construct the machine object.
1707
1708 @deprecated Will be removed soon.
1709 <result name="VBOX_E_FILE_ERROR">
1710 Settings file name invalid, not found or sharing violation.
1711 </result>
1712 </desc>
1713 <param name="settingsFile" type="wstring" dir="in">
1714 <desc>
1715 Name of the machine settings file.
1716 </desc>
1717 </param>
1718 <param name="machine" type="IMachine" dir="return">
1719 <desc>Opened machine object.</desc>
1720 </param>
1721 <note>
1722 <link to="IMachine::settingsModified"/> will return
1723 false for the created machine, until any of machine settings
1724 are changed.
1725 </note>
1726 </method>
1727
1728 <method name="registerMachine">
1729 <desc>
1730
1731 Registers the machine previously created using
1732 <link to="#createMachine"/> or opened using
1733 <link to="#openMachine"/> within this VirtualBox installation. After
1734 successful method invocation, the
1735 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1736 to all registered callbacks.
1737
1738 <note>
1739 This method implicitly calls <link to="IMachine::saveSettings"/>
1740 to save all current machine settings before registering it.
1741 </note>
1742
1743 <result name="VBOX_E_OBJECT_NOT_FOUND">
1744 No matching virtual machine found.
1745 </result>
1746 <result name="VBOX_E_INVALID_OBJECT_STATE">
1747 Virtual machine was not created within this VirtualBox instance.
1748 </result>
1749
1750 </desc>
1751 <param name="machine" type="IMachine" dir="in"/>
1752 </method>
1753
1754 <method name="getMachine">
1755 <desc>
1756 Attempts to find a virtual machine given its UUID.
1757 To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1758 instead.
1759
1760 <result name="VBOX_E_OBJECT_NOT_FOUND">
1761 Could not find registered machine matching @a id.
1762 </result>
1763
1764 </desc>
1765 <param name="id" type="uuid" dir="in"/>
1766 <param name="machine" type="IMachine" dir="return"/>
1767 </method>
1768
1769 <method name="findMachine">
1770 <desc>
1771 Attempts to find a virtual machine given its name.
1772 To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1773 instead.
1774
1775 <result name="VBOX_E_OBJECT_NOT_FOUND">
1776 Could not find registered machine matching @a name.
1777 </result>
1778
1779 </desc>
1780 <param name="name" type="wstring" dir="in"/>
1781 <param name="machine" type="IMachine" dir="return"/>
1782 </method>
1783
1784 <method name="unregisterMachine">
1785 <desc>
1786
1787 Unregisters the machine previously registered using
1788 <link to="#registerMachine"/>. After successful method invocation, the
1789 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1790 to all registered callbacks.
1791
1792 <note>
1793 The specified machine must not be in the Saved state, have an open
1794 (or a spawning) direct session associated with it, have snapshots or
1795 have hard disks attached.
1796 </note>
1797
1798 <note>
1799 This method implicitly calls <link to="IMachine::saveSettings"/> to
1800 save all current machine settings before unregistering it.
1801 </note>
1802
1803 <note>
1804 If the given machine is inaccessible (see
1805 <link to="IMachine::accessible"/>), it will be unregistered and
1806 fully uninitialized right afterwards. As a result, the returned
1807 machine object will be unusable and an attempt to call
1808 <b>any</b> method will return the "Object not ready" error.
1809 </note>
1810
1811 <result name="VBOX_E_OBJECT_NOT_FOUND">
1812 Could not find registered machine matching @a id.
1813 </result>
1814 <result name="VBOX_E_INVALID_VM_STATE">
1815 Machine is in Saved state.
1816 </result>
1817 <result name="VBOX_E_INVALID_OBJECT_STATE">
1818 Machine has snapshot or open session or hard disk attached.
1819 </result>
1820
1821 </desc>
1822 <param name="id" type="uuid" dir="in">
1823 <desc>UUID of the machine to unregister.</desc>
1824 </param>
1825 <param name="machine" type="IMachine" dir="return">
1826 <desc>Unregistered machine object.</desc>
1827 </param>
1828 </method>
1829
1830 <method name="createAppliance">
1831 <desc>
1832 Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1833 Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1834 machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1835 </desc>
1836 <param name="appliance" type="IAppliance" dir="return">
1837 <desc>New appliance.</desc>
1838 </param>
1839 </method>
1840
1841 <method name="createHardDisk">
1842 <desc>
1843 Creates a new base hard disk object that will use the given storage
1844 format and location for hard disk data.
1845
1846 Note that the actual storage unit is not created by this method. In
1847 order to do it, and before you are able to attach the created hard disk
1848 to virtual machines, you must call one of the following methods to
1849 allocate a format-specific storage unit at the specified location:
1850 <ul>
1851 <li><link to="IHardDisk::createBaseStorage"/></li>
1852 <li><link to="IHardDisk::createDiffStorage"/></li>
1853 </ul>
1854
1855 Some hard disk attributes, such as <link to="IHardDisk::id"/>, may
1856 remain uninitialized until the hard disk storage unit is successfully
1857 created by one of the above methods.
1858
1859 After the storage unit is successfully created, the hard disk gets
1860 remembered by this VirtualBox installation and will be accessible
1861 through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
1862 methods. Remembered root (base) hard disks are also returned as part of
1863 the <link to="#hardDisks"/> array. See IHardDisk for more details.
1864
1865 The list of all storage formats supported by this VirtualBox
1866 installation can be obtained using
1867 <link to="ISystemProperties::hardDiskFormats"/>. If the @a format
1868 attribute is empty or <tt>null</tt> then the default storage format
1869 specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1870 be used for creating a storage unit of the hard disk.
1871
1872 Note that the format of the location string is storage format specific.
1873 See <link to="IMedium::location"/>, IHardDisk and
1874 <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1875
1876 <result name="VBOX_E_OBJECT_NOT_FOUND">
1877 @a format identifier is invalid. See
1878 <link to="ISystemProperties::hardDiskFormats"/>.
1879 </result>
1880 <result name="VBOX_E_FILE_ERROR">
1881 @a location is a not valid file name (for file-based formats only).
1882 </result>
1883 <result name="E_INVALIDARG">
1884 @a format is a null or empty string.
1885 </result>
1886 </desc>
1887 <param name="format" type="wstring" dir="in">
1888 <desc>
1889 Identifier of the storage format to use for the new hard disk.
1890 </desc>
1891 </param>
1892 <param name="location" type="wstring" dir="in">
1893 <desc>
1894 Location of the storage unit for the new hard disk.
1895 </desc>
1896 </param>
1897 <param name="hardDisk" type="IHardDisk" dir="return">
1898 <desc>Created hard disk object.</desc>
1899 </param>
1900 </method>
1901
1902 <method name="openHardDisk">
1903 <desc>
1904 Opens a hard disk from an existing location.
1905
1906 After the hard disk is successfully opened by this method, it gets
1907 remembered by (known to) this VirtualBox installation and will be
1908 accessible through <link to="#getHardDisk"/> and
1909 <link to="#findHardDisk"/> methods. Remembered root (base) hard disks
1910 are also returned as part of the <link to="#hardDisks"/> array and can
1911 be attached to virtual machines. See IHardDisk for more details.
1912
1913 If a differencing hard disk is to be opened by this method, the
1914 operation will succeed only if its parent hard disk and all ancestors,
1915 if any, are already known to this VirtualBox installation (for example,
1916 were opened by this method before).
1917
1918 This method tries to guess the storage format of the specified hard disk
1919 by reading hard disk data at the specified location.
1920
1921 If @a write is ReadWrite (which it should be), the image is opened for
1922 read/write access and must have according permissions, as VirtualBox
1923 may actually write status information into the disk's metadata sections.
1924
1925 Note that write access is required for all typical image usage in VirtualBox,
1926 since VirtualBox may need to write metadata such as a UUID into the image.
1927 The only exception is opening a source image temporarily for copying and
1928 cloning when the image will quickly be closed again.
1929
1930 Note that the format of the location string is storage format specific.
1931 See <link to="IMedium::location"/>, IHardDisk and
1932 <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1933
1934 <result name="VBOX_E_FILE_ERROR">
1935 Invalid hard disk storage file location or could not find the hard
1936 disk at the specified location.
1937 </result>
1938 <result name="VBOX_E_IPRT_ERROR">
1939 Could not get hard disk storage format.
1940 </result>
1941 <result name="E_INVALIDARG">
1942 Invalid hard disk storage format.
1943 </result>
1944
1945 </desc>
1946 <param name="location" type="wstring" dir="in">
1947 <desc>
1948 Location of the storage unit that contains hard disk data in one of
1949 the supported storage formats.
1950 </desc>
1951 </param>
1952 <param name="accessMode" type="AccessMode" dir="in">
1953 <desc>
1954 Determines whether to open the image in read/write or read-only mode.
1955 </desc>
1956 </param>
1957 <param name="hardDisk" type="IHardDisk" dir="return">
1958 <desc>Opened hard disk object.</desc>
1959 </param>
1960 </method>
1961
1962 <method name="getHardDisk" const="yes">
1963 <desc>
1964 Returns a hard disk with the given UUID.
1965
1966 The hard disk with the given UUID must be known to this VirtualBox
1967 installation, i.e. it must be previously created by
1968 <link to="#createHardDisk"/> or opened by <link
1969 to="#openHardDisk"/>, or attached to some known virtual machine.
1970
1971 <result name="VBOX_E_OBJECT_NOT_FOUND">
1972 No hard disk object matching @a id found.
1973 </result>
1974
1975 </desc>
1976 <param name="id" type="uuid" dir="in">
1977 <desc>UUID of the hard disk to look for.</desc>
1978 </param>
1979 <param name="hardDisk" type="IHardDisk" dir="return">
1980 <desc>Found hard disk object.</desc>
1981 </param>
1982 </method>
1983
1984 <method name="findHardDisk">
1985 <desc>
1986 Returns a hard disk that uses the given location to store hard
1987 disk data.
1988
1989 The given hard disk must be known to this VirtualBox installation, i.e.
1990 it must be previously created by
1991 <link to="#createHardDisk"/> or opened by <link
1992 to="#openHardDisk"/>, or attached to some known virtual machine.
1993
1994 The search is done by comparing the value of the @a location argument to
1995 the <link to="IHardDisk::location"/> attribute of each known hard
1996 disk.
1997
1998 For locations represented by file names in the host's file system, the
1999 requested location can be a path relative to the
2000 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2001 only a file name without any path is given, the
2002 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2003 folder</link> will be prepended to the file name before searching. Note
2004 that on case sensitive file systems, a case sensitive comparison is
2005 performed, otherwise the case of symbols in the file path is ignored.
2006
2007 <result name="VBOX_E_OBJECT_NOT_FOUND">
2008 No hard disk object matching @a location found.
2009 </result>
2010
2011 </desc>
2012 <param name="location" type="wstring" dir="in">
2013 <desc>Location string to search for.</desc>
2014 </param>
2015 <param name="hardDisk" type="IHardDisk" dir="return">
2016 <desc>Found hard disk object.</desc>
2017 </param>
2018 </method>
2019
2020 <method name="openDVDImage">
2021 <desc>
2022 Opens a CD/DVD image contained in the specified file of the supported
2023 format and assigns it the given UUID.
2024
2025 After the image is successfully opened by this method, it gets
2026 remembered by (known to) this VirtualBox installation and will be
2027 accessible through <link to="#getDVDImage"/> and
2028 <link to="#findDVDImage"/> methods. Remembered images are also
2029 returned as part of the <link to="#DVDImages"/> array and can be mounted
2030 to virtual machines. See IMedium for more details.
2031
2032 See <link to="IMedium::location"/> to get more details about the format
2033 of the location string.
2034
2035 <note>
2036 Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
2037 </note>
2038
2039 <result name="VBOX_E_FILE_ERROR">
2040 Invalid CD/DVD image file location or could not find the CD/DVD
2041 image at the specified location.
2042 </result>
2043 <result name="VBOX_E_INVALID_OBJECT_STATE">
2044 CD/DVD image already exists in the media registry.
2045 </result>
2046
2047 </desc>
2048 <param name="location" type="wstring" dir="in">
2049 <desc>
2050 Full path to the file that contains a valid CD/DVD image.
2051 </desc>
2052 </param>
2053 <param name="id" type="uuid" dir="in">
2054 <desc>
2055 UUID to assign to the given image within this VirtualBox installation.
2056 If an empty (null) UUID is specified, the system will randomly
2057 generate a new UUID.
2058 </desc>
2059 </param>
2060 <param name="image" type="IDVDImage" dir="return">
2061 <desc>Opened CD/DVD image object.</desc>
2062 </param>
2063 </method>
2064
2065 <method name="getDVDImage">
2066 <desc>
2067 Returns a CD/DVD image with the given UUID.
2068
2069 The image with the given UUID must be known to this VirtualBox
2070 installation, i.e. it must be previously opened by <link
2071 to="#openDVDImage"/>, or mounted to some known virtual machine.
2072
2073 <result name="VBOX_E_OBJECT_NOT_FOUND">
2074 No matching DVD image found in the media registry.
2075 </result>
2076
2077 </desc>
2078 <param name="id" type="uuid" dir="in">
2079 <desc>UUID of the image to look for.</desc>
2080 </param>
2081 <param name="image" type="IDVDImage" dir="return">
2082 <desc>Found CD/DVD image object.</desc>
2083 </param>
2084 </method>
2085
2086 <method name="findDVDImage">
2087 <desc>
2088 Returns a CD/DVD image with the given image location.
2089
2090 The image with the given UUID must be known to this VirtualBox
2091 installation, i.e. it must be previously opened by <link
2092 to="#openDVDImage"/>, or mounted to some known virtual machine.
2093
2094 The search is done by comparing the value of the @a location argument to
2095 the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2096
2097 The requested location can be a path relative to the
2098 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2099 only a file name without any path is given, the
2100 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2101 folder</link> will be prepended to the file name before searching. Note
2102 that on case sensitive file systems, a case sensitive comparison is
2103 performed, otherwise the case in the file path is ignored.
2104
2105 <result name="VBOX_E_FILE_ERROR">
2106 Invalid image file location.
2107 </result>
2108 <result name="VBOX_E_OBJECT_NOT_FOUND">
2109 No matching DVD image found in the media registry.
2110 </result>
2111
2112 </desc>
2113 <param name="location" type="wstring" dir="in">
2114 <desc>CD/DVD image file path to look for.</desc>
2115 </param>
2116 <param name="image" type="IDVDImage" dir="return">
2117 <desc>Found CD/DVD image object.</desc>
2118 </param>
2119 </method>
2120
2121 <method name="openFloppyImage">
2122 <desc>
2123 Opens a floppy image contained in the specified file of the supported
2124 format and assigns it the given UUID.
2125
2126 After the image is successfully opened by this method, it gets
2127 remembered by (known to) this VirtualBox installation and will be
2128 accessible through <link to="#getFloppyImage"/> and
2129 <link to="#findFloppyImage"/> methods. Remembered images are also
2130 returned as part of the <link to="#floppyImages"/> array and can be
2131 mounted to virtual machines. See IMedium for more details.
2132
2133 See <link to="IMedium::location"/> to get more details about the format
2134 of the location string.
2135
2136 <result name="VBOX_E_FILE_ERROR">
2137 Invalid floppy image file location or could not find the floppy
2138 image at the specified location.
2139 </result>
2140 <result name="VBOX_E_INVALID_OBJECT_STATE">
2141 Floppy image already exists in the media registry.
2142 </result>
2143
2144 <note>
2145 Currently, only raw floppy images are supported by VirtualBox.
2146 </note>
2147 </desc>
2148 <param name="location" type="wstring" dir="in">
2149 <desc>
2150 Full path to the file that contains a valid floppy image.
2151 </desc>
2152 </param>
2153 <param name="id" type="uuid" dir="in">
2154 <desc>
2155 UUID to assign to the given image file within this VirtualBox
2156 installation. If an empty (null) UUID is specified, the system will
2157 randomly generate a new UUID.
2158 </desc>
2159 </param>
2160 <param name="image" type="IFloppyImage" dir="return">
2161 <desc>Opened floppy image object.</desc>
2162 </param>
2163 </method>
2164
2165 <method name="getFloppyImage">
2166 <desc>
2167 Returns a floppy image with the given UUID.
2168
2169 The image with the given UUID must be known to this VirtualBox
2170 installation, i.e. it must be previously opened by <link
2171 to="#openFloppyImage"/>, or mounted to some known virtual machine.
2172
2173 <result name="VBOX_E_OBJECT_NOT_FOUND">
2174 No matching floppy image found in the media registry.
2175 </result>
2176
2177 </desc>
2178 <param name="id" type="uuid" dir="in">
2179 <desc>UUID of the image to look for.</desc>
2180 </param>
2181 <param name="image" type="IFloppyImage" dir="return">
2182 <desc>Found floppy image object.</desc>
2183 </param>
2184 </method>
2185
2186 <method name="findFloppyImage">
2187 <desc>
2188 Returns a floppy image with the given image location.
2189
2190 The image with the given UUID must be known to this VirtualBox
2191 installation, i.e. it must be previously opened by <link
2192 to="#openFloppyImage"/>, or mounted to some known virtual machine.
2193
2194 The search is done by comparing the value of the @a location argument to
2195 the <link to="IMedium::location"/> attribute of each known floppy image.
2196
2197 The requested location can be a path relative to the
2198 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2199 only a file name without any path is given, the
2200 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2201 folder</link> will be prepended to the file name before searching. Note
2202 that on case sensitive file systems, a case sensitive comparison is
2203 performed, otherwise the case of symbols in the file path is ignored.
2204
2205 <result name="VBOX_E_FILE_ERROR">
2206 Invalid image file location.
2207 </result>
2208 <result name="VBOX_E_OBJECT_NOT_FOUND">
2209 No matching floppy image found in the media registry.
2210 </result>
2211
2212 </desc>
2213 <param name="location" type="wstring" dir="in">
2214 <desc>Floppy image file path to look for.</desc>
2215 </param>
2216 <param name="image" type="IFloppyImage" dir="return">
2217 <desc>Found floppy image object.</desc>
2218 </param>
2219 </method>
2220
2221 <method name="getGuestOSType">
2222 <desc>
2223 Returns an object describing the specified guest OS type.
2224
2225 The requested guest OS type is specified using a string which is a
2226 mnemonic identifier of the guest operating system, such as
2227 <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2228 particular virtual machine can be read or set using the
2229 <link to="IMachine::OSTypeId"/> attribute.
2230
2231 The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2232 available guest OS type objects. Each object has an
2233 <link to="IGuestOSType::id"/> attribute which contains an identifier of
2234 the guest OS this object describes.
2235
2236 <result name="E_INVALIDARG">
2237 @a id is not a valid Guest OS type.
2238 </result>
2239
2240 </desc>
2241 <param name="id" type="wstring" dir="in">
2242 <desc>Guest OS type ID string.</desc>
2243 </param>
2244 <param name="type" type="IGuestOSType" dir="return">
2245 <desc>Guest OS type object.</desc>
2246 </param>
2247 </method>
2248
2249 <method name="createSharedFolder">
2250 <desc>
2251 Creates a new global shared folder by associating the given logical
2252 name with the given host path, adds it to the collection of shared
2253 folders and starts sharing it. Refer to the description of
2254 <link to="ISharedFolder"/> to read more about logical names.
2255 <note>
2256 In the current implementation, this operation is not
2257 implemented.
2258 </note>
2259 </desc>
2260 <param name="name" type="wstring" dir="in">
2261 <desc>Unique logical name of the shared folder.</desc>
2262 </param>
2263 <param name="hostPath" type="wstring" dir="in">
2264 <desc>Full path to the shared folder in the host file system.</desc>
2265 </param>
2266 <param name="writable" type="boolean" dir="in">
2267 <desc>Whether the share is writable or readonly</desc>
2268 </param>
2269 </method>
2270
2271 <method name="removeSharedFolder">
2272 <desc>
2273 Removes the global shared folder with the given name previously
2274 created by <link to="#createSharedFolder"/> from the collection of
2275 shared folders and stops sharing it.
2276 <note>
2277 In the current implementation, this operation is not
2278 implemented.
2279 </note>
2280 </desc>
2281 <param name="name" type="wstring" dir="in">
2282 <desc>Logical name of the shared folder to remove.</desc>
2283 </param>
2284 </method>
2285
2286 <method name="getNextExtraDataKey">
2287 <desc>
2288 Returns the global extra data key name following the supplied key.
2289
2290 An error is returned if the supplied @a key does not exist. @c NULL is
2291 returned in @a nextKey if the supplied key is the last key. When
2292 supplying @c NULL or an empty string for the @a key, the first key item
2293 is returned in @a nextKey (if there is any). @a nextValue is an optional
2294 parameter and if supplied, the next key's value is returned in it.
2295
2296 <result name="VBOX_E_OBJECT_NOT_FOUND">
2297 Extra data @a key not found.
2298 </result>
2299
2300 </desc>
2301 <param name="key" type="wstring" dir="in">
2302 <desc>Name of the data key to follow.</desc>
2303 </param>
2304 <param name="nextKey" type="wstring" dir="out">
2305 <desc>Name of the next data key.</desc>
2306 </param>
2307 <param name="nextValue" type="wstring" dir="out">
2308 <desc>Value of the next data key.</desc>
2309 </param>
2310 </method>
2311
2312 <method name="getExtraData">
2313 <desc>
2314 Returns associated global extra data.
2315
2316 If the requested data @a key does not exist, this function will
2317 succeed and return @c NULL in the @a value argument.
2318
2319 <result name="VBOX_E_FILE_ERROR">
2320 Settings file not accessible.
2321 </result>
2322 <result name="VBOX_E_XML_ERROR">
2323 Could not parse the settings file.
2324 </result>
2325
2326 </desc>
2327 <param name="key" type="wstring" dir="in">
2328 <desc>Name of the data key to get.</desc>
2329 </param>
2330 <param name="value" type="wstring" dir="return">
2331 <desc>Value of the requested data key.</desc>
2332 </param>
2333 </method>
2334
2335 <method name="setExtraData">
2336 <desc>
2337 Sets associated global extra data.
2338
2339 If you pass @c NULL as a key @a value, the given @a key will be
2340 deleted.
2341
2342 <note>
2343 Before performing the actual data change, this method will ask all
2344 registered callbacks using the
2345 <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2346 notification for a permission. If one of the callbacks refuses the
2347 new value, the change will not be performed.
2348 </note>
2349 <note>
2350 On success, the
2351 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2352 is called to inform all registered callbacks about a successful data
2353 change.
2354 </note>
2355
2356 <result name="VBOX_E_FILE_ERROR">
2357 Settings file not accessible.
2358 </result>
2359 <result name="VBOX_E_XML_ERROR">
2360 Could not parse the settings file.
2361 </result>
2362 <result name="E_ACCESSDENIED">
2363 Modification request refused.
2364 </result>
2365
2366 </desc>
2367 <param name="key" type="wstring" dir="in">
2368 <desc>Name of the data key to set.</desc>
2369 </param>
2370 <param name="value" type="wstring" dir="in">
2371 <desc>Value to assign to the key.</desc>
2372 </param>
2373 </method>
2374
2375 <method name="openSession">
2376 <desc>
2377 Opens a new direct session with the given virtual machine.
2378
2379 A direct session acts as a local lock on the given VM.
2380 There can be only one direct session open at a time for every
2381 virtual machine, protecting the VM from being manipulated by
2382 conflicting actions from different processes. Only after a
2383 direct session has been opened, one can change all VM settings
2384 and execute the VM in the process space of the session object.
2385
2386 Sessions therefore can be compared to mutex semaphores that
2387 lock a given VM for modification and execution.
2388 See <link to="ISession">ISession</link> for details.
2389
2390 <note>Unless you are writing a new VM frontend, you will not
2391 want to execute a VM in the current process. To spawn a new
2392 process that executes a VM, use
2393 <link to="IVirtualBox::openRemoteSession" />
2394 instead.</note>
2395
2396 Upon successful return, the session object can be used to
2397 get access to the machine and to the VM console.
2398
2399 In VirtualBox terminology, the machine becomes "mutable" after
2400 a session has been opened. Note that the "mutable" machine
2401 object, on which you may invoke IMachine methods to change its
2402 settings, will be a different object from the immutable IMachine
2403 objects returned by various IVirtualBox methods. To obtain a
2404 mutable IMachine object (upon which you can invoke settings methods),
2405 use the <link to="ISession::machine" /> attribute.
2406
2407 One must always call <link to="ISession::close" /> to release the
2408 lock on the machine, or the machine's state will eventually be
2409 set to "Aborted".
2410
2411 In other words, to change settings on a machine, the following
2412 sequence is typically performed:
2413
2414 <ol>
2415 <li>Call this method (openSession) to have a machine locked for
2416 the current session.</li>
2417
2418 <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2419
2420 <li>Change the settings of the machine.</li>
2421
2422 <li>Call <link to="IMachine::saveSettings" />.</li>
2423
2424 <li>Close the session by calling <link to="ISession::close"/>.</li>
2425 </ol>
2426
2427 <result name="E_UNEXPECTED">
2428 Virtual machine not registered.
2429 </result>
2430 <result name="E_ACCESSDENIED">
2431 Process not started by OpenRemoteSession.
2432 </result>
2433 <result name="VBOX_E_OBJECT_NOT_FOUND">
2434 No matching virtual machine found.
2435 </result>
2436 <result name="VBOX_E_INVALID_OBJECT_STATE">
2437 Session already open or being opened.
2438 </result>
2439 <result name="VBOX_E_VM_ERROR">
2440 Failed to assign machine to session.
2441 </result>
2442
2443 </desc>
2444 <param name="session" type="ISession" dir="in">
2445 <desc>
2446 Session object that will represent the opened session after
2447 successful method invocation. This object must not represent
2448 the already open session.
2449 <note>
2450 This session will be automatically closed if the
2451 VirtualBox server is terminated for some reason.
2452 </note>
2453 </desc>
2454 </param>
2455 <param name="machineId" type="uuid" dir="in">
2456 <desc>ID of the virtual machine to open a session with.</desc>
2457 </param>
2458 </method>
2459
2460 <method name="openRemoteSession">
2461 <desc>
2462 Spawns a new process that executes a virtual machine (called a
2463 "remote session").
2464
2465 Opening a remote session causes the VirtualBox server to start a new
2466 process that opens a direct session with the given VM. As a result, the
2467 VM is locked by that direct session in the new process, preventing
2468 conflicting changes from other processes. Since sessions act as locks
2469 that prevent conflicting changes, one cannot open a remote session
2470 for a VM that already has another open session (direct or remote), or
2471 is currently in the process of opening one (see <link
2472 to="IMachine::sessionState"/>).
2473
2474 While the remote session still provides some level of control over the
2475 VM execution to the caller (using the <link to="IConsole" /> interface),
2476 not all VM settings are available for modification within the remote
2477 session context.
2478
2479 This operation can take some time (a new VM is started in a new process,
2480 for which memory and other resources need to be set up). Because of this,
2481 an <link to="IProgress" /> is returned to allow the caller to wait for this
2482 asynchronous operation to be completed. Until then, the remote session
2483 object remains in the closed state, and accessing the machine or its
2484 console through it is invalid. It is recommended to use
2485 <link to="IProgress::waitForCompletion" /> or similar calls to wait for
2486 completion.
2487
2488 As with all <link to="ISession" /> objects, it is recommended to call
2489 <link to="ISession::close" /> on the local session object once openRemoteSession()
2490 has been called. However, the session's state (see <link to="ISession::state" />)
2491 will not return to "Closed" until the remote session has also closed (i.e.
2492 until the VM is no longer running). In that case, however, the state of
2493 the session will automatically change back to "Closed".
2494
2495 Currently supported session types (values of the @a type
2496 argument) are:
2497 <ul>
2498 <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
2499 <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
2500 </ul>
2501
2502 The @a environment argument is a string containing definitions of
2503 environment variables in the following format:
2504 @code
2505 NAME[=VALUE]\n
2506 NAME[=VALUE]\n
2507 ...
2508 @endcode
2509 where <tt>\\n</tt> is the new line character. These environment
2510 variables will be appended to the environment of the VirtualBox server
2511 process. If an environment variable exists both in the server process
2512 and in this list, the value from this list takes precedence over the
2513 server's variable. If the value of the environment variable is
2514 omitted, this variable will be removed from the resulting environment.
2515 If the environment string is @c null, the server environment is
2516 inherited by the started process as is.
2517
2518 <see>openExistingSession</see>
2519
2520 <result name="E_UNEXPECTED">
2521 Virtual machine not registered.
2522 </result>
2523 <result name="E_INVALIDARG">
2524 Invalid session type @a type.
2525 </result>
2526 <result name="VBOX_E_OBJECT_NOT_FOUND">
2527 No machine matching @a machineId found.
2528 </result>
2529 <result name="VBOX_E_INVALID_OBJECT_STATE">
2530 Session already open or being opened.
2531 </result>
2532 <result name="VBOX_E_IPRT_ERROR">
2533 Launching process for machine failed.
2534 </result>
2535 <result name="VBOX_E_VM_ERROR">
2536 Failed to assign machine to session.
2537 </result>
2538
2539 </desc>
2540 <param name="session" type="ISession" dir="in">
2541 <desc>
2542 Session object that will represent the opened remote session
2543 after successful method invocation (this object must not
2544 represent an already open session).
2545 </desc>
2546 </param>
2547 <param name="machineId" type="uuid" dir="in">
2548 <desc>ID of the virtual machine to open a session with.</desc>
2549 </param>
2550 <param name="type" type="wstring" dir="in">
2551 <desc>
2552 Type of the remote session (case sensitive).
2553 </desc>
2554 </param>
2555 <param name="environment" type="wstring" dir="in">
2556 <desc>
2557 Environment to pass to the opened session (may be @c null).
2558 </desc>
2559 </param>
2560 <param name="progress" type="IProgress" dir="return">
2561 <desc>Progress object to track the operation completion.</desc>
2562 </param>
2563 </method>
2564
2565 <method name="openExistingSession">
2566 <desc>
2567 Opens a new remote session with the virtual machine for
2568 which a direct session is already open.
2569
2570 The remote session provides some level of control over the VM
2571 execution (using the IConsole interface) to the caller; however,
2572 within the remote session context, not all VM settings are available
2573 for modification.
2574
2575 As opposed to <link to="#openRemoteSession"/>, the number of
2576 remote sessions opened this way is not limited by the API
2577
2578 <note>
2579 It is an error to open a remote session with the machine that
2580 doesn't have an open direct session.
2581 </note>
2582
2583 <result name="E_UNEXPECTED">
2584 Virtual machine not registered.
2585 </result>
2586 <result name="VBOX_E_OBJECT_NOT_FOUND">
2587 No machine matching @a machineId found.
2588 </result>
2589 <result name="VBOX_E_INVALID_OBJECT_STATE">
2590 Session already open or being opened.
2591 </result>
2592 <result name="VBOX_E_INVALID_SESSION_STATE">
2593 Direct session state not Open.
2594 </result>
2595 <result name="VBOX_E_VM_ERROR">
2596 Failed to get console object from direct session or assign
2597 machine to session.
2598 </result>
2599
2600 <see>openRemoteSession</see>
2601 </desc>
2602 <param name="session" type="ISession" dir="in">
2603 <desc>
2604 Session object that will represent the open remote session
2605 after successful method invocation. This object must not
2606 represent an already open session.
2607 <note>
2608 This session will be automatically closed when the peer
2609 (direct) session dies or gets closed.
2610 </note>
2611 </desc>
2612 </param>
2613 <param name="machineId" type="uuid" dir="in">
2614 <desc>ID of the virtual machine to open a session with.</desc>
2615 </param>
2616 </method>
2617
2618 <method name="registerCallback">
2619 <desc>
2620 Registers a new global VirtualBox callback. The methods of the given
2621 callback object will be called by VirtualBox when an appropriate
2622 event occurs.
2623
2624 <result name="E_INVALIDARG">
2625 A @c NULL callback cannot be registered.
2626 </result>
2627
2628 </desc>
2629 <param name="callback" type="IVirtualBoxCallback" dir="in">
2630 <desc>Callback object to register.</desc>
2631 </param>
2632 </method>
2633
2634 <method name="unregisterCallback">
2635 <desc>
2636 Unregisters the previously registered global VirtualBox callback.
2637
2638 <result name="E_INVALIDARG">
2639 Specified @a callback not registered.
2640 </result>
2641
2642 </desc>
2643 <param name="callback" type="IVirtualBoxCallback" dir="in">
2644 <desc>Callback object to unregister.</desc>
2645 </param>
2646 </method>
2647
2648 <method name="waitForPropertyChange">
2649 <desc>
2650 Blocks the caller until any of the properties represented by the
2651 @a what argument changes the value or until the given timeout interval
2652 expires.
2653
2654 The @a what argument is a comma separated list of property masks that
2655 describe properties the caller is interested in. The property mask is
2656 a string in the following format:
2657
2658 <pre>
2659 [[group.]subgroup.]name
2660 </pre>
2661
2662 where @c name is the property name and @c group, @c subgroup are zero
2663 or more property group specifiers. Each element (group or name) in
2664 the property mask may be either a Latin string or an asterisk symbol
2665 (@c "*") which is used to match any string for the given element. A
2666 property mask that doesn't contain asterisk symbols represents a
2667 single fully qualified property name.
2668
2669 Groups in the fully qualified property name go from more generic (the
2670 left-most part) to more specific (the right-most part). The first
2671 element is usually a name of the object the property belongs to. The
2672 second element may be either a property name, or a child object name,
2673 or an index if the preceding element names an object which is one of
2674 many objects of the same type. This way, property names form a
2675 hierarchy of properties. Here are some examples of property names:
2676
2677 <table>
2678 <tr>
2679 <td><tt>VirtualBox.version</tt></td>
2680 <td><link to="IVirtualBox::version"/> property</td>
2681 </tr>
2682 <tr>
2683 <td><tt>Machine.&lt;UUID&gt;.name</tt></td>
2684 <td><link to="IMachine::name"/> property of the machine with the
2685 given UUID</td>
2686 </tr>
2687 </table>
2688
2689 Most property names directly correspond to the properties of objects
2690 (components) provided by the VirtualBox library and may be used to
2691 track changes to these properties. However, there may be
2692 pseudo-property names that don't correspond to any existing object's
2693 property directly, as well as there may be object properties that
2694 don't have a corresponding property name that is understood by this
2695 method, and therefore changes to such properties cannot be
2696 tracked. See individual object's property descriptions to get a
2697 fully qualified property name that can be used with this method (if
2698 any).
2699
2700 There is a special property mask @c "*" (i.e. a string consisting of a
2701 single asterisk symbol) that can be used to match all properties.
2702 Below are more examples of property masks:
2703
2704 <table>
2705 <tr>
2706 <td><tt>VirtualBox.*</tt></td>
2707 <td>Track all properties of the VirtualBox object</td>
2708 </tr>
2709 <tr>
2710 <td><tt>Machine.*.name</tt></td>
2711 <td>Track changes to the <link to="IMachine::name"/> property of
2712 all registered virtual machines</td>
2713 </tr>
2714 </table>
2715
2716 <note>
2717 This function is not implemented in the current version of the
2718 product.
2719 </note>
2720 </desc>
2721 <param name="what" type="wstring" dir="in">
2722 <desc>Comma separated list of property masks.</desc>
2723 </param>
2724 <param name="timeout" type="unsigned long" dir="in">
2725 <desc>
2726 Wait timeout in milliseconds.
2727 Specify -1 for an indefinite wait.
2728 </desc>
2729 </param>
2730 <param name="changed" type="wstring" dir="out">
2731 <desc>
2732 Comma separated list of properties that have been changed and caused
2733 this method to return to the caller.
2734 </desc>
2735 </param>
2736 <param name="values" type="wstring" dir="out">
2737 <desc>Reserved, not currently used.</desc>
2738 </param>
2739 </method>
2740
2741 <method name="saveSettings">
2742 <desc>
2743 Saves the global settings to the global settings file
2744 (<link to="#settingsFilePath"/>).
2745
2746 This method is only useful for explicitly saving the global settings
2747 file after it has been auto-converted from the old format to the most
2748 recent format (see <link to="#settingsFileVersion"/> for details).
2749 Normally, the global settings file is implicitly saved when a global
2750 setting is changed.
2751
2752 <result name="VBOX_E_FILE_ERROR">
2753 Settings file not accessible.
2754 </result>
2755 <result name="VBOX_E_XML_ERROR">
2756 Could not parse the settings file.
2757 </result>
2758
2759 </desc>
2760 </method>
2761
2762 <method name="saveSettingsWithBackup">
2763 <desc>
2764 Creates a backup copy of the global settings file
2765 (<link to="IVirtualBox::settingsFilePath"/>) in case of auto-conversion,
2766 and then calls <link to="IVirtualBox::saveSettings"/>.
2767
2768 Note that the backup copy is created <b>only</b> if the settings file
2769 auto-conversion took place (see <link to="#settingsFileVersion"/> for
2770 details). Otherwise, this call is fully equivalent to
2771 <link to="IVirtualBox::saveSettings"/> and no backup copying is done.
2772
2773 The backup copy is created in the same directory where the original
2774 settings file is located. It is given the following file name:
2775 <pre>
2776 original.xml.x.y-platform.bak
2777 </pre>
2778 where <tt>original.xml</tt> is the original settings file name
2779 (excluding path), and <tt>x.y-platform</tt> is the version of the old
2780 format of the settings file (before auto-conversion).
2781
2782 If the given backup file already exists, this method will try to add the
2783 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
2784 0 to 9) and copy it again until it succeeds. If all suffixes are
2785 occupied, or if any other copy error occurs, this method will return a
2786 failure.
2787
2788 If the copy operation succeeds, the @a bakFileName return argument will
2789 receive a full path to the created backup file (for informational
2790 purposes). Note that this will happen even if the subsequent
2791 <link to="#saveSettings"/> call performed by this method after the
2792 copy operation, fails.
2793
2794 <note>
2795 The VirtualBox API never calls this method. It is intended purely for
2796 the purposes of creating backup copies of the settings files by
2797 front-ends before saving the results of the automatically performed
2798 settings conversion to disk.
2799 </note>
2800
2801 <see>settingsFileVersion</see>
2802
2803 <result name="VBOX_E_FILE_ERROR">
2804 Settings file not accessible.
2805 </result>
2806 <result name="VBOX_E_XML_ERROR">
2807 Could not parse the settings file.
2808 </result>
2809 <result name="VBOX_E_IPRT_ERROR">
2810 Could not copy the settings file.
2811 </result>
2812
2813 </desc>
2814 <param name="bakFileName" type="wstring" dir="return">
2815 <desc>Full path to the created backup copy.</desc>
2816 </param>
2817 </method>
2818
2819 <!--method name="createDHCPServerForInterface">
2820 <desc>
2821 Creates a dhcp server settings to be used for the given interface
2822 <result name="E_INVALIDARG">
2823 Host network interface @a name already exists.
2824 </result>
2825 </desc>
2826 <param name="interface" type="IHostNetworkInterface" dir="in">
2827 <desc>Network Interface</desc>
2828 </param>
2829 <param name="server" type="IDHCPServer" dir="out">
2830 <desc>Dhcp server settings</desc>
2831 </param>
2832 </method-->
2833
2834 <method name="createDHCPServer">
2835 <desc>
2836 Creates a dhcp server settings to be used for the given internal network name
2837 <result name="E_INVALIDARG">
2838 Host network interface @a name already exists.
2839 </result>
2840 </desc>
2841 <param name="name" type="wstring" dir="in">
2842 <desc>server name</desc>
2843 </param>
2844 <param name="server" type="IDHCPServer" dir="return">
2845 <desc>Dhcp server settings</desc>
2846 </param>
2847 </method>
2848
2849 <method name="findDHCPServerByNetworkName">
2850 <desc>
2851 Searches a dhcp server settings to be used for the given internal network name
2852 <result name="E_INVALIDARG">
2853 Host network interface @a name already exists.
2854 </result>
2855
2856 </desc>
2857 <param name="name" type="wstring" dir="in">
2858 <desc>server name</desc>
2859 </param>
2860 <param name="server" type="IDHCPServer" dir="return">
2861 <desc>Dhcp server settings</desc>
2862 </param>
2863 </method>
2864
2865 <!--method name="findDHCPServerForInterface">
2866 <desc>
2867 Searches a dhcp server settings to be used for the given interface
2868 <result name="E_INVALIDARG">
2869 Host network interface @a name already exists.
2870 </result>
2871 </desc>
2872 <param name="interface" type="IHostNetworkInterface" dir="in">
2873 <desc>Network Interface</desc>
2874 </param>
2875 <param name="server" type="IDHCPServer" dir="out">
2876 <desc>Dhcp server settings</desc>
2877 </param>
2878 </method-->
2879
2880 <method name="removeDHCPServer">
2881 <desc>
2882 Removes the dhcp server settings
2883 <result name="E_INVALIDARG">
2884 Host network interface @a name already exists.
2885 </result>
2886 </desc>
2887 <param name="server" type="IDHCPServer" dir="in">
2888 <desc>Dhcp server settings to be removed</desc>
2889 </param>
2890 </method>
2891
2892 </interface>
2893
2894 <!--
2895 // IAppliance
2896 /////////////////////////////////////////////////////////////////////////
2897 -->
2898
2899 <enum
2900 name="CIMOSType"
2901 uuid="86ef5f8c-18b2-4db8-a314-33721b59f89b"
2902 >
2903 <desc>
2904 OVF operating system values according to CIM V2.20 (as of Nov 2008); http://www.dmtf.org/standards/cim/cim_schema_v220
2905 </desc>
2906
2907 <const name="CIMOS_Unknown" value="0" /> <!-- "Unknown" -->
2908 <const name="CIMOS_Other" value="1" /> <!-- "Other" -->
2909 <const name="CIMOS_MACOS" value="2" /> <!-- "MACOS" -->
2910 <const name="CIMOS_ATTUNIX" value="3" /> <!-- "ATTUNIX" -->
2911 <const name="CIMOS_DGUX" value="4" /> <!-- "DGUX" -->
2912 <const name="CIMOS_DECNT" value="5" /> <!-- "DECNT" -->
2913 <const name="CIMOS_Tru64UNIX" value="6" /> <!-- "Tru64 UNIX" -->
2914 <const name="CIMOS_OpenVMS" value="7" /> <!-- "OpenVMS" -->
2915 <const name="CIMOS_HPUX" value="8" /> <!-- "HPUX" -->
2916 <const name="CIMOS_AIX" value="9" /> <!-- "AIX" -->
2917 <const name="CIMOS_MVS" value="10" /> <!-- "MVS" -->
2918 <const name="CIMOS_OS400" value="11" /> <!-- "OS400" -->
2919 <const name="CIMOS_OS2" value="12" /> <!-- "OS/2" -->
2920 <const name="CIMOS_JavaVM" value="13" /> <!-- "JavaVM" -->
2921 <const name="CIMOS_MSDOS" value="14" /> <!-- "MSDOS" -->
2922 <const name="CIMOS_WIN3x" value="15" /> <!-- "WIN3x" -->
2923 <const name="CIMOS_WIN95" value="16" /> <!-- "WIN95" -->
2924 <const name="CIMOS_WIN98" value="17" /> <!-- "WIN98" -->
2925 <const name="CIMOS_WINNT" value="18" /> <!-- "WINNT" -->
2926 <const name="CIMOS_WINCE" value="19" /> <!-- "WINCE" -->
2927 <const name="CIMOS_NCR3000" value="20" /> <!-- "NCR3000" -->
2928 <const name="CIMOS_NetWare" value="21" /> <!-- "NetWare" -->
2929 <const name="CIMOS_OSF" value="22" /> <!-- "OSF" -->
2930 <const name="CIMOS_DCOS" value="23" /> <!-- "DC/OS" -->
2931 <const name="CIMOS_ReliantUNIX" value="24" /> <!-- "Reliant UNIX" -->
2932 <const name="CIMOS_SCOUnixWare" value="25" /> <!-- "SCO UnixWare" -->
2933 <const name="CIMOS_SCOOpenServer" value="26" /> <!-- "SCO OpenServer" -->
2934 <const name="CIMOS_Sequent" value="27" /> <!-- "Sequent" -->
2935 <const name="CIMOS_IRIX" value="28" /> <!-- "IRIX" -->
2936 <const name="CIMOS_Solaris" value="29" /> <!-- "Solaris" -->
2937 <const name="CIMOS_SunOS" value="30" /> <!-- "SunOS" -->
2938 <const name="CIMOS_U6000" value="31" /> <!-- "U6000" -->
2939 <const name="CIMOS_ASERIES" value="32" /> <!-- "ASERIES" -->
2940 <const name="CIMOS_HPNonStopOS" value="33" /> <!-- "HP NonStop OS" -->
2941 <const name="CIMOS_HPNonStopOSS" value="34" /> <!-- "HP NonStop OSS" -->
2942 <const name="CIMOS_BS2000" value="35" /> <!-- "BS2000" -->
2943 <const name="CIMOS_LINUX" value="36" /> <!-- "LINUX" -->
2944 <const name="CIMOS_Lynx" value="37" /> <!-- "Lynx" -->
2945 <const name="CIMOS_XENIX" value="38" /> <!-- "XENIX" -->
2946 <const name="CIMOS_VM" value="39" /> <!-- "VM" -->
2947 <const name="CIMOS_InteractiveUNIX" value="40" /> <!-- "Interactive UNIX" -->
2948 <const name="CIMOS_BSDUNIX" value="41" /> <!-- "BSDUNIX" -->
2949 <const name="CIMOS_FreeBSD" value="42" /> <!-- "FreeBSD" -->
2950 <const name="CIMOS_NetBSD" value="43" /> <!-- "NetBSD" -->
2951 <const name="CIMOS_GNUHurd" value="44" /> <!-- "GNU Hurd" -->
2952 <const name="CIMOS_OS9" value="45" /> <!-- "OS9" -->
2953 <const name="CIMOS_MACHKernel" value="46" /> <!-- "MACH Kernel" -->
2954 <const name="CIMOS_Inferno" value="47" /> <!-- "Inferno" -->
2955 <const name="CIMOS_QNX" value="48" /> <!-- "QNX" -->
2956 <const name="CIMOS_EPOC" value="49" /> <!-- "EPOC" -->
2957 <const name="CIMOS_IxWorks" value="50" /> <!-- "IxWorks" -->
2958 <const name="CIMOS_VxWorks" value="51" /> <!-- "VxWorks" -->
2959 <const name="CIMOS_MiNT" value="52" /> <!-- "MiNT" -->
2960 <const name="CIMOS_BeOS" value="53" /> <!-- "BeOS" -->
2961 <const name="CIMOS_HPMPE" value="54" /> <!-- "HP MPE" -->
2962 <const name="CIMOS_NextStep" value="55" /> <!-- "NextStep" -->
2963 <const name="CIMOS_PalmPilot" value="56" /> <!-- "PalmPilot" -->
2964 <const name="CIMOS_Rhapsody" value="57" /> <!-- "Rhapsody" -->
2965 <const name="CIMOS_Windows2000" value="58" /> <!-- "Windows 2000" -->
2966 <const name="CIMOS_Dedicated" value="59" /> <!-- "Dedicated" -->
2967 <const name="CIMOS_OS390" value="60" /> <!-- "OS/390" -->
2968 <const name="CIMOS_VSE" value="61" /> <!-- "VSE" -->
2969 <const name="CIMOS_TPF" value="62" /> <!-- "TPF" -->
2970 <const name="CIMOS_WindowsMe" value="63" /> <!-- "Windows (R) Me" -->
2971 <const name="CIMOS_CalderaOpenUNIX" value="64" /> <!-- "Caldera Open UNIX" -->
2972 <const name="CIMOS_OpenBSD" value="65" /> <!-- "OpenBSD" -->
2973 <const name="CIMOS_NotApplicable" value="66" /> <!-- "Not Applicable" -->
2974 <const name="CIMOS_WindowsXP" value="67" /> <!-- "Windows XP" -->
2975 <const name="CIMOS_zOS" value="68" /> <!-- "z/OS" -->
2976 <const name="CIMOS_MicrosoftWindowsServer2003" value="69" /> <!-- "Microsoft Windows Server 2003" -->
2977 <const name="CIMOS_MicrosoftWindowsServer2003_64" value="70" /> <!-- "Microsoft Windows Server 2003 64-Bit" -->
2978 <const name="CIMOS_WindowsXP_64" value="71" /> <!-- "Windows XP 64-Bit" -->
2979 <const name="CIMOS_WindowsXPEmbedded" value="72" /> <!-- "Windows XP Embedded" -->
2980 <const name="CIMOS_WindowsVista" value="73" /> <!-- "Windows Vista" -->
2981 <const name="CIMOS_WindowsVista_64" value="74" /> <!-- "Windows Vista 64-Bit" -->
2982 <const name="CIMOS_WindowsEmbeddedforPointofService" value="75" /> <!-- "Windows Embedded for Point of Service" -->
2983 <const name="CIMOS_MicrosoftWindowsServer2008" value="76" /> <!-- "Microsoft Windows Server 2008" -->
2984 <const name="CIMOS_MicrosoftWindowsServer2008_64" value="77" /> <!-- "Microsoft Windows Server 2008 64-Bit" -->
2985 <const name="CIMOS_FreeBSD_64" value="78" /> <!-- "FreeBSD 64-Bit" -->
2986 <const name="CIMOS_RedHatEnterpriseLinux" value="79" /> <!-- "RedHat Enterprise Linux" -->
2987 <const name="CIMOS_RedHatEnterpriseLinux_64" value="80" /> <!-- "RedHat Enterprise Linux 64-Bit" -->
2988 <const name="CIMOS_Solaris_64" value="81" /> <!-- "Solaris 64-Bit" -->
2989 <const name="CIMOS_SUSE" value="82" /> <!-- "SUSE" -->
2990 <const name="CIMOS_SUSE_64" value="83" /> <!-- "SUSE 64-Bit" -->
2991 <const name="CIMOS_SLES" value="84" /> <!-- "SLES" -->
2992 <const name="CIMOS_SLES_64" value="85" /> <!-- "SLES 64-Bit" -->
2993 <const name="CIMOS_NovellOES" value="86" /> <!-- "Novell OES" -->
2994 <const name="CIMOS_NovellLinuxDesktop" value="87" /> <!-- "Novell Linux Desktop" -->
2995 <const name="CIMOS_SunJavaDesktopSystem" value="88" /> <!-- "Sun Java Desktop System" -->
2996 <const name="CIMOS_Mandriva" value="89" /> <!-- "Mandriva" -->
2997 <const name="CIMOS_Mandriva_64" value="90" /> <!-- "Mandriva 64-Bit" -->
2998 <const name="CIMOS_TurboLinux" value="91" /> <!-- "TurboLinux" -->
2999 <const name="CIMOS_TurboLinux_64" value="92" /> <!-- "TurboLinux 64-Bit" -->
3000 <const name="CIMOS_Ubuntu" value="93" /> <!-- "Ubuntu" -->
3001 <const name="CIMOS_Ubuntu_64" value="94" /> <!-- "Ubuntu 64-Bit" -->
3002 <const name="CIMOS_Debian" value="95" /> <!-- "Debian" -->
3003 <const name="CIMOS_Debian_64" value="96" /> <!-- "Debian 64-Bit" -->
3004 <const name="CIMOS_Linux_2_4_x" value="97" /> <!-- "Linux 2.4.x" -->
3005 <const name="CIMOS_Linux_2_4_x_64" value="98" /> <!-- "Linux 2.4.x 64-Bit" -->
3006 <const name="CIMOS_Linux_2_6_x" value="99" /> <!-- "Linux 2.6.x" -->
3007 <const name="CIMOS_Linux_2_6_x_64" value="100" /> <!-- "Linux 2.6.x 64-Bit" -->
3008 <const name="CIMOS_Linux_64" value="101" /> <!-- "Linux 64-Bit" -->
3009 <const name="CIMOS_Other_64" value="102" /> <!-- "Other 64-Bit" -->
3010 </enum>
3011
3012 <enum
3013 name="OVFResourceType"
3014 uuid="646a78d7-6f04-49f4-82c4-75c28a75a4cd"
3015 >
3016 <desc>
3017 OVF resource type (as listed with CIM_ResourceAllocationSettingData; see for example
3018 http://msdn.microsoft.com/en-us/library/cc136877(VS.85).aspx).
3019 </desc>
3020
3021 <const name="Other" value="1" />
3022 <const name="ComputerSystem" value="2" />
3023 <const name="Processor" value="3" />
3024 <const name="Memory" value="4" />
3025 <const name="IDEController" value="5" />
3026 <const name="ParallelSCSIHBA" value="6" />
3027 <const name="FCHBA" value="7" />
3028 <const name="iSCSIHBA" value="8" />
3029 <const name="IBHCA" value="9" />
3030 <const name="EthernetAdapter" value="10" />
3031 <const name="OtherNetworkAdapter" value="11" />
3032 <const name="IOSlot" value="12" />
3033 <const name="IODevice" value="13" />
3034 <const name="FloppyDrive" value="14" />
3035 <const name="CDDrive" value="15" />
3036 <const name="DVDDrive" value="16" />
3037 <const name="HardDisk" value="17" />
3038 <const name="OtherStorageDevice" value="20" />
3039 <const name="USBController" value="23" />
3040 <const name="SoundCard" value="35" />
3041 </enum>
3042
3043 <interface
3044 name="IAppliance" extends="$unknown"
3045 uuid="30bfa6b8-9eda-4b0a-b218-a86813248ccd"
3046 wsmap="managed"
3047 >
3048 <desc>
3049 Represents a platform-independent appliance in OVF format. An instance of this is returned
3050 by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
3051 appliances with VirtualBox.
3052
3053 The OVF standard suggests two different physical file formats:
3054
3055 <ol>
3056 <li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
3057 path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
3058 this descriptor file references other files, as OVF appliances distributed as a set of
3059 files most likely do, those files must be in the same directory as the descriptor file.</li>
3060
3061 <li>If the OVF is distributed as a single file, it must be in TAR format and have the
3062 <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3063 files and optionally other files.
3064
3065 At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3066 be added with a later version.</li>
3067 </ol>
3068
3069 <b>Importing</b> an OVF appliance into VirtualBox as instances of
3070 <link to="IMachine" /> involves the following sequence of API calls:
3071
3072 <ol>
3073 <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3074 </li>
3075
3076 <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3077 would like to import. So long as this file is syntactically valid, this will succeed
3078 and return an instance of IAppliance that contains the parsed data from the OVF file.
3079 </li>
3080
3081 <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3082 contents of the IAppliance attributes accordingly. These can be inspected by a
3083 VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3084 user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3085 instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3086 systems in the OVF, which in turn describe the virtual hardware prescribed by the
3087 OVF (network and hardware adapters, virtual disk images, memory size and so on).
3088 The GUI can then give the user the option to confirm and/or change these suggestions.
3089 </li>
3090
3091 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3092 virtual system to override the suggestions made by the interpret() routine.
3093 </li>
3094
3095 <li>Finally, call <link to="#importMachines" /> to create virtual machines in
3096 VirtualBox as instances of <link to="IMachine" /> that match the information in the
3097 virtual system descriptions.
3098 </li>
3099 </ol>
3100
3101 <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3102
3103 <ol>
3104 <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3105 an empty IAppliance object.
3106 </li>
3107
3108 <li>For each machine you would like to export, call <link to="IMachine::export" />
3109 with the IAppliance object you just created. This creates an instance of
3110 <link to="IVirtualSystemDescription" /> inside the appliance.
3111 </li>
3112
3113 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3114 virtual system to override the suggestions made by the export() routine.
3115 </li>
3116
3117 <li>Finally, call <link to="#write" /> with a path specification to have the OVF
3118 file written.</li>
3119 </ol>
3120
3121 </desc>
3122
3123 <attribute name="path" type="wstring" readonly="yes">
3124 <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3125 the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3126 <link to="#write" /> (for export).
3127 This attribute is empty until one of these methods has been called.
3128 </desc>
3129 </attribute>
3130
3131 <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3132 <desc>
3133 Array of virtual disk definitions. One such description exists for each
3134 disk definition in the OVF; each string array item represents one such piece of
3135 disk information, with the information fields separated by tab (\\t) characters.
3136
3137 The caller should be prepared for additional fields being appended to
3138 this string in future versions of VirtualBox and therefore check for
3139 the number of tabs in the strings returned.
3140
3141 In the current version, the following eight fields are returned per string
3142 in the array:
3143
3144 <ol>
3145 <li>Disk ID (unique string identifier given to disk)</li>
3146
3147 <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3148
3149 <li>Populated size (optional unsigned integer indicating the current size of the
3150 disk; can be approximate; -1 if unspecified)</li>
3151
3152 <li>Format (string identifying the disk format, typically
3153 "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3154
3155 <li>Reference (where to find the disk image, typically a file name; if empty,
3156 then the disk should be created on import)</li>
3157
3158 <li>Image size (optional unsigned integer indicating the size of the image,
3159 which need not necessarily be the same as the values specified above, since
3160 the image may be compressed or sparse; -1 if not specified)</li>
3161
3162 <li>Chunk size (optional unsigned integer if the image is split into chunks;
3163 presently unsupported and always -1)</li>
3164
3165 <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3166 </ol>
3167 </desc>
3168 </attribute>
3169
3170 <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3171 <desc> Array of virtual system descriptions. One such description is created
3172 for each virtual system found in the OVF.
3173 This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3174 (for export) has been called.
3175 </desc>
3176 </attribute>
3177
3178 <method name="read">
3179 <desc>
3180 Reads an OVF file into the appliance object.
3181
3182 This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3183 mere fact that this method returns successfully does not mean that VirtualBox supports all
3184 features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3185 </desc>
3186 <param name="file" type="wstring" dir="in">
3187 <desc>
3188 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3189 on whether the appliance is distributed as a set of files or as a single file, respectively).
3190 </desc>
3191 </param>
3192 </method>
3193
3194 <method name="interpret">
3195 <desc>
3196 Interprets the OVF data that was read when the appliance was constructed. After
3197 calling this method, one can inspect the
3198 <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3199 one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3200 the appliance.
3201
3202 Calling this method is the second step of importing an appliance into VirtualBox;
3203 see <link to="IAppliance" /> for an overview.
3204
3205 After calling this method, one should call <link to="#getWarnings" /> to find out
3206 if problems were encountered during the processing which might later lead to
3207 errors.
3208 </desc>
3209 </method>
3210
3211 <method name="importMachines">
3212 <desc>
3213 Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3214 and other interfaces that match the information contained in the appliance as
3215 closely as possible, as represented by the import instructions in the
3216 <link to="#virtualSystemDescriptions" /> array.
3217
3218 Calling this method is the final step of importing an appliance into VirtualBox;
3219 see <link to="IAppliance" /> for an overview.
3220
3221 Since importing the appliance will most probably involve copying and converting
3222 disk images, which can take a long time, this method operates asynchronously and
3223 returns an IProgress object to allow the caller to monitor the progress.
3224 </desc>
3225
3226 <param name="aProgress" type="IProgress" dir="return">
3227 <desc></desc>
3228 </param>
3229 </method>
3230
3231 <method name="write">
3232 <desc>
3233 Writes the contents of the appliance exports into a new OVF file.
3234
3235 Calling this method is the final step of exporting an appliance from VirtualBox;
3236 see <link to="IAppliance" /> for an overview.
3237
3238 Since exporting the appliance will most probably involve copying and converting
3239 disk images, which can take a long time, this method operates asynchronously and
3240 returns an IProgress object to allow the caller to monitor the progress.
3241 </desc>
3242 <param name="format" type="wstring" dir="in">
3243 <desc>
3244 Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
3245 future versions of VirtualBox may support additional formats.
3246 </desc>
3247 </param>
3248 <param name="path" type="wstring" dir="in">
3249 <desc>
3250 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3251 on whether the appliance is distributed as a set of files or as a single file, respectively).
3252 </desc>
3253 </param>
3254 <param name="aProgress" type="IProgress" dir="return">
3255 <desc></desc>
3256 </param>
3257 </method>
3258
3259 <method name="getWarnings">
3260 <desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3261
3262 <param name="aWarnings" type="wstring" dir="return" safearray="yes">
3263 <desc></desc>
3264 </param>
3265 </method>
3266
3267 </interface>
3268
3269 <enum
3270 name="VirtualSystemDescriptionType"
3271 uuid="aacc58de-5b45-4f82-ae2e-dd9a824fc3b5"
3272 >
3273 <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3274 a configuration value.</desc>
3275
3276 <const name="Ignore" value="1" />
3277 <const name="OS" value="2" />
3278 <const name="Name" value="3" />
3279 <const name="Product" value="4" />
3280 <const name="Vendor" value="5" />
3281 <const name="Version" value="6" />
3282 <const name="ProductUrl" value="7" />
3283 <const name="VendorUrl" value="8" />
3284 <const name="Description" value="9" />
3285 <const name="License" value="10" />
3286 <const name="Miscellaneous" value="11" />
3287 <const name="CPU" value="12" />
3288 <const name="Memory" value="13" />
3289 <const name="HardDiskControllerIDE" value="14" />
3290 <const name="HardDiskControllerSATA" value="15" />
3291 <const name="HardDiskControllerSCSI" value="16" />
3292 <const name="HardDiskImage" value="17" />
3293 <const name="Floppy" value="18" />
3294 <const name="CDROM" value="19" />
3295 <const name="NetworkAdapter" value="20" />
3296 <const name="USBController" value="21" />
3297 <const name="SoundCard" value="22" />
3298
3299 </enum>
3300
3301 <enum
3302 name="VirtualSystemDescriptionValueType"
3303 uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
3304 >
3305 <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
3306 type to fetch.</desc>
3307
3308 <const name="Reference" value="1" />
3309 <const name="Original" value="2" />
3310 <const name="Auto" value="3" />
3311 <const name="ExtraConfig" value="4" />
3312
3313 </enum>
3314
3315 <interface
3316 name="IVirtualSystemDescription" extends="$unknown"
3317 uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
3318 wsmap="managed"
3319 >
3320
3321 <desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3322 After <link to="IAppliance::interpret" /> has been called, that array contains
3323 information about how the virtual systems described in the OVF should best be imported into VirtualBox
3324 virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3325 into VirtualBox.
3326 </desc>
3327
3328 <attribute name="count" type="unsigned long" readonly="yes">
3329 <desc>Return the number of virtual system description entries.</desc>
3330 </attribute>
3331
3332 <method name="getDescription">
3333 <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3334 items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3335
3336 The list below identifies the value sets that are possible depending on the
3337 <link to="VirtualSystemDescriptionType" /> enum value in the array item in aTypes[]. In each case,
3338 the array item with the same index in aOvfValues[] will contain the original value as contained
3339 in the OVF file (just for informational purposes), and the corresponding item in aVboxValues[]
3340 will contain a suggested value to be used for VirtualBox. Depending on the description type,
3341 the aExtraConfigValues[] array item may also be used.
3342
3343 <ul>
3344 <li>
3345 "OS": the guest operating system type. There must be exactly one such array item on import. The
3346 corresponding item in aVboxValues[] contains the suggested guest operating system for VirtualBox.
3347 This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3348 item in aOvfValues[] will contain a numerical value that described the operating system in the OVF
3349 (see <link to="CIMOSType" />).
3350 </li>
3351 <li>
3352 "Name": the name to give to the new virtual machine. There can be at most one such array item;
3353 if none is present on import, then an automatic name will be created from the operating system
3354 type. The correponding item im aOvfValues[] will contain the suggested virtual machine name
3355 from the OVF file, and aVboxValues[] will contain a suggestion for a unique VirtualBox
3356 <link to="IMachine" /> name that does not exist yet.
3357 </li>
3358 <li>
3359 "Description": an arbitrary description.
3360 </li>
3361 <li>
3362 "License": the EULA section from the OVF, if present. It is the responsibility of the calling
3363 code to display such a license for agreement; the Main API does not enforce any such policy.
3364 </li>
3365 <li>
3366 Miscellaneous: reserved for future use.
3367 </li>
3368 <li>
3369 "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3370 </li>
3371 <li>
3372 "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3373 is present on import, then VirtualBox will set a meaningful default based on the operating system
3374 type.
3375 </li>
3376 <li>
3377 "HarddiskControllerIDE": an IDE hard disk controller. There can be at most one such item. This
3378 has no value in aOvfValues[] or aVboxValues[].
3379 The matching item in the aRefs[] array will contain an integer that items of the "Harddisk"
3380 type can use to specify which hard disk controller a virtual disk should be connected to.
3381 </li>
3382 <li>
3383 "HarddiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3384 has no value in aOvfValues[] or aVboxValues[].
3385 The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3386 </li>
3387 <li>
3388 "HarddiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3389 The items in aOvfValues[] and aVboxValues[] will either be "LsiLogic" or "BusLogic".
3390 The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3391 </li>
3392 <li>
3393 "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3394 arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3395
3396 The array item in aOvfValues[] will contain the file specification from the OVF file (without
3397 a path since the image file should be in the same location as the OVF file itself), whereas the
3398 item in aVboxValues[] will contain a qualified path specification to where VirtualBox uses the
3399 hard disk image. This means that on import the image will be copied and converted from the
3400 "ovf" location to the "vbox" location; on export, this will be handled the other way round.
3401 On import, the target image will also be registered with VirtualBox.
3402
3403 The matching item in the aExtraConfigValues[] array must contain a string of the following
3404 format: "controller=&lt;index&gt;;channel=&lt;c&gt;"
3405 In this string, &lt;index&gt; must be an integer specifying the hard disk controller to connect
3406 the image to. That number must be the index of an array item with one of the hard disk controller
3407 types (HarddiskControllerSCSI, HarddiskControllerSATA, HarddiskControllerIDE).
3408 In addition, &lt;c&gt; must specify the channel to use on that controller. For IDE controllers,
3409 this can range from 0-2 (which VirtualBox will interpret as primary master, primary slave,
3410 secondary slave; VirtualBox reserves the secondary master for the CD-ROM drive). For SATA and
3411 SCSI conrollers, the channel can range from 0-29.
3412 </li>
3413 <li>
3414 "NetworkAdapter": a network adapter. The array item in aVboxValues[] will specify the hardware
3415 for the network adapter, whereas the array item in aExtraConfigValues[] will have a string
3416 of the "type=&lt;X&gt;" format, where &lt;X&gt; must be either "NAT" or "Bridged".
3417 </li>
3418 <li>
3419 "USBController": a USB controller. There can be at most one such item. If and only if such an
3420 item ispresent, USB support will be enabled for the new virtual machine.
3421 </li>
3422 <li>
3423 "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3424 present, sound support will be enabled for the new virtual machine. Note that the virtual
3425 machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3426 may be different from the virtual soundcard expected by the appliance.
3427 </li>
3428 </ul>
3429
3430 </desc>
3431
3432 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3433 <desc></desc>
3434 </param>
3435
3436 <param name="aRefs" type="wstring" dir="out" safearray="yes">
3437 <desc></desc>
3438 </param>
3439
3440 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3441 <desc></desc>
3442 </param>
3443
3444 <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
3445 <desc></desc>
3446 </param>
3447
3448 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3449 <desc></desc>
3450 </param>
3451
3452 </method>
3453
3454 <method name="getDescriptionByType">
3455 <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
3456 should be returned.</desc>
3457
3458 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
3459 <desc></desc>
3460 </param>
3461
3462 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3463 <desc></desc>
3464 </param>
3465
3466 <param name="aRefs" type="wstring" dir="out" safearray="yes">
3467 <desc></desc>
3468 </param>
3469
3470 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3471 <desc></desc>
3472 </param>
3473
3474 <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
3475 <desc></desc>
3476 </param>
3477
3478 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3479 <desc></desc>
3480 </param>
3481
3482 </method>
3483
3484 <method name="getValuesByType">
3485 <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
3486 value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
3487 values.</desc>
3488
3489 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
3490 <desc></desc>
3491 </param>
3492
3493 <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
3494 <desc></desc>
3495 </param>
3496
3497 <param name="aValues" type="wstring" dir="return" safearray="yes">
3498 <desc></desc>
3499 </param>
3500
3501 </method>
3502
3503 <method name="setFinalValues">
3504 <desc>
3505 This method allows the appliance's user to change the configuration for the virtual
3506 system descriptions. For each array item returned from <link to="#getDescription" />,
3507 you must pass in one boolean value and one configuration value.
3508
3509 Each item in the boolean array determines whether the particular configuration item
3510 should be enabled.
3511 You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3512 HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3513 and SoundCard.
3514
3515 For the "vbox" and "extra configuration" values, if you pass in the same arrays
3516 as returned in the aVboxValues and aExtraConfigValues arrays from getDescription(),
3517 the configuration remains unchanged. Please see the documentation for getDescription()
3518 for valid configuration values for the individual array item types. If the
3519 corresponding item in the aEnabled array is false, the configuration value is ignored.
3520 </desc>
3521
3522 <param name="aEnabled" type="boolean" dir="in" safearray="yes">
3523 <desc></desc>
3524 </param>
3525
3526 <param name="aVboxValues" type="wstring" dir="in" safearray="yes">
3527 <desc></desc>
3528 </param>
3529
3530 <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3531 <desc></desc>
3532 </param>
3533 </method>
3534
3535 <method name="addDescription">
3536 <desc>
3537 This method adds an additional description entry to the stack of already
3538 available descriptions for this virtual system. This is handy for writing
3539 values which aren't directly supported by VirtualBox. One example would
3540 be the License type of <link to="VirtualSystemDescriptionType" />.
3541 </desc>
3542
3543 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
3544 <desc></desc>
3545 </param>
3546
3547 <param name="aVboxValue" type="wstring" dir="in">
3548 <desc></desc>
3549 </param>
3550
3551 <param name="aExtraConfigValue" type="wstring" dir="in">
3552 <desc></desc>
3553 </param>
3554 </method>
3555 </interface>
3556
3557
3558 <!--
3559 // IMachine
3560 /////////////////////////////////////////////////////////////////////////
3561 -->
3562
3563 <interface
3564 name="IInternalMachineControl" extends="$unknown"
3565 uuid="2c88b969-7a74-4ef3-b95f-8a209a1535f3"
3566 internal="yes"
3567 wsmap="suppress"
3568 >
3569 <method name="updateState">
3570 <desc>
3571 Updates the VM state.
3572 <note>
3573 This operation will also update the settings file with
3574 the correct information about the saved state file
3575 and delete this file from disk when appropriate.
3576 </note>
3577 </desc>
3578 <param name="state" type="MachineState" dir="in"/>
3579 </method>
3580
3581 <method name="getIPCId">
3582 <param name="id" type="wstring" dir="return"/>
3583 </method>
3584
3585 <method name="runUSBDeviceFilters">
3586 <desc>
3587 Asks the server to run USB devices filters of the associated
3588 machine against the given USB device and tell if there is
3589 a match.
3590 <note>
3591 Intended to be used only for remote USB devices. Local
3592 ones don't require to call this method (this is done
3593 implicitly by the Host and USBProxyService).
3594 </note>
3595 </desc>
3596 <param name="device" type="IUSBDevice" dir="in"/>
3597 <param name="matched" type="boolean" dir="out"/>
3598 <param name="maskedInterfaces" type="unsigned long" dir="out"/>
3599 </method>
3600
3601 <method name="captureUSBDevice">
3602 <desc>
3603 Requests a capture of the given host USB device.
3604 When the request is completed, the VM process will
3605 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3606 notification.
3607 </desc>
3608 <param name="id" type="uuid" dir="in"/>
3609 </method>
3610
3611 <method name="detachUSBDevice">
3612 <desc>
3613 Notification that a VM is going to detach (done = false) or has
3614 already detached (done = true) the given USB device.
3615 When the done = true request is completed, the VM process will
3616 get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3617 notification.
3618 <note>
3619 In the done = true case, the server must run its own filters
3620 and filters of all VMs but this one on the detached device
3621 as if it were just attached to the host computer.
3622 </note>
3623 </desc>
3624 <param name="id" type="uuid" dir="in"/>
3625 <param name="done" type="boolean" dir="in"/>
3626 </method>
3627
3628 <method name="autoCaptureUSBDevices">
3629 <desc>
3630 Requests a capture all matching USB devices attached to the host.
3631 When the request is completed, the VM process will
3632 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3633 notification per every captured device.
3634 </desc>
3635 </method>
3636
3637 <method name="detachAllUSBDevices">
3638 <desc>
3639 Notification that a VM that is being powered down. The done
3640 parameter indicates whether which stage of the power down
3641 we're at. When done = false the VM is announcing its
3642 intentions, while when done = true the VM is reporting
3643 what it has done.
3644 <note>
3645 In the done = true case, the server must run its own filters
3646 and filters of all VMs but this one on all detach devices as
3647 if they were just attached to the host computer.
3648 </note>
3649 </desc>
3650 <param name="done" type="boolean" dir="in"/>
3651 </method>
3652
3653 <method name="onSessionEnd">
3654 <desc>
3655 Triggered by the given session object when the session is about
3656 to close normally.
3657 </desc>
3658 <param name="session" type="ISession" dir="in">
3659 <desc>Session that is being closed</desc>
3660 </param>
3661 <param name="progress" type="IProgress" dir="return">
3662 <desc>
3663 Used to wait until the corresponding machine is actually
3664 dissociated from the given session on the server.
3665 Returned only when this session is a direct one.
3666 </desc>
3667 </param>
3668 </method>
3669
3670 <method name="beginSavingState">
3671 <desc>
3672 Called by the VM process to inform the server it wants to
3673 save the current state and stop the VM execution.
3674 </desc>
3675 <param name="progress" type="IProgress" dir="in">
3676 <desc>
3677 Progress object created by the VM process to wait until
3678 the state is saved.
3679 </desc>
3680 </param>
3681 <param name="stateFilePath" type="wstring" dir="out">
3682 <desc>
3683 File path the VM process must save the execution state to.
3684 </desc>
3685 </param>
3686 </method>
3687
3688 <method name="endSavingState">
3689 <desc>
3690 Called by the VM process to inform the server that saving
3691 the state previously requested by #beginSavingState is either
3692 successfully finished or there was a failure.
3693
3694 <result name="VBOX_E_FILE_ERROR">
3695 Settings file not accessible.
3696 </result>
3697 <result name="VBOX_E_XML_ERROR">
3698 Could not parse the settings file.
3699 </result>
3700
3701 </desc>
3702
3703 <param name="success" type="boolean" dir="in">
3704 <desc><tt>true</tt> to indicate success and <tt>false</tt>
3705 otherwise.
3706 </desc>
3707 </param>
3708 </method>
3709
3710 <method name="adoptSavedState">
3711 <desc>
3712 Gets called by IConsole::adoptSavedState.
3713 <result name="VBOX_E_FILE_ERROR">
3714 Invalid saved state file path.
3715 </result>
3716 </desc>
3717 <param name="savedStateFile" type="wstring" dir="in">
3718 <desc>Path to the saved state file to adopt.</desc>
3719 </param>
3720 </method>
3721
3722 <method name="beginTakingSnapshot">
3723 <desc>
3724 Called by the VM process to inform the server it wants to
3725 take a snapshot.
3726
3727 <result name="VBOX_E_FILE_ERROR">
3728 Settings file not accessible.
3729 </result>
3730 <result name="VBOX_E_XML_ERROR">
3731 Could not parse the settings file.
3732 </result>
3733 </desc>
3734 <param name="initiator" type="IConsole" dir="in">
3735 <desc>The console object that initiated this call.</desc>
3736 </param>
3737 <param name="name" type="wstring" dir="in">
3738 <desc>Snapshot name.</desc>
3739 </param>
3740 <param name="description" type="wstring" dir="in">
3741 <desc>Snapshot description.</desc>
3742 </param>
3743 <param name="progress" type="IProgress" dir="in">
3744 <desc>
3745 Progress object created by the VM process to wait until
3746 the state is saved (only for online snapshots).
3747 </desc>
3748 </param>
3749 <param name="stateFilePath" type="wstring" dir="out">
3750 <desc>
3751 File path the VM process must save the execution state to.
3752 </desc>
3753 </param>
3754 <param name="serverProgress" type="IProgress" dir="out">
3755 <desc>
3756 Progress object created by the server process to wait until
3757 the snapshot is taken (VDI diff creation, etc.).
3758 </desc>
3759 </param>
3760 </method>
3761
3762 <method name="endTakingSnapshot">
3763 <desc>
3764 Called by the VM process to inform the server that the snapshot
3765 previously requested by #beginTakingSnapshot is either
3766 successfully taken or there was a failure.
3767 </desc>
3768
3769 <param name="success" type="boolean" dir="in">
3770 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
3771 </param>
3772 </method>
3773
3774 <method name="discardSnapshot">
3775 <desc>
3776 Gets called by IConsole::discardSnapshot.
3777 <result name="VBOX_E_INVALID_OBJECT_STATE">
3778 Snapshot has more than one child snapshot.
3779 </result>
3780 </desc>
3781 <param name="initiator" type="IConsole" dir="in">
3782 <desc>The console object that initiated this call.</desc>
3783 </param>
3784 <param name="id" type="uuid" dir="in">
3785 <desc>UUID of the snapshot to discard.</desc>
3786 </param>
3787 <param name="machineState" type="MachineState" dir="out">
3788 <desc>New machine state after this operation is started.</desc>
3789 </param>
3790 <param name="progress" type="IProgress" dir="return">
3791 <desc>Progress object to track the operation completion.</desc>
3792 </param>
3793 </method>
3794
3795 <method name="discardCurrentState">
3796 <desc>
3797 Gets called by IConsole::discardCurrentState.
3798 <result name="VBOX_E_INVALID_OBJECT_STATE">
3799 Virtual machine does not have any snapshot.
3800 </result>
3801 </desc>
3802 <param name="initiator" type="IConsole" dir="in">
3803 <desc>The console object that initiated this call.</desc>
3804 </param>
3805 <param name="machineState" type="MachineState" dir="out">
3806 <desc>New machine state after this operation is started.</desc>
3807 </param>
3808 <param name="progress" type="IProgress" dir="return">
3809 <desc>Progress object to track the operation completion.</desc>
3810 </param>
3811 </method>
3812
3813 <method name="discardCurrentSnapshotAndState">
3814 <desc>
3815 Gets called by IConsole::discardCurrentSnapshotAndState.
3816 <result name="VBOX_E_INVALID_OBJECT_STATE">
3817 Virtual machine does not have any snapshot.
3818 </result>
3819 </desc>
3820 <param name="initiator" type="IConsole" dir="in">
3821 <desc>The console object that initiated this call.</desc>
3822 </param>
3823 <param name="machineState" type="MachineState" dir="out">
3824 <desc>New machine state after this operation is started.</desc>
3825 </param>
3826 <param name="progress" type="IProgress" dir="return">
3827 <desc>Progress object to track the operation completion.</desc>
3828 </param>
3829 </method>
3830
3831 <method name="pullGuestProperties">
3832 <desc>
3833 Get the list of the guest properties matching a set of patterns along
3834 with their values, time stamps and flags and give responsibility for
3835 managing properties to the console.
3836 </desc>
3837 <param name="name" type="wstring" dir="out" safearray="yes">
3838 <desc>
3839 The names of the properties returned.
3840 </desc>
3841 </param>
3842 <param name="value" type="wstring" dir="out" safearray="yes">
3843 <desc>
3844 The values of the properties returned. The array entries match the
3845 corresponding entries in the @a name array.
3846 </desc>
3847 </param>
3848 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3849 <desc>
3850 The time stamps of the properties returned. The array entries match
3851 the corresponding entries in the @a name array.
3852 </desc>
3853 </param>
3854 <param name="flags" type="wstring" dir="out" safearray="yes">
3855 <desc>
3856 The flags of the properties returned. The array entries match the
3857 corresponding entries in the @a name array.
3858 </desc>
3859 </param>
3860 </method>
3861
3862 <method name="pushGuestProperties">
3863 <desc>
3864 Set the list of the guest properties matching a set of patterns along
3865 with their values, time stamps and flags and return responsibility for
3866 managing properties to IMachine.
3867 </desc>
3868 <param name="name" type="wstring" dir="in" safearray="yes">
3869 <desc>
3870 The names of the properties.
3871 </desc>
3872 </param>
3873 <param name="value" type="wstring" dir="in" safearray="yes">
3874 <desc>
3875 The values of the properties. The array entries match the
3876 corresponding entries in the @a name array.
3877 </desc>
3878 </param>
3879 <param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
3880 <desc>
3881 The time stamps of the properties. The array entries match
3882 the corresponding entries in the @a name array.
3883 </desc>
3884 </param>
3885 <param name="flags" type="wstring" dir="in" safearray="yes">
3886 <desc>
3887 The flags of the properties. The array entries match the
3888 corresponding entries in the @a name array.
3889 </desc>
3890 </param>
3891 </method>
3892 <method name="pushGuestProperty">
3893 <desc>
3894 Update a single guest property in IMachine.
3895 </desc>
3896 <param name="name" type="wstring" dir="in">
3897 <desc>
3898 The name of the property to be updated.
3899 </desc>
3900 </param>
3901 <param name="value" type="wstring" dir="in">
3902 <desc>
3903 The value of the property.
3904 </desc>
3905 </param>
3906 <param name="timestamp" type="unsigned long long" dir="in">
3907 <desc>
3908 The timestamp of the property.
3909 </desc>
3910 </param>
3911 <param name="flags" type="wstring" dir="in">
3912 <desc>
3913 The flags of the property.
3914 </desc>
3915 </param>
3916 </method>
3917
3918 <method name="lockMedia">
3919 <desc>
3920 Locks all media attached to the machine for writing and parents of
3921 attahced different hard disks (if any) for reading. This operation is
3922 atomic so that if it fails no media is actually locked.
3923
3924 This method is intended to be called when the machine is in Starting or
3925 Restoring state. The locked media will be automatically unlocked when
3926 the machine is powered off or crashed.
3927 </desc>
3928 </method>
3929 </interface>
3930
3931 <interface
3932 name="IBIOSSettings" extends="$unknown"
3933 uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3934 wsmap="managed"
3935 >
3936 <desc>
3937 The IBIOSSettings interface represents BIOS settings of the virtual
3938 machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3939 </desc>
3940 <attribute name="logoFadeIn" type="boolean">
3941 <desc>Fade in flag for BIOS logo animation.</desc>
3942 </attribute>
3943
3944 <attribute name="logoFadeOut" type="boolean">
3945 <desc>Fade out flag for BIOS logo animation.</desc>
3946 </attribute>
3947
3948 <attribute name="logoDisplayTime" type="unsigned long">
3949 <desc>BIOS logo display time in milliseconds (0 = default).</desc>
3950 </attribute>
3951
3952 <attribute name="logoImagePath" type="wstring">
3953 <desc>Local file system path for external BIOS image.</desc>
3954 </attribute>
3955
3956 <attribute name="bootMenuMode" type="BIOSBootMenuMode">
3957 <desc>Mode of the BIOS boot device menu.</desc>
3958 </attribute>
3959
3960 <attribute name="ACPIEnabled" type="boolean">
3961 <desc>ACPI support flag.</desc>
3962 </attribute>
3963
3964 <attribute name="IOAPICEnabled" type="boolean">
3965 <desc>
3966 IO APIC support flag. If set, VirtualBox will provide an IO APIC
3967 and support IRQs above 15.
3968 </desc>
3969 </attribute>
3970
3971 <attribute name="timeOffset" type="long long">
3972 <desc>
3973 Offset in milliseconds from the host system time. This allows for
3974 guests running with a different system date/time than the host.
3975 It is equivalent to setting the system date/time in the BIOS except
3976 it is not an absolute value but a relative one. Guest Additions
3977 time synchronization honors this offset.
3978 </desc>
3979 </attribute>
3980
3981 <attribute name="PXEDebugEnabled" type="boolean">
3982 <desc>
3983 PXE debug logging flag. If set, VirtualBox will write extensive
3984 PXE trace information to the release log.
3985 </desc>
3986 </attribute>
3987
3988 </interface>
3989
3990 <interface
3991 name="IMachine" extends="$unknown"
3992 uuid="13420cbb-175a-4456-85d0-301126dfdec7"
3993 wsmap="managed"
3994 >
3995 <desc>
3996 The IMachine interface represents a virtual machine, or guest, created
3997 in VirtualBox.
3998
3999 This interface is used in two contexts. First of all, a collection of
4000 objects implementing this interface is stored in the
4001 <link to="IVirtualBox::machines"/> attribute which lists all the virtual
4002 machines that are currently registered with this VirtualBox
4003 installation. Also, once a session has been opened for the given virtual
4004 machine (e.g. the virtual machine is running), the machine object
4005 associated with the open session can be queried from the session object;
4006 see <link to="ISession"/> for details.
4007
4008 The main role of this interface is to expose the settings of the virtual
4009 machine and provide methods to change various aspects of the virtual
4010 machine's configuration. For machine objects stored in the
4011 <link to="IVirtualBox::machines"/> collection, all attributes are
4012 read-only unless explicitly stated otherwise in individual attribute
4013 and method descriptions. In order to change a machine setting, a session
4014 for this machine must be opened using one of
4015 <link to="IVirtualBox::openSession"/>,
4016 <link to="IVirtualBox::openRemoteSession"/> or
4017 <link to="IVirtualBox::openExistingSession"/> methods. After the
4018 session has been successfully opened, a mutable machine object needs to
4019 be queried from the session object and then the desired settings changes
4020 can be applied to the returned object using IMachine attributes and
4021 methods. See the ISession interface description for more information
4022 about sessions.
4023
4024 Note that the IMachine interface does not provide methods to control
4025 virtual machine execution (such as start the machine, or power it
4026 down) -- these methods are grouped in a separate IConsole
4027 interface. Refer to the IConsole interface description to get more
4028 information about this topic.
4029
4030 <see>ISession, IConsole</see>
4031 </desc>
4032
4033 <attribute name="parent" type="IVirtualBox" readonly="yes">
4034 <desc>Associated parent object.</desc>
4035 </attribute>
4036
4037 <attribute name="accessible" type="boolean" readonly="yes">
4038 <desc>
4039 Whether this virtual machine is currently accessible or not.
4040
4041 The machine is considered to be inaccessible when:
4042 <ul>
4043 <li>It is a registered virtual machine, and
4044 </li>
4045 <li>Its settings file is inaccessible (for example, it is
4046 located on a network share that is not accessible during
4047 VirtualBox startup, or becomes inaccessible later, or if
4048 the settings file can be read but is invalid).
4049 </li>
4050 </ul>
4051
4052 Otherwise, the value of this property is always <tt>true</tt>.
4053
4054 Every time this property is read, the accessibility state of
4055 this machine is re-evaluated. If the returned value is |false|,
4056 the <link to="#accessError"/> property may be used to get the
4057 detailed error information describing the reason of
4058 inaccessibility.
4059
4060 When the machine is inaccessible, only the following properties
4061 can be used on it:
4062 <ul>
4063 <li><link to="#parent"/></li>
4064 <li><link to="#id"/></li>
4065 <li><link to="#settingsFilePath"/></li>
4066 <li><link to="#accessible"/></li>
4067 <li><link to="#accessError"/></li>
4068 </ul>
4069
4070 An attempt to access any other property or method will return
4071 an error.
4072
4073 The only possible action you can perform on an inaccessible
4074 machine is to unregister it using the
4075 <link to="IVirtualBox::unregisterMachine"/> call (or, to check
4076 for the accessibility state once more by querying this
4077 property).
4078
4079 <note>
4080 In the current implementation, once this property returns
4081 <tt>true</tt>, the machine will never become inaccessible
4082 later, even if its settings file cannot be successfully
4083 read/written any more (at least, until the VirtualBox
4084 server is restarted). This limitation may be removed in
4085 future releases.
4086 </note>
4087 </desc>
4088 </attribute>
4089
4090 <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
4091 <desc>
4092 Error information describing the reason of machine
4093 inaccessibility.
4094
4095 Reading this property is only valid after the last call to
4096 <link to="#accessible"/> returned <tt>false</tt> (i.e. the
4097 machine is currently unaccessible). Otherwise, a null
4098 IVirtualBoxErrorInfo object will be returned.
4099 </desc>
4100 </attribute>
4101
4102 <attribute name="name" type="wstring">
4103 <desc>
4104 Name of the virtual machine.
4105
4106 Besides being used for human-readable identification purposes
4107 everywhere in VirtualBox, the virtual machine name is also used
4108 as a name of the machine's settings file and as a name of the
4109 subdirectory this settings file resides in. Thus, every time you
4110 change the value of this property, the settings file will be
4111 renamed once you call <link to="#saveSettings"/> to confirm the
4112 change. The containing subdirectory will be also renamed, but
4113 only if it has exactly the same name as the settings file
4114 itself prior to changing this property (for backward compatibility
4115 with previous API releases). The above implies the following
4116 limitations:
4117 <ul>
4118 <li>The machine name cannot be empty.</li>
4119 <li>The machine name can contain only characters that are valid
4120 file name characters according to the rules of the file
4121 system used to store VirtualBox configuration.</li>
4122 <li>You cannot have two or more machines with the same name
4123 if they use the same subdirectory for storing the machine
4124 settings files.</li>
4125 <li>You cannot change the name of the machine if it is running,
4126 or if any file in the directory containing the settings file
4127 is being used by another running machine or by any other
4128 process in the host operating system at a time when
4129 <link to="#saveSettings"/> is called.
4130 </li>
4131 </ul>
4132 If any of the above limitations are hit, <link to="#saveSettings"/>
4133 will return an appropriate error message explaining the exact
4134 reason and the changes you made to this machine will not be
4135 saved.
4136 <note>
4137 For "legacy" machines created using the
4138 <link to="IVirtualBox::createLegacyMachine"/> call,
4139 the above naming limitations do not apply because the
4140 machine name does not affect the settings file name.
4141 The settings file name remains the same as it was specified
4142 during machine creation and never changes.
4143 </note>
4144 </desc>
4145 </attribute>
4146
4147 <attribute name="description" type="wstring">
4148 <desc>
4149 Description of the virtual machine.
4150
4151 The description attribute can contain any text and is
4152 typically used to describe the hardware and software
4153 configuration of the virtual machine in detail (i.e. network
4154 settings, versions of the installed software and so on).
4155 </desc>
4156 </attribute>
4157
4158 <attribute name="id" type="uuid" readonly="yes">
4159 <desc>UUID of the virtual machine.</desc>
4160 </attribute>
4161
4162 <attribute name="OSTypeId" type="wstring">
4163 <desc>
4164 User-defined identifier of the Guest OS type.
4165 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4166 an IGuestOSType object representing details about the given
4167 Guest OS type.
4168 <note>
4169 This value may differ from the value returned by
4170 <link to="IGuest::OSTypeId"/> if Guest Additions are
4171 installed to the guest OS.
4172 </note>
4173 </desc>
4174 </attribute>
4175
4176 <attribute name="HardwareVersion" type="wstring">
4177 <desc>Hardware version identifier. Internal use only for now.</desc>
4178 </attribute>
4179
4180 <attribute name="CPUCount" type="unsigned long">
4181 <desc>Number of virtual CPUs in the VM. In the current version of the product, this is always 1.</desc>
4182 </attribute>
4183
4184 <attribute name="memorySize" type="unsigned long">
4185 <desc>System memory size in megabytes.</desc>
4186 </attribute>
4187
4188 <attribute name="memoryBalloonSize" type="unsigned long">
4189 <desc>Initial memory balloon size in megabytes.</desc>
4190 </attribute>
4191
4192 <attribute name="statisticsUpdateInterval" type="unsigned long">
4193 <desc>Initial interval to update guest statistics in seconds.</desc>
4194 </attribute>
4195
4196 <attribute name="VRAMSize" type="unsigned long">
4197 <desc>Video memory size in megabytes.</desc>
4198 </attribute>
4199
4200 <attribute name="accelerate3DEnabled" type="boolean" default="false">
4201 <desc>
4202 This setting determines whether VirtualBox allows guests to make use
4203 of the 3D graphics support available on the host. Currently limited
4204 to OpenGL only. </desc>
4205 </attribute>
4206
4207 <attribute name="monitorCount" type="unsigned long">
4208 <desc>
4209 Number of virtual monitors.
4210 <note>
4211 Only effective on Windows XP and later guests with
4212 Guest Additions installed.
4213 </note>
4214 </desc>
4215 </attribute>
4216
4217 <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4218 <desc>Object containing all BIOS settings.</desc>
4219 </attribute>
4220
4221 <attribute name="HWVirtExEnabled" type="TSBool">
4222 <desc>
4223 This setting determines whether VirtualBox will try to make use of
4224 the host CPU's hardware virtualization extensions such as Intel VT-x
4225 and AMD-V. Note that in case such extensions are not available,
4226 they will not be used.
4227 </desc>
4228 </attribute>
4229
4230 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">
4231 <desc>
4232 This setting determines whether VirtualBox will try to make use of
4233 the nested paging extension of Intel VT-x and AMD-V. Note that in case
4234 such extensions are not available, they will not be used.
4235 </desc>
4236 </attribute>
4237
4238 <attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">
4239 <desc>
4240 This setting determines whether VirtualBox will try to make use of
4241 the VPID extension of Intel VT-x. Note that in case such extensions are
4242 not available, they will not be used.
4243 </desc>
4244 </attribute>
4245
4246 <attribute name="PAEEnabled" type="boolean" default="false">
4247 <desc>
4248 This setting determines whether VirtualBox will expose the Physical Address
4249 Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
4250 is not available, it will not be reported.
4251 </desc>
4252 </attribute>
4253
4254 <attribute name="snapshotFolder" type="wstring">
4255 <desc>
4256 Full path to the directory used to store snapshot data
4257 (differencing hard disks and saved state files) of this machine.
4258
4259 The initial value of this property is
4260 <tt>&lt;</tt><link to="#settingsFilePath">
4261 path_to_settings_file</link><tt>&gt;/&lt;</tt>
4262 <link to="#id">machine_uuid</link>
4263 <tt>&gt;</tt>.
4264
4265 Currently, it is an error to try to change this property on
4266 a machine that has snapshots (because this would require to
4267 move possibly large files to a different location).
4268 A separate method will be available for this purpose later.
4269
4270 <note>
4271 Setting this property to <tt>null</tt> will restore the
4272 initial value.
4273 </note>
4274 <note>
4275 When setting this property, the specified path can be
4276 absolute (full path) or relative to the directory where the
4277 <link to="#settingsFilePath">machine settings file</link>
4278 is located. When reading this property, a full path is
4279 always returned.
4280 </note>
4281 <note>
4282 The specified path may not exist, it will be created
4283 when necessary.
4284 </note>
4285 </desc>
4286 </attribute>
4287
4288 <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4289 <desc>VRDP server object.</desc>
4290 </attribute>
4291
4292 <attribute name="hardDiskAttachments" type="IHardDiskAttachment" readonly="yes" safearray="yes">
4293 <desc>Array of hard disks attached to this machine.</desc>
4294 </attribute>
4295
4296 <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
4297 <desc>Associated DVD drive object.</desc>
4298 </attribute>
4299
4300 <attribute name="floppyDrive" type="IFloppyDrive" readonly="yes">
4301 <desc>Associated floppy drive object.</desc>
4302 </attribute>
4303
4304 <attribute name="USBController" type="IUSBController" readonly="yes">
4305 <desc>
4306 Associated USB controller object.
4307
4308 <note>
4309 If USB functionality is not available in the given edition of
4310 VirtualBox, this method will set the result code to @c E_NOTIMPL.
4311 </note>
4312 </desc>
4313 </attribute>
4314
4315 <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4316 <desc>Associated audio adapter, always present.</desc>
4317 </attribute>
4318
4319 <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4320 <desc>Array of storage controllers attached to this machine.</desc>
4321 </attribute>
4322
4323 <attribute name="settingsFilePath" type="wstring" readonly="yes">
4324 <desc>
4325 Full name of the file containing machine settings data.
4326 </desc>
4327 </attribute>
4328
4329 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
4330 <desc>
4331 Current version of the format of the settings file of this machine
4332 (<link to="IMachine::settingsFilePath"/>).
4333
4334 The version string has the following format:
4335 <pre>
4336 x.y-platform
4337 </pre>
4338 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
4339 versions, and <tt>platform</tt> is the platform identifier.
4340
4341 The current version usually matches the value of the
4342 <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
4343 settings file was created by an older version of VirtualBox and there
4344 was a change of the settings file format since then.
4345
4346 Note that VirtualBox automatically converts settings files from older
4347 versions to the most recent version when reading them (usually at
4348 VirtualBox startup) but it doesn't save the changes back until
4349 you call a method that implicitly saves settings (such as
4350 <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
4351 explicitly. Therefore, if the value of this attribute differs from the
4352 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
4353 means that the settings file was converted but the result of the
4354 conversion is not yet saved to disk.
4355
4356 The above feature may be used by interactive front-ends to inform users
4357 about the settings file format change and offer them to explicitly save
4358 all converted settings files (the global and VM-specific ones),
4359 optionally create backup copies of the old settings files before saving,
4360 etc.
4361
4362 <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
4363 </desc>
4364 </attribute>
4365
4366 <attribute name="settingsModified" type="boolean" readonly="yes">
4367 <desc>
4368 Whether the settings of this machine have been modified
4369 (but neither yet saved nor discarded).
4370 <note>
4371 Reading this property is only valid on instances returned
4372 by <link to="ISession::machine"/> and on new machines
4373 created by <link to="IVirtualBox::createMachine"/> or opened
4374 by <link to="IVirtualBox::openMachine"/> but not
4375 yet registered, or on unregistered machines after calling
4376 <link to="IVirtualBox::unregisterMachine"/>. For all other
4377 cases, the settings can never be modified.
4378 </note>
4379 <note>
4380 For newly created unregistered machines, the value of this
4381 property is always TRUE until <link to="#saveSettings"/>
4382 is called (no matter if any machine settings have been
4383 changed after the creation or not). For opened machines
4384 the value is set to FALSE (and then follows to normal rules).
4385 </note>
4386 </desc>
4387 </attribute>
4388
4389 <attribute name="sessionState" type="SessionState" readonly="yes">
4390 <desc>Current session state for this machine.</desc>
4391 </attribute>
4392
4393 <attribute name="sessionType" type="wstring" readonly="yes">
4394 <desc>
4395 Type of the session. If <link to="#sessionState"/> is
4396 SessionSpawning or SessionOpen, this attribute contains the
4397 same value as passed to the
4398 <link to="IVirtualBox::openRemoteSession"/> method in the
4399 @a type parameter. If the session was opened directly using
4400 <link to="IVirtualBox::openSession"/>, or if
4401 <link to="#sessionState"/> is SessionClosed, the value of this
4402 attribute is @c null.
4403 </desc>
4404 </attribute>
4405
4406 <attribute name="sessionPid" type="unsigned long" readonly="yes">
4407 <desc>
4408 Identifier of the session process. This attribute contains the
4409 platform-dependent identifier of the process that has opened a
4410 direct session for this machine using the
4411 <link to="IVirtualBox::openSession"/> call. The returned value
4412 is only valid if <link to="#sessionState"/> is SessionOpen or
4413 SessionClosing (i.e. a session is currently open or being
4414 closed) by the time this property is read.
4415 </desc>
4416 </attribute>
4417
4418 <attribute name="state" type="MachineState" readonly="yes">
4419 <desc>Current execution state of this machine.</desc>
4420 </attribute>
4421
4422 <attribute name="lastStateChange" type="long long" readonly="yes">
4423 <desc>
4424 Time stamp of the last execution state change,
4425 in milliseconds since 1970-01-01 UTC.
4426 </desc>
4427 </attribute>
4428
4429 <attribute name="stateFilePath" type="wstring" readonly="yes">
4430 <desc>
4431 Full path to the file that stores the execution state of
4432 the machine when it is in the <link to="MachineState_Saved"/> state.
4433 <note>
4434 When the machine is not in the Saved state, this attribute
4435 <tt>null</tt>.
4436 </note>
4437 </desc>
4438 </attribute>
4439
4440 <attribute name="logFolder" type="wstring" readonly="yes">
4441 <desc>
4442 Full path to the folder that stores a set of rotated log files
4443 recorded during machine execution. The most recent log file is
4444 named <tt>VBox.log</tt>, the previous log file is
4445 named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4446 in the current version).
4447 </desc>
4448 </attribute>
4449
4450 <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4451 <desc>
4452 Current snapshot of this machine.
4453 <note>
4454 A <tt>null</tt> object is returned if the machine doesn't
4455 have snapshots.
4456 </note>
4457 <see><link to="ISnapshot"/></see>
4458 </desc>
4459 </attribute>
4460
4461 <attribute name="snapshotCount" type="unsigned long" readonly="yes">
4462 <desc>
4463 Number of snapshots taken on this machine. Zero means the
4464 machine doesn't have any snapshots.
4465 </desc>
4466 </attribute>
4467
4468 <attribute name="currentStateModified" type="boolean" readonly="yes">
4469 <desc>
4470 Returns <tt>true</tt> if the current state of the machine is not
4471 identical to the state stored in the current snapshot.
4472
4473 The current state is identical to the current snapshot right
4474 after one of the following calls are made:
4475 <ul>
4476 <li><link to="IConsole::discardCurrentState"/> or
4477 <link to="IConsole::discardCurrentSnapshotAndState"/>
4478 </li>
4479 <li><link to="IConsole::takeSnapshot"/> (issued on a
4480 powered off or saved machine, for which
4481 <link to="#settingsModified"/> returns <tt>false</tt>)
4482 </li>
4483 <li><link to="IMachine::setCurrentSnapshot"/>
4484 </li>
4485 </ul>
4486
4487 The current state remains identical until one of the following
4488 happens:
4489 <ul>
4490 <li>settings of the machine are changed</li>
4491 <li>the saved state is discarded</li>
4492 <li>the current snapshot is discarded</li>
4493 <li>an attempt to execute the machine is made</li>
4494 </ul>
4495
4496 <note>
4497 For machines that don't have snapshots, this property is
4498 always <tt>false</tt>.
4499 </note>
4500 </desc>
4501 </attribute>
4502
4503 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4504 <desc>
4505 Collection of shared folders for this machine (permanent shared
4506 folders). These folders are shared automatically at machine startup
4507 and available only to the guest OS installed within this machine.
4508
4509 New shared folders are added to the collection using
4510 <link to="#createSharedFolder"/>. Existing shared folders can be
4511 removed using <link to="#removeSharedFolder"/>.
4512 </desc>
4513 </attribute>
4514
4515 <attribute name="clipboardMode" type="ClipboardMode">
4516 <desc>
4517 Synchronization mode between the host OS clipboard
4518 and the guest OS clipboard.
4519 </desc>
4520 </attribute>
4521
4522 <attribute name="guestPropertyNotificationPatterns" type="wstring">
4523 <desc>
4524 A comma-separated list of simple glob patterns. Changes to guest
4525 properties whose name matches one of the patterns will generate an
4526 <link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4527 </desc>
4528 </attribute>
4529
4530 <method name="setBootOrder">
4531 <desc>
4532 Puts the given device to the specified position in
4533 the boot order.
4534
4535 To indicate that no device is associated with the given position,
4536 <link to="DeviceType_Null"/> should be used.
4537
4538 @todo setHardDiskBootOrder(), setNetworkBootOrder()
4539
4540 <result name="E_INVALIDARG">
4541 Boot @a position out of range.
4542 </result>
4543 <result name="E_NOTIMPL">
4544 Booting from USB @a device currently not supported.
4545 </result>
4546
4547 </desc>
4548 <param name="position" type="unsigned long" dir="in">
4549 <desc>
4550 Position in the boot order (<tt>1</tt> to the total number of
4551 devices the machine can boot from, as returned by
4552 <link to="ISystemProperties::maxBootPosition"/>).
4553 </desc>
4554 </param>
4555 <param name="device" type="DeviceType" dir="in">
4556 <desc>
4557 The type of the device used to boot at the given position.
4558 </desc>
4559 </param>
4560 </method>
4561
4562 <method name="getBootOrder" const="yes">
4563 <desc>
4564 Returns the device type that occupies the specified
4565 position in the boot order.
4566
4567 @todo [remove?]
4568 If the machine can have more than one device of the returned type
4569 (such as hard disks), then a separate method should be used to
4570 retrieve the individual device that occupies the given position.
4571
4572 If here are no devices at the given position, then
4573 <link to="DeviceType_Null"/> is returned.
4574
4575 @todo getHardDiskBootOrder(), getNetworkBootOrder()
4576
4577 <result name="E_INVALIDARG">
4578 Boot @a position out of range.
4579 </result>
4580
4581 </desc>
4582 <param name="position" type="unsigned long" dir="in">
4583 <desc>
4584 Position in the boot order (<tt>1</tt> to the total number of
4585 devices the machine can boot from, as returned by
4586 <link to="ISystemProperties::maxBootPosition"/>).
4587 </desc>
4588 </param>
4589 <param name="device" type="DeviceType" dir="return">
4590 <desc>
4591 Device at the given position.
4592 </desc>
4593 </param>
4594 </method>
4595
4596 <method name="attachHardDisk">
4597 <desc>
4598 Attaches a virtual hard disk (<link to="IHardDisk" />, identified
4599 by the given UUID @a id) to the given hard disk controller
4600 (<link to="IStorageController" />, identified by @a name),
4601 at the indicated port and device.
4602
4603 For the IDE bus, the @a controllerPort parameter can be either
4604 @c 0 or @c 1, to specify the primary or secondary IDE controller,
4605 respectively. For the primary controller of the IDE bus,
4606 @a device can be either @c 0 or @c 1, to specify the master or the
4607 slave device, respectively. For the secondary IDE controller, the
4608 device number must be @c 1 because VirtualBox reserves the
4609 secondary master for the CD-ROM drive.
4610
4611 For an SATA controller, @a controllerPort must be a number ranging
4612 from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
4613 be a number ranging from @c 0 to @c 15.
4614
4615 For both SCSI and SATA, the @a device parameter is unused and must
4616 be @c 0.
4617
4618 The specified device slot must not have another disk attached to it, or
4619 this method will fail.
4620
4621 See <link to="IHardDisk"/> for more detailed information about
4622 attaching hard disks.
4623
4624 <note>
4625 You cannot attach a hard disk to a running machine. Also, you cannot
4626 attach a hard disk to a newly created machine until this machine's
4627 settings are saved to disk using <link to="#saveSettings"/>.
4628 </note>
4629 <note>
4630 If the hard disk is being attached indirectly, a new differencing hard
4631 disk will implicitly be created for it and attached instead. If the
4632 changes made to the machine settings (including this indirect
4633 attachment) are later cancelled using <link to="#discardSettings"/>,
4634 this implicitly created differencing hard disk will implicitly
4635 be deleted.
4636 </note>
4637
4638 <result name="E_INVALIDARG">
4639 SATA device, SATA port, IDE port or IDE slot out of range.
4640 </result>
4641 <result name="VBOX_E_INVALID_OBJECT_STATE">
4642 Attempt to attach hard disk to an unregistered virtual machine.
4643 </result>
4644 <result name="VBOX_E_INVALID_VM_STATE">
4645 Invalid machine state.
4646 </result>
4647 <result name="VBOX_E_OBJECT_IN_USE">
4648 Hard disk already attached to this or another virtual machine.
4649 </result>
4650
4651 </desc>
4652 <param name="id" type="uuid" dir="in">
4653 <desc>UUID of the hard disk to attach.</desc>
4654 </param>
4655 <param name="name" type="wstring" dir="in">
4656 <desc>Name of the storage controller to attach the hard disk to.</desc>
4657 </param>
4658 <param name="controllerPort" type="long" dir="in">
4659 <desc>Port to attach the hard disk to.</desc>
4660 </param>
4661 <param name="device" type="long" dir="in">
4662 <desc>
4663 Device slot in the given port to attach the hard disk to.
4664 </desc>
4665 </param>
4666 </method>
4667
4668 <method name="getHardDisk" const="yes">
4669 <desc>
4670 Returns the virtual hard disk attached to a device slot of the specified
4671 bus.
4672
4673 Note that if the hard disk was indirectly attached by
4674 <link to="#attachHardDisk"/> to the given device slot then this
4675 method will return not the same object as passed to the
4676 <link to="#attachHardDisk"/> call. See <link to="IHardDisk"/> for
4677 more detailed information about attaching hard disks.
4678
4679 <result name="VBOX_E_OBJECT_NOT_FOUND">
4680 No hard disk attached to given slot/bus.
4681 </result>
4682
4683 </desc>
4684 <param name="name" type="wstring" dir="in">
4685 <desc>Name of the storage controller the hard disk is attached to.</desc>
4686 </param>
4687 <param name="controllerPort" type="long" dir="in">
4688 <desc>Port to query.</desc>
4689 </param>
4690 <param name="device" type="long" dir="in">
4691 <desc>Device slot in the given port to query.</desc>
4692 </param>
4693 <param name="hardDisk" type="IHardDisk" dir="return">
4694 <desc>Attached hard disk object.</desc>
4695 </param>
4696 </method>
4697
4698 <method name="detachHardDisk">
4699 <desc>
4700 Detaches the virtual hard disk attached to a device slot of the
4701 specified bus.
4702
4703 Detaching the hard disk from the virtual machine is deferred. This means
4704 that the hard disk remains associated with the machine when this method
4705 returns and gets actually de-associated only after a successful
4706 <link to="#saveSettings"/> call. See <link to="IHardDisk"/>
4707 for more detailed information about attaching hard disks.
4708
4709 <note>
4710 You cannot detach the hard disk from a running machine.
4711 </note>
4712 <note>
4713 Detaching differencing hard disks implicitly created by <link
4714 to="#attachHardDisk"/> for the indirect attachment using this
4715 method will <b>not</b> implicitly delete them. The
4716 <link to="IHardDisk::deleteStorage"/> operation should be
4717 explicitly performed by the caller after the hard disk is successfully
4718 detached and the settings are saved with
4719 <link to="#saveSettings"/>, if it is the desired action.
4720 </note>
4721
4722 <result name="VBOX_E_INVALID_VM_STATE">
4723 Attempt to detach hard disk from a running virtual machine.
4724 </result>
4725 <result name="VBOX_E_OBJECT_NOT_FOUND">
4726 No hard disk attached to given slot/bus.
4727 </result>
4728 <result name="VBOX_E_NOT_SUPPORTED">
4729 Hard disk format does not support storage deletion.
4730 </result>
4731
4732 </desc>
4733 <param name="name" type="wstring" dir="in">
4734 <desc>name of the storage controller to detach the hard disk from.</desc>
4735 </param>
4736 <param name="controllerPort" type="long" dir="in">
4737 <desc>Port number to detach the hard disk from.</desc>
4738 </param>
4739 <param name="device" type="long" dir="in">
4740 <desc>Device slot number to detach the hard disk from.</desc>
4741 </param>
4742 </method>
4743
4744 <method name="getHardDiskAttachmentsOfController" const="yes">
4745 <desc>
4746 Returns an array of hard disk attachments which are attached to the
4747 the controller with the given name.
4748
4749 <result name="VBOX_E_OBJECT_NOT_FOUND">
4750 A storage controller with given name doesn't exist.
4751 </result>
4752 </desc>
4753 <param name="name" type="wstring" dir="in"/>
4754 <param name="hardDiskAttachments" type="IHardDiskAttachment" safearray="yes" dir="return"/>
4755 </method>
4756
4757 <method name="getNetworkAdapter" const="yes">
4758 <desc>
4759 Returns the network adapter associated with the given slot.
4760 Slots are numbered sequentially, starting with zero. The total
4761 number of adapters per machine is defined by the
4762 <link to="ISystemProperties::networkAdapterCount"/> property,
4763 so the maximum slot number is one less than that property's value.
4764
4765 <result name="E_INVALIDARG">
4766 Invalid @a slot number.
4767 </result>
4768
4769 </desc>
4770 <param name="slot" type="unsigned long" dir="in"/>
4771 <param name="adapter" type="INetworkAdapter" dir="return"/>
4772 </method>
4773
4774 <method name="addStorageController">
4775 <desc>
4776 Adds a new storage controller (SCSI or SATA controller) to the
4777 machine and returns it as an instance of
4778 <link to="IStorageController" />.
4779
4780 @a name identifies the controller for subsequent calls such as
4781 <link to="#getStorageControllerByName" /> or
4782 <link to="#removeStorageController" /> or
4783 <link to="#attachHardDisk" />.
4784
4785 After the controller has been added, you can set its exact
4786 type by setting the <link to="IStorageController::controllerType" />.
4787
4788 <result name="VBOX_E_OBJECT_IN_USE">
4789 A storage controller with given name exists already.
4790 </result>
4791 <result name="E_INVALIDARG">
4792 Invalid @a controllerType.
4793 </result>
4794 </desc>
4795 <param name="name" type="wstring" dir="in"/>
4796 <param name="connectionType" type="StorageBus" dir="in"/>
4797 <param name="controller" type="IStorageController" dir="return"/>
4798 </method>
4799
4800 <method name="getStorageControllerByName" const="yes">
4801 <desc>
4802 Returns a storage controller with the given name.
4803
4804 <result name="VBOX_E_OBJECT_NOT_FOUND">
4805 A storage controller with given name doesn't exist.
4806 </result>
4807 </desc>
4808 <param name="name" type="wstring" dir="in"/>
4809 <param name="storageController" type="IStorageController" dir="return"/>
4810 </method>
4811
4812 <method name="removeStorageController">
4813 <desc>
4814 Removes a storage controller from the machine.
4815
4816 <result name="VBOX_E_OBJECT_NOT_FOUND">
4817 A storage controller with given name doesn't exist.
4818 </result>
4819 </desc>
4820 <param name="name" type="wstring" dir="in"/>
4821 </method>
4822
4823 <method name="getSerialPort" const="yes">
4824 <desc>
4825 Returns the serial port associated with the given slot.
4826 Slots are numbered sequentially, starting with zero. The total
4827 number of serial ports per machine is defined by the
4828 <link to="ISystemProperties::serialPortCount"/> property,
4829 so the maximum slot number is one less than that property's value.
4830
4831 <result name="E_INVALIDARG">
4832 Invalid @a slot number.
4833 </result>
4834
4835 </desc>
4836 <param name="slot" type="unsigned long" dir="in"/>
4837 <param name="port" type="ISerialPort" dir="return"/>
4838 </method>
4839
4840 <method name="getParallelPort" const="yes">
4841 <desc>
4842 Returns the parallel port associated with the given slot.
4843 Slots are numbered sequentially, starting with zero. The total
4844 number of parallel ports per machine is defined by the
4845 <link to="ISystemProperties::parallelPortCount"/> property,
4846 so the maximum slot number is one less than that property's value.
4847
4848 <result name="E_INVALIDARG">
4849 Invalid @a slot number.
4850 </result>
4851
4852 </desc>
4853 <param name="slot" type="unsigned long" dir="in"/>
4854 <param name="port" type="IParallelPort" dir="return"/>
4855 </method>
4856
4857 <method name="getNextExtraDataKey">
4858 <desc>
4859 Returns the machine-specific extra data key name following the
4860 supplied key.
4861
4862 An error is returned if the supplied @a key does not exist. @c NULL is
4863 returned in @a nextKey if the supplied key is the last key. When
4864 supplying @c NULL for the @a key, the first key item is returned in
4865 @a nextKey (if there is any). @a nextValue is an optional parameter and
4866 if supplied, the next key's value is returned in it.
4867
4868 <result name="VBOX_E_OBJECT_NOT_FOUND">
4869 Extra data @a key not found.
4870 </result>
4871
4872 </desc>
4873 <param name="key" type="wstring" dir="in">
4874 <desc>Name of the data key to follow.</desc>
4875 </param>
4876 <param name="nextKey" type="wstring" dir="out">
4877 <desc>Name of the next data key.</desc>
4878 </param>
4879 <param name="nextValue" type="wstring" dir="out">
4880 <desc>Value of the next data key.</desc>
4881 </param>
4882 </method>
4883
4884 <method name="getExtraData">
4885 <desc>
4886 Returns associated machine-specific extra data.
4887
4888 If the requested data @a key does not exist, this function will
4889 succeed and return @c NULL in the @a value argument.
4890
4891 <result name="VBOX_E_FILE_ERROR">
4892 Settings file not accessible.
4893 </result>
4894 <result name="VBOX_E_XML_ERROR">
4895 Could not parse the settings file.
4896 </result>
4897
4898 </desc>
4899 <param name="key" type="wstring" dir="in">
4900 <desc>Name of the data key to get.</desc>
4901 </param>
4902 <param name="value" type="wstring" dir="return">
4903 <desc>Value of the requested data key.</desc>
4904 </param>
4905 </method>
4906
4907 <method name="setExtraData">
4908 <desc>
4909 Sets associated machine-specific extra data.
4910
4911 If you pass @c NULL as a key @a value, the given @a key will be
4912 deleted.
4913
4914 <note>
4915 Before performing the actual data change, this method will ask all
4916 registered callbacks using the
4917 <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
4918 notification for a permission. If one of the callbacks refuses the
4919 new value, the change will not be performed.
4920 </note>
4921 <note>
4922 On success, the
4923 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
4924 is called to inform all registered callbacks about a successful data
4925 change.
4926 </note>
4927 <note>
4928 This method can be called outside the machine session and therefore
4929 it's a caller's responsibility to handle possible race conditions
4930 when several clients change the same key at the same time.
4931 </note>
4932
4933 <result name="VBOX_E_FILE_ERROR">
4934 Settings file not accessible.
4935 </result>
4936 <result name="VBOX_E_XML_ERROR">
4937 Could not parse the settings file.
4938 </result>
4939
4940 </desc>
4941 <param name="key" type="wstring" dir="in">
4942 <desc>Name of the data key to set.</desc>
4943 </param>
4944 <param name="value" type="wstring" dir="in">
4945 <desc>Value to assign to the key.</desc>
4946 </param>
4947 </method>
4948
4949 <method name="saveSettings">
4950 <desc>
4951 Saves any changes to machine settings made since the session
4952 has been opened or a new machine has been created, or since the
4953 last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
4954 For registered machines, new settings become visible to all
4955 other VirtualBox clients after successful invocation of this
4956 method.
4957 <note>
4958 The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
4959 notification event after the configuration has been successfully
4960 saved (only for registered machines).
4961 </note>
4962 <note>
4963 Calling this method is only valid on instances returned
4964 by <link to="ISession::machine"/> and on new machines
4965 created by <link to="IVirtualBox::createMachine"/> but not
4966 yet registered, or on unregistered machines after calling
4967 <link to="IVirtualBox::unregisterMachine"/>.
4968 </note>
4969
4970 <result name="VBOX_E_FILE_ERROR">
4971 Settings file not accessible.
4972 </result>
4973 <result name="VBOX_E_XML_ERROR">
4974 Could not parse the settings file.
4975 </result>
4976 <result name="E_ACCESSDENIED">
4977 Modification request refused.
4978 </result>
4979
4980 </desc>
4981 </method>
4982
4983 <method name="saveSettingsWithBackup">
4984 <desc>
4985 Creates a backup copy of the machine settings file (<link
4986 to="IMachine::settingsFilePath"/>) in case of auto-conversion, and then calls
4987 <link to="IMachine::saveSettings"/>.
4988
4989 Note that the backup copy is created <b>only</b> if the settings file
4990 auto-conversion took place (see <link to="#settingsFileVersion"/> for
4991 details). Otherwise, this call is fully equivalent to
4992 <link to="IMachine::saveSettings"/> and no backup copying is done.
4993
4994 The backup copy is created in the same directory where the original
4995 settings file is located. It is given the following file name:
4996 <pre>
4997 original.xml.x.y-platform.bak
4998 </pre>
4999 where <tt>original.xml</tt> is the original settings file name
5000 (excluding path), and <tt>x.y-platform</tt> is the version of the old
5001 format of the settings file (before auto-conversion).
5002
5003 If the given backup file already exists, this method will try to add the
5004 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
5005 0 to 9) and copy it again until it succeeds. If all suffixes are
5006 occupied, or if any other copy error occurs, this method will return a
5007 failure.
5008
5009 If the copy operation succeeds, the @a bakFileName return argument will
5010 receive a full path to the created backup file (for informational
5011 purposes). Note that this will happen even if the subsequent
5012 <link to="#saveSettings"/> call performed by this method after the
5013 copy operation, fails.
5014
5015 <note>
5016 The VirtualBox API never calls this method. It is intended purely for
5017 the purposes of creating backup copies of the settings files by
5018 front-ends before saving the results of the automatically performed
5019 settings conversion to disk.
5020 </note>
5021
5022 <see>settingsFileVersion</see>
5023
5024 <result name="VBOX_E_FILE_ERROR">
5025 Settings file not accessible.
5026 </result>
5027 <result name="VBOX_E_XML_ERROR">
5028 Could not parse the settings file.
5029 </result>
5030 <result name="VBOX_E_INVALID_VM_STATE">
5031 Virtual machine is not mutable.
5032 </result>
5033 <result name="E_ACCESSDENIED">
5034 Modification request refused.
5035 </result>
5036
5037 </desc>
5038 <param name="bakFileName" type="wstring" dir="return">
5039 <desc>Full path to the created backup copy.</desc>
5040 </param>
5041 </method>
5042
5043 <method name="discardSettings">
5044 <desc>
5045 Discards any changes to the machine settings made since the session
5046 has been opened or since the last call to <link to="#saveSettings"/>
5047 or <link to="#discardSettings"/>.
5048 <note>
5049 Calling this method is only valid on instances returned
5050 by <link to="ISession::machine"/> and on new machines
5051 created by <link to="IVirtualBox::createMachine"/> or
5052 opened by <link to="IVirtualBox::openMachine"/> but not
5053 yet registered, or on unregistered machines after calling
5054 <link to="IVirtualBox::unregisterMachine"/>.
5055 </note>
5056
5057 <result name="VBOX_E_INVALID_VM_STATE">
5058 Virtual machine is not mutable.
5059 </result>
5060
5061 </desc>
5062 </method>
5063
5064 <method name="deleteSettings">
5065 <desc>
5066 Deletes the settings file of this machine from disk.
5067 The machine must not be registered in order for this operation
5068 to succeed.
5069 <note>
5070 <link to="#settingsModified"/> will return TRUE after this
5071 method successfully returns.
5072 </note>
5073 <note>
5074 Calling this method is only valid on instances returned
5075 by <link to="ISession::machine"/> and on new machines
5076 created by <link to="IVirtualBox::createMachine"/> or
5077 opened by <link to="IVirtualBox::openMachine"/> but not
5078 yet registered, or on unregistered machines after calling
5079 <link to="IVirtualBox::unregisterMachine"/>.
5080 </note>
5081 <note>
5082 The deleted machine settings file can be restored (saved again)
5083 by calling <link to="#saveSettings"/>.
5084 </note>
5085
5086 <result name="VBOX_E_INVALID_VM_STATE">
5087 Cannot delete settings of a registered machine or
5088 machine not mutable.
5089 </result>
5090 <result name="VBOX_E_IPRT_ERROR">
5091 Could not delete the settings file.
5092 </result>
5093
5094 </desc>
5095 </method>
5096
5097 <method name="export">
5098 <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
5099 steps required to export VirtualBox machines to OVF.
5100 </desc>
5101
5102 <param name="aAppliance" type="IAppliance" dir="in">
5103 <desc>Appliance to export this machine to.</desc>
5104 </param>
5105 <param name="aDescription" type="IVirtualSystemDescription" dir="return">
5106 <desc>VirtualSystemDescription object which is created for this machine.</desc>
5107 </param>
5108 </method >
5109
5110 <method name="getSnapshot">
5111 <desc>
5112 Returns a snapshot of this machine with the given UUID.
5113 A <tt>null</tt> UUID can be used to obtain the first snapshot
5114 taken on this machine. This is useful if you want to traverse
5115 the whole tree of snapshots starting from the root.
5116
5117 <result name="VBOX_E_OBJECT_NOT_FOUND">
5118 Virtual machine has no snapshots or snapshot not found.
5119 </result>
5120
5121 </desc>
5122 <param name="id" type="uuid" dir="in">
5123 <desc>UUID of the snapshot to get</desc>
5124 </param>
5125 <param name="snapshot" type="ISnapshot" dir="return">
5126 <desc>Snapshot object with the given UUID.</desc>
5127 </param>
5128 </method>
5129
5130 <method name="findSnapshot">
5131 <desc>
5132 Returns a snapshot of this machine with the given name.
5133
5134 <result name="VBOX_E_OBJECT_NOT_FOUND">
5135 Virtual machine has no snapshots or snapshot not found.
5136 </result>
5137
5138 </desc>
5139 <param name="name" type="wstring" dir="in">
5140 <desc>Name of the snapshot to find</desc>
5141 </param>
5142 <param name="snapshot" type="ISnapshot" dir="return">
5143 <desc>Snapshot object with the given name.</desc>
5144 </param>
5145 </method>
5146
5147 <method name="setCurrentSnapshot">
5148 <desc>
5149 Sets the current snapshot of this machine.
5150 <note>
5151 In the current implementation, this operation is not
5152 implemented.
5153 </note>
5154 </desc>
5155 <param name="id" type="uuid" dir="in">
5156 <desc>UUID of the snapshot to set as the current snapshot.</desc>
5157 </param>
5158 </method>
5159
5160 <method name="createSharedFolder">
5161 <desc>
5162 Creates a new permanent shared folder by associating the given logical
5163 name with the given host path, adds it to the collection of shared
5164 folders and starts sharing it. Refer to the description of
5165 <link to="ISharedFolder"/> to read more about logical names.
5166
5167 <result name="VBOX_E_OBJECT_IN_USE">
5168 Shared folder already exists.
5169 </result>
5170 <result name="VBOX_E_FILE_ERROR">
5171 Shared folder @a hostPath not accessible.
5172 </result>
5173
5174 </desc>
5175 <param name="name" type="wstring" dir="in">
5176 <desc>Unique logical name of the shared folder.</desc>
5177 </param>
5178 <param name="hostPath" type="wstring" dir="in">
5179 <desc>Full path to the shared folder in the host file system.</desc>
5180 </param>
5181 <param name="writable" type="boolean" dir="in">
5182 <desc>Whether the share is writable or readonly</desc>
5183 </param>
5184 </method>
5185
5186 <method name="removeSharedFolder">
5187 <desc>
5188 Removes the permanent shared folder with the given name previously
5189 created by <link to="#createSharedFolder"/> from the collection of
5190 shared folders and stops sharing it.
5191
5192 <result name="VBOX_E_INVALID_VM_STATE">
5193 Virtual machine is not mutable.
5194 </result>
5195 <result name="VBOX_E_OBJECT_NOT_FOUND">
5196 Shared folder @a name does not exist.
5197 </result>
5198
5199 </desc>
5200 <param name="name" type="wstring" dir="in">
5201 <desc>Logical name of the shared folder to remove.</desc>
5202 </param>
5203 </method>
5204
5205 <method name="canShowConsoleWindow">
5206 <desc>
5207 Returns @c true if the VM console process can activate the
5208 console window and bring it to foreground on the desktop of
5209 the host PC.
5210 <note>
5211 This method will fail if a session for this machine is not
5212 currently open.
5213 </note>
5214
5215 <result name="VBOX_E_INVALID_VM_STATE">
5216 Machine session is not open.
5217 </result>
5218
5219 </desc>
5220 <param name="canShow" type="boolean" dir="return">
5221 <desc>
5222 @c true if the console window can be shown and @c
5223 false otherwise.
5224 </desc>
5225 </param>
5226 </method>
5227
5228 <method name="showConsoleWindow">
5229 <desc>
5230 Activates the console window and brings it to foreground on
5231 the desktop of the host PC. Many modern window managers on
5232 many platforms implement some sort of focus stealing
5233 prevention logic, so that it may be impossible to activate
5234 a window without the help of the currently active
5235 application. In this case, this method will return a non-zero
5236 identifier that represents the top-level window of the VM
5237 console process. The caller, if it represents a currently
5238 active process, is responsible to use this identifier (in a
5239 platform-dependent manner) to perform actual window
5240 activation.
5241 <note>
5242 This method will fail if a session for this machine is not
5243 currently open.
5244 </note>
5245
5246 <result name="VBOX_E_INVALID_VM_STATE">
5247 Machine session is not open.
5248 </result>
5249
5250 </desc>
5251 <param name="winId" type="unsigned long long" dir="return">
5252 <desc>
5253 Platform-dependent identifier of the top-level VM console
5254 window, or zero if this method has performed all actions
5255 necessary to implement the <i>show window</i> semantics for
5256 the given platform and/or VirtualBox front-end.
5257 </desc>
5258 </param>
5259 </method>
5260
5261 <method name="getGuestProperty">
5262 <desc>
5263 Reads an entry from the machine's guest property store.
5264
5265 <result name="VBOX_E_INVALID_VM_STATE">
5266 Machine session is not open.
5267 </result>
5268
5269 </desc>
5270 <param name="name" type="wstring" dir="in">
5271 <desc>
5272 The name of the property to read.
5273 </desc>
5274 </param>
5275 <param name="value" type="wstring" dir="out">
5276 <desc>
5277 The value of the property. If the property does not exist then this
5278 will be empty.
5279 </desc>
5280 </param>
5281 <param name="timestamp" type="unsigned long long" dir="out">
5282 <desc>
5283 The time at which the property was last modified, as seen by the
5284 server process.
5285 </desc>
5286 </param>
5287 <param name="flags" type="wstring" dir="out">
5288 <desc>
5289 Additional property parameters, passed as a comma-separated list of
5290 "name=value" type entries.
5291 </desc>
5292 </param>
5293 </method>
5294
5295 <method name="getGuestPropertyValue">
5296 <desc>
5297 Reads a value from the machine's guest property store.
5298
5299 <result name="VBOX_E_INVALID_VM_STATE">
5300 Machine session is not open.
5301 </result>
5302
5303 </desc>
5304 <param name="property" type="wstring" dir="in">
5305 <desc>
5306 The name of the property to read.
5307 </desc>
5308 </param>
5309 <param name="value" type="wstring" dir="return">
5310 <desc>
5311 The value of the property. If the property does not exist then this
5312 will be empty.
5313 </desc>
5314 </param>
5315 </method>
5316
5317 <method name="getGuestPropertyTimestamp">
5318 <desc>
5319 Reads a property timestamp from the machine's guest property store.
5320
5321 <result name="VBOX_E_INVALID_VM_STATE">
5322 Machine session is not open.
5323 </result>
5324
5325 </desc>
5326 <param name="property" type="wstring" dir="in">
5327 <desc>
5328 The name of the property to read.
5329 </desc>
5330 </param>
5331 <param name="value" type="unsigned long long" dir="return">
5332 <desc>
5333 The timestamp. If the property does not exist then this will be
5334 empty.
5335 </desc>
5336 </param>
5337 </method>
5338
5339 <method name="setGuestProperty">
5340 <desc>
5341 Sets, changes or deletes an entry in the machine's guest property
5342 store.
5343
5344 <result name="E_ACCESSDENIED">
5345 Property cannot be changed.
5346 </result>
5347 <result name="E_INVALIDARG">
5348 Invalid @a flags.
5349 </result>
5350 <result name="VBOX_E_INVALID_VM_STATE">
5351 Virtual machine is not mutable or session not open.
5352 </result>
5353 <result name="VBOX_E_INVALID_OBJECT_STATE">
5354 Cannot set transient property when machine not running.
5355 </result>
5356
5357 </desc>
5358 <param name="property" type="wstring" dir="in">
5359 <desc>
5360 The name of the property to set, change or delete.
5361 </desc>
5362 </param>
5363 <param name="value" type="wstring" dir="in">
5364 <desc>
5365 The new value of the property to set, change or delete. If the
5366 property does not yet exist and value is non-empty, it will be
5367 created. If the value is empty, the key will be deleted if it
5368 exists.
5369 </desc>
5370 </param>
5371 <param name="flags" type="wstring" dir="in">
5372 <desc>
5373 Additional property parameters, passed as a comma-separated list of
5374 "name=value" type entries.
5375 </desc>
5376 </param>
5377 </method>
5378
5379 <method name="setGuestPropertyValue">
5380 <desc>
5381 Sets, changes or deletes a value in the machine's guest property
5382 store. The flags field will be left unchanged or created empty for a
5383 new property.
5384
5385 <result name="E_ACCESSDENIED">
5386 Property cannot be changed.
5387 </result>
5388 <result name="VBOX_E_INVALID_VM_STATE">
5389 Virtual machine is not mutable or session not open.
5390 </result>
5391 <result name="VBOX_E_INVALID_OBJECT_STATE">
5392 Cannot set transient property when machine not running.
5393 </result>
5394 </desc>
5395
5396 <param name="property" type="wstring" dir="in">
5397 <desc>
5398 The name of the property to set, change or delete.
5399 </desc>
5400 </param>
5401 <param name="value" type="wstring" dir="in">
5402 <desc>
5403 The new value of the property to set, change or delete. If the
5404 property does not yet exist and value is non-empty, it will be
5405 created. If value is empty, the property will be deleted if it
5406 exists.
5407 </desc>
5408 </param>
5409 </method>
5410
5411 <method name="enumerateGuestProperties">
5412 <desc>
5413 Return a list of the guest properties matching a set of patterns along
5414 with their values, time stamps and flags.
5415 </desc>
5416 <param name="patterns" type="wstring" dir="in">
5417 <desc>
5418 The patterns to match the properties against, separated by '|'
5419 characters. If this is empty or NULL, all properties will match.
5420 </desc>
5421 </param>
5422 <param name="name" type="wstring" dir="out" safearray="yes">
5423 <desc>
5424 The names of the properties returned.
5425 </desc>
5426 </param>
5427 <param name="value" type="wstring" dir="out" safearray="yes">
5428 <desc>
5429 The values of the properties returned. The array entries match the
5430 corresponding entries in the @a name array.
5431 </desc>
5432 </param>
5433 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5434 <desc>
5435 The time stamps of the properties returned. The array entries match
5436 the corresponding entries in the @a name array.
5437 </desc>
5438 </param>
5439 <param name="flags" type="wstring" dir="out" safearray="yes">
5440 <desc>
5441 The flags of the properties returned. The array entries match the
5442 corresponding entries in the @a name array.
5443 </desc>
5444 </param>
5445 </method>
5446</interface>
5447
5448 <!--
5449 // IConsole
5450 /////////////////////////////////////////////////////////////////////////
5451 -->
5452
5453 <interface
5454 name="IConsoleCallback" extends="$unknown"
5455 uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
5456 wsmap="suppress"
5457 >
5458
5459 <method name="onMousePointerShapeChange">
5460 <desc>
5461 Notification when the guest mouse pointer shape has
5462 changed. The new shape data is given.
5463 </desc>
5464 <param name="visible" type="boolean" dir="in">
5465 <desc>
5466 Flag whether the pointer is visible.
5467 </desc>
5468 </param>
5469 <param name="alpha" type="boolean" dir="in">
5470 <desc>
5471 Flag whether the pointer has an alpha channel.
5472 </desc>
5473 </param>
5474 <param name="xHot" type="unsigned long" dir="in">
5475 <desc>
5476 The pointer hot spot x coordinate.
5477 </desc>
5478 </param>
5479 <param name="yHot" type="unsigned long" dir="in">
5480 <desc>
5481 The pointer hot spot y coordinate.
5482 </desc>
5483 </param>
5484 <param name="width" type="unsigned long" dir="in">
5485 <desc>
5486 Width of the pointer shape in pixels.
5487 </desc>
5488 </param>
5489 <param name="height" type="unsigned long" dir="in">
5490 <desc>
5491 Height of the pointer shape in pixels.
5492 </desc>
5493 </param>
5494 <param name="shape" type="octet" mod="ptr" dir="in">
5495 <desc>
5496 Address of the shape buffer.
5497
5498 The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
5499 followed by a 32-bpp XOR (color) mask.
5500
5501 For pointers without alpha channel the XOR mask pixels are 32
5502 bit values: (lsb)BGR0(msb). For pointers with alpha channel
5503 the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
5504
5505 An AND mask is used for pointers with alpha channel, so if the
5506 callback does not support alpha, the pointer could be
5507 displayed as a normal color pointer.
5508
5509 The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
5510 size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
5511 height</tt>. The padding bits at the end of each scanline are
5512 undefined.
5513
5514 The XOR mask follows the AND mask on the next 4-byte aligned
5515 offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>.
5516 Bytes in the gap between the AND and the XOR mask are undefined.
5517 The XOR mask scanlines have no gap between them and the size of
5518 the XOR mask is: <tt>cXor = width * 4 * height</tt>.
5519
5520 <note>
5521 If @a shape is 0, only the pointer visibility is changed.
5522 </note>
5523 </desc>
5524 </param>
5525 </method>
5526
5527 <method name="onMouseCapabilityChange">
5528 <desc>
5529 Notification when the mouse capabilities reported by the
5530 guest have changed. The new capabilities are passed.
5531 </desc>
5532 <param name="supportsAbsolute" type="boolean" dir="in"/>
5533 <param name="needsHostCursor" type="boolean" dir="in"/>
5534 </method>
5535
5536 <method name="onKeyboardLedsChange">
5537 <desc>
5538 Notification when the guest OS executes the KBD_CMD_SET_LEDS command
5539 to alter the state of the keyboard LEDs.
5540 </desc>
5541 <param name="numLock" type="boolean" dir="in"/>
5542 <param name="capsLock" type="boolean" dir="in"/>
5543 <param name="scrollLock" type="boolean" dir="in"/>
5544 </method>
5545
5546 <method name="onStateChange">
5547 <desc>
5548 Notification when the execution state of the machine has changed.
5549 The new state will be given.
5550 </desc>
5551 <param name="state" type="MachineState" dir="in"/>
5552 </method>
5553
5554 <method name="onAdditionsStateChange">
5555 <desc>
5556 Notification when a Guest Additions property changes.
5557 Interested callees should query IGuest attributes to
5558 find out what has changed.
5559 </desc>
5560 </method>
5561
5562 <method name="onDVDDriveChange">
5563 <desc>
5564 Notification when a property of the
5565 virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
5566 Interested callees should use IDVDDrive methods to find out what has
5567 changed.
5568 </desc>
5569 </method>
5570
5571 <method name="onFloppyDriveChange">
5572 <desc>
5573 Notification when a property of the
5574 virtual <link to="IMachine::floppyDrive">floppy drive</link> changes.
5575 Interested callees should use IFloppyDrive methods to find out what
5576 has changed.
5577 </desc>
5578 </method>
5579
5580 <method name="onNetworkAdapterChange">
5581 <desc>
5582 Notification when a property of one of the
5583 virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
5584 changes. Interested callees should use INetworkAdapter methods and
5585 attributes to find out what has changed.
5586 </desc>
5587 <param name="networkAdapter" type="INetworkAdapter" dir="in">
5588 <desc>Network adapter that is subject to change.</desc>
5589 </param>
5590 </method>
5591
5592 <method name="onSerialPortChange">
5593 <desc>
5594 Notification when a property of one of the
5595 virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
5596 Interested callees should use ISerialPort methods and attributes
5597 to find out what has changed.
5598 </desc>
5599 <param name="serialPort" type="ISerialPort" dir="in">
5600 <desc>Serial port that is subject to change.</desc>
5601 </param>
5602 </method>
5603
5604 <method name="onParallelPortChange">
5605 <desc>
5606 Notification when a property of one of the
5607 virtual <link to="IMachine::getParallelPort">parallel ports</link>
5608 changes. Interested callees should use ISerialPort methods and
5609 attributes to find out what has changed.
5610 </desc>
5611 <param name="parallelPort" type="IParallelPort" dir="in">
5612 <desc>Parallel port that is subject to change.</desc>
5613 </param>
5614 </method>
5615
5616 <method name="onStorageControllerChange">
5617 <desc>
5618 Notification when a property of one of the
5619 virtual <link to="IMachine::storageControllers">storage controllers</link>
5620 changes. Interested callees should query the corresponding collections
5621 to find out what has changed.
5622 </desc>
5623 </method>
5624
5625 <method name="onVRDPServerChange">
5626 <desc>
5627 Notification when a property of the
5628 <link to="IMachine::VRDPServer">VRDP server</link> changes.
5629 Interested callees should use IVRDPServer methods and attributes to
5630 find out what has changed.
5631 </desc>
5632 </method>
5633
5634 <method name="onUSBControllerChange">
5635 <desc>
5636 Notification when a property of the virtual
5637 <link to="IMachine::USBController">USB controller</link> changes.
5638 Interested callees should use IUSBController methods and attributes to
5639 find out what has changed.
5640 </desc>
5641 </method>
5642
5643 <method name="onUSBDeviceStateChange">
5644 <desc>
5645 Notification when a USB device is attached to or detached from
5646 the virtual USB controller.
5647
5648 This notification is sent as a result of the indirect
5649 request to attach the device because it matches one of the
5650 machine USB filters, or as a result of the direct request
5651 issued by <link to="IConsole::attachUSBDevice"/> or
5652 <link to="IConsole::detachUSBDevice"/>.
5653
5654 This notification is sent in case of both a succeeded and a
5655 failed request completion. When the request succeeds, the
5656 @a error parameter is @c null, and the given device has been
5657 already added to (when @a attached is @c true) or removed from
5658 (when @a attached is @c false) the collection represented by
5659 <link to="IConsole::USBDevices"/>. On failure, the collection
5660 doesn't change and the @a error parameter represents the error
5661 message describing the failure.
5662
5663 </desc>
5664 <param name="device" type="IUSBDevice" dir="in">
5665 <desc>Device that is subject to state change.</desc>
5666 </param>
5667 <param name="attached" type="boolean" dir="in">
5668 <desc>
5669 <tt>true</tt> if the device was attached
5670 and <tt>false</tt> otherwise.
5671 </desc>
5672 </param>
5673 <param name="error" type="IVirtualBoxErrorInfo" dir="in">
5674 <desc>
5675 <tt>null</tt> on success or an error message object on
5676 failure.
5677 </desc>
5678 </param>
5679 </method>
5680
5681 <method name="onSharedFolderChange">
5682 <desc>
5683 Notification when a shared folder is added or removed.
5684 The @a scope argument defines one of three scopes:
5685 <link to="IVirtualBox::sharedFolders">global shared folders</link>
5686 (<link to="Scope_Global">Global</link>),
5687 <link to="IMachine::sharedFolders">permanent shared folders</link> of
5688 the machine (<link to="Scope_Machine">Machine</link>) or <link
5689 to="IConsole::sharedFolders">transient shared folders</link> of the
5690 machine (<link to="Scope_Session">Session</link>). Interested callees
5691 should use query the corresponding collections to find out what has
5692 changed.
5693 </desc>
5694 <param name="scope" type="Scope" dir="in">
5695 <desc>Scope of the notification.</desc>
5696 </param>
5697 </method>
5698
5699 <method name="onRuntimeError">
5700 <desc>
5701 Notification when an error happens during the virtual
5702 machine execution.
5703
5704 There are three kinds of runtime errors:
5705 <ul>
5706 <li><i>fatal</i></li>
5707 <li><i>non-fatal with retry</i></li>
5708 <li><i>non-fatal warnings</i></li>
5709 </ul>
5710
5711 <b>Fatal</b> errors are indicated by the @a fatal parameter set
5712 to <tt>true</tt>. In case of fatal errors, the virtual machine
5713 execution is always paused before calling this notification, and
5714 the notification handler is supposed either to immediately save
5715 the virtual machine state using <link to="IConsole::saveState"/>
5716 or power it off using <link to="IConsole::powerDown"/>.
5717 Resuming the execution can lead to unpredictable results.
5718
5719 <b>Non-fatal</b> errors and warnings are indicated by the
5720 @a fatal parameter set to <tt>false</tt>. If the virtual machine
5721 is in the Paused state by the time the error notification is
5722 received, it means that the user can <i>try to resume</i> the machine
5723 execution after attempting to solve the problem that caused the
5724 error. In this case, the notification handler is supposed
5725 to show an appropriate message to the user (depending on the
5726 value of the @a id parameter) that offers several actions such
5727 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
5728 wants to retry, the notification handler should continue
5729 the machine execution using the <link to="IConsole::resume"/>
5730 call. If the machine execution is not Paused during this
5731 notification, then it means this notification is a <i>warning</i>
5732 (for example, about a fatal condition that can happen very soon);
5733 no immediate action is required from the user, the machine
5734 continues its normal execution.
5735
5736 Note that in either case the notification handler
5737 <b>must not</b> perform any action directly on a thread
5738 where this notification is called. Everything it is allowed to
5739 do is to post a message to another thread that will then talk
5740 to the user and take the corresponding action.
5741
5742 Currently, the following error identifiers are known:
5743 <ul>
5744 <li><tt>"HostMemoryLow"</tt></li>
5745 <li><tt>"HostAudioNotResponding"</tt></li>
5746 <li><tt>"VDIStorageFull"</tt></li>
5747 </ul>
5748
5749 <note>
5750 This notification is not designed to be implemented by
5751 more than one callback at a time. If you have multiple
5752 IConsoleCallback instances registered on the given
5753 IConsole object, make sure you simply do nothing but
5754 return @c S_OK from all but one of them that does actual
5755 user notification and performs necessary actions.
5756 </note>
5757
5758 </desc>
5759 <param name="fatal" type="boolean" dir="in">
5760 <desc>Whether the error is fatal or not</desc>
5761 </param>
5762 <param name="id" type="wstring" dir="in">
5763 <desc>Error identifier</desc>
5764 </param>
5765 <param name="message" type="wstring" dir="in">
5766 <desc>Optional error message</desc>
5767 </param>
5768 </method>
5769
5770 <method name="onCanShowWindow">
5771 <desc>
5772 Notification when a call to
5773 <link to="IMachine::canShowConsoleWindow"/> is made by a
5774 front-end to check if a subsequent call to
5775 <link to="IMachine::showConsoleWindow"/> can succeed.
5776
5777 The callee should give an answer appropriate to the current
5778 machine state in the @a canShow argument. This answer must
5779 remain valid at least until the next
5780 <link to="IConsole::state">machine state</link> change.
5781
5782 <note>
5783 This notification is not designed to be implemented by
5784 more than one callback at a time. If you have multiple
5785 IConsoleCallback instances registered on the given
5786 IConsole object, make sure you simply do nothing but
5787 return @c true and @c S_OK from all but one of them that
5788 actually manages console window activation.
5789 </note>
5790 </desc>
5791 <param name="canShow" type="boolean" dir="return">
5792 <desc>
5793 @c true if the console window can be shown and @c
5794 false otherwise.
5795 </desc>
5796 </param>
5797 </method>
5798
5799 <method name="onShowWindow">
5800 <desc>
5801 Notification when a call to
5802 <link to="IMachine::showConsoleWindow"/>
5803 requests the console window to be activated and brought to
5804 foreground on the desktop of the host PC.
5805
5806 This notification should cause the VM console process to
5807 perform the requested action as described above. If it is
5808 impossible to do it at a time of this notification, this
5809 method should return a failure.
5810
5811 Note that many modern window managers on many platforms
5812 implement some sort of focus stealing prevention logic, so
5813 that it may be impossible to activate a window without the
5814 help of the currently active application (which is supposedly
5815 an initiator of this notification). In this case, this method
5816 must return a non-zero identifier that represents the
5817 top-level window of the VM console process. The caller, if it
5818 represents a currently active process, is responsible to use
5819 this identifier (in a platform-dependent manner) to perform
5820 actual window activation.
5821
5822 This method must set @a winId to zero if it has performed all
5823 actions necessary to complete the request and the console
5824 window is now active and in foreground, to indicate that no
5825 further action is required on the caller's side.
5826
5827 <note>
5828 This notification is not designed to be implemented by
5829 more than one callback at a time. If you have multiple
5830 IConsoleCallback instances registered on the given
5831 IConsole object, make sure you simply do nothing but
5832 return @c S_OK from all but one of them that actually
5833 manages console window activation.
5834 </note>
5835 </desc>
5836 <param name="winId" type="unsigned long long" dir="return">
5837 <desc>
5838 Platform-dependent identifier of the top-level VM console
5839 window, or zero if this method has performed all actions
5840 necessary to implement the <i>show window</i> semantics for
5841 the given platform and/or this VirtualBox front-end.
5842 </desc>
5843 </param>
5844 </method>
5845
5846 </interface>
5847
5848 <interface
5849 name="IRemoteDisplayInfo" extends="$unknown"
5850 uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
5851 wsmap="struct"
5852 >
5853 <desc>
5854 Contains information about the remote display (VRDP) capabilities and status.
5855 This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
5856 </desc>
5857
5858 <attribute name="active" type="boolean" readonly="yes">
5859 <desc>
5860 Whether the remote display connection is active.
5861 </desc>
5862 </attribute>
5863
5864 <attribute name="numberOfClients" type="unsigned long" readonly="yes">
5865 <desc>
5866 How many times a client connected.
5867 </desc>
5868 </attribute>
5869
5870 <attribute name="beginTime" type="long long" readonly="yes">
5871 <desc>
5872 When the last connection was established, in milliseconds since 1970-01-01 UTC.
5873 </desc>
5874 </attribute>
5875
5876 <attribute name="endTime" type="long long" readonly="yes">
5877 <desc>
5878 When the last connection was terminated or the current time, if
5879 connection is still active, in milliseconds since 1970-01-01 UTC.
5880 </desc>
5881 </attribute>
5882
5883 <attribute name="bytesSent" type="unsigned long long" readonly="yes">
5884 <desc>
5885 How many bytes were sent in last or current, if still active, connection.
5886 </desc>
5887 </attribute>
5888
5889 <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
5890 <desc>
5891 How many bytes were sent in all connections.
5892 </desc>
5893 </attribute>
5894
5895 <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
5896 <desc>
5897 How many bytes were received in last or current, if still active, connection.
5898 </desc>
5899 </attribute>
5900
5901 <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
5902 <desc>
5903 How many bytes were received in all connections.
5904 </desc>
5905 </attribute>
5906
5907 <attribute name="user" type="wstring" readonly="yes">
5908 <desc>
5909 Login user name supplied by the client.
5910 </desc>
5911 </attribute>
5912
5913 <attribute name="domain" type="wstring" readonly="yes">
5914 <desc>
5915 Login domain name supplied by the client.
5916 </desc>
5917 </attribute>
5918
5919 <attribute name="clientName" type="wstring" readonly="yes">
5920 <desc>
5921 The client name supplied by the client.
5922 </desc>
5923 </attribute>
5924
5925 <attribute name="clientIP" type="wstring" readonly="yes">
5926 <desc>
5927 The IP address of the client.
5928 </desc>
5929 </attribute>
5930
5931 <attribute name="clientVersion" type="unsigned long" readonly="yes">
5932 <desc>
5933 The client software version number.
5934 </desc>
5935 </attribute>
5936
5937 <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
5938 <desc>
5939 Public key exchange method used when connection was established.
5940 Values: 0 - RDP4 public key exchange scheme.
5941 1 - X509 certificates were sent to client.
5942 </desc>
5943 </attribute>
5944
5945 </interface>
5946
5947 <interface
5948 name="IConsole" extends="$unknown"
5949 uuid="9511bc54-15ee-4ddf-808e-472aba03809c"
5950 wsmap="managed"
5951 >
5952 <desc>
5953 The IConsole interface represents an interface to control virtual
5954 machine execution.
5955
5956 The console object that implements the IConsole interface is obtained
5957 from a session object after the session for the given machine has been
5958 opened using one of <link to="IVirtualBox::openSession"/>,
5959 <link to="IVirtualBox::openRemoteSession"/> or
5960 <link to="IVirtualBox::openExistingSession"/> methods.
5961
5962 Methods of the IConsole interface allow the caller to query the current
5963 virtual machine execution state, pause the machine or power it down, save
5964 the machine state or take a snapshot, attach and detach removable media
5965 and so on.
5966
5967 <see>ISession</see>
5968 </desc>
5969
5970 <attribute name="machine" type="IMachine" readonly="yes">
5971 <desc>
5972 Machine object this console is sessioned with.
5973 <note>
5974 This is a convenience property, it has the same value as
5975 <link to="ISession::machine"/> of the corresponding session
5976 object.
5977 </note>
5978 </desc>
5979 </attribute>
5980
5981 <attribute name="state" type="MachineState" readonly="yes">
5982 <desc>
5983 Current execution state of the machine.
5984 <note>
5985 This property always returns the same value as the corresponding
5986 property of the IMachine object this console is sessioned with.
5987 For the process that owns (executes) the VM, this is the
5988 preferable way of querying the VM state, because no IPC
5989 calls are made.
5990 </note>
5991 </desc>
5992 </attribute>
5993
5994 <attribute name="guest" type="IGuest" readonly="yes">
5995 <desc>Guest object.</desc>
5996 </attribute>
5997
5998 <attribute name="keyboard" type="IKeyboard" readonly="yes">
5999 <desc>
6000 Virtual keyboard object.
6001 <note>
6002 If the machine is not running, any attempt to use
6003 the returned object will result in an error.
6004 </note>
6005 </desc>
6006 </attribute>
6007
6008 <attribute name="mouse" type="IMouse" readonly="yes">
6009 <desc>
6010 Virtual mouse object.
6011 <note>
6012 If the machine is not running, any attempt to use
6013 the returned object will result in an error.
6014 </note>
6015 </desc>
6016 </attribute>
6017
6018 <attribute name="display" type="IDisplay" readonly="yes">
6019 <desc>Virtual display object.
6020 <note>
6021 If the machine is not running, any attempt to use
6022 the returned object will result in an error.
6023 </note>
6024 </desc>
6025 </attribute>
6026
6027 <attribute name="debugger" type="IMachineDebugger" readonly="yes">
6028 <desc>Debugging interface.</desc>
6029 </attribute>
6030
6031 <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
6032 <desc>
6033 Collection of USB devices currently attached to the virtual
6034 USB controller.
6035 <note>
6036 The collection is empty if the machine is not running.
6037 </note>
6038 </desc>
6039 </attribute>
6040
6041 <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6042 <desc>
6043 List of USB devices currently attached to the remote VRDP client.
6044 Once a new device is physically attached to the remote host computer,
6045 it appears in this list and remains there until detached.
6046 </desc>
6047 </attribute>
6048
6049 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
6050 <desc>
6051 Collection of shared folders for the current session. These folders
6052 are called transient shared folders because they are available to the
6053 guest OS running inside the associated virtual machine only for the
6054 duration of the session (as opposed to
6055 <link to="IMachine::sharedFolders"/> which represent permanent shared
6056 folders). When the session is closed (e.g. the machine is powered down),
6057 these folders are automatically discarded.
6058
6059 New shared folders are added to the collection using
6060 <link to="#createSharedFolder"/>. Existing shared folders can be
6061 removed using <link to="#removeSharedFolder"/>.
6062 </desc>
6063 </attribute>
6064
6065 <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
6066 <desc>
6067 Interface that provides information on Remote Display (VRDP) connection.
6068 </desc>
6069 </attribute>
6070
6071 <method name="powerUp">
6072 <desc>
6073 Starts the virtual machine execution using the current machine
6074 state (that is, its current execution state, current settings and
6075 current hard disks).
6076
6077 If the machine is powered off or aborted, the execution will
6078 start from the beginning (as if the real hardware were just
6079 powered on).
6080
6081 If the machine is in the <link to="MachineState_Saved"/> state,
6082 it will continue its execution the point where the state has
6083 been saved.
6084
6085 <note>
6086 Unless you are trying to write a new VirtualBox front-end that
6087 performs direct machine execution (like the VirtualBox or VBoxSDL
6088 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
6089 session opened by <link to="IVirtualBox::openSession"/> and use this
6090 session only to change virtual machine settings. If you simply want to
6091 start virtual machine execution using one of the existing front-ends
6092 (for example the VirtualBox GUI or headless server), simply use
6093 <link to="IVirtualBox::openRemoteSession"/>; these front-ends will
6094 power up the machine automatically for you.
6095 </note>
6096
6097 <see>#saveState</see>
6098 <result name="VBOX_E_INVALID_VM_STATE">
6099 Virtual machine already running.
6100 </result>
6101 <result name="VBOX_E_HOST_ERROR">
6102 Host interface does not exist or name not set.
6103 </result>
6104 <result name="VBOX_E_FILE_ERROR">
6105 Invalid saved state file.
6106 </result>
6107 </desc>
6108 <param name="progress" type="IProgress" dir="return">
6109 <desc>Progress object to track the operation completion.</desc>
6110 </param>
6111 </method>
6112
6113 <method name="powerUpPaused">
6114 <desc>
6115 Identical to powerUp except that the VM will enter the
6116 <link to="MachineState_Paused"/> state, instead of
6117 <link to="MachineState_Running"/>.
6118
6119 <see>#powerUp</see>
6120 <result name="VBOX_E_INVALID_VM_STATE">
6121 Virtual machine already running.
6122 </result>
6123 <result name="VBOX_E_HOST_ERROR">
6124 Host interface does not exist or name not set.
6125 </result>
6126 <result name="VBOX_E_FILE_ERROR">
6127 Invalid saved state file.
6128 </result>
6129 </desc>
6130 <param name="progress" type="IProgress" dir="return">
6131 <desc>Progress object to track the operation completion.</desc>
6132 </param>
6133 </method>
6134
6135 <method name="powerDown">
6136 <desc>
6137 Stops the virtual machine execution.
6138 After this operation completes, the machine will go to the
6139 PoweredOff state.
6140
6141 @deprecated This method will be removed in VirtualBox 2.1 where the
6142 powerDownAsync() method will take its name. Do not use this method in
6143 the code.
6144 <result name="VBOX_E_INVALID_VM_STATE">
6145 Virtual machine must be Running, Paused or Stuck to be powered down.
6146 </result>
6147 <result name="VBOX_E_VM_ERROR">
6148 Unable to power off or destroy virtual machine.
6149 </result>
6150 </desc>
6151 </method>
6152
6153 <method name="powerDownAsync">
6154 <desc>
6155 Initiates the power down procedure to stop the virtual machine
6156 execution.
6157
6158 The completion of the power down procedure is tracked using the returned
6159 IProgress object. After the operation is complete, the machine will go
6160 to the PoweredOff state.
6161
6162 @warning This method will be renamed to "powerDown" in VirtualBox 2.1
6163 where the original powerDown() method will be removed. You will need to
6164 rename "powerDownAsync" to "powerDown" in your sources to make them
6165 build with version 2.1.
6166 <result name="VBOX_E_INVALID_VM_STATE">
6167 Virtual machine must be Running, Paused or Stuck to be powered down.
6168 </result>
6169 </desc>
6170 <param name="progress" type="IProgress" dir="return">
6171 <desc>Progress object to track the operation completion.</desc>
6172 </param>
6173 </method>
6174
6175 <method name="reset">
6176 <desc>Resets the virtual machine.
6177 <result name="VBOX_E_INVALID_VM_STATE">
6178 Virtual machine not in Running state.
6179 </result>
6180 <result name="VBOX_E_VM_ERROR">
6181 Virtual machine error in reset operation.
6182 </result>
6183 </desc>
6184 </method>
6185
6186 <method name="pause">
6187 <desc>Pauses the virtual machine execution.
6188 <result name="VBOX_E_INVALID_VM_STATE">
6189 Virtual machine not in Running state.
6190 </result>
6191 <result name="VBOX_E_VM_ERROR">
6192 Virtual machine error in suspend operation.
6193 </result>
6194 </desc>
6195 </method>
6196
6197 <method name="resume">
6198 <desc>Resumes the virtual machine execution.
6199 <result name="VBOX_E_INVALID_VM_STATE">
6200 Virtual machine not in Paused state.
6201 </result>
6202 <result name="VBOX_E_VM_ERROR">
6203 Virtual machine error in resume operation.
6204 </result>
6205 </desc>
6206 </method>
6207
6208 <method name="powerButton">
6209 <desc>Sends the ACPI power button event to the guest.
6210 <result name="VBOX_E_INVALID_VM_STATE">
6211 Virtual machine not in Running state.
6212 </result>
6213 <result name="VBOX_E_PDM_ERROR">
6214 Controlled power off failed.
6215 </result>
6216 </desc>
6217 </method>
6218
6219 <method name="sleepButton">
6220 <desc>Sends the ACPI sleep button event to the guest.
6221 <result name="VBOX_E_INVALID_VM_STATE">
6222 Virtual machine not in Running state.
6223 </result>
6224 <result name="VBOX_E_PDM_ERROR">
6225 Sending sleep button event failed.
6226 </result>
6227 </desc>
6228 </method>
6229
6230 <method name="getPowerButtonHandled">
6231 <desc>Checks if the last power button event was handled by guest.
6232 <result name="VBOX_E_PDM_ERROR">
6233 Checking if the event was handled by the guest OS failed.
6234 </result>
6235 </desc>
6236 <param name="handled" type="boolean" dir="return"/>
6237 </method>
6238
6239 <method name="getGuestEnteredACPIMode">
6240 <desc>Checks if the guest entered the ACPI mode G0 (working) or
6241 G1 (sleeping). If this method returns false, the guest will
6242 most likely not respond to external ACPI events.
6243 <result name="VBOX_E_INVALID_VM_STATE">
6244 Virtual machine not in Running state.
6245 </result>
6246 </desc>
6247 <param name="entered" type="boolean" dir="return"/>
6248 </method>
6249
6250 <method name="saveState">
6251 <desc>
6252 Saves the current execution state of a running virtual machine
6253 and stops its execution.
6254
6255 After this operation completes, the machine will go to the
6256 Saved state. Next time it is powered up, this state will
6257 be restored and the machine will continue its execution from
6258 the place where it was saved.
6259
6260 This operation differs from taking a snapshot to the effect
6261 that it doesn't create new differencing hard disks. Also, once
6262 the machine is powered up from the state saved using this method,
6263 the saved state is deleted, so it will be impossible to return
6264 to this state later.
6265
6266 <note>
6267 On success, this method implicitly calls
6268 <link to="IMachine::saveSettings"/> to save all current machine
6269 settings (including runtime changes to the DVD drive, etc.).
6270 Together with the impossibility to change any VM settings when it is
6271 in the Saved state, this guarantees adequate hardware
6272 configuration of the machine when it is restored from the saved
6273 state file.
6274 </note>
6275
6276 <note>
6277 The machine must be in the Running or Paused state, otherwise
6278 the operation will fail.
6279 </note>
6280 <result name="VBOX_E_INVALID_VM_STATE">
6281 Virtual machine state neither Running nor Paused.
6282 </result>
6283 <result name="VBOX_E_FILE_ERROR">
6284 Failed to create directory for saved state file.
6285 </result>
6286
6287 <see><link to="#takeSnapshot"/></see>
6288 </desc>
6289 <param name="progress" type="IProgress" dir="return">
6290 <desc>Progress object to track the operation completion.</desc>
6291 </param>
6292 </method>
6293
6294 <method name="adoptSavedState">
6295 <desc>
6296 Associates the given saved state file to the virtual machine.
6297
6298 On success, the machine will go to the Saved state. Next time it is
6299 powered up, it will be restored from the adopted saved state and
6300 continue execution from the place where the saved state file was
6301 created.
6302
6303 The specified saved state file path may be absolute or relative to the
6304 folder the VM normally saves the state to (usually,
6305 <link to="IMachine::snapshotFolder"/>).
6306
6307 <note>
6308 It's a caller's responsibility to make sure the given saved state
6309 file is compatible with the settings of this virtual machine that
6310 represent its virtual hardware (memory size, hard disk configuration
6311 etc.). If there is a mismatch, the behavior of the virtual machine
6312 is undefined.
6313 </note>
6314 <result name="VBOX_E_INVALID_VM_STATE">
6315 Virtual machine state neither PoweredOff nor Aborted.
6316 </result>
6317 </desc>
6318 <param name="savedStateFile" type="wstring" dir="in">
6319 <desc>Path to the saved state file to adopt.</desc>
6320 </param>
6321 </method>
6322
6323 <method name="discardSavedState">
6324 <desc>
6325 Discards (deletes) the saved state of the virtual machine
6326 previously created by <link to="#saveState"/>. Next time the
6327 machine is powered up, a clean boot will occur.
6328 <note>
6329 This operation is equivalent to resetting or powering off
6330 the machine without doing a proper shutdown in the guest OS.
6331 </note>
6332 <result name="VBOX_E_INVALID_VM_STATE">
6333 Virtual machine not in state Saved.
6334 </result>
6335 </desc>
6336 </method>
6337
6338 <method name="getDeviceActivity">
6339 <desc>
6340 Gets the current activity type of a given device or device group.
6341 <result name="E_INVALIDARG">
6342 Invalid device type.
6343 </result>
6344 </desc>
6345 <param name="type" type="DeviceType" dir="in"/>
6346 <param name="activity" type="DeviceActivity" dir="return"/>
6347 </method>
6348
6349 <method name="attachUSBDevice">
6350 <desc>
6351 Attaches a host USB device with the given UUID to the
6352 USB controller of the virtual machine.
6353
6354 The device needs to be in one of the following states:
6355 <link to="USBDeviceState_Busy"/>,
6356 <link to="USBDeviceState_Available"/> or
6357 <link to="USBDeviceState_Held"/>,
6358 otherwise an error is immediately returned.
6359
6360 When the device state is
6361 <link to="USBDeviceState_Busy">Busy</link>, an error may also
6362 be returned if the host computer refuses to release it for some reason.
6363
6364 <see>IUSBController::deviceFilters, USBDeviceState</see>
6365 <result name="VBOX_E_INVALID_VM_STATE">
6366 Virtual machine state neither Running nor Paused.
6367 </result>
6368 <result name="VBOX_E_PDM_ERROR">
6369 Virtual machine does not have a USB controller.
6370 </result>
6371 </desc>
6372 <param name="id" type="uuid" dir="in">
6373 <desc>UUID of the host USB device to attach.</desc>
6374 </param>
6375 </method>
6376
6377 <method name="detachUSBDevice">
6378 <desc>
6379 Detaches an USB device with the given UUID from the USB controller
6380 of the virtual machine.
6381
6382 After this method succeeds, the VirtualBox server re-initiates
6383 all USB filters as if the device were just physically attached
6384 to the host, but filters of this machine are ignored to avoid
6385 a possible automatic re-attachment.
6386
6387 <see>IUSBController::deviceFilters, USBDeviceState</see>
6388
6389 <result name="VBOX_E_PDM_ERROR">
6390 Virtual machine does not have a USB controller.
6391 </result>
6392 <result name="E_INVALIDARG">
6393 USB device not attached to this virtual machine.
6394 </result>
6395 </desc>
6396 <param name="id" type="uuid" dir="in">
6397 <desc>UUID of the USB device to detach.</desc>
6398 </param>
6399 <param name="device" type="IUSBDevice" dir="return">
6400 <desc>Detached USB device.</desc>
6401 </param>
6402 </method>
6403
6404 <method name="findUSBDeviceByAddress">
6405 <desc>
6406 Searches for a USB device with the given host address.
6407
6408 <result name="VBOX_E_OBJECT_NOT_FOUND">
6409 Given @c name does not correspond to any USB device.
6410 </result>
6411
6412 <see>IUSBDevice::address</see>
6413 </desc>
6414 <param name="name" type="wstring" dir="in">
6415 <desc>
6416 Address of the USB device (as assigned by the host) to
6417 search for.
6418 </desc>
6419 </param>
6420 <param name="device" type="IUSBDevice" dir="return">
6421 <desc>Found USB device object.</desc>
6422 </param>
6423 </method>
6424
6425 <method name="findUSBDeviceById">
6426 <desc>
6427 Searches for a USB device with the given UUID.
6428
6429 <result name="VBOX_E_OBJECT_NOT_FOUND">
6430 Given @c id does not correspond to any USB device.
6431 </result>
6432
6433 <see>IUSBDevice::id</see>
6434 </desc>
6435 <param name="id" type="uuid" dir="in">
6436 <desc>UUID of the USB device to search for.</desc>
6437 </param>
6438 <param name="device" type="IUSBDevice" dir="return">
6439 <desc>Found USB device object.</desc>
6440 </param>
6441 </method>
6442
6443 <method name="createSharedFolder">
6444 <desc>
6445 Creates a transient new shared folder by associating the given logical
6446 name with the given host path, adds it to the collection of shared
6447 folders and starts sharing it. Refer to the description of
6448 <link to="ISharedFolder"/> to read more about logical names.
6449
6450 <result name="VBOX_E_INVALID_VM_STATE">
6451 Virtual machine in Saved state or currently changing state.
6452 </result>
6453 <result name="VBOX_E_FILE_ERROR">
6454 Shared folder already exists or not accessible.
6455 </result>
6456 </desc>
6457 <param name="name" type="wstring" dir="in">
6458 <desc>Unique logical name of the shared folder.</desc>
6459 </param>
6460 <param name="hostPath" type="wstring" dir="in">
6461 <desc>Full path to the shared folder in the host file system.</desc>
6462 </param>
6463 <param name="writable" type="boolean" dir="in">
6464 <desc>Whether the share is writable or readonly</desc>
6465 </param>
6466 </method>
6467
6468 <method name="removeSharedFolder">
6469 <desc>
6470 Removes a transient shared folder with the given name previously
6471 created by <link to="#createSharedFolder"/> from the collection of
6472 shared folders and stops sharing it.
6473 <result name="VBOX_E_INVALID_VM_STATE">
6474 Virtual machine in Saved state or currently changing state.
6475 </result>
6476 <result name="VBOX_E_FILE_ERROR">
6477 Shared folder does not exists.
6478 </result>
6479 </desc>
6480 <param name="name" type="wstring" dir="in">
6481 <desc>Logical name of the shared folder to remove.</desc>
6482 </param>
6483 </method>
6484
6485 <method name="takeSnapshot">
6486 <desc>
6487 Saves the current execution state and all settings of the
6488 machine and creates differencing images for all
6489 normal (non-independent) hard disks.
6490
6491 This method can be called for a PoweredOff, Saved, Running or
6492 Paused virtual machine. When the machine is PoweredOff, an
6493 offline <link to="ISnapshot">snapshot</link> is created,
6494 in all other cases -- an online snapshot.
6495
6496 The taken snapshot is always based on the
6497 <link to="IMachine::currentSnapshot">current
6498 snapshot</link> of the associated virtual machine and becomes
6499 a new current snapshot.
6500
6501 <note>
6502 This method implicitly calls <link to="IMachine::saveSettings"/> to
6503 save all current machine settings before taking an offline snapshot.
6504 </note>
6505
6506 <see>ISnapshot, <link to="#saveState"/></see>
6507 <result name="VBOX_E_INVALID_VM_STATE">
6508 Virtual machine currently changing state.
6509 </result>
6510 </desc>
6511 <param name="name" type="wstring" dir="in">
6512 <desc>Short name for the snapshot.</desc>
6513 </param>
6514 <param name="description" type="wstring" dir="in">
6515 <desc>Optional description of the snapshot.</desc>
6516 </param>
6517 <param name="progress" type="IProgress" dir="return">
6518 <desc>Progress object to track the operation completion.</desc>
6519 </param>
6520 </method>
6521
6522 <method name="discardSnapshot">
6523 <desc>
6524
6525 Starts discarding the specified snapshot. The execution state
6526 and settings of the associated machine stored in the snapshot
6527 will be deleted. The contents of all differencing hard disks of
6528 this snapshot will be merged with the contents of their
6529 dependent child hard disks to keep the, disks valid (in other
6530 words, all changes represented by hard disks being discarded
6531 will be propagated to their child hard disks). After that, this
6532 snapshot's differencing hard disks will be deleted. The parent
6533 of this snapshot will become a new parent for all its child
6534 snapshots.
6535
6536 If the discarded snapshot is the current one, its parent
6537 snapshot will become a new current snapshot. The current machine
6538 state is not directly affected in this case, except that
6539 currently attached differencing hard disks based on hard disks
6540 of the discarded snapshot will be also merged as described
6541 above.
6542
6543 If the discarded snapshot is the first one (the root snapshot)
6544 and it has exactly one child snapshot, this child snapshot will
6545 become the first snapshot after discarding. If there are no
6546 children at all (i.e. the first snapshot is the only snapshot of
6547 the machine), both the current and the first snapshot of the
6548 machine will be set to null. In all other cases, the first
6549 snapshot cannot be discarded.
6550
6551 You cannot discard the snapshot if it
6552 stores <link to="HardDiskType_Normal">normal</link> (non-differencing)
6553 hard disks that have differencing hard disks based on them. Snapshots of
6554 such kind can be discarded only when every normal hard disk has either
6555 no children at all or exactly one child. In the former case, the normal
6556 hard disk simply becomes unused (i.e. not attached to any VM). In the
6557 latter case, it receives all the changes stored in the child hard disk,
6558 and then it replaces the child hard disk in the configuration of the
6559 corresponding snapshot or machine.
6560
6561 Also, you cannot discard the snapshot if it stores hard disks
6562 (of any type) having differencing child hard disks that belong
6563 to other machines. Such snapshots can be only discarded after
6564 you discard all snapshots of other machines containing "foreign"
6565 child disks, or detach these "foreign" child disks from machines
6566 they are attached to.
6567
6568 One particular example of the snapshot storing normal hard disks
6569 is the first snapshot of a virtual machine that had normal hard
6570 disks attached when taking the snapshot. Be careful when
6571 discarding such snapshots because this implicitly commits
6572 changes (made since the snapshot being discarded has been taken)
6573 to normal hard disks (as described above), which may be not what
6574 you want.
6575
6576 The virtual machine is put to
6577 the <link to="MachineState_Discarding">Discarding</link> state until
6578 the discard operation is completed.
6579
6580 <note>
6581 The machine must not be running, otherwise the operation
6582 will fail.
6583 </note>
6584
6585 <note>
6586 Child hard disks of all normal hard disks of the discarded snapshot
6587 must be accessible (see <link to="IMedium::state"/>) for this
6588 operation to succeed. In particular, this means that all virtual
6589 machines, whose hard disks are directly or indirectly based on the
6590 hard disks of discarded snapshot, must be powered off.
6591 </note>
6592 <note>
6593 Merging hard disk contents can be very time and disk space
6594 consuming, if these disks are big in size and have many
6595 children. However, if the snapshot being discarded is the last
6596 (head) snapshot on the branch, the operation will be rather
6597 quick.
6598 </note>
6599 <note>
6600 Note that discarding the current snapshot
6601 will implicitly call <link to="IMachine::saveSettings"/> to
6602 make all current machine settings permanent.
6603 </note>
6604 <result name="VBOX_E_INVALID_VM_STATE">
6605 Virtual machine is running.
6606 </result>
6607 </desc>
6608 <param name="id" type="uuid" dir="in">
6609 <desc>UUID of the snapshot to discard.</desc>
6610 </param>
6611 <param name="progress" type="IProgress" dir="return">
6612 <desc>Progress object to track the operation completion.</desc>
6613 </param>
6614 </method>
6615
6616 <method name="discardCurrentState">
6617 <desc>
6618 This operation is similar to <link to="IConsole::discardSnapshot"/> but
6619 affects the current machine state. This means that the state stored in
6620 the current snapshot will become a new current state, and all current
6621 settings of the machine and changes stored in differencing hard disks
6622 will be lost.
6623
6624 After this operation is successfully completed, new empty differencing
6625 hard disks are created for all normal hard disks of the machine.
6626
6627 If the current snapshot of the machine is an online snapshot, the
6628 machine will go to the <link to="MachineState_Saved"> saved
6629 state</link>, so that the next time it is powered on, the execution
6630 state will be restored from the current snapshot.
6631
6632 <note>
6633 The machine must not be running, otherwise the operation will fail.
6634 </note>
6635
6636 <note>
6637 If the machine state is <link to="MachineState_Saved">Saved</link>
6638 prior to this operation, the saved state file will be implicitly
6639 discarded (as if <link to="IConsole::discardSavedState"/> were
6640 called).
6641 </note>
6642
6643 <result name="VBOX_E_INVALID_VM_STATE">
6644 Virtual machine is running.
6645 </result>
6646 </desc>
6647 <param name="progress" type="IProgress" dir="return">
6648 <desc>Progress object to track the operation completion.</desc>
6649 </param>
6650 </method>
6651
6652 <method name="discardCurrentSnapshotAndState">
6653 <desc>
6654
6655 This method is equivalent to
6656 doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
6657 (currentSnapshot.id(), progress) followed by
6658 <link to="IConsole::discardCurrentState"/>.
6659
6660 As a result, the machine will be fully restored from the
6661 snapshot preceding the current snapshot, while both the current
6662 snapshot and the current machine state will be discarded.
6663
6664 If the current snapshot is the first snapshot of the machine (i.e. it
6665 has the only snapshot), the current machine state will be
6666 discarded <b>before</b> discarding the snapshot. In other words, the
6667 machine will be restored from its last snapshot, before discarding
6668 it. This differs from performing a single
6669 <link to="IConsole::discardSnapshot"/> call (note that no
6670 <link to="IConsole::discardCurrentState"/> will be possible after it)
6671 to the effect that the latter will preserve the current state instead of
6672 discarding it.
6673
6674 Unless explicitly mentioned otherwise, all remarks and
6675 limitations of the above two methods also apply to this method.
6676
6677 <note>
6678 The machine must not be running, otherwise the operation
6679 will fail.
6680 </note>
6681
6682 <note>
6683 If the machine state is <link to="MachineState_Saved">Saved</link>
6684 prior to this operation, the saved state file will be implicitly
6685 discarded (as if <link to="#discardSavedState"/> were
6686 called).
6687 </note>
6688
6689 <note>
6690 This method is more efficient than calling both of the above
6691 methods separately: it requires less IPC calls and provides
6692 a single progress object.
6693 </note>
6694
6695 <result name="VBOX_E_INVALID_VM_STATE">
6696 Virtual machine is running.
6697 </result>
6698 </desc>
6699 <param name="progress" type="IProgress" dir="return">
6700 <desc>Progress object to track the operation completion.</desc>
6701 </param>
6702 </method>
6703
6704 <method name="registerCallback">
6705 <desc>
6706 Registers a new console callback on this instance. The methods of the
6707 callback interface will be called by this instance when the appropriate
6708 event occurs.
6709 </desc>
6710 <param name="callback" type="IConsoleCallback" dir="in"/>
6711 </method>
6712
6713 <method name="unregisterCallback">
6714 <desc>
6715 Unregisters the console callback previously registered using
6716 <link to="#registerCallback"/>.
6717 <result name="E_INVALIDARG">
6718 Given @a callback handler is not registered.
6719 </result>
6720 </desc>
6721 <param name="callback" type="IConsoleCallback" dir="in"/>
6722 </method>
6723 </interface>
6724
6725 <!--
6726 // IHost
6727 /////////////////////////////////////////////////////////////////////////
6728 -->
6729
6730 <interface
6731 name="IHostDVDDrive" extends="$unknown"
6732 uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
6733 wsmap="managed"
6734 >
6735 <desc>
6736 The IHostDVDDrive interface represents the physical CD/DVD drive
6737 hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
6738 </desc>
6739
6740 <attribute name="name" type="wstring" readonly="yes">
6741 <desc>
6742 Returns the platform-specific device identifier.
6743 On DOS-like platforms, it is a drive name (e.g. R:).
6744 On Unix-like platforms, it is a device name (e.g. /dev/hdc).
6745 </desc>
6746 </attribute>
6747 <attribute name="description" type="wstring" readonly="yes">
6748 <desc>
6749 Returns a human readable description for the drive. This
6750 description usually contains the product and vendor name. A
6751 @c null string is returned if the description is not available.
6752 </desc>
6753 </attribute>
6754 <attribute name="udi" type="wstring" readonly="yes">
6755 <desc>
6756 Returns the unique device identifier for the drive. This
6757 attribute is reserved for future use instead of
6758 <link to="#name"/>. Currently it is not used and may return
6759 @c null on some platforms.
6760 </desc>
6761 </attribute>
6762
6763 </interface>
6764
6765 <interface
6766 name="IHostFloppyDrive" extends="$unknown"
6767 uuid="3f02d604-e908-4919-9fd1-8a4afd68fc63"
6768 wsmap="managed"
6769 >
6770 <desc>
6771 The IHostFloppyDrive interface represents the physical floppy drive
6772 hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
6773 </desc>
6774 <attribute name="name" type="wstring" readonly="yes">
6775 <desc>
6776 Returns the platform-specific device identifier.
6777 On DOS-like platforms, it is a drive name (e.g. A:).
6778 On Unix-like platforms, it is a device name (e.g. /dev/fd0).
6779 </desc>
6780 </attribute>
6781 <attribute name="description" type="wstring" readonly="yes">
6782 <desc>
6783 Returns a human readable description for the drive. This
6784 description usually contains the product and vendor name. A
6785 @c null string is returned if the description is not available.
6786 </desc>
6787 </attribute>
6788 <attribute name="udi" type="wstring" readonly="yes">
6789 <desc>
6790 Returns the unique device identifier for the drive. This
6791 attribute is reserved for future use instead of
6792 <link to="#name"/>. Currently it is not used and may return
6793 @c null on some platforms.
6794 </desc>
6795 </attribute>
6796 </interface>
6797
6798 <enum
6799 name="HostNetworkInterfaceMediumType"
6800 uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
6801 >
6802 <desc>
6803 Type of encapsulation. Ethernet encapsulation includes both wired and
6804 wireless Ethernet connections.
6805 <see>IHostNetworkInterface</see>
6806 </desc>
6807
6808 <const name="Unknown" value="0">
6809 <desc>
6810 The type of interface cannot be determined.
6811 </desc>
6812 </const>
6813 <const name="Ethernet" value="1">
6814 <desc>
6815 Ethernet frame encapsulation.
6816 </desc>
6817 </const>
6818 <const name="PPP" value="2">
6819 <desc>
6820 Point-to-point protocol encapsulation.
6821 </desc>
6822 </const>
6823 <const name="SLIP" value="3">
6824 <desc>
6825 Serial line IP encapsulation.
6826 </desc>
6827 </const>
6828 </enum>
6829
6830 <enum
6831 name="HostNetworkInterfaceStatus"
6832 uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
6833 >
6834 <desc>
6835 Current status of the interface.
6836 <see>IHostNetworkInterface</see>
6837 </desc>
6838
6839 <const name="Unknown" value="0">
6840 <desc>
6841 The state of interface cannot be determined.
6842 </desc>
6843 </const>
6844 <const name="Up" value="1">
6845 <desc>
6846 The interface is fully operational.
6847 </desc>
6848 </const>
6849 <const name="Down" value="2">
6850 <desc>
6851 The interface is not functioning.
6852 </desc>
6853 </const>
6854 </enum>
6855
6856 <enum
6857 name="HostNetworkInterfaceType"
6858 uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
6859 >
6860 <desc>
6861 Network interface type.
6862 </desc>
6863 <const name="Bridged" value="1"/>
6864 <const name="HostOnly" value="2"/>
6865 </enum>
6866
6867 <interface
6868 name="IHostNetworkInterface" extends="$unknown"
6869 uuid="88adaf3f-166b-4542-9457-0f1323507fae"
6870 wsmap="managed"
6871 >
6872 <desc>
6873 Reprents one of host's network interfaces. IP V6 address and network
6874 mask are strings of 32 hexdecimal digits grouped by four. Groups are
6875 separated by colons.
6876 For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
6877 </desc>
6878 <attribute name="name" type="wstring" readonly="yes">
6879 <desc>Returns the host network interface name.</desc>
6880 </attribute>
6881
6882 <attribute name="id" type="uuid" readonly="yes">
6883 <desc>Returns the interface UUID.</desc>
6884 </attribute>
6885
6886 <attribute name="networkName" type="wstring" readonly="yes">
6887 <desc>Returns the name of a virtual network the interface gets attached to.</desc>
6888 </attribute>
6889
6890 <attribute name="dhcpEnabled" type="boolean" readonly="yes">
6891 <desc>Specifies whether the DHCP is enabled for the interface.</desc>
6892 </attribute>
6893
6894 <attribute name="IPAddress" type="wstring" readonly="yes">
6895 <desc>Returns the IP V4 address of the interface.</desc>
6896 </attribute>
6897
6898 <attribute name="networkMask" type="wstring" readonly="yes">
6899 <desc>Returns the network mask of the interface.</desc>
6900 </attribute>
6901
6902 <attribute name="IPV6Supported" type="boolean" readonly="yes">
6903 <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
6904 </attribute>
6905
6906 <attribute name="IPV6Address" type="wstring" readonly="yes">
6907 <desc>Returns the IP V6 address of the interface.</desc>
6908 </attribute>
6909
6910 <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
6911 <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
6912 </attribute>
6913
6914 <attribute name="hardwareAddress" type="wstring" readonly="yes">
6915 <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
6916 </attribute>
6917
6918 <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
6919 <desc>Type of protocol encapsulation used.</desc>
6920 </attribute>
6921
6922 <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
6923 <desc>Status of the interface.</desc>
6924 </attribute>
6925
6926 <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
6927 <desc>specifies the host interface type.</desc>
6928 </attribute>
6929
6930 <method name="enableStaticIpConfig">
6931 <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
6932 <param name="IPAddress" type="wstring" dir="in">
6933 <desc>
6934 IP address.
6935 </desc>
6936 </param>
6937 <param name="networkMask" type="wstring" dir="in">
6938 <desc>
6939 network mask.
6940 </desc>
6941 </param>
6942 </method>
6943
6944 <method name="enableStaticIpConfigV6">
6945 <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
6946 <param name="IPV6Address" type="wstring" dir="in">
6947 <desc>
6948 IP address.
6949 </desc>
6950 </param>
6951 <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
6952 <desc>
6953 network mask.
6954 </desc>
6955 </param>
6956 </method>
6957
6958 <method name="enableDynamicIpConfig">
6959 <desc>enables the dynamic IP configuration.</desc>
6960 </method>
6961
6962 <method name="dhcpRediscover">
6963 <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
6964 </method>
6965
6966 </interface>
6967
6968 <interface
6969 name="IHost" extends="$unknown"
6970 uuid="fa7b3d79-972c-4f18-9f61-6b20c88559b6"
6971 wsmap="managed"
6972 >
6973 <desc>
6974 The IHost interface represents the physical machine that this VirtualBox
6975 installation runs on.
6976
6977 An object implementing this interface is returned by the
6978 <link to="IVirtualBox::host" /> attribute. This interface contains
6979 read-only information about the host's physical hardware (such as what
6980 processors and disks are available, what the host operating system is,
6981 and so on) and also allows for manipulating some of the host's hardware,
6982 such as global USB device filters and host interface networking.
6983
6984 </desc>
6985 <attribute name="DVDDrives" type="IHostDVDDrive" readonly="yes" safearray="yes">
6986 <desc>List of DVD drives available on the host.</desc>
6987 </attribute>
6988
6989 <attribute name="floppyDrives" type="IHostFloppyDrive" readonly="yes" safearray="yes">
6990 <desc>List of floppy drives available on the host.</desc>
6991 </attribute>
6992
6993 <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6994 <desc>
6995 List of USB devices currently attached to the host.
6996 Once a new device is physically attached to the host computer,
6997 it appears in this list and remains there until detached.
6998
6999 <note>
7000 If USB functionality is not available in the given edition of
7001 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7002 </note>
7003 </desc>
7004 </attribute>
7005
7006 <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
7007 <desc>
7008 List of USB device filters in action.
7009 When a new device is physically attached to the host computer,
7010 filters from this list are applied to it (in order they are stored
7011 in the list). The first matched filter will determine the
7012 <link to="IHostUSBDeviceFilter::action">action</link>
7013 performed on the device.
7014
7015 Unless the device is ignored by these filters, filters of all
7016 currently running virtual machines
7017 (<link to="IUSBController::deviceFilters"/>) are applied to it.
7018
7019 <note>
7020 If USB functionality is not available in the given edition of
7021 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7022 </note>
7023
7024 <see>IHostUSBDeviceFilter, USBDeviceState</see>
7025 </desc>
7026 </attribute>
7027
7028 <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
7029 <desc>List of host network interfaces currently defined on the host.</desc>
7030 </attribute>
7031
7032 <attribute name="processorCount" type="unsigned long" readonly="yes">
7033 <desc>Number of (logical) CPUs installed in the host system.</desc>
7034 </attribute>
7035
7036 <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
7037 <desc>Number of (logical) CPUs online in the host system.</desc>
7038 </attribute>
7039
7040 <method name="getProcessorSpeed">
7041 <desc>Query the (approximate) maximum speed of a specified host CPU in
7042 Megahertz.
7043 </desc>
7044 <param name="cpuId" type="unsigned long" dir="in">
7045 <desc>
7046 Identifier of the CPU.
7047 </desc>
7048 </param>
7049 <param name="speed" type="unsigned long" dir="return">
7050 <desc>
7051 Speed value. 0 is returned if value is not known or @a cpuId is
7052 invalid.
7053 </desc>
7054 </param>
7055 </method>
7056
7057 <method name="getProcessorFeature">
7058 <desc>Query whether a CPU feature is supported or not.</desc>
7059 <param name="feature" type="ProcessorFeature" dir="in">
7060 <desc>
7061 CPU Feature identifier.
7062 </desc>
7063 </param>
7064 <param name="supported" type="boolean" dir="return">
7065 <desc>
7066 Feature is supported or not.
7067 </desc>
7068 </param>
7069 </method>
7070
7071 <method name="getProcessorDescription">
7072 <desc>Query the model string of a specified host CPU.
7073 <note>
7074 This function is not implemented in the current version of the
7075 product.
7076 </note>
7077 </desc>
7078 <param name="cpuId" type="unsigned long" dir="in">
7079 <desc>
7080 Identifier of the CPU.
7081 </desc>
7082 </param>
7083 <param name="description" type="wstring" dir="return">
7084 <desc>
7085 Model string. A NULL string is returned if value is not known or
7086 @a cpuId is invalid.
7087 </desc>
7088 </param>
7089 </method>
7090
7091 <attribute name="memorySize" type="unsigned long" readonly="yes">
7092 <desc>Amount of system memory in megabytes installed in the host system.</desc>
7093 </attribute>
7094
7095 <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
7096 <desc>Available system memory in the host system.</desc>
7097 </attribute>
7098
7099 <attribute name="operatingSystem" type="wstring" readonly="yes">
7100 <desc>Name of the host system's operating system.</desc>
7101 </attribute>
7102
7103 <attribute name="OSVersion" type="wstring" readonly="yes">
7104 <desc>Host operating system's version string.</desc>
7105 </attribute>
7106
7107 <attribute name="UTCTime" type="long long" readonly="yes">
7108 <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
7109 </attribute>
7110
7111 <method name="createHostOnlyNetworkInterface">
7112 <desc>
7113 Creates a new adapter for Host Only Networking.
7114 <result name="E_INVALIDARG">
7115 Host network interface @a name already exists.
7116 </result>
7117 </desc>
7118 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
7119 <desc>
7120 Created host interface object.
7121 </desc>
7122 </param>
7123 <param name="progress" type="IProgress" dir="return">
7124 <desc>
7125 Progress object to track the operation completion.
7126 </desc>
7127 </param>
7128 </method>
7129
7130 <method name="removeHostOnlyNetworkInterface">
7131 <desc>
7132 Removes the given Host Only Networking interface.
7133 <result name="VBOX_E_OBJECT_NOT_FOUND">
7134 No host network interface matching @a id found.
7135 </result>
7136 </desc>
7137 <param name="id" type="uuid" dir="in">
7138 <desc>
7139 Adapter GUID.
7140 </desc>
7141 </param>
7142 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
7143 <desc>
7144 Removed host interface object.
7145 </desc>
7146 </param>
7147 <param name="progress" type="IProgress" dir="return">
7148 <desc>
7149 Progress object to track the operation completion.
7150 </desc>
7151 </param>
7152 </method>
7153
7154 <method name="createUSBDeviceFilter">
7155 <desc>
7156 Creates a new USB device filter. All attributes except
7157 the filter name are set to <tt>null</tt> (any match),
7158 <i>active</i> is <tt>false</tt> (the filter is not active).
7159
7160 The created filter can be added to the list of filters using
7161 <link to="#insertUSBDeviceFilter"/>.
7162
7163 <see>#USBDeviceFilters</see>
7164 </desc>
7165 <param name="name" type="wstring" dir="in">
7166 <desc>
7167 Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7168 for more info.
7169 </desc>
7170 </param>
7171 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
7172 <desc>Created filter object.</desc>
7173 </param>
7174 </method>
7175
7176 <method name="insertUSBDeviceFilter">
7177 <desc>
7178 Inserts the given USB device to the specified position
7179 in the list of filters.
7180
7181 Positions are numbered starting from <tt>0</tt>. If the specified
7182 position is equal to or greater than the number of elements in
7183 the list, the filter is added at the end of the collection.
7184
7185 <note>
7186 Duplicates are not allowed, so an attempt to insert a
7187 filter already in the list is an error.
7188 </note>
7189 <note>
7190 If USB functionality is not available in the given edition of
7191 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7192 </note>
7193
7194 <see>#USBDeviceFilters</see>
7195
7196 <result name="VBOX_E_INVALID_OBJECT_STATE">
7197 USB device filter is not created within this VirtualBox instance.
7198 </result>
7199 <result name="E_INVALIDARG">
7200 USB device filter already in list.
7201 </result>
7202
7203 </desc>
7204 <param name="position" type="unsigned long" dir="in">
7205 <desc>Position to insert the filter to.</desc>
7206 </param>
7207 <param name="filter" type="IHostUSBDeviceFilter" dir="in">
7208 <desc>USB device filter to insert.</desc>
7209 </param>
7210 </method>
7211
7212 <method name="removeUSBDeviceFilter">
7213 <desc>
7214 Removes a USB device filter from the specified position in the
7215 list of filters.
7216
7217 Positions are numbered starting from <tt>0</tt>. Specifying a
7218 position equal to or greater than the number of elements in
7219 the list will produce an error.
7220
7221 <note>
7222 If USB functionality is not available in the given edition of
7223 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7224 </note>
7225
7226 <see>#USBDeviceFilters</see>
7227
7228 <result name="E_INVALIDARG">
7229 USB device filter list empty or invalid @a position.
7230 </result>
7231
7232 </desc>
7233 <param name="position" type="unsigned long" dir="in">
7234 <desc>Position to remove the filter from.</desc>
7235 </param>
7236 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
7237 <desc>Removed USB device filter.</desc>
7238 </param>
7239 </method>
7240
7241 <method name="findHostDVDDrive">
7242 <desc>
7243 Searches for a host DVD drive with the given @c name.
7244
7245 <result name="VBOX_E_OBJECT_NOT_FOUND">
7246 Given @c name does not correspond to any host drive.
7247 </result>
7248
7249 </desc>
7250 <param name="name" type="wstring" dir="in">
7251 <desc>Name of the host drive to search for</desc>
7252 </param>
7253 <param name="drive" type="IHostDVDDrive" dir="return">
7254 <desc>Found host drive object</desc>
7255 </param>
7256 </method>
7257
7258 <method name="findHostFloppyDrive">
7259 <desc>
7260 Searches for a host floppy drive with the given @c name.
7261
7262 <result name="VBOX_E_OBJECT_NOT_FOUND">
7263 Given @c name does not correspond to any host floppy drive.
7264 </result>
7265
7266 </desc>
7267 <param name="name" type="wstring" dir="in">
7268 <desc>Name of the host floppy drive to search for</desc>
7269 </param>
7270 <param name="drive" type="IHostFloppyDrive" dir="return">
7271 <desc>Found host floppy drive object</desc>
7272 </param>
7273 </method>
7274
7275 <method name="findHostNetworkInterfaceByName">
7276 <desc>
7277 Searches through all host network interfaces for an interface with
7278 the given @c name.
7279 <note>
7280 The method returns an error if the given @c name does not
7281 correspond to any host network interface.
7282 </note>
7283 </desc>
7284 <param name="name" type="wstring" dir="in">
7285 <desc>Name of the host network interface to search for.</desc>
7286 </param>
7287 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7288 <desc>Found host network interface object.</desc>
7289 </param>
7290 </method>
7291 <method name="findHostNetworkInterfaceById">
7292 <desc>
7293 Searches through all host network interfaces for an interface with
7294 the given GUID.
7295 <note>
7296 The method returns an error if the given GUID does not
7297 correspond to any host network interface.
7298 </note>
7299 </desc>
7300 <param name="id" type="uuid" dir="in">
7301 <desc>GUID of the host network interface to search for.</desc>
7302 </param>
7303 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7304 <desc>Found host network interface object.</desc>
7305 </param>
7306 </method>
7307 <method name="findHostNetworkInterfacesOfType">
7308 <desc>
7309 Searches through all host network interfaces and returns a list of interfaces of the specified type
7310 </desc>
7311 <param name="type" type="HostNetworkInterfaceType" dir="in">
7312 <desc>type of the host network interfaces to search for.</desc>
7313 </param>
7314 <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7315 <desc>Found host network interface objects.</desc>
7316 </param>
7317 </method>
7318
7319 <method name="findUSBDeviceById">
7320 <desc>
7321 Searches for a USB device with the given UUID.
7322
7323 <result name="VBOX_E_OBJECT_NOT_FOUND">
7324 Given @c id does not correspond to any USB device.
7325 </result>
7326
7327 <see>IHostUSBDevice::id</see>
7328 </desc>
7329 <param name="id" type="uuid" dir="in">
7330 <desc>UUID of the USB device to search for.</desc>
7331 </param>
7332 <param name="device" type="IHostUSBDevice" dir="return">
7333 <desc>Found USB device object.</desc>
7334 </param>
7335 </method>
7336
7337 <method name="findUSBDeviceByAddress">
7338 <desc>
7339 Searches for a USB device with the given host address.
7340
7341 <result name="VBOX_E_OBJECT_NOT_FOUND">
7342 Given @c name does not correspond to any USB device.
7343 </result>
7344
7345 <see>IHostUSBDevice::address</see>
7346 </desc>
7347 <param name="name" type="wstring" dir="in">
7348 <desc>
7349 Address of the USB device (as assigned by the host) to
7350 search for.
7351 </desc>
7352 </param>
7353 <param name="device" type="IHostUSBDevice" dir="return">
7354 <desc>Found USB device object.</desc>
7355 </param>
7356 </method>
7357
7358 </interface>
7359
7360 <!--
7361 // ISystemProperties
7362 /////////////////////////////////////////////////////////////////////////
7363 -->
7364
7365 <interface
7366 name="ISystemProperties"
7367 extends="$unknown"
7368 uuid="0760e03f-06d0-481e-9f81-be43fef092ba"
7369 wsmap="managed"
7370 >
7371 <desc>
7372 The ISystemProperties interface represents global properties of the given
7373 VirtualBox installation.
7374
7375 These properties define limits and default values for various attributes
7376 and parameters. Most of the properties are read-only, but some can be
7377 changed by a user.
7378 </desc>
7379
7380 <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7381 <desc>Minimum guest system memory in Megabytes.</desc>
7382 </attribute>
7383
7384 <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7385 <desc>Maximum guest system memory in Megabytes.</desc>
7386 </attribute>
7387
7388 <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7389 <desc>Minimum guest video memory in Megabytes.</desc>
7390 </attribute>
7391
7392 <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7393 <desc>Maximum guest video memory in Megabytes.</desc>
7394 </attribute>
7395
7396 <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7397 <desc>Minimum CPU count.</desc>
7398 </attribute>
7399
7400 <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7401 <desc>Maximum CPU count.</desc>
7402 </attribute>
7403
7404 <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
7405 <desc>Maximum size of a virtual disk image in Megabytes.</desc>
7406 </attribute>
7407
7408 <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
7409 <desc>
7410 Number of network adapters associated with every
7411 <link to="IMachine"/> instance.
7412 </desc>
7413 </attribute>
7414
7415 <attribute name="serialPortCount" type="unsigned long" readonly="yes">
7416 <desc>
7417 Number of serial ports associated with every
7418 <link to="IMachine"/> instance.
7419 </desc>
7420 </attribute>
7421
7422 <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
7423 <desc>
7424 Number of parallel ports associated with every
7425 <link to="IMachine"/> instance.
7426 </desc>
7427 </attribute>
7428
7429 <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
7430 <desc>
7431 Maximum device position in the boot order. This value corresponds
7432 to the total number of devices a machine can boot from, to make it
7433 possible to include all possible devices to the boot list.
7434 <see><link to="IMachine::setBootOrder"/></see>
7435 </desc>
7436 </attribute>
7437
7438 <attribute name="defaultMachineFolder" type="wstring">
7439 <desc>
7440 Full path to the default directory used to create new or open
7441 existing machines when a settings file name contains no
7442 path.
7443
7444 The initial value of this property is
7445 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
7446 VirtualBox_home</link><tt>&gt;/Machines</tt>.
7447
7448 <note>
7449 Setting this property to <tt>null</tt> will restore the
7450 initial value.
7451 </note>
7452 <note>
7453 When settings this property, the specified path can be
7454 absolute (full path) or relative
7455 to the <link to="IVirtualBox::homeFolder">
7456 VirtualBox home directory</link>.
7457 When reading this property, a full path is
7458 always returned.
7459 </note>
7460 <note>
7461 The specified path may not exist, it will be created
7462 when necessary.
7463 </note>
7464
7465 <see>
7466 <link to="IVirtualBox::createMachine"/>,
7467 <link to="IVirtualBox::openMachine"/>
7468 </see>
7469 </desc>
7470 </attribute>
7471
7472 <attribute name="defaultHardDiskFolder" type="wstring">
7473 <desc>
7474 Full path to the default directory used to create new or open existing
7475 virtual disks.
7476
7477 This path is used when the storage unit of a hard disk is a regular file
7478 in the host's file system and only a file name that contains no path is
7479 given.
7480
7481 The initial value of this property is
7482 <tt>&lt;</tt>
7483 <link to="IVirtualBox::homeFolder">VirtualBox_home</link>
7484 <tt>&gt;/HardDisks</tt>.
7485
7486 <note>
7487 Setting this property to <tt>null</tt> will restore the
7488 initial value.
7489 </note>
7490 <note>
7491 When settings this property, the specified path can be relative
7492 to the
7493 <link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
7494 absolute. When reading this property, a full path is
7495 always returned.
7496 </note>
7497 <note>
7498 The specified path may not exist, it will be created
7499 when necessary.
7500 </note>
7501
7502 <see>
7503 IHardDisk,
7504 <link to="IVirtualBox::createHardDisk"/>,
7505 <link to="IVirtualBox::openHardDisk"/>,
7506 <link to="IMedium::location"/>
7507 </see>
7508 </desc>
7509 </attribute>
7510
7511 <attribute name="hardDiskFormats" type="IHardDiskFormat" safearray="yes" readonly="yes">
7512 <desc>
7513 List of all hard disk storage formats supported by this VirtualBox
7514 installation.
7515
7516 Keep in mind that the hard disk format identifier
7517 (<link to="IHardDiskFormat::id"/>) used in other API calls like
7518 <link to="IVirtualBox::createHardDisk"/> to refer to a particular
7519 hard disk format is a case-insensitive string. This means that, for
7520 example, all of the following strings:
7521 <pre>
7522 "VDI"
7523 "vdi"
7524 "VdI"</pre>
7525 refer to the same hard disk format.
7526
7527 Note that the virtual hard disk framework is backend-based, therefore
7528 the list of supported formats depends on what backends are currently
7529 installed.
7530
7531 <see>
7532 <link to="IHardDiskFormat"/>,
7533 </see>
7534 </desc>
7535 </attribute>
7536
7537 <attribute name="defaultHardDiskFormat" type="wstring">
7538 <desc>
7539 Identifier of the default hard disk format used by VirtualBox.
7540
7541 The hard disk format set by this attribute is used by VirtualBox
7542 when the hard disk format was not specified explicitly. One example is
7543 <link to="IVirtualBox::createHardDisk"/> with the <tt>null</tt>
7544 format argument. A more complex example is implicit creation of
7545 differencing hard disks when taking a snapshot of a virtual machine:
7546 this operation will try to use a format of the parent hard disk first
7547 and if this format does not support differencing hard disks the default
7548 format specified by this argument will be used.
7549
7550 The list of supported hard disk formats may be obtained by the
7551 <link to="#hardDiskFormats"/> call. Note that the default hard disk
7552 format must have a capability to create differencing hard disks;
7553 otherwise opeartions that create hard disks implicitly may fail
7554 unexpectedly.
7555
7556 The initial value of this property is <tt>VDI</tt> in the current
7557 version of the VirtualBox product, but may change in the future.
7558
7559 <note>
7560 Setting this property to <tt>null</tt> will restore the
7561 initial value.
7562 </note>
7563
7564 <see>
7565 <link to="#hardDiskFormats"/>,
7566 <link to="IHardDiskFormat::id"/>,
7567 <link to="IVirtualBox::createHardDisk"/>
7568 </see>
7569 </desc>
7570 </attribute>
7571
7572 <attribute name="remoteDisplayAuthLibrary" type="wstring">
7573 <desc>
7574 Library that provides authentication for VRDP clients. The library
7575 is used if a virtual machine's authentication type is set to "external"
7576 in the VM RemoteDisplay configuration.
7577
7578 The system library extension (".DLL" or ".so") must be omitted.
7579 A full path can be specified; if not, then the library must reside on the
7580 system's default library path.
7581
7582 The default value of this property is <tt>VRDPAuth</tt>. There is a library
7583 of that name in one of the default VirtualBox library directories.
7584
7585 For details about VirtualBox authentication libraries and how to implement
7586 them, please refer to the VirtualBox manual.
7587
7588 <note>
7589 Setting this property to <tt>null</tt> will restore the
7590 initial value.
7591 </note>
7592 </desc>
7593 </attribute>
7594
7595 <attribute name="webServiceAuthLibrary" type="wstring">
7596 <desc>
7597 Library that provides authentication for webservice clients. The library
7598 is used if a virtual machine's authentication type is set to "external"
7599 in the VM RemoteDisplay configuration and will be called from
7600 within the <link to="IWebsessionManager::logon" /> implementation.
7601
7602 As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
7603 there is no per-VM setting for this, as the webservice is a global
7604 resource (if it is running). Only for this setting (for the webservice),
7605 setting this value to a literal "null" string disables authentication,
7606 meaning that <link to="IWebsessionManager::logon" /> will always succeed,
7607 no matter what user name and password are supplied.
7608
7609 The initial value of this property is <tt>VRDPAuth</tt>,
7610 meaning that the webservice will use the same authentication
7611 library that is used by default for VBoxVRDP (again, see
7612 <link to="ISystemProperties::remoteDisplayAuthLibrary" />).
7613 The format and calling convention of authentication libraries
7614 is the same for the webservice as it is for VBoxVRDP.
7615
7616 </desc>
7617 </attribute>
7618
7619 <attribute name="HWVirtExEnabled" type="boolean">
7620 <desc>
7621 This specifies the default value for hardware virtualization
7622 extensions. If enabled, virtual machines will make use of
7623 hardware virtualization extensions such as Intel VT-x and
7624 AMD-V by default. This value can be overridden by each VM
7625 using their <link to="IMachine::HWVirtExEnabled" /> property.
7626 </desc>
7627 </attribute>
7628
7629 <attribute name="LogHistoryCount" type="unsigned long">
7630 <desc>
7631 This value specifies how many old release log files are kept.
7632 </desc>
7633 </attribute>
7634 </interface>
7635
7636 <!--
7637 // IGuest
7638 /////////////////////////////////////////////////////////////////////////
7639 -->
7640
7641 <interface
7642 name="IGuestOSType" extends="$unknown"
7643 uuid="cfe9e64c-4430-435b-9e7c-e3d8e417bd58"
7644 wsmap="struct"
7645 >
7646 <desc>
7647 </desc>
7648
7649 <attribute name="familyId" type="wstring" readonly="yes">
7650 <desc>Guest OS family identifier string.</desc>
7651 </attribute>
7652
7653 <attribute name="familyDescription" type="wstring" readonly="yes">
7654 <desc>Human readable description of the guest OS family.</desc>
7655 </attribute>
7656
7657 <attribute name="id" type="wstring" readonly="yes">
7658 <desc>Guest OS identifier string.</desc>
7659 </attribute>
7660
7661 <attribute name="description" type="wstring" readonly="yes">
7662 <desc>Human readable description of the guest OS.</desc>
7663 </attribute>
7664
7665 <attribute name="is64Bit" type="boolean" readonly="yes">
7666 <desc>Returns @c true if the given OS is 64-bit</desc>
7667 </attribute>
7668
7669 <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
7670 <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
7671 </attribute>
7672
7673 <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
7674 <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
7675 </attribute>
7676
7677 <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
7678 <desc>Recommended RAM size in Megabytes.</desc>
7679 </attribute>
7680
7681 <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
7682 <desc>Recommended video RAM size in Megabytes.</desc>
7683 </attribute>
7684
7685 <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
7686 <desc>Recommended hard disk size in Megabytes.</desc>
7687 </attribute>
7688
7689 <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
7690 <desc>Returns recommended network adapter for this OS type.</desc>
7691 </attribute>
7692 </interface>
7693
7694 <interface
7695 name="IGuest" extends="$unknown"
7696 uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
7697
7698 wsmap="suppress"
7699 >
7700 <desc>
7701 The IGuest interface represents information about the operating system
7702 running inside the virtual machine. Used in
7703 <link to="IConsole::guest"/>.
7704
7705 IGuest provides information about the guest operating system, whether
7706 Guest Additions are installed and other OS-specific virtual machine
7707 properties.
7708 </desc>
7709
7710 <attribute name="OSTypeId" type="wstring" readonly="yes">
7711 <desc>
7712 Identifier of the Guest OS type as reported by the Guest
7713 Additions.
7714 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
7715 an IGuestOSType object representing details about the given
7716 Guest OS type.
7717 <note>
7718 If Guest Additions are not installed, this value will be
7719 the same as <link to="IMachine::OSTypeId"/>.
7720 </note>
7721 </desc>
7722 </attribute>
7723
7724 <attribute name="additionsActive" type="boolean" readonly="yes">
7725 <desc>
7726 Flag whether the Guest Additions are installed and active
7727 in which case their version will be returned by the
7728 <link to="#additionsVersion"/> property.
7729 </desc>
7730 </attribute>
7731
7732 <attribute name="additionsVersion" type="wstring" readonly="yes">
7733 <desc>
7734 Version of the Guest Additions (3 decimal numbers separated
7735 by dots) or empty when the Additions are not installed. The
7736 Additions may also report a version but yet not be active as
7737 the version might be refused by VirtualBox (incompatible) or
7738 other failures occurred.
7739 </desc>
7740 </attribute>
7741
7742 <attribute name="supportsSeamless" type="boolean" readonly="yes">
7743 <desc>
7744 Flag whether seamless guest display rendering (seamless desktop
7745 integration) is supported.
7746 </desc>
7747 </attribute>
7748
7749 <attribute name="supportsGraphics" type="boolean" readonly="yes">
7750 <desc>
7751 Flag whether the guest is in graphics mode. If it is not, then
7752 seamless rendering will not work, resize hints are not immediately
7753 acted on and guest display resizes are probably not initiated by
7754 the guest additions.
7755 </desc>
7756 </attribute>
7757
7758 <attribute name="memoryBalloonSize" type="unsigned long">
7759 <desc>Guest system memory balloon size in megabytes.</desc>
7760 </attribute>
7761
7762 <attribute name="statisticsUpdateInterval" type="unsigned long">
7763 <desc>Interval to update guest statistics in seconds.</desc>
7764 </attribute>
7765
7766 <method name="setCredentials">
7767 <desc>
7768 Store login credentials that can be queried by guest operating
7769 systems with Additions installed. The credentials are transient
7770 to the session and the guest may also choose to erase them. Note
7771 that the caller cannot determine whether the guest operating system
7772 has queried or made use of the credentials.
7773
7774 <result name="VBOX_E_VM_ERROR">
7775 VMM device is not available.
7776 </result>
7777
7778 </desc>
7779 <param name="userName" type="wstring" dir="in">
7780 <desc>User name string, can be empty</desc>
7781 </param>
7782 <param name="password" type="wstring" dir="in">
7783 <desc>Password string, can be empty</desc>
7784 </param>
7785 <param name="domain" type="wstring" dir="in">
7786 <desc>Domain name (guest logon scheme specific), can be empty</desc>
7787 </param>
7788 <param name="allowInteractiveLogon" type="boolean" dir="in">
7789 <desc>
7790 Flag whether the guest should alternatively allow the user to
7791 interactively specify different credentials. This flag might
7792 not be supported by all versions of the Additions.
7793 </desc>
7794 </param>
7795 </method>
7796
7797 <method name="getStatistic">
7798 <desc>
7799 Query specified guest statistics as reported by the VirtualBox Additions.
7800 </desc>
7801 <param name="cpuId" type="unsigned long" dir="in">
7802 <desc>Virtual CPU id; not relevant for all statistic types</desc>
7803 </param>
7804 <param name="statistic" type="GuestStatisticType" dir="in">
7805 <desc>Statistic type.</desc>
7806 </param>
7807 <param name="statVal" type="unsigned long" dir="out">
7808 <desc>Statistics value</desc>
7809 </param>
7810 </method>
7811
7812 </interface>
7813
7814
7815 <!--
7816 // IProgress
7817 /////////////////////////////////////////////////////////////////////////
7818 -->
7819
7820 <interface
7821 name="IProgress" extends="$unknown"
7822 uuid="c4f94e6b-2273-446b-9539-4c05bb416fe7"
7823 wsmap="managed"
7824 >
7825 <desc>
7826 The IProgress interface is used to track and control
7827 asynchronous tasks within VirtualBox.
7828
7829 An instance of this is returned every time VirtualBox starts
7830 an asynchronous task (in other words, a separate thread) which
7831 continues to run after a method call returns. For example,
7832 <link to="IConsole::saveState" />, which saves the state of
7833 a running virtual machine, can take a long time to complete.
7834 To be able to display a progress bar, a user interface such as
7835 the VirtualBox graphical user interface can use the IProgress
7836 object returned by that method.
7837
7838 Note that IProgress is a "read-only" interface in the sense
7839 that only the VirtualBox internals behind the Main API can
7840 create and manipulate progress objects, whereas client code
7841 can only use the IProgress object to monitor a task's
7842 progress and, if <link to="#cancelable" /> is true,
7843 cancel the task by calling <link to="#cancel" />.
7844
7845 A task represented by IProgress consists of either one or
7846 several sub-operations that run sequentially, one by one (see
7847 <link to="#operation" /> and <link to="#operationCount" />).
7848 Every operation is identified by a number (starting from 0)
7849 and has a separate description.
7850
7851 You can find the individual percentage of completion of the current
7852 operation in <link to="#operationPercent" /> and the
7853 percentage of completion of the task as a whole
7854 in <link to="#percent" />.
7855
7856 Similarly, you can wait for the completion of a particular
7857 operation via <link to="#waitForOperationCompletion" /> or
7858 for the completion of the whole task via
7859 <link to="#waitForCompletion" />.
7860 </desc>
7861
7862 <attribute name="id" type="uuid" readonly="yes">
7863 <desc>ID of the task.</desc>
7864 </attribute>
7865
7866 <attribute name="description" type="wstring" readonly="yes">
7867 <desc>Description of the task.</desc>
7868 </attribute>
7869
7870 <attribute name="initiator" type="$unknown" readonly="yes">
7871 <desc>Initiator of the task.</desc>
7872 </attribute>
7873
7874 <attribute name="cancelable" type="boolean" readonly="yes">
7875 <desc>Whether the task can be interrupted.</desc>
7876 </attribute>
7877
7878 <attribute name="percent" type="unsigned long" readonly="yes">
7879 <desc>
7880 Current progress value of the task as a whole, in percent.
7881 This value depends on how many operations are already complete.
7882 Returns 100 if <link to="#completed" /> is true.
7883 </desc>
7884 </attribute>
7885
7886 <attribute name="timeRemaining" type="long" readonly="yes">
7887 <desc>
7888 Estimated remaining time until the task completes, in
7889 seconds. Returns 0 once the task has completed; returns -1
7890 if the remaining time cannot be computed, in particular if
7891 the current progress is 0.
7892
7893 Even if a value is returned, the estimate will be unreliable
7894 for low progress values. It will become more reliable as the
7895 task progresses; it is not recommended to display an ETA
7896 before at least 20% of a task have completed.
7897 </desc>
7898 </attribute>
7899
7900 <attribute name="completed" type="boolean" readonly="yes">
7901 <desc>Whether the task has been completed.</desc>
7902 </attribute>
7903
7904 <attribute name="canceled" type="boolean" readonly="yes">
7905 <desc>Whether the task has been canceled.</desc>
7906 </attribute>
7907
7908 <attribute name="resultCode" type="result" readonly="yes">
7909 <desc>
7910 Result code of the progress task.
7911 Valid only if <link to="#completed"/> is true.
7912 </desc>
7913 </attribute>
7914
7915 <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
7916 <desc>
7917 Extended information about the unsuccessful result of the
7918 progress operation. May be NULL if no extended information
7919 is available.
7920 Valid only if <link to="#completed"/> is true and
7921 <link to="#resultCode"/> indicates a failure.
7922 </desc>
7923 </attribute>
7924
7925 <attribute name="operationCount" type="unsigned long" readonly="yes">
7926 <desc>
7927 Number of sub-operations this task is divided into.
7928 Every task consists of at least one suboperation.
7929 </desc>
7930 </attribute>
7931
7932 <attribute name="operation" type="unsigned long" readonly="yes">
7933 <desc>Number of the sub-operation being currently executed.</desc>
7934 </attribute>
7935
7936 <attribute name="operationDescription" type="wstring" readonly="yes">
7937 <desc>
7938 Description of the sub-operation being currently executed.
7939 </desc>
7940 </attribute>
7941
7942 <attribute name="operationPercent" type="unsigned long" readonly="yes">
7943 <desc>Progress value of the current sub-operation only, in percent.</desc>
7944 </attribute>
7945
7946 <method name="waitForCompletion">
7947 <desc>
7948 Waits until the task is done (including all sub-operations)
7949 with a given timeout in milliseconds; specify -1 for an indefinite wait.
7950
7951 <result name="VBOX_E_IPRT_ERROR">
7952 Failed to wait for task completion.
7953 </result>
7954 </desc>
7955
7956 <param name="timeout" type="long" dir="in">
7957 <desc>
7958 Maximum time in milliseconds to wait or -1 to wait indefinitely.
7959 </desc>
7960 </param>
7961 </method>
7962
7963 <method name="waitForOperationCompletion">
7964 <desc>
7965 Waits until the given operation is done with a given timeout in
7966 milliseconds; specify -1 for an indefinite wait.
7967
7968 <result name="VBOX_E_IPRT_ERROR">
7969 Failed to wait for operation completion.
7970 </result>
7971
7972 </desc>
7973 <param name="operation" type="unsigned long" dir="in">
7974 <desc>
7975 Number of the operation to wait for.
7976 Must be less than <link to="#operationCount"/>.
7977 </desc>
7978 </param>
7979 <param name="timeout" type="long" dir="in">
7980 <desc>
7981 Maximum time in milliseconds to wait or -1 to wait indefinitely.
7982 </desc>
7983 </param>
7984 </method>
7985
7986 <method name="cancel">
7987 <desc>
7988 Cancels the task.
7989 <note>
7990 If <link to="#cancelable"/> is <tt>false</tt>, then
7991 this method will fail.
7992 </note>
7993
7994 <result name="VBOX_E_INVALID_OBJECT_STATE">
7995 Operation cannot be canceled.
7996 </result>
7997
7998 </desc>
7999 </method>
8000
8001 </interface>
8002
8003
8004 <!--
8005 // ISnapshot
8006 /////////////////////////////////////////////////////////////////////////
8007 -->
8008
8009 <interface
8010 name="ISnapshot" extends="$unknown"
8011 uuid="5db6b1d9-c76b-4424-a6f4-8257f642d6ea"
8012 wsmap="managed"
8013 >
8014 <desc>
8015 The ISnapshot interface represents a snapshot of the virtual
8016 machine.
8017
8018 The <i>snapshot</i> stores all the information about a virtual
8019 machine necessary to bring it to exactly the same state as it was at
8020 the time of taking the snapshot. The snapshot includes:
8021
8022 <ul>
8023 <li>all settings of the virtual machine (i.e. its hardware
8024 configuration: RAM size, attached hard disks, etc.)
8025 </li>
8026 <li>the execution state of the virtual machine (memory contents,
8027 CPU state, etc.).
8028 </li>
8029 </ul>
8030
8031 Snapshots can be <i>offline</i> (taken when the VM is powered off)
8032 or <i>online</i> (taken when the VM is running). The execution
8033 state of the offline snapshot is called a <i>zero execution state</i>
8034 (it doesn't actually contain any information about memory contents
8035 or the CPU state, assuming that all hardware is just powered off).
8036
8037 <h3>Snapshot branches</h3>
8038
8039 Snapshots can be chained. Chained snapshots form a branch where
8040 every next snapshot is based on the previous one. This chaining is
8041 mostly related to hard disk branching (see <link to="IHardDisk"/>
8042 description). This means that every time a new snapshot is created,
8043 a new differencing hard disk is implicitly created for all normal
8044 hard disks attached to the given virtual machine. This allows to
8045 fully restore hard disk contents when the machine is later reverted
8046 to a particular snapshot.
8047
8048 In the current implementation, multiple snapshot branches within one
8049 virtual machine are not allowed. Every machine has a single branch,
8050 and <link to="IConsole::takeSnapshot"/> operation adds a new
8051 snapshot to the top of that branch.
8052
8053 Existing snapshots can be discarded using
8054 <link to="IConsole::discardSnapshot"/>.
8055
8056 <h3>Current snapshot</h3>
8057
8058 Every virtual machine has a current snapshot, identified by
8059 <link to="IMachine::currentSnapshot"/>. This snapshot is used as
8060 a base for the <i>current machine state</i> (see below), to the effect
8061 that all normal hard disks of the machine and its execution
8062 state are based on this snapshot.
8063
8064 In the current implementation, the current snapshot is always the
8065 last taken snapshot (i.e. the head snapshot on the branch) and it
8066 cannot be changed.
8067
8068 The current snapshot is <tt>null</tt> if the machine doesn't have
8069 snapshots at all; in this case the current machine state is just
8070 current settings of this machine plus its current execution state.
8071
8072 <h3>Current machine state</h3>
8073
8074 The current machine state is what represented by IMachine instances got
8075 directly from IVirtualBox
8076 using <link
8077 to="IVirtualBox::getMachine">getMachine()</link>, <link
8078 to="IVirtualBox::findMachine">findMachine()</link>, etc. (as opposed
8079 to instances returned by <link to="ISnapshot::machine"/>). This state
8080 is always used when the machine is <link to="IConsole::powerUp"> powered
8081 on</link>.
8082
8083 The current machine state also includes the current execution state.
8084 If the machine is being currently executed
8085 (<link to="IMachine::state"/> is <link to="MachineState_Running"/>
8086 and above), its execution state is just what's happening now.
8087 If it is powered off (<link to="MachineState_PoweredOff"/> or
8088 <link to="MachineState_Aborted"/>), it has a zero execution state.
8089 If the machine is saved (<link to="MachineState_Saved"/>), its
8090 execution state is what saved in the execution state file
8091 (<link to="IMachine::stateFilePath"/>).
8092
8093 If the machine is in the saved state, then, next time it is powered
8094 on, its execution state will be fully restored from the saved state
8095 file and the execution will continue from the point where the state
8096 was saved.
8097
8098 Similarly to snapshots, the current machine state can be discarded
8099 using <link to="IConsole::discardCurrentState"/>.
8100
8101 <h3>Taking and discarding snapshots</h3>
8102
8103 The table below briefly explains the meaning of every snapshot
8104 operation:
8105
8106 <table>
8107 <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
8108
8109 <tr><td><link to="IConsole::takeSnapshot"/></td>
8110
8111 <td>Save the current state of the virtual machine, including all
8112 settings, contents of normal hard disks and the current modifications
8113 to immutable hard disks (for online snapshots)</td>
8114
8115 <td>The current state is not changed (the machine will continue
8116 execution if it is being executed when the snapshot is
8117 taken)</td></tr>
8118
8119 <tr><td><link to="IConsole::discardSnapshot"/></td>
8120
8121 <td>Forget the state of the virtual machine stored in the snapshot:
8122 dismiss all saved settings and delete the saved execution state (for
8123 online snapshots)</td>
8124
8125 <td>Other snapshots (including child snapshots, if any) and the
8126 current state are not directly affected</td></tr>
8127
8128 <tr><td><link to="IConsole::discardCurrentState"/></td>
8129
8130 <td>Restore the current state of the virtual machine from the state
8131 stored in the current snapshot, including all settings and hard disk
8132 contents</td>
8133
8134 <td>The current state of the machine existed prior to this operation
8135 is lost</td></tr>
8136
8137 <tr><td><link to="IConsole::discardCurrentSnapshotAndState"/></td>
8138
8139 <td>Completely revert the virtual machine to the state it was in
8140 before the current snapshot has been taken</td>
8141
8142 <td>The current state, as well as the current snapshot, are
8143 lost</td></tr>
8144
8145 </table>
8146
8147 </desc>
8148
8149 <attribute name="id" type="uuid" readonly="yes">
8150 <desc>UUID of the snapshot.</desc>
8151 </attribute>
8152
8153 <attribute name="name" type="wstring">
8154 <desc>Short name of the snapshot.</desc>
8155 </attribute>
8156
8157 <attribute name="description" type="wstring">
8158 <desc>Optional description of the snapshot.</desc>
8159 </attribute>
8160
8161 <attribute name="timeStamp" type="long long" readonly="yes">
8162 <desc>
8163 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
8164 </desc>
8165 </attribute>
8166
8167 <attribute name="online" type="boolean" readonly="yes">
8168 <desc>
8169 <tt>true</tt> if this snapshot is an online snapshot and
8170 <tt>false</tt> otherwise.
8171
8172 <note>
8173 When this attribute is <tt>true</tt>, the
8174 <link to="IMachine::stateFilePath"/> attribute of the
8175 <link to="#machine"/> object associated with this snapshot
8176 will point to the saved state file. Otherwise, it will be
8177 <tt>null</tt>.
8178 </note>
8179 </desc>
8180 </attribute>
8181
8182 <attribute name="machine" type="IMachine" readonly="yes">
8183 <desc>
8184 Virtual machine this snapshot is taken on. This object
8185 stores all settings the machine had when taking this snapshot.
8186 <note>
8187 The returned machine object is immutable, i.e. no
8188 any settings can be changed.
8189 </note>
8190 </desc>
8191 </attribute>
8192
8193 <attribute name="parent" type="ISnapshot" readonly="yes">
8194 <desc>
8195 Parent snapshot (a snapshot this one is based on).
8196 <note>
8197 It's not an error to read this attribute on a snapshot
8198 that doesn't have a parent -- a null object will be
8199 returned to indicate this.
8200 </note>
8201 </desc>
8202 </attribute>
8203
8204 <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
8205 <desc>
8206 Child snapshots (all snapshots having this one as a parent).
8207 <note>
8208 In the current implementation, there can be only one
8209 child snapshot, or no children at all, meaning this is the
8210 last (head) snapshot.
8211 </note>
8212 </desc>
8213 </attribute>
8214
8215 </interface>
8216
8217
8218 <!--
8219 // IMedia
8220 /////////////////////////////////////////////////////////////////////////
8221 -->
8222
8223 <enum
8224 name="MediaState"
8225 uuid="8b86e03c-2f1c-412a-8fbd-326f62701200"
8226 >
8227 <desc>
8228 Virtual media state.
8229 <see>IMedia</see>
8230 </desc>
8231
8232 <const name="NotCreated" value="0">
8233 <desc>
8234 Associated media storage does not exist (either was not created yet or
8235 was deleted).
8236 </desc>
8237 </const>
8238 <const name="Created" value="1">
8239 <desc>
8240 Associated storage exists and accessible.
8241 </desc>
8242 </const>
8243 <const name="LockedRead" value="2">
8244 <desc>
8245 Media is locked for reading, no data modification is possible.
8246 </desc>
8247 </const>
8248 <const name="LockedWrite" value="3">
8249 <desc>
8250 Media is locked for writing, no concurrent data reading or modification
8251 is possible.
8252 </desc>
8253 </const>
8254 <const name="Inaccessible" value="4">
8255 <desc>
8256 Associated media storage is not accessible.
8257 </desc>
8258 </const>
8259 <const name="Creating" value="5">
8260 <desc>
8261 Associated media storage is being created.
8262 </desc>
8263 </const>
8264 <const name="Deleting" value="6">
8265 <desc>
8266 Associated media storage is being deleted.
8267 </desc>
8268 </const>
8269 </enum>
8270
8271 <interface
8272 name="IMedium" extends="$unknown"
8273 uuid="a7fb3bfb-c180-4274-bae4-7fbc89046e13"
8274 wsmap="managed"
8275 >
8276 <desc>
8277 The IMedium interface is a common interface for all objects representing
8278 virtual media such as hard disks, CD/DVD images and floppy images.
8279
8280 Each medium is associated with a storage unit (such as a file on the host
8281 computer or a network resource) that holds actual data. The location of
8282 the storage unit is represented by the #location attribute. The value of
8283 this attribute is media type dependent.
8284
8285 The exact media type may be determined by querying the appropriate
8286 interface such as:
8287 <ul>
8288 <li>IHardDisk (virtual hard disks)</li>
8289 <li>IDVDImage (standard CD/DVD ISO image files)</li>
8290 <li>IFloppyImage (raw floppy image files)</li>
8291 </ul>
8292
8293 Existing media are opened using the following methods, depending on the
8294 media type:
8295 <ul>
8296 <li><link to="IVirtualBox::openHardDisk"/></li>
8297 <li><link to="IVirtualBox::openDVDImage"/></li>
8298 <li><link to="IVirtualBox::openFloppyImage"/></li>
8299 </ul>
8300
8301 New hard disk media are created using the
8302 <link to="IVirtualBox::createHardDisk"/> method. CD/DVD and floppy
8303 images are created outside VirtualBox, usually by storing a copy
8304 of the real medium of the corresponding type in a regular file.
8305
8306 <h3>Known Media</h3>
8307
8308 When an existing medium gets opened for the first time, it gets
8309 automatically remembered by the given VirtualBox installation or, in other
8310 words, becomes a <i>known medium</i>. Known media are stored in the media
8311 registry transparently maintained by VirtualBox and stored in settings
8312 files so that this registry is preserved when VirtualBox is not running.
8313
8314 Newly created virtual hard disks get remembered only when the associated
8315 storage unit is actually created (see IHardDisk for more details).
8316
8317 All known media can be enumerated using
8318 <link to="IVirtualBox::hardDisks"/>,
8319 <link to="IVirtualBox::DVDImages"/> and
8320 <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
8321 quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
8322 and similar methods or by location using
8323 <link to="IVirtualBox::findHardDisk"/> and similar methods.
8324
8325 Only known media can be attached to virtual machines.
8326
8327 Removing known media from the media registry is performed when the given
8328 medium is closed using the <link to="#close"/> method or when its
8329 associated storage unit is deleted (only for hard disks).
8330
8331 <h3>Accessibility Checks</h3>
8332
8333 The given medium (with the created storage unit) is considered to be
8334 <i>accessible</i> when its storage unit can be read.
8335 Accessible media are indicated by the <link to="MediaState_Created"/>
8336 value of the <link to="#state"/> attribute. When the storage unit cannot
8337 be read (for example, because it is located on a disconnected network
8338 resource, or was accidentally deleted outside VirtualBox), the medium is
8339 considered to be <i>inaccessible</i> which is indicated by the
8340 <link to="MediaState_Inaccessible"/> state. The details about the reason
8341 of being inaccessible can be obtained using the
8342 <link to="#lastAccessError"/> attribute.
8343
8344 A new accessibility check is performed each time the <link to="#state"/>
8345 attribute is read. Please note that this check may take long time (several
8346 seconds or even minutes, depending on the storage unit location and
8347 format), and will block the calling thread until finished. For this
8348 reason, it is recommended to never read this attribute on the main UI
8349 thread to avoid making the UI unresponsive.
8350
8351 Note that when VirtualBox starts up (e.g. the VirtualBox object gets
8352 created for the first time), all known media are in the
8353 <link to="MediaState_Inaccessible"/> state but the value of the <link
8354 to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
8355 accessibility check is made on startup. This is done to make the
8356 VirtualBox object ready for serving requests as
8357 fast as possible and let the end-user application decide if it needs to
8358 check media accessibility right away or not.
8359 </desc>
8360
8361 <attribute name="id" type="uuid" readonly="yes">
8362 <desc>
8363 UUID of the medium. For a newly created medium, this value is a randomly
8364 generated UUID.
8365
8366 <note>
8367 For media in one of MediaState_NotCreated, MediaState_Creating or
8368 MediaState_Deleting states, the value of this property is undefined
8369 and will most likely be an empty UUID.
8370 </note>
8371 </desc>
8372 </attribute>
8373
8374 <attribute name="description" type="wstring">
8375 <desc>
8376 Optional description of the medium. For newly created media, the value
8377 of this attribute value is <tt>null</tt>.
8378
8379 Media types that don't support this attribute will return E_NOTIMPL in
8380 attempt to get or set this attribute's value.
8381
8382 <note>
8383 For some storage types, reading this attribute may return an outdated
8384 (last known) value when <link to="#state"/> is <link
8385 to="MediaState_Inaccessible"/> or <link
8386 to="MediaState_LockedWrite"/> because the value of this attribute is
8387 stored within the storage unit itself. Also note that changing the
8388 attribute value is not possible in such case, as well as when the
8389 medium is the <link to="MediaState_LockedRead"/> state.
8390 </note>
8391 </desc>
8392 </attribute>
8393
8394 <attribute name="state" type="MediaState" readonly="yes">
8395 <desc>
8396 Current media state. Inspect <link to="MediaState"/> values for details.
8397
8398 Reading this attribute may take a long time because an accessibility
8399 check of the storage unit is performed each time the attribute is read.
8400 This check may cause a significant delay if the storage unit of the
8401 given medium is, for example, a file located on a network share which is
8402 not currently accessible due to connectivity problems -- the call will
8403 not return until a timeout interval defined by the host OS for this
8404 operation expires.
8405
8406 If the last known state of the medium is <link to="MediaState_Created"/>
8407 and the accessibility check fails then the state would be set to
8408 <link to="MediaState_Inaccessible"/> and <link to="#lastAccessError"/>
8409 may be used to get more details about the failure. If the state of the
8410 medium is <link to="MediaState_LockedRead"/> or
8411 <link to="MediaState_LockedWrite"/> then it remains the same, and a
8412 non-null value of <link to="#lastAccessError"/> will indicate a failed
8413 accessibility check in this case.
8414
8415 Note that not all media states are applicable to all media types.
8416 For example, states <link to="MediaState_NotCreated"/>,
8417 <link to="MediaState_LockedWrite"/>, <link to="MediaState_Creating"/>,
8418 <link to="MediaState_Deleting"/> are meaningless for IDVDImage and
8419 IFloppyImage media.
8420 </desc>
8421 </attribute>
8422
8423 <attribute name="location" type="wstring">
8424 <desc>
8425 Location of the storage unit holding media data.
8426
8427 The format of the location string is media type specific. For media
8428 types using regular files in a host's file system, the location
8429 string is the full file name.
8430
8431 Some media types may support changing the storage unit location by
8432 simply changing the value of this property. If this operation is not
8433 supported, the implementation will return E_NOTIMPL in attempt to set
8434 this attribute's value.
8435
8436 When setting a value of the location attribute which is a regular file
8437 in the host's file system, the given file name may be either relative to
8438 the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
8439 absolute. Note that if the given location specification does not contain
8440 the file extension part then a proper default extension will be
8441 automatically appended by the implementation depending on the media type.
8442 </desc>
8443 </attribute>
8444
8445 <attribute name="name" type="wstring" readonly="yes">
8446 <desc>
8447 Name of the storage unit holding media data.
8448
8449 The returned string is a short version of the <link to="#location"/>
8450 attribute that is suitable for representing the medium in situations
8451 where the full location specification is too long (such as lists
8452 and comboboxes in GUI frontends). This string is also used by frontends
8453 to sort the media list alphabetically when needed.
8454
8455 For example, for locations that are regular files in the host's file
8456 system, the value of this attribute is just the file name (+ extension),
8457 without the path specification.
8458
8459 Note that as opposed to the <link to="#location"/> attribute, the name
8460 attribute will not necessary be unique for a list of media of the
8461 given type and format.
8462 </desc>
8463 </attribute>
8464
8465 <attribute name="size" type="unsigned long long" readonly="yes">
8466 <desc>
8467 Physical size of the storage unit used to hold media data (in bytes).
8468
8469 <note>
8470 For media whose <link to="#state"/> is <link
8471 to="MediaState_Inaccessible"/>, the value of this property is the
8472 last known size. For <link to="MediaState_NotCreated"/> media,
8473 the returned value is zero.
8474 </note>
8475 </desc>
8476 </attribute>
8477
8478 <attribute name="lastAccessError" type="wstring" readonly="yes">
8479 <desc>
8480 Text message that represents the result of the last accessibility
8481 check.
8482
8483 Accessibility checks are performed each time the <link to="#state"/>
8484 attribute is read. A @c null string is returned if the last
8485 accessibility check was successful. A non-null string indicates a
8486 failure and should normally describe a reason of the failure (for
8487 example, a file read error).
8488 </desc>
8489 </attribute>
8490
8491 <attribute name="machineIds" type="uuid" safearray="yes" readonly="yes">
8492 <desc>
8493 Array of UUIDs of all machines this medium is attached to.
8494
8495 A <tt>null</tt> array is returned if this medium is not attached to any
8496 machine or to any machine's snapshot.
8497
8498 <note>
8499 The returned array will include a machine even if this medium is not
8500 attached to that machine in the current state but attached to it in
8501 one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
8502 details.
8503 </note>
8504 </desc>
8505 </attribute>
8506
8507 <method name="getSnapshotIds">
8508 <desc>
8509 Returns an array of UUIDs of all snapshots of the given machine where
8510 this medium is attached to.
8511
8512 If the medium is attached to the machine in the current state, then the
8513 first element in the array will always be the ID of the queried machine
8514 (i.e. the value equal to the @c machineId argument), followed by
8515 snapshot IDs (if any).
8516
8517 If the medium is not attached to the machine in the current state, then
8518 the array will contain only snapshot IDs.
8519
8520 The returned array may be <tt>null</tt> if this medium is not attached
8521 to the given machine at all, neither in the current state nor in one of
8522 the snapshots.
8523 </desc>
8524 <param name="machineId" type="uuid" dir="in">
8525 <desc>
8526 UUID of the machine to query.
8527 </desc>
8528 </param>
8529 <param name="snapshotIds" type="uuid" safearray="yes" dir="return">
8530 <desc>
8531 Array of snapshot UUIDs of the given machine using this medium.
8532 </desc>
8533 </param>
8534 </method>
8535
8536 <method name="lockRead">
8537 <desc>
8538 Locks this medium for reading.
8539
8540 The read lock is shared: many clients can simultaneously lock the
8541 same media for reading unless it is already locked for writing (see
8542 <link to="#lockWrite"/>) in which case an error is returned.
8543
8544 When the medium is locked for reading, it cannot be modified
8545 from within VirtualBox. This means that any method that changes
8546 the properties of this medium or contents of the storage unit
8547 will return an error (unless explicitly stated otherwise) and
8548 that an attempt to start a virtual machine that wants to modify
8549 the medium will also fail.
8550
8551 When the virtual machine is started up, it locks for reading all
8552 media it uses in read-only mode. If some media cannot be locked
8553 for reading, the startup procedure will fail.
8554
8555 The medium locked for reading must be unlocked using the <link
8556 to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
8557 can be nested and must be followed by the same number of paired
8558 <link to="#unlockRead"/> calls.
8559
8560 This method sets the media state to <link
8561 to="MediaState_LockedRead"/> on success. The state prior to
8562 this call must be <link to="MediaState_Created"/>, <link
8563 to="MediaState_Inaccessible"/> or <link
8564 to="MediaState_LockedRead"/>. As you can see, inaccessible
8565 media can be locked too. This is not an error; this method
8566 performs a logical lock that prevents modifications of this
8567 media through the VirtualBox API, not a physical lock of the
8568 underlying storage unit.
8569
8570 This method returns the current state of the medium
8571 <b>before</b> the operation.
8572
8573 <result name="VBOX_E_INVALID_OBJECT_STATE">
8574 Invalid media state (e.g. not created, locked, inaccessible,
8575 creating, deleting).
8576 </result>
8577
8578 </desc>
8579 <param name="state" type="MediaState" dir="return">
8580 <desc>
8581 State of the medium after the operation.
8582 </desc>
8583 </param>
8584 </method>
8585
8586 <method name="unlockRead">
8587 <desc>
8588 Cancels the read lock previously set by <link to="#lockRead"/>.
8589
8590 For both, success and failure, this method returns the current state
8591 of the medium <b>after</b> the operation.
8592
8593 See <link to="#lockRead"/> for more details.
8594
8595 <result name="VBOX_E_INVALID_OBJECT_STATE">
8596 Medium not locked for reading.
8597 </result>
8598
8599 </desc>
8600 <param name="state" type="MediaState" dir="return">
8601 <desc>
8602 State of the medium after the operation.
8603 </desc>
8604 </param>
8605 </method>
8606
8607 <method name="lockWrite">
8608 <desc>
8609 Locks this medium for writing.
8610
8611 The write lock, as opposed to <link to="#lockRead"/>, is
8612 exclusive: there may be only one client holding a write lock
8613 and there may be no read locks while the write lock is held.
8614
8615 When the medium is locked for writing, it cannot be modified
8616 from within VirtualBox and it is not guaranteed that the values
8617 of its properties are up-to-date. Any method that changes the
8618 properties of this medium or contents of the storage unit will
8619 return an error (unless explicitly stated otherwise) and an
8620 attempt to start a virtual machine wanting to modify or to
8621 read the medium will fail.
8622
8623 When the virtual machine is started up, it locks for writing all
8624 media it uses to write data to. If any medium could not be locked
8625 for writing, the startup procedure will fail.
8626
8627 The medium locked for writing must be unlocked using the <link
8628 to="#unlockWrite"/> method. Calls to <link to="#lockWrite"/>
8629 can <b>not</b> be nested and must be followed by a<link
8630 to="#unlockWrite"/> call before the next lockWrite call.
8631
8632 This method sets the media state to <link
8633 to="MediaState_LockedWrite"/> on success. The state prior to
8634 this call must be <link to="MediaState_Created"/> or <link
8635 to="MediaState_Inaccessible"/>. As you can see, inaccessible
8636 media can be locked too. This is not an error; this method
8637 performs a logical lock preventing modifications of this
8638 media through the VirtualBox API, not a physical lock of the
8639 underlying storage unit.
8640
8641 For both, success and failure, this method returns the current
8642 state of the medium <b>before</b> the operation.
8643
8644 <result name="VBOX_E_INVALID_OBJECT_STATE">
8645 Invalid media state (e.g. not created, locked, inaccessible,
8646 creating, deleting).
8647 </result>
8648
8649 </desc>
8650 <param name="state" type="MediaState" dir="return">
8651 <desc>
8652 State of the medium after the operation.
8653 </desc>
8654 </param>
8655 </method>
8656
8657 <method name="unlockWrite">
8658 <desc>
8659 Cancels the write lock previously set by <link to="#lockWrite"/>.
8660
8661 For both, success and failure, this method returns the current
8662 state of the medium <b>after</b> the operation.
8663
8664 See <link to="#lockWrite"/> for more details.
8665
8666 <result name="VBOX_E_INVALID_OBJECT_STATE">
8667 Medium not locked for writing.
8668 </result>
8669
8670 </desc>
8671 <param name="state" type="MediaState" dir="return">
8672 <desc>
8673 State of the medium after the operation.
8674 </desc>
8675 </param>
8676 </method>
8677
8678 <method name="close">
8679 <desc>
8680 Closes this medium.
8681
8682 The hard disk must not be attached to any known virtual machine
8683 and must not have any known child hard disks, otherwise the
8684 operation will fail.
8685
8686 When the hard disk is successfully closed, it gets removed from
8687 the list of remembered hard disks, but its storage unit is not
8688 deleted. In particular, this means that this hard disk can be
8689 later opened again using the <link
8690 to="IVirtualBox::openHardDisk"/> call.
8691
8692 Note that after this method successfully returns, the given hard
8693 disk object becomes uninitialized. This means that any attempt
8694 to call any of its methods or attributes will fail with the
8695 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
8696
8697 <result name="VBOX_E_INVALID_OBJECT_STATE">
8698 Invalid media state (other than not created, created or
8699 inaccessible).
8700 </result>
8701 <result name="VBOX_E_OBJECT_IN_USE">
8702 Medium attached to virtual machine.
8703 </result>
8704 <result name="VBOX_E_FILE_ERROR">
8705 Settings file not accessible.
8706 </result>
8707 <result name="VBOX_E_XML_ERROR">
8708 Could not parse the settings file.
8709 </result>
8710
8711 </desc>
8712 </method>
8713
8714 </interface>
8715
8716
8717 <!--
8718 // IHardDisk
8719 /////////////////////////////////////////////////////////////////////////
8720 -->
8721
8722 <enum
8723 name="HardDiskType"
8724 uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
8725 >
8726 <desc>
8727 Virtual hard disk type.
8728 <see>IHardDisk</see>
8729 </desc>
8730
8731 <const name="Normal" value="0">
8732 <desc>
8733 Normal hard disk (attached directly or indirectly, preserved
8734 when taking snapshots).
8735 </desc>
8736 </const>
8737 <const name="Immutable" value="1">
8738 <desc>
8739 Immutable hard disk (attached indirectly, changes are wiped out
8740 after powering off the virtual machine).
8741 </desc>
8742 </const>
8743 <const name="Writethrough" value="2">
8744 <desc>
8745 Write through hard disk (attached directly, ignored when
8746 taking snapshots).
8747 </desc>
8748 </const>
8749 </enum>
8750
8751 <enum
8752 name="HardDiskVariant"
8753 uuid="eb7fc6b3-ae23-4c5d-a1f6-e3522dd1efb0"
8754 >
8755 <desc>
8756 Virtual hard disk image variant. More than one flag may be set.
8757 <see>IHardDisk</see>
8758 </desc>
8759
8760 <const name="Standard" value="0">
8761 <desc>
8762 No particular variant requested, results in using the backend default.
8763 </desc>
8764 </const>
8765 <const name="VmdkSplit2G" value="0x01">
8766 <desc>
8767 VMDK image split in chunks of less than 2GByte.
8768 </desc>
8769 </const>
8770 <const name="VmdkStreamOptimized" value="0x04">
8771 <desc>
8772 VMDK streamOptimized image. Special import/export format which is
8773 read-only/append-only.
8774 </desc>
8775 </const>
8776 <const name="VmdkESX" value="0x08">
8777 <desc>
8778 VMDK format variant used on ESX products.
8779 </desc>
8780 </const>
8781 <const name="Fixed" value="0x10000">
8782 <desc>
8783 Fixed image. Only allowed for base images.
8784 </desc>
8785 </const>
8786 <const name="Diff" value="0x20000">
8787 <desc>
8788 Fixed image. Only allowed for base images.
8789 </desc>
8790 </const>
8791 </enum>
8792
8793 <interface
8794 name="IHardDiskAttachment" extends="$unknown"
8795 uuid="b1dd04bb-93c0-4ad3-a9cf-82316e595836"
8796 wsmap="struct"
8797 >
8798 <desc>
8799 The IHardDiskAttachment interface represents a hard disk attachment of a
8800 virtual machine.
8801
8802 Every hard disk attachment specifies a slot of the virtual hard disk
8803 controller and a virtual hard disk attached to this slot.
8804
8805 The array of hard disk attachments is returned by
8806 <link to="IMachine::hardDiskAttachments"/>.
8807 </desc>
8808 <attribute name="hardDisk" type="IHardDisk" readonly="yes">
8809 <desc>Hard disk object associated with this attachment.</desc>
8810 </attribute>
8811
8812 <attribute name="controller" type="wstring" readonly="yes">
8813 <desc>Interface bus of this attachment.</desc>
8814 </attribute>
8815
8816 <attribute name="port" type="long" readonly="yes">
8817 <desc>Port number of this attachment.</desc>
8818 </attribute>
8819
8820 <attribute name="device" type="long" readonly="yes">
8821 <desc>Device slot number of this attachment.</desc>
8822 </attribute>
8823
8824 </interface>
8825
8826 <interface
8827 name="IHardDisk" extends="IMedium"
8828 uuid="91648dc6-bb19-46bf-9e1c-4bf5b960c8e2"
8829 wsmap="managed"
8830 >
8831 <desc>
8832 The IHardDisk interface represents a virtual hard disk drive
8833 used by a virtual machine. This is a subclass of <link to="IMedium" />; see remarks there.
8834
8835 Virtual hard disk objects virtualize the hard disk hardware and look like
8836 regular hard disks for the guest OS running inside the virtual machine.
8837
8838 <h3>Hard Disk Types</h3>
8839
8840 There are three types of hard disks:
8841 <link to="HardDiskType_Normal">Normal</link>,
8842 <link to="HardDiskType_Immutable">Immutable</link> and
8843 <link to="HardDiskType_Writethrough">Writethrough</link>. The type of the
8844 hard disk defines how the hard disk is attached to a virtual machine and
8845 what happens when a <link to="ISnapshot">snapshot</link> of the virtual
8846 machine with the attached hard disk is taken. The type of the hard disk is
8847 defined by the <link to="#type"/> attribute.
8848
8849 All hard disks can be also divided in two big groups: <i>base</i> hard
8850 disks and <i>differencing</i> hard disks. A base hard disk contains all
8851 sectors of the hard disk data in its storage unit and therefore can be
8852 used independently. On the contrary, a differencing hard disk contains
8853 only some part of the hard disk data (a subset of sectors) and needs
8854 another hard disk to get access to the missing sectors of data. This
8855 another hard disk is called a <i>parent</i> hard disk and defines a hard
8856 disk to which this differencing hard disk is known to be <i>linked to</i>.
8857 The parent hard disk may be itself a differencing hard disk. This
8858 way, differencing hard disks form a linked hard disk chain. This chain
8859 always ends with the base hard disk which is sometimes referred to as the
8860 root hard disk of this chain. Note that several differencing hard disks
8861 may be linked to the same parent hard disk. This way, all known hard disks
8862 form a hard disk tree which is based on their parent-child relationship.
8863
8864 Differencing hard disks can be distinguished from base hard disks by
8865 querying the <link to="#parent"/> attribute: base hard disks do not have
8866 parents they would depend on, so the value of this attribute is always
8867 <tt>null</tt> for them. Using this attribute, it is possible to walk up
8868 the hard disk tree (from the child hard disk to its parent). It is also
8869 possible to walk down the tree using the <link to="#children"/>
8870 attribute.
8871
8872 Note that the type of all differencing hard disks is
8873 <link to="HardDiskType_Normal">Normal</link>; all other values are
8874 meaningless for them. Base hard disks may be of any type.
8875
8876 <h3>Creating Hard Disks</h3>
8877
8878 New base hard disks are created using
8879 <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
8880 opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
8881 disks are usually implicitly created by VirtualBox when needed but may
8882 also be created explicitly using <link to="#createDiffStorage"/>.
8883
8884 After the hard disk is successfully created (including the storage unit)
8885 or opened, it becomes a known hard disk (remembered in the internal media
8886 registry). Known hard disks can be attached to a virtual machine, accessed
8887 through <link to="IVirtualBox::getHardDisk"/> and
8888 <link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
8889 <link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
8890
8891 The following methods, besides <link to="IMedium::close"/>,
8892 automatically remove the hard disk from the media registry:
8893 <ul>
8894 <li><link to="#deleteStorage"/></li>
8895 <li><link to="#mergeTo"/></li>
8896 </ul>
8897
8898 If the storage unit of the hard disk is a regular file in the host's
8899 file system then the rules stated in the description of the
8900 <link to="IMedium::location"/> attribute apply when setting its value. In
8901 addition, a plain file name without any path may be given, in which case
8902 the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
8903 folder</link> will be prepended to it.
8904
8905 <h4>Automatic composition of the file name part</h4>
8906
8907 Another extension to the <link to="IMedium::location"/> attribute is that
8908 there is a possibility to cause VirtualBox to compose a unique value for
8909 the file name part of the location using the UUID of the hard disk. This
8910 applies only to hard disks in <link to="MediaState_NotCreated"/> state,
8911 e.g. before the storage unit is created, and works as follows. You set the
8912 value of the <link to="IMedium::location"/> attribute to a location
8913 specification which only contains the path specification but not the file
8914 name part and ends with either a forward slash or a backslash character.
8915 In response, VirtualBox will generate a new UUID for the hard disk and
8916 compose the file name using the following pattern:
8917 <pre>
8918 &lt;path&gt;/{&lt;uuid&gt;}.&lt;ext&gt;
8919 </pre>
8920 where <tt>&lt;path&gt;</tt> is the supplied path specification,
8921 <tt>&lt;uuid&gt;</tt> is the newly generated UUID and <tt>&lt;ext&gt;</tt>
8922 is the default extension for the storage format of this hard disk. After
8923 that, you may call any of the methods that create a new hard disk storage
8924 unit and they will use the generated UUID and file name.
8925
8926 <h3>Attaching Hard Disks</h3>
8927
8928 Hard disks are attached to virtual machines using the
8929 <link to="IMachine::attachHardDisk"/> method and detached using the
8930 <link to="IMachine::detachHardDisk"/> method. Depending on their
8931 <link to="#type"/>, hard disks are attached either
8932 <i>directly</i> or <i>indirectly</i>.
8933
8934 When a hard disk is being attached directly, it is associated with the
8935 virtual machine and used for hard disk operations when the machine is
8936 running. When a hard disk is being attached indirectly, a new differencing
8937 hard disk linked to it is implicitly created and this differencing hard
8938 disk is associated with the machine and used for hard disk operations.
8939 This also means that if <link to="IMachine::attachHardDisk"/> performs
8940 a direct attachment then the same hard disk will be returned in response
8941 to the subsequent <link to="IMachine::getHardDisk"/> call; however if
8942 an indirect attachment is performed then
8943 <link to="IMachine::getHardDisk"/> will return the implicitly created
8944 differencing hard disk, not the original one passed to <link
8945 to="IMachine::attachHardDisk"/>. The following table shows the
8946 dependency of the attachment type on the hard disk type:
8947
8948 <table>
8949 <tr>
8950 <th>Hard Disk Type</th>
8951 <th>Direct or Indirect?</th>
8952 </tr>
8953 <tr>
8954 <td>Normal (Base)</td>
8955 <td>
8956 Normal base hard disks that do not have children (i.e. differencing
8957 hard disks linked to them) and that are not already attached to
8958 virtual machines in snapshots are attached <b>directly</b>.
8959 Otherwise, they are attached <b>indirectly</b> because having
8960 dependent children or being part of the snapshot makes it impossible
8961 to modify hard disk contents without breaking the integrity of the
8962 dependent party. The <link to="#readOnly"/> attribute allows to
8963 quickly determine the kind of the attachment for the given hard
8964 disk. Note that if a normal base hard disk is to be indirectly
8965 attached to a virtual machine with snapshots then a special
8966 procedure called <i>smart attachment</i> is performed (see below).
8967 </td>
8968 </tr>
8969 <tr>
8970 <td>Normal (Differencing)</td>
8971 <td>
8972 Differencing hard disks are like normal base hard disks: attached
8973 <b>directly</b> if they do not have children and are not attached to
8974 virtual machines in snapshots, and <b>indirectly</b> otherwise. Note
8975 that the smart attachment procedure is never performed for
8976 differencing hard disks.
8977 </td>
8978 </tr>
8979 <tr>
8980 <td>Immutable</td>
8981 <td>
8982 Immutable hard disks are always attached <b>indirectly</b> because
8983 they are designed to be non-writable. If an immutable hard disk is
8984 attached to a virtual machine with snapshots then a special
8985 procedure called smart attachment is performed (see below).
8986 </td>
8987 </tr>
8988 <tr>
8989 <td>Writethrough</td>
8990 <td>
8991 Writethrough hard disks are always attached <b>directly</b>, also as
8992 designed. This also means that writethrough hard disks cannot have
8993 other hard disks linked to them at all.
8994 </td>
8995 </tr>
8996 </table>
8997
8998 Note that the same hard disk, regardless of its type, may be attached to
8999 more than one virtual machine at a time. In this case, the machine that is
9000 started first gains exclusive access to the hard disk and attempts to
9001 start other machines having this hard disk attached will fail until the
9002 first machine is powered down.
9003
9004 Detaching hard disks is performed in a <i>deferred</i> fashion. This means
9005 that the given hard disk remains associated with the given machine after a
9006 successful <link to="IMachine::detachHardDisk"/> call until
9007 <link to="IMachine::saveSettings"/> is called to save all changes to
9008 machine settings to disk. This deferring is necessary to guarantee that
9009 the hard disk configuration may be restored at any time by a call to
9010 <link to="IMachine::discardSettings"/> before the settings
9011 are saved (committed).
9012
9013 Note that if <link to="IMachine::discardSettings"/> is called after
9014 indirectly attaching some hard disks to the machine but before a call to
9015 <link to="IMachine::saveSettings"/> is made, it will implicitly delete
9016 all differencing hard disks implicitly created by
9017 <link to="IMachine::attachHardDisk"/> for these indirect attachments.
9018 Such implicitly created hard disks will also be immediately deleted when
9019 detached explicitly using the <link to="IMachine::detachHardDisk"/>
9020 call if it is made before <link to="IMachine::saveSettings"/>. This
9021 implicit deletion is safe because newly created differencing hard
9022 disks do not contain any user data.
9023
9024 However, keep in mind that detaching differencing hard disks that were
9025 implicitly created by <link to="IMachine::attachHardDisk"/>
9026 before the last <link to="IMachine::saveSettings"/> call will
9027 <b>not</b> implicitly delete them as they may already contain some data
9028 (for example, as a result of virtual machine execution). If these hard
9029 disks are no more necessary, the caller can always delete them explicitly
9030 using <link to="#deleteStorage"/> after they are actually de-associated
9031 from this machine by the <link to="IMachine::saveSettings"/> call.
9032
9033 <h3>Smart Attachment</h3>
9034
9035 When normal base or immutable hard disks are indirectly attached to a
9036 virtual machine then some additional steps are performed to make sure the
9037 virtual machine will have the most recent "view" of the hard disk being
9038 attached. These steps include walking through the machine's snapshots
9039 starting from the current one and going through ancestors up to the first
9040 snapshot. Hard disks attached to the virtual machine in all
9041 of the encountered snapshots are checked whether they are descendants of
9042 the given normal base or immutable hard disk. The first found child (which
9043 is the differencing hard disk) will be used instead of the normal base or
9044 immutable hard disk as a parent for creating a new differencing hard disk
9045 that will be actually attached to the machine. And only if no descendants
9046 are found or if the virtual machine does not have any snapshots then the
9047 normal base or immutable hard disk will be used itself as a parent for
9048 this differencing hard disk.
9049
9050 It is easier to explain what smart attachment does using the
9051 following example:
9052 <pre>
9053BEFORE attaching B.vdi: AFTER attaching B.vdi:
9054
9055Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
9056 Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
9057 Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
9058 Snapshot 4 (none) Snapshot 4 (none)
9059 CurState (none) CurState (D3->D2.vdi)
9060
9061 NOT
9062 ...
9063 CurState (D3->B.vdi)
9064 </pre>
9065 The first column is the virtual machine configuration before the base hard
9066 disk <tt>B.vdi</tt> is attached, the second column shows the machine after
9067 this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
9068 mean that the hard disk that is actually attached to the machine is a
9069 differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
9070 another hard disk, <tt>B.vdi</tt>.
9071
9072 As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
9073 from the machine before taking Snapshot 4. Later, after Snapshot 4 was
9074 taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
9075 dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
9076 it cannot be attached directly and needs an indirect attachment (i.e.
9077 implicit creation of a new differencing hard disk). Due to the smart
9078 attachment procedure, the new differencing hard disk
9079 (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
9080 <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
9081 <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
9082 machine.
9083
9084 Note that if there is more than one descendant hard disk of the given base
9085 hard disk found in a snapshot, and there is an exact device, channel and
9086 bus match, then this exact match will be used. Otherwise, the youngest
9087 descendant will be picked up.
9088
9089 There is one more important aspect of the smart attachment procedure which
9090 is not related to snapshots at all. Before walking through the snapshots
9091 as described above, the backup copy of the current list of hard disk
9092 attachment is searched for descendants. This backup copy is created when
9093 the hard disk configuration is changed for the first time after the last
9094 <link to="IMachine::saveSettings"/> call and used by
9095 <link to="IMachine::discardSettings"/> to undo the recent hard disk
9096 changes. When such a descendant is found in this backup copy, it will be
9097 simply re-attached back, without creating a new differencing hard disk for
9098 it. This optimization is necessary to make it possible to re-attach the
9099 base or immutable hard disk to a different bus, channel or device slot
9100 without losing the contents of the differencing hard disk actually
9101 attached to the machine in place of it.
9102 </desc>
9103
9104 <attribute name="format" type="wstring" readonly="yes">
9105 <desc>
9106 Storage format of this hard disk.
9107
9108 The value of this attribute is a string that specifies a backend used to
9109 store hard disk data. The storage format is defined when you create a
9110 new hard disk or automatically detected when you open an existing hard
9111 disk medium, and cannot be changed later.
9112
9113 The list of all storage formats supported by this VirtualBox
9114 installation can be obtained using
9115 <link to="ISystemProperties::hardDiskFormats"/>.
9116 </desc>
9117 </attribute>
9118
9119 <attribute name="type" type="HardDiskType">
9120 <desc>
9121 Type (role) of this hard disk.
9122
9123 The following constraints apply when changing the value of this
9124 attribute:
9125 <ul>
9126 <li>If a hard disk is attached to a virtual machine (either in the
9127 current state or in one of the snapshots), its type cannot be
9128 changed.
9129 </li>
9130 <li>As long as the hard disk has children, its type cannot be set
9131 to <link to="HardDiskType_Writethrough"/>.
9132 </li>
9133 <li>The type of all differencing hard disks is
9134 <link to="HardDiskType_Normal"/> and cannot be changed.
9135 </li>
9136 </ul>
9137
9138 The type of a newly created or opened hard disk is set to
9139 <link to="HardDiskType_Normal"/>.
9140 </desc>
9141 </attribute>
9142
9143 <attribute name="parent" type="IHardDisk" readonly="yes">
9144 <desc>
9145 Parent of this hard disk (a hard disk this hard disk is directly based
9146 on).
9147
9148 Only differencing hard disks have parents. For base (non-differencing)
9149 hard disks, <tt>null</tt> is returned.
9150 </desc>
9151 </attribute>
9152
9153 <attribute name="children" type="IHardDisk" safearray="yes" readonly="yes">
9154 <desc>
9155 Children of this hard disk (all differencing hard disks directly based
9156 on this hard disk). A <tt>null</tt> array is returned if this hard disk
9157 does not have any children.
9158 </desc>
9159 </attribute>
9160
9161 <attribute name="root" type="IHardDisk" readonly="yes">
9162 <desc>
9163 Root hard disk of this hard disk.
9164
9165 If this is a differencing hard disk, its root hard disk is the base hard
9166 disk the given hard disk branch starts from. For all other types of hard
9167 disks, this property returns the hard disk object itself (i.e. the same
9168 object this property is read on).
9169 </desc>
9170 </attribute>
9171
9172 <attribute name="readOnly" type="boolean" readonly="yes">
9173 <desc>
9174 Returns <tt>true</tt> if this hard disk is read-only and <tt>false</tt>
9175 otherwise.
9176
9177 A hard disk is considered to be read-only when its contents cannot be
9178 modified without breaking the integrity of other parties that depend on
9179 this hard disk such as its child hard disks or snapshots of virtual
9180 machines where this hard disk is attached to these machines. If there
9181 are no children and no such snapshots then there is no dependency and
9182 the hard disk is not read-only.
9183
9184 The value of this attribute can be used to determine the kind of the
9185 attachment that will take place when attaching this hard disk to a
9186 virtual machine. If the value is <tt>false</tt> then the hard disk will
9187 be attached directly. If the value is <tt>true</tt> then the hard disk
9188 will be attached indirectly by creating a new differencing child hard
9189 disk for that. See the interface description for more information.
9190
9191 Note that all <link to="HardDiskType_Immutable">Immutable</link> hard
9192 disks are always read-only while all
9193 <link to="HardDiskType_Writethrough">Writethrough</link> hard disks are
9194 always not.
9195
9196 <note>
9197 The read-only condition represented by this attribute is related to
9198 the hard disk type and usage, not to the current
9199 <link to="IMedium::state">media state</link> and not to the read-only
9200 state of the storage unit.
9201 </note>
9202 </desc>
9203 </attribute>
9204
9205 <attribute name="logicalSize" type="unsigned long long" readonly="yes">
9206 <desc>
9207 Logical size of this hard disk (in megabytes), as reported to the
9208 guest OS running inside the virtual machine this disk is
9209 attached to. The logical size is defined when the hard disk is created
9210 and cannot be changed later.
9211
9212 <note>
9213 Reading this property on a differencing hard disk will return the size
9214 of its <link to="#root"/> hard disk.
9215 </note>
9216 <note>
9217 For hard disks whose state is <link to="#state"/> is <link
9218 to="MediaState_Inaccessible"/>, the value of this property is the
9219 last known logical size. For <link to="MediaState_NotCreated"/> hard
9220 disks, the returned value is zero.
9221 </note>
9222 </desc>
9223 </attribute>
9224
9225 <attribute name="autoReset" type="boolean">
9226 <desc>
9227 Whether this differencing hard disk will be automatically reset each
9228 time a virtual machine it is attached to is powered up.
9229
9230 See <link to="#reset()"/> for more information about resetting
9231 differencing hard disks.
9232
9233 <note>
9234 Reading this property on a base (non-differencing) hard disk will
9235 always <tt>false</tt>. Changing the value of this property in this
9236 case is not supported.
9237 </note>
9238
9239 <result name="VBOX_E_NOT_SUPPORTED">
9240 This is not a differencing hard disk (when changing the attribute
9241 value).
9242 </result>
9243 </desc>
9244 </attribute>
9245
9246 <!-- storage methods -->
9247
9248 <method name="getProperty">
9249 <desc>
9250 Returns the value of the custom hard disk property with the given name.
9251
9252 The list of all properties supported by the given hard disk format can
9253 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9254
9255 Note that if this method returns a <tt>null</tt> @a value, the requested
9256 property is supported but currently not assigned any value.
9257
9258 <result name="VBOX_E_OBJECT_NOT_FOUND">
9259 Requested property does not exist (not supported by the format).
9260 </result>
9261 <result name="E_INVALIDARG">@a name is NULL or empty.</result>
9262 </desc>
9263 <param name="name" type="wstring" dir="in">
9264 <desc>Name of the property to get.</desc>
9265 </param>
9266 <param name="value" type="wstring" dir="return">
9267 <desc>Current property value.</desc>
9268 </param>
9269 </method>
9270
9271 <method name="setProperty">
9272 <desc>
9273 Sets the value of the custom hard disk property with the given name.
9274
9275 The list of all properties supported by the given hard disk format can
9276 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9277
9278 Note that setting the property value to <tt>null</tt> is equivalent to
9279 deleting the existing value. A default value (if it is defined for this
9280 property) will be used by the format backend in this case.
9281
9282 <result name="VBOX_E_OBJECT_NOT_FOUND">
9283 Requested property does not exist (not supported by the format).
9284 </result>
9285 <result name="E_INVALIDARG">@a name is NULL or empty.</result>
9286 </desc>
9287 <param name="name" type="wstring" dir="in">
9288 <desc>Name of the property to set.</desc>
9289 </param>
9290 <param name="value" type="wstring" dir="in">
9291 <desc>Property value to set.</desc>
9292 </param>
9293 </method>
9294
9295 <method name="getProperties">
9296 <desc>
9297 Returns values for a group of properties in one call.
9298
9299 The names of the properties to get are specified using the @a names
9300 argument which is a list of comma-separated property names or
9301 <tt>null</tt> if all properties are to be returned. Note that currently
9302 the value of this argument is ignored and the method always returns all
9303 existing properties.
9304
9305 The list of all properties supported by the given hard disk format can
9306 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9307
9308 The method returns two arrays, the array of property names corresponding
9309 to the @a names argument and the current values of these properties.
9310 Both arrays have the same number of elements with each elemend at the
9311 given index in the first array corresponds to an element at the same
9312 index in the second array.
9313
9314 Note that for properties that do not have assigned values,
9315 <tt>null</tt> is returned at the appropriate index in the
9316 @a returnValues array.
9317
9318 </desc>
9319 <param name="names" type="wstring" dir="in">
9320 <desc>
9321 Names of properties to get.
9322 </desc>
9323 </param>
9324 <param name="returnNames" type="wstring" safearray="yes" dir="out">
9325 <desc>Names of returned properties.</desc>
9326 </param>
9327 <param name="returnValues" type="wstring" safearray="yes" dir="return">
9328 <desc>Values of returned properties.</desc>
9329 </param>
9330 </method>
9331
9332 <method name="setProperties">
9333 <desc>
9334 Sets values for a group of properties in one call.
9335
9336 The names of the properties to set are passed in the @a names
9337 array along with the new values for them in the @a values array. Both
9338 arrays have the same number of elements with each elemend at the given
9339 index in the first array corresponding to an element at the same index
9340 in the second array.
9341
9342 If there is at least one property name in @a names that is not valid,
9343 the method will fail before changing the values of any other properties
9344 from the @a names array.
9345
9346 Using this method over <link to="#setProperty"/> is preferred if you
9347 need to set several properties at once since it will result into less
9348 IPC calls.
9349
9350 The list of all properties supported by the given hard disk format can
9351 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9352
9353 Note that setting the property value to <tt>null</tt> is equivalent to
9354 deleting the existing value. A default value (if it is defined for this
9355 property) will be used by the format backend in this case.
9356 </desc>
9357 <param name="names" type="wstring" safearray="yes" dir="in">
9358 <desc>Names of properties to set.</desc>
9359 </param>
9360 <param name="values" type="wstring" safearray="yes" dir="in">
9361 <desc>Values of properties to set.</desc>
9362 </param>
9363 </method>
9364
9365 <!-- storage methods -->
9366
9367 <method name="createBaseStorage">
9368 <desc>
9369 Starts creating a hard disk storage unit (fixed/dynamic, according
9370 to the variant flags) in in the background. The previous storage unit
9371 created for this object, if any, must first be deleted using
9372 <link to="#deleteStorage"/>, otherwise the operation will fail.
9373
9374 Before the operation starts, the hard disk is placed in
9375 <link to="MediaState_Creating"/> state. If the create operation
9376 fails, the media will be placed back in <link to="MediaState_NotCreated"/>
9377 state.
9378
9379 After the returned progress object reports that the operation has
9380 successfully completed, the media state will be set to <link
9381 to="MediaState_Created"/>, the hard disk will be remembered by this
9382 VirtualBox installation and may be attached to virtual machines.
9383
9384 <result name="VBOX_E_NOT_SUPPORTED">
9385 The variant of storage creation operation is not supported. See <link
9386 to="IHardDiskFormat::capabilities"/>.
9387 </result>
9388 </desc>
9389 <param name="logicalSize" type="unsigned long long" dir="in">
9390 <desc>Maximum logical size of the hard disk in megabytes.</desc>
9391 </param>
9392 <param name="variant" type="HardDiskVariant" dir="in">
9393 <desc>Exact image variant which should be created.</desc>
9394 </param>
9395 <param name="progress" type="IProgress" dir="return">
9396 <desc>Progress object to track the operation completion.</desc>
9397 </param>
9398 </method>
9399
9400 <method name="deleteStorage">
9401 <desc>
9402 Starts deleting the storage unit of this hard disk.
9403
9404 The hard disk must not be attached to any known virtual machine and must
9405 not have any known child hard disks, otherwise the operation will fail.
9406 It will also fail if there is no storage unit to delete or if deletion
9407 is already in progress, or if the hard disk is being in use (locked for
9408 read or for write) or inaccessible. Therefore, the only valid state for
9409 this operation to succeed is <link to="MediaState_Created"/>.
9410
9411 Before the operation starts, the hard disk is placed to
9412 <link to="MediaState_Deleting"/> state and gets removed from the list
9413 of remembered hard disks (media registry). If the delete operation
9414 fails, the media will be remembered again and placed back to
9415 <link to="MediaState_Created"/> state.
9416
9417 After the returned progress object reports that the operation is
9418 complete, the media state will be set to
9419 <link to="MediaState_NotCreated"/> and you will be able to use one of
9420 the storage creation methods to create it again.
9421
9422 <see>#close()</see>
9423
9424 <result name="VBOX_E_OBJECT_IN_USE">
9425 Hard disk is attached to a virtual machine.
9426 </result>
9427 <result name="VBOX_E_NOT_SUPPORTED">
9428 Storage deletion is not allowed because neither of storage creation
9429 operations are supported. See
9430 <link to="IHardDiskFormat::capabilities"/>.
9431 </result>
9432
9433 <note>
9434 If the deletion operation fails, it is not guaranteed that the storage
9435 unit still exists. You may check the <link to="IMedium::state"/> value
9436 to answer this question.
9437 </note>
9438 </desc>
9439 <param name="progress" type="IProgress" dir="return">
9440 <desc>Progress object to track the operation completion.</desc>
9441 </param>
9442 </method>
9443
9444 <!-- diff methods -->
9445
9446 <method name="createDiffStorage">
9447 <desc>
9448 Starts creating an empty differencing storage unit based on this hard
9449 disk in the format and at the location defined by the @a target
9450 argument.
9451
9452 The target hard disk must be in <link to="MediaState_NotCreated"/>
9453 state (i.e. must not have an existing storage unit). Upon successful
9454 completion, this operation will set the type of the target hard disk to
9455 <link to="HardDiskType_Normal"/> and create a storage unit necessary to
9456 represent the differencing hard disk data in the given format (according
9457 to the storage format of the target object).
9458
9459 After the returned progress object reports that the operation is
9460 successfully complete, the target hard disk gets remembered by this
9461 VirtualBox installation and may be attached to virtual machines.
9462
9463 <note>
9464 The hard disk will be set to <link to="MediaState_LockedRead"/>
9465 state for the duration of this operation.
9466 </note>
9467 <result name="VBOX_E_OBJECT_IN_USE">
9468 Hard disk not in NotCreated state.
9469 </result>
9470 </desc>
9471 <param name="target" type="IHardDisk" dir="in">
9472 <desc>Target hard disk.</desc>
9473 </param>
9474 <param name="variant" type="HardDiskVariant" dir="in">
9475 <desc>Exact image variant which should be created.</desc>
9476 </param>
9477 <param name="progress" type="IProgress" dir="return">
9478 <desc>Progress object to track the operation completion.</desc>
9479 </param>
9480 </method>
9481
9482 <method name="mergeTo">
9483 <desc>
9484 Starts merging the contents of this hard disk and all intermediate
9485 differencing hard disks in the chain to the given target hard disk.
9486
9487 The target hard disk must be either a descendant of this hard disk or
9488 its ancestor (otherwise this method will immediately return a failure).
9489 It follows that there are two logical directions of the merge operation:
9490 from ancestor to descendant (<i>forward merge</i>) and from descendant to
9491 ancestor (<i>backward merge</i>). Let us consider the following hard disk
9492 chain:
9493
9494 <pre>Base &lt;- Diff_1 &lt;- Diff_2</pre>
9495
9496 Here, calling this method on the <tt>Base</tt> hard disk object with
9497 <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
9498 <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
9499 merge. Note that in both cases the contents of the resulting hard disk
9500 will be the same, the only difference is the hard disk object that takes
9501 the result of the merge operation. In case of the forward merge in the
9502 above example, the result will be written to <tt>Diff_2</tt>; in case of
9503 the backward merge, the result will be written to <tt>Base</tt>. In
9504 other words, the result of the operation is always stored in the target
9505 hard disk.
9506
9507 Upon successful operation completion, the storage units of all hard
9508 disks in the chain between this (source) hard disk and the target hard
9509 disk, including the source hard disk itself, will be automatically
9510 deleted and the relevant hard disk objects (including this hard disk)
9511 will become uninitialized. This means that any attempt to call any of
9512 their methods or attributes will fail with the
9513 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
9514 example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
9515 delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
9516 disks. Note that <tt>Diff_2</tt> in this case will become a base hard
9517 disk itself since it will no longer be based on any other hard disk.
9518
9519 Considering the above, all of the following conditions must be met in
9520 order for the merge operation to succeed:
9521 <ul>
9522 <li>
9523 Neither this (source) hard disk nor any intermediate
9524 differencing hard disk in the chain between it and the target
9525 hard disk is attached to any virtual machine.
9526 </li>
9527 <li>
9528 Neither the source hard disk nor the target hard disk is an
9529 <link to="HardDiskType_Immutable"/> hard disk.
9530 </li>
9531 <li>
9532 The part of the hard disk tree from the source hard disk to the
9533 target hard disk is a linear chain, i.e. all hard disks in this
9534 chain have exactly one child which is the next hard disk in this
9535 chain. The only exception from this rule is the target hard disk in
9536 the forward merge operation; it is allowed to have any number of
9537 child hard disks because the merge operation will hot change its
9538 logical contents (as it is seen by the guest OS or by children).
9539 </li>
9540 <li>
9541 None of the involved hard disks are in
9542 <link to="MediaState_LockedRead"/> or
9543 <link to="MediaState_LockedWrite"/> state.
9544 </li>
9545 </ul>
9546
9547 <note>
9548 This (source) hard disk and all intermediates will be placed to <link
9549 to="MediaState_Deleting"/> state and the target hard disk will be
9550 placed to <link to="MediaState_LockedWrite"/> state and for the
9551 duration of this operation.
9552 </note>
9553 </desc>
9554 <param name="targetId" type="uuid" dir="in">
9555 <desc>UUID of the target ancestor or descendant hard disk.</desc>
9556 </param>
9557 <param name="progress" type="IProgress" dir="return">
9558 <desc>Progress object to track the operation completion.</desc>
9559 </param>
9560 </method>
9561
9562 <!-- clone method -->
9563
9564 <method name="cloneTo">
9565 <desc>
9566 Starts creating a clone of this hard disk in the format and at the
9567 location defined by the @a target argument.
9568
9569 The target hard disk must be in <link to="MediaState_NotCreated"/>
9570 state (i.e. must not have an existing storage unit). Upon successful
9571 completion, the cloned hard disk will contain exactly the same sector
9572 data as the hard disk being cloned, except that a new UUID for the
9573 clone will be randomly generated.
9574
9575 The @a parent argument defines which hard disk will be the parent
9576 of the clone. Passing a NULL reference indicates that the clone will
9577 be a base image, i.e. completely independent. It is possible to specify
9578 an arbitrary hard disk for this parameter, including the parent of the
9579 hard disk which is being cloned. Even cloning to a child of the source
9580 hard disk is possible.
9581
9582 After the returned progress object reports that the operation is
9583 successfully complete, the target hard disk gets remembered by this
9584 VirtualBox installation and may be attached to virtual machines.
9585
9586 <note>
9587 This hard disk will be placed to <link to="MediaState_LockedRead"/>
9588 state for the duration of this operation.
9589 </note>
9590 </desc>
9591 <param name="target" type="IHardDisk" dir="in">
9592 <desc>Target hard disk.</desc>
9593 </param>
9594 <param name="variant" type="HardDiskVariant" dir="in">
9595 <desc>Exact image variant which should be created.</desc>
9596 </param>
9597 <param name="parent" type="IHardDisk" dir="in">
9598 <desc>Parent of the cloned hard disk.</desc>
9599 </param>
9600 <param name="progress" type="IProgress" dir="return">
9601 <desc>Progress object to track the operation completion.</desc>
9602 </param>
9603 </method>
9604
9605 <!-- other methods -->
9606
9607 <method name="compact">
9608 <desc>
9609 Starts compacting of this hard disk. This means that the disk is
9610 transformed into a possibly more compact storage representation.
9611 This potentially creates temporary images, which can require a
9612 substantial amount of additional disk space.
9613
9614 This hard disk will be placed to <link to="MediaState_LockedWrite"/>
9615 state and all its parent hard disks (if any) will be placed to
9616 <link to="MediaState_LockedRead"/> state for the duration of this
9617 operation.
9618
9619 <result name="VBOX_E_NOT_SUPPORTED">
9620 Hard disk format does not support compacting (but potentially
9621 needs it).
9622 </result>
9623 </desc>
9624 <param name="progress" type="IProgress" dir="return">
9625 <desc>Progress object to track the operation completion.</desc>
9626 </param>
9627 </method>
9628
9629 <method name="reset">
9630 <desc>
9631 Starts erasing the contents of this differencing hard disk.
9632
9633 This operation will reset the differencing hard disk to its initial
9634 state when it does not contain any sector data and any read operation is
9635 redirected to its parent hard disk.
9636
9637 This hard disk will be placed to <link to="MediaState_LockedWrite"/>
9638 for the duration of this operation.
9639
9640 <result name="VBOX_E_NOT_SUPPORTED">
9641 This is not a differencing hard disk.
9642 </result>
9643 <result name="VBOX_E_INVALID_OBJECT_STATE">
9644 Hard disk is not in <link to="MediaState_Created"/> or
9645 <link to="MediaState_Inaccessible"/> state.
9646 </result>
9647 </desc>
9648 <param name="progress" type="IProgress" dir="return">
9649 <desc>Progress object to track the operation completion.</desc>
9650 </param>
9651 </method>
9652
9653 </interface>
9654
9655
9656 <!--
9657 // IHardDiskFormat
9658 /////////////////////////////////////////////////////////////////////////
9659 -->
9660
9661 <enum
9662 name="DataType"
9663 uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
9664 >
9665 <const name="Int32" value="0"/>
9666 <const name="Int8" value="1"/>
9667 <const name="String" value="2"/>
9668 </enum>
9669
9670 <enum
9671 name="DataFlags"
9672 uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
9673 >
9674 <const name="None" value="0x00"/>
9675 <const name="Mandatory" value="0x01"/>
9676 <const name="Expert" value="0x02"/>
9677 <const name="Array" value="0x04"/>
9678 <const name="FlagMask" value="0x07"/>
9679 </enum>
9680
9681 <enum
9682 name="HardDiskFormatCapabilities"
9683 uuid="1df1e4aa-d25a-4ba6-b2a2-02f60eb5903b"
9684 >
9685 <desc>
9686 Hard disk format capability flags.
9687 </desc>
9688
9689 <const name="Uuid" value="0x01">
9690 <desc>
9691 Supports UUIDs as expected by VirtualBox code.
9692 </desc>
9693 </const>
9694
9695 <const name="CreateFixed" value="0x02">
9696 <desc>
9697 Supports creating fixed size images, allocating all space instantly.
9698 </desc>
9699 </const>
9700
9701 <const name="CreateDynamic" value="0x04">
9702 <desc>
9703 Supports creating dynamically growing images, allocating space on
9704 demand.
9705 </desc>
9706 </const>
9707
9708 <const name="CreateSplit2G" value="0x08">
9709 <desc>
9710 Supports creating images split in chunks of a bit less than 2 GBytes.
9711 </desc>
9712 </const>
9713
9714 <const name="Differencing" value="0x10">
9715 <desc>
9716 Supports being used as a format for differencing hard disks (see <link
9717 to="IHardDisk::createDiffStorage"/>).
9718 </desc>
9719 </const>
9720
9721 <const name="Asynchronous" value="0x20">
9722 <desc>
9723 Supports asynchronous I/O operations for at least some configurations.
9724 </desc>
9725 </const>
9726
9727 <const name="File" value="0x40">
9728 <desc>
9729 The format backend operates on files (the <link to="IMedium::location"/>
9730 attribute of the hard disk specifies a file used to store hard disk
9731 data; for a list of supported file extensions see
9732 <link to="IHardDiskFormat::fileExtensions"/>).
9733 </desc>
9734 </const>
9735
9736 <const name="Properties" value="0x80">
9737 <desc>
9738 The format backend uses the property interface to configure the storage
9739 location and properties (the <link to="IHardDiskFormat::describeProperties"/>
9740 method is used to get access to properties supported by the given hard
9741 disk format).
9742 </desc>
9743 </const>
9744
9745 <const name="CapabilityMask" value="0xFF"/>
9746 </enum>
9747
9748 <interface
9749 name="IHardDiskFormat" extends="$unknown"
9750 uuid="7f3ba790-3a0b-4a8a-bac2-bb50150123c5"
9751 wsmap="managed"
9752 >
9753 <desc>
9754 The IHardDiskFormat interface represents a virtual hard disk format.
9755
9756 Each hard disk format has an associated backend which is used to handle
9757 hard disks stored in this format. This interface provides information
9758 about the properties of the associated backend.
9759
9760 Each hard disk format is identified by a string represented by the
9761 <link to="#id"/> attribute. This string is used in calls like
9762 <link to="IVirtualBox::createHardDisk"/> to specify the desired
9763 format.
9764
9765 The list of all supported hard disk formats can be obtained using
9766 <link to="ISystemProperties::hardDiskFormats"/>.
9767
9768 <see>IHardDisk</see>
9769 </desc>
9770
9771 <attribute name="id" type="wstring" readonly="yes">
9772 <desc>
9773 Identifier of this format.
9774
9775 The format identifier is a non-null non-empty ASCII string. Note that
9776 this string is case-insensitive. This means that, for example, all of
9777 the following strings:
9778 <pre>
9779 "VDI"
9780 "vdi"
9781 "VdI"</pre>
9782 refer to the same hard disk format.
9783
9784 This string is used in methods of other interfaces where it is necessary
9785 to specify a hard disk format, such as
9786 <link to="IVirtualBox::createHardDisk"/>.
9787 </desc>
9788 </attribute>
9789
9790 <attribute name="name" type="wstring" readonly="yes">
9791 <desc>
9792 Human readable description of this format.
9793
9794 Mainly for use in file open dialogs.
9795 </desc>
9796 </attribute>
9797
9798 <attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
9799 <desc>
9800 Array of strings containing the supported file extensions.
9801
9802 The first extension in the array is the extension preferred by the
9803 backend. It is recommended to use this extension when specifying a
9804 location of the storage unit for a new hard disk.
9805
9806 Note that some backends do not work on files, so this array may be
9807 empty.
9808
9809 <see>IHardDiskFormat::capabilities</see>
9810 </desc>
9811 </attribute>
9812
9813 <attribute name="capabilities" type="unsigned long" readonly="yes">
9814 <desc>
9815 Capabilities of the format as a set of bit flags.
9816
9817 For the meaning of individual capability flags see
9818 <link to="HardDiskFormatCapabilities"/>.
9819 </desc>
9820 </attribute>
9821
9822 <method name="describeProperties">
9823 <desc>
9824 Returns several arrays describing the properties supported by this
9825 format.
9826
9827 An element with the given index in each array describes one
9828 property. Thus, the number of elements in each returned array is the
9829 same and corresponds to the number of supported properties.
9830
9831 The returned arrays are filled in only if the
9832 <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
9833 All arguments must be non-NULL.
9834
9835 <see>DataType</see>
9836 <see>DataFlags</see>
9837 </desc>
9838
9839 <param name="names" type="wstring" safearray="yes" dir="out">
9840 <desc>Array of property names.</desc>
9841 </param>
9842 <param name="description" type="wstring" safearray="yes" dir="out">
9843 <desc>Array of property descriptions.</desc>
9844 </param>
9845 <param name="types" type="DataType" safearray="yes" dir="out">
9846 <desc>Array of property types.</desc>
9847 </param>
9848 <param name="flags" type="unsigned long" safearray="yes" dir="out">
9849 <desc>Array of property flags.</desc>
9850 </param>
9851 <param name="defaults" type="wstring" safearray="yes" dir="out">
9852 <desc>Array of default property values.</desc>
9853 </param>
9854 </method>
9855
9856 </interface>
9857
9858
9859 <!--
9860 // IFloppyImage
9861 /////////////////////////////////////////////////////////////////////////
9862 -->
9863
9864 <interface
9865 name="IFloppyImage" extends="IMedium"
9866 uuid="faa6101f-078c-4b3a-ab75-75670c8170b3"
9867 wsmap="managed"
9868 >
9869 <desc>
9870 The IFloppyImage interface represents a medium containing the image
9871 of a floppy disk. This is a subclass of <link to="IMedium" />; see remarks there.
9872 </desc>
9873
9874 </interface>
9875
9876
9877 <!--
9878 // IDVDImage
9879 /////////////////////////////////////////////////////////////////////////
9880 -->
9881
9882 <interface
9883 name="IDVDImage" extends="IMedium"
9884 uuid="b1f90bbb-e8a9-4484-9af1-3638e943f763"
9885 wsmap="managed"
9886 >
9887 <desc>
9888 The IDVDImage interface represents a medium containing the image
9889 of a CD or DVD disk in the ISO format.
9890
9891 This is a subclass of <link to="IMedium" />; see remarks there.
9892 </desc>
9893
9894 </interface>
9895
9896
9897 <!--
9898 // IDVDDrive
9899 /////////////////////////////////////////////////////////////////////////
9900 -->
9901
9902 <interface
9903 name="IDVDDrive" extends="$unknown"
9904 uuid="d650ef30-be9b-4dae-b463-11d5824681a5"
9905 wsmap="managed"
9906 >
9907 <desc>
9908 The IDVDDrive interface represents the virtual CD/DVD drive of the
9909 virtual machine. An object of this type is returned by
9910 <link to="IMachine::DVDDrive"/>.
9911 </desc>
9912
9913 <attribute name="state" type="DriveState" readonly="yes">
9914 <desc>Current drive state.</desc>
9915 </attribute>
9916
9917 <attribute name="passthrough" type="boolean">
9918 <desc>
9919 When a host drive is mounted and passthrough is enabled
9920 the guest OS will be able to directly send SCSI commands to
9921 the host drive. This enables the guest OS to use CD/DVD writers
9922 but is potentially dangerous.
9923 </desc>
9924 </attribute>
9925
9926 <method name="mountImage">
9927 <desc>Mounts a CD/DVD image with the specified UUID.
9928
9929 <result name="VBOX_E_FILE_ERROR">
9930 Invalid image file location.
9931 </result>
9932 <result name="VBOX_E_OBJECT_NOT_FOUND">
9933 Could not find a CD/DVD image matching @a imageId.
9934 </result>
9935 <result name="VBOX_E_INVALID_OBJECT_STATE">
9936 Invalid media state.
9937 </result>
9938
9939 </desc>
9940 <param name="imageId" type="uuid" dir="in"/>
9941 </method>
9942
9943 <method name="captureHostDrive">
9944 <desc>Captures the specified host CD/DVD drive.</desc>
9945 <param name="drive" type="IHostDVDDrive" dir="in"/>
9946 </method>
9947
9948 <method name="unmount">
9949 <desc>Unmounts the currently mounted image or host drive.</desc>
9950 </method>
9951
9952 <method name="getImage">
9953 <desc>Returns the currently mounted CD/DVD image.</desc>
9954 <param name="image" type="IDVDImage" dir="return"/>
9955 </method>
9956
9957 <method name="getHostDrive">
9958 <desc>Returns the currently mounted host CD/DVD drive.</desc>
9959 <param name="drive" type="IHostDVDDrive" dir="return"/>
9960 </method>
9961
9962 </interface>
9963
9964
9965 <!--
9966 // IFloppyDrive
9967 /////////////////////////////////////////////////////////////////////////
9968 -->
9969
9970 <interface
9971 name="IFloppyDrive" extends="$unknown"
9972 uuid="159412cd-bab8-452e-8097-218a020825a6"
9973 wsmap="managed"
9974 >
9975 <desc>
9976 The IFloppyDrive interface represents the virtual floppy drive of the
9977 virtual machine. An object of this type is returned by
9978 <link to="IMachine::floppyDrive" />.
9979 </desc>
9980
9981 <attribute name="enabled" type="boolean">
9982 <desc>
9983 Flag whether the floppy drive is enabled. If it is disabled,
9984 the floppy drive will not be reported to the guest OS.
9985 </desc>
9986 </attribute>
9987
9988 <attribute name="state" type="DriveState" readonly="yes">
9989 <desc>Current drive state.</desc>
9990 </attribute>
9991
9992 <method name="mountImage">
9993 <desc>Mounts a floppy image with the specified UUID.
9994
9995 <result name="VBOX_E_FILE_ERROR">
9996 Invalid image file location.
9997 </result>
9998 <result name="VBOX_E_OBJECT_NOT_FOUND">
9999 Could not find a floppy image matching @a imageID.
10000 </result>
10001 <result name="VBOX_E_INVALID_OBJECT_STATE">
10002 Invalid media state.
10003 </result>
10004
10005 </desc>
10006 <param name="imageId" type="uuid" dir="in"/>
10007 </method>
10008
10009 <method name="captureHostDrive">
10010 <desc>Captures the specified host floppy drive.</desc>
10011 <param name="drive" type="IHostFloppyDrive" dir="in"/>
10012 </method>
10013
10014 <method name="unmount">
10015 <desc>Unmounts the currently mounted image or host drive.</desc>
10016 </method>
10017
10018 <method name="getImage">
10019 <desc>Returns the currently mounted floppy image.</desc>
10020 <param name="image" type="IFloppyImage" dir="return"/>
10021 </method>
10022
10023 <method name="getHostDrive">
10024 <desc>Returns the currently mounted host floppy drive.</desc>
10025 <param name="drive" type="IHostFloppyDrive" dir="return"/>
10026 </method>
10027
10028 </interface>
10029
10030
10031 <!--
10032 // IKeyboard
10033 /////////////////////////////////////////////////////////////////////////
10034 -->
10035
10036 <interface
10037 name="IKeyboard" extends="$unknown"
10038 uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
10039 wsmap="managed"
10040 >
10041 <desc>
10042 The IKeyboard interface represents the virtual machine's keyboard. Used
10043 in <link to="IConsole::keyboard"/>.
10044
10045 Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
10046 to the virtual machine.
10047
10048 </desc>
10049 <method name="putScancode">
10050 <desc>Sends a scancode to the keyboard.
10051
10052 <result name="VBOX_E_IPRT_ERROR">
10053 Could not send scan code to virtual keyboard.
10054 </result>
10055
10056 </desc>
10057 <param name="scancode" type="long" dir="in"/>
10058 </method>
10059
10060 <method name="putScancodes">
10061 <desc>Sends an array of scancodes to the keyboard.
10062
10063 <result name="VBOX_E_IPRT_ERROR">
10064 Could not send all scan codes to virtual keyboard.
10065 </result>
10066
10067 </desc>
10068 <param name="scancodes" type="long" dir="in" safearray="yes"/>
10069 <param name="codesStored" type="unsigned long" dir="return"/>
10070 </method>
10071
10072 <method name="putCAD">
10073 <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
10074 function is nothing special, it is just a convenience function
10075 calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
10076
10077 <result name="VBOX_E_IPRT_ERROR">
10078 Could not send all scan codes to virtual keyboard.
10079 </result>
10080
10081 </desc>
10082 </method>
10083
10084 </interface>
10085
10086
10087 <!--
10088 // IMouse
10089 /////////////////////////////////////////////////////////////////////////
10090 -->
10091
10092 <enum
10093 name="MouseButtonState"
10094 uuid="03131722-2EC5-4173-9794-0DACA46673EF"
10095 >
10096 <desc>
10097 Mouse button state.
10098 </desc>
10099
10100 <const name="LeftButton" value="0x01"/>
10101 <const name="RightButton" value="0x02"/>
10102 <const name="MiddleButton" value="0x04"/>
10103 <const name="WheelUp" value="0x08"/>
10104 <const name="WheelDown" value="0x10"/>
10105 <const name="MouseStateMask" value="0x1F"/>
10106 </enum>
10107
10108 <interface
10109 name="IMouse" extends="$unknown"
10110 uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
10111 wsmap="managed"
10112 >
10113 <desc>
10114 The IMouse interface represents the virtual machine's mouse. Used in
10115 <link to="IConsole::mouse"/>.
10116
10117 Through this interface, the virtual machine's virtual mouse can be
10118 controlled.
10119 </desc>
10120
10121 <attribute name="absoluteSupported" type="boolean" readonly="yes">
10122 <desc>
10123 Whether the guest OS supports absolute mouse pointer positioning
10124 or not.
10125 <note>
10126 VirtualBox Guest Tools need to be installed to the guest OS
10127 in order to enable absolute mouse positioning support.
10128 You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
10129 callback to be instantly informed about changes of this attribute
10130 during virtual machine execution.
10131 </note>
10132 <see><link to="#putMouseEventAbsolute"/></see>
10133 </desc>
10134 </attribute>
10135
10136 <method name="putMouseEvent">
10137 <desc>
10138 Initiates a mouse event using relative pointer movements
10139 along x and y axis.
10140
10141 <result name="E_ACCESSDENIED">
10142 Console not powered up.
10143 </result>
10144 <result name="VBOX_E_IPRT_ERROR">
10145 Could not send mouse event to virtual mouse.
10146 </result>
10147
10148 </desc>
10149
10150 <param name="dx" type="long" dir="in">
10151 <desc>
10152 Amount of pixels the mouse should move to the right.
10153 Negative values move the mouse to the left.
10154 </desc>
10155 </param>
10156 <param name="dy" type="long" dir="in">
10157 <desc>
10158 Amount of pixels the mouse should move downwards.
10159 Negative values move the mouse upwards.
10160 </desc>
10161 </param>
10162 <param name="dz" type="long" dir="in">
10163 <desc>
10164 Amount of mouse wheel moves.
10165 Positive values describe clockwise wheel rotations,
10166 negative values describe counterclockwise rotations.
10167 </desc>
10168 </param>
10169 <param name="buttonState" type="long" dir="in">
10170 <desc>
10171 The current state of mouse buttons. Every bit represents
10172 a mouse button as follows:
10173 <table>
10174 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10175 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10176 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10177 </table>
10178 A value of <tt>1</tt> means the corresponding button is pressed.
10179 otherwise it is released.
10180 </desc>
10181 </param>
10182 </method>
10183
10184 <method name="putMouseEventAbsolute">
10185 <desc>
10186 Positions the mouse pointer using absolute x and y coordinates.
10187 These coordinates are expressed in pixels and
10188 start from <tt>[1,1]</tt> which corresponds to the top left
10189 corner of the virtual display.
10190
10191 <result name="E_ACCESSDENIED">
10192 Console not powered up.
10193 </result>
10194 <result name="VBOX_E_IPRT_ERROR">
10195 Could not send mouse event to virtual mouse.
10196 </result>
10197
10198 <note>
10199 This method will have effect only if absolute mouse
10200 positioning is supported by the guest OS.
10201 </note>
10202
10203 <see><link to="#absoluteSupported"/></see>
10204 </desc>
10205
10206 <param name="x" type="long" dir="in">
10207 <desc>
10208 X coordinate of the pointer in pixels, starting from <tt>1</tt>.
10209 </desc>
10210 </param>
10211 <param name="y" type="long" dir="in">
10212 <desc>
10213 Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
10214 </desc>
10215 </param>
10216 <param name="dz" type="long" dir="in">
10217 <desc>
10218 Amount of mouse wheel moves.
10219 Positive values describe clockwise wheel rotations,
10220 negative values describe counterclockwise rotations.
10221 </desc>
10222 </param>
10223 <param name="buttonState" type="long" dir="in">
10224 <desc>
10225 The current state of mouse buttons. Every bit represents
10226 a mouse button as follows:
10227 <table>
10228 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10229 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10230 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10231 </table>
10232 A value of <tt>1</tt> means the corresponding button is pressed.
10233 otherwise it is released.
10234 </desc>
10235 </param>
10236 </method>
10237
10238 </interface>
10239
10240 <!--
10241 // IDisplay
10242 /////////////////////////////////////////////////////////////////////////
10243 -->
10244
10245 <enum
10246 name="FramebufferAccelerationOperation"
10247 uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
10248 >
10249 <desc>
10250 Frame buffer acceleration operation.
10251 </desc>
10252
10253 <const name="SolidFillAcceleration" value="1"/>
10254 <const name="ScreenCopyAcceleration" value="2"/>
10255 </enum>
10256
10257 <enum
10258 name="FramebufferPixelFormat"
10259 uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
10260 >
10261 <desc>
10262 Format of the video memory buffer. Constants represented by this enum can
10263 be used to test for particular values of <link
10264 to="IFramebuffer::pixelFormat"/>. See also <link
10265 to="IFramebuffer::requestResize"/>.
10266
10267 See also www.fourcc.org for more information about FOURCC pixel formats.
10268 </desc>
10269
10270 <const name="Opaque" value="0">
10271 <desc>
10272 Unknown buffer format (the user may not assume any particular format of
10273 the buffer).
10274 </desc>
10275 </const>
10276 <const name="FOURCC_RGB" value="0x32424752">
10277 <desc>
10278 Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
10279 bit layout).
10280 </desc>
10281 </const>
10282 </enum>
10283
10284 <interface
10285 name="IFramebuffer" extends="$unknown"
10286 uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
10287 wsmap="suppress"
10288 >
10289 <attribute name="address" type="octet" mod="ptr" readonly="yes">
10290 <desc>Address of the start byte of the frame buffer.</desc>
10291 </attribute>
10292
10293 <attribute name="width" type="unsigned long" readonly="yes">
10294 <desc>Frame buffer width, in pixels.</desc>
10295 </attribute>
10296
10297 <attribute name="height" type="unsigned long" readonly="yes">
10298 <desc>Frame buffer height, in pixels.</desc>
10299 </attribute>
10300
10301 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10302 <desc>
10303 Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
10304 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
10305 are: 8, 15, 16, 24 and 32.
10306 </desc>
10307 </attribute>
10308
10309 <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
10310 <desc>
10311 Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
10312 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
10313 size of the scan line must be aligned to 32 bits.
10314 </desc>
10315 </attribute>
10316
10317 <attribute name="pixelFormat" type="unsigned long" readonly="yes">
10318 <desc>
10319 Frame buffer pixel format. It's either one of the values defined by <link
10320 to="FramebufferPixelFormat"/> or a raw FOURCC code.
10321 <note>
10322 This attribute must never return <link
10323 to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
10324 <link to="#address"/> points to must be always known.
10325 </note>
10326 </desc>
10327 </attribute>
10328
10329 <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
10330 <desc>
10331 Defines whether this frame buffer uses the virtual video card's memory
10332 buffer (guest VRAM) directly or not. See <link
10333 to="IFramebuffer::requestResize"/> for more information.
10334 </desc>
10335 </attribute>
10336
10337 <attribute name="heightReduction" type="unsigned long" readonly="yes">
10338 <desc>
10339 Hint from the frame buffer about how much of the standard
10340 screen height it wants to use for itself. This information is
10341 exposed to the guest through the VESA BIOS and VMMDev interface
10342 so that it can use it for determining its video mode table. It
10343 is not guaranteed that the guest respects the value.
10344 </desc>
10345 </attribute>
10346
10347 <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
10348 <desc>
10349 An alpha-blended overlay which is superposed over the frame buffer.
10350 The initial purpose is to allow the display of icons providing
10351 information about the VM state, including disk activity, in front
10352 ends which do not have other means of doing that. The overlay is
10353 designed to controlled exclusively by IDisplay. It has no locking
10354 of its own, and any changes made to it are not guaranteed to be
10355 visible until the affected portion of IFramebuffer is updated. The
10356 overlay can be created lazily the first time it is requested. This
10357 attribute can also return NULL to signal that the overlay is not
10358 implemented.
10359 </desc>
10360 </attribute>
10361
10362 <attribute name="winId" type="unsigned long long" readonly="yes">
10363 <desc>
10364 Platform-dependent identifier of the window where context of this
10365 frame buffer is drawn, or zero if there's no such window.
10366 </desc>
10367 </attribute>
10368
10369 <method name="lock">
10370 <desc>
10371 Locks the frame buffer.
10372 Gets called by the IDisplay object where this frame buffer is
10373 bound to.
10374 </desc>
10375 </method>
10376
10377 <method name="unlock">
10378 <desc>
10379 Unlocks the frame buffer.
10380 Gets called by the IDisplay object where this frame buffer is
10381 bound to.
10382 </desc>
10383 </method>
10384
10385 <method name="notifyUpdate">
10386 <desc>
10387 Informs about an update.
10388 Gets called by the display object where this buffer is
10389 registered.
10390 </desc>
10391 <param name="x" type="unsigned long" dir="in"/>
10392 <param name="y" type="unsigned long" dir="in"/>
10393 <param name="width" type="unsigned long" dir="in"/>
10394 <param name="height" type="unsigned long" dir="in"/>
10395 <param name="finished" type="boolean" dir="return"/>
10396 </method>
10397
10398 <method name="requestResize">
10399 <desc>
10400 Requests a size and pixel format change.
10401
10402 There are two modes of working with the video buffer of the virtual
10403 machine. The <i>indirect</i> mode implies that the IFramebuffer
10404 implementation allocates a memory buffer for the requested display mode
10405 and provides it to the virtual machine. In <i>direct</i> mode, the
10406 IFramebuffer implementation uses the memory buffer allocated and owned
10407 by the virtual machine. This buffer represents the video memory of the
10408 emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
10409 usually faster because the implementation gets a raw pointer to the
10410 guest VRAM buffer which it can directly use for visualizing the contents
10411 of the virtual display, as opposed to the indirect mode where the
10412 contents of guest VRAM are copied to the memory buffer provided by
10413 the implementation every time a display update occurs.
10414
10415 It is important to note that the direct mode is really fast only when
10416 the implementation uses the given guest VRAM buffer directly, for
10417 example, by blitting it to the window representing the virtual machine's
10418 display, which saves at least one copy operation comparing to the
10419 indirect mode. However, using the guest VRAM buffer directly is not
10420 always possible: the format and the color depth of this buffer may be
10421 not supported by the target window, or it may be unknown (opaque) as in
10422 case of text or non-linear multi-plane VGA video modes. In this case,
10423 the indirect mode (that is always available) should be used as a
10424 fallback: when the guest VRAM contents are copied to the
10425 implementation-provided memory buffer, color and format conversion is
10426 done automatically by the underlying code.
10427
10428 The @a pixelFormat parameter defines whether the direct mode is
10429 available or not. If @a pixelFormat is <link
10430 to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
10431 VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
10432 @a bytesPerLine parameters must be ignored and the implementation must use
10433 the indirect mode (where it provides its own buffer in one of the
10434 supported formats). In all other cases, @a pixelFormat together with
10435 @a bitsPerPixel and @a bytesPerLine define the format of the video memory
10436 buffer pointed to by the @a VRAM parameter and the implementation is
10437 free to choose which mode to use. To indicate that this frame buffer uses
10438 the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
10439 attribute must return <tt>true</tt> and <link to="#address"/> must
10440 return exactly the same address that is passed in the @a VRAM parameter
10441 of this method; otherwise it is assumed that the indirect strategy is
10442 chosen.
10443
10444 The @a width and @a height parameters represent the size of the
10445 requested display mode in both modes. In case of indirect mode, the
10446 provided memory buffer should be big enough to store data of the given
10447 display mode. In case of direct mode, it is guaranteed that the given
10448 @a VRAM buffer contains enough space to represent the display mode of the
10449 given size. Note that this frame buffer's <link to="#width"/> and <link
10450 to="#height"/> attributes must return exactly the same values as
10451 passed to this method after the resize is completed (see below).
10452
10453 The @a finished output parameter determines if the implementation has
10454 finished resizing the frame buffer or not. If, for some reason, the
10455 resize cannot be finished immediately during this call, @a finished
10456 must be set to @c false, and the implementation must call
10457 <link to="IDisplay::resizeCompleted"/> after it has returned from
10458 this method as soon as possible. If @a finished is @c false, the
10459 machine will not call any frame buffer methods until
10460 <link to="IDisplay::resizeCompleted"/> is called.
10461
10462 Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
10463 <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
10464 this frame buffer must return exactly the same values as specified in the
10465 parameters of this method, after the resize is completed. If the
10466 indirect mode is chosen, these attributes must return values describing
10467 the format of the implementation's own memory buffer <link
10468 to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
10469 value must always correlate with <link to="#pixelFormat"/>. Note that
10470 the <link to="#pixelFormat"/> attribute must never return <link
10471 to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
10472
10473 <note>
10474 This method is called by the IDisplay object under the
10475 <link to="#lock"/> provided by this IFramebuffer
10476 implementation. If this method returns @c false in @a finished, then
10477 this lock is not released until
10478 <link to="IDisplay::resizeCompleted"/> is called.
10479 </note>
10480 </desc>
10481 <param name="screenId" type="unsigned long" dir="in">
10482 <desc>
10483 Logical screen number. Must be used in the corresponding call to
10484 <link to="IDisplay::resizeCompleted"/> if this call is made.
10485 </desc>
10486 </param>
10487 <param name="pixelFormat" type="unsigned long" dir="in">
10488 <desc>
10489 Pixel format of the memory buffer pointed to by @a VRAM.
10490 See also <link to="FramebufferPixelFormat"/>.
10491 </desc>
10492 </param>
10493 <param name="VRAM" type="octet" mod="ptr" dir="in">
10494 <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
10495 </param>
10496 <param name="bitsPerPixel" type="unsigned long" dir="in">
10497 <desc>Color depth, bits per pixel.</desc>
10498 </param>
10499 <param name="bytesPerLine" type="unsigned long" dir="in">
10500 <desc>Size of one scan line, in bytes.</desc>
10501 </param>
10502 <param name="width" type="unsigned long" dir="in">
10503 <desc>Width of the guest display, in pixels.</desc>
10504 </param>
10505 <param name="height" type="unsigned long" dir="in">
10506 <desc>Height of the guest display, in pixels.</desc>
10507 </param>
10508 <param name="finished" type="boolean" dir="return">
10509 <desc>
10510 Can the VM start using the new frame buffer immediately
10511 after this method returns or it should wait for
10512 <link to="IDisplay::resizeCompleted"/>.
10513 </desc>
10514 </param>
10515 </method>
10516
10517 <method name="operationSupported">
10518 <desc>
10519 Returns whether the given acceleration operation is supported
10520 by the IFramebuffer implementation. If not, the display object
10521 will not attempt to call the corresponding IFramebuffer entry
10522 point. Even if an operation is indicated as supported, the
10523 IFramebuffer implementation always has the option to return non
10524 supported from the corresponding acceleration method in which
10525 case the operation will be performed by the display engine. This
10526 allows for reduced IFramebuffer implementation complexity where
10527 only common cases are handled.
10528 </desc>
10529 <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
10530 <param name="supported" type="boolean" dir="return"/>
10531 </method>
10532
10533 <method name="videoModeSupported">
10534 <desc>
10535 Returns whether the frame buffer implementation is willing to
10536 support a given video mode. In case it is not able to render
10537 the video mode (or for some reason not willing), it should
10538 return false. Usually this method is called when the guest
10539 asks the VMM device whether a given video mode is supported
10540 so the information returned is directly exposed to the guest.
10541 It is important that this method returns very quickly.
10542 </desc>
10543 <param name="width" type="unsigned long" dir="in"/>
10544 <param name="height" type="unsigned long" dir="in"/>
10545 <param name="bpp" type="unsigned long" dir="in"/>
10546 <param name="supported" type="boolean" dir="return"/>
10547 </method>
10548
10549 <method name="solidFill">
10550 <desc>
10551 Fills the specified rectangle on screen with a solid color.
10552 </desc>
10553 <param name="x" type="unsigned long" dir="in"/>
10554 <param name="y" type="unsigned long" dir="in"/>
10555 <param name="width" type="unsigned long" dir="in"/>
10556 <param name="height" type="unsigned long" dir="in"/>
10557 <param name="color" type="unsigned long" dir="in"/>
10558 <param name="handled" type="boolean" dir="return"/>
10559 </method>
10560
10561 <method name="copyScreenBits">
10562 <desc>
10563 Copies specified rectangle on the screen.
10564 </desc>
10565 <param name="xDst" type="unsigned long" dir="in"/>
10566 <param name="yDst" type="unsigned long" dir="in"/>
10567 <param name="xSrc" type="unsigned long" dir="in"/>
10568 <param name="ySrc" type="unsigned long" dir="in"/>
10569 <param name="width" type="unsigned long" dir="in"/>
10570 <param name="height" type="unsigned long" dir="in"/>
10571 <param name="handled" type="boolean" dir="return"/>
10572 </method>
10573
10574 <method name="getVisibleRegion">
10575 <desc>
10576 Returns the visible region of this frame buffer.
10577
10578 If the @a rectangles parameter is <tt>NULL</tt> then the value of the
10579 @a count parameter is ignored and the number of elements necessary to
10580 describe the current visible region is returned in @a countCopied.
10581
10582 If @a rectangles is not <tt>NULL</tt> but @a count is less
10583 than the required number of elements to store region data, the method
10584 will report a failure. If @a count is equal or greater than the
10585 required number of elements, then the actual number of elements copied
10586 to the provided array will be returned in @a countCopied.
10587
10588 <note>
10589 The address of the provided array must be in the process space of
10590 this IFramebuffer object.
10591 </note>
10592 <note>
10593 Method not yet implemented.
10594 </note>
10595 </desc>
10596 <param name="rectangles" type="octet" mod="ptr" dir="in">
10597 <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
10598 </param>
10599 <param name="count" type="unsigned long" dir="in">
10600 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
10601 </param>
10602 <param name="countCopied" type="unsigned long" dir="return">
10603 <desc>Number of elements copied to the @a rectangles array.</desc>
10604 </param>
10605 </method>
10606
10607 <method name="setVisibleRegion">
10608 <desc>
10609 Suggests a new visible region to this frame buffer. This region
10610 represents the area of the VM display which is a union of regions of
10611 all top-level windows of the guest operating system running inside the
10612 VM (if the Guest Additions for this system support this
10613 functionality). This information may be used by the frontends to
10614 implement the seamless desktop integration feature.
10615
10616 <note>
10617 The address of the provided array must be in the process space of
10618 this IFramebuffer object.
10619 </note>
10620 <note>
10621 The IFramebuffer implementation must make a copy of the provided
10622 array of rectangles.
10623 </note>
10624 <note>
10625 Method not yet implemented.
10626 </note>
10627 </desc>
10628 <param name="rectangles" type="octet" mod="ptr" dir="in">
10629 <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
10630 </param>
10631 <param name="count" type="unsigned long" dir="in">
10632 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
10633 </param>
10634 </method>
10635
10636 </interface>
10637
10638 <interface
10639 name="IFramebufferOverlay" extends="IFramebuffer"
10640 uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
10641 wsmap="suppress"
10642 >
10643 <desc>
10644 The IFramebufferOverlay interface represents an alpha blended overlay
10645 for displaying status icons above an IFramebuffer. It is always created
10646 not visible, so that it must be explicitly shown. It only covers a
10647 portion of the IFramebuffer, determined by its width, height and
10648 co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
10649 that order) format, and may be written to directly. Do re-read the
10650 width though, after setting it, as it may be adjusted (increased) to
10651 make it more suitable for the front end.
10652 </desc>
10653 <attribute name="x" type="unsigned long" readonly="yes">
10654 <desc>X position of the overlay, relative to the frame buffer.</desc>
10655 </attribute>
10656
10657 <attribute name="y" type="unsigned long" readonly="yes">
10658 <desc>Y position of the overlay, relative to the frame buffer.</desc>
10659 </attribute>
10660
10661 <attribute name="visible" type="boolean" readonly="no">
10662 <desc>
10663 Whether the overlay is currently visible.
10664 </desc>
10665 </attribute>
10666
10667 <attribute name="alpha" type="unsigned long" readonly="no">
10668 <desc>
10669 The global alpha value for the overlay. This may or may not be
10670 supported by a given front end.
10671 </desc>
10672 </attribute>
10673
10674 <method name="move">
10675 <desc>
10676 Changes the overlay's position relative to the IFramebuffer.
10677 </desc>
10678 <param name="x" type="unsigned long" dir="in"/>
10679 <param name="y" type="unsigned long" dir="in"/>
10680 </method>
10681
10682 </interface>
10683
10684 <interface
10685 name="IDisplay" extends="$unknown"
10686 uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
10687 wsmap="suppress"
10688 >
10689 <desc>
10690 The IDisplay interface represents the virtual machine's display.
10691
10692 The object implementing this interface is contained in each
10693 <link to="IConsole::display"/> attribute and represents the visual
10694 output of the virtual machine.
10695
10696 The virtual display supports pluggable output targets represented by the
10697 IFramebuffer interface. Examples of the output target are a window on
10698 the host computer or an RDP session's display on a remote computer.
10699 </desc>
10700 <attribute name="width" type="unsigned long" readonly="yes">
10701 <desc>Current display width.</desc>
10702 </attribute>
10703
10704 <attribute name="height" type="unsigned long" readonly="yes">
10705 <desc>Current display height.</desc>
10706 </attribute>
10707
10708 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10709 <desc>
10710 Current guest display color depth. Note that this may differ
10711 from <link to="IFramebuffer::bitsPerPixel"/>.
10712 </desc>
10713 </attribute>
10714
10715 <method name="setupInternalFramebuffer">
10716 <desc>
10717 Prepares an internally managed frame buffer.
10718 </desc>
10719 <param name="depth" type="unsigned long" dir="in"/>
10720 </method>
10721
10722 <method name="lockFramebuffer">
10723 <desc>
10724 Requests access to the internal frame buffer.
10725
10726 <result name="VBOX_E_NOT_SUPPORTED">
10727 Attempt to lock a non-internal frame buffer.
10728 </result>
10729
10730 </desc>
10731 <param name="address" type="octet" mod="ptr" dir="return"/>
10732 </method>
10733
10734 <method name="unlockFramebuffer">
10735 <desc>
10736 Releases access to the internal frame buffer.
10737
10738 <result name="VBOX_E_NOT_SUPPORTED">
10739 Attempt to unlock a non-internal frame buffer.
10740 </result>
10741
10742 </desc>
10743 </method>
10744
10745 <method name="registerExternalFramebuffer">
10746 <desc>
10747 Registers an external frame buffer.
10748 </desc>
10749 <param name="framebuffer" type="IFramebuffer" dir="in"/>
10750 </method>
10751
10752 <method name="setFramebuffer">
10753 <desc>
10754 Sets the framebuffer for given screen.
10755 </desc>
10756 <param name="screenId" type="unsigned long" dir="in"/>
10757 <param name="framebuffer" type="IFramebuffer" dir="in"/>
10758 </method>
10759
10760 <method name="getFramebuffer">
10761 <desc>
10762 Queries the framebuffer for given screen.
10763 </desc>
10764 <param name="screenId" type="unsigned long" dir="in"/>
10765 <param name="framebuffer" type="IFramebuffer" dir="out"/>
10766 <param name="xOrigin" type="long" dir="out"/>
10767 <param name="yOrigin" type="long" dir="out"/>
10768 </method>
10769
10770 <method name="setVideoModeHint">
10771 <desc>
10772 Asks VirtualBox to request the given video mode from
10773 the guest. This is just a hint and it cannot be guaranteed
10774 that the requested resolution will be used. Guest Additions
10775 are required for the request to be seen by guests. The caller
10776 should issue the request and wait for a resolution change and
10777 after a timeout retry.
10778
10779 Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
10780 parameters means that the corresponding values should be taken from the
10781 current video mode (i.e. left unchanged).
10782
10783 If the guest OS supports multi-monitor configuration then the @a display
10784 parameter specifies the number of the guest display to send the hint to:
10785 <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
10786 so on. If the multi-monitor configuration is not supported, @a display
10787 must be <tt>0</tt>.
10788
10789 <result name="E_INVALIDARG">
10790 The @a display is not associated with any monitor.
10791 </result>
10792
10793 </desc>
10794 <param name="width" type="unsigned long" dir="in"/>
10795 <param name="height" type="unsigned long" dir="in"/>
10796 <param name="bitsPerPixel" type="unsigned long" dir="in"/>
10797 <param name="display" type="unsigned long" dir="in"/>
10798 </method>
10799
10800 <method name="setSeamlessMode">
10801 <desc>
10802 Enables or disables seamless guest display rendering (seamless desktop
10803 integration) mode.
10804 <note>
10805 Calling this method has no effect if <link
10806 to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
10807 </note>
10808 </desc>
10809 <param name="enabled" type="boolean" dir="in"/>
10810 </method>
10811
10812 <method name="takeScreenShot">
10813 <desc>
10814 Takes a screen shot of the requested size and copies it to the
10815 32-bpp buffer allocated by the caller.
10816
10817 <result name="E_NOTIMPL">
10818 Feature not implemented.
10819 </result>
10820 <result name="VBOX_E_IPRT_ERROR">
10821 Could not take a screenshot.
10822 </result>
10823
10824 </desc>
10825 <param name="address" type="octet" mod="ptr" dir="in"/>
10826 <param name="width" type="unsigned long" dir="in"/>
10827 <param name="height" type="unsigned long" dir="in"/>
10828 </method>
10829
10830 <method name="drawToScreen">
10831 <desc>
10832 Draws a 32-bpp image of the specified size from the given buffer
10833 to the given point on the VM display.
10834
10835 <result name="E_NOTIMPL">
10836 Feature not implemented.
10837 </result>
10838 <result name="VBOX_E_IPRT_ERROR">
10839 Could not draw to screen.
10840 </result>
10841
10842 </desc>
10843 <param name="address" type="octet" mod="ptr" dir="in"/>
10844 <param name="x" type="unsigned long" dir="in"/>
10845 <param name="y" type="unsigned long" dir="in"/>
10846 <param name="width" type="unsigned long" dir="in"/>
10847 <param name="height" type="unsigned long" dir="in"/>
10848 </method>
10849
10850 <method name="invalidateAndUpdate">
10851 <desc>
10852 Does a full invalidation of the VM display and instructs the VM
10853 to update it.
10854
10855 <result name="VBOX_E_IPRT_ERROR">
10856 Could not invalidate and update screen.
10857 </result>
10858
10859 </desc>
10860 </method>
10861
10862 <method name="resizeCompleted">
10863 <desc>
10864 Signals that a framebuffer has completed the resize operation.
10865
10866 <result name="VBOX_E_NOT_SUPPORTED">
10867 Operation only valid for external frame buffers.
10868 </result>
10869
10870 </desc>
10871 <param name="screenId" type="unsigned long" dir="in"/>
10872 </method>
10873
10874 <method name="updateCompleted">
10875 <desc>
10876 Signals that a framebuffer has completed the update operation.
10877
10878 <result name="VBOX_E_NOT_SUPPORTED">
10879 Operation only valid for external frame buffers.
10880 </result>
10881
10882 </desc>
10883 </method>
10884
10885 </interface>
10886
10887 <!--
10888 // INetworkAdapter
10889 /////////////////////////////////////////////////////////////////////////
10890 -->
10891
10892 <enum
10893 name="NetworkAttachmentType"
10894 uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
10895 >
10896 <desc>
10897 Network attachment type.
10898 </desc>
10899
10900 <const name="Null" value="0">
10901 <desc>Null value, also means "not attached".</desc>
10902 </const>
10903 <const name="NAT" value="1"/>
10904 <const name="Bridged" value="2"/>
10905 <const name="Internal" value="3"/>
10906 <const name="HostOnly" value="4"/>
10907 </enum>
10908
10909 <enum
10910 name="NetworkAdapterType"
10911 uuid="50c3dfd8-07ac-4a31-baac-519c828fbf97"
10912 >
10913 <desc>
10914 Network adapter type.
10915 </desc>
10916
10917 <const name="Null" value="0">
10918 <desc>Null value (never used by the API).</desc>
10919 </const>
10920 <const name="Am79C970A" value="1">
10921 <desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
10922 </const>
10923 <const name="Am79C973" value="2">
10924 <desc>AMD PCNet-FAST III network card (Am79C973).</desc>
10925 </const>
10926 <const name="I82540EM" value="3">
10927 <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
10928 </const>
10929 <const name="I82543GC" value="4">
10930 <desc>Intel PRO/1000 T Server network card (82543GC).</desc>
10931 </const>
10932 <const name="I82545EM" value="5">
10933 <desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
10934 </const>
10935 </enum>
10936
10937 <interface
10938 name="INetworkAdapter" extends="$unknown"
10939 uuid="65607a27-2b73-4d43-b4cc-0ba2c817fbde"
10940 wsmap="managed"
10941 >
10942 <desc>
10943 Represents a virtual network adapter that is attached to a virtual machine.
10944 Each virtual machine has a fixed number of network adapter slots with one
10945 instance of this attached to each of them. Call
10946 <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
10947 is attached to a given slot in a given machine.
10948
10949 Each network adapter can be in one of five attachment modes, which are
10950 represented by the <link to="NetworkAttachmentType" /> enumeration;
10951 see the <link to="#attachmentType" /> attribute.
10952 </desc>
10953
10954 <attribute name="adapterType" type="NetworkAdapterType">
10955 <desc>
10956 Type of the virtual network adapter. Depending on this value,
10957 VirtualBox will provide a different virtual network hardware
10958 to the guest.
10959 </desc>
10960 </attribute>
10961
10962 <attribute name="slot" type="unsigned long" readonly="yes">
10963 <desc>
10964 Slot number this adapter is plugged into. Corresponds to
10965 the value you pass to <link to="IMachine::getNetworkAdapter"/>
10966 to obtain this instance.
10967 </desc>
10968 </attribute>
10969
10970 <attribute name="enabled" type="boolean">
10971 <desc>
10972 Flag whether the network adapter is present in the
10973 guest system. If disabled, the virtual guest hardware will
10974 not contain this network adapter. Can only be changed when
10975 the VM is not running.
10976 </desc>
10977 </attribute>
10978
10979 <attribute name="MACAddress" type="wstring">
10980 <desc>
10981 Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
10982 it to NULL, VirtualBox will generate a unique MAC address.
10983 </desc>
10984 </attribute>
10985
10986 <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
10987
10988 <attribute name="hostInterface" type="wstring">
10989 <desc>
10990 Name of the host network interface the VM is attached to.
10991 </desc>
10992 </attribute>
10993
10994 <attribute name="internalNetwork" type="wstring">
10995 <desc>
10996 Name of the internal network the VM is attached to.
10997 </desc>
10998 </attribute>
10999
11000 <attribute name="NATNetwork" type="wstring">
11001 <desc>
11002 Name of the NAT network the VM is attached to.
11003 </desc>
11004 </attribute>
11005
11006 <attribute name="cableConnected" type="boolean">
11007 <desc>
11008 Flag whether the adapter reports the cable as connected or not.
11009 It can be used to report offline situations to a VM.
11010 </desc>
11011 </attribute>
11012
11013 <attribute name="lineSpeed" type="unsigned long">
11014 <desc>
11015 Line speed reported by custom drivers, in units of 1 kbps.
11016 </desc>
11017 </attribute>
11018
11019 <attribute name="traceEnabled" type="boolean">
11020 <desc>
11021 Flag whether network traffic from/to the network card should be traced.
11022 Can only be toggled when the VM is turned off.
11023 </desc>
11024 </attribute>
11025
11026 <attribute name="traceFile" type="wstring">
11027 <desc>
11028 Filename where a network trace will be stored. If not set, VBox-pid.pcap
11029 will be used.
11030 </desc>
11031 </attribute>
11032
11033 <method name="attachToNAT">
11034 <desc>
11035 Attach the network adapter to the Network Address Translation (NAT) interface.
11036 </desc>
11037 </method>
11038
11039 <method name="attachToBridgedInterface">
11040 <desc>
11041 Attach the network adapter to a bridged host interface.
11042 </desc>
11043 </method>
11044
11045 <method name="attachToInternalNetwork">
11046 <desc>
11047 Attach the network adapter to an internal network.
11048 </desc>
11049 </method>
11050
11051 <method name="attachToHostOnlyInterface">
11052 <desc>
11053 Attach the network adapter to the host-only network.
11054 </desc>
11055 </method>
11056
11057 <method name="detach">
11058 <desc>
11059 Detach the network adapter
11060 </desc>
11061 </method>
11062 </interface>
11063
11064
11065 <!--
11066 // ISerialPort
11067 /////////////////////////////////////////////////////////////////////////
11068 -->
11069
11070 <enum
11071 name="PortMode"
11072 uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
11073 >
11074 <desc>
11075 The PortMode enumeration represents possible communication modes for
11076 the virtual serial port device.
11077 </desc>
11078
11079 <const name="Disconnected" value="0">
11080 <desc>Virtual device is not attached to any real host device.</desc>
11081 </const>
11082 <const name="HostPipe" value="1">
11083 <desc>Virtual device is attached to a host pipe.</desc>
11084 </const>
11085 <const name="HostDevice" value="2">
11086 <desc>Virtual device is attached to a host device.</desc>
11087 </const>
11088 </enum>
11089
11090 <interface
11091 name="ISerialPort" extends="$unknown"
11092 uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
11093 wsmap="managed"
11094 >
11095
11096 <desc>
11097 The ISerialPort interface represents the virtual serial port device.
11098
11099 The virtual serial port device acts like an ordinary serial port
11100 inside the virtual machine. This device communicates to the real
11101 serial port hardware in one of two modes: host pipe or host device.
11102
11103 In host pipe mode, the #path attribute specifies the path to the pipe on
11104 the host computer that represents a serial port. The #server attribute
11105 determines if this pipe is created by the virtual machine process at
11106 machine startup or it must already exist before starting machine
11107 execution.
11108
11109 In host device mode, the #path attribute specifies the name of the
11110 serial port device on the host computer.
11111
11112 There is also a third communication mode: the disconnected mode. In this
11113 mode, the guest OS running inside the virtual machine will be able to
11114 detect the serial port, but all port write operations will be discarded
11115 and all port read operations will return no data.
11116
11117 <see>IMachine::getSerialPort</see>
11118 </desc>
11119
11120 <attribute name="slot" type="unsigned long" readonly="yes">
11121 <desc>
11122 Slot number this serial port is plugged into. Corresponds to
11123 the value you pass to <link to="IMachine::getSerialPort"/>
11124 to obtain this instance.
11125 </desc>
11126 </attribute>
11127
11128 <attribute name="enabled" type="boolean">
11129 <desc>
11130 Flag whether the serial port is enabled. If disabled,
11131 the serial port will not be reported to the guest OS.
11132 </desc>
11133 </attribute>
11134
11135 <attribute name="IOBase" type="unsigned long">
11136 <desc>Base I/O address of the serial port.</desc>
11137 </attribute>
11138
11139 <attribute name="IRQ" type="unsigned long">
11140 <desc>IRQ number of the serial port.</desc>
11141 </attribute>
11142
11143 <attribute name="hostMode" type="PortMode">
11144 <desc>
11145 How is this port connected to the host.
11146 <note>
11147 Changing this attribute may fail if the conditions for
11148 <link to="#path"/> are not met.
11149 </note>
11150 </desc>
11151 </attribute>
11152
11153 <attribute name="server" type="boolean">
11154 <desc>
11155 Flag whether this serial port acts as a server (creates a new pipe on
11156 the host) or as a client (uses the existing pipe). This attribute is
11157 used only when <link to="#hostMode"/> is PortMode_HostPipe.
11158 </desc>
11159 </attribute>
11160
11161 <attribute name="path" type="wstring">
11162 <desc>
11163 Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
11164 PortMode_HostPipe, or the host serial device name when
11165 <link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
11166 cases, setting a @c null or empty string as the attribute's value
11167 is an error. Otherwise, the value of this property is ignored.
11168 </desc>
11169 </attribute>
11170
11171 </interface>
11172
11173 <!--
11174 // IParallelPort
11175 /////////////////////////////////////////////////////////////////////////
11176 -->
11177
11178 <interface
11179 name="IParallelPort" extends="$unknown"
11180 uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
11181 wsmap="managed"
11182 >
11183
11184 <desc>
11185 The IParallelPort interface represents the virtual parallel port device.
11186
11187 The virtual parallel port device acts like an ordinary parallel port
11188 inside the virtual machine. This device communicates to the real
11189 parallel port hardware using the name of the parallel device on the host
11190 computer specified in the #path attribute.
11191
11192 Each virtual parallel port device is assigned a base I/O address and an
11193 IRQ number that will be reported to the guest operating system and used
11194 to operate the given parallel port from within the virtual machine.
11195
11196 <see>IMachine::getParallelPort</see>
11197 </desc>
11198
11199 <attribute name="slot" type="unsigned long" readonly="yes">
11200 <desc>
11201 Slot number this parallel port is plugged into. Corresponds to
11202 the value you pass to <link to="IMachine::getParallelPort"/>
11203 to obtain this instance.
11204 </desc>
11205 </attribute>
11206
11207 <attribute name="enabled" type="boolean">
11208 <desc>
11209 Flag whether the parallel port is enabled. If disabled,
11210 the parallel port will not be reported to the guest OS.
11211 </desc>
11212 </attribute>
11213
11214 <attribute name="IOBase" type="unsigned long">
11215 <desc>Base I/O address of the parallel port.</desc>
11216 </attribute>
11217
11218 <attribute name="IRQ" type="unsigned long">
11219 <desc>IRQ number of the parallel port.</desc>
11220 </attribute>
11221
11222 <attribute name="path" type="wstring">
11223 <desc>
11224 Host parallel device name. If this parallel port is enabled, setting a
11225 @c null or an empty string as this attribute's value will result into
11226 an error.
11227 </desc>
11228 </attribute>
11229
11230 </interface>
11231
11232
11233 <!--
11234 // IMachineDebugger
11235 /////////////////////////////////////////////////////////////////////////
11236 -->
11237
11238 <interface
11239 name="IMachineDebugger" extends="$unknown"
11240 uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
11241 wsmap="suppress"
11242 >
11243 <method name="resetStats">
11244 <desc>
11245 Reset VM statistics.
11246 </desc>
11247 <param name="pattern" type="wstring" dir="in">
11248 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11249 </param>
11250 </method>
11251
11252 <method name="dumpStats">
11253 <desc>
11254 Dumps VM statistics.
11255 </desc>
11256 <param name="pattern" type="wstring" dir="in">
11257 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11258 </param>
11259 </method>
11260
11261 <method name="getStats">
11262 <desc>
11263 Get the VM statistics in a XMLish format.
11264 </desc>
11265 <param name="pattern" type="wstring" dir="in">
11266 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11267 </param>
11268 <param name="withDescriptions" type="boolean" dir="in">
11269 <desc>Whether to include the descriptions.</desc>
11270 </param>
11271 <param name="stats" type="wstring" dir="out">
11272 <desc>The XML document containing the statistics.</desc>
11273 </param>
11274 </method>
11275
11276 <method name="injectNMI">
11277 <desc>
11278 Inject an NMI into a running VT-x/AMD-V VM.
11279 </desc>
11280 </method>
11281
11282 <attribute name="singlestep" type="boolean">
11283 <desc>Switch for enabling singlestepping.</desc>
11284 </attribute>
11285
11286 <attribute name="recompileUser" type="boolean">
11287 <desc>Switch for forcing code recompilation for user mode code.</desc>
11288 </attribute>
11289
11290 <attribute name="recompileSupervisor" type="boolean">
11291 <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
11292 </attribute>
11293
11294 <attribute name="PATMEnabled" type="boolean">
11295 <desc>Switch for enabling and disabling the PATM component.</desc>
11296 </attribute>
11297
11298 <attribute name="CSAMEnabled" type="boolean">
11299 <desc>Switch for enabling and disabling the CSAM component.</desc>
11300 </attribute>
11301
11302 <attribute name="logEnabled" type="boolean">
11303 <desc>Switch for enabling and disabling logging.</desc>
11304 </attribute>
11305
11306 <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
11307 <desc>
11308 Flag indicating whether the VM is currently making use of CPU hardware
11309 virtualization extensions.
11310 </desc>
11311 </attribute>
11312
11313 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
11314 <desc>
11315 Flag indicating whether the VM is currently making use of the nested paging
11316 CPU hardware virtualization extension.
11317 </desc>
11318 </attribute>
11319
11320 <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
11321 <desc>
11322 Flag indicating whether the VM is currently making use of the VPID
11323 VT-x extension.
11324 </desc>
11325 </attribute>
11326
11327 <attribute name="PAEEnabled" type="boolean" readonly="yes">
11328 <desc>
11329 Flag indicating whether the VM is currently making use of the Physical
11330 Address Extension CPU feature.
11331 </desc>
11332 </attribute>
11333
11334 <attribute name="virtualTimeRate" type="unsigned long">
11335 <desc>
11336 The rate at which the virtual time runs expressed as a percentage.
11337 The accepted range is 2% to 20000%.
11338 </desc>
11339 </attribute>
11340
11341 <!-- @todo method for setting log flags, groups and destination! -->
11342
11343 <attribute name="VM" type="unsigned long long" readonly="yes">
11344 <desc>
11345 Gets the VM handle. This is only for internal use while
11346 we carve the details of this interface.
11347 </desc>
11348 </attribute>
11349
11350 </interface>
11351
11352 <!--
11353 // IUSBController
11354 /////////////////////////////////////////////////////////////////////////
11355 -->
11356
11357 <interface
11358 name="IUSBController" extends="$unknown"
11359 uuid="238540fa-4b73-435a-a38e-4e1d9eab5c17"
11360 wsmap="managed"
11361 >
11362 <attribute name="enabled" type="boolean">
11363 <desc>
11364 Flag whether the USB controller is present in the
11365 guest system. If disabled, the virtual guest hardware will
11366 not contain any USB controller. Can only be changed when
11367 the VM is powered off.
11368 </desc>
11369 </attribute>
11370
11371 <attribute name="enabledEhci" type="boolean">
11372 <desc>
11373 Flag whether the USB EHCI controller is present in the
11374 guest system. If disabled, the virtual guest hardware will
11375 not contain a USB EHCI controller. Can only be changed when
11376 the VM is powered off.
11377 </desc>
11378 </attribute>
11379
11380 <attribute name="USBStandard" type="unsigned short" readonly="yes">
11381 <desc>
11382 USB standard version which the controller implements.
11383 This is a BCD which means that the major version is in the
11384 high byte and minor version is in the low byte.
11385 </desc>
11386 </attribute>
11387
11388 <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
11389 <desc>
11390 List of USB device filters associated with the machine.
11391
11392 If the machine is currently running, these filters are activated
11393 every time a new (supported) USB device is attached to the host
11394 computer that was not ignored by global filters
11395 (<link to="IHost::USBDeviceFilters"/>).
11396
11397 These filters are also activated when the machine is powered up.
11398 They are run against a list of all currently available USB
11399 devices (in states
11400 <link to="USBDeviceState_Available"/>,
11401 <link to="USBDeviceState_Busy"/>,
11402 <link to="USBDeviceState_Held"/>) that were not previously
11403 ignored by global filters.
11404
11405 If at least one filter matches the USB device in question, this
11406 device is automatically captured (attached to) the virtual USB
11407 controller of this machine.
11408
11409 <see>IUSBDeviceFilter, ::IUSBController</see>
11410 </desc>
11411 </attribute>
11412
11413 <method name="createDeviceFilter">
11414 <desc>
11415 Creates a new USB device filter. All attributes except
11416 the filter name are set to <tt>null</tt> (any match),
11417 <i>active</i> is <tt>false</tt> (the filter is not active).
11418
11419 The created filter can then be added to the list of filters using
11420 <link to="#insertDeviceFilter"/>.
11421
11422 <result name="VBOX_E_INVALID_VM_STATE">
11423 The virtual machine is not mutable.
11424 </result>
11425
11426 <see>#deviceFilters</see>
11427 </desc>
11428 <param name="name" type="wstring" dir="in">
11429 <desc>
11430 Filter name. See <link to="IUSBDeviceFilter::name"/>
11431 for more info.
11432 </desc>
11433 </param>
11434 <param name="filter" type="IUSBDeviceFilter" dir="return">
11435 <desc>Created filter object.</desc>
11436 </param>
11437 </method>
11438
11439 <method name="insertDeviceFilter">
11440 <desc>
11441 Inserts the given USB device to the specified position
11442 in the list of filters.
11443
11444 Positions are numbered starting from <tt>0</tt>. If the specified
11445 position is equal to or greater than the number of elements in
11446 the list, the filter is added to the end of the collection.
11447
11448 <note>
11449 Duplicates are not allowed, so an attempt to insert a
11450 filter that is already in the collection, will return an
11451 error.
11452 </note>
11453
11454 <result name="VBOX_E_INVALID_VM_STATE">
11455 Virtual machine is not mutable.
11456 </result>
11457 <result name="E_INVALIDARG">
11458 USB device filter not created within this VirtualBox instance.
11459 </result>
11460 <result name="VBOX_E_INVALID_OBJECT_STATE">
11461 USB device filter already in list.
11462 </result>
11463
11464 <see>#deviceFilters</see>
11465 </desc>
11466 <param name="position" type="unsigned long" dir="in">
11467 <desc>Position to insert the filter to.</desc>
11468 </param>
11469 <param name="filter" type="IUSBDeviceFilter" dir="in">
11470 <desc>USB device filter to insert.</desc>
11471 </param>
11472 </method>
11473
11474 <method name="removeDeviceFilter">
11475 <desc>
11476 Removes a USB device filter from the specified position in the
11477 list of filters.
11478
11479 Positions are numbered starting from <tt>0</tt>. Specifying a
11480 position equal to or greater than the number of elements in
11481 the list will produce an error.
11482
11483 <see>#deviceFilters</see>
11484
11485 <result name="VBOX_E_INVALID_VM_STATE">
11486 Virtual machine is not mutable.
11487 </result>
11488 <result name="E_INVALIDARG">
11489 USB device filter list empty or invalid @a position.
11490 </result>
11491
11492 </desc>
11493 <param name="position" type="unsigned long" dir="in">
11494 <desc>Position to remove the filter from.</desc>
11495 </param>
11496 <param name="filter" type="IUSBDeviceFilter" dir="return">
11497 <desc>Removed USB device filter.</desc>
11498 </param>
11499 </method>
11500
11501 </interface>
11502
11503
11504 <!--
11505 // IUSBDevice
11506 /////////////////////////////////////////////////////////////////////////
11507 -->
11508
11509 <interface
11510 name="IUSBDevice" extends="$unknown"
11511 uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
11512 wsmap="managed"
11513 >
11514 <desc>
11515 The IUSBDevice interface represents a virtual USB device attached to the
11516 virtual machine.
11517
11518 A collection of objects implementing this interface is stored in the
11519 <link to="IConsole::USBDevices"/> attribute which lists all USB devices
11520 attached to a running virtual machine's USB controller.
11521 </desc>
11522
11523 <attribute name="id" type="uuid" readonly="yes">
11524 <desc>
11525 Unique USB device ID. This ID is built from #vendorId,
11526 #productId, #revision and #serialNumber.
11527 </desc>
11528 </attribute>
11529
11530 <attribute name="vendorId" type="unsigned short" readonly="yes">
11531 <desc>Vendor ID.</desc>
11532 </attribute>
11533
11534 <attribute name="productId" type="unsigned short" readonly="yes">
11535 <desc>Product ID.</desc>
11536 </attribute>
11537
11538 <attribute name="revision" type="unsigned short" readonly="yes">
11539 <desc>
11540 Product revision number. This is a packed BCD represented as
11541 unsigned short. The high byte is the integer part and the low
11542 byte is the decimal.
11543 </desc>
11544 </attribute>
11545
11546 <attribute name="manufacturer" type="wstring" readonly="yes">
11547 <desc>Manufacturer string.</desc>
11548 </attribute>
11549
11550 <attribute name="product" type="wstring" readonly="yes">
11551 <desc>Product string.</desc>
11552 </attribute>
11553
11554 <attribute name="serialNumber" type="wstring" readonly="yes">
11555 <desc>Serial number string.</desc>
11556 </attribute>
11557
11558 <attribute name="address" type="wstring" readonly="yes">
11559 <desc>Host specific address of the device.</desc>
11560 </attribute>
11561
11562 <attribute name="port" type="unsigned short" readonly="yes">
11563 <desc>
11564 Host USB port number the device is physically
11565 connected to.
11566 </desc>
11567 </attribute>
11568
11569 <attribute name="version" type="unsigned short" readonly="yes">
11570 <desc>
11571 The major USB version of the device - 1 or 2.
11572 </desc>
11573 </attribute>
11574
11575 <attribute name="portVersion" type="unsigned short" readonly="yes">
11576 <desc>
11577 The major USB version of the host USB port the device is
11578 physically connected to - 1 or 2. For devices not connected to
11579 anything this will have the same value as the version attribute.
11580 </desc>
11581 </attribute>
11582
11583 <attribute name="remote" type="boolean" readonly="yes">
11584 <desc>
11585 Whether the device is physically connected to a remote VRDP
11586 client or to a local host machine.
11587 </desc>
11588 </attribute>
11589
11590 </interface>
11591
11592
11593 <!--
11594 // IUSBDeviceFilter
11595 /////////////////////////////////////////////////////////////////////////
11596 -->
11597
11598 <interface
11599 name="IUSBDeviceFilter" extends="$unknown"
11600 uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
11601 wsmap="managed"
11602 >
11603 <desc>
11604 The IUSBDeviceFilter interface represents an USB device filter used
11605 to perform actions on a group of USB devices.
11606
11607 This type of filters is used by running virtual machines to
11608 automatically capture selected USB devices once they are physically
11609 attached to the host computer.
11610
11611 A USB device is matched to the given device filter if and only if all
11612 attributes of the device match the corresponding attributes of the
11613 filter (that is, attributes are joined together using the logical AND
11614 operation). On the other hand, all together, filters in the list of
11615 filters carry the semantics of the logical OR operation. So if it is
11616 desirable to create a match like "this vendor id OR this product id",
11617 one needs to create two filters and specify "any match" (see below)
11618 for unused attributes.
11619
11620 All filter attributes used for matching are strings. Each string
11621 is an expression representing a set of values of the corresponding
11622 device attribute, that will match the given filter. Currently, the
11623 following filtering expressions are supported:
11624
11625 <ul>
11626 <li><i>Interval filters</i>. Used to specify valid intervals for
11627 integer device attributes (Vendor ID, Product ID and Revision).
11628 The format of the string is:
11629
11630 <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
11631
11632 where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
11633 (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
11634 or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
11635 is omitted before a dash (<tt>-</tt>), the minimum possible integer
11636 is assumed; if <tt>n</tt> is omitted after a dash, the maximum
11637 possible integer is assumed.
11638 </li>
11639 <li><i>Boolean filters</i>. Used to specify acceptable values for
11640 boolean device attributes. The format of the string is:
11641
11642 <tt>true|false|yes|no|0|1</tt>
11643
11644 </li>
11645 <li><i>Exact match</i>. Used to specify a single value for the given
11646 device attribute. Any string that doesn't start with <tt>int:</tt>
11647 represents the exact match. String device attributes are compared to
11648 this string including case of symbols. Integer attributes are first
11649 converted to a string (see individual filter attributes) and then
11650 compared ignoring case.
11651
11652 </li>
11653 <li><i>Any match</i>. Any value of the corresponding device attribute
11654 will match the given filter. An empty or <tt>null</tt> string is
11655 used to construct this type of filtering expressions.
11656
11657 </li>
11658 </ul>
11659
11660 <note>
11661 On the Windows host platform, interval filters are not currently
11662 available. Also all string filter attributes
11663 (<link to="#manufacturer"/>, <link to="#product"/>,
11664 <link to="#serialNumber"/>) are ignored, so they behave as
11665 <i>any match</i> no matter what string expression is specified.
11666 </note>
11667
11668 <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
11669 </desc>
11670
11671 <attribute name="name" type="wstring">
11672 <desc>
11673 Visible name for this filter.
11674 This name is used to visually distinguish one filter from another,
11675 so it can neither be <tt>null</tt> nor an empty string.
11676 </desc>
11677 </attribute>
11678
11679 <attribute name="active" type="boolean">
11680 <desc>Whether this filter active or has been temporarily disabled.</desc>
11681 </attribute>
11682
11683 <attribute name="vendorId" type="wstring">
11684 <desc>
11685 <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
11686 The string representation for the <i>exact matching</i>
11687 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11688 (including leading zeroes).
11689 </desc>
11690 </attribute>
11691
11692 <attribute name="productId" type="wstring">
11693 <desc>
11694 <link to="IUSBDevice::productId">Product ID</link> filter.
11695 The string representation for the <i>exact matching</i>
11696 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11697 (including leading zeroes).
11698 </desc>
11699 </attribute>
11700
11701 <attribute name="revision" type="wstring">
11702 <desc>
11703 <link to="IUSBDevice::productId">Product revision number</link>
11704 filter. The string representation for the <i>exact matching</i>
11705 has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
11706 of the integer part of the revision, and <tt>F</tt> is the
11707 decimal digit of its fractional part (including leading and
11708 trailing zeros).
11709 Note that for interval filters, it's best to use the hexadecimal
11710 form, because the revision is stored as a 16 bit packed BCD value;
11711 so the expression <tt>int:0x0100-0x0199</tt> will match any
11712 revision from <tt>1.0</tt> to <tt>1.99</tt>.
11713 </desc>
11714 </attribute>
11715
11716 <attribute name="manufacturer" type="wstring">
11717 <desc>
11718 <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
11719 </desc>
11720 </attribute>
11721
11722 <attribute name="product" type="wstring">
11723 <desc>
11724 <link to="IUSBDevice::product">Product</link> filter.
11725 </desc>
11726 </attribute>
11727
11728 <attribute name="serialNumber" type="wstring">
11729 <desc>
11730 <link to="IUSBDevice::serialNumber">Serial number</link> filter.
11731 </desc>
11732 </attribute>
11733
11734 <attribute name="port" type="wstring">
11735 <desc>
11736 <link to="IUSBDevice::port">Host USB port</link> filter.
11737 </desc>
11738 </attribute>
11739
11740 <attribute name="remote" type="wstring">
11741 <desc>
11742 <link to="IUSBDevice::remote">Remote state</link> filter.
11743 <note>
11744 This filter makes sense only for machine USB filters,
11745 i.e. it is ignored by IHostUSBDeviceFilter objects.
11746 </note>
11747 </desc>
11748 </attribute>
11749
11750 <attribute name="maskedInterfaces" type="unsigned long">
11751 <desc>
11752 This is an advanced option for hiding one or more USB interfaces
11753 from the guest. The value is a bit mask where the bits that are set
11754 means the corresponding USB interface should be hidden, masked off
11755 if you like.
11756 This feature only works on Linux hosts.
11757 </desc>
11758 </attribute>
11759
11760 </interface>
11761
11762
11763 <!--
11764 // IHostUSBDevice
11765 /////////////////////////////////////////////////////////////////////////
11766 -->
11767
11768 <enum
11769 name="USBDeviceState"
11770 uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
11771 >
11772 <desc>
11773 USB device state. This enumeration represents all possible states
11774 of the USB device physically attached to the host computer regarding
11775 its state on the host computer and availability to guest computers
11776 (all currently running virtual machines).
11777
11778 Once a supported USB device is attached to the host, global USB
11779 filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
11780 either ignore the device, or put it to USBDeviceState_Held state, or do
11781 nothing. Unless the device is ignored by global filters, filters of all
11782 currently running guests (<link to="IUSBController::deviceFilters"/>) are
11783 activated that can put it to USBDeviceState_Captured state.
11784
11785 If the device was ignored by global filters, or didn't match
11786 any filters at all (including guest ones), it is handled by the host
11787 in a normal way. In this case, the device state is determined by
11788 the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
11789 or USBDeviceState_Available, depending on the current device usage.
11790
11791 Besides auto-capturing based on filters, the device can be manually
11792 captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
11793 state is USBDeviceState_Busy, USBDeviceState_Available or
11794 USBDeviceState_Held.
11795
11796 <note>
11797 Due to differences in USB stack implementations in Linux and Win32,
11798 states USBDeviceState_Busy and USBDeviceState_vailable are applicable
11799 only to the Linux version of the product. This also means that (<link
11800 to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
11801 device state is USBDeviceState_Held.
11802 </note>
11803
11804 <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
11805 </desc>
11806
11807 <const name="NotSupported" value="0">
11808 <desc>
11809 Not supported by the VirtualBox server, not available to guests.
11810 </desc>
11811 </const>
11812 <const name="Unavailable" value="1">
11813 <desc>
11814 Being used by the host computer exclusively,
11815 not available to guests.
11816 </desc>
11817 </const>
11818 <const name="Busy" value="2">
11819 <desc>
11820 Being used by the host computer, potentially available to guests.
11821 </desc>
11822 </const>
11823 <const name="Available" value="3">
11824 <desc>
11825 Not used by the host computer, available to guests (the host computer
11826 can also start using the device at any time).
11827 </desc>
11828 </const>
11829 <const name="Held" value="4">
11830 <desc>
11831 Held by the VirtualBox server (ignored by the host computer),
11832 available to guests.
11833 </desc>
11834 </const>
11835 <const name="Captured" value="5">
11836 <desc>
11837 Captured by one of the guest computers, not available
11838 to anybody else.
11839 </desc>
11840 </const>
11841 </enum>
11842
11843 <interface
11844 name="IHostUSBDevice" extends="IUSBDevice"
11845 uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
11846 wsmap="managed"
11847 >
11848 <desc>
11849 The IHostUSBDevice interface represents a physical USB device attached
11850 to the host computer.
11851
11852 Besides properties inherited from IUSBDevice, this interface adds the
11853 <link to="#state"/> property that holds the current state of the USB
11854 device.
11855
11856 <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
11857 </desc>
11858
11859 <attribute name="state" type="USBDeviceState" readonly="yes">
11860 <desc>
11861 Current state of the device.
11862 </desc>
11863 </attribute>
11864
11865 <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
11866
11867 </interface>
11868
11869
11870 <!--
11871 // IHostUSBDeviceFilter
11872 /////////////////////////////////////////////////////////////////////////
11873 -->
11874
11875 <enum
11876 name="USBDeviceFilterAction"
11877 uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
11878 >
11879 <desc>
11880 Actions for host USB device filters.
11881 <see>IHostUSBDeviceFilter, USBDeviceState</see>
11882 </desc>
11883
11884 <const name="Null" value="0">
11885 <desc>Null value (never used by the API).</desc>
11886 </const>
11887 <const name="Ignore" value="1">
11888 <desc>Ignore the matched USB device.</desc>
11889 </const>
11890 <const name="Hold" value="2">
11891 <desc>Hold the matched USB device.</desc>
11892 </const>
11893 </enum>
11894
11895 <interface
11896 name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
11897 uuid="4cc70246-d74a-400f-8222-3900489c0374"
11898 wsmap="managed"
11899 >
11900 <desc>
11901 The IHostUSBDeviceFilter interface represents a global filter for a
11902 physical USB device used by the host computer. Used indirectly in
11903 <link to="IHost::USBDeviceFilters"/>.
11904
11905 Using filters of this type, the host computer determines the initial
11906 state of the USB device after it is physically attached to the
11907 host's USB controller.
11908
11909 <note>
11910 The <link to="#remote"/> attribute is ignored by this type of
11911 filters, because it makes sense only for
11912 <link to="IUSBController::deviceFilters">machine USB filters</link>.
11913 </note>
11914
11915 <see>IHost::USBDeviceFilters</see>
11916 </desc>
11917
11918 <attribute name="action" type="USBDeviceFilterAction">
11919 <desc>
11920 Action performed by the host when an attached USB device
11921 matches this filter.
11922 </desc>
11923 </attribute>
11924
11925 </interface>
11926
11927 <!--
11928 // IAudioAdapter
11929 /////////////////////////////////////////////////////////////////////////
11930 -->
11931
11932 <enum
11933 name="AudioDriverType"
11934 uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
11935 >
11936 <desc>
11937 Host audio driver type.
11938 </desc>
11939
11940 <const name="Null" value="0">
11941 <desc>Null value, also means "dummy audio driver".</desc>
11942 </const>
11943 <const name="WinMM" value="1"/>
11944 <const name="OSS" value="2"/>
11945 <const name="ALSA" value="3"/>
11946 <const name="DirectSound" value="4"/>
11947 <const name="CoreAudio" value="5"/>
11948 <const name="MMPM" value="6"/>
11949 <const name="Pulse" value="7"/>
11950 <const name="SolAudio" value="8"/>
11951 </enum>
11952
11953 <enum
11954 name="AudioControllerType"
11955 uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
11956 >
11957 <desc>
11958 Virtual audio controller type.
11959 </desc>
11960
11961 <const name="AC97" value="0"/>
11962 <const name="SB16" value="1"/>
11963 </enum>
11964
11965 <interface
11966 name="IAudioAdapter" extends="$unknown"
11967 uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
11968 wsmap="managed"
11969 >
11970 <desc>
11971 The IAudioAdapter interface represents the virtual audio adapter of
11972 the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
11973 </desc>
11974 <attribute name="enabled" type="boolean">
11975 <desc>
11976 Flag whether the audio adapter is present in the
11977 guest system. If disabled, the virtual guest hardware will
11978 not contain any audio adapter. Can only be changed when
11979 the VM is not running.
11980 </desc>
11981 </attribute>
11982 <attribute name="audioController" type="AudioControllerType">
11983 <desc>
11984 The audio hardware we emulate.
11985 </desc>
11986 </attribute>
11987 <attribute name="audioDriver" type="AudioDriverType">
11988 <desc>
11989 Audio driver the adapter is connected to. This setting
11990 can only be changed when the VM is not running.
11991 </desc>
11992 </attribute>
11993 </interface>
11994
11995 <!--
11996 // IVRDPServer
11997 /////////////////////////////////////////////////////////////////////////
11998 -->
11999
12000 <enum
12001 name="VRDPAuthType"
12002 uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
12003 >
12004 <desc>
12005 VRDP authentication type.
12006 </desc>
12007
12008 <const name="Null" value="0">
12009 <desc>Null value, also means "no authentication".</desc>
12010 </const>
12011 <const name="External" value="1"/>
12012 <const name="Guest" value="2"/>
12013 </enum>
12014
12015 <interface
12016 name="IVRDPServer" extends="$unknown"
12017 uuid="f4584ae7-6bce-474b-83d6-17d235e6aa89"
12018 wsmap="managed"
12019 >
12020 <attribute name="enabled" type="boolean">
12021 <desc>VRDP server status.</desc>
12022 </attribute>
12023
12024 <attribute name="port" type="unsigned long">
12025 <desc>
12026 VRDP server port number.
12027 <note>
12028 Setting the value of this property to <tt>0</tt> will reset the port
12029 number to the default value which is
12030 currently <tt>3389</tt>. Reading this property will always return a
12031 real port number, even after it has been set to <tt>0</tt> (in which
12032 case the default port is returned).
12033 </note>
12034 </desc>
12035 </attribute>
12036
12037 <attribute name="netAddress" type="wstring">
12038 <desc>VRDP server address.</desc>
12039 </attribute>
12040
12041 <attribute name="authType" type="VRDPAuthType">
12042 <desc>VRDP authentication method.</desc>
12043 </attribute>
12044
12045 <attribute name="authTimeout" type="unsigned long">
12046 <desc>Timeout for guest authentication. Milliseconds.</desc>
12047 </attribute>
12048
12049 <attribute name="allowMultiConnection" type="boolean">
12050 <desc>
12051 Flag whether multiple simultaneous connections to the VM are permitted.
12052 Note that this will be replaced by a more powerful mechanism in the future.
12053 </desc>
12054 </attribute>
12055
12056 <attribute name="reuseSingleConnection" type="boolean">
12057 <desc>
12058 Flag whether the existing connection must be dropped and a new connection
12059 must be established by the VRDP server, when a new client connects in single
12060 connection mode.
12061 </desc>
12062 </attribute>
12063
12064 </interface>
12065
12066
12067 <!--
12068 // ISharedFolder
12069 /////////////////////////////////////////////////////////////////////////
12070 -->
12071
12072 <interface
12073 name="ISharedFolder" extends="$unknown"
12074 uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
12075 wsmap="struct"
12076 >
12077 <desc>
12078 The ISharedFolder interface represents a folder in the host computer's
12079 file system accessible from the guest OS running inside a virtual
12080 machine using an associated logical name.
12081
12082 There are three types of shared folders:
12083 <ul>
12084 <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
12085 folders available to all virtual machines.</li>
12086 <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
12087 VM-specific shared folders available to the given virtual machine at
12088 startup.</li>
12089 <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
12090 VM-specific shared folders created in the session context (for
12091 example, when the virtual machine is running) and automatically
12092 discarded when the session is closed (the VM is powered off).</li>
12093 </ul>
12094
12095 Logical names of shared folders must be unique within the given scope
12096 (global, permanent or transient). However, they do not need to be unique
12097 across scopes. In this case, the definition of the shared folder in a
12098 more specific scope takes precedence over definitions in all other
12099 scopes. The order of precedence is (more specific to more general):
12100 <ol>
12101 <li>Transient definitions</li>
12102 <li>Permanent definitions</li>
12103 <li>Global definitions</li>
12104 </ol>
12105
12106 For example, if MyMachine has a shared folder named
12107 <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
12108 transient shared folder named <tt>C_DRIVE</tt> (that points
12109 to <tt>C:\\\\WINDOWS</tt>) will change the definition
12110 of <tt>C_DRIVE</tt> in the guest OS so
12111 that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
12112 to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
12113 PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
12114 the previous (permanent) definition of <tt>C_DRIVE</tt> that points
12115 to <tt>C:\\</tt> if it still exists.
12116
12117 Note that permanent and transient shared folders of different machines
12118 are in different name spaces, so they don't overlap and don't need to
12119 have unique logical names.
12120
12121 <note>
12122 Global shared folders are not implemented in the current version of the
12123 product.
12124 </note>
12125 </desc>
12126
12127 <attribute name="name" type="wstring" readonly="yes">
12128 <desc>Logical name of the shared folder.</desc>
12129 </attribute>
12130
12131 <attribute name="hostPath" type="wstring" readonly="yes">
12132 <desc>Full path to the shared folder in the host file system.</desc>
12133 </attribute>
12134
12135 <attribute name="accessible" type="boolean" readonly="yes">
12136 <desc>
12137 Whether the folder defined by the host path is currently
12138 accessible or not.
12139 For example, the folder can be unaccessible if it is placed
12140 on the network share that is not available by the time
12141 this property is read.
12142 </desc>
12143 </attribute>
12144
12145 <attribute name="writable" type="boolean" readonly="yes">
12146 <desc>
12147 Whether the folder defined by the host path is writable or
12148 not.
12149 </desc>
12150 </attribute>
12151
12152 <attribute name="lastAccessError" type="wstring" readonly="yes">
12153 <desc>
12154 Text message that represents the result of the last accessibility
12155 check.
12156
12157 Accessibility checks are performed each time the <link to="#accessible"/>
12158 attribute is read. A @c null string is returned if the last
12159 accessibility check was successful. A non-null string indicates a
12160 failure and should normally describe a reason of the failure (for
12161 example, a file read error).
12162 </desc>
12163 </attribute>
12164
12165 </interface>
12166
12167 <!--
12168 // ISession
12169 /////////////////////////////////////////////////////////////////////////
12170 -->
12171
12172 <interface
12173 name="IInternalSessionControl" extends="$unknown"
12174 uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
12175 internal="yes"
12176 wsmap="suppress"
12177 >
12178 <method name="getPID">
12179 <desc>PID of the process that has created this Session object.
12180 </desc>
12181 <param name="pid" type="unsigned long" dir="return"/>
12182 </method>
12183
12184 <method name="getRemoteConsole">
12185 <desc>
12186 Returns the console object suitable for remote control.
12187
12188 <result name="VBOX_E_INVALID_VM_STATE">
12189 Session state prevents operation.
12190 </result>
12191 <result name="VBOX_E_INVALID_OBJECT_STATE">
12192 Session type prevents operation.
12193 </result>
12194
12195 </desc>
12196 <param name="console" type="IConsole" dir="return"/>
12197 </method>
12198
12199 <method name="assignMachine">
12200 <desc>
12201 Assigns the machine object associated with this direct-type
12202 session or informs the session that it will be a remote one
12203 (if @a machine == NULL).
12204
12205 <result name="VBOX_E_INVALID_VM_STATE">
12206 Session state prevents operation.
12207 </result>
12208 <result name="VBOX_E_INVALID_OBJECT_STATE">
12209 Session type prevents operation.
12210 </result>
12211
12212 </desc>
12213 <param name="machine" type="IMachine" dir="in"/>
12214 </method>
12215
12216 <method name="assignRemoteMachine">
12217 <desc>
12218 Assigns the machine and the (remote) console object associated with
12219 this remote-type session.
12220
12221 <result name="VBOX_E_INVALID_VM_STATE">
12222 Session state prevents operation.
12223 </result>
12224
12225 </desc>
12226 <param name="machine" type="IMachine" dir="in"/>
12227 <param name="console" type="IConsole" dir="in"/>
12228 </method>
12229
12230 <method name="updateMachineState">
12231 <desc>
12232 Updates the machine state in the VM process.
12233 Must be called only in certain cases
12234 (see the method implementation).
12235
12236 <result name="VBOX_E_INVALID_VM_STATE">
12237 Session state prevents operation.
12238 </result>
12239 <result name="VBOX_E_INVALID_OBJECT_STATE">
12240 Session type prevents operation.
12241 </result>
12242
12243 </desc>
12244 <param name="aMachineState" type="MachineState" dir="in"/>
12245 </method>
12246
12247 <method name="uninitialize">
12248 <desc>
12249 Uninitializes (closes) this session. Used by VirtualBox to close
12250 the corresponding remote session when the direct session dies
12251 or gets closed.
12252
12253 <result name="VBOX_E_INVALID_VM_STATE">
12254 Session state prevents operation.
12255 </result>
12256
12257 </desc>
12258 </method>
12259
12260 <method name="onDVDDriveChange">
12261 <desc>
12262 Triggered when settings of the DVD drive object of the
12263 associated virtual machine have changed.
12264
12265 <result name="VBOX_E_INVALID_VM_STATE">
12266 Session state prevents operation.
12267 </result>
12268 <result name="VBOX_E_INVALID_OBJECT_STATE">
12269 Session type prevents operation.
12270 </result>
12271
12272 </desc>
12273 </method>
12274
12275 <method name="onFloppyDriveChange">
12276 <desc>
12277 Triggered when settings of the floppy drive object of the
12278 associated virtual machine have changed.
12279
12280 <result name="VBOX_E_INVALID_VM_STATE">
12281 Session state prevents operation.
12282 </result>
12283 <result name="VBOX_E_INVALID_OBJECT_STATE">
12284 Session type prevents operation.
12285 </result>
12286
12287 </desc>
12288 </method>
12289
12290 <method name="onNetworkAdapterChange">
12291 <desc>
12292 Triggered when settings of a network adapter of the
12293 associated virtual machine have changed.
12294
12295 <result name="VBOX_E_INVALID_VM_STATE">
12296 Session state prevents operation.
12297 </result>
12298 <result name="VBOX_E_INVALID_OBJECT_STATE">
12299 Session type prevents operation.
12300 </result>
12301
12302 </desc>
12303 <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
12304 </method>
12305
12306 <method name="onSerialPortChange">
12307 <desc>
12308 Triggered when settings of a serial port of the
12309 associated virtual machine have changed.
12310
12311 <result name="VBOX_E_INVALID_VM_STATE">
12312 Session state prevents operation.
12313 </result>
12314 <result name="VBOX_E_INVALID_OBJECT_STATE">
12315 Session type prevents operation.
12316 </result>
12317
12318 </desc>
12319 <param name="serialPort" type="ISerialPort" dir="in"/>
12320 </method>
12321
12322 <method name="onParallelPortChange">
12323 <desc>
12324 Triggered when settings of a parallel port of the
12325 associated virtual machine have changed.
12326
12327 <result name="VBOX_E_INVALID_VM_STATE">
12328 Session state prevents operation.
12329 </result>
12330 <result name="VBOX_E_INVALID_OBJECT_STATE">
12331 Session type prevents operation.
12332 </result>
12333
12334 </desc>
12335 <param name="parallelPort" type="IParallelPort" dir="in"/>
12336 </method>
12337
12338 <method name="onStorageControllerChange">
12339 <desc>
12340 Triggered when settings of a storage controller of the
12341 associated virtual machine have changed.
12342
12343 <result name="VBOX_E_INVALID_VM_STATE">
12344 Session state prevents operation.
12345 </result>
12346 <result name="VBOX_E_INVALID_OBJECT_STATE">
12347 Session type prevents operation.
12348 </result>
12349
12350 </desc>
12351 </method>
12352
12353 <method name="onVRDPServerChange">
12354 <desc>
12355 Triggered when settings of the VRDP server object of the
12356 associated virtual machine have changed.
12357
12358 <result name="VBOX_E_INVALID_VM_STATE">
12359 Session state prevents operation.
12360 </result>
12361 <result name="VBOX_E_INVALID_OBJECT_STATE">
12362 Session type prevents operation.
12363 </result>
12364
12365 </desc>
12366 </method>
12367
12368 <method name="onUSBControllerChange">
12369 <desc>
12370 Triggered when settings of the USB controller object of the
12371 associated virtual machine have changed.
12372
12373 <result name="VBOX_E_INVALID_VM_STATE">
12374 Session state prevents operation.
12375 </result>
12376 <result name="VBOX_E_INVALID_OBJECT_STATE">
12377 Session type prevents operation.
12378 </result>
12379
12380 </desc>
12381 </method>
12382
12383 <method name="onSharedFolderChange">
12384 <desc>
12385 Triggered when a permanent (global or machine) shared folder has been
12386 created or removed.
12387 <note>
12388 We don't pass shared folder parameters in this notification because
12389 the order in which parallel notifications are delivered is not defined,
12390 therefore it could happen that these parameters were outdated by the
12391 time of processing this notification.
12392 </note>
12393
12394 <result name="VBOX_E_INVALID_VM_STATE">
12395 Session state prevents operation.
12396 </result>
12397 <result name="VBOX_E_INVALID_OBJECT_STATE">
12398 Session type prevents operation.
12399 </result>
12400
12401 </desc>
12402 <param name="global" type="boolean" dir="in"/>
12403 </method>
12404
12405 <method name="onUSBDeviceAttach">
12406 <desc>
12407 Triggered when a request to capture a USB device (as a result
12408 of matched USB filters or direct call to
12409 <link to="IConsole::attachUSBDevice"/>) has completed.
12410 A @c null @a error object means success, otherwise it
12411 describes a failure.
12412
12413 <result name="VBOX_E_INVALID_VM_STATE">
12414 Session state prevents operation.
12415 </result>
12416 <result name="VBOX_E_INVALID_OBJECT_STATE">
12417 Session type prevents operation.
12418 </result>
12419
12420 </desc>
12421 <param name="device" type="IUSBDevice" dir="in"/>
12422 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12423 <param name="maskedInterfaces" type="unsigned long" dir="in"/>
12424 </method>
12425
12426 <method name="onUSBDeviceDetach">
12427 <desc>
12428 Triggered when a request to release the USB device (as a result
12429 of machine termination or direct call to
12430 <link to="IConsole::detachUSBDevice"/>) has completed.
12431 A @c null @a error object means success, otherwise it
12432
12433 <result name="VBOX_E_INVALID_VM_STATE">
12434 Session state prevents operation.
12435 </result>
12436 <result name="VBOX_E_INVALID_OBJECT_STATE">
12437 Session type prevents operation.
12438 </result>
12439
12440 </desc>
12441 <param name="id" type="uuid" dir="in"/>
12442 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12443 </method>
12444
12445 <method name="onShowWindow">
12446 <desc>
12447 Called by <link to="IMachine::canShowConsoleWindow"/> and by
12448 <link to="IMachine::showConsoleWindow"/> in order to notify
12449 console callbacks
12450 <link to="IConsoleCallback::onCanShowWindow"/>
12451 and <link to="IConsoleCallback::onShowWindow"/>.
12452
12453 <result name="VBOX_E_INVALID_OBJECT_STATE">
12454 Session type prevents operation.
12455 </result>
12456
12457 </desc>
12458 <param name="check" type="boolean" dir="in"/>
12459 <param name="canShow" type="boolean" dir="out"/>
12460 <param name="winId" type="unsigned long long" dir="out"/>
12461 </method>
12462
12463 <method name="accessGuestProperty">
12464 <desc>
12465 Called by <link to="IMachine::getGuestProperty"/> and by
12466 <link to="IMachine::setGuestProperty"/> in order to read and
12467 modify guest properties.
12468
12469 <result name="VBOX_E_INVALID_VM_STATE">
12470 Machine session is not open.
12471 </result>
12472 <result name="VBOX_E_INVALID_OBJECT_STATE">
12473 Session type is not direct.
12474 </result>
12475
12476 </desc>
12477 <param name="name" type="wstring" dir="in"/>
12478 <param name="value" type="wstring" dir="in"/>
12479 <param name="flags" type="wstring" dir="in"/>
12480 <param name="isSetter" type="boolean" dir="in"/>
12481 <param name="retValue" type="wstring" dir="out"/>
12482 <param name="retTimestamp" type="unsigned long long" dir="out"/>
12483 <param name="retFlags" type="wstring" dir="out"/>
12484 </method>
12485
12486 <method name="enumerateGuestProperties">
12487 <desc>
12488 Return a list of the guest properties matching a set of patterns along
12489 with their values, time stamps and flags.
12490
12491 <result name="VBOX_E_INVALID_VM_STATE">
12492 Machine session is not open.
12493 </result>
12494 <result name="VBOX_E_INVALID_OBJECT_STATE">
12495 Session type is not direct.
12496 </result>
12497
12498 </desc>
12499 <param name="patterns" type="wstring" dir="in">
12500 <desc>
12501 The patterns to match the properties against as a comma-separated
12502 string. If this is empty, all properties currently set will be
12503 returned.
12504 </desc>
12505 </param>
12506 <param name="key" type="wstring" dir="out" safearray="yes">
12507 <desc>
12508 The key names of the properties returned.
12509 </desc>
12510 </param>
12511 <param name="value" type="wstring" dir="out" safearray="yes">
12512 <desc>
12513 The values of the properties returned. The array entries match the
12514 corresponding entries in the @a key array.
12515 </desc>
12516 </param>
12517 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
12518 <desc>
12519 The time stamps of the properties returned. The array entries match
12520 the corresponding entries in the @a key array.
12521 </desc>
12522 </param>
12523 <param name="flags" type="wstring" dir="out" safearray="yes">
12524 <desc>
12525 The flags of the properties returned. The array entries match the
12526 corresponding entries in the @a key array.
12527 </desc>
12528 </param>
12529 </method>
12530
12531 </interface>
12532
12533 <interface
12534 name="ISession" extends="$dispatched"
12535 uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
12536 wsmap="managed"
12537 >
12538 <desc>
12539 The ISession interface represents a serialization primitive for virtual
12540 machines.
12541
12542 With VirtualBox, every time one wishes to manipulate a virtual machine
12543 (e.g. change its settings or start execution), a session object is
12544 required. Such an object must be passed to one of the session methods
12545 that open the given session, which then initiates the machine manipulation.
12546
12547 A session serves several purposes: it identifies to the inter-process VirtualBox
12548 code which process is currently working with the virtual machine, and it ensures
12549 that there are no incompatible requests from several processes for the
12550 same virtual machine. Session objects can therefore be thought of as mutex
12551 semaphores that lock virtual machines to prevent conflicting accesses from
12552 several processes.
12553
12554 How sessions objects are used depends on whether you use the Main API
12555 via COM or via the webservice:
12556
12557 <ul>
12558 <li>When using the COM API directly, an object of the Session class from the
12559 VirtualBox type library needs to be created. In regular COM C++ client code,
12560 this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
12561 This object will then act as a local session object in further calls to open
12562 a session.
12563 </li>
12564
12565 <li>In the webservice, the session manager (IWebsessionManager) instead creates
12566 one session object automatically when <link to="IWebsessionManager::logon" />
12567 is called. A managed object reference to that session object can be retrieved by
12568 calling <link to="IWebsessionManager::getSessionObject" />. This session object
12569 reference can then be used to open sessions.
12570 </li>
12571 </ul>
12572
12573 Sessions are mainly used in two variations:
12574
12575 <ul>
12576 <li>
12577 To start a virtual machine in a separate process, one would call
12578 <link to="IVirtualBox::openRemoteSession"/>, which requires a session
12579 object as its first parameter. This session then identifies the caller
12580 and lets him control the started machine (for example, pause machine
12581 execution or power it down) as well as be notified about machine
12582 execution state changes.
12583 </li>
12584
12585 <li>To alter machine settings, or to start machine execution within the
12586 current process, one needs to open a direct session for the machine first by
12587 calling <link to="IVirtualBox::openSession"/>. While a direct session
12588 is open within one process, no any other process may open another direct
12589 session for the same machine. This prevents the machine from being changed
12590 by other processes while it is running or while the machine is being configured.
12591 </li>
12592 </ul>
12593
12594 One also can attach to an existing direct session already opened by
12595 another process (for example, in order to send a control request to the
12596 virtual machine such as the pause or the reset request). This is done by
12597 calling <link to="IVirtualBox::openExistingSession"/>.
12598
12599 <note>
12600 Unless you are trying to write a new VirtualBox front-end that
12601 performs direct machine execution (like the VirtualBox or VBoxSDL
12602 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
12603 session opened by <link to="IVirtualBox::openSession"/> and use this
12604 session only to change virtual machine settings. If you simply want to
12605 start virtual machine execution using one of the existing front-ends
12606 (for example the VirtualBox GUI or headless server), simply use
12607 <link to="IVirtualBox::openRemoteSession"/>; these front-ends
12608 will power up the machine automatically for you.
12609 </note>
12610 </desc>
12611
12612 <attribute name="state" type="SessionState" readonly="yes">
12613 <desc>Current state of this session.</desc>
12614 </attribute>
12615
12616 <attribute name="type" type="SessionType" readonly="yes">
12617 <desc>
12618 Type of this session. The value of this attribute is valid only
12619 if the session is currently open (i.e. its #state is
12620 SessionType_SessionOpen), otherwise an error will be returned.
12621 </desc>
12622 </attribute>
12623
12624 <attribute name="machine" type="IMachine" readonly="yes">
12625 <desc>Machine object associated with this session.</desc>
12626 </attribute>
12627
12628 <attribute name="console" type="IConsole" readonly="yes">
12629 <desc>Console object associated with this session.</desc>
12630 </attribute>
12631
12632 <method name="close">
12633 <desc>
12634 Closes a session that was previously opened.
12635
12636 It is recommended that every time an "open session" method (such as
12637 <link to="IVirtualBox::openRemoteSession" /> or
12638 <link to="IVirtualBox::openSession" />) has been called to
12639 manipulate a virtual machine, the caller invoke
12640 ISession::close() when it's done doing so. Since sessions are
12641 serialization primitives much like ordinary mutexes, they are
12642 best used the same way: for each "open" call, there should be
12643 a matching "close" call, even when errors occur.
12644
12645 Otherwise, if a direct session for a machine opened with
12646 <link to="IVirtualBox::openSession"/> is not explicitly closed
12647 when the application terminates, the state of the machine will
12648 be set to <link to="MachineState_Aborted" /> on the server.
12649
12650 Generally, it is recommended to close all open sessions explicitly
12651 before terminating the application (regardless of the reason for
12652 the termination).
12653
12654 <note>
12655 Do not expect the session state (<link to="ISession::state" />
12656 to return to "Closed" immediately after you invoke
12657 ISession::close(), particularly if you have started a remote
12658 session to execute the VM in a new process. The session state will
12659 automatically return to "Closed" once the VM is no longer executing,
12660 which can of course take a very long time.
12661 </note>
12662
12663 <result name="E_UNEXPECTED">
12664 Session is not open.
12665 </result>
12666
12667 </desc>
12668 </method>
12669
12670 </interface>
12671
12672 <!--
12673 // IStorageController
12674 /////////////////////////////////////////////////////////////////////////
12675 -->
12676
12677 <enum
12678 name="StorageBus"
12679 uuid="f381fdca-5953-41d0-b2bd-0542b012698d"
12680 >
12681 <desc>
12682 The connection type of the storage controller.
12683 </desc>
12684 <const name="Null" value="0">
12685 <desc><tt>null</tt> value. Never used by the API.</desc>
12686 </const>
12687 <const name="IDE" value="1"/>
12688 <const name="SATA" value="2"/>
12689 <const name="SCSI" value="3"/>
12690 </enum>
12691
12692 <enum
12693 name="StorageControllerType"
12694 uuid="685387db-a837-4320-a258-08f46a22f62a"
12695 >
12696 <desc>
12697 Storage controller type.
12698 </desc>
12699
12700 <const name="Null" value="0">
12701 <desc><tt>null</tt> value. Never used by the API.</desc>
12702 </const>
12703 <const name="LsiLogic" value="1"/>
12704 <const name="BusLogic" value="2"/>
12705 <const name="IntelAhci" value="3"/>
12706 <const name="PIIX3" value="4"/>
12707 <const name="PIIX4" value="5"/>
12708 <const name="ICH6" value="6"/>
12709 </enum>
12710
12711 <interface
12712 name="IStorageController" extends="$unknown"
12713 uuid="6bf8335b-d14a-44a5-9b45-ddc49ce7d5b2"
12714 wsmap="managed"
12715 >
12716 <desc>
12717 Represents a storage controller that is attached to a virtual machine
12718 (<link to="IMachine" />). Just as hard disks are attached to storage
12719 controllers in a real computer, virtual hard disks (represented by
12720 <link to="IHardDisk" />) are attached to virtual storage controllers,
12721 represented by this interface.
12722
12723 VirtualBox supports three types of virtual storage controller hardware:
12724 IDE, SCSI, and SATA (see <link to="#bus" />). Depending on which of
12725 these three is used, certain sub-types are available and can be
12726 selected in <link to="#controllerType" />.
12727 </desc>
12728
12729 <attribute name="name" type="wstring" readonly="yes">
12730 <desc>
12731 Name of the storage controller, as originally specified with
12732 <link to="IMachine::addStorageController" />. This then uniquely
12733 identifies this controller with other method calls such as
12734 <link to="IMachine::attachHardDisk" />.
12735 </desc>
12736 </attribute>
12737
12738 <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
12739 <desc>
12740 Maximum number of devices which can be attached to one port.
12741 </desc>
12742 </attribute>
12743
12744 <attribute name="minPortCount" type="unsigned long" readonly="yes">
12745 <desc>
12746 Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
12747 </desc>
12748 </attribute>
12749
12750 <attribute name="maxPortCount" type="unsigned long" readonly="yes">
12751 <desc>
12752 Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
12753 </desc>
12754 </attribute>
12755
12756 <attribute name="instance" type="unsigned long">
12757 <desc>
12758 The instance number of the device in the running VM.
12759 </desc>
12760 </attribute>
12761
12762 <attribute name="portCount" type="unsigned long">
12763 <desc>
12764 The number of currently usable ports on the controller.
12765 The minimum and maximum number of ports for one controller are
12766 stored in <link to="IStorageController::minPortCount"/>
12767 and <link to="IStorageController::maxPortCount"/>.
12768 </desc>
12769 </attribute>
12770
12771 <attribute name="bus" type="StorageBus" readonly="yes">
12772 <desc>
12773 The connection type of the storage controller.
12774 </desc>
12775 </attribute>
12776
12777 <attribute name="controllerType" type="StorageControllerType">
12778 <desc>
12779 Type of the virtual storage controller. Depending on this value,
12780 VirtualBox will provide a different virtual storage controller hardware
12781 to the guest.
12782
12783 For SCSI controllers, the default type is LsiLogic.
12784 </desc>
12785 </attribute>
12786
12787 <method name="GetIDEEmulationPort">
12788 <desc>
12789 Gets the corresponding port number which is emulated as an IDE device.
12790
12791 <result name="E_INVALIDARG">
12792 The @a devicePosition is not in the range 0 to 3.
12793 </result>
12794 <result name="E_NOTIMPL">
12795 The storage controller type is not SATAIntelAhci.
12796 </result>
12797
12798 </desc>
12799 <param name="devicePosition" type="long" dir="in"/>
12800 <param name="portNumber" type="long" dir="return"/>
12801 </method>
12802
12803 <method name="SetIDEEmulationPort">
12804 <desc>
12805 Sets the port number which is emulated as an IDE device.
12806
12807 <result name="E_INVALIDARG">
12808 The @a devicePosition is not in the range 0 to 3 or the
12809 @a portNumber is not in the range 0 to 29.
12810 </result>
12811 <result name="E_NOTIMPL">
12812 The storage controller type is not SATAIntelAhci.
12813 </result>
12814
12815 </desc>
12816 <param name="devicePosition" type="long" dir="in"/>
12817 <param name="portNumber" type="long" dir="in"/>
12818 </method>
12819
12820 </interface>
12821
12822<if target="wsdl">
12823
12824 <!--
12825 // IManagedObjectRef
12826 /////////////////////////////////////////////////////////////////////////
12827 -->
12828
12829 <interface
12830 name="IManagedObjectRef" extends="$unknown"
12831 uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
12832 internal="yes"
12833 wsmap="managed"
12834 wscpp="hardcoded"
12835 >
12836 <desc>
12837 Managed object reference.
12838
12839 Only within the webservice, a managed object reference (which is really
12840 an opaque number) allows a webservice client to address an object
12841 that lives in the address space of the webservice server.
12842
12843 Behind each managed object reference, there is a COM object that lives
12844 in the webservice server's address space. The COM object is not freed
12845 until the managed object reference is released, either by an explicit
12846 call to <link to="IManagedObjectRef::release" /> or by logging off from
12847 the webservice (<link to="IWebsessionManager::logoff" />), which releases
12848 all objects created during the webservice session.
12849
12850 Whenever a method call of the VirtualBox API returns a COM object, the
12851 webservice representation of that method will instead return a
12852 managed object reference, which can then be used to invoke methods
12853 on that object.
12854 </desc>
12855
12856 <method name="getInterfaceName">
12857 <desc>
12858 Returns the name of the interface that this managed object represents,
12859 for example, "IMachine", as a string.
12860 </desc>
12861 <param name="return" type="wstring" dir="return"/>
12862 </method>
12863
12864 <method name="release">
12865 <desc>
12866 Releases this managed object reference and frees the resources that
12867 were allocated for it in the webservice server process. After calling
12868 this method, the identifier of the reference can no longer be used.
12869 </desc>
12870 </method>
12871
12872 </interface>
12873
12874 <!--
12875 // IWebsessionManager
12876 /////////////////////////////////////////////////////////////////////////
12877 -->
12878
12879 <interface
12880 name="IWebsessionManager" extends="$unknown"
12881 uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
12882 internal="yes"
12883 wsmap="global"
12884 wscpp="hardcoded"
12885 >
12886 <desc>
12887 Websession manager. This provides essential services
12888 to webservice clients.
12889 </desc>
12890 <method name="logon">
12891 <desc>
12892 Logs a new client onto the webservice and returns a managed object reference to
12893 the IVirtualBox instance, which the client can then use as a basis to further
12894 queries, since all calls to the VirtualBox API are based on the IVirtualBox
12895 interface, in one way or the other.
12896 </desc>
12897 <param name="username" type="wstring" dir="in"/>
12898 <param name="password" type="wstring" dir="in"/>
12899 <param name="return" type="IVirtualBox" dir="return"/>
12900 </method>
12901
12902 <method name="getSessionObject">
12903 <desc>
12904 Returns a managed object reference to the internal ISession object that was created
12905 for this web service session when the client logged on.
12906
12907 <see>ISession</see>
12908 </desc>
12909 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12910 <param name="return" type="ISession" dir="return"/>
12911 </method>
12912
12913 <method name="logoff">
12914 <desc>
12915 Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
12916 and destroys all resources associated with the session (most importantly, all
12917 managed objects created in the server while the session was active).
12918 </desc>
12919 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12920 </method>
12921
12922 </interface>
12923
12924</if>
12925
12926 <!--
12927 // IPerformanceCollector & friends
12928 /////////////////////////////////////////////////////////////////////////
12929 -->
12930
12931 <interface
12932 name="IPerformanceMetric" extends="$unknown"
12933 uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
12934 >
12935 <desc>
12936 The IPerformanceMetric interface represents parameters of the given
12937 performance metric.
12938 </desc>
12939
12940 <attribute name="metricName" type="wstring" readonly="yes">
12941 <desc>
12942 Name of the metric.
12943 </desc>
12944 </attribute>
12945
12946 <attribute name="object" type="$unknown" readonly="yes">
12947 <desc>
12948 Object this metric belongs to.
12949 </desc>
12950 </attribute>
12951
12952 <attribute name="description" type="wstring" readonly="yes">
12953 <desc>
12954 Textual description of the metric.
12955 </desc>
12956 </attribute>
12957
12958 <attribute name="period" type="unsigned long" readonly="yes">
12959 <desc>
12960 Time interval between samples, measured in seconds.
12961 </desc>
12962 </attribute>
12963
12964 <attribute name="count" type="unsigned long" readonly="yes">
12965 <desc>
12966 Number of recent samples retained by the performance collector for this
12967 metric.
12968
12969 When the collected sample count exceeds this number, older samples
12970 are discarded.
12971 </desc>
12972 </attribute>
12973
12974 <attribute name="unit" type="wstring" readonly="yes">
12975 <desc>
12976 Unit of measurement.
12977 </desc>
12978 </attribute>
12979
12980 <attribute name="minimumValue" type="long" readonly="yes">
12981 <desc>
12982 Minimum possible value of this metric.
12983 </desc>
12984 </attribute>
12985
12986 <attribute name="maximumValue" type="long" readonly="yes">
12987 <desc>
12988 Maximum possible value of this metric.
12989 </desc>
12990 </attribute>
12991 </interface>
12992
12993 <interface
12994 name="IPerformanceCollector" extends="$unknown"
12995 uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
12996 wsmap="managed"
12997 >
12998 <desc>
12999 The IPerformanceCollector interface represents a service that collects and
13000 stores performance metrics data.
13001
13002 Performance metrics are associated with objects like IHost and
13003 IMachine. Each object has a distinct set of performance metrics.
13004 The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
13005
13006 Metric data are collected at the specified intervals and are retained
13007 internally. The interval and the number of samples retained can be set
13008 with <link to="IPerformanceCollector::setupMetrics" />.
13009
13010 Metrics are organized hierarchically, each level separated by slash (/).
13011 General scheme for metric name is
13012 "Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
13013 metric name stands for: CPU category, Load metric, User submetric, average
13014 aggregate. An aggregate function is computed over all retained data. Valid
13015 aggregate functions are:
13016
13017 <ul>
13018 <li>avg -- average</li>
13019 <li>min -- minimum</li>
13020 <li>max -- maximum</li>
13021 </ul>
13022
13023 "Category/Metric" together form base metric name. A base metric is the
13024 smallest unit for which a sampling interval and the number of retained
13025 samples can be set. Only base metrics can be enabled and disabled. All
13026 sub-metrics are collected when their base metric is collected.
13027 Collected values for any set of sub-metrics can be queried with
13028 <link to="IPerformanceCollector::queryMetricsData" />. When setting up
13029 metric parameters, querying metric data, enabling or disabling metrics
13030 wildcards can be used in metric names to specify a subset of metrics. For
13031 example, to select all CPU-related metrics use <tt>CPU/*</tt>, all
13032 averages can be queried using <tt>*:avg</tt> and so on. To query metric
13033 values without aggregates <tt>*:</tt> can be used.
13034
13035 The valid names for base metrics are:
13036
13037 <ul>
13038 <li>CPU/Load</li>
13039 <li>CPU/MHz</li>
13040 <li>RAM/Usage</li>
13041 </ul>
13042
13043 The general sequence for collecting and retrieving the metrics is:
13044 <ul>
13045 <li>
13046 Obtain an instance of IPerformanceCollector with
13047 <link to="IVirtualBox::performanceCollector" />
13048 </li>
13049 <li>
13050 Allocate and populate an array with references to objects the metrics
13051 will be collected for. Use references to IHost and IMachine objects.
13052 </li>
13053 <li>
13054 Allocate and populate an array with base metric names the data will be
13055 collected for.
13056 </li>
13057 <li>
13058 Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
13059 metric data will be collected and stored.
13060 </li>
13061 <li>
13062 Wait for the data to get collected.
13063 </li>
13064 <li>
13065 Allocate and populate an array with references to objects the metric
13066 values will be queried for. You can re-use the object array used for
13067 setting base metrics.
13068 </li>
13069 <li>
13070 Allocate and populate an array with metric names the data will be
13071 collected for. Note that metric names differ from base metric names.
13072 </li>
13073 <li>
13074 Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
13075 have been collected so far are returned. Note that the values are still
13076 retained internally and data collection continues.
13077 </li>
13078 </ul>
13079
13080 For an example of usage refer to the following files in VirtualBox SDK:
13081 <ul>
13082 <li>
13083 Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
13084 </li>
13085 <li>
13086 Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
13087 </li>
13088 </ul>
13089 </desc>
13090
13091 <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
13092 <desc>
13093 Array of unique names of metrics.
13094
13095 This array represents all metrics supported by the performance
13096 collector. Individual objects do not necessarily support all of them.
13097 <link to="IPerformanceCollector::getMetrics"/> can be used to get the
13098 list of supported metrics for a particular object.
13099 </desc>
13100 </attribute>
13101
13102 <method name="getMetrics">
13103 <desc>
13104 Returns parameters of specified metrics for a set of objects.
13105 <note>
13106 @c Null metrics array means all metrics. @c Null object array means
13107 all existing objects.
13108 </note>
13109 </desc>
13110 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13111 <desc>
13112 Metric name filter. Currently, only a comma-separated list of metrics
13113 is supported.
13114 </desc>
13115 </param>
13116 <param name="objects" type="$unknown" dir="in" safearray="yes">
13117 <desc>
13118 Set of objects to return metric parameters for.
13119 </desc>
13120 </param>
13121 <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
13122 <desc>
13123 Array of returned metric parameters.
13124 </desc>
13125 </param>
13126 </method>
13127
13128 <method name="setupMetrics">
13129 <desc>
13130 Sets parameters of specified base metrics for a set of objects. Returns
13131 an array of <link to="IPerformanceMetric" /> describing the metrics have
13132 been affected.
13133 <note>
13134 @c Null or empty metric name array means all metrics. @c Null or empty
13135 object array means all existing objects. If metric name array contains
13136 a single element and object array contains many, the single metric
13137 name array element is applied to each object array element to form
13138 metric/object pairs.
13139 </note>
13140 </desc>
13141 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13142 <desc>
13143 Metric name filter. Comma-separated list of metrics with wildcard
13144 support.
13145 </desc>
13146 </param>
13147 <param name="objects" type="$unknown" dir="in" safearray="yes">
13148 <desc>
13149 Set of objects to setup metric parameters for.
13150 </desc>
13151 </param>
13152 <param name="period" type="unsigned long" dir="in">
13153 <desc>
13154 Time interval in seconds between two consecutive samples of performance
13155 data.
13156 </desc>
13157 </param>
13158 <param name="count" type="unsigned long" dir="in">
13159 <desc>
13160 Number of samples to retain in performance data history. Older samples
13161 get discarded.
13162 </desc>
13163 </param>
13164 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13165 <desc>
13166 Array of metrics that have been modified by the call to this method.
13167 </desc>
13168 </param>
13169 </method>
13170
13171 <method name="enableMetrics">
13172 <desc>
13173 Turns on collecting specified base metrics. Returns an array of
13174 <link to="IPerformanceMetric" /> describing the metrics have been
13175 affected.
13176 <note>
13177 @c Null or empty metric name array means all metrics. @c Null or empty
13178 object array means all existing objects. If metric name array contains
13179 a single element and object array contains many, the single metric
13180 name array element is applied to each object array element to form
13181 metric/object pairs.
13182 </note>
13183 </desc>
13184 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13185 <desc>
13186 Metric name filter. Comma-separated list of metrics with wildcard
13187 support.
13188 </desc>
13189 </param>
13190 <param name="objects" type="$unknown" dir="in" safearray="yes">
13191 <desc>
13192 Set of objects to enable metrics for.
13193 </desc>
13194 </param>
13195 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13196 <desc>
13197 Array of metrics that have been modified by the call to this method.
13198 </desc>
13199 </param>
13200 </method>
13201
13202 <method name="disableMetrics">
13203 <desc>
13204 Turns off collecting specified base metrics. Returns an array of
13205 <link to="IPerformanceMetric" /> describing the metrics have been
13206 affected.
13207 <note>
13208 @c Null or empty metric name array means all metrics. @c Null or empty
13209 object array means all existing objects. If metric name array contains
13210 a single element and object array contains many, the single metric
13211 name array element is applied to each object array element to form
13212 metric/object pairs.
13213 </note>
13214 </desc>
13215 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13216 <desc>
13217 Metric name filter. Comma-separated list of metrics with wildcard
13218 support.
13219 </desc>
13220 </param>
13221 <param name="objects" type="$unknown" dir="in" safearray="yes">
13222 <desc>
13223 Set of objects to disable metrics for.
13224 </desc>
13225 </param>
13226 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13227 <desc>
13228 Array of metrics that have been modified by the call to this method.
13229 </desc>
13230 </param>
13231 </method>
13232
13233 <method name="queryMetricsData">
13234 <desc>
13235 Queries collected metrics data for a set of objects.
13236
13237 The data itself and related metric information are returned in seven
13238 parallel and one flattened array of arrays. Elements of
13239 <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
13240 returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
13241 the same index describe one set of values corresponding to a single
13242 metric.
13243
13244 The <tt>returnData</tt> parameter is a flattened array of arrays. Each
13245 start and length of a sub-array is indicated by
13246 <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
13247 value for metric <tt>metricNames[i]</tt> is at
13248 <tt>returnData[returnIndices[i]]</tt>.
13249
13250 <note>
13251 @c Null or empty metric name array means all metrics. @c Null or empty
13252 object array means all existing objects. If metric name array contains
13253 a single element and object array contains many, the single metric
13254 name array element is applied to each object array element to form
13255 metric/object pairs.
13256 </note>
13257 <note>
13258 Data collection continues behind the scenes after call to
13259 @c queryMetricsData. The return data can be seen as the snapshot of
13260 the current state at the time of @c queryMetricsData call. The
13261 internally kept metric values are not cleared by the call. This makes
13262 possible querying different subsets of metrics or aggregates with
13263 subsequent calls. If periodic querying is needed it is highly
13264 suggested to query the values with @c interval*count period to avoid
13265 confusion. This way a completely new set of data values will be
13266 provided by each query.
13267 </note>
13268 </desc>
13269 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13270 <desc>
13271 Metric name filter. Comma-separated list of metrics with wildcard
13272 support.
13273 </desc>
13274 </param>
13275 <param name="objects" type="$unknown" dir="in" safearray="yes">
13276 <desc>
13277 Set of objects to query metrics for.
13278 </desc>
13279 </param>
13280 <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
13281 <desc>
13282 Names of metrics returned in @c returnData.
13283 </desc>
13284 </param>
13285 <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
13286 <desc>
13287 Objects associated with metrics returned in @c returnData.
13288 </desc>
13289 </param>
13290 <param name="returnUnits" type="wstring" dir="out" safearray="yes">
13291 <desc>
13292 Units of measurement for each returned metric.
13293 </desc>
13294 </param>
13295 <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
13296 <desc>
13297 Divisor that should be applied to return values in order to get
13298 floating point values. For example:
13299 <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
13300 will retrieve the floating point value of i-th sample of the first
13301 metric.
13302 </desc>
13303 </param>
13304 <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
13305 <desc>
13306 Sequence numbers of the first elements of value sequences of particular metrics
13307 returned in @c returnData. For aggregate metrics it is the sequence number of
13308 the sample the aggregate started calculation from.
13309 </desc>
13310 </param>
13311 <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
13312 <desc>
13313 Indices of the first elements of value sequences of particular metrics
13314 returned in @c returnData.
13315 </desc>
13316 </param>
13317 <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
13318 <desc>
13319 Lengths of value sequences of particular metrics.
13320 </desc>
13321 </param>
13322 <param name="returnData" type="long" dir="return" safearray="yes">
13323 <desc>
13324 Flattened array of all metric data containing sequences of values for
13325 each metric.
13326 </desc>
13327 </param>
13328 </method>
13329
13330 </interface>
13331
13332 <module name="VBoxSVC" context="LocalServer">
13333 <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
13334 namespace="virtualbox.org">
13335 <interface name="IVirtualBox" default="yes"/>
13336 </class>
13337 </module>
13338
13339 <module name="VBoxC" context="InprocServer" threadingModel="Free">
13340 <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
13341 namespace="virtualbox.org">
13342 <interface name="ISession" default="yes"/>
13343 </class>
13344 </module>
13345
13346</library>
13347
13348</idl>
13349
13350<!-- 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