VirtualBox

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

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

fixed problem with setting BIOS parameters

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 379.9 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/Frontends/VirtualBox4/include/COMWrappers.xsl =>
41 * out/<platform>/obj/src/VBox/Frontends/VirtualBox4/VirtualBox/include/COMWrappers.h
42 * (smart Qt-based C++ wrapper classes for COM interfaces
43 * of the Main API)
44 *
45 * 7. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
46 * out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
47 * (Main API TypeLib block for the WiX installer)
48 *
49 Copyright (C) 2006-2007 Sun Microsystems, Inc.
50
51 This file is part of VirtualBox Open Source Edition (OSE), as
52 available from http://www.virtualbox.org. This file is free software;
53 you can redistribute it and/or modify it under the terms of the GNU
54 General Public License (GPL) as published by the Free Software
55 Foundation, in version 2 as it comes in the "COPYING" file of the
56 VirtualBox OSE distribution. VirtualBox OSE is distributed in the
57 hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
58
59 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
60 Clara, CA 95054 USA or visit http://www.sun.com if you need
61 additional information or have any questions.
62-->
63
64<idl>
65
66<if target="midl">
67 <cpp line="enum {"/>
68 <cpp line=" kTypeLibraryMajorVersion = 1,"/>
69 <cpp line=" kTypeLibraryMinorVersion = 0"/>
70 <cpp line="};"/>
71</if>
72
73<if target="xpidl">
74 <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
75 <cpp>
76// currenty, nsISupportsImpl.h lacks the below-like macros
77#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
78#define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
79 NS_IMPL_THREADSAFE_ADDREF(_class) \
80 NS_IMPL_THREADSAFE_RELEASE(_class) \
81 NS_IMPL_QUERY_INTERFACE1_CI(_class, _interface) \
82 NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
83#endif
84#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
85#define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
86 NS_IMPL_THREADSAFE_ADDREF(_class) \
87 NS_IMPL_THREADSAFE_RELEASE(_class) \
88 NS_IMPL_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
89 NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
90#endif
91 </cpp>
92</if>
93
94<library
95 name="VirtualBox"
96 uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
97 version="1.3"
98 desc="VirtualBox Type Library"
99 appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
100 supportsErrorInfo="yes"
101>
102
103 <!--
104 // all common enums
105 /////////////////////////////////////////////////////////////////////////
106 -->
107
108 <enum
109 name="TSBool"
110 uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
111 >
112 <desc>
113 Boolean variable having a third state, default.
114 </desc>
115
116 <const name="False" value="0"/>
117 <const name="True" value="1"/>
118 <const name="Default" value="2"/>
119 </enum>
120
121 <enum
122 name="MachineState"
123 uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
124 >
125 <desc>
126 Virtual machine execution state. This enumeration represents possible
127 values of the <link to="IMachine::state"/> attribute.
128 </desc>
129
130 <const name="Null" value="0">
131 <desc><tt>null</tt> value. Never used by the API.</desc>
132 </const>
133 <const name="PoweredOff" value="1">
134 <desc>
135 The machine is not running.
136 </desc>
137 </const>
138 <const name="Saved" value="2">
139 <desc>
140 The machine is not currently running, but the execution state
141 of the machine has been saved to an external file when it
142 was running.
143 <note>
144 No any machine settings can be altered when the machine
145 is in this state.
146 </note>
147 </desc>
148 </const>
149 <const name="Aborted" value="3">
150 <desc>
151 A process that run the machine has abnormally terminated.
152 Other than that, this value is equivalent to #PoweredOff.
153 </desc>
154 </const>
155 <const name="Running" value="4">
156 <desc>
157 The machine is currently being executed.
158 <note>
159 This value can be used in comparison expressions:
160 all state values below it describe a virtual machine that is
161 not currently being executed (i.e., it is completely out of
162 action).
163 </note>
164 <note internal="yes">
165 For whoever decides to touch this enum: In order to keep the
166 aforementioned comparisons valid, this state must immediately
167 preceed the Paused state.
168 </note>
169 </desc>
170 </const>
171 <const name="Paused" value="5">
172 <desc>
173 The execution of the machine has been paused.
174 <note>
175 This value can be used in comparison expressions: all state values
176 above it represent unstable states of the running virtual
177 machine. Unless explicitly stated otherwise, no machine settings can
178 be altered when it is in one of the unstable states.
179 </note>
180 <note internal="yes">
181 For whoever decides to touch this enum: In order to keep the
182 aforementioned comparisons valid, this state must immediately
183 follow the Running state.
184 </note>
185 </desc>
186 </const>
187 <const name="Stuck" value="6">
188 <desc>
189 The execution of the machine has reached the "Guru Meditation"
190 condition. This condition indicates an internal VMM failure which may
191 happen as a result of either an unhandled low-level virtual hardware
192 exception or one of the recompiler exceptions (such as
193 the <i>too-many-traps</i> condition).
194 </desc>
195 </const>
196 <const name="Starting" value="7">
197 <desc>
198 The machine is being started after
199 <link to="IConsole::powerUp">powering it on</link> from a
200 zero execution state.
201 </desc>
202 </const>
203 <const name="Stopping" value="8">
204 <desc>
205 The machine is being normally stopped
206 (after explicitly <link to="IConsole::powerDown">powering it off</link>,
207 or after the guest OS has initiated a shutdown sequence).
208 </desc>
209 </const>
210 <const name="Saving" value="9">
211 <desc>
212 The machine is saving its execution state to a file as a
213 result of calling <link to="IConsole::saveState"/> or an online
214 snapshot of the machine is being taken using
215 <link to="IConsole::takeSnapshot"/>.
216 </desc>
217 </const>
218 <const name="Restoring" value="10">
219 <desc>
220 The execution state of the machine is being restored from a file
221 after <link to="IConsole::powerUp">powering it on</link> from
222 a saved execution state.
223 </desc>
224 </const>
225 <const name="Discarding" value="11">
226 <desc>
227 A snapshot of the machine is being discarded after calling
228 <link to="IConsole::discardSnapshot"/> or its current state is
229 being discarded after <link to="IConsole::discardCurrentState"/>.
230 </desc>
231 </const>
232 </enum>
233
234 <enum
235 name="SessionState"
236 uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
237 >
238 <desc>
239 Session state. This enumeration represents possible values of
240 <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
241 attributes. Idividual value descriptions contain the appropriate
242 meaning for every case.
243 </desc>
244
245 <const name="Null" value="0">
246 <desc><tt>null</tt> value. Never used by the API.</desc>
247 </const>
248 <const name="Closed" value="1">
249 <desc>
250 The machine has no open sessions (<link to="IMachine::sessionState"/>);
251 the session is closed (<link to="ISession::state"/>)
252 </desc>
253 </const>
254 <const name="Open" value="2">
255 <desc>
256 The machine has an open direct session (<link to="IMachine::sessionState"/>);
257 the session is open (<link to="ISession::state"/>)
258 </desc>
259 </const>
260 <const name="Spawning" value="3">
261 <desc>
262 A new (direct) session is being opened for the machine
263 as a result of <link to="IVirtualBox::openRemoteSession()"/>
264 call (<link to="IMachine::sessionState"/>);
265 the session is currently being opened
266 as a result of <link to="IVirtualBox::openRemoteSession()"/>
267 call (<link to="ISession::state"/>)
268 </desc>
269 </const>
270 <const name="Closing" value="4">
271 <desc>
272 The direct session is being closed (<link to="IMachine::sessionState"/>);
273 the session is being closed (<link to="ISession::state"/>)
274 </desc>
275 </const>
276 </enum>
277
278 <enum
279 name="SessionType"
280 uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
281 >
282 <desc>
283 Session type. This enumeration represents possible values of the
284 <link to="ISession::type"/> attribute.
285 </desc>
286
287 <const name="Null" value="0">
288 <desc><tt>null</tt> value. Never used by the API.</desc>
289 </const>
290 <const name="Direct" value="1">
291 <desc>
292 Direct session
293 (opened by <link to="IVirtualBox::openSession()"/>)
294 </desc>
295 </const>
296 <const name="Remote" value="2">
297 <desc>
298 Remote session
299 (opened by <link to="IVirtualBox::openRemoteSession()"/>)
300 </desc>
301 </const>
302 <const name="Existing" value="3">
303 <desc>
304 Existing session
305 (opened by <link to="IVirtualBox::openExistingSession()"/>)
306 </desc>
307 </const>
308 </enum>
309
310 <enum
311 name="DeviceType"
312 uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
313 >
314 <desc>
315 Device type.
316 </desc>
317 <const name="Null" value="0">
318 <desc>
319 <tt>null</tt> value which may also mean "no device".
320 <note>
321 This value is not allowed for
322 <link to="IConsole::getDeviceActivity"/>
323 </note>
324 </desc>
325 </const>
326 <const name="Floppy" value="1">
327 <desc>Floppy device.</desc>
328 </const>
329 <const name="DVD" value="2">
330 <desc>CD/DVD-ROM device.</desc>
331 </const>
332 <const name="HardDisk" value="3">
333 <desc>Hard disk device.</desc>
334 </const>
335 <const name="Network" value="4">
336 <desc>Network device.</desc>
337 </const>
338 <const name="USB" value="5">
339 <desc>USB device.</desc>
340 </const>
341 <const name="SharedFolder" value="6">
342 <desc>Shared folder device.</desc>
343 </const>
344 </enum>
345
346 <enum
347 name="DeviceActivity"
348 uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
349 >
350 <desc>
351 Device activity for <link to="IConsole::getDeviceActivity"/>.
352 </desc>
353
354 <const name="Null" value="0"/>
355 <const name="Idle" value="1"/>
356 <const name="Reading" value="2"/>
357 <const name="Writing" value="3"/>
358 </enum>
359
360 <enum
361 name="ResourceUsage"
362 uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
363 >
364 <desc>
365 Usage type constants for
366 <link to="IVirtualBox::getDVDImageUsage"/> and
367 <link to="IVirtualBox::getFloppyImageUsage"/>.
368 </desc>
369
370 <const name="Null" value="0">
371 <desc><tt>null</tt> value. Never used by the API.</desc>
372 </const>
373 <const name="Permanent" value="1">
374 <desc>
375 Scopes the VMs that use the resource permanently
376 (the information about this usage is stored in the VM
377 settings file).
378 </desc>
379 </const>
380 <const name="Temporary" value="2">
381 <desc>
382 Scopes the VMs that are temporarily using the resource
383 (the information about the usage is not yet saved in the VM
384 settings file). Temporary usage can take place only in the
385 context of an open session.
386 </desc>
387 </const>
388 <const name="All" value="3">
389 <desc>
390 Combines Permanent and Temporary.
391 </desc>
392 </const>
393 </enum>
394
395 <enum
396 name="StorageBus"
397 uuid="715984a5-093c-43bb-aa42-a16ed16828dd"
398 >
399 <desc>Interface bus type for storage devices.</desc>
400
401 <const name="Null" value="0">
402 <desc><tt>null</tt> value. Never used by the API.</desc>
403 </const>
404
405 <const name="IDE" value="1"/>
406 <const name="SATA" value="2"/>
407 </enum>
408
409 <enum
410 name="ClipboardMode"
411 uuid="33364716-4008-4701-8f14-be0fa3d62950"
412 >
413 <desc>
414 Host-Guest clipboard interchange mode.
415 </desc>
416
417 <const name="Disabled" value="0"/>
418 <const name="HostToGuest" value="1"/>
419 <const name="GuestToHost" value="2"/>
420 <const name="Bidirectional" value="3"/>
421 </enum>
422
423 <enum
424 name="Scope"
425 uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
426 >
427 <desc>
428 Scope of the operation.
429
430 A generic enumeration used in various methods to define the action or
431 argument scope.
432 </desc>
433
434 <const name="Global" value="0"/>
435 <const name="Machine" value="1"/>
436 <const name="Session" value="2"/>
437 </enum>
438
439 <enum
440 name="GuestStatisticType"
441 uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
442 >
443 <desc>
444 Statistics type for <link to="IGuest::getStatistic"/>.
445 </desc>
446
447 <const name="CPULoad_Idle" value="0">
448 <desc>
449 Idle CPU load (0-100%) for last interval.
450 </desc>
451 </const>
452 <const name="CPULoad_Kernel" value="1">
453 <desc>
454 Kernel CPU load (0-100%) for last interval.
455 </desc>
456 </const>
457 <const name="CPULoad_User" value="2">
458 <desc>
459 User CPU load (0-100%) for last interval.
460 </desc>
461 </const>
462 <const name="Threads" value="3">
463 <desc>
464 Total number of threads in the system.
465 </desc>
466 </const>
467 <const name="Processes" value="4">
468 <desc>
469 Total number of processes in the system.
470 </desc>
471 </const>
472 <const name="Handles" value="5">
473 <desc>
474 Total number of handles in the system.
475 </desc>
476 </const>
477 <const name="MemoryLoad" value="6">
478 <desc>
479 Memory load (0-100%).
480 </desc>
481 </const>
482 <const name="PhysMemTotal" value="7">
483 <desc>
484 Total physical memory in megabytes.
485 </desc>
486 </const>
487 <const name="PhysMemAvailable" value="8">
488 <desc>
489 Free physical memory in megabytes.
490 </desc>
491 </const>
492 <const name="PhysMemBalloon" value="9">
493 <desc>
494 Ballooned physical memory in megabytes.
495 </desc>
496 </const>
497 <const name="MemCommitTotal" value="10">
498 <desc>
499 Total amount of memory in the committed state in megabytes.
500 </desc>
501 </const>
502 <const name="MemKernelTotal" value="11">
503 <desc>
504 Total amount of memory used by the guest OS's kernel in megabytes.
505 </desc>
506 </const>
507 <const name="MemKernelPaged" value="12">
508 <desc>
509 Total amount of paged memory used by the guest OS's kernel in megabytes.
510 </desc>
511 </const>
512 <const name="MemKernelNonpaged" value="13">
513 <desc>
514 Total amount of nonpaged memory used by the guest OS's kernel in megabytes.
515 </desc>
516 </const>
517 <const name="MemSystemCache" value="14">
518 <desc>
519 Total amount of memory used by the guest OS's system cache in megabytes.
520 </desc>
521 </const>
522 <const name="PageFileSize" value="15">
523 <desc>
524 Pagefile size in megabytes.
525 </desc>
526 </const>
527 <const name="SampleNumber" value="16">
528 <desc>
529 Statistics sample number
530 </desc>
531 </const>
532 <const name="MaxVal" value="17"/>
533 </enum>
534
535 <enum
536 name="BIOSBootMenuMode"
537 uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
538 >
539 <desc>
540 BIOS boot menu mode.
541 </desc>
542
543 <const name="Disabled" value="0"/>
544 <const name="MenuOnly" value="1"/>
545 <const name="MessageAndMenu" value="2"/>
546 </enum>
547
548 <enum
549 name="IDEControllerType"
550 uuid="445330e3-202a-4dab-854f-ce22e6cb9715"
551 >
552 <desc>
553 IDE controller type.
554 </desc>
555
556 <const name="Null" value="0">
557 <desc><tt>null</tt> value. Never used by the API.</desc>
558 </const>
559 <const name="PIIX3" value="1"/>
560 <const name="PIIX4" value="2"/>
561 </enum>
562
563 <enum
564 name="DriveState"
565 uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
566 >
567 <const name="Null" value="0">
568 <desc><tt>null</tt> value. Never used by the API.</desc>
569 </const>
570 <const name="NotMounted" value="1"/>
571 <const name="ImageMounted" value="2"/>
572 <const name="HostDriveCaptured" value="3"/>
573 </enum>
574
575 <!--
576 // IVirtualBoxErrorInfo
577 /////////////////////////////////////////////////////////////////////////
578 -->
579
580 <interface
581 name="IVirtualBoxErrorInfo" extends="$errorinfo"
582 uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
583 supportsErrorInfo="no"
584 wsmap="suppress"
585 >
586 <desc>
587 The IVirtualBoxErrorInfo interface represents extended error information.
588
589 Extended error information can be set by VirtualBox components after
590 unsuccessful or partially successful method invocation. This information
591 can be retrievefd by the calling party as an IVirtualBoxErrorInfo object
592 and then shown to the client in addition to the plain 32-bit result code.
593
594 In MS COM, this interface extends the IErrorInfo interface,
595 in XPCOM, it extends the nsIException interface. In both cases,
596 it provides a set of common attributes to retrieve error
597 information.
598
599 Sometimes invocation of some component's method may involve methods of
600 other components that may also fail (independently of this method's
601 failure), or a series of non-fatal errors may precede a fatal error that
602 causes method failure. In cases like that, it may be desirable to preserve
603 information about all errors happened during method invocation and deliver
604 it to the caller. The <link to="#next"/> attribute is intended
605 specifically for this purpose and allows to represent a chain of errors
606 through a single IVirtualBoxErrorInfo object set after method invocation.
607
608 Note that errors are stored to a chain in the reverse order, i.e. the
609 initial error object you query right after method invocation is the last
610 error set by the callee, the object it points to in the @a next attribute
611 is the previous error and so on, up to the first error (which is the last
612 in the chain).
613 </desc>
614
615 <attribute name="resultCode" type="result" readonly="yes">
616 <desc>
617 Result code of the error.
618 Usually, it will be the same as the result code returned
619 by the method that provided this error information, but not
620 always. For example, on Win32, CoCreateInstance() will most
621 likely return E_NOINTERFACE upon unsuccessful component
622 instantiation attempt, but not the value the component factory
623 returned.
624 <note>
625 In MS COM, there is no equivalent.
626 In XPCOM, it is the same as nsIException::result.
627 </note>
628 </desc>
629 </attribute>
630
631 <attribute name="interfaceID" type="uuid" readonly="yes">
632 <desc>
633 UUID of the interface that defined the error.
634 <note>
635 In MS COM, it is the same as IErrorInfo::GetGUID.
636 In XPCOM, there is no equivalent.
637 </note>
638 </desc>
639 </attribute>
640
641 <attribute name="component" type="wstring" readonly="yes">
642 <desc>
643 Name of the component that generated the error.
644 <note>
645 In MS COM, it is the same as IErrorInfo::GetSource.
646 In XPCOM, there is no equivalent.
647 </note>
648 </desc>
649 </attribute>
650
651 <attribute name="text" type="wstring" readonly="yes">
652 <desc>
653 Text description of the error.
654 <note>
655 In MS COM, it is the same as IErrorInfo::GetDescription.
656 In XPCOM, it is the same as nsIException::message.
657 </note>
658 </desc>
659 </attribute>
660
661 <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
662 <desc>
663 Next error object if there is any, or @c null otherwise.
664 <note>
665 In MS COM, there is no equivalent.
666 In XPCOM, it is the same as nsIException::inner.
667 </note>
668 </desc>
669 </attribute>
670
671 </interface>
672
673
674 <!--
675 // IVirtualBox
676 /////////////////////////////////////////////////////////////////////////
677 -->
678
679 <interface
680 name="IVirtualBoxCallback" extends="$unknown"
681 uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
682 wsmap="suppress"
683 >
684 <method name="onMachineStateChange">
685 <desc>
686 The execution state of the given machine has changed.
687 <see>IMachine::state</see>
688 </desc>
689 <param name="machineId" type="uuid" dir="in">
690 <desc>ID of the machine this event relates to.</desc>
691 </param>
692 <param name="state" type="MachineState" dir="in">
693 <desc>New execution state.</desc>
694 </param>
695 </method>
696
697 <method name="onMachineDataChange">
698 <desc>
699 Any of the settings of the given machine has changed.
700 </desc>
701 <param name="machineId" type="uuid" dir="in">
702 <desc>ID of the machine this event relates to.</desc>
703 </param>
704 </method>
705
706 <method name="onExtraDataCanChange">
707 <desc>
708 Notification when someone tries to change extra data for
709 either the given machine or (if null) global extra data.
710 This gives the chance to veto against changes.
711 </desc>
712 <param name="machineId" type="uuid" dir="in">
713 <desc>
714 ID of the machine this event relates to
715 (null ID for global extra data change requests).
716 </desc>
717 </param>
718 <param name="key" type="wstring" dir="in">
719 <desc>
720 Extra data key for the attempted write.
721 </desc>
722 </param>
723 <param name="value" type="wstring" dir="in">
724 <desc>
725 Extra data value for the given key.
726 </desc>
727 </param>
728 <param name="error" type="wstring" dir="out">
729 <desc>
730 Optional error message describing the reason of the
731 veto (ignored if this notification returns @c true).
732 </desc>
733 </param>
734 <param name="allowChange" type="boolean" dir="return">
735 <desc>
736 Flag to indicate whether the callee agrees (@ true)
737 or vetoes against the change (@ false).
738 </desc>
739 </param>
740 </method>
741
742 <method name="onExtraDataChange">
743 <desc>
744 Notification when machine specific or global extra data
745 has changed.
746 </desc>
747 <param name="machineId" type="uuid" dir="in">
748 <desc>
749 ID of the machine this event relates to.
750 Null for global extra data changes.
751 </desc>
752 </param>
753 <param name="key" type="wstring" dir="in">
754 <desc>
755 Extra data key that has changed.
756 </desc>
757 </param>
758 <param name="value" type="wstring" dir="in">
759 <desc>
760 Extra data value for the given key.
761 </desc>
762 </param>
763 </method>
764
765 <method name="onMediaRegistered">
766 <desc>
767 The given media was registered or unregistered
768 within this VirtualBox installation.
769
770 The @a mediaType parameter describes what type of
771 media the specified @a mediaId refers to. Possible
772 values are:
773
774 <ul>
775 <li><link to="DeviceType::HardDisk"/>: the media is a hard disk
776 that, if registered, can be obtained using the
777 <link to="IVirtualBox::getHardDisk"/> call.</li>
778 <li><link to="DeviceType::DVD"/>: the media is a CD/DVD image
779 that, if registered, can be obtained using the
780 <link to="IVirtualBox::getDVDImage"/> call.</li>
781 <li><link to="DeviceType::Floppy"/>: the media is a Floppy image
782 that, if registered, can be obtained using the
783 <link to="IVirtualBox::getFloppyImage"/> call.</li>
784 </ul>
785
786 Note that if this is a deregistration notification,
787 there is no way to access the object representing the
788 unregistered media. It is supposed that the
789 application will do required cleanup based on the @a
790 mediaId value.
791 </desc>
792 <param name="mediaId" type="uuid" dir="in">
793 <desc>ID of the media this event relates to.</desc>
794 </param>
795 <param name="mediaType" type="DeviceType" dir="in">
796 <desc>Type of the media this event relates to.</desc>
797 </param>
798 <param name="registered" type="boolean" dir="in">
799 <desc>
800 If true, the media was registered, otherwise it was
801 unregistered.
802 </desc>
803 </param>
804 </method>
805
806 <method name="onMachineRegistered">
807 <desc>
808 The given machine was registered or unregistered
809 within this VirtualBox installation.
810 </desc>
811 <param name="machineId" type="uuid" dir="in">
812 <desc>ID of the machine this event relates to.</desc>
813 </param>
814 <param name="registered" type="boolean" dir="in">
815 <desc>
816 If true, the machine was registered, otherwise it was
817 unregistered.
818 </desc>
819 </param>
820 </method>
821
822 <method name="onSessionStateChange">
823 <desc>
824 The state of the session for the given machine was changed.
825 <see>IMachine::sessionState</see>
826 </desc>
827 <param name="machineId" type="uuid" dir="in">
828 <desc>ID of the machine this event relates to.</desc>
829 </param>
830 <param name="state" type="SessionState" dir="in">
831 <desc>New session state.</desc>
832 </param>
833 </method>
834
835 <method name="onSnapshotTaken">
836 <desc>
837 A new snapshot of the machine has been taken.
838 <see>ISnapshot</see>
839 </desc>
840 <param name="machineId" type="uuid" dir="in">
841 <desc>ID of the machine this event relates to.</desc>
842 </param>
843 <param name="snapshotId" type="uuid" dir="in">
844 <desc>ID of the new snapshot.</desc>
845 </param>
846 </method>
847
848 <method name="onSnapshotDiscarded">
849 <desc>
850 Snapshot of the given machine has been discarded.
851
852 <note>
853 This notification is delivered <b>after</b> the snapshot
854 object has been uninitialized on the server (so that any
855 attempt to call its methods will return an error).
856 </note>
857
858 <see>ISnapshot</see>
859 </desc>
860 <param name="machineId" type="uuid" dir="in">
861 <desc>ID of the machine this event relates to.</desc>
862 </param>
863 <param name="snapshotId" type="uuid" dir="in">
864 <desc>
865 ID of the discarded snapshot. <tt>null</tt> means the
866 current machine state has been discarded (restored from
867 the current snapshot).
868 </desc>
869 </param>
870 </method>
871
872 <method name="onSnapshotChange">
873 <desc>
874 Snapshot properties (name and/or description) have been changed.
875 <see>ISnapshot</see>
876 </desc>
877 <param name="machineId" type="uuid" dir="in">
878 <desc>ID of the machine this event relates to.</desc>
879 </param>
880 <param name="snapshotId" type="uuid" dir="in">
881 <desc>ID of the changed snapshot.</desc>
882 </param>
883 </method>
884
885 <method name="onGuestPropertyChange">
886 <desc>
887 Notification when a guest property has changed.
888 </desc>
889 <param name="machineId" type="uuid" dir="in">
890 <desc>
891 ID of the machine this event relates to.
892 </desc>
893 </param>
894 <param name="name" type="wstring" dir="in">
895 <desc>
896 The name of the property that has changed.
897 </desc>
898 </param>
899 <param name="value" type="wstring" dir="in">
900 <desc>
901 The new property value.
902 </desc>
903 </param>
904 <param name="flags" type="wstring" dir="in">
905 <desc>
906 The new property flags.
907 </desc>
908 </param>
909 </method>
910
911 </interface>
912
913 <interface
914 name="IVirtualBox" extends="$dispatched"
915 uuid="557a07bc-e6ae-4520-a361-4a8493199137"
916 wsmap="managed"
917 >
918 <desc>
919 The IVirtualBox interface represents the main interface exposed by the
920 product that provides virtual machine management.
921
922 An instance of IVirtualBox is required for the product to do anything
923 useful. Even though the interface does not expose this, internally,
924 IVirtualBox is implemented as a singleton and actually lives in the
925 process of the VirtualBox server (VBoxSVC.exe). This makes sure that
926 IVirtualBox can track the state of all virtual machines on a particular
927 host, regardless of which frontend started them.
928
929 To enumerate all the virtual machines on the host, use the
930 <link to="IVirtualBox::machines"/> attribute.
931 </desc>
932
933 <attribute name="version" type="wstring" readonly="yes">
934 <desc>
935 A string representing the version number of the product. The
936 format is 3 integer numbers divided by dots (e.g. 1.0.1). The
937 last number represents the build number and will frequently change.
938 </desc>
939 </attribute>
940
941 <attribute name="packageType" type="wstring" readonly="yes">
942 <desc>
943 A string representing the package type of this product. The
944 format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
945 SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
946 is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
947 this.
948 </desc>
949 </attribute>
950
951 <attribute name="homeFolder" type="wstring" readonly="yes">
952 <desc>
953 Full path to the directory where the global settings file,
954 <tt>VirtualBox.xml</tt>, is stored.
955
956 In this version of VirtualBox, the value of this property is
957 always <tt>&lt;user_dir&gt;/.VirtualBox</tt> (where
958 <tt>&lt;user_dir&gt;</tt> is the path to the user directory,
959 as determined by the host OS), and cannot be changed.
960
961 This path is also used as the base to resolve relative paths in
962 places where relative paths are allowed (unless otherwise
963 expressly indicated).
964 </desc>
965 </attribute>
966
967 <attribute name="settingsFilePath" type="wstring" readonly="yes">
968 <desc>
969 Full name of the global settings file.
970 The value of this property corresponds to the value of
971 <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
972 </desc>
973 </attribute>
974
975 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
976 <desc>
977 Current version of the format of the global VirtualBox settings file
978 (<tt>VirtualBox.xml</tt>).
979
980 The version string has the following format:
981 <pre>
982 x.y-platform
983 </pre>
984 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
985 versions, and <tt>platform</tt> is the platform identifier.
986
987 The current version usually matches the value of the
988 <link to="#settingsFormatVersion"/> attribute unless the
989 settings file was created by an older version of VirtualBox and there
990 was a change of the settings file format since then.
991
992 Note that VirtualBox automatically converts settings files from older
993 versions to the most recent version when reading them (usually at
994 VirtualBox startup) but it doesn't save the changes back until
995 you call a method that implicitly saves settings (such as
996 <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
997 explicitly. Therefore, if the value of this attribute differs from the
998 value of <link to="#settingsFormatVersion"/>, then it
999 means that the settings file was converted but the result of the
1000 conversion is not yet saved to disk.
1001
1002 The above feature may be used by interactive front-ends to inform users
1003 about the settings file format change and offer them to explicitly save
1004 all converted settings files (the global and VM-specific ones),
1005 optionally create bacup copies of the old settings files before saving,
1006 etc.
1007
1008 <see>settingsFormatVersion, saveSettingsWithBackup()</see>
1009 </desc>
1010 </attribute>
1011
1012 <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
1013 <desc>
1014 Most recent version of the settings file format.
1015
1016 The version string has the following format:
1017 <pre>
1018 x.y-platform
1019 </pre>
1020 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
1021 versions, and <tt>platform</tt> is the platform identifier.
1022
1023 VirtualBox uses this version of the format when saving settings files
1024 (either as a result of method calls that require to save settings or as
1025 a result of an explicit call to <link to="#saveSettings()"/>).
1026
1027 <see>settingsFileVersion</see>
1028 </desc>
1029 </attribute>
1030
1031 <attribute name="host" type="IHost" readonly="yes">
1032 <desc>Associated host object.</desc>
1033 </attribute>
1034
1035 <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
1036 <desc>Associated system information object.</desc>
1037 </attribute>
1038
1039 <attribute name="machines" type="IMachineCollection" readonly="yes">
1040 <desc>
1041 Collection of machine objects registered within this VirtualBox
1042 instance.
1043 </desc>
1044 </attribute>
1045
1046 <attribute name="machines2" type="IMachine" readonly="yes" safearray="yes">
1047 <desc>
1048 Array of machine objects registered within this VirtualBox instance.
1049 </desc>
1050 </attribute>
1051
1052 <attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
1053 <desc>
1054 Collection of hard disk objects registered within this VirtualBox
1055 instance.
1056
1057 This collection contains only "top-level" (basic or independent) hard
1058 disk images, but not differencing ones. All differencing images of the
1059 given top-level image (i.e. all its children) can be enumerated using
1060 <link to="IHardDisk::children"/>.
1061 </desc>
1062 </attribute>
1063
1064 <attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
1065
1066 <attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
1067
1068 <attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
1069
1070 <attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
1071
1072 <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
1073 <desc>
1074 Collection of global shared folders. Global shared folders are
1075 available to all virtual machines.
1076
1077 New shared folders are added to the collection using
1078 <link to="#createSharedFolder"/>. Existing shared folders can be
1079 removed using <link to="#removeSharedFolder"/>.
1080
1081 <note>
1082 In the current version of the product, global shared folders are not
1083 implemented and therefore this collection is always empty.
1084 </note>
1085 </desc>
1086 </attribute>
1087
1088 <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
1089 <desc>
1090 Associated performance collector object.
1091 </desc>
1092 </attribute>
1093
1094 <method name="createMachine">
1095 <desc>
1096 Creates a new virtual machine.
1097
1098 The new machine will have "empty" default settings and will not
1099 yet be registered. The typical sequence to create a virtual machine
1100 is therefore something like this:
1101
1102 <ol>
1103 <li>Call this method (IVirtualBox::createMachine) to have a new
1104 machine created. The machine object returned is "mutable", i.e.
1105 automatically locked for the current session, as if
1106 <link to="#openSession" /> had been called on it.</li>
1107
1108 <li>Assign meaningful settings to the new machine by calling the
1109 respective methods.</li>
1110
1111 <li>Call <link to="IMachine::saveSettings" /> to have the settings written
1112 to the machine's XML settings file. The configuration of the newly
1113 created machine will not be saved to disk (and the settings subfolder
1114 and file, as described below, will not be created) until this method
1115 is called.</li>
1116
1117 <li>Call <link to="#registerMachine" /> to have the
1118 machine show up in the list of machines registered with VirtualBox.</li>
1119 </ol>
1120
1121 Every machine has a <i>settings file</i> that is used to store
1122 the machine configuration. This file is stored in the directory
1123 called <i>machine settings subfolder</i>. Unless specified otherwise,
1124 both the subfolder and the settings file will have a name that
1125 corresponds to the name of the virtual machine. You can specify
1126 where to create the machine settings subfolder using the @a
1127 baseFolder argument. The base folder can be absolute (full path)
1128 or relative to the <link to="IVirtualBox::homeFolder">
1129 VirtualBox home directory</link>.
1130
1131 If a null or empty string is given as the base folder (which is
1132 recommended), the <link to="ISystemProperties::defaultMachineFolder">
1133 default machine settings folder</link> will be used as the base
1134 folder to create the machine settings subfolder and file. In
1135 any case, the full path to the settings file will look like:
1136 <pre>
1137 &lt;base_folder&gt;/&lt;machine_name&gt;/&lt;machine_name&gt;.xml
1138 </pre>
1139
1140 Optionally the UUID of the machine can be predefined. If this is
1141 not desired (i.e. a new UUID should be generated), pass just an
1142 empty or null UUID.
1143
1144 You should also specify a valid name for the machine.
1145 See the <link to="IMachine::name"/> property
1146 description for more details about the machine name.
1147
1148 The created machine remains
1149 unregistered until you call <link to="#registerMachine()"/>.
1150
1151 <note>
1152 There is no way to change the name of the settings file or
1153 subfolder of the created machine directly.
1154 </note>
1155 </desc>
1156 <param name="baseFolder" type="wstring" dir="in">
1157 <desc>
1158 Name of the folder where to create the machine settings
1159 subfolder containing the settings file.
1160 </desc>
1161 </param>
1162 <param name="name" type="wstring" dir="in">
1163 <desc>Machine name.</desc>
1164 </param>
1165 <param name="id" type="uuid" dir="in">
1166 <desc>
1167 UUID of the newly created VM, when non-null or non-empty.
1168 Otherwise a UUID is automatically generated.
1169 </desc>
1170 </param>
1171 <param name="machine" type="IMachine" dir="return">
1172 <desc>Created machine object.</desc>
1173 </param>
1174 </method>
1175
1176 <method name="createLegacyMachine">
1177 <desc>
1178 Creates a new virtual machine in "legacy" mode, using the
1179 specified settings file to store machine settings.
1180
1181 As opposed to machines created by <link to="#createMachine()"/>,
1182 the settings file of the machine created in "legacy" mode
1183 is not automatically renamed when the machine name is
1184 changed -- it will always remain the same as specified in this
1185 method call.
1186
1187 The specified settings file name can be absolute
1188 (full path) or relative to the <link to="IVirtualBox::homeFolder">
1189 VirtualBox home directory</link>. If the file name doesn't
1190 contain an extension, the default extension (.xml) will be
1191 appended.
1192
1193 Optionally the UUID of the machine can be predefined. If this is
1194 not desired (i.e. a new UUID should be generated), pass just an
1195 empty or null UUID.
1196
1197 Note that the configuration of the newly created machine is not
1198 saved to disk (and therefore no settings file is created)
1199 until <link to="IMachine::saveSettings()"/> is called. If the
1200 specified settings file already exists,
1201 <link to="IMachine::saveSettings()"/> will return an error.
1202
1203 You should also specify a valid name for the machine.
1204 See the <link to="IMachine::name"/> property
1205 description for more details about the machine name.
1206
1207 The created machine remains
1208 unregistered until you call <link to="#registerMachine()"/>.
1209
1210 @deprecated This method may be removed later. It is better
1211 to use <link to="IVirtualBox::createMachine()"/>.
1212
1213 <note>
1214 There is no way to change the name of the settings file
1215 of the created machine.
1216 </note>
1217 </desc>
1218 <param name="settingsFile" type="wstring" dir="in">
1219 <desc>
1220 Name of the file where to store machine settings.
1221 </desc>
1222 </param>
1223 <param name="name" type="wstring" dir="in">
1224 <desc>Machine name.</desc>
1225 </param>
1226 <param name="id" type="uuid" dir="in">
1227 <desc>
1228 UUID of the newly created VM, when non-null or non-empty.
1229 Otherwise a UUID is automatically generated.
1230 </desc>
1231 </param>
1232 <param name="machine" type="IMachine" dir="return">
1233 <desc>Created machine object.</desc>
1234 </param>
1235 </method>
1236
1237 <method name="openMachine">
1238 <desc>
1239 Opens a virtual machine from the existing settings file.
1240 The opened machine remains unregistered until you call
1241 <link to="#registerMachine()"/>.
1242
1243 The specified settings file name can be absolute
1244 (full path) or relative to the <link to="IVirtualBox::homeFolder">
1245 VirtualBox home directory</link>. This file must exist
1246 and must be a valid machine settings file whose contents
1247 will be used to construct the machine object.
1248
1249 @deprecated Will be removed soon.
1250 </desc>
1251 <param name="settingsFile" type="wstring" dir="in">
1252 <desc>
1253 Name of the machine settings file.
1254 </desc>
1255 </param>
1256 <param name="machine" type="IMachine" dir="return">
1257 <desc>Opened machine object.</desc>
1258 </param>
1259 <note>
1260 <link to="IMachine::settingsModified"/> will return
1261 false for the created machine, until any of machine settigs
1262 are changed.
1263 </note>
1264 </method>
1265
1266 <method name="registerMachine">
1267 <desc>
1268
1269 Registers the machine previously created using
1270 <link to="#createMachine()"/> or opened using
1271 <link to="#openMachine()"/> within this VirtualBox installation. After
1272 successful method invocation, the
1273 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1274 to all registered callbacks.
1275
1276 <note>
1277 This method implicitly calls <link to="IMachine::saveSettings"/>
1278 to save all current machine settings before registering it.
1279 </note>
1280
1281 </desc>
1282 <param name="machine" type="IMachine" dir="in"/>
1283 </method>
1284
1285 <method name="getMachine">
1286 <desc>
1287 Attempts to find a virtual machine given its UUID.
1288 To look up a machine by name, use <link to="IVirtualBox::findMachine" /> instead.
1289 </desc>
1290 <param name="id" type="uuid" dir="in"/>
1291 <param name="machine" type="IMachine" dir="return"/>
1292 </method>
1293
1294 <method name="findMachine">
1295 <desc>
1296 Attempts to find a virtual machine given its name.
1297 To look up a machine by UUID, use <link to="IVirtualBox::getMachine" /> instead.
1298 </desc>
1299 <param name="name" type="wstring" dir="in"/>
1300 <param name="machine" type="IMachine" dir="return"/>
1301 </method>
1302
1303 <method name="unregisterMachine">
1304 <desc>
1305
1306 Unregisters the machine previously registered using
1307 <link to="#registerMachine"/>. After successful method invocation, the
1308 <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
1309 to all registered callbacks.
1310
1311 <note>
1312 The specified machine must not be in the Saved state, have an open
1313 (or a spawning) direct session associated with it, have snapshots or
1314 have hard disks attached.
1315 </note>
1316
1317 <note>
1318 This method implicitly calls <link to="IMachine::saveSettings"/> to
1319 save all current machine settings before unregistering it.
1320 </note>
1321
1322 <note>
1323 If the given machine is inaccessible (see
1324 <link to="IMachine::accessible"/>), it will be unregistered and
1325 fully uninitialized right afterwards. As a result, the returned
1326 machine object will be unusable and an attempt to call
1327 <b>any</b> method will return the "Object not ready" error.
1328 </note>
1329
1330 </desc>
1331 <param name="id" type="uuid" dir="in">
1332 <desc>UUID of the machine to unregister.</desc>
1333 </param>
1334 <param name="machine" type="IMachine" dir="return">
1335 <desc>Unregistered machine object.</desc>
1336 </param>
1337 </method>
1338
1339 <method name="createHardDisk">
1340 <desc>
1341
1342 Creates a new unregistered hard disk that will use the given
1343 storage type.
1344
1345 Most properties of the created hard disk object are
1346 uninitialized. Valid values must be assigned to them (and probalby
1347 some actions performed) to make the actual usage of this hard disk
1348 (<link to="#registerHardDisk()">register</link>, attach to a virtual
1349 machine, etc.). See the description of <link to="IHardDisk"/> and
1350 descriptions of storage type specific interfaces for more information.
1351
1352 <note>
1353 For hard disks using
1354 the <link
1355 to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
1356 storage type, an image file is not actually created until you call
1357 <link to="IVirtualDiskImage::createDynamicImage()"/> or
1358 <link to="IVirtualDiskImage::createFixedImage()"/>.
1359 </note>
1360
1361 </desc>
1362
1363 <param name="storageType" type="HardDiskStorageType" dir="in">
1364 <desc>Storage type of the hard disk image to create.</desc>
1365 </param>
1366 <param name="hardDisk" type="IHardDisk" dir="return">
1367 <desc>Created hard disk object of the given storage type.</desc>
1368 </param>
1369
1370 </method>
1371
1372 <method name="openHardDisk">
1373 <desc>
1374
1375 Opens a hard disk from an existing location.
1376
1377 This method tries to guess the
1378 <link to="HardDiskStorageType">hard disk storage type</link> from the
1379 format of the location string and from the contents of the resource the
1380 location points to. Currently, a <i>file path</i> is the only
1381 supported format for the location string which must point to either a
1382 VDI file or to a VMDK file. On success, an IHardDisk object will be
1383 returned that also implements the corresponding interface
1384 (IVirtualDiskImage or IVMDKImage, respectively). The
1385 <link to="IHardDisk::storageType"/> property may also be used to
1386 determine the storage type of the returned object (instead of trying
1387 to query one of these interfaces).
1388
1389 <note>
1390 The specified file path can be absolute (full path) or relative to
1391 the <link to="IVirtualBox::homeFolder">VirtualBox home
1392 directory</link>. If only a file name without any path is given,
1393 the <link to="ISystemProperties::defaultVDIFolder"> default VDI
1394 folder</link> will be used as a path to the image file.
1395 </note>
1396
1397 The opened hard disk remains unregistered
1398 until <link to="#registerHardDisk()"/> is called.
1399
1400 </desc>
1401
1402 <param name="location" type="wstring" dir="in">
1403 <desc>
1404 Location of the resource that contains a valid hard disk.
1405 </desc>
1406 </param>
1407 <param name="hardDisk" type="IHardDisk" dir="return">
1408 <desc>Opened hard disk object.</desc>
1409 </param>
1410 </method>
1411
1412 <method name="openVirtualDiskImage">
1413 <desc>
1414
1415 Opens a hard disk from an existing Virtual Disk Image file.
1416 The opened hard disk remains unregistered
1417 until <link to="#registerHardDisk()"/> is called.
1418
1419 @deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.
1420
1421 <note>Opening differencing images is not supported.</note>
1422
1423 <note>The specified file path can be absolute (full path) or
1424 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
1425 home directory</link>. If only a file name without any path is
1426 given, the <link to="ISystemProperties::defaultVDIFolder">
1427 default VDI folder</link> will be used as a path to the image
1428 file.</note>
1429
1430 </desc>
1431
1432 <param name="filePath" type="wstring" dir="in">
1433 <desc>
1434 Name of the file that contains a valid Virtual Disk Image.
1435 </desc>
1436 </param>
1437 <param name="image" type="IVirtualDiskImage" dir="return">
1438 <desc>Opened hard disk object.</desc>
1439 </param>
1440 </method>
1441
1442 <method name="registerHardDisk">
1443 <desc>
1444
1445 Registers the given hard disk within this VirtualBox
1446 installation. The hard disk must not be registered, must be
1447 <link to="IHardDisk::accessible"/> and must not be a
1448 differencing hard disk, otherwise the registration will fail.
1449
1450 </desc>
1451 <param name="hardDisk" type="IHardDisk" dir="in">
1452 <desc>Hard disk object to register.</desc>
1453 </param>
1454 </method>
1455
1456 <method name="getHardDisk" const="yes">
1457 <desc>
1458 Returns the registered hard disk with the given UUID.
1459 </desc>
1460 <param name="id" type="uuid" dir="in">
1461 <desc>UUID of the hard disk to look for.</desc>
1462 </param>
1463 <param name="hardDisk" type="IHardDisk" dir="return">
1464 <desc>Found hard disk object.</desc>
1465 </param>
1466 </method>
1467
1468 <method name="findHardDisk">
1469 <desc>
1470
1471 Returns a registered hard disk that uses the given location to
1472 store data. The search is done by comparing the
1473 value of the @a location argument to the
1474 <link to="IHardDisk::location"/> attribute of each registered
1475 hard disk.
1476
1477 For locations repesented by file paths (such as VDI and VMDK
1478 images), the specified location can be either an absolute file
1479 path or a path relative to
1480 the <link to="IVirtualBox::homeFolder"> VirtualBox home
1481 directory</link>. If only a file name without any path is
1482 given, the <link to="ISystemProperties::defaultVDIFolder">
1483 default VDI folder</link> will be used as a path to construct
1484 the absolute image file name to search for. Note that on host
1485 systems with case sensitive filesystems, a case sensitive
1486 comparison is performed, otherwise the case of symbols in the
1487 file path is ignored.
1488
1489 </desc>
1490 <param name="location" type="wstring" dir="in">
1491 <desc>Hard disk location specification to search for.</desc>
1492 </param>
1493 <param name="hardDisk" type="IHardDisk" dir="return">
1494 <desc>Found hard disk object.</desc>
1495 </param>
1496 </method>
1497
1498 <method name="findVirtualDiskImage">
1499 <desc>
1500
1501 Returns a registered hard disk that uses the given image file.
1502
1503 @deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.
1504
1505 <note>The specified file path can be absolute (full path) or
1506 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
1507 home directory</link>. If only a file name without any path is
1508 given, the <link to="ISystemProperties::defaultVDIFolder">
1509 default VDI folder</link> will be used as a path to the image
1510 file.</note>
1511
1512 <note>On host systems with case sensitive filesystems, a case
1513 sensitive comparison is performed, otherwise the case of symbols
1514 in the file path is ignored.</note>
1515
1516 </desc>
1517 <param name="filePath" type="wstring" dir="in">
1518 <desc>Virtual Disk Image file path to look for.</desc>
1519 </param>
1520 <param name="image" type="IVirtualDiskImage" dir="return">
1521 <desc>Found hard disk object.</desc>
1522 </param>
1523 </method>
1524
1525 <method name="unregisterHardDisk">
1526 <desc>
1527 Unregisters a hard disk previously registered using
1528 <link to="#registerHardDisk()"/>.
1529 <note>
1530 The specified hard disk must not be attached to any of
1531 the existing virtual machines and must not have children
1532 (differencing) hard disks.
1533 </note>
1534 </desc>
1535 <param name="id" type="uuid" dir="in">
1536 <desc>UUID of the hard disk to unregister.</desc>
1537 </param>
1538 <param name="hardDisk" type="IHardDisk" dir="return">
1539 <desc>Unregistered hard disk object.</desc>
1540 </param>
1541 </method>
1542
1543 <method name="openDVDImage">
1544 <desc>
1545 Opens the CD/DVD image contained in the specified file of
1546 the supported format and assigns it the given UUID. The opened
1547 image remains unregistered
1548 until <link to="#registerDVDImage()"/> is called.
1549 </desc>
1550 <param name="filePath" type="wstring" dir="in">
1551 <desc>
1552 Full name of the file that contains a valid
1553 CD/DVD image. Currently, only ISO images are supported.
1554 <note>
1555 The specified file name can be absolute or relative
1556 to the <link to="IVirtualBox::homeFolder">
1557 VirtualBox home directory</link>.
1558 </note>
1559 </desc>
1560 </param>
1561 <param name="id" type="uuid" dir="in">
1562 <desc>
1563 UUID to assign to the given image file within this
1564 VirtualBox installation. If an empty (null) UUID is
1565 specified, the system will randomly generate an UUID.
1566 </desc>
1567 </param>
1568 <param name="image" type="IDVDImage" dir="return">
1569 <desc>Opened CD/DVD image object.</desc>
1570 </param>
1571 </method>
1572
1573 <method name="registerDVDImage">
1574 <desc>
1575 Registers a CD/DVD image within this VirtualBox
1576 installation. The image must not be registered and must not
1577 be associated with the same image file as any of the already
1578 registered images, otherwise the registration will fail.
1579 </desc>
1580 <param name="image" type="IDVDImage" dir="in">
1581 <desc>CD/DVD image object to register.</desc>
1582 </param>
1583 </method>
1584
1585 <method name="getDVDImage">
1586 <desc>
1587 Returns a registered CD/DVD image with the given UUID.
1588 </desc>
1589 <param name="id" type="uuid" dir="in">
1590 <desc>UUID of the image to look for.</desc>
1591 </param>
1592 <param name="image" type="IDVDImage" dir="return">
1593 <desc>Found CD/DVD image object.</desc>
1594 </param>
1595 </method>
1596
1597 <method name="findDVDImage">
1598 <desc>
1599 Returns a registered CD/DVD image with the given image file.
1600 <note>
1601 On host systems with case sensitive filesystems, a case
1602 sensitive comparison is performed, otherwise the case of
1603 symbols in the file path is ignored.
1604 </note>
1605 </desc>
1606 <param name="filePath" type="wstring" dir="in">
1607 <desc>CD/DVD image file path to look for.</desc>
1608 </param>
1609 <param name="image" type="IDVDImage" dir="return">
1610 <desc>Found CD/DVD image object.</desc>
1611 </param>
1612 </method>
1613
1614 <method name="getDVDImageUsage">
1615 <desc>
1616 Returns the list of of UUIDs of all virtual machines that use
1617 the given CD/DVD image.
1618 </desc>
1619 <param name="id" type="uuid" dir="in">
1620 <desc>UUID of the image to get the usage information for.</desc>
1621 </param>
1622 <param name="usage" type="ResourceUsage" dir="in">
1623 <desc>Type of the usage (permanent, temporary or all).</desc>
1624 </param>
1625 <param name="machineIDs" type="wstring" dir="return">
1626 <desc>
1627 List of UUIDs of all machines that use the given image
1628 in the way specified by the usage parameter.
1629 The list is returned as a string containing UUIDs separated
1630 by spaces. A null string means that the image is not used.
1631 <note>
1632 When the usage type is <link to="ResourceUsage::All"/> and the image
1633 is used by the VM both permanently and temporarily, the VM's UUID
1634 will be present only once in the list.
1635 </note>
1636 </desc>
1637 </param>
1638 </method>
1639
1640 <method name="unregisterDVDImage">
1641 <desc>
1642 Unregisters the CD/DVD image previously registered using
1643 <link to="#registerDVDImage()"/>.
1644 <note>
1645 The specified image must not be mounted to any of
1646 the existing virtual machines.
1647 </note>
1648 </desc>
1649 <param name="id" type="uuid" dir="in">
1650 <desc>UUID of the CD/DVD image to unregister.</desc>
1651 </param>
1652 <param name="image" type="IDVDImage" dir="return">
1653 <desc>Unregistered image object.</desc>
1654 </param>
1655 </method>
1656
1657 <method name="openFloppyImage">
1658 <desc>
1659 Opens a floppy image contained in the specified file of
1660 the supported format and assigns it the given UUID. The opened
1661 image remains unregistered
1662 until <link to="#registerFloppyImage()"/> is called.
1663 </desc>
1664 <param name="filePath" type="wstring" dir="in">
1665 <desc>
1666 Full name of the file that contains a valid
1667 floppy image.
1668 <note>
1669 The specified file name can be absolute or relative
1670 to the <link to="IVirtualBox::homeFolder">
1671 VirtualBox home directory</link>.
1672 </note>
1673 </desc>
1674 </param>
1675 <param name="id" type="uuid" dir="in">
1676 <desc>
1677 UUID to assign to the given image file within this
1678 VirtualBox installation. If an empty (null) UUID is
1679 specified, the system will randomly generate an UUID.
1680 </desc>
1681 </param>
1682 <param name="image" type="IFloppyImage" dir="return">
1683 <desc>Opened CD/DVD image object.</desc>
1684 </param>
1685 </method>
1686
1687 <method name="registerFloppyImage">
1688 <desc>
1689 Registers a floppy image within this VirtualBox
1690 installation. The image must not be registered and must not
1691 be associated with the same image file as any of the already
1692 registered images, otherwise the registration will fail.
1693 </desc>
1694 <param name="image" type="IFloppyImage" dir="in">
1695 <desc>Floppy image object to register.</desc>
1696 </param>
1697 </method>
1698
1699 <method name="getFloppyImage">
1700 <desc>
1701 Returns a registered floppy image with the given UUID.
1702 </desc>
1703 <param name="id" type="uuid" dir="in">
1704 <desc>UUID of the image to look for.</desc>
1705 </param>
1706 <param name="image" type="IFloppyImage" dir="return">
1707 <desc>Found floppy image object.</desc>
1708 </param>
1709 </method>
1710
1711 <method name="findFloppyImage">
1712 <desc>
1713 Returns a registered floppy image with the given image file.
1714 <note>
1715 On host systems with case sensitive filesystems, a case
1716 sensitive comparison is performed, otherwise the case of
1717 symbols in the file path is ignored.
1718 </note>
1719 </desc>
1720 <param name="filePath" type="wstring" dir="in">
1721 <desc>Floppy image file path to look for.</desc>
1722 </param>
1723 <param name="image" type="IFloppyImage" dir="return">
1724 <desc>Found floppy image object.</desc>
1725 </param>
1726 </method>
1727
1728 <method name="getFloppyImageUsage">
1729 <desc>
1730 Returns the list of of UUIDs of all virtual machines that use
1731 the given floppy image.
1732 </desc>
1733 <param name="id" type="uuid" dir="in">
1734 <desc>UUID of the image to get the usage information for.</desc>
1735 </param>
1736 <param name="usage" type="ResourceUsage" dir="in">
1737 <desc>Type of the usage (permanent, temporary or all).</desc>
1738 </param>
1739 <param name="machineIDs" type="wstring" dir="return">
1740 <desc>
1741 List of UUIDs of all machines that use the given image
1742 in the way specified by the usage parameter.
1743 The list is returned as a string containing UUIDs separated
1744 by spaces. A null string means that the image is not used.
1745 <note>
1746 When the usage type is <link to="ResourceUsage::All"/> and the image
1747 is used by the VM both permanently and temporarily, the VM's UUID
1748 will be present only once in the list.
1749 </note>
1750 </desc>
1751 </param>
1752 </method>
1753
1754 <method name="unregisterFloppyImage">
1755 <desc>
1756 Unregisters the floppy image previously registered using
1757 <link to="#registerFloppyImage()"/>.
1758 <note>
1759 The specified image must not be mounted to any of
1760 the existing virtual machines.
1761 </note>
1762 </desc>
1763 <param name="id" type="uuid" dir="in">
1764 <desc>UUID of the floppy image to unregister.</desc>
1765 </param>
1766 <param name="image" type="IFloppyImage" dir="return">
1767 <desc>Unregistered image object.</desc>
1768 </param>
1769 </method>
1770
1771 <method name="getGuestOSType">
1772 <desc>
1773 Returns an object describing the specified guest OS type.
1774
1775 The requested guest OS type is specified using a string which is a
1776 mnemonic identifier of the guest operating system, such as
1777 <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
1778 particular virtual machine can be read or set using the
1779 <link to="IMachine::OSTypeId"/> attribute.
1780
1781 The <link to="IVirtualBox::guestOSTypes"/> collection contains all
1782 available guest OS type objects. Each object has an
1783 <link to="IGuestOSType::id"/> attribute which contains an identifier of
1784 the guest OS this object describes.
1785 </desc>
1786 <param name="id" type="wstring" dir="in">
1787 <desc>Guest OS type ID string.</desc>
1788 </param>
1789 <param name="type" type="IGuestOSType" dir="return">
1790 <desc>Guest OS type object.</desc>
1791 </param>
1792 </method>
1793
1794 <method name="createSharedFolder">
1795 <desc>
1796 Creates a new global shared folder by associating the given logical
1797 name with the given host path, adds it to the collection of shared
1798 folders and starts sharing it. Refer to the description of
1799 <link to="ISharedFolder"/> to read more about logical names.
1800 </desc>
1801 <param name="name" type="wstring" dir="in">
1802 <desc>Unique logical name of the shared folder.</desc>
1803 </param>
1804 <param name="hostPath" type="wstring" dir="in">
1805 <desc>Full path to the shared folder in the host file system.</desc>
1806 </param>
1807 <param name="writable" type="boolean" dir="in">
1808 <desc>Whether the share is writable or readonly</desc>
1809 </param>
1810 </method>
1811
1812 <method name="removeSharedFolder">
1813 <desc>
1814 Removes the global shared folder with the given name previously
1815 created by <link to="#createSharedFolder"/> from the collection of
1816 shared folders and stops sharing it.
1817 </desc>
1818 <param name="name" type="wstring" dir="in">
1819 <desc>Logical name of the shared folder to remove.</desc>
1820 </param>
1821 </method>
1822
1823 <method name="getNextExtraDataKey">
1824 <desc>
1825 Returns the global extra data key name following the supplied key.
1826
1827 An error is returned if the supplied @a key does not exist. @c NULL is
1828 returned in @a nextKey if the supplied key is the last key. When
1829 supplying @c NULL for the @a key, the first key item is returned in @a
1830 nextKey (if there is any). @a nextValue is an optional parameter and
1831 if supplied, the next key's value is returned in it.
1832 </desc>
1833 <param name="key" type="wstring" dir="in">
1834 <desc>Name of the data key to follow.</desc>
1835 </param>
1836 <param name="nextKey" type="wstring" dir="out">
1837 <desc>Name of the next data key.</desc>
1838 </param>
1839 <param name="nextValue" type="wstring" dir="out">
1840 <desc>Value of the next data key.</desc>
1841 </param>
1842 </method>
1843
1844 <method name="getExtraData">
1845 <desc>
1846 Returns associated global extra data.
1847
1848 If the requested data @a key does not exist, this function will
1849 succeed and return @c NULL in the @a value argument.
1850 </desc>
1851 <param name="key" type="wstring" dir="in">
1852 <desc>Name of the data key to get.</desc>
1853 </param>
1854 <param name="value" type="wstring" dir="return">
1855 <desc>Value of the requested data key.</desc>
1856 </param>
1857 </method>
1858
1859 <method name="setExtraData">
1860 <desc>
1861 Sets associated global extra data.
1862
1863 If you pass @c NULL as a key @a value, the given @a key will be
1864 deleted.
1865
1866 <note>
1867 Before performing the actual data change, this method will ask all
1868 registered callbacks using the
1869 <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
1870 notification for a permission. If one of the callbacks refuses the
1871 new value, the change will not be performed.
1872 </note>
1873 <note>
1874 On success, the
1875 <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
1876 is called to inform all registered callbacks about a successful data
1877 change.
1878 </note>
1879 </desc>
1880 <param name="key" type="wstring" dir="in">
1881 <desc>Name of the data key to set.</desc>
1882 </param>
1883 <param name="value" type="wstring" dir="in">
1884 <desc>Value to assign to the key.</desc>
1885 </param>
1886 </method>
1887
1888 <method name="openSession">
1889 <desc>
1890 Opens a new direct session with the given virtual machine.
1891
1892 Within the direct session context, it is possible to change
1893 all VM settings, as well as to execute the VM in the process
1894 space of the session object. There can be only one direct
1895 session open at a time for every virtual machine. In VirtualBox
1896 terminology, the machine becomes "mutable" after a session has
1897 been opened.
1898
1899 Upon successful return, the session object can be used to
1900 get access to the machine and to the VM console.
1901
1902 Note that the "mutable" machine object, on which you may want
1903 to invoke IMachine methods to change its settings, will be a
1904 different object from the immutable IMachine objects returned
1905 by various IVirtualBox methods. To obtain a mutable
1906 IMachine object, upon which you can invoke settings methods,
1907 use the "machine" attribute of the ISession object which represents
1908 your open session.
1909
1910 In other words, to change settings on a machine, the following
1911 sequence is typically performed:
1912
1913 <ol>
1914 <li>Call this method (openSession) to have a machine locked for
1915 the current session.</li>
1916
1917 <li>Obtain a mutable IMachine object from ISession::machine.</li>
1918
1919 <li>Change the settings of the machine.</li>
1920
1921 <li>Call IMachine::saveSettings.</li>
1922
1923 <li>Close the session by calling <link to="#close" />.</li>
1924 </ol>
1925 </desc>
1926 <param name="session" type="ISession" dir="in">
1927 <desc>
1928 Session object that will represent the opened session after
1929 successful method invocation. This object must not represent
1930 the already open session.
1931 <note>
1932 This session will be automatically closed if the
1933 VirtualBox server is terminated for some reason.
1934 </note>
1935 </desc>
1936 </param>
1937 <param name="machineId" type="uuid" dir="in">
1938 <desc>ID of the virtual machine to open a session with.</desc>
1939 </param>
1940 </method>
1941
1942 <method name="openRemoteSession">
1943 <desc>
1944 Opens a new remote session with the given virtual machine.
1945
1946 Opening a remote session causes the VirtualBox server to start a new
1947 process that opens a direct session with the given VM. The remote
1948 session provides some level of control over the VM execution to the
1949 caller (using the IConsole interface); however, within the remote
1950 session context, not all VM settings are available for modification.
1951
1952 This operation can take some time (a new VM is started in a new process,
1953 for which memory and other resources need to be set up, which can take
1954 a few seconds). Because of this, a progress object is returned to allow the
1955 caller to wait for this asynchronous operation to be completed. Until then,
1956 the remote session object remains in the closed state and accessing the
1957 machine or its console through it is invalid. It is recommended to use
1958 <link to="IProgress::waitForCompletion" /> or similar calls to wait for
1959 completion.
1960
1961 Currently supported session types (values of the @a type
1962 argument) are:
1963 <ul>
1964 <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
1965 <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
1966 </ul>
1967
1968 The @a environment argument is a string containing definitions of
1969 environment variables in the following format:
1970 @code
1971 NAME[=VALUE]\n
1972 NAME[=VALUE]\n
1973 ...
1974 @endcode
1975 where <tt>\\n</tt> is the new line character. These environment
1976 variables will be appended to the environment of the VirtualBox server
1977 process. If an environment variable exists both in the server process
1978 and in this list, the value from this list takes precedence over the
1979 server's variable. If the value of the environment variable is
1980 omitted, this variable will be removed from the resulting environment.
1981 If the environment string is @c null, the server environment is
1982 inherited by the started process as is.
1983
1984 <note>
1985 It is an error to open a remote session with the machine
1986 that already has an open direct session or waits until the
1987 previous request to open the remote session is completed
1988 (see <link to="IMachine::sessionState"/>).
1989 </note>
1990
1991 <note>
1992 The opened @a session will be automatically closed when
1993 the corresponding direct session dies or gets closed.
1994 </note>
1995
1996 <see>openExistingSession</see>
1997 </desc>
1998 <param name="session" type="ISession" dir="in">
1999 <desc>
2000 Session object that will represent the opened remote session
2001 after successful method invocation (this object must not
2002 represent an already open session).
2003 </desc>
2004 </param>
2005 <param name="machineId" type="uuid" dir="in">
2006 <desc>ID of the virtual machine to open a session with.</desc>
2007 </param>
2008 <param name="type" type="wstring" dir="in">
2009 <desc>
2010 Type of the remote session (case sensitive).
2011 </desc>
2012 </param>
2013 <param name="environment" type="wstring" dir="in">
2014 <desc>
2015 Environment to pass to the opened session (may be @c null).
2016 </desc>
2017 </param>
2018 <param name="progress" type="IProgress" dir="return">
2019 <desc>Progress object to track the operation completion.</desc>
2020 </param>
2021 </method>
2022
2023 <method name="openExistingSession">
2024 <desc>
2025 Opens a new remote session with the virtual machine for
2026 which a direct session is already open.
2027
2028 The remote session provides some level of control over the VM
2029 execution (using the IConsole interface) to the caller; however,
2030 within the remote session context, not all VM settings are available
2031 for modification.
2032
2033 As opposed to <link to="#openRemoteSession()"/>, the number of
2034 remote sessions opened this way is not limited by the API
2035
2036 <note>
2037 It is an error to open a remote session with the machine that
2038 doesn't have an open direct session.
2039 </note>
2040
2041 <see>openRemoteSession</see>
2042 </desc>
2043 <param name="session" type="ISession" dir="in">
2044 <desc>
2045 Session object that will represent the open remote session
2046 after successful method invocation. This object must not
2047 represent an already open session.
2048 <note>
2049 This session will be automatically closed when the peer
2050 (direct) session dies or gets closed.
2051 </note>
2052 </desc>
2053 </param>
2054 <param name="machineId" type="uuid" dir="in">
2055 <desc>ID of the virtual machine to open a session with.</desc>
2056 </param>
2057 </method>
2058
2059 <method name="registerCallback">
2060 <desc>
2061 Registers a new global VirtualBox callback. The methods of the given
2062 callback object will be called by VirtualBox when an appropriate
2063 event occurs.
2064 </desc>
2065 <param name="callback" type="IVirtualBoxCallback" dir="in">
2066 <desc>Callback object to register.</desc>
2067 </param>
2068 </method>
2069
2070 <method name="unregisterCallback">
2071 <desc>
2072 Unregisters the previously registered global VirtualBox callback.
2073 </desc>
2074 <param name="callback" type="IVirtualBoxCallback" dir="in">
2075 <desc>Callback object to unregister.</desc>
2076 </param>
2077 </method>
2078
2079 <method name="waitForPropertyChange">
2080 <desc>
2081 Blocks the caller until any of the properties represented by the @a
2082 what argument changes the value or until the given timeout interval
2083 expires.
2084
2085 The @a what argument is a comma separated list of propertiy masks that
2086 describe properties the caller is interested in. The property mask is
2087 a string in the following format:
2088
2089 <pre>
2090 [[group.]subgroup.]name
2091 </pre>
2092
2093 where @c name is the property name and @c group, @c subgroup are zero
2094 or or more property group specifiers. Each element (group or name) in
2095 the property mask may be either a latin string or an asterisk symbol
2096 (@c "*") which is used to match any string for the given element. A
2097 property mask that doesn't contain asterisk symbols represents a
2098 single fully qualified property name.
2099
2100 Groups in the fully qualified property name go from more generic (the
2101 left-most part) to more specific (the right-most part). The first
2102 element is usually a name of the object the property belongs to. The
2103 second element may be either a property name, or a child object name,
2104 or an index if the preceeding element names an object which is one of
2105 many objects of the same type. This way, property names form a
2106 hierarchy of properties. Here are some examples of property names:
2107
2108 <table>
2109 <tr>
2110 <td><tt>VirtualBox.version</tt></td>
2111 <td><link to="IVirtualBox::version"/> property</td>
2112 </tr>
2113 <tr>
2114 <td><tt>Machine.&lt;UUID&gt;.name</tt></td>
2115 <td><link to="IMachine::name"/> property of the machine with the
2116 given UUID</td>
2117 </tr>
2118 </table>
2119
2120 Most property names directly correspond to the properties of objects
2121 (components) provided by the VirtualBox library and may be used to
2122 track changes to these properties. However, there may be
2123 pseudo-property names that don't correspond to any existing object's
2124 property directly, as well as there may be object properties that
2125 don't have a corresponding property name that is understood by this
2126 method, and therefore changes to such properties cannot be
2127 tracked. See individual object's property descrcriptions to get a
2128 fully qualified property name that can be used with this method (if
2129 any).
2130
2131 There is a special property mask @c "*" (i.e. a string consisting of a
2132 single asterisk symbol) that can be used to match all properties.
2133 Below are more examples of property masks:
2134
2135 <table>
2136 <tr>
2137 <td><tt>VirtualBox.*</tt></td>
2138 <td>Track all properties of the VirtualBox object</td>
2139 </tr>
2140 <tr>
2141 <td><tt>Machine.*.name</tt></td>
2142 <td>Track changes to the <link to="IMachine::name"/> property of
2143 all registered virtual machines</td>
2144 </tr>
2145 </table>
2146
2147 </desc>
2148 <param name="what" type="wstring" dir="in">
2149 <desc>Comma separated list of property masks.</desc>
2150 </param>
2151 <param name="timeout" type="unsigned long" dir="in">
2152 <desc>
2153 Wait timeout in milliseconds.
2154 Specify -1 for an indefinite wait.
2155 </desc>
2156 </param>
2157 <param name="changed" type="wstring" dir="out">
2158 <desc>
2159 Comma separated list of properties that have been changed and caused
2160 this method to return to the caller.
2161 </desc>
2162 </param>
2163 <param name="values" type="wstring" dir="out">
2164 <desc>Reserved, not currently used.</desc>
2165 </param>
2166 </method>
2167
2168 <method name="saveSettings">
2169 <desc>
2170 Saves the global settings to the global settings file
2171 (<link to="#settingsFilePath"/>).
2172
2173 This method is only useful for explicitly saving the global settings
2174 file after it has been auto-converted from the old format to the most
2175 recent format (see <link to="#settingsFileVersion"/> for details).
2176 Normally, the global settings file is implicitly saved when a global
2177 setting is changed.
2178 </desc>
2179 </method>
2180
2181 <method name="saveSettingsWithBackup">
2182 <desc>
2183 Creates a backup copy of the global settings file
2184 (<link to="#settingsFilePath"/>) in case of auto-conversion, and then
2185 calls <link to="#saveSettings()"/>.
2186
2187 Note that the backup copy is created <b>only</b> if the settings file
2188 auto-conversion took place (see <link to="#settingsFileVersion"/> for
2189 details). Otherwise, this call is fully equivalent to
2190 <link to="#saveSettings()"/> and no backup copying is done.
2191
2192 The backup copy is created in the same directory where the original
2193 settings file is located. It is given the following file name:
2194 <pre>
2195 original.xml.x.y-platform.bak
2196 </pre>
2197 where <tt>original.xml</tt> is the original settings file name
2198 (excluding path), and <tt>x.y-platform</tt> is the version of the old
2199 format of the settings file (before auto-conversion).
2200
2201 If the given backup file already exists, this method will try to add the
2202 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
2203 0 to 9) and copy it again until it succeeds. If all suffixes are
2204 occupied, or if any other copy error occurs, this method will return a
2205 failure.
2206
2207 If the copy operation succeeds, the @a bakFileName return argument will
2208 receive a full path to the created backup file (for informational
2209 purposes). Note that this will happen even if the subsequent
2210 <link to="#saveSettings()"/> call performed by this method after the
2211 copy operation, fails.
2212
2213 <note>
2214 The VirtualBox API never calls this method. It is intended purely for
2215 the purposes of creating backup copies of the settings files by
2216 front-ends before saving the results of the automatically performed
2217 settings conversion to disk.
2218 </note>
2219
2220 <see>settingsFileVersion</see>
2221 </desc>
2222 <param name="bakFileName" type="wstring" dir="return">
2223 <desc>Full path to the created backup copy.</desc>
2224 </param>
2225 </method>
2226
2227 </interface>
2228
2229 <!--
2230 // IMachine
2231 /////////////////////////////////////////////////////////////////////////
2232 -->
2233
2234 <enumerator
2235 name="IMachineEnumerator" type="IMachine"
2236 uuid="1b554149-be0a-4465-9252-9ff8f420af55"
2237 />
2238
2239 <collection
2240 name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
2241 uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
2242 readonly="yes"
2243 />
2244
2245 <interface
2246 name="IInternalMachineControl" extends="$unknown"
2247 uuid="de04566a-7125-444b-949e-34e9f3ec3676"
2248 internal="yes"
2249 wsmap="suppress"
2250 >
2251 <method name="updateState">
2252 <desc>
2253 Updates the VM state.
2254 <note>
2255 This operation will also update the settings file with
2256 the correct information about the saved state file
2257 and delete this file from disk when appropriate.
2258 </note>
2259 </desc>
2260 <param name="state" type="MachineState" dir="in"/>
2261 </method>
2262
2263 <method name="getIPCId">
2264 <param name="id" type="wstring" dir="return"/>
2265 </method>
2266
2267 <method name="runUSBDeviceFilters">
2268 <desc>
2269 Asks the server to run USB devices filters of the associated
2270 machine against the given USB device and tell if there is
2271 a match.
2272 <note>
2273 Intended to be used only for remote USB devices. Local
2274 ones don't require to call this method (this is done
2275 implicitly by the Host and USBProxyService).
2276 </note>
2277 </desc>
2278 <param name="device" type="IUSBDevice" dir="in"/>
2279 <param name="matched" type="boolean" dir="out"/>
2280 <param name="maskedInterfaces" type="unsigned long" dir="out"/>
2281 </method>
2282
2283 <method name="captureUSBDevice">
2284 <desc>
2285 Requests a capture of the given host USB device.
2286 When the request is completed, the VM process will
2287 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
2288 notification.
2289 </desc>
2290 <param name="id" type="uuid" dir="in"/>
2291 </method>
2292
2293 <method name="detachUSBDevice">
2294 <desc>
2295 Notification that a VM is going to detach (done = false) or has
2296 already detached (done = true) the given USB device.
2297 When the done = true request is completed, the VM process will
2298 get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
2299 notification.
2300 <note>
2301 In the done = true case, the server must run its own filters
2302 and filters of all VMs but this one on the detached device
2303 as if it were just attached to the host computer.
2304 </note>
2305 </desc>
2306 <param name="id" type="uuid" dir="in"/>
2307 <param name="done" type="boolean" dir="in"/>
2308 </method>
2309
2310 <method name="autoCaptureUSBDevices">
2311 <desc>
2312 Requests a capture all matching USB devices attached to the host.
2313 When the request is completed, the VM process will
2314 get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
2315 notification per every captured device.
2316 </desc>
2317 </method>
2318
2319 <method name="detachAllUSBDevices">
2320 <desc>
2321 Notification that a VM that is being powered down. The done
2322 parameter indicates whether which stage of the power down
2323 we're at. When done = false the VM is announcing its
2324 intentions, while when done = true the VM is reporting
2325 what it has done.
2326 <note>
2327 In the done = true case, the server must run its own filters
2328 and filters of all VMs but this one on all detach devices as
2329 if they were just attached to the host computer.
2330 </note>
2331 </desc>
2332 <param name="done" type="boolean" dir="in"/>
2333 </method>
2334
2335 <method name="onSessionEnd">
2336 <desc>
2337 Triggered by the given session object when the session is about
2338 to close normally.
2339 </desc>
2340 <param name="session" type="ISession" dir="in">
2341 <desc>Session that is being closed</desc>
2342 </param>
2343 <param name="progress" type="IProgress" dir="return">
2344 <desc>
2345 Used to wait until the corresponding machine is actually
2346 deassociated from the given session on the server.
2347 Returned only when this session is a direct one.
2348 </desc>
2349 </param>
2350 </method>
2351
2352 <method name="beginSavingState">
2353 <desc>
2354 Called by the VM process to inform the server it wants to
2355 save the current state and stop the VM execution.
2356 </desc>
2357 <param name="progress" type="IProgress" dir="in">
2358 <desc>
2359 Progress object created by the VM process to wait until
2360 the state is saved.
2361 </desc>
2362 </param>
2363 <param name="stateFilePath" type="wstring" dir="out">
2364 <desc>
2365 File path the VM process must save the execution state to.
2366 </desc>
2367 </param>
2368 </method>
2369
2370 <method name="endSavingState">
2371 <desc>
2372 Called by the VM process to inform the server that saving
2373 the state previously requested by #beginSavingState is either
2374 successfully finished or there was a failure.
2375 </desc>
2376
2377 <param name="success" type="boolean" dir="in">
2378 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
2379 </param>
2380 </method>
2381
2382 <method name="adoptSavedState">
2383 <desc>
2384 Gets called by IConsole::adoptSavedState.
2385 </desc>
2386 <param name="savedStateFile" type="wstring" dir="in">
2387 <desc>Path to the saved state file to adopt.</desc>
2388 </param>
2389 </method>
2390
2391 <method name="beginTakingSnapshot">
2392 <desc>
2393 Called by the VM process to inform the server it wants to
2394 take a snapshot.
2395 </desc>
2396 <param name="initiator" type="IConsole" dir="in">
2397 <desc>The console object that initiated this call.</desc>
2398 </param>
2399 <param name="name" type="wstring" dir="in">
2400 <desc>Snapshot name</desc>
2401 </param>
2402 <param name="description" type="wstring" dir="in">
2403 <desc>Snapshot description</desc>
2404 </param>
2405 <param name="progress" type="IProgress" dir="in">
2406 <desc>
2407 Progress object created by the VM process to wait until
2408 the state is saved (only for online snapshots).
2409 </desc>
2410 </param>
2411 <param name="stateFilePath" type="wstring" dir="out">
2412 <desc>
2413 File path the VM process must save the execution state to.
2414 </desc>
2415 </param>
2416 <param name="serverProgress" type="IProgress" dir="out">
2417 <desc>
2418 Progress object created by the server process to wait until
2419 the snapshot is taken (VDI diff creation, etc.).
2420 </desc>
2421 </param>
2422 </method>
2423
2424 <method name="endTakingSnapshot">
2425 <desc>
2426 Called by the VM process to inform the server that the snapshot
2427 previously requested by #beginTakingSnapshot is either
2428 successfully taken or there was a failure.
2429 </desc>
2430
2431 <param name="success" type="boolean" dir="in">
2432 <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
2433 </param>
2434 </method>
2435
2436 <method name="discardSnapshot">
2437 <desc>
2438 Gets called by IConsole::discardSnapshot.
2439 </desc>
2440 <param name="initiator" type="IConsole" dir="in">
2441 <desc>The console object that initiated this call.</desc>
2442 </param>
2443 <param name="id" type="uuid" dir="in">
2444 <desc>UUID of the snapshot to discard.</desc>
2445 </param>
2446 <param name="machineState" type="MachineState" dir="out">
2447 <desc>New machine state after this operation is started.</desc>
2448 </param>
2449 <param name="progress" type="IProgress" dir="return">
2450 <desc>Progress object to track the operation completion.</desc>
2451 </param>
2452 </method>
2453
2454 <method name="discardCurrentState">
2455 <desc>
2456 Gets called by IConsole::discardCurrentState.
2457 </desc>
2458 <param name="initiator" type="IConsole" dir="in">
2459 <desc>The console object that initiated this call.</desc>
2460 </param>
2461 <param name="machineState" type="MachineState" dir="out">
2462 <desc>New machine state after this operation is started.</desc>
2463 </param>
2464 <param name="progress" type="IProgress" dir="return">
2465 <desc>Progress object to track the operation completion.</desc>
2466 </param>
2467 </method>
2468
2469 <method name="discardCurrentSnapshotAndState">
2470 <desc>
2471 Gets called by IConsole::discardCurrentSnapshotAndState.
2472 </desc>
2473 <param name="initiator" type="IConsole" dir="in">
2474 <desc>The console object that initiated this call.</desc>
2475 </param>
2476 <param name="machineState" type="MachineState" dir="out">
2477 <desc>New machine state after this operation is started.</desc>
2478 </param>
2479 <param name="progress" type="IProgress" dir="return">
2480 <desc>Progress object to track the operation completion.</desc>
2481 </param>
2482 </method>
2483
2484 <method name="pullGuestProperties">
2485 <desc>
2486 Get the list of the guest properties matching a set of patterns along
2487 with their values, timestamps and flags and give responsibility for
2488 managing properties to the console.
2489 </desc>
2490 <param name="name" type="wstring" dir="out" safearray="yes">
2491 <desc>
2492 The names of the properties returned.
2493 </desc>
2494 </param>
2495 <param name="value" type="wstring" dir="out" safearray="yes">
2496 <desc>
2497 The values of the properties returned. The array entries match the
2498 corresponding entries in the @a name array.
2499 </desc>
2500 </param>
2501 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
2502 <desc>
2503 The timestamps of the properties returned. The array entries match
2504 the corresponding entries in the @a name array.
2505 </desc>
2506 </param>
2507 <param name="flags" type="wstring" dir="out" safearray="yes">
2508 <desc>
2509 The flags of the properties returned. The array entries match the
2510 corresponding entries in the @a name array.
2511 </desc>
2512 </param>
2513 </method>
2514
2515 <method name="pushGuestProperties">
2516 <desc>
2517 Set the list of the guest properties matching a set of patterns along
2518 with their values, timestamps and flags and return responsibility for
2519 managing properties to IMachine.
2520 </desc>
2521 <param name="name" type="wstring" dir="in" safearray="yes">
2522 <desc>
2523 The names of the properties returned.
2524 </desc>
2525 </param>
2526 <param name="value" type="wstring" dir="in" safearray="yes">
2527 <desc>
2528 The values of the properties returned. The array entries match the
2529 corresponding entries in the @a name array.
2530 </desc>
2531 </param>
2532 <param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
2533 <desc>
2534 The timestamps of the properties returned. The array entries match
2535 the corresponding entries in the @a name array.
2536 </desc>
2537 </param>
2538 <param name="flags" type="wstring" dir="in" safearray="yes">
2539 <desc>
2540 The flags of the properties returned. The array entries match the
2541 corresponding entries in the @a name array.
2542 </desc>
2543 </param>
2544 </method>
2545 </interface>
2546
2547 <interface
2548 name="IBIOSSettings" extends="$unknown"
2549 uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
2550 wsmap="managed"
2551 >
2552 <desc>
2553 The IBIOSSettings interface represents BIOS settings of the virtual
2554 machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
2555 </desc>
2556 <attribute name="logoFadeIn" type="boolean">
2557 <desc>Fade in flag for BIOS logo animation.</desc>
2558 </attribute>
2559
2560 <attribute name="logoFadeOut" type="boolean">
2561 <desc>Fade out flag for BIOS logo animation.</desc>
2562 </attribute>
2563
2564 <attribute name="logoDisplayTime" type="unsigned long">
2565 <desc>BIOS logo display time in milliseconds (0 = default).</desc>
2566 </attribute>
2567
2568 <attribute name="logoImagePath" type="wstring">
2569 <desc>Local file system path for external BIOS image.</desc>
2570 </attribute>
2571
2572 <attribute name="bootMenuMode" type="BIOSBootMenuMode">
2573 <desc>Mode of the BIOS boot device menu.</desc>
2574 </attribute>
2575
2576 <attribute name="ACPIEnabled" type="boolean">
2577 <desc>ACPI support flag.</desc>
2578 </attribute>
2579
2580 <attribute name="IOAPICEnabled" type="boolean">
2581 <desc>
2582 IO APIC support flag. If set, VirtualBox will provide an IO APIC
2583 and support IRQs above 15.
2584 </desc>
2585 </attribute>
2586
2587 <attribute name="timeOffset" type="long long">
2588 <desc>
2589 Offset in milliseconds from the host system time. This allows for
2590 guests running with a different system date/time than the host.
2591 It is equivalent to setting the system date/time in the BIOS other
2592 than it's not an absolute value but a relative one. Guest Additions
2593 time synchronization also honors this offset.
2594 </desc>
2595 </attribute>
2596
2597 <attribute name="PXEDebugEnabled" type="boolean">
2598 <desc>
2599 PXE debug logging flag. If set, VirtualBox will write extensive
2600 PXE trace information to the release log.
2601 </desc>
2602 </attribute>
2603
2604 <attribute name="IDEControllerType" type="IDEControllerType">
2605 <desc>
2606 Type of the virtual IDE controller. Depending on this value,
2607 VirtualBox will provide different virtual IDE hardware
2608 devices to the guest.
2609 </desc>
2610 </attribute>
2611
2612 </interface>
2613
2614 <interface
2615 name="IMachine" extends="$unknown"
2616 uuid="1e509de4-d96c-4f44-8b94-860194f710ac"
2617 wsmap="managed"
2618 >
2619 <desc>
2620 The IMachine interface represents a virtual machine, or guest, created
2621 in VirtualBox.
2622
2623 This interface is used in two contexts. First of all, a collection of
2624 objects implementing this interface is stored in the
2625 <link to="IVirtualBox::machines"/> attribute which lists all the virtual
2626 machines that are currently registered with this VirtualBox
2627 installation. Also, once a session has been opened for the given virtual
2628 machine (e.g. the virtual machine is running), the machine object
2629 associated with the open session can be queried from the session object;
2630 see <link to="ISession"/> for details.
2631
2632 The main role of this interface is to expose the settings of the virtual
2633 machine and provide methods to change various aspects of the virtual
2634 machine's configuration. For machine objects stored in the
2635 <link to="IVirtualBox::machines"/> collection, all attributes are
2636 read-only unless explicitely stated otherwise in individual attribute
2637 and method descriptions. In order to change a machine setting, a session
2638 for this machine must be opened using one of
2639 <link to="IVirtualBox::openSession"/>,
2640 <link to="IVirtualBox::openRemoteSession"/> or
2641 <link to="IVirtualBox::openExistingSession"/> methdods. After the
2642 session has been successfully opened, a mutable machine object needs to
2643 be queried from the session object and then the desired settings changes
2644 can be applied to the returned object using IMachine attributes and
2645 methods. See the ISession interface description for more information
2646 about sessions.
2647
2648 Note that the IMachine interface does not provide methods to control
2649 virtual machine execution (such as start the machine, or power it
2650 down) -- these methods are grouped in a separate IConsole
2651 interface. Refer to the IConsole interface description to get more
2652 information about this topic.
2653
2654 <see>ISession, IConsole</see>
2655 </desc>
2656
2657 <attribute name="parent" type="IVirtualBox" readonly="yes">
2658 <desc>Associated parent obect.</desc>
2659 </attribute>
2660
2661 <attribute name="accessible" type="boolean" readonly="yes">
2662 <desc>
2663 Whether this virtual machine is currently accessible or not.
2664
2665 The machine is considered to be inaccessible when:
2666 <ul>
2667 <li>It is a registered virtual machine, and
2668 </li>
2669 <li>Its settings file is inaccessible (for example, it is
2670 located on a network share that is not accessible during
2671 VirtualBox startup, or becomes inaccessible later, or if
2672 the settings file can be read but is invalid).
2673 </li>
2674 </ul>
2675
2676 Otherwise, the value of this property is always <tt>true</tt>.
2677
2678 Every time this property is read, the accessibility state of
2679 this machine is re-evaluated. If the returned value is |false|,
2680 the <link to="#accessError"/> property may be used to get the
2681 detailed error information describing the reason of
2682 inaccessibility.
2683
2684 When the machine is inaccessible, only the following properties
2685 can be used on it:
2686 <ul>
2687 <li><link to="#parent"/></li>
2688 <li><link to="#id"/></li>
2689 <li><link to="#settingsFilePath"/></li>
2690 <li><link to="#accessible"/></li>
2691 <li><link to="#accessError"/></li>
2692 </ul>
2693
2694 An attempt to access any other property or method will return
2695 an error.
2696
2697 The only possible action you can perform on an inaccessible
2698 machine is to unregister it using the
2699 <link to="IVirtualBox::unregisterMachine"/> call (or, to check
2700 for the accessibility state once more by querying this
2701 property).
2702
2703 <note>
2704 In the current implementation, once this property returns
2705 <tt>true</tt>, the machine will never become inaccessible
2706 later, even if its settings file cannot be successfully
2707 read/written any more (at least, until the VirtualBox
2708 server is restarted). This limitation may be removed in
2709 future releases.
2710 </note>
2711 </desc>
2712 </attribute>
2713
2714 <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
2715 <desc>
2716 Error information describing the reason of machine
2717 inaccessibility.
2718
2719 Reading this property is only valid after the last call to
2720 <link to="#accessible"/> returned <tt>false</tt> (i.e. the
2721 machine is currently unaccessible). Otherwise, a null
2722 IVirtualBoxErrorInfo object will be returned.
2723 </desc>
2724 </attribute>
2725
2726 <attribute name="name" type="wstring">
2727 <desc>
2728 Name of the virtual machine.
2729
2730 Besides being used for human-readable identification purposes
2731 everywhere in VirtualBox, the virtual machine name is also used
2732 as a name of the machine's settings file and as a name of the
2733 subdirectory this settings file resides in. Thus, every time you
2734 change the value of this property, the settings file will be
2735 renamed once you call <link to="#saveSettings()"/> to confirm the
2736 change. The containing subdirectory will be also renamed, but
2737 only if it has exactly the same name as the settings file
2738 itself prior to changing this property (for backward compatibility
2739 with previous API releases). The above implies the following
2740 limitations:
2741 <ul>
2742 <li>The machine name cannot be empty.</li>
2743 <li>The machine name can contain only characters that are valid
2744 file name characters according to the rules of the file
2745 system used to store VirtualBox configuration.</li>
2746 <li>You cannot have two or more machines with the same name
2747 if they use the same subdirectory for storing the machine
2748 settings files.</li>
2749 <li>You cannot change the name of the machine if it is running,
2750 or if any file in the directory containing the settings file
2751 is being used by another running machine or by any other
2752 process in the host operating system at a time when
2753 <link to="#saveSettings()"/> is called.
2754 </li>
2755 </ul>
2756 If any of the above limitations are hit, <link to="#saveSettings()"/>
2757 will return an appropriate error message explaining the exact
2758 reason and the changes you made to this machine will not be
2759 saved.
2760 <note>
2761 For "legacy" machines created using the
2762 <link to="IVirtualBox::createLegacyMachine()"/> call,
2763 the above naming limitations do not apply because the
2764 machine name does not affect the settings file name.
2765 The settings file name remains the same as it was specified
2766 during machine creation and never changes.
2767 </note>
2768 </desc>
2769 </attribute>
2770
2771 <attribute name="description" type="wstring">
2772 <desc>
2773 Description of the virtual machine.
2774
2775 The description attribute can contain any text and is
2776 typically used to describe the hardware and software
2777 configuration of the virtual machine in detail (i.e. network
2778 settings, versions of the installed software and so on).
2779 </desc>
2780 </attribute>
2781
2782 <attribute name="id" type="uuid" readonly="yes">
2783 <desc>UUID of the virtual machine.</desc>
2784 </attribute>
2785
2786 <attribute name="OSTypeId" type="wstring">
2787 <desc>
2788 User-defined identifier of the Guest OS type.
2789 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
2790 an IGuestOSType object representing details about the given
2791 Guest OS type.
2792 <note>
2793 This value may differ from the value returned by
2794 <link to="IGuest::OSTypeId"/> if Guest Additions are
2795 installed to the guest OS.
2796 </note>
2797 </desc>
2798 </attribute>
2799
2800 <attribute name="memorySize" type="unsigned long">
2801 <desc>System memory size in megabytes.</desc>
2802 </attribute>
2803
2804 <attribute name="memoryBalloonSize" type="unsigned long">
2805 <desc>Initial memory balloon size in megabytes.</desc>
2806 </attribute>
2807
2808 <attribute name="statisticsUpdateInterval" type="unsigned long">
2809 <desc>Initial interval to update guest statistics in seconds.</desc>
2810 </attribute>
2811
2812 <attribute name="VRAMSize" type="unsigned long">
2813 <desc>Video memory size in megabytes.</desc>
2814 </attribute>
2815
2816 <attribute name="MonitorCount" type="unsigned long">
2817 <desc>
2818 Number of virtual monitors.
2819 <note>
2820 Only effective on Windows XP and later guests with
2821 Guest Additions installed.
2822 </note>
2823 </desc>
2824 </attribute>
2825
2826 <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
2827 <desc>Object containing all BIOS settings.</desc>
2828 </attribute>
2829
2830 <attribute name="HWVirtExEnabled" type="TSBool">
2831 <desc>
2832 This setting determines whether VirtualBox will try to make use of
2833 the host CPU's hardware virtualization extensions such as Intel VT-x
2834 and AMD-V. Note that in case such extensions are not available,
2835 they will not be used.
2836 </desc>
2837 </attribute>
2838
2839 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="true">
2840 <desc>
2841 This setting determines whether VirtualBox will try to make use of
2842 the nested paging extension of Intel VT-x and AMD-V. Note that in case
2843 such extensions are not available, they will not be used.
2844 </desc>
2845 </attribute>
2846
2847 <attribute name="PAEEnabled" type="boolean" default="false">
2848 <desc>
2849 This setting determines whether VirtualBox will expose the Physical Address
2850 Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
2851 is not available, it will not be reported.
2852 </desc>
2853 </attribute>
2854
2855 <attribute name="snapshotFolder" type="wstring">
2856 <desc>
2857 Full path to the directory used to store snapshot data
2858 (difrerencing hard disks and saved state files) of this machine.
2859
2860 The initial value of this property is
2861 <tt>&lt;</tt><link to="#settingsFilePath">
2862 path_to_settings_file</link><tt>&gt;/&lt;</tt>
2863 <link to="#id">machine_uuid</link>
2864 <tt>&gt;</tt>.
2865
2866 Currently, it is an error to try to change this property on
2867 a machine that has snapshots (because this would require to
2868 move possibly large files to a different location).
2869 A separate method will be available for this purpose later.
2870
2871 <note>
2872 Setting this property to <tt>null</tt> will restore the
2873 initial value.
2874 </note>
2875 <note>
2876 When setting this property, the specified path can be
2877 absolute (full path) or relative to the directory where the
2878 <link to="#settingsFilePath">machine settings file</link>
2879 is located. When reading this property, a full path is
2880 always returned.
2881 </note>
2882 <note>
2883 The specified path may not exist, it will be created
2884 when necessary.
2885 </note>
2886 </desc>
2887 </attribute>
2888
2889 <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
2890 <desc>VRDP server object.</desc>
2891 </attribute>
2892
2893 <attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
2894 <desc>Collection of hard disks attached to the machine.</desc>
2895 </attribute>
2896
2897 <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
2898 <desc>Associated DVD drive object.</desc>
2899 </attribute>
2900
2901 <attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
2902 <desc>Associated floppy drive object.</desc>
2903 </attribute>
2904
2905 <attribute name="USBController" type="IUSBController" readonly="yes">
2906 <desc>
2907 Associated USB controller object.
2908
2909 <note>
2910 This method may set a @ref com_warnings "warning result code".
2911 </note>
2912 <note>
2913 If USB functionality is not avaliable in the given edition of
2914 VirtualBox, this method will set the result code to @c E_NOTIMPL.
2915 </note>
2916 </desc>
2917 </attribute>
2918
2919 <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
2920 <desc>Associated audio adapter, always present.</desc>
2921 </attribute>
2922
2923 <attribute name="SATAController" type="ISATAController" readonly="yes">
2924 <desc>
2925 Associated SATA controller object.
2926 </desc>
2927 </attribute>
2928
2929 <attribute name="settingsFilePath" type="wstring" readonly="yes">
2930 <desc>
2931 Full name of the file containing machine settings data.
2932 </desc>
2933 </attribute>
2934
2935 <attribute name="settingsFileVersion" type="wstring" readonly="yes">
2936 <desc>
2937 Current version of the format of the settings file of this machine
2938 (<link to="#settingsFilePath"/>).
2939
2940 The version string has the following format:
2941 <pre>
2942 x.y-platform
2943 </pre>
2944 where <tt>x</tt> and <tt>y</tt> are the major and the minor format
2945 versions, and <tt>platform</tt> is the platform identifier.
2946
2947 The current version usually matches the value of the
2948 <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
2949 settings file was created by an older version of VirtualBox and there
2950 was a change of the settings file format since then.
2951
2952 Note that VirtualBox automatically converts settings files from older
2953 versions to the most recent version when reading them (usually at
2954 VirtualBox startup) but it doesn't save the changes back until
2955 you call a method that implicitly saves settings (such as
2956 <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
2957 explicitly. Therefore, if the value of this attribute differs from the
2958 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
2959 means that the settings file was converted but the result of the
2960 conversion is not yet saved to disk.
2961
2962 The above feature may be used by interactive front-ends to inform users
2963 about the settings file format change and offer them to explicitly save
2964 all converted settings files (the global and VM-specific ones),
2965 optionally create bacup copies of the old settings files before saving,
2966 etc.
2967
2968 <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
2969 </desc>
2970 </attribute>
2971
2972 <attribute name="settingsModified" type="boolean" readonly="yes">
2973 <desc>
2974 Whether the settings of this machine have been modified
2975 (but neither yet saved nor discarded).
2976 <note>
2977 Reading this property is only valid on instances returned
2978 by <link to="ISession::machine"/> and on new machines
2979 created by <link to="IVirtualBox::createMachine"/> or opened
2980 by <link to="IVirtualBox::openMachine"/> but not
2981 yet registered, or on unregistered machines after calling
2982 <link to="IVirtualBox::unregisterMachine"/>. For all other
2983 cases, the settigs can never be modified.
2984 </note>
2985 <note>
2986 For newly created unregistered machines, the value of this
2987 property is always TRUE until <link to="#saveSettings()"/>
2988 is called (no matter if any machine settings have been
2989 changed after the creation or not). For opened machines
2990 the value is set to FALSE (and then follows to normal rules).
2991 </note>
2992 </desc>
2993 </attribute>
2994
2995 <attribute name="sessionState" type="SessionState" readonly="yes">
2996 <desc>Current session state for this machine.</desc>
2997 </attribute>
2998
2999 <attribute name="sessionType" type="wstring" readonly="yes">
3000 <desc>
3001 Type of the session. If <link to="#sessionState"/> is
3002 SessionSpawning or SessionOpen, this attribute contains the
3003 same value as passed to the
3004 <link to="IVirtualBox::openRemoteSession()"/> method in the @a
3005 type parameter. If the session was opened directly using
3006 <link to="IVirtualBox::openSession()"/>, or if
3007 <link to="#sessionState"/> is SessionClosed, the value of this
3008 attribute is @c null.
3009 </desc>
3010 </attribute>
3011
3012 <attribute name="sessionPid" type="unsigned long" readonly="yes">
3013 <desc>
3014 Identifier of the session process. This attribute contains the
3015 platform-dependent identifier of the process that has opened a
3016 direct session for this machine using the
3017 <link to="IVirtualBox::openSession()"/> call. The returned value
3018 is only valid if <link to="#sessionState"/> is SessionOpen or
3019 SessionClosing (i.e. a session is currently open or being
3020 closed) by the time this property is read.
3021 </desc>
3022 </attribute>
3023
3024 <attribute name="state" type="MachineState" readonly="yes">
3025 <desc>Current execution state of this machine.</desc>
3026 </attribute>
3027
3028 <attribute name="lastStateChange" type="long long" readonly="yes">
3029 <desc>
3030 Time stamp of the last execution state change,
3031 in milliseconds since 1970-01-01 UTC.
3032 </desc>
3033 </attribute>
3034
3035 <attribute name="stateFilePath" type="wstring" readonly="yes">
3036 <desc>
3037 Full path to the file that stores the execution state of
3038 the machine when it is in the <link to="MachineState::Saved"/>
3039 state.
3040 <note>
3041 When the machine is not in the Saved state, this attribute
3042 <tt>null</tt>.
3043 </note>
3044 </desc>
3045 </attribute>
3046
3047 <attribute name="logFolder" type="wstring" readonly="yes">
3048 <desc>
3049 Full path to the folder that stores a set of rotated log files
3050 recorded during machine execution. The most recent log file is
3051 named <tt>VBox.log</tt>, the previous log file is
3052 named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>
3053 in the current version).
3054 </desc>
3055 </attribute>
3056
3057 <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
3058 <desc>
3059 Current snapshot of this machine.
3060 <note>
3061 A <tt>null</tt> object is returned if the machine doesn't
3062 have snapshots.
3063 </note>
3064 <see><link to="ISnapshot"/></see>
3065 </desc>
3066 </attribute>
3067
3068 <attribute name="snapshotCount" type="unsigned long" readonly="yes">
3069 <desc>
3070 Number of snapshots taken on this machine. Zero means the
3071 machine doesn't have any snapshots.
3072 </desc>
3073 </attribute>
3074
3075 <attribute name="currentStateModified" type="boolean" readonly="yes">
3076 <desc>
3077 Returns <tt>true</tt> if the current state of the machine is not
3078 identical to the state stored in the current snapshot.
3079
3080 The current state is identical to the current snapshot right
3081 after one of the following calls are made:
3082 <ul>
3083 <li><link to="IConsole::discardCurrentState"/> or
3084 <link to="IConsole::discardCurrentSnapshotAndState"/>
3085 </li>
3086 <li><link to="IConsole::takeSnapshot"/> (issued on a
3087 powered off or saved machine, for which
3088 <link to="#settingsModified"/> returns <tt>false</tt>)
3089 </li>
3090 <li><link to="IMachine::setCurrentSnapshot"/>
3091 </li>
3092 </ul>
3093
3094 The current state remains identical until one of the following
3095 happens:
3096 <ul>
3097 <li>settings of the machine are changed</li>
3098 <li>the saved state is discarded</li>
3099 <li>the current snapshot is discarded</li>
3100 <li>an attempt to execute the machine is made</li>
3101 </ul>
3102
3103 <note>
3104 For machines that don't have snapshots, this property is
3105 always <tt>false</tt>.
3106 </note>
3107 </desc>
3108 </attribute>
3109
3110 <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
3111 <desc>
3112 Collection of shared folders for this machine (permanent shared
3113 folders). These folders are shared automatically at machine startup
3114 and available only to the guest OS installed within this machine.
3115
3116 New shared folders are added to the collection using
3117 <link to="#createSharedFolder"/>. Existing shared folders can be
3118 removed using <link to="#removeSharedFolder"/>.
3119 </desc>
3120 </attribute>
3121
3122 <attribute name="clipboardMode" type="ClipboardMode">
3123 <desc>
3124 Synchronization mode between the host OS clipboard
3125 and the guest OS clipboard.
3126 </desc>
3127 </attribute>
3128
3129 <method name="setBootOrder">
3130 <desc>
3131 Puts the given device to the specified position in
3132 the boot order.
3133
3134 To indicate that no device is associated with the given position,
3135 <link to="DeviceType::Null"/> should be used.
3136
3137 @todo setHardDiskBootOrder(), setNetworkBootOrder()
3138 </desc>
3139 <param name="position" type="unsigned long" dir="in">
3140 <desc>
3141 Position in the boot order (<tt>1</tt> to the total number of
3142 devices the machine can boot from, as returned by
3143 <link to="ISystemProperties::maxBootPosition"/>).
3144 </desc>
3145 </param>
3146 <param name="device" type="DeviceType" dir="in">
3147 <desc>
3148 The type of the device used to boot at the given position.
3149 </desc>
3150 </param>
3151 </method>
3152
3153 <method name="getBootOrder" const="yes">
3154 <desc>
3155 Returns the device type that occupies the specified
3156 position in the boot order.
3157
3158 @todo [remove?]
3159 If the machine can have more than one device of the returned type
3160 (such as hard disks), then a separate method should be used to
3161 retrieve the individual device that occupies the given position.
3162
3163 If here are no devices at the given position, then
3164 <link to="DeviceType::Null"/> is returned.
3165
3166 @todo getHardDiskBootOrder(), getNetworkBootOrder()
3167 </desc>
3168 <param name="order" type="unsigned long" dir="in">
3169 <desc>
3170 Position in the boot order (<tt>1</tt> to the total number of
3171 devices the machine can boot from, as returned by
3172 <link to="ISystemProperties::maxBootPosition"/>).
3173 </desc>
3174 </param>
3175 <param name="device" type="DeviceType" dir="return">
3176 <desc>
3177 Device at the given position.
3178 </desc>
3179 </param>
3180 </method>
3181
3182 <method name="attachHardDisk">
3183 <desc>
3184
3185 Attaches a virtual hard disk identified by the given UUID to the
3186 given device slot of the given channel on the given bus. The
3187 specified device slot must not have another disk attached and the
3188 given hard disk must not be already attached to this machine.
3189
3190 See <link to="IHardDisk"/> for detailed information about
3191 attaching hard disks.
3192
3193 <note>You cannot attach a hard disk to a running machine. Also,
3194 you cannot attach a hard disk to a newly created machine until
3195 it is registered.</note>
3196
3197 <note>Attaching a hard disk to a machine creates a <i>lazy</i>
3198 attachment. In particular, no differeincing images are
3199 actually created until <link to="#saveSettings()"/> is called to
3200 commit all changed settings.</note>
3201
3202 </desc>
3203 <param name="id" type="uuid" dir="in">
3204 <desc>UUID of the hard disk to attach.</desc>
3205 </param>
3206 <param name="bus" type="StorageBus" dir="in">
3207 <desc>Type of storage bus to use (IDE or SATA).</desc>
3208 </param>
3209 <param name="channel" type="long" dir="in">
3210 <desc>Channel to attach the hard disk to. For IDE controllers,
3211 this can either be 0 or 1, for the primary or secondary controller,
3212 respectively.</desc>
3213 </param>
3214 <param name="device" type="long" dir="in">
3215 <desc>Device slot in the given channel to attach the hard disk to.
3216 For IDE devices, within each channel (0 or 1), this can again be
3217 0 or 1, for master or slave, respectively.</desc>
3218 </param>
3219 </method>
3220
3221 <method name="getHardDisk" const="yes">
3222 <desc>
3223 Returns the hard disk attached to the
3224 given controller under the specified device number.
3225 </desc>
3226 <param name="bus" type="StorageBus" dir="in"/>
3227 <param name="channel" type="long" dir="in"/>
3228 <param name="device" type="long" dir="in"/>
3229 <param name="hardDisk" type="IHardDisk" dir="return"/>
3230 </method>
3231
3232 <method name="detachHardDisk">
3233 <desc>
3234
3235 Detaches the hard disk drive attached to the given device slot
3236 of the given controller.
3237
3238 See <link to="IHardDisk"/> for detailed information about
3239 attaching hard disks.
3240
3241 <note>You cannot detach a hard disk from a running
3242 machine.</note>
3243
3244 <note>
3245 Detaching a hard disk from a machine creates a <i>lazy</i>
3246 detachment. In particular, if the detached hard disk is a
3247 differencing hard disk, it is not actually deleted until
3248 <link to="#saveSettings()"/> is called to commit all changed settings.
3249 Keep in mind, that doing <link to="#saveSettings()"/> will
3250 <b>physically delete</b> all detached differencing hard disks,
3251 so be careful.
3252 </note>
3253
3254 </desc>
3255 <param name="bus" type="StorageBus" dir="in">
3256 <desc>Bus to dettach the hard disk from.</desc>
3257 </param>
3258 <param name="channel" type="long" dir="in">
3259 <desc>Channel number to dettach the hard disk from.</desc>
3260 </param>
3261 <param name="device" type="long" dir="in">
3262 <desc>Device slot number to dettach the hard disk from.</desc>
3263 </param>
3264 </method>
3265
3266 <method name="getNetworkAdapter" const="yes">
3267 <desc>
3268 Returns the network adapter associated with the given slot.
3269 Slots are numbered sequentially, starting with zero. The total
3270 number of adapters per every machine is defined by the
3271 <link to="ISystemProperties::networkAdapterCount"/> property,
3272 so the maximum slot number is one less than that property's value.
3273 </desc>
3274 <param name="slot" type="unsigned long" dir="in"/>
3275 <param name="adapter" type="INetworkAdapter" dir="return"/>
3276 </method>
3277
3278 <method name="getSerialPort" const="yes">
3279 <desc>
3280 Returns the serial port associated with the given slot.
3281 Slots are numbered sequentially, starting with zero. The total
3282 number of serial ports per every machine is defined by the
3283 <link to="ISystemProperties::serialPortCount"/> property,
3284 so the maximum slot number is one less than that property's value.
3285 </desc>
3286 <param name="slot" type="unsigned long" dir="in"/>
3287 <param name="port" type="ISerialPort" dir="return"/>
3288 </method>
3289
3290 <method name="getParallelPort" const="yes">
3291 <desc>
3292 Returns the parallel port associated with the given slot.
3293 Slots are numbered sequentially, starting with zero. The total
3294 number of parallel ports per every machine is defined by the
3295 <link to="ISystemProperties::parallelPortCount"/> property,
3296 so the maximum slot number is one less than that property's value.
3297 </desc>
3298 <param name="slot" type="unsigned long" dir="in"/>
3299 <param name="port" type="IParallelPort" dir="return"/>
3300 </method>
3301
3302 <method name="getNextExtraDataKey">
3303 <desc>
3304 Returns the machine-specific extra data key name following the
3305 supplied key.
3306
3307 An error is returned if the supplied @a key does not exist. @c NULL is
3308 returned in @a nextKey if the supplied key is the last key. When
3309 supplying @c NULL for the @a key, the first key item is returned in @a
3310 nextKey (if there is any). @a nextValue is an optional parameter and
3311 if supplied, the next key's value is returned in it.
3312 </desc>
3313 <param name="key" type="wstring" dir="in">
3314 <desc>Name of the data key to follow.</desc>
3315 </param>
3316 <param name="nextKey" type="wstring" dir="out">
3317 <desc>Name of the next data key.</desc>
3318 </param>
3319 <param name="nextValue" type="wstring" dir="out">
3320 <desc>Value of the next data key.</desc>
3321 </param>
3322 </method>
3323
3324 <method name="getExtraData">
3325 <desc>
3326 Returns associated machine-specific extra data.
3327
3328 If the reuqested data @a key does not exist, this function will
3329 succeed and return @c NULL in the @a value argument.
3330 </desc>
3331 <param name="key" type="wstring" dir="in">
3332 <desc>Name of the data key to get.</desc>
3333 </param>
3334 <param name="value" type="wstring" dir="return">
3335 <desc>Value of the requested data key.</desc>
3336 </param>
3337 </method>
3338
3339 <method name="setExtraData">
3340 <desc>
3341 Sets associated machine-specific extra data.
3342
3343 If you pass @c NULL as a key @a vaule, the given @a key will be
3344 deleted.
3345
3346 <note>
3347 Before performing the actual data change, this method will ask all
3348 registered callbacks using the
3349 <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
3350 notification for a permission. If one of the callbacks refuses the
3351 new value, the change will not be performed.
3352 </note>
3353 <note>
3354 On success, the
3355 <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
3356 is called to inform all registered callbacks about a successful data
3357 change.
3358 </note>
3359 <note>
3360 This method can be called outside the machine session and therefore
3361 it's a caller's responsibility to handle possible race conditions
3362 when several clients change the same key at the same time.
3363 </note>
3364 </desc>
3365 <param name="key" type="wstring" dir="in">
3366 <desc>Name of the data key to set.</desc>
3367 </param>
3368 <param name="value" type="wstring" dir="in">
3369 <desc>Value to assign to the key.</desc>
3370 </param>
3371 </method>
3372
3373 <method name="saveSettings">
3374 <desc>
3375 Saves any changes to machine settings made since the session
3376 has been opened or a new machine has been created, or since the
3377 last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>.
3378 For registered machines, new settings become visible to all
3379 other VirtualBox clients after successful invocation of this
3380 method.
3381 <note>
3382 The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/>
3383 notification event after the configuration has been successfully
3384 saved (only for registered machines).
3385 </note>
3386 <note>
3387 Calling this method is only valid on instances returned
3388 by <link to="ISession::machine"/> and on new machines
3389 created by <link to="IVirtualBox::createMachine"/> but not
3390 yet registered, or on unregistered machines after calling
3391 <link to="IVirtualBox::unregisterMachine"/>.
3392 </note>
3393 </desc>
3394 </method>
3395
3396 <method name="saveSettingsWithBackup">
3397 <desc>
3398 Creates a backup copy of the machine settings file (<link
3399 to="#settingsFilePath"/>) in case of auto-conversion, and then calls
3400 <link to="#saveSettings()"/>.
3401
3402 Note that the backup copy is created <b>only</b> if the settings file
3403 auto-conversion took place (see <link to="#settingsFileVersion"/> for
3404 details). Otherwise, this call is fully equivalent to
3405 <link to="#saveSettings()"/> and no backup copying is done.
3406
3407 The backup copy is created in the same directory where the original
3408 settings file is located. It is given the following file name:
3409 <pre>
3410 original.xml.x.y-platform.bak
3411 </pre>
3412 where <tt>original.xml</tt> is the original settings file name
3413 (excluding path), and <tt>x.y-platform</tt> is the version of the old
3414 format of the settings file (before auto-conversion).
3415
3416 If the given backup file already exists, this method will try to add the
3417 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
3418 0 to 9) and copy it again until it succeeds. If all suffixes are
3419 occupied, or if any other copy error occurs, this method will return a
3420 failure.
3421
3422 If the copy operation succeeds, the @a bakFileName return argument will
3423 receive a full path to the created backup file (for informational
3424 purposes). Note that this will happen even if the subsequent
3425 <link to="#saveSettings()"/> call performed by this method after the
3426 copy operation, fails.
3427
3428 <note>
3429 The VirtualBox API never calls this method. It is intended purely for
3430 the purposes of creating backup copies of the settings files by
3431 front-ends before saving the results of the automatically performed
3432 settings conversion to disk.
3433 </note>
3434
3435 <see>settingsFileVersion</see>
3436 </desc>
3437 <param name="bakFileName" type="wstring" dir="return">
3438 <desc>Full path to the created backup copy.</desc>
3439 </param>
3440 </method>
3441
3442 <method name="discardSettings">
3443 <desc>
3444 Discards any changes to the machine settings made since the session
3445 has been opened or since the last call to <link to="#saveSettings()"/>
3446 or <link to="#discardSettings"/>.
3447 <note>
3448 Calling this method is only valid on instances returned
3449 by <link to="ISession::machine"/> and on new machines
3450 created by <link to="IVirtualBox::createMachine"/> or
3451 opened by <link to="IVirtualBox::openMachine"/> but not
3452 yet registered, or on unregistered machines after calling
3453 <link to="IVirtualBox::unregisterMachine"/>.
3454 </note>
3455 </desc>
3456 </method>
3457
3458 <method name="deleteSettings">
3459 <desc>
3460 Deletes the settings file of this machine from disk.
3461 The machine must not be registered in order for this operation
3462 to succeed.
3463 <note>
3464 <link to="#settingsModified"/> will return TRUE after this
3465 method successfully returns.
3466 </note>
3467 <note>
3468 Calling this method is only valid on instances returned
3469 by <link to="ISession::machine"/> and on new machines
3470 created by <link to="IVirtualBox::createMachine"/> or
3471 opened by <link to="IVirtualBox::openMachine"/> but not
3472 yet registered, or on unregistered machines after calling
3473 <link to="IVirtualBox::unregisterMachine"/>.
3474 </note>
3475 <note>
3476 The deleted machine settings file can be restored (saved again)
3477 by calling <link to="#saveSettings()"/>.
3478 </note>
3479 </desc>
3480 </method>
3481
3482 <method name="getSnapshot">
3483 <desc>
3484 Returns a snapshot of this machine with the given UUID.
3485 A <tt>null</tt> UUID can be used to obtain the first snapshot
3486 taken on this machine. This is useful if you want to traverse
3487 the whole tree of snapshots starting from the root.
3488 </desc>
3489 <param name="id" type="uuid" dir="in">
3490 <desc>UUID of the snapshot to get</desc>
3491 </param>
3492 <param name="snapshot" type="ISnapshot" dir="return">
3493 <desc>Snapshot object with the given UUID.</desc>
3494 </param>
3495 </method>
3496
3497 <method name="findSnapshot">
3498 <desc>
3499 Returns a snapshot of this machine with the given name.
3500 </desc>
3501 <param name="name" type="wstring" dir="in">
3502 <desc>Name of the snapshot to find</desc>
3503 </param>
3504 <param name="snapshot" type="ISnapshot" dir="return">
3505 <desc>Snapshot object with the given name.</desc>
3506 </param>
3507 </method>
3508
3509 <method name="setCurrentSnapshot">
3510 <desc>
3511 Sets the current snapshot of this machine.
3512 <note>
3513 In the current implementation, this operation is not
3514 implemented.
3515 </note>
3516 </desc>
3517 <param name="id" type="uuid" dir="in">
3518 <desc>UUID of the snapshot to set as the current snapshot.</desc>
3519 </param>
3520 </method>
3521
3522 <method name="createSharedFolder">
3523 <desc>
3524 Creates a new permanent shared folder by associating the given logical
3525 name with the given host path, adds it to the collection of shared
3526 folders and starts sharing it. Refer to the description of
3527 <link to="ISharedFolder"/> to read more about logical names.
3528 </desc>
3529 <param name="name" type="wstring" dir="in">
3530 <desc>Unique logical name of the shared folder.</desc>
3531 </param>
3532 <param name="hostPath" type="wstring" dir="in">
3533 <desc>Full path to the shared folder in the host file system.</desc>
3534 </param>
3535 <param name="writable" type="boolean" dir="in">
3536 <desc>Whether the share is writable or readonly</desc>
3537 </param>
3538 </method>
3539
3540 <method name="removeSharedFolder">
3541 <desc>
3542 Removes the permanent shared folder with the given name previously
3543 created by <link to="#createSharedFolder"/> from the collection of
3544 shared folders and stops sharing it.
3545 </desc>
3546 <param name="name" type="wstring" dir="in">
3547 <desc>Logical name of the shared folder to remove.</desc>
3548 </param>
3549 </method>
3550
3551 <method name="canShowConsoleWindow">
3552 <desc>
3553 Returns @c true if the VM console process can activate the
3554 console window and bring it to foreground on the desktop of
3555 the host PC.
3556 <note>
3557 This method will fail if a session for this machine is not
3558 currently open.
3559 </note>
3560 </desc>
3561 <param name="canShow" type="boolean" dir="return">
3562 <desc>
3563 @c true if the console window can be shown and @c
3564 false otherwise.
3565 </desc>
3566 </param>
3567 </method>
3568
3569 <method name="showConsoleWindow">
3570 <desc>
3571 Activates the console window and brings it to foreground on
3572 the desktop of the host PC. Many modern window managers on
3573 many platforms implement some sort of focus stealing
3574 prevention logic, so that it may be impossible to activate
3575 a window without the help of the currently active
3576 application. In this case, this method will return a non-zero
3577 identifier that represents the top-level window of the VM
3578 console process. The caller, if it represents a currently
3579 active process, is responsible to use this identifier (in a
3580 platform-dependent manner) to perform actual window
3581 activation.
3582 <note>
3583 This method will fail if a session for this machine is not
3584 currently open.
3585 </note>
3586 </desc>
3587 <param name="winId" type="unsigned long long" dir="return">
3588 <desc>
3589 Platform-dependent identifier of the top-level VM console
3590 window, or zero if this method has performed all actions
3591 necessary to implement the <i>show window</i> semantics for
3592 the given platform and/or VirtualBox front-end.
3593 </desc>
3594 </param>
3595 </method>
3596
3597 <method name="getGuestProperty">
3598 <desc>
3599 Reads an entry from the machine's guest property store.
3600 </desc>
3601 <param name="name" type="wstring" dir="in">
3602 <desc>
3603 The name of the property to read.
3604 </desc>
3605 </param>
3606 <param name="value" type="wstring" dir="out">
3607 <desc>
3608 The value of the property. If the property does not exist then this
3609 will be empty.
3610 </desc>
3611 </param>
3612 <param name="timestamp" type="unsigned long long" dir="out">
3613 <desc>
3614 The time at which the property was last modified, as seen by the
3615 server process.
3616 </desc>
3617 </param>
3618 <param name="flags" type="wstring" dir="out">
3619 <desc>
3620 Additional property parameters, passed as a comma-separated list of
3621 "name=value" type entries.
3622 </desc>
3623 </param>
3624 </method>
3625
3626 <method name="getGuestPropertyValue">
3627 <desc>
3628 Reads a value from the machine's guest property store.
3629 </desc>
3630 <param name="property" type="wstring" dir="in">
3631 <desc>
3632 The name of the property to read.
3633 </desc>
3634 </param>
3635 <param name="value" type="wstring" dir="return">
3636 <desc>
3637 The value of the property. If the property does not exist then this
3638 will be empty.
3639 </desc>
3640 </param>
3641 </method>
3642
3643 <method name="getGuestPropertyTimestamp">
3644 <desc>
3645 Reads a property timestamp from the machine's guest property store.
3646 </desc>
3647 <param name="property" type="wstring" dir="in">
3648 <desc>
3649 The name of the property to read.
3650 </desc>
3651 </param>
3652 <param name="value" type="unsigned long long" dir="return">
3653 <desc>
3654 The timestamp. If the property does not exist then this will be
3655 empty.
3656 </desc>
3657 </param>
3658 </method>
3659
3660 <method name="setGuestProperty">
3661 <desc>
3662 Sets, changes or deletes an entry in the machine's guest property
3663 store.
3664 </desc>
3665 <param name="property" type="wstring" dir="in">
3666 <desc>
3667 The name of the property to set, change or delete.
3668 </desc>
3669 </param>
3670 <param name="value" type="wstring" dir="in">
3671 <desc>
3672 The new value of the property to set, change or delete. If the
3673 property does not yet exist and value is non-empty, it will be
3674 created. If the value is empty, the key will be deleted if it
3675 exists.
3676 </desc>
3677 </param>
3678 <param name="flags" type="wstring" dir="in">
3679 <desc>
3680 Additional property parameters, passed as a comma-separated list of
3681 "name=value" type entries.
3682 </desc>
3683 </param>
3684 </method>
3685
3686 <method name="setGuestPropertyValue">
3687 <desc>
3688 Sets, changes or deletes a value in the machine's guest property
3689 store. The flags field will be left unchanged or created empty for a
3690 new property.
3691 </desc>
3692 <param name="property" type="wstring" dir="in">
3693 <desc>
3694 The name of the property to set, change or delete.
3695 </desc>
3696 </param>
3697 <param name="value" type="wstring" dir="in">
3698 <desc>
3699 The new value of the property to set, change or delete. If the
3700 property does not yet exist and value is non-empty, it will be
3701 created. If value is empty, the property will be deleted if it
3702 exists.
3703 </desc>
3704 </param>
3705 </method>
3706
3707 <method name="enumerateGuestProperties">
3708 <desc>
3709 Return a list of the guest properties matching a set of patterns along
3710 with their values, timestamps and flags.
3711 </desc>
3712 <param name="patterns" type="wstring" dir="in">
3713 <desc>
3714 The patterns to match the properties against as a comma-separated
3715 string with no spaces. If this is empty, all properties currently
3716 set will be returned.
3717 </desc>
3718 </param>
3719 <param name="name" type="wstring" dir="out" safearray="yes">
3720 <desc>
3721 The names of the properties returned.
3722 </desc>
3723 </param>
3724 <param name="value" type="wstring" dir="out" safearray="yes">
3725 <desc>
3726 The values of the properties returned. The array entries match the
3727 corresponding entries in the @a name array.
3728 </desc>
3729 </param>
3730 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
3731 <desc>
3732 The timestamps of the properties returned. The array entries match
3733 the corresponding entries in the @a name array.
3734 </desc>
3735 </param>
3736 <param name="flags" type="wstring" dir="out" safearray="yes">
3737 <desc>
3738 The flags of the properties returned. The array entries match the
3739 corresponding entries in the @a name array.
3740 </desc>
3741 </param>
3742 </method>
3743 </interface>
3744
3745 <!--
3746 // IConsole
3747 /////////////////////////////////////////////////////////////////////////
3748 -->
3749
3750 <interface
3751 name="IConsoleCallback" extends="$unknown"
3752 uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
3753 wsmap="suppress"
3754 >
3755
3756 <method name="onMousePointerShapeChange">
3757 <desc>
3758 Notification when the guest mouse pointer shape has
3759 changed. The new shape data is given.
3760 </desc>
3761 <param name="visible" type="boolean" dir="in">
3762 <desc>
3763 Flag whether the pointer is visible.
3764 </desc>
3765 </param>
3766 <param name="alpha" type="boolean" dir="in">
3767 <desc>
3768 Flag whether the pointer has an alpha channel.
3769 </desc>
3770 </param>
3771 <param name="xHot" type="unsigned long" dir="in">
3772 <desc>
3773 The pointer hot spot x coordinate.
3774 </desc>
3775 </param>
3776 <param name="yHot" type="unsigned long" dir="in">
3777 <desc>
3778 The pointer hot spot y coordinate.
3779 </desc>
3780 </param>
3781 <param name="width" type="unsigned long" dir="in">
3782 <desc>
3783 Width of the pointer shape in pixels.
3784 </desc>
3785 </param>
3786 <param name="height" type="unsigned long" dir="in">
3787 <desc>
3788 Height of the pointer shape in pixels.
3789 </desc>
3790 </param>
3791 <param name="shape" type="octet" mod="ptr" dir="in">
3792 <desc>
3793 Address of the shape buffer.
3794
3795 The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
3796
3797 For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
3798 For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
3799
3800 AND mask presents for pointers with alpha channel, so if the callback does not
3801 support alpha, the pointer could be displayed as a normal color pointer.
3802
3803 The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
3804 therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
3805 end of any scanline are undefined.
3806
3807 The XOR mask follows the AND mask on the next 4 bytes aligned offset:
3808 <tt>uint8_t *pXor = pAnd + (cbAnd + 3) &amp; ~3</tt>
3809 Bytes in the gap between the AND and the XOR mask are undefined.
3810 XOR mask scanlines have no gap between them and size of XOR mask is:
3811 <tt>cXor = width * 4 * height</tt>.
3812
3813 <note>
3814 If 'shape' is equal to 0, only pointer visibility is being changed.
3815 </note>
3816 </desc>
3817 </param>
3818 </method>
3819
3820 <method name="onMouseCapabilityChange">
3821 <desc>
3822 Notification when the mouse capabilities reported by the
3823 guest have changed. The new capabilities are passed.
3824 </desc>
3825 <param name="supportsAbsolute" type="boolean" dir="in"/>
3826 <param name="needsHostCursor" type="boolean" dir="in"/>
3827 </method>
3828
3829 <method name="onKeyboardLedsChange">
3830 <desc>
3831 Notification when the guest OS executes the KBD_CMD_SET_LEDS command
3832 to alter the state of the keyboard LEDs.
3833 </desc>
3834 <param name="numLock" type="boolean" dir="in"/>
3835 <param name="capsLock" type="boolean" dir="in"/>
3836 <param name="scrollLock" type="boolean" dir="in"/>
3837 </method>
3838
3839 <method name="onStateChange">
3840 <desc>
3841 Notification when the execution state of the machine has changed.
3842 The new state will be given.
3843 </desc>
3844 <param name="state" type="MachineState" dir="in"/>
3845 </method>
3846
3847 <method name="onAdditionsStateChange">
3848 <desc>
3849 Notification when a Guest Additions property changes.
3850 Interested callees should query IGuest attributes to
3851 find out what has changed.
3852 </desc>
3853 </method>
3854
3855 <method name="onDVDDriveChange">
3856 <desc>
3857 Notification when a property of the
3858 virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
3859 Interested callees should use IDVDDrive methods to find out what has
3860 changed.
3861 </desc>
3862 </method>
3863
3864 <method name="onFloppyDriveChange">
3865 <desc>
3866 Notification when a property of the
3867 virtual <link to="IMachine::FloppyDrive">floppy drive</link> changes.
3868 Interested callees should use IFloppyDrive methods to find out what
3869 has changed.
3870 </desc>
3871 </method>
3872
3873 <method name="onNetworkAdapterChange">
3874 <desc>
3875 Notification when a property of one of the
3876 virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
3877 changes. Interested callees should use INetworkAdapter methods and
3878 attributes to find out what has changed.
3879 </desc>
3880 <param name="networkAdapter" type="INetworkAdapter" dir="in">
3881 <desc>Network adapter that is subject to change.</desc>
3882 </param>
3883 </method>
3884
3885 <method name="onSerialPortChange">
3886 <desc>
3887 Notification when a property of one of the
3888 virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
3889 Interested callees should use ISerialPort methods and attributes
3890 to find out what has changed.
3891 </desc>
3892 <param name="serialPort" type="ISerialPort" dir="in">
3893 <desc>Serial port that is subject to change.</desc>
3894 </param>
3895 </method>
3896
3897 <method name="onParallelPortChange">
3898 <desc>
3899 Notification when a property of one of the
3900 virtual <link to="IMachine::getParallelPort">parallel ports</link>
3901 changes. Interested callees should use ISerialPort methods and
3902 attributes to find out what has changed.
3903 </desc>
3904 <param name="parallelPort" type="IParallelPort" dir="in">
3905 <desc>Parallel port that is subject to change.</desc>
3906 </param>
3907 </method>
3908
3909 <method name="onVRDPServerChange">
3910 <desc>
3911 Notification when a property of the
3912 <link to="IMachine::VRDPServer">VRDP server</link> changes.
3913 Interested callees should use IVRDPServer methods and attributes to
3914 find out what has changed.
3915 </desc>
3916 </method>
3917
3918 <method name="onUSBControllerChange">
3919 <desc>
3920 Notification when a property of the virtual
3921 <link to="IMachine::USBController">USB controller</link> changes.
3922 Interested callees should use IUSBController methods and attributes to
3923 find out what has changed.
3924 </desc>
3925 </method>
3926
3927 <method name="onUSBDeviceStateChange">
3928 <desc>
3929 Notification when a USB device is attached to or detached from
3930 the virtual USB controller.
3931
3932 This notification is sent as a result of the indirect
3933 request to attach the device because it matches one of the
3934 machine USB filters, or as a result of the direct request
3935 issued by <link to="IConsole::attachUSBDevice"/> or
3936 <link to="IConsole::detachUSBDevice"/>.
3937
3938 This notification is sent in case of both a succeeded and a
3939 failed request completion. When the request succeeds, the @a
3940 error parameter is @c null, and the given device has been
3941 already added to (when @a attached is @c true) or removed from
3942 (when @a attached is @c false) the collection represented by
3943 <link to="IConsole::USBDevices"/>. On failure, the collection
3944 doesn't change and the @a error perameter represents the error
3945 message describing the failure.
3946
3947 </desc>
3948 <param name="device" type="IUSBDevice" dir="in">
3949 <desc>Device that is subject to state change.</desc>
3950 </param>
3951 <param name="attached" type="boolean" dir="in">
3952 <desc>
3953 <tt>true</tt> if the device was attached
3954 and <tt>false</tt> otherwise.
3955 </desc>
3956 </param>
3957 <param name="error" type="IVirtualBoxErrorInfo" dir="in">
3958 <desc>
3959 <tt>null</tt> on success or an error message object on
3960 failure.
3961 </desc>
3962 </param>
3963 </method>
3964
3965 <method name="onSharedFolderChange">
3966 <desc>
3967 Notification when a shared folder is added or removed.
3968 The @a scope argument defines one of three scopes:
3969 <link to="IVirtualBox::sharedFolders">global shared folders</link>
3970 (<link to="Scope::Global">Global</link>),
3971 <link to="IMachine::sharedFolders">permanent shared folders</link> of
3972 the machine (<link to="Scope::Machine">Machine</link>) or <link
3973 to="IConsole::sharedFolders">transient shared folders</link> of the
3974 machine (<link to="Scope::Session">Session</link>). Interested callees
3975 should use query the corresponding collections to find out what has
3976 changed.
3977 </desc>
3978 <param name="scope" type="Scope" dir="in">
3979 <desc>Sope of the notification.</desc>
3980 </param>
3981 </method>
3982
3983 <method name="onRuntimeError">
3984 <desc>
3985 Notification when an error happens during the virtual
3986 machine execution.
3987
3988 There are three kinds of runtime errors:
3989 <ul>
3990 <li><i>fatal</i></li>
3991 <li><i>non-fatal with retry</i></li>
3992 <li><i>non-fatal warnings</i></li>
3993 </ul>
3994
3995 <b>Fatal</b> errors are indicated by the @a fatal parameter set
3996 to <tt>true</tt>. In case of fatal errors, the virtual machine
3997 execution is always paused before calling this notification, and
3998 the notification handler is supposed either to immediately save
3999 the virtual machine state using <link to="IConsole::saveState()"/>
4000 or power it off using <link to="IConsole::powerDown()"/>.
4001 Resuming the execution can lead to unpredictable results.
4002
4003 <b>Non-fatal</b> errors and warnings are indicated by the
4004 @a fatal parameter set to <tt>false</tt>. If the virtual machine
4005 is in the Paused state by the time the error notification is
4006 received, it means that the user can <i>try to resume</i> the machine
4007 execution after attempting to solve the probem that caused the
4008 error. In this case, the notification handler is supposed
4009 to show an appropriate message to the user (depending on the
4010 value of the @a id parameter) that offers several actions such
4011 as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
4012 wants to retry, the notification handler should continue
4013 the machine execution using the <link to="IConsole::resume()"/>
4014 call. If the machine execution is not Paused during this
4015 notification, then it means this notification is a <i>warning</i>
4016 (for example, about a fatal condition that can happen very soon);
4017 no immediate action is required from the user, the machine
4018 continues its normal execution.
4019
4020 Note that in either case the notification handler
4021 <b>must not</b> perform any action directly on a thread
4022 where this notification is called. Everything it is allowed to
4023 do is to post a message to another thread that will then talk
4024 to the user and take the corresponding action.
4025
4026 Currently, the following error identificators are known:
4027 <ul>
4028 <li><tt>"HostMemoryLow"</tt></li>
4029 <li><tt>"HostAudioNotResponding"</tt></li>
4030 <li><tt>"VDIStorageFull"</tt></li>
4031 </ul>
4032
4033 <note>
4034 This notification is not designed to be implemented by
4035 more than one callback at a time. If you have multiple
4036 IConsoleCallback instances registered on the given
4037 IConsole object, make sure you simply do nothing but
4038 return @c S_OK from all but one of them that does actual
4039 user notification and performs necessary actions.
4040 </note>
4041
4042 </desc>
4043 <param name="fatal" type="boolean" dir="in">
4044 <desc>Whether the error is fatal or not</desc>
4045 </param>
4046 <param name="id" type="wstring" dir="in">
4047 <desc>Error identificator</desc>
4048 </param>
4049 <param name="message" type="wstring" dir="in">
4050 <desc>Optional error message</desc>
4051 </param>
4052 </method>
4053
4054 <method name="onCanShowWindow">
4055 <desc>
4056 Notification when a call to
4057 <link to="IMachine::canShowConsoleWindow()"/> is made by a
4058 front-end to check if a subsequent call to
4059 <link to="IMachine::showConsoleWindow()"/> can succeed.
4060
4061 The callee should give an answer appropriate to the current
4062 machine state in the @a canShow argument. This answer must
4063 remain valid at least until the next
4064 <link to="IConsole::state">machine state</link> change.
4065
4066 <note>
4067 This notification is not designed to be implemented by
4068 more than one callback at a time. If you have multiple
4069 IConsoleCallback instances registered on the given
4070 IConsole object, make sure you simply do nothing but
4071 return @c true and @c S_OK from all but one of them that
4072 actually manages console window activation.
4073 </note>
4074 </desc>
4075 <param name="canShow" type="boolean" dir="return">
4076 <desc>
4077 @c true if the console window can be shown and @c
4078 false otherwise.
4079 </desc>
4080 </param>
4081 </method>
4082
4083 <method name="onShowWindow">
4084 <desc>
4085 Notification when a call to
4086 <link to="IMachine::showConsoleWindow()"/>
4087 requests the console window to be activated and brought to
4088 foreground on the desktop of the host PC.
4089
4090 This notification should cause the VM console process to
4091 perform the requested action as described above. If it is
4092 impossible to do it at a time of this notification, this
4093 method should return a failure.
4094
4095 Note that many modern window managers on many platforms
4096 implement some sort of focus stealing prevention logic, so
4097 that it may be impossible to activate a window without the
4098 help of the currently active application (which is supposedly
4099 an initiator of this notification). In this case, this method
4100 must return a non-zero identifier that represents the
4101 top-level window of the VM console process. The caller, if it
4102 represents a currently active process, is responsible to use
4103 this identifier (in a platform-dependent manner) to perform
4104 actual window activation.
4105
4106 This method must set @a winId to zero if it has performed all
4107 actions necessary to complete the request and the console
4108 window is now active and in foreground, to indicate that no
4109 further action is required on the caller's side.
4110
4111 <note>
4112 This notification is not designed to be implemented by
4113 more than one callback at a time. If you have multiple
4114 IConsoleCallback instances registered on the given
4115 IConsole object, make sure you simply do nothing but
4116 return@c S_OK from all but one of them that actually
4117 manages console window activation.
4118 </note>
4119 </desc>
4120 <param name="winId" type="unsigned long long" dir="return">
4121 <desc>
4122 Platform-dependent identifier of the top-level VM console
4123 window, or zero if this method has performed all actions
4124 necessary to implement the <i>show window</i> semantics for
4125 the given platform and/or this VirtualBox front-end.
4126 </desc>
4127 </param>
4128 </method>
4129
4130 </interface>
4131
4132 <interface
4133 name="IRemoteDisplayInfo" extends="$unknown"
4134 uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
4135 wsmap="struct"
4136 >
4137 <desc>
4138 Contains information about the remote display (VRDP) capabilities and status.
4139 This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
4140 </desc>
4141
4142 <attribute name="active" type="boolean" readonly="yes">
4143 <desc>
4144 Whether the remote display connection is active.
4145 </desc>
4146 </attribute>
4147
4148 <attribute name="numberOfClients" type="unsigned long" readonly="yes">
4149 <desc>
4150 How many times a client connected.
4151 </desc>
4152 </attribute>
4153
4154 <attribute name="beginTime" type="long long" readonly="yes">
4155 <desc>
4156 When the last connection was established, in milliseconds since 1970-01-01 UTC.
4157 </desc>
4158 </attribute>
4159
4160 <attribute name="endTime" type="long long" readonly="yes">
4161 <desc>
4162 When the last connection was terminated or the current time, if
4163 connection is still active, in milliseconds since 1970-01-01 UTC.
4164 </desc>
4165 </attribute>
4166
4167 <attribute name="bytesSent" type="unsigned long long" readonly="yes">
4168 <desc>
4169 How many bytes were sent in last or current, if still active, connection.
4170 </desc>
4171 </attribute>
4172
4173 <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
4174 <desc>
4175 How many bytes were sent in all connections.
4176 </desc>
4177 </attribute>
4178
4179 <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
4180 <desc>
4181 How many bytes were received in last or current, if still active, connection.
4182 </desc>
4183 </attribute>
4184
4185 <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
4186 <desc>
4187 How many bytes were received in all connections.
4188 </desc>
4189 </attribute>
4190
4191 <attribute name="user" type="wstring" readonly="yes">
4192 <desc>
4193 Login user name supplied by the client.
4194 </desc>
4195 </attribute>
4196
4197 <attribute name="domain" type="wstring" readonly="yes">
4198 <desc>
4199 Login domain name supplied by the client.
4200 </desc>
4201 </attribute>
4202
4203 <attribute name="clientName" type="wstring" readonly="yes">
4204 <desc>
4205 The client name supplied by the client.
4206 </desc>
4207 </attribute>
4208
4209 <attribute name="clientIP" type="wstring" readonly="yes">
4210 <desc>
4211 The IP address of the client.
4212 </desc>
4213 </attribute>
4214
4215 <attribute name="clientVersion" type="unsigned long" readonly="yes">
4216 <desc>
4217 The client software version number.
4218 </desc>
4219 </attribute>
4220
4221 <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
4222 <desc>
4223 Public key exchange method used when connection was established.
4224 Values: 0 - RDP4 public key exchange scheme.
4225 1 - X509 sertificates were sent to client.
4226 </desc>
4227 </attribute>
4228
4229 </interface>
4230
4231 <interface
4232 name="IConsole" extends="$unknown"
4233 uuid="d5a1cbda-f5d7-4824-9afe-d640c94c7dcf"
4234 wsmap="managed"
4235 >
4236 <desc>
4237 The IConsole interface represents an interface to control virtual
4238 machine execution.
4239
4240 The console object that implements the IConsole interface is obtained
4241 from a session object after the session for the given machine has been
4242 opened using one of <link to="IVirtualBox::openSession"/>,
4243 <link to="IVirtualBox::openRemoteSession"/> or
4244 <link to="IVirtualBox::openExistingSession"/> methods.
4245
4246 Methods of the IConsole interface allow the caller to query the current
4247 virtual machine execution state, pause the machine or power it down, save
4248 the machine state or take a snapshot, attach and detach removable media
4249 and so on.
4250
4251 <see>ISession</see>
4252 </desc>
4253
4254 <attribute name="machine" type="IMachine" readonly="yes">
4255 <desc>
4256 Machine object this console is sessioned with.
4257 <note>
4258 This is a convenience property, it has the same value as
4259 <link to="ISession::machine"/> of the corresponding session
4260 object.
4261 </note>
4262 </desc>
4263 </attribute>
4264
4265 <attribute name="state" type="MachineState" readonly="yes">
4266 <desc>
4267 Current execution state of the machine.
4268 <note>
4269 This property always returns the same value as the corresponding
4270 property of the IMachine object this console is sessioned with.
4271 For the process that owns (executes) the VM, this is the
4272 preferable way of querying the VM state, because no IPC
4273 calls are made.
4274 </note>
4275 </desc>
4276 </attribute>
4277
4278 <attribute name="guest" type="IGuest" readonly="yes">
4279 <desc>Guest object.</desc>
4280 </attribute>
4281
4282 <attribute name="keyboard" type="IKeyboard" readonly="yes">
4283 <desc>
4284 Virtual keyboard object.
4285 <note>
4286 If the machine is not running, any attempt to use
4287 the returned object will result in an error.
4288 </note>
4289 </desc>
4290 </attribute>
4291
4292 <attribute name="mouse" type="IMouse" readonly="yes">
4293 <desc>
4294 Virtual mouse object.
4295 <note>
4296 If the machine is not running, any attempt to use
4297 the returned object will result in an error.
4298 </note>
4299 </desc>
4300 </attribute>
4301
4302 <attribute name="display" type="IDisplay" readonly="yes">
4303 <desc>Virtual display object.
4304 <note>
4305 If the machine is not running, any attempt to use
4306 the returned object will result in an error.
4307 </note>
4308 </desc>
4309 </attribute>
4310
4311 <attribute name="debugger" type="IMachineDebugger" readonly="yes">
4312 <desc>Debugging interface.</desc>
4313 </attribute>
4314
4315 <attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
4316 <desc>
4317 Collection of USB devices currently attached to the virtual
4318 USB controller.
4319 <note>
4320 The collection is empty if the machine is not running.
4321 </note>
4322 </desc>
4323 </attribute>
4324
4325 <attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
4326 <desc>
4327 List of USB devices currently attached to the remote VRDP client.
4328 Once a new device is physically attached to the remote host computer,
4329 it appears in this list and remains there until detached.
4330 </desc>
4331 </attribute>
4332
4333 <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
4334 <desc>
4335 Collection of shared folders for the current session. These folders
4336 are called transient shared folders because they are available to the
4337 guest OS running inside the associated virtual machine only for the
4338 duration of the session (as opposed to
4339 <link to="IMachine::sharedFolders"/> which represent permanent shared
4340 folders). When the session is closed (e.g. the machine is powered down),
4341 these folders are automatically discarded.
4342
4343 New shared folders are added to the collection using
4344 <link to="#createSharedFolder"/>. Existing shared folders can be
4345 removed using <link to="#removeSharedFolder"/>.
4346 </desc>
4347 </attribute>
4348
4349 <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
4350 <desc>
4351 Interface that provides information on Remote Display (VRDP) connection.
4352 </desc>
4353 </attribute>
4354
4355 <method name="powerUp">
4356 <desc>
4357 Starts the virtual machine execution using the current machine
4358 state (i.e. its current execution state, current settings and
4359 current hard disks).
4360
4361 If the machine is powered off or aborted, the execution will
4362 start from the beginning (as if the real hardware were just
4363 powered on).
4364
4365 If the machine is in the <link to="MachineState::Saved"/> state,
4366 it will continue its execution the point where the state has
4367 been saved.
4368
4369 <note>
4370 Unless you are trying to write a new VirtualBox front-end that
4371 performs direct machine execution (like the VirtualBox or VBoxSDL
4372 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
4373 session opened by <link to="IVirtualBox::openSession"/> and use this
4374 session only to change virtual machine settings. If you simply want to
4375 start virtual machine execution using one of the existing front-ends
4376 (for example the VirtualBox GUI or headless server), simply use
4377 <link to="IVirtualBox::openRemoteSession"/>; these front-ends
4378 will power up the machine automatically for you.
4379 </note>
4380
4381 <see>#saveState</see>
4382 </desc>
4383 <param name="progress" type="IProgress" dir="return">
4384 <desc>Progress object to track the operation completion.</desc>
4385 </param>
4386 </method>
4387
4388 <method name="powerDown">
4389 <desc>
4390 Stops the virtual machine execution.
4391 After this operation completes, the machine will go to the
4392 PoweredOff state.
4393 </desc>
4394 </method>
4395
4396 <method name="reset">
4397 <desc>Resets the virtual machine.</desc>
4398 </method>
4399
4400 <method name="pause">
4401 <desc>Pauses the virtual machine execution.</desc>
4402 </method>
4403
4404 <method name="resume">
4405 <desc>Resumes the virtual machine execution.</desc>
4406 </method>
4407
4408 <method name="powerButton">
4409 <desc>Send the ACPI power button event to the guest.</desc>
4410 </method>
4411
4412 <method name="sleepButton">
4413 <desc>Send the ACPI sleep button event to the guest.</desc>
4414 </method>
4415
4416 <method name="getPowerButtonHandled">
4417 <desc>Check if the last power button event was handled by guest.</desc>
4418 <param name="handled" type="boolean" dir="return"/>
4419 </method>
4420
4421 <method name="saveState">
4422 <desc>
4423 Saves the current execution state of a running virtual machine
4424 and stops its execution.
4425
4426 After this operation completes, the machine will go to the
4427 Saved state. Next time it is powered up, this state will
4428 be restored and the machine will continue its execution from
4429 the place where it was saved.
4430
4431 This operation differs from taking a snapshot to the effect
4432 that it doesn't create new differencing hard disks. Also, once
4433 the machine is powered up from the state saved using this method,
4434 the saved state is deleted, so it will be impossible to return
4435 to this state later.
4436
4437 <note>
4438 On success, this method implicitly calls
4439 <link to="IMachine::saveSettings()"/> to save all current machine
4440 settings (including runtime changes to the DVD drive, etc.).
4441 Together with the impossibility to change any VM settings when it is
4442 in the Saved state, this guarantees the adequate hardware
4443 configuration of the machine when it is restored from the saved
4444 state file.
4445 </note>
4446
4447 <note>
4448 The machine must be in the Running or Paused state, otherwise
4449 the operation will fail.
4450 </note>
4451
4452 <see><link to="#takeSnapshot"/></see>
4453 </desc>
4454 <param name="progress" type="IProgress" dir="return">
4455 <desc>Progress object to track the operation completion.</desc>
4456 </param>
4457 </method>
4458
4459 <method name="adoptSavedState">
4460 <desc>
4461 Associates the given saved state file to the virtual machine.
4462
4463 On success, the machine will go to the Saved state. Next time it is
4464 powered up, it will be restored from the adopted saved state and
4465 continue execution from the place where the saved state file was
4466 created.
4467
4468 The specified saved state file path may be full or relative to the
4469 folder the VM normally saves the state to (usually,
4470 <link to="IMachine::snapshotFolder"/>).
4471
4472 <note>
4473 It's a caller's responsibility to make sure the given saved state
4474 file is compatible with the settings of this virtual machine that
4475 represent its virtual hardware (memory size, hard disk configuration
4476 etc.). If there is a mismatch, the behavior of the virtual machine
4477 is undefined.
4478 </note>
4479 </desc>
4480 <param name="savedStateFile" type="wstring" dir="in">
4481 <desc>Path to the saved state file to adopt.</desc>
4482 </param>
4483 </method>
4484
4485 <method name="discardSavedState">
4486 <desc>
4487 Discards (deletes) the saved state of the virtual machine
4488 previously created by <link to="#saveState"/>. Next time the
4489 machine is powered up, a clean boot will occur.
4490 <note>
4491 This operation is equivalent to resetting or powering off
4492 the machine without doing a proper shutdown in the guest OS.
4493 </note>
4494 </desc>
4495 </method>
4496
4497 <method name="getDeviceActivity">
4498 <desc>
4499 Gets the current activity type of a given device or device group.
4500 </desc>
4501 <param name="type" type="DeviceType" dir="in"/>
4502 <param name="activity" type="DeviceActivity" dir="return"/>
4503 </method>
4504
4505 <method name="attachUSBDevice">
4506 <desc>
4507 Attaches a host USB device with the given UUID to the
4508 USB controller of the virtual machine.
4509
4510 The device needs to be in one of the following states:
4511 <link to="USBDeviceState::Busy">Busy</link>,
4512 <link to="USBDeviceState::Available">Available</link> or
4513 <link to="USBDeviceState::Held">Held</link>,
4514 otherwise an error is immediately returned.
4515
4516 When the device state is
4517 <link to="USBDeviceState::Busy">Busy</link>, an error may also
4518 be returned if the host computer refuses to release it for some reason.
4519
4520 <see>IUSBController::deviceFilters, USBDeviceState</see>
4521 </desc>
4522 <param name="id" type="uuid" dir="in">
4523 <desc>UUID of the host USB device to attach.</desc>
4524 </param>
4525 </method>
4526
4527 <method name="detachUSBDevice">
4528 <desc>
4529 Detaches an USB device with the given UUID from the USB controller
4530 oif the virtual machine.
4531
4532 After this method succeeds, the VirtualBox server reinitiates
4533 all USB filters as if the device were just physically attached
4534 to the host, but filters of this machine are ignored to avoid
4535 a possible automatic reattachment.
4536
4537 <see>IUSBController::deviceFilters, USBDeviceState</see>
4538 </desc>
4539 <param name="id" type="uuid" dir="in">
4540 <desc>UUID of the USB device to detach.</desc>
4541 </param>
4542 <param name="device" type="IUSBDevice" dir="return">
4543 <desc>Detached USB device.</desc>
4544 </param>
4545 </method>
4546
4547 <method name="createSharedFolder">
4548 <desc>
4549 Creates a transient new shared folder by associating the given logical
4550 name with the given host path, adds it to the collection of shared
4551 folders and starts sharing it. Refer to the description of
4552 <link to="ISharedFolder"/> to read more about logical names.
4553 </desc>
4554 <param name="name" type="wstring" dir="in">
4555 <desc>Unique logical name of the shared folder.</desc>
4556 </param>
4557 <param name="hostPath" type="wstring" dir="in">
4558 <desc>Full path to the shared folder in the host file system.</desc>
4559 </param>
4560 <param name="writable" type="boolean" dir="in">
4561 <desc>Whether the share is writable or readonly</desc>
4562 </param>
4563 </method>
4564
4565 <method name="removeSharedFolder">
4566 <desc>
4567 Removes a transient shared folder with the given name previously
4568 created by <link to="#createSharedFolder"/> from the collection of
4569 shared folders and stops sharing it.
4570 </desc>
4571 <param name="name" type="wstring" dir="in">
4572 <desc>Logical name of the shared folder to remove.</desc>
4573 </param>
4574 </method>
4575
4576 <method name="takeSnapshot">
4577 <desc>
4578 Saves the current execution state and all settings of the
4579 machine and creates differencing images for all
4580 normal (non-independent) hard disks.
4581
4582 This method can be called for a PoweredOff, Saved, Running or
4583 Paused virtual machine. When the machine is PoweredOff, an
4584 offline <link to="ISnapshot">snapshot</link> is created,
4585 in all other cases -- an online snapshot.
4586
4587 The taken snapshot is always based on the
4588 <link to="IMachine::currentSnapshot">current
4589 snapshot</link> of the associated virtual machine and becomes
4590 a new current snapshot.
4591
4592 <note>
4593 This method implicitly calls <link to="IMachine::saveSettings()"/> to
4594 save all current machine settings before taking an offline snapshot.
4595 </note>
4596
4597 <see>ISnapshot, <link to="#saveState"/></see>
4598 </desc>
4599 <param name="name" type="wstring" dir="in">
4600 <desc>Short name for the snapshot.</desc>
4601 </param>
4602 <param name="description" type="wstring" dir="in">
4603 <desc>Optional description of the snapshot.</desc>
4604 </param>
4605 <param name="progress" type="IProgress" dir="return">
4606 <desc>Progress object to track the operation completion.</desc>
4607 </param>
4608 </method>
4609
4610 <method name="discardSnapshot">
4611 <desc>
4612
4613 Starts discarding the specified snapshot. The execution state
4614 and settings of the associated machine stored in the snapshot
4615 will be deleted. The contents of all differencing hard disks of
4616 this snapshot will be merged with the contents of their
4617 dependent child hard disks to keep the, disks valid (in other
4618 words, all changes represented by hard disks being discarded
4619 will be propagated to their child hard disks). After that, this
4620 snapshot's differencing hard disks will be deleted. The parent
4621 of this snapshot will become a new parent for all its child
4622 snapshots.
4623
4624 If the discarded snapshot is the current one, its parent
4625 snapshot will become a new current snapshot. The current machine
4626 state is not directly affected in this case, except that
4627 currently attached differencing hard disks based on hard disks
4628 of the discarded snapshot will be also merged as described
4629 above.
4630
4631 If the discarded snapshot is the first one (the root snapshot)
4632 and it has exactly one child snapshot, this child snapshot will
4633 become the first snapshot after discarding. If there are no
4634 children at all (i.e. the first snapshot is the only snapshot of
4635 the machine), both the current and the first snapshot of the
4636 machine will be set to null. In all other cases, the first
4637 snapshot cannot be discarded.
4638
4639 You cannot discard the snapshot if it
4640 stores <link to="HardDiskType::Normal">normal</link> (non-differencing)
4641 hard disks that have differencing hard disks based on them. Snapshots of
4642 such kind can be discarded only when every normal hard disk has either
4643 no children at all or exactly one child. In the former case, the normal
4644 hard disk simply becomes unused (i.e. not attached to any VM). In the
4645 latter case, it receives all the changes strored in the child hard disk,
4646 and then it replaces the child hard disk in the configuration of the
4647 corresponding snapshot or machine.
4648
4649 Also, you cannot discard the snapshot if it stores hard disks
4650 (of any type) having differencing child hard disks that belong
4651 to other machines. Such snapshots can be only discarded after
4652 you discard all snapshots of other machines containing "foreign"
4653 child disks, or detach these "foreign" child disks from machines
4654 they are attached to.
4655
4656 One particular example of the snapshot storing normal hard disks
4657 is the first snapshot of a virtual machine that had normal hard
4658 disks attached when taking the snapshot. Be careful when
4659 discarding such snapshots because this implicitly commits
4660 changes (made since the snapshot being discarded has been taken)
4661 to normal hard disks (as described above), which may be not what
4662 you want.
4663
4664 The virtual machine is put to
4665 the <link to="MachineState::Discarding">Discarding</link> state until
4666 the discard operation is completed.
4667
4668 <note>
4669 The machine must not be running, otherwise the operation
4670 will fail.
4671 </note>
4672
4673 <note>
4674 Child hard disks of all normal hard disks of the discarded snapshot
4675 must be <link to="IHardDisk::accessible">accessible</link> for this
4676 operation to succeed. In particular, this means that all virtual
4677 machines, whose hard disks are directly or indirectly based on the
4678 hard disks of discarded snapshot, must be powered off.
4679 </note>
4680 <note>
4681 Merging hard disk contents can be very time and disk space
4682 consuming, if these disks are big in size and have many
4683 children. However, if the snapshot being discarded is the last
4684 (head) snapshot on the branch, the operation will be rather
4685 quick.
4686 </note>
4687 <note>
4688 Note that discarding the current snapshot
4689 will imlicitly call <link to="IMachine::saveSettings()"/> to
4690 make all current machine settings permanent.
4691 </note>
4692 </desc>
4693 <param name="id" type="uuid" dir="in">
4694 <desc>UUID of the snapshot to discard.</desc>
4695 </param>
4696 <param name="progress" type="IProgress" dir="return">
4697 <desc>Progress object to track the operation completion.</desc>
4698 </param>
4699 </method>
4700
4701 <method name="discardCurrentState">
4702 <desc>
4703 This operation is similar to <link to="#discardSnapshot()"/> but
4704 affects the current machine state. This means that the state stored in
4705 the current snapshot will become a new current state, and all current
4706 settings of the machine and changes stored in differencing hard disks
4707 will be lost.
4708
4709 After this operation is successfully completed, new empty differencing
4710 hard disks are created for all normal hard disks of the machine.
4711
4712 If the current snapshot of the machine is an online snapshot, the
4713 machine will go to the <link to="MachineState::Saved"> saved
4714 state</link>, so that the next time it is powered on, the execution
4715 state will be restored from the current snapshot.
4716
4717 <note>
4718 The machine must not be running, otherwise the operation will fail.
4719 </note>
4720
4721 <note>
4722 If the machine state is <link to="MachineState::Saved">Saved</link>
4723 prior to this operation, the saved state file will be implicitly
4724 discarded (as if <link to="IConsole::discardSavedState()"/> were
4725 called).
4726 </note>
4727
4728 </desc>
4729 <param name="progress" type="IProgress" dir="return">
4730 <desc>Progress object to track the operation completion.</desc>
4731 </param>
4732 </method>
4733
4734 <method name="discardCurrentSnapshotAndState">
4735 <desc>
4736
4737 This method is equivalent to
4738 doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
4739 (currentSnapshot.id(), progress) followed by
4740 <link to="#discardCurrentState()"/>.
4741
4742 As a result, the machine will be fully restored from the
4743 snapshot preceeding the current snapshot, while both the current
4744 snapshot and the current machine state will be discarded.
4745
4746 If the current snapshot is the first snapshot of the machine (i.e. it
4747 has the only snapshot), the current machine state will be
4748 discarded <b>before</b> discarding the snapshot. In other words, the
4749 machine will be restored from its last snapshot, before discarding
4750 it. This differs from performing a single
4751 <link to="#discardSnapshot()"/> call (note that no
4752 <link to="#discardCurrentState()"/> will be possible after it)
4753 to the effect that the latter will preserve the current state instead of
4754 discarding it.
4755
4756 Unless explicitly mentioned otherwise, all remarks and
4757 limitations of the above two methods also apply to this method.
4758
4759 <note>
4760 The machine must not be running, otherwise the operation
4761 will fail.
4762 </note>
4763
4764 <note>
4765 If the machine state is <link to="MachineState::Saved">Saved</link>
4766 prior to this operation, the saved state file will be implicitly
4767 discarded (as if <link to="#discardSavedState()"/> were
4768 called).
4769 </note>
4770
4771 <note>
4772 This method is more efficient than calling two above
4773 methods separately: it requires less IPC calls and provides
4774 a single progress object.
4775 </note>
4776
4777 </desc>
4778 <param name="progress" type="IProgress" dir="return">
4779 <desc>Progress object to track the operation completion.</desc>
4780 </param>
4781 </method>
4782
4783 <method name="registerCallback">
4784 <desc>
4785 Registers a new console callback on this instance. The methods of the
4786 callback interface will be called by this instance when the appropriate
4787 event occurs.
4788 </desc>
4789 <param name="callback" type="IConsoleCallback" dir="in"/>
4790 </method>
4791
4792 <method name="unregisterCallback">
4793 <desc>
4794 Unregisters the console callback previously registered using
4795 <link to="#registerCallback"/>.
4796 </desc>
4797 <param name="callback" type="IConsoleCallback" dir="in"/>
4798 </method>
4799 </interface>
4800
4801 <!--
4802 // IHost
4803 /////////////////////////////////////////////////////////////////////////
4804 -->
4805
4806 <interface
4807 name="IHostDVDDrive" extends="$unknown"
4808 uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
4809 wsmap="managed"
4810 >
4811 <desc>
4812 The IHostDVDDrive interface represents the physical CD/DVD drive
4813 hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
4814 </desc>
4815
4816 <attribute name="name" type="wstring" readonly="yes">
4817 <desc>
4818 Returns the platform-specific device identifier.
4819 On DOS-like platforms, it is a drive name (e.g. R:).
4820 On Unix-like platforms, it is a device name (e.g. /dev/hdc).
4821 </desc>
4822 </attribute>
4823 <attribute name="description" type="wstring" readonly="yes">
4824 <desc>
4825 Returns a human readable description for the drive. This
4826 description usually contains the product and vendor name. A
4827 @c null string is returned if the description is not available.
4828 </desc>
4829 </attribute>
4830 <attribute name="udi" type="wstring" readonly="yes">
4831 <desc>
4832 Returns the unique device identifier for the drive. This
4833 attribute is reserved for future use instead of
4834 <link to="#name"/>. Currently it is not used and may return
4835 @c null on some platforms.
4836 </desc>
4837 </attribute>
4838
4839 </interface>
4840
4841 <enumerator
4842 name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
4843 uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
4844 />
4845
4846 <collection
4847 name="IHostDVDDriveCollection" type="IHostDVDDrive"
4848 enumerator="IHostDVDDriveEnumerator"
4849 uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
4850 readonly="yes"
4851 >
4852 <method name="findByName">
4853 <desc>
4854 Searches this collection for a host drive with the given name.
4855 <note>
4856 The method returns an error if the given name does not
4857 correspond to any host drive in the collection.
4858 </note>
4859 </desc>
4860 <param name="name" type="wstring" dir="in">
4861 <desc>Name of the host drive to search for</desc>
4862 </param>
4863 <param name="drive" type="IHostDVDDrive" dir="return">
4864 <desc>Found host drive object</desc>
4865 </param>
4866 </method>
4867 </collection>
4868
4869 <interface
4870 name="IHostFloppyDrive" extends="$unknown"
4871 uuid="b6a4d1a9-4221-43c3-bd52-021a5daa9ed2"
4872 wsmap="managed"
4873 >
4874 <desc>
4875 The IHostFloppyDrive interface represents the physical floppy drive
4876 hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
4877 </desc>
4878 <attribute name="name" type="wstring" readonly="yes">
4879 <desc>
4880 Returns the platform-specific device identifier.
4881 On DOS-like platforms, it is a drive name (e.g. A:).
4882 On Unix-like platforms, it is a device name (e.g. /dev/fd0).
4883 </desc>
4884 </attribute>
4885 <attribute name="description" type="wstring" readonly="yes">
4886 <desc>
4887 Returns a human readable description for the drive. This
4888 description usually contains the product and vendor name. A
4889 @c null string is returned if the description is not available.
4890 </desc>
4891 </attribute>
4892 <attribute name="udi" type="wstring" readonly="yes">
4893 <desc>
4894 Returns the unique device identifier for the drive. This
4895 attribute is reserved for future use instead of
4896 <link to="#name"/>. Currently it is not used and may return
4897 @c null on some platforms.
4898 </desc>
4899 </attribute>
4900 </interface>
4901
4902 <enumerator
4903 name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
4904 uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
4905 />
4906
4907 <collection
4908 name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
4909 enumerator="IHostFloppyDriveEnumerator"
4910 uuid="fd84bb86-c59a-4037-a557-755ff263a460"
4911 readonly="yes"
4912 >
4913 <method name="findByName">
4914 <desc>
4915 Searches this collection for a host drive with the given name.
4916 <note>
4917 The method returns an error if the given name does not
4918 correspond to any host drive in the collection.
4919 </note>
4920 </desc>
4921 <param name="name" type="wstring" dir="in">
4922 <desc>Name of the host drive to search for</desc>
4923 </param>
4924 <param name="drive" type="IHostFloppyDrive" dir="return">
4925 <desc>Found host drive object</desc>
4926 </param>
4927 </method>
4928 </collection>
4929
4930 <interface
4931 name="IHostNetworkInterface" extends="$unknown"
4932 uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
4933 wsmap="managed"
4934 >
4935 <attribute name="name" type="wstring" readonly="yes">
4936 <desc>Returns the host network interface name.</desc>
4937 </attribute>
4938
4939 <attribute name="id" type="uuid" readonly="yes">
4940 <desc>Returns the interface UUID.</desc>
4941 </attribute>
4942 </interface>
4943
4944 <enumerator
4945 name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
4946 uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
4947 />
4948
4949 <collection
4950 name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
4951 enumerator="IHostNetworkInterfaceEnumerator"
4952 uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
4953 readonly="yes"
4954 >
4955 <method name="findByName">
4956 <desc>
4957 Searches this collection for a host network interface with the given name.
4958 <note>
4959 The method returns an error if the given name does not
4960 correspond to any host network interface in the collection.
4961 </note>
4962 </desc>
4963 <param name="name" type="wstring" dir="in">
4964 <desc>Name of the host network interface to search for.</desc>
4965 </param>
4966 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
4967 <desc>Found host network interface object.</desc>
4968 </param>
4969 </method>
4970 <method name="findById">
4971 <desc>
4972 Searches this collection for a host network interface with the given GUID.
4973 <note>
4974 The method returns an error if the given GUID does not
4975 correspond to any host network interface in the collection.
4976 </note>
4977 </desc>
4978 <param name="id" type="uuid" dir="in">
4979 <desc>GUID of the host network interface to search for.</desc>
4980 </param>
4981 <param name="networkInterface" type="IHostNetworkInterface" dir="return">
4982 <desc>Found host network interface object.</desc>
4983 </param>
4984 </method>
4985 </collection>
4986
4987 <interface
4988 name="IHost" extends="$unknown"
4989 uuid="489fb370-c227-4d43-9761-ceb28484fd9f"
4990 wsmap="managed"
4991 >
4992 <desc>
4993 The IHost interface represents the physical machine that this VirtualBox
4994 installation runs on.
4995
4996 An object implementing this interface is returned by the
4997 <link to="IVirtualBox::host" /> attribute. This interface contains
4998 read-only information about the host's physical hardware (such as what
4999 processors, and disks are available, what the host operating system is,
5000 and so on) and also allows for manipulating some of the host's hardware,
5001 such as global USB device filters and host interface networking.
5002
5003 </desc>
5004 <attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
5005 <desc>List of DVD drives available on the host.</desc>
5006 </attribute>
5007
5008 <attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
5009 <desc>List of floppy drives available on the host.</desc>
5010 </attribute>
5011
5012 <attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
5013 <desc>
5014 List of USB devices currently attached to the host.
5015 Once a new device is physically attached to the host computer,
5016 it appears in this list and remains there until detached.
5017
5018 <note>
5019 This method may set a @ref com_warnings "warning result code".
5020 </note>
5021 <note>
5022 If USB functionality is not avaliable in the given edition of
5023 VirtualBox, this method will set the result code to @c E_NOTIMPL.
5024 </note>
5025 </desc>
5026 </attribute>
5027
5028 <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
5029 <desc>
5030 List of USB device filters in action.
5031 When a new device is physically attached to the host computer,
5032 filters from this list are applied to it (in order they are stored
5033 in the list). The first matched filter will determine the
5034 <link to="IHostUSBDeviceFilter::action">action</link>
5035 performed on the device.
5036
5037 Unless the device is ignored by these filters, filters of all
5038 currently running virtual machines
5039 (<link to="IUSBController::deviceFilters"/>) are applied to it.
5040
5041 <note>
5042 This method may set a @ref com_warnings "warning result code".
5043 </note>
5044 <note>
5045 If USB functionality is not avaliable in the given edition of
5046 VirtualBox, this method will set the result code to @c E_NOTIMPL.
5047 </note>
5048
5049 <see>IHostUSBDeviceFilter, USBDeviceState</see>
5050 </desc>
5051 </attribute>
5052
5053 <attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
5054 <desc>List of host network interfaces currently defined on the host.</desc>
5055 </attribute>
5056
5057 <attribute name="processorCount" type="unsigned long" readonly="yes">
5058 <desc>Number of (logical) CPUs installed in the host system.</desc>
5059 </attribute>
5060
5061 <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
5062 <desc>Number of (logical) CPUs online in the host system.</desc>
5063 </attribute>
5064
5065 <method name="getProcessorSpeed">
5066 <desc>Query the (approximate) maximum speed of a specified host CPU in Megahertz.</desc>
5067 <param name="cpuId" type="unsigned long" dir="in">
5068 <desc>
5069 Identifier of the CPU.
5070 </desc>
5071 </param>
5072 <param name="speed" type="unsigned long" dir="return">
5073 <desc>
5074 Speed value. 0 is returned if value is not known or @a cpuId is
5075 invalid.
5076 </desc>
5077 </param>
5078 </method>
5079
5080 <method name="getProcessorDescription">
5081 <desc>Query the model string of a specified host CPU.</desc>
5082 <param name="cpuId" type="unsigned long" dir="in">
5083 <desc>
5084 Identifier of the CPU.
5085 </desc>
5086 </param>
5087 <param name="description" type="wstring" dir="return">
5088 <desc>
5089 Model string. A NULL string is returned if value is not known or
5090 @a cpuId is invalid.
5091 </desc>
5092 </param>
5093 </method>
5094
5095 <attribute name="memorySize" type="unsigned long" readonly="yes">
5096 <desc>Amount of system memory in megabytes installed in the host system.</desc>
5097 </attribute>
5098
5099 <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
5100 <desc>Available system memory in the host system.</desc>
5101 </attribute>
5102
5103 <attribute name="operatingSystem" type="wstring" readonly="yes">
5104 <desc>Name of the host system's operating system.</desc>
5105 </attribute>
5106
5107 <attribute name="OSVersion" type="wstring" readonly="yes">
5108 <desc>Host operating system's version string.</desc>
5109 </attribute>
5110
5111 <attribute name="UTCTime" type="long long" readonly="yes">
5112 <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
5113 </attribute>
5114
5115<if target="midl">
5116 <method name="createHostNetworkInterface">
5117 <desc>
5118 Creates a new adapter for Host Interface Networking.
5119 </desc>
5120 <param name="name" type="wstring" dir="in">
5121 <desc>
5122 Adapter name.
5123 </desc>
5124 </param>
5125 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
5126 <desc>
5127 Created host interface object.
5128 </desc>
5129 </param>
5130 <param name="progress" type="IProgress" dir="return">
5131 <desc>
5132 Progress object to track the operation completion.
5133 </desc>
5134 </param>
5135 </method>
5136 <method name="removeHostNetworkInterface">
5137 <desc>
5138 Removes the given host network interface.
5139 </desc>
5140 <param name="id" type="uuid" dir="in">
5141 <desc>
5142 Adapter GUID.
5143 </desc>
5144 </param>
5145 <param name="hostInterface" type="IHostNetworkInterface" dir="out">
5146 <desc>
5147 Removed host interface object.
5148 </desc>
5149 </param>
5150 <param name="progress" type="IProgress" dir="return">
5151 <desc>
5152 Progress object to track the operation completion.
5153 </desc>
5154 </param>
5155 </method>
5156</if>
5157
5158 <method name="createUSBDeviceFilter">
5159 <desc>
5160 Creates a new USB device filter. All attributes except
5161 the filter name are set to <tt>null</tt> (any match),
5162 <i>active</i> is <tt>false</tt> (the filter is not active).
5163
5164 The created filter can be added to the list of filters using
5165 <link to="#insertUSBDeviceFilter()"/>.
5166
5167 <see>#USBDeviceFilters</see>
5168 </desc>
5169 <param name="name" type="wstring" dir="in">
5170 <desc>
5171 Filter name. See <link to="IHostUSBDeviceFilter::name"/>
5172 for more info.
5173 </desc>
5174 </param>
5175 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
5176 <desc>Created filter object.</desc>
5177 </param>
5178 </method>
5179
5180 <method name="insertUSBDeviceFilter">
5181 <desc>
5182 Inserts the given USB device to the specified position
5183 in the list of filters.
5184
5185 Positions are numbered starting from <tt>0</tt>. If the specified
5186 position is equal to or greater than the number of elements in
5187 the list, the filter is added to the end of the collection.
5188
5189 <note>
5190 Duplicates are not allowed, so an attempt to insert a
5191 filter that is already in the list, will return an
5192 error.
5193 </note>
5194 <note>
5195 This method may set a @ref com_warnings "warning result code".
5196 </note>
5197 <note>
5198 If USB functionality is not avaliable in the given edition of
5199 VirtualBox, this method will set the result code to @c E_NOTIMPL.
5200 </note>
5201
5202 <see>#USBDeviceFilters</see>
5203 </desc>
5204 <param name="position" type="unsigned long" dir="in">
5205 <desc>Position to insert the filter to.</desc>
5206 </param>
5207 <param name="filter" type="IHostUSBDeviceFilter" dir="in">
5208 <desc>USB device filter to insert.</desc>
5209 </param>
5210 </method>
5211
5212 <method name="removeUSBDeviceFilter">
5213 <desc>
5214 Removes a USB device filter from the specified position in the
5215 list of filters.
5216
5217 Positions are numbered starting from <tt>0</tt>. Specifying a
5218 position equal to or greater than the number of elements in
5219 the list will produce an error.
5220
5221 <note>
5222 This method may set a @ref com_warnings "warning result code".
5223 </note>
5224 <note>
5225 If USB functionality is not avaliable in the given edition of
5226 VirtualBox, this method will set the result code to @c E_NOTIMPL.
5227 </note>
5228
5229 <see>#USBDeviceFilters</see>
5230 </desc>
5231 <param name="position" type="unsigned long" dir="in">
5232 <desc>Position to remove the filter from.</desc>
5233 </param>
5234 <param name="filter" type="IHostUSBDeviceFilter" dir="return">
5235 <desc>Removed USB device filter.</desc>
5236 </param>
5237 </method>
5238
5239 </interface>
5240
5241 <!--
5242 // ISystemProperties
5243 /////////////////////////////////////////////////////////////////////////
5244 -->
5245
5246 <interface
5247 name="ISystemProperties"
5248 extends="$unknown"
5249 uuid="12c2e31e-247f-4d51-82e5-5b9d4a6c7d5b"
5250 wsmap="managed"
5251 >
5252 <desc>
5253 The ISystemProperties interface represents global properties
5254 of the given VirtualBox installation.
5255
5256 These properties define limits and default values for various
5257 attributes and parameters. Most of the properties are read-only, but some can be
5258 changed by a user.
5259 </desc>
5260
5261 <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
5262 <desc>Minium guest system memory in Megabytes.</desc>
5263 </attribute>
5264
5265 <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
5266 <desc>Maximum guest system memory in Megabytes.</desc>
5267 </attribute>
5268
5269 <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
5270 <desc>Minimum guest video memory in Megabytes.</desc>
5271 </attribute>
5272
5273 <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
5274 <desc>Maximum guest video memory in Megabytes.</desc>
5275 </attribute>
5276
5277 <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
5278 <desc>Maximum size of a virtual disk image in Megabytes.</desc>
5279 </attribute>
5280
5281 <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
5282 <desc>
5283 Number of network adapters associated with every
5284 <link to="IMachine"/> instance.
5285 </desc>
5286 </attribute>
5287
5288 <attribute name="serialPortCount" type="unsigned long" readonly="yes">
5289 <desc>
5290 Number of serial ports associated with every
5291 <link to="IMachine"/> instance.
5292 </desc>
5293 </attribute>
5294
5295 <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
5296 <desc>
5297 Number of parallel ports associated with every
5298 <link to="IMachine"/> instance.
5299 </desc>
5300 </attribute>
5301
5302 <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
5303 <desc>
5304 Maximum device position in the boot order. This value corresponds
5305 to the total number of devices a machine can boot from, to make it
5306 possible to include all possible devices to the boot list.
5307 <see><link to="IMachine::setBootOrder()"/></see>
5308 </desc>
5309 </attribute>
5310
5311 <attribute name="defaultVDIFolder" type="wstring">
5312 <desc>
5313 Full path to the default directory used to create new or open
5314 existing virtual disk images when an image file name contains no
5315 path.
5316
5317 The initial value of this property is
5318 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
5319 VirtualBox_home</link><tt>&gt;/VDI</tt>.
5320
5321 <note>
5322 Setting this property to <tt>null</tt> will restore the
5323 initial value.
5324 </note>
5325 <note>
5326 When settings this property, the specified path can be
5327 absolute (full path) or relative
5328 to the <link to="IVirtualBox::homeFolder">
5329 VirtualBox home directory</link>.
5330 When reading this property, a full path is
5331 always returned.
5332 </note>
5333 <note>
5334 The specified path may not exist, it will be created
5335 when necessary.
5336 </note>
5337
5338 <see>
5339 <link to="IVirtualBox::createHardDisk()"/>,
5340 <link to="IVirtualBox::openVirtualDiskImage()"/>
5341 </see>
5342 </desc>
5343 </attribute>
5344
5345 <attribute name="defaultMachineFolder" type="wstring">
5346 <desc>
5347 Full path to the default directory used to create new or open
5348 existing machines when a settings file name contains no
5349 path.
5350
5351 The initial value of this property is
5352 <tt>&lt;</tt><link to="IVirtualBox::homeFolder">
5353 VirtualBox_home</link><tt>&gt;/Machines</tt>.
5354
5355 <note>
5356 Setting this property to <tt>null</tt> will restore the
5357 initial value.
5358 </note>
5359 <note>
5360 When settings this property, the specified path can be
5361 absolute (full path) or relative
5362 to the <link to="IVirtualBox::homeFolder">
5363 VirtualBox home directory</link>.
5364 When reading this property, a full path is
5365 always returned.
5366 </note>
5367 <note>
5368 The specified path may not exist, it will be created
5369 when necessary.
5370 </note>
5371
5372 <see>
5373 <link to="IVirtualBox::createMachine()"/>,
5374 <link to="IVirtualBox::openMachine()"/>
5375 </see>
5376 </desc>
5377 </attribute>
5378
5379 <attribute name="remoteDisplayAuthLibrary" type="wstring">
5380 <desc>
5381 Library that provides authentication for VRDP clients. The library
5382 is used if a virtual machine's authentication type is set to "external"
5383 in the VM RemoteDisplay configuration.
5384
5385 The system library extension (".DLL" or ".so") must be omitted.
5386 A full path can be specified; if not, then the library must reside on the
5387 system's default library path.
5388
5389 The default value of this property is <tt>VRDPAuth</tt>. There is a library
5390 of that name in one of the default VirtualBox library directories.
5391
5392 For details about VirtualBox authentication libraries and how to implement
5393 them, please refer to the VirtualBox manual.
5394
5395 <note>
5396 Setting this property to <tt>null</tt> will restore the
5397 initial value.
5398 </note>
5399 </desc>
5400 </attribute>
5401
5402 <attribute name="webServiceAuthLibrary" type="wstring">
5403 <desc>
5404 Library that provides authentication for webservice clients. The library
5405 is used if a virtual machine's authentication type is set to "external"
5406 in the VM RemoteDisplay configuration and will be called from
5407 within the <link to="IWebsessionManager::logon" /> implementation.
5408
5409 As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
5410 there is no per-VM setting for this, as the webservice is a global
5411 resource (if it is running). Only for this setting (for the webservice),
5412 setting this value to a literal "null" string disables authentication,
5413 meaning that <link to="IWebsessionManager::logon" /> will always succeed,
5414 no matter what user name and password are supplied.
5415
5416 The initial value of this property is <tt>VRDPAuth</tt>,
5417 meaning that the webservice will use the same authentication
5418 library that is used by default for VBoxVRDP (again, see
5419 <link to="ISystemProperties::remoteDisplayAuthLibrary" />).
5420 The format and calling convetion of authentication libraries
5421 is the same for the webservice as it is for VBoxVRDP.
5422
5423 </desc>
5424 </attribute>
5425
5426 <attribute name="HWVirtExEnabled" type="boolean">
5427 <desc>
5428 This specifies the default value for hardware virtualization
5429 extensions. If enabled, virtual machines will make use of
5430 hardware virtualization extensions such as Intel VT-x and
5431 AMD-V by default. This value can be overridden by each VM
5432 using their <link to="IMachine::HWVirtExEnabled" /> property.
5433 </desc>
5434 </attribute>
5435
5436 <attribute name="LogHistoryCount" type="unsigned long">
5437 <desc>
5438 This value specifies how many old release log files are kept.
5439 </desc>
5440 </attribute>
5441 </interface>
5442
5443 <!--
5444 // IGuest
5445 /////////////////////////////////////////////////////////////////////////
5446 -->
5447
5448 <interface
5449 name="IGuestOSType" extends="$unknown"
5450 uuid="da94f478-1f37-4726-b750-2235950dc2fe"
5451 wsmap="struct"
5452 >
5453 <desc>
5454 </desc>
5455
5456 <attribute name="id" type="wstring" readonly="yes">
5457 <desc>Guest OS identifier string.</desc>
5458 </attribute>
5459
5460 <attribute name="description" type="wstring" readonly="yes">
5461 <desc>Human readable description of the guest OS.</desc>
5462 </attribute>
5463
5464 <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
5465 <desc>Recommended RAM size in Megabytes.</desc>
5466 </attribute>
5467
5468 <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
5469 <desc>Recommended video RAM size in Megabytes.</desc>
5470 </attribute>
5471
5472 <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
5473 <desc>Recommended hard disk size in Megabytes.</desc>
5474 </attribute>
5475 </interface>
5476
5477
5478 <enumerator
5479 name="IGuestOSTypeEnumerator" type="IGuestOSType"
5480 uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
5481 />
5482
5483 <collection
5484 name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
5485 uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
5486 readonly="yes"
5487 />
5488
5489 <interface
5490 name="IGuest" extends="$unknown"
5491 uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
5492
5493 wsmap="suppress"
5494 >
5495 <desc>
5496 The IGuest interface represents information about the operating system
5497 running inside the virtual machine. Used in
5498 <link to="IConsole::guest"/>.
5499
5500 IGuest provides information about the guest operating system, whether
5501 Guest Additions are installed and other OS-specific virtual machine
5502 properties.
5503 </desc>
5504
5505 <attribute name="OSTypeId" type="wstring" readonly="yes">
5506 <desc>
5507 Identifier of the Guest OS type as reported by the Guest
5508 Additions.
5509 You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
5510 an IGuestOSType object representing details about the given
5511 Guest OS type.
5512 <note>
5513 If Guest Additions are not installed, this value will be
5514 the same as <link to="IMachine::OSTypeId"/>.
5515 </note>
5516 </desc>
5517 </attribute>
5518
5519 <attribute name="additionsActive" type="boolean" readonly="yes">
5520 <desc>
5521 Flag whether the Guest Additions are installed and active
5522 in which case their version will be returned by the
5523 <link to="#additionsVersion"/> property.
5524 </desc>
5525 </attribute>
5526
5527 <attribute name="additionsVersion" type="wstring" readonly="yes">
5528 <desc>
5529 Version of the Guest Additions (3 decimal numbers separated
5530 by dots) or empty when the Additions are not installed. The
5531 Additions may also report a version but yet not be active as
5532 the version might be refused by VirtualBox (incompatible) or
5533 other failures occured.
5534 </desc>
5535 </attribute>
5536
5537 <attribute name="supportsSeamless" type="boolean" readonly="yes">
5538 <desc>
5539 Flag whether seamless guest display rendering (seamless desktop
5540 integration) is supported.
5541 </desc>
5542 </attribute>
5543
5544 <attribute name="supportsGraphics" type="boolean" readonly="yes">
5545 <desc>
5546 Flag whether the guest is in graphics mode. If it is not, then
5547 seamless rendering will not work, resize hints are not immediately
5548 acted on and guest display resizes are probably not initiated by
5549 the guest additions.
5550 </desc>
5551 </attribute>
5552
5553 <attribute name="memoryBalloonSize" type="unsigned long">
5554 <desc>Guest system memory balloon size in megabytes.</desc>
5555 </attribute>
5556
5557 <attribute name="statisticsUpdateInterval" type="unsigned long">
5558 <desc>Interval to update guest statistics in seconds.</desc>
5559 </attribute>
5560
5561 <method name="setCredentials">
5562 <desc>
5563 Store login credentials that can be queried by guest operating
5564 systems with Additions installed. The credentials are transient
5565 to the session and the guest may also choose to erase them. Note
5566 that the caller cannot determine whether the guest operating system
5567 has queried or made use of the credentials.
5568 </desc>
5569 <param name="userName" type="wstring" dir="in">
5570 <desc>User name string, can be empty</desc>
5571 </param>
5572 <param name="password" type="wstring" dir="in">
5573 <desc>Password string, can be empty</desc>
5574 </param>
5575 <param name="domain" type="wstring" dir="in">
5576 <desc>Domain name (guest logon scheme specific), can be emtpy</desc>
5577 </param>
5578 <param name="allowInteractiveLogon" type="boolean" dir="in">
5579 <desc>
5580 Flag whether the guest should alternatively allow the user to
5581 interactively specify different credentials. This flag might
5582 not be supported by all versions of the Additions.
5583 </desc>
5584 </param>
5585 </method>
5586
5587 <method name="getStatistic">
5588 <desc>
5589 Query specified guest statistics as reported by the VirtualBox Additions.
5590 </desc>
5591 <param name="cpuId" type="unsigned long" dir="in">
5592 <desc>Virtual CPU id; not relevant for all statistic types</desc>
5593 </param>
5594 <param name="statistic" type="GuestStatisticType" dir="in">
5595 <desc>Statistic type.</desc>
5596 </param>
5597 <param name="statVal" type="unsigned long" dir="out">
5598 <desc>Statistics value</desc>
5599 </param>
5600 </method>
5601
5602 </interface>
5603
5604
5605 <!--
5606 // IProgress
5607 /////////////////////////////////////////////////////////////////////////
5608 -->
5609
5610 <enumerator
5611 name="IProgressEnumerator" type="IProgress"
5612 uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
5613 />
5614
5615 <collection
5616 name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
5617 uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
5618 readonly="yes"
5619 />
5620
5621 <interface
5622 name="IProgress" extends="$unknown"
5623 uuid="10CC03A1-717E-429b-992D-C67B56175A51"
5624 wsmap="managed"
5625 >
5626 <desc>
5627 The IProgress interface represents a task progress object that allows
5628 to wait for the completion of some asynchronous task.
5629
5630 The task consists of one or more operations that run sequentially,
5631 one after one. There is an individual percent of completion of the
5632 current operation and the percent of completion of the task as a
5633 whole. Similarly, you can wait for the completion of a particular
5634 operation or for the completion of the whole task.
5635
5636 Every operation is identified by a number (starting from 0)
5637 and has a separate description.
5638 </desc>
5639
5640 <attribute name="id" type="uuid" readonly="yes">
5641 <desc>ID of the task.</desc>
5642 </attribute>
5643
5644 <attribute name="description" type="wstring" readonly="yes">
5645 <desc>Description of the task.</desc>
5646 </attribute>
5647
5648 <attribute name="initiator" type="$unknown" readonly="yes">
5649 <desc>Initiator of the task.</desc>
5650 </attribute>
5651
5652 <attribute name="cancelable" type="boolean" readonly="yes">
5653 <desc>Whether the task can be interrupted.</desc>
5654 </attribute>
5655
5656 <attribute name="percent" type="long" readonly="yes">
5657 <desc>
5658 Current task progress value in percent.
5659 This value depends on how many operations are already complete.
5660 </desc>
5661 </attribute>
5662
5663 <attribute name="completed" type="boolean" readonly="yes">
5664 <desc>Whether the task has been completed.</desc>
5665 </attribute>
5666
5667 <attribute name="canceled" type="boolean" readonly="yes">
5668 <desc>Whether the task has been canceled.</desc>
5669 </attribute>
5670
5671 <attribute name="resultCode" type="result" readonly="yes">
5672 <desc>
5673 Result code of the progress task.
5674 Valid only if <link to="#completed"/> is true.
5675 </desc>
5676 </attribute>
5677
5678 <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
5679 <desc>
5680 Extended information about the unsuccessful result of the
5681 progress operation. May be NULL when no extended information
5682 is available.
5683 Valid only if <link to="#completed"/> is true and
5684 <link to="#resultCode"/> indicates a failure.
5685 </desc>
5686 </attribute>
5687
5688 <attribute name="operationCount" type="unsigned long" readonly="yes">
5689 <desc>
5690 Number of operations this task is divided into.
5691 Every task consists of at least one operation.
5692 </desc>
5693 </attribute>
5694
5695 <attribute name="operation" type="unsigned long" readonly="yes">
5696 <desc>Number of the operation being currently executed.</desc>
5697 </attribute>
5698
5699 <attribute name="operationDescription" type="wstring" readonly="yes">
5700 <desc>
5701 Description of the operation being currently executed.
5702 </desc>
5703 </attribute>
5704
5705 <attribute name="operationPercent" type="long" readonly="yes">
5706 <desc>Current operation progress value in percent.</desc>
5707 </attribute>
5708
5709 <method name="waitForCompletion">
5710 <desc>
5711 Waits until the task is done (including all operations) with a
5712 given timeout.
5713 </desc>
5714 <param name="timeout" type="long" dir="in">
5715 <desc>
5716 Timeout value in milliseconds.
5717 Specify -1 for an indefinite wait.
5718 </desc>
5719 </param>
5720 </method>
5721
5722 <method name="waitForOperationCompletion">
5723 <desc>
5724 Waits until the given operation is done with a given timeout.
5725 </desc>
5726 <param name="operation" type="unsigned long" dir="in">
5727 <desc>
5728 Number of the operation to wait for.
5729 Must be less than <link to="#operationCount"/>.
5730 </desc>
5731 </param>
5732 <param name="timeout" type="long" dir="in">
5733 <desc>
5734 Timeout value in milliseconds.
5735 Specify -1 for an indefinite wait.
5736 </desc>
5737 </param>
5738 </method>
5739
5740 <method name="cancel">
5741 <desc>
5742 Cancels the task.
5743 <note>
5744 If <link to="#cancelable"/> is <tt>false</tt>, then
5745 this method will fail.
5746 </note>
5747 </desc>
5748 </method>
5749
5750 </interface>
5751
5752
5753 <!--
5754 // ISnapshot
5755 /////////////////////////////////////////////////////////////////////////
5756 -->
5757
5758 <enumerator
5759 name="ISnapshotEnumerator" type="ISnapshot"
5760 uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
5761 />
5762
5763 <collection
5764 name="ISnapshotCollection" type="ISnapshot"
5765 enumerator="ISnapshotEnumerator"
5766 uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
5767 readonly="yes"
5768 />
5769
5770 <interface
5771 name="ISnapshot" extends="$unknown"
5772 uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
5773 wsmap="managed"
5774 >
5775 <desc>
5776 The ISnapshot interface represents a snapshot of the virtual
5777 machine.
5778
5779 The <i>snapshot</i> stores all the information about a virtual
5780 machine necessary to bring it to exactly the same state as it was at
5781 the time of taking the snapshot. The snapshot includes:
5782
5783 <ul>
5784 <li>all settings of the virtual machine (i.e. its hardware
5785 configuration: RAM size, attached hard disks, etc.)
5786 </li>
5787 <li>the execution state of the virtual machine (memory contents,
5788 CPU state, etc.).
5789 </li>
5790 </ul>
5791
5792 Snapshots can be <i>offline</i> (taken when the VM is powered off)
5793 or <i>online</i> (taken when the VM is running). The execution
5794 state of the offline snapshot is called a <i>zero execution state</i>
5795 (it doesn't actually contain any information about memory contents
5796 or the CPU state, assuming that all hardware is just powered off).
5797
5798 <h3>Snapshot branches</h3>
5799
5800 Snapshots can be chained. Chained snapshots form a branch where
5801 every next snapshot is based on the previous one. This chaining is
5802 mostly related to hard disk branching (see <link to="IHardDisk"/>
5803 description). This means that every time a new snapshot is created,
5804 a new differencing hard disk is implicitly created for all normal
5805 hard disks attached to the given virtual machine. This allows to
5806 fully restore hard disk contents when the machine is later reverted
5807 to a particular snapshot.
5808
5809 In the current implelemtation, multiple snapshot branches within one
5810 virtual machine are not allowed. Every machine has a signle branch,
5811 and <link to="IConsole::takeSnapshot()"/> operation adds a new
5812 snapshot to the top of that branch.
5813
5814 Existings snapshots can be discarded using
5815 <link to="IConsole::discardSnapshot()"/>.
5816
5817 <h3>Current snapshot</h3>
5818
5819 Every virtual machine has a current snapshot, identified by
5820 <link to="IMachine::currentSnapshot"/>. This snapshot is used as
5821 a base for the <i>current machine state</i> (see below), to the effect
5822 that all normal hard disks of the machine and its execution
5823 state are based on this snapshot.
5824
5825 In the current implementation, the current snapshot is always the
5826 last taken snapshot (i.e. the head snapshot on the branch) and it
5827 cannot be changed.
5828
5829 The current snapshot is <tt>null</tt> if the machine doesn't have
5830 snapshots at all; in this case the current machine state is just
5831 current settings of this machine plus its current execution state.
5832
5833 <h3>Current machine state</h3>
5834
5835 The current machine state is what represened by IMachine instances got
5836 directly from IVirtualBox
5837 using <link
5838 to="IVirtualBox::getMachine()">getMachine()</link>, <link
5839 to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as opposed
5840 to instances returned by <link to="ISnapshot::machine"/>). This state
5841 is always used when the machine is <link to="IConsole::powerUp"> powered
5842 on</link>.
5843
5844 The current machine state also includes the current execution state.
5845 If the machine is being currently executed
5846 (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
5847 and above), its execution state is just what's happening now.
5848 If it is powered off (<link to="MachineState::PoweredOff"/> or
5849 <link to="MachineState::Aborted"/>), it has a zero execution state.
5850 If the machine is saved (<link to="MachineState::Saved"/>), its
5851 execution state is what saved in the execution state file
5852 (<link to="IMachine::stateFilePath"/>).
5853
5854 If the machine is in the saved state, then, next time it is powered
5855 on, its execution state will be fully restored from the saved state
5856 file and the execution will continue from the point where the state
5857 was saved.
5858
5859 Similarly to snapshots, the current machine state can be discarded
5860 using <link to="IConsole::discardCurrentState()"/>.
5861
5862 <h3>Taking and discarding snapshots</h3>
5863
5864 The table below briefly explains the meaning of every snapshot
5865 operation:
5866
5867 <table>
5868 <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
5869
5870 <tr><td><link to="IConsole::takeSnapshot()"/></td>
5871
5872 <td>Save the current state of the virtual machine, including all
5873 settings, contents of normal hard disks and the current modifications
5874 to immutable hard disks (for online snapshots)</td>
5875
5876 <td>The current state is not changed (the machine will continue
5877 execution if it is being executed when the snapshot is
5878 taken)</td></tr>
5879
5880 <tr><td><link to="IConsole::discardSnapshot()"/></td>
5881
5882 <td>Forget the state of the virtual machine stored in the snapshot:
5883 dismiss all saved settings and delete the saved execution state (for
5884 online snapshots)</td>
5885
5886 <td>Other snapshots (including child snapshots, if any) and the
5887 current state are not directly affected</td></tr>
5888
5889 <tr><td><link to="IConsole::discardCurrentState()"/></td>
5890
5891 <td>Restore the current state of the virtual machine from the state
5892 stored in the current snapshot, including all settings and hard disk
5893 contents</td>
5894
5895 <td>The current state of the machine existed prior to this operation
5896 is lost</td></tr>
5897
5898 <tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
5899
5900 <td>Completely revert the virtual machine to the state it was in
5901 before the current snapshot has been taken</td>
5902
5903 <td>The current state, as well as the current snapshot, are
5904 lost</td></tr>
5905
5906 </table>
5907
5908 </desc>
5909
5910 <attribute name="id" type="uuid" readonly="yes">
5911 <desc>UUID of the snapshot.</desc>
5912 </attribute>
5913
5914 <attribute name="name" type="wstring">
5915 <desc>Short name of the snapshot.</desc>
5916 </attribute>
5917
5918 <attribute name="description" type="wstring">
5919 <desc>Optional description of the snapshot.</desc>
5920 </attribute>
5921
5922 <attribute name="timeStamp" type="long long" readonly="yes">
5923 <desc>
5924 Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
5925 </desc>
5926 </attribute>
5927
5928 <attribute name="online" type="boolean" readonly="yes">
5929 <desc>
5930 <tt>true</tt> if this snapshot is an online snapshot and
5931 <tt>false</tt> otherwise.
5932
5933 <note>
5934 When this attribute is <tt>true</tt>, the
5935 <link to="IMachine::stateFilePath"/> attribute of the
5936 <link to="#machine"/> object associated with this snapshot
5937 will point to the saved state file. Otherwise, it will be
5938 <tt>null</tt>.
5939 </note>
5940 </desc>
5941 </attribute>
5942
5943 <attribute name="machine" type="IMachine" readonly="yes">
5944 <desc>
5945 Virtual machine this snapshot is taken on. This object
5946 stores all settings the machine had when taking this snapshot.
5947 <note>
5948 The returned machine object is immutable, i.e. no
5949 any settings can be changed.
5950 </note>
5951 </desc>
5952 </attribute>
5953
5954 <attribute name="parent" type="ISnapshot" readonly="yes">
5955 <desc>
5956 Parent snapshot (a snapshot this one is based on).
5957 <note>
5958 It's not an error to read this attribute on a snapshot
5959 that doesn't have a parent -- a null object will be
5960 returned to indicate this.
5961 </note>
5962 </desc>
5963 </attribute>
5964
5965 <attribute name="children" type="ISnapshotCollection" readonly="yes">
5966 <desc>
5967 Child snapshots (all snapshots having this one as a parent).
5968 <note>
5969 In the current implementation, there can be only one
5970 child snapshot, or no children at all, meaning this is the
5971 last (head) snapshot.
5972 </note>
5973 </desc>
5974 </attribute>
5975
5976 </interface>
5977
5978 <!--
5979 // IHardDisk
5980 /////////////////////////////////////////////////////////////////////////
5981 -->
5982
5983 <enum
5984 name="HardDiskStorageType"
5985 uuid="48138584-ad99-479d-a36f-eb82a7663685"
5986 >
5987 <desc>
5988 Virtual hard disk storage type.
5989 <see>IHardDisk</see>
5990 </desc>
5991
5992 <const name="VirtualDiskImage" value="0">
5993 <desc>
5994 Virtual Disk Image, VDI (a regular file in the file
5995 system of the host OS, see <link to="IVirtualDiskImage"/>)
5996 </desc>
5997 </const>
5998 <const name="ISCSIHardDisk" value="1">
5999 <desc>
6000 iSCSI Remote Disk (a disk accessed via the Internet
6001 SCSI protocol over a TCP/IP network, see
6002 <link to="IISCSIHardDisk"/>)
6003 </desc>
6004 </const>
6005 <const name="VMDKImage" value="2">
6006 <desc>
6007 VMware Virtual Machine Disk image (a regular file in the file
6008 system of the host OS, see <link to="IVMDKImage"/>)
6009 </desc>
6010 </const>
6011 <const name="CustomHardDisk" value="3">
6012 <desc>
6013 Disk formats supported through plugins (see
6014 <link to="ICustomHardDisk"/>)
6015 </desc>
6016 </const>
6017 <const name="VHDImage" value="4">
6018 <desc>
6019 Virtual PC Virtual Machine Disk image (a regular file in the file
6020 system of the host OS, see <link to="IVHDImage"/>)
6021 </desc>
6022 </const>
6023 </enum>
6024
6025 <enum
6026 name="HardDiskType"
6027 uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
6028 >
6029 <desc>
6030 Virtual hard disk type.
6031 <see>IHardDisk</see>
6032 </desc>
6033
6034 <const name="Normal" value="0">
6035 <desc>
6036 Normal hard disk (attached directly or indirectly, preserved
6037 when taking snapshots).
6038 </desc>
6039 </const>
6040 <const name="Immutable" value="1">
6041 <desc>
6042 Immutable hard disk (attached indirectly, changes are wiped out
6043 after powering off the virtual machine).
6044 </desc>
6045 </const>
6046 <const name="Writethrough" value="2">
6047 <desc>
6048 Write through hard disk (attached directly, ignored when
6049 taking snapshots).
6050 </desc>
6051 </const>
6052 </enum>
6053
6054 <interface
6055 name="IHardDiskAttachment" extends="$unknown"
6056 uuid="c0ffe596-21c6-4797-8d8a-b47b66881e7a"
6057 wsmap="struct"
6058 >
6059 <desc>
6060 </desc>
6061 <attribute name="hardDisk" type="IHardDisk" readonly="yes">
6062 <desc>Harddisk object this attachment is about.</desc>
6063 </attribute>
6064
6065 <attribute name="bus" type="StorageBus" readonly="yes">
6066 <desc>Disk controller ID of this attachment.</desc>
6067 </attribute>
6068
6069 <attribute name="channel" type="long" readonly="yes">
6070 <desc>Channel number of the attachment.</desc>
6071 </attribute>
6072
6073 <attribute name="device" type="long" readonly="yes">
6074 <desc>Device slot number of the attachment.</desc>
6075 </attribute>
6076
6077 </interface>
6078
6079 <enumerator
6080 name="IHardDiskAttachmentEnumerator" type="IHardDiskAttachment"
6081 uuid="9955e486-2f0b-432a-99e4-0ebbd338875e"
6082 />
6083
6084 <collection
6085 name="IHardDiskAttachmentCollection" type="IHardDiskAttachment"
6086 enumerator="IHardDiskAttachmentEnumerator"
6087 uuid="8f727842-bb77-45d4-92de-4ec14bf613c9"
6088 readonly="yes"
6089 />
6090
6091 <enumerator
6092 name="IHardDiskEnumerator" type="IHardDisk"
6093 uuid="b976f97b-cdb8-47e3-9860-084031cbd533"
6094 />
6095
6096 <collection
6097 name="IHardDiskCollection" type="IHardDisk"
6098 enumerator="IHardDiskEnumerator"
6099 uuid="43EAC2BC-5C61-40fa-BC38-46DE2C7DB6BB"
6100 readonly="yes"
6101 />
6102
6103 <interface
6104 name="IHardDisk" extends="$unknown"
6105 uuid="FD443EC1-000F-4F5B-9282-D72760A66916"
6106 wsmap="managed"
6107 >
6108 <desc>
6109 The IHardDisk interface represents a virtual hard disk drive
6110 used by virtual machines.
6111
6112 The virtual hard disk drive virtualizes the hard disk hardware and
6113 looks like a regular hard disk inside the virtual machine and
6114 the guest OS.
6115
6116 <h3>Storage Types</h3>
6117
6118 The <link to="HardDiskStorageType">storage type</link> of the
6119 virtual hard disk determines where and how it stores its data
6120 (sectors). Currently, the following storage types are supported:
6121
6122 <ul>
6123
6124 <li>
6125 <i>Virtual Disk Image (VDI)</i>, a regular file in the file system
6126 of the host OS (represented by the <link to="IVirtualDiskImage"/>
6127 interface). This file has a special format optimized so that unused
6128 sectors of data occupy much less space than on a physical hard disk.
6129 </li>
6130
6131 <li>
6132 <i>iSCSI Remote Disk</i>, a disk accessed via the Internet SCSI
6133 protocol over a TCP/IP network link (represented by the
6134 <link to="IISCSIHardDisk"/> interface).
6135 </li>
6136
6137 <li>
6138 <i>VMware VMDK image</i>, a regular file in the file system of the
6139 host OS (represented by the <link to="IVMDKImage"/> interface).
6140 Note that the regular file may be just a descriptor referring to
6141 further files, so don't make assumptions about the OS representation
6142 of a VMDK image.
6143 </li>
6144
6145 <li>
6146 <i>Custom HardDisk</i>, a disk accessed via a plugin which is loaded
6147 when the disk is accessed (represented by the
6148 <link to="ICustomHardDisk"/> interface).
6149 </li>
6150
6151 <li>
6152 <i>Virtual PC VHD Image</i>, a regular file in the file system of the
6153 host OS (represented by the <link to="IVHDImage"/> interface).
6154 </li>
6155
6156 </ul>
6157
6158 The storage type of the particular hard disk object is indicated by
6159 the <link to="#storageType"/> property.
6160
6161 Each storage type is represented by its own interface (as shown
6162 above), that allows to query and set properties and perform
6163 operations specific to that storage type. When an IHardDisk object
6164 reports it uses some particular storage type, it also guaranteed to
6165 support the corresponding interface which you can query. And vice
6166 versa, every object that supports a storage-specific interface, also
6167 supports IHardDisk.
6168
6169 <h3>Virtual Hard Disk Types</h3>
6170
6171 The <link to="HardDiskType">type</link> of the virtual hard disk
6172 determines how it is attached to the virtual machine when you call
6173 <link to="IMachine::attachHardDisk()"/> and what happens to it when
6174 a <link to="ISnapshot">snapshot</link> of the virtual machine is
6175 taken.
6176
6177 There are three types of virtual hard disks:
6178
6179 <ul>
6180 <li><i>Normal</i></li>
6181 <li><i>Immutable</i></li>
6182 <li><i>Writethrough</i></li>
6183 </ul>
6184
6185 The virtual disk type is indicated by the <link to="#type"/>
6186 property. Each of the above types is described in detail further
6187 down.
6188
6189 There is also a forth, "hidden" virtual disk type:
6190 <i>Differencing</i>. It is "hidden" because you cannot directly
6191 create hard disks of this type -- they are automatically created by
6192 VirtualBox when necessary.
6193
6194 <b>Differencing Hard Disks</b>
6195
6196 Unlike disks of other types (that are similar to real hard disks),
6197 the differencing hard disk does not store the full range of data
6198 sectors. Instead, it stores only a subset of sectors of some other
6199 disk that were changed since the differencing hard disk has been
6200 created. Thus, every differencing hard disk has a parent hard disk
6201 it is linked to, and represents the difference between the initial
6202 and the current hard disk state. A differencing hard disk can be
6203 linked to another differencing hard disk -- this way, differencing
6204 hard disks can form a branch of changes. More over, a given virtual
6205 hard disk can have more than one differencing hard disk linked to
6206 it.
6207
6208 A disk the differencing hard disk is linked to (or, in other words,
6209 based on) is called a <i>parent</i> hard disk and is accessible through
6210 the <link to="#parent"/> property. Similarly, all existing differencing
6211 hard disks for a given parent hard disk are called its <i>child</i> hard
6212 disks (and accessible through the <link to="#children"/> property).
6213
6214 All differencing hard disks use Virtual Disk Image files to store
6215 changed sectors. They have the <link to="#type"/> property set to
6216 Normal, but can be easily distinguished from normal hard disks using
6217 the <link to="#parent"/> property: all differencing hard disks have
6218 a parent, while all normal hard disks don't.
6219
6220 When the virtual machine makes an attempt to read a sector that is
6221 missing in a differencing hard disk, its parent is accessed to
6222 resolve the sector in question. This process continues until the
6223 sector is found, or until the root hard disk is encountered, which
6224 always contains all sectors. As a consequence,
6225
6226 <ul>
6227
6228 <li>
6229 The virtual hard disk geometry seen by the guest OS is
6230 always defined by the root hard disk.
6231 </li>
6232
6233 <li>
6234 All hard disks on a branch, up to the root, must be
6235 <link to="#accessible"/> for a given differencing hard disk in order
6236 to let it function properly when the virtual machine is
6237 running.
6238 </li>
6239
6240 </ul>
6241
6242 Differencing hard disks can be implicitly created by VirtualBox in
6243 the following cases:
6244
6245 <ul>
6246
6247 <li>
6248 When a hard disk is <i>indirectly</i> attached to the virtual
6249 machine using <link to="IMachine::attachHardDisk()"/>. In this
6250 case, all disk writes performed by the guest OS will go to the
6251 created diffferencing hard disk, as opposed to the
6252 <i>direct</i> attachment, where all changes are written to the
6253 attached hard disk itself.
6254 </li>
6255
6256 <li>
6257 When a <link to="ISnapshot">snapshot</link> of the virtual machine
6258 is taken. After that, disk writes to hard disks the differencing
6259 ones have been created for, will be directed to those differencing
6260 hard disks, to preserve the contents of the original disks.
6261 </li>
6262
6263 </ul>
6264
6265 Whether to create a differencing hard disk or not depends on the
6266 type of the hard disk attached to the virtual machine. This is
6267 explained below.
6268
6269 Note that in the current implementation, only the
6270 <link to="VirtualDiskImage"/> storage type is used to
6271 represent differencing hard disks. In other words, all
6272 differencing hard disks are <link to="IVirtualDiskImage"/>
6273 objects.
6274
6275 <b>Normal Hard Disks</b>
6276
6277 Normal hard disks are the most commonly used virtual hard disk. A
6278 normal hard disk is attached to the machine directly if it is not
6279 already attached to some other machine. Otherwise, an attempt to
6280 make an indirect attachment through a differencing hard disk will be
6281 made. This attempt will fail if the hard disk is attached to a
6282 virtual machine without snapshots (because it's impossible to create
6283 a differencing hard disk based on a hard disk that is subject to
6284 change).
6285
6286 When an indirect attachment takes place, in the simplest case, where
6287 the machine the hard disk is being attached to doesn't have
6288 snapshots, the differencing hard disk will be based on the normal
6289 hard disk being attached. Otherwise, the first (i.e. the most
6290 recent) descendant of the given normal hard disk found in the
6291 current snapshot branch (starting from the current snapshot and
6292 going up to the root) will be actually used as a base.
6293
6294 Note that when you detach an indirectly attached hard disk from the
6295 machine, the created differencing hard disk image is simply
6296 <b>deleted</b>, so <b>all changes are lost</b>. If you attach the
6297 same disk again, a clean differencing disk will be created based on
6298 the most recent child, as described above.
6299
6300 When taking a snapshot, the contents of all normal hard disks (and
6301 all differencing disks whose roots are normal hard disks) currently
6302 attached to the virtual machine is preserved by creating
6303 differencing hard disks based on them.
6304
6305 <b>Immutable Hard Disks</b>
6306
6307 Immutable hard disks can be used to provide a sort of read-only
6308 access. An immutable hard disk is always attached indirectly. The
6309 created differencing hard disk is automatically wiped out (recreated
6310 from scratch) every time you power off the virtual machine. Thus,
6311 the contents of the immutable disk remains unchanged between runs.
6312
6313 Detaching an immutable hard disk deletes the differencing disk
6314 created for it, with the same effect as in case with normal hard
6315 disks.
6316
6317 When taking a snapshot, the differencing part of the immutable
6318 hard disk is cloned (i.e. copied to a separate Virtual Disk Image
6319 file) without any changes. This is necessary to preserve the exact
6320 virtual machine state when you create an online snapshot.
6321
6322 <b>Writethrough Hard Disks</b>
6323
6324 Hard disks of this type are always attached directly. This means
6325 that every given writethrough hard disk can be attached only to one
6326 virtual machine at a time.
6327
6328 It is impossible to take a snapshot of a virtual machine with the
6329 writethrough hard disk attached, because taking a snapshot implies
6330 saving the execution state and preserving the contents of all hard
6331 disks, but writethrough hard disks cannot be preserved. Preserving
6332 hard disk contents is necessary to ensure the guest OS stored in the
6333 snapshot will get the same hard disk state when restored, which is
6334 especially important when it has open file handles or when there are
6335 cached files and directories stored in memory.
6336
6337 <h3>Creating, Opening and Registering Hard Disks</h3>
6338
6339 Non-differencing hard disks are either created from scratch using
6340 <link to="IVirtualBox::createHardDisk()"/> or opened from a VDI file
6341 using <link to="IVirtualBox::openVirtualDiskImage()"/> (only for hard
6342 disks using the VirtualDiskImage storage type). Once a hard disk is
6343 created or opened, it needs to be registered using
6344 <link to="IVirtualBox::registerHardDisk()"/> to make it available for
6345 attaching to virtual machines. See the documentation of individual
6346 interfaces for various storage types to get more information.
6347
6348 Differencing hard disks are never created explicitly and cannot
6349 be registered or unregistered; they are automatically registered
6350 upon creation and deregistered when deleted.
6351
6352 <h3>More about Indirect Hard Disk Attachments</h3>
6353
6354 Normally, when you attach a hard disk to the virtual machine, and then
6355 query the corresponding attachment using
6356 <link to="IMachine::getHardDisk()"/> or
6357 <link to="IMachine::hardDiskAttachments"/> you will get the same hard
6358 disk object, whose UUID you passed earlier to
6359 <link to="IMachine::attachHardDisk()"/>. However, when an indirect
6360 attachment takes place, calling <link to="IMachine::getHardDisk()"/>
6361 will return a differencing hard disk object, that is either based on the
6362 attached hard disk or on another differencing hard disk, the attached
6363 hard disk is eventually a root for (as described above). In both cases
6364 the returned hard disk object is the object the virtual machine actually
6365 uses to perform disk writes to.
6366
6367 Regardless of whether the attachment is direct or indirect, the
6368 <link to="#machineId"/> property of the attached disk will contain an
6369 UUID of the machine object <link to="IMachine::attachHardDisk()"/>
6370 has been called on.
6371
6372 Note that both <link to="IMachine::attachHardDisk()"/> and
6373 <link to="IMachine::detachHardDisk()"/> are <i>lazy</i> operations. In
6374 particular, this means that when an indirect attachment is made,
6375 differencing hard disks are not created until machine settings are
6376 committed using <link to="IMachine::saveSettings()"/>. Similarly, when a
6377 differencing hard disk is detached, it is not deleted until
6378 <link to="IMachine::saveSettings()"/> is called. Calling
6379 <link to="IMachine::discardSettings()"/> cancels all lazy attachments or
6380 detachments made since the last commit and effectively restores the
6381 previous set of hard disks.
6382
6383 <h3>Hard Disk Accessibility</h3>
6384
6385 The <link to="#accessible"/> attribute of the hard disk object
6386 defines the accessibility state of the respective hard disk storage
6387 (for example, the VDI file for IVirtualDiskImage objects). If the
6388 value of this attribute is <tt>false</tt> then some hard disk
6389 attributes may contain invalid or outdated values (for example, the
6390 virtual or the actual hard disk size) until a new accessibility
6391 check is done that returns <tt>true</tt> (see the attribute
6392 description for more details).
6393
6394 <note>
6395 Because of the possible slowness of the accessibility check,
6396 it is not implicitly performed upon the VirtualBox server startup
6397 (to prevent the application freeze). In partcular, this means that
6398 if you try to read hard disk properties that depend on the
6399 accessibility state without first reading the value of the
6400 <link to="#accessible"/> attribute and ensuring it's value is
6401 <tt>true</tt>, you will get wrong (zero) values.
6402 </note>
6403
6404 </desc>
6405
6406 <attribute name="id" type="uuid" readonly="yes">
6407 <desc>
6408
6409 UUID of the hard disk. For newly created hard disk objects,
6410 this value is a randomly generated UUID.
6411
6412 </desc>
6413 </attribute>
6414
6415 <attribute name="description" type="wstring">
6416 <desc>
6417
6418 Optional description of the hard disk. For a newly created hard
6419 disk, this value is <tt>null</tt>.
6420
6421 <note>For some storage types, reading this property is
6422 meaningless when <link to="#accessible"/> is <tt>false</tt>.
6423 Also, you cannot assign it a new value in this case.</note>
6424
6425 </desc>
6426 </attribute>
6427
6428 <attribute name="storageType" type="HardDiskStorageType" readonly="yes">
6429 <desc>
6430
6431 Storage type of this hard disk.
6432
6433 Storage type is defined when you open or create a new hard disk
6434 object.
6435
6436 </desc>
6437 </attribute>
6438
6439 <attribute name="location" type="wstring" readonly="yes">
6440 <desc>
6441
6442 Storage location of this hard disk. The returned string serves
6443 for informational purposes only. To access detailed information
6444 about the storage, query the appropriate storage-specific
6445 interface.
6446
6447 </desc>
6448 </attribute>
6449
6450 <attribute name="type" type="HardDiskType">
6451 <desc>
6452
6453 Type (behavior) of this hard disk. For a newly created or opened hard
6454 disk, this value is <link to="HardDiskType::Normal"/>.
6455
6456 <note>
6457 In the current implementation, this property can be
6458 changed only on an unregistered hard disk object. This may be
6459 changed later.
6460 </note>
6461
6462 </desc>
6463 </attribute>
6464
6465 <attribute name="parent" type="IHardDisk" readonly="yes">
6466 <desc>
6467
6468 Parent of this hard disk (a hard disk this one is directly based
6469 on).
6470
6471 Only differencing hard disks have parents, so a <tt>null</tt>
6472 object is returned for a hard disk of any other type.
6473 </desc>
6474 </attribute>
6475
6476 <attribute name="children" type="IHardDiskCollection" readonly="yes">
6477 <desc>
6478
6479 Children of this hard disk (all differencing hard disks for
6480 those this one is a parent). An empty collection is returned, if
6481 this hard disk doesn't have any children.
6482
6483 </desc>
6484 </attribute>
6485
6486 <attribute name="root" type="IHardDisk" readonly="yes">
6487 <desc>
6488
6489 Root hard disk of this hard disk. If this hard disk is a
6490 differencing hard disk, its root hard disk is the first disk on
6491 the branch. For all other types of hard disks, this property
6492 returns the hard disk object itself (i.e. the same object you
6493 read this property on).
6494
6495 </desc>
6496 </attribute>
6497
6498 <attribute name="accessible" type="boolean" readonly="yes">
6499 <desc>
6500
6501 Whether the hard disk storage is currently accessible or not.
6502 The storage, for example, can be unaccessible if it doesn't exist
6503 or if it is placed on a network resource that is not available
6504 by the time this attribute is read.
6505
6506 In the current implementation, the value of this property is
6507 also <tt>false</tt> if this hard disk is attached to a running
6508 virtual machine.
6509
6510 The accessibility check is performed automatically every time
6511 this attribute is read. You should keep it in mind that this check
6512 may be slow and can block the calling thread for a long time (for
6513 example, if the network resourse where the hard disk storage is
6514 located is down).
6515
6516 The following attributes of the hard disk object are considered
6517 to be invalid when this attribute is <tt>false</tt>:
6518 <ul>
6519 <li><link to="#size"/></li>
6520 <li><link to="#actualSize"/></li>
6521 </ul>
6522 Individual hard disk storage type interfaces may define
6523 additional attributes that depend on the accessibility state.
6524 </desc>
6525 </attribute>
6526
6527 <attribute name="allAccessible" type="boolean" readonly="yes">
6528 <desc>
6529
6530 Whether the whole hard disk branch, starting from this image and
6531 going through its ancestors up to the root, is accessible or
6532 not.
6533
6534 This property makes sense only for differencing hard disks. For
6535 all other types of hard disks it returns the same value as
6536 <link to="#accessible"/>.
6537
6538 </desc>
6539 </attribute>
6540
6541 <attribute name="lastAccessError" type="wstring" readonly="yes">
6542 <desc>
6543
6544 String describing the reason of inaccessibility of this hard
6545 disk after the last call to <link to="#accessible"/> that
6546 returned <tt>false</tt>. A <tt>null</tt> value of this property
6547 means that the last accessibility check returned <tt>true</tt>.
6548
6549 </desc>
6550 </attribute>
6551
6552 <attribute name="size" type="unsigned long long" readonly="yes">
6553 <desc>
6554
6555 Logical size of this hard disk (in megabytes), as reported to the
6556 guest OS running inside the vurtual machine this disk is
6557 attached to. The logical size is defined when the hard disk is
6558 created.
6559
6560 <note>Reading this property on a differencing hard disk will
6561 return the size of its root hard disk.</note>
6562
6563 <note>Reading this property is meaningless when
6564 <link to="#accessible"/> is <tt>false</tt></note>
6565
6566 </desc>
6567 </attribute>
6568
6569 <attribute name="actualSize" type="unsigned long long" readonly="yes">
6570 <desc>
6571
6572 Physical size of the storage used to store hard disk data (in
6573 bytes). This size is usually less than the logical size of the
6574 hard disk, depending on the storage type and on the size
6575 optimization method used for that storage.
6576
6577 <note>Reading this property is meaningless when
6578 <link to="#accessible"/> is <tt>false</tt></note>
6579
6580 </desc>
6581 </attribute>
6582
6583 <attribute name="machineId" type="uuid" readonly="yes">
6584 <desc>
6585
6586 UUID of the machine this hard disk is attached to (or a
6587 <tt>null</tt> UUID if it is not attached).
6588
6589 <note>Immutable hard disks are never attached directly, so this
6590 attribute is always <tt>null</tt> in this case.</note>
6591
6592 </desc>
6593 </attribute>
6594
6595 <attribute name="snapshotId" type="uuid" readonly="yes">
6596 <desc>
6597
6598 UUID of the <link to="ISnapshot">snapshot</link> this hard disk
6599 is associated with (or <tt>null</tt> UUID if it is not
6600 associated with any snapshot).
6601
6602 <note>
6603 This attribute is always <tt>null</tt> if <link to="#machineId"/>
6604 is <tt>null</tt>.
6605 </note>
6606
6607 <note>
6608 Writethrough hard disks are always attached directly and cannot be
6609 involved when taking snapshots, so this attribute is meaningless and
6610 therefore always <tt>null</tt>.
6611 </note>
6612
6613 </desc>
6614 </attribute>
6615
6616 <method name="cloneToImage">
6617
6618 <desc>
6619
6620 Starts creating a clone of this hard disk. The cloned hard disk
6621 will use the specified Virtual Disk Image file as a storage and
6622 will contain exactly the same sector data as the hard disk being
6623 cloned, except that a new UUID for the clone will be randomly
6624 generated.
6625
6626 The specified image file path can be absolute (full path) or
6627 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
6628 home directory</link>. If only a file name without any path is
6629 given, the <link to="ISystemProperties::defaultVDIFolder">
6630 default VDI folder</link> will be used as a path to the image
6631 file.
6632
6633 It is an error to use the object returned in the @a image
6634 parameter until the returned @a progress object reports success.
6635
6636 <note>In the current implementation, only non-differencing hard
6637 disks can be cloned.</note>
6638
6639 </desc>
6640
6641 <param name="filePath" type="wstring" dir="in">
6642 <desc>Path to a file where to store the cloned hard disk.</desc>
6643 </param>
6644 <param name="image" type="IVirtualDiskImage" dir="out">
6645 <desc>Cloned hard disk object.</desc>
6646 </param>
6647 <param name="progress" type="IProgress" dir="return">
6648 <desc>Progress object to track the operation completion.</desc>
6649 </param>
6650
6651 </method>
6652
6653 </interface>
6654
6655 <!--
6656 // IVirtualDiskImage
6657 /////////////////////////////////////////////////////////////////////////
6658 -->
6659
6660 <interface
6661 name="IVirtualDiskImage" extends="$unknown"
6662 uuid="a8265b5a-0d20-4a46-a02f-65693a4e8239"
6663 wsmap="managed"
6664 >
6665
6666 <desc>
6667 The IVirtualDiskImage interface represent a specific type of
6668 <link to="IHardDisk" /> that uses VDI image files.
6669
6670 The Virtual Disk Image (VDI) format is VirtualBox's native format for
6671 hard disk containers.
6672
6673 Objects that support this interface also support the
6674 <link to="IHardDisk"/> interface.
6675
6676 Hard disks using virtual disk images can be either opened using
6677 <link to="IVirtualBox::openHardDisk()"/> or created from
6678 scratch using <link to="IVirtualBox::createHardDisk()"/>.
6679
6680 When a new hard disk object is created from scratch, an image file for it
6681 is not automatically created. To do it, you need to specify a
6682 valid <link to="#filePath">file path</link>, and call
6683 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
6684 When it is done, the hard disk object can be registered by calling
6685 <link to="IVirtualBox::registerHardDisk()"/> and then
6686 <link to="IMachine::attachHardDisk()">attached</link> to
6687 virtual machines.
6688
6689 The <link to="IHardDisk::description">description</link> of the
6690 Virtual Disk Image is stored in the image file. For this reason,
6691 changing the value of this property requires the hard disk to be
6692 <link to="IHardDisk::accessible">accessible</link>. The description
6693 of a registered hard disk can be changed only if a virtual machine
6694 using it is not running.
6695
6696 </desc>
6697
6698 <attribute name="filePath" type="wstring">
6699 <desc>
6700
6701 Full file name of the virtual disk image of this hard disk. For
6702 newly created hard disk objects, this value is <tt>null</tt>.
6703
6704 When assigning a new path, it can be absolute (full path) or relative
6705 to the <link to="IVirtualBox::homeFolder"> VirtualBox home
6706 directory</link>. If only a file name without any path is given,
6707 the <link to="ISystemProperties::defaultVDIFolder"> default VDI
6708 folder</link> will be used as a path to the image file.
6709
6710 When reading this propery, a full path is always returned.
6711
6712 <note>
6713 This property cannot be changed when <link to="#created"/>
6714 returns <tt>true</tt>.
6715 </note>
6716
6717 </desc>
6718 </attribute>
6719
6720 <attribute name="created" type="boolean" readonly="yes">
6721 <desc>
6722
6723 Whether the virual disk image is created or not. For newly
6724 created hard disk objects or after a successful invocation of
6725 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
6726 <link to="#createFixedImage()"/> or <link
6727 to="#createDynamicImage()"/> is called.
6728
6729 </desc>
6730 </attribute>
6731
6732 <method name="createDynamicImage">
6733
6734 <desc>
6735
6736 Starts creating a dymically expanding hard disk image in the
6737 background. The previous image associated with this object, if
6738 any, must be deleted using <link to="#deleteImage"/>, otherwise
6739 the operation will fail.
6740
6741 <note>After the returned progress object reports that the
6742 operation is complete, this hard disk object can be
6743 <link to="IVirtualBox::registerHardDisk()">registered</link>
6744 within this VirtualBox installation.</note>
6745
6746 </desc>
6747
6748 <param name="size" type="unsigned long long" dir="in">
6749 <desc>Maximum logical size of the hard disk in megabytes.</desc>
6750 </param>
6751 <param name="progress" type="IProgress" dir="return">
6752 <desc>Progress object to track the operation completion.</desc>
6753 </param>
6754
6755 </method>
6756
6757 <method name="createFixedImage">
6758 <desc>
6759
6760 Starts creating a fixed-size hard disk image in the background. The
6761 previous image, if any, must be deleted using
6762 <link to="#deleteImage"/>, otherwise the operation will fail.
6763
6764 <note>
6765 After the returned progress object reports that the
6766 operation is complete, this hard disk object can be
6767 <link to="IVirtualBox::registerHardDisk()">registered</link>
6768 within this VirtualBox installation.
6769 </note>
6770
6771 </desc>
6772
6773 <param name="size" type="unsigned long long" dir="in">
6774 <desc>Logical size of the hard disk in megabytes.</desc>
6775 </param>
6776 <param name="progress" type="IProgress" dir="return">
6777 <desc>Progress object to track the operation completion.</desc>
6778 </param>
6779
6780 </method>
6781
6782 <method name="deleteImage">
6783 <desc>
6784
6785 Deletes the existing hard disk image. The hard disk must not be
6786 registered within this VirtualBox installation, otherwise the
6787 operation will fail.
6788
6789 <note>
6790 After this operation succeeds, it will be impossible to
6791 register the hard disk until the image file is created
6792 again.
6793 </note>
6794
6795 <note>
6796 This operation is valid only for non-differencing hard disks, after
6797 they are unregistered using
6798 <link to="IVirtualBox::unregisterHardDisk()"/>.
6799 </note>
6800
6801 </desc>
6802 </method>
6803
6804 </interface>
6805
6806 <!--
6807 // IISCSIHardDisk
6808 /////////////////////////////////////////////////////////////////////////
6809 -->
6810
6811 <interface
6812 name="IISCSIHardDisk" extends="$unknown"
6813 uuid="003f6ca9-3257-4ef9-99c9-c66ce44576cb"
6814 wsmap="managed"
6815 >
6816
6817 <desc>
6818 THe IISCSIHardDisk interface represents a specific type of
6819 <link to="IHardDisk"/> that uses iSCSI.
6820
6821 The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
6822 hard disks</link> that use the Internet SCSI (iSCSI) protocol to store
6823 hard disk data on remote machines.
6824
6825 Objects that support this interface also support the
6826 <link to="IHardDisk"/> interface.
6827
6828 iSCSI hard disks can be created using
6829 <link to="IVirtualBox::createHardDisk()"/>. When a new hard disk object
6830 is created, all its properties are uninitialized. After you assign some
6831 meaningful values to them, the hard disk object can be registered by
6832 calling <link to="IVirtualBox::registerHardDisk()"/> and
6833 then <link to="IMachine::attachHardDisk()">attached</link> to virtual
6834 machines.
6835
6836 The <link to="IHardDisk::description">description</link>
6837 of the iSCSI hard disk is stored in the VirtualBox
6838 configuration file, so it can be changed (at appropriate
6839 times) even when
6840 <link to="IHardDisk::accessible">accessible</link> returns
6841 <tt>false</tt>. However, the hard disk must not be
6842 attached to a running virtual machine.
6843
6844 <note>
6845 In the current imlementation, the type of all iSCSI hard disks
6846 is <link to="HardDiskType::Writethrough">Writethrough</link>
6847 and cannot be changed.
6848 </note>
6849
6850 </desc>
6851
6852 <attribute name="server" type="wstring">
6853 <desc>
6854
6855 iSCSI Server name (either a host name or an IP address). For
6856 newly created hard disk objects, this value is <tt>null</tt>.
6857
6858 </desc>
6859 </attribute>
6860
6861 <attribute name="port" type="unsigned short">
6862 <desc>
6863
6864 iSCSI Server port. For newly created hard disk objects, this
6865 value is <tt>0</tt>, which means the default port.
6866
6867 </desc>
6868 </attribute>
6869
6870 <attribute name="target" type="wstring">
6871 <desc>
6872
6873 iSCSI target name. For newly created hard disk objects, this
6874 value is <tt>null</tt>.
6875
6876 </desc>
6877 </attribute>
6878
6879 <attribute name="lun" type="unsigned long long">
6880 <desc>
6881
6882 Logical unit number for this iSCSI disk. For newly created hard
6883 disk objects, this value is <tt>0</tt>.
6884
6885 </desc>
6886 </attribute>
6887
6888 <attribute name="userName" type="wstring">
6889 <desc>
6890
6891 User name for accessing this iSCSI disk. For newly created hard
6892 disk objects, this value is <tt>null</tt>.
6893
6894 </desc>
6895 </attribute>
6896
6897 <attribute name="password" type="wstring">
6898 <desc>
6899
6900 User password for accessing this iSCSI disk. For newly created
6901 hard disk objects, this value is <tt>null</tt>.
6902
6903 </desc>
6904 </attribute>
6905
6906 </interface>
6907
6908 <!--
6909 // IVMDKImage
6910 /////////////////////////////////////////////////////////////////////////
6911 -->
6912
6913 <interface
6914 name="IVMDKImage" extends="$unknown"
6915 uuid="178398f5-8559-4fee-979e-420af5b53eef"
6916 wsmap="managed"
6917 >
6918 <desc>
6919 The IVMDKImage interface represents a specific type of
6920 <link to="IHardDisk"/> that uses VMDK image files.
6921
6922 The Virtual Machine Disk (VMDK) format is the industry standard format
6923 for virtual hard disk image files, which VirtualBox supports besides its
6924 own native VDI format.
6925
6926 Objects that support this interface also support the
6927 <link to="IHardDisk"/> interface.
6928
6929 Hard disks using VMDK images can be either opened using
6930 <link to="IVirtualBox::openHardDisk()"/> or created from
6931 scratch using <link to="IVirtualBox::createHardDisk()"/>.
6932
6933 When a new hard disk object is created from scratch, an image file for it
6934 is not automatically created. To do it, you need to specify a
6935 valid <link to="#filePath">file path</link>, and call
6936 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
6937 When it is done, the hard disk object can be registered by calling
6938 <link to="IVirtualBox::registerHardDisk()"/> and then
6939 <link to="IMachine::attachHardDisk()">attached</link> to
6940 virtual machines.
6941
6942 The <link to="IHardDisk::description">description</link>
6943 of the VMDK hard disk is stored in the VirtualBox
6944 configuration file, so it can be changed (at appropriate
6945 times) even when
6946 <link to="IHardDisk::accessible">accessible</link> returns
6947 <tt>false</tt>. However, the hard disk must not be
6948 attached to a running virtual machine.
6949
6950 <note>
6951 In the current imlementation, the type of all VMDK hard disks
6952 is <link to="HardDiskType::Writethrough">Writethrough</link> and cannot
6953 be changed.
6954 </note>
6955
6956 </desc>
6957
6958 <attribute name="filePath" type="wstring">
6959 <desc>
6960
6961 Full file name of the VMDK image of this hard disk. For
6962 newly created hard disk objects, this value is <tt>null</tt>.
6963
6964 When assigning a new path, it can be absolute (full path) or relative
6965 to the <link to="IVirtualBox::homeFolder"> VirtualBox home
6966 directory</link>. If only a file name without any path is given,
6967 the <link to="ISystemProperties::defaultVDIFolder"> default VDI
6968 folder</link> will be used as a path to the image file.
6969
6970 When reading this propery, a full path is always returned.
6971
6972 <note>
6973 This property cannot be changed when <link to="#created"/>
6974 returns <tt>true</tt>.
6975 </note>
6976
6977 </desc>
6978 </attribute>
6979
6980 <attribute name="created" type="boolean" readonly="yes">
6981 <desc>
6982
6983 Whether the virual disk image is created or not. For newly created
6984 hard disk objects or after a successful invocation of
6985 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
6986 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
6987 is called.
6988
6989 </desc>
6990 </attribute>
6991
6992 <method name="createDynamicImage">
6993
6994 <desc>
6995
6996 Starts creating a dymically expanding hard disk image in the
6997 background. The previous image associated with this object, if
6998 any, must be deleted using <link to="#deleteImage"/>, otherwise
6999 the operation will fail.
7000
7001 <note>
7002 After the returned progress object reports that the
7003 operation is complete, this hard disk object can be
7004 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7005 this VirtualBox installation.
7006 </note>
7007
7008 </desc>
7009
7010 <param name="size" type="unsigned long long" dir="in">
7011 <desc>Maximum logical size of the hard disk in megabytes.</desc>
7012 </param>
7013 <param name="progress" type="IProgress" dir="return">
7014 <desc>Progress object to track the operation completion.</desc>
7015 </param>
7016
7017 </method>
7018
7019 <method name="createFixedImage">
7020 <desc>
7021
7022 Starts creating a fixed-size hard disk image in the background. The
7023 previous image, if any, must be deleted using
7024 <link to="#deleteImage"/>, otherwise the operation will fail.
7025
7026 <note>
7027 After the returned progress object reports that the
7028 operation is complete, this hard disk object can be
7029 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7030 this VirtualBox installation.
7031 </note>
7032
7033 </desc>
7034
7035 <param name="size" type="unsigned long long" dir="in">
7036 <desc>Logical size of the hard disk in megabytes.</desc>
7037 </param>
7038 <param name="progress" type="IProgress" dir="return">
7039 <desc>Progress object to track the operation completion.</desc>
7040 </param>
7041
7042 </method>
7043
7044 <method name="deleteImage">
7045 <desc>
7046
7047 Deletes the existing hard disk image. The hard disk must not be
7048 registered within this VirtualBox installation, otherwise the
7049 operation will fail.
7050
7051 <note>
7052 After this operation succeeds, it will be impossible to register the
7053 hard disk until the image file is created again.
7054 </note>
7055
7056 <note>
7057 This operation is valid only for non-differencing hard disks, after
7058 they are unregistered using
7059 <link to="IVirtualBox::unregisterHardDisk()"/>.
7060 </note>
7061
7062 </desc>
7063 </method>
7064
7065 </interface>
7066
7067 <!--
7068 // ICustomHardDisk
7069 /////////////////////////////////////////////////////////////////////////
7070 -->
7071
7072 <interface
7073 name="ICustomHardDisk" extends="$unknown"
7074 uuid="a7b0236d-3ff4-47c0-a4aa-ddc4ddc1141a"
7075 wsmap="managed"
7076 >
7077 <desc>
7078 The ICustomHardDisk interface represents a specific type of
7079 <link to="IHardDisk" /> that is supported through a third-party plugin.
7080
7081 This interface allows to add support for custom hard disk formats to
7082 VirtualBox.
7083
7084 Objects that support this interface also support the
7085 <link to="IHardDisk"/> interface.
7086
7087 Hard disks using custom hard disk formats can be either opened using
7088 <link to="IVirtualBox::openHardDisk()"/> or created from scratch using
7089 <link to="IVirtualBox::createHardDisk()"/>.
7090
7091 When a new hard disk object is created from scratch, an image file for
7092 it is not automatically created. To do it, you need to specify a
7093 valid <link to="#location">location</link>, and call
7094 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
7095 When it is done, the hard disk object can be registered by calling
7096 <link to="IVirtualBox::registerHardDisk()"/> and then
7097 <link to="IMachine::attachHardDisk()">attached</link> to
7098 virtual machines.
7099
7100 The <link to="IHardDisk::description">description</link>
7101 of the hard disk is stored in the VirtualBox
7102 configuration file, so it can be changed (at appropriate
7103 times) even when
7104 <link to="IHardDisk::accessible">accessible</link> returns
7105 <tt>false</tt>. However, the hard disk must not be
7106 attached to a running virtual machine.
7107
7108 </desc>
7109
7110 <attribute name="location" type="wstring">
7111 <desc>
7112
7113 Location of this custom hard disk. For
7114 newly created hard disk objects, this value is <tt>null</tt>.
7115
7116 The format of the location string is plugin-dependent. In case if the
7117 plugin uses a regular file in the local file system to store hard disk
7118 data, then the location is a file path and the following rules apply:
7119 <ul>
7120 <li>
7121 when assigning a new path, it must be absolute (full path) or
7122 relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
7123 home directory</link>. If only a file name without any path is
7124 given, the <link to="ISystemProperties::defaultVDIFolder"> default
7125 VDI folder</link> will be used as a path to the image file.
7126 </li>
7127 <li>
7128 When reading this propery, a full path is always returned.
7129 </li>
7130 </ul>
7131
7132 <note>
7133 This property cannot be changed when <link to="#created"/>
7134 returns <tt>true</tt>.
7135 </note>
7136
7137 </desc>
7138 </attribute>
7139
7140 <attribute name="format" type="wstring" readonly="yes">
7141 <desc>
7142
7143 The plugin name of the image file.
7144
7145 </desc>
7146 </attribute>
7147
7148 <attribute name="created" type="boolean" readonly="yes">
7149 <desc>
7150
7151 Whether the virual disk image is created or not. For newly created
7152 hard disk objects or after a successful invocation of
7153 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
7154 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
7155 is called.
7156
7157 </desc>
7158 </attribute>
7159
7160 <method name="createDynamicImage">
7161
7162 <desc>
7163
7164 Starts creating a dymically expanding hard disk image in the
7165 background. The previous image associated with this object, if
7166 any, must be deleted using <link to="#deleteImage"/>, otherwise
7167 the operation will fail.
7168
7169 <note>
7170 After the returned progress object reports that the
7171 operation is complete, this hard disk object can be
7172 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7173 this VirtualBox installation.
7174 </note>
7175
7176 </desc>
7177
7178 <param name="size" type="unsigned long long" dir="in">
7179 <desc>Maximum logical size of the hard disk in megabytes.</desc>
7180 </param>
7181 <param name="progress" type="IProgress" dir="return">
7182 <desc>Progress object to track the operation completion.</desc>
7183 </param>
7184
7185 </method>
7186
7187 <method name="createFixedImage">
7188 <desc>
7189
7190 Starts creating a fixed-size hard disk image in the background. The
7191 previous image, if any, must be deleted using
7192 <link to="#deleteImage"/>, otherwise the operation will fail.
7193
7194 <note>
7195 After the returned progress object reports that the
7196 operation is complete, this hard disk object can be
7197 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7198 this VirtualBox installation.
7199 </note>
7200
7201 </desc>
7202
7203 <param name="size" type="unsigned long long" dir="in">
7204 <desc>Logical size of the hard disk in megabytes.</desc>
7205 </param>
7206 <param name="progress" type="IProgress" dir="return">
7207 <desc>Progress object to track the operation completion.</desc>
7208 </param>
7209
7210 </method>
7211
7212 <method name="deleteImage">
7213 <desc>
7214
7215 Deletes the existing hard disk image. The hard disk must not be
7216 registered within this VirtualBox installation, otherwise the
7217 operation will fail.
7218
7219 <note>
7220 After this operation succeeds, it will be impossible to register the
7221 hard disk until the image file is created again.
7222 </note>
7223
7224 <note>
7225 This operation is valid only for non-differencing hard disks, after
7226 they are unregistered using
7227 <link to="IVirtualBox::unregisterHardDisk()"/>.
7228 </note>
7229
7230 </desc>
7231 </method>
7232
7233 </interface>
7234
7235 <!--
7236 // IVHDImage
7237 /////////////////////////////////////////////////////////////////////////
7238 -->
7239
7240 <interface
7241 name="IVHDImage" extends="$unknown"
7242 uuid="163b88c3-7552-424a-8205-daf17a004747"
7243 wsmap="managed"
7244 >
7245 <desc>
7246
7247 The IVHDImage interface represents <link to="IHardDisk">virtual hard
7248 disks</link> that use Virtual PC Virtual Machine Disk image files to store
7249 hard disk data.
7250
7251 Hard disks using VHD images can be either opened using
7252 <link to="IVirtualBox::openHardDisk()"/> or created from
7253 scratch using <link to="IVirtualBox::createHardDisk()"/>.
7254
7255 Objects that support this interface also support the
7256 <link to="IHardDisk"/> interface.
7257
7258 When a new hard disk object is created from scatch, an image file for it
7259 is not automatically created. To do it, you need to specify a
7260 valid <link to="#filePath">file path</link>, and call
7261 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
7262 When it is done, the hard disk object can be registered by calling
7263 <link to="IVirtualBox::registerHardDisk()"/> and then
7264 <link to="IMachine::attachHardDisk()">attached</link> to
7265 virtual machines.
7266
7267 The <link to="IHardDisk::description">description</link>
7268 of the VHD hard disk is stored in the VirtualBox
7269 configuration file, so it can be changed (at appropriate
7270 times) even when
7271 <link to="IHardDisk::accessible">accessible</link> returns
7272 <tt>false</tt>. However, the hard disk must not be
7273 attached to a running virtual machine.
7274
7275 <note>
7276 In the current imlementation, the type of all VHD hard disks
7277 is <link to="HardDiskType::Writethrough">Writethrough</link> and cannot
7278 be changed.
7279 </note>
7280
7281 </desc>
7282
7283 <attribute name="filePath" type="wstring">
7284 <desc>
7285
7286 Full file name of the VHD image of this hard disk. For
7287 newly created hard disk objects, this value is <tt>null</tt>.
7288
7289 When assigning a new path, it can be absolute (full path) or relative
7290 to the <link to="IVirtualBox::homeFolder"> VirtualBox home
7291 directory</link>. If only a file name without any path is given,
7292 the <link to="ISystemProperties::defaultVDIFolder"> default VDI
7293 folder</link> will be used as a path to the image file.
7294
7295 When reading this propery, a full path is always returned.
7296
7297 <note>
7298 This property cannot be changed when <link to="#created"/>
7299 returns <tt>true</tt>. In this case, the specified file name can be
7300 absolute (full path) or relative to
7301 the <link to="IVirtualBox::homeFolder"> VirtualBox home
7302 directory</link>. If only a file name without any path is given,
7303 the <link to="ISystemProperties::defaultVDIFolder"> default VDI
7304 folder</link> will be used as a path to the image file.
7305 </note>
7306
7307 </desc>
7308 </attribute>
7309
7310 <attribute name="created" type="boolean" readonly="yes">
7311 <desc>
7312
7313 Whether the virual disk image is created or not. For newly created
7314 hard disk objects or after a successful invocation of
7315 <link to="#deleteImage()"/>, this value is <tt>false</tt> until
7316 <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
7317 is called.
7318
7319 </desc>
7320 </attribute>
7321
7322 <method name="createDynamicImage">
7323
7324 <desc>
7325
7326 Starts creating a dymically expanding hard disk image in the
7327 background. The previous image associated with this object, if
7328 any, must be deleted using <link to="#deleteImage"/>, otherwise
7329 the operation will fail.
7330
7331 <note>
7332 After the returned progress object reports that the
7333 operation is complete, this hard disk object can be
7334 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7335 this VirtualBox installation.
7336 </note>
7337
7338 </desc>
7339
7340 <param name="size" type="unsigned long long" dir="in">
7341 <desc>Maximum logical size of the hard disk in megabytes.</desc>
7342 </param>
7343 <param name="progress" type="IProgress" dir="return">
7344 <desc>Progress object to track the operation completion.</desc>
7345 </param>
7346
7347 </method>
7348
7349 <method name="createFixedImage">
7350 <desc>
7351
7352 Starts creating a fixed-size hard disk image in the background. The
7353 previous image, if any, must be deleted using
7354 <link to="#deleteImage"/>, otherwise the operation will fail.
7355
7356 <note>
7357 After the returned progress object reports that the
7358 operation is complete, this hard disk object can be
7359 <link to="IVirtualBox::registerHardDisk()">registered</link> within
7360 this VirtualBox installation.
7361 </note>
7362
7363 </desc>
7364
7365 <param name="size" type="unsigned long long" dir="in">
7366 <desc>Logical size of the hard disk in megabytes.</desc>
7367 </param>
7368 <param name="progress" type="IProgress" dir="return">
7369 <desc>Progress object to track the operation completion.</desc>
7370 </param>
7371
7372 </method>
7373
7374 <method name="deleteImage">
7375 <desc>
7376
7377 Deletes the existing hard disk image. The hard disk must not be
7378 registered within this VirtualBox installation, otherwise the
7379 operation will fail.
7380
7381 <note>
7382 After this operation succeeds, it will be impossible to register the
7383 hard disk until the image file is created again.
7384 </note>
7385
7386 <note>
7387 This operation is valid only for non-differencing hard disks, after
7388 they are unregistered using
7389 <link to="IVirtualBox::unregisterHardDisk()"/>.
7390 </note>
7391
7392 </desc>
7393 </method>
7394
7395 </interface>
7396
7397 <!--
7398 // IDVDImage
7399 /////////////////////////////////////////////////////////////////////////
7400 -->
7401
7402 <enumerator
7403 name="IDVDImageEnumerator" type="IDVDImage"
7404 uuid="9BE77C8D-E1BE-4bf2-A67B-B4DD3D2B0F28"
7405 />
7406
7407 <collection
7408 name="IDVDImageCollection" type="IDVDImage"
7409 enumerator="IDVDImageEnumerator"
7410 uuid="AE7053FA-ADD2-4ea4-AFCF-24D5F8DDED64"
7411 readonly="yes"
7412 >
7413 <method name="findByPath">
7414 <desc>
7415 Searches this collection for a DVD image with the given disk path.
7416 <note>
7417 The method returns an error if the given name does not
7418 correspond to any DVD image in the collection.
7419 </note>
7420 </desc>
7421 <param name="path" type="wstring" dir="in">
7422 <desc>Name of the DVD image's file system location.</desc>
7423 </param>
7424 <param name="image" type="IDVDImage" dir="return">
7425 <desc>Found DVD image object</desc>
7426 </param>
7427 </method>
7428 </collection>
7429
7430 <interface
7431 name="IDVDImage" extends="$unknown"
7432 uuid="140FFF03-E479-4194-8562-ABC4F8171009"
7433 wsmap="managed"
7434 >
7435 <desc>
7436
7437 The IDVDImage interface represents a file containing the image
7438 of the DVD or CD disk.
7439
7440 <h3>Image Accessibility</h3>
7441
7442 The <link to="#accessible"/> attribute of the image object
7443 defines the accessibility state of the image file. If the
7444 value of this attribute is <tt>false</tt> then some image
7445 attributes may contain invalid or outdated values (for example, the
7446 the image file size) until a new accessibility
7447 check is done that returns <tt>true</tt>.
7448
7449 <note>
7450 Because of the possible slowness of the accessibility check,
7451 it is not implicitly performed upon the VirtualBox server startup
7452 (to prevent the application freeze). In partcular, this means that
7453 if you try to read image properties that depend on the
7454 accessibility state without first reading the value of the
7455 <link to="#accessible"/> attribute and ensuring it's value is
7456 <tt>true</tt>, you will get wrong (zero) values.
7457 </note>
7458
7459 </desc>
7460 <attribute name="id" type="uuid" readonly="yes">
7461 <desc>UUID of the CD/DVD image.</desc>
7462 </attribute>
7463
7464 <attribute name="filePath" type="wstring" readonly="yes">
7465 <desc>Full file name of the CD/DVD image.</desc>
7466 </attribute>
7467
7468 <attribute name="accessible" type="boolean" readonly="yes">
7469 <desc>
7470
7471 Whether the CD/DVD image is currently accessible or not.
7472 The image, for example, can be unaccessible if it is placed
7473 on a network share that is not available by the time
7474 this property is read.
7475
7476 The accessibility check is performed automatically every time
7477 this attribute is read. You should keep it in mind that this check
7478 may be slow and can block the calling thread for a long time (for
7479 example, if the network share where the image is located is down).
7480
7481 The following attributes of the image object are considered
7482 to be invalid when this attribute is <tt>false</tt>:
7483 <ul>
7484 <li><link to="#size"/></li>
7485 </ul>
7486
7487 </desc>
7488 </attribute>
7489
7490 <attribute name="size" type="unsigned long long" readonly="yes">
7491 <desc>Size of the ISO image in bytes.</desc>
7492 </attribute>
7493
7494 </interface>
7495
7496
7497 <!--
7498 // IDVDDrive
7499 /////////////////////////////////////////////////////////////////////////
7500 -->
7501
7502 <interface
7503 name="IDVDDrive" extends="$unknown"
7504 uuid="d9bd101a-8079-4fb9-bad1-31bf32482b75"
7505 wsmap="managed"
7506 >
7507 <desc>
7508 The IDVDDrive interface represents the virtual CD/DVD drive of the
7509 virtual machine. Used in <link to="IMachine::DVDDrive"/>.
7510 </desc>
7511 <attribute name="state" type="DriveState" readonly="yes">
7512 <desc>Current drive state.</desc>
7513 </attribute>
7514
7515 <attribute name="passthrough" type="boolean">
7516 <desc>
7517 When a host drive is mounted and passthrough is enabled
7518 the guest will be able to directly send SCSI commands to
7519 the host drive. This enables the guest to use CD/DVD writers
7520 but is potentially dangerous.
7521 </desc>
7522 </attribute>
7523
7524 <method name="mountImage">
7525 <desc>Mounts the specified image.</desc>
7526 <param name="imageId" type="uuid" dir="in"/>
7527 </method>
7528
7529 <method name="captureHostDrive">
7530 <desc>Captures the specified host drive.</desc>
7531 <param name="drive" type="IHostDVDDrive" dir="in"/>
7532 </method>
7533
7534 <method name="unmount">
7535 <desc>Unmounts the currently mounted image/device.</desc>
7536 </method>
7537
7538 <method name="getImage">
7539 <desc>Gets the currently mounted image ID.</desc>
7540 <param name="image" type="IDVDImage" dir="return"/>
7541 </method>
7542
7543 <method name="getHostDrive">
7544 <desc>Gets the currently mounted image ID.</desc>
7545 <param name="drive" type="IHostDVDDrive" dir="return"/>
7546 </method>
7547
7548 </interface>
7549
7550 <!--
7551 // IFloppyImage
7552 /////////////////////////////////////////////////////////////////////////
7553 -->
7554
7555 <enumerator
7556 name="IFloppyImageEnumerator" type="IFloppyImage"
7557 uuid="902C4089-76B7-41f1-91E8-49A261A28A2C"
7558 />
7559
7560 <collection
7561 name="IFloppyImageCollection" type="IFloppyImage"
7562 enumerator="IFloppyImageEnumerator"
7563 uuid="327A8928-8572-446e-AD9A-18FE30E81F3F"
7564 readonly="yes">
7565 <method name="findByPath">
7566 <desc>
7567 Searches this collection for a floppy image with the given disk path.
7568 <note>
7569 The method returns an error if the given name does not
7570 correspond to any floppy image in the collection.
7571 </note>
7572 </desc>
7573 <param name="path" type="wstring" dir="in">
7574 <desc>Name of the floppy image's file system location.</desc>
7575 </param>
7576 <param name="image" type="IFloppyImage" dir="return">
7577 <desc>Found Floppy image object</desc>
7578 </param>
7579 </method>
7580 </collection>
7581
7582 <interface
7583 name="IFloppyImage" extends="$unknown"
7584 uuid="CC696755-EA98-4ffe-9DC5-C003047034AB"
7585 wsmap="managed"
7586 >
7587 <desc>
7588
7589 The IFloppyImage interface represents a file containing the image
7590 of a floppy disk.
7591
7592 <h3>Image Accessibility</h3>
7593
7594 The <link to="#accessible"/> attribute of the image object
7595 defines the accessibility state of the image file. If the
7596 value of this attribute is <tt>false</tt> then some image
7597 attributes may contain invalid or outdated values (for example, the
7598 the image file size) until a new accessibility
7599 check is done that returns <tt>true</tt>.
7600
7601 <note>
7602 Because of the possible slowness of the accessibility check,
7603 it is not implicitly performed upon the VirtualBox server startup
7604 (to prevent the application freeze). In partcular, this means that
7605 if you try to read image properties that depend on the
7606 accessibility state without first reading the value of the
7607 <link to="#accessible"/> attribute and ensuring it's value is
7608 <tt>true</tt>, you will get wrong (zero) values.
7609 </note>
7610
7611 </desc>
7612 <attribute name="id" type="uuid" readonly="yes">
7613 <desc>UUID of the floppy image.</desc>
7614 </attribute>
7615
7616 <attribute name="filePath" type="wstring" readonly="yes">
7617 <desc>Full file name of the floppy image.</desc>
7618 </attribute>
7619
7620 <attribute name="accessible" type="boolean" readonly="yes">
7621 <desc>
7622
7623 Whether the floppy image is currently accessible or not.
7624 The image, for example, can be unaccessible if it is placed
7625 on a network share that is not available by the time
7626 this property is read.
7627
7628 The accessibility check is performed automatically every time
7629 this attribute is read. You should keep it in mind that this check
7630 may be slow and can block the calling thread for a long time (for
7631 example, if the network share where the image is located is down).
7632
7633 The following attributes of the image object are considered
7634 to be invalid when this attribute is <tt>false</tt>:
7635 <ul>
7636 <li><link to="#size"/></li>
7637 </ul>
7638
7639 </desc>
7640 </attribute>
7641
7642 <attribute name="size" type="unsigned long" readonly="yes">
7643 <desc>Size of the floppy image in bytes.</desc>
7644 </attribute>
7645
7646 </interface>
7647
7648
7649 <!--
7650 // IFloppyDrive
7651 /////////////////////////////////////////////////////////////////////////
7652 -->
7653
7654 <interface
7655 name="IFloppyDrive" extends="$unknown"
7656 uuid="E9318F71-78D2-4b00-863C-B7CB0030A2D9"
7657 wsmap="managed"
7658 >
7659 <desc>
7660 The IFloppyDrive interface represents the virtual floppy drive of the
7661 virtual machine. Used in <link to="IMachine::FloppyDrive" />.
7662 </desc>
7663
7664 <attribute name="enabled" type="boolean">
7665 <desc>
7666 Flag whether the floppy drive is enabled. If it is disabled,
7667 the floppy drive will not be reported to the guest.
7668 </desc>
7669 </attribute>
7670
7671 <attribute name="state" type="DriveState" readonly="yes">
7672 <desc>Current drive state.</desc>
7673 </attribute>
7674
7675 <method name="mountImage">
7676 <desc>Mounts the specified image.</desc>
7677 <param name="imageId" type="uuid" dir="in"/>
7678 </method>
7679
7680 <method name="captureHostDrive">
7681 <desc>Captures the specified host drive.</desc>
7682 <param name="drive" type="IHostFloppyDrive" dir="in"/>
7683 </method>
7684
7685 <method name="unmount">
7686 <desc>Unmounts the currently mounted image/device.</desc>
7687 </method>
7688
7689 <method name="getImage">
7690 <desc>Gets the currently mounted image ID.</desc>
7691 <param name="image" type="IFloppyImage" dir="return"/>
7692 </method>
7693
7694 <method name="getHostDrive">
7695 <desc>Gets the currently mounted image ID.</desc>
7696 <param name="drive" type="IHostFloppyDrive" dir="return"/>
7697 </method>
7698
7699 </interface>
7700
7701
7702 <!--
7703 // IKeyboard
7704 /////////////////////////////////////////////////////////////////////////
7705 -->
7706
7707 <interface
7708 name="IKeyboard" extends="$unknown"
7709 uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
7710 wsmap="managed"
7711 >
7712 <desc>
7713 The IKeyboard interface represents the virtual machine's keyboard. Used
7714 in <link to="IConsole::keyboard"/>.
7715
7716 Through this interface, the virtual machine's virtual keyboard can be controlled. One
7717 can send keystrokes to the virtual machine and send the Ctrl-Alt-Del sequence to it.
7718 </desc>
7719 <method name="putScancode">
7720 <desc>Sends a scancode to the keyboard.</desc>
7721 <param name="scancode" type="long" dir="in"/>
7722 </method>
7723
7724 <method name="putScancodes">
7725 <desc>Sends an array of scancode to the keyboard.</desc>
7726 <param name="scancodes" type="long" dir="in" safearray="yes"/>
7727 <param name="codesStored" type="unsigned long" dir="return"/>
7728 </method>
7729
7730 <method name="putCAD">
7731 <desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
7732 </method>
7733
7734 </interface>
7735
7736
7737 <!--
7738 // IMouse
7739 /////////////////////////////////////////////////////////////////////////
7740 -->
7741
7742 <enum
7743 name="MouseButtonState"
7744 uuid="03131722-2EC5-4173-9794-0DACA46673EF"
7745 >
7746 <desc>
7747 Mouse button state.
7748 </desc>
7749
7750 <const name="LeftButton" value="0x01"/>
7751 <const name="RightButton" value="0x02"/>
7752 <const name="MiddleButton" value="0x04"/>
7753 <const name="WheelUp" value="0x08"/>
7754 <const name="WheelDown" value="0x10"/>
7755 <const name="MouseStateMask" value="0x1F"/>
7756 </enum>
7757
7758 <interface
7759 name="IMouse" extends="$unknown"
7760 uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
7761 wsmap="managed"
7762 >
7763 <desc>
7764 The IMouse interface represents the virtual machine's mouse. Used in
7765 <link to="IConsole::mouse"/>.
7766
7767 Through this interface, the virtual machine's virtual mouse can be
7768 controlled.
7769 </desc>
7770
7771 <attribute name="absoluteSupported" type="boolean" readonly="yes">
7772 <desc>
7773 Whether the guest OS supports absolute mouse pointer positioning
7774 or not.
7775 <note>
7776 VirtualBox Guest Tools need to be installed to the guest OS
7777 in order to enable absolute mouse positioning support.
7778 You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
7779 callback to be instantly informed about changes of this attribute
7780 during virtual machine execution.
7781 </note>
7782 <see><link to="#putMouseEventAbsolute"/></see>
7783 </desc>
7784 </attribute>
7785
7786 <method name="putMouseEvent">
7787 <desc>
7788 Initiates a mouse event using relative pointer movements
7789 along x and y axis.
7790 </desc>
7791
7792 <param name="dx" type="long" dir="in">
7793 <desc>
7794 Amout of pixels the mouse should move to the right.
7795 Negative values move the mouse to the left.
7796 </desc>
7797 </param>
7798 <param name="dy" type="long" dir="in">
7799 <desc>
7800 Amout of pixels the mouse should move downwards.
7801 Negative values move the mouse upwards.
7802 </desc>
7803 </param>
7804 <param name="dz" type="long" dir="in">
7805 <desc>
7806 Amount of mouse wheel moves.
7807 Positive values describe clockwize wheel rotations,
7808 negative values describe counterclockwise rotations.
7809 </desc>
7810 </param>
7811 <param name="buttonState" type="long" dir="in">
7812 <desc>
7813 The current state of mouse buttons. Every bit represents
7814 a mouse button as follows:
7815 <table>
7816 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
7817 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
7818 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
7819 </table>
7820 A value of <tt>1</tt> means the corresponding button is pressed.
7821 otherwise it is released.
7822 </desc>
7823 </param>
7824 </method>
7825
7826 <method name="putMouseEventAbsolute">
7827 <desc>
7828 Positions the mouse pointer using absolute x and y coordinates.
7829 These coordinates are expressed in pixels and
7830 start from <tt>[1,1]</tt> which corresponds to the top left
7831 corner of the virtual display.
7832
7833 <note>
7834 This method will have effect only if absolute mouse
7835 positioning is supported by the guest OS.
7836 </note>
7837
7838 <see><link to="#absoluteSupported"/></see>
7839 </desc>
7840
7841 <param name="x" type="long" dir="in">
7842 <desc>
7843 X coordinate of the pointer in pixels, starting from <tt>1</tt>.
7844 </desc>
7845 </param>
7846 <param name="y" type="long" dir="in">
7847 <desc>
7848 Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
7849 </desc>
7850 </param>
7851 <param name="dz" type="long" dir="in">
7852 <desc>
7853 Amout of mouse wheel moves.
7854 Positive values describe clockwize wheel rotations,
7855 negative values describe counterclockwise rotations.
7856 </desc>
7857 </param>
7858 <param name="buttonState" type="long" dir="in">
7859 <desc>
7860 The current state of mouse buttons. Every bit represents
7861 a mouse button as follows:
7862 <table>
7863 <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
7864 <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
7865 <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
7866 </table>
7867 A value of <tt>1</tt> means the corresponding button is pressed.
7868 otherwise it is released.
7869 </desc>
7870 </param>
7871 </method>
7872
7873 </interface>
7874
7875 <!--
7876 // IDisplay
7877 /////////////////////////////////////////////////////////////////////////
7878 -->
7879
7880 <enum
7881 name="FramebufferAccelerationOperation"
7882 uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
7883 >
7884 <desc>
7885 Framebuffer acceleration operation.
7886 </desc>
7887
7888 <const name="SolidFillAcceleration" value="1"/>
7889 <const name="ScreenCopyAcceleration" value="2"/>
7890 </enum>
7891
7892 <enum
7893 name="FramebufferPixelFormat"
7894 uuid="6b27d1fc-4f2c-4e9c-a166-01d06540305d"
7895 >
7896 <desc>
7897 Format of the video memory buffer. Constants represented by this enum can
7898 be used to test for particular values of <link
7899 to="IFramebuffer::pixelFormat"/>. See also <link
7900 to="IFramebuffer::requestResize()"/>.
7901
7902 See also www.fourcc.org for more informantion about FOURCC pixel formats.
7903 </desc>
7904
7905 <const name="Opaque" value="0xFFFFFFFF">
7906 <desc>
7907 Unknown buffer format. The user may not assume any particular
7908 format of the buffer.
7909 </desc>
7910 </const>
7911 <const name="FOURCC_RGB" value="0x32424752">
7912 <desc>
7913 Basic RGB format. <link to="IFramebuffer::bitsPerPixel"/> determines
7914 the bit layout.
7915 </desc>
7916 </const>
7917 </enum>
7918
7919 <interface
7920 name="IFramebuffer" extends="$unknown"
7921 uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
7922 wsmap="suppress"
7923 >
7924 <attribute name="address" type="octet" mod="ptr" readonly="yes">
7925 <desc>Address of the start byte of the framebuffer.</desc>
7926 </attribute>
7927
7928 <attribute name="width" type="unsigned long" readonly="yes">
7929 <desc>Framebuffer width, in pixels.</desc>
7930 </attribute>
7931
7932 <attribute name="height" type="unsigned long" readonly="yes">
7933 <desc>Framebuffer height, in pixels.</desc>
7934 </attribute>
7935
7936 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
7937 <desc>
7938 Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
7939 to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, valid values
7940 are: 8, 15, 16, 24 and 32.
7941 </desc>
7942 </attribute>
7943
7944 <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
7945 <desc>
7946 Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
7947 to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, the
7948 size of the scan line must be aligned to 32 bits.
7949 </desc>
7950 </attribute>
7951
7952 <attribute name="pixelFormat" type="unsigned long" readonly="yes">
7953 <desc>
7954 Framebuffer pixel format. It's either one of the values defined by <link
7955 to="FramebufferPixelFormat"/> or a raw FOURCC code.
7956 <note>
7957 This attribute must never return <link
7958 to="PixelFormat::Opaque"/> -- the format of the buffer
7959 <link to="#address"/> points to must be always known.
7960 </note>
7961 </desc>
7962 </attribute>
7963
7964 <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
7965 <desc>
7966 Defines whether this framebuffer uses the virtual video card's memory
7967 buffer (guest VRAM) directly or not. See <link
7968 to="IFramebuffer::requestResize()"/> for more information.
7969 </desc>
7970 </attribute>
7971
7972 <attribute name="heightReduction" type="unsigned long" readonly="yes">
7973 <desc>
7974 Hint from the framebuffer about how much of the standard
7975 screen height it wants to use for itself. This information is
7976 exposed to the guest through the VESA BIOS and VMMDev interface
7977 so that it can use it for determining its video mode table. It
7978 is not guaranteed that the guest respects the value.
7979 </desc>
7980 </attribute>
7981
7982 <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
7983 <desc>
7984 An alpha-blended overlay which is superposed over the framebuffer.
7985 The initial purpose is to allow the display of icons providing
7986 information about the VM state, including disk activity, in front
7987 ends which do not have other means of doing that. The overlay is
7988 designed to controlled exclusively by IDisplay. It has no locking
7989 of its own, and any changes made to it are not guaranteed to be
7990 visible until the affected portion of IFramebuffer is updated. The
7991 overlay can be created lazily the first time it is requested. This
7992 attribute can also return NULL to signal that the overlay is not
7993 implemented.
7994 </desc>
7995 </attribute>
7996
7997 <method name="lock">
7998 <desc>
7999 Locks the framebuffer.
8000 Gets called by the IDisplay object where this framebuffer is
8001 bound to.
8002 </desc>
8003 </method>
8004
8005 <method name="unlock">
8006 <desc>
8007 Unlocks the framebuffer.
8008 Gets called by the IDisplay object where this framebuffer is
8009 bound to.
8010 </desc>
8011 </method>
8012
8013 <method name="notifyUpdate">
8014 <desc>
8015 Informs about an update.
8016 Gets called by the display object where this buffer is
8017 registered.
8018 </desc>
8019 <param name="x" type="unsigned long" dir="in"/>
8020 <param name="y" type="unsigned long" dir="in"/>
8021 <param name="width" type="unsigned long" dir="in"/>
8022 <param name="height" type="unsigned long" dir="in"/>
8023 <param name="finished" type="boolean" dir="return"/>
8024 </method>
8025
8026 <method name="requestResize">
8027 <desc>
8028 Requests a size and pixel format change.
8029
8030 There are two modes of working with the video buffer of the virtual
8031 machine. The <i>indirect</i> mode implies that the IFramebuffer
8032 implementation allocates a memory buffer for the requested display mode
8033 and provides it to the virtual machine. In <i>direct</i> mode, the
8034 IFramebuffer implementation uses the memory buffer allocated and owned
8035 by the virtual machine. This buffer represents the video memory of the
8036 emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
8037 usually faster because the implementation gets a raw pointer to the
8038 guest VRAM buffer which it can directly use for visualising the contents
8039 of the virtual display, as opposed to the indirect mode where the
8040 contents of guest VRAM are copied to the memory buffer provided by
8041 the implementation every time a display update occurs.
8042
8043 It is important to note that the direct mode is really fast only when
8044 the implementation uses the given guest VRAM buffer directly, for
8045 example, by blitting it to the window representing the virtual machine's
8046 display, which saves at least one copy operation comparing to the
8047 indirect mode. However, using the guest VRAM buffer directly is not
8048 always possible: the format and the color depth of this buffer may be
8049 not supported by the target window, or it may be unknown (opaque) as in
8050 case of text or non-linear multi-plane VGA video modes. In this case,
8051 the indirect mode (that is always available) should be used as a
8052 fallback: when the guest VRAM contents are copied to the
8053 implementation-provided memory buffer, color and format conversion is
8054 done authomatically by the underlying code.
8055
8056 The @a pixelFormat parameter defines whether the direct mode is
8057 available or not. If @a pixelFormat is <link
8058 to="PixelFormat::Opaque"/> then direct access to the guest
8059 VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and @a
8060 bytesPerLine parameters must be ignored and the implementation must use
8061 the indirect mode (where it provides its own buffer in one of the
8062 supported formats). In all other cases, @a pixelFormat together with @a
8063 bitsPerPixel and @a bytesPerLine define the format of the video memory
8064 buffer pointed to by the @a VRAM parameter and the implementation is
8065 free to choose which mode to use. To indicate that this framebuffer uses
8066 the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
8067 attribute must return <tt>true</tt> and <link to="#address"/> must
8068 return exactly the same address that is passed in the @a VRAM parameter
8069 of this method; otherwise it is assumed that the indirect strategy is
8070 chosen.
8071
8072 The @a width and @a height parameters represent the size of the
8073 requested display mode in both modes. In case of indirect mode, the
8074 provided memory buffer should be big enough to store data of the given
8075 display mode. In case of direct mode, it is guaranteed that the given @a
8076 VRAM buffer contains enough space to represent the display mode of the
8077 given size. Note that this framebuffer's <link to="#width"/> and <link
8078 to="#height"/> attributes must return exactly the same values as
8079 passed to this method after the resize is completed (see below).
8080
8081 The @a finished output parameter determines if the implementation has
8082 finished resizing the framebuffer or not. If, for some reason, the
8083 resize cannot be finished immediately during this call, @a finished
8084 must be set to @c false, and the implementation must call
8085 <link to="IDisplay::resizeCompleted()"/> after it has returned from
8086 this method as soon as possible. If @a finished is @c false, the
8087 machine will not call any framebuffer methods until
8088 <link to="IDisplay::resizeCompleted()"/> is called.
8089
8090 Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
8091 <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
8092 this framebuffer must return exactly the same values as specified in the
8093 parameters of this method, after the resize is completed. If the
8094 indirect mode is chosen, these attributes must return values describing
8095 the format of the implementation's own memory buffer <link
8096 to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
8097 value must always correlate with <link to="#pixelFormat"/>. Note that
8098 the <link to="#pixelFormat"/> attribute must never return <link
8099 to="PixelFormat::Opaque"/> regardless of the selected mode.
8100
8101 <note>
8102 This method is called by the IDisplay object under the
8103 <link to="#lock()"/> provided by this IFramebuffer
8104 implementation. If this method returns @c false in @a finished, then
8105 this lock is not released until
8106 <link to="IDisplay::resizeCompleted()"/> is called.
8107 </note>
8108 </desc>
8109 <param name="screenId" type="unsigned long" dir="in">
8110 <desc>
8111 Logical screen number. Must be used in the corresponding call to
8112 <link to="IDisplay::resizeCompleted()"/> if this call is made.
8113 </desc>
8114 </param>
8115 <param name="pixelFormat" type="unsigned long" dir="in">
8116 <desc>
8117 Pixel format of the memory buffer pointed to by @a VRAM.
8118 See also <link to="FramebufferPixelFormat"/>.
8119 </desc>
8120 </param>
8121 <param name="VRAM" type="octet" mod="ptr" dir="in">
8122 <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
8123 </param>
8124 <param name="bitsPerPixel" type="unsigned long" dir="in">
8125 <desc>Color depth, bits per pixel.</desc>
8126 </param>
8127 <param name="bytesPerLine" type="unsigned long" dir="in">
8128 <desc>Size of one scan line, in bytes.</desc>
8129 </param>
8130 <param name="width" type="unsigned long" dir="in">
8131 <desc>Width of the guest display, in pixels.</desc>
8132 </param>
8133 <param name="height" type="unsigned long" dir="in">
8134 <desc>Height of the guest display, in pixels.</desc>
8135 </param>
8136 <param name="finished" type="boolean" dir="return">
8137 <desc>
8138 Can the VM start using the new framebuffer immediately
8139 after this method returns or it should wait for
8140 <link to="IDisplay::resizeCompleted()"/>.
8141 </desc>
8142 </param>
8143 </method>
8144
8145 <method name="operationSupported">
8146 <desc>
8147 Returns whether the given acceleration operation is supported
8148 by the IFramebuffer implementation. If not, the display object
8149 will not attempt to call the corresponding IFramebuffer entry
8150 point. Even if an operation is indicated to supported, the
8151 IFramebuffer implementation always has the option to return non
8152 supported from the corresponding acceleration method in which
8153 case the operation will be performed by the display engine. This
8154 allows for reduced IFramebuffer implementation complexity where
8155 only common cases are handled.
8156 </desc>
8157 <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
8158 <param name="supported" type="boolean" dir="return"/>
8159 </method>
8160
8161 <method name="videoModeSupported">
8162 <desc>
8163 Returns whether the framebuffer implementation is willing to
8164 support a given video mode. In case it is not able to render
8165 the video mode (or for some reason not willing), it should
8166 return false. Usually this method is called when the guest
8167 asks the VMM device whether a given video mode is supported
8168 so the information returned is directly exposed to the guest.
8169 It is important that this method returns very quickly.
8170 </desc>
8171 <param name="width" type="unsigned long" dir="in"/>
8172 <param name="height" type="unsigned long" dir="in"/>
8173 <param name="bpp" type="unsigned long" dir="in"/>
8174 <param name="supported" type="boolean" dir="return"/>
8175 </method>
8176
8177 <method name="solidFill">
8178 <desc>
8179 Fills the specified rectangle on screen with a solid color.
8180 </desc>
8181 <param name="x" type="unsigned long" dir="in"/>
8182 <param name="y" type="unsigned long" dir="in"/>
8183 <param name="width" type="unsigned long" dir="in"/>
8184 <param name="height" type="unsigned long" dir="in"/>
8185 <param name="color" type="unsigned long" dir="in"/>
8186 <param name="handled" type="boolean" dir="return"/>
8187 </method>
8188
8189 <method name="copyScreenBits">
8190 <desc>
8191 Copies specified rectangle on the screen.
8192 </desc>
8193 <param name="xDst" type="unsigned long" dir="in"/>
8194 <param name="yDst" type="unsigned long" dir="in"/>
8195 <param name="xSrc" type="unsigned long" dir="in"/>
8196 <param name="ySrc" type="unsigned long" dir="in"/>
8197 <param name="width" type="unsigned long" dir="in"/>
8198 <param name="height" type="unsigned long" dir="in"/>
8199 <param name="handled" type="boolean" dir="return"/>
8200 </method>
8201
8202 <method name="getVisibleRegion">
8203 <desc>
8204 Returns the visible region of this framebuffer.
8205
8206 If the @a rectangles parameter is <tt>NULL</tt> then the value of the
8207 @a count parameter is ignored and the number of elements necessary to
8208 describe the current visible region is returned in @a countCopied.
8209
8210 If @a rectangles is not <tt>NULL</tt> but @a count is less
8211 than the required number of elements to store region data, the method
8212 will report a failure. If @a count is equal or greater than the
8213 required number of elements, then the actual number of elements copied
8214 to the provided array will be returned in @a countCopied.
8215
8216 <note>
8217 The address of the provided array must be in the process space of
8218 this IFramebuffer object.
8219 </note>
8220 </desc>
8221 <param name="rectangles" type="octet" mod="ptr" dir="in">
8222 <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
8223 </param>
8224 <param name="count" type="unsigned long" dir="in">
8225 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
8226 </param>
8227 <param name="countCopied" type="unsigned long" dir="return">
8228 <desc>Number of elements copied to the @a rectangles array.</desc>
8229 </param>
8230 </method>
8231
8232 <method name="setVisibleRegion">
8233 <desc>
8234 Suggests a new visible region to this framebuffer. This region
8235 represents the area of the VM display which is a union of regions of
8236 all top-level windows of the guest operating system running inside the
8237 VM (if the Guest Additions for this system support this
8238 functionality). This information may be used by the frontends to
8239 implement the seamless desktop integration feature.
8240
8241 <note>
8242 The address of the provided array must be in the process space of
8243 this IFramebuffer object.
8244 </note>
8245 <note>
8246 The IFramebuffer implementation must make a copy of the provided
8247 array of rectangles.
8248 </note>
8249 </desc>
8250 <param name="rectangles" type="octet" mod="ptr" dir="in">
8251 <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
8252 </param>
8253 <param name="count" type="unsigned long" dir="in">
8254 <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
8255 </param>
8256 </method>
8257
8258 </interface>
8259
8260 <interface
8261 name="IFramebufferOverlay" extends="IFrameBuffer"
8262 uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
8263 wsmap="suppress"
8264 >
8265 <desc>
8266 The IFramebufferOverlay interface represents an alpha blended overlay
8267 for displaying status icons above an IFramebuffer. It is always created
8268 not visible, so that it must be explicitly shown. It only covers a
8269 portion of the IFramebuffer, determined by its width, height and
8270 co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
8271 that order) format, and may be written to directly. Do re-read the
8272 width though, after setting it, as it may be adjusted (increased) to
8273 make it more suitable for the front end.
8274 </desc>
8275 <attribute name="x" type="unsigned long" readonly="yes">
8276 <desc>X position of the overlay, relative to the framebuffer.</desc>
8277 </attribute>
8278
8279 <attribute name="y" type="unsigned long" readonly="yes">
8280 <desc>Y position of the overlay, relative to the framebuffer.</desc>
8281 </attribute>
8282
8283 <attribute name="visible" type="boolean" readonly="no">
8284 <desc>
8285 Whether the overlay is currently visible.
8286 </desc>
8287 </attribute>
8288
8289 <attribute name="alpha" type="unsigned long" readonly="no">
8290 <desc>
8291 The global alpha value for the overlay. This may or may not be
8292 supported by a given front end.
8293 </desc>
8294 </attribute>
8295
8296 <method name="move">
8297 <desc>
8298 Changes the overlay's position relative to the IFramebuffer.
8299 </desc>
8300 <param name="x" type="unsigned long" dir="in"/>
8301 <param name="y" type="unsigned long" dir="in"/>
8302 </method>
8303
8304 </interface>
8305
8306 <interface
8307 name="IDisplay" extends="$unknown"
8308 uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
8309 wsmap="suppress"
8310 >
8311 <desc>
8312 The IDisplay interface represents the virtual machine's display.
8313
8314 The object implementing this interface is contained in each
8315 <link to="IConsole::display"/> attribute and represents the visual
8316 output of the virtual machine.
8317
8318 The virtual display supports pluggable output targets represented by the
8319 IFramebuffer interface. Examples of the output target are a window on
8320 the host computer or an RDP sessoin's display on a remote computer.
8321 </desc>
8322 <attribute name="width" type="unsigned long" readonly="yes">
8323 <desc>Current display width.</desc>
8324 </attribute>
8325
8326 <attribute name="height" type="unsigned long" readonly="yes">
8327 <desc>Current display height.</desc>
8328 </attribute>
8329
8330 <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
8331 <desc>
8332 Current guest display color depth. Note that this may differ
8333 from <link to="IFramebuffer::bitsPerPixel"/>.
8334 </desc>
8335 </attribute>
8336
8337 <method name="setupInternalFramebuffer">
8338 <desc>
8339 Prepares an internally managed framebuffer.
8340 </desc>
8341 <param name="depth" type="unsigned long" dir="in"/>
8342 </method>
8343
8344 <method name="lockFramebuffer">
8345 <desc>
8346 Requests access to the internal framebuffer.
8347 </desc>
8348 <param name="address" type="octet" mod="ptr" dir="return"/>
8349 </method>
8350
8351 <method name="unlockFramebuffer">
8352 <desc>
8353 Releases access to the internal framebuffer.
8354 </desc>
8355 </method>
8356
8357 <method name="registerExternalFramebuffer">
8358 <desc>
8359 Registers an external framebuffer.
8360 </desc>
8361 <param name="framebuffer" type="IFramebuffer" dir="in"/>
8362 </method>
8363
8364 <method name="setFramebuffer">
8365 <desc>
8366 Sets the framebuffer for given screen.
8367 </desc>
8368 <param name="screenId" type="unsigned long" dir="in"/>
8369 <param name="framebuffer" type="IFramebuffer" dir="in"/>
8370 </method>
8371
8372 <method name="getFramebuffer">
8373 <desc>
8374 Queries the framebuffer for given screen.
8375 </desc>
8376 <param name="screenId" type="unsigned long" dir="in"/>
8377 <param name="framebuffer" type="IFramebuffer" dir="out"/>
8378 <param name="xOrigin" type="long" dir="out"/>
8379 <param name="yOrigin" type="long" dir="out"/>
8380 </method>
8381
8382 <method name="setVideoModeHint">
8383 <desc>
8384 Asks VirtualBox to request the given video mode from
8385 the guest. This is just a hint and it cannot be guaranteed
8386 that the requested resolution will be used. Guest Additions
8387 are required for the request to be seen by guests. The caller
8388 should issue the request and wait for a resolution change and
8389 after a timeout retry.
8390
8391 Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
8392 parameters means that the corresponding values should be taken from the
8393 current video mode (i.e. left unchanged).
8394
8395 If the guest OS supports multi-monitor configuration then the @a display
8396 parameter specifies the number of the guest display to send the hint to:
8397 <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
8398 so on. If the multi-monitor configuration is not supported, @a display
8399 must be <tt>0</tt>.
8400
8401 </desc>
8402 <param name="width" type="unsigned long" dir="in"/>
8403 <param name="height" type="unsigned long" dir="in"/>
8404 <param name="bitsPerPixel" type="unsigned long" dir="in"/>
8405 <param name="display" type="unsigned long" dir="in"/>
8406 </method>
8407
8408 <method name="setSeamlessMode">
8409 <desc>
8410 Enables or disables seamless guest display rendering (seamless desktop
8411 integration) mode.
8412 <note>
8413 Calling this method has no effect if <link
8414 to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
8415 </note>
8416 </desc>
8417 <param name="enabled" type="boolean" dir="in"/>
8418 </method>
8419
8420 <method name="takeScreenShot">
8421 <desc>
8422 Takes a screen shot of the requested size and copies it to the
8423 32-bpp buffer allocated by the caller.
8424 </desc>
8425 <param name="address" type="octet" mod="ptr" dir="in"/>
8426 <param name="width" type="unsigned long" dir="in"/>
8427 <param name="height" type="unsigned long" dir="in"/>
8428 </method>
8429
8430 <method name="drawToScreen">
8431 <desc>
8432 Draws a 32-bpp image of the specified size from the given buffer
8433 to the given point on the VM display.
8434 </desc>
8435 <param name="address" type="octet" mod="ptr" dir="in"/>
8436 <param name="x" type="unsigned long" dir="in"/>
8437 <param name="y" type="unsigned long" dir="in"/>
8438 <param name="width" type="unsigned long" dir="in"/>
8439 <param name="height" type="unsigned long" dir="in"/>
8440 </method>
8441
8442 <method name="invalidateAndUpdate">
8443 <desc>
8444 Does a full invalidation of the VM display and instructs the VM
8445 to update it.
8446 </desc>
8447 </method>
8448
8449 <method name="resizeCompleted">
8450 <desc>
8451 Signals that a framebuffer has completed the resize operation.
8452 </desc>
8453 <param name="screenId" type="unsigned long" dir="in"/>
8454 </method>
8455
8456 <method name="updateCompleted">
8457 <desc>
8458 Signals that a framebuffer has completed the update operation.
8459 </desc>
8460 </method>
8461
8462 </interface>
8463
8464 <!--
8465 // INetworkAdapter
8466 /////////////////////////////////////////////////////////////////////////
8467 -->
8468
8469 <enum
8470 name="NetworkAttachmentType"
8471 uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
8472 >
8473 <desc>
8474 Network attachment type.
8475 </desc>
8476
8477 <const name="Null" value="0">
8478 <desc><tt>null</tt> value. Also means "not attached".</desc>
8479 </const>
8480 <const name="NAT" value="1"/>
8481 <const name="HostInterface" value="2"/>
8482 <const name="Internal" value="3"/>
8483 </enum>
8484
8485 <enum
8486 name="NetworkAdapterType"
8487 uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
8488 >
8489 <desc>
8490 Network adapter type.
8491 </desc>
8492
8493 <const name="Null" value="0">
8494 <desc><tt>null</tt> value. Never used by the API.</desc>
8495 </const>
8496 <const name="Am79C970A" value="1"/>
8497 <const name="Am79C973" value="2"/>
8498 <const name="I82540EM" value="3"/>
8499 <const name="I82543GC" value="4"/>
8500 </enum>
8501
8502 <interface
8503 name="INetworkAdapter" extends="$unknown"
8504 uuid="a876d9b1-68d9-43b1-9c68-ddea0a473663"
8505 wsmap="managed"
8506 >
8507 <attribute name="adapterType" type="NetworkAdapterType">
8508 <desc>
8509 Type of the virtual network adapter. Depending on this value,
8510 VirtualBox will provide a different virtual network hardware
8511 to the guest.
8512 </desc>
8513 </attribute>
8514
8515 <attribute name="slot" type="unsigned long" readonly="yes">
8516 <desc>
8517 Slot number this adapter is plugged into. Corresponds to
8518 the value you pass to <link to="IMachine::getNetworkAdapter"/>
8519 to obtain this instance.
8520 </desc>
8521 </attribute>
8522
8523 <attribute name="enabled" type="boolean">
8524 <desc>
8525 Flag whether the network adapter is present in the
8526 guest system. If disabled, the virtual guest hardware will
8527 not contain this network adapter. Can only be changed when
8528 the VM is not running.
8529 </desc>
8530 </attribute>
8531
8532 <attribute name="MACAddress" type="wstring">
8533 <desc>
8534 Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
8535 it to NULL, VirtualBox will generate a unique MAC address.
8536 </desc>
8537 </attribute>
8538
8539 <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
8540
8541 <attribute name="hostInterface" type="wstring">
8542 <desc>
8543 Name of the Host Network Interface that is currently in use. NULL will be returned
8544 if no device has been allocated. On Linux, setting this refers to a permanent TAP
8545 device. However, a file descriptor has precedence over the interface name on Linux.
8546 Note that when VBox allocates a TAP device, this property will not be set, i.e. the
8547 interface name would have to be determined using the file descriptor and /proc/self/fd.
8548 </desc>
8549 </attribute>
8550
8551<if target="xpidl">
8552 <attribute name="TAPFileDescriptor" type="long">
8553 <desc>
8554 File descriptor of the TAP device. It can either be setup by the caller
8555 which has to supply an existing valid file handle allocated in the parent
8556 process of the VM process or allocated by VirtualBox. The value is -1 if it
8557 has not been defined. This property is non persistent, i.e. it will not be
8558 stored in the VM's configuration data and thus has to be set at each startup.
8559 </desc>
8560 </attribute>
8561 <attribute name="TAPSetupApplication" type="wstring">
8562 <desc>
8563 Application to start to configure the TAP device.
8564 It is being passed two parameters, 1) the file handle (as ascii),
8565 2) the TAP device name if it is available.
8566 </desc>
8567 </attribute>
8568 <attribute name="TAPTerminateApplication" type="wstring">
8569 <desc>
8570 Application to start before closing a TAP device.
8571 It is being passed two parameters, 1) the file handle (as ascii),
8572 2) the TAP device name if it is available.
8573 </desc>
8574 </attribute>
8575</if>
8576
8577 <attribute name="internalNetwork" type="wstring">
8578 <desc>
8579 Name of the internal network the VM is attached to.
8580 </desc>
8581 </attribute>
8582
8583 <attribute name="NATNetwork" type="wstring">
8584 <desc>
8585 Name of the NAT network the VM is attached to.
8586 </desc>
8587 </attribute>
8588
8589 <attribute name="cableConnected" type="boolean">
8590 <desc>
8591 Flag whether the adapter reports the cable as connected or not.
8592 It can be used to report offline situations to a VM.
8593 </desc>
8594 </attribute>
8595
8596 <attribute name="lineSpeed" type="unsigned long">
8597 <desc>
8598 Line speed reported by custom drivers, in units of 1 kbps.
8599 </desc>
8600 </attribute>
8601
8602 <attribute name="traceEnabled" type="boolean">
8603 <desc>
8604 Flag whether network traffic from/to the network card should be traced.
8605 Can only be toggled when the VM is turned off.
8606 </desc>
8607 </attribute>
8608
8609 <attribute name="traceFile" type="wstring">
8610 <desc>
8611 Filename where a network trace will be stored. If not set, VBox-pid.pcap
8612 will be used.
8613 </desc>
8614 </attribute>
8615
8616 <method name="attachToNAT">
8617 <desc>
8618 Attach the network adapter to the Network Address Translation (NAT) interface.
8619 </desc>
8620 </method>
8621
8622 <method name="attachToHostInterface">
8623 <desc>
8624 Attach the network adapter to a host interface. On Linux, the TAP
8625 setup application will be executed if configured and unless a device
8626 name and/or file descriptor has been set, a new TAP interface will be
8627 created.
8628 </desc>
8629 </method>
8630
8631 <method name="attachToInternalNetwork">
8632 <desc>
8633 Attach the network adapter to an internal network.
8634 </desc>
8635 </method>
8636
8637 <method name="detach">
8638 <desc>
8639 Detach the network adapter
8640 </desc>
8641 </method>
8642 </interface>
8643
8644
8645 <!--
8646 // ISerialPort
8647 /////////////////////////////////////////////////////////////////////////
8648 -->
8649
8650 <enum
8651 name="PortMode"
8652 uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
8653 >
8654 <desc>
8655 The PortMode enumeration represents possible communicaton modes for
8656 the virtual serial port device.
8657 </desc>
8658
8659 <const name="Disconnected" value="0">
8660 <desc>Virtual device is not attached to any real host device.</desc>
8661 </const>
8662 <const name="HostPipe" value="1">
8663 <desc>Virtual device is attached to a host pipe.</desc>
8664 </const>
8665 <const name="HostDevice" value="2">
8666 <desc>Virtual device is attached to a host device.</desc>
8667 </const>
8668 </enum>
8669
8670 <interface
8671 name="ISerialPort" extends="$unknown"
8672 uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
8673 wsmap="managed"
8674 >
8675
8676 <desc>
8677 The ISerialPort interface represents the virtual serial port device.
8678
8679 The virtual serial port device acts like an ordinary serial port
8680 inside the virtual machine. This device communicates to the real
8681 serial port hardware in one of two modes: host pipe or host device.
8682
8683 In host pipe mode, the #path attribute specifies the path to the pipe on
8684 the host computer that represents a serial port. The #server attribute
8685 determines if this pipe is created by the virtual machine process at
8686 machine startup or it must already exist before starting machine
8687 execution.
8688
8689 In host device mode, the #path attribute specifies the name of the
8690 serial port device on the host computer.
8691
8692 There is also a third communication mode: the disconnected mode. In this
8693 mode, the guest OS running inside the virtual machine will be able to
8694 detect the serial port, but all port write operations will be discarded
8695 and all port read operations will return no data.
8696
8697 <see>IMachine::getSerialPort</see>
8698 </desc>
8699
8700 <attribute name="slot" type="unsigned long" readonly="yes">
8701 <desc>
8702 Slot number this serial port is plugged into. Corresponds to
8703 the value you pass to <link to="IMachine::getSerialPort"/>
8704 to obtain this instance.
8705 </desc>
8706 </attribute>
8707
8708 <attribute name="enabled" type="boolean">
8709 <desc>
8710 Flag whether the serial port is enabled. If disabled,
8711 the serial port will not be reported to the guest OS.
8712 </desc>
8713 </attribute>
8714
8715 <attribute name="IOBase" type="unsigned long">
8716 <desc>Base I/O address of the serial port.</desc>
8717 </attribute>
8718
8719 <attribute name="IRQ" type="unsigned long">
8720 <desc>IRQ number of the serial port.</desc>
8721 </attribute>
8722
8723 <attribute name="hostMode" type="PortMode">
8724 <desc>How is this port connected to the host.</desc>
8725 </attribute>
8726
8727 <attribute name="server" type="boolean">
8728 <desc>
8729 Flag whether this serial port acts as a server (creates a new pipe on
8730 the host) or as a client (uses the existing pipe). This attribute is
8731 used only when <link to="#hostMode"/> is PortMode::HostPipe.
8732 </desc>
8733 </attribute>
8734
8735 <attribute name="path" type="wstring">
8736 <desc>
8737 Path to the serial port's pipe on the host when <link to="#hostMode"/> is
8738 PortMode::HostPipe, or the host serial device name when
8739 <link to="#hostMode"/> is PortMode::HostDevice. In either of the above
8740 cases, setting a @c null or an empty string as the attribute's value
8741 will result into an error. Otherwise, the value of this property is
8742 ignored.
8743 </desc>
8744 </attribute>
8745
8746 </interface>
8747
8748 <!--
8749 // IParallelPort
8750 /////////////////////////////////////////////////////////////////////////
8751 -->
8752
8753 <interface
8754 name="IParallelPort" extends="$unknown"
8755 uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
8756 wsmap="managed"
8757 >
8758
8759 <desc>
8760 The IParallelPort interface represents the virtual parallel port device.
8761
8762 The virtual parallel port device acts like an ordinary parallel port
8763 inside the virtual machine. This device communicates to the real
8764 parallel port hardware using the name of the parallel device on the host
8765 computer specified in the #path attribute.
8766
8767 Each virtual parallel port device is assigned a base I/O address and an
8768 IRQ number that will be reported to the guest operating system and used
8769 to operate the given parallel port from within the virtual machine.
8770
8771 <see>IMachine::getParallelPort</see>
8772 </desc>
8773
8774 <attribute name="slot" type="unsigned long" readonly="yes">
8775 <desc>
8776 Slot number this parallel port is plugged into. Corresponds to
8777 the value you pass to <link to="IMachine::getParallelPort"/>
8778 to obtain this instance.
8779 </desc>
8780 </attribute>
8781
8782 <attribute name="enabled" type="boolean">
8783 <desc>
8784 Flag whether the parallel port is enabled. If disabled,
8785 the parallel port will not be reported to the guest OS.
8786 </desc>
8787 </attribute>
8788
8789 <attribute name="IOBase" type="unsigned long">
8790 <desc>Base I/O address of the parallel port.</desc>
8791 </attribute>
8792
8793 <attribute name="IRQ" type="unsigned long">
8794 <desc>IRQ number of the parallel port.</desc>
8795 </attribute>
8796
8797 <attribute name="path" type="wstring">
8798 <desc>
8799 Host parallel device name. If this parallel port is enabled, setting a
8800 @c null or an empty string as this attribute's value will result into
8801 an error.
8802 </desc>
8803 </attribute>
8804
8805 </interface>
8806
8807
8808 <!--
8809 // IMachineDebugger
8810 /////////////////////////////////////////////////////////////////////////
8811 -->
8812
8813 <interface
8814 name="IMachineDebugger" extends="$unknown"
8815 uuid="54ebce96-fa7d-4a4d-bc81-a7db41c29637"
8816 wsmap="suppress"
8817 >
8818 <method name="resetStats">
8819 <desc>
8820 Reset VM statistics.
8821 </desc>
8822 <param name="pattern" type="wstring" dir="in">
8823 <desc>The selection pattern. A bit similar to filename globbing.</desc>
8824 </param>
8825 </method>
8826
8827 <method name="dumpStats">
8828 <desc>
8829 Dumps VM statistics.
8830 </desc>
8831 <param name="pattern" type="wstring" dir="in">
8832 <desc>The selection pattern. A bit similar to filename globbing.</desc>
8833 </param>
8834 </method>
8835
8836 <method name="getStats">
8837 <desc>
8838 Get the VM statistics in a XMLish format.
8839 </desc>
8840 <param name="pattern" type="wstring" dir="in">
8841 <desc>The selection pattern. A bit similar to filename globbing.</desc>
8842 </param>
8843 <param name="withDescriptions" type="boolean" dir="in">
8844 <desc>Whether to include the descriptions.</desc>
8845 </param>
8846 <param name="stats" type="wstring" dir="out">
8847 <desc>The XML document containing the statistics.</desc>
8848 </param>
8849 </method>
8850
8851 <attribute name="singlestep" type="boolean">
8852 <desc>Switch for enabling singlestepping.</desc>
8853 </attribute>
8854
8855 <attribute name="recompileUser" type="boolean">
8856 <desc>Switch for forcing code recompilation for user mode code.</desc>
8857 </attribute>
8858
8859 <attribute name="recompileSupervisor" type="boolean">
8860 <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
8861 </attribute>
8862
8863 <attribute name="PATMEnabled" type="boolean">
8864 <desc>Switch for enabling and disabling the PATM component.</desc>
8865 </attribute>
8866
8867 <attribute name="CSAMEnabled" type="boolean">
8868 <desc>Switch for enabling and disabling the CSAM component.</desc>
8869 </attribute>
8870
8871 <attribute name="logEnabled" type="boolean">
8872 <desc>Switch for enabling and disabling logging.</desc>
8873 </attribute>
8874
8875 <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
8876 <desc>
8877 Flag indicating whether the VM is currently making use of CPU hardware
8878 virtualization extensions.
8879 </desc>
8880 </attribute>
8881
8882 <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
8883 <desc>
8884 Flag indicating whether the VM is currently making use of the nested paging
8885 CPU hardware virtualization extension.
8886 </desc>
8887 </attribute>
8888
8889 <attribute name="PAEEnabled" type="boolean" readonly="yes">
8890 <desc>
8891 Flag indicating whether the VM is currently making use of the Physical
8892 Address Extension CPU feature.
8893 </desc>
8894 </attribute>
8895
8896 <attribute name="virtualTimeRate" type="unsigned long">
8897 <desc>
8898 The rate at which the virtual time runs expressed as a percentage.
8899 The accepted range is 2% to 20000%.
8900 </desc>
8901 </attribute>
8902
8903 <!-- @todo method for setting log flags, groups and destination! -->
8904
8905 <attribute name="VM" type="unsigned long long" readonly="yes">
8906 <desc>
8907 Gets the VM handle. This is only for internal use while
8908 we carve the details of this interface.
8909 </desc>
8910 </attribute>
8911
8912 </interface>
8913
8914 <!--
8915 // IUSBController
8916 /////////////////////////////////////////////////////////////////////////
8917 -->
8918
8919 <interface
8920 name="IUSBController" extends="$unknown"
8921 uuid="f4c2d3dc-f109-4da7-93b1-ec28973ac89f"
8922 wsmap="managed"
8923 >
8924 <attribute name="enabled" type="boolean">
8925 <desc>
8926 Flag whether the USB controller is present in the
8927 guest system. If disabled, the virtual guest hardware will
8928 not contain any USB controller. Can only be changed when
8929 the VM is powered off.
8930 </desc>
8931 </attribute>
8932
8933 <attribute name="enabledEhci" type="boolean">
8934 <desc>
8935 Flag whether the USB EHCI controller is present in the
8936 guest system. If disabled, the virtual guest hardware will
8937 not contain a USB EHCI controller. Can only be changed when
8938 the VM is powered off.
8939 </desc>
8940 </attribute>
8941
8942 <attribute name="USBStandard" type="unsigned short" readonly="yes">
8943 <desc>
8944 USB standard version which the controller implements.
8945 This is a BCD which means that the major version is in the
8946 high byte and minor version is in the low byte.
8947 </desc>
8948 </attribute>
8949
8950 <attribute name="deviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
8951 <desc>
8952 List of USB device filters associated with the machine.
8953
8954 If the machine is currently running, these filters are activated
8955 every time a new (supported) USB device is attached to the host
8956 computer that was not ignored by global filters
8957 (<link to="IHost::USBDeviceFilters"/>).
8958
8959 These filters are also activated when the machine is powered up.
8960 They are run against a list of all currently available USB
8961 devices (in states
8962 <link to="USBDeviceState::Available">Available</link>,
8963 <link to="USBDeviceState::Busy">Busy</link>,
8964 <link to="USBDeviceState::Held">Held</link>) that were not previously
8965 ignored by global filters.
8966
8967 If at least one filter matches the USB device in question, this
8968 device is automatically captured (attached to) the virtual USB
8969 controller of this machine.
8970
8971 <see>IUSBDeviceFilter, ::IUSBController</see>
8972 </desc>
8973 </attribute>
8974
8975 <method name="createDeviceFilter">
8976 <desc>
8977 Creates a new USB device filter. All attributes except
8978 the filter name are set to <tt>null</tt> (any match),
8979 <i>active</i> is <tt>false</tt> (the filter is not active).
8980
8981 The created filter can then be added to the list of filters using
8982 <link to="#insertDeviceFilter()"/>.
8983
8984 <see>#deviceFilters</see>
8985 </desc>
8986 <param name="name" type="wstring" dir="in">
8987 <desc>
8988 Filter name. See <link to="IUSBDeviceFilter::name"/>
8989 for more info.
8990 </desc>
8991 </param>
8992 <param name="filter" type="IUSBDeviceFilter" dir="return">
8993 <desc>Created filter object.</desc>
8994 </param>
8995 </method>
8996
8997 <method name="insertDeviceFilter">
8998 <desc>
8999 Inserts the given USB device to the specified position
9000 in the list of filters.
9001
9002 Positions are numbered starting from <tt>0</tt>. If the specified
9003 position is equal to or greater than the number of elements in
9004 the list, the filter is added to the end of the collection.
9005
9006 <note>
9007 Duplicates are not allowed, so an attempt to inster a
9008 filter that is already in the collection, will return an
9009 error.
9010 </note>
9011
9012 <see>#deviceFilters</see>
9013 </desc>
9014 <param name="position" type="unsigned long" dir="in">
9015 <desc>Position to insert the filter to.</desc>
9016 </param>
9017 <param name="filter" type="IUSBDeviceFilter" dir="in">
9018 <desc>USB device filter to insert.</desc>
9019 </param>
9020 </method>
9021
9022 <method name="removeDeviceFilter">
9023 <desc>
9024 Removes a USB device filter from the specified position in the
9025 list of filters.
9026
9027 Positions are numbered starting from <tt>0</tt>. Specifying a
9028 position equal to or greater than the number of elements in
9029 the list will produce an error.
9030
9031 <see>#deviceFilters</see>
9032 </desc>
9033 <param name="position" type="unsigned long" dir="in">
9034 <desc>Position to remove the filter from.</desc>
9035 </param>
9036 <param name="filter" type="IUSBDeviceFilter" dir="return">
9037 <desc>Removed USB device filter.</desc>
9038 </param>
9039 </method>
9040
9041 </interface>
9042
9043
9044 <!--
9045 // IUSBDevice
9046 /////////////////////////////////////////////////////////////////////////
9047 -->
9048
9049 <enumerator
9050 name="IUSBDeviceEnumerator" type="IUSBDevice"
9051 uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
9052 />
9053
9054 <collection
9055 name="IUSBDeviceCollection" type="IUSBDevice"
9056 enumerator="IUSBDeviceEnumerator"
9057 uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
9058 readonly="yes"
9059 >
9060 <method name="findById">
9061 <desc>
9062 Searches this collection for a USB device with the given UUID.
9063 <note>
9064 The method returns an error if the given UUID does not
9065 correspond to any USB device in the collection.
9066 </note>
9067 <see>IUSBDevice::id</see>
9068 </desc>
9069 <param name="id" type="uuid" dir="in">
9070 <desc>UUID of the USB device to search for.</desc>
9071 </param>
9072 <param name="device" type="IUSBDevice" dir="return">
9073 <desc>Found USB device object.</desc>
9074 </param>
9075 </method>
9076
9077 <method name="findByAddress">
9078 <desc>
9079 Searches this collection for a USB device with the given
9080 host address.
9081 <note>
9082 The method returns an error if the given address does not
9083 correspond to any USB device in the collection.
9084 </note>
9085 <see>IUSBDevice::address</see>
9086 </desc>
9087 <param name="name" type="wstring" dir="in">
9088 <desc>
9089 Address of the USB device (as assigned by the host) to
9090 search for.
9091 </desc>
9092 </param>
9093 <param name="device" type="IUSBDevice" dir="return">
9094 <desc>Found USB device object.</desc>
9095 </param>
9096 </method>
9097
9098 </collection>
9099
9100 <interface
9101 name="IUSBDevice" extends="$unknown"
9102 uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
9103 wsmap="managed"
9104 >
9105 <desc>
9106 The IUSBDevice interface represents a virtual USB device attached to the
9107 virtual machine.
9108
9109 A collection of objects implementing this interface is stored in the
9110 <link to="IConsole::USBDevices"/> attribute which lists all USB devices
9111 attached to a running virtual machine's USB controller.
9112 </desc>
9113
9114 <attribute name="id" type="uuid" readonly="yes">
9115 <desc>
9116 Unique USB device ID. This ID is built from #vendorId,
9117 #productId, #revision and #serialNumber.
9118 </desc>
9119 </attribute>
9120
9121 <attribute name="vendorId" type="unsigned short" readonly="yes">
9122 <desc>Vendor ID.</desc>
9123 </attribute>
9124
9125 <attribute name="productId" type="unsigned short" readonly="yes">
9126 <desc>Product ID.</desc>
9127 </attribute>
9128
9129 <attribute name="revision" type="unsigned short" readonly="yes">
9130 <desc>
9131 Product revision number. This is a packed BCD represented as
9132 unsigned short. The high byte is the integer part and the low
9133 byte is the decimal.
9134 </desc>
9135 </attribute>
9136
9137 <attribute name="manufacturer" type="wstring" readonly="yes">
9138 <desc>Manufacturer string.</desc>
9139 </attribute>
9140
9141 <attribute name="product" type="wstring" readonly="yes">
9142 <desc>Product string.</desc>
9143 </attribute>
9144
9145 <attribute name="serialNumber" type="wstring" readonly="yes">
9146 <desc>Serial number string.</desc>
9147 </attribute>
9148
9149 <attribute name="address" type="wstring" readonly="yes">
9150 <desc>Host specific address of the device.</desc>
9151 </attribute>
9152
9153 <attribute name="port" type="unsigned short" readonly="yes">
9154 <desc>
9155 Host USB port number the device is physically
9156 coonected to.
9157 </desc>
9158 </attribute>
9159
9160 <attribute name="version" type="unsigned short" readonly="yes">
9161 <desc>
9162 The major USB version of the device - 1 or 2.
9163 </desc>
9164 </attribute>
9165
9166 <attribute name="portVersion" type="unsigned short" readonly="yes">
9167 <desc>
9168 The major USB version of the host USB port the device is
9169 physically coonected to - 1 or 2. For devices not connected to
9170 anything this will have the same value as the version attribute.
9171 </desc>
9172 </attribute>
9173
9174 <attribute name="remote" type="boolean" readonly="yes">
9175 <desc>
9176 Whether the device is physically connected to a remote VRDP
9177 client or to a local host machine.
9178 </desc>
9179 </attribute>
9180
9181 </interface>
9182
9183
9184 <!--
9185 // IUSBDeviceFilter
9186 /////////////////////////////////////////////////////////////////////////
9187 -->
9188
9189 <enumerator
9190 name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
9191 uuid="d5109c61-93e7-4726-926b-0dee1020da56"
9192 />
9193
9194 <collection
9195 name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
9196 enumerator="IUSBDeviceFilterEnumerator"
9197 uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
9198 readonly="yes"
9199 />
9200
9201 <interface
9202 name="IUSBDeviceFilter" extends="$unknown"
9203 uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
9204 wsmap="managed"
9205 >
9206 <desc>
9207 The IUSBDeviceFilter interface represents an USB device filter used
9208 to perform actions on a group of USB devices.
9209
9210 This type of filters is used by running virtual machines to
9211 automatically capture selected USB devices once they are physically
9212 attached to the host computer.
9213
9214 A USB device is matched to the given device filter if and only if all
9215 attributes of the device match the corresponding attributes of the
9216 filter (that is, attributes are joined together using the logical AND
9217 operation). On the other hand, all together, filters in the list of
9218 filters carry the semantics of the logical OR operation. So if it is
9219 desirable to create a match like "this vendor id OR this product id",
9220 one needs to create two filters and specify "any match" (see below)
9221 for unused attributes.
9222
9223 All filter attributes used for matching are strings. Each string
9224 is an expression representing a set of values of the corresponding
9225 device attribute, that will match the given filter. Currently, the
9226 following filtering expressions are supported:
9227
9228 <ul>
9229 <li><i>Interval filters</i>. Used to specify valid intervals for
9230 integer device attributes (Vendor ID, Product ID and Revision).
9231 The format of the string is:
9232
9233 <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
9234
9235 where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
9236 (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
9237 or decimal (otherwise) form, so that <tt>m &lt; n</tt>. If <tt>m</tt>
9238 is ommitted before a dash (<tt>-</tt>), the minimum possible integer
9239 is assumed; if <tt>n</tt> is ommitted after a dash, the maximum
9240 possible integer is assummed.
9241 </li>
9242 <li><i>Boolean filters</i>. Used to specify acceptable values for
9243 boolean device attributes. The format of the string is:
9244
9245 <tt>true|false|yes|no|0|1</tt>
9246
9247 </li>
9248 <li><i>Exact match</i>. Used to specify a single value for the given
9249 device attribute. Any string that does't start with <tt>int:</tt>
9250 represents the exact match. String device attributes are compared to
9251 this string including case of symbols. Integer attributes are first
9252 converted to a string (see individual filter attributes) and then
9253 compared ignoring case.
9254
9255 </li>
9256 <li><i>Any match</i>. Any value of the corresponding device attribute
9257 will match the given filter. An empty or <tt>null</tt> string is
9258 used to construct this type of filtering expressions.
9259
9260 </li>
9261 </ul>
9262
9263 <note>
9264 On the Windows host platform, interval filters are not currently
9265 available. Also all string filter attributes
9266 (<link to="#manufacturer"/>, <link to="#product"/>,
9267 <link to="#serialNumber"/>) are ignored, so they behave as
9268 <i>any match</i> no matter what string expression is specified.
9269 </note>
9270
9271 <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
9272 </desc>
9273
9274 <attribute name="name" type="wstring">
9275 <desc>
9276 Visible name for this filter.
9277 This name is used to visually distungish one filter from another,
9278 so it can neither be <tt>null</tt> nor an empty string.
9279 </desc>
9280 </attribute>
9281
9282 <attribute name="active" type="boolean">
9283 <desc>Whether this filter active or has been temporarily disabled.</desc>
9284 </attribute>
9285
9286 <attribute name="vendorId" type="wstring">
9287 <desc>
9288 <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
9289 The string representation for the <i>exact matching</i>
9290 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
9291 (including leading zeroes).
9292 </desc>
9293 </attribute>
9294
9295 <attribute name="productId" type="wstring">
9296 <desc>
9297 <link to="IUSBDevice::productId">Product ID</link> filter.
9298 The string representation for the <i>exact matching</i>
9299 has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
9300 (including leading zeroes).
9301 </desc>
9302 </attribute>
9303
9304 <attribute name="revision" type="wstring">
9305 <desc>
9306 <link to="IUSBDevice::productId">Product revision number</link>
9307 filter. The string representation for the <i>exact matching</i>
9308 has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
9309 of the integer part of the revision, and <tt>F</tt> is the
9310 decimal digit of its fractional part (including leading and
9311 trailing zeroes).
9312 Note that for interval filters, it's best to use the hexadecimal
9313 form, because the revision is stored as a 16 bit packed BCD value;
9314 so the expression <tt>int:0x0100-0x0199</tt> will match any
9315 revision from <tt>1.0</tt> to <tt>1.99</tt>.
9316 </desc>
9317 </attribute>
9318
9319 <attribute name="manufacturer" type="wstring">
9320 <desc>
9321 <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
9322 </desc>
9323 </attribute>
9324
9325 <attribute name="product" type="wstring">
9326 <desc>
9327 <link to="IUSBDevice::product">Product</link> filter.
9328 </desc>
9329 </attribute>
9330
9331 <attribute name="serialNumber" type="wstring">
9332 <desc>
9333 <link to="IUSBDevice::serialNumber">Serial number</link> filter.
9334 </desc>
9335 </attribute>
9336
9337 <attribute name="port" type="wstring">
9338 <desc>
9339 <link to="IUSBDevice::port">Host USB port</link> filter.
9340 </desc>
9341 </attribute>
9342
9343 <attribute name="remote" type="wstring">
9344 <desc>
9345 <link to="IUSBDevice::remote">Remote state</link> filter.
9346 <note>
9347 This filter makes sense only for machine USB filters,
9348 i.e. it is ignored by IHostUSBDeviceFilter objects.
9349 </note>
9350 </desc>
9351 </attribute>
9352
9353 <attribute name="maskedInterfaces" type="unsigned long">
9354 <desc>
9355 This is an advanced option for hiding one or more USB interfaces
9356 from the guest. The value is a bitmask where the bits that are set
9357 means the corresponding USB interface should be hidden, masked off
9358 if you like.
9359 This feature only works on Linux hosts.
9360 </desc>
9361 </attribute>
9362
9363 </interface>
9364
9365
9366 <!--
9367 // IHostUSBDevice
9368 /////////////////////////////////////////////////////////////////////////
9369 -->
9370
9371 <enum
9372 name="USBDeviceState"
9373 uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
9374 >
9375 <desc>
9376 USB device state. This enumeration represents all possible states
9377 of the USB device physically attached to the host computer regarding
9378 its state on the host computer and availability to guest computers
9379 (all currently running virtual machines).
9380
9381 Once a supported USB device is attached to the host, global USB
9382 filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
9383 either ignore the device, or put ot to #Held state, or do nothing. Unless
9384 the device is ignored by global filters, filters of all currently running
9385 guests (<link to="IUSBController::deviceFilters"/>) are activated that can
9386 put it to #Captured state.
9387
9388 If the device was ignored by global filters, or didn't match
9389 any filters at all (including guest ones), it is handled by the host
9390 in a normal way. In this case, the device state is determined by
9391 the host and can be one of #Unavailable, #Busy or #Available, depending on
9392 the current device usage.
9393
9394 Besides auto-capturing based on filters, the device can be manually
9395 captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
9396 state is #Busy, #Available or #Held.
9397
9398 <note>
9399 Due to differences in USB stack implementations in Linux and Win32,
9400 states #Busy and #Available are applicable only to the Linux version of
9401 the product. This also means that (<link
9402 to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if
9403 the device state is #Held.
9404 </note>
9405
9406 <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
9407 </desc>
9408
9409 <const name="NotSupported" value="0">
9410 <desc>
9411 Not supported by the VirtualBox server, not available to guests.
9412 </desc>
9413 </const>
9414 <const name="Unavailable" value="1">
9415 <desc>
9416 Being used by the host computer exclusively,
9417 not available to guests.
9418 </desc>
9419 </const>
9420 <const name="Busy" value="2">
9421 <desc>
9422 Being used by the host computer, potentially available to guests.
9423 </desc>
9424 </const>
9425 <const name="Available" value="3">
9426 <desc>
9427 Not used by the host computer, available to guests.
9428 The host computer can also start using the device at any time.
9429 </desc>
9430 </const>
9431 <const name="Held" value="4">
9432 <desc>
9433 Held by the VirtualBox server (ignored by the host computer),
9434 available to guests.
9435 </desc>
9436 </const>
9437 <const name="Captured" value="5">
9438 <desc>
9439 Captured by one of the guest computers, not available
9440 to anybody else.
9441 </desc>
9442 </const>
9443 </enum>
9444
9445 <enumerator
9446 name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
9447 uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
9448 />
9449
9450 <collection
9451 name="IHostUSBDeviceCollection" type="IHostUSBDevice"
9452 enumerator="IHostUSBDeviceEnumerator"
9453 uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
9454 readonly="yes"
9455 >
9456 <method name="findById">
9457 <desc>
9458 Searches this collection for a USB device with the given UUID.
9459 <note>
9460 The method returns an error if the given UUID does not
9461 correspond to any USB device in the collection.
9462 </note>
9463 <see>IHostUSBDevice::id</see>
9464 </desc>
9465 <param name="id" type="uuid" dir="in">
9466 <desc>UUID of the USB device to search for.</desc>
9467 </param>
9468 <param name="device" type="IHostUSBDevice" dir="return">
9469 <desc>Found USB device object.</desc>
9470 </param>
9471 </method>
9472
9473 <method name="findByAddress">
9474 <desc>
9475 Searches this collection for a USB device with the given
9476 host address.
9477 <note>
9478 The method returns an error if the given address does not
9479 correspond to any USB device in the collection.
9480 </note>
9481 <see>IHostUSBDevice::address</see>
9482 </desc>
9483 <param name="name" type="wstring" dir="in">
9484 <desc>
9485 Address of the USB device (as assigned by the host) to
9486 search for.
9487 </desc>
9488 </param>
9489 <param name="device" type="IHostUSBDevice" dir="return">
9490 <desc>Found USB device object.</desc>
9491 </param>
9492 </method>
9493
9494 </collection>
9495
9496 <interface
9497 name="IHostUSBDevice" extends="IUSBDevice"
9498 uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
9499 wsmap="managed"
9500 >
9501 <desc>
9502 The IHostUSBDevice interface represents a physical USB device attached
9503 to the host computer.
9504
9505 Besides properties inherited from IUSBDevice, this interface adds the
9506 <link to="#state"/> property that holds the courrent state of the USB
9507 device.
9508
9509 <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
9510 </desc>
9511
9512 <attribute name="state" type="USBDeviceState" readonly="yes">
9513 <desc>
9514 Current state of the device.
9515 </desc>
9516 </attribute>
9517
9518 <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
9519
9520 </interface>
9521
9522
9523 <!--
9524 // IHostUSBDeviceFilter
9525 /////////////////////////////////////////////////////////////////////////
9526 -->
9527
9528 <enum
9529 name="USBDeviceFilterAction"
9530 uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
9531 >
9532 <desc>
9533 Actions for host USB device filters.
9534 <see>IHostUSBDeviceFilter, USBDeviceState</see>
9535 </desc>
9536
9537 <const name="Null" value="0">
9538 <desc><tt>null</tt> value. Never used by the API.</desc>
9539 </const>
9540 <const name="Ignore" value="1">
9541 <desc>Ignore the matched USB device.</desc>
9542 </const>
9543 <const name="Hold" value="2">
9544 <desc>Hold the matched USB device.</desc>
9545 </const>
9546 </enum>
9547
9548 <enumerator
9549 name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
9550 uuid="ff735211-903e-4642-9c37-189eb44579fe"
9551 />
9552
9553 <collection
9554 name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
9555 enumerator="IHostUSBDeviceFilterEnumerator"
9556 uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
9557 readonly="yes"
9558 />
9559
9560 <interface
9561 name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
9562 uuid="4cc70246-d74a-400f-8222-3900489c0374"
9563 wsmap="managed"
9564 >
9565 <desc>
9566 The IHostUSBDeviceFilter interface represents a global filter for a
9567 physical USB device used by the host computer. Used indirectly in
9568 <link to="IHost::USBDeviceFilters"/>.
9569
9570 Using filters of this type, the host computer determines the initial
9571 state of the USB device after it is physically attached to the
9572 host's USB controller.
9573
9574 <note>
9575 The <link to="#remote"/> attribute is ignored by this type of
9576 filters, because it makes sense only for
9577 <link to="IUSBController::deviceFilters">machine USB filters</link>.
9578 </note>
9579
9580 <see>IHost::USBDeviceFilters</see>
9581 </desc>
9582
9583 <attribute name="action" type="USBDeviceFilterAction">
9584 <desc>
9585 Action performed by the host when an attached USB device
9586 matches this filter.
9587 </desc>
9588 </attribute>
9589
9590 </interface>
9591
9592 <!--
9593 // IAudioAdapter
9594 /////////////////////////////////////////////////////////////////////////
9595 -->
9596
9597 <enum
9598 name="AudioDriverType"
9599 uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
9600 >
9601 <desc>
9602 Host audio driver type.
9603 </desc>
9604
9605 <const name="Null" value="0">
9606 <desc><tt>null</tt> value. Also means "dummy audio driver".</desc>
9607 </const>
9608 <const name="WinMM" value="1"/>
9609 <const name="OSS" value="2"/>
9610 <const name="ALSA" value="3"/>
9611 <const name="DirectSound" value="4"/>
9612 <const name="CoreAudio" value="5"/>
9613 <const name="MMPM" value="6"/>
9614 <const name="Pulse" value="7"/>
9615 <const name="SolAudio" value="8"/>
9616 </enum>
9617
9618 <enum
9619 name="AudioControllerType"
9620 uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
9621 >
9622 <desc>
9623 Virtual audio controller type.
9624 </desc>
9625
9626 <const name="AC97" value="0"/>
9627 <const name="SB16" value="1"/>
9628 </enum>
9629
9630 <interface
9631 name="IAudioAdapter" extends="$unknown"
9632 uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
9633 wsmap="managed"
9634 >
9635 <desc>
9636 The IAudioAdapter interface represents the virtual audio adapter of
9637 the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
9638 </desc>
9639 <attribute name="enabled" type="boolean">
9640 <desc>
9641 Flag whether the audio adapter is present in the
9642 guest system. If disabled, the virtual guest hardware will
9643 not contain any audio adapter. Can only be changed when
9644 the VM is not running.
9645 </desc>
9646 </attribute>
9647 <attribute name="audioController" type="AudioControllerType">
9648 <desc>
9649 The audio hardware we emulate.
9650 </desc>
9651 </attribute>
9652 <attribute name="audioDriver" type="AudioDriverType">
9653 <desc>
9654 Audio driver the adapter is connected to. This setting
9655 can only be changed when the VM is not running.
9656 </desc>
9657 </attribute>
9658 </interface>
9659
9660 <!--
9661 // IVRDPServer
9662 /////////////////////////////////////////////////////////////////////////
9663 -->
9664
9665 <enum
9666 name="VRDPAuthType"
9667 uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
9668 >
9669 <desc>
9670 VRDP authentication type.
9671 </desc>
9672
9673 <const name="Null" value="0">
9674 <desc><tt>null</tt> value. Also means "no authentication".</desc>
9675 </const>
9676 <const name="External" value="1"/>
9677 <const name="Guest" value="2"/>
9678 </enum>
9679
9680 <interface
9681 name="IVRDPServer" extends="$unknown"
9682 uuid="ed9d31ae-867f-45fc-b727-6740084d1883"
9683 wsmap="managed"
9684 >
9685 <attribute name="enabled" type="boolean">
9686 <desc>VRDP server status.</desc>
9687 </attribute>
9688
9689 <attribute name="port" type="unsigned long">
9690 <desc>
9691 VRDP server port number.
9692 <note>
9693 Setting the value of this property to <tt>0</tt> will reset the port
9694 number to the default value which is
9695 currently <tt>3389</tt>. Reading this property will always return a
9696 real port number, even after it has been set to <tt>0</tt> (in which
9697 case the default port is returned).
9698 </note>
9699 </desc>
9700 </attribute>
9701
9702 <attribute name="netAddress" type="wstring">
9703 <desc>VRDP server address.</desc>
9704 </attribute>
9705
9706 <attribute name="authType" type="VRDPAuthType">
9707 <desc>VRDP authentication method.</desc>
9708 </attribute>
9709
9710 <attribute name="authTimeout" type="unsigned long">
9711 <desc>Timeout for guest authentication. Milliseconds.</desc>
9712 </attribute>
9713
9714 <attribute name="allowMultiConnection" type="boolean">
9715 <desc>
9716 Flag whether multiple simultaneous connections to the VM are permitted.
9717 Note that this will be replaced by a more powerful mechanism in the future.
9718 </desc>
9719 </attribute>
9720
9721 </interface>
9722
9723
9724 <!--
9725 // ISharedFolder
9726 /////////////////////////////////////////////////////////////////////////
9727 -->
9728
9729 <enumerator
9730 name="ISharedFolderEnumerator" type="ISharedFolder"
9731 uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
9732 />
9733
9734 <collection
9735 name="ISharedFolderCollection" type="ISharedFolder"
9736 enumerator="ISharedFolderEnumerator"
9737 uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
9738 readonly="yes">
9739
9740 <method name="findByName">
9741 <desc>
9742 Searches this collection for a shared folder with the given logical
9743 name.
9744 <note>
9745 The method returns an error if the given name does not correspond to
9746 any shared folder in the collection.
9747 </note>
9748 </desc>
9749 <param name="name" type="wstring" dir="in">
9750 <desc>Logical name of the shared folder to search for</desc>
9751 </param>
9752 <param name="sharedFolder" type="ISharedFolder" dir="return">
9753 <desc>Found shared folder object</desc>
9754 </param>
9755 </method>
9756
9757 </collection>
9758
9759 <interface
9760 name="ISharedFolder" extends="$unknown"
9761 uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
9762 wsmap="struct"
9763 >
9764 <desc>
9765 The ISharedFolder interface represents a folder in the host computer's
9766 file system accessible from the guest OS running inside a virtual
9767 machine using an associated logical name.
9768
9769 There are three types of shared folders:
9770 <ul>
9771 <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
9772 folders available to all virtual machines.</li>
9773 <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
9774 VM-specific shared folders available to the given virtual machine at
9775 startup.</li>
9776 <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
9777 VM-specific shared folders created in the session context (for
9778 example, when the virtual machine is running) and automatically
9779 discarded when the session is closed (the VM is powered off).</li>
9780 </ul>
9781
9782 Logical names of shared folders must be unique within the given scope
9783 (global, permanent or transient). However, they do not need to be unique
9784 across scopes. In this case, the definitioin of the shared folder in a
9785 more specific scope takes precedence over definitions in all other
9786 scopes. The order of precedence is (more specific to more general):
9787 <ol>
9788 <li>Transient definitions</li>
9789 <li>Permanent definitions</li>
9790 <li>Global definitions</li>
9791 </ol>
9792
9793 For example, if MyMachine has a shared folder named
9794 <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then cretaing a
9795 transient shared folder named <tt>C_DRIVE</tt> (that points
9796 to <tt>C:\\\\WINDOWS</tt>) will change the definition
9797 of <tt>C_DRIVE</tt> in the guest OS so
9798 that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
9799 to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
9800 PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
9801 the prevoious (permanent) definition of <tt>C_DRIVE</tt> that points
9802 to <tt>C:\\</tt> if it still exists.
9803
9804 Note that permanent and transient shared folders of different machines
9805 are in different name spaces, so they don't overlap and don't need to
9806 have unique logical names.
9807
9808 <note>
9809 Global shared folders are not implemented in the current vesion of the
9810 product.
9811 </note>
9812 </desc>
9813
9814 <attribute name="name" type="wstring" readonly="yes">
9815 <desc>Logical name of the shared folder.</desc>
9816 </attribute>
9817
9818 <attribute name="hostPath" type="wstring" readonly="yes">
9819 <desc>Full path to the shared folder in the host file system.</desc>
9820 </attribute>
9821
9822 <attribute name="accessible" type="boolean" readonly="yes">
9823 <desc>
9824 Whether the folder defined by the host path is currently
9825 accessible or not.
9826 For example, the folder can be unaccessible if it is placed
9827 on the network share that is not available by the time
9828 this property is read.
9829 </desc>
9830 </attribute>
9831
9832 <attribute name="writable" type="boolean" readonly="yes">
9833 <desc>
9834 Whether the folder defined by the host path is writable or
9835 not.
9836 </desc>
9837 </attribute>
9838
9839 </interface>
9840
9841 <!--
9842 // ISession
9843 /////////////////////////////////////////////////////////////////////////
9844 -->
9845
9846 <interface
9847 name="IInternalSessionControl" extends="$unknown"
9848 uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
9849 internal="yes"
9850 wsmap="suppress"
9851 >
9852 <method name="getPID">
9853 <desc>PID of the process that has created this Session object.
9854 </desc>
9855 <param name="pid" type="unsigned long" dir="return"/>
9856 </method>
9857
9858 <method name="getRemoteConsole">
9859 <desc>Returns the console object suitable for remote control.</desc>
9860 <param name="console" type="IConsole" dir="return"/>
9861 </method>
9862
9863 <method name="assignMachine">
9864 <desc>
9865 Assigns the machine object associated with this direct-type
9866 session or informs the session that it will be a remote one
9867 (if machine = NULL).
9868 </desc>
9869 <param name="machine" type="IMachine" dir="in"/>
9870 </method>
9871
9872 <method name="assignRemoteMachine">
9873 <desc>
9874 Assigns the machine and the (remote) console object associated with
9875 this remote-type session.
9876 </desc>
9877 <param name="machine" type="IMachine" dir="in"/>
9878 <param name="console" type="IConsole" dir="in"/>
9879 </method>
9880
9881 <method name="updateMachineState">
9882 <desc>
9883 Updates the machine state in the VM process.
9884 Must be called only in certain cases
9885 (see the method implementation).
9886 </desc>
9887 <param name="aMachineState" type="MachineState" dir="in"/>
9888 </method>
9889
9890 <method name="uninitialize">
9891 <desc>
9892 Uninitializes (closes) this session. Used by VirtualBox to close
9893 the corresponding remote session when the direct session dies
9894 or gets closed.
9895 </desc>
9896 </method>
9897
9898 <method name="onDVDDriveChange">
9899 <desc>
9900 Triggered when settings of the DVD drive object of the
9901 associated virtual machine have changed.
9902 </desc>
9903 </method>
9904
9905 <method name="onFloppyDriveChange">
9906 <desc>
9907 Triggered when settings of the floppy drive object of the
9908 associated virtual machine have changed.
9909 </desc>
9910 </method>
9911
9912 <method name="onNetworkAdapterChange">
9913 <desc>
9914 Triggered when settings of a network adapter of the
9915 associated virtual machine have changed.
9916 </desc>
9917 <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
9918 </method>
9919
9920 <method name="onSerialPortChange">
9921 <desc>
9922 Triggered when settions of a serial port of the
9923 associated virtual machine have changed.
9924 </desc>
9925 <param name="serialPort" type="ISerialPort" dir="in"/>
9926 </method>
9927
9928 <method name="onParallelPortChange">
9929 <desc>
9930 Triggered when settings of a parallel port of the
9931 associated virtual machine have changed.
9932 </desc>
9933 <param name="parallelPort" type="IParallelPort" dir="in"/>
9934 </method>
9935
9936 <method name="onVRDPServerChange">
9937 <desc>
9938 Triggered when settings of the VRDP server object of the
9939 associated virtual machine have changed.
9940 </desc>
9941 </method>
9942
9943 <method name="onUSBControllerChange">
9944 <desc>
9945 Triggered when settings of the USB controller object of the
9946 associated virtual machine have changed.
9947 </desc>
9948 </method>
9949
9950 <method name="onSharedFolderChange">
9951 <desc>
9952 Triggered when a permanent (global or machine) shared folder has been
9953 created or removed.
9954 <note>
9955 We don't pass shared folder parameters in this notification because
9956 the order in which parallel notifications are delivered is not defined,
9957 therefore it could happen that these parameters were outdated by the
9958 time of processing this notification.
9959 </note>
9960 </desc>
9961 <param name="global" type="boolean" dir="in"/>
9962 </method>
9963
9964 <method name="onUSBDeviceAttach">
9965 <desc>
9966 Triggered when a request to capture a USB device (as a result
9967 of matched USB filters or direct call to
9968 <link to="IConsole::attachUSBDevice"/>) has completed.
9969 A @c null @a error object means success, otherwise it
9970 describes a failure.
9971 </desc>
9972 <param name="device" type="IUSBDevice" dir="in"/>
9973 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
9974 <param name="maskedInterfaces" type="unsigned long" dir="in"/>
9975 </method>
9976
9977 <method name="onUSBDeviceDetach">
9978 <desc>
9979 Triggered when a request to release the USB device (as a result
9980 of machine termination or direct call to
9981 <link to="IConsole::detachUSBDevice"/>) has completed.
9982 A @c null @a error object means success, otherwise it
9983 </desc>
9984 <param name="id" type="uuid" dir="in"/>
9985 <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
9986 </method>
9987
9988 <method name="onShowWindow">
9989 <desc>
9990 Called by <link to="IMachine::canShowConsoleWindow()"/> and by
9991 <link to="IMachine::showConsoleWindow()"/> in order to notify
9992 console callbacks
9993 <link to="IConsoleCallback::onCanShowWindow()"/>
9994 and <link to="IConsoleCallback::onShowWindow()"/>.
9995 </desc>
9996 <param name="check" type="boolean" dir="in"/>
9997 <param name="canShow" type="boolean" dir="out"/>
9998 <param name="winId" type="unsigned long long" dir="out"/>
9999 </method>
10000
10001 <method name="accessGuestProperty">
10002 <desc>
10003 Called by <link to="IMachine::getGuestProperty()"/> and by
10004 <link to="IMachine::setGuestProperty()"/> in order to read and
10005 modify guest properties.
10006 </desc>
10007 <param name="name" type="wstring" dir="in"/>
10008 <param name="value" type="wstring" dir="in"/>
10009 <param name="flags" type="wstring" dir="in"/>
10010 <param name="isSetter" type="boolean" dir="in"/>
10011 <param name="retValue" type="wstring" dir="out"/>
10012 <param name="retTimestamp" type="unsigned long long" dir="out"/>
10013 <param name="retFlags" type="wstring" dir="out"/>
10014 </method>
10015
10016 <method name="enumerateGuestProperties">
10017 <desc>
10018 Return a list of the guest properties matching a set of patterns along
10019 with their values, timestamps and flags.
10020 </desc>
10021 <param name="patterns" type="wstring" dir="in">
10022 <desc>
10023 The patterns to match the properties against as a comma-separated
10024 string. If this is empty, all properties currently set will be
10025 returned.
10026 </desc>
10027 </param>
10028 <param name="key" type="wstring" dir="out" safearray="yes">
10029 <desc>
10030 The key names of the properties returned.
10031 </desc>
10032 </param>
10033 <param name="value" type="wstring" dir="out" safearray="yes">
10034 <desc>
10035 The values of the properties returned. The array entries match the
10036 corresponding entries in the @a key array.
10037 </desc>
10038 </param>
10039 <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
10040 <desc>
10041 The timestamps of the properties returned. The array entries match
10042 the corresponding entries in the @a key array.
10043 </desc>
10044 </param>
10045 <param name="flags" type="wstring" dir="out" safearray="yes">
10046 <desc>
10047 The flags of the properties returned. The array entries match the
10048 corresponding entries in the @a key array.
10049 </desc>
10050 </param>
10051 </method>
10052
10053 </interface>
10054
10055 <interface
10056 name="ISession" extends="$dispatched"
10057 uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
10058 wsmap="managed"
10059 >
10060 <desc>
10061 The ISession interface represents a serialization primitive for virtual
10062 machines.
10063
10064 Within VirtualBox, every time one wishes to manipulate a virtual machine
10065 (for example, change its settings or start execution), an instance of
10066 the ISession interface is required. One first creates a local session
10067 object that implements the ISession interface and then passes the
10068 created object with the method call that opens the given session and
10069 thus initiates the machine manipulation. The session serves several
10070 purposes: it identifies to the inter-process VirtualBox code which
10071 process is currently working with the virtual machine, and it ensures
10072 that there are no incompatible requests from several processes for the
10073 same virtual machine.
10074
10075 How sessions objects are used depends on whether you use the Main API
10076 via COM or via the web service:
10077
10078 <ul>
10079 <li>When using the COM API directly, an object of the Session class from the
10080 VirtualBox type library needs to be created. In regular COM C++ client code,
10081 this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
10082 This object will then act as a local session object in further calls to open
10083 a session.
10084 </li>
10085
10086 <li>In the webservice, the session manager (IWebsessionManager) instead creates
10087 one session object automatically when <link to="IWebsessionManager::logon" />
10088 is called. A managed object reference to that session object can be retrieved by
10089 calling <link to="IWebsessionManager::getSessionObject" />. This session object
10090 reference can then be used to open sessions.
10091 </li>
10092 </ul>
10093
10094 Sessions are mainly used in two variations:
10095
10096 <ul>
10097 <li>
10098 To start a virtual machine in a separate process, one would call
10099 <link to="IVirtualBox::openRemoteSession"/>, which requires a session
10100 object as its first parameter. This session then identifies the caller
10101 and lets him control the started machine (for example, pause machine
10102 execution or power it down) as well as be notified about machine
10103 execution state changes.
10104 </li>
10105
10106 <li>To alter machine settings, or to start machine execution within the
10107 current process, one needs to open a direct session for the machine first by
10108 calling <link to="IVirtualBox::openSession"/>. While a direct session
10109 is open within one process, no any other process may open another direct
10110 session for the same machine. This prevents the machine from being changed
10111 by other processes while it is running or while the machine is being configured.
10112 </li>
10113 </ul>
10114
10115 One also can attach to an existing direct session alreay opened by
10116 another process (for example, in order to send a control request to the
10117 virtual machine such as the pause or the reset request). This is done by
10118 calling <link to="IVirtualBox::openExistingSession"/>.
10119
10120 <note>
10121 Unless you are trying to write a new VirtualBox front-end that
10122 performs direct machine execution (like the VirtualBox or VBoxSDL
10123 front-ends), don't call <link to="IConsole::powerUp"/> in a direct
10124 session opened by <link to="IVirtualBox::openSession"/> and use this
10125 session only to change virtual machine settings. If you simply want to
10126 start virtual machine execution using one of the existing front-ends
10127 (for example the VirtualBox GUI or headless server), simply use
10128 <link to="IVirtualBox::openRemoteSession"/>; these front-ends
10129 will power up the machine automatically for you.
10130 </note>
10131 </desc>
10132
10133 <attribute name="state" type="SessionState" readonly="yes">
10134 <desc>Current state of this session.</desc>
10135 </attribute>
10136
10137 <attribute name="type" type="SessionType" readonly="yes">
10138 <desc>
10139 Type of this session. The value of this attribute is valid only
10140 if the session is currently open (i.e. its #state is SessionType::SessionOpen),
10141 otherwise an error will be returned.
10142 </desc>
10143 </attribute>
10144
10145 <attribute name="machine" type="IMachine" readonly="yes">
10146 <desc>Machine object associated with this session.</desc>
10147 </attribute>
10148
10149 <attribute name="console" type="IConsole" readonly="yes">
10150 <desc>Console object associated with this session.</desc>
10151 </attribute>
10152
10153 <method name="close">
10154 <desc>
10155 Closes this session.
10156 <note>
10157 If a direct session for a machine opened with
10158 <link to="IVirtualBox::openSession()"/> is not explicitly
10159 closed when the application terminates, the state of the
10160 machine will be set to <link to="MachineState::Aborted"/>
10161 on the server. Generally, it is recommended to close all
10162 open sessions explicitly before terminating the application
10163 (no matter what is the reason of the termination).
10164 </note>
10165 </desc>
10166 </method>
10167
10168 </interface>
10169
10170 <!--
10171 // ISATAController
10172 /////////////////////////////////////////////////////////////////////////
10173 -->
10174
10175 <interface
10176 name="ISATAController" extends="$unknown"
10177 uuid="9a4b868b-1376-4533-8ef5-065b8e8cedff"
10178 wsmap="managed"
10179 >
10180 <attribute name="enabled" type="boolean">
10181 <desc>
10182 Flag whether the SATA controller is present in the
10183 guest system. If disabled, the virtual guest hardware will
10184 not contain any SATA controller. Can only be changed when
10185 the VM is powered off.
10186 </desc>
10187 </attribute>
10188
10189 <attribute name="portCount" type="unsigned long">
10190 <desc>
10191 The number of usable ports on the sata controller.
10192 It ranges from 1 to 30.
10193 </desc>
10194 </attribute>
10195
10196 <method name="GetIDEEmulationPort">
10197 <desc>Gets the corresponding port number which is emulated as an IDE device.</desc>
10198 <param name="devicePosition" type="long" dir="in"/>
10199 <param name="portNumber" type="long" dir="return"/>
10200 </method>
10201
10202 <method name="SetIDEEmulationPort">
10203 <desc>Sets the port number which is emulated as an IDE device.</desc>
10204 <param name="devicePosition" type="long" dir="in"/>
10205 <param name="portNumber" type="long" dir="in"/>
10206 </method>
10207
10208 </interface>
10209
10210<if target="wsdl">
10211
10212 <!--
10213 // IManagedObjectRef
10214 /////////////////////////////////////////////////////////////////////////
10215 -->
10216
10217 <interface
10218 name="IManagedObjectRef" extends="$unknown"
10219 uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
10220 internal="yes"
10221 wsmap="managed"
10222 wscpp="hardcoded"
10223 >
10224 <desc>
10225 Managed object reference.
10226
10227 Only within the webservice, a managed object reference (which is really
10228 an opaque number) allows a webservice client to address an object
10229 that lives in the address space of the webservice server.
10230
10231 Behind each managed object reference, there is a COM object that lives
10232 in the webservice server's address space. The COM object is not freed
10233 until the managed object reference is released, either by an explicit
10234 call to <link to="IManagedObjectRef::release" /> or by logging off from
10235 the webservice (<link to="IWebsessionManager::logoff" />), which releases
10236 all objects created during the webservice session.
10237
10238 Whenever a method call of the VirtualBox API returns a COM object, the
10239 webservice representation of that method will instead return a
10240 managed object reference, which can then be used to invoke methods
10241 on that object.
10242 </desc>
10243
10244 <method name="getInterfaceName">
10245 <desc>
10246 Returns the name of the interface that this managed object represents,
10247 for example, "IMachine", as a string.
10248 </desc>
10249 <param name="return" type="wstring" dir="return"/>
10250 </method>
10251
10252 <method name="release">
10253 <desc>
10254 Releases this managed object reference and frees the resources that
10255 were allocated for it in the webservice server process. After calling
10256 this method, the identifier of the reference can no longer be used.
10257 </desc>
10258 </method>
10259
10260 </interface>
10261
10262 <!--
10263 // IWebsessionManager
10264 /////////////////////////////////////////////////////////////////////////
10265 -->
10266
10267 <interface
10268 name="IWebsessionManager" extends="$unknown"
10269 uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
10270 internal="yes"
10271 wsmap="global"
10272 wscpp="hardcoded"
10273 >
10274 <desc>
10275 Websession manager. This provides essential services
10276 to webservice clients.
10277 </desc>
10278 <method name="logon">
10279 <desc>
10280 Logs a new client onto the webservice and returns a managed object reference to
10281 the IVirtualBox instance, which the client can then use as a basis to further
10282 queries, since all calls to the VirtualBox API are based on the IVirtualBox
10283 interface, in one way or the other.
10284 </desc>
10285 <param name="username" type="wstring" dir="in"/>
10286 <param name="password" type="wstring" dir="in"/>
10287 <param name="return" type="IVirtualBox" dir="return"/>
10288 </method>
10289
10290 <method name="getSessionObject">
10291 <desc>
10292 Returns a managed object reference to the internal ISession object that was created
10293 for this web service session when the client logged on.
10294
10295 <see>ISession</see>
10296 </desc>
10297 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
10298 <param name="return" type="ISession" dir="return"/>
10299 </method>
10300
10301 <method name="logoff">
10302 <desc>
10303 Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
10304 and destroys all resources associated with the session (most importantly, all
10305 managed objects created in the server while the session was active).
10306 </desc>
10307 <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
10308 </method>
10309
10310 </interface>
10311
10312</if>
10313
10314 <!--
10315 // IPerformanceCollector & friends
10316 /////////////////////////////////////////////////////////////////////////
10317 -->
10318
10319 <interface
10320 name="IPerformanceMetric" extends="$unknown"
10321 uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
10322 >
10323 <desc>
10324 The IPerformanceMetric interface represents parameters of the given
10325 performance metric.
10326 </desc>
10327
10328 <attribute name="metricName" type="wstring" readonly="yes">
10329 <desc>
10330 Name of the metric.
10331 </desc>
10332 </attribute>
10333
10334 <attribute name="object" type="$unknown" readonly="yes">
10335 <desc>
10336 Object this metric belongs to.
10337 </desc>
10338 </attribute>
10339
10340 <attribute name="description" type="wstring" readonly="yes">
10341 <desc>
10342 Textual description of the metric.
10343 </desc>
10344 </attribute>
10345
10346 <attribute name="period" type="unsigned long" readonly="yes">
10347 <desc>
10348 Time interval between samples, measured in seconds.
10349 </desc>
10350 </attribute>
10351
10352 <attribute name="count" type="unsigned long" readonly="yes">
10353 <desc>
10354 Number of recent samples retained by the performance collector for this
10355 metric.
10356
10357 When the collected sample count exceeds this number, older samples
10358 are discarded.
10359 </desc>
10360 </attribute>
10361
10362 <attribute name="unit" type="wstring" readonly="yes">
10363 <desc>
10364 Unit of measurement.
10365 </desc>
10366 </attribute>
10367
10368 <attribute name="minimumValue" type="long" readonly="yes">
10369 <desc>
10370 Minimum possible value of this metric.
10371 </desc>
10372 </attribute>
10373
10374 <attribute name="maximumValue" type="long" readonly="yes">
10375 <desc>
10376 Maximum possible value of this metric.
10377 </desc>
10378 </attribute>
10379 </interface>
10380
10381 <interface
10382 name="IPerformanceCollector" extends="$unknown"
10383 uuid="dcd37e5a-3964-43d1-be30-0f3c7234e347"
10384 wsmap="managed"
10385 >
10386 <desc>
10387 The IPerformanceCollector interface represents a service that collects and
10388 stores performance metrics data.
10389
10390 Performance metrics are associated with objects like IHost and
10391 IMachine. Each object has a distinct set of performance metrics.
10392 The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
10393
10394 Metric data are collected at the specified intervals and are retained
10395 internally. The interval and the number of samples retained can be set
10396 with <link to="IPerformanceCollector::setMetrics" />.
10397
10398 Metrics are organized hierarchically, each level separated by slash (/).
10399 General scheme for metric name is
10400 "Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
10401 metric name stands for: CPU category, Load metric, User submetric, average
10402 aggregate. An aggregate function is computed over all retained data. Valid
10403 aggregate functions are:
10404
10405 <ul>
10406 <li>avg -- average</li>
10407 <li>min -- minimum</li>
10408 <li>max -- maximum</li>
10409 </ul>
10410
10411 "Category/Metric" together form base metric name. A base metric is the
10412 smallest unit for which a sampling interval and the number of retained
10413 samples can be set. Only base metrics can be enabled and disabled. All
10414 sub-metrics are collected when their base metric is collected.
10415 Collected values for any set of sub-metrics can be queried with
10416 <link to="IPerformanceCollector::queryMetricsData" />.
10417
10418 The valid names for base metrics are:
10419
10420 <ul>
10421 <li>CPU/Load</li>
10422 <li>CPU/MHz</li>
10423 <li>RAM/Usage</li>
10424 </ul>
10425
10426 The general sequence for collecting and retrieving the metrics is:
10427 <ul>
10428 <li>
10429 Obtain an instance of IPerfromanceCollector with
10430 <link to="IVirtualBox::performanceCollector" />
10431 </li>
10432 <li>
10433 Allocate and populate an array with references to objects the metrics
10434 will be collected for. Use references to IHost and IMachine objects.
10435 </li>
10436 <li>
10437 Allocate and populate an array with base metric names the data will be
10438 collected for.
10439 </li>
10440 <li>
10441 Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
10442 metric data will be collected and stored.
10443 </li>
10444 <li>
10445 Wait for the data to get collected.
10446 </li>
10447 <li>
10448 Allocate and populate an array with references to objects the metric
10449 values will be queried for. You can re-use the object array used for
10450 setting base metrics.
10451 </li>
10452 <li>
10453 Allocate and populate an array with metric names the data will be
10454 collected for. Note that metric names differ from base metric names.
10455 </li>
10456 <li>
10457 Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
10458 have been collected so far are returned. Note that the values are still
10459 retained internally and data collection continues.
10460 </li>
10461 </ul>
10462 </desc>
10463
10464 <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
10465 <desc>
10466 Array of unique names of metrics.
10467
10468 This array represents all metrics supported by the performance
10469 collector. Individual objects do not necessarily support all of them.
10470 <link to="IPerformanceCollector::getMetrics"/> can be used to get the
10471 list of supported metrics for a particular object.
10472 </desc>
10473 </attribute>
10474
10475 <method name="getMetrics">
10476 <desc>
10477 Returns parameters of specified metrics for a set of objects.
10478 <note>
10479 @c Null metrics array means all metrics. @c Null object array means
10480 all existing objects.
10481 </note>
10482 </desc>
10483 <param name="metricNames" type="wstring" dir="in" safearray="yes">
10484 <desc>
10485 Metric name filter. Currently, only a comma-separated list of metrics
10486 is supported.
10487 </desc>
10488 </param>
10489 <param name="objects" type="$unknown" dir="in" safearray="yes">
10490 <desc>
10491 Set of objects to return metric parameters for.
10492 </desc>
10493 </param>
10494 <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
10495 <desc>
10496 Array of returned metric parameters.
10497 </desc>
10498 </param>
10499 </method>
10500
10501 <method name="setupMetrics">
10502 <desc>
10503 Sets parameters of specified base metrics for a set of objects.
10504 <note>
10505 @c Null metrics array means all metrics. @c Null object array means
10506 all existing objects.
10507 </note>
10508 </desc>
10509 <param name="metricNames" type="wstring" dir="in" safearray="yes">
10510 <desc>
10511 Metric name filter. Currently, only a comma-separated list of metrics
10512 is supported.
10513 </desc>
10514 </param>
10515 <param name="objects" type="$unknown" dir="in" safearray="yes">
10516 <desc>
10517 Set of objects to setup metric parameters for.
10518 </desc>
10519 </param>
10520 <param name="period" type="unsigned long" dir="in">
10521 <desc>
10522 Time interval in seconds between two consecutive samples of performace
10523 data.
10524 </desc>
10525 </param>
10526 <param name="count" type="unsigned long" dir="in">
10527 <desc>
10528 Number of samples to retain in performance data history. Older samples
10529 get discarded.
10530 </desc>
10531 </param>
10532 </method>
10533
10534 <method name="enableMetrics">
10535 <desc>
10536 Turns on collecting specified base metrics.
10537 <note>
10538 @c Null metrics array means all metrics. @c Null object array means
10539 all existing objects.
10540 </note>
10541 </desc>
10542 <param name="metricNames" type="wstring" dir="in" safearray="yes">
10543 <desc>
10544 Metric name filter. Currently, only a comma-separated list of metrics
10545 is supported.
10546 </desc>
10547 </param>
10548 <param name="objects" type="$unknown" dir="in" safearray="yes">
10549 <desc>
10550 Set of objects to enable metrics for.
10551 </desc>
10552 </param>
10553 </method>
10554
10555 <method name="disableMetrics">
10556 <desc>
10557 Turns off collecting specified base metrics.
10558 <note>
10559 @c Null metrics array means all metrics. @c Null object array means
10560 all existing objects.
10561 </note>
10562 </desc>
10563 <param name="metricNames" type="wstring" dir="in" safearray="yes">
10564 <desc>
10565 Metric name filter. Currently, only a comma-separated list of metrics
10566 is supported.
10567 </desc>
10568 </param>
10569 <param name="objects" type="$unknown" dir="in" safearray="yes">
10570 <desc>
10571 Set of objects to disable metrics for.
10572 </desc>
10573 </param>
10574 </method>
10575
10576 <method name="queryMetricsData">
10577 <desc>
10578 Queries collected metrics data for a set of objects.
10579
10580 The data itself and related metric information are returned in four
10581 parallel and one flattened array of arrays. Elements of @c
10582 returnMetricNames, @c returnObjects, @c returnDataIndices and @c
10583 returnDataLengths with the same index describe one set of values
10584 corresponding to a single metric.
10585
10586 The @a returnData parameter is a flattened array of arrays. Each start
10587 and length of a sub-array is indicated by @a returnDataIndices and @a
10588 returnDataLengths. The first value for metric <tt>metricNames[i]</tt> is at
10589 <tt> returnData[returnIndices[i]]</tt>.
10590
10591 <note>
10592 @c Null metrics array means all applicable metrics. @c Null object
10593 array means all existing objects.
10594 </note>
10595 <note>
10596 Data collection continues behind the scenes after call to @c
10597 queryMetricsData. The return data can be seen as the snapshot of
10598 the current state at the time of @c queryMetricsData call. The
10599 internally kept metric values are not cleared by the call. This makes
10600 possible querying different subsets of metrics or aggregates with
10601 subsequent calls. If periodic querying is needed it is highly
10602 suggested to query the values with @c interval*count period to avoid
10603 confusion. This way a completely new set of data values will be
10604 provided by each query.
10605 </note>
10606 </desc>
10607 <param name="metricNames" type="wstring" dir="in" safearray="yes">
10608 <desc>
10609 Metric name filter. Currently, only a comma-separated list of metrics
10610 is supported.
10611 </desc>
10612 </param>
10613 <param name="objects" type="$unknown" dir="in" safearray="yes">
10614 <desc>
10615 Set of objects to query metrics for.
10616 </desc>
10617 </param>
10618 <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
10619 <desc>
10620 Names of metrics returned in @c returnData.
10621 </desc>
10622 </param>
10623 <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
10624 <desc>
10625 Objects associated with metrics returned in @c returnData.
10626 </desc>
10627 </param>
10628 <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
10629 <desc>
10630 Indices of the first elements of value sequences of particular metrics
10631 returned in @c returnData.
10632 </desc>
10633 </param>
10634 <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
10635 <desc>
10636 Lengths of value sequences of particular metrics.
10637 </desc>
10638 </param>
10639 <param name="returnData" type="long" dir="return" safearray="yes">
10640 <desc>
10641 Flattened array of all metric data containing sequences of values for
10642 each metric.
10643 </desc>
10644 </param>
10645 </method>
10646
10647 </interface>
10648
10649 <module name="VBoxSVC" context="LocalServer">
10650 <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
10651 namespace="virtualbox.org">
10652 <interface name="IVirtualBox" default="yes"/>
10653 </class>
10654 </module>
10655
10656 <module name="VBoxC" context="InprocServer" threadingModel="Free">
10657 <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
10658 namespace="virtualbox.org">
10659 <interface name="ISession" default="yes"/>
10660 </class>
10661 </module>
10662
10663</library>
10664
10665</idl>
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