1 | <?xml version="1.0" ?>
|
---|
2 |
|
---|
3 | <!--
|
---|
4 | * :tabSize=2:indentSize=2:noTabs=true:
|
---|
5 | * :folding=explicit:collapseFolds=1:
|
---|
6 | *
|
---|
7 | * Master declaration for VirtualBox's Main API, represented
|
---|
8 | * by COM/XPCOM and web service interfaces.
|
---|
9 | *
|
---|
10 | * From this document, the build system generates several files
|
---|
11 | * via XSLT that are then used during the build process.
|
---|
12 | *
|
---|
13 | * Below is the list of XSL templates that operate on this file and
|
---|
14 | * output files they generate. These XSL templates must be updated
|
---|
15 | * whenever the schema of this file changes:
|
---|
16 | *
|
---|
17 | * 1. src/VBox/Main/idl/midl.xsl =>
|
---|
18 | * out/<platform>/bin/sdk/idl/VirtualBox.idl
|
---|
19 | * (MS COM interface definition file for Main API)
|
---|
20 | *
|
---|
21 | * 2. src/VBox/Main/idl/xpidl.xsl =>
|
---|
22 | * out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
|
---|
23 | * (XPCOM interface definition file for Main API)
|
---|
24 | *
|
---|
25 | * 3. src/VBox/Main/idl/doxygen.xsl =>
|
---|
26 | * out/<platform>/obj/src/VBox/Main/VirtualBox.idl
|
---|
27 | * (pseudo-IDL for Doxygen to generate the official Main API
|
---|
28 | * documentation)
|
---|
29 | *
|
---|
30 | * 4. src/VBox/Main/webservice/*.xsl =>
|
---|
31 | * a bunch of WSDL and C++ files
|
---|
32 | * (VirtualBox web service sources and SOAP mappers;
|
---|
33 | * see src/VBox/Main/webservice/Makefile.kmk for details)
|
---|
34 | *
|
---|
35 | * 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
|
---|
36 | * out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
|
---|
37 | * (smart Qt-based C++ wrapper classes for COM interfaces
|
---|
38 | * of the Main API)
|
---|
39 | *
|
---|
40 | * 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
|
---|
41 | * out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
|
---|
42 | * (Main API TypeLib block for the WiX installer)
|
---|
43 | *
|
---|
44 | * 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
|
---|
45 | * out/<platform>/obj/Runtime/errmsgvboxcomdata.h
|
---|
46 | * (<result> extraction for the %Rhrc format specifier)
|
---|
47 | *
|
---|
48 | Copyright (C) 2006-2009 Sun Microsystems, Inc.
|
---|
49 |
|
---|
50 | This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
51 | available from http://www.virtualbox.org. This file is free software;
|
---|
52 | you can redistribute it and/or modify it under the terms of the GNU
|
---|
53 | General Public License (GPL) as published by the Free Software
|
---|
54 | Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
55 | VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
56 | hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
57 |
|
---|
58 | Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
59 | Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
60 | additional information or have any questions.
|
---|
61 | -->
|
---|
62 |
|
---|
63 | <idl>
|
---|
64 |
|
---|
65 | <desc>
|
---|
66 | Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
|
---|
67 | describes the so-called <i>VirtualBox Main API</i> which comprises all public
|
---|
68 | COM interfaces and components provided by the VirtualBox server and by the
|
---|
69 | VirtualBox client library.
|
---|
70 |
|
---|
71 | VirtualBox employs a client-server design, meaning that whenever any part of
|
---|
72 | VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
|
---|
73 | interface or any virtual machine --, a dedicated server process named
|
---|
74 | VBoxSVC runs in the background. This allows multiple processes working with
|
---|
75 | VirtualBox to cooperate without conflicts. These processes communicate to each
|
---|
76 | other using inter-process communication facilities provided by the COM
|
---|
77 | implementation of the host computer.
|
---|
78 |
|
---|
79 | On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
|
---|
80 | implementation. On all other platforms, Mozilla XPCOM, an open-source COM
|
---|
81 | implementation, is used.
|
---|
82 |
|
---|
83 | All the parts that a typical VirtualBox user interacts with (the Qt GUI,
|
---|
84 | the VBoxManage command-line interface and the VBoxVRDP server) are technically
|
---|
85 | front-ends to the Main API and only use the interfaces that are documented
|
---|
86 | in this Main API documentation. This ensures that, with any given release
|
---|
87 | version of VirtualBox, all capabilities of the product that could be useful
|
---|
88 | to an external client program are always exposed by way of this API.
|
---|
89 |
|
---|
90 | The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
|
---|
91 | contains two public component classes:
|
---|
92 | <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
|
---|
93 | implement IVirtualBox and ISession interfaces respectively. These two classes
|
---|
94 | are of supreme importance and will be needed in order for any front-end
|
---|
95 | program to do anything useful. It is recommended to read the documentation of
|
---|
96 | the mentioned interfaces first.
|
---|
97 |
|
---|
98 | The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
|
---|
99 | there can be only one object of this class on the local machine at any given
|
---|
100 | time. This object is a parent of many other objects in the VirtualBox COM
|
---|
101 | library and lives in the VBoxSVC process. In fact, when you create an instance
|
---|
102 | of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
|
---|
103 | process is already running, starts it if not, and returns you a reference to
|
---|
104 | the <tt>VirtualBox</tt> object created in this process. When the last reference
|
---|
105 | to this object is released, the VBoxSVC process ends (with a 5 second delay to
|
---|
106 | protect from too frequent restarts).
|
---|
107 |
|
---|
108 | The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
|
---|
109 | as many <tt>Session</tt> objects as you need but all of them will live in a
|
---|
110 | process which issues the object instantiation call. <tt>Session</tt> objects
|
---|
111 | represent virtual machine sessions which are used to configure virtual
|
---|
112 | machines and control their execution.
|
---|
113 | </desc>
|
---|
114 |
|
---|
115 | <if target="midl">
|
---|
116 | <cpp line="enum {"/>
|
---|
117 | <cpp line=" kTypeLibraryMajorVersion = 1,"/>
|
---|
118 | <cpp line=" kTypeLibraryMinorVersion = 0"/>
|
---|
119 | <cpp line="};"/>
|
---|
120 | </if>
|
---|
121 |
|
---|
122 | <if target="xpidl">
|
---|
123 | <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
|
---|
124 | <cpp>
|
---|
125 | /* currently, nsISupportsImpl.h lacks the below-like macros */
|
---|
126 |
|
---|
127 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
|
---|
128 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
|
---|
129 |
|
---|
130 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
|
---|
131 | # define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
|
---|
132 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
133 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
134 | NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
|
---|
135 | NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
|
---|
136 | #endif
|
---|
137 |
|
---|
138 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
|
---|
139 | # define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
|
---|
140 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
141 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
142 | NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
|
---|
143 | NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
|
---|
144 | #endif
|
---|
145 |
|
---|
146 | #ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
|
---|
147 | # define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
148 | NS_INTERFACE_MAP_BEGIN(_class) \
|
---|
149 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
|
---|
150 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
|
---|
151 | NS_IMPL_QUERY_CLASSINFO(_class) \
|
---|
152 | NS_INTERFACE_MAP_END
|
---|
153 | #endif
|
---|
154 |
|
---|
155 | #ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
|
---|
156 | # define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
157 | _i2, _ic2) \
|
---|
158 | NS_INTERFACE_MAP_BEGIN(_class) \
|
---|
159 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
|
---|
160 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
|
---|
161 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
|
---|
162 | NS_IMPL_QUERY_CLASSINFO(_class) \
|
---|
163 | NS_INTERFACE_MAP_END
|
---|
164 | #endif
|
---|
165 |
|
---|
166 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
|
---|
167 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
|
---|
168 |
|
---|
169 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
|
---|
170 | # define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
171 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
172 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
173 | NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
174 | NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
|
---|
175 | #endif
|
---|
176 |
|
---|
177 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
|
---|
178 | # define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
179 | _i2, _ic2) \
|
---|
180 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
181 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
182 | NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
183 | _i2, _ic2) \
|
---|
184 | NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
|
---|
185 | #endif
|
---|
186 | </cpp>
|
---|
187 | </if>
|
---|
188 |
|
---|
189 | <library
|
---|
190 | name="VirtualBox"
|
---|
191 | uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
|
---|
192 | version="1.3"
|
---|
193 | desc="VirtualBox Type Library"
|
---|
194 | appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
|
---|
195 | supportsErrorInfo="yes"
|
---|
196 | >
|
---|
197 |
|
---|
198 |
|
---|
199 | <!--
|
---|
200 | // COM result codes for VirtualBox
|
---|
201 | /////////////////////////////////////////////////////////////////////////
|
---|
202 | -->
|
---|
203 |
|
---|
204 | <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
|
---|
205 | <desc>
|
---|
206 | This section describes all VirtualBox-specific COM result codes that may
|
---|
207 | be returned by methods of VirtualBox COM interfaces in addition to
|
---|
208 | standard COM result codes.
|
---|
209 |
|
---|
210 | Note that along with the result code, every VirtualBox method returns
|
---|
211 | extended error information through the IVirtualBoxErrorInfo interface on
|
---|
212 | failure. This interface is a preferred way to present the error to the end
|
---|
213 | user because it contains a human readable description of the error. Raw
|
---|
214 | result codes, both standard and described in this section, are intended to
|
---|
215 | be used by programs to analyze the reason of a failure and select an
|
---|
216 | appropriate course of action without involving the end user (for example,
|
---|
217 | retry the operation later or make a different call).
|
---|
218 |
|
---|
219 | The standard COM result codes that may originate from our methods include:
|
---|
220 |
|
---|
221 | <table>
|
---|
222 | <tr><td>E_INVALIDARG</td>
|
---|
223 | <td>
|
---|
224 | Returned when the value of the method's argument is not within the range
|
---|
225 | of valid values. This should not be confused with situations when the
|
---|
226 | value is within the range but simply doesn't suit the current object
|
---|
227 | state and there is a possibility that it will be accepted later (in such
|
---|
228 | cases VirtualBox-specific codes are returned, for example,
|
---|
229 | <link to="VBOX_E_OBJECT_NOT_FOUND"/>).
|
---|
230 | </td>
|
---|
231 | </tr>
|
---|
232 | <tr><td>E_POINTER</td>
|
---|
233 | <td>
|
---|
234 | Returned if a memory pointer for the output argument is invalid (for
|
---|
235 | example, <tt>NULL</tt>). Note that when pointers representing input
|
---|
236 | arguments (such as strings) are invalid, E_INVALIDARG is returned.
|
---|
237 | </td>
|
---|
238 | </tr>
|
---|
239 | <tr><td>E_ACCESSDENIED</td>
|
---|
240 | <td>
|
---|
241 | Returned when the called object is not ready. Since the lifetime of a
|
---|
242 | public COM object cannot be fully controlled by the implementation,
|
---|
243 | VirtualBox maintains the readiness state for all objects it creates and
|
---|
244 | returns this code in response to any method call on the object that was
|
---|
245 | deactivated by VirtualBox and is not functioning any more.
|
---|
246 | </td>
|
---|
247 | </tr>
|
---|
248 | <tr><td>E_OUTOFMEMORY</td>
|
---|
249 | <td>
|
---|
250 | Returned when a memory allocation operation fails.
|
---|
251 | </td>
|
---|
252 | </tr>
|
---|
253 | </table>
|
---|
254 | </desc>
|
---|
255 | </descGroup>
|
---|
256 |
|
---|
257 | <!--
|
---|
258 | Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
|
---|
259 | everything in <result>/<desc> after (and including) the first dot, so express
|
---|
260 | the matter of the error code in the first sentence and keep it short.
|
---|
261 | -->
|
---|
262 |
|
---|
263 | <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
|
---|
264 | <desc>
|
---|
265 | Object corresponding to the supplied arguments does not exist.
|
---|
266 | </desc>
|
---|
267 | </result>
|
---|
268 |
|
---|
269 | <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
|
---|
270 | <desc>
|
---|
271 | Current virtual machine state prevents the operation.
|
---|
272 | </desc>
|
---|
273 | </result>
|
---|
274 |
|
---|
275 | <result name="VBOX_E_VM_ERROR" value="0x80BB0003">
|
---|
276 | <desc>
|
---|
277 | Virtual machine error occurred attempting the operation.
|
---|
278 | </desc>
|
---|
279 | </result>
|
---|
280 |
|
---|
281 | <result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
|
---|
282 | <desc>
|
---|
283 | File not accessible or erroneous file contents.
|
---|
284 | </desc>
|
---|
285 | </result>
|
---|
286 |
|
---|
287 | <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
|
---|
288 | <desc>
|
---|
289 | Runtime subsystem error.
|
---|
290 | </desc>
|
---|
291 | </result>
|
---|
292 |
|
---|
293 | <result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
|
---|
294 | <desc>
|
---|
295 | Pluggable Device Manager error.
|
---|
296 | </desc>
|
---|
297 | </result>
|
---|
298 |
|
---|
299 | <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
|
---|
300 | <desc>
|
---|
301 | Current object state prohibits operation.
|
---|
302 | </desc>
|
---|
303 | </result>
|
---|
304 |
|
---|
305 | <result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
|
---|
306 | <desc>
|
---|
307 | Host operating system related error.
|
---|
308 | </desc>
|
---|
309 | </result>
|
---|
310 |
|
---|
311 | <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
|
---|
312 | <desc>
|
---|
313 | Requested operation is not supported.
|
---|
314 | </desc>
|
---|
315 | </result>
|
---|
316 |
|
---|
317 | <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
|
---|
318 | <desc>
|
---|
319 | Invalid XML found.
|
---|
320 | </desc>
|
---|
321 | </result>
|
---|
322 |
|
---|
323 | <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
|
---|
324 | <desc>
|
---|
325 | Current session state prohibits operation.
|
---|
326 | </desc>
|
---|
327 | </result>
|
---|
328 |
|
---|
329 | <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
|
---|
330 | <desc>
|
---|
331 | Object being in use prohibits operation.
|
---|
332 | </desc>
|
---|
333 | </result>
|
---|
334 |
|
---|
335 | <!--
|
---|
336 | Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
|
---|
337 | everything in <result>/<desc> after (and including) the first dot, so express
|
---|
338 | the matter of the error code in the first sentence and keep it short.
|
---|
339 | -->
|
---|
340 |
|
---|
341 | <descGroup/>
|
---|
342 |
|
---|
343 | <!--
|
---|
344 | // all common enums
|
---|
345 | /////////////////////////////////////////////////////////////////////////
|
---|
346 | -->
|
---|
347 |
|
---|
348 | <enum
|
---|
349 | name="TSBool"
|
---|
350 | uuid="523ff64d-842a-4b1a-80e7-c311b028cb3a"
|
---|
351 | >
|
---|
352 | <desc>
|
---|
353 | Boolean variable having a third state, default.
|
---|
354 | </desc>
|
---|
355 |
|
---|
356 | <const name="False" value="0"/>
|
---|
357 | <const name="True" value="1"/>
|
---|
358 | <const name="Default" value="2"/>
|
---|
359 | </enum>
|
---|
360 |
|
---|
361 | <enum
|
---|
362 | name="AccessMode"
|
---|
363 | uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
|
---|
364 | >
|
---|
365 | <desc>
|
---|
366 | Access mode for opening files.
|
---|
367 | </desc>
|
---|
368 |
|
---|
369 | <const name="ReadOnly" value="1"/>
|
---|
370 | <const name="ReadWrite" value="2"/>
|
---|
371 | </enum>
|
---|
372 |
|
---|
373 | <enum
|
---|
374 | name="MachineState"
|
---|
375 | uuid="73bf04d0-7c4f-4684-9abf-d65a9ad74343"
|
---|
376 | >
|
---|
377 | <desc>
|
---|
378 | Virtual machine execution state.
|
---|
379 |
|
---|
380 | This enumeration represents possible values of the <link
|
---|
381 | to="IMachine::state"/> attribute.
|
---|
382 |
|
---|
383 | Below is the basic virtual machine state diagram. It shows how the state
|
---|
384 | changes during virtual machine execution. The text in square braces shows
|
---|
385 | a method of the IConsole interface that performs the given state
|
---|
386 | transition.
|
---|
387 |
|
---|
388 | <pre>
|
---|
389 | +---------[powerDown()] <- Stuck <--[failure]-+
|
---|
390 | V |
|
---|
391 | +-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+
|
---|
392 | | | | | V |
|
---|
393 | | Aborted -----+ +--> Running --[pause()]--> Paused
|
---|
394 | | | ^ | ^ |
|
---|
395 | | Saved -----------[powerUp()]--> Restoring -+ | | | |
|
---|
396 | | ^ | | | |
|
---|
397 | | | +-----------------------------------------+-|-------------------+ +
|
---|
398 | | | | | |
|
---|
399 | | | +-- Saving <--------[takeSnapshot()]<-------+---------------------+
|
---|
400 | | | | |
|
---|
401 | | +-------- Saving <--------[saveState()]<----------+---------------------+
|
---|
402 | | | |
|
---|
403 | +-------------- Stopping -------[powerDown()]<----------+---------------------+
|
---|
404 | </pre>
|
---|
405 |
|
---|
406 | Note that states to the right from PoweredOff, Aborted and Saved in the
|
---|
407 | above diagram are called <i>online VM states</i>. These states
|
---|
408 | represent the virtual machine which is being executed in a dedicated
|
---|
409 | process (usually with a GUI window attached to it where you can see the
|
---|
410 | activity of the virtual machine and interact with it). There are two
|
---|
411 | special pseudo-states, FirstOnline and LastOnline, that can be used in
|
---|
412 | relational expressions to detect if the given machine state is online or
|
---|
413 | not:
|
---|
414 |
|
---|
415 | <pre>
|
---|
416 | if (machine.GetState() >= MachineState_FirstOnline &&
|
---|
417 | machine.GetState() <= MachineState_LastOnline)
|
---|
418 | {
|
---|
419 | ...the machine is being executed...
|
---|
420 | }
|
---|
421 | </pre>
|
---|
422 |
|
---|
423 | When the virtual machine is in one of the online VM states (that is, being
|
---|
424 | executed), only a few machine settings can be modified. Methods working
|
---|
425 | with such settings contain an explicit note about that. An attempt to
|
---|
426 | change any oter setting or perform a modifying operation during this time
|
---|
427 | will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
|
---|
428 |
|
---|
429 | All online states except Running, Paused and Stuck are transitional: they
|
---|
430 | represent temporary conditions of the virtual machine that will last as
|
---|
431 | long as the operation that initiated such a condition.
|
---|
432 |
|
---|
433 | The Stuck state is a special case. It means that execution of the machine
|
---|
434 | has reached the "Guru Meditation" condition. This condition indicates an
|
---|
435 | internal VMM (virtual machine manager) failure which may happen as a
|
---|
436 | result of either an unhandled low-level virtual hardware exception or one
|
---|
437 | of the recompiler exceptions (such as the <i>too-many-traps</i>
|
---|
438 | condition).
|
---|
439 |
|
---|
440 | Note also that any online VM state may transit to the Aborted state. This
|
---|
441 | happens if the process that is executing the virtual machine terminates
|
---|
442 | unexpectedly (for example, crashes). Other than that, the Aborted state is
|
---|
443 | equivalent to PoweredOff.
|
---|
444 |
|
---|
445 | There are also a few additional state diagrams that do not deal with
|
---|
446 | virtual machine execution and therefore are shown separately. The states
|
---|
447 | shown on these diagrams are called <i>offline VM states</i> (this includes
|
---|
448 | PoweredOff, Aborted and Saved too).
|
---|
449 |
|
---|
450 | The first diagram shows what happens when a lengthy setup operation is
|
---|
451 | being executed (such as <link to="IMachine::attachHardDisk"/>).
|
---|
452 |
|
---|
453 | <pre>
|
---|
454 | +----------------------------------(same state as before the call)------+
|
---|
455 | | |
|
---|
456 | +-> PoweredOff --+ |
|
---|
457 | | | |
|
---|
458 | |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
|
---|
459 | | |
|
---|
460 | +-> Saved -------+
|
---|
461 | </pre>
|
---|
462 |
|
---|
463 | The next two diagrams demonstrate the process of taking a snapshot of a
|
---|
464 | powered off virtual machine and performing one of the "discard..."
|
---|
465 | operations, respectively.
|
---|
466 |
|
---|
467 | <pre>
|
---|
468 | +----------------------------------(same state as before the call)------+
|
---|
469 | | |
|
---|
470 | +-> PoweredOff --+ |
|
---|
471 | | +-->[takeSnapshot()] -------------------> Saving ------+
|
---|
472 | +-> Aborted -----+
|
---|
473 |
|
---|
474 | +-> PoweredOff --+
|
---|
475 | | |
|
---|
476 | | Aborted -----+-->[discardSnapshot() ]-------------> Discarding --+
|
---|
477 | | | [discardCurrentState()] |
|
---|
478 | +-> Saved -------+ [discardCurrentSnapshotAndState()] |
|
---|
479 | | |
|
---|
480 | +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
|
---|
481 | </pre>
|
---|
482 |
|
---|
483 | Note that the Saving state is present in both the offline state group and
|
---|
484 | online state group. Currently, the only way to determine what group is
|
---|
485 | assumed in a particular case is to remember the previous machine state: if
|
---|
486 | it was Running or Paused, then Saving is an online state, otherwise it is
|
---|
487 | an offline state. This inconsistency may be removed in one of the future
|
---|
488 | versions of VirtualBox by adding a new state.
|
---|
489 |
|
---|
490 | <note internal="yes">
|
---|
491 | For whoever decides to touch this enum: In order to keep the
|
---|
492 | comparisons involving FirstOnline and LastOnline pseudo-states valid,
|
---|
493 | the numeric values of these states must be correspondingly updated if
|
---|
494 | needed: for any online VM state, the condition
|
---|
495 | <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
496 | <tt>true</tt>. The same relates to transient states for which
|
---|
497 | the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
498 | <tt>true</tt>.
|
---|
499 | </note>
|
---|
500 | </desc>
|
---|
501 |
|
---|
502 | <const name="Null" value="0">
|
---|
503 | <desc>Null value (never used by the API).</desc>
|
---|
504 | </const>
|
---|
505 | <const name="PoweredOff" value="1">
|
---|
506 | <desc>
|
---|
507 | The machine is not running.
|
---|
508 | </desc>
|
---|
509 | </const>
|
---|
510 | <const name="Saved" value="2">
|
---|
511 | <desc>
|
---|
512 | The machine is not currently running, but the execution state of the machine
|
---|
513 | has been saved to an external file when it was running.
|
---|
514 | </desc>
|
---|
515 | </const>
|
---|
516 | <const name="Aborted" value="3">
|
---|
517 | <desc>
|
---|
518 | The process running the machine has terminated abnormally.
|
---|
519 | </desc>
|
---|
520 | </const>
|
---|
521 | <const name="Running" value="4">
|
---|
522 | <desc>
|
---|
523 | The machine is currently being executed.
|
---|
524 | <note internal="yes">
|
---|
525 | For whoever decides to touch this enum: In order to keep the
|
---|
526 | comparisons in the old source code valid, this state must immediately
|
---|
527 | precede the Paused state.
|
---|
528 | </note>
|
---|
529 | </desc>
|
---|
530 | </const>
|
---|
531 | <const name="Paused" value="5">
|
---|
532 | <desc>
|
---|
533 | Execution of the machine has been paused.
|
---|
534 | <note internal="yes">
|
---|
535 | For whoever decides to touch this enum: In order to keep the
|
---|
536 | comparisons in the old source code valid, this state must immediately
|
---|
537 | follow the Running state.
|
---|
538 | </note>
|
---|
539 | </desc>
|
---|
540 | </const>
|
---|
541 | <const name="Stuck" value="6">
|
---|
542 | <desc>
|
---|
543 | Execution of the machine has reached the "Guru Meditation"
|
---|
544 | condition.
|
---|
545 | </desc>
|
---|
546 | </const>
|
---|
547 | <const name="Starting" value="7">
|
---|
548 | <desc>
|
---|
549 | Machine is being started after powering it on from a
|
---|
550 | zero execution state.
|
---|
551 | </desc>
|
---|
552 | </const>
|
---|
553 | <const name="Stopping" value="8">
|
---|
554 | <desc>
|
---|
555 | Machine is being normally stopped powering it off, or after the guest OS
|
---|
556 | has initiated a shutdown sequence.
|
---|
557 | </desc>
|
---|
558 | </const>
|
---|
559 | <const name="Saving" value="9">
|
---|
560 | <desc>
|
---|
561 | Machine is saving its execution state to a file or an online
|
---|
562 | snapshot of the machine is being taken.
|
---|
563 | </desc>
|
---|
564 | </const>
|
---|
565 | <const name="Restoring" value="10">
|
---|
566 | <desc>
|
---|
567 | Execution state of the machine is being restored from a file
|
---|
568 | after powering it on from the saved execution state.
|
---|
569 | </desc>
|
---|
570 | </const>
|
---|
571 | <const name="Discarding" value="11">
|
---|
572 | <desc>
|
---|
573 | Snapshot of the machine is being discarded.
|
---|
574 | </desc>
|
---|
575 | </const>
|
---|
576 | <const name="SettingUp" value="12">
|
---|
577 | <desc>
|
---|
578 | Lengthy setup operation is in progress.
|
---|
579 | </desc>
|
---|
580 | </const>
|
---|
581 |
|
---|
582 | <const name="FirstOnline" value="4" wsmap="suppress"> <!-- Running -->
|
---|
583 | <desc>
|
---|
584 | Pseudo-state: first online state (for use in relational expressions).
|
---|
585 | </desc>
|
---|
586 | </const>
|
---|
587 | <const name="LastOnline" value="10" wsmap="suppress"> <!-- Restoring -->
|
---|
588 | <desc>
|
---|
589 | Pseudo-state: last online state (for use in relational expressions).
|
---|
590 | </desc>
|
---|
591 | </const>
|
---|
592 |
|
---|
593 | <const name="FirstTransient" value="7" wsmap="suppress"> <!-- Starting -->
|
---|
594 | <desc>
|
---|
595 | Pseudo-state: first transient state (for use in relational expressions).
|
---|
596 | </desc>
|
---|
597 | </const>
|
---|
598 | <const name="LastTransient" value="12" wsmap="suppress"> <!-- SettingUp -->
|
---|
599 | <desc>
|
---|
600 | Pseudo-state: last transient state (for use in relational expressions).
|
---|
601 | </desc>
|
---|
602 | </const>
|
---|
603 |
|
---|
604 | </enum>
|
---|
605 |
|
---|
606 | <enum
|
---|
607 | name="SessionState"
|
---|
608 | uuid="CF2700C0-EA4B-47ae-9725-7810114B94D8"
|
---|
609 | >
|
---|
610 | <desc>
|
---|
611 | Session state. This enumeration represents possible values of
|
---|
612 | <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
|
---|
613 | attributes. See individual enumerator descriptions for the meaning for
|
---|
614 | every value.
|
---|
615 | </desc>
|
---|
616 |
|
---|
617 | <const name="Null" value="0">
|
---|
618 | <desc>Null value (never used by the API).</desc>
|
---|
619 | </const>
|
---|
620 | <const name="Closed" value="1">
|
---|
621 | <desc>
|
---|
622 | The machine has no open sessions (<link to="IMachine::sessionState"/>);
|
---|
623 | the session is closed (<link to="ISession::state"/>)
|
---|
624 | </desc>
|
---|
625 | </const>
|
---|
626 | <const name="Open" value="2">
|
---|
627 | <desc>
|
---|
628 | The machine has an open direct session (<link to="IMachine::sessionState"/>);
|
---|
629 | the session is open (<link to="ISession::state"/>)
|
---|
630 | </desc>
|
---|
631 | </const>
|
---|
632 | <const name="Spawning" value="3">
|
---|
633 | <desc>
|
---|
634 | A new (direct) session is being opened for the machine
|
---|
635 | as a result of <link to="IVirtualBox::openRemoteSession"/>
|
---|
636 | call (<link to="IMachine::sessionState"/>);
|
---|
637 | the session is currently being opened
|
---|
638 | as a result of <link to="IVirtualBox::openRemoteSession"/>
|
---|
639 | call (<link to="ISession::state"/>)
|
---|
640 | </desc>
|
---|
641 | </const>
|
---|
642 | <const name="Closing" value="4">
|
---|
643 | <desc>
|
---|
644 | The direct session is being closed (<link to="IMachine::sessionState"/>);
|
---|
645 | the session is being closed (<link to="ISession::state"/>)
|
---|
646 | </desc>
|
---|
647 | </const>
|
---|
648 | </enum>
|
---|
649 |
|
---|
650 | <enum
|
---|
651 | name="SessionType"
|
---|
652 | uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
|
---|
653 | >
|
---|
654 | <desc>
|
---|
655 | Session type. This enumeration represents possible values of the
|
---|
656 | <link to="ISession::type"/> attribute.
|
---|
657 | </desc>
|
---|
658 |
|
---|
659 | <const name="Null" value="0">
|
---|
660 | <desc>Null value (never used by the API).</desc>
|
---|
661 | </const>
|
---|
662 | <const name="Direct" value="1">
|
---|
663 | <desc>
|
---|
664 | Direct session
|
---|
665 | (opened by <link to="IVirtualBox::openSession"/>)
|
---|
666 | </desc>
|
---|
667 | </const>
|
---|
668 | <const name="Remote" value="2">
|
---|
669 | <desc>
|
---|
670 | Remote session
|
---|
671 | (opened by <link to="IVirtualBox::openRemoteSession"/>)
|
---|
672 | </desc>
|
---|
673 | </const>
|
---|
674 | <const name="Existing" value="3">
|
---|
675 | <desc>
|
---|
676 | Existing session
|
---|
677 | (opened by <link to="IVirtualBox::openExistingSession"/>)
|
---|
678 | </desc>
|
---|
679 | </const>
|
---|
680 | </enum>
|
---|
681 |
|
---|
682 | <enum
|
---|
683 | name="DeviceType"
|
---|
684 | uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
|
---|
685 | >
|
---|
686 | <desc>
|
---|
687 | Device type.
|
---|
688 | </desc>
|
---|
689 | <const name="Null" value="0">
|
---|
690 | <desc>
|
---|
691 | Null value, may also mean "no device" (not allowed for
|
---|
692 | <link to="IConsole::getDeviceActivity"/>).
|
---|
693 | </desc>
|
---|
694 | </const>
|
---|
695 | <const name="Floppy" value="1">
|
---|
696 | <desc>Floppy device.</desc>
|
---|
697 | </const>
|
---|
698 | <const name="DVD" value="2">
|
---|
699 | <desc>CD/DVD-ROM device.</desc>
|
---|
700 | </const>
|
---|
701 | <const name="HardDisk" value="3">
|
---|
702 | <desc>Hard disk device.</desc>
|
---|
703 | </const>
|
---|
704 | <const name="Network" value="4">
|
---|
705 | <desc>Network device.</desc>
|
---|
706 | </const>
|
---|
707 | <const name="USB" value="5">
|
---|
708 | <desc>USB device.</desc>
|
---|
709 | </const>
|
---|
710 | <const name="SharedFolder" value="6">
|
---|
711 | <desc>Shared folder device.</desc>
|
---|
712 | </const>
|
---|
713 | </enum>
|
---|
714 |
|
---|
715 | <enum
|
---|
716 | name="DeviceActivity"
|
---|
717 | uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
|
---|
718 | >
|
---|
719 | <desc>
|
---|
720 | Device activity for <link to="IConsole::getDeviceActivity"/>.
|
---|
721 | </desc>
|
---|
722 |
|
---|
723 | <const name="Null" value="0"/>
|
---|
724 | <const name="Idle" value="1"/>
|
---|
725 | <const name="Reading" value="2"/>
|
---|
726 | <const name="Writing" value="3"/>
|
---|
727 | </enum>
|
---|
728 |
|
---|
729 | <enum
|
---|
730 | name="ClipboardMode"
|
---|
731 | uuid="33364716-4008-4701-8f14-be0fa3d62950"
|
---|
732 | >
|
---|
733 | <desc>
|
---|
734 | Host-Guest clipboard interchange mode.
|
---|
735 | </desc>
|
---|
736 |
|
---|
737 | <const name="Disabled" value="0"/>
|
---|
738 | <const name="HostToGuest" value="1"/>
|
---|
739 | <const name="GuestToHost" value="2"/>
|
---|
740 | <const name="Bidirectional" value="3"/>
|
---|
741 | </enum>
|
---|
742 |
|
---|
743 | <enum
|
---|
744 | name="Scope"
|
---|
745 | uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
|
---|
746 | >
|
---|
747 | <desc>
|
---|
748 | Scope of the operation.
|
---|
749 |
|
---|
750 | A generic enumeration used in various methods to define the action or
|
---|
751 | argument scope.
|
---|
752 | </desc>
|
---|
753 |
|
---|
754 | <const name="Global" value="0"/>
|
---|
755 | <const name="Machine" value="1"/>
|
---|
756 | <const name="Session" value="2"/>
|
---|
757 | </enum>
|
---|
758 |
|
---|
759 | <enum
|
---|
760 | name="GuestStatisticType"
|
---|
761 | uuid="aa7c1d71-aafe-47a8-9608-27d2d337cf55"
|
---|
762 | >
|
---|
763 | <desc>
|
---|
764 | Statistics type for <link to="IGuest::getStatistic"/>.
|
---|
765 | </desc>
|
---|
766 |
|
---|
767 | <const name="CPULoad_Idle" value="0">
|
---|
768 | <desc>
|
---|
769 | Idle CPU load (0-100%) for last interval.
|
---|
770 | </desc>
|
---|
771 | </const>
|
---|
772 | <const name="CPULoad_Kernel" value="1">
|
---|
773 | <desc>
|
---|
774 | Kernel CPU load (0-100%) for last interval.
|
---|
775 | </desc>
|
---|
776 | </const>
|
---|
777 | <const name="CPULoad_User" value="2">
|
---|
778 | <desc>
|
---|
779 | User CPU load (0-100%) for last interval.
|
---|
780 | </desc>
|
---|
781 | </const>
|
---|
782 | <const name="Threads" value="3">
|
---|
783 | <desc>
|
---|
784 | Total number of threads in the system.
|
---|
785 | </desc>
|
---|
786 | </const>
|
---|
787 | <const name="Processes" value="4">
|
---|
788 | <desc>
|
---|
789 | Total number of processes in the system.
|
---|
790 | </desc>
|
---|
791 | </const>
|
---|
792 | <const name="Handles" value="5">
|
---|
793 | <desc>
|
---|
794 | Total number of handles in the system.
|
---|
795 | </desc>
|
---|
796 | </const>
|
---|
797 | <const name="MemoryLoad" value="6">
|
---|
798 | <desc>
|
---|
799 | Memory load (0-100%).
|
---|
800 | </desc>
|
---|
801 | </const>
|
---|
802 | <const name="PhysMemTotal" value="7">
|
---|
803 | <desc>
|
---|
804 | Total physical memory in megabytes.
|
---|
805 | </desc>
|
---|
806 | </const>
|
---|
807 | <const name="PhysMemAvailable" value="8">
|
---|
808 | <desc>
|
---|
809 | Free physical memory in megabytes.
|
---|
810 | </desc>
|
---|
811 | </const>
|
---|
812 | <const name="PhysMemBalloon" value="9">
|
---|
813 | <desc>
|
---|
814 | Ballooned physical memory in megabytes.
|
---|
815 | </desc>
|
---|
816 | </const>
|
---|
817 | <const name="MemCommitTotal" value="10">
|
---|
818 | <desc>
|
---|
819 | Total amount of memory in the committed state in megabytes.
|
---|
820 | </desc>
|
---|
821 | </const>
|
---|
822 | <const name="MemKernelTotal" value="11">
|
---|
823 | <desc>
|
---|
824 | Total amount of memory used by the guest OS's kernel in megabytes.
|
---|
825 | </desc>
|
---|
826 | </const>
|
---|
827 | <const name="MemKernelPaged" value="12">
|
---|
828 | <desc>
|
---|
829 | Total amount of paged memory used by the guest OS's kernel in megabytes.
|
---|
830 | </desc>
|
---|
831 | </const>
|
---|
832 | <const name="MemKernelNonpaged" value="13">
|
---|
833 | <desc>
|
---|
834 | Total amount of non-paged memory used by the guest OS's kernel in megabytes.
|
---|
835 | </desc>
|
---|
836 | </const>
|
---|
837 | <const name="MemSystemCache" value="14">
|
---|
838 | <desc>
|
---|
839 | Total amount of memory used by the guest OS's system cache in megabytes.
|
---|
840 | </desc>
|
---|
841 | </const>
|
---|
842 | <const name="PageFileSize" value="15">
|
---|
843 | <desc>
|
---|
844 | Pagefile size in megabytes.
|
---|
845 | </desc>
|
---|
846 | </const>
|
---|
847 | <const name="SampleNumber" value="16">
|
---|
848 | <desc>
|
---|
849 | Statistics sample number
|
---|
850 | </desc>
|
---|
851 | </const>
|
---|
852 | <const name="MaxVal" value="17"/>
|
---|
853 | </enum>
|
---|
854 |
|
---|
855 | <enum
|
---|
856 | name="BIOSBootMenuMode"
|
---|
857 | uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
|
---|
858 | >
|
---|
859 | <desc>
|
---|
860 | BIOS boot menu mode.
|
---|
861 | </desc>
|
---|
862 |
|
---|
863 | <const name="Disabled" value="0"/>
|
---|
864 | <const name="MenuOnly" value="1"/>
|
---|
865 | <const name="MessageAndMenu" value="2"/>
|
---|
866 | </enum>
|
---|
867 |
|
---|
868 | <enum
|
---|
869 | name="DriveState"
|
---|
870 | uuid="cb7233b7-c519-42a5-8310-1830953cacbc"
|
---|
871 | >
|
---|
872 | <const name="Null" value="0">
|
---|
873 | <desc>Null value (never used by the API).</desc>
|
---|
874 | </const>
|
---|
875 | <const name="NotMounted" value="1"/>
|
---|
876 | <const name="ImageMounted" value="2"/>
|
---|
877 | <const name="HostDriveCaptured" value="3"/>
|
---|
878 | </enum>
|
---|
879 |
|
---|
880 | <enum
|
---|
881 | name="ProcessorFeature"
|
---|
882 | uuid="b8353b35-705d-4796-9967-ebfb7ba54af4"
|
---|
883 | >
|
---|
884 | <desc>
|
---|
885 | CPU features.
|
---|
886 | </desc>
|
---|
887 |
|
---|
888 | <const name="HWVirtEx" value="0"/>
|
---|
889 | <const name="PAE" value="1"/>
|
---|
890 | <const name="LongMode" value="2"/>
|
---|
891 | </enum>
|
---|
892 |
|
---|
893 |
|
---|
894 | <!--
|
---|
895 | // IVirtualBoxErrorInfo
|
---|
896 | /////////////////////////////////////////////////////////////////////////
|
---|
897 | -->
|
---|
898 |
|
---|
899 | <interface
|
---|
900 | name="IVirtualBoxErrorInfo" extends="$errorinfo"
|
---|
901 | uuid="e98b5376-8eb4-4eea-812a-3964bf3bb26f"
|
---|
902 | supportsErrorInfo="no"
|
---|
903 | wsmap="suppress"
|
---|
904 | >
|
---|
905 | <desc>
|
---|
906 | The IVirtualBoxErrorInfo interface represents extended error information.
|
---|
907 |
|
---|
908 | Extended error information can be set by VirtualBox components after
|
---|
909 | unsuccessful or partially successful method invocation. This information
|
---|
910 | can be retrieved by the calling party as an IVirtualBoxErrorInfo object
|
---|
911 | and then shown to the client in addition to the plain 32-bit result code.
|
---|
912 |
|
---|
913 | In MS COM, this interface extends the IErrorInfo interface,
|
---|
914 | in XPCOM, it extends the nsIException interface. In both cases,
|
---|
915 | it provides a set of common attributes to retrieve error
|
---|
916 | information.
|
---|
917 |
|
---|
918 | Sometimes invocation of some component's method may involve methods of
|
---|
919 | other components that may also fail (independently of this method's
|
---|
920 | failure), or a series of non-fatal errors may precede a fatal error that
|
---|
921 | causes method failure. In cases like that, it may be desirable to preserve
|
---|
922 | information about all errors happened during method invocation and deliver
|
---|
923 | it to the caller. The <link to="#next"/> attribute is intended
|
---|
924 | specifically for this purpose and allows to represent a chain of errors
|
---|
925 | through a single IVirtualBoxErrorInfo object set after method invocation.
|
---|
926 |
|
---|
927 | Note that errors are stored to a chain in the reverse order, i.e. the
|
---|
928 | initial error object you query right after method invocation is the last
|
---|
929 | error set by the callee, the object it points to in the @a next attribute
|
---|
930 | is the previous error and so on, up to the first error (which is the last
|
---|
931 | in the chain).
|
---|
932 | </desc>
|
---|
933 |
|
---|
934 | <attribute name="resultCode" type="result" readonly="yes">
|
---|
935 | <desc>
|
---|
936 | Result code of the error.
|
---|
937 | Usually, it will be the same as the result code returned
|
---|
938 | by the method that provided this error information, but not
|
---|
939 | always. For example, on Win32, CoCreateInstance() will most
|
---|
940 | likely return E_NOINTERFACE upon unsuccessful component
|
---|
941 | instantiation attempt, but not the value the component factory
|
---|
942 | returned.
|
---|
943 | <note>
|
---|
944 | In MS COM, there is no equivalent.
|
---|
945 | In XPCOM, it is the same as nsIException::result.
|
---|
946 | </note>
|
---|
947 | </desc>
|
---|
948 | </attribute>
|
---|
949 |
|
---|
950 | <attribute name="interfaceID" type="uuid" readonly="yes">
|
---|
951 | <desc>
|
---|
952 | UUID of the interface that defined the error.
|
---|
953 | <note>
|
---|
954 | In MS COM, it is the same as IErrorInfo::GetGUID.
|
---|
955 | In XPCOM, there is no equivalent.
|
---|
956 | </note>
|
---|
957 | </desc>
|
---|
958 | </attribute>
|
---|
959 |
|
---|
960 | <attribute name="component" type="wstring" readonly="yes">
|
---|
961 | <desc>
|
---|
962 | Name of the component that generated the error.
|
---|
963 | <note>
|
---|
964 | In MS COM, it is the same as IErrorInfo::GetSource.
|
---|
965 | In XPCOM, there is no equivalent.
|
---|
966 | </note>
|
---|
967 | </desc>
|
---|
968 | </attribute>
|
---|
969 |
|
---|
970 | <attribute name="text" type="wstring" readonly="yes">
|
---|
971 | <desc>
|
---|
972 | Text description of the error.
|
---|
973 | <note>
|
---|
974 | In MS COM, it is the same as IErrorInfo::GetDescription.
|
---|
975 | In XPCOM, it is the same as nsIException::message.
|
---|
976 | </note>
|
---|
977 | </desc>
|
---|
978 | </attribute>
|
---|
979 |
|
---|
980 | <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
981 | <desc>
|
---|
982 | Next error object if there is any, or @c null otherwise.
|
---|
983 | <note>
|
---|
984 | In MS COM, there is no equivalent.
|
---|
985 | In XPCOM, it is the same as nsIException::inner.
|
---|
986 | </note>
|
---|
987 | </desc>
|
---|
988 | </attribute>
|
---|
989 |
|
---|
990 | </interface>
|
---|
991 |
|
---|
992 |
|
---|
993 | <!--
|
---|
994 | // IVirtualBox
|
---|
995 | /////////////////////////////////////////////////////////////////////////
|
---|
996 | -->
|
---|
997 |
|
---|
998 | <interface
|
---|
999 | name="IVirtualBoxCallback" extends="$unknown"
|
---|
1000 | uuid="5516cc08-fb81-47a6-b184-031e7bbd2997"
|
---|
1001 | wsmap="suppress"
|
---|
1002 | >
|
---|
1003 | <method name="onMachineStateChange">
|
---|
1004 | <desc>
|
---|
1005 | The execution state of the given machine has changed.
|
---|
1006 | <see>IMachine::state</see>
|
---|
1007 | </desc>
|
---|
1008 | <param name="machineId" type="uuid" dir="in">
|
---|
1009 | <desc>ID of the machine this event relates to.</desc>
|
---|
1010 | </param>
|
---|
1011 | <param name="state" type="MachineState" dir="in">
|
---|
1012 | <desc>New execution state.</desc>
|
---|
1013 | </param>
|
---|
1014 | </method>
|
---|
1015 |
|
---|
1016 | <method name="onMachineDataChange">
|
---|
1017 | <desc>
|
---|
1018 | Any of the settings of the given machine has changed.
|
---|
1019 | </desc>
|
---|
1020 | <param name="machineId" type="uuid" dir="in">
|
---|
1021 | <desc>ID of the machine this event relates to.</desc>
|
---|
1022 | </param>
|
---|
1023 | </method>
|
---|
1024 |
|
---|
1025 | <method name="onExtraDataCanChange">
|
---|
1026 | <desc>
|
---|
1027 | Notification when someone tries to change extra data for
|
---|
1028 | either the given machine or (if null) global extra data.
|
---|
1029 | This gives the chance to veto against changes.
|
---|
1030 | </desc>
|
---|
1031 | <param name="machineId" type="uuid" dir="in">
|
---|
1032 | <desc>
|
---|
1033 | ID of the machine this event relates to
|
---|
1034 | (null ID for global extra data change requests).
|
---|
1035 | </desc>
|
---|
1036 | </param>
|
---|
1037 | <param name="key" type="wstring" dir="in">
|
---|
1038 | <desc>
|
---|
1039 | Extra data key for the attempted write.
|
---|
1040 | </desc>
|
---|
1041 | </param>
|
---|
1042 | <param name="value" type="wstring" dir="in">
|
---|
1043 | <desc>
|
---|
1044 | Extra data value for the given key.
|
---|
1045 | </desc>
|
---|
1046 | </param>
|
---|
1047 | <param name="error" type="wstring" dir="out">
|
---|
1048 | <desc>
|
---|
1049 | Optional error message describing the reason of the
|
---|
1050 | veto (ignored if this notification returns @c true).
|
---|
1051 | </desc>
|
---|
1052 | </param>
|
---|
1053 | <param name="allowChange" type="boolean" dir="return">
|
---|
1054 | <desc>
|
---|
1055 | Flag to indicate whether the callee agrees (@c true)
|
---|
1056 | or vetoes against the change (@c false).
|
---|
1057 | </desc>
|
---|
1058 | </param>
|
---|
1059 | </method>
|
---|
1060 |
|
---|
1061 | <method name="onExtraDataChange">
|
---|
1062 | <desc>
|
---|
1063 | Notification when machine specific or global extra data
|
---|
1064 | has changed.
|
---|
1065 | </desc>
|
---|
1066 | <param name="machineId" type="uuid" dir="in">
|
---|
1067 | <desc>
|
---|
1068 | ID of the machine this event relates to.
|
---|
1069 | Null for global extra data changes.
|
---|
1070 | </desc>
|
---|
1071 | </param>
|
---|
1072 | <param name="key" type="wstring" dir="in">
|
---|
1073 | <desc>
|
---|
1074 | Extra data key that has changed.
|
---|
1075 | </desc>
|
---|
1076 | </param>
|
---|
1077 | <param name="value" type="wstring" dir="in">
|
---|
1078 | <desc>
|
---|
1079 | Extra data value for the given key.
|
---|
1080 | </desc>
|
---|
1081 | </param>
|
---|
1082 | </method>
|
---|
1083 |
|
---|
1084 | <method name="onMediaRegistered">
|
---|
1085 | <desc>
|
---|
1086 | The given media was registered or unregistered
|
---|
1087 | within this VirtualBox installation.
|
---|
1088 |
|
---|
1089 | The @a mediaType parameter describes what type of
|
---|
1090 | media the specified @a mediaId refers to. Possible
|
---|
1091 | values are:
|
---|
1092 |
|
---|
1093 | <ul>
|
---|
1094 | <li><link to="DeviceType_HardDisk"/>: the media is a hard disk
|
---|
1095 | that, if registered, can be obtained using the
|
---|
1096 | <link to="IVirtualBox::getHardDisk"/> call.</li>
|
---|
1097 | <li><link to="DeviceType_DVD"/>: the media is a CD/DVD image
|
---|
1098 | that, if registered, can be obtained using the
|
---|
1099 | <link to="IVirtualBox::getDVDImage"/> call.</li>
|
---|
1100 | <li><link to="DeviceType_Floppy"/>: the media is a Floppy image
|
---|
1101 | that, if registered, can be obtained using the
|
---|
1102 | <link to="IVirtualBox::getFloppyImage"/> call.</li>
|
---|
1103 | </ul>
|
---|
1104 |
|
---|
1105 | Note that if this is a deregistration notification,
|
---|
1106 | there is no way to access the object representing the
|
---|
1107 | unregistered media. It is supposed that the
|
---|
1108 | application will do required cleanup based on the
|
---|
1109 | @a mediaId value.
|
---|
1110 | </desc>
|
---|
1111 | <param name="mediaId" type="uuid" dir="in">
|
---|
1112 | <desc>ID of the media this event relates to.</desc>
|
---|
1113 | </param>
|
---|
1114 | <param name="mediaType" type="DeviceType" dir="in">
|
---|
1115 | <desc>Type of the media this event relates to.</desc>
|
---|
1116 | </param>
|
---|
1117 | <param name="registered" type="boolean" dir="in">
|
---|
1118 | <desc>
|
---|
1119 | If true, the media was registered, otherwise it was
|
---|
1120 | unregistered.
|
---|
1121 | </desc>
|
---|
1122 | </param>
|
---|
1123 | </method>
|
---|
1124 |
|
---|
1125 | <method name="onMachineRegistered">
|
---|
1126 | <desc>
|
---|
1127 | The given machine was registered or unregistered
|
---|
1128 | within this VirtualBox installation.
|
---|
1129 | </desc>
|
---|
1130 | <param name="machineId" type="uuid" dir="in">
|
---|
1131 | <desc>ID of the machine this event relates to.</desc>
|
---|
1132 | </param>
|
---|
1133 | <param name="registered" type="boolean" dir="in">
|
---|
1134 | <desc>
|
---|
1135 | If true, the machine was registered, otherwise it was
|
---|
1136 | unregistered.
|
---|
1137 | </desc>
|
---|
1138 | </param>
|
---|
1139 | </method>
|
---|
1140 |
|
---|
1141 | <method name="onSessionStateChange">
|
---|
1142 | <desc>
|
---|
1143 | The state of the session for the given machine was changed.
|
---|
1144 | <see>IMachine::sessionState</see>
|
---|
1145 | </desc>
|
---|
1146 | <param name="machineId" type="uuid" dir="in">
|
---|
1147 | <desc>ID of the machine this event relates to.</desc>
|
---|
1148 | </param>
|
---|
1149 | <param name="state" type="SessionState" dir="in">
|
---|
1150 | <desc>New session state.</desc>
|
---|
1151 | </param>
|
---|
1152 | </method>
|
---|
1153 |
|
---|
1154 | <method name="onSnapshotTaken">
|
---|
1155 | <desc>
|
---|
1156 | A new snapshot of the machine has been taken.
|
---|
1157 | <see>ISnapshot</see>
|
---|
1158 | </desc>
|
---|
1159 | <param name="machineId" type="uuid" dir="in">
|
---|
1160 | <desc>ID of the machine this event relates to.</desc>
|
---|
1161 | </param>
|
---|
1162 | <param name="snapshotId" type="uuid" dir="in">
|
---|
1163 | <desc>ID of the new snapshot.</desc>
|
---|
1164 | </param>
|
---|
1165 | </method>
|
---|
1166 |
|
---|
1167 | <method name="onSnapshotDiscarded">
|
---|
1168 | <desc>
|
---|
1169 | Snapshot of the given machine has been discarded.
|
---|
1170 |
|
---|
1171 | <note>
|
---|
1172 | This notification is delivered <b>after</b> the snapshot
|
---|
1173 | object has been uninitialized on the server (so that any
|
---|
1174 | attempt to call its methods will return an error).
|
---|
1175 | </note>
|
---|
1176 |
|
---|
1177 | <see>ISnapshot</see>
|
---|
1178 | </desc>
|
---|
1179 | <param name="machineId" type="uuid" dir="in">
|
---|
1180 | <desc>ID of the machine this event relates to.</desc>
|
---|
1181 | </param>
|
---|
1182 | <param name="snapshotId" type="uuid" dir="in">
|
---|
1183 | <desc>
|
---|
1184 | ID of the discarded snapshot. <tt>null</tt> means the
|
---|
1185 | current machine state has been discarded (restored from
|
---|
1186 | the current snapshot).
|
---|
1187 | </desc>
|
---|
1188 | </param>
|
---|
1189 | </method>
|
---|
1190 |
|
---|
1191 | <method name="onSnapshotChange">
|
---|
1192 | <desc>
|
---|
1193 | Snapshot properties (name and/or description) have been changed.
|
---|
1194 | <see>ISnapshot</see>
|
---|
1195 | </desc>
|
---|
1196 | <param name="machineId" type="uuid" dir="in">
|
---|
1197 | <desc>ID of the machine this event relates to.</desc>
|
---|
1198 | </param>
|
---|
1199 | <param name="snapshotId" type="uuid" dir="in">
|
---|
1200 | <desc>ID of the changed snapshot.</desc>
|
---|
1201 | </param>
|
---|
1202 | </method>
|
---|
1203 |
|
---|
1204 | <method name="onGuestPropertyChange">
|
---|
1205 | <desc>
|
---|
1206 | Notification when a guest property has changed.
|
---|
1207 | </desc>
|
---|
1208 | <param name="machineId" type="uuid" dir="in">
|
---|
1209 | <desc>
|
---|
1210 | ID of the machine this event relates to.
|
---|
1211 | </desc>
|
---|
1212 | </param>
|
---|
1213 | <param name="name" type="wstring" dir="in">
|
---|
1214 | <desc>
|
---|
1215 | The name of the property that has changed.
|
---|
1216 | </desc>
|
---|
1217 | </param>
|
---|
1218 | <param name="value" type="wstring" dir="in">
|
---|
1219 | <desc>
|
---|
1220 | The new property value.
|
---|
1221 | </desc>
|
---|
1222 | </param>
|
---|
1223 | <param name="flags" type="wstring" dir="in">
|
---|
1224 | <desc>
|
---|
1225 | The new property flags.
|
---|
1226 | </desc>
|
---|
1227 | </param>
|
---|
1228 | </method>
|
---|
1229 |
|
---|
1230 | </interface>
|
---|
1231 |
|
---|
1232 | <interface
|
---|
1233 | name="IDHCPServer" extends="$unknown"
|
---|
1234 | uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
|
---|
1235 | wsmap="managed"
|
---|
1236 | >
|
---|
1237 | <desc>
|
---|
1238 | The IDHCPServer interface represents the vbox dhcp server configuration.
|
---|
1239 |
|
---|
1240 | To enumerate all the dhcp servers on the host, use the
|
---|
1241 | <link to="IVirtualBox::DHCPServers"/> attribute.
|
---|
1242 | </desc>
|
---|
1243 |
|
---|
1244 | <attribute name="enabled" type="boolean">
|
---|
1245 | <desc>
|
---|
1246 | specifies if the dhcp server is enabled
|
---|
1247 | </desc>
|
---|
1248 | </attribute>
|
---|
1249 |
|
---|
1250 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
1251 | <desc>
|
---|
1252 | specifies server IP
|
---|
1253 | </desc>
|
---|
1254 | </attribute>
|
---|
1255 |
|
---|
1256 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
1257 | <desc>
|
---|
1258 | specifies server network mask
|
---|
1259 | </desc>
|
---|
1260 | </attribute>
|
---|
1261 |
|
---|
1262 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
1263 | <desc>
|
---|
1264 | specifies internal network name the server is used for
|
---|
1265 | </desc>
|
---|
1266 | </attribute>
|
---|
1267 |
|
---|
1268 | <attribute name="lowerIP" type="wstring" readonly="yes">
|
---|
1269 | <desc>
|
---|
1270 | specifies from IP adrres in server address range
|
---|
1271 | </desc>
|
---|
1272 | </attribute>
|
---|
1273 |
|
---|
1274 | <attribute name="upperIP" type="wstring" readonly="yes">
|
---|
1275 | <desc>
|
---|
1276 | specifies to IP adrres in server address range
|
---|
1277 | </desc>
|
---|
1278 | </attribute>
|
---|
1279 |
|
---|
1280 | <method name="setConfiguration">
|
---|
1281 | <desc>
|
---|
1282 | configures the server
|
---|
1283 | <result name="E_INVALIDARG">
|
---|
1284 | invalid configuration supplied
|
---|
1285 | </result>
|
---|
1286 | </desc>
|
---|
1287 | <param name="IPAddress" type="wstring" dir="in">
|
---|
1288 | <desc>
|
---|
1289 | server IP address
|
---|
1290 | </desc>
|
---|
1291 | </param>
|
---|
1292 | <param name="networkMask" type="wstring" dir="in">
|
---|
1293 | <desc>
|
---|
1294 | server network mask
|
---|
1295 | </desc>
|
---|
1296 | </param>
|
---|
1297 | <param name="FromIPAddress" type="wstring" dir="in">
|
---|
1298 | <desc>
|
---|
1299 | server From IP address for address range
|
---|
1300 | </desc>
|
---|
1301 | </param>
|
---|
1302 | <param name="ToIPAddress" type="wstring" dir="in">
|
---|
1303 | <desc>
|
---|
1304 | server To IP address for address range
|
---|
1305 | </desc>
|
---|
1306 | </param>
|
---|
1307 | </method>
|
---|
1308 |
|
---|
1309 | <method name="start">
|
---|
1310 | <desc>
|
---|
1311 | Starts DHCP server process.
|
---|
1312 | <result name="E_FAIL">
|
---|
1313 | Failed to start the process.
|
---|
1314 | </result>
|
---|
1315 | </desc>
|
---|
1316 | <param name="networkName" type="wstring" dir="in">
|
---|
1317 | <desc>
|
---|
1318 | Name of internal network DHCP server should attach to.
|
---|
1319 | </desc>
|
---|
1320 | </param>
|
---|
1321 | <param name="trunkName" type="wstring" dir="in">
|
---|
1322 | <desc>
|
---|
1323 | Name of internal network trunk.
|
---|
1324 | </desc>
|
---|
1325 | </param>
|
---|
1326 | <param name="trunkType" type="wstring" dir="in">
|
---|
1327 | <desc>
|
---|
1328 | Type of internal network trunk.
|
---|
1329 | </desc>
|
---|
1330 | </param>
|
---|
1331 | </method>
|
---|
1332 |
|
---|
1333 | <method name="stop">
|
---|
1334 | <desc>
|
---|
1335 | Stops DHCP server process.
|
---|
1336 | <result name="E_FAIL">
|
---|
1337 | Failed to stop the process.
|
---|
1338 | </result>
|
---|
1339 | </desc>
|
---|
1340 | </method>
|
---|
1341 | </interface>
|
---|
1342 |
|
---|
1343 | <interface
|
---|
1344 | name="IVirtualBox" extends="$dispatched"
|
---|
1345 | uuid="779264f4-65ed-48ed-be39-518ca549e296"
|
---|
1346 | wsmap="managed"
|
---|
1347 | >
|
---|
1348 | <desc>
|
---|
1349 | The IVirtualBox interface represents the main interface exposed by the
|
---|
1350 | product that provides virtual machine management.
|
---|
1351 |
|
---|
1352 | An instance of IVirtualBox is required for the product to do anything
|
---|
1353 | useful. Even though the interface does not expose this, internally,
|
---|
1354 | IVirtualBox is implemented as a singleton and actually lives in the
|
---|
1355 | process of the VirtualBox server (VBoxSVC.exe). This makes sure that
|
---|
1356 | IVirtualBox can track the state of all virtual machines on a particular
|
---|
1357 | host, regardless of which frontend started them.
|
---|
1358 |
|
---|
1359 | To enumerate all the virtual machines on the host, use the
|
---|
1360 | <link to="IVirtualBox::machines"/> attribute.
|
---|
1361 | </desc>
|
---|
1362 |
|
---|
1363 | <attribute name="version" type="wstring" readonly="yes">
|
---|
1364 | <desc>
|
---|
1365 | A string representing the version number of the product. The
|
---|
1366 | format is 3 integer numbers divided by dots (e.g. 1.0.1). The
|
---|
1367 | last number represents the build number and will frequently change.
|
---|
1368 | </desc>
|
---|
1369 | </attribute>
|
---|
1370 |
|
---|
1371 | <attribute name="revision" type="unsigned long" readonly="yes">
|
---|
1372 | <desc>
|
---|
1373 | The internal build revision number of the product.
|
---|
1374 | </desc>
|
---|
1375 | </attribute>
|
---|
1376 |
|
---|
1377 | <attribute name="packageType" type="wstring" readonly="yes">
|
---|
1378 | <desc>
|
---|
1379 | A string representing the package type of this product. The
|
---|
1380 | format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
|
---|
1381 | SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
|
---|
1382 | is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
|
---|
1383 | this.
|
---|
1384 | </desc>
|
---|
1385 | </attribute>
|
---|
1386 |
|
---|
1387 | <attribute name="homeFolder" type="wstring" readonly="yes">
|
---|
1388 | <desc>
|
---|
1389 | Full path to the directory where the global settings file,
|
---|
1390 | <tt>VirtualBox.xml</tt>, is stored.
|
---|
1391 |
|
---|
1392 | In this version of VirtualBox, the value of this property is
|
---|
1393 | always <tt><user_dir>/.VirtualBox</tt> (where
|
---|
1394 | <tt><user_dir></tt> is the path to the user directory,
|
---|
1395 | as determined by the host OS), and cannot be changed.
|
---|
1396 |
|
---|
1397 | This path is also used as the base to resolve relative paths in
|
---|
1398 | places where relative paths are allowed (unless otherwise
|
---|
1399 | expressly indicated).
|
---|
1400 | </desc>
|
---|
1401 | </attribute>
|
---|
1402 |
|
---|
1403 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
1404 | <desc>
|
---|
1405 | Full name of the global settings file.
|
---|
1406 | The value of this property corresponds to the value of
|
---|
1407 | <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
|
---|
1408 | </desc>
|
---|
1409 | </attribute>
|
---|
1410 |
|
---|
1411 | <attribute name="settingsFileVersion" type="wstring" readonly="yes">
|
---|
1412 | <desc>
|
---|
1413 | Current version of the format of the global VirtualBox settings file
|
---|
1414 | (<tt>VirtualBox.xml</tt>).
|
---|
1415 |
|
---|
1416 | The version string has the following format:
|
---|
1417 | <pre>
|
---|
1418 | x.y-platform
|
---|
1419 | </pre>
|
---|
1420 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
1421 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
1422 |
|
---|
1423 | The current version usually matches the value of the
|
---|
1424 | <link to="#settingsFormatVersion"/> attribute unless the
|
---|
1425 | settings file was created by an older version of VirtualBox and there
|
---|
1426 | was a change of the settings file format since then.
|
---|
1427 |
|
---|
1428 | Note that VirtualBox automatically converts settings files from older
|
---|
1429 | versions to the most recent version when reading them (usually at
|
---|
1430 | VirtualBox startup) but it doesn't save the changes back until
|
---|
1431 | you call a method that implicitly saves settings (such as
|
---|
1432 | <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
|
---|
1433 | explicitly. Therefore, if the value of this attribute differs from the
|
---|
1434 | value of <link to="#settingsFormatVersion"/>, then it
|
---|
1435 | means that the settings file was converted but the result of the
|
---|
1436 | conversion is not yet saved to disk.
|
---|
1437 |
|
---|
1438 | The above feature may be used by interactive front-ends to inform users
|
---|
1439 | about the settings file format change and offer them to explicitly save
|
---|
1440 | all converted settings files (the global and VM-specific ones),
|
---|
1441 | optionally create backup copies of the old settings files before saving,
|
---|
1442 | etc.
|
---|
1443 |
|
---|
1444 | <see>settingsFormatVersion, saveSettingsWithBackup()</see>
|
---|
1445 | </desc>
|
---|
1446 | </attribute>
|
---|
1447 |
|
---|
1448 | <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
|
---|
1449 | <desc>
|
---|
1450 | Most recent version of the settings file format.
|
---|
1451 |
|
---|
1452 | The version string has the following format:
|
---|
1453 | <pre>
|
---|
1454 | x.y-platform
|
---|
1455 | </pre>
|
---|
1456 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
1457 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
1458 |
|
---|
1459 | VirtualBox uses this version of the format when saving settings files
|
---|
1460 | (either as a result of method calls that require to save settings or as
|
---|
1461 | a result of an explicit call to <link to="#saveSettings"/>).
|
---|
1462 |
|
---|
1463 | <see>settingsFileVersion</see>
|
---|
1464 | </desc>
|
---|
1465 | </attribute>
|
---|
1466 |
|
---|
1467 | <attribute name="host" type="IHost" readonly="yes">
|
---|
1468 | <desc>Associated host object.</desc>
|
---|
1469 | </attribute>
|
---|
1470 |
|
---|
1471 | <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
|
---|
1472 | <desc>Associated system information object.</desc>
|
---|
1473 | </attribute>
|
---|
1474 |
|
---|
1475 | <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
|
---|
1476 | <desc>
|
---|
1477 | Array of machine objects registered within this VirtualBox instance.
|
---|
1478 | </desc>
|
---|
1479 | </attribute>
|
---|
1480 |
|
---|
1481 | <attribute name="hardDisks" type="IHardDisk" readonly="yes" safearray="yes">
|
---|
1482 | <desc>
|
---|
1483 | Array of hard disk objects known to this VirtualBox installation.
|
---|
1484 |
|
---|
1485 | This array contains only base (root) hard disks. All differencing
|
---|
1486 | hard disks of the given base hard disk can be enumerated using
|
---|
1487 | <link to="IHardDisk::children"/>.
|
---|
1488 | </desc>
|
---|
1489 | </attribute>
|
---|
1490 |
|
---|
1491 | <attribute name="DVDImages" type="IDVDImage" readonly="yes" safearray="yes">
|
---|
1492 | <desc>
|
---|
1493 | Array of CD/DVD image objects registered with this VirtualBox instance.
|
---|
1494 | </desc>
|
---|
1495 | </attribute>
|
---|
1496 |
|
---|
1497 | <attribute name="floppyImages" type="IFloppyImage" readonly="yes" safearray="yes">
|
---|
1498 | <desc>
|
---|
1499 | Array of floppy image objects registered with this VirtualBox instance.
|
---|
1500 | </desc>
|
---|
1501 | </attribute>
|
---|
1502 |
|
---|
1503 | <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
|
---|
1504 |
|
---|
1505 | <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
|
---|
1506 |
|
---|
1507 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
1508 | <desc>
|
---|
1509 | Collection of global shared folders. Global shared folders are
|
---|
1510 | available to all virtual machines.
|
---|
1511 |
|
---|
1512 | New shared folders are added to the collection using
|
---|
1513 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
1514 | removed using <link to="#removeSharedFolder"/>.
|
---|
1515 |
|
---|
1516 | <note>
|
---|
1517 | In the current version of the product, global shared folders are not
|
---|
1518 | implemented and therefore this collection is always empty.
|
---|
1519 | </note>
|
---|
1520 | </desc>
|
---|
1521 | </attribute>
|
---|
1522 |
|
---|
1523 | <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
|
---|
1524 | <desc>
|
---|
1525 | Associated performance collector object.
|
---|
1526 | </desc>
|
---|
1527 | </attribute>
|
---|
1528 |
|
---|
1529 | <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
|
---|
1530 | <desc>
|
---|
1531 | dhcp server settings.
|
---|
1532 | </desc>
|
---|
1533 | </attribute>
|
---|
1534 |
|
---|
1535 | <method name="createMachine">
|
---|
1536 | <desc>
|
---|
1537 | Creates a new virtual machine.
|
---|
1538 |
|
---|
1539 | The new machine is created unregistered, with the initial configuration
|
---|
1540 | set according to the specified guest OS type. A typical sequence of
|
---|
1541 | actions to create a new virtual machine is as follows:
|
---|
1542 |
|
---|
1543 | <ol>
|
---|
1544 | <li>
|
---|
1545 | Call this method to have a new machine created. The returned machine
|
---|
1546 | object will be "mutable" allowing to change any machine property.
|
---|
1547 | </li>
|
---|
1548 |
|
---|
1549 | <li>
|
---|
1550 | Configure the machine using the appropriate attributes and methods.
|
---|
1551 | </li>
|
---|
1552 |
|
---|
1553 | <li>
|
---|
1554 | Call <link to="IMachine::saveSettings" /> to write the settings
|
---|
1555 | to the machine's XML settings file. The configuration of the newly
|
---|
1556 | created machine will not be saved to disk until this method is
|
---|
1557 | called.
|
---|
1558 | </li>
|
---|
1559 |
|
---|
1560 | <li>
|
---|
1561 | Call <link to="#registerMachine" /> to add the machine to the list
|
---|
1562 | of machines known to VirtualBox.
|
---|
1563 | </li>
|
---|
1564 | </ol>
|
---|
1565 |
|
---|
1566 | You should specify valid name for the newly created machine when calling
|
---|
1567 | this method. See the <link to="IMachine::name"/> attribute description
|
---|
1568 | for more details about the machine name.
|
---|
1569 |
|
---|
1570 | The specified guest OS type identifier must match an ID of one of known
|
---|
1571 | guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
|
---|
1572 | array.
|
---|
1573 |
|
---|
1574 | Every machine has a <i>settings file</i> that is used to store
|
---|
1575 | the machine configuration. This file is stored in a directory called the
|
---|
1576 | <i>machine settings subfolder</i>. Both the settings subfolder and file
|
---|
1577 | will have a name that corresponds to the name of the virtual machine.
|
---|
1578 | You can specify where to create the machine setting subfolder using the
|
---|
1579 | @a baseFolder argument. The base folder can be absolute (full path) or
|
---|
1580 | relative to the <link to="IVirtualBox::homeFolder">VirtualBox home
|
---|
1581 | directory</link>.
|
---|
1582 |
|
---|
1583 | If @a baseFolder is a null or empty string (which is recommended), the
|
---|
1584 | <link to="ISystemProperties::defaultMachineFolder">default machine
|
---|
1585 | settings folder</link> will be used as a base folder for the created
|
---|
1586 | machine. Otherwise the given base folder will be used. In either case,
|
---|
1587 | the full path to the resulting settings file has the following
|
---|
1588 | structure:
|
---|
1589 | <pre>
|
---|
1590 | <base_folder>/<machine_name>/<machine_name>.xml
|
---|
1591 | </pre>
|
---|
1592 |
|
---|
1593 | Note that if the resulting settings file already exists, this method
|
---|
1594 | will fail with <link to="VBOX_E_FILE_ERROR"/>.
|
---|
1595 |
|
---|
1596 | Optionally, you may specify an UUID of to assign to the created machine.
|
---|
1597 | However, this is not recommended and you should normally pass an empty
|
---|
1598 | (null) UUID to this method so that a new UUID will be automatically
|
---|
1599 | generated for every created machine. You can use UUID
|
---|
1600 | 00000000-0000-0000-0000-000000000000 as null value.
|
---|
1601 |
|
---|
1602 | <note>
|
---|
1603 | There is no way to change the name of the settings file or
|
---|
1604 | subfolder of the created machine directly.
|
---|
1605 | </note>
|
---|
1606 |
|
---|
1607 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1608 | @a osTypeId is invalid.
|
---|
1609 | </result>
|
---|
1610 | <result name="VBOX_E_FILE_ERROR">
|
---|
1611 | Resulting settings file name is invalid or the settings file already
|
---|
1612 | exists or could not be created due to an I/O error.
|
---|
1613 | </result>
|
---|
1614 | <result name="E_INVALIDARG">
|
---|
1615 | @a name is empty or null.
|
---|
1616 | </result>
|
---|
1617 | </desc>
|
---|
1618 |
|
---|
1619 | <param name="name" type="wstring" dir="in">
|
---|
1620 | <desc>Machine name.</desc>
|
---|
1621 | </param>
|
---|
1622 | <param name="osTypeId" type="wstring" dir="in">
|
---|
1623 | <desc>Guest OS Type ID.</desc>
|
---|
1624 | </param>
|
---|
1625 | <param name="baseFolder" type="wstring" dir="in">
|
---|
1626 | <desc>Base machine folder (optional).</desc>
|
---|
1627 | </param>
|
---|
1628 | <param name="id" type="uuid" dir="in">
|
---|
1629 | <desc>Machine UUID (optional).</desc>
|
---|
1630 | </param>
|
---|
1631 | <param name="machine" type="IMachine" dir="return">
|
---|
1632 | <desc>Created machine object.</desc>
|
---|
1633 | </param>
|
---|
1634 | </method>
|
---|
1635 |
|
---|
1636 | <method name="createLegacyMachine">
|
---|
1637 | <desc>
|
---|
1638 | Creates a new virtual machine in "legacy" mode, using the specified
|
---|
1639 | settings file to store machine settings.
|
---|
1640 |
|
---|
1641 | As opposed to machines created by <link to="#createMachine"/>,
|
---|
1642 | the settings file of the machine created in "legacy" mode is not
|
---|
1643 | automatically renamed when the machine name is changed -- it will always
|
---|
1644 | remain the same as specified in this method call.
|
---|
1645 |
|
---|
1646 | The specified settings file name can be absolute (full path) or relative
|
---|
1647 | to the <link to="IVirtualBox::homeFolder">VirtualBox home
|
---|
1648 | directory</link>. If the file name doesn't contain an extension, the
|
---|
1649 | default extension (.xml) will be appended.
|
---|
1650 |
|
---|
1651 | Note that the configuration of the newly created machine is not
|
---|
1652 | saved to disk (and therefore no settings file is created)
|
---|
1653 | until <link to="IMachine::saveSettings"/> is called. If the
|
---|
1654 | specified settings file already exists, this method
|
---|
1655 | will fail with <link to="VBOX_E_FILE_ERROR"/>.
|
---|
1656 |
|
---|
1657 | See <link to="#createMachine"/> for more information.
|
---|
1658 |
|
---|
1659 | @deprecated This method may be removed later. Use <link
|
---|
1660 | to="IVirtualBox::createMachine"/> instead.
|
---|
1661 |
|
---|
1662 | <note>
|
---|
1663 | There is no way to change the name of the settings file
|
---|
1664 | of the machine created in "legacy" mode.
|
---|
1665 | </note>
|
---|
1666 |
|
---|
1667 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1668 | @a osTypeId is invalid.
|
---|
1669 | </result>
|
---|
1670 | <result name="VBOX_E_FILE_ERROR">
|
---|
1671 | @a settingsFile is invalid or the settings file already exists or
|
---|
1672 | could not be created due to an I/O error.
|
---|
1673 | </result>
|
---|
1674 | <result name="E_INVALIDARG">
|
---|
1675 | @a name or @a settingsFile is empty or null.
|
---|
1676 | </result>
|
---|
1677 | </desc>
|
---|
1678 |
|
---|
1679 | <param name="name" type="wstring" dir="in">
|
---|
1680 | <desc>Machine name.</desc>
|
---|
1681 | </param>
|
---|
1682 | <param name="osTypeId" type="wstring" dir="in">
|
---|
1683 | <desc>Machine OS Type ID.</desc>
|
---|
1684 | </param>
|
---|
1685 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1686 | <desc>Name of the machine settings file.</desc>
|
---|
1687 | </param>
|
---|
1688 | <param name="id" type="uuid" dir="in">
|
---|
1689 | <desc>Machine UUID (optional).</desc>
|
---|
1690 | </param>
|
---|
1691 | <param name="machine" type="IMachine" dir="return">
|
---|
1692 | <desc>Created machine object.</desc>
|
---|
1693 | </param>
|
---|
1694 | </method>
|
---|
1695 |
|
---|
1696 | <method name="openMachine">
|
---|
1697 | <desc>
|
---|
1698 | Opens a virtual machine from the existing settings file.
|
---|
1699 | The opened machine remains unregistered until you call
|
---|
1700 | <link to="#registerMachine"/>.
|
---|
1701 |
|
---|
1702 | The specified settings file name can be absolute
|
---|
1703 | (full path) or relative to the <link to="IVirtualBox::homeFolder">
|
---|
1704 | VirtualBox home directory</link>. This file must exist
|
---|
1705 | and must be a valid machine settings file whose contents
|
---|
1706 | will be used to construct the machine object.
|
---|
1707 |
|
---|
1708 | @deprecated Will be removed soon.
|
---|
1709 | <result name="VBOX_E_FILE_ERROR">
|
---|
1710 | Settings file name invalid, not found or sharing violation.
|
---|
1711 | </result>
|
---|
1712 | </desc>
|
---|
1713 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1714 | <desc>
|
---|
1715 | Name of the machine settings file.
|
---|
1716 | </desc>
|
---|
1717 | </param>
|
---|
1718 | <param name="machine" type="IMachine" dir="return">
|
---|
1719 | <desc>Opened machine object.</desc>
|
---|
1720 | </param>
|
---|
1721 | <note>
|
---|
1722 | <link to="IMachine::settingsModified"/> will return
|
---|
1723 | false for the created machine, until any of machine settings
|
---|
1724 | are changed.
|
---|
1725 | </note>
|
---|
1726 | </method>
|
---|
1727 |
|
---|
1728 | <method name="registerMachine">
|
---|
1729 | <desc>
|
---|
1730 |
|
---|
1731 | Registers the machine previously created using
|
---|
1732 | <link to="#createMachine"/> or opened using
|
---|
1733 | <link to="#openMachine"/> within this VirtualBox installation. After
|
---|
1734 | successful method invocation, the
|
---|
1735 | <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
|
---|
1736 | to all registered callbacks.
|
---|
1737 |
|
---|
1738 | <note>
|
---|
1739 | This method implicitly calls <link to="IMachine::saveSettings"/>
|
---|
1740 | to save all current machine settings before registering it.
|
---|
1741 | </note>
|
---|
1742 |
|
---|
1743 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1744 | No matching virtual machine found.
|
---|
1745 | </result>
|
---|
1746 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1747 | Virtual machine was not created within this VirtualBox instance.
|
---|
1748 | </result>
|
---|
1749 |
|
---|
1750 | </desc>
|
---|
1751 | <param name="machine" type="IMachine" dir="in"/>
|
---|
1752 | </method>
|
---|
1753 |
|
---|
1754 | <method name="getMachine">
|
---|
1755 | <desc>
|
---|
1756 | Attempts to find a virtual machine given its UUID.
|
---|
1757 | To look up a machine by name, use <link to="IVirtualBox::findMachine" />
|
---|
1758 | instead.
|
---|
1759 |
|
---|
1760 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1761 | Could not find registered machine matching @a id.
|
---|
1762 | </result>
|
---|
1763 |
|
---|
1764 | </desc>
|
---|
1765 | <param name="id" type="uuid" dir="in"/>
|
---|
1766 | <param name="machine" type="IMachine" dir="return"/>
|
---|
1767 | </method>
|
---|
1768 |
|
---|
1769 | <method name="findMachine">
|
---|
1770 | <desc>
|
---|
1771 | Attempts to find a virtual machine given its name.
|
---|
1772 | To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
|
---|
1773 | instead.
|
---|
1774 |
|
---|
1775 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1776 | Could not find registered machine matching @a name.
|
---|
1777 | </result>
|
---|
1778 |
|
---|
1779 | </desc>
|
---|
1780 | <param name="name" type="wstring" dir="in"/>
|
---|
1781 | <param name="machine" type="IMachine" dir="return"/>
|
---|
1782 | </method>
|
---|
1783 |
|
---|
1784 | <method name="unregisterMachine">
|
---|
1785 | <desc>
|
---|
1786 |
|
---|
1787 | Unregisters the machine previously registered using
|
---|
1788 | <link to="#registerMachine"/>. After successful method invocation, the
|
---|
1789 | <link to="IVirtualBoxCallback::onMachineRegistered"/> signal is sent
|
---|
1790 | to all registered callbacks.
|
---|
1791 |
|
---|
1792 | <note>
|
---|
1793 | The specified machine must not be in the Saved state, have an open
|
---|
1794 | (or a spawning) direct session associated with it, have snapshots or
|
---|
1795 | have hard disks attached.
|
---|
1796 | </note>
|
---|
1797 |
|
---|
1798 | <note>
|
---|
1799 | This method implicitly calls <link to="IMachine::saveSettings"/> to
|
---|
1800 | save all current machine settings before unregistering it.
|
---|
1801 | </note>
|
---|
1802 |
|
---|
1803 | <note>
|
---|
1804 | If the given machine is inaccessible (see
|
---|
1805 | <link to="IMachine::accessible"/>), it will be unregistered and
|
---|
1806 | fully uninitialized right afterwards. As a result, the returned
|
---|
1807 | machine object will be unusable and an attempt to call
|
---|
1808 | <b>any</b> method will return the "Object not ready" error.
|
---|
1809 | </note>
|
---|
1810 |
|
---|
1811 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1812 | Could not find registered machine matching @a id.
|
---|
1813 | </result>
|
---|
1814 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
1815 | Machine is in Saved state.
|
---|
1816 | </result>
|
---|
1817 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1818 | Machine has snapshot or open session or hard disk attached.
|
---|
1819 | </result>
|
---|
1820 |
|
---|
1821 | </desc>
|
---|
1822 | <param name="id" type="uuid" dir="in">
|
---|
1823 | <desc>UUID of the machine to unregister.</desc>
|
---|
1824 | </param>
|
---|
1825 | <param name="machine" type="IMachine" dir="return">
|
---|
1826 | <desc>Unregistered machine object.</desc>
|
---|
1827 | </param>
|
---|
1828 | </method>
|
---|
1829 |
|
---|
1830 | <method name="createAppliance">
|
---|
1831 | <desc>
|
---|
1832 | Creates a new appliance object, which represents an appliance in the Open Virtual Machine
|
---|
1833 | Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
|
---|
1834 | machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
|
---|
1835 | </desc>
|
---|
1836 | <param name="appliance" type="IAppliance" dir="return">
|
---|
1837 | <desc>New appliance.</desc>
|
---|
1838 | </param>
|
---|
1839 | </method>
|
---|
1840 |
|
---|
1841 | <method name="createHardDisk">
|
---|
1842 | <desc>
|
---|
1843 | Creates a new base hard disk object that will use the given storage
|
---|
1844 | format and location for hard disk data.
|
---|
1845 |
|
---|
1846 | Note that the actual storage unit is not created by this method. In
|
---|
1847 | order to do it, and before you are able to attach the created hard disk
|
---|
1848 | to virtual machines, you must call one of the following methods to
|
---|
1849 | allocate a format-specific storage unit at the specified location:
|
---|
1850 | <ul>
|
---|
1851 | <li><link to="IHardDisk::createBaseStorage"/></li>
|
---|
1852 | <li><link to="IHardDisk::createDiffStorage"/></li>
|
---|
1853 | </ul>
|
---|
1854 |
|
---|
1855 | Some hard disk attributes, such as <link to="IHardDisk::id"/>, may
|
---|
1856 | remain uninitialized until the hard disk storage unit is successfully
|
---|
1857 | created by one of the above methods.
|
---|
1858 |
|
---|
1859 | After the storage unit is successfully created, the hard disk gets
|
---|
1860 | remembered by this VirtualBox installation and will be accessible
|
---|
1861 | through <link to="#getHardDisk"/> and <link to="#findHardDisk"/>
|
---|
1862 | methods. Remembered root (base) hard disks are also returned as part of
|
---|
1863 | the <link to="#hardDisks"/> array. See IHardDisk for more details.
|
---|
1864 |
|
---|
1865 | The list of all storage formats supported by this VirtualBox
|
---|
1866 | installation can be obtained using
|
---|
1867 | <link to="ISystemProperties::hardDiskFormats"/>. If the @a format
|
---|
1868 | attribute is empty or <tt>null</tt> then the default storage format
|
---|
1869 | specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
|
---|
1870 | be used for creating a storage unit of the hard disk.
|
---|
1871 |
|
---|
1872 | Note that the format of the location string is storage format specific.
|
---|
1873 | See <link to="IMedium::location"/>, IHardDisk and
|
---|
1874 | <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
|
---|
1875 |
|
---|
1876 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1877 | @a format identifier is invalid. See
|
---|
1878 | <link to="ISystemProperties::hardDiskFormats"/>.
|
---|
1879 | </result>
|
---|
1880 | <result name="VBOX_E_FILE_ERROR">
|
---|
1881 | @a location is a not valid file name (for file-based formats only).
|
---|
1882 | </result>
|
---|
1883 | <result name="E_INVALIDARG">
|
---|
1884 | @a format is a null or empty string.
|
---|
1885 | </result>
|
---|
1886 | </desc>
|
---|
1887 | <param name="format" type="wstring" dir="in">
|
---|
1888 | <desc>
|
---|
1889 | Identifier of the storage format to use for the new hard disk.
|
---|
1890 | </desc>
|
---|
1891 | </param>
|
---|
1892 | <param name="location" type="wstring" dir="in">
|
---|
1893 | <desc>
|
---|
1894 | Location of the storage unit for the new hard disk.
|
---|
1895 | </desc>
|
---|
1896 | </param>
|
---|
1897 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1898 | <desc>Created hard disk object.</desc>
|
---|
1899 | </param>
|
---|
1900 | </method>
|
---|
1901 |
|
---|
1902 | <method name="openHardDisk">
|
---|
1903 | <desc>
|
---|
1904 | Opens a hard disk from an existing location.
|
---|
1905 |
|
---|
1906 | After the hard disk is successfully opened by this method, it gets
|
---|
1907 | remembered by (known to) this VirtualBox installation and will be
|
---|
1908 | accessible through <link to="#getHardDisk"/> and
|
---|
1909 | <link to="#findHardDisk"/> methods. Remembered root (base) hard disks
|
---|
1910 | are also returned as part of the <link to="#hardDisks"/> array and can
|
---|
1911 | be attached to virtual machines. See IHardDisk for more details.
|
---|
1912 |
|
---|
1913 | If a differencing hard disk is to be opened by this method, the
|
---|
1914 | operation will succeed only if its parent hard disk and all ancestors,
|
---|
1915 | if any, are already known to this VirtualBox installation (for example,
|
---|
1916 | were opened by this method before).
|
---|
1917 |
|
---|
1918 | This method tries to guess the storage format of the specified hard disk
|
---|
1919 | by reading hard disk data at the specified location.
|
---|
1920 |
|
---|
1921 | If @a write is ReadWrite (which it should be), the image is opened for
|
---|
1922 | read/write access and must have according permissions, as VirtualBox
|
---|
1923 | may actually write status information into the disk's metadata sections.
|
---|
1924 |
|
---|
1925 | Note that write access is required for all typical image usage in VirtualBox,
|
---|
1926 | since VirtualBox may need to write metadata such as a UUID into the image.
|
---|
1927 | The only exception is opening a source image temporarily for copying and
|
---|
1928 | cloning when the image will quickly be closed again.
|
---|
1929 |
|
---|
1930 | Note that the format of the location string is storage format specific.
|
---|
1931 | See <link to="IMedium::location"/>, IHardDisk and
|
---|
1932 | <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
|
---|
1933 |
|
---|
1934 | <result name="VBOX_E_FILE_ERROR">
|
---|
1935 | Invalid hard disk storage file location or could not find the hard
|
---|
1936 | disk at the specified location.
|
---|
1937 | </result>
|
---|
1938 | <result name="VBOX_E_IPRT_ERROR">
|
---|
1939 | Could not get hard disk storage format.
|
---|
1940 | </result>
|
---|
1941 | <result name="E_INVALIDARG">
|
---|
1942 | Invalid hard disk storage format.
|
---|
1943 | </result>
|
---|
1944 |
|
---|
1945 | </desc>
|
---|
1946 | <param name="location" type="wstring" dir="in">
|
---|
1947 | <desc>
|
---|
1948 | Location of the storage unit that contains hard disk data in one of
|
---|
1949 | the supported storage formats.
|
---|
1950 | </desc>
|
---|
1951 | </param>
|
---|
1952 | <param name="accessMode" type="AccessMode" dir="in">
|
---|
1953 | <desc>
|
---|
1954 | Determines whether to open the image in read/write or read-only mode.
|
---|
1955 | </desc>
|
---|
1956 | </param>
|
---|
1957 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1958 | <desc>Opened hard disk object.</desc>
|
---|
1959 | </param>
|
---|
1960 | </method>
|
---|
1961 |
|
---|
1962 | <method name="getHardDisk" const="yes">
|
---|
1963 | <desc>
|
---|
1964 | Returns a hard disk with the given UUID.
|
---|
1965 |
|
---|
1966 | The hard disk with the given UUID must be known to this VirtualBox
|
---|
1967 | installation, i.e. it must be previously created by
|
---|
1968 | <link to="#createHardDisk"/> or opened by <link
|
---|
1969 | to="#openHardDisk"/>, or attached to some known virtual machine.
|
---|
1970 |
|
---|
1971 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1972 | No hard disk object matching @a id found.
|
---|
1973 | </result>
|
---|
1974 |
|
---|
1975 | </desc>
|
---|
1976 | <param name="id" type="uuid" dir="in">
|
---|
1977 | <desc>UUID of the hard disk to look for.</desc>
|
---|
1978 | </param>
|
---|
1979 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
1980 | <desc>Found hard disk object.</desc>
|
---|
1981 | </param>
|
---|
1982 | </method>
|
---|
1983 |
|
---|
1984 | <method name="findHardDisk">
|
---|
1985 | <desc>
|
---|
1986 | Returns a hard disk that uses the given location to store hard
|
---|
1987 | disk data.
|
---|
1988 |
|
---|
1989 | The given hard disk must be known to this VirtualBox installation, i.e.
|
---|
1990 | it must be previously created by
|
---|
1991 | <link to="#createHardDisk"/> or opened by <link
|
---|
1992 | to="#openHardDisk"/>, or attached to some known virtual machine.
|
---|
1993 |
|
---|
1994 | The search is done by comparing the value of the @a location argument to
|
---|
1995 | the <link to="IHardDisk::location"/> attribute of each known hard
|
---|
1996 | disk.
|
---|
1997 |
|
---|
1998 | For locations represented by file names in the host's file system, the
|
---|
1999 | requested location can be a path relative to the
|
---|
2000 | <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
|
---|
2001 | only a file name without any path is given, the
|
---|
2002 | <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
|
---|
2003 | folder</link> will be prepended to the file name before searching. Note
|
---|
2004 | that on case sensitive file systems, a case sensitive comparison is
|
---|
2005 | performed, otherwise the case of symbols in the file path is ignored.
|
---|
2006 |
|
---|
2007 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2008 | No hard disk object matching @a location found.
|
---|
2009 | </result>
|
---|
2010 |
|
---|
2011 | </desc>
|
---|
2012 | <param name="location" type="wstring" dir="in">
|
---|
2013 | <desc>Location string to search for.</desc>
|
---|
2014 | </param>
|
---|
2015 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
2016 | <desc>Found hard disk object.</desc>
|
---|
2017 | </param>
|
---|
2018 | </method>
|
---|
2019 |
|
---|
2020 | <method name="openDVDImage">
|
---|
2021 | <desc>
|
---|
2022 | Opens a CD/DVD image contained in the specified file of the supported
|
---|
2023 | format and assigns it the given UUID.
|
---|
2024 |
|
---|
2025 | After the image is successfully opened by this method, it gets
|
---|
2026 | remembered by (known to) this VirtualBox installation and will be
|
---|
2027 | accessible through <link to="#getDVDImage"/> and
|
---|
2028 | <link to="#findDVDImage"/> methods. Remembered images are also
|
---|
2029 | returned as part of the <link to="#DVDImages"/> array and can be mounted
|
---|
2030 | to virtual machines. See IMedium for more details.
|
---|
2031 |
|
---|
2032 | See <link to="IMedium::location"/> to get more details about the format
|
---|
2033 | of the location string.
|
---|
2034 |
|
---|
2035 | <note>
|
---|
2036 | Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
|
---|
2037 | </note>
|
---|
2038 |
|
---|
2039 | <result name="VBOX_E_FILE_ERROR">
|
---|
2040 | Invalid CD/DVD image file location or could not find the CD/DVD
|
---|
2041 | image at the specified location.
|
---|
2042 | </result>
|
---|
2043 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
2044 | CD/DVD image already exists in the media registry.
|
---|
2045 | </result>
|
---|
2046 |
|
---|
2047 | </desc>
|
---|
2048 | <param name="location" type="wstring" dir="in">
|
---|
2049 | <desc>
|
---|
2050 | Full path to the file that contains a valid CD/DVD image.
|
---|
2051 | </desc>
|
---|
2052 | </param>
|
---|
2053 | <param name="id" type="uuid" dir="in">
|
---|
2054 | <desc>
|
---|
2055 | UUID to assign to the given image within this VirtualBox installation.
|
---|
2056 | If an empty (null) UUID is specified, the system will randomly
|
---|
2057 | generate a new UUID.
|
---|
2058 | </desc>
|
---|
2059 | </param>
|
---|
2060 | <param name="image" type="IDVDImage" dir="return">
|
---|
2061 | <desc>Opened CD/DVD image object.</desc>
|
---|
2062 | </param>
|
---|
2063 | </method>
|
---|
2064 |
|
---|
2065 | <method name="getDVDImage">
|
---|
2066 | <desc>
|
---|
2067 | Returns a CD/DVD image with the given UUID.
|
---|
2068 |
|
---|
2069 | The image with the given UUID must be known to this VirtualBox
|
---|
2070 | installation, i.e. it must be previously opened by <link
|
---|
2071 | to="#openDVDImage"/>, or mounted to some known virtual machine.
|
---|
2072 |
|
---|
2073 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2074 | No matching DVD image found in the media registry.
|
---|
2075 | </result>
|
---|
2076 |
|
---|
2077 | </desc>
|
---|
2078 | <param name="id" type="uuid" dir="in">
|
---|
2079 | <desc>UUID of the image to look for.</desc>
|
---|
2080 | </param>
|
---|
2081 | <param name="image" type="IDVDImage" dir="return">
|
---|
2082 | <desc>Found CD/DVD image object.</desc>
|
---|
2083 | </param>
|
---|
2084 | </method>
|
---|
2085 |
|
---|
2086 | <method name="findDVDImage">
|
---|
2087 | <desc>
|
---|
2088 | Returns a CD/DVD image with the given image location.
|
---|
2089 |
|
---|
2090 | The image with the given UUID must be known to this VirtualBox
|
---|
2091 | installation, i.e. it must be previously opened by <link
|
---|
2092 | to="#openDVDImage"/>, or mounted to some known virtual machine.
|
---|
2093 |
|
---|
2094 | The search is done by comparing the value of the @a location argument to
|
---|
2095 | the <link to="IMedium::location"/> attribute of each known CD/DVD image.
|
---|
2096 |
|
---|
2097 | The requested location can be a path relative to the
|
---|
2098 | <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
|
---|
2099 | only a file name without any path is given, the
|
---|
2100 | <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
|
---|
2101 | folder</link> will be prepended to the file name before searching. Note
|
---|
2102 | that on case sensitive file systems, a case sensitive comparison is
|
---|
2103 | performed, otherwise the case in the file path is ignored.
|
---|
2104 |
|
---|
2105 | <result name="VBOX_E_FILE_ERROR">
|
---|
2106 | Invalid image file location.
|
---|
2107 | </result>
|
---|
2108 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2109 | No matching DVD image found in the media registry.
|
---|
2110 | </result>
|
---|
2111 |
|
---|
2112 | </desc>
|
---|
2113 | <param name="location" type="wstring" dir="in">
|
---|
2114 | <desc>CD/DVD image file path to look for.</desc>
|
---|
2115 | </param>
|
---|
2116 | <param name="image" type="IDVDImage" dir="return">
|
---|
2117 | <desc>Found CD/DVD image object.</desc>
|
---|
2118 | </param>
|
---|
2119 | </method>
|
---|
2120 |
|
---|
2121 | <method name="openFloppyImage">
|
---|
2122 | <desc>
|
---|
2123 | Opens a floppy image contained in the specified file of the supported
|
---|
2124 | format and assigns it the given UUID.
|
---|
2125 |
|
---|
2126 | After the image is successfully opened by this method, it gets
|
---|
2127 | remembered by (known to) this VirtualBox installation and will be
|
---|
2128 | accessible through <link to="#getFloppyImage"/> and
|
---|
2129 | <link to="#findFloppyImage"/> methods. Remembered images are also
|
---|
2130 | returned as part of the <link to="#floppyImages"/> array and can be
|
---|
2131 | mounted to virtual machines. See IMedium for more details.
|
---|
2132 |
|
---|
2133 | See <link to="IMedium::location"/> to get more details about the format
|
---|
2134 | of the location string.
|
---|
2135 |
|
---|
2136 | <result name="VBOX_E_FILE_ERROR">
|
---|
2137 | Invalid floppy image file location or could not find the floppy
|
---|
2138 | image at the specified location.
|
---|
2139 | </result>
|
---|
2140 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
2141 | Floppy image already exists in the media registry.
|
---|
2142 | </result>
|
---|
2143 |
|
---|
2144 | <note>
|
---|
2145 | Currently, only raw floppy images are supported by VirtualBox.
|
---|
2146 | </note>
|
---|
2147 | </desc>
|
---|
2148 | <param name="location" type="wstring" dir="in">
|
---|
2149 | <desc>
|
---|
2150 | Full path to the file that contains a valid floppy image.
|
---|
2151 | </desc>
|
---|
2152 | </param>
|
---|
2153 | <param name="id" type="uuid" dir="in">
|
---|
2154 | <desc>
|
---|
2155 | UUID to assign to the given image file within this VirtualBox
|
---|
2156 | installation. If an empty (null) UUID is specified, the system will
|
---|
2157 | randomly generate a new UUID.
|
---|
2158 | </desc>
|
---|
2159 | </param>
|
---|
2160 | <param name="image" type="IFloppyImage" dir="return">
|
---|
2161 | <desc>Opened floppy image object.</desc>
|
---|
2162 | </param>
|
---|
2163 | </method>
|
---|
2164 |
|
---|
2165 | <method name="getFloppyImage">
|
---|
2166 | <desc>
|
---|
2167 | Returns a floppy image with the given UUID.
|
---|
2168 |
|
---|
2169 | The image with the given UUID must be known to this VirtualBox
|
---|
2170 | installation, i.e. it must be previously opened by <link
|
---|
2171 | to="#openFloppyImage"/>, or mounted to some known virtual machine.
|
---|
2172 |
|
---|
2173 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2174 | No matching floppy image found in the media registry.
|
---|
2175 | </result>
|
---|
2176 |
|
---|
2177 | </desc>
|
---|
2178 | <param name="id" type="uuid" dir="in">
|
---|
2179 | <desc>UUID of the image to look for.</desc>
|
---|
2180 | </param>
|
---|
2181 | <param name="image" type="IFloppyImage" dir="return">
|
---|
2182 | <desc>Found floppy image object.</desc>
|
---|
2183 | </param>
|
---|
2184 | </method>
|
---|
2185 |
|
---|
2186 | <method name="findFloppyImage">
|
---|
2187 | <desc>
|
---|
2188 | Returns a floppy image with the given image location.
|
---|
2189 |
|
---|
2190 | The image with the given UUID must be known to this VirtualBox
|
---|
2191 | installation, i.e. it must be previously opened by <link
|
---|
2192 | to="#openFloppyImage"/>, or mounted to some known virtual machine.
|
---|
2193 |
|
---|
2194 | The search is done by comparing the value of the @a location argument to
|
---|
2195 | the <link to="IMedium::location"/> attribute of each known floppy image.
|
---|
2196 |
|
---|
2197 | The requested location can be a path relative to the
|
---|
2198 | <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
|
---|
2199 | only a file name without any path is given, the
|
---|
2200 | <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
|
---|
2201 | folder</link> will be prepended to the file name before searching. Note
|
---|
2202 | that on case sensitive file systems, a case sensitive comparison is
|
---|
2203 | performed, otherwise the case of symbols in the file path is ignored.
|
---|
2204 |
|
---|
2205 | <result name="VBOX_E_FILE_ERROR">
|
---|
2206 | Invalid image file location.
|
---|
2207 | </result>
|
---|
2208 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2209 | No matching floppy image found in the media registry.
|
---|
2210 | </result>
|
---|
2211 |
|
---|
2212 | </desc>
|
---|
2213 | <param name="location" type="wstring" dir="in">
|
---|
2214 | <desc>Floppy image file path to look for.</desc>
|
---|
2215 | </param>
|
---|
2216 | <param name="image" type="IFloppyImage" dir="return">
|
---|
2217 | <desc>Found floppy image object.</desc>
|
---|
2218 | </param>
|
---|
2219 | </method>
|
---|
2220 |
|
---|
2221 | <method name="getGuestOSType">
|
---|
2222 | <desc>
|
---|
2223 | Returns an object describing the specified guest OS type.
|
---|
2224 |
|
---|
2225 | The requested guest OS type is specified using a string which is a
|
---|
2226 | mnemonic identifier of the guest operating system, such as
|
---|
2227 | <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
|
---|
2228 | particular virtual machine can be read or set using the
|
---|
2229 | <link to="IMachine::OSTypeId"/> attribute.
|
---|
2230 |
|
---|
2231 | The <link to="IVirtualBox::guestOSTypes"/> collection contains all
|
---|
2232 | available guest OS type objects. Each object has an
|
---|
2233 | <link to="IGuestOSType::id"/> attribute which contains an identifier of
|
---|
2234 | the guest OS this object describes.
|
---|
2235 |
|
---|
2236 | <result name="E_INVALIDARG">
|
---|
2237 | @a id is not a valid Guest OS type.
|
---|
2238 | </result>
|
---|
2239 |
|
---|
2240 | </desc>
|
---|
2241 | <param name="id" type="wstring" dir="in">
|
---|
2242 | <desc>Guest OS type ID string.</desc>
|
---|
2243 | </param>
|
---|
2244 | <param name="type" type="IGuestOSType" dir="return">
|
---|
2245 | <desc>Guest OS type object.</desc>
|
---|
2246 | </param>
|
---|
2247 | </method>
|
---|
2248 |
|
---|
2249 | <method name="createSharedFolder">
|
---|
2250 | <desc>
|
---|
2251 | Creates a new global shared folder by associating the given logical
|
---|
2252 | name with the given host path, adds it to the collection of shared
|
---|
2253 | folders and starts sharing it. Refer to the description of
|
---|
2254 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
2255 | <note>
|
---|
2256 | In the current implementation, this operation is not
|
---|
2257 | implemented.
|
---|
2258 | </note>
|
---|
2259 | </desc>
|
---|
2260 | <param name="name" type="wstring" dir="in">
|
---|
2261 | <desc>Unique logical name of the shared folder.</desc>
|
---|
2262 | </param>
|
---|
2263 | <param name="hostPath" type="wstring" dir="in">
|
---|
2264 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
2265 | </param>
|
---|
2266 | <param name="writable" type="boolean" dir="in">
|
---|
2267 | <desc>Whether the share is writable or readonly</desc>
|
---|
2268 | </param>
|
---|
2269 | </method>
|
---|
2270 |
|
---|
2271 | <method name="removeSharedFolder">
|
---|
2272 | <desc>
|
---|
2273 | Removes the global shared folder with the given name previously
|
---|
2274 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
2275 | shared folders and stops sharing it.
|
---|
2276 | <note>
|
---|
2277 | In the current implementation, this operation is not
|
---|
2278 | implemented.
|
---|
2279 | </note>
|
---|
2280 | </desc>
|
---|
2281 | <param name="name" type="wstring" dir="in">
|
---|
2282 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
2283 | </param>
|
---|
2284 | </method>
|
---|
2285 |
|
---|
2286 | <method name="getNextExtraDataKey">
|
---|
2287 | <desc>
|
---|
2288 | Returns the global extra data key name following the supplied key.
|
---|
2289 |
|
---|
2290 | An error is returned if the supplied @a key does not exist. @c NULL is
|
---|
2291 | returned in @a nextKey if the supplied key is the last key. When
|
---|
2292 | supplying @c NULL or an empty string for the @a key, the first key item
|
---|
2293 | is returned in @a nextKey (if there is any). @a nextValue is an optional
|
---|
2294 | parameter and if supplied, the next key's value is returned in it.
|
---|
2295 |
|
---|
2296 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2297 | Extra data @a key not found.
|
---|
2298 | </result>
|
---|
2299 |
|
---|
2300 | </desc>
|
---|
2301 | <param name="key" type="wstring" dir="in">
|
---|
2302 | <desc>Name of the data key to follow.</desc>
|
---|
2303 | </param>
|
---|
2304 | <param name="nextKey" type="wstring" dir="out">
|
---|
2305 | <desc>Name of the next data key.</desc>
|
---|
2306 | </param>
|
---|
2307 | <param name="nextValue" type="wstring" dir="out">
|
---|
2308 | <desc>Value of the next data key.</desc>
|
---|
2309 | </param>
|
---|
2310 | </method>
|
---|
2311 |
|
---|
2312 | <method name="getExtraData">
|
---|
2313 | <desc>
|
---|
2314 | Returns associated global extra data.
|
---|
2315 |
|
---|
2316 | If the requested data @a key does not exist, this function will
|
---|
2317 | succeed and return @c NULL in the @a value argument.
|
---|
2318 |
|
---|
2319 | <result name="VBOX_E_FILE_ERROR">
|
---|
2320 | Settings file not accessible.
|
---|
2321 | </result>
|
---|
2322 | <result name="VBOX_E_XML_ERROR">
|
---|
2323 | Could not parse the settings file.
|
---|
2324 | </result>
|
---|
2325 |
|
---|
2326 | </desc>
|
---|
2327 | <param name="key" type="wstring" dir="in">
|
---|
2328 | <desc>Name of the data key to get.</desc>
|
---|
2329 | </param>
|
---|
2330 | <param name="value" type="wstring" dir="return">
|
---|
2331 | <desc>Value of the requested data key.</desc>
|
---|
2332 | </param>
|
---|
2333 | </method>
|
---|
2334 |
|
---|
2335 | <method name="setExtraData">
|
---|
2336 | <desc>
|
---|
2337 | Sets associated global extra data.
|
---|
2338 |
|
---|
2339 | If you pass @c NULL as a key @a value, the given @a key will be
|
---|
2340 | deleted.
|
---|
2341 |
|
---|
2342 | <note>
|
---|
2343 | Before performing the actual data change, this method will ask all
|
---|
2344 | registered callbacks using the
|
---|
2345 | <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
|
---|
2346 | notification for a permission. If one of the callbacks refuses the
|
---|
2347 | new value, the change will not be performed.
|
---|
2348 | </note>
|
---|
2349 | <note>
|
---|
2350 | On success, the
|
---|
2351 | <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
|
---|
2352 | is called to inform all registered callbacks about a successful data
|
---|
2353 | change.
|
---|
2354 | </note>
|
---|
2355 |
|
---|
2356 | <result name="VBOX_E_FILE_ERROR">
|
---|
2357 | Settings file not accessible.
|
---|
2358 | </result>
|
---|
2359 | <result name="VBOX_E_XML_ERROR">
|
---|
2360 | Could not parse the settings file.
|
---|
2361 | </result>
|
---|
2362 | <result name="E_ACCESSDENIED">
|
---|
2363 | Modification request refused.
|
---|
2364 | </result>
|
---|
2365 |
|
---|
2366 | </desc>
|
---|
2367 | <param name="key" type="wstring" dir="in">
|
---|
2368 | <desc>Name of the data key to set.</desc>
|
---|
2369 | </param>
|
---|
2370 | <param name="value" type="wstring" dir="in">
|
---|
2371 | <desc>Value to assign to the key.</desc>
|
---|
2372 | </param>
|
---|
2373 | </method>
|
---|
2374 |
|
---|
2375 | <method name="openSession">
|
---|
2376 | <desc>
|
---|
2377 | Opens a new direct session with the given virtual machine.
|
---|
2378 |
|
---|
2379 | A direct session acts as a local lock on the given VM.
|
---|
2380 | There can be only one direct session open at a time for every
|
---|
2381 | virtual machine, protecting the VM from being manipulated by
|
---|
2382 | conflicting actions from different processes. Only after a
|
---|
2383 | direct session has been opened, one can change all VM settings
|
---|
2384 | and execute the VM in the process space of the session object.
|
---|
2385 |
|
---|
2386 | Sessions therefore can be compared to mutex semaphores that
|
---|
2387 | lock a given VM for modification and execution.
|
---|
2388 | See <link to="ISession">ISession</link> for details.
|
---|
2389 |
|
---|
2390 | <note>Unless you are writing a new VM frontend, you will not
|
---|
2391 | want to execute a VM in the current process. To spawn a new
|
---|
2392 | process that executes a VM, use
|
---|
2393 | <link to="IVirtualBox::openRemoteSession" />
|
---|
2394 | instead.</note>
|
---|
2395 |
|
---|
2396 | Upon successful return, the session object can be used to
|
---|
2397 | get access to the machine and to the VM console.
|
---|
2398 |
|
---|
2399 | In VirtualBox terminology, the machine becomes "mutable" after
|
---|
2400 | a session has been opened. Note that the "mutable" machine
|
---|
2401 | object, on which you may invoke IMachine methods to change its
|
---|
2402 | settings, will be a different object from the immutable IMachine
|
---|
2403 | objects returned by various IVirtualBox methods. To obtain a
|
---|
2404 | mutable IMachine object (upon which you can invoke settings methods),
|
---|
2405 | use the <link to="ISession::machine" /> attribute.
|
---|
2406 |
|
---|
2407 | One must always call <link to="ISession::close" /> to release the
|
---|
2408 | lock on the machine, or the machine's state will eventually be
|
---|
2409 | set to "Aborted".
|
---|
2410 |
|
---|
2411 | In other words, to change settings on a machine, the following
|
---|
2412 | sequence is typically performed:
|
---|
2413 |
|
---|
2414 | <ol>
|
---|
2415 | <li>Call this method (openSession) to have a machine locked for
|
---|
2416 | the current session.</li>
|
---|
2417 |
|
---|
2418 | <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
|
---|
2419 |
|
---|
2420 | <li>Change the settings of the machine.</li>
|
---|
2421 |
|
---|
2422 | <li>Call <link to="IMachine::saveSettings" />.</li>
|
---|
2423 |
|
---|
2424 | <li>Close the session by calling <link to="ISession::close"/>.</li>
|
---|
2425 | </ol>
|
---|
2426 |
|
---|
2427 | <result name="E_UNEXPECTED">
|
---|
2428 | Virtual machine not registered.
|
---|
2429 | </result>
|
---|
2430 | <result name="E_ACCESSDENIED">
|
---|
2431 | Process not started by OpenRemoteSession.
|
---|
2432 | </result>
|
---|
2433 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2434 | No matching virtual machine found.
|
---|
2435 | </result>
|
---|
2436 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
2437 | Session already open or being opened.
|
---|
2438 | </result>
|
---|
2439 | <result name="VBOX_E_VM_ERROR">
|
---|
2440 | Failed to assign machine to session.
|
---|
2441 | </result>
|
---|
2442 |
|
---|
2443 | </desc>
|
---|
2444 | <param name="session" type="ISession" dir="in">
|
---|
2445 | <desc>
|
---|
2446 | Session object that will represent the opened session after
|
---|
2447 | successful method invocation. This object must not represent
|
---|
2448 | the already open session.
|
---|
2449 | <note>
|
---|
2450 | This session will be automatically closed if the
|
---|
2451 | VirtualBox server is terminated for some reason.
|
---|
2452 | </note>
|
---|
2453 | </desc>
|
---|
2454 | </param>
|
---|
2455 | <param name="machineId" type="uuid" dir="in">
|
---|
2456 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
2457 | </param>
|
---|
2458 | </method>
|
---|
2459 |
|
---|
2460 | <method name="openRemoteSession">
|
---|
2461 | <desc>
|
---|
2462 | Spawns a new process that executes a virtual machine (called a
|
---|
2463 | "remote session").
|
---|
2464 |
|
---|
2465 | Opening a remote session causes the VirtualBox server to start a new
|
---|
2466 | process that opens a direct session with the given VM. As a result, the
|
---|
2467 | VM is locked by that direct session in the new process, preventing
|
---|
2468 | conflicting changes from other processes. Since sessions act as locks
|
---|
2469 | that prevent conflicting changes, one cannot open a remote session
|
---|
2470 | for a VM that already has another open session (direct or remote), or
|
---|
2471 | is currently in the process of opening one (see <link
|
---|
2472 | to="IMachine::sessionState"/>).
|
---|
2473 |
|
---|
2474 | While the remote session still provides some level of control over the
|
---|
2475 | VM execution to the caller (using the <link to="IConsole" /> interface),
|
---|
2476 | not all VM settings are available for modification within the remote
|
---|
2477 | session context.
|
---|
2478 |
|
---|
2479 | This operation can take some time (a new VM is started in a new process,
|
---|
2480 | for which memory and other resources need to be set up). Because of this,
|
---|
2481 | an <link to="IProgress" /> is returned to allow the caller to wait for this
|
---|
2482 | asynchronous operation to be completed. Until then, the remote session
|
---|
2483 | object remains in the closed state, and accessing the machine or its
|
---|
2484 | console through it is invalid. It is recommended to use
|
---|
2485 | <link to="IProgress::waitForCompletion" /> or similar calls to wait for
|
---|
2486 | completion.
|
---|
2487 |
|
---|
2488 | As with all <link to="ISession" /> objects, it is recommended to call
|
---|
2489 | <link to="ISession::close" /> on the local session object once openRemoteSession()
|
---|
2490 | has been called. However, the session's state (see <link to="ISession::state" />)
|
---|
2491 | will not return to "Closed" until the remote session has also closed (i.e.
|
---|
2492 | until the VM is no longer running). In that case, however, the state of
|
---|
2493 | the session will automatically change back to "Closed".
|
---|
2494 |
|
---|
2495 | Currently supported session types (values of the @a type
|
---|
2496 | argument) are:
|
---|
2497 | <ul>
|
---|
2498 | <li><tt>gui</tt>: VirtualBox Qt GUI session</li>
|
---|
2499 | <li><tt>vrdp</tt>: VirtualBox VRDP Server session</li>
|
---|
2500 | </ul>
|
---|
2501 |
|
---|
2502 | The @a environment argument is a string containing definitions of
|
---|
2503 | environment variables in the following format:
|
---|
2504 | @code
|
---|
2505 | NAME[=VALUE]\n
|
---|
2506 | NAME[=VALUE]\n
|
---|
2507 | ...
|
---|
2508 | @endcode
|
---|
2509 | where <tt>\\n</tt> is the new line character. These environment
|
---|
2510 | variables will be appended to the environment of the VirtualBox server
|
---|
2511 | process. If an environment variable exists both in the server process
|
---|
2512 | and in this list, the value from this list takes precedence over the
|
---|
2513 | server's variable. If the value of the environment variable is
|
---|
2514 | omitted, this variable will be removed from the resulting environment.
|
---|
2515 | If the environment string is @c null, the server environment is
|
---|
2516 | inherited by the started process as is.
|
---|
2517 |
|
---|
2518 | <see>openExistingSession</see>
|
---|
2519 |
|
---|
2520 | <result name="E_UNEXPECTED">
|
---|
2521 | Virtual machine not registered.
|
---|
2522 | </result>
|
---|
2523 | <result name="E_INVALIDARG">
|
---|
2524 | Invalid session type @a type.
|
---|
2525 | </result>
|
---|
2526 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2527 | No machine matching @a machineId found.
|
---|
2528 | </result>
|
---|
2529 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
2530 | Session already open or being opened.
|
---|
2531 | </result>
|
---|
2532 | <result name="VBOX_E_IPRT_ERROR">
|
---|
2533 | Launching process for machine failed.
|
---|
2534 | </result>
|
---|
2535 | <result name="VBOX_E_VM_ERROR">
|
---|
2536 | Failed to assign machine to session.
|
---|
2537 | </result>
|
---|
2538 |
|
---|
2539 | </desc>
|
---|
2540 | <param name="session" type="ISession" dir="in">
|
---|
2541 | <desc>
|
---|
2542 | Session object that will represent the opened remote session
|
---|
2543 | after successful method invocation (this object must not
|
---|
2544 | represent an already open session).
|
---|
2545 | </desc>
|
---|
2546 | </param>
|
---|
2547 | <param name="machineId" type="uuid" dir="in">
|
---|
2548 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
2549 | </param>
|
---|
2550 | <param name="type" type="wstring" dir="in">
|
---|
2551 | <desc>
|
---|
2552 | Type of the remote session (case sensitive).
|
---|
2553 | </desc>
|
---|
2554 | </param>
|
---|
2555 | <param name="environment" type="wstring" dir="in">
|
---|
2556 | <desc>
|
---|
2557 | Environment to pass to the opened session (may be @c null).
|
---|
2558 | </desc>
|
---|
2559 | </param>
|
---|
2560 | <param name="progress" type="IProgress" dir="return">
|
---|
2561 | <desc>Progress object to track the operation completion.</desc>
|
---|
2562 | </param>
|
---|
2563 | </method>
|
---|
2564 |
|
---|
2565 | <method name="openExistingSession">
|
---|
2566 | <desc>
|
---|
2567 | Opens a new remote session with the virtual machine for
|
---|
2568 | which a direct session is already open.
|
---|
2569 |
|
---|
2570 | The remote session provides some level of control over the VM
|
---|
2571 | execution (using the IConsole interface) to the caller; however,
|
---|
2572 | within the remote session context, not all VM settings are available
|
---|
2573 | for modification.
|
---|
2574 |
|
---|
2575 | As opposed to <link to="#openRemoteSession"/>, the number of
|
---|
2576 | remote sessions opened this way is not limited by the API
|
---|
2577 |
|
---|
2578 | <note>
|
---|
2579 | It is an error to open a remote session with the machine that
|
---|
2580 | doesn't have an open direct session.
|
---|
2581 | </note>
|
---|
2582 |
|
---|
2583 | <result name="E_UNEXPECTED">
|
---|
2584 | Virtual machine not registered.
|
---|
2585 | </result>
|
---|
2586 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
2587 | No machine matching @a machineId found.
|
---|
2588 | </result>
|
---|
2589 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
2590 | Session already open or being opened.
|
---|
2591 | </result>
|
---|
2592 | <result name="VBOX_E_INVALID_SESSION_STATE">
|
---|
2593 | Direct session state not Open.
|
---|
2594 | </result>
|
---|
2595 | <result name="VBOX_E_VM_ERROR">
|
---|
2596 | Failed to get console object from direct session or assign
|
---|
2597 | machine to session.
|
---|
2598 | </result>
|
---|
2599 |
|
---|
2600 | <see>openRemoteSession</see>
|
---|
2601 | </desc>
|
---|
2602 | <param name="session" type="ISession" dir="in">
|
---|
2603 | <desc>
|
---|
2604 | Session object that will represent the open remote session
|
---|
2605 | after successful method invocation. This object must not
|
---|
2606 | represent an already open session.
|
---|
2607 | <note>
|
---|
2608 | This session will be automatically closed when the peer
|
---|
2609 | (direct) session dies or gets closed.
|
---|
2610 | </note>
|
---|
2611 | </desc>
|
---|
2612 | </param>
|
---|
2613 | <param name="machineId" type="uuid" dir="in">
|
---|
2614 | <desc>ID of the virtual machine to open a session with.</desc>
|
---|
2615 | </param>
|
---|
2616 | </method>
|
---|
2617 |
|
---|
2618 | <method name="registerCallback">
|
---|
2619 | <desc>
|
---|
2620 | Registers a new global VirtualBox callback. The methods of the given
|
---|
2621 | callback object will be called by VirtualBox when an appropriate
|
---|
2622 | event occurs.
|
---|
2623 |
|
---|
2624 | <result name="E_INVALIDARG">
|
---|
2625 | A @c NULL callback cannot be registered.
|
---|
2626 | </result>
|
---|
2627 |
|
---|
2628 | </desc>
|
---|
2629 | <param name="callback" type="IVirtualBoxCallback" dir="in">
|
---|
2630 | <desc>Callback object to register.</desc>
|
---|
2631 | </param>
|
---|
2632 | </method>
|
---|
2633 |
|
---|
2634 | <method name="unregisterCallback">
|
---|
2635 | <desc>
|
---|
2636 | Unregisters the previously registered global VirtualBox callback.
|
---|
2637 |
|
---|
2638 | <result name="E_INVALIDARG">
|
---|
2639 | Specified @a callback not registered.
|
---|
2640 | </result>
|
---|
2641 |
|
---|
2642 | </desc>
|
---|
2643 | <param name="callback" type="IVirtualBoxCallback" dir="in">
|
---|
2644 | <desc>Callback object to unregister.</desc>
|
---|
2645 | </param>
|
---|
2646 | </method>
|
---|
2647 |
|
---|
2648 | <method name="waitForPropertyChange">
|
---|
2649 | <desc>
|
---|
2650 | Blocks the caller until any of the properties represented by the
|
---|
2651 | @a what argument changes the value or until the given timeout interval
|
---|
2652 | expires.
|
---|
2653 |
|
---|
2654 | The @a what argument is a comma separated list of property masks that
|
---|
2655 | describe properties the caller is interested in. The property mask is
|
---|
2656 | a string in the following format:
|
---|
2657 |
|
---|
2658 | <pre>
|
---|
2659 | [[group.]subgroup.]name
|
---|
2660 | </pre>
|
---|
2661 |
|
---|
2662 | where @c name is the property name and @c group, @c subgroup are zero
|
---|
2663 | or more property group specifiers. Each element (group or name) in
|
---|
2664 | the property mask may be either a Latin string or an asterisk symbol
|
---|
2665 | (@c "*") which is used to match any string for the given element. A
|
---|
2666 | property mask that doesn't contain asterisk symbols represents a
|
---|
2667 | single fully qualified property name.
|
---|
2668 |
|
---|
2669 | Groups in the fully qualified property name go from more generic (the
|
---|
2670 | left-most part) to more specific (the right-most part). The first
|
---|
2671 | element is usually a name of the object the property belongs to. The
|
---|
2672 | second element may be either a property name, or a child object name,
|
---|
2673 | or an index if the preceding element names an object which is one of
|
---|
2674 | many objects of the same type. This way, property names form a
|
---|
2675 | hierarchy of properties. Here are some examples of property names:
|
---|
2676 |
|
---|
2677 | <table>
|
---|
2678 | <tr>
|
---|
2679 | <td><tt>VirtualBox.version</tt></td>
|
---|
2680 | <td><link to="IVirtualBox::version"/> property</td>
|
---|
2681 | </tr>
|
---|
2682 | <tr>
|
---|
2683 | <td><tt>Machine.<UUID>.name</tt></td>
|
---|
2684 | <td><link to="IMachine::name"/> property of the machine with the
|
---|
2685 | given UUID</td>
|
---|
2686 | </tr>
|
---|
2687 | </table>
|
---|
2688 |
|
---|
2689 | Most property names directly correspond to the properties of objects
|
---|
2690 | (components) provided by the VirtualBox library and may be used to
|
---|
2691 | track changes to these properties. However, there may be
|
---|
2692 | pseudo-property names that don't correspond to any existing object's
|
---|
2693 | property directly, as well as there may be object properties that
|
---|
2694 | don't have a corresponding property name that is understood by this
|
---|
2695 | method, and therefore changes to such properties cannot be
|
---|
2696 | tracked. See individual object's property descriptions to get a
|
---|
2697 | fully qualified property name that can be used with this method (if
|
---|
2698 | any).
|
---|
2699 |
|
---|
2700 | There is a special property mask @c "*" (i.e. a string consisting of a
|
---|
2701 | single asterisk symbol) that can be used to match all properties.
|
---|
2702 | Below are more examples of property masks:
|
---|
2703 |
|
---|
2704 | <table>
|
---|
2705 | <tr>
|
---|
2706 | <td><tt>VirtualBox.*</tt></td>
|
---|
2707 | <td>Track all properties of the VirtualBox object</td>
|
---|
2708 | </tr>
|
---|
2709 | <tr>
|
---|
2710 | <td><tt>Machine.*.name</tt></td>
|
---|
2711 | <td>Track changes to the <link to="IMachine::name"/> property of
|
---|
2712 | all registered virtual machines</td>
|
---|
2713 | </tr>
|
---|
2714 | </table>
|
---|
2715 |
|
---|
2716 | <note>
|
---|
2717 | This function is not implemented in the current version of the
|
---|
2718 | product.
|
---|
2719 | </note>
|
---|
2720 | </desc>
|
---|
2721 | <param name="what" type="wstring" dir="in">
|
---|
2722 | <desc>Comma separated list of property masks.</desc>
|
---|
2723 | </param>
|
---|
2724 | <param name="timeout" type="unsigned long" dir="in">
|
---|
2725 | <desc>
|
---|
2726 | Wait timeout in milliseconds.
|
---|
2727 | Specify -1 for an indefinite wait.
|
---|
2728 | </desc>
|
---|
2729 | </param>
|
---|
2730 | <param name="changed" type="wstring" dir="out">
|
---|
2731 | <desc>
|
---|
2732 | Comma separated list of properties that have been changed and caused
|
---|
2733 | this method to return to the caller.
|
---|
2734 | </desc>
|
---|
2735 | </param>
|
---|
2736 | <param name="values" type="wstring" dir="out">
|
---|
2737 | <desc>Reserved, not currently used.</desc>
|
---|
2738 | </param>
|
---|
2739 | </method>
|
---|
2740 |
|
---|
2741 | <method name="saveSettings">
|
---|
2742 | <desc>
|
---|
2743 | Saves the global settings to the global settings file
|
---|
2744 | (<link to="#settingsFilePath"/>).
|
---|
2745 |
|
---|
2746 | This method is only useful for explicitly saving the global settings
|
---|
2747 | file after it has been auto-converted from the old format to the most
|
---|
2748 | recent format (see <link to="#settingsFileVersion"/> for details).
|
---|
2749 | Normally, the global settings file is implicitly saved when a global
|
---|
2750 | setting is changed.
|
---|
2751 |
|
---|
2752 | <result name="VBOX_E_FILE_ERROR">
|
---|
2753 | Settings file not accessible.
|
---|
2754 | </result>
|
---|
2755 | <result name="VBOX_E_XML_ERROR">
|
---|
2756 | Could not parse the settings file.
|
---|
2757 | </result>
|
---|
2758 |
|
---|
2759 | </desc>
|
---|
2760 | </method>
|
---|
2761 |
|
---|
2762 | <method name="saveSettingsWithBackup">
|
---|
2763 | <desc>
|
---|
2764 | Creates a backup copy of the global settings file
|
---|
2765 | (<link to="IVirtualBox::settingsFilePath"/>) in case of auto-conversion,
|
---|
2766 | and then calls <link to="IVirtualBox::saveSettings"/>.
|
---|
2767 |
|
---|
2768 | Note that the backup copy is created <b>only</b> if the settings file
|
---|
2769 | auto-conversion took place (see <link to="#settingsFileVersion"/> for
|
---|
2770 | details). Otherwise, this call is fully equivalent to
|
---|
2771 | <link to="IVirtualBox::saveSettings"/> and no backup copying is done.
|
---|
2772 |
|
---|
2773 | The backup copy is created in the same directory where the original
|
---|
2774 | settings file is located. It is given the following file name:
|
---|
2775 | <pre>
|
---|
2776 | original.xml.x.y-platform.bak
|
---|
2777 | </pre>
|
---|
2778 | where <tt>original.xml</tt> is the original settings file name
|
---|
2779 | (excluding path), and <tt>x.y-platform</tt> is the version of the old
|
---|
2780 | format of the settings file (before auto-conversion).
|
---|
2781 |
|
---|
2782 | If the given backup file already exists, this method will try to add the
|
---|
2783 | <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
|
---|
2784 | 0 to 9) and copy it again until it succeeds. If all suffixes are
|
---|
2785 | occupied, or if any other copy error occurs, this method will return a
|
---|
2786 | failure.
|
---|
2787 |
|
---|
2788 | If the copy operation succeeds, the @a bakFileName return argument will
|
---|
2789 | receive a full path to the created backup file (for informational
|
---|
2790 | purposes). Note that this will happen even if the subsequent
|
---|
2791 | <link to="#saveSettings"/> call performed by this method after the
|
---|
2792 | copy operation, fails.
|
---|
2793 |
|
---|
2794 | <note>
|
---|
2795 | The VirtualBox API never calls this method. It is intended purely for
|
---|
2796 | the purposes of creating backup copies of the settings files by
|
---|
2797 | front-ends before saving the results of the automatically performed
|
---|
2798 | settings conversion to disk.
|
---|
2799 | </note>
|
---|
2800 |
|
---|
2801 | <see>settingsFileVersion</see>
|
---|
2802 |
|
---|
2803 | <result name="VBOX_E_FILE_ERROR">
|
---|
2804 | Settings file not accessible.
|
---|
2805 | </result>
|
---|
2806 | <result name="VBOX_E_XML_ERROR">
|
---|
2807 | Could not parse the settings file.
|
---|
2808 | </result>
|
---|
2809 | <result name="VBOX_E_IPRT_ERROR">
|
---|
2810 | Could not copy the settings file.
|
---|
2811 | </result>
|
---|
2812 |
|
---|
2813 | </desc>
|
---|
2814 | <param name="bakFileName" type="wstring" dir="return">
|
---|
2815 | <desc>Full path to the created backup copy.</desc>
|
---|
2816 | </param>
|
---|
2817 | </method>
|
---|
2818 |
|
---|
2819 | <!--method name="createDHCPServerForInterface">
|
---|
2820 | <desc>
|
---|
2821 | Creates a dhcp server settings to be used for the given interface
|
---|
2822 | <result name="E_INVALIDARG">
|
---|
2823 | Host network interface @a name already exists.
|
---|
2824 | </result>
|
---|
2825 | </desc>
|
---|
2826 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2827 | <desc>Network Interface</desc>
|
---|
2828 | </param>
|
---|
2829 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2830 | <desc>Dhcp server settings</desc>
|
---|
2831 | </param>
|
---|
2832 | </method-->
|
---|
2833 |
|
---|
2834 | <method name="createDHCPServer">
|
---|
2835 | <desc>
|
---|
2836 | Creates a dhcp server settings to be used for the given internal network name
|
---|
2837 | <result name="E_INVALIDARG">
|
---|
2838 | Host network interface @a name already exists.
|
---|
2839 | </result>
|
---|
2840 | </desc>
|
---|
2841 | <param name="name" type="wstring" dir="in">
|
---|
2842 | <desc>server name</desc>
|
---|
2843 | </param>
|
---|
2844 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2845 | <desc>Dhcp server settings</desc>
|
---|
2846 | </param>
|
---|
2847 | </method>
|
---|
2848 |
|
---|
2849 | <method name="findDHCPServerByNetworkName">
|
---|
2850 | <desc>
|
---|
2851 | Searches a dhcp server settings to be used for the given internal network name
|
---|
2852 | <result name="E_INVALIDARG">
|
---|
2853 | Host network interface @a name already exists.
|
---|
2854 | </result>
|
---|
2855 |
|
---|
2856 | </desc>
|
---|
2857 | <param name="name" type="wstring" dir="in">
|
---|
2858 | <desc>server name</desc>
|
---|
2859 | </param>
|
---|
2860 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2861 | <desc>Dhcp server settings</desc>
|
---|
2862 | </param>
|
---|
2863 | </method>
|
---|
2864 |
|
---|
2865 | <!--method name="findDHCPServerForInterface">
|
---|
2866 | <desc>
|
---|
2867 | Searches a dhcp server settings to be used for the given interface
|
---|
2868 | <result name="E_INVALIDARG">
|
---|
2869 | Host network interface @a name already exists.
|
---|
2870 | </result>
|
---|
2871 | </desc>
|
---|
2872 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2873 | <desc>Network Interface</desc>
|
---|
2874 | </param>
|
---|
2875 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2876 | <desc>Dhcp server settings</desc>
|
---|
2877 | </param>
|
---|
2878 | </method-->
|
---|
2879 |
|
---|
2880 | <method name="removeDHCPServer">
|
---|
2881 | <desc>
|
---|
2882 | Removes the dhcp server settings
|
---|
2883 | <result name="E_INVALIDARG">
|
---|
2884 | Host network interface @a name already exists.
|
---|
2885 | </result>
|
---|
2886 | </desc>
|
---|
2887 | <param name="server" type="IDHCPServer" dir="in">
|
---|
2888 | <desc>Dhcp server settings to be removed</desc>
|
---|
2889 | </param>
|
---|
2890 | </method>
|
---|
2891 |
|
---|
2892 | </interface>
|
---|
2893 |
|
---|
2894 | <!--
|
---|
2895 | // IAppliance
|
---|
2896 | /////////////////////////////////////////////////////////////////////////
|
---|
2897 | -->
|
---|
2898 |
|
---|
2899 | <enum
|
---|
2900 | name="CIMOSType"
|
---|
2901 | uuid="86ef5f8c-18b2-4db8-a314-33721b59f89b"
|
---|
2902 | >
|
---|
2903 | <desc>
|
---|
2904 | OVF operating system values according to CIM V2.20 (as of Nov 2008); http://www.dmtf.org/standards/cim/cim_schema_v220
|
---|
2905 | </desc>
|
---|
2906 |
|
---|
2907 | <const name="CIMOS_Unknown" value="0" /> <!-- "Unknown" -->
|
---|
2908 | <const name="CIMOS_Other" value="1" /> <!-- "Other" -->
|
---|
2909 | <const name="CIMOS_MACOS" value="2" /> <!-- "MACOS" -->
|
---|
2910 | <const name="CIMOS_ATTUNIX" value="3" /> <!-- "ATTUNIX" -->
|
---|
2911 | <const name="CIMOS_DGUX" value="4" /> <!-- "DGUX" -->
|
---|
2912 | <const name="CIMOS_DECNT" value="5" /> <!-- "DECNT" -->
|
---|
2913 | <const name="CIMOS_Tru64UNIX" value="6" /> <!-- "Tru64 UNIX" -->
|
---|
2914 | <const name="CIMOS_OpenVMS" value="7" /> <!-- "OpenVMS" -->
|
---|
2915 | <const name="CIMOS_HPUX" value="8" /> <!-- "HPUX" -->
|
---|
2916 | <const name="CIMOS_AIX" value="9" /> <!-- "AIX" -->
|
---|
2917 | <const name="CIMOS_MVS" value="10" /> <!-- "MVS" -->
|
---|
2918 | <const name="CIMOS_OS400" value="11" /> <!-- "OS400" -->
|
---|
2919 | <const name="CIMOS_OS2" value="12" /> <!-- "OS/2" -->
|
---|
2920 | <const name="CIMOS_JavaVM" value="13" /> <!-- "JavaVM" -->
|
---|
2921 | <const name="CIMOS_MSDOS" value="14" /> <!-- "MSDOS" -->
|
---|
2922 | <const name="CIMOS_WIN3x" value="15" /> <!-- "WIN3x" -->
|
---|
2923 | <const name="CIMOS_WIN95" value="16" /> <!-- "WIN95" -->
|
---|
2924 | <const name="CIMOS_WIN98" value="17" /> <!-- "WIN98" -->
|
---|
2925 | <const name="CIMOS_WINNT" value="18" /> <!-- "WINNT" -->
|
---|
2926 | <const name="CIMOS_WINCE" value="19" /> <!-- "WINCE" -->
|
---|
2927 | <const name="CIMOS_NCR3000" value="20" /> <!-- "NCR3000" -->
|
---|
2928 | <const name="CIMOS_NetWare" value="21" /> <!-- "NetWare" -->
|
---|
2929 | <const name="CIMOS_OSF" value="22" /> <!-- "OSF" -->
|
---|
2930 | <const name="CIMOS_DCOS" value="23" /> <!-- "DC/OS" -->
|
---|
2931 | <const name="CIMOS_ReliantUNIX" value="24" /> <!-- "Reliant UNIX" -->
|
---|
2932 | <const name="CIMOS_SCOUnixWare" value="25" /> <!-- "SCO UnixWare" -->
|
---|
2933 | <const name="CIMOS_SCOOpenServer" value="26" /> <!-- "SCO OpenServer" -->
|
---|
2934 | <const name="CIMOS_Sequent" value="27" /> <!-- "Sequent" -->
|
---|
2935 | <const name="CIMOS_IRIX" value="28" /> <!-- "IRIX" -->
|
---|
2936 | <const name="CIMOS_Solaris" value="29" /> <!-- "Solaris" -->
|
---|
2937 | <const name="CIMOS_SunOS" value="30" /> <!-- "SunOS" -->
|
---|
2938 | <const name="CIMOS_U6000" value="31" /> <!-- "U6000" -->
|
---|
2939 | <const name="CIMOS_ASERIES" value="32" /> <!-- "ASERIES" -->
|
---|
2940 | <const name="CIMOS_HPNonStopOS" value="33" /> <!-- "HP NonStop OS" -->
|
---|
2941 | <const name="CIMOS_HPNonStopOSS" value="34" /> <!-- "HP NonStop OSS" -->
|
---|
2942 | <const name="CIMOS_BS2000" value="35" /> <!-- "BS2000" -->
|
---|
2943 | <const name="CIMOS_LINUX" value="36" /> <!-- "LINUX" -->
|
---|
2944 | <const name="CIMOS_Lynx" value="37" /> <!-- "Lynx" -->
|
---|
2945 | <const name="CIMOS_XENIX" value="38" /> <!-- "XENIX" -->
|
---|
2946 | <const name="CIMOS_VM" value="39" /> <!-- "VM" -->
|
---|
2947 | <const name="CIMOS_InteractiveUNIX" value="40" /> <!-- "Interactive UNIX" -->
|
---|
2948 | <const name="CIMOS_BSDUNIX" value="41" /> <!-- "BSDUNIX" -->
|
---|
2949 | <const name="CIMOS_FreeBSD" value="42" /> <!-- "FreeBSD" -->
|
---|
2950 | <const name="CIMOS_NetBSD" value="43" /> <!-- "NetBSD" -->
|
---|
2951 | <const name="CIMOS_GNUHurd" value="44" /> <!-- "GNU Hurd" -->
|
---|
2952 | <const name="CIMOS_OS9" value="45" /> <!-- "OS9" -->
|
---|
2953 | <const name="CIMOS_MACHKernel" value="46" /> <!-- "MACH Kernel" -->
|
---|
2954 | <const name="CIMOS_Inferno" value="47" /> <!-- "Inferno" -->
|
---|
2955 | <const name="CIMOS_QNX" value="48" /> <!-- "QNX" -->
|
---|
2956 | <const name="CIMOS_EPOC" value="49" /> <!-- "EPOC" -->
|
---|
2957 | <const name="CIMOS_IxWorks" value="50" /> <!-- "IxWorks" -->
|
---|
2958 | <const name="CIMOS_VxWorks" value="51" /> <!-- "VxWorks" -->
|
---|
2959 | <const name="CIMOS_MiNT" value="52" /> <!-- "MiNT" -->
|
---|
2960 | <const name="CIMOS_BeOS" value="53" /> <!-- "BeOS" -->
|
---|
2961 | <const name="CIMOS_HPMPE" value="54" /> <!-- "HP MPE" -->
|
---|
2962 | <const name="CIMOS_NextStep" value="55" /> <!-- "NextStep" -->
|
---|
2963 | <const name="CIMOS_PalmPilot" value="56" /> <!-- "PalmPilot" -->
|
---|
2964 | <const name="CIMOS_Rhapsody" value="57" /> <!-- "Rhapsody" -->
|
---|
2965 | <const name="CIMOS_Windows2000" value="58" /> <!-- "Windows 2000" -->
|
---|
2966 | <const name="CIMOS_Dedicated" value="59" /> <!-- "Dedicated" -->
|
---|
2967 | <const name="CIMOS_OS390" value="60" /> <!-- "OS/390" -->
|
---|
2968 | <const name="CIMOS_VSE" value="61" /> <!-- "VSE" -->
|
---|
2969 | <const name="CIMOS_TPF" value="62" /> <!-- "TPF" -->
|
---|
2970 | <const name="CIMOS_WindowsMe" value="63" /> <!-- "Windows (R) Me" -->
|
---|
2971 | <const name="CIMOS_CalderaOpenUNIX" value="64" /> <!-- "Caldera Open UNIX" -->
|
---|
2972 | <const name="CIMOS_OpenBSD" value="65" /> <!-- "OpenBSD" -->
|
---|
2973 | <const name="CIMOS_NotApplicable" value="66" /> <!-- "Not Applicable" -->
|
---|
2974 | <const name="CIMOS_WindowsXP" value="67" /> <!-- "Windows XP" -->
|
---|
2975 | <const name="CIMOS_zOS" value="68" /> <!-- "z/OS" -->
|
---|
2976 | <const name="CIMOS_MicrosoftWindowsServer2003" value="69" /> <!-- "Microsoft Windows Server 2003" -->
|
---|
2977 | <const name="CIMOS_MicrosoftWindowsServer2003_64" value="70" /> <!-- "Microsoft Windows Server 2003 64-Bit" -->
|
---|
2978 | <const name="CIMOS_WindowsXP_64" value="71" /> <!-- "Windows XP 64-Bit" -->
|
---|
2979 | <const name="CIMOS_WindowsXPEmbedded" value="72" /> <!-- "Windows XP Embedded" -->
|
---|
2980 | <const name="CIMOS_WindowsVista" value="73" /> <!-- "Windows Vista" -->
|
---|
2981 | <const name="CIMOS_WindowsVista_64" value="74" /> <!-- "Windows Vista 64-Bit" -->
|
---|
2982 | <const name="CIMOS_WindowsEmbeddedforPointofService" value="75" /> <!-- "Windows Embedded for Point of Service" -->
|
---|
2983 | <const name="CIMOS_MicrosoftWindowsServer2008" value="76" /> <!-- "Microsoft Windows Server 2008" -->
|
---|
2984 | <const name="CIMOS_MicrosoftWindowsServer2008_64" value="77" /> <!-- "Microsoft Windows Server 2008 64-Bit" -->
|
---|
2985 | <const name="CIMOS_FreeBSD_64" value="78" /> <!-- "FreeBSD 64-Bit" -->
|
---|
2986 | <const name="CIMOS_RedHatEnterpriseLinux" value="79" /> <!-- "RedHat Enterprise Linux" -->
|
---|
2987 | <const name="CIMOS_RedHatEnterpriseLinux_64" value="80" /> <!-- "RedHat Enterprise Linux 64-Bit" -->
|
---|
2988 | <const name="CIMOS_Solaris_64" value="81" /> <!-- "Solaris 64-Bit" -->
|
---|
2989 | <const name="CIMOS_SUSE" value="82" /> <!-- "SUSE" -->
|
---|
2990 | <const name="CIMOS_SUSE_64" value="83" /> <!-- "SUSE 64-Bit" -->
|
---|
2991 | <const name="CIMOS_SLES" value="84" /> <!-- "SLES" -->
|
---|
2992 | <const name="CIMOS_SLES_64" value="85" /> <!-- "SLES 64-Bit" -->
|
---|
2993 | <const name="CIMOS_NovellOES" value="86" /> <!-- "Novell OES" -->
|
---|
2994 | <const name="CIMOS_NovellLinuxDesktop" value="87" /> <!-- "Novell Linux Desktop" -->
|
---|
2995 | <const name="CIMOS_SunJavaDesktopSystem" value="88" /> <!-- "Sun Java Desktop System" -->
|
---|
2996 | <const name="CIMOS_Mandriva" value="89" /> <!-- "Mandriva" -->
|
---|
2997 | <const name="CIMOS_Mandriva_64" value="90" /> <!-- "Mandriva 64-Bit" -->
|
---|
2998 | <const name="CIMOS_TurboLinux" value="91" /> <!-- "TurboLinux" -->
|
---|
2999 | <const name="CIMOS_TurboLinux_64" value="92" /> <!-- "TurboLinux 64-Bit" -->
|
---|
3000 | <const name="CIMOS_Ubuntu" value="93" /> <!-- "Ubuntu" -->
|
---|
3001 | <const name="CIMOS_Ubuntu_64" value="94" /> <!-- "Ubuntu 64-Bit" -->
|
---|
3002 | <const name="CIMOS_Debian" value="95" /> <!-- "Debian" -->
|
---|
3003 | <const name="CIMOS_Debian_64" value="96" /> <!-- "Debian 64-Bit" -->
|
---|
3004 | <const name="CIMOS_Linux_2_4_x" value="97" /> <!-- "Linux 2.4.x" -->
|
---|
3005 | <const name="CIMOS_Linux_2_4_x_64" value="98" /> <!-- "Linux 2.4.x 64-Bit" -->
|
---|
3006 | <const name="CIMOS_Linux_2_6_x" value="99" /> <!-- "Linux 2.6.x" -->
|
---|
3007 | <const name="CIMOS_Linux_2_6_x_64" value="100" /> <!-- "Linux 2.6.x 64-Bit" -->
|
---|
3008 | <const name="CIMOS_Linux_64" value="101" /> <!-- "Linux 64-Bit" -->
|
---|
3009 | <const name="CIMOS_Other_64" value="102" /> <!-- "Other 64-Bit" -->
|
---|
3010 | </enum>
|
---|
3011 |
|
---|
3012 | <enum
|
---|
3013 | name="OVFResourceType"
|
---|
3014 | uuid="646a78d7-6f04-49f4-82c4-75c28a75a4cd"
|
---|
3015 | >
|
---|
3016 | <desc>
|
---|
3017 | OVF resource type (as listed with CIM_ResourceAllocationSettingData; see for example
|
---|
3018 | http://msdn.microsoft.com/en-us/library/cc136877(VS.85).aspx).
|
---|
3019 | </desc>
|
---|
3020 |
|
---|
3021 | <const name="Other" value="1" />
|
---|
3022 | <const name="ComputerSystem" value="2" />
|
---|
3023 | <const name="Processor" value="3" />
|
---|
3024 | <const name="Memory" value="4" />
|
---|
3025 | <const name="IDEController" value="5" />
|
---|
3026 | <const name="ParallelSCSIHBA" value="6" />
|
---|
3027 | <const name="FCHBA" value="7" />
|
---|
3028 | <const name="iSCSIHBA" value="8" />
|
---|
3029 | <const name="IBHCA" value="9" />
|
---|
3030 | <const name="EthernetAdapter" value="10" />
|
---|
3031 | <const name="OtherNetworkAdapter" value="11" />
|
---|
3032 | <const name="IOSlot" value="12" />
|
---|
3033 | <const name="IODevice" value="13" />
|
---|
3034 | <const name="FloppyDrive" value="14" />
|
---|
3035 | <const name="CDDrive" value="15" />
|
---|
3036 | <const name="DVDDrive" value="16" />
|
---|
3037 | <const name="HardDisk" value="17" />
|
---|
3038 | <const name="OtherStorageDevice" value="20" />
|
---|
3039 | <const name="USBController" value="23" />
|
---|
3040 | <const name="SoundCard" value="35" />
|
---|
3041 | </enum>
|
---|
3042 |
|
---|
3043 | <interface
|
---|
3044 | name="IAppliance" extends="$unknown"
|
---|
3045 | uuid="30bfa6b8-9eda-4b0a-b218-a86813248ccd"
|
---|
3046 | wsmap="managed"
|
---|
3047 | >
|
---|
3048 | <desc>
|
---|
3049 | Represents a platform-independent appliance in OVF format. An instance of this is returned
|
---|
3050 | by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
|
---|
3051 | appliances with VirtualBox.
|
---|
3052 |
|
---|
3053 | The OVF standard suggests two different physical file formats:
|
---|
3054 |
|
---|
3055 | <ol>
|
---|
3056 | <li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
|
---|
3057 | path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
|
---|
3058 | this descriptor file references other files, as OVF appliances distributed as a set of
|
---|
3059 | files most likely do, those files must be in the same directory as the descriptor file.</li>
|
---|
3060 |
|
---|
3061 | <li>If the OVF is distributed as a single file, it must be in TAR format and have the
|
---|
3062 | <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
|
---|
3063 | files and optionally other files.
|
---|
3064 |
|
---|
3065 | At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
|
---|
3066 | be added with a later version.</li>
|
---|
3067 | </ol>
|
---|
3068 |
|
---|
3069 | <b>Importing</b> an OVF appliance into VirtualBox as instances of
|
---|
3070 | <link to="IMachine" /> involves the following sequence of API calls:
|
---|
3071 |
|
---|
3072 | <ol>
|
---|
3073 | <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
|
---|
3074 | </li>
|
---|
3075 |
|
---|
3076 | <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
|
---|
3077 | would like to import. So long as this file is syntactically valid, this will succeed
|
---|
3078 | and return an instance of IAppliance that contains the parsed data from the OVF file.
|
---|
3079 | </li>
|
---|
3080 |
|
---|
3081 | <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
|
---|
3082 | contents of the IAppliance attributes accordingly. These can be inspected by a
|
---|
3083 | VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
|
---|
3084 | user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
|
---|
3085 | instances of <link to="IVirtualSystemDescription" /> which represent the virtual
|
---|
3086 | systems in the OVF, which in turn describe the virtual hardware prescribed by the
|
---|
3087 | OVF (network and hardware adapters, virtual disk images, memory size and so on).
|
---|
3088 | The GUI can then give the user the option to confirm and/or change these suggestions.
|
---|
3089 | </li>
|
---|
3090 |
|
---|
3091 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
3092 | virtual system to override the suggestions made by the interpret() routine.
|
---|
3093 | </li>
|
---|
3094 |
|
---|
3095 | <li>Finally, call <link to="#importMachines" /> to create virtual machines in
|
---|
3096 | VirtualBox as instances of <link to="IMachine" /> that match the information in the
|
---|
3097 | virtual system descriptions.
|
---|
3098 | </li>
|
---|
3099 | </ol>
|
---|
3100 |
|
---|
3101 | <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
|
---|
3102 |
|
---|
3103 | <ol>
|
---|
3104 | <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
|
---|
3105 | an empty IAppliance object.
|
---|
3106 | </li>
|
---|
3107 |
|
---|
3108 | <li>For each machine you would like to export, call <link to="IMachine::export" />
|
---|
3109 | with the IAppliance object you just created. This creates an instance of
|
---|
3110 | <link to="IVirtualSystemDescription" /> inside the appliance.
|
---|
3111 | </li>
|
---|
3112 |
|
---|
3113 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
3114 | virtual system to override the suggestions made by the export() routine.
|
---|
3115 | </li>
|
---|
3116 |
|
---|
3117 | <li>Finally, call <link to="#write" /> with a path specification to have the OVF
|
---|
3118 | file written.</li>
|
---|
3119 | </ol>
|
---|
3120 |
|
---|
3121 | </desc>
|
---|
3122 |
|
---|
3123 | <attribute name="path" type="wstring" readonly="yes">
|
---|
3124 | <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
|
---|
3125 | the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
|
---|
3126 | <link to="#write" /> (for export).
|
---|
3127 | This attribute is empty until one of these methods has been called.
|
---|
3128 | </desc>
|
---|
3129 | </attribute>
|
---|
3130 |
|
---|
3131 | <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
|
---|
3132 | <desc>
|
---|
3133 | Array of virtual disk definitions. One such description exists for each
|
---|
3134 | disk definition in the OVF; each string array item represents one such piece of
|
---|
3135 | disk information, with the information fields separated by tab (\\t) characters.
|
---|
3136 |
|
---|
3137 | The caller should be prepared for additional fields being appended to
|
---|
3138 | this string in future versions of VirtualBox and therefore check for
|
---|
3139 | the number of tabs in the strings returned.
|
---|
3140 |
|
---|
3141 | In the current version, the following eight fields are returned per string
|
---|
3142 | in the array:
|
---|
3143 |
|
---|
3144 | <ol>
|
---|
3145 | <li>Disk ID (unique string identifier given to disk)</li>
|
---|
3146 |
|
---|
3147 | <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
|
---|
3148 |
|
---|
3149 | <li>Populated size (optional unsigned integer indicating the current size of the
|
---|
3150 | disk; can be approximate; -1 if unspecified)</li>
|
---|
3151 |
|
---|
3152 | <li>Format (string identifying the disk format, typically
|
---|
3153 | "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
|
---|
3154 |
|
---|
3155 | <li>Reference (where to find the disk image, typically a file name; if empty,
|
---|
3156 | then the disk should be created on import)</li>
|
---|
3157 |
|
---|
3158 | <li>Image size (optional unsigned integer indicating the size of the image,
|
---|
3159 | which need not necessarily be the same as the values specified above, since
|
---|
3160 | the image may be compressed or sparse; -1 if not specified)</li>
|
---|
3161 |
|
---|
3162 | <li>Chunk size (optional unsigned integer if the image is split into chunks;
|
---|
3163 | presently unsupported and always -1)</li>
|
---|
3164 |
|
---|
3165 | <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
|
---|
3166 | </ol>
|
---|
3167 | </desc>
|
---|
3168 | </attribute>
|
---|
3169 |
|
---|
3170 | <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
|
---|
3171 | <desc> Array of virtual system descriptions. One such description is created
|
---|
3172 | for each virtual system found in the OVF.
|
---|
3173 | This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
|
---|
3174 | (for export) has been called.
|
---|
3175 | </desc>
|
---|
3176 | </attribute>
|
---|
3177 |
|
---|
3178 | <method name="read">
|
---|
3179 | <desc>
|
---|
3180 | Reads an OVF file into the appliance object.
|
---|
3181 |
|
---|
3182 | This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
|
---|
3183 | mere fact that this method returns successfully does not mean that VirtualBox supports all
|
---|
3184 | features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
|
---|
3185 | </desc>
|
---|
3186 | <param name="file" type="wstring" dir="in">
|
---|
3187 | <desc>
|
---|
3188 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
3189 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
3190 | </desc>
|
---|
3191 | </param>
|
---|
3192 | </method>
|
---|
3193 |
|
---|
3194 | <method name="interpret">
|
---|
3195 | <desc>
|
---|
3196 | Interprets the OVF data that was read when the appliance was constructed. After
|
---|
3197 | calling this method, one can inspect the
|
---|
3198 | <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
|
---|
3199 | one <link to="IVirtualSystemDescription" /> for each virtual machine found in
|
---|
3200 | the appliance.
|
---|
3201 |
|
---|
3202 | Calling this method is the second step of importing an appliance into VirtualBox;
|
---|
3203 | see <link to="IAppliance" /> for an overview.
|
---|
3204 |
|
---|
3205 | After calling this method, one should call <link to="#getWarnings" /> to find out
|
---|
3206 | if problems were encountered during the processing which might later lead to
|
---|
3207 | errors.
|
---|
3208 | </desc>
|
---|
3209 | </method>
|
---|
3210 |
|
---|
3211 | <method name="importMachines">
|
---|
3212 | <desc>
|
---|
3213 | Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
|
---|
3214 | and other interfaces that match the information contained in the appliance as
|
---|
3215 | closely as possible, as represented by the import instructions in the
|
---|
3216 | <link to="#virtualSystemDescriptions" /> array.
|
---|
3217 |
|
---|
3218 | Calling this method is the final step of importing an appliance into VirtualBox;
|
---|
3219 | see <link to="IAppliance" /> for an overview.
|
---|
3220 |
|
---|
3221 | Since importing the appliance will most probably involve copying and converting
|
---|
3222 | disk images, which can take a long time, this method operates asynchronously and
|
---|
3223 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
3224 | </desc>
|
---|
3225 |
|
---|
3226 | <param name="aProgress" type="IProgress" dir="return">
|
---|
3227 | <desc></desc>
|
---|
3228 | </param>
|
---|
3229 | </method>
|
---|
3230 |
|
---|
3231 | <method name="write">
|
---|
3232 | <desc>
|
---|
3233 | Writes the contents of the appliance exports into a new OVF file.
|
---|
3234 |
|
---|
3235 | Calling this method is the final step of exporting an appliance from VirtualBox;
|
---|
3236 | see <link to="IAppliance" /> for an overview.
|
---|
3237 |
|
---|
3238 | Since exporting the appliance will most probably involve copying and converting
|
---|
3239 | disk images, which can take a long time, this method operates asynchronously and
|
---|
3240 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
3241 | </desc>
|
---|
3242 | <param name="format" type="wstring" dir="in">
|
---|
3243 | <desc>
|
---|
3244 | Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
|
---|
3245 | future versions of VirtualBox may support additional formats.
|
---|
3246 | </desc>
|
---|
3247 | </param>
|
---|
3248 | <param name="path" type="wstring" dir="in">
|
---|
3249 | <desc>
|
---|
3250 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
3251 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
3252 | </desc>
|
---|
3253 | </param>
|
---|
3254 | <param name="aProgress" type="IProgress" dir="return">
|
---|
3255 | <desc></desc>
|
---|
3256 | </param>
|
---|
3257 | </method>
|
---|
3258 |
|
---|
3259 | <method name="getWarnings">
|
---|
3260 | <desc>Returns textual warnings which occured during execution of <link to="#interpret" />.</desc>
|
---|
3261 |
|
---|
3262 | <param name="aWarnings" type="wstring" dir="return" safearray="yes">
|
---|
3263 | <desc></desc>
|
---|
3264 | </param>
|
---|
3265 | </method>
|
---|
3266 |
|
---|
3267 | </interface>
|
---|
3268 |
|
---|
3269 | <enum
|
---|
3270 | name="VirtualSystemDescriptionType"
|
---|
3271 | uuid="aacc58de-5b45-4f82-ae2e-dd9a824fc3b5"
|
---|
3272 | >
|
---|
3273 | <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
|
---|
3274 | a configuration value.</desc>
|
---|
3275 |
|
---|
3276 | <const name="Ignore" value="1" />
|
---|
3277 | <const name="OS" value="2" />
|
---|
3278 | <const name="Name" value="3" />
|
---|
3279 | <const name="Product" value="4" />
|
---|
3280 | <const name="Vendor" value="5" />
|
---|
3281 | <const name="Version" value="6" />
|
---|
3282 | <const name="ProductUrl" value="7" />
|
---|
3283 | <const name="VendorUrl" value="8" />
|
---|
3284 | <const name="Description" value="9" />
|
---|
3285 | <const name="License" value="10" />
|
---|
3286 | <const name="Miscellaneous" value="11" />
|
---|
3287 | <const name="CPU" value="12" />
|
---|
3288 | <const name="Memory" value="13" />
|
---|
3289 | <const name="HardDiskControllerIDE" value="14" />
|
---|
3290 | <const name="HardDiskControllerSATA" value="15" />
|
---|
3291 | <const name="HardDiskControllerSCSI" value="16" />
|
---|
3292 | <const name="HardDiskImage" value="17" />
|
---|
3293 | <const name="Floppy" value="18" />
|
---|
3294 | <const name="CDROM" value="19" />
|
---|
3295 | <const name="NetworkAdapter" value="20" />
|
---|
3296 | <const name="USBController" value="21" />
|
---|
3297 | <const name="SoundCard" value="22" />
|
---|
3298 |
|
---|
3299 | </enum>
|
---|
3300 |
|
---|
3301 | <enum
|
---|
3302 | name="VirtualSystemDescriptionValueType"
|
---|
3303 | uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
|
---|
3304 | >
|
---|
3305 | <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
|
---|
3306 | type to fetch.</desc>
|
---|
3307 |
|
---|
3308 | <const name="Reference" value="1" />
|
---|
3309 | <const name="Original" value="2" />
|
---|
3310 | <const name="Auto" value="3" />
|
---|
3311 | <const name="ExtraConfig" value="4" />
|
---|
3312 |
|
---|
3313 | </enum>
|
---|
3314 |
|
---|
3315 | <interface
|
---|
3316 | name="IVirtualSystemDescription" extends="$unknown"
|
---|
3317 | uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
|
---|
3318 | wsmap="managed"
|
---|
3319 | >
|
---|
3320 |
|
---|
3321 | <desc>This interface is used in the <link to="IAppliance::virtualSystemDescriptions" /> array.
|
---|
3322 | After <link to="IAppliance::interpret" /> has been called, that array contains
|
---|
3323 | information about how the virtual systems described in the OVF should best be imported into VirtualBox
|
---|
3324 | virtual machines. See <link to="IAppliance" /> for the steps required to import an OVF
|
---|
3325 | into VirtualBox.
|
---|
3326 | </desc>
|
---|
3327 |
|
---|
3328 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
3329 | <desc>Return the number of virtual system description entries.</desc>
|
---|
3330 | </attribute>
|
---|
3331 |
|
---|
3332 | <method name="getDescription">
|
---|
3333 | <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
|
---|
3334 | items with the same indices correspond and jointly represent an import instruction for VirtualBox.
|
---|
3335 |
|
---|
3336 | The list below identifies the value sets that are possible depending on the
|
---|
3337 | <link to="VirtualSystemDescriptionType" /> enum value in the array item in aTypes[]. In each case,
|
---|
3338 | the array item with the same index in aOvfValues[] will contain the original value as contained
|
---|
3339 | in the OVF file (just for informational purposes), and the corresponding item in aVboxValues[]
|
---|
3340 | will contain a suggested value to be used for VirtualBox. Depending on the description type,
|
---|
3341 | the aExtraConfigValues[] array item may also be used.
|
---|
3342 |
|
---|
3343 | <ul>
|
---|
3344 | <li>
|
---|
3345 | "OS": the guest operating system type. There must be exactly one such array item on import. The
|
---|
3346 | corresponding item in aVboxValues[] contains the suggested guest operating system for VirtualBox.
|
---|
3347 | This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
|
---|
3348 | item in aOvfValues[] will contain a numerical value that described the operating system in the OVF
|
---|
3349 | (see <link to="CIMOSType" />).
|
---|
3350 | </li>
|
---|
3351 | <li>
|
---|
3352 | "Name": the name to give to the new virtual machine. There can be at most one such array item;
|
---|
3353 | if none is present on import, then an automatic name will be created from the operating system
|
---|
3354 | type. The correponding item im aOvfValues[] will contain the suggested virtual machine name
|
---|
3355 | from the OVF file, and aVboxValues[] will contain a suggestion for a unique VirtualBox
|
---|
3356 | <link to="IMachine" /> name that does not exist yet.
|
---|
3357 | </li>
|
---|
3358 | <li>
|
---|
3359 | "Description": an arbitrary description.
|
---|
3360 | </li>
|
---|
3361 | <li>
|
---|
3362 | "License": the EULA section from the OVF, if present. It is the responsibility of the calling
|
---|
3363 | code to display such a license for agreement; the Main API does not enforce any such policy.
|
---|
3364 | </li>
|
---|
3365 | <li>
|
---|
3366 | Miscellaneous: reserved for future use.
|
---|
3367 | </li>
|
---|
3368 | <li>
|
---|
3369 | "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
|
---|
3370 | </li>
|
---|
3371 | <li>
|
---|
3372 | "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
|
---|
3373 | is present on import, then VirtualBox will set a meaningful default based on the operating system
|
---|
3374 | type.
|
---|
3375 | </li>
|
---|
3376 | <li>
|
---|
3377 | "HarddiskControllerIDE": an IDE hard disk controller. There can be at most one such item. This
|
---|
3378 | has no value in aOvfValues[] or aVboxValues[].
|
---|
3379 | The matching item in the aRefs[] array will contain an integer that items of the "Harddisk"
|
---|
3380 | type can use to specify which hard disk controller a virtual disk should be connected to.
|
---|
3381 | </li>
|
---|
3382 | <li>
|
---|
3383 | "HarddiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
|
---|
3384 | has no value in aOvfValues[] or aVboxValues[].
|
---|
3385 | The matching item in the aRefs[] array will be used as with IDE controllers (see above).
|
---|
3386 | </li>
|
---|
3387 | <li>
|
---|
3388 | "HarddiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
|
---|
3389 | The items in aOvfValues[] and aVboxValues[] will either be "LsiLogic" or "BusLogic".
|
---|
3390 | The matching item in the aRefs[] array will be used as with IDE controllers (see above).
|
---|
3391 | </li>
|
---|
3392 | <li>
|
---|
3393 | "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
|
---|
3394 | arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
|
---|
3395 |
|
---|
3396 | The array item in aOvfValues[] will contain the file specification from the OVF file (without
|
---|
3397 | a path since the image file should be in the same location as the OVF file itself), whereas the
|
---|
3398 | item in aVboxValues[] will contain a qualified path specification to where VirtualBox uses the
|
---|
3399 | hard disk image. This means that on import the image will be copied and converted from the
|
---|
3400 | "ovf" location to the "vbox" location; on export, this will be handled the other way round.
|
---|
3401 | On import, the target image will also be registered with VirtualBox.
|
---|
3402 |
|
---|
3403 | The matching item in the aExtraConfigValues[] array must contain a string of the following
|
---|
3404 | format: "controller=<index>;channel=<c>"
|
---|
3405 | In this string, <index> must be an integer specifying the hard disk controller to connect
|
---|
3406 | the image to. That number must be the index of an array item with one of the hard disk controller
|
---|
3407 | types (HarddiskControllerSCSI, HarddiskControllerSATA, HarddiskControllerIDE).
|
---|
3408 | In addition, <c> must specify the channel to use on that controller. For IDE controllers,
|
---|
3409 | this can range from 0-2 (which VirtualBox will interpret as primary master, primary slave,
|
---|
3410 | secondary slave; VirtualBox reserves the secondary master for the CD-ROM drive). For SATA and
|
---|
3411 | SCSI conrollers, the channel can range from 0-29.
|
---|
3412 | </li>
|
---|
3413 | <li>
|
---|
3414 | "NetworkAdapter": a network adapter. The array item in aVboxValues[] will specify the hardware
|
---|
3415 | for the network adapter, whereas the array item in aExtraConfigValues[] will have a string
|
---|
3416 | of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
|
---|
3417 | </li>
|
---|
3418 | <li>
|
---|
3419 | "USBController": a USB controller. There can be at most one such item. If and only if such an
|
---|
3420 | item ispresent, USB support will be enabled for the new virtual machine.
|
---|
3421 | </li>
|
---|
3422 | <li>
|
---|
3423 | "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
|
---|
3424 | present, sound support will be enabled for the new virtual machine. Note that the virtual
|
---|
3425 | machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
|
---|
3426 | may be different from the virtual soundcard expected by the appliance.
|
---|
3427 | </li>
|
---|
3428 | </ul>
|
---|
3429 |
|
---|
3430 | </desc>
|
---|
3431 |
|
---|
3432 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
3433 | <desc></desc>
|
---|
3434 | </param>
|
---|
3435 |
|
---|
3436 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
3437 | <desc></desc>
|
---|
3438 | </param>
|
---|
3439 |
|
---|
3440 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
3441 | <desc></desc>
|
---|
3442 | </param>
|
---|
3443 |
|
---|
3444 | <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
|
---|
3445 | <desc></desc>
|
---|
3446 | </param>
|
---|
3447 |
|
---|
3448 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
3449 | <desc></desc>
|
---|
3450 | </param>
|
---|
3451 |
|
---|
3452 | </method>
|
---|
3453 |
|
---|
3454 | <method name="getDescriptionByType">
|
---|
3455 | <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
|
---|
3456 | should be returned.</desc>
|
---|
3457 |
|
---|
3458 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
3459 | <desc></desc>
|
---|
3460 | </param>
|
---|
3461 |
|
---|
3462 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
3463 | <desc></desc>
|
---|
3464 | </param>
|
---|
3465 |
|
---|
3466 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
3467 | <desc></desc>
|
---|
3468 | </param>
|
---|
3469 |
|
---|
3470 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
3471 | <desc></desc>
|
---|
3472 | </param>
|
---|
3473 |
|
---|
3474 | <param name="aVboxValues" type="wstring" dir="out" safearray="yes">
|
---|
3475 | <desc></desc>
|
---|
3476 | </param>
|
---|
3477 |
|
---|
3478 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
3479 | <desc></desc>
|
---|
3480 | </param>
|
---|
3481 |
|
---|
3482 | </method>
|
---|
3483 |
|
---|
3484 | <method name="getValuesByType">
|
---|
3485 | <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
|
---|
3486 | value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
|
---|
3487 | values.</desc>
|
---|
3488 |
|
---|
3489 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
3490 | <desc></desc>
|
---|
3491 | </param>
|
---|
3492 |
|
---|
3493 | <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
|
---|
3494 | <desc></desc>
|
---|
3495 | </param>
|
---|
3496 |
|
---|
3497 | <param name="aValues" type="wstring" dir="return" safearray="yes">
|
---|
3498 | <desc></desc>
|
---|
3499 | </param>
|
---|
3500 |
|
---|
3501 | </method>
|
---|
3502 |
|
---|
3503 | <method name="setFinalValues">
|
---|
3504 | <desc>
|
---|
3505 | This method allows the appliance's user to change the configuration for the virtual
|
---|
3506 | system descriptions. For each array item returned from <link to="#getDescription" />,
|
---|
3507 | you must pass in one boolean value and one configuration value.
|
---|
3508 |
|
---|
3509 | Each item in the boolean array determines whether the particular configuration item
|
---|
3510 | should be enabled.
|
---|
3511 | You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
|
---|
3512 | HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
|
---|
3513 | and SoundCard.
|
---|
3514 |
|
---|
3515 | For the "vbox" and "extra configuration" values, if you pass in the same arrays
|
---|
3516 | as returned in the aVboxValues and aExtraConfigValues arrays from getDescription(),
|
---|
3517 | the configuration remains unchanged. Please see the documentation for getDescription()
|
---|
3518 | for valid configuration values for the individual array item types. If the
|
---|
3519 | corresponding item in the aEnabled array is false, the configuration value is ignored.
|
---|
3520 | </desc>
|
---|
3521 |
|
---|
3522 | <param name="aEnabled" type="boolean" dir="in" safearray="yes">
|
---|
3523 | <desc></desc>
|
---|
3524 | </param>
|
---|
3525 |
|
---|
3526 | <param name="aVboxValues" type="wstring" dir="in" safearray="yes">
|
---|
3527 | <desc></desc>
|
---|
3528 | </param>
|
---|
3529 |
|
---|
3530 | <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
|
---|
3531 | <desc></desc>
|
---|
3532 | </param>
|
---|
3533 | </method>
|
---|
3534 |
|
---|
3535 | <method name="addDescription">
|
---|
3536 | <desc>
|
---|
3537 | This method adds an additional description entry to the stack of already
|
---|
3538 | available descriptions for this virtual system. This is handy for writing
|
---|
3539 | values which aren't directly supported by VirtualBox. One example would
|
---|
3540 | be the License type of <link to="VirtualSystemDescriptionType" />.
|
---|
3541 | </desc>
|
---|
3542 |
|
---|
3543 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
3544 | <desc></desc>
|
---|
3545 | </param>
|
---|
3546 |
|
---|
3547 | <param name="aVboxValue" type="wstring" dir="in">
|
---|
3548 | <desc></desc>
|
---|
3549 | </param>
|
---|
3550 |
|
---|
3551 | <param name="aExtraConfigValue" type="wstring" dir="in">
|
---|
3552 | <desc></desc>
|
---|
3553 | </param>
|
---|
3554 | </method>
|
---|
3555 | </interface>
|
---|
3556 |
|
---|
3557 |
|
---|
3558 | <!--
|
---|
3559 | // IMachine
|
---|
3560 | /////////////////////////////////////////////////////////////////////////
|
---|
3561 | -->
|
---|
3562 |
|
---|
3563 | <interface
|
---|
3564 | name="IInternalMachineControl" extends="$unknown"
|
---|
3565 | uuid="2c88b969-7a74-4ef3-b95f-8a209a1535f3"
|
---|
3566 | internal="yes"
|
---|
3567 | wsmap="suppress"
|
---|
3568 | >
|
---|
3569 | <method name="updateState">
|
---|
3570 | <desc>
|
---|
3571 | Updates the VM state.
|
---|
3572 | <note>
|
---|
3573 | This operation will also update the settings file with
|
---|
3574 | the correct information about the saved state file
|
---|
3575 | and delete this file from disk when appropriate.
|
---|
3576 | </note>
|
---|
3577 | </desc>
|
---|
3578 | <param name="state" type="MachineState" dir="in"/>
|
---|
3579 | </method>
|
---|
3580 |
|
---|
3581 | <method name="getIPCId">
|
---|
3582 | <param name="id" type="wstring" dir="return"/>
|
---|
3583 | </method>
|
---|
3584 |
|
---|
3585 | <method name="runUSBDeviceFilters">
|
---|
3586 | <desc>
|
---|
3587 | Asks the server to run USB devices filters of the associated
|
---|
3588 | machine against the given USB device and tell if there is
|
---|
3589 | a match.
|
---|
3590 | <note>
|
---|
3591 | Intended to be used only for remote USB devices. Local
|
---|
3592 | ones don't require to call this method (this is done
|
---|
3593 | implicitly by the Host and USBProxyService).
|
---|
3594 | </note>
|
---|
3595 | </desc>
|
---|
3596 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
3597 | <param name="matched" type="boolean" dir="out"/>
|
---|
3598 | <param name="maskedInterfaces" type="unsigned long" dir="out"/>
|
---|
3599 | </method>
|
---|
3600 |
|
---|
3601 | <method name="captureUSBDevice">
|
---|
3602 | <desc>
|
---|
3603 | Requests a capture of the given host USB device.
|
---|
3604 | When the request is completed, the VM process will
|
---|
3605 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3606 | notification.
|
---|
3607 | </desc>
|
---|
3608 | <param name="id" type="uuid" dir="in"/>
|
---|
3609 | </method>
|
---|
3610 |
|
---|
3611 | <method name="detachUSBDevice">
|
---|
3612 | <desc>
|
---|
3613 | Notification that a VM is going to detach (done = false) or has
|
---|
3614 | already detached (done = true) the given USB device.
|
---|
3615 | When the done = true request is completed, the VM process will
|
---|
3616 | get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
|
---|
3617 | notification.
|
---|
3618 | <note>
|
---|
3619 | In the done = true case, the server must run its own filters
|
---|
3620 | and filters of all VMs but this one on the detached device
|
---|
3621 | as if it were just attached to the host computer.
|
---|
3622 | </note>
|
---|
3623 | </desc>
|
---|
3624 | <param name="id" type="uuid" dir="in"/>
|
---|
3625 | <param name="done" type="boolean" dir="in"/>
|
---|
3626 | </method>
|
---|
3627 |
|
---|
3628 | <method name="autoCaptureUSBDevices">
|
---|
3629 | <desc>
|
---|
3630 | Requests a capture all matching USB devices attached to the host.
|
---|
3631 | When the request is completed, the VM process will
|
---|
3632 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3633 | notification per every captured device.
|
---|
3634 | </desc>
|
---|
3635 | </method>
|
---|
3636 |
|
---|
3637 | <method name="detachAllUSBDevices">
|
---|
3638 | <desc>
|
---|
3639 | Notification that a VM that is being powered down. The done
|
---|
3640 | parameter indicates whether which stage of the power down
|
---|
3641 | we're at. When done = false the VM is announcing its
|
---|
3642 | intentions, while when done = true the VM is reporting
|
---|
3643 | what it has done.
|
---|
3644 | <note>
|
---|
3645 | In the done = true case, the server must run its own filters
|
---|
3646 | and filters of all VMs but this one on all detach devices as
|
---|
3647 | if they were just attached to the host computer.
|
---|
3648 | </note>
|
---|
3649 | </desc>
|
---|
3650 | <param name="done" type="boolean" dir="in"/>
|
---|
3651 | </method>
|
---|
3652 |
|
---|
3653 | <method name="onSessionEnd">
|
---|
3654 | <desc>
|
---|
3655 | Triggered by the given session object when the session is about
|
---|
3656 | to close normally.
|
---|
3657 | </desc>
|
---|
3658 | <param name="session" type="ISession" dir="in">
|
---|
3659 | <desc>Session that is being closed</desc>
|
---|
3660 | </param>
|
---|
3661 | <param name="progress" type="IProgress" dir="return">
|
---|
3662 | <desc>
|
---|
3663 | Used to wait until the corresponding machine is actually
|
---|
3664 | dissociated from the given session on the server.
|
---|
3665 | Returned only when this session is a direct one.
|
---|
3666 | </desc>
|
---|
3667 | </param>
|
---|
3668 | </method>
|
---|
3669 |
|
---|
3670 | <method name="beginSavingState">
|
---|
3671 | <desc>
|
---|
3672 | Called by the VM process to inform the server it wants to
|
---|
3673 | save the current state and stop the VM execution.
|
---|
3674 | </desc>
|
---|
3675 | <param name="progress" type="IProgress" dir="in">
|
---|
3676 | <desc>
|
---|
3677 | Progress object created by the VM process to wait until
|
---|
3678 | the state is saved.
|
---|
3679 | </desc>
|
---|
3680 | </param>
|
---|
3681 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3682 | <desc>
|
---|
3683 | File path the VM process must save the execution state to.
|
---|
3684 | </desc>
|
---|
3685 | </param>
|
---|
3686 | </method>
|
---|
3687 |
|
---|
3688 | <method name="endSavingState">
|
---|
3689 | <desc>
|
---|
3690 | Called by the VM process to inform the server that saving
|
---|
3691 | the state previously requested by #beginSavingState is either
|
---|
3692 | successfully finished or there was a failure.
|
---|
3693 |
|
---|
3694 | <result name="VBOX_E_FILE_ERROR">
|
---|
3695 | Settings file not accessible.
|
---|
3696 | </result>
|
---|
3697 | <result name="VBOX_E_XML_ERROR">
|
---|
3698 | Could not parse the settings file.
|
---|
3699 | </result>
|
---|
3700 |
|
---|
3701 | </desc>
|
---|
3702 |
|
---|
3703 | <param name="success" type="boolean" dir="in">
|
---|
3704 | <desc><tt>true</tt> to indicate success and <tt>false</tt>
|
---|
3705 | otherwise.
|
---|
3706 | </desc>
|
---|
3707 | </param>
|
---|
3708 | </method>
|
---|
3709 |
|
---|
3710 | <method name="adoptSavedState">
|
---|
3711 | <desc>
|
---|
3712 | Gets called by IConsole::adoptSavedState.
|
---|
3713 | <result name="VBOX_E_FILE_ERROR">
|
---|
3714 | Invalid saved state file path.
|
---|
3715 | </result>
|
---|
3716 | </desc>
|
---|
3717 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
3718 | <desc>Path to the saved state file to adopt.</desc>
|
---|
3719 | </param>
|
---|
3720 | </method>
|
---|
3721 |
|
---|
3722 | <method name="beginTakingSnapshot">
|
---|
3723 | <desc>
|
---|
3724 | Called by the VM process to inform the server it wants to
|
---|
3725 | take a snapshot.
|
---|
3726 |
|
---|
3727 | <result name="VBOX_E_FILE_ERROR">
|
---|
3728 | Settings file not accessible.
|
---|
3729 | </result>
|
---|
3730 | <result name="VBOX_E_XML_ERROR">
|
---|
3731 | Could not parse the settings file.
|
---|
3732 | </result>
|
---|
3733 | </desc>
|
---|
3734 | <param name="initiator" type="IConsole" dir="in">
|
---|
3735 | <desc>The console object that initiated this call.</desc>
|
---|
3736 | </param>
|
---|
3737 | <param name="name" type="wstring" dir="in">
|
---|
3738 | <desc>Snapshot name.</desc>
|
---|
3739 | </param>
|
---|
3740 | <param name="description" type="wstring" dir="in">
|
---|
3741 | <desc>Snapshot description.</desc>
|
---|
3742 | </param>
|
---|
3743 | <param name="progress" type="IProgress" dir="in">
|
---|
3744 | <desc>
|
---|
3745 | Progress object created by the VM process to wait until
|
---|
3746 | the state is saved (only for online snapshots).
|
---|
3747 | </desc>
|
---|
3748 | </param>
|
---|
3749 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3750 | <desc>
|
---|
3751 | File path the VM process must save the execution state to.
|
---|
3752 | </desc>
|
---|
3753 | </param>
|
---|
3754 | <param name="serverProgress" type="IProgress" dir="out">
|
---|
3755 | <desc>
|
---|
3756 | Progress object created by the server process to wait until
|
---|
3757 | the snapshot is taken (VDI diff creation, etc.).
|
---|
3758 | </desc>
|
---|
3759 | </param>
|
---|
3760 | </method>
|
---|
3761 |
|
---|
3762 | <method name="endTakingSnapshot">
|
---|
3763 | <desc>
|
---|
3764 | Called by the VM process to inform the server that the snapshot
|
---|
3765 | previously requested by #beginTakingSnapshot is either
|
---|
3766 | successfully taken or there was a failure.
|
---|
3767 | </desc>
|
---|
3768 |
|
---|
3769 | <param name="success" type="boolean" dir="in">
|
---|
3770 | <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
|
---|
3771 | </param>
|
---|
3772 | </method>
|
---|
3773 |
|
---|
3774 | <method name="discardSnapshot">
|
---|
3775 | <desc>
|
---|
3776 | Gets called by IConsole::discardSnapshot.
|
---|
3777 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
3778 | Snapshot has more than one child snapshot.
|
---|
3779 | </result>
|
---|
3780 | </desc>
|
---|
3781 | <param name="initiator" type="IConsole" dir="in">
|
---|
3782 | <desc>The console object that initiated this call.</desc>
|
---|
3783 | </param>
|
---|
3784 | <param name="id" type="uuid" dir="in">
|
---|
3785 | <desc>UUID of the snapshot to discard.</desc>
|
---|
3786 | </param>
|
---|
3787 | <param name="machineState" type="MachineState" dir="out">
|
---|
3788 | <desc>New machine state after this operation is started.</desc>
|
---|
3789 | </param>
|
---|
3790 | <param name="progress" type="IProgress" dir="return">
|
---|
3791 | <desc>Progress object to track the operation completion.</desc>
|
---|
3792 | </param>
|
---|
3793 | </method>
|
---|
3794 |
|
---|
3795 | <method name="discardCurrentState">
|
---|
3796 | <desc>
|
---|
3797 | Gets called by IConsole::discardCurrentState.
|
---|
3798 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
3799 | Virtual machine does not have any snapshot.
|
---|
3800 | </result>
|
---|
3801 | </desc>
|
---|
3802 | <param name="initiator" type="IConsole" dir="in">
|
---|
3803 | <desc>The console object that initiated this call.</desc>
|
---|
3804 | </param>
|
---|
3805 | <param name="machineState" type="MachineState" dir="out">
|
---|
3806 | <desc>New machine state after this operation is started.</desc>
|
---|
3807 | </param>
|
---|
3808 | <param name="progress" type="IProgress" dir="return">
|
---|
3809 | <desc>Progress object to track the operation completion.</desc>
|
---|
3810 | </param>
|
---|
3811 | </method>
|
---|
3812 |
|
---|
3813 | <method name="discardCurrentSnapshotAndState">
|
---|
3814 | <desc>
|
---|
3815 | Gets called by IConsole::discardCurrentSnapshotAndState.
|
---|
3816 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
3817 | Virtual machine does not have any snapshot.
|
---|
3818 | </result>
|
---|
3819 | </desc>
|
---|
3820 | <param name="initiator" type="IConsole" dir="in">
|
---|
3821 | <desc>The console object that initiated this call.</desc>
|
---|
3822 | </param>
|
---|
3823 | <param name="machineState" type="MachineState" dir="out">
|
---|
3824 | <desc>New machine state after this operation is started.</desc>
|
---|
3825 | </param>
|
---|
3826 | <param name="progress" type="IProgress" dir="return">
|
---|
3827 | <desc>Progress object to track the operation completion.</desc>
|
---|
3828 | </param>
|
---|
3829 | </method>
|
---|
3830 |
|
---|
3831 | <method name="pullGuestProperties">
|
---|
3832 | <desc>
|
---|
3833 | Get the list of the guest properties matching a set of patterns along
|
---|
3834 | with their values, time stamps and flags and give responsibility for
|
---|
3835 | managing properties to the console.
|
---|
3836 | </desc>
|
---|
3837 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
3838 | <desc>
|
---|
3839 | The names of the properties returned.
|
---|
3840 | </desc>
|
---|
3841 | </param>
|
---|
3842 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
3843 | <desc>
|
---|
3844 | The values of the properties returned. The array entries match the
|
---|
3845 | corresponding entries in the @a name array.
|
---|
3846 | </desc>
|
---|
3847 | </param>
|
---|
3848 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
3849 | <desc>
|
---|
3850 | The time stamps of the properties returned. The array entries match
|
---|
3851 | the corresponding entries in the @a name array.
|
---|
3852 | </desc>
|
---|
3853 | </param>
|
---|
3854 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
3855 | <desc>
|
---|
3856 | The flags of the properties returned. The array entries match the
|
---|
3857 | corresponding entries in the @a name array.
|
---|
3858 | </desc>
|
---|
3859 | </param>
|
---|
3860 | </method>
|
---|
3861 |
|
---|
3862 | <method name="pushGuestProperties">
|
---|
3863 | <desc>
|
---|
3864 | Set the list of the guest properties matching a set of patterns along
|
---|
3865 | with their values, time stamps and flags and return responsibility for
|
---|
3866 | managing properties to IMachine.
|
---|
3867 | </desc>
|
---|
3868 | <param name="name" type="wstring" dir="in" safearray="yes">
|
---|
3869 | <desc>
|
---|
3870 | The names of the properties.
|
---|
3871 | </desc>
|
---|
3872 | </param>
|
---|
3873 | <param name="value" type="wstring" dir="in" safearray="yes">
|
---|
3874 | <desc>
|
---|
3875 | The values of the properties. The array entries match the
|
---|
3876 | corresponding entries in the @a name array.
|
---|
3877 | </desc>
|
---|
3878 | </param>
|
---|
3879 | <param name="timestamp" type="unsigned long long" dir="in" safearray="yes">
|
---|
3880 | <desc>
|
---|
3881 | The time stamps of the properties. The array entries match
|
---|
3882 | the corresponding entries in the @a name array.
|
---|
3883 | </desc>
|
---|
3884 | </param>
|
---|
3885 | <param name="flags" type="wstring" dir="in" safearray="yes">
|
---|
3886 | <desc>
|
---|
3887 | The flags of the properties. The array entries match the
|
---|
3888 | corresponding entries in the @a name array.
|
---|
3889 | </desc>
|
---|
3890 | </param>
|
---|
3891 | </method>
|
---|
3892 | <method name="pushGuestProperty">
|
---|
3893 | <desc>
|
---|
3894 | Update a single guest property in IMachine.
|
---|
3895 | </desc>
|
---|
3896 | <param name="name" type="wstring" dir="in">
|
---|
3897 | <desc>
|
---|
3898 | The name of the property to be updated.
|
---|
3899 | </desc>
|
---|
3900 | </param>
|
---|
3901 | <param name="value" type="wstring" dir="in">
|
---|
3902 | <desc>
|
---|
3903 | The value of the property.
|
---|
3904 | </desc>
|
---|
3905 | </param>
|
---|
3906 | <param name="timestamp" type="unsigned long long" dir="in">
|
---|
3907 | <desc>
|
---|
3908 | The timestamp of the property.
|
---|
3909 | </desc>
|
---|
3910 | </param>
|
---|
3911 | <param name="flags" type="wstring" dir="in">
|
---|
3912 | <desc>
|
---|
3913 | The flags of the property.
|
---|
3914 | </desc>
|
---|
3915 | </param>
|
---|
3916 | </method>
|
---|
3917 |
|
---|
3918 | <method name="lockMedia">
|
---|
3919 | <desc>
|
---|
3920 | Locks all media attached to the machine for writing and parents of
|
---|
3921 | attahced different hard disks (if any) for reading. This operation is
|
---|
3922 | atomic so that if it fails no media is actually locked.
|
---|
3923 |
|
---|
3924 | This method is intended to be called when the machine is in Starting or
|
---|
3925 | Restoring state. The locked media will be automatically unlocked when
|
---|
3926 | the machine is powered off or crashed.
|
---|
3927 | </desc>
|
---|
3928 | </method>
|
---|
3929 | </interface>
|
---|
3930 |
|
---|
3931 | <interface
|
---|
3932 | name="IBIOSSettings" extends="$unknown"
|
---|
3933 | uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
|
---|
3934 | wsmap="managed"
|
---|
3935 | >
|
---|
3936 | <desc>
|
---|
3937 | The IBIOSSettings interface represents BIOS settings of the virtual
|
---|
3938 | machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
|
---|
3939 | </desc>
|
---|
3940 | <attribute name="logoFadeIn" type="boolean">
|
---|
3941 | <desc>Fade in flag for BIOS logo animation.</desc>
|
---|
3942 | </attribute>
|
---|
3943 |
|
---|
3944 | <attribute name="logoFadeOut" type="boolean">
|
---|
3945 | <desc>Fade out flag for BIOS logo animation.</desc>
|
---|
3946 | </attribute>
|
---|
3947 |
|
---|
3948 | <attribute name="logoDisplayTime" type="unsigned long">
|
---|
3949 | <desc>BIOS logo display time in milliseconds (0 = default).</desc>
|
---|
3950 | </attribute>
|
---|
3951 |
|
---|
3952 | <attribute name="logoImagePath" type="wstring">
|
---|
3953 | <desc>Local file system path for external BIOS image.</desc>
|
---|
3954 | </attribute>
|
---|
3955 |
|
---|
3956 | <attribute name="bootMenuMode" type="BIOSBootMenuMode">
|
---|
3957 | <desc>Mode of the BIOS boot device menu.</desc>
|
---|
3958 | </attribute>
|
---|
3959 |
|
---|
3960 | <attribute name="ACPIEnabled" type="boolean">
|
---|
3961 | <desc>ACPI support flag.</desc>
|
---|
3962 | </attribute>
|
---|
3963 |
|
---|
3964 | <attribute name="IOAPICEnabled" type="boolean">
|
---|
3965 | <desc>
|
---|
3966 | IO APIC support flag. If set, VirtualBox will provide an IO APIC
|
---|
3967 | and support IRQs above 15.
|
---|
3968 | </desc>
|
---|
3969 | </attribute>
|
---|
3970 |
|
---|
3971 | <attribute name="timeOffset" type="long long">
|
---|
3972 | <desc>
|
---|
3973 | Offset in milliseconds from the host system time. This allows for
|
---|
3974 | guests running with a different system date/time than the host.
|
---|
3975 | It is equivalent to setting the system date/time in the BIOS except
|
---|
3976 | it is not an absolute value but a relative one. Guest Additions
|
---|
3977 | time synchronization honors this offset.
|
---|
3978 | </desc>
|
---|
3979 | </attribute>
|
---|
3980 |
|
---|
3981 | <attribute name="PXEDebugEnabled" type="boolean">
|
---|
3982 | <desc>
|
---|
3983 | PXE debug logging flag. If set, VirtualBox will write extensive
|
---|
3984 | PXE trace information to the release log.
|
---|
3985 | </desc>
|
---|
3986 | </attribute>
|
---|
3987 |
|
---|
3988 | </interface>
|
---|
3989 |
|
---|
3990 | <interface
|
---|
3991 | name="IMachine" extends="$unknown"
|
---|
3992 | uuid="13420cbb-175a-4456-85d0-301126dfdec7"
|
---|
3993 | wsmap="managed"
|
---|
3994 | >
|
---|
3995 | <desc>
|
---|
3996 | The IMachine interface represents a virtual machine, or guest, created
|
---|
3997 | in VirtualBox.
|
---|
3998 |
|
---|
3999 | This interface is used in two contexts. First of all, a collection of
|
---|
4000 | objects implementing this interface is stored in the
|
---|
4001 | <link to="IVirtualBox::machines"/> attribute which lists all the virtual
|
---|
4002 | machines that are currently registered with this VirtualBox
|
---|
4003 | installation. Also, once a session has been opened for the given virtual
|
---|
4004 | machine (e.g. the virtual machine is running), the machine object
|
---|
4005 | associated with the open session can be queried from the session object;
|
---|
4006 | see <link to="ISession"/> for details.
|
---|
4007 |
|
---|
4008 | The main role of this interface is to expose the settings of the virtual
|
---|
4009 | machine and provide methods to change various aspects of the virtual
|
---|
4010 | machine's configuration. For machine objects stored in the
|
---|
4011 | <link to="IVirtualBox::machines"/> collection, all attributes are
|
---|
4012 | read-only unless explicitly stated otherwise in individual attribute
|
---|
4013 | and method descriptions. In order to change a machine setting, a session
|
---|
4014 | for this machine must be opened using one of
|
---|
4015 | <link to="IVirtualBox::openSession"/>,
|
---|
4016 | <link to="IVirtualBox::openRemoteSession"/> or
|
---|
4017 | <link to="IVirtualBox::openExistingSession"/> methods. After the
|
---|
4018 | session has been successfully opened, a mutable machine object needs to
|
---|
4019 | be queried from the session object and then the desired settings changes
|
---|
4020 | can be applied to the returned object using IMachine attributes and
|
---|
4021 | methods. See the ISession interface description for more information
|
---|
4022 | about sessions.
|
---|
4023 |
|
---|
4024 | Note that the IMachine interface does not provide methods to control
|
---|
4025 | virtual machine execution (such as start the machine, or power it
|
---|
4026 | down) -- these methods are grouped in a separate IConsole
|
---|
4027 | interface. Refer to the IConsole interface description to get more
|
---|
4028 | information about this topic.
|
---|
4029 |
|
---|
4030 | <see>ISession, IConsole</see>
|
---|
4031 | </desc>
|
---|
4032 |
|
---|
4033 | <attribute name="parent" type="IVirtualBox" readonly="yes">
|
---|
4034 | <desc>Associated parent object.</desc>
|
---|
4035 | </attribute>
|
---|
4036 |
|
---|
4037 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
4038 | <desc>
|
---|
4039 | Whether this virtual machine is currently accessible or not.
|
---|
4040 |
|
---|
4041 | The machine is considered to be inaccessible when:
|
---|
4042 | <ul>
|
---|
4043 | <li>It is a registered virtual machine, and
|
---|
4044 | </li>
|
---|
4045 | <li>Its settings file is inaccessible (for example, it is
|
---|
4046 | located on a network share that is not accessible during
|
---|
4047 | VirtualBox startup, or becomes inaccessible later, or if
|
---|
4048 | the settings file can be read but is invalid).
|
---|
4049 | </li>
|
---|
4050 | </ul>
|
---|
4051 |
|
---|
4052 | Otherwise, the value of this property is always <tt>true</tt>.
|
---|
4053 |
|
---|
4054 | Every time this property is read, the accessibility state of
|
---|
4055 | this machine is re-evaluated. If the returned value is |false|,
|
---|
4056 | the <link to="#accessError"/> property may be used to get the
|
---|
4057 | detailed error information describing the reason of
|
---|
4058 | inaccessibility.
|
---|
4059 |
|
---|
4060 | When the machine is inaccessible, only the following properties
|
---|
4061 | can be used on it:
|
---|
4062 | <ul>
|
---|
4063 | <li><link to="#parent"/></li>
|
---|
4064 | <li><link to="#id"/></li>
|
---|
4065 | <li><link to="#settingsFilePath"/></li>
|
---|
4066 | <li><link to="#accessible"/></li>
|
---|
4067 | <li><link to="#accessError"/></li>
|
---|
4068 | </ul>
|
---|
4069 |
|
---|
4070 | An attempt to access any other property or method will return
|
---|
4071 | an error.
|
---|
4072 |
|
---|
4073 | The only possible action you can perform on an inaccessible
|
---|
4074 | machine is to unregister it using the
|
---|
4075 | <link to="IVirtualBox::unregisterMachine"/> call (or, to check
|
---|
4076 | for the accessibility state once more by querying this
|
---|
4077 | property).
|
---|
4078 |
|
---|
4079 | <note>
|
---|
4080 | In the current implementation, once this property returns
|
---|
4081 | <tt>true</tt>, the machine will never become inaccessible
|
---|
4082 | later, even if its settings file cannot be successfully
|
---|
4083 | read/written any more (at least, until the VirtualBox
|
---|
4084 | server is restarted). This limitation may be removed in
|
---|
4085 | future releases.
|
---|
4086 | </note>
|
---|
4087 | </desc>
|
---|
4088 | </attribute>
|
---|
4089 |
|
---|
4090 | <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
4091 | <desc>
|
---|
4092 | Error information describing the reason of machine
|
---|
4093 | inaccessibility.
|
---|
4094 |
|
---|
4095 | Reading this property is only valid after the last call to
|
---|
4096 | <link to="#accessible"/> returned <tt>false</tt> (i.e. the
|
---|
4097 | machine is currently unaccessible). Otherwise, a null
|
---|
4098 | IVirtualBoxErrorInfo object will be returned.
|
---|
4099 | </desc>
|
---|
4100 | </attribute>
|
---|
4101 |
|
---|
4102 | <attribute name="name" type="wstring">
|
---|
4103 | <desc>
|
---|
4104 | Name of the virtual machine.
|
---|
4105 |
|
---|
4106 | Besides being used for human-readable identification purposes
|
---|
4107 | everywhere in VirtualBox, the virtual machine name is also used
|
---|
4108 | as a name of the machine's settings file and as a name of the
|
---|
4109 | subdirectory this settings file resides in. Thus, every time you
|
---|
4110 | change the value of this property, the settings file will be
|
---|
4111 | renamed once you call <link to="#saveSettings"/> to confirm the
|
---|
4112 | change. The containing subdirectory will be also renamed, but
|
---|
4113 | only if it has exactly the same name as the settings file
|
---|
4114 | itself prior to changing this property (for backward compatibility
|
---|
4115 | with previous API releases). The above implies the following
|
---|
4116 | limitations:
|
---|
4117 | <ul>
|
---|
4118 | <li>The machine name cannot be empty.</li>
|
---|
4119 | <li>The machine name can contain only characters that are valid
|
---|
4120 | file name characters according to the rules of the file
|
---|
4121 | system used to store VirtualBox configuration.</li>
|
---|
4122 | <li>You cannot have two or more machines with the same name
|
---|
4123 | if they use the same subdirectory for storing the machine
|
---|
4124 | settings files.</li>
|
---|
4125 | <li>You cannot change the name of the machine if it is running,
|
---|
4126 | or if any file in the directory containing the settings file
|
---|
4127 | is being used by another running machine or by any other
|
---|
4128 | process in the host operating system at a time when
|
---|
4129 | <link to="#saveSettings"/> is called.
|
---|
4130 | </li>
|
---|
4131 | </ul>
|
---|
4132 | If any of the above limitations are hit, <link to="#saveSettings"/>
|
---|
4133 | will return an appropriate error message explaining the exact
|
---|
4134 | reason and the changes you made to this machine will not be
|
---|
4135 | saved.
|
---|
4136 | <note>
|
---|
4137 | For "legacy" machines created using the
|
---|
4138 | <link to="IVirtualBox::createLegacyMachine"/> call,
|
---|
4139 | the above naming limitations do not apply because the
|
---|
4140 | machine name does not affect the settings file name.
|
---|
4141 | The settings file name remains the same as it was specified
|
---|
4142 | during machine creation and never changes.
|
---|
4143 | </note>
|
---|
4144 | </desc>
|
---|
4145 | </attribute>
|
---|
4146 |
|
---|
4147 | <attribute name="description" type="wstring">
|
---|
4148 | <desc>
|
---|
4149 | Description of the virtual machine.
|
---|
4150 |
|
---|
4151 | The description attribute can contain any text and is
|
---|
4152 | typically used to describe the hardware and software
|
---|
4153 | configuration of the virtual machine in detail (i.e. network
|
---|
4154 | settings, versions of the installed software and so on).
|
---|
4155 | </desc>
|
---|
4156 | </attribute>
|
---|
4157 |
|
---|
4158 | <attribute name="id" type="uuid" readonly="yes">
|
---|
4159 | <desc>UUID of the virtual machine.</desc>
|
---|
4160 | </attribute>
|
---|
4161 |
|
---|
4162 | <attribute name="OSTypeId" type="wstring">
|
---|
4163 | <desc>
|
---|
4164 | User-defined identifier of the Guest OS type.
|
---|
4165 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
4166 | an IGuestOSType object representing details about the given
|
---|
4167 | Guest OS type.
|
---|
4168 | <note>
|
---|
4169 | This value may differ from the value returned by
|
---|
4170 | <link to="IGuest::OSTypeId"/> if Guest Additions are
|
---|
4171 | installed to the guest OS.
|
---|
4172 | </note>
|
---|
4173 | </desc>
|
---|
4174 | </attribute>
|
---|
4175 |
|
---|
4176 | <attribute name="HardwareVersion" type="wstring">
|
---|
4177 | <desc>Hardware version identifier. Internal use only for now.</desc>
|
---|
4178 | </attribute>
|
---|
4179 |
|
---|
4180 | <attribute name="CPUCount" type="unsigned long">
|
---|
4181 | <desc>Number of virtual CPUs in the VM. In the current version of the product, this is always 1.</desc>
|
---|
4182 | </attribute>
|
---|
4183 |
|
---|
4184 | <attribute name="memorySize" type="unsigned long">
|
---|
4185 | <desc>System memory size in megabytes.</desc>
|
---|
4186 | </attribute>
|
---|
4187 |
|
---|
4188 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
4189 | <desc>Initial memory balloon size in megabytes.</desc>
|
---|
4190 | </attribute>
|
---|
4191 |
|
---|
4192 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
4193 | <desc>Initial interval to update guest statistics in seconds.</desc>
|
---|
4194 | </attribute>
|
---|
4195 |
|
---|
4196 | <attribute name="VRAMSize" type="unsigned long">
|
---|
4197 | <desc>Video memory size in megabytes.</desc>
|
---|
4198 | </attribute>
|
---|
4199 |
|
---|
4200 | <attribute name="accelerate3DEnabled" type="boolean" default="false">
|
---|
4201 | <desc>
|
---|
4202 | This setting determines whether VirtualBox allows guests to make use
|
---|
4203 | of the 3D graphics support available on the host. Currently limited
|
---|
4204 | to OpenGL only. </desc>
|
---|
4205 | </attribute>
|
---|
4206 |
|
---|
4207 | <attribute name="monitorCount" type="unsigned long">
|
---|
4208 | <desc>
|
---|
4209 | Number of virtual monitors.
|
---|
4210 | <note>
|
---|
4211 | Only effective on Windows XP and later guests with
|
---|
4212 | Guest Additions installed.
|
---|
4213 | </note>
|
---|
4214 | </desc>
|
---|
4215 | </attribute>
|
---|
4216 |
|
---|
4217 | <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
|
---|
4218 | <desc>Object containing all BIOS settings.</desc>
|
---|
4219 | </attribute>
|
---|
4220 |
|
---|
4221 | <attribute name="HWVirtExEnabled" type="TSBool">
|
---|
4222 | <desc>
|
---|
4223 | This setting determines whether VirtualBox will try to make use of
|
---|
4224 | the host CPU's hardware virtualization extensions such as Intel VT-x
|
---|
4225 | and AMD-V. Note that in case such extensions are not available,
|
---|
4226 | they will not be used.
|
---|
4227 | </desc>
|
---|
4228 | </attribute>
|
---|
4229 |
|
---|
4230 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" default="false">
|
---|
4231 | <desc>
|
---|
4232 | This setting determines whether VirtualBox will try to make use of
|
---|
4233 | the nested paging extension of Intel VT-x and AMD-V. Note that in case
|
---|
4234 | such extensions are not available, they will not be used.
|
---|
4235 | </desc>
|
---|
4236 | </attribute>
|
---|
4237 |
|
---|
4238 | <attribute name="HWVirtExVPIDEnabled" type="boolean" default="false">
|
---|
4239 | <desc>
|
---|
4240 | This setting determines whether VirtualBox will try to make use of
|
---|
4241 | the VPID extension of Intel VT-x. Note that in case such extensions are
|
---|
4242 | not available, they will not be used.
|
---|
4243 | </desc>
|
---|
4244 | </attribute>
|
---|
4245 |
|
---|
4246 | <attribute name="PAEEnabled" type="boolean" default="false">
|
---|
4247 | <desc>
|
---|
4248 | This setting determines whether VirtualBox will expose the Physical Address
|
---|
4249 | Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
|
---|
4250 | is not available, it will not be reported.
|
---|
4251 | </desc>
|
---|
4252 | </attribute>
|
---|
4253 |
|
---|
4254 | <attribute name="snapshotFolder" type="wstring">
|
---|
4255 | <desc>
|
---|
4256 | Full path to the directory used to store snapshot data
|
---|
4257 | (differencing hard disks and saved state files) of this machine.
|
---|
4258 |
|
---|
4259 | The initial value of this property is
|
---|
4260 | <tt><</tt><link to="#settingsFilePath">
|
---|
4261 | path_to_settings_file</link><tt>>/<</tt>
|
---|
4262 | <link to="#id">machine_uuid</link>
|
---|
4263 | <tt>></tt>.
|
---|
4264 |
|
---|
4265 | Currently, it is an error to try to change this property on
|
---|
4266 | a machine that has snapshots (because this would require to
|
---|
4267 | move possibly large files to a different location).
|
---|
4268 | A separate method will be available for this purpose later.
|
---|
4269 |
|
---|
4270 | <note>
|
---|
4271 | Setting this property to <tt>null</tt> will restore the
|
---|
4272 | initial value.
|
---|
4273 | </note>
|
---|
4274 | <note>
|
---|
4275 | When setting this property, the specified path can be
|
---|
4276 | absolute (full path) or relative to the directory where the
|
---|
4277 | <link to="#settingsFilePath">machine settings file</link>
|
---|
4278 | is located. When reading this property, a full path is
|
---|
4279 | always returned.
|
---|
4280 | </note>
|
---|
4281 | <note>
|
---|
4282 | The specified path may not exist, it will be created
|
---|
4283 | when necessary.
|
---|
4284 | </note>
|
---|
4285 | </desc>
|
---|
4286 | </attribute>
|
---|
4287 |
|
---|
4288 | <attribute name="VRDPServer" type="IVRDPServer" readonly="yes">
|
---|
4289 | <desc>VRDP server object.</desc>
|
---|
4290 | </attribute>
|
---|
4291 |
|
---|
4292 | <attribute name="hardDiskAttachments" type="IHardDiskAttachment" readonly="yes" safearray="yes">
|
---|
4293 | <desc>Array of hard disks attached to this machine.</desc>
|
---|
4294 | </attribute>
|
---|
4295 |
|
---|
4296 | <attribute name="DVDDrive" type="IDVDDrive" readonly="yes">
|
---|
4297 | <desc>Associated DVD drive object.</desc>
|
---|
4298 | </attribute>
|
---|
4299 |
|
---|
4300 | <attribute name="floppyDrive" type="IFloppyDrive" readonly="yes">
|
---|
4301 | <desc>Associated floppy drive object.</desc>
|
---|
4302 | </attribute>
|
---|
4303 |
|
---|
4304 | <attribute name="USBController" type="IUSBController" readonly="yes">
|
---|
4305 | <desc>
|
---|
4306 | Associated USB controller object.
|
---|
4307 |
|
---|
4308 | <note>
|
---|
4309 | If USB functionality is not available in the given edition of
|
---|
4310 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
4311 | </note>
|
---|
4312 | </desc>
|
---|
4313 | </attribute>
|
---|
4314 |
|
---|
4315 | <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
|
---|
4316 | <desc>Associated audio adapter, always present.</desc>
|
---|
4317 | </attribute>
|
---|
4318 |
|
---|
4319 | <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
|
---|
4320 | <desc>Array of storage controllers attached to this machine.</desc>
|
---|
4321 | </attribute>
|
---|
4322 |
|
---|
4323 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
4324 | <desc>
|
---|
4325 | Full name of the file containing machine settings data.
|
---|
4326 | </desc>
|
---|
4327 | </attribute>
|
---|
4328 |
|
---|
4329 | <attribute name="settingsFileVersion" type="wstring" readonly="yes">
|
---|
4330 | <desc>
|
---|
4331 | Current version of the format of the settings file of this machine
|
---|
4332 | (<link to="IMachine::settingsFilePath"/>).
|
---|
4333 |
|
---|
4334 | The version string has the following format:
|
---|
4335 | <pre>
|
---|
4336 | x.y-platform
|
---|
4337 | </pre>
|
---|
4338 | where <tt>x</tt> and <tt>y</tt> are the major and the minor format
|
---|
4339 | versions, and <tt>platform</tt> is the platform identifier.
|
---|
4340 |
|
---|
4341 | The current version usually matches the value of the
|
---|
4342 | <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
|
---|
4343 | settings file was created by an older version of VirtualBox and there
|
---|
4344 | was a change of the settings file format since then.
|
---|
4345 |
|
---|
4346 | Note that VirtualBox automatically converts settings files from older
|
---|
4347 | versions to the most recent version when reading them (usually at
|
---|
4348 | VirtualBox startup) but it doesn't save the changes back until
|
---|
4349 | you call a method that implicitly saves settings (such as
|
---|
4350 | <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
|
---|
4351 | explicitly. Therefore, if the value of this attribute differs from the
|
---|
4352 | value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
|
---|
4353 | means that the settings file was converted but the result of the
|
---|
4354 | conversion is not yet saved to disk.
|
---|
4355 |
|
---|
4356 | The above feature may be used by interactive front-ends to inform users
|
---|
4357 | about the settings file format change and offer them to explicitly save
|
---|
4358 | all converted settings files (the global and VM-specific ones),
|
---|
4359 | optionally create backup copies of the old settings files before saving,
|
---|
4360 | etc.
|
---|
4361 |
|
---|
4362 | <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
|
---|
4363 | </desc>
|
---|
4364 | </attribute>
|
---|
4365 |
|
---|
4366 | <attribute name="settingsModified" type="boolean" readonly="yes">
|
---|
4367 | <desc>
|
---|
4368 | Whether the settings of this machine have been modified
|
---|
4369 | (but neither yet saved nor discarded).
|
---|
4370 | <note>
|
---|
4371 | Reading this property is only valid on instances returned
|
---|
4372 | by <link to="ISession::machine"/> and on new machines
|
---|
4373 | created by <link to="IVirtualBox::createMachine"/> or opened
|
---|
4374 | by <link to="IVirtualBox::openMachine"/> but not
|
---|
4375 | yet registered, or on unregistered machines after calling
|
---|
4376 | <link to="IVirtualBox::unregisterMachine"/>. For all other
|
---|
4377 | cases, the settings can never be modified.
|
---|
4378 | </note>
|
---|
4379 | <note>
|
---|
4380 | For newly created unregistered machines, the value of this
|
---|
4381 | property is always TRUE until <link to="#saveSettings"/>
|
---|
4382 | is called (no matter if any machine settings have been
|
---|
4383 | changed after the creation or not). For opened machines
|
---|
4384 | the value is set to FALSE (and then follows to normal rules).
|
---|
4385 | </note>
|
---|
4386 | </desc>
|
---|
4387 | </attribute>
|
---|
4388 |
|
---|
4389 | <attribute name="sessionState" type="SessionState" readonly="yes">
|
---|
4390 | <desc>Current session state for this machine.</desc>
|
---|
4391 | </attribute>
|
---|
4392 |
|
---|
4393 | <attribute name="sessionType" type="wstring" readonly="yes">
|
---|
4394 | <desc>
|
---|
4395 | Type of the session. If <link to="#sessionState"/> is
|
---|
4396 | SessionSpawning or SessionOpen, this attribute contains the
|
---|
4397 | same value as passed to the
|
---|
4398 | <link to="IVirtualBox::openRemoteSession"/> method in the
|
---|
4399 | @a type parameter. If the session was opened directly using
|
---|
4400 | <link to="IVirtualBox::openSession"/>, or if
|
---|
4401 | <link to="#sessionState"/> is SessionClosed, the value of this
|
---|
4402 | attribute is @c null.
|
---|
4403 | </desc>
|
---|
4404 | </attribute>
|
---|
4405 |
|
---|
4406 | <attribute name="sessionPid" type="unsigned long" readonly="yes">
|
---|
4407 | <desc>
|
---|
4408 | Identifier of the session process. This attribute contains the
|
---|
4409 | platform-dependent identifier of the process that has opened a
|
---|
4410 | direct session for this machine using the
|
---|
4411 | <link to="IVirtualBox::openSession"/> call. The returned value
|
---|
4412 | is only valid if <link to="#sessionState"/> is SessionOpen or
|
---|
4413 | SessionClosing (i.e. a session is currently open or being
|
---|
4414 | closed) by the time this property is read.
|
---|
4415 | </desc>
|
---|
4416 | </attribute>
|
---|
4417 |
|
---|
4418 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
4419 | <desc>Current execution state of this machine.</desc>
|
---|
4420 | </attribute>
|
---|
4421 |
|
---|
4422 | <attribute name="lastStateChange" type="long long" readonly="yes">
|
---|
4423 | <desc>
|
---|
4424 | Time stamp of the last execution state change,
|
---|
4425 | in milliseconds since 1970-01-01 UTC.
|
---|
4426 | </desc>
|
---|
4427 | </attribute>
|
---|
4428 |
|
---|
4429 | <attribute name="stateFilePath" type="wstring" readonly="yes">
|
---|
4430 | <desc>
|
---|
4431 | Full path to the file that stores the execution state of
|
---|
4432 | the machine when it is in the <link to="MachineState_Saved"/> state.
|
---|
4433 | <note>
|
---|
4434 | When the machine is not in the Saved state, this attribute
|
---|
4435 | <tt>null</tt>.
|
---|
4436 | </note>
|
---|
4437 | </desc>
|
---|
4438 | </attribute>
|
---|
4439 |
|
---|
4440 | <attribute name="logFolder" type="wstring" readonly="yes">
|
---|
4441 | <desc>
|
---|
4442 | Full path to the folder that stores a set of rotated log files
|
---|
4443 | recorded during machine execution. The most recent log file is
|
---|
4444 | named <tt>VBox.log</tt>, the previous log file is
|
---|
4445 | named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
|
---|
4446 | in the current version).
|
---|
4447 | </desc>
|
---|
4448 | </attribute>
|
---|
4449 |
|
---|
4450 | <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
|
---|
4451 | <desc>
|
---|
4452 | Current snapshot of this machine.
|
---|
4453 | <note>
|
---|
4454 | A <tt>null</tt> object is returned if the machine doesn't
|
---|
4455 | have snapshots.
|
---|
4456 | </note>
|
---|
4457 | <see><link to="ISnapshot"/></see>
|
---|
4458 | </desc>
|
---|
4459 | </attribute>
|
---|
4460 |
|
---|
4461 | <attribute name="snapshotCount" type="unsigned long" readonly="yes">
|
---|
4462 | <desc>
|
---|
4463 | Number of snapshots taken on this machine. Zero means the
|
---|
4464 | machine doesn't have any snapshots.
|
---|
4465 | </desc>
|
---|
4466 | </attribute>
|
---|
4467 |
|
---|
4468 | <attribute name="currentStateModified" type="boolean" readonly="yes">
|
---|
4469 | <desc>
|
---|
4470 | Returns <tt>true</tt> if the current state of the machine is not
|
---|
4471 | identical to the state stored in the current snapshot.
|
---|
4472 |
|
---|
4473 | The current state is identical to the current snapshot right
|
---|
4474 | after one of the following calls are made:
|
---|
4475 | <ul>
|
---|
4476 | <li><link to="IConsole::discardCurrentState"/> or
|
---|
4477 | <link to="IConsole::discardCurrentSnapshotAndState"/>
|
---|
4478 | </li>
|
---|
4479 | <li><link to="IConsole::takeSnapshot"/> (issued on a
|
---|
4480 | powered off or saved machine, for which
|
---|
4481 | <link to="#settingsModified"/> returns <tt>false</tt>)
|
---|
4482 | </li>
|
---|
4483 | <li><link to="IMachine::setCurrentSnapshot"/>
|
---|
4484 | </li>
|
---|
4485 | </ul>
|
---|
4486 |
|
---|
4487 | The current state remains identical until one of the following
|
---|
4488 | happens:
|
---|
4489 | <ul>
|
---|
4490 | <li>settings of the machine are changed</li>
|
---|
4491 | <li>the saved state is discarded</li>
|
---|
4492 | <li>the current snapshot is discarded</li>
|
---|
4493 | <li>an attempt to execute the machine is made</li>
|
---|
4494 | </ul>
|
---|
4495 |
|
---|
4496 | <note>
|
---|
4497 | For machines that don't have snapshots, this property is
|
---|
4498 | always <tt>false</tt>.
|
---|
4499 | </note>
|
---|
4500 | </desc>
|
---|
4501 | </attribute>
|
---|
4502 |
|
---|
4503 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
4504 | <desc>
|
---|
4505 | Collection of shared folders for this machine (permanent shared
|
---|
4506 | folders). These folders are shared automatically at machine startup
|
---|
4507 | and available only to the guest OS installed within this machine.
|
---|
4508 |
|
---|
4509 | New shared folders are added to the collection using
|
---|
4510 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
4511 | removed using <link to="#removeSharedFolder"/>.
|
---|
4512 | </desc>
|
---|
4513 | </attribute>
|
---|
4514 |
|
---|
4515 | <attribute name="clipboardMode" type="ClipboardMode">
|
---|
4516 | <desc>
|
---|
4517 | Synchronization mode between the host OS clipboard
|
---|
4518 | and the guest OS clipboard.
|
---|
4519 | </desc>
|
---|
4520 | </attribute>
|
---|
4521 |
|
---|
4522 | <attribute name="guestPropertyNotificationPatterns" type="wstring">
|
---|
4523 | <desc>
|
---|
4524 | A comma-separated list of simple glob patterns. Changes to guest
|
---|
4525 | properties whose name matches one of the patterns will generate an
|
---|
4526 | <link to="IVirtualBoxCallback::onGuestPropertyChange"/> signal.
|
---|
4527 | </desc>
|
---|
4528 | </attribute>
|
---|
4529 |
|
---|
4530 | <method name="setBootOrder">
|
---|
4531 | <desc>
|
---|
4532 | Puts the given device to the specified position in
|
---|
4533 | the boot order.
|
---|
4534 |
|
---|
4535 | To indicate that no device is associated with the given position,
|
---|
4536 | <link to="DeviceType_Null"/> should be used.
|
---|
4537 |
|
---|
4538 | @todo setHardDiskBootOrder(), setNetworkBootOrder()
|
---|
4539 |
|
---|
4540 | <result name="E_INVALIDARG">
|
---|
4541 | Boot @a position out of range.
|
---|
4542 | </result>
|
---|
4543 | <result name="E_NOTIMPL">
|
---|
4544 | Booting from USB @a device currently not supported.
|
---|
4545 | </result>
|
---|
4546 |
|
---|
4547 | </desc>
|
---|
4548 | <param name="position" type="unsigned long" dir="in">
|
---|
4549 | <desc>
|
---|
4550 | Position in the boot order (<tt>1</tt> to the total number of
|
---|
4551 | devices the machine can boot from, as returned by
|
---|
4552 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4553 | </desc>
|
---|
4554 | </param>
|
---|
4555 | <param name="device" type="DeviceType" dir="in">
|
---|
4556 | <desc>
|
---|
4557 | The type of the device used to boot at the given position.
|
---|
4558 | </desc>
|
---|
4559 | </param>
|
---|
4560 | </method>
|
---|
4561 |
|
---|
4562 | <method name="getBootOrder" const="yes">
|
---|
4563 | <desc>
|
---|
4564 | Returns the device type that occupies the specified
|
---|
4565 | position in the boot order.
|
---|
4566 |
|
---|
4567 | @todo [remove?]
|
---|
4568 | If the machine can have more than one device of the returned type
|
---|
4569 | (such as hard disks), then a separate method should be used to
|
---|
4570 | retrieve the individual device that occupies the given position.
|
---|
4571 |
|
---|
4572 | If here are no devices at the given position, then
|
---|
4573 | <link to="DeviceType_Null"/> is returned.
|
---|
4574 |
|
---|
4575 | @todo getHardDiskBootOrder(), getNetworkBootOrder()
|
---|
4576 |
|
---|
4577 | <result name="E_INVALIDARG">
|
---|
4578 | Boot @a position out of range.
|
---|
4579 | </result>
|
---|
4580 |
|
---|
4581 | </desc>
|
---|
4582 | <param name="position" type="unsigned long" dir="in">
|
---|
4583 | <desc>
|
---|
4584 | Position in the boot order (<tt>1</tt> to the total number of
|
---|
4585 | devices the machine can boot from, as returned by
|
---|
4586 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4587 | </desc>
|
---|
4588 | </param>
|
---|
4589 | <param name="device" type="DeviceType" dir="return">
|
---|
4590 | <desc>
|
---|
4591 | Device at the given position.
|
---|
4592 | </desc>
|
---|
4593 | </param>
|
---|
4594 | </method>
|
---|
4595 |
|
---|
4596 | <method name="attachHardDisk">
|
---|
4597 | <desc>
|
---|
4598 | Attaches a virtual hard disk (<link to="IHardDisk" />, identified
|
---|
4599 | by the given UUID @a id) to the given hard disk controller
|
---|
4600 | (<link to="IStorageController" />, identified by @a name),
|
---|
4601 | at the indicated port and device.
|
---|
4602 |
|
---|
4603 | For the IDE bus, the @a controllerPort parameter can be either
|
---|
4604 | @c 0 or @c 1, to specify the primary or secondary IDE controller,
|
---|
4605 | respectively. For the primary controller of the IDE bus,
|
---|
4606 | @a device can be either @c 0 or @c 1, to specify the master or the
|
---|
4607 | slave device, respectively. For the secondary IDE controller, the
|
---|
4608 | device number must be @c 1 because VirtualBox reserves the
|
---|
4609 | secondary master for the CD-ROM drive.
|
---|
4610 |
|
---|
4611 | For an SATA controller, @a controllerPort must be a number ranging
|
---|
4612 | from @c 0 to @c 29. For a SCSI controller, @a controllerPort must
|
---|
4613 | be a number ranging from @c 0 to @c 15.
|
---|
4614 |
|
---|
4615 | For both SCSI and SATA, the @a device parameter is unused and must
|
---|
4616 | be @c 0.
|
---|
4617 |
|
---|
4618 | The specified device slot must not have another disk attached to it, or
|
---|
4619 | this method will fail.
|
---|
4620 |
|
---|
4621 | See <link to="IHardDisk"/> for more detailed information about
|
---|
4622 | attaching hard disks.
|
---|
4623 |
|
---|
4624 | <note>
|
---|
4625 | You cannot attach a hard disk to a running machine. Also, you cannot
|
---|
4626 | attach a hard disk to a newly created machine until this machine's
|
---|
4627 | settings are saved to disk using <link to="#saveSettings"/>.
|
---|
4628 | </note>
|
---|
4629 | <note>
|
---|
4630 | If the hard disk is being attached indirectly, a new differencing hard
|
---|
4631 | disk will implicitly be created for it and attached instead. If the
|
---|
4632 | changes made to the machine settings (including this indirect
|
---|
4633 | attachment) are later cancelled using <link to="#discardSettings"/>,
|
---|
4634 | this implicitly created differencing hard disk will implicitly
|
---|
4635 | be deleted.
|
---|
4636 | </note>
|
---|
4637 |
|
---|
4638 | <result name="E_INVALIDARG">
|
---|
4639 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4640 | </result>
|
---|
4641 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4642 | Attempt to attach hard disk to an unregistered virtual machine.
|
---|
4643 | </result>
|
---|
4644 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4645 | Invalid machine state.
|
---|
4646 | </result>
|
---|
4647 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4648 | Hard disk already attached to this or another virtual machine.
|
---|
4649 | </result>
|
---|
4650 |
|
---|
4651 | </desc>
|
---|
4652 | <param name="id" type="uuid" dir="in">
|
---|
4653 | <desc>UUID of the hard disk to attach.</desc>
|
---|
4654 | </param>
|
---|
4655 | <param name="name" type="wstring" dir="in">
|
---|
4656 | <desc>Name of the storage controller to attach the hard disk to.</desc>
|
---|
4657 | </param>
|
---|
4658 | <param name="controllerPort" type="long" dir="in">
|
---|
4659 | <desc>Port to attach the hard disk to.</desc>
|
---|
4660 | </param>
|
---|
4661 | <param name="device" type="long" dir="in">
|
---|
4662 | <desc>
|
---|
4663 | Device slot in the given port to attach the hard disk to.
|
---|
4664 | </desc>
|
---|
4665 | </param>
|
---|
4666 | </method>
|
---|
4667 |
|
---|
4668 | <method name="getHardDisk" const="yes">
|
---|
4669 | <desc>
|
---|
4670 | Returns the virtual hard disk attached to a device slot of the specified
|
---|
4671 | bus.
|
---|
4672 |
|
---|
4673 | Note that if the hard disk was indirectly attached by
|
---|
4674 | <link to="#attachHardDisk"/> to the given device slot then this
|
---|
4675 | method will return not the same object as passed to the
|
---|
4676 | <link to="#attachHardDisk"/> call. See <link to="IHardDisk"/> for
|
---|
4677 | more detailed information about attaching hard disks.
|
---|
4678 |
|
---|
4679 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4680 | No hard disk attached to given slot/bus.
|
---|
4681 | </result>
|
---|
4682 |
|
---|
4683 | </desc>
|
---|
4684 | <param name="name" type="wstring" dir="in">
|
---|
4685 | <desc>Name of the storage controller the hard disk is attached to.</desc>
|
---|
4686 | </param>
|
---|
4687 | <param name="controllerPort" type="long" dir="in">
|
---|
4688 | <desc>Port to query.</desc>
|
---|
4689 | </param>
|
---|
4690 | <param name="device" type="long" dir="in">
|
---|
4691 | <desc>Device slot in the given port to query.</desc>
|
---|
4692 | </param>
|
---|
4693 | <param name="hardDisk" type="IHardDisk" dir="return">
|
---|
4694 | <desc>Attached hard disk object.</desc>
|
---|
4695 | </param>
|
---|
4696 | </method>
|
---|
4697 |
|
---|
4698 | <method name="detachHardDisk">
|
---|
4699 | <desc>
|
---|
4700 | Detaches the virtual hard disk attached to a device slot of the
|
---|
4701 | specified bus.
|
---|
4702 |
|
---|
4703 | Detaching the hard disk from the virtual machine is deferred. This means
|
---|
4704 | that the hard disk remains associated with the machine when this method
|
---|
4705 | returns and gets actually de-associated only after a successful
|
---|
4706 | <link to="#saveSettings"/> call. See <link to="IHardDisk"/>
|
---|
4707 | for more detailed information about attaching hard disks.
|
---|
4708 |
|
---|
4709 | <note>
|
---|
4710 | You cannot detach the hard disk from a running machine.
|
---|
4711 | </note>
|
---|
4712 | <note>
|
---|
4713 | Detaching differencing hard disks implicitly created by <link
|
---|
4714 | to="#attachHardDisk"/> for the indirect attachment using this
|
---|
4715 | method will <b>not</b> implicitly delete them. The
|
---|
4716 | <link to="IHardDisk::deleteStorage"/> operation should be
|
---|
4717 | explicitly performed by the caller after the hard disk is successfully
|
---|
4718 | detached and the settings are saved with
|
---|
4719 | <link to="#saveSettings"/>, if it is the desired action.
|
---|
4720 | </note>
|
---|
4721 |
|
---|
4722 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4723 | Attempt to detach hard disk from a running virtual machine.
|
---|
4724 | </result>
|
---|
4725 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4726 | No hard disk attached to given slot/bus.
|
---|
4727 | </result>
|
---|
4728 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
4729 | Hard disk format does not support storage deletion.
|
---|
4730 | </result>
|
---|
4731 |
|
---|
4732 | </desc>
|
---|
4733 | <param name="name" type="wstring" dir="in">
|
---|
4734 | <desc>name of the storage controller to detach the hard disk from.</desc>
|
---|
4735 | </param>
|
---|
4736 | <param name="controllerPort" type="long" dir="in">
|
---|
4737 | <desc>Port number to detach the hard disk from.</desc>
|
---|
4738 | </param>
|
---|
4739 | <param name="device" type="long" dir="in">
|
---|
4740 | <desc>Device slot number to detach the hard disk from.</desc>
|
---|
4741 | </param>
|
---|
4742 | </method>
|
---|
4743 |
|
---|
4744 | <method name="getHardDiskAttachmentsOfController" const="yes">
|
---|
4745 | <desc>
|
---|
4746 | Returns an array of hard disk attachments which are attached to the
|
---|
4747 | the controller with the given name.
|
---|
4748 |
|
---|
4749 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4750 | A storage controller with given name doesn't exist.
|
---|
4751 | </result>
|
---|
4752 | </desc>
|
---|
4753 | <param name="name" type="wstring" dir="in"/>
|
---|
4754 | <param name="hardDiskAttachments" type="IHardDiskAttachment" safearray="yes" dir="return"/>
|
---|
4755 | </method>
|
---|
4756 |
|
---|
4757 | <method name="getNetworkAdapter" const="yes">
|
---|
4758 | <desc>
|
---|
4759 | Returns the network adapter associated with the given slot.
|
---|
4760 | Slots are numbered sequentially, starting with zero. The total
|
---|
4761 | number of adapters per machine is defined by the
|
---|
4762 | <link to="ISystemProperties::networkAdapterCount"/> property,
|
---|
4763 | so the maximum slot number is one less than that property's value.
|
---|
4764 |
|
---|
4765 | <result name="E_INVALIDARG">
|
---|
4766 | Invalid @a slot number.
|
---|
4767 | </result>
|
---|
4768 |
|
---|
4769 | </desc>
|
---|
4770 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4771 | <param name="adapter" type="INetworkAdapter" dir="return"/>
|
---|
4772 | </method>
|
---|
4773 |
|
---|
4774 | <method name="addStorageController">
|
---|
4775 | <desc>
|
---|
4776 | Adds a new storage controller (SCSI or SATA controller) to the
|
---|
4777 | machine and returns it as an instance of
|
---|
4778 | <link to="IStorageController" />.
|
---|
4779 |
|
---|
4780 | @a name identifies the controller for subsequent calls such as
|
---|
4781 | <link to="#getStorageControllerByName" /> or
|
---|
4782 | <link to="#removeStorageController" /> or
|
---|
4783 | <link to="#attachHardDisk" />.
|
---|
4784 |
|
---|
4785 | After the controller has been added, you can set its exact
|
---|
4786 | type by setting the <link to="IStorageController::controllerType" />.
|
---|
4787 |
|
---|
4788 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4789 | A storage controller with given name exists already.
|
---|
4790 | </result>
|
---|
4791 | <result name="E_INVALIDARG">
|
---|
4792 | Invalid @a controllerType.
|
---|
4793 | </result>
|
---|
4794 | </desc>
|
---|
4795 | <param name="name" type="wstring" dir="in"/>
|
---|
4796 | <param name="connectionType" type="StorageBus" dir="in"/>
|
---|
4797 | <param name="controller" type="IStorageController" dir="return"/>
|
---|
4798 | </method>
|
---|
4799 |
|
---|
4800 | <method name="getStorageControllerByName" const="yes">
|
---|
4801 | <desc>
|
---|
4802 | Returns a storage controller with the given name.
|
---|
4803 |
|
---|
4804 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4805 | A storage controller with given name doesn't exist.
|
---|
4806 | </result>
|
---|
4807 | </desc>
|
---|
4808 | <param name="name" type="wstring" dir="in"/>
|
---|
4809 | <param name="storageController" type="IStorageController" dir="return"/>
|
---|
4810 | </method>
|
---|
4811 |
|
---|
4812 | <method name="removeStorageController">
|
---|
4813 | <desc>
|
---|
4814 | Removes a storage controller from the machine.
|
---|
4815 |
|
---|
4816 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4817 | A storage controller with given name doesn't exist.
|
---|
4818 | </result>
|
---|
4819 | </desc>
|
---|
4820 | <param name="name" type="wstring" dir="in"/>
|
---|
4821 | </method>
|
---|
4822 |
|
---|
4823 | <method name="getSerialPort" const="yes">
|
---|
4824 | <desc>
|
---|
4825 | Returns the serial port associated with the given slot.
|
---|
4826 | Slots are numbered sequentially, starting with zero. The total
|
---|
4827 | number of serial ports per machine is defined by the
|
---|
4828 | <link to="ISystemProperties::serialPortCount"/> property,
|
---|
4829 | so the maximum slot number is one less than that property's value.
|
---|
4830 |
|
---|
4831 | <result name="E_INVALIDARG">
|
---|
4832 | Invalid @a slot number.
|
---|
4833 | </result>
|
---|
4834 |
|
---|
4835 | </desc>
|
---|
4836 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4837 | <param name="port" type="ISerialPort" dir="return"/>
|
---|
4838 | </method>
|
---|
4839 |
|
---|
4840 | <method name="getParallelPort" const="yes">
|
---|
4841 | <desc>
|
---|
4842 | Returns the parallel port associated with the given slot.
|
---|
4843 | Slots are numbered sequentially, starting with zero. The total
|
---|
4844 | number of parallel ports per machine is defined by the
|
---|
4845 | <link to="ISystemProperties::parallelPortCount"/> property,
|
---|
4846 | so the maximum slot number is one less than that property's value.
|
---|
4847 |
|
---|
4848 | <result name="E_INVALIDARG">
|
---|
4849 | Invalid @a slot number.
|
---|
4850 | </result>
|
---|
4851 |
|
---|
4852 | </desc>
|
---|
4853 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4854 | <param name="port" type="IParallelPort" dir="return"/>
|
---|
4855 | </method>
|
---|
4856 |
|
---|
4857 | <method name="getNextExtraDataKey">
|
---|
4858 | <desc>
|
---|
4859 | Returns the machine-specific extra data key name following the
|
---|
4860 | supplied key.
|
---|
4861 |
|
---|
4862 | An error is returned if the supplied @a key does not exist. @c NULL is
|
---|
4863 | returned in @a nextKey if the supplied key is the last key. When
|
---|
4864 | supplying @c NULL for the @a key, the first key item is returned in
|
---|
4865 | @a nextKey (if there is any). @a nextValue is an optional parameter and
|
---|
4866 | if supplied, the next key's value is returned in it.
|
---|
4867 |
|
---|
4868 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4869 | Extra data @a key not found.
|
---|
4870 | </result>
|
---|
4871 |
|
---|
4872 | </desc>
|
---|
4873 | <param name="key" type="wstring" dir="in">
|
---|
4874 | <desc>Name of the data key to follow.</desc>
|
---|
4875 | </param>
|
---|
4876 | <param name="nextKey" type="wstring" dir="out">
|
---|
4877 | <desc>Name of the next data key.</desc>
|
---|
4878 | </param>
|
---|
4879 | <param name="nextValue" type="wstring" dir="out">
|
---|
4880 | <desc>Value of the next data key.</desc>
|
---|
4881 | </param>
|
---|
4882 | </method>
|
---|
4883 |
|
---|
4884 | <method name="getExtraData">
|
---|
4885 | <desc>
|
---|
4886 | Returns associated machine-specific extra data.
|
---|
4887 |
|
---|
4888 | If the requested data @a key does not exist, this function will
|
---|
4889 | succeed and return @c NULL in the @a value argument.
|
---|
4890 |
|
---|
4891 | <result name="VBOX_E_FILE_ERROR">
|
---|
4892 | Settings file not accessible.
|
---|
4893 | </result>
|
---|
4894 | <result name="VBOX_E_XML_ERROR">
|
---|
4895 | Could not parse the settings file.
|
---|
4896 | </result>
|
---|
4897 |
|
---|
4898 | </desc>
|
---|
4899 | <param name="key" type="wstring" dir="in">
|
---|
4900 | <desc>Name of the data key to get.</desc>
|
---|
4901 | </param>
|
---|
4902 | <param name="value" type="wstring" dir="return">
|
---|
4903 | <desc>Value of the requested data key.</desc>
|
---|
4904 | </param>
|
---|
4905 | </method>
|
---|
4906 |
|
---|
4907 | <method name="setExtraData">
|
---|
4908 | <desc>
|
---|
4909 | Sets associated machine-specific extra data.
|
---|
4910 |
|
---|
4911 | If you pass @c NULL as a key @a value, the given @a key will be
|
---|
4912 | deleted.
|
---|
4913 |
|
---|
4914 | <note>
|
---|
4915 | Before performing the actual data change, this method will ask all
|
---|
4916 | registered callbacks using the
|
---|
4917 | <link to="IVirtualBoxCallback::onExtraDataCanChange"/>
|
---|
4918 | notification for a permission. If one of the callbacks refuses the
|
---|
4919 | new value, the change will not be performed.
|
---|
4920 | </note>
|
---|
4921 | <note>
|
---|
4922 | On success, the
|
---|
4923 | <link to="IVirtualBoxCallback::onExtraDataChange"/> notification
|
---|
4924 | is called to inform all registered callbacks about a successful data
|
---|
4925 | change.
|
---|
4926 | </note>
|
---|
4927 | <note>
|
---|
4928 | This method can be called outside the machine session and therefore
|
---|
4929 | it's a caller's responsibility to handle possible race conditions
|
---|
4930 | when several clients change the same key at the same time.
|
---|
4931 | </note>
|
---|
4932 |
|
---|
4933 | <result name="VBOX_E_FILE_ERROR">
|
---|
4934 | Settings file not accessible.
|
---|
4935 | </result>
|
---|
4936 | <result name="VBOX_E_XML_ERROR">
|
---|
4937 | Could not parse the settings file.
|
---|
4938 | </result>
|
---|
4939 |
|
---|
4940 | </desc>
|
---|
4941 | <param name="key" type="wstring" dir="in">
|
---|
4942 | <desc>Name of the data key to set.</desc>
|
---|
4943 | </param>
|
---|
4944 | <param name="value" type="wstring" dir="in">
|
---|
4945 | <desc>Value to assign to the key.</desc>
|
---|
4946 | </param>
|
---|
4947 | </method>
|
---|
4948 |
|
---|
4949 | <method name="saveSettings">
|
---|
4950 | <desc>
|
---|
4951 | Saves any changes to machine settings made since the session
|
---|
4952 | has been opened or a new machine has been created, or since the
|
---|
4953 | last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
|
---|
4954 | For registered machines, new settings become visible to all
|
---|
4955 | other VirtualBox clients after successful invocation of this
|
---|
4956 | method.
|
---|
4957 | <note>
|
---|
4958 | The method sends <link to="IVirtualBoxCallback::onMachineDataChange"/>
|
---|
4959 | notification event after the configuration has been successfully
|
---|
4960 | saved (only for registered machines).
|
---|
4961 | </note>
|
---|
4962 | <note>
|
---|
4963 | Calling this method is only valid on instances returned
|
---|
4964 | by <link to="ISession::machine"/> and on new machines
|
---|
4965 | created by <link to="IVirtualBox::createMachine"/> but not
|
---|
4966 | yet registered, or on unregistered machines after calling
|
---|
4967 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
4968 | </note>
|
---|
4969 |
|
---|
4970 | <result name="VBOX_E_FILE_ERROR">
|
---|
4971 | Settings file not accessible.
|
---|
4972 | </result>
|
---|
4973 | <result name="VBOX_E_XML_ERROR">
|
---|
4974 | Could not parse the settings file.
|
---|
4975 | </result>
|
---|
4976 | <result name="E_ACCESSDENIED">
|
---|
4977 | Modification request refused.
|
---|
4978 | </result>
|
---|
4979 |
|
---|
4980 | </desc>
|
---|
4981 | </method>
|
---|
4982 |
|
---|
4983 | <method name="saveSettingsWithBackup">
|
---|
4984 | <desc>
|
---|
4985 | Creates a backup copy of the machine settings file (<link
|
---|
4986 | to="IMachine::settingsFilePath"/>) in case of auto-conversion, and then calls
|
---|
4987 | <link to="IMachine::saveSettings"/>.
|
---|
4988 |
|
---|
4989 | Note that the backup copy is created <b>only</b> if the settings file
|
---|
4990 | auto-conversion took place (see <link to="#settingsFileVersion"/> for
|
---|
4991 | details). Otherwise, this call is fully equivalent to
|
---|
4992 | <link to="IMachine::saveSettings"/> and no backup copying is done.
|
---|
4993 |
|
---|
4994 | The backup copy is created in the same directory where the original
|
---|
4995 | settings file is located. It is given the following file name:
|
---|
4996 | <pre>
|
---|
4997 | original.xml.x.y-platform.bak
|
---|
4998 | </pre>
|
---|
4999 | where <tt>original.xml</tt> is the original settings file name
|
---|
5000 | (excluding path), and <tt>x.y-platform</tt> is the version of the old
|
---|
5001 | format of the settings file (before auto-conversion).
|
---|
5002 |
|
---|
5003 | If the given backup file already exists, this method will try to add the
|
---|
5004 | <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from
|
---|
5005 | 0 to 9) and copy it again until it succeeds. If all suffixes are
|
---|
5006 | occupied, or if any other copy error occurs, this method will return a
|
---|
5007 | failure.
|
---|
5008 |
|
---|
5009 | If the copy operation succeeds, the @a bakFileName return argument will
|
---|
5010 | receive a full path to the created backup file (for informational
|
---|
5011 | purposes). Note that this will happen even if the subsequent
|
---|
5012 | <link to="#saveSettings"/> call performed by this method after the
|
---|
5013 | copy operation, fails.
|
---|
5014 |
|
---|
5015 | <note>
|
---|
5016 | The VirtualBox API never calls this method. It is intended purely for
|
---|
5017 | the purposes of creating backup copies of the settings files by
|
---|
5018 | front-ends before saving the results of the automatically performed
|
---|
5019 | settings conversion to disk.
|
---|
5020 | </note>
|
---|
5021 |
|
---|
5022 | <see>settingsFileVersion</see>
|
---|
5023 |
|
---|
5024 | <result name="VBOX_E_FILE_ERROR">
|
---|
5025 | Settings file not accessible.
|
---|
5026 | </result>
|
---|
5027 | <result name="VBOX_E_XML_ERROR">
|
---|
5028 | Could not parse the settings file.
|
---|
5029 | </result>
|
---|
5030 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5031 | Virtual machine is not mutable.
|
---|
5032 | </result>
|
---|
5033 | <result name="E_ACCESSDENIED">
|
---|
5034 | Modification request refused.
|
---|
5035 | </result>
|
---|
5036 |
|
---|
5037 | </desc>
|
---|
5038 | <param name="bakFileName" type="wstring" dir="return">
|
---|
5039 | <desc>Full path to the created backup copy.</desc>
|
---|
5040 | </param>
|
---|
5041 | </method>
|
---|
5042 |
|
---|
5043 | <method name="discardSettings">
|
---|
5044 | <desc>
|
---|
5045 | Discards any changes to the machine settings made since the session
|
---|
5046 | has been opened or since the last call to <link to="#saveSettings"/>
|
---|
5047 | or <link to="#discardSettings"/>.
|
---|
5048 | <note>
|
---|
5049 | Calling this method is only valid on instances returned
|
---|
5050 | by <link to="ISession::machine"/> and on new machines
|
---|
5051 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
5052 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
5053 | yet registered, or on unregistered machines after calling
|
---|
5054 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
5055 | </note>
|
---|
5056 |
|
---|
5057 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5058 | Virtual machine is not mutable.
|
---|
5059 | </result>
|
---|
5060 |
|
---|
5061 | </desc>
|
---|
5062 | </method>
|
---|
5063 |
|
---|
5064 | <method name="deleteSettings">
|
---|
5065 | <desc>
|
---|
5066 | Deletes the settings file of this machine from disk.
|
---|
5067 | The machine must not be registered in order for this operation
|
---|
5068 | to succeed.
|
---|
5069 | <note>
|
---|
5070 | <link to="#settingsModified"/> will return TRUE after this
|
---|
5071 | method successfully returns.
|
---|
5072 | </note>
|
---|
5073 | <note>
|
---|
5074 | Calling this method is only valid on instances returned
|
---|
5075 | by <link to="ISession::machine"/> and on new machines
|
---|
5076 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
5077 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
5078 | yet registered, or on unregistered machines after calling
|
---|
5079 | <link to="IVirtualBox::unregisterMachine"/>.
|
---|
5080 | </note>
|
---|
5081 | <note>
|
---|
5082 | The deleted machine settings file can be restored (saved again)
|
---|
5083 | by calling <link to="#saveSettings"/>.
|
---|
5084 | </note>
|
---|
5085 |
|
---|
5086 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5087 | Cannot delete settings of a registered machine or
|
---|
5088 | machine not mutable.
|
---|
5089 | </result>
|
---|
5090 | <result name="VBOX_E_IPRT_ERROR">
|
---|
5091 | Could not delete the settings file.
|
---|
5092 | </result>
|
---|
5093 |
|
---|
5094 | </desc>
|
---|
5095 | </method>
|
---|
5096 |
|
---|
5097 | <method name="export">
|
---|
5098 | <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
|
---|
5099 | steps required to export VirtualBox machines to OVF.
|
---|
5100 | </desc>
|
---|
5101 |
|
---|
5102 | <param name="aAppliance" type="IAppliance" dir="in">
|
---|
5103 | <desc>Appliance to export this machine to.</desc>
|
---|
5104 | </param>
|
---|
5105 | <param name="aDescription" type="IVirtualSystemDescription" dir="return">
|
---|
5106 | <desc>VirtualSystemDescription object which is created for this machine.</desc>
|
---|
5107 | </param>
|
---|
5108 | </method >
|
---|
5109 |
|
---|
5110 | <method name="getSnapshot">
|
---|
5111 | <desc>
|
---|
5112 | Returns a snapshot of this machine with the given UUID.
|
---|
5113 | A <tt>null</tt> UUID can be used to obtain the first snapshot
|
---|
5114 | taken on this machine. This is useful if you want to traverse
|
---|
5115 | the whole tree of snapshots starting from the root.
|
---|
5116 |
|
---|
5117 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5118 | Virtual machine has no snapshots or snapshot not found.
|
---|
5119 | </result>
|
---|
5120 |
|
---|
5121 | </desc>
|
---|
5122 | <param name="id" type="uuid" dir="in">
|
---|
5123 | <desc>UUID of the snapshot to get</desc>
|
---|
5124 | </param>
|
---|
5125 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
5126 | <desc>Snapshot object with the given UUID.</desc>
|
---|
5127 | </param>
|
---|
5128 | </method>
|
---|
5129 |
|
---|
5130 | <method name="findSnapshot">
|
---|
5131 | <desc>
|
---|
5132 | Returns a snapshot of this machine with the given name.
|
---|
5133 |
|
---|
5134 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5135 | Virtual machine has no snapshots or snapshot not found.
|
---|
5136 | </result>
|
---|
5137 |
|
---|
5138 | </desc>
|
---|
5139 | <param name="name" type="wstring" dir="in">
|
---|
5140 | <desc>Name of the snapshot to find</desc>
|
---|
5141 | </param>
|
---|
5142 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
5143 | <desc>Snapshot object with the given name.</desc>
|
---|
5144 | </param>
|
---|
5145 | </method>
|
---|
5146 |
|
---|
5147 | <method name="setCurrentSnapshot">
|
---|
5148 | <desc>
|
---|
5149 | Sets the current snapshot of this machine.
|
---|
5150 | <note>
|
---|
5151 | In the current implementation, this operation is not
|
---|
5152 | implemented.
|
---|
5153 | </note>
|
---|
5154 | </desc>
|
---|
5155 | <param name="id" type="uuid" dir="in">
|
---|
5156 | <desc>UUID of the snapshot to set as the current snapshot.</desc>
|
---|
5157 | </param>
|
---|
5158 | </method>
|
---|
5159 |
|
---|
5160 | <method name="createSharedFolder">
|
---|
5161 | <desc>
|
---|
5162 | Creates a new permanent shared folder by associating the given logical
|
---|
5163 | name with the given host path, adds it to the collection of shared
|
---|
5164 | folders and starts sharing it. Refer to the description of
|
---|
5165 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
5166 |
|
---|
5167 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
5168 | Shared folder already exists.
|
---|
5169 | </result>
|
---|
5170 | <result name="VBOX_E_FILE_ERROR">
|
---|
5171 | Shared folder @a hostPath not accessible.
|
---|
5172 | </result>
|
---|
5173 |
|
---|
5174 | </desc>
|
---|
5175 | <param name="name" type="wstring" dir="in">
|
---|
5176 | <desc>Unique logical name of the shared folder.</desc>
|
---|
5177 | </param>
|
---|
5178 | <param name="hostPath" type="wstring" dir="in">
|
---|
5179 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
5180 | </param>
|
---|
5181 | <param name="writable" type="boolean" dir="in">
|
---|
5182 | <desc>Whether the share is writable or readonly</desc>
|
---|
5183 | </param>
|
---|
5184 | </method>
|
---|
5185 |
|
---|
5186 | <method name="removeSharedFolder">
|
---|
5187 | <desc>
|
---|
5188 | Removes the permanent shared folder with the given name previously
|
---|
5189 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
5190 | shared folders and stops sharing it.
|
---|
5191 |
|
---|
5192 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5193 | Virtual machine is not mutable.
|
---|
5194 | </result>
|
---|
5195 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5196 | Shared folder @a name does not exist.
|
---|
5197 | </result>
|
---|
5198 |
|
---|
5199 | </desc>
|
---|
5200 | <param name="name" type="wstring" dir="in">
|
---|
5201 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
5202 | </param>
|
---|
5203 | </method>
|
---|
5204 |
|
---|
5205 | <method name="canShowConsoleWindow">
|
---|
5206 | <desc>
|
---|
5207 | Returns @c true if the VM console process can activate the
|
---|
5208 | console window and bring it to foreground on the desktop of
|
---|
5209 | the host PC.
|
---|
5210 | <note>
|
---|
5211 | This method will fail if a session for this machine is not
|
---|
5212 | currently open.
|
---|
5213 | </note>
|
---|
5214 |
|
---|
5215 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5216 | Machine session is not open.
|
---|
5217 | </result>
|
---|
5218 |
|
---|
5219 | </desc>
|
---|
5220 | <param name="canShow" type="boolean" dir="return">
|
---|
5221 | <desc>
|
---|
5222 | @c true if the console window can be shown and @c
|
---|
5223 | false otherwise.
|
---|
5224 | </desc>
|
---|
5225 | </param>
|
---|
5226 | </method>
|
---|
5227 |
|
---|
5228 | <method name="showConsoleWindow">
|
---|
5229 | <desc>
|
---|
5230 | Activates the console window and brings it to foreground on
|
---|
5231 | the desktop of the host PC. Many modern window managers on
|
---|
5232 | many platforms implement some sort of focus stealing
|
---|
5233 | prevention logic, so that it may be impossible to activate
|
---|
5234 | a window without the help of the currently active
|
---|
5235 | application. In this case, this method will return a non-zero
|
---|
5236 | identifier that represents the top-level window of the VM
|
---|
5237 | console process. The caller, if it represents a currently
|
---|
5238 | active process, is responsible to use this identifier (in a
|
---|
5239 | platform-dependent manner) to perform actual window
|
---|
5240 | activation.
|
---|
5241 | <note>
|
---|
5242 | This method will fail if a session for this machine is not
|
---|
5243 | currently open.
|
---|
5244 | </note>
|
---|
5245 |
|
---|
5246 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5247 | Machine session is not open.
|
---|
5248 | </result>
|
---|
5249 |
|
---|
5250 | </desc>
|
---|
5251 | <param name="winId" type="unsigned long long" dir="return">
|
---|
5252 | <desc>
|
---|
5253 | Platform-dependent identifier of the top-level VM console
|
---|
5254 | window, or zero if this method has performed all actions
|
---|
5255 | necessary to implement the <i>show window</i> semantics for
|
---|
5256 | the given platform and/or VirtualBox front-end.
|
---|
5257 | </desc>
|
---|
5258 | </param>
|
---|
5259 | </method>
|
---|
5260 |
|
---|
5261 | <method name="getGuestProperty">
|
---|
5262 | <desc>
|
---|
5263 | Reads an entry from the machine's guest property store.
|
---|
5264 |
|
---|
5265 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5266 | Machine session is not open.
|
---|
5267 | </result>
|
---|
5268 |
|
---|
5269 | </desc>
|
---|
5270 | <param name="name" type="wstring" dir="in">
|
---|
5271 | <desc>
|
---|
5272 | The name of the property to read.
|
---|
5273 | </desc>
|
---|
5274 | </param>
|
---|
5275 | <param name="value" type="wstring" dir="out">
|
---|
5276 | <desc>
|
---|
5277 | The value of the property. If the property does not exist then this
|
---|
5278 | will be empty.
|
---|
5279 | </desc>
|
---|
5280 | </param>
|
---|
5281 | <param name="timestamp" type="unsigned long long" dir="out">
|
---|
5282 | <desc>
|
---|
5283 | The time at which the property was last modified, as seen by the
|
---|
5284 | server process.
|
---|
5285 | </desc>
|
---|
5286 | </param>
|
---|
5287 | <param name="flags" type="wstring" dir="out">
|
---|
5288 | <desc>
|
---|
5289 | Additional property parameters, passed as a comma-separated list of
|
---|
5290 | "name=value" type entries.
|
---|
5291 | </desc>
|
---|
5292 | </param>
|
---|
5293 | </method>
|
---|
5294 |
|
---|
5295 | <method name="getGuestPropertyValue">
|
---|
5296 | <desc>
|
---|
5297 | Reads a value from the machine's guest property store.
|
---|
5298 |
|
---|
5299 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5300 | Machine session is not open.
|
---|
5301 | </result>
|
---|
5302 |
|
---|
5303 | </desc>
|
---|
5304 | <param name="property" type="wstring" dir="in">
|
---|
5305 | <desc>
|
---|
5306 | The name of the property to read.
|
---|
5307 | </desc>
|
---|
5308 | </param>
|
---|
5309 | <param name="value" type="wstring" dir="return">
|
---|
5310 | <desc>
|
---|
5311 | The value of the property. If the property does not exist then this
|
---|
5312 | will be empty.
|
---|
5313 | </desc>
|
---|
5314 | </param>
|
---|
5315 | </method>
|
---|
5316 |
|
---|
5317 | <method name="getGuestPropertyTimestamp">
|
---|
5318 | <desc>
|
---|
5319 | Reads a property timestamp from the machine's guest property store.
|
---|
5320 |
|
---|
5321 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5322 | Machine session is not open.
|
---|
5323 | </result>
|
---|
5324 |
|
---|
5325 | </desc>
|
---|
5326 | <param name="property" type="wstring" dir="in">
|
---|
5327 | <desc>
|
---|
5328 | The name of the property to read.
|
---|
5329 | </desc>
|
---|
5330 | </param>
|
---|
5331 | <param name="value" type="unsigned long long" dir="return">
|
---|
5332 | <desc>
|
---|
5333 | The timestamp. If the property does not exist then this will be
|
---|
5334 | empty.
|
---|
5335 | </desc>
|
---|
5336 | </param>
|
---|
5337 | </method>
|
---|
5338 |
|
---|
5339 | <method name="setGuestProperty">
|
---|
5340 | <desc>
|
---|
5341 | Sets, changes or deletes an entry in the machine's guest property
|
---|
5342 | store.
|
---|
5343 |
|
---|
5344 | <result name="E_ACCESSDENIED">
|
---|
5345 | Property cannot be changed.
|
---|
5346 | </result>
|
---|
5347 | <result name="E_INVALIDARG">
|
---|
5348 | Invalid @a flags.
|
---|
5349 | </result>
|
---|
5350 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5351 | Virtual machine is not mutable or session not open.
|
---|
5352 | </result>
|
---|
5353 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5354 | Cannot set transient property when machine not running.
|
---|
5355 | </result>
|
---|
5356 |
|
---|
5357 | </desc>
|
---|
5358 | <param name="property" type="wstring" dir="in">
|
---|
5359 | <desc>
|
---|
5360 | The name of the property to set, change or delete.
|
---|
5361 | </desc>
|
---|
5362 | </param>
|
---|
5363 | <param name="value" type="wstring" dir="in">
|
---|
5364 | <desc>
|
---|
5365 | The new value of the property to set, change or delete. If the
|
---|
5366 | property does not yet exist and value is non-empty, it will be
|
---|
5367 | created. If the value is empty, the key will be deleted if it
|
---|
5368 | exists.
|
---|
5369 | </desc>
|
---|
5370 | </param>
|
---|
5371 | <param name="flags" type="wstring" dir="in">
|
---|
5372 | <desc>
|
---|
5373 | Additional property parameters, passed as a comma-separated list of
|
---|
5374 | "name=value" type entries.
|
---|
5375 | </desc>
|
---|
5376 | </param>
|
---|
5377 | </method>
|
---|
5378 |
|
---|
5379 | <method name="setGuestPropertyValue">
|
---|
5380 | <desc>
|
---|
5381 | Sets, changes or deletes a value in the machine's guest property
|
---|
5382 | store. The flags field will be left unchanged or created empty for a
|
---|
5383 | new property.
|
---|
5384 |
|
---|
5385 | <result name="E_ACCESSDENIED">
|
---|
5386 | Property cannot be changed.
|
---|
5387 | </result>
|
---|
5388 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5389 | Virtual machine is not mutable or session not open.
|
---|
5390 | </result>
|
---|
5391 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5392 | Cannot set transient property when machine not running.
|
---|
5393 | </result>
|
---|
5394 | </desc>
|
---|
5395 |
|
---|
5396 | <param name="property" type="wstring" dir="in">
|
---|
5397 | <desc>
|
---|
5398 | The name of the property to set, change or delete.
|
---|
5399 | </desc>
|
---|
5400 | </param>
|
---|
5401 | <param name="value" type="wstring" dir="in">
|
---|
5402 | <desc>
|
---|
5403 | The new value of the property to set, change or delete. If the
|
---|
5404 | property does not yet exist and value is non-empty, it will be
|
---|
5405 | created. If value is empty, the property will be deleted if it
|
---|
5406 | exists.
|
---|
5407 | </desc>
|
---|
5408 | </param>
|
---|
5409 | </method>
|
---|
5410 |
|
---|
5411 | <method name="enumerateGuestProperties">
|
---|
5412 | <desc>
|
---|
5413 | Return a list of the guest properties matching a set of patterns along
|
---|
5414 | with their values, time stamps and flags.
|
---|
5415 | </desc>
|
---|
5416 | <param name="patterns" type="wstring" dir="in">
|
---|
5417 | <desc>
|
---|
5418 | The patterns to match the properties against, separated by '|'
|
---|
5419 | characters. If this is empty or NULL, all properties will match.
|
---|
5420 | </desc>
|
---|
5421 | </param>
|
---|
5422 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
5423 | <desc>
|
---|
5424 | The names of the properties returned.
|
---|
5425 | </desc>
|
---|
5426 | </param>
|
---|
5427 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
5428 | <desc>
|
---|
5429 | The values of the properties returned. The array entries match the
|
---|
5430 | corresponding entries in the @a name array.
|
---|
5431 | </desc>
|
---|
5432 | </param>
|
---|
5433 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
5434 | <desc>
|
---|
5435 | The time stamps of the properties returned. The array entries match
|
---|
5436 | the corresponding entries in the @a name array.
|
---|
5437 | </desc>
|
---|
5438 | </param>
|
---|
5439 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
5440 | <desc>
|
---|
5441 | The flags of the properties returned. The array entries match the
|
---|
5442 | corresponding entries in the @a name array.
|
---|
5443 | </desc>
|
---|
5444 | </param>
|
---|
5445 | </method>
|
---|
5446 | </interface>
|
---|
5447 |
|
---|
5448 | <!--
|
---|
5449 | // IConsole
|
---|
5450 | /////////////////////////////////////////////////////////////////////////
|
---|
5451 | -->
|
---|
5452 |
|
---|
5453 | <interface
|
---|
5454 | name="IConsoleCallback" extends="$unknown"
|
---|
5455 | uuid="13dfbef3-b74d-487d-bada-2304529aefa6"
|
---|
5456 | wsmap="suppress"
|
---|
5457 | >
|
---|
5458 |
|
---|
5459 | <method name="onMousePointerShapeChange">
|
---|
5460 | <desc>
|
---|
5461 | Notification when the guest mouse pointer shape has
|
---|
5462 | changed. The new shape data is given.
|
---|
5463 | </desc>
|
---|
5464 | <param name="visible" type="boolean" dir="in">
|
---|
5465 | <desc>
|
---|
5466 | Flag whether the pointer is visible.
|
---|
5467 | </desc>
|
---|
5468 | </param>
|
---|
5469 | <param name="alpha" type="boolean" dir="in">
|
---|
5470 | <desc>
|
---|
5471 | Flag whether the pointer has an alpha channel.
|
---|
5472 | </desc>
|
---|
5473 | </param>
|
---|
5474 | <param name="xHot" type="unsigned long" dir="in">
|
---|
5475 | <desc>
|
---|
5476 | The pointer hot spot x coordinate.
|
---|
5477 | </desc>
|
---|
5478 | </param>
|
---|
5479 | <param name="yHot" type="unsigned long" dir="in">
|
---|
5480 | <desc>
|
---|
5481 | The pointer hot spot y coordinate.
|
---|
5482 | </desc>
|
---|
5483 | </param>
|
---|
5484 | <param name="width" type="unsigned long" dir="in">
|
---|
5485 | <desc>
|
---|
5486 | Width of the pointer shape in pixels.
|
---|
5487 | </desc>
|
---|
5488 | </param>
|
---|
5489 | <param name="height" type="unsigned long" dir="in">
|
---|
5490 | <desc>
|
---|
5491 | Height of the pointer shape in pixels.
|
---|
5492 | </desc>
|
---|
5493 | </param>
|
---|
5494 | <param name="shape" type="octet" mod="ptr" dir="in">
|
---|
5495 | <desc>
|
---|
5496 | Address of the shape buffer.
|
---|
5497 |
|
---|
5498 | The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
|
---|
5499 | followed by a 32-bpp XOR (color) mask.
|
---|
5500 |
|
---|
5501 | For pointers without alpha channel the XOR mask pixels are 32
|
---|
5502 | bit values: (lsb)BGR0(msb). For pointers with alpha channel
|
---|
5503 | the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
|
---|
5504 |
|
---|
5505 | An AND mask is used for pointers with alpha channel, so if the
|
---|
5506 | callback does not support alpha, the pointer could be
|
---|
5507 | displayed as a normal color pointer.
|
---|
5508 |
|
---|
5509 | The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
|
---|
5510 | size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
|
---|
5511 | height</tt>. The padding bits at the end of each scanline are
|
---|
5512 | undefined.
|
---|
5513 |
|
---|
5514 | The XOR mask follows the AND mask on the next 4-byte aligned
|
---|
5515 | offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
|
---|
5516 | Bytes in the gap between the AND and the XOR mask are undefined.
|
---|
5517 | The XOR mask scanlines have no gap between them and the size of
|
---|
5518 | the XOR mask is: <tt>cXor = width * 4 * height</tt>.
|
---|
5519 |
|
---|
5520 | <note>
|
---|
5521 | If @a shape is 0, only the pointer visibility is changed.
|
---|
5522 | </note>
|
---|
5523 | </desc>
|
---|
5524 | </param>
|
---|
5525 | </method>
|
---|
5526 |
|
---|
5527 | <method name="onMouseCapabilityChange">
|
---|
5528 | <desc>
|
---|
5529 | Notification when the mouse capabilities reported by the
|
---|
5530 | guest have changed. The new capabilities are passed.
|
---|
5531 | </desc>
|
---|
5532 | <param name="supportsAbsolute" type="boolean" dir="in"/>
|
---|
5533 | <param name="needsHostCursor" type="boolean" dir="in"/>
|
---|
5534 | </method>
|
---|
5535 |
|
---|
5536 | <method name="onKeyboardLedsChange">
|
---|
5537 | <desc>
|
---|
5538 | Notification when the guest OS executes the KBD_CMD_SET_LEDS command
|
---|
5539 | to alter the state of the keyboard LEDs.
|
---|
5540 | </desc>
|
---|
5541 | <param name="numLock" type="boolean" dir="in"/>
|
---|
5542 | <param name="capsLock" type="boolean" dir="in"/>
|
---|
5543 | <param name="scrollLock" type="boolean" dir="in"/>
|
---|
5544 | </method>
|
---|
5545 |
|
---|
5546 | <method name="onStateChange">
|
---|
5547 | <desc>
|
---|
5548 | Notification when the execution state of the machine has changed.
|
---|
5549 | The new state will be given.
|
---|
5550 | </desc>
|
---|
5551 | <param name="state" type="MachineState" dir="in"/>
|
---|
5552 | </method>
|
---|
5553 |
|
---|
5554 | <method name="onAdditionsStateChange">
|
---|
5555 | <desc>
|
---|
5556 | Notification when a Guest Additions property changes.
|
---|
5557 | Interested callees should query IGuest attributes to
|
---|
5558 | find out what has changed.
|
---|
5559 | </desc>
|
---|
5560 | </method>
|
---|
5561 |
|
---|
5562 | <method name="onDVDDriveChange">
|
---|
5563 | <desc>
|
---|
5564 | Notification when a property of the
|
---|
5565 | virtual <link to="IMachine::DVDDrive">DVD drive</link> changes.
|
---|
5566 | Interested callees should use IDVDDrive methods to find out what has
|
---|
5567 | changed.
|
---|
5568 | </desc>
|
---|
5569 | </method>
|
---|
5570 |
|
---|
5571 | <method name="onFloppyDriveChange">
|
---|
5572 | <desc>
|
---|
5573 | Notification when a property of the
|
---|
5574 | virtual <link to="IMachine::floppyDrive">floppy drive</link> changes.
|
---|
5575 | Interested callees should use IFloppyDrive methods to find out what
|
---|
5576 | has changed.
|
---|
5577 | </desc>
|
---|
5578 | </method>
|
---|
5579 |
|
---|
5580 | <method name="onNetworkAdapterChange">
|
---|
5581 | <desc>
|
---|
5582 | Notification when a property of one of the
|
---|
5583 | virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
|
---|
5584 | changes. Interested callees should use INetworkAdapter methods and
|
---|
5585 | attributes to find out what has changed.
|
---|
5586 | </desc>
|
---|
5587 | <param name="networkAdapter" type="INetworkAdapter" dir="in">
|
---|
5588 | <desc>Network adapter that is subject to change.</desc>
|
---|
5589 | </param>
|
---|
5590 | </method>
|
---|
5591 |
|
---|
5592 | <method name="onSerialPortChange">
|
---|
5593 | <desc>
|
---|
5594 | Notification when a property of one of the
|
---|
5595 | virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
|
---|
5596 | Interested callees should use ISerialPort methods and attributes
|
---|
5597 | to find out what has changed.
|
---|
5598 | </desc>
|
---|
5599 | <param name="serialPort" type="ISerialPort" dir="in">
|
---|
5600 | <desc>Serial port that is subject to change.</desc>
|
---|
5601 | </param>
|
---|
5602 | </method>
|
---|
5603 |
|
---|
5604 | <method name="onParallelPortChange">
|
---|
5605 | <desc>
|
---|
5606 | Notification when a property of one of the
|
---|
5607 | virtual <link to="IMachine::getParallelPort">parallel ports</link>
|
---|
5608 | changes. Interested callees should use ISerialPort methods and
|
---|
5609 | attributes to find out what has changed.
|
---|
5610 | </desc>
|
---|
5611 | <param name="parallelPort" type="IParallelPort" dir="in">
|
---|
5612 | <desc>Parallel port that is subject to change.</desc>
|
---|
5613 | </param>
|
---|
5614 | </method>
|
---|
5615 |
|
---|
5616 | <method name="onStorageControllerChange">
|
---|
5617 | <desc>
|
---|
5618 | Notification when a property of one of the
|
---|
5619 | virtual <link to="IMachine::storageControllers">storage controllers</link>
|
---|
5620 | changes. Interested callees should query the corresponding collections
|
---|
5621 | to find out what has changed.
|
---|
5622 | </desc>
|
---|
5623 | </method>
|
---|
5624 |
|
---|
5625 | <method name="onVRDPServerChange">
|
---|
5626 | <desc>
|
---|
5627 | Notification when a property of the
|
---|
5628 | <link to="IMachine::VRDPServer">VRDP server</link> changes.
|
---|
5629 | Interested callees should use IVRDPServer methods and attributes to
|
---|
5630 | find out what has changed.
|
---|
5631 | </desc>
|
---|
5632 | </method>
|
---|
5633 |
|
---|
5634 | <method name="onUSBControllerChange">
|
---|
5635 | <desc>
|
---|
5636 | Notification when a property of the virtual
|
---|
5637 | <link to="IMachine::USBController">USB controller</link> changes.
|
---|
5638 | Interested callees should use IUSBController methods and attributes to
|
---|
5639 | find out what has changed.
|
---|
5640 | </desc>
|
---|
5641 | </method>
|
---|
5642 |
|
---|
5643 | <method name="onUSBDeviceStateChange">
|
---|
5644 | <desc>
|
---|
5645 | Notification when a USB device is attached to or detached from
|
---|
5646 | the virtual USB controller.
|
---|
5647 |
|
---|
5648 | This notification is sent as a result of the indirect
|
---|
5649 | request to attach the device because it matches one of the
|
---|
5650 | machine USB filters, or as a result of the direct request
|
---|
5651 | issued by <link to="IConsole::attachUSBDevice"/> or
|
---|
5652 | <link to="IConsole::detachUSBDevice"/>.
|
---|
5653 |
|
---|
5654 | This notification is sent in case of both a succeeded and a
|
---|
5655 | failed request completion. When the request succeeds, the
|
---|
5656 | @a error parameter is @c null, and the given device has been
|
---|
5657 | already added to (when @a attached is @c true) or removed from
|
---|
5658 | (when @a attached is @c false) the collection represented by
|
---|
5659 | <link to="IConsole::USBDevices"/>. On failure, the collection
|
---|
5660 | doesn't change and the @a error parameter represents the error
|
---|
5661 | message describing the failure.
|
---|
5662 |
|
---|
5663 | </desc>
|
---|
5664 | <param name="device" type="IUSBDevice" dir="in">
|
---|
5665 | <desc>Device that is subject to state change.</desc>
|
---|
5666 | </param>
|
---|
5667 | <param name="attached" type="boolean" dir="in">
|
---|
5668 | <desc>
|
---|
5669 | <tt>true</tt> if the device was attached
|
---|
5670 | and <tt>false</tt> otherwise.
|
---|
5671 | </desc>
|
---|
5672 | </param>
|
---|
5673 | <param name="error" type="IVirtualBoxErrorInfo" dir="in">
|
---|
5674 | <desc>
|
---|
5675 | <tt>null</tt> on success or an error message object on
|
---|
5676 | failure.
|
---|
5677 | </desc>
|
---|
5678 | </param>
|
---|
5679 | </method>
|
---|
5680 |
|
---|
5681 | <method name="onSharedFolderChange">
|
---|
5682 | <desc>
|
---|
5683 | Notification when a shared folder is added or removed.
|
---|
5684 | The @a scope argument defines one of three scopes:
|
---|
5685 | <link to="IVirtualBox::sharedFolders">global shared folders</link>
|
---|
5686 | (<link to="Scope_Global">Global</link>),
|
---|
5687 | <link to="IMachine::sharedFolders">permanent shared folders</link> of
|
---|
5688 | the machine (<link to="Scope_Machine">Machine</link>) or <link
|
---|
5689 | to="IConsole::sharedFolders">transient shared folders</link> of the
|
---|
5690 | machine (<link to="Scope_Session">Session</link>). Interested callees
|
---|
5691 | should use query the corresponding collections to find out what has
|
---|
5692 | changed.
|
---|
5693 | </desc>
|
---|
5694 | <param name="scope" type="Scope" dir="in">
|
---|
5695 | <desc>Scope of the notification.</desc>
|
---|
5696 | </param>
|
---|
5697 | </method>
|
---|
5698 |
|
---|
5699 | <method name="onRuntimeError">
|
---|
5700 | <desc>
|
---|
5701 | Notification when an error happens during the virtual
|
---|
5702 | machine execution.
|
---|
5703 |
|
---|
5704 | There are three kinds of runtime errors:
|
---|
5705 | <ul>
|
---|
5706 | <li><i>fatal</i></li>
|
---|
5707 | <li><i>non-fatal with retry</i></li>
|
---|
5708 | <li><i>non-fatal warnings</i></li>
|
---|
5709 | </ul>
|
---|
5710 |
|
---|
5711 | <b>Fatal</b> errors are indicated by the @a fatal parameter set
|
---|
5712 | to <tt>true</tt>. In case of fatal errors, the virtual machine
|
---|
5713 | execution is always paused before calling this notification, and
|
---|
5714 | the notification handler is supposed either to immediately save
|
---|
5715 | the virtual machine state using <link to="IConsole::saveState"/>
|
---|
5716 | or power it off using <link to="IConsole::powerDown"/>.
|
---|
5717 | Resuming the execution can lead to unpredictable results.
|
---|
5718 |
|
---|
5719 | <b>Non-fatal</b> errors and warnings are indicated by the
|
---|
5720 | @a fatal parameter set to <tt>false</tt>. If the virtual machine
|
---|
5721 | is in the Paused state by the time the error notification is
|
---|
5722 | received, it means that the user can <i>try to resume</i> the machine
|
---|
5723 | execution after attempting to solve the problem that caused the
|
---|
5724 | error. In this case, the notification handler is supposed
|
---|
5725 | to show an appropriate message to the user (depending on the
|
---|
5726 | value of the @a id parameter) that offers several actions such
|
---|
5727 | as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
|
---|
5728 | wants to retry, the notification handler should continue
|
---|
5729 | the machine execution using the <link to="IConsole::resume"/>
|
---|
5730 | call. If the machine execution is not Paused during this
|
---|
5731 | notification, then it means this notification is a <i>warning</i>
|
---|
5732 | (for example, about a fatal condition that can happen very soon);
|
---|
5733 | no immediate action is required from the user, the machine
|
---|
5734 | continues its normal execution.
|
---|
5735 |
|
---|
5736 | Note that in either case the notification handler
|
---|
5737 | <b>must not</b> perform any action directly on a thread
|
---|
5738 | where this notification is called. Everything it is allowed to
|
---|
5739 | do is to post a message to another thread that will then talk
|
---|
5740 | to the user and take the corresponding action.
|
---|
5741 |
|
---|
5742 | Currently, the following error identifiers are known:
|
---|
5743 | <ul>
|
---|
5744 | <li><tt>"HostMemoryLow"</tt></li>
|
---|
5745 | <li><tt>"HostAudioNotResponding"</tt></li>
|
---|
5746 | <li><tt>"VDIStorageFull"</tt></li>
|
---|
5747 | </ul>
|
---|
5748 |
|
---|
5749 | <note>
|
---|
5750 | This notification is not designed to be implemented by
|
---|
5751 | more than one callback at a time. If you have multiple
|
---|
5752 | IConsoleCallback instances registered on the given
|
---|
5753 | IConsole object, make sure you simply do nothing but
|
---|
5754 | return @c S_OK from all but one of them that does actual
|
---|
5755 | user notification and performs necessary actions.
|
---|
5756 | </note>
|
---|
5757 |
|
---|
5758 | </desc>
|
---|
5759 | <param name="fatal" type="boolean" dir="in">
|
---|
5760 | <desc>Whether the error is fatal or not</desc>
|
---|
5761 | </param>
|
---|
5762 | <param name="id" type="wstring" dir="in">
|
---|
5763 | <desc>Error identifier</desc>
|
---|
5764 | </param>
|
---|
5765 | <param name="message" type="wstring" dir="in">
|
---|
5766 | <desc>Optional error message</desc>
|
---|
5767 | </param>
|
---|
5768 | </method>
|
---|
5769 |
|
---|
5770 | <method name="onCanShowWindow">
|
---|
5771 | <desc>
|
---|
5772 | Notification when a call to
|
---|
5773 | <link to="IMachine::canShowConsoleWindow"/> is made by a
|
---|
5774 | front-end to check if a subsequent call to
|
---|
5775 | <link to="IMachine::showConsoleWindow"/> can succeed.
|
---|
5776 |
|
---|
5777 | The callee should give an answer appropriate to the current
|
---|
5778 | machine state in the @a canShow argument. This answer must
|
---|
5779 | remain valid at least until the next
|
---|
5780 | <link to="IConsole::state">machine state</link> change.
|
---|
5781 |
|
---|
5782 | <note>
|
---|
5783 | This notification is not designed to be implemented by
|
---|
5784 | more than one callback at a time. If you have multiple
|
---|
5785 | IConsoleCallback instances registered on the given
|
---|
5786 | IConsole object, make sure you simply do nothing but
|
---|
5787 | return @c true and @c S_OK from all but one of them that
|
---|
5788 | actually manages console window activation.
|
---|
5789 | </note>
|
---|
5790 | </desc>
|
---|
5791 | <param name="canShow" type="boolean" dir="return">
|
---|
5792 | <desc>
|
---|
5793 | @c true if the console window can be shown and @c
|
---|
5794 | false otherwise.
|
---|
5795 | </desc>
|
---|
5796 | </param>
|
---|
5797 | </method>
|
---|
5798 |
|
---|
5799 | <method name="onShowWindow">
|
---|
5800 | <desc>
|
---|
5801 | Notification when a call to
|
---|
5802 | <link to="IMachine::showConsoleWindow"/>
|
---|
5803 | requests the console window to be activated and brought to
|
---|
5804 | foreground on the desktop of the host PC.
|
---|
5805 |
|
---|
5806 | This notification should cause the VM console process to
|
---|
5807 | perform the requested action as described above. If it is
|
---|
5808 | impossible to do it at a time of this notification, this
|
---|
5809 | method should return a failure.
|
---|
5810 |
|
---|
5811 | Note that many modern window managers on many platforms
|
---|
5812 | implement some sort of focus stealing prevention logic, so
|
---|
5813 | that it may be impossible to activate a window without the
|
---|
5814 | help of the currently active application (which is supposedly
|
---|
5815 | an initiator of this notification). In this case, this method
|
---|
5816 | must return a non-zero identifier that represents the
|
---|
5817 | top-level window of the VM console process. The caller, if it
|
---|
5818 | represents a currently active process, is responsible to use
|
---|
5819 | this identifier (in a platform-dependent manner) to perform
|
---|
5820 | actual window activation.
|
---|
5821 |
|
---|
5822 | This method must set @a winId to zero if it has performed all
|
---|
5823 | actions necessary to complete the request and the console
|
---|
5824 | window is now active and in foreground, to indicate that no
|
---|
5825 | further action is required on the caller's side.
|
---|
5826 |
|
---|
5827 | <note>
|
---|
5828 | This notification is not designed to be implemented by
|
---|
5829 | more than one callback at a time. If you have multiple
|
---|
5830 | IConsoleCallback instances registered on the given
|
---|
5831 | IConsole object, make sure you simply do nothing but
|
---|
5832 | return @c S_OK from all but one of them that actually
|
---|
5833 | manages console window activation.
|
---|
5834 | </note>
|
---|
5835 | </desc>
|
---|
5836 | <param name="winId" type="unsigned long long" dir="return">
|
---|
5837 | <desc>
|
---|
5838 | Platform-dependent identifier of the top-level VM console
|
---|
5839 | window, or zero if this method has performed all actions
|
---|
5840 | necessary to implement the <i>show window</i> semantics for
|
---|
5841 | the given platform and/or this VirtualBox front-end.
|
---|
5842 | </desc>
|
---|
5843 | </param>
|
---|
5844 | </method>
|
---|
5845 |
|
---|
5846 | </interface>
|
---|
5847 |
|
---|
5848 | <interface
|
---|
5849 | name="IRemoteDisplayInfo" extends="$unknown"
|
---|
5850 | uuid="550104cd-2dfd-4a6c-857d-f6f8e088e62c"
|
---|
5851 | wsmap="struct"
|
---|
5852 | >
|
---|
5853 | <desc>
|
---|
5854 | Contains information about the remote display (VRDP) capabilities and status.
|
---|
5855 | This is used in the <link to="IConsole::remoteDisplayInfo" /> attribute.
|
---|
5856 | </desc>
|
---|
5857 |
|
---|
5858 | <attribute name="active" type="boolean" readonly="yes">
|
---|
5859 | <desc>
|
---|
5860 | Whether the remote display connection is active.
|
---|
5861 | </desc>
|
---|
5862 | </attribute>
|
---|
5863 |
|
---|
5864 | <attribute name="numberOfClients" type="unsigned long" readonly="yes">
|
---|
5865 | <desc>
|
---|
5866 | How many times a client connected.
|
---|
5867 | </desc>
|
---|
5868 | </attribute>
|
---|
5869 |
|
---|
5870 | <attribute name="beginTime" type="long long" readonly="yes">
|
---|
5871 | <desc>
|
---|
5872 | When the last connection was established, in milliseconds since 1970-01-01 UTC.
|
---|
5873 | </desc>
|
---|
5874 | </attribute>
|
---|
5875 |
|
---|
5876 | <attribute name="endTime" type="long long" readonly="yes">
|
---|
5877 | <desc>
|
---|
5878 | When the last connection was terminated or the current time, if
|
---|
5879 | connection is still active, in milliseconds since 1970-01-01 UTC.
|
---|
5880 | </desc>
|
---|
5881 | </attribute>
|
---|
5882 |
|
---|
5883 | <attribute name="bytesSent" type="unsigned long long" readonly="yes">
|
---|
5884 | <desc>
|
---|
5885 | How many bytes were sent in last or current, if still active, connection.
|
---|
5886 | </desc>
|
---|
5887 | </attribute>
|
---|
5888 |
|
---|
5889 | <attribute name="bytesSentTotal" type="unsigned long long" readonly="yes">
|
---|
5890 | <desc>
|
---|
5891 | How many bytes were sent in all connections.
|
---|
5892 | </desc>
|
---|
5893 | </attribute>
|
---|
5894 |
|
---|
5895 | <attribute name="bytesReceived" type="unsigned long long" readonly="yes">
|
---|
5896 | <desc>
|
---|
5897 | How many bytes were received in last or current, if still active, connection.
|
---|
5898 | </desc>
|
---|
5899 | </attribute>
|
---|
5900 |
|
---|
5901 | <attribute name="bytesReceivedTotal" type="unsigned long long" readonly="yes">
|
---|
5902 | <desc>
|
---|
5903 | How many bytes were received in all connections.
|
---|
5904 | </desc>
|
---|
5905 | </attribute>
|
---|
5906 |
|
---|
5907 | <attribute name="user" type="wstring" readonly="yes">
|
---|
5908 | <desc>
|
---|
5909 | Login user name supplied by the client.
|
---|
5910 | </desc>
|
---|
5911 | </attribute>
|
---|
5912 |
|
---|
5913 | <attribute name="domain" type="wstring" readonly="yes">
|
---|
5914 | <desc>
|
---|
5915 | Login domain name supplied by the client.
|
---|
5916 | </desc>
|
---|
5917 | </attribute>
|
---|
5918 |
|
---|
5919 | <attribute name="clientName" type="wstring" readonly="yes">
|
---|
5920 | <desc>
|
---|
5921 | The client name supplied by the client.
|
---|
5922 | </desc>
|
---|
5923 | </attribute>
|
---|
5924 |
|
---|
5925 | <attribute name="clientIP" type="wstring" readonly="yes">
|
---|
5926 | <desc>
|
---|
5927 | The IP address of the client.
|
---|
5928 | </desc>
|
---|
5929 | </attribute>
|
---|
5930 |
|
---|
5931 | <attribute name="clientVersion" type="unsigned long" readonly="yes">
|
---|
5932 | <desc>
|
---|
5933 | The client software version number.
|
---|
5934 | </desc>
|
---|
5935 | </attribute>
|
---|
5936 |
|
---|
5937 | <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
|
---|
5938 | <desc>
|
---|
5939 | Public key exchange method used when connection was established.
|
---|
5940 | Values: 0 - RDP4 public key exchange scheme.
|
---|
5941 | 1 - X509 certificates were sent to client.
|
---|
5942 | </desc>
|
---|
5943 | </attribute>
|
---|
5944 |
|
---|
5945 | </interface>
|
---|
5946 |
|
---|
5947 | <interface
|
---|
5948 | name="IConsole" extends="$unknown"
|
---|
5949 | uuid="9511bc54-15ee-4ddf-808e-472aba03809c"
|
---|
5950 | wsmap="managed"
|
---|
5951 | >
|
---|
5952 | <desc>
|
---|
5953 | The IConsole interface represents an interface to control virtual
|
---|
5954 | machine execution.
|
---|
5955 |
|
---|
5956 | The console object that implements the IConsole interface is obtained
|
---|
5957 | from a session object after the session for the given machine has been
|
---|
5958 | opened using one of <link to="IVirtualBox::openSession"/>,
|
---|
5959 | <link to="IVirtualBox::openRemoteSession"/> or
|
---|
5960 | <link to="IVirtualBox::openExistingSession"/> methods.
|
---|
5961 |
|
---|
5962 | Methods of the IConsole interface allow the caller to query the current
|
---|
5963 | virtual machine execution state, pause the machine or power it down, save
|
---|
5964 | the machine state or take a snapshot, attach and detach removable media
|
---|
5965 | and so on.
|
---|
5966 |
|
---|
5967 | <see>ISession</see>
|
---|
5968 | </desc>
|
---|
5969 |
|
---|
5970 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
5971 | <desc>
|
---|
5972 | Machine object this console is sessioned with.
|
---|
5973 | <note>
|
---|
5974 | This is a convenience property, it has the same value as
|
---|
5975 | <link to="ISession::machine"/> of the corresponding session
|
---|
5976 | object.
|
---|
5977 | </note>
|
---|
5978 | </desc>
|
---|
5979 | </attribute>
|
---|
5980 |
|
---|
5981 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
5982 | <desc>
|
---|
5983 | Current execution state of the machine.
|
---|
5984 | <note>
|
---|
5985 | This property always returns the same value as the corresponding
|
---|
5986 | property of the IMachine object this console is sessioned with.
|
---|
5987 | For the process that owns (executes) the VM, this is the
|
---|
5988 | preferable way of querying the VM state, because no IPC
|
---|
5989 | calls are made.
|
---|
5990 | </note>
|
---|
5991 | </desc>
|
---|
5992 | </attribute>
|
---|
5993 |
|
---|
5994 | <attribute name="guest" type="IGuest" readonly="yes">
|
---|
5995 | <desc>Guest object.</desc>
|
---|
5996 | </attribute>
|
---|
5997 |
|
---|
5998 | <attribute name="keyboard" type="IKeyboard" readonly="yes">
|
---|
5999 | <desc>
|
---|
6000 | Virtual keyboard object.
|
---|
6001 | <note>
|
---|
6002 | If the machine is not running, any attempt to use
|
---|
6003 | the returned object will result in an error.
|
---|
6004 | </note>
|
---|
6005 | </desc>
|
---|
6006 | </attribute>
|
---|
6007 |
|
---|
6008 | <attribute name="mouse" type="IMouse" readonly="yes">
|
---|
6009 | <desc>
|
---|
6010 | Virtual mouse object.
|
---|
6011 | <note>
|
---|
6012 | If the machine is not running, any attempt to use
|
---|
6013 | the returned object will result in an error.
|
---|
6014 | </note>
|
---|
6015 | </desc>
|
---|
6016 | </attribute>
|
---|
6017 |
|
---|
6018 | <attribute name="display" type="IDisplay" readonly="yes">
|
---|
6019 | <desc>Virtual display object.
|
---|
6020 | <note>
|
---|
6021 | If the machine is not running, any attempt to use
|
---|
6022 | the returned object will result in an error.
|
---|
6023 | </note>
|
---|
6024 | </desc>
|
---|
6025 | </attribute>
|
---|
6026 |
|
---|
6027 | <attribute name="debugger" type="IMachineDebugger" readonly="yes">
|
---|
6028 | <desc>Debugging interface.</desc>
|
---|
6029 | </attribute>
|
---|
6030 |
|
---|
6031 | <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
|
---|
6032 | <desc>
|
---|
6033 | Collection of USB devices currently attached to the virtual
|
---|
6034 | USB controller.
|
---|
6035 | <note>
|
---|
6036 | The collection is empty if the machine is not running.
|
---|
6037 | </note>
|
---|
6038 | </desc>
|
---|
6039 | </attribute>
|
---|
6040 |
|
---|
6041 | <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
6042 | <desc>
|
---|
6043 | List of USB devices currently attached to the remote VRDP client.
|
---|
6044 | Once a new device is physically attached to the remote host computer,
|
---|
6045 | it appears in this list and remains there until detached.
|
---|
6046 | </desc>
|
---|
6047 | </attribute>
|
---|
6048 |
|
---|
6049 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
6050 | <desc>
|
---|
6051 | Collection of shared folders for the current session. These folders
|
---|
6052 | are called transient shared folders because they are available to the
|
---|
6053 | guest OS running inside the associated virtual machine only for the
|
---|
6054 | duration of the session (as opposed to
|
---|
6055 | <link to="IMachine::sharedFolders"/> which represent permanent shared
|
---|
6056 | folders). When the session is closed (e.g. the machine is powered down),
|
---|
6057 | these folders are automatically discarded.
|
---|
6058 |
|
---|
6059 | New shared folders are added to the collection using
|
---|
6060 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
6061 | removed using <link to="#removeSharedFolder"/>.
|
---|
6062 | </desc>
|
---|
6063 | </attribute>
|
---|
6064 |
|
---|
6065 | <attribute name="remoteDisplayInfo" type="IRemoteDisplayInfo" readonly="yes">
|
---|
6066 | <desc>
|
---|
6067 | Interface that provides information on Remote Display (VRDP) connection.
|
---|
6068 | </desc>
|
---|
6069 | </attribute>
|
---|
6070 |
|
---|
6071 | <method name="powerUp">
|
---|
6072 | <desc>
|
---|
6073 | Starts the virtual machine execution using the current machine
|
---|
6074 | state (that is, its current execution state, current settings and
|
---|
6075 | current hard disks).
|
---|
6076 |
|
---|
6077 | If the machine is powered off or aborted, the execution will
|
---|
6078 | start from the beginning (as if the real hardware were just
|
---|
6079 | powered on).
|
---|
6080 |
|
---|
6081 | If the machine is in the <link to="MachineState_Saved"/> state,
|
---|
6082 | it will continue its execution the point where the state has
|
---|
6083 | been saved.
|
---|
6084 |
|
---|
6085 | <note>
|
---|
6086 | Unless you are trying to write a new VirtualBox front-end that
|
---|
6087 | performs direct machine execution (like the VirtualBox or VBoxSDL
|
---|
6088 | front-ends), don't call <link to="IConsole::powerUp"/> in a direct
|
---|
6089 | session opened by <link to="IVirtualBox::openSession"/> and use this
|
---|
6090 | session only to change virtual machine settings. If you simply want to
|
---|
6091 | start virtual machine execution using one of the existing front-ends
|
---|
6092 | (for example the VirtualBox GUI or headless server), simply use
|
---|
6093 | <link to="IVirtualBox::openRemoteSession"/>; these front-ends will
|
---|
6094 | power up the machine automatically for you.
|
---|
6095 | </note>
|
---|
6096 |
|
---|
6097 | <see>#saveState</see>
|
---|
6098 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6099 | Virtual machine already running.
|
---|
6100 | </result>
|
---|
6101 | <result name="VBOX_E_HOST_ERROR">
|
---|
6102 | Host interface does not exist or name not set.
|
---|
6103 | </result>
|
---|
6104 | <result name="VBOX_E_FILE_ERROR">
|
---|
6105 | Invalid saved state file.
|
---|
6106 | </result>
|
---|
6107 | </desc>
|
---|
6108 | <param name="progress" type="IProgress" dir="return">
|
---|
6109 | <desc>Progress object to track the operation completion.</desc>
|
---|
6110 | </param>
|
---|
6111 | </method>
|
---|
6112 |
|
---|
6113 | <method name="powerUpPaused">
|
---|
6114 | <desc>
|
---|
6115 | Identical to powerUp except that the VM will enter the
|
---|
6116 | <link to="MachineState_Paused"/> state, instead of
|
---|
6117 | <link to="MachineState_Running"/>.
|
---|
6118 |
|
---|
6119 | <see>#powerUp</see>
|
---|
6120 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6121 | Virtual machine already running.
|
---|
6122 | </result>
|
---|
6123 | <result name="VBOX_E_HOST_ERROR">
|
---|
6124 | Host interface does not exist or name not set.
|
---|
6125 | </result>
|
---|
6126 | <result name="VBOX_E_FILE_ERROR">
|
---|
6127 | Invalid saved state file.
|
---|
6128 | </result>
|
---|
6129 | </desc>
|
---|
6130 | <param name="progress" type="IProgress" dir="return">
|
---|
6131 | <desc>Progress object to track the operation completion.</desc>
|
---|
6132 | </param>
|
---|
6133 | </method>
|
---|
6134 |
|
---|
6135 | <method name="powerDown">
|
---|
6136 | <desc>
|
---|
6137 | Stops the virtual machine execution.
|
---|
6138 | After this operation completes, the machine will go to the
|
---|
6139 | PoweredOff state.
|
---|
6140 |
|
---|
6141 | @deprecated This method will be removed in VirtualBox 2.1 where the
|
---|
6142 | powerDownAsync() method will take its name. Do not use this method in
|
---|
6143 | the code.
|
---|
6144 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6145 | Virtual machine must be Running, Paused or Stuck to be powered down.
|
---|
6146 | </result>
|
---|
6147 | <result name="VBOX_E_VM_ERROR">
|
---|
6148 | Unable to power off or destroy virtual machine.
|
---|
6149 | </result>
|
---|
6150 | </desc>
|
---|
6151 | </method>
|
---|
6152 |
|
---|
6153 | <method name="powerDownAsync">
|
---|
6154 | <desc>
|
---|
6155 | Initiates the power down procedure to stop the virtual machine
|
---|
6156 | execution.
|
---|
6157 |
|
---|
6158 | The completion of the power down procedure is tracked using the returned
|
---|
6159 | IProgress object. After the operation is complete, the machine will go
|
---|
6160 | to the PoweredOff state.
|
---|
6161 |
|
---|
6162 | @warning This method will be renamed to "powerDown" in VirtualBox 2.1
|
---|
6163 | where the original powerDown() method will be removed. You will need to
|
---|
6164 | rename "powerDownAsync" to "powerDown" in your sources to make them
|
---|
6165 | build with version 2.1.
|
---|
6166 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6167 | Virtual machine must be Running, Paused or Stuck to be powered down.
|
---|
6168 | </result>
|
---|
6169 | </desc>
|
---|
6170 | <param name="progress" type="IProgress" dir="return">
|
---|
6171 | <desc>Progress object to track the operation completion.</desc>
|
---|
6172 | </param>
|
---|
6173 | </method>
|
---|
6174 |
|
---|
6175 | <method name="reset">
|
---|
6176 | <desc>Resets the virtual machine.
|
---|
6177 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6178 | Virtual machine not in Running state.
|
---|
6179 | </result>
|
---|
6180 | <result name="VBOX_E_VM_ERROR">
|
---|
6181 | Virtual machine error in reset operation.
|
---|
6182 | </result>
|
---|
6183 | </desc>
|
---|
6184 | </method>
|
---|
6185 |
|
---|
6186 | <method name="pause">
|
---|
6187 | <desc>Pauses the virtual machine execution.
|
---|
6188 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6189 | Virtual machine not in Running state.
|
---|
6190 | </result>
|
---|
6191 | <result name="VBOX_E_VM_ERROR">
|
---|
6192 | Virtual machine error in suspend operation.
|
---|
6193 | </result>
|
---|
6194 | </desc>
|
---|
6195 | </method>
|
---|
6196 |
|
---|
6197 | <method name="resume">
|
---|
6198 | <desc>Resumes the virtual machine execution.
|
---|
6199 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6200 | Virtual machine not in Paused state.
|
---|
6201 | </result>
|
---|
6202 | <result name="VBOX_E_VM_ERROR">
|
---|
6203 | Virtual machine error in resume operation.
|
---|
6204 | </result>
|
---|
6205 | </desc>
|
---|
6206 | </method>
|
---|
6207 |
|
---|
6208 | <method name="powerButton">
|
---|
6209 | <desc>Sends the ACPI power button event to the guest.
|
---|
6210 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6211 | Virtual machine not in Running state.
|
---|
6212 | </result>
|
---|
6213 | <result name="VBOX_E_PDM_ERROR">
|
---|
6214 | Controlled power off failed.
|
---|
6215 | </result>
|
---|
6216 | </desc>
|
---|
6217 | </method>
|
---|
6218 |
|
---|
6219 | <method name="sleepButton">
|
---|
6220 | <desc>Sends the ACPI sleep button event to the guest.
|
---|
6221 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6222 | Virtual machine not in Running state.
|
---|
6223 | </result>
|
---|
6224 | <result name="VBOX_E_PDM_ERROR">
|
---|
6225 | Sending sleep button event failed.
|
---|
6226 | </result>
|
---|
6227 | </desc>
|
---|
6228 | </method>
|
---|
6229 |
|
---|
6230 | <method name="getPowerButtonHandled">
|
---|
6231 | <desc>Checks if the last power button event was handled by guest.
|
---|
6232 | <result name="VBOX_E_PDM_ERROR">
|
---|
6233 | Checking if the event was handled by the guest OS failed.
|
---|
6234 | </result>
|
---|
6235 | </desc>
|
---|
6236 | <param name="handled" type="boolean" dir="return"/>
|
---|
6237 | </method>
|
---|
6238 |
|
---|
6239 | <method name="getGuestEnteredACPIMode">
|
---|
6240 | <desc>Checks if the guest entered the ACPI mode G0 (working) or
|
---|
6241 | G1 (sleeping). If this method returns false, the guest will
|
---|
6242 | most likely not respond to external ACPI events.
|
---|
6243 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6244 | Virtual machine not in Running state.
|
---|
6245 | </result>
|
---|
6246 | </desc>
|
---|
6247 | <param name="entered" type="boolean" dir="return"/>
|
---|
6248 | </method>
|
---|
6249 |
|
---|
6250 | <method name="saveState">
|
---|
6251 | <desc>
|
---|
6252 | Saves the current execution state of a running virtual machine
|
---|
6253 | and stops its execution.
|
---|
6254 |
|
---|
6255 | After this operation completes, the machine will go to the
|
---|
6256 | Saved state. Next time it is powered up, this state will
|
---|
6257 | be restored and the machine will continue its execution from
|
---|
6258 | the place where it was saved.
|
---|
6259 |
|
---|
6260 | This operation differs from taking a snapshot to the effect
|
---|
6261 | that it doesn't create new differencing hard disks. Also, once
|
---|
6262 | the machine is powered up from the state saved using this method,
|
---|
6263 | the saved state is deleted, so it will be impossible to return
|
---|
6264 | to this state later.
|
---|
6265 |
|
---|
6266 | <note>
|
---|
6267 | On success, this method implicitly calls
|
---|
6268 | <link to="IMachine::saveSettings"/> to save all current machine
|
---|
6269 | settings (including runtime changes to the DVD drive, etc.).
|
---|
6270 | Together with the impossibility to change any VM settings when it is
|
---|
6271 | in the Saved state, this guarantees adequate hardware
|
---|
6272 | configuration of the machine when it is restored from the saved
|
---|
6273 | state file.
|
---|
6274 | </note>
|
---|
6275 |
|
---|
6276 | <note>
|
---|
6277 | The machine must be in the Running or Paused state, otherwise
|
---|
6278 | the operation will fail.
|
---|
6279 | </note>
|
---|
6280 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6281 | Virtual machine state neither Running nor Paused.
|
---|
6282 | </result>
|
---|
6283 | <result name="VBOX_E_FILE_ERROR">
|
---|
6284 | Failed to create directory for saved state file.
|
---|
6285 | </result>
|
---|
6286 |
|
---|
6287 | <see><link to="#takeSnapshot"/></see>
|
---|
6288 | </desc>
|
---|
6289 | <param name="progress" type="IProgress" dir="return">
|
---|
6290 | <desc>Progress object to track the operation completion.</desc>
|
---|
6291 | </param>
|
---|
6292 | </method>
|
---|
6293 |
|
---|
6294 | <method name="adoptSavedState">
|
---|
6295 | <desc>
|
---|
6296 | Associates the given saved state file to the virtual machine.
|
---|
6297 |
|
---|
6298 | On success, the machine will go to the Saved state. Next time it is
|
---|
6299 | powered up, it will be restored from the adopted saved state and
|
---|
6300 | continue execution from the place where the saved state file was
|
---|
6301 | created.
|
---|
6302 |
|
---|
6303 | The specified saved state file path may be absolute or relative to the
|
---|
6304 | folder the VM normally saves the state to (usually,
|
---|
6305 | <link to="IMachine::snapshotFolder"/>).
|
---|
6306 |
|
---|
6307 | <note>
|
---|
6308 | It's a caller's responsibility to make sure the given saved state
|
---|
6309 | file is compatible with the settings of this virtual machine that
|
---|
6310 | represent its virtual hardware (memory size, hard disk configuration
|
---|
6311 | etc.). If there is a mismatch, the behavior of the virtual machine
|
---|
6312 | is undefined.
|
---|
6313 | </note>
|
---|
6314 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6315 | Virtual machine state neither PoweredOff nor Aborted.
|
---|
6316 | </result>
|
---|
6317 | </desc>
|
---|
6318 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
6319 | <desc>Path to the saved state file to adopt.</desc>
|
---|
6320 | </param>
|
---|
6321 | </method>
|
---|
6322 |
|
---|
6323 | <method name="discardSavedState">
|
---|
6324 | <desc>
|
---|
6325 | Discards (deletes) the saved state of the virtual machine
|
---|
6326 | previously created by <link to="#saveState"/>. Next time the
|
---|
6327 | machine is powered up, a clean boot will occur.
|
---|
6328 | <note>
|
---|
6329 | This operation is equivalent to resetting or powering off
|
---|
6330 | the machine without doing a proper shutdown in the guest OS.
|
---|
6331 | </note>
|
---|
6332 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6333 | Virtual machine not in state Saved.
|
---|
6334 | </result>
|
---|
6335 | </desc>
|
---|
6336 | </method>
|
---|
6337 |
|
---|
6338 | <method name="getDeviceActivity">
|
---|
6339 | <desc>
|
---|
6340 | Gets the current activity type of a given device or device group.
|
---|
6341 | <result name="E_INVALIDARG">
|
---|
6342 | Invalid device type.
|
---|
6343 | </result>
|
---|
6344 | </desc>
|
---|
6345 | <param name="type" type="DeviceType" dir="in"/>
|
---|
6346 | <param name="activity" type="DeviceActivity" dir="return"/>
|
---|
6347 | </method>
|
---|
6348 |
|
---|
6349 | <method name="attachUSBDevice">
|
---|
6350 | <desc>
|
---|
6351 | Attaches a host USB device with the given UUID to the
|
---|
6352 | USB controller of the virtual machine.
|
---|
6353 |
|
---|
6354 | The device needs to be in one of the following states:
|
---|
6355 | <link to="USBDeviceState_Busy"/>,
|
---|
6356 | <link to="USBDeviceState_Available"/> or
|
---|
6357 | <link to="USBDeviceState_Held"/>,
|
---|
6358 | otherwise an error is immediately returned.
|
---|
6359 |
|
---|
6360 | When the device state is
|
---|
6361 | <link to="USBDeviceState_Busy">Busy</link>, an error may also
|
---|
6362 | be returned if the host computer refuses to release it for some reason.
|
---|
6363 |
|
---|
6364 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6365 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6366 | Virtual machine state neither Running nor Paused.
|
---|
6367 | </result>
|
---|
6368 | <result name="VBOX_E_PDM_ERROR">
|
---|
6369 | Virtual machine does not have a USB controller.
|
---|
6370 | </result>
|
---|
6371 | </desc>
|
---|
6372 | <param name="id" type="uuid" dir="in">
|
---|
6373 | <desc>UUID of the host USB device to attach.</desc>
|
---|
6374 | </param>
|
---|
6375 | </method>
|
---|
6376 |
|
---|
6377 | <method name="detachUSBDevice">
|
---|
6378 | <desc>
|
---|
6379 | Detaches an USB device with the given UUID from the USB controller
|
---|
6380 | of the virtual machine.
|
---|
6381 |
|
---|
6382 | After this method succeeds, the VirtualBox server re-initiates
|
---|
6383 | all USB filters as if the device were just physically attached
|
---|
6384 | to the host, but filters of this machine are ignored to avoid
|
---|
6385 | a possible automatic re-attachment.
|
---|
6386 |
|
---|
6387 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6388 |
|
---|
6389 | <result name="VBOX_E_PDM_ERROR">
|
---|
6390 | Virtual machine does not have a USB controller.
|
---|
6391 | </result>
|
---|
6392 | <result name="E_INVALIDARG">
|
---|
6393 | USB device not attached to this virtual machine.
|
---|
6394 | </result>
|
---|
6395 | </desc>
|
---|
6396 | <param name="id" type="uuid" dir="in">
|
---|
6397 | <desc>UUID of the USB device to detach.</desc>
|
---|
6398 | </param>
|
---|
6399 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6400 | <desc>Detached USB device.</desc>
|
---|
6401 | </param>
|
---|
6402 | </method>
|
---|
6403 |
|
---|
6404 | <method name="findUSBDeviceByAddress">
|
---|
6405 | <desc>
|
---|
6406 | Searches for a USB device with the given host address.
|
---|
6407 |
|
---|
6408 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6409 | Given @c name does not correspond to any USB device.
|
---|
6410 | </result>
|
---|
6411 |
|
---|
6412 | <see>IUSBDevice::address</see>
|
---|
6413 | </desc>
|
---|
6414 | <param name="name" type="wstring" dir="in">
|
---|
6415 | <desc>
|
---|
6416 | Address of the USB device (as assigned by the host) to
|
---|
6417 | search for.
|
---|
6418 | </desc>
|
---|
6419 | </param>
|
---|
6420 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6421 | <desc>Found USB device object.</desc>
|
---|
6422 | </param>
|
---|
6423 | </method>
|
---|
6424 |
|
---|
6425 | <method name="findUSBDeviceById">
|
---|
6426 | <desc>
|
---|
6427 | Searches for a USB device with the given UUID.
|
---|
6428 |
|
---|
6429 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6430 | Given @c id does not correspond to any USB device.
|
---|
6431 | </result>
|
---|
6432 |
|
---|
6433 | <see>IUSBDevice::id</see>
|
---|
6434 | </desc>
|
---|
6435 | <param name="id" type="uuid" dir="in">
|
---|
6436 | <desc>UUID of the USB device to search for.</desc>
|
---|
6437 | </param>
|
---|
6438 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6439 | <desc>Found USB device object.</desc>
|
---|
6440 | </param>
|
---|
6441 | </method>
|
---|
6442 |
|
---|
6443 | <method name="createSharedFolder">
|
---|
6444 | <desc>
|
---|
6445 | Creates a transient new shared folder by associating the given logical
|
---|
6446 | name with the given host path, adds it to the collection of shared
|
---|
6447 | folders and starts sharing it. Refer to the description of
|
---|
6448 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
6449 |
|
---|
6450 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6451 | Virtual machine in Saved state or currently changing state.
|
---|
6452 | </result>
|
---|
6453 | <result name="VBOX_E_FILE_ERROR">
|
---|
6454 | Shared folder already exists or not accessible.
|
---|
6455 | </result>
|
---|
6456 | </desc>
|
---|
6457 | <param name="name" type="wstring" dir="in">
|
---|
6458 | <desc>Unique logical name of the shared folder.</desc>
|
---|
6459 | </param>
|
---|
6460 | <param name="hostPath" type="wstring" dir="in">
|
---|
6461 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
6462 | </param>
|
---|
6463 | <param name="writable" type="boolean" dir="in">
|
---|
6464 | <desc>Whether the share is writable or readonly</desc>
|
---|
6465 | </param>
|
---|
6466 | </method>
|
---|
6467 |
|
---|
6468 | <method name="removeSharedFolder">
|
---|
6469 | <desc>
|
---|
6470 | Removes a transient shared folder with the given name previously
|
---|
6471 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
6472 | shared folders and stops sharing it.
|
---|
6473 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6474 | Virtual machine in Saved state or currently changing state.
|
---|
6475 | </result>
|
---|
6476 | <result name="VBOX_E_FILE_ERROR">
|
---|
6477 | Shared folder does not exists.
|
---|
6478 | </result>
|
---|
6479 | </desc>
|
---|
6480 | <param name="name" type="wstring" dir="in">
|
---|
6481 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
6482 | </param>
|
---|
6483 | </method>
|
---|
6484 |
|
---|
6485 | <method name="takeSnapshot">
|
---|
6486 | <desc>
|
---|
6487 | Saves the current execution state and all settings of the
|
---|
6488 | machine and creates differencing images for all
|
---|
6489 | normal (non-independent) hard disks.
|
---|
6490 |
|
---|
6491 | This method can be called for a PoweredOff, Saved, Running or
|
---|
6492 | Paused virtual machine. When the machine is PoweredOff, an
|
---|
6493 | offline <link to="ISnapshot">snapshot</link> is created,
|
---|
6494 | in all other cases -- an online snapshot.
|
---|
6495 |
|
---|
6496 | The taken snapshot is always based on the
|
---|
6497 | <link to="IMachine::currentSnapshot">current
|
---|
6498 | snapshot</link> of the associated virtual machine and becomes
|
---|
6499 | a new current snapshot.
|
---|
6500 |
|
---|
6501 | <note>
|
---|
6502 | This method implicitly calls <link to="IMachine::saveSettings"/> to
|
---|
6503 | save all current machine settings before taking an offline snapshot.
|
---|
6504 | </note>
|
---|
6505 |
|
---|
6506 | <see>ISnapshot, <link to="#saveState"/></see>
|
---|
6507 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6508 | Virtual machine currently changing state.
|
---|
6509 | </result>
|
---|
6510 | </desc>
|
---|
6511 | <param name="name" type="wstring" dir="in">
|
---|
6512 | <desc>Short name for the snapshot.</desc>
|
---|
6513 | </param>
|
---|
6514 | <param name="description" type="wstring" dir="in">
|
---|
6515 | <desc>Optional description of the snapshot.</desc>
|
---|
6516 | </param>
|
---|
6517 | <param name="progress" type="IProgress" dir="return">
|
---|
6518 | <desc>Progress object to track the operation completion.</desc>
|
---|
6519 | </param>
|
---|
6520 | </method>
|
---|
6521 |
|
---|
6522 | <method name="discardSnapshot">
|
---|
6523 | <desc>
|
---|
6524 |
|
---|
6525 | Starts discarding the specified snapshot. The execution state
|
---|
6526 | and settings of the associated machine stored in the snapshot
|
---|
6527 | will be deleted. The contents of all differencing hard disks of
|
---|
6528 | this snapshot will be merged with the contents of their
|
---|
6529 | dependent child hard disks to keep the, disks valid (in other
|
---|
6530 | words, all changes represented by hard disks being discarded
|
---|
6531 | will be propagated to their child hard disks). After that, this
|
---|
6532 | snapshot's differencing hard disks will be deleted. The parent
|
---|
6533 | of this snapshot will become a new parent for all its child
|
---|
6534 | snapshots.
|
---|
6535 |
|
---|
6536 | If the discarded snapshot is the current one, its parent
|
---|
6537 | snapshot will become a new current snapshot. The current machine
|
---|
6538 | state is not directly affected in this case, except that
|
---|
6539 | currently attached differencing hard disks based on hard disks
|
---|
6540 | of the discarded snapshot will be also merged as described
|
---|
6541 | above.
|
---|
6542 |
|
---|
6543 | If the discarded snapshot is the first one (the root snapshot)
|
---|
6544 | and it has exactly one child snapshot, this child snapshot will
|
---|
6545 | become the first snapshot after discarding. If there are no
|
---|
6546 | children at all (i.e. the first snapshot is the only snapshot of
|
---|
6547 | the machine), both the current and the first snapshot of the
|
---|
6548 | machine will be set to null. In all other cases, the first
|
---|
6549 | snapshot cannot be discarded.
|
---|
6550 |
|
---|
6551 | You cannot discard the snapshot if it
|
---|
6552 | stores <link to="HardDiskType_Normal">normal</link> (non-differencing)
|
---|
6553 | hard disks that have differencing hard disks based on them. Snapshots of
|
---|
6554 | such kind can be discarded only when every normal hard disk has either
|
---|
6555 | no children at all or exactly one child. In the former case, the normal
|
---|
6556 | hard disk simply becomes unused (i.e. not attached to any VM). In the
|
---|
6557 | latter case, it receives all the changes stored in the child hard disk,
|
---|
6558 | and then it replaces the child hard disk in the configuration of the
|
---|
6559 | corresponding snapshot or machine.
|
---|
6560 |
|
---|
6561 | Also, you cannot discard the snapshot if it stores hard disks
|
---|
6562 | (of any type) having differencing child hard disks that belong
|
---|
6563 | to other machines. Such snapshots can be only discarded after
|
---|
6564 | you discard all snapshots of other machines containing "foreign"
|
---|
6565 | child disks, or detach these "foreign" child disks from machines
|
---|
6566 | they are attached to.
|
---|
6567 |
|
---|
6568 | One particular example of the snapshot storing normal hard disks
|
---|
6569 | is the first snapshot of a virtual machine that had normal hard
|
---|
6570 | disks attached when taking the snapshot. Be careful when
|
---|
6571 | discarding such snapshots because this implicitly commits
|
---|
6572 | changes (made since the snapshot being discarded has been taken)
|
---|
6573 | to normal hard disks (as described above), which may be not what
|
---|
6574 | you want.
|
---|
6575 |
|
---|
6576 | The virtual machine is put to
|
---|
6577 | the <link to="MachineState_Discarding">Discarding</link> state until
|
---|
6578 | the discard operation is completed.
|
---|
6579 |
|
---|
6580 | <note>
|
---|
6581 | The machine must not be running, otherwise the operation
|
---|
6582 | will fail.
|
---|
6583 | </note>
|
---|
6584 |
|
---|
6585 | <note>
|
---|
6586 | Child hard disks of all normal hard disks of the discarded snapshot
|
---|
6587 | must be accessible (see <link to="IMedium::state"/>) for this
|
---|
6588 | operation to succeed. In particular, this means that all virtual
|
---|
6589 | machines, whose hard disks are directly or indirectly based on the
|
---|
6590 | hard disks of discarded snapshot, must be powered off.
|
---|
6591 | </note>
|
---|
6592 | <note>
|
---|
6593 | Merging hard disk contents can be very time and disk space
|
---|
6594 | consuming, if these disks are big in size and have many
|
---|
6595 | children. However, if the snapshot being discarded is the last
|
---|
6596 | (head) snapshot on the branch, the operation will be rather
|
---|
6597 | quick.
|
---|
6598 | </note>
|
---|
6599 | <note>
|
---|
6600 | Note that discarding the current snapshot
|
---|
6601 | will implicitly call <link to="IMachine::saveSettings"/> to
|
---|
6602 | make all current machine settings permanent.
|
---|
6603 | </note>
|
---|
6604 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6605 | Virtual machine is running.
|
---|
6606 | </result>
|
---|
6607 | </desc>
|
---|
6608 | <param name="id" type="uuid" dir="in">
|
---|
6609 | <desc>UUID of the snapshot to discard.</desc>
|
---|
6610 | </param>
|
---|
6611 | <param name="progress" type="IProgress" dir="return">
|
---|
6612 | <desc>Progress object to track the operation completion.</desc>
|
---|
6613 | </param>
|
---|
6614 | </method>
|
---|
6615 |
|
---|
6616 | <method name="discardCurrentState">
|
---|
6617 | <desc>
|
---|
6618 | This operation is similar to <link to="IConsole::discardSnapshot"/> but
|
---|
6619 | affects the current machine state. This means that the state stored in
|
---|
6620 | the current snapshot will become a new current state, and all current
|
---|
6621 | settings of the machine and changes stored in differencing hard disks
|
---|
6622 | will be lost.
|
---|
6623 |
|
---|
6624 | After this operation is successfully completed, new empty differencing
|
---|
6625 | hard disks are created for all normal hard disks of the machine.
|
---|
6626 |
|
---|
6627 | If the current snapshot of the machine is an online snapshot, the
|
---|
6628 | machine will go to the <link to="MachineState_Saved"> saved
|
---|
6629 | state</link>, so that the next time it is powered on, the execution
|
---|
6630 | state will be restored from the current snapshot.
|
---|
6631 |
|
---|
6632 | <note>
|
---|
6633 | The machine must not be running, otherwise the operation will fail.
|
---|
6634 | </note>
|
---|
6635 |
|
---|
6636 | <note>
|
---|
6637 | If the machine state is <link to="MachineState_Saved">Saved</link>
|
---|
6638 | prior to this operation, the saved state file will be implicitly
|
---|
6639 | discarded (as if <link to="IConsole::discardSavedState"/> were
|
---|
6640 | called).
|
---|
6641 | </note>
|
---|
6642 |
|
---|
6643 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6644 | Virtual machine is running.
|
---|
6645 | </result>
|
---|
6646 | </desc>
|
---|
6647 | <param name="progress" type="IProgress" dir="return">
|
---|
6648 | <desc>Progress object to track the operation completion.</desc>
|
---|
6649 | </param>
|
---|
6650 | </method>
|
---|
6651 |
|
---|
6652 | <method name="discardCurrentSnapshotAndState">
|
---|
6653 | <desc>
|
---|
6654 |
|
---|
6655 | This method is equivalent to
|
---|
6656 | doing <link to="IConsole::discardSnapshot">discardSnapshot</link>
|
---|
6657 | (currentSnapshot.id(), progress) followed by
|
---|
6658 | <link to="IConsole::discardCurrentState"/>.
|
---|
6659 |
|
---|
6660 | As a result, the machine will be fully restored from the
|
---|
6661 | snapshot preceding the current snapshot, while both the current
|
---|
6662 | snapshot and the current machine state will be discarded.
|
---|
6663 |
|
---|
6664 | If the current snapshot is the first snapshot of the machine (i.e. it
|
---|
6665 | has the only snapshot), the current machine state will be
|
---|
6666 | discarded <b>before</b> discarding the snapshot. In other words, the
|
---|
6667 | machine will be restored from its last snapshot, before discarding
|
---|
6668 | it. This differs from performing a single
|
---|
6669 | <link to="IConsole::discardSnapshot"/> call (note that no
|
---|
6670 | <link to="IConsole::discardCurrentState"/> will be possible after it)
|
---|
6671 | to the effect that the latter will preserve the current state instead of
|
---|
6672 | discarding it.
|
---|
6673 |
|
---|
6674 | Unless explicitly mentioned otherwise, all remarks and
|
---|
6675 | limitations of the above two methods also apply to this method.
|
---|
6676 |
|
---|
6677 | <note>
|
---|
6678 | The machine must not be running, otherwise the operation
|
---|
6679 | will fail.
|
---|
6680 | </note>
|
---|
6681 |
|
---|
6682 | <note>
|
---|
6683 | If the machine state is <link to="MachineState_Saved">Saved</link>
|
---|
6684 | prior to this operation, the saved state file will be implicitly
|
---|
6685 | discarded (as if <link to="#discardSavedState"/> were
|
---|
6686 | called).
|
---|
6687 | </note>
|
---|
6688 |
|
---|
6689 | <note>
|
---|
6690 | This method is more efficient than calling both of the above
|
---|
6691 | methods separately: it requires less IPC calls and provides
|
---|
6692 | a single progress object.
|
---|
6693 | </note>
|
---|
6694 |
|
---|
6695 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6696 | Virtual machine is running.
|
---|
6697 | </result>
|
---|
6698 | </desc>
|
---|
6699 | <param name="progress" type="IProgress" dir="return">
|
---|
6700 | <desc>Progress object to track the operation completion.</desc>
|
---|
6701 | </param>
|
---|
6702 | </method>
|
---|
6703 |
|
---|
6704 | <method name="registerCallback">
|
---|
6705 | <desc>
|
---|
6706 | Registers a new console callback on this instance. The methods of the
|
---|
6707 | callback interface will be called by this instance when the appropriate
|
---|
6708 | event occurs.
|
---|
6709 | </desc>
|
---|
6710 | <param name="callback" type="IConsoleCallback" dir="in"/>
|
---|
6711 | </method>
|
---|
6712 |
|
---|
6713 | <method name="unregisterCallback">
|
---|
6714 | <desc>
|
---|
6715 | Unregisters the console callback previously registered using
|
---|
6716 | <link to="#registerCallback"/>.
|
---|
6717 | <result name="E_INVALIDARG">
|
---|
6718 | Given @a callback handler is not registered.
|
---|
6719 | </result>
|
---|
6720 | </desc>
|
---|
6721 | <param name="callback" type="IConsoleCallback" dir="in"/>
|
---|
6722 | </method>
|
---|
6723 | </interface>
|
---|
6724 |
|
---|
6725 | <!--
|
---|
6726 | // IHost
|
---|
6727 | /////////////////////////////////////////////////////////////////////////
|
---|
6728 | -->
|
---|
6729 |
|
---|
6730 | <interface
|
---|
6731 | name="IHostDVDDrive" extends="$unknown"
|
---|
6732 | uuid="21f86694-202d-4ce4-8b05-a63ff82dbf4c"
|
---|
6733 | wsmap="managed"
|
---|
6734 | >
|
---|
6735 | <desc>
|
---|
6736 | The IHostDVDDrive interface represents the physical CD/DVD drive
|
---|
6737 | hardware on the host. Used indirectly in <link to="IHost::DVDDrives"/>.
|
---|
6738 | </desc>
|
---|
6739 |
|
---|
6740 | <attribute name="name" type="wstring" readonly="yes">
|
---|
6741 | <desc>
|
---|
6742 | Returns the platform-specific device identifier.
|
---|
6743 | On DOS-like platforms, it is a drive name (e.g. R:).
|
---|
6744 | On Unix-like platforms, it is a device name (e.g. /dev/hdc).
|
---|
6745 | </desc>
|
---|
6746 | </attribute>
|
---|
6747 | <attribute name="description" type="wstring" readonly="yes">
|
---|
6748 | <desc>
|
---|
6749 | Returns a human readable description for the drive. This
|
---|
6750 | description usually contains the product and vendor name. A
|
---|
6751 | @c null string is returned if the description is not available.
|
---|
6752 | </desc>
|
---|
6753 | </attribute>
|
---|
6754 | <attribute name="udi" type="wstring" readonly="yes">
|
---|
6755 | <desc>
|
---|
6756 | Returns the unique device identifier for the drive. This
|
---|
6757 | attribute is reserved for future use instead of
|
---|
6758 | <link to="#name"/>. Currently it is not used and may return
|
---|
6759 | @c null on some platforms.
|
---|
6760 | </desc>
|
---|
6761 | </attribute>
|
---|
6762 |
|
---|
6763 | </interface>
|
---|
6764 |
|
---|
6765 | <interface
|
---|
6766 | name="IHostFloppyDrive" extends="$unknown"
|
---|
6767 | uuid="3f02d604-e908-4919-9fd1-8a4afd68fc63"
|
---|
6768 | wsmap="managed"
|
---|
6769 | >
|
---|
6770 | <desc>
|
---|
6771 | The IHostFloppyDrive interface represents the physical floppy drive
|
---|
6772 | hardware on the host. Used indirectly in <link to="IHost::floppyDrives"/>.
|
---|
6773 | </desc>
|
---|
6774 | <attribute name="name" type="wstring" readonly="yes">
|
---|
6775 | <desc>
|
---|
6776 | Returns the platform-specific device identifier.
|
---|
6777 | On DOS-like platforms, it is a drive name (e.g. A:).
|
---|
6778 | On Unix-like platforms, it is a device name (e.g. /dev/fd0).
|
---|
6779 | </desc>
|
---|
6780 | </attribute>
|
---|
6781 | <attribute name="description" type="wstring" readonly="yes">
|
---|
6782 | <desc>
|
---|
6783 | Returns a human readable description for the drive. This
|
---|
6784 | description usually contains the product and vendor name. A
|
---|
6785 | @c null string is returned if the description is not available.
|
---|
6786 | </desc>
|
---|
6787 | </attribute>
|
---|
6788 | <attribute name="udi" type="wstring" readonly="yes">
|
---|
6789 | <desc>
|
---|
6790 | Returns the unique device identifier for the drive. This
|
---|
6791 | attribute is reserved for future use instead of
|
---|
6792 | <link to="#name"/>. Currently it is not used and may return
|
---|
6793 | @c null on some platforms.
|
---|
6794 | </desc>
|
---|
6795 | </attribute>
|
---|
6796 | </interface>
|
---|
6797 |
|
---|
6798 | <enum
|
---|
6799 | name="HostNetworkInterfaceMediumType"
|
---|
6800 | uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
|
---|
6801 | >
|
---|
6802 | <desc>
|
---|
6803 | Type of encapsulation. Ethernet encapsulation includes both wired and
|
---|
6804 | wireless Ethernet connections.
|
---|
6805 | <see>IHostNetworkInterface</see>
|
---|
6806 | </desc>
|
---|
6807 |
|
---|
6808 | <const name="Unknown" value="0">
|
---|
6809 | <desc>
|
---|
6810 | The type of interface cannot be determined.
|
---|
6811 | </desc>
|
---|
6812 | </const>
|
---|
6813 | <const name="Ethernet" value="1">
|
---|
6814 | <desc>
|
---|
6815 | Ethernet frame encapsulation.
|
---|
6816 | </desc>
|
---|
6817 | </const>
|
---|
6818 | <const name="PPP" value="2">
|
---|
6819 | <desc>
|
---|
6820 | Point-to-point protocol encapsulation.
|
---|
6821 | </desc>
|
---|
6822 | </const>
|
---|
6823 | <const name="SLIP" value="3">
|
---|
6824 | <desc>
|
---|
6825 | Serial line IP encapsulation.
|
---|
6826 | </desc>
|
---|
6827 | </const>
|
---|
6828 | </enum>
|
---|
6829 |
|
---|
6830 | <enum
|
---|
6831 | name="HostNetworkInterfaceStatus"
|
---|
6832 | uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
|
---|
6833 | >
|
---|
6834 | <desc>
|
---|
6835 | Current status of the interface.
|
---|
6836 | <see>IHostNetworkInterface</see>
|
---|
6837 | </desc>
|
---|
6838 |
|
---|
6839 | <const name="Unknown" value="0">
|
---|
6840 | <desc>
|
---|
6841 | The state of interface cannot be determined.
|
---|
6842 | </desc>
|
---|
6843 | </const>
|
---|
6844 | <const name="Up" value="1">
|
---|
6845 | <desc>
|
---|
6846 | The interface is fully operational.
|
---|
6847 | </desc>
|
---|
6848 | </const>
|
---|
6849 | <const name="Down" value="2">
|
---|
6850 | <desc>
|
---|
6851 | The interface is not functioning.
|
---|
6852 | </desc>
|
---|
6853 | </const>
|
---|
6854 | </enum>
|
---|
6855 |
|
---|
6856 | <enum
|
---|
6857 | name="HostNetworkInterfaceType"
|
---|
6858 | uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
|
---|
6859 | >
|
---|
6860 | <desc>
|
---|
6861 | Network interface type.
|
---|
6862 | </desc>
|
---|
6863 | <const name="Bridged" value="1"/>
|
---|
6864 | <const name="HostOnly" value="2"/>
|
---|
6865 | </enum>
|
---|
6866 |
|
---|
6867 | <interface
|
---|
6868 | name="IHostNetworkInterface" extends="$unknown"
|
---|
6869 | uuid="88adaf3f-166b-4542-9457-0f1323507fae"
|
---|
6870 | wsmap="managed"
|
---|
6871 | >
|
---|
6872 | <desc>
|
---|
6873 | Reprents one of host's network interfaces. IP V6 address and network
|
---|
6874 | mask are strings of 32 hexdecimal digits grouped by four. Groups are
|
---|
6875 | separated by colons.
|
---|
6876 | For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
|
---|
6877 | </desc>
|
---|
6878 | <attribute name="name" type="wstring" readonly="yes">
|
---|
6879 | <desc>Returns the host network interface name.</desc>
|
---|
6880 | </attribute>
|
---|
6881 |
|
---|
6882 | <attribute name="id" type="uuid" readonly="yes">
|
---|
6883 | <desc>Returns the interface UUID.</desc>
|
---|
6884 | </attribute>
|
---|
6885 |
|
---|
6886 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
6887 | <desc>Returns the name of a virtual network the interface gets attached to.</desc>
|
---|
6888 | </attribute>
|
---|
6889 |
|
---|
6890 | <attribute name="dhcpEnabled" type="boolean" readonly="yes">
|
---|
6891 | <desc>Specifies whether the DHCP is enabled for the interface.</desc>
|
---|
6892 | </attribute>
|
---|
6893 |
|
---|
6894 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
6895 | <desc>Returns the IP V4 address of the interface.</desc>
|
---|
6896 | </attribute>
|
---|
6897 |
|
---|
6898 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
6899 | <desc>Returns the network mask of the interface.</desc>
|
---|
6900 | </attribute>
|
---|
6901 |
|
---|
6902 | <attribute name="IPV6Supported" type="boolean" readonly="yes">
|
---|
6903 | <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
|
---|
6904 | </attribute>
|
---|
6905 |
|
---|
6906 | <attribute name="IPV6Address" type="wstring" readonly="yes">
|
---|
6907 | <desc>Returns the IP V6 address of the interface.</desc>
|
---|
6908 | </attribute>
|
---|
6909 |
|
---|
6910 | <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
|
---|
6911 | <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
|
---|
6912 | </attribute>
|
---|
6913 |
|
---|
6914 | <attribute name="hardwareAddress" type="wstring" readonly="yes">
|
---|
6915 | <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
|
---|
6916 | </attribute>
|
---|
6917 |
|
---|
6918 | <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
|
---|
6919 | <desc>Type of protocol encapsulation used.</desc>
|
---|
6920 | </attribute>
|
---|
6921 |
|
---|
6922 | <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
|
---|
6923 | <desc>Status of the interface.</desc>
|
---|
6924 | </attribute>
|
---|
6925 |
|
---|
6926 | <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
|
---|
6927 | <desc>specifies the host interface type.</desc>
|
---|
6928 | </attribute>
|
---|
6929 |
|
---|
6930 | <method name="enableStaticIpConfig">
|
---|
6931 | <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
|
---|
6932 | <param name="IPAddress" type="wstring" dir="in">
|
---|
6933 | <desc>
|
---|
6934 | IP address.
|
---|
6935 | </desc>
|
---|
6936 | </param>
|
---|
6937 | <param name="networkMask" type="wstring" dir="in">
|
---|
6938 | <desc>
|
---|
6939 | network mask.
|
---|
6940 | </desc>
|
---|
6941 | </param>
|
---|
6942 | </method>
|
---|
6943 |
|
---|
6944 | <method name="enableStaticIpConfigV6">
|
---|
6945 | <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
|
---|
6946 | <param name="IPV6Address" type="wstring" dir="in">
|
---|
6947 | <desc>
|
---|
6948 | IP address.
|
---|
6949 | </desc>
|
---|
6950 | </param>
|
---|
6951 | <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
|
---|
6952 | <desc>
|
---|
6953 | network mask.
|
---|
6954 | </desc>
|
---|
6955 | </param>
|
---|
6956 | </method>
|
---|
6957 |
|
---|
6958 | <method name="enableDynamicIpConfig">
|
---|
6959 | <desc>enables the dynamic IP configuration.</desc>
|
---|
6960 | </method>
|
---|
6961 |
|
---|
6962 | <method name="dhcpRediscover">
|
---|
6963 | <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
|
---|
6964 | </method>
|
---|
6965 |
|
---|
6966 | </interface>
|
---|
6967 |
|
---|
6968 | <interface
|
---|
6969 | name="IHost" extends="$unknown"
|
---|
6970 | uuid="fa7b3d79-972c-4f18-9f61-6b20c88559b6"
|
---|
6971 | wsmap="managed"
|
---|
6972 | >
|
---|
6973 | <desc>
|
---|
6974 | The IHost interface represents the physical machine that this VirtualBox
|
---|
6975 | installation runs on.
|
---|
6976 |
|
---|
6977 | An object implementing this interface is returned by the
|
---|
6978 | <link to="IVirtualBox::host" /> attribute. This interface contains
|
---|
6979 | read-only information about the host's physical hardware (such as what
|
---|
6980 | processors and disks are available, what the host operating system is,
|
---|
6981 | and so on) and also allows for manipulating some of the host's hardware,
|
---|
6982 | such as global USB device filters and host interface networking.
|
---|
6983 |
|
---|
6984 | </desc>
|
---|
6985 | <attribute name="DVDDrives" type="IHostDVDDrive" readonly="yes" safearray="yes">
|
---|
6986 | <desc>List of DVD drives available on the host.</desc>
|
---|
6987 | </attribute>
|
---|
6988 |
|
---|
6989 | <attribute name="floppyDrives" type="IHostFloppyDrive" readonly="yes" safearray="yes">
|
---|
6990 | <desc>List of floppy drives available on the host.</desc>
|
---|
6991 | </attribute>
|
---|
6992 |
|
---|
6993 | <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
6994 | <desc>
|
---|
6995 | List of USB devices currently attached to the host.
|
---|
6996 | Once a new device is physically attached to the host computer,
|
---|
6997 | it appears in this list and remains there until detached.
|
---|
6998 |
|
---|
6999 | <note>
|
---|
7000 | If USB functionality is not available in the given edition of
|
---|
7001 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7002 | </note>
|
---|
7003 | </desc>
|
---|
7004 | </attribute>
|
---|
7005 |
|
---|
7006 | <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
7007 | <desc>
|
---|
7008 | List of USB device filters in action.
|
---|
7009 | When a new device is physically attached to the host computer,
|
---|
7010 | filters from this list are applied to it (in order they are stored
|
---|
7011 | in the list). The first matched filter will determine the
|
---|
7012 | <link to="IHostUSBDeviceFilter::action">action</link>
|
---|
7013 | performed on the device.
|
---|
7014 |
|
---|
7015 | Unless the device is ignored by these filters, filters of all
|
---|
7016 | currently running virtual machines
|
---|
7017 | (<link to="IUSBController::deviceFilters"/>) are applied to it.
|
---|
7018 |
|
---|
7019 | <note>
|
---|
7020 | If USB functionality is not available in the given edition of
|
---|
7021 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7022 | </note>
|
---|
7023 |
|
---|
7024 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
7025 | </desc>
|
---|
7026 | </attribute>
|
---|
7027 |
|
---|
7028 | <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
|
---|
7029 | <desc>List of host network interfaces currently defined on the host.</desc>
|
---|
7030 | </attribute>
|
---|
7031 |
|
---|
7032 | <attribute name="processorCount" type="unsigned long" readonly="yes">
|
---|
7033 | <desc>Number of (logical) CPUs installed in the host system.</desc>
|
---|
7034 | </attribute>
|
---|
7035 |
|
---|
7036 | <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
|
---|
7037 | <desc>Number of (logical) CPUs online in the host system.</desc>
|
---|
7038 | </attribute>
|
---|
7039 |
|
---|
7040 | <method name="getProcessorSpeed">
|
---|
7041 | <desc>Query the (approximate) maximum speed of a specified host CPU in
|
---|
7042 | Megahertz.
|
---|
7043 | </desc>
|
---|
7044 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7045 | <desc>
|
---|
7046 | Identifier of the CPU.
|
---|
7047 | </desc>
|
---|
7048 | </param>
|
---|
7049 | <param name="speed" type="unsigned long" dir="return">
|
---|
7050 | <desc>
|
---|
7051 | Speed value. 0 is returned if value is not known or @a cpuId is
|
---|
7052 | invalid.
|
---|
7053 | </desc>
|
---|
7054 | </param>
|
---|
7055 | </method>
|
---|
7056 |
|
---|
7057 | <method name="getProcessorFeature">
|
---|
7058 | <desc>Query whether a CPU feature is supported or not.</desc>
|
---|
7059 | <param name="feature" type="ProcessorFeature" dir="in">
|
---|
7060 | <desc>
|
---|
7061 | CPU Feature identifier.
|
---|
7062 | </desc>
|
---|
7063 | </param>
|
---|
7064 | <param name="supported" type="boolean" dir="return">
|
---|
7065 | <desc>
|
---|
7066 | Feature is supported or not.
|
---|
7067 | </desc>
|
---|
7068 | </param>
|
---|
7069 | </method>
|
---|
7070 |
|
---|
7071 | <method name="getProcessorDescription">
|
---|
7072 | <desc>Query the model string of a specified host CPU.
|
---|
7073 | <note>
|
---|
7074 | This function is not implemented in the current version of the
|
---|
7075 | product.
|
---|
7076 | </note>
|
---|
7077 | </desc>
|
---|
7078 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7079 | <desc>
|
---|
7080 | Identifier of the CPU.
|
---|
7081 | </desc>
|
---|
7082 | </param>
|
---|
7083 | <param name="description" type="wstring" dir="return">
|
---|
7084 | <desc>
|
---|
7085 | Model string. A NULL string is returned if value is not known or
|
---|
7086 | @a cpuId is invalid.
|
---|
7087 | </desc>
|
---|
7088 | </param>
|
---|
7089 | </method>
|
---|
7090 |
|
---|
7091 | <attribute name="memorySize" type="unsigned long" readonly="yes">
|
---|
7092 | <desc>Amount of system memory in megabytes installed in the host system.</desc>
|
---|
7093 | </attribute>
|
---|
7094 |
|
---|
7095 | <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
|
---|
7096 | <desc>Available system memory in the host system.</desc>
|
---|
7097 | </attribute>
|
---|
7098 |
|
---|
7099 | <attribute name="operatingSystem" type="wstring" readonly="yes">
|
---|
7100 | <desc>Name of the host system's operating system.</desc>
|
---|
7101 | </attribute>
|
---|
7102 |
|
---|
7103 | <attribute name="OSVersion" type="wstring" readonly="yes">
|
---|
7104 | <desc>Host operating system's version string.</desc>
|
---|
7105 | </attribute>
|
---|
7106 |
|
---|
7107 | <attribute name="UTCTime" type="long long" readonly="yes">
|
---|
7108 | <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
|
---|
7109 | </attribute>
|
---|
7110 |
|
---|
7111 | <method name="createHostOnlyNetworkInterface">
|
---|
7112 | <desc>
|
---|
7113 | Creates a new adapter for Host Only Networking.
|
---|
7114 | <result name="E_INVALIDARG">
|
---|
7115 | Host network interface @a name already exists.
|
---|
7116 | </result>
|
---|
7117 | </desc>
|
---|
7118 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
7119 | <desc>
|
---|
7120 | Created host interface object.
|
---|
7121 | </desc>
|
---|
7122 | </param>
|
---|
7123 | <param name="progress" type="IProgress" dir="return">
|
---|
7124 | <desc>
|
---|
7125 | Progress object to track the operation completion.
|
---|
7126 | </desc>
|
---|
7127 | </param>
|
---|
7128 | </method>
|
---|
7129 |
|
---|
7130 | <method name="removeHostOnlyNetworkInterface">
|
---|
7131 | <desc>
|
---|
7132 | Removes the given Host Only Networking interface.
|
---|
7133 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7134 | No host network interface matching @a id found.
|
---|
7135 | </result>
|
---|
7136 | </desc>
|
---|
7137 | <param name="id" type="uuid" dir="in">
|
---|
7138 | <desc>
|
---|
7139 | Adapter GUID.
|
---|
7140 | </desc>
|
---|
7141 | </param>
|
---|
7142 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
7143 | <desc>
|
---|
7144 | Removed host interface object.
|
---|
7145 | </desc>
|
---|
7146 | </param>
|
---|
7147 | <param name="progress" type="IProgress" dir="return">
|
---|
7148 | <desc>
|
---|
7149 | Progress object to track the operation completion.
|
---|
7150 | </desc>
|
---|
7151 | </param>
|
---|
7152 | </method>
|
---|
7153 |
|
---|
7154 | <method name="createUSBDeviceFilter">
|
---|
7155 | <desc>
|
---|
7156 | Creates a new USB device filter. All attributes except
|
---|
7157 | the filter name are set to <tt>null</tt> (any match),
|
---|
7158 | <i>active</i> is <tt>false</tt> (the filter is not active).
|
---|
7159 |
|
---|
7160 | The created filter can be added to the list of filters using
|
---|
7161 | <link to="#insertUSBDeviceFilter"/>.
|
---|
7162 |
|
---|
7163 | <see>#USBDeviceFilters</see>
|
---|
7164 | </desc>
|
---|
7165 | <param name="name" type="wstring" dir="in">
|
---|
7166 | <desc>
|
---|
7167 | Filter name. See <link to="IHostUSBDeviceFilter::name"/>
|
---|
7168 | for more info.
|
---|
7169 | </desc>
|
---|
7170 | </param>
|
---|
7171 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
7172 | <desc>Created filter object.</desc>
|
---|
7173 | </param>
|
---|
7174 | </method>
|
---|
7175 |
|
---|
7176 | <method name="insertUSBDeviceFilter">
|
---|
7177 | <desc>
|
---|
7178 | Inserts the given USB device to the specified position
|
---|
7179 | in the list of filters.
|
---|
7180 |
|
---|
7181 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
7182 | position is equal to or greater than the number of elements in
|
---|
7183 | the list, the filter is added at the end of the collection.
|
---|
7184 |
|
---|
7185 | <note>
|
---|
7186 | Duplicates are not allowed, so an attempt to insert a
|
---|
7187 | filter already in the list is an error.
|
---|
7188 | </note>
|
---|
7189 | <note>
|
---|
7190 | If USB functionality is not available in the given edition of
|
---|
7191 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7192 | </note>
|
---|
7193 |
|
---|
7194 | <see>#USBDeviceFilters</see>
|
---|
7195 |
|
---|
7196 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
7197 | USB device filter is not created within this VirtualBox instance.
|
---|
7198 | </result>
|
---|
7199 | <result name="E_INVALIDARG">
|
---|
7200 | USB device filter already in list.
|
---|
7201 | </result>
|
---|
7202 |
|
---|
7203 | </desc>
|
---|
7204 | <param name="position" type="unsigned long" dir="in">
|
---|
7205 | <desc>Position to insert the filter to.</desc>
|
---|
7206 | </param>
|
---|
7207 | <param name="filter" type="IHostUSBDeviceFilter" dir="in">
|
---|
7208 | <desc>USB device filter to insert.</desc>
|
---|
7209 | </param>
|
---|
7210 | </method>
|
---|
7211 |
|
---|
7212 | <method name="removeUSBDeviceFilter">
|
---|
7213 | <desc>
|
---|
7214 | Removes a USB device filter from the specified position in the
|
---|
7215 | list of filters.
|
---|
7216 |
|
---|
7217 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
7218 | position equal to or greater than the number of elements in
|
---|
7219 | the list will produce an error.
|
---|
7220 |
|
---|
7221 | <note>
|
---|
7222 | If USB functionality is not available in the given edition of
|
---|
7223 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7224 | </note>
|
---|
7225 |
|
---|
7226 | <see>#USBDeviceFilters</see>
|
---|
7227 |
|
---|
7228 | <result name="E_INVALIDARG">
|
---|
7229 | USB device filter list empty or invalid @a position.
|
---|
7230 | </result>
|
---|
7231 |
|
---|
7232 | </desc>
|
---|
7233 | <param name="position" type="unsigned long" dir="in">
|
---|
7234 | <desc>Position to remove the filter from.</desc>
|
---|
7235 | </param>
|
---|
7236 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
7237 | <desc>Removed USB device filter.</desc>
|
---|
7238 | </param>
|
---|
7239 | </method>
|
---|
7240 |
|
---|
7241 | <method name="findHostDVDDrive">
|
---|
7242 | <desc>
|
---|
7243 | Searches for a host DVD drive with the given @c name.
|
---|
7244 |
|
---|
7245 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7246 | Given @c name does not correspond to any host drive.
|
---|
7247 | </result>
|
---|
7248 |
|
---|
7249 | </desc>
|
---|
7250 | <param name="name" type="wstring" dir="in">
|
---|
7251 | <desc>Name of the host drive to search for</desc>
|
---|
7252 | </param>
|
---|
7253 | <param name="drive" type="IHostDVDDrive" dir="return">
|
---|
7254 | <desc>Found host drive object</desc>
|
---|
7255 | </param>
|
---|
7256 | </method>
|
---|
7257 |
|
---|
7258 | <method name="findHostFloppyDrive">
|
---|
7259 | <desc>
|
---|
7260 | Searches for a host floppy drive with the given @c name.
|
---|
7261 |
|
---|
7262 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7263 | Given @c name does not correspond to any host floppy drive.
|
---|
7264 | </result>
|
---|
7265 |
|
---|
7266 | </desc>
|
---|
7267 | <param name="name" type="wstring" dir="in">
|
---|
7268 | <desc>Name of the host floppy drive to search for</desc>
|
---|
7269 | </param>
|
---|
7270 | <param name="drive" type="IHostFloppyDrive" dir="return">
|
---|
7271 | <desc>Found host floppy drive object</desc>
|
---|
7272 | </param>
|
---|
7273 | </method>
|
---|
7274 |
|
---|
7275 | <method name="findHostNetworkInterfaceByName">
|
---|
7276 | <desc>
|
---|
7277 | Searches through all host network interfaces for an interface with
|
---|
7278 | the given @c name.
|
---|
7279 | <note>
|
---|
7280 | The method returns an error if the given @c name does not
|
---|
7281 | correspond to any host network interface.
|
---|
7282 | </note>
|
---|
7283 | </desc>
|
---|
7284 | <param name="name" type="wstring" dir="in">
|
---|
7285 | <desc>Name of the host network interface to search for.</desc>
|
---|
7286 | </param>
|
---|
7287 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7288 | <desc>Found host network interface object.</desc>
|
---|
7289 | </param>
|
---|
7290 | </method>
|
---|
7291 | <method name="findHostNetworkInterfaceById">
|
---|
7292 | <desc>
|
---|
7293 | Searches through all host network interfaces for an interface with
|
---|
7294 | the given GUID.
|
---|
7295 | <note>
|
---|
7296 | The method returns an error if the given GUID does not
|
---|
7297 | correspond to any host network interface.
|
---|
7298 | </note>
|
---|
7299 | </desc>
|
---|
7300 | <param name="id" type="uuid" dir="in">
|
---|
7301 | <desc>GUID of the host network interface to search for.</desc>
|
---|
7302 | </param>
|
---|
7303 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7304 | <desc>Found host network interface object.</desc>
|
---|
7305 | </param>
|
---|
7306 | </method>
|
---|
7307 | <method name="findHostNetworkInterfacesOfType">
|
---|
7308 | <desc>
|
---|
7309 | Searches through all host network interfaces and returns a list of interfaces of the specified type
|
---|
7310 | </desc>
|
---|
7311 | <param name="type" type="HostNetworkInterfaceType" dir="in">
|
---|
7312 | <desc>type of the host network interfaces to search for.</desc>
|
---|
7313 | </param>
|
---|
7314 | <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
|
---|
7315 | <desc>Found host network interface objects.</desc>
|
---|
7316 | </param>
|
---|
7317 | </method>
|
---|
7318 |
|
---|
7319 | <method name="findUSBDeviceById">
|
---|
7320 | <desc>
|
---|
7321 | Searches for a USB device with the given UUID.
|
---|
7322 |
|
---|
7323 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7324 | Given @c id does not correspond to any USB device.
|
---|
7325 | </result>
|
---|
7326 |
|
---|
7327 | <see>IHostUSBDevice::id</see>
|
---|
7328 | </desc>
|
---|
7329 | <param name="id" type="uuid" dir="in">
|
---|
7330 | <desc>UUID of the USB device to search for.</desc>
|
---|
7331 | </param>
|
---|
7332 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7333 | <desc>Found USB device object.</desc>
|
---|
7334 | </param>
|
---|
7335 | </method>
|
---|
7336 |
|
---|
7337 | <method name="findUSBDeviceByAddress">
|
---|
7338 | <desc>
|
---|
7339 | Searches for a USB device with the given host address.
|
---|
7340 |
|
---|
7341 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7342 | Given @c name does not correspond to any USB device.
|
---|
7343 | </result>
|
---|
7344 |
|
---|
7345 | <see>IHostUSBDevice::address</see>
|
---|
7346 | </desc>
|
---|
7347 | <param name="name" type="wstring" dir="in">
|
---|
7348 | <desc>
|
---|
7349 | Address of the USB device (as assigned by the host) to
|
---|
7350 | search for.
|
---|
7351 | </desc>
|
---|
7352 | </param>
|
---|
7353 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7354 | <desc>Found USB device object.</desc>
|
---|
7355 | </param>
|
---|
7356 | </method>
|
---|
7357 |
|
---|
7358 | </interface>
|
---|
7359 |
|
---|
7360 | <!--
|
---|
7361 | // ISystemProperties
|
---|
7362 | /////////////////////////////////////////////////////////////////////////
|
---|
7363 | -->
|
---|
7364 |
|
---|
7365 | <interface
|
---|
7366 | name="ISystemProperties"
|
---|
7367 | extends="$unknown"
|
---|
7368 | uuid="0760e03f-06d0-481e-9f81-be43fef092ba"
|
---|
7369 | wsmap="managed"
|
---|
7370 | >
|
---|
7371 | <desc>
|
---|
7372 | The ISystemProperties interface represents global properties of the given
|
---|
7373 | VirtualBox installation.
|
---|
7374 |
|
---|
7375 | These properties define limits and default values for various attributes
|
---|
7376 | and parameters. Most of the properties are read-only, but some can be
|
---|
7377 | changed by a user.
|
---|
7378 | </desc>
|
---|
7379 |
|
---|
7380 | <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
|
---|
7381 | <desc>Minimum guest system memory in Megabytes.</desc>
|
---|
7382 | </attribute>
|
---|
7383 |
|
---|
7384 | <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
|
---|
7385 | <desc>Maximum guest system memory in Megabytes.</desc>
|
---|
7386 | </attribute>
|
---|
7387 |
|
---|
7388 | <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7389 | <desc>Minimum guest video memory in Megabytes.</desc>
|
---|
7390 | </attribute>
|
---|
7391 |
|
---|
7392 | <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7393 | <desc>Maximum guest video memory in Megabytes.</desc>
|
---|
7394 | </attribute>
|
---|
7395 |
|
---|
7396 | <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7397 | <desc>Minimum CPU count.</desc>
|
---|
7398 | </attribute>
|
---|
7399 |
|
---|
7400 | <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7401 | <desc>Maximum CPU count.</desc>
|
---|
7402 | </attribute>
|
---|
7403 |
|
---|
7404 | <attribute name="maxVDISize" type="unsigned long long" readonly="yes">
|
---|
7405 | <desc>Maximum size of a virtual disk image in Megabytes.</desc>
|
---|
7406 | </attribute>
|
---|
7407 |
|
---|
7408 | <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
|
---|
7409 | <desc>
|
---|
7410 | Number of network adapters associated with every
|
---|
7411 | <link to="IMachine"/> instance.
|
---|
7412 | </desc>
|
---|
7413 | </attribute>
|
---|
7414 |
|
---|
7415 | <attribute name="serialPortCount" type="unsigned long" readonly="yes">
|
---|
7416 | <desc>
|
---|
7417 | Number of serial ports associated with every
|
---|
7418 | <link to="IMachine"/> instance.
|
---|
7419 | </desc>
|
---|
7420 | </attribute>
|
---|
7421 |
|
---|
7422 | <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
|
---|
7423 | <desc>
|
---|
7424 | Number of parallel ports associated with every
|
---|
7425 | <link to="IMachine"/> instance.
|
---|
7426 | </desc>
|
---|
7427 | </attribute>
|
---|
7428 |
|
---|
7429 | <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
|
---|
7430 | <desc>
|
---|
7431 | Maximum device position in the boot order. This value corresponds
|
---|
7432 | to the total number of devices a machine can boot from, to make it
|
---|
7433 | possible to include all possible devices to the boot list.
|
---|
7434 | <see><link to="IMachine::setBootOrder"/></see>
|
---|
7435 | </desc>
|
---|
7436 | </attribute>
|
---|
7437 |
|
---|
7438 | <attribute name="defaultMachineFolder" type="wstring">
|
---|
7439 | <desc>
|
---|
7440 | Full path to the default directory used to create new or open
|
---|
7441 | existing machines when a settings file name contains no
|
---|
7442 | path.
|
---|
7443 |
|
---|
7444 | The initial value of this property is
|
---|
7445 | <tt><</tt><link to="IVirtualBox::homeFolder">
|
---|
7446 | VirtualBox_home</link><tt>>/Machines</tt>.
|
---|
7447 |
|
---|
7448 | <note>
|
---|
7449 | Setting this property to <tt>null</tt> will restore the
|
---|
7450 | initial value.
|
---|
7451 | </note>
|
---|
7452 | <note>
|
---|
7453 | When settings this property, the specified path can be
|
---|
7454 | absolute (full path) or relative
|
---|
7455 | to the <link to="IVirtualBox::homeFolder">
|
---|
7456 | VirtualBox home directory</link>.
|
---|
7457 | When reading this property, a full path is
|
---|
7458 | always returned.
|
---|
7459 | </note>
|
---|
7460 | <note>
|
---|
7461 | The specified path may not exist, it will be created
|
---|
7462 | when necessary.
|
---|
7463 | </note>
|
---|
7464 |
|
---|
7465 | <see>
|
---|
7466 | <link to="IVirtualBox::createMachine"/>,
|
---|
7467 | <link to="IVirtualBox::openMachine"/>
|
---|
7468 | </see>
|
---|
7469 | </desc>
|
---|
7470 | </attribute>
|
---|
7471 |
|
---|
7472 | <attribute name="defaultHardDiskFolder" type="wstring">
|
---|
7473 | <desc>
|
---|
7474 | Full path to the default directory used to create new or open existing
|
---|
7475 | virtual disks.
|
---|
7476 |
|
---|
7477 | This path is used when the storage unit of a hard disk is a regular file
|
---|
7478 | in the host's file system and only a file name that contains no path is
|
---|
7479 | given.
|
---|
7480 |
|
---|
7481 | The initial value of this property is
|
---|
7482 | <tt><</tt>
|
---|
7483 | <link to="IVirtualBox::homeFolder">VirtualBox_home</link>
|
---|
7484 | <tt>>/HardDisks</tt>.
|
---|
7485 |
|
---|
7486 | <note>
|
---|
7487 | Setting this property to <tt>null</tt> will restore the
|
---|
7488 | initial value.
|
---|
7489 | </note>
|
---|
7490 | <note>
|
---|
7491 | When settings this property, the specified path can be relative
|
---|
7492 | to the
|
---|
7493 | <link to="IVirtualBox::homeFolder">VirtualBox home directory</link> or
|
---|
7494 | absolute. When reading this property, a full path is
|
---|
7495 | always returned.
|
---|
7496 | </note>
|
---|
7497 | <note>
|
---|
7498 | The specified path may not exist, it will be created
|
---|
7499 | when necessary.
|
---|
7500 | </note>
|
---|
7501 |
|
---|
7502 | <see>
|
---|
7503 | IHardDisk,
|
---|
7504 | <link to="IVirtualBox::createHardDisk"/>,
|
---|
7505 | <link to="IVirtualBox::openHardDisk"/>,
|
---|
7506 | <link to="IMedium::location"/>
|
---|
7507 | </see>
|
---|
7508 | </desc>
|
---|
7509 | </attribute>
|
---|
7510 |
|
---|
7511 | <attribute name="hardDiskFormats" type="IHardDiskFormat" safearray="yes" readonly="yes">
|
---|
7512 | <desc>
|
---|
7513 | List of all hard disk storage formats supported by this VirtualBox
|
---|
7514 | installation.
|
---|
7515 |
|
---|
7516 | Keep in mind that the hard disk format identifier
|
---|
7517 | (<link to="IHardDiskFormat::id"/>) used in other API calls like
|
---|
7518 | <link to="IVirtualBox::createHardDisk"/> to refer to a particular
|
---|
7519 | hard disk format is a case-insensitive string. This means that, for
|
---|
7520 | example, all of the following strings:
|
---|
7521 | <pre>
|
---|
7522 | "VDI"
|
---|
7523 | "vdi"
|
---|
7524 | "VdI"</pre>
|
---|
7525 | refer to the same hard disk format.
|
---|
7526 |
|
---|
7527 | Note that the virtual hard disk framework is backend-based, therefore
|
---|
7528 | the list of supported formats depends on what backends are currently
|
---|
7529 | installed.
|
---|
7530 |
|
---|
7531 | <see>
|
---|
7532 | <link to="IHardDiskFormat"/>,
|
---|
7533 | </see>
|
---|
7534 | </desc>
|
---|
7535 | </attribute>
|
---|
7536 |
|
---|
7537 | <attribute name="defaultHardDiskFormat" type="wstring">
|
---|
7538 | <desc>
|
---|
7539 | Identifier of the default hard disk format used by VirtualBox.
|
---|
7540 |
|
---|
7541 | The hard disk format set by this attribute is used by VirtualBox
|
---|
7542 | when the hard disk format was not specified explicitly. One example is
|
---|
7543 | <link to="IVirtualBox::createHardDisk"/> with the <tt>null</tt>
|
---|
7544 | format argument. A more complex example is implicit creation of
|
---|
7545 | differencing hard disks when taking a snapshot of a virtual machine:
|
---|
7546 | this operation will try to use a format of the parent hard disk first
|
---|
7547 | and if this format does not support differencing hard disks the default
|
---|
7548 | format specified by this argument will be used.
|
---|
7549 |
|
---|
7550 | The list of supported hard disk formats may be obtained by the
|
---|
7551 | <link to="#hardDiskFormats"/> call. Note that the default hard disk
|
---|
7552 | format must have a capability to create differencing hard disks;
|
---|
7553 | otherwise opeartions that create hard disks implicitly may fail
|
---|
7554 | unexpectedly.
|
---|
7555 |
|
---|
7556 | The initial value of this property is <tt>VDI</tt> in the current
|
---|
7557 | version of the VirtualBox product, but may change in the future.
|
---|
7558 |
|
---|
7559 | <note>
|
---|
7560 | Setting this property to <tt>null</tt> will restore the
|
---|
7561 | initial value.
|
---|
7562 | </note>
|
---|
7563 |
|
---|
7564 | <see>
|
---|
7565 | <link to="#hardDiskFormats"/>,
|
---|
7566 | <link to="IHardDiskFormat::id"/>,
|
---|
7567 | <link to="IVirtualBox::createHardDisk"/>
|
---|
7568 | </see>
|
---|
7569 | </desc>
|
---|
7570 | </attribute>
|
---|
7571 |
|
---|
7572 | <attribute name="remoteDisplayAuthLibrary" type="wstring">
|
---|
7573 | <desc>
|
---|
7574 | Library that provides authentication for VRDP clients. The library
|
---|
7575 | is used if a virtual machine's authentication type is set to "external"
|
---|
7576 | in the VM RemoteDisplay configuration.
|
---|
7577 |
|
---|
7578 | The system library extension (".DLL" or ".so") must be omitted.
|
---|
7579 | A full path can be specified; if not, then the library must reside on the
|
---|
7580 | system's default library path.
|
---|
7581 |
|
---|
7582 | The default value of this property is <tt>VRDPAuth</tt>. There is a library
|
---|
7583 | of that name in one of the default VirtualBox library directories.
|
---|
7584 |
|
---|
7585 | For details about VirtualBox authentication libraries and how to implement
|
---|
7586 | them, please refer to the VirtualBox manual.
|
---|
7587 |
|
---|
7588 | <note>
|
---|
7589 | Setting this property to <tt>null</tt> will restore the
|
---|
7590 | initial value.
|
---|
7591 | </note>
|
---|
7592 | </desc>
|
---|
7593 | </attribute>
|
---|
7594 |
|
---|
7595 | <attribute name="webServiceAuthLibrary" type="wstring">
|
---|
7596 | <desc>
|
---|
7597 | Library that provides authentication for webservice clients. The library
|
---|
7598 | is used if a virtual machine's authentication type is set to "external"
|
---|
7599 | in the VM RemoteDisplay configuration and will be called from
|
---|
7600 | within the <link to="IWebsessionManager::logon" /> implementation.
|
---|
7601 |
|
---|
7602 | As opposed to <link to="ISystemProperties::remoteDisplayAuthLibrary" />,
|
---|
7603 | there is no per-VM setting for this, as the webservice is a global
|
---|
7604 | resource (if it is running). Only for this setting (for the webservice),
|
---|
7605 | setting this value to a literal "null" string disables authentication,
|
---|
7606 | meaning that <link to="IWebsessionManager::logon" /> will always succeed,
|
---|
7607 | no matter what user name and password are supplied.
|
---|
7608 |
|
---|
7609 | The initial value of this property is <tt>VRDPAuth</tt>,
|
---|
7610 | meaning that the webservice will use the same authentication
|
---|
7611 | library that is used by default for VBoxVRDP (again, see
|
---|
7612 | <link to="ISystemProperties::remoteDisplayAuthLibrary" />).
|
---|
7613 | The format and calling convention of authentication libraries
|
---|
7614 | is the same for the webservice as it is for VBoxVRDP.
|
---|
7615 |
|
---|
7616 | </desc>
|
---|
7617 | </attribute>
|
---|
7618 |
|
---|
7619 | <attribute name="HWVirtExEnabled" type="boolean">
|
---|
7620 | <desc>
|
---|
7621 | This specifies the default value for hardware virtualization
|
---|
7622 | extensions. If enabled, virtual machines will make use of
|
---|
7623 | hardware virtualization extensions such as Intel VT-x and
|
---|
7624 | AMD-V by default. This value can be overridden by each VM
|
---|
7625 | using their <link to="IMachine::HWVirtExEnabled" /> property.
|
---|
7626 | </desc>
|
---|
7627 | </attribute>
|
---|
7628 |
|
---|
7629 | <attribute name="LogHistoryCount" type="unsigned long">
|
---|
7630 | <desc>
|
---|
7631 | This value specifies how many old release log files are kept.
|
---|
7632 | </desc>
|
---|
7633 | </attribute>
|
---|
7634 | </interface>
|
---|
7635 |
|
---|
7636 | <!--
|
---|
7637 | // IGuest
|
---|
7638 | /////////////////////////////////////////////////////////////////////////
|
---|
7639 | -->
|
---|
7640 |
|
---|
7641 | <interface
|
---|
7642 | name="IGuestOSType" extends="$unknown"
|
---|
7643 | uuid="cfe9e64c-4430-435b-9e7c-e3d8e417bd58"
|
---|
7644 | wsmap="struct"
|
---|
7645 | >
|
---|
7646 | <desc>
|
---|
7647 | </desc>
|
---|
7648 |
|
---|
7649 | <attribute name="familyId" type="wstring" readonly="yes">
|
---|
7650 | <desc>Guest OS family identifier string.</desc>
|
---|
7651 | </attribute>
|
---|
7652 |
|
---|
7653 | <attribute name="familyDescription" type="wstring" readonly="yes">
|
---|
7654 | <desc>Human readable description of the guest OS family.</desc>
|
---|
7655 | </attribute>
|
---|
7656 |
|
---|
7657 | <attribute name="id" type="wstring" readonly="yes">
|
---|
7658 | <desc>Guest OS identifier string.</desc>
|
---|
7659 | </attribute>
|
---|
7660 |
|
---|
7661 | <attribute name="description" type="wstring" readonly="yes">
|
---|
7662 | <desc>Human readable description of the guest OS.</desc>
|
---|
7663 | </attribute>
|
---|
7664 |
|
---|
7665 | <attribute name="is64Bit" type="boolean" readonly="yes">
|
---|
7666 | <desc>Returns @c true if the given OS is 64-bit</desc>
|
---|
7667 | </attribute>
|
---|
7668 |
|
---|
7669 | <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
|
---|
7670 | <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
|
---|
7671 | </attribute>
|
---|
7672 |
|
---|
7673 | <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
|
---|
7674 | <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
|
---|
7675 | </attribute>
|
---|
7676 |
|
---|
7677 | <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
|
---|
7678 | <desc>Recommended RAM size in Megabytes.</desc>
|
---|
7679 | </attribute>
|
---|
7680 |
|
---|
7681 | <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
|
---|
7682 | <desc>Recommended video RAM size in Megabytes.</desc>
|
---|
7683 | </attribute>
|
---|
7684 |
|
---|
7685 | <attribute name="recommendedHDD" type="unsigned long" readonly="yes">
|
---|
7686 | <desc>Recommended hard disk size in Megabytes.</desc>
|
---|
7687 | </attribute>
|
---|
7688 |
|
---|
7689 | <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
|
---|
7690 | <desc>Returns recommended network adapter for this OS type.</desc>
|
---|
7691 | </attribute>
|
---|
7692 | </interface>
|
---|
7693 |
|
---|
7694 | <interface
|
---|
7695 | name="IGuest" extends="$unknown"
|
---|
7696 | uuid="d8556fca-81bc-12af-fca3-365528fa38ca"
|
---|
7697 |
|
---|
7698 | wsmap="suppress"
|
---|
7699 | >
|
---|
7700 | <desc>
|
---|
7701 | The IGuest interface represents information about the operating system
|
---|
7702 | running inside the virtual machine. Used in
|
---|
7703 | <link to="IConsole::guest"/>.
|
---|
7704 |
|
---|
7705 | IGuest provides information about the guest operating system, whether
|
---|
7706 | Guest Additions are installed and other OS-specific virtual machine
|
---|
7707 | properties.
|
---|
7708 | </desc>
|
---|
7709 |
|
---|
7710 | <attribute name="OSTypeId" type="wstring" readonly="yes">
|
---|
7711 | <desc>
|
---|
7712 | Identifier of the Guest OS type as reported by the Guest
|
---|
7713 | Additions.
|
---|
7714 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
7715 | an IGuestOSType object representing details about the given
|
---|
7716 | Guest OS type.
|
---|
7717 | <note>
|
---|
7718 | If Guest Additions are not installed, this value will be
|
---|
7719 | the same as <link to="IMachine::OSTypeId"/>.
|
---|
7720 | </note>
|
---|
7721 | </desc>
|
---|
7722 | </attribute>
|
---|
7723 |
|
---|
7724 | <attribute name="additionsActive" type="boolean" readonly="yes">
|
---|
7725 | <desc>
|
---|
7726 | Flag whether the Guest Additions are installed and active
|
---|
7727 | in which case their version will be returned by the
|
---|
7728 | <link to="#additionsVersion"/> property.
|
---|
7729 | </desc>
|
---|
7730 | </attribute>
|
---|
7731 |
|
---|
7732 | <attribute name="additionsVersion" type="wstring" readonly="yes">
|
---|
7733 | <desc>
|
---|
7734 | Version of the Guest Additions (3 decimal numbers separated
|
---|
7735 | by dots) or empty when the Additions are not installed. The
|
---|
7736 | Additions may also report a version but yet not be active as
|
---|
7737 | the version might be refused by VirtualBox (incompatible) or
|
---|
7738 | other failures occurred.
|
---|
7739 | </desc>
|
---|
7740 | </attribute>
|
---|
7741 |
|
---|
7742 | <attribute name="supportsSeamless" type="boolean" readonly="yes">
|
---|
7743 | <desc>
|
---|
7744 | Flag whether seamless guest display rendering (seamless desktop
|
---|
7745 | integration) is supported.
|
---|
7746 | </desc>
|
---|
7747 | </attribute>
|
---|
7748 |
|
---|
7749 | <attribute name="supportsGraphics" type="boolean" readonly="yes">
|
---|
7750 | <desc>
|
---|
7751 | Flag whether the guest is in graphics mode. If it is not, then
|
---|
7752 | seamless rendering will not work, resize hints are not immediately
|
---|
7753 | acted on and guest display resizes are probably not initiated by
|
---|
7754 | the guest additions.
|
---|
7755 | </desc>
|
---|
7756 | </attribute>
|
---|
7757 |
|
---|
7758 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
7759 | <desc>Guest system memory balloon size in megabytes.</desc>
|
---|
7760 | </attribute>
|
---|
7761 |
|
---|
7762 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
7763 | <desc>Interval to update guest statistics in seconds.</desc>
|
---|
7764 | </attribute>
|
---|
7765 |
|
---|
7766 | <method name="setCredentials">
|
---|
7767 | <desc>
|
---|
7768 | Store login credentials that can be queried by guest operating
|
---|
7769 | systems with Additions installed. The credentials are transient
|
---|
7770 | to the session and the guest may also choose to erase them. Note
|
---|
7771 | that the caller cannot determine whether the guest operating system
|
---|
7772 | has queried or made use of the credentials.
|
---|
7773 |
|
---|
7774 | <result name="VBOX_E_VM_ERROR">
|
---|
7775 | VMM device is not available.
|
---|
7776 | </result>
|
---|
7777 |
|
---|
7778 | </desc>
|
---|
7779 | <param name="userName" type="wstring" dir="in">
|
---|
7780 | <desc>User name string, can be empty</desc>
|
---|
7781 | </param>
|
---|
7782 | <param name="password" type="wstring" dir="in">
|
---|
7783 | <desc>Password string, can be empty</desc>
|
---|
7784 | </param>
|
---|
7785 | <param name="domain" type="wstring" dir="in">
|
---|
7786 | <desc>Domain name (guest logon scheme specific), can be empty</desc>
|
---|
7787 | </param>
|
---|
7788 | <param name="allowInteractiveLogon" type="boolean" dir="in">
|
---|
7789 | <desc>
|
---|
7790 | Flag whether the guest should alternatively allow the user to
|
---|
7791 | interactively specify different credentials. This flag might
|
---|
7792 | not be supported by all versions of the Additions.
|
---|
7793 | </desc>
|
---|
7794 | </param>
|
---|
7795 | </method>
|
---|
7796 |
|
---|
7797 | <method name="getStatistic">
|
---|
7798 | <desc>
|
---|
7799 | Query specified guest statistics as reported by the VirtualBox Additions.
|
---|
7800 | </desc>
|
---|
7801 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7802 | <desc>Virtual CPU id; not relevant for all statistic types</desc>
|
---|
7803 | </param>
|
---|
7804 | <param name="statistic" type="GuestStatisticType" dir="in">
|
---|
7805 | <desc>Statistic type.</desc>
|
---|
7806 | </param>
|
---|
7807 | <param name="statVal" type="unsigned long" dir="out">
|
---|
7808 | <desc>Statistics value</desc>
|
---|
7809 | </param>
|
---|
7810 | </method>
|
---|
7811 |
|
---|
7812 | </interface>
|
---|
7813 |
|
---|
7814 |
|
---|
7815 | <!--
|
---|
7816 | // IProgress
|
---|
7817 | /////////////////////////////////////////////////////////////////////////
|
---|
7818 | -->
|
---|
7819 |
|
---|
7820 | <interface
|
---|
7821 | name="IProgress" extends="$unknown"
|
---|
7822 | uuid="c4f94e6b-2273-446b-9539-4c05bb416fe7"
|
---|
7823 | wsmap="managed"
|
---|
7824 | >
|
---|
7825 | <desc>
|
---|
7826 | The IProgress interface is used to track and control
|
---|
7827 | asynchronous tasks within VirtualBox.
|
---|
7828 |
|
---|
7829 | An instance of this is returned every time VirtualBox starts
|
---|
7830 | an asynchronous task (in other words, a separate thread) which
|
---|
7831 | continues to run after a method call returns. For example,
|
---|
7832 | <link to="IConsole::saveState" />, which saves the state of
|
---|
7833 | a running virtual machine, can take a long time to complete.
|
---|
7834 | To be able to display a progress bar, a user interface such as
|
---|
7835 | the VirtualBox graphical user interface can use the IProgress
|
---|
7836 | object returned by that method.
|
---|
7837 |
|
---|
7838 | Note that IProgress is a "read-only" interface in the sense
|
---|
7839 | that only the VirtualBox internals behind the Main API can
|
---|
7840 | create and manipulate progress objects, whereas client code
|
---|
7841 | can only use the IProgress object to monitor a task's
|
---|
7842 | progress and, if <link to="#cancelable" /> is true,
|
---|
7843 | cancel the task by calling <link to="#cancel" />.
|
---|
7844 |
|
---|
7845 | A task represented by IProgress consists of either one or
|
---|
7846 | several sub-operations that run sequentially, one by one (see
|
---|
7847 | <link to="#operation" /> and <link to="#operationCount" />).
|
---|
7848 | Every operation is identified by a number (starting from 0)
|
---|
7849 | and has a separate description.
|
---|
7850 |
|
---|
7851 | You can find the individual percentage of completion of the current
|
---|
7852 | operation in <link to="#operationPercent" /> and the
|
---|
7853 | percentage of completion of the task as a whole
|
---|
7854 | in <link to="#percent" />.
|
---|
7855 |
|
---|
7856 | Similarly, you can wait for the completion of a particular
|
---|
7857 | operation via <link to="#waitForOperationCompletion" /> or
|
---|
7858 | for the completion of the whole task via
|
---|
7859 | <link to="#waitForCompletion" />.
|
---|
7860 | </desc>
|
---|
7861 |
|
---|
7862 | <attribute name="id" type="uuid" readonly="yes">
|
---|
7863 | <desc>ID of the task.</desc>
|
---|
7864 | </attribute>
|
---|
7865 |
|
---|
7866 | <attribute name="description" type="wstring" readonly="yes">
|
---|
7867 | <desc>Description of the task.</desc>
|
---|
7868 | </attribute>
|
---|
7869 |
|
---|
7870 | <attribute name="initiator" type="$unknown" readonly="yes">
|
---|
7871 | <desc>Initiator of the task.</desc>
|
---|
7872 | </attribute>
|
---|
7873 |
|
---|
7874 | <attribute name="cancelable" type="boolean" readonly="yes">
|
---|
7875 | <desc>Whether the task can be interrupted.</desc>
|
---|
7876 | </attribute>
|
---|
7877 |
|
---|
7878 | <attribute name="percent" type="unsigned long" readonly="yes">
|
---|
7879 | <desc>
|
---|
7880 | Current progress value of the task as a whole, in percent.
|
---|
7881 | This value depends on how many operations are already complete.
|
---|
7882 | Returns 100 if <link to="#completed" /> is true.
|
---|
7883 | </desc>
|
---|
7884 | </attribute>
|
---|
7885 |
|
---|
7886 | <attribute name="timeRemaining" type="long" readonly="yes">
|
---|
7887 | <desc>
|
---|
7888 | Estimated remaining time until the task completes, in
|
---|
7889 | seconds. Returns 0 once the task has completed; returns -1
|
---|
7890 | if the remaining time cannot be computed, in particular if
|
---|
7891 | the current progress is 0.
|
---|
7892 |
|
---|
7893 | Even if a value is returned, the estimate will be unreliable
|
---|
7894 | for low progress values. It will become more reliable as the
|
---|
7895 | task progresses; it is not recommended to display an ETA
|
---|
7896 | before at least 20% of a task have completed.
|
---|
7897 | </desc>
|
---|
7898 | </attribute>
|
---|
7899 |
|
---|
7900 | <attribute name="completed" type="boolean" readonly="yes">
|
---|
7901 | <desc>Whether the task has been completed.</desc>
|
---|
7902 | </attribute>
|
---|
7903 |
|
---|
7904 | <attribute name="canceled" type="boolean" readonly="yes">
|
---|
7905 | <desc>Whether the task has been canceled.</desc>
|
---|
7906 | </attribute>
|
---|
7907 |
|
---|
7908 | <attribute name="resultCode" type="result" readonly="yes">
|
---|
7909 | <desc>
|
---|
7910 | Result code of the progress task.
|
---|
7911 | Valid only if <link to="#completed"/> is true.
|
---|
7912 | </desc>
|
---|
7913 | </attribute>
|
---|
7914 |
|
---|
7915 | <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
7916 | <desc>
|
---|
7917 | Extended information about the unsuccessful result of the
|
---|
7918 | progress operation. May be NULL if no extended information
|
---|
7919 | is available.
|
---|
7920 | Valid only if <link to="#completed"/> is true and
|
---|
7921 | <link to="#resultCode"/> indicates a failure.
|
---|
7922 | </desc>
|
---|
7923 | </attribute>
|
---|
7924 |
|
---|
7925 | <attribute name="operationCount" type="unsigned long" readonly="yes">
|
---|
7926 | <desc>
|
---|
7927 | Number of sub-operations this task is divided into.
|
---|
7928 | Every task consists of at least one suboperation.
|
---|
7929 | </desc>
|
---|
7930 | </attribute>
|
---|
7931 |
|
---|
7932 | <attribute name="operation" type="unsigned long" readonly="yes">
|
---|
7933 | <desc>Number of the sub-operation being currently executed.</desc>
|
---|
7934 | </attribute>
|
---|
7935 |
|
---|
7936 | <attribute name="operationDescription" type="wstring" readonly="yes">
|
---|
7937 | <desc>
|
---|
7938 | Description of the sub-operation being currently executed.
|
---|
7939 | </desc>
|
---|
7940 | </attribute>
|
---|
7941 |
|
---|
7942 | <attribute name="operationPercent" type="unsigned long" readonly="yes">
|
---|
7943 | <desc>Progress value of the current sub-operation only, in percent.</desc>
|
---|
7944 | </attribute>
|
---|
7945 |
|
---|
7946 | <method name="waitForCompletion">
|
---|
7947 | <desc>
|
---|
7948 | Waits until the task is done (including all sub-operations)
|
---|
7949 | with a given timeout in milliseconds; specify -1 for an indefinite wait.
|
---|
7950 |
|
---|
7951 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7952 | Failed to wait for task completion.
|
---|
7953 | </result>
|
---|
7954 | </desc>
|
---|
7955 |
|
---|
7956 | <param name="timeout" type="long" dir="in">
|
---|
7957 | <desc>
|
---|
7958 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
7959 | </desc>
|
---|
7960 | </param>
|
---|
7961 | </method>
|
---|
7962 |
|
---|
7963 | <method name="waitForOperationCompletion">
|
---|
7964 | <desc>
|
---|
7965 | Waits until the given operation is done with a given timeout in
|
---|
7966 | milliseconds; specify -1 for an indefinite wait.
|
---|
7967 |
|
---|
7968 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7969 | Failed to wait for operation completion.
|
---|
7970 | </result>
|
---|
7971 |
|
---|
7972 | </desc>
|
---|
7973 | <param name="operation" type="unsigned long" dir="in">
|
---|
7974 | <desc>
|
---|
7975 | Number of the operation to wait for.
|
---|
7976 | Must be less than <link to="#operationCount"/>.
|
---|
7977 | </desc>
|
---|
7978 | </param>
|
---|
7979 | <param name="timeout" type="long" dir="in">
|
---|
7980 | <desc>
|
---|
7981 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
7982 | </desc>
|
---|
7983 | </param>
|
---|
7984 | </method>
|
---|
7985 |
|
---|
7986 | <method name="cancel">
|
---|
7987 | <desc>
|
---|
7988 | Cancels the task.
|
---|
7989 | <note>
|
---|
7990 | If <link to="#cancelable"/> is <tt>false</tt>, then
|
---|
7991 | this method will fail.
|
---|
7992 | </note>
|
---|
7993 |
|
---|
7994 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
7995 | Operation cannot be canceled.
|
---|
7996 | </result>
|
---|
7997 |
|
---|
7998 | </desc>
|
---|
7999 | </method>
|
---|
8000 |
|
---|
8001 | </interface>
|
---|
8002 |
|
---|
8003 |
|
---|
8004 | <!--
|
---|
8005 | // ISnapshot
|
---|
8006 | /////////////////////////////////////////////////////////////////////////
|
---|
8007 | -->
|
---|
8008 |
|
---|
8009 | <interface
|
---|
8010 | name="ISnapshot" extends="$unknown"
|
---|
8011 | uuid="5db6b1d9-c76b-4424-a6f4-8257f642d6ea"
|
---|
8012 | wsmap="managed"
|
---|
8013 | >
|
---|
8014 | <desc>
|
---|
8015 | The ISnapshot interface represents a snapshot of the virtual
|
---|
8016 | machine.
|
---|
8017 |
|
---|
8018 | The <i>snapshot</i> stores all the information about a virtual
|
---|
8019 | machine necessary to bring it to exactly the same state as it was at
|
---|
8020 | the time of taking the snapshot. The snapshot includes:
|
---|
8021 |
|
---|
8022 | <ul>
|
---|
8023 | <li>all settings of the virtual machine (i.e. its hardware
|
---|
8024 | configuration: RAM size, attached hard disks, etc.)
|
---|
8025 | </li>
|
---|
8026 | <li>the execution state of the virtual machine (memory contents,
|
---|
8027 | CPU state, etc.).
|
---|
8028 | </li>
|
---|
8029 | </ul>
|
---|
8030 |
|
---|
8031 | Snapshots can be <i>offline</i> (taken when the VM is powered off)
|
---|
8032 | or <i>online</i> (taken when the VM is running). The execution
|
---|
8033 | state of the offline snapshot is called a <i>zero execution state</i>
|
---|
8034 | (it doesn't actually contain any information about memory contents
|
---|
8035 | or the CPU state, assuming that all hardware is just powered off).
|
---|
8036 |
|
---|
8037 | <h3>Snapshot branches</h3>
|
---|
8038 |
|
---|
8039 | Snapshots can be chained. Chained snapshots form a branch where
|
---|
8040 | every next snapshot is based on the previous one. This chaining is
|
---|
8041 | mostly related to hard disk branching (see <link to="IHardDisk"/>
|
---|
8042 | description). This means that every time a new snapshot is created,
|
---|
8043 | a new differencing hard disk is implicitly created for all normal
|
---|
8044 | hard disks attached to the given virtual machine. This allows to
|
---|
8045 | fully restore hard disk contents when the machine is later reverted
|
---|
8046 | to a particular snapshot.
|
---|
8047 |
|
---|
8048 | In the current implementation, multiple snapshot branches within one
|
---|
8049 | virtual machine are not allowed. Every machine has a single branch,
|
---|
8050 | and <link to="IConsole::takeSnapshot"/> operation adds a new
|
---|
8051 | snapshot to the top of that branch.
|
---|
8052 |
|
---|
8053 | Existing snapshots can be discarded using
|
---|
8054 | <link to="IConsole::discardSnapshot"/>.
|
---|
8055 |
|
---|
8056 | <h3>Current snapshot</h3>
|
---|
8057 |
|
---|
8058 | Every virtual machine has a current snapshot, identified by
|
---|
8059 | <link to="IMachine::currentSnapshot"/>. This snapshot is used as
|
---|
8060 | a base for the <i>current machine state</i> (see below), to the effect
|
---|
8061 | that all normal hard disks of the machine and its execution
|
---|
8062 | state are based on this snapshot.
|
---|
8063 |
|
---|
8064 | In the current implementation, the current snapshot is always the
|
---|
8065 | last taken snapshot (i.e. the head snapshot on the branch) and it
|
---|
8066 | cannot be changed.
|
---|
8067 |
|
---|
8068 | The current snapshot is <tt>null</tt> if the machine doesn't have
|
---|
8069 | snapshots at all; in this case the current machine state is just
|
---|
8070 | current settings of this machine plus its current execution state.
|
---|
8071 |
|
---|
8072 | <h3>Current machine state</h3>
|
---|
8073 |
|
---|
8074 | The current machine state is what represented by IMachine instances got
|
---|
8075 | directly from IVirtualBox
|
---|
8076 | using <link
|
---|
8077 | to="IVirtualBox::getMachine">getMachine()</link>, <link
|
---|
8078 | to="IVirtualBox::findMachine">findMachine()</link>, etc. (as opposed
|
---|
8079 | to instances returned by <link to="ISnapshot::machine"/>). This state
|
---|
8080 | is always used when the machine is <link to="IConsole::powerUp"> powered
|
---|
8081 | on</link>.
|
---|
8082 |
|
---|
8083 | The current machine state also includes the current execution state.
|
---|
8084 | If the machine is being currently executed
|
---|
8085 | (<link to="IMachine::state"/> is <link to="MachineState_Running"/>
|
---|
8086 | and above), its execution state is just what's happening now.
|
---|
8087 | If it is powered off (<link to="MachineState_PoweredOff"/> or
|
---|
8088 | <link to="MachineState_Aborted"/>), it has a zero execution state.
|
---|
8089 | If the machine is saved (<link to="MachineState_Saved"/>), its
|
---|
8090 | execution state is what saved in the execution state file
|
---|
8091 | (<link to="IMachine::stateFilePath"/>).
|
---|
8092 |
|
---|
8093 | If the machine is in the saved state, then, next time it is powered
|
---|
8094 | on, its execution state will be fully restored from the saved state
|
---|
8095 | file and the execution will continue from the point where the state
|
---|
8096 | was saved.
|
---|
8097 |
|
---|
8098 | Similarly to snapshots, the current machine state can be discarded
|
---|
8099 | using <link to="IConsole::discardCurrentState"/>.
|
---|
8100 |
|
---|
8101 | <h3>Taking and discarding snapshots</h3>
|
---|
8102 |
|
---|
8103 | The table below briefly explains the meaning of every snapshot
|
---|
8104 | operation:
|
---|
8105 |
|
---|
8106 | <table>
|
---|
8107 | <tr><th>Operation</th><th>Meaning</th><th>Remarks</th></tr>
|
---|
8108 |
|
---|
8109 | <tr><td><link to="IConsole::takeSnapshot"/></td>
|
---|
8110 |
|
---|
8111 | <td>Save the current state of the virtual machine, including all
|
---|
8112 | settings, contents of normal hard disks and the current modifications
|
---|
8113 | to immutable hard disks (for online snapshots)</td>
|
---|
8114 |
|
---|
8115 | <td>The current state is not changed (the machine will continue
|
---|
8116 | execution if it is being executed when the snapshot is
|
---|
8117 | taken)</td></tr>
|
---|
8118 |
|
---|
8119 | <tr><td><link to="IConsole::discardSnapshot"/></td>
|
---|
8120 |
|
---|
8121 | <td>Forget the state of the virtual machine stored in the snapshot:
|
---|
8122 | dismiss all saved settings and delete the saved execution state (for
|
---|
8123 | online snapshots)</td>
|
---|
8124 |
|
---|
8125 | <td>Other snapshots (including child snapshots, if any) and the
|
---|
8126 | current state are not directly affected</td></tr>
|
---|
8127 |
|
---|
8128 | <tr><td><link to="IConsole::discardCurrentState"/></td>
|
---|
8129 |
|
---|
8130 | <td>Restore the current state of the virtual machine from the state
|
---|
8131 | stored in the current snapshot, including all settings and hard disk
|
---|
8132 | contents</td>
|
---|
8133 |
|
---|
8134 | <td>The current state of the machine existed prior to this operation
|
---|
8135 | is lost</td></tr>
|
---|
8136 |
|
---|
8137 | <tr><td><link to="IConsole::discardCurrentSnapshotAndState"/></td>
|
---|
8138 |
|
---|
8139 | <td>Completely revert the virtual machine to the state it was in
|
---|
8140 | before the current snapshot has been taken</td>
|
---|
8141 |
|
---|
8142 | <td>The current state, as well as the current snapshot, are
|
---|
8143 | lost</td></tr>
|
---|
8144 |
|
---|
8145 | </table>
|
---|
8146 |
|
---|
8147 | </desc>
|
---|
8148 |
|
---|
8149 | <attribute name="id" type="uuid" readonly="yes">
|
---|
8150 | <desc>UUID of the snapshot.</desc>
|
---|
8151 | </attribute>
|
---|
8152 |
|
---|
8153 | <attribute name="name" type="wstring">
|
---|
8154 | <desc>Short name of the snapshot.</desc>
|
---|
8155 | </attribute>
|
---|
8156 |
|
---|
8157 | <attribute name="description" type="wstring">
|
---|
8158 | <desc>Optional description of the snapshot.</desc>
|
---|
8159 | </attribute>
|
---|
8160 |
|
---|
8161 | <attribute name="timeStamp" type="long long" readonly="yes">
|
---|
8162 | <desc>
|
---|
8163 | Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
|
---|
8164 | </desc>
|
---|
8165 | </attribute>
|
---|
8166 |
|
---|
8167 | <attribute name="online" type="boolean" readonly="yes">
|
---|
8168 | <desc>
|
---|
8169 | <tt>true</tt> if this snapshot is an online snapshot and
|
---|
8170 | <tt>false</tt> otherwise.
|
---|
8171 |
|
---|
8172 | <note>
|
---|
8173 | When this attribute is <tt>true</tt>, the
|
---|
8174 | <link to="IMachine::stateFilePath"/> attribute of the
|
---|
8175 | <link to="#machine"/> object associated with this snapshot
|
---|
8176 | will point to the saved state file. Otherwise, it will be
|
---|
8177 | <tt>null</tt>.
|
---|
8178 | </note>
|
---|
8179 | </desc>
|
---|
8180 | </attribute>
|
---|
8181 |
|
---|
8182 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
8183 | <desc>
|
---|
8184 | Virtual machine this snapshot is taken on. This object
|
---|
8185 | stores all settings the machine had when taking this snapshot.
|
---|
8186 | <note>
|
---|
8187 | The returned machine object is immutable, i.e. no
|
---|
8188 | any settings can be changed.
|
---|
8189 | </note>
|
---|
8190 | </desc>
|
---|
8191 | </attribute>
|
---|
8192 |
|
---|
8193 | <attribute name="parent" type="ISnapshot" readonly="yes">
|
---|
8194 | <desc>
|
---|
8195 | Parent snapshot (a snapshot this one is based on).
|
---|
8196 | <note>
|
---|
8197 | It's not an error to read this attribute on a snapshot
|
---|
8198 | that doesn't have a parent -- a null object will be
|
---|
8199 | returned to indicate this.
|
---|
8200 | </note>
|
---|
8201 | </desc>
|
---|
8202 | </attribute>
|
---|
8203 |
|
---|
8204 | <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
|
---|
8205 | <desc>
|
---|
8206 | Child snapshots (all snapshots having this one as a parent).
|
---|
8207 | <note>
|
---|
8208 | In the current implementation, there can be only one
|
---|
8209 | child snapshot, or no children at all, meaning this is the
|
---|
8210 | last (head) snapshot.
|
---|
8211 | </note>
|
---|
8212 | </desc>
|
---|
8213 | </attribute>
|
---|
8214 |
|
---|
8215 | </interface>
|
---|
8216 |
|
---|
8217 |
|
---|
8218 | <!--
|
---|
8219 | // IMedia
|
---|
8220 | /////////////////////////////////////////////////////////////////////////
|
---|
8221 | -->
|
---|
8222 |
|
---|
8223 | <enum
|
---|
8224 | name="MediaState"
|
---|
8225 | uuid="8b86e03c-2f1c-412a-8fbd-326f62701200"
|
---|
8226 | >
|
---|
8227 | <desc>
|
---|
8228 | Virtual media state.
|
---|
8229 | <see>IMedia</see>
|
---|
8230 | </desc>
|
---|
8231 |
|
---|
8232 | <const name="NotCreated" value="0">
|
---|
8233 | <desc>
|
---|
8234 | Associated media storage does not exist (either was not created yet or
|
---|
8235 | was deleted).
|
---|
8236 | </desc>
|
---|
8237 | </const>
|
---|
8238 | <const name="Created" value="1">
|
---|
8239 | <desc>
|
---|
8240 | Associated storage exists and accessible.
|
---|
8241 | </desc>
|
---|
8242 | </const>
|
---|
8243 | <const name="LockedRead" value="2">
|
---|
8244 | <desc>
|
---|
8245 | Media is locked for reading, no data modification is possible.
|
---|
8246 | </desc>
|
---|
8247 | </const>
|
---|
8248 | <const name="LockedWrite" value="3">
|
---|
8249 | <desc>
|
---|
8250 | Media is locked for writing, no concurrent data reading or modification
|
---|
8251 | is possible.
|
---|
8252 | </desc>
|
---|
8253 | </const>
|
---|
8254 | <const name="Inaccessible" value="4">
|
---|
8255 | <desc>
|
---|
8256 | Associated media storage is not accessible.
|
---|
8257 | </desc>
|
---|
8258 | </const>
|
---|
8259 | <const name="Creating" value="5">
|
---|
8260 | <desc>
|
---|
8261 | Associated media storage is being created.
|
---|
8262 | </desc>
|
---|
8263 | </const>
|
---|
8264 | <const name="Deleting" value="6">
|
---|
8265 | <desc>
|
---|
8266 | Associated media storage is being deleted.
|
---|
8267 | </desc>
|
---|
8268 | </const>
|
---|
8269 | </enum>
|
---|
8270 |
|
---|
8271 | <interface
|
---|
8272 | name="IMedium" extends="$unknown"
|
---|
8273 | uuid="a7fb3bfb-c180-4274-bae4-7fbc89046e13"
|
---|
8274 | wsmap="managed"
|
---|
8275 | >
|
---|
8276 | <desc>
|
---|
8277 | The IMedium interface is a common interface for all objects representing
|
---|
8278 | virtual media such as hard disks, CD/DVD images and floppy images.
|
---|
8279 |
|
---|
8280 | Each medium is associated with a storage unit (such as a file on the host
|
---|
8281 | computer or a network resource) that holds actual data. The location of
|
---|
8282 | the storage unit is represented by the #location attribute. The value of
|
---|
8283 | this attribute is media type dependent.
|
---|
8284 |
|
---|
8285 | The exact media type may be determined by querying the appropriate
|
---|
8286 | interface such as:
|
---|
8287 | <ul>
|
---|
8288 | <li>IHardDisk (virtual hard disks)</li>
|
---|
8289 | <li>IDVDImage (standard CD/DVD ISO image files)</li>
|
---|
8290 | <li>IFloppyImage (raw floppy image files)</li>
|
---|
8291 | </ul>
|
---|
8292 |
|
---|
8293 | Existing media are opened using the following methods, depending on the
|
---|
8294 | media type:
|
---|
8295 | <ul>
|
---|
8296 | <li><link to="IVirtualBox::openHardDisk"/></li>
|
---|
8297 | <li><link to="IVirtualBox::openDVDImage"/></li>
|
---|
8298 | <li><link to="IVirtualBox::openFloppyImage"/></li>
|
---|
8299 | </ul>
|
---|
8300 |
|
---|
8301 | New hard disk media are created using the
|
---|
8302 | <link to="IVirtualBox::createHardDisk"/> method. CD/DVD and floppy
|
---|
8303 | images are created outside VirtualBox, usually by storing a copy
|
---|
8304 | of the real medium of the corresponding type in a regular file.
|
---|
8305 |
|
---|
8306 | <h3>Known Media</h3>
|
---|
8307 |
|
---|
8308 | When an existing medium gets opened for the first time, it gets
|
---|
8309 | automatically remembered by the given VirtualBox installation or, in other
|
---|
8310 | words, becomes a <i>known medium</i>. Known media are stored in the media
|
---|
8311 | registry transparently maintained by VirtualBox and stored in settings
|
---|
8312 | files so that this registry is preserved when VirtualBox is not running.
|
---|
8313 |
|
---|
8314 | Newly created virtual hard disks get remembered only when the associated
|
---|
8315 | storage unit is actually created (see IHardDisk for more details).
|
---|
8316 |
|
---|
8317 | All known media can be enumerated using
|
---|
8318 | <link to="IVirtualBox::hardDisks"/>,
|
---|
8319 | <link to="IVirtualBox::DVDImages"/> and
|
---|
8320 | <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
|
---|
8321 | quickly found by UUID using <link to="IVirtualBox::getHardDisk"/>
|
---|
8322 | and similar methods or by location using
|
---|
8323 | <link to="IVirtualBox::findHardDisk"/> and similar methods.
|
---|
8324 |
|
---|
8325 | Only known media can be attached to virtual machines.
|
---|
8326 |
|
---|
8327 | Removing known media from the media registry is performed when the given
|
---|
8328 | medium is closed using the <link to="#close"/> method or when its
|
---|
8329 | associated storage unit is deleted (only for hard disks).
|
---|
8330 |
|
---|
8331 | <h3>Accessibility Checks</h3>
|
---|
8332 |
|
---|
8333 | The given medium (with the created storage unit) is considered to be
|
---|
8334 | <i>accessible</i> when its storage unit can be read.
|
---|
8335 | Accessible media are indicated by the <link to="MediaState_Created"/>
|
---|
8336 | value of the <link to="#state"/> attribute. When the storage unit cannot
|
---|
8337 | be read (for example, because it is located on a disconnected network
|
---|
8338 | resource, or was accidentally deleted outside VirtualBox), the medium is
|
---|
8339 | considered to be <i>inaccessible</i> which is indicated by the
|
---|
8340 | <link to="MediaState_Inaccessible"/> state. The details about the reason
|
---|
8341 | of being inaccessible can be obtained using the
|
---|
8342 | <link to="#lastAccessError"/> attribute.
|
---|
8343 |
|
---|
8344 | A new accessibility check is performed each time the <link to="#state"/>
|
---|
8345 | attribute is read. Please note that this check may take long time (several
|
---|
8346 | seconds or even minutes, depending on the storage unit location and
|
---|
8347 | format), and will block the calling thread until finished. For this
|
---|
8348 | reason, it is recommended to never read this attribute on the main UI
|
---|
8349 | thread to avoid making the UI unresponsive.
|
---|
8350 |
|
---|
8351 | Note that when VirtualBox starts up (e.g. the VirtualBox object gets
|
---|
8352 | created for the first time), all known media are in the
|
---|
8353 | <link to="MediaState_Inaccessible"/> state but the value of the <link
|
---|
8354 | to="#lastAccessError"/> attribute is <tt>null</tt> because no actual
|
---|
8355 | accessibility check is made on startup. This is done to make the
|
---|
8356 | VirtualBox object ready for serving requests as
|
---|
8357 | fast as possible and let the end-user application decide if it needs to
|
---|
8358 | check media accessibility right away or not.
|
---|
8359 | </desc>
|
---|
8360 |
|
---|
8361 | <attribute name="id" type="uuid" readonly="yes">
|
---|
8362 | <desc>
|
---|
8363 | UUID of the medium. For a newly created medium, this value is a randomly
|
---|
8364 | generated UUID.
|
---|
8365 |
|
---|
8366 | <note>
|
---|
8367 | For media in one of MediaState_NotCreated, MediaState_Creating or
|
---|
8368 | MediaState_Deleting states, the value of this property is undefined
|
---|
8369 | and will most likely be an empty UUID.
|
---|
8370 | </note>
|
---|
8371 | </desc>
|
---|
8372 | </attribute>
|
---|
8373 |
|
---|
8374 | <attribute name="description" type="wstring">
|
---|
8375 | <desc>
|
---|
8376 | Optional description of the medium. For newly created media, the value
|
---|
8377 | of this attribute value is <tt>null</tt>.
|
---|
8378 |
|
---|
8379 | Media types that don't support this attribute will return E_NOTIMPL in
|
---|
8380 | attempt to get or set this attribute's value.
|
---|
8381 |
|
---|
8382 | <note>
|
---|
8383 | For some storage types, reading this attribute may return an outdated
|
---|
8384 | (last known) value when <link to="#state"/> is <link
|
---|
8385 | to="MediaState_Inaccessible"/> or <link
|
---|
8386 | to="MediaState_LockedWrite"/> because the value of this attribute is
|
---|
8387 | stored within the storage unit itself. Also note that changing the
|
---|
8388 | attribute value is not possible in such case, as well as when the
|
---|
8389 | medium is the <link to="MediaState_LockedRead"/> state.
|
---|
8390 | </note>
|
---|
8391 | </desc>
|
---|
8392 | </attribute>
|
---|
8393 |
|
---|
8394 | <attribute name="state" type="MediaState" readonly="yes">
|
---|
8395 | <desc>
|
---|
8396 | Current media state. Inspect <link to="MediaState"/> values for details.
|
---|
8397 |
|
---|
8398 | Reading this attribute may take a long time because an accessibility
|
---|
8399 | check of the storage unit is performed each time the attribute is read.
|
---|
8400 | This check may cause a significant delay if the storage unit of the
|
---|
8401 | given medium is, for example, a file located on a network share which is
|
---|
8402 | not currently accessible due to connectivity problems -- the call will
|
---|
8403 | not return until a timeout interval defined by the host OS for this
|
---|
8404 | operation expires.
|
---|
8405 |
|
---|
8406 | If the last known state of the medium is <link to="MediaState_Created"/>
|
---|
8407 | and the accessibility check fails then the state would be set to
|
---|
8408 | <link to="MediaState_Inaccessible"/> and <link to="#lastAccessError"/>
|
---|
8409 | may be used to get more details about the failure. If the state of the
|
---|
8410 | medium is <link to="MediaState_LockedRead"/> or
|
---|
8411 | <link to="MediaState_LockedWrite"/> then it remains the same, and a
|
---|
8412 | non-null value of <link to="#lastAccessError"/> will indicate a failed
|
---|
8413 | accessibility check in this case.
|
---|
8414 |
|
---|
8415 | Note that not all media states are applicable to all media types.
|
---|
8416 | For example, states <link to="MediaState_NotCreated"/>,
|
---|
8417 | <link to="MediaState_LockedWrite"/>, <link to="MediaState_Creating"/>,
|
---|
8418 | <link to="MediaState_Deleting"/> are meaningless for IDVDImage and
|
---|
8419 | IFloppyImage media.
|
---|
8420 | </desc>
|
---|
8421 | </attribute>
|
---|
8422 |
|
---|
8423 | <attribute name="location" type="wstring">
|
---|
8424 | <desc>
|
---|
8425 | Location of the storage unit holding media data.
|
---|
8426 |
|
---|
8427 | The format of the location string is media type specific. For media
|
---|
8428 | types using regular files in a host's file system, the location
|
---|
8429 | string is the full file name.
|
---|
8430 |
|
---|
8431 | Some media types may support changing the storage unit location by
|
---|
8432 | simply changing the value of this property. If this operation is not
|
---|
8433 | supported, the implementation will return E_NOTIMPL in attempt to set
|
---|
8434 | this attribute's value.
|
---|
8435 |
|
---|
8436 | When setting a value of the location attribute which is a regular file
|
---|
8437 | in the host's file system, the given file name may be either relative to
|
---|
8438 | the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
|
---|
8439 | absolute. Note that if the given location specification does not contain
|
---|
8440 | the file extension part then a proper default extension will be
|
---|
8441 | automatically appended by the implementation depending on the media type.
|
---|
8442 | </desc>
|
---|
8443 | </attribute>
|
---|
8444 |
|
---|
8445 | <attribute name="name" type="wstring" readonly="yes">
|
---|
8446 | <desc>
|
---|
8447 | Name of the storage unit holding media data.
|
---|
8448 |
|
---|
8449 | The returned string is a short version of the <link to="#location"/>
|
---|
8450 | attribute that is suitable for representing the medium in situations
|
---|
8451 | where the full location specification is too long (such as lists
|
---|
8452 | and comboboxes in GUI frontends). This string is also used by frontends
|
---|
8453 | to sort the media list alphabetically when needed.
|
---|
8454 |
|
---|
8455 | For example, for locations that are regular files in the host's file
|
---|
8456 | system, the value of this attribute is just the file name (+ extension),
|
---|
8457 | without the path specification.
|
---|
8458 |
|
---|
8459 | Note that as opposed to the <link to="#location"/> attribute, the name
|
---|
8460 | attribute will not necessary be unique for a list of media of the
|
---|
8461 | given type and format.
|
---|
8462 | </desc>
|
---|
8463 | </attribute>
|
---|
8464 |
|
---|
8465 | <attribute name="size" type="unsigned long long" readonly="yes">
|
---|
8466 | <desc>
|
---|
8467 | Physical size of the storage unit used to hold media data (in bytes).
|
---|
8468 |
|
---|
8469 | <note>
|
---|
8470 | For media whose <link to="#state"/> is <link
|
---|
8471 | to="MediaState_Inaccessible"/>, the value of this property is the
|
---|
8472 | last known size. For <link to="MediaState_NotCreated"/> media,
|
---|
8473 | the returned value is zero.
|
---|
8474 | </note>
|
---|
8475 | </desc>
|
---|
8476 | </attribute>
|
---|
8477 |
|
---|
8478 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
8479 | <desc>
|
---|
8480 | Text message that represents the result of the last accessibility
|
---|
8481 | check.
|
---|
8482 |
|
---|
8483 | Accessibility checks are performed each time the <link to="#state"/>
|
---|
8484 | attribute is read. A @c null string is returned if the last
|
---|
8485 | accessibility check was successful. A non-null string indicates a
|
---|
8486 | failure and should normally describe a reason of the failure (for
|
---|
8487 | example, a file read error).
|
---|
8488 | </desc>
|
---|
8489 | </attribute>
|
---|
8490 |
|
---|
8491 | <attribute name="machineIds" type="uuid" safearray="yes" readonly="yes">
|
---|
8492 | <desc>
|
---|
8493 | Array of UUIDs of all machines this medium is attached to.
|
---|
8494 |
|
---|
8495 | A <tt>null</tt> array is returned if this medium is not attached to any
|
---|
8496 | machine or to any machine's snapshot.
|
---|
8497 |
|
---|
8498 | <note>
|
---|
8499 | The returned array will include a machine even if this medium is not
|
---|
8500 | attached to that machine in the current state but attached to it in
|
---|
8501 | one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
|
---|
8502 | details.
|
---|
8503 | </note>
|
---|
8504 | </desc>
|
---|
8505 | </attribute>
|
---|
8506 |
|
---|
8507 | <method name="getSnapshotIds">
|
---|
8508 | <desc>
|
---|
8509 | Returns an array of UUIDs of all snapshots of the given machine where
|
---|
8510 | this medium is attached to.
|
---|
8511 |
|
---|
8512 | If the medium is attached to the machine in the current state, then the
|
---|
8513 | first element in the array will always be the ID of the queried machine
|
---|
8514 | (i.e. the value equal to the @c machineId argument), followed by
|
---|
8515 | snapshot IDs (if any).
|
---|
8516 |
|
---|
8517 | If the medium is not attached to the machine in the current state, then
|
---|
8518 | the array will contain only snapshot IDs.
|
---|
8519 |
|
---|
8520 | The returned array may be <tt>null</tt> if this medium is not attached
|
---|
8521 | to the given machine at all, neither in the current state nor in one of
|
---|
8522 | the snapshots.
|
---|
8523 | </desc>
|
---|
8524 | <param name="machineId" type="uuid" dir="in">
|
---|
8525 | <desc>
|
---|
8526 | UUID of the machine to query.
|
---|
8527 | </desc>
|
---|
8528 | </param>
|
---|
8529 | <param name="snapshotIds" type="uuid" safearray="yes" dir="return">
|
---|
8530 | <desc>
|
---|
8531 | Array of snapshot UUIDs of the given machine using this medium.
|
---|
8532 | </desc>
|
---|
8533 | </param>
|
---|
8534 | </method>
|
---|
8535 |
|
---|
8536 | <method name="lockRead">
|
---|
8537 | <desc>
|
---|
8538 | Locks this medium for reading.
|
---|
8539 |
|
---|
8540 | The read lock is shared: many clients can simultaneously lock the
|
---|
8541 | same media for reading unless it is already locked for writing (see
|
---|
8542 | <link to="#lockWrite"/>) in which case an error is returned.
|
---|
8543 |
|
---|
8544 | When the medium is locked for reading, it cannot be modified
|
---|
8545 | from within VirtualBox. This means that any method that changes
|
---|
8546 | the properties of this medium or contents of the storage unit
|
---|
8547 | will return an error (unless explicitly stated otherwise) and
|
---|
8548 | that an attempt to start a virtual machine that wants to modify
|
---|
8549 | the medium will also fail.
|
---|
8550 |
|
---|
8551 | When the virtual machine is started up, it locks for reading all
|
---|
8552 | media it uses in read-only mode. If some media cannot be locked
|
---|
8553 | for reading, the startup procedure will fail.
|
---|
8554 |
|
---|
8555 | The medium locked for reading must be unlocked using the <link
|
---|
8556 | to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
|
---|
8557 | can be nested and must be followed by the same number of paired
|
---|
8558 | <link to="#unlockRead"/> calls.
|
---|
8559 |
|
---|
8560 | This method sets the media state to <link
|
---|
8561 | to="MediaState_LockedRead"/> on success. The state prior to
|
---|
8562 | this call must be <link to="MediaState_Created"/>, <link
|
---|
8563 | to="MediaState_Inaccessible"/> or <link
|
---|
8564 | to="MediaState_LockedRead"/>. As you can see, inaccessible
|
---|
8565 | media can be locked too. This is not an error; this method
|
---|
8566 | performs a logical lock that prevents modifications of this
|
---|
8567 | media through the VirtualBox API, not a physical lock of the
|
---|
8568 | underlying storage unit.
|
---|
8569 |
|
---|
8570 | This method returns the current state of the medium
|
---|
8571 | <b>before</b> the operation.
|
---|
8572 |
|
---|
8573 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8574 | Invalid media state (e.g. not created, locked, inaccessible,
|
---|
8575 | creating, deleting).
|
---|
8576 | </result>
|
---|
8577 |
|
---|
8578 | </desc>
|
---|
8579 | <param name="state" type="MediaState" dir="return">
|
---|
8580 | <desc>
|
---|
8581 | State of the medium after the operation.
|
---|
8582 | </desc>
|
---|
8583 | </param>
|
---|
8584 | </method>
|
---|
8585 |
|
---|
8586 | <method name="unlockRead">
|
---|
8587 | <desc>
|
---|
8588 | Cancels the read lock previously set by <link to="#lockRead"/>.
|
---|
8589 |
|
---|
8590 | For both, success and failure, this method returns the current state
|
---|
8591 | of the medium <b>after</b> the operation.
|
---|
8592 |
|
---|
8593 | See <link to="#lockRead"/> for more details.
|
---|
8594 |
|
---|
8595 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8596 | Medium not locked for reading.
|
---|
8597 | </result>
|
---|
8598 |
|
---|
8599 | </desc>
|
---|
8600 | <param name="state" type="MediaState" dir="return">
|
---|
8601 | <desc>
|
---|
8602 | State of the medium after the operation.
|
---|
8603 | </desc>
|
---|
8604 | </param>
|
---|
8605 | </method>
|
---|
8606 |
|
---|
8607 | <method name="lockWrite">
|
---|
8608 | <desc>
|
---|
8609 | Locks this medium for writing.
|
---|
8610 |
|
---|
8611 | The write lock, as opposed to <link to="#lockRead"/>, is
|
---|
8612 | exclusive: there may be only one client holding a write lock
|
---|
8613 | and there may be no read locks while the write lock is held.
|
---|
8614 |
|
---|
8615 | When the medium is locked for writing, it cannot be modified
|
---|
8616 | from within VirtualBox and it is not guaranteed that the values
|
---|
8617 | of its properties are up-to-date. Any method that changes the
|
---|
8618 | properties of this medium or contents of the storage unit will
|
---|
8619 | return an error (unless explicitly stated otherwise) and an
|
---|
8620 | attempt to start a virtual machine wanting to modify or to
|
---|
8621 | read the medium will fail.
|
---|
8622 |
|
---|
8623 | When the virtual machine is started up, it locks for writing all
|
---|
8624 | media it uses to write data to. If any medium could not be locked
|
---|
8625 | for writing, the startup procedure will fail.
|
---|
8626 |
|
---|
8627 | The medium locked for writing must be unlocked using the <link
|
---|
8628 | to="#unlockWrite"/> method. Calls to <link to="#lockWrite"/>
|
---|
8629 | can <b>not</b> be nested and must be followed by a<link
|
---|
8630 | to="#unlockWrite"/> call before the next lockWrite call.
|
---|
8631 |
|
---|
8632 | This method sets the media state to <link
|
---|
8633 | to="MediaState_LockedWrite"/> on success. The state prior to
|
---|
8634 | this call must be <link to="MediaState_Created"/> or <link
|
---|
8635 | to="MediaState_Inaccessible"/>. As you can see, inaccessible
|
---|
8636 | media can be locked too. This is not an error; this method
|
---|
8637 | performs a logical lock preventing modifications of this
|
---|
8638 | media through the VirtualBox API, not a physical lock of the
|
---|
8639 | underlying storage unit.
|
---|
8640 |
|
---|
8641 | For both, success and failure, this method returns the current
|
---|
8642 | state of the medium <b>before</b> the operation.
|
---|
8643 |
|
---|
8644 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8645 | Invalid media state (e.g. not created, locked, inaccessible,
|
---|
8646 | creating, deleting).
|
---|
8647 | </result>
|
---|
8648 |
|
---|
8649 | </desc>
|
---|
8650 | <param name="state" type="MediaState" dir="return">
|
---|
8651 | <desc>
|
---|
8652 | State of the medium after the operation.
|
---|
8653 | </desc>
|
---|
8654 | </param>
|
---|
8655 | </method>
|
---|
8656 |
|
---|
8657 | <method name="unlockWrite">
|
---|
8658 | <desc>
|
---|
8659 | Cancels the write lock previously set by <link to="#lockWrite"/>.
|
---|
8660 |
|
---|
8661 | For both, success and failure, this method returns the current
|
---|
8662 | state of the medium <b>after</b> the operation.
|
---|
8663 |
|
---|
8664 | See <link to="#lockWrite"/> for more details.
|
---|
8665 |
|
---|
8666 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8667 | Medium not locked for writing.
|
---|
8668 | </result>
|
---|
8669 |
|
---|
8670 | </desc>
|
---|
8671 | <param name="state" type="MediaState" dir="return">
|
---|
8672 | <desc>
|
---|
8673 | State of the medium after the operation.
|
---|
8674 | </desc>
|
---|
8675 | </param>
|
---|
8676 | </method>
|
---|
8677 |
|
---|
8678 | <method name="close">
|
---|
8679 | <desc>
|
---|
8680 | Closes this medium.
|
---|
8681 |
|
---|
8682 | The hard disk must not be attached to any known virtual machine
|
---|
8683 | and must not have any known child hard disks, otherwise the
|
---|
8684 | operation will fail.
|
---|
8685 |
|
---|
8686 | When the hard disk is successfully closed, it gets removed from
|
---|
8687 | the list of remembered hard disks, but its storage unit is not
|
---|
8688 | deleted. In particular, this means that this hard disk can be
|
---|
8689 | later opened again using the <link
|
---|
8690 | to="IVirtualBox::openHardDisk"/> call.
|
---|
8691 |
|
---|
8692 | Note that after this method successfully returns, the given hard
|
---|
8693 | disk object becomes uninitialized. This means that any attempt
|
---|
8694 | to call any of its methods or attributes will fail with the
|
---|
8695 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
|
---|
8696 |
|
---|
8697 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8698 | Invalid media state (other than not created, created or
|
---|
8699 | inaccessible).
|
---|
8700 | </result>
|
---|
8701 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
8702 | Medium attached to virtual machine.
|
---|
8703 | </result>
|
---|
8704 | <result name="VBOX_E_FILE_ERROR">
|
---|
8705 | Settings file not accessible.
|
---|
8706 | </result>
|
---|
8707 | <result name="VBOX_E_XML_ERROR">
|
---|
8708 | Could not parse the settings file.
|
---|
8709 | </result>
|
---|
8710 |
|
---|
8711 | </desc>
|
---|
8712 | </method>
|
---|
8713 |
|
---|
8714 | </interface>
|
---|
8715 |
|
---|
8716 |
|
---|
8717 | <!--
|
---|
8718 | // IHardDisk
|
---|
8719 | /////////////////////////////////////////////////////////////////////////
|
---|
8720 | -->
|
---|
8721 |
|
---|
8722 | <enum
|
---|
8723 | name="HardDiskType"
|
---|
8724 | uuid="a348fafd-a64e-4643-ba65-eb3896bd7e0a"
|
---|
8725 | >
|
---|
8726 | <desc>
|
---|
8727 | Virtual hard disk type.
|
---|
8728 | <see>IHardDisk</see>
|
---|
8729 | </desc>
|
---|
8730 |
|
---|
8731 | <const name="Normal" value="0">
|
---|
8732 | <desc>
|
---|
8733 | Normal hard disk (attached directly or indirectly, preserved
|
---|
8734 | when taking snapshots).
|
---|
8735 | </desc>
|
---|
8736 | </const>
|
---|
8737 | <const name="Immutable" value="1">
|
---|
8738 | <desc>
|
---|
8739 | Immutable hard disk (attached indirectly, changes are wiped out
|
---|
8740 | after powering off the virtual machine).
|
---|
8741 | </desc>
|
---|
8742 | </const>
|
---|
8743 | <const name="Writethrough" value="2">
|
---|
8744 | <desc>
|
---|
8745 | Write through hard disk (attached directly, ignored when
|
---|
8746 | taking snapshots).
|
---|
8747 | </desc>
|
---|
8748 | </const>
|
---|
8749 | </enum>
|
---|
8750 |
|
---|
8751 | <enum
|
---|
8752 | name="HardDiskVariant"
|
---|
8753 | uuid="eb7fc6b3-ae23-4c5d-a1f6-e3522dd1efb0"
|
---|
8754 | >
|
---|
8755 | <desc>
|
---|
8756 | Virtual hard disk image variant. More than one flag may be set.
|
---|
8757 | <see>IHardDisk</see>
|
---|
8758 | </desc>
|
---|
8759 |
|
---|
8760 | <const name="Standard" value="0">
|
---|
8761 | <desc>
|
---|
8762 | No particular variant requested, results in using the backend default.
|
---|
8763 | </desc>
|
---|
8764 | </const>
|
---|
8765 | <const name="VmdkSplit2G" value="0x01">
|
---|
8766 | <desc>
|
---|
8767 | VMDK image split in chunks of less than 2GByte.
|
---|
8768 | </desc>
|
---|
8769 | </const>
|
---|
8770 | <const name="VmdkStreamOptimized" value="0x04">
|
---|
8771 | <desc>
|
---|
8772 | VMDK streamOptimized image. Special import/export format which is
|
---|
8773 | read-only/append-only.
|
---|
8774 | </desc>
|
---|
8775 | </const>
|
---|
8776 | <const name="VmdkESX" value="0x08">
|
---|
8777 | <desc>
|
---|
8778 | VMDK format variant used on ESX products.
|
---|
8779 | </desc>
|
---|
8780 | </const>
|
---|
8781 | <const name="Fixed" value="0x10000">
|
---|
8782 | <desc>
|
---|
8783 | Fixed image. Only allowed for base images.
|
---|
8784 | </desc>
|
---|
8785 | </const>
|
---|
8786 | <const name="Diff" value="0x20000">
|
---|
8787 | <desc>
|
---|
8788 | Fixed image. Only allowed for base images.
|
---|
8789 | </desc>
|
---|
8790 | </const>
|
---|
8791 | </enum>
|
---|
8792 |
|
---|
8793 | <interface
|
---|
8794 | name="IHardDiskAttachment" extends="$unknown"
|
---|
8795 | uuid="b1dd04bb-93c0-4ad3-a9cf-82316e595836"
|
---|
8796 | wsmap="struct"
|
---|
8797 | >
|
---|
8798 | <desc>
|
---|
8799 | The IHardDiskAttachment interface represents a hard disk attachment of a
|
---|
8800 | virtual machine.
|
---|
8801 |
|
---|
8802 | Every hard disk attachment specifies a slot of the virtual hard disk
|
---|
8803 | controller and a virtual hard disk attached to this slot.
|
---|
8804 |
|
---|
8805 | The array of hard disk attachments is returned by
|
---|
8806 | <link to="IMachine::hardDiskAttachments"/>.
|
---|
8807 | </desc>
|
---|
8808 | <attribute name="hardDisk" type="IHardDisk" readonly="yes">
|
---|
8809 | <desc>Hard disk object associated with this attachment.</desc>
|
---|
8810 | </attribute>
|
---|
8811 |
|
---|
8812 | <attribute name="controller" type="wstring" readonly="yes">
|
---|
8813 | <desc>Interface bus of this attachment.</desc>
|
---|
8814 | </attribute>
|
---|
8815 |
|
---|
8816 | <attribute name="port" type="long" readonly="yes">
|
---|
8817 | <desc>Port number of this attachment.</desc>
|
---|
8818 | </attribute>
|
---|
8819 |
|
---|
8820 | <attribute name="device" type="long" readonly="yes">
|
---|
8821 | <desc>Device slot number of this attachment.</desc>
|
---|
8822 | </attribute>
|
---|
8823 |
|
---|
8824 | </interface>
|
---|
8825 |
|
---|
8826 | <interface
|
---|
8827 | name="IHardDisk" extends="IMedium"
|
---|
8828 | uuid="91648dc6-bb19-46bf-9e1c-4bf5b960c8e2"
|
---|
8829 | wsmap="managed"
|
---|
8830 | >
|
---|
8831 | <desc>
|
---|
8832 | The IHardDisk interface represents a virtual hard disk drive
|
---|
8833 | used by a virtual machine. This is a subclass of <link to="IMedium" />; see remarks there.
|
---|
8834 |
|
---|
8835 | Virtual hard disk objects virtualize the hard disk hardware and look like
|
---|
8836 | regular hard disks for the guest OS running inside the virtual machine.
|
---|
8837 |
|
---|
8838 | <h3>Hard Disk Types</h3>
|
---|
8839 |
|
---|
8840 | There are three types of hard disks:
|
---|
8841 | <link to="HardDiskType_Normal">Normal</link>,
|
---|
8842 | <link to="HardDiskType_Immutable">Immutable</link> and
|
---|
8843 | <link to="HardDiskType_Writethrough">Writethrough</link>. The type of the
|
---|
8844 | hard disk defines how the hard disk is attached to a virtual machine and
|
---|
8845 | what happens when a <link to="ISnapshot">snapshot</link> of the virtual
|
---|
8846 | machine with the attached hard disk is taken. The type of the hard disk is
|
---|
8847 | defined by the <link to="#type"/> attribute.
|
---|
8848 |
|
---|
8849 | All hard disks can be also divided in two big groups: <i>base</i> hard
|
---|
8850 | disks and <i>differencing</i> hard disks. A base hard disk contains all
|
---|
8851 | sectors of the hard disk data in its storage unit and therefore can be
|
---|
8852 | used independently. On the contrary, a differencing hard disk contains
|
---|
8853 | only some part of the hard disk data (a subset of sectors) and needs
|
---|
8854 | another hard disk to get access to the missing sectors of data. This
|
---|
8855 | another hard disk is called a <i>parent</i> hard disk and defines a hard
|
---|
8856 | disk to which this differencing hard disk is known to be <i>linked to</i>.
|
---|
8857 | The parent hard disk may be itself a differencing hard disk. This
|
---|
8858 | way, differencing hard disks form a linked hard disk chain. This chain
|
---|
8859 | always ends with the base hard disk which is sometimes referred to as the
|
---|
8860 | root hard disk of this chain. Note that several differencing hard disks
|
---|
8861 | may be linked to the same parent hard disk. This way, all known hard disks
|
---|
8862 | form a hard disk tree which is based on their parent-child relationship.
|
---|
8863 |
|
---|
8864 | Differencing hard disks can be distinguished from base hard disks by
|
---|
8865 | querying the <link to="#parent"/> attribute: base hard disks do not have
|
---|
8866 | parents they would depend on, so the value of this attribute is always
|
---|
8867 | <tt>null</tt> for them. Using this attribute, it is possible to walk up
|
---|
8868 | the hard disk tree (from the child hard disk to its parent). It is also
|
---|
8869 | possible to walk down the tree using the <link to="#children"/>
|
---|
8870 | attribute.
|
---|
8871 |
|
---|
8872 | Note that the type of all differencing hard disks is
|
---|
8873 | <link to="HardDiskType_Normal">Normal</link>; all other values are
|
---|
8874 | meaningless for them. Base hard disks may be of any type.
|
---|
8875 |
|
---|
8876 | <h3>Creating Hard Disks</h3>
|
---|
8877 |
|
---|
8878 | New base hard disks are created using
|
---|
8879 | <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
|
---|
8880 | opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
|
---|
8881 | disks are usually implicitly created by VirtualBox when needed but may
|
---|
8882 | also be created explicitly using <link to="#createDiffStorage"/>.
|
---|
8883 |
|
---|
8884 | After the hard disk is successfully created (including the storage unit)
|
---|
8885 | or opened, it becomes a known hard disk (remembered in the internal media
|
---|
8886 | registry). Known hard disks can be attached to a virtual machine, accessed
|
---|
8887 | through <link to="IVirtualBox::getHardDisk"/> and
|
---|
8888 | <link to="IVirtualBox::findHardDisk"/> methods or enumerated using the
|
---|
8889 | <link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
|
---|
8890 |
|
---|
8891 | The following methods, besides <link to="IMedium::close"/>,
|
---|
8892 | automatically remove the hard disk from the media registry:
|
---|
8893 | <ul>
|
---|
8894 | <li><link to="#deleteStorage"/></li>
|
---|
8895 | <li><link to="#mergeTo"/></li>
|
---|
8896 | </ul>
|
---|
8897 |
|
---|
8898 | If the storage unit of the hard disk is a regular file in the host's
|
---|
8899 | file system then the rules stated in the description of the
|
---|
8900 | <link to="IMedium::location"/> attribute apply when setting its value. In
|
---|
8901 | addition, a plain file name without any path may be given, in which case
|
---|
8902 | the <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
|
---|
8903 | folder</link> will be prepended to it.
|
---|
8904 |
|
---|
8905 | <h4>Automatic composition of the file name part</h4>
|
---|
8906 |
|
---|
8907 | Another extension to the <link to="IMedium::location"/> attribute is that
|
---|
8908 | there is a possibility to cause VirtualBox to compose a unique value for
|
---|
8909 | the file name part of the location using the UUID of the hard disk. This
|
---|
8910 | applies only to hard disks in <link to="MediaState_NotCreated"/> state,
|
---|
8911 | e.g. before the storage unit is created, and works as follows. You set the
|
---|
8912 | value of the <link to="IMedium::location"/> attribute to a location
|
---|
8913 | specification which only contains the path specification but not the file
|
---|
8914 | name part and ends with either a forward slash or a backslash character.
|
---|
8915 | In response, VirtualBox will generate a new UUID for the hard disk and
|
---|
8916 | compose the file name using the following pattern:
|
---|
8917 | <pre>
|
---|
8918 | <path>/{<uuid>}.<ext>
|
---|
8919 | </pre>
|
---|
8920 | where <tt><path></tt> is the supplied path specification,
|
---|
8921 | <tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
|
---|
8922 | is the default extension for the storage format of this hard disk. After
|
---|
8923 | that, you may call any of the methods that create a new hard disk storage
|
---|
8924 | unit and they will use the generated UUID and file name.
|
---|
8925 |
|
---|
8926 | <h3>Attaching Hard Disks</h3>
|
---|
8927 |
|
---|
8928 | Hard disks are attached to virtual machines using the
|
---|
8929 | <link to="IMachine::attachHardDisk"/> method and detached using the
|
---|
8930 | <link to="IMachine::detachHardDisk"/> method. Depending on their
|
---|
8931 | <link to="#type"/>, hard disks are attached either
|
---|
8932 | <i>directly</i> or <i>indirectly</i>.
|
---|
8933 |
|
---|
8934 | When a hard disk is being attached directly, it is associated with the
|
---|
8935 | virtual machine and used for hard disk operations when the machine is
|
---|
8936 | running. When a hard disk is being attached indirectly, a new differencing
|
---|
8937 | hard disk linked to it is implicitly created and this differencing hard
|
---|
8938 | disk is associated with the machine and used for hard disk operations.
|
---|
8939 | This also means that if <link to="IMachine::attachHardDisk"/> performs
|
---|
8940 | a direct attachment then the same hard disk will be returned in response
|
---|
8941 | to the subsequent <link to="IMachine::getHardDisk"/> call; however if
|
---|
8942 | an indirect attachment is performed then
|
---|
8943 | <link to="IMachine::getHardDisk"/> will return the implicitly created
|
---|
8944 | differencing hard disk, not the original one passed to <link
|
---|
8945 | to="IMachine::attachHardDisk"/>. The following table shows the
|
---|
8946 | dependency of the attachment type on the hard disk type:
|
---|
8947 |
|
---|
8948 | <table>
|
---|
8949 | <tr>
|
---|
8950 | <th>Hard Disk Type</th>
|
---|
8951 | <th>Direct or Indirect?</th>
|
---|
8952 | </tr>
|
---|
8953 | <tr>
|
---|
8954 | <td>Normal (Base)</td>
|
---|
8955 | <td>
|
---|
8956 | Normal base hard disks that do not have children (i.e. differencing
|
---|
8957 | hard disks linked to them) and that are not already attached to
|
---|
8958 | virtual machines in snapshots are attached <b>directly</b>.
|
---|
8959 | Otherwise, they are attached <b>indirectly</b> because having
|
---|
8960 | dependent children or being part of the snapshot makes it impossible
|
---|
8961 | to modify hard disk contents without breaking the integrity of the
|
---|
8962 | dependent party. The <link to="#readOnly"/> attribute allows to
|
---|
8963 | quickly determine the kind of the attachment for the given hard
|
---|
8964 | disk. Note that if a normal base hard disk is to be indirectly
|
---|
8965 | attached to a virtual machine with snapshots then a special
|
---|
8966 | procedure called <i>smart attachment</i> is performed (see below).
|
---|
8967 | </td>
|
---|
8968 | </tr>
|
---|
8969 | <tr>
|
---|
8970 | <td>Normal (Differencing)</td>
|
---|
8971 | <td>
|
---|
8972 | Differencing hard disks are like normal base hard disks: attached
|
---|
8973 | <b>directly</b> if they do not have children and are not attached to
|
---|
8974 | virtual machines in snapshots, and <b>indirectly</b> otherwise. Note
|
---|
8975 | that the smart attachment procedure is never performed for
|
---|
8976 | differencing hard disks.
|
---|
8977 | </td>
|
---|
8978 | </tr>
|
---|
8979 | <tr>
|
---|
8980 | <td>Immutable</td>
|
---|
8981 | <td>
|
---|
8982 | Immutable hard disks are always attached <b>indirectly</b> because
|
---|
8983 | they are designed to be non-writable. If an immutable hard disk is
|
---|
8984 | attached to a virtual machine with snapshots then a special
|
---|
8985 | procedure called smart attachment is performed (see below).
|
---|
8986 | </td>
|
---|
8987 | </tr>
|
---|
8988 | <tr>
|
---|
8989 | <td>Writethrough</td>
|
---|
8990 | <td>
|
---|
8991 | Writethrough hard disks are always attached <b>directly</b>, also as
|
---|
8992 | designed. This also means that writethrough hard disks cannot have
|
---|
8993 | other hard disks linked to them at all.
|
---|
8994 | </td>
|
---|
8995 | </tr>
|
---|
8996 | </table>
|
---|
8997 |
|
---|
8998 | Note that the same hard disk, regardless of its type, may be attached to
|
---|
8999 | more than one virtual machine at a time. In this case, the machine that is
|
---|
9000 | started first gains exclusive access to the hard disk and attempts to
|
---|
9001 | start other machines having this hard disk attached will fail until the
|
---|
9002 | first machine is powered down.
|
---|
9003 |
|
---|
9004 | Detaching hard disks is performed in a <i>deferred</i> fashion. This means
|
---|
9005 | that the given hard disk remains associated with the given machine after a
|
---|
9006 | successful <link to="IMachine::detachHardDisk"/> call until
|
---|
9007 | <link to="IMachine::saveSettings"/> is called to save all changes to
|
---|
9008 | machine settings to disk. This deferring is necessary to guarantee that
|
---|
9009 | the hard disk configuration may be restored at any time by a call to
|
---|
9010 | <link to="IMachine::discardSettings"/> before the settings
|
---|
9011 | are saved (committed).
|
---|
9012 |
|
---|
9013 | Note that if <link to="IMachine::discardSettings"/> is called after
|
---|
9014 | indirectly attaching some hard disks to the machine but before a call to
|
---|
9015 | <link to="IMachine::saveSettings"/> is made, it will implicitly delete
|
---|
9016 | all differencing hard disks implicitly created by
|
---|
9017 | <link to="IMachine::attachHardDisk"/> for these indirect attachments.
|
---|
9018 | Such implicitly created hard disks will also be immediately deleted when
|
---|
9019 | detached explicitly using the <link to="IMachine::detachHardDisk"/>
|
---|
9020 | call if it is made before <link to="IMachine::saveSettings"/>. This
|
---|
9021 | implicit deletion is safe because newly created differencing hard
|
---|
9022 | disks do not contain any user data.
|
---|
9023 |
|
---|
9024 | However, keep in mind that detaching differencing hard disks that were
|
---|
9025 | implicitly created by <link to="IMachine::attachHardDisk"/>
|
---|
9026 | before the last <link to="IMachine::saveSettings"/> call will
|
---|
9027 | <b>not</b> implicitly delete them as they may already contain some data
|
---|
9028 | (for example, as a result of virtual machine execution). If these hard
|
---|
9029 | disks are no more necessary, the caller can always delete them explicitly
|
---|
9030 | using <link to="#deleteStorage"/> after they are actually de-associated
|
---|
9031 | from this machine by the <link to="IMachine::saveSettings"/> call.
|
---|
9032 |
|
---|
9033 | <h3>Smart Attachment</h3>
|
---|
9034 |
|
---|
9035 | When normal base or immutable hard disks are indirectly attached to a
|
---|
9036 | virtual machine then some additional steps are performed to make sure the
|
---|
9037 | virtual machine will have the most recent "view" of the hard disk being
|
---|
9038 | attached. These steps include walking through the machine's snapshots
|
---|
9039 | starting from the current one and going through ancestors up to the first
|
---|
9040 | snapshot. Hard disks attached to the virtual machine in all
|
---|
9041 | of the encountered snapshots are checked whether they are descendants of
|
---|
9042 | the given normal base or immutable hard disk. The first found child (which
|
---|
9043 | is the differencing hard disk) will be used instead of the normal base or
|
---|
9044 | immutable hard disk as a parent for creating a new differencing hard disk
|
---|
9045 | that will be actually attached to the machine. And only if no descendants
|
---|
9046 | are found or if the virtual machine does not have any snapshots then the
|
---|
9047 | normal base or immutable hard disk will be used itself as a parent for
|
---|
9048 | this differencing hard disk.
|
---|
9049 |
|
---|
9050 | It is easier to explain what smart attachment does using the
|
---|
9051 | following example:
|
---|
9052 | <pre>
|
---|
9053 | BEFORE attaching B.vdi: AFTER attaching B.vdi:
|
---|
9054 |
|
---|
9055 | Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
|
---|
9056 | Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
|
---|
9057 | Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
|
---|
9058 | Snapshot 4 (none) Snapshot 4 (none)
|
---|
9059 | CurState (none) CurState (D3->D2.vdi)
|
---|
9060 |
|
---|
9061 | NOT
|
---|
9062 | ...
|
---|
9063 | CurState (D3->B.vdi)
|
---|
9064 | </pre>
|
---|
9065 | The first column is the virtual machine configuration before the base hard
|
---|
9066 | disk <tt>B.vdi</tt> is attached, the second column shows the machine after
|
---|
9067 | this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
|
---|
9068 | mean that the hard disk that is actually attached to the machine is a
|
---|
9069 | differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
|
---|
9070 | another hard disk, <tt>B.vdi</tt>.
|
---|
9071 |
|
---|
9072 | As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
|
---|
9073 | from the machine before taking Snapshot 4. Later, after Snapshot 4 was
|
---|
9074 | taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
|
---|
9075 | dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
|
---|
9076 | it cannot be attached directly and needs an indirect attachment (i.e.
|
---|
9077 | implicit creation of a new differencing hard disk). Due to the smart
|
---|
9078 | attachment procedure, the new differencing hard disk
|
---|
9079 | (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
|
---|
9080 | <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
|
---|
9081 | <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
|
---|
9082 | machine.
|
---|
9083 |
|
---|
9084 | Note that if there is more than one descendant hard disk of the given base
|
---|
9085 | hard disk found in a snapshot, and there is an exact device, channel and
|
---|
9086 | bus match, then this exact match will be used. Otherwise, the youngest
|
---|
9087 | descendant will be picked up.
|
---|
9088 |
|
---|
9089 | There is one more important aspect of the smart attachment procedure which
|
---|
9090 | is not related to snapshots at all. Before walking through the snapshots
|
---|
9091 | as described above, the backup copy of the current list of hard disk
|
---|
9092 | attachment is searched for descendants. This backup copy is created when
|
---|
9093 | the hard disk configuration is changed for the first time after the last
|
---|
9094 | <link to="IMachine::saveSettings"/> call and used by
|
---|
9095 | <link to="IMachine::discardSettings"/> to undo the recent hard disk
|
---|
9096 | changes. When such a descendant is found in this backup copy, it will be
|
---|
9097 | simply re-attached back, without creating a new differencing hard disk for
|
---|
9098 | it. This optimization is necessary to make it possible to re-attach the
|
---|
9099 | base or immutable hard disk to a different bus, channel or device slot
|
---|
9100 | without losing the contents of the differencing hard disk actually
|
---|
9101 | attached to the machine in place of it.
|
---|
9102 | </desc>
|
---|
9103 |
|
---|
9104 | <attribute name="format" type="wstring" readonly="yes">
|
---|
9105 | <desc>
|
---|
9106 | Storage format of this hard disk.
|
---|
9107 |
|
---|
9108 | The value of this attribute is a string that specifies a backend used to
|
---|
9109 | store hard disk data. The storage format is defined when you create a
|
---|
9110 | new hard disk or automatically detected when you open an existing hard
|
---|
9111 | disk medium, and cannot be changed later.
|
---|
9112 |
|
---|
9113 | The list of all storage formats supported by this VirtualBox
|
---|
9114 | installation can be obtained using
|
---|
9115 | <link to="ISystemProperties::hardDiskFormats"/>.
|
---|
9116 | </desc>
|
---|
9117 | </attribute>
|
---|
9118 |
|
---|
9119 | <attribute name="type" type="HardDiskType">
|
---|
9120 | <desc>
|
---|
9121 | Type (role) of this hard disk.
|
---|
9122 |
|
---|
9123 | The following constraints apply when changing the value of this
|
---|
9124 | attribute:
|
---|
9125 | <ul>
|
---|
9126 | <li>If a hard disk is attached to a virtual machine (either in the
|
---|
9127 | current state or in one of the snapshots), its type cannot be
|
---|
9128 | changed.
|
---|
9129 | </li>
|
---|
9130 | <li>As long as the hard disk has children, its type cannot be set
|
---|
9131 | to <link to="HardDiskType_Writethrough"/>.
|
---|
9132 | </li>
|
---|
9133 | <li>The type of all differencing hard disks is
|
---|
9134 | <link to="HardDiskType_Normal"/> and cannot be changed.
|
---|
9135 | </li>
|
---|
9136 | </ul>
|
---|
9137 |
|
---|
9138 | The type of a newly created or opened hard disk is set to
|
---|
9139 | <link to="HardDiskType_Normal"/>.
|
---|
9140 | </desc>
|
---|
9141 | </attribute>
|
---|
9142 |
|
---|
9143 | <attribute name="parent" type="IHardDisk" readonly="yes">
|
---|
9144 | <desc>
|
---|
9145 | Parent of this hard disk (a hard disk this hard disk is directly based
|
---|
9146 | on).
|
---|
9147 |
|
---|
9148 | Only differencing hard disks have parents. For base (non-differencing)
|
---|
9149 | hard disks, <tt>null</tt> is returned.
|
---|
9150 | </desc>
|
---|
9151 | </attribute>
|
---|
9152 |
|
---|
9153 | <attribute name="children" type="IHardDisk" safearray="yes" readonly="yes">
|
---|
9154 | <desc>
|
---|
9155 | Children of this hard disk (all differencing hard disks directly based
|
---|
9156 | on this hard disk). A <tt>null</tt> array is returned if this hard disk
|
---|
9157 | does not have any children.
|
---|
9158 | </desc>
|
---|
9159 | </attribute>
|
---|
9160 |
|
---|
9161 | <attribute name="root" type="IHardDisk" readonly="yes">
|
---|
9162 | <desc>
|
---|
9163 | Root hard disk of this hard disk.
|
---|
9164 |
|
---|
9165 | If this is a differencing hard disk, its root hard disk is the base hard
|
---|
9166 | disk the given hard disk branch starts from. For all other types of hard
|
---|
9167 | disks, this property returns the hard disk object itself (i.e. the same
|
---|
9168 | object this property is read on).
|
---|
9169 | </desc>
|
---|
9170 | </attribute>
|
---|
9171 |
|
---|
9172 | <attribute name="readOnly" type="boolean" readonly="yes">
|
---|
9173 | <desc>
|
---|
9174 | Returns <tt>true</tt> if this hard disk is read-only and <tt>false</tt>
|
---|
9175 | otherwise.
|
---|
9176 |
|
---|
9177 | A hard disk is considered to be read-only when its contents cannot be
|
---|
9178 | modified without breaking the integrity of other parties that depend on
|
---|
9179 | this hard disk such as its child hard disks or snapshots of virtual
|
---|
9180 | machines where this hard disk is attached to these machines. If there
|
---|
9181 | are no children and no such snapshots then there is no dependency and
|
---|
9182 | the hard disk is not read-only.
|
---|
9183 |
|
---|
9184 | The value of this attribute can be used to determine the kind of the
|
---|
9185 | attachment that will take place when attaching this hard disk to a
|
---|
9186 | virtual machine. If the value is <tt>false</tt> then the hard disk will
|
---|
9187 | be attached directly. If the value is <tt>true</tt> then the hard disk
|
---|
9188 | will be attached indirectly by creating a new differencing child hard
|
---|
9189 | disk for that. See the interface description for more information.
|
---|
9190 |
|
---|
9191 | Note that all <link to="HardDiskType_Immutable">Immutable</link> hard
|
---|
9192 | disks are always read-only while all
|
---|
9193 | <link to="HardDiskType_Writethrough">Writethrough</link> hard disks are
|
---|
9194 | always not.
|
---|
9195 |
|
---|
9196 | <note>
|
---|
9197 | The read-only condition represented by this attribute is related to
|
---|
9198 | the hard disk type and usage, not to the current
|
---|
9199 | <link to="IMedium::state">media state</link> and not to the read-only
|
---|
9200 | state of the storage unit.
|
---|
9201 | </note>
|
---|
9202 | </desc>
|
---|
9203 | </attribute>
|
---|
9204 |
|
---|
9205 | <attribute name="logicalSize" type="unsigned long long" readonly="yes">
|
---|
9206 | <desc>
|
---|
9207 | Logical size of this hard disk (in megabytes), as reported to the
|
---|
9208 | guest OS running inside the virtual machine this disk is
|
---|
9209 | attached to. The logical size is defined when the hard disk is created
|
---|
9210 | and cannot be changed later.
|
---|
9211 |
|
---|
9212 | <note>
|
---|
9213 | Reading this property on a differencing hard disk will return the size
|
---|
9214 | of its <link to="#root"/> hard disk.
|
---|
9215 | </note>
|
---|
9216 | <note>
|
---|
9217 | For hard disks whose state is <link to="#state"/> is <link
|
---|
9218 | to="MediaState_Inaccessible"/>, the value of this property is the
|
---|
9219 | last known logical size. For <link to="MediaState_NotCreated"/> hard
|
---|
9220 | disks, the returned value is zero.
|
---|
9221 | </note>
|
---|
9222 | </desc>
|
---|
9223 | </attribute>
|
---|
9224 |
|
---|
9225 | <attribute name="autoReset" type="boolean">
|
---|
9226 | <desc>
|
---|
9227 | Whether this differencing hard disk will be automatically reset each
|
---|
9228 | time a virtual machine it is attached to is powered up.
|
---|
9229 |
|
---|
9230 | See <link to="#reset()"/> for more information about resetting
|
---|
9231 | differencing hard disks.
|
---|
9232 |
|
---|
9233 | <note>
|
---|
9234 | Reading this property on a base (non-differencing) hard disk will
|
---|
9235 | always <tt>false</tt>. Changing the value of this property in this
|
---|
9236 | case is not supported.
|
---|
9237 | </note>
|
---|
9238 |
|
---|
9239 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9240 | This is not a differencing hard disk (when changing the attribute
|
---|
9241 | value).
|
---|
9242 | </result>
|
---|
9243 | </desc>
|
---|
9244 | </attribute>
|
---|
9245 |
|
---|
9246 | <!-- storage methods -->
|
---|
9247 |
|
---|
9248 | <method name="getProperty">
|
---|
9249 | <desc>
|
---|
9250 | Returns the value of the custom hard disk property with the given name.
|
---|
9251 |
|
---|
9252 | The list of all properties supported by the given hard disk format can
|
---|
9253 | be obtained with <link to="IHardDiskFormat::describeProperties"/>.
|
---|
9254 |
|
---|
9255 | Note that if this method returns a <tt>null</tt> @a value, the requested
|
---|
9256 | property is supported but currently not assigned any value.
|
---|
9257 |
|
---|
9258 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9259 | Requested property does not exist (not supported by the format).
|
---|
9260 | </result>
|
---|
9261 | <result name="E_INVALIDARG">@a name is NULL or empty.</result>
|
---|
9262 | </desc>
|
---|
9263 | <param name="name" type="wstring" dir="in">
|
---|
9264 | <desc>Name of the property to get.</desc>
|
---|
9265 | </param>
|
---|
9266 | <param name="value" type="wstring" dir="return">
|
---|
9267 | <desc>Current property value.</desc>
|
---|
9268 | </param>
|
---|
9269 | </method>
|
---|
9270 |
|
---|
9271 | <method name="setProperty">
|
---|
9272 | <desc>
|
---|
9273 | Sets the value of the custom hard disk property with the given name.
|
---|
9274 |
|
---|
9275 | The list of all properties supported by the given hard disk format can
|
---|
9276 | be obtained with <link to="IHardDiskFormat::describeProperties"/>.
|
---|
9277 |
|
---|
9278 | Note that setting the property value to <tt>null</tt> is equivalent to
|
---|
9279 | deleting the existing value. A default value (if it is defined for this
|
---|
9280 | property) will be used by the format backend in this case.
|
---|
9281 |
|
---|
9282 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9283 | Requested property does not exist (not supported by the format).
|
---|
9284 | </result>
|
---|
9285 | <result name="E_INVALIDARG">@a name is NULL or empty.</result>
|
---|
9286 | </desc>
|
---|
9287 | <param name="name" type="wstring" dir="in">
|
---|
9288 | <desc>Name of the property to set.</desc>
|
---|
9289 | </param>
|
---|
9290 | <param name="value" type="wstring" dir="in">
|
---|
9291 | <desc>Property value to set.</desc>
|
---|
9292 | </param>
|
---|
9293 | </method>
|
---|
9294 |
|
---|
9295 | <method name="getProperties">
|
---|
9296 | <desc>
|
---|
9297 | Returns values for a group of properties in one call.
|
---|
9298 |
|
---|
9299 | The names of the properties to get are specified using the @a names
|
---|
9300 | argument which is a list of comma-separated property names or
|
---|
9301 | <tt>null</tt> if all properties are to be returned. Note that currently
|
---|
9302 | the value of this argument is ignored and the method always returns all
|
---|
9303 | existing properties.
|
---|
9304 |
|
---|
9305 | The list of all properties supported by the given hard disk format can
|
---|
9306 | be obtained with <link to="IHardDiskFormat::describeProperties"/>.
|
---|
9307 |
|
---|
9308 | The method returns two arrays, the array of property names corresponding
|
---|
9309 | to the @a names argument and the current values of these properties.
|
---|
9310 | Both arrays have the same number of elements with each elemend at the
|
---|
9311 | given index in the first array corresponds to an element at the same
|
---|
9312 | index in the second array.
|
---|
9313 |
|
---|
9314 | Note that for properties that do not have assigned values,
|
---|
9315 | <tt>null</tt> is returned at the appropriate index in the
|
---|
9316 | @a returnValues array.
|
---|
9317 |
|
---|
9318 | </desc>
|
---|
9319 | <param name="names" type="wstring" dir="in">
|
---|
9320 | <desc>
|
---|
9321 | Names of properties to get.
|
---|
9322 | </desc>
|
---|
9323 | </param>
|
---|
9324 | <param name="returnNames" type="wstring" safearray="yes" dir="out">
|
---|
9325 | <desc>Names of returned properties.</desc>
|
---|
9326 | </param>
|
---|
9327 | <param name="returnValues" type="wstring" safearray="yes" dir="return">
|
---|
9328 | <desc>Values of returned properties.</desc>
|
---|
9329 | </param>
|
---|
9330 | </method>
|
---|
9331 |
|
---|
9332 | <method name="setProperties">
|
---|
9333 | <desc>
|
---|
9334 | Sets values for a group of properties in one call.
|
---|
9335 |
|
---|
9336 | The names of the properties to set are passed in the @a names
|
---|
9337 | array along with the new values for them in the @a values array. Both
|
---|
9338 | arrays have the same number of elements with each elemend at the given
|
---|
9339 | index in the first array corresponding to an element at the same index
|
---|
9340 | in the second array.
|
---|
9341 |
|
---|
9342 | If there is at least one property name in @a names that is not valid,
|
---|
9343 | the method will fail before changing the values of any other properties
|
---|
9344 | from the @a names array.
|
---|
9345 |
|
---|
9346 | Using this method over <link to="#setProperty"/> is preferred if you
|
---|
9347 | need to set several properties at once since it will result into less
|
---|
9348 | IPC calls.
|
---|
9349 |
|
---|
9350 | The list of all properties supported by the given hard disk format can
|
---|
9351 | be obtained with <link to="IHardDiskFormat::describeProperties"/>.
|
---|
9352 |
|
---|
9353 | Note that setting the property value to <tt>null</tt> is equivalent to
|
---|
9354 | deleting the existing value. A default value (if it is defined for this
|
---|
9355 | property) will be used by the format backend in this case.
|
---|
9356 | </desc>
|
---|
9357 | <param name="names" type="wstring" safearray="yes" dir="in">
|
---|
9358 | <desc>Names of properties to set.</desc>
|
---|
9359 | </param>
|
---|
9360 | <param name="values" type="wstring" safearray="yes" dir="in">
|
---|
9361 | <desc>Values of properties to set.</desc>
|
---|
9362 | </param>
|
---|
9363 | </method>
|
---|
9364 |
|
---|
9365 | <!-- storage methods -->
|
---|
9366 |
|
---|
9367 | <method name="createBaseStorage">
|
---|
9368 | <desc>
|
---|
9369 | Starts creating a hard disk storage unit (fixed/dynamic, according
|
---|
9370 | to the variant flags) in in the background. The previous storage unit
|
---|
9371 | created for this object, if any, must first be deleted using
|
---|
9372 | <link to="#deleteStorage"/>, otherwise the operation will fail.
|
---|
9373 |
|
---|
9374 | Before the operation starts, the hard disk is placed in
|
---|
9375 | <link to="MediaState_Creating"/> state. If the create operation
|
---|
9376 | fails, the media will be placed back in <link to="MediaState_NotCreated"/>
|
---|
9377 | state.
|
---|
9378 |
|
---|
9379 | After the returned progress object reports that the operation has
|
---|
9380 | successfully completed, the media state will be set to <link
|
---|
9381 | to="MediaState_Created"/>, the hard disk will be remembered by this
|
---|
9382 | VirtualBox installation and may be attached to virtual machines.
|
---|
9383 |
|
---|
9384 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9385 | The variant of storage creation operation is not supported. See <link
|
---|
9386 | to="IHardDiskFormat::capabilities"/>.
|
---|
9387 | </result>
|
---|
9388 | </desc>
|
---|
9389 | <param name="logicalSize" type="unsigned long long" dir="in">
|
---|
9390 | <desc>Maximum logical size of the hard disk in megabytes.</desc>
|
---|
9391 | </param>
|
---|
9392 | <param name="variant" type="HardDiskVariant" dir="in">
|
---|
9393 | <desc>Exact image variant which should be created.</desc>
|
---|
9394 | </param>
|
---|
9395 | <param name="progress" type="IProgress" dir="return">
|
---|
9396 | <desc>Progress object to track the operation completion.</desc>
|
---|
9397 | </param>
|
---|
9398 | </method>
|
---|
9399 |
|
---|
9400 | <method name="deleteStorage">
|
---|
9401 | <desc>
|
---|
9402 | Starts deleting the storage unit of this hard disk.
|
---|
9403 |
|
---|
9404 | The hard disk must not be attached to any known virtual machine and must
|
---|
9405 | not have any known child hard disks, otherwise the operation will fail.
|
---|
9406 | It will also fail if there is no storage unit to delete or if deletion
|
---|
9407 | is already in progress, or if the hard disk is being in use (locked for
|
---|
9408 | read or for write) or inaccessible. Therefore, the only valid state for
|
---|
9409 | this operation to succeed is <link to="MediaState_Created"/>.
|
---|
9410 |
|
---|
9411 | Before the operation starts, the hard disk is placed to
|
---|
9412 | <link to="MediaState_Deleting"/> state and gets removed from the list
|
---|
9413 | of remembered hard disks (media registry). If the delete operation
|
---|
9414 | fails, the media will be remembered again and placed back to
|
---|
9415 | <link to="MediaState_Created"/> state.
|
---|
9416 |
|
---|
9417 | After the returned progress object reports that the operation is
|
---|
9418 | complete, the media state will be set to
|
---|
9419 | <link to="MediaState_NotCreated"/> and you will be able to use one of
|
---|
9420 | the storage creation methods to create it again.
|
---|
9421 |
|
---|
9422 | <see>#close()</see>
|
---|
9423 |
|
---|
9424 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
9425 | Hard disk is attached to a virtual machine.
|
---|
9426 | </result>
|
---|
9427 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9428 | Storage deletion is not allowed because neither of storage creation
|
---|
9429 | operations are supported. See
|
---|
9430 | <link to="IHardDiskFormat::capabilities"/>.
|
---|
9431 | </result>
|
---|
9432 |
|
---|
9433 | <note>
|
---|
9434 | If the deletion operation fails, it is not guaranteed that the storage
|
---|
9435 | unit still exists. You may check the <link to="IMedium::state"/> value
|
---|
9436 | to answer this question.
|
---|
9437 | </note>
|
---|
9438 | </desc>
|
---|
9439 | <param name="progress" type="IProgress" dir="return">
|
---|
9440 | <desc>Progress object to track the operation completion.</desc>
|
---|
9441 | </param>
|
---|
9442 | </method>
|
---|
9443 |
|
---|
9444 | <!-- diff methods -->
|
---|
9445 |
|
---|
9446 | <method name="createDiffStorage">
|
---|
9447 | <desc>
|
---|
9448 | Starts creating an empty differencing storage unit based on this hard
|
---|
9449 | disk in the format and at the location defined by the @a target
|
---|
9450 | argument.
|
---|
9451 |
|
---|
9452 | The target hard disk must be in <link to="MediaState_NotCreated"/>
|
---|
9453 | state (i.e. must not have an existing storage unit). Upon successful
|
---|
9454 | completion, this operation will set the type of the target hard disk to
|
---|
9455 | <link to="HardDiskType_Normal"/> and create a storage unit necessary to
|
---|
9456 | represent the differencing hard disk data in the given format (according
|
---|
9457 | to the storage format of the target object).
|
---|
9458 |
|
---|
9459 | After the returned progress object reports that the operation is
|
---|
9460 | successfully complete, the target hard disk gets remembered by this
|
---|
9461 | VirtualBox installation and may be attached to virtual machines.
|
---|
9462 |
|
---|
9463 | <note>
|
---|
9464 | The hard disk will be set to <link to="MediaState_LockedRead"/>
|
---|
9465 | state for the duration of this operation.
|
---|
9466 | </note>
|
---|
9467 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
9468 | Hard disk not in NotCreated state.
|
---|
9469 | </result>
|
---|
9470 | </desc>
|
---|
9471 | <param name="target" type="IHardDisk" dir="in">
|
---|
9472 | <desc>Target hard disk.</desc>
|
---|
9473 | </param>
|
---|
9474 | <param name="variant" type="HardDiskVariant" dir="in">
|
---|
9475 | <desc>Exact image variant which should be created.</desc>
|
---|
9476 | </param>
|
---|
9477 | <param name="progress" type="IProgress" dir="return">
|
---|
9478 | <desc>Progress object to track the operation completion.</desc>
|
---|
9479 | </param>
|
---|
9480 | </method>
|
---|
9481 |
|
---|
9482 | <method name="mergeTo">
|
---|
9483 | <desc>
|
---|
9484 | Starts merging the contents of this hard disk and all intermediate
|
---|
9485 | differencing hard disks in the chain to the given target hard disk.
|
---|
9486 |
|
---|
9487 | The target hard disk must be either a descendant of this hard disk or
|
---|
9488 | its ancestor (otherwise this method will immediately return a failure).
|
---|
9489 | It follows that there are two logical directions of the merge operation:
|
---|
9490 | from ancestor to descendant (<i>forward merge</i>) and from descendant to
|
---|
9491 | ancestor (<i>backward merge</i>). Let us consider the following hard disk
|
---|
9492 | chain:
|
---|
9493 |
|
---|
9494 | <pre>Base <- Diff_1 <- Diff_2</pre>
|
---|
9495 |
|
---|
9496 | Here, calling this method on the <tt>Base</tt> hard disk object with
|
---|
9497 | <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
|
---|
9498 | <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
|
---|
9499 | merge. Note that in both cases the contents of the resulting hard disk
|
---|
9500 | will be the same, the only difference is the hard disk object that takes
|
---|
9501 | the result of the merge operation. In case of the forward merge in the
|
---|
9502 | above example, the result will be written to <tt>Diff_2</tt>; in case of
|
---|
9503 | the backward merge, the result will be written to <tt>Base</tt>. In
|
---|
9504 | other words, the result of the operation is always stored in the target
|
---|
9505 | hard disk.
|
---|
9506 |
|
---|
9507 | Upon successful operation completion, the storage units of all hard
|
---|
9508 | disks in the chain between this (source) hard disk and the target hard
|
---|
9509 | disk, including the source hard disk itself, will be automatically
|
---|
9510 | deleted and the relevant hard disk objects (including this hard disk)
|
---|
9511 | will become uninitialized. This means that any attempt to call any of
|
---|
9512 | their methods or attributes will fail with the
|
---|
9513 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
|
---|
9514 | example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
|
---|
9515 | delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> hard
|
---|
9516 | disks. Note that <tt>Diff_2</tt> in this case will become a base hard
|
---|
9517 | disk itself since it will no longer be based on any other hard disk.
|
---|
9518 |
|
---|
9519 | Considering the above, all of the following conditions must be met in
|
---|
9520 | order for the merge operation to succeed:
|
---|
9521 | <ul>
|
---|
9522 | <li>
|
---|
9523 | Neither this (source) hard disk nor any intermediate
|
---|
9524 | differencing hard disk in the chain between it and the target
|
---|
9525 | hard disk is attached to any virtual machine.
|
---|
9526 | </li>
|
---|
9527 | <li>
|
---|
9528 | Neither the source hard disk nor the target hard disk is an
|
---|
9529 | <link to="HardDiskType_Immutable"/> hard disk.
|
---|
9530 | </li>
|
---|
9531 | <li>
|
---|
9532 | The part of the hard disk tree from the source hard disk to the
|
---|
9533 | target hard disk is a linear chain, i.e. all hard disks in this
|
---|
9534 | chain have exactly one child which is the next hard disk in this
|
---|
9535 | chain. The only exception from this rule is the target hard disk in
|
---|
9536 | the forward merge operation; it is allowed to have any number of
|
---|
9537 | child hard disks because the merge operation will hot change its
|
---|
9538 | logical contents (as it is seen by the guest OS or by children).
|
---|
9539 | </li>
|
---|
9540 | <li>
|
---|
9541 | None of the involved hard disks are in
|
---|
9542 | <link to="MediaState_LockedRead"/> or
|
---|
9543 | <link to="MediaState_LockedWrite"/> state.
|
---|
9544 | </li>
|
---|
9545 | </ul>
|
---|
9546 |
|
---|
9547 | <note>
|
---|
9548 | This (source) hard disk and all intermediates will be placed to <link
|
---|
9549 | to="MediaState_Deleting"/> state and the target hard disk will be
|
---|
9550 | placed to <link to="MediaState_LockedWrite"/> state and for the
|
---|
9551 | duration of this operation.
|
---|
9552 | </note>
|
---|
9553 | </desc>
|
---|
9554 | <param name="targetId" type="uuid" dir="in">
|
---|
9555 | <desc>UUID of the target ancestor or descendant hard disk.</desc>
|
---|
9556 | </param>
|
---|
9557 | <param name="progress" type="IProgress" dir="return">
|
---|
9558 | <desc>Progress object to track the operation completion.</desc>
|
---|
9559 | </param>
|
---|
9560 | </method>
|
---|
9561 |
|
---|
9562 | <!-- clone method -->
|
---|
9563 |
|
---|
9564 | <method name="cloneTo">
|
---|
9565 | <desc>
|
---|
9566 | Starts creating a clone of this hard disk in the format and at the
|
---|
9567 | location defined by the @a target argument.
|
---|
9568 |
|
---|
9569 | The target hard disk must be in <link to="MediaState_NotCreated"/>
|
---|
9570 | state (i.e. must not have an existing storage unit). Upon successful
|
---|
9571 | completion, the cloned hard disk will contain exactly the same sector
|
---|
9572 | data as the hard disk being cloned, except that a new UUID for the
|
---|
9573 | clone will be randomly generated.
|
---|
9574 |
|
---|
9575 | The @a parent argument defines which hard disk will be the parent
|
---|
9576 | of the clone. Passing a NULL reference indicates that the clone will
|
---|
9577 | be a base image, i.e. completely independent. It is possible to specify
|
---|
9578 | an arbitrary hard disk for this parameter, including the parent of the
|
---|
9579 | hard disk which is being cloned. Even cloning to a child of the source
|
---|
9580 | hard disk is possible.
|
---|
9581 |
|
---|
9582 | After the returned progress object reports that the operation is
|
---|
9583 | successfully complete, the target hard disk gets remembered by this
|
---|
9584 | VirtualBox installation and may be attached to virtual machines.
|
---|
9585 |
|
---|
9586 | <note>
|
---|
9587 | This hard disk will be placed to <link to="MediaState_LockedRead"/>
|
---|
9588 | state for the duration of this operation.
|
---|
9589 | </note>
|
---|
9590 | </desc>
|
---|
9591 | <param name="target" type="IHardDisk" dir="in">
|
---|
9592 | <desc>Target hard disk.</desc>
|
---|
9593 | </param>
|
---|
9594 | <param name="variant" type="HardDiskVariant" dir="in">
|
---|
9595 | <desc>Exact image variant which should be created.</desc>
|
---|
9596 | </param>
|
---|
9597 | <param name="parent" type="IHardDisk" dir="in">
|
---|
9598 | <desc>Parent of the cloned hard disk.</desc>
|
---|
9599 | </param>
|
---|
9600 | <param name="progress" type="IProgress" dir="return">
|
---|
9601 | <desc>Progress object to track the operation completion.</desc>
|
---|
9602 | </param>
|
---|
9603 | </method>
|
---|
9604 |
|
---|
9605 | <!-- other methods -->
|
---|
9606 |
|
---|
9607 | <method name="compact">
|
---|
9608 | <desc>
|
---|
9609 | Starts compacting of this hard disk. This means that the disk is
|
---|
9610 | transformed into a possibly more compact storage representation.
|
---|
9611 | This potentially creates temporary images, which can require a
|
---|
9612 | substantial amount of additional disk space.
|
---|
9613 |
|
---|
9614 | This hard disk will be placed to <link to="MediaState_LockedWrite"/>
|
---|
9615 | state and all its parent hard disks (if any) will be placed to
|
---|
9616 | <link to="MediaState_LockedRead"/> state for the duration of this
|
---|
9617 | operation.
|
---|
9618 |
|
---|
9619 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9620 | Hard disk format does not support compacting (but potentially
|
---|
9621 | needs it).
|
---|
9622 | </result>
|
---|
9623 | </desc>
|
---|
9624 | <param name="progress" type="IProgress" dir="return">
|
---|
9625 | <desc>Progress object to track the operation completion.</desc>
|
---|
9626 | </param>
|
---|
9627 | </method>
|
---|
9628 |
|
---|
9629 | <method name="reset">
|
---|
9630 | <desc>
|
---|
9631 | Starts erasing the contents of this differencing hard disk.
|
---|
9632 |
|
---|
9633 | This operation will reset the differencing hard disk to its initial
|
---|
9634 | state when it does not contain any sector data and any read operation is
|
---|
9635 | redirected to its parent hard disk.
|
---|
9636 |
|
---|
9637 | This hard disk will be placed to <link to="MediaState_LockedWrite"/>
|
---|
9638 | for the duration of this operation.
|
---|
9639 |
|
---|
9640 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9641 | This is not a differencing hard disk.
|
---|
9642 | </result>
|
---|
9643 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9644 | Hard disk is not in <link to="MediaState_Created"/> or
|
---|
9645 | <link to="MediaState_Inaccessible"/> state.
|
---|
9646 | </result>
|
---|
9647 | </desc>
|
---|
9648 | <param name="progress" type="IProgress" dir="return">
|
---|
9649 | <desc>Progress object to track the operation completion.</desc>
|
---|
9650 | </param>
|
---|
9651 | </method>
|
---|
9652 |
|
---|
9653 | </interface>
|
---|
9654 |
|
---|
9655 |
|
---|
9656 | <!--
|
---|
9657 | // IHardDiskFormat
|
---|
9658 | /////////////////////////////////////////////////////////////////////////
|
---|
9659 | -->
|
---|
9660 |
|
---|
9661 | <enum
|
---|
9662 | name="DataType"
|
---|
9663 | uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
|
---|
9664 | >
|
---|
9665 | <const name="Int32" value="0"/>
|
---|
9666 | <const name="Int8" value="1"/>
|
---|
9667 | <const name="String" value="2"/>
|
---|
9668 | </enum>
|
---|
9669 |
|
---|
9670 | <enum
|
---|
9671 | name="DataFlags"
|
---|
9672 | uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
|
---|
9673 | >
|
---|
9674 | <const name="None" value="0x00"/>
|
---|
9675 | <const name="Mandatory" value="0x01"/>
|
---|
9676 | <const name="Expert" value="0x02"/>
|
---|
9677 | <const name="Array" value="0x04"/>
|
---|
9678 | <const name="FlagMask" value="0x07"/>
|
---|
9679 | </enum>
|
---|
9680 |
|
---|
9681 | <enum
|
---|
9682 | name="HardDiskFormatCapabilities"
|
---|
9683 | uuid="1df1e4aa-d25a-4ba6-b2a2-02f60eb5903b"
|
---|
9684 | >
|
---|
9685 | <desc>
|
---|
9686 | Hard disk format capability flags.
|
---|
9687 | </desc>
|
---|
9688 |
|
---|
9689 | <const name="Uuid" value="0x01">
|
---|
9690 | <desc>
|
---|
9691 | Supports UUIDs as expected by VirtualBox code.
|
---|
9692 | </desc>
|
---|
9693 | </const>
|
---|
9694 |
|
---|
9695 | <const name="CreateFixed" value="0x02">
|
---|
9696 | <desc>
|
---|
9697 | Supports creating fixed size images, allocating all space instantly.
|
---|
9698 | </desc>
|
---|
9699 | </const>
|
---|
9700 |
|
---|
9701 | <const name="CreateDynamic" value="0x04">
|
---|
9702 | <desc>
|
---|
9703 | Supports creating dynamically growing images, allocating space on
|
---|
9704 | demand.
|
---|
9705 | </desc>
|
---|
9706 | </const>
|
---|
9707 |
|
---|
9708 | <const name="CreateSplit2G" value="0x08">
|
---|
9709 | <desc>
|
---|
9710 | Supports creating images split in chunks of a bit less than 2 GBytes.
|
---|
9711 | </desc>
|
---|
9712 | </const>
|
---|
9713 |
|
---|
9714 | <const name="Differencing" value="0x10">
|
---|
9715 | <desc>
|
---|
9716 | Supports being used as a format for differencing hard disks (see <link
|
---|
9717 | to="IHardDisk::createDiffStorage"/>).
|
---|
9718 | </desc>
|
---|
9719 | </const>
|
---|
9720 |
|
---|
9721 | <const name="Asynchronous" value="0x20">
|
---|
9722 | <desc>
|
---|
9723 | Supports asynchronous I/O operations for at least some configurations.
|
---|
9724 | </desc>
|
---|
9725 | </const>
|
---|
9726 |
|
---|
9727 | <const name="File" value="0x40">
|
---|
9728 | <desc>
|
---|
9729 | The format backend operates on files (the <link to="IMedium::location"/>
|
---|
9730 | attribute of the hard disk specifies a file used to store hard disk
|
---|
9731 | data; for a list of supported file extensions see
|
---|
9732 | <link to="IHardDiskFormat::fileExtensions"/>).
|
---|
9733 | </desc>
|
---|
9734 | </const>
|
---|
9735 |
|
---|
9736 | <const name="Properties" value="0x80">
|
---|
9737 | <desc>
|
---|
9738 | The format backend uses the property interface to configure the storage
|
---|
9739 | location and properties (the <link to="IHardDiskFormat::describeProperties"/>
|
---|
9740 | method is used to get access to properties supported by the given hard
|
---|
9741 | disk format).
|
---|
9742 | </desc>
|
---|
9743 | </const>
|
---|
9744 |
|
---|
9745 | <const name="CapabilityMask" value="0xFF"/>
|
---|
9746 | </enum>
|
---|
9747 |
|
---|
9748 | <interface
|
---|
9749 | name="IHardDiskFormat" extends="$unknown"
|
---|
9750 | uuid="7f3ba790-3a0b-4a8a-bac2-bb50150123c5"
|
---|
9751 | wsmap="managed"
|
---|
9752 | >
|
---|
9753 | <desc>
|
---|
9754 | The IHardDiskFormat interface represents a virtual hard disk format.
|
---|
9755 |
|
---|
9756 | Each hard disk format has an associated backend which is used to handle
|
---|
9757 | hard disks stored in this format. This interface provides information
|
---|
9758 | about the properties of the associated backend.
|
---|
9759 |
|
---|
9760 | Each hard disk format is identified by a string represented by the
|
---|
9761 | <link to="#id"/> attribute. This string is used in calls like
|
---|
9762 | <link to="IVirtualBox::createHardDisk"/> to specify the desired
|
---|
9763 | format.
|
---|
9764 |
|
---|
9765 | The list of all supported hard disk formats can be obtained using
|
---|
9766 | <link to="ISystemProperties::hardDiskFormats"/>.
|
---|
9767 |
|
---|
9768 | <see>IHardDisk</see>
|
---|
9769 | </desc>
|
---|
9770 |
|
---|
9771 | <attribute name="id" type="wstring" readonly="yes">
|
---|
9772 | <desc>
|
---|
9773 | Identifier of this format.
|
---|
9774 |
|
---|
9775 | The format identifier is a non-null non-empty ASCII string. Note that
|
---|
9776 | this string is case-insensitive. This means that, for example, all of
|
---|
9777 | the following strings:
|
---|
9778 | <pre>
|
---|
9779 | "VDI"
|
---|
9780 | "vdi"
|
---|
9781 | "VdI"</pre>
|
---|
9782 | refer to the same hard disk format.
|
---|
9783 |
|
---|
9784 | This string is used in methods of other interfaces where it is necessary
|
---|
9785 | to specify a hard disk format, such as
|
---|
9786 | <link to="IVirtualBox::createHardDisk"/>.
|
---|
9787 | </desc>
|
---|
9788 | </attribute>
|
---|
9789 |
|
---|
9790 | <attribute name="name" type="wstring" readonly="yes">
|
---|
9791 | <desc>
|
---|
9792 | Human readable description of this format.
|
---|
9793 |
|
---|
9794 | Mainly for use in file open dialogs.
|
---|
9795 | </desc>
|
---|
9796 | </attribute>
|
---|
9797 |
|
---|
9798 | <attribute name="fileExtensions" type="wstring" safearray="yes" readonly="yes">
|
---|
9799 | <desc>
|
---|
9800 | Array of strings containing the supported file extensions.
|
---|
9801 |
|
---|
9802 | The first extension in the array is the extension preferred by the
|
---|
9803 | backend. It is recommended to use this extension when specifying a
|
---|
9804 | location of the storage unit for a new hard disk.
|
---|
9805 |
|
---|
9806 | Note that some backends do not work on files, so this array may be
|
---|
9807 | empty.
|
---|
9808 |
|
---|
9809 | <see>IHardDiskFormat::capabilities</see>
|
---|
9810 | </desc>
|
---|
9811 | </attribute>
|
---|
9812 |
|
---|
9813 | <attribute name="capabilities" type="unsigned long" readonly="yes">
|
---|
9814 | <desc>
|
---|
9815 | Capabilities of the format as a set of bit flags.
|
---|
9816 |
|
---|
9817 | For the meaning of individual capability flags see
|
---|
9818 | <link to="HardDiskFormatCapabilities"/>.
|
---|
9819 | </desc>
|
---|
9820 | </attribute>
|
---|
9821 |
|
---|
9822 | <method name="describeProperties">
|
---|
9823 | <desc>
|
---|
9824 | Returns several arrays describing the properties supported by this
|
---|
9825 | format.
|
---|
9826 |
|
---|
9827 | An element with the given index in each array describes one
|
---|
9828 | property. Thus, the number of elements in each returned array is the
|
---|
9829 | same and corresponds to the number of supported properties.
|
---|
9830 |
|
---|
9831 | The returned arrays are filled in only if the
|
---|
9832 | <link to="HardDiskFormatCapabilities_Properties"/> flag is set.
|
---|
9833 | All arguments must be non-NULL.
|
---|
9834 |
|
---|
9835 | <see>DataType</see>
|
---|
9836 | <see>DataFlags</see>
|
---|
9837 | </desc>
|
---|
9838 |
|
---|
9839 | <param name="names" type="wstring" safearray="yes" dir="out">
|
---|
9840 | <desc>Array of property names.</desc>
|
---|
9841 | </param>
|
---|
9842 | <param name="description" type="wstring" safearray="yes" dir="out">
|
---|
9843 | <desc>Array of property descriptions.</desc>
|
---|
9844 | </param>
|
---|
9845 | <param name="types" type="DataType" safearray="yes" dir="out">
|
---|
9846 | <desc>Array of property types.</desc>
|
---|
9847 | </param>
|
---|
9848 | <param name="flags" type="unsigned long" safearray="yes" dir="out">
|
---|
9849 | <desc>Array of property flags.</desc>
|
---|
9850 | </param>
|
---|
9851 | <param name="defaults" type="wstring" safearray="yes" dir="out">
|
---|
9852 | <desc>Array of default property values.</desc>
|
---|
9853 | </param>
|
---|
9854 | </method>
|
---|
9855 |
|
---|
9856 | </interface>
|
---|
9857 |
|
---|
9858 |
|
---|
9859 | <!--
|
---|
9860 | // IFloppyImage
|
---|
9861 | /////////////////////////////////////////////////////////////////////////
|
---|
9862 | -->
|
---|
9863 |
|
---|
9864 | <interface
|
---|
9865 | name="IFloppyImage" extends="IMedium"
|
---|
9866 | uuid="faa6101f-078c-4b3a-ab75-75670c8170b3"
|
---|
9867 | wsmap="managed"
|
---|
9868 | >
|
---|
9869 | <desc>
|
---|
9870 | The IFloppyImage interface represents a medium containing the image
|
---|
9871 | of a floppy disk. This is a subclass of <link to="IMedium" />; see remarks there.
|
---|
9872 | </desc>
|
---|
9873 |
|
---|
9874 | </interface>
|
---|
9875 |
|
---|
9876 |
|
---|
9877 | <!--
|
---|
9878 | // IDVDImage
|
---|
9879 | /////////////////////////////////////////////////////////////////////////
|
---|
9880 | -->
|
---|
9881 |
|
---|
9882 | <interface
|
---|
9883 | name="IDVDImage" extends="IMedium"
|
---|
9884 | uuid="b1f90bbb-e8a9-4484-9af1-3638e943f763"
|
---|
9885 | wsmap="managed"
|
---|
9886 | >
|
---|
9887 | <desc>
|
---|
9888 | The IDVDImage interface represents a medium containing the image
|
---|
9889 | of a CD or DVD disk in the ISO format.
|
---|
9890 |
|
---|
9891 | This is a subclass of <link to="IMedium" />; see remarks there.
|
---|
9892 | </desc>
|
---|
9893 |
|
---|
9894 | </interface>
|
---|
9895 |
|
---|
9896 |
|
---|
9897 | <!--
|
---|
9898 | // IDVDDrive
|
---|
9899 | /////////////////////////////////////////////////////////////////////////
|
---|
9900 | -->
|
---|
9901 |
|
---|
9902 | <interface
|
---|
9903 | name="IDVDDrive" extends="$unknown"
|
---|
9904 | uuid="d650ef30-be9b-4dae-b463-11d5824681a5"
|
---|
9905 | wsmap="managed"
|
---|
9906 | >
|
---|
9907 | <desc>
|
---|
9908 | The IDVDDrive interface represents the virtual CD/DVD drive of the
|
---|
9909 | virtual machine. An object of this type is returned by
|
---|
9910 | <link to="IMachine::DVDDrive"/>.
|
---|
9911 | </desc>
|
---|
9912 |
|
---|
9913 | <attribute name="state" type="DriveState" readonly="yes">
|
---|
9914 | <desc>Current drive state.</desc>
|
---|
9915 | </attribute>
|
---|
9916 |
|
---|
9917 | <attribute name="passthrough" type="boolean">
|
---|
9918 | <desc>
|
---|
9919 | When a host drive is mounted and passthrough is enabled
|
---|
9920 | the guest OS will be able to directly send SCSI commands to
|
---|
9921 | the host drive. This enables the guest OS to use CD/DVD writers
|
---|
9922 | but is potentially dangerous.
|
---|
9923 | </desc>
|
---|
9924 | </attribute>
|
---|
9925 |
|
---|
9926 | <method name="mountImage">
|
---|
9927 | <desc>Mounts a CD/DVD image with the specified UUID.
|
---|
9928 |
|
---|
9929 | <result name="VBOX_E_FILE_ERROR">
|
---|
9930 | Invalid image file location.
|
---|
9931 | </result>
|
---|
9932 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9933 | Could not find a CD/DVD image matching @a imageId.
|
---|
9934 | </result>
|
---|
9935 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9936 | Invalid media state.
|
---|
9937 | </result>
|
---|
9938 |
|
---|
9939 | </desc>
|
---|
9940 | <param name="imageId" type="uuid" dir="in"/>
|
---|
9941 | </method>
|
---|
9942 |
|
---|
9943 | <method name="captureHostDrive">
|
---|
9944 | <desc>Captures the specified host CD/DVD drive.</desc>
|
---|
9945 | <param name="drive" type="IHostDVDDrive" dir="in"/>
|
---|
9946 | </method>
|
---|
9947 |
|
---|
9948 | <method name="unmount">
|
---|
9949 | <desc>Unmounts the currently mounted image or host drive.</desc>
|
---|
9950 | </method>
|
---|
9951 |
|
---|
9952 | <method name="getImage">
|
---|
9953 | <desc>Returns the currently mounted CD/DVD image.</desc>
|
---|
9954 | <param name="image" type="IDVDImage" dir="return"/>
|
---|
9955 | </method>
|
---|
9956 |
|
---|
9957 | <method name="getHostDrive">
|
---|
9958 | <desc>Returns the currently mounted host CD/DVD drive.</desc>
|
---|
9959 | <param name="drive" type="IHostDVDDrive" dir="return"/>
|
---|
9960 | </method>
|
---|
9961 |
|
---|
9962 | </interface>
|
---|
9963 |
|
---|
9964 |
|
---|
9965 | <!--
|
---|
9966 | // IFloppyDrive
|
---|
9967 | /////////////////////////////////////////////////////////////////////////
|
---|
9968 | -->
|
---|
9969 |
|
---|
9970 | <interface
|
---|
9971 | name="IFloppyDrive" extends="$unknown"
|
---|
9972 | uuid="159412cd-bab8-452e-8097-218a020825a6"
|
---|
9973 | wsmap="managed"
|
---|
9974 | >
|
---|
9975 | <desc>
|
---|
9976 | The IFloppyDrive interface represents the virtual floppy drive of the
|
---|
9977 | virtual machine. An object of this type is returned by
|
---|
9978 | <link to="IMachine::floppyDrive" />.
|
---|
9979 | </desc>
|
---|
9980 |
|
---|
9981 | <attribute name="enabled" type="boolean">
|
---|
9982 | <desc>
|
---|
9983 | Flag whether the floppy drive is enabled. If it is disabled,
|
---|
9984 | the floppy drive will not be reported to the guest OS.
|
---|
9985 | </desc>
|
---|
9986 | </attribute>
|
---|
9987 |
|
---|
9988 | <attribute name="state" type="DriveState" readonly="yes">
|
---|
9989 | <desc>Current drive state.</desc>
|
---|
9990 | </attribute>
|
---|
9991 |
|
---|
9992 | <method name="mountImage">
|
---|
9993 | <desc>Mounts a floppy image with the specified UUID.
|
---|
9994 |
|
---|
9995 | <result name="VBOX_E_FILE_ERROR">
|
---|
9996 | Invalid image file location.
|
---|
9997 | </result>
|
---|
9998 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9999 | Could not find a floppy image matching @a imageID.
|
---|
10000 | </result>
|
---|
10001 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10002 | Invalid media state.
|
---|
10003 | </result>
|
---|
10004 |
|
---|
10005 | </desc>
|
---|
10006 | <param name="imageId" type="uuid" dir="in"/>
|
---|
10007 | </method>
|
---|
10008 |
|
---|
10009 | <method name="captureHostDrive">
|
---|
10010 | <desc>Captures the specified host floppy drive.</desc>
|
---|
10011 | <param name="drive" type="IHostFloppyDrive" dir="in"/>
|
---|
10012 | </method>
|
---|
10013 |
|
---|
10014 | <method name="unmount">
|
---|
10015 | <desc>Unmounts the currently mounted image or host drive.</desc>
|
---|
10016 | </method>
|
---|
10017 |
|
---|
10018 | <method name="getImage">
|
---|
10019 | <desc>Returns the currently mounted floppy image.</desc>
|
---|
10020 | <param name="image" type="IFloppyImage" dir="return"/>
|
---|
10021 | </method>
|
---|
10022 |
|
---|
10023 | <method name="getHostDrive">
|
---|
10024 | <desc>Returns the currently mounted host floppy drive.</desc>
|
---|
10025 | <param name="drive" type="IHostFloppyDrive" dir="return"/>
|
---|
10026 | </method>
|
---|
10027 |
|
---|
10028 | </interface>
|
---|
10029 |
|
---|
10030 |
|
---|
10031 | <!--
|
---|
10032 | // IKeyboard
|
---|
10033 | /////////////////////////////////////////////////////////////////////////
|
---|
10034 | -->
|
---|
10035 |
|
---|
10036 | <interface
|
---|
10037 | name="IKeyboard" extends="$unknown"
|
---|
10038 | uuid="2d1a531b-4c6e-49cc-8af6-5c857b78b5d7"
|
---|
10039 | wsmap="managed"
|
---|
10040 | >
|
---|
10041 | <desc>
|
---|
10042 | The IKeyboard interface represents the virtual machine's keyboard. Used
|
---|
10043 | in <link to="IConsole::keyboard"/>.
|
---|
10044 |
|
---|
10045 | Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
|
---|
10046 | to the virtual machine.
|
---|
10047 |
|
---|
10048 | </desc>
|
---|
10049 | <method name="putScancode">
|
---|
10050 | <desc>Sends a scancode to the keyboard.
|
---|
10051 |
|
---|
10052 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10053 | Could not send scan code to virtual keyboard.
|
---|
10054 | </result>
|
---|
10055 |
|
---|
10056 | </desc>
|
---|
10057 | <param name="scancode" type="long" dir="in"/>
|
---|
10058 | </method>
|
---|
10059 |
|
---|
10060 | <method name="putScancodes">
|
---|
10061 | <desc>Sends an array of scancodes to the keyboard.
|
---|
10062 |
|
---|
10063 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10064 | Could not send all scan codes to virtual keyboard.
|
---|
10065 | </result>
|
---|
10066 |
|
---|
10067 | </desc>
|
---|
10068 | <param name="scancodes" type="long" dir="in" safearray="yes"/>
|
---|
10069 | <param name="codesStored" type="unsigned long" dir="return"/>
|
---|
10070 | </method>
|
---|
10071 |
|
---|
10072 | <method name="putCAD">
|
---|
10073 | <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
|
---|
10074 | function is nothing special, it is just a convenience function
|
---|
10075 | calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
|
---|
10076 |
|
---|
10077 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10078 | Could not send all scan codes to virtual keyboard.
|
---|
10079 | </result>
|
---|
10080 |
|
---|
10081 | </desc>
|
---|
10082 | </method>
|
---|
10083 |
|
---|
10084 | </interface>
|
---|
10085 |
|
---|
10086 |
|
---|
10087 | <!--
|
---|
10088 | // IMouse
|
---|
10089 | /////////////////////////////////////////////////////////////////////////
|
---|
10090 | -->
|
---|
10091 |
|
---|
10092 | <enum
|
---|
10093 | name="MouseButtonState"
|
---|
10094 | uuid="03131722-2EC5-4173-9794-0DACA46673EF"
|
---|
10095 | >
|
---|
10096 | <desc>
|
---|
10097 | Mouse button state.
|
---|
10098 | </desc>
|
---|
10099 |
|
---|
10100 | <const name="LeftButton" value="0x01"/>
|
---|
10101 | <const name="RightButton" value="0x02"/>
|
---|
10102 | <const name="MiddleButton" value="0x04"/>
|
---|
10103 | <const name="WheelUp" value="0x08"/>
|
---|
10104 | <const name="WheelDown" value="0x10"/>
|
---|
10105 | <const name="MouseStateMask" value="0x1F"/>
|
---|
10106 | </enum>
|
---|
10107 |
|
---|
10108 | <interface
|
---|
10109 | name="IMouse" extends="$unknown"
|
---|
10110 | uuid="FD443EC1-0006-4F5B-9282-D72760A66916"
|
---|
10111 | wsmap="managed"
|
---|
10112 | >
|
---|
10113 | <desc>
|
---|
10114 | The IMouse interface represents the virtual machine's mouse. Used in
|
---|
10115 | <link to="IConsole::mouse"/>.
|
---|
10116 |
|
---|
10117 | Through this interface, the virtual machine's virtual mouse can be
|
---|
10118 | controlled.
|
---|
10119 | </desc>
|
---|
10120 |
|
---|
10121 | <attribute name="absoluteSupported" type="boolean" readonly="yes">
|
---|
10122 | <desc>
|
---|
10123 | Whether the guest OS supports absolute mouse pointer positioning
|
---|
10124 | or not.
|
---|
10125 | <note>
|
---|
10126 | VirtualBox Guest Tools need to be installed to the guest OS
|
---|
10127 | in order to enable absolute mouse positioning support.
|
---|
10128 | You can use the <link to="IConsoleCallback::onMouseCapabilityChange"/>
|
---|
10129 | callback to be instantly informed about changes of this attribute
|
---|
10130 | during virtual machine execution.
|
---|
10131 | </note>
|
---|
10132 | <see><link to="#putMouseEventAbsolute"/></see>
|
---|
10133 | </desc>
|
---|
10134 | </attribute>
|
---|
10135 |
|
---|
10136 | <method name="putMouseEvent">
|
---|
10137 | <desc>
|
---|
10138 | Initiates a mouse event using relative pointer movements
|
---|
10139 | along x and y axis.
|
---|
10140 |
|
---|
10141 | <result name="E_ACCESSDENIED">
|
---|
10142 | Console not powered up.
|
---|
10143 | </result>
|
---|
10144 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10145 | Could not send mouse event to virtual mouse.
|
---|
10146 | </result>
|
---|
10147 |
|
---|
10148 | </desc>
|
---|
10149 |
|
---|
10150 | <param name="dx" type="long" dir="in">
|
---|
10151 | <desc>
|
---|
10152 | Amount of pixels the mouse should move to the right.
|
---|
10153 | Negative values move the mouse to the left.
|
---|
10154 | </desc>
|
---|
10155 | </param>
|
---|
10156 | <param name="dy" type="long" dir="in">
|
---|
10157 | <desc>
|
---|
10158 | Amount of pixels the mouse should move downwards.
|
---|
10159 | Negative values move the mouse upwards.
|
---|
10160 | </desc>
|
---|
10161 | </param>
|
---|
10162 | <param name="dz" type="long" dir="in">
|
---|
10163 | <desc>
|
---|
10164 | Amount of mouse wheel moves.
|
---|
10165 | Positive values describe clockwise wheel rotations,
|
---|
10166 | negative values describe counterclockwise rotations.
|
---|
10167 | </desc>
|
---|
10168 | </param>
|
---|
10169 | <param name="buttonState" type="long" dir="in">
|
---|
10170 | <desc>
|
---|
10171 | The current state of mouse buttons. Every bit represents
|
---|
10172 | a mouse button as follows:
|
---|
10173 | <table>
|
---|
10174 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
10175 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
10176 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
10177 | </table>
|
---|
10178 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
10179 | otherwise it is released.
|
---|
10180 | </desc>
|
---|
10181 | </param>
|
---|
10182 | </method>
|
---|
10183 |
|
---|
10184 | <method name="putMouseEventAbsolute">
|
---|
10185 | <desc>
|
---|
10186 | Positions the mouse pointer using absolute x and y coordinates.
|
---|
10187 | These coordinates are expressed in pixels and
|
---|
10188 | start from <tt>[1,1]</tt> which corresponds to the top left
|
---|
10189 | corner of the virtual display.
|
---|
10190 |
|
---|
10191 | <result name="E_ACCESSDENIED">
|
---|
10192 | Console not powered up.
|
---|
10193 | </result>
|
---|
10194 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10195 | Could not send mouse event to virtual mouse.
|
---|
10196 | </result>
|
---|
10197 |
|
---|
10198 | <note>
|
---|
10199 | This method will have effect only if absolute mouse
|
---|
10200 | positioning is supported by the guest OS.
|
---|
10201 | </note>
|
---|
10202 |
|
---|
10203 | <see><link to="#absoluteSupported"/></see>
|
---|
10204 | </desc>
|
---|
10205 |
|
---|
10206 | <param name="x" type="long" dir="in">
|
---|
10207 | <desc>
|
---|
10208 | X coordinate of the pointer in pixels, starting from <tt>1</tt>.
|
---|
10209 | </desc>
|
---|
10210 | </param>
|
---|
10211 | <param name="y" type="long" dir="in">
|
---|
10212 | <desc>
|
---|
10213 | Y coordinate of the pointer in pixels, starting from <tt>1</tt>.
|
---|
10214 | </desc>
|
---|
10215 | </param>
|
---|
10216 | <param name="dz" type="long" dir="in">
|
---|
10217 | <desc>
|
---|
10218 | Amount of mouse wheel moves.
|
---|
10219 | Positive values describe clockwise wheel rotations,
|
---|
10220 | negative values describe counterclockwise rotations.
|
---|
10221 | </desc>
|
---|
10222 | </param>
|
---|
10223 | <param name="buttonState" type="long" dir="in">
|
---|
10224 | <desc>
|
---|
10225 | The current state of mouse buttons. Every bit represents
|
---|
10226 | a mouse button as follows:
|
---|
10227 | <table>
|
---|
10228 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
10229 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
10230 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
10231 | </table>
|
---|
10232 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
10233 | otherwise it is released.
|
---|
10234 | </desc>
|
---|
10235 | </param>
|
---|
10236 | </method>
|
---|
10237 |
|
---|
10238 | </interface>
|
---|
10239 |
|
---|
10240 | <!--
|
---|
10241 | // IDisplay
|
---|
10242 | /////////////////////////////////////////////////////////////////////////
|
---|
10243 | -->
|
---|
10244 |
|
---|
10245 | <enum
|
---|
10246 | name="FramebufferAccelerationOperation"
|
---|
10247 | uuid="f0e5ebbe-dc8e-4e2d-916e-53baa3844df8"
|
---|
10248 | >
|
---|
10249 | <desc>
|
---|
10250 | Frame buffer acceleration operation.
|
---|
10251 | </desc>
|
---|
10252 |
|
---|
10253 | <const name="SolidFillAcceleration" value="1"/>
|
---|
10254 | <const name="ScreenCopyAcceleration" value="2"/>
|
---|
10255 | </enum>
|
---|
10256 |
|
---|
10257 | <enum
|
---|
10258 | name="FramebufferPixelFormat"
|
---|
10259 | uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
|
---|
10260 | >
|
---|
10261 | <desc>
|
---|
10262 | Format of the video memory buffer. Constants represented by this enum can
|
---|
10263 | be used to test for particular values of <link
|
---|
10264 | to="IFramebuffer::pixelFormat"/>. See also <link
|
---|
10265 | to="IFramebuffer::requestResize"/>.
|
---|
10266 |
|
---|
10267 | See also www.fourcc.org for more information about FOURCC pixel formats.
|
---|
10268 | </desc>
|
---|
10269 |
|
---|
10270 | <const name="Opaque" value="0">
|
---|
10271 | <desc>
|
---|
10272 | Unknown buffer format (the user may not assume any particular format of
|
---|
10273 | the buffer).
|
---|
10274 | </desc>
|
---|
10275 | </const>
|
---|
10276 | <const name="FOURCC_RGB" value="0x32424752">
|
---|
10277 | <desc>
|
---|
10278 | Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
|
---|
10279 | bit layout).
|
---|
10280 | </desc>
|
---|
10281 | </const>
|
---|
10282 | </enum>
|
---|
10283 |
|
---|
10284 | <interface
|
---|
10285 | name="IFramebuffer" extends="$unknown"
|
---|
10286 | uuid="af431304-5b09-40e2-94da-3c3cb03822c1"
|
---|
10287 | wsmap="suppress"
|
---|
10288 | >
|
---|
10289 | <attribute name="address" type="octet" mod="ptr" readonly="yes">
|
---|
10290 | <desc>Address of the start byte of the frame buffer.</desc>
|
---|
10291 | </attribute>
|
---|
10292 |
|
---|
10293 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
10294 | <desc>Frame buffer width, in pixels.</desc>
|
---|
10295 | </attribute>
|
---|
10296 |
|
---|
10297 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
10298 | <desc>Frame buffer height, in pixels.</desc>
|
---|
10299 | </attribute>
|
---|
10300 |
|
---|
10301 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
10302 | <desc>
|
---|
10303 | Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
|
---|
10304 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
|
---|
10305 | are: 8, 15, 16, 24 and 32.
|
---|
10306 | </desc>
|
---|
10307 | </attribute>
|
---|
10308 |
|
---|
10309 | <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
|
---|
10310 | <desc>
|
---|
10311 | Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
|
---|
10312 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
|
---|
10313 | size of the scan line must be aligned to 32 bits.
|
---|
10314 | </desc>
|
---|
10315 | </attribute>
|
---|
10316 |
|
---|
10317 | <attribute name="pixelFormat" type="unsigned long" readonly="yes">
|
---|
10318 | <desc>
|
---|
10319 | Frame buffer pixel format. It's either one of the values defined by <link
|
---|
10320 | to="FramebufferPixelFormat"/> or a raw FOURCC code.
|
---|
10321 | <note>
|
---|
10322 | This attribute must never return <link
|
---|
10323 | to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
|
---|
10324 | <link to="#address"/> points to must be always known.
|
---|
10325 | </note>
|
---|
10326 | </desc>
|
---|
10327 | </attribute>
|
---|
10328 |
|
---|
10329 | <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
|
---|
10330 | <desc>
|
---|
10331 | Defines whether this frame buffer uses the virtual video card's memory
|
---|
10332 | buffer (guest VRAM) directly or not. See <link
|
---|
10333 | to="IFramebuffer::requestResize"/> for more information.
|
---|
10334 | </desc>
|
---|
10335 | </attribute>
|
---|
10336 |
|
---|
10337 | <attribute name="heightReduction" type="unsigned long" readonly="yes">
|
---|
10338 | <desc>
|
---|
10339 | Hint from the frame buffer about how much of the standard
|
---|
10340 | screen height it wants to use for itself. This information is
|
---|
10341 | exposed to the guest through the VESA BIOS and VMMDev interface
|
---|
10342 | so that it can use it for determining its video mode table. It
|
---|
10343 | is not guaranteed that the guest respects the value.
|
---|
10344 | </desc>
|
---|
10345 | </attribute>
|
---|
10346 |
|
---|
10347 | <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
|
---|
10348 | <desc>
|
---|
10349 | An alpha-blended overlay which is superposed over the frame buffer.
|
---|
10350 | The initial purpose is to allow the display of icons providing
|
---|
10351 | information about the VM state, including disk activity, in front
|
---|
10352 | ends which do not have other means of doing that. The overlay is
|
---|
10353 | designed to controlled exclusively by IDisplay. It has no locking
|
---|
10354 | of its own, and any changes made to it are not guaranteed to be
|
---|
10355 | visible until the affected portion of IFramebuffer is updated. The
|
---|
10356 | overlay can be created lazily the first time it is requested. This
|
---|
10357 | attribute can also return NULL to signal that the overlay is not
|
---|
10358 | implemented.
|
---|
10359 | </desc>
|
---|
10360 | </attribute>
|
---|
10361 |
|
---|
10362 | <attribute name="winId" type="unsigned long long" readonly="yes">
|
---|
10363 | <desc>
|
---|
10364 | Platform-dependent identifier of the window where context of this
|
---|
10365 | frame buffer is drawn, or zero if there's no such window.
|
---|
10366 | </desc>
|
---|
10367 | </attribute>
|
---|
10368 |
|
---|
10369 | <method name="lock">
|
---|
10370 | <desc>
|
---|
10371 | Locks the frame buffer.
|
---|
10372 | Gets called by the IDisplay object where this frame buffer is
|
---|
10373 | bound to.
|
---|
10374 | </desc>
|
---|
10375 | </method>
|
---|
10376 |
|
---|
10377 | <method name="unlock">
|
---|
10378 | <desc>
|
---|
10379 | Unlocks the frame buffer.
|
---|
10380 | Gets called by the IDisplay object where this frame buffer is
|
---|
10381 | bound to.
|
---|
10382 | </desc>
|
---|
10383 | </method>
|
---|
10384 |
|
---|
10385 | <method name="notifyUpdate">
|
---|
10386 | <desc>
|
---|
10387 | Informs about an update.
|
---|
10388 | Gets called by the display object where this buffer is
|
---|
10389 | registered.
|
---|
10390 | </desc>
|
---|
10391 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10392 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10393 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10394 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10395 | <param name="finished" type="boolean" dir="return"/>
|
---|
10396 | </method>
|
---|
10397 |
|
---|
10398 | <method name="requestResize">
|
---|
10399 | <desc>
|
---|
10400 | Requests a size and pixel format change.
|
---|
10401 |
|
---|
10402 | There are two modes of working with the video buffer of the virtual
|
---|
10403 | machine. The <i>indirect</i> mode implies that the IFramebuffer
|
---|
10404 | implementation allocates a memory buffer for the requested display mode
|
---|
10405 | and provides it to the virtual machine. In <i>direct</i> mode, the
|
---|
10406 | IFramebuffer implementation uses the memory buffer allocated and owned
|
---|
10407 | by the virtual machine. This buffer represents the video memory of the
|
---|
10408 | emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
|
---|
10409 | usually faster because the implementation gets a raw pointer to the
|
---|
10410 | guest VRAM buffer which it can directly use for visualizing the contents
|
---|
10411 | of the virtual display, as opposed to the indirect mode where the
|
---|
10412 | contents of guest VRAM are copied to the memory buffer provided by
|
---|
10413 | the implementation every time a display update occurs.
|
---|
10414 |
|
---|
10415 | It is important to note that the direct mode is really fast only when
|
---|
10416 | the implementation uses the given guest VRAM buffer directly, for
|
---|
10417 | example, by blitting it to the window representing the virtual machine's
|
---|
10418 | display, which saves at least one copy operation comparing to the
|
---|
10419 | indirect mode. However, using the guest VRAM buffer directly is not
|
---|
10420 | always possible: the format and the color depth of this buffer may be
|
---|
10421 | not supported by the target window, or it may be unknown (opaque) as in
|
---|
10422 | case of text or non-linear multi-plane VGA video modes. In this case,
|
---|
10423 | the indirect mode (that is always available) should be used as a
|
---|
10424 | fallback: when the guest VRAM contents are copied to the
|
---|
10425 | implementation-provided memory buffer, color and format conversion is
|
---|
10426 | done automatically by the underlying code.
|
---|
10427 |
|
---|
10428 | The @a pixelFormat parameter defines whether the direct mode is
|
---|
10429 | available or not. If @a pixelFormat is <link
|
---|
10430 | to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
|
---|
10431 | VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
|
---|
10432 | @a bytesPerLine parameters must be ignored and the implementation must use
|
---|
10433 | the indirect mode (where it provides its own buffer in one of the
|
---|
10434 | supported formats). In all other cases, @a pixelFormat together with
|
---|
10435 | @a bitsPerPixel and @a bytesPerLine define the format of the video memory
|
---|
10436 | buffer pointed to by the @a VRAM parameter and the implementation is
|
---|
10437 | free to choose which mode to use. To indicate that this frame buffer uses
|
---|
10438 | the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
|
---|
10439 | attribute must return <tt>true</tt> and <link to="#address"/> must
|
---|
10440 | return exactly the same address that is passed in the @a VRAM parameter
|
---|
10441 | of this method; otherwise it is assumed that the indirect strategy is
|
---|
10442 | chosen.
|
---|
10443 |
|
---|
10444 | The @a width and @a height parameters represent the size of the
|
---|
10445 | requested display mode in both modes. In case of indirect mode, the
|
---|
10446 | provided memory buffer should be big enough to store data of the given
|
---|
10447 | display mode. In case of direct mode, it is guaranteed that the given
|
---|
10448 | @a VRAM buffer contains enough space to represent the display mode of the
|
---|
10449 | given size. Note that this frame buffer's <link to="#width"/> and <link
|
---|
10450 | to="#height"/> attributes must return exactly the same values as
|
---|
10451 | passed to this method after the resize is completed (see below).
|
---|
10452 |
|
---|
10453 | The @a finished output parameter determines if the implementation has
|
---|
10454 | finished resizing the frame buffer or not. If, for some reason, the
|
---|
10455 | resize cannot be finished immediately during this call, @a finished
|
---|
10456 | must be set to @c false, and the implementation must call
|
---|
10457 | <link to="IDisplay::resizeCompleted"/> after it has returned from
|
---|
10458 | this method as soon as possible. If @a finished is @c false, the
|
---|
10459 | machine will not call any frame buffer methods until
|
---|
10460 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
10461 |
|
---|
10462 | Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
|
---|
10463 | <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
|
---|
10464 | this frame buffer must return exactly the same values as specified in the
|
---|
10465 | parameters of this method, after the resize is completed. If the
|
---|
10466 | indirect mode is chosen, these attributes must return values describing
|
---|
10467 | the format of the implementation's own memory buffer <link
|
---|
10468 | to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
|
---|
10469 | value must always correlate with <link to="#pixelFormat"/>. Note that
|
---|
10470 | the <link to="#pixelFormat"/> attribute must never return <link
|
---|
10471 | to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
|
---|
10472 |
|
---|
10473 | <note>
|
---|
10474 | This method is called by the IDisplay object under the
|
---|
10475 | <link to="#lock"/> provided by this IFramebuffer
|
---|
10476 | implementation. If this method returns @c false in @a finished, then
|
---|
10477 | this lock is not released until
|
---|
10478 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
10479 | </note>
|
---|
10480 | </desc>
|
---|
10481 | <param name="screenId" type="unsigned long" dir="in">
|
---|
10482 | <desc>
|
---|
10483 | Logical screen number. Must be used in the corresponding call to
|
---|
10484 | <link to="IDisplay::resizeCompleted"/> if this call is made.
|
---|
10485 | </desc>
|
---|
10486 | </param>
|
---|
10487 | <param name="pixelFormat" type="unsigned long" dir="in">
|
---|
10488 | <desc>
|
---|
10489 | Pixel format of the memory buffer pointed to by @a VRAM.
|
---|
10490 | See also <link to="FramebufferPixelFormat"/>.
|
---|
10491 | </desc>
|
---|
10492 | </param>
|
---|
10493 | <param name="VRAM" type="octet" mod="ptr" dir="in">
|
---|
10494 | <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
|
---|
10495 | </param>
|
---|
10496 | <param name="bitsPerPixel" type="unsigned long" dir="in">
|
---|
10497 | <desc>Color depth, bits per pixel.</desc>
|
---|
10498 | </param>
|
---|
10499 | <param name="bytesPerLine" type="unsigned long" dir="in">
|
---|
10500 | <desc>Size of one scan line, in bytes.</desc>
|
---|
10501 | </param>
|
---|
10502 | <param name="width" type="unsigned long" dir="in">
|
---|
10503 | <desc>Width of the guest display, in pixels.</desc>
|
---|
10504 | </param>
|
---|
10505 | <param name="height" type="unsigned long" dir="in">
|
---|
10506 | <desc>Height of the guest display, in pixels.</desc>
|
---|
10507 | </param>
|
---|
10508 | <param name="finished" type="boolean" dir="return">
|
---|
10509 | <desc>
|
---|
10510 | Can the VM start using the new frame buffer immediately
|
---|
10511 | after this method returns or it should wait for
|
---|
10512 | <link to="IDisplay::resizeCompleted"/>.
|
---|
10513 | </desc>
|
---|
10514 | </param>
|
---|
10515 | </method>
|
---|
10516 |
|
---|
10517 | <method name="operationSupported">
|
---|
10518 | <desc>
|
---|
10519 | Returns whether the given acceleration operation is supported
|
---|
10520 | by the IFramebuffer implementation. If not, the display object
|
---|
10521 | will not attempt to call the corresponding IFramebuffer entry
|
---|
10522 | point. Even if an operation is indicated as supported, the
|
---|
10523 | IFramebuffer implementation always has the option to return non
|
---|
10524 | supported from the corresponding acceleration method in which
|
---|
10525 | case the operation will be performed by the display engine. This
|
---|
10526 | allows for reduced IFramebuffer implementation complexity where
|
---|
10527 | only common cases are handled.
|
---|
10528 | </desc>
|
---|
10529 | <param name="operation" type="FramebufferAccelerationOperation" dir="in"/>
|
---|
10530 | <param name="supported" type="boolean" dir="return"/>
|
---|
10531 | </method>
|
---|
10532 |
|
---|
10533 | <method name="videoModeSupported">
|
---|
10534 | <desc>
|
---|
10535 | Returns whether the frame buffer implementation is willing to
|
---|
10536 | support a given video mode. In case it is not able to render
|
---|
10537 | the video mode (or for some reason not willing), it should
|
---|
10538 | return false. Usually this method is called when the guest
|
---|
10539 | asks the VMM device whether a given video mode is supported
|
---|
10540 | so the information returned is directly exposed to the guest.
|
---|
10541 | It is important that this method returns very quickly.
|
---|
10542 | </desc>
|
---|
10543 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10544 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10545 | <param name="bpp" type="unsigned long" dir="in"/>
|
---|
10546 | <param name="supported" type="boolean" dir="return"/>
|
---|
10547 | </method>
|
---|
10548 |
|
---|
10549 | <method name="solidFill">
|
---|
10550 | <desc>
|
---|
10551 | Fills the specified rectangle on screen with a solid color.
|
---|
10552 | </desc>
|
---|
10553 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10554 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10555 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10556 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10557 | <param name="color" type="unsigned long" dir="in"/>
|
---|
10558 | <param name="handled" type="boolean" dir="return"/>
|
---|
10559 | </method>
|
---|
10560 |
|
---|
10561 | <method name="copyScreenBits">
|
---|
10562 | <desc>
|
---|
10563 | Copies specified rectangle on the screen.
|
---|
10564 | </desc>
|
---|
10565 | <param name="xDst" type="unsigned long" dir="in"/>
|
---|
10566 | <param name="yDst" type="unsigned long" dir="in"/>
|
---|
10567 | <param name="xSrc" type="unsigned long" dir="in"/>
|
---|
10568 | <param name="ySrc" type="unsigned long" dir="in"/>
|
---|
10569 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10570 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10571 | <param name="handled" type="boolean" dir="return"/>
|
---|
10572 | </method>
|
---|
10573 |
|
---|
10574 | <method name="getVisibleRegion">
|
---|
10575 | <desc>
|
---|
10576 | Returns the visible region of this frame buffer.
|
---|
10577 |
|
---|
10578 | If the @a rectangles parameter is <tt>NULL</tt> then the value of the
|
---|
10579 | @a count parameter is ignored and the number of elements necessary to
|
---|
10580 | describe the current visible region is returned in @a countCopied.
|
---|
10581 |
|
---|
10582 | If @a rectangles is not <tt>NULL</tt> but @a count is less
|
---|
10583 | than the required number of elements to store region data, the method
|
---|
10584 | will report a failure. If @a count is equal or greater than the
|
---|
10585 | required number of elements, then the actual number of elements copied
|
---|
10586 | to the provided array will be returned in @a countCopied.
|
---|
10587 |
|
---|
10588 | <note>
|
---|
10589 | The address of the provided array must be in the process space of
|
---|
10590 | this IFramebuffer object.
|
---|
10591 | </note>
|
---|
10592 | <note>
|
---|
10593 | Method not yet implemented.
|
---|
10594 | </note>
|
---|
10595 | </desc>
|
---|
10596 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
10597 | <desc>Pointer to the <tt>RTRECT</tt> array to receive region data.</desc>
|
---|
10598 | </param>
|
---|
10599 | <param name="count" type="unsigned long" dir="in">
|
---|
10600 | <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
|
---|
10601 | </param>
|
---|
10602 | <param name="countCopied" type="unsigned long" dir="return">
|
---|
10603 | <desc>Number of elements copied to the @a rectangles array.</desc>
|
---|
10604 | </param>
|
---|
10605 | </method>
|
---|
10606 |
|
---|
10607 | <method name="setVisibleRegion">
|
---|
10608 | <desc>
|
---|
10609 | Suggests a new visible region to this frame buffer. This region
|
---|
10610 | represents the area of the VM display which is a union of regions of
|
---|
10611 | all top-level windows of the guest operating system running inside the
|
---|
10612 | VM (if the Guest Additions for this system support this
|
---|
10613 | functionality). This information may be used by the frontends to
|
---|
10614 | implement the seamless desktop integration feature.
|
---|
10615 |
|
---|
10616 | <note>
|
---|
10617 | The address of the provided array must be in the process space of
|
---|
10618 | this IFramebuffer object.
|
---|
10619 | </note>
|
---|
10620 | <note>
|
---|
10621 | The IFramebuffer implementation must make a copy of the provided
|
---|
10622 | array of rectangles.
|
---|
10623 | </note>
|
---|
10624 | <note>
|
---|
10625 | Method not yet implemented.
|
---|
10626 | </note>
|
---|
10627 | </desc>
|
---|
10628 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
10629 | <desc>Pointer to the <tt>RTRECT</tt> array.</desc>
|
---|
10630 | </param>
|
---|
10631 | <param name="count" type="unsigned long" dir="in">
|
---|
10632 | <desc>Number of <tt>RTRECT</tt> elements in the @a rectangles array.</desc>
|
---|
10633 | </param>
|
---|
10634 | </method>
|
---|
10635 |
|
---|
10636 | </interface>
|
---|
10637 |
|
---|
10638 | <interface
|
---|
10639 | name="IFramebufferOverlay" extends="IFramebuffer"
|
---|
10640 | uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
|
---|
10641 | wsmap="suppress"
|
---|
10642 | >
|
---|
10643 | <desc>
|
---|
10644 | The IFramebufferOverlay interface represents an alpha blended overlay
|
---|
10645 | for displaying status icons above an IFramebuffer. It is always created
|
---|
10646 | not visible, so that it must be explicitly shown. It only covers a
|
---|
10647 | portion of the IFramebuffer, determined by its width, height and
|
---|
10648 | co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
|
---|
10649 | that order) format, and may be written to directly. Do re-read the
|
---|
10650 | width though, after setting it, as it may be adjusted (increased) to
|
---|
10651 | make it more suitable for the front end.
|
---|
10652 | </desc>
|
---|
10653 | <attribute name="x" type="unsigned long" readonly="yes">
|
---|
10654 | <desc>X position of the overlay, relative to the frame buffer.</desc>
|
---|
10655 | </attribute>
|
---|
10656 |
|
---|
10657 | <attribute name="y" type="unsigned long" readonly="yes">
|
---|
10658 | <desc>Y position of the overlay, relative to the frame buffer.</desc>
|
---|
10659 | </attribute>
|
---|
10660 |
|
---|
10661 | <attribute name="visible" type="boolean" readonly="no">
|
---|
10662 | <desc>
|
---|
10663 | Whether the overlay is currently visible.
|
---|
10664 | </desc>
|
---|
10665 | </attribute>
|
---|
10666 |
|
---|
10667 | <attribute name="alpha" type="unsigned long" readonly="no">
|
---|
10668 | <desc>
|
---|
10669 | The global alpha value for the overlay. This may or may not be
|
---|
10670 | supported by a given front end.
|
---|
10671 | </desc>
|
---|
10672 | </attribute>
|
---|
10673 |
|
---|
10674 | <method name="move">
|
---|
10675 | <desc>
|
---|
10676 | Changes the overlay's position relative to the IFramebuffer.
|
---|
10677 | </desc>
|
---|
10678 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10679 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10680 | </method>
|
---|
10681 |
|
---|
10682 | </interface>
|
---|
10683 |
|
---|
10684 | <interface
|
---|
10685 | name="IDisplay" extends="$unknown"
|
---|
10686 | uuid="09789f63-4525-48e5-a5e4-1080453b0eab"
|
---|
10687 | wsmap="suppress"
|
---|
10688 | >
|
---|
10689 | <desc>
|
---|
10690 | The IDisplay interface represents the virtual machine's display.
|
---|
10691 |
|
---|
10692 | The object implementing this interface is contained in each
|
---|
10693 | <link to="IConsole::display"/> attribute and represents the visual
|
---|
10694 | output of the virtual machine.
|
---|
10695 |
|
---|
10696 | The virtual display supports pluggable output targets represented by the
|
---|
10697 | IFramebuffer interface. Examples of the output target are a window on
|
---|
10698 | the host computer or an RDP session's display on a remote computer.
|
---|
10699 | </desc>
|
---|
10700 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
10701 | <desc>Current display width.</desc>
|
---|
10702 | </attribute>
|
---|
10703 |
|
---|
10704 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
10705 | <desc>Current display height.</desc>
|
---|
10706 | </attribute>
|
---|
10707 |
|
---|
10708 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
10709 | <desc>
|
---|
10710 | Current guest display color depth. Note that this may differ
|
---|
10711 | from <link to="IFramebuffer::bitsPerPixel"/>.
|
---|
10712 | </desc>
|
---|
10713 | </attribute>
|
---|
10714 |
|
---|
10715 | <method name="setupInternalFramebuffer">
|
---|
10716 | <desc>
|
---|
10717 | Prepares an internally managed frame buffer.
|
---|
10718 | </desc>
|
---|
10719 | <param name="depth" type="unsigned long" dir="in"/>
|
---|
10720 | </method>
|
---|
10721 |
|
---|
10722 | <method name="lockFramebuffer">
|
---|
10723 | <desc>
|
---|
10724 | Requests access to the internal frame buffer.
|
---|
10725 |
|
---|
10726 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10727 | Attempt to lock a non-internal frame buffer.
|
---|
10728 | </result>
|
---|
10729 |
|
---|
10730 | </desc>
|
---|
10731 | <param name="address" type="octet" mod="ptr" dir="return"/>
|
---|
10732 | </method>
|
---|
10733 |
|
---|
10734 | <method name="unlockFramebuffer">
|
---|
10735 | <desc>
|
---|
10736 | Releases access to the internal frame buffer.
|
---|
10737 |
|
---|
10738 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10739 | Attempt to unlock a non-internal frame buffer.
|
---|
10740 | </result>
|
---|
10741 |
|
---|
10742 | </desc>
|
---|
10743 | </method>
|
---|
10744 |
|
---|
10745 | <method name="registerExternalFramebuffer">
|
---|
10746 | <desc>
|
---|
10747 | Registers an external frame buffer.
|
---|
10748 | </desc>
|
---|
10749 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
10750 | </method>
|
---|
10751 |
|
---|
10752 | <method name="setFramebuffer">
|
---|
10753 | <desc>
|
---|
10754 | Sets the framebuffer for given screen.
|
---|
10755 | </desc>
|
---|
10756 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10757 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
10758 | </method>
|
---|
10759 |
|
---|
10760 | <method name="getFramebuffer">
|
---|
10761 | <desc>
|
---|
10762 | Queries the framebuffer for given screen.
|
---|
10763 | </desc>
|
---|
10764 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10765 | <param name="framebuffer" type="IFramebuffer" dir="out"/>
|
---|
10766 | <param name="xOrigin" type="long" dir="out"/>
|
---|
10767 | <param name="yOrigin" type="long" dir="out"/>
|
---|
10768 | </method>
|
---|
10769 |
|
---|
10770 | <method name="setVideoModeHint">
|
---|
10771 | <desc>
|
---|
10772 | Asks VirtualBox to request the given video mode from
|
---|
10773 | the guest. This is just a hint and it cannot be guaranteed
|
---|
10774 | that the requested resolution will be used. Guest Additions
|
---|
10775 | are required for the request to be seen by guests. The caller
|
---|
10776 | should issue the request and wait for a resolution change and
|
---|
10777 | after a timeout retry.
|
---|
10778 |
|
---|
10779 | Specifying <tt>0</tt> for either @a width, @a height or @a bitsPerPixel
|
---|
10780 | parameters means that the corresponding values should be taken from the
|
---|
10781 | current video mode (i.e. left unchanged).
|
---|
10782 |
|
---|
10783 | If the guest OS supports multi-monitor configuration then the @a display
|
---|
10784 | parameter specifies the number of the guest display to send the hint to:
|
---|
10785 | <tt>0</tt> is the primary display, <tt>1</tt> is the first secondary and
|
---|
10786 | so on. If the multi-monitor configuration is not supported, @a display
|
---|
10787 | must be <tt>0</tt>.
|
---|
10788 |
|
---|
10789 | <result name="E_INVALIDARG">
|
---|
10790 | The @a display is not associated with any monitor.
|
---|
10791 | </result>
|
---|
10792 |
|
---|
10793 | </desc>
|
---|
10794 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10795 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10796 | <param name="bitsPerPixel" type="unsigned long" dir="in"/>
|
---|
10797 | <param name="display" type="unsigned long" dir="in"/>
|
---|
10798 | </method>
|
---|
10799 |
|
---|
10800 | <method name="setSeamlessMode">
|
---|
10801 | <desc>
|
---|
10802 | Enables or disables seamless guest display rendering (seamless desktop
|
---|
10803 | integration) mode.
|
---|
10804 | <note>
|
---|
10805 | Calling this method has no effect if <link
|
---|
10806 | to="IGuest::supportsSeamless"/> returns <tt>false</tt>.
|
---|
10807 | </note>
|
---|
10808 | </desc>
|
---|
10809 | <param name="enabled" type="boolean" dir="in"/>
|
---|
10810 | </method>
|
---|
10811 |
|
---|
10812 | <method name="takeScreenShot">
|
---|
10813 | <desc>
|
---|
10814 | Takes a screen shot of the requested size and copies it to the
|
---|
10815 | 32-bpp buffer allocated by the caller.
|
---|
10816 |
|
---|
10817 | <result name="E_NOTIMPL">
|
---|
10818 | Feature not implemented.
|
---|
10819 | </result>
|
---|
10820 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10821 | Could not take a screenshot.
|
---|
10822 | </result>
|
---|
10823 |
|
---|
10824 | </desc>
|
---|
10825 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
10826 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10827 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10828 | </method>
|
---|
10829 |
|
---|
10830 | <method name="drawToScreen">
|
---|
10831 | <desc>
|
---|
10832 | Draws a 32-bpp image of the specified size from the given buffer
|
---|
10833 | to the given point on the VM display.
|
---|
10834 |
|
---|
10835 | <result name="E_NOTIMPL">
|
---|
10836 | Feature not implemented.
|
---|
10837 | </result>
|
---|
10838 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10839 | Could not draw to screen.
|
---|
10840 | </result>
|
---|
10841 |
|
---|
10842 | </desc>
|
---|
10843 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
10844 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10845 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10846 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10847 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10848 | </method>
|
---|
10849 |
|
---|
10850 | <method name="invalidateAndUpdate">
|
---|
10851 | <desc>
|
---|
10852 | Does a full invalidation of the VM display and instructs the VM
|
---|
10853 | to update it.
|
---|
10854 |
|
---|
10855 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10856 | Could not invalidate and update screen.
|
---|
10857 | </result>
|
---|
10858 |
|
---|
10859 | </desc>
|
---|
10860 | </method>
|
---|
10861 |
|
---|
10862 | <method name="resizeCompleted">
|
---|
10863 | <desc>
|
---|
10864 | Signals that a framebuffer has completed the resize operation.
|
---|
10865 |
|
---|
10866 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10867 | Operation only valid for external frame buffers.
|
---|
10868 | </result>
|
---|
10869 |
|
---|
10870 | </desc>
|
---|
10871 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10872 | </method>
|
---|
10873 |
|
---|
10874 | <method name="updateCompleted">
|
---|
10875 | <desc>
|
---|
10876 | Signals that a framebuffer has completed the update operation.
|
---|
10877 |
|
---|
10878 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10879 | Operation only valid for external frame buffers.
|
---|
10880 | </result>
|
---|
10881 |
|
---|
10882 | </desc>
|
---|
10883 | </method>
|
---|
10884 |
|
---|
10885 | </interface>
|
---|
10886 |
|
---|
10887 | <!--
|
---|
10888 | // INetworkAdapter
|
---|
10889 | /////////////////////////////////////////////////////////////////////////
|
---|
10890 | -->
|
---|
10891 |
|
---|
10892 | <enum
|
---|
10893 | name="NetworkAttachmentType"
|
---|
10894 | uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
|
---|
10895 | >
|
---|
10896 | <desc>
|
---|
10897 | Network attachment type.
|
---|
10898 | </desc>
|
---|
10899 |
|
---|
10900 | <const name="Null" value="0">
|
---|
10901 | <desc>Null value, also means "not attached".</desc>
|
---|
10902 | </const>
|
---|
10903 | <const name="NAT" value="1"/>
|
---|
10904 | <const name="Bridged" value="2"/>
|
---|
10905 | <const name="Internal" value="3"/>
|
---|
10906 | <const name="HostOnly" value="4"/>
|
---|
10907 | </enum>
|
---|
10908 |
|
---|
10909 | <enum
|
---|
10910 | name="NetworkAdapterType"
|
---|
10911 | uuid="50c3dfd8-07ac-4a31-baac-519c828fbf97"
|
---|
10912 | >
|
---|
10913 | <desc>
|
---|
10914 | Network adapter type.
|
---|
10915 | </desc>
|
---|
10916 |
|
---|
10917 | <const name="Null" value="0">
|
---|
10918 | <desc>Null value (never used by the API).</desc>
|
---|
10919 | </const>
|
---|
10920 | <const name="Am79C970A" value="1">
|
---|
10921 | <desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
|
---|
10922 | </const>
|
---|
10923 | <const name="Am79C973" value="2">
|
---|
10924 | <desc>AMD PCNet-FAST III network card (Am79C973).</desc>
|
---|
10925 | </const>
|
---|
10926 | <const name="I82540EM" value="3">
|
---|
10927 | <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
|
---|
10928 | </const>
|
---|
10929 | <const name="I82543GC" value="4">
|
---|
10930 | <desc>Intel PRO/1000 T Server network card (82543GC).</desc>
|
---|
10931 | </const>
|
---|
10932 | <const name="I82545EM" value="5">
|
---|
10933 | <desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
|
---|
10934 | </const>
|
---|
10935 | </enum>
|
---|
10936 |
|
---|
10937 | <interface
|
---|
10938 | name="INetworkAdapter" extends="$unknown"
|
---|
10939 | uuid="65607a27-2b73-4d43-b4cc-0ba2c817fbde"
|
---|
10940 | wsmap="managed"
|
---|
10941 | >
|
---|
10942 | <desc>
|
---|
10943 | Represents a virtual network adapter that is attached to a virtual machine.
|
---|
10944 | Each virtual machine has a fixed number of network adapter slots with one
|
---|
10945 | instance of this attached to each of them. Call
|
---|
10946 | <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
|
---|
10947 | is attached to a given slot in a given machine.
|
---|
10948 |
|
---|
10949 | Each network adapter can be in one of five attachment modes, which are
|
---|
10950 | represented by the <link to="NetworkAttachmentType" /> enumeration;
|
---|
10951 | see the <link to="#attachmentType" /> attribute.
|
---|
10952 | </desc>
|
---|
10953 |
|
---|
10954 | <attribute name="adapterType" type="NetworkAdapterType">
|
---|
10955 | <desc>
|
---|
10956 | Type of the virtual network adapter. Depending on this value,
|
---|
10957 | VirtualBox will provide a different virtual network hardware
|
---|
10958 | to the guest.
|
---|
10959 | </desc>
|
---|
10960 | </attribute>
|
---|
10961 |
|
---|
10962 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
10963 | <desc>
|
---|
10964 | Slot number this adapter is plugged into. Corresponds to
|
---|
10965 | the value you pass to <link to="IMachine::getNetworkAdapter"/>
|
---|
10966 | to obtain this instance.
|
---|
10967 | </desc>
|
---|
10968 | </attribute>
|
---|
10969 |
|
---|
10970 | <attribute name="enabled" type="boolean">
|
---|
10971 | <desc>
|
---|
10972 | Flag whether the network adapter is present in the
|
---|
10973 | guest system. If disabled, the virtual guest hardware will
|
---|
10974 | not contain this network adapter. Can only be changed when
|
---|
10975 | the VM is not running.
|
---|
10976 | </desc>
|
---|
10977 | </attribute>
|
---|
10978 |
|
---|
10979 | <attribute name="MACAddress" type="wstring">
|
---|
10980 | <desc>
|
---|
10981 | Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
|
---|
10982 | it to NULL, VirtualBox will generate a unique MAC address.
|
---|
10983 | </desc>
|
---|
10984 | </attribute>
|
---|
10985 |
|
---|
10986 | <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
|
---|
10987 |
|
---|
10988 | <attribute name="hostInterface" type="wstring">
|
---|
10989 | <desc>
|
---|
10990 | Name of the host network interface the VM is attached to.
|
---|
10991 | </desc>
|
---|
10992 | </attribute>
|
---|
10993 |
|
---|
10994 | <attribute name="internalNetwork" type="wstring">
|
---|
10995 | <desc>
|
---|
10996 | Name of the internal network the VM is attached to.
|
---|
10997 | </desc>
|
---|
10998 | </attribute>
|
---|
10999 |
|
---|
11000 | <attribute name="NATNetwork" type="wstring">
|
---|
11001 | <desc>
|
---|
11002 | Name of the NAT network the VM is attached to.
|
---|
11003 | </desc>
|
---|
11004 | </attribute>
|
---|
11005 |
|
---|
11006 | <attribute name="cableConnected" type="boolean">
|
---|
11007 | <desc>
|
---|
11008 | Flag whether the adapter reports the cable as connected or not.
|
---|
11009 | It can be used to report offline situations to a VM.
|
---|
11010 | </desc>
|
---|
11011 | </attribute>
|
---|
11012 |
|
---|
11013 | <attribute name="lineSpeed" type="unsigned long">
|
---|
11014 | <desc>
|
---|
11015 | Line speed reported by custom drivers, in units of 1 kbps.
|
---|
11016 | </desc>
|
---|
11017 | </attribute>
|
---|
11018 |
|
---|
11019 | <attribute name="traceEnabled" type="boolean">
|
---|
11020 | <desc>
|
---|
11021 | Flag whether network traffic from/to the network card should be traced.
|
---|
11022 | Can only be toggled when the VM is turned off.
|
---|
11023 | </desc>
|
---|
11024 | </attribute>
|
---|
11025 |
|
---|
11026 | <attribute name="traceFile" type="wstring">
|
---|
11027 | <desc>
|
---|
11028 | Filename where a network trace will be stored. If not set, VBox-pid.pcap
|
---|
11029 | will be used.
|
---|
11030 | </desc>
|
---|
11031 | </attribute>
|
---|
11032 |
|
---|
11033 | <method name="attachToNAT">
|
---|
11034 | <desc>
|
---|
11035 | Attach the network adapter to the Network Address Translation (NAT) interface.
|
---|
11036 | </desc>
|
---|
11037 | </method>
|
---|
11038 |
|
---|
11039 | <method name="attachToBridgedInterface">
|
---|
11040 | <desc>
|
---|
11041 | Attach the network adapter to a bridged host interface.
|
---|
11042 | </desc>
|
---|
11043 | </method>
|
---|
11044 |
|
---|
11045 | <method name="attachToInternalNetwork">
|
---|
11046 | <desc>
|
---|
11047 | Attach the network adapter to an internal network.
|
---|
11048 | </desc>
|
---|
11049 | </method>
|
---|
11050 |
|
---|
11051 | <method name="attachToHostOnlyInterface">
|
---|
11052 | <desc>
|
---|
11053 | Attach the network adapter to the host-only network.
|
---|
11054 | </desc>
|
---|
11055 | </method>
|
---|
11056 |
|
---|
11057 | <method name="detach">
|
---|
11058 | <desc>
|
---|
11059 | Detach the network adapter
|
---|
11060 | </desc>
|
---|
11061 | </method>
|
---|
11062 | </interface>
|
---|
11063 |
|
---|
11064 |
|
---|
11065 | <!--
|
---|
11066 | // ISerialPort
|
---|
11067 | /////////////////////////////////////////////////////////////////////////
|
---|
11068 | -->
|
---|
11069 |
|
---|
11070 | <enum
|
---|
11071 | name="PortMode"
|
---|
11072 | uuid="b266f43c-2e93-46b3-812b-c20e600e867b"
|
---|
11073 | >
|
---|
11074 | <desc>
|
---|
11075 | The PortMode enumeration represents possible communication modes for
|
---|
11076 | the virtual serial port device.
|
---|
11077 | </desc>
|
---|
11078 |
|
---|
11079 | <const name="Disconnected" value="0">
|
---|
11080 | <desc>Virtual device is not attached to any real host device.</desc>
|
---|
11081 | </const>
|
---|
11082 | <const name="HostPipe" value="1">
|
---|
11083 | <desc>Virtual device is attached to a host pipe.</desc>
|
---|
11084 | </const>
|
---|
11085 | <const name="HostDevice" value="2">
|
---|
11086 | <desc>Virtual device is attached to a host device.</desc>
|
---|
11087 | </const>
|
---|
11088 | </enum>
|
---|
11089 |
|
---|
11090 | <interface
|
---|
11091 | name="ISerialPort" extends="$unknown"
|
---|
11092 | uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
|
---|
11093 | wsmap="managed"
|
---|
11094 | >
|
---|
11095 |
|
---|
11096 | <desc>
|
---|
11097 | The ISerialPort interface represents the virtual serial port device.
|
---|
11098 |
|
---|
11099 | The virtual serial port device acts like an ordinary serial port
|
---|
11100 | inside the virtual machine. This device communicates to the real
|
---|
11101 | serial port hardware in one of two modes: host pipe or host device.
|
---|
11102 |
|
---|
11103 | In host pipe mode, the #path attribute specifies the path to the pipe on
|
---|
11104 | the host computer that represents a serial port. The #server attribute
|
---|
11105 | determines if this pipe is created by the virtual machine process at
|
---|
11106 | machine startup or it must already exist before starting machine
|
---|
11107 | execution.
|
---|
11108 |
|
---|
11109 | In host device mode, the #path attribute specifies the name of the
|
---|
11110 | serial port device on the host computer.
|
---|
11111 |
|
---|
11112 | There is also a third communication mode: the disconnected mode. In this
|
---|
11113 | mode, the guest OS running inside the virtual machine will be able to
|
---|
11114 | detect the serial port, but all port write operations will be discarded
|
---|
11115 | and all port read operations will return no data.
|
---|
11116 |
|
---|
11117 | <see>IMachine::getSerialPort</see>
|
---|
11118 | </desc>
|
---|
11119 |
|
---|
11120 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11121 | <desc>
|
---|
11122 | Slot number this serial port is plugged into. Corresponds to
|
---|
11123 | the value you pass to <link to="IMachine::getSerialPort"/>
|
---|
11124 | to obtain this instance.
|
---|
11125 | </desc>
|
---|
11126 | </attribute>
|
---|
11127 |
|
---|
11128 | <attribute name="enabled" type="boolean">
|
---|
11129 | <desc>
|
---|
11130 | Flag whether the serial port is enabled. If disabled,
|
---|
11131 | the serial port will not be reported to the guest OS.
|
---|
11132 | </desc>
|
---|
11133 | </attribute>
|
---|
11134 |
|
---|
11135 | <attribute name="IOBase" type="unsigned long">
|
---|
11136 | <desc>Base I/O address of the serial port.</desc>
|
---|
11137 | </attribute>
|
---|
11138 |
|
---|
11139 | <attribute name="IRQ" type="unsigned long">
|
---|
11140 | <desc>IRQ number of the serial port.</desc>
|
---|
11141 | </attribute>
|
---|
11142 |
|
---|
11143 | <attribute name="hostMode" type="PortMode">
|
---|
11144 | <desc>
|
---|
11145 | How is this port connected to the host.
|
---|
11146 | <note>
|
---|
11147 | Changing this attribute may fail if the conditions for
|
---|
11148 | <link to="#path"/> are not met.
|
---|
11149 | </note>
|
---|
11150 | </desc>
|
---|
11151 | </attribute>
|
---|
11152 |
|
---|
11153 | <attribute name="server" type="boolean">
|
---|
11154 | <desc>
|
---|
11155 | Flag whether this serial port acts as a server (creates a new pipe on
|
---|
11156 | the host) or as a client (uses the existing pipe). This attribute is
|
---|
11157 | used only when <link to="#hostMode"/> is PortMode_HostPipe.
|
---|
11158 | </desc>
|
---|
11159 | </attribute>
|
---|
11160 |
|
---|
11161 | <attribute name="path" type="wstring">
|
---|
11162 | <desc>
|
---|
11163 | Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
|
---|
11164 | PortMode_HostPipe, or the host serial device name when
|
---|
11165 | <link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
|
---|
11166 | cases, setting a @c null or empty string as the attribute's value
|
---|
11167 | is an error. Otherwise, the value of this property is ignored.
|
---|
11168 | </desc>
|
---|
11169 | </attribute>
|
---|
11170 |
|
---|
11171 | </interface>
|
---|
11172 |
|
---|
11173 | <!--
|
---|
11174 | // IParallelPort
|
---|
11175 | /////////////////////////////////////////////////////////////////////////
|
---|
11176 | -->
|
---|
11177 |
|
---|
11178 | <interface
|
---|
11179 | name="IParallelPort" extends="$unknown"
|
---|
11180 | uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
|
---|
11181 | wsmap="managed"
|
---|
11182 | >
|
---|
11183 |
|
---|
11184 | <desc>
|
---|
11185 | The IParallelPort interface represents the virtual parallel port device.
|
---|
11186 |
|
---|
11187 | The virtual parallel port device acts like an ordinary parallel port
|
---|
11188 | inside the virtual machine. This device communicates to the real
|
---|
11189 | parallel port hardware using the name of the parallel device on the host
|
---|
11190 | computer specified in the #path attribute.
|
---|
11191 |
|
---|
11192 | Each virtual parallel port device is assigned a base I/O address and an
|
---|
11193 | IRQ number that will be reported to the guest operating system and used
|
---|
11194 | to operate the given parallel port from within the virtual machine.
|
---|
11195 |
|
---|
11196 | <see>IMachine::getParallelPort</see>
|
---|
11197 | </desc>
|
---|
11198 |
|
---|
11199 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11200 | <desc>
|
---|
11201 | Slot number this parallel port is plugged into. Corresponds to
|
---|
11202 | the value you pass to <link to="IMachine::getParallelPort"/>
|
---|
11203 | to obtain this instance.
|
---|
11204 | </desc>
|
---|
11205 | </attribute>
|
---|
11206 |
|
---|
11207 | <attribute name="enabled" type="boolean">
|
---|
11208 | <desc>
|
---|
11209 | Flag whether the parallel port is enabled. If disabled,
|
---|
11210 | the parallel port will not be reported to the guest OS.
|
---|
11211 | </desc>
|
---|
11212 | </attribute>
|
---|
11213 |
|
---|
11214 | <attribute name="IOBase" type="unsigned long">
|
---|
11215 | <desc>Base I/O address of the parallel port.</desc>
|
---|
11216 | </attribute>
|
---|
11217 |
|
---|
11218 | <attribute name="IRQ" type="unsigned long">
|
---|
11219 | <desc>IRQ number of the parallel port.</desc>
|
---|
11220 | </attribute>
|
---|
11221 |
|
---|
11222 | <attribute name="path" type="wstring">
|
---|
11223 | <desc>
|
---|
11224 | Host parallel device name. If this parallel port is enabled, setting a
|
---|
11225 | @c null or an empty string as this attribute's value will result into
|
---|
11226 | an error.
|
---|
11227 | </desc>
|
---|
11228 | </attribute>
|
---|
11229 |
|
---|
11230 | </interface>
|
---|
11231 |
|
---|
11232 |
|
---|
11233 | <!--
|
---|
11234 | // IMachineDebugger
|
---|
11235 | /////////////////////////////////////////////////////////////////////////
|
---|
11236 | -->
|
---|
11237 |
|
---|
11238 | <interface
|
---|
11239 | name="IMachineDebugger" extends="$unknown"
|
---|
11240 | uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
|
---|
11241 | wsmap="suppress"
|
---|
11242 | >
|
---|
11243 | <method name="resetStats">
|
---|
11244 | <desc>
|
---|
11245 | Reset VM statistics.
|
---|
11246 | </desc>
|
---|
11247 | <param name="pattern" type="wstring" dir="in">
|
---|
11248 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11249 | </param>
|
---|
11250 | </method>
|
---|
11251 |
|
---|
11252 | <method name="dumpStats">
|
---|
11253 | <desc>
|
---|
11254 | Dumps VM statistics.
|
---|
11255 | </desc>
|
---|
11256 | <param name="pattern" type="wstring" dir="in">
|
---|
11257 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11258 | </param>
|
---|
11259 | </method>
|
---|
11260 |
|
---|
11261 | <method name="getStats">
|
---|
11262 | <desc>
|
---|
11263 | Get the VM statistics in a XMLish format.
|
---|
11264 | </desc>
|
---|
11265 | <param name="pattern" type="wstring" dir="in">
|
---|
11266 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11267 | </param>
|
---|
11268 | <param name="withDescriptions" type="boolean" dir="in">
|
---|
11269 | <desc>Whether to include the descriptions.</desc>
|
---|
11270 | </param>
|
---|
11271 | <param name="stats" type="wstring" dir="out">
|
---|
11272 | <desc>The XML document containing the statistics.</desc>
|
---|
11273 | </param>
|
---|
11274 | </method>
|
---|
11275 |
|
---|
11276 | <method name="injectNMI">
|
---|
11277 | <desc>
|
---|
11278 | Inject an NMI into a running VT-x/AMD-V VM.
|
---|
11279 | </desc>
|
---|
11280 | </method>
|
---|
11281 |
|
---|
11282 | <attribute name="singlestep" type="boolean">
|
---|
11283 | <desc>Switch for enabling singlestepping.</desc>
|
---|
11284 | </attribute>
|
---|
11285 |
|
---|
11286 | <attribute name="recompileUser" type="boolean">
|
---|
11287 | <desc>Switch for forcing code recompilation for user mode code.</desc>
|
---|
11288 | </attribute>
|
---|
11289 |
|
---|
11290 | <attribute name="recompileSupervisor" type="boolean">
|
---|
11291 | <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
|
---|
11292 | </attribute>
|
---|
11293 |
|
---|
11294 | <attribute name="PATMEnabled" type="boolean">
|
---|
11295 | <desc>Switch for enabling and disabling the PATM component.</desc>
|
---|
11296 | </attribute>
|
---|
11297 |
|
---|
11298 | <attribute name="CSAMEnabled" type="boolean">
|
---|
11299 | <desc>Switch for enabling and disabling the CSAM component.</desc>
|
---|
11300 | </attribute>
|
---|
11301 |
|
---|
11302 | <attribute name="logEnabled" type="boolean">
|
---|
11303 | <desc>Switch for enabling and disabling logging.</desc>
|
---|
11304 | </attribute>
|
---|
11305 |
|
---|
11306 | <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
|
---|
11307 | <desc>
|
---|
11308 | Flag indicating whether the VM is currently making use of CPU hardware
|
---|
11309 | virtualization extensions.
|
---|
11310 | </desc>
|
---|
11311 | </attribute>
|
---|
11312 |
|
---|
11313 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
|
---|
11314 | <desc>
|
---|
11315 | Flag indicating whether the VM is currently making use of the nested paging
|
---|
11316 | CPU hardware virtualization extension.
|
---|
11317 | </desc>
|
---|
11318 | </attribute>
|
---|
11319 |
|
---|
11320 | <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
|
---|
11321 | <desc>
|
---|
11322 | Flag indicating whether the VM is currently making use of the VPID
|
---|
11323 | VT-x extension.
|
---|
11324 | </desc>
|
---|
11325 | </attribute>
|
---|
11326 |
|
---|
11327 | <attribute name="PAEEnabled" type="boolean" readonly="yes">
|
---|
11328 | <desc>
|
---|
11329 | Flag indicating whether the VM is currently making use of the Physical
|
---|
11330 | Address Extension CPU feature.
|
---|
11331 | </desc>
|
---|
11332 | </attribute>
|
---|
11333 |
|
---|
11334 | <attribute name="virtualTimeRate" type="unsigned long">
|
---|
11335 | <desc>
|
---|
11336 | The rate at which the virtual time runs expressed as a percentage.
|
---|
11337 | The accepted range is 2% to 20000%.
|
---|
11338 | </desc>
|
---|
11339 | </attribute>
|
---|
11340 |
|
---|
11341 | <!-- @todo method for setting log flags, groups and destination! -->
|
---|
11342 |
|
---|
11343 | <attribute name="VM" type="unsigned long long" readonly="yes">
|
---|
11344 | <desc>
|
---|
11345 | Gets the VM handle. This is only for internal use while
|
---|
11346 | we carve the details of this interface.
|
---|
11347 | </desc>
|
---|
11348 | </attribute>
|
---|
11349 |
|
---|
11350 | </interface>
|
---|
11351 |
|
---|
11352 | <!--
|
---|
11353 | // IUSBController
|
---|
11354 | /////////////////////////////////////////////////////////////////////////
|
---|
11355 | -->
|
---|
11356 |
|
---|
11357 | <interface
|
---|
11358 | name="IUSBController" extends="$unknown"
|
---|
11359 | uuid="238540fa-4b73-435a-a38e-4e1d9eab5c17"
|
---|
11360 | wsmap="managed"
|
---|
11361 | >
|
---|
11362 | <attribute name="enabled" type="boolean">
|
---|
11363 | <desc>
|
---|
11364 | Flag whether the USB controller is present in the
|
---|
11365 | guest system. If disabled, the virtual guest hardware will
|
---|
11366 | not contain any USB controller. Can only be changed when
|
---|
11367 | the VM is powered off.
|
---|
11368 | </desc>
|
---|
11369 | </attribute>
|
---|
11370 |
|
---|
11371 | <attribute name="enabledEhci" type="boolean">
|
---|
11372 | <desc>
|
---|
11373 | Flag whether the USB EHCI controller is present in the
|
---|
11374 | guest system. If disabled, the virtual guest hardware will
|
---|
11375 | not contain a USB EHCI controller. Can only be changed when
|
---|
11376 | the VM is powered off.
|
---|
11377 | </desc>
|
---|
11378 | </attribute>
|
---|
11379 |
|
---|
11380 | <attribute name="USBStandard" type="unsigned short" readonly="yes">
|
---|
11381 | <desc>
|
---|
11382 | USB standard version which the controller implements.
|
---|
11383 | This is a BCD which means that the major version is in the
|
---|
11384 | high byte and minor version is in the low byte.
|
---|
11385 | </desc>
|
---|
11386 | </attribute>
|
---|
11387 |
|
---|
11388 | <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
11389 | <desc>
|
---|
11390 | List of USB device filters associated with the machine.
|
---|
11391 |
|
---|
11392 | If the machine is currently running, these filters are activated
|
---|
11393 | every time a new (supported) USB device is attached to the host
|
---|
11394 | computer that was not ignored by global filters
|
---|
11395 | (<link to="IHost::USBDeviceFilters"/>).
|
---|
11396 |
|
---|
11397 | These filters are also activated when the machine is powered up.
|
---|
11398 | They are run against a list of all currently available USB
|
---|
11399 | devices (in states
|
---|
11400 | <link to="USBDeviceState_Available"/>,
|
---|
11401 | <link to="USBDeviceState_Busy"/>,
|
---|
11402 | <link to="USBDeviceState_Held"/>) that were not previously
|
---|
11403 | ignored by global filters.
|
---|
11404 |
|
---|
11405 | If at least one filter matches the USB device in question, this
|
---|
11406 | device is automatically captured (attached to) the virtual USB
|
---|
11407 | controller of this machine.
|
---|
11408 |
|
---|
11409 | <see>IUSBDeviceFilter, ::IUSBController</see>
|
---|
11410 | </desc>
|
---|
11411 | </attribute>
|
---|
11412 |
|
---|
11413 | <method name="createDeviceFilter">
|
---|
11414 | <desc>
|
---|
11415 | Creates a new USB device filter. All attributes except
|
---|
11416 | the filter name are set to <tt>null</tt> (any match),
|
---|
11417 | <i>active</i> is <tt>false</tt> (the filter is not active).
|
---|
11418 |
|
---|
11419 | The created filter can then be added to the list of filters using
|
---|
11420 | <link to="#insertDeviceFilter"/>.
|
---|
11421 |
|
---|
11422 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11423 | The virtual machine is not mutable.
|
---|
11424 | </result>
|
---|
11425 |
|
---|
11426 | <see>#deviceFilters</see>
|
---|
11427 | </desc>
|
---|
11428 | <param name="name" type="wstring" dir="in">
|
---|
11429 | <desc>
|
---|
11430 | Filter name. See <link to="IUSBDeviceFilter::name"/>
|
---|
11431 | for more info.
|
---|
11432 | </desc>
|
---|
11433 | </param>
|
---|
11434 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
11435 | <desc>Created filter object.</desc>
|
---|
11436 | </param>
|
---|
11437 | </method>
|
---|
11438 |
|
---|
11439 | <method name="insertDeviceFilter">
|
---|
11440 | <desc>
|
---|
11441 | Inserts the given USB device to the specified position
|
---|
11442 | in the list of filters.
|
---|
11443 |
|
---|
11444 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
11445 | position is equal to or greater than the number of elements in
|
---|
11446 | the list, the filter is added to the end of the collection.
|
---|
11447 |
|
---|
11448 | <note>
|
---|
11449 | Duplicates are not allowed, so an attempt to insert a
|
---|
11450 | filter that is already in the collection, will return an
|
---|
11451 | error.
|
---|
11452 | </note>
|
---|
11453 |
|
---|
11454 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11455 | Virtual machine is not mutable.
|
---|
11456 | </result>
|
---|
11457 | <result name="E_INVALIDARG">
|
---|
11458 | USB device filter not created within this VirtualBox instance.
|
---|
11459 | </result>
|
---|
11460 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
11461 | USB device filter already in list.
|
---|
11462 | </result>
|
---|
11463 |
|
---|
11464 | <see>#deviceFilters</see>
|
---|
11465 | </desc>
|
---|
11466 | <param name="position" type="unsigned long" dir="in">
|
---|
11467 | <desc>Position to insert the filter to.</desc>
|
---|
11468 | </param>
|
---|
11469 | <param name="filter" type="IUSBDeviceFilter" dir="in">
|
---|
11470 | <desc>USB device filter to insert.</desc>
|
---|
11471 | </param>
|
---|
11472 | </method>
|
---|
11473 |
|
---|
11474 | <method name="removeDeviceFilter">
|
---|
11475 | <desc>
|
---|
11476 | Removes a USB device filter from the specified position in the
|
---|
11477 | list of filters.
|
---|
11478 |
|
---|
11479 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
11480 | position equal to or greater than the number of elements in
|
---|
11481 | the list will produce an error.
|
---|
11482 |
|
---|
11483 | <see>#deviceFilters</see>
|
---|
11484 |
|
---|
11485 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11486 | Virtual machine is not mutable.
|
---|
11487 | </result>
|
---|
11488 | <result name="E_INVALIDARG">
|
---|
11489 | USB device filter list empty or invalid @a position.
|
---|
11490 | </result>
|
---|
11491 |
|
---|
11492 | </desc>
|
---|
11493 | <param name="position" type="unsigned long" dir="in">
|
---|
11494 | <desc>Position to remove the filter from.</desc>
|
---|
11495 | </param>
|
---|
11496 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
11497 | <desc>Removed USB device filter.</desc>
|
---|
11498 | </param>
|
---|
11499 | </method>
|
---|
11500 |
|
---|
11501 | </interface>
|
---|
11502 |
|
---|
11503 |
|
---|
11504 | <!--
|
---|
11505 | // IUSBDevice
|
---|
11506 | /////////////////////////////////////////////////////////////////////////
|
---|
11507 | -->
|
---|
11508 |
|
---|
11509 | <interface
|
---|
11510 | name="IUSBDevice" extends="$unknown"
|
---|
11511 | uuid="850af07b-9ee8-48c2-b6b0-f6d0acbf63c3"
|
---|
11512 | wsmap="managed"
|
---|
11513 | >
|
---|
11514 | <desc>
|
---|
11515 | The IUSBDevice interface represents a virtual USB device attached to the
|
---|
11516 | virtual machine.
|
---|
11517 |
|
---|
11518 | A collection of objects implementing this interface is stored in the
|
---|
11519 | <link to="IConsole::USBDevices"/> attribute which lists all USB devices
|
---|
11520 | attached to a running virtual machine's USB controller.
|
---|
11521 | </desc>
|
---|
11522 |
|
---|
11523 | <attribute name="id" type="uuid" readonly="yes">
|
---|
11524 | <desc>
|
---|
11525 | Unique USB device ID. This ID is built from #vendorId,
|
---|
11526 | #productId, #revision and #serialNumber.
|
---|
11527 | </desc>
|
---|
11528 | </attribute>
|
---|
11529 |
|
---|
11530 | <attribute name="vendorId" type="unsigned short" readonly="yes">
|
---|
11531 | <desc>Vendor ID.</desc>
|
---|
11532 | </attribute>
|
---|
11533 |
|
---|
11534 | <attribute name="productId" type="unsigned short" readonly="yes">
|
---|
11535 | <desc>Product ID.</desc>
|
---|
11536 | </attribute>
|
---|
11537 |
|
---|
11538 | <attribute name="revision" type="unsigned short" readonly="yes">
|
---|
11539 | <desc>
|
---|
11540 | Product revision number. This is a packed BCD represented as
|
---|
11541 | unsigned short. The high byte is the integer part and the low
|
---|
11542 | byte is the decimal.
|
---|
11543 | </desc>
|
---|
11544 | </attribute>
|
---|
11545 |
|
---|
11546 | <attribute name="manufacturer" type="wstring" readonly="yes">
|
---|
11547 | <desc>Manufacturer string.</desc>
|
---|
11548 | </attribute>
|
---|
11549 |
|
---|
11550 | <attribute name="product" type="wstring" readonly="yes">
|
---|
11551 | <desc>Product string.</desc>
|
---|
11552 | </attribute>
|
---|
11553 |
|
---|
11554 | <attribute name="serialNumber" type="wstring" readonly="yes">
|
---|
11555 | <desc>Serial number string.</desc>
|
---|
11556 | </attribute>
|
---|
11557 |
|
---|
11558 | <attribute name="address" type="wstring" readonly="yes">
|
---|
11559 | <desc>Host specific address of the device.</desc>
|
---|
11560 | </attribute>
|
---|
11561 |
|
---|
11562 | <attribute name="port" type="unsigned short" readonly="yes">
|
---|
11563 | <desc>
|
---|
11564 | Host USB port number the device is physically
|
---|
11565 | connected to.
|
---|
11566 | </desc>
|
---|
11567 | </attribute>
|
---|
11568 |
|
---|
11569 | <attribute name="version" type="unsigned short" readonly="yes">
|
---|
11570 | <desc>
|
---|
11571 | The major USB version of the device - 1 or 2.
|
---|
11572 | </desc>
|
---|
11573 | </attribute>
|
---|
11574 |
|
---|
11575 | <attribute name="portVersion" type="unsigned short" readonly="yes">
|
---|
11576 | <desc>
|
---|
11577 | The major USB version of the host USB port the device is
|
---|
11578 | physically connected to - 1 or 2. For devices not connected to
|
---|
11579 | anything this will have the same value as the version attribute.
|
---|
11580 | </desc>
|
---|
11581 | </attribute>
|
---|
11582 |
|
---|
11583 | <attribute name="remote" type="boolean" readonly="yes">
|
---|
11584 | <desc>
|
---|
11585 | Whether the device is physically connected to a remote VRDP
|
---|
11586 | client or to a local host machine.
|
---|
11587 | </desc>
|
---|
11588 | </attribute>
|
---|
11589 |
|
---|
11590 | </interface>
|
---|
11591 |
|
---|
11592 |
|
---|
11593 | <!--
|
---|
11594 | // IUSBDeviceFilter
|
---|
11595 | /////////////////////////////////////////////////////////////////////////
|
---|
11596 | -->
|
---|
11597 |
|
---|
11598 | <interface
|
---|
11599 | name="IUSBDeviceFilter" extends="$unknown"
|
---|
11600 | uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
|
---|
11601 | wsmap="managed"
|
---|
11602 | >
|
---|
11603 | <desc>
|
---|
11604 | The IUSBDeviceFilter interface represents an USB device filter used
|
---|
11605 | to perform actions on a group of USB devices.
|
---|
11606 |
|
---|
11607 | This type of filters is used by running virtual machines to
|
---|
11608 | automatically capture selected USB devices once they are physically
|
---|
11609 | attached to the host computer.
|
---|
11610 |
|
---|
11611 | A USB device is matched to the given device filter if and only if all
|
---|
11612 | attributes of the device match the corresponding attributes of the
|
---|
11613 | filter (that is, attributes are joined together using the logical AND
|
---|
11614 | operation). On the other hand, all together, filters in the list of
|
---|
11615 | filters carry the semantics of the logical OR operation. So if it is
|
---|
11616 | desirable to create a match like "this vendor id OR this product id",
|
---|
11617 | one needs to create two filters and specify "any match" (see below)
|
---|
11618 | for unused attributes.
|
---|
11619 |
|
---|
11620 | All filter attributes used for matching are strings. Each string
|
---|
11621 | is an expression representing a set of values of the corresponding
|
---|
11622 | device attribute, that will match the given filter. Currently, the
|
---|
11623 | following filtering expressions are supported:
|
---|
11624 |
|
---|
11625 | <ul>
|
---|
11626 | <li><i>Interval filters</i>. Used to specify valid intervals for
|
---|
11627 | integer device attributes (Vendor ID, Product ID and Revision).
|
---|
11628 | The format of the string is:
|
---|
11629 |
|
---|
11630 | <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
|
---|
11631 |
|
---|
11632 | where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
|
---|
11633 | (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
|
---|
11634 | or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
|
---|
11635 | is omitted before a dash (<tt>-</tt>), the minimum possible integer
|
---|
11636 | is assumed; if <tt>n</tt> is omitted after a dash, the maximum
|
---|
11637 | possible integer is assumed.
|
---|
11638 | </li>
|
---|
11639 | <li><i>Boolean filters</i>. Used to specify acceptable values for
|
---|
11640 | boolean device attributes. The format of the string is:
|
---|
11641 |
|
---|
11642 | <tt>true|false|yes|no|0|1</tt>
|
---|
11643 |
|
---|
11644 | </li>
|
---|
11645 | <li><i>Exact match</i>. Used to specify a single value for the given
|
---|
11646 | device attribute. Any string that doesn't start with <tt>int:</tt>
|
---|
11647 | represents the exact match. String device attributes are compared to
|
---|
11648 | this string including case of symbols. Integer attributes are first
|
---|
11649 | converted to a string (see individual filter attributes) and then
|
---|
11650 | compared ignoring case.
|
---|
11651 |
|
---|
11652 | </li>
|
---|
11653 | <li><i>Any match</i>. Any value of the corresponding device attribute
|
---|
11654 | will match the given filter. An empty or <tt>null</tt> string is
|
---|
11655 | used to construct this type of filtering expressions.
|
---|
11656 |
|
---|
11657 | </li>
|
---|
11658 | </ul>
|
---|
11659 |
|
---|
11660 | <note>
|
---|
11661 | On the Windows host platform, interval filters are not currently
|
---|
11662 | available. Also all string filter attributes
|
---|
11663 | (<link to="#manufacturer"/>, <link to="#product"/>,
|
---|
11664 | <link to="#serialNumber"/>) are ignored, so they behave as
|
---|
11665 | <i>any match</i> no matter what string expression is specified.
|
---|
11666 | </note>
|
---|
11667 |
|
---|
11668 | <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
|
---|
11669 | </desc>
|
---|
11670 |
|
---|
11671 | <attribute name="name" type="wstring">
|
---|
11672 | <desc>
|
---|
11673 | Visible name for this filter.
|
---|
11674 | This name is used to visually distinguish one filter from another,
|
---|
11675 | so it can neither be <tt>null</tt> nor an empty string.
|
---|
11676 | </desc>
|
---|
11677 | </attribute>
|
---|
11678 |
|
---|
11679 | <attribute name="active" type="boolean">
|
---|
11680 | <desc>Whether this filter active or has been temporarily disabled.</desc>
|
---|
11681 | </attribute>
|
---|
11682 |
|
---|
11683 | <attribute name="vendorId" type="wstring">
|
---|
11684 | <desc>
|
---|
11685 | <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
|
---|
11686 | The string representation for the <i>exact matching</i>
|
---|
11687 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
11688 | (including leading zeroes).
|
---|
11689 | </desc>
|
---|
11690 | </attribute>
|
---|
11691 |
|
---|
11692 | <attribute name="productId" type="wstring">
|
---|
11693 | <desc>
|
---|
11694 | <link to="IUSBDevice::productId">Product ID</link> filter.
|
---|
11695 | The string representation for the <i>exact matching</i>
|
---|
11696 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
11697 | (including leading zeroes).
|
---|
11698 | </desc>
|
---|
11699 | </attribute>
|
---|
11700 |
|
---|
11701 | <attribute name="revision" type="wstring">
|
---|
11702 | <desc>
|
---|
11703 | <link to="IUSBDevice::productId">Product revision number</link>
|
---|
11704 | filter. The string representation for the <i>exact matching</i>
|
---|
11705 | has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
|
---|
11706 | of the integer part of the revision, and <tt>F</tt> is the
|
---|
11707 | decimal digit of its fractional part (including leading and
|
---|
11708 | trailing zeros).
|
---|
11709 | Note that for interval filters, it's best to use the hexadecimal
|
---|
11710 | form, because the revision is stored as a 16 bit packed BCD value;
|
---|
11711 | so the expression <tt>int:0x0100-0x0199</tt> will match any
|
---|
11712 | revision from <tt>1.0</tt> to <tt>1.99</tt>.
|
---|
11713 | </desc>
|
---|
11714 | </attribute>
|
---|
11715 |
|
---|
11716 | <attribute name="manufacturer" type="wstring">
|
---|
11717 | <desc>
|
---|
11718 | <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
|
---|
11719 | </desc>
|
---|
11720 | </attribute>
|
---|
11721 |
|
---|
11722 | <attribute name="product" type="wstring">
|
---|
11723 | <desc>
|
---|
11724 | <link to="IUSBDevice::product">Product</link> filter.
|
---|
11725 | </desc>
|
---|
11726 | </attribute>
|
---|
11727 |
|
---|
11728 | <attribute name="serialNumber" type="wstring">
|
---|
11729 | <desc>
|
---|
11730 | <link to="IUSBDevice::serialNumber">Serial number</link> filter.
|
---|
11731 | </desc>
|
---|
11732 | </attribute>
|
---|
11733 |
|
---|
11734 | <attribute name="port" type="wstring">
|
---|
11735 | <desc>
|
---|
11736 | <link to="IUSBDevice::port">Host USB port</link> filter.
|
---|
11737 | </desc>
|
---|
11738 | </attribute>
|
---|
11739 |
|
---|
11740 | <attribute name="remote" type="wstring">
|
---|
11741 | <desc>
|
---|
11742 | <link to="IUSBDevice::remote">Remote state</link> filter.
|
---|
11743 | <note>
|
---|
11744 | This filter makes sense only for machine USB filters,
|
---|
11745 | i.e. it is ignored by IHostUSBDeviceFilter objects.
|
---|
11746 | </note>
|
---|
11747 | </desc>
|
---|
11748 | </attribute>
|
---|
11749 |
|
---|
11750 | <attribute name="maskedInterfaces" type="unsigned long">
|
---|
11751 | <desc>
|
---|
11752 | This is an advanced option for hiding one or more USB interfaces
|
---|
11753 | from the guest. The value is a bit mask where the bits that are set
|
---|
11754 | means the corresponding USB interface should be hidden, masked off
|
---|
11755 | if you like.
|
---|
11756 | This feature only works on Linux hosts.
|
---|
11757 | </desc>
|
---|
11758 | </attribute>
|
---|
11759 |
|
---|
11760 | </interface>
|
---|
11761 |
|
---|
11762 |
|
---|
11763 | <!--
|
---|
11764 | // IHostUSBDevice
|
---|
11765 | /////////////////////////////////////////////////////////////////////////
|
---|
11766 | -->
|
---|
11767 |
|
---|
11768 | <enum
|
---|
11769 | name="USBDeviceState"
|
---|
11770 | uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
|
---|
11771 | >
|
---|
11772 | <desc>
|
---|
11773 | USB device state. This enumeration represents all possible states
|
---|
11774 | of the USB device physically attached to the host computer regarding
|
---|
11775 | its state on the host computer and availability to guest computers
|
---|
11776 | (all currently running virtual machines).
|
---|
11777 |
|
---|
11778 | Once a supported USB device is attached to the host, global USB
|
---|
11779 | filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
|
---|
11780 | either ignore the device, or put it to USBDeviceState_Held state, or do
|
---|
11781 | nothing. Unless the device is ignored by global filters, filters of all
|
---|
11782 | currently running guests (<link to="IUSBController::deviceFilters"/>) are
|
---|
11783 | activated that can put it to USBDeviceState_Captured state.
|
---|
11784 |
|
---|
11785 | If the device was ignored by global filters, or didn't match
|
---|
11786 | any filters at all (including guest ones), it is handled by the host
|
---|
11787 | in a normal way. In this case, the device state is determined by
|
---|
11788 | the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
|
---|
11789 | or USBDeviceState_Available, depending on the current device usage.
|
---|
11790 |
|
---|
11791 | Besides auto-capturing based on filters, the device can be manually
|
---|
11792 | captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
|
---|
11793 | state is USBDeviceState_Busy, USBDeviceState_Available or
|
---|
11794 | USBDeviceState_Held.
|
---|
11795 |
|
---|
11796 | <note>
|
---|
11797 | Due to differences in USB stack implementations in Linux and Win32,
|
---|
11798 | states USBDeviceState_Busy and USBDeviceState_vailable are applicable
|
---|
11799 | only to the Linux version of the product. This also means that (<link
|
---|
11800 | to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
|
---|
11801 | device state is USBDeviceState_Held.
|
---|
11802 | </note>
|
---|
11803 |
|
---|
11804 | <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
|
---|
11805 | </desc>
|
---|
11806 |
|
---|
11807 | <const name="NotSupported" value="0">
|
---|
11808 | <desc>
|
---|
11809 | Not supported by the VirtualBox server, not available to guests.
|
---|
11810 | </desc>
|
---|
11811 | </const>
|
---|
11812 | <const name="Unavailable" value="1">
|
---|
11813 | <desc>
|
---|
11814 | Being used by the host computer exclusively,
|
---|
11815 | not available to guests.
|
---|
11816 | </desc>
|
---|
11817 | </const>
|
---|
11818 | <const name="Busy" value="2">
|
---|
11819 | <desc>
|
---|
11820 | Being used by the host computer, potentially available to guests.
|
---|
11821 | </desc>
|
---|
11822 | </const>
|
---|
11823 | <const name="Available" value="3">
|
---|
11824 | <desc>
|
---|
11825 | Not used by the host computer, available to guests (the host computer
|
---|
11826 | can also start using the device at any time).
|
---|
11827 | </desc>
|
---|
11828 | </const>
|
---|
11829 | <const name="Held" value="4">
|
---|
11830 | <desc>
|
---|
11831 | Held by the VirtualBox server (ignored by the host computer),
|
---|
11832 | available to guests.
|
---|
11833 | </desc>
|
---|
11834 | </const>
|
---|
11835 | <const name="Captured" value="5">
|
---|
11836 | <desc>
|
---|
11837 | Captured by one of the guest computers, not available
|
---|
11838 | to anybody else.
|
---|
11839 | </desc>
|
---|
11840 | </const>
|
---|
11841 | </enum>
|
---|
11842 |
|
---|
11843 | <interface
|
---|
11844 | name="IHostUSBDevice" extends="IUSBDevice"
|
---|
11845 | uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
|
---|
11846 | wsmap="managed"
|
---|
11847 | >
|
---|
11848 | <desc>
|
---|
11849 | The IHostUSBDevice interface represents a physical USB device attached
|
---|
11850 | to the host computer.
|
---|
11851 |
|
---|
11852 | Besides properties inherited from IUSBDevice, this interface adds the
|
---|
11853 | <link to="#state"/> property that holds the current state of the USB
|
---|
11854 | device.
|
---|
11855 |
|
---|
11856 | <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
|
---|
11857 | </desc>
|
---|
11858 |
|
---|
11859 | <attribute name="state" type="USBDeviceState" readonly="yes">
|
---|
11860 | <desc>
|
---|
11861 | Current state of the device.
|
---|
11862 | </desc>
|
---|
11863 | </attribute>
|
---|
11864 |
|
---|
11865 | <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
|
---|
11866 |
|
---|
11867 | </interface>
|
---|
11868 |
|
---|
11869 |
|
---|
11870 | <!--
|
---|
11871 | // IHostUSBDeviceFilter
|
---|
11872 | /////////////////////////////////////////////////////////////////////////
|
---|
11873 | -->
|
---|
11874 |
|
---|
11875 | <enum
|
---|
11876 | name="USBDeviceFilterAction"
|
---|
11877 | uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
|
---|
11878 | >
|
---|
11879 | <desc>
|
---|
11880 | Actions for host USB device filters.
|
---|
11881 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
11882 | </desc>
|
---|
11883 |
|
---|
11884 | <const name="Null" value="0">
|
---|
11885 | <desc>Null value (never used by the API).</desc>
|
---|
11886 | </const>
|
---|
11887 | <const name="Ignore" value="1">
|
---|
11888 | <desc>Ignore the matched USB device.</desc>
|
---|
11889 | </const>
|
---|
11890 | <const name="Hold" value="2">
|
---|
11891 | <desc>Hold the matched USB device.</desc>
|
---|
11892 | </const>
|
---|
11893 | </enum>
|
---|
11894 |
|
---|
11895 | <interface
|
---|
11896 | name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
|
---|
11897 | uuid="4cc70246-d74a-400f-8222-3900489c0374"
|
---|
11898 | wsmap="managed"
|
---|
11899 | >
|
---|
11900 | <desc>
|
---|
11901 | The IHostUSBDeviceFilter interface represents a global filter for a
|
---|
11902 | physical USB device used by the host computer. Used indirectly in
|
---|
11903 | <link to="IHost::USBDeviceFilters"/>.
|
---|
11904 |
|
---|
11905 | Using filters of this type, the host computer determines the initial
|
---|
11906 | state of the USB device after it is physically attached to the
|
---|
11907 | host's USB controller.
|
---|
11908 |
|
---|
11909 | <note>
|
---|
11910 | The <link to="#remote"/> attribute is ignored by this type of
|
---|
11911 | filters, because it makes sense only for
|
---|
11912 | <link to="IUSBController::deviceFilters">machine USB filters</link>.
|
---|
11913 | </note>
|
---|
11914 |
|
---|
11915 | <see>IHost::USBDeviceFilters</see>
|
---|
11916 | </desc>
|
---|
11917 |
|
---|
11918 | <attribute name="action" type="USBDeviceFilterAction">
|
---|
11919 | <desc>
|
---|
11920 | Action performed by the host when an attached USB device
|
---|
11921 | matches this filter.
|
---|
11922 | </desc>
|
---|
11923 | </attribute>
|
---|
11924 |
|
---|
11925 | </interface>
|
---|
11926 |
|
---|
11927 | <!--
|
---|
11928 | // IAudioAdapter
|
---|
11929 | /////////////////////////////////////////////////////////////////////////
|
---|
11930 | -->
|
---|
11931 |
|
---|
11932 | <enum
|
---|
11933 | name="AudioDriverType"
|
---|
11934 | uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
|
---|
11935 | >
|
---|
11936 | <desc>
|
---|
11937 | Host audio driver type.
|
---|
11938 | </desc>
|
---|
11939 |
|
---|
11940 | <const name="Null" value="0">
|
---|
11941 | <desc>Null value, also means "dummy audio driver".</desc>
|
---|
11942 | </const>
|
---|
11943 | <const name="WinMM" value="1"/>
|
---|
11944 | <const name="OSS" value="2"/>
|
---|
11945 | <const name="ALSA" value="3"/>
|
---|
11946 | <const name="DirectSound" value="4"/>
|
---|
11947 | <const name="CoreAudio" value="5"/>
|
---|
11948 | <const name="MMPM" value="6"/>
|
---|
11949 | <const name="Pulse" value="7"/>
|
---|
11950 | <const name="SolAudio" value="8"/>
|
---|
11951 | </enum>
|
---|
11952 |
|
---|
11953 | <enum
|
---|
11954 | name="AudioControllerType"
|
---|
11955 | uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
|
---|
11956 | >
|
---|
11957 | <desc>
|
---|
11958 | Virtual audio controller type.
|
---|
11959 | </desc>
|
---|
11960 |
|
---|
11961 | <const name="AC97" value="0"/>
|
---|
11962 | <const name="SB16" value="1"/>
|
---|
11963 | </enum>
|
---|
11964 |
|
---|
11965 | <interface
|
---|
11966 | name="IAudioAdapter" extends="$unknown"
|
---|
11967 | uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
|
---|
11968 | wsmap="managed"
|
---|
11969 | >
|
---|
11970 | <desc>
|
---|
11971 | The IAudioAdapter interface represents the virtual audio adapter of
|
---|
11972 | the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
|
---|
11973 | </desc>
|
---|
11974 | <attribute name="enabled" type="boolean">
|
---|
11975 | <desc>
|
---|
11976 | Flag whether the audio adapter is present in the
|
---|
11977 | guest system. If disabled, the virtual guest hardware will
|
---|
11978 | not contain any audio adapter. Can only be changed when
|
---|
11979 | the VM is not running.
|
---|
11980 | </desc>
|
---|
11981 | </attribute>
|
---|
11982 | <attribute name="audioController" type="AudioControllerType">
|
---|
11983 | <desc>
|
---|
11984 | The audio hardware we emulate.
|
---|
11985 | </desc>
|
---|
11986 | </attribute>
|
---|
11987 | <attribute name="audioDriver" type="AudioDriverType">
|
---|
11988 | <desc>
|
---|
11989 | Audio driver the adapter is connected to. This setting
|
---|
11990 | can only be changed when the VM is not running.
|
---|
11991 | </desc>
|
---|
11992 | </attribute>
|
---|
11993 | </interface>
|
---|
11994 |
|
---|
11995 | <!--
|
---|
11996 | // IVRDPServer
|
---|
11997 | /////////////////////////////////////////////////////////////////////////
|
---|
11998 | -->
|
---|
11999 |
|
---|
12000 | <enum
|
---|
12001 | name="VRDPAuthType"
|
---|
12002 | uuid="3d91887a-b67f-4b33-85bf-2da7ab1ea83a"
|
---|
12003 | >
|
---|
12004 | <desc>
|
---|
12005 | VRDP authentication type.
|
---|
12006 | </desc>
|
---|
12007 |
|
---|
12008 | <const name="Null" value="0">
|
---|
12009 | <desc>Null value, also means "no authentication".</desc>
|
---|
12010 | </const>
|
---|
12011 | <const name="External" value="1"/>
|
---|
12012 | <const name="Guest" value="2"/>
|
---|
12013 | </enum>
|
---|
12014 |
|
---|
12015 | <interface
|
---|
12016 | name="IVRDPServer" extends="$unknown"
|
---|
12017 | uuid="f4584ae7-6bce-474b-83d6-17d235e6aa89"
|
---|
12018 | wsmap="managed"
|
---|
12019 | >
|
---|
12020 | <attribute name="enabled" type="boolean">
|
---|
12021 | <desc>VRDP server status.</desc>
|
---|
12022 | </attribute>
|
---|
12023 |
|
---|
12024 | <attribute name="port" type="unsigned long">
|
---|
12025 | <desc>
|
---|
12026 | VRDP server port number.
|
---|
12027 | <note>
|
---|
12028 | Setting the value of this property to <tt>0</tt> will reset the port
|
---|
12029 | number to the default value which is
|
---|
12030 | currently <tt>3389</tt>. Reading this property will always return a
|
---|
12031 | real port number, even after it has been set to <tt>0</tt> (in which
|
---|
12032 | case the default port is returned).
|
---|
12033 | </note>
|
---|
12034 | </desc>
|
---|
12035 | </attribute>
|
---|
12036 |
|
---|
12037 | <attribute name="netAddress" type="wstring">
|
---|
12038 | <desc>VRDP server address.</desc>
|
---|
12039 | </attribute>
|
---|
12040 |
|
---|
12041 | <attribute name="authType" type="VRDPAuthType">
|
---|
12042 | <desc>VRDP authentication method.</desc>
|
---|
12043 | </attribute>
|
---|
12044 |
|
---|
12045 | <attribute name="authTimeout" type="unsigned long">
|
---|
12046 | <desc>Timeout for guest authentication. Milliseconds.</desc>
|
---|
12047 | </attribute>
|
---|
12048 |
|
---|
12049 | <attribute name="allowMultiConnection" type="boolean">
|
---|
12050 | <desc>
|
---|
12051 | Flag whether multiple simultaneous connections to the VM are permitted.
|
---|
12052 | Note that this will be replaced by a more powerful mechanism in the future.
|
---|
12053 | </desc>
|
---|
12054 | </attribute>
|
---|
12055 |
|
---|
12056 | <attribute name="reuseSingleConnection" type="boolean">
|
---|
12057 | <desc>
|
---|
12058 | Flag whether the existing connection must be dropped and a new connection
|
---|
12059 | must be established by the VRDP server, when a new client connects in single
|
---|
12060 | connection mode.
|
---|
12061 | </desc>
|
---|
12062 | </attribute>
|
---|
12063 |
|
---|
12064 | </interface>
|
---|
12065 |
|
---|
12066 |
|
---|
12067 | <!--
|
---|
12068 | // ISharedFolder
|
---|
12069 | /////////////////////////////////////////////////////////////////////////
|
---|
12070 | -->
|
---|
12071 |
|
---|
12072 | <interface
|
---|
12073 | name="ISharedFolder" extends="$unknown"
|
---|
12074 | uuid="64637bb2-9e17-471c-b8f3-f8968dd9884e"
|
---|
12075 | wsmap="struct"
|
---|
12076 | >
|
---|
12077 | <desc>
|
---|
12078 | The ISharedFolder interface represents a folder in the host computer's
|
---|
12079 | file system accessible from the guest OS running inside a virtual
|
---|
12080 | machine using an associated logical name.
|
---|
12081 |
|
---|
12082 | There are three types of shared folders:
|
---|
12083 | <ul>
|
---|
12084 | <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
|
---|
12085 | folders available to all virtual machines.</li>
|
---|
12086 | <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
|
---|
12087 | VM-specific shared folders available to the given virtual machine at
|
---|
12088 | startup.</li>
|
---|
12089 | <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
|
---|
12090 | VM-specific shared folders created in the session context (for
|
---|
12091 | example, when the virtual machine is running) and automatically
|
---|
12092 | discarded when the session is closed (the VM is powered off).</li>
|
---|
12093 | </ul>
|
---|
12094 |
|
---|
12095 | Logical names of shared folders must be unique within the given scope
|
---|
12096 | (global, permanent or transient). However, they do not need to be unique
|
---|
12097 | across scopes. In this case, the definition of the shared folder in a
|
---|
12098 | more specific scope takes precedence over definitions in all other
|
---|
12099 | scopes. The order of precedence is (more specific to more general):
|
---|
12100 | <ol>
|
---|
12101 | <li>Transient definitions</li>
|
---|
12102 | <li>Permanent definitions</li>
|
---|
12103 | <li>Global definitions</li>
|
---|
12104 | </ol>
|
---|
12105 |
|
---|
12106 | For example, if MyMachine has a shared folder named
|
---|
12107 | <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
|
---|
12108 | transient shared folder named <tt>C_DRIVE</tt> (that points
|
---|
12109 | to <tt>C:\\\\WINDOWS</tt>) will change the definition
|
---|
12110 | of <tt>C_DRIVE</tt> in the guest OS so
|
---|
12111 | that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
|
---|
12112 | to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
|
---|
12113 | PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
|
---|
12114 | the previous (permanent) definition of <tt>C_DRIVE</tt> that points
|
---|
12115 | to <tt>C:\\</tt> if it still exists.
|
---|
12116 |
|
---|
12117 | Note that permanent and transient shared folders of different machines
|
---|
12118 | are in different name spaces, so they don't overlap and don't need to
|
---|
12119 | have unique logical names.
|
---|
12120 |
|
---|
12121 | <note>
|
---|
12122 | Global shared folders are not implemented in the current version of the
|
---|
12123 | product.
|
---|
12124 | </note>
|
---|
12125 | </desc>
|
---|
12126 |
|
---|
12127 | <attribute name="name" type="wstring" readonly="yes">
|
---|
12128 | <desc>Logical name of the shared folder.</desc>
|
---|
12129 | </attribute>
|
---|
12130 |
|
---|
12131 | <attribute name="hostPath" type="wstring" readonly="yes">
|
---|
12132 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
12133 | </attribute>
|
---|
12134 |
|
---|
12135 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
12136 | <desc>
|
---|
12137 | Whether the folder defined by the host path is currently
|
---|
12138 | accessible or not.
|
---|
12139 | For example, the folder can be unaccessible if it is placed
|
---|
12140 | on the network share that is not available by the time
|
---|
12141 | this property is read.
|
---|
12142 | </desc>
|
---|
12143 | </attribute>
|
---|
12144 |
|
---|
12145 | <attribute name="writable" type="boolean" readonly="yes">
|
---|
12146 | <desc>
|
---|
12147 | Whether the folder defined by the host path is writable or
|
---|
12148 | not.
|
---|
12149 | </desc>
|
---|
12150 | </attribute>
|
---|
12151 |
|
---|
12152 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
12153 | <desc>
|
---|
12154 | Text message that represents the result of the last accessibility
|
---|
12155 | check.
|
---|
12156 |
|
---|
12157 | Accessibility checks are performed each time the <link to="#accessible"/>
|
---|
12158 | attribute is read. A @c null string is returned if the last
|
---|
12159 | accessibility check was successful. A non-null string indicates a
|
---|
12160 | failure and should normally describe a reason of the failure (for
|
---|
12161 | example, a file read error).
|
---|
12162 | </desc>
|
---|
12163 | </attribute>
|
---|
12164 |
|
---|
12165 | </interface>
|
---|
12166 |
|
---|
12167 | <!--
|
---|
12168 | // ISession
|
---|
12169 | /////////////////////////////////////////////////////////////////////////
|
---|
12170 | -->
|
---|
12171 |
|
---|
12172 | <interface
|
---|
12173 | name="IInternalSessionControl" extends="$unknown"
|
---|
12174 | uuid="2581845a-5a9d-45fb-bc3b-2476552dd970"
|
---|
12175 | internal="yes"
|
---|
12176 | wsmap="suppress"
|
---|
12177 | >
|
---|
12178 | <method name="getPID">
|
---|
12179 | <desc>PID of the process that has created this Session object.
|
---|
12180 | </desc>
|
---|
12181 | <param name="pid" type="unsigned long" dir="return"/>
|
---|
12182 | </method>
|
---|
12183 |
|
---|
12184 | <method name="getRemoteConsole">
|
---|
12185 | <desc>
|
---|
12186 | Returns the console object suitable for remote control.
|
---|
12187 |
|
---|
12188 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12189 | Session state prevents operation.
|
---|
12190 | </result>
|
---|
12191 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12192 | Session type prevents operation.
|
---|
12193 | </result>
|
---|
12194 |
|
---|
12195 | </desc>
|
---|
12196 | <param name="console" type="IConsole" dir="return"/>
|
---|
12197 | </method>
|
---|
12198 |
|
---|
12199 | <method name="assignMachine">
|
---|
12200 | <desc>
|
---|
12201 | Assigns the machine object associated with this direct-type
|
---|
12202 | session or informs the session that it will be a remote one
|
---|
12203 | (if @a machine == NULL).
|
---|
12204 |
|
---|
12205 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12206 | Session state prevents operation.
|
---|
12207 | </result>
|
---|
12208 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12209 | Session type prevents operation.
|
---|
12210 | </result>
|
---|
12211 |
|
---|
12212 | </desc>
|
---|
12213 | <param name="machine" type="IMachine" dir="in"/>
|
---|
12214 | </method>
|
---|
12215 |
|
---|
12216 | <method name="assignRemoteMachine">
|
---|
12217 | <desc>
|
---|
12218 | Assigns the machine and the (remote) console object associated with
|
---|
12219 | this remote-type session.
|
---|
12220 |
|
---|
12221 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12222 | Session state prevents operation.
|
---|
12223 | </result>
|
---|
12224 |
|
---|
12225 | </desc>
|
---|
12226 | <param name="machine" type="IMachine" dir="in"/>
|
---|
12227 | <param name="console" type="IConsole" dir="in"/>
|
---|
12228 | </method>
|
---|
12229 |
|
---|
12230 | <method name="updateMachineState">
|
---|
12231 | <desc>
|
---|
12232 | Updates the machine state in the VM process.
|
---|
12233 | Must be called only in certain cases
|
---|
12234 | (see the method implementation).
|
---|
12235 |
|
---|
12236 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12237 | Session state prevents operation.
|
---|
12238 | </result>
|
---|
12239 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12240 | Session type prevents operation.
|
---|
12241 | </result>
|
---|
12242 |
|
---|
12243 | </desc>
|
---|
12244 | <param name="aMachineState" type="MachineState" dir="in"/>
|
---|
12245 | </method>
|
---|
12246 |
|
---|
12247 | <method name="uninitialize">
|
---|
12248 | <desc>
|
---|
12249 | Uninitializes (closes) this session. Used by VirtualBox to close
|
---|
12250 | the corresponding remote session when the direct session dies
|
---|
12251 | or gets closed.
|
---|
12252 |
|
---|
12253 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12254 | Session state prevents operation.
|
---|
12255 | </result>
|
---|
12256 |
|
---|
12257 | </desc>
|
---|
12258 | </method>
|
---|
12259 |
|
---|
12260 | <method name="onDVDDriveChange">
|
---|
12261 | <desc>
|
---|
12262 | Triggered when settings of the DVD drive object of the
|
---|
12263 | associated virtual machine have changed.
|
---|
12264 |
|
---|
12265 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12266 | Session state prevents operation.
|
---|
12267 | </result>
|
---|
12268 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12269 | Session type prevents operation.
|
---|
12270 | </result>
|
---|
12271 |
|
---|
12272 | </desc>
|
---|
12273 | </method>
|
---|
12274 |
|
---|
12275 | <method name="onFloppyDriveChange">
|
---|
12276 | <desc>
|
---|
12277 | Triggered when settings of the floppy drive object of the
|
---|
12278 | associated virtual machine have changed.
|
---|
12279 |
|
---|
12280 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12281 | Session state prevents operation.
|
---|
12282 | </result>
|
---|
12283 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12284 | Session type prevents operation.
|
---|
12285 | </result>
|
---|
12286 |
|
---|
12287 | </desc>
|
---|
12288 | </method>
|
---|
12289 |
|
---|
12290 | <method name="onNetworkAdapterChange">
|
---|
12291 | <desc>
|
---|
12292 | Triggered when settings of a network adapter of the
|
---|
12293 | associated virtual machine have changed.
|
---|
12294 |
|
---|
12295 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12296 | Session state prevents operation.
|
---|
12297 | </result>
|
---|
12298 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12299 | Session type prevents operation.
|
---|
12300 | </result>
|
---|
12301 |
|
---|
12302 | </desc>
|
---|
12303 | <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
|
---|
12304 | </method>
|
---|
12305 |
|
---|
12306 | <method name="onSerialPortChange">
|
---|
12307 | <desc>
|
---|
12308 | Triggered when settings of a serial port of the
|
---|
12309 | associated virtual machine have changed.
|
---|
12310 |
|
---|
12311 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12312 | Session state prevents operation.
|
---|
12313 | </result>
|
---|
12314 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12315 | Session type prevents operation.
|
---|
12316 | </result>
|
---|
12317 |
|
---|
12318 | </desc>
|
---|
12319 | <param name="serialPort" type="ISerialPort" dir="in"/>
|
---|
12320 | </method>
|
---|
12321 |
|
---|
12322 | <method name="onParallelPortChange">
|
---|
12323 | <desc>
|
---|
12324 | Triggered when settings of a parallel port of the
|
---|
12325 | associated virtual machine have changed.
|
---|
12326 |
|
---|
12327 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12328 | Session state prevents operation.
|
---|
12329 | </result>
|
---|
12330 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12331 | Session type prevents operation.
|
---|
12332 | </result>
|
---|
12333 |
|
---|
12334 | </desc>
|
---|
12335 | <param name="parallelPort" type="IParallelPort" dir="in"/>
|
---|
12336 | </method>
|
---|
12337 |
|
---|
12338 | <method name="onStorageControllerChange">
|
---|
12339 | <desc>
|
---|
12340 | Triggered when settings of a storage controller of the
|
---|
12341 | associated virtual machine have changed.
|
---|
12342 |
|
---|
12343 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12344 | Session state prevents operation.
|
---|
12345 | </result>
|
---|
12346 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12347 | Session type prevents operation.
|
---|
12348 | </result>
|
---|
12349 |
|
---|
12350 | </desc>
|
---|
12351 | </method>
|
---|
12352 |
|
---|
12353 | <method name="onVRDPServerChange">
|
---|
12354 | <desc>
|
---|
12355 | Triggered when settings of the VRDP server object of the
|
---|
12356 | associated virtual machine have changed.
|
---|
12357 |
|
---|
12358 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12359 | Session state prevents operation.
|
---|
12360 | </result>
|
---|
12361 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12362 | Session type prevents operation.
|
---|
12363 | </result>
|
---|
12364 |
|
---|
12365 | </desc>
|
---|
12366 | </method>
|
---|
12367 |
|
---|
12368 | <method name="onUSBControllerChange">
|
---|
12369 | <desc>
|
---|
12370 | Triggered when settings of the USB controller object of the
|
---|
12371 | associated virtual machine have changed.
|
---|
12372 |
|
---|
12373 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12374 | Session state prevents operation.
|
---|
12375 | </result>
|
---|
12376 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12377 | Session type prevents operation.
|
---|
12378 | </result>
|
---|
12379 |
|
---|
12380 | </desc>
|
---|
12381 | </method>
|
---|
12382 |
|
---|
12383 | <method name="onSharedFolderChange">
|
---|
12384 | <desc>
|
---|
12385 | Triggered when a permanent (global or machine) shared folder has been
|
---|
12386 | created or removed.
|
---|
12387 | <note>
|
---|
12388 | We don't pass shared folder parameters in this notification because
|
---|
12389 | the order in which parallel notifications are delivered is not defined,
|
---|
12390 | therefore it could happen that these parameters were outdated by the
|
---|
12391 | time of processing this notification.
|
---|
12392 | </note>
|
---|
12393 |
|
---|
12394 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12395 | Session state prevents operation.
|
---|
12396 | </result>
|
---|
12397 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12398 | Session type prevents operation.
|
---|
12399 | </result>
|
---|
12400 |
|
---|
12401 | </desc>
|
---|
12402 | <param name="global" type="boolean" dir="in"/>
|
---|
12403 | </method>
|
---|
12404 |
|
---|
12405 | <method name="onUSBDeviceAttach">
|
---|
12406 | <desc>
|
---|
12407 | Triggered when a request to capture a USB device (as a result
|
---|
12408 | of matched USB filters or direct call to
|
---|
12409 | <link to="IConsole::attachUSBDevice"/>) has completed.
|
---|
12410 | A @c null @a error object means success, otherwise it
|
---|
12411 | describes a failure.
|
---|
12412 |
|
---|
12413 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12414 | Session state prevents operation.
|
---|
12415 | </result>
|
---|
12416 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12417 | Session type prevents operation.
|
---|
12418 | </result>
|
---|
12419 |
|
---|
12420 | </desc>
|
---|
12421 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
12422 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
12423 | <param name="maskedInterfaces" type="unsigned long" dir="in"/>
|
---|
12424 | </method>
|
---|
12425 |
|
---|
12426 | <method name="onUSBDeviceDetach">
|
---|
12427 | <desc>
|
---|
12428 | Triggered when a request to release the USB device (as a result
|
---|
12429 | of machine termination or direct call to
|
---|
12430 | <link to="IConsole::detachUSBDevice"/>) has completed.
|
---|
12431 | A @c null @a error object means success, otherwise it
|
---|
12432 |
|
---|
12433 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12434 | Session state prevents operation.
|
---|
12435 | </result>
|
---|
12436 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12437 | Session type prevents operation.
|
---|
12438 | </result>
|
---|
12439 |
|
---|
12440 | </desc>
|
---|
12441 | <param name="id" type="uuid" dir="in"/>
|
---|
12442 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
12443 | </method>
|
---|
12444 |
|
---|
12445 | <method name="onShowWindow">
|
---|
12446 | <desc>
|
---|
12447 | Called by <link to="IMachine::canShowConsoleWindow"/> and by
|
---|
12448 | <link to="IMachine::showConsoleWindow"/> in order to notify
|
---|
12449 | console callbacks
|
---|
12450 | <link to="IConsoleCallback::onCanShowWindow"/>
|
---|
12451 | and <link to="IConsoleCallback::onShowWindow"/>.
|
---|
12452 |
|
---|
12453 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12454 | Session type prevents operation.
|
---|
12455 | </result>
|
---|
12456 |
|
---|
12457 | </desc>
|
---|
12458 | <param name="check" type="boolean" dir="in"/>
|
---|
12459 | <param name="canShow" type="boolean" dir="out"/>
|
---|
12460 | <param name="winId" type="unsigned long long" dir="out"/>
|
---|
12461 | </method>
|
---|
12462 |
|
---|
12463 | <method name="accessGuestProperty">
|
---|
12464 | <desc>
|
---|
12465 | Called by <link to="IMachine::getGuestProperty"/> and by
|
---|
12466 | <link to="IMachine::setGuestProperty"/> in order to read and
|
---|
12467 | modify guest properties.
|
---|
12468 |
|
---|
12469 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12470 | Machine session is not open.
|
---|
12471 | </result>
|
---|
12472 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12473 | Session type is not direct.
|
---|
12474 | </result>
|
---|
12475 |
|
---|
12476 | </desc>
|
---|
12477 | <param name="name" type="wstring" dir="in"/>
|
---|
12478 | <param name="value" type="wstring" dir="in"/>
|
---|
12479 | <param name="flags" type="wstring" dir="in"/>
|
---|
12480 | <param name="isSetter" type="boolean" dir="in"/>
|
---|
12481 | <param name="retValue" type="wstring" dir="out"/>
|
---|
12482 | <param name="retTimestamp" type="unsigned long long" dir="out"/>
|
---|
12483 | <param name="retFlags" type="wstring" dir="out"/>
|
---|
12484 | </method>
|
---|
12485 |
|
---|
12486 | <method name="enumerateGuestProperties">
|
---|
12487 | <desc>
|
---|
12488 | Return a list of the guest properties matching a set of patterns along
|
---|
12489 | with their values, time stamps and flags.
|
---|
12490 |
|
---|
12491 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12492 | Machine session is not open.
|
---|
12493 | </result>
|
---|
12494 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12495 | Session type is not direct.
|
---|
12496 | </result>
|
---|
12497 |
|
---|
12498 | </desc>
|
---|
12499 | <param name="patterns" type="wstring" dir="in">
|
---|
12500 | <desc>
|
---|
12501 | The patterns to match the properties against as a comma-separated
|
---|
12502 | string. If this is empty, all properties currently set will be
|
---|
12503 | returned.
|
---|
12504 | </desc>
|
---|
12505 | </param>
|
---|
12506 | <param name="key" type="wstring" dir="out" safearray="yes">
|
---|
12507 | <desc>
|
---|
12508 | The key names of the properties returned.
|
---|
12509 | </desc>
|
---|
12510 | </param>
|
---|
12511 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
12512 | <desc>
|
---|
12513 | The values of the properties returned. The array entries match the
|
---|
12514 | corresponding entries in the @a key array.
|
---|
12515 | </desc>
|
---|
12516 | </param>
|
---|
12517 | <param name="timestamp" type="unsigned long long" dir="out" safearray="yes">
|
---|
12518 | <desc>
|
---|
12519 | The time stamps of the properties returned. The array entries match
|
---|
12520 | the corresponding entries in the @a key array.
|
---|
12521 | </desc>
|
---|
12522 | </param>
|
---|
12523 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
12524 | <desc>
|
---|
12525 | The flags of the properties returned. The array entries match the
|
---|
12526 | corresponding entries in the @a key array.
|
---|
12527 | </desc>
|
---|
12528 | </param>
|
---|
12529 | </method>
|
---|
12530 |
|
---|
12531 | </interface>
|
---|
12532 |
|
---|
12533 | <interface
|
---|
12534 | name="ISession" extends="$dispatched"
|
---|
12535 | uuid="12F4DCDB-12B2-4ec1-B7CD-DDD9F6C5BF4D"
|
---|
12536 | wsmap="managed"
|
---|
12537 | >
|
---|
12538 | <desc>
|
---|
12539 | The ISession interface represents a serialization primitive for virtual
|
---|
12540 | machines.
|
---|
12541 |
|
---|
12542 | With VirtualBox, every time one wishes to manipulate a virtual machine
|
---|
12543 | (e.g. change its settings or start execution), a session object is
|
---|
12544 | required. Such an object must be passed to one of the session methods
|
---|
12545 | that open the given session, which then initiates the machine manipulation.
|
---|
12546 |
|
---|
12547 | A session serves several purposes: it identifies to the inter-process VirtualBox
|
---|
12548 | code which process is currently working with the virtual machine, and it ensures
|
---|
12549 | that there are no incompatible requests from several processes for the
|
---|
12550 | same virtual machine. Session objects can therefore be thought of as mutex
|
---|
12551 | semaphores that lock virtual machines to prevent conflicting accesses from
|
---|
12552 | several processes.
|
---|
12553 |
|
---|
12554 | How sessions objects are used depends on whether you use the Main API
|
---|
12555 | via COM or via the webservice:
|
---|
12556 |
|
---|
12557 | <ul>
|
---|
12558 | <li>When using the COM API directly, an object of the Session class from the
|
---|
12559 | VirtualBox type library needs to be created. In regular COM C++ client code,
|
---|
12560 | this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
|
---|
12561 | This object will then act as a local session object in further calls to open
|
---|
12562 | a session.
|
---|
12563 | </li>
|
---|
12564 |
|
---|
12565 | <li>In the webservice, the session manager (IWebsessionManager) instead creates
|
---|
12566 | one session object automatically when <link to="IWebsessionManager::logon" />
|
---|
12567 | is called. A managed object reference to that session object can be retrieved by
|
---|
12568 | calling <link to="IWebsessionManager::getSessionObject" />. This session object
|
---|
12569 | reference can then be used to open sessions.
|
---|
12570 | </li>
|
---|
12571 | </ul>
|
---|
12572 |
|
---|
12573 | Sessions are mainly used in two variations:
|
---|
12574 |
|
---|
12575 | <ul>
|
---|
12576 | <li>
|
---|
12577 | To start a virtual machine in a separate process, one would call
|
---|
12578 | <link to="IVirtualBox::openRemoteSession"/>, which requires a session
|
---|
12579 | object as its first parameter. This session then identifies the caller
|
---|
12580 | and lets him control the started machine (for example, pause machine
|
---|
12581 | execution or power it down) as well as be notified about machine
|
---|
12582 | execution state changes.
|
---|
12583 | </li>
|
---|
12584 |
|
---|
12585 | <li>To alter machine settings, or to start machine execution within the
|
---|
12586 | current process, one needs to open a direct session for the machine first by
|
---|
12587 | calling <link to="IVirtualBox::openSession"/>. While a direct session
|
---|
12588 | is open within one process, no any other process may open another direct
|
---|
12589 | session for the same machine. This prevents the machine from being changed
|
---|
12590 | by other processes while it is running or while the machine is being configured.
|
---|
12591 | </li>
|
---|
12592 | </ul>
|
---|
12593 |
|
---|
12594 | One also can attach to an existing direct session already opened by
|
---|
12595 | another process (for example, in order to send a control request to the
|
---|
12596 | virtual machine such as the pause or the reset request). This is done by
|
---|
12597 | calling <link to="IVirtualBox::openExistingSession"/>.
|
---|
12598 |
|
---|
12599 | <note>
|
---|
12600 | Unless you are trying to write a new VirtualBox front-end that
|
---|
12601 | performs direct machine execution (like the VirtualBox or VBoxSDL
|
---|
12602 | front-ends), don't call <link to="IConsole::powerUp"/> in a direct
|
---|
12603 | session opened by <link to="IVirtualBox::openSession"/> and use this
|
---|
12604 | session only to change virtual machine settings. If you simply want to
|
---|
12605 | start virtual machine execution using one of the existing front-ends
|
---|
12606 | (for example the VirtualBox GUI or headless server), simply use
|
---|
12607 | <link to="IVirtualBox::openRemoteSession"/>; these front-ends
|
---|
12608 | will power up the machine automatically for you.
|
---|
12609 | </note>
|
---|
12610 | </desc>
|
---|
12611 |
|
---|
12612 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
12613 | <desc>Current state of this session.</desc>
|
---|
12614 | </attribute>
|
---|
12615 |
|
---|
12616 | <attribute name="type" type="SessionType" readonly="yes">
|
---|
12617 | <desc>
|
---|
12618 | Type of this session. The value of this attribute is valid only
|
---|
12619 | if the session is currently open (i.e. its #state is
|
---|
12620 | SessionType_SessionOpen), otherwise an error will be returned.
|
---|
12621 | </desc>
|
---|
12622 | </attribute>
|
---|
12623 |
|
---|
12624 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
12625 | <desc>Machine object associated with this session.</desc>
|
---|
12626 | </attribute>
|
---|
12627 |
|
---|
12628 | <attribute name="console" type="IConsole" readonly="yes">
|
---|
12629 | <desc>Console object associated with this session.</desc>
|
---|
12630 | </attribute>
|
---|
12631 |
|
---|
12632 | <method name="close">
|
---|
12633 | <desc>
|
---|
12634 | Closes a session that was previously opened.
|
---|
12635 |
|
---|
12636 | It is recommended that every time an "open session" method (such as
|
---|
12637 | <link to="IVirtualBox::openRemoteSession" /> or
|
---|
12638 | <link to="IVirtualBox::openSession" />) has been called to
|
---|
12639 | manipulate a virtual machine, the caller invoke
|
---|
12640 | ISession::close() when it's done doing so. Since sessions are
|
---|
12641 | serialization primitives much like ordinary mutexes, they are
|
---|
12642 | best used the same way: for each "open" call, there should be
|
---|
12643 | a matching "close" call, even when errors occur.
|
---|
12644 |
|
---|
12645 | Otherwise, if a direct session for a machine opened with
|
---|
12646 | <link to="IVirtualBox::openSession"/> is not explicitly closed
|
---|
12647 | when the application terminates, the state of the machine will
|
---|
12648 | be set to <link to="MachineState_Aborted" /> on the server.
|
---|
12649 |
|
---|
12650 | Generally, it is recommended to close all open sessions explicitly
|
---|
12651 | before terminating the application (regardless of the reason for
|
---|
12652 | the termination).
|
---|
12653 |
|
---|
12654 | <note>
|
---|
12655 | Do not expect the session state (<link to="ISession::state" />
|
---|
12656 | to return to "Closed" immediately after you invoke
|
---|
12657 | ISession::close(), particularly if you have started a remote
|
---|
12658 | session to execute the VM in a new process. The session state will
|
---|
12659 | automatically return to "Closed" once the VM is no longer executing,
|
---|
12660 | which can of course take a very long time.
|
---|
12661 | </note>
|
---|
12662 |
|
---|
12663 | <result name="E_UNEXPECTED">
|
---|
12664 | Session is not open.
|
---|
12665 | </result>
|
---|
12666 |
|
---|
12667 | </desc>
|
---|
12668 | </method>
|
---|
12669 |
|
---|
12670 | </interface>
|
---|
12671 |
|
---|
12672 | <!--
|
---|
12673 | // IStorageController
|
---|
12674 | /////////////////////////////////////////////////////////////////////////
|
---|
12675 | -->
|
---|
12676 |
|
---|
12677 | <enum
|
---|
12678 | name="StorageBus"
|
---|
12679 | uuid="f381fdca-5953-41d0-b2bd-0542b012698d"
|
---|
12680 | >
|
---|
12681 | <desc>
|
---|
12682 | The connection type of the storage controller.
|
---|
12683 | </desc>
|
---|
12684 | <const name="Null" value="0">
|
---|
12685 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
12686 | </const>
|
---|
12687 | <const name="IDE" value="1"/>
|
---|
12688 | <const name="SATA" value="2"/>
|
---|
12689 | <const name="SCSI" value="3"/>
|
---|
12690 | </enum>
|
---|
12691 |
|
---|
12692 | <enum
|
---|
12693 | name="StorageControllerType"
|
---|
12694 | uuid="685387db-a837-4320-a258-08f46a22f62a"
|
---|
12695 | >
|
---|
12696 | <desc>
|
---|
12697 | Storage controller type.
|
---|
12698 | </desc>
|
---|
12699 |
|
---|
12700 | <const name="Null" value="0">
|
---|
12701 | <desc><tt>null</tt> value. Never used by the API.</desc>
|
---|
12702 | </const>
|
---|
12703 | <const name="LsiLogic" value="1"/>
|
---|
12704 | <const name="BusLogic" value="2"/>
|
---|
12705 | <const name="IntelAhci" value="3"/>
|
---|
12706 | <const name="PIIX3" value="4"/>
|
---|
12707 | <const name="PIIX4" value="5"/>
|
---|
12708 | <const name="ICH6" value="6"/>
|
---|
12709 | </enum>
|
---|
12710 |
|
---|
12711 | <interface
|
---|
12712 | name="IStorageController" extends="$unknown"
|
---|
12713 | uuid="6bf8335b-d14a-44a5-9b45-ddc49ce7d5b2"
|
---|
12714 | wsmap="managed"
|
---|
12715 | >
|
---|
12716 | <desc>
|
---|
12717 | Represents a storage controller that is attached to a virtual machine
|
---|
12718 | (<link to="IMachine" />). Just as hard disks are attached to storage
|
---|
12719 | controllers in a real computer, virtual hard disks (represented by
|
---|
12720 | <link to="IHardDisk" />) are attached to virtual storage controllers,
|
---|
12721 | represented by this interface.
|
---|
12722 |
|
---|
12723 | VirtualBox supports three types of virtual storage controller hardware:
|
---|
12724 | IDE, SCSI, and SATA (see <link to="#bus" />). Depending on which of
|
---|
12725 | these three is used, certain sub-types are available and can be
|
---|
12726 | selected in <link to="#controllerType" />.
|
---|
12727 | </desc>
|
---|
12728 |
|
---|
12729 | <attribute name="name" type="wstring" readonly="yes">
|
---|
12730 | <desc>
|
---|
12731 | Name of the storage controller, as originally specified with
|
---|
12732 | <link to="IMachine::addStorageController" />. This then uniquely
|
---|
12733 | identifies this controller with other method calls such as
|
---|
12734 | <link to="IMachine::attachHardDisk" />.
|
---|
12735 | </desc>
|
---|
12736 | </attribute>
|
---|
12737 |
|
---|
12738 | <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
|
---|
12739 | <desc>
|
---|
12740 | Maximum number of devices which can be attached to one port.
|
---|
12741 | </desc>
|
---|
12742 | </attribute>
|
---|
12743 |
|
---|
12744 | <attribute name="minPortCount" type="unsigned long" readonly="yes">
|
---|
12745 | <desc>
|
---|
12746 | Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
12747 | </desc>
|
---|
12748 | </attribute>
|
---|
12749 |
|
---|
12750 | <attribute name="maxPortCount" type="unsigned long" readonly="yes">
|
---|
12751 | <desc>
|
---|
12752 | Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
12753 | </desc>
|
---|
12754 | </attribute>
|
---|
12755 |
|
---|
12756 | <attribute name="instance" type="unsigned long">
|
---|
12757 | <desc>
|
---|
12758 | The instance number of the device in the running VM.
|
---|
12759 | </desc>
|
---|
12760 | </attribute>
|
---|
12761 |
|
---|
12762 | <attribute name="portCount" type="unsigned long">
|
---|
12763 | <desc>
|
---|
12764 | The number of currently usable ports on the controller.
|
---|
12765 | The minimum and maximum number of ports for one controller are
|
---|
12766 | stored in <link to="IStorageController::minPortCount"/>
|
---|
12767 | and <link to="IStorageController::maxPortCount"/>.
|
---|
12768 | </desc>
|
---|
12769 | </attribute>
|
---|
12770 |
|
---|
12771 | <attribute name="bus" type="StorageBus" readonly="yes">
|
---|
12772 | <desc>
|
---|
12773 | The connection type of the storage controller.
|
---|
12774 | </desc>
|
---|
12775 | </attribute>
|
---|
12776 |
|
---|
12777 | <attribute name="controllerType" type="StorageControllerType">
|
---|
12778 | <desc>
|
---|
12779 | Type of the virtual storage controller. Depending on this value,
|
---|
12780 | VirtualBox will provide a different virtual storage controller hardware
|
---|
12781 | to the guest.
|
---|
12782 |
|
---|
12783 | For SCSI controllers, the default type is LsiLogic.
|
---|
12784 | </desc>
|
---|
12785 | </attribute>
|
---|
12786 |
|
---|
12787 | <method name="GetIDEEmulationPort">
|
---|
12788 | <desc>
|
---|
12789 | Gets the corresponding port number which is emulated as an IDE device.
|
---|
12790 |
|
---|
12791 | <result name="E_INVALIDARG">
|
---|
12792 | The @a devicePosition is not in the range 0 to 3.
|
---|
12793 | </result>
|
---|
12794 | <result name="E_NOTIMPL">
|
---|
12795 | The storage controller type is not SATAIntelAhci.
|
---|
12796 | </result>
|
---|
12797 |
|
---|
12798 | </desc>
|
---|
12799 | <param name="devicePosition" type="long" dir="in"/>
|
---|
12800 | <param name="portNumber" type="long" dir="return"/>
|
---|
12801 | </method>
|
---|
12802 |
|
---|
12803 | <method name="SetIDEEmulationPort">
|
---|
12804 | <desc>
|
---|
12805 | Sets the port number which is emulated as an IDE device.
|
---|
12806 |
|
---|
12807 | <result name="E_INVALIDARG">
|
---|
12808 | The @a devicePosition is not in the range 0 to 3 or the
|
---|
12809 | @a portNumber is not in the range 0 to 29.
|
---|
12810 | </result>
|
---|
12811 | <result name="E_NOTIMPL">
|
---|
12812 | The storage controller type is not SATAIntelAhci.
|
---|
12813 | </result>
|
---|
12814 |
|
---|
12815 | </desc>
|
---|
12816 | <param name="devicePosition" type="long" dir="in"/>
|
---|
12817 | <param name="portNumber" type="long" dir="in"/>
|
---|
12818 | </method>
|
---|
12819 |
|
---|
12820 | </interface>
|
---|
12821 |
|
---|
12822 | <if target="wsdl">
|
---|
12823 |
|
---|
12824 | <!--
|
---|
12825 | // IManagedObjectRef
|
---|
12826 | /////////////////////////////////////////////////////////////////////////
|
---|
12827 | -->
|
---|
12828 |
|
---|
12829 | <interface
|
---|
12830 | name="IManagedObjectRef" extends="$unknown"
|
---|
12831 | uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
|
---|
12832 | internal="yes"
|
---|
12833 | wsmap="managed"
|
---|
12834 | wscpp="hardcoded"
|
---|
12835 | >
|
---|
12836 | <desc>
|
---|
12837 | Managed object reference.
|
---|
12838 |
|
---|
12839 | Only within the webservice, a managed object reference (which is really
|
---|
12840 | an opaque number) allows a webservice client to address an object
|
---|
12841 | that lives in the address space of the webservice server.
|
---|
12842 |
|
---|
12843 | Behind each managed object reference, there is a COM object that lives
|
---|
12844 | in the webservice server's address space. The COM object is not freed
|
---|
12845 | until the managed object reference is released, either by an explicit
|
---|
12846 | call to <link to="IManagedObjectRef::release" /> or by logging off from
|
---|
12847 | the webservice (<link to="IWebsessionManager::logoff" />), which releases
|
---|
12848 | all objects created during the webservice session.
|
---|
12849 |
|
---|
12850 | Whenever a method call of the VirtualBox API returns a COM object, the
|
---|
12851 | webservice representation of that method will instead return a
|
---|
12852 | managed object reference, which can then be used to invoke methods
|
---|
12853 | on that object.
|
---|
12854 | </desc>
|
---|
12855 |
|
---|
12856 | <method name="getInterfaceName">
|
---|
12857 | <desc>
|
---|
12858 | Returns the name of the interface that this managed object represents,
|
---|
12859 | for example, "IMachine", as a string.
|
---|
12860 | </desc>
|
---|
12861 | <param name="return" type="wstring" dir="return"/>
|
---|
12862 | </method>
|
---|
12863 |
|
---|
12864 | <method name="release">
|
---|
12865 | <desc>
|
---|
12866 | Releases this managed object reference and frees the resources that
|
---|
12867 | were allocated for it in the webservice server process. After calling
|
---|
12868 | this method, the identifier of the reference can no longer be used.
|
---|
12869 | </desc>
|
---|
12870 | </method>
|
---|
12871 |
|
---|
12872 | </interface>
|
---|
12873 |
|
---|
12874 | <!--
|
---|
12875 | // IWebsessionManager
|
---|
12876 | /////////////////////////////////////////////////////////////////////////
|
---|
12877 | -->
|
---|
12878 |
|
---|
12879 | <interface
|
---|
12880 | name="IWebsessionManager" extends="$unknown"
|
---|
12881 | uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
|
---|
12882 | internal="yes"
|
---|
12883 | wsmap="global"
|
---|
12884 | wscpp="hardcoded"
|
---|
12885 | >
|
---|
12886 | <desc>
|
---|
12887 | Websession manager. This provides essential services
|
---|
12888 | to webservice clients.
|
---|
12889 | </desc>
|
---|
12890 | <method name="logon">
|
---|
12891 | <desc>
|
---|
12892 | Logs a new client onto the webservice and returns a managed object reference to
|
---|
12893 | the IVirtualBox instance, which the client can then use as a basis to further
|
---|
12894 | queries, since all calls to the VirtualBox API are based on the IVirtualBox
|
---|
12895 | interface, in one way or the other.
|
---|
12896 | </desc>
|
---|
12897 | <param name="username" type="wstring" dir="in"/>
|
---|
12898 | <param name="password" type="wstring" dir="in"/>
|
---|
12899 | <param name="return" type="IVirtualBox" dir="return"/>
|
---|
12900 | </method>
|
---|
12901 |
|
---|
12902 | <method name="getSessionObject">
|
---|
12903 | <desc>
|
---|
12904 | Returns a managed object reference to the internal ISession object that was created
|
---|
12905 | for this web service session when the client logged on.
|
---|
12906 |
|
---|
12907 | <see>ISession</see>
|
---|
12908 | </desc>
|
---|
12909 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
12910 | <param name="return" type="ISession" dir="return"/>
|
---|
12911 | </method>
|
---|
12912 |
|
---|
12913 | <method name="logoff">
|
---|
12914 | <desc>
|
---|
12915 | Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
|
---|
12916 | and destroys all resources associated with the session (most importantly, all
|
---|
12917 | managed objects created in the server while the session was active).
|
---|
12918 | </desc>
|
---|
12919 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
12920 | </method>
|
---|
12921 |
|
---|
12922 | </interface>
|
---|
12923 |
|
---|
12924 | </if>
|
---|
12925 |
|
---|
12926 | <!--
|
---|
12927 | // IPerformanceCollector & friends
|
---|
12928 | /////////////////////////////////////////////////////////////////////////
|
---|
12929 | -->
|
---|
12930 |
|
---|
12931 | <interface
|
---|
12932 | name="IPerformanceMetric" extends="$unknown"
|
---|
12933 | uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
|
---|
12934 | >
|
---|
12935 | <desc>
|
---|
12936 | The IPerformanceMetric interface represents parameters of the given
|
---|
12937 | performance metric.
|
---|
12938 | </desc>
|
---|
12939 |
|
---|
12940 | <attribute name="metricName" type="wstring" readonly="yes">
|
---|
12941 | <desc>
|
---|
12942 | Name of the metric.
|
---|
12943 | </desc>
|
---|
12944 | </attribute>
|
---|
12945 |
|
---|
12946 | <attribute name="object" type="$unknown" readonly="yes">
|
---|
12947 | <desc>
|
---|
12948 | Object this metric belongs to.
|
---|
12949 | </desc>
|
---|
12950 | </attribute>
|
---|
12951 |
|
---|
12952 | <attribute name="description" type="wstring" readonly="yes">
|
---|
12953 | <desc>
|
---|
12954 | Textual description of the metric.
|
---|
12955 | </desc>
|
---|
12956 | </attribute>
|
---|
12957 |
|
---|
12958 | <attribute name="period" type="unsigned long" readonly="yes">
|
---|
12959 | <desc>
|
---|
12960 | Time interval between samples, measured in seconds.
|
---|
12961 | </desc>
|
---|
12962 | </attribute>
|
---|
12963 |
|
---|
12964 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
12965 | <desc>
|
---|
12966 | Number of recent samples retained by the performance collector for this
|
---|
12967 | metric.
|
---|
12968 |
|
---|
12969 | When the collected sample count exceeds this number, older samples
|
---|
12970 | are discarded.
|
---|
12971 | </desc>
|
---|
12972 | </attribute>
|
---|
12973 |
|
---|
12974 | <attribute name="unit" type="wstring" readonly="yes">
|
---|
12975 | <desc>
|
---|
12976 | Unit of measurement.
|
---|
12977 | </desc>
|
---|
12978 | </attribute>
|
---|
12979 |
|
---|
12980 | <attribute name="minimumValue" type="long" readonly="yes">
|
---|
12981 | <desc>
|
---|
12982 | Minimum possible value of this metric.
|
---|
12983 | </desc>
|
---|
12984 | </attribute>
|
---|
12985 |
|
---|
12986 | <attribute name="maximumValue" type="long" readonly="yes">
|
---|
12987 | <desc>
|
---|
12988 | Maximum possible value of this metric.
|
---|
12989 | </desc>
|
---|
12990 | </attribute>
|
---|
12991 | </interface>
|
---|
12992 |
|
---|
12993 | <interface
|
---|
12994 | name="IPerformanceCollector" extends="$unknown"
|
---|
12995 | uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
|
---|
12996 | wsmap="managed"
|
---|
12997 | >
|
---|
12998 | <desc>
|
---|
12999 | The IPerformanceCollector interface represents a service that collects and
|
---|
13000 | stores performance metrics data.
|
---|
13001 |
|
---|
13002 | Performance metrics are associated with objects like IHost and
|
---|
13003 | IMachine. Each object has a distinct set of performance metrics.
|
---|
13004 | The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
|
---|
13005 |
|
---|
13006 | Metric data are collected at the specified intervals and are retained
|
---|
13007 | internally. The interval and the number of samples retained can be set
|
---|
13008 | with <link to="IPerformanceCollector::setupMetrics" />.
|
---|
13009 |
|
---|
13010 | Metrics are organized hierarchically, each level separated by slash (/).
|
---|
13011 | General scheme for metric name is
|
---|
13012 | "Category/Metric[/SubMetric][:aggregation]". For example CPU/Load/User:avg
|
---|
13013 | metric name stands for: CPU category, Load metric, User submetric, average
|
---|
13014 | aggregate. An aggregate function is computed over all retained data. Valid
|
---|
13015 | aggregate functions are:
|
---|
13016 |
|
---|
13017 | <ul>
|
---|
13018 | <li>avg -- average</li>
|
---|
13019 | <li>min -- minimum</li>
|
---|
13020 | <li>max -- maximum</li>
|
---|
13021 | </ul>
|
---|
13022 |
|
---|
13023 | "Category/Metric" together form base metric name. A base metric is the
|
---|
13024 | smallest unit for which a sampling interval and the number of retained
|
---|
13025 | samples can be set. Only base metrics can be enabled and disabled. All
|
---|
13026 | sub-metrics are collected when their base metric is collected.
|
---|
13027 | Collected values for any set of sub-metrics can be queried with
|
---|
13028 | <link to="IPerformanceCollector::queryMetricsData" />. When setting up
|
---|
13029 | metric parameters, querying metric data, enabling or disabling metrics
|
---|
13030 | wildcards can be used in metric names to specify a subset of metrics. For
|
---|
13031 | example, to select all CPU-related metrics use <tt>CPU/*</tt>, all
|
---|
13032 | averages can be queried using <tt>*:avg</tt> and so on. To query metric
|
---|
13033 | values without aggregates <tt>*:</tt> can be used.
|
---|
13034 |
|
---|
13035 | The valid names for base metrics are:
|
---|
13036 |
|
---|
13037 | <ul>
|
---|
13038 | <li>CPU/Load</li>
|
---|
13039 | <li>CPU/MHz</li>
|
---|
13040 | <li>RAM/Usage</li>
|
---|
13041 | </ul>
|
---|
13042 |
|
---|
13043 | The general sequence for collecting and retrieving the metrics is:
|
---|
13044 | <ul>
|
---|
13045 | <li>
|
---|
13046 | Obtain an instance of IPerformanceCollector with
|
---|
13047 | <link to="IVirtualBox::performanceCollector" />
|
---|
13048 | </li>
|
---|
13049 | <li>
|
---|
13050 | Allocate and populate an array with references to objects the metrics
|
---|
13051 | will be collected for. Use references to IHost and IMachine objects.
|
---|
13052 | </li>
|
---|
13053 | <li>
|
---|
13054 | Allocate and populate an array with base metric names the data will be
|
---|
13055 | collected for.
|
---|
13056 | </li>
|
---|
13057 | <li>
|
---|
13058 | Call <link to="IPerformanceCollector::setupMetrics" />. From now on the
|
---|
13059 | metric data will be collected and stored.
|
---|
13060 | </li>
|
---|
13061 | <li>
|
---|
13062 | Wait for the data to get collected.
|
---|
13063 | </li>
|
---|
13064 | <li>
|
---|
13065 | Allocate and populate an array with references to objects the metric
|
---|
13066 | values will be queried for. You can re-use the object array used for
|
---|
13067 | setting base metrics.
|
---|
13068 | </li>
|
---|
13069 | <li>
|
---|
13070 | Allocate and populate an array with metric names the data will be
|
---|
13071 | collected for. Note that metric names differ from base metric names.
|
---|
13072 | </li>
|
---|
13073 | <li>
|
---|
13074 | Call <link to="IPerformanceCollector::queryMetricsData" />. The data that
|
---|
13075 | have been collected so far are returned. Note that the values are still
|
---|
13076 | retained internally and data collection continues.
|
---|
13077 | </li>
|
---|
13078 | </ul>
|
---|
13079 |
|
---|
13080 | For an example of usage refer to the following files in VirtualBox SDK:
|
---|
13081 | <ul>
|
---|
13082 | <li>
|
---|
13083 | Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
|
---|
13084 | </li>
|
---|
13085 | <li>
|
---|
13086 | Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
|
---|
13087 | </li>
|
---|
13088 | </ul>
|
---|
13089 | </desc>
|
---|
13090 |
|
---|
13091 | <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
|
---|
13092 | <desc>
|
---|
13093 | Array of unique names of metrics.
|
---|
13094 |
|
---|
13095 | This array represents all metrics supported by the performance
|
---|
13096 | collector. Individual objects do not necessarily support all of them.
|
---|
13097 | <link to="IPerformanceCollector::getMetrics"/> can be used to get the
|
---|
13098 | list of supported metrics for a particular object.
|
---|
13099 | </desc>
|
---|
13100 | </attribute>
|
---|
13101 |
|
---|
13102 | <method name="getMetrics">
|
---|
13103 | <desc>
|
---|
13104 | Returns parameters of specified metrics for a set of objects.
|
---|
13105 | <note>
|
---|
13106 | @c Null metrics array means all metrics. @c Null object array means
|
---|
13107 | all existing objects.
|
---|
13108 | </note>
|
---|
13109 | </desc>
|
---|
13110 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13111 | <desc>
|
---|
13112 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
13113 | is supported.
|
---|
13114 | </desc>
|
---|
13115 | </param>
|
---|
13116 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13117 | <desc>
|
---|
13118 | Set of objects to return metric parameters for.
|
---|
13119 | </desc>
|
---|
13120 | </param>
|
---|
13121 | <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13122 | <desc>
|
---|
13123 | Array of returned metric parameters.
|
---|
13124 | </desc>
|
---|
13125 | </param>
|
---|
13126 | </method>
|
---|
13127 |
|
---|
13128 | <method name="setupMetrics">
|
---|
13129 | <desc>
|
---|
13130 | Sets parameters of specified base metrics for a set of objects. Returns
|
---|
13131 | an array of <link to="IPerformanceMetric" /> describing the metrics have
|
---|
13132 | been affected.
|
---|
13133 | <note>
|
---|
13134 | @c Null or empty metric name array means all metrics. @c Null or empty
|
---|
13135 | object array means all existing objects. If metric name array contains
|
---|
13136 | a single element and object array contains many, the single metric
|
---|
13137 | name array element is applied to each object array element to form
|
---|
13138 | metric/object pairs.
|
---|
13139 | </note>
|
---|
13140 | </desc>
|
---|
13141 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13142 | <desc>
|
---|
13143 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13144 | support.
|
---|
13145 | </desc>
|
---|
13146 | </param>
|
---|
13147 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13148 | <desc>
|
---|
13149 | Set of objects to setup metric parameters for.
|
---|
13150 | </desc>
|
---|
13151 | </param>
|
---|
13152 | <param name="period" type="unsigned long" dir="in">
|
---|
13153 | <desc>
|
---|
13154 | Time interval in seconds between two consecutive samples of performance
|
---|
13155 | data.
|
---|
13156 | </desc>
|
---|
13157 | </param>
|
---|
13158 | <param name="count" type="unsigned long" dir="in">
|
---|
13159 | <desc>
|
---|
13160 | Number of samples to retain in performance data history. Older samples
|
---|
13161 | get discarded.
|
---|
13162 | </desc>
|
---|
13163 | </param>
|
---|
13164 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13165 | <desc>
|
---|
13166 | Array of metrics that have been modified by the call to this method.
|
---|
13167 | </desc>
|
---|
13168 | </param>
|
---|
13169 | </method>
|
---|
13170 |
|
---|
13171 | <method name="enableMetrics">
|
---|
13172 | <desc>
|
---|
13173 | Turns on collecting specified base metrics. Returns an array of
|
---|
13174 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
13175 | affected.
|
---|
13176 | <note>
|
---|
13177 | @c Null or empty metric name array means all metrics. @c Null or empty
|
---|
13178 | object array means all existing objects. If metric name array contains
|
---|
13179 | a single element and object array contains many, the single metric
|
---|
13180 | name array element is applied to each object array element to form
|
---|
13181 | metric/object pairs.
|
---|
13182 | </note>
|
---|
13183 | </desc>
|
---|
13184 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13185 | <desc>
|
---|
13186 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13187 | support.
|
---|
13188 | </desc>
|
---|
13189 | </param>
|
---|
13190 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13191 | <desc>
|
---|
13192 | Set of objects to enable metrics for.
|
---|
13193 | </desc>
|
---|
13194 | </param>
|
---|
13195 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13196 | <desc>
|
---|
13197 | Array of metrics that have been modified by the call to this method.
|
---|
13198 | </desc>
|
---|
13199 | </param>
|
---|
13200 | </method>
|
---|
13201 |
|
---|
13202 | <method name="disableMetrics">
|
---|
13203 | <desc>
|
---|
13204 | Turns off collecting specified base metrics. Returns an array of
|
---|
13205 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
13206 | affected.
|
---|
13207 | <note>
|
---|
13208 | @c Null or empty metric name array means all metrics. @c Null or empty
|
---|
13209 | object array means all existing objects. If metric name array contains
|
---|
13210 | a single element and object array contains many, the single metric
|
---|
13211 | name array element is applied to each object array element to form
|
---|
13212 | metric/object pairs.
|
---|
13213 | </note>
|
---|
13214 | </desc>
|
---|
13215 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13216 | <desc>
|
---|
13217 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13218 | support.
|
---|
13219 | </desc>
|
---|
13220 | </param>
|
---|
13221 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13222 | <desc>
|
---|
13223 | Set of objects to disable metrics for.
|
---|
13224 | </desc>
|
---|
13225 | </param>
|
---|
13226 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13227 | <desc>
|
---|
13228 | Array of metrics that have been modified by the call to this method.
|
---|
13229 | </desc>
|
---|
13230 | </param>
|
---|
13231 | </method>
|
---|
13232 |
|
---|
13233 | <method name="queryMetricsData">
|
---|
13234 | <desc>
|
---|
13235 | Queries collected metrics data for a set of objects.
|
---|
13236 |
|
---|
13237 | The data itself and related metric information are returned in seven
|
---|
13238 | parallel and one flattened array of arrays. Elements of
|
---|
13239 | <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
|
---|
13240 | returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
|
---|
13241 | the same index describe one set of values corresponding to a single
|
---|
13242 | metric.
|
---|
13243 |
|
---|
13244 | The <tt>returnData</tt> parameter is a flattened array of arrays. Each
|
---|
13245 | start and length of a sub-array is indicated by
|
---|
13246 | <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
|
---|
13247 | value for metric <tt>metricNames[i]</tt> is at
|
---|
13248 | <tt>returnData[returnIndices[i]]</tt>.
|
---|
13249 |
|
---|
13250 | <note>
|
---|
13251 | @c Null or empty metric name array means all metrics. @c Null or empty
|
---|
13252 | object array means all existing objects. If metric name array contains
|
---|
13253 | a single element and object array contains many, the single metric
|
---|
13254 | name array element is applied to each object array element to form
|
---|
13255 | metric/object pairs.
|
---|
13256 | </note>
|
---|
13257 | <note>
|
---|
13258 | Data collection continues behind the scenes after call to
|
---|
13259 | @c queryMetricsData. The return data can be seen as the snapshot of
|
---|
13260 | the current state at the time of @c queryMetricsData call. The
|
---|
13261 | internally kept metric values are not cleared by the call. This makes
|
---|
13262 | possible querying different subsets of metrics or aggregates with
|
---|
13263 | subsequent calls. If periodic querying is needed it is highly
|
---|
13264 | suggested to query the values with @c interval*count period to avoid
|
---|
13265 | confusion. This way a completely new set of data values will be
|
---|
13266 | provided by each query.
|
---|
13267 | </note>
|
---|
13268 | </desc>
|
---|
13269 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13270 | <desc>
|
---|
13271 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13272 | support.
|
---|
13273 | </desc>
|
---|
13274 | </param>
|
---|
13275 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13276 | <desc>
|
---|
13277 | Set of objects to query metrics for.
|
---|
13278 | </desc>
|
---|
13279 | </param>
|
---|
13280 | <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
|
---|
13281 | <desc>
|
---|
13282 | Names of metrics returned in @c returnData.
|
---|
13283 | </desc>
|
---|
13284 | </param>
|
---|
13285 | <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
|
---|
13286 | <desc>
|
---|
13287 | Objects associated with metrics returned in @c returnData.
|
---|
13288 | </desc>
|
---|
13289 | </param>
|
---|
13290 | <param name="returnUnits" type="wstring" dir="out" safearray="yes">
|
---|
13291 | <desc>
|
---|
13292 | Units of measurement for each returned metric.
|
---|
13293 | </desc>
|
---|
13294 | </param>
|
---|
13295 | <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
|
---|
13296 | <desc>
|
---|
13297 | Divisor that should be applied to return values in order to get
|
---|
13298 | floating point values. For example:
|
---|
13299 | <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
|
---|
13300 | will retrieve the floating point value of i-th sample of the first
|
---|
13301 | metric.
|
---|
13302 | </desc>
|
---|
13303 | </param>
|
---|
13304 | <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
|
---|
13305 | <desc>
|
---|
13306 | Sequence numbers of the first elements of value sequences of particular metrics
|
---|
13307 | returned in @c returnData. For aggregate metrics it is the sequence number of
|
---|
13308 | the sample the aggregate started calculation from.
|
---|
13309 | </desc>
|
---|
13310 | </param>
|
---|
13311 | <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
|
---|
13312 | <desc>
|
---|
13313 | Indices of the first elements of value sequences of particular metrics
|
---|
13314 | returned in @c returnData.
|
---|
13315 | </desc>
|
---|
13316 | </param>
|
---|
13317 | <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
|
---|
13318 | <desc>
|
---|
13319 | Lengths of value sequences of particular metrics.
|
---|
13320 | </desc>
|
---|
13321 | </param>
|
---|
13322 | <param name="returnData" type="long" dir="return" safearray="yes">
|
---|
13323 | <desc>
|
---|
13324 | Flattened array of all metric data containing sequences of values for
|
---|
13325 | each metric.
|
---|
13326 | </desc>
|
---|
13327 | </param>
|
---|
13328 | </method>
|
---|
13329 |
|
---|
13330 | </interface>
|
---|
13331 |
|
---|
13332 | <module name="VBoxSVC" context="LocalServer">
|
---|
13333 | <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
|
---|
13334 | namespace="virtualbox.org">
|
---|
13335 | <interface name="IVirtualBox" default="yes"/>
|
---|
13336 | </class>
|
---|
13337 | </module>
|
---|
13338 |
|
---|
13339 | <module name="VBoxC" context="InprocServer" threadingModel="Free">
|
---|
13340 | <class name="Session" uuid="3C02F46D-C9D2-4f11-A384-53F0CF917214"
|
---|
13341 | namespace="virtualbox.org">
|
---|
13342 | <interface name="ISession" default="yes"/>
|
---|
13343 | </class>
|
---|
13344 | </module>
|
---|
13345 |
|
---|
13346 | </library>
|
---|
13347 |
|
---|
13348 | </idl>
|
---|
13349 |
|
---|
13350 | <!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->
|
---|