VirtualBox

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

Last change on this file since 1939 was 1721, checked in by vboxsync, 18 years ago

Implemented new 'MonitorCount' VM setting, to be used by VGA device and NT guest driver.

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