1 | <?xml version="1.0" ?>
|
---|
2 |
|
---|
3 | <!--
|
---|
4 | * :tabSize=2:indentSize=2:noTabs=true:
|
---|
5 | * :folding=explicit:collapseFolds=1:
|
---|
6 | *
|
---|
7 | * Master declaration for VirtualBox's Main API, represented
|
---|
8 | * by COM/XPCOM and web service interfaces.
|
---|
9 | *
|
---|
10 | * From this document, the build system generates several files
|
---|
11 | * via XSLT that are then used during the build process.
|
---|
12 | *
|
---|
13 | * Below is the list of XSL templates that operate on this file and
|
---|
14 | * output files they generate. These XSL templates must be updated
|
---|
15 | * whenever the schema of this file changes:
|
---|
16 | *
|
---|
17 | * 1. src/VBox/Main/idl/midl.xsl =>
|
---|
18 | * out/<platform>/bin/sdk/idl/VirtualBox.idl
|
---|
19 | * (MS COM interface definition file for Main API)
|
---|
20 | *
|
---|
21 | * 2. src/VBox/Main/idl/xpidl.xsl =>
|
---|
22 | * out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
|
---|
23 | * (XPCOM interface definition file for Main API)
|
---|
24 | *
|
---|
25 | * 3. src/VBox/Main/idl/doxygen.xsl =>
|
---|
26 | * out/<platform>/obj/src/VBox/Main/VirtualBox.idl
|
---|
27 | * (pseudo-IDL for Doxygen to generate the official Main API
|
---|
28 | * documentation)
|
---|
29 | *
|
---|
30 | * 4. src/VBox/Main/webservice/*.xsl =>
|
---|
31 | * a bunch of WSDL and C++ files
|
---|
32 | * (VirtualBox web service sources and SOAP mappers;
|
---|
33 | * see src/VBox/Main/webservice/Makefile.kmk for details)
|
---|
34 | *
|
---|
35 | * 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
|
---|
36 | * out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
|
---|
37 | * (smart Qt-based C++ wrapper classes for COM interfaces
|
---|
38 | * of the Main API)
|
---|
39 | *
|
---|
40 | * 6. src/VBox/Frontends/VirtualBox4/include/COMWrappers.xsl =>
|
---|
41 | * out/<platform>/obj/src/VBox/Frontends/VirtualBox4/VirtualBox/include/COMWrappers.h
|
---|
42 | * (smart Qt-based C++ wrapper classes for COM interfaces
|
---|
43 | * of the Main API)
|
---|
44 | *
|
---|
45 | * 7. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
|
---|
46 | * out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
|
---|
47 | * (Main API TypeLib block for the WiX installer)
|
---|
48 | *
|
---|
49 | Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
50 |
|
---|
51 | This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
52 | available from http://www.virtualbox.org. This file is free software;
|
---|
53 | you can redistribute it and/or modify it under the terms of the GNU
|
---|
54 | General Public License (GPL) as published by the Free Software
|
---|
55 | Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
56 | VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
57 | hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
58 |
|
---|
59 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
60 | Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
61 | additional information or have any questions.
|
---|
62 | -->
|
---|
63 |
|
---|
64 | <idl>
|
---|
65 |
|
---|
66 | <if target="midl">
|
---|
67 | <cpp line="enum {"/>
|
---|
68 | <cpp line=" kTypeLibraryMajorVersion = 1,"/>
|
---|
69 | <cpp line=" kTypeLibraryMinorVersion = 0"/>
|
---|
70 | <cpp line="};"/>
|
---|
71 | </if>
|
---|
72 |
|
---|
73 | <if target="xpidl">
|
---|
74 | <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
|
---|
75 | <cpp>
|
---|
76 | // currenty, nsISupportsImpl.h lacks the below-like macros
|
---|
77 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
|
---|
78 | #define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
|
---|
79 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
80 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
81 | NS_IMPL_QUERY_INTERFACE1_CI(_class, _interface) \
|
---|
82 | NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
|
---|
83 | #endif
|
---|
84 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
|
---|
85 | #define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
|
---|
86 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
87 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
88 | NS_IMPL_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
|
---|
89 | NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
|
---|
90 | #endif
|
---|
91 | </cpp>
|
---|
92 | </if>
|
---|
93 |
|
---|
94 | <library
|
---|
95 | name="VirtualBox"
|
---|
96 | uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
|
---|
97 | version="1.3"
|
---|
98 | desc="VirtualBox Type Library"
|
---|
99 | appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
|
---|
100 | supportsErrorInfo="yes"
|
---|
101 | >
|
---|
102 |
|
---|
103 | <!--
|
---|
104 | // all common enums
|
---|
105 | /////////////////////////////////////////////////////////////////////////
|
---|
106 | -->
|
---|
107 |
|
---|
108 | <enum
|
---|
109 | name="TSBool"
|
---|
110 | uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
|
---|
111 | >
|
---|
112 | <desc>
|
---|
113 | Boolean variable having a third state, default.
|
---|
114 | </desc>
|
---|
115 |
|
---|
116 | <const name="False" value="0"/>
|
---|
117 | <const name="True" value="1"/>
|
---|
118 | <const name="Default" value="2"/>
|
---|
119 | </enum>
|
---|
120 |
|
---|
121 | <enum
|
---|
122 | name="MachineState"
|
---|
123 | uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
|
---|
124 | >
|
---|
125 | <desc>
|
---|
126 | Virtual machine execution state. This enumeration represents possible
|
---|
127 | values of the <link to="IMachine::state"/> attribute.
|
---|
128 | </desc>
|
---|
129 |
|
---|
130 | <const name="Null" value="0">
|
---|
131 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
132 | </const>
|
---|
133 | <const name="PoweredOff" value="1">
|
---|
134 | <desc>
|
---|
135 | The machine is not running.
|
---|
136 | </desc>
|
---|
137 | </const>
|
---|
138 | <const name="Saved" value="2">
|
---|
139 | <desc>
|
---|
140 | The machine is not currently running, but the execution state
|
---|
141 | of the machine has been saved to an external file when it
|
---|
142 | was running.
|
---|
143 | <note>
|
---|
144 | No any machine settings can be altered when the machine
|
---|
145 | is in this state.
|
---|
146 | </note>
|
---|
147 | </desc>
|
---|
148 | </const>
|
---|
149 | <const name="Aborted" value="3">
|
---|
150 | <desc>
|
---|
151 | A process that run the machine has abnormally terminated.
|
---|
152 | Other than that, this value is equivalent to #PoweredOff.
|
---|
153 | </desc>
|
---|
154 | </const>
|
---|
155 | <const name="Running" value="4">
|
---|
156 | <desc>
|
---|
157 | The machine is currently being executed.
|
---|
158 | <note>
|
---|
159 | This value can be used in comparison expressions:
|
---|
160 | all state values below it describe a virtual machine that is
|
---|
161 | not currently being executed (i.e., it is completely out of
|
---|
162 | action).
|
---|
163 | </note>
|
---|
164 | <note internal="yes">
|
---|
165 | For whoever decides to touch this enum: In order to keep the
|
---|
166 | aforementioned comparisons valid, this state must immediately
|
---|
167 | preceed the Paused state.
|
---|
168 | </note>
|
---|
169 | </desc>
|
---|
170 | </const>
|
---|
171 | <const name="Paused" value="5">
|
---|
172 | <desc>
|
---|
173 | The execution of the machine has been paused.
|
---|
174 | <note>
|
---|
175 | This value can be used in comparison expressions: all state values
|
---|
176 | above it represent unstable states of the running virtual
|
---|
177 | machine. Unless explicitly stated otherwise, no machine settings can
|
---|
178 | be altered when it is in one of the unstable states.
|
---|
179 | </note>
|
---|
180 | <note internal="yes">
|
---|
181 | For whoever decides to touch this enum: In order to keep the
|
---|
182 | aforementioned comparisons valid, this state must immediately
|
---|
183 | follow the Running state.
|
---|
184 | </note>
|
---|
185 | </desc>
|
---|
186 | </const>
|
---|
187 | <const name="Stuck" value="6">
|
---|
188 | <desc>
|
---|
189 | The execution of the machine has reached the "Guru Meditation"
|
---|
190 | condition. This condition indicates an internal VMM failure which may
|
---|
191 | happen as a result of either an unhandled low-level virtual hardware
|
---|
192 | exception or one of the recompiler exceptions (such as
|
---|
193 | the <i>too-many-traps</i> condition).
|
---|
194 | </desc>
|
---|
195 | </const>
|
---|
196 | <const name="Starting" value="7">
|
---|
197 | <desc>
|
---|
198 | The machine is being started after
|
---|
199 | <link to="IConsole::powerUp">powering it on</link> from a
|
---|
200 | zero execution state.
|
---|
201 | </desc>
|
---|
202 | </const>
|
---|
203 | <const name="Stopping" value="8">
|
---|
204 | <desc>
|
---|
205 | The machine is being normally stopped
|
---|
206 | (after explicitly <link to="IConsole::powerDown">powering it off</link>,
|
---|
207 | or after the guest OS has initiated a shutdown sequence).
|
---|
208 | </desc>
|
---|
209 | </const>
|
---|
210 | <const name="Saving" value="9">
|
---|
211 | <desc>
|
---|
212 | The machine is saving its execution state to a file as a
|
---|
213 | result of calling <link to="IConsole::saveState"/> or an online
|
---|
214 | snapshot of the machine is being taken using
|
---|
215 | <link to="IConsole::takeSnapshot"/>.
|
---|
216 | </desc>
|
---|
217 | </const>
|
---|
218 | <const name="Restoring" value="10">
|
---|
219 | <desc>
|
---|
220 | The execution state of the machine is being restored from a file
|
---|
221 | after <link to="IConsole::powerUp">powering it on</link> from
|
---|
222 | a saved execution state.
|
---|
223 | </desc>
|
---|
224 | </const>
|
---|
225 | <const name="Discarding" value="11">
|
---|
226 | <desc>
|
---|
227 | A snapshot of the machine is being discarded after calling
|
---|
228 | <link to="IConsole::discardSnapshot"/> or its current state is
|
---|
229 | being discarded after <link to="IConsole::discardCurrentState"/>.
|
---|
230 | </desc>
|
---|
231 | </const>
|
---|
232 | </enum>
|
---|
233 |
|
---|
234 | <enum
|
---|
235 | name="SessionState"
|
---|
236 | uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
|
---|
237 | >
|
---|
238 | <desc>
|
---|
239 | Session state. This enumeration represents possible values of
|
---|
240 | <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
|
---|
241 | attributes. Idividual value descriptions contain the appropriate
|
---|
242 | meaning for every case.
|
---|
243 | </desc>
|
---|
244 |
|
---|
245 | <const name="Null" value="0">
|
---|
246 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
247 | </const>
|
---|
248 | <const name="Closed" value="1">
|
---|
249 | <desc>
|
---|
250 | The machine has no open sessions (<link to="IMachine::sessionState"/>);
|
---|
251 | the session is closed (<link to="ISession::state"/>)
|
---|
252 | </desc>
|
---|
253 | </const>
|
---|
254 | <const name="Open" value="2">
|
---|
255 | <desc>
|
---|
256 | The machine has an open direct session (<link to="IMachine::sessionState"/>);
|
---|
257 | the session is open (<link to="ISession::state"/>)
|
---|
258 | </desc>
|
---|
259 | </const>
|
---|
260 | <const name="Spawning" value="3">
|
---|
261 | <desc>
|
---|
262 | A new (direct) session is being opened for the machine
|
---|
263 | as a result of <link to="IVirtualBox::openRemoteSession()"/>
|
---|
264 | call (<link to="IMachine::sessionState"/>);
|
---|
265 | the session is currently being opened
|
---|
266 | as a result of <link to="IVirtualBox::openRemoteSession()"/>
|
---|
267 | call (<link to="ISession::state"/>)
|
---|
268 | </desc>
|
---|
269 | </const>
|
---|
270 | <const name="Closing" value="4">
|
---|
271 | <desc>
|
---|
272 | The direct session is being closed (<link to="IMachine::sessionState"/>);
|
---|
273 | the session is being closed (<link to="ISession::state"/>)
|
---|
274 | </desc>
|
---|
275 | </const>
|
---|
276 | </enum>
|
---|
277 |
|
---|
278 | <enum
|
---|
279 | name="SessionType"
|
---|
280 | uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
|
---|
281 | >
|
---|
282 | <desc>
|
---|
283 | Session type. This enumeration represents possible values of the
|
---|
284 | <link to="ISession::type"/> attribute.
|
---|
285 | </desc>
|
---|
286 |
|
---|
287 | <const name="Null" value="0">
|
---|
288 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
289 | </const>
|
---|
290 | <const name="Direct" value="1">
|
---|
291 | <desc>
|
---|
292 | Direct session
|
---|
293 | (opened by <link to="IVirtualBox::openSession()"/>)
|
---|
294 | </desc>
|
---|
295 | </const>
|
---|
296 | <const name="Remote" value="2">
|
---|
297 | <desc>
|
---|
298 | Remote session
|
---|
299 | (opened by <link to="IVirtualBox::openRemoteSession()"/>)
|
---|
300 | </desc>
|
---|
301 | </const>
|
---|
302 | <const name="Existing" value="3">
|
---|
303 | <desc>
|
---|
304 | Existing session
|
---|
305 | (opened by <link to="IVirtualBox::openExistingSession()"/>)
|
---|
306 | </desc>
|
---|
307 | </const>
|
---|
308 | </enum>
|
---|
309 |
|
---|
310 | <enum
|
---|
311 | name="DeviceType"
|
---|
312 | uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
|
---|
313 | >
|
---|
314 | <desc>
|
---|
315 | Device type.
|
---|
316 | </desc>
|
---|
317 | <const name="Null" value="0">
|
---|
318 | <desc>
|
---|
319 | <tt>null</tt> value which may also mean "no device".
|
---|
320 | <note>
|
---|
321 | This value is not allowed for
|
---|
322 | <link to="IConsole::getDeviceActivity"/>
|
---|
323 | </note>
|
---|
324 | </desc>
|
---|
325 | </const>
|
---|
326 | <const name="Floppy" value="1">
|
---|
327 | <desc>Floppy device.</desc>
|
---|
328 | </const>
|
---|
329 | <const name="DVD" value="2">
|
---|
330 | <desc>CD/DVD-ROM device.</desc>
|
---|
331 | </const>
|
---|
332 | <const name="HardDisk" value="3">
|
---|
333 | <desc>Hard disk device.</desc>
|
---|
334 | </const>
|
---|
335 | <const name="Network" value="4">
|
---|
336 | <desc>Network device.</desc>
|
---|
337 | </const>
|
---|
338 | <const name="USB" value="5">
|
---|
339 | <desc>USB device.</desc>
|
---|
340 | </const>
|
---|
341 | <const name="SharedFolder" value="6">
|
---|
342 | <desc>Shared folder device.</desc>
|
---|
343 | </const>
|
---|
344 | </enum>
|
---|
345 |
|
---|
346 | <enum
|
---|
347 | name="DeviceActivity"
|
---|
348 | uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
|
---|
349 | >
|
---|
350 | <desc>
|
---|
351 | Device activity for <link to="IConsole::getDeviceActivity"/>.
|
---|
352 | </desc>
|
---|
353 |
|
---|
354 | <const name="Null" value="0"/>
|
---|
355 | <const name="Idle" value="1"/>
|
---|
356 | <const name="Reading" value="2"/>
|
---|
357 | <const name="Writing" value="3"/>
|
---|
358 | </enum>
|
---|
359 |
|
---|
360 | <enum
|
---|
361 | name="ResourceUsage"
|
---|
362 | uuid="FC56E4B6-B195-48e2-A5E1-A667B0D9F809"
|
---|
363 | >
|
---|
364 | <desc>
|
---|
365 | Usage type constants for
|
---|
366 | <link to="IVirtualBox::getDVDImageUsage"/> and
|
---|
367 | <link to="IVirtualBox::getFloppyImageUsage"/>.
|
---|
368 | </desc>
|
---|
369 |
|
---|
370 | <const name="Null" value="0">
|
---|
371 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
372 | </const>
|
---|
373 | <const name="Permanent" value="1">
|
---|
374 | <desc>
|
---|
375 | Scopes the VMs that use the resource permanently
|
---|
376 | (the information about this usage is stored in the VM
|
---|
377 | settings file).
|
---|
378 | </desc>
|
---|
379 | </const>
|
---|
380 | <const name="Temporary" value="2">
|
---|
381 | <desc>
|
---|
382 | Scopes the VMs that are temporarily using the resource
|
---|
383 | (the information about the usage is not yet saved in the VM
|
---|
384 | settings file). Temporary usage can take place only in the
|
---|
385 | context of an open session.
|
---|
386 | </desc>
|
---|
387 | </const>
|
---|
388 | <const name="All" value="3">
|
---|
389 | <desc>
|
---|
390 | Combines Permanent and Temporary.
|
---|
391 | </desc>
|
---|
392 | </const>
|
---|
393 | </enum>
|
---|
394 |
|
---|
395 | <enum
|
---|
396 | name="StorageBus"
|
---|
397 | uuid="715984a5-093c-43bb-aa42-a16ed16828dd"
|
---|
398 | >
|
---|
399 | <desc>Interface bus type for storage devices.</desc>
|
---|
400 |
|
---|
401 | <const name="Null" value="0">
|
---|
402 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
403 | </const>
|
---|
404 |
|
---|
405 | <const name="IDE" value="1"/>
|
---|
406 | <const name="SATA" value="2"/>
|
---|
407 | </enum>
|
---|
408 |
|
---|
409 | <enum
|
---|
410 | name="ClipboardMode"
|
---|
411 | uuid="33364716-4008-4701-8f14-be0fa3d62950"
|
---|
412 | >
|
---|
413 | <desc>
|
---|
414 | Host-Guest clipboard interchange mode.
|
---|
415 | </desc>
|
---|
416 |
|
---|
417 | <const name="Disabled" value="0"/>
|
---|
418 | <const name="HostToGuest" value="1"/>
|
---|
419 | <const name="GuestToHost" value="2"/>
|
---|
420 | <const name="Bidirectional" value="3"/>
|
---|
421 | </enum>
|
---|
422 |
|
---|
423 | <enum
|
---|
424 | name="Scope"
|
---|
425 | uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
|
---|
426 | >
|
---|
427 | <desc>
|
---|
428 | Scope of the operation.
|
---|
429 |
|
---|
430 | A generic enumeration used in various methods to define the action or
|
---|
431 | argument scope.
|
---|
432 | </desc>
|
---|
433 |
|
---|
434 | <const name="Global" value="0"/>
|
---|
435 | <const name="Machine" value="1"/>
|
---|
436 | <const name="Session" value="2"/>
|
---|
437 | </enum>
|
---|
438 |
|
---|
439 | <enum
|
---|
440 | name="GuestStatisticType"
|
---|
441 | uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
|
---|
442 | >
|
---|
443 | <desc>
|
---|
444 | Statistics type for <link to="IGuest::getStatistic"/>.
|
---|
445 | </desc>
|
---|
446 |
|
---|
447 | <const name="CPULoad_Idle" value="0">
|
---|
448 | <desc>
|
---|
449 | Idle CPU load (0-100%) for last interval.
|
---|
450 | </desc>
|
---|
451 | </const>
|
---|
452 | <const name="CPULoad_Kernel" value="1">
|
---|
453 | <desc>
|
---|
454 | Kernel CPU load (0-100%) for last interval.
|
---|
455 | </desc>
|
---|
456 | </const>
|
---|
457 | <const name="CPULoad_User" value="2">
|
---|
458 | <desc>
|
---|
459 | User CPU load (0-100%) for last interval.
|
---|
460 | </desc>
|
---|
461 | </const>
|
---|
462 | <const name="Threads" value="3">
|
---|
463 | <desc>
|
---|
464 | Total number of threads in the system.
|
---|
465 | </desc>
|
---|
466 | </const>
|
---|
467 | <const name="Processes" value="4">
|
---|
468 | <desc>
|
---|
469 | Total number of processes in the system.
|
---|
470 | </desc>
|
---|
471 | </const>
|
---|
472 | <const name="Handles" value="5">
|
---|
473 | <desc>
|
---|
474 | Total number of handles in the system.
|
---|
475 | </desc>
|
---|
476 | </const>
|
---|
477 | <const name="MemoryLoad" value="6">
|
---|
478 | <desc>
|
---|
479 | Memory load (0-100%).
|
---|
480 | </desc>
|
---|
481 | </const>
|
---|
482 | <const name="PhysMemTotal" value="7">
|
---|
483 | <desc>
|
---|
484 | Total physical memory in megabytes.
|
---|
485 | </desc>
|
---|
486 | </const>
|
---|
487 | <const name="PhysMemAvailable" value="8">
|
---|
488 | <desc>
|
---|
489 | Free physical memory in megabytes.
|
---|
490 | </desc>
|
---|
491 | </const>
|
---|
492 | <const name="PhysMemBalloon" value="9">
|
---|
493 | <desc>
|
---|
494 | Ballooned physical memory in megabytes.
|
---|
495 | </desc>
|
---|
496 | </const>
|
---|
497 | <const name="MemCommitTotal" value="10">
|
---|
498 | <desc>
|
---|
499 | Total amount of memory in the committed state in megabytes.
|
---|
500 | </desc>
|
---|
501 | </const>
|
---|
502 | <const name="MemKernelTotal" value="11">
|
---|
503 | <desc>
|
---|
504 | Total amount of memory used by the guest OS's kernel in megabytes.
|
---|
505 | </desc>
|
---|
506 | </const>
|
---|
507 | <const name="MemKernelPaged" value="12">
|
---|
508 | <desc>
|
---|
509 | Total amount of paged memory used by the guest OS's kernel in megabytes.
|
---|
510 | </desc>
|
---|
511 | </const>
|
---|
512 | <const name="MemKernelNonpaged" value="13">
|
---|
513 | <desc>
|
---|
514 | Total amount of nonpaged memory used by the guest OS's kernel in megabytes.
|
---|
515 | </desc>
|
---|
516 | </const>
|
---|
517 | <const name="MemSystemCache" value="14">
|
---|
518 | <desc>
|
---|
519 | Total amount of memory used by the guest OS's system cache in megabytes.
|
---|
520 | </desc>
|
---|
521 | </const>
|
---|
522 | <const name="PageFileSize" value="15">
|
---|
523 | <desc>
|
---|
524 | Pagefile size in megabytes.
|
---|
525 | </desc>
|
---|
526 | </const>
|
---|
527 | <const name="SampleNumber" value="16">
|
---|
528 | <desc>
|
---|
529 | Statistics sample number
|
---|
530 | </desc>
|
---|
531 | </const>
|
---|
532 | <const name="MaxVal" value="17"/>
|
---|
533 | </enum>
|
---|
534 |
|
---|
535 | <enum
|
---|
536 | name="BIOSBootMenuMode"
|
---|
537 | uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
|
---|
538 | >
|
---|
539 | <desc>
|
---|
540 | BIOS boot menu mode.
|
---|
541 | </desc>
|
---|
542 |
|
---|
543 | <const name="Disabled" value="0"/>
|
---|
544 | <const name="MenuOnly" value="1"/>
|
---|
545 | <const name="MessageAndMenu" value="2"/>
|
---|
546 | </enum>
|
---|
547 |
|
---|
548 | <enum
|
---|
549 | name="IDEControllerType"
|
---|
550 | uuid="445330e3-202a-4dab-854f-ce22e6cb9715"
|
---|
551 | >
|
---|
552 | <desc>
|
---|
553 | IDE controller type.
|
---|
554 | </desc>
|
---|
555 |
|
---|
556 | <const name="Null" value="0">
|
---|
557 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
558 | </const>
|
---|
559 | <const name="PIIX3" value="1"/>
|
---|
560 | <const name="PIIX4" value="2"/>
|
---|
561 | </enum>
|
---|
562 |
|
---|
563 | <enum
|
---|
564 | name="DriveState"
|
---|
565 | uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
|
---|
566 | >
|
---|
567 | <const name="Null" value="0">
|
---|
568 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
569 | </const>
|
---|
570 | <const name="NotMounted" value="1"/>
|
---|
571 | <const name="ImageMounted" value="2"/>
|
---|
572 | <const name="HostDriveCaptured" value="3"/>
|
---|
573 | </enum>
|
---|
574 |
|
---|
575 | <!--
|
---|
576 | // IVirtualBoxErrorInfo
|
---|
577 | /////////////////////////////////////////////////////////////////////////
|
---|
578 | -->
|
---|
579 |
|
---|
580 | <interface
|
---|
581 | name="IVirtualBoxErrorInfo" extends="$errorinfo"
|
---|
582 | uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
|
---|
583 | supportsErrorInfo="no"
|
---|
584 | wsmap="suppress"
|
---|
585 | >
|
---|
586 | <desc>
|
---|
587 | The IVirtualBoxErrorInfo interface represents extended error information.
|
---|
588 |
|
---|
589 | Extended error information can be set by VirtualBox components after
|
---|
590 | unsuccessful or partially successful method invocation. This information
|
---|
591 | can be retrievefd by the calling party as an IVirtualBoxErrorInfo object
|
---|
592 | and then shown to the client in addition to the plain 32-bit result code.
|
---|
593 |
|
---|
594 | In MS COM, this interface extends the IErrorInfo interface,
|
---|
595 | in XPCOM, it extends the nsIException interface. In both cases,
|
---|
596 | it provides a set of common attributes to retrieve error
|
---|
597 | information.
|
---|
598 |
|
---|
599 | Sometimes invocation of some component's method may involve methods of
|
---|
600 | other components that may also fail (independently of this method's
|
---|
601 | failure), or a series of non-fatal errors may precede a fatal error that
|
---|
602 | causes method failure. In cases like that, it may be desirable to preserve
|
---|
603 | information about all errors happened during method invocation and deliver
|
---|
604 | it to the caller. The <link to="#next"/> attribute is intended
|
---|
605 | specifically for this purpose and allows to represent a chain of errors
|
---|
606 | through a single IVirtualBoxErrorInfo object set after method invocation.
|
---|
607 |
|
---|
608 | Note that errors are stored to a chain in the reverse order, i.e. the
|
---|
609 | initial error object you query right after method invocation is the last
|
---|
610 | error set by the callee, the object it points to in the @a next attribute
|
---|
611 | is the previous error and so on, up to the first error (which is the last
|
---|
612 | in the chain).
|
---|
613 | </desc>
|
---|
614 |
|
---|
615 | <attribute name="resultCode" type="result" readonly="yes">
|
---|
616 | <desc>
|
---|
617 | Result code of the error.
|
---|
618 | Usually, it will be the same as the result code returned
|
---|
619 | by the method that provided this error information, but not
|
---|
620 | always. For example, on Win32, CoCreateInstance() will most
|
---|
621 | likely return E_NOINTERFACE upon unsuccessful component
|
---|
622 | instantiation attempt, but not the value the component factory
|
---|
623 | returned.
|
---|
624 | <note>
|
---|
625 | In MS COM, there is no equivalent.
|
---|
626 | In XPCOM, it is the same as nsIException::result.
|
---|
627 | </note>
|
---|
628 | </desc>
|
---|
629 | </attribute>
|
---|
630 |
|
---|
631 | <attribute name="interfaceID" type="uuid" readonly="yes">
|
---|
632 | <desc>
|
---|
633 | UUID of the interface that defined the error.
|
---|
634 | <note>
|
---|
635 | In MS COM, it is the same as IErrorInfo::GetGUID.
|
---|
636 | In XPCOM, there is no equivalent.
|
---|
637 | </note>
|
---|
638 | </desc>
|
---|
639 | </attribute>
|
---|
640 |
|
---|
641 | <attribute name="component" type="wstring" readonly="yes">
|
---|
642 | <desc>
|
---|
643 | Name of the component that generated the error.
|
---|
644 | <note>
|
---|
645 | In MS COM, it is the same as IErrorInfo::GetSource.
|
---|
646 | In XPCOM, there is no equivalent.
|
---|
647 | </note>
|
---|
648 | </desc>
|
---|
649 | </attribute>
|
---|
650 |
|
---|
651 | <attribute name="text" type="wstring" readonly="yes">
|
---|
652 | <desc>
|
---|
653 | Text description of the error.
|
---|
654 | <note>
|
---|
655 | In MS COM, it is the same as IErrorInfo::GetDescription.
|
---|
656 | In XPCOM, it is the same as nsIException::message.
|
---|
657 | </note>
|
---|
658 | </desc>
|
---|
659 | </attribute>
|
---|
660 |
|
---|
661 | <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
662 | <desc>
|
---|
663 | Next error object if there is any, or @c null otherwise.
|
---|
664 | <note>
|
---|
665 | In MS COM, there is no equivalent.
|
---|
666 | In XPCOM, it is the same as nsIException::inner.
|
---|
667 | </note>
|
---|
668 | </desc>
|
---|
669 | </attribute>
|
---|
670 |
|
---|
671 | </interface>
|
---|
672 |
|
---|
673 |
|
---|
674 | <!--
|
---|
675 | // IVirtualBox
|
---|
676 | /////////////////////////////////////////////////////////////////////////
|
---|
677 | -->
|
---|
678 |
|
---|
679 | <interface
|
---|
680 | name="IVirtualBoxCallback" extends="$unknown"
|
---|
681 | uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
|
---|
682 | wsmap="suppress"
|
---|
683 | >
|
---|
684 | <method name="onMachineStateChange">
|
---|
685 | <desc>
|
---|
686 | The execution state of the given machine has changed.
|
---|
687 | <see>IMachine::state</see>
|
---|
688 | </desc>
|
---|
689 | <param name="machineId" type="uuid" dir="in">
|
---|
690 | <desc>ID of the machine this event relates to.</desc>
|
---|
691 | </param>
|
---|
692 | <param name="state" type="MachineState" dir="in">
|
---|
693 | <desc>New execution state.</desc>
|
---|
694 | </param>
|
---|
695 | </method>
|
---|
696 |
|
---|
697 | <method name="onMachineDataChange">
|
---|
698 | <desc>
|
---|
699 | Any of the settings of the given machine has changed.
|
---|
700 | </desc>
|
---|
701 | <param name="machineId" type="uuid" dir="in">
|
---|
702 | <desc>ID of the machine this event relates to.</desc>
|
---|
703 | </param>
|
---|
704 | </method>
|
---|
705 |
|
---|
706 | <method name="onExtraDataCanChange">
|
---|
707 | <desc>
|
---|
708 | Notification when someone tries to change extra data for
|
---|
709 | either the given machine or (if null) global extra data.
|
---|
710 | This gives the chance to veto against changes.
|
---|
711 | </desc>
|
---|
712 | <param name="machineId" type="uuid" dir="in">
|
---|
713 | <desc>
|
---|
714 | ID of the machine this event relates to
|
---|
715 | (null ID for global extra data change requests).
|
---|
716 | </desc>
|
---|
717 | </param>
|
---|
718 | <param name="key" type="wstring" dir="in">
|
---|
719 | <desc>
|
---|
720 | Extra data key for the attempted write.
|
---|
721 | </desc>
|
---|
722 | </param>
|
---|
723 | <param name="value" type="wstring" dir="in">
|
---|
724 | <desc>
|
---|
725 | Extra data value for the given key.
|
---|
726 | </desc>
|
---|
727 | </param>
|
---|
728 | <param name="error" type="wstring" dir="out">
|
---|
729 | <desc>
|
---|
730 | Optional error message describing the reason of the
|
---|
731 | veto (ignored if this notification returns @c true).
|
---|
732 | </desc>
|
---|
733 | </param>
|
---|
734 | <param name="allowChange" type="boolean" dir="return">
|
---|
735 | <desc>
|
---|
736 | Flag to indicate whether the callee agrees (@ true)
|
---|
737 | or vetoes against the change (@ false).
|
---|
738 | </desc>
|
---|
739 | </param>
|
---|
740 | </method>
|
---|
741 |
|
---|
742 | <method name="onExtraDataChange">
|
---|
743 | <desc>
|
---|
744 | Notification when machine specific or global extra data
|
---|
745 | has changed.
|
---|
746 | </desc>
|
---|
747 | <param name="machineId" type="uuid" dir="in">
|
---|
748 | <desc>
|
---|
749 | ID of the machine this event relates to.
|
---|
750 | Null for global extra data changes.
|
---|
751 | </desc>
|
---|
752 | </param>
|
---|
753 | <param name="key" type="wstring" dir="in">
|
---|
754 | <desc>
|
---|
755 | Extra data key that has changed.
|
---|
756 | </desc>
|
---|
757 | </param>
|
---|
758 | <param name="value" type="wstring" dir="in">
|
---|
759 | <desc>
|
---|
760 | Extra data value for the given key.
|
---|
761 | </desc>
|
---|
762 | </param>
|
---|
763 | </method>
|
---|
764 |
|
---|
765 | <method name="onMediaRegistered">
|
---|
766 | <desc>
|
---|
767 | The given media was registered or unregistered
|
---|
768 | within this VirtualBox installation.
|
---|
769 |
|
---|
770 | The @a mediaType parameter describes what type of
|
---|
771 | media the specified @a mediaId refers to. Possible
|
---|
772 | values are:
|
---|
773 |
|
---|
774 | <ul>
|
---|
775 | <li><link to="DeviceType::HardDisk"/>: the media is a hard disk
|
---|
776 | that, if registered, can be obtained using the
|
---|
777 | <link to="IVirtualBox::getHardDisk"/> call.</li>
|
---|
778 | <li><link to="DeviceType::DVD"/>: the media is a CD/DVD image
|
---|
779 | that, if registered, can be obtained using the
|
---|
780 | <link to="IVirtualBox::getDVDImage"/> call.</li>
|
---|
781 | <li><link to="DeviceType::Floppy"/>: the media is a Floppy image
|
---|
782 | that, if registered, can be obtained using the
|
---|
783 | <link to="IVirtualBox::getFloppyImage"/> call.</li>
|
---|
784 | </ul>
|
---|
785 |
|
---|
786 | Note that if this is a deregistration notification,
|
---|
787 | there is no way to access the object representing the
|
---|
788 | unregistered media. It is supposed that the
|
---|
789 | application will do required cleanup based on the @a
|
---|
790 | mediaId value.
|
---|
791 | </desc>
|
---|
792 | <param name="mediaId" type="uuid" dir="in">
|
---|
793 | <desc>ID of the media this event relates to.</desc>
|
---|
794 | </param>
|
---|
795 | <param name="mediaType" type="DeviceType" dir="in">
|
---|
796 | <desc>Type of the media this event relates to.</desc>
|
---|
797 | </param>
|
---|
798 | <param name="registered" type="boolean" dir="in">
|
---|
799 | <desc>
|
---|
800 | If true, the media was registered, otherwise it was
|
---|
801 | unregistered.
|
---|
802 | </desc>
|
---|
803 | </param>
|
---|
804 | </method>
|
---|
805 |
|
---|
806 | <method name="onMachineRegistered">
|
---|
807 | <desc>
|
---|
808 | The given machine was registered or unregistered
|
---|
809 | within this VirtualBox installation.
|
---|
810 | </desc>
|
---|
811 | <param name="machineId" type="uuid" dir="in">
|
---|
812 | <desc>ID of the machine this event relates to.</desc>
|
---|
813 | </param>
|
---|
814 | <param name="registered" type="boolean" dir="in">
|
---|
815 | <desc>
|
---|
816 | If true, the machine was registered, otherwise it was
|
---|
817 | unregistered.
|
---|
818 | </desc>
|
---|
819 | </param>
|
---|
820 | </method>
|
---|
821 |
|
---|
822 | <method name="onSessionStateChange">
|
---|
823 | <desc>
|
---|
824 | The state of the session for the given machine was changed.
|
---|
825 | <see>IMachine::sessionState</see>
|
---|
826 | </desc>
|
---|
827 | <param name="machineId" type="uuid" dir="in">
|
---|
828 | <desc>ID of the machine this event relates to.</desc>
|
---|
829 | </param>
|
---|
830 | <param name="state" type="SessionState" dir="in">
|
---|
831 | <desc>New session state.</desc>
|
---|
832 | </param>
|
---|
833 | </method>
|
---|
834 |
|
---|
835 | <method name="onSnapshotTaken">
|
---|
836 | <desc>
|
---|
837 | A new snapshot of the machine has been taken.
|
---|
838 | <see>ISnapshot</see>
|
---|
839 | </desc>
|
---|
840 | <param name="machineId" type="uuid" dir="in">
|
---|
841 | <desc>ID of the machine this event relates to.</desc>
|
---|
842 | </param>
|
---|
843 | <param name="snapshotId" type="uuid" dir="in">
|
---|
844 | <desc>ID of the new snapshot.</desc>
|
---|
845 | </param>
|
---|
846 | </method>
|
---|
847 |
|
---|
848 | <method name="onSnapshotDiscarded">
|
---|
849 | <desc>
|
---|
850 | Snapshot of the given machine has been discarded.
|
---|
851 |
|
---|
852 | <note>
|
---|
853 | This notification is delivered <b>after</b> the snapshot
|
---|
854 | object has been uninitialized on the server (so that any
|
---|
855 | attempt to call its methods will return an error).
|
---|
856 | </note>
|
---|
857 |
|
---|
858 | <see>ISnapshot</see>
|
---|
859 | </desc>
|
---|
860 | <param name="machineId" type="uuid" dir="in">
|
---|
861 | <desc>ID of the machine this event relates to.</desc>
|
---|
862 | </param>
|
---|
863 | <param name="snapshotId" type="uuid" dir="in">
|
---|
864 | <desc>
|
---|
865 | ID of the discarded snapshot. <tt>null</tt> means the
|
---|
866 | current machine state has been discarded (restored from
|
---|
867 | the current snapshot).
|
---|
868 | </desc>
|
---|
869 | </param>
|
---|
870 | </method>
|
---|
871 |
|
---|
872 | <method name="onSnapshotChange">
|
---|
873 | <desc>
|
---|
874 | Snapshot properties (name and/or description) have been changed.
|
---|
875 | <see>ISnapshot</see>
|
---|
876 | </desc>
|
---|
877 | <param name="machineId" type="uuid" dir="in">
|
---|
878 | <desc>ID of the machine this event relates to.</desc>
|
---|
879 | </param>
|
---|
880 | <param name="snapshotId" type="uuid" dir="in">
|
---|
881 | <desc>ID of the changed snapshot.</desc>
|
---|
882 | </param>
|
---|
883 | </method>
|
---|
884 |
|
---|
885 | <method name="onGuestPropertyChange">
|
---|
886 | <desc>
|
---|
887 | Notification when a guest property has changed.
|
---|
888 | </desc>
|
---|
889 | <param name="machineId" type="uuid" dir="in">
|
---|
890 | <desc>
|
---|
891 | ID of the machine this event relates to.
|
---|
892 | </desc>
|
---|
893 | </param>
|
---|
894 | <param name="name" type="wstring" dir="in">
|
---|
895 | <desc>
|
---|
896 | The name of the property that has changed.
|
---|
897 | </desc>
|
---|
898 | </param>
|
---|
899 | <param name="value" type="wstring" dir="in">
|
---|
900 | <desc>
|
---|
901 | The new property value.
|
---|
902 | </desc>
|
---|
903 | </param>
|
---|
904 | <param name="flags" type="wstring" dir="in">
|
---|
905 | <desc>
|
---|
906 | The new property flags.
|
---|
907 | </desc>
|
---|
908 | </param>
|
---|
909 | </method>
|
---|
910 |
|
---|
911 | </interface>
|
---|
912 |
|
---|
913 | <interface
|
---|
914 | name="IVirtualBox" extends="$dispatched"
|
---|
915 | uuid="557a07bc-e6ae-4520-a361-4a8493199137"
|
---|
916 | wsmap="managed"
|
---|
917 | >
|
---|
918 | <desc>
|
---|
919 | The IVirtualBox interface represents the main interface exposed by the
|
---|
920 | product that provides virtual machine management.
|
---|
921 |
|
---|
922 | An instance of IVirtualBox is required for the product to do anything
|
---|
923 | useful. Even though the interface does not expose this, internally,
|
---|
924 | IVirtualBox is implemented as a singleton and actually lives in the
|
---|
925 | process of the VirtualBox server (VBoxSVC.exe). This makes sure that
|
---|
926 | IVirtualBox can track the state of all virtual machines on a particular
|
---|
927 | host, regardless of which frontend started them.
|
---|
928 |
|
---|
929 | To enumerate all the virtual machines on the host, use the
|
---|
930 | <link to="IVirtualBox::machines"/> attribute.
|
---|
931 | </desc>
|
---|
932 |
|
---|
933 | <attribute name="version" type="wstring" readonly="yes">
|
---|
934 | <desc>
|
---|
935 | A string representing the version number of the product. The
|
---|
936 | format is 3 integer numbers divided by dots (e.g. 1.0.1). The
|
---|
937 | last number represents the build number and will frequently change.
|
---|
938 | </desc>
|
---|
939 | </attribute>
|
---|
940 |
|
---|
941 | <attribute name="packageType" type="wstring" readonly="yes">
|
---|
942 | <desc>
|
---|
943 | A string representing the package type of this product. The
|
---|
944 | format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
|
---|
945 | SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
|
---|
946 | is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
|
---|
947 | this.
|
---|
948 | </desc>
|
---|
949 | </attribute>
|
---|
950 |
|
---|
951 | <attribute name="homeFolder" type="wstring" readonly="yes">
|
---|
952 | <desc>
|
---|
953 | Full path to the directory where the global settings file,
|
---|
954 | <tt>VirtualBox.xml</tt>, is stored.
|
---|
955 |
|
---|
956 | In this version of VirtualBox, the value of this property is
|
---|
957 | always <tt><user_dir>/.VirtualBox</tt> (where
|
---|
958 | <tt><user_dir></tt> is the path to the user directory,
|
---|
959 | as determined by the host OS), and cannot be changed.
|
---|
960 |
|
---|
961 | This path is also used as the base to resolve relative paths in
|
---|
962 | places where relative paths are allowed (unless otherwise
|
---|
963 | expressly indicated).
|
---|
964 | </desc>
|
---|
965 | </attribute>
|
---|
966 |
|
---|
967 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
968 | <desc>
|
---|
969 | Full name of the global settings file.
|
---|
970 | The value of this property corresponds to the value of
|
---|
971 | <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
|
---|
972 | </desc>
|
---|
973 | </attribute>
|
---|
974 |
|
---|
975 | <attribute name="settingsFileVersion" type="wstring" readonly="yes">
|
---|
976 | <desc>
|
---|
977 | Current version of the format of the global VirtualBox settings file
|
---|
978 | (<tt>VirtualBox.xml</tt>).
|
---|
979 |
|
---|
980 | The version string has the following format:
|
---|
981 | <pre>
|
---|
982 | x.y-platform
|
---|
983 | </pre>
|
---|
984 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
985 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
986 |
|
---|
987 | The current version usually matches the value of the
|
---|
988 | <link to="#settingsFormatVersion"/> attribute unless the
|
---|
989 | settings file was created by an older version of VirtualBox and there
|
---|
990 | was a change of the settings file format since then.
|
---|
991 |
|
---|
992 | Note that VirtualBox automatically converts settings files from older
|
---|
993 | versions to the most recent version when reading them (usually at
|
---|
994 | VirtualBox startup) but it doesn't save the changes back until
|
---|
995 | you call a method that implicitly saves settings (such as
|
---|
996 | <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
|
---|
997 | explicitly. Therefore, if the value of this attribute differs from the
|
---|
998 | value of <link to="#settingsFormatVersion"/>, then it
|
---|
999 | means that the settings file was converted but the result of the
|
---|
1000 | conversion is not yet saved to disk.
|
---|
1001 |
|
---|
1002 | The above feature may be used by interactive front-ends to inform users
|
---|
1003 | about the settings file format change and offer them to explicitly save
|
---|
1004 | all converted settings files (the global and VM-specific ones),
|
---|
1005 | optionally create bacup copies of the old settings files before saving,
|
---|
1006 | etc.
|
---|
1007 |
|
---|
1008 | <see>settingsFormatVersion, saveSettingsWithBackup()</see>
|
---|
1009 | </desc>
|
---|
1010 | </attribute>
|
---|
1011 |
|
---|
1012 | <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
|
---|
1013 | <desc>
|
---|
1014 | Most recent version of the settings file format.
|
---|
1015 |
|
---|
1016 | The version string has the following format:
|
---|
1017 | <pre>
|
---|
1018 | x.y-platform
|
---|
1019 | </pre>
|
---|
1020 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
1021 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
1022 |
|
---|
1023 | VirtualBox uses this version of the format when saving settings files
|
---|
1024 | (either as a result of method calls that require to save settings or as
|
---|
1025 | a result of an explicit call to <link to="#saveSettings()"/>).
|
---|
1026 |
|
---|
1027 | <see>settingsFileVersion</see>
|
---|
1028 | </desc>
|
---|
1029 | </attribute>
|
---|
1030 |
|
---|
1031 | <attribute name="host" type="IHost" readonly="yes">
|
---|
1032 | <desc>Associated host object.</desc>
|
---|
1033 | </attribute>
|
---|
1034 |
|
---|
1035 | <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
|
---|
1036 | <desc>Associated system information object.</desc>
|
---|
1037 | </attribute>
|
---|
1038 |
|
---|
1039 | <attribute name="machines" type="IMachineCollection" readonly="yes">
|
---|
1040 | <desc>
|
---|
1041 | Collection of machine objects registered within this VirtualBox
|
---|
1042 | instance.
|
---|
1043 | </desc>
|
---|
1044 | </attribute>
|
---|
1045 |
|
---|
1046 | <attribute name="machines2" type="IMachine" readonly="yes" safearray="yes">
|
---|
1047 | <desc>
|
---|
1048 | Array of machine objects registered within this VirtualBox instance.
|
---|
1049 | </desc>
|
---|
1050 | </attribute>
|
---|
1051 |
|
---|
1052 | <attribute name="hardDisks" type="IHardDiskCollection" readonly="yes">
|
---|
1053 | <desc>
|
---|
1054 | Collection of hard disk objects registered within this VirtualBox
|
---|
1055 | instance.
|
---|
1056 |
|
---|
1057 | This collection contains only "top-level" (basic or independent) hard
|
---|
1058 | disk images, but not differencing ones. All differencing images of the
|
---|
1059 | given top-level image (i.e. all its children) can be enumerated using
|
---|
1060 | <link to="IHardDisk::children"/>.
|
---|
1061 | </desc>
|
---|
1062 | </attribute>
|
---|
1063 |
|
---|
1064 | <attribute name="DVDImages" type="IDVDImageCollection" readonly="yes"/>
|
---|
1065 |
|
---|
1066 | <attribute name="FloppyImages" type="IFloppyImageCollection" readonly="yes"/>
|
---|
1067 |
|
---|
1068 | <attribute name="progressOperations" type="IProgressCollection" readonly="yes"/>
|
---|
1069 |
|
---|
1070 | <attribute name="guestOSTypes" type="IGuestOSTypeCollection" readonly="yes"/>
|
---|
1071 |
|
---|
1072 | <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
|
---|
1073 | <desc>
|
---|
1074 | Collection of global shared folders. Global shared folders are
|
---|
1075 | available to all virtual machines.
|
---|
1076 |
|
---|
1077 | New shared folders are added to the collection using
|
---|
1078 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
1079 | removed using <link to="#removeSharedFolder"/>.
|
---|
1080 |
|
---|
1081 | <note>
|
---|
1082 | In the current version of the product, global shared folders are not
|
---|
1083 | implemented and therefore this collection is always empty.
|
---|
1084 | </note>
|
---|
1085 | </desc>
|
---|
1086 | </attribute>
|
---|
1087 |
|
---|
1088 | <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
|
---|
1089 | <desc>
|
---|
1090 | Associated performance collector object.
|
---|
1091 | </desc>
|
---|
1092 | </attribute>
|
---|
1093 |
|
---|
1094 | <method name="createMachine">
|
---|
1095 | <desc>
|
---|
1096 | Creates a new virtual machine.
|
---|
1097 |
|
---|
1098 | The new machine will have "empty" default settings and will not
|
---|
1099 | yet be registered. The typical sequence to create a virtual machine
|
---|
1100 | is therefore something like this:
|
---|
1101 |
|
---|
1102 | <ol>
|
---|
1103 | <li>Call this method (IVirtualBox::createMachine) to have a new
|
---|
1104 | machine created. The machine object returned is "mutable", i.e.
|
---|
1105 | automatically locked for the current session, as if
|
---|
1106 | <link to="#openSession" /> had been called on it.</li>
|
---|
1107 |
|
---|
1108 | <li>Assign meaningful settings to the new machine by calling the
|
---|
1109 | respective methods.</li>
|
---|
1110 |
|
---|
1111 | <li>Call <link to="IMachine::saveSettings" /> to have the settings written
|
---|
1112 | to the machine's XML settings file. The configuration of the newly
|
---|
1113 | created machine will not be saved to disk (and the settings subfolder
|
---|
1114 | and file, as described below, will not be created) until this method
|
---|
1115 | is called.</li>
|
---|
1116 |
|
---|
1117 | <li>Call <link to="#registerMachine" /> to have the
|
---|
1118 | machine show up in the list of machines registered with VirtualBox.</li>
|
---|
1119 | </ol>
|
---|
1120 |
|
---|
1121 | Every machine has a <i>settings file</i> that is used to store
|
---|
1122 | the machine configuration. This file is stored in the directory
|
---|
1123 | called <i>machine settings subfolder</i>. Unless specified otherwise,
|
---|
1124 | both the subfolder and the settings file will have a name that
|
---|
1125 | corresponds to the name of the virtual machine. You can specify
|
---|
1126 | where to create the machine settings subfolder using the @a
|
---|
1127 | baseFolder argument. The base folder can be absolute (full path)
|
---|
1128 | or relative to the <link to="IVirtualBox::homeFolder">
|
---|
1129 | VirtualBox home directory</link>.
|
---|
1130 |
|
---|
1131 | If a null or empty string is given as the base folder (which is
|
---|
1132 | recommended), the <link to="ISystemProperties::defaultMachineFolder">
|
---|
1133 | default machine settings folder</link> will be used as the base
|
---|
1134 | folder to create the machine settings subfolder and file. In
|
---|
1135 | any case, the full path to the settings file will look like:
|
---|
1136 | <pre>
|
---|
1137 | <base_folder>/<machine_name>/<machine_name>.xml
|
---|
1138 | </pre>
|
---|
1139 |
|
---|
1140 | Optionally the UUID of the machine can be predefined. If this is
|
---|
1141 | not desired (i.e. a new UUID should be generated), pass just an
|
---|
1142 | empty or null UUID.
|
---|
1143 |
|
---|
1144 | You should also specify a valid name for the machine.
|
---|
1145 | See the <link to="IMachine::name"/> property
|
---|
1146 | description for more details about the machine name.
|
---|
1147 |
|
---|
1148 | The created machine remains
|
---|
1149 | unregistered until you call <link to="#registerMachine()"/>.
|
---|
1150 |
|
---|
1151 | <note>
|
---|
1152 | There is no way to change the name of the settings file or
|
---|
1153 | subfolder of the created machine directly.
|
---|
1154 | </note>
|
---|
1155 | </desc>
|
---|
1156 | <param name="baseFolder" type="wstring" dir="in">
|
---|
1157 | <desc>
|
---|
1158 | Name of the folder where to create the machine settings
|
---|
1159 | subfolder containing the settings file.
|
---|
1160 | </desc>
|
---|
1161 | </param>
|
---|
1162 | <param name="name" type="wstring" dir="in">
|
---|
1163 | <desc>Machine name.</desc>
|
---|
1164 | </param>
|
---|
1165 | <param name="id" type="uuid" dir="in">
|
---|
1166 | <desc>
|
---|
1167 | UUID of the newly created VM, when non-null or non-empty.
|
---|
1168 | Otherwise a UUID is automatically generated.
|
---|
1169 | </desc>
|
---|
1170 | </param>
|
---|
1171 | <param name="machine" type="IMachine" dir="return">
|
---|
1172 | <desc>Created machine object.</desc>
|
---|
1173 | </param>
|
---|
1174 | </method>
|
---|
1175 |
|
---|
1176 | <method name="createLegacyMachine">
|
---|
1177 | <desc>
|
---|
1178 | Creates a new virtual machine in "legacy" mode, using the
|
---|
1179 | specified settings file to store machine settings.
|
---|
1180 |
|
---|
1181 | As opposed to machines created by <link to="#createMachine()"/>,
|
---|
1182 | the settings file of the machine created in "legacy" mode
|
---|
1183 | is not automatically renamed when the machine name is
|
---|
1184 | changed -- it will always remain the same as specified in this
|
---|
1185 | method call.
|
---|
1186 |
|
---|
1187 | The specified settings file name can be absolute
|
---|
1188 | (full path) or relative to the <link to="IVirtualBox::homeFolder">
|
---|
1189 | VirtualBox home directory</link>. If the file name doesn't
|
---|
1190 | contain an extension, the default extension (.xml) will be
|
---|
1191 | appended.
|
---|
1192 |
|
---|
1193 | Optionally the UUID of the machine can be predefined. If this is
|
---|
1194 | not desired (i.e. a new UUID should be generated), pass just an
|
---|
1195 | empty or null UUID.
|
---|
1196 |
|
---|
1197 | Note that the configuration of the newly created machine is not
|
---|
1198 | saved to disk (and therefore no settings file is created)
|
---|
1199 | until <link to="IMachine::saveSettings()"/> is called. If the
|
---|
1200 | specified settings file already exists,
|
---|
1201 | <link to="IMachine::saveSettings()"/> will return an error.
|
---|
1202 |
|
---|
1203 | You should also specify a valid name for the machine.
|
---|
1204 | See the <link to="IMachine::name"/> property
|
---|
1205 | description for more details about the machine name.
|
---|
1206 |
|
---|
1207 | The created machine remains
|
---|
1208 | unregistered until you call <link to="#registerMachine()"/>.
|
---|
1209 |
|
---|
1210 | @deprecated This method may be removed later. It is better
|
---|
1211 | to use <link to="IVirtualBox::createMachine()"/>.
|
---|
1212 |
|
---|
1213 | <note>
|
---|
1214 | There is no way to change the name of the settings file
|
---|
1215 | of the created machine.
|
---|
1216 | </note>
|
---|
1217 | </desc>
|
---|
1218 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1219 | <desc>
|
---|
1220 | Name of the file where to store machine settings.
|
---|
1221 | </desc>
|
---|
1222 | </param>
|
---|
1223 | <param name="name" type="wstring" dir="in">
|
---|
1224 | <desc>Machine name.</desc>
|
---|
1225 | </param>
|
---|
1226 | <param name="id" type="uuid" dir="in">
|
---|
1227 | <desc>
|
---|
1228 | UUID of the newly created VM, when non-null or non-empty.
|
---|
1229 | Otherwise a UUID is automatically generated.
|
---|
1230 | </desc>
|
---|
1231 | </param>
|
---|
1232 | <param name="machine" type="IMachine" dir="return">
|
---|
1233 | <desc>Created machine object.</desc>
|
---|
1234 | </param>
|
---|
1235 | </method>
|
---|
1236 |
|
---|
1237 | <method name="openMachine">
|
---|
1238 | <desc>
|
---|
1239 | Opens a virtual machine from the existing settings file.
|
---|
1240 | The opened machine remains unregistered until you call
|
---|
1241 | <link to="#registerMachine()"/>.
|
---|
1242 |
|
---|
1243 | The specified settings file name can be absolute
|
---|
1244 | (full path) or relative to the <link to="IVirtualBox::homeFolder">
|
---|
1245 | VirtualBox home directory</link>. This file must exist
|
---|
1246 | and must be a valid machine settings file whose contents
|
---|
1247 | will be used to construct the machine object.
|
---|
1248 |
|
---|
1249 | @deprecated Will be removed soon.
|
---|
1250 | </desc>
|
---|
1251 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1252 | <desc>
|
---|
1253 | Name of the machine settings file.
|
---|
1254 | </desc>
|
---|
1255 | </param>
|
---|
1256 | <param name="machine" type="IMachine" dir="return">
|
---|
1257 | <desc>Opened machine object.</desc>
|
---|
1258 | </param>
|
---|
1259 | <note>
|
---|
1260 | <link to="IMachine::settingsModified"/> will return
|
---|
1261 | false for the created machine, until any of machine settigs
|
---|
1262 | are changed.
|
---|
1263 | </note>
|
---|
1264 | </method>
|
---|
1265 |
|
---|
1266 | <method name="registerMachine">
|
---|
1267 | <desc>
|
---|
1268 |
|
---|
1269 | Registers the machine previously created using
|
---|
1270 | <link to="#createMachine()"/> or opened using
|
---|
1271 | <link to="#openMachine()"/> within this VirtualBox installation. After
|
---|
1272 | successful method invocation, the
|
---|
1273 | <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
|
---|
1274 | to all registered callbacks.
|
---|
1275 |
|
---|
1276 | <note>
|
---|
1277 | This method implicitly calls <link to="IMachine::saveSettings"/>
|
---|
1278 | to save all current machine settings before registering it.
|
---|
1279 | </note>
|
---|
1280 |
|
---|
1281 | </desc>
|
---|
1282 | <param name="machine" type="IMachine" dir="in"/>
|
---|
1283 | </method>
|
---|
1284 |
|
---|
1285 | <method name="getMachine">
|
---|
1286 | <desc>
|
---|
1287 | Attempts to find a virtual machine given its UUID.
|
---|
1288 | To look up a machine by name, use <link to="IVirtualBox::findMachine" /> instead.
|
---|
1289 | </desc>
|
---|
1290 | <param name="id" type="uuid" dir="in"/>
|
---|
1291 | <param name="machine" type="IMachine" dir="return"/>
|
---|
1292 | </method>
|
---|
1293 |
|
---|
1294 | <method name="findMachine">
|
---|
1295 | <desc>
|
---|
1296 | Attempts to find a virtual machine given its name.
|
---|
1297 | To look up a machine by UUID, use <link to="IVirtualBox::getMachine" /> instead.
|
---|
1298 | </desc>
|
---|
1299 | <param name="name" type="wstring" dir="in"/>
|
---|
1300 | <param name="machine" type="IMachine" dir="return"/>
|
---|
1301 | </method>
|
---|
1302 |
|
---|
1303 | <method name="unregisterMachine">
|
---|
1304 | <desc>
|
---|
1305 |
|
---|
1306 | Unregisters the machine previously registered using
|
---|
1307 | <link to="#registerMachine"/>. After successful method invocation, the
|
---|
1308 | <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
|
---|
1309 | to all registered callbacks.
|
---|
1310 |
|
---|
1311 | <note>
|
---|
1312 | The specified machine must not be in the Saved state, have an open
|
---|
1313 | (or a spawning) direct session associated with it, have snapshots or
|
---|
1314 | have hard disks attached.
|
---|
1315 | </note>
|
---|
1316 |
|
---|
1317 | <note>
|
---|
1318 | This method implicitly calls <link to="IMachine::saveSettings"/> to
|
---|
1319 | save all current machine settings before unregistering it.
|
---|
1320 | </note>
|
---|
1321 |
|
---|
1322 | <note>
|
---|
1323 | If the given machine is inaccessible (see
|
---|
1324 | <link to="IMachine::accessible"/>), it will be unregistered and
|
---|
1325 | fully uninitialized right afterwards. As a result, the returned
|
---|
1326 | machine object will be unusable and an attempt to call
|
---|
1327 | <b>any</b> method will return the "Object not ready" error.
|
---|
1328 | </note>
|
---|
1329 |
|
---|
1330 | </desc>
|
---|
1331 | <param name="id" type="uuid" dir="in">
|
---|
1332 | <desc>UUID of the machine to unregister.</desc>
|
---|
1333 | </param>
|
---|
1334 | <param name="machine" type="IMachine" dir="return">
|
---|
1335 | <desc>Unregistered machine object.</desc>
|
---|
1336 | </param>
|
---|
1337 | </method>
|
---|
1338 |
|
---|
1339 | <method name="createHardDisk">
|
---|
1340 | <desc>
|
---|
1341 |
|
---|
1342 | Creates a new unregistered hard disk that will use the given
|
---|
1343 | storage type.
|
---|
1344 |
|
---|
1345 | Most properties of the created hard disk object are
|
---|
1346 | uninitialized. Valid values must be assigned to them (and probalby
|
---|
1347 | some actions performed) to make the actual usage of this hard disk
|
---|
1348 | (<link to="#registerHardDisk()">register</link>, attach to a virtual
|
---|
1349 | machine, etc.). See the description of <link to="IHardDisk"/> and
|
---|
1350 | descriptions of storage type specific interfaces for more information.
|
---|
1351 |
|
---|
1352 | <note>
|
---|
1353 | For hard disks using
|
---|
1354 | the <link
|
---|
1355 | to="HardDiskStorageType::VirtualDiskImage">VirtualDiskImage</link>
|
---|
1356 | storage type, an image file is not actually created until you call
|
---|
1357 | <link to="IVirtualDiskImage::createDynamicImage()"/> or
|
---|
1358 | <link to="IVirtualDiskImage::createFixedImage()"/>.
|
---|
1359 | </note>
|
---|
1360 |
|
---|
1361 | </desc>
|
---|
1362 |
|
---|
1363 | <param name="storageType" type="HardDiskStorageType" dir="in">
|
---|
1364 | <desc>Storage type of the hard disk image to create.</desc>
|
---|
1365 | </param>
|
---|
1366 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1367 | <desc>Created hard disk object of the given storage type.</desc>
|
---|
1368 | </param>
|
---|
1369 |
|
---|
1370 | </method>
|
---|
1371 |
|
---|
1372 | <method name="openHardDisk">
|
---|
1373 | <desc>
|
---|
1374 |
|
---|
1375 | Opens a hard disk from an existing location.
|
---|
1376 |
|
---|
1377 | This method tries to guess the
|
---|
1378 | <link to="HardDiskStorageType">hard disk storage type</link> from the
|
---|
1379 | format of the location string and from the contents of the resource the
|
---|
1380 | location points to. Currently, a <i>file path</i> is the only
|
---|
1381 | supported format for the location string which must point to either a
|
---|
1382 | VDI file or to a VMDK file. On success, an IHardDisk object will be
|
---|
1383 | returned that also implements the corresponding interface
|
---|
1384 | (IVirtualDiskImage or IVMDKImage, respectively). The
|
---|
1385 | <link to="IHardDisk::storageType"/> property may also be used to
|
---|
1386 | determine the storage type of the returned object (instead of trying
|
---|
1387 | to query one of these interfaces).
|
---|
1388 |
|
---|
1389 | <note>
|
---|
1390 | The specified file path can be absolute (full path) or relative to
|
---|
1391 | the <link to="IVirtualBox::homeFolder">VirtualBox home
|
---|
1392 | directory</link>. If only a file name without any path is given,
|
---|
1393 | the <link to="ISystemProperties::defaultVDIFolder"> default VDI
|
---|
1394 | folder</link> will be used as a path to the image file.
|
---|
1395 | </note>
|
---|
1396 |
|
---|
1397 | The opened hard disk remains unregistered
|
---|
1398 | until <link to="#registerHardDisk()"/> is called.
|
---|
1399 |
|
---|
1400 | </desc>
|
---|
1401 |
|
---|
1402 | <param name="location" type="wstring" dir="in">
|
---|
1403 | <desc>
|
---|
1404 | Location of the resource that contains a valid hard disk.
|
---|
1405 | </desc>
|
---|
1406 | </param>
|
---|
1407 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1408 | <desc>Opened hard disk object.</desc>
|
---|
1409 | </param>
|
---|
1410 | </method>
|
---|
1411 |
|
---|
1412 | <method name="openVirtualDiskImage">
|
---|
1413 | <desc>
|
---|
1414 |
|
---|
1415 | Opens a hard disk from an existing Virtual Disk Image file.
|
---|
1416 | The opened hard disk remains unregistered
|
---|
1417 | until <link to="#registerHardDisk()"/> is called.
|
---|
1418 |
|
---|
1419 | @deprecated Use <link to="IVirtualBox::openHardDisk()"/> instead.
|
---|
1420 |
|
---|
1421 | <note>Opening differencing images is not supported.</note>
|
---|
1422 |
|
---|
1423 | <note>The specified file path can be absolute (full path) or
|
---|
1424 | relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
|
---|
1425 | home directory</link>. If only a file name without any path is
|
---|
1426 | given, the <link to="ISystemProperties::defaultVDIFolder">
|
---|
1427 | default VDI folder</link> will be used as a path to the image
|
---|
1428 | file.</note>
|
---|
1429 |
|
---|
1430 | </desc>
|
---|
1431 |
|
---|
1432 | <param name="filePath" type="wstring" dir="in">
|
---|
1433 | <desc>
|
---|
1434 | Name of the file that contains a valid Virtual Disk Image.
|
---|
1435 | </desc>
|
---|
1436 | </param>
|
---|
1437 | <param name="image" type="IVirtualDiskImage" dir="return">
|
---|
1438 | <desc>Opened hard disk object.</desc>
|
---|
1439 | </param>
|
---|
1440 | </method>
|
---|
1441 |
|
---|
1442 | <method name="registerHardDisk">
|
---|
1443 | <desc>
|
---|
1444 |
|
---|
1445 | Registers the given hard disk within this VirtualBox
|
---|
1446 | installation. The hard disk must not be registered, must be
|
---|
1447 | <link to="IHardDisk::accessible"/> and must not be a
|
---|
1448 | differencing hard disk, otherwise the registration will fail.
|
---|
1449 |
|
---|
1450 | </desc>
|
---|
1451 | <param name="hardDisk" type="IHardDisk" dir="in">
|
---|
1452 | <desc>Hard disk object to register.</desc>
|
---|
1453 | </param>
|
---|
1454 | </method>
|
---|
1455 |
|
---|
1456 | <method name="getHardDisk" const="yes">
|
---|
1457 | <desc>
|
---|
1458 | Returns the registered hard disk with the given UUID.
|
---|
1459 | </desc>
|
---|
1460 | <param name="id" type="uuid" dir="in">
|
---|
1461 | <desc>UUID of the hard disk to look for.</desc>
|
---|
1462 | </param>
|
---|
1463 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1464 | <desc>Found hard disk object.</desc>
|
---|
1465 | </param>
|
---|
1466 | </method>
|
---|
1467 |
|
---|
1468 | <method name="findHardDisk">
|
---|
1469 | <desc>
|
---|
1470 |
|
---|
1471 | Returns a registered hard disk that uses the given location to
|
---|
1472 | store data. The search is done by comparing the
|
---|
1473 | value of the @a location argument to the
|
---|
1474 | <link to="IHardDisk::location"/> attribute of each registered
|
---|
1475 | hard disk.
|
---|
1476 |
|
---|
1477 | For locations repesented by file paths (such as VDI and VMDK
|
---|
1478 | images), the specified location can be either an absolute file
|
---|
1479 | path or a path relative to
|
---|
1480 | the <link to="IVirtualBox::homeFolder"> VirtualBox home
|
---|
1481 | directory</link>. If only a file name without any path is
|
---|
1482 | given, the <link to="ISystemProperties::defaultVDIFolder">
|
---|
1483 | default VDI folder</link> will be used as a path to construct
|
---|
1484 | the absolute image file name to search for. Note that on host
|
---|
1485 | systems with case sensitive filesystems, a case sensitive
|
---|
1486 | comparison is performed, otherwise the case of symbols in the
|
---|
1487 | file path is ignored.
|
---|
1488 |
|
---|
1489 | </desc>
|
---|
1490 | <param name="location" type="wstring" dir="in">
|
---|
1491 | <desc>Hard disk location specification to search for.</desc>
|
---|
1492 | </param>
|
---|
1493 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1494 | <desc>Found hard disk object.</desc>
|
---|
1495 | </param>
|
---|
1496 | </method>
|
---|
1497 |
|
---|
1498 | <method name="findVirtualDiskImage">
|
---|
1499 | <desc>
|
---|
1500 |
|
---|
1501 | Returns a registered hard disk that uses the given image file.
|
---|
1502 |
|
---|
1503 | @deprecated Use <link to="IVirtualBox::findHardDisk()"/> instead.
|
---|
1504 |
|
---|
1505 | <note>The specified file path can be absolute (full path) or
|
---|
1506 | relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
|
---|
1507 | home directory</link>. If only a file name without any path is
|
---|
1508 | given, the <link to="ISystemProperties::defaultVDIFolder">
|
---|
1509 | default VDI folder</link> will be used as a path to the image
|
---|
1510 | file.</note>
|
---|
1511 |
|
---|
1512 | <note>On host systems with case sensitive filesystems, a case
|
---|
1513 | sensitive comparison is performed, otherwise the case of symbols
|
---|
1514 | in the file path is ignored.</note>
|
---|
1515 |
|
---|
1516 | </desc>
|
---|
1517 | <param name="filePath" type="wstring" dir="in">
|
---|
1518 | <desc>Virtual Disk Image file path to look for.</desc>
|
---|
1519 | </param>
|
---|
1520 | <param name="image" type="IVirtualDiskImage" dir="return">
|
---|
1521 | <desc>Found hard disk object.</desc>
|
---|
1522 | </param>
|
---|
1523 | </method>
|
---|
1524 |
|
---|
1525 | <method name="unregisterHardDisk">
|
---|
1526 | <desc>
|
---|
1527 | Unregisters a hard disk previously registered using
|
---|
1528 | <link to="#registerHardDisk()"/>.
|
---|
1529 | <note>
|
---|
1530 | The specified hard disk must not be attached to any of
|
---|
1531 | the existing virtual machines and must not have children
|
---|
1532 | (differencing) hard disks.
|
---|
1533 | </note>
|
---|
1534 | </desc>
|
---|
1535 | <param name="id" type="uuid" dir="in">
|
---|
1536 | <desc>UUID of the hard disk to unregister.</desc>
|
---|
1537 | </param>
|
---|
1538 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1539 | <desc>Unregistered hard disk object.</desc>
|
---|
1540 | </param>
|
---|
1541 | </method>
|
---|
1542 |
|
---|
1543 | <method name="openDVDImage">
|
---|
1544 | <desc>
|
---|
1545 | Opens the CD/DVD image contained in the specified file of
|
---|
1546 | the supported format and assigns it the given UUID. The opened
|
---|
1547 | image remains unregistered
|
---|
1548 | until <link to="#registerDVDImage()"/> is called.
|
---|
1549 | </desc>
|
---|
1550 | <param name="filePath" type="wstring" dir="in">
|
---|
1551 | <desc>
|
---|
1552 | Full name of the file that contains a valid
|
---|
1553 | CD/DVD image. Currently, only ISO images are supported.
|
---|
1554 | <note>
|
---|
1555 | The specified file name can be absolute or relative
|
---|
1556 | to the <link to="IVirtualBox::homeFolder">
|
---|
1557 | VirtualBox home directory</link>.
|
---|
1558 | </note>
|
---|
1559 | </desc>
|
---|
1560 | </param>
|
---|
1561 | <param name="id" type="uuid" dir="in">
|
---|
1562 | <desc>
|
---|
1563 | UUID to assign to the given image file within this
|
---|
1564 | VirtualBox installation. If an empty (null) UUID is
|
---|
1565 | specified, the system will randomly generate an UUID.
|
---|
1566 | </desc>
|
---|
1567 | </param>
|
---|
1568 | <param name="image" type="IDVDImage" dir="return">
|
---|
1569 | <desc>Opened CD/DVD image object.</desc>
|
---|
1570 | </param>
|
---|
1571 | </method>
|
---|
1572 |
|
---|
1573 | <method name="registerDVDImage">
|
---|
1574 | <desc>
|
---|
1575 | Registers a CD/DVD image within this VirtualBox
|
---|
1576 | installation. The image must not be registered and must not
|
---|
1577 | be associated with the same image file as any of the already
|
---|
1578 | registered images, otherwise the registration will fail.
|
---|
1579 | </desc>
|
---|
1580 | <param name="image" type="IDVDImage" dir="in">
|
---|
1581 | <desc>CD/DVD image object to register.</desc>
|
---|
1582 | </param>
|
---|
1583 | </method>
|
---|
1584 |
|
---|
1585 | <method name="getDVDImage">
|
---|
1586 | <desc>
|
---|
1587 | Returns a registered CD/DVD image with the given UUID.
|
---|
1588 | </desc>
|
---|
1589 | <param name="id" type="uuid" dir="in">
|
---|
1590 | <desc>UUID of the image to look for.</desc>
|
---|
1591 | </param>
|
---|
1592 | <param name="image" type="IDVDImage" dir="return">
|
---|
1593 | <desc>Found CD/DVD image object.</desc>
|
---|
1594 | </param>
|
---|
1595 | </method>
|
---|
1596 |
|
---|
1597 | <method name="findDVDImage">
|
---|
1598 | <desc>
|
---|
1599 | Returns a registered CD/DVD image with the given image file.
|
---|
1600 | <note>
|
---|
1601 | On host systems with case sensitive filesystems, a case
|
---|
1602 | sensitive comparison is performed, otherwise the case of
|
---|
1603 | symbols in the file path is ignored.
|
---|
1604 | </note>
|
---|
1605 | </desc>
|
---|
1606 | <param name="filePath" type="wstring" dir="in">
|
---|
1607 | <desc>CD/DVD image file path to look for.</desc>
|
---|
1608 | </param>
|
---|
1609 | <param name="image" type="IDVDImage" dir="return">
|
---|
1610 | <desc>Found CD/DVD image object.</desc>
|
---|
1611 | </param>
|
---|
1612 | </method>
|
---|
1613 |
|
---|
1614 | <method name="getDVDImageUsage">
|
---|
1615 | <desc>
|
---|
1616 | Returns the list of of UUIDs of all virtual machines that use
|
---|
1617 | the given CD/DVD image.
|
---|
1618 | </desc>
|
---|
1619 | <param name="id" type="uuid" dir="in">
|
---|
1620 | <desc>UUID of the image to get the usage information for.</desc>
|
---|
1621 | </param>
|
---|
1622 | <param name="usage" type="ResourceUsage" dir="in">
|
---|
1623 | <desc>Type of the usage (permanent, temporary or all).</desc>
|
---|
1624 | </param>
|
---|
1625 | <param name="machineIDs" type="wstring" dir="return">
|
---|
1626 | <desc>
|
---|
1627 | List of UUIDs of all machines that use the given image
|
---|
1628 | in the way specified by the usage parameter.
|
---|
1629 | The list is returned as a string containing UUIDs separated
|
---|
1630 | by spaces. A null string means that the image is not used.
|
---|
1631 | <note>
|
---|
1632 | When the usage type is <link to="ResourceUsage::All"/> and the image
|
---|
1633 | is used by the VM both permanently and temporarily, the VM's UUID
|
---|
1634 | will be present only once in the list.
|
---|
1635 | </note>
|
---|
1636 | </desc>
|
---|
1637 | </param>
|
---|
1638 | </method>
|
---|
1639 |
|
---|
1640 | <method name="unregisterDVDImage">
|
---|
1641 | <desc>
|
---|
1642 | Unregisters the CD/DVD image previously registered using
|
---|
1643 | <link to="#registerDVDImage()"/>.
|
---|
1644 | <note>
|
---|
1645 | The specified image must not be mounted to any of
|
---|
1646 | the existing virtual machines.
|
---|
1647 | </note>
|
---|
1648 | </desc>
|
---|
1649 | <param name="id" type="uuid" dir="in">
|
---|
1650 | <desc>UUID of the CD/DVD image to unregister.</desc>
|
---|
1651 | </param>
|
---|
1652 | <param name="image" type="IDVDImage" dir="return">
|
---|
1653 | <desc>Unregistered image object.</desc>
|
---|
1654 | </param>
|
---|
1655 | </method>
|
---|
1656 |
|
---|
1657 | <method name="openFloppyImage">
|
---|
1658 | <desc>
|
---|
1659 | Opens a floppy image contained in the specified file of
|
---|
1660 | the supported format and assigns it the given UUID. The opened
|
---|
1661 | image remains unregistered
|
---|
1662 | until <link to="#registerFloppyImage()"/> is called.
|
---|
1663 | </desc>
|
---|
1664 | <param name="filePath" type="wstring" dir="in">
|
---|
1665 | <desc>
|
---|
1666 | Full name of the file that contains a valid
|
---|
1667 | floppy image.
|
---|
1668 | <note>
|
---|
1669 | The specified file name can be absolute or relative
|
---|
1670 | to the <link to="IVirtualBox::homeFolder">
|
---|
1671 | VirtualBox home directory</link>.
|
---|
1672 | </note>
|
---|
1673 | </desc>
|
---|
1674 | </param>
|
---|
1675 | <param name="id" type="uuid" dir="in">
|
---|
1676 | <desc>
|
---|
1677 | UUID to assign to the given image file within this
|
---|
1678 | VirtualBox installation. If an empty (null) UUID is
|
---|
1679 | specified, the system will randomly generate an UUID.
|
---|
1680 | </desc>
|
---|
1681 | </param>
|
---|
1682 | <param name="image" type="IFloppyImage" dir="return">
|
---|
1683 | <desc>Opened CD/DVD image object.</desc>
|
---|
1684 | </param>
|
---|
1685 | </method>
|
---|
1686 |
|
---|
1687 | <method name="registerFloppyImage">
|
---|
1688 | <desc>
|
---|
1689 | Registers a floppy image within this VirtualBox
|
---|
1690 | installation. The image must not be registered and must not
|
---|
1691 | be associated with the same image file as any of the already
|
---|
1692 | registered images, otherwise the registration will fail.
|
---|
1693 | </desc>
|
---|
1694 | <param name="image" type="IFloppyImage" dir="in">
|
---|
1695 | <desc>Floppy image object to register.</desc>
|
---|
1696 | </param>
|
---|
1697 | </method>
|
---|
1698 |
|
---|
1699 | <method name="getFloppyImage">
|
---|
1700 | <desc>
|
---|
1701 | Returns a registered floppy image with the given UUID.
|
---|
1702 | </desc>
|
---|
1703 | <param name="id" type="uuid" dir="in">
|
---|
1704 | <desc>UUID of the image to look for.</desc>
|
---|
1705 | </param>
|
---|
1706 | <param name="image" type="IFloppyImage" dir="return">
|
---|
1707 | <desc>Found floppy image object.</desc>
|
---|
1708 | </param>
|
---|
1709 | </method>
|
---|
1710 |
|
---|
1711 | <method name="findFloppyImage">
|
---|
1712 | <desc>
|
---|
1713 | Returns a registered floppy image with the given image file.
|
---|
1714 | <note>
|
---|
1715 | On host systems with case sensitive filesystems, a case
|
---|
1716 | sensitive comparison is performed, otherwise the case of
|
---|
1717 | symbols in the file path is ignored.
|
---|
1718 | </note>
|
---|
1719 | </desc>
|
---|
1720 | <param name="filePath" type="wstring" dir="in">
|
---|
1721 | <desc>Floppy image file path to look for.</desc>
|
---|
1722 | </param>
|
---|
1723 | <param name="image" type="IFloppyImage" dir="return">
|
---|
1724 | <desc>Found floppy image object.</desc>
|
---|
1725 | </param>
|
---|
1726 | </method>
|
---|
1727 |
|
---|
1728 | <method name="getFloppyImageUsage">
|
---|
1729 | <desc>
|
---|
1730 | Returns the list of of UUIDs of all virtual machines that use
|
---|
1731 | the given floppy image.
|
---|
1732 | </desc>
|
---|
1733 | <param name="id" type="uuid" dir="in">
|
---|
1734 | <desc>UUID of the image to get the usage information for.</desc>
|
---|
1735 | </param>
|
---|
1736 | <param name="usage" type="ResourceUsage" dir="in">
|
---|
1737 | <desc>Type of the usage (permanent, temporary or all).</desc>
|
---|
1738 | </param>
|
---|
1739 | <param name="machineIDs" type="wstring" dir="return">
|
---|
1740 | <desc>
|
---|
1741 | List of UUIDs of all machines that use the given image
|
---|
1742 | in the way specified by the usage parameter.
|
---|
1743 | The list is returned as a string containing UUIDs separated
|
---|
1744 | by spaces. A null string means that the image is not used.
|
---|
1745 | <note>
|
---|
1746 | When the usage type is <link to="ResourceUsage::All"/> and the image
|
---|
1747 | is used by the VM both permanently and temporarily, the VM's UUID
|
---|
1748 | will be present only once in the list.
|
---|
1749 | </note>
|
---|
1750 | </desc>
|
---|
1751 | </param>
|
---|
1752 | </method>
|
---|
1753 |
|
---|
1754 | <method name="unregisterFloppyImage">
|
---|
1755 | <desc>
|
---|
1756 | Unregisters the floppy image previously registered using
|
---|
1757 | <link to="#registerFloppyImage()"/>.
|
---|
1758 | <note>
|
---|
1759 | The specified image must not be mounted to any of
|
---|
1760 | the existing virtual machines.
|
---|
1761 | </note>
|
---|
1762 | </desc>
|
---|
1763 | <param name="id" type="uuid" dir="in">
|
---|
1764 | <desc>UUID of the floppy image to unregister.</desc>
|
---|
1765 | </param>
|
---|
1766 | <param name="image" type="IFloppyImage" dir="return">
|
---|
1767 | <desc>Unregistered image object.</desc>
|
---|
1768 | </param>
|
---|
1769 | </method>
|
---|
1770 |
|
---|
1771 | <method name="getGuestOSType">
|
---|
1772 | <desc>
|
---|
1773 | Returns an object describing the specified guest OS type.
|
---|
1774 |
|
---|
1775 | The requested guest OS type is specified using a string which is a
|
---|
1776 | mnemonic identifier of the guest operating system, such as
|
---|
1777 | <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
|
---|
1778 | particular virtual machine can be read or set using the
|
---|
1779 | <link to="IMachine::OSTypeId"/> attribute.
|
---|
1780 |
|
---|
1781 | The <link to="IVirtualBox::guestOSTypes"/> collection contains all
|
---|
1782 | available guest OS type objects. Each object has an
|
---|
1783 | <link to="IGuestOSType::id"/> attribute which contains an identifier of
|
---|
1784 | the guest OS this object describes.
|
---|
1785 | </desc>
|
---|
1786 | <param name="id" type="wstring" dir="in">
|
---|
1787 | <desc>Guest OS type ID string.</desc>
|
---|
1788 | </param>
|
---|
1789 | <param name="type" type="IGuestOSType" dir="return">
|
---|
1790 | <desc>Guest OS type object.</desc>
|
---|
1791 | </param>
|
---|
1792 | </method>
|
---|
1793 |
|
---|
1794 | <method name="createSharedFolder">
|
---|
1795 | <desc>
|
---|
1796 | Creates a new global shared folder by associating the given logical
|
---|
1797 | name with the given host path, adds it to the collection of shared
|
---|
1798 | folders and starts sharing it. Refer to the description of
|
---|
1799 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
1800 | </desc>
|
---|
1801 | <param name="name" type="wstring" dir="in">
|
---|
1802 | <desc>Unique logical name of the shared folder.</desc>
|
---|
1803 | </param>
|
---|
1804 | <param name="hostPath" type="wstring" dir="in">
|
---|
1805 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
1806 | </param>
|
---|
1807 | <param name="writable" type="boolean" dir="in">
|
---|
1808 | <desc>Whether the share is writable or readonly</desc>
|
---|
1809 | </param>
|
---|
1810 | </method>
|
---|
1811 |
|
---|
1812 | <method name="removeSharedFolder">
|
---|
1813 | <desc>
|
---|
1814 | Removes the global shared folder with the given name previously
|
---|
1815 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
1816 | shared folders and stops sharing it.
|
---|
1817 | </desc>
|
---|
1818 | <param name="name" type="wstring" dir="in">
|
---|
1819 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
1820 | </param>
|
---|
1821 | </method>
|
---|
1822 |
|
---|
1823 | <method name="getNextExtraDataKey">
|
---|
1824 | <desc>
|
---|
1825 | Returns the global extra data key name following the supplied key.
|
---|
1826 |
|
---|
1827 | An error is returned if the supplied @a key does not exist. @c NULL is
|
---|
1828 | returned in @a nextKey if the supplied key is the last key. When
|
---|
1829 | supplying @c NULL for the @a key, the first key item is returned in @a
|
---|
1830 | nextKey (if there is any). @a nextValue is an optional parameter and
|
---|
1831 | if supplied, the next key's value is returned in it.
|
---|
1832 | </desc>
|
---|
1833 | <param name="key" type="wstring" dir="in">
|
---|
1834 | <desc>Name of the data key to follow.</desc>
|
---|
1835 | </param>
|
---|
1836 | <param name="nextKey" type="wstring" dir="out">
|
---|
1837 | <desc>Name of the next data key.</desc>
|
---|
1838 | </param>
|
---|
1839 | <param name="nextValue" type="wstring" dir="out">
|
---|
1840 | <desc>Value of the next data key.</desc>
|
---|
1841 | </param>
|
---|
1842 | </method>
|
---|
1843 |
|
---|
1844 | <method name="getExtraData">
|
---|
1845 | <desc>
|
---|
1846 | Returns associated global extra data.
|
---|
1847 |
|
---|
1848 | If the requested data @a key does not exist, this function will
|
---|
1849 | succeed and return @c NULL in the @a value argument.
|
---|
1850 | </desc>
|
---|
1851 | <param name="key" type="wstring" dir="in">
|
---|
1852 | <desc>Name of the data key to get.</desc>
|
---|
1853 | </param>
|
---|
1854 | <param name="value" type="wstring" dir="return">
|
---|
1855 | <desc>Value of the requested data key.</desc>
|
---|
1856 | </param>
|
---|
1857 | </method>
|
---|
1858 |
|
---|
1859 | <method name="setExtraData">
|
---|
1860 | <desc>
|
---|
1861 | Sets associated global extra data.
|
---|
1862 |
|
---|
1863 | If you pass @c NULL as a key @a value, the given @a key will be
|
---|
1864 | deleted.
|
---|
1865 |
|
---|
1866 | <note>
|
---|
1867 | Before performing the actual data change, this method will ask all
|
---|
1868 | registered callbacks using the
|
---|
1869 | <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
|
---|
1870 | notification for a permission. If one of the callbacks refuses the
|
---|
1871 | new value, the change will not be performed.
|
---|
1872 | </note>
|
---|
1873 | <note>
|
---|
1874 | On success, the
|
---|
1875 | <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
|
---|
1876 | is called to inform all registered callbacks about a successful data
|
---|
1877 | change.
|
---|
1878 | </note>
|
---|
1879 | </desc>
|
---|
1880 | <param name="key" type="wstring" dir="in">
|
---|
1881 | <desc>Name of the data key to set.</desc>
|
---|
1882 | </param>
|
---|
1883 | <param name="value" type="wstring" dir="in">
|
---|
1884 | <desc>Value to assign to the key.</desc>
|
---|
1885 | </param>
|
---|
1886 | </method>
|
---|
1887 |
|
---|
1888 | <method name="openSession">
|
---|
1889 | <desc>
|
---|
1890 | Opens a new direct session with the given virtual machine.
|
---|
1891 |
|
---|
1892 | Within the direct session context, it is possible to change
|
---|
1893 | all VM settings, as well as to execute the VM in the process
|
---|
1894 | space of the session object. There can be only one direct
|
---|
1895 | session open at a time for every virtual machine. In VirtualBox
|
---|
1896 | terminology, the machine becomes "mutable" after a session has
|
---|
1897 | been opened.
|
---|
1898 |
|
---|
1899 | Upon successful return, the session object can be used to
|
---|
1900 | get access to the machine and to the VM console.
|
---|
1901 |
|
---|
1902 | Note that the "mutable" machine object, on which you may want
|
---|
1903 | to invoke IMachine methods to change its settings, will be a
|
---|
1904 | different object from the immutable IMachine objects returned
|
---|
1905 | by various IVirtualBox methods. To obtain a mutable
|
---|
1906 | IMachine object, upon which you can invoke settings methods,
|
---|
1907 | use the "machine" attribute of the ISession object which represents
|
---|
1908 | your open session.
|
---|
1909 |
|
---|
1910 | In other words, to change settings on a machine, the following
|
---|
1911 | sequence is typically performed:
|
---|
1912 |
|
---|
1913 | <ol>
|
---|
1914 | <li>Call this method (openSession) to have a machine locked for
|
---|
1915 | the current session.</li>
|
---|
1916 |
|
---|
1917 | <li>Obtain a mutable IMachine object from ISession::machine.</li>
|
---|
1918 |
|
---|
1919 | <li>Change the settings of the machine.</li>
|
---|
1920 |
|
---|
1921 | <li>Call IMachine::saveSettings.</li>
|
---|
1922 |
|
---|
1923 | <li>Close the session by calling <link to="#close" />.</li>
|
---|
1924 | </ol>
|
---|
1925 | </desc>
|
---|
1926 | <param name="session" type="ISession" dir="in">
|
---|
1927 | <desc>
|
---|
1928 | Session object that will represent the opened session after
|
---|
1929 | successful method invocation. This object must not represent
|
---|
1930 | the already open session.
|
---|
1931 | <note>
|
---|
1932 | This session will be automatically closed if the
|
---|
1933 | VirtualBox server is terminated for some reason.
|
---|
1934 | </note>
|
---|
1935 | </desc>
|
---|
1936 | </param>
|
---|
1937 | <param name="machineId" type="uuid" dir="in">
|
---|
1938 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
1939 | </param>
|
---|
1940 | </method>
|
---|
1941 |
|
---|
1942 | <method name="openRemoteSession">
|
---|
1943 | <desc>
|
---|
1944 | Opens a new remote session with the given virtual machine.
|
---|
1945 |
|
---|
1946 | Opening a remote session causes the VirtualBox server to start a new
|
---|
1947 | process that opens a direct session with the given VM. The remote
|
---|
1948 | session provides some level of control over the VM execution to the
|
---|
1949 | caller (using the IConsole interface); however, within the remote
|
---|
1950 | session context, not all VM settings are available for modification.
|
---|
1951 |
|
---|
1952 | This operation can take some time (a new VM is started in a new process,
|
---|
1953 | for which memory and other resources need to be set up, which can take
|
---|
1954 | a few seconds). Because of this, a progress object is returned to allow the
|
---|
1955 | caller to wait for this asynchronous operation to be completed. Until then,
|
---|
1956 | the remote session object remains in the closed state and accessing the
|
---|
1957 | machine or its console through it is invalid. It is recommended to use
|
---|
1958 | <link to="IProgress::waitForCompletion" /> or similar calls to wait for
|
---|
1959 | completion.
|
---|
1960 |
|
---|
1961 | Currently supported session types (values of the @a type
|
---|
1962 | argument) are:
|
---|
1963 | <ul>
|
---|
1964 | <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
|
---|
1965 | <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
|
---|
1966 | </ul>
|
---|
1967 |
|
---|
1968 | The @a environment argument is a string containing definitions of
|
---|
1969 | environment variables in the following format:
|
---|
1970 | @code
|
---|
1971 | NAME[=VALUE]\n
|
---|
1972 | NAME[=VALUE]\n
|
---|
1973 | ...
|
---|
1974 | @endcode
|
---|
1975 | where <tt>\\n</tt> is the new line character. These environment
|
---|
1976 | variables will be appended to the environment of the VirtualBox server
|
---|
1977 | process. If an environment variable exists both in the server process
|
---|
1978 | and in this list, the value from this list takes precedence over the
|
---|
1979 | server's variable. If the value of the environment variable is
|
---|
1980 | omitted, this variable will be removed from the resulting environment.
|
---|
1981 | If the environment string is @c null, the server environment is
|
---|
1982 | inherited by the started process as is.
|
---|
1983 |
|
---|
1984 | <note>
|
---|
1985 | It is an error to open a remote session with the machine
|
---|
1986 | that already has an open direct session or waits until the
|
---|
1987 | previous request to open the remote session is completed
|
---|
1988 | (see <link to="IMachine::sessionState"/>).
|
---|
1989 | </note>
|
---|
1990 |
|
---|
1991 | <note>
|
---|
1992 | The opened @a session will be automatically closed when
|
---|
1993 | the corresponding direct session dies or gets closed.
|
---|
1994 | </note>
|
---|
1995 |
|
---|
1996 | <see>openExistingSession</see>
|
---|
1997 | </desc>
|
---|
1998 | <param name="session" type="ISession" dir="in">
|
---|
1999 | <desc>
|
---|
2000 | Session object that will represent the opened remote session
|
---|
2001 | after successful method invocation (this object must not
|
---|
2002 | represent an already open session).
|
---|
2003 | </desc>
|
---|
2004 | </param>
|
---|
2005 | <param name="machineId" type="uuid" dir="in">
|
---|
2006 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
2007 | </param>
|
---|
2008 | <param name="type" type="wstring" dir="in">
|
---|
2009 | <desc>
|
---|
2010 | Type of the remote session (case sensitive).
|
---|
2011 | </desc>
|
---|
2012 | </param>
|
---|
2013 | <param name="environment" type="wstring" dir="in">
|
---|
2014 | <desc>
|
---|
2015 | Environment to pass to the opened session (may be @c null).
|
---|
2016 | </desc>
|
---|
2017 | </param>
|
---|
2018 | <param name="progress" type="IProgress" dir="return">
|
---|
2019 | <desc>Progress object to track the operation completion.</desc>
|
---|
2020 | </param>
|
---|
2021 | </method>
|
---|
2022 |
|
---|
2023 | <method name="openExistingSession">
|
---|
2024 | <desc>
|
---|
2025 | Opens a new remote session with the virtual machine for
|
---|
2026 | which a direct session is already open.
|
---|
2027 |
|
---|
2028 | The remote session provides some level of control over the VM
|
---|
2029 | execution (using the IConsole interface) to the caller; however,
|
---|
2030 | within the remote session context, not all VM settings are available
|
---|
2031 | for modification.
|
---|
2032 |
|
---|
2033 | As opposed to <link to="#openRemoteSession()"/>, the number of
|
---|
2034 | remote sessions opened this way is not limited by the API
|
---|
2035 |
|
---|
2036 | <note>
|
---|
2037 | It is an error to open a remote session with the machine that
|
---|
2038 | doesn't have an open direct session.
|
---|
2039 | </note>
|
---|
2040 |
|
---|
2041 | <see>openRemoteSession</see>
|
---|
2042 | </desc>
|
---|
2043 | <param name="session" type="ISession" dir="in">
|
---|
2044 | <desc>
|
---|
2045 | Session object that will represent the open remote session
|
---|
2046 | after successful method invocation. This object must not
|
---|
2047 | represent an already open session.
|
---|
2048 | <note>
|
---|
2049 | This session will be automatically closed when the peer
|
---|
2050 | (direct) session dies or gets closed.
|
---|
2051 | </note>
|
---|
2052 | </desc>
|
---|
2053 | </param>
|
---|
2054 | <param name="machineId" type="uuid" dir="in">
|
---|
2055 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
2056 | </param>
|
---|
2057 | </method>
|
---|
2058 |
|
---|
2059 | <method name="registerCallback">
|
---|
2060 | <desc>
|
---|
2061 | Registers a new global VirtualBox callback. The methods of the given
|
---|
2062 | callback object will be called by VirtualBox when an appropriate
|
---|
2063 | event occurs.
|
---|
2064 | </desc>
|
---|
2065 | <param name="callback" type="IVirtualBoxCallback" dir="in">
|
---|
2066 | <desc>Callback object to register.</desc>
|
---|
2067 | </param>
|
---|
2068 | </method>
|
---|
2069 |
|
---|
2070 | <method name="unregisterCallback">
|
---|
2071 | <desc>
|
---|
2072 | Unregisters the previously registered global VirtualBox callback.
|
---|
2073 | </desc>
|
---|
2074 | <param name="callback" type="IVirtualBoxCallback" dir="in">
|
---|
2075 | <desc>Callback object to unregister.</desc>
|
---|
2076 | </param>
|
---|
2077 | </method>
|
---|
2078 |
|
---|
2079 | <method name="waitForPropertyChange">
|
---|
2080 | <desc>
|
---|
2081 | Blocks the caller until any of the properties represented by the @a
|
---|
2082 | what argument changes the value or until the given timeout interval
|
---|
2083 | expires.
|
---|
2084 |
|
---|
2085 | The @a what argument is a comma separated list of propertiy masks that
|
---|
2086 | describe properties the caller is interested in. The property mask is
|
---|
2087 | a string in the following format:
|
---|
2088 |
|
---|
2089 | <pre>
|
---|
2090 | [[group.]subgroup.]name
|
---|
2091 | </pre>
|
---|
2092 |
|
---|
2093 | where @c name is the property name and @c group, @c subgroup are zero
|
---|
2094 | or or more property group specifiers. Each element (group or name) in
|
---|
2095 | the property mask may be either a latin string or an asterisk symbol
|
---|
2096 | (@c "*") which is used to match any string for the given element. A
|
---|
2097 | property mask that doesn't contain asterisk symbols represents a
|
---|
2098 | single fully qualified property name.
|
---|
2099 |
|
---|
2100 | Groups in the fully qualified property name go from more generic (the
|
---|
2101 | left-most part) to more specific (the right-most part). The first
|
---|
2102 | element is usually a name of the object the property belongs to. The
|
---|
2103 | second element may be either a property name, or a child object name,
|
---|
2104 | or an index if the preceeding element names an object which is one of
|
---|
2105 | many objects of the same type. This way, property names form a
|
---|
2106 | hierarchy of properties. Here are some examples of property names:
|
---|
2107 |
|
---|
2108 | <table>
|
---|
2109 | <tr>
|
---|
2110 | <td><tt>VirtualBox.version</tt></td>
|
---|
2111 | <td><link to="IVirtualBox::version"/> property</td>
|
---|
2112 | </tr>
|
---|
2113 | <tr>
|
---|
2114 | <td><tt>Machine.<UUID>.name</tt></td>
|
---|
2115 | <td><link to="IMachine::name"/> property of the machine with the
|
---|
2116 | given UUID</td>
|
---|
2117 | </tr>
|
---|
2118 | </table>
|
---|
2119 |
|
---|
2120 | Most property names directly correspond to the properties of objects
|
---|
2121 | (components) provided by the VirtualBox library and may be used to
|
---|
2122 | track changes to these properties. However, there may be
|
---|
2123 | pseudo-property names that don't correspond to any existing object's
|
---|
2124 | property directly, as well as there may be object properties that
|
---|
2125 | don't have a corresponding property name that is understood by this
|
---|
2126 | method, and therefore changes to such properties cannot be
|
---|
2127 | tracked. See individual object's property descrcriptions to get a
|
---|
2128 | fully qualified property name that can be used with this method (if
|
---|
2129 | any).
|
---|
2130 |
|
---|
2131 | There is a special property mask @c "*" (i.e. a string consisting of a
|
---|
2132 | single asterisk symbol) that can be used to match all properties.
|
---|
2133 | Below are more examples of property masks:
|
---|
2134 |
|
---|
2135 | <table>
|
---|
2136 | <tr>
|
---|
2137 | <td><tt>VirtualBox.*</tt></td>
|
---|
2138 | <td>Track all properties of the VirtualBox object</td>
|
---|
2139 | </tr>
|
---|
2140 | <tr>
|
---|
2141 | <td><tt>Machine.*.name</tt></td>
|
---|
2142 | <td>Track changes to the <link to="IMachine::name"/> property of
|
---|
2143 | all registered virtual machines</td>
|
---|
2144 | </tr>
|
---|
2145 | </table>
|
---|
2146 |
|
---|
2147 | </desc>
|
---|
2148 | <param name="what" type="wstring" dir="in">
|
---|
2149 | <desc>Comma separated list of property masks.</desc>
|
---|
2150 | </param>
|
---|
2151 | <param name="timeout" type="unsigned long" dir="in">
|
---|
2152 | <desc>
|
---|
2153 | Wait timeout in milliseconds.
|
---|
2154 | Specify -1 for an indefinite wait.
|
---|
2155 | </desc>
|
---|
2156 | </param>
|
---|
2157 | <param name="changed" type="wstring" dir="out">
|
---|
2158 | <desc>
|
---|
2159 | Comma separated list of properties that have been changed and caused
|
---|
2160 | this method to return to the caller.
|
---|
2161 | </desc>
|
---|
2162 | </param>
|
---|
2163 | <param name="values" type="wstring" dir="out">
|
---|
2164 | <desc>Reserved, not currently used.</desc>
|
---|
2165 | </param>
|
---|
2166 | </method>
|
---|
2167 |
|
---|
2168 | <method name="saveSettings">
|
---|
2169 | <desc>
|
---|
2170 | Saves the global settings to the global settings file
|
---|
2171 | (<link to="#settingsFilePath"/>).
|
---|
2172 |
|
---|
2173 | This method is only useful for explicitly saving the global settings
|
---|
2174 | file after it has been auto-converted from the old format to the most
|
---|
2175 | recent format (see <link to="#settingsFileVersion"/> for details).
|
---|
2176 | Normally, the global settings file is implicitly saved when a global
|
---|
2177 | setting is changed.
|
---|
2178 | </desc>
|
---|
2179 | </method>
|
---|
2180 |
|
---|
2181 | <method name="saveSettingsWithBackup">
|
---|
2182 | <desc>
|
---|
2183 | Creates a backup copy of the global settings file
|
---|
2184 | (<link to="#settingsFilePath"/>) in case of auto-conversion, and then
|
---|
2185 | calls <link to="#saveSettings()"/>.
|
---|
2186 |
|
---|
2187 | Note that the backup copy is created <b>only</b> if the settings file
|
---|
2188 | auto-conversion took place (see <link to="#settingsFileVersion"/> for
|
---|
2189 | details). Otherwise, this call is fully equivalent to
|
---|
2190 | <link to="#saveSettings()"/> and no backup copying is done.
|
---|
2191 |
|
---|
2192 | The backup copy is created in the same directory where the original
|
---|
2193 | settings file is located. It is given the following file name:
|
---|
2194 | <pre>
|
---|
2195 | original.xml.x.y-platform.bak
|
---|
2196 | </pre>
|
---|
2197 | where <tt>original.xml</tt> is the original settings file name
|
---|
2198 | (excluding path), and <tt>x.y-platform</tt> is the version of the old
|
---|
2199 | format of the settings file (before auto-conversion).
|
---|
2200 |
|
---|
2201 | If the given backup file already exists, this method will try to add the
|
---|
2202 | <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
|
---|
2203 | 0 to 9) and copy it again until it succeeds. If all suffixes are
|
---|
2204 | occupied, or if any other copy error occurs, this method will return a
|
---|
2205 | failure.
|
---|
2206 |
|
---|
2207 | If the copy operation succeeds, the @a bakFileName return argument will
|
---|
2208 | receive a full path to the created backup file (for informational
|
---|
2209 | purposes). Note that this will happen even if the subsequent
|
---|
2210 | <link to="#saveSettings()"/> call performed by this method after the
|
---|
2211 | copy operation, fails.
|
---|
2212 |
|
---|
2213 | <note>
|
---|
2214 | The VirtualBox API never calls this method. It is intended purely for
|
---|
2215 | the purposes of creating backup copies of the settings files by
|
---|
2216 | front-ends before saving the results of the automatically performed
|
---|
2217 | settings conversion to disk.
|
---|
2218 | </note>
|
---|
2219 |
|
---|
2220 | <see>settingsFileVersion</see>
|
---|
2221 | </desc>
|
---|
2222 | <param name="bakFileName" type="wstring" dir="return">
|
---|
2223 | <desc>Full path to the created backup copy.</desc>
|
---|
2224 | </param>
|
---|
2225 | </method>
|
---|
2226 |
|
---|
2227 | </interface>
|
---|
2228 |
|
---|
2229 | <!--
|
---|
2230 | // IMachine
|
---|
2231 | /////////////////////////////////////////////////////////////////////////
|
---|
2232 | -->
|
---|
2233 |
|
---|
2234 | <enumerator
|
---|
2235 | name="IMachineEnumerator" type="IMachine"
|
---|
2236 | uuid="1b554149-be0a-4465-9252-9ff8f420af55"
|
---|
2237 | />
|
---|
2238 |
|
---|
2239 | <collection
|
---|
2240 | name="IMachineCollection" type="IMachine" enumerator="IMachineEnumerator"
|
---|
2241 | uuid="FD443EC1-3007-4F5B-9282-D72760A66916"
|
---|
2242 | readonly="yes"
|
---|
2243 | />
|
---|
2244 |
|
---|
2245 | <interface
|
---|
2246 | name="IInternalMachineControl" extends="$unknown"
|
---|
2247 | uuid="de04566a-7125-444b-949e-34e9f3ec3676"
|
---|
2248 | internal="yes"
|
---|
2249 | wsmap="suppress"
|
---|
2250 | >
|
---|
2251 | <method name="updateState">
|
---|
2252 | <desc>
|
---|
2253 | Updates the VM state.
|
---|
2254 | <note>
|
---|
2255 | This operation will also update the settings file with
|
---|
2256 | the correct information about the saved state file
|
---|
2257 | and delete this file from disk when appropriate.
|
---|
2258 | </note>
|
---|
2259 | </desc>
|
---|
2260 | <param name="state" type="MachineState" dir="in"/>
|
---|
2261 | </method>
|
---|
2262 |
|
---|
2263 | <method name="getIPCId">
|
---|
2264 | <param name="id" type="wstring" dir="return"/>
|
---|
2265 | </method>
|
---|
2266 |
|
---|
2267 | <method name="runUSBDeviceFilters">
|
---|
2268 | <desc>
|
---|
2269 | Asks the server to run USB devices filters of the associated
|
---|
2270 | machine against the given USB device and tell if there is
|
---|
2271 | a match.
|
---|
2272 | <note>
|
---|
2273 | Intended to be used only for remote USB devices. Local
|
---|
2274 | ones don't require to call this method (this is done
|
---|
2275 | implicitly by the Host and USBProxyService).
|
---|
2276 | </note>
|
---|
2277 | </desc>
|
---|
2278 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
2279 | <param name="matched" type="boolean" dir="out"/>
|
---|
2280 | <param name="maskedInterfaces" type="unsigned long" dir="out"/>
|
---|
2281 | </method>
|
---|
2282 |
|
---|
2283 | <method name="captureUSBDevice">
|
---|
2284 | <desc>
|
---|
2285 | Requests a capture of the given host USB device.
|
---|
2286 | When the request is completed, the VM process will
|
---|
2287 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
2288 | notification.
|
---|
2289 | </desc>
|
---|
2290 | <param name="id" type="uuid" dir="in"/>
|
---|
2291 | </method>
|
---|
2292 |
|
---|
2293 | <method name="detachUSBDevice">
|
---|
2294 | <desc>
|
---|
2295 | Notification that a VM is going to detach (done = false) or has
|
---|
2296 | already detached (done = true) the given USB device.
|
---|
2297 | When the done = true request is completed, the VM process will
|
---|
2298 | get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
|
---|
2299 | notification.
|
---|
2300 | <note>
|
---|
2301 | In the done = true case, the server must run its own filters
|
---|
2302 | and filters of all VMs but this one on the detached device
|
---|
2303 | as if it were just attached to the host computer.
|
---|
2304 | </note>
|
---|
2305 | </desc>
|
---|
2306 | <param name="id" type="uuid" dir="in"/>
|
---|
2307 | <param name="done" type="boolean" dir="in"/>
|
---|
2308 | </method>
|
---|
2309 |
|
---|
2310 | <method name="autoCaptureUSBDevices">
|
---|
2311 | <desc>
|
---|
2312 | Requests a capture all matching USB devices attached to the host.
|
---|
2313 | When the request is completed, the VM process will
|
---|
2314 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
2315 | notification per every captured device.
|
---|
2316 | </desc>
|
---|
2317 | </method>
|
---|
2318 |
|
---|
2319 | <method name="detachAllUSBDevices">
|
---|
2320 | <desc>
|
---|
2321 | Notification that a VM that is being powered down. The done
|
---|
2322 | parameter indicates whether which stage of the power down
|
---|
2323 | we're at. When done = false the VM is announcing its
|
---|
2324 | intentions, while when done = true the VM is reporting
|
---|
2325 | what it has done.
|
---|
2326 | <note>
|
---|
2327 | In the done = true case, the server must run its own filters
|
---|
2328 | and filters of all VMs but this one on all detach devices as
|
---|
2329 | if they were just attached to the host computer.
|
---|
2330 | </note>
|
---|
2331 | </desc>
|
---|
2332 | <param name="done" type="boolean" dir="in"/>
|
---|
2333 | </method>
|
---|
2334 |
|
---|
2335 | <method name="onSessionEnd">
|
---|
2336 | <desc>
|
---|
2337 | Triggered by the given session object when the session is about
|
---|
2338 | to close normally.
|
---|
2339 | </desc>
|
---|
2340 | <param name="session" type="ISession" dir="in">
|
---|
2341 | <desc>Session that is being closed</desc>
|
---|
2342 | </param>
|
---|
2343 | <param name="progress" type="IProgress" dir="return">
|
---|
2344 | <desc>
|
---|
2345 | Used to wait until the corresponding machine is actually
|
---|
2346 | deassociated from the given session on the server.
|
---|
2347 | Returned only when this session is a direct one.
|
---|
2348 | </desc>
|
---|
2349 | </param>
|
---|
2350 | </method>
|
---|
2351 |
|
---|
2352 | <method name="beginSavingState">
|
---|
2353 | <desc>
|
---|
2354 | Called by the VM process to inform the server it wants to
|
---|
2355 | save the current state and stop the VM execution.
|
---|
2356 | </desc>
|
---|
2357 | <param name="progress" type="IProgress" dir="in">
|
---|
2358 | <desc>
|
---|
2359 | Progress object created by the VM process to wait until
|
---|
2360 | the state is saved.
|
---|
2361 | </desc>
|
---|
2362 | </param>
|
---|
2363 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
2364 | <desc>
|
---|
2365 | File path the VM process must save the execution state to.
|
---|
2366 | </desc>
|
---|
2367 | </param>
|
---|
2368 | </method>
|
---|
2369 |
|
---|
2370 | <method name="endSavingState">
|
---|
2371 | <desc>
|
---|
2372 | Called by the VM process to inform the server that saving
|
---|
2373 | the state previously requested by #beginSavingState is either
|
---|
2374 | successfully finished or there was a failure.
|
---|
2375 | </desc>
|
---|
2376 |
|
---|
2377 | <param name="success" type="boolean" dir="in">
|
---|
2378 | <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
|
---|
2379 | </param>
|
---|
2380 | </method>
|
---|
2381 |
|
---|
2382 | <method name="adoptSavedState">
|
---|
2383 | <desc>
|
---|
2384 | Gets called by IConsole::adoptSavedState.
|
---|
2385 | </desc>
|
---|
2386 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
2387 | <desc>Path to the saved state file to adopt.</desc>
|
---|
2388 | </param>
|
---|
2389 | </method>
|
---|
2390 |
|
---|
2391 | <method name="beginTakingSnapshot">
|
---|
2392 | <desc>
|
---|
2393 | Called by the VM process to inform the server it wants to
|
---|
2394 | take a snapshot.
|
---|
2395 | </desc>
|
---|
2396 | <param name="initiator" type="IConsole" dir="in">
|
---|
2397 | <desc>The console object that initiated this call.</desc>
|
---|
2398 | </param>
|
---|
2399 | <param name="name" type="wstring" dir="in">
|
---|
2400 | <desc>Snapshot name</desc>
|
---|
2401 | </param>
|
---|
2402 | <param name="description" type="wstring" dir="in">
|
---|
2403 | <desc>Snapshot description</desc>
|
---|
2404 | </param>
|
---|
2405 | <param name="progress" type="IProgress" dir="in">
|
---|
2406 | <desc>
|
---|
2407 | Progress object created by the VM process to wait until
|
---|
2408 | the state is saved (only for online snapshots).
|
---|
2409 | </desc>
|
---|
2410 | </param>
|
---|
2411 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
2412 | <desc>
|
---|
2413 | File path the VM process must save the execution state to.
|
---|
2414 | </desc>
|
---|
2415 | </param>
|
---|
2416 | <param name="serverProgress" type="IProgress" dir="out">
|
---|
2417 | <desc>
|
---|
2418 | Progress object created by the server process to wait until
|
---|
2419 | the snapshot is taken (VDI diff creation, etc.).
|
---|
2420 | </desc>
|
---|
2421 | </param>
|
---|
2422 | </method>
|
---|
2423 |
|
---|
2424 | <method name="endTakingSnapshot">
|
---|
2425 | <desc>
|
---|
2426 | Called by the VM process to inform the server that the snapshot
|
---|
2427 | previously requested by #beginTakingSnapshot is either
|
---|
2428 | successfully taken or there was a failure.
|
---|
2429 | </desc>
|
---|
2430 |
|
---|
2431 | <param name="success" type="boolean" dir="in">
|
---|
2432 | <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
|
---|
2433 | </param>
|
---|
2434 | </method>
|
---|
2435 |
|
---|
2436 | <method name="discardSnapshot">
|
---|
2437 | <desc>
|
---|
2438 | Gets called by IConsole::discardSnapshot.
|
---|
2439 | </desc>
|
---|
2440 | <param name="initiator" type="IConsole" dir="in">
|
---|
2441 | <desc>The console object that initiated this call.</desc>
|
---|
2442 | </param>
|
---|
2443 | <param name="id" type="uuid" dir="in">
|
---|
2444 | <desc>UUID of the snapshot to discard.</desc>
|
---|
2445 | </param>
|
---|
2446 | <param name="machineState" type="MachineState" dir="out">
|
---|
2447 | <desc>New machine state after this operation is started.</desc>
|
---|
2448 | </param>
|
---|
2449 | <param name="progress" type="IProgress" dir="return">
|
---|
2450 | <desc>Progress object to track the operation completion.</desc>
|
---|
2451 | </param>
|
---|
2452 | </method>
|
---|
2453 |
|
---|
2454 | <method name="discardCurrentState">
|
---|
2455 | <desc>
|
---|
2456 | Gets called by IConsole::discardCurrentState.
|
---|
2457 | </desc>
|
---|
2458 | <param name="initiator" type="IConsole" dir="in">
|
---|
2459 | <desc>The console object that initiated this call.</desc>
|
---|
2460 | </param>
|
---|
2461 | <param name="machineState" type="MachineState" dir="out">
|
---|
2462 | <desc>New machine state after this operation is started.</desc>
|
---|
2463 | </param>
|
---|
2464 | <param name="progress" type="IProgress" dir="return">
|
---|
2465 | <desc>Progress object to track the operation completion.</desc>
|
---|
2466 | </param>
|
---|
2467 | </method>
|
---|
2468 |
|
---|
2469 | <method name="discardCurrentSnapshotAndState">
|
---|
2470 | <desc>
|
---|
2471 | Gets called by IConsole::discardCurrentSnapshotAndState.
|
---|
2472 | </desc>
|
---|
2473 | <param name="initiator" type="IConsole" dir="in">
|
---|
2474 | <desc>The console object that initiated this call.</desc>
|
---|
2475 | </param>
|
---|
2476 | <param name="machineState" type="MachineState" dir="out">
|
---|
2477 | <desc>New machine state after this operation is started.</desc>
|
---|
2478 | </param>
|
---|
2479 | <param name="progress" type="IProgress" dir="return">
|
---|
2480 | <desc>Progress object to track the operation completion.</desc>
|
---|
2481 | </param>
|
---|
2482 | </method>
|
---|
2483 |
|
---|
2484 | <method name="pullGuestProperties">
|
---|
2485 | <desc>
|
---|
2486 | Get the list of the guest properties matching a set of patterns along
|
---|
2487 | with their values, timestamps and flags and give responsibility for
|
---|
2488 | managing properties to the console.
|
---|
2489 | </desc>
|
---|
2490 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
2491 | <desc>
|
---|
2492 | The names of the properties returned.
|
---|
2493 | </desc>
|
---|
2494 | </param>
|
---|
2495 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
2496 | <desc>
|
---|
2497 | The values of the properties returned. The array entries match the
|
---|
2498 | corresponding entries in the @a name array.
|
---|
2499 | </desc>
|
---|
2500 | </param>
|
---|
2501 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
2502 | <desc>
|
---|
2503 | The timestamps of the properties returned. The array entries match
|
---|
2504 | the corresponding entries in the @a name array.
|
---|
2505 | </desc>
|
---|
2506 | </param>
|
---|
2507 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
2508 | <desc>
|
---|
2509 | The flags of the properties returned. The array entries match the
|
---|
2510 | corresponding entries in the @a name array.
|
---|
2511 | </desc>
|
---|
2512 | </param>
|
---|
2513 | </method>
|
---|
2514 |
|
---|
2515 | <method name="pushGuestProperties">
|
---|
2516 | <desc>
|
---|
2517 | Set the list of the guest properties matching a set of patterns along
|
---|
2518 | with their values, timestamps and flags and return responsibility for
|
---|
2519 | managing properties to IMachine.
|
---|
2520 | </desc>
|
---|
2521 | <param name="name" type="wstring" dir="in" safearray="yes">
|
---|
2522 | <desc>
|
---|
2523 | The names of the properties returned.
|
---|
2524 | </desc>
|
---|
2525 | </param>
|
---|
2526 | <param name="value" type="wstring" dir="in" safearray="yes">
|
---|
2527 | <desc>
|
---|
2528 | The values of the properties returned. The array entries match the
|
---|
2529 | corresponding entries in the @a name array.
|
---|
2530 | </desc>
|
---|
2531 | </param>
|
---|
2532 | <param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
|
---|
2533 | <desc>
|
---|
2534 | The timestamps of the properties returned. The array entries match
|
---|
2535 | the corresponding entries in the @a name array.
|
---|
2536 | </desc>
|
---|
2537 | </param>
|
---|
2538 | <param name="flags" type="wstring" dir="in" safearray="yes">
|
---|
2539 | <desc>
|
---|
2540 | The flags of the properties returned. The array entries match the
|
---|
2541 | corresponding entries in the @a name array.
|
---|
2542 | </desc>
|
---|
2543 | </param>
|
---|
2544 | </method>
|
---|
2545 | </interface>
|
---|
2546 |
|
---|
2547 | <interface
|
---|
2548 | name="IBIOSSettings" extends="$unknown"
|
---|
2549 | uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
|
---|
2550 | wsmap="managed"
|
---|
2551 | >
|
---|
2552 | <desc>
|
---|
2553 | The IBIOSSettings interface represents BIOS settings of the virtual
|
---|
2554 | machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
|
---|
2555 | </desc>
|
---|
2556 | <attribute name="logoFadeIn" type="boolean">
|
---|
2557 | <desc>Fade in flag for BIOS logo animation.</desc>
|
---|
2558 | </attribute>
|
---|
2559 |
|
---|
2560 | <attribute name="logoFadeOut" type="boolean">
|
---|
2561 | <desc>Fade out flag for BIOS logo animation.</desc>
|
---|
2562 | </attribute>
|
---|
2563 |
|
---|
2564 | <attribute name="logoDisplayTime" type="unsigned long">
|
---|
2565 | <desc>BIOS logo display time in milliseconds (0 = default).</desc>
|
---|
2566 | </attribute>
|
---|
2567 |
|
---|
2568 | <attribute name="logoImagePath" type="wstring">
|
---|
2569 | <desc>Local file system path for external BIOS image.</desc>
|
---|
2570 | </attribute>
|
---|
2571 |
|
---|
2572 | <attribute name="bootMenuMode" type="BIOSBootMenuMode">
|
---|
2573 | <desc>Mode of the BIOS boot device menu.</desc>
|
---|
2574 | </attribute>
|
---|
2575 |
|
---|
2576 | <attribute name="ACPIEnabled" type="boolean">
|
---|
2577 | <desc>ACPI support flag.</desc>
|
---|
2578 | </attribute>
|
---|
2579 |
|
---|
2580 | <attribute name="IOAPICEnabled" type="boolean">
|
---|
2581 | <desc>
|
---|
2582 | IO APIC support flag. If set, VirtualBox will provide an IO APIC
|
---|
2583 | and support IRQs above 15.
|
---|
2584 | </desc>
|
---|
2585 | </attribute>
|
---|
2586 |
|
---|
2587 | <attribute name="timeOffset" type="long long">
|
---|
2588 | <desc>
|
---|
2589 | Offset in milliseconds from the host system time. This allows for
|
---|
2590 | guests running with a different system date/time than the host.
|
---|
2591 | It is equivalent to setting the system date/time in the BIOS other
|
---|
2592 | than it's not an absolute value but a relative one. Guest Additions
|
---|
2593 | time synchronization also honors this offset.
|
---|
2594 | </desc>
|
---|
2595 | </attribute>
|
---|
2596 |
|
---|
2597 | <attribute name="PXEDebugEnabled" type="boolean">
|
---|
2598 | <desc>
|
---|
2599 | PXE debug logging flag. If set, VirtualBox will write extensive
|
---|
2600 | PXE trace information to the release log.
|
---|
2601 | </desc>
|
---|
2602 | </attribute>
|
---|
2603 |
|
---|
2604 | <attribute name="IDEControllerType" type="IDEControllerType">
|
---|
2605 | <desc>
|
---|
2606 | Type of the virtual IDE controller. Depending on this value,
|
---|
2607 | VirtualBox will provide different virtual IDE hardware
|
---|
2608 | devices to the guest.
|
---|
2609 | </desc>
|
---|
2610 | </attribute>
|
---|
2611 |
|
---|
2612 | </interface>
|
---|
2613 |
|
---|
2614 | <interface
|
---|
2615 | name="IMachine" extends="$unknown"
|
---|
2616 | uuid="1e509de4-d96c-4f44-8b94-860194f710ac"
|
---|
2617 | wsmap="managed"
|
---|
2618 | >
|
---|
2619 | <desc>
|
---|
2620 | The IMachine interface represents a virtual machine, or guest, created
|
---|
2621 | in VirtualBox.
|
---|
2622 |
|
---|
2623 | This interface is used in two contexts. First of all, a collection of
|
---|
2624 | objects implementing this interface is stored in the
|
---|
2625 | <link to="IVirtualBox::machines"/> attribute which lists all the virtual
|
---|
2626 | machines that are currently registered with this VirtualBox
|
---|
2627 | installation. Also, once a session has been opened for the given virtual
|
---|
2628 | machine (e.g. the virtual machine is running), the machine object
|
---|
2629 | associated with the open session can be queried from the session object;
|
---|
2630 | see <link to="ISession"/> for details.
|
---|
2631 |
|
---|
2632 | The main role of this interface is to expose the settings of the virtual
|
---|
2633 | machine and provide methods to change various aspects of the virtual
|
---|
2634 | machine's configuration. For machine objects stored in the
|
---|
2635 | <link to="IVirtualBox::machines"/> collection, all attributes are
|
---|
2636 | read-only unless explicitely stated otherwise in individual attribute
|
---|
2637 | and method descriptions. In order to change a machine setting, a session
|
---|
2638 | for this machine must be opened using one of
|
---|
2639 | <link to="IVirtualBox::openSession"/>,
|
---|
2640 | <link to="IVirtualBox::openRemoteSession"/> or
|
---|
2641 | <link to="IVirtualBox::openExistingSession"/> methdods. After the
|
---|
2642 | session has been successfully opened, a mutable machine object needs to
|
---|
2643 | be queried from the session object and then the desired settings changes
|
---|
2644 | can be applied to the returned object using IMachine attributes and
|
---|
2645 | methods. See the ISession interface description for more information
|
---|
2646 | about sessions.
|
---|
2647 |
|
---|
2648 | Note that the IMachine interface does not provide methods to control
|
---|
2649 | virtual machine execution (such as start the machine, or power it
|
---|
2650 | down) -- these methods are grouped in a separate IConsole
|
---|
2651 | interface. Refer to the IConsole interface description to get more
|
---|
2652 | information about this topic.
|
---|
2653 |
|
---|
2654 | <see>ISession, IConsole</see>
|
---|
2655 | </desc>
|
---|
2656 |
|
---|
2657 | <attribute name="parent" type="IVirtualBox" readonly="yes">
|
---|
2658 | <desc>Associated parent obect.</desc>
|
---|
2659 | </attribute>
|
---|
2660 |
|
---|
2661 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
2662 | <desc>
|
---|
2663 | Whether this virtual machine is currently accessible or not.
|
---|
2664 |
|
---|
2665 | The machine is considered to be inaccessible when:
|
---|
2666 | <ul>
|
---|
2667 | <li>It is a registered virtual machine, and
|
---|
2668 | </li>
|
---|
2669 | <li>Its settings file is inaccessible (for example, it is
|
---|
2670 | located on a network share that is not accessible during
|
---|
2671 | VirtualBox startup, or becomes inaccessible later, or if
|
---|
2672 | the settings file can be read but is invalid).
|
---|
2673 | </li>
|
---|
2674 | </ul>
|
---|
2675 |
|
---|
2676 | Otherwise, the value of this property is always <tt>true</tt>.
|
---|
2677 |
|
---|
2678 | Every time this property is read, the accessibility state of
|
---|
2679 | this machine is re-evaluated. If the returned value is |false|,
|
---|
2680 | the <link to="#accessError"/> property may be used to get the
|
---|
2681 | detailed error information describing the reason of
|
---|
2682 | inaccessibility.
|
---|
2683 |
|
---|
2684 | When the machine is inaccessible, only the following properties
|
---|
2685 | can be used on it:
|
---|
2686 | <ul>
|
---|
2687 | <li><link to="#parent"/></li>
|
---|
2688 | <li><link to="#id"/></li>
|
---|
2689 | <li><link to="#settingsFilePath"/></li>
|
---|
2690 | <li><link to="#accessible"/></li>
|
---|
2691 | <li><link to="#accessError"/></li>
|
---|
2692 | </ul>
|
---|
2693 |
|
---|
2694 | An attempt to access any other property or method will return
|
---|
2695 | an error.
|
---|
2696 |
|
---|
2697 | The only possible action you can perform on an inaccessible
|
---|
2698 | machine is to unregister it using the
|
---|
2699 | <link to="IVirtualBox::unregisterMachine"/> call (or, to check
|
---|
2700 | for the accessibility state once more by querying this
|
---|
2701 | property).
|
---|
2702 |
|
---|
2703 | <note>
|
---|
2704 | In the current implementation, once this property returns
|
---|
2705 | <tt>true</tt>, the machine will never become inaccessible
|
---|
2706 | later, even if its settings file cannot be successfully
|
---|
2707 | read/written any more (at least, until the VirtualBox
|
---|
2708 | server is restarted). This limitation may be removed in
|
---|
2709 | future releases.
|
---|
2710 | </note>
|
---|
2711 | </desc>
|
---|
2712 | </attribute>
|
---|
2713 |
|
---|
2714 | <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
2715 | <desc>
|
---|
2716 | Error information describing the reason of machine
|
---|
2717 | inaccessibility.
|
---|
2718 |
|
---|
2719 | Reading this property is only valid after the last call to
|
---|
2720 | <link to="#accessible"/> returned <tt>false</tt> (i.e. the
|
---|
2721 | machine is currently unaccessible). Otherwise, a null
|
---|
2722 | IVirtualBoxErrorInfo object will be returned.
|
---|
2723 | </desc>
|
---|
2724 | </attribute>
|
---|
2725 |
|
---|
2726 | <attribute name="name" type="wstring">
|
---|
2727 | <desc>
|
---|
2728 | Name of the virtual machine.
|
---|
2729 |
|
---|
2730 | Besides being used for human-readable identification purposes
|
---|
2731 | everywhere in VirtualBox, the virtual machine name is also used
|
---|
2732 | as a name of the machine's settings file and as a name of the
|
---|
2733 | subdirectory this settings file resides in. Thus, every time you
|
---|
2734 | change the value of this property, the settings file will be
|
---|
2735 | renamed once you call <link to="#saveSettings()"/> to confirm the
|
---|
2736 | change. The containing subdirectory will be also renamed, but
|
---|
2737 | only if it has exactly the same name as the settings file
|
---|
2738 | itself prior to changing this property (for backward compatibility
|
---|
2739 | with previous API releases). The above implies the following
|
---|
2740 | limitations:
|
---|
2741 | <ul>
|
---|
2742 | <li>The machine name cannot be empty.</li>
|
---|
2743 | <li>The machine name can contain only characters that are valid
|
---|
2744 | file name characters according to the rules of the file
|
---|
2745 | system used to store VirtualBox configuration.</li>
|
---|
2746 | <li>You cannot have two or more machines with the same name
|
---|
2747 | if they use the same subdirectory for storing the machine
|
---|
2748 | settings files.</li>
|
---|
2749 | <li>You cannot change the name of the machine if it is running,
|
---|
2750 | or if any file in the directory containing the settings file
|
---|
2751 | is being used by another running machine or by any other
|
---|
2752 | process in the host operating system at a time when
|
---|
2753 | <link to="#saveSettings()"/> is called.
|
---|
2754 | </li>
|
---|
2755 | </ul>
|
---|
2756 | If any of the above limitations are hit, <link to="#saveSettings()"/>
|
---|
2757 | will return an appropriate error message explaining the exact
|
---|
2758 | reason and the changes you made to this machine will not be
|
---|
2759 | saved.
|
---|
2760 | <note>
|
---|
2761 | For "legacy" machines created using the
|
---|
2762 | <link to="IVirtualBox::createLegacyMachine()"/> call,
|
---|
2763 | the above naming limitations do not apply because the
|
---|
2764 | machine name does not affect the settings file name.
|
---|
2765 | The settings file name remains the same as it was specified
|
---|
2766 | during machine creation and never changes.
|
---|
2767 | </note>
|
---|
2768 | </desc>
|
---|
2769 | </attribute>
|
---|
2770 |
|
---|
2771 | <attribute name="description" type="wstring">
|
---|
2772 | <desc>
|
---|
2773 | Description of the virtual machine.
|
---|
2774 |
|
---|
2775 | The description attribute can contain any text and is
|
---|
2776 | typically used to describe the hardware and software
|
---|
2777 | configuration of the virtual machine in detail (i.e. network
|
---|
2778 | settings, versions of the installed software and so on).
|
---|
2779 | </desc>
|
---|
2780 | </attribute>
|
---|
2781 |
|
---|
2782 | <attribute name="id" type="uuid" readonly="yes">
|
---|
2783 | <desc>UUID of the virtual machine.</desc>
|
---|
2784 | </attribute>
|
---|
2785 |
|
---|
2786 | <attribute name="OSTypeId" type="wstring">
|
---|
2787 | <desc>
|
---|
2788 | User-defined identifier of the Guest OS type.
|
---|
2789 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
2790 | an IGuestOSType object representing details about the given
|
---|
2791 | Guest OS type.
|
---|
2792 | <note>
|
---|
2793 | This value may differ from the value returned by
|
---|
2794 | <link to="IGuest::OSTypeId"/> if Guest Additions are
|
---|
2795 | installed to the guest OS.
|
---|
2796 | </note>
|
---|
2797 | </desc>
|
---|
2798 | </attribute>
|
---|
2799 |
|
---|
2800 | <attribute name="memorySize" type="unsigned long">
|
---|
2801 | <desc>System memory size in megabytes.</desc>
|
---|
2802 | </attribute>
|
---|
2803 |
|
---|
2804 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
2805 | <desc>Initial memory balloon size in megabytes.</desc>
|
---|
2806 | </attribute>
|
---|
2807 |
|
---|
2808 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
2809 | <desc>Initial interval to update guest statistics in seconds.</desc>
|
---|
2810 | </attribute>
|
---|
2811 |
|
---|
2812 | <attribute name="VRAMSize" type="unsigned long">
|
---|
2813 | <desc>Video memory size in megabytes.</desc>
|
---|
2814 | </attribute>
|
---|
2815 |
|
---|
2816 | <attribute name="MonitorCount" type="unsigned long">
|
---|
2817 | <desc>
|
---|
2818 | Number of virtual monitors.
|
---|
2819 | <note>
|
---|
2820 | Only effective on Windows XP and later guests with
|
---|
2821 | Guest Additions installed.
|
---|
2822 | </note>
|
---|
2823 | </desc>
|
---|
2824 | </attribute>
|
---|
2825 |
|
---|
2826 | <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
|
---|
2827 | <desc>Object containing all BIOS settings.</desc>
|
---|
2828 | </attribute>
|
---|
2829 |
|
---|
2830 | <attribute name="HWVirtExEnabled" type="TSBool">
|
---|
2831 | <desc>
|
---|
2832 | This setting determines whether VirtualBox will try to make use of
|
---|
2833 | the host CPU's hardware virtualization extensions such as Intel VT-x
|
---|
2834 | and AMD-V. Note that in case such extensions are not available,
|
---|
2835 | they will not be used.
|
---|
2836 | </desc>
|
---|
2837 | </attribute>
|
---|
2838 |
|
---|
2839 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="true">
|
---|
2840 | <desc>
|
---|
2841 | This setting determines whether VirtualBox will try to make use of
|
---|
2842 | the nested paging extension of Intel VT-x and AMD-V. Note that in case
|
---|
2843 | such extensions are not available, they will not be used.
|
---|
2844 | </desc>
|
---|
2845 | </attribute>
|
---|
2846 |
|
---|
2847 | <attribute name="PAEEnabled" type="boolean" default="false">
|
---|
2848 | <desc>
|
---|
2849 | This setting determines whether VirtualBox will expose the Physical Address
|
---|
2850 | Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
|
---|
2851 | is not available, it will not be reported.
|
---|
2852 | </desc>
|
---|
2853 | </attribute>
|
---|
2854 |
|
---|
2855 | <attribute name="snapshotFolder" type="wstring">
|
---|
2856 | <desc>
|
---|
2857 | Full path to the directory used to store snapshot data
|
---|
2858 | (difrerencing hard disks and saved state files) of this machine.
|
---|
2859 |
|
---|
2860 | The initial value of this property is
|
---|
2861 | <tt><</tt><link to="#settingsFilePath">
|
---|
2862 | path_to_settings_file</link><tt>>/<</tt>
|
---|
2863 | <link to="#id">machine_uuid</link>
|
---|
2864 | <tt>></tt>.
|
---|
2865 |
|
---|
2866 | Currently, it is an error to try to change this property on
|
---|
2867 | a machine that has snapshots (because this would require to
|
---|
2868 | move possibly large files to a different location).
|
---|
2869 | A separate method will be available for this purpose later.
|
---|
2870 |
|
---|
2871 | <note>
|
---|
2872 | Setting this property to <tt>null</tt> will restore the
|
---|
2873 | initial value.
|
---|
2874 | </note>
|
---|
2875 | <note>
|
---|
2876 | When setting this property, the specified path can be
|
---|
2877 | absolute (full path) or relative to the directory where the
|
---|
2878 | <link to="#settingsFilePath">machine settings file</link>
|
---|
2879 | is located. When reading this property, a full path is
|
---|
2880 | always returned.
|
---|
2881 | </note>
|
---|
2882 | <note>
|
---|
2883 | The specified path may not exist, it will be created
|
---|
2884 | when necessary.
|
---|
2885 | </note>
|
---|
2886 | </desc>
|
---|
2887 | </attribute>
|
---|
2888 |
|
---|
2889 | <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
|
---|
2890 | <desc>VRDP server object.</desc>
|
---|
2891 | </attribute>
|
---|
2892 |
|
---|
2893 | <attribute name="hardDiskAttachments" type="IHardDiskAttachmentCollection" readonly="yes">
|
---|
2894 | <desc>Collection of hard disks attached to the machine.</desc>
|
---|
2895 | </attribute>
|
---|
2896 |
|
---|
2897 | <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
|
---|
2898 | <desc>Associated DVD drive object.</desc>
|
---|
2899 | </attribute>
|
---|
2900 |
|
---|
2901 | <attribute name="FloppyDrive" type="IFloppyDrive" readonly="yes">
|
---|
2902 | <desc>Associated floppy drive object.</desc>
|
---|
2903 | </attribute>
|
---|
2904 |
|
---|
2905 | <attribute name="USBController" type="IUSBController" readonly="yes">
|
---|
2906 | <desc>
|
---|
2907 | Associated USB controller object.
|
---|
2908 |
|
---|
2909 | <note>
|
---|
2910 | This method may set a @ref com_warnings "warning result code".
|
---|
2911 | </note>
|
---|
2912 | <note>
|
---|
2913 | If USB functionality is not avaliable in the given edition of
|
---|
2914 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
2915 | </note>
|
---|
2916 | </desc>
|
---|
2917 | </attribute>
|
---|
2918 |
|
---|
2919 | <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
|
---|
2920 | <desc>Associated audio adapter, always present.</desc>
|
---|
2921 | </attribute>
|
---|
2922 |
|
---|
2923 | <attribute name="SATAController" type="ISATAController" readonly="yes">
|
---|
2924 | <desc>
|
---|
2925 | Associated SATA controller object.
|
---|
2926 | </desc>
|
---|
2927 | </attribute>
|
---|
2928 |
|
---|
2929 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
2930 | <desc>
|
---|
2931 | Full name of the file containing machine settings data.
|
---|
2932 | </desc>
|
---|
2933 | </attribute>
|
---|
2934 |
|
---|
2935 | <attribute name="settingsFileVersion" type="wstring" readonly="yes">
|
---|
2936 | <desc>
|
---|
2937 | Current version of the format of the settings file of this machine
|
---|
2938 | (<link to="#settingsFilePath"/>).
|
---|
2939 |
|
---|
2940 | The version string has the following format:
|
---|
2941 | <pre>
|
---|
2942 | x.y-platform
|
---|
2943 | </pre>
|
---|
2944 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
2945 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
2946 |
|
---|
2947 | The current version usually matches the value of the
|
---|
2948 | <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
|
---|
2949 | settings file was created by an older version of VirtualBox and there
|
---|
2950 | was a change of the settings file format since then.
|
---|
2951 |
|
---|
2952 | Note that VirtualBox automatically converts settings files from older
|
---|
2953 | versions to the most recent version when reading them (usually at
|
---|
2954 | VirtualBox startup) but it doesn't save the changes back until
|
---|
2955 | you call a method that implicitly saves settings (such as
|
---|
2956 | <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/>
|
---|
2957 | explicitly. Therefore, if the value of this attribute differs from the
|
---|
2958 | value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
|
---|
2959 | means that the settings file was converted but the result of the
|
---|
2960 | conversion is not yet saved to disk.
|
---|
2961 |
|
---|
2962 | The above feature may be used by interactive front-ends to inform users
|
---|
2963 | about the settings file format change and offer them to explicitly save
|
---|
2964 | all converted settings files (the global and VM-specific ones),
|
---|
2965 | optionally create bacup copies of the old settings files before saving,
|
---|
2966 | etc.
|
---|
2967 |
|
---|
2968 | <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
|
---|
2969 | </desc>
|
---|
2970 | </attribute>
|
---|
2971 |
|
---|
2972 | <attribute name="settingsModified" type="boolean" readonly="yes">
|
---|
2973 | <desc>
|
---|
2974 | Whether the settings of this machine have been modified
|
---|
2975 | (but neither yet saved nor discarded).
|
---|
2976 | <note>
|
---|
2977 | Reading this property is only valid on instances returned
|
---|
2978 | by <link to="ISession::machine"/> and on new machines
|
---|
2979 | created by <link to="IVirtualBox::createMachine"/> or opened
|
---|
2980 | by <link to="IVirtualBox::openMachine"/> but not
|
---|
2981 | yet registered, or on unregistered machines after calling
|
---|
2982 | <link to="IVirtualBox::unregisterMachine"/>. For all other
|
---|
2983 | cases, the settigs can never be modified.
|
---|
2984 | </note>
|
---|
2985 | <note>
|
---|
2986 | For newly created unregistered machines, the value of this
|
---|
2987 | property is always TRUE until <link to="#saveSettings()"/>
|
---|
2988 | is called (no matter if any machine settings have been
|
---|
2989 | changed after the creation or not). For opened machines
|
---|
2990 | the value is set to FALSE (and then follows to normal rules).
|
---|
2991 | </note>
|
---|
2992 | </desc>
|
---|
2993 | </attribute>
|
---|
2994 |
|
---|
2995 | <attribute name="sessionState" type="SessionState" readonly="yes">
|
---|
2996 | <desc>Current session state for this machine.</desc>
|
---|
2997 | </attribute>
|
---|
2998 |
|
---|
2999 | <attribute name="sessionType" type="wstring" readonly="yes">
|
---|
3000 | <desc>
|
---|
3001 | Type of the session. If <link to="#sessionState"/> is
|
---|
3002 | SessionSpawning or SessionOpen, this attribute contains the
|
---|
3003 | same value as passed to the
|
---|
3004 | <link to="IVirtualBox::openRemoteSession()"/> method in the @a
|
---|
3005 | type parameter. If the session was opened directly using
|
---|
3006 | <link to="IVirtualBox::openSession()"/>, or if
|
---|
3007 | <link to="#sessionState"/> is SessionClosed, the value of this
|
---|
3008 | attribute is @c null.
|
---|
3009 | </desc>
|
---|
3010 | </attribute>
|
---|
3011 |
|
---|
3012 | <attribute name="sessionPid" type="unsigned long" readonly="yes">
|
---|
3013 | <desc>
|
---|
3014 | Identifier of the session process. This attribute contains the
|
---|
3015 | platform-dependent identifier of the process that has opened a
|
---|
3016 | direct session for this machine using the
|
---|
3017 | <link to="IVirtualBox::openSession()"/> call. The returned value
|
---|
3018 | is only valid if <link to="#sessionState"/> is SessionOpen or
|
---|
3019 | SessionClosing (i.e. a session is currently open or being
|
---|
3020 | closed) by the time this property is read.
|
---|
3021 | </desc>
|
---|
3022 | </attribute>
|
---|
3023 |
|
---|
3024 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
3025 | <desc>Current execution state of this machine.</desc>
|
---|
3026 | </attribute>
|
---|
3027 |
|
---|
3028 | <attribute name="lastStateChange" type="long long" readonly="yes">
|
---|
3029 | <desc>
|
---|
3030 | Time stamp of the last execution state change,
|
---|
3031 | in milliseconds since 1970-01-01 UTC.
|
---|
3032 | </desc>
|
---|
3033 | </attribute>
|
---|
3034 |
|
---|
3035 | <attribute name="stateFilePath" type="wstring" readonly="yes">
|
---|
3036 | <desc>
|
---|
3037 | Full path to the file that stores the execution state of
|
---|
3038 | the machine when it is in the <link to="MachineState::Saved"/>
|
---|
3039 | state.
|
---|
3040 | <note>
|
---|
3041 | When the machine is not in the Saved state, this attribute
|
---|
3042 | <tt>null</tt>.
|
---|
3043 | </note>
|
---|
3044 | </desc>
|
---|
3045 | </attribute>
|
---|
3046 |
|
---|
3047 | <attribute name="logFolder" type="wstring" readonly="yes">
|
---|
3048 | <desc>
|
---|
3049 | Full path to the folder that stores a set of rotated log files
|
---|
3050 | recorded during machine execution. The most recent log file is
|
---|
3051 | named <tt>VBox.log</tt>, the previous log file is
|
---|
3052 | named <tt>VBox.log.1</tt> and so on (upto <tt>VBox.log.3</tt>
|
---|
3053 | in the current version).
|
---|
3054 | </desc>
|
---|
3055 | </attribute>
|
---|
3056 |
|
---|
3057 | <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
|
---|
3058 | <desc>
|
---|
3059 | Current snapshot of this machine.
|
---|
3060 | <note>
|
---|
3061 | A <tt>null</tt> object is returned if the machine doesn't
|
---|
3062 | have snapshots.
|
---|
3063 | </note>
|
---|
3064 | <see><link to="ISnapshot"/></see>
|
---|
3065 | </desc>
|
---|
3066 | </attribute>
|
---|
3067 |
|
---|
3068 | <attribute name="snapshotCount" type="unsigned long" readonly="yes">
|
---|
3069 | <desc>
|
---|
3070 | Number of snapshots taken on this machine. Zero means the
|
---|
3071 | machine doesn't have any snapshots.
|
---|
3072 | </desc>
|
---|
3073 | </attribute>
|
---|
3074 |
|
---|
3075 | <attribute name="currentStateModified" type="boolean" readonly="yes">
|
---|
3076 | <desc>
|
---|
3077 | Returns <tt>true</tt> if the current state of the machine is not
|
---|
3078 | identical to the state stored in the current snapshot.
|
---|
3079 |
|
---|
3080 | The current state is identical to the current snapshot right
|
---|
3081 | after one of the following calls are made:
|
---|
3082 | <ul>
|
---|
3083 | <li><link to="IConsole::discardCurrentState"/> or
|
---|
3084 | <link to="IConsole::discardCurrentSnapshotAndState"/>
|
---|
3085 | </li>
|
---|
3086 | <li><link to="IConsole::takeSnapshot"/> (issued on a
|
---|
3087 | powered off or saved machine, for which
|
---|
3088 | <link to="#settingsModified"/> returns <tt>false</tt>)
|
---|
3089 | </li>
|
---|
3090 | <li><link to="IMachine::setCurrentSnapshot"/>
|
---|
3091 | </li>
|
---|
3092 | </ul>
|
---|
3093 |
|
---|
3094 | The current state remains identical until one of the following
|
---|
3095 | happens:
|
---|
3096 | <ul>
|
---|
3097 | <li>settings of the machine are changed</li>
|
---|
3098 | <li>the saved state is discarded</li>
|
---|
3099 | <li>the current snapshot is discarded</li>
|
---|
3100 | <li>an attempt to execute the machine is made</li>
|
---|
3101 | </ul>
|
---|
3102 |
|
---|
3103 | <note>
|
---|
3104 | For machines that don't have snapshots, this property is
|
---|
3105 | always <tt>false</tt>.
|
---|
3106 | </note>
|
---|
3107 | </desc>
|
---|
3108 | </attribute>
|
---|
3109 |
|
---|
3110 | <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
|
---|
3111 | <desc>
|
---|
3112 | Collection of shared folders for this machine (permanent shared
|
---|
3113 | folders). These folders are shared automatically at machine startup
|
---|
3114 | and available only to the guest OS installed within this machine.
|
---|
3115 |
|
---|
3116 | New shared folders are added to the collection using
|
---|
3117 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
3118 | removed using <link to="#removeSharedFolder"/>.
|
---|
3119 | </desc>
|
---|
3120 | </attribute>
|
---|
3121 |
|
---|
3122 | <attribute name="clipboardMode" type="ClipboardMode">
|
---|
3123 | <desc>
|
---|
3124 | Synchronization mode between the host OS clipboard
|
---|
3125 | and the guest OS clipboard.
|
---|
3126 | </desc>
|
---|
3127 | </attribute>
|
---|
3128 |
|
---|
3129 | <method name="setBootOrder">
|
---|
3130 | <desc>
|
---|
3131 | Puts the given device to the specified position in
|
---|
3132 | the boot order.
|
---|
3133 |
|
---|
3134 | To indicate that no device is associated with the given position,
|
---|
3135 | <link to="DeviceType::Null"/> should be used.
|
---|
3136 |
|
---|
3137 | @todo setHardDiskBootOrder(), setNetworkBootOrder()
|
---|
3138 | </desc>
|
---|
3139 | <param name="position" type="unsigned long" dir="in">
|
---|
3140 | <desc>
|
---|
3141 | Position in the boot order (<tt>1</tt> to the total number of
|
---|
3142 | devices the machine can boot from, as returned by
|
---|
3143 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
3144 | </desc>
|
---|
3145 | </param>
|
---|
3146 | <param name="device" type="DeviceType" dir="in">
|
---|
3147 | <desc>
|
---|
3148 | The type of the device used to boot at the given position.
|
---|
3149 | </desc>
|
---|
3150 | </param>
|
---|
3151 | </method>
|
---|
3152 |
|
---|
3153 | <method name="getBootOrder" const="yes">
|
---|
3154 | <desc>
|
---|
3155 | Returns the device type that occupies the specified
|
---|
3156 | position in the boot order.
|
---|
3157 |
|
---|
3158 | @todo [remove?]
|
---|
3159 | If the machine can have more than one device of the returned type
|
---|
3160 | (such as hard disks), then a separate method should be used to
|
---|
3161 | retrieve the individual device that occupies the given position.
|
---|
3162 |
|
---|
3163 | If here are no devices at the given position, then
|
---|
3164 | <link to="DeviceType::Null"/> is returned.
|
---|
3165 |
|
---|
3166 | @todo getHardDiskBootOrder(), getNetworkBootOrder()
|
---|
3167 | </desc>
|
---|
3168 | <param name="order" type="unsigned long" dir="in">
|
---|
3169 | <desc>
|
---|
3170 | Position in the boot order (<tt>1</tt> to the total number of
|
---|
3171 | devices the machine can boot from, as returned by
|
---|
3172 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
3173 | </desc>
|
---|
3174 | </param>
|
---|
3175 | <param name="device" type="DeviceType" dir="return">
|
---|
3176 | <desc>
|
---|
3177 | Device at the given position.
|
---|
3178 | </desc>
|
---|
3179 | </param>
|
---|
3180 | </method>
|
---|
3181 |
|
---|
3182 | <method name="attachHardDisk">
|
---|
3183 | <desc>
|
---|
3184 |
|
---|
3185 | Attaches a virtual hard disk identified by the given UUID to the
|
---|
3186 | given device slot of the given channel on the given bus. The
|
---|
3187 | specified device slot must not have another disk attached and the
|
---|
3188 | given hard disk must not be already attached to this machine.
|
---|
3189 |
|
---|
3190 | See <link to="IHardDisk"/> for detailed information about
|
---|
3191 | attaching hard disks.
|
---|
3192 |
|
---|
3193 | <note>You cannot attach a hard disk to a running machine. Also,
|
---|
3194 | you cannot attach a hard disk to a newly created machine until
|
---|
3195 | it is registered.</note>
|
---|
3196 |
|
---|
3197 | <note>Attaching a hard disk to a machine creates a <i>lazy</i>
|
---|
3198 | attachment. In particular, no differeincing images are
|
---|
3199 | actually created until <link to="#saveSettings()"/> is called to
|
---|
3200 | commit all changed settings.</note>
|
---|
3201 |
|
---|
3202 | </desc>
|
---|
3203 | <param name="id" type="uuid" dir="in">
|
---|
3204 | <desc>UUID of the hard disk to attach.</desc>
|
---|
3205 | </param>
|
---|
3206 | <param name="bus" type="StorageBus" dir="in">
|
---|
3207 | <desc>Type of storage bus to use (IDE or SATA).</desc>
|
---|
3208 | </param>
|
---|
3209 | <param name="channel" type="long" dir="in">
|
---|
3210 | <desc>Channel to attach the hard disk to. For IDE controllers,
|
---|
3211 | this can either be 0 or 1, for the primary or secondary controller,
|
---|
3212 | respectively.</desc>
|
---|
3213 | </param>
|
---|
3214 | <param name="device" type="long" dir="in">
|
---|
3215 | <desc>Device slot in the given channel to attach the hard disk to.
|
---|
3216 | For IDE devices, within each channel (0 or 1), this can again be
|
---|
3217 | 0 or 1, for master or slave, respectively.</desc>
|
---|
3218 | </param>
|
---|
3219 | </method>
|
---|
3220 |
|
---|
3221 | <method name="getHardDisk" const="yes">
|
---|
3222 | <desc>
|
---|
3223 | Returns the hard disk attached to the
|
---|
3224 | given controller under the specified device number.
|
---|
3225 | </desc>
|
---|
3226 | <param name="bus" type="StorageBus" dir="in"/>
|
---|
3227 | <param name="channel" type="long" dir="in"/>
|
---|
3228 | <param name="device" type="long" dir="in"/>
|
---|
3229 | <param name="hardDisk" type="IHardDisk" dir="return"/>
|
---|
3230 | </method>
|
---|
3231 |
|
---|
3232 | <method name="detachHardDisk">
|
---|
3233 | <desc>
|
---|
3234 |
|
---|
3235 | Detaches the hard disk drive attached to the given device slot
|
---|
3236 | of the given controller.
|
---|
3237 |
|
---|
3238 | See <link to="IHardDisk"/> for detailed information about
|
---|
3239 | attaching hard disks.
|
---|
3240 |
|
---|
3241 | <note>You cannot detach a hard disk from a running
|
---|
3242 | machine.</note>
|
---|
3243 |
|
---|
3244 | <note>
|
---|
3245 | Detaching a hard disk from a machine creates a <i>lazy</i>
|
---|
3246 | detachment. In particular, if the detached hard disk is a
|
---|
3247 | differencing hard disk, it is not actually deleted until
|
---|
3248 | <link to="#saveSettings()"/> is called to commit all changed settings.
|
---|
3249 | Keep in mind, that doing <link to="#saveSettings()"/> will
|
---|
3250 | <b>physically delete</b> all detached differencing hard disks,
|
---|
3251 | so be careful.
|
---|
3252 | </note>
|
---|
3253 |
|
---|
3254 | </desc>
|
---|
3255 | <param name="bus" type="StorageBus" dir="in">
|
---|
3256 | <desc>Bus to dettach the hard disk from.</desc>
|
---|
3257 | </param>
|
---|
3258 | <param name="channel" type="long" dir="in">
|
---|
3259 | <desc>Channel number to dettach the hard disk from.</desc>
|
---|
3260 | </param>
|
---|
3261 | <param name="device" type="long" dir="in">
|
---|
3262 | <desc>Device slot number to dettach the hard disk from.</desc>
|
---|
3263 | </param>
|
---|
3264 | </method>
|
---|
3265 |
|
---|
3266 | <method name="getNetworkAdapter" const="yes">
|
---|
3267 | <desc>
|
---|
3268 | Returns the network adapter associated with the given slot.
|
---|
3269 | Slots are numbered sequentially, starting with zero. The total
|
---|
3270 | number of adapters per every machine is defined by the
|
---|
3271 | <link to="ISystemProperties::networkAdapterCount"/> property,
|
---|
3272 | so the maximum slot number is one less than that property's value.
|
---|
3273 | </desc>
|
---|
3274 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
3275 | <param name="adapter" type="INetworkAdapter" dir="return"/>
|
---|
3276 | </method>
|
---|
3277 |
|
---|
3278 | <method name="getSerialPort" const="yes">
|
---|
3279 | <desc>
|
---|
3280 | Returns the serial port associated with the given slot.
|
---|
3281 | Slots are numbered sequentially, starting with zero. The total
|
---|
3282 | number of serial ports per every machine is defined by the
|
---|
3283 | <link to="ISystemProperties::serialPortCount"/> property,
|
---|
3284 | so the maximum slot number is one less than that property's value.
|
---|
3285 | </desc>
|
---|
3286 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
3287 | <param name="port" type="ISerialPort" dir="return"/>
|
---|
3288 | </method>
|
---|
3289 |
|
---|
3290 | <method name="getParallelPort" const="yes">
|
---|
3291 | <desc>
|
---|
3292 | Returns the parallel port associated with the given slot.
|
---|
3293 | Slots are numbered sequentially, starting with zero. The total
|
---|
3294 | number of parallel ports per every machine is defined by the
|
---|
3295 | <link to="ISystemProperties::parallelPortCount"/> property,
|
---|
3296 | so the maximum slot number is one less than that property's value.
|
---|
3297 | </desc>
|
---|
3298 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
3299 | <param name="port" type="IParallelPort" dir="return"/>
|
---|
3300 | </method>
|
---|
3301 |
|
---|
3302 | <method name="getNextExtraDataKey">
|
---|
3303 | <desc>
|
---|
3304 | Returns the machine-specific extra data key name following the
|
---|
3305 | supplied key.
|
---|
3306 |
|
---|
3307 | An error is returned if the supplied @a key does not exist. @c NULL is
|
---|
3308 | returned in @a nextKey if the supplied key is the last key. When
|
---|
3309 | supplying @c NULL for the @a key, the first key item is returned in @a
|
---|
3310 | nextKey (if there is any). @a nextValue is an optional parameter and
|
---|
3311 | if supplied, the next key's value is returned in it.
|
---|
3312 | </desc>
|
---|
3313 | <param name="key" type="wstring" dir="in">
|
---|
3314 | <desc>Name of the data key to follow.</desc>
|
---|
3315 | </param>
|
---|
3316 | <param name="nextKey" type="wstring" dir="out">
|
---|
3317 | <desc>Name of the next data key.</desc>
|
---|
3318 | </param>
|
---|
3319 | <param name="nextValue" type="wstring" dir="out">
|
---|
3320 | <desc>Value of the next data key.</desc>
|
---|
3321 | </param>
|
---|
3322 | </method>
|
---|
3323 |
|
---|
3324 | <method name="getExtraData">
|
---|
3325 | <desc>
|
---|
3326 | Returns associated machine-specific extra data.
|
---|
3327 |
|
---|
3328 | If the reuqested data @a key does not exist, this function will
|
---|
3329 | succeed and return @c NULL in the @a value argument.
|
---|
3330 | </desc>
|
---|
3331 | <param name="key" type="wstring" dir="in">
|
---|
3332 | <desc>Name of the data key to get.</desc>
|
---|
3333 | </param>
|
---|
3334 | <param name="value" type="wstring" dir="return">
|
---|
3335 | <desc>Value of the requested data key.</desc>
|
---|
3336 | </param>
|
---|
3337 | </method>
|
---|
3338 |
|
---|
3339 | <method name="setExtraData">
|
---|
3340 | <desc>
|
---|
3341 | Sets associated machine-specific extra data.
|
---|
3342 |
|
---|
3343 | If you pass @c NULL as a key @a vaule, the given @a key will be
|
---|
3344 | deleted.
|
---|
3345 |
|
---|
3346 | <note>
|
---|
3347 | Before performing the actual data change, this method will ask all
|
---|
3348 | registered callbacks using the
|
---|
3349 | <link to="IVirtualBoxCallback::onExtraDataCanChange()"/>
|
---|
3350 | notification for a permission. If one of the callbacks refuses the
|
---|
3351 | new value, the change will not be performed.
|
---|
3352 | </note>
|
---|
3353 | <note>
|
---|
3354 | On success, the
|
---|
3355 | <link to="IVirtualBoxCallback::onExtraDataChange()"/> notification
|
---|
3356 | is called to inform all registered callbacks about a successful data
|
---|
3357 | change.
|
---|
3358 | </note>
|
---|
3359 | <note>
|
---|
3360 | This method can be called outside the machine session and therefore
|
---|
3361 | it's a caller's responsibility to handle possible race conditions
|
---|
3362 | when several clients change the same key at the same time.
|
---|
3363 | </note>
|
---|
3364 | </desc>
|
---|
3365 | <param name="key" type="wstring" dir="in">
|
---|
3366 | <desc>Name of the data key to set.</desc>
|
---|
3367 | </param>
|
---|
3368 | <param name="value" type="wstring" dir="in">
|
---|
3369 | <desc>Value to assign to the key.</desc>
|
---|
3370 | </param>
|
---|
3371 | </method>
|
---|
3372 |
|
---|
3373 | <method name="saveSettings">
|
---|
3374 | <desc>
|
---|
3375 | Saves any changes to machine settings made since the session
|
---|
3376 | has been opened or a new machine has been created, or since the
|
---|
3377 | last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>.
|
---|
3378 | For registered machines, new settings become visible to all
|
---|
3379 | other VirtualBox clients after successful invocation of this
|
---|
3380 | method.
|
---|
3381 | <note>
|
---|
3382 | The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/>
|
---|
3383 | notification event after the configuration has been successfully
|
---|
3384 | saved (only for registered machines).
|
---|
3385 | </note>
|
---|
3386 | <note>
|
---|
3387 | Calling this method is only valid on instances returned
|
---|
3388 | by <link to="ISession::machine"/> and on new machines
|
---|
3389 | created by <link to="IVirtualBox::createMachine"/> but not
|
---|
3390 | yet registered, or on unregistered machines after calling
|
---|
3391 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
3392 | </note>
|
---|
3393 | </desc>
|
---|
3394 | </method>
|
---|
3395 |
|
---|
3396 | <method name="saveSettingsWithBackup">
|
---|
3397 | <desc>
|
---|
3398 | Creates a backup copy of the machine settings file (<link
|
---|
3399 | to="#settingsFilePath"/>) in case of auto-conversion, and then calls
|
---|
3400 | <link to="#saveSettings()"/>.
|
---|
3401 |
|
---|
3402 | Note that the backup copy is created <b>only</b> if the settings file
|
---|
3403 | auto-conversion took place (see <link to="#settingsFileVersion"/> for
|
---|
3404 | details). Otherwise, this call is fully equivalent to
|
---|
3405 | <link to="#saveSettings()"/> and no backup copying is done.
|
---|
3406 |
|
---|
3407 | The backup copy is created in the same directory where the original
|
---|
3408 | settings file is located. It is given the following file name:
|
---|
3409 | <pre>
|
---|
3410 | original.xml.x.y-platform.bak
|
---|
3411 | </pre>
|
---|
3412 | where <tt>original.xml</tt> is the original settings file name
|
---|
3413 | (excluding path), and <tt>x.y-platform</tt> is the version of the old
|
---|
3414 | format of the settings file (before auto-conversion).
|
---|
3415 |
|
---|
3416 | If the given backup file already exists, this method will try to add the
|
---|
3417 | <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
|
---|
3418 | 0 to 9) and copy it again until it succeeds. If all suffixes are
|
---|
3419 | occupied, or if any other copy error occurs, this method will return a
|
---|
3420 | failure.
|
---|
3421 |
|
---|
3422 | If the copy operation succeeds, the @a bakFileName return argument will
|
---|
3423 | receive a full path to the created backup file (for informational
|
---|
3424 | purposes). Note that this will happen even if the subsequent
|
---|
3425 | <link to="#saveSettings()"/> call performed by this method after the
|
---|
3426 | copy operation, fails.
|
---|
3427 |
|
---|
3428 | <note>
|
---|
3429 | The VirtualBox API never calls this method. It is intended purely for
|
---|
3430 | the purposes of creating backup copies of the settings files by
|
---|
3431 | front-ends before saving the results of the automatically performed
|
---|
3432 | settings conversion to disk.
|
---|
3433 | </note>
|
---|
3434 |
|
---|
3435 | <see>settingsFileVersion</see>
|
---|
3436 | </desc>
|
---|
3437 | <param name="bakFileName" type="wstring" dir="return">
|
---|
3438 | <desc>Full path to the created backup copy.</desc>
|
---|
3439 | </param>
|
---|
3440 | </method>
|
---|
3441 |
|
---|
3442 | <method name="discardSettings">
|
---|
3443 | <desc>
|
---|
3444 | Discards any changes to the machine settings made since the session
|
---|
3445 | has been opened or since the last call to <link to="#saveSettings()"/>
|
---|
3446 | or <link to="#discardSettings"/>.
|
---|
3447 | <note>
|
---|
3448 | Calling this method is only valid on instances returned
|
---|
3449 | by <link to="ISession::machine"/> and on new machines
|
---|
3450 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
3451 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
3452 | yet registered, or on unregistered machines after calling
|
---|
3453 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
3454 | </note>
|
---|
3455 | </desc>
|
---|
3456 | </method>
|
---|
3457 |
|
---|
3458 | <method name="deleteSettings">
|
---|
3459 | <desc>
|
---|
3460 | Deletes the settings file of this machine from disk.
|
---|
3461 | The machine must not be registered in order for this operation
|
---|
3462 | to succeed.
|
---|
3463 | <note>
|
---|
3464 | <link to="#settingsModified"/> will return TRUE after this
|
---|
3465 | method successfully returns.
|
---|
3466 | </note>
|
---|
3467 | <note>
|
---|
3468 | Calling this method is only valid on instances returned
|
---|
3469 | by <link to="ISession::machine"/> and on new machines
|
---|
3470 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
3471 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
3472 | yet registered, or on unregistered machines after calling
|
---|
3473 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
3474 | </note>
|
---|
3475 | <note>
|
---|
3476 | The deleted machine settings file can be restored (saved again)
|
---|
3477 | by calling <link to="#saveSettings()"/>.
|
---|
3478 | </note>
|
---|
3479 | </desc>
|
---|
3480 | </method>
|
---|
3481 |
|
---|
3482 | <method name="getSnapshot">
|
---|
3483 | <desc>
|
---|
3484 | Returns a snapshot of this machine with the given UUID.
|
---|
3485 | A <tt>null</tt> UUID can be used to obtain the first snapshot
|
---|
3486 | taken on this machine. This is useful if you want to traverse
|
---|
3487 | the whole tree of snapshots starting from the root.
|
---|
3488 | </desc>
|
---|
3489 | <param name="id" type="uuid" dir="in">
|
---|
3490 | <desc>UUID of the snapshot to get</desc>
|
---|
3491 | </param>
|
---|
3492 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
3493 | <desc>Snapshot object with the given UUID.</desc>
|
---|
3494 | </param>
|
---|
3495 | </method>
|
---|
3496 |
|
---|
3497 | <method name="findSnapshot">
|
---|
3498 | <desc>
|
---|
3499 | Returns a snapshot of this machine with the given name.
|
---|
3500 | </desc>
|
---|
3501 | <param name="name" type="wstring" dir="in">
|
---|
3502 | <desc>Name of the snapshot to find</desc>
|
---|
3503 | </param>
|
---|
3504 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
3505 | <desc>Snapshot object with the given name.</desc>
|
---|
3506 | </param>
|
---|
3507 | </method>
|
---|
3508 |
|
---|
3509 | <method name="setCurrentSnapshot">
|
---|
3510 | <desc>
|
---|
3511 | Sets the current snapshot of this machine.
|
---|
3512 | <note>
|
---|
3513 | In the current implementation, this operation is not
|
---|
3514 | implemented.
|
---|
3515 | </note>
|
---|
3516 | </desc>
|
---|
3517 | <param name="id" type="uuid" dir="in">
|
---|
3518 | <desc>UUID of the snapshot to set as the current snapshot.</desc>
|
---|
3519 | </param>
|
---|
3520 | </method>
|
---|
3521 |
|
---|
3522 | <method name="createSharedFolder">
|
---|
3523 | <desc>
|
---|
3524 | Creates a new permanent shared folder by associating the given logical
|
---|
3525 | name with the given host path, adds it to the collection of shared
|
---|
3526 | folders and starts sharing it. Refer to the description of
|
---|
3527 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
3528 | </desc>
|
---|
3529 | <param name="name" type="wstring" dir="in">
|
---|
3530 | <desc>Unique logical name of the shared folder.</desc>
|
---|
3531 | </param>
|
---|
3532 | <param name="hostPath" type="wstring" dir="in">
|
---|
3533 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
3534 | </param>
|
---|
3535 | <param name="writable" type="boolean" dir="in">
|
---|
3536 | <desc>Whether the share is writable or readonly</desc>
|
---|
3537 | </param>
|
---|
3538 | </method>
|
---|
3539 |
|
---|
3540 | <method name="removeSharedFolder">
|
---|
3541 | <desc>
|
---|
3542 | Removes the permanent shared folder with the given name previously
|
---|
3543 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
3544 | shared folders and stops sharing it.
|
---|
3545 | </desc>
|
---|
3546 | <param name="name" type="wstring" dir="in">
|
---|
3547 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
3548 | </param>
|
---|
3549 | </method>
|
---|
3550 |
|
---|
3551 | <method name="canShowConsoleWindow">
|
---|
3552 | <desc>
|
---|
3553 | Returns @c true if the VM console process can activate the
|
---|
3554 | console window and bring it to foreground on the desktop of
|
---|
3555 | the host PC.
|
---|
3556 | <note>
|
---|
3557 | This method will fail if a session for this machine is not
|
---|
3558 | currently open.
|
---|
3559 | </note>
|
---|
3560 | </desc>
|
---|
3561 | <param name="canShow" type="boolean" dir="return">
|
---|
3562 | <desc>
|
---|
3563 | @c true if the console window can be shown and @c
|
---|
3564 | false otherwise.
|
---|
3565 | </desc>
|
---|
3566 | </param>
|
---|
3567 | </method>
|
---|
3568 |
|
---|
3569 | <method name="showConsoleWindow">
|
---|
3570 | <desc>
|
---|
3571 | Activates the console window and brings it to foreground on
|
---|
3572 | the desktop of the host PC. Many modern window managers on
|
---|
3573 | many platforms implement some sort of focus stealing
|
---|
3574 | prevention logic, so that it may be impossible to activate
|
---|
3575 | a window without the help of the currently active
|
---|
3576 | application. In this case, this method will return a non-zero
|
---|
3577 | identifier that represents the top-level window of the VM
|
---|
3578 | console process. The caller, if it represents a currently
|
---|
3579 | active process, is responsible to use this identifier (in a
|
---|
3580 | platform-dependent manner) to perform actual window
|
---|
3581 | activation.
|
---|
3582 | <note>
|
---|
3583 | This method will fail if a session for this machine is not
|
---|
3584 | currently open.
|
---|
3585 | </note>
|
---|
3586 | </desc>
|
---|
3587 | <param name="winId" type="unsigned long long" dir="return">
|
---|
3588 | <desc>
|
---|
3589 | Platform-dependent identifier of the top-level VM console
|
---|
3590 | window, or zero if this method has performed all actions
|
---|
3591 | necessary to implement the <i>show window</i> semantics for
|
---|
3592 | the given platform and/or VirtualBox front-end.
|
---|
3593 | </desc>
|
---|
3594 | </param>
|
---|
3595 | </method>
|
---|
3596 |
|
---|
3597 | <method name="getGuestProperty">
|
---|
3598 | <desc>
|
---|
3599 | Reads an entry from the machine's guest property store.
|
---|
3600 | </desc>
|
---|
3601 | <param name="name" type="wstring" dir="in">
|
---|
3602 | <desc>
|
---|
3603 | The name of the property to read.
|
---|
3604 | </desc>
|
---|
3605 | </param>
|
---|
3606 | <param name="value" type="wstring" dir="out">
|
---|
3607 | <desc>
|
---|
3608 | The value of the property. If the property does not exist then this
|
---|
3609 | will be empty.
|
---|
3610 | </desc>
|
---|
3611 | </param>
|
---|
3612 | <param name="timestamp" type="unsigned long long" dir="out">
|
---|
3613 | <desc>
|
---|
3614 | The time at which the property was last modified, as seen by the
|
---|
3615 | server process.
|
---|
3616 | </desc>
|
---|
3617 | </param>
|
---|
3618 | <param name="flags" type="wstring" dir="out">
|
---|
3619 | <desc>
|
---|
3620 | Additional property parameters, passed as a comma-separated list of
|
---|
3621 | "name=value" type entries.
|
---|
3622 | </desc>
|
---|
3623 | </param>
|
---|
3624 | </method>
|
---|
3625 |
|
---|
3626 | <method name="getGuestPropertyValue">
|
---|
3627 | <desc>
|
---|
3628 | Reads a value from the machine's guest property store.
|
---|
3629 | </desc>
|
---|
3630 | <param name="property" type="wstring" dir="in">
|
---|
3631 | <desc>
|
---|
3632 | The name of the property to read.
|
---|
3633 | </desc>
|
---|
3634 | </param>
|
---|
3635 | <param name="value" type="wstring" dir="return">
|
---|
3636 | <desc>
|
---|
3637 | The value of the property. If the property does not exist then this
|
---|
3638 | will be empty.
|
---|
3639 | </desc>
|
---|
3640 | </param>
|
---|
3641 | </method>
|
---|
3642 |
|
---|
3643 | <method name="getGuestPropertyTimestamp">
|
---|
3644 | <desc>
|
---|
3645 | Reads a property timestamp from the machine's guest property store.
|
---|
3646 | </desc>
|
---|
3647 | <param name="property" type="wstring" dir="in">
|
---|
3648 | <desc>
|
---|
3649 | The name of the property to read.
|
---|
3650 | </desc>
|
---|
3651 | </param>
|
---|
3652 | <param name="value" type="unsigned long long" dir="return">
|
---|
3653 | <desc>
|
---|
3654 | The timestamp. If the property does not exist then this will be
|
---|
3655 | empty.
|
---|
3656 | </desc>
|
---|
3657 | </param>
|
---|
3658 | </method>
|
---|
3659 |
|
---|
3660 | <method name="setGuestProperty">
|
---|
3661 | <desc>
|
---|
3662 | Sets, changes or deletes an entry in the machine's guest property
|
---|
3663 | store.
|
---|
3664 | </desc>
|
---|
3665 | <param name="property" type="wstring" dir="in">
|
---|
3666 | <desc>
|
---|
3667 | The name of the property to set, change or delete.
|
---|
3668 | </desc>
|
---|
3669 | </param>
|
---|
3670 | <param name="value" type="wstring" dir="in">
|
---|
3671 | <desc>
|
---|
3672 | The new value of the property to set, change or delete. If the
|
---|
3673 | property does not yet exist and value is non-empty, it will be
|
---|
3674 | created. If the value is empty, the key will be deleted if it
|
---|
3675 | exists.
|
---|
3676 | </desc>
|
---|
3677 | </param>
|
---|
3678 | <param name="flags" type="wstring" dir="in">
|
---|
3679 | <desc>
|
---|
3680 | Additional property parameters, passed as a comma-separated list of
|
---|
3681 | "name=value" type entries.
|
---|
3682 | </desc>
|
---|
3683 | </param>
|
---|
3684 | </method>
|
---|
3685 |
|
---|
3686 | <method name="setGuestPropertyValue">
|
---|
3687 | <desc>
|
---|
3688 | Sets, changes or deletes a value in the machine's guest property
|
---|
3689 | store. The flags field will be left unchanged or created empty for a
|
---|
3690 | new property.
|
---|
3691 | </desc>
|
---|
3692 | <param name="property" type="wstring" dir="in">
|
---|
3693 | <desc>
|
---|
3694 | The name of the property to set, change or delete.
|
---|
3695 | </desc>
|
---|
3696 | </param>
|
---|
3697 | <param name="value" type="wstring" dir="in">
|
---|
3698 | <desc>
|
---|
3699 | The new value of the property to set, change or delete. If the
|
---|
3700 | property does not yet exist and value is non-empty, it will be
|
---|
3701 | created. If value is empty, the property will be deleted if it
|
---|
3702 | exists.
|
---|
3703 | </desc>
|
---|
3704 | </param>
|
---|
3705 | </method>
|
---|
3706 |
|
---|
3707 | <method name="enumerateGuestProperties">
|
---|
3708 | <desc>
|
---|
3709 | Return a list of the guest properties matching a set of patterns along
|
---|
3710 | with their values, timestamps and flags.
|
---|
3711 | </desc>
|
---|
3712 | <param name="patterns" type="wstring" dir="in">
|
---|
3713 | <desc>
|
---|
3714 | The patterns to match the properties against as a comma-separated
|
---|
3715 | string with no spaces. If this is empty, all properties currently
|
---|
3716 | set will be returned.
|
---|
3717 | </desc>
|
---|
3718 | </param>
|
---|
3719 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
3720 | <desc>
|
---|
3721 | The names of the properties returned.
|
---|
3722 | </desc>
|
---|
3723 | </param>
|
---|
3724 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
3725 | <desc>
|
---|
3726 | The values of the properties returned. The array entries match the
|
---|
3727 | corresponding entries in the @a name array.
|
---|
3728 | </desc>
|
---|
3729 | </param>
|
---|
3730 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
3731 | <desc>
|
---|
3732 | The timestamps of the properties returned. The array entries match
|
---|
3733 | the corresponding entries in the @a name array.
|
---|
3734 | </desc>
|
---|
3735 | </param>
|
---|
3736 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
3737 | <desc>
|
---|
3738 | The flags of the properties returned. The array entries match the
|
---|
3739 | corresponding entries in the @a name array.
|
---|
3740 | </desc>
|
---|
3741 | </param>
|
---|
3742 | </method>
|
---|
3743 | </interface>
|
---|
3744 |
|
---|
3745 | <!--
|
---|
3746 | // IConsole
|
---|
3747 | /////////////////////////////////////////////////////////////////////////
|
---|
3748 | -->
|
---|
3749 |
|
---|
3750 | <interface
|
---|
3751 | name="IConsoleCallback" extends="$unknown"
|
---|
3752 | uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
|
---|
3753 | wsmap="suppress"
|
---|
3754 | >
|
---|
3755 |
|
---|
3756 | <method name="onMousePointerShapeChange">
|
---|
3757 | <desc>
|
---|
3758 | Notification when the guest mouse pointer shape has
|
---|
3759 | changed. The new shape data is given.
|
---|
3760 | </desc>
|
---|
3761 | <param name="visible" type="boolean" dir="in">
|
---|
3762 | <desc>
|
---|
3763 | Flag whether the pointer is visible.
|
---|
3764 | </desc>
|
---|
3765 | </param>
|
---|
3766 | <param name="alpha" type="boolean" dir="in">
|
---|
3767 | <desc>
|
---|
3768 | Flag whether the pointer has an alpha channel.
|
---|
3769 | </desc>
|
---|
3770 | </param>
|
---|
3771 | <param name="xHot" type="unsigned long" dir="in">
|
---|
3772 | <desc>
|
---|
3773 | The pointer hot spot x coordinate.
|
---|
3774 | </desc>
|
---|
3775 | </param>
|
---|
3776 | <param name="yHot" type="unsigned long" dir="in">
|
---|
3777 | <desc>
|
---|
3778 | The pointer hot spot y coordinate.
|
---|
3779 | </desc>
|
---|
3780 | </param>
|
---|
3781 | <param name="width" type="unsigned long" dir="in">
|
---|
3782 | <desc>
|
---|
3783 | Width of the pointer shape in pixels.
|
---|
3784 | </desc>
|
---|
3785 | </param>
|
---|
3786 | <param name="height" type="unsigned long" dir="in">
|
---|
3787 | <desc>
|
---|
3788 | Height of the pointer shape in pixels.
|
---|
3789 | </desc>
|
---|
3790 | </param>
|
---|
3791 | <param name="shape" type="octet" mod="ptr" dir="in">
|
---|
3792 | <desc>
|
---|
3793 | Address of the shape buffer.
|
---|
3794 |
|
---|
3795 | The buffer contains 1 bpp (bits per pixel) AND mask followed by 32 bpp XOR (color) mask.
|
---|
3796 |
|
---|
3797 | For pointers without alpha channel the XOR mask pixels are 32 bit values: (lsb)BGR0(msb).
|
---|
3798 | For pointers with alpha channel the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
|
---|
3799 |
|
---|
3800 | AND mask presents for pointers with alpha channel, so if the callback does not
|
---|
3801 | support alpha, the pointer could be displayed as a normal color pointer.
|
---|
3802 |
|
---|
3803 | The AND mask is 1 bpp bitmap with byte aligned scanlines. Size of AND mask,
|
---|
3804 | therefore, is <tt>cbAnd = (width + 7) / 8 * height</tt>. The padding bits at the
|
---|
3805 | end of any scanline are undefined.
|
---|
3806 |
|
---|
3807 | The XOR mask follows the AND mask on the next 4 bytes aligned offset:
|
---|
3808 | <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>
|
---|
3809 | Bytes in the gap between the AND and the XOR mask are undefined.
|
---|
3810 | XOR mask scanlines have no gap between them and size of XOR mask is:
|
---|
3811 | <tt>cXor = width * 4 * height</tt>.
|
---|
3812 |
|
---|
3813 | <note>
|
---|
3814 | If 'shape' is equal to 0, only pointer visibility is being changed.
|
---|
3815 | </note>
|
---|
3816 | </desc>
|
---|
3817 | </param>
|
---|
3818 | </method>
|
---|
3819 |
|
---|
3820 | <method name="onMouseCapabilityChange">
|
---|
3821 | <desc>
|
---|
3822 | Notification when the mouse capabilities reported by the
|
---|
3823 | guest have changed. The new capabilities are passed.
|
---|
3824 | </desc>
|
---|
3825 | <param name="supportsAbsolute" type="boolean" dir="in"/>
|
---|
3826 | <param name="needsHostCursor" type="boolean" dir="in"/>
|
---|
3827 | </method>
|
---|
3828 |
|
---|
3829 | <method name="onKeyboardLedsChange">
|
---|
3830 | <desc>
|
---|
3831 | Notification when the guest OS executes the KBD_CMD_SET_LEDS command
|
---|
3832 | to alter the state of the keyboard LEDs.
|
---|
3833 | </desc>
|
---|
3834 | <param name="numLock" type="boolean" dir="in"/>
|
---|
3835 | <param name="capsLock" type="boolean" dir="in"/>
|
---|
3836 | <param name="scrollLock" type="boolean" dir="in"/>
|
---|
3837 | </method>
|
---|
3838 |
|
---|
3839 | <method name="onStateChange">
|
---|
3840 | <desc>
|
---|
3841 | Notification when the execution state of the machine has changed.
|
---|
3842 | The new state will be given.
|
---|
3843 | </desc>
|
---|
3844 | <param name="state" type="MachineState" dir="in"/>
|
---|
3845 | </method>
|
---|
3846 |
|
---|
3847 | <method name="onAdditionsStateChange">
|
---|
3848 | <desc>
|
---|
3849 | Notification when a Guest Additions property changes.
|
---|
3850 | Interested callees should query IGuest attributes to
|
---|
3851 | find out what has changed.
|
---|
3852 | </desc>
|
---|
3853 | </method>
|
---|
3854 |
|
---|
3855 | <method name="onDVDDriveChange">
|
---|
3856 | <desc>
|
---|
3857 | Notification when a property of the
|
---|
3858 | virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
|
---|
3859 | Interested callees should use IDVDDrive methods to find out what has
|
---|
3860 | changed.
|
---|
3861 | </desc>
|
---|
3862 | </method>
|
---|
3863 |
|
---|
3864 | <method name="onFloppyDriveChange">
|
---|
3865 | <desc>
|
---|
3866 | Notification when a property of the
|
---|
3867 | virtual <link to="IMachine::FloppyDrive">floppy drive</link> changes.
|
---|
3868 | Interested callees should use IFloppyDrive methods to find out what
|
---|
3869 | has changed.
|
---|
3870 | </desc>
|
---|
3871 | </method>
|
---|
3872 |
|
---|
3873 | <method name="onNetworkAdapterChange">
|
---|
3874 | <desc>
|
---|
3875 | Notification when a property of one of the
|
---|
3876 | virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
|
---|
3877 | changes. Interested callees should use INetworkAdapter methods and
|
---|
3878 | attributes to find out what has changed.
|
---|
3879 | </desc>
|
---|
3880 | <param name="networkAdapter" type="INetworkAdapter" dir="in">
|
---|
3881 | <desc>Network adapter that is subject to change.</desc>
|
---|
3882 | </param>
|
---|
3883 | </method>
|
---|
3884 |
|
---|
3885 | <method name="onSerialPortChange">
|
---|
3886 | <desc>
|
---|
3887 | Notification when a property of one of the
|
---|
3888 | virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
|
---|
3889 | Interested callees should use ISerialPort methods and attributes
|
---|
3890 | to find out what has changed.
|
---|
3891 | </desc>
|
---|
3892 | <param name="serialPort" type="ISerialPort" dir="in">
|
---|
3893 | <desc>Serial port that is subject to change.</desc>
|
---|
3894 | </param>
|
---|
3895 | </method>
|
---|
3896 |
|
---|
3897 | <method name="onParallelPortChange">
|
---|
3898 | <desc>
|
---|
3899 | Notification when a property of one of the
|
---|
3900 | virtual <link to="IMachine::getParallelPort">parallel ports</link>
|
---|
3901 | changes. Interested callees should use ISerialPort methods and
|
---|
3902 | attributes to find out what has changed.
|
---|
3903 | </desc>
|
---|
3904 | <param name="parallelPort" type="IParallelPort" dir="in">
|
---|
3905 | <desc>Parallel port that is subject to change.</desc>
|
---|
3906 | </param>
|
---|
3907 | </method>
|
---|
3908 |
|
---|
3909 | <method name="onVRDPServerChange">
|
---|
3910 | <desc>
|
---|
3911 | Notification when a property of the
|
---|
3912 | <link to="IMachine::VRDPServer">VRDP server</link> changes.
|
---|
3913 | Interested callees should use IVRDPServer methods and attributes to
|
---|
3914 | find out what has changed.
|
---|
3915 | </desc>
|
---|
3916 | </method>
|
---|
3917 |
|
---|
3918 | <method name="onUSBControllerChange">
|
---|
3919 | <desc>
|
---|
3920 | Notification when a property of the virtual
|
---|
3921 | <link to="IMachine::USBController">USB controller</link> changes.
|
---|
3922 | Interested callees should use IUSBController methods and attributes to
|
---|
3923 | find out what has changed.
|
---|
3924 | </desc>
|
---|
3925 | </method>
|
---|
3926 |
|
---|
3927 | <method name="onUSBDeviceStateChange">
|
---|
3928 | <desc>
|
---|
3929 | Notification when a USB device is attached to or detached from
|
---|
3930 | the virtual USB controller.
|
---|
3931 |
|
---|
3932 | This notification is sent as a result of the indirect
|
---|
3933 | request to attach the device because it matches one of the
|
---|
3934 | machine USB filters, or as a result of the direct request
|
---|
3935 | issued by <link to="IConsole::attachUSBDevice"/> or
|
---|
3936 | <link to="IConsole::detachUSBDevice"/>.
|
---|
3937 |
|
---|
3938 | This notification is sent in case of both a succeeded and a
|
---|
3939 | failed request completion. When the request succeeds, the @a
|
---|
3940 | error parameter is @c null, and the given device has been
|
---|
3941 | already added to (when @a attached is @c true) or removed from
|
---|
3942 | (when @a attached is @c false) the collection represented by
|
---|
3943 | <link to="IConsole::USBDevices"/>. On failure, the collection
|
---|
3944 | doesn't change and the @a error perameter represents the error
|
---|
3945 | message describing the failure.
|
---|
3946 |
|
---|
3947 | </desc>
|
---|
3948 | <param name="device" type="IUSBDevice" dir="in">
|
---|
3949 | <desc>Device that is subject to state change.</desc>
|
---|
3950 | </param>
|
---|
3951 | <param name="attached" type="boolean" dir="in">
|
---|
3952 | <desc>
|
---|
3953 | <tt>true</tt> if the device was attached
|
---|
3954 | and <tt>false</tt> otherwise.
|
---|
3955 | </desc>
|
---|
3956 | </param>
|
---|
3957 | <param name="error" type="IVirtualBoxErrorInfo" dir="in">
|
---|
3958 | <desc>
|
---|
3959 | <tt>null</tt> on success or an error message object on
|
---|
3960 | failure.
|
---|
3961 | </desc>
|
---|
3962 | </param>
|
---|
3963 | </method>
|
---|
3964 |
|
---|
3965 | <method name="onSharedFolderChange">
|
---|
3966 | <desc>
|
---|
3967 | Notification when a shared folder is added or removed.
|
---|
3968 | The @a scope argument defines one of three scopes:
|
---|
3969 | <link to="IVirtualBox::sharedFolders">global shared folders</link>
|
---|
3970 | (<link to="Scope::Global">Global</link>),
|
---|
3971 | <link to="IMachine::sharedFolders">permanent shared folders</link> of
|
---|
3972 | the machine (<link to="Scope::Machine">Machine</link>) or <link
|
---|
3973 | to="IConsole::sharedFolders">transient shared folders</link> of the
|
---|
3974 | machine (<link to="Scope::Session">Session</link>). Interested callees
|
---|
3975 | should use query the corresponding collections to find out what has
|
---|
3976 | changed.
|
---|
3977 | </desc>
|
---|
3978 | <param name="scope" type="Scope" dir="in">
|
---|
3979 | <desc>Sope of the notification.</desc>
|
---|
3980 | </param>
|
---|
3981 | </method>
|
---|
3982 |
|
---|
3983 | <method name="onRuntimeError">
|
---|
3984 | <desc>
|
---|
3985 | Notification when an error happens during the virtual
|
---|
3986 | machine execution.
|
---|
3987 |
|
---|
3988 | There are three kinds of runtime errors:
|
---|
3989 | <ul>
|
---|
3990 | <li><i>fatal</i></li>
|
---|
3991 | <li><i>non-fatal with retry</i></li>
|
---|
3992 | <li><i>non-fatal warnings</i></li>
|
---|
3993 | </ul>
|
---|
3994 |
|
---|
3995 | <b>Fatal</b> errors are indicated by the @a fatal parameter set
|
---|
3996 | to <tt>true</tt>. In case of fatal errors, the virtual machine
|
---|
3997 | execution is always paused before calling this notification, and
|
---|
3998 | the notification handler is supposed either to immediately save
|
---|
3999 | the virtual machine state using <link to="IConsole::saveState()"/>
|
---|
4000 | or power it off using <link to="IConsole::powerDown()"/>.
|
---|
4001 | Resuming the execution can lead to unpredictable results.
|
---|
4002 |
|
---|
4003 | <b>Non-fatal</b> errors and warnings are indicated by the
|
---|
4004 | @a fatal parameter set to <tt>false</tt>. If the virtual machine
|
---|
4005 | is in the Paused state by the time the error notification is
|
---|
4006 | received, it means that the user can <i>try to resume</i> the machine
|
---|
4007 | execution after attempting to solve the probem that caused the
|
---|
4008 | error. In this case, the notification handler is supposed
|
---|
4009 | to show an appropriate message to the user (depending on the
|
---|
4010 | value of the @a id parameter) that offers several actions such
|
---|
4011 | as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
|
---|
4012 | wants to retry, the notification handler should continue
|
---|
4013 | the machine execution using the <link to="IConsole::resume()"/>
|
---|
4014 | call. If the machine execution is not Paused during this
|
---|
4015 | notification, then it means this notification is a <i>warning</i>
|
---|
4016 | (for example, about a fatal condition that can happen very soon);
|
---|
4017 | no immediate action is required from the user, the machine
|
---|
4018 | continues its normal execution.
|
---|
4019 |
|
---|
4020 | Note that in either case the notification handler
|
---|
4021 | <b>must not</b> perform any action directly on a thread
|
---|
4022 | where this notification is called. Everything it is allowed to
|
---|
4023 | do is to post a message to another thread that will then talk
|
---|
4024 | to the user and take the corresponding action.
|
---|
4025 |
|
---|
4026 | Currently, the following error identificators are known:
|
---|
4027 | <ul>
|
---|
4028 | <li><tt>"HostMemoryLow"</tt></li>
|
---|
4029 | <li><tt>"HostAudioNotResponding"</tt></li>
|
---|
4030 | <li><tt>"VDIStorageFull"</tt></li>
|
---|
4031 | </ul>
|
---|
4032 |
|
---|
4033 | <note>
|
---|
4034 | This notification is not designed to be implemented by
|
---|
4035 | more than one callback at a time. If you have multiple
|
---|
4036 | IConsoleCallback instances registered on the given
|
---|
4037 | IConsole object, make sure you simply do nothing but
|
---|
4038 | return @c S_OK from all but one of them that does actual
|
---|
4039 | user notification and performs necessary actions.
|
---|
4040 | </note>
|
---|
4041 |
|
---|
4042 | </desc>
|
---|
4043 | <param name="fatal" type="boolean" dir="in">
|
---|
4044 | <desc>Whether the error is fatal or not</desc>
|
---|
4045 | </param>
|
---|
4046 | <param name="id" type="wstring" dir="in">
|
---|
4047 | <desc>Error identificator</desc>
|
---|
4048 | </param>
|
---|
4049 | <param name="message" type="wstring" dir="in">
|
---|
4050 | <desc>Optional error message</desc>
|
---|
4051 | </param>
|
---|
4052 | </method>
|
---|
4053 |
|
---|
4054 | <method name="onCanShowWindow">
|
---|
4055 | <desc>
|
---|
4056 | Notification when a call to
|
---|
4057 | <link to="IMachine::canShowConsoleWindow()"/> is made by a
|
---|
4058 | front-end to check if a subsequent call to
|
---|
4059 | <link to="IMachine::showConsoleWindow()"/> can succeed.
|
---|
4060 |
|
---|
4061 | The callee should give an answer appropriate to the current
|
---|
4062 | machine state in the @a canShow argument. This answer must
|
---|
4063 | remain valid at least until the next
|
---|
4064 | <link to="IConsole::state">machine state</link> change.
|
---|
4065 |
|
---|
4066 | <note>
|
---|
4067 | This notification is not designed to be implemented by
|
---|
4068 | more than one callback at a time. If you have multiple
|
---|
4069 | IConsoleCallback instances registered on the given
|
---|
4070 | IConsole object, make sure you simply do nothing but
|
---|
4071 | return @c true and @c S_OK from all but one of them that
|
---|
4072 | actually manages console window activation.
|
---|
4073 | </note>
|
---|
4074 | </desc>
|
---|
4075 | <param name="canShow" type="boolean" dir="return">
|
---|
4076 | <desc>
|
---|
4077 | @c true if the console window can be shown and @c
|
---|
4078 | false otherwise.
|
---|
4079 | </desc>
|
---|
4080 | </param>
|
---|
4081 | </method>
|
---|
4082 |
|
---|
4083 | <method name="onShowWindow">
|
---|
4084 | <desc>
|
---|
4085 | Notification when a call to
|
---|
4086 | <link to="IMachine::showConsoleWindow()"/>
|
---|
4087 | requests the console window to be activated and brought to
|
---|
4088 | foreground on the desktop of the host PC.
|
---|
4089 |
|
---|
4090 | This notification should cause the VM console process to
|
---|
4091 | perform the requested action as described above. If it is
|
---|
4092 | impossible to do it at a time of this notification, this
|
---|
4093 | method should return a failure.
|
---|
4094 |
|
---|
4095 | Note that many modern window managers on many platforms
|
---|
4096 | implement some sort of focus stealing prevention logic, so
|
---|
4097 | that it may be impossible to activate a window without the
|
---|
4098 | help of the currently active application (which is supposedly
|
---|
4099 | an initiator of this notification). In this case, this method
|
---|
4100 | must return a non-zero identifier that represents the
|
---|
4101 | top-level window of the VM console process. The caller, if it
|
---|
4102 | represents a currently active process, is responsible to use
|
---|
4103 | this identifier (in a platform-dependent manner) to perform
|
---|
4104 | actual window activation.
|
---|
4105 |
|
---|
4106 | This method must set @a winId to zero if it has performed all
|
---|
4107 | actions necessary to complete the request and the console
|
---|
4108 | window is now active and in foreground, to indicate that no
|
---|
4109 | further action is required on the caller's side.
|
---|
4110 |
|
---|
4111 | <note>
|
---|
4112 | This notification is not designed to be implemented by
|
---|
4113 | more than one callback at a time. If you have multiple
|
---|
4114 | IConsoleCallback instances registered on the given
|
---|
4115 | IConsole object, make sure you simply do nothing but
|
---|
4116 | return@c S_OK from all but one of them that actually
|
---|
4117 | manages console window activation.
|
---|
4118 | </note>
|
---|
4119 | </desc>
|
---|
4120 | <param name="winId" type="unsigned long long" dir="return">
|
---|
4121 | <desc>
|
---|
4122 | Platform-dependent identifier of the top-level VM console
|
---|
4123 | window, or zero if this method has performed all actions
|
---|
4124 | necessary to implement the <i>show window</i> semantics for
|
---|
4125 | the given platform and/or this VirtualBox front-end.
|
---|
4126 | </desc>
|
---|
4127 | </param>
|
---|
4128 | </method>
|
---|
4129 |
|
---|
4130 | </interface>
|
---|
4131 |
|
---|
4132 | <interface
|
---|
4133 | name="IRemoteDisplayInfo" extends="$unknown"
|
---|
4134 | uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
|
---|
4135 | wsmap="struct"
|
---|
4136 | >
|
---|
4137 | <desc>
|
---|
4138 | Contains information about the remote display (VRDP) capabilities and status.
|
---|
4139 | This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
|
---|
4140 | </desc>
|
---|
4141 |
|
---|
4142 | <attribute name="active" type="boolean" readonly="yes">
|
---|
4143 | <desc>
|
---|
4144 | Whether the remote display connection is active.
|
---|
4145 | </desc>
|
---|
4146 | </attribute>
|
---|
4147 |
|
---|
4148 | <attribute name="numberOfClients" type="unsigned long" readonly="yes">
|
---|
4149 | <desc>
|
---|
4150 | How many times a client connected.
|
---|
4151 | </desc>
|
---|
4152 | </attribute>
|
---|
4153 |
|
---|
4154 | <attribute name="beginTime" type="long long" readonly="yes">
|
---|
4155 | <desc>
|
---|
4156 | When the last connection was established, in milliseconds since 1970-01-01 UTC.
|
---|
4157 | </desc>
|
---|
4158 | </attribute>
|
---|
4159 |
|
---|
4160 | <attribute name="endTime" type="long long" readonly="yes">
|
---|
4161 | <desc>
|
---|
4162 | When the last connection was terminated or the current time, if
|
---|
4163 | connection is still active, in milliseconds since 1970-01-01 UTC.
|
---|
4164 | </desc>
|
---|
4165 | </attribute>
|
---|
4166 |
|
---|
4167 | <attribute name="bytesSent" type="unsigned long long" readonly="yes">
|
---|
4168 | <desc>
|
---|
4169 | How many bytes were sent in last or current, if still active, connection.
|
---|
4170 | </desc>
|
---|
4171 | </attribute>
|
---|
4172 |
|
---|
4173 | <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
|
---|
4174 | <desc>
|
---|
4175 | How many bytes were sent in all connections.
|
---|
4176 | </desc>
|
---|
4177 | </attribute>
|
---|
4178 |
|
---|
4179 | <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
|
---|
4180 | <desc>
|
---|
4181 | How many bytes were received in last or current, if still active, connection.
|
---|
4182 | </desc>
|
---|
4183 | </attribute>
|
---|
4184 |
|
---|
4185 | <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
|
---|
4186 | <desc>
|
---|
4187 | How many bytes were received in all connections.
|
---|
4188 | </desc>
|
---|
4189 | </attribute>
|
---|
4190 |
|
---|
4191 | <attribute name="user" type="wstring" readonly="yes">
|
---|
4192 | <desc>
|
---|
4193 | Login user name supplied by the client.
|
---|
4194 | </desc>
|
---|
4195 | </attribute>
|
---|
4196 |
|
---|
4197 | <attribute name="domain" type="wstring" readonly="yes">
|
---|
4198 | <desc>
|
---|
4199 | Login domain name supplied by the client.
|
---|
4200 | </desc>
|
---|
4201 | </attribute>
|
---|
4202 |
|
---|
4203 | <attribute name="clientName" type="wstring" readonly="yes">
|
---|
4204 | <desc>
|
---|
4205 | The client name supplied by the client.
|
---|
4206 | </desc>
|
---|
4207 | </attribute>
|
---|
4208 |
|
---|
4209 | <attribute name="clientIP" type="wstring" readonly="yes">
|
---|
4210 | <desc>
|
---|
4211 | The IP address of the client.
|
---|
4212 | </desc>
|
---|
4213 | </attribute>
|
---|
4214 |
|
---|
4215 | <attribute name="clientVersion" type="unsigned long" readonly="yes">
|
---|
4216 | <desc>
|
---|
4217 | The client software version number.
|
---|
4218 | </desc>
|
---|
4219 | </attribute>
|
---|
4220 |
|
---|
4221 | <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
|
---|
4222 | <desc>
|
---|
4223 | Public key exchange method used when connection was established.
|
---|
4224 | Values: 0 - RDP4 public key exchange scheme.
|
---|
4225 | 1 - X509 sertificates were sent to client.
|
---|
4226 | </desc>
|
---|
4227 | </attribute>
|
---|
4228 |
|
---|
4229 | </interface>
|
---|
4230 |
|
---|
4231 | <interface
|
---|
4232 | name="IConsole" extends="$unknown"
|
---|
4233 | uuid="d5a1cbda-f5d7-4824-9afe-d640c94c7dcf"
|
---|
4234 | wsmap="managed"
|
---|
4235 | >
|
---|
4236 | <desc>
|
---|
4237 | The IConsole interface represents an interface to control virtual
|
---|
4238 | machine execution.
|
---|
4239 |
|
---|
4240 | The console object that implements the IConsole interface is obtained
|
---|
4241 | from a session object after the session for the given machine has been
|
---|
4242 | opened using one of <link to="IVirtualBox::openSession"/>,
|
---|
4243 | <link to="IVirtualBox::openRemoteSession"/> or
|
---|
4244 | <link to="IVirtualBox::openExistingSession"/> methods.
|
---|
4245 |
|
---|
4246 | Methods of the IConsole interface allow the caller to query the current
|
---|
4247 | virtual machine execution state, pause the machine or power it down, save
|
---|
4248 | the machine state or take a snapshot, attach and detach removable media
|
---|
4249 | and so on.
|
---|
4250 |
|
---|
4251 | <see>ISession</see>
|
---|
4252 | </desc>
|
---|
4253 |
|
---|
4254 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
4255 | <desc>
|
---|
4256 | Machine object this console is sessioned with.
|
---|
4257 | <note>
|
---|
4258 | This is a convenience property, it has the same value as
|
---|
4259 | <link to="ISession::machine"/> of the corresponding session
|
---|
4260 | object.
|
---|
4261 | </note>
|
---|
4262 | </desc>
|
---|
4263 | </attribute>
|
---|
4264 |
|
---|
4265 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
4266 | <desc>
|
---|
4267 | Current execution state of the machine.
|
---|
4268 | <note>
|
---|
4269 | This property always returns the same value as the corresponding
|
---|
4270 | property of the IMachine object this console is sessioned with.
|
---|
4271 | For the process that owns (executes) the VM, this is the
|
---|
4272 | preferable way of querying the VM state, because no IPC
|
---|
4273 | calls are made.
|
---|
4274 | </note>
|
---|
4275 | </desc>
|
---|
4276 | </attribute>
|
---|
4277 |
|
---|
4278 | <attribute name="guest" type="IGuest" readonly="yes">
|
---|
4279 | <desc>Guest object.</desc>
|
---|
4280 | </attribute>
|
---|
4281 |
|
---|
4282 | <attribute name="keyboard" type="IKeyboard" readonly="yes">
|
---|
4283 | <desc>
|
---|
4284 | Virtual keyboard object.
|
---|
4285 | <note>
|
---|
4286 | If the machine is not running, any attempt to use
|
---|
4287 | the returned object will result in an error.
|
---|
4288 | </note>
|
---|
4289 | </desc>
|
---|
4290 | </attribute>
|
---|
4291 |
|
---|
4292 | <attribute name="mouse" type="IMouse" readonly="yes">
|
---|
4293 | <desc>
|
---|
4294 | Virtual mouse object.
|
---|
4295 | <note>
|
---|
4296 | If the machine is not running, any attempt to use
|
---|
4297 | the returned object will result in an error.
|
---|
4298 | </note>
|
---|
4299 | </desc>
|
---|
4300 | </attribute>
|
---|
4301 |
|
---|
4302 | <attribute name="display" type="IDisplay" readonly="yes">
|
---|
4303 | <desc>Virtual display object.
|
---|
4304 | <note>
|
---|
4305 | If the machine is not running, any attempt to use
|
---|
4306 | the returned object will result in an error.
|
---|
4307 | </note>
|
---|
4308 | </desc>
|
---|
4309 | </attribute>
|
---|
4310 |
|
---|
4311 | <attribute name="debugger" type="IMachineDebugger" readonly="yes">
|
---|
4312 | <desc>Debugging interface.</desc>
|
---|
4313 | </attribute>
|
---|
4314 |
|
---|
4315 | <attribute name="USBDevices" type="IUSBDeviceCollection" readonly="yes">
|
---|
4316 | <desc>
|
---|
4317 | Collection of USB devices currently attached to the virtual
|
---|
4318 | USB controller.
|
---|
4319 | <note>
|
---|
4320 | The collection is empty if the machine is not running.
|
---|
4321 | </note>
|
---|
4322 | </desc>
|
---|
4323 | </attribute>
|
---|
4324 |
|
---|
4325 | <attribute name="remoteUSBDevices" type="IHostUSBDeviceCollection" readonly="yes">
|
---|
4326 | <desc>
|
---|
4327 | List of USB devices currently attached to the remote VRDP client.
|
---|
4328 | Once a new device is physically attached to the remote host computer,
|
---|
4329 | it appears in this list and remains there until detached.
|
---|
4330 | </desc>
|
---|
4331 | </attribute>
|
---|
4332 |
|
---|
4333 | <attribute name="sharedFolders" type="ISharedFolderCollection" readonly="yes">
|
---|
4334 | <desc>
|
---|
4335 | Collection of shared folders for the current session. These folders
|
---|
4336 | are called transient shared folders because they are available to the
|
---|
4337 | guest OS running inside the associated virtual machine only for the
|
---|
4338 | duration of the session (as opposed to
|
---|
4339 | <link to="IMachine::sharedFolders"/> which represent permanent shared
|
---|
4340 | folders). When the session is closed (e.g. the machine is powered down),
|
---|
4341 | these folders are automatically discarded.
|
---|
4342 |
|
---|
4343 | New shared folders are added to the collection using
|
---|
4344 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
4345 | removed using <link to="#removeSharedFolder"/>.
|
---|
4346 | </desc>
|
---|
4347 | </attribute>
|
---|
4348 |
|
---|
4349 | <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
|
---|
4350 | <desc>
|
---|
4351 | Interface that provides information on Remote Display (VRDP) connection.
|
---|
4352 | </desc>
|
---|
4353 | </attribute>
|
---|
4354 |
|
---|
4355 | <method name="powerUp">
|
---|
4356 | <desc>
|
---|
4357 | Starts the virtual machine execution using the current machine
|
---|
4358 | state (i.e. its current execution state, current settings and
|
---|
4359 | current hard disks).
|
---|
4360 |
|
---|
4361 | If the machine is powered off or aborted, the execution will
|
---|
4362 | start from the beginning (as if the real hardware were just
|
---|
4363 | powered on).
|
---|
4364 |
|
---|
4365 | If the machine is in the <link to="MachineState::Saved"/> state,
|
---|
4366 | it will continue its execution the point where the state has
|
---|
4367 | been saved.
|
---|
4368 |
|
---|
4369 | <note>
|
---|
4370 | Unless you are trying to write a new VirtualBox front-end that
|
---|
4371 | performs direct machine execution (like the VirtualBox or VBoxSDL
|
---|
4372 | front-ends), don't call <link to="IConsole::powerUp"/> in a direct
|
---|
4373 | session opened by <link to="IVirtualBox::openSession"/> and use this
|
---|
4374 | session only to change virtual machine settings. If you simply want to
|
---|
4375 | start virtual machine execution using one of the existing front-ends
|
---|
4376 | (for example the VirtualBox GUI or headless server), simply use
|
---|
4377 | <link to="IVirtualBox::openRemoteSession"/>; these front-ends
|
---|
4378 | will power up the machine automatically for you.
|
---|
4379 | </note>
|
---|
4380 |
|
---|
4381 | <see>#saveState</see>
|
---|
4382 | </desc>
|
---|
4383 | <param name="progress" type="IProgress" dir="return">
|
---|
4384 | <desc>Progress object to track the operation completion.</desc>
|
---|
4385 | </param>
|
---|
4386 | </method>
|
---|
4387 |
|
---|
4388 | <method name="powerDown">
|
---|
4389 | <desc>
|
---|
4390 | Stops the virtual machine execution.
|
---|
4391 | After this operation completes, the machine will go to the
|
---|
4392 | PoweredOff state.
|
---|
4393 | </desc>
|
---|
4394 | </method>
|
---|
4395 |
|
---|
4396 | <method name="reset">
|
---|
4397 | <desc>Resets the virtual machine.</desc>
|
---|
4398 | </method>
|
---|
4399 |
|
---|
4400 | <method name="pause">
|
---|
4401 | <desc>Pauses the virtual machine execution.</desc>
|
---|
4402 | </method>
|
---|
4403 |
|
---|
4404 | <method name="resume">
|
---|
4405 | <desc>Resumes the virtual machine execution.</desc>
|
---|
4406 | </method>
|
---|
4407 |
|
---|
4408 | <method name="powerButton">
|
---|
4409 | <desc>Send the ACPI power button event to the guest.</desc>
|
---|
4410 | </method>
|
---|
4411 |
|
---|
4412 | <method name="sleepButton">
|
---|
4413 | <desc>Send the ACPI sleep button event to the guest.</desc>
|
---|
4414 | </method>
|
---|
4415 |
|
---|
4416 | <method name="getPowerButtonHandled">
|
---|
4417 | <desc>Check if the last power button event was handled by guest.</desc>
|
---|
4418 | <param name="handled" type="boolean" dir="return"/>
|
---|
4419 | </method>
|
---|
4420 |
|
---|
4421 | <method name="saveState">
|
---|
4422 | <desc>
|
---|
4423 | Saves the current execution state of a running virtual machine
|
---|
4424 | and stops its execution.
|
---|
4425 |
|
---|
4426 | After this operation completes, the machine will go to the
|
---|
4427 | Saved state. Next time it is powered up, this state will
|
---|
4428 | be restored and the machine will continue its execution from
|
---|
4429 | the place where it was saved.
|
---|
4430 |
|
---|
4431 | This operation differs from taking a snapshot to the effect
|
---|
4432 | that it doesn't create new differencing hard disks. Also, once
|
---|
4433 | the machine is powered up from the state saved using this method,
|
---|
4434 | the saved state is deleted, so it will be impossible to return
|
---|
4435 | to this state later.
|
---|
4436 |
|
---|
4437 | <note>
|
---|
4438 | On success, this method implicitly calls
|
---|
4439 | <link to="IMachine::saveSettings()"/> to save all current machine
|
---|
4440 | settings (including runtime changes to the DVD drive, etc.).
|
---|
4441 | Together with the impossibility to change any VM settings when it is
|
---|
4442 | in the Saved state, this guarantees the adequate hardware
|
---|
4443 | configuration of the machine when it is restored from the saved
|
---|
4444 | state file.
|
---|
4445 | </note>
|
---|
4446 |
|
---|
4447 | <note>
|
---|
4448 | The machine must be in the Running or Paused state, otherwise
|
---|
4449 | the operation will fail.
|
---|
4450 | </note>
|
---|
4451 |
|
---|
4452 | <see><link to="#takeSnapshot"/></see>
|
---|
4453 | </desc>
|
---|
4454 | <param name="progress" type="IProgress" dir="return">
|
---|
4455 | <desc>Progress object to track the operation completion.</desc>
|
---|
4456 | </param>
|
---|
4457 | </method>
|
---|
4458 |
|
---|
4459 | <method name="adoptSavedState">
|
---|
4460 | <desc>
|
---|
4461 | Associates the given saved state file to the virtual machine.
|
---|
4462 |
|
---|
4463 | On success, the machine will go to the Saved state. Next time it is
|
---|
4464 | powered up, it will be restored from the adopted saved state and
|
---|
4465 | continue execution from the place where the saved state file was
|
---|
4466 | created.
|
---|
4467 |
|
---|
4468 | The specified saved state file path may be full or relative to the
|
---|
4469 | folder the VM normally saves the state to (usually,
|
---|
4470 | <link to="IMachine::snapshotFolder"/>).
|
---|
4471 |
|
---|
4472 | <note>
|
---|
4473 | It's a caller's responsibility to make sure the given saved state
|
---|
4474 | file is compatible with the settings of this virtual machine that
|
---|
4475 | represent its virtual hardware (memory size, hard disk configuration
|
---|
4476 | etc.). If there is a mismatch, the behavior of the virtual machine
|
---|
4477 | is undefined.
|
---|
4478 | </note>
|
---|
4479 | </desc>
|
---|
4480 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
4481 | <desc>Path to the saved state file to adopt.</desc>
|
---|
4482 | </param>
|
---|
4483 | </method>
|
---|
4484 |
|
---|
4485 | <method name="discardSavedState">
|
---|
4486 | <desc>
|
---|
4487 | Discards (deletes) the saved state of the virtual machine
|
---|
4488 | previously created by <link to="#saveState"/>. Next time the
|
---|
4489 | machine is powered up, a clean boot will occur.
|
---|
4490 | <note>
|
---|
4491 | This operation is equivalent to resetting or powering off
|
---|
4492 | the machine without doing a proper shutdown in the guest OS.
|
---|
4493 | </note>
|
---|
4494 | </desc>
|
---|
4495 | </method>
|
---|
4496 |
|
---|
4497 | <method name="getDeviceActivity">
|
---|
4498 | <desc>
|
---|
4499 | Gets the current activity type of a given device or device group.
|
---|
4500 | </desc>
|
---|
4501 | <param name="type" type="DeviceType" dir="in"/>
|
---|
4502 | <param name="activity" type="DeviceActivity" dir="return"/>
|
---|
4503 | </method>
|
---|
4504 |
|
---|
4505 | <method name="attachUSBDevice">
|
---|
4506 | <desc>
|
---|
4507 | Attaches a host USB device with the given UUID to the
|
---|
4508 | USB controller of the virtual machine.
|
---|
4509 |
|
---|
4510 | The device needs to be in one of the following states:
|
---|
4511 | <link to="USBDeviceState::Busy">Busy</link>,
|
---|
4512 | <link to="USBDeviceState::Available">Available</link> or
|
---|
4513 | <link to="USBDeviceState::Held">Held</link>,
|
---|
4514 | otherwise an error is immediately returned.
|
---|
4515 |
|
---|
4516 | When the device state is
|
---|
4517 | <link to="USBDeviceState::Busy">Busy</link>, an error may also
|
---|
4518 | be returned if the host computer refuses to release it for some reason.
|
---|
4519 |
|
---|
4520 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
4521 | </desc>
|
---|
4522 | <param name="id" type="uuid" dir="in">
|
---|
4523 | <desc>UUID of the host USB device to attach.</desc>
|
---|
4524 | </param>
|
---|
4525 | </method>
|
---|
4526 |
|
---|
4527 | <method name="detachUSBDevice">
|
---|
4528 | <desc>
|
---|
4529 | Detaches an USB device with the given UUID from the USB controller
|
---|
4530 | oif the virtual machine.
|
---|
4531 |
|
---|
4532 | After this method succeeds, the VirtualBox server reinitiates
|
---|
4533 | all USB filters as if the device were just physically attached
|
---|
4534 | to the host, but filters of this machine are ignored to avoid
|
---|
4535 | a possible automatic reattachment.
|
---|
4536 |
|
---|
4537 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
4538 | </desc>
|
---|
4539 | <param name="id" type="uuid" dir="in">
|
---|
4540 | <desc>UUID of the USB device to detach.</desc>
|
---|
4541 | </param>
|
---|
4542 | <param name="device" type="IUSBDevice" dir="return">
|
---|
4543 | <desc>Detached USB device.</desc>
|
---|
4544 | </param>
|
---|
4545 | </method>
|
---|
4546 |
|
---|
4547 | <method name="createSharedFolder">
|
---|
4548 | <desc>
|
---|
4549 | Creates a transient new shared folder by associating the given logical
|
---|
4550 | name with the given host path, adds it to the collection of shared
|
---|
4551 | folders and starts sharing it. Refer to the description of
|
---|
4552 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
4553 | </desc>
|
---|
4554 | <param name="name" type="wstring" dir="in">
|
---|
4555 | <desc>Unique logical name of the shared folder.</desc>
|
---|
4556 | </param>
|
---|
4557 | <param name="hostPath" type="wstring" dir="in">
|
---|
4558 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
4559 | </param>
|
---|
4560 | <param name="writable" type="boolean" dir="in">
|
---|
4561 | <desc>Whether the share is writable or readonly</desc>
|
---|
4562 | </param>
|
---|
4563 | </method>
|
---|
4564 |
|
---|
4565 | <method name="removeSharedFolder">
|
---|
4566 | <desc>
|
---|
4567 | Removes a transient shared folder with the given name previously
|
---|
4568 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
4569 | shared folders and stops sharing it.
|
---|
4570 | </desc>
|
---|
4571 | <param name="name" type="wstring" dir="in">
|
---|
4572 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
4573 | </param>
|
---|
4574 | </method>
|
---|
4575 |
|
---|
4576 | <method name="takeSnapshot">
|
---|
4577 | <desc>
|
---|
4578 | Saves the current execution state and all settings of the
|
---|
4579 | machine and creates differencing images for all
|
---|
4580 | normal (non-independent) hard disks.
|
---|
4581 |
|
---|
4582 | This method can be called for a PoweredOff, Saved, Running or
|
---|
4583 | Paused virtual machine. When the machine is PoweredOff, an
|
---|
4584 | offline <link to="ISnapshot">snapshot</link> is created,
|
---|
4585 | in all other cases -- an online snapshot.
|
---|
4586 |
|
---|
4587 | The taken snapshot is always based on the
|
---|
4588 | <link to="IMachine::currentSnapshot">current
|
---|
4589 | snapshot</link> of the associated virtual machine and becomes
|
---|
4590 | a new current snapshot.
|
---|
4591 |
|
---|
4592 | <note>
|
---|
4593 | This method implicitly calls <link to="IMachine::saveSettings()"/> to
|
---|
4594 | save all current machine settings before taking an offline snapshot.
|
---|
4595 | </note>
|
---|
4596 |
|
---|
4597 | <see>ISnapshot, <link to="#saveState"/></see>
|
---|
4598 | </desc>
|
---|
4599 | <param name="name" type="wstring" dir="in">
|
---|
4600 | <desc>Short name for the snapshot.</desc>
|
---|
4601 | </param>
|
---|
4602 | <param name="description" type="wstring" dir="in">
|
---|
4603 | <desc>Optional description of the snapshot.</desc>
|
---|
4604 | </param>
|
---|
4605 | <param name="progress" type="IProgress" dir="return">
|
---|
4606 | <desc>Progress object to track the operation completion.</desc>
|
---|
4607 | </param>
|
---|
4608 | </method>
|
---|
4609 |
|
---|
4610 | <method name="discardSnapshot">
|
---|
4611 | <desc>
|
---|
4612 |
|
---|
4613 | Starts discarding the specified snapshot. The execution state
|
---|
4614 | and settings of the associated machine stored in the snapshot
|
---|
4615 | will be deleted. The contents of all differencing hard disks of
|
---|
4616 | this snapshot will be merged with the contents of their
|
---|
4617 | dependent child hard disks to keep the, disks valid (in other
|
---|
4618 | words, all changes represented by hard disks being discarded
|
---|
4619 | will be propagated to their child hard disks). After that, this
|
---|
4620 | snapshot's differencing hard disks will be deleted. The parent
|
---|
4621 | of this snapshot will become a new parent for all its child
|
---|
4622 | snapshots.
|
---|
4623 |
|
---|
4624 | If the discarded snapshot is the current one, its parent
|
---|
4625 | snapshot will become a new current snapshot. The current machine
|
---|
4626 | state is not directly affected in this case, except that
|
---|
4627 | currently attached differencing hard disks based on hard disks
|
---|
4628 | of the discarded snapshot will be also merged as described
|
---|
4629 | above.
|
---|
4630 |
|
---|
4631 | If the discarded snapshot is the first one (the root snapshot)
|
---|
4632 | and it has exactly one child snapshot, this child snapshot will
|
---|
4633 | become the first snapshot after discarding. If there are no
|
---|
4634 | children at all (i.e. the first snapshot is the only snapshot of
|
---|
4635 | the machine), both the current and the first snapshot of the
|
---|
4636 | machine will be set to null. In all other cases, the first
|
---|
4637 | snapshot cannot be discarded.
|
---|
4638 |
|
---|
4639 | You cannot discard the snapshot if it
|
---|
4640 | stores <link to="HardDiskType::Normal">normal</link> (non-differencing)
|
---|
4641 | hard disks that have differencing hard disks based on them. Snapshots of
|
---|
4642 | such kind can be discarded only when every normal hard disk has either
|
---|
4643 | no children at all or exactly one child. In the former case, the normal
|
---|
4644 | hard disk simply becomes unused (i.e. not attached to any VM). In the
|
---|
4645 | latter case, it receives all the changes strored in the child hard disk,
|
---|
4646 | and then it replaces the child hard disk in the configuration of the
|
---|
4647 | corresponding snapshot or machine.
|
---|
4648 |
|
---|
4649 | Also, you cannot discard the snapshot if it stores hard disks
|
---|
4650 | (of any type) having differencing child hard disks that belong
|
---|
4651 | to other machines. Such snapshots can be only discarded after
|
---|
4652 | you discard all snapshots of other machines containing "foreign"
|
---|
4653 | child disks, or detach these "foreign" child disks from machines
|
---|
4654 | they are attached to.
|
---|
4655 |
|
---|
4656 | One particular example of the snapshot storing normal hard disks
|
---|
4657 | is the first snapshot of a virtual machine that had normal hard
|
---|
4658 | disks attached when taking the snapshot. Be careful when
|
---|
4659 | discarding such snapshots because this implicitly commits
|
---|
4660 | changes (made since the snapshot being discarded has been taken)
|
---|
4661 | to normal hard disks (as described above), which may be not what
|
---|
4662 | you want.
|
---|
4663 |
|
---|
4664 | The virtual machine is put to
|
---|
4665 | the <link to="MachineState::Discarding">Discarding</link> state until
|
---|
4666 | the discard operation is completed.
|
---|
4667 |
|
---|
4668 | <note>
|
---|
4669 | The machine must not be running, otherwise the operation
|
---|
4670 | will fail.
|
---|
4671 | </note>
|
---|
4672 |
|
---|
4673 | <note>
|
---|
4674 | Child hard disks of all normal hard disks of the discarded snapshot
|
---|
4675 | must be <link to="IHardDisk::accessible">accessible</link> for this
|
---|
4676 | operation to succeed. In particular, this means that all virtual
|
---|
4677 | machines, whose hard disks are directly or indirectly based on the
|
---|
4678 | hard disks of discarded snapshot, must be powered off.
|
---|
4679 | </note>
|
---|
4680 | <note>
|
---|
4681 | Merging hard disk contents can be very time and disk space
|
---|
4682 | consuming, if these disks are big in size and have many
|
---|
4683 | children. However, if the snapshot being discarded is the last
|
---|
4684 | (head) snapshot on the branch, the operation will be rather
|
---|
4685 | quick.
|
---|
4686 | </note>
|
---|
4687 | <note>
|
---|
4688 | Note that discarding the current snapshot
|
---|
4689 | will imlicitly call <link to="IMachine::saveSettings()"/> to
|
---|
4690 | make all current machine settings permanent.
|
---|
4691 | </note>
|
---|
4692 | </desc>
|
---|
4693 | <param name="id" type="uuid" dir="in">
|
---|
4694 | <desc>UUID of the snapshot to discard.</desc>
|
---|
4695 | </param>
|
---|
4696 | <param name="progress" type="IProgress" dir="return">
|
---|
4697 | <desc>Progress object to track the operation completion.</desc>
|
---|
4698 | </param>
|
---|
4699 | </method>
|
---|
4700 |
|
---|
4701 | <method name="discardCurrentState">
|
---|
4702 | <desc>
|
---|
4703 | This operation is similar to <link to="#discardSnapshot()"/> but
|
---|
4704 | affects the current machine state. This means that the state stored in
|
---|
4705 | the current snapshot will become a new current state, and all current
|
---|
4706 | settings of the machine and changes stored in differencing hard disks
|
---|
4707 | will be lost.
|
---|
4708 |
|
---|
4709 | After this operation is successfully completed, new empty differencing
|
---|
4710 | hard disks are created for all normal hard disks of the machine.
|
---|
4711 |
|
---|
4712 | If the current snapshot of the machine is an online snapshot, the
|
---|
4713 | machine will go to the <link to="MachineState::Saved"> saved
|
---|
4714 | state</link>, so that the next time it is powered on, the execution
|
---|
4715 | state will be restored from the current snapshot.
|
---|
4716 |
|
---|
4717 | <note>
|
---|
4718 | The machine must not be running, otherwise the operation will fail.
|
---|
4719 | </note>
|
---|
4720 |
|
---|
4721 | <note>
|
---|
4722 | If the machine state is <link to="MachineState::Saved">Saved</link>
|
---|
4723 | prior to this operation, the saved state file will be implicitly
|
---|
4724 | discarded (as if <link to="IConsole::discardSavedState()"/> were
|
---|
4725 | called).
|
---|
4726 | </note>
|
---|
4727 |
|
---|
4728 | </desc>
|
---|
4729 | <param name="progress" type="IProgress" dir="return">
|
---|
4730 | <desc>Progress object to track the operation completion.</desc>
|
---|
4731 | </param>
|
---|
4732 | </method>
|
---|
4733 |
|
---|
4734 | <method name="discardCurrentSnapshotAndState">
|
---|
4735 | <desc>
|
---|
4736 |
|
---|
4737 | This method is equivalent to
|
---|
4738 | doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
|
---|
4739 | (currentSnapshot.id(), progress) followed by
|
---|
4740 | <link to="#discardCurrentState()"/>.
|
---|
4741 |
|
---|
4742 | As a result, the machine will be fully restored from the
|
---|
4743 | snapshot preceeding the current snapshot, while both the current
|
---|
4744 | snapshot and the current machine state will be discarded.
|
---|
4745 |
|
---|
4746 | If the current snapshot is the first snapshot of the machine (i.e. it
|
---|
4747 | has the only snapshot), the current machine state will be
|
---|
4748 | discarded <b>before</b> discarding the snapshot. In other words, the
|
---|
4749 | machine will be restored from its last snapshot, before discarding
|
---|
4750 | it. This differs from performing a single
|
---|
4751 | <link to="#discardSnapshot()"/> call (note that no
|
---|
4752 | <link to="#discardCurrentState()"/> will be possible after it)
|
---|
4753 | to the effect that the latter will preserve the current state instead of
|
---|
4754 | discarding it.
|
---|
4755 |
|
---|
4756 | Unless explicitly mentioned otherwise, all remarks and
|
---|
4757 | limitations of the above two methods also apply to this method.
|
---|
4758 |
|
---|
4759 | <note>
|
---|
4760 | The machine must not be running, otherwise the operation
|
---|
4761 | will fail.
|
---|
4762 | </note>
|
---|
4763 |
|
---|
4764 | <note>
|
---|
4765 | If the machine state is <link to="MachineState::Saved">Saved</link>
|
---|
4766 | prior to this operation, the saved state file will be implicitly
|
---|
4767 | discarded (as if <link to="#discardSavedState()"/> were
|
---|
4768 | called).
|
---|
4769 | </note>
|
---|
4770 |
|
---|
4771 | <note>
|
---|
4772 | This method is more efficient than calling two above
|
---|
4773 | methods separately: it requires less IPC calls and provides
|
---|
4774 | a single progress object.
|
---|
4775 | </note>
|
---|
4776 |
|
---|
4777 | </desc>
|
---|
4778 | <param name="progress" type="IProgress" dir="return">
|
---|
4779 | <desc>Progress object to track the operation completion.</desc>
|
---|
4780 | </param>
|
---|
4781 | </method>
|
---|
4782 |
|
---|
4783 | <method name="registerCallback">
|
---|
4784 | <desc>
|
---|
4785 | Registers a new console callback on this instance. The methods of the
|
---|
4786 | callback interface will be called by this instance when the appropriate
|
---|
4787 | event occurs.
|
---|
4788 | </desc>
|
---|
4789 | <param name="callback" type="IConsoleCallback" dir="in"/>
|
---|
4790 | </method>
|
---|
4791 |
|
---|
4792 | <method name="unregisterCallback">
|
---|
4793 | <desc>
|
---|
4794 | Unregisters the console callback previously registered using
|
---|
4795 | <link to="#registerCallback"/>.
|
---|
4796 | </desc>
|
---|
4797 | <param name="callback" type="IConsoleCallback" dir="in"/>
|
---|
4798 | </method>
|
---|
4799 | </interface>
|
---|
4800 |
|
---|
4801 | <!--
|
---|
4802 | // IHost
|
---|
4803 | /////////////////////////////////////////////////////////////////////////
|
---|
4804 | -->
|
---|
4805 |
|
---|
4806 | <interface
|
---|
4807 | name="IHostDVDDrive" extends="$unknown"
|
---|
4808 | uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
|
---|
4809 | wsmap="managed"
|
---|
4810 | >
|
---|
4811 | <desc>
|
---|
4812 | The IHostDVDDrive interface represents the physical CD/DVD drive
|
---|
4813 | hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
|
---|
4814 | </desc>
|
---|
4815 |
|
---|
4816 | <attribute name="name" type="wstring" readonly="yes">
|
---|
4817 | <desc>
|
---|
4818 | Returns the platform-specific device identifier.
|
---|
4819 | On DOS-like platforms, it is a drive name (e.g. R:).
|
---|
4820 | On Unix-like platforms, it is a device name (e.g. /dev/hdc).
|
---|
4821 | </desc>
|
---|
4822 | </attribute>
|
---|
4823 | <attribute name="description" type="wstring" readonly="yes">
|
---|
4824 | <desc>
|
---|
4825 | Returns a human readable description for the drive. This
|
---|
4826 | description usually contains the product and vendor name. A
|
---|
4827 | @c null string is returned if the description is not available.
|
---|
4828 | </desc>
|
---|
4829 | </attribute>
|
---|
4830 | <attribute name="udi" type="wstring" readonly="yes">
|
---|
4831 | <desc>
|
---|
4832 | Returns the unique device identifier for the drive. This
|
---|
4833 | attribute is reserved for future use instead of
|
---|
4834 | <link to="#name"/>. Currently it is not used and may return
|
---|
4835 | @c null on some platforms.
|
---|
4836 | </desc>
|
---|
4837 | </attribute>
|
---|
4838 |
|
---|
4839 | </interface>
|
---|
4840 |
|
---|
4841 | <enumerator
|
---|
4842 | name="IHostDVDDriveEnumerator" type="IHostDVDDrive"
|
---|
4843 | uuid="1ed7cfaf-c363-40df-aa4e-89c1afb7d96b"
|
---|
4844 | />
|
---|
4845 |
|
---|
4846 | <collection
|
---|
4847 | name="IHostDVDDriveCollection" type="IHostDVDDrive"
|
---|
4848 | enumerator="IHostDVDDriveEnumerator"
|
---|
4849 | uuid="1909c533-1a1e-445f-a4e1-a267cffc30ed"
|
---|
4850 | readonly="yes"
|
---|
4851 | >
|
---|
4852 | <method name="findByName">
|
---|
4853 | <desc>
|
---|
4854 | Searches this collection for a host drive with the given name.
|
---|
4855 | <note>
|
---|
4856 | The method returns an error if the given name does not
|
---|
4857 | correspond to any host drive in the collection.
|
---|
4858 | </note>
|
---|
4859 | </desc>
|
---|
4860 | <param name="name" type="wstring" dir="in">
|
---|
4861 | <desc>Name of the host drive to search for</desc>
|
---|
4862 | </param>
|
---|
4863 | <param name="drive" type="IHostDVDDrive" dir="return">
|
---|
4864 | <desc>Found host drive object</desc>
|
---|
4865 | </param>
|
---|
4866 | </method>
|
---|
4867 | </collection>
|
---|
4868 |
|
---|
4869 | <interface
|
---|
4870 | name="IHostFloppyDrive" extends="$unknown"
|
---|
4871 | uuid="b6a4d1a9-4221-43c3-bd52-021a5daa9ed2"
|
---|
4872 | wsmap="managed"
|
---|
4873 | >
|
---|
4874 | <desc>
|
---|
4875 | The IHostFloppyDrive interface represents the physical floppy drive
|
---|
4876 | hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
|
---|
4877 | </desc>
|
---|
4878 | <attribute name="name" type="wstring" readonly="yes">
|
---|
4879 | <desc>
|
---|
4880 | Returns the platform-specific device identifier.
|
---|
4881 | On DOS-like platforms, it is a drive name (e.g. A:).
|
---|
4882 | On Unix-like platforms, it is a device name (e.g. /dev/fd0).
|
---|
4883 | </desc>
|
---|
4884 | </attribute>
|
---|
4885 | <attribute name="description" type="wstring" readonly="yes">
|
---|
4886 | <desc>
|
---|
4887 | Returns a human readable description for the drive. This
|
---|
4888 | description usually contains the product and vendor name. A
|
---|
4889 | @c null string is returned if the description is not available.
|
---|
4890 | </desc>
|
---|
4891 | </attribute>
|
---|
4892 | <attribute name="udi" type="wstring" readonly="yes">
|
---|
4893 | <desc>
|
---|
4894 | Returns the unique device identifier for the drive. This
|
---|
4895 | attribute is reserved for future use instead of
|
---|
4896 | <link to="#name"/>. Currently it is not used and may return
|
---|
4897 | @c null on some platforms.
|
---|
4898 | </desc>
|
---|
4899 | </attribute>
|
---|
4900 | </interface>
|
---|
4901 |
|
---|
4902 | <enumerator
|
---|
4903 | name="IHostFloppyDriveEnumerator" type="IHostFloppyDrive"
|
---|
4904 | uuid="ce04c924-4f54-432a-9dec-11fddc3ea875"
|
---|
4905 | />
|
---|
4906 |
|
---|
4907 | <collection
|
---|
4908 | name="IHostFloppyDriveCollection" type="IHostFloppyDrive"
|
---|
4909 | enumerator="IHostFloppyDriveEnumerator"
|
---|
4910 | uuid="fd84bb86-c59a-4037-a557-755ff263a460"
|
---|
4911 | readonly="yes"
|
---|
4912 | >
|
---|
4913 | <method name="findByName">
|
---|
4914 | <desc>
|
---|
4915 | Searches this collection for a host drive with the given name.
|
---|
4916 | <note>
|
---|
4917 | The method returns an error if the given name does not
|
---|
4918 | correspond to any host drive in the collection.
|
---|
4919 | </note>
|
---|
4920 | </desc>
|
---|
4921 | <param name="name" type="wstring" dir="in">
|
---|
4922 | <desc>Name of the host drive to search for</desc>
|
---|
4923 | </param>
|
---|
4924 | <param name="drive" type="IHostFloppyDrive" dir="return">
|
---|
4925 | <desc>Found host drive object</desc>
|
---|
4926 | </param>
|
---|
4927 | </method>
|
---|
4928 | </collection>
|
---|
4929 |
|
---|
4930 | <interface
|
---|
4931 | name="IHostNetworkInterface" extends="$unknown"
|
---|
4932 | uuid="F4512D7C-B074-4e97-99B8-6D2BD27C3F5A"
|
---|
4933 | wsmap="managed"
|
---|
4934 | >
|
---|
4935 | <attribute name="name" type="wstring" readonly="yes">
|
---|
4936 | <desc>Returns the host network interface name.</desc>
|
---|
4937 | </attribute>
|
---|
4938 |
|
---|
4939 | <attribute name="id" type="uuid" readonly="yes">
|
---|
4940 | <desc>Returns the interface UUID.</desc>
|
---|
4941 | </attribute>
|
---|
4942 | </interface>
|
---|
4943 |
|
---|
4944 | <enumerator
|
---|
4945 | name="IHostNetworkInterfaceEnumerator" type="IHostNetworkInterface"
|
---|
4946 | uuid="7B52FEF7-56E8-4aec-92F5-15E6D11EC630"
|
---|
4947 | />
|
---|
4948 |
|
---|
4949 | <collection
|
---|
4950 | name="IHostNetworkInterfaceCollection" type="IHostNetworkInterface"
|
---|
4951 | enumerator="IHostNetworkInterfaceEnumerator"
|
---|
4952 | uuid="BF1D41F2-B97B-4314-A0FB-D4823AF42FB5"
|
---|
4953 | readonly="yes"
|
---|
4954 | >
|
---|
4955 | <method name="findByName">
|
---|
4956 | <desc>
|
---|
4957 | Searches this collection for a host network interface with the given name.
|
---|
4958 | <note>
|
---|
4959 | The method returns an error if the given name does not
|
---|
4960 | correspond to any host network interface in the collection.
|
---|
4961 | </note>
|
---|
4962 | </desc>
|
---|
4963 | <param name="name" type="wstring" dir="in">
|
---|
4964 | <desc>Name of the host network interface to search for.</desc>
|
---|
4965 | </param>
|
---|
4966 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
4967 | <desc>Found host network interface object.</desc>
|
---|
4968 | </param>
|
---|
4969 | </method>
|
---|
4970 | <method name="findById">
|
---|
4971 | <desc>
|
---|
4972 | Searches this collection for a host network interface with the given GUID.
|
---|
4973 | <note>
|
---|
4974 | The method returns an error if the given GUID does not
|
---|
4975 | correspond to any host network interface in the collection.
|
---|
4976 | </note>
|
---|
4977 | </desc>
|
---|
4978 | <param name="id" type="uuid" dir="in">
|
---|
4979 | <desc>GUID of the host network interface to search for.</desc>
|
---|
4980 | </param>
|
---|
4981 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
4982 | <desc>Found host network interface object.</desc>
|
---|
4983 | </param>
|
---|
4984 | </method>
|
---|
4985 | </collection>
|
---|
4986 |
|
---|
4987 | <interface
|
---|
4988 | name="IHost" extends="$unknown"
|
---|
4989 | uuid="489fb370-c227-4d43-9761-ceb28484fd9f"
|
---|
4990 | wsmap="managed"
|
---|
4991 | >
|
---|
4992 | <desc>
|
---|
4993 | The IHost interface represents the physical machine that this VirtualBox
|
---|
4994 | installation runs on.
|
---|
4995 |
|
---|
4996 | An object implementing this interface is returned by the
|
---|
4997 | <link to="IVirtualBox::host" /> attribute. This interface contains
|
---|
4998 | read-only information about the host's physical hardware (such as what
|
---|
4999 | processors, and disks are available, what the host operating system is,
|
---|
5000 | and so on) and also allows for manipulating some of the host's hardware,
|
---|
5001 | such as global USB device filters and host interface networking.
|
---|
5002 |
|
---|
5003 | </desc>
|
---|
5004 | <attribute name="DVDDrives" type="IHostDVDDriveCollection" readonly="yes">
|
---|
5005 | <desc>List of DVD drives available on the host.</desc>
|
---|
5006 | </attribute>
|
---|
5007 |
|
---|
5008 | <attribute name="floppyDrives" type="IHostFloppyDriveCollection" readonly="yes">
|
---|
5009 | <desc>List of floppy drives available on the host.</desc>
|
---|
5010 | </attribute>
|
---|
5011 |
|
---|
5012 | <attribute name="USBDevices" type="IHostUSBDeviceCollection" readonly="yes">
|
---|
5013 | <desc>
|
---|
5014 | List of USB devices currently attached to the host.
|
---|
5015 | Once a new device is physically attached to the host computer,
|
---|
5016 | it appears in this list and remains there until detached.
|
---|
5017 |
|
---|
5018 | <note>
|
---|
5019 | This method may set a @ref com_warnings "warning result code".
|
---|
5020 | </note>
|
---|
5021 | <note>
|
---|
5022 | If USB functionality is not avaliable in the given edition of
|
---|
5023 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
5024 | </note>
|
---|
5025 | </desc>
|
---|
5026 | </attribute>
|
---|
5027 |
|
---|
5028 | <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilterCollection" readonly="yes">
|
---|
5029 | <desc>
|
---|
5030 | List of USB device filters in action.
|
---|
5031 | When a new device is physically attached to the host computer,
|
---|
5032 | filters from this list are applied to it (in order they are stored
|
---|
5033 | in the list). The first matched filter will determine the
|
---|
5034 | <link to="IHostUSBDeviceFilter::action">action</link>
|
---|
5035 | performed on the device.
|
---|
5036 |
|
---|
5037 | Unless the device is ignored by these filters, filters of all
|
---|
5038 | currently running virtual machines
|
---|
5039 | (<link to="IUSBController::deviceFilters"/>) are applied to it.
|
---|
5040 |
|
---|
5041 | <note>
|
---|
5042 | This method may set a @ref com_warnings "warning result code".
|
---|
5043 | </note>
|
---|
5044 | <note>
|
---|
5045 | If USB functionality is not avaliable in the given edition of
|
---|
5046 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
5047 | </note>
|
---|
5048 |
|
---|
5049 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
5050 | </desc>
|
---|
5051 | </attribute>
|
---|
5052 |
|
---|
5053 | <attribute name="networkInterfaces" type="IHostNetworkInterfaceCollection" readonly="yes">
|
---|
5054 | <desc>List of host network interfaces currently defined on the host.</desc>
|
---|
5055 | </attribute>
|
---|
5056 |
|
---|
5057 | <attribute name="processorCount" type="unsigned long" readonly="yes">
|
---|
5058 | <desc>Number of (logical) CPUs installed in the host system.</desc>
|
---|
5059 | </attribute>
|
---|
5060 |
|
---|
5061 | <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
|
---|
5062 | <desc>Number of (logical) CPUs online in the host system.</desc>
|
---|
5063 | </attribute>
|
---|
5064 |
|
---|
5065 | <method name="getProcessorSpeed">
|
---|
5066 | <desc>Query the (approximate) maximum speed of a specified host CPU in Megahertz.</desc>
|
---|
5067 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
5068 | <desc>
|
---|
5069 | Identifier of the CPU.
|
---|
5070 | </desc>
|
---|
5071 | </param>
|
---|
5072 | <param name="speed" type="unsigned long" dir="return">
|
---|
5073 | <desc>
|
---|
5074 | Speed value. 0 is returned if value is not known or @a cpuId is
|
---|
5075 | invalid.
|
---|
5076 | </desc>
|
---|
5077 | </param>
|
---|
5078 | </method>
|
---|
5079 |
|
---|
5080 | <method name="getProcessorDescription">
|
---|
5081 | <desc>Query the model string of a specified host CPU.</desc>
|
---|
5082 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
5083 | <desc>
|
---|
5084 | Identifier of the CPU.
|
---|
5085 | </desc>
|
---|
5086 | </param>
|
---|
5087 | <param name="description" type="wstring" dir="return">
|
---|
5088 | <desc>
|
---|
5089 | Model string. A NULL string is returned if value is not known or
|
---|
5090 | @a cpuId is invalid.
|
---|
5091 | </desc>
|
---|
5092 | </param>
|
---|
5093 | </method>
|
---|
5094 |
|
---|
5095 | <attribute name="memorySize" type="unsigned long" readonly="yes">
|
---|
5096 | <desc>Amount of system memory in megabytes installed in the host system.</desc>
|
---|
5097 | </attribute>
|
---|
5098 |
|
---|
5099 | <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
|
---|
5100 | <desc>Available system memory in the host system.</desc>
|
---|
5101 | </attribute>
|
---|
5102 |
|
---|
5103 | <attribute name="operatingSystem" type="wstring" readonly="yes">
|
---|
5104 | <desc>Name of the host system's operating system.</desc>
|
---|
5105 | </attribute>
|
---|
5106 |
|
---|
5107 | <attribute name="OSVersion" type="wstring" readonly="yes">
|
---|
5108 | <desc>Host operating system's version string.</desc>
|
---|
5109 | </attribute>
|
---|
5110 |
|
---|
5111 | <attribute name="UTCTime" type="long long" readonly="yes">
|
---|
5112 | <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
|
---|
5113 | </attribute>
|
---|
5114 |
|
---|
5115 | <if target="midl">
|
---|
5116 | <method name="createHostNetworkInterface">
|
---|
5117 | <desc>
|
---|
5118 | Creates a new adapter for Host Interface Networking.
|
---|
5119 | </desc>
|
---|
5120 | <param name="name" type="wstring" dir="in">
|
---|
5121 | <desc>
|
---|
5122 | Adapter name.
|
---|
5123 | </desc>
|
---|
5124 | </param>
|
---|
5125 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
5126 | <desc>
|
---|
5127 | Created host interface object.
|
---|
5128 | </desc>
|
---|
5129 | </param>
|
---|
5130 | <param name="progress" type="IProgress" dir="return">
|
---|
5131 | <desc>
|
---|
5132 | Progress object to track the operation completion.
|
---|
5133 | </desc>
|
---|
5134 | </param>
|
---|
5135 | </method>
|
---|
5136 | <method name="removeHostNetworkInterface">
|
---|
5137 | <desc>
|
---|
5138 | Removes the given host network interface.
|
---|
5139 | </desc>
|
---|
5140 | <param name="id" type="uuid" dir="in">
|
---|
5141 | <desc>
|
---|
5142 | Adapter GUID.
|
---|
5143 | </desc>
|
---|
5144 | </param>
|
---|
5145 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
5146 | <desc>
|
---|
5147 | Removed host interface object.
|
---|
5148 | </desc>
|
---|
5149 | </param>
|
---|
5150 | <param name="progress" type="IProgress" dir="return">
|
---|
5151 | <desc>
|
---|
5152 | Progress object to track the operation completion.
|
---|
5153 | </desc>
|
---|
5154 | </param>
|
---|
5155 | </method>
|
---|
5156 | </if>
|
---|
5157 |
|
---|
5158 | <method name="createUSBDeviceFilter">
|
---|
5159 | <desc>
|
---|
5160 | Creates a new USB device filter. All attributes except
|
---|
5161 | the filter name are set to <tt>null</tt> (any match),
|
---|
5162 | <i>active</i> is <tt>false</tt> (the filter is not active).
|
---|
5163 |
|
---|
5164 | The created filter can be added to the list of filters using
|
---|
5165 | <link to="#insertUSBDeviceFilter()"/>.
|
---|
5166 |
|
---|
5167 | <see>#USBDeviceFilters</see>
|
---|
5168 | </desc>
|
---|
5169 | <param name="name" type="wstring" dir="in">
|
---|
5170 | <desc>
|
---|
5171 | Filter name. See <link to="IHostUSBDeviceFilter::name"/>
|
---|
5172 | for more info.
|
---|
5173 | </desc>
|
---|
5174 | </param>
|
---|
5175 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
5176 | <desc>Created filter object.</desc>
|
---|
5177 | </param>
|
---|
5178 | </method>
|
---|
5179 |
|
---|
5180 | <method name="insertUSBDeviceFilter">
|
---|
5181 | <desc>
|
---|
5182 | Inserts the given USB device to the specified position
|
---|
5183 | in the list of filters.
|
---|
5184 |
|
---|
5185 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
5186 | position is equal to or greater than the number of elements in
|
---|
5187 | the list, the filter is added to the end of the collection.
|
---|
5188 |
|
---|
5189 | <note>
|
---|
5190 | Duplicates are not allowed, so an attempt to insert a
|
---|
5191 | filter that is already in the list, will return an
|
---|
5192 | error.
|
---|
5193 | </note>
|
---|
5194 | <note>
|
---|
5195 | This method may set a @ref com_warnings "warning result code".
|
---|
5196 | </note>
|
---|
5197 | <note>
|
---|
5198 | If USB functionality is not avaliable in the given edition of
|
---|
5199 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
5200 | </note>
|
---|
5201 |
|
---|
5202 | <see>#USBDeviceFilters</see>
|
---|
5203 | </desc>
|
---|
5204 | <param name="position" type="unsigned long" dir="in">
|
---|
5205 | <desc>Position to insert the filter to.</desc>
|
---|
5206 | </param>
|
---|
5207 | <param name="filter" type="IHostUSBDeviceFilter" dir="in">
|
---|
5208 | <desc>USB device filter to insert.</desc>
|
---|
5209 | </param>
|
---|
5210 | </method>
|
---|
5211 |
|
---|
5212 | <method name="removeUSBDeviceFilter">
|
---|
5213 | <desc>
|
---|
5214 | Removes a USB device filter from the specified position in the
|
---|
5215 | list of filters.
|
---|
5216 |
|
---|
5217 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
5218 | position equal to or greater than the number of elements in
|
---|
5219 | the list will produce an error.
|
---|
5220 |
|
---|
5221 | <note>
|
---|
5222 | This method may set a @ref com_warnings "warning result code".
|
---|
5223 | </note>
|
---|
5224 | <note>
|
---|
5225 | If USB functionality is not avaliable in the given edition of
|
---|
5226 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
5227 | </note>
|
---|
5228 |
|
---|
5229 | <see>#USBDeviceFilters</see>
|
---|
5230 | </desc>
|
---|
5231 | <param name="position" type="unsigned long" dir="in">
|
---|
5232 | <desc>Position to remove the filter from.</desc>
|
---|
5233 | </param>
|
---|
5234 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
5235 | <desc>Removed USB device filter.</desc>
|
---|
5236 | </param>
|
---|
5237 | </method>
|
---|
5238 |
|
---|
5239 | </interface>
|
---|
5240 |
|
---|
5241 | <!--
|
---|
5242 | // ISystemProperties
|
---|
5243 | /////////////////////////////////////////////////////////////////////////
|
---|
5244 | -->
|
---|
5245 |
|
---|
5246 | <interface
|
---|
5247 | name="ISystemProperties"
|
---|
5248 | extends="$unknown"
|
---|
5249 | uuid="12c2e31e-247f-4d51-82e5-5b9d4a6c7d5b"
|
---|
5250 | wsmap="managed"
|
---|
5251 | >
|
---|
5252 | <desc>
|
---|
5253 | The ISystemProperties interface represents global properties
|
---|
5254 | of the given VirtualBox installation.
|
---|
5255 |
|
---|
5256 | These properties define limits and default values for various
|
---|
5257 | attributes and parameters. Most of the properties are read-only, but some can be
|
---|
5258 | changed by a user.
|
---|
5259 | </desc>
|
---|
5260 |
|
---|
5261 | <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
|
---|
5262 | <desc>Minium guest system memory in Megabytes.</desc>
|
---|
5263 | </attribute>
|
---|
5264 |
|
---|
5265 | <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
|
---|
5266 | <desc>Maximum guest system memory in Megabytes.</desc>
|
---|
5267 | </attribute>
|
---|
5268 |
|
---|
5269 | <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
|
---|
5270 | <desc>Minimum guest video memory in Megabytes.</desc>
|
---|
5271 | </attribute>
|
---|
5272 |
|
---|
5273 | <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
|
---|
5274 | <desc>Maximum guest video memory in Megabytes.</desc>
|
---|
5275 | </attribute>
|
---|
5276 |
|
---|
5277 | <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
|
---|
5278 | <desc>Maximum size of a virtual disk image in Megabytes.</desc>
|
---|
5279 | </attribute>
|
---|
5280 |
|
---|
5281 | <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
|
---|
5282 | <desc>
|
---|
5283 | Number of network adapters associated with every
|
---|
5284 | <link to="IMachine"/> instance.
|
---|
5285 | </desc>
|
---|
5286 | </attribute>
|
---|
5287 |
|
---|
5288 | <attribute name="serialPortCount" type="unsigned long" readonly="yes">
|
---|
5289 | <desc>
|
---|
5290 | Number of serial ports associated with every
|
---|
5291 | <link to="IMachine"/> instance.
|
---|
5292 | </desc>
|
---|
5293 | </attribute>
|
---|
5294 |
|
---|
5295 | <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
|
---|
5296 | <desc>
|
---|
5297 | Number of parallel ports associated with every
|
---|
5298 | <link to="IMachine"/> instance.
|
---|
5299 | </desc>
|
---|
5300 | </attribute>
|
---|
5301 |
|
---|
5302 | <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
|
---|
5303 | <desc>
|
---|
5304 | Maximum device position in the boot order. This value corresponds
|
---|
5305 | to the total number of devices a machine can boot from, to make it
|
---|
5306 | possible to include all possible devices to the boot list.
|
---|
5307 | <see><link to="IMachine::setBootOrder()"/></see>
|
---|
5308 | </desc>
|
---|
5309 | </attribute>
|
---|
5310 |
|
---|
5311 | <attribute name="defaultVDIFolder" type="wstring">
|
---|
5312 | <desc>
|
---|
5313 | Full path to the default directory used to create new or open
|
---|
5314 | existing virtual disk images when an image file name contains no
|
---|
5315 | path.
|
---|
5316 |
|
---|
5317 | The initial value of this property is
|
---|
5318 | <tt><</tt><link to="IVirtualBox::homeFolder">
|
---|
5319 | VirtualBox_home</link><tt>>/VDI</tt>.
|
---|
5320 |
|
---|
5321 | <note>
|
---|
5322 | Setting this property to <tt>null</tt> will restore the
|
---|
5323 | initial value.
|
---|
5324 | </note>
|
---|
5325 | <note>
|
---|
5326 | When settings this property, the specified path can be
|
---|
5327 | absolute (full path) or relative
|
---|
5328 | to the <link to="IVirtualBox::homeFolder">
|
---|
5329 | VirtualBox home directory</link>.
|
---|
5330 | When reading this property, a full path is
|
---|
5331 | always returned.
|
---|
5332 | </note>
|
---|
5333 | <note>
|
---|
5334 | The specified path may not exist, it will be created
|
---|
5335 | when necessary.
|
---|
5336 | </note>
|
---|
5337 |
|
---|
5338 | <see>
|
---|
5339 | <link to="IVirtualBox::createHardDisk()"/>,
|
---|
5340 | <link to="IVirtualBox::openVirtualDiskImage()"/>
|
---|
5341 | </see>
|
---|
5342 | </desc>
|
---|
5343 | </attribute>
|
---|
5344 |
|
---|
5345 | <attribute name="defaultMachineFolder" type="wstring">
|
---|
5346 | <desc>
|
---|
5347 | Full path to the default directory used to create new or open
|
---|
5348 | existing machines when a settings file name contains no
|
---|
5349 | path.
|
---|
5350 |
|
---|
5351 | The initial value of this property is
|
---|
5352 | <tt><</tt><link to="IVirtualBox::homeFolder">
|
---|
5353 | VirtualBox_home</link><tt>>/Machines</tt>.
|
---|
5354 |
|
---|
5355 | <note>
|
---|
5356 | Setting this property to <tt>null</tt> will restore the
|
---|
5357 | initial value.
|
---|
5358 | </note>
|
---|
5359 | <note>
|
---|
5360 | When settings this property, the specified path can be
|
---|
5361 | absolute (full path) or relative
|
---|
5362 | to the <link to="IVirtualBox::homeFolder">
|
---|
5363 | VirtualBox home directory</link>.
|
---|
5364 | When reading this property, a full path is
|
---|
5365 | always returned.
|
---|
5366 | </note>
|
---|
5367 | <note>
|
---|
5368 | The specified path may not exist, it will be created
|
---|
5369 | when necessary.
|
---|
5370 | </note>
|
---|
5371 |
|
---|
5372 | <see>
|
---|
5373 | <link to="IVirtualBox::createMachine()"/>,
|
---|
5374 | <link to="IVirtualBox::openMachine()"/>
|
---|
5375 | </see>
|
---|
5376 | </desc>
|
---|
5377 | </attribute>
|
---|
5378 |
|
---|
5379 | <attribute name="remoteDisplayAuthLibrary" type="wstring">
|
---|
5380 | <desc>
|
---|
5381 | Library that provides authentication for VRDP clients. The library
|
---|
5382 | is used if a virtual machine's authentication type is set to "external"
|
---|
5383 | in the VM RemoteDisplay configuration.
|
---|
5384 |
|
---|
5385 | The system library extension (".DLL" or ".so") must be omitted.
|
---|
5386 | A full path can be specified; if not, then the library must reside on the
|
---|
5387 | system's default library path.
|
---|
5388 |
|
---|
5389 | The default value of this property is <tt>VRDPAuth</tt>. There is a library
|
---|
5390 | of that name in one of the default VirtualBox library directories.
|
---|
5391 |
|
---|
5392 | For details about VirtualBox authentication libraries and how to implement
|
---|
5393 | them, please refer to the VirtualBox manual.
|
---|
5394 |
|
---|
5395 | <note>
|
---|
5396 | Setting this property to <tt>null</tt> will restore the
|
---|
5397 | initial value.
|
---|
5398 | </note>
|
---|
5399 | </desc>
|
---|
5400 | </attribute>
|
---|
5401 |
|
---|
5402 | <attribute name="webServiceAuthLibrary" type="wstring">
|
---|
5403 | <desc>
|
---|
5404 | Library that provides authentication for webservice clients. The library
|
---|
5405 | is used if a virtual machine's authentication type is set to "external"
|
---|
5406 | in the VM RemoteDisplay configuration and will be called from
|
---|
5407 | within the <link to="IWebsessionManager::logon" /> implementation.
|
---|
5408 |
|
---|
5409 | As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
|
---|
5410 | there is no per-VM setting for this, as the webservice is a global
|
---|
5411 | resource (if it is running). Only for this setting (for the webservice),
|
---|
5412 | setting this value to a literal "null" string disables authentication,
|
---|
5413 | meaning that <link to="IWebsessionManager::logon" /> will always succeed,
|
---|
5414 | no matter what user name and password are supplied.
|
---|
5415 |
|
---|
5416 | The initial value of this property is <tt>VRDPAuth</tt>,
|
---|
5417 | meaning that the webservice will use the same authentication
|
---|
5418 | library that is used by default for VBoxVRDP (again, see
|
---|
5419 | <link to="ISystemProperties::remoteDisplayAuthLibrary" />).
|
---|
5420 | The format and calling convetion of authentication libraries
|
---|
5421 | is the same for the webservice as it is for VBoxVRDP.
|
---|
5422 |
|
---|
5423 | </desc>
|
---|
5424 | </attribute>
|
---|
5425 |
|
---|
5426 | <attribute name="HWVirtExEnabled" type="boolean">
|
---|
5427 | <desc>
|
---|
5428 | This specifies the default value for hardware virtualization
|
---|
5429 | extensions. If enabled, virtual machines will make use of
|
---|
5430 | hardware virtualization extensions such as Intel VT-x and
|
---|
5431 | AMD-V by default. This value can be overridden by each VM
|
---|
5432 | using their <link to="IMachine::HWVirtExEnabled" /> property.
|
---|
5433 | </desc>
|
---|
5434 | </attribute>
|
---|
5435 |
|
---|
5436 | <attribute name="LogHistoryCount" type="unsigned long">
|
---|
5437 | <desc>
|
---|
5438 | This value specifies how many old release log files are kept.
|
---|
5439 | </desc>
|
---|
5440 | </attribute>
|
---|
5441 | </interface>
|
---|
5442 |
|
---|
5443 | <!--
|
---|
5444 | // IGuest
|
---|
5445 | /////////////////////////////////////////////////////////////////////////
|
---|
5446 | -->
|
---|
5447 |
|
---|
5448 | <interface
|
---|
5449 | name="IGuestOSType" extends="$unknown"
|
---|
5450 | uuid="da94f478-1f37-4726-b750-2235950dc2fe"
|
---|
5451 | wsmap="struct"
|
---|
5452 | >
|
---|
5453 | <desc>
|
---|
5454 | </desc>
|
---|
5455 |
|
---|
5456 | <attribute name="id" type="wstring" readonly="yes">
|
---|
5457 | <desc>Guest OS identifier string.</desc>
|
---|
5458 | </attribute>
|
---|
5459 |
|
---|
5460 | <attribute name="description" type="wstring" readonly="yes">
|
---|
5461 | <desc>Human readable description of the guest OS.</desc>
|
---|
5462 | </attribute>
|
---|
5463 |
|
---|
5464 | <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
|
---|
5465 | <desc>Recommended RAM size in Megabytes.</desc>
|
---|
5466 | </attribute>
|
---|
5467 |
|
---|
5468 | <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
|
---|
5469 | <desc>Recommended video RAM size in Megabytes.</desc>
|
---|
5470 | </attribute>
|
---|
5471 |
|
---|
5472 | <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
|
---|
5473 | <desc>Recommended hard disk size in Megabytes.</desc>
|
---|
5474 | </attribute>
|
---|
5475 | </interface>
|
---|
5476 |
|
---|
5477 |
|
---|
5478 | <enumerator
|
---|
5479 | name="IGuestOSTypeEnumerator" type="IGuestOSType"
|
---|
5480 | uuid="a3335e02-4669-4e3c-80c7-c4dc7056a07c"
|
---|
5481 | />
|
---|
5482 |
|
---|
5483 | <collection
|
---|
5484 | name="IGuestOSTypeCollection" type="IGuestOSType" enumerator="IGuestOSTypeEnumerator"
|
---|
5485 | uuid="a5e36749-a610-498b-9f29-2e36c1042d65"
|
---|
5486 | readonly="yes"
|
---|
5487 | />
|
---|
5488 |
|
---|
5489 | <interface
|
---|
5490 | name="IGuest" extends="$unknown"
|
---|
5491 | uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
|
---|
5492 |
|
---|
5493 | wsmap="suppress"
|
---|
5494 | >
|
---|
5495 | <desc>
|
---|
5496 | The IGuest interface represents information about the operating system
|
---|
5497 | running inside the virtual machine. Used in
|
---|
5498 | <link to="IConsole::guest"/>.
|
---|
5499 |
|
---|
5500 | IGuest provides information about the guest operating system, whether
|
---|
5501 | Guest Additions are installed and other OS-specific virtual machine
|
---|
5502 | properties.
|
---|
5503 | </desc>
|
---|
5504 |
|
---|
5505 | <attribute name="OSTypeId" type="wstring" readonly="yes">
|
---|
5506 | <desc>
|
---|
5507 | Identifier of the Guest OS type as reported by the Guest
|
---|
5508 | Additions.
|
---|
5509 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
5510 | an IGuestOSType object representing details about the given
|
---|
5511 | Guest OS type.
|
---|
5512 | <note>
|
---|
5513 | If Guest Additions are not installed, this value will be
|
---|
5514 | the same as <link to="IMachine::OSTypeId"/>.
|
---|
5515 | </note>
|
---|
5516 | </desc>
|
---|
5517 | </attribute>
|
---|
5518 |
|
---|
5519 | <attribute name="additionsActive" type="boolean" readonly="yes">
|
---|
5520 | <desc>
|
---|
5521 | Flag whether the Guest Additions are installed and active
|
---|
5522 | in which case their version will be returned by the
|
---|
5523 | <link to="#additionsVersion"/> property.
|
---|
5524 | </desc>
|
---|
5525 | </attribute>
|
---|
5526 |
|
---|
5527 | <attribute name="additionsVersion" type="wstring" readonly="yes">
|
---|
5528 | <desc>
|
---|
5529 | Version of the Guest Additions (3 decimal numbers separated
|
---|
5530 | by dots) or empty when the Additions are not installed. The
|
---|
5531 | Additions may also report a version but yet not be active as
|
---|
5532 | the version might be refused by VirtualBox (incompatible) or
|
---|
5533 | other failures occured.
|
---|
5534 | </desc>
|
---|
5535 | </attribute>
|
---|
5536 |
|
---|
5537 | <attribute name="supportsSeamless" type="boolean" readonly="yes">
|
---|
5538 | <desc>
|
---|
5539 | Flag whether seamless guest display rendering (seamless desktop
|
---|
5540 | integration) is supported.
|
---|
5541 | </desc>
|
---|
5542 | </attribute>
|
---|
5543 |
|
---|
5544 | <attribute name="supportsGraphics" type="boolean" readonly="yes">
|
---|
5545 | <desc>
|
---|
5546 | Flag whether the guest is in graphics mode. If it is not, then
|
---|
5547 | seamless rendering will not work, resize hints are not immediately
|
---|
5548 | acted on and guest display resizes are probably not initiated by
|
---|
5549 | the guest additions.
|
---|
5550 | </desc>
|
---|
5551 | </attribute>
|
---|
5552 |
|
---|
5553 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
5554 | <desc>Guest system memory balloon size in megabytes.</desc>
|
---|
5555 | </attribute>
|
---|
5556 |
|
---|
5557 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
5558 | <desc>Interval to update guest statistics in seconds.</desc>
|
---|
5559 | </attribute>
|
---|
5560 |
|
---|
5561 | <method name="setCredentials">
|
---|
5562 | <desc>
|
---|
5563 | Store login credentials that can be queried by guest operating
|
---|
5564 | systems with Additions installed. The credentials are transient
|
---|
5565 | to the session and the guest may also choose to erase them. Note
|
---|
5566 | that the caller cannot determine whether the guest operating system
|
---|
5567 | has queried or made use of the credentials.
|
---|
5568 | </desc>
|
---|
5569 | <param name="userName" type="wstring" dir="in">
|
---|
5570 | <desc>User name string, can be empty</desc>
|
---|
5571 | </param>
|
---|
5572 | <param name="password" type="wstring" dir="in">
|
---|
5573 | <desc>Password string, can be empty</desc>
|
---|
5574 | </param>
|
---|
5575 | <param name="domain" type="wstring" dir="in">
|
---|
5576 | <desc>Domain name (guest logon scheme specific), can be emtpy</desc>
|
---|
5577 | </param>
|
---|
5578 | <param name="allowInteractiveLogon" type="boolean" dir="in">
|
---|
5579 | <desc>
|
---|
5580 | Flag whether the guest should alternatively allow the user to
|
---|
5581 | interactively specify different credentials. This flag might
|
---|
5582 | not be supported by all versions of the Additions.
|
---|
5583 | </desc>
|
---|
5584 | </param>
|
---|
5585 | </method>
|
---|
5586 |
|
---|
5587 | <method name="getStatistic">
|
---|
5588 | <desc>
|
---|
5589 | Query specified guest statistics as reported by the VirtualBox Additions.
|
---|
5590 | </desc>
|
---|
5591 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
5592 | <desc>Virtual CPU id; not relevant for all statistic types</desc>
|
---|
5593 | </param>
|
---|
5594 | <param name="statistic" type="GuestStatisticType" dir="in">
|
---|
5595 | <desc>Statistic type.</desc>
|
---|
5596 | </param>
|
---|
5597 | <param name="statVal" type="unsigned long" dir="out">
|
---|
5598 | <desc>Statistics value</desc>
|
---|
5599 | </param>
|
---|
5600 | </method>
|
---|
5601 |
|
---|
5602 | </interface>
|
---|
5603 |
|
---|
5604 |
|
---|
5605 | <!--
|
---|
5606 | // IProgress
|
---|
5607 | /////////////////////////////////////////////////////////////////////////
|
---|
5608 | -->
|
---|
5609 |
|
---|
5610 | <enumerator
|
---|
5611 | name="IProgressEnumerator" type="IProgress"
|
---|
5612 | uuid="e0380522-4ef1-48f4-856c-e455177ccb2d"
|
---|
5613 | />
|
---|
5614 |
|
---|
5615 | <collection
|
---|
5616 | name="IProgressCollection" type="IProgress" enumerator="IProgressEnumerator"
|
---|
5617 | uuid="78B76A7C-F0F2-467c-9F0E-F089A54EE957"
|
---|
5618 | readonly="yes"
|
---|
5619 | />
|
---|
5620 |
|
---|
5621 | <interface
|
---|
5622 | name="IProgress" extends="$unknown"
|
---|
5623 | uuid="10CC03A1-717E-429b-992D-C67B56175A51"
|
---|
5624 | wsmap="managed"
|
---|
5625 | >
|
---|
5626 | <desc>
|
---|
5627 | The IProgress interface represents a task progress object that allows
|
---|
5628 | to wait for the completion of some asynchronous task.
|
---|
5629 |
|
---|
5630 | The task consists of one or more operations that run sequentially,
|
---|
5631 | one after one. There is an individual percent of completion of the
|
---|
5632 | current operation and the percent of completion of the task as a
|
---|
5633 | whole. Similarly, you can wait for the completion of a particular
|
---|
5634 | operation or for the completion of the whole task.
|
---|
5635 |
|
---|
5636 | Every operation is identified by a number (starting from 0)
|
---|
5637 | and has a separate description.
|
---|
5638 | </desc>
|
---|
5639 |
|
---|
5640 | <attribute name="id" type="uuid" readonly="yes">
|
---|
5641 | <desc>ID of the task.</desc>
|
---|
5642 | </attribute>
|
---|
5643 |
|
---|
5644 | <attribute name="description" type="wstring" readonly="yes">
|
---|
5645 | <desc>Description of the task.</desc>
|
---|
5646 | </attribute>
|
---|
5647 |
|
---|
5648 | <attribute name="initiator" type="$unknown" readonly="yes">
|
---|
5649 | <desc>Initiator of the task.</desc>
|
---|
5650 | </attribute>
|
---|
5651 |
|
---|
5652 | <attribute name="cancelable" type="boolean" readonly="yes">
|
---|
5653 | <desc>Whether the task can be interrupted.</desc>
|
---|
5654 | </attribute>
|
---|
5655 |
|
---|
5656 | <attribute name="percent" type="long" readonly="yes">
|
---|
5657 | <desc>
|
---|
5658 | Current task progress value in percent.
|
---|
5659 | This value depends on how many operations are already complete.
|
---|
5660 | </desc>
|
---|
5661 | </attribute>
|
---|
5662 |
|
---|
5663 | <attribute name="completed" type="boolean" readonly="yes">
|
---|
5664 | <desc>Whether the task has been completed.</desc>
|
---|
5665 | </attribute>
|
---|
5666 |
|
---|
5667 | <attribute name="canceled" type="boolean" readonly="yes">
|
---|
5668 | <desc>Whether the task has been canceled.</desc>
|
---|
5669 | </attribute>
|
---|
5670 |
|
---|
5671 | <attribute name="resultCode" type="result" readonly="yes">
|
---|
5672 | <desc>
|
---|
5673 | Result code of the progress task.
|
---|
5674 | Valid only if <link to="#completed"/> is true.
|
---|
5675 | </desc>
|
---|
5676 | </attribute>
|
---|
5677 |
|
---|
5678 | <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
5679 | <desc>
|
---|
5680 | Extended information about the unsuccessful result of the
|
---|
5681 | progress operation. May be NULL when no extended information
|
---|
5682 | is available.
|
---|
5683 | Valid only if <link to="#completed"/> is true and
|
---|
5684 | <link to="#resultCode"/> indicates a failure.
|
---|
5685 | </desc>
|
---|
5686 | </attribute>
|
---|
5687 |
|
---|
5688 | <attribute name="operationCount" type="unsigned long" readonly="yes">
|
---|
5689 | <desc>
|
---|
5690 | Number of operations this task is divided into.
|
---|
5691 | Every task consists of at least one operation.
|
---|
5692 | </desc>
|
---|
5693 | </attribute>
|
---|
5694 |
|
---|
5695 | <attribute name="operation" type="unsigned long" readonly="yes">
|
---|
5696 | <desc>Number of the operation being currently executed.</desc>
|
---|
5697 | </attribute>
|
---|
5698 |
|
---|
5699 | <attribute name="operationDescription" type="wstring" readonly="yes">
|
---|
5700 | <desc>
|
---|
5701 | Description of the operation being currently executed.
|
---|
5702 | </desc>
|
---|
5703 | </attribute>
|
---|
5704 |
|
---|
5705 | <attribute name="operationPercent" type="long" readonly="yes">
|
---|
5706 | <desc>Current operation progress value in percent.</desc>
|
---|
5707 | </attribute>
|
---|
5708 |
|
---|
5709 | <method name="waitForCompletion">
|
---|
5710 | <desc>
|
---|
5711 | Waits until the task is done (including all operations) with a
|
---|
5712 | given timeout.
|
---|
5713 | </desc>
|
---|
5714 | <param name="timeout" type="long" dir="in">
|
---|
5715 | <desc>
|
---|
5716 | Timeout value in milliseconds.
|
---|
5717 | Specify -1 for an indefinite wait.
|
---|
5718 | </desc>
|
---|
5719 | </param>
|
---|
5720 | </method>
|
---|
5721 |
|
---|
5722 | <method name="waitForOperationCompletion">
|
---|
5723 | <desc>
|
---|
5724 | Waits until the given operation is done with a given timeout.
|
---|
5725 | </desc>
|
---|
5726 | <param name="operation" type="unsigned long" dir="in">
|
---|
5727 | <desc>
|
---|
5728 | Number of the operation to wait for.
|
---|
5729 | Must be less than <link to="#operationCount"/>.
|
---|
5730 | </desc>
|
---|
5731 | </param>
|
---|
5732 | <param name="timeout" type="long" dir="in">
|
---|
5733 | <desc>
|
---|
5734 | Timeout value in milliseconds.
|
---|
5735 | Specify -1 for an indefinite wait.
|
---|
5736 | </desc>
|
---|
5737 | </param>
|
---|
5738 | </method>
|
---|
5739 |
|
---|
5740 | <method name="cancel">
|
---|
5741 | <desc>
|
---|
5742 | Cancels the task.
|
---|
5743 | <note>
|
---|
5744 | If <link to="#cancelable"/> is <tt>false</tt>, then
|
---|
5745 | this method will fail.
|
---|
5746 | </note>
|
---|
5747 | </desc>
|
---|
5748 | </method>
|
---|
5749 |
|
---|
5750 | </interface>
|
---|
5751 |
|
---|
5752 |
|
---|
5753 | <!--
|
---|
5754 | // ISnapshot
|
---|
5755 | /////////////////////////////////////////////////////////////////////////
|
---|
5756 | -->
|
---|
5757 |
|
---|
5758 | <enumerator
|
---|
5759 | name="ISnapshotEnumerator" type="ISnapshot"
|
---|
5760 | uuid="25cfa2a4-1f1d-4f05-9658-b7a5894ef1a3"
|
---|
5761 | />
|
---|
5762 |
|
---|
5763 | <collection
|
---|
5764 | name="ISnapshotCollection" type="ISnapshot"
|
---|
5765 | enumerator="ISnapshotEnumerator"
|
---|
5766 | uuid="23852e3c-94cd-4801-ab05-ed35675b3894"
|
---|
5767 | readonly="yes"
|
---|
5768 | />
|
---|
5769 |
|
---|
5770 | <interface
|
---|
5771 | name="ISnapshot" extends="$unknown"
|
---|
5772 | uuid="9f1bbf79-13b0-4da2-abba-4a992c65c083"
|
---|
5773 | wsmap="managed"
|
---|
5774 | >
|
---|
5775 | <desc>
|
---|
5776 | The ISnapshot interface represents a snapshot of the virtual
|
---|
5777 | machine.
|
---|
5778 |
|
---|
5779 | The <i>snapshot</i> stores all the information about a virtual
|
---|
5780 | machine necessary to bring it to exactly the same state as it was at
|
---|
5781 | the time of taking the snapshot. The snapshot includes:
|
---|
5782 |
|
---|
5783 | <ul>
|
---|
5784 | <li>all settings of the virtual machine (i.e. its hardware
|
---|
5785 | configuration: RAM size, attached hard disks, etc.)
|
---|
5786 | </li>
|
---|
5787 | <li>the execution state of the virtual machine (memory contents,
|
---|
5788 | CPU state, etc.).
|
---|
5789 | </li>
|
---|
5790 | </ul>
|
---|
5791 |
|
---|
5792 | Snapshots can be <i>offline</i> (taken when the VM is powered off)
|
---|
5793 | or <i>online</i> (taken when the VM is running). The execution
|
---|
5794 | state of the offline snapshot is called a <i>zero execution state</i>
|
---|
5795 | (it doesn't actually contain any information about memory contents
|
---|
5796 | or the CPU state, assuming that all hardware is just powered off).
|
---|
5797 |
|
---|
5798 | <h3>Snapshot branches</h3>
|
---|
5799 |
|
---|
5800 | Snapshots can be chained. Chained snapshots form a branch where
|
---|
5801 | every next snapshot is based on the previous one. This chaining is
|
---|
5802 | mostly related to hard disk branching (see <link to="IHardDisk"/>
|
---|
5803 | description). This means that every time a new snapshot is created,
|
---|
5804 | a new differencing hard disk is implicitly created for all normal
|
---|
5805 | hard disks attached to the given virtual machine. This allows to
|
---|
5806 | fully restore hard disk contents when the machine is later reverted
|
---|
5807 | to a particular snapshot.
|
---|
5808 |
|
---|
5809 | In the current implelemtation, multiple snapshot branches within one
|
---|
5810 | virtual machine are not allowed. Every machine has a signle branch,
|
---|
5811 | and <link to="IConsole::takeSnapshot()"/> operation adds a new
|
---|
5812 | snapshot to the top of that branch.
|
---|
5813 |
|
---|
5814 | Existings snapshots can be discarded using
|
---|
5815 | <link to="IConsole::discardSnapshot()"/>.
|
---|
5816 |
|
---|
5817 | <h3>Current snapshot</h3>
|
---|
5818 |
|
---|
5819 | Every virtual machine has a current snapshot, identified by
|
---|
5820 | <link to="IMachine::currentSnapshot"/>. This snapshot is used as
|
---|
5821 | a base for the <i>current machine state</i> (see below), to the effect
|
---|
5822 | that all normal hard disks of the machine and its execution
|
---|
5823 | state are based on this snapshot.
|
---|
5824 |
|
---|
5825 | In the current implementation, the current snapshot is always the
|
---|
5826 | last taken snapshot (i.e. the head snapshot on the branch) and it
|
---|
5827 | cannot be changed.
|
---|
5828 |
|
---|
5829 | The current snapshot is <tt>null</tt> if the machine doesn't have
|
---|
5830 | snapshots at all; in this case the current machine state is just
|
---|
5831 | current settings of this machine plus its current execution state.
|
---|
5832 |
|
---|
5833 | <h3>Current machine state</h3>
|
---|
5834 |
|
---|
5835 | The current machine state is what represened by IMachine instances got
|
---|
5836 | directly from IVirtualBox
|
---|
5837 | using <link
|
---|
5838 | to="IVirtualBox::getMachine()">getMachine()</link>, <link
|
---|
5839 | to="IVirtualBox::findMachine()">findMachine()</link>, etc. (as opposed
|
---|
5840 | to instances returned by <link to="ISnapshot::machine"/>). This state
|
---|
5841 | is always used when the machine is <link to="IConsole::powerUp"> powered
|
---|
5842 | on</link>.
|
---|
5843 |
|
---|
5844 | The current machine state also includes the current execution state.
|
---|
5845 | If the machine is being currently executed
|
---|
5846 | (<link to="IMachine::state"/> is <link to="MachineState::Running"/>
|
---|
5847 | and above), its execution state is just what's happening now.
|
---|
5848 | If it is powered off (<link to="MachineState::PoweredOff"/> or
|
---|
5849 | <link to="MachineState::Aborted"/>), it has a zero execution state.
|
---|
5850 | If the machine is saved (<link to="MachineState::Saved"/>), its
|
---|
5851 | execution state is what saved in the execution state file
|
---|
5852 | (<link to="IMachine::stateFilePath"/>).
|
---|
5853 |
|
---|
5854 | If the machine is in the saved state, then, next time it is powered
|
---|
5855 | on, its execution state will be fully restored from the saved state
|
---|
5856 | file and the execution will continue from the point where the state
|
---|
5857 | was saved.
|
---|
5858 |
|
---|
5859 | Similarly to snapshots, the current machine state can be discarded
|
---|
5860 | using <link to="IConsole::discardCurrentState()"/>.
|
---|
5861 |
|
---|
5862 | <h3>Taking and discarding snapshots</h3>
|
---|
5863 |
|
---|
5864 | The table below briefly explains the meaning of every snapshot
|
---|
5865 | operation:
|
---|
5866 |
|
---|
5867 | <table>
|
---|
5868 | <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
|
---|
5869 |
|
---|
5870 | <tr><td><link to="IConsole::takeSnapshot()"/></td>
|
---|
5871 |
|
---|
5872 | <td>Save the current state of the virtual machine, including all
|
---|
5873 | settings, contents of normal hard disks and the current modifications
|
---|
5874 | to immutable hard disks (for online snapshots)</td>
|
---|
5875 |
|
---|
5876 | <td>The current state is not changed (the machine will continue
|
---|
5877 | execution if it is being executed when the snapshot is
|
---|
5878 | taken)</td></tr>
|
---|
5879 |
|
---|
5880 | <tr><td><link to="IConsole::discardSnapshot()"/></td>
|
---|
5881 |
|
---|
5882 | <td>Forget the state of the virtual machine stored in the snapshot:
|
---|
5883 | dismiss all saved settings and delete the saved execution state (for
|
---|
5884 | online snapshots)</td>
|
---|
5885 |
|
---|
5886 | <td>Other snapshots (including child snapshots, if any) and the
|
---|
5887 | current state are not directly affected</td></tr>
|
---|
5888 |
|
---|
5889 | <tr><td><link to="IConsole::discardCurrentState()"/></td>
|
---|
5890 |
|
---|
5891 | <td>Restore the current state of the virtual machine from the state
|
---|
5892 | stored in the current snapshot, including all settings and hard disk
|
---|
5893 | contents</td>
|
---|
5894 |
|
---|
5895 | <td>The current state of the machine existed prior to this operation
|
---|
5896 | is lost</td></tr>
|
---|
5897 |
|
---|
5898 | <tr><td><link to="IConsole::discardCurrentSnapshotAndState()"/></td>
|
---|
5899 |
|
---|
5900 | <td>Completely revert the virtual machine to the state it was in
|
---|
5901 | before the current snapshot has been taken</td>
|
---|
5902 |
|
---|
5903 | <td>The current state, as well as the current snapshot, are
|
---|
5904 | lost</td></tr>
|
---|
5905 |
|
---|
5906 | </table>
|
---|
5907 |
|
---|
5908 | </desc>
|
---|
5909 |
|
---|
5910 | <attribute name="id" type="uuid" readonly="yes">
|
---|
5911 | <desc>UUID of the snapshot.</desc>
|
---|
5912 | </attribute>
|
---|
5913 |
|
---|
5914 | <attribute name="name" type="wstring">
|
---|
5915 | <desc>Short name of the snapshot.</desc>
|
---|
5916 | </attribute>
|
---|
5917 |
|
---|
5918 | <attribute name="description" type="wstring">
|
---|
5919 | <desc>Optional description of the snapshot.</desc>
|
---|
5920 | </attribute>
|
---|
5921 |
|
---|
5922 | <attribute name="timeStamp" type="long long" readonly="yes">
|
---|
5923 | <desc>
|
---|
5924 | Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
|
---|
5925 | </desc>
|
---|
5926 | </attribute>
|
---|
5927 |
|
---|
5928 | <attribute name="online" type="boolean" readonly="yes">
|
---|
5929 | <desc>
|
---|
5930 | <tt>true</tt> if this snapshot is an online snapshot and
|
---|
5931 | <tt>false</tt> otherwise.
|
---|
5932 |
|
---|
5933 | <note>
|
---|
5934 | When this attribute is <tt>true</tt>, the
|
---|
5935 | <link to="IMachine::stateFilePath"/> attribute of the
|
---|
5936 | <link to="#machine"/> object associated with this snapshot
|
---|
5937 | will point to the saved state file. Otherwise, it will be
|
---|
5938 | <tt>null</tt>.
|
---|
5939 | </note>
|
---|
5940 | </desc>
|
---|
5941 | </attribute>
|
---|
5942 |
|
---|
5943 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
5944 | <desc>
|
---|
5945 | Virtual machine this snapshot is taken on. This object
|
---|
5946 | stores all settings the machine had when taking this snapshot.
|
---|
5947 | <note>
|
---|
5948 | The returned machine object is immutable, i.e. no
|
---|
5949 | any settings can be changed.
|
---|
5950 | </note>
|
---|
5951 | </desc>
|
---|
5952 | </attribute>
|
---|
5953 |
|
---|
5954 | <attribute name="parent" type="ISnapshot" readonly="yes">
|
---|
5955 | <desc>
|
---|
5956 | Parent snapshot (a snapshot this one is based on).
|
---|
5957 | <note>
|
---|
5958 | It's not an error to read this attribute on a snapshot
|
---|
5959 | that doesn't have a parent -- a null object will be
|
---|
5960 | returned to indicate this.
|
---|
5961 | </note>
|
---|
5962 | </desc>
|
---|
5963 | </attribute>
|
---|
5964 |
|
---|
5965 | <attribute name="children" type="ISnapshotCollection" readonly="yes">
|
---|
5966 | <desc>
|
---|
5967 | Child snapshots (all snapshots having this one as a parent).
|
---|
5968 | <note>
|
---|
5969 | In the current implementation, there can be only one
|
---|
5970 | child snapshot, or no children at all, meaning this is the
|
---|
5971 | last (head) snapshot.
|
---|
5972 | </note>
|
---|
5973 | </desc>
|
---|
5974 | </attribute>
|
---|
5975 |
|
---|
5976 | </interface>
|
---|
5977 |
|
---|
5978 | <!--
|
---|
5979 | // IHardDisk
|
---|
5980 | /////////////////////////////////////////////////////////////////////////
|
---|
5981 | -->
|
---|
5982 |
|
---|
5983 | <enum
|
---|
5984 | name="HardDiskStorageType"
|
---|
5985 | uuid="48138584-ad99-479d-a36f-eb82a7663685"
|
---|
5986 | >
|
---|
5987 | <desc>
|
---|
5988 | Virtual hard disk storage type.
|
---|
5989 | <see>IHardDisk</see>
|
---|
5990 | </desc>
|
---|
5991 |
|
---|
5992 | <const name="VirtualDiskImage" value="0">
|
---|
5993 | <desc>
|
---|
5994 | Virtual Disk Image, VDI (a regular file in the file
|
---|
5995 | system of the host OS, see <link to="IVirtualDiskImage"/>)
|
---|
5996 | </desc>
|
---|
5997 | </const>
|
---|
5998 | <const name="ISCSIHardDisk" value="1">
|
---|
5999 | <desc>
|
---|
6000 | iSCSI Remote Disk (a disk accessed via the Internet
|
---|
6001 | SCSI protocol over a TCP/IP network, see
|
---|
6002 | <link to="IISCSIHardDisk"/>)
|
---|
6003 | </desc>
|
---|
6004 | </const>
|
---|
6005 | <const name="VMDKImage" value="2">
|
---|
6006 | <desc>
|
---|
6007 | VMware Virtual Machine Disk image (a regular file in the file
|
---|
6008 | system of the host OS, see <link to="IVMDKImage"/>)
|
---|
6009 | </desc>
|
---|
6010 | </const>
|
---|
6011 | <const name="CustomHardDisk" value="3">
|
---|
6012 | <desc>
|
---|
6013 | Disk formats supported through plugins (see
|
---|
6014 | <link to="ICustomHardDisk"/>)
|
---|
6015 | </desc>
|
---|
6016 | </const>
|
---|
6017 | <const name="VHDImage" value="4">
|
---|
6018 | <desc>
|
---|
6019 | Virtual PC Virtual Machine Disk image (a regular file in the file
|
---|
6020 | system of the host OS, see <link to="IVHDImage"/>)
|
---|
6021 | </desc>
|
---|
6022 | </const>
|
---|
6023 | </enum>
|
---|
6024 |
|
---|
6025 | <enum
|
---|
6026 | name="HardDiskType"
|
---|
6027 | uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
|
---|
6028 | >
|
---|
6029 | <desc>
|
---|
6030 | Virtual hard disk type.
|
---|
6031 | <see>IHardDisk</see>
|
---|
6032 | </desc>
|
---|
6033 |
|
---|
6034 | <const name="Normal" value="0">
|
---|
6035 | <desc>
|
---|
6036 | Normal hard disk (attached directly or indirectly, preserved
|
---|
6037 | when taking snapshots).
|
---|
6038 | </desc>
|
---|
6039 | </const>
|
---|
6040 | <const name="Immutable" value="1">
|
---|
6041 | <desc>
|
---|
6042 | Immutable hard disk (attached indirectly, changes are wiped out
|
---|
6043 | after powering off the virtual machine).
|
---|
6044 | </desc>
|
---|
6045 | </const>
|
---|
6046 | <const name="Writethrough" value="2">
|
---|
6047 | <desc>
|
---|
6048 | Write through hard disk (attached directly, ignored when
|
---|
6049 | taking snapshots).
|
---|
6050 | </desc>
|
---|
6051 | </const>
|
---|
6052 | </enum>
|
---|
6053 |
|
---|
6054 | <interface
|
---|
6055 | name="IHardDiskAttachment" extends="$unknown"
|
---|
6056 | uuid="c0ffe596-21c6-4797-8d8a-b47b66881e7a"
|
---|
6057 | wsmap="struct"
|
---|
6058 | >
|
---|
6059 | <desc>
|
---|
6060 | </desc>
|
---|
6061 | <attribute name="hardDisk" type="IHardDisk" readonly="yes">
|
---|
6062 | <desc>Harddisk object this attachment is about.</desc>
|
---|
6063 | </attribute>
|
---|
6064 |
|
---|
6065 | <attribute name="bus" type="StorageBus" readonly="yes">
|
---|
6066 | <desc>Disk controller ID of this attachment.</desc>
|
---|
6067 | </attribute>
|
---|
6068 |
|
---|
6069 | <attribute name="channel" type="long" readonly="yes">
|
---|
6070 | <desc>Channel number of the attachment.</desc>
|
---|
6071 | </attribute>
|
---|
6072 |
|
---|
6073 | <attribute name="device" type="long" readonly="yes">
|
---|
6074 | <desc>Device slot number of the attachment.</desc>
|
---|
6075 | </attribute>
|
---|
6076 |
|
---|
6077 | </interface>
|
---|
6078 |
|
---|
6079 | <enumerator
|
---|
6080 | name="IHardDiskAttachmentEnumerator" type="IHardDiskAttachment"
|
---|
6081 | uuid="9955e486-2f0b-432a-99e4-0ebbd338875e"
|
---|
6082 | />
|
---|
6083 |
|
---|
6084 | <collection
|
---|
6085 | name="IHardDiskAttachmentCollection" type="IHardDiskAttachment"
|
---|
6086 | enumerator="IHardDiskAttachmentEnumerator"
|
---|
6087 | uuid="8f727842-bb77-45d4-92de-4ec14bf613c9"
|
---|
6088 | readonly="yes"
|
---|
6089 | />
|
---|
6090 |
|
---|
6091 | <enumerator
|
---|
6092 | name="IHardDiskEnumerator" type="IHardDisk"
|
---|
6093 | uuid="b976f97b-cdb8-47e3-9860-084031cbd533"
|
---|
6094 | />
|
---|
6095 |
|
---|
6096 | <collection
|
---|
6097 | name="IHardDiskCollection" type="IHardDisk"
|
---|
6098 | enumerator="IHardDiskEnumerator"
|
---|
6099 | uuid="43EAC2BC-5C61-40fa-BC38-46DE2C7DB6BB"
|
---|
6100 | readonly="yes"
|
---|
6101 | />
|
---|
6102 |
|
---|
6103 | <interface
|
---|
6104 | name="IHardDisk" extends="$unknown"
|
---|
6105 | uuid="FD443EC1-000F-4F5B-9282-D72760A66916"
|
---|
6106 | wsmap="managed"
|
---|
6107 | >
|
---|
6108 | <desc>
|
---|
6109 | The IHardDisk interface represents a virtual hard disk drive
|
---|
6110 | used by virtual machines.
|
---|
6111 |
|
---|
6112 | The virtual hard disk drive virtualizes the hard disk hardware and
|
---|
6113 | looks like a regular hard disk inside the virtual machine and
|
---|
6114 | the guest OS.
|
---|
6115 |
|
---|
6116 | <h3>Storage Types</h3>
|
---|
6117 |
|
---|
6118 | The <link to="HardDiskStorageType">storage type</link> of the
|
---|
6119 | virtual hard disk determines where and how it stores its data
|
---|
6120 | (sectors). Currently, the following storage types are supported:
|
---|
6121 |
|
---|
6122 | <ul>
|
---|
6123 |
|
---|
6124 | <li>
|
---|
6125 | <i>Virtual Disk Image (VDI)</i>, a regular file in the file system
|
---|
6126 | of the host OS (represented by the <link to="IVirtualDiskImage"/>
|
---|
6127 | interface). This file has a special format optimized so that unused
|
---|
6128 | sectors of data occupy much less space than on a physical hard disk.
|
---|
6129 | </li>
|
---|
6130 |
|
---|
6131 | <li>
|
---|
6132 | <i>iSCSI Remote Disk</i>, a disk accessed via the Internet SCSI
|
---|
6133 | protocol over a TCP/IP network link (represented by the
|
---|
6134 | <link to="IISCSIHardDisk"/> interface).
|
---|
6135 | </li>
|
---|
6136 |
|
---|
6137 | <li>
|
---|
6138 | <i>VMware VMDK image</i>, a regular file in the file system of the
|
---|
6139 | host OS (represented by the <link to="IVMDKImage"/> interface).
|
---|
6140 | Note that the regular file may be just a descriptor referring to
|
---|
6141 | further files, so don't make assumptions about the OS representation
|
---|
6142 | of a VMDK image.
|
---|
6143 | </li>
|
---|
6144 |
|
---|
6145 | <li>
|
---|
6146 | <i>Custom HardDisk</i>, a disk accessed via a plugin which is loaded
|
---|
6147 | when the disk is accessed (represented by the
|
---|
6148 | <link to="ICustomHardDisk"/> interface).
|
---|
6149 | </li>
|
---|
6150 |
|
---|
6151 | <li>
|
---|
6152 | <i>Virtual PC VHD Image</i>, a regular file in the file system of the
|
---|
6153 | host OS (represented by the <link to="IVHDImage"/> interface).
|
---|
6154 | </li>
|
---|
6155 |
|
---|
6156 | </ul>
|
---|
6157 |
|
---|
6158 | The storage type of the particular hard disk object is indicated by
|
---|
6159 | the <link to="#storageType"/> property.
|
---|
6160 |
|
---|
6161 | Each storage type is represented by its own interface (as shown
|
---|
6162 | above), that allows to query and set properties and perform
|
---|
6163 | operations specific to that storage type. When an IHardDisk object
|
---|
6164 | reports it uses some particular storage type, it also guaranteed to
|
---|
6165 | support the corresponding interface which you can query. And vice
|
---|
6166 | versa, every object that supports a storage-specific interface, also
|
---|
6167 | supports IHardDisk.
|
---|
6168 |
|
---|
6169 | <h3>Virtual Hard Disk Types</h3>
|
---|
6170 |
|
---|
6171 | The <link to="HardDiskType">type</link> of the virtual hard disk
|
---|
6172 | determines how it is attached to the virtual machine when you call
|
---|
6173 | <link to="IMachine::attachHardDisk()"/> and what happens to it when
|
---|
6174 | a <link to="ISnapshot">snapshot</link> of the virtual machine is
|
---|
6175 | taken.
|
---|
6176 |
|
---|
6177 | There are three types of virtual hard disks:
|
---|
6178 |
|
---|
6179 | <ul>
|
---|
6180 | <li><i>Normal</i></li>
|
---|
6181 | <li><i>Immutable</i></li>
|
---|
6182 | <li><i>Writethrough</i></li>
|
---|
6183 | </ul>
|
---|
6184 |
|
---|
6185 | The virtual disk type is indicated by the <link to="#type"/>
|
---|
6186 | property. Each of the above types is described in detail further
|
---|
6187 | down.
|
---|
6188 |
|
---|
6189 | There is also a forth, "hidden" virtual disk type:
|
---|
6190 | <i>Differencing</i>. It is "hidden" because you cannot directly
|
---|
6191 | create hard disks of this type -- they are automatically created by
|
---|
6192 | VirtualBox when necessary.
|
---|
6193 |
|
---|
6194 | <b>Differencing Hard Disks</b>
|
---|
6195 |
|
---|
6196 | Unlike disks of other types (that are similar to real hard disks),
|
---|
6197 | the differencing hard disk does not store the full range of data
|
---|
6198 | sectors. Instead, it stores only a subset of sectors of some other
|
---|
6199 | disk that were changed since the differencing hard disk has been
|
---|
6200 | created. Thus, every differencing hard disk has a parent hard disk
|
---|
6201 | it is linked to, and represents the difference between the initial
|
---|
6202 | and the current hard disk state. A differencing hard disk can be
|
---|
6203 | linked to another differencing hard disk -- this way, differencing
|
---|
6204 | hard disks can form a branch of changes. More over, a given virtual
|
---|
6205 | hard disk can have more than one differencing hard disk linked to
|
---|
6206 | it.
|
---|
6207 |
|
---|
6208 | A disk the differencing hard disk is linked to (or, in other words,
|
---|
6209 | based on) is called a <i>parent</i> hard disk and is accessible through
|
---|
6210 | the <link to="#parent"/> property. Similarly, all existing differencing
|
---|
6211 | hard disks for a given parent hard disk are called its <i>child</i> hard
|
---|
6212 | disks (and accessible through the <link to="#children"/> property).
|
---|
6213 |
|
---|
6214 | All differencing hard disks use Virtual Disk Image files to store
|
---|
6215 | changed sectors. They have the <link to="#type"/> property set to
|
---|
6216 | Normal, but can be easily distinguished from normal hard disks using
|
---|
6217 | the <link to="#parent"/> property: all differencing hard disks have
|
---|
6218 | a parent, while all normal hard disks don't.
|
---|
6219 |
|
---|
6220 | When the virtual machine makes an attempt to read a sector that is
|
---|
6221 | missing in a differencing hard disk, its parent is accessed to
|
---|
6222 | resolve the sector in question. This process continues until the
|
---|
6223 | sector is found, or until the root hard disk is encountered, which
|
---|
6224 | always contains all sectors. As a consequence,
|
---|
6225 |
|
---|
6226 | <ul>
|
---|
6227 |
|
---|
6228 | <li>
|
---|
6229 | The virtual hard disk geometry seen by the guest OS is
|
---|
6230 | always defined by the root hard disk.
|
---|
6231 | </li>
|
---|
6232 |
|
---|
6233 | <li>
|
---|
6234 | All hard disks on a branch, up to the root, must be
|
---|
6235 | <link to="#accessible"/> for a given differencing hard disk in order
|
---|
6236 | to let it function properly when the virtual machine is
|
---|
6237 | running.
|
---|
6238 | </li>
|
---|
6239 |
|
---|
6240 | </ul>
|
---|
6241 |
|
---|
6242 | Differencing hard disks can be implicitly created by VirtualBox in
|
---|
6243 | the following cases:
|
---|
6244 |
|
---|
6245 | <ul>
|
---|
6246 |
|
---|
6247 | <li>
|
---|
6248 | When a hard disk is <i>indirectly</i> attached to the virtual
|
---|
6249 | machine using <link to="IMachine::attachHardDisk()"/>. In this
|
---|
6250 | case, all disk writes performed by the guest OS will go to the
|
---|
6251 | created diffferencing hard disk, as opposed to the
|
---|
6252 | <i>direct</i> attachment, where all changes are written to the
|
---|
6253 | attached hard disk itself.
|
---|
6254 | </li>
|
---|
6255 |
|
---|
6256 | <li>
|
---|
6257 | When a <link to="ISnapshot">snapshot</link> of the virtual machine
|
---|
6258 | is taken. After that, disk writes to hard disks the differencing
|
---|
6259 | ones have been created for, will be directed to those differencing
|
---|
6260 | hard disks, to preserve the contents of the original disks.
|
---|
6261 | </li>
|
---|
6262 |
|
---|
6263 | </ul>
|
---|
6264 |
|
---|
6265 | Whether to create a differencing hard disk or not depends on the
|
---|
6266 | type of the hard disk attached to the virtual machine. This is
|
---|
6267 | explained below.
|
---|
6268 |
|
---|
6269 | Note that in the current implementation, only the
|
---|
6270 | <link to="VirtualDiskImage"/> storage type is used to
|
---|
6271 | represent differencing hard disks. In other words, all
|
---|
6272 | differencing hard disks are <link to="IVirtualDiskImage"/>
|
---|
6273 | objects.
|
---|
6274 |
|
---|
6275 | <b>Normal Hard Disks</b>
|
---|
6276 |
|
---|
6277 | Normal hard disks are the most commonly used virtual hard disk. A
|
---|
6278 | normal hard disk is attached to the machine directly if it is not
|
---|
6279 | already attached to some other machine. Otherwise, an attempt to
|
---|
6280 | make an indirect attachment through a differencing hard disk will be
|
---|
6281 | made. This attempt will fail if the hard disk is attached to a
|
---|
6282 | virtual machine without snapshots (because it's impossible to create
|
---|
6283 | a differencing hard disk based on a hard disk that is subject to
|
---|
6284 | change).
|
---|
6285 |
|
---|
6286 | When an indirect attachment takes place, in the simplest case, where
|
---|
6287 | the machine the hard disk is being attached to doesn't have
|
---|
6288 | snapshots, the differencing hard disk will be based on the normal
|
---|
6289 | hard disk being attached. Otherwise, the first (i.e. the most
|
---|
6290 | recent) descendant of the given normal hard disk found in the
|
---|
6291 | current snapshot branch (starting from the current snapshot and
|
---|
6292 | going up to the root) will be actually used as a base.
|
---|
6293 |
|
---|
6294 | Note that when you detach an indirectly attached hard disk from the
|
---|
6295 | machine, the created differencing hard disk image is simply
|
---|
6296 | <b>deleted</b>, so <b>all changes are lost</b>. If you attach the
|
---|
6297 | same disk again, a clean differencing disk will be created based on
|
---|
6298 | the most recent child, as described above.
|
---|
6299 |
|
---|
6300 | When taking a snapshot, the contents of all normal hard disks (and
|
---|
6301 | all differencing disks whose roots are normal hard disks) currently
|
---|
6302 | attached to the virtual machine is preserved by creating
|
---|
6303 | differencing hard disks based on them.
|
---|
6304 |
|
---|
6305 | <b>Immutable Hard Disks</b>
|
---|
6306 |
|
---|
6307 | Immutable hard disks can be used to provide a sort of read-only
|
---|
6308 | access. An immutable hard disk is always attached indirectly. The
|
---|
6309 | created differencing hard disk is automatically wiped out (recreated
|
---|
6310 | from scratch) every time you power off the virtual machine. Thus,
|
---|
6311 | the contents of the immutable disk remains unchanged between runs.
|
---|
6312 |
|
---|
6313 | Detaching an immutable hard disk deletes the differencing disk
|
---|
6314 | created for it, with the same effect as in case with normal hard
|
---|
6315 | disks.
|
---|
6316 |
|
---|
6317 | When taking a snapshot, the differencing part of the immutable
|
---|
6318 | hard disk is cloned (i.e. copied to a separate Virtual Disk Image
|
---|
6319 | file) without any changes. This is necessary to preserve the exact
|
---|
6320 | virtual machine state when you create an online snapshot.
|
---|
6321 |
|
---|
6322 | <b>Writethrough Hard Disks</b>
|
---|
6323 |
|
---|
6324 | Hard disks of this type are always attached directly. This means
|
---|
6325 | that every given writethrough hard disk can be attached only to one
|
---|
6326 | virtual machine at a time.
|
---|
6327 |
|
---|
6328 | It is impossible to take a snapshot of a virtual machine with the
|
---|
6329 | writethrough hard disk attached, because taking a snapshot implies
|
---|
6330 | saving the execution state and preserving the contents of all hard
|
---|
6331 | disks, but writethrough hard disks cannot be preserved. Preserving
|
---|
6332 | hard disk contents is necessary to ensure the guest OS stored in the
|
---|
6333 | snapshot will get the same hard disk state when restored, which is
|
---|
6334 | especially important when it has open file handles or when there are
|
---|
6335 | cached files and directories stored in memory.
|
---|
6336 |
|
---|
6337 | <h3>Creating, Opening and Registering Hard Disks</h3>
|
---|
6338 |
|
---|
6339 | Non-differencing hard disks are either created from scratch using
|
---|
6340 | <link to="IVirtualBox::createHardDisk()"/> or opened from a VDI file
|
---|
6341 | using <link to="IVirtualBox::openVirtualDiskImage()"/> (only for hard
|
---|
6342 | disks using the VirtualDiskImage storage type). Once a hard disk is
|
---|
6343 | created or opened, it needs to be registered using
|
---|
6344 | <link to="IVirtualBox::registerHardDisk()"/> to make it available for
|
---|
6345 | attaching to virtual machines. See the documentation of individual
|
---|
6346 | interfaces for various storage types to get more information.
|
---|
6347 |
|
---|
6348 | Differencing hard disks are never created explicitly and cannot
|
---|
6349 | be registered or unregistered; they are automatically registered
|
---|
6350 | upon creation and deregistered when deleted.
|
---|
6351 |
|
---|
6352 | <h3>More about Indirect Hard Disk Attachments</h3>
|
---|
6353 |
|
---|
6354 | Normally, when you attach a hard disk to the virtual machine, and then
|
---|
6355 | query the corresponding attachment using
|
---|
6356 | <link to="IMachine::getHardDisk()"/> or
|
---|
6357 | <link to="IMachine::hardDiskAttachments"/> you will get the same hard
|
---|
6358 | disk object, whose UUID you passed earlier to
|
---|
6359 | <link to="IMachine::attachHardDisk()"/>. However, when an indirect
|
---|
6360 | attachment takes place, calling <link to="IMachine::getHardDisk()"/>
|
---|
6361 | will return a differencing hard disk object, that is either based on the
|
---|
6362 | attached hard disk or on another differencing hard disk, the attached
|
---|
6363 | hard disk is eventually a root for (as described above). In both cases
|
---|
6364 | the returned hard disk object is the object the virtual machine actually
|
---|
6365 | uses to perform disk writes to.
|
---|
6366 |
|
---|
6367 | Regardless of whether the attachment is direct or indirect, the
|
---|
6368 | <link to="#machineId"/> property of the attached disk will contain an
|
---|
6369 | UUID of the machine object <link to="IMachine::attachHardDisk()"/>
|
---|
6370 | has been called on.
|
---|
6371 |
|
---|
6372 | Note that both <link to="IMachine::attachHardDisk()"/> and
|
---|
6373 | <link to="IMachine::detachHardDisk()"/> are <i>lazy</i> operations. In
|
---|
6374 | particular, this means that when an indirect attachment is made,
|
---|
6375 | differencing hard disks are not created until machine settings are
|
---|
6376 | committed using <link to="IMachine::saveSettings()"/>. Similarly, when a
|
---|
6377 | differencing hard disk is detached, it is not deleted until
|
---|
6378 | <link to="IMachine::saveSettings()"/> is called. Calling
|
---|
6379 | <link to="IMachine::discardSettings()"/> cancels all lazy attachments or
|
---|
6380 | detachments made since the last commit and effectively restores the
|
---|
6381 | previous set of hard disks.
|
---|
6382 |
|
---|
6383 | <h3>Hard Disk Accessibility</h3>
|
---|
6384 |
|
---|
6385 | The <link to="#accessible"/> attribute of the hard disk object
|
---|
6386 | defines the accessibility state of the respective hard disk storage
|
---|
6387 | (for example, the VDI file for IVirtualDiskImage objects). If the
|
---|
6388 | value of this attribute is <tt>false</tt> then some hard disk
|
---|
6389 | attributes may contain invalid or outdated values (for example, the
|
---|
6390 | virtual or the actual hard disk size) until a new accessibility
|
---|
6391 | check is done that returns <tt>true</tt> (see the attribute
|
---|
6392 | description for more details).
|
---|
6393 |
|
---|
6394 | <note>
|
---|
6395 | Because of the possible slowness of the accessibility check,
|
---|
6396 | it is not implicitly performed upon the VirtualBox server startup
|
---|
6397 | (to prevent the application freeze). In partcular, this means that
|
---|
6398 | if you try to read hard disk properties that depend on the
|
---|
6399 | accessibility state without first reading the value of the
|
---|
6400 | <link to="#accessible"/> attribute and ensuring it's value is
|
---|
6401 | <tt>true</tt>, you will get wrong (zero) values.
|
---|
6402 | </note>
|
---|
6403 |
|
---|
6404 | </desc>
|
---|
6405 |
|
---|
6406 | <attribute name="id" type="uuid" readonly="yes">
|
---|
6407 | <desc>
|
---|
6408 |
|
---|
6409 | UUID of the hard disk. For newly created hard disk objects,
|
---|
6410 | this value is a randomly generated UUID.
|
---|
6411 |
|
---|
6412 | </desc>
|
---|
6413 | </attribute>
|
---|
6414 |
|
---|
6415 | <attribute name="description" type="wstring">
|
---|
6416 | <desc>
|
---|
6417 |
|
---|
6418 | Optional description of the hard disk. For a newly created hard
|
---|
6419 | disk, this value is <tt>null</tt>.
|
---|
6420 |
|
---|
6421 | <note>For some storage types, reading this property is
|
---|
6422 | meaningless when <link to="#accessible"/> is <tt>false</tt>.
|
---|
6423 | Also, you cannot assign it a new value in this case.</note>
|
---|
6424 |
|
---|
6425 | </desc>
|
---|
6426 | </attribute>
|
---|
6427 |
|
---|
6428 | <attribute name="storageType" type="HardDiskStorageType" readonly="yes">
|
---|
6429 | <desc>
|
---|
6430 |
|
---|
6431 | Storage type of this hard disk.
|
---|
6432 |
|
---|
6433 | Storage type is defined when you open or create a new hard disk
|
---|
6434 | object.
|
---|
6435 |
|
---|
6436 | </desc>
|
---|
6437 | </attribute>
|
---|
6438 |
|
---|
6439 | <attribute name="location" type="wstring" readonly="yes">
|
---|
6440 | <desc>
|
---|
6441 |
|
---|
6442 | Storage location of this hard disk. The returned string serves
|
---|
6443 | for informational purposes only. To access detailed information
|
---|
6444 | about the storage, query the appropriate storage-specific
|
---|
6445 | interface.
|
---|
6446 |
|
---|
6447 | </desc>
|
---|
6448 | </attribute>
|
---|
6449 |
|
---|
6450 | <attribute name="type" type="HardDiskType">
|
---|
6451 | <desc>
|
---|
6452 |
|
---|
6453 | Type (behavior) of this hard disk. For a newly created or opened hard
|
---|
6454 | disk, this value is <link to="HardDiskType::Normal"/>.
|
---|
6455 |
|
---|
6456 | <note>
|
---|
6457 | In the current implementation, this property can be
|
---|
6458 | changed only on an unregistered hard disk object. This may be
|
---|
6459 | changed later.
|
---|
6460 | </note>
|
---|
6461 |
|
---|
6462 | </desc>
|
---|
6463 | </attribute>
|
---|
6464 |
|
---|
6465 | <attribute name="parent" type="IHardDisk" readonly="yes">
|
---|
6466 | <desc>
|
---|
6467 |
|
---|
6468 | Parent of this hard disk (a hard disk this one is directly based
|
---|
6469 | on).
|
---|
6470 |
|
---|
6471 | Only differencing hard disks have parents, so a <tt>null</tt>
|
---|
6472 | object is returned for a hard disk of any other type.
|
---|
6473 | </desc>
|
---|
6474 | </attribute>
|
---|
6475 |
|
---|
6476 | <attribute name="children" type="IHardDiskCollection" readonly="yes">
|
---|
6477 | <desc>
|
---|
6478 |
|
---|
6479 | Children of this hard disk (all differencing hard disks for
|
---|
6480 | those this one is a parent). An empty collection is returned, if
|
---|
6481 | this hard disk doesn't have any children.
|
---|
6482 |
|
---|
6483 | </desc>
|
---|
6484 | </attribute>
|
---|
6485 |
|
---|
6486 | <attribute name="root" type="IHardDisk" readonly="yes">
|
---|
6487 | <desc>
|
---|
6488 |
|
---|
6489 | Root hard disk of this hard disk. If this hard disk is a
|
---|
6490 | differencing hard disk, its root hard disk is the first disk on
|
---|
6491 | the branch. For all other types of hard disks, this property
|
---|
6492 | returns the hard disk object itself (i.e. the same object you
|
---|
6493 | read this property on).
|
---|
6494 |
|
---|
6495 | </desc>
|
---|
6496 | </attribute>
|
---|
6497 |
|
---|
6498 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
6499 | <desc>
|
---|
6500 |
|
---|
6501 | Whether the hard disk storage is currently accessible or not.
|
---|
6502 | The storage, for example, can be unaccessible if it doesn't exist
|
---|
6503 | or if it is placed on a network resource that is not available
|
---|
6504 | by the time this attribute is read.
|
---|
6505 |
|
---|
6506 | In the current implementation, the value of this property is
|
---|
6507 | also <tt>false</tt> if this hard disk is attached to a running
|
---|
6508 | virtual machine.
|
---|
6509 |
|
---|
6510 | The accessibility check is performed automatically every time
|
---|
6511 | this attribute is read. You should keep it in mind that this check
|
---|
6512 | may be slow and can block the calling thread for a long time (for
|
---|
6513 | example, if the network resourse where the hard disk storage is
|
---|
6514 | located is down).
|
---|
6515 |
|
---|
6516 | The following attributes of the hard disk object are considered
|
---|
6517 | to be invalid when this attribute is <tt>false</tt>:
|
---|
6518 | <ul>
|
---|
6519 | <li><link to="#size"/></li>
|
---|
6520 | <li><link to="#actualSize"/></li>
|
---|
6521 | </ul>
|
---|
6522 | Individual hard disk storage type interfaces may define
|
---|
6523 | additional attributes that depend on the accessibility state.
|
---|
6524 | </desc>
|
---|
6525 | </attribute>
|
---|
6526 |
|
---|
6527 | <attribute name="allAccessible" type="boolean" readonly="yes">
|
---|
6528 | <desc>
|
---|
6529 |
|
---|
6530 | Whether the whole hard disk branch, starting from this image and
|
---|
6531 | going through its ancestors up to the root, is accessible or
|
---|
6532 | not.
|
---|
6533 |
|
---|
6534 | This property makes sense only for differencing hard disks. For
|
---|
6535 | all other types of hard disks it returns the same value as
|
---|
6536 | <link to="#accessible"/>.
|
---|
6537 |
|
---|
6538 | </desc>
|
---|
6539 | </attribute>
|
---|
6540 |
|
---|
6541 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
6542 | <desc>
|
---|
6543 |
|
---|
6544 | String describing the reason of inaccessibility of this hard
|
---|
6545 | disk after the last call to <link to="#accessible"/> that
|
---|
6546 | returned <tt>false</tt>. A <tt>null</tt> value of this property
|
---|
6547 | means that the last accessibility check returned <tt>true</tt>.
|
---|
6548 |
|
---|
6549 | </desc>
|
---|
6550 | </attribute>
|
---|
6551 |
|
---|
6552 | <attribute name="size" type="unsigned long long" readonly="yes">
|
---|
6553 | <desc>
|
---|
6554 |
|
---|
6555 | Logical size of this hard disk (in megabytes), as reported to the
|
---|
6556 | guest OS running inside the vurtual machine this disk is
|
---|
6557 | attached to. The logical size is defined when the hard disk is
|
---|
6558 | created.
|
---|
6559 |
|
---|
6560 | <note>Reading this property on a differencing hard disk will
|
---|
6561 | return the size of its root hard disk.</note>
|
---|
6562 |
|
---|
6563 | <note>Reading this property is meaningless when
|
---|
6564 | <link to="#accessible"/> is <tt>false</tt></note>
|
---|
6565 |
|
---|
6566 | </desc>
|
---|
6567 | </attribute>
|
---|
6568 |
|
---|
6569 | <attribute name="actualSize" type="unsigned long long" readonly="yes">
|
---|
6570 | <desc>
|
---|
6571 |
|
---|
6572 | Physical size of the storage used to store hard disk data (in
|
---|
6573 | bytes). This size is usually less than the logical size of the
|
---|
6574 | hard disk, depending on the storage type and on the size
|
---|
6575 | optimization method used for that storage.
|
---|
6576 |
|
---|
6577 | <note>Reading this property is meaningless when
|
---|
6578 | <link to="#accessible"/> is <tt>false</tt></note>
|
---|
6579 |
|
---|
6580 | </desc>
|
---|
6581 | </attribute>
|
---|
6582 |
|
---|
6583 | <attribute name="machineId" type="uuid" readonly="yes">
|
---|
6584 | <desc>
|
---|
6585 |
|
---|
6586 | UUID of the machine this hard disk is attached to (or a
|
---|
6587 | <tt>null</tt> UUID if it is not attached).
|
---|
6588 |
|
---|
6589 | <note>Immutable hard disks are never attached directly, so this
|
---|
6590 | attribute is always <tt>null</tt> in this case.</note>
|
---|
6591 |
|
---|
6592 | </desc>
|
---|
6593 | </attribute>
|
---|
6594 |
|
---|
6595 | <attribute name="snapshotId" type="uuid" readonly="yes">
|
---|
6596 | <desc>
|
---|
6597 |
|
---|
6598 | UUID of the <link to="ISnapshot">snapshot</link> this hard disk
|
---|
6599 | is associated with (or <tt>null</tt> UUID if it is not
|
---|
6600 | associated with any snapshot).
|
---|
6601 |
|
---|
6602 | <note>
|
---|
6603 | This attribute is always <tt>null</tt> if <link to="#machineId"/>
|
---|
6604 | is <tt>null</tt>.
|
---|
6605 | </note>
|
---|
6606 |
|
---|
6607 | <note>
|
---|
6608 | Writethrough hard disks are always attached directly and cannot be
|
---|
6609 | involved when taking snapshots, so this attribute is meaningless and
|
---|
6610 | therefore always <tt>null</tt>.
|
---|
6611 | </note>
|
---|
6612 |
|
---|
6613 | </desc>
|
---|
6614 | </attribute>
|
---|
6615 |
|
---|
6616 | <method name="cloneToImage">
|
---|
6617 |
|
---|
6618 | <desc>
|
---|
6619 |
|
---|
6620 | Starts creating a clone of this hard disk. The cloned hard disk
|
---|
6621 | will use the specified Virtual Disk Image file as a storage and
|
---|
6622 | will contain exactly the same sector data as the hard disk being
|
---|
6623 | cloned, except that a new UUID for the clone will be randomly
|
---|
6624 | generated.
|
---|
6625 |
|
---|
6626 | The specified image file path can be absolute (full path) or
|
---|
6627 | relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
|
---|
6628 | home directory</link>. If only a file name without any path is
|
---|
6629 | given, the <link to="ISystemProperties::defaultVDIFolder">
|
---|
6630 | default VDI folder</link> will be used as a path to the image
|
---|
6631 | file.
|
---|
6632 |
|
---|
6633 | It is an error to use the object returned in the @a image
|
---|
6634 | parameter until the returned @a progress object reports success.
|
---|
6635 |
|
---|
6636 | <note>In the current implementation, only non-differencing hard
|
---|
6637 | disks can be cloned.</note>
|
---|
6638 |
|
---|
6639 | </desc>
|
---|
6640 |
|
---|
6641 | <param name="filePath" type="wstring" dir="in">
|
---|
6642 | <desc>Path to a file where to store the cloned hard disk.</desc>
|
---|
6643 | </param>
|
---|
6644 | <param name="image" type="IVirtualDiskImage" dir="out">
|
---|
6645 | <desc>Cloned hard disk object.</desc>
|
---|
6646 | </param>
|
---|
6647 | <param name="progress" type="IProgress" dir="return">
|
---|
6648 | <desc>Progress object to track the operation completion.</desc>
|
---|
6649 | </param>
|
---|
6650 |
|
---|
6651 | </method>
|
---|
6652 |
|
---|
6653 | </interface>
|
---|
6654 |
|
---|
6655 | <!--
|
---|
6656 | // IVirtualDiskImage
|
---|
6657 | /////////////////////////////////////////////////////////////////////////
|
---|
6658 | -->
|
---|
6659 |
|
---|
6660 | <interface
|
---|
6661 | name="IVirtualDiskImage" extends="$unknown"
|
---|
6662 | uuid="a8265b5a-0d20-4a46-a02f-65693a4e8239"
|
---|
6663 | wsmap="managed"
|
---|
6664 | >
|
---|
6665 |
|
---|
6666 | <desc>
|
---|
6667 | The IVirtualDiskImage interface represent a specific type of
|
---|
6668 | <link to="IHardDisk" /> that uses VDI image files.
|
---|
6669 |
|
---|
6670 | The Virtual Disk Image (VDI) format is VirtualBox's native format for
|
---|
6671 | hard disk containers.
|
---|
6672 |
|
---|
6673 | Objects that support this interface also support the
|
---|
6674 | <link to="IHardDisk"/> interface.
|
---|
6675 |
|
---|
6676 | Hard disks using virtual disk images can be either opened using
|
---|
6677 | <link to="IVirtualBox::openHardDisk()"/> or created from
|
---|
6678 | scratch using <link to="IVirtualBox::createHardDisk()"/>.
|
---|
6679 |
|
---|
6680 | When a new hard disk object is created from scratch, an image file for it
|
---|
6681 | is not automatically created. To do it, you need to specify a
|
---|
6682 | valid <link to="#filePath">file path</link>, and call
|
---|
6683 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
|
---|
6684 | When it is done, the hard disk object can be registered by calling
|
---|
6685 | <link to="IVirtualBox::registerHardDisk()"/> and then
|
---|
6686 | <link to="IMachine::attachHardDisk()">attached</link> to
|
---|
6687 | virtual machines.
|
---|
6688 |
|
---|
6689 | The <link to="IHardDisk::description">description</link> of the
|
---|
6690 | Virtual Disk Image is stored in the image file. For this reason,
|
---|
6691 | changing the value of this property requires the hard disk to be
|
---|
6692 | <link to="IHardDisk::accessible">accessible</link>. The description
|
---|
6693 | of a registered hard disk can be changed only if a virtual machine
|
---|
6694 | using it is not running.
|
---|
6695 |
|
---|
6696 | </desc>
|
---|
6697 |
|
---|
6698 | <attribute name="filePath" type="wstring">
|
---|
6699 | <desc>
|
---|
6700 |
|
---|
6701 | Full file name of the virtual disk image of this hard disk. For
|
---|
6702 | newly created hard disk objects, this value is <tt>null</tt>.
|
---|
6703 |
|
---|
6704 | When assigning a new path, it can be absolute (full path) or relative
|
---|
6705 | to the <link to="IVirtualBox::homeFolder"> VirtualBox home
|
---|
6706 | directory</link>. If only a file name without any path is given,
|
---|
6707 | the <link to="ISystemProperties::defaultVDIFolder"> default VDI
|
---|
6708 | folder</link> will be used as a path to the image file.
|
---|
6709 |
|
---|
6710 | When reading this propery, a full path is always returned.
|
---|
6711 |
|
---|
6712 | <note>
|
---|
6713 | This property cannot be changed when <link to="#created"/>
|
---|
6714 | returns <tt>true</tt>.
|
---|
6715 | </note>
|
---|
6716 |
|
---|
6717 | </desc>
|
---|
6718 | </attribute>
|
---|
6719 |
|
---|
6720 | <attribute name="created" type="boolean" readonly="yes">
|
---|
6721 | <desc>
|
---|
6722 |
|
---|
6723 | Whether the virual disk image is created or not. For newly
|
---|
6724 | created hard disk objects or after a successful invocation of
|
---|
6725 | <link to="#deleteImage()"/>, this value is <tt>false</tt> until
|
---|
6726 | <link to="#createFixedImage()"/> or <link
|
---|
6727 | to="#createDynamicImage()"/> is called.
|
---|
6728 |
|
---|
6729 | </desc>
|
---|
6730 | </attribute>
|
---|
6731 |
|
---|
6732 | <method name="createDynamicImage">
|
---|
6733 |
|
---|
6734 | <desc>
|
---|
6735 |
|
---|
6736 | Starts creating a dymically expanding hard disk image in the
|
---|
6737 | background. The previous image associated with this object, if
|
---|
6738 | any, must be deleted using <link to="#deleteImage"/>, otherwise
|
---|
6739 | the operation will fail.
|
---|
6740 |
|
---|
6741 | <note>After the returned progress object reports that the
|
---|
6742 | operation is complete, this hard disk object can be
|
---|
6743 | <link to="IVirtualBox::registerHardDisk()">registered</link>
|
---|
6744 | within this VirtualBox installation.</note>
|
---|
6745 |
|
---|
6746 | </desc>
|
---|
6747 |
|
---|
6748 | <param name="size" type="unsigned long long" dir="in">
|
---|
6749 | <desc>Maximum logical size of the hard disk in megabytes.</desc>
|
---|
6750 | </param>
|
---|
6751 | <param name="progress" type="IProgress" dir="return">
|
---|
6752 | <desc>Progress object to track the operation completion.</desc>
|
---|
6753 | </param>
|
---|
6754 |
|
---|
6755 | </method>
|
---|
6756 |
|
---|
6757 | <method name="createFixedImage">
|
---|
6758 | <desc>
|
---|
6759 |
|
---|
6760 | Starts creating a fixed-size hard disk image in the background. The
|
---|
6761 | previous image, if any, must be deleted using
|
---|
6762 | <link to="#deleteImage"/>, otherwise the operation will fail.
|
---|
6763 |
|
---|
6764 | <note>
|
---|
6765 | After the returned progress object reports that the
|
---|
6766 | operation is complete, this hard disk object can be
|
---|
6767 | <link to="IVirtualBox::registerHardDisk()">registered</link>
|
---|
6768 | within this VirtualBox installation.
|
---|
6769 | </note>
|
---|
6770 |
|
---|
6771 | </desc>
|
---|
6772 |
|
---|
6773 | <param name="size" type="unsigned long long" dir="in">
|
---|
6774 | <desc>Logical size of the hard disk in megabytes.</desc>
|
---|
6775 | </param>
|
---|
6776 | <param name="progress" type="IProgress" dir="return">
|
---|
6777 | <desc>Progress object to track the operation completion.</desc>
|
---|
6778 | </param>
|
---|
6779 |
|
---|
6780 | </method>
|
---|
6781 |
|
---|
6782 | <method name="deleteImage">
|
---|
6783 | <desc>
|
---|
6784 |
|
---|
6785 | Deletes the existing hard disk image. The hard disk must not be
|
---|
6786 | registered within this VirtualBox installation, otherwise the
|
---|
6787 | operation will fail.
|
---|
6788 |
|
---|
6789 | <note>
|
---|
6790 | After this operation succeeds, it will be impossible to
|
---|
6791 | register the hard disk until the image file is created
|
---|
6792 | again.
|
---|
6793 | </note>
|
---|
6794 |
|
---|
6795 | <note>
|
---|
6796 | This operation is valid only for non-differencing hard disks, after
|
---|
6797 | they are unregistered using
|
---|
6798 | <link to="IVirtualBox::unregisterHardDisk()"/>.
|
---|
6799 | </note>
|
---|
6800 |
|
---|
6801 | </desc>
|
---|
6802 | </method>
|
---|
6803 |
|
---|
6804 | </interface>
|
---|
6805 |
|
---|
6806 | <!--
|
---|
6807 | // IISCSIHardDisk
|
---|
6808 | /////////////////////////////////////////////////////////////////////////
|
---|
6809 | -->
|
---|
6810 |
|
---|
6811 | <interface
|
---|
6812 | name="IISCSIHardDisk" extends="$unknown"
|
---|
6813 | uuid="003f6ca9-3257-4ef9-99c9-c66ce44576cb"
|
---|
6814 | wsmap="managed"
|
---|
6815 | >
|
---|
6816 |
|
---|
6817 | <desc>
|
---|
6818 | THe IISCSIHardDisk interface represents a specific type of
|
---|
6819 | <link to="IHardDisk"/> that uses iSCSI.
|
---|
6820 |
|
---|
6821 | The IISCSIHardDisk interface represents <link to="IHardDisk">virtual
|
---|
6822 | hard disks</link> that use the Internet SCSI (iSCSI) protocol to store
|
---|
6823 | hard disk data on remote machines.
|
---|
6824 |
|
---|
6825 | Objects that support this interface also support the
|
---|
6826 | <link to="IHardDisk"/> interface.
|
---|
6827 |
|
---|
6828 | iSCSI hard disks can be created using
|
---|
6829 | <link to="IVirtualBox::createHardDisk()"/>. When a new hard disk object
|
---|
6830 | is created, all its properties are uninitialized. After you assign some
|
---|
6831 | meaningful values to them, the hard disk object can be registered by
|
---|
6832 | calling <link to="IVirtualBox::registerHardDisk()"/> and
|
---|
6833 | then <link to="IMachine::attachHardDisk()">attached</link> to virtual
|
---|
6834 | machines.
|
---|
6835 |
|
---|
6836 | The <link to="IHardDisk::description">description</link>
|
---|
6837 | of the iSCSI hard disk is stored in the VirtualBox
|
---|
6838 | configuration file, so it can be changed (at appropriate
|
---|
6839 | times) even when
|
---|
6840 | <link to="IHardDisk::accessible">accessible</link> returns
|
---|
6841 | <tt>false</tt>. However, the hard disk must not be
|
---|
6842 | attached to a running virtual machine.
|
---|
6843 |
|
---|
6844 | <note>
|
---|
6845 | In the current imlementation, the type of all iSCSI hard disks
|
---|
6846 | is <link to="HardDiskType::Writethrough">Writethrough</link>
|
---|
6847 | and cannot be changed.
|
---|
6848 | </note>
|
---|
6849 |
|
---|
6850 | </desc>
|
---|
6851 |
|
---|
6852 | <attribute name="server" type="wstring">
|
---|
6853 | <desc>
|
---|
6854 |
|
---|
6855 | iSCSI Server name (either a host name or an IP address). For
|
---|
6856 | newly created hard disk objects, this value is <tt>null</tt>.
|
---|
6857 |
|
---|
6858 | </desc>
|
---|
6859 | </attribute>
|
---|
6860 |
|
---|
6861 | <attribute name="port" type="unsigned short">
|
---|
6862 | <desc>
|
---|
6863 |
|
---|
6864 | iSCSI Server port. For newly created hard disk objects, this
|
---|
6865 | value is <tt>0</tt>, which means the default port.
|
---|
6866 |
|
---|
6867 | </desc>
|
---|
6868 | </attribute>
|
---|
6869 |
|
---|
6870 | <attribute name="target" type="wstring">
|
---|
6871 | <desc>
|
---|
6872 |
|
---|
6873 | iSCSI target name. For newly created hard disk objects, this
|
---|
6874 | value is <tt>null</tt>.
|
---|
6875 |
|
---|
6876 | </desc>
|
---|
6877 | </attribute>
|
---|
6878 |
|
---|
6879 | <attribute name="lun" type="unsigned long long">
|
---|
6880 | <desc>
|
---|
6881 |
|
---|
6882 | Logical unit number for this iSCSI disk. For newly created hard
|
---|
6883 | disk objects, this value is <tt>0</tt>.
|
---|
6884 |
|
---|
6885 | </desc>
|
---|
6886 | </attribute>
|
---|
6887 |
|
---|
6888 | <attribute name="userName" type="wstring">
|
---|
6889 | <desc>
|
---|
6890 |
|
---|
6891 | User name for accessing this iSCSI disk. For newly created hard
|
---|
6892 | disk objects, this value is <tt>null</tt>.
|
---|
6893 |
|
---|
6894 | </desc>
|
---|
6895 | </attribute>
|
---|
6896 |
|
---|
6897 | <attribute name="password" type="wstring">
|
---|
6898 | <desc>
|
---|
6899 |
|
---|
6900 | User password for accessing this iSCSI disk. For newly created
|
---|
6901 | hard disk objects, this value is <tt>null</tt>.
|
---|
6902 |
|
---|
6903 | </desc>
|
---|
6904 | </attribute>
|
---|
6905 |
|
---|
6906 | </interface>
|
---|
6907 |
|
---|
6908 | <!--
|
---|
6909 | // IVMDKImage
|
---|
6910 | /////////////////////////////////////////////////////////////////////////
|
---|
6911 | -->
|
---|
6912 |
|
---|
6913 | <interface
|
---|
6914 | name="IVMDKImage" extends="$unknown"
|
---|
6915 | uuid="178398f5-8559-4fee-979e-420af5b53eef"
|
---|
6916 | wsmap="managed"
|
---|
6917 | >
|
---|
6918 | <desc>
|
---|
6919 | The IVMDKImage interface represents a specific type of
|
---|
6920 | <link to="IHardDisk"/> that uses VMDK image files.
|
---|
6921 |
|
---|
6922 | The Virtual Machine Disk (VMDK) format is the industry standard format
|
---|
6923 | for virtual hard disk image files, which VirtualBox supports besides its
|
---|
6924 | own native VDI format.
|
---|
6925 |
|
---|
6926 | Objects that support this interface also support the
|
---|
6927 | <link to="IHardDisk"/> interface.
|
---|
6928 |
|
---|
6929 | Hard disks using VMDK images can be either opened using
|
---|
6930 | <link to="IVirtualBox::openHardDisk()"/> or created from
|
---|
6931 | scratch using <link to="IVirtualBox::createHardDisk()"/>.
|
---|
6932 |
|
---|
6933 | When a new hard disk object is created from scratch, an image file for it
|
---|
6934 | is not automatically created. To do it, you need to specify a
|
---|
6935 | valid <link to="#filePath">file path</link>, and call
|
---|
6936 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
|
---|
6937 | When it is done, the hard disk object can be registered by calling
|
---|
6938 | <link to="IVirtualBox::registerHardDisk()"/> and then
|
---|
6939 | <link to="IMachine::attachHardDisk()">attached</link> to
|
---|
6940 | virtual machines.
|
---|
6941 |
|
---|
6942 | The <link to="IHardDisk::description">description</link>
|
---|
6943 | of the VMDK hard disk is stored in the VirtualBox
|
---|
6944 | configuration file, so it can be changed (at appropriate
|
---|
6945 | times) even when
|
---|
6946 | <link to="IHardDisk::accessible">accessible</link> returns
|
---|
6947 | <tt>false</tt>. However, the hard disk must not be
|
---|
6948 | attached to a running virtual machine.
|
---|
6949 |
|
---|
6950 | <note>
|
---|
6951 | In the current imlementation, the type of all VMDK hard disks
|
---|
6952 | is <link to="HardDiskType::Writethrough">Writethrough</link> and cannot
|
---|
6953 | be changed.
|
---|
6954 | </note>
|
---|
6955 |
|
---|
6956 | </desc>
|
---|
6957 |
|
---|
6958 | <attribute name="filePath" type="wstring">
|
---|
6959 | <desc>
|
---|
6960 |
|
---|
6961 | Full file name of the VMDK image of this hard disk. For
|
---|
6962 | newly created hard disk objects, this value is <tt>null</tt>.
|
---|
6963 |
|
---|
6964 | When assigning a new path, it can be absolute (full path) or relative
|
---|
6965 | to the <link to="IVirtualBox::homeFolder"> VirtualBox home
|
---|
6966 | directory</link>. If only a file name without any path is given,
|
---|
6967 | the <link to="ISystemProperties::defaultVDIFolder"> default VDI
|
---|
6968 | folder</link> will be used as a path to the image file.
|
---|
6969 |
|
---|
6970 | When reading this propery, a full path is always returned.
|
---|
6971 |
|
---|
6972 | <note>
|
---|
6973 | This property cannot be changed when <link to="#created"/>
|
---|
6974 | returns <tt>true</tt>.
|
---|
6975 | </note>
|
---|
6976 |
|
---|
6977 | </desc>
|
---|
6978 | </attribute>
|
---|
6979 |
|
---|
6980 | <attribute name="created" type="boolean" readonly="yes">
|
---|
6981 | <desc>
|
---|
6982 |
|
---|
6983 | Whether the virual disk image is created or not. For newly created
|
---|
6984 | hard disk objects or after a successful invocation of
|
---|
6985 | <link to="#deleteImage()"/>, this value is <tt>false</tt> until
|
---|
6986 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
|
---|
6987 | is called.
|
---|
6988 |
|
---|
6989 | </desc>
|
---|
6990 | </attribute>
|
---|
6991 |
|
---|
6992 | <method name="createDynamicImage">
|
---|
6993 |
|
---|
6994 | <desc>
|
---|
6995 |
|
---|
6996 | Starts creating a dymically expanding hard disk image in the
|
---|
6997 | background. The previous image associated with this object, if
|
---|
6998 | any, must be deleted using <link to="#deleteImage"/>, otherwise
|
---|
6999 | the operation will fail.
|
---|
7000 |
|
---|
7001 | <note>
|
---|
7002 | After the returned progress object reports that the
|
---|
7003 | operation is complete, this hard disk object can be
|
---|
7004 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7005 | this VirtualBox installation.
|
---|
7006 | </note>
|
---|
7007 |
|
---|
7008 | </desc>
|
---|
7009 |
|
---|
7010 | <param name="size" type="unsigned long long" dir="in">
|
---|
7011 | <desc>Maximum logical size of the hard disk in megabytes.</desc>
|
---|
7012 | </param>
|
---|
7013 | <param name="progress" type="IProgress" dir="return">
|
---|
7014 | <desc>Progress object to track the operation completion.</desc>
|
---|
7015 | </param>
|
---|
7016 |
|
---|
7017 | </method>
|
---|
7018 |
|
---|
7019 | <method name="createFixedImage">
|
---|
7020 | <desc>
|
---|
7021 |
|
---|
7022 | Starts creating a fixed-size hard disk image in the background. The
|
---|
7023 | previous image, if any, must be deleted using
|
---|
7024 | <link to="#deleteImage"/>, otherwise the operation will fail.
|
---|
7025 |
|
---|
7026 | <note>
|
---|
7027 | After the returned progress object reports that the
|
---|
7028 | operation is complete, this hard disk object can be
|
---|
7029 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7030 | this VirtualBox installation.
|
---|
7031 | </note>
|
---|
7032 |
|
---|
7033 | </desc>
|
---|
7034 |
|
---|
7035 | <param name="size" type="unsigned long long" dir="in">
|
---|
7036 | <desc>Logical size of the hard disk in megabytes.</desc>
|
---|
7037 | </param>
|
---|
7038 | <param name="progress" type="IProgress" dir="return">
|
---|
7039 | <desc>Progress object to track the operation completion.</desc>
|
---|
7040 | </param>
|
---|
7041 |
|
---|
7042 | </method>
|
---|
7043 |
|
---|
7044 | <method name="deleteImage">
|
---|
7045 | <desc>
|
---|
7046 |
|
---|
7047 | Deletes the existing hard disk image. The hard disk must not be
|
---|
7048 | registered within this VirtualBox installation, otherwise the
|
---|
7049 | operation will fail.
|
---|
7050 |
|
---|
7051 | <note>
|
---|
7052 | After this operation succeeds, it will be impossible to register the
|
---|
7053 | hard disk until the image file is created again.
|
---|
7054 | </note>
|
---|
7055 |
|
---|
7056 | <note>
|
---|
7057 | This operation is valid only for non-differencing hard disks, after
|
---|
7058 | they are unregistered using
|
---|
7059 | <link to="IVirtualBox::unregisterHardDisk()"/>.
|
---|
7060 | </note>
|
---|
7061 |
|
---|
7062 | </desc>
|
---|
7063 | </method>
|
---|
7064 |
|
---|
7065 | </interface>
|
---|
7066 |
|
---|
7067 | <!--
|
---|
7068 | // ICustomHardDisk
|
---|
7069 | /////////////////////////////////////////////////////////////////////////
|
---|
7070 | -->
|
---|
7071 |
|
---|
7072 | <interface
|
---|
7073 | name="ICustomHardDisk" extends="$unknown"
|
---|
7074 | uuid="a7b0236d-3ff4-47c0-a4aa-ddc4ddc1141a"
|
---|
7075 | wsmap="managed"
|
---|
7076 | >
|
---|
7077 | <desc>
|
---|
7078 | The ICustomHardDisk interface represents a specific type of
|
---|
7079 | <link to="IHardDisk" /> that is supported through a third-party plugin.
|
---|
7080 |
|
---|
7081 | This interface allows to add support for custom hard disk formats to
|
---|
7082 | VirtualBox.
|
---|
7083 |
|
---|
7084 | Objects that support this interface also support the
|
---|
7085 | <link to="IHardDisk"/> interface.
|
---|
7086 |
|
---|
7087 | Hard disks using custom hard disk formats can be either opened using
|
---|
7088 | <link to="IVirtualBox::openHardDisk()"/> or created from scratch using
|
---|
7089 | <link to="IVirtualBox::createHardDisk()"/>.
|
---|
7090 |
|
---|
7091 | When a new hard disk object is created from scratch, an image file for
|
---|
7092 | it is not automatically created. To do it, you need to specify a
|
---|
7093 | valid <link to="#location">location</link>, and call
|
---|
7094 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
|
---|
7095 | When it is done, the hard disk object can be registered by calling
|
---|
7096 | <link to="IVirtualBox::registerHardDisk()"/> and then
|
---|
7097 | <link to="IMachine::attachHardDisk()">attached</link> to
|
---|
7098 | virtual machines.
|
---|
7099 |
|
---|
7100 | The <link to="IHardDisk::description">description</link>
|
---|
7101 | of the hard disk is stored in the VirtualBox
|
---|
7102 | configuration file, so it can be changed (at appropriate
|
---|
7103 | times) even when
|
---|
7104 | <link to="IHardDisk::accessible">accessible</link> returns
|
---|
7105 | <tt>false</tt>. However, the hard disk must not be
|
---|
7106 | attached to a running virtual machine.
|
---|
7107 |
|
---|
7108 | </desc>
|
---|
7109 |
|
---|
7110 | <attribute name="location" type="wstring">
|
---|
7111 | <desc>
|
---|
7112 |
|
---|
7113 | Location of this custom hard disk. For
|
---|
7114 | newly created hard disk objects, this value is <tt>null</tt>.
|
---|
7115 |
|
---|
7116 | The format of the location string is plugin-dependent. In case if the
|
---|
7117 | plugin uses a regular file in the local file system to store hard disk
|
---|
7118 | data, then the location is a file path and the following rules apply:
|
---|
7119 | <ul>
|
---|
7120 | <li>
|
---|
7121 | when assigning a new path, it must be absolute (full path) or
|
---|
7122 | relative to the <link to="IVirtualBox::homeFolder"> VirtualBox
|
---|
7123 | home directory</link>. If only a file name without any path is
|
---|
7124 | given, the <link to="ISystemProperties::defaultVDIFolder"> default
|
---|
7125 | VDI folder</link> will be used as a path to the image file.
|
---|
7126 | </li>
|
---|
7127 | <li>
|
---|
7128 | When reading this propery, a full path is always returned.
|
---|
7129 | </li>
|
---|
7130 | </ul>
|
---|
7131 |
|
---|
7132 | <note>
|
---|
7133 | This property cannot be changed when <link to="#created"/>
|
---|
7134 | returns <tt>true</tt>.
|
---|
7135 | </note>
|
---|
7136 |
|
---|
7137 | </desc>
|
---|
7138 | </attribute>
|
---|
7139 |
|
---|
7140 | <attribute name="format" type="wstring" readonly="yes">
|
---|
7141 | <desc>
|
---|
7142 |
|
---|
7143 | The plugin name of the image file.
|
---|
7144 |
|
---|
7145 | </desc>
|
---|
7146 | </attribute>
|
---|
7147 |
|
---|
7148 | <attribute name="created" type="boolean" readonly="yes">
|
---|
7149 | <desc>
|
---|
7150 |
|
---|
7151 | Whether the virual disk image is created or not. For newly created
|
---|
7152 | hard disk objects or after a successful invocation of
|
---|
7153 | <link to="#deleteImage()"/>, this value is <tt>false</tt> until
|
---|
7154 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
|
---|
7155 | is called.
|
---|
7156 |
|
---|
7157 | </desc>
|
---|
7158 | </attribute>
|
---|
7159 |
|
---|
7160 | <method name="createDynamicImage">
|
---|
7161 |
|
---|
7162 | <desc>
|
---|
7163 |
|
---|
7164 | Starts creating a dymically expanding hard disk image in the
|
---|
7165 | background. The previous image associated with this object, if
|
---|
7166 | any, must be deleted using <link to="#deleteImage"/>, otherwise
|
---|
7167 | the operation will fail.
|
---|
7168 |
|
---|
7169 | <note>
|
---|
7170 | After the returned progress object reports that the
|
---|
7171 | operation is complete, this hard disk object can be
|
---|
7172 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7173 | this VirtualBox installation.
|
---|
7174 | </note>
|
---|
7175 |
|
---|
7176 | </desc>
|
---|
7177 |
|
---|
7178 | <param name="size" type="unsigned long long" dir="in">
|
---|
7179 | <desc>Maximum logical size of the hard disk in megabytes.</desc>
|
---|
7180 | </param>
|
---|
7181 | <param name="progress" type="IProgress" dir="return">
|
---|
7182 | <desc>Progress object to track the operation completion.</desc>
|
---|
7183 | </param>
|
---|
7184 |
|
---|
7185 | </method>
|
---|
7186 |
|
---|
7187 | <method name="createFixedImage">
|
---|
7188 | <desc>
|
---|
7189 |
|
---|
7190 | Starts creating a fixed-size hard disk image in the background. The
|
---|
7191 | previous image, if any, must be deleted using
|
---|
7192 | <link to="#deleteImage"/>, otherwise the operation will fail.
|
---|
7193 |
|
---|
7194 | <note>
|
---|
7195 | After the returned progress object reports that the
|
---|
7196 | operation is complete, this hard disk object can be
|
---|
7197 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7198 | this VirtualBox installation.
|
---|
7199 | </note>
|
---|
7200 |
|
---|
7201 | </desc>
|
---|
7202 |
|
---|
7203 | <param name="size" type="unsigned long long" dir="in">
|
---|
7204 | <desc>Logical size of the hard disk in megabytes.</desc>
|
---|
7205 | </param>
|
---|
7206 | <param name="progress" type="IProgress" dir="return">
|
---|
7207 | <desc>Progress object to track the operation completion.</desc>
|
---|
7208 | </param>
|
---|
7209 |
|
---|
7210 | </method>
|
---|
7211 |
|
---|
7212 | <method name="deleteImage">
|
---|
7213 | <desc>
|
---|
7214 |
|
---|
7215 | Deletes the existing hard disk image. The hard disk must not be
|
---|
7216 | registered within this VirtualBox installation, otherwise the
|
---|
7217 | operation will fail.
|
---|
7218 |
|
---|
7219 | <note>
|
---|
7220 | After this operation succeeds, it will be impossible to register the
|
---|
7221 | hard disk until the image file is created again.
|
---|
7222 | </note>
|
---|
7223 |
|
---|
7224 | <note>
|
---|
7225 | This operation is valid only for non-differencing hard disks, after
|
---|
7226 | they are unregistered using
|
---|
7227 | <link to="IVirtualBox::unregisterHardDisk()"/>.
|
---|
7228 | </note>
|
---|
7229 |
|
---|
7230 | </desc>
|
---|
7231 | </method>
|
---|
7232 |
|
---|
7233 | </interface>
|
---|
7234 |
|
---|
7235 | <!--
|
---|
7236 | // IVHDImage
|
---|
7237 | /////////////////////////////////////////////////////////////////////////
|
---|
7238 | -->
|
---|
7239 |
|
---|
7240 | <interface
|
---|
7241 | name="IVHDImage" extends="$unknown"
|
---|
7242 | uuid="163b88c3-7552-424a-8205-daf17a004747"
|
---|
7243 | wsmap="managed"
|
---|
7244 | >
|
---|
7245 | <desc>
|
---|
7246 |
|
---|
7247 | The IVHDImage interface represents <link to="IHardDisk">virtual hard
|
---|
7248 | disks</link> that use Virtual PC Virtual Machine Disk image files to store
|
---|
7249 | hard disk data.
|
---|
7250 |
|
---|
7251 | Hard disks using VHD images can be either opened using
|
---|
7252 | <link to="IVirtualBox::openHardDisk()"/> or created from
|
---|
7253 | scratch using <link to="IVirtualBox::createHardDisk()"/>.
|
---|
7254 |
|
---|
7255 | Objects that support this interface also support the
|
---|
7256 | <link to="IHardDisk"/> interface.
|
---|
7257 |
|
---|
7258 | When a new hard disk object is created from scatch, an image file for it
|
---|
7259 | is not automatically created. To do it, you need to specify a
|
---|
7260 | valid <link to="#filePath">file path</link>, and call
|
---|
7261 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>.
|
---|
7262 | When it is done, the hard disk object can be registered by calling
|
---|
7263 | <link to="IVirtualBox::registerHardDisk()"/> and then
|
---|
7264 | <link to="IMachine::attachHardDisk()">attached</link> to
|
---|
7265 | virtual machines.
|
---|
7266 |
|
---|
7267 | The <link to="IHardDisk::description">description</link>
|
---|
7268 | of the VHD hard disk is stored in the VirtualBox
|
---|
7269 | configuration file, so it can be changed (at appropriate
|
---|
7270 | times) even when
|
---|
7271 | <link to="IHardDisk::accessible">accessible</link> returns
|
---|
7272 | <tt>false</tt>. However, the hard disk must not be
|
---|
7273 | attached to a running virtual machine.
|
---|
7274 |
|
---|
7275 | <note>
|
---|
7276 | In the current imlementation, the type of all VHD hard disks
|
---|
7277 | is <link to="HardDiskType::Writethrough">Writethrough</link> and cannot
|
---|
7278 | be changed.
|
---|
7279 | </note>
|
---|
7280 |
|
---|
7281 | </desc>
|
---|
7282 |
|
---|
7283 | <attribute name="filePath" type="wstring">
|
---|
7284 | <desc>
|
---|
7285 |
|
---|
7286 | Full file name of the VHD image of this hard disk. For
|
---|
7287 | newly created hard disk objects, this value is <tt>null</tt>.
|
---|
7288 |
|
---|
7289 | When assigning a new path, it can be absolute (full path) or relative
|
---|
7290 | to the <link to="IVirtualBox::homeFolder"> VirtualBox home
|
---|
7291 | directory</link>. If only a file name without any path is given,
|
---|
7292 | the <link to="ISystemProperties::defaultVDIFolder"> default VDI
|
---|
7293 | folder</link> will be used as a path to the image file.
|
---|
7294 |
|
---|
7295 | When reading this propery, a full path is always returned.
|
---|
7296 |
|
---|
7297 | <note>
|
---|
7298 | This property cannot be changed when <link to="#created"/>
|
---|
7299 | returns <tt>true</tt>. In this case, the specified file name can be
|
---|
7300 | absolute (full path) or relative to
|
---|
7301 | the <link to="IVirtualBox::homeFolder"> VirtualBox home
|
---|
7302 | directory</link>. If only a file name without any path is given,
|
---|
7303 | the <link to="ISystemProperties::defaultVDIFolder"> default VDI
|
---|
7304 | folder</link> will be used as a path to the image file.
|
---|
7305 | </note>
|
---|
7306 |
|
---|
7307 | </desc>
|
---|
7308 | </attribute>
|
---|
7309 |
|
---|
7310 | <attribute name="created" type="boolean" readonly="yes">
|
---|
7311 | <desc>
|
---|
7312 |
|
---|
7313 | Whether the virual disk image is created or not. For newly created
|
---|
7314 | hard disk objects or after a successful invocation of
|
---|
7315 | <link to="#deleteImage()"/>, this value is <tt>false</tt> until
|
---|
7316 | <link to="#createFixedImage()"/> or <link to="#createDynamicImage()"/>
|
---|
7317 | is called.
|
---|
7318 |
|
---|
7319 | </desc>
|
---|
7320 | </attribute>
|
---|
7321 |
|
---|
7322 | <method name="createDynamicImage">
|
---|
7323 |
|
---|
7324 | <desc>
|
---|
7325 |
|
---|
7326 | Starts creating a dymically expanding hard disk image in the
|
---|
7327 | background. The previous image associated with this object, if
|
---|
7328 | any, must be deleted using <link to="#deleteImage"/>, otherwise
|
---|
7329 | the operation will fail.
|
---|
7330 |
|
---|
7331 | <note>
|
---|
7332 | After the returned progress object reports that the
|
---|
7333 | operation is complete, this hard disk object can be
|
---|
7334 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7335 | this VirtualBox installation.
|
---|
7336 | </note>
|
---|
7337 |
|
---|
7338 | </desc>
|
---|
7339 |
|
---|
7340 | <param name="size" type="unsigned long long" dir="in">
|
---|
7341 | <desc>Maximum logical size of the hard disk in megabytes.</desc>
|
---|
7342 | </param>
|
---|
7343 | <param name="progress" type="IProgress" dir="return">
|
---|
7344 | <desc>Progress object to track the operation completion.</desc>
|
---|
7345 | </param>
|
---|
7346 |
|
---|
7347 | </method>
|
---|
7348 |
|
---|
7349 | <method name="createFixedImage">
|
---|
7350 | <desc>
|
---|
7351 |
|
---|
7352 | Starts creating a fixed-size hard disk image in the background. The
|
---|
7353 | previous image, if any, must be deleted using
|
---|
7354 | <link to="#deleteImage"/>, otherwise the operation will fail.
|
---|
7355 |
|
---|
7356 | <note>
|
---|
7357 | After the returned progress object reports that the
|
---|
7358 | operation is complete, this hard disk object can be
|
---|
7359 | <link to="IVirtualBox::registerHardDisk()">registered</link> within
|
---|
7360 | this VirtualBox installation.
|
---|
7361 | </note>
|
---|
7362 |
|
---|
7363 | </desc>
|
---|
7364 |
|
---|
7365 | <param name="size" type="unsigned long long" dir="in">
|
---|
7366 | <desc>Logical size of the hard disk in megabytes.</desc>
|
---|
7367 | </param>
|
---|
7368 | <param name="progress" type="IProgress" dir="return">
|
---|
7369 | <desc>Progress object to track the operation completion.</desc>
|
---|
7370 | </param>
|
---|
7371 |
|
---|
7372 | </method>
|
---|
7373 |
|
---|
7374 | <method name="deleteImage">
|
---|
7375 | <desc>
|
---|
7376 |
|
---|
7377 | Deletes the existing hard disk image. The hard disk must not be
|
---|
7378 | registered within this VirtualBox installation, otherwise the
|
---|
7379 | operation will fail.
|
---|
7380 |
|
---|
7381 | <note>
|
---|
7382 | After this operation succeeds, it will be impossible to register the
|
---|
7383 | hard disk until the image file is created again.
|
---|
7384 | </note>
|
---|
7385 |
|
---|
7386 | <note>
|
---|
7387 | This operation is valid only for non-differencing hard disks, after
|
---|
7388 | they are unregistered using
|
---|
7389 | <link to="IVirtualBox::unregisterHardDisk()"/>.
|
---|
7390 | </note>
|
---|
7391 |
|
---|
7392 | </desc>
|
---|
7393 | </method>
|
---|
7394 |
|
---|
7395 | </interface>
|
---|
7396 |
|
---|
7397 | <!--
|
---|
7398 | // IDVDImage
|
---|
7399 | /////////////////////////////////////////////////////////////////////////
|
---|
7400 | -->
|
---|
7401 |
|
---|
7402 | <enumerator
|
---|
7403 | name="IDVDImageEnumerator" type="IDVDImage"
|
---|
7404 | uuid="9BE77C8D-E1BE-4bf2-A67B-B4DD3D2B0F28"
|
---|
7405 | />
|
---|
7406 |
|
---|
7407 | <collection
|
---|
7408 | name="IDVDImageCollection" type="IDVDImage"
|
---|
7409 | enumerator="IDVDImageEnumerator"
|
---|
7410 | uuid="AE7053FA-ADD2-4ea4-AFCF-24D5F8DDED64"
|
---|
7411 | readonly="yes"
|
---|
7412 | >
|
---|
7413 | <method name="findByPath">
|
---|
7414 | <desc>
|
---|
7415 | Searches this collection for a DVD image with the given disk path.
|
---|
7416 | <note>
|
---|
7417 | The method returns an error if the given name does not
|
---|
7418 | correspond to any DVD image in the collection.
|
---|
7419 | </note>
|
---|
7420 | </desc>
|
---|
7421 | <param name="path" type="wstring" dir="in">
|
---|
7422 | <desc>Name of the DVD image's file system location.</desc>
|
---|
7423 | </param>
|
---|
7424 | <param name="image" type="IDVDImage" dir="return">
|
---|
7425 | <desc>Found DVD image object</desc>
|
---|
7426 | </param>
|
---|
7427 | </method>
|
---|
7428 | </collection>
|
---|
7429 |
|
---|
7430 | <interface
|
---|
7431 | name="IDVDImage" extends="$unknown"
|
---|
7432 | uuid="140FFF03-E479-4194-8562-ABC4F8171009"
|
---|
7433 | wsmap="managed"
|
---|
7434 | >
|
---|
7435 | <desc>
|
---|
7436 |
|
---|
7437 | The IDVDImage interface represents a file containing the image
|
---|
7438 | of the DVD or CD disk.
|
---|
7439 |
|
---|
7440 | <h3>Image Accessibility</h3>
|
---|
7441 |
|
---|
7442 | The <link to="#accessible"/> attribute of the image object
|
---|
7443 | defines the accessibility state of the image file. If the
|
---|
7444 | value of this attribute is <tt>false</tt> then some image
|
---|
7445 | attributes may contain invalid or outdated values (for example, the
|
---|
7446 | the image file size) until a new accessibility
|
---|
7447 | check is done that returns <tt>true</tt>.
|
---|
7448 |
|
---|
7449 | <note>
|
---|
7450 | Because of the possible slowness of the accessibility check,
|
---|
7451 | it is not implicitly performed upon the VirtualBox server startup
|
---|
7452 | (to prevent the application freeze). In partcular, this means that
|
---|
7453 | if you try to read image properties that depend on the
|
---|
7454 | accessibility state without first reading the value of the
|
---|
7455 | <link to="#accessible"/> attribute and ensuring it's value is
|
---|
7456 | <tt>true</tt>, you will get wrong (zero) values.
|
---|
7457 | </note>
|
---|
7458 |
|
---|
7459 | </desc>
|
---|
7460 | <attribute name="id" type="uuid" readonly="yes">
|
---|
7461 | <desc>UUID of the CD/DVD image.</desc>
|
---|
7462 | </attribute>
|
---|
7463 |
|
---|
7464 | <attribute name="filePath" type="wstring" readonly="yes">
|
---|
7465 | <desc>Full file name of the CD/DVD image.</desc>
|
---|
7466 | </attribute>
|
---|
7467 |
|
---|
7468 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
7469 | <desc>
|
---|
7470 |
|
---|
7471 | Whether the CD/DVD image is currently accessible or not.
|
---|
7472 | The image, for example, can be unaccessible if it is placed
|
---|
7473 | on a network share that is not available by the time
|
---|
7474 | this property is read.
|
---|
7475 |
|
---|
7476 | The accessibility check is performed automatically every time
|
---|
7477 | this attribute is read. You should keep it in mind that this check
|
---|
7478 | may be slow and can block the calling thread for a long time (for
|
---|
7479 | example, if the network share where the image is located is down).
|
---|
7480 |
|
---|
7481 | The following attributes of the image object are considered
|
---|
7482 | to be invalid when this attribute is <tt>false</tt>:
|
---|
7483 | <ul>
|
---|
7484 | <li><link to="#size"/></li>
|
---|
7485 | </ul>
|
---|
7486 |
|
---|
7487 | </desc>
|
---|
7488 | </attribute>
|
---|
7489 |
|
---|
7490 | <attribute name="size" type="unsigned long long" readonly="yes">
|
---|
7491 | <desc>Size of the ISO image in bytes.</desc>
|
---|
7492 | </attribute>
|
---|
7493 |
|
---|
7494 | </interface>
|
---|
7495 |
|
---|
7496 |
|
---|
7497 | <!--
|
---|
7498 | // IDVDDrive
|
---|
7499 | /////////////////////////////////////////////////////////////////////////
|
---|
7500 | -->
|
---|
7501 |
|
---|
7502 | <interface
|
---|
7503 | name="IDVDDrive" extends="$unknown"
|
---|
7504 | uuid="d9bd101a-8079-4fb9-bad1-31bf32482b75"
|
---|
7505 | wsmap="managed"
|
---|
7506 | >
|
---|
7507 | <desc>
|
---|
7508 | The IDVDDrive interface represents the virtual CD/DVD drive of the
|
---|
7509 | virtual machine. Used in <link to="IMachine::DVDDrive"/>.
|
---|
7510 | </desc>
|
---|
7511 | <attribute name="state" type="DriveState" readonly="yes">
|
---|
7512 | <desc>Current drive state.</desc>
|
---|
7513 | </attribute>
|
---|
7514 |
|
---|
7515 | <attribute name="passthrough" type="boolean">
|
---|
7516 | <desc>
|
---|
7517 | When a host drive is mounted and passthrough is enabled
|
---|
7518 | the guest will be able to directly send SCSI commands to
|
---|
7519 | the host drive. This enables the guest to use CD/DVD writers
|
---|
7520 | but is potentially dangerous.
|
---|
7521 | </desc>
|
---|
7522 | </attribute>
|
---|
7523 |
|
---|
7524 | <method name="mountImage">
|
---|
7525 | <desc>Mounts the specified image.</desc>
|
---|
7526 | <param name="imageId" type="uuid" dir="in"/>
|
---|
7527 | </method>
|
---|
7528 |
|
---|
7529 | <method name="captureHostDrive">
|
---|
7530 | <desc>Captures the specified host drive.</desc>
|
---|
7531 | <param name="drive" type="IHostDVDDrive" dir="in"/>
|
---|
7532 | </method>
|
---|
7533 |
|
---|
7534 | <method name="unmount">
|
---|
7535 | <desc>Unmounts the currently mounted image/device.</desc>
|
---|
7536 | </method>
|
---|
7537 |
|
---|
7538 | <method name="getImage">
|
---|
7539 | <desc>Gets the currently mounted image ID.</desc>
|
---|
7540 | <param name="image" type="IDVDImage" dir="return"/>
|
---|
7541 | </method>
|
---|
7542 |
|
---|
7543 | <method name="getHostDrive">
|
---|
7544 | <desc>Gets the currently mounted image ID.</desc>
|
---|
7545 | <param name="drive" type="IHostDVDDrive" dir="return"/>
|
---|
7546 | </method>
|
---|
7547 |
|
---|
7548 | </interface>
|
---|
7549 |
|
---|
7550 | <!--
|
---|
7551 | // IFloppyImage
|
---|
7552 | /////////////////////////////////////////////////////////////////////////
|
---|
7553 | -->
|
---|
7554 |
|
---|
7555 | <enumerator
|
---|
7556 | name="IFloppyImageEnumerator" type="IFloppyImage"
|
---|
7557 | uuid="902C4089-76B7-41f1-91E8-49A261A28A2C"
|
---|
7558 | />
|
---|
7559 |
|
---|
7560 | <collection
|
---|
7561 | name="IFloppyImageCollection" type="IFloppyImage"
|
---|
7562 | enumerator="IFloppyImageEnumerator"
|
---|
7563 | uuid="327A8928-8572-446e-AD9A-18FE30E81F3F"
|
---|
7564 | readonly="yes">
|
---|
7565 | <method name="findByPath">
|
---|
7566 | <desc>
|
---|
7567 | Searches this collection for a floppy image with the given disk path.
|
---|
7568 | <note>
|
---|
7569 | The method returns an error if the given name does not
|
---|
7570 | correspond to any floppy image in the collection.
|
---|
7571 | </note>
|
---|
7572 | </desc>
|
---|
7573 | <param name="path" type="wstring" dir="in">
|
---|
7574 | <desc>Name of the floppy image's file system location.</desc>
|
---|
7575 | </param>
|
---|
7576 | <param name="image" type="IFloppyImage" dir="return">
|
---|
7577 | <desc>Found Floppy image object</desc>
|
---|
7578 | </param>
|
---|
7579 | </method>
|
---|
7580 | </collection>
|
---|
7581 |
|
---|
7582 | <interface
|
---|
7583 | name="IFloppyImage" extends="$unknown"
|
---|
7584 | uuid="CC696755-EA98-4ffe-9DC5-C003047034AB"
|
---|
7585 | wsmap="managed"
|
---|
7586 | >
|
---|
7587 | <desc>
|
---|
7588 |
|
---|
7589 | The IFloppyImage interface represents a file containing the image
|
---|
7590 | of a floppy disk.
|
---|
7591 |
|
---|
7592 | <h3>Image Accessibility</h3>
|
---|
7593 |
|
---|
7594 | The <link to="#accessible"/> attribute of the image object
|
---|
7595 | defines the accessibility state of the image file. If the
|
---|
7596 | value of this attribute is <tt>false</tt> then some image
|
---|
7597 | attributes may contain invalid or outdated values (for example, the
|
---|
7598 | the image file size) until a new accessibility
|
---|
7599 | check is done that returns <tt>true</tt>.
|
---|
7600 |
|
---|
7601 | <note>
|
---|
7602 | Because of the possible slowness of the accessibility check,
|
---|
7603 | it is not implicitly performed upon the VirtualBox server startup
|
---|
7604 | (to prevent the application freeze). In partcular, this means that
|
---|
7605 | if you try to read image properties that depend on the
|
---|
7606 | accessibility state without first reading the value of the
|
---|
7607 | <link to="#accessible"/> attribute and ensuring it's value is
|
---|
7608 | <tt>true</tt>, you will get wrong (zero) values.
|
---|
7609 | </note>
|
---|
7610 |
|
---|
7611 | </desc>
|
---|
7612 | <attribute name="id" type="uuid" readonly="yes">
|
---|
7613 | <desc>UUID of the floppy image.</desc>
|
---|
7614 | </attribute>
|
---|
7615 |
|
---|
7616 | <attribute name="filePath" type="wstring" readonly="yes">
|
---|
7617 | <desc>Full file name of the floppy image.</desc>
|
---|
7618 | </attribute>
|
---|
7619 |
|
---|
7620 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
7621 | <desc>
|
---|
7622 |
|
---|
7623 | Whether the floppy image is currently accessible or not.
|
---|
7624 | The image, for example, can be unaccessible if it is placed
|
---|
7625 | on a network share that is not available by the time
|
---|
7626 | this property is read.
|
---|
7627 |
|
---|
7628 | The accessibility check is performed automatically every time
|
---|
7629 | this attribute is read. You should keep it in mind that this check
|
---|
7630 | may be slow and can block the calling thread for a long time (for
|
---|
7631 | example, if the network share where the image is located is down).
|
---|
7632 |
|
---|
7633 | The following attributes of the image object are considered
|
---|
7634 | to be invalid when this attribute is <tt>false</tt>:
|
---|
7635 | <ul>
|
---|
7636 | <li><link to="#size"/></li>
|
---|
7637 | </ul>
|
---|
7638 |
|
---|
7639 | </desc>
|
---|
7640 | </attribute>
|
---|
7641 |
|
---|
7642 | <attribute name="size" type="unsigned long" readonly="yes">
|
---|
7643 | <desc>Size of the floppy image in bytes.</desc>
|
---|
7644 | </attribute>
|
---|
7645 |
|
---|
7646 | </interface>
|
---|
7647 |
|
---|
7648 |
|
---|
7649 | <!--
|
---|
7650 | // IFloppyDrive
|
---|
7651 | /////////////////////////////////////////////////////////////////////////
|
---|
7652 | -->
|
---|
7653 |
|
---|
7654 | <interface
|
---|
7655 | name="IFloppyDrive" extends="$unknown"
|
---|
7656 | uuid="E9318F71-78D2-4b00-863C-B7CB0030A2D9"
|
---|
7657 | wsmap="managed"
|
---|
7658 | >
|
---|
7659 | <desc>
|
---|
7660 | The IFloppyDrive interface represents the virtual floppy drive of the
|
---|
7661 | virtual machine. Used in <link to="IMachine::FloppyDrive" />.
|
---|
7662 | </desc>
|
---|
7663 |
|
---|
7664 | <attribute name="enabled" type="boolean">
|
---|
7665 | <desc>
|
---|
7666 | Flag whether the floppy drive is enabled. If it is disabled,
|
---|
7667 | the floppy drive will not be reported to the guest.
|
---|
7668 | </desc>
|
---|
7669 | </attribute>
|
---|
7670 |
|
---|
7671 | <attribute name="state" type="DriveState" readonly="yes">
|
---|
7672 | <desc>Current drive state.</desc>
|
---|
7673 | </attribute>
|
---|
7674 |
|
---|
7675 | <method name="mountImage">
|
---|
7676 | <desc>Mounts the specified image.</desc>
|
---|
7677 | <param name="imageId" type="uuid" dir="in"/>
|
---|
7678 | </method>
|
---|
7679 |
|
---|
7680 | <method name="captureHostDrive">
|
---|
7681 | <desc>Captures the specified host drive.</desc>
|
---|
7682 | <param name="drive" type="IHostFloppyDrive" dir="in"/>
|
---|
7683 | </method>
|
---|
7684 |
|
---|
7685 | <method name="unmount">
|
---|
7686 | <desc>Unmounts the currently mounted image/device.</desc>
|
---|
7687 | </method>
|
---|
7688 |
|
---|
7689 | <method name="getImage">
|
---|
7690 | <desc>Gets the currently mounted image ID.</desc>
|
---|
7691 | <param name="image" type="IFloppyImage" dir="return"/>
|
---|
7692 | </method>
|
---|
7693 |
|
---|
7694 | <method name="getHostDrive">
|
---|
7695 | <desc>Gets the currently mounted image ID.</desc>
|
---|
7696 | <param name="drive" type="IHostFloppyDrive" dir="return"/>
|
---|
7697 | </method>
|
---|
7698 |
|
---|
7699 | </interface>
|
---|
7700 |
|
---|
7701 |
|
---|
7702 | <!--
|
---|
7703 | // IKeyboard
|
---|
7704 | /////////////////////////////////////////////////////////////////////////
|
---|
7705 | -->
|
---|
7706 |
|
---|
7707 | <interface
|
---|
7708 | name="IKeyboard" extends="$unknown"
|
---|
7709 | uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
|
---|
7710 | wsmap="managed"
|
---|
7711 | >
|
---|
7712 | <desc>
|
---|
7713 | The IKeyboard interface represents the virtual machine's keyboard. Used
|
---|
7714 | in <link to="IConsole::keyboard"/>.
|
---|
7715 |
|
---|
7716 | Through this interface, the virtual machine's virtual keyboard can be controlled. One
|
---|
7717 | can send keystrokes to the virtual machine and send the Ctrl-Alt-Del sequence to it.
|
---|
7718 | </desc>
|
---|
7719 | <method name="putScancode">
|
---|
7720 | <desc>Sends a scancode to the keyboard.</desc>
|
---|
7721 | <param name="scancode" type="long" dir="in"/>
|
---|
7722 | </method>
|
---|
7723 |
|
---|
7724 | <method name="putScancodes">
|
---|
7725 | <desc>Sends an array of scancode to the keyboard.</desc>
|
---|
7726 | <param name="scancodes" type="long" dir="in" safearray="yes"/>
|
---|
7727 | <param name="codesStored" type="unsigned long" dir="return"/>
|
---|
7728 | </method>
|
---|
7729 |
|
---|
7730 | <method name="putCAD">
|
---|
7731 | <desc>Sends the Ctrl-Alt-Del sequence to the keyboard.</desc>
|
---|
7732 | </method>
|
---|
7733 |
|
---|
7734 | </interface>
|
---|
7735 |
|
---|
7736 |
|
---|
7737 | <!--
|
---|
7738 | // IMouse
|
---|
7739 | /////////////////////////////////////////////////////////////////////////
|
---|
7740 | -->
|
---|
7741 |
|
---|
7742 | <enum
|
---|
7743 | name="MouseButtonState"
|
---|
7744 | uuid="03131722-2EC5-4173-9794-0DACA46673EF"
|
---|
7745 | >
|
---|
7746 | <desc>
|
---|
7747 | Mouse button state.
|
---|
7748 | </desc>
|
---|
7749 |
|
---|
7750 | <const name="LeftButton" value="0x01"/>
|
---|
7751 | <const name="RightButton" value="0x02"/>
|
---|
7752 | <const name="MiddleButton" value="0x04"/>
|
---|
7753 | <const name="WheelUp" value="0x08"/>
|
---|
7754 | <const name="WheelDown" value="0x10"/>
|
---|
7755 | <const name="MouseStateMask" value="0x1F"/>
|
---|
7756 | </enum>
|
---|
7757 |
|
---|
7758 | <interface
|
---|
7759 | name="IMouse" extends="$unknown"
|
---|
7760 | uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
|
---|
7761 | wsmap="managed"
|
---|
7762 | >
|
---|
7763 | <desc>
|
---|
7764 | The IMouse interface represents the virtual machine's mouse. Used in
|
---|
7765 | <link to="IConsole::mouse"/>.
|
---|
7766 |
|
---|
7767 | Through this interface, the virtual machine's virtual mouse can be
|
---|
7768 | controlled.
|
---|
7769 | </desc>
|
---|
7770 |
|
---|
7771 | <attribute name="absoluteSupported" type="boolean" readonly="yes">
|
---|
7772 | <desc>
|
---|
7773 | Whether the guest OS supports absolute mouse pointer positioning
|
---|
7774 | or not.
|
---|
7775 | <note>
|
---|
7776 | VirtualBox Guest Tools need to be installed to the guest OS
|
---|
7777 | in order to enable absolute mouse positioning support.
|
---|
7778 | You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
|
---|
7779 | callback to be instantly informed about changes of this attribute
|
---|
7780 | during virtual machine execution.
|
---|
7781 | </note>
|
---|
7782 | <see><link to="#putMouseEventAbsolute"/></see>
|
---|
7783 | </desc>
|
---|
7784 | </attribute>
|
---|
7785 |
|
---|
7786 | <method name="putMouseEvent">
|
---|
7787 | <desc>
|
---|
7788 | Initiates a mouse event using relative pointer movements
|
---|
7789 | along x and y axis.
|
---|
7790 | </desc>
|
---|
7791 |
|
---|
7792 | <param name="dx" type="long" dir="in">
|
---|
7793 | <desc>
|
---|
7794 | Amout of pixels the mouse should move to the right.
|
---|
7795 | Negative values move the mouse to the left.
|
---|
7796 | </desc>
|
---|
7797 | </param>
|
---|
7798 | <param name="dy" type="long" dir="in">
|
---|
7799 | <desc>
|
---|
7800 | Amout of pixels the mouse should move downwards.
|
---|
7801 | Negative values move the mouse upwards.
|
---|
7802 | </desc>
|
---|
7803 | </param>
|
---|
7804 | <param name="dz" type="long" dir="in">
|
---|
7805 | <desc>
|
---|
7806 | Amount of mouse wheel moves.
|
---|
7807 | Positive values describe clockwize wheel rotations,
|
---|
7808 | negative values describe counterclockwise rotations.
|
---|
7809 | </desc>
|
---|
7810 | </param>
|
---|
7811 | <param name="buttonState" type="long" dir="in">
|
---|
7812 | <desc>
|
---|
7813 | The current state of mouse buttons. Every bit represents
|
---|
7814 | a mouse button as follows:
|
---|
7815 | <table>
|
---|
7816 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
7817 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
7818 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
7819 | </table>
|
---|
7820 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
7821 | otherwise it is released.
|
---|
7822 | </desc>
|
---|
7823 | </param>
|
---|
7824 | </method>
|
---|
7825 |
|
---|
7826 | <method name="putMouseEventAbsolute">
|
---|
7827 | <desc>
|
---|
7828 | Positions the mouse pointer using absolute x and y coordinates.
|
---|
7829 | These coordinates are expressed in pixels and
|
---|
7830 | start from <tt>[1,1]</tt> which corresponds to the top left
|
---|
7831 | corner of the virtual display.
|
---|
7832 |
|
---|
7833 | <note>
|
---|
7834 | This method will have effect only if absolute mouse
|
---|
7835 | positioning is supported by the guest OS.
|
---|
7836 | </note>
|
---|
7837 |
|
---|
7838 | <see><link to="#absoluteSupported"/></see>
|
---|
7839 | </desc>
|
---|
7840 |
|
---|
7841 | <param name="x" type="long" dir="in">
|
---|
7842 | <desc>
|
---|
7843 | X coordinate of the pointer in pixels, starting from <tt>1</tt>.
|
---|
7844 | </desc>
|
---|
7845 | </param>
|
---|
7846 | <param name="y" type="long" dir="in">
|
---|
7847 | <desc>
|
---|
7848 | Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
|
---|
7849 | </desc>
|
---|
7850 | </param>
|
---|
7851 | <param name="dz" type="long" dir="in">
|
---|
7852 | <desc>
|
---|
7853 | Amout of mouse wheel moves.
|
---|
7854 | Positive values describe clockwize wheel rotations,
|
---|
7855 | negative values describe counterclockwise rotations.
|
---|
7856 | </desc>
|
---|
7857 | </param>
|
---|
7858 | <param name="buttonState" type="long" dir="in">
|
---|
7859 | <desc>
|
---|
7860 | The current state of mouse buttons. Every bit represents
|
---|
7861 | a mouse button as follows:
|
---|
7862 | <table>
|
---|
7863 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
7864 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
7865 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
7866 | </table>
|
---|
7867 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
7868 | otherwise it is released.
|
---|
7869 | </desc>
|
---|
7870 | </param>
|
---|
7871 | </method>
|
---|
7872 |
|
---|
7873 | </interface>
|
---|
7874 |
|
---|
7875 | <!--
|
---|
7876 | // IDisplay
|
---|
7877 | /////////////////////////////////////////////////////////////////////////
|
---|
7878 | -->
|
---|
7879 |
|
---|
7880 | <enum
|
---|
7881 | name="FramebufferAccelerationOperation"
|
---|
7882 | uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
|
---|
7883 | >
|
---|
7884 | <desc>
|
---|
7885 | Framebuffer acceleration operation.
|
---|
7886 | </desc>
|
---|
7887 |
|
---|
7888 | <const name="SolidFillAcceleration" value="1"/>
|
---|
7889 | <const name="ScreenCopyAcceleration" value="2"/>
|
---|
7890 | </enum>
|
---|
7891 |
|
---|
7892 | <enum
|
---|
7893 | name="FramebufferPixelFormat"
|
---|
7894 | uuid="6b27d1fc-4f2c-4e9c-a166-01d06540305d"
|
---|
7895 | >
|
---|
7896 | <desc>
|
---|
7897 | Format of the video memory buffer. Constants represented by this enum can
|
---|
7898 | be used to test for particular values of <link
|
---|
7899 | to="IFramebuffer::pixelFormat"/>. See also <link
|
---|
7900 | to="IFramebuffer::requestResize()"/>.
|
---|
7901 |
|
---|
7902 | See also www.fourcc.org for more informantion about FOURCC pixel formats.
|
---|
7903 | </desc>
|
---|
7904 |
|
---|
7905 | <const name="Opaque" value="0xFFFFFFFF">
|
---|
7906 | <desc>
|
---|
7907 | Unknown buffer format. The user may not assume any particular
|
---|
7908 | format of the buffer.
|
---|
7909 | </desc>
|
---|
7910 | </const>
|
---|
7911 | <const name="FOURCC_RGB" value="0x32424752">
|
---|
7912 | <desc>
|
---|
7913 | Basic RGB format. <link to="IFramebuffer::bitsPerPixel"/> determines
|
---|
7914 | the bit layout.
|
---|
7915 | </desc>
|
---|
7916 | </const>
|
---|
7917 | </enum>
|
---|
7918 |
|
---|
7919 | <interface
|
---|
7920 | name="IFramebuffer" extends="$unknown"
|
---|
7921 | uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
|
---|
7922 | wsmap="suppress"
|
---|
7923 | >
|
---|
7924 | <attribute name="address" type="octet" mod="ptr" readonly="yes">
|
---|
7925 | <desc>Address of the start byte of the framebuffer.</desc>
|
---|
7926 | </attribute>
|
---|
7927 |
|
---|
7928 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
7929 | <desc>Framebuffer width, in pixels.</desc>
|
---|
7930 | </attribute>
|
---|
7931 |
|
---|
7932 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
7933 | <desc>Framebuffer height, in pixels.</desc>
|
---|
7934 | </attribute>
|
---|
7935 |
|
---|
7936 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
7937 | <desc>
|
---|
7938 | Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
|
---|
7939 | to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, valid values
|
---|
7940 | are: 8, 15, 16, 24 and 32.
|
---|
7941 | </desc>
|
---|
7942 | </attribute>
|
---|
7943 |
|
---|
7944 | <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
|
---|
7945 | <desc>
|
---|
7946 | Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
|
---|
7947 | to="FramebufferPixelFormat::FOURCC_RGB">FOURCC_RGB</link>, the
|
---|
7948 | size of the scan line must be aligned to 32 bits.
|
---|
7949 | </desc>
|
---|
7950 | </attribute>
|
---|
7951 |
|
---|
7952 | <attribute name="pixelFormat" type="unsigned long" readonly="yes">
|
---|
7953 | <desc>
|
---|
7954 | Framebuffer pixel format. It's either one of the values defined by <link
|
---|
7955 | to="FramebufferPixelFormat"/> or a raw FOURCC code.
|
---|
7956 | <note>
|
---|
7957 | This attribute must never return <link
|
---|
7958 | to="PixelFormat::Opaque"/> -- the format of the buffer
|
---|
7959 | <link to="#address"/> points to must be always known.
|
---|
7960 | </note>
|
---|
7961 | </desc>
|
---|
7962 | </attribute>
|
---|
7963 |
|
---|
7964 | <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
|
---|
7965 | <desc>
|
---|
7966 | Defines whether this framebuffer uses the virtual video card's memory
|
---|
7967 | buffer (guest VRAM) directly or not. See <link
|
---|
7968 | to="IFramebuffer::requestResize()"/> for more information.
|
---|
7969 | </desc>
|
---|
7970 | </attribute>
|
---|
7971 |
|
---|
7972 | <attribute name="heightReduction" type="unsigned long" readonly="yes">
|
---|
7973 | <desc>
|
---|
7974 | Hint from the framebuffer about how much of the standard
|
---|
7975 | screen height it wants to use for itself. This information is
|
---|
7976 | exposed to the guest through the VESA BIOS and VMMDev interface
|
---|
7977 | so that it can use it for determining its video mode table. It
|
---|
7978 | is not guaranteed that the guest respects the value.
|
---|
7979 | </desc>
|
---|
7980 | </attribute>
|
---|
7981 |
|
---|
7982 | <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
|
---|
7983 | <desc>
|
---|
7984 | An alpha-blended overlay which is superposed over the framebuffer.
|
---|
7985 | The initial purpose is to allow the display of icons providing
|
---|
7986 | information about the VM state, including disk activity, in front
|
---|
7987 | ends which do not have other means of doing that. The overlay is
|
---|
7988 | designed to controlled exclusively by IDisplay. It has no locking
|
---|
7989 | of its own, and any changes made to it are not guaranteed to be
|
---|
7990 | visible until the affected portion of IFramebuffer is updated. The
|
---|
7991 | overlay can be created lazily the first time it is requested. This
|
---|
7992 | attribute can also return NULL to signal that the overlay is not
|
---|
7993 | implemented.
|
---|
7994 | </desc>
|
---|
7995 | </attribute>
|
---|
7996 |
|
---|
7997 | <method name="lock">
|
---|
7998 | <desc>
|
---|
7999 | Locks the framebuffer.
|
---|
8000 | Gets called by the IDisplay object where this framebuffer is
|
---|
8001 | bound to.
|
---|
8002 | </desc>
|
---|
8003 | </method>
|
---|
8004 |
|
---|
8005 | <method name="unlock">
|
---|
8006 | <desc>
|
---|
8007 | Unlocks the framebuffer.
|
---|
8008 | Gets called by the IDisplay object where this framebuffer is
|
---|
8009 | bound to.
|
---|
8010 | </desc>
|
---|
8011 | </method>
|
---|
8012 |
|
---|
8013 | <method name="notifyUpdate">
|
---|
8014 | <desc>
|
---|
8015 | Informs about an update.
|
---|
8016 | Gets called by the display object where this buffer is
|
---|
8017 | registered.
|
---|
8018 | </desc>
|
---|
8019 | <param name="x" type="unsigned long" dir="in"/>
|
---|
8020 | <param name="y" type="unsigned long" dir="in"/>
|
---|
8021 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8022 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8023 | <param name="finished" type="boolean" dir="return"/>
|
---|
8024 | </method>
|
---|
8025 |
|
---|
8026 | <method name="requestResize">
|
---|
8027 | <desc>
|
---|
8028 | Requests a size and pixel format change.
|
---|
8029 |
|
---|
8030 | There are two modes of working with the video buffer of the virtual
|
---|
8031 | machine. The <i>indirect</i> mode implies that the IFramebuffer
|
---|
8032 | implementation allocates a memory buffer for the requested display mode
|
---|
8033 | and provides it to the virtual machine. In <i>direct</i> mode, the
|
---|
8034 | IFramebuffer implementation uses the memory buffer allocated and owned
|
---|
8035 | by the virtual machine. This buffer represents the video memory of the
|
---|
8036 | emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
|
---|
8037 | usually faster because the implementation gets a raw pointer to the
|
---|
8038 | guest VRAM buffer which it can directly use for visualising the contents
|
---|
8039 | of the virtual display, as opposed to the indirect mode where the
|
---|
8040 | contents of guest VRAM are copied to the memory buffer provided by
|
---|
8041 | the implementation every time a display update occurs.
|
---|
8042 |
|
---|
8043 | It is important to note that the direct mode is really fast only when
|
---|
8044 | the implementation uses the given guest VRAM buffer directly, for
|
---|
8045 | example, by blitting it to the window representing the virtual machine's
|
---|
8046 | display, which saves at least one copy operation comparing to the
|
---|
8047 | indirect mode. However, using the guest VRAM buffer directly is not
|
---|
8048 | always possible: the format and the color depth of this buffer may be
|
---|
8049 | not supported by the target window, or it may be unknown (opaque) as in
|
---|
8050 | case of text or non-linear multi-plane VGA video modes. In this case,
|
---|
8051 | the indirect mode (that is always available) should be used as a
|
---|
8052 | fallback: when the guest VRAM contents are copied to the
|
---|
8053 | implementation-provided memory buffer, color and format conversion is
|
---|
8054 | done authomatically by the underlying code.
|
---|
8055 |
|
---|
8056 | The @a pixelFormat parameter defines whether the direct mode is
|
---|
8057 | available or not. If @a pixelFormat is <link
|
---|
8058 | to="PixelFormat::Opaque"/> then direct access to the guest
|
---|
8059 | VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and @a
|
---|
8060 | bytesPerLine parameters must be ignored and the implementation must use
|
---|
8061 | the indirect mode (where it provides its own buffer in one of the
|
---|
8062 | supported formats). In all other cases, @a pixelFormat together with @a
|
---|
8063 | bitsPerPixel and @a bytesPerLine define the format of the video memory
|
---|
8064 | buffer pointed to by the @a VRAM parameter and the implementation is
|
---|
8065 | free to choose which mode to use. To indicate that this framebuffer uses
|
---|
8066 | the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
|
---|
8067 | attribute must return <tt>true</tt> and <link to="#address"/> must
|
---|
8068 | return exactly the same address that is passed in the @a VRAM parameter
|
---|
8069 | of this method; otherwise it is assumed that the indirect strategy is
|
---|
8070 | chosen.
|
---|
8071 |
|
---|
8072 | The @a width and @a height parameters represent the size of the
|
---|
8073 | requested display mode in both modes. In case of indirect mode, the
|
---|
8074 | provided memory buffer should be big enough to store data of the given
|
---|
8075 | display mode. In case of direct mode, it is guaranteed that the given @a
|
---|
8076 | VRAM buffer contains enough space to represent the display mode of the
|
---|
8077 | given size. Note that this framebuffer's <link to="#width"/> and <link
|
---|
8078 | to="#height"/> attributes must return exactly the same values as
|
---|
8079 | passed to this method after the resize is completed (see below).
|
---|
8080 |
|
---|
8081 | The @a finished output parameter determines if the implementation has
|
---|
8082 | finished resizing the framebuffer or not. If, for some reason, the
|
---|
8083 | resize cannot be finished immediately during this call, @a finished
|
---|
8084 | must be set to @c false, and the implementation must call
|
---|
8085 | <link to="IDisplay::resizeCompleted()"/> after it has returned from
|
---|
8086 | this method as soon as possible. If @a finished is @c false, the
|
---|
8087 | machine will not call any framebuffer methods until
|
---|
8088 | <link to="IDisplay::resizeCompleted()"/> is called.
|
---|
8089 |
|
---|
8090 | Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
|
---|
8091 | <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
|
---|
8092 | this framebuffer must return exactly the same values as specified in the
|
---|
8093 | parameters of this method, after the resize is completed. If the
|
---|
8094 | indirect mode is chosen, these attributes must return values describing
|
---|
8095 | the format of the implementation's own memory buffer <link
|
---|
8096 | to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
|
---|
8097 | value must always correlate with <link to="#pixelFormat"/>. Note that
|
---|
8098 | the <link to="#pixelFormat"/> attribute must never return <link
|
---|
8099 | to="PixelFormat::Opaque"/> regardless of the selected mode.
|
---|
8100 |
|
---|
8101 | <note>
|
---|
8102 | This method is called by the IDisplay object under the
|
---|
8103 | <link to="#lock()"/> provided by this IFramebuffer
|
---|
8104 | implementation. If this method returns @c false in @a finished, then
|
---|
8105 | this lock is not released until
|
---|
8106 | <link to="IDisplay::resizeCompleted()"/> is called.
|
---|
8107 | </note>
|
---|
8108 | </desc>
|
---|
8109 | <param name="screenId" type="unsigned long" dir="in">
|
---|
8110 | <desc>
|
---|
8111 | Logical screen number. Must be used in the corresponding call to
|
---|
8112 | <link to="IDisplay::resizeCompleted()"/> if this call is made.
|
---|
8113 | </desc>
|
---|
8114 | </param>
|
---|
8115 | <param name="pixelFormat" type="unsigned long" dir="in">
|
---|
8116 | <desc>
|
---|
8117 | Pixel format of the memory buffer pointed to by @a VRAM.
|
---|
8118 | See also <link to="FramebufferPixelFormat"/>.
|
---|
8119 | </desc>
|
---|
8120 | </param>
|
---|
8121 | <param name="VRAM" type="octet" mod="ptr" dir="in">
|
---|
8122 | <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
|
---|
8123 | </param>
|
---|
8124 | <param name="bitsPerPixel" type="unsigned long" dir="in">
|
---|
8125 | <desc>Color depth, bits per pixel.</desc>
|
---|
8126 | </param>
|
---|
8127 | <param name="bytesPerLine" type="unsigned long" dir="in">
|
---|
8128 | <desc>Size of one scan line, in bytes.</desc>
|
---|
8129 | </param>
|
---|
8130 | <param name="width" type="unsigned long" dir="in">
|
---|
8131 | <desc>Width of the guest display, in pixels.</desc>
|
---|
8132 | </param>
|
---|
8133 | <param name="height" type="unsigned long" dir="in">
|
---|
8134 | <desc>Height of the guest display, in pixels.</desc>
|
---|
8135 | </param>
|
---|
8136 | <param name="finished" type="boolean" dir="return">
|
---|
8137 | <desc>
|
---|
8138 | Can the VM start using the new framebuffer immediately
|
---|
8139 | after this method returns or it should wait for
|
---|
8140 | <link to="IDisplay::resizeCompleted()"/>.
|
---|
8141 | </desc>
|
---|
8142 | </param>
|
---|
8143 | </method>
|
---|
8144 |
|
---|
8145 | <method name="operationSupported">
|
---|
8146 | <desc>
|
---|
8147 | Returns whether the given acceleration operation is supported
|
---|
8148 | by the IFramebuffer implementation. If not, the display object
|
---|
8149 | will not attempt to call the corresponding IFramebuffer entry
|
---|
8150 | point. Even if an operation is indicated to supported, the
|
---|
8151 | IFramebuffer implementation always has the option to return non
|
---|
8152 | supported from the corresponding acceleration method in which
|
---|
8153 | case the operation will be performed by the display engine. This
|
---|
8154 | allows for reduced IFramebuffer implementation complexity where
|
---|
8155 | only common cases are handled.
|
---|
8156 | </desc>
|
---|
8157 | <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
|
---|
8158 | <param name="supported" type="boolean" dir="return"/>
|
---|
8159 | </method>
|
---|
8160 |
|
---|
8161 | <method name="videoModeSupported">
|
---|
8162 | <desc>
|
---|
8163 | Returns whether the framebuffer implementation is willing to
|
---|
8164 | support a given video mode. In case it is not able to render
|
---|
8165 | the video mode (or for some reason not willing), it should
|
---|
8166 | return false. Usually this method is called when the guest
|
---|
8167 | asks the VMM device whether a given video mode is supported
|
---|
8168 | so the information returned is directly exposed to the guest.
|
---|
8169 | It is important that this method returns very quickly.
|
---|
8170 | </desc>
|
---|
8171 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8172 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8173 | <param name="bpp" type="unsigned long" dir="in"/>
|
---|
8174 | <param name="supported" type="boolean" dir="return"/>
|
---|
8175 | </method>
|
---|
8176 |
|
---|
8177 | <method name="solidFill">
|
---|
8178 | <desc>
|
---|
8179 | Fills the specified rectangle on screen with a solid color.
|
---|
8180 | </desc>
|
---|
8181 | <param name="x" type="unsigned long" dir="in"/>
|
---|
8182 | <param name="y" type="unsigned long" dir="in"/>
|
---|
8183 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8184 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8185 | <param name="color" type="unsigned long" dir="in"/>
|
---|
8186 | <param name="handled" type="boolean" dir="return"/>
|
---|
8187 | </method>
|
---|
8188 |
|
---|
8189 | <method name="copyScreenBits">
|
---|
8190 | <desc>
|
---|
8191 | Copies specified rectangle on the screen.
|
---|
8192 | </desc>
|
---|
8193 | <param name="xDst" type="unsigned long" dir="in"/>
|
---|
8194 | <param name="yDst" type="unsigned long" dir="in"/>
|
---|
8195 | <param name="xSrc" type="unsigned long" dir="in"/>
|
---|
8196 | <param name="ySrc" type="unsigned long" dir="in"/>
|
---|
8197 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8198 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8199 | <param name="handled" type="boolean" dir="return"/>
|
---|
8200 | </method>
|
---|
8201 |
|
---|
8202 | <method name="getVisibleRegion">
|
---|
8203 | <desc>
|
---|
8204 | Returns the visible region of this framebuffer.
|
---|
8205 |
|
---|
8206 | If the @a rectangles parameter is <tt>NULL</tt> then the value of the
|
---|
8207 | @a count parameter is ignored and the number of elements necessary to
|
---|
8208 | describe the current visible region is returned in @a countCopied.
|
---|
8209 |
|
---|
8210 | If @a rectangles is not <tt>NULL</tt> but @a count is less
|
---|
8211 | than the required number of elements to store region data, the method
|
---|
8212 | will report a failure. If @a count is equal or greater than the
|
---|
8213 | required number of elements, then the actual number of elements copied
|
---|
8214 | to the provided array will be returned in @a countCopied.
|
---|
8215 |
|
---|
8216 | <note>
|
---|
8217 | The address of the provided array must be in the process space of
|
---|
8218 | this IFramebuffer object.
|
---|
8219 | </note>
|
---|
8220 | </desc>
|
---|
8221 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
8222 | <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
|
---|
8223 | </param>
|
---|
8224 | <param name="count" type="unsigned long" dir="in">
|
---|
8225 | <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
|
---|
8226 | </param>
|
---|
8227 | <param name="countCopied" type="unsigned long" dir="return">
|
---|
8228 | <desc>Number of elements copied to the @a rectangles array.</desc>
|
---|
8229 | </param>
|
---|
8230 | </method>
|
---|
8231 |
|
---|
8232 | <method name="setVisibleRegion">
|
---|
8233 | <desc>
|
---|
8234 | Suggests a new visible region to this framebuffer. This region
|
---|
8235 | represents the area of the VM display which is a union of regions of
|
---|
8236 | all top-level windows of the guest operating system running inside the
|
---|
8237 | VM (if the Guest Additions for this system support this
|
---|
8238 | functionality). This information may be used by the frontends to
|
---|
8239 | implement the seamless desktop integration feature.
|
---|
8240 |
|
---|
8241 | <note>
|
---|
8242 | The address of the provided array must be in the process space of
|
---|
8243 | this IFramebuffer object.
|
---|
8244 | </note>
|
---|
8245 | <note>
|
---|
8246 | The IFramebuffer implementation must make a copy of the provided
|
---|
8247 | array of rectangles.
|
---|
8248 | </note>
|
---|
8249 | </desc>
|
---|
8250 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
8251 | <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
|
---|
8252 | </param>
|
---|
8253 | <param name="count" type="unsigned long" dir="in">
|
---|
8254 | <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
|
---|
8255 | </param>
|
---|
8256 | </method>
|
---|
8257 |
|
---|
8258 | </interface>
|
---|
8259 |
|
---|
8260 | <interface
|
---|
8261 | name="IFramebufferOverlay" extends="IFrameBuffer"
|
---|
8262 | uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
|
---|
8263 | wsmap="suppress"
|
---|
8264 | >
|
---|
8265 | <desc>
|
---|
8266 | The IFramebufferOverlay interface represents an alpha blended overlay
|
---|
8267 | for displaying status icons above an IFramebuffer. It is always created
|
---|
8268 | not visible, so that it must be explicitly shown. It only covers a
|
---|
8269 | portion of the IFramebuffer, determined by its width, height and
|
---|
8270 | co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
|
---|
8271 | that order) format, and may be written to directly. Do re-read the
|
---|
8272 | width though, after setting it, as it may be adjusted (increased) to
|
---|
8273 | make it more suitable for the front end.
|
---|
8274 | </desc>
|
---|
8275 | <attribute name="x" type="unsigned long" readonly="yes">
|
---|
8276 | <desc>X position of the overlay, relative to the framebuffer.</desc>
|
---|
8277 | </attribute>
|
---|
8278 |
|
---|
8279 | <attribute name="y" type="unsigned long" readonly="yes">
|
---|
8280 | <desc>Y position of the overlay, relative to the framebuffer.</desc>
|
---|
8281 | </attribute>
|
---|
8282 |
|
---|
8283 | <attribute name="visible" type="boolean" readonly="no">
|
---|
8284 | <desc>
|
---|
8285 | Whether the overlay is currently visible.
|
---|
8286 | </desc>
|
---|
8287 | </attribute>
|
---|
8288 |
|
---|
8289 | <attribute name="alpha" type="unsigned long" readonly="no">
|
---|
8290 | <desc>
|
---|
8291 | The global alpha value for the overlay. This may or may not be
|
---|
8292 | supported by a given front end.
|
---|
8293 | </desc>
|
---|
8294 | </attribute>
|
---|
8295 |
|
---|
8296 | <method name="move">
|
---|
8297 | <desc>
|
---|
8298 | Changes the overlay's position relative to the IFramebuffer.
|
---|
8299 | </desc>
|
---|
8300 | <param name="x" type="unsigned long" dir="in"/>
|
---|
8301 | <param name="y" type="unsigned long" dir="in"/>
|
---|
8302 | </method>
|
---|
8303 |
|
---|
8304 | </interface>
|
---|
8305 |
|
---|
8306 | <interface
|
---|
8307 | name="IDisplay" extends="$unknown"
|
---|
8308 | uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
|
---|
8309 | wsmap="suppress"
|
---|
8310 | >
|
---|
8311 | <desc>
|
---|
8312 | The IDisplay interface represents the virtual machine's display.
|
---|
8313 |
|
---|
8314 | The object implementing this interface is contained in each
|
---|
8315 | <link to="IConsole::display"/> attribute and represents the visual
|
---|
8316 | output of the virtual machine.
|
---|
8317 |
|
---|
8318 | The virtual display supports pluggable output targets represented by the
|
---|
8319 | IFramebuffer interface. Examples of the output target are a window on
|
---|
8320 | the host computer or an RDP sessoin's display on a remote computer.
|
---|
8321 | </desc>
|
---|
8322 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
8323 | <desc>Current display width.</desc>
|
---|
8324 | </attribute>
|
---|
8325 |
|
---|
8326 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
8327 | <desc>Current display height.</desc>
|
---|
8328 | </attribute>
|
---|
8329 |
|
---|
8330 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
8331 | <desc>
|
---|
8332 | Current guest display color depth. Note that this may differ
|
---|
8333 | from <link to="IFramebuffer::bitsPerPixel"/>.
|
---|
8334 | </desc>
|
---|
8335 | </attribute>
|
---|
8336 |
|
---|
8337 | <method name="setupInternalFramebuffer">
|
---|
8338 | <desc>
|
---|
8339 | Prepares an internally managed framebuffer.
|
---|
8340 | </desc>
|
---|
8341 | <param name="depth" type="unsigned long" dir="in"/>
|
---|
8342 | </method>
|
---|
8343 |
|
---|
8344 | <method name="lockFramebuffer">
|
---|
8345 | <desc>
|
---|
8346 | Requests access to the internal framebuffer.
|
---|
8347 | </desc>
|
---|
8348 | <param name="address" type="octet" mod="ptr" dir="return"/>
|
---|
8349 | </method>
|
---|
8350 |
|
---|
8351 | <method name="unlockFramebuffer">
|
---|
8352 | <desc>
|
---|
8353 | Releases access to the internal framebuffer.
|
---|
8354 | </desc>
|
---|
8355 | </method>
|
---|
8356 |
|
---|
8357 | <method name="registerExternalFramebuffer">
|
---|
8358 | <desc>
|
---|
8359 | Registers an external framebuffer.
|
---|
8360 | </desc>
|
---|
8361 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
8362 | </method>
|
---|
8363 |
|
---|
8364 | <method name="setFramebuffer">
|
---|
8365 | <desc>
|
---|
8366 | Sets the framebuffer for given screen.
|
---|
8367 | </desc>
|
---|
8368 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
8369 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
8370 | </method>
|
---|
8371 |
|
---|
8372 | <method name="getFramebuffer">
|
---|
8373 | <desc>
|
---|
8374 | Queries the framebuffer for given screen.
|
---|
8375 | </desc>
|
---|
8376 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
8377 | <param name="framebuffer" type="IFramebuffer" dir="out"/>
|
---|
8378 | <param name="xOrigin" type="long" dir="out"/>
|
---|
8379 | <param name="yOrigin" type="long" dir="out"/>
|
---|
8380 | </method>
|
---|
8381 |
|
---|
8382 | <method name="setVideoModeHint">
|
---|
8383 | <desc>
|
---|
8384 | Asks VirtualBox to request the given video mode from
|
---|
8385 | the guest. This is just a hint and it cannot be guaranteed
|
---|
8386 | that the requested resolution will be used. Guest Additions
|
---|
8387 | are required for the request to be seen by guests. The caller
|
---|
8388 | should issue the request and wait for a resolution change and
|
---|
8389 | after a timeout retry.
|
---|
8390 |
|
---|
8391 | Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
|
---|
8392 | parameters means that the corresponding values should be taken from the
|
---|
8393 | current video mode (i.e. left unchanged).
|
---|
8394 |
|
---|
8395 | If the guest OS supports multi-monitor configuration then the @a display
|
---|
8396 | parameter specifies the number of the guest display to send the hint to:
|
---|
8397 | <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
|
---|
8398 | so on. If the multi-monitor configuration is not supported, @a display
|
---|
8399 | must be <tt>0</tt>.
|
---|
8400 |
|
---|
8401 | </desc>
|
---|
8402 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8403 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8404 | <param name="bitsPerPixel" type="unsigned long" dir="in"/>
|
---|
8405 | <param name="display" type="unsigned long" dir="in"/>
|
---|
8406 | </method>
|
---|
8407 |
|
---|
8408 | <method name="setSeamlessMode">
|
---|
8409 | <desc>
|
---|
8410 | Enables or disables seamless guest display rendering (seamless desktop
|
---|
8411 | integration) mode.
|
---|
8412 | <note>
|
---|
8413 | Calling this method has no effect if <link
|
---|
8414 | to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
|
---|
8415 | </note>
|
---|
8416 | </desc>
|
---|
8417 | <param name="enabled" type="boolean" dir="in"/>
|
---|
8418 | </method>
|
---|
8419 |
|
---|
8420 | <method name="takeScreenShot">
|
---|
8421 | <desc>
|
---|
8422 | Takes a screen shot of the requested size and copies it to the
|
---|
8423 | 32-bpp buffer allocated by the caller.
|
---|
8424 | </desc>
|
---|
8425 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
8426 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8427 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8428 | </method>
|
---|
8429 |
|
---|
8430 | <method name="drawToScreen">
|
---|
8431 | <desc>
|
---|
8432 | Draws a 32-bpp image of the specified size from the given buffer
|
---|
8433 | to the given point on the VM display.
|
---|
8434 | </desc>
|
---|
8435 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
8436 | <param name="x" type="unsigned long" dir="in"/>
|
---|
8437 | <param name="y" type="unsigned long" dir="in"/>
|
---|
8438 | <param name="width" type="unsigned long" dir="in"/>
|
---|
8439 | <param name="height" type="unsigned long" dir="in"/>
|
---|
8440 | </method>
|
---|
8441 |
|
---|
8442 | <method name="invalidateAndUpdate">
|
---|
8443 | <desc>
|
---|
8444 | Does a full invalidation of the VM display and instructs the VM
|
---|
8445 | to update it.
|
---|
8446 | </desc>
|
---|
8447 | </method>
|
---|
8448 |
|
---|
8449 | <method name="resizeCompleted">
|
---|
8450 | <desc>
|
---|
8451 | Signals that a framebuffer has completed the resize operation.
|
---|
8452 | </desc>
|
---|
8453 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
8454 | </method>
|
---|
8455 |
|
---|
8456 | <method name="updateCompleted">
|
---|
8457 | <desc>
|
---|
8458 | Signals that a framebuffer has completed the update operation.
|
---|
8459 | </desc>
|
---|
8460 | </method>
|
---|
8461 |
|
---|
8462 | </interface>
|
---|
8463 |
|
---|
8464 | <!--
|
---|
8465 | // INetworkAdapter
|
---|
8466 | /////////////////////////////////////////////////////////////////////////
|
---|
8467 | -->
|
---|
8468 |
|
---|
8469 | <enum
|
---|
8470 | name="NetworkAttachmentType"
|
---|
8471 | uuid="8730d899-d036-4925-bc63-e58f3486f4bf"
|
---|
8472 | >
|
---|
8473 | <desc>
|
---|
8474 | Network attachment type.
|
---|
8475 | </desc>
|
---|
8476 |
|
---|
8477 | <const name="Null" value="0">
|
---|
8478 | <desc><tt>null</tt> value. Also means "not attached".</desc>
|
---|
8479 | </const>
|
---|
8480 | <const name="NAT" value="1"/>
|
---|
8481 | <const name="HostInterface" value="2"/>
|
---|
8482 | <const name="Internal" value="3"/>
|
---|
8483 | </enum>
|
---|
8484 |
|
---|
8485 | <enum
|
---|
8486 | name="NetworkAdapterType"
|
---|
8487 | uuid="156b17b9-5d61-4d54-be90-62e37dda848d"
|
---|
8488 | >
|
---|
8489 | <desc>
|
---|
8490 | Network adapter type.
|
---|
8491 | </desc>
|
---|
8492 |
|
---|
8493 | <const name="Null" value="0">
|
---|
8494 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
8495 | </const>
|
---|
8496 | <const name="Am79C970A" value="1"/>
|
---|
8497 | <const name="Am79C973" value="2"/>
|
---|
8498 | <const name="I82540EM" value="3"/>
|
---|
8499 | <const name="I82543GC" value="4"/>
|
---|
8500 | </enum>
|
---|
8501 |
|
---|
8502 | <interface
|
---|
8503 | name="INetworkAdapter" extends="$unknown"
|
---|
8504 | uuid="a876d9b1-68d9-43b1-9c68-ddea0a473663"
|
---|
8505 | wsmap="managed"
|
---|
8506 | >
|
---|
8507 | <attribute name="adapterType" type="NetworkAdapterType">
|
---|
8508 | <desc>
|
---|
8509 | Type of the virtual network adapter. Depending on this value,
|
---|
8510 | VirtualBox will provide a different virtual network hardware
|
---|
8511 | to the guest.
|
---|
8512 | </desc>
|
---|
8513 | </attribute>
|
---|
8514 |
|
---|
8515 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
8516 | <desc>
|
---|
8517 | Slot number this adapter is plugged into. Corresponds to
|
---|
8518 | the value you pass to <link to="IMachine::getNetworkAdapter"/>
|
---|
8519 | to obtain this instance.
|
---|
8520 | </desc>
|
---|
8521 | </attribute>
|
---|
8522 |
|
---|
8523 | <attribute name="enabled" type="boolean">
|
---|
8524 | <desc>
|
---|
8525 | Flag whether the network adapter is present in the
|
---|
8526 | guest system. If disabled, the virtual guest hardware will
|
---|
8527 | not contain this network adapter. Can only be changed when
|
---|
8528 | the VM is not running.
|
---|
8529 | </desc>
|
---|
8530 | </attribute>
|
---|
8531 |
|
---|
8532 | <attribute name="MACAddress" type="wstring">
|
---|
8533 | <desc>
|
---|
8534 | Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
|
---|
8535 | it to NULL, VirtualBox will generate a unique MAC address.
|
---|
8536 | </desc>
|
---|
8537 | </attribute>
|
---|
8538 |
|
---|
8539 | <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
|
---|
8540 |
|
---|
8541 | <attribute name="hostInterface" type="wstring">
|
---|
8542 | <desc>
|
---|
8543 | Name of the Host Network Interface that is currently in use. NULL will be returned
|
---|
8544 | if no device has been allocated. On Linux, setting this refers to a permanent TAP
|
---|
8545 | device. However, a file descriptor has precedence over the interface name on Linux.
|
---|
8546 | Note that when VBox allocates a TAP device, this property will not be set, i.e. the
|
---|
8547 | interface name would have to be determined using the file descriptor and /proc/self/fd.
|
---|
8548 | </desc>
|
---|
8549 | </attribute>
|
---|
8550 |
|
---|
8551 | <if target="xpidl">
|
---|
8552 | <attribute name="TAPFileDescriptor" type="long">
|
---|
8553 | <desc>
|
---|
8554 | File descriptor of the TAP device. It can either be setup by the caller
|
---|
8555 | which has to supply an existing valid file handle allocated in the parent
|
---|
8556 | process of the VM process or allocated by VirtualBox. The value is -1 if it
|
---|
8557 | has not been defined. This property is non persistent, i.e. it will not be
|
---|
8558 | stored in the VM's configuration data and thus has to be set at each startup.
|
---|
8559 | </desc>
|
---|
8560 | </attribute>
|
---|
8561 | <attribute name="TAPSetupApplication" type="wstring">
|
---|
8562 | <desc>
|
---|
8563 | Application to start to configure the TAP device.
|
---|
8564 | It is being passed two parameters, 1) the file handle (as ascii),
|
---|
8565 | 2) the TAP device name if it is available.
|
---|
8566 | </desc>
|
---|
8567 | </attribute>
|
---|
8568 | <attribute name="TAPTerminateApplication" type="wstring">
|
---|
8569 | <desc>
|
---|
8570 | Application to start before closing a TAP device.
|
---|
8571 | It is being passed two parameters, 1) the file handle (as ascii),
|
---|
8572 | 2) the TAP device name if it is available.
|
---|
8573 | </desc>
|
---|
8574 | </attribute>
|
---|
8575 | </if>
|
---|
8576 |
|
---|
8577 | <attribute name="internalNetwork" type="wstring">
|
---|
8578 | <desc>
|
---|
8579 | Name of the internal network the VM is attached to.
|
---|
8580 | </desc>
|
---|
8581 | </attribute>
|
---|
8582 |
|
---|
8583 | <attribute name="NATNetwork" type="wstring">
|
---|
8584 | <desc>
|
---|
8585 | Name of the NAT network the VM is attached to.
|
---|
8586 | </desc>
|
---|
8587 | </attribute>
|
---|
8588 |
|
---|
8589 | <attribute name="cableConnected" type="boolean">
|
---|
8590 | <desc>
|
---|
8591 | Flag whether the adapter reports the cable as connected or not.
|
---|
8592 | It can be used to report offline situations to a VM.
|
---|
8593 | </desc>
|
---|
8594 | </attribute>
|
---|
8595 |
|
---|
8596 | <attribute name="lineSpeed" type="unsigned long">
|
---|
8597 | <desc>
|
---|
8598 | Line speed reported by custom drivers, in units of 1 kbps.
|
---|
8599 | </desc>
|
---|
8600 | </attribute>
|
---|
8601 |
|
---|
8602 | <attribute name="traceEnabled" type="boolean">
|
---|
8603 | <desc>
|
---|
8604 | Flag whether network traffic from/to the network card should be traced.
|
---|
8605 | Can only be toggled when the VM is turned off.
|
---|
8606 | </desc>
|
---|
8607 | </attribute>
|
---|
8608 |
|
---|
8609 | <attribute name="traceFile" type="wstring">
|
---|
8610 | <desc>
|
---|
8611 | Filename where a network trace will be stored. If not set, VBox-pid.pcap
|
---|
8612 | will be used.
|
---|
8613 | </desc>
|
---|
8614 | </attribute>
|
---|
8615 |
|
---|
8616 | <method name="attachToNAT">
|
---|
8617 | <desc>
|
---|
8618 | Attach the network adapter to the Network Address Translation (NAT) interface.
|
---|
8619 | </desc>
|
---|
8620 | </method>
|
---|
8621 |
|
---|
8622 | <method name="attachToHostInterface">
|
---|
8623 | <desc>
|
---|
8624 | Attach the network adapter to a host interface. On Linux, the TAP
|
---|
8625 | setup application will be executed if configured and unless a device
|
---|
8626 | name and/or file descriptor has been set, a new TAP interface will be
|
---|
8627 | created.
|
---|
8628 | </desc>
|
---|
8629 | </method>
|
---|
8630 |
|
---|
8631 | <method name="attachToInternalNetwork">
|
---|
8632 | <desc>
|
---|
8633 | Attach the network adapter to an internal network.
|
---|
8634 | </desc>
|
---|
8635 | </method>
|
---|
8636 |
|
---|
8637 | <method name="detach">
|
---|
8638 | <desc>
|
---|
8639 | Detach the network adapter
|
---|
8640 | </desc>
|
---|
8641 | </method>
|
---|
8642 | </interface>
|
---|
8643 |
|
---|
8644 |
|
---|
8645 | <!--
|
---|
8646 | // ISerialPort
|
---|
8647 | /////////////////////////////////////////////////////////////////////////
|
---|
8648 | -->
|
---|
8649 |
|
---|
8650 | <enum
|
---|
8651 | name="PortMode"
|
---|
8652 | uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
|
---|
8653 | >
|
---|
8654 | <desc>
|
---|
8655 | The PortMode enumeration represents possible communicaton modes for
|
---|
8656 | the virtual serial port device.
|
---|
8657 | </desc>
|
---|
8658 |
|
---|
8659 | <const name="Disconnected" value="0">
|
---|
8660 | <desc>Virtual device is not attached to any real host device.</desc>
|
---|
8661 | </const>
|
---|
8662 | <const name="HostPipe" value="1">
|
---|
8663 | <desc>Virtual device is attached to a host pipe.</desc>
|
---|
8664 | </const>
|
---|
8665 | <const name="HostDevice" value="2">
|
---|
8666 | <desc>Virtual device is attached to a host device.</desc>
|
---|
8667 | </const>
|
---|
8668 | </enum>
|
---|
8669 |
|
---|
8670 | <interface
|
---|
8671 | name="ISerialPort" extends="$unknown"
|
---|
8672 | uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
|
---|
8673 | wsmap="managed"
|
---|
8674 | >
|
---|
8675 |
|
---|
8676 | <desc>
|
---|
8677 | The ISerialPort interface represents the virtual serial port device.
|
---|
8678 |
|
---|
8679 | The virtual serial port device acts like an ordinary serial port
|
---|
8680 | inside the virtual machine. This device communicates to the real
|
---|
8681 | serial port hardware in one of two modes: host pipe or host device.
|
---|
8682 |
|
---|
8683 | In host pipe mode, the #path attribute specifies the path to the pipe on
|
---|
8684 | the host computer that represents a serial port. The #server attribute
|
---|
8685 | determines if this pipe is created by the virtual machine process at
|
---|
8686 | machine startup or it must already exist before starting machine
|
---|
8687 | execution.
|
---|
8688 |
|
---|
8689 | In host device mode, the #path attribute specifies the name of the
|
---|
8690 | serial port device on the host computer.
|
---|
8691 |
|
---|
8692 | There is also a third communication mode: the disconnected mode. In this
|
---|
8693 | mode, the guest OS running inside the virtual machine will be able to
|
---|
8694 | detect the serial port, but all port write operations will be discarded
|
---|
8695 | and all port read operations will return no data.
|
---|
8696 |
|
---|
8697 | <see>IMachine::getSerialPort</see>
|
---|
8698 | </desc>
|
---|
8699 |
|
---|
8700 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
8701 | <desc>
|
---|
8702 | Slot number this serial port is plugged into. Corresponds to
|
---|
8703 | the value you pass to <link to="IMachine::getSerialPort"/>
|
---|
8704 | to obtain this instance.
|
---|
8705 | </desc>
|
---|
8706 | </attribute>
|
---|
8707 |
|
---|
8708 | <attribute name="enabled" type="boolean">
|
---|
8709 | <desc>
|
---|
8710 | Flag whether the serial port is enabled. If disabled,
|
---|
8711 | the serial port will not be reported to the guest OS.
|
---|
8712 | </desc>
|
---|
8713 | </attribute>
|
---|
8714 |
|
---|
8715 | <attribute name="IOBase" type="unsigned long">
|
---|
8716 | <desc>Base I/O address of the serial port.</desc>
|
---|
8717 | </attribute>
|
---|
8718 |
|
---|
8719 | <attribute name="IRQ" type="unsigned long">
|
---|
8720 | <desc>IRQ number of the serial port.</desc>
|
---|
8721 | </attribute>
|
---|
8722 |
|
---|
8723 | <attribute name="hostMode" type="PortMode">
|
---|
8724 | <desc>How is this port connected to the host.</desc>
|
---|
8725 | </attribute>
|
---|
8726 |
|
---|
8727 | <attribute name="server" type="boolean">
|
---|
8728 | <desc>
|
---|
8729 | Flag whether this serial port acts as a server (creates a new pipe on
|
---|
8730 | the host) or as a client (uses the existing pipe). This attribute is
|
---|
8731 | used only when <link to="#hostMode"/> is PortMode::HostPipe.
|
---|
8732 | </desc>
|
---|
8733 | </attribute>
|
---|
8734 |
|
---|
8735 | <attribute name="path" type="wstring">
|
---|
8736 | <desc>
|
---|
8737 | Path to the serial port's pipe on the host when <link to="#hostMode"/> is
|
---|
8738 | PortMode::HostPipe, or the host serial device name when
|
---|
8739 | <link to="#hostMode"/> is PortMode::HostDevice. In either of the above
|
---|
8740 | cases, setting a @c null or an empty string as the attribute's value
|
---|
8741 | will result into an error. Otherwise, the value of this property is
|
---|
8742 | ignored.
|
---|
8743 | </desc>
|
---|
8744 | </attribute>
|
---|
8745 |
|
---|
8746 | </interface>
|
---|
8747 |
|
---|
8748 | <!--
|
---|
8749 | // IParallelPort
|
---|
8750 | /////////////////////////////////////////////////////////////////////////
|
---|
8751 | -->
|
---|
8752 |
|
---|
8753 | <interface
|
---|
8754 | name="IParallelPort" extends="$unknown"
|
---|
8755 | uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
|
---|
8756 | wsmap="managed"
|
---|
8757 | >
|
---|
8758 |
|
---|
8759 | <desc>
|
---|
8760 | The IParallelPort interface represents the virtual parallel port device.
|
---|
8761 |
|
---|
8762 | The virtual parallel port device acts like an ordinary parallel port
|
---|
8763 | inside the virtual machine. This device communicates to the real
|
---|
8764 | parallel port hardware using the name of the parallel device on the host
|
---|
8765 | computer specified in the #path attribute.
|
---|
8766 |
|
---|
8767 | Each virtual parallel port device is assigned a base I/O address and an
|
---|
8768 | IRQ number that will be reported to the guest operating system and used
|
---|
8769 | to operate the given parallel port from within the virtual machine.
|
---|
8770 |
|
---|
8771 | <see>IMachine::getParallelPort</see>
|
---|
8772 | </desc>
|
---|
8773 |
|
---|
8774 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
8775 | <desc>
|
---|
8776 | Slot number this parallel port is plugged into. Corresponds to
|
---|
8777 | the value you pass to <link to="IMachine::getParallelPort"/>
|
---|
8778 | to obtain this instance.
|
---|
8779 | </desc>
|
---|
8780 | </attribute>
|
---|
8781 |
|
---|
8782 | <attribute name="enabled" type="boolean">
|
---|
8783 | <desc>
|
---|
8784 | Flag whether the parallel port is enabled. If disabled,
|
---|
8785 | the parallel port will not be reported to the guest OS.
|
---|
8786 | </desc>
|
---|
8787 | </attribute>
|
---|
8788 |
|
---|
8789 | <attribute name="IOBase" type="unsigned long">
|
---|
8790 | <desc>Base I/O address of the parallel port.</desc>
|
---|
8791 | </attribute>
|
---|
8792 |
|
---|
8793 | <attribute name="IRQ" type="unsigned long">
|
---|
8794 | <desc>IRQ number of the parallel port.</desc>
|
---|
8795 | </attribute>
|
---|
8796 |
|
---|
8797 | <attribute name="path" type="wstring">
|
---|
8798 | <desc>
|
---|
8799 | Host parallel device name. If this parallel port is enabled, setting a
|
---|
8800 | @c null or an empty string as this attribute's value will result into
|
---|
8801 | an error.
|
---|
8802 | </desc>
|
---|
8803 | </attribute>
|
---|
8804 |
|
---|
8805 | </interface>
|
---|
8806 |
|
---|
8807 |
|
---|
8808 | <!--
|
---|
8809 | // IMachineDebugger
|
---|
8810 | /////////////////////////////////////////////////////////////////////////
|
---|
8811 | -->
|
---|
8812 |
|
---|
8813 | <interface
|
---|
8814 | name="IMachineDebugger" extends="$unknown"
|
---|
8815 | uuid="54ebce96-fa7d-4a4d-bc81-a7db41c29637"
|
---|
8816 | wsmap="suppress"
|
---|
8817 | >
|
---|
8818 | <method name="resetStats">
|
---|
8819 | <desc>
|
---|
8820 | Reset VM statistics.
|
---|
8821 | </desc>
|
---|
8822 | <param name="pattern" type="wstring" dir="in">
|
---|
8823 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
8824 | </param>
|
---|
8825 | </method>
|
---|
8826 |
|
---|
8827 | <method name="dumpStats">
|
---|
8828 | <desc>
|
---|
8829 | Dumps VM statistics.
|
---|
8830 | </desc>
|
---|
8831 | <param name="pattern" type="wstring" dir="in">
|
---|
8832 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
8833 | </param>
|
---|
8834 | </method>
|
---|
8835 |
|
---|
8836 | <method name="getStats">
|
---|
8837 | <desc>
|
---|
8838 | Get the VM statistics in a XMLish format.
|
---|
8839 | </desc>
|
---|
8840 | <param name="pattern" type="wstring" dir="in">
|
---|
8841 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
8842 | </param>
|
---|
8843 | <param name="withDescriptions" type="boolean" dir="in">
|
---|
8844 | <desc>Whether to include the descriptions.</desc>
|
---|
8845 | </param>
|
---|
8846 | <param name="stats" type="wstring" dir="out">
|
---|
8847 | <desc>The XML document containing the statistics.</desc>
|
---|
8848 | </param>
|
---|
8849 | </method>
|
---|
8850 |
|
---|
8851 | <attribute name="singlestep" type="boolean">
|
---|
8852 | <desc>Switch for enabling singlestepping.</desc>
|
---|
8853 | </attribute>
|
---|
8854 |
|
---|
8855 | <attribute name="recompileUser" type="boolean">
|
---|
8856 | <desc>Switch for forcing code recompilation for user mode code.</desc>
|
---|
8857 | </attribute>
|
---|
8858 |
|
---|
8859 | <attribute name="recompileSupervisor" type="boolean">
|
---|
8860 | <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
|
---|
8861 | </attribute>
|
---|
8862 |
|
---|
8863 | <attribute name="PATMEnabled" type="boolean">
|
---|
8864 | <desc>Switch for enabling and disabling the PATM component.</desc>
|
---|
8865 | </attribute>
|
---|
8866 |
|
---|
8867 | <attribute name="CSAMEnabled" type="boolean">
|
---|
8868 | <desc>Switch for enabling and disabling the CSAM component.</desc>
|
---|
8869 | </attribute>
|
---|
8870 |
|
---|
8871 | <attribute name="logEnabled" type="boolean">
|
---|
8872 | <desc>Switch for enabling and disabling logging.</desc>
|
---|
8873 | </attribute>
|
---|
8874 |
|
---|
8875 | <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
|
---|
8876 | <desc>
|
---|
8877 | Flag indicating whether the VM is currently making use of CPU hardware
|
---|
8878 | virtualization extensions.
|
---|
8879 | </desc>
|
---|
8880 | </attribute>
|
---|
8881 |
|
---|
8882 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
|
---|
8883 | <desc>
|
---|
8884 | Flag indicating whether the VM is currently making use of the nested paging
|
---|
8885 | CPU hardware virtualization extension.
|
---|
8886 | </desc>
|
---|
8887 | </attribute>
|
---|
8888 |
|
---|
8889 | <attribute name="PAEEnabled" type="boolean" readonly="yes">
|
---|
8890 | <desc>
|
---|
8891 | Flag indicating whether the VM is currently making use of the Physical
|
---|
8892 | Address Extension CPU feature.
|
---|
8893 | </desc>
|
---|
8894 | </attribute>
|
---|
8895 |
|
---|
8896 | <attribute name="virtualTimeRate" type="unsigned long">
|
---|
8897 | <desc>
|
---|
8898 | The rate at which the virtual time runs expressed as a percentage.
|
---|
8899 | The accepted range is 2% to 20000%.
|
---|
8900 | </desc>
|
---|
8901 | </attribute>
|
---|
8902 |
|
---|
8903 | <!-- @todo method for setting log flags, groups and destination! -->
|
---|
8904 |
|
---|
8905 | <attribute name="VM" type="unsigned long long" readonly="yes">
|
---|
8906 | <desc>
|
---|
8907 | Gets the VM handle. This is only for internal use while
|
---|
8908 | we carve the details of this interface.
|
---|
8909 | </desc>
|
---|
8910 | </attribute>
|
---|
8911 |
|
---|
8912 | </interface>
|
---|
8913 |
|
---|
8914 | <!--
|
---|
8915 | // IUSBController
|
---|
8916 | /////////////////////////////////////////////////////////////////////////
|
---|
8917 | -->
|
---|
8918 |
|
---|
8919 | <interface
|
---|
8920 | name="IUSBController" extends="$unknown"
|
---|
8921 | uuid="f4c2d3dc-f109-4da7-93b1-ec28973ac89f"
|
---|
8922 | wsmap="managed"
|
---|
8923 | >
|
---|
8924 | <attribute name="enabled" type="boolean">
|
---|
8925 | <desc>
|
---|
8926 | Flag whether the USB controller is present in the
|
---|
8927 | guest system. If disabled, the virtual guest hardware will
|
---|
8928 | not contain any USB controller. Can only be changed when
|
---|
8929 | the VM is powered off.
|
---|
8930 | </desc>
|
---|
8931 | </attribute>
|
---|
8932 |
|
---|
8933 | <attribute name="enabledEhci" type="boolean">
|
---|
8934 | <desc>
|
---|
8935 | Flag whether the USB EHCI controller is present in the
|
---|
8936 | guest system. If disabled, the virtual guest hardware will
|
---|
8937 | not contain a USB EHCI controller. Can only be changed when
|
---|
8938 | the VM is powered off.
|
---|
8939 | </desc>
|
---|
8940 | </attribute>
|
---|
8941 |
|
---|
8942 | <attribute name="USBStandard" type="unsigned short" readonly="yes">
|
---|
8943 | <desc>
|
---|
8944 | USB standard version which the controller implements.
|
---|
8945 | This is a BCD which means that the major version is in the
|
---|
8946 | high byte and minor version is in the low byte.
|
---|
8947 | </desc>
|
---|
8948 | </attribute>
|
---|
8949 |
|
---|
8950 | <attribute name="deviceFilters" type="IUSBDeviceFilterCollection" readonly="yes">
|
---|
8951 | <desc>
|
---|
8952 | List of USB device filters associated with the machine.
|
---|
8953 |
|
---|
8954 | If the machine is currently running, these filters are activated
|
---|
8955 | every time a new (supported) USB device is attached to the host
|
---|
8956 | computer that was not ignored by global filters
|
---|
8957 | (<link to="IHost::USBDeviceFilters"/>).
|
---|
8958 |
|
---|
8959 | These filters are also activated when the machine is powered up.
|
---|
8960 | They are run against a list of all currently available USB
|
---|
8961 | devices (in states
|
---|
8962 | <link to="USBDeviceState::Available">Available</link>,
|
---|
8963 | <link to="USBDeviceState::Busy">Busy</link>,
|
---|
8964 | <link to="USBDeviceState::Held">Held</link>) that were not previously
|
---|
8965 | ignored by global filters.
|
---|
8966 |
|
---|
8967 | If at least one filter matches the USB device in question, this
|
---|
8968 | device is automatically captured (attached to) the virtual USB
|
---|
8969 | controller of this machine.
|
---|
8970 |
|
---|
8971 | <see>IUSBDeviceFilter, ::IUSBController</see>
|
---|
8972 | </desc>
|
---|
8973 | </attribute>
|
---|
8974 |
|
---|
8975 | <method name="createDeviceFilter">
|
---|
8976 | <desc>
|
---|
8977 | Creates a new USB device filter. All attributes except
|
---|
8978 | the filter name are set to <tt>null</tt> (any match),
|
---|
8979 | <i>active</i> is <tt>false</tt> (the filter is not active).
|
---|
8980 |
|
---|
8981 | The created filter can then be added to the list of filters using
|
---|
8982 | <link to="#insertDeviceFilter()"/>.
|
---|
8983 |
|
---|
8984 | <see>#deviceFilters</see>
|
---|
8985 | </desc>
|
---|
8986 | <param name="name" type="wstring" dir="in">
|
---|
8987 | <desc>
|
---|
8988 | Filter name. See <link to="IUSBDeviceFilter::name"/>
|
---|
8989 | for more info.
|
---|
8990 | </desc>
|
---|
8991 | </param>
|
---|
8992 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
8993 | <desc>Created filter object.</desc>
|
---|
8994 | </param>
|
---|
8995 | </method>
|
---|
8996 |
|
---|
8997 | <method name="insertDeviceFilter">
|
---|
8998 | <desc>
|
---|
8999 | Inserts the given USB device to the specified position
|
---|
9000 | in the list of filters.
|
---|
9001 |
|
---|
9002 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
9003 | position is equal to or greater than the number of elements in
|
---|
9004 | the list, the filter is added to the end of the collection.
|
---|
9005 |
|
---|
9006 | <note>
|
---|
9007 | Duplicates are not allowed, so an attempt to inster a
|
---|
9008 | filter that is already in the collection, will return an
|
---|
9009 | error.
|
---|
9010 | </note>
|
---|
9011 |
|
---|
9012 | <see>#deviceFilters</see>
|
---|
9013 | </desc>
|
---|
9014 | <param name="position" type="unsigned long" dir="in">
|
---|
9015 | <desc>Position to insert the filter to.</desc>
|
---|
9016 | </param>
|
---|
9017 | <param name="filter" type="IUSBDeviceFilter" dir="in">
|
---|
9018 | <desc>USB device filter to insert.</desc>
|
---|
9019 | </param>
|
---|
9020 | </method>
|
---|
9021 |
|
---|
9022 | <method name="removeDeviceFilter">
|
---|
9023 | <desc>
|
---|
9024 | Removes a USB device filter from the specified position in the
|
---|
9025 | list of filters.
|
---|
9026 |
|
---|
9027 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
9028 | position equal to or greater than the number of elements in
|
---|
9029 | the list will produce an error.
|
---|
9030 |
|
---|
9031 | <see>#deviceFilters</see>
|
---|
9032 | </desc>
|
---|
9033 | <param name="position" type="unsigned long" dir="in">
|
---|
9034 | <desc>Position to remove the filter from.</desc>
|
---|
9035 | </param>
|
---|
9036 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
9037 | <desc>Removed USB device filter.</desc>
|
---|
9038 | </param>
|
---|
9039 | </method>
|
---|
9040 |
|
---|
9041 | </interface>
|
---|
9042 |
|
---|
9043 |
|
---|
9044 | <!--
|
---|
9045 | // IUSBDevice
|
---|
9046 | /////////////////////////////////////////////////////////////////////////
|
---|
9047 | -->
|
---|
9048 |
|
---|
9049 | <enumerator
|
---|
9050 | name="IUSBDeviceEnumerator" type="IUSBDevice"
|
---|
9051 | uuid="aefe00f7-eb8a-454b-9ea4-fd5ad93c0e99"
|
---|
9052 | />
|
---|
9053 |
|
---|
9054 | <collection
|
---|
9055 | name="IUSBDeviceCollection" type="IUSBDevice"
|
---|
9056 | enumerator="IUSBDeviceEnumerator"
|
---|
9057 | uuid="e31f3248-90dd-4ca2-95f0-6b36042d96a2"
|
---|
9058 | readonly="yes"
|
---|
9059 | >
|
---|
9060 | <method name="findById">
|
---|
9061 | <desc>
|
---|
9062 | Searches this collection for a USB device with the given UUID.
|
---|
9063 | <note>
|
---|
9064 | The method returns an error if the given UUID does not
|
---|
9065 | correspond to any USB device in the collection.
|
---|
9066 | </note>
|
---|
9067 | <see>IUSBDevice::id</see>
|
---|
9068 | </desc>
|
---|
9069 | <param name="id" type="uuid" dir="in">
|
---|
9070 | <desc>UUID of the USB device to search for.</desc>
|
---|
9071 | </param>
|
---|
9072 | <param name="device" type="IUSBDevice" dir="return">
|
---|
9073 | <desc>Found USB device object.</desc>
|
---|
9074 | </param>
|
---|
9075 | </method>
|
---|
9076 |
|
---|
9077 | <method name="findByAddress">
|
---|
9078 | <desc>
|
---|
9079 | Searches this collection for a USB device with the given
|
---|
9080 | host address.
|
---|
9081 | <note>
|
---|
9082 | The method returns an error if the given address does not
|
---|
9083 | correspond to any USB device in the collection.
|
---|
9084 | </note>
|
---|
9085 | <see>IUSBDevice::address</see>
|
---|
9086 | </desc>
|
---|
9087 | <param name="name" type="wstring" dir="in">
|
---|
9088 | <desc>
|
---|
9089 | Address of the USB device (as assigned by the host) to
|
---|
9090 | search for.
|
---|
9091 | </desc>
|
---|
9092 | </param>
|
---|
9093 | <param name="device" type="IUSBDevice" dir="return">
|
---|
9094 | <desc>Found USB device object.</desc>
|
---|
9095 | </param>
|
---|
9096 | </method>
|
---|
9097 |
|
---|
9098 | </collection>
|
---|
9099 |
|
---|
9100 | <interface
|
---|
9101 | name="IUSBDevice" extends="$unknown"
|
---|
9102 | uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
|
---|
9103 | wsmap="managed"
|
---|
9104 | >
|
---|
9105 | <desc>
|
---|
9106 | The IUSBDevice interface represents a virtual USB device attached to the
|
---|
9107 | virtual machine.
|
---|
9108 |
|
---|
9109 | A collection of objects implementing this interface is stored in the
|
---|
9110 | <link to="IConsole::USBDevices"/> attribute which lists all USB devices
|
---|
9111 | attached to a running virtual machine's USB controller.
|
---|
9112 | </desc>
|
---|
9113 |
|
---|
9114 | <attribute name="id" type="uuid" readonly="yes">
|
---|
9115 | <desc>
|
---|
9116 | Unique USB device ID. This ID is built from #vendorId,
|
---|
9117 | #productId, #revision and #serialNumber.
|
---|
9118 | </desc>
|
---|
9119 | </attribute>
|
---|
9120 |
|
---|
9121 | <attribute name="vendorId" type="unsigned short" readonly="yes">
|
---|
9122 | <desc>Vendor ID.</desc>
|
---|
9123 | </attribute>
|
---|
9124 |
|
---|
9125 | <attribute name="productId" type="unsigned short" readonly="yes">
|
---|
9126 | <desc>Product ID.</desc>
|
---|
9127 | </attribute>
|
---|
9128 |
|
---|
9129 | <attribute name="revision" type="unsigned short" readonly="yes">
|
---|
9130 | <desc>
|
---|
9131 | Product revision number. This is a packed BCD represented as
|
---|
9132 | unsigned short. The high byte is the integer part and the low
|
---|
9133 | byte is the decimal.
|
---|
9134 | </desc>
|
---|
9135 | </attribute>
|
---|
9136 |
|
---|
9137 | <attribute name="manufacturer" type="wstring" readonly="yes">
|
---|
9138 | <desc>Manufacturer string.</desc>
|
---|
9139 | </attribute>
|
---|
9140 |
|
---|
9141 | <attribute name="product" type="wstring" readonly="yes">
|
---|
9142 | <desc>Product string.</desc>
|
---|
9143 | </attribute>
|
---|
9144 |
|
---|
9145 | <attribute name="serialNumber" type="wstring" readonly="yes">
|
---|
9146 | <desc>Serial number string.</desc>
|
---|
9147 | </attribute>
|
---|
9148 |
|
---|
9149 | <attribute name="address" type="wstring" readonly="yes">
|
---|
9150 | <desc>Host specific address of the device.</desc>
|
---|
9151 | </attribute>
|
---|
9152 |
|
---|
9153 | <attribute name="port" type="unsigned short" readonly="yes">
|
---|
9154 | <desc>
|
---|
9155 | Host USB port number the device is physically
|
---|
9156 | coonected to.
|
---|
9157 | </desc>
|
---|
9158 | </attribute>
|
---|
9159 |
|
---|
9160 | <attribute name="version" type="unsigned short" readonly="yes">
|
---|
9161 | <desc>
|
---|
9162 | The major USB version of the device - 1 or 2.
|
---|
9163 | </desc>
|
---|
9164 | </attribute>
|
---|
9165 |
|
---|
9166 | <attribute name="portVersion" type="unsigned short" readonly="yes">
|
---|
9167 | <desc>
|
---|
9168 | The major USB version of the host USB port the device is
|
---|
9169 | physically coonected to - 1 or 2. For devices not connected to
|
---|
9170 | anything this will have the same value as the version attribute.
|
---|
9171 | </desc>
|
---|
9172 | </attribute>
|
---|
9173 |
|
---|
9174 | <attribute name="remote" type="boolean" readonly="yes">
|
---|
9175 | <desc>
|
---|
9176 | Whether the device is physically connected to a remote VRDP
|
---|
9177 | client or to a local host machine.
|
---|
9178 | </desc>
|
---|
9179 | </attribute>
|
---|
9180 |
|
---|
9181 | </interface>
|
---|
9182 |
|
---|
9183 |
|
---|
9184 | <!--
|
---|
9185 | // IUSBDeviceFilter
|
---|
9186 | /////////////////////////////////////////////////////////////////////////
|
---|
9187 | -->
|
---|
9188 |
|
---|
9189 | <enumerator
|
---|
9190 | name="IUSBDeviceFilterEnumerator" type="IUSBDeviceFilter"
|
---|
9191 | uuid="d5109c61-93e7-4726-926b-0dee1020da56"
|
---|
9192 | />
|
---|
9193 |
|
---|
9194 | <collection
|
---|
9195 | name="IUSBDeviceFilterCollection" type="IUSBDeviceFilter"
|
---|
9196 | enumerator="IUSBDeviceFilterEnumerator"
|
---|
9197 | uuid="4fa3fc99-ceb1-4bf5-a9cb-e962d825c1ef"
|
---|
9198 | readonly="yes"
|
---|
9199 | />
|
---|
9200 |
|
---|
9201 | <interface
|
---|
9202 | name="IUSBDeviceFilter" extends="$unknown"
|
---|
9203 | uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
|
---|
9204 | wsmap="managed"
|
---|
9205 | >
|
---|
9206 | <desc>
|
---|
9207 | The IUSBDeviceFilter interface represents an USB device filter used
|
---|
9208 | to perform actions on a group of USB devices.
|
---|
9209 |
|
---|
9210 | This type of filters is used by running virtual machines to
|
---|
9211 | automatically capture selected USB devices once they are physically
|
---|
9212 | attached to the host computer.
|
---|
9213 |
|
---|
9214 | A USB device is matched to the given device filter if and only if all
|
---|
9215 | attributes of the device match the corresponding attributes of the
|
---|
9216 | filter (that is, attributes are joined together using the logical AND
|
---|
9217 | operation). On the other hand, all together, filters in the list of
|
---|
9218 | filters carry the semantics of the logical OR operation. So if it is
|
---|
9219 | desirable to create a match like "this vendor id OR this product id",
|
---|
9220 | one needs to create two filters and specify "any match" (see below)
|
---|
9221 | for unused attributes.
|
---|
9222 |
|
---|
9223 | All filter attributes used for matching are strings. Each string
|
---|
9224 | is an expression representing a set of values of the corresponding
|
---|
9225 | device attribute, that will match the given filter. Currently, the
|
---|
9226 | following filtering expressions are supported:
|
---|
9227 |
|
---|
9228 | <ul>
|
---|
9229 | <li><i>Interval filters</i>. Used to specify valid intervals for
|
---|
9230 | integer device attributes (Vendor ID, Product ID and Revision).
|
---|
9231 | The format of the string is:
|
---|
9232 |
|
---|
9233 | <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
|
---|
9234 |
|
---|
9235 | where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
|
---|
9236 | (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
|
---|
9237 | or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
|
---|
9238 | is ommitted before a dash (<tt>-</tt>), the minimum possible integer
|
---|
9239 | is assumed; if <tt>n</tt> is ommitted after a dash, the maximum
|
---|
9240 | possible integer is assummed.
|
---|
9241 | </li>
|
---|
9242 | <li><i>Boolean filters</i>. Used to specify acceptable values for
|
---|
9243 | boolean device attributes. The format of the string is:
|
---|
9244 |
|
---|
9245 | <tt>true|false|yes|no|0|1</tt>
|
---|
9246 |
|
---|
9247 | </li>
|
---|
9248 | <li><i>Exact match</i>. Used to specify a single value for the given
|
---|
9249 | device attribute. Any string that does't start with <tt>int:</tt>
|
---|
9250 | represents the exact match. String device attributes are compared to
|
---|
9251 | this string including case of symbols. Integer attributes are first
|
---|
9252 | converted to a string (see individual filter attributes) and then
|
---|
9253 | compared ignoring case.
|
---|
9254 |
|
---|
9255 | </li>
|
---|
9256 | <li><i>Any match</i>. Any value of the corresponding device attribute
|
---|
9257 | will match the given filter. An empty or <tt>null</tt> string is
|
---|
9258 | used to construct this type of filtering expressions.
|
---|
9259 |
|
---|
9260 | </li>
|
---|
9261 | </ul>
|
---|
9262 |
|
---|
9263 | <note>
|
---|
9264 | On the Windows host platform, interval filters are not currently
|
---|
9265 | available. Also all string filter attributes
|
---|
9266 | (<link to="#manufacturer"/>, <link to="#product"/>,
|
---|
9267 | <link to="#serialNumber"/>) are ignored, so they behave as
|
---|
9268 | <i>any match</i> no matter what string expression is specified.
|
---|
9269 | </note>
|
---|
9270 |
|
---|
9271 | <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
|
---|
9272 | </desc>
|
---|
9273 |
|
---|
9274 | <attribute name="name" type="wstring">
|
---|
9275 | <desc>
|
---|
9276 | Visible name for this filter.
|
---|
9277 | This name is used to visually distungish one filter from another,
|
---|
9278 | so it can neither be <tt>null</tt> nor an empty string.
|
---|
9279 | </desc>
|
---|
9280 | </attribute>
|
---|
9281 |
|
---|
9282 | <attribute name="active" type="boolean">
|
---|
9283 | <desc>Whether this filter active or has been temporarily disabled.</desc>
|
---|
9284 | </attribute>
|
---|
9285 |
|
---|
9286 | <attribute name="vendorId" type="wstring">
|
---|
9287 | <desc>
|
---|
9288 | <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
|
---|
9289 | The string representation for the <i>exact matching</i>
|
---|
9290 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
9291 | (including leading zeroes).
|
---|
9292 | </desc>
|
---|
9293 | </attribute>
|
---|
9294 |
|
---|
9295 | <attribute name="productId" type="wstring">
|
---|
9296 | <desc>
|
---|
9297 | <link to="IUSBDevice::productId">Product ID</link> filter.
|
---|
9298 | The string representation for the <i>exact matching</i>
|
---|
9299 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
9300 | (including leading zeroes).
|
---|
9301 | </desc>
|
---|
9302 | </attribute>
|
---|
9303 |
|
---|
9304 | <attribute name="revision" type="wstring">
|
---|
9305 | <desc>
|
---|
9306 | <link to="IUSBDevice::productId">Product revision number</link>
|
---|
9307 | filter. The string representation for the <i>exact matching</i>
|
---|
9308 | has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
|
---|
9309 | of the integer part of the revision, and <tt>F</tt> is the
|
---|
9310 | decimal digit of its fractional part (including leading and
|
---|
9311 | trailing zeroes).
|
---|
9312 | Note that for interval filters, it's best to use the hexadecimal
|
---|
9313 | form, because the revision is stored as a 16 bit packed BCD value;
|
---|
9314 | so the expression <tt>int:0x0100-0x0199</tt> will match any
|
---|
9315 | revision from <tt>1.0</tt> to <tt>1.99</tt>.
|
---|
9316 | </desc>
|
---|
9317 | </attribute>
|
---|
9318 |
|
---|
9319 | <attribute name="manufacturer" type="wstring">
|
---|
9320 | <desc>
|
---|
9321 | <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
|
---|
9322 | </desc>
|
---|
9323 | </attribute>
|
---|
9324 |
|
---|
9325 | <attribute name="product" type="wstring">
|
---|
9326 | <desc>
|
---|
9327 | <link to="IUSBDevice::product">Product</link> filter.
|
---|
9328 | </desc>
|
---|
9329 | </attribute>
|
---|
9330 |
|
---|
9331 | <attribute name="serialNumber" type="wstring">
|
---|
9332 | <desc>
|
---|
9333 | <link to="IUSBDevice::serialNumber">Serial number</link> filter.
|
---|
9334 | </desc>
|
---|
9335 | </attribute>
|
---|
9336 |
|
---|
9337 | <attribute name="port" type="wstring">
|
---|
9338 | <desc>
|
---|
9339 | <link to="IUSBDevice::port">Host USB port</link> filter.
|
---|
9340 | </desc>
|
---|
9341 | </attribute>
|
---|
9342 |
|
---|
9343 | <attribute name="remote" type="wstring">
|
---|
9344 | <desc>
|
---|
9345 | <link to="IUSBDevice::remote">Remote state</link> filter.
|
---|
9346 | <note>
|
---|
9347 | This filter makes sense only for machine USB filters,
|
---|
9348 | i.e. it is ignored by IHostUSBDeviceFilter objects.
|
---|
9349 | </note>
|
---|
9350 | </desc>
|
---|
9351 | </attribute>
|
---|
9352 |
|
---|
9353 | <attribute name="maskedInterfaces" type="unsigned long">
|
---|
9354 | <desc>
|
---|
9355 | This is an advanced option for hiding one or more USB interfaces
|
---|
9356 | from the guest. The value is a bitmask where the bits that are set
|
---|
9357 | means the corresponding USB interface should be hidden, masked off
|
---|
9358 | if you like.
|
---|
9359 | This feature only works on Linux hosts.
|
---|
9360 | </desc>
|
---|
9361 | </attribute>
|
---|
9362 |
|
---|
9363 | </interface>
|
---|
9364 |
|
---|
9365 |
|
---|
9366 | <!--
|
---|
9367 | // IHostUSBDevice
|
---|
9368 | /////////////////////////////////////////////////////////////////////////
|
---|
9369 | -->
|
---|
9370 |
|
---|
9371 | <enum
|
---|
9372 | name="USBDeviceState"
|
---|
9373 | uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
|
---|
9374 | >
|
---|
9375 | <desc>
|
---|
9376 | USB device state. This enumeration represents all possible states
|
---|
9377 | of the USB device physically attached to the host computer regarding
|
---|
9378 | its state on the host computer and availability to guest computers
|
---|
9379 | (all currently running virtual machines).
|
---|
9380 |
|
---|
9381 | Once a supported USB device is attached to the host, global USB
|
---|
9382 | filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
|
---|
9383 | either ignore the device, or put ot to #Held state, or do nothing. Unless
|
---|
9384 | the device is ignored by global filters, filters of all currently running
|
---|
9385 | guests (<link to="IUSBController::deviceFilters"/>) are activated that can
|
---|
9386 | put it to #Captured state.
|
---|
9387 |
|
---|
9388 | If the device was ignored by global filters, or didn't match
|
---|
9389 | any filters at all (including guest ones), it is handled by the host
|
---|
9390 | in a normal way. In this case, the device state is determined by
|
---|
9391 | the host and can be one of #Unavailable, #Busy or #Available, depending on
|
---|
9392 | the current device usage.
|
---|
9393 |
|
---|
9394 | Besides auto-capturing based on filters, the device can be manually
|
---|
9395 | captured by guests (<link to="IConsole::attachUSBDevice()"/>) if its
|
---|
9396 | state is #Busy, #Available or #Held.
|
---|
9397 |
|
---|
9398 | <note>
|
---|
9399 | Due to differences in USB stack implementations in Linux and Win32,
|
---|
9400 | states #Busy and #Available are applicable only to the Linux version of
|
---|
9401 | the product. This also means that (<link
|
---|
9402 | to="IConsole::attachUSBDevice()"/>) can only succeed on Win32 if
|
---|
9403 | the device state is #Held.
|
---|
9404 | </note>
|
---|
9405 |
|
---|
9406 | <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
|
---|
9407 | </desc>
|
---|
9408 |
|
---|
9409 | <const name="NotSupported" value="0">
|
---|
9410 | <desc>
|
---|
9411 | Not supported by the VirtualBox server, not available to guests.
|
---|
9412 | </desc>
|
---|
9413 | </const>
|
---|
9414 | <const name="Unavailable" value="1">
|
---|
9415 | <desc>
|
---|
9416 | Being used by the host computer exclusively,
|
---|
9417 | not available to guests.
|
---|
9418 | </desc>
|
---|
9419 | </const>
|
---|
9420 | <const name="Busy" value="2">
|
---|
9421 | <desc>
|
---|
9422 | Being used by the host computer, potentially available to guests.
|
---|
9423 | </desc>
|
---|
9424 | </const>
|
---|
9425 | <const name="Available" value="3">
|
---|
9426 | <desc>
|
---|
9427 | Not used by the host computer, available to guests.
|
---|
9428 | The host computer can also start using the device at any time.
|
---|
9429 | </desc>
|
---|
9430 | </const>
|
---|
9431 | <const name="Held" value="4">
|
---|
9432 | <desc>
|
---|
9433 | Held by the VirtualBox server (ignored by the host computer),
|
---|
9434 | available to guests.
|
---|
9435 | </desc>
|
---|
9436 | </const>
|
---|
9437 | <const name="Captured" value="5">
|
---|
9438 | <desc>
|
---|
9439 | Captured by one of the guest computers, not available
|
---|
9440 | to anybody else.
|
---|
9441 | </desc>
|
---|
9442 | </const>
|
---|
9443 | </enum>
|
---|
9444 |
|
---|
9445 | <enumerator
|
---|
9446 | name="IHostUSBDeviceEnumerator" type="IHostUSBDevice"
|
---|
9447 | uuid="a0c55136-939f-4d20-b9d3-4d406f08bfa5"
|
---|
9448 | />
|
---|
9449 |
|
---|
9450 | <collection
|
---|
9451 | name="IHostUSBDeviceCollection" type="IHostUSBDevice"
|
---|
9452 | enumerator="IHostUSBDeviceEnumerator"
|
---|
9453 | uuid="f9d3f96d-b027-4994-b589-70bb9ee0d364"
|
---|
9454 | readonly="yes"
|
---|
9455 | >
|
---|
9456 | <method name="findById">
|
---|
9457 | <desc>
|
---|
9458 | Searches this collection for a USB device with the given UUID.
|
---|
9459 | <note>
|
---|
9460 | The method returns an error if the given UUID does not
|
---|
9461 | correspond to any USB device in the collection.
|
---|
9462 | </note>
|
---|
9463 | <see>IHostUSBDevice::id</see>
|
---|
9464 | </desc>
|
---|
9465 | <param name="id" type="uuid" dir="in">
|
---|
9466 | <desc>UUID of the USB device to search for.</desc>
|
---|
9467 | </param>
|
---|
9468 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
9469 | <desc>Found USB device object.</desc>
|
---|
9470 | </param>
|
---|
9471 | </method>
|
---|
9472 |
|
---|
9473 | <method name="findByAddress">
|
---|
9474 | <desc>
|
---|
9475 | Searches this collection for a USB device with the given
|
---|
9476 | host address.
|
---|
9477 | <note>
|
---|
9478 | The method returns an error if the given address does not
|
---|
9479 | correspond to any USB device in the collection.
|
---|
9480 | </note>
|
---|
9481 | <see>IHostUSBDevice::address</see>
|
---|
9482 | </desc>
|
---|
9483 | <param name="name" type="wstring" dir="in">
|
---|
9484 | <desc>
|
---|
9485 | Address of the USB device (as assigned by the host) to
|
---|
9486 | search for.
|
---|
9487 | </desc>
|
---|
9488 | </param>
|
---|
9489 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
9490 | <desc>Found USB device object.</desc>
|
---|
9491 | </param>
|
---|
9492 | </method>
|
---|
9493 |
|
---|
9494 | </collection>
|
---|
9495 |
|
---|
9496 | <interface
|
---|
9497 | name="IHostUSBDevice" extends="IUSBDevice"
|
---|
9498 | uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
|
---|
9499 | wsmap="managed"
|
---|
9500 | >
|
---|
9501 | <desc>
|
---|
9502 | The IHostUSBDevice interface represents a physical USB device attached
|
---|
9503 | to the host computer.
|
---|
9504 |
|
---|
9505 | Besides properties inherited from IUSBDevice, this interface adds the
|
---|
9506 | <link to="#state"/> property that holds the courrent state of the USB
|
---|
9507 | device.
|
---|
9508 |
|
---|
9509 | <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
|
---|
9510 | </desc>
|
---|
9511 |
|
---|
9512 | <attribute name="state" type="USBDeviceState" readonly="yes">
|
---|
9513 | <desc>
|
---|
9514 | Current state of the device.
|
---|
9515 | </desc>
|
---|
9516 | </attribute>
|
---|
9517 |
|
---|
9518 | <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
|
---|
9519 |
|
---|
9520 | </interface>
|
---|
9521 |
|
---|
9522 |
|
---|
9523 | <!--
|
---|
9524 | // IHostUSBDeviceFilter
|
---|
9525 | /////////////////////////////////////////////////////////////////////////
|
---|
9526 | -->
|
---|
9527 |
|
---|
9528 | <enum
|
---|
9529 | name="USBDeviceFilterAction"
|
---|
9530 | uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
|
---|
9531 | >
|
---|
9532 | <desc>
|
---|
9533 | Actions for host USB device filters.
|
---|
9534 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
9535 | </desc>
|
---|
9536 |
|
---|
9537 | <const name="Null" value="0">
|
---|
9538 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
9539 | </const>
|
---|
9540 | <const name="Ignore" value="1">
|
---|
9541 | <desc>Ignore the matched USB device.</desc>
|
---|
9542 | </const>
|
---|
9543 | <const name="Hold" value="2">
|
---|
9544 | <desc>Hold the matched USB device.</desc>
|
---|
9545 | </const>
|
---|
9546 | </enum>
|
---|
9547 |
|
---|
9548 | <enumerator
|
---|
9549 | name="IHostUSBDeviceFilterEnumerator" type="IHostUSBDeviceFilter"
|
---|
9550 | uuid="ff735211-903e-4642-9c37-189eb44579fe"
|
---|
9551 | />
|
---|
9552 |
|
---|
9553 | <collection
|
---|
9554 | name="IHostUSBDeviceFilterCollection" type="IHostUSBDeviceFilter"
|
---|
9555 | enumerator="IHostUSBDeviceFilterEnumerator"
|
---|
9556 | uuid="1a80458b-87f1-4a74-995d-04e2330119e0"
|
---|
9557 | readonly="yes"
|
---|
9558 | />
|
---|
9559 |
|
---|
9560 | <interface
|
---|
9561 | name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
|
---|
9562 | uuid="4cc70246-d74a-400f-8222-3900489c0374"
|
---|
9563 | wsmap="managed"
|
---|
9564 | >
|
---|
9565 | <desc>
|
---|
9566 | The IHostUSBDeviceFilter interface represents a global filter for a
|
---|
9567 | physical USB device used by the host computer. Used indirectly in
|
---|
9568 | <link to="IHost::USBDeviceFilters"/>.
|
---|
9569 |
|
---|
9570 | Using filters of this type, the host computer determines the initial
|
---|
9571 | state of the USB device after it is physically attached to the
|
---|
9572 | host's USB controller.
|
---|
9573 |
|
---|
9574 | <note>
|
---|
9575 | The <link to="#remote"/> attribute is ignored by this type of
|
---|
9576 | filters, because it makes sense only for
|
---|
9577 | <link to="IUSBController::deviceFilters">machine USB filters</link>.
|
---|
9578 | </note>
|
---|
9579 |
|
---|
9580 | <see>IHost::USBDeviceFilters</see>
|
---|
9581 | </desc>
|
---|
9582 |
|
---|
9583 | <attribute name="action" type="USBDeviceFilterAction">
|
---|
9584 | <desc>
|
---|
9585 | Action performed by the host when an attached USB device
|
---|
9586 | matches this filter.
|
---|
9587 | </desc>
|
---|
9588 | </attribute>
|
---|
9589 |
|
---|
9590 | </interface>
|
---|
9591 |
|
---|
9592 | <!--
|
---|
9593 | // IAudioAdapter
|
---|
9594 | /////////////////////////////////////////////////////////////////////////
|
---|
9595 | -->
|
---|
9596 |
|
---|
9597 | <enum
|
---|
9598 | name="AudioDriverType"
|
---|
9599 | uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
|
---|
9600 | >
|
---|
9601 | <desc>
|
---|
9602 | Host audio driver type.
|
---|
9603 | </desc>
|
---|
9604 |
|
---|
9605 | <const name="Null" value="0">
|
---|
9606 | <desc><tt>null</tt> value. Also means "dummy audio driver".</desc>
|
---|
9607 | </const>
|
---|
9608 | <const name="WinMM" value="1"/>
|
---|
9609 | <const name="OSS" value="2"/>
|
---|
9610 | <const name="ALSA" value="3"/>
|
---|
9611 | <const name="DirectSound" value="4"/>
|
---|
9612 | <const name="CoreAudio" value="5"/>
|
---|
9613 | <const name="MMPM" value="6"/>
|
---|
9614 | <const name="Pulse" value="7"/>
|
---|
9615 | <const name="SolAudio" value="8"/>
|
---|
9616 | </enum>
|
---|
9617 |
|
---|
9618 | <enum
|
---|
9619 | name="AudioControllerType"
|
---|
9620 | uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
|
---|
9621 | >
|
---|
9622 | <desc>
|
---|
9623 | Virtual audio controller type.
|
---|
9624 | </desc>
|
---|
9625 |
|
---|
9626 | <const name="AC97" value="0"/>
|
---|
9627 | <const name="SB16" value="1"/>
|
---|
9628 | </enum>
|
---|
9629 |
|
---|
9630 | <interface
|
---|
9631 | name="IAudioAdapter" extends="$unknown"
|
---|
9632 | uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
|
---|
9633 | wsmap="managed"
|
---|
9634 | >
|
---|
9635 | <desc>
|
---|
9636 | The IAudioAdapter interface represents the virtual audio adapter of
|
---|
9637 | the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
|
---|
9638 | </desc>
|
---|
9639 | <attribute name="enabled" type="boolean">
|
---|
9640 | <desc>
|
---|
9641 | Flag whether the audio adapter is present in the
|
---|
9642 | guest system. If disabled, the virtual guest hardware will
|
---|
9643 | not contain any audio adapter. Can only be changed when
|
---|
9644 | the VM is not running.
|
---|
9645 | </desc>
|
---|
9646 | </attribute>
|
---|
9647 | <attribute name="audioController" type="AudioControllerType">
|
---|
9648 | <desc>
|
---|
9649 | The audio hardware we emulate.
|
---|
9650 | </desc>
|
---|
9651 | </attribute>
|
---|
9652 | <attribute name="audioDriver" type="AudioDriverType">
|
---|
9653 | <desc>
|
---|
9654 | Audio driver the adapter is connected to. This setting
|
---|
9655 | can only be changed when the VM is not running.
|
---|
9656 | </desc>
|
---|
9657 | </attribute>
|
---|
9658 | </interface>
|
---|
9659 |
|
---|
9660 | <!--
|
---|
9661 | // IVRDPServer
|
---|
9662 | /////////////////////////////////////////////////////////////////////////
|
---|
9663 | -->
|
---|
9664 |
|
---|
9665 | <enum
|
---|
9666 | name="VRDPAuthType"
|
---|
9667 | uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
|
---|
9668 | >
|
---|
9669 | <desc>
|
---|
9670 | VRDP authentication type.
|
---|
9671 | </desc>
|
---|
9672 |
|
---|
9673 | <const name="Null" value="0">
|
---|
9674 | <desc><tt>null</tt> value. Also means "no authentication".</desc>
|
---|
9675 | </const>
|
---|
9676 | <const name="External" value="1"/>
|
---|
9677 | <const name="Guest" value="2"/>
|
---|
9678 | </enum>
|
---|
9679 |
|
---|
9680 | <interface
|
---|
9681 | name="IVRDPServer" extends="$unknown"
|
---|
9682 | uuid="ed9d31ae-867f-45fc-b727-6740084d1883"
|
---|
9683 | wsmap="managed"
|
---|
9684 | >
|
---|
9685 | <attribute name="enabled" type="boolean">
|
---|
9686 | <desc>VRDP server status.</desc>
|
---|
9687 | </attribute>
|
---|
9688 |
|
---|
9689 | <attribute name="port" type="unsigned long">
|
---|
9690 | <desc>
|
---|
9691 | VRDP server port number.
|
---|
9692 | <note>
|
---|
9693 | Setting the value of this property to <tt>0</tt> will reset the port
|
---|
9694 | number to the default value which is
|
---|
9695 | currently <tt>3389</tt>. Reading this property will always return a
|
---|
9696 | real port number, even after it has been set to <tt>0</tt> (in which
|
---|
9697 | case the default port is returned).
|
---|
9698 | </note>
|
---|
9699 | </desc>
|
---|
9700 | </attribute>
|
---|
9701 |
|
---|
9702 | <attribute name="netAddress" type="wstring">
|
---|
9703 | <desc>VRDP server address.</desc>
|
---|
9704 | </attribute>
|
---|
9705 |
|
---|
9706 | <attribute name="authType" type="VRDPAuthType">
|
---|
9707 | <desc>VRDP authentication method.</desc>
|
---|
9708 | </attribute>
|
---|
9709 |
|
---|
9710 | <attribute name="authTimeout" type="unsigned long">
|
---|
9711 | <desc>Timeout for guest authentication. Milliseconds.</desc>
|
---|
9712 | </attribute>
|
---|
9713 |
|
---|
9714 | <attribute name="allowMultiConnection" type="boolean">
|
---|
9715 | <desc>
|
---|
9716 | Flag whether multiple simultaneous connections to the VM are permitted.
|
---|
9717 | Note that this will be replaced by a more powerful mechanism in the future.
|
---|
9718 | </desc>
|
---|
9719 | </attribute>
|
---|
9720 |
|
---|
9721 | </interface>
|
---|
9722 |
|
---|
9723 |
|
---|
9724 | <!--
|
---|
9725 | // ISharedFolder
|
---|
9726 | /////////////////////////////////////////////////////////////////////////
|
---|
9727 | -->
|
---|
9728 |
|
---|
9729 | <enumerator
|
---|
9730 | name="ISharedFolderEnumerator" type="ISharedFolder"
|
---|
9731 | uuid="1d420fd8-e7c1-4511-abf4-a504dc6d0cbf"
|
---|
9732 | />
|
---|
9733 |
|
---|
9734 | <collection
|
---|
9735 | name="ISharedFolderCollection" type="ISharedFolder"
|
---|
9736 | enumerator="ISharedFolderEnumerator"
|
---|
9737 | uuid="9c7e2282-bb16-4fa7-9138-f383c5e02353"
|
---|
9738 | readonly="yes">
|
---|
9739 |
|
---|
9740 | <method name="findByName">
|
---|
9741 | <desc>
|
---|
9742 | Searches this collection for a shared folder with the given logical
|
---|
9743 | name.
|
---|
9744 | <note>
|
---|
9745 | The method returns an error if the given name does not correspond to
|
---|
9746 | any shared folder in the collection.
|
---|
9747 | </note>
|
---|
9748 | </desc>
|
---|
9749 | <param name="name" type="wstring" dir="in">
|
---|
9750 | <desc>Logical name of the shared folder to search for</desc>
|
---|
9751 | </param>
|
---|
9752 | <param name="sharedFolder" type="ISharedFolder" dir="return">
|
---|
9753 | <desc>Found shared folder object</desc>
|
---|
9754 | </param>
|
---|
9755 | </method>
|
---|
9756 |
|
---|
9757 | </collection>
|
---|
9758 |
|
---|
9759 | <interface
|
---|
9760 | name="ISharedFolder" extends="$unknown"
|
---|
9761 | uuid="8b0c5f70-9139-4f97-a421-64d5e9c335d5"
|
---|
9762 | wsmap="struct"
|
---|
9763 | >
|
---|
9764 | <desc>
|
---|
9765 | The ISharedFolder interface represents a folder in the host computer's
|
---|
9766 | file system accessible from the guest OS running inside a virtual
|
---|
9767 | machine using an associated logical name.
|
---|
9768 |
|
---|
9769 | There are three types of shared folders:
|
---|
9770 | <ul>
|
---|
9771 | <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
|
---|
9772 | folders available to all virtual machines.</li>
|
---|
9773 | <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
|
---|
9774 | VM-specific shared folders available to the given virtual machine at
|
---|
9775 | startup.</li>
|
---|
9776 | <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
|
---|
9777 | VM-specific shared folders created in the session context (for
|
---|
9778 | example, when the virtual machine is running) and automatically
|
---|
9779 | discarded when the session is closed (the VM is powered off).</li>
|
---|
9780 | </ul>
|
---|
9781 |
|
---|
9782 | Logical names of shared folders must be unique within the given scope
|
---|
9783 | (global, permanent or transient). However, they do not need to be unique
|
---|
9784 | across scopes. In this case, the definitioin of the shared folder in a
|
---|
9785 | more specific scope takes precedence over definitions in all other
|
---|
9786 | scopes. The order of precedence is (more specific to more general):
|
---|
9787 | <ol>
|
---|
9788 | <li>Transient definitions</li>
|
---|
9789 | <li>Permanent definitions</li>
|
---|
9790 | <li>Global definitions</li>
|
---|
9791 | </ol>
|
---|
9792 |
|
---|
9793 | For example, if MyMachine has a shared folder named
|
---|
9794 | <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then cretaing a
|
---|
9795 | transient shared folder named <tt>C_DRIVE</tt> (that points
|
---|
9796 | to <tt>C:\\\\WINDOWS</tt>) will change the definition
|
---|
9797 | of <tt>C_DRIVE</tt> in the guest OS so
|
---|
9798 | that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
|
---|
9799 | to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
|
---|
9800 | PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
|
---|
9801 | the prevoious (permanent) definition of <tt>C_DRIVE</tt> that points
|
---|
9802 | to <tt>C:\\</tt> if it still exists.
|
---|
9803 |
|
---|
9804 | Note that permanent and transient shared folders of different machines
|
---|
9805 | are in different name spaces, so they don't overlap and don't need to
|
---|
9806 | have unique logical names.
|
---|
9807 |
|
---|
9808 | <note>
|
---|
9809 | Global shared folders are not implemented in the current vesion of the
|
---|
9810 | product.
|
---|
9811 | </note>
|
---|
9812 | </desc>
|
---|
9813 |
|
---|
9814 | <attribute name="name" type="wstring" readonly="yes">
|
---|
9815 | <desc>Logical name of the shared folder.</desc>
|
---|
9816 | </attribute>
|
---|
9817 |
|
---|
9818 | <attribute name="hostPath" type="wstring" readonly="yes">
|
---|
9819 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
9820 | </attribute>
|
---|
9821 |
|
---|
9822 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
9823 | <desc>
|
---|
9824 | Whether the folder defined by the host path is currently
|
---|
9825 | accessible or not.
|
---|
9826 | For example, the folder can be unaccessible if it is placed
|
---|
9827 | on the network share that is not available by the time
|
---|
9828 | this property is read.
|
---|
9829 | </desc>
|
---|
9830 | </attribute>
|
---|
9831 |
|
---|
9832 | <attribute name="writable" type="boolean" readonly="yes">
|
---|
9833 | <desc>
|
---|
9834 | Whether the folder defined by the host path is writable or
|
---|
9835 | not.
|
---|
9836 | </desc>
|
---|
9837 | </attribute>
|
---|
9838 |
|
---|
9839 | </interface>
|
---|
9840 |
|
---|
9841 | <!--
|
---|
9842 | // ISession
|
---|
9843 | /////////////////////////////////////////////////////////////////////////
|
---|
9844 | -->
|
---|
9845 |
|
---|
9846 | <interface
|
---|
9847 | name="IInternalSessionControl" extends="$unknown"
|
---|
9848 | uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
|
---|
9849 | internal="yes"
|
---|
9850 | wsmap="suppress"
|
---|
9851 | >
|
---|
9852 | <method name="getPID">
|
---|
9853 | <desc>PID of the process that has created this Session object.
|
---|
9854 | </desc>
|
---|
9855 | <param name="pid" type="unsigned long" dir="return"/>
|
---|
9856 | </method>
|
---|
9857 |
|
---|
9858 | <method name="getRemoteConsole">
|
---|
9859 | <desc>Returns the console object suitable for remote control.</desc>
|
---|
9860 | <param name="console" type="IConsole" dir="return"/>
|
---|
9861 | </method>
|
---|
9862 |
|
---|
9863 | <method name="assignMachine">
|
---|
9864 | <desc>
|
---|
9865 | Assigns the machine object associated with this direct-type
|
---|
9866 | session or informs the session that it will be a remote one
|
---|
9867 | (if machine = NULL).
|
---|
9868 | </desc>
|
---|
9869 | <param name="machine" type="IMachine" dir="in"/>
|
---|
9870 | </method>
|
---|
9871 |
|
---|
9872 | <method name="assignRemoteMachine">
|
---|
9873 | <desc>
|
---|
9874 | Assigns the machine and the (remote) console object associated with
|
---|
9875 | this remote-type session.
|
---|
9876 | </desc>
|
---|
9877 | <param name="machine" type="IMachine" dir="in"/>
|
---|
9878 | <param name="console" type="IConsole" dir="in"/>
|
---|
9879 | </method>
|
---|
9880 |
|
---|
9881 | <method name="updateMachineState">
|
---|
9882 | <desc>
|
---|
9883 | Updates the machine state in the VM process.
|
---|
9884 | Must be called only in certain cases
|
---|
9885 | (see the method implementation).
|
---|
9886 | </desc>
|
---|
9887 | <param name="aMachineState" type="MachineState" dir="in"/>
|
---|
9888 | </method>
|
---|
9889 |
|
---|
9890 | <method name="uninitialize">
|
---|
9891 | <desc>
|
---|
9892 | Uninitializes (closes) this session. Used by VirtualBox to close
|
---|
9893 | the corresponding remote session when the direct session dies
|
---|
9894 | or gets closed.
|
---|
9895 | </desc>
|
---|
9896 | </method>
|
---|
9897 |
|
---|
9898 | <method name="onDVDDriveChange">
|
---|
9899 | <desc>
|
---|
9900 | Triggered when settings of the DVD drive object of the
|
---|
9901 | associated virtual machine have changed.
|
---|
9902 | </desc>
|
---|
9903 | </method>
|
---|
9904 |
|
---|
9905 | <method name="onFloppyDriveChange">
|
---|
9906 | <desc>
|
---|
9907 | Triggered when settings of the floppy drive object of the
|
---|
9908 | associated virtual machine have changed.
|
---|
9909 | </desc>
|
---|
9910 | </method>
|
---|
9911 |
|
---|
9912 | <method name="onNetworkAdapterChange">
|
---|
9913 | <desc>
|
---|
9914 | Triggered when settings of a network adapter of the
|
---|
9915 | associated virtual machine have changed.
|
---|
9916 | </desc>
|
---|
9917 | <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
|
---|
9918 | </method>
|
---|
9919 |
|
---|
9920 | <method name="onSerialPortChange">
|
---|
9921 | <desc>
|
---|
9922 | Triggered when settions of a serial port of the
|
---|
9923 | associated virtual machine have changed.
|
---|
9924 | </desc>
|
---|
9925 | <param name="serialPort" type="ISerialPort" dir="in"/>
|
---|
9926 | </method>
|
---|
9927 |
|
---|
9928 | <method name="onParallelPortChange">
|
---|
9929 | <desc>
|
---|
9930 | Triggered when settings of a parallel port of the
|
---|
9931 | associated virtual machine have changed.
|
---|
9932 | </desc>
|
---|
9933 | <param name="parallelPort" type="IParallelPort" dir="in"/>
|
---|
9934 | </method>
|
---|
9935 |
|
---|
9936 | <method name="onVRDPServerChange">
|
---|
9937 | <desc>
|
---|
9938 | Triggered when settings of the VRDP server object of the
|
---|
9939 | associated virtual machine have changed.
|
---|
9940 | </desc>
|
---|
9941 | </method>
|
---|
9942 |
|
---|
9943 | <method name="onUSBControllerChange">
|
---|
9944 | <desc>
|
---|
9945 | Triggered when settings of the USB controller object of the
|
---|
9946 | associated virtual machine have changed.
|
---|
9947 | </desc>
|
---|
9948 | </method>
|
---|
9949 |
|
---|
9950 | <method name="onSharedFolderChange">
|
---|
9951 | <desc>
|
---|
9952 | Triggered when a permanent (global or machine) shared folder has been
|
---|
9953 | created or removed.
|
---|
9954 | <note>
|
---|
9955 | We don't pass shared folder parameters in this notification because
|
---|
9956 | the order in which parallel notifications are delivered is not defined,
|
---|
9957 | therefore it could happen that these parameters were outdated by the
|
---|
9958 | time of processing this notification.
|
---|
9959 | </note>
|
---|
9960 | </desc>
|
---|
9961 | <param name="global" type="boolean" dir="in"/>
|
---|
9962 | </method>
|
---|
9963 |
|
---|
9964 | <method name="onUSBDeviceAttach">
|
---|
9965 | <desc>
|
---|
9966 | Triggered when a request to capture a USB device (as a result
|
---|
9967 | of matched USB filters or direct call to
|
---|
9968 | <link to="IConsole::attachUSBDevice"/>) has completed.
|
---|
9969 | A @c null @a error object means success, otherwise it
|
---|
9970 | describes a failure.
|
---|
9971 | </desc>
|
---|
9972 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
9973 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
9974 | <param name="maskedInterfaces" type="unsigned long" dir="in"/>
|
---|
9975 | </method>
|
---|
9976 |
|
---|
9977 | <method name="onUSBDeviceDetach">
|
---|
9978 | <desc>
|
---|
9979 | Triggered when a request to release the USB device (as a result
|
---|
9980 | of machine termination or direct call to
|
---|
9981 | <link to="IConsole::detachUSBDevice"/>) has completed.
|
---|
9982 | A @c null @a error object means success, otherwise it
|
---|
9983 | </desc>
|
---|
9984 | <param name="id" type="uuid" dir="in"/>
|
---|
9985 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
9986 | </method>
|
---|
9987 |
|
---|
9988 | <method name="onShowWindow">
|
---|
9989 | <desc>
|
---|
9990 | Called by <link to="IMachine::canShowConsoleWindow()"/> and by
|
---|
9991 | <link to="IMachine::showConsoleWindow()"/> in order to notify
|
---|
9992 | console callbacks
|
---|
9993 | <link to="IConsoleCallback::onCanShowWindow()"/>
|
---|
9994 | and <link to="IConsoleCallback::onShowWindow()"/>.
|
---|
9995 | </desc>
|
---|
9996 | <param name="check" type="boolean" dir="in"/>
|
---|
9997 | <param name="canShow" type="boolean" dir="out"/>
|
---|
9998 | <param name="winId" type="unsigned long long" dir="out"/>
|
---|
9999 | </method>
|
---|
10000 |
|
---|
10001 | <method name="accessGuestProperty">
|
---|
10002 | <desc>
|
---|
10003 | Called by <link to="IMachine::getGuestProperty()"/> and by
|
---|
10004 | <link to="IMachine::setGuestProperty()"/> in order to read and
|
---|
10005 | modify guest properties.
|
---|
10006 | </desc>
|
---|
10007 | <param name="name" type="wstring" dir="in"/>
|
---|
10008 | <param name="value" type="wstring" dir="in"/>
|
---|
10009 | <param name="flags" type="wstring" dir="in"/>
|
---|
10010 | <param name="isSetter" type="boolean" dir="in"/>
|
---|
10011 | <param name="retValue" type="wstring" dir="out"/>
|
---|
10012 | <param name="retTimestamp" type="unsigned long long" dir="out"/>
|
---|
10013 | <param name="retFlags" type="wstring" dir="out"/>
|
---|
10014 | </method>
|
---|
10015 |
|
---|
10016 | <method name="enumerateGuestProperties">
|
---|
10017 | <desc>
|
---|
10018 | Return a list of the guest properties matching a set of patterns along
|
---|
10019 | with their values, timestamps and flags.
|
---|
10020 | </desc>
|
---|
10021 | <param name="patterns" type="wstring" dir="in">
|
---|
10022 | <desc>
|
---|
10023 | The patterns to match the properties against as a comma-separated
|
---|
10024 | string. If this is empty, all properties currently set will be
|
---|
10025 | returned.
|
---|
10026 | </desc>
|
---|
10027 | </param>
|
---|
10028 | <param name="key" type="wstring" dir="out" safearray="yes">
|
---|
10029 | <desc>
|
---|
10030 | The key names of the properties returned.
|
---|
10031 | </desc>
|
---|
10032 | </param>
|
---|
10033 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
10034 | <desc>
|
---|
10035 | The values of the properties returned. The array entries match the
|
---|
10036 | corresponding entries in the @a key array.
|
---|
10037 | </desc>
|
---|
10038 | </param>
|
---|
10039 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
10040 | <desc>
|
---|
10041 | The timestamps of the properties returned. The array entries match
|
---|
10042 | the corresponding entries in the @a key array.
|
---|
10043 | </desc>
|
---|
10044 | </param>
|
---|
10045 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
10046 | <desc>
|
---|
10047 | The flags of the properties returned. The array entries match the
|
---|
10048 | corresponding entries in the @a key array.
|
---|
10049 | </desc>
|
---|
10050 | </param>
|
---|
10051 | </method>
|
---|
10052 |
|
---|
10053 | </interface>
|
---|
10054 |
|
---|
10055 | <interface
|
---|
10056 | name="ISession" extends="$dispatched"
|
---|
10057 | uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
|
---|
10058 | wsmap="managed"
|
---|
10059 | >
|
---|
10060 | <desc>
|
---|
10061 | The ISession interface represents a serialization primitive for virtual
|
---|
10062 | machines.
|
---|
10063 |
|
---|
10064 | Within VirtualBox, every time one wishes to manipulate a virtual machine
|
---|
10065 | (for example, change its settings or start execution), an instance of
|
---|
10066 | the ISession interface is required. One first creates a local session
|
---|
10067 | object that implements the ISession interface and then passes the
|
---|
10068 | created object with the method call that opens the given session and
|
---|
10069 | thus initiates the machine manipulation. The session serves several
|
---|
10070 | purposes: it identifies to the inter-process VirtualBox code which
|
---|
10071 | process is currently working with the virtual machine, and it ensures
|
---|
10072 | that there are no incompatible requests from several processes for the
|
---|
10073 | same virtual machine.
|
---|
10074 |
|
---|
10075 | How sessions objects are used depends on whether you use the Main API
|
---|
10076 | via COM or via the web service:
|
---|
10077 |
|
---|
10078 | <ul>
|
---|
10079 | <li>When using the COM API directly, an object of the Session class from the
|
---|
10080 | VirtualBox type library needs to be created. In regular COM C++ client code,
|
---|
10081 | this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
|
---|
10082 | This object will then act as a local session object in further calls to open
|
---|
10083 | a session.
|
---|
10084 | </li>
|
---|
10085 |
|
---|
10086 | <li>In the webservice, the session manager (IWebsessionManager) instead creates
|
---|
10087 | one session object automatically when <link to="IWebsessionManager::logon" />
|
---|
10088 | is called. A managed object reference to that session object can be retrieved by
|
---|
10089 | calling <link to="IWebsessionManager::getSessionObject" />. This session object
|
---|
10090 | reference can then be used to open sessions.
|
---|
10091 | </li>
|
---|
10092 | </ul>
|
---|
10093 |
|
---|
10094 | Sessions are mainly used in two variations:
|
---|
10095 |
|
---|
10096 | <ul>
|
---|
10097 | <li>
|
---|
10098 | To start a virtual machine in a separate process, one would call
|
---|
10099 | <link to="IVirtualBox::openRemoteSession"/>, which requires a session
|
---|
10100 | object as its first parameter. This session then identifies the caller
|
---|
10101 | and lets him control the started machine (for example, pause machine
|
---|
10102 | execution or power it down) as well as be notified about machine
|
---|
10103 | execution state changes.
|
---|
10104 | </li>
|
---|
10105 |
|
---|
10106 | <li>To alter machine settings, or to start machine execution within the
|
---|
10107 | current process, one needs to open a direct session for the machine first by
|
---|
10108 | calling <link to="IVirtualBox::openSession"/>. While a direct session
|
---|
10109 | is open within one process, no any other process may open another direct
|
---|
10110 | session for the same machine. This prevents the machine from being changed
|
---|
10111 | by other processes while it is running or while the machine is being configured.
|
---|
10112 | </li>
|
---|
10113 | </ul>
|
---|
10114 |
|
---|
10115 | One also can attach to an existing direct session alreay opened by
|
---|
10116 | another process (for example, in order to send a control request to the
|
---|
10117 | virtual machine such as the pause or the reset request). This is done by
|
---|
10118 | calling <link to="IVirtualBox::openExistingSession"/>.
|
---|
10119 |
|
---|
10120 | <note>
|
---|
10121 | Unless you are trying to write a new VirtualBox front-end that
|
---|
10122 | performs direct machine execution (like the VirtualBox or VBoxSDL
|
---|
10123 | front-ends), don't call <link to="IConsole::powerUp"/> in a direct
|
---|
10124 | session opened by <link to="IVirtualBox::openSession"/> and use this
|
---|
10125 | session only to change virtual machine settings. If you simply want to
|
---|
10126 | start virtual machine execution using one of the existing front-ends
|
---|
10127 | (for example the VirtualBox GUI or headless server), simply use
|
---|
10128 | <link to="IVirtualBox::openRemoteSession"/>; these front-ends
|
---|
10129 | will power up the machine automatically for you.
|
---|
10130 | </note>
|
---|
10131 | </desc>
|
---|
10132 |
|
---|
10133 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
10134 | <desc>Current state of this session.</desc>
|
---|
10135 | </attribute>
|
---|
10136 |
|
---|
10137 | <attribute name="type" type="SessionType" readonly="yes">
|
---|
10138 | <desc>
|
---|
10139 | Type of this session. The value of this attribute is valid only
|
---|
10140 | if the session is currently open (i.e. its #state is SessionType::SessionOpen),
|
---|
10141 | otherwise an error will be returned.
|
---|
10142 | </desc>
|
---|
10143 | </attribute>
|
---|
10144 |
|
---|
10145 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
10146 | <desc>Machine object associated with this session.</desc>
|
---|
10147 | </attribute>
|
---|
10148 |
|
---|
10149 | <attribute name="console" type="IConsole" readonly="yes">
|
---|
10150 | <desc>Console object associated with this session.</desc>
|
---|
10151 | </attribute>
|
---|
10152 |
|
---|
10153 | <method name="close">
|
---|
10154 | <desc>
|
---|
10155 | Closes this session.
|
---|
10156 | <note>
|
---|
10157 | If a direct session for a machine opened with
|
---|
10158 | <link to="IVirtualBox::openSession()"/> is not explicitly
|
---|
10159 | closed when the application terminates, the state of the
|
---|
10160 | machine will be set to <link to="MachineState::Aborted"/>
|
---|
10161 | on the server. Generally, it is recommended to close all
|
---|
10162 | open sessions explicitly before terminating the application
|
---|
10163 | (no matter what is the reason of the termination).
|
---|
10164 | </note>
|
---|
10165 | </desc>
|
---|
10166 | </method>
|
---|
10167 |
|
---|
10168 | </interface>
|
---|
10169 |
|
---|
10170 | <!--
|
---|
10171 | // ISATAController
|
---|
10172 | /////////////////////////////////////////////////////////////////////////
|
---|
10173 | -->
|
---|
10174 |
|
---|
10175 | <interface
|
---|
10176 | name="ISATAController" extends="$unknown"
|
---|
10177 | uuid="9a4b868b-1376-4533-8ef5-065b8e8cedff"
|
---|
10178 | wsmap="managed"
|
---|
10179 | >
|
---|
10180 | <attribute name="enabled" type="boolean">
|
---|
10181 | <desc>
|
---|
10182 | Flag whether the SATA controller is present in the
|
---|
10183 | guest system. If disabled, the virtual guest hardware will
|
---|
10184 | not contain any SATA controller. Can only be changed when
|
---|
10185 | the VM is powered off.
|
---|
10186 | </desc>
|
---|
10187 | </attribute>
|
---|
10188 |
|
---|
10189 | <attribute name="portCount" type="unsigned long">
|
---|
10190 | <desc>
|
---|
10191 | The number of usable ports on the sata controller.
|
---|
10192 | It ranges from 1 to 30.
|
---|
10193 | </desc>
|
---|
10194 | </attribute>
|
---|
10195 |
|
---|
10196 | <method name="GetIDEEmulationPort">
|
---|
10197 | <desc>Gets the corresponding port number which is emulated as an IDE device.</desc>
|
---|
10198 | <param name="devicePosition" type="long" dir="in"/>
|
---|
10199 | <param name="portNumber" type="long" dir="return"/>
|
---|
10200 | </method>
|
---|
10201 |
|
---|
10202 | <method name="SetIDEEmulationPort">
|
---|
10203 | <desc>Sets the port number which is emulated as an IDE device.</desc>
|
---|
10204 | <param name="devicePosition" type="long" dir="in"/>
|
---|
10205 | <param name="portNumber" type="long" dir="in"/>
|
---|
10206 | </method>
|
---|
10207 |
|
---|
10208 | </interface>
|
---|
10209 |
|
---|
10210 | <if target="wsdl">
|
---|
10211 |
|
---|
10212 | <!--
|
---|
10213 | // IManagedObjectRef
|
---|
10214 | /////////////////////////////////////////////////////////////////////////
|
---|
10215 | -->
|
---|
10216 |
|
---|
10217 | <interface
|
---|
10218 | name="IManagedObjectRef" extends="$unknown"
|
---|
10219 | uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
|
---|
10220 | internal="yes"
|
---|
10221 | wsmap="managed"
|
---|
10222 | wscpp="hardcoded"
|
---|
10223 | >
|
---|
10224 | <desc>
|
---|
10225 | Managed object reference.
|
---|
10226 |
|
---|
10227 | Only within the webservice, a managed object reference (which is really
|
---|
10228 | an opaque number) allows a webservice client to address an object
|
---|
10229 | that lives in the address space of the webservice server.
|
---|
10230 |
|
---|
10231 | Behind each managed object reference, there is a COM object that lives
|
---|
10232 | in the webservice server's address space. The COM object is not freed
|
---|
10233 | until the managed object reference is released, either by an explicit
|
---|
10234 | call to <link to="IManagedObjectRef::release" /> or by logging off from
|
---|
10235 | the webservice (<link to="IWebsessionManager::logoff" />), which releases
|
---|
10236 | all objects created during the webservice session.
|
---|
10237 |
|
---|
10238 | Whenever a method call of the VirtualBox API returns a COM object, the
|
---|
10239 | webservice representation of that method will instead return a
|
---|
10240 | managed object reference, which can then be used to invoke methods
|
---|
10241 | on that object.
|
---|
10242 | </desc>
|
---|
10243 |
|
---|
10244 | <method name="getInterfaceName">
|
---|
10245 | <desc>
|
---|
10246 | Returns the name of the interface that this managed object represents,
|
---|
10247 | for example, "IMachine", as a string.
|
---|
10248 | </desc>
|
---|
10249 | <param name="return" type="wstring" dir="return"/>
|
---|
10250 | </method>
|
---|
10251 |
|
---|
10252 | <method name="release">
|
---|
10253 | <desc>
|
---|
10254 | Releases this managed object reference and frees the resources that
|
---|
10255 | were allocated for it in the webservice server process. After calling
|
---|
10256 | this method, the identifier of the reference can no longer be used.
|
---|
10257 | </desc>
|
---|
10258 | </method>
|
---|
10259 |
|
---|
10260 | </interface>
|
---|
10261 |
|
---|
10262 | <!--
|
---|
10263 | // IWebsessionManager
|
---|
10264 | /////////////////////////////////////////////////////////////////////////
|
---|
10265 | -->
|
---|
10266 |
|
---|
10267 | <interface
|
---|
10268 | name="IWebsessionManager" extends="$unknown"
|
---|
10269 | uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
|
---|
10270 | internal="yes"
|
---|
10271 | wsmap="global"
|
---|
10272 | wscpp="hardcoded"
|
---|
10273 | >
|
---|
10274 | <desc>
|
---|
10275 | Websession manager. This provides essential services
|
---|
10276 | to webservice clients.
|
---|
10277 | </desc>
|
---|
10278 | <method name="logon">
|
---|
10279 | <desc>
|
---|
10280 | Logs a new client onto the webservice and returns a managed object reference to
|
---|
10281 | the IVirtualBox instance, which the client can then use as a basis to further
|
---|
10282 | queries, since all calls to the VirtualBox API are based on the IVirtualBox
|
---|
10283 | interface, in one way or the other.
|
---|
10284 | </desc>
|
---|
10285 | <param name="username" type="wstring" dir="in"/>
|
---|
10286 | <param name="password" type="wstring" dir="in"/>
|
---|
10287 | <param name="return" type="IVirtualBox" dir="return"/>
|
---|
10288 | </method>
|
---|
10289 |
|
---|
10290 | <method name="getSessionObject">
|
---|
10291 | <desc>
|
---|
10292 | Returns a managed object reference to the internal ISession object that was created
|
---|
10293 | for this web service session when the client logged on.
|
---|
10294 |
|
---|
10295 | <see>ISession</see>
|
---|
10296 | </desc>
|
---|
10297 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
10298 | <param name="return" type="ISession" dir="return"/>
|
---|
10299 | </method>
|
---|
10300 |
|
---|
10301 | <method name="logoff">
|
---|
10302 | <desc>
|
---|
10303 | Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
|
---|
10304 | and destroys all resources associated with the session (most importantly, all
|
---|
10305 | managed objects created in the server while the session was active).
|
---|
10306 | </desc>
|
---|
10307 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
10308 | </method>
|
---|
10309 |
|
---|
10310 | </interface>
|
---|
10311 |
|
---|
10312 | </if>
|
---|
10313 |
|
---|
10314 | <!--
|
---|
10315 | // IPerformanceCollector & friends
|
---|
10316 | /////////////////////////////////////////////////////////////////////////
|
---|
10317 | -->
|
---|
10318 |
|
---|
10319 | <interface
|
---|
10320 | name="IPerformanceMetric" extends="$unknown"
|
---|
10321 | uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
|
---|
10322 | >
|
---|
10323 | <desc>
|
---|
10324 | The IPerformanceMetric interface represents parameters of the given
|
---|
10325 | performance metric.
|
---|
10326 | </desc>
|
---|
10327 |
|
---|
10328 | <attribute name="metricName" type="wstring" readonly="yes">
|
---|
10329 | <desc>
|
---|
10330 | Name of the metric.
|
---|
10331 | </desc>
|
---|
10332 | </attribute>
|
---|
10333 |
|
---|
10334 | <attribute name="object" type="$unknown" readonly="yes">
|
---|
10335 | <desc>
|
---|
10336 | Object this metric belongs to.
|
---|
10337 | </desc>
|
---|
10338 | </attribute>
|
---|
10339 |
|
---|
10340 | <attribute name="description" type="wstring" readonly="yes">
|
---|
10341 | <desc>
|
---|
10342 | Textual description of the metric.
|
---|
10343 | </desc>
|
---|
10344 | </attribute>
|
---|
10345 |
|
---|
10346 | <attribute name="period" type="unsigned long" readonly="yes">
|
---|
10347 | <desc>
|
---|
10348 | Time interval between samples, measured in seconds.
|
---|
10349 | </desc>
|
---|
10350 | </attribute>
|
---|
10351 |
|
---|
10352 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
10353 | <desc>
|
---|
10354 | Number of recent samples retained by the performance collector for this
|
---|
10355 | metric.
|
---|
10356 |
|
---|
10357 | When the collected sample count exceeds this number, older samples
|
---|
10358 | are discarded.
|
---|
10359 | </desc>
|
---|
10360 | </attribute>
|
---|
10361 |
|
---|
10362 | <attribute name="unit" type="wstring" readonly="yes">
|
---|
10363 | <desc>
|
---|
10364 | Unit of measurement.
|
---|
10365 | </desc>
|
---|
10366 | </attribute>
|
---|
10367 |
|
---|
10368 | <attribute name="minimumValue" type="long" readonly="yes">
|
---|
10369 | <desc>
|
---|
10370 | Minimum possible value of this metric.
|
---|
10371 | </desc>
|
---|
10372 | </attribute>
|
---|
10373 |
|
---|
10374 | <attribute name="maximumValue" type="long" readonly="yes">
|
---|
10375 | <desc>
|
---|
10376 | Maximum possible value of this metric.
|
---|
10377 | </desc>
|
---|
10378 | </attribute>
|
---|
10379 | </interface>
|
---|
10380 |
|
---|
10381 | <interface
|
---|
10382 | name="IPerformanceCollector" extends="$unknown"
|
---|
10383 | uuid="dcd37e5a-3964-43d1-be30-0f3c7234e347"
|
---|
10384 | wsmap="managed"
|
---|
10385 | >
|
---|
10386 | <desc>
|
---|
10387 | The IPerformanceCollector interface represents a service that collects and
|
---|
10388 | stores performance metrics data.
|
---|
10389 |
|
---|
10390 | Performance metrics are associated with objects like IHost and
|
---|
10391 | IMachine. Each object has a distinct set of performance metrics.
|
---|
10392 | The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
|
---|
10393 |
|
---|
10394 | Metric data are collected at the specified intervals and are retained
|
---|
10395 | internally. The interval and the number of samples retained can be set
|
---|
10396 | with <link to="IPerformanceCollector::setMetrics" />.
|
---|
10397 |
|
---|
10398 | Metrics are organized hierarchically, each level separated by slash (/).
|
---|
10399 | General scheme for metric name is
|
---|
10400 | "Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
|
---|
10401 | metric name stands for: CPU category, Load metric, User submetric, average
|
---|
10402 | aggregate. An aggregate function is computed over all retained data. Valid
|
---|
10403 | aggregate functions are:
|
---|
10404 |
|
---|
10405 | <ul>
|
---|
10406 | <li>avg -- average</li>
|
---|
10407 | <li>min -- minimum</li>
|
---|
10408 | <li>max -- maximum</li>
|
---|
10409 | </ul>
|
---|
10410 |
|
---|
10411 | "Category/Metric" together form base metric name. A base metric is the
|
---|
10412 | smallest unit for which a sampling interval and the number of retained
|
---|
10413 | samples can be set. Only base metrics can be enabled and disabled. All
|
---|
10414 | sub-metrics are collected when their base metric is collected.
|
---|
10415 | Collected values for any set of sub-metrics can be queried with
|
---|
10416 | <link to="IPerformanceCollector::queryMetricsData" />.
|
---|
10417 |
|
---|
10418 | The valid names for base metrics are:
|
---|
10419 |
|
---|
10420 | <ul>
|
---|
10421 | <li>CPU/Load</li>
|
---|
10422 | <li>CPU/MHz</li>
|
---|
10423 | <li>RAM/Usage</li>
|
---|
10424 | </ul>
|
---|
10425 |
|
---|
10426 | The general sequence for collecting and retrieving the metrics is:
|
---|
10427 | <ul>
|
---|
10428 | <li>
|
---|
10429 | Obtain an instance of IPerfromanceCollector with
|
---|
10430 | <link to="IVirtualBox::performanceCollector" />
|
---|
10431 | </li>
|
---|
10432 | <li>
|
---|
10433 | Allocate and populate an array with references to objects the metrics
|
---|
10434 | will be collected for. Use references to IHost and IMachine objects.
|
---|
10435 | </li>
|
---|
10436 | <li>
|
---|
10437 | Allocate and populate an array with base metric names the data will be
|
---|
10438 | collected for.
|
---|
10439 | </li>
|
---|
10440 | <li>
|
---|
10441 | Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
|
---|
10442 | metric data will be collected and stored.
|
---|
10443 | </li>
|
---|
10444 | <li>
|
---|
10445 | Wait for the data to get collected.
|
---|
10446 | </li>
|
---|
10447 | <li>
|
---|
10448 | Allocate and populate an array with references to objects the metric
|
---|
10449 | values will be queried for. You can re-use the object array used for
|
---|
10450 | setting base metrics.
|
---|
10451 | </li>
|
---|
10452 | <li>
|
---|
10453 | Allocate and populate an array with metric names the data will be
|
---|
10454 | collected for. Note that metric names differ from base metric names.
|
---|
10455 | </li>
|
---|
10456 | <li>
|
---|
10457 | Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
|
---|
10458 | have been collected so far are returned. Note that the values are still
|
---|
10459 | retained internally and data collection continues.
|
---|
10460 | </li>
|
---|
10461 | </ul>
|
---|
10462 | </desc>
|
---|
10463 |
|
---|
10464 | <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
|
---|
10465 | <desc>
|
---|
10466 | Array of unique names of metrics.
|
---|
10467 |
|
---|
10468 | This array represents all metrics supported by the performance
|
---|
10469 | collector. Individual objects do not necessarily support all of them.
|
---|
10470 | <link to="IPerformanceCollector::getMetrics"/> can be used to get the
|
---|
10471 | list of supported metrics for a particular object.
|
---|
10472 | </desc>
|
---|
10473 | </attribute>
|
---|
10474 |
|
---|
10475 | <method name="getMetrics">
|
---|
10476 | <desc>
|
---|
10477 | Returns parameters of specified metrics for a set of objects.
|
---|
10478 | <note>
|
---|
10479 | @c Null metrics array means all metrics. @c Null object array means
|
---|
10480 | all existing objects.
|
---|
10481 | </note>
|
---|
10482 | </desc>
|
---|
10483 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
10484 | <desc>
|
---|
10485 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
10486 | is supported.
|
---|
10487 | </desc>
|
---|
10488 | </param>
|
---|
10489 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
10490 | <desc>
|
---|
10491 | Set of objects to return metric parameters for.
|
---|
10492 | </desc>
|
---|
10493 | </param>
|
---|
10494 | <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
10495 | <desc>
|
---|
10496 | Array of returned metric parameters.
|
---|
10497 | </desc>
|
---|
10498 | </param>
|
---|
10499 | </method>
|
---|
10500 |
|
---|
10501 | <method name="setupMetrics">
|
---|
10502 | <desc>
|
---|
10503 | Sets parameters of specified base metrics for a set of objects.
|
---|
10504 | <note>
|
---|
10505 | @c Null metrics array means all metrics. @c Null object array means
|
---|
10506 | all existing objects.
|
---|
10507 | </note>
|
---|
10508 | </desc>
|
---|
10509 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
10510 | <desc>
|
---|
10511 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
10512 | is supported.
|
---|
10513 | </desc>
|
---|
10514 | </param>
|
---|
10515 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
10516 | <desc>
|
---|
10517 | Set of objects to setup metric parameters for.
|
---|
10518 | </desc>
|
---|
10519 | </param>
|
---|
10520 | <param name="period" type="unsigned long" dir="in">
|
---|
10521 | <desc>
|
---|
10522 | Time interval in seconds between two consecutive samples of performace
|
---|
10523 | data.
|
---|
10524 | </desc>
|
---|
10525 | </param>
|
---|
10526 | <param name="count" type="unsigned long" dir="in">
|
---|
10527 | <desc>
|
---|
10528 | Number of samples to retain in performance data history. Older samples
|
---|
10529 | get discarded.
|
---|
10530 | </desc>
|
---|
10531 | </param>
|
---|
10532 | </method>
|
---|
10533 |
|
---|
10534 | <method name="enableMetrics">
|
---|
10535 | <desc>
|
---|
10536 | Turns on collecting specified base metrics.
|
---|
10537 | <note>
|
---|
10538 | @c Null metrics array means all metrics. @c Null object array means
|
---|
10539 | all existing objects.
|
---|
10540 | </note>
|
---|
10541 | </desc>
|
---|
10542 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
10543 | <desc>
|
---|
10544 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
10545 | is supported.
|
---|
10546 | </desc>
|
---|
10547 | </param>
|
---|
10548 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
10549 | <desc>
|
---|
10550 | Set of objects to enable metrics for.
|
---|
10551 | </desc>
|
---|
10552 | </param>
|
---|
10553 | </method>
|
---|
10554 |
|
---|
10555 | <method name="disableMetrics">
|
---|
10556 | <desc>
|
---|
10557 | Turns off collecting specified base metrics.
|
---|
10558 | <note>
|
---|
10559 | @c Null metrics array means all metrics. @c Null object array means
|
---|
10560 | all existing objects.
|
---|
10561 | </note>
|
---|
10562 | </desc>
|
---|
10563 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
10564 | <desc>
|
---|
10565 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
10566 | is supported.
|
---|
10567 | </desc>
|
---|
10568 | </param>
|
---|
10569 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
10570 | <desc>
|
---|
10571 | Set of objects to disable metrics for.
|
---|
10572 | </desc>
|
---|
10573 | </param>
|
---|
10574 | </method>
|
---|
10575 |
|
---|
10576 | <method name="queryMetricsData">
|
---|
10577 | <desc>
|
---|
10578 | Queries collected metrics data for a set of objects.
|
---|
10579 |
|
---|
10580 | The data itself and related metric information are returned in four
|
---|
10581 | parallel and one flattened array of arrays. Elements of @c
|
---|
10582 | returnMetricNames, @c returnObjects, @c returnDataIndices and @c
|
---|
10583 | returnDataLengths with the same index describe one set of values
|
---|
10584 | corresponding to a single metric.
|
---|
10585 |
|
---|
10586 | The @a returnData parameter is a flattened array of arrays. Each start
|
---|
10587 | and length of a sub-array is indicated by @a returnDataIndices and @a
|
---|
10588 | returnDataLengths. The first value for metric <tt>metricNames[i]</tt> is at
|
---|
10589 | <tt> returnData[returnIndices[i]]</tt>.
|
---|
10590 |
|
---|
10591 | <note>
|
---|
10592 | @c Null metrics array means all applicable metrics. @c Null object
|
---|
10593 | array means all existing objects.
|
---|
10594 | </note>
|
---|
10595 | <note>
|
---|
10596 | Data collection continues behind the scenes after call to @c
|
---|
10597 | queryMetricsData. The return data can be seen as the snapshot of
|
---|
10598 | the current state at the time of @c queryMetricsData call. The
|
---|
10599 | internally kept metric values are not cleared by the call. This makes
|
---|
10600 | possible querying different subsets of metrics or aggregates with
|
---|
10601 | subsequent calls. If periodic querying is needed it is highly
|
---|
10602 | suggested to query the values with @c interval*count period to avoid
|
---|
10603 | confusion. This way a completely new set of data values will be
|
---|
10604 | provided by each query.
|
---|
10605 | </note>
|
---|
10606 | </desc>
|
---|
10607 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
10608 | <desc>
|
---|
10609 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
10610 | is supported.
|
---|
10611 | </desc>
|
---|
10612 | </param>
|
---|
10613 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
10614 | <desc>
|
---|
10615 | Set of objects to query metrics for.
|
---|
10616 | </desc>
|
---|
10617 | </param>
|
---|
10618 | <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
|
---|
10619 | <desc>
|
---|
10620 | Names of metrics returned in @c returnData.
|
---|
10621 | </desc>
|
---|
10622 | </param>
|
---|
10623 | <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
|
---|
10624 | <desc>
|
---|
10625 | Objects associated with metrics returned in @c returnData.
|
---|
10626 | </desc>
|
---|
10627 | </param>
|
---|
10628 | <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
|
---|
10629 | <desc>
|
---|
10630 | Indices of the first elements of value sequences of particular metrics
|
---|
10631 | returned in @c returnData.
|
---|
10632 | </desc>
|
---|
10633 | </param>
|
---|
10634 | <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
|
---|
10635 | <desc>
|
---|
10636 | Lengths of value sequences of particular metrics.
|
---|
10637 | </desc>
|
---|
10638 | </param>
|
---|
10639 | <param name="returnData" type="long" dir="return" safearray="yes">
|
---|
10640 | <desc>
|
---|
10641 | Flattened array of all metric data containing sequences of values for
|
---|
10642 | each metric.
|
---|
10643 | </desc>
|
---|
10644 | </param>
|
---|
10645 | </method>
|
---|
10646 |
|
---|
10647 | </interface>
|
---|
10648 |
|
---|
10649 | <module name="VBoxSVC" context="LocalServer">
|
---|
10650 | <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
|
---|
10651 | namespace="virtualbox.org">
|
---|
10652 | <interface name="IVirtualBox" default="yes"/>
|
---|
10653 | </class>
|
---|
10654 | </module>
|
---|
10655 |
|
---|
10656 | <module name="VBoxC" context="InprocServer" threadingModel="Free">
|
---|
10657 | <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
|
---|
10658 | namespace="virtualbox.org">
|
---|
10659 | <interface name="ISession" default="yes"/>
|
---|
10660 | </class>
|
---|
10661 | </module>
|
---|
10662 |
|
---|
10663 | </library>
|
---|
10664 |
|
---|
10665 | </idl>
|
---|