VirtualBox

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

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

Main: add read/write param to OpenHardDisk to allow for opening disk images during import without requiring write access

  • Property svn:eol-style set to native
File size: 486.7 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="MachineState"
363 uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
364 >
365 <desc>
366 Virtual machine execution state.
367
368 This enumeration represents possible values of the <link
369 to="IMachine::state"/> attribute.
370
371 Below is the basic virtual machine state diagram. It shows how the state
372 changes during virtual machine execution. The text in square braces shows
373 a method of the IConsole interface that performs the given state
374 transition.
375
376 <pre>
377 +---------[powerDown()] &lt;- Stuck &lt;--[failure]-+
378 V |
379 +-&gt; PoweredOff --+--&gt;[powerUp()]--&gt; Starting --+ | +-----[resume()]-----+
380 | | | | V |
381 | Aborted -----+ +--&gt; Running --[pause()]--&gt; Paused
382 | | ^ | ^ |
383 | Saved -----------[powerUp()]--&gt; Restoring -+ | | | |
384 | ^ | | | |
385 | | +-----------------------------------------+-|-------------------+ +
386 | | | | |
387 | | +-- Saving &lt;--------[takeSnapshot()]&lt;-------+---------------------+
388 | | | |
389 | +-------- Saving &lt;--------[saveState()]&lt;----------+---------------------+
390 | | |
391 +-------------- Stopping -------[powerDown()]&lt;----------+---------------------+
392 </pre>
393
394 Note that states to the right from PoweredOff, Aborted and Saved in the
395 above diagram are called <i>online VM states</i>. These states
396 represent the virtual machine which is being executed in a dedicated
397 process (usually with a GUI window attached to it where you can see the
398 activity of the virtual machine and interact with it). There are two
399 special pseudo-states, FirstOnline and LastOnline, that can be used in
400 relational expressions to detect if the given machine state is online or
401 not:
402
403 <pre>
404 if (machine.GetState() &gt;= MachineState_FirstOnline &amp;&amp;
405 machine.GetState() &lt;= MachineState_LastOnline)
406 {
407 ...the machine is being executed...
408 }
409 </pre>
410
411 When the virtual machine is in one of the online VM states (that is, being
412 executed), only a few machine settings can be modified. Methods working
413 with such settings contain an explicit note about that. An attempt to
414 change any oter setting or perform a modifying operation during this time
415 will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
416
417 All online states except Running, Paused and Stuck are transitional: they
418 represent temporary conditions of the virtual machine that will last as
419 long as the operation that initiated such a condition.
420
421 The Stuck state is a special case. It means that execution of the machine
422 has reached the "Guru Meditation" condition. This condition indicates an
423 internal VMM (virtual machine manager) failure which may happen as a
424 result of either an unhandled low-level virtual hardware exception or one
425 of the recompiler exceptions (such as the <i>too-many-traps</i>
426 condition).
427
428 Note also that any online VM state may transit to the Aborted state. This
429 happens if the process that is executing the virtual machine terminates
430 unexpectedly (for example, crashes). Other than that, the Aborted state is
431 equivalent to PoweredOff.
432
433 There are also a few additional state diagrams that do not deal with
434 virtual machine execution and therefore are shown separately. The states
435 shown on these diagrams are called <i>offline VM states</i> (this includes
436 PoweredOff, Aborted and Saved too).
437
438 The first diagram shows what happens when a lengthy setup operation is
439 being executed (such as <link to="IMachine::attachHardDisk"/>).
440
441 <pre>
442 +-----------------------------------(same sate as before the call)------+
443 | |
444 +-&gt; PoweredOff --+ |
445 | | |
446 |-&gt; Aborted -----+--&gt;[lengthy VM configuration call] --&gt; SettingUp -----+
447 | |
448 +-&gt; Saved -------+
449 </pre>
450
451 The next two diagrams demonstrate the process of taking a snapshot of a
452 powered off virtual machine and performing one of the "discard..."
453 operations, respectively.
454
455 <pre>
456 +-----------------------------------(same sate as before the call)------+
457 | |
458 +-&gt; PoweredOff --+ |
459 | +--&gt;[takeSnapshot()] -------------------&gt; Saving ------+
460 +-&gt; Aborted -----+
461
462 +-&gt; PoweredOff --+
463 | |
464 | Aborted -----+--&gt;[discardSnapshot() ]-------------&gt; Discarding --+
465 | | [discardCurrentState()] |
466 +-&gt; Saved -------+ [discardCurrentSnapshotAndState()] |
467 | |
468 +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
469 </pre>
470
471 Note that the Saving state is present in both the offline state group and
472 online state group. Currently, the only way to determine what group is
473 assumed in a particular case is to remember the previous machine state: if
474 it was Running or Paused, then Saving is an online state, otherwise it is
475 an offline state. This inconsistency may be removed in one of the future
476 versions of VirtualBox by adding a new state.
477
478 <note internal="yes">
479 For whoever decides to touch this enum: In order to keep the
480 comparisons involving FirstOnline and LastOnline pseudo-states valid,
481 the numeric values of these states must be correspondingly updated if
482 needed: for any online VM state, the condition
483 <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
484 <tt>true</tt>. The same relates to transient states for which
485 the condition <tt>FirstOnline &lt;= state &lt;= LastOnline</tt> must be
486 <tt>true</tt>.
487 </note>
488 </desc>
489
490 <const name="Null" value="0">
491 <desc>Null value (nver used by the API).</desc>
492 </const>
493 <const name="PoweredOff" value="1">
494 <desc>
495 The machine is not running.
496 </desc>
497 </const>
498 <const name="Saved" value="2">
499 <desc>
500 The machine is not currently running, but the execution state of the machine
501 has been saved to an external file when it was running.
502 </desc>
503 </const>
504 <const name="Aborted" value="3">
505 <desc>
506 The process running the machine has terminated abnormally.
507 </desc>
508 </const>
509 <const name="Running" value="4">
510 <desc>
511 The machine is currently being executed.
512 <note internal="yes">
513 For whoever decides to touch this enum: In order to keep the
514 comparisons in the old source code valid, this state must immediately
515 precede the Paused state.
516 </note>
517 </desc>
518 </const>
519 <const name="Paused" value="5">
520 <desc>
521 Execution of the machine has been paused.
522 <note internal="yes">
523 For whoever decides to touch this enum: In order to keep the
524 comparisons in the old source code valid, this state must immediately
525 follow the Running state.
526 </note>
527 </desc>
528 </const>
529 <const name="Stuck" value="6">
530 <desc>
531 Execution of the machine has reached the "Guru Meditation"
532 condition.
533 </desc>
534 </const>
535 <const name="Starting" value="7">
536 <desc>
537 Machine is being started after powering it on from a
538 zero execution state.
539 </desc>
540 </const>
541 <const name="Stopping" value="8">
542 <desc>
543 Machine is being normally stopped powering it off, or after the guest OS
544 has initiated a shutdown sequence.
545 </desc>
546 </const>
547 <const name="Saving" value="9">
548 <desc>
549 Machine is saving its execution state to a file or an online
550 snapshot of the machine is being taken.
551 </desc>
552 </const>
553 <const name="Restoring" value="10">
554 <desc>
555 Execution state of the machine is being restored from a file
556 after powering it on from the saved execution state.
557 </desc>
558 </const>
559 <const name="Discarding" value="11">
560 <desc>
561 Snapshot of the machine is being discarded.
562 </desc>
563 </const>
564 <const name="SettingUp" value="12">
565 <desc>
566 Lengthy setup operation is in progress.
567 </desc>
568 </const>
569
570 <const name="FirstOnline" value="4" wsmap="suppress"> <!-- Running -->
571 <desc>
572 Pseudo-state: first online state (for use in relational expressions).
573 </desc>
574 </const>
575 <const name="LastOnline" value="10" wsmap="suppress"> <!-- Restoring -->
576 <desc>
577 Pseudo-state: last online state (for use in relational expressions).
578 </desc>
579 </const>
580
581 <const name="FirstTransient" value="7" wsmap="suppress"> <!-- Starting -->
582 <desc>
583 Pseudo-state: first transient state (for use in relational expressions).
584 </desc>
585 </const>
586 <const name="LastTransient" value="12" wsmap="suppress"> <!-- SettingUp -->
587 <desc>
588 Pseudo-state: last transient state (for use in relational expressions).
589 </desc>
590 </const>
591
592 </enum>
593
594 <enum
595 name="SessionState"
596 uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
597 >
598 <desc>
599 Session state. This enumeration represents possible values of
600 <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
601 attributes. See individual enumerator descriptions for the meaning for
602 every value.
603 </desc>
604
605 <const name="Null" value="0">
606 <desc>Null value (never used by the API).</desc>
607 </const>
608 <const name="Closed" value="1">
609 <desc>
610 The machine has no open sessions (<link to="IMachine::sessionState"/>);
611 the session is closed (<link to="ISession::state"/>)
612 </desc>
613 </const>
614 <const name="Open" value="2">
615 <desc>
616 The machine has an open direct session (<link to="IMachine::sessionState"/>);
617 the session is open (<link to="ISession::state"/>)
618 </desc>
619 </const>
620 <const name="Spawning" value="3">
621 <desc>
622 A new (direct) session is being opened for the machine
623 as a result of <link to="IVirtualBox::openRemoteSession"/>
624 call (<link to="IMachine::sessionState"/>);
625 the session is currently being opened
626 as a result of <link to="IVirtualBox::openRemoteSession"/>
627 call (<link to="ISession::state"/>)
628 </desc>
629 </const>
630 <const name="Closing" value="4">
631 <desc>
632 The direct session is being closed (<link to="IMachine::sessionState"/>);
633 the session is being closed (<link to="ISession::state"/>)
634 </desc>
635 </const>
636 </enum>
637
638 <enum
639 name="SessionType"
640 uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
641 >
642 <desc>
643 Session type. This enumeration represents possible values of the
644 <link to="ISession::type"/> attribute.
645 </desc>
646
647 <const name="Null" value="0">
648 <desc>Null value (never used by the API).</desc>
649 </const>
650 <const name="Direct" value="1">
651 <desc>
652 Direct session
653 (opened by <link to="IVirtualBox::openSession"/>)
654 </desc>
655 </const>
656 <const name="Remote" value="2">
657 <desc>
658 Remote session
659 (opened by <link to="IVirtualBox::openRemoteSession"/>)
660 </desc>
661 </const>
662 <const name="Existing" value="3">
663 <desc>
664 Existing session
665 (opened by <link to="IVirtualBox::openExistingSession"/>)
666 </desc>
667 </const>
668 </enum>
669
670 <enum
671 name="DeviceType"
672 uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
673 >
674 <desc>
675 Device type.
676 </desc>
677 <const name="Null" value="0">
678 <desc>
679 Null value, may also mean "no device" (not allowed for
680 <link to="IConsole::getDeviceActivity"/>).
681 </desc>
682 </const>
683 <const name="Floppy" value="1">
684 <desc>Floppy device.</desc>
685 </const>
686 <const name="DVD" value="2">
687 <desc>CD/DVD-ROM device.</desc>
688 </const>
689 <const name="HardDisk" value="3">
690 <desc>Hard disk device.</desc>
691 </const>
692 <const name="Network" value="4">
693 <desc>Network device.</desc>
694 </const>
695 <const name="USB" value="5">
696 <desc>USB device.</desc>
697 </const>
698 <const name="SharedFolder" value="6">
699 <desc>Shared folder device.</desc>
700 </const>
701 </enum>
702
703 <enum
704 name="DeviceActivity"
705 uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
706 >
707 <desc>
708 Device activity for <link to="IConsole::getDeviceActivity"/>.
709 </desc>
710
711 <const name="Null" value="0"/>
712 <const name="Idle" value="1"/>
713 <const name="Reading" value="2"/>
714 <const name="Writing" value="3"/>
715 </enum>
716
717 <enum
718 name="ClipboardMode"
719 uuid="33364716-4008-4701-8f14-be0fa3d62950"
720 >
721 <desc>
722 Host-Guest clipboard interchange mode.
723 </desc>
724
725 <const name="Disabled" value="0"/>
726 <const name="HostToGuest" value="1"/>
727 <const name="GuestToHost" value="2"/>
728 <const name="Bidirectional" value="3"/>
729 </enum>
730
731 <enum
732 name="Scope"
733 uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
734 >
735 <desc>
736 Scope of the operation.
737
738 A generic enumeration used in various methods to define the action or
739 argument scope.
740 </desc>
741
742 <const name="Global" value="0"/>
743 <const name="Machine" value="1"/>
744 <const name="Session" value="2"/>
745 </enum>
746
747 <enum
748 name="GuestStatisticType"
749 uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
750 >
751 <desc>
752 Statistics type for <link to="IGuest::getStatistic"/>.
753 </desc>
754
755 <const name="CPULoad_Idle" value="0">
756 <desc>
757 Idle CPU load (0-100%) for last interval.
758 </desc>
759 </const>
760 <const name="CPULoad_Kernel" value="1">
761 <desc>
762 Kernel CPU load (0-100%) for last interval.
763 </desc>
764 </const>
765 <const name="CPULoad_User" value="2">
766 <desc>
767 User CPU load (0-100%) for last interval.
768 </desc>
769 </const>
770 <const name="Threads" value="3">
771 <desc>
772 Total number of threads in the system.
773 </desc>
774 </const>
775 <const name="Processes" value="4">
776 <desc>
777 Total number of processes in the system.
778 </desc>
779 </const>
780 <const name="Handles" value="5">
781 <desc>
782 Total number of handles in the system.
783 </desc>
784 </const>
785 <const name="MemoryLoad" value="6">
786 <desc>
787 Memory load (0-100%).
788 </desc>
789 </const>
790 <const name="PhysMemTotal" value="7">
791 <desc>
792 Total physical memory in megabytes.
793 </desc>
794 </const>
795 <const name="PhysMemAvailable" value="8">
796 <desc>
797 Free physical memory in megabytes.
798 </desc>
799 </const>
800 <const name="PhysMemBalloon" value="9">
801 <desc>
802 Ballooned physical memory in megabytes.
803 </desc>
804 </const>
805 <const name="MemCommitTotal" value="10">
806 <desc>
807 Total amount of memory in the committed state in megabytes.
808 </desc>
809 </const>
810 <const name="MemKernelTotal" value="11">
811 <desc>
812 Total amount of memory used by the guest OS's kernel in megabytes.
813 </desc>
814 </const>
815 <const name="MemKernelPaged" value="12">
816 <desc>
817 Total amount of paged memory used by the guest OS's kernel in megabytes.
818 </desc>
819 </const>
820 <const name="MemKernelNonpaged" value="13">
821 <desc>
822 Total amount of non-paged memory used by the guest OS's kernel in megabytes.
823 </desc>
824 </const>
825 <const name="MemSystemCache" value="14">
826 <desc>
827 Total amount of memory used by the guest OS's system cache in megabytes.
828 </desc>
829 </const>
830 <const name="PageFileSize" value="15">
831 <desc>
832 Pagefile size in megabytes.
833 </desc>
834 </const>
835 <const name="SampleNumber" value="16">
836 <desc>
837 Statistics sample number
838 </desc>
839 </const>
840 <const name="MaxVal" value="17"/>
841 </enum>
842
843 <enum
844 name="BIOSBootMenuMode"
845 uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
846 >
847 <desc>
848 BIOS boot menu mode.
849 </desc>
850
851 <const name="Disabled" value="0"/>
852 <const name="MenuOnly" value="1"/>
853 <const name="MessageAndMenu" value="2"/>
854 </enum>
855
856 <enum
857 name="DriveState"
858 uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
859 >
860 <const name="Null" value="0">
861 <desc>Null value (never used by the API).</desc>
862 </const>
863 <const name="NotMounted" value="1"/>
864 <const name="ImageMounted" value="2"/>
865 <const name="HostDriveCaptured" value="3"/>
866 </enum>
867
868 <enum
869 name="ProcessorFeature"
870 uuid="b8353b35-705d-4796-9967-ebfb7ba54af4"
871 >
872 <desc>
873 CPU features.
874 </desc>
875
876 <const name="HWVirtEx" value="0"/>
877 <const name="PAE" value="1"/>
878 <const name="LongMode" value="2"/>
879 </enum>
880
881
882 <!--
883 // IVirtualBoxErrorInfo
884 /////////////////////////////////////////////////////////////////////////
885 -->
886
887 <interface
888 name="IVirtualBoxErrorInfo" extends="$errorinfo"
889 uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
890 supportsErrorInfo="no"
891 wsmap="suppress"
892 >
893 <desc>
894 The IVirtualBoxErrorInfo interface represents extended error information.
895
896 Extended error information can be set by VirtualBox components after
897 unsuccessful or partially successful method invocation. This information
898 can be retrieved by the calling party as an IVirtualBoxErrorInfo object
899 and then shown to the client in addition to the plain 32-bit result code.
900
901 In MS COM, this interface extends the IErrorInfo interface,
902 in XPCOM, it extends the nsIException interface. In both cases,
903 it provides a set of common attributes to retrieve error
904 information.
905
906 Sometimes invocation of some component's method may involve methods of
907 other components that may also fail (independently of this method's
908 failure), or a series of non-fatal errors may precede a fatal error that
909 causes method failure. In cases like that, it may be desirable to preserve
910 information about all errors happened during method invocation and deliver
911 it to the caller. The <link to="#next"/> attribute is intended
912 specifically for this purpose and allows to represent a chain of errors
913 through a single IVirtualBoxErrorInfo object set after method invocation.
914
915 Note that errors are stored to a chain in the reverse order, i.e. the
916 initial error object you query right after method invocation is the last
917 error set by the callee, the object it points to in the @a next attribute
918 is the previous error and so on, up to the first error (which is the last
919 in the chain).
920 </desc>
921
922 <attribute name="resultCode" type="result" readonly="yes">
923 <desc>
924 Result code of the error.
925 Usually, it will be the same as the result code returned
926 by the method that provided this error information, but not
927 always. For example, on Win32, CoCreateInstance() will most
928 likely return E_NOINTERFACE upon unsuccessful component
929 instantiation attempt, but not the value the component factory
930 returned.
931 <note>
932 In MS COM, there is no equivalent.
933 In XPCOM, it is the same as nsIException::result.
934 </note>
935 </desc>
936 </attribute>
937
938 <attribute name="interfaceID" type="uuid" readonly="yes">
939 <desc>
940 UUID of the interface that defined the error.
941 <note>
942 In MS COM, it is the same as IErrorInfo::GetGUID.
943 In XPCOM, there is no equivalent.
944 </note>
945 </desc>
946 </attribute>
947
948 <attribute name="component" type="wstring" readonly="yes">
949 <desc>
950 Name of the component that generated the error.
951 <note>
952 In MS COM, it is the same as IErrorInfo::GetSource.
953 In XPCOM, there is no equivalent.
954 </note>
955 </desc>
956 </attribute>
957
958 <attribute name="text" type="wstring" readonly="yes">
959 <desc>
960 Text description of the error.
961 <note>
962 In MS COM, it is the same as IErrorInfo::GetDescription.
963 In XPCOM, it is the same as nsIException::message.
964 </note>
965 </desc>
966 </attribute>
967
968 <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
969 <desc>
970 Next error object if there is any, or @c null otherwise.
971 <note>
972 In MS COM, there is no equivalent.
973 In XPCOM, it is the same as nsIException::inner.
974 </note>
975 </desc>
976 </attribute>
977
978 </interface>
979
980
981 <!--
982 // IVirtualBox
983 /////////////////////////////////////////////////////////////////////////
984 -->
985
986 <interface
987 name="IVirtualBoxCallback" extends="$unknown"
988 uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
989 wsmap="suppress"
990 >
991 <method name="onMachineStateChange">
992 <desc>
993 The execution state of the given machine has changed.
994 <see>IMachine::state</see>
995 </desc>
996 <param name="machineId" type="uuid" dir="in">
997 <desc>ID of the machine this event relates to.</desc>
998 </param>
999 <param name="state" type="MachineState" dir="in">
1000 <desc>New execution state.</desc>
1001 </param>
1002 </method>
1003
1004 <method name="onMachineDataChange">
1005 <desc>
1006 Any of the settings of the given machine has changed.
1007 </desc>
1008 <param name="machineId" type="uuid" dir="in">
1009 <desc>ID of the machine this event relates to.</desc>
1010 </param>
1011 </method>
1012
1013 <method name="onExtraDataCanChange">
1014 <desc>
1015 Notification when someone tries to change extra data for
1016 either the given machine or (if null) global extra data.
1017 This gives the chance to veto against changes.
1018 </desc>
1019 <param name="machineId" type="uuid" dir="in">
1020 <desc>
1021 ID of the machine this event relates to
1022 (null ID for global extra data change requests).
1023 </desc>
1024 </param>
1025 <param name="key" type="wstring" dir="in">
1026 <desc>
1027 Extra data key for the attempted write.
1028 </desc>
1029 </param>
1030 <param name="value" type="wstring" dir="in">
1031 <desc>
1032 Extra data value for the given key.
1033 </desc>
1034 </param>
1035 <param name="error" type="wstring" dir="out">
1036 <desc>
1037 Optional error message describing the reason of the
1038 veto (ignored if this notification returns @c true).
1039 </desc>
1040 </param>
1041 <param name="allowChange" type="boolean" dir="return">
1042 <desc>
1043 Flag to indicate whether the callee agrees (@c true)
1044 or vetoes against the change (@c false).
1045 </desc>
1046 </param>
1047 </method>
1048
1049 <method name="onExtraDataChange">
1050 <desc>
1051 Notification when machine specific or global extra data
1052 has changed.
1053 </desc>
1054 <param name="machineId" type="uuid" dir="in">
1055 <desc>
1056 ID of the machine this event relates to.
1057 Null for global extra data changes.
1058 </desc>
1059 </param>
1060 <param name="key" type="wstring" dir="in">
1061 <desc>
1062 Extra data key that has changed.
1063 </desc>
1064 </param>
1065 <param name="value" type="wstring" dir="in">
1066 <desc>
1067 Extra data value for the given key.
1068 </desc>
1069 </param>
1070 </method>
1071
1072 <method name="onMediaRegistered">
1073 <desc>
1074 The given media was registered or unregistered
1075 within this VirtualBox installation.
1076
1077 The @a mediaType parameter describes what type of
1078 media the specified @a mediaId refers to. Possible
1079 values are:
1080
1081 <ul>
1082 <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
1083 that, if registered, can be obtained using the
1084 <link to="IVirtualBox::getHardDisk"/> call.</li>
1085 <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
1086 that, if registered, can be obtained using the
1087 <link to="IVirtualBox::getDVDImage"/> call.</li>
1088 <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
1089 that, if registered, can be obtained using the
1090 <link to="IVirtualBox::getFloppyImage"/> call.</li>
1091 </ul>
1092
1093 Note that if this is a deregistration notification,
1094 there is no way to access the object representing the
1095 unregistered media. It is supposed that the
1096 application will do required cleanup based on the
1097 @a mediaId value.
1098 </desc>
1099 <param name="mediaId" type="uuid" dir="in">
1100 <desc>ID of the media this event relates to.</desc>
1101 </param>
1102 <param name="mediaType" type="DeviceType" dir="in">
1103 <desc>Type of the media this event relates to.</desc>
1104 </param>
1105 <param name="registered" type="boolean" dir="in">
1106 <desc>
1107 If true, the media was registered, otherwise it was
1108 unregistered.
1109 </desc>
1110 </param>
1111 </method>
1112
1113 <method name="onMachineRegistered">
1114 <desc>
1115 The given machine was registered or unregistered
1116 within this VirtualBox installation.
1117 </desc>
1118 <param name="machineId" type="uuid" dir="in">
1119 <desc>ID of the machine this event relates to.</desc>
1120 </param>
1121 <param name="registered" type="boolean" dir="in">
1122 <desc>
1123 If true, the machine was registered, otherwise it was
1124 unregistered.
1125 </desc>
1126 </param>
1127 </method>
1128
1129 <method name="onSessionStateChange">
1130 <desc>
1131 The state of the session for the given machine was changed.
1132 <see>IMachine::sessionState</see>
1133 </desc>
1134 <param name="machineId" type="uuid" dir="in">
1135 <desc>ID of the machine this event relates to.</desc>
1136 </param>
1137 <param name="state" type="SessionState" dir="in">
1138 <desc>New session state.</desc>
1139 </param>
1140 </method>
1141
1142 <method name="onSnapshotTaken">
1143 <desc>
1144 A new snapshot of the machine has been taken.
1145 <see>ISnapshot</see>
1146 </desc>
1147 <param name="machineId" type="uuid" dir="in">
1148 <desc>ID of the machine this event relates to.</desc>
1149 </param>
1150 <param name="snapshotId" type="uuid" dir="in">
1151 <desc>ID of the new snapshot.</desc>
1152 </param>
1153 </method>
1154
1155 <method name="onSnapshotDiscarded">
1156 <desc>
1157 Snapshot of the given machine has been discarded.
1158
1159 <note>
1160 This notification is delivered <b>after</b> the snapshot
1161 object has been uninitialized on the server (so that any
1162 attempt to call its methods will return an error).
1163 </note>
1164
1165 <see>ISnapshot</see>
1166 </desc>
1167 <param name="machineId" type="uuid" dir="in">
1168 <desc>ID of the machine this event relates to.</desc>
1169 </param>
1170 <param name="snapshotId" type="uuid" dir="in">
1171 <desc>
1172 ID of the discarded snapshot. <tt>null</tt> means the
1173 current machine state has been discarded (restored from
1174 the current snapshot).
1175 </desc>
1176 </param>
1177 </method>
1178
1179 <method name="onSnapshotChange">
1180 <desc>
1181 Snapshot properties (name and/or description) have been changed.
1182 <see>ISnapshot</see>
1183 </desc>
1184 <param name="machineId" type="uuid" dir="in">
1185 <desc>ID of the machine this event relates to.</desc>
1186 </param>
1187 <param name="snapshotId" type="uuid" dir="in">
1188 <desc>ID of the changed snapshot.</desc>
1189 </param>
1190 </method>
1191
1192 <method name="onGuestPropertyChange">
1193 <desc>
1194 Notification when a guest property has changed.
1195 </desc>
1196 <param name="machineId" type="uuid" dir="in">
1197 <desc>
1198 ID of the machine this event relates to.
1199 </desc>
1200 </param>
1201 <param name="name" type="wstring" dir="in">
1202 <desc>
1203 The name of the property that has changed.
1204 </desc>
1205 </param>
1206 <param name="value" type="wstring" dir="in">
1207 <desc>
1208 The new property value.
1209 </desc>
1210 </param>
1211 <param name="flags" type="wstring" dir="in">
1212 <desc>
1213 The new property flags.
1214 </desc>
1215 </param>
1216 </method>
1217
1218 </interface>
1219
1220 <interface
1221 name="IDHCPServer" extends="$unknown"
1222 uuid="fab58256-c76e-4ddd-8029-18343e5b0069"
1223 wsmap="managed"
1224 >
1225 <desc>
1226 The IDHCPServer interface represents the vbox dhcp server configuration.
1227
1228 To enumerate all the dhcp servers on the host, use the
1229 <link to="IVirtualBox::DHCPServers"/> attribute.
1230 </desc>
1231
1232 <attribute name="enabled" type="boolean">
1233 <desc>
1234 specifies if the dhcp server is enabled
1235 </desc>
1236 </attribute>
1237
1238 <attribute name="IPAddress" type="wstring" readonly="yes">
1239 <desc>
1240 specifies server IP
1241 </desc>
1242 </attribute>
1243
1244 <attribute name="networkMask" type="wstring" readonly="yes">
1245 <desc>
1246 specifies server network mask
1247 </desc>
1248 </attribute>
1249
1250 <attribute name="networkName" type="wstring" readonly="yes">
1251 <desc>
1252 specifies internal network name the server is used for
1253 </desc>
1254 </attribute>
1255
1256 <attribute name="lowerIP" type="wstring" readonly="yes">
1257 <desc>
1258 specifies from IP adrres in server address range
1259 </desc>
1260 </attribute>
1261
1262 <attribute name="upperIP" type="wstring" readonly="yes">
1263 <desc>
1264 specifies to IP adrres in server address range
1265 </desc>
1266 </attribute>
1267
1268 <method name="setConfiguration">
1269 <desc>
1270 configures the server
1271 <result name="E_INVALIDARG">
1272 invalid configuration supplied
1273 </result>
1274 </desc>
1275 <param name="IPAddress" type="wstring" dir="in">
1276 <desc>
1277 server IP address
1278 </desc>
1279 </param>
1280 <param name="networkMask" type="wstring" dir="in">
1281 <desc>
1282 server network mask
1283 </desc>
1284 </param>
1285 <param name="FromIPAddress" type="wstring" dir="in">
1286 <desc>
1287 server From IP address for address range
1288 </desc>
1289 </param>
1290 <param name="ToIPAddress" type="wstring" dir="in">
1291 <desc>
1292 server To IP address for address range
1293 </desc>
1294 </param>
1295 </method>
1296 </interface>
1297
1298 <interface
1299 name="IVirtualBox" extends="$dispatched"
1300 uuid="779264f4-65ed-48ed-be39-518ca549e296"
1301 wsmap="managed"
1302 >
1303 <desc>
1304 The IVirtualBox interface represents the main interface exposed by the
1305 product that provides virtual machine management.
1306
1307 An instance of IVirtualBox is required for the product to do anything
1308 useful. Even though the interface does not expose this, internally,
1309 IVirtualBox is implemented as a singleton and actually lives in the
1310 process of the VirtualBox server (VBoxSVC.exe). This makes sure that
1311 IVirtualBox can track the state of all virtual machines on a particular
1312 host, regardless of which frontend started them.
1313
1314 To enumerate all the virtual machines on the host, use the
1315 <link to="IVirtualBox::machines"/> attribute.
1316 </desc>
1317
1318 <attribute name="version" type="wstring" readonly="yes">
1319 <desc>
1320 A string representing the version number of the product. The
1321 format is 3 integer numbers divided by dots (e.g. 1.0.1). The
1322 last number represents the build number and will frequently change.
1323 </desc>
1324 </attribute>
1325
1326 <attribute name="revision" type="unsigned long" readonly="yes">
1327 <desc>
1328 The internal build revision number of the product.
1329 </desc>
1330 </attribute>
1331
1332 <attribute name="packageType" type="wstring" readonly="yes">
1333 <desc>
1334 A string representing the package type of this product. The
1335 format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
1336 SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
1337 is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
1338 this.
1339 </desc>
1340 </attribute>
1341
1342 <attribute name="homeFolder" type="wstring" readonly="yes">
1343 <desc>
1344 Full path to the directory where the global settings file,
1345 <tt>VirtualBox.xml</tt>, is stored.
1346
1347 In this version of VirtualBox, the value of this property is
1348 always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
1349 <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
1350 as determined by the host OS), and cannot be changed.
1351
1352 This path is also used as the base to resolve relative paths in
1353 places where relative paths are allowed (unless otherwise
1354 expressly indicated).
1355 </desc>
1356 </attribute>
1357
1358 <attribute name="settingsFilePath" type="wstring" readonly="yes">
1359 <desc>
1360 Full name of the global settings file.
1361 The value of this property corresponds to the value of
1362 <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
1363 </desc>
1364 </attribute>
1365
1366 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
1367 <desc>
1368 Current version of the format of the global VirtualBox settings file
1369 (<tt>VirtualBox.xml</tt>).
1370
1371 The version string has the following format:
1372 <pre>
1373 x.y-platform
1374 </pre>
1375 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1376 versions, and <tt>platform</tt> is the platform identifier.
1377
1378 The current version usually matches the value of the
1379 <link to="#settingsFormatVersion"/> attribute unless the
1380 settings file was created by an older version of VirtualBox and there
1381 was a change of the settings file format since then.
1382
1383 Note that VirtualBox automatically converts settings files from older
1384 versions to the most recent version when reading them (usually at
1385 VirtualBox startup) but it doesn't save the changes back until
1386 you call a method that implicitly saves settings (such as
1387 <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
1388 explicitly. Therefore, if the value of this attribute differs from the
1389 value of <link to="#settingsFormatVersion"/>, then it
1390 means that the settings file was converted but the result of the
1391 conversion is not yet saved to disk.
1392
1393 The above feature may be used by interactive front-ends to inform users
1394 about the settings file format change and offer them to explicitly save
1395 all converted settings files (the global and VM-specific ones),
1396 optionally create backup copies of the old settings files before saving,
1397 etc.
1398
1399 <see>settingsFormatVersion, saveSettingsWithBackup()</see>
1400 </desc>
1401 </attribute>
1402
1403 <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
1404 <desc>
1405 Most recent version of the settings file format.
1406
1407 The version string has the following format:
1408 <pre>
1409 x.y-platform
1410 </pre>
1411 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1412 versions, and <tt>platform</tt> is the platform identifier.
1413
1414 VirtualBox uses this version of the format when saving settings files
1415 (either as a result of method calls that require to save settings or as
1416 a result of an explicit call to <link to="#saveSettings"/>).
1417
1418 <see>settingsFileVersion</see>
1419 </desc>
1420 </attribute>
1421
1422 <attribute name="host" type="IHost" readonly="yes">
1423 <desc>Associated host object.</desc>
1424 </attribute>
1425
1426 <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1427 <desc>Associated system information object.</desc>
1428 </attribute>
1429
1430 <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
1431 <desc>
1432 Array of machine objects registered within this VirtualBox instance.
1433 </desc>
1434 </attribute>
1435
1436 <attribute name="hardDisks" type="IHardDisk" readonly="yes" safearray="yes">
1437 <desc>
1438 Array of hard disk objects known to this VirtualBox installation.
1439
1440 This array contains only base (root) hard disks. All differencing
1441 hard disks of the given base hard disk can be enumerated using
1442 <link to="IHardDisk::children"/>.
1443 </desc>
1444 </attribute>
1445
1446 <attribute name="DVDImages" type="IDVDImage" readonly="yes" safearray="yes">
1447 <desc>
1448 Array of CD/DVD image objects registered with this VirtualBox instance.
1449 </desc>
1450 </attribute>
1451
1452 <attribute name="floppyImages" type="IFloppyImage" readonly="yes" safearray="yes">
1453 <desc>
1454 Array of floppy image objects registered with this VirtualBox instance.
1455 </desc>
1456 </attribute>
1457
1458 <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
1459
1460 <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
1461
1462 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
1463 <desc>
1464 Collection of global shared folders. Global shared folders are
1465 available to all virtual machines.
1466
1467 New shared folders are added to the collection using
1468 <link to="#createSharedFolder"/>. Existing shared folders can be
1469 removed using <link to="#removeSharedFolder"/>.
1470
1471 <note>
1472 In the current version of the product, global shared folders are not
1473 implemented and therefore this collection is always empty.
1474 </note>
1475 </desc>
1476 </attribute>
1477
1478 <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1479 <desc>
1480 Associated performance collector object.
1481 </desc>
1482 </attribute>
1483
1484 <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
1485 <desc>
1486 dhcp server settings.
1487 </desc>
1488 </attribute>
1489
1490 <method name="createMachine">
1491 <desc>
1492 Creates a new virtual machine.
1493
1494 The new machine is created unregistered, with the initial configuration
1495 set according to the specified guest OS type. A typical sequence of
1496 actions to create a new virtual machine is as follows:
1497
1498 <ol>
1499 <li>
1500 Call this method to have a new machine created. The returned machine
1501 object will be "mutable" allowing to change any machine property.
1502 </li>
1503
1504 <li>
1505 Configure the machine using the appropriate attributes and methods.
1506 </li>
1507
1508 <li>
1509 Call <link to="IMachine::saveSettings" /> to write the settings
1510 to the machine's XML settings file. The configuration of the newly
1511 created machine will not be saved to disk until this method is
1512 called.
1513 </li>
1514
1515 <li>
1516 Call <link to="#registerMachine" /> to add the machine to the list
1517 of machines known to VirtualBox.
1518 </li>
1519 </ol>
1520
1521 You should specify valid name for the newly created machine when calling
1522 this method. See the <link to="IMachine::name"/> attribute description
1523 for more details about the machine name.
1524
1525 The specified guest OS type identifier must match an ID of one of known
1526 guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
1527 array.
1528
1529 Every machine has a <i>settings file</i> that is used to store
1530 the machine configuration. This file is stored in a directory called the
1531 <i>machine settings subfolder</i>. Both the settings subfolder and file
1532 will have a name that corresponds to the name of the virtual machine.
1533 You can specify where to create the machine setting subfolder using the
1534 @a baseFolder argument. The base folder can be absolute (full path) or
1535 relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
1536 directory</link>.
1537
1538 If @a baseFolder is a null or empty string (which is recommended), the
1539 <link to="ISystemProperties::defaultMachineFolder">default machine
1540 settings folder</link> will be used as a base folder for the created
1541 machine. Otherwise the given base folder will be used. In either case,
1542 the full path to the resulting settings file has the following
1543 structure:
1544 <pre>
1545 &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml
1546 </pre>
1547
1548 Note that if the resulting settings file already exists, this method
1549 will fail with <link to="VBOX_E_FILE_ERROR"/>.
1550
1551 Optionally, you may specify an UUID of to assign to the created machine.
1552 However, this is not recommended and you should normally pass an empty
1553 (null) UUID to this method so that a new UUID will be automatically
1554 generated for every created machine. You can use UUID
1555 00000000-0000-0000-0000-000000000000 as null value.
1556
1557 <note>
1558 There is no way to change the name of the settings file or
1559 subfolder of the created machine directly.
1560 </note>
1561
1562 <result name="VBOX_E_OBJECT_NOT_FOUND">
1563 @a osTypeId is invalid.
1564 </result>
1565 <result name="VBOX_E_FILE_ERROR">
1566 Resulting settings file name is invalid or the settings file already
1567 exists or could not be created due to an I/O error.
1568 </result>
1569 <result name="E_INVALIDARG">
1570 @a name is empty or null.
1571 </result>
1572 </desc>
1573
1574 <param name="name" type="wstring" dir="in">
1575 <desc>Machine name.</desc>
1576 </param>
1577 <param name="osTypeId" type="wstring" dir="in">
1578 <desc>Guest OS Type ID.</desc>
1579 </param>
1580 <param name="baseFolder" type="wstring" dir="in">
1581 <desc>Base machine folder (optional).</desc>
1582 </param>
1583 <param name="id" type="uuid" dir="in">
1584 <desc>Machine UUID (optional).</desc>
1585 </param>
1586 <param name="machine" type="IMachine" dir="return">
1587 <desc>Created machine object.</desc>
1588 </param>
1589 </method>
1590
1591 <method name="createLegacyMachine">
1592 <desc>
1593 Creates a new virtual machine in "legacy" mode, using the specified
1594 settings file to store machine settings.
1595
1596 As opposed to machines created by <link to="#createMachine"/>,
1597 the settings file of the machine created in "legacy" mode is not
1598 automatically renamed when the machine name is changed -- it will always
1599 remain the same as specified in this method call.
1600
1601 The specified settings file name can be absolute (full path) or relative
1602 to the <link to="IVirtualBox::homeFolder">VirtualBox home
1603 directory</link>. If the file name doesn't contain an extension, the
1604 default extension (.xml) will be appended.
1605
1606 Note that the configuration of the newly created machine is not
1607 saved to disk (and therefore no settings file is created)
1608 until <link to="IMachine::saveSettings"/> is called. If the
1609 specified settings file already exists, this method
1610 will fail with <link to="VBOX_E_FILE_ERROR"/>..
1611
1612 See <link to="#createMachine"/> for more information.
1613
1614 @deprecated This method may be removed later. Use <link
1615 to="IVirtualBox::createMachine"/> instead.
1616
1617 <note>
1618 There is no way to change the name of the settings file
1619 of the machine created in "legacy" mode.
1620 </note>
1621
1622 <result name="VBOX_E_OBJECT_NOT_FOUND">
1623 @a osTypeId is invalid.
1624 </result>
1625 <result name="VBOX_E_FILE_ERROR">
1626 @a settingsFile is invalid or the settings file already exists or
1627 could not be created due to an I/O error.
1628 </result>
1629 <result name="E_INVALIDARG">
1630 @a name or @a settingsFile is empty or null.
1631 </result>
1632 </desc>
1633
1634 <param name="name" type="wstring" dir="in">
1635 <desc>Machine name.</desc>
1636 </param>
1637 <param name="osTypeId" type="wstring" dir="in">
1638 <desc>Machine OS Type ID.</desc>
1639 </param>
1640 <param name="settingsFile" type="wstring" dir="in">
1641 <desc>Name of the machine settings file.</desc>
1642 </param>
1643 <param name="id" type="uuid" dir="in">
1644 <desc>Machine UUID (optional).</desc>
1645 </param>
1646 <param name="machine" type="IMachine" dir="return">
1647 <desc>Created machine object.</desc>
1648 </param>
1649 </method>
1650
1651 <method name="openMachine">
1652 <desc>
1653 Opens a virtual machine from the existing settings file.
1654 The opened machine remains unregistered until you call
1655 <link to="#registerMachine"/>.
1656
1657 The specified settings file name can be absolute
1658 (full path) or relative to the <link to="IVirtualBox::homeFolder">
1659 VirtualBox home directory</link>. This file must exist
1660 and must be a valid machine settings file whose contents
1661 will be used to construct the machine object.
1662
1663 @deprecated Will be removed soon.
1664 <result name="VBOX_E_FILE_ERROR">
1665 Settings file name invalid, not found or sharing violation.
1666 </result>
1667 </desc>
1668 <param name="settingsFile" type="wstring" dir="in">
1669 <desc>
1670 Name of the machine settings file.
1671 </desc>
1672 </param>
1673 <param name="machine" type="IMachine" dir="return">
1674 <desc>Opened machine object.</desc>
1675 </param>
1676 <note>
1677 <link to="IMachine::settingsModified"/> will return
1678 false for the created machine, until any of machine settings
1679 are changed.
1680 </note>
1681 </method>
1682
1683 <method name="registerMachine">
1684 <desc>
1685
1686 Registers the machine previously created using
1687 <link to="#createMachine"/> or opened using
1688 <link to="#openMachine"/> within this VirtualBox installation. After
1689 successful method invocation, the
1690 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1691 to all registered callbacks.
1692
1693 <note>
1694 This method implicitly calls <link to="IMachine::saveSettings"/>
1695 to save all current machine settings before registering it.
1696 </note>
1697
1698 <result name="VBOX_E_OBJECT_NOT_FOUND">
1699 No matching virtual machine found.
1700 </result>
1701 <result name="VBOX_E_INVALID_OBJECT_STATE">
1702 Virtual machine was not created within this VirtualBox instance.
1703 </result>
1704
1705 </desc>
1706 <param name="machine" type="IMachine" dir="in"/>
1707 </method>
1708
1709 <method name="getMachine">
1710 <desc>
1711 Attempts to find a virtual machine given its UUID.
1712 To look up a machine by name, use <link to="IVirtualBox::findMachine" />
1713 instead.
1714
1715 <result name="VBOX_E_OBJECT_NOT_FOUND">
1716 Could not find registered machine matching @a id.
1717 </result>
1718
1719 </desc>
1720 <param name="id" type="uuid" dir="in"/>
1721 <param name="machine" type="IMachine" dir="return"/>
1722 </method>
1723
1724 <method name="findMachine">
1725 <desc>
1726 Attempts to find a virtual machine given its name.
1727 To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
1728 instead.
1729
1730 <result name="VBOX_E_OBJECT_NOT_FOUND">
1731 Could not find registered machine matching @a name.
1732 </result>
1733
1734 </desc>
1735 <param name="name" type="wstring" dir="in"/>
1736 <param name="machine" type="IMachine" dir="return"/>
1737 </method>
1738
1739 <method name="unregisterMachine">
1740 <desc>
1741
1742 Unregisters the machine previously registered using
1743 <link to="#registerMachine"/>. After successful method invocation, the
1744 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1745 to all registered callbacks.
1746
1747 <note>
1748 The specified machine must not be in the Saved state, have an open
1749 (or a spawning) direct session associated with it, have snapshots or
1750 have hard disks attached.
1751 </note>
1752
1753 <note>
1754 This method implicitly calls <link to="IMachine::saveSettings"/> to
1755 save all current machine settings before unregistering it.
1756 </note>
1757
1758 <note>
1759 If the given machine is inaccessible (see
1760 <link to="IMachine::accessible"/>), it will be unregistered and
1761 fully uninitialized right afterwards. As a result, the returned
1762 machine object will be unusable and an attempt to call
1763 <b>any</b> method will return the "Object not ready" error.
1764 </note>
1765
1766 <result name="VBOX_E_OBJECT_NOT_FOUND">
1767 Could not find registered machine matching @a id.
1768 </result>
1769 <result name="VBOX_E_INVALID_VM_STATE">
1770 Machine is in Saved state.
1771 </result>
1772 <result name="VBOX_E_INVALID_OBJECT_STATE">
1773 Machine has snapshot or open session or hard disk attached.
1774 </result>
1775
1776 </desc>
1777 <param name="id" type="uuid" dir="in">
1778 <desc>UUID of the machine to unregister.</desc>
1779 </param>
1780 <param name="machine" type="IMachine" dir="return">
1781 <desc>Unregistered machine object.</desc>
1782 </param>
1783 </method>
1784
1785 <method name="createAppliance">
1786 <desc>
1787 Creates a new appliance object, which represents an appliance in the Open Virtual Machine
1788 Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
1789 machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
1790 </desc>
1791 <param name="appliance" type="IAppliance" dir="return">
1792 <desc>New appliance.</desc>
1793 </param>
1794 </method>
1795
1796 <method name="createHardDisk">
1797 <desc>
1798 Creates a new base hard disk object that will use the given storage
1799 format and location for hard disk data.
1800
1801 Note that the actual storage unit is not created by this method. In
1802 order to do it, and before you are able to attach the created hard disk
1803 to virtual machines, you must call one of the following methods to
1804 allocate a format-specific storage unit at the specified location:
1805 <ul>
1806 <li><link to="IHardDisk::createBaseStorage"/></li>
1807 <li><link to="IHardDisk::createDiffStorage"/></li>
1808 </ul>
1809
1810 Some hard disk attributes, such as <link to="IHardDisk::id"/>, may
1811 remain uninitialized until the hard disk storage unit is successfully
1812 created by one of the above methods.
1813
1814 After the storage unit is successfully created, the hard disk gets
1815 remembered by this VirtualBox installation and will be accessible
1816 through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
1817 methods. Remembered root (base) hard disks are also returned as part of
1818 the <link to="#hardDisks"/> array. See IHardDisk for more details.
1819
1820 The list of all storage formats supported by this VirtualBox
1821 installation can be obtained using
1822 <link to="ISystemProperties::hardDiskFormats"/>. If the @a format
1823 attribute is empty or <tt>null</tt> then the default storage format
1824 specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
1825 be used for creating a storage unit of the hard disk.
1826
1827 Note that the format of the location string is storage format specific.
1828 See <link to="IMedium::location"/>, IHardDisk and
1829 <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1830
1831 <result name="VBOX_E_OBJECT_NOT_FOUND">
1832 @a format identifier is invalid. See
1833 <link to="ISystemProperties::hardDiskFormats"/>.
1834 </result>
1835 <result name="VBOX_E_FILE_ERROR">
1836 @a location is a not valid file name (for file-based formats only).
1837 </result>
1838 <result name="E_INVALIDARG">
1839 @a format is a null or empty string.
1840 </result>
1841 </desc>
1842 <param name="format" type="wstring" dir="in">
1843 <desc>
1844 Identifier of the storage format to use for the new hard disk.
1845 </desc>
1846 </param>
1847 <param name="location" type="wstring" dir="in">
1848 <desc>
1849 Location of the storage unit for the new hard disk.
1850 </desc>
1851 </param>
1852 <param name="hardDisk" type="IHardDisk" dir="return">
1853 <desc>Created hard disk object.</desc>
1854 </param>
1855 </method>
1856
1857 <method name="openHardDisk">
1858 <desc>
1859 Opens a hard disk from an existing location.
1860
1861 After the hard disk is successfully opened by this method, it gets
1862 remembered by (known to) this VirtualBox installation and will be
1863 accessible through <link to="#getHardDisk"/> and
1864 <link to="#findHardDisk"/> methods. Remembered root (base) hard disks
1865 are also returned as part of the <link to="#hardDisks"/> array and can
1866 be attached to virtual machines. See IHardDisk for more details.
1867
1868 If a differencing hard disk is to be opened by this method, the
1869 operation will succeed only if its parent hard disk and all ancestors,
1870 if any, are already known to this VirtualBox installation (for example,
1871 were opened by this method before).
1872
1873 This method tries to guess the storage format of the specified hard disk
1874 by reading hard disk data at the specified location.
1875
1876 If @write is true, the image is opened for read/write access and must
1877 have according permissions, as VirtualBox may actually write status
1878 information into the disk's metadata sections. Note that write access
1879 is required for all typical image usage in VirtualBox, since VirtualBox
1880 may need to write metadata such as a UUID into the image. The only
1881 exception is opening a source image temporarily for copying and
1882 cloning when the image will quickly be closed againl.
1883
1884 Note that the format of the location string is storage format specific.
1885 See <link to="IMedium::location"/>, IHardDisk and
1886 <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
1887
1888 <result name="VBOX_E_FILE_ERROR">
1889 Invalid hard disk storage file location.
1890 </result>
1891 <result name="VBOX_E_IPRT_ERROR">
1892 Could not get hard disk storage format.
1893 </result>
1894 <result name="E_INVALIDARG">
1895 Invalid hard disk storage format.
1896 </result>
1897
1898 </desc>
1899 <param name="location" type="wstring" dir="in">
1900 <desc>
1901 Location of the storage unit that contains hard disk data in one of
1902 the supported storage formats.
1903 </desc>
1904 </param>
1905 <param name="write" type="boolean" dir="in">
1906 <desc>
1907 If true, opens for read/write access. If false, opens for read access only.
1908 </desc>
1909 </param>
1910 <param name="hardDisk" type="IHardDisk" dir="return">
1911 <desc>Opened hard disk object.</desc>
1912 </param>
1913 </method>
1914
1915 <method name="getHardDisk" const="yes">
1916 <desc>
1917 Returns a hard disk with the given UUID.
1918
1919 The hard disk with the given UUID must be known to this VirtualBox
1920 installation, i.e. it must be previously created by
1921 <link to="#createHardDisk"/> or opened by <link
1922 to="#openHardDisk"/>, or attached to some known virtual machine.
1923
1924 <result name="VBOX_E_OBJECT_NOT_FOUND">
1925 No hard disk object matching @a id found.
1926 </result>
1927
1928 </desc>
1929 <param name="id" type="uuid" dir="in">
1930 <desc>UUID of the hard disk to look for.</desc>
1931 </param>
1932 <param name="hardDisk" type="IHardDisk" dir="return">
1933 <desc>Found hard disk object.</desc>
1934 </param>
1935 </method>
1936
1937 <method name="findHardDisk">
1938 <desc>
1939 Returns a hard disk that uses the given location to store hard
1940 disk data.
1941
1942 The given hard disk must be known to this VirtualBox installation, i.e.
1943 it must be previously created by
1944 <link to="#createHardDisk"/> or opened by <link
1945 to="#openHardDisk"/>, or attached to some known virtual machine.
1946
1947 The search is done by comparing the value of the @a location argument to
1948 the <link to="IHardDisk::location"/> attribute of each known hard
1949 disk.
1950
1951 For locations represented by file names in the host's file system, the
1952 requested location can be a path relative to the
1953 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
1954 only a file name without any path is given, the
1955 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
1956 folder</link> will be prepended to the file name before searching. Note
1957 that on case sensitive file systems, a case sensitive comparison is
1958 performed, otherwise the case of symbols in the file path is ignored.
1959
1960 <result name="VBOX_E_OBJECT_NOT_FOUND">
1961 No hard disk object matching @a location found.
1962 </result>
1963
1964 </desc>
1965 <param name="location" type="wstring" dir="in">
1966 <desc>Location string to search for.</desc>
1967 </param>
1968 <param name="hardDisk" type="IHardDisk" dir="return">
1969 <desc>Found hard disk object.</desc>
1970 </param>
1971 </method>
1972
1973 <method name="openDVDImage">
1974 <desc>
1975 Opens a CD/DVD image contained in the specified file of the supported
1976 format and assigns it the given UUID.
1977
1978 After the image is successfully opened by this method, it gets
1979 remembered by (known to) this VirtualBox installation and will be
1980 accessible through <link to="#getDVDImage"/> and
1981 <link to="#findDVDImage"/> methods. Remembered images are also
1982 returned as part of the <link to="#DVDImages"/> array and can be mounted
1983 to virtual machines. See IMedium for more details.
1984
1985 See <link to="IMedium::location"/> to get more details about the format
1986 of the location string.
1987
1988 <note>
1989 Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
1990 </note>
1991
1992 <result name="VBOX_E_INVALID_OBJECT_STATE">
1993 CD/DVD image already exists in the media registry.
1994 </result>
1995
1996 </desc>
1997 <param name="location" type="wstring" dir="in">
1998 <desc>
1999 Full path to the file that contains a valid CD/DVD image.
2000 </desc>
2001 </param>
2002 <param name="id" type="uuid" dir="in">
2003 <desc>
2004 UUID to assign to the given image within this VirtualBox installation.
2005 If an empty (null) UUID is specified, the system will randomly
2006 generate a new UUID.
2007 </desc>
2008 </param>
2009 <param name="image" type="IDVDImage" dir="return">
2010 <desc>Opened CD/DVD image object.</desc>
2011 </param>
2012 </method>
2013
2014 <method name="getDVDImage">
2015 <desc>
2016 Returns a CD/DVD image with the given UUID.
2017
2018 The image with the given UUID must be known to this VirtualBox
2019 installation, i.e. it must be previously opened by <link
2020 to="#openDVDImage"/>, or mounted to some known virtual machine.
2021
2022 <result name="VBOX_E_OBJECT_NOT_FOUND">
2023 No matching DVD image found in the media registry.
2024 </result>
2025
2026 </desc>
2027 <param name="id" type="uuid" dir="in">
2028 <desc>UUID of the image to look for.</desc>
2029 </param>
2030 <param name="image" type="IDVDImage" dir="return">
2031 <desc>Found CD/DVD image object.</desc>
2032 </param>
2033 </method>
2034
2035 <method name="findDVDImage">
2036 <desc>
2037 Returns a CD/DVD image with the given image location.
2038
2039 The image with the given UUID must be known to this VirtualBox
2040 installation, i.e. it must be previously opened by <link
2041 to="#openDVDImage"/>, or mounted to some known virtual machine.
2042
2043 The search is done by comparing the value of the @a location argument to
2044 the <link to="IMedium::location"/> attribute of each known CD/DVD image.
2045
2046 The requested location can be a path relative to the
2047 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2048 only a file name without any path is given, the
2049 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2050 folder</link> will be prepended to the file name before searching. Note
2051 that on case sensitive file systems, a case sensitive comparison is
2052 performed, otherwise the case in the file path is ignored.
2053
2054 <result name="VBOX_E_FILE_ERROR">
2055 Invalid image file location.
2056 </result>
2057 <result name="VBOX_E_OBJECT_NOT_FOUND">
2058 No matching DVD image found in the media registry.
2059 </result>
2060
2061 </desc>
2062 <param name="location" type="wstring" dir="in">
2063 <desc>CD/DVD image file path to look for.</desc>
2064 </param>
2065 <param name="image" type="IDVDImage" dir="return">
2066 <desc>Found CD/DVD image object.</desc>
2067 </param>
2068 </method>
2069
2070 <method name="openFloppyImage">
2071 <desc>
2072 Opens a floppy image contained in the specified file of the supported
2073 format and assigns it the given UUID.
2074
2075 After the image is successfully opened by this method, it gets
2076 remembered by (known to) this VirtualBox installation and will be
2077 accessible through <link to="#getFloppyImage"/> and
2078 <link to="#findFloppyImage"/> methods. Remembered images are also
2079 returned as part of the <link to="#floppyImages"/> array and can be
2080 mounted to virtual machines. See IMedium for more details.
2081
2082 See <link to="IMedium::location"/> to get more details about the format
2083 of the location string.
2084
2085 <result name="VBOX_E_FILE_ERROR">
2086 Floppy image specified by @a location not accessible.
2087 </result>
2088 <result name="VBOX_E_INVALID_OBJECT_STATE">
2089 Floppy image already exists in the media registry.
2090 </result>
2091
2092 <note>
2093 Currently, only raw floppy images are supported by VirtualBox.
2094 </note>
2095 </desc>
2096 <param name="location" type="wstring" dir="in">
2097 <desc>
2098 Full path to the file that contains a valid floppy image.
2099 </desc>
2100 </param>
2101 <param name="id" type="uuid" dir="in">
2102 <desc>
2103 UUID to assign to the given image file within this VirtualBox
2104 installation. If an empty (null) UUID is specified, the system will
2105 randomly generate a new UUID.
2106 </desc>
2107 </param>
2108 <param name="image" type="IFloppyImage" dir="return">
2109 <desc>Opened floppy image object.</desc>
2110 </param>
2111 </method>
2112
2113 <method name="getFloppyImage">
2114 <desc>
2115 Returns a floppy image with the given UUID.
2116
2117 The image with the given UUID must be known to this VirtualBox
2118 installation, i.e. it must be previously opened by <link
2119 to="#openFloppyImage"/>, or mounted to some known virtual machine.
2120
2121 <result name="VBOX_E_OBJECT_NOT_FOUND">
2122 No matching floppy image found in the media registry.
2123 </result>
2124
2125 </desc>
2126 <param name="id" type="uuid" dir="in">
2127 <desc>UUID of the image to look for.</desc>
2128 </param>
2129 <param name="image" type="IFloppyImage" dir="return">
2130 <desc>Found floppy image object.</desc>
2131 </param>
2132 </method>
2133
2134 <method name="findFloppyImage">
2135 <desc>
2136 Returns a floppy image with the given image location.
2137
2138 The image with the given UUID must be known to this VirtualBox
2139 installation, i.e. it must be previously opened by <link
2140 to="#openFloppyImage"/>, or mounted to some known virtual machine.
2141
2142 The search is done by comparing the value of the @a location argument to
2143 the <link to="IMedium::location"/> attribute of each known floppy image.
2144
2145 The requested location can be a path relative to the
2146 <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
2147 only a file name without any path is given, the
2148 <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
2149 folder</link> will be prepended to the file name before searching. Note
2150 that on case sensitive file systems, a case sensitive comparison is
2151 performed, otherwise the case of symbols in the file path is ignored.
2152
2153 <result name="VBOX_E_FILE_ERROR">
2154 Invalid image file location.
2155 </result>
2156 <result name="VBOX_E_OBJECT_NOT_FOUND">
2157 No matching floppy image found in the media registry.
2158 </result>
2159
2160 </desc>
2161 <param name="location" type="wstring" dir="in">
2162 <desc>Floppy image file path to look for.</desc>
2163 </param>
2164 <param name="image" type="IFloppyImage" dir="return">
2165 <desc>Found floppy image object.</desc>
2166 </param>
2167 </method>
2168
2169 <method name="getGuestOSType">
2170 <desc>
2171 Returns an object describing the specified guest OS type.
2172
2173 The requested guest OS type is specified using a string which is a
2174 mnemonic identifier of the guest operating system, such as
2175 <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
2176 particular virtual machine can be read or set using the
2177 <link to="IMachine::OSTypeId"/> attribute.
2178
2179 The <link to="IVirtualBox::guestOSTypes"/> collection contains all
2180 available guest OS type objects. Each object has an
2181 <link to="IGuestOSType::id"/> attribute which contains an identifier of
2182 the guest OS this object describes.
2183
2184 <result name="E_INVALIDARG">
2185 @a id is not a valid Guest OS type.
2186 </result>
2187
2188 </desc>
2189 <param name="id" type="wstring" dir="in">
2190 <desc>Guest OS type ID string.</desc>
2191 </param>
2192 <param name="type" type="IGuestOSType" dir="return">
2193 <desc>Guest OS type object.</desc>
2194 </param>
2195 </method>
2196
2197 <method name="createSharedFolder">
2198 <desc>
2199 Creates a new global shared folder by associating the given logical
2200 name with the given host path, adds it to the collection of shared
2201 folders and starts sharing it. Refer to the description of
2202 <link to="ISharedFolder"/> to read more about logical names.
2203 <note>
2204 In the current implementation, this operation is not
2205 implemented.
2206 </note>
2207 </desc>
2208 <param name="name" type="wstring" dir="in">
2209 <desc>Unique logical name of the shared folder.</desc>
2210 </param>
2211 <param name="hostPath" type="wstring" dir="in">
2212 <desc>Full path to the shared folder in the host file system.</desc>
2213 </param>
2214 <param name="writable" type="boolean" dir="in">
2215 <desc>Whether the share is writable or readonly</desc>
2216 </param>
2217 </method>
2218
2219 <method name="removeSharedFolder">
2220 <desc>
2221 Removes the global shared folder with the given name previously
2222 created by <link to="#createSharedFolder"/> from the collection of
2223 shared folders and stops sharing it.
2224 <note>
2225 In the current implementation, this operation is not
2226 implemented.
2227 </note>
2228 </desc>
2229 <param name="name" type="wstring" dir="in">
2230 <desc>Logical name of the shared folder to remove.</desc>
2231 </param>
2232 </method>
2233
2234 <method name="getNextExtraDataKey">
2235 <desc>
2236 Returns the global extra data key name following the supplied key.
2237
2238 An error is returned if the supplied @a key does not exist. @c NULL is
2239 returned in @a nextKey if the supplied key is the last key. When
2240 supplying @c NULL or an empty string for the @a key, the first key item
2241 is returned in @a nextKey (if there is any). @a nextValue is an optional
2242 parameter and if supplied, the next key's value is returned in it.
2243
2244 <result name="VBOX_E_OBJECT_NOT_FOUND">
2245 Extra data @a key not found.
2246 </result>
2247
2248 </desc>
2249 <param name="key" type="wstring" dir="in">
2250 <desc>Name of the data key to follow.</desc>
2251 </param>
2252 <param name="nextKey" type="wstring" dir="out">
2253 <desc>Name of the next data key.</desc>
2254 </param>
2255 <param name="nextValue" type="wstring" dir="out">
2256 <desc>Value of the next data key.</desc>
2257 </param>
2258 </method>
2259
2260 <method name="getExtraData">
2261 <desc>
2262 Returns associated global extra data.
2263
2264 If the requested data @a key does not exist, this function will
2265 succeed and return @c NULL in the @a value argument.
2266
2267 <result name="VBOX_E_FILE_ERROR">
2268 Settings file not accessible.
2269 </result>
2270 <result name="VBOX_E_XML_ERROR">
2271 Could not parse the settings file.
2272 </result>
2273
2274 </desc>
2275 <param name="key" type="wstring" dir="in">
2276 <desc>Name of the data key to get.</desc>
2277 </param>
2278 <param name="value" type="wstring" dir="return">
2279 <desc>Value of the requested data key.</desc>
2280 </param>
2281 </method>
2282
2283 <method name="setExtraData">
2284 <desc>
2285 Sets associated global extra data.
2286
2287 If you pass @c NULL as a key @a value, the given @a key will be
2288 deleted.
2289
2290 <note>
2291 Before performing the actual data change, this method will ask all
2292 registered callbacks using the
2293 <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
2294 notification for a permission. If one of the callbacks refuses the
2295 new value, the change will not be performed.
2296 </note>
2297 <note>
2298 On success, the
2299 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
2300 is called to inform all registered callbacks about a successful data
2301 change.
2302 </note>
2303
2304 <result name="VBOX_E_FILE_ERROR">
2305 Settings file not accessible.
2306 </result>
2307 <result name="VBOX_E_XML_ERROR">
2308 Could not parse the settings file.
2309 </result>
2310 <result name="E_ACCESSDENIED">
2311 Modification request refused.
2312 </result>
2313
2314 </desc>
2315 <param name="key" type="wstring" dir="in">
2316 <desc>Name of the data key to set.</desc>
2317 </param>
2318 <param name="value" type="wstring" dir="in">
2319 <desc>Value to assign to the key.</desc>
2320 </param>
2321 </method>
2322
2323 <method name="openSession">
2324 <desc>
2325 Opens a new direct session with the given virtual machine.
2326
2327 A direct session acts as a local lock on the given VM.
2328 There can be only one direct session open at a time for every
2329 virtual machine, protecting the VM from being manipulated by
2330 conflicting actions from different processes. Only after a
2331 direct session has been opened, one can change all VM settings
2332 and execute the VM in the process space of the session object.
2333
2334 Sessions therefore can be compared to mutex semaphores that
2335 lock a given VM for modification and execution.
2336 See <link to="ISession">ISession</link> for details.
2337
2338 <note>Unless you are writing a new VM frontend, you will not
2339 want to execute a VM in the current process. To spawn a new
2340 process that executes a VM, use
2341 <link to="IVirtualBox::openRemoteSession" />
2342 instead.</note>
2343
2344 Upon successful return, the session object can be used to
2345 get access to the machine and to the VM console.
2346
2347 In VirtualBox terminology, the machine becomes "mutable" after
2348 a session has been opened. Note that the "mutable" machine
2349 object, on which you may invoke IMachine methods to change its
2350 settings, will be a different object from the immutable IMachine
2351 objects returned by various IVirtualBox methods. To obtain a
2352 mutable IMachine object (upon which you can invoke settings methods),
2353 use the <link to="ISession::machine" /> attribute.
2354
2355 One must always call <link to="ISession::close" /> to release the
2356 lock on the machine, or the machine's state will eventually be
2357 set to "Aborted".
2358
2359 In other words, to change settings on a machine, the following
2360 sequence is typically performed:
2361
2362 <ol>
2363 <li>Call this method (openSession) to have a machine locked for
2364 the current session.</li>
2365
2366 <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
2367
2368 <li>Change the settings of the machine.</li>
2369
2370 <li>Call <link to="IMachine::saveSettings" />.</li>
2371
2372 <li>Close the session by calling <link to="ISession::close"/>.</li>
2373 </ol>
2374
2375 <result name="E_UNEXPECTED">
2376 Virtual machine not registered.
2377 </result>
2378 <result name="E_ACCESSDENIED">
2379 Process not started by OpenRemoteSession.
2380 </result>
2381 <result name="VBOX_E_OBJECT_NOT_FOUND">
2382 No matching virtual machine found.
2383 </result>
2384 <result name="VBOX_E_INVALID_OBJECT_STATE">
2385 Session already open or being opened.
2386 </result>
2387 <result name="VBOX_E_VM_ERROR">
2388 Failed to assign machine to session.
2389 </result>
2390
2391 </desc>
2392 <param name="session" type="ISession" dir="in">
2393 <desc>
2394 Session object that will represent the opened session after
2395 successful method invocation. This object must not represent
2396 the already open session.
2397 <note>
2398 This session will be automatically closed if the
2399 VirtualBox server is terminated for some reason.
2400 </note>
2401 </desc>
2402 </param>
2403 <param name="machineId" type="uuid" dir="in">
2404 <desc>ID of the virtual machine to open a session with.</desc>
2405 </param>
2406 </method>
2407
2408 <method name="openRemoteSession">
2409 <desc>
2410 Spawns a new process that executes a virtual machine (called a
2411 "remote session").
2412
2413 Opening a remote session causes the VirtualBox server to start a new
2414 process that opens a direct session with the given VM. As a result, the
2415 VM is locked by that direct session in the new process, preventing
2416 conflicting changes from other processes. Since sessions act as locks
2417 that prevent conflicting changes, one cannot open a remote session
2418 for a VM that already has another open session (direct or remote), or
2419 is currently in the process of opening one (see <link
2420 to="IMachine::sessionState"/>).
2421
2422 While the remote session still provides some level of control over the
2423 VM execution to the caller (using the <link to="IConsole" /> interface),
2424 not all VM settings are available for modification within the remote
2425 session context.
2426
2427 This operation can take some time (a new VM is started in a new process,
2428 for which memory and other resources need to be set up). Because of this,
2429 an <link to="IProgress" /> is returned to allow the caller to wait for this
2430 asynchronous operation to be completed. Until then, the remote session
2431 object remains in the closed state, and accessing the machine or its
2432 console through it is invalid. It is recommended to use
2433 <link to="IProgress::waitForCompletion" /> or similar calls to wait for
2434 completion.
2435
2436 As with all <link to="ISession" /> objects, it is recommended to call
2437 <link to="ISession::close" /> on the local session object once openRemoteSession()
2438 has been called. However, the session's state (see <link to="ISession::state" />)
2439 will not return to "Closed" until the remote session has also closed (i.e.
2440 until the VM is no longer running). In that case, however, the state of
2441 the session will automatically change back to "Closed".
2442
2443 Currently supported session types (values of the @a type
2444 argument) are:
2445 <ul>
2446 <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
2447 <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
2448 </ul>
2449
2450 The @a environment argument is a string containing definitions of
2451 environment variables in the following format:
2452 @code
2453 NAME[=VALUE]\n
2454 NAME[=VALUE]\n
2455 ...
2456 @endcode
2457 where <tt>\\n</tt> is the new line character. These environment
2458 variables will be appended to the environment of the VirtualBox server
2459 process. If an environment variable exists both in the server process
2460 and in this list, the value from this list takes precedence over the
2461 server's variable. If the value of the environment variable is
2462 omitted, this variable will be removed from the resulting environment.
2463 If the environment string is @c null, the server environment is
2464 inherited by the started process as is.
2465
2466 <see>openExistingSession</see>
2467
2468 <result name="E_UNEXPECTED">
2469 Virtual machine not registered.
2470 </result>
2471 <result name="E_INVALIDARG">
2472 Invalid session type @a type.
2473 </result>
2474 <result name="VBOX_E_OBJECT_NOT_FOUND">
2475 No machine matching @a machineId found.
2476 </result>
2477 <result name="VBOX_E_INVALID_OBJECT_STATE">
2478 Session already open or being opened.
2479 </result>
2480 <result name="VBOX_E_IPRT_ERROR">
2481 Launching process for machine failed.
2482 </result>
2483 <result name="VBOX_E_VM_ERROR">
2484 Failed to assign machine to session.
2485 </result>
2486
2487 </desc>
2488 <param name="session" type="ISession" dir="in">
2489 <desc>
2490 Session object that will represent the opened remote session
2491 after successful method invocation (this object must not
2492 represent an already open session).
2493 </desc>
2494 </param>
2495 <param name="machineId" type="uuid" dir="in">
2496 <desc>ID of the virtual machine to open a session with.</desc>
2497 </param>
2498 <param name="type" type="wstring" dir="in">
2499 <desc>
2500 Type of the remote session (case sensitive).
2501 </desc>
2502 </param>
2503 <param name="environment" type="wstring" dir="in">
2504 <desc>
2505 Environment to pass to the opened session (may be @c null).
2506 </desc>
2507 </param>
2508 <param name="progress" type="IProgress" dir="return">
2509 <desc>Progress object to track the operation completion.</desc>
2510 </param>
2511 </method>
2512
2513 <method name="openExistingSession">
2514 <desc>
2515 Opens a new remote session with the virtual machine for
2516 which a direct session is already open.
2517
2518 The remote session provides some level of control over the VM
2519 execution (using the IConsole interface) to the caller; however,
2520 within the remote session context, not all VM settings are available
2521 for modification.
2522
2523 As opposed to <link to="#openRemoteSession"/>, the number of
2524 remote sessions opened this way is not limited by the API
2525
2526 <note>
2527 It is an error to open a remote session with the machine that
2528 doesn't have an open direct session.
2529 </note>
2530
2531 <result name="E_UNEXPECTED">
2532 Virtual machine not registered.
2533 </result>
2534 <result name="VBOX_E_OBJECT_NOT_FOUND">
2535 No machine matching @a machineId found.
2536 </result>
2537 <result name="VBOX_E_INVALID_OBJECT_STATE">
2538 Session already open or being opened.
2539 </result>
2540 <result name="VBOX_E_INVALID_SESSION_STATE">
2541 Direct session state not Open.
2542 </result>
2543 <result name="VBOX_E_VM_ERROR">
2544 Failed to get console object from direct session or assign
2545 machine to session.
2546 </result>
2547
2548 <see>openRemoteSession</see>
2549 </desc>
2550 <param name="session" type="ISession" dir="in">
2551 <desc>
2552 Session object that will represent the open remote session
2553 after successful method invocation. This object must not
2554 represent an already open session.
2555 <note>
2556 This session will be automatically closed when the peer
2557 (direct) session dies or gets closed.
2558 </note>
2559 </desc>
2560 </param>
2561 <param name="machineId" type="uuid" dir="in">
2562 <desc>ID of the virtual machine to open a session with.</desc>
2563 </param>
2564 </method>
2565
2566 <method name="registerCallback">
2567 <desc>
2568 Registers a new global VirtualBox callback. The methods of the given
2569 callback object will be called by VirtualBox when an appropriate
2570 event occurs.
2571
2572 <result name="E_INVALIDARG">
2573 A @c NULL callback cannot be registered.
2574 </result>
2575
2576 </desc>
2577 <param name="callback" type="IVirtualBoxCallback" dir="in">
2578 <desc>Callback object to register.</desc>
2579 </param>
2580 </method>
2581
2582 <method name="unregisterCallback">
2583 <desc>
2584 Unregisters the previously registered global VirtualBox callback.
2585
2586 <result name="E_INVALIDARG">
2587 Specified @a callback not registered.
2588 </result>
2589
2590 </desc>
2591 <param name="callback" type="IVirtualBoxCallback" dir="in">
2592 <desc>Callback object to unregister.</desc>
2593 </param>
2594 </method>
2595
2596 <method name="waitForPropertyChange">
2597 <desc>
2598 Blocks the caller until any of the properties represented by the
2599 @a what argument changes the value or until the given timeout interval
2600 expires.
2601
2602 The @a what argument is a comma separated list of property masks that
2603 describe properties the caller is interested in. The property mask is
2604 a string in the following format:
2605
2606 <pre>
2607 [[group.]subgroup.]name
2608 </pre>
2609
2610 where @c name is the property name and @c group, @c subgroup are zero
2611 or more property group specifiers. Each element (group or name) in
2612 the property mask may be either a Latin string or an asterisk symbol
2613 (@c "*") which is used to match any string for the given element. A
2614 property mask that doesn't contain asterisk symbols represents a
2615 single fully qualified property name.
2616
2617 Groups in the fully qualified property name go from more generic (the
2618 left-most part) to more specific (the right-most part). The first
2619 element is usually a name of the object the property belongs to. The
2620 second element may be either a property name, or a child object name,
2621 or an index if the preceding element names an object which is one of
2622 many objects of the same type. This way, property names form a
2623 hierarchy of properties. Here are some examples of property names:
2624
2625 <table>
2626 <tr>
2627 <td><tt>VirtualBox.version</tt></td>
2628 <td><link to="IVirtualBox::version"/> property</td>
2629 </tr>
2630 <tr>
2631 <td><tt>Machine.&lt;UUID&gt;.name</tt></td>
2632 <td><link to="IMachine::name"/> property of the machine with the
2633 given UUID</td>
2634 </tr>
2635 </table>
2636
2637 Most property names directly correspond to the properties of objects
2638 (components) provided by the VirtualBox library and may be used to
2639 track changes to these properties. However, there may be
2640 pseudo-property names that don't correspond to any existing object's
2641 property directly, as well as there may be object properties that
2642 don't have a corresponding property name that is understood by this
2643 method, and therefore changes to such properties cannot be
2644 tracked. See individual object's property descriptions to get a
2645 fully qualified property name that can be used with this method (if
2646 any).
2647
2648 There is a special property mask @c "*" (i.e. a string consisting of a
2649 single asterisk symbol) that can be used to match all properties.
2650 Below are more examples of property masks:
2651
2652 <table>
2653 <tr>
2654 <td><tt>VirtualBox.*</tt></td>
2655 <td>Track all properties of the VirtualBox object</td>
2656 </tr>
2657 <tr>
2658 <td><tt>Machine.*.name</tt></td>
2659 <td>Track changes to the <link to="IMachine::name"/> property of
2660 all registered virtual machines</td>
2661 </tr>
2662 </table>
2663
2664 <note>
2665 This function is not implemented in the current version of the
2666 product.
2667 </note>
2668 </desc>
2669 <param name="what" type="wstring" dir="in">
2670 <desc>Comma separated list of property masks.</desc>
2671 </param>
2672 <param name="timeout" type="unsigned long" dir="in">
2673 <desc>
2674 Wait timeout in milliseconds.
2675 Specify -1 for an indefinite wait.
2676 </desc>
2677 </param>
2678 <param name="changed" type="wstring" dir="out">
2679 <desc>
2680 Comma separated list of properties that have been changed and caused
2681 this method to return to the caller.
2682 </desc>
2683 </param>
2684 <param name="values" type="wstring" dir="out">
2685 <desc>Reserved, not currently used.</desc>
2686 </param>
2687 </method>
2688
2689 <method name="saveSettings">
2690 <desc>
2691 Saves the global settings to the global settings file
2692 (<link to="#settingsFilePath"/>).
2693
2694 This method is only useful for explicitly saving the global settings
2695 file after it has been auto-converted from the old format to the most
2696 recent format (see <link to="#settingsFileVersion"/> for details).
2697 Normally, the global settings file is implicitly saved when a global
2698 setting is changed.
2699
2700 <result name="VBOX_E_FILE_ERROR">
2701 Settings file not accessible.
2702 </result>
2703 <result name="VBOX_E_XML_ERROR">
2704 Could not parse the settings file.
2705 </result>
2706
2707 </desc>
2708 </method>
2709
2710 <method name="saveSettingsWithBackup">
2711 <desc>
2712 Creates a backup copy of the global settings file
2713 (<link to="#settingsFilePath"/>) in case of auto-conversion, and then
2714 calls <link to="#saveSettings"/>.
2715
2716 Note that the backup copy is created <b>only</b> if the settings file
2717 auto-conversion took place (see <link to="#settingsFileVersion"/> for
2718 details). Otherwise, this call is fully equivalent to
2719 <link to="#saveSettings"/> and no backup copying is done.
2720
2721 The backup copy is created in the same directory where the original
2722 settings file is located. It is given the following file name:
2723 <pre>
2724 original.xml.x.y-platform.bak
2725 </pre>
2726 where <tt>original.xml</tt> is the original settings file name
2727 (excluding path), and <tt>x.y-platform</tt> is the version of the old
2728 format of the settings file (before auto-conversion).
2729
2730 If the given backup file already exists, this method will try to add the
2731 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
2732 0 to 9) and copy it again until it succeeds. If all suffixes are
2733 occupied, or if any other copy error occurs, this method will return a
2734 failure.
2735
2736 If the copy operation succeeds, the @a bakFileName return argument will
2737 receive a full path to the created backup file (for informational
2738 purposes). Note that this will happen even if the subsequent
2739 <link to="#saveSettings"/> call performed by this method after the
2740 copy operation, fails.
2741
2742 <note>
2743 The VirtualBox API never calls this method. It is intended purely for
2744 the purposes of creating backup copies of the settings files by
2745 front-ends before saving the results of the automatically performed
2746 settings conversion to disk.
2747 </note>
2748
2749 <see>settingsFileVersion</see>
2750
2751 <result name="VBOX_E_FILE_ERROR">
2752 Settings file not accessible.
2753 </result>
2754 <result name="VBOX_E_XML_ERROR">
2755 Could not parse the settings file.
2756 </result>
2757 <result name="VBOX_E_IPRT_ERROR">
2758 Could not copy the settings file.
2759 </result>
2760
2761 </desc>
2762 <param name="bakFileName" type="wstring" dir="return">
2763 <desc>Full path to the created backup copy.</desc>
2764 </param>
2765 </method>
2766
2767 <!--method name="createDHCPServerForInterface">
2768 <desc>
2769 Creates a dhcp server settings to be used for the given interface
2770 <result name="E_INVALIDARG">
2771 Host network interface @a name already exists.
2772 </result>
2773 </desc>
2774 <param name="interface" type="IHostNetworkInterface" dir="in">
2775 <desc>Network Interface</desc>
2776 </param>
2777 <param name="server" type="IDHCPServer" dir="out">
2778 <desc>Dhcp server settings</desc>
2779 </param>
2780 </method-->
2781
2782 <method name="createDHCPServer">
2783 <desc>
2784 Creates a dhcp server settings to be used for the given internal network name
2785 <result name="E_INVALIDARG">
2786 Host network interface @a name already exists.
2787 </result>
2788 </desc>
2789 <param name="name" type="wstring" dir="in">
2790 <desc>server name</desc>
2791 </param>
2792 <param name="server" type="IDHCPServer" dir="return">
2793 <desc>Dhcp server settings</desc>
2794 </param>
2795 </method>
2796
2797 <method name="findDHCPServerByNetworkName">
2798 <desc>
2799 Searches a dhcp server settings to be used for the given internal network name
2800 <result name="E_INVALIDARG">
2801 Host network interface @a name already exists.
2802 </result>
2803
2804 </desc>
2805 <param name="name" type="wstring" dir="in">
2806 <desc>server name</desc>
2807 </param>
2808 <param name="server" type="IDHCPServer" dir="return">
2809 <desc>Dhcp server settings</desc>
2810 </param>
2811 </method>
2812
2813 <!--method name="findDHCPServerForInterface">
2814 <desc>
2815 Searches a dhcp server settings to be used for the given interface
2816 <result name="E_INVALIDARG">
2817 Host network interface @a name already exists.
2818 </result>
2819 </desc>
2820 <param name="interface" type="IHostNetworkInterface" dir="in">
2821 <desc>Network Interface</desc>
2822 </param>
2823 <param name="server" type="IDHCPServer" dir="out">
2824 <desc>Dhcp server settings</desc>
2825 </param>
2826 </method-->
2827
2828 <method name="removeDHCPServer">
2829 <desc>
2830 Removes the dhcp server settings
2831 <result name="E_INVALIDARG">
2832 Host network interface @a name already exists.
2833 </result>
2834 </desc>
2835 <param name="server" type="IDHCPServer" dir="in">
2836 <desc>Dhcp server settings to be removed</desc>
2837 </param>
2838 </method>
2839
2840 </interface>
2841
2842 <!--
2843 // IAppliance
2844 /////////////////////////////////////////////////////////////////////////
2845 -->
2846
2847 <enum
2848 name="CIMOSType"
2849 uuid="86ef5f8c-18b2-4db8-a314-33721b59f89b"
2850 >
2851 <desc>
2852 OVF operating system values according to CIM V2.20 (as of Nov 2008); http://www.dmtf.org/standards/cim/cim_schema_v220
2853 </desc>
2854
2855 <const name="CIMOS_Unknown" value="0" /> <!-- "Unknown" -->
2856 <const name="CIMOS_Other" value="1" /> <!-- "Other" -->
2857 <const name="CIMOS_MACOS" value="2" /> <!-- "MACOS" -->
2858 <const name="CIMOS_ATTUNIX" value="3" /> <!-- "ATTUNIX" -->
2859 <const name="CIMOS_DGUX" value="4" /> <!-- "DGUX" -->
2860 <const name="CIMOS_DECNT" value="5" /> <!-- "DECNT" -->
2861 <const name="CIMOS_Tru64UNIX" value="6" /> <!-- "Tru64 UNIX" -->
2862 <const name="CIMOS_OpenVMS" value="7" /> <!-- "OpenVMS" -->
2863 <const name="CIMOS_HPUX" value="8" /> <!-- "HPUX" -->
2864 <const name="CIMOS_AIX" value="9" /> <!-- "AIX" -->
2865 <const name="CIMOS_MVS" value="10" /> <!-- "MVS" -->
2866 <const name="CIMOS_OS400" value="11" /> <!-- "OS400" -->
2867 <const name="CIMOS_OS2" value="12" /> <!-- "OS/2" -->
2868 <const name="CIMOS_JavaVM" value="13" /> <!-- "JavaVM" -->
2869 <const name="CIMOS_MSDOS" value="14" /> <!-- "MSDOS" -->
2870 <const name="CIMOS_WIN3x" value="15" /> <!-- "WIN3x" -->
2871 <const name="CIMOS_WIN95" value="16" /> <!-- "WIN95" -->
2872 <const name="CIMOS_WIN98" value="17" /> <!-- "WIN98" -->
2873 <const name="CIMOS_WINNT" value="18" /> <!-- "WINNT" -->
2874 <const name="CIMOS_WINCE" value="19" /> <!-- "WINCE" -->
2875 <const name="CIMOS_NCR3000" value="20" /> <!-- "NCR3000" -->
2876 <const name="CIMOS_NetWare" value="21" /> <!-- "NetWare" -->
2877 <const name="CIMOS_OSF" value="22" /> <!-- "OSF" -->
2878 <const name="CIMOS_DCOS" value="23" /> <!-- "DC/OS" -->
2879 <const name="CIMOS_ReliantUNIX" value="24" /> <!-- "Reliant UNIX" -->
2880 <const name="CIMOS_SCOUnixWare" value="25" /> <!-- "SCO UnixWare" -->
2881 <const name="CIMOS_SCOOpenServer" value="26" /> <!-- "SCO OpenServer" -->
2882 <const name="CIMOS_Sequent" value="27" /> <!-- "Sequent" -->
2883 <const name="CIMOS_IRIX" value="28" /> <!-- "IRIX" -->
2884 <const name="CIMOS_Solaris" value="29" /> <!-- "Solaris" -->
2885 <const name="CIMOS_SunOS" value="30" /> <!-- "SunOS" -->
2886 <const name="CIMOS_U6000" value="31" /> <!-- "U6000" -->
2887 <const name="CIMOS_ASERIES" value="32" /> <!-- "ASERIES" -->
2888 <const name="CIMOS_HPNonStopOS" value="33" /> <!-- "HP NonStop OS" -->
2889 <const name="CIMOS_HPNonStopOSS" value="34" /> <!-- "HP NonStop OSS" -->
2890 <const name="CIMOS_BS2000" value="35" /> <!-- "BS2000" -->
2891 <const name="CIMOS_LINUX" value="36" /> <!-- "LINUX" -->
2892 <const name="CIMOS_Lynx" value="37" /> <!-- "Lynx" -->
2893 <const name="CIMOS_XENIX" value="38" /> <!-- "XENIX" -->
2894 <const name="CIMOS_VM" value="39" /> <!-- "VM" -->
2895 <const name="CIMOS_InteractiveUNIX" value="40" /> <!-- "Interactive UNIX" -->
2896 <const name="CIMOS_BSDUNIX" value="41" /> <!-- "BSDUNIX" -->
2897 <const name="CIMOS_FreeBSD" value="42" /> <!-- "FreeBSD" -->
2898 <const name="CIMOS_NetBSD" value="43" /> <!-- "NetBSD" -->
2899 <const name="CIMOS_GNUHurd" value="44" /> <!-- "GNU Hurd" -->
2900 <const name="CIMOS_OS9" value="45" /> <!-- "OS9" -->
2901 <const name="CIMOS_MACHKernel" value="46" /> <!-- "MACH Kernel" -->
2902 <const name="CIMOS_Inferno" value="47" /> <!-- "Inferno" -->
2903 <const name="CIMOS_QNX" value="48" /> <!-- "QNX" -->
2904 <const name="CIMOS_EPOC" value="49" /> <!-- "EPOC" -->
2905 <const name="CIMOS_IxWorks" value="50" /> <!-- "IxWorks" -->
2906 <const name="CIMOS_VxWorks" value="51" /> <!-- "VxWorks" -->
2907 <const name="CIMOS_MiNT" value="52" /> <!-- "MiNT" -->
2908 <const name="CIMOS_BeOS" value="53" /> <!-- "BeOS" -->
2909 <const name="CIMOS_HPMPE" value="54" /> <!-- "HP MPE" -->
2910 <const name="CIMOS_NextStep" value="55" /> <!-- "NextStep" -->
2911 <const name="CIMOS_PalmPilot" value="56" /> <!-- "PalmPilot" -->
2912 <const name="CIMOS_Rhapsody" value="57" /> <!-- "Rhapsody" -->
2913 <const name="CIMOS_Windows2000" value="58" /> <!-- "Windows 2000" -->
2914 <const name="CIMOS_Dedicated" value="59" /> <!-- "Dedicated" -->
2915 <const name="CIMOS_OS390" value="60" /> <!-- "OS/390" -->
2916 <const name="CIMOS_VSE" value="61" /> <!-- "VSE" -->
2917 <const name="CIMOS_TPF" value="62" /> <!-- "TPF" -->
2918 <const name="CIMOS_WindowsMe" value="63" /> <!-- "Windows (R) Me" -->
2919 <const name="CIMOS_CalderaOpenUNIX" value="64" /> <!-- "Caldera Open UNIX" -->
2920 <const name="CIMOS_OpenBSD" value="65" /> <!-- "OpenBSD" -->
2921 <const name="CIMOS_NotApplicable" value="66" /> <!-- "Not Applicable" -->
2922 <const name="CIMOS_WindowsXP" value="67" /> <!-- "Windows XP" -->
2923 <const name="CIMOS_zOS" value="68" /> <!-- "z/OS" -->
2924 <const name="CIMOS_MicrosoftWindowsServer2003" value="69" /> <!-- "Microsoft Windows Server 2003" -->
2925 <const name="CIMOS_MicrosoftWindowsServer2003_64" value="70" /> <!-- "Microsoft Windows Server 2003 64-Bit" -->
2926 <const name="CIMOS_WindowsXP_64" value="71" /> <!-- "Windows XP 64-Bit" -->
2927 <const name="CIMOS_WindowsXPEmbedded" value="72" /> <!-- "Windows XP Embedded" -->
2928 <const name="CIMOS_WindowsVista" value="73" /> <!-- "Windows Vista" -->
2929 <const name="CIMOS_WindowsVista_64" value="74" /> <!-- "Windows Vista 64-Bit" -->
2930 <const name="CIMOS_WindowsEmbeddedforPointofService" value="75" /> <!-- "Windows Embedded for Point of Service" -->
2931 <const name="CIMOS_MicrosoftWindowsServer2008" value="76" /> <!-- "Microsoft Windows Server 2008" -->
2932 <const name="CIMOS_MicrosoftWindowsServer2008_64" value="77" /> <!-- "Microsoft Windows Server 2008 64-Bit" -->
2933 <const name="CIMOS_FreeBSD_64" value="78" /> <!-- "FreeBSD 64-Bit" -->
2934 <const name="CIMOS_RedHatEnterpriseLinux" value="79" /> <!-- "RedHat Enterprise Linux" -->
2935 <const name="CIMOS_RedHatEnterpriseLinux_64" value="80" /> <!-- "RedHat Enterprise Linux 64-Bit" -->
2936 <const name="CIMOS_Solaris_64" value="81" /> <!-- "Solaris 64-Bit" -->
2937 <const name="CIMOS_SUSE" value="82" /> <!-- "SUSE" -->
2938 <const name="CIMOS_SUSE_64" value="83" /> <!-- "SUSE 64-Bit" -->
2939 <const name="CIMOS_SLES" value="84" /> <!-- "SLES" -->
2940 <const name="CIMOS_SLES_64" value="85" /> <!-- "SLES 64-Bit" -->
2941 <const name="CIMOS_NovellOES" value="86" /> <!-- "Novell OES" -->
2942 <const name="CIMOS_NovellLinuxDesktop" value="87" /> <!-- "Novell Linux Desktop" -->
2943 <const name="CIMOS_SunJavaDesktopSystem" value="88" /> <!-- "Sun Java Desktop System" -->
2944 <const name="CIMOS_Mandriva" value="89" /> <!-- "Mandriva" -->
2945 <const name="CIMOS_Mandriva_64" value="90" /> <!-- "Mandriva 64-Bit" -->
2946 <const name="CIMOS_TurboLinux" value="91" /> <!-- "TurboLinux" -->
2947 <const name="CIMOS_TurboLinux_64" value="92" /> <!-- "TurboLinux 64-Bit" -->
2948 <const name="CIMOS_Ubuntu" value="93" /> <!-- "Ubuntu" -->
2949 <const name="CIMOS_Ubuntu_64" value="94" /> <!-- "Ubuntu 64-Bit" -->
2950 <const name="CIMOS_Debian" value="95" /> <!-- "Debian" -->
2951 <const name="CIMOS_Debian_64" value="96" /> <!-- "Debian 64-Bit" -->
2952 <const name="CIMOS_Linux_2_4_x" value="97" /> <!-- "Linux 2.4.x" -->
2953 <const name="CIMOS_Linux_2_4_x_64" value="98" /> <!-- "Linux 2.4.x 64-Bit" -->
2954 <const name="CIMOS_Linux_2_6_x" value="99" /> <!-- "Linux 2.6.x" -->
2955 <const name="CIMOS_Linux_2_6_x_64" value="100" /> <!-- "Linux 2.6.x 64-Bit" -->
2956 <const name="CIMOS_Linux_64" value="101" /> <!-- "Linux 64-Bit" -->
2957 <const name="CIMOS_Other_64" value="102" /> <!-- "Other 64-Bit" -->
2958 </enum>
2959
2960 <enum
2961 name="OVFResourceType"
2962 uuid="646a78d7-6f04-49f4-82c4-75c28a75a4cd"
2963 >
2964 <desc>
2965 OVF resource type (as listed with CIM_ResourceAllocationSettingData; see for example
2966 http://msdn.microsoft.com/en-us/library/cc136877(VS.85).aspx).
2967 </desc>
2968
2969 <const name="Other" value="1" />
2970 <const name="ComputerSystem" value="2" />
2971 <const name="Processor" value="3" />
2972 <const name="Memory" value="4" />
2973 <const name="IDEController" value="5" />
2974 <const name="ParallelSCSIHBA" value="6" />
2975 <const name="FCHBA" value="7" />
2976 <const name="iSCSIHBA" value="8" />
2977 <const name="IBHCA" value="9" />
2978 <const name="EthernetAdapter" value="10" />
2979 <const name="OtherNetworkAdapter" value="11" />
2980 <const name="IOSlot" value="12" />
2981 <const name="IODevice" value="13" />
2982 <const name="FloppyDrive" value="14" />
2983 <const name="CDDrive" value="15" />
2984 <const name="DVDDrive" value="16" />
2985 <const name="HardDisk" value="17" />
2986 <const name="OtherStorageDevice" value="20" />
2987 <const name="USBController" value="23" />
2988 <const name="SoundCard" value="35" />
2989 </enum>
2990
2991 <interface
2992 name="IAppliance" extends="$unknown"
2993 uuid="a7a71c1f-20d3-4483-95c0-7357dda77f50"
2994 wsmap="managed"
2995 >
2996 <desc>
2997 Represents a platform-independent appliance in OVF format. An instance of this is returned
2998 by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
2999 appliances with VirtualBox.
3000
3001 The OVF standard suggests two different physical file formats:
3002
3003 <ol>
3004 <li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
3005 path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
3006 this descriptor file references other files, as OVF appliances distributed as a set of
3007 files most likely do, those files must be in the same directory as the descriptor file.</li>
3008
3009 <li>If the OVF is distributed as a single file, it must be in TAR format and have the
3010 <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
3011 files and optionally other files.
3012
3013 At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
3014 be added with a later version.</li>
3015 </ol>
3016
3017 <b>Importing</b> an OVF appliance into VirtualBox as instances of
3018 <link to="IMachine" /> involves the following sequence of API calls:
3019
3020 <ol>
3021 <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
3022 </li>
3023
3024 <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
3025 would like to import. So long as this file is syntactically valid, this will succeed
3026 and return an instance of IAppliance that contains the parsed data from the OVF file.
3027 </li>
3028
3029 <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
3030 contents of the IAppliance attributes accordingly. These can be inspected by a
3031 VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
3032 user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
3033 instances of <link to="IVirtualSystemDescription" /> which represent the virtual
3034 systems in the OVF, which in turn describe the virtual hardware prescribed by the
3035 OVF (network and hardware adapters, virtual disk images, memory size and so on).
3036 The GUI can then give the user the option to confirm and/or change these suggestions.
3037 </li>
3038
3039 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3040 virtual system to override the suggestions made by the interpret() routine.
3041 </li>
3042
3043 <li>Finally, call <link to="#importMachines" /> to create virtual machines in
3044 VirtualBox as instances of <link to="IMachine" /> that match the information in the
3045 virtual system descriptions.
3046 </li>
3047 </ol>
3048
3049 <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
3050
3051 <ol>
3052 <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
3053 an empty IAppliance object.
3054 </li>
3055
3056 <li>For each machine you would like to export, call <link to="IMachine::export" />
3057 with the IAppliance object you just created. This creates an instance of
3058 <link to="IVirtualSystemDescription" /> inside the appliance.
3059 </li>
3060
3061 <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
3062 virtual system to override the suggestions made by the export() routine.
3063 </li>
3064
3065 <li>Finally, call <link to="#write" /> with a path specification to have the OVF
3066 file written.</li>
3067 </ol>
3068
3069 </desc>
3070
3071 <attribute name="path" type="wstring" readonly="yes">
3072 <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
3073 the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
3074 <link to="#write" /> (for export).
3075 This attribute is empty until one of these methods has been called.
3076 </desc>
3077 </attribute>
3078
3079 <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
3080 <desc>
3081 Array of virtual disk definitions. One such description exists for each
3082 disk definition in the OVF; each string array item represents one such piece of
3083 disk information, with the information fields separated by tab (\t) characters.
3084
3085 The caller should be prepared for additional fields being appended to
3086 this string in future versions of VirtualBox and therefore check for
3087 the number of tabs in the strings returned.
3088
3089 In the current version, the following eight fields are returned per string
3090 in the array:
3091
3092 <ol>
3093 <li>Disk ID (unique string identifier given to disk)</li>
3094
3095 <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
3096
3097 <li>Populated size (optional unsigned integer indicating the current size of the
3098 disk; can be approximate; -1 if unspecified)</li>
3099
3100 <li>Format (string identifying the disk format, typically
3101 "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
3102
3103 <li>Reference (where to find the disk image, typically a file name; if empty,
3104 then the disk should be created on import)</li>
3105
3106 <li>Image size (optional unsigned integer indicating the size of the image,
3107 which need not necessarily be the same as the values specified above, since
3108 the image may be compressed or sparse; -1 if not specified)</li>
3109
3110 <li>Chunk size (optional unsigned integer if the image is split into chunks;
3111 presently unsupported and always -1)</li>
3112
3113 <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
3114 </ol>
3115 </desc>
3116 </attribute>
3117
3118 <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
3119 <desc> Array of virtual system descriptions. One such description is created
3120 for each virtual system found in the OVF.
3121 This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
3122 (for export) has been called.
3123 </desc>
3124 </attribute>
3125
3126 <method name="read">
3127 <desc>
3128 Reads an OVF file into the appliance object.
3129
3130 This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
3131 mere fact that this method returns successfully does not mean that VirtualBox supports all
3132 features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
3133 </desc>
3134 <param name="file" type="wstring" dir="in">
3135 <desc>
3136 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3137 on whether the appliance is distributed as a set of files or as a single file, respectively).
3138 </desc>
3139 </param>
3140 </method>
3141
3142 <method name="interpret">
3143 <desc>
3144 Interprets the OVF data that was read when the appliance was constructed. After
3145 calling this method, one can inspect the
3146 <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
3147 one <link to="IVirtualSystemDescription" /> for each virtual machine found in
3148 the appliance.
3149
3150 Calling this method is the second step of importing an appliance into VirtualBox;
3151 see <link to="IAppliance" /> for an overview.
3152
3153 After calling this method, one should call <link to="#getWarnings" /> to find out
3154 if problems were encountered during the processing which might later lead to
3155 errors.
3156 </desc>
3157 </method>
3158
3159 <method name="importMachines">
3160 <desc>
3161 Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
3162 and other interfaces that match the information contained in the appliance as
3163 closely as possible, as represented by the import instructions in the
3164 <link to="#virtualSystemDescriptions" /> array.
3165
3166 Calling this method is the final step of importing an appliance into VirtualBox;
3167 see <link to="IAppliance" /> for an overview.
3168
3169 Since importing the appliance will most probably involve copying and converting
3170 disk images, which can take a long time, this method operates asynchronously and
3171 returns an IProgress object to allow the caller to monitor the progress.
3172 </desc>
3173
3174 <param name="aProgress" type="IProgress" dir="return">
3175 <desc></desc>
3176 </param>
3177 </method>
3178
3179 <method name="write">
3180 <desc>
3181 Writes the contents of the appliance exports into a new OVF file.
3182
3183 Calling this method is the final step of exporting an appliance from VirtualBox;
3184 see <link to="IAppliance" /> for an overview.
3185
3186 Since exporting the appliance will most probably involve copying and converting
3187 disk images, which can take a long time, this method operates asynchronously and
3188 returns an IProgress object to allow the caller to monitor the progress.
3189 </desc>
3190 <param name="path" type="wstring" dir="in">
3191 <desc>
3192 Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
3193 on whether the appliance is distributed as a set of files or as a single file, respectively).
3194 </desc>
3195 </param>
3196 <param name="aProgress" type="IProgress" dir="return">
3197 <desc></desc>
3198 </param>
3199 </method>
3200
3201 <method name="getWarnings">
3202 <desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
3203
3204 <param name="aWarnings" type="wstring" dir="return" safearray="yes">
3205 <desc></desc>
3206 </param>
3207 </method>
3208
3209 </interface>
3210
3211 <enum
3212 name="VirtualSystemDescriptionType"
3213 uuid="8ac36d00-bb7c-4a35-a835-3f004b27427b"
3214 >
3215 <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
3216 a configuration value.</desc>
3217
3218 <const name="Ignore" value="1" />
3219 <const name="OS" value="2" />
3220 <const name="Name" value="3" />
3221 <const name="Description" value="4" />
3222 <const name="CPU" value="5" />
3223 <const name="Memory" value="6" />
3224 <const name="HardDiskControllerIDE" value="7" />
3225 <const name="HardDiskControllerSATA" value="8" />
3226 <const name="HardDiskControllerSCSI" value="9" />
3227 <const name="HardDiskImage" value="10" />
3228 <const name="Floppy" value="11" />
3229 <const name="CDROM" value="12" />
3230 <const name="NetworkAdapter" value="13" />
3231 <const name="USBController" value="14" />
3232 <const name="SoundCard" value="15" />
3233
3234 </enum>
3235
3236 <interface
3237 name="IVirtualSystemDescription" extends="$unknown"
3238 uuid="c2e9f5b5-522c-47e5-be55-0d20b46a95d9"
3239 wsmap="managed"
3240 >
3241
3242 <desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
3243 After <link to="IAppliance::interpret" /> has been called, that array contains
3244 information about how the virtual systems described in the OVF should best be imported into VirtualBox
3245 virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
3246 into VirtualBox.
3247 </desc>
3248
3249 <attribute name="count" type="unsigned long" readonly="yes">
3250 <desc>Return the number of virtual system description entries.</desc>
3251 </attribute>
3252
3253 <method name="getDescription">
3254 <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
3255 items with the same indices correspond and jointly represent an import instruction for VirtualBox.
3256
3257 The list below identifies the value sets that are possible depending on the
3258 <link to="VirtualSystemDescriptionType" /> enum value in the array item in aTypes[]. In each case,
3259 the array item with the same index in aOvfValues[] will contain the original value as contained
3260 in the OVF file (just for informational purposes), and the corresponding item in aVboxValues[]
3261 will contain a suggested value to be used for VirtualBox. Depending on the description type,
3262 the aExtraConfigValues[] array item may also be used.
3263
3264 <ul>
3265 <li>
3266 "OS": the guest operating system type. There must be exactly one such array item on import. The
3267 corresponding item in aVboxValues[] contains the suggested guest operating system for VirtualBox.
3268 This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
3269 item in aOvfValues[] will contain a numerical value that described the operating system in the OVF
3270 (see <link to="CIMOSType" />).
3271 </li>
3272 <li>
3273 "Name": the name to give to the new virtual machine. There can be at most one such array item;
3274 if none is present on import, then an automatic name will be created from the operating system
3275 type. The correponding item im aOvfValues[] will contain the suggested virtual machine name
3276 from the OVF file, and aVboxValues[] will contain a suggestion for a unique VirtualBox
3277 <link to="IMachine" /> name that does not exist yet.
3278 </li>
3279 <li>
3280 "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
3281 </li>
3282 <li>
3283 "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
3284 is present on import, then VirtualBox will set a meaningful default based on the operating system
3285 type.
3286 </li>
3287 <li>
3288 "HarddiskControllerIDE": an IDE hard disk controller. There can be at most one such item. This
3289 has no value in aOvfValues[] or aVboxValues[].
3290 The matching item in the aRefs[] array will contain an integer that items of the "Harddisk"
3291 type can use to specify which hard disk controller a virtual disk should be connected to.
3292 </li>
3293 <li>
3294 "HarddiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
3295 has no value in aOvfValues[] or aVboxValues[].
3296 The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3297 </li>
3298 <li>
3299 "HarddiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
3300 The items in aOvfValues[] and aVboxValues[] will either be "LsiLogic" or "BusLogic".
3301 The matching item in the aRefs[] array will be used as with IDE controllers (see above).
3302 </li>
3303 <li>
3304 "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
3305 arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
3306
3307 The array item in aOvfValues[] will contain the file specification from the OVF file (without
3308 a path since the image file should be in the same location as the OVF file itself), whereas the
3309 item in aVboxValues[] will contain a qualified path specification to where VirtualBox uses the
3310 hard disk image. This means that on import the image will be copied and converted from the
3311 "ovf" location to the "vbox" location; on export, this will be handled the other way round.
3312 On import, the target image will also be registered with VirtualBox.
3313
3314 The matching item in the aExtraConfigValues[] array must contain a string of the following
3315 format: "controller=&lt;index&gt;;channel=&lt;c&gt;"
3316 In this string, &lt;index&gt; must be an integer specifying the hard disk controller to connect
3317 the image to. That number must be the index of an array item with one of the hard disk controller
3318 types (HarddiskControllerSCSI, HarddiskControllerSATA, HarddiskControllerIDE).
3319 In addition, &lt;c&gt; must specify the channel to use on that controller. For IDE controllers,
3320 this can range from 0-2 (which VirtualBox will interpret as primary master, primary slave,
3321 secondary slave; VirtualBox reserves the secondary master for the CD-ROM drive). For SATA and
3322 SCSI conrollers, the channel can range from 0-29.
3323 </li>
3324 <li>
3325 "NetworkAdapter": a network adapter. The array item in aVboxValues[] will specify the hardware
3326 for the network adapter, whereas the array item in aExtraConfigValues[] will have a string
3327 of the "type=&lt;X&gt;" format, where &lt;X&gt; must be either "NAT" or "Bridged".
3328 </li>
3329 <li>
3330 "USBController": a USB controller. There can be at most one such item. If and only if such an
3331 item ispresent, USB support will be enabled for the new virtual machine.
3332 </li>
3333 <li>
3334 "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
3335 present, sound support will be enabled for the new virtual machine. Note that the virtual
3336 machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
3337 may be different from the virtual soundcard expected by the appliance.
3338 </li>
3339 </ul>
3340
3341 </desc>
3342
3343 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3344 <desc></desc>
3345 </param>
3346
3347 <param name="aRefs" type="wstring" dir="out" safearray="yes">
3348 <desc></desc>
3349 </param>
3350
3351 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3352 <desc></desc>
3353 </param>
3354
3355 <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
3356 <desc></desc>
3357 </param>
3358
3359 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3360 <desc></desc>
3361 </param>
3362
3363 </method>
3364
3365 <method name="getDescriptionByType">
3366 <desc>This is the same as <link to="getDescription" /> except that you can specify which types
3367 should be returned.</desc>
3368
3369 <param name="aType" type="VirtualSystemDescriptionType" dir="in">
3370 <desc></desc>
3371 </param>
3372
3373 <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
3374 <desc></desc>
3375 </param>
3376
3377 <param name="aRefs" type="wstring" dir="out" safearray="yes">
3378 <desc></desc>
3379 </param>
3380
3381 <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
3382 <desc></desc>
3383 </param>
3384
3385 <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
3386 <desc></desc>
3387 </param>
3388
3389 <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
3390 <desc></desc>
3391 </param>
3392
3393 </method>
3394
3395 <method name="setFinalValues">
3396 <desc>
3397 This method allows the appliance's user to change the configuration for the virtual
3398 system descriptions. For each array item returned from <link to="getDescription" />,
3399 you must pass in one boolean value and one configuration value.
3400
3401 Each item in the boolean array determines whether the particular configuration item
3402 should be enabled.
3403 You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
3404 HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
3405 and SoundCard.
3406
3407 For the "vbox" and "extra configuration" values, if you pass in the same arrays
3408 as returned in the aVboxValues and aExtraConfigValues arrays from getDescription(),
3409 the configuration remains unchanged. Please see the documentation for getDescription()
3410 for valid configuration values for the individual array item types. If the
3411 corresponding item in the aEnabled array is false, the configuration value is ignored.
3412 </desc>
3413
3414 <param name="aEnabled" type="boolean" dir="in" safearray="yes">
3415 <desc></desc>
3416 </param>
3417
3418 <param name="aVboxValues" type="wstring" dir="in" safearray="yes">
3419 <desc></desc>
3420 </param>
3421
3422 <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
3423 <desc></desc>
3424 </param>
3425 </method>
3426 </interface>
3427
3428
3429 <!--
3430 // IMachine
3431 /////////////////////////////////////////////////////////////////////////
3432 -->
3433
3434 <interface
3435 name="IInternalMachineControl" extends="$unknown"
3436 uuid="2c88b969-7a74-4ef3-b95f-8a209a1535f3"
3437 internal="yes"
3438 wsmap="suppress"
3439 >
3440 <method name="updateState">
3441 <desc>
3442 Updates the VM state.
3443 <note>
3444 This operation will also update the settings file with
3445 the correct information about the saved state file
3446 and delete this file from disk when appropriate.
3447 </note>
3448 </desc>
3449 <param name="state" type="MachineState" dir="in"/>
3450 </method>
3451
3452 <method name="getIPCId">
3453 <param name="id" type="wstring" dir="return"/>
3454 </method>
3455
3456 <method name="runUSBDeviceFilters">
3457 <desc>
3458 Asks the server to run USB devices filters of the associated
3459 machine against the given USB device and tell if there is
3460 a match.
3461 <note>
3462 Intended to be used only for remote USB devices. Local
3463 ones don't require to call this method (this is done
3464 implicitly by the Host and USBProxyService).
3465 </note>
3466 </desc>
3467 <param name="device" type="IUSBDevice" dir="in"/>
3468 <param name="matched" type="boolean" dir="out"/>
3469 <param name="maskedInterfaces" type="unsigned long" dir="out"/>
3470 </method>
3471
3472 <method name="captureUSBDevice">
3473 <desc>
3474 Requests a capture of the given host USB device.
3475 When the request is completed, the VM process will
3476 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3477 notification.
3478 </desc>
3479 <param name="id" type="uuid" dir="in"/>
3480 </method>
3481
3482 <method name="detachUSBDevice">
3483 <desc>
3484 Notification that a VM is going to detach (done = false) or has
3485 already detached (done = true) the given USB device.
3486 When the done = true request is completed, the VM process will
3487 get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
3488 notification.
3489 <note>
3490 In the done = true case, the server must run its own filters
3491 and filters of all VMs but this one on the detached device
3492 as if it were just attached to the host computer.
3493 </note>
3494 </desc>
3495 <param name="id" type="uuid" dir="in"/>
3496 <param name="done" type="boolean" dir="in"/>
3497 </method>
3498
3499 <method name="autoCaptureUSBDevices">
3500 <desc>
3501 Requests a capture all matching USB devices attached to the host.
3502 When the request is completed, the VM process will
3503 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
3504 notification per every captured device.
3505 </desc>
3506 </method>
3507
3508 <method name="detachAllUSBDevices">
3509 <desc>
3510 Notification that a VM that is being powered down. The done
3511 parameter indicates whether which stage of the power down
3512 we're at. When done = false the VM is announcing its
3513 intentions, while when done = true the VM is reporting
3514 what it has done.
3515 <note>
3516 In the done = true case, the server must run its own filters
3517 and filters of all VMs but this one on all detach devices as
3518 if they were just attached to the host computer.
3519 </note>
3520 </desc>
3521 <param name="done" type="boolean" dir="in"/>
3522 </method>
3523
3524 <method name="onSessionEnd">
3525 <desc>
3526 Triggered by the given session object when the session is about
3527 to close normally.
3528 </desc>
3529 <param name="session" type="ISession" dir="in">
3530 <desc>Session that is being closed</desc>
3531 </param>
3532 <param name="progress" type="IProgress" dir="return">
3533 <desc>
3534 Used to wait until the corresponding machine is actually
3535 dissociated from the given session on the server.
3536 Returned only when this session is a direct one.
3537 </desc>
3538 </param>
3539 </method>
3540
3541 <method name="beginSavingState">
3542 <desc>
3543 Called by the VM process to inform the server it wants to
3544 save the current state and stop the VM execution.
3545 </desc>
3546 <param name="progress" type="IProgress" dir="in">
3547 <desc>
3548 Progress object created by the VM process to wait until
3549 the state is saved.
3550 </desc>
3551 </param>
3552 <param name="stateFilePath" type="wstring" dir="out">
3553 <desc>
3554 File path the VM process must save the execution state to.
3555 </desc>
3556 </param>
3557 </method>
3558
3559 <method name="endSavingState">
3560 <desc>
3561 Called by the VM process to inform the server that saving
3562 the state previously requested by #beginSavingState is either
3563 successfully finished or there was a failure.
3564
3565 <result name="VBOX_E_FILE_ERROR">
3566 Settings file not accessible.
3567 </result>
3568 <result name="VBOX_E_XML_ERROR">
3569 Could not parse the settings file.
3570 </result>
3571
3572 </desc>
3573
3574 <param name="success" type="boolean" dir="in">
3575 <desc><tt>true</tt> to indicate success and <tt>false</tt>
3576 otherwise.
3577 </desc>
3578 </param>
3579 </method>
3580
3581 <method name="adoptSavedState">
3582 <desc>
3583 Gets called by IConsole::adoptSavedState.
3584 <result name="VBOX_E_FILE_ERROR">
3585 Invalid saved state file path.
3586 </result>
3587 </desc>
3588 <param name="savedStateFile" type="wstring" dir="in">
3589 <desc>Path to the saved state file to adopt.</desc>
3590 </param>
3591 </method>
3592
3593 <method name="beginTakingSnapshot">
3594 <desc>
3595 Called by the VM process to inform the server it wants to
3596 take a snapshot.
3597
3598 <result name="VBOX_E_FILE_ERROR">
3599 Settings file not accessible.
3600 </result>
3601 <result name="VBOX_E_XML_ERROR">
3602 Could not parse the settings file.
3603 </result>
3604 </desc>
3605 <param name="initiator" type="IConsole" dir="in">
3606 <desc>The console object that initiated this call.</desc>
3607 </param>
3608 <param name="name" type="wstring" dir="in">
3609 <desc>Snapshot name.</desc>
3610 </param>
3611 <param name="description" type="wstring" dir="in">
3612 <desc>Snapshot description.</desc>
3613 </param>
3614 <param name="progress" type="IProgress" dir="in">
3615 <desc>
3616 Progress object created by the VM process to wait until
3617 the state is saved (only for online snapshots).
3618 </desc>
3619 </param>
3620 <param name="stateFilePath" type="wstring" dir="out">
3621 <desc>
3622 File path the VM process must save the execution state to.
3623 </desc>
3624 </param>
3625 <param name="serverProgress" type="IProgress" dir="out">
3626 <desc>
3627 Progress object created by the server process to wait until
3628 the snapshot is taken (VDI diff creation, etc.).
3629 </desc>
3630 </param>
3631 </method>
3632
3633 <method name="endTakingSnapshot">
3634 <desc>
3635 Called by the VM process to inform the server that the snapshot
3636 previously requested by #beginTakingSnapshot is either
3637 successfully taken or there was a failure.
3638 </desc>
3639
3640 <param name="success" type="boolean" dir="in">
3641 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
3642 </param>
3643 </method>
3644
3645 <method name="discardSnapshot">
3646 <desc>
3647 Gets called by IConsole::discardSnapshot.
3648 <result name="VBOX_E_INVALID_OBJECT_STATE">
3649 Snapshot has more than one child snapshot.
3650 </result>
3651 </desc>
3652 <param name="initiator" type="IConsole" dir="in">
3653 <desc>The console object that initiated this call.</desc>
3654 </param>
3655 <param name="id" type="uuid" dir="in">
3656 <desc>UUID of the snapshot to discard.</desc>
3657 </param>
3658 <param name="machineState" type="MachineState" dir="out">
3659 <desc>New machine state after this operation is started.</desc>
3660 </param>
3661 <param name="progress" type="IProgress" dir="return">
3662 <desc>Progress object to track the operation completion.</desc>
3663 </param>
3664 </method>
3665
3666 <method name="discardCurrentState">
3667 <desc>
3668 Gets called by IConsole::discardCurrentState.
3669 <result name="VBOX_E_INVALID_OBJECT_STATE">
3670 Virtual machine does not have any snapshot.
3671 </result>
3672 </desc>
3673 <param name="initiator" type="IConsole" dir="in">
3674 <desc>The console object that initiated this call.</desc>
3675 </param>
3676 <param name="machineState" type="MachineState" dir="out">
3677 <desc>New machine state after this operation is started.</desc>
3678 </param>
3679 <param name="progress" type="IProgress" dir="return">
3680 <desc>Progress object to track the operation completion.</desc>
3681 </param>
3682 </method>
3683
3684 <method name="discardCurrentSnapshotAndState">
3685 <desc>
3686 Gets called by IConsole::discardCurrentSnapshotAndState.
3687 <result name="VBOX_E_INVALID_OBJECT_STATE">
3688 Virtual machine does not have any snapshot.
3689 </result>
3690 </desc>
3691 <param name="initiator" type="IConsole" dir="in">
3692 <desc>The console object that initiated this call.</desc>
3693 </param>
3694 <param name="machineState" type="MachineState" dir="out">
3695 <desc>New machine state after this operation is started.</desc>
3696 </param>
3697 <param name="progress" type="IProgress" dir="return">
3698 <desc>Progress object to track the operation completion.</desc>
3699 </param>
3700 </method>
3701
3702 <method name="pullGuestProperties">
3703 <desc>
3704 Get the list of the guest properties matching a set of patterns along
3705 with their values, time stamps and flags and give responsibility for
3706 managing properties to the console.
3707 </desc>
3708 <param name="name" type="wstring" dir="out" safearray="yes">
3709 <desc>
3710 The names of the properties returned.
3711 </desc>
3712 </param>
3713 <param name="value" type="wstring" dir="out" safearray="yes">
3714 <desc>
3715 The values of the properties returned. The array entries match the
3716 corresponding entries in the @a name array.
3717 </desc>
3718 </param>
3719 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3720 <desc>
3721 The time stamps of the properties returned. The array entries match
3722 the corresponding entries in the @a name array.
3723 </desc>
3724 </param>
3725 <param name="flags" type="wstring" dir="out" safearray="yes">
3726 <desc>
3727 The flags of the properties returned. The array entries match the
3728 corresponding entries in the @a name array.
3729 </desc>
3730 </param>
3731 </method>
3732
3733 <method name="pushGuestProperties">
3734 <desc>
3735 Set the list of the guest properties matching a set of patterns along
3736 with their values, time stamps and flags and return responsibility for
3737 managing properties to IMachine.
3738 </desc>
3739 <param name="name" type="wstring" dir="in" safearray="yes">
3740 <desc>
3741 The names of the properties.
3742 </desc>
3743 </param>
3744 <param name="value" type="wstring" dir="in" safearray="yes">
3745 <desc>
3746 The values of the properties. The array entries match the
3747 corresponding entries in the @a name array.
3748 </desc>
3749 </param>
3750 <param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
3751 <desc>
3752 The time stamps of the properties. The array entries match
3753 the corresponding entries in the @a name array.
3754 </desc>
3755 </param>
3756 <param name="flags" type="wstring" dir="in" safearray="yes">
3757 <desc>
3758 The flags of the properties. The array entries match the
3759 corresponding entries in the @a name array.
3760 </desc>
3761 </param>
3762 </method>
3763 <method name="pushGuestProperty">
3764 <desc>
3765 Update a single guest property in IMachine.
3766 </desc>
3767 <param name="name" type="wstring" dir="in">
3768 <desc>
3769 The name of the property to be updated.
3770 </desc>
3771 </param>
3772 <param name="value" type="wstring" dir="in">
3773 <desc>
3774 The value of the property.
3775 </desc>
3776 </param>
3777 <param name="timestamp" type="unsigned long long" dir="in">
3778 <desc>
3779 The timestamp of the property.
3780 </desc>
3781 </param>
3782 <param name="flags" type="wstring" dir="in">
3783 <desc>
3784 The flags of the property.
3785 </desc>
3786 </param>
3787 </method>
3788
3789 <method name="lockMedia">
3790 <desc>
3791 Locks all media attached to the machine for writing and parents of
3792 attahced different hard disks (if any) for reading. This operation is
3793 atomic so that if it fails no media is actually locked.
3794
3795 This method is intended to be called when the machine is in Starting or
3796 Restoring state. The locked media will be automatically unlocked when
3797 the machine is powered off or crashed.
3798 </desc>
3799 </method>
3800 </interface>
3801
3802 <interface
3803 name="IBIOSSettings" extends="$unknown"
3804 uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
3805 wsmap="managed"
3806 >
3807 <desc>
3808 The IBIOSSettings interface represents BIOS settings of the virtual
3809 machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
3810 </desc>
3811 <attribute name="logoFadeIn" type="boolean">
3812 <desc>Fade in flag for BIOS logo animation.</desc>
3813 </attribute>
3814
3815 <attribute name="logoFadeOut" type="boolean">
3816 <desc>Fade out flag for BIOS logo animation.</desc>
3817 </attribute>
3818
3819 <attribute name="logoDisplayTime" type="unsigned long">
3820 <desc>BIOS logo display time in milliseconds (0 = default).</desc>
3821 </attribute>
3822
3823 <attribute name="logoImagePath" type="wstring">
3824 <desc>Local file system path for external BIOS image.</desc>
3825 </attribute>
3826
3827 <attribute name="bootMenuMode" type="BIOSBootMenuMode">
3828 <desc>Mode of the BIOS boot device menu.</desc>
3829 </attribute>
3830
3831 <attribute name="ACPIEnabled" type="boolean">
3832 <desc>ACPI support flag.</desc>
3833 </attribute>
3834
3835 <attribute name="IOAPICEnabled" type="boolean">
3836 <desc>
3837 IO APIC support flag. If set, VirtualBox will provide an IO APIC
3838 and support IRQs above 15.
3839 </desc>
3840 </attribute>
3841
3842 <attribute name="timeOffset" type="long long">
3843 <desc>
3844 Offset in milliseconds from the host system time. This allows for
3845 guests running with a different system date/time than the host.
3846 It is equivalent to setting the system date/time in the BIOS except
3847 it is not an absolute value but a relative one. Guest Additions
3848 time synchronization honors this offset.
3849 </desc>
3850 </attribute>
3851
3852 <attribute name="PXEDebugEnabled" type="boolean">
3853 <desc>
3854 PXE debug logging flag. If set, VirtualBox will write extensive
3855 PXE trace information to the release log.
3856 </desc>
3857 </attribute>
3858
3859 </interface>
3860
3861 <interface
3862 name="IMachine" extends="$unknown"
3863 uuid="dcf6a64c-1466-4b5a-b822-9db04133dc74"
3864 wsmap="managed"
3865 >
3866 <desc>
3867 The IMachine interface represents a virtual machine, or guest, created
3868 in VirtualBox.
3869
3870 This interface is used in two contexts. First of all, a collection of
3871 objects implementing this interface is stored in the
3872 <link to="IVirtualBox::machines"/> attribute which lists all the virtual
3873 machines that are currently registered with this VirtualBox
3874 installation. Also, once a session has been opened for the given virtual
3875 machine (e.g. the virtual machine is running), the machine object
3876 associated with the open session can be queried from the session object;
3877 see <link to="ISession"/> for details.
3878
3879 The main role of this interface is to expose the settings of the virtual
3880 machine and provide methods to change various aspects of the virtual
3881 machine's configuration. For machine objects stored in the
3882 <link to="IVirtualBox::machines"/> collection, all attributes are
3883 read-only unless explicitly stated otherwise in individual attribute
3884 and method descriptions. In order to change a machine setting, a session
3885 for this machine must be opened using one of
3886 <link to="IVirtualBox::openSession"/>,
3887 <link to="IVirtualBox::openRemoteSession"/> or
3888 <link to="IVirtualBox::openExistingSession"/> methods. After the
3889 session has been successfully opened, a mutable machine object needs to
3890 be queried from the session object and then the desired settings changes
3891 can be applied to the returned object using IMachine attributes and
3892 methods. See the ISession interface description for more information
3893 about sessions.
3894
3895 Note that the IMachine interface does not provide methods to control
3896 virtual machine execution (such as start the machine, or power it
3897 down) -- these methods are grouped in a separate IConsole
3898 interface. Refer to the IConsole interface description to get more
3899 information about this topic.
3900
3901 <see>ISession, IConsole</see>
3902 </desc>
3903
3904 <attribute name="parent" type="IVirtualBox" readonly="yes">
3905 <desc>Associated parent object.</desc>
3906 </attribute>
3907
3908 <attribute name="accessible" type="boolean" readonly="yes">
3909 <desc>
3910 Whether this virtual machine is currently accessible or not.
3911
3912 The machine is considered to be inaccessible when:
3913 <ul>
3914 <li>It is a registered virtual machine, and
3915 </li>
3916 <li>Its settings file is inaccessible (for example, it is
3917 located on a network share that is not accessible during
3918 VirtualBox startup, or becomes inaccessible later, or if
3919 the settings file can be read but is invalid).
3920 </li>
3921 </ul>
3922
3923 Otherwise, the value of this property is always <tt>true</tt>.
3924
3925 Every time this property is read, the accessibility state of
3926 this machine is re-evaluated. If the returned value is |false|,
3927 the <link to="#accessError"/> property may be used to get the
3928 detailed error information describing the reason of
3929 inaccessibility.
3930
3931 When the machine is inaccessible, only the following properties
3932 can be used on it:
3933 <ul>
3934 <li><link to="#parent"/></li>
3935 <li><link to="#id"/></li>
3936 <li><link to="#settingsFilePath"/></li>
3937 <li><link to="#accessible"/></li>
3938 <li><link to="#accessError"/></li>
3939 </ul>
3940
3941 An attempt to access any other property or method will return
3942 an error.
3943
3944 The only possible action you can perform on an inaccessible
3945 machine is to unregister it using the
3946 <link to="IVirtualBox::unregisterMachine"/> call (or, to check
3947 for the accessibility state once more by querying this
3948 property).
3949
3950 <note>
3951 In the current implementation, once this property returns
3952 <tt>true</tt>, the machine will never become inaccessible
3953 later, even if its settings file cannot be successfully
3954 read/written any more (at least, until the VirtualBox
3955 server is restarted). This limitation may be removed in
3956 future releases.
3957 </note>
3958 </desc>
3959 </attribute>
3960
3961 <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
3962 <desc>
3963 Error information describing the reason of machine
3964 inaccessibility.
3965
3966 Reading this property is only valid after the last call to
3967 <link to="#accessible"/> returned <tt>false</tt> (i.e. the
3968 machine is currently unaccessible). Otherwise, a null
3969 IVirtualBoxErrorInfo object will be returned.
3970 </desc>
3971 </attribute>
3972
3973 <attribute name="name" type="wstring">
3974 <desc>
3975 Name of the virtual machine.
3976
3977 Besides being used for human-readable identification purposes
3978 everywhere in VirtualBox, the virtual machine name is also used
3979 as a name of the machine's settings file and as a name of the
3980 subdirectory this settings file resides in. Thus, every time you
3981 change the value of this property, the settings file will be
3982 renamed once you call <link to="#saveSettings"/> to confirm the
3983 change. The containing subdirectory will be also renamed, but
3984 only if it has exactly the same name as the settings file
3985 itself prior to changing this property (for backward compatibility
3986 with previous API releases). The above implies the following
3987 limitations:
3988 <ul>
3989 <li>The machine name cannot be empty.</li>
3990 <li>The machine name can contain only characters that are valid
3991 file name characters according to the rules of the file
3992 system used to store VirtualBox configuration.</li>
3993 <li>You cannot have two or more machines with the same name
3994 if they use the same subdirectory for storing the machine
3995 settings files.</li>
3996 <li>You cannot change the name of the machine if it is running,
3997 or if any file in the directory containing the settings file
3998 is being used by another running machine or by any other
3999 process in the host operating system at a time when
4000 <link to="#saveSettings"/> is called.
4001 </li>
4002 </ul>
4003 If any of the above limitations are hit, <link to="#saveSettings"/>
4004 will return an appropriate error message explaining the exact
4005 reason and the changes you made to this machine will not be
4006 saved.
4007 <note>
4008 For "legacy" machines created using the
4009 <link to="IVirtualBox::createLegacyMachine"/> call,
4010 the above naming limitations do not apply because the
4011 machine name does not affect the settings file name.
4012 The settings file name remains the same as it was specified
4013 during machine creation and never changes.
4014 </note>
4015 </desc>
4016 </attribute>
4017
4018 <attribute name="description" type="wstring">
4019 <desc>
4020 Description of the virtual machine.
4021
4022 The description attribute can contain any text and is
4023 typically used to describe the hardware and software
4024 configuration of the virtual machine in detail (i.e. network
4025 settings, versions of the installed software and so on).
4026 </desc>
4027 </attribute>
4028
4029 <attribute name="id" type="uuid" readonly="yes">
4030 <desc>UUID of the virtual machine.</desc>
4031 </attribute>
4032
4033 <attribute name="OSTypeId" type="wstring">
4034 <desc>
4035 User-defined identifier of the Guest OS type.
4036 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
4037 an IGuestOSType object representing details about the given
4038 Guest OS type.
4039 <note>
4040 This value may differ from the value returned by
4041 <link to="IGuest::OSTypeId"/> if Guest Additions are
4042 installed to the guest OS.
4043 </note>
4044 </desc>
4045 </attribute>
4046
4047 <attribute name="HardwareVersion" type="wstring">
4048 <desc>Hardware version identifier. Internal use only for now.</desc>
4049 </attribute>
4050
4051 <attribute name="CPUCount" type="unsigned long">
4052 <desc>Number of virtual CPUs in the VM. In the current version of the product, this is always 1.</desc>
4053 </attribute>
4054
4055 <attribute name="memorySize" type="unsigned long">
4056 <desc>System memory size in megabytes.</desc>
4057 </attribute>
4058
4059 <attribute name="memoryBalloonSize" type="unsigned long">
4060 <desc>Initial memory balloon size in megabytes.</desc>
4061 </attribute>
4062
4063 <attribute name="statisticsUpdateInterval" type="unsigned long">
4064 <desc>Initial interval to update guest statistics in seconds.</desc>
4065 </attribute>
4066
4067 <attribute name="VRAMSize" type="unsigned long">
4068 <desc>Video memory size in megabytes.</desc>
4069 </attribute>
4070
4071 <attribute name="accelerate3DEnabled" type="boolean" default="false">
4072 <desc>
4073 This setting determines whether VirtualBox allows guests to make use
4074 of the 3D graphics support available on the host. Currently limited
4075 to OpenGL only. </desc>
4076 </attribute>
4077
4078 <attribute name="monitorCount" type="unsigned long">
4079 <desc>
4080 Number of virtual monitors.
4081 <note>
4082 Only effective on Windows XP and later guests with
4083 Guest Additions installed.
4084 </note>
4085 </desc>
4086 </attribute>
4087
4088 <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
4089 <desc>Object containing all BIOS settings.</desc>
4090 </attribute>
4091
4092 <attribute name="HWVirtExEnabled" type="TSBool">
4093 <desc>
4094 This setting determines whether VirtualBox will try to make use of
4095 the host CPU's hardware virtualization extensions such as Intel VT-x
4096 and AMD-V. Note that in case such extensions are not available,
4097 they will not be used.
4098 </desc>
4099 </attribute>
4100
4101 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">
4102 <desc>
4103 This setting determines whether VirtualBox will try to make use of
4104 the nested paging extension of Intel VT-x and AMD-V. Note that in case
4105 such extensions are not available, they will not be used.
4106 </desc>
4107 </attribute>
4108
4109 <attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">
4110 <desc>
4111 This setting determines whether VirtualBox will try to make use of
4112 the VPID extension of Intel VT-x. Note that in case such extensions are
4113 not available, they will not be used.
4114 </desc>
4115 </attribute>
4116
4117 <attribute name="PAEEnabled" type="boolean" default="false">
4118 <desc>
4119 This setting determines whether VirtualBox will expose the Physical Address
4120 Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
4121 is not available, it will not be reported.
4122 </desc>
4123 </attribute>
4124
4125 <attribute name="snapshotFolder" type="wstring">
4126 <desc>
4127 Full path to the directory used to store snapshot data
4128 (differencing hard disks and saved state files) of this machine.
4129
4130 The initial value of this property is
4131 <tt>&lt;</tt><link to="#settingsFilePath">
4132 path_to_settings_file</link><tt>&gt;/&lt;</tt>
4133 <link to="#id">machine_uuid</link>
4134 <tt>&gt;</tt>.
4135
4136 Currently, it is an error to try to change this property on
4137 a machine that has snapshots (because this would require to
4138 move possibly large files to a different location).
4139 A separate method will be available for this purpose later.
4140
4141 <note>
4142 Setting this property to <tt>null</tt> will restore the
4143 initial value.
4144 </note>
4145 <note>
4146 When setting this property, the specified path can be
4147 absolute (full path) or relative to the directory where the
4148 <link to="#settingsFilePath">machine settings file</link>
4149 is located. When reading this property, a full path is
4150 always returned.
4151 </note>
4152 <note>
4153 The specified path may not exist, it will be created
4154 when necessary.
4155 </note>
4156 </desc>
4157 </attribute>
4158
4159 <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
4160 <desc>VRDP server object.</desc>
4161 </attribute>
4162
4163 <attribute name="hardDiskAttachments" type="IHardDiskAttachment" readonly="yes" safearray="yes">
4164 <desc>Array of hard disks attached to this machine.</desc>
4165 </attribute>
4166
4167 <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
4168 <desc>Associated DVD drive object.</desc>
4169 </attribute>
4170
4171 <attribute name="floppyDrive" type="IFloppyDrive" readonly="yes">
4172 <desc>Associated floppy drive object.</desc>
4173 </attribute>
4174
4175 <attribute name="USBController" type="IUSBController" readonly="yes">
4176 <desc>
4177 Associated USB controller object.
4178
4179 <note>
4180 This method may set a @ref com_warnings "warning result code".
4181 </note>
4182 <note>
4183 If USB functionality is not available in the given edition of
4184 VirtualBox, this method will set the result code to @c E_NOTIMPL.
4185 </note>
4186 </desc>
4187 </attribute>
4188
4189 <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
4190 <desc>Associated audio adapter, always present.</desc>
4191 </attribute>
4192
4193 <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
4194 <desc>Array of storage controllers attached to this machine.</desc>
4195 </attribute>
4196
4197 <attribute name="settingsFilePath" type="wstring" readonly="yes">
4198 <desc>
4199 Full name of the file containing machine settings data.
4200 </desc>
4201 </attribute>
4202
4203 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
4204 <desc>
4205 Current version of the format of the settings file of this machine
4206 (<link to="#settingsFilePath"/>).
4207
4208 The version string has the following format:
4209 <pre>
4210 x.y-platform
4211 </pre>
4212 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
4213 versions, and <tt>platform</tt> is the platform identifier.
4214
4215 The current version usually matches the value of the
4216 <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
4217 settings file was created by an older version of VirtualBox and there
4218 was a change of the settings file format since then.
4219
4220 Note that VirtualBox automatically converts settings files from older
4221 versions to the most recent version when reading them (usually at
4222 VirtualBox startup) but it doesn't save the changes back until
4223 you call a method that implicitly saves settings (such as
4224 <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
4225 explicitly. Therefore, if the value of this attribute differs from the
4226 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
4227 means that the settings file was converted but the result of the
4228 conversion is not yet saved to disk.
4229
4230 The above feature may be used by interactive front-ends to inform users
4231 about the settings file format change and offer them to explicitly save
4232 all converted settings files (the global and VM-specific ones),
4233 optionally create backup copies of the old settings files before saving,
4234 etc.
4235
4236 <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
4237 </desc>
4238 </attribute>
4239
4240 <attribute name="settingsModified" type="boolean" readonly="yes">
4241 <desc>
4242 Whether the settings of this machine have been modified
4243 (but neither yet saved nor discarded).
4244 <note>
4245 Reading this property is only valid on instances returned
4246 by <link to="ISession::machine"/> and on new machines
4247 created by <link to="IVirtualBox::createMachine"/> or opened
4248 by <link to="IVirtualBox::openMachine"/> but not
4249 yet registered, or on unregistered machines after calling
4250 <link to="IVirtualBox::unregisterMachine"/>. For all other
4251 cases, the settings can never be modified.
4252 </note>
4253 <note>
4254 For newly created unregistered machines, the value of this
4255 property is always TRUE until <link to="#saveSettings"/>
4256 is called (no matter if any machine settings have been
4257 changed after the creation or not). For opened machines
4258 the value is set to FALSE (and then follows to normal rules).
4259 </note>
4260 </desc>
4261 </attribute>
4262
4263 <attribute name="sessionState" type="SessionState" readonly="yes">
4264 <desc>Current session state for this machine.</desc>
4265 </attribute>
4266
4267 <attribute name="sessionType" type="wstring" readonly="yes">
4268 <desc>
4269 Type of the session. If <link to="#sessionState"/> is
4270 SessionSpawning or SessionOpen, this attribute contains the
4271 same value as passed to the
4272 <link to="IVirtualBox::openRemoteSession"/> method in the
4273 @a type parameter. If the session was opened directly using
4274 <link to="IVirtualBox::openSession"/>, or if
4275 <link to="#sessionState"/> is SessionClosed, the value of this
4276 attribute is @c null.
4277 </desc>
4278 </attribute>
4279
4280 <attribute name="sessionPid" type="unsigned long" readonly="yes">
4281 <desc>
4282 Identifier of the session process. This attribute contains the
4283 platform-dependent identifier of the process that has opened a
4284 direct session for this machine using the
4285 <link to="IVirtualBox::openSession"/> call. The returned value
4286 is only valid if <link to="#sessionState"/> is SessionOpen or
4287 SessionClosing (i.e. a session is currently open or being
4288 closed) by the time this property is read.
4289 </desc>
4290 </attribute>
4291
4292 <attribute name="state" type="MachineState" readonly="yes">
4293 <desc>Current execution state of this machine.</desc>
4294 </attribute>
4295
4296 <attribute name="lastStateChange" type="long long" readonly="yes">
4297 <desc>
4298 Time stamp of the last execution state change,
4299 in milliseconds since 1970-01-01 UTC.
4300 </desc>
4301 </attribute>
4302
4303 <attribute name="stateFilePath" type="wstring" readonly="yes">
4304 <desc>
4305 Full path to the file that stores the execution state of
4306 the machine when it is in the <link to="MachineState_Saved"/> state.
4307 <note>
4308 When the machine is not in the Saved state, this attribute
4309 <tt>null</tt>.
4310 </note>
4311 </desc>
4312 </attribute>
4313
4314 <attribute name="logFolder" type="wstring" readonly="yes">
4315 <desc>
4316 Full path to the folder that stores a set of rotated log files
4317 recorded during machine execution. The most recent log file is
4318 named <tt>VBox.log</tt>, the previous log file is
4319 named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
4320 in the current version).
4321 </desc>
4322 </attribute>
4323
4324 <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
4325 <desc>
4326 Current snapshot of this machine.
4327 <note>
4328 A <tt>null</tt> object is returned if the machine doesn't
4329 have snapshots.
4330 </note>
4331 <see><link to="ISnapshot"/></see>
4332 </desc>
4333 </attribute>
4334
4335 <attribute name="snapshotCount" type="unsigned long" readonly="yes">
4336 <desc>
4337 Number of snapshots taken on this machine. Zero means the
4338 machine doesn't have any snapshots.
4339 </desc>
4340 </attribute>
4341
4342 <attribute name="currentStateModified" type="boolean" readonly="yes">
4343 <desc>
4344 Returns <tt>true</tt> if the current state of the machine is not
4345 identical to the state stored in the current snapshot.
4346
4347 The current state is identical to the current snapshot right
4348 after one of the following calls are made:
4349 <ul>
4350 <li><link to="IConsole::discardCurrentState"/> or
4351 <link to="IConsole::discardCurrentSnapshotAndState"/>
4352 </li>
4353 <li><link to="IConsole::takeSnapshot"/> (issued on a
4354 powered off or saved machine, for which
4355 <link to="#settingsModified"/> returns <tt>false</tt>)
4356 </li>
4357 <li><link to="IMachine::setCurrentSnapshot"/>
4358 </li>
4359 </ul>
4360
4361 The current state remains identical until one of the following
4362 happens:
4363 <ul>
4364 <li>settings of the machine are changed</li>
4365 <li>the saved state is discarded</li>
4366 <li>the current snapshot is discarded</li>
4367 <li>an attempt to execute the machine is made</li>
4368 </ul>
4369
4370 <note>
4371 For machines that don't have snapshots, this property is
4372 always <tt>false</tt>.
4373 </note>
4374 </desc>
4375 </attribute>
4376
4377 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
4378 <desc>
4379 Collection of shared folders for this machine (permanent shared
4380 folders). These folders are shared automatically at machine startup
4381 and available only to the guest OS installed within this machine.
4382
4383 New shared folders are added to the collection using
4384 <link to="#createSharedFolder"/>. Existing shared folders can be
4385 removed using <link to="#removeSharedFolder"/>.
4386 </desc>
4387 </attribute>
4388
4389 <attribute name="clipboardMode" type="ClipboardMode">
4390 <desc>
4391 Synchronization mode between the host OS clipboard
4392 and the guest OS clipboard.
4393 </desc>
4394 </attribute>
4395
4396 <attribute name="guestPropertyNotificationPatterns" type="wstring">
4397 <desc>
4398 A comma-separated list of simple glob patterns. Changes to guest
4399 properties whose name matches one of the patterns will generate an
4400 <link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
4401 </desc>
4402 </attribute>
4403
4404 <method name="setBootOrder">
4405 <desc>
4406 Puts the given device to the specified position in
4407 the boot order.
4408
4409 To indicate that no device is associated with the given position,
4410 <link to="DeviceType_Null"/> should be used.
4411
4412 @todo setHardDiskBootOrder(), setNetworkBootOrder()
4413
4414 <result name="E_INVALIDARG">
4415 Boot @a position out of range.
4416 </result>
4417 <result name="E_NOTIMPL">
4418 Booting from USB @a device currently not supported.
4419 </result>
4420
4421 </desc>
4422 <param name="position" type="unsigned long" dir="in">
4423 <desc>
4424 Position in the boot order (<tt>1</tt> to the total number of
4425 devices the machine can boot from, as returned by
4426 <link to="ISystemProperties::maxBootPosition"/>).
4427 </desc>
4428 </param>
4429 <param name="device" type="DeviceType" dir="in">
4430 <desc>
4431 The type of the device used to boot at the given position.
4432 </desc>
4433 </param>
4434 </method>
4435
4436 <method name="getBootOrder" const="yes">
4437 <desc>
4438 Returns the device type that occupies the specified
4439 position in the boot order.
4440
4441 @todo [remove?]
4442 If the machine can have more than one device of the returned type
4443 (such as hard disks), then a separate method should be used to
4444 retrieve the individual device that occupies the given position.
4445
4446 If here are no devices at the given position, then
4447 <link to="DeviceType_Null"/> is returned.
4448
4449 @todo getHardDiskBootOrder(), getNetworkBootOrder()
4450
4451 <result name="E_INVALIDARG">
4452 Boot @a position out of range.
4453 </result>
4454
4455 </desc>
4456 <param name="position" type="unsigned long" dir="in">
4457 <desc>
4458 Position in the boot order (<tt>1</tt> to the total number of
4459 devices the machine can boot from, as returned by
4460 <link to="ISystemProperties::maxBootPosition"/>).
4461 </desc>
4462 </param>
4463 <param name="device" type="DeviceType" dir="return">
4464 <desc>
4465 Device at the given position.
4466 </desc>
4467 </param>
4468 </method>
4469
4470 <method name="attachHardDisk">
4471 <desc>
4472 Attaches a virtual hard disk (<link to="IHardDisk" />, identified
4473 by the given UUID @a id) to the given hard disk controller
4474 (<link to="IStorageController" />, identified by @a name),
4475 at the indicated port and device.
4476
4477 For the IDE bus, the @a controllerPort parameter can be either
4478 @c 0 or @c 1, to specify the primary or secondary IDE controller,
4479 respectively. For the primary controller of the IDE bus,
4480 @a device can be either @c 0 or @c 1, to specify the master or the
4481 slave device, respectively. For the secondary IDE controller, the
4482 device number must be @c 1 because VirtualBox reserves the
4483 secondary master for the CD-ROM drive.
4484
4485 For an SATA controller, @a controllerPort must be a number ranging
4486 from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
4487 be a number ranging from @c 0 to @c 15.
4488
4489 For both SCSI and SATA, the @a device parameter is unused and must
4490 be @c 0.
4491
4492 The specified device slot must not have another disk attached to it, or
4493 this method will fail.
4494
4495 See <link to="IHardDisk"/> for more detailed information about
4496 attaching hard disks.
4497
4498 <note>
4499 You cannot attach a hard disk to a running machine. Also, you cannot
4500 attach a hard disk to a newly created machine until this machine's
4501 settings are saved to disk using <link to="#saveSettings"/>.
4502 </note>
4503 <note>
4504 If the hard disk is being attached indirectly, a new differencing hard
4505 disk will implicitly be created for it and attached instead. If the
4506 changes made to the machine settings (including this indirect
4507 attachment) are later cancelled using <link to="#discardSettings"/>,
4508 this implicitly created differencing hard disk will implicitly
4509 be deleted.
4510 </note>
4511
4512 <result name="E_INVALIDARG">
4513 SATA device, SATA port, IDE port or IDE slot out of range.
4514 </result>
4515 <result name="VBOX_E_INVALID_OBJECT_STATE">
4516 Attempt to attach hard disk to an unregistered virtual machine.
4517 </result>
4518 <result name="VBOX_E_INVALID_VM_STATE">
4519 Invalid machine state.
4520 </result>
4521 <result name="VBOX_E_OBJECT_IN_USE">
4522 Hard disk already attached to this or another virtual machine.
4523 </result>
4524
4525 </desc>
4526 <param name="id" type="uuid" dir="in">
4527 <desc>UUID of the hard disk to attach.</desc>
4528 </param>
4529 <param name="name" type="wstring" dir="in">
4530 <desc>Name of the storage controller to attach the hard disk to.</desc>
4531 </param>
4532 <param name="controllerPort" type="long" dir="in">
4533 <desc>Port to attach the hard disk to.</desc>
4534 </param>
4535 <param name="device" type="long" dir="in">
4536 <desc>
4537 Device slot in the given port to attach the hard disk to.
4538 </desc>
4539 </param>
4540 </method>
4541
4542 <method name="getHardDisk" const="yes">
4543 <desc>
4544 Returns the virtual hard disk attached to a device slot of the specified
4545 bus.
4546
4547 Note that if the hard disk was indirectly attached by
4548 <link to="#attachHardDisk"/> to the given device slot then this
4549 method will return not the same object as passed to the
4550 <link to="#attachHardDisk"/> call. See <link to="IHardDisk"/> for
4551 more detailed information about attaching hard disks.
4552
4553 <result name="VBOX_E_OBJECT_NOT_FOUND">
4554 No hard disk attached to given slot/bus.
4555 </result>
4556
4557 </desc>
4558 <param name="name" type="wstring" dir="in">
4559 <desc>Name of the storage controller the hard disk is attached to.</desc>
4560 </param>
4561 <param name="controllerPort" type="long" dir="in">
4562 <desc>Port to query.</desc>
4563 </param>
4564 <param name="device" type="long" dir="in">
4565 <desc>Device slot in the given port to query.</desc>
4566 </param>
4567 <param name="hardDisk" type="IHardDisk" dir="return">
4568 <desc>Attached hard disk object.</desc>
4569 </param>
4570 </method>
4571
4572 <method name="detachHardDisk">
4573 <desc>
4574 Detaches the virtual hard disk attached to a device slot of the
4575 specified bus.
4576
4577 Detaching the hard disk from the virtual machine is deferred. This means
4578 that the hard disk remains associated with the machine when this method
4579 returns and gets actually de-associated only after a successful
4580 <link to="#saveSettings"/> call. See <link to="IHardDisk"/>
4581 for more detailed information about attaching hard disks.
4582
4583 <note>
4584 You cannot detach the hard disk from a running machine.
4585 </note>
4586 <note>
4587 Detaching differencing hard disks implicitly created by <link
4588 to="#attachHardDisk"/> for the indirect attachment using this
4589 method will <b>not</b> implicitly delete them. The
4590 <link to="IHardDisk::deleteStorage"/> operation should be
4591 explicitly performed by the caller after the hard disk is successfully
4592 detached and the settings are saved with
4593 <link to="#saveSettings"/>, if it is the desired action.
4594 </note>
4595
4596 <result name="VBOX_E_INVALID_VM_STATE">
4597 Attempt to detach hard disk from a running virtual machine.
4598 </result>
4599 <result name="VBOX_E_OBJECT_NOT_FOUND">
4600 No hard disk attached to given slot/bus.
4601 </result>
4602 <result name="VBOX_E_NOT_SUPPORTED">
4603 Hard disk format does not support storage deletion.
4604 </result>
4605
4606 </desc>
4607 <param name="name" type="wstring" dir="in">
4608 <desc>name of the storage controller to detach the hard disk from.</desc>
4609 </param>
4610 <param name="controllerPort" type="long" dir="in">
4611 <desc>Port number to detach the hard disk from.</desc>
4612 </param>
4613 <param name="device" type="long" dir="in">
4614 <desc>Device slot number to detach the hard disk from.</desc>
4615 </param>
4616 </method>
4617
4618 <method name="getHardDiskAttachmentsOfController" const="yes">
4619 <desc>
4620 Returns an array of hard disk attachments which are attached to the
4621 the controller with the given name.
4622
4623 <result name="VBOX_E_OBJECT_NOT_FOUND">
4624 A storage controller with given name doesn't exist.
4625 </result>
4626 </desc>
4627 <param name="name" type="wstring" dir="in"/>
4628 <param name="hardDiskAttachments" type="IHardDiskAttachment" safearray="yes" dir="return"/>
4629 </method>
4630
4631 <method name="getNetworkAdapter" const="yes">
4632 <desc>
4633 Returns the network adapter associated with the given slot.
4634 Slots are numbered sequentially, starting with zero. The total
4635 number of adapters per machine is defined by the
4636 <link to="ISystemProperties::networkAdapterCount"/> property,
4637 so the maximum slot number is one less than that property's value.
4638
4639 <result name="E_INVALIDARG">
4640 Invalid @a slot number.
4641 </result>
4642
4643 </desc>
4644 <param name="slot" type="unsigned long" dir="in"/>
4645 <param name="adapter" type="INetworkAdapter" dir="return"/>
4646 </method>
4647
4648 <method name="addStorageController">
4649 <desc>
4650 Adds a new storage controller (SCSI or SATA controller) to the
4651 machine and returns it as an instance of
4652 <link to="IStorageController" />.
4653
4654 @a name identifies the controller with subsequent calls such as
4655 <link to="#getStorageControllerByName" /> or
4656 <link to="#removeStorageController" /> or
4657 <link to="#attachHardDisk" />.
4658
4659 After the controller has been added, you can set its exact
4660 type by setting the <link to="IStorageController::controllerType" />.
4661
4662 <result name="VBOX_E_OBJECT_IN_USE">
4663 A storage controller with given name exists already.
4664 </result>
4665 <result name="E_INVALIDARG">
4666 Invalid @a controllerType.
4667 </result>
4668 </desc>
4669 <param name="name" type="wstring" dir="in"/>
4670 <param name="connectionType" type="StorageBus" dir="in"/>
4671 <param name="controller" type="IStorageController" dir="return"/>
4672 </method>
4673
4674 <method name="getStorageControllerByName" const="yes">
4675 <desc>
4676 Returns a storage controller with the given name.
4677
4678 <result name="VBOX_E_OBJECT_NOT_FOUND">
4679 A storage controller with given name doesn't exist.
4680 </result>
4681 </desc>
4682 <param name="name" type="wstring" dir="in"/>
4683 <param name="storageController" type="IStorageController" dir="return"/>
4684 </method>
4685
4686 <method name="removeStorageController">
4687 <desc>
4688 Removes a storage controller from the machine.
4689
4690 <result name="VBOX_E_OBJECT_NOT_FOUND">
4691 A storage controller with given name doesn't exist.
4692 </result>
4693 </desc>
4694 <param name="name" type="wstring" dir="in"/>
4695 </method>
4696
4697 <method name="getSerialPort" const="yes">
4698 <desc>
4699 Returns the serial port associated with the given slot.
4700 Slots are numbered sequentially, starting with zero. The total
4701 number of serial ports per machine is defined by the
4702 <link to="ISystemProperties::serialPortCount"/> property,
4703 so the maximum slot number is one less than that property's value.
4704
4705 <result name="E_INVALIDARG">
4706 Invalid @a slot number.
4707 </result>
4708
4709 </desc>
4710 <param name="slot" type="unsigned long" dir="in"/>
4711 <param name="port" type="ISerialPort" dir="return"/>
4712 </method>
4713
4714 <method name="getParallelPort" const="yes">
4715 <desc>
4716 Returns the parallel port associated with the given slot.
4717 Slots are numbered sequentially, starting with zero. The total
4718 number of parallel ports per machine is defined by the
4719 <link to="ISystemProperties::parallelPortCount"/> property,
4720 so the maximum slot number is one less than that property's value.
4721
4722 <result name="E_INVALIDARG">
4723 Invalid @a slot number.
4724 </result>
4725
4726 </desc>
4727 <param name="slot" type="unsigned long" dir="in"/>
4728 <param name="port" type="IParallelPort" dir="return"/>
4729 </method>
4730
4731 <method name="getNextExtraDataKey">
4732 <desc>
4733 Returns the machine-specific extra data key name following the
4734 supplied key.
4735
4736 An error is returned if the supplied @a key does not exist. @c NULL is
4737 returned in @a nextKey if the supplied key is the last key. When
4738 supplying @c NULL for the @a key, the first key item is returned in
4739 @a nextKey (if there is any). @a nextValue is an optional parameter and
4740 if supplied, the next key's value is returned in it.
4741
4742 <result name="VBOX_E_OBJECT_NOT_FOUND">
4743 Extra data @a key not found.
4744 </result>
4745
4746 </desc>
4747 <param name="key" type="wstring" dir="in">
4748 <desc>Name of the data key to follow.</desc>
4749 </param>
4750 <param name="nextKey" type="wstring" dir="out">
4751 <desc>Name of the next data key.</desc>
4752 </param>
4753 <param name="nextValue" type="wstring" dir="out">
4754 <desc>Value of the next data key.</desc>
4755 </param>
4756 </method>
4757
4758 <method name="getExtraData">
4759 <desc>
4760 Returns associated machine-specific extra data.
4761
4762 If the requested data @a key does not exist, this function will
4763 succeed and return @c NULL in the @a value argument.
4764
4765 <result name="VBOX_E_FILE_ERROR">
4766 Settings file not accessible.
4767 </result>
4768 <result name="VBOX_E_XML_ERROR">
4769 Could not parse the settings file.
4770 </result>
4771
4772 </desc>
4773 <param name="key" type="wstring" dir="in">
4774 <desc>Name of the data key to get.</desc>
4775 </param>
4776 <param name="value" type="wstring" dir="return">
4777 <desc>Value of the requested data key.</desc>
4778 </param>
4779 </method>
4780
4781 <method name="setExtraData">
4782 <desc>
4783 Sets associated machine-specific extra data.
4784
4785 If you pass @c NULL as a key @a value, the given @a key will be
4786 deleted.
4787
4788 <note>
4789 Before performing the actual data change, this method will ask all
4790 registered callbacks using the
4791 <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
4792 notification for a permission. If one of the callbacks refuses the
4793 new value, the change will not be performed.
4794 </note>
4795 <note>
4796 On success, the
4797 <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
4798 is called to inform all registered callbacks about a successful data
4799 change.
4800 </note>
4801 <note>
4802 This method can be called outside the machine session and therefore
4803 it's a caller's responsibility to handle possible race conditions
4804 when several clients change the same key at the same time.
4805 </note>
4806
4807 <result name="VBOX_E_FILE_ERROR">
4808 Settings file not accessible.
4809 </result>
4810 <result name="VBOX_E_XML_ERROR">
4811 Could not parse the settings file.
4812 </result>
4813
4814 </desc>
4815 <param name="key" type="wstring" dir="in">
4816 <desc>Name of the data key to set.</desc>
4817 </param>
4818 <param name="value" type="wstring" dir="in">
4819 <desc>Value to assign to the key.</desc>
4820 </param>
4821 </method>
4822
4823 <method name="saveSettings">
4824 <desc>
4825 Saves any changes to machine settings made since the session
4826 has been opened or a new machine has been created, or since the
4827 last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
4828 For registered machines, new settings become visible to all
4829 other VirtualBox clients after successful invocation of this
4830 method.
4831 <note>
4832 The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
4833 notification event after the configuration has been successfully
4834 saved (only for registered machines).
4835 </note>
4836 <note>
4837 Calling this method is only valid on instances returned
4838 by <link to="ISession::machine"/> and on new machines
4839 created by <link to="IVirtualBox::createMachine"/> but not
4840 yet registered, or on unregistered machines after calling
4841 <link to="IVirtualBox::unregisterMachine"/>.
4842 </note>
4843
4844 <result name="VBOX_E_FILE_ERROR">
4845 Settings file not accessible.
4846 </result>
4847 <result name="VBOX_E_XML_ERROR">
4848 Could not parse the settings file.
4849 </result>
4850 <result name="E_ACCESSDENIED">
4851 Modification request refused.
4852 </result>
4853
4854 </desc>
4855 </method>
4856
4857 <method name="saveSettingsWithBackup">
4858 <desc>
4859 Creates a backup copy of the machine settings file (<link
4860 to="#settingsFilePath"/>) in case of auto-conversion, and then calls
4861 <link to="#saveSettings"/>.
4862
4863 Note that the backup copy is created <b>only</b> if the settings file
4864 auto-conversion took place (see <link to="#settingsFileVersion"/> for
4865 details). Otherwise, this call is fully equivalent to
4866 <link to="#saveSettings"/> and no backup copying is done.
4867
4868 The backup copy is created in the same directory where the original
4869 settings file is located. It is given the following file name:
4870 <pre>
4871 original.xml.x.y-platform.bak
4872 </pre>
4873 where <tt>original.xml</tt> is the original settings file name
4874 (excluding path), and <tt>x.y-platform</tt> is the version of the old
4875 format of the settings file (before auto-conversion).
4876
4877 If the given backup file already exists, this method will try to add the
4878 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
4879 0 to 9) and copy it again until it succeeds. If all suffixes are
4880 occupied, or if any other copy error occurs, this method will return a
4881 failure.
4882
4883 If the copy operation succeeds, the @a bakFileName return argument will
4884 receive a full path to the created backup file (for informational
4885 purposes). Note that this will happen even if the subsequent
4886 <link to="#saveSettings"/> call performed by this method after the
4887 copy operation, fails.
4888
4889 <note>
4890 The VirtualBox API never calls this method. It is intended purely for
4891 the purposes of creating backup copies of the settings files by
4892 front-ends before saving the results of the automatically performed
4893 settings conversion to disk.
4894 </note>
4895
4896 <see>settingsFileVersion</see>
4897
4898 <result name="VBOX_E_FILE_ERROR">
4899 Settings file not accessible.
4900 </result>
4901 <result name="VBOX_E_XML_ERROR">
4902 Could not parse the settings file.
4903 </result>
4904 <result name="VBOX_E_INVALID_VM_STATE">
4905 Virtual machine is not mutable.
4906 </result>
4907 <result name="E_ACCESSDENIED">
4908 Modification request refused.
4909 </result>
4910
4911 </desc>
4912 <param name="bakFileName" type="wstring" dir="return">
4913 <desc>Full path to the created backup copy.</desc>
4914 </param>
4915 </method>
4916
4917 <method name="discardSettings">
4918 <desc>
4919 Discards any changes to the machine settings made since the session
4920 has been opened or since the last call to <link to="#saveSettings"/>
4921 or <link to="#discardSettings"/>.
4922 <note>
4923 Calling this method is only valid on instances returned
4924 by <link to="ISession::machine"/> and on new machines
4925 created by <link to="IVirtualBox::createMachine"/> or
4926 opened by <link to="IVirtualBox::openMachine"/> but not
4927 yet registered, or on unregistered machines after calling
4928 <link to="IVirtualBox::unregisterMachine"/>.
4929 </note>
4930
4931 <result name="VBOX_E_INVALID_VM_STATE">
4932 Virtual machine is not mutable.
4933 </result>
4934
4935 </desc>
4936 </method>
4937
4938 <method name="deleteSettings">
4939 <desc>
4940 Deletes the settings file of this machine from disk.
4941 The machine must not be registered in order for this operation
4942 to succeed.
4943 <note>
4944 <link to="#settingsModified"/> will return TRUE after this
4945 method successfully returns.
4946 </note>
4947 <note>
4948 Calling this method is only valid on instances returned
4949 by <link to="ISession::machine"/> and on new machines
4950 created by <link to="IVirtualBox::createMachine"/> or
4951 opened by <link to="IVirtualBox::openMachine"/> but not
4952 yet registered, or on unregistered machines after calling
4953 <link to="IVirtualBox::unregisterMachine"/>.
4954 </note>
4955 <note>
4956 The deleted machine settings file can be restored (saved again)
4957 by calling <link to="#saveSettings"/>.
4958 </note>
4959
4960 <result name="VBOX_E_INVALID_VM_STATE">
4961 Cannot delete settings of a registered machine or
4962 machine not mutable.
4963 </result>
4964 <result name="VBOX_E_IPRT_ERROR">
4965 Could not delete the settings file.
4966 </result>
4967
4968 </desc>
4969 </method>
4970
4971 <method name="export">
4972 <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
4973 steps required to export VirtualBox machines to OVF.
4974 </desc>
4975
4976 <param name="appliance" type="IAppliance" dir="in">
4977 <desc>Appliance to export this machine to.</desc>
4978 </param>
4979 </method >
4980
4981 <method name="getSnapshot">
4982 <desc>
4983 Returns a snapshot of this machine with the given UUID.
4984 A <tt>null</tt> UUID can be used to obtain the first snapshot
4985 taken on this machine. This is useful if you want to traverse
4986 the whole tree of snapshots starting from the root.
4987
4988 <result name="VBOX_E_OBJECT_NOT_FOUND">
4989 Virtual machine has no snapshots or snapshot not found.
4990 </result>
4991
4992 </desc>
4993 <param name="id" type="uuid" dir="in">
4994 <desc>UUID of the snapshot to get</desc>
4995 </param>
4996 <param name="snapshot" type="ISnapshot" dir="return">
4997 <desc>Snapshot object with the given UUID.</desc>
4998 </param>
4999 </method>
5000
5001 <method name="findSnapshot">
5002 <desc>
5003 Returns a snapshot of this machine with the given name.
5004
5005 <result name="VBOX_E_OBJECT_NOT_FOUND">
5006 Virtual machine has no snapshots or snapshot not found.
5007 </result>
5008
5009 </desc>
5010 <param name="name" type="wstring" dir="in">
5011 <desc>Name of the snapshot to find</desc>
5012 </param>
5013 <param name="snapshot" type="ISnapshot" dir="return">
5014 <desc>Snapshot object with the given name.</desc>
5015 </param>
5016 </method>
5017
5018 <method name="setCurrentSnapshot">
5019 <desc>
5020 Sets the current snapshot of this machine.
5021 <note>
5022 In the current implementation, this operation is not
5023 implemented.
5024 </note>
5025 </desc>
5026 <param name="id" type="uuid" dir="in">
5027 <desc>UUID of the snapshot to set as the current snapshot.</desc>
5028 </param>
5029 </method>
5030
5031 <method name="createSharedFolder">
5032 <desc>
5033 Creates a new permanent shared folder by associating the given logical
5034 name with the given host path, adds it to the collection of shared
5035 folders and starts sharing it. Refer to the description of
5036 <link to="ISharedFolder"/> to read more about logical names.
5037
5038 <result name="VBOX_E_OBJECT_IN_USE">
5039 Shared folder already exists.
5040 </result>
5041 <result name="VBOX_E_FILE_ERROR">
5042 Shared folder @a hostPath not accessible.
5043 </result>
5044
5045 </desc>
5046 <param name="name" type="wstring" dir="in">
5047 <desc>Unique logical name of the shared folder.</desc>
5048 </param>
5049 <param name="hostPath" type="wstring" dir="in">
5050 <desc>Full path to the shared folder in the host file system.</desc>
5051 </param>
5052 <param name="writable" type="boolean" dir="in">
5053 <desc>Whether the share is writable or readonly</desc>
5054 </param>
5055 </method>
5056
5057 <method name="removeSharedFolder">
5058 <desc>
5059 Removes the permanent shared folder with the given name previously
5060 created by <link to="#createSharedFolder"/> from the collection of
5061 shared folders and stops sharing it.
5062
5063 <result name="VBOX_E_INVALID_VM_STATE">
5064 Virtual machine is not mutable.
5065 </result>
5066 <result name="VBOX_E_OBJECT_NOT_FOUND">
5067 Shared folder @a name does not exist.
5068 </result>
5069
5070 </desc>
5071 <param name="name" type="wstring" dir="in">
5072 <desc>Logical name of the shared folder to remove.</desc>
5073 </param>
5074 </method>
5075
5076 <method name="canShowConsoleWindow">
5077 <desc>
5078 Returns @c true if the VM console process can activate the
5079 console window and bring it to foreground on the desktop of
5080 the host PC.
5081 <note>
5082 This method will fail if a session for this machine is not
5083 currently open.
5084 </note>
5085
5086 <result name="VBOX_E_INVALID_VM_STATE">
5087 Machine session is not open.
5088 </result>
5089
5090 </desc>
5091 <param name="canShow" type="boolean" dir="return">
5092 <desc>
5093 @c true if the console window can be shown and @c
5094 false otherwise.
5095 </desc>
5096 </param>
5097 </method>
5098
5099 <method name="showConsoleWindow">
5100 <desc>
5101 Activates the console window and brings it to foreground on
5102 the desktop of the host PC. Many modern window managers on
5103 many platforms implement some sort of focus stealing
5104 prevention logic, so that it may be impossible to activate
5105 a window without the help of the currently active
5106 application. In this case, this method will return a non-zero
5107 identifier that represents the top-level window of the VM
5108 console process. The caller, if it represents a currently
5109 active process, is responsible to use this identifier (in a
5110 platform-dependent manner) to perform actual window
5111 activation.
5112 <note>
5113 This method will fail if a session for this machine is not
5114 currently open.
5115 </note>
5116
5117 <result name="VBOX_E_INVALID_VM_STATE">
5118 Machine session is not open.
5119 </result>
5120
5121 </desc>
5122 <param name="winId" type="unsigned long long" dir="return">
5123 <desc>
5124 Platform-dependent identifier of the top-level VM console
5125 window, or zero if this method has performed all actions
5126 necessary to implement the <i>show window</i> semantics for
5127 the given platform and/or VirtualBox front-end.
5128 </desc>
5129 </param>
5130 </method>
5131
5132 <method name="getGuestProperty">
5133 <desc>
5134 Reads an entry from the machine's guest property store.
5135
5136 <result name="VBOX_E_INVALID_VM_STATE">
5137 Machine session is not open.
5138 </result>
5139
5140 </desc>
5141 <param name="name" type="wstring" dir="in">
5142 <desc>
5143 The name of the property to read.
5144 </desc>
5145 </param>
5146 <param name="value" type="wstring" dir="out">
5147 <desc>
5148 The value of the property. If the property does not exist then this
5149 will be empty.
5150 </desc>
5151 </param>
5152 <param name="timestamp" type="unsigned long long" dir="out">
5153 <desc>
5154 The time at which the property was last modified, as seen by the
5155 server process.
5156 </desc>
5157 </param>
5158 <param name="flags" type="wstring" dir="out">
5159 <desc>
5160 Additional property parameters, passed as a comma-separated list of
5161 "name=value" type entries.
5162 </desc>
5163 </param>
5164 </method>
5165
5166 <method name="getGuestPropertyValue">
5167 <desc>
5168 Reads a value from the machine's guest property store.
5169
5170 <result name="VBOX_E_INVALID_VM_STATE">
5171 Machine session is not open.
5172 </result>
5173
5174 </desc>
5175 <param name="property" type="wstring" dir="in">
5176 <desc>
5177 The name of the property to read.
5178 </desc>
5179 </param>
5180 <param name="value" type="wstring" dir="return">
5181 <desc>
5182 The value of the property. If the property does not exist then this
5183 will be empty.
5184 </desc>
5185 </param>
5186 </method>
5187
5188 <method name="getGuestPropertyTimestamp">
5189 <desc>
5190 Reads a property timestamp from the machine's guest property store.
5191
5192 <result name="VBOX_E_INVALID_VM_STATE">
5193 Machine session is not open.
5194 </result>
5195
5196 </desc>
5197 <param name="property" type="wstring" dir="in">
5198 <desc>
5199 The name of the property to read.
5200 </desc>
5201 </param>
5202 <param name="value" type="unsigned long long" dir="return">
5203 <desc>
5204 The timestamp. If the property does not exist then this will be
5205 empty.
5206 </desc>
5207 </param>
5208 </method>
5209
5210 <method name="setGuestProperty">
5211 <desc>
5212 Sets, changes or deletes an entry in the machine's guest property
5213 store.
5214
5215 <result name="E_ACCESSDENIED">
5216 Property cannot be changed.
5217 </result>
5218 <result name="E_INVALIDARG">
5219 Invalid @a flags.
5220 </result>
5221 <result name="VBOX_E_INVALID_VM_STATE">
5222 Virtual machine is not mutable or session not open.
5223 </result>
5224 <result name="VBOX_E_INVALID_OBJECT_STATE">
5225 Cannot set transient property when machine not running.
5226 </result>
5227
5228 </desc>
5229 <param name="property" type="wstring" dir="in">
5230 <desc>
5231 The name of the property to set, change or delete.
5232 </desc>
5233 </param>
5234 <param name="value" type="wstring" dir="in">
5235 <desc>
5236 The new value of the property to set, change or delete. If the
5237 property does not yet exist and value is non-empty, it will be
5238 created. If the value is empty, the key will be deleted if it
5239 exists.
5240 </desc>
5241 </param>
5242 <param name="flags" type="wstring" dir="in">
5243 <desc>
5244 Additional property parameters, passed as a comma-separated list of
5245 "name=value" type entries.
5246 </desc>
5247 </param>
5248 </method>
5249
5250 <method name="setGuestPropertyValue">
5251 <desc>
5252 Sets, changes or deletes a value in the machine's guest property
5253 store. The flags field will be left unchanged or created empty for a
5254 new property.
5255
5256 <result name="E_ACCESSDENIED">
5257 Property cannot be changed.
5258 </result>
5259 <result name="VBOX_E_INVALID_VM_STATE">
5260 Virtual machine is not mutable or session not open.
5261 </result>
5262 <result name="VBOX_E_INVALID_OBJECT_STATE">
5263 Cannot set transient property when machine not running.
5264 </result>
5265 </desc>
5266
5267 <param name="property" type="wstring" dir="in">
5268 <desc>
5269 The name of the property to set, change or delete.
5270 </desc>
5271 </param>
5272 <param name="value" type="wstring" dir="in">
5273 <desc>
5274 The new value of the property to set, change or delete. If the
5275 property does not yet exist and value is non-empty, it will be
5276 created. If value is empty, the property will be deleted if it
5277 exists.
5278 </desc>
5279 </param>
5280 </method>
5281
5282 <method name="enumerateGuestProperties">
5283 <desc>
5284 Return a list of the guest properties matching a set of patterns along
5285 with their values, time stamps and flags.
5286 </desc>
5287 <param name="patterns" type="wstring" dir="in">
5288 <desc>
5289 The patterns to match the properties against, separated by '|'
5290 characters. If this is empty or NULL, all properties will match.
5291 </desc>
5292 </param>
5293 <param name="name" type="wstring" dir="out" safearray="yes">
5294 <desc>
5295 The names of the properties returned.
5296 </desc>
5297 </param>
5298 <param name="value" type="wstring" dir="out" safearray="yes">
5299 <desc>
5300 The values of the properties returned. The array entries match the
5301 corresponding entries in the @a name array.
5302 </desc>
5303 </param>
5304 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
5305 <desc>
5306 The time stamps of the properties returned. The array entries match
5307 the corresponding entries in the @a name array.
5308 </desc>
5309 </param>
5310 <param name="flags" type="wstring" dir="out" safearray="yes">
5311 <desc>
5312 The flags of the properties returned. The array entries match the
5313 corresponding entries in the @a name array.
5314 </desc>
5315 </param>
5316 </method>
5317</interface>
5318
5319 <!--
5320 // IConsole
5321 /////////////////////////////////////////////////////////////////////////
5322 -->
5323
5324 <interface
5325 name="IConsoleCallback" extends="$unknown"
5326 uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
5327 wsmap="suppress"
5328 >
5329
5330 <method name="onMousePointerShapeChange">
5331 <desc>
5332 Notification when the guest mouse pointer shape has
5333 changed. The new shape data is given.
5334 </desc>
5335 <param name="visible" type="boolean" dir="in">
5336 <desc>
5337 Flag whether the pointer is visible.
5338 </desc>
5339 </param>
5340 <param name="alpha" type="boolean" dir="in">
5341 <desc>
5342 Flag whether the pointer has an alpha channel.
5343 </desc>
5344 </param>
5345 <param name="xHot" type="unsigned long" dir="in">
5346 <desc>
5347 The pointer hot spot x coordinate.
5348 </desc>
5349 </param>
5350 <param name="yHot" type="unsigned long" dir="in">
5351 <desc>
5352 The pointer hot spot y coordinate.
5353 </desc>
5354 </param>
5355 <param name="width" type="unsigned long" dir="in">
5356 <desc>
5357 Width of the pointer shape in pixels.
5358 </desc>
5359 </param>
5360 <param name="height" type="unsigned long" dir="in">
5361 <desc>
5362 Height of the pointer shape in pixels.
5363 </desc>
5364 </param>
5365 <param name="shape" type="octet" mod="ptr" dir="in">
5366 <desc>
5367 Address of the shape buffer.
5368
5369 The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
5370 followed by a 32-bpp XOR (color) mask.
5371
5372 For pointers without alpha channel the XOR mask pixels are 32
5373 bit values: (lsb)BGR0(msb). For pointers with alpha channel
5374 the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
5375
5376 An AND mask is used for pointers with alpha channel, so if the
5377 callback does not support alpha, the pointer could be
5378 displayed as a normal color pointer.
5379
5380 The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
5381 size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
5382 height</tt>. The padding bits at the end of each scanline are
5383 undefined.
5384
5385 The XOR mask follows the AND mask on the next 4-byte aligned
5386 offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>.
5387 Bytes in the gap between the AND and the XOR mask are undefined.
5388 The XOR mask scanlines have no gap between them and the size of
5389 the XOR mask is: <tt>cXor = width * 4 * height</tt>.
5390
5391 <note>
5392 If @a shape is 0, only the pointer visibility is changed.
5393 </note>
5394 </desc>
5395 </param>
5396 </method>
5397
5398 <method name="onMouseCapabilityChange">
5399 <desc>
5400 Notification when the mouse capabilities reported by the
5401 guest have changed. The new capabilities are passed.
5402 </desc>
5403 <param name="supportsAbsolute" type="boolean" dir="in"/>
5404 <param name="needsHostCursor" type="boolean" dir="in"/>
5405 </method>
5406
5407 <method name="onKeyboardLedsChange">
5408 <desc>
5409 Notification when the guest OS executes the KBD_CMD_SET_LEDS command
5410 to alter the state of the keyboard LEDs.
5411 </desc>
5412 <param name="numLock" type="boolean" dir="in"/>
5413 <param name="capsLock" type="boolean" dir="in"/>
5414 <param name="scrollLock" type="boolean" dir="in"/>
5415 </method>
5416
5417 <method name="onStateChange">
5418 <desc>
5419 Notification when the execution state of the machine has changed.
5420 The new state will be given.
5421 </desc>
5422 <param name="state" type="MachineState" dir="in"/>
5423 </method>
5424
5425 <method name="onAdditionsStateChange">
5426 <desc>
5427 Notification when a Guest Additions property changes.
5428 Interested callees should query IGuest attributes to
5429 find out what has changed.
5430 </desc>
5431 </method>
5432
5433 <method name="onDVDDriveChange">
5434 <desc>
5435 Notification when a property of the
5436 virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
5437 Interested callees should use IDVDDrive methods to find out what has
5438 changed.
5439 </desc>
5440 </method>
5441
5442 <method name="onFloppyDriveChange">
5443 <desc>
5444 Notification when a property of the
5445 virtual <link to="IMachine::floppyDrive">floppy drive</link> changes.
5446 Interested callees should use IFloppyDrive methods to find out what
5447 has changed.
5448 </desc>
5449 </method>
5450
5451 <method name="onNetworkAdapterChange">
5452 <desc>
5453 Notification when a property of one of the
5454 virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
5455 changes. Interested callees should use INetworkAdapter methods and
5456 attributes to find out what has changed.
5457 </desc>
5458 <param name="networkAdapter" type="INetworkAdapter" dir="in">
5459 <desc>Network adapter that is subject to change.</desc>
5460 </param>
5461 </method>
5462
5463 <method name="onSerialPortChange">
5464 <desc>
5465 Notification when a property of one of the
5466 virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
5467 Interested callees should use ISerialPort methods and attributes
5468 to find out what has changed.
5469 </desc>
5470 <param name="serialPort" type="ISerialPort" dir="in">
5471 <desc>Serial port that is subject to change.</desc>
5472 </param>
5473 </method>
5474
5475 <method name="onParallelPortChange">
5476 <desc>
5477 Notification when a property of one of the
5478 virtual <link to="IMachine::getParallelPort">parallel ports</link>
5479 changes. Interested callees should use ISerialPort methods and
5480 attributes to find out what has changed.
5481 </desc>
5482 <param name="parallelPort" type="IParallelPort" dir="in">
5483 <desc>Parallel port that is subject to change.</desc>
5484 </param>
5485 </method>
5486
5487 <method name="onStorageControllerChange">
5488 <desc>
5489 Notification when a property of one of the
5490 virtual <link to="IMachine::getStorageControllers">storage controllers</link>
5491 changes. Interested callees should use query the corresponding collections
5492 to find out what has changed.
5493 </desc>
5494 </method>
5495
5496 <method name="onVRDPServerChange">
5497 <desc>
5498 Notification when a property of the
5499 <link to="IMachine::VRDPServer">VRDP server</link> changes.
5500 Interested callees should use IVRDPServer methods and attributes to
5501 find out what has changed.
5502 </desc>
5503 </method>
5504
5505 <method name="onUSBControllerChange">
5506 <desc>
5507 Notification when a property of the virtual
5508 <link to="IMachine::USBController">USB controller</link> changes.
5509 Interested callees should use IUSBController methods and attributes to
5510 find out what has changed.
5511 </desc>
5512 </method>
5513
5514 <method name="onUSBDeviceStateChange">
5515 <desc>
5516 Notification when a USB device is attached to or detached from
5517 the virtual USB controller.
5518
5519 This notification is sent as a result of the indirect
5520 request to attach the device because it matches one of the
5521 machine USB filters, or as a result of the direct request
5522 issued by <link to="IConsole::attachUSBDevice"/> or
5523 <link to="IConsole::detachUSBDevice"/>.
5524
5525 This notification is sent in case of both a succeeded and a
5526 failed request completion. When the request succeeds, the
5527 @a error parameter is @c null, and the given device has been
5528 already added to (when @a attached is @c true) or removed from
5529 (when @a attached is @c false) the collection represented by
5530 <link to="IConsole::USBDevices"/>. On failure, the collection
5531 doesn't change and the @a error parameter represents the error
5532 message describing the failure.
5533
5534 </desc>
5535 <param name="device" type="IUSBDevice" dir="in">
5536 <desc>Device that is subject to state change.</desc>
5537 </param>
5538 <param name="attached" type="boolean" dir="in">
5539 <desc>
5540 <tt>true</tt> if the device was attached
5541 and <tt>false</tt> otherwise.
5542 </desc>
5543 </param>
5544 <param name="error" type="IVirtualBoxErrorInfo" dir="in">
5545 <desc>
5546 <tt>null</tt> on success or an error message object on
5547 failure.
5548 </desc>
5549 </param>
5550 </method>
5551
5552 <method name="onSharedFolderChange">
5553 <desc>
5554 Notification when a shared folder is added or removed.
5555 The @a scope argument defines one of three scopes:
5556 <link to="IVirtualBox::sharedFolders">global shared folders</link>
5557 (<link to="Scope_Global">Global</link>),
5558 <link to="IMachine::sharedFolders">permanent shared folders</link> of
5559 the machine (<link to="Scope_Machine">Machine</link>) or <link
5560 to="IConsole::sharedFolders">transient shared folders</link> of the
5561 machine (<link to="Scope_Session">Session</link>). Interested callees
5562 should use query the corresponding collections to find out what has
5563 changed.
5564 </desc>
5565 <param name="scope" type="Scope" dir="in">
5566 <desc>Scope of the notification.</desc>
5567 </param>
5568 </method>
5569
5570 <method name="onRuntimeError">
5571 <desc>
5572 Notification when an error happens during the virtual
5573 machine execution.
5574
5575 There are three kinds of runtime errors:
5576 <ul>
5577 <li><i>fatal</i></li>
5578 <li><i>non-fatal with retry</i></li>
5579 <li><i>non-fatal warnings</i></li>
5580 </ul>
5581
5582 <b>Fatal</b> errors are indicated by the @a fatal parameter set
5583 to <tt>true</tt>. In case of fatal errors, the virtual machine
5584 execution is always paused before calling this notification, and
5585 the notification handler is supposed either to immediately save
5586 the virtual machine state using <link to="IConsole::saveState"/>
5587 or power it off using <link to="IConsole::powerDown"/>.
5588 Resuming the execution can lead to unpredictable results.
5589
5590 <b>Non-fatal</b> errors and warnings are indicated by the
5591 @a fatal parameter set to <tt>false</tt>. If the virtual machine
5592 is in the Paused state by the time the error notification is
5593 received, it means that the user can <i>try to resume</i> the machine
5594 execution after attempting to solve the problem that caused the
5595 error. In this case, the notification handler is supposed
5596 to show an appropriate message to the user (depending on the
5597 value of the @a id parameter) that offers several actions such
5598 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
5599 wants to retry, the notification handler should continue
5600 the machine execution using the <link to="IConsole::resume"/>
5601 call. If the machine execution is not Paused during this
5602 notification, then it means this notification is a <i>warning</i>
5603 (for example, about a fatal condition that can happen very soon);
5604 no immediate action is required from the user, the machine
5605 continues its normal execution.
5606
5607 Note that in either case the notification handler
5608 <b>must not</b> perform any action directly on a thread
5609 where this notification is called. Everything it is allowed to
5610 do is to post a message to another thread that will then talk
5611 to the user and take the corresponding action.
5612
5613 Currently, the following error identifiers are known:
5614 <ul>
5615 <li><tt>"HostMemoryLow"</tt></li>
5616 <li><tt>"HostAudioNotResponding"</tt></li>
5617 <li><tt>"VDIStorageFull"</tt></li>
5618 </ul>
5619
5620 <note>
5621 This notification is not designed to be implemented by
5622 more than one callback at a time. If you have multiple
5623 IConsoleCallback instances registered on the given
5624 IConsole object, make sure you simply do nothing but
5625 return @c S_OK from all but one of them that does actual
5626 user notification and performs necessary actions.
5627 </note>
5628
5629 </desc>
5630 <param name="fatal" type="boolean" dir="in">
5631 <desc>Whether the error is fatal or not</desc>
5632 </param>
5633 <param name="id" type="wstring" dir="in">
5634 <desc>Error identifier</desc>
5635 </param>
5636 <param name="message" type="wstring" dir="in">
5637 <desc>Optional error message</desc>
5638 </param>
5639 </method>
5640
5641 <method name="onCanShowWindow">
5642 <desc>
5643 Notification when a call to
5644 <link to="IMachine::canShowConsoleWindow"/> is made by a
5645 front-end to check if a subsequent call to
5646 <link to="IMachine::showConsoleWindow"/> can succeed.
5647
5648 The callee should give an answer appropriate to the current
5649 machine state in the @a canShow argument. This answer must
5650 remain valid at least until the next
5651 <link to="IConsole::state">machine state</link> change.
5652
5653 <note>
5654 This notification is not designed to be implemented by
5655 more than one callback at a time. If you have multiple
5656 IConsoleCallback instances registered on the given
5657 IConsole object, make sure you simply do nothing but
5658 return @c true and @c S_OK from all but one of them that
5659 actually manages console window activation.
5660 </note>
5661 </desc>
5662 <param name="canShow" type="boolean" dir="return">
5663 <desc>
5664 @c true if the console window can be shown and @c
5665 false otherwise.
5666 </desc>
5667 </param>
5668 </method>
5669
5670 <method name="onShowWindow">
5671 <desc>
5672 Notification when a call to
5673 <link to="IMachine::showConsoleWindow"/>
5674 requests the console window to be activated and brought to
5675 foreground on the desktop of the host PC.
5676
5677 This notification should cause the VM console process to
5678 perform the requested action as described above. If it is
5679 impossible to do it at a time of this notification, this
5680 method should return a failure.
5681
5682 Note that many modern window managers on many platforms
5683 implement some sort of focus stealing prevention logic, so
5684 that it may be impossible to activate a window without the
5685 help of the currently active application (which is supposedly
5686 an initiator of this notification). In this case, this method
5687 must return a non-zero identifier that represents the
5688 top-level window of the VM console process. The caller, if it
5689 represents a currently active process, is responsible to use
5690 this identifier (in a platform-dependent manner) to perform
5691 actual window activation.
5692
5693 This method must set @a winId to zero if it has performed all
5694 actions necessary to complete the request and the console
5695 window is now active and in foreground, to indicate that no
5696 further action is required on the caller's side.
5697
5698 <note>
5699 This notification is not designed to be implemented by
5700 more than one callback at a time. If you have multiple
5701 IConsoleCallback instances registered on the given
5702 IConsole object, make sure you simply do nothing but
5703 return @c S_OK from all but one of them that actually
5704 manages console window activation.
5705 </note>
5706 </desc>
5707 <param name="winId" type="unsigned long long" dir="return">
5708 <desc>
5709 Platform-dependent identifier of the top-level VM console
5710 window, or zero if this method has performed all actions
5711 necessary to implement the <i>show window</i> semantics for
5712 the given platform and/or this VirtualBox front-end.
5713 </desc>
5714 </param>
5715 </method>
5716
5717 </interface>
5718
5719 <interface
5720 name="IRemoteDisplayInfo" extends="$unknown"
5721 uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
5722 wsmap="struct"
5723 >
5724 <desc>
5725 Contains information about the remote display (VRDP) capabilities and status.
5726 This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
5727 </desc>
5728
5729 <attribute name="active" type="boolean" readonly="yes">
5730 <desc>
5731 Whether the remote display connection is active.
5732 </desc>
5733 </attribute>
5734
5735 <attribute name="numberOfClients" type="unsigned long" readonly="yes">
5736 <desc>
5737 How many times a client connected.
5738 </desc>
5739 </attribute>
5740
5741 <attribute name="beginTime" type="long long" readonly="yes">
5742 <desc>
5743 When the last connection was established, in milliseconds since 1970-01-01 UTC.
5744 </desc>
5745 </attribute>
5746
5747 <attribute name="endTime" type="long long" readonly="yes">
5748 <desc>
5749 When the last connection was terminated or the current time, if
5750 connection is still active, in milliseconds since 1970-01-01 UTC.
5751 </desc>
5752 </attribute>
5753
5754 <attribute name="bytesSent" type="unsigned long long" readonly="yes">
5755 <desc>
5756 How many bytes were sent in last or current, if still active, connection.
5757 </desc>
5758 </attribute>
5759
5760 <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
5761 <desc>
5762 How many bytes were sent in all connections.
5763 </desc>
5764 </attribute>
5765
5766 <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
5767 <desc>
5768 How many bytes were received in last or current, if still active, connection.
5769 </desc>
5770 </attribute>
5771
5772 <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
5773 <desc>
5774 How many bytes were received in all connections.
5775 </desc>
5776 </attribute>
5777
5778 <attribute name="user" type="wstring" readonly="yes">
5779 <desc>
5780 Login user name supplied by the client.
5781 </desc>
5782 </attribute>
5783
5784 <attribute name="domain" type="wstring" readonly="yes">
5785 <desc>
5786 Login domain name supplied by the client.
5787 </desc>
5788 </attribute>
5789
5790 <attribute name="clientName" type="wstring" readonly="yes">
5791 <desc>
5792 The client name supplied by the client.
5793 </desc>
5794 </attribute>
5795
5796 <attribute name="clientIP" type="wstring" readonly="yes">
5797 <desc>
5798 The IP address of the client.
5799 </desc>
5800 </attribute>
5801
5802 <attribute name="clientVersion" type="unsigned long" readonly="yes">
5803 <desc>
5804 The client software version number.
5805 </desc>
5806 </attribute>
5807
5808 <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
5809 <desc>
5810 Public key exchange method used when connection was established.
5811 Values: 0 - RDP4 public key exchange scheme.
5812 1 - X509 certificates were sent to client.
5813 </desc>
5814 </attribute>
5815
5816 </interface>
5817
5818 <interface
5819 name="IConsole" extends="$unknown"
5820 uuid="9511bc54-15ee-4ddf-808e-472aba03809c"
5821 wsmap="managed"
5822 >
5823 <desc>
5824 The IConsole interface represents an interface to control virtual
5825 machine execution.
5826
5827 The console object that implements the IConsole interface is obtained
5828 from a session object after the session for the given machine has been
5829 opened using one of <link to="IVirtualBox::openSession"/>,
5830 <link to="IVirtualBox::openRemoteSession"/> or
5831 <link to="IVirtualBox::openExistingSession"/> methods.
5832
5833 Methods of the IConsole interface allow the caller to query the current
5834 virtual machine execution state, pause the machine or power it down, save
5835 the machine state or take a snapshot, attach and detach removable media
5836 and so on.
5837
5838 <see>ISession</see>
5839 </desc>
5840
5841 <attribute name="machine" type="IMachine" readonly="yes">
5842 <desc>
5843 Machine object this console is sessioned with.
5844 <note>
5845 This is a convenience property, it has the same value as
5846 <link to="ISession::machine"/> of the corresponding session
5847 object.
5848 </note>
5849 </desc>
5850 </attribute>
5851
5852 <attribute name="state" type="MachineState" readonly="yes">
5853 <desc>
5854 Current execution state of the machine.
5855 <note>
5856 This property always returns the same value as the corresponding
5857 property of the IMachine object this console is sessioned with.
5858 For the process that owns (executes) the VM, this is the
5859 preferable way of querying the VM state, because no IPC
5860 calls are made.
5861 </note>
5862 </desc>
5863 </attribute>
5864
5865 <attribute name="guest" type="IGuest" readonly="yes">
5866 <desc>Guest object.</desc>
5867 </attribute>
5868
5869 <attribute name="keyboard" type="IKeyboard" readonly="yes">
5870 <desc>
5871 Virtual keyboard object.
5872 <note>
5873 If the machine is not running, any attempt to use
5874 the returned object will result in an error.
5875 </note>
5876 </desc>
5877 </attribute>
5878
5879 <attribute name="mouse" type="IMouse" readonly="yes">
5880 <desc>
5881 Virtual mouse object.
5882 <note>
5883 If the machine is not running, any attempt to use
5884 the returned object will result in an error.
5885 </note>
5886 </desc>
5887 </attribute>
5888
5889 <attribute name="display" type="IDisplay" readonly="yes">
5890 <desc>Virtual display object.
5891 <note>
5892 If the machine is not running, any attempt to use
5893 the returned object will result in an error.
5894 </note>
5895 </desc>
5896 </attribute>
5897
5898 <attribute name="debugger" type="IMachineDebugger" readonly="yes">
5899 <desc>Debugging interface.</desc>
5900 </attribute>
5901
5902 <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
5903 <desc>
5904 Collection of USB devices currently attached to the virtual
5905 USB controller.
5906 <note>
5907 The collection is empty if the machine is not running.
5908 </note>
5909 </desc>
5910 </attribute>
5911
5912 <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
5913 <desc>
5914 List of USB devices currently attached to the remote VRDP client.
5915 Once a new device is physically attached to the remote host computer,
5916 it appears in this list and remains there until detached.
5917 </desc>
5918 </attribute>
5919
5920 <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
5921 <desc>
5922 Collection of shared folders for the current session. These folders
5923 are called transient shared folders because they are available to the
5924 guest OS running inside the associated virtual machine only for the
5925 duration of the session (as opposed to
5926 <link to="IMachine::sharedFolders"/> which represent permanent shared
5927 folders). When the session is closed (e.g. the machine is powered down),
5928 these folders are automatically discarded.
5929
5930 New shared folders are added to the collection using
5931 <link to="#createSharedFolder"/>. Existing shared folders can be
5932 removed using <link to="#removeSharedFolder"/>.
5933 </desc>
5934 </attribute>
5935
5936 <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
5937 <desc>
5938 Interface that provides information on Remote Display (VRDP) connection.
5939 </desc>
5940 </attribute>
5941
5942 <method name="powerUp">
5943 <desc>
5944 Starts the virtual machine execution using the current machine
5945 state (that is, its current execution state, current settings and
5946 current hard disks).
5947
5948 If the machine is powered off or aborted, the execution will
5949 start from the beginning (as if the real hardware were just
5950 powered on).
5951
5952 If the machine is in the <link to="MachineState_Saved"/> state,
5953 it will continue its execution the point where the state has
5954 been saved.
5955
5956 <note>
5957 Unless you are trying to write a new VirtualBox front-end that
5958 performs direct machine execution (like the VirtualBox or VBoxSDL
5959 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
5960 session opened by <link to="IVirtualBox::openSession"/> and use this
5961 session only to change virtual machine settings. If you simply want to
5962 start virtual machine execution using one of the existing front-ends
5963 (for example the VirtualBox GUI or headless server), simply use
5964 <link to="IVirtualBox::openRemoteSession"/>; these front-ends will
5965 power up the machine automatically for you.
5966 </note>
5967
5968 <see>#saveState</see>
5969 <result name="VBOX_E_INVALID_VM_STATE">
5970 Virtual machine already running.
5971 </result>
5972 <result name="VBOX_E_HOST_ERROR">
5973 Host interface does not exist or name not set.
5974 </result>
5975 <result name="VBOX_E_FILE_ERROR">
5976 Invalid saved state file.
5977 </result>
5978 </desc>
5979 <param name="progress" type="IProgress" dir="return">
5980 <desc>Progress object to track the operation completion.</desc>
5981 </param>
5982 </method>
5983
5984 <method name="powerUpPaused">
5985 <desc>
5986 Identical to powerUp except that the VM will enter the
5987 <link to="MachineState_Paused"/> state, instead of
5988 <link to="MachineState_Running"/>.
5989
5990 <see>#powerUp</see>
5991 <result name="VBOX_E_INVALID_VM_STATE">
5992 Virtual machine already running.
5993 </result>
5994 <result name="VBOX_E_HOST_ERROR">
5995 Host interface does not exist or name not set.
5996 </result>
5997 <result name="VBOX_E_FILE_ERROR">
5998 Invalid saved state file.
5999 </result>
6000 </desc>
6001 <param name="progress" type="IProgress" dir="return">
6002 <desc>Progress object to track the operation completion.</desc>
6003 </param>
6004 </method>
6005
6006 <method name="powerDown">
6007 <desc>
6008 Stops the virtual machine execution.
6009 After this operation completes, the machine will go to the
6010 PoweredOff state.
6011
6012 @deprecated This method will be removed in VirtualBox 2.1 where the
6013 powerDownAsync() method will take its name. Do not use this method in
6014 the code.
6015 <result name="VBOX_E_INVALID_VM_STATE">
6016 Virtual machine must be Running, Paused or Stuck to be powered down.
6017 </result>
6018 <result name="VBOX_E_VM_ERROR">
6019 Unable to power off or destroy virtual machine.
6020 </result>
6021 </desc>
6022 </method>
6023
6024 <method name="powerDownAsync">
6025 <desc>
6026 Initiates the power down procedure to stop the virtual machine
6027 execution.
6028
6029 The completion of the power down procedure is tracked using the returned
6030 IProgress object. After the operation is complete, the machine will go
6031 to the PoweredOff state.
6032
6033 @warning This method will be renamed to "powerDown" in VirtualBox 2.1
6034 where the original powerDown() method will be removed. You will need to
6035 rename "powerDownAsync" to "powerDown" in your sources to make them
6036 build with version 2.1.
6037 <result name="VBOX_E_INVALID_VM_STATE">
6038 Virtual machine must be Running, Paused or Stuck to be powered down.
6039 </result>
6040 </desc>
6041 <param name="progress" type="IProgress" dir="return">
6042 <desc>Progress object to track the operation completion.</desc>
6043 </param>
6044 </method>
6045
6046 <method name="reset">
6047 <desc>Resets the virtual machine.
6048 <result name="VBOX_E_INVALID_VM_STATE">
6049 Virtual machine not in Running state.
6050 </result>
6051 <result name="VBOX_E_VM_ERROR">
6052 Virtual machine error in reset operation.
6053 </result>
6054 </desc>
6055 </method>
6056
6057 <method name="pause">
6058 <desc>Pauses the virtual machine execution.
6059 <result name="VBOX_E_INVALID_VM_STATE">
6060 Virtual machine not in Running state.
6061 </result>
6062 <result name="VBOX_E_VM_ERROR">
6063 Virtual machine error in suspend operation.
6064 </result>
6065 </desc>
6066 </method>
6067
6068 <method name="resume">
6069 <desc>Resumes the virtual machine execution.
6070 <result name="VBOX_E_INVALID_VM_STATE">
6071 Virtual machine not in Paused state.
6072 </result>
6073 <result name="VBOX_E_VM_ERROR">
6074 Virtual machine error in resume operation.
6075 </result>
6076 </desc>
6077 </method>
6078
6079 <method name="powerButton">
6080 <desc>Sends the ACPI power button event to the guest.
6081 <result name="VBOX_E_INVALID_VM_STATE">
6082 Virtual machine not in Running state.
6083 </result>
6084 <result name="VBOX_E_PDM_ERROR">
6085 Controlled power off failed.
6086 </result>
6087 </desc>
6088 </method>
6089
6090 <method name="sleepButton">
6091 <desc>Sends the ACPI sleep button event to the guest.
6092 <result name="VBOX_E_INVALID_VM_STATE">
6093 Virtual machine not in Running state.
6094 </result>
6095 <result name="VBOX_E_PDM_ERROR">
6096 Sending sleep button event failed.
6097 </result>
6098 </desc>
6099 </method>
6100
6101 <method name="getPowerButtonHandled">
6102 <desc>Checks if the last power button event was handled by guest.
6103 <result name="VBOX_E_PDM_ERROR">
6104 Checking if the event was handled by the guest OS failed.
6105 </result>
6106 </desc>
6107 <param name="handled" type="boolean" dir="return"/>
6108 </method>
6109
6110 <method name="getGuestEnteredACPIMode">
6111 <desc>Checks if the guest entered the ACPI mode G0 (working) or
6112 G1 (sleeping). If this method returns false, the guest will
6113 most likely not respond to external ACPI events.
6114 <result name="VBOX_E_INVALID_VM_STATE">
6115 Virtual machine not in Running state.
6116 </result>
6117 </desc>
6118 <param name="entered" type="boolean" dir="return"/>
6119 </method>
6120
6121 <method name="saveState">
6122 <desc>
6123 Saves the current execution state of a running virtual machine
6124 and stops its execution.
6125
6126 After this operation completes, the machine will go to the
6127 Saved state. Next time it is powered up, this state will
6128 be restored and the machine will continue its execution from
6129 the place where it was saved.
6130
6131 This operation differs from taking a snapshot to the effect
6132 that it doesn't create new differencing hard disks. Also, once
6133 the machine is powered up from the state saved using this method,
6134 the saved state is deleted, so it will be impossible to return
6135 to this state later.
6136
6137 <note>
6138 On success, this method implicitly calls
6139 <link to="IMachine::saveSettings"/> to save all current machine
6140 settings (including runtime changes to the DVD drive, etc.).
6141 Together with the impossibility to change any VM settings when it is
6142 in the Saved state, this guarantees adequate hardware
6143 configuration of the machine when it is restored from the saved
6144 state file.
6145 </note>
6146
6147 <note>
6148 The machine must be in the Running or Paused state, otherwise
6149 the operation will fail.
6150 </note>
6151 <result name="VBOX_E_INVALID_VM_STATE">
6152 Virtual machine state neither Running nor Paused.
6153 </result>
6154 <result name="VBOX_E_FILE_ERROR">
6155 Failed to create directory for saved state file.
6156 </result>
6157
6158 <see><link to="#takeSnapshot"/></see>
6159 </desc>
6160 <param name="progress" type="IProgress" dir="return">
6161 <desc>Progress object to track the operation completion.</desc>
6162 </param>
6163 </method>
6164
6165 <method name="adoptSavedState">
6166 <desc>
6167 Associates the given saved state file to the virtual machine.
6168
6169 On success, the machine will go to the Saved state. Next time it is
6170 powered up, it will be restored from the adopted saved state and
6171 continue execution from the place where the saved state file was
6172 created.
6173
6174 The specified saved state file path may be absolute or relative to the
6175 folder the VM normally saves the state to (usually,
6176 <link to="IMachine::snapshotFolder"/>).
6177
6178 <note>
6179 It's a caller's responsibility to make sure the given saved state
6180 file is compatible with the settings of this virtual machine that
6181 represent its virtual hardware (memory size, hard disk configuration
6182 etc.). If there is a mismatch, the behavior of the virtual machine
6183 is undefined.
6184 </note>
6185 <result name="VBOX_E_INVALID_VM_STATE">
6186 Virtual machine state neither PoweredOff nor Aborted.
6187 </result>
6188 </desc>
6189 <param name="savedStateFile" type="wstring" dir="in">
6190 <desc>Path to the saved state file to adopt.</desc>
6191 </param>
6192 </method>
6193
6194 <method name="discardSavedState">
6195 <desc>
6196 Discards (deletes) the saved state of the virtual machine
6197 previously created by <link to="#saveState"/>. Next time the
6198 machine is powered up, a clean boot will occur.
6199 <note>
6200 This operation is equivalent to resetting or powering off
6201 the machine without doing a proper shutdown in the guest OS.
6202 </note>
6203 <result name="VBOX_E_INVALID_VM_STATE">
6204 Virtual machine not in state Saved.
6205 </result>
6206 </desc>
6207 </method>
6208
6209 <method name="getDeviceActivity">
6210 <desc>
6211 Gets the current activity type of a given device or device group.
6212 <result name="E_INVALIDARG">
6213 Invalid device type.
6214 </result>
6215 </desc>
6216 <param name="type" type="DeviceType" dir="in"/>
6217 <param name="activity" type="DeviceActivity" dir="return"/>
6218 </method>
6219
6220 <method name="attachUSBDevice">
6221 <desc>
6222 Attaches a host USB device with the given UUID to the
6223 USB controller of the virtual machine.
6224
6225 The device needs to be in one of the following states:
6226 <link to="USBDeviceState_Busy"/>,
6227 <link to="USBDeviceState_Available"/> or
6228 <link to="USBDeviceState_Held"/>,
6229 otherwise an error is immediately returned.
6230
6231 When the device state is
6232 <link to="USBDeviceState_Busy">Busy</link>, an error may also
6233 be returned if the host computer refuses to release it for some reason.
6234
6235 <see>IUSBController::deviceFilters, USBDeviceState</see>
6236 <result name="VBOX_E_INVALID_VM_STATE">
6237 Virtual machine state neither Running nor Paused.
6238 </result>
6239 <result name="VBOX_E_PDM_ERROR">
6240 Virtual machine does not have a USB controller.
6241 </result>
6242 </desc>
6243 <param name="id" type="uuid" dir="in">
6244 <desc>UUID of the host USB device to attach.</desc>
6245 </param>
6246 </method>
6247
6248 <method name="detachUSBDevice">
6249 <desc>
6250 Detaches an USB device with the given UUID from the USB controller
6251 of the virtual machine.
6252
6253 After this method succeeds, the VirtualBox server re-initiates
6254 all USB filters as if the device were just physically attached
6255 to the host, but filters of this machine are ignored to avoid
6256 a possible automatic re-attachment.
6257
6258 <see>IUSBController::deviceFilters, USBDeviceState</see>
6259
6260 <result name="VBOX_E_PDM_ERROR">
6261 Virtual machine does not have a USB controller.
6262 </result>
6263 <result name="E_INVALIDARG">
6264 USB device not attached to this virtual machine.
6265 </result>
6266 </desc>
6267 <param name="id" type="uuid" dir="in">
6268 <desc>UUID of the USB device to detach.</desc>
6269 </param>
6270 <param name="device" type="IUSBDevice" dir="return">
6271 <desc>Detached USB device.</desc>
6272 </param>
6273 </method>
6274
6275 <method name="findUSBDeviceByAddress">
6276 <desc>
6277 Searches for a USB device with the given host address.
6278
6279 <result name="VBOX_E_OBJECT_NOT_FOUND">
6280 Given @c name does not correspond to any USB device.
6281 </result>
6282
6283 <see>IUSBDevice::address</see>
6284 </desc>
6285 <param name="name" type="wstring" dir="in">
6286 <desc>
6287 Address of the USB device (as assigned by the host) to
6288 search for.
6289 </desc>
6290 </param>
6291 <param name="device" type="IUSBDevice" dir="return">
6292 <desc>Found USB device object.</desc>
6293 </param>
6294 </method>
6295
6296 <method name="findUSBDeviceById">
6297 <desc>
6298 Searches for a USB device with the given UUID.
6299
6300 <result name="VBOX_E_OBJECT_NOT_FOUND">
6301 Given @c id does not correspond to any USB device.
6302 </result>
6303
6304 <see>IUSBDevice::id</see>
6305 </desc>
6306 <param name="id" type="uuid" dir="in">
6307 <desc>UUID of the USB device to search for.</desc>
6308 </param>
6309 <param name="device" type="IUSBDevice" dir="return">
6310 <desc>Found USB device object.</desc>
6311 </param>
6312 </method>
6313
6314 <method name="createSharedFolder">
6315 <desc>
6316 Creates a transient new shared folder by associating the given logical
6317 name with the given host path, adds it to the collection of shared
6318 folders and starts sharing it. Refer to the description of
6319 <link to="ISharedFolder"/> to read more about logical names.
6320
6321 <result name="VBOX_E_INVALID_VM_STATE">
6322 Virtual machine in Saved state or currently changing state.
6323 </result>
6324 <result name="VBOX_E_FILE_ERROR">
6325 Shared folder already exists or not accessible.
6326 </result>
6327 </desc>
6328 <param name="name" type="wstring" dir="in">
6329 <desc>Unique logical name of the shared folder.</desc>
6330 </param>
6331 <param name="hostPath" type="wstring" dir="in">
6332 <desc>Full path to the shared folder in the host file system.</desc>
6333 </param>
6334 <param name="writable" type="boolean" dir="in">
6335 <desc>Whether the share is writable or readonly</desc>
6336 </param>
6337 </method>
6338
6339 <method name="removeSharedFolder">
6340 <desc>
6341 Removes a transient shared folder with the given name previously
6342 created by <link to="#createSharedFolder"/> from the collection of
6343 shared folders and stops sharing it.
6344 <result name="VBOX_E_INVALID_VM_STATE">
6345 Virtual machine in Saved state or currently changing state.
6346 </result>
6347 <result name="VBOX_E_FILE_ERROR">
6348 Shared folder does not exists.
6349 </result>
6350 </desc>
6351 <param name="name" type="wstring" dir="in">
6352 <desc>Logical name of the shared folder to remove.</desc>
6353 </param>
6354 </method>
6355
6356 <method name="takeSnapshot">
6357 <desc>
6358 Saves the current execution state and all settings of the
6359 machine and creates differencing images for all
6360 normal (non-independent) hard disks.
6361
6362 This method can be called for a PoweredOff, Saved, Running or
6363 Paused virtual machine. When the machine is PoweredOff, an
6364 offline <link to="ISnapshot">snapshot</link> is created,
6365 in all other cases -- an online snapshot.
6366
6367 The taken snapshot is always based on the
6368 <link to="IMachine::currentSnapshot">current
6369 snapshot</link> of the associated virtual machine and becomes
6370 a new current snapshot.
6371
6372 <note>
6373 This method implicitly calls <link to="IMachine::saveSettings"/> to
6374 save all current machine settings before taking an offline snapshot.
6375 </note>
6376
6377 <see>ISnapshot, <link to="#saveState"/></see>
6378 <result name="VBOX_E_INVALID_VM_STATE">
6379 Virtual machine currently changing state.
6380 </result>
6381 </desc>
6382 <param name="name" type="wstring" dir="in">
6383 <desc>Short name for the snapshot.</desc>
6384 </param>
6385 <param name="description" type="wstring" dir="in">
6386 <desc>Optional description of the snapshot.</desc>
6387 </param>
6388 <param name="progress" type="IProgress" dir="return">
6389 <desc>Progress object to track the operation completion.</desc>
6390 </param>
6391 </method>
6392
6393 <method name="discardSnapshot">
6394 <desc>
6395
6396 Starts discarding the specified snapshot. The execution state
6397 and settings of the associated machine stored in the snapshot
6398 will be deleted. The contents of all differencing hard disks of
6399 this snapshot will be merged with the contents of their
6400 dependent child hard disks to keep the, disks valid (in other
6401 words, all changes represented by hard disks being discarded
6402 will be propagated to their child hard disks). After that, this
6403 snapshot's differencing hard disks will be deleted. The parent
6404 of this snapshot will become a new parent for all its child
6405 snapshots.
6406
6407 If the discarded snapshot is the current one, its parent
6408 snapshot will become a new current snapshot. The current machine
6409 state is not directly affected in this case, except that
6410 currently attached differencing hard disks based on hard disks
6411 of the discarded snapshot will be also merged as described
6412 above.
6413
6414 If the discarded snapshot is the first one (the root snapshot)
6415 and it has exactly one child snapshot, this child snapshot will
6416 become the first snapshot after discarding. If there are no
6417 children at all (i.e. the first snapshot is the only snapshot of
6418 the machine), both the current and the first snapshot of the
6419 machine will be set to null. In all other cases, the first
6420 snapshot cannot be discarded.
6421
6422 You cannot discard the snapshot if it
6423 stores <link to="HardDiskType_Normal">normal</link> (non-differencing)
6424 hard disks that have differencing hard disks based on them. Snapshots of
6425 such kind can be discarded only when every normal hard disk has either
6426 no children at all or exactly one child. In the former case, the normal
6427 hard disk simply becomes unused (i.e. not attached to any VM). In the
6428 latter case, it receives all the changes stored in the child hard disk,
6429 and then it replaces the child hard disk in the configuration of the
6430 corresponding snapshot or machine.
6431
6432 Also, you cannot discard the snapshot if it stores hard disks
6433 (of any type) having differencing child hard disks that belong
6434 to other machines. Such snapshots can be only discarded after
6435 you discard all snapshots of other machines containing "foreign"
6436 child disks, or detach these "foreign" child disks from machines
6437 they are attached to.
6438
6439 One particular example of the snapshot storing normal hard disks
6440 is the first snapshot of a virtual machine that had normal hard
6441 disks attached when taking the snapshot. Be careful when
6442 discarding such snapshots because this implicitly commits
6443 changes (made since the snapshot being discarded has been taken)
6444 to normal hard disks (as described above), which may be not what
6445 you want.
6446
6447 The virtual machine is put to
6448 the <link to="MachineState_Discarding">Discarding</link> state until
6449 the discard operation is completed.
6450
6451 <note>
6452 The machine must not be running, otherwise the operation
6453 will fail.
6454 </note>
6455
6456 <note>
6457 Child hard disks of all normal hard disks of the discarded snapshot
6458 must be accessible (see <link to="IMedium::state"/>) for this
6459 operation to succeed. In particular, this means that all virtual
6460 machines, whose hard disks are directly or indirectly based on the
6461 hard disks of discarded snapshot, must be powered off.
6462 </note>
6463 <note>
6464 Merging hard disk contents can be very time and disk space
6465 consuming, if these disks are big in size and have many
6466 children. However, if the snapshot being discarded is the last
6467 (head) snapshot on the branch, the operation will be rather
6468 quick.
6469 </note>
6470 <note>
6471 Note that discarding the current snapshot
6472 will implicitly call <link to="IMachine::saveSettings"/> to
6473 make all current machine settings permanent.
6474 </note>
6475 <result name="VBOX_E_INVALID_VM_STATE">
6476 Virtual machine is running.
6477 </result>
6478 </desc>
6479 <param name="id" type="uuid" dir="in">
6480 <desc>UUID of the snapshot to discard.</desc>
6481 </param>
6482 <param name="progress" type="IProgress" dir="return">
6483 <desc>Progress object to track the operation completion.</desc>
6484 </param>
6485 </method>
6486
6487 <method name="discardCurrentState">
6488 <desc>
6489 This operation is similar to <link to="#discardSnapshot"/> but
6490 affects the current machine state. This means that the state stored in
6491 the current snapshot will become a new current state, and all current
6492 settings of the machine and changes stored in differencing hard disks
6493 will be lost.
6494
6495 After this operation is successfully completed, new empty differencing
6496 hard disks are created for all normal hard disks of the machine.
6497
6498 If the current snapshot of the machine is an online snapshot, the
6499 machine will go to the <link to="MachineState_Saved"> saved
6500 state</link>, so that the next time it is powered on, the execution
6501 state will be restored from the current snapshot.
6502
6503 <note>
6504 The machine must not be running, otherwise the operation will fail.
6505 </note>
6506
6507 <note>
6508 If the machine state is <link to="MachineState_Saved">Saved</link>
6509 prior to this operation, the saved state file will be implicitly
6510 discarded (as if <link to="IConsole::discardSavedState"/> were
6511 called).
6512 </note>
6513
6514 <result name="VBOX_E_INVALID_VM_STATE">
6515 Virtual machine is running.
6516 </result>
6517 </desc>
6518 <param name="progress" type="IProgress" dir="return">
6519 <desc>Progress object to track the operation completion.</desc>
6520 </param>
6521 </method>
6522
6523 <method name="discardCurrentSnapshotAndState">
6524 <desc>
6525
6526 This method is equivalent to
6527 doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
6528 (currentSnapshot.id(), progress) followed by
6529 <link to="#discardCurrentState"/>.
6530
6531 As a result, the machine will be fully restored from the
6532 snapshot preceding the current snapshot, while both the current
6533 snapshot and the current machine state will be discarded.
6534
6535 If the current snapshot is the first snapshot of the machine (i.e. it
6536 has the only snapshot), the current machine state will be
6537 discarded <b>before</b> discarding the snapshot. In other words, the
6538 machine will be restored from its last snapshot, before discarding
6539 it. This differs from performing a single
6540 <link to="#discardSnapshot"/> call (note that no
6541 <link to="#discardCurrentState"/> will be possible after it)
6542 to the effect that the latter will preserve the current state instead of
6543 discarding it.
6544
6545 Unless explicitly mentioned otherwise, all remarks and
6546 limitations of the above two methods also apply to this method.
6547
6548 <note>
6549 The machine must not be running, otherwise the operation
6550 will fail.
6551 </note>
6552
6553 <note>
6554 If the machine state is <link to="MachineState_Saved">Saved</link>
6555 prior to this operation, the saved state file will be implicitly
6556 discarded (as if <link to="#discardSavedState"/> were
6557 called).
6558 </note>
6559
6560 <note>
6561 This method is more efficient than calling both of the above
6562 methods separately: it requires less IPC calls and provides
6563 a single progress object.
6564 </note>
6565
6566 <result name="VBOX_E_INVALID_VM_STATE">
6567 Virtual machine is running.
6568 </result>
6569 </desc>
6570 <param name="progress" type="IProgress" dir="return">
6571 <desc>Progress object to track the operation completion.</desc>
6572 </param>
6573 </method>
6574
6575 <method name="registerCallback">
6576 <desc>
6577 Registers a new console callback on this instance. The methods of the
6578 callback interface will be called by this instance when the appropriate
6579 event occurs.
6580 </desc>
6581 <param name="callback" type="IConsoleCallback" dir="in"/>
6582 </method>
6583
6584 <method name="unregisterCallback">
6585 <desc>
6586 Unregisters the console callback previously registered using
6587 <link to="#registerCallback"/>.
6588 <result name="E_INVALIDARG">
6589 Given @a callback handler is not registered.
6590 </result>
6591 </desc>
6592 <param name="callback" type="IConsoleCallback" dir="in"/>
6593 </method>
6594 </interface>
6595
6596 <!--
6597 // IHost
6598 /////////////////////////////////////////////////////////////////////////
6599 -->
6600
6601 <interface
6602 name="IHostDVDDrive" extends="$unknown"
6603 uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
6604 wsmap="managed"
6605 >
6606 <desc>
6607 The IHostDVDDrive interface represents the physical CD/DVD drive
6608 hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
6609 </desc>
6610
6611 <attribute name="name" type="wstring" readonly="yes">
6612 <desc>
6613 Returns the platform-specific device identifier.
6614 On DOS-like platforms, it is a drive name (e.g. R:).
6615 On Unix-like platforms, it is a device name (e.g. /dev/hdc).
6616 </desc>
6617 </attribute>
6618 <attribute name="description" type="wstring" readonly="yes">
6619 <desc>
6620 Returns a human readable description for the drive. This
6621 description usually contains the product and vendor name. A
6622 @c null string is returned if the description is not available.
6623 </desc>
6624 </attribute>
6625 <attribute name="udi" type="wstring" readonly="yes">
6626 <desc>
6627 Returns the unique device identifier for the drive. This
6628 attribute is reserved for future use instead of
6629 <link to="#name"/>. Currently it is not used and may return
6630 @c null on some platforms.
6631 </desc>
6632 </attribute>
6633
6634 </interface>
6635
6636 <interface
6637 name="IHostFloppyDrive" extends="$unknown"
6638 uuid="3f02d604-e908-4919-9fd1-8a4afd68fc63"
6639 wsmap="managed"
6640 >
6641 <desc>
6642 The IHostFloppyDrive interface represents the physical floppy drive
6643 hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
6644 </desc>
6645 <attribute name="name" type="wstring" readonly="yes">
6646 <desc>
6647 Returns the platform-specific device identifier.
6648 On DOS-like platforms, it is a drive name (e.g. A:).
6649 On Unix-like platforms, it is a device name (e.g. /dev/fd0).
6650 </desc>
6651 </attribute>
6652 <attribute name="description" type="wstring" readonly="yes">
6653 <desc>
6654 Returns a human readable description for the drive. This
6655 description usually contains the product and vendor name. A
6656 @c null string is returned if the description is not available.
6657 </desc>
6658 </attribute>
6659 <attribute name="udi" type="wstring" readonly="yes">
6660 <desc>
6661 Returns the unique device identifier for the drive. This
6662 attribute is reserved for future use instead of
6663 <link to="#name"/>. Currently it is not used and may return
6664 @c null on some platforms.
6665 </desc>
6666 </attribute>
6667 </interface>
6668
6669 <enum
6670 name="HostNetworkInterfaceMediumType"
6671 uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
6672 >
6673 <desc>
6674 Type of encapsulation. Ethernet encapsulation includes both wired and
6675 wireless Ethernet connections.
6676 <see>IHostNetworkInterface</see>
6677 </desc>
6678
6679 <const name="Unknown" value="0">
6680 <desc>
6681 The type of interface cannot be determined.
6682 </desc>
6683 </const>
6684 <const name="Ethernet" value="1">
6685 <desc>
6686 Ethernet frame encapsulation.
6687 </desc>
6688 </const>
6689 <const name="PPP" value="2">
6690 <desc>
6691 Point-to-point protocol encapsulation.
6692 </desc>
6693 </const>
6694 <const name="SLIP" value="3">
6695 <desc>
6696 Serial line IP encapsulation.
6697 </desc>
6698 </const>
6699 </enum>
6700
6701 <enum
6702 name="HostNetworkInterfaceStatus"
6703 uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
6704 >
6705 <desc>
6706 Current status of the interface.
6707 <see>IHostNetworkInterface</see>
6708 </desc>
6709
6710 <const name="Unknown" value="0">
6711 <desc>
6712 The state of interface cannot be determined.
6713 </desc>
6714 </const>
6715 <const name="Up" value="1">
6716 <desc>
6717 The interface is fully operational.
6718 </desc>
6719 </const>
6720 <const name="Down" value="2">
6721 <desc>
6722 The interface is not functioning.
6723 </desc>
6724 </const>
6725 </enum>
6726
6727 <enum
6728 name="HostNetworkInterfaceType"
6729 uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
6730 >
6731 <desc>
6732 Network interface type.
6733 </desc>
6734 <const name="Bridged" value="1"/>
6735 <const name="HostOnly" value="2"/>
6736 </enum>
6737
6738 <interface
6739 name="IHostNetworkInterface" extends="$unknown"
6740 uuid="88adaf3f-166b-4542-9457-0f1323507fae"
6741 wsmap="managed"
6742 >
6743 <desc>
6744 Reprents one of host's network interfaces. IP V6 address and network
6745 mask are strings of 32 hexdecimal digits grouped by four. Groups are
6746 separated by colons.
6747 For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
6748 </desc>
6749 <attribute name="name" type="wstring" readonly="yes">
6750 <desc>Returns the host network interface name.</desc>
6751 </attribute>
6752
6753 <attribute name="id" type="uuid" readonly="yes">
6754 <desc>Returns the interface UUID.</desc>
6755 </attribute>
6756
6757 <attribute name="networkName" type="wstring" readonly="yes">
6758 <desc>Returns the name of a virtual network the interface gets attached to.</desc>
6759 </attribute>
6760
6761 <attribute name="dhcpEnabled" type="boolean" readonly="yes">
6762 <desc>Specifies whether the DHCP is enabled for the interface.</desc>
6763 </attribute>
6764
6765 <attribute name="IPAddress" type="wstring" readonly="yes">
6766 <desc>Returns the IP V4 address of the interface.</desc>
6767 </attribute>
6768
6769 <attribute name="networkMask" type="wstring" readonly="yes">
6770 <desc>Returns the network mask of the interface.</desc>
6771 </attribute>
6772
6773 <attribute name="IPV6Supported" type="boolean" readonly="yes">
6774 <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
6775 </attribute>
6776
6777 <attribute name="IPV6Address" type="wstring" readonly="yes">
6778 <desc>Returns the IP V6 address of the interface.</desc>
6779 </attribute>
6780
6781 <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
6782 <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
6783 </attribute>
6784
6785 <attribute name="hardwareAddress" type="wstring" readonly="yes">
6786 <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
6787 </attribute>
6788
6789 <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
6790 <desc>Type of protocol encapsulation used.</desc>
6791 </attribute>
6792
6793 <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
6794 <desc>Status of the interface.</desc>
6795 </attribute>
6796
6797 <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
6798 <desc>specifies the host interface type.</desc>
6799 </attribute>
6800
6801 <method name="enableStaticIpConfig">
6802 <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
6803 <param name="IPAddress" type="wstring" dir="in">
6804 <desc>
6805 IP address.
6806 </desc>
6807 </param>
6808 <param name="networkMask" type="wstring" dir="in">
6809 <desc>
6810 network mask.
6811 </desc>
6812 </param>
6813 </method>
6814
6815 <method name="enableStaticIpConfigV6">
6816 <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
6817 <param name="IPV6Address" type="wstring" dir="in">
6818 <desc>
6819 IP address.
6820 </desc>
6821 </param>
6822 <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
6823 <desc>
6824 network mask.
6825 </desc>
6826 </param>
6827 </method>
6828
6829 <method name="enableDynamicIpConfig">
6830 <desc>enables the dynamic IP configuration.</desc>
6831 </method>
6832
6833 <method name="dhcpRediscover">
6834 <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
6835 </method>
6836
6837 </interface>
6838
6839 <interface
6840 name="IHost" extends="$unknown"
6841 uuid="926469ca-9091-42ef-928e-582d78b66c70"
6842 wsmap="managed"
6843 >
6844 <desc>
6845 The IHost interface represents the physical machine that this VirtualBox
6846 installation runs on.
6847
6848 An object implementing this interface is returned by the
6849 <link to="IVirtualBox::host" /> attribute. This interface contains
6850 read-only information about the host's physical hardware (such as what
6851 processors and disks are available, what the host operating system is,
6852 and so on) and also allows for manipulating some of the host's hardware,
6853 such as global USB device filters and host interface networking.
6854
6855 </desc>
6856 <attribute name="DVDDrives" type="IHostDVDDrive" readonly="yes" safearray="yes">
6857 <desc>List of DVD drives available on the host.</desc>
6858 </attribute>
6859
6860 <attribute name="floppyDrives" type="IHostFloppyDrive" readonly="yes" safearray="yes">
6861 <desc>List of floppy drives available on the host.</desc>
6862 </attribute>
6863
6864 <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
6865 <desc>
6866 List of USB devices currently attached to the host.
6867 Once a new device is physically attached to the host computer,
6868 it appears in this list and remains there until detached.
6869
6870 <note>
6871 This method may set a @ref com_warnings "warning result code".
6872 </note>
6873 <note>
6874 If USB functionality is not available in the given edition of
6875 VirtualBox, this method will set the result code to @c E_NOTIMPL.
6876 </note>
6877 </desc>
6878 </attribute>
6879
6880 <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
6881 <desc>
6882 List of USB device filters in action.
6883 When a new device is physically attached to the host computer,
6884 filters from this list are applied to it (in order they are stored
6885 in the list). The first matched filter will determine the
6886 <link to="IHostUSBDeviceFilter::action">action</link>
6887 performed on the device.
6888
6889 Unless the device is ignored by these filters, filters of all
6890 currently running virtual machines
6891 (<link to="IUSBController::deviceFilters"/>) are applied to it.
6892
6893 <note>
6894 This method may set a @ref com_warnings "warning result code".
6895 </note>
6896 <note>
6897 If USB functionality is not available in the given edition of
6898 VirtualBox, this method will set the result code to @c E_NOTIMPL.
6899 </note>
6900
6901 <see>IHostUSBDeviceFilter, USBDeviceState</see>
6902 </desc>
6903 </attribute>
6904
6905 <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
6906 <desc>List of host network interfaces currently defined on the host.</desc>
6907 </attribute>
6908
6909 <attribute name="processorCount" type="unsigned long" readonly="yes">
6910 <desc>Number of (logical) CPUs installed in the host system.</desc>
6911 </attribute>
6912
6913 <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
6914 <desc>Number of (logical) CPUs online in the host system.</desc>
6915 </attribute>
6916
6917 <method name="getProcessorSpeed">
6918 <desc>Query the (approximate) maximum speed of a specified host CPU in
6919 Megahertz.
6920 </desc>
6921 <param name="cpuId" type="unsigned long" dir="in">
6922 <desc>
6923 Identifier of the CPU.
6924 </desc>
6925 </param>
6926 <param name="speed" type="unsigned long" dir="return">
6927 <desc>
6928 Speed value. 0 is returned if value is not known or @a cpuId is
6929 invalid.
6930 </desc>
6931 </param>
6932 </method>
6933
6934 <method name="getProcessorFeature">
6935 <desc>Query whether a CPU feature is supported or not.</desc>
6936 <param name="feature" type="ProcessorFeature" dir="in">
6937 <desc>
6938 CPU Feature identifier.
6939 </desc>
6940 </param>
6941 <param name="supported" type="boolean" dir="return">
6942 <desc>
6943 Feature is supported or not.
6944 </desc>
6945 </param>
6946 </method>
6947
6948 <method name="getProcessorDescription">
6949 <desc>Query the model string of a specified host CPU.
6950 <note>
6951 This function is not implemented in the current version of the
6952 product.
6953 </note>
6954 </desc>
6955 <param name="cpuId" type="unsigned long" dir="in">
6956 <desc>
6957 Identifier of the CPU.
6958 </desc>
6959 </param>
6960 <param name="description" type="wstring" dir="return">
6961 <desc>
6962 Model string. A NULL string is returned if value is not known or
6963 @a cpuId is invalid.
6964 </desc>
6965 </param>
6966 </method>
6967
6968 <attribute name="memorySize" type="unsigned long" readonly="yes">
6969 <desc>Amount of system memory in megabytes installed in the host system.</desc>
6970 </attribute>
6971
6972 <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
6973 <desc>Available system memory in the host system.</desc>
6974 </attribute>
6975
6976 <attribute name="operatingSystem" type="wstring" readonly="yes">
6977 <desc>Name of the host system's operating system.</desc>
6978 </attribute>
6979
6980 <attribute name="OSVersion" type="wstring" readonly="yes">
6981 <desc>Host operating system's version string.</desc>
6982 </attribute>
6983
6984 <attribute name="UTCTime" type="long long" readonly="yes">
6985 <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
6986 </attribute>
6987
6988<if target="midl">
6989 <method name="createHostOnlyNetworkInterface">
6990 <desc>
6991 Creates a new adapter for Host Only Networking.
6992 <result name="E_INVALIDARG">
6993 Host network interface @a name already exists.
6994 </result>
6995 </desc>
6996 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
6997 <desc>
6998 Created host interface object.
6999 </desc>
7000 </param>
7001 <param name="progress" type="IProgress" dir="return">
7002 <desc>
7003 Progress object to track the operation completion.
7004 </desc>
7005 </param>
7006 </method>
7007 <method name="removeHostOnlyNetworkInterface">
7008 <desc>
7009 Removes the given Host Only Networking interface.
7010 <result name="VBOX_E_OBJECT_NOT_FOUND">
7011 No host network interface matching @a id found.
7012 </result>
7013 </desc>
7014 <param name="id" type="uuid" dir="in">
7015 <desc>
7016 Adapter GUID.
7017 </desc>
7018 </param>
7019 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
7020 <desc>
7021 Removed host interface object.
7022 </desc>
7023 </param>
7024 <param name="progress" type="IProgress" dir="return">
7025 <desc>
7026 Progress object to track the operation completion.
7027 </desc>
7028 </param>
7029 </method>
7030</if>
7031
7032 <method name="createUSBDeviceFilter">
7033 <desc>
7034 Creates a new USB device filter. All attributes except
7035 the filter name are set to <tt>null</tt> (any match),
7036 <i>active</i> is <tt>false</tt> (the filter is not active).
7037
7038 The created filter can be added to the list of filters using
7039 <link to="#insertUSBDeviceFilter"/>.
7040
7041 <see>#USBDeviceFilters</see>
7042 </desc>
7043 <param name="name" type="wstring" dir="in">
7044 <desc>
7045 Filter name. See <link to="IHostUSBDeviceFilter::name"/>
7046 for more info.
7047 </desc>
7048 </param>
7049 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
7050 <desc>Created filter object.</desc>
7051 </param>
7052 </method>
7053
7054 <method name="insertUSBDeviceFilter">
7055 <desc>
7056 Inserts the given USB device to the specified position
7057 in the list of filters.
7058
7059 Positions are numbered starting from <tt>0</tt>. If the specified
7060 position is equal to or greater than the number of elements in
7061 the list, the filter is added at the end of the collection.
7062
7063 <note>
7064 Duplicates are not allowed, so an attempt to insert a
7065 filter that is already in the list, will return an
7066 error.
7067 </note>
7068 <note>
7069 This method may set a @ref com_warnings "warning result code".
7070 </note>
7071 <note>
7072 If USB functionality is not available in the given edition of
7073 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7074 </note>
7075
7076 <see>#USBDeviceFilters</see>
7077
7078 <result name="VBOX_E_INVALID_OBJECT_STATE">
7079 USB device filter is not created within this VirtualBox instance.
7080 </result>
7081 <result name="E_INVALIDARG">
7082 USB device filter already in list.
7083 </result>
7084
7085 </desc>
7086 <param name="position" type="unsigned long" dir="in">
7087 <desc>Position to insert the filter to.</desc>
7088 </param>
7089 <param name="filter" type="IHostUSBDeviceFilter" dir="in">
7090 <desc>USB device filter to insert.</desc>
7091 </param>
7092 </method>
7093
7094 <method name="removeUSBDeviceFilter">
7095 <desc>
7096 Removes a USB device filter from the specified position in the
7097 list of filters.
7098
7099 Positions are numbered starting from <tt>0</tt>. Specifying a
7100 position equal to or greater than the number of elements in
7101 the list will produce an error.
7102
7103 <note>
7104 This method may set a @ref com_warnings "warning result code".
7105 </note>
7106 <note>
7107 If USB functionality is not available in the given edition of
7108 VirtualBox, this method will set the result code to @c E_NOTIMPL.
7109 </note>
7110
7111 <see>#USBDeviceFilters</see>
7112
7113 <result name="E_INVALIDARG">
7114 USB device filter list empty or invalid @a position.
7115 </result>
7116
7117 </desc>
7118 <param name="position" type="unsigned long" dir="in">
7119 <desc>Position to remove the filter from.</desc>
7120 </param>
7121 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
7122 <desc>Removed USB device filter.</desc>
7123 </param>
7124 </method>
7125
7126 <method name="findHostDVDDrive">
7127 <desc>
7128 Searches for a host DVD drive with the given @c name.
7129
7130 <result name="VBOX_E_OBJECT_NOT_FOUND">
7131 Given @c name does not correspond to any host drive.
7132 </result>
7133
7134 </desc>
7135 <param name="name" type="wstring" dir="in">
7136 <desc>Name of the host drive to search for</desc>
7137 </param>
7138 <param name="drive" type="IHostDVDDrive" dir="return">
7139 <desc>Found host drive object</desc>
7140 </param>
7141 </method>
7142
7143 <method name="findHostFloppyDrive">
7144 <desc>
7145 Searches for a host floppy drive with the given @c name.
7146
7147 <result name="VBOX_E_OBJECT_NOT_FOUND">
7148 Given @c name does not correspond to any host floppy drive.
7149 </result>
7150
7151 </desc>
7152 <param name="name" type="wstring" dir="in">
7153 <desc>Name of the host floppy drive to search for</desc>
7154 </param>
7155 <param name="drive" type="IHostFloppyDrive" dir="return">
7156 <desc>Found host floppy drive object</desc>
7157 </param>
7158 </method>
7159
7160 <method name="findHostNetworkInterfaceByName">
7161 <desc>
7162 Searches through all host network interfaces for an interface with
7163 the given @c name.
7164 <note>
7165 The method returns an error if the given @c name does not
7166 correspond to any host network interface.
7167 </note>
7168 </desc>
7169 <param name="name" type="wstring" dir="in">
7170 <desc>Name of the host network interface to search for.</desc>
7171 </param>
7172 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7173 <desc>Found host network interface object.</desc>
7174 </param>
7175 </method>
7176 <method name="findHostNetworkInterfaceById">
7177 <desc>
7178 Searches through all host network interfaces for an interface with
7179 the given GUID.
7180 <note>
7181 The method returns an error if the given GUID does not
7182 correspond to any host network interface.
7183 </note>
7184 </desc>
7185 <param name="id" type="uuid" dir="in">
7186 <desc>GUID of the host network interface to search for.</desc>
7187 </param>
7188 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
7189 <desc>Found host network interface object.</desc>
7190 </param>
7191 </method>
7192 <method name="findHostNetworkInterfacesOfType">
7193 <desc>
7194 Searches through all host network interfaces and returns a list of interfaces of the specified type
7195 </desc>
7196 <param name="type" type="HostNetworkInterfaceType" dir="in">
7197 <desc>type of the host network interfaces to search for.</desc>
7198 </param>
7199 <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
7200 <desc>Found host network interface objects.</desc>
7201 </param>
7202 </method>
7203
7204 <method name="findUSBDeviceById">
7205 <desc>
7206 Searches for a USB device with the given UUID.
7207
7208 <result name="VBOX_E_OBJECT_NOT_FOUND">
7209 Given @id does not correspond to any USB device.
7210 </result>
7211
7212 <see>IHostUSBDevice::id</see>
7213 </desc>
7214 <param name="id" type="uuid" dir="in">
7215 <desc>UUID of the USB device to search for.</desc>
7216 </param>
7217 <param name="device" type="IHostUSBDevice" dir="return">
7218 <desc>Found USB device object.</desc>
7219 </param>
7220 </method>
7221
7222 <method name="findUSBDeviceByAddress">
7223 <desc>
7224 Searches for a USB device with the given host address.
7225
7226 <result name="VBOX_E_OBJECT_NOT_FOUND">
7227 Given @c name does not correspond to any USB device.
7228 </result>
7229
7230 <see>IHostUSBDevice::address</see>
7231 </desc>
7232 <param name="name" type="wstring" dir="in">
7233 <desc>
7234 Address of the USB device (as assigned by the host) to
7235 search for.
7236 </desc>
7237 </param>
7238 <param name="device" type="IHostUSBDevice" dir="return">
7239 <desc>Found USB device object.</desc>
7240 </param>
7241 </method>
7242
7243 </interface>
7244
7245 <!--
7246 // ISystemProperties
7247 /////////////////////////////////////////////////////////////////////////
7248 -->
7249
7250 <interface
7251 name="ISystemProperties"
7252 extends="$unknown"
7253 uuid="0760e03f-06d0-481e-9f81-be43fef092ba"
7254 wsmap="managed"
7255 >
7256 <desc>
7257 The ISystemProperties interface represents global properties of the given
7258 VirtualBox installation.
7259
7260 These properties define limits and default values for various attributes
7261 and parameters. Most of the properties are read-only, but some can be
7262 changed by a user.
7263 </desc>
7264
7265 <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
7266 <desc>Minimum guest system memory in Megabytes.</desc>
7267 </attribute>
7268
7269 <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
7270 <desc>Maximum guest system memory in Megabytes.</desc>
7271 </attribute>
7272
7273 <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
7274 <desc>Minimum guest video memory in Megabytes.</desc>
7275 </attribute>
7276
7277 <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
7278 <desc>Maximum guest video memory in Megabytes.</desc>
7279 </attribute>
7280
7281 <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
7282 <desc>Minimum CPU count.</desc>
7283 </attribute>
7284
7285 <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
7286 <desc>Maximum CPU count.</desc>
7287 </attribute>
7288
7289 <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
7290 <desc>Maximum size of a virtual disk image in Megabytes.</desc>
7291 </attribute>
7292
7293 <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
7294 <desc>
7295 Number of network adapters associated with every
7296 <link to="IMachine"/> instance.
7297 </desc>
7298 </attribute>
7299
7300 <attribute name="serialPortCount" type="unsigned long" readonly="yes">
7301 <desc>
7302 Number of serial ports associated with every
7303 <link to="IMachine"/> instance.
7304 </desc>
7305 </attribute>
7306
7307 <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
7308 <desc>
7309 Number of parallel ports associated with every
7310 <link to="IMachine"/> instance.
7311 </desc>
7312 </attribute>
7313
7314 <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
7315 <desc>
7316 Maximum device position in the boot order. This value corresponds
7317 to the total number of devices a machine can boot from, to make it
7318 possible to include all possible devices to the boot list.
7319 <see><link to="IMachine::setBootOrder"/></see>
7320 </desc>
7321 </attribute>
7322
7323 <attribute name="defaultMachineFolder" type="wstring">
7324 <desc>
7325 Full path to the default directory used to create new or open
7326 existing machines when a settings file name contains no
7327 path.
7328
7329 The initial value of this property is
7330 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
7331 VirtualBox_home</link><tt>&gt;/Machines</tt>.
7332
7333 <note>
7334 Setting this property to <tt>null</tt> will restore the
7335 initial value.
7336 </note>
7337 <note>
7338 When settings this property, the specified path can be
7339 absolute (full path) or relative
7340 to the <link to="IVirtualBox::homeFolder">
7341 VirtualBox home directory</link>.
7342 When reading this property, a full path is
7343 always returned.
7344 </note>
7345 <note>
7346 The specified path may not exist, it will be created
7347 when necessary.
7348 </note>
7349
7350 <see>
7351 <link to="IVirtualBox::createMachine"/>,
7352 <link to="IVirtualBox::openMachine"/>
7353 </see>
7354 </desc>
7355 </attribute>
7356
7357 <attribute name="defaultHardDiskFolder" type="wstring">
7358 <desc>
7359 Full path to the default directory used to create new or open existing
7360 virtual disks.
7361
7362 This path is used when the storage unit of a hard disk is a regular file
7363 in the host's file system and only a file name that contains no path is
7364 given.
7365
7366 The initial value of this property is
7367 <tt>&lt;</tt>
7368 <link to="IVirtualBox::homeFolder">VirtualBox_home</link>
7369 <tt>&gt;/HardDisks</tt>.
7370
7371 <note>
7372 Setting this property to <tt>null</tt> will restore the
7373 initial value.
7374 </note>
7375 <note>
7376 When settings this property, the specified path can be relative
7377 to the
7378 <link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
7379 absolute. When reading this property, a full path is
7380 always returned.
7381 </note>
7382 <note>
7383 The specified path may not exist, it will be created
7384 when necessary.
7385 </note>
7386
7387 <see>
7388 IHardDisk,
7389 <link to="IVirtualBox::createHardDisk"/>,
7390 <link to="IVirtualBox::openHardDisk"/>,
7391 <link to="IMedium::location"/>
7392 </see>
7393 </desc>
7394 </attribute>
7395
7396 <attribute name="hardDiskFormats" type="IHardDiskFormat" safearray="yes" readonly="yes">
7397 <desc>
7398 List of all hard disk storage formats supported by this VirtualBox
7399 installation.
7400
7401 Keep in mind that the hard disk format identifier
7402 (<link to="IHardDiskFormat::id"/>) used in other API calls like
7403 <link to="IVirtualBox::createHardDisk"/> to refer to a particular
7404 hard disk format is a case-insensitive string. This means that, for
7405 example, all of the following strings:
7406 <pre>
7407 "VDI"
7408 "vdi"
7409 "VdI"</pre>
7410 refer to the same hard disk format.
7411
7412 Note that the virtual hard disk framework is backend-based, therefore
7413 the list of supported formats depends on what backends are currently
7414 installed.
7415
7416 <see>
7417 <link to="IHardDiskFormat"/>,
7418 </see>
7419 </desc>
7420 </attribute>
7421
7422 <attribute name="defaultHardDiskFormat" type="wstring">
7423 <desc>
7424 Identifier of the default hard disk format used by VirtualBox.
7425
7426 The hard disk format set by this attribute is used by VirtualBox
7427 when the hard disk format was not specified explicitly. One example is
7428 <link to="IVirtualBox::createHardDisk"/> with the <tt>null</tt>
7429 format argument. A more complex example is implicit creation of
7430 differencing hard disks when taking a snapshot of a virtual machine:
7431 this operation will try to use a format of the parent hard disk first
7432 and if this format does not support differencing hard disks the default
7433 format specified by this argument will be used.
7434
7435 The list of supported hard disk formats may be obtained by the
7436 <link to="#hardDiskFormats"/> call. Note that the default hard disk
7437 format must have a capability to create differencing hard disks;
7438 otherwise opeartions that create hard disks implicitly may fail
7439 unexpectedly.
7440
7441 The initial value of this property is <tt>VDI</tt> in the current
7442 version of the VirtualBox product, but may change in the future.
7443
7444 <note>
7445 Setting this property to <tt>null</tt> will restore the
7446 initial value.
7447 </note>
7448
7449 <see>
7450 <link to="#hardDiskFormats"/>,
7451 <link to="IHardDiskFormat::id"/>,
7452 <link to="IVirtualBox::createHardDisk"/>
7453 </see>
7454 </desc>
7455 </attribute>
7456
7457 <attribute name="remoteDisplayAuthLibrary" type="wstring">
7458 <desc>
7459 Library that provides authentication for VRDP clients. The library
7460 is used if a virtual machine's authentication type is set to "external"
7461 in the VM RemoteDisplay configuration.
7462
7463 The system library extension (".DLL" or ".so") must be omitted.
7464 A full path can be specified; if not, then the library must reside on the
7465 system's default library path.
7466
7467 The default value of this property is <tt>VRDPAuth</tt>. There is a library
7468 of that name in one of the default VirtualBox library directories.
7469
7470 For details about VirtualBox authentication libraries and how to implement
7471 them, please refer to the VirtualBox manual.
7472
7473 <note>
7474 Setting this property to <tt>null</tt> will restore the
7475 initial value.
7476 </note>
7477 </desc>
7478 </attribute>
7479
7480 <attribute name="webServiceAuthLibrary" type="wstring">
7481 <desc>
7482 Library that provides authentication for webservice clients. The library
7483 is used if a virtual machine's authentication type is set to "external"
7484 in the VM RemoteDisplay configuration and will be called from
7485 within the <link to="IWebsessionManager::logon" /> implementation.
7486
7487 As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
7488 there is no per-VM setting for this, as the webservice is a global
7489 resource (if it is running). Only for this setting (for the webservice),
7490 setting this value to a literal "null" string disables authentication,
7491 meaning that <link to="IWebsessionManager::logon" /> will always succeed,
7492 no matter what user name and password are supplied.
7493
7494 The initial value of this property is <tt>VRDPAuth</tt>,
7495 meaning that the webservice will use the same authentication
7496 library that is used by default for VBoxVRDP (again, see
7497 <link to="ISystemProperties::remoteDisplayAuthLibrary" />).
7498 The format and calling convention of authentication libraries
7499 is the same for the webservice as it is for VBoxVRDP.
7500
7501 </desc>
7502 </attribute>
7503
7504 <attribute name="HWVirtExEnabled" type="boolean">
7505 <desc>
7506 This specifies the default value for hardware virtualization
7507 extensions. If enabled, virtual machines will make use of
7508 hardware virtualization extensions such as Intel VT-x and
7509 AMD-V by default. This value can be overridden by each VM
7510 using their <link to="IMachine::HWVirtExEnabled" /> property.
7511 </desc>
7512 </attribute>
7513
7514 <attribute name="LogHistoryCount" type="unsigned long">
7515 <desc>
7516 This value specifies how many old release log files are kept.
7517 </desc>
7518 </attribute>
7519 </interface>
7520
7521 <!--
7522 // IGuest
7523 /////////////////////////////////////////////////////////////////////////
7524 -->
7525
7526 <interface
7527 name="IGuestOSType" extends="$unknown"
7528 uuid="cfe9e64c-4430-435b-9e7c-e3d8e417bd58"
7529 wsmap="struct"
7530 >
7531 <desc>
7532 </desc>
7533
7534 <attribute name="familyId" type="wstring" readonly="yes">
7535 <desc>Guest OS family identifier string.</desc>
7536 </attribute>
7537
7538 <attribute name="familyDescription" type="wstring" readonly="yes">
7539 <desc>Human readable description of the guest OS family.</desc>
7540 </attribute>
7541
7542 <attribute name="id" type="wstring" readonly="yes">
7543 <desc>Guest OS identifier string.</desc>
7544 </attribute>
7545
7546 <attribute name="description" type="wstring" readonly="yes">
7547 <desc>Human readable description of the guest OS.</desc>
7548 </attribute>
7549
7550 <attribute name="is64Bit" type="boolean" readonly="yes">
7551 <desc>Returns @c true if the given OS is 64-bit</desc>
7552 </attribute>
7553
7554 <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
7555 <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
7556 </attribute>
7557
7558 <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
7559 <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
7560 </attribute>
7561
7562 <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
7563 <desc>Recommended RAM size in Megabytes.</desc>
7564 </attribute>
7565
7566 <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
7567 <desc>Recommended video RAM size in Megabytes.</desc>
7568 </attribute>
7569
7570 <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
7571 <desc>Recommended hard disk size in Megabytes.</desc>
7572 </attribute>
7573
7574 <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
7575 <desc>Returns recommended network adapter for this OS type.</desc>
7576 </attribute>
7577 </interface>
7578
7579 <interface
7580 name="IGuest" extends="$unknown"
7581 uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
7582
7583 wsmap="suppress"
7584 >
7585 <desc>
7586 The IGuest interface represents information about the operating system
7587 running inside the virtual machine. Used in
7588 <link to="IConsole::guest"/>.
7589
7590 IGuest provides information about the guest operating system, whether
7591 Guest Additions are installed and other OS-specific virtual machine
7592 properties.
7593 </desc>
7594
7595 <attribute name="OSTypeId" type="wstring" readonly="yes">
7596 <desc>
7597 Identifier of the Guest OS type as reported by the Guest
7598 Additions.
7599 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
7600 an IGuestOSType object representing details about the given
7601 Guest OS type.
7602 <note>
7603 If Guest Additions are not installed, this value will be
7604 the same as <link to="IMachine::OSTypeId"/>.
7605 </note>
7606 </desc>
7607 </attribute>
7608
7609 <attribute name="additionsActive" type="boolean" readonly="yes">
7610 <desc>
7611 Flag whether the Guest Additions are installed and active
7612 in which case their version will be returned by the
7613 <link to="#additionsVersion"/> property.
7614 </desc>
7615 </attribute>
7616
7617 <attribute name="additionsVersion" type="wstring" readonly="yes">
7618 <desc>
7619 Version of the Guest Additions (3 decimal numbers separated
7620 by dots) or empty when the Additions are not installed. The
7621 Additions may also report a version but yet not be active as
7622 the version might be refused by VirtualBox (incompatible) or
7623 other failures occurred.
7624 </desc>
7625 </attribute>
7626
7627 <attribute name="supportsSeamless" type="boolean" readonly="yes">
7628 <desc>
7629 Flag whether seamless guest display rendering (seamless desktop
7630 integration) is supported.
7631 </desc>
7632 </attribute>
7633
7634 <attribute name="supportsGraphics" type="boolean" readonly="yes">
7635 <desc>
7636 Flag whether the guest is in graphics mode. If it is not, then
7637 seamless rendering will not work, resize hints are not immediately
7638 acted on and guest display resizes are probably not initiated by
7639 the guest additions.
7640 </desc>
7641 </attribute>
7642
7643 <attribute name="memoryBalloonSize" type="unsigned long">
7644 <desc>Guest system memory balloon size in megabytes.</desc>
7645 </attribute>
7646
7647 <attribute name="statisticsUpdateInterval" type="unsigned long">
7648 <desc>Interval to update guest statistics in seconds.</desc>
7649 </attribute>
7650
7651 <method name="setCredentials">
7652 <desc>
7653 Store login credentials that can be queried by guest operating
7654 systems with Additions installed. The credentials are transient
7655 to the session and the guest may also choose to erase them. Note
7656 that the caller cannot determine whether the guest operating system
7657 has queried or made use of the credentials.
7658
7659 <result name="VBOX_E_VM_ERROR">
7660 VMM device is not available.
7661 </result>
7662
7663 </desc>
7664 <param name="userName" type="wstring" dir="in">
7665 <desc>User name string, can be empty</desc>
7666 </param>
7667 <param name="password" type="wstring" dir="in">
7668 <desc>Password string, can be empty</desc>
7669 </param>
7670 <param name="domain" type="wstring" dir="in">
7671 <desc>Domain name (guest logon scheme specific), can be empty</desc>
7672 </param>
7673 <param name="allowInteractiveLogon" type="boolean" dir="in">
7674 <desc>
7675 Flag whether the guest should alternatively allow the user to
7676 interactively specify different credentials. This flag might
7677 not be supported by all versions of the Additions.
7678 </desc>
7679 </param>
7680 </method>
7681
7682 <method name="getStatistic">
7683 <desc>
7684 Query specified guest statistics as reported by the VirtualBox Additions.
7685 </desc>
7686 <param name="cpuId" type="unsigned long" dir="in">
7687 <desc>Virtual CPU id; not relevant for all statistic types</desc>
7688 </param>
7689 <param name="statistic" type="GuestStatisticType" dir="in">
7690 <desc>Statistic type.</desc>
7691 </param>
7692 <param name="statVal" type="unsigned long" dir="out">
7693 <desc>Statistics value</desc>
7694 </param>
7695 </method>
7696
7697 </interface>
7698
7699
7700 <!--
7701 // IProgress
7702 /////////////////////////////////////////////////////////////////////////
7703 -->
7704
7705 <interface
7706 name="IProgress" extends="$unknown"
7707 uuid="d3aa5417-6103-41fc-9e54-01ee1d08f42f"
7708 wsmap="managed"
7709 >
7710 <desc>
7711 The IProgress interface represents a task progress object that allows
7712 to wait for the completion of some asynchronous task.
7713
7714 The task consists of one or more operations that run sequentially,
7715 one by one. There is an individual percentage of completion of the
7716 current operation and the percentage of completion of the task as a
7717 whole. Similarly, you can wait for the completion of a particular
7718 operation or for the completion of the whole task.
7719
7720 Every operation is identified by a number (starting from 0)
7721 and has a separate description.
7722 </desc>
7723
7724 <attribute name="id" type="uuid" readonly="yes">
7725 <desc>ID of the task.</desc>
7726 </attribute>
7727
7728 <attribute name="description" type="wstring" readonly="yes">
7729 <desc>Description of the task.</desc>
7730 </attribute>
7731
7732 <attribute name="initiator" type="$unknown" readonly="yes">
7733 <desc>Initiator of the task.</desc>
7734 </attribute>
7735
7736 <attribute name="cancelable" type="boolean" readonly="yes">
7737 <desc>Whether the task can be interrupted.</desc>
7738 </attribute>
7739
7740 <attribute name="percent" type="long" readonly="yes">
7741 <desc>
7742 Current task progress value in percent.
7743 This value depends on how many operations are already complete.
7744 </desc>
7745 </attribute>
7746
7747 <attribute name="completed" type="boolean" readonly="yes">
7748 <desc>Whether the task has been completed.</desc>
7749 </attribute>
7750
7751 <attribute name="canceled" type="boolean" readonly="yes">
7752 <desc>Whether the task has been canceled.</desc>
7753 </attribute>
7754
7755 <attribute name="resultCode" type="result" readonly="yes">
7756 <desc>
7757 Result code of the progress task.
7758 Valid only if <link to="#completed"/> is true.
7759 </desc>
7760 </attribute>
7761
7762 <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
7763 <desc>
7764 Extended information about the unsuccessful result of the
7765 progress operation. May be NULL when no extended information
7766 is available.
7767 Valid only if <link to="#completed"/> is true and
7768 <link to="#resultCode"/> indicates a failure.
7769 </desc>
7770 </attribute>
7771
7772 <attribute name="operationCount" type="unsigned long" readonly="yes">
7773 <desc>
7774 Number of operations this task is divided into.
7775 Every task consists of at least one operation.
7776 </desc>
7777 </attribute>
7778
7779 <attribute name="operation" type="unsigned long" readonly="yes">
7780 <desc>Number of the operation being currently executed.</desc>
7781 </attribute>
7782
7783 <attribute name="operationDescription" type="wstring" readonly="yes">
7784 <desc>
7785 Description of the operation being currently executed.
7786 </desc>
7787 </attribute>
7788
7789 <attribute name="operationPercent" type="long" readonly="yes">
7790 <desc>Current operation progress value in percent.</desc>
7791 </attribute>
7792
7793 <method name="waitForCompletion">
7794 <desc>
7795 Waits until the task is done (including all operations) with a
7796 given timeout.
7797
7798 <result name="VBOX_E_IPRT_ERROR">
7799 Failed to wait for task completion.
7800 </result>
7801
7802 </desc>
7803 <param name="timeout" type="long" dir="in">
7804 <desc>
7805 Timeout value in milliseconds.
7806 Specify -1 for an indefinite wait.
7807 </desc>
7808 </param>
7809 </method>
7810
7811 <method name="waitForOperationCompletion">
7812 <desc>
7813 Waits until the given operation is done with a given timeout.
7814
7815 <result name="VBOX_E_IPRT_ERROR">
7816 Failed to wait for operation completion.
7817 </result>
7818
7819 </desc>
7820 <param name="operation" type="unsigned long" dir="in">
7821 <desc>
7822 Number of the operation to wait for.
7823 Must be less than <link to="#operationCount"/>.
7824 </desc>
7825 </param>
7826 <param name="timeout" type="long" dir="in">
7827 <desc>
7828 Timeout value in milliseconds.
7829 Specify -1 for an indefinite wait.
7830 </desc>
7831 </param>
7832 </method>
7833
7834 <method name="cancel">
7835 <desc>
7836 Cancels the task.
7837 <note>
7838 If <link to="#cancelable"/> is <tt>false</tt>, then
7839 this method will fail.
7840 </note>
7841
7842 <result name="VBOX_E_INVALID_OBJECT_STATE">
7843 Operation cannot be canceled.
7844 </result>
7845
7846 </desc>
7847 </method>
7848
7849 </interface>
7850
7851
7852 <!--
7853 // ISnapshot
7854 /////////////////////////////////////////////////////////////////////////
7855 -->
7856
7857 <interface
7858 name="ISnapshot" extends="$unknown"
7859 uuid="5db6b1d9-c76b-4424-a6f4-8257f642d6ea"
7860 wsmap="managed"
7861 >
7862 <desc>
7863 The ISnapshot interface represents a snapshot of the virtual
7864 machine.
7865
7866 The <i>snapshot</i> stores all the information about a virtual
7867 machine necessary to bring it to exactly the same state as it was at
7868 the time of taking the snapshot. The snapshot includes:
7869
7870 <ul>
7871 <li>all settings of the virtual machine (i.e. its hardware
7872 configuration: RAM size, attached hard disks, etc.)
7873 </li>
7874 <li>the execution state of the virtual machine (memory contents,
7875 CPU state, etc.).
7876 </li>
7877 </ul>
7878
7879 Snapshots can be <i>offline</i> (taken when the VM is powered off)
7880 or <i>online</i> (taken when the VM is running). The execution
7881 state of the offline snapshot is called a <i>zero execution state</i>
7882 (it doesn't actually contain any information about memory contents
7883 or the CPU state, assuming that all hardware is just powered off).
7884
7885 <h3>Snapshot branches</h3>
7886
7887 Snapshots can be chained. Chained snapshots form a branch where
7888 every next snapshot is based on the previous one. This chaining is
7889 mostly related to hard disk branching (see <link to="IHardDisk"/>
7890 description). This means that every time a new snapshot is created,
7891 a new differencing hard disk is implicitly created for all normal
7892 hard disks attached to the given virtual machine. This allows to
7893 fully restore hard disk contents when the machine is later reverted
7894 to a particular snapshot.
7895
7896 In the current implementation, multiple snapshot branches within one
7897 virtual machine are not allowed. Every machine has a single branch,
7898 and <link to="IConsole::takeSnapshot"/> operation adds a new
7899 snapshot to the top of that branch.
7900
7901 Existing snapshots can be discarded using
7902 <link to="IConsole::discardSnapshot"/>.
7903
7904 <h3>Current snapshot</h3>
7905
7906 Every virtual machine has a current snapshot, identified by
7907 <link to="IMachine::currentSnapshot"/>. This snapshot is used as
7908 a base for the <i>current machine state</i> (see below), to the effect
7909 that all normal hard disks of the machine and its execution
7910 state are based on this snapshot.
7911
7912 In the current implementation, the current snapshot is always the
7913 last taken snapshot (i.e. the head snapshot on the branch) and it
7914 cannot be changed.
7915
7916 The current snapshot is <tt>null</tt> if the machine doesn't have
7917 snapshots at all; in this case the current machine state is just
7918 current settings of this machine plus its current execution state.
7919
7920 <h3>Current machine state</h3>
7921
7922 The current machine state is what represented by IMachine instances got
7923 directly from IVirtualBox
7924 using <link
7925 to="IVirtualBox::getMachine">getMachine()</link>, <link
7926 to="IVirtualBox::findMachine">findMachine()</link>, etc. (as opposed
7927 to instances returned by <link to="ISnapshot::machine"/>). This state
7928 is always used when the machine is <link to="IConsole::powerUp"> powered
7929 on</link>.
7930
7931 The current machine state also includes the current execution state.
7932 If the machine is being currently executed
7933 (<link to="IMachine::state"/> is <link to="MachineState_Running"/>
7934 and above), its execution state is just what's happening now.
7935 If it is powered off (<link to="MachineState_PoweredOff"/> or
7936 <link to="MachineState_Aborted"/>), it has a zero execution state.
7937 If the machine is saved (<link to="MachineState_Saved"/>), its
7938 execution state is what saved in the execution state file
7939 (<link to="IMachine::stateFilePath"/>).
7940
7941 If the machine is in the saved state, then, next time it is powered
7942 on, its execution state will be fully restored from the saved state
7943 file and the execution will continue from the point where the state
7944 was saved.
7945
7946 Similarly to snapshots, the current machine state can be discarded
7947 using <link to="IConsole::discardCurrentState"/>.
7948
7949 <h3>Taking and discarding snapshots</h3>
7950
7951 The table below briefly explains the meaning of every snapshot
7952 operation:
7953
7954 <table>
7955 <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
7956
7957 <tr><td><link to="IConsole::takeSnapshot"/></td>
7958
7959 <td>Save the current state of the virtual machine, including all
7960 settings, contents of normal hard disks and the current modifications
7961 to immutable hard disks (for online snapshots)</td>
7962
7963 <td>The current state is not changed (the machine will continue
7964 execution if it is being executed when the snapshot is
7965 taken)</td></tr>
7966
7967 <tr><td><link to="IConsole::discardSnapshot"/></td>
7968
7969 <td>Forget the state of the virtual machine stored in the snapshot:
7970 dismiss all saved settings and delete the saved execution state (for
7971 online snapshots)</td>
7972
7973 <td>Other snapshots (including child snapshots, if any) and the
7974 current state are not directly affected</td></tr>
7975
7976 <tr><td><link to="IConsole::discardCurrentState"/></td>
7977
7978 <td>Restore the current state of the virtual machine from the state
7979 stored in the current snapshot, including all settings and hard disk
7980 contents</td>
7981
7982 <td>The current state of the machine existed prior to this operation
7983 is lost</td></tr>
7984
7985 <tr><td><link to="IConsole::discardCurrentSnapshotAndState"/></td>
7986
7987 <td>Completely revert the virtual machine to the state it was in
7988 before the current snapshot has been taken</td>
7989
7990 <td>The current state, as well as the current snapshot, are
7991 lost</td></tr>
7992
7993 </table>
7994
7995 </desc>
7996
7997 <attribute name="id" type="uuid" readonly="yes">
7998 <desc>UUID of the snapshot.</desc>
7999 </attribute>
8000
8001 <attribute name="name" type="wstring">
8002 <desc>Short name of the snapshot.</desc>
8003 </attribute>
8004
8005 <attribute name="description" type="wstring">
8006 <desc>Optional description of the snapshot.</desc>
8007 </attribute>
8008
8009 <attribute name="timeStamp" type="long long" readonly="yes">
8010 <desc>
8011 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
8012 </desc>
8013 </attribute>
8014
8015 <attribute name="online" type="boolean" readonly="yes">
8016 <desc>
8017 <tt>true</tt> if this snapshot is an online snapshot and
8018 <tt>false</tt> otherwise.
8019
8020 <note>
8021 When this attribute is <tt>true</tt>, the
8022 <link to="IMachine::stateFilePath"/> attribute of the
8023 <link to="#machine"/> object associated with this snapshot
8024 will point to the saved state file. Otherwise, it will be
8025 <tt>null</tt>.
8026 </note>
8027 </desc>
8028 </attribute>
8029
8030 <attribute name="machine" type="IMachine" readonly="yes">
8031 <desc>
8032 Virtual machine this snapshot is taken on. This object
8033 stores all settings the machine had when taking this snapshot.
8034 <note>
8035 The returned machine object is immutable, i.e. no
8036 any settings can be changed.
8037 </note>
8038 </desc>
8039 </attribute>
8040
8041 <attribute name="parent" type="ISnapshot" readonly="yes">
8042 <desc>
8043 Parent snapshot (a snapshot this one is based on).
8044 <note>
8045 It's not an error to read this attribute on a snapshot
8046 that doesn't have a parent -- a null object will be
8047 returned to indicate this.
8048 </note>
8049 </desc>
8050 </attribute>
8051
8052 <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
8053 <desc>
8054 Child snapshots (all snapshots having this one as a parent).
8055 <note>
8056 In the current implementation, there can be only one
8057 child snapshot, or no children at all, meaning this is the
8058 last (head) snapshot.
8059 </note>
8060 </desc>
8061 </attribute>
8062
8063 </interface>
8064
8065
8066 <!--
8067 // IMedia
8068 /////////////////////////////////////////////////////////////////////////
8069 -->
8070
8071 <enum
8072 name="MediaState"
8073 uuid="8b86e03c-2f1c-412a-8fbd-326f62701200"
8074 >
8075 <desc>
8076 Virtual media state.
8077 <see>IMedia</see>
8078 </desc>
8079
8080 <const name="NotCreated" value="0">
8081 <desc>
8082 Associated media storage does not exist (either was not created yet or
8083 was deleted).
8084 </desc>
8085 </const>
8086 <const name="Created" value="1">
8087 <desc>
8088 Associated storage exists and accessible.
8089 </desc>
8090 </const>
8091 <const name="LockedRead" value="2">
8092 <desc>
8093 Media is locked for reading, no data modification is possible.
8094 </desc>
8095 </const>
8096 <const name="LockedWrite" value="3">
8097 <desc>
8098 Media is locked for writing, no concurrent data reading or modification
8099 is possible.
8100 </desc>
8101 </const>
8102 <const name="Inaccessible" value="4">
8103 <desc>
8104 Associated media storage is not accessible.
8105 </desc>
8106 </const>
8107 <const name="Creating" value="5">
8108 <desc>
8109 Associated media storage is being created.
8110 </desc>
8111 </const>
8112 <const name="Deleting" value="6">
8113 <desc>
8114 Associated media storage is being deleted.
8115 </desc>
8116 </const>
8117 </enum>
8118
8119 <interface
8120 name="IMedium" extends="$unknown"
8121 uuid="a7fb3bfb-c180-4274-bae4-7fbc89046e13"
8122 wsmap="managed"
8123 >
8124 <desc>
8125 The IMedium interface is a common interface for all objects representing
8126 virtual media such as hard disks, CD/DVD images and floppy images.
8127
8128 Each medium is associated with a storage unit (such as a file on the host
8129 computer or a network resource) that holds actual data. The location of
8130 the storage unit is represented by the #location attribute. The value of
8131 this attribute is media type dependent.
8132
8133 The exact media type may be determined by querying the appropriate
8134 interface such as:
8135 <ul>
8136 <li>IHardDisk (virtual hard disks)</li>
8137 <li>IDVDImage (standard CD/DVD ISO image files)</li>
8138 <li>IFloppyImage (raw floppy image files)</li>
8139 </ul>
8140
8141 Existing media are opened using the following methods, depending on the
8142 media type:
8143 <ul>
8144 <li><link to="IVirtualBox::openHardDisk"/></li>
8145 <li><link to="IVirtualBox::openDVDImage"/></li>
8146 <li><link to="IVirtualBox::openFloppyImage"/></li>
8147 </ul>
8148
8149 New hard disk media are created using the
8150 <link to="IVirtualBox::createHardDisk"/> method. CD/DVD and floppy
8151 images are created outside VirtualBox, usually by storing a copy
8152 of the real medium of the corresponding type in a regular file.
8153
8154 <h3>Known Media</h3>
8155
8156 When an existing medium gets opened for the first time, it gets
8157 automatically remembered by the given VirtualBox installation or, in other
8158 words, becomes a <i>known medium</i>. Known media are stored in the media
8159 registry transparently maintained by VirtualBox and stored in settings
8160 files so that this registry is preserved when VirtualBox is not running.
8161
8162 Newly created virtual hard disks get remembered only when the associated
8163 storage unit is actually created (see IHardDisk for more details).
8164
8165 All known media can be enumerated using
8166 <link to="IVirtualBox::hardDisks"/>,
8167 <link to="IVirtualBox::DVDImages"/> and
8168 <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
8169 quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
8170 and similar methods or by location using
8171 <link to="IVirtualBox::findHardDisk"/> and similar methods.
8172
8173 Only known media can be attached to virtual machines.
8174
8175 Removing known media from the media registry is performed when the given
8176 medium is closed using the <link to="#close"/> method or when its
8177 associated storage unit is deleted (only for hard disks).
8178
8179 <h3>Accessibility Checks</h3>
8180
8181 The given medium (with the created storage unit) is considered to be
8182 <i>accessible</i> when its storage unit can be read.
8183 Accessible media are indicated by the <link to="MediaState_Created"/>
8184 value of the <link to="#state"/> attribute. When the storage unit cannot
8185 be read (for example, because it is located on a disconnected network
8186 resource, or was accidentally deleted outside VirtualBox), the medium is
8187 considered to be <i>inaccessible</i> which is indicated by the
8188 <link to="MediaState_Inaccessible"/> state. The details about the reason
8189 of being inaccessible can be obtained using the
8190 <link to="#lastAccessError"/> attribute.
8191
8192 A new accessibility check is performed each time the <link to="#state"/>
8193 attribute is read. Please note that this check may take long time (several
8194 seconds or even minutes, depending on the storage unit location and
8195 format), and will block the calling thread until finished. For this
8196 reason, it is recommended to never read this attribute on the main UI
8197 thread to avoid making the UI unresponsive.
8198
8199 Note that when VirtualBox starts up (e.g. the VirtualBox object gets
8200 created for the first time), all known media are in the
8201 <link to="MediaState_Inaccessible"/> state but the value of the <link
8202 to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
8203 accessibility check is made on startup. This is done to make the
8204 VirtualBox object ready for serving requests as
8205 fast as possible and let the end-user application decide if it needs to
8206 check media accessibility right away or not.
8207 </desc>
8208
8209 <attribute name="id" type="uuid" readonly="yes">
8210 <desc>
8211 UUID of the medium. For a newly created medium, this value is a randomly
8212 generated UUID.
8213
8214 <note>
8215 For media in one of MediaState_NotCreated, MediaState_Creating or
8216 MediaState_Deleting states, the value of this property is undefined
8217 and will most likely be an empty UUID.
8218 </note>
8219 </desc>
8220 </attribute>
8221
8222 <attribute name="description" type="wstring">
8223 <desc>
8224 Optional description of the medium. For newly created media, the value
8225 of this attribute value is <tt>null</tt>.
8226
8227 Media types that don't support this attribute will return E_NOTIMPL in
8228 attempt to get or set this attribute's value.
8229
8230 <note>
8231 For some storage types, reading this attribute may return an outdated
8232 (last known) value when <link to="#state"/> is <link
8233 to="MediaState_Inaccessible"/> or <link
8234 to="MediaState_LockedWrite"/> because the value of this attribute is
8235 stored within the storage unit itself. Also note that changing the
8236 attribute value is not possible in such case, as well as when the
8237 medium is the <link to="MediaState_LockedRead"/> state.
8238 </note>
8239 </desc>
8240 </attribute>
8241
8242 <attribute name="state" type="MediaState" readonly="yes">
8243 <desc>
8244 Current media state. Inspect <link to="MediaState"/> values for details.
8245
8246 Reading this attribute may take a long time because an accessibility
8247 check of the storage unit is performed each time the attribute is read.
8248 This check may cause a significant delay if the storage unit of the
8249 given medium is, for example, a file located on a network share which is
8250 not currently accessible due to connectivity problems -- the call will
8251 not return until a timeout interval defined by the host OS for this
8252 operation expires.
8253
8254 If the last known state of the medium is <link to="MediaState_Created"/>
8255 and the accessibility check fails then the state would be set to
8256 <link to="MediaState_Inaccessible"/> and <link to="#lastAccessError"/>
8257 may be used to get more details about the failure. If the state of the
8258 medium is <link to="MediaState_LockedRead"/> or
8259 <link to="MediaState_LockedWrite"/> then it remains the same, and a
8260 non-null value of <link to="#lastAccessError"/> will indicate a failed
8261 accessibility check in this case.
8262
8263 Note that not all media states are applicable to all media types.
8264 For example, states <link to="MediaState_NotCreated"/>,
8265 <link to="MediaState_LockedWrite"/>, <link to="MediaState_Creating"/>,
8266 <link to="MediaState_Deleting"/> are meaningless for IDVDImage and
8267 IFloppyImage media.
8268 </desc>
8269 </attribute>
8270
8271 <attribute name="location" type="wstring">
8272 <desc>
8273 Location of the storage unit holding media data.
8274
8275 The format of the location string is media type specific. For media
8276 types using regular files in a host's file system, the location
8277 string is the full file name.
8278
8279 Some media types may support changing the storage unit location by
8280 simply changing the value of this property. If this operation is not
8281 supported, the implementation will return E_NOTIMPL in attempt to set
8282 this attribute's value.
8283
8284 When setting a value of the location attribute which is a regular file
8285 in the host's file system, the given file name may be either relative to
8286 the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
8287 absolute. Note that if the given location specification does not contain
8288 the file extension part then a proper default extension will be
8289 automatically appended by the implementation depending on the media type.
8290 </desc>
8291 </attribute>
8292
8293 <attribute name="name" type="wstring" readonly="yes">
8294 <desc>
8295 Name of the storage unit holding media data.
8296
8297 The returned string is a short version of the <link to="#location"/>
8298 attribute that is suitable for representing the medium in situations
8299 where the full location specification is too long (such as lists
8300 and comboboxes in GUI frontends). This string is also used by frontends
8301 to sort the media list alphabetically when needed.
8302
8303 For example, for locations that are regular files in the host's file
8304 system, the value of this attribute is just the file name (+ extension),
8305 without the path specification.
8306
8307 Note that as opposed to the <link to="#location"/> attribute, the name
8308 attribute will not necessary be unique for a list of media of the
8309 given type and format.
8310 </desc>
8311 </attribute>
8312
8313 <attribute name="size" type="unsigned long long" readonly="yes">
8314 <desc>
8315 Physical size of the storage unit used to hold media data (in bytes).
8316
8317 <note>
8318 For media whose <link to="#state"/> is <link
8319 to="MediaState_Inaccessible"/>, the value of this property is the
8320 last known size. For <link to="MediaState_NotCreated"/> media,
8321 the returned value is zero.
8322 </note>
8323 </desc>
8324 </attribute>
8325
8326 <attribute name="lastAccessError" type="wstring" readonly="yes">
8327 <desc>
8328 Text message that represents the result of the last accessibility
8329 check.
8330
8331 Accessibility checks are performed each time the <link to="#state"/>
8332 attribute is read. A @c null string is returned if the last
8333 accessibility check was successful. A non-null string indicates a
8334 failure and should normally describe a reason of the failure (for
8335 example, a file read error).
8336 </desc>
8337 </attribute>
8338
8339 <attribute name="machineIds" type="uuid" safearray="yes" readonly="yes">
8340 <desc>
8341 Array of UUIDs of all machines this medium is attached to.
8342
8343 A <tt>null</tt> array is returned if this medium is not attached to any
8344 machine or to any machine's snapshot.
8345
8346 <note>
8347 The returned array will include a machine even if this medium is not
8348 attached to that machine in the current state but attached to it in
8349 one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
8350 details.
8351 </note>
8352 </desc>
8353 </attribute>
8354
8355 <method name="getSnapshotIds">
8356 <desc>
8357 Returns an array of UUIDs of all snapshots of the given machine where
8358 this medium is attached to.
8359
8360 If the medium is attached to the machine in the current state, then the
8361 first element in the array will always be the ID of the queried machine
8362 (i.e. the value equal to the @c machineId argument), followed by
8363 snapshot IDs (if any).
8364
8365 If the medium is not attached to the machine in the current state, then
8366 the array will contain only snapshot IDs.
8367
8368 The returned array may be <tt>null</tt> if this medium is not attached
8369 to the given machine at all, neither in the current state nor in one of
8370 the snapshots.
8371 </desc>
8372 <param name="machineId" type="uuid" dir="in">
8373 <desc>
8374 UUID of the machine to query.
8375 </desc>
8376 </param>
8377 <param name="snapshotIds" type="uuid" safearray="yes" dir="return">
8378 <desc>
8379 Array of snapshot UUIDs of the given machine using this medium.
8380 </desc>
8381 </param>
8382 </method>
8383
8384 <method name="lockRead">
8385 <desc>
8386 Locks this medium for reading.
8387
8388 The read lock is shared: many clients can simultaneously lock the
8389 same media for reading unless it is already locked for writing (see
8390 <link to="#lockWrite"/>) in which case an error is returned.
8391
8392 When the medium is locked for reading, it cannot be modified
8393 from within VirtualBox. This means that any method that changes
8394 the properties of this medium or contents of the storage unit
8395 will return an error (unless explicitly stated otherwise) and
8396 that an attempt to start a virtual machine that wants to modify
8397 the medium will also fail.
8398
8399 When the virtual machine is started up, it locks for reading all
8400 media it uses in read-only mode. If some media cannot be locked
8401 for reading, the startup procedure will fail.
8402
8403 The medium locked for reading must be unlocked using the <link
8404 to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
8405 can be nested and must be followed by the same number of paired
8406 <link to="#unlockRead"/> calls.
8407
8408 This method sets the media state to <link
8409 to="MediaState_LockedRead"/> on success. The state prior to
8410 this call must be <link to="MediaState_Created"/>, <link
8411 to="MediaState_Inaccessible"/> or <link
8412 to="MediaState_LockedRead"/>. As you can see, inaccessible
8413 media can be locked too. This is not an error; this method
8414 performs a logical lock that prevents modifications of this
8415 media through the VirtualBox API, not a physical lock of the
8416 underlying storage unit.
8417
8418 This method returns the current state of the medium
8419 <b>before</b> the operation.
8420
8421 <result name="VBOX_E_INVALID_OBJECT_STATE">
8422 Invalid media state (e.g. not created, locked, inaccessible,
8423 creating, deleting).
8424 </result>
8425
8426 </desc>
8427 <param name="state" type="MediaState" dir="return">
8428 <desc>
8429 State of the medium after the operation.
8430 </desc>
8431 </param>
8432 </method>
8433
8434 <method name="unlockRead">
8435 <desc>
8436 Cancels the read lock previously set by <link to="#lockRead"/>.
8437
8438 For both, success and failure, this method returns the current state
8439 of the medium <b>after</b> the operation.
8440
8441 See <link to="#lockRead"/> for more details.
8442
8443 <result name="VBOX_E_INVALID_OBJECT_STATE">
8444 Medium not locked for reading.
8445 </result>
8446
8447 </desc>
8448 <param name="state" type="MediaState" dir="return">
8449 <desc>
8450 State of the medium after the operation.
8451 </desc>
8452 </param>
8453 </method>
8454
8455 <method name="lockWrite">
8456 <desc>
8457 Locks this medium for writing.
8458
8459 The write lock, as opposed to <link to="#lockRead"/>, is
8460 exclusive: there may be only one client holding a write lock
8461 and there may be no read locks while the write lock is held.
8462
8463 When the medium is locked for writing, it cannot be modified
8464 from within VirtualBox and it is not guaranteed that the values
8465 of its properties are up-to-date. Any method that changes the
8466 properties of this medium or contents of the storage unit will
8467 return an error (unless explicitly stated otherwise) and an
8468 attempt to start a virtual machine wanting to modify or to
8469 read the medium will fail.
8470
8471 When the virtual machine is started up, it locks for writing all
8472 media it uses to write data to. If any medium could not be locked
8473 for writing, the startup procedure will fail.
8474
8475 The medium locked for writing must be unlocked using the <link
8476 to="#unlockWrite"/> method. Calls to <link to="#lockWrite"/>
8477 can <b>not</b> be nested and must be followed by a<link
8478 to="#unlockWrite"/> call before the next lockWrite call.
8479
8480 This method sets the media state to <link
8481 to="MediaState_LockedWrite"/> on success. The state prior to
8482 this call must be <link to="MediaState_Created"/> or <link
8483 to="MediaState_Inaccessible"/>. As you can see, inaccessible
8484 media can be locked too. This is not an error; this method
8485 performs a logical lock preventing modifications of this
8486 media through the VirtualBox API, not a physical lock of the
8487 underlying storage unit.
8488
8489 For both, success and failure, this method returns the current
8490 state of the medium <b>before</b> the operation.
8491
8492 <result name="VBOX_E_INVALID_OBJECT_STATE">
8493 Invalid media state (e.g. not created, locked, inaccessible,
8494 creating, deleting).
8495 </result>
8496
8497 </desc>
8498 <param name="state" type="MediaState" dir="return">
8499 <desc>
8500 State of the medium after the operation.
8501 </desc>
8502 </param>
8503 </method>
8504
8505 <method name="unlockWrite">
8506 <desc>
8507 Cancels the write lock previously set by <link to="#lockWrite"/>.
8508
8509 For both, success and failure, this method returns the current
8510 state of the medium <b>after</b> the operation.
8511
8512 See <link to="#lockWrite"/> for more details.
8513
8514 <result name="VBOX_E_INVALID_OBJECT_STATE">
8515 Medium not locked for writing.
8516 </result>
8517
8518 </desc>
8519 <param name="state" type="MediaState" dir="return">
8520 <desc>
8521 State of the medium after the operation.
8522 </desc>
8523 </param>
8524 </method>
8525
8526 <method name="close">
8527 <desc>
8528 Closes this medium.
8529
8530 The hard disk must not be attached to any known virtual machine
8531 and must not have any known child hard disks, otherwise the
8532 operation will fail.
8533
8534 When the hard disk is successfully closed, it gets removed from
8535 the list of remembered hard disks, but its storage unit is not
8536 deleted. In particular, this means that this hard disk can be
8537 later opened again using the <link
8538 to="IVirtualBox::openHardDisk"/> call.
8539
8540 Note that after this method successfully returns, the given hard
8541 disk object becomes uninitialized. This means that any attempt
8542 to call any of its methods or attributes will fail with the
8543 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
8544
8545 <result name="VBOX_E_INVALID_OBJECT_STATE">
8546 Invalid media state (other than not created, created or
8547 inaccessible).
8548 </result>
8549 <result name="VBOX_E_OBJECT_IN_USE">
8550 Medium attached to virtual machine.
8551 </result>
8552 <result name="VBOX_E_FILE_ERROR">
8553 Settings file not accessible.
8554 </result>
8555 <result name="VBOX_E_XML_ERROR">
8556 Could not parse the settings file.
8557 </result>
8558
8559 </desc>
8560 </method>
8561
8562 </interface>
8563
8564
8565 <!--
8566 // IHardDisk
8567 /////////////////////////////////////////////////////////////////////////
8568 -->
8569
8570 <enum
8571 name="HardDiskType"
8572 uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
8573 >
8574 <desc>
8575 Virtual hard disk type.
8576 <see>IHardDisk</see>
8577 </desc>
8578
8579 <const name="Normal" value="0">
8580 <desc>
8581 Normal hard disk (attached directly or indirectly, preserved
8582 when taking snapshots).
8583 </desc>
8584 </const>
8585 <const name="Immutable" value="1">
8586 <desc>
8587 Immutable hard disk (attached indirectly, changes are wiped out
8588 after powering off the virtual machine).
8589 </desc>
8590 </const>
8591 <const name="Writethrough" value="2">
8592 <desc>
8593 Write through hard disk (attached directly, ignored when
8594 taking snapshots).
8595 </desc>
8596 </const>
8597 </enum>
8598
8599 <enum
8600 name="HardDiskVariant"
8601 uuid="99334b63-7ed0-4f61-8a7e-7ec3e20dd912"
8602 >
8603 <desc>
8604 Virtual hard disk image variant. More than one flag may be set.
8605 <see>IHardDisk</see>
8606 </desc>
8607
8608 <const name="Standard" value="0">
8609 <desc>
8610 No particular variant requested, results in using the backend default.
8611 </desc>
8612 </const>
8613 <const name="VmdkSplit2G" value="0x01">
8614 <desc>
8615 VMDK image split in chunks of less than 2GByte.
8616 </desc>
8617 </const>
8618 <const name="VmdkStreamOptimized" value="0x04">
8619 <desc>
8620 VMDK streamOptimized image. Special import/export format which is
8621 read-only/append-only.
8622 </desc>
8623 </const>
8624 <const name="Fixed" value="0x1000">
8625 <desc>
8626 Fixed image. Only allowed for base images.
8627 </desc>
8628 </const>
8629 <const name="Diff" value="0x2000">
8630 <desc>
8631 Fixed image. Only allowed for base images.
8632 </desc>
8633 </const>
8634 </enum>
8635
8636 <interface
8637 name="IHardDiskAttachment" extends="$unknown"
8638 uuid="b1dd04bb-93c0-4ad3-a9cf-82316e595836"
8639 wsmap="struct"
8640 >
8641 <desc>
8642 The IHardDiskAttachment interface represents a hard disk attachment of a
8643 virtual machine.
8644
8645 Every hard disk attachment specifies a slot of the virtual hard disk
8646 controller and a virtual hard disk attached to this slot.
8647
8648 The array of hard disk attachments is returned by
8649 <link to="IMachine::hardDiskAttachments"/>.
8650 </desc>
8651 <attribute name="hardDisk" type="IHardDisk" readonly="yes">
8652 <desc>Hard disk object associated with this attachment.</desc>
8653 </attribute>
8654
8655 <attribute name="controller" type="wstring" readonly="yes">
8656 <desc>Interface bus of this attachment.</desc>
8657 </attribute>
8658
8659 <attribute name="port" type="long" readonly="yes">
8660 <desc>Port number of this attachment.</desc>
8661 </attribute>
8662
8663 <attribute name="device" type="long" readonly="yes">
8664 <desc>Device slot number of this attachment.</desc>
8665 </attribute>
8666
8667 </interface>
8668
8669 <interface
8670 name="IHardDisk" extends="IMedium"
8671 uuid="3498d065-dee6-48bf-bcc5-47018fee4f42"
8672 wsmap="managed"
8673 >
8674 <desc>
8675 The IHardDisk interface represents a virtual hard disk drive
8676 used by a virtual machine. This is a subclass of <link to="IMedium" />; see remarks there.
8677
8678 Virtual hard disk objects virtualize the hard disk hardware and look like
8679 regular hard disks for the guest OS running inside the virtual machine.
8680
8681 <h3>Hard Disk Types</h3>
8682
8683 There are three types of hard disks:
8684 <link to="HardDiskType_Normal">Normal</link>,
8685 <link to="HardDiskType_Immutable">Immutable</link> and
8686 <link to="HardDiskType_Writethrough">Writethrough</link>. The type of the
8687 hard disk defines how the hard disk is attached to a virtual machine and
8688 what happens when a <link to="ISnapshot">snapshot</link> of the virtual
8689 machine with the attached hard disk is taken. The type of the hard disk is
8690 defined by the <link to="#type"/> attribute.
8691
8692 All hard disks can be also divided in two big groups: <i>base</i> hard
8693 disks and <i>differencing</i> hard disks. A base hard disk contains all
8694 sectors of the hard disk data in its storage unit and therefore can be
8695 used independently. On the contrary, a differencing hard disk contains
8696 only some part of the hard disk data (a subset of sectors) and needs
8697 another hard disk to get access to the missing sectors of data. This
8698 another hard disk is called a <i>parent</i> hard disk and defines a hard
8699 disk to which this differencing hard disk is known to be <i>linked to</i>.
8700 The parent hard disk may be itself a differencing hard disk. This
8701 way, differencing hard disks form a linked hard disk chain. This chain
8702 always ends with the base hard disk which is sometimes referred to as the
8703 root hard disk of this chain. Note that several differencing hard disks
8704 may be linked to the same parent hard disk. This way, all known hard disks
8705 form a hard disk tree which is based on their parent-child relationship.
8706
8707 Differencing hard disks can be distinguished from base hard disks by
8708 querying the <link to="#parent"/> attribute: base hard disks do not have
8709 parents they would depend on, so the value of this attribute is always
8710 <tt>null</tt> for them. Using this attribute, it is possible to walk up
8711 the hard disk tree (from the child hard disk to its parent). It is also
8712 possible to walk down the tree using the <link to="#children"/>
8713 attribute.
8714
8715 Note that the type of all differencing hard disks is
8716 <link to="HardDiskType_Normal">Normal</link>; all other values are
8717 meaningless for them. Base hard disks may be of any type.
8718
8719 <h3>Creating Hard Disks</h3>
8720
8721 New base hard disks are created using
8722 <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
8723 opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
8724 disks are usually implicitly created by VirtualBox when needed but may
8725 also be created explicitly using <link to="#createDiffStorage"/>.
8726
8727 After the hard disk is successfully created (including the storage unit)
8728 or opened, it becomes a known hard disk (remembered in the internal media
8729 registry). Known hard disks can be attached to a virtual machine, accessed
8730 through <link to="IVirtualBox::getHardDisk"/> and
8731 <link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
8732 <link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
8733
8734 The following methods, besides <link to="IMedium::close"/>,
8735 automatically remove the hard disk from the media registry:
8736 <ul>
8737 <li><link to="#deleteStorage"/></li>
8738 <li><link to="#mergeTo"/></li>
8739 </ul>
8740
8741 If the storage unit of the hard disk is a regular file in the host's
8742 file system then the rules stated in the description of the
8743 <link to="IMedium::location"/> attribute apply when setting its value. In
8744 addition, a plain file name without any path may be given, in which case
8745 the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
8746 folder</link> will be prepended to it.
8747
8748 <h4>Automatic composition of the file name part</h4>
8749
8750 Another extension to the <link to="IMedium::location"/> attribute is that
8751 there is a possibility to cause VirtualBox to compose a unique value for
8752 the file name part of the location using the UUID of the hard disk. This
8753 applies only to hard disks in <link to="MediaState_NotCreated"/> state,
8754 e.g. before the storage unit is created, and works as follows. You set the
8755 value of the <link to="IMedium::location"/> attribute to a location
8756 specification which only contains the path specification but not the file
8757 name part and ends with either a forward slash or a backslash character.
8758 In response, VirtualBox will generate a new UUID for the hard disk and
8759 compose the file name using the following pattern:
8760 <pre>
8761 &lt;path&gt;/{&lt;uuid&gt;}.&lt;ext&gt;
8762 </pre>
8763 where <tt>&lt;path&gt;</tt> is the supplied path specification,
8764 <tt>&lt;uuid&gt;</tt> is the newly generated UUID and <tt>&lt;ext&gt;</tt>
8765 is the default extension for the storage format of this hard disk. After
8766 that, you may call any of the methods that create a new hard disk storage
8767 unit and they will use the generated UUID and file name.
8768
8769 <h3>Attaching Hard Disks</h3>
8770
8771 Hard disks are attached to virtual machines using the
8772 <link to="IMachine::attachHardDisk"/> method and detached using the
8773 <link to="IMachine::detachHardDisk"/> method. Depending on their
8774 <link to="#type"/>, hard disks are attached either
8775 <i>directly</i> or <i>indirectly</i>.
8776
8777 When a hard disk is being attached directly, it is associated with the
8778 virtual machine and used for hard disk operations when the machine is
8779 running. When a hard disk is being attached indirectly, a new differencing
8780 hard disk linked to it is implicitly created and this differencing hard
8781 disk is associated with the machine and used for hard disk operations.
8782 This also means that if <link to="IMachine::attachHardDisk"/> performs
8783 a direct attachment then the same hard disk will be returned in response
8784 to the subsequent <link to="IMachine::getHardDisk"/> call; however if
8785 an indirect attachment is performed then
8786 <link to="IMachine::getHardDisk"/> will return the implicitly created
8787 differencing hard disk, not the original one passed to <link
8788 to="IMachine::attachHardDisk"/>. The following table shows the
8789 dependency of the attachment type on the hard disk type:
8790
8791 <table>
8792 <tr>
8793 <th>Hard Disk Type</th>
8794 <th>Direct or Indirect?</th>
8795 </tr>
8796 <tr>
8797 <td>Normal (Base)</td>
8798 <td>
8799 Normal base hard disks that do not have children (i.e. differencing
8800 hard disks linked to them) and that are not already attached to
8801 virtual machines in snapshots are attached <b>directly</b>.
8802 Otherwise, they are attached <b>indirectly</b> because having
8803 dependent children or being part of the snapshot makes it impossible
8804 to modify hard disk contents without breaking the integrity of the
8805 dependent party. The <link to="#readOnly"/> attribute allows to
8806 quickly determine the kind of the attachment for the given hard
8807 disk. Note that if a normal base hard disk is to be indirectly
8808 attached to a virtual machine with snapshots then a special
8809 procedure called <i>smart attachment</i> is performed (see below).
8810 </td>
8811 </tr>
8812 <tr>
8813 <td>Normal (Differencing)</td>
8814 <td>
8815 Differencing hard disks are like normal base hard disks: attached
8816 <b>directly</b> if they do not have children and are not attached to
8817 virtual machines in snapshots, and <b>indirectly</b> otherwise. Note
8818 that the smart attachment procedure is never performed for
8819 differencing hard disks.
8820 </td>
8821 </tr>
8822 <tr>
8823 <td>Immutable</td>
8824 <td>
8825 Immutable hard disks are always attached <b>indirectly</b> because
8826 they are designed to be non-writable. If an immutable hard disk is
8827 attached to a virtual machine with snapshots then a special
8828 procedure called smart attachment is performed (see below).
8829 </td>
8830 </tr>
8831 <tr>
8832 <td>Writethrough</td>
8833 <td>
8834 Writethrough hard disks are always attached <b>directly</b>, also as
8835 designed. This also means that writethrough hard disks cannot have
8836 other hard disks linked to them at all.
8837 </td>
8838 </tr>
8839 </table>
8840
8841 Note that the same hard disk, regardless of its type, may be attached to
8842 more than one virtual machine at a time. In this case, the machine that is
8843 started first gains exclusive access to the hard disk and attempts to
8844 start other machines having this hard disk attached will fail until the
8845 first machine is powered down.
8846
8847 Detaching hard disks is performed in a <i>deferred</i> fashion. This means
8848 that the given hard disk remains associated with the given machine after a
8849 successful <link to="IMachine::detachHardDisk"/> call until
8850 <link to="IMachine::saveSettings"/> is called to save all changes to
8851 machine settings to disk. This deferring is necessary to guarantee that
8852 the hard disk configuration may be restored at any time by a call to
8853 <link to="IMachine::discardSettings"/> before the settings
8854 are saved (committed).
8855
8856 Note that if <link to="IMachine::discardSettings"/> is called after
8857 indirectly attaching some hard disks to the machine but before a call to
8858 <link to="IMachine::saveSettings"/> is made, it will implicitly delete
8859 all differencing hard disks implicitly created by
8860 <link to="IMachine::attachHardDisk"/> for these indirect attachments.
8861 Such implicitly created hard disks will also be immediately deleted when
8862 detached explicitly using the <link to="IMachine::detachHardDisk"/>
8863 call if it is made before <link to="IMachine::saveSettings"/>. This
8864 implicit deletion is safe because newly created differencing hard
8865 disks do not contain any user data.
8866
8867 However, keep in mind that detaching differencing hard disks that were
8868 implicitly created by <link to="IMachine::attachHardDisk"/>
8869 before the last <link to="IMachine::saveSettings"/> call will
8870 <b>not</b> implicitly delete them as they may already contain some data
8871 (for example, as a result of virtual machine execution). If these hard
8872 disks are no more necessary, the caller can always delete them explicitly
8873 using <link to="#deleteStorage"/> after they are actually de-associated
8874 from this machine by the <link to="IMachine::saveSettings"/> call.
8875
8876 <h3>Smart Attachment</h3>
8877
8878 When normal base or immutable hard disks are indirectly attached to a
8879 virtual machine then some additional steps are performed to make sure the
8880 virtual machine will have the most recent "view" of the hard disk being
8881 attached. These steps include walking through the machine's snapshots
8882 starting from the current one and going through ancestors up to the first
8883 snapshot. Hard disks attached to the virtual machine in all
8884 of the encountered snapshots are checked whether they are descendants of
8885 the given normal base or immutable hard disk. The first found child (which
8886 is the differencing hard disk) will be used instead of the normal base or
8887 immutable hard disk as a parent for creating a new differencing hard disk
8888 that will be actually attached to the machine. And only if no descendants
8889 are found or if the virtual machine does not have any snapshots then the
8890 normal base or immutable hard disk will be used itself as a parent for
8891 this differencing hard disk.
8892
8893 It is easier to explain what smart attachment does using the
8894 following example:
8895 <pre>
8896BEFORE attaching B.vdi: AFTER attaching B.vdi:
8897
8898Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
8899 Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
8900 Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
8901 Snapshot 4 (none) Snapshot 4 (none)
8902 CurState (none) CurState (D3->D2.vdi)
8903
8904 NOT
8905 ...
8906 CurState (D3->B.vdi)
8907 </pre>
8908 The first column is the virtual machine configuration before the base hard
8909 disk <tt>B.vdi</tt> is attached, the second column shows the machine after
8910 this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
8911 mean that the hard disk that is actually attached to the machine is a
8912 differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
8913 another hard disk, <tt>B.vdi</tt>.
8914
8915 As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
8916 from the machine before taking Snapshot 4. Later, after Snapshot 4 was
8917 taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
8918 dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
8919 it cannot be attached directly and needs an indirect attachment (i.e.
8920 implicit creation of a new differencing hard disk). Due to the smart
8921 attachment procedure, the new differencing hard disk
8922 (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
8923 <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
8924 <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
8925 machine.
8926
8927 Note that if there is more than one descendant hard disk of the given base
8928 hard disk found in a snapshot, and there is an exact device, channel and
8929 bus match, then this exact match will be used. Otherwise, the youngest
8930 descendant will be picked up.
8931
8932 There is one more important aspect of the smart attachment procedure which
8933 is not related to snapshots at all. Before walking through the snapshots
8934 as described above, the backup copy of the current list of hard disk
8935 attachment is searched for descendants. This backup copy is created when
8936 the hard disk configuration is changed for the first time after the last
8937 <link to="IMachine::saveSettings"/> call and used by
8938 <link to="IMachine::discardSettings"/> to undo the recent hard disk
8939 changes. When such a descendant is found in this backup copy, it will be
8940 simply re-attached back, without creating a new differencing hard disk for
8941 it. This optimization is necessary to make it possible to re-attach the
8942 base or immutable hard disk to a different bus, channel or device slot
8943 without losing the contents of the differencing hard disk actually
8944 attached to the machine in place of it.
8945 </desc>
8946
8947 <attribute name="format" type="wstring" readonly="yes">
8948 <desc>
8949 Storage format of this hard disk.
8950
8951 The value of this attribute is a string that specifies a backend used to
8952 store hard disk data. The storage format is defined when you create a
8953 new hard disk or automatically detected when you open an existing hard
8954 disk medium, and cannot be changed later.
8955
8956 The list of all storage formats supported by this VirtualBox
8957 installation can be obtained using
8958 <link to="ISystemProperties::hardDiskFormats"/>.
8959 </desc>
8960 </attribute>
8961
8962 <attribute name="type" type="HardDiskType">
8963 <desc>
8964 Type (role) of this hard disk.
8965
8966 The following constraints apply when changing the value of this
8967 attribute:
8968 <ul>
8969 <li>If a hard disk is attached to a virtual machine (either in the
8970 current state or in one of the snapshots), its type cannot be
8971 changed.
8972 </li>
8973 <li>As long as the hard disk has children, its type cannot be set
8974 to <link to="HardDiskType_Writethrough"/>.
8975 </li>
8976 <li>The type of all differencing hard disks is
8977 <link to="HardDiskType_Normal"/> and cannot be changed.
8978 </li>
8979 </ul>
8980
8981 The type of a newly created or opened hard disk is set to
8982 <link to="HardDiskType_Normal"/>.
8983 </desc>
8984 </attribute>
8985
8986 <attribute name="parent" type="IHardDisk" readonly="yes">
8987 <desc>
8988 Parent of this hard disk (a hard disk this hard disk is directly based
8989 on).
8990
8991 Only differencing hard disks have parents. For base (non-differencing)
8992 hard disks, <tt>null</tt> is returned.
8993 </desc>
8994 </attribute>
8995
8996 <attribute name="children" type="IHardDisk" safearray="yes" readonly="yes">
8997 <desc>
8998 Children of this hard disk (all differencing hard disks directly based
8999 on this hard disk). A <tt>null</tt> array is returned if this hard disk
9000 does not have any children.
9001 </desc>
9002 </attribute>
9003
9004 <attribute name="root" type="IHardDisk" readonly="yes">
9005 <desc>
9006 Root hard disk of this hard disk.
9007
9008 If this is a differencing hard disk, its root hard disk is the base hard
9009 disk the given hard disk branch starts from. For all other types of hard
9010 disks, this property returns the hard disk object itself (i.e. the same
9011 object this property is read on).
9012 </desc>
9013 </attribute>
9014
9015 <attribute name="readOnly" type="boolean" readonly="yes">
9016 <desc>
9017 Returns <tt>true</tt> if this hard disk is read-only and <tt>false</tt>
9018 otherwise.
9019
9020 A hard disk is considered to be read-only when its contents cannot be
9021 modified without breaking the integrity of other parties that depend on
9022 this hard disk such as its child hard disks or snapshots of virtual
9023 machines where this hard disk is attached to these machines. If there
9024 are no children and no such snapshots then there is no dependency and
9025 the hard disk is not read-only.
9026
9027 The value of this attribute can be used to determine the kind of the
9028 attachment that will take place when attaching this hard disk to a
9029 virtual machine. If the value is <tt>false</tt> then the hard disk will
9030 be attached directly. If the value is <tt>true</tt> then the hard disk
9031 will be attached indirectly by creating a new differencing child hard
9032 disk for that. See the interface description for more information.
9033
9034 Note that all <link to="HardDiskType_Immutable">Immutable</link> hard
9035 disks are always read-only while all
9036 <link to="HardDiskType_Writethrough">Writethrough</link> hard disks are
9037 always not.
9038
9039 <note>
9040 The read-only condition represented by this attribute is related to
9041 the hard disk type and usage, not to the current
9042 <link to="IMedium::state">media state</link> and not to the read-only
9043 state of the storage unit.
9044 </note>
9045 </desc>
9046 </attribute>
9047
9048 <attribute name="logicalSize" type="unsigned long long" readonly="yes">
9049 <desc>
9050 Logical size of this hard disk (in megabytes), as reported to the
9051 guest OS running inside the virtual machine this disk is
9052 attached to. The logical size is defined when the hard disk is created
9053 and cannot be changed later.
9054
9055 <note>
9056 Reading this property on a differencing hard disk will return the size
9057 of its <link to="#root"/> hard disk.
9058 </note>
9059 <note>
9060 For hard disks whose state is <link to="#state"/> is <link
9061 to="MediaState_Inaccessible"/>, the value of this property is the
9062 last known logical size. For <link to="MediaState_NotCreated"/> hard
9063 disks, the returned value is zero.
9064 </note>
9065 </desc>
9066 </attribute>
9067
9068 <attribute name="autoReset" type="boolean">
9069 <desc>
9070 Whether this differencing hard disk will be automatically reset each
9071 time a virtual machine it is attached to is powered up.
9072
9073 See <link to="#reset()"/> for more information about resetting
9074 differencing hard disks.
9075
9076 <note>
9077 Reading this property on a base (non-differencing) hard disk will
9078 always <tt>false</tt>. Changing the value of this property in this
9079 case is not supported.
9080 </note>
9081
9082 <result name="VBOX_E_NOT_SUPPORTED">
9083 This is not a differencing hard disk (when changing the attribute
9084 value).
9085 </result>
9086 </desc>
9087 </attribute>
9088
9089 <!-- storage methods -->
9090
9091 <method name="getProperty">
9092 <desc>
9093 Returns the value of the custom hard disk property with the given name.
9094
9095 The list of all properties supported by the given hard disk format can
9096 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9097
9098 Note that if this method returns a <tt>null</tt> @a value, the requested
9099 property is supported but currently not assigned any value.
9100
9101 <result name="VBOX_E_OBJECT_NOT_FOUND">
9102 Requested property does not exist (not supported by the format).
9103 </result>
9104 <result name="E_INVALIDARG">@a name is NULL or empty.</result>
9105 </desc>
9106 <param name="name" type="wstring" dir="in">
9107 <desc>Name of the property to get.</desc>
9108 </param>
9109 <param name="value" type="wstring" dir="return">
9110 <desc>Current property value.</desc>
9111 </param>
9112 </method>
9113
9114 <method name="setProperty">
9115 <desc>
9116 Sets the value of the custom hard disk property with the given name.
9117
9118 The list of all properties supported by the given hard disk format can
9119 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9120
9121 Note that setting the property value to <tt>null</tt> is equivalent to
9122 deleting the existing value. A default value (if it is defined for this
9123 property) will be used by the format backend in this case.
9124
9125 <result name="VBOX_E_OBJECT_NOT_FOUND">
9126 Requested property does not exist (not supported by the format).
9127 </result>
9128 <result name="E_INVALIDARG">@a name is NULL or empty.</result>
9129 </desc>
9130 <param name="name" type="wstring" dir="in">
9131 <desc>Name of the property to set.</desc>
9132 </param>
9133 <param name="value" type="wstring" dir="in">
9134 <desc>Property value to set.</desc>
9135 </param>
9136 </method>
9137
9138 <method name="getProperties">
9139 <desc>
9140 Returns values for a group of properties in one call.
9141
9142 The names of the properties to get are specified using the @a names
9143 argument which is a list of comma-separated property names or
9144 <tt>null</tt> if all properties are to be returned. Note that currently
9145 the value of this argument is ignored and the method always returns all
9146 existing properties.
9147
9148 The list of all properties supported by the given hard disk format can
9149 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9150
9151 The method returns two arrays, the array of property names corresponding
9152 to the @a names argument and the current values of these properties.
9153 Both arrays have the same number of elements with each elemend at the
9154 given index in the first array corresponds to an element at the same
9155 index in the second array.
9156
9157 Note that for properties that do not have assigned values,
9158 <tt>null</tt> is returned at the appropriate index in the
9159 @a returnValues array.
9160
9161 </desc>
9162 <param name="names" type="wstring" dir="in">
9163 <desc>
9164 Names of properties to get.
9165 </desc>
9166 </param>
9167 <param name="returnNames" type="wstring" safearray="yes" dir="out">
9168 <desc>Names of returned properties.</desc>
9169 </param>
9170 <param name="returnValues" type="wstring" safearray="yes" dir="return">
9171 <desc>Values of returned properties.</desc>
9172 </param>
9173 </method>
9174
9175 <method name="setProperties">
9176 <desc>
9177 Sets values for a group of properties in one call.
9178
9179 The names of the properties to set are passed in the @a names
9180 array along with the new values for them in the @a values array. Both
9181 arrays have the same number of elements with each elemend at the given
9182 index in the first array corresponding to an element at the same index
9183 in the second array.
9184
9185 If there is at least one property name in @a names that is not valid,
9186 the method will fail before changing the values of any other properties
9187 from the @a names array.
9188
9189 Using this method over <link to="#setProperty"/> is preferred if you
9190 need to set several properties at once since it will result into less
9191 IPC calls.
9192
9193 The list of all properties supported by the given hard disk format can
9194 be obtained with <link to="IHardDiskFormat::describeProperties"/>.
9195
9196 Note that setting the property value to <tt>null</tt> is equivalent to
9197 deleting the existing value. A default value (if it is defined for this
9198 property) will be used by the format backend in this case.
9199 </desc>
9200 <param name="names" type="wstring" safearray="yes" dir="in">
9201 <desc>Names of properties to set.</desc>
9202 </param>
9203 <param name="values" type="wstring" safearray="yes" dir="in">
9204 <desc>Values of properties to set.</desc>
9205 </param>
9206 </method>
9207
9208 <!-- storage methods -->
9209
9210 <method name="createBaseStorage">
9211 <desc>
9212 Starts creating a hard disk storage unit (fixed/dynamic, according
9213 to the variant flags) in in the background. The previous storage unit
9214 created for this object, if any, must first be deleted using
9215 <link to="#deleteStorage"/>, otherwise the operation will fail.
9216
9217 Before the operation starts, the hard disk is placed in
9218 <link to="MediaState_Creating"/> state. If the create operation
9219 fails, the media will be placed back in <link to="MediaState_NotCreated"/>
9220 state.
9221
9222 After the returned progress object reports that the operation has
9223 successfully completed, the media state will be set to <link
9224 to="MediaState_Created"/>, the hard disk will be remembered by this
9225 VirtualBox installation and may be attached to virtual machines.
9226
9227 <result name="VBOX_E_NOT_SUPPORTED">
9228 The variant of storage creation operation is not supported. See <link
9229 to="IHardDiskFormat::capabilities"/>.
9230 </result>
9231 </desc>
9232 <param name="logicalSize" type="unsigned long long" dir="in">
9233 <desc>Maximum logical size of the hard disk in megabytes.</desc>
9234 </param>
9235 <param name="variant" type="HardDiskVariant" dir="in">
9236 <desc>Exact image variant which should be created.</desc>
9237 </param>
9238 <param name="progress" type="IProgress" dir="return">
9239 <desc>Progress object to track the operation completion.</desc>
9240 </param>
9241 </method>
9242
9243 <method name="deleteStorage">
9244 <desc>
9245 Starts deleting the storage unit of this hard disk.
9246
9247 The hard disk must not be attached to any known virtual machine and must
9248 not have any known child hard disks, otherwise the operation will fail.
9249 It will also fail if there is no storage unit to delete or if deletion
9250 is already in progress, or if the hard disk is being in use (locked for
9251 read or for write) or inaccessible. Therefore, the only valid state for
9252 this operation to succeed is <link to="MediaState_Created"/>.
9253
9254 Before the operation starts, the hard disk is placed to
9255 <link to="MediaState_Deleting"/> state and gets removed from the list
9256 of remembered hard disks (media registry). If the delete operation
9257 fails, the media will be remembered again and placed back to
9258 <link to="MediaState_Created"/> state.
9259
9260 After the returned progress object reports that the operation is
9261 complete, the media state will be set to
9262 <link to="MediaState_NotCreated"/> and you will be able to use one of
9263 the storage creation methods to create it again.
9264
9265 <see>#close()</see>
9266
9267 <result name="VBOX_E_OBJECT_IN_USE">
9268 Hard disk is attached to a virtual machine.
9269 </result>
9270 <result name="VBOX_E_NOT_SUPPORTED">
9271 Storage deletion is not allowed because neither of storage creation
9272 operations are supported. See
9273 <link to="IHardDiskFormat::capabilities"/>.
9274 </result>
9275
9276 <note>
9277 If the deletion operation fails, it is not guaranteed that the storage
9278 unit still exists. You may check the <link to="IMedium::state"/> value
9279 to answer this question.
9280 </note>
9281 </desc>
9282 <param name="progress" type="IProgress" dir="return">
9283 <desc>Progress object to track the operation completion.</desc>
9284 </param>
9285 </method>
9286
9287 <!-- diff methods -->
9288
9289 <method name="createDiffStorage">
9290 <desc>
9291 Starts creating an empty differencing storage unit based on this hard
9292 disk in the format and at the location defined by the @a target
9293 argument.
9294
9295 The target hard disk must be in <link to="MediaState_NotCreated"/>
9296 state (i.e. must not have an existing storage unit). Upon successful
9297 completion, this operation will set the type of the target hard disk to
9298 <link to="HardDiskType_Normal"/> and create a storage unit necessary to
9299 represent the differencing hard disk data in the given format (according
9300 to the storage format of the target object).
9301
9302 After the returned progress object reports that the operation is
9303 successfully complete, the target hard disk gets remembered by this
9304 VirtualBox installation and may be attached to virtual machines.
9305
9306 <note>
9307 The hard disk will be set to <link to="MediaState_LockedRead"/>
9308 state for the duration of this operation.
9309 </note>
9310 <result name="VBOX_E_OBJECT_IN_USE">
9311 Hard disk not in NotCreated state.
9312 </result>
9313 </desc>
9314 <param name="target" type="IHardDisk" dir="in">
9315 <desc>Target hard disk.</desc>
9316 </param>
9317 <param name="variant" type="HardDiskVariant" dir="in">
9318 <desc>Exact image variant which should be created.</desc>
9319 </param>
9320 <param name="progress" type="IProgress" dir="return">
9321 <desc>Progress object to track the operation completion.</desc>
9322 </param>
9323 </method>
9324
9325 <method name="mergeTo">
9326 <desc>
9327 Starts merging the contents of this hard disk and all intermediate
9328 differencing hard disks in the chain to the given target hard disk.
9329
9330 The target hard disk must be either a descendant of this hard disk or
9331 its ancestor (otherwise this method will immediately return a failure).
9332 It follows that there are two logical directions of the merge operation:
9333 from ancestor to descendant (<i>forward merge</i>) and from descendant to
9334 ancestor (<i>backward merge</i>). Let us consider the following hard disk
9335 chain:
9336
9337 <pre>Base &lt;- Diff_1 &lt;- Diff_2</pre>
9338
9339 Here, calling this method on the <tt>Base</tt> hard disk object with
9340 <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
9341 <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
9342 merge. Note that in both cases the contents of the resulting hard disk
9343 will be the same, the only difference is the hard disk object that takes
9344 the result of the merge operation. In case of the forward merge in the
9345 above example, the result will be written to <tt>Diff_2</tt>; in case of
9346 the backward merge, the result will be written to <tt>Base</tt>. In
9347 other words, the result of the operation is always stored in the target
9348 hard disk.
9349
9350 Upon successful operation completion, the storage units of all hard
9351 disks in the chain between this (source) hard disk and the target hard
9352 disk, including the source hard disk itself, will be automatically
9353 deleted and the relevant hard disk objects (including this hard disk)
9354 will become uninitialized. This means that any attempt to call any of
9355 their methods or attributes will fail with the
9356 <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
9357 example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
9358 delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
9359 disks. Note that <tt>Diff_2</tt> in this case will become a base hard
9360 disk itself since it will no longer be based on any other hard disk.
9361
9362 Considering the above, all of the following conditions must be met in
9363 order for the merge operation to succeed:
9364 <ul>
9365 <li>
9366 Neither this (source) hard disk nor any intermediate
9367 differencing hard disk in the chain between it and the target
9368 hard disk is attached to any virtual machine.
9369 </li>
9370 <li>
9371 Neither the source hard disk nor the target hard disk is an
9372 <link to="HardDiskType_Immutable"/> hard disk.
9373 </li>
9374 <li>
9375 The part of the hard disk tree from the source hard disk to the
9376 target hard disk is a linear chain, i.e. all hard disks in this
9377 chain have exactly one child which is the next hard disk in this
9378 chain. The only exception from this rule is the target hard disk in
9379 the forward merge operation; it is allowed to have any number of
9380 child hard disks because the merge operation will hot change its
9381 logical contents (as it is seen by the guest OS or by children).
9382 </li>
9383 <li>
9384 None of the involved hard disks are in
9385 <link to="MediaState_LockedRead"/> or
9386 <link to="MediaState_LockedWrite"/> state.
9387 </li>
9388 </ul>
9389
9390 <note>
9391 This (source) hard disk and all intermediates will be placed to <link
9392 to="MediaState_Deleting"/> state and the target hard disk will be
9393 placed to <link to="MediaState_LockedWrite"/> state and for the
9394 duration of this operation.
9395 </note>
9396 </desc>
9397 <param name="targetId" type="uuid" dir="in">
9398 <desc>UUID of the target ancestor or descendant hard disk.</desc>
9399 </param>
9400 <param name="progress" type="IProgress" dir="return">
9401 <desc>Progress object to track the operation completion.</desc>
9402 </param>
9403 </method>
9404
9405 <!-- clone methods -->
9406
9407 <method name="cloneTo">
9408 <desc>
9409 Starts creating a clone of this hard disk in the format and at the
9410 location defined by the @a target argument.
9411
9412 The target hard disk must be in <link to="MediaState_NotCreated"/>
9413 state (i.e. must not have an existing storage unit). Upon successful
9414 completion, the cloned hard disk will contain exactly the same sector
9415 data as the hard disk being cloned, except that a new UUID for the clone
9416 will be randomly generated.
9417
9418 After the returned progress object reports that the operation is
9419 successfully complete, the target hard disk gets remembered by this
9420 VirtualBox installation and may be attached to virtual machines.
9421
9422 <note>
9423 If the cloned hard disk is a differencing hard disk, it will inherit
9424 parent dependency of the original hard disk.
9425 </note>
9426 <note>
9427 This hard disk will be placed to <link to="MediaState_LockedRead"/>
9428 state for the duration of this operation.
9429 </note>
9430 </desc>
9431 <param name="target" type="IHardDisk" dir="in">
9432 <desc>Target hard disk.</desc>
9433 </param>
9434 <param name="variant" type="HardDiskVariant" dir="in">
9435 <desc>Exact image variant which should be created.</desc>
9436 </param>
9437 <param name="progress" type="IProgress" dir="return">
9438 <desc>Progress object to track the operation completion.</desc>
9439 </param>
9440 </method>
9441
9442 <method name="flattenTo">
9443 <desc>
9444 Starts creating a deep (independent) clone of this hard disk in the
9445 format and at the location defined by the @a target argument.
9446
9447 This operation is similar to <link to="#cloneTo"/> except that when
9448 applied to a differencing hard disk, it will also copy missing hard disk
9449 data from all parent hard disks it is linked to. This will make the
9450 created clone an independent base hard disk that contains all hard disk
9451 data and does not need any other hard disks to operate.
9452
9453 After the returned progress object reports that the operation is
9454 successfully complete, the target hard disk gets remembered by this
9455 VirtualBox installation and may be attached to virtual machines.
9456
9457 <note>
9458 For base hard disks, this operation is identical to
9459 <link to="#cloneTo"/>.
9460 </note>
9461 <note>
9462 This hard disk and all its parent hard disks will be placed to <link
9463 to="MediaState_LockedRead"/> state for the duration of this
9464 operation.
9465 </note>
9466 </desc>
9467 <param name="target" type="IHardDisk" dir="in">
9468 <desc>Target hard disk.</desc>
9469 </param>
9470 <param name="variant" type="HardDiskVariant" dir="in">
9471 <desc>Exact image variant which should be created.</desc>
9472 </param>
9473 <param name="progress" type="IProgress" dir="return">
9474 <desc>Progress object to track the operation completion.</desc>
9475 </param>
9476 </method>
9477
9478 <!-- other methods -->
9479
9480 <method name="compact">
9481 <desc>
9482 Starts compacting of this hard disk. This means that the disk is
9483 transformed into a possibly more compact storage representation.
9484 This potentially creates temporary images, which can require a
9485 substantial amount of additional disk space.
9486
9487 This hard disk will be placed to <link to="MediaState_LockedWrite"/>
9488 state and all its parent hard disks (if any) will be placed to
9489 <link to="MediaState_LockedRead"/> state for the duration of this
9490 operation.
9491 </desc>
9492 <param name="progress" type="IProgress" dir="return">
9493 <desc>Progress object to track the operation completion.</desc>
9494 </param>
9495 </method>
9496
9497 <method name="reset">
9498 <desc>
9499 Starts erasing the contents of this differencing hard disk.
9500
9501 This operation will reset the differencing hard disk to its initial
9502 state when it does not contain any sector data and any read operation is
9503 redirected to its parent hard disk.
9504
9505 This hard disk will be placed to <link to="MediaState_LockedWrite"/>
9506 for the duration of this operation.
9507
9508 <result name="VBOX_E_NOT_SUPPORTED">
9509 This is not a differencing hard disk.
9510 </result>
9511 <result name="VBOX_E_INVALID_OBJECT_STATE">
9512 Hard disk is not in <link to="MediaState_Created"/> or
9513 <link to="MediaState_Inaccessible"/> state.
9514 </result>
9515 </desc>
9516 <param name="progress" type="IProgress" dir="return">
9517 <desc>Progress object to track the operation completion.</desc>
9518 </param>
9519 </method>
9520
9521 </interface>
9522
9523
9524 <!--
9525 // IHardDiskFormat
9526 /////////////////////////////////////////////////////////////////////////
9527 -->
9528
9529 <enum
9530 name="DataType"
9531 uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
9532 >
9533 <const name="Int32" value="0"/>
9534 <const name="Int8" value="1"/>
9535 <const name="String" value="2"/>
9536 </enum>
9537
9538 <enum
9539 name="DataFlags"
9540 uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
9541 >
9542 <const name="None" value="0x00"/>
9543 <const name="Mandatory" value="0x01"/>
9544 <const name="Expert" value="0x02"/>
9545 <const name="Array" value="0x04"/>
9546 <const name="FlagMask" value="0x07"/>
9547 </enum>
9548
9549 <enum
9550 name="HardDiskFormatCapabilities"
9551 uuid="1df1e4aa-d25a-4ba6-b2a2-02f60eb5903b"
9552 >
9553 <desc>
9554 Hard disk format capability flags.
9555 </desc>
9556
9557 <const name="Uuid" value="0x01">
9558 <desc>
9559 Supports UUIDs as expected by VirtualBox code.
9560 </desc>
9561 </const>
9562
9563 <const name="CreateFixed" value="0x02">
9564 <desc>
9565 Supports creating fixed size images, allocating all space instantly.
9566 </desc>
9567 </const>
9568
9569 <const name="CreateDynamic" value="0x04">
9570 <desc>
9571 Supports creating dynamically growing images, allocating space on
9572 demand.
9573 </desc>
9574 </const>
9575
9576 <const name="CreateSplit2G" value="0x08">
9577 <desc>
9578 Supports creating images split in chunks of a bit less than 2 GBytes.
9579 </desc>
9580 </const>
9581
9582 <const name="Differencing" value="0x10">
9583 <desc>
9584 Supports being used as a format for differencing hard disks (see <link
9585 to="IHardDisk::createDiffStorage"/>).
9586 </desc>
9587 </const>
9588
9589 <const name="Asynchronous" value="0x20">
9590 <desc>
9591 Supports asynchronous I/O operations for at least some configurations.
9592 </desc>
9593 </const>
9594
9595 <const name="File" value="0x40">
9596 <desc>
9597 The format backend operates on files (the <link to="IMedium::location"/>
9598 attribute of the hard disk specifies a file used to store hard disk
9599 data; for a list of supported file extensions see
9600 <link to="IHardDiskFormat::fileExtensions"/>).
9601 </desc>
9602 </const>
9603
9604 <const name="Properties" value="0x80">
9605 <desc>
9606 The format backend uses the property interface to configure the storage
9607 location and properties (the <link to="IHardDiskFormat::describeProperties"/>
9608 method is used to get access to properties supported by the given hard
9609 disk format).
9610 </desc>
9611 </const>
9612
9613 <const name="CapabilityMask" value="0xFF"/>
9614 </enum>
9615
9616 <interface
9617 name="IHardDiskFormat" extends="$unknown"
9618 uuid="7f3ba790-3a0b-4a8a-bac2-bb50150123c5"
9619 wsmap="managed"
9620 >
9621 <desc>
9622 The IHardDiskFormat interface represents a virtual hard disk format.
9623
9624 Each hard disk format has an associated backend which is used to handle
9625 hard disks stored in this format. This interface provides information
9626 about the properties of the associated backend.
9627
9628 Each hard disk format is identified by a string represented by the
9629 <link to="#id"/> attribute. This string is used in calls like
9630 <link to="IVirtualBox::createHardDisk"/> to specify the desired
9631 format.
9632
9633 The list of all supported hard disk formats can be obtained using
9634 <link to="ISystemProperties::hardDiskFormats"/>.
9635
9636 <see>IHardDisk</see>
9637 </desc>
9638
9639 <attribute name="id" type="wstring" readonly="yes">
9640 <desc>
9641 Identifier of this format.
9642
9643 The format identifier is a non-null non-empty ASCII string. Note that
9644 this string is case-insensitive. This means that, for example, all of
9645 the following strings:
9646 <pre>
9647 "VDI"
9648 "vdi"
9649 "VdI"</pre>
9650 refer to the same hard disk format.
9651
9652 This string is used in methods of other interfaces where it is necessary
9653 to specify a hard disk format, such as
9654 <link to="IVirtualBox::createHardDisk"/>.
9655 </desc>
9656 </attribute>
9657
9658 <attribute name="name" type="wstring" readonly="yes">
9659 <desc>
9660 Human readable description of this format.
9661
9662 Mainly for use in file open dialogs.
9663 </desc>
9664 </attribute>
9665
9666 <attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
9667 <desc>
9668 Array of strings containing the supported file extensions.
9669
9670 The first extension in the array is the extension preferred by the
9671 backend. It is recommended to use this extension when specifying a
9672 location of the storage unit for a new hard disk.
9673
9674 Note that some backends do not work on files, so this array may be
9675 empty.
9676
9677 <see>IHardDiskFormat::capabilities</see>
9678 </desc>
9679 </attribute>
9680
9681 <attribute name="capabilities" type="unsigned long" readonly="yes">
9682 <desc>
9683 Capabilities of the format as a set of bit flags.
9684
9685 For the meaning of individual capability flags see
9686 <link to="HardDiskFormatCapabilities"/>.
9687 </desc>
9688 </attribute>
9689
9690 <method name="describeProperties">
9691 <desc>
9692 Returns several arrays describing the properties supported by this
9693 format.
9694
9695 An element with the given index in each array describes one
9696 property. Thus, the number of elements in each returned array is the
9697 same and corresponds to the number of supported properties.
9698
9699 The returned arrays are filled in only if the
9700 <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
9701 All arguments must be non-NULL.
9702
9703 <see>DataType</see>
9704 <see>DataFlags</see>
9705 </desc>
9706
9707 <param name="names" type="wstring" safearray="yes" dir="out">
9708 <desc>Array of property names.</desc>
9709 </param>
9710 <param name="description" type="wstring" safearray="yes" dir="out">
9711 <desc>Array of property descriptions.</desc>
9712 </param>
9713 <param name="types" type="DataType" safearray="yes" dir="out">
9714 <desc>Array of property types.</desc>
9715 </param>
9716 <param name="flags" type="unsigned long" safearray="yes" dir="out">
9717 <desc>Array of property flags.</desc>
9718 </param>
9719 <param name="defaults" type="wstring" safearray="yes" dir="out">
9720 <desc>Array of default property values.</desc>
9721 </param>
9722 </method>
9723
9724 </interface>
9725
9726
9727 <!--
9728 // IFloppyImage
9729 /////////////////////////////////////////////////////////////////////////
9730 -->
9731
9732 <interface
9733 name="IFloppyImage" extends="IMedium"
9734 uuid="faa6101f-078c-4b3a-ab75-75670c8170b3"
9735 wsmap="managed"
9736 >
9737 <desc>
9738 The IFloppyImage interface represents a medium containing the image
9739 of a floppy disk. This is a subclass of <link to="IMedium" />; see remarks there.
9740 </desc>
9741
9742 </interface>
9743
9744
9745 <!--
9746 // IDVDImage
9747 /////////////////////////////////////////////////////////////////////////
9748 -->
9749
9750 <interface
9751 name="IDVDImage" extends="IMedium"
9752 uuid="b1f90bbb-e8a9-4484-9af1-3638e943f763"
9753 wsmap="managed"
9754 >
9755 <desc>
9756 The IDVDImage interface represents a medium containing the image
9757 of a CD or DVD disk in the ISO format.
9758
9759 This is a subclass of <link to="IMedium" />; see remarks there.
9760 </desc>
9761
9762 </interface>
9763
9764
9765 <!--
9766 // IDVDDrive
9767 /////////////////////////////////////////////////////////////////////////
9768 -->
9769
9770 <interface
9771 name="IDVDDrive" extends="$unknown"
9772 uuid="d650ef30-be9b-4dae-b463-11d5824681a5"
9773 wsmap="managed"
9774 >
9775 <desc>
9776 The IDVDDrive interface represents the virtual CD/DVD drive of the
9777 virtual machine. An object of this type is returned by
9778 <link to="IMachine::DVDDrive"/>.
9779 </desc>
9780
9781 <attribute name="state" type="DriveState" readonly="yes">
9782 <desc>Current drive state.</desc>
9783 </attribute>
9784
9785 <attribute name="passthrough" type="boolean">
9786 <desc>
9787 When a host drive is mounted and passthrough is enabled
9788 the guest OS will be able to directly send SCSI commands to
9789 the host drive. This enables the guest OS to use CD/DVD writers
9790 but is potentially dangerous.
9791 </desc>
9792 </attribute>
9793
9794 <method name="mountImage">
9795 <desc>Mounts a CD/DVD image with the specified UUID.
9796
9797 <result name="VBOX_E_FILE_ERROR">
9798 Invalid image file location.
9799 </result>
9800 <result name="VBOX_E_OBJECT_NOT_FOUND">
9801 Could not find a CD/DVD image matching @a imageId.
9802 </result>
9803 <result name="VBOX_E_INVALID_OBJECT_STATE">
9804 Invalid media state.
9805 </result>
9806
9807 </desc>
9808 <param name="imageId" type="uuid" dir="in"/>
9809 </method>
9810
9811 <method name="captureHostDrive">
9812 <desc>Captures the specified host CD/DVD drive.</desc>
9813 <param name="drive" type="IHostDVDDrive" dir="in"/>
9814 </method>
9815
9816 <method name="unmount">
9817 <desc>Unmounts the currently mounted image or host drive.</desc>
9818 </method>
9819
9820 <method name="getImage">
9821 <desc>Returns the currently mounted CD/DVD image.</desc>
9822 <param name="image" type="IDVDImage" dir="return"/>
9823 </method>
9824
9825 <method name="getHostDrive">
9826 <desc>Returns the currently mounted host CD/DVD drive.</desc>
9827 <param name="drive" type="IHostDVDDrive" dir="return"/>
9828 </method>
9829
9830 </interface>
9831
9832
9833 <!--
9834 // IFloppyDrive
9835 /////////////////////////////////////////////////////////////////////////
9836 -->
9837
9838 <interface
9839 name="IFloppyDrive" extends="$unknown"
9840 uuid="159412cd-bab8-452e-8097-218a020825a6"
9841 wsmap="managed"
9842 >
9843 <desc>
9844 The IFloppyDrive interface represents the virtual floppy drive of the
9845 virtual machine. An object of this type is returned by
9846 <link to="IMachine::floppyDrive" />.
9847 </desc>
9848
9849 <attribute name="enabled" type="boolean">
9850 <desc>
9851 Flag whether the floppy drive is enabled. If it is disabled,
9852 the floppy drive will not be reported to the guest OS.
9853 </desc>
9854 </attribute>
9855
9856 <attribute name="state" type="DriveState" readonly="yes">
9857 <desc>Current drive state.</desc>
9858 </attribute>
9859
9860 <method name="mountImage">
9861 <desc>Mounts a floppy image with the specified UUID.
9862
9863 <result name="VBOX_E_FILE_ERROR">
9864 Invalid image file location.
9865 </result>
9866 <result name="VBOX_E_OBJECT_NOT_FOUND">
9867 Could not find a floppy image matching @a imageID.
9868 </result>
9869 <result name="VBOX_E_INVALID_OBJECT_STATE">
9870 Invalid media state.
9871 </result>
9872
9873 </desc>
9874 <param name="imageId" type="uuid" dir="in"/>
9875 </method>
9876
9877 <method name="captureHostDrive">
9878 <desc>Captures the specified host floppy drive.</desc>
9879 <param name="drive" type="IHostFloppyDrive" dir="in"/>
9880 </method>
9881
9882 <method name="unmount">
9883 <desc>Unmounts the currently mounted image or host drive.</desc>
9884 </method>
9885
9886 <method name="getImage">
9887 <desc>Returns the currently mounted floppy image.</desc>
9888 <param name="image" type="IFloppyImage" dir="return"/>
9889 </method>
9890
9891 <method name="getHostDrive">
9892 <desc>Returns the currently mounted host floppy drive.</desc>
9893 <param name="drive" type="IHostFloppyDrive" dir="return"/>
9894 </method>
9895
9896 </interface>
9897
9898
9899 <!--
9900 // IKeyboard
9901 /////////////////////////////////////////////////////////////////////////
9902 -->
9903
9904 <interface
9905 name="IKeyboard" extends="$unknown"
9906 uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
9907 wsmap="managed"
9908 >
9909 <desc>
9910 The IKeyboard interface represents the virtual machine's keyboard. Used
9911 in <link to="IConsole::keyboard"/>.
9912
9913 Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
9914 to the virtual machine.
9915
9916 </desc>
9917 <method name="putScancode">
9918 <desc>Sends a scancode to the keyboard.
9919
9920 <result name="VBOX_E_IPRT_ERROR">
9921 Could not send scan code to virtual keyboard.
9922 </result>
9923
9924 </desc>
9925 <param name="scancode" type="long" dir="in"/>
9926 </method>
9927
9928 <method name="putScancodes">
9929 <desc>Sends an array of scancodes to the keyboard.
9930
9931 <result name="VBOX_E_IPRT_ERROR">
9932 Could not send all scan codes to virtual keyboard.
9933 </result>
9934
9935 </desc>
9936 <param name="scancodes" type="long" dir="in" safearray="yes"/>
9937 <param name="codesStored" type="unsigned long" dir="return"/>
9938 </method>
9939
9940 <method name="putCAD">
9941 <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
9942 function is nothing special, it is just a convenience function
9943 calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
9944
9945 <result name="VBOX_E_IPRT_ERROR">
9946 Could not send all scan codes to virtual keyboard.
9947 </result>
9948
9949 </desc>
9950 </method>
9951
9952 </interface>
9953
9954
9955 <!--
9956 // IMouse
9957 /////////////////////////////////////////////////////////////////////////
9958 -->
9959
9960 <enum
9961 name="MouseButtonState"
9962 uuid="03131722-2EC5-4173-9794-0DACA46673EF"
9963 >
9964 <desc>
9965 Mouse button state.
9966 </desc>
9967
9968 <const name="LeftButton" value="0x01"/>
9969 <const name="RightButton" value="0x02"/>
9970 <const name="MiddleButton" value="0x04"/>
9971 <const name="WheelUp" value="0x08"/>
9972 <const name="WheelDown" value="0x10"/>
9973 <const name="MouseStateMask" value="0x1F"/>
9974 </enum>
9975
9976 <interface
9977 name="IMouse" extends="$unknown"
9978 uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
9979 wsmap="managed"
9980 >
9981 <desc>
9982 The IMouse interface represents the virtual machine's mouse. Used in
9983 <link to="IConsole::mouse"/>.
9984
9985 Through this interface, the virtual machine's virtual mouse can be
9986 controlled.
9987 </desc>
9988
9989 <attribute name="absoluteSupported" type="boolean" readonly="yes">
9990 <desc>
9991 Whether the guest OS supports absolute mouse pointer positioning
9992 or not.
9993 <note>
9994 VirtualBox Guest Tools need to be installed to the guest OS
9995 in order to enable absolute mouse positioning support.
9996 You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
9997 callback to be instantly informed about changes of this attribute
9998 during virtual machine execution.
9999 </note>
10000 <see><link to="#putMouseEventAbsolute"/></see>
10001 </desc>
10002 </attribute>
10003
10004 <method name="putMouseEvent">
10005 <desc>
10006 Initiates a mouse event using relative pointer movements
10007 along x and y axis.
10008
10009 <result name="E_ACCESSDENIED">
10010 Console not powered up.
10011 </result>
10012 <result name="VBOX_E_IPRT_ERROR">
10013 Could not send mouse event to virtual mouse.
10014 </result>
10015
10016 </desc>
10017
10018 <param name="dx" type="long" dir="in">
10019 <desc>
10020 Amount of pixels the mouse should move to the right.
10021 Negative values move the mouse to the left.
10022 </desc>
10023 </param>
10024 <param name="dy" type="long" dir="in">
10025 <desc>
10026 Amount of pixels the mouse should move downwards.
10027 Negative values move the mouse upwards.
10028 </desc>
10029 </param>
10030 <param name="dz" type="long" dir="in">
10031 <desc>
10032 Amount of mouse wheel moves.
10033 Positive values describe clockwise wheel rotations,
10034 negative values describe counterclockwise rotations.
10035 </desc>
10036 </param>
10037 <param name="buttonState" type="long" dir="in">
10038 <desc>
10039 The current state of mouse buttons. Every bit represents
10040 a mouse button as follows:
10041 <table>
10042 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10043 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10044 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10045 </table>
10046 A value of <tt>1</tt> means the corresponding button is pressed.
10047 otherwise it is released.
10048 </desc>
10049 </param>
10050 </method>
10051
10052 <method name="putMouseEventAbsolute">
10053 <desc>
10054 Positions the mouse pointer using absolute x and y coordinates.
10055 These coordinates are expressed in pixels and
10056 start from <tt>[1,1]</tt> which corresponds to the top left
10057 corner of the virtual display.
10058
10059 <result name="E_ACCESSDENIED">
10060 Console not powered up.
10061 </result>
10062 <result name="VBOX_E_IPRT_ERROR">
10063 Could not send mouse event to virtual mouse.
10064 </result>
10065
10066 <note>
10067 This method will have effect only if absolute mouse
10068 positioning is supported by the guest OS.
10069 </note>
10070
10071 <see><link to="#absoluteSupported"/></see>
10072 </desc>
10073
10074 <param name="x" type="long" dir="in">
10075 <desc>
10076 X coordinate of the pointer in pixels, starting from <tt>1</tt>.
10077 </desc>
10078 </param>
10079 <param name="y" type="long" dir="in">
10080 <desc>
10081 Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
10082 </desc>
10083 </param>
10084 <param name="dz" type="long" dir="in">
10085 <desc>
10086 Amount of mouse wheel moves.
10087 Positive values describe clockwise wheel rotations,
10088 negative values describe counterclockwise rotations.
10089 </desc>
10090 </param>
10091 <param name="buttonState" type="long" dir="in">
10092 <desc>
10093 The current state of mouse buttons. Every bit represents
10094 a mouse button as follows:
10095 <table>
10096 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
10097 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
10098 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
10099 </table>
10100 A value of <tt>1</tt> means the corresponding button is pressed.
10101 otherwise it is released.
10102 </desc>
10103 </param>
10104 </method>
10105
10106 </interface>
10107
10108 <!--
10109 // IDisplay
10110 /////////////////////////////////////////////////////////////////////////
10111 -->
10112
10113 <enum
10114 name="FramebufferAccelerationOperation"
10115 uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
10116 >
10117 <desc>
10118 Frame buffer acceleration operation.
10119 </desc>
10120
10121 <const name="SolidFillAcceleration" value="1"/>
10122 <const name="ScreenCopyAcceleration" value="2"/>
10123 </enum>
10124
10125 <enum
10126 name="FramebufferPixelFormat"
10127 uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
10128 >
10129 <desc>
10130 Format of the video memory buffer. Constants represented by this enum can
10131 be used to test for particular values of <link
10132 to="IFramebuffer::pixelFormat"/>. See also <link
10133 to="IFramebuffer::requestResize"/>.
10134
10135 See also www.fourcc.org for more information about FOURCC pixel formats.
10136 </desc>
10137
10138 <const name="Opaque" value="0">
10139 <desc>
10140 Unknown buffer format (the user may not assume any particular format of
10141 the buffer).
10142 </desc>
10143 </const>
10144 <const name="FOURCC_RGB" value="0x32424752">
10145 <desc>
10146 Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
10147 bit layout).
10148 </desc>
10149 </const>
10150 </enum>
10151
10152 <interface
10153 name="IFramebuffer" extends="$unknown"
10154 uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
10155 wsmap="suppress"
10156 >
10157 <attribute name="address" type="octet" mod="ptr" readonly="yes">
10158 <desc>Address of the start byte of the frame buffer.</desc>
10159 </attribute>
10160
10161 <attribute name="width" type="unsigned long" readonly="yes">
10162 <desc>Frame buffer width, in pixels.</desc>
10163 </attribute>
10164
10165 <attribute name="height" type="unsigned long" readonly="yes">
10166 <desc>Frame buffer height, in pixels.</desc>
10167 </attribute>
10168
10169 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10170 <desc>
10171 Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
10172 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
10173 are: 8, 15, 16, 24 and 32.
10174 </desc>
10175 </attribute>
10176
10177 <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
10178 <desc>
10179 Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
10180 to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
10181 size of the scan line must be aligned to 32 bits.
10182 </desc>
10183 </attribute>
10184
10185 <attribute name="pixelFormat" type="unsigned long" readonly="yes">
10186 <desc>
10187 Frame buffer pixel format. It's either one of the values defined by <link
10188 to="FramebufferPixelFormat"/> or a raw FOURCC code.
10189 <note>
10190 This attribute must never return <link
10191 to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
10192 <link to="#address"/> points to must be always known.
10193 </note>
10194 </desc>
10195 </attribute>
10196
10197 <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
10198 <desc>
10199 Defines whether this frame buffer uses the virtual video card's memory
10200 buffer (guest VRAM) directly or not. See <link
10201 to="IFramebuffer::requestResize"/> for more information.
10202 </desc>
10203 </attribute>
10204
10205 <attribute name="heightReduction" type="unsigned long" readonly="yes">
10206 <desc>
10207 Hint from the frame buffer about how much of the standard
10208 screen height it wants to use for itself. This information is
10209 exposed to the guest through the VESA BIOS and VMMDev interface
10210 so that it can use it for determining its video mode table. It
10211 is not guaranteed that the guest respects the value.
10212 </desc>
10213 </attribute>
10214
10215 <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
10216 <desc>
10217 An alpha-blended overlay which is superposed over the frame buffer.
10218 The initial purpose is to allow the display of icons providing
10219 information about the VM state, including disk activity, in front
10220 ends which do not have other means of doing that. The overlay is
10221 designed to controlled exclusively by IDisplay. It has no locking
10222 of its own, and any changes made to it are not guaranteed to be
10223 visible until the affected portion of IFramebuffer is updated. The
10224 overlay can be created lazily the first time it is requested. This
10225 attribute can also return NULL to signal that the overlay is not
10226 implemented.
10227 </desc>
10228 </attribute>
10229
10230 <attribute name="winId" type="unsigned long long" readonly="yes">
10231 <desc>
10232 Platform-dependent identifier of the window where context of this
10233 frame buffer is drawn, or zero if there's no such window.
10234 </desc>
10235 </attribute>
10236
10237 <method name="lock">
10238 <desc>
10239 Locks the frame buffer.
10240 Gets called by the IDisplay object where this frame buffer is
10241 bound to.
10242 </desc>
10243 </method>
10244
10245 <method name="unlock">
10246 <desc>
10247 Unlocks the frame buffer.
10248 Gets called by the IDisplay object where this frame buffer is
10249 bound to.
10250 </desc>
10251 </method>
10252
10253 <method name="notifyUpdate">
10254 <desc>
10255 Informs about an update.
10256 Gets called by the display object where this buffer is
10257 registered.
10258 </desc>
10259 <param name="x" type="unsigned long" dir="in"/>
10260 <param name="y" type="unsigned long" dir="in"/>
10261 <param name="width" type="unsigned long" dir="in"/>
10262 <param name="height" type="unsigned long" dir="in"/>
10263 <param name="finished" type="boolean" dir="return"/>
10264 </method>
10265
10266 <method name="requestResize">
10267 <desc>
10268 Requests a size and pixel format change.
10269
10270 There are two modes of working with the video buffer of the virtual
10271 machine. The <i>indirect</i> mode implies that the IFramebuffer
10272 implementation allocates a memory buffer for the requested display mode
10273 and provides it to the virtual machine. In <i>direct</i> mode, the
10274 IFramebuffer implementation uses the memory buffer allocated and owned
10275 by the virtual machine. This buffer represents the video memory of the
10276 emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
10277 usually faster because the implementation gets a raw pointer to the
10278 guest VRAM buffer which it can directly use for visualizing the contents
10279 of the virtual display, as opposed to the indirect mode where the
10280 contents of guest VRAM are copied to the memory buffer provided by
10281 the implementation every time a display update occurs.
10282
10283 It is important to note that the direct mode is really fast only when
10284 the implementation uses the given guest VRAM buffer directly, for
10285 example, by blitting it to the window representing the virtual machine's
10286 display, which saves at least one copy operation comparing to the
10287 indirect mode. However, using the guest VRAM buffer directly is not
10288 always possible: the format and the color depth of this buffer may be
10289 not supported by the target window, or it may be unknown (opaque) as in
10290 case of text or non-linear multi-plane VGA video modes. In this case,
10291 the indirect mode (that is always available) should be used as a
10292 fallback: when the guest VRAM contents are copied to the
10293 implementation-provided memory buffer, color and format conversion is
10294 done automatically by the underlying code.
10295
10296 The @a pixelFormat parameter defines whether the direct mode is
10297 available or not. If @a pixelFormat is <link
10298 to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
10299 VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
10300 @a bytesPerLine parameters must be ignored and the implementation must use
10301 the indirect mode (where it provides its own buffer in one of the
10302 supported formats). In all other cases, @a pixelFormat together with
10303 @a bitsPerPixel and @a bytesPerLine define the format of the video memory
10304 buffer pointed to by the @a VRAM parameter and the implementation is
10305 free to choose which mode to use. To indicate that this frame buffer uses
10306 the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
10307 attribute must return <tt>true</tt> and <link to="#address"/> must
10308 return exactly the same address that is passed in the @a VRAM parameter
10309 of this method; otherwise it is assumed that the indirect strategy is
10310 chosen.
10311
10312 The @a width and @a height parameters represent the size of the
10313 requested display mode in both modes. In case of indirect mode, the
10314 provided memory buffer should be big enough to store data of the given
10315 display mode. In case of direct mode, it is guaranteed that the given
10316 @a VRAM buffer contains enough space to represent the display mode of the
10317 given size. Note that this frame buffer's <link to="#width"/> and <link
10318 to="#height"/> attributes must return exactly the same values as
10319 passed to this method after the resize is completed (see below).
10320
10321 The @a finished output parameter determines if the implementation has
10322 finished resizing the frame buffer or not. If, for some reason, the
10323 resize cannot be finished immediately during this call, @a finished
10324 must be set to @c false, and the implementation must call
10325 <link to="IDisplay::resizeCompleted"/> after it has returned from
10326 this method as soon as possible. If @a finished is @c false, the
10327 machine will not call any frame buffer methods until
10328 <link to="IDisplay::resizeCompleted"/> is called.
10329
10330 Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
10331 <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
10332 this frame buffer must return exactly the same values as specified in the
10333 parameters of this method, after the resize is completed. If the
10334 indirect mode is chosen, these attributes must return values describing
10335 the format of the implementation's own memory buffer <link
10336 to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
10337 value must always correlate with <link to="#pixelFormat"/>. Note that
10338 the <link to="#pixelFormat"/> attribute must never return <link
10339 to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
10340
10341 <note>
10342 This method is called by the IDisplay object under the
10343 <link to="#lock"/> provided by this IFramebuffer
10344 implementation. If this method returns @c false in @a finished, then
10345 this lock is not released until
10346 <link to="IDisplay::resizeCompleted"/> is called.
10347 </note>
10348 </desc>
10349 <param name="screenId" type="unsigned long" dir="in">
10350 <desc>
10351 Logical screen number. Must be used in the corresponding call to
10352 <link to="IDisplay::resizeCompleted"/> if this call is made.
10353 </desc>
10354 </param>
10355 <param name="pixelFormat" type="unsigned long" dir="in">
10356 <desc>
10357 Pixel format of the memory buffer pointed to by @a VRAM.
10358 See also <link to="FramebufferPixelFormat"/>.
10359 </desc>
10360 </param>
10361 <param name="VRAM" type="octet" mod="ptr" dir="in">
10362 <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
10363 </param>
10364 <param name="bitsPerPixel" type="unsigned long" dir="in">
10365 <desc>Color depth, bits per pixel.</desc>
10366 </param>
10367 <param name="bytesPerLine" type="unsigned long" dir="in">
10368 <desc>Size of one scan line, in bytes.</desc>
10369 </param>
10370 <param name="width" type="unsigned long" dir="in">
10371 <desc>Width of the guest display, in pixels.</desc>
10372 </param>
10373 <param name="height" type="unsigned long" dir="in">
10374 <desc>Height of the guest display, in pixels.</desc>
10375 </param>
10376 <param name="finished" type="boolean" dir="return">
10377 <desc>
10378 Can the VM start using the new frame buffer immediately
10379 after this method returns or it should wait for
10380 <link to="IDisplay::resizeCompleted"/>.
10381 </desc>
10382 </param>
10383 </method>
10384
10385 <method name="operationSupported">
10386 <desc>
10387 Returns whether the given acceleration operation is supported
10388 by the IFramebuffer implementation. If not, the display object
10389 will not attempt to call the corresponding IFramebuffer entry
10390 point. Even if an operation is indicated as supported, the
10391 IFramebuffer implementation always has the option to return non
10392 supported from the corresponding acceleration method in which
10393 case the operation will be performed by the display engine. This
10394 allows for reduced IFramebuffer implementation complexity where
10395 only common cases are handled.
10396 </desc>
10397 <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
10398 <param name="supported" type="boolean" dir="return"/>
10399 </method>
10400
10401 <method name="videoModeSupported">
10402 <desc>
10403 Returns whether the frame buffer implementation is willing to
10404 support a given video mode. In case it is not able to render
10405 the video mode (or for some reason not willing), it should
10406 return false. Usually this method is called when the guest
10407 asks the VMM device whether a given video mode is supported
10408 so the information returned is directly exposed to the guest.
10409 It is important that this method returns very quickly.
10410 </desc>
10411 <param name="width" type="unsigned long" dir="in"/>
10412 <param name="height" type="unsigned long" dir="in"/>
10413 <param name="bpp" type="unsigned long" dir="in"/>
10414 <param name="supported" type="boolean" dir="return"/>
10415 </method>
10416
10417 <method name="solidFill">
10418 <desc>
10419 Fills the specified rectangle on screen with a solid color.
10420 </desc>
10421 <param name="x" type="unsigned long" dir="in"/>
10422 <param name="y" type="unsigned long" dir="in"/>
10423 <param name="width" type="unsigned long" dir="in"/>
10424 <param name="height" type="unsigned long" dir="in"/>
10425 <param name="color" type="unsigned long" dir="in"/>
10426 <param name="handled" type="boolean" dir="return"/>
10427 </method>
10428
10429 <method name="copyScreenBits">
10430 <desc>
10431 Copies specified rectangle on the screen.
10432 </desc>
10433 <param name="xDst" type="unsigned long" dir="in"/>
10434 <param name="yDst" type="unsigned long" dir="in"/>
10435 <param name="xSrc" type="unsigned long" dir="in"/>
10436 <param name="ySrc" type="unsigned long" dir="in"/>
10437 <param name="width" type="unsigned long" dir="in"/>
10438 <param name="height" type="unsigned long" dir="in"/>
10439 <param name="handled" type="boolean" dir="return"/>
10440 </method>
10441
10442 <method name="getVisibleRegion">
10443 <desc>
10444 Returns the visible region of this frame buffer.
10445
10446 If the @a rectangles parameter is <tt>NULL</tt> then the value of the
10447 @a count parameter is ignored and the number of elements necessary to
10448 describe the current visible region is returned in @a countCopied.
10449
10450 If @a rectangles is not <tt>NULL</tt> but @a count is less
10451 than the required number of elements to store region data, the method
10452 will report a failure. If @a count is equal or greater than the
10453 required number of elements, then the actual number of elements copied
10454 to the provided array will be returned in @a countCopied.
10455
10456 <note>
10457 The address of the provided array must be in the process space of
10458 this IFramebuffer object.
10459 </note>
10460 <note>
10461 Method not yet implemented.
10462 </note>
10463 </desc>
10464 <param name="rectangles" type="octet" mod="ptr" dir="in">
10465 <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
10466 </param>
10467 <param name="count" type="unsigned long" dir="in">
10468 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
10469 </param>
10470 <param name="countCopied" type="unsigned long" dir="return">
10471 <desc>Number of elements copied to the @a rectangles array.</desc>
10472 </param>
10473 </method>
10474
10475 <method name="setVisibleRegion">
10476 <desc>
10477 Suggests a new visible region to this frame buffer. This region
10478 represents the area of the VM display which is a union of regions of
10479 all top-level windows of the guest operating system running inside the
10480 VM (if the Guest Additions for this system support this
10481 functionality). This information may be used by the frontends to
10482 implement the seamless desktop integration feature.
10483
10484 <note>
10485 The address of the provided array must be in the process space of
10486 this IFramebuffer object.
10487 </note>
10488 <note>
10489 The IFramebuffer implementation must make a copy of the provided
10490 array of rectangles.
10491 </note>
10492 <note>
10493 Method not yet implemented.
10494 </note>
10495 </desc>
10496 <param name="rectangles" type="octet" mod="ptr" dir="in">
10497 <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
10498 </param>
10499 <param name="count" type="unsigned long" dir="in">
10500 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
10501 </param>
10502 </method>
10503
10504 </interface>
10505
10506 <interface
10507 name="IFramebufferOverlay" extends="IFramebuffer"
10508 uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
10509 wsmap="suppress"
10510 >
10511 <desc>
10512 The IFramebufferOverlay interface represents an alpha blended overlay
10513 for displaying status icons above an IFramebuffer. It is always created
10514 not visible, so that it must be explicitly shown. It only covers a
10515 portion of the IFramebuffer, determined by its width, height and
10516 co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
10517 that order) format, and may be written to directly. Do re-read the
10518 width though, after setting it, as it may be adjusted (increased) to
10519 make it more suitable for the front end.
10520 </desc>
10521 <attribute name="x" type="unsigned long" readonly="yes">
10522 <desc>X position of the overlay, relative to the frame buffer.</desc>
10523 </attribute>
10524
10525 <attribute name="y" type="unsigned long" readonly="yes">
10526 <desc>Y position of the overlay, relative to the frame buffer.</desc>
10527 </attribute>
10528
10529 <attribute name="visible" type="boolean" readonly="no">
10530 <desc>
10531 Whether the overlay is currently visible.
10532 </desc>
10533 </attribute>
10534
10535 <attribute name="alpha" type="unsigned long" readonly="no">
10536 <desc>
10537 The global alpha value for the overlay. This may or may not be
10538 supported by a given front end.
10539 </desc>
10540 </attribute>
10541
10542 <method name="move">
10543 <desc>
10544 Changes the overlay's position relative to the IFramebuffer.
10545 </desc>
10546 <param name="x" type="unsigned long" dir="in"/>
10547 <param name="y" type="unsigned long" dir="in"/>
10548 </method>
10549
10550 </interface>
10551
10552 <interface
10553 name="IDisplay" extends="$unknown"
10554 uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
10555 wsmap="suppress"
10556 >
10557 <desc>
10558 The IDisplay interface represents the virtual machine's display.
10559
10560 The object implementing this interface is contained in each
10561 <link to="IConsole::display"/> attribute and represents the visual
10562 output of the virtual machine.
10563
10564 The virtual display supports pluggable output targets represented by the
10565 IFramebuffer interface. Examples of the output target are a window on
10566 the host computer or an RDP session's display on a remote computer.
10567 </desc>
10568 <attribute name="width" type="unsigned long" readonly="yes">
10569 <desc>Current display width.</desc>
10570 </attribute>
10571
10572 <attribute name="height" type="unsigned long" readonly="yes">
10573 <desc>Current display height.</desc>
10574 </attribute>
10575
10576 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
10577 <desc>
10578 Current guest display color depth. Note that this may differ
10579 from <link to="IFramebuffer::bitsPerPixel"/>.
10580 </desc>
10581 </attribute>
10582
10583 <method name="setupInternalFramebuffer">
10584 <desc>
10585 Prepares an internally managed frame buffer.
10586 </desc>
10587 <param name="depth" type="unsigned long" dir="in"/>
10588 </method>
10589
10590 <method name="lockFramebuffer">
10591 <desc>
10592 Requests access to the internal frame buffer.
10593
10594 <result name="VBOX_E_NOT_SUPPORTED">
10595 Attempt to lock a non-internal frame buffer.
10596 </result>
10597
10598 </desc>
10599 <param name="address" type="octet" mod="ptr" dir="return"/>
10600 </method>
10601
10602 <method name="unlockFramebuffer">
10603 <desc>
10604 Releases access to the internal frame buffer.
10605
10606 <result name="VBOX_E_NOT_SUPPORTED">
10607 Attempt to unlock a non-internal frame buffer.
10608 </result>
10609
10610 </desc>
10611 </method>
10612
10613 <method name="registerExternalFramebuffer">
10614 <desc>
10615 Registers an external frame buffer.
10616 </desc>
10617 <param name="framebuffer" type="IFramebuffer" dir="in"/>
10618 </method>
10619
10620 <method name="setFramebuffer">
10621 <desc>
10622 Sets the framebuffer for given screen.
10623 </desc>
10624 <param name="screenId" type="unsigned long" dir="in"/>
10625 <param name="framebuffer" type="IFramebuffer" dir="in"/>
10626 </method>
10627
10628 <method name="getFramebuffer">
10629 <desc>
10630 Queries the framebuffer for given screen.
10631 </desc>
10632 <param name="screenId" type="unsigned long" dir="in"/>
10633 <param name="framebuffer" type="IFramebuffer" dir="out"/>
10634 <param name="xOrigin" type="long" dir="out"/>
10635 <param name="yOrigin" type="long" dir="out"/>
10636 </method>
10637
10638 <method name="setVideoModeHint">
10639 <desc>
10640 Asks VirtualBox to request the given video mode from
10641 the guest. This is just a hint and it cannot be guaranteed
10642 that the requested resolution will be used. Guest Additions
10643 are required for the request to be seen by guests. The caller
10644 should issue the request and wait for a resolution change and
10645 after a timeout retry.
10646
10647 Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
10648 parameters means that the corresponding values should be taken from the
10649 current video mode (i.e. left unchanged).
10650
10651 If the guest OS supports multi-monitor configuration then the @a display
10652 parameter specifies the number of the guest display to send the hint to:
10653 <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
10654 so on. If the multi-monitor configuration is not supported, @a display
10655 must be <tt>0</tt>.
10656
10657 <result name="E_INVALIDARG">
10658 The @a display is not associated with any monitor.
10659 </result>
10660
10661 </desc>
10662 <param name="width" type="unsigned long" dir="in"/>
10663 <param name="height" type="unsigned long" dir="in"/>
10664 <param name="bitsPerPixel" type="unsigned long" dir="in"/>
10665 <param name="display" type="unsigned long" dir="in"/>
10666 </method>
10667
10668 <method name="setSeamlessMode">
10669 <desc>
10670 Enables or disables seamless guest display rendering (seamless desktop
10671 integration) mode.
10672 <note>
10673 Calling this method has no effect if <link
10674 to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
10675 </note>
10676 </desc>
10677 <param name="enabled" type="boolean" dir="in"/>
10678 </method>
10679
10680 <method name="takeScreenShot">
10681 <desc>
10682 Takes a screen shot of the requested size and copies it to the
10683 32-bpp buffer allocated by the caller.
10684
10685 <result name="E_NOTIMPL">
10686 Feature not implemented.
10687 </result>
10688 <result name="VBOX_E_IPRT_ERROR">
10689 Could not take a screenshot.
10690 </result>
10691
10692 </desc>
10693 <param name="address" type="octet" mod="ptr" dir="in"/>
10694 <param name="width" type="unsigned long" dir="in"/>
10695 <param name="height" type="unsigned long" dir="in"/>
10696 </method>
10697
10698 <method name="drawToScreen">
10699 <desc>
10700 Draws a 32-bpp image of the specified size from the given buffer
10701 to the given point on the VM display.
10702
10703 <result name="E_NOTIMPL">
10704 Feature not implemented.
10705 </result>
10706 <result name="VBOX_E_IPRT_ERROR">
10707 Could not draw to screen.
10708 </result>
10709
10710 </desc>
10711 <param name="address" type="octet" mod="ptr" dir="in"/>
10712 <param name="x" type="unsigned long" dir="in"/>
10713 <param name="y" type="unsigned long" dir="in"/>
10714 <param name="width" type="unsigned long" dir="in"/>
10715 <param name="height" type="unsigned long" dir="in"/>
10716 </method>
10717
10718 <method name="invalidateAndUpdate">
10719 <desc>
10720 Does a full invalidation of the VM display and instructs the VM
10721 to update it.
10722
10723 <result name="VBOX_E_IPRT_ERROR">
10724 Could not invalidate and update screen.
10725 </result>
10726
10727 </desc>
10728 </method>
10729
10730 <method name="resizeCompleted">
10731 <desc>
10732 Signals that a framebuffer has completed the resize operation.
10733
10734 <result name="VBOX_E_NOT_SUPPORTED">
10735 Operation only valid for external frame buffers.
10736 </result>
10737
10738 </desc>
10739 <param name="screenId" type="unsigned long" dir="in"/>
10740 </method>
10741
10742 <method name="updateCompleted">
10743 <desc>
10744 Signals that a framebuffer has completed the update operation.
10745
10746 <result name="VBOX_E_NOT_SUPPORTED">
10747 Operation only valid for external frame buffers.
10748 </result>
10749
10750 </desc>
10751 </method>
10752
10753 </interface>
10754
10755 <!--
10756 // INetworkAdapter
10757 /////////////////////////////////////////////////////////////////////////
10758 -->
10759
10760 <enum
10761 name="NetworkAttachmentType"
10762 uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
10763 >
10764 <desc>
10765 Network attachment type.
10766 </desc>
10767
10768 <const name="Null" value="0">
10769 <desc>Null value, also means "not attached".</desc>
10770 </const>
10771 <const name="NAT" value="1"/>
10772 <const name="Bridged" value="2"/>
10773 <const name="Internal" value="3"/>
10774 <const name="HostOnly" value="4"/>
10775 </enum>
10776
10777 <enum
10778 name="NetworkAdapterType"
10779 uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
10780 >
10781 <desc>
10782 Network adapter type.
10783 </desc>
10784
10785 <const name="Null" value="0">
10786 <desc>Null value (never used by the API).</desc>
10787 </const>
10788 <const name="Am79C970A" value="1"/>
10789 <const name="Am79C973" value="2"/>
10790 <const name="I82540EM" value="3"/>
10791 <const name="I82543GC" value="4"/>
10792 </enum>
10793
10794 <interface
10795 name="INetworkAdapter" extends="$unknown"
10796 uuid="65607a27-2b73-4d43-b4cc-0ba2c817fbde"
10797 wsmap="managed"
10798 >
10799 <desc>
10800 Represents a virtual network adapter that is attached to a virtual machine.
10801 Each virtual machine has a fixed number of network adapter slots with one
10802 instance of this attached to each of them. Call
10803 <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
10804 is attached to a given slot in a given machine.
10805
10806 Each network adapter can be in one of five attachment modes, which are
10807 represented by the <link to="NetworkAttachmentType" /> enumeration;
10808 see the <link to="#attachmentType" /> attribute.
10809 </desc>
10810
10811 <attribute name="adapterType" type="NetworkAdapterType">
10812 <desc>
10813 Type of the virtual network adapter. Depending on this value,
10814 VirtualBox will provide a different virtual network hardware
10815 to the guest.
10816 </desc>
10817 </attribute>
10818
10819 <attribute name="slot" type="unsigned long" readonly="yes">
10820 <desc>
10821 Slot number this adapter is plugged into. Corresponds to
10822 the value you pass to <link to="IMachine::getNetworkAdapter"/>
10823 to obtain this instance.
10824 </desc>
10825 </attribute>
10826
10827 <attribute name="enabled" type="boolean">
10828 <desc>
10829 Flag whether the network adapter is present in the
10830 guest system. If disabled, the virtual guest hardware will
10831 not contain this network adapter. Can only be changed when
10832 the VM is not running.
10833 </desc>
10834 </attribute>
10835
10836 <attribute name="MACAddress" type="wstring">
10837 <desc>
10838 Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
10839 it to NULL, VirtualBox will generate a unique MAC address.
10840 </desc>
10841 </attribute>
10842
10843 <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
10844
10845 <attribute name="hostInterface" type="wstring">
10846 <desc>
10847 Name of the host network interface the VM is attached to.
10848 </desc>
10849 </attribute>
10850
10851 <attribute name="internalNetwork" type="wstring">
10852 <desc>
10853 Name of the internal network the VM is attached to.
10854 </desc>
10855 </attribute>
10856
10857 <attribute name="NATNetwork" type="wstring">
10858 <desc>
10859 Name of the NAT network the VM is attached to.
10860 </desc>
10861 </attribute>
10862
10863 <attribute name="cableConnected" type="boolean">
10864 <desc>
10865 Flag whether the adapter reports the cable as connected or not.
10866 It can be used to report offline situations to a VM.
10867 </desc>
10868 </attribute>
10869
10870 <attribute name="lineSpeed" type="unsigned long">
10871 <desc>
10872 Line speed reported by custom drivers, in units of 1 kbps.
10873 </desc>
10874 </attribute>
10875
10876 <attribute name="traceEnabled" type="boolean">
10877 <desc>
10878 Flag whether network traffic from/to the network card should be traced.
10879 Can only be toggled when the VM is turned off.
10880 </desc>
10881 </attribute>
10882
10883 <attribute name="traceFile" type="wstring">
10884 <desc>
10885 Filename where a network trace will be stored. If not set, VBox-pid.pcap
10886 will be used.
10887 </desc>
10888 </attribute>
10889
10890 <method name="attachToNAT">
10891 <desc>
10892 Attach the network adapter to the Network Address Translation (NAT) interface.
10893 </desc>
10894 </method>
10895
10896 <method name="attachToBridgedInterface">
10897 <desc>
10898 Attach the network adapter to a bridged host interface.
10899 </desc>
10900 </method>
10901
10902 <method name="attachToInternalNetwork">
10903 <desc>
10904 Attach the network adapter to an internal network.
10905 </desc>
10906 </method>
10907
10908 <method name="attachToHostOnlyInterface">
10909 <desc>
10910 Attach the network adapter to the host-only network.
10911 </desc>
10912 </method>
10913
10914 <method name="detach">
10915 <desc>
10916 Detach the network adapter
10917 </desc>
10918 </method>
10919 </interface>
10920
10921
10922 <!--
10923 // ISerialPort
10924 /////////////////////////////////////////////////////////////////////////
10925 -->
10926
10927 <enum
10928 name="PortMode"
10929 uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
10930 >
10931 <desc>
10932 The PortMode enumeration represents possible communication modes for
10933 the virtual serial port device.
10934 </desc>
10935
10936 <const name="Disconnected" value="0">
10937 <desc>Virtual device is not attached to any real host device.</desc>
10938 </const>
10939 <const name="HostPipe" value="1">
10940 <desc>Virtual device is attached to a host pipe.</desc>
10941 </const>
10942 <const name="HostDevice" value="2">
10943 <desc>Virtual device is attached to a host device.</desc>
10944 </const>
10945 </enum>
10946
10947 <interface
10948 name="ISerialPort" extends="$unknown"
10949 uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
10950 wsmap="managed"
10951 >
10952
10953 <desc>
10954 The ISerialPort interface represents the virtual serial port device.
10955
10956 The virtual serial port device acts like an ordinary serial port
10957 inside the virtual machine. This device communicates to the real
10958 serial port hardware in one of two modes: host pipe or host device.
10959
10960 In host pipe mode, the #path attribute specifies the path to the pipe on
10961 the host computer that represents a serial port. The #server attribute
10962 determines if this pipe is created by the virtual machine process at
10963 machine startup or it must already exist before starting machine
10964 execution.
10965
10966 In host device mode, the #path attribute specifies the name of the
10967 serial port device on the host computer.
10968
10969 There is also a third communication mode: the disconnected mode. In this
10970 mode, the guest OS running inside the virtual machine will be able to
10971 detect the serial port, but all port write operations will be discarded
10972 and all port read operations will return no data.
10973
10974 <see>IMachine::getSerialPort</see>
10975 </desc>
10976
10977 <attribute name="slot" type="unsigned long" readonly="yes">
10978 <desc>
10979 Slot number this serial port is plugged into. Corresponds to
10980 the value you pass to <link to="IMachine::getSerialPort"/>
10981 to obtain this instance.
10982 </desc>
10983 </attribute>
10984
10985 <attribute name="enabled" type="boolean">
10986 <desc>
10987 Flag whether the serial port is enabled. If disabled,
10988 the serial port will not be reported to the guest OS.
10989 </desc>
10990 </attribute>
10991
10992 <attribute name="IOBase" type="unsigned long">
10993 <desc>Base I/O address of the serial port.</desc>
10994 </attribute>
10995
10996 <attribute name="IRQ" type="unsigned long">
10997 <desc>IRQ number of the serial port.</desc>
10998 </attribute>
10999
11000 <attribute name="hostMode" type="PortMode">
11001 <desc>
11002 How is this port connected to the host.
11003 <note>
11004 Changing this attribute may fail if the conditions for
11005 <link to="#path"/> are not met.
11006 </note>
11007 </desc>
11008 </attribute>
11009
11010 <attribute name="server" type="boolean">
11011 <desc>
11012 Flag whether this serial port acts as a server (creates a new pipe on
11013 the host) or as a client (uses the existing pipe). This attribute is
11014 used only when <link to="#hostMode"/> is PortMode_HostPipe.
11015 </desc>
11016 </attribute>
11017
11018 <attribute name="path" type="wstring">
11019 <desc>
11020 Path to the serial port's pipe on the host when <link to="#hostMode"/> is
11021 PortMode_HostPipe, or the host serial device name when
11022 <link to="#hostMode"/> is PortMode_HostDevice. In either of the above
11023 cases, setting a @c null or an empty string as the attribute's value
11024 will result into an error. Otherwise, the value of this property is
11025 ignored.
11026 </desc>
11027 </attribute>
11028
11029 </interface>
11030
11031 <!--
11032 // IParallelPort
11033 /////////////////////////////////////////////////////////////////////////
11034 -->
11035
11036 <interface
11037 name="IParallelPort" extends="$unknown"
11038 uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
11039 wsmap="managed"
11040 >
11041
11042 <desc>
11043 The IParallelPort interface represents the virtual parallel port device.
11044
11045 The virtual parallel port device acts like an ordinary parallel port
11046 inside the virtual machine. This device communicates to the real
11047 parallel port hardware using the name of the parallel device on the host
11048 computer specified in the #path attribute.
11049
11050 Each virtual parallel port device is assigned a base I/O address and an
11051 IRQ number that will be reported to the guest operating system and used
11052 to operate the given parallel port from within the virtual machine.
11053
11054 <see>IMachine::getParallelPort</see>
11055 </desc>
11056
11057 <attribute name="slot" type="unsigned long" readonly="yes">
11058 <desc>
11059 Slot number this parallel port is plugged into. Corresponds to
11060 the value you pass to <link to="IMachine::getParallelPort"/>
11061 to obtain this instance.
11062 </desc>
11063 </attribute>
11064
11065 <attribute name="enabled" type="boolean">
11066 <desc>
11067 Flag whether the parallel port is enabled. If disabled,
11068 the parallel port will not be reported to the guest OS.
11069 </desc>
11070 </attribute>
11071
11072 <attribute name="IOBase" type="unsigned long">
11073 <desc>Base I/O address of the parallel port.</desc>
11074 </attribute>
11075
11076 <attribute name="IRQ" type="unsigned long">
11077 <desc>IRQ number of the parallel port.</desc>
11078 </attribute>
11079
11080 <attribute name="path" type="wstring">
11081 <desc>
11082 Host parallel device name. If this parallel port is enabled, setting a
11083 @c null or an empty string as this attribute's value will result into
11084 an error.
11085 </desc>
11086 </attribute>
11087
11088 </interface>
11089
11090
11091 <!--
11092 // IMachineDebugger
11093 /////////////////////////////////////////////////////////////////////////
11094 -->
11095
11096 <interface
11097 name="IMachineDebugger" extends="$unknown"
11098 uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
11099 wsmap="suppress"
11100 >
11101 <method name="resetStats">
11102 <desc>
11103 Reset VM statistics.
11104 </desc>
11105 <param name="pattern" type="wstring" dir="in">
11106 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11107 </param>
11108 </method>
11109
11110 <method name="dumpStats">
11111 <desc>
11112 Dumps VM statistics.
11113 </desc>
11114 <param name="pattern" type="wstring" dir="in">
11115 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11116 </param>
11117 </method>
11118
11119 <method name="getStats">
11120 <desc>
11121 Get the VM statistics in a XMLish format.
11122 </desc>
11123 <param name="pattern" type="wstring" dir="in">
11124 <desc>The selection pattern. A bit similar to filename globbing.</desc>
11125 </param>
11126 <param name="withDescriptions" type="boolean" dir="in">
11127 <desc>Whether to include the descriptions.</desc>
11128 </param>
11129 <param name="stats" type="wstring" dir="out">
11130 <desc>The XML document containing the statistics.</desc>
11131 </param>
11132 </method>
11133
11134 <method name="injectNMI">
11135 <desc>
11136 Inject an NMI into a running VT-x/AMD-V VM.
11137 </desc>
11138 </method>
11139
11140 <attribute name="singlestep" type="boolean">
11141 <desc>Switch for enabling singlestepping.</desc>
11142 </attribute>
11143
11144 <attribute name="recompileUser" type="boolean">
11145 <desc>Switch for forcing code recompilation for user mode code.</desc>
11146 </attribute>
11147
11148 <attribute name="recompileSupervisor" type="boolean">
11149 <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
11150 </attribute>
11151
11152 <attribute name="PATMEnabled" type="boolean">
11153 <desc>Switch for enabling and disabling the PATM component.</desc>
11154 </attribute>
11155
11156 <attribute name="CSAMEnabled" type="boolean">
11157 <desc>Switch for enabling and disabling the CSAM component.</desc>
11158 </attribute>
11159
11160 <attribute name="logEnabled" type="boolean">
11161 <desc>Switch for enabling and disabling logging.</desc>
11162 </attribute>
11163
11164 <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
11165 <desc>
11166 Flag indicating whether the VM is currently making use of CPU hardware
11167 virtualization extensions.
11168 </desc>
11169 </attribute>
11170
11171 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
11172 <desc>
11173 Flag indicating whether the VM is currently making use of the nested paging
11174 CPU hardware virtualization extension.
11175 </desc>
11176 </attribute>
11177
11178 <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
11179 <desc>
11180 Flag indicating whether the VM is currently making use of the VPID
11181 VT-x extension.
11182 </desc>
11183 </attribute>
11184
11185 <attribute name="PAEEnabled" type="boolean" readonly="yes">
11186 <desc>
11187 Flag indicating whether the VM is currently making use of the Physical
11188 Address Extension CPU feature.
11189 </desc>
11190 </attribute>
11191
11192 <attribute name="virtualTimeRate" type="unsigned long">
11193 <desc>
11194 The rate at which the virtual time runs expressed as a percentage.
11195 The accepted range is 2% to 20000%.
11196 </desc>
11197 </attribute>
11198
11199 <!-- @todo method for setting log flags, groups and destination! -->
11200
11201 <attribute name="VM" type="unsigned long long" readonly="yes">
11202 <desc>
11203 Gets the VM handle. This is only for internal use while
11204 we carve the details of this interface.
11205 </desc>
11206 </attribute>
11207
11208 </interface>
11209
11210 <!--
11211 // IUSBController
11212 /////////////////////////////////////////////////////////////////////////
11213 -->
11214
11215 <interface
11216 name="IUSBController" extends="$unknown"
11217 uuid="238540fa-4b73-435a-a38e-4e1d9eab5c17"
11218 wsmap="managed"
11219 >
11220 <attribute name="enabled" type="boolean">
11221 <desc>
11222 Flag whether the USB controller is present in the
11223 guest system. If disabled, the virtual guest hardware will
11224 not contain any USB controller. Can only be changed when
11225 the VM is powered off.
11226 </desc>
11227 </attribute>
11228
11229 <attribute name="enabledEhci" type="boolean">
11230 <desc>
11231 Flag whether the USB EHCI controller is present in the
11232 guest system. If disabled, the virtual guest hardware will
11233 not contain a USB EHCI controller. Can only be changed when
11234 the VM is powered off.
11235 </desc>
11236 </attribute>
11237
11238 <attribute name="USBStandard" type="unsigned short" readonly="yes">
11239 <desc>
11240 USB standard version which the controller implements.
11241 This is a BCD which means that the major version is in the
11242 high byte and minor version is in the low byte.
11243 </desc>
11244 </attribute>
11245
11246 <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
11247 <desc>
11248 List of USB device filters associated with the machine.
11249
11250 If the machine is currently running, these filters are activated
11251 every time a new (supported) USB device is attached to the host
11252 computer that was not ignored by global filters
11253 (<link to="IHost::USBDeviceFilters"/>).
11254
11255 These filters are also activated when the machine is powered up.
11256 They are run against a list of all currently available USB
11257 devices (in states
11258 <link to="USBDeviceState_Available"/>,
11259 <link to="USBDeviceState_Busy"/>,
11260 <link to="USBDeviceState_Held"/>) that were not previously
11261 ignored by global filters.
11262
11263 If at least one filter matches the USB device in question, this
11264 device is automatically captured (attached to) the virtual USB
11265 controller of this machine.
11266
11267 <see>IUSBDeviceFilter, ::IUSBController</see>
11268 </desc>
11269 </attribute>
11270
11271 <method name="createDeviceFilter">
11272 <desc>
11273 Creates a new USB device filter. All attributes except
11274 the filter name are set to <tt>null</tt> (any match),
11275 <i>active</i> is <tt>false</tt> (the filter is not active).
11276
11277 The created filter can then be added to the list of filters using
11278 <link to="#insertDeviceFilter"/>.
11279
11280 <result name="VBOX_E_INVALID_VM_STATE">
11281 The virtual machine is not mutable.
11282 </result>
11283
11284 <see>#deviceFilters</see>
11285 </desc>
11286 <param name="name" type="wstring" dir="in">
11287 <desc>
11288 Filter name. See <link to="IUSBDeviceFilter::name"/>
11289 for more info.
11290 </desc>
11291 </param>
11292 <param name="filter" type="IUSBDeviceFilter" dir="return">
11293 <desc>Created filter object.</desc>
11294 </param>
11295 </method>
11296
11297 <method name="insertDeviceFilter">
11298 <desc>
11299 Inserts the given USB device to the specified position
11300 in the list of filters.
11301
11302 Positions are numbered starting from <tt>0</tt>. If the specified
11303 position is equal to or greater than the number of elements in
11304 the list, the filter is added to the end of the collection.
11305
11306 <note>
11307 Duplicates are not allowed, so an attempt to insert a
11308 filter that is already in the collection, will return an
11309 error.
11310 </note>
11311
11312 <result name="VBOX_E_INVALID_VM_STATE">
11313 Virtual machine is not mutable.
11314 </result>
11315 <result name="E_INVALIDARG">
11316 USB device filter not created within this VirtualBox instance.
11317 </result>
11318 <result name="VBOX_E_INVALID_OBJECT_STATE">
11319 USB device filter already in list.
11320 </result>
11321
11322 <see>#deviceFilters</see>
11323 </desc>
11324 <param name="position" type="unsigned long" dir="in">
11325 <desc>Position to insert the filter to.</desc>
11326 </param>
11327 <param name="filter" type="IUSBDeviceFilter" dir="in">
11328 <desc>USB device filter to insert.</desc>
11329 </param>
11330 </method>
11331
11332 <method name="removeDeviceFilter">
11333 <desc>
11334 Removes a USB device filter from the specified position in the
11335 list of filters.
11336
11337 Positions are numbered starting from <tt>0</tt>. Specifying a
11338 position equal to or greater than the number of elements in
11339 the list will produce an error.
11340
11341 <see>#deviceFilters</see>
11342
11343 <result name="VBOX_E_INVALID_VM_STATE">
11344 Virtual machine is not mutable.
11345 </result>
11346 <result name="E_INVALIDARG">
11347 USB device filter list empty or invalid @a position.
11348 </result>
11349
11350 </desc>
11351 <param name="position" type="unsigned long" dir="in">
11352 <desc>Position to remove the filter from.</desc>
11353 </param>
11354 <param name="filter" type="IUSBDeviceFilter" dir="return">
11355 <desc>Removed USB device filter.</desc>
11356 </param>
11357 </method>
11358
11359 </interface>
11360
11361
11362 <!--
11363 // IUSBDevice
11364 /////////////////////////////////////////////////////////////////////////
11365 -->
11366
11367 <interface
11368 name="IUSBDevice" extends="$unknown"
11369 uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
11370 wsmap="managed"
11371 >
11372 <desc>
11373 The IUSBDevice interface represents a virtual USB device attached to the
11374 virtual machine.
11375
11376 A collection of objects implementing this interface is stored in the
11377 <link to="IConsole::USBDevices"/> attribute which lists all USB devices
11378 attached to a running virtual machine's USB controller.
11379 </desc>
11380
11381 <attribute name="id" type="uuid" readonly="yes">
11382 <desc>
11383 Unique USB device ID. This ID is built from #vendorId,
11384 #productId, #revision and #serialNumber.
11385 </desc>
11386 </attribute>
11387
11388 <attribute name="vendorId" type="unsigned short" readonly="yes">
11389 <desc>Vendor ID.</desc>
11390 </attribute>
11391
11392 <attribute name="productId" type="unsigned short" readonly="yes">
11393 <desc>Product ID.</desc>
11394 </attribute>
11395
11396 <attribute name="revision" type="unsigned short" readonly="yes">
11397 <desc>
11398 Product revision number. This is a packed BCD represented as
11399 unsigned short. The high byte is the integer part and the low
11400 byte is the decimal.
11401 </desc>
11402 </attribute>
11403
11404 <attribute name="manufacturer" type="wstring" readonly="yes">
11405 <desc>Manufacturer string.</desc>
11406 </attribute>
11407
11408 <attribute name="product" type="wstring" readonly="yes">
11409 <desc>Product string.</desc>
11410 </attribute>
11411
11412 <attribute name="serialNumber" type="wstring" readonly="yes">
11413 <desc>Serial number string.</desc>
11414 </attribute>
11415
11416 <attribute name="address" type="wstring" readonly="yes">
11417 <desc>Host specific address of the device.</desc>
11418 </attribute>
11419
11420 <attribute name="port" type="unsigned short" readonly="yes">
11421 <desc>
11422 Host USB port number the device is physically
11423 connected to.
11424 </desc>
11425 </attribute>
11426
11427 <attribute name="version" type="unsigned short" readonly="yes">
11428 <desc>
11429 The major USB version of the device - 1 or 2.
11430 </desc>
11431 </attribute>
11432
11433 <attribute name="portVersion" type="unsigned short" readonly="yes">
11434 <desc>
11435 The major USB version of the host USB port the device is
11436 physically connected to - 1 or 2. For devices not connected to
11437 anything this will have the same value as the version attribute.
11438 </desc>
11439 </attribute>
11440
11441 <attribute name="remote" type="boolean" readonly="yes">
11442 <desc>
11443 Whether the device is physically connected to a remote VRDP
11444 client or to a local host machine.
11445 </desc>
11446 </attribute>
11447
11448 </interface>
11449
11450
11451 <!--
11452 // IUSBDeviceFilter
11453 /////////////////////////////////////////////////////////////////////////
11454 -->
11455
11456 <interface
11457 name="IUSBDeviceFilter" extends="$unknown"
11458 uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
11459 wsmap="managed"
11460 >
11461 <desc>
11462 The IUSBDeviceFilter interface represents an USB device filter used
11463 to perform actions on a group of USB devices.
11464
11465 This type of filters is used by running virtual machines to
11466 automatically capture selected USB devices once they are physically
11467 attached to the host computer.
11468
11469 A USB device is matched to the given device filter if and only if all
11470 attributes of the device match the corresponding attributes of the
11471 filter (that is, attributes are joined together using the logical AND
11472 operation). On the other hand, all together, filters in the list of
11473 filters carry the semantics of the logical OR operation. So if it is
11474 desirable to create a match like "this vendor id OR this product id",
11475 one needs to create two filters and specify "any match" (see below)
11476 for unused attributes.
11477
11478 All filter attributes used for matching are strings. Each string
11479 is an expression representing a set of values of the corresponding
11480 device attribute, that will match the given filter. Currently, the
11481 following filtering expressions are supported:
11482
11483 <ul>
11484 <li><i>Interval filters</i>. Used to specify valid intervals for
11485 integer device attributes (Vendor ID, Product ID and Revision).
11486 The format of the string is:
11487
11488 <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
11489
11490 where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
11491 (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
11492 or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
11493 is omitted before a dash (<tt>-</tt>), the minimum possible integer
11494 is assumed; if <tt>n</tt> is omitted after a dash, the maximum
11495 possible integer is assumed.
11496 </li>
11497 <li><i>Boolean filters</i>. Used to specify acceptable values for
11498 boolean device attributes. The format of the string is:
11499
11500 <tt>true|false|yes|no|0|1</tt>
11501
11502 </li>
11503 <li><i>Exact match</i>. Used to specify a single value for the given
11504 device attribute. Any string that doesn't start with <tt>int:</tt>
11505 represents the exact match. String device attributes are compared to
11506 this string including case of symbols. Integer attributes are first
11507 converted to a string (see individual filter attributes) and then
11508 compared ignoring case.
11509
11510 </li>
11511 <li><i>Any match</i>. Any value of the corresponding device attribute
11512 will match the given filter. An empty or <tt>null</tt> string is
11513 used to construct this type of filtering expressions.
11514
11515 </li>
11516 </ul>
11517
11518 <note>
11519 On the Windows host platform, interval filters are not currently
11520 available. Also all string filter attributes
11521 (<link to="#manufacturer"/>, <link to="#product"/>,
11522 <link to="#serialNumber"/>) are ignored, so they behave as
11523 <i>any match</i> no matter what string expression is specified.
11524 </note>
11525
11526 <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
11527 </desc>
11528
11529 <attribute name="name" type="wstring">
11530 <desc>
11531 Visible name for this filter.
11532 This name is used to visually distinguish one filter from another,
11533 so it can neither be <tt>null</tt> nor an empty string.
11534 </desc>
11535 </attribute>
11536
11537 <attribute name="active" type="boolean">
11538 <desc>Whether this filter active or has been temporarily disabled.</desc>
11539 </attribute>
11540
11541 <attribute name="vendorId" type="wstring">
11542 <desc>
11543 <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
11544 The string representation for the <i>exact matching</i>
11545 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11546 (including leading zeroes).
11547 </desc>
11548 </attribute>
11549
11550 <attribute name="productId" type="wstring">
11551 <desc>
11552 <link to="IUSBDevice::productId">Product ID</link> filter.
11553 The string representation for the <i>exact matching</i>
11554 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
11555 (including leading zeroes).
11556 </desc>
11557 </attribute>
11558
11559 <attribute name="revision" type="wstring">
11560 <desc>
11561 <link to="IUSBDevice::productId">Product revision number</link>
11562 filter. The string representation for the <i>exact matching</i>
11563 has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
11564 of the integer part of the revision, and <tt>F</tt> is the
11565 decimal digit of its fractional part (including leading and
11566 trailing zeros).
11567 Note that for interval filters, it's best to use the hexadecimal
11568 form, because the revision is stored as a 16 bit packed BCD value;
11569 so the expression <tt>int:0x0100-0x0199</tt> will match any
11570 revision from <tt>1.0</tt> to <tt>1.99</tt>.
11571 </desc>
11572 </attribute>
11573
11574 <attribute name="manufacturer" type="wstring">
11575 <desc>
11576 <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
11577 </desc>
11578 </attribute>
11579
11580 <attribute name="product" type="wstring">
11581 <desc>
11582 <link to="IUSBDevice::product">Product</link> filter.
11583 </desc>
11584 </attribute>
11585
11586 <attribute name="serialNumber" type="wstring">
11587 <desc>
11588 <link to="IUSBDevice::serialNumber">Serial number</link> filter.
11589 </desc>
11590 </attribute>
11591
11592 <attribute name="port" type="wstring">
11593 <desc>
11594 <link to="IUSBDevice::port">Host USB port</link> filter.
11595 </desc>
11596 </attribute>
11597
11598 <attribute name="remote" type="wstring">
11599 <desc>
11600 <link to="IUSBDevice::remote">Remote state</link> filter.
11601 <note>
11602 This filter makes sense only for machine USB filters,
11603 i.e. it is ignored by IHostUSBDeviceFilter objects.
11604 </note>
11605 </desc>
11606 </attribute>
11607
11608 <attribute name="maskedInterfaces" type="unsigned long">
11609 <desc>
11610 This is an advanced option for hiding one or more USB interfaces
11611 from the guest. The value is a bit mask where the bits that are set
11612 means the corresponding USB interface should be hidden, masked off
11613 if you like.
11614 This feature only works on Linux hosts.
11615 </desc>
11616 </attribute>
11617
11618 </interface>
11619
11620
11621 <!--
11622 // IHostUSBDevice
11623 /////////////////////////////////////////////////////////////////////////
11624 -->
11625
11626 <enum
11627 name="USBDeviceState"
11628 uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
11629 >
11630 <desc>
11631 USB device state. This enumeration represents all possible states
11632 of the USB device physically attached to the host computer regarding
11633 its state on the host computer and availability to guest computers
11634 (all currently running virtual machines).
11635
11636 Once a supported USB device is attached to the host, global USB
11637 filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
11638 either ignore the device, or put it to USBDeviceState_Held state, or do
11639 nothing. Unless the device is ignored by global filters, filters of all
11640 currently running guests (<link to="IUSBController::deviceFilters"/>) are
11641 activated that can put it to USBDeviceState_Captured state.
11642
11643 If the device was ignored by global filters, or didn't match
11644 any filters at all (including guest ones), it is handled by the host
11645 in a normal way. In this case, the device state is determined by
11646 the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
11647 or USBDeviceState_Available, depending on the current device usage.
11648
11649 Besides auto-capturing based on filters, the device can be manually
11650 captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
11651 state is USBDeviceState_Busy, USBDeviceState_Available or
11652 USBDeviceState_Held.
11653
11654 <note>
11655 Due to differences in USB stack implementations in Linux and Win32,
11656 states USBDeviceState_Busy and USBDeviceState_vailable are applicable
11657 only to the Linux version of the product. This also means that (<link
11658 to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
11659 device state is USBDeviceState_Held.
11660 </note>
11661
11662 <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
11663 </desc>
11664
11665 <const name="NotSupported" value="0">
11666 <desc>
11667 Not supported by the VirtualBox server, not available to guests.
11668 </desc>
11669 </const>
11670 <const name="Unavailable" value="1">
11671 <desc>
11672 Being used by the host computer exclusively,
11673 not available to guests.
11674 </desc>
11675 </const>
11676 <const name="Busy" value="2">
11677 <desc>
11678 Being used by the host computer, potentially available to guests.
11679 </desc>
11680 </const>
11681 <const name="Available" value="3">
11682 <desc>
11683 Not used by the host computer, available to guests (the host computer
11684 can also start using the device at any time).
11685 </desc>
11686 </const>
11687 <const name="Held" value="4">
11688 <desc>
11689 Held by the VirtualBox server (ignored by the host computer),
11690 available to guests.
11691 </desc>
11692 </const>
11693 <const name="Captured" value="5">
11694 <desc>
11695 Captured by one of the guest computers, not available
11696 to anybody else.
11697 </desc>
11698 </const>
11699 </enum>
11700
11701 <interface
11702 name="IHostUSBDevice" extends="IUSBDevice"
11703 uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
11704 wsmap="managed"
11705 >
11706 <desc>
11707 The IHostUSBDevice interface represents a physical USB device attached
11708 to the host computer.
11709
11710 Besides properties inherited from IUSBDevice, this interface adds the
11711 <link to="#state"/> property that holds the current state of the USB
11712 device.
11713
11714 <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
11715 </desc>
11716
11717 <attribute name="state" type="USBDeviceState" readonly="yes">
11718 <desc>
11719 Current state of the device.
11720 </desc>
11721 </attribute>
11722
11723 <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
11724
11725 </interface>
11726
11727
11728 <!--
11729 // IHostUSBDeviceFilter
11730 /////////////////////////////////////////////////////////////////////////
11731 -->
11732
11733 <enum
11734 name="USBDeviceFilterAction"
11735 uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
11736 >
11737 <desc>
11738 Actions for host USB device filters.
11739 <see>IHostUSBDeviceFilter, USBDeviceState</see>
11740 </desc>
11741
11742 <const name="Null" value="0">
11743 <desc>Null value (never used by the API).</desc>
11744 </const>
11745 <const name="Ignore" value="1">
11746 <desc>Ignore the matched USB device.</desc>
11747 </const>
11748 <const name="Hold" value="2">
11749 <desc>Hold the matched USB device.</desc>
11750 </const>
11751 </enum>
11752
11753 <interface
11754 name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
11755 uuid="4cc70246-d74a-400f-8222-3900489c0374"
11756 wsmap="managed"
11757 >
11758 <desc>
11759 The IHostUSBDeviceFilter interface represents a global filter for a
11760 physical USB device used by the host computer. Used indirectly in
11761 <link to="IHost::USBDeviceFilters"/>.
11762
11763 Using filters of this type, the host computer determines the initial
11764 state of the USB device after it is physically attached to the
11765 host's USB controller.
11766
11767 <note>
11768 The <link to="#remote"/> attribute is ignored by this type of
11769 filters, because it makes sense only for
11770 <link to="IUSBController::deviceFilters">machine USB filters</link>.
11771 </note>
11772
11773 <see>IHost::USBDeviceFilters</see>
11774 </desc>
11775
11776 <attribute name="action" type="USBDeviceFilterAction">
11777 <desc>
11778 Action performed by the host when an attached USB device
11779 matches this filter.
11780 </desc>
11781 </attribute>
11782
11783 </interface>
11784
11785 <!--
11786 // IAudioAdapter
11787 /////////////////////////////////////////////////////////////////////////
11788 -->
11789
11790 <enum
11791 name="AudioDriverType"
11792 uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
11793 >
11794 <desc>
11795 Host audio driver type.
11796 </desc>
11797
11798 <const name="Null" value="0">
11799 <desc>Null value, also means "dummy audio driver".</desc>
11800 </const>
11801 <const name="WinMM" value="1"/>
11802 <const name="OSS" value="2"/>
11803 <const name="ALSA" value="3"/>
11804 <const name="DirectSound" value="4"/>
11805 <const name="CoreAudio" value="5"/>
11806 <const name="MMPM" value="6"/>
11807 <const name="Pulse" value="7"/>
11808 <const name="SolAudio" value="8"/>
11809 </enum>
11810
11811 <enum
11812 name="AudioControllerType"
11813 uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
11814 >
11815 <desc>
11816 Virtual audio controller type.
11817 </desc>
11818
11819 <const name="AC97" value="0"/>
11820 <const name="SB16" value="1"/>
11821 </enum>
11822
11823 <interface
11824 name="IAudioAdapter" extends="$unknown"
11825 uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
11826 wsmap="managed"
11827 >
11828 <desc>
11829 The IAudioAdapter interface represents the virtual audio adapter of
11830 the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
11831 </desc>
11832 <attribute name="enabled" type="boolean">
11833 <desc>
11834 Flag whether the audio adapter is present in the
11835 guest system. If disabled, the virtual guest hardware will
11836 not contain any audio adapter. Can only be changed when
11837 the VM is not running.
11838 </desc>
11839 </attribute>
11840 <attribute name="audioController" type="AudioControllerType">
11841 <desc>
11842 The audio hardware we emulate.
11843 </desc>
11844 </attribute>
11845 <attribute name="audioDriver" type="AudioDriverType">
11846 <desc>
11847 Audio driver the adapter is connected to. This setting
11848 can only be changed when the VM is not running.
11849 </desc>
11850 </attribute>
11851 </interface>
11852
11853 <!--
11854 // IVRDPServer
11855 /////////////////////////////////////////////////////////////////////////
11856 -->
11857
11858 <enum
11859 name="VRDPAuthType"
11860 uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
11861 >
11862 <desc>
11863 VRDP authentication type.
11864 </desc>
11865
11866 <const name="Null" value="0">
11867 <desc>Null value, also means "no authentication".</desc>
11868 </const>
11869 <const name="External" value="1"/>
11870 <const name="Guest" value="2"/>
11871 </enum>
11872
11873 <interface
11874 name="IVRDPServer" extends="$unknown"
11875 uuid="f4584ae7-6bce-474b-83d6-17d235e6aa89"
11876 wsmap="managed"
11877 >
11878 <attribute name="enabled" type="boolean">
11879 <desc>VRDP server status.</desc>
11880 </attribute>
11881
11882 <attribute name="port" type="unsigned long">
11883 <desc>
11884 VRDP server port number.
11885 <note>
11886 Setting the value of this property to <tt>0</tt> will reset the port
11887 number to the default value which is
11888 currently <tt>3389</tt>. Reading this property will always return a
11889 real port number, even after it has been set to <tt>0</tt> (in which
11890 case the default port is returned).
11891 </note>
11892 </desc>
11893 </attribute>
11894
11895 <attribute name="netAddress" type="wstring">
11896 <desc>VRDP server address.</desc>
11897 </attribute>
11898
11899 <attribute name="authType" type="VRDPAuthType">
11900 <desc>VRDP authentication method.</desc>
11901 </attribute>
11902
11903 <attribute name="authTimeout" type="unsigned long">
11904 <desc>Timeout for guest authentication. Milliseconds.</desc>
11905 </attribute>
11906
11907 <attribute name="allowMultiConnection" type="boolean">
11908 <desc>
11909 Flag whether multiple simultaneous connections to the VM are permitted.
11910 Note that this will be replaced by a more powerful mechanism in the future.
11911 </desc>
11912 </attribute>
11913
11914 <attribute name="reuseSingleConnection" type="boolean">
11915 <desc>
11916 Flag whether the existing connection must be dropped and a new connection
11917 must be established by the VRDP server, when a new client connects in single
11918 connection mode.
11919 </desc>
11920 </attribute>
11921
11922 </interface>
11923
11924
11925 <!--
11926 // ISharedFolder
11927 /////////////////////////////////////////////////////////////////////////
11928 -->
11929
11930 <interface
11931 name="ISharedFolder" extends="$unknown"
11932 uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
11933 wsmap="struct"
11934 >
11935 <desc>
11936 The ISharedFolder interface represents a folder in the host computer's
11937 file system accessible from the guest OS running inside a virtual
11938 machine using an associated logical name.
11939
11940 There are three types of shared folders:
11941 <ul>
11942 <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
11943 folders available to all virtual machines.</li>
11944 <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
11945 VM-specific shared folders available to the given virtual machine at
11946 startup.</li>
11947 <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
11948 VM-specific shared folders created in the session context (for
11949 example, when the virtual machine is running) and automatically
11950 discarded when the session is closed (the VM is powered off).</li>
11951 </ul>
11952
11953 Logical names of shared folders must be unique within the given scope
11954 (global, permanent or transient). However, they do not need to be unique
11955 across scopes. In this case, the definition of the shared folder in a
11956 more specific scope takes precedence over definitions in all other
11957 scopes. The order of precedence is (more specific to more general):
11958 <ol>
11959 <li>Transient definitions</li>
11960 <li>Permanent definitions</li>
11961 <li>Global definitions</li>
11962 </ol>
11963
11964 For example, if MyMachine has a shared folder named
11965 <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
11966 transient shared folder named <tt>C_DRIVE</tt> (that points
11967 to <tt>C:\\\\WINDOWS</tt>) will change the definition
11968 of <tt>C_DRIVE</tt> in the guest OS so
11969 that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
11970 to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
11971 PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
11972 the previous (permanent) definition of <tt>C_DRIVE</tt> that points
11973 to <tt>C:\\</tt> if it still exists.
11974
11975 Note that permanent and transient shared folders of different machines
11976 are in different name spaces, so they don't overlap and don't need to
11977 have unique logical names.
11978
11979 <note>
11980 Global shared folders are not implemented in the current version of the
11981 product.
11982 </note>
11983 </desc>
11984
11985 <attribute name="name" type="wstring" readonly="yes">
11986 <desc>Logical name of the shared folder.</desc>
11987 </attribute>
11988
11989 <attribute name="hostPath" type="wstring" readonly="yes">
11990 <desc>Full path to the shared folder in the host file system.</desc>
11991 </attribute>
11992
11993 <attribute name="accessible" type="boolean" readonly="yes">
11994 <desc>
11995 Whether the folder defined by the host path is currently
11996 accessible or not.
11997 For example, the folder can be unaccessible if it is placed
11998 on the network share that is not available by the time
11999 this property is read.
12000 </desc>
12001 </attribute>
12002
12003 <attribute name="writable" type="boolean" readonly="yes">
12004 <desc>
12005 Whether the folder defined by the host path is writable or
12006 not.
12007 </desc>
12008 </attribute>
12009
12010 <attribute name="lastAccessError" type="wstring" readonly="yes">
12011 <desc>
12012 Text message that represents the result of the last accessibility
12013 check.
12014
12015 Accessibility checks are performed each time the <link to="#accessible"/>
12016 attribute is read. A @c null string is returned if the last
12017 accessibility check was successful. A non-null string indicates a
12018 failure and should normally describe a reason of the failure (for
12019 example, a file read error).
12020 </desc>
12021 </attribute>
12022
12023 </interface>
12024
12025 <!--
12026 // ISession
12027 /////////////////////////////////////////////////////////////////////////
12028 -->
12029
12030 <interface
12031 name="IInternalSessionControl" extends="$unknown"
12032 uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
12033 internal="yes"
12034 wsmap="suppress"
12035 >
12036 <method name="getPID">
12037 <desc>PID of the process that has created this Session object.
12038 </desc>
12039 <param name="pid" type="unsigned long" dir="return"/>
12040 </method>
12041
12042 <method name="getRemoteConsole">
12043 <desc>
12044 Returns the console object suitable for remote control.
12045
12046 <result name="VBOX_E_INVALID_VM_STATE">
12047 Session state prevents operation.
12048 </result>
12049 <result name="VBOX_E_INVALID_OBJECT_STATE">
12050 Session type prevents operation.
12051 </result>
12052
12053 </desc>
12054 <param name="console" type="IConsole" dir="return"/>
12055 </method>
12056
12057 <method name="assignMachine">
12058 <desc>
12059 Assigns the machine object associated with this direct-type
12060 session or informs the session that it will be a remote one
12061 (if @a machine == NULL).
12062
12063 <result name="VBOX_E_INVALID_VM_STATE">
12064 Session state prevents operation.
12065 </result>
12066 <result name="VBOX_E_INVALID_OBJECT_STATE">
12067 Session type prevents operation.
12068 </result>
12069
12070 </desc>
12071 <param name="machine" type="IMachine" dir="in"/>
12072 </method>
12073
12074 <method name="assignRemoteMachine">
12075 <desc>
12076 Assigns the machine and the (remote) console object associated with
12077 this remote-type session.
12078
12079 <result name="VBOX_E_INVALID_VM_STATE">
12080 Session state prevents operation.
12081 </result>
12082
12083 </desc>
12084 <param name="machine" type="IMachine" dir="in"/>
12085 <param name="console" type="IConsole" dir="in"/>
12086 </method>
12087
12088 <method name="updateMachineState">
12089 <desc>
12090 Updates the machine state in the VM process.
12091 Must be called only in certain cases
12092 (see the method implementation).
12093
12094 <result name="VBOX_E_INVALID_VM_STATE">
12095 Session state prevents operation.
12096 </result>
12097 <result name="VBOX_E_INVALID_OBJECT_STATE">
12098 Session type prevents operation.
12099 </result>
12100
12101 </desc>
12102 <param name="aMachineState" type="MachineState" dir="in"/>
12103 </method>
12104
12105 <method name="uninitialize">
12106 <desc>
12107 Uninitializes (closes) this session. Used by VirtualBox to close
12108 the corresponding remote session when the direct session dies
12109 or gets closed.
12110
12111 <result name="VBOX_E_INVALID_VM_STATE">
12112 Session state prevents operation.
12113 </result>
12114
12115 </desc>
12116 </method>
12117
12118 <method name="onDVDDriveChange">
12119 <desc>
12120 Triggered when settings of the DVD drive object of the
12121 associated virtual machine have changed.
12122
12123 <result name="VBOX_E_INVALID_VM_STATE">
12124 Session state prevents operation.
12125 </result>
12126 <result name="VBOX_E_INVALID_OBJECT_STATE">
12127 Session type prevents operation.
12128 </result>
12129
12130 </desc>
12131 </method>
12132
12133 <method name="onFloppyDriveChange">
12134 <desc>
12135 Triggered when settings of the floppy drive object of the
12136 associated virtual machine have changed.
12137
12138 <result name="VBOX_E_INVALID_VM_STATE">
12139 Session state prevents operation.
12140 </result>
12141 <result name="VBOX_E_INVALID_OBJECT_STATE">
12142 Session type prevents operation.
12143 </result>
12144
12145 </desc>
12146 </method>
12147
12148 <method name="onNetworkAdapterChange">
12149 <desc>
12150 Triggered when settings of a network adapter of the
12151 associated virtual machine have changed.
12152
12153 <result name="VBOX_E_INVALID_VM_STATE">
12154 Session state prevents operation.
12155 </result>
12156 <result name="VBOX_E_INVALID_OBJECT_STATE">
12157 Session type prevents operation.
12158 </result>
12159
12160 </desc>
12161 <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
12162 </method>
12163
12164 <method name="onSerialPortChange">
12165 <desc>
12166 Triggered when settings of a serial port of the
12167 associated virtual machine have changed.
12168
12169 <result name="VBOX_E_INVALID_VM_STATE">
12170 Session state prevents operation.
12171 </result>
12172 <result name="VBOX_E_INVALID_OBJECT_STATE">
12173 Session type prevents operation.
12174 </result>
12175
12176 </desc>
12177 <param name="serialPort" type="ISerialPort" dir="in"/>
12178 </method>
12179
12180 <method name="onParallelPortChange">
12181 <desc>
12182 Triggered when settings of a parallel port of the
12183 associated virtual machine have changed.
12184
12185 <result name="VBOX_E_INVALID_VM_STATE">
12186 Session state prevents operation.
12187 </result>
12188 <result name="VBOX_E_INVALID_OBJECT_STATE">
12189 Session type prevents operation.
12190 </result>
12191
12192 </desc>
12193 <param name="parallelPort" type="IParallelPort" dir="in"/>
12194 </method>
12195
12196 <method name="onStorageControllerChange">
12197 <desc>
12198 Triggered when settings of a storage controller of the
12199 associated virtual machine have changed.
12200
12201 <result name="VBOX_E_INVALID_VM_STATE">
12202 Session state prevents operation.
12203 </result>
12204 <result name="VBOX_E_INVALID_OBJECT_STATE">
12205 Session type prevents operation.
12206 </result>
12207
12208 </desc>
12209 </method>
12210
12211 <method name="onVRDPServerChange">
12212 <desc>
12213 Triggered when settings of the VRDP server object of the
12214 associated virtual machine have changed.
12215
12216 <result name="VBOX_E_INVALID_VM_STATE">
12217 Session state prevents operation.
12218 </result>
12219 <result name="VBOX_E_INVALID_OBJECT_STATE">
12220 Session type prevents operation.
12221 </result>
12222
12223 </desc>
12224 </method>
12225
12226 <method name="onUSBControllerChange">
12227 <desc>
12228 Triggered when settings of the USB controller object of the
12229 associated virtual machine have changed.
12230
12231 <result name="VBOX_E_INVALID_VM_STATE">
12232 Session state prevents operation.
12233 </result>
12234 <result name="VBOX_E_INVALID_OBJECT_STATE">
12235 Session type prevents operation.
12236 </result>
12237
12238 </desc>
12239 </method>
12240
12241 <method name="onSharedFolderChange">
12242 <desc>
12243 Triggered when a permanent (global or machine) shared folder has been
12244 created or removed.
12245 <note>
12246 We don't pass shared folder parameters in this notification because
12247 the order in which parallel notifications are delivered is not defined,
12248 therefore it could happen that these parameters were outdated by the
12249 time of processing this notification.
12250 </note>
12251
12252 <result name="VBOX_E_INVALID_VM_STATE">
12253 Session state prevents operation.
12254 </result>
12255 <result name="VBOX_E_INVALID_OBJECT_STATE">
12256 Session type prevents operation.
12257 </result>
12258
12259 </desc>
12260 <param name="global" type="boolean" dir="in"/>
12261 </method>
12262
12263 <method name="onUSBDeviceAttach">
12264 <desc>
12265 Triggered when a request to capture a USB device (as a result
12266 of matched USB filters or direct call to
12267 <link to="IConsole::attachUSBDevice"/>) has completed.
12268 A @c null @a error object means success, otherwise it
12269 describes a failure.
12270
12271 <result name="VBOX_E_INVALID_VM_STATE">
12272 Session state prevents operation.
12273 </result>
12274 <result name="VBOX_E_INVALID_OBJECT_STATE">
12275 Session type prevents operation.
12276 </result>
12277
12278 </desc>
12279 <param name="device" type="IUSBDevice" dir="in"/>
12280 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12281 <param name="maskedInterfaces" type="unsigned long" dir="in"/>
12282 </method>
12283
12284 <method name="onUSBDeviceDetach">
12285 <desc>
12286 Triggered when a request to release the USB device (as a result
12287 of machine termination or direct call to
12288 <link to="IConsole::detachUSBDevice"/>) has completed.
12289 A @c null @a error object means success, otherwise it
12290
12291 <result name="VBOX_E_INVALID_VM_STATE">
12292 Session state prevents operation.
12293 </result>
12294 <result name="VBOX_E_INVALID_OBJECT_STATE">
12295 Session type prevents operation.
12296 </result>
12297
12298 </desc>
12299 <param name="id" type="uuid" dir="in"/>
12300 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
12301 </method>
12302
12303 <method name="onShowWindow">
12304 <desc>
12305 Called by <link to="IMachine::canShowConsoleWindow"/> and by
12306 <link to="IMachine::showConsoleWindow"/> in order to notify
12307 console callbacks
12308 <link to="IConsoleCallback::onCanShowWindow"/>
12309 and <link to="IConsoleCallback::onShowWindow"/>.
12310
12311 <result name="VBOX_E_INVALID_OBJECT_STATE">
12312 Session type prevents operation.
12313 </result>
12314
12315 </desc>
12316 <param name="check" type="boolean" dir="in"/>
12317 <param name="canShow" type="boolean" dir="out"/>
12318 <param name="winId" type="unsigned long long" dir="out"/>
12319 </method>
12320
12321 <method name="accessGuestProperty">
12322 <desc>
12323 Called by <link to="IMachine::getGuestProperty"/> and by
12324 <link to="IMachine::setGuestProperty"/> in order to read and
12325 modify guest properties.
12326
12327 <result name="VBOX_E_INVALID_VM_STATE">
12328 Machine session is not open.
12329 </result>
12330 <result name="VBOX_E_INVALID_OBJECT_STATE">
12331 Session type is not direct.
12332 </result>
12333
12334 </desc>
12335 <param name="name" type="wstring" dir="in"/>
12336 <param name="value" type="wstring" dir="in"/>
12337 <param name="flags" type="wstring" dir="in"/>
12338 <param name="isSetter" type="boolean" dir="in"/>
12339 <param name="retValue" type="wstring" dir="out"/>
12340 <param name="retTimestamp" type="unsigned long long" dir="out"/>
12341 <param name="retFlags" type="wstring" dir="out"/>
12342 </method>
12343
12344 <method name="enumerateGuestProperties">
12345 <desc>
12346 Return a list of the guest properties matching a set of patterns along
12347 with their values, time stamps and flags.
12348
12349 <result name="VBOX_E_INVALID_VM_STATE">
12350 Machine session is not open.
12351 </result>
12352 <result name="VBOX_E_INVALID_OBJECT_STATE">
12353 Session type is not direct.
12354 </result>
12355
12356 </desc>
12357 <param name="patterns" type="wstring" dir="in">
12358 <desc>
12359 The patterns to match the properties against as a comma-separated
12360 string. If this is empty, all properties currently set will be
12361 returned.
12362 </desc>
12363 </param>
12364 <param name="key" type="wstring" dir="out" safearray="yes">
12365 <desc>
12366 The key names of the properties returned.
12367 </desc>
12368 </param>
12369 <param name="value" type="wstring" dir="out" safearray="yes">
12370 <desc>
12371 The values of the properties returned. The array entries match the
12372 corresponding entries in the @a key array.
12373 </desc>
12374 </param>
12375 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
12376 <desc>
12377 The time stamps of the properties returned. The array entries match
12378 the corresponding entries in the @a key array.
12379 </desc>
12380 </param>
12381 <param name="flags" type="wstring" dir="out" safearray="yes">
12382 <desc>
12383 The flags of the properties returned. The array entries match the
12384 corresponding entries in the @a key array.
12385 </desc>
12386 </param>
12387 </method>
12388
12389 </interface>
12390
12391 <interface
12392 name="ISession" extends="$dispatched"
12393 uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
12394 wsmap="managed"
12395 >
12396 <desc>
12397 The ISession interface represents a serialization primitive for virtual
12398 machines.
12399
12400 With VirtualBox, every time one wishes to manipulate a virtual machine
12401 (e.g. change its settings or start execution), a session object is
12402 required. Such an object must be passed to one of the session methods
12403 that open the given session, which then initiates the machine manipulation.
12404
12405 A session serves several purposes: it identifies to the inter-process VirtualBox
12406 code which process is currently working with the virtual machine, and it ensures
12407 that there are no incompatible requests from several processes for the
12408 same virtual machine. Session objects can therefore be thought of as mutex
12409 semaphores that lock virtual machines to prevent conflicting accesses from
12410 several processes.
12411
12412 How sessions objects are used depends on whether you use the Main API
12413 via COM or via the webservice:
12414
12415 <ul>
12416 <li>When using the COM API directly, an object of the Session class from the
12417 VirtualBox type library needs to be created. In regular COM C++ client code,
12418 this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
12419 This object will then act as a local session object in further calls to open
12420 a session.
12421 </li>
12422
12423 <li>In the webservice, the session manager (IWebsessionManager) instead creates
12424 one session object automatically when <link to="IWebsessionManager::logon" />
12425 is called. A managed object reference to that session object can be retrieved by
12426 calling <link to="IWebsessionManager::getSessionObject" />. This session object
12427 reference can then be used to open sessions.
12428 </li>
12429 </ul>
12430
12431 Sessions are mainly used in two variations:
12432
12433 <ul>
12434 <li>
12435 To start a virtual machine in a separate process, one would call
12436 <link to="IVirtualBox::openRemoteSession"/>, which requires a session
12437 object as its first parameter. This session then identifies the caller
12438 and lets him control the started machine (for example, pause machine
12439 execution or power it down) as well as be notified about machine
12440 execution state changes.
12441 </li>
12442
12443 <li>To alter machine settings, or to start machine execution within the
12444 current process, one needs to open a direct session for the machine first by
12445 calling <link to="IVirtualBox::openSession"/>. While a direct session
12446 is open within one process, no any other process may open another direct
12447 session for the same machine. This prevents the machine from being changed
12448 by other processes while it is running or while the machine is being configured.
12449 </li>
12450 </ul>
12451
12452 One also can attach to an existing direct session already opened by
12453 another process (for example, in order to send a control request to the
12454 virtual machine such as the pause or the reset request). This is done by
12455 calling <link to="IVirtualBox::openExistingSession"/>.
12456
12457 <note>
12458 Unless you are trying to write a new VirtualBox front-end that
12459 performs direct machine execution (like the VirtualBox or VBoxSDL
12460 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
12461 session opened by <link to="IVirtualBox::openSession"/> and use this
12462 session only to change virtual machine settings. If you simply want to
12463 start virtual machine execution using one of the existing front-ends
12464 (for example the VirtualBox GUI or headless server), simply use
12465 <link to="IVirtualBox::openRemoteSession"/>; these front-ends
12466 will power up the machine automatically for you.
12467 </note>
12468 </desc>
12469
12470 <attribute name="state" type="SessionState" readonly="yes">
12471 <desc>Current state of this session.</desc>
12472 </attribute>
12473
12474 <attribute name="type" type="SessionType" readonly="yes">
12475 <desc>
12476 Type of this session. The value of this attribute is valid only
12477 if the session is currently open (i.e. its #state is
12478 SessionType_SessionOpen), otherwise an error will be returned.
12479 </desc>
12480 </attribute>
12481
12482 <attribute name="machine" type="IMachine" readonly="yes">
12483 <desc>Machine object associated with this session.</desc>
12484 </attribute>
12485
12486 <attribute name="console" type="IConsole" readonly="yes">
12487 <desc>Console object associated with this session.</desc>
12488 </attribute>
12489
12490 <method name="close">
12491 <desc>
12492 Closes a session that was previously opened.
12493
12494 It is recommended that every time an "open session" method (such as
12495 <link to="IVirtualBox::openRemoteSession" /> or
12496 <link to="IVirtualBox::openSession" />) has been called to
12497 manipulate a virtual machine, the caller invoke
12498 ISession::close() when it's done doing so. Since sessions are
12499 serialization primitives much like ordinary mutexes, they are
12500 best used the same way: for each "open" call, there should be
12501 a matching "close" call, even when errors occur.
12502
12503 Otherwise, if a direct session for a machine opened with
12504 <link to="IVirtualBox::openSession"/> is not explicitly closed
12505 when the application terminates, the state of the machine will
12506 be set to <link to="MachineState_Aborted" /> on the server.
12507
12508 Generally, it is recommended to close all open sessions explicitly
12509 before terminating the application (regardless of the reason for
12510 the termination).
12511
12512 <note>
12513 Do not expect the session state (<link to="ISession::state" />
12514 to return to "Closed" immediately after you invoke
12515 ISession::close(), particularly if you have started a remote
12516 session to execute the VM in a new process. The session state will
12517 automatically return to "Closed" once the VM is no longer executing,
12518 which can of course take a very long time.
12519 </note>
12520
12521 <result name="E_UNEXPECTED">
12522 Session is not open.
12523 </result>
12524
12525 </desc>
12526 </method>
12527
12528 </interface>
12529
12530 <!--
12531 // IStorageController
12532 /////////////////////////////////////////////////////////////////////////
12533 -->
12534
12535 <enum
12536 name="StorageBus"
12537 uuid="f381fdca-5953-41d0-b2bd-0542b012698d"
12538 >
12539 <desc>
12540 The connection type of the storage controller.
12541 </desc>
12542 <const name="Null" value="0">
12543 <desc><tt>null</tt> value. Never used by the API.</desc>
12544 </const>
12545 <const name="IDE" value="1"/>
12546 <const name="SATA" value="2"/>
12547 <const name="SCSI" value="3"/>
12548 </enum>
12549
12550 <enum
12551 name="StorageControllerType"
12552 uuid="685387db-a837-4320-a258-08f46a22f62a"
12553 >
12554 <desc>
12555 Storage controller type.
12556 </desc>
12557
12558 <const name="Null" value="0">
12559 <desc><tt>null</tt> value. Never used by the API.</desc>
12560 </const>
12561 <const name="LsiLogic" value="1"/>
12562 <const name="BusLogic" value="2"/>
12563 <const name="IntelAhci" value="3"/>
12564 <const name="PIIX3" value="4"/>
12565 <const name="PIIX4" value="5"/>
12566 <const name="ICH6" value="6"/>
12567 </enum>
12568
12569 <interface
12570 name="IStorageController" extends="$unknown"
12571 uuid="6bf8335b-d14a-44a5-9b45-ddc49ce7d5b2"
12572 wsmap="managed"
12573 >
12574 <desc>
12575 Represents a storage controller that is attached to a virtual machine
12576 (<link to="IMachine" />). Just as hard disks are attached to storage
12577 controllers in a real computer, virtual hard disks (represented by
12578 <link to="IHardDisk" />) are attached to virtual storage controllers,
12579 represented by this interface.
12580
12581 VirtualBox supports three types of virtual storage controller hardware:
12582 IDE, SCSI, and SATA (see <link to="#bus" />). Depending on which of
12583 these three is used, certain sub-types are available and can be
12584 selected in <link to="#controllerType" />.
12585 </desc>
12586
12587 <attribute name="name" type="wstring" readonly="yes">
12588 <desc>
12589 Name of the storage controller, as originally specified with
12590 <link to="IMachine::addStorageController" />. This then uniquely
12591 identifies this controller with other method calls such as
12592 <link to="IMachine::attachHardDisk" />.
12593 </desc>
12594 </attribute>
12595
12596 <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
12597 <desc>
12598 Maximum number of devices which can be attached to one port.
12599 </desc>
12600 </attribute>
12601
12602 <attribute name="minPortCount" type="unsigned long" readonly="yes">
12603 <desc>
12604 Minimum number of ports which can be set with
12605 <link to="IStorageController::SetPortCount"/>.
12606 </desc>
12607 </attribute>
12608
12609 <attribute name="maxPortCount" type="unsigned long" readonly="yes">
12610 <desc>
12611 Maximum number of ports which can be set with
12612 <link to="IStorageController::SetPortCount"/>.
12613 </desc>
12614 </attribute>
12615
12616 <attribute name="instance" type="unsigned long">
12617 <desc>
12618 The instance number of the device in the running VM.
12619 </desc>
12620 </attribute>
12621
12622 <attribute name="portCount" type="unsigned long">
12623 <desc>
12624 The number of currently usable ports on the controller.
12625 The minimum and maximum number of ports for one controller type can
12626 be determined with <link to="IStorageController::GetMinPortCount"/>
12627 and <link to="IStorageController::GetMaxPortCount"/>..
12628 </desc>
12629 </attribute>
12630
12631 <attribute name="bus" type="StorageBus" readonly="yes">
12632 <desc>
12633 The connection type of the storage controller.
12634 </desc>
12635 </attribute>
12636
12637 <attribute name="controllerType" type="StorageControllerType">
12638 <desc>
12639 Type of the virtual storage controller. Depending on this value,
12640 VirtualBox will provide a different virtual storage controller hardware
12641 to the guest.
12642
12643 For SCSI controllers, the default type is LsiLogic.
12644 </desc>
12645 </attribute>
12646
12647 <method name="GetIDEEmulationPort">
12648 <desc>
12649 Gets the corresponding port number which is emulated as an IDE device.
12650
12651 <result name="E_INVALIDARG">
12652 The @a devicePosition is not in the range 0 to 3.
12653 </result>
12654 <result name="E_NOTIMPL">
12655 The storage controller type is not SATAIntelAhci.
12656 </result>
12657
12658 </desc>
12659 <param name="devicePosition" type="long" dir="in"/>
12660 <param name="portNumber" type="long" dir="return"/>
12661 </method>
12662
12663 <method name="SetIDEEmulationPort">
12664 <desc>
12665 Sets the port number which is emulated as an IDE device.
12666
12667 <result name="E_INVALIDARG">
12668 The @a devicePosition is not in the range 0 to 3 or the
12669 @a portNumber is not in the range 0 to 29.
12670 </result>
12671 <result name="E_NOTIMPL">
12672 The storage controller type is not SATAIntelAhci.
12673 </result>
12674
12675 </desc>
12676 <param name="devicePosition" type="long" dir="in"/>
12677 <param name="portNumber" type="long" dir="in"/>
12678 </method>
12679
12680 </interface>
12681
12682<if target="wsdl">
12683
12684 <!--
12685 // IManagedObjectRef
12686 /////////////////////////////////////////////////////////////////////////
12687 -->
12688
12689 <interface
12690 name="IManagedObjectRef" extends="$unknown"
12691 uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
12692 internal="yes"
12693 wsmap="managed"
12694 wscpp="hardcoded"
12695 >
12696 <desc>
12697 Managed object reference.
12698
12699 Only within the webservice, a managed object reference (which is really
12700 an opaque number) allows a webservice client to address an object
12701 that lives in the address space of the webservice server.
12702
12703 Behind each managed object reference, there is a COM object that lives
12704 in the webservice server's address space. The COM object is not freed
12705 until the managed object reference is released, either by an explicit
12706 call to <link to="IManagedObjectRef::release" /> or by logging off from
12707 the webservice (<link to="IWebsessionManager::logoff" />), which releases
12708 all objects created during the webservice session.
12709
12710 Whenever a method call of the VirtualBox API returns a COM object, the
12711 webservice representation of that method will instead return a
12712 managed object reference, which can then be used to invoke methods
12713 on that object.
12714 </desc>
12715
12716 <method name="getInterfaceName">
12717 <desc>
12718 Returns the name of the interface that this managed object represents,
12719 for example, "IMachine", as a string.
12720 </desc>
12721 <param name="return" type="wstring" dir="return"/>
12722 </method>
12723
12724 <method name="release">
12725 <desc>
12726 Releases this managed object reference and frees the resources that
12727 were allocated for it in the webservice server process. After calling
12728 this method, the identifier of the reference can no longer be used.
12729 </desc>
12730 </method>
12731
12732 </interface>
12733
12734 <!--
12735 // IWebsessionManager
12736 /////////////////////////////////////////////////////////////////////////
12737 -->
12738
12739 <interface
12740 name="IWebsessionManager" extends="$unknown"
12741 uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
12742 internal="yes"
12743 wsmap="global"
12744 wscpp="hardcoded"
12745 >
12746 <desc>
12747 Websession manager. This provides essential services
12748 to webservice clients.
12749 </desc>
12750 <method name="logon">
12751 <desc>
12752 Logs a new client onto the webservice and returns a managed object reference to
12753 the IVirtualBox instance, which the client can then use as a basis to further
12754 queries, since all calls to the VirtualBox API are based on the IVirtualBox
12755 interface, in one way or the other.
12756 </desc>
12757 <param name="username" type="wstring" dir="in"/>
12758 <param name="password" type="wstring" dir="in"/>
12759 <param name="return" type="IVirtualBox" dir="return"/>
12760 </method>
12761
12762 <method name="getSessionObject">
12763 <desc>
12764 Returns a managed object reference to the internal ISession object that was created
12765 for this web service session when the client logged on.
12766
12767 <see>ISession</see>
12768 </desc>
12769 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12770 <param name="return" type="ISession" dir="return"/>
12771 </method>
12772
12773 <method name="logoff">
12774 <desc>
12775 Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
12776 and destroys all resources associated with the session (most importantly, all
12777 managed objects created in the server while the session was active).
12778 </desc>
12779 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
12780 </method>
12781
12782 </interface>
12783
12784</if>
12785
12786 <!--
12787 // IPerformanceCollector & friends
12788 /////////////////////////////////////////////////////////////////////////
12789 -->
12790
12791 <interface
12792 name="IPerformanceMetric" extends="$unknown"
12793 uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
12794 >
12795 <desc>
12796 The IPerformanceMetric interface represents parameters of the given
12797 performance metric.
12798 </desc>
12799
12800 <attribute name="metricName" type="wstring" readonly="yes">
12801 <desc>
12802 Name of the metric.
12803 </desc>
12804 </attribute>
12805
12806 <attribute name="object" type="$unknown" readonly="yes">
12807 <desc>
12808 Object this metric belongs to.
12809 </desc>
12810 </attribute>
12811
12812 <attribute name="description" type="wstring" readonly="yes">
12813 <desc>
12814 Textual description of the metric.
12815 </desc>
12816 </attribute>
12817
12818 <attribute name="period" type="unsigned long" readonly="yes">
12819 <desc>
12820 Time interval between samples, measured in seconds.
12821 </desc>
12822 </attribute>
12823
12824 <attribute name="count" type="unsigned long" readonly="yes">
12825 <desc>
12826 Number of recent samples retained by the performance collector for this
12827 metric.
12828
12829 When the collected sample count exceeds this number, older samples
12830 are discarded.
12831 </desc>
12832 </attribute>
12833
12834 <attribute name="unit" type="wstring" readonly="yes">
12835 <desc>
12836 Unit of measurement.
12837 </desc>
12838 </attribute>
12839
12840 <attribute name="minimumValue" type="long" readonly="yes">
12841 <desc>
12842 Minimum possible value of this metric.
12843 </desc>
12844 </attribute>
12845
12846 <attribute name="maximumValue" type="long" readonly="yes">
12847 <desc>
12848 Maximum possible value of this metric.
12849 </desc>
12850 </attribute>
12851 </interface>
12852
12853 <interface
12854 name="IPerformanceCollector" extends="$unknown"
12855 uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
12856 wsmap="managed"
12857 >
12858 <desc>
12859 The IPerformanceCollector interface represents a service that collects and
12860 stores performance metrics data.
12861
12862 Performance metrics are associated with objects like IHost and
12863 IMachine. Each object has a distinct set of performance metrics.
12864 The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
12865
12866 Metric data are collected at the specified intervals and are retained
12867 internally. The interval and the number of samples retained can be set
12868 with <link to="IPerformanceCollector::setupMetrics" />.
12869
12870 Metrics are organized hierarchically, each level separated by slash (/).
12871 General scheme for metric name is
12872 "Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
12873 metric name stands for: CPU category, Load metric, User submetric, average
12874 aggregate. An aggregate function is computed over all retained data. Valid
12875 aggregate functions are:
12876
12877 <ul>
12878 <li>avg -- average</li>
12879 <li>min -- minimum</li>
12880 <li>max -- maximum</li>
12881 </ul>
12882
12883 "Category/Metric" together form base metric name. A base metric is the
12884 smallest unit for which a sampling interval and the number of retained
12885 samples can be set. Only base metrics can be enabled and disabled. All
12886 sub-metrics are collected when their base metric is collected.
12887 Collected values for any set of sub-metrics can be queried with
12888 <link to="IPerformanceCollector::queryMetricsData" />. When setting up
12889 metric parameters, querying metric data, enabling or disabling metrics
12890 wildcards can be used in metric names to specify a subset of metrics. For
12891 example, to select all CPU-related metrics use <tt>CPU/*</tt>, all
12892 averages can be queried using <tt>*:avg</tt> and so on. To query metric
12893 values without aggregates <tt>*:</tt> can be used.
12894
12895 The valid names for base metrics are:
12896
12897 <ul>
12898 <li>CPU/Load</li>
12899 <li>CPU/MHz</li>
12900 <li>RAM/Usage</li>
12901 </ul>
12902
12903 The general sequence for collecting and retrieving the metrics is:
12904 <ul>
12905 <li>
12906 Obtain an instance of IPerformanceCollector with
12907 <link to="IVirtualBox::performanceCollector" />
12908 </li>
12909 <li>
12910 Allocate and populate an array with references to objects the metrics
12911 will be collected for. Use references to IHost and IMachine objects.
12912 </li>
12913 <li>
12914 Allocate and populate an array with base metric names the data will be
12915 collected for.
12916 </li>
12917 <li>
12918 Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
12919 metric data will be collected and stored.
12920 </li>
12921 <li>
12922 Wait for the data to get collected.
12923 </li>
12924 <li>
12925 Allocate and populate an array with references to objects the metric
12926 values will be queried for. You can re-use the object array used for
12927 setting base metrics.
12928 </li>
12929 <li>
12930 Allocate and populate an array with metric names the data will be
12931 collected for. Note that metric names differ from base metric names.
12932 </li>
12933 <li>
12934 Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
12935 have been collected so far are returned. Note that the values are still
12936 retained internally and data collection continues.
12937 </li>
12938 </ul>
12939
12940 For an example of usage refer to the following files in VirtualBox SDK:
12941 <ul>
12942 <li>
12943 Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
12944 </li>
12945 <li>
12946 Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
12947 </li>
12948 </ul>
12949 </desc>
12950
12951 <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
12952 <desc>
12953 Array of unique names of metrics.
12954
12955 This array represents all metrics supported by the performance
12956 collector. Individual objects do not necessarily support all of them.
12957 <link to="IPerformanceCollector::getMetrics"/> can be used to get the
12958 list of supported metrics for a particular object.
12959 </desc>
12960 </attribute>
12961
12962 <method name="getMetrics">
12963 <desc>
12964 Returns parameters of specified metrics for a set of objects.
12965 <note>
12966 @c Null metrics array means all metrics. @c Null object array means
12967 all existing objects.
12968 </note>
12969 </desc>
12970 <param name="metricNames" type="wstring" dir="in" safearray="yes">
12971 <desc>
12972 Metric name filter. Currently, only a comma-separated list of metrics
12973 is supported.
12974 </desc>
12975 </param>
12976 <param name="objects" type="$unknown" dir="in" safearray="yes">
12977 <desc>
12978 Set of objects to return metric parameters for.
12979 </desc>
12980 </param>
12981 <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
12982 <desc>
12983 Array of returned metric parameters.
12984 </desc>
12985 </param>
12986 </method>
12987
12988 <method name="setupMetrics">
12989 <desc>
12990 Sets parameters of specified base metrics for a set of objects. Returns
12991 an array of <link to="IPerformanceMetric" /> describing the metrics have
12992 been affected.
12993 <note>
12994 @c Null or empty metric name array means all metrics. @c Null or empty
12995 object array means all existing objects. If metric name array contains
12996 a single element and object array contains many, the single metric
12997 name array element is applied to each object array element to form
12998 metric/object pairs.
12999 </note>
13000 </desc>
13001 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13002 <desc>
13003 Metric name filter. Comma-separated list of metrics with wildcard
13004 support.
13005 </desc>
13006 </param>
13007 <param name="objects" type="$unknown" dir="in" safearray="yes">
13008 <desc>
13009 Set of objects to setup metric parameters for.
13010 </desc>
13011 </param>
13012 <param name="period" type="unsigned long" dir="in">
13013 <desc>
13014 Time interval in seconds between two consecutive samples of performance
13015 data.
13016 </desc>
13017 </param>
13018 <param name="count" type="unsigned long" dir="in">
13019 <desc>
13020 Number of samples to retain in performance data history. Older samples
13021 get discarded.
13022 </desc>
13023 </param>
13024 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13025 <desc>
13026 Array of metrics that have been modified by the call to this method.
13027 </desc>
13028 </param>
13029 </method>
13030
13031 <method name="enableMetrics">
13032 <desc>
13033 Turns on collecting specified base metrics. Returns an array of
13034 <link to="IPerformanceMetric" /> describing the metrics have been
13035 affected.
13036 <note>
13037 @c Null or empty metric name array means all metrics. @c Null or empty
13038 object array means all existing objects. If metric name array contains
13039 a single element and object array contains many, the single metric
13040 name array element is applied to each object array element to form
13041 metric/object pairs.
13042 </note>
13043 </desc>
13044 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13045 <desc>
13046 Metric name filter. Comma-separated list of metrics with wildcard
13047 support.
13048 </desc>
13049 </param>
13050 <param name="objects" type="$unknown" dir="in" safearray="yes">
13051 <desc>
13052 Set of objects to enable metrics for.
13053 </desc>
13054 </param>
13055 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13056 <desc>
13057 Array of metrics that have been modified by the call to this method.
13058 </desc>
13059 </param>
13060 </method>
13061
13062 <method name="disableMetrics">
13063 <desc>
13064 Turns off collecting specified base metrics. Returns an array of
13065 <link to="IPerformanceMetric" /> describing the metrics have been
13066 affected.
13067 <note>
13068 @c Null or empty metric name array means all metrics. @c Null or empty
13069 object array means all existing objects. If metric name array contains
13070 a single element and object array contains many, the single metric
13071 name array element is applied to each object array element to form
13072 metric/object pairs.
13073 </note>
13074 </desc>
13075 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13076 <desc>
13077 Metric name filter. Comma-separated list of metrics with wildcard
13078 support.
13079 </desc>
13080 </param>
13081 <param name="objects" type="$unknown" dir="in" safearray="yes">
13082 <desc>
13083 Set of objects to disable metrics for.
13084 </desc>
13085 </param>
13086 <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
13087 <desc>
13088 Array of metrics that have been modified by the call to this method.
13089 </desc>
13090 </param>
13091 </method>
13092
13093 <method name="queryMetricsData">
13094 <desc>
13095 Queries collected metrics data for a set of objects.
13096
13097 The data itself and related metric information are returned in seven
13098 parallel and one flattened array of arrays. Elements of
13099 <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
13100 returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
13101 the same index describe one set of values corresponding to a single
13102 metric.
13103
13104 The <tt>returnData</tt> parameter is a flattened array of arrays. Each
13105 start and length of a sub-array is indicated by
13106 <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
13107 value for metric <tt>metricNames[i]</tt> is at
13108 <tt>returnData[returnIndices[i]]</tt>.
13109
13110 <note>
13111 @c Null or empty metric name array means all metrics. @c Null or empty
13112 object array means all existing objects. If metric name array contains
13113 a single element and object array contains many, the single metric
13114 name array element is applied to each object array element to form
13115 metric/object pairs.
13116 </note>
13117 <note>
13118 Data collection continues behind the scenes after call to
13119 @c queryMetricsData. The return data can be seen as the snapshot of
13120 the current state at the time of @c queryMetricsData call. The
13121 internally kept metric values are not cleared by the call. This makes
13122 possible querying different subsets of metrics or aggregates with
13123 subsequent calls. If periodic querying is needed it is highly
13124 suggested to query the values with @c interval*count period to avoid
13125 confusion. This way a completely new set of data values will be
13126 provided by each query.
13127 </note>
13128 </desc>
13129 <param name="metricNames" type="wstring" dir="in" safearray="yes">
13130 <desc>
13131 Metric name filter. Comma-separated list of metrics with wildcard
13132 support.
13133 </desc>
13134 </param>
13135 <param name="objects" type="$unknown" dir="in" safearray="yes">
13136 <desc>
13137 Set of objects to query metrics for.
13138 </desc>
13139 </param>
13140 <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
13141 <desc>
13142 Names of metrics returned in @c returnData.
13143 </desc>
13144 </param>
13145 <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
13146 <desc>
13147 Objects associated with metrics returned in @c returnData.
13148 </desc>
13149 </param>
13150 <param name="returnUnits" type="wstring" dir="out" safearray="yes">
13151 <desc>
13152 Units of measurement for each returned metric.
13153 </desc>
13154 </param>
13155 <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
13156 <desc>
13157 Divisor that should be applied to return values in order to get
13158 floating point values. For example:
13159 <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
13160 will retrieve the floating point value of i-th sample of the first
13161 metric.
13162 </desc>
13163 </param>
13164 <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
13165 <desc>
13166 Sequence numbers of the first elements of value sequences of particular metrics
13167 returned in @c returnData. For aggregate metrics it is the sequence number of
13168 the sample the aggregate started calculation from.
13169 </desc>
13170 </param>
13171 <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
13172 <desc>
13173 Indices of the first elements of value sequences of particular metrics
13174 returned in @c returnData.
13175 </desc>
13176 </param>
13177 <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
13178 <desc>
13179 Lengths of value sequences of particular metrics.
13180 </desc>
13181 </param>
13182 <param name="returnData" type="long" dir="return" safearray="yes">
13183 <desc>
13184 Flattened array of all metric data containing sequences of values for
13185 each metric.
13186 </desc>
13187 </param>
13188 </method>
13189
13190 </interface>
13191
13192 <module name="VBoxSVC" context="LocalServer">
13193 <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
13194 namespace="virtualbox.org">
13195 <interface name="IVirtualBox" default="yes"/>
13196 </class>
13197 </module>
13198
13199 <module name="VBoxC" context="InprocServer" threadingModel="Free">
13200 <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
13201 namespace="virtualbox.org">
13202 <interface name="ISession" default="yes"/>
13203 </class>
13204 </module>
13205
13206</library>
13207
13208</idl>
13209
13210<!-- 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