1 | <?xml version="1.0" ?>
|
---|
2 |
|
---|
3 | <!--
|
---|
4 |
|
---|
5 | Copyright (C) 2006-2011 Oracle Corporation
|
---|
6 |
|
---|
7 | This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
8 | available from http://www.virtualbox.org. This file is free software;
|
---|
9 | you can redistribute it and/or modify it under the terms of the GNU
|
---|
10 | General Public License (GPL) as published by the Free Software
|
---|
11 | Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
12 | VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
13 | hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
14 | -->
|
---|
15 |
|
---|
16 | <!--
|
---|
17 | This is the master declaration for VirtualBox's Main API,
|
---|
18 | represented by COM/XPCOM and web service interfaces.
|
---|
19 |
|
---|
20 | From this document, the build system generates several files
|
---|
21 | via XSLT that are then used during the build process.
|
---|
22 |
|
---|
23 | Below is the list of XSL templates that operate on this file and
|
---|
24 | output files they generate. These XSL templates must be updated
|
---|
25 | whenever the schema of this file changes:
|
---|
26 |
|
---|
27 | 1. src/VBox/Main/idl/midl.xsl =>
|
---|
28 | out/<platform>/bin/sdk/idl/VirtualBox.idl
|
---|
29 | (MS COM interface definition file for Main API)
|
---|
30 |
|
---|
31 | 2. src/VBox/Main/idl/xpidl.xsl =>
|
---|
32 | out/<platform>/bin/sdk/idl/VirtualBox_XPCOM.idl
|
---|
33 | (XPCOM interface definition file for Main API)
|
---|
34 |
|
---|
35 | 3. src/VBox/Main/idl/doxygen.xsl =>
|
---|
36 | out/<platform>/obj/src/VBox/Main/VirtualBox.idl
|
---|
37 | (pseudo-IDL for Doxygen to generate the official Main API
|
---|
38 | documentation)
|
---|
39 |
|
---|
40 | 4. src/VBox/Main/webservice/*.xsl =>
|
---|
41 | a bunch of WSDL and C++ files
|
---|
42 | (VirtualBox web service sources and SOAP mappers;
|
---|
43 | see src/VBox/Main/webservice/Makefile.kmk for details)
|
---|
44 |
|
---|
45 | 5. src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl =>
|
---|
46 | out/<platform>/obj/src/VBox/Frontends/VirtualBox/VirtualBox/include/COMWrappers.h
|
---|
47 | (smart Qt-based C++ wrapper classes for COM interfaces
|
---|
48 | of the Main API)
|
---|
49 |
|
---|
50 | 6. src/VBox/Installer/win32/VirtualBox_TypeLib.xsl =>
|
---|
51 | out/<platform>/obj/src/VBox/Installer/win32/VirtualBox_TypeLib.wxi
|
---|
52 | (Main API TypeLib block for the WiX installer)
|
---|
53 |
|
---|
54 | 7. src/VBox/Runtime/common/err/errmsgvboxcom.xsl =>
|
---|
55 | out/<platform>/obj/Runtime/errmsgvboxcomdata.h
|
---|
56 | (<result> extraction for the %Rhrc format specifier)
|
---|
57 | -->
|
---|
58 |
|
---|
59 | <idl>
|
---|
60 |
|
---|
61 | <desc>
|
---|
62 | Welcome to the <b>VirtualBox Main API documentation</b>. This documentation
|
---|
63 | describes the so-called <i>VirtualBox Main API</i> which comprises all public
|
---|
64 | COM interfaces and components provided by the VirtualBox server and by the
|
---|
65 | VirtualBox client library.
|
---|
66 |
|
---|
67 | VirtualBox employs a client-server design, meaning that whenever any part of
|
---|
68 | VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line
|
---|
69 | interface or any virtual machine --, a dedicated server process named
|
---|
70 | VBoxSVC runs in the background. This allows multiple processes working with
|
---|
71 | VirtualBox to cooperate without conflicts. These processes communicate to each
|
---|
72 | other using inter-process communication facilities provided by the COM
|
---|
73 | implementation of the host computer.
|
---|
74 |
|
---|
75 | On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
|
---|
76 | implementation. On all other platforms, Mozilla XPCOM, an open-source COM
|
---|
77 | implementation, is used.
|
---|
78 |
|
---|
79 | All the parts that a typical VirtualBox user interacts with (the Qt GUI
|
---|
80 | and the VBoxManage command-line interface) are technically
|
---|
81 | front-ends to the Main API and only use the interfaces that are documented
|
---|
82 | in this Main API documentation. This ensures that, with any given release
|
---|
83 | version of VirtualBox, all capabilities of the product that could be useful
|
---|
84 | to an external client program are always exposed by way of this API.
|
---|
85 |
|
---|
86 | The VirtualBox Main API (also called the <i>VirtualBox COM library</i>)
|
---|
87 | contains two public component classes:
|
---|
88 | <tt>%VirtualBox.VirtualBox</tt> and <tt>%VirtualBox.Session</tt>, which
|
---|
89 | implement IVirtualBox and ISession interfaces respectively. These two classes
|
---|
90 | are of supreme importance and will be needed in order for any front-end
|
---|
91 | program to do anything useful. It is recommended to read the documentation of
|
---|
92 | the mentioned interfaces first.
|
---|
93 |
|
---|
94 | The <tt>%VirtualBox.VirtualBox</tt> class is a singleton. This means that
|
---|
95 | there can be only one object of this class on the local machine at any given
|
---|
96 | time. This object is a parent of many other objects in the VirtualBox COM
|
---|
97 | library and lives in the VBoxSVC process. In fact, when you create an instance
|
---|
98 | of the <tt>VirtualBox.VirtualBox</tt>, the COM subsystem checks if the VBoxSVC
|
---|
99 | process is already running, starts it if not, and returns you a reference to
|
---|
100 | the <tt>VirtualBox</tt> object created in this process. When the last reference
|
---|
101 | to this object is released, the VBoxSVC process ends (with a 5 second delay to
|
---|
102 | protect from too frequent restarts).
|
---|
103 |
|
---|
104 | The <tt>%VirtualBox.Session</tt> class is a regular component. You can create
|
---|
105 | as many <tt>Session</tt> objects as you need but all of them will live in a
|
---|
106 | process which issues the object instantiation call. <tt>Session</tt> objects
|
---|
107 | represent virtual machine sessions which are used to configure virtual
|
---|
108 | machines and control their execution.
|
---|
109 | </desc>
|
---|
110 |
|
---|
111 | <if target="midl">
|
---|
112 | <cpp line="enum {"/>
|
---|
113 | <cpp line=" kTypeLibraryMajorVersion = 1,"/>
|
---|
114 | <cpp line=" kTypeLibraryMinorVersion = 0"/>
|
---|
115 | <cpp line="};"/>
|
---|
116 | </if>
|
---|
117 |
|
---|
118 | <if target="xpidl">
|
---|
119 | <!-- NS_IMPL_THREADSAFE_ISUPPORTSxx_CI macros are placed here, for convenience -->
|
---|
120 | <cpp>
|
---|
121 | /* currently, nsISupportsImpl.h lacks the below-like macros */
|
---|
122 |
|
---|
123 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI
|
---|
124 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI
|
---|
125 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI
|
---|
126 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI
|
---|
127 |
|
---|
128 |
|
---|
129 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI
|
---|
130 | # define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \
|
---|
131 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
132 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
133 | NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \
|
---|
134 | NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface)
|
---|
135 | #endif
|
---|
136 |
|
---|
137 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI
|
---|
138 | # define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \
|
---|
139 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
140 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
141 | NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \
|
---|
142 | NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
|
---|
143 | #endif
|
---|
144 |
|
---|
145 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI
|
---|
146 | # define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \
|
---|
147 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
148 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
149 | NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \
|
---|
150 | NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
|
---|
151 | #endif
|
---|
152 |
|
---|
153 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI
|
---|
154 | # define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \
|
---|
155 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
156 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
157 | NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \
|
---|
158 | NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4)
|
---|
159 | #endif
|
---|
160 |
|
---|
161 | #ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
|
---|
162 | # define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
163 | NS_INTERFACE_MAP_BEGIN(_class) \
|
---|
164 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
|
---|
165 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
|
---|
166 | NS_IMPL_QUERY_CLASSINFO(_class) \
|
---|
167 | NS_INTERFACE_MAP_END
|
---|
168 | #endif
|
---|
169 |
|
---|
170 | #ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
|
---|
171 | # define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
172 | _i2, _ic2) \
|
---|
173 | NS_INTERFACE_MAP_BEGIN(_class) \
|
---|
174 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
|
---|
175 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
|
---|
176 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
|
---|
177 | NS_IMPL_QUERY_CLASSINFO(_class) \
|
---|
178 | NS_INTERFACE_MAP_END
|
---|
179 | #endif
|
---|
180 |
|
---|
181 | #ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
|
---|
182 | # define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
183 | _i2, _ic2, _i3, _ic3) \
|
---|
184 | NS_INTERFACE_MAP_BEGIN(_class) \
|
---|
185 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \
|
---|
186 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \
|
---|
187 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \
|
---|
188 | NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \
|
---|
189 | NS_IMPL_QUERY_CLASSINFO(_class) \
|
---|
190 | NS_INTERFACE_MAP_END
|
---|
191 | #endif
|
---|
192 |
|
---|
193 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI
|
---|
194 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI
|
---|
195 | #define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI
|
---|
196 |
|
---|
197 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI
|
---|
198 | # define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
199 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
200 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
201 | NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \
|
---|
202 | NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1)
|
---|
203 | #endif
|
---|
204 |
|
---|
205 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI
|
---|
206 | # define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
207 | _i2, _ic2) \
|
---|
208 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
209 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
210 | NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
211 | _i2, _ic2) \
|
---|
212 | NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2)
|
---|
213 | #endif
|
---|
214 |
|
---|
215 | #ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI
|
---|
216 | # define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
217 | _i2, _ic2, _i3, _ic3) \
|
---|
218 | NS_IMPL_THREADSAFE_ADDREF(_class) \
|
---|
219 | NS_IMPL_THREADSAFE_RELEASE(_class) \
|
---|
220 | NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \
|
---|
221 | _i2, _ic2, _i3, _ic3) \
|
---|
222 | NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3)
|
---|
223 | #endif
|
---|
224 |
|
---|
225 | </cpp>
|
---|
226 | </if>
|
---|
227 |
|
---|
228 | <library
|
---|
229 | name="VirtualBox"
|
---|
230 | uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259"
|
---|
231 | version="1.3"
|
---|
232 | desc="VirtualBox Type Library"
|
---|
233 | appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9"
|
---|
234 | supportsErrorInfo="yes"
|
---|
235 | >
|
---|
236 |
|
---|
237 |
|
---|
238 | <!--
|
---|
239 | // COM result codes for VirtualBox
|
---|
240 | /////////////////////////////////////////////////////////////////////////
|
---|
241 | -->
|
---|
242 |
|
---|
243 | <descGroup id="VirtualBox_COM_result_codes" title="VirtualBox COM result codes">
|
---|
244 | <desc>
|
---|
245 | This section describes all VirtualBox-specific COM result codes that may
|
---|
246 | be returned by methods of VirtualBox COM interfaces in addition to
|
---|
247 | standard COM result codes.
|
---|
248 |
|
---|
249 | Note that along with the result code, every VirtualBox method returns
|
---|
250 | extended error information through the IVirtualBoxErrorInfo interface on
|
---|
251 | failure. This interface is a preferred way to present the error to the end
|
---|
252 | user because it contains a human readable description of the error. Raw
|
---|
253 | result codes, both standard and described in this section, are intended to
|
---|
254 | be used by programs to analyze the reason of a failure and select an
|
---|
255 | appropriate course of action without involving the end user (for example,
|
---|
256 | retry the operation later or make a different call).
|
---|
257 |
|
---|
258 | The standard COM result codes that may originate from our methods include:
|
---|
259 |
|
---|
260 | <table>
|
---|
261 | <tr><td>E_INVALIDARG</td>
|
---|
262 | <td>
|
---|
263 | Returned when the value of the method's argument is not within the range
|
---|
264 | of valid values. This should not be confused with situations when the
|
---|
265 | value is within the range but simply doesn't suit the current object
|
---|
266 | state and there is a possibility that it will be accepted later (in such
|
---|
267 | cases VirtualBox-specific codes are returned, for example,
|
---|
268 | <link to="VBOX_E_OBJECT_NOT_FOUND"/>).
|
---|
269 | </td>
|
---|
270 | </tr>
|
---|
271 | <tr><td>E_POINTER</td>
|
---|
272 | <td>
|
---|
273 | Returned if a memory pointer for the output argument is invalid (for
|
---|
274 | example, @c null). Note that when pointers representing input
|
---|
275 | arguments (such as strings) are invalid, E_INVALIDARG is returned.
|
---|
276 | </td>
|
---|
277 | </tr>
|
---|
278 | <tr><td>E_ACCESSDENIED</td>
|
---|
279 | <td>
|
---|
280 | Returned when the called object is not ready. Since the lifetime of a
|
---|
281 | public COM object cannot be fully controlled by the implementation,
|
---|
282 | VirtualBox maintains the readiness state for all objects it creates and
|
---|
283 | returns this code in response to any method call on the object that was
|
---|
284 | deactivated by VirtualBox and is not functioning any more.
|
---|
285 | </td>
|
---|
286 | </tr>
|
---|
287 | <tr><td>E_OUTOFMEMORY</td>
|
---|
288 | <td>
|
---|
289 | Returned when a memory allocation operation fails.
|
---|
290 | </td>
|
---|
291 | </tr>
|
---|
292 | </table>
|
---|
293 | </desc>
|
---|
294 | </descGroup>
|
---|
295 |
|
---|
296 | <!--
|
---|
297 | Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
|
---|
298 | everything in <result>/<desc> after (and including) the first dot, so express
|
---|
299 | the matter of the error code in the first sentence and keep it short.
|
---|
300 | -->
|
---|
301 |
|
---|
302 | <result name="VBOX_E_OBJECT_NOT_FOUND" value="0x80BB0001">
|
---|
303 | <desc>
|
---|
304 | Object corresponding to the supplied arguments does not exist.
|
---|
305 | </desc>
|
---|
306 | </result>
|
---|
307 |
|
---|
308 | <result name="VBOX_E_INVALID_VM_STATE" value="0x80BB0002">
|
---|
309 | <desc>
|
---|
310 | Current virtual machine state prevents the operation.
|
---|
311 | </desc>
|
---|
312 | </result>
|
---|
313 |
|
---|
314 | <result name="VBOX_E_VM_ERROR" value="0x80BB0003">
|
---|
315 | <desc>
|
---|
316 | Virtual machine error occurred attempting the operation.
|
---|
317 | </desc>
|
---|
318 | </result>
|
---|
319 |
|
---|
320 | <result name="VBOX_E_FILE_ERROR" value="0x80BB0004">
|
---|
321 | <desc>
|
---|
322 | File not accessible or erroneous file contents.
|
---|
323 | </desc>
|
---|
324 | </result>
|
---|
325 |
|
---|
326 | <result name="VBOX_E_IPRT_ERROR" value="0x80BB0005">
|
---|
327 | <desc>
|
---|
328 | Runtime subsystem error.
|
---|
329 | </desc>
|
---|
330 | </result>
|
---|
331 |
|
---|
332 | <result name="VBOX_E_PDM_ERROR" value="0x80BB0006">
|
---|
333 | <desc>
|
---|
334 | Pluggable Device Manager error.
|
---|
335 | </desc>
|
---|
336 | </result>
|
---|
337 |
|
---|
338 | <result name="VBOX_E_INVALID_OBJECT_STATE" value="0x80BB0007">
|
---|
339 | <desc>
|
---|
340 | Current object state prohibits operation.
|
---|
341 | </desc>
|
---|
342 | </result>
|
---|
343 |
|
---|
344 | <result name="VBOX_E_HOST_ERROR" value="0x80BB0008">
|
---|
345 | <desc>
|
---|
346 | Host operating system related error.
|
---|
347 | </desc>
|
---|
348 | </result>
|
---|
349 |
|
---|
350 | <result name="VBOX_E_NOT_SUPPORTED" value="0x80BB0009">
|
---|
351 | <desc>
|
---|
352 | Requested operation is not supported.
|
---|
353 | </desc>
|
---|
354 | </result>
|
---|
355 |
|
---|
356 | <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
|
---|
357 | <desc>
|
---|
358 | Invalid XML found.
|
---|
359 | </desc>
|
---|
360 | </result>
|
---|
361 |
|
---|
362 | <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
|
---|
363 | <desc>
|
---|
364 | Current session state prohibits operation.
|
---|
365 | </desc>
|
---|
366 | </result>
|
---|
367 |
|
---|
368 | <result name="VBOX_E_OBJECT_IN_USE" value="0x80BB000C">
|
---|
369 | <desc>
|
---|
370 | Object being in use prohibits operation.
|
---|
371 | </desc>
|
---|
372 | </result>
|
---|
373 |
|
---|
374 | <!--
|
---|
375 | Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
|
---|
376 | everything in <result>/<desc> after (and including) the first dot, so express
|
---|
377 | the matter of the error code in the first sentence and keep it short.
|
---|
378 | -->
|
---|
379 |
|
---|
380 | <descGroup/>
|
---|
381 |
|
---|
382 | <!--
|
---|
383 | // all common enums
|
---|
384 | /////////////////////////////////////////////////////////////////////////
|
---|
385 | -->
|
---|
386 |
|
---|
387 | <enum
|
---|
388 | name="SettingsVersion"
|
---|
389 | uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
|
---|
390 | >
|
---|
391 | <desc>
|
---|
392 | Settings version of VirtualBox settings files. This is written to
|
---|
393 | the "version" attribute of the root "VirtualBox" element in the settings
|
---|
394 | file XML and indicates which VirtualBox version wrote the file.
|
---|
395 | </desc>
|
---|
396 |
|
---|
397 | <const name="Null" value="0">
|
---|
398 | <desc>Null value, indicates invalid version.</desc>
|
---|
399 | </const>
|
---|
400 | <const name="v1_0" value="1">
|
---|
401 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
402 | </const>
|
---|
403 | <const name="v1_1" value="2">
|
---|
404 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
405 | </const>
|
---|
406 | <const name="v1_2" value="3">
|
---|
407 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
408 | </const>
|
---|
409 | <const name="v1_3pre" value="4">
|
---|
410 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
411 | </const>
|
---|
412 | <const name="v1_3" value="5">
|
---|
413 | <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
|
---|
414 | <!--
|
---|
415 | Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
|
---|
416 | -->
|
---|
417 | </const>
|
---|
418 | <const name="v1_4" value="6">
|
---|
419 | <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
|
---|
420 | <!--
|
---|
421 | VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
|
---|
422 | (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
|
---|
423 | -->
|
---|
424 | </const>
|
---|
425 | <const name="v1_5" value="7">
|
---|
426 | <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
|
---|
427 | <!--
|
---|
428 | 2008-09-04: 2.0.0 released
|
---|
429 | 2008-11-20: settings version 1.5 introduced
|
---|
430 | 2008-12-17: 2.1.0 released
|
---|
431 | Machine changes:
|
---|
432 | guest OS identifiers changed;
|
---|
433 | Machine/Hardware/Display/MonitorCount renamed to monitorCount;
|
---|
434 | Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
|
---|
435 | Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
|
---|
436 | -->
|
---|
437 | </const>
|
---|
438 | <const name="v1_6" value="8">
|
---|
439 | <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
|
---|
440 | <!--
|
---|
441 | 2008-12-17: 2.1.0 released
|
---|
442 | 2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
|
---|
443 | 2009-04-08: 2.2.0 released
|
---|
444 | Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
|
---|
445 | -->
|
---|
446 | </const>
|
---|
447 | <const name="v1_7" value="9">
|
---|
448 | <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
|
---|
449 | <!--
|
---|
450 | 2008-12-17: 2.1.0 released
|
---|
451 | 2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
|
---|
452 | 2009-04-08: 2.2.0 released
|
---|
453 | VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
|
---|
454 | Machine changes: HardDiskAttachments is now StorageControllers (done)
|
---|
455 | -->
|
---|
456 | </const>
|
---|
457 | <const name="v1_8" value="10">
|
---|
458 | <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
|
---|
459 | <!--
|
---|
460 | Machine additions: Display/@accelerate2DVideo (done)
|
---|
461 | -->
|
---|
462 | </const>
|
---|
463 | <const name="v1_9" value="11">
|
---|
464 | <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
|
---|
465 | <!--
|
---|
466 | The big storage controller / DVD / Floppy rework (done)
|
---|
467 | -->
|
---|
468 | </const>
|
---|
469 | <const name="v1_10" value="12">
|
---|
470 | <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
|
---|
471 | <!--
|
---|
472 | Machine changes: RTC localOrUTC (done)
|
---|
473 | CPU hot-plug support
|
---|
474 | -->
|
---|
475 | </const>
|
---|
476 | <const name="v1_11" value="13">
|
---|
477 | <desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc>
|
---|
478 | <!--
|
---|
479 | Machine changes: HD Audio controller, per-machine disk registries,
|
---|
480 | /@format attribute for DVD and floppy images.
|
---|
481 | -->
|
---|
482 | </const>
|
---|
483 | <const name="v1_12" value="14">
|
---|
484 | <desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc>
|
---|
485 | <!--
|
---|
486 | Machine changes: raw PCI device attachment;
|
---|
487 | NetworkAdapter changes: bandwidth group.
|
---|
488 | -->
|
---|
489 | </const>
|
---|
490 |
|
---|
491 | <const name="Future" value="99999">
|
---|
492 | <desc>Settings version greater than "1.11", written by a future VirtualBox version.</desc>
|
---|
493 | </const>
|
---|
494 | </enum>
|
---|
495 |
|
---|
496 | <enum
|
---|
497 | name="AccessMode"
|
---|
498 | uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
|
---|
499 | >
|
---|
500 | <desc>
|
---|
501 | Access mode for opening files.
|
---|
502 | </desc>
|
---|
503 |
|
---|
504 | <const name="ReadOnly" value="1"/>
|
---|
505 | <const name="ReadWrite" value="2"/>
|
---|
506 | </enum>
|
---|
507 |
|
---|
508 | <enum
|
---|
509 | name="MachineState"
|
---|
510 | uuid="ec6c6a9e-113d-4ff4-b44f-0b69f21c97fe"
|
---|
511 | >
|
---|
512 | <desc>
|
---|
513 | Virtual machine execution state.
|
---|
514 |
|
---|
515 | This enumeration represents possible values of the <link
|
---|
516 | to="IMachine::state"/> attribute.
|
---|
517 |
|
---|
518 | Below is the basic virtual machine state diagram. It shows how the state
|
---|
519 | changes during virtual machine execution. The text in square braces shows
|
---|
520 | a method of the IConsole interface that performs the given state
|
---|
521 | transition.
|
---|
522 |
|
---|
523 | <pre>
|
---|
524 | +---------[powerDown()] <- Stuck <--[failure]-+
|
---|
525 | V |
|
---|
526 | +-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+
|
---|
527 | | | | | V |
|
---|
528 | | Aborted -----+ +--> Running --[pause()]--> Paused
|
---|
529 | | | ^ | ^ |
|
---|
530 | | Saved -----------[powerUp()]--> Restoring -+ | | | |
|
---|
531 | | ^ | | | |
|
---|
532 | | | +-----------------------------------------+-|-------------------+ +
|
---|
533 | | | | | |
|
---|
534 | | | +-- Saving <--------[takeSnapshot()]<-------+---------------------+
|
---|
535 | | | | |
|
---|
536 | | +-------- Saving <--------[saveState()]<----------+---------------------+
|
---|
537 | | | |
|
---|
538 | +-------------- Stopping -------[powerDown()]<----------+---------------------+
|
---|
539 | </pre>
|
---|
540 |
|
---|
541 | Note that states to the right from PoweredOff, Aborted and Saved in the
|
---|
542 | above diagram are called <i>online VM states</i>. These states
|
---|
543 | represent the virtual machine which is being executed in a dedicated
|
---|
544 | process (usually with a GUI window attached to it where you can see the
|
---|
545 | activity of the virtual machine and interact with it). There are two
|
---|
546 | special pseudo-states, FirstOnline and LastOnline, that can be used in
|
---|
547 | relational expressions to detect if the given machine state is online or
|
---|
548 | not:
|
---|
549 |
|
---|
550 | <pre>
|
---|
551 | if (machine.GetState() >= MachineState_FirstOnline &&
|
---|
552 | machine.GetState() <= MachineState_LastOnline)
|
---|
553 | {
|
---|
554 | ...the machine is being executed...
|
---|
555 | }
|
---|
556 | </pre>
|
---|
557 |
|
---|
558 | When the virtual machine is in one of the online VM states (that is, being
|
---|
559 | executed), only a few machine settings can be modified. Methods working
|
---|
560 | with such settings contain an explicit note about that. An attempt to
|
---|
561 | change any oter setting or perform a modifying operation during this time
|
---|
562 | will result in the @c VBOX_E_INVALID_VM_STATE error.
|
---|
563 |
|
---|
564 | All online states except Running, Paused and Stuck are transitional: they
|
---|
565 | represent temporary conditions of the virtual machine that will last as
|
---|
566 | long as the operation that initiated such a condition.
|
---|
567 |
|
---|
568 | The Stuck state is a special case. It means that execution of the machine
|
---|
569 | has reached the "Guru Meditation" condition. This condition indicates an
|
---|
570 | internal VMM (virtual machine manager) failure which may happen as a
|
---|
571 | result of either an unhandled low-level virtual hardware exception or one
|
---|
572 | of the recompiler exceptions (such as the <i>too-many-traps</i>
|
---|
573 | condition).
|
---|
574 |
|
---|
575 | Note also that any online VM state may transit to the Aborted state. This
|
---|
576 | happens if the process that is executing the virtual machine terminates
|
---|
577 | unexpectedly (for example, crashes). Other than that, the Aborted state is
|
---|
578 | equivalent to PoweredOff.
|
---|
579 |
|
---|
580 | There are also a few additional state diagrams that do not deal with
|
---|
581 | virtual machine execution and therefore are shown separately. The states
|
---|
582 | shown on these diagrams are called <i>offline VM states</i> (this includes
|
---|
583 | PoweredOff, Aborted and Saved too).
|
---|
584 |
|
---|
585 | The first diagram shows what happens when a lengthy setup operation is
|
---|
586 | being executed (such as <link to="IMachine::attachDevice"/>).
|
---|
587 |
|
---|
588 | <pre>
|
---|
589 | +----------------------------------(same state as before the call)------+
|
---|
590 | | |
|
---|
591 | +-> PoweredOff --+ |
|
---|
592 | | | |
|
---|
593 | |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
|
---|
594 | | |
|
---|
595 | +-> Saved -------+
|
---|
596 | </pre>
|
---|
597 |
|
---|
598 | The next two diagrams demonstrate the process of taking a snapshot of a
|
---|
599 | powered off virtual machine, restoring the state to that as of a snapshot
|
---|
600 | or deleting a snapshot, respectively.
|
---|
601 |
|
---|
602 | <pre>
|
---|
603 | +----------------------------------(same state as before the call)------+
|
---|
604 | | |
|
---|
605 | +-> PoweredOff --+ |
|
---|
606 | | +-->[takeSnapshot()] -------------------> Saving ------+
|
---|
607 | +-> Aborted -----+
|
---|
608 |
|
---|
609 | +-> PoweredOff --+
|
---|
610 | | |
|
---|
611 | | Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
|
---|
612 | | | [deleteSnapshot() ]-------> DeletingSnapshot --+
|
---|
613 | +-> Saved -------+ |
|
---|
614 | | |
|
---|
615 | +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
|
---|
616 | </pre>
|
---|
617 |
|
---|
618 | Note that the Saving state is present in both the offline state group and
|
---|
619 | online state group. Currently, the only way to determine what group is
|
---|
620 | assumed in a particular case is to remember the previous machine state: if
|
---|
621 | it was Running or Paused, then Saving is an online state, otherwise it is
|
---|
622 | an offline state. This inconsistency may be removed in one of the future
|
---|
623 | versions of VirtualBox by adding a new state.
|
---|
624 |
|
---|
625 | <note internal="yes">
|
---|
626 | For whoever decides to touch this enum: In order to keep the
|
---|
627 | comparisons involving FirstOnline and LastOnline pseudo-states valid,
|
---|
628 | the numeric values of these states must be correspondingly updated if
|
---|
629 | needed: for any online VM state, the condition
|
---|
630 | <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
631 | @c true. The same relates to transient states for which
|
---|
632 | the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
633 | @c true.
|
---|
634 | </note>
|
---|
635 | </desc>
|
---|
636 |
|
---|
637 | <const name="Null" value="0">
|
---|
638 | <desc>Null value (never used by the API).</desc>
|
---|
639 | </const>
|
---|
640 | <const name="PoweredOff" value="1">
|
---|
641 | <desc>
|
---|
642 | The machine is not running and has no saved execution state; it has
|
---|
643 | either never been started or been shut down successfully.
|
---|
644 | </desc>
|
---|
645 | </const>
|
---|
646 | <const name="Saved" value="2">
|
---|
647 | <desc>
|
---|
648 | The machine is not currently running, but the execution state of the machine
|
---|
649 | has been saved to an external file when it was running, from where
|
---|
650 | it can be resumed.
|
---|
651 | </desc>
|
---|
652 | </const>
|
---|
653 | <const name="Teleported" value="3">
|
---|
654 | <desc>
|
---|
655 | The machine was teleported to a different host (or process) and then
|
---|
656 | powered off. Take care when powering it on again may corrupt resources
|
---|
657 | it shares with the teleportation target (e.g. disk and network).
|
---|
658 | </desc>
|
---|
659 | </const>
|
---|
660 | <const name="Aborted" value="4">
|
---|
661 | <desc>
|
---|
662 | The process running the machine has terminated abnormally. This may
|
---|
663 | indicate a crash of the VM process in host execution context, or
|
---|
664 | the VM process has been terminated externally.
|
---|
665 | </desc>
|
---|
666 | </const>
|
---|
667 | <const name="Running" value="5">
|
---|
668 | <desc>
|
---|
669 | The machine is currently being executed.
|
---|
670 | <note internal="yes">
|
---|
671 | For whoever decides to touch this enum: In order to keep the
|
---|
672 | comparisons in the old source code valid, this state must immediately
|
---|
673 | precede the Paused state.
|
---|
674 | TODO: Lift this spectacularly wonderful restriction.
|
---|
675 | </note>
|
---|
676 | </desc>
|
---|
677 | </const>
|
---|
678 | <const name="Paused" value="6">
|
---|
679 | <desc>
|
---|
680 | Execution of the machine has been paused.
|
---|
681 | <note internal="yes">
|
---|
682 | For whoever decides to touch this enum: In order to keep the
|
---|
683 | comparisons in the old source code valid, this state must immediately
|
---|
684 | follow the Running state.
|
---|
685 | TODO: Lift this spectacularly wonderful restriction.
|
---|
686 | </note>
|
---|
687 | </desc>
|
---|
688 | </const>
|
---|
689 | <const name="Stuck" value="7">
|
---|
690 | <desc>
|
---|
691 | Execution of the machine has reached the "Guru Meditation"
|
---|
692 | condition. This indicates a severe error in the hypervisor itself.
|
---|
693 | <note internal="yes">
|
---|
694 | bird: Why this uncool name? Could we rename it to "GuruMeditation" or
|
---|
695 | "Guru", perhaps? Or are there some other VMM states that are
|
---|
696 | intended to be lumped in here as well?
|
---|
697 | </note>
|
---|
698 | </desc>
|
---|
699 | </const>
|
---|
700 | <const name="Teleporting" value="8">
|
---|
701 | <desc>
|
---|
702 | The machine is about to be teleported to a different host or process.
|
---|
703 | It is possible to pause a machine in this state, but it will go to the
|
---|
704 | @c TeleportingPausedVM state and it will not be
|
---|
705 | possible to resume it again unless the teleportation fails.
|
---|
706 | </desc>
|
---|
707 | </const>
|
---|
708 | <const name="LiveSnapshotting" value="9">
|
---|
709 | <desc>
|
---|
710 | A live snapshot is being taken. The machine is running normally, but
|
---|
711 | some of the runtime configuration options are inaccessible. Also, if
|
---|
712 | paused while in this state it will transition to
|
---|
713 | @c Saving and it will not be resume the
|
---|
714 | execution until the snapshot operation has completed.
|
---|
715 | </desc>
|
---|
716 | </const>
|
---|
717 | <const name="Starting" value="10">
|
---|
718 | <desc>
|
---|
719 | Machine is being started after powering it on from a
|
---|
720 | zero execution state.
|
---|
721 | </desc>
|
---|
722 | </const>
|
---|
723 | <const name="Stopping" value="11">
|
---|
724 | <desc>
|
---|
725 | Machine is being normally stopped powering it off, or after the guest OS
|
---|
726 | has initiated a shutdown sequence.
|
---|
727 | </desc>
|
---|
728 | </const>
|
---|
729 | <const name="Saving" value="12">
|
---|
730 | <desc>
|
---|
731 | Machine is saving its execution state to a file, or an online
|
---|
732 | snapshot of the machine is being taken.
|
---|
733 | </desc>
|
---|
734 | </const>
|
---|
735 | <const name="Restoring" value="13">
|
---|
736 | <desc>
|
---|
737 | Execution state of the machine is being restored from a file
|
---|
738 | after powering it on from the saved execution state.
|
---|
739 | </desc>
|
---|
740 | </const>
|
---|
741 | <const name="TeleportingPausedVM" value="14">
|
---|
742 | <desc>
|
---|
743 | The machine is being teleported to another host or process, but it is
|
---|
744 | not running. This is the paused variant of the
|
---|
745 | @c state.
|
---|
746 | </desc>
|
---|
747 | </const>
|
---|
748 | <const name="TeleportingIn" value="15">
|
---|
749 | <desc>
|
---|
750 | Teleporting the machine state in from another host or process.
|
---|
751 | </desc>
|
---|
752 | </const>
|
---|
753 | <const name="FaultTolerantSyncing" value="16">
|
---|
754 | <desc>
|
---|
755 | The machine is being synced with a fault tolerant VM running elsewhere.
|
---|
756 | </desc>
|
---|
757 | </const>
|
---|
758 | <const name="DeletingSnapshotOnline" value="17">
|
---|
759 | <desc>
|
---|
760 | Like @c DeletingSnapshot, but the merging of media is ongoing in
|
---|
761 | the background while the machine is running.
|
---|
762 | </desc>
|
---|
763 | </const>
|
---|
764 | <const name="DeletingSnapshotPaused" value="18">
|
---|
765 | <desc>
|
---|
766 | Like @c DeletingSnapshotOnline, but the machine was paused when the
|
---|
767 | merging of differencing media was started.
|
---|
768 | </desc>
|
---|
769 | </const>
|
---|
770 | <const name="RestoringSnapshot" value="19">
|
---|
771 | <desc>
|
---|
772 | A machine snapshot is being restored; this typically does not take long.
|
---|
773 | </desc>
|
---|
774 | </const>
|
---|
775 | <const name="DeletingSnapshot" value="20">
|
---|
776 | <desc>
|
---|
777 | A machine snapshot is being deleted; this can take a long time since this
|
---|
778 | may require merging differencing media. This value indicates that the
|
---|
779 | machine is not running while the snapshot is being deleted.
|
---|
780 | </desc>
|
---|
781 | </const>
|
---|
782 | <const name="SettingUp" value="21">
|
---|
783 | <desc>
|
---|
784 | Lengthy setup operation is in progress.
|
---|
785 | </desc>
|
---|
786 | </const>
|
---|
787 |
|
---|
788 | <const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
|
---|
789 | <desc>
|
---|
790 | Pseudo-state: first online state (for use in relational expressions).
|
---|
791 | </desc>
|
---|
792 | </const>
|
---|
793 | <const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
|
---|
794 | <desc>
|
---|
795 | Pseudo-state: last online state (for use in relational expressions).
|
---|
796 | </desc>
|
---|
797 | </const>
|
---|
798 |
|
---|
799 | <const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
|
---|
800 | <desc>
|
---|
801 | Pseudo-state: first transient state (for use in relational expressions).
|
---|
802 | </desc>
|
---|
803 | </const>
|
---|
804 | <const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp -->
|
---|
805 | <desc>
|
---|
806 | Pseudo-state: last transient state (for use in relational expressions).
|
---|
807 | </desc>
|
---|
808 | </const>
|
---|
809 |
|
---|
810 | </enum>
|
---|
811 |
|
---|
812 | <enum
|
---|
813 | name="SessionState"
|
---|
814 | uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
|
---|
815 | >
|
---|
816 | <desc>
|
---|
817 | Session state. This enumeration represents possible values of
|
---|
818 | <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
|
---|
819 | attributes.
|
---|
820 | </desc>
|
---|
821 |
|
---|
822 | <const name="Null" value="0">
|
---|
823 | <desc>Null value (never used by the API).</desc>
|
---|
824 | </const>
|
---|
825 | <const name="Unlocked" value="1">
|
---|
826 | <desc>
|
---|
827 | In <link to="IMachine::sessionState"/>, this means that the machine
|
---|
828 | is not locked for any sessions.
|
---|
829 |
|
---|
830 | In <link to="ISession::state"/>, this means that no machine is
|
---|
831 | currently locked for this session.
|
---|
832 | </desc>
|
---|
833 | </const>
|
---|
834 | <const name="Locked" value="2">
|
---|
835 | <desc>
|
---|
836 | In <link to="IMachine::sessionState"/>, this means that the machine
|
---|
837 | is currently locked for a session, whose process identifier can
|
---|
838 | then be found in the <link to="IMachine::sessionPid" /> attribute.
|
---|
839 |
|
---|
840 | In <link to="ISession::state"/>, this means that a machine is
|
---|
841 | currently locked for this session, and the mutable machine object
|
---|
842 | can be found in the <link to="ISession::machine"/> attribute
|
---|
843 | (see <link to="IMachine::lockMachine" /> for details).
|
---|
844 | </desc>
|
---|
845 | </const>
|
---|
846 | <const name="Spawning" value="3">
|
---|
847 | <desc>
|
---|
848 | A new process is being spawned for the machine as a result of
|
---|
849 | <link to="IMachine::launchVMProcess"/> call. This state also occurs
|
---|
850 | as a short transient state during an <link to="IMachine::lockMachine"/>
|
---|
851 | call.
|
---|
852 | </desc>
|
---|
853 | </const>
|
---|
854 | <const name="Unlocking" value="4">
|
---|
855 | <desc>
|
---|
856 | The session is being unlocked.
|
---|
857 | </desc>
|
---|
858 | </const>
|
---|
859 | </enum>
|
---|
860 |
|
---|
861 | <enum
|
---|
862 | name="CPUPropertyType"
|
---|
863 | uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
|
---|
864 | >
|
---|
865 | <desc>
|
---|
866 | Virtual CPU property type. This enumeration represents possible values of the
|
---|
867 | IMachine get- and setCPUProperty methods.
|
---|
868 | </desc>
|
---|
869 | <const name="Null" value="0">
|
---|
870 | <desc>Null value (never used by the API).</desc>
|
---|
871 | </const>
|
---|
872 | <const name="PAE" value="1">
|
---|
873 | <desc>
|
---|
874 | This setting determines whether VirtualBox will expose the Physical Address
|
---|
875 | Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
|
---|
876 | is not available, it will not be reported.
|
---|
877 | </desc>
|
---|
878 | </const>
|
---|
879 | <const name="Synthetic" value="2">
|
---|
880 | <desc>
|
---|
881 | This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
|
---|
882 | teleporting between host systems that differ significantly.
|
---|
883 | </desc>
|
---|
884 | </const>
|
---|
885 | </enum>
|
---|
886 |
|
---|
887 |
|
---|
888 | <enum
|
---|
889 | name="HWVirtExPropertyType"
|
---|
890 | uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
|
---|
891 | >
|
---|
892 | <desc>
|
---|
893 | Hardware virtualization property type. This enumeration represents possible values
|
---|
894 | for the <link to="IMachine::getHWVirtExProperty"/> and
|
---|
895 | <link to="IMachine::setHWVirtExProperty"/> methods.
|
---|
896 | </desc>
|
---|
897 | <const name="Null" value="0">
|
---|
898 | <desc>Null value (never used by the API).</desc>
|
---|
899 | </const>
|
---|
900 | <const name="Enabled" value="1">
|
---|
901 | <desc>
|
---|
902 | Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
|
---|
903 | such extensions are not available, they will not be used.
|
---|
904 | </desc>
|
---|
905 | </const>
|
---|
906 | <const name="Exclusive" value="2">
|
---|
907 | <desc>
|
---|
908 | Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
|
---|
909 | VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
|
---|
910 | feature of the host. To share these with other hypervisors, you must disable this property.
|
---|
911 | </desc>
|
---|
912 | </const>
|
---|
913 | <const name="VPID" value="3">
|
---|
914 | <desc>
|
---|
915 | Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
|
---|
916 | </desc>
|
---|
917 | </const>
|
---|
918 | <const name="NestedPaging" value="4">
|
---|
919 | <desc>
|
---|
920 | Whether Nested Paging is enabled. If this extension is not available, it will not be used.
|
---|
921 | </desc>
|
---|
922 | </const>
|
---|
923 | <const name="LargePages" value="5">
|
---|
924 | <desc>
|
---|
925 | Whether large page allocation is enabled; requires nested paging and a 64 bits host.
|
---|
926 | </desc>
|
---|
927 | </const>
|
---|
928 | <const name="Force" value="6">
|
---|
929 | <desc>
|
---|
930 | Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If
|
---|
931 | not set, there will be an automatic fallback to software virtualization.
|
---|
932 | </desc>
|
---|
933 | </const>
|
---|
934 | </enum>
|
---|
935 |
|
---|
936 | <enum
|
---|
937 | name="FaultToleranceState"
|
---|
938 | uuid="5124f7ec-6b67-493c-9dee-ee45a44114e1"
|
---|
939 | >
|
---|
940 | <desc>
|
---|
941 | Used with <link to="IMachine::faultToleranceState" />.
|
---|
942 | </desc>
|
---|
943 | <const name="Inactive" value="1">
|
---|
944 | <desc>No fault tolerance enabled.</desc>
|
---|
945 | </const>
|
---|
946 | <const name="Master" value="2">
|
---|
947 | <desc>Fault tolerant master VM.</desc>
|
---|
948 | </const>
|
---|
949 | <const name="Standby" value="3">
|
---|
950 | <desc>Fault tolerant standby VM.</desc>
|
---|
951 | </const>
|
---|
952 | </enum>
|
---|
953 |
|
---|
954 | <enum
|
---|
955 | name="LockType"
|
---|
956 | uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"
|
---|
957 | >
|
---|
958 | <desc>
|
---|
959 | Used with <link to="IMachine::lockMachine" />.
|
---|
960 | </desc>
|
---|
961 | <const name="Write" value="2">
|
---|
962 | <desc>Lock the machine for writing.</desc>
|
---|
963 | </const>
|
---|
964 | <const name="Shared" value="1">
|
---|
965 | <desc>Request only a shared read lock for remote-controlling the machine.</desc>
|
---|
966 | </const>
|
---|
967 | </enum>
|
---|
968 |
|
---|
969 | <enum
|
---|
970 | name="SessionType"
|
---|
971 | uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
|
---|
972 | >
|
---|
973 | <desc>
|
---|
974 | Session type. This enumeration represents possible values of the
|
---|
975 | <link to="ISession::type"/> attribute.
|
---|
976 | </desc>
|
---|
977 |
|
---|
978 | <const name="Null" value="0">
|
---|
979 | <desc>Null value (never used by the API).</desc>
|
---|
980 | </const>
|
---|
981 | <const name="WriteLock" value="1">
|
---|
982 | <desc>
|
---|
983 | Session has acquired an exclusive write lock on a machine
|
---|
984 | using <link to="IMachine::lockMachine"/>.
|
---|
985 | </desc>
|
---|
986 | </const>
|
---|
987 | <const name="Remote" value="2">
|
---|
988 | <desc>
|
---|
989 | Session has launched a VM process using
|
---|
990 | <link to="IMachine::launchVMProcess"/>
|
---|
991 | </desc>
|
---|
992 | </const>
|
---|
993 | <const name="Shared" value="3">
|
---|
994 | <desc>
|
---|
995 | Session has obtained a link to another session using
|
---|
996 | <link to="IMachine::lockMachine"/>
|
---|
997 | </desc>
|
---|
998 | </const>
|
---|
999 | </enum>
|
---|
1000 |
|
---|
1001 | <enum
|
---|
1002 | name="DeviceType"
|
---|
1003 | uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
|
---|
1004 | >
|
---|
1005 | <desc>
|
---|
1006 | Device type.
|
---|
1007 | </desc>
|
---|
1008 | <const name="Null" value="0">
|
---|
1009 | <desc>
|
---|
1010 | Null value, may also mean "no device" (not allowed for
|
---|
1011 | <link to="IConsole::getDeviceActivity"/>).
|
---|
1012 | </desc>
|
---|
1013 | </const>
|
---|
1014 | <const name="Floppy" value="1">
|
---|
1015 | <desc>Floppy device.</desc>
|
---|
1016 | </const>
|
---|
1017 | <const name="DVD" value="2">
|
---|
1018 | <desc>CD/DVD-ROM device.</desc>
|
---|
1019 | </const>
|
---|
1020 | <const name="HardDisk" value="3">
|
---|
1021 | <desc>Hard disk device.</desc>
|
---|
1022 | </const>
|
---|
1023 | <const name="Network" value="4">
|
---|
1024 | <desc>Network device.</desc>
|
---|
1025 | </const>
|
---|
1026 | <const name="USB" value="5">
|
---|
1027 | <desc>USB device.</desc>
|
---|
1028 | </const>
|
---|
1029 | <const name="SharedFolder" value="6">
|
---|
1030 | <desc>Shared folder device.</desc>
|
---|
1031 | </const>
|
---|
1032 | </enum>
|
---|
1033 |
|
---|
1034 | <enum
|
---|
1035 | name="DeviceActivity"
|
---|
1036 | uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
|
---|
1037 | >
|
---|
1038 | <desc>
|
---|
1039 | Device activity for <link to="IConsole::getDeviceActivity"/>.
|
---|
1040 | </desc>
|
---|
1041 |
|
---|
1042 | <const name="Null" value="0"/>
|
---|
1043 | <const name="Idle" value="1"/>
|
---|
1044 | <const name="Reading" value="2"/>
|
---|
1045 | <const name="Writing" value="3"/>
|
---|
1046 | </enum>
|
---|
1047 |
|
---|
1048 | <enum
|
---|
1049 | name="ClipboardMode"
|
---|
1050 | uuid="33364716-4008-4701-8f14-be0fa3d62950"
|
---|
1051 | >
|
---|
1052 | <desc>
|
---|
1053 | Host-Guest clipboard interchange mode.
|
---|
1054 | </desc>
|
---|
1055 |
|
---|
1056 | <const name="Disabled" value="0"/>
|
---|
1057 | <const name="HostToGuest" value="1"/>
|
---|
1058 | <const name="GuestToHost" value="2"/>
|
---|
1059 | <const name="Bidirectional" value="3"/>
|
---|
1060 | </enum>
|
---|
1061 |
|
---|
1062 | <enum
|
---|
1063 | name="Scope"
|
---|
1064 | uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
|
---|
1065 | >
|
---|
1066 | <desc>
|
---|
1067 | Scope of the operation.
|
---|
1068 |
|
---|
1069 | A generic enumeration used in various methods to define the action or
|
---|
1070 | argument scope.
|
---|
1071 | </desc>
|
---|
1072 |
|
---|
1073 | <const name="Global" value="0"/>
|
---|
1074 | <const name="Machine" value="1"/>
|
---|
1075 | <const name="Session" value="2"/>
|
---|
1076 | </enum>
|
---|
1077 |
|
---|
1078 | <enum
|
---|
1079 | name="BIOSBootMenuMode"
|
---|
1080 | uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
|
---|
1081 | >
|
---|
1082 | <desc>
|
---|
1083 | BIOS boot menu mode.
|
---|
1084 | </desc>
|
---|
1085 |
|
---|
1086 | <const name="Disabled" value="0"/>
|
---|
1087 | <const name="MenuOnly" value="1"/>
|
---|
1088 | <const name="MessageAndMenu" value="2"/>
|
---|
1089 | </enum>
|
---|
1090 |
|
---|
1091 | <enum
|
---|
1092 | name="ProcessorFeature"
|
---|
1093 | uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
|
---|
1094 | >
|
---|
1095 | <desc>
|
---|
1096 | CPU features.
|
---|
1097 | </desc>
|
---|
1098 |
|
---|
1099 | <const name="HWVirtEx" value="0"/>
|
---|
1100 | <const name="PAE" value="1"/>
|
---|
1101 | <const name="LongMode" value="2"/>
|
---|
1102 | <const name="NestedPaging" value="3"/>
|
---|
1103 | </enum>
|
---|
1104 |
|
---|
1105 | <enum
|
---|
1106 | name="FirmwareType"
|
---|
1107 | uuid="b903f264-c230-483e-ac74-2b37ce60d371"
|
---|
1108 | >
|
---|
1109 | <desc>
|
---|
1110 | Firmware type.
|
---|
1111 | </desc>
|
---|
1112 | <const name="BIOS" value="1">
|
---|
1113 | <desc>BIOS Firmware.</desc>
|
---|
1114 | </const>
|
---|
1115 | <const name="EFI" value="2">
|
---|
1116 | <desc>EFI Firmware, bitness detected basing on OS type.</desc>
|
---|
1117 | </const>
|
---|
1118 | <const name="EFI32" value="3">
|
---|
1119 | <desc>Efi firmware, 32-bit.</desc>
|
---|
1120 | </const>
|
---|
1121 | <const name="EFI64" value="4">
|
---|
1122 | <desc>Efi firmware, 64-bit.</desc>
|
---|
1123 | </const>
|
---|
1124 | <const name="EFIDUAL" value="5">
|
---|
1125 | <desc>Efi firmware, combined 32 and 64-bit.</desc>
|
---|
1126 | </const>
|
---|
1127 | </enum>
|
---|
1128 |
|
---|
1129 | <enum
|
---|
1130 | name="PointingHidType"
|
---|
1131 | uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
|
---|
1132 | >
|
---|
1133 | <desc>
|
---|
1134 | Type of pointing device used in a virtual machine.
|
---|
1135 | </desc>
|
---|
1136 | <const name="None" value="1">
|
---|
1137 | <desc>No mouse.</desc>
|
---|
1138 | </const>
|
---|
1139 | <const name="PS2Mouse" value="2">
|
---|
1140 | <desc>PS/2 auxiliary device, a.k.a. mouse.</desc>
|
---|
1141 | </const>
|
---|
1142 | <const name="USBMouse" value="3">
|
---|
1143 | <desc>USB mouse (relative pointer).</desc>
|
---|
1144 | </const>
|
---|
1145 | <const name="USBTablet" value="4">
|
---|
1146 | <desc>USB tablet (absolute pointer).</desc>
|
---|
1147 | </const>
|
---|
1148 | <const name="ComboMouse" value="5">
|
---|
1149 | <desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
|
---|
1150 | Using of such device can have negative performance implications. </desc>
|
---|
1151 | </const>
|
---|
1152 | </enum>
|
---|
1153 |
|
---|
1154 | <enum
|
---|
1155 | name="KeyboardHidType"
|
---|
1156 | uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
|
---|
1157 | >
|
---|
1158 | <desc>
|
---|
1159 | Type of keyboard device used in a virtual machine.
|
---|
1160 | </desc>
|
---|
1161 | <const name="None" value="1">
|
---|
1162 | <desc>No keyboard.</desc>
|
---|
1163 | </const>
|
---|
1164 | <const name="PS2Keyboard" value="2">
|
---|
1165 | <desc>PS/2 keyboard.</desc>
|
---|
1166 | </const>
|
---|
1167 | <const name="USBKeyboard" value="3">
|
---|
1168 | <desc>USB keyboard.</desc>
|
---|
1169 | </const>
|
---|
1170 | <const name="ComboKeyboard" value="4">
|
---|
1171 | <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
|
---|
1172 | Using of such device can have negative performance implications. </desc>
|
---|
1173 | </const>
|
---|
1174 | </enum>
|
---|
1175 |
|
---|
1176 | <!--
|
---|
1177 | // IVirtualBoxErrorInfo
|
---|
1178 | /////////////////////////////////////////////////////////////////////////
|
---|
1179 | -->
|
---|
1180 |
|
---|
1181 | <interface
|
---|
1182 | name="IVirtualBoxErrorInfo" extends="$errorinfo"
|
---|
1183 | uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"
|
---|
1184 | supportsErrorInfo="no"
|
---|
1185 | wsmap="managed"
|
---|
1186 | >
|
---|
1187 | <desc>
|
---|
1188 | The IVirtualBoxErrorInfo interface represents extended error information.
|
---|
1189 |
|
---|
1190 | Extended error information can be set by VirtualBox components after
|
---|
1191 | unsuccessful or partially successful method invocation. This information
|
---|
1192 | can be retrieved by the calling party as an IVirtualBoxErrorInfo object
|
---|
1193 | and then shown to the client in addition to the plain 32-bit result code.
|
---|
1194 |
|
---|
1195 | In MS COM, this interface extends the IErrorInfo interface,
|
---|
1196 | in XPCOM, it extends the nsIException interface. In both cases,
|
---|
1197 | it provides a set of common attributes to retrieve error
|
---|
1198 | information.
|
---|
1199 |
|
---|
1200 | Sometimes invocation of some component's method may involve methods of
|
---|
1201 | other components that may also fail (independently of this method's
|
---|
1202 | failure), or a series of non-fatal errors may precede a fatal error that
|
---|
1203 | causes method failure. In cases like that, it may be desirable to preserve
|
---|
1204 | information about all errors happened during method invocation and deliver
|
---|
1205 | it to the caller. The <link to="#next"/> attribute is intended
|
---|
1206 | specifically for this purpose and allows to represent a chain of errors
|
---|
1207 | through a single IVirtualBoxErrorInfo object set after method invocation.
|
---|
1208 |
|
---|
1209 | Note that errors are stored to a chain in the reverse order, i.e. the
|
---|
1210 | initial error object you query right after method invocation is the last
|
---|
1211 | error set by the callee, the object it points to in the @a next attribute
|
---|
1212 | is the previous error and so on, up to the first error (which is the last
|
---|
1213 | in the chain).
|
---|
1214 | </desc>
|
---|
1215 |
|
---|
1216 | <attribute name="resultCode" type="long" readonly="yes">
|
---|
1217 | <desc>
|
---|
1218 | Result code of the error.
|
---|
1219 | Usually, it will be the same as the result code returned
|
---|
1220 | by the method that provided this error information, but not
|
---|
1221 | always. For example, on Win32, CoCreateInstance() will most
|
---|
1222 | likely return E_NOINTERFACE upon unsuccessful component
|
---|
1223 | instantiation attempt, but not the value the component factory
|
---|
1224 | returned. Value is typed 'long', not 'result',
|
---|
1225 | to make interface usable from scripting languages.
|
---|
1226 | <note>
|
---|
1227 | In MS COM, there is no equivalent.
|
---|
1228 | In XPCOM, it is the same as nsIException::result.
|
---|
1229 | </note>
|
---|
1230 | </desc>
|
---|
1231 | </attribute>
|
---|
1232 |
|
---|
1233 | <attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
|
---|
1234 | <desc>
|
---|
1235 | UUID of the interface that defined the error.
|
---|
1236 | <note>
|
---|
1237 | In MS COM, it is the same as IErrorInfo::GetGUID, except for the
|
---|
1238 | data type.
|
---|
1239 | In XPCOM, there is no equivalent.
|
---|
1240 | </note>
|
---|
1241 | </desc>
|
---|
1242 | </attribute>
|
---|
1243 |
|
---|
1244 | <attribute name="component" type="wstring" readonly="yes">
|
---|
1245 | <desc>
|
---|
1246 | Name of the component that generated the error.
|
---|
1247 | <note>
|
---|
1248 | In MS COM, it is the same as IErrorInfo::GetSource.
|
---|
1249 | In XPCOM, there is no equivalent.
|
---|
1250 | </note>
|
---|
1251 | </desc>
|
---|
1252 | </attribute>
|
---|
1253 |
|
---|
1254 | <attribute name="text" type="wstring" readonly="yes">
|
---|
1255 | <desc>
|
---|
1256 | Text description of the error.
|
---|
1257 | <note>
|
---|
1258 | In MS COM, it is the same as IErrorInfo::GetDescription.
|
---|
1259 | In XPCOM, it is the same as nsIException::message.
|
---|
1260 | </note>
|
---|
1261 | </desc>
|
---|
1262 | </attribute>
|
---|
1263 |
|
---|
1264 | <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
1265 | <desc>
|
---|
1266 | Next error object if there is any, or @c null otherwise.
|
---|
1267 | <note>
|
---|
1268 | In MS COM, there is no equivalent.
|
---|
1269 | In XPCOM, it is the same as nsIException::inner.
|
---|
1270 | </note>
|
---|
1271 | </desc>
|
---|
1272 | </attribute>
|
---|
1273 |
|
---|
1274 | </interface>
|
---|
1275 |
|
---|
1276 | <!--
|
---|
1277 | // IVirtualBox
|
---|
1278 | /////////////////////////////////////////////////////////////////////////
|
---|
1279 | -->
|
---|
1280 |
|
---|
1281 | <interface
|
---|
1282 | name="IDHCPServer" extends="$unknown"
|
---|
1283 | uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
|
---|
1284 | wsmap="managed"
|
---|
1285 | >
|
---|
1286 | <desc>
|
---|
1287 | The IDHCPServer interface represents the vbox dhcp server configuration.
|
---|
1288 |
|
---|
1289 | To enumerate all the dhcp servers on the host, use the
|
---|
1290 | <link to="IVirtualBox::DHCPServers"/> attribute.
|
---|
1291 | </desc>
|
---|
1292 |
|
---|
1293 | <attribute name="enabled" type="boolean">
|
---|
1294 | <desc>
|
---|
1295 | specifies if the dhcp server is enabled
|
---|
1296 | </desc>
|
---|
1297 | </attribute>
|
---|
1298 |
|
---|
1299 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
1300 | <desc>
|
---|
1301 | specifies server IP
|
---|
1302 | </desc>
|
---|
1303 | </attribute>
|
---|
1304 |
|
---|
1305 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
1306 | <desc>
|
---|
1307 | specifies server network mask
|
---|
1308 | </desc>
|
---|
1309 | </attribute>
|
---|
1310 |
|
---|
1311 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
1312 | <desc>
|
---|
1313 | specifies internal network name the server is used for
|
---|
1314 | </desc>
|
---|
1315 | </attribute>
|
---|
1316 |
|
---|
1317 | <attribute name="lowerIP" type="wstring" readonly="yes">
|
---|
1318 | <desc>
|
---|
1319 | specifies from IP address in server address range
|
---|
1320 | </desc>
|
---|
1321 | </attribute>
|
---|
1322 |
|
---|
1323 | <attribute name="upperIP" type="wstring" readonly="yes">
|
---|
1324 | <desc>
|
---|
1325 | specifies to IP address in server address range
|
---|
1326 | </desc>
|
---|
1327 | </attribute>
|
---|
1328 |
|
---|
1329 | <method name="setConfiguration">
|
---|
1330 | <desc>
|
---|
1331 | configures the server
|
---|
1332 | <result name="E_INVALIDARG">
|
---|
1333 | invalid configuration supplied
|
---|
1334 | </result>
|
---|
1335 | </desc>
|
---|
1336 | <param name="IPAddress" type="wstring" dir="in">
|
---|
1337 | <desc>
|
---|
1338 | server IP address
|
---|
1339 | </desc>
|
---|
1340 | </param>
|
---|
1341 | <param name="networkMask" type="wstring" dir="in">
|
---|
1342 | <desc>
|
---|
1343 | server network mask
|
---|
1344 | </desc>
|
---|
1345 | </param>
|
---|
1346 | <param name="FromIPAddress" type="wstring" dir="in">
|
---|
1347 | <desc>
|
---|
1348 | server From IP address for address range
|
---|
1349 | </desc>
|
---|
1350 | </param>
|
---|
1351 | <param name="ToIPAddress" type="wstring" dir="in">
|
---|
1352 | <desc>
|
---|
1353 | server To IP address for address range
|
---|
1354 | </desc>
|
---|
1355 | </param>
|
---|
1356 | </method>
|
---|
1357 |
|
---|
1358 | <method name="start">
|
---|
1359 | <desc>
|
---|
1360 | Starts DHCP server process.
|
---|
1361 | <result name="E_FAIL">
|
---|
1362 | Failed to start the process.
|
---|
1363 | </result>
|
---|
1364 | </desc>
|
---|
1365 | <param name="networkName" type="wstring" dir="in">
|
---|
1366 | <desc>
|
---|
1367 | Name of internal network DHCP server should attach to.
|
---|
1368 | </desc>
|
---|
1369 | </param>
|
---|
1370 | <param name="trunkName" type="wstring" dir="in">
|
---|
1371 | <desc>
|
---|
1372 | Name of internal network trunk.
|
---|
1373 | </desc>
|
---|
1374 | </param>
|
---|
1375 | <param name="trunkType" type="wstring" dir="in">
|
---|
1376 | <desc>
|
---|
1377 | Type of internal network trunk.
|
---|
1378 | </desc>
|
---|
1379 | </param>
|
---|
1380 | </method>
|
---|
1381 |
|
---|
1382 | <method name="stop">
|
---|
1383 | <desc>
|
---|
1384 | Stops DHCP server process.
|
---|
1385 | <result name="E_FAIL">
|
---|
1386 | Failed to stop the process.
|
---|
1387 | </result>
|
---|
1388 | </desc>
|
---|
1389 | </method>
|
---|
1390 | </interface>
|
---|
1391 |
|
---|
1392 | <interface
|
---|
1393 | name="IVirtualBox" extends="$unknown"
|
---|
1394 | uuid="d2de270c-1d4b-4c9e-843f-bbb9b47269ff"
|
---|
1395 | wsmap="managed"
|
---|
1396 | >
|
---|
1397 | <desc>
|
---|
1398 | The IVirtualBox interface represents the main interface exposed by the
|
---|
1399 | product that provides virtual machine management.
|
---|
1400 |
|
---|
1401 | An instance of IVirtualBox is required for the product to do anything
|
---|
1402 | useful. Even though the interface does not expose this, internally,
|
---|
1403 | IVirtualBox is implemented as a singleton and actually lives in the
|
---|
1404 | process of the VirtualBox server (VBoxSVC.exe). This makes sure that
|
---|
1405 | IVirtualBox can track the state of all virtual machines on a particular
|
---|
1406 | host, regardless of which frontend started them.
|
---|
1407 |
|
---|
1408 | To enumerate all the virtual machines on the host, use the
|
---|
1409 | <link to="IVirtualBox::machines"/> attribute.
|
---|
1410 | </desc>
|
---|
1411 |
|
---|
1412 | <attribute name="version" type="wstring" readonly="yes">
|
---|
1413 | <desc>
|
---|
1414 | A string representing the version number of the product. The
|
---|
1415 | format is 3 integer numbers divided by dots (e.g. 1.0.1). The
|
---|
1416 | last number represents the build number and will frequently change.
|
---|
1417 | </desc>
|
---|
1418 | </attribute>
|
---|
1419 |
|
---|
1420 | <attribute name="revision" type="unsigned long" readonly="yes">
|
---|
1421 | <desc>
|
---|
1422 | The internal build revision number of the product.
|
---|
1423 | </desc>
|
---|
1424 | </attribute>
|
---|
1425 |
|
---|
1426 | <attribute name="packageType" type="wstring" readonly="yes">
|
---|
1427 | <desc>
|
---|
1428 | A string representing the package type of this product. The
|
---|
1429 | format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
|
---|
1430 | SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
|
---|
1431 | is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
|
---|
1432 | this.
|
---|
1433 | </desc>
|
---|
1434 | </attribute>
|
---|
1435 |
|
---|
1436 | <attribute name="homeFolder" type="wstring" readonly="yes">
|
---|
1437 | <desc>
|
---|
1438 | Full path to the directory where the global settings file,
|
---|
1439 | <tt>VirtualBox.xml</tt>, is stored.
|
---|
1440 |
|
---|
1441 | In this version of VirtualBox, the value of this property is
|
---|
1442 | always <tt><user_dir>/.VirtualBox</tt> (where
|
---|
1443 | <tt><user_dir></tt> is the path to the user directory,
|
---|
1444 | as determined by the host OS), and cannot be changed.
|
---|
1445 |
|
---|
1446 | This path is also used as the base to resolve relative paths in
|
---|
1447 | places where relative paths are allowed (unless otherwise
|
---|
1448 | expressly indicated).
|
---|
1449 | </desc>
|
---|
1450 | </attribute>
|
---|
1451 |
|
---|
1452 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
1453 | <desc>
|
---|
1454 | Full name of the global settings file.
|
---|
1455 | The value of this property corresponds to the value of
|
---|
1456 | <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
|
---|
1457 | </desc>
|
---|
1458 | </attribute>
|
---|
1459 |
|
---|
1460 | <attribute name="host" type="IHost" readonly="yes">
|
---|
1461 | <desc>Associated host object.</desc>
|
---|
1462 | </attribute>
|
---|
1463 |
|
---|
1464 | <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
|
---|
1465 | <desc>Associated system information object.</desc>
|
---|
1466 | </attribute>
|
---|
1467 |
|
---|
1468 | <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
|
---|
1469 | <desc>
|
---|
1470 | Array of machine objects registered within this VirtualBox instance.
|
---|
1471 | </desc>
|
---|
1472 | </attribute>
|
---|
1473 |
|
---|
1474 | <attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
|
---|
1475 | <desc>
|
---|
1476 | Array of medium objects known to this VirtualBox installation.
|
---|
1477 |
|
---|
1478 | This array contains only base media. All differencing
|
---|
1479 | media of the given base medium can be enumerated using
|
---|
1480 | <link to="IMedium::children"/>.
|
---|
1481 | </desc>
|
---|
1482 | </attribute>
|
---|
1483 |
|
---|
1484 | <attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
|
---|
1485 | <desc>
|
---|
1486 | Array of CD/DVD image objects currently in use by this VirtualBox instance.
|
---|
1487 | </desc>
|
---|
1488 | </attribute>
|
---|
1489 |
|
---|
1490 | <attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
|
---|
1491 | <desc>
|
---|
1492 | Array of floppy image objects currently in use by this VirtualBox instance.
|
---|
1493 | </desc>
|
---|
1494 | </attribute>
|
---|
1495 |
|
---|
1496 | <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
|
---|
1497 |
|
---|
1498 | <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
|
---|
1499 |
|
---|
1500 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
1501 | <desc>
|
---|
1502 | Collection of global shared folders. Global shared folders are
|
---|
1503 | available to all virtual machines.
|
---|
1504 |
|
---|
1505 | New shared folders are added to the collection using
|
---|
1506 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
1507 | removed using <link to="#removeSharedFolder"/>.
|
---|
1508 |
|
---|
1509 | <note>
|
---|
1510 | In the current version of the product, global shared folders are not
|
---|
1511 | implemented and therefore this collection is always empty.
|
---|
1512 | </note>
|
---|
1513 | </desc>
|
---|
1514 | </attribute>
|
---|
1515 |
|
---|
1516 | <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
|
---|
1517 | <desc>
|
---|
1518 | Associated performance collector object.
|
---|
1519 | </desc>
|
---|
1520 | </attribute>
|
---|
1521 |
|
---|
1522 | <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
|
---|
1523 | <desc>
|
---|
1524 | DHCP servers.
|
---|
1525 | </desc>
|
---|
1526 | </attribute>
|
---|
1527 |
|
---|
1528 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
1529 | <desc>
|
---|
1530 | Event source for VirtualBox events.
|
---|
1531 | </desc>
|
---|
1532 | </attribute>
|
---|
1533 |
|
---|
1534 | <attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">
|
---|
1535 | <desc>
|
---|
1536 | The extension pack manager.
|
---|
1537 | </desc>
|
---|
1538 | </attribute>
|
---|
1539 |
|
---|
1540 |
|
---|
1541 | <method name="composeMachineFilename">
|
---|
1542 | <desc>
|
---|
1543 | Returns a recommended full path of the settings file name for a new virtual
|
---|
1544 | machine.
|
---|
1545 |
|
---|
1546 | This API serves two purposes:
|
---|
1547 |
|
---|
1548 | <ul>
|
---|
1549 | <li>It gets called by <link to="#createMachine" /> if NULL is specified
|
---|
1550 | for the @a settingsFile argument there, which means that API should use
|
---|
1551 | a recommended default file name.</li>
|
---|
1552 |
|
---|
1553 | <li>It can be called manually by a client software before creating a machine,
|
---|
1554 | e.g. if that client wants to pre-create the machine directory to create
|
---|
1555 | virtual hard disks in that directory together with the new machine
|
---|
1556 | settings file. In that case, the file name should be stripped from the
|
---|
1557 | full settings file path returned by this function to obtain the
|
---|
1558 | machine directory.</li>
|
---|
1559 | </ul>
|
---|
1560 |
|
---|
1561 | See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
|
---|
1562 | details about the machine name.
|
---|
1563 |
|
---|
1564 | If @a baseFolder is a @c null or empty string (which is recommended), the
|
---|
1565 | default machine settings folder
|
---|
1566 | (see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
|
---|
1567 | a base folder for the created machine, resulting in a file name like
|
---|
1568 | "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
|
---|
1569 | will be used.
|
---|
1570 |
|
---|
1571 | This method does not access the host disks. In particular, it does not check
|
---|
1572 | for whether a machine of this name already exists.
|
---|
1573 | </desc>
|
---|
1574 | <param name="name" type="wstring" dir="in">
|
---|
1575 | <desc>Suggested machine name.</desc>
|
---|
1576 | </param>
|
---|
1577 | <param name="baseFolder" type="wstring" dir="in">
|
---|
1578 | <desc>Base machine folder (optional).</desc>
|
---|
1579 | </param>
|
---|
1580 | <param name="file" type="wstring" dir="return">
|
---|
1581 | <desc>Fully qualified path where the machine would be created.</desc>
|
---|
1582 | </param>
|
---|
1583 | </method>
|
---|
1584 |
|
---|
1585 | <method name="createMachine">
|
---|
1586 | <desc>
|
---|
1587 | Creates a new virtual machine by creating a machine settings file at
|
---|
1588 | the given location.
|
---|
1589 |
|
---|
1590 | VirtualBox machine settings files use a custom XML dialect. Starting
|
---|
1591 | with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
|
---|
1592 | and machine files can be created at arbitrary locations.
|
---|
1593 |
|
---|
1594 | However, it is is recommended that machines be created in the default
|
---|
1595 | machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
|
---|
1596 | <link to="ISystemProperties::defaultMachineFolder" />). If you specify
|
---|
1597 | NULL for the @a settingsFile argument, <link to="#composeMachineFilename" />
|
---|
1598 | is called automatically to have such a recommended name composed based
|
---|
1599 | on the machine name given in the @a name argument.
|
---|
1600 |
|
---|
1601 | If the resulting settings file already exists, this method will fail,
|
---|
1602 | unless @a forceOverwrite is set.
|
---|
1603 |
|
---|
1604 | The new machine is created unregistered, with the initial configuration
|
---|
1605 | set according to the specified guest OS type. A typical sequence of
|
---|
1606 | actions to create a new virtual machine is as follows:
|
---|
1607 |
|
---|
1608 | <ol>
|
---|
1609 | <li>
|
---|
1610 | Call this method to have a new machine created. The returned machine
|
---|
1611 | object will be "mutable" allowing to change any machine property.
|
---|
1612 | </li>
|
---|
1613 |
|
---|
1614 | <li>
|
---|
1615 | Configure the machine using the appropriate attributes and methods.
|
---|
1616 | </li>
|
---|
1617 |
|
---|
1618 | <li>
|
---|
1619 | Call <link to="IMachine::saveSettings" /> to write the settings
|
---|
1620 | to the machine's XML settings file. The configuration of the newly
|
---|
1621 | created machine will not be saved to disk until this method is
|
---|
1622 | called.
|
---|
1623 | </li>
|
---|
1624 |
|
---|
1625 | <li>
|
---|
1626 | Call <link to="#registerMachine" /> to add the machine to the list
|
---|
1627 | of machines known to VirtualBox.
|
---|
1628 | </li>
|
---|
1629 | </ol>
|
---|
1630 |
|
---|
1631 | The specified guest OS type identifier must match an ID of one of known
|
---|
1632 | guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
|
---|
1633 | array.
|
---|
1634 |
|
---|
1635 | Optionally, you may specify an UUID of to assign to the created machine.
|
---|
1636 | However, this is not recommended and you should normally pass an empty
|
---|
1637 | (@c null) UUID to this method so that a new UUID will be automatically
|
---|
1638 | generated for every created machine. You can use UUID
|
---|
1639 | 00000000-0000-0000-0000-000000000000 as @c null value.
|
---|
1640 |
|
---|
1641 | <note>
|
---|
1642 | There is no way to change the name of the settings file or
|
---|
1643 | subfolder of the created machine directly.
|
---|
1644 | </note>
|
---|
1645 |
|
---|
1646 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1647 | @a osTypeId is invalid.
|
---|
1648 | </result>
|
---|
1649 | <result name="VBOX_E_FILE_ERROR">
|
---|
1650 | Resulting settings file name is invalid or the settings file already
|
---|
1651 | exists or could not be created due to an I/O error.
|
---|
1652 | </result>
|
---|
1653 | <result name="E_INVALIDARG">
|
---|
1654 | @a name is empty or @c null.
|
---|
1655 | </result>
|
---|
1656 | </desc>
|
---|
1657 |
|
---|
1658 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1659 | <desc>Fully qualified path where the settings file should be created,
|
---|
1660 | or NULL for a default folder and file based on the @a name argument
|
---|
1661 | (see <link to="#composeMachineFilename" />).</desc>
|
---|
1662 | </param>
|
---|
1663 | <param name="name" type="wstring" dir="in">
|
---|
1664 | <desc>Machine name.</desc>
|
---|
1665 | </param>
|
---|
1666 | <param name="osTypeId" type="wstring" dir="in">
|
---|
1667 | <desc>Guest OS Type ID.</desc>
|
---|
1668 | </param>
|
---|
1669 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
1670 | <desc>Machine UUID (optional).</desc>
|
---|
1671 | </param>
|
---|
1672 | <param name="forceOverwrite" type="boolean" dir="in">
|
---|
1673 | <desc>If true, an existing machine settings file will be overwritten.</desc>
|
---|
1674 | </param>
|
---|
1675 | <param name="machine" type="IMachine" dir="return">
|
---|
1676 | <desc>Created machine object.</desc>
|
---|
1677 | </param>
|
---|
1678 | </method>
|
---|
1679 |
|
---|
1680 | <method name="openMachine">
|
---|
1681 | <desc>
|
---|
1682 | Opens a virtual machine from the existing settings file.
|
---|
1683 | The opened machine remains unregistered until you call
|
---|
1684 | <link to="#registerMachine"/>.
|
---|
1685 |
|
---|
1686 | The specified settings file name must be fully qualified.
|
---|
1687 | The file must exist and be a valid machine XML settings file
|
---|
1688 | whose contents will be used to construct the machine object.
|
---|
1689 |
|
---|
1690 | <result name="VBOX_E_FILE_ERROR">
|
---|
1691 | Settings file name invalid, not found or sharing violation.
|
---|
1692 | </result>
|
---|
1693 | </desc>
|
---|
1694 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1695 | <desc>
|
---|
1696 | Name of the machine settings file.
|
---|
1697 | </desc>
|
---|
1698 | </param>
|
---|
1699 | <param name="machine" type="IMachine" dir="return">
|
---|
1700 | <desc>Opened machine object.</desc>
|
---|
1701 | </param>
|
---|
1702 | <note>
|
---|
1703 | <link to="IMachine::settingsModified"/> will return
|
---|
1704 | @c false for the created machine, until any of machine settings
|
---|
1705 | are changed.
|
---|
1706 | </note>
|
---|
1707 | </method>
|
---|
1708 |
|
---|
1709 | <method name="registerMachine">
|
---|
1710 | <desc>
|
---|
1711 |
|
---|
1712 | Registers the machine previously created using
|
---|
1713 | <link to="#createMachine"/> or opened using
|
---|
1714 | <link to="#openMachine"/> within this VirtualBox installation. After
|
---|
1715 | successful method invocation, the
|
---|
1716 | <link to="IMachineRegisteredEvent"/> event is fired.
|
---|
1717 |
|
---|
1718 | <note>
|
---|
1719 | This method implicitly calls <link to="IMachine::saveSettings"/>
|
---|
1720 | to save all current machine settings before registering it.
|
---|
1721 | </note>
|
---|
1722 |
|
---|
1723 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1724 | No matching virtual machine found.
|
---|
1725 | </result>
|
---|
1726 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1727 | Virtual machine was not created within this VirtualBox instance.
|
---|
1728 | </result>
|
---|
1729 |
|
---|
1730 | </desc>
|
---|
1731 | <param name="machine" type="IMachine" dir="in"/>
|
---|
1732 | </method>
|
---|
1733 |
|
---|
1734 | <method name="findMachine">
|
---|
1735 | <desc>
|
---|
1736 | Attempts to find a virtual machine given its name or UUID.
|
---|
1737 |
|
---|
1738 | <note>Inaccessible machines cannot be found by name, only by UUID, because their name
|
---|
1739 | cannot safely be determined.</note>
|
---|
1740 |
|
---|
1741 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1742 | Could not find registered machine matching @a nameOrId.
|
---|
1743 | </result>
|
---|
1744 |
|
---|
1745 | </desc>
|
---|
1746 | <param name="nameOrId" type="wstring" dir="in">
|
---|
1747 | <desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>
|
---|
1748 | </param>
|
---|
1749 | <param name="machine" type="IMachine" dir="return">
|
---|
1750 | <desc>Machine object, if found.</desc>
|
---|
1751 | </param>
|
---|
1752 | </method>
|
---|
1753 |
|
---|
1754 | <method name="createAppliance">
|
---|
1755 | <desc>
|
---|
1756 | Creates a new appliance object, which represents an appliance in the Open Virtual Machine
|
---|
1757 | Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
|
---|
1758 | machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
|
---|
1759 | </desc>
|
---|
1760 | <param name="appliance" type="IAppliance" dir="return">
|
---|
1761 | <desc>New appliance.</desc>
|
---|
1762 | </param>
|
---|
1763 | </method>
|
---|
1764 |
|
---|
1765 | <method name="createHardDisk">
|
---|
1766 | <desc>
|
---|
1767 | Creates a new base medium object that will use the given storage
|
---|
1768 | format and location for medium data.
|
---|
1769 |
|
---|
1770 | Note that the actual storage unit is not created by this method. In
|
---|
1771 | order to do it, and before you are able to attach the created medium
|
---|
1772 | to virtual machines, you must call one of the following methods to
|
---|
1773 | allocate a format-specific storage unit at the specified location:
|
---|
1774 | <ul>
|
---|
1775 | <li><link to="IMedium::createBaseStorage"/></li>
|
---|
1776 | <li><link to="IMedium::createDiffStorage"/></li>
|
---|
1777 | </ul>
|
---|
1778 |
|
---|
1779 | Some medium attributes, such as <link to="IMedium::id"/>, may
|
---|
1780 | remain uninitialized until the medium storage unit is successfully
|
---|
1781 | created by one of the above methods.
|
---|
1782 |
|
---|
1783 | After the storage unit is successfully created, it will be
|
---|
1784 | accessible through the <link to="#findMedium"/> method and can
|
---|
1785 | be found in the <link to="#hardDisks"/> array.
|
---|
1786 |
|
---|
1787 | The list of all storage formats supported by this VirtualBox
|
---|
1788 | installation can be obtained using
|
---|
1789 | <link to="ISystemProperties::mediumFormats"/>. If the @a format
|
---|
1790 | attribute is empty or @c null then the default storage format
|
---|
1791 | specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
|
---|
1792 | be used for creating a storage unit of the medium.
|
---|
1793 |
|
---|
1794 | Note that the format of the location string is storage format specific.
|
---|
1795 | See <link to="IMedium::location"/> and IMedium for more details.
|
---|
1796 |
|
---|
1797 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1798 | @a format identifier is invalid. See
|
---|
1799 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
1800 | </result>
|
---|
1801 | <result name="VBOX_E_FILE_ERROR">
|
---|
1802 | @a location is a not valid file name (for file-based formats only).
|
---|
1803 | </result>
|
---|
1804 | </desc>
|
---|
1805 | <param name="format" type="wstring" dir="in">
|
---|
1806 | <desc>
|
---|
1807 | Identifier of the storage format to use for the new medium.
|
---|
1808 | </desc>
|
---|
1809 | </param>
|
---|
1810 | <param name="location" type="wstring" dir="in">
|
---|
1811 | <desc>
|
---|
1812 | Location of the storage unit for the new medium.
|
---|
1813 | </desc>
|
---|
1814 | </param>
|
---|
1815 | <param name="medium" type="IMedium" dir="return">
|
---|
1816 | <desc>Created medium object.</desc>
|
---|
1817 | </param>
|
---|
1818 | </method>
|
---|
1819 |
|
---|
1820 | <method name="openMedium">
|
---|
1821 | <desc>
|
---|
1822 | Opens a medium from an existing storage location.
|
---|
1823 |
|
---|
1824 | Once a medium has been opened, it can be passed to other VirtualBox
|
---|
1825 | methods, in particular to <link to="IMachine::attachDevice" />.
|
---|
1826 |
|
---|
1827 | Depending on the given device type, the file at the storage location
|
---|
1828 | must be in one of the media formats understood by VirtualBox:
|
---|
1829 |
|
---|
1830 | <ul>
|
---|
1831 | <li>With a "HardDisk" device type, the file must be a hard disk image
|
---|
1832 | in one of the formats supported by VirtualBox (see
|
---|
1833 | <link to="ISystemProperties::mediumFormats" />).
|
---|
1834 | After this method succeeds, if the medium is a base medium, it
|
---|
1835 | will be added to the <link to="#hardDisks"/> array attribute. </li>
|
---|
1836 | <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
|
---|
1837 | After this method succeeds, the medium will be added to the
|
---|
1838 | <link to="#DVDImages"/> array attribute.</li>
|
---|
1839 | <li>With a "Floppy" device type, the file must be an RAW floppy image.
|
---|
1840 | After this method succeeds, the medium will be added to the
|
---|
1841 | <link to="#floppyImages"/> array attribute.</li>
|
---|
1842 | </ul>
|
---|
1843 |
|
---|
1844 | After having been opened, the medium can be found by the <link to="#findMedium"/>
|
---|
1845 | method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
|
---|
1846 |
|
---|
1847 | The UUID of the newly opened medium will either be retrieved from the
|
---|
1848 | storage location, if the format supports it (e.g. for hard disk images),
|
---|
1849 | or a new UUID will be randomly generated (e.g. for ISO and RAW files).
|
---|
1850 | If for some reason you need to change the medium's UUID, use
|
---|
1851 | <link to="IMedium::setIDs" />.
|
---|
1852 |
|
---|
1853 | If a differencing hard disk medium is to be opened by this method, the
|
---|
1854 | operation will succeed only if its parent medium and all ancestors,
|
---|
1855 | if any, are already known to this VirtualBox installation (for example,
|
---|
1856 | were opened by this method before).
|
---|
1857 |
|
---|
1858 | This method attempts to guess the storage format of the specified medium
|
---|
1859 | by reading medium data at the specified location.
|
---|
1860 |
|
---|
1861 | If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
|
---|
1862 | the image is opened for read/write access and must have according permissions,
|
---|
1863 | as VirtualBox may actually write status information into the disk's metadata
|
---|
1864 | sections.
|
---|
1865 |
|
---|
1866 | Note that write access is required for all typical hard disk usage in VirtualBox,
|
---|
1867 | since VirtualBox may need to write metadata such as a UUID into the image.
|
---|
1868 | The only exception is opening a source image temporarily for copying and
|
---|
1869 | cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
|
---|
1870 | again soon.
|
---|
1871 |
|
---|
1872 | The format of the location string is storage format specific. See
|
---|
1873 | <link to="IMedium::location"/> and IMedium for more details.
|
---|
1874 |
|
---|
1875 | <result name="VBOX_E_FILE_ERROR">
|
---|
1876 | Invalid medium storage file location or could not find the medium
|
---|
1877 | at the specified location.
|
---|
1878 | </result>
|
---|
1879 | <result name="VBOX_E_IPRT_ERROR">
|
---|
1880 | Could not get medium storage format.
|
---|
1881 | </result>
|
---|
1882 | <result name="E_INVALIDARG">
|
---|
1883 | Invalid medium storage format.
|
---|
1884 | </result>
|
---|
1885 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1886 | Medium has already been added to a media registry.
|
---|
1887 | </result>
|
---|
1888 | </desc>
|
---|
1889 | <param name="location" type="wstring" dir="in">
|
---|
1890 | <desc>
|
---|
1891 | Location of the storage unit that contains medium data in one of
|
---|
1892 | the supported storage formats.
|
---|
1893 | </desc>
|
---|
1894 | </param>
|
---|
1895 | <param name="deviceType" type="DeviceType" dir="in">
|
---|
1896 | <desc>
|
---|
1897 | Must be one of "HardDisk", "DVD" or "Floppy".
|
---|
1898 | </desc>
|
---|
1899 | </param>
|
---|
1900 | <param name="accessMode" type="AccessMode" dir="in">
|
---|
1901 | <desc>Whether to open the image in read/write or read-only mode. For
|
---|
1902 | a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
|
---|
1903 | </param>
|
---|
1904 | <param name="medium" type="IMedium" dir="return">
|
---|
1905 | <desc>Opened medium object.</desc>
|
---|
1906 | </param>
|
---|
1907 | </method>
|
---|
1908 |
|
---|
1909 | <method name="findMedium">
|
---|
1910 | <desc>
|
---|
1911 | Returns a medium of the given type that uses the given fully qualified
|
---|
1912 | location or UUID to store medium data.
|
---|
1913 |
|
---|
1914 | The given medium must be known to this VirtualBox installation, i.e.
|
---|
1915 | it must be previously created by <link to="#createHardDisk"/> or opened
|
---|
1916 | by <link to="#openMedium"/>.
|
---|
1917 |
|
---|
1918 | The search is done by comparing the value of the @a location argument to
|
---|
1919 | the <link to="IMedium::location"/> and <link to="IMedium::id" />
|
---|
1920 | attributes of each known medium.
|
---|
1921 |
|
---|
1922 | On case sensitive file systems, a case sensitive comparison is performed,
|
---|
1923 | otherwise the case of symbols in the file path is ignored.
|
---|
1924 |
|
---|
1925 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1926 | No medium object matching @a location found.
|
---|
1927 | </result>
|
---|
1928 | </desc>
|
---|
1929 | <param name="location" type="wstring" dir="in">
|
---|
1930 | <desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>
|
---|
1931 | </param>
|
---|
1932 | <param name="type" type="DeviceType" dir="in">
|
---|
1933 | <desc>Device type (must be HardDisk, DVD or Floppy)</desc>
|
---|
1934 | </param>
|
---|
1935 | <param name="medium" type="IMedium" dir="return">
|
---|
1936 | <desc>Medium object, if found.</desc>
|
---|
1937 | </param>
|
---|
1938 | </method>
|
---|
1939 |
|
---|
1940 | <method name="getGuestOSType">
|
---|
1941 | <desc>
|
---|
1942 | Returns an object describing the specified guest OS type.
|
---|
1943 |
|
---|
1944 | The requested guest OS type is specified using a string which is a
|
---|
1945 | mnemonic identifier of the guest operating system, such as
|
---|
1946 | <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
|
---|
1947 | particular virtual machine can be read or set using the
|
---|
1948 | <link to="IMachine::OSTypeId"/> attribute.
|
---|
1949 |
|
---|
1950 | The <link to="IVirtualBox::guestOSTypes"/> collection contains all
|
---|
1951 | available guest OS type objects. Each object has an
|
---|
1952 | <link to="IGuestOSType::id"/> attribute which contains an identifier of
|
---|
1953 | the guest OS this object describes.
|
---|
1954 |
|
---|
1955 | <result name="E_INVALIDARG">
|
---|
1956 | @a id is not a valid Guest OS type.
|
---|
1957 | </result>
|
---|
1958 |
|
---|
1959 | </desc>
|
---|
1960 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
1961 | <desc>Guest OS type ID string.</desc>
|
---|
1962 | </param>
|
---|
1963 | <param name="type" type="IGuestOSType" dir="return">
|
---|
1964 | <desc>Guest OS type object.</desc>
|
---|
1965 | </param>
|
---|
1966 | </method>
|
---|
1967 |
|
---|
1968 | <method name="createSharedFolder">
|
---|
1969 | <desc>
|
---|
1970 | Creates a new global shared folder by associating the given logical
|
---|
1971 | name with the given host path, adds it to the collection of shared
|
---|
1972 | folders and starts sharing it. Refer to the description of
|
---|
1973 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
1974 | <note>
|
---|
1975 | In the current implementation, this operation is not
|
---|
1976 | implemented.
|
---|
1977 | </note>
|
---|
1978 | </desc>
|
---|
1979 | <param name="name" type="wstring" dir="in">
|
---|
1980 | <desc>Unique logical name of the shared folder.</desc>
|
---|
1981 | </param>
|
---|
1982 | <param name="hostPath" type="wstring" dir="in">
|
---|
1983 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
1984 | </param>
|
---|
1985 | <param name="writable" type="boolean" dir="in">
|
---|
1986 | <desc>Whether the share is writable or readonly</desc>
|
---|
1987 | </param>
|
---|
1988 | <param name="automount" type="boolean" dir="in">
|
---|
1989 | <desc>Whether the share gets automatically mounted by the guest
|
---|
1990 | or not.</desc>
|
---|
1991 | </param>
|
---|
1992 | </method>
|
---|
1993 |
|
---|
1994 | <method name="removeSharedFolder">
|
---|
1995 | <desc>
|
---|
1996 | Removes the global shared folder with the given name previously
|
---|
1997 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
1998 | shared folders and stops sharing it.
|
---|
1999 | <note>
|
---|
2000 | In the current implementation, this operation is not
|
---|
2001 | implemented.
|
---|
2002 | </note>
|
---|
2003 | </desc>
|
---|
2004 | <param name="name" type="wstring" dir="in">
|
---|
2005 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
2006 | </param>
|
---|
2007 | </method>
|
---|
2008 |
|
---|
2009 | <method name="getExtraDataKeys">
|
---|
2010 | <desc>
|
---|
2011 | Returns an array representing the global extra data keys which currently
|
---|
2012 | have values defined.
|
---|
2013 | </desc>
|
---|
2014 | <param name="value" type="wstring" dir="return" safearray="yes">
|
---|
2015 | <desc>Array of extra data keys.</desc>
|
---|
2016 | </param>
|
---|
2017 | </method>
|
---|
2018 |
|
---|
2019 | <method name="getExtraData">
|
---|
2020 | <desc>
|
---|
2021 | Returns associated global extra data.
|
---|
2022 |
|
---|
2023 | If the requested data @a key does not exist, this function will
|
---|
2024 | succeed and return an empty string in the @a value argument.
|
---|
2025 |
|
---|
2026 | <result name="VBOX_E_FILE_ERROR">
|
---|
2027 | Settings file not accessible.
|
---|
2028 | </result>
|
---|
2029 | <result name="VBOX_E_XML_ERROR">
|
---|
2030 | Could not parse the settings file.
|
---|
2031 | </result>
|
---|
2032 |
|
---|
2033 | </desc>
|
---|
2034 | <param name="key" type="wstring" dir="in">
|
---|
2035 | <desc>Name of the data key to get.</desc>
|
---|
2036 | </param>
|
---|
2037 | <param name="value" type="wstring" dir="return">
|
---|
2038 | <desc>Value of the requested data key.</desc>
|
---|
2039 | </param>
|
---|
2040 | </method>
|
---|
2041 |
|
---|
2042 | <method name="setExtraData">
|
---|
2043 | <desc>
|
---|
2044 | Sets associated global extra data.
|
---|
2045 |
|
---|
2046 | If you pass @c null or empty string as a key @a value, the given @a key
|
---|
2047 | will be deleted.
|
---|
2048 |
|
---|
2049 | <note>
|
---|
2050 | Before performing the actual data change, this method will ask all
|
---|
2051 | registered event listener using the
|
---|
2052 | <link to="IExtraDataCanChangeEvent"/>
|
---|
2053 | notification for a permission. If one of the listeners refuses the
|
---|
2054 | new value, the change will not be performed.
|
---|
2055 | </note>
|
---|
2056 | <note>
|
---|
2057 | On success, the
|
---|
2058 | <link to="IExtraDataChangedEvent"/> notification
|
---|
2059 | is called to inform all registered listeners about a successful data
|
---|
2060 | change.
|
---|
2061 | </note>
|
---|
2062 |
|
---|
2063 | <result name="VBOX_E_FILE_ERROR">
|
---|
2064 | Settings file not accessible.
|
---|
2065 | </result>
|
---|
2066 | <result name="VBOX_E_XML_ERROR">
|
---|
2067 | Could not parse the settings file.
|
---|
2068 | </result>
|
---|
2069 | <result name="E_ACCESSDENIED">
|
---|
2070 | Modification request refused.
|
---|
2071 | </result>
|
---|
2072 |
|
---|
2073 | </desc>
|
---|
2074 | <param name="key" type="wstring" dir="in">
|
---|
2075 | <desc>Name of the data key to set.</desc>
|
---|
2076 | </param>
|
---|
2077 | <param name="value" type="wstring" dir="in">
|
---|
2078 | <desc>Value to assign to the key.</desc>
|
---|
2079 | </param>
|
---|
2080 | </method>
|
---|
2081 |
|
---|
2082 | <!--method name="createDHCPServerForInterface">
|
---|
2083 | <desc>
|
---|
2084 | Creates a dhcp server settings to be used for the given interface
|
---|
2085 | <result name="E_INVALIDARG">
|
---|
2086 | Host network interface @a name already exists.
|
---|
2087 | </result>
|
---|
2088 | </desc>
|
---|
2089 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2090 | <desc>Network Interface</desc>
|
---|
2091 | </param>
|
---|
2092 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2093 | <desc>Dhcp server settings</desc>
|
---|
2094 | </param>
|
---|
2095 | </method-->
|
---|
2096 |
|
---|
2097 | <method name="createDHCPServer">
|
---|
2098 | <desc>
|
---|
2099 | Creates a dhcp server settings to be used for the given internal network name
|
---|
2100 | <result name="E_INVALIDARG">
|
---|
2101 | Host network interface @a name already exists.
|
---|
2102 | </result>
|
---|
2103 | </desc>
|
---|
2104 | <param name="name" type="wstring" dir="in">
|
---|
2105 | <desc>server name</desc>
|
---|
2106 | </param>
|
---|
2107 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2108 | <desc>Dhcp server settings</desc>
|
---|
2109 | </param>
|
---|
2110 | </method>
|
---|
2111 |
|
---|
2112 | <method name="findDHCPServerByNetworkName">
|
---|
2113 | <desc>
|
---|
2114 | Searches a dhcp server settings to be used for the given internal network name
|
---|
2115 | <result name="E_INVALIDARG">
|
---|
2116 | Host network interface @a name already exists.
|
---|
2117 | </result>
|
---|
2118 |
|
---|
2119 | </desc>
|
---|
2120 | <param name="name" type="wstring" dir="in">
|
---|
2121 | <desc>server name</desc>
|
---|
2122 | </param>
|
---|
2123 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2124 | <desc>Dhcp server settings</desc>
|
---|
2125 | </param>
|
---|
2126 | </method>
|
---|
2127 |
|
---|
2128 | <!--method name="findDHCPServerForInterface">
|
---|
2129 | <desc>
|
---|
2130 | Searches a dhcp server settings to be used for the given interface
|
---|
2131 | <result name="E_INVALIDARG">
|
---|
2132 | Host network interface @a name already exists.
|
---|
2133 | </result>
|
---|
2134 | </desc>
|
---|
2135 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2136 | <desc>Network Interface</desc>
|
---|
2137 | </param>
|
---|
2138 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2139 | <desc>Dhcp server settings</desc>
|
---|
2140 | </param>
|
---|
2141 | </method-->
|
---|
2142 |
|
---|
2143 | <method name="removeDHCPServer">
|
---|
2144 | <desc>
|
---|
2145 | Removes the dhcp server settings
|
---|
2146 | <result name="E_INVALIDARG">
|
---|
2147 | Host network interface @a name already exists.
|
---|
2148 | </result>
|
---|
2149 | </desc>
|
---|
2150 | <param name="server" type="IDHCPServer" dir="in">
|
---|
2151 | <desc>Dhcp server settings to be removed</desc>
|
---|
2152 | </param>
|
---|
2153 | </method>
|
---|
2154 |
|
---|
2155 |
|
---|
2156 | <method name="checkFirmwarePresent">
|
---|
2157 | <desc>
|
---|
2158 | Check if this VirtualBox installation has a firmware
|
---|
2159 | of the given type available, either system-wide or per-user.
|
---|
2160 | Optionally, this may return a hint where this firmware can be
|
---|
2161 | downloaded from.
|
---|
2162 | </desc>
|
---|
2163 | <param name="firmwareType" type="FirmwareType" dir="in">
|
---|
2164 | <desc>
|
---|
2165 | Type of firmware to check.
|
---|
2166 | </desc>
|
---|
2167 | </param>
|
---|
2168 | <param name="version" type="wstring" dir="in">
|
---|
2169 | <desc>Expected version number, usually empty string (presently ignored).</desc>
|
---|
2170 | </param>
|
---|
2171 |
|
---|
2172 | <param name="url" type="wstring" dir="out">
|
---|
2173 | <desc>
|
---|
2174 | Suggested URL to download this firmware from.
|
---|
2175 | </desc>
|
---|
2176 | </param>
|
---|
2177 |
|
---|
2178 | <param name="file" type="wstring" dir="out">
|
---|
2179 | <desc>
|
---|
2180 | Filename of firmware, only valid if result == TRUE.
|
---|
2181 | </desc>
|
---|
2182 | </param>
|
---|
2183 |
|
---|
2184 | <param name="result" type="boolean" dir="return">
|
---|
2185 | <desc>If firmware of this type and version is available.</desc>
|
---|
2186 | </param>
|
---|
2187 | </method>
|
---|
2188 |
|
---|
2189 | </interface>
|
---|
2190 |
|
---|
2191 | <!--
|
---|
2192 | // IVFSExplorer
|
---|
2193 | /////////////////////////////////////////////////////////////////////////
|
---|
2194 | -->
|
---|
2195 |
|
---|
2196 | <enum
|
---|
2197 | name="VFSType"
|
---|
2198 | uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
|
---|
2199 | >
|
---|
2200 | <desc>
|
---|
2201 | Virtual file systems supported by VFSExplorer.
|
---|
2202 | </desc>
|
---|
2203 |
|
---|
2204 | <const name="File" value="1" />
|
---|
2205 | <const name="Cloud" value="2" />
|
---|
2206 | <const name="S3" value="3" />
|
---|
2207 | <const name="WebDav" value="4" />
|
---|
2208 | </enum>
|
---|
2209 |
|
---|
2210 | <enum
|
---|
2211 | name="VFSFileType"
|
---|
2212 | uuid="714333cd-44e2-415f-a245-d378fa9b1242"
|
---|
2213 | >
|
---|
2214 | <desc>
|
---|
2215 | File types known by VFSExplorer.
|
---|
2216 | </desc>
|
---|
2217 |
|
---|
2218 | <const name="Unknown" value="1" />
|
---|
2219 | <const name="Fifo" value="2" />
|
---|
2220 | <const name="DevChar" value="3" />
|
---|
2221 | <const name="Directory" value="4" />
|
---|
2222 | <const name="DevBlock" value="5" />
|
---|
2223 | <const name="File" value="6" />
|
---|
2224 | <const name="SymLink" value="7" />
|
---|
2225 | <const name="Socket" value="8" />
|
---|
2226 | <const name="WhiteOut" value="9" />
|
---|
2227 | </enum>
|
---|
2228 |
|
---|
2229 | <interface
|
---|
2230 | name="IVFSExplorer" extends="$unknown"
|
---|
2231 | uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"
|
---|
2232 | wsmap="managed"
|
---|
2233 | >
|
---|
2234 | <desc>
|
---|
2235 | The VFSExplorer interface unifies access to different file system
|
---|
2236 | types. This includes local file systems as well remote file systems like
|
---|
2237 | S3. For a list of supported types see <link to="VFSType" />.
|
---|
2238 | An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
|
---|
2239 | </desc>
|
---|
2240 |
|
---|
2241 | <attribute name="path" type="wstring" readonly="yes">
|
---|
2242 | <desc>Returns the current path in the virtual file system.</desc>
|
---|
2243 | </attribute>
|
---|
2244 |
|
---|
2245 | <attribute name="type" type="VFSType" readonly="yes">
|
---|
2246 | <desc>Returns the file system type which is currently in use.</desc>
|
---|
2247 | </attribute>
|
---|
2248 |
|
---|
2249 | <method name="update">
|
---|
2250 | <desc>Updates the internal list of files/directories from the
|
---|
2251 | current directory level. Use <link to="#entryList" /> to get the full list
|
---|
2252 | after a call to this method.</desc>
|
---|
2253 |
|
---|
2254 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2255 | <desc>Progress object to track the operation completion.</desc>
|
---|
2256 | </param>
|
---|
2257 | </method>
|
---|
2258 |
|
---|
2259 | <method name="cd">
|
---|
2260 | <desc>Change the current directory level.</desc>
|
---|
2261 |
|
---|
2262 | <param name="aDir" type="wstring" dir="in">
|
---|
2263 | <desc>The name of the directory to go in.</desc>
|
---|
2264 | </param>
|
---|
2265 |
|
---|
2266 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2267 | <desc>Progress object to track the operation completion.</desc>
|
---|
2268 | </param>
|
---|
2269 | </method>
|
---|
2270 |
|
---|
2271 | <method name="cdUp">
|
---|
2272 | <desc>Go one directory upwards from the current directory level.</desc>
|
---|
2273 |
|
---|
2274 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2275 | <desc>Progress object to track the operation completion.</desc>
|
---|
2276 | </param>
|
---|
2277 | </method>
|
---|
2278 |
|
---|
2279 | <method name="entryList">
|
---|
2280 | <desc>Returns a list of files/directories after a call to <link
|
---|
2281 | to="#update" />. The user is responsible for keeping this internal
|
---|
2282 | list up do date.</desc>
|
---|
2283 |
|
---|
2284 | <param name="aNames" type="wstring" safearray="yes" dir="out">
|
---|
2285 | <desc>The list of names for the entries.</desc>
|
---|
2286 | </param>
|
---|
2287 |
|
---|
2288 | <param name="aTypes" type="unsigned long" safearray="yes" dir="out">
|
---|
2289 | <desc>The list of types for the entries.</desc>
|
---|
2290 | </param>
|
---|
2291 |
|
---|
2292 | <param name="aSizes" type="unsigned long" safearray="yes" dir="out">
|
---|
2293 | <desc>The list of sizes (in bytes) for the entries.</desc>
|
---|
2294 | </param>
|
---|
2295 |
|
---|
2296 | <param name="aModes" type="unsigned long" safearray="yes" dir="out">
|
---|
2297 | <desc>The list of file modes (in octal form) for the entries.</desc>
|
---|
2298 | </param>
|
---|
2299 | </method>
|
---|
2300 |
|
---|
2301 | <method name="exists">
|
---|
2302 | <desc>Checks if the given file list exists in the current directory
|
---|
2303 | level.</desc>
|
---|
2304 |
|
---|
2305 | <param name="aNames" type="wstring" safearray="yes" dir="in">
|
---|
2306 | <desc>The names to check.</desc>
|
---|
2307 | </param>
|
---|
2308 |
|
---|
2309 | <param name="aExists" type="wstring" safearray="yes" dir="return">
|
---|
2310 | <desc>The names which exist.</desc>
|
---|
2311 | </param>
|
---|
2312 | </method>
|
---|
2313 |
|
---|
2314 | <method name="remove">
|
---|
2315 | <desc>Deletes the given files in the current directory level.</desc>
|
---|
2316 |
|
---|
2317 | <param name="aNames" type="wstring" safearray="yes" dir="in">
|
---|
2318 | <desc>The names to remove.</desc>
|
---|
2319 | </param>
|
---|
2320 |
|
---|
2321 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2322 | <desc>Progress object to track the operation completion.</desc>
|
---|
2323 | </param>
|
---|
2324 | </method>
|
---|
2325 |
|
---|
2326 | </interface>
|
---|
2327 |
|
---|
2328 | <!--
|
---|
2329 | // IAppliance
|
---|
2330 | /////////////////////////////////////////////////////////////////////////
|
---|
2331 | -->
|
---|
2332 |
|
---|
2333 | <interface
|
---|
2334 | name="IAppliance" extends="$unknown"
|
---|
2335 | uuid="7b148032-4124-4f46-b56a-b48ac1273f5a"
|
---|
2336 | wsmap="managed"
|
---|
2337 | >
|
---|
2338 | <desc>
|
---|
2339 | Represents a platform-independent appliance in OVF format. An instance of this is returned
|
---|
2340 | by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
|
---|
2341 | virtual machines within an appliance with VirtualBox.
|
---|
2342 |
|
---|
2343 | The OVF standard suggests two different physical file formats:
|
---|
2344 |
|
---|
2345 | <ol>
|
---|
2346 | <li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
|
---|
2347 | file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
|
---|
2348 | this descriptor file references other files such as disk images, as OVF appliances typically
|
---|
2349 | do, those additional files must be in the same directory as the descriptor file.</li>
|
---|
2350 |
|
---|
2351 | <li>If the appliance is distributed as a single file, it must be in TAR format and have the
|
---|
2352 | <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
|
---|
2353 | files and optionally other files.
|
---|
2354 |
|
---|
2355 | At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
|
---|
2356 | be added with a later version.</li>
|
---|
2357 | </ol>
|
---|
2358 |
|
---|
2359 | <b>Importing</b> an OVF appliance into VirtualBox as instances of
|
---|
2360 | <link to="IMachine" /> involves the following sequence of API calls:
|
---|
2361 |
|
---|
2362 | <ol>
|
---|
2363 | <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
|
---|
2364 | </li>
|
---|
2365 |
|
---|
2366 | <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
|
---|
2367 | would like to import. So long as this file is syntactically valid, this will succeed
|
---|
2368 | and fill the appliance object with the parsed data from the OVF file.
|
---|
2369 | </li>
|
---|
2370 |
|
---|
2371 | <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
|
---|
2372 | contents of the IAppliance attributes accordingly. These can be inspected by a
|
---|
2373 | VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
|
---|
2374 | user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
|
---|
2375 | instances of <link to="IVirtualSystemDescription" /> which represent the virtual
|
---|
2376 | systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
|
---|
2377 | by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
|
---|
2378 | The GUI can then give the user the option to confirm and/or change these suggestions.
|
---|
2379 | </li>
|
---|
2380 |
|
---|
2381 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
2382 | virtual system (machine) to override the suggestions made by the interpret() routine.
|
---|
2383 | </li>
|
---|
2384 |
|
---|
2385 | <li>Finally, call <link to="#importMachines" /> to create virtual machines in
|
---|
2386 | VirtualBox as instances of <link to="IMachine" /> that match the information in the
|
---|
2387 | virtual system descriptions. After this call succeeded, the UUIDs of the machines created
|
---|
2388 | can be found in the <link to="#machines" /> array attribute.
|
---|
2389 | </li>
|
---|
2390 | </ol>
|
---|
2391 |
|
---|
2392 | <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
|
---|
2393 |
|
---|
2394 | <ol>
|
---|
2395 | <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
|
---|
2396 | an empty IAppliance object.
|
---|
2397 | </li>
|
---|
2398 |
|
---|
2399 | <li>For each machine you would like to export, call <link to="IMachine::export" />
|
---|
2400 | with the IAppliance object you just created. Each such call creates one instance of
|
---|
2401 | <link to="IVirtualSystemDescription" /> inside the appliance.
|
---|
2402 | </li>
|
---|
2403 |
|
---|
2404 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
2405 | virtual system (machine) to override the suggestions made by the export() routine.
|
---|
2406 | </li>
|
---|
2407 |
|
---|
2408 | <li>Finally, call <link to="#write" /> with a path specification to have the OVF
|
---|
2409 | file written.</li>
|
---|
2410 | </ol>
|
---|
2411 |
|
---|
2412 | </desc>
|
---|
2413 |
|
---|
2414 | <attribute name="path" type="wstring" readonly="yes">
|
---|
2415 | <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
|
---|
2416 | the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
|
---|
2417 | <link to="#write" /> (for export).
|
---|
2418 | This attribute is empty until one of these methods has been called.
|
---|
2419 | </desc>
|
---|
2420 | </attribute>
|
---|
2421 |
|
---|
2422 | <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
|
---|
2423 | <desc>
|
---|
2424 | Array of virtual disk definitions. One such description exists for each
|
---|
2425 | disk definition in the OVF; each string array item represents one such piece of
|
---|
2426 | disk information, with the information fields separated by tab (\\t) characters.
|
---|
2427 |
|
---|
2428 | The caller should be prepared for additional fields being appended to
|
---|
2429 | this string in future versions of VirtualBox and therefore check for
|
---|
2430 | the number of tabs in the strings returned.
|
---|
2431 |
|
---|
2432 | In the current version, the following eight fields are returned per string
|
---|
2433 | in the array:
|
---|
2434 |
|
---|
2435 | <ol>
|
---|
2436 | <li>Disk ID (unique string identifier given to disk)</li>
|
---|
2437 |
|
---|
2438 | <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
|
---|
2439 |
|
---|
2440 | <li>Populated size (optional unsigned integer indicating the current size of the
|
---|
2441 | disk; can be approximate; -1 if unspecified)</li>
|
---|
2442 |
|
---|
2443 | <li>Format (string identifying the disk format, typically
|
---|
2444 | "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
|
---|
2445 |
|
---|
2446 | <li>Reference (where to find the disk image, typically a file name; if empty,
|
---|
2447 | then the disk should be created on import)</li>
|
---|
2448 |
|
---|
2449 | <li>Image size (optional unsigned integer indicating the size of the image,
|
---|
2450 | which need not necessarily be the same as the values specified above, since
|
---|
2451 | the image may be compressed or sparse; -1 if not specified)</li>
|
---|
2452 |
|
---|
2453 | <li>Chunk size (optional unsigned integer if the image is split into chunks;
|
---|
2454 | presently unsupported and always -1)</li>
|
---|
2455 |
|
---|
2456 | <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
|
---|
2457 | </ol>
|
---|
2458 | </desc>
|
---|
2459 | </attribute>
|
---|
2460 |
|
---|
2461 | <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
|
---|
2462 | <desc> Array of virtual system descriptions. One such description is created
|
---|
2463 | for each virtual system (machine) found in the OVF.
|
---|
2464 | This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
|
---|
2465 | (for export) has been called.
|
---|
2466 | </desc>
|
---|
2467 | </attribute>
|
---|
2468 |
|
---|
2469 | <attribute name="machines" type="wstring" readonly="yes" safearray="yes">
|
---|
2470 | <desc>
|
---|
2471 | Contains the UUIDs of the machines created from the information in this appliances. This is only
|
---|
2472 | relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
|
---|
2473 | succeeded.
|
---|
2474 | </desc>
|
---|
2475 | </attribute>
|
---|
2476 |
|
---|
2477 | <method name="read">
|
---|
2478 | <desc>
|
---|
2479 | Reads an OVF file into the appliance object.
|
---|
2480 |
|
---|
2481 | This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
|
---|
2482 | mere fact that this method returns successfully does not mean that VirtualBox supports all
|
---|
2483 | features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
|
---|
2484 | </desc>
|
---|
2485 | <param name="file" type="wstring" dir="in">
|
---|
2486 | <desc>
|
---|
2487 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
2488 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
2489 | </desc>
|
---|
2490 | </param>
|
---|
2491 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2492 | <desc>Progress object to track the operation completion.</desc>
|
---|
2493 | </param>
|
---|
2494 | </method>
|
---|
2495 |
|
---|
2496 | <method name="interpret">
|
---|
2497 | <desc>
|
---|
2498 | Interprets the OVF data that was read when the appliance was constructed. After
|
---|
2499 | calling this method, one can inspect the
|
---|
2500 | <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
|
---|
2501 | one <link to="IVirtualSystemDescription" /> for each virtual machine found in
|
---|
2502 | the appliance.
|
---|
2503 |
|
---|
2504 | Calling this method is the second step of importing an appliance into VirtualBox;
|
---|
2505 | see <link to="IAppliance" /> for an overview.
|
---|
2506 |
|
---|
2507 | After calling this method, one should call <link to="#getWarnings" /> to find out
|
---|
2508 | if problems were encountered during the processing which might later lead to
|
---|
2509 | errors.
|
---|
2510 | </desc>
|
---|
2511 | </method>
|
---|
2512 |
|
---|
2513 | <method name="importMachines">
|
---|
2514 | <desc>
|
---|
2515 | Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
|
---|
2516 | and other interfaces that match the information contained in the appliance as
|
---|
2517 | closely as possible, as represented by the import instructions in the
|
---|
2518 | <link to="#virtualSystemDescriptions" /> array.
|
---|
2519 |
|
---|
2520 | Calling this method is the final step of importing an appliance into VirtualBox;
|
---|
2521 | see <link to="IAppliance" /> for an overview.
|
---|
2522 |
|
---|
2523 | Since importing the appliance will most probably involve copying and converting
|
---|
2524 | disk images, which can take a long time, this method operates asynchronously and
|
---|
2525 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
2526 |
|
---|
2527 | After the import succeeded, the UUIDs of the IMachine instances created can be
|
---|
2528 | retrieved from the <link to="#machines" /> array attribute.
|
---|
2529 | </desc>
|
---|
2530 |
|
---|
2531 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2532 | <desc>Progress object to track the operation completion.</desc>
|
---|
2533 | </param>
|
---|
2534 | </method>
|
---|
2535 |
|
---|
2536 | <method name="createVFSExplorer">
|
---|
2537 | <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
|
---|
2538 |
|
---|
2539 | <param name="aUri" type="wstring" dir="in">
|
---|
2540 | <desc>The URI describing the file system to use.</desc>
|
---|
2541 | </param>
|
---|
2542 |
|
---|
2543 | <param name="aExplorer" type="IVFSExplorer" dir="return">
|
---|
2544 | <desc></desc>
|
---|
2545 | </param>
|
---|
2546 | </method>
|
---|
2547 |
|
---|
2548 | <method name="write">
|
---|
2549 | <desc>
|
---|
2550 | Writes the contents of the appliance exports into a new OVF file.
|
---|
2551 |
|
---|
2552 | Calling this method is the final step of exporting an appliance from VirtualBox;
|
---|
2553 | see <link to="IAppliance" /> for an overview.
|
---|
2554 |
|
---|
2555 | Since exporting the appliance will most probably involve copying and converting
|
---|
2556 | disk images, which can take a long time, this method operates asynchronously and
|
---|
2557 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
2558 | </desc>
|
---|
2559 | <param name="format" type="wstring" dir="in">
|
---|
2560 | <desc>
|
---|
2561 | Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
|
---|
2562 | future versions of VirtualBox may support additional formats.
|
---|
2563 | </desc>
|
---|
2564 | </param>
|
---|
2565 | <param name="manifest" type="boolean" dir="in">
|
---|
2566 | <desc>
|
---|
2567 | Indicate if the optional manifest file (.mf) should be written. The manifest file
|
---|
2568 | is used for integrity checks prior import.
|
---|
2569 | </desc>
|
---|
2570 | </param>
|
---|
2571 | <param name="path" type="wstring" dir="in">
|
---|
2572 | <desc>
|
---|
2573 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
2574 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
2575 | </desc>
|
---|
2576 | </param>
|
---|
2577 | <param name="progress" type="IProgress" dir="return">
|
---|
2578 | <desc>Progress object to track the operation completion.</desc>
|
---|
2579 | </param>
|
---|
2580 | </method>
|
---|
2581 |
|
---|
2582 | <method name="getWarnings">
|
---|
2583 | <desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>
|
---|
2584 |
|
---|
2585 | <param name="aWarnings" type="wstring" dir="return" safearray="yes">
|
---|
2586 | <desc></desc>
|
---|
2587 | </param>
|
---|
2588 | </method>
|
---|
2589 |
|
---|
2590 | </interface>
|
---|
2591 |
|
---|
2592 | <enum
|
---|
2593 | name="VirtualSystemDescriptionType"
|
---|
2594 | uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"
|
---|
2595 | >
|
---|
2596 | <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
|
---|
2597 | a configuration value.</desc>
|
---|
2598 |
|
---|
2599 | <const name="Ignore" value="1" />
|
---|
2600 | <const name="OS" value="2" />
|
---|
2601 | <const name="Name" value="3" />
|
---|
2602 | <const name="Product" value="4" />
|
---|
2603 | <const name="Vendor" value="5" />
|
---|
2604 | <const name="Version" value="6" />
|
---|
2605 | <const name="ProductUrl" value="7" />
|
---|
2606 | <const name="VendorUrl" value="8" />
|
---|
2607 | <const name="Description" value="9" />
|
---|
2608 | <const name="License" value="10" />
|
---|
2609 | <const name="Miscellaneous" value="11" />
|
---|
2610 | <const name="CPU" value="12" />
|
---|
2611 | <const name="Memory" value="13" />
|
---|
2612 | <const name="HardDiskControllerIDE" value="14" />
|
---|
2613 | <const name="HardDiskControllerSATA" value="15" />
|
---|
2614 | <const name="HardDiskControllerSCSI" value="16" />
|
---|
2615 | <const name="HardDiskControllerSAS" value="17" />
|
---|
2616 | <const name="HardDiskImage" value="18" />
|
---|
2617 | <const name="Floppy" value="19" />
|
---|
2618 | <const name="CDROM" value="20" />
|
---|
2619 | <const name="NetworkAdapter" value="21" />
|
---|
2620 | <const name="USBController" value="22" />
|
---|
2621 | <const name="SoundCard" value="23" />
|
---|
2622 |
|
---|
2623 | </enum>
|
---|
2624 |
|
---|
2625 | <enum
|
---|
2626 | name="VirtualSystemDescriptionValueType"
|
---|
2627 | uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
|
---|
2628 | >
|
---|
2629 | <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
|
---|
2630 | type to fetch.</desc>
|
---|
2631 |
|
---|
2632 | <const name="Reference" value="1" />
|
---|
2633 | <const name="Original" value="2" />
|
---|
2634 | <const name="Auto" value="3" />
|
---|
2635 | <const name="ExtraConfig" value="4" />
|
---|
2636 |
|
---|
2637 | </enum>
|
---|
2638 |
|
---|
2639 | <interface
|
---|
2640 | name="IVirtualSystemDescription" extends="$unknown"
|
---|
2641 | uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
|
---|
2642 | wsmap="managed"
|
---|
2643 | >
|
---|
2644 |
|
---|
2645 | <desc>Represents one virtual system (machine) in an appliance. This interface is used in
|
---|
2646 | the <link to="IAppliance::virtualSystemDescriptions" /> array. After
|
---|
2647 | <link to="IAppliance::interpret" /> has been called, that array contains information
|
---|
2648 | about how the virtual systems described in the OVF should best be imported into
|
---|
2649 | VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
|
---|
2650 | import an OVF into VirtualBox.
|
---|
2651 | </desc>
|
---|
2652 |
|
---|
2653 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
2654 | <desc>Return the number of virtual system description entries.</desc>
|
---|
2655 | </attribute>
|
---|
2656 |
|
---|
2657 | <method name="getDescription">
|
---|
2658 | <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
|
---|
2659 | items with the same indices correspond and jointly represent an import instruction for VirtualBox.
|
---|
2660 |
|
---|
2661 | The list below identifies the value sets that are possible depending on the
|
---|
2662 | <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
|
---|
2663 | the array item with the same index in @a aOvfValues[] will contain the original value as contained
|
---|
2664 | in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
|
---|
2665 | will contain a suggested value to be used for VirtualBox. Depending on the description type,
|
---|
2666 | the @a aExtraConfigValues[] array item may also be used.
|
---|
2667 |
|
---|
2668 | <ul>
|
---|
2669 | <li>
|
---|
2670 | "OS": the guest operating system type. There must be exactly one such array item on import. The
|
---|
2671 | corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
|
---|
2672 | This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
|
---|
2673 | item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
|
---|
2674 | </li>
|
---|
2675 | <li>
|
---|
2676 | "Name": the name to give to the new virtual machine. There can be at most one such array item;
|
---|
2677 | if none is present on import, then an automatic name will be created from the operating system
|
---|
2678 | type. The corresponding item im @a aOvfValues[] will contain the suggested virtual machine name
|
---|
2679 | from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
|
---|
2680 | <link to="IMachine" /> name that does not exist yet.
|
---|
2681 | </li>
|
---|
2682 | <li>
|
---|
2683 | "Description": an arbitrary description.
|
---|
2684 | </li>
|
---|
2685 | <li>
|
---|
2686 | "License": the EULA section from the OVF, if present. It is the responsibility of the calling
|
---|
2687 | code to display such a license for agreement; the Main API does not enforce any such policy.
|
---|
2688 | </li>
|
---|
2689 | <li>
|
---|
2690 | Miscellaneous: reserved for future use.
|
---|
2691 | </li>
|
---|
2692 | <li>
|
---|
2693 | "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
|
---|
2694 | </li>
|
---|
2695 | <li>
|
---|
2696 | "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
|
---|
2697 | is present on import, then VirtualBox will set a meaningful default based on the operating system
|
---|
2698 | type.
|
---|
2699 | </li>
|
---|
2700 | <li>
|
---|
2701 | "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
|
---|
2702 | An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
|
---|
2703 | the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
|
---|
2704 | writes into the OVF.
|
---|
2705 | The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
|
---|
2706 | type can use to specify which hard disk controller a virtual disk should be connected to.
|
---|
2707 | Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
|
---|
2708 | in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
|
---|
2709 | its virtual machines supports four channels (primary master, primary slave, secondary master,
|
---|
2710 | secondary slave) and thus maps to two IDE controllers in the OVF sense.
|
---|
2711 | </li>
|
---|
2712 | <li>
|
---|
2713 | "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
|
---|
2714 | has no value in @a aOvfValues[] or @a aVBoxValues[].
|
---|
2715 | The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
|
---|
2716 | </li>
|
---|
2717 | <li>
|
---|
2718 | "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
|
---|
2719 | The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
|
---|
2720 | "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
|
---|
2721 | whereas VirtualBox considers it a class of storage controllers of its own; see
|
---|
2722 | <link to="StorageControllerType" />).
|
---|
2723 | The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
|
---|
2724 | </li>
|
---|
2725 | <li>
|
---|
2726 | "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
|
---|
2727 | arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
|
---|
2728 |
|
---|
2729 | The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
|
---|
2730 | a path since the image file should be in the same location as the OVF file itself), whereas the
|
---|
2731 | item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
|
---|
2732 | hard disk image. This means that on import the image will be copied and converted from the
|
---|
2733 | "ovf" location to the "vbox" location; on export, this will be handled the other way round.
|
---|
2734 |
|
---|
2735 | The matching item in the @a aExtraConfigValues[] array must contain a string of the following
|
---|
2736 | format: "controller=<index>;channel=<c>"
|
---|
2737 | In this string, <index> must be an integer specifying the hard disk controller to connect
|
---|
2738 | the image to. That number must be the index of an array item with one of the hard disk controller
|
---|
2739 | types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
|
---|
2740 | In addition, <c> must specify the channel to use on that controller. For IDE controllers,
|
---|
2741 | this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
|
---|
2742 | before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
|
---|
2743 | no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
|
---|
2744 | </li>
|
---|
2745 | <li>
|
---|
2746 | "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
|
---|
2747 | attachment information as with "HardDiskImage" items.
|
---|
2748 | </li>
|
---|
2749 | <li>
|
---|
2750 | "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
|
---|
2751 | attachment information as with "HardDiskImage" items.
|
---|
2752 | </li>
|
---|
2753 | <li>
|
---|
2754 | "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
|
---|
2755 | for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
|
---|
2756 | of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
|
---|
2757 | </li>
|
---|
2758 | <li>
|
---|
2759 | "USBController": a USB controller. There can be at most one such item. If and only if such an
|
---|
2760 | item ispresent, USB support will be enabled for the new virtual machine.
|
---|
2761 | </li>
|
---|
2762 | <li>
|
---|
2763 | "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
|
---|
2764 | present, sound support will be enabled for the new virtual machine. Note that the virtual
|
---|
2765 | machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
|
---|
2766 | may be different from the virtual soundcard expected by the appliance.
|
---|
2767 | </li>
|
---|
2768 | </ul>
|
---|
2769 |
|
---|
2770 | </desc>
|
---|
2771 |
|
---|
2772 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
2773 | <desc></desc>
|
---|
2774 | </param>
|
---|
2775 |
|
---|
2776 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
2777 | <desc></desc>
|
---|
2778 | </param>
|
---|
2779 |
|
---|
2780 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
2781 | <desc></desc>
|
---|
2782 | </param>
|
---|
2783 |
|
---|
2784 | <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
|
---|
2785 | <desc></desc>
|
---|
2786 | </param>
|
---|
2787 |
|
---|
2788 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
2789 | <desc></desc>
|
---|
2790 | </param>
|
---|
2791 |
|
---|
2792 | </method>
|
---|
2793 |
|
---|
2794 | <method name="getDescriptionByType">
|
---|
2795 | <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
|
---|
2796 | should be returned.</desc>
|
---|
2797 |
|
---|
2798 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2799 | <desc></desc>
|
---|
2800 | </param>
|
---|
2801 |
|
---|
2802 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
2803 | <desc></desc>
|
---|
2804 | </param>
|
---|
2805 |
|
---|
2806 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
2807 | <desc></desc>
|
---|
2808 | </param>
|
---|
2809 |
|
---|
2810 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
2811 | <desc></desc>
|
---|
2812 | </param>
|
---|
2813 |
|
---|
2814 | <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
|
---|
2815 | <desc></desc>
|
---|
2816 | </param>
|
---|
2817 |
|
---|
2818 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
2819 | <desc></desc>
|
---|
2820 | </param>
|
---|
2821 |
|
---|
2822 | </method>
|
---|
2823 |
|
---|
2824 | <method name="getValuesByType">
|
---|
2825 | <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
|
---|
2826 | value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
|
---|
2827 | values.</desc>
|
---|
2828 |
|
---|
2829 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2830 | <desc></desc>
|
---|
2831 | </param>
|
---|
2832 |
|
---|
2833 | <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
|
---|
2834 | <desc></desc>
|
---|
2835 | </param>
|
---|
2836 |
|
---|
2837 | <param name="aValues" type="wstring" dir="return" safearray="yes">
|
---|
2838 | <desc></desc>
|
---|
2839 | </param>
|
---|
2840 |
|
---|
2841 | </method>
|
---|
2842 |
|
---|
2843 | <method name="setFinalValues">
|
---|
2844 | <desc>
|
---|
2845 | This method allows the appliance's user to change the configuration for the virtual
|
---|
2846 | system descriptions. For each array item returned from <link to="#getDescription" />,
|
---|
2847 | you must pass in one boolean value and one configuration value.
|
---|
2848 |
|
---|
2849 | Each item in the boolean array determines whether the particular configuration item
|
---|
2850 | should be enabled.
|
---|
2851 | You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
|
---|
2852 | HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
|
---|
2853 | and SoundCard.
|
---|
2854 |
|
---|
2855 | For the "vbox" and "extra configuration" values, if you pass in the same arrays
|
---|
2856 | as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
|
---|
2857 | the configuration remains unchanged. Please see the documentation for getDescription()
|
---|
2858 | for valid configuration values for the individual array item types. If the
|
---|
2859 | corresponding item in the aEnabled array is @c false, the configuration value is ignored.
|
---|
2860 | </desc>
|
---|
2861 |
|
---|
2862 | <param name="aEnabled" type="boolean" dir="in" safearray="yes">
|
---|
2863 | <desc></desc>
|
---|
2864 | </param>
|
---|
2865 |
|
---|
2866 | <param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
|
---|
2867 | <desc></desc>
|
---|
2868 | </param>
|
---|
2869 |
|
---|
2870 | <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
|
---|
2871 | <desc></desc>
|
---|
2872 | </param>
|
---|
2873 | </method>
|
---|
2874 |
|
---|
2875 | <method name="addDescription">
|
---|
2876 | <desc>
|
---|
2877 | This method adds an additional description entry to the stack of already
|
---|
2878 | available descriptions for this virtual system. This is handy for writing
|
---|
2879 | values which aren't directly supported by VirtualBox. One example would
|
---|
2880 | be the License type of <link to="VirtualSystemDescriptionType" />.
|
---|
2881 | </desc>
|
---|
2882 |
|
---|
2883 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2884 | <desc></desc>
|
---|
2885 | </param>
|
---|
2886 |
|
---|
2887 | <param name="aVBoxValue" type="wstring" dir="in">
|
---|
2888 | <desc></desc>
|
---|
2889 | </param>
|
---|
2890 |
|
---|
2891 | <param name="aExtraConfigValue" type="wstring" dir="in">
|
---|
2892 | <desc></desc>
|
---|
2893 | </param>
|
---|
2894 | </method>
|
---|
2895 | </interface>
|
---|
2896 |
|
---|
2897 |
|
---|
2898 | <!--
|
---|
2899 | // IMachine
|
---|
2900 | /////////////////////////////////////////////////////////////////////////
|
---|
2901 | -->
|
---|
2902 |
|
---|
2903 | <interface
|
---|
2904 | name="IInternalMachineControl" extends="$unknown"
|
---|
2905 | uuid="8e723ab0-812c-5662-dd8e-7ebc89637acf"
|
---|
2906 | internal="yes"
|
---|
2907 | wsmap="suppress"
|
---|
2908 | >
|
---|
2909 | <method name="setRemoveSavedStateFile">
|
---|
2910 | <desc>
|
---|
2911 | Updates the flag whether the saved state file is removed on a
|
---|
2912 | machine state change from Saved to PoweredOff.
|
---|
2913 | </desc>
|
---|
2914 | <param name="aRemove" type="boolean" dir="in"/>
|
---|
2915 | </method>
|
---|
2916 |
|
---|
2917 | <method name="updateState">
|
---|
2918 | <desc>
|
---|
2919 | Updates the VM state.
|
---|
2920 | <note>
|
---|
2921 | This operation will also update the settings file with the correct
|
---|
2922 | information about the saved state file and delete this file from disk
|
---|
2923 | when appropriate.
|
---|
2924 | </note>
|
---|
2925 | </desc>
|
---|
2926 | <param name="state" type="MachineState" dir="in"/>
|
---|
2927 | </method>
|
---|
2928 |
|
---|
2929 | <method name="getIPCId">
|
---|
2930 | <param name="id" type="wstring" dir="return"/>
|
---|
2931 | </method>
|
---|
2932 |
|
---|
2933 | <method name="beginPowerUp">
|
---|
2934 | <desc>
|
---|
2935 | Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
|
---|
2936 | gives it the progress object that should be part of any pending
|
---|
2937 | <link to="IMachine::launchVMProcess"/> operations. The progress
|
---|
2938 | object may be called back to reflect an early cancelation, so some care
|
---|
2939 | have to be taken with respect to any cancelation callbacks. The console
|
---|
2940 | object will call <link to="IInternalMachineControl::endPowerUp"/>
|
---|
2941 | to signal the completion of the progress object.
|
---|
2942 | </desc>
|
---|
2943 | <param name="aProgress" type="IProgress" dir="in" />
|
---|
2944 | </method>
|
---|
2945 |
|
---|
2946 | <method name="endPowerUp">
|
---|
2947 | <desc>
|
---|
2948 | Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
|
---|
2949 | This method may query status information from the progress object it
|
---|
2950 | received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
|
---|
2951 | it over to any in-progress <link to="IMachine::launchVMProcess"/>
|
---|
2952 | call in order to complete that progress object.
|
---|
2953 | </desc>
|
---|
2954 | <param name="result" type="long" dir="in"/>
|
---|
2955 | </method>
|
---|
2956 |
|
---|
2957 | <method name="beginPoweringDown">
|
---|
2958 | <desc>
|
---|
2959 | Called by the VM process to inform the server it wants to
|
---|
2960 | stop the VM execution and power down.
|
---|
2961 | </desc>
|
---|
2962 | <param name="progress" type="IProgress" dir="out">
|
---|
2963 | <desc>
|
---|
2964 | Progress object created by VBoxSVC to wait until
|
---|
2965 | the VM is powered down.
|
---|
2966 | </desc>
|
---|
2967 | </param>
|
---|
2968 | </method>
|
---|
2969 |
|
---|
2970 | <method name="endPoweringDown">
|
---|
2971 | <desc>
|
---|
2972 | Called by the VM process to inform the server that powering
|
---|
2973 | down previously requested by #beginPoweringDown is either
|
---|
2974 | successfully finished or there was a failure.
|
---|
2975 |
|
---|
2976 | <result name="VBOX_E_FILE_ERROR">
|
---|
2977 | Settings file not accessible.
|
---|
2978 | </result>
|
---|
2979 | <result name="VBOX_E_XML_ERROR">
|
---|
2980 | Could not parse the settings file.
|
---|
2981 | </result>
|
---|
2982 |
|
---|
2983 | </desc>
|
---|
2984 |
|
---|
2985 | <param name="result" type="long" dir="in">
|
---|
2986 | <desc>@c S_OK to indicate success.
|
---|
2987 | </desc>
|
---|
2988 | </param>
|
---|
2989 | <param name="errMsg" type="wstring" dir="in">
|
---|
2990 | <desc>@c human readable error message in case of failure.
|
---|
2991 | </desc>
|
---|
2992 | </param>
|
---|
2993 | </method>
|
---|
2994 |
|
---|
2995 | <method name="runUSBDeviceFilters">
|
---|
2996 | <desc>
|
---|
2997 | Asks the server to run USB devices filters of the associated
|
---|
2998 | machine against the given USB device and tell if there is
|
---|
2999 | a match.
|
---|
3000 | <note>
|
---|
3001 | Intended to be used only for remote USB devices. Local
|
---|
3002 | ones don't require to call this method (this is done
|
---|
3003 | implicitly by the Host and USBProxyService).
|
---|
3004 | </note>
|
---|
3005 | </desc>
|
---|
3006 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
3007 | <param name="matched" type="boolean" dir="out"/>
|
---|
3008 | <param name="maskedInterfaces" type="unsigned long" dir="out"/>
|
---|
3009 | </method>
|
---|
3010 |
|
---|
3011 | <method name="captureUSBDevice">
|
---|
3012 | <desc>
|
---|
3013 | Requests a capture of the given host USB device.
|
---|
3014 | When the request is completed, the VM process will
|
---|
3015 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3016 | notification.
|
---|
3017 | </desc>
|
---|
3018 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
3019 | </method>
|
---|
3020 |
|
---|
3021 | <method name="detachUSBDevice">
|
---|
3022 | <desc>
|
---|
3023 | Notification that a VM is going to detach (@a done = @c false) or has
|
---|
3024 | already detached (@a done = @c true) the given USB device.
|
---|
3025 | When the @a done = @c true request is completed, the VM process will
|
---|
3026 | get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
|
---|
3027 | notification.
|
---|
3028 | <note>
|
---|
3029 | In the @a done = @c true case, the server must run its own filters
|
---|
3030 | and filters of all VMs but this one on the detached device
|
---|
3031 | as if it were just attached to the host computer.
|
---|
3032 | </note>
|
---|
3033 | </desc>
|
---|
3034 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
3035 | <param name="done" type="boolean" dir="in"/>
|
---|
3036 | </method>
|
---|
3037 |
|
---|
3038 | <method name="autoCaptureUSBDevices">
|
---|
3039 | <desc>
|
---|
3040 | Requests a capture all matching USB devices attached to the host.
|
---|
3041 | When the request is completed, the VM process will
|
---|
3042 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3043 | notification per every captured device.
|
---|
3044 | </desc>
|
---|
3045 | </method>
|
---|
3046 |
|
---|
3047 | <method name="detachAllUSBDevices">
|
---|
3048 | <desc>
|
---|
3049 | Notification that a VM that is being powered down. The done
|
---|
3050 | parameter indicates whether which stage of the power down
|
---|
3051 | we're at. When @a done = @c false the VM is announcing its
|
---|
3052 | intentions, while when @a done = @c true the VM is reporting
|
---|
3053 | what it has done.
|
---|
3054 | <note>
|
---|
3055 | In the @a done = @c true case, the server must run its own filters
|
---|
3056 | and filters of all VMs but this one on all detach devices as
|
---|
3057 | if they were just attached to the host computer.
|
---|
3058 | </note>
|
---|
3059 | </desc>
|
---|
3060 | <param name="done" type="boolean" dir="in"/>
|
---|
3061 | </method>
|
---|
3062 |
|
---|
3063 | <method name="onSessionEnd">
|
---|
3064 | <desc>
|
---|
3065 | Triggered by the given session object when the session is about
|
---|
3066 | to close normally.
|
---|
3067 | </desc>
|
---|
3068 | <param name="session" type="ISession" dir="in">
|
---|
3069 | <desc>Session that is being closed</desc>
|
---|
3070 | </param>
|
---|
3071 | <param name="progress" type="IProgress" dir="return">
|
---|
3072 | <desc>
|
---|
3073 | Used to wait until the corresponding machine is actually
|
---|
3074 | dissociated from the given session on the server.
|
---|
3075 | Returned only when this session is a direct one.
|
---|
3076 | </desc>
|
---|
3077 | </param>
|
---|
3078 | </method>
|
---|
3079 |
|
---|
3080 | <method name="beginSavingState">
|
---|
3081 | <desc>
|
---|
3082 | Called by the VM process to inform the server it wants to
|
---|
3083 | save the current state and stop the VM execution.
|
---|
3084 | </desc>
|
---|
3085 | <param name="progress" type="IProgress" dir="out">
|
---|
3086 | <desc>
|
---|
3087 | Progress object created by VBoxSVC to wait until
|
---|
3088 | the state is saved.
|
---|
3089 | </desc>
|
---|
3090 | </param>
|
---|
3091 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3092 | <desc>
|
---|
3093 | File path the VM process must save the execution state to.
|
---|
3094 | </desc>
|
---|
3095 | </param>
|
---|
3096 | </method>
|
---|
3097 |
|
---|
3098 | <method name="endSavingState">
|
---|
3099 | <desc>
|
---|
3100 | Called by the VM process to inform the server that saving
|
---|
3101 | the state previously requested by #beginSavingState is either
|
---|
3102 | successfully finished or there was a failure.
|
---|
3103 |
|
---|
3104 | <result name="VBOX_E_FILE_ERROR">
|
---|
3105 | Settings file not accessible.
|
---|
3106 | </result>
|
---|
3107 | <result name="VBOX_E_XML_ERROR">
|
---|
3108 | Could not parse the settings file.
|
---|
3109 | </result>
|
---|
3110 |
|
---|
3111 | </desc>
|
---|
3112 |
|
---|
3113 | <param name="result" type="long" dir="in">
|
---|
3114 | <desc>@c S_OK to indicate success.
|
---|
3115 | </desc>
|
---|
3116 | </param>
|
---|
3117 | <param name="errMsg" type="wstring" dir="in">
|
---|
3118 | <desc>@c human readable error message in case of failure.
|
---|
3119 | </desc>
|
---|
3120 | </param>
|
---|
3121 | </method>
|
---|
3122 |
|
---|
3123 | <method name="adoptSavedState">
|
---|
3124 | <desc>
|
---|
3125 | Gets called by IConsole::adoptSavedState.
|
---|
3126 | <result name="VBOX_E_FILE_ERROR">
|
---|
3127 | Invalid saved state file path.
|
---|
3128 | </result>
|
---|
3129 | </desc>
|
---|
3130 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
3131 | <desc>Path to the saved state file to adopt.</desc>
|
---|
3132 | </param>
|
---|
3133 | </method>
|
---|
3134 |
|
---|
3135 | <method name="beginTakingSnapshot">
|
---|
3136 | <desc>
|
---|
3137 | Called from the VM process to request from the server to perform the
|
---|
3138 | server-side actions of creating a snapshot (creating differencing images
|
---|
3139 | and the snapshot object).
|
---|
3140 |
|
---|
3141 | <result name="VBOX_E_FILE_ERROR">
|
---|
3142 | Settings file not accessible.
|
---|
3143 | </result>
|
---|
3144 | <result name="VBOX_E_XML_ERROR">
|
---|
3145 | Could not parse the settings file.
|
---|
3146 | </result>
|
---|
3147 | </desc>
|
---|
3148 | <param name="initiator" type="IConsole" dir="in">
|
---|
3149 | <desc>The console object that initiated this call.</desc>
|
---|
3150 | </param>
|
---|
3151 | <param name="name" type="wstring" dir="in">
|
---|
3152 | <desc>Snapshot name.</desc>
|
---|
3153 | </param>
|
---|
3154 | <param name="description" type="wstring" dir="in">
|
---|
3155 | <desc>Snapshot description.</desc>
|
---|
3156 | </param>
|
---|
3157 | <param name="consoleProgress" type="IProgress" dir="in">
|
---|
3158 | <desc>
|
---|
3159 | Progress object created by the VM process tracking the
|
---|
3160 | snapshot's progress. This has the following sub-operations:
|
---|
3161 | <ul>
|
---|
3162 | <li>setting up (weight 1);</li>
|
---|
3163 | <li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
|
---|
3164 | <li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
|
---|
3165 | <li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
|
---|
3166 | <li>finishing up (weight 1)</li>
|
---|
3167 | </ul>
|
---|
3168 | </desc>
|
---|
3169 | </param>
|
---|
3170 | <param name="fTakingSnapshotOnline" type="boolean" dir="in">
|
---|
3171 | <desc>
|
---|
3172 | Whether this is an online snapshot (i.e. the machine is running).
|
---|
3173 | </desc>
|
---|
3174 | </param>
|
---|
3175 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3176 | <desc>
|
---|
3177 | File path the VM process must save the execution state to.
|
---|
3178 | </desc>
|
---|
3179 | </param>
|
---|
3180 | </method>
|
---|
3181 |
|
---|
3182 | <method name="endTakingSnapshot">
|
---|
3183 | <desc>
|
---|
3184 | Called by the VM process to inform the server that the snapshot
|
---|
3185 | previously requested by #beginTakingSnapshot is either
|
---|
3186 | successfully taken or there was a failure.
|
---|
3187 | </desc>
|
---|
3188 |
|
---|
3189 | <param name="success" type="boolean" dir="in">
|
---|
3190 | <desc>@c true to indicate success and @c false otherwise</desc>
|
---|
3191 | </param>
|
---|
3192 | </method>
|
---|
3193 |
|
---|
3194 | <method name="deleteSnapshot">
|
---|
3195 | <desc>
|
---|
3196 | Gets called by IConsole::deleteSnapshot.
|
---|
3197 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
3198 | Snapshot has more than one child snapshot.
|
---|
3199 | </result>
|
---|
3200 | </desc>
|
---|
3201 | <param name="initiator" type="IConsole" dir="in">
|
---|
3202 | <desc>The console object that initiated this call.</desc>
|
---|
3203 | </param>
|
---|
3204 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
3205 | <desc>UUID of the snapshot to delete.</desc>
|
---|
3206 | </param>
|
---|
3207 | <param name="machineState" type="MachineState" dir="out">
|
---|
3208 | <desc>New machine state after this operation is started.</desc>
|
---|
3209 | </param>
|
---|
3210 | <param name="progress" type="IProgress" dir="return">
|
---|
3211 | <desc>Progress object to track the operation completion.</desc>
|
---|
3212 | </param>
|
---|
3213 | </method>
|
---|
3214 |
|
---|
3215 | <method name="finishOnlineMergeMedium">
|
---|
3216 | <desc>
|
---|
3217 | Gets called by IConsole::onlineMergeMedium.
|
---|
3218 | </desc>
|
---|
3219 | <param name="mediumAttachment" type="IMediumAttachment" dir="in">
|
---|
3220 | <desc>The medium attachment which needs to be cleaned up.</desc>
|
---|
3221 | </param>
|
---|
3222 | <param name="source" type="IMedium" dir="in">
|
---|
3223 | <desc>Merge source medium.</desc>
|
---|
3224 | </param>
|
---|
3225 | <param name="target" type="IMedium" dir="in">
|
---|
3226 | <desc>Merge target medium.</desc>
|
---|
3227 | </param>
|
---|
3228 | <param name="mergeForward" type="boolean" dir="in">
|
---|
3229 | <desc>Merge direction.</desc>
|
---|
3230 | </param>
|
---|
3231 | <param name="parentForTarget" type="IMedium" dir="in">
|
---|
3232 | <desc>For forward merges: new parent for target medium.</desc>
|
---|
3233 | </param>
|
---|
3234 | <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
|
---|
3235 | <desc>For backward merges: list of media which need their parent UUID
|
---|
3236 | updated.</desc>
|
---|
3237 | </param>
|
---|
3238 | </method>
|
---|
3239 |
|
---|
3240 | <method name="restoreSnapshot">
|
---|
3241 | <desc>
|
---|
3242 | Gets called by IConsole::RestoreSnapshot.
|
---|
3243 | </desc>
|
---|
3244 | <param name="initiator" type="IConsole" dir="in">
|
---|
3245 | <desc>The console object that initiated this call.</desc>
|
---|
3246 | </param>
|
---|
3247 | <param name="snapshot" type="ISnapshot" dir="in">
|
---|
3248 | <desc>The snapshot to restore the VM state from.</desc>
|
---|
3249 | </param>
|
---|
3250 | <param name="machineState" type="MachineState" dir="out">
|
---|
3251 | <desc>New machine state after this operation is started.</desc>
|
---|
3252 | </param>
|
---|
3253 | <param name="progress" type="IProgress" dir="return">
|
---|
3254 | <desc>Progress object to track the operation completion.</desc>
|
---|
3255 | </param>
|
---|
3256 | </method>
|
---|
3257 |
|
---|
3258 | <method name="pullGuestProperties">
|
---|
3259 | <desc>
|
---|
3260 | Get the list of the guest properties matching a set of patterns along
|
---|
3261 | with their values, time stamps and flags and give responsibility for
|
---|
3262 | managing properties to the console.
|
---|
3263 | </desc>
|
---|
3264 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
3265 | <desc>
|
---|
3266 | The names of the properties returned.
|
---|
3267 | </desc>
|
---|
3268 | </param>
|
---|
3269 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
3270 | <desc>
|
---|
3271 | The values of the properties returned. The array entries match the
|
---|
3272 | corresponding entries in the @a name array.
|
---|
3273 | </desc>
|
---|
3274 | </param>
|
---|
3275 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
3276 | <desc>
|
---|
3277 | The time stamps of the properties returned. The array entries match
|
---|
3278 | the corresponding entries in the @a name array.
|
---|
3279 | </desc>
|
---|
3280 | </param>
|
---|
3281 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
3282 | <desc>
|
---|
3283 | The flags of the properties returned. The array entries match the
|
---|
3284 | corresponding entries in the @a name array.
|
---|
3285 | </desc>
|
---|
3286 | </param>
|
---|
3287 | </method>
|
---|
3288 |
|
---|
3289 | <method name="pushGuestProperty">
|
---|
3290 | <desc>
|
---|
3291 | Update a single guest property in IMachine.
|
---|
3292 | </desc>
|
---|
3293 | <param name="name" type="wstring" dir="in">
|
---|
3294 | <desc>
|
---|
3295 | The name of the property to be updated.
|
---|
3296 | </desc>
|
---|
3297 | </param>
|
---|
3298 | <param name="value" type="wstring" dir="in">
|
---|
3299 | <desc>
|
---|
3300 | The value of the property.
|
---|
3301 | </desc>
|
---|
3302 | </param>
|
---|
3303 | <param name="timestamp" type="long long" dir="in">
|
---|
3304 | <desc>
|
---|
3305 | The timestamp of the property.
|
---|
3306 | </desc>
|
---|
3307 | </param>
|
---|
3308 | <param name="flags" type="wstring" dir="in">
|
---|
3309 | <desc>
|
---|
3310 | The flags of the property.
|
---|
3311 | </desc>
|
---|
3312 | </param>
|
---|
3313 | </method>
|
---|
3314 |
|
---|
3315 | <method name="lockMedia">
|
---|
3316 | <desc>
|
---|
3317 | Locks all media attached to the machine for writing and parents of
|
---|
3318 | attached differencing media (if any) for reading. This operation is
|
---|
3319 | atomic so that if it fails no media is actually locked.
|
---|
3320 |
|
---|
3321 | This method is intended to be called when the machine is in Starting or
|
---|
3322 | Restoring state. The locked media will be automatically unlocked when
|
---|
3323 | the machine is powered off or crashed.
|
---|
3324 | </desc>
|
---|
3325 | </method>
|
---|
3326 | <method name="unlockMedia">
|
---|
3327 | <desc>
|
---|
3328 | Unlocks all media previously locked using
|
---|
3329 | <link to="IInternalMachineControl::lockMedia"/>.
|
---|
3330 |
|
---|
3331 | This method is intended to be used with teleportation so that it is
|
---|
3332 | possible to teleport between processes on the same machine.
|
---|
3333 | </desc>
|
---|
3334 | </method>
|
---|
3335 | </interface>
|
---|
3336 |
|
---|
3337 | <interface
|
---|
3338 | name="IBIOSSettings" extends="$unknown"
|
---|
3339 | uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
|
---|
3340 | wsmap="managed"
|
---|
3341 | >
|
---|
3342 | <desc>
|
---|
3343 | The IBIOSSettings interface represents BIOS settings of the virtual
|
---|
3344 | machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
|
---|
3345 | </desc>
|
---|
3346 | <attribute name="logoFadeIn" type="boolean">
|
---|
3347 | <desc>Fade in flag for BIOS logo animation.</desc>
|
---|
3348 | </attribute>
|
---|
3349 |
|
---|
3350 | <attribute name="logoFadeOut" type="boolean">
|
---|
3351 | <desc>Fade out flag for BIOS logo animation.</desc>
|
---|
3352 | </attribute>
|
---|
3353 |
|
---|
3354 | <attribute name="logoDisplayTime" type="unsigned long">
|
---|
3355 | <desc>BIOS logo display time in milliseconds (0 = default).</desc>
|
---|
3356 | </attribute>
|
---|
3357 |
|
---|
3358 | <attribute name="logoImagePath" type="wstring">
|
---|
3359 | <desc>
|
---|
3360 | Local file system path for external BIOS splash image. Empty string
|
---|
3361 | means the default image is shown on boot.
|
---|
3362 | </desc>
|
---|
3363 | </attribute>
|
---|
3364 |
|
---|
3365 | <attribute name="bootMenuMode" type="BIOSBootMenuMode">
|
---|
3366 | <desc>Mode of the BIOS boot device menu.</desc>
|
---|
3367 | </attribute>
|
---|
3368 |
|
---|
3369 | <attribute name="ACPIEnabled" type="boolean">
|
---|
3370 | <desc>ACPI support flag.</desc>
|
---|
3371 | </attribute>
|
---|
3372 |
|
---|
3373 | <attribute name="IOAPICEnabled" type="boolean">
|
---|
3374 | <desc>
|
---|
3375 | IO APIC support flag. If set, VirtualBox will provide an IO APIC
|
---|
3376 | and support IRQs above 15.
|
---|
3377 | </desc>
|
---|
3378 | </attribute>
|
---|
3379 |
|
---|
3380 | <attribute name="timeOffset" type="long long">
|
---|
3381 | <desc>
|
---|
3382 | Offset in milliseconds from the host system time. This allows for
|
---|
3383 | guests running with a different system date/time than the host.
|
---|
3384 | It is equivalent to setting the system date/time in the BIOS except
|
---|
3385 | it is not an absolute value but a relative one. Guest Additions
|
---|
3386 | time synchronization honors this offset.
|
---|
3387 | </desc>
|
---|
3388 | </attribute>
|
---|
3389 |
|
---|
3390 | <attribute name="PXEDebugEnabled" type="boolean">
|
---|
3391 | <desc>
|
---|
3392 | PXE debug logging flag. If set, VirtualBox will write extensive
|
---|
3393 | PXE trace information to the release log.
|
---|
3394 | </desc>
|
---|
3395 | </attribute>
|
---|
3396 |
|
---|
3397 | </interface>
|
---|
3398 |
|
---|
3399 | <enum
|
---|
3400 | name="CleanupMode"
|
---|
3401 | uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441"
|
---|
3402 | >
|
---|
3403 | <desc>Cleanup mode, used with <link to="IMachine::unregister" />.
|
---|
3404 | </desc>
|
---|
3405 | <const name="UnregisterOnly" value="1">
|
---|
3406 | <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
|
---|
3407 | </const>
|
---|
3408 | <const name="DetachAllReturnNone" value="2">
|
---|
3409 | <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
|
---|
3410 | </const>
|
---|
3411 | <const name="DetachAllReturnHardDisksOnly" value="3">
|
---|
3412 | <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc>
|
---|
3413 | </const>
|
---|
3414 | <const name="Full" value="4">
|
---|
3415 | <desc>Delete all snapshots, detach all media and return all media for closing.</desc>
|
---|
3416 | </const>
|
---|
3417 | </enum>
|
---|
3418 |
|
---|
3419 | <interface
|
---|
3420 | name="IPciAddress" extends="$unknown"
|
---|
3421 | uuid="D88B324F-DB19-4D3B-A1A9-BF5B127199A8"
|
---|
3422 | wsmap="struct"
|
---|
3423 | >
|
---|
3424 |
|
---|
3425 | <desc>
|
---|
3426 | Address on the PCI bus.
|
---|
3427 | </desc>
|
---|
3428 |
|
---|
3429 | <attribute name="bus" type="short">
|
---|
3430 | <desc>
|
---|
3431 | Bus number.
|
---|
3432 | </desc>
|
---|
3433 | </attribute>
|
---|
3434 |
|
---|
3435 | <attribute name="device" type="short">
|
---|
3436 | <desc>
|
---|
3437 | Device number.
|
---|
3438 | </desc>
|
---|
3439 | </attribute>
|
---|
3440 |
|
---|
3441 | <attribute name="devFunction" type="short">
|
---|
3442 | <desc>
|
---|
3443 | Device function number.
|
---|
3444 | </desc>
|
---|
3445 | </attribute>
|
---|
3446 |
|
---|
3447 | <method name="asLong">
|
---|
3448 | <desc>
|
---|
3449 | Convert PCI address into long.
|
---|
3450 | </desc>
|
---|
3451 | <param name="result" type="long" dir="return" />
|
---|
3452 | </method>
|
---|
3453 |
|
---|
3454 | <method name="fromLong">
|
---|
3455 | <desc>
|
---|
3456 | Make PCI address from long.
|
---|
3457 | </desc>
|
---|
3458 | <param name="number" type="long" dir="in" />
|
---|
3459 | </method>
|
---|
3460 | </interface>
|
---|
3461 |
|
---|
3462 | <interface
|
---|
3463 | name="IPciDeviceAttachment" extends="$unknown"
|
---|
3464 | uuid="91f33d6f-e621-4f70-a77e-15f0e3c714d5"
|
---|
3465 | wsmap="struct"
|
---|
3466 | >
|
---|
3467 |
|
---|
3468 | <desc>
|
---|
3469 | Information about PCI attachments.
|
---|
3470 | </desc>
|
---|
3471 |
|
---|
3472 | <attribute name="name" type="wstring" readonly="yes">
|
---|
3473 | <desc>
|
---|
3474 | Device name.
|
---|
3475 | </desc>
|
---|
3476 | </attribute>
|
---|
3477 |
|
---|
3478 | <attribute name="isPhysicalDevice" type="boolean" readonly="yes">
|
---|
3479 | <desc>
|
---|
3480 | If this is physical or virtual device.
|
---|
3481 | </desc>
|
---|
3482 | </attribute>
|
---|
3483 |
|
---|
3484 | <attribute name="hostAddress" type="long" readonly="yes">
|
---|
3485 | <desc>
|
---|
3486 | Address of device on the host, applicable only to host devices.
|
---|
3487 | </desc>
|
---|
3488 | </attribute>
|
---|
3489 |
|
---|
3490 | <attribute name="guestAddress" type="long" readonly="yes">
|
---|
3491 | <desc>
|
---|
3492 | Address of device on the guest.
|
---|
3493 | </desc>
|
---|
3494 | </attribute>
|
---|
3495 |
|
---|
3496 | </interface>
|
---|
3497 |
|
---|
3498 |
|
---|
3499 | <interface
|
---|
3500 | name="IMachine" extends="$unknown"
|
---|
3501 | uuid="59d09c78-2558-45c8-a95e-8761d70fdc95"
|
---|
3502 | wsmap="managed"
|
---|
3503 | >
|
---|
3504 | <desc>
|
---|
3505 | The IMachine interface represents a virtual machine, or guest, created
|
---|
3506 | in VirtualBox.
|
---|
3507 |
|
---|
3508 | This interface is used in two contexts. First of all, a collection of
|
---|
3509 | objects implementing this interface is stored in the
|
---|
3510 | <link to="IVirtualBox::machines"/> attribute which lists all the virtual
|
---|
3511 | machines that are currently registered with this VirtualBox
|
---|
3512 | installation. Also, once a session has been opened for the given virtual
|
---|
3513 | machine (e.g. the virtual machine is running), the machine object
|
---|
3514 | associated with the open session can be queried from the session object;
|
---|
3515 | see <link to="ISession"/> for details.
|
---|
3516 |
|
---|
3517 | The main role of this interface is to expose the settings of the virtual
|
---|
3518 | machine and provide methods to change various aspects of the virtual
|
---|
3519 | machine's configuration. For machine objects stored in the
|
---|
3520 | <link to="IVirtualBox::machines"/> collection, all attributes are
|
---|
3521 | read-only unless explicitly stated otherwise in individual attribute
|
---|
3522 | and method descriptions.
|
---|
3523 |
|
---|
3524 | In order to change a machine setting, a session for this machine must be
|
---|
3525 | opened using one of the <link to="IMachine::lockMachine" /> or
|
---|
3526 | <link to="IMachine::launchVMProcess"/> methods. After the
|
---|
3527 | machine has been successfully locked for a session, a mutable machine object
|
---|
3528 | needs to be queried from the session object and then the desired settings
|
---|
3529 | changes can be applied to the returned object using IMachine attributes and
|
---|
3530 | methods. See the <link to="ISession"/> interface description for more
|
---|
3531 | information about sessions.
|
---|
3532 |
|
---|
3533 | Note that IMachine does not provide methods to control virtual machine
|
---|
3534 | execution (such as start the machine, or power it down) -- these methods
|
---|
3535 | are grouped in a separate interface called <link to="IConsole" />.
|
---|
3536 |
|
---|
3537 | <see>ISession, IConsole</see>
|
---|
3538 | </desc>
|
---|
3539 |
|
---|
3540 | <attribute name="parent" type="IVirtualBox" readonly="yes">
|
---|
3541 | <desc>Associated parent object.</desc>
|
---|
3542 | </attribute>
|
---|
3543 |
|
---|
3544 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
3545 | <desc>
|
---|
3546 | Whether this virtual machine is currently accessible or not.
|
---|
3547 |
|
---|
3548 | A machine is always deemed accessible unless it is registered <i>and</i>
|
---|
3549 | its settings file cannot be read or parsed (either because the file itself
|
---|
3550 | is unavailable or has invalid XML contents).
|
---|
3551 |
|
---|
3552 | Every time this property is read, the accessibility state of
|
---|
3553 | this machine is re-evaluated. If the returned value is @c false,
|
---|
3554 | the <link to="#accessError"/> property may be used to get the
|
---|
3555 | detailed error information describing the reason of
|
---|
3556 | inaccessibility, including XML error messages.
|
---|
3557 |
|
---|
3558 | When the machine is inaccessible, only the following properties
|
---|
3559 | can be used on it:
|
---|
3560 | <ul>
|
---|
3561 | <li><link to="#parent"/></li>
|
---|
3562 | <li><link to="#id"/></li>
|
---|
3563 | <li><link to="#settingsFilePath"/></li>
|
---|
3564 | <li><link to="#accessible"/></li>
|
---|
3565 | <li><link to="#accessError"/></li>
|
---|
3566 | </ul>
|
---|
3567 |
|
---|
3568 | An attempt to access any other property or method will return
|
---|
3569 | an error.
|
---|
3570 |
|
---|
3571 | The only possible action you can perform on an inaccessible
|
---|
3572 | machine is to unregister it using the
|
---|
3573 | <link to="IMachine::unregister"/> call (or, to check
|
---|
3574 | for the accessibility state once more by querying this
|
---|
3575 | property).
|
---|
3576 |
|
---|
3577 | <note>
|
---|
3578 | In the current implementation, once this property returns
|
---|
3579 | @c true, the machine will never become inaccessible
|
---|
3580 | later, even if its settings file cannot be successfully
|
---|
3581 | read/written any more (at least, until the VirtualBox
|
---|
3582 | server is restarted). This limitation may be removed in
|
---|
3583 | future releases.
|
---|
3584 | </note>
|
---|
3585 | </desc>
|
---|
3586 | </attribute>
|
---|
3587 |
|
---|
3588 | <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
3589 | <desc>
|
---|
3590 | Error information describing the reason of machine
|
---|
3591 | inaccessibility.
|
---|
3592 |
|
---|
3593 | Reading this property is only valid after the last call to
|
---|
3594 | <link to="#accessible"/> returned @c false (i.e. the
|
---|
3595 | machine is currently inaccessible). Otherwise, a @c null
|
---|
3596 | IVirtualBoxErrorInfo object will be returned.
|
---|
3597 | </desc>
|
---|
3598 | </attribute>
|
---|
3599 |
|
---|
3600 | <attribute name="name" type="wstring">
|
---|
3601 | <desc>
|
---|
3602 | Name of the virtual machine.
|
---|
3603 |
|
---|
3604 | Besides being used for human-readable identification purposes
|
---|
3605 | everywhere in VirtualBox, the virtual machine name is also used
|
---|
3606 | as a name of the machine's settings file and as a name of the
|
---|
3607 | subdirectory this settings file resides in. Thus, every time you
|
---|
3608 | change the value of this property, the settings file will be
|
---|
3609 | renamed once you call <link to="#saveSettings"/> to confirm the
|
---|
3610 | change. The containing subdirectory will be also renamed, but
|
---|
3611 | only if it has exactly the same name as the settings file
|
---|
3612 | itself prior to changing this property (for backward compatibility
|
---|
3613 | with previous API releases). The above implies the following
|
---|
3614 | limitations:
|
---|
3615 | <ul>
|
---|
3616 | <li>The machine name cannot be empty.</li>
|
---|
3617 | <li>The machine name can contain only characters that are valid
|
---|
3618 | file name characters according to the rules of the file
|
---|
3619 | system used to store VirtualBox configuration.</li>
|
---|
3620 | <li>You cannot have two or more machines with the same name
|
---|
3621 | if they use the same subdirectory for storing the machine
|
---|
3622 | settings files.</li>
|
---|
3623 | <li>You cannot change the name of the machine if it is running,
|
---|
3624 | or if any file in the directory containing the settings file
|
---|
3625 | is being used by another running machine or by any other
|
---|
3626 | process in the host operating system at a time when
|
---|
3627 | <link to="#saveSettings"/> is called.
|
---|
3628 | </li>
|
---|
3629 | </ul>
|
---|
3630 | If any of the above limitations are hit, <link to="#saveSettings"/>
|
---|
3631 | will return an appropriate error message explaining the exact
|
---|
3632 | reason and the changes you made to this machine will not be saved.
|
---|
3633 |
|
---|
3634 | Starting with VirtualBox 4.0, a “.vbox” extension of the settings
|
---|
3635 | file is recommended, but not enforced. (Previous versions always
|
---|
3636 | used a generic ".xml" extension.)
|
---|
3637 | </desc>
|
---|
3638 | </attribute>
|
---|
3639 |
|
---|
3640 | <attribute name="description" type="wstring">
|
---|
3641 | <desc>
|
---|
3642 | Description of the virtual machine.
|
---|
3643 |
|
---|
3644 | The description attribute can contain any text and is
|
---|
3645 | typically used to describe the hardware and software
|
---|
3646 | configuration of the virtual machine in detail (i.e. network
|
---|
3647 | settings, versions of the installed software and so on).
|
---|
3648 | </desc>
|
---|
3649 | </attribute>
|
---|
3650 |
|
---|
3651 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
3652 | <desc>UUID of the virtual machine.</desc>
|
---|
3653 | </attribute>
|
---|
3654 |
|
---|
3655 | <attribute name="OSTypeId" type="wstring">
|
---|
3656 | <desc>
|
---|
3657 | User-defined identifier of the Guest OS type.
|
---|
3658 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
3659 | an IGuestOSType object representing details about the given
|
---|
3660 | Guest OS type.
|
---|
3661 | <note>
|
---|
3662 | This value may differ from the value returned by
|
---|
3663 | <link to="IGuest::OSTypeId"/> if Guest Additions are
|
---|
3664 | installed to the guest OS.
|
---|
3665 | </note>
|
---|
3666 | </desc>
|
---|
3667 | </attribute>
|
---|
3668 |
|
---|
3669 | <attribute name="HardwareVersion" type="wstring">
|
---|
3670 | <desc>Hardware version identifier. Internal use only for now.</desc>
|
---|
3671 | </attribute>
|
---|
3672 |
|
---|
3673 | <attribute name="hardwareUUID" type="uuid" mod="string">
|
---|
3674 | <desc>
|
---|
3675 | The UUID presented to the guest via memory tables, hardware and guest
|
---|
3676 | properties. For most VMs this is the same as the @a id, but for VMs
|
---|
3677 | which have been cloned or teleported it may be the same as the source
|
---|
3678 | VM. This latter is because the guest shouldn't notice that it was
|
---|
3679 | cloned or teleported.
|
---|
3680 | </desc>
|
---|
3681 | </attribute>
|
---|
3682 |
|
---|
3683 | <attribute name="CPUCount" type="unsigned long">
|
---|
3684 | <desc>Number of virtual CPUs in the VM.</desc>
|
---|
3685 | </attribute>
|
---|
3686 |
|
---|
3687 | <attribute name="CPUHotPlugEnabled" type="boolean">
|
---|
3688 | <desc>
|
---|
3689 | This setting determines whether VirtualBox allows CPU
|
---|
3690 | hotplugging for this machine.</desc>
|
---|
3691 | </attribute>
|
---|
3692 |
|
---|
3693 | <attribute name="CPUExecutionCap" type="unsigned long">
|
---|
3694 | <desc>
|
---|
3695 | Means to limit the number of CPU cycles a guest can use. The unit
|
---|
3696 | is percentage of host CPU cycles per second. The valid range
|
---|
3697 | is 1 - 100. 100 (the default) implies no limit.
|
---|
3698 | </desc>
|
---|
3699 | </attribute>
|
---|
3700 |
|
---|
3701 | <attribute name="memorySize" type="unsigned long">
|
---|
3702 | <desc>System memory size in megabytes.</desc>
|
---|
3703 | </attribute>
|
---|
3704 |
|
---|
3705 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
3706 | <desc>Memory balloon size in megabytes.</desc>
|
---|
3707 | </attribute>
|
---|
3708 |
|
---|
3709 | <attribute name="PageFusionEnabled" type="boolean">
|
---|
3710 | <desc>
|
---|
3711 | This setting determines whether VirtualBox allows page
|
---|
3712 | fusion for this machine (64 bits host only).
|
---|
3713 | </desc>
|
---|
3714 | </attribute>
|
---|
3715 |
|
---|
3716 | <attribute name="VRAMSize" type="unsigned long">
|
---|
3717 | <desc>Video memory size in megabytes.</desc>
|
---|
3718 | </attribute>
|
---|
3719 |
|
---|
3720 | <attribute name="accelerate3DEnabled" type="boolean" default="false">
|
---|
3721 | <desc>
|
---|
3722 | This setting determines whether VirtualBox allows this machine to make
|
---|
3723 | use of the 3D graphics support available on the host.</desc>
|
---|
3724 | </attribute>
|
---|
3725 |
|
---|
3726 | <attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
|
---|
3727 | <desc>
|
---|
3728 | This setting determines whether VirtualBox allows this machine to make
|
---|
3729 | use of the 2D video acceleration support available on the host.</desc>
|
---|
3730 | </attribute>
|
---|
3731 |
|
---|
3732 | <attribute name="monitorCount" type="unsigned long">
|
---|
3733 | <desc>
|
---|
3734 | Number of virtual monitors.
|
---|
3735 | <note>
|
---|
3736 | Only effective on Windows XP and later guests with
|
---|
3737 | Guest Additions installed.
|
---|
3738 | </note>
|
---|
3739 | </desc>
|
---|
3740 | </attribute>
|
---|
3741 |
|
---|
3742 | <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
|
---|
3743 | <desc>Object containing all BIOS settings.</desc>
|
---|
3744 | </attribute>
|
---|
3745 |
|
---|
3746 | <attribute name="firmwareType" type="FirmwareType">
|
---|
3747 | <desc>Type of firmware (such as legacy BIOS or EFI), used for initial
|
---|
3748 | bootstrap in this VM.</desc>
|
---|
3749 | </attribute>
|
---|
3750 |
|
---|
3751 | <attribute name="pointingHidType" type="PointingHidType">
|
---|
3752 | <desc>Type of pointing HID (such as mouse or tablet) used in this VM.
|
---|
3753 | The default is typically "PS2Mouse" but can vary depending on the
|
---|
3754 | requirements of the guest operating system.</desc>
|
---|
3755 | </attribute>
|
---|
3756 |
|
---|
3757 | <attribute name="keyboardHidType" type="KeyboardHidType">
|
---|
3758 | <desc>Type of keyboard HID used in this VM.
|
---|
3759 | The default is typically "PS2Keyboard" but can vary depending on the
|
---|
3760 | requirements of the guest operating system.</desc>
|
---|
3761 | </attribute>
|
---|
3762 |
|
---|
3763 | <attribute name="hpetEnabled" type="boolean">
|
---|
3764 | <desc>This attribute controls if High Precision Event Timer (HPET) is
|
---|
3765 | enabled in this VM. Use this property if you want to provide guests
|
---|
3766 | with additional time source, or if guest requires HPET to function correctly.
|
---|
3767 | Default is false.</desc>
|
---|
3768 | </attribute>
|
---|
3769 |
|
---|
3770 | <attribute name="chipsetType" type="ChipsetType">
|
---|
3771 | <desc>Chipset type used in this VM.</desc>
|
---|
3772 | </attribute>
|
---|
3773 |
|
---|
3774 | <attribute name="snapshotFolder" type="wstring">
|
---|
3775 | <desc>
|
---|
3776 | Full path to the directory used to store snapshot data
|
---|
3777 | (differencing media and saved state files) of this machine.
|
---|
3778 |
|
---|
3779 | The initial value of this property is
|
---|
3780 | <tt><</tt><link to="#settingsFilePath">
|
---|
3781 | path_to_settings_file</link><tt>>/<</tt>
|
---|
3782 | <link to="#id">machine_uuid</link>
|
---|
3783 | <tt>></tt>.
|
---|
3784 |
|
---|
3785 | Currently, it is an error to try to change this property on
|
---|
3786 | a machine that has snapshots (because this would require to
|
---|
3787 | move possibly large files to a different location).
|
---|
3788 | A separate method will be available for this purpose later.
|
---|
3789 |
|
---|
3790 | <note>
|
---|
3791 | Setting this property to @c null or to an empty string will restore
|
---|
3792 | the initial value.
|
---|
3793 | </note>
|
---|
3794 | <note>
|
---|
3795 | When setting this property, the specified path can be
|
---|
3796 | absolute (full path) or relative to the directory where the
|
---|
3797 | <link to="#settingsFilePath">machine settings file</link>
|
---|
3798 | is located. When reading this property, a full path is
|
---|
3799 | always returned.
|
---|
3800 | </note>
|
---|
3801 | <note>
|
---|
3802 | The specified path may not exist, it will be created
|
---|
3803 | when necessary.
|
---|
3804 | </note>
|
---|
3805 | </desc>
|
---|
3806 | </attribute>
|
---|
3807 |
|
---|
3808 | <attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
|
---|
3809 | <desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
|
---|
3810 | </attribute>
|
---|
3811 |
|
---|
3812 | <attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
|
---|
3813 | <desc>Array of media attached to this machine.</desc>
|
---|
3814 | </attribute>
|
---|
3815 |
|
---|
3816 | <attribute name="USBController" type="IUSBController" readonly="yes">
|
---|
3817 | <desc>
|
---|
3818 | Associated USB controller object.
|
---|
3819 |
|
---|
3820 | <note>
|
---|
3821 | If USB functionality is not available in the given edition of
|
---|
3822 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
3823 | </note>
|
---|
3824 | </desc>
|
---|
3825 | </attribute>
|
---|
3826 |
|
---|
3827 | <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
|
---|
3828 | <desc>Associated audio adapter, always present.</desc>
|
---|
3829 | </attribute>
|
---|
3830 |
|
---|
3831 | <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
|
---|
3832 | <desc>Array of storage controllers attached to this machine.</desc>
|
---|
3833 | </attribute>
|
---|
3834 |
|
---|
3835 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
3836 | <desc>
|
---|
3837 | Full name of the file containing machine settings data.
|
---|
3838 | </desc>
|
---|
3839 | </attribute>
|
---|
3840 |
|
---|
3841 | <attribute name="settingsModified" type="boolean" readonly="yes">
|
---|
3842 | <desc>
|
---|
3843 | Whether the settings of this machine have been modified
|
---|
3844 | (but neither yet saved nor discarded).
|
---|
3845 | <note>
|
---|
3846 | Reading this property is only valid on instances returned
|
---|
3847 | by <link to="ISession::machine"/> and on new machines
|
---|
3848 | created by <link to="IVirtualBox::createMachine"/> or opened
|
---|
3849 | by <link to="IVirtualBox::openMachine"/> but not
|
---|
3850 | yet registered, or on unregistered machines after calling
|
---|
3851 | <link to="IMachine::unregister"/>. For all other
|
---|
3852 | cases, the settings can never be modified.
|
---|
3853 | </note>
|
---|
3854 | <note>
|
---|
3855 | For newly created unregistered machines, the value of this
|
---|
3856 | property is always @c true until <link to="#saveSettings"/>
|
---|
3857 | is called (no matter if any machine settings have been
|
---|
3858 | changed after the creation or not). For opened machines
|
---|
3859 | the value is set to @c false (and then follows to normal rules).
|
---|
3860 | </note>
|
---|
3861 | </desc>
|
---|
3862 | </attribute>
|
---|
3863 |
|
---|
3864 | <attribute name="sessionState" type="SessionState" readonly="yes">
|
---|
3865 | <desc>Current session state for this machine.</desc>
|
---|
3866 | </attribute>
|
---|
3867 |
|
---|
3868 | <attribute name="sessionType" type="wstring" readonly="yes">
|
---|
3869 | <desc>
|
---|
3870 | Type of the session. If <link to="#sessionState"/> is
|
---|
3871 | Spawning or Locked, this attribute contains the
|
---|
3872 | same value as passed to the
|
---|
3873 | <link to="IMachine::launchVMProcess"/> method in the
|
---|
3874 | @a type parameter. If the session was used with
|
---|
3875 | <link to="IMachine::lockMachine" />, or if
|
---|
3876 | <link to="#sessionState"/> is SessionClosed, the value of this
|
---|
3877 | attribute is an empty string.
|
---|
3878 | </desc>
|
---|
3879 | </attribute>
|
---|
3880 |
|
---|
3881 | <attribute name="sessionPid" type="unsigned long" readonly="yes">
|
---|
3882 | <desc>
|
---|
3883 | Identifier of the session process. This attribute contains the
|
---|
3884 | platform-dependent identifier of the process whose session was
|
---|
3885 | used with <link to="IMachine::lockMachine" /> call. The returned
|
---|
3886 | value is only valid if <link to="#sessionState"/> is Locked or
|
---|
3887 | Unlocking by the time this property is read.
|
---|
3888 | </desc>
|
---|
3889 | </attribute>
|
---|
3890 |
|
---|
3891 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
3892 | <desc>Current execution state of this machine.</desc>
|
---|
3893 | </attribute>
|
---|
3894 |
|
---|
3895 | <attribute name="lastStateChange" type="long long" readonly="yes">
|
---|
3896 | <desc>
|
---|
3897 | Time stamp of the last execution state change,
|
---|
3898 | in milliseconds since 1970-01-01 UTC.
|
---|
3899 | </desc>
|
---|
3900 | </attribute>
|
---|
3901 |
|
---|
3902 | <attribute name="stateFilePath" type="wstring" readonly="yes">
|
---|
3903 | <desc>
|
---|
3904 | Full path to the file that stores the execution state of
|
---|
3905 | the machine when it is in the <link to="MachineState_Saved"/> state.
|
---|
3906 | <note>
|
---|
3907 | When the machine is not in the Saved state, this attribute is
|
---|
3908 | an empty string.
|
---|
3909 | </note>
|
---|
3910 | </desc>
|
---|
3911 | </attribute>
|
---|
3912 |
|
---|
3913 | <attribute name="logFolder" type="wstring" readonly="yes">
|
---|
3914 | <desc>
|
---|
3915 | Full path to the folder that stores a set of rotated log files
|
---|
3916 | recorded during machine execution. The most recent log file is
|
---|
3917 | named <tt>VBox.log</tt>, the previous log file is
|
---|
3918 | named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
|
---|
3919 | in the current version).
|
---|
3920 | </desc>
|
---|
3921 | </attribute>
|
---|
3922 |
|
---|
3923 | <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
|
---|
3924 | <desc>
|
---|
3925 | Current snapshot of this machine. This is @c null if the machine
|
---|
3926 | currently has no snapshots. If it is not @c null, then it was
|
---|
3927 | set by one of <link to="IConsole::takeSnapshot" />,
|
---|
3928 | <link to="IConsole::deleteSnapshot" />
|
---|
3929 | or <link to="IConsole::restoreSnapshot" />, depending on which
|
---|
3930 | was called last. See <link to="ISnapshot"/> for details.
|
---|
3931 | </desc>
|
---|
3932 | </attribute>
|
---|
3933 |
|
---|
3934 | <attribute name="snapshotCount" type="unsigned long" readonly="yes">
|
---|
3935 | <desc>
|
---|
3936 | Number of snapshots taken on this machine. Zero means the
|
---|
3937 | machine doesn't have any snapshots.
|
---|
3938 | </desc>
|
---|
3939 | </attribute>
|
---|
3940 |
|
---|
3941 | <attribute name="currentStateModified" type="boolean" readonly="yes">
|
---|
3942 | <desc>
|
---|
3943 | Returns @c true if the current state of the machine is not
|
---|
3944 | identical to the state stored in the current snapshot.
|
---|
3945 |
|
---|
3946 | The current state is identical to the current snapshot only
|
---|
3947 | directly after one of the following calls are made:
|
---|
3948 |
|
---|
3949 | <ul>
|
---|
3950 | <li><link to="IConsole::restoreSnapshot"/>
|
---|
3951 | </li>
|
---|
3952 | <li><link to="IConsole::takeSnapshot"/> (issued on a
|
---|
3953 | "powered off" or "saved" machine, for which
|
---|
3954 | <link to="#settingsModified"/> returns @c false)
|
---|
3955 | </li>
|
---|
3956 | </ul>
|
---|
3957 |
|
---|
3958 | The current state remains identical until one of the following
|
---|
3959 | happens:
|
---|
3960 | <ul>
|
---|
3961 | <li>settings of the machine are changed</li>
|
---|
3962 | <li>the saved state is deleted</li>
|
---|
3963 | <li>the current snapshot is deleted</li>
|
---|
3964 | <li>an attempt to execute the machine is made</li>
|
---|
3965 | </ul>
|
---|
3966 |
|
---|
3967 | <note>
|
---|
3968 | For machines that don't have snapshots, this property is
|
---|
3969 | always @c false.
|
---|
3970 | </note>
|
---|
3971 | </desc>
|
---|
3972 | </attribute>
|
---|
3973 |
|
---|
3974 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
3975 | <desc>
|
---|
3976 | Collection of shared folders for this machine (permanent shared
|
---|
3977 | folders). These folders are shared automatically at machine startup
|
---|
3978 | and available only to the guest OS installed within this machine.
|
---|
3979 |
|
---|
3980 | New shared folders are added to the collection using
|
---|
3981 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
3982 | removed using <link to="#removeSharedFolder"/>.
|
---|
3983 | </desc>
|
---|
3984 | </attribute>
|
---|
3985 |
|
---|
3986 | <attribute name="clipboardMode" type="ClipboardMode">
|
---|
3987 | <desc>
|
---|
3988 | Synchronization mode between the host OS clipboard
|
---|
3989 | and the guest OS clipboard.
|
---|
3990 | </desc>
|
---|
3991 | </attribute>
|
---|
3992 |
|
---|
3993 | <attribute name="guestPropertyNotificationPatterns" type="wstring">
|
---|
3994 | <desc>
|
---|
3995 | A comma-separated list of simple glob patterns. Changes to guest
|
---|
3996 | properties whose name matches one of the patterns will generate an
|
---|
3997 | <link to="IGuestPropertyChangedEvent"/> signal.
|
---|
3998 | </desc>
|
---|
3999 | </attribute>
|
---|
4000 |
|
---|
4001 | <attribute name="teleporterEnabled" type="boolean">
|
---|
4002 | <desc>
|
---|
4003 | When set to @a true, the virtual machine becomes a target teleporter
|
---|
4004 | the next time it is powered on. This can only set to @a true when the
|
---|
4005 | VM is in the @a PoweredOff or @a Aborted state.
|
---|
4006 |
|
---|
4007 | <!-- This property is automatically set to @a false when the VM is powered
|
---|
4008 | on. (bird: This doesn't work yet ) -->
|
---|
4009 | </desc>
|
---|
4010 | </attribute>
|
---|
4011 |
|
---|
4012 | <attribute name="teleporterPort" type="unsigned long">
|
---|
4013 | <desc>
|
---|
4014 | The TCP port the target teleporter will listen for incoming
|
---|
4015 | teleportations on.
|
---|
4016 |
|
---|
4017 | 0 means the port is automatically selected upon power on. The actual
|
---|
4018 | value can be read from this property while the machine is waiting for
|
---|
4019 | incoming teleportations.
|
---|
4020 | </desc>
|
---|
4021 | </attribute>
|
---|
4022 |
|
---|
4023 | <attribute name="teleporterAddress" type="wstring">
|
---|
4024 | <desc>
|
---|
4025 | The address the target teleporter will listen on. If set to an empty
|
---|
4026 | string, it will listen on all addresses.
|
---|
4027 | </desc>
|
---|
4028 | </attribute>
|
---|
4029 |
|
---|
4030 | <attribute name="teleporterPassword" type="wstring">
|
---|
4031 | <desc>
|
---|
4032 | The password to check for on the target teleporter. This is just a
|
---|
4033 | very basic measure to prevent simple hacks and operators accidentally
|
---|
4034 | beaming a virtual machine to the wrong place.
|
---|
4035 | </desc>
|
---|
4036 | </attribute>
|
---|
4037 |
|
---|
4038 | <attribute name="faultToleranceState" type="FaultToleranceState">
|
---|
4039 | <desc>
|
---|
4040 | Fault tolerance state; disabled, source or target.
|
---|
4041 | This property can be changed at any time. If you change it for a running
|
---|
4042 | VM, then the fault tolerance address and port must be set beforehand.
|
---|
4043 | </desc>
|
---|
4044 | </attribute>
|
---|
4045 |
|
---|
4046 | <attribute name="faultTolerancePort" type="unsigned long">
|
---|
4047 | <desc>
|
---|
4048 | The TCP port the fault tolerance source or target will use for
|
---|
4049 | communication.
|
---|
4050 | </desc>
|
---|
4051 | </attribute>
|
---|
4052 |
|
---|
4053 | <attribute name="faultToleranceAddress" type="wstring">
|
---|
4054 | <desc>
|
---|
4055 | The address the fault tolerance source or target.
|
---|
4056 | </desc>
|
---|
4057 | </attribute>
|
---|
4058 |
|
---|
4059 | <attribute name="faultTolerancePassword" type="wstring">
|
---|
4060 | <desc>
|
---|
4061 | The password to check for on the standby VM. This is just a
|
---|
4062 | very basic measure to prevent simple hacks and operators accidentally
|
---|
4063 | choosing the wrong standby VM.
|
---|
4064 | </desc>
|
---|
4065 | </attribute>
|
---|
4066 |
|
---|
4067 | <attribute name="faultToleranceSyncInterval" type="unsigned long">
|
---|
4068 | <desc>
|
---|
4069 | The interval in ms used for syncing the state between source and target.
|
---|
4070 | </desc>
|
---|
4071 | </attribute>
|
---|
4072 |
|
---|
4073 | <attribute name="RTCUseUTC" type="boolean">
|
---|
4074 | <desc>
|
---|
4075 | When set to @a true, the RTC device of the virtual machine will run
|
---|
4076 | in UTC time, otherwise in local time. Especially Unix guests prefer
|
---|
4077 | the time in UTC.
|
---|
4078 | </desc>
|
---|
4079 | </attribute>
|
---|
4080 |
|
---|
4081 | <attribute name="ioCacheEnabled" type="boolean">
|
---|
4082 | <desc>
|
---|
4083 | When set to @a true, the builtin I/O cache of the virtual machine
|
---|
4084 | will be enabled.
|
---|
4085 | </desc>
|
---|
4086 | </attribute>
|
---|
4087 |
|
---|
4088 | <attribute name="ioCacheSize" type="unsigned long">
|
---|
4089 | <desc>
|
---|
4090 | Maximum size of the I/O cache in MB.
|
---|
4091 | </desc>
|
---|
4092 | </attribute>
|
---|
4093 |
|
---|
4094 | <attribute name="bandwidthControl" type="IBandwidthControl" readonly="yes">
|
---|
4095 | <desc>
|
---|
4096 | Bandwidth control manager.
|
---|
4097 | </desc>
|
---|
4098 | </attribute>
|
---|
4099 |
|
---|
4100 | <attribute name="pciDeviceAssignments" type="IPciDeviceAttachment" readonly="yes" safearray="yes">
|
---|
4101 | <desc>Array of PCI devices assigned to this machine, to get list of all PCI devices
|
---|
4102 | attached to the machine use IConsole::attachedPciDevices attribute, as
|
---|
4103 | this attribute is intended to list only devices additional to what
|
---|
4104 | described in virtual hardware config. Usually, this list keeps host's
|
---|
4105 | physical devices assigned to the particular machine.
|
---|
4106 | </desc>
|
---|
4107 | </attribute>
|
---|
4108 |
|
---|
4109 | <method name="lockMachine">
|
---|
4110 | <desc>
|
---|
4111 | Locks the machine for the given session to enable the caller
|
---|
4112 | to make changes to the machine or start the VM or control
|
---|
4113 | VM execution.
|
---|
4114 |
|
---|
4115 | There are two ways to lock a machine for such uses:
|
---|
4116 |
|
---|
4117 | <ul>
|
---|
4118 | <li>If you want to make changes to the machine settings,
|
---|
4119 | you must obtain an exclusive write lock on the machine
|
---|
4120 | by setting @a lockType to @c Write.
|
---|
4121 |
|
---|
4122 | This will only succeed if no other process has locked
|
---|
4123 | the machine to prevent conflicting changes. Only after
|
---|
4124 | an exclusive write lock has been obtained using this method, one
|
---|
4125 | can change all VM settings or execute the VM in the process
|
---|
4126 | space of the session object. (Note that the latter is only of
|
---|
4127 | interest if you actually want to write a new front-end for
|
---|
4128 | virtual machines; but this API gets called internally by
|
---|
4129 | the existing front-ends such as VBoxHeadless and the VirtualBox
|
---|
4130 | GUI to acquire a write lock on the machine that they are running.)
|
---|
4131 |
|
---|
4132 | On success, write-locking the machine for a session creates
|
---|
4133 | a second copy of the IMachine object. It is this second object
|
---|
4134 | upon which changes can be made; in VirtualBox terminology, the
|
---|
4135 | second copy is "mutable". It is only this second, mutable machine
|
---|
4136 | object upon which you can call methods that change the
|
---|
4137 | machine state. After having called this method, you can
|
---|
4138 | obtain this second, mutable machine object using the
|
---|
4139 | <link to="ISession::machine" /> attribute.
|
---|
4140 | </li>
|
---|
4141 | <li>If you only want to check the machine state or control
|
---|
4142 | machine execution without actually changing machine
|
---|
4143 | settings (e.g. to get access to VM statistics or take
|
---|
4144 | a snapshot or save the machine state), then set the
|
---|
4145 | @a lockType argument to @c Shared.
|
---|
4146 |
|
---|
4147 | If no other session has obtained a lock, you will obtain an
|
---|
4148 | exclusive write lock as described above. However, if another
|
---|
4149 | session has already obtained such a lock, then a link to that
|
---|
4150 | existing session will be established which allows you
|
---|
4151 | to control that existing session.
|
---|
4152 |
|
---|
4153 | To find out which type of lock was obtained, you can
|
---|
4154 | inspect <link to="ISession::type" />, which will have been
|
---|
4155 | set to either @c WriteLock or @c Shared.
|
---|
4156 | </li>
|
---|
4157 | </ul>
|
---|
4158 |
|
---|
4159 | In either case, you can get access to the <link to="IConsole" />
|
---|
4160 | object which controls VM execution.
|
---|
4161 |
|
---|
4162 | Also in all of the above cases, one must always call
|
---|
4163 | <link to="ISession::unlockMachine" /> to release the lock on the machine, or
|
---|
4164 | the machine's state will eventually be set to "Aborted".
|
---|
4165 |
|
---|
4166 | To change settings on a machine, the following sequence is typically
|
---|
4167 | performed:
|
---|
4168 |
|
---|
4169 | <ol>
|
---|
4170 | <li>Call this method to obtain an exclusive write lock for the current session.</li>
|
---|
4171 |
|
---|
4172 | <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
|
---|
4173 |
|
---|
4174 | <li>Change the settings of the machine by invoking IMachine methods.</li>
|
---|
4175 |
|
---|
4176 | <li>Call <link to="IMachine::saveSettings" />.</li>
|
---|
4177 |
|
---|
4178 | <li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
|
---|
4179 | </ol>
|
---|
4180 |
|
---|
4181 | <result name="E_UNEXPECTED">
|
---|
4182 | Virtual machine not registered.
|
---|
4183 | </result>
|
---|
4184 | <result name="E_ACCESSDENIED">
|
---|
4185 | Process not started by OpenRemoteSession.
|
---|
4186 | </result>
|
---|
4187 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4188 | Session already open or being opened.
|
---|
4189 | </result>
|
---|
4190 | <result name="VBOX_E_VM_ERROR">
|
---|
4191 | Failed to assign machine to session.
|
---|
4192 | </result>
|
---|
4193 | </desc>
|
---|
4194 | <param name="session" type="ISession" dir="in">
|
---|
4195 | <desc>
|
---|
4196 | Session object for which the machine will be locked.
|
---|
4197 | </desc>
|
---|
4198 | </param>
|
---|
4199 | <param name="lockType" type="LockType" dir="in">
|
---|
4200 | <desc>
|
---|
4201 | If set to @c Write, then attempt to acquire an exclusive write lock or fail.
|
---|
4202 | If set to @c Shared, then either acquire an exclusive write lock or establish
|
---|
4203 | a link to an existing session.
|
---|
4204 | </desc>
|
---|
4205 | </param>
|
---|
4206 | </method>
|
---|
4207 |
|
---|
4208 | <method name="launchVMProcess">
|
---|
4209 | <desc>
|
---|
4210 | Spawns a new process that will execute the virtual machine and obtains a shared
|
---|
4211 | lock on the machine for the calling session.
|
---|
4212 |
|
---|
4213 | If launching the VM succeeds, the new VM process will create its own session
|
---|
4214 | and write-lock the machine for it, preventing conflicting changes from other
|
---|
4215 | processes. If the machine is already locked (because it is already running or
|
---|
4216 | because another session has a write lock), launching the VM process will therefore
|
---|
4217 | fail. Reversely, future attempts to obtain a write lock will also fail while the
|
---|
4218 | machine is running.
|
---|
4219 |
|
---|
4220 | The caller's session object remains separate from the session opened by the new
|
---|
4221 | VM process. It receives its own <link to="IConsole" /> object which can be used
|
---|
4222 | to control machine execution, but it cannot be used to change all VM settings
|
---|
4223 | which would be available after a <link to="#lockMachine" /> call.
|
---|
4224 |
|
---|
4225 | The caller must eventually release the session's shared lock by calling
|
---|
4226 | <link to="ISession::unlockMachine" /> on the local session object once this call
|
---|
4227 | has returned. However, the session's state (see <link to="ISession::state" />)
|
---|
4228 | will not return to "Unlocked" until the remote session has also unlocked
|
---|
4229 | the machine (i.e. the machine has stopped running).
|
---|
4230 |
|
---|
4231 | Launching a VM process can take some time (a new VM is started in a new process,
|
---|
4232 | for which memory and other resources need to be set up). Because of this,
|
---|
4233 | an <link to="IProgress" /> object is returned to allow the caller to wait
|
---|
4234 | for this asynchronous operation to be completed. Until then, the caller's
|
---|
4235 | session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
|
---|
4236 | and <link to="ISession::console" /> attributes cannot be accessed.
|
---|
4237 | It is recommended to use <link to="IProgress::waitForCompletion" /> or
|
---|
4238 | similar calls to wait for completion. Completion is signalled when the VM
|
---|
4239 | is powered on. If launching the VM fails, error messages can be queried
|
---|
4240 | via the progress object, if available.
|
---|
4241 |
|
---|
4242 | The progress object will have at least 2 sub-operations. The first
|
---|
4243 | operation covers the period up to the new VM process calls powerUp.
|
---|
4244 | The subsequent operations mirror the <link to="IConsole::powerUp"/>
|
---|
4245 | progress object. Because <link to="IConsole::powerUp"/> may require
|
---|
4246 | some extra sub-operations, the <link to="IProgress::operationCount"/>
|
---|
4247 | may change at the completion of operation.
|
---|
4248 |
|
---|
4249 | For details on the teleportation progress operation, see
|
---|
4250 | <link to="IConsole::powerUp"/>.
|
---|
4251 |
|
---|
4252 | The @a environment argument is a string containing definitions of
|
---|
4253 | environment variables in the following format:
|
---|
4254 | @code
|
---|
4255 | NAME[=VALUE]\n
|
---|
4256 | NAME[=VALUE]\n
|
---|
4257 | ...
|
---|
4258 | @endcode
|
---|
4259 | where <tt>\\n</tt> is the new line character. These environment
|
---|
4260 | variables will be appended to the environment of the VirtualBox server
|
---|
4261 | process. If an environment variable exists both in the server process
|
---|
4262 | and in this list, the value from this list takes precedence over the
|
---|
4263 | server's variable. If the value of the environment variable is
|
---|
4264 | omitted, this variable will be removed from the resulting environment.
|
---|
4265 | If the environment string is @c null or empty, the server environment
|
---|
4266 | is inherited by the started process as is.
|
---|
4267 |
|
---|
4268 | <result name="E_UNEXPECTED">
|
---|
4269 | Virtual machine not registered.
|
---|
4270 | </result>
|
---|
4271 | <result name="E_INVALIDARG">
|
---|
4272 | Invalid session type @a type.
|
---|
4273 | </result>
|
---|
4274 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4275 | No machine matching @a machineId found.
|
---|
4276 | </result>
|
---|
4277 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4278 | Session already open or being opened.
|
---|
4279 | </result>
|
---|
4280 | <result name="VBOX_E_IPRT_ERROR">
|
---|
4281 | Launching process for machine failed.
|
---|
4282 | </result>
|
---|
4283 | <result name="VBOX_E_VM_ERROR">
|
---|
4284 | Failed to assign machine to session.
|
---|
4285 | </result>
|
---|
4286 | </desc>
|
---|
4287 | <param name="session" type="ISession" dir="in">
|
---|
4288 | <desc>
|
---|
4289 | Client session object to which the VM process will be connected (this
|
---|
4290 | must be in "Unlocked" state).
|
---|
4291 | </desc>
|
---|
4292 | </param>
|
---|
4293 | <param name="type" type="wstring" dir="in">
|
---|
4294 | <desc>
|
---|
4295 | Front-end to use for the new VM process. The following are currently supported:
|
---|
4296 | <ul>
|
---|
4297 | <li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
|
---|
4298 | <li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
|
---|
4299 | <li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
|
---|
4300 | <li><tt>"emergencystop"</tt>: reserved value, used for aborting
|
---|
4301 | the currently running VM or session owner. In this case the
|
---|
4302 | @a session parameter may be @c NULL (if it is non-null it isn't
|
---|
4303 | used in any way), and the @a progress return value will be always
|
---|
4304 | NULL. The operation completes immediately.</li>
|
---|
4305 | </ul>
|
---|
4306 | </desc>
|
---|
4307 | </param>
|
---|
4308 | <param name="environment" type="wstring" dir="in">
|
---|
4309 | <desc>
|
---|
4310 | Environment to pass to the VM process.
|
---|
4311 | </desc>
|
---|
4312 | </param>
|
---|
4313 | <param name="progress" type="IProgress" dir="return">
|
---|
4314 | <desc>Progress object to track the operation completion.</desc>
|
---|
4315 | </param>
|
---|
4316 | </method>
|
---|
4317 |
|
---|
4318 | <method name="setBootOrder">
|
---|
4319 | <desc>
|
---|
4320 | Puts the given device to the specified position in
|
---|
4321 | the boot order.
|
---|
4322 |
|
---|
4323 | To indicate that no device is associated with the given position,
|
---|
4324 | <link to="DeviceType_Null"/> should be used.
|
---|
4325 |
|
---|
4326 | @todo setHardDiskBootOrder(), setNetworkBootOrder()
|
---|
4327 |
|
---|
4328 | <result name="E_INVALIDARG">
|
---|
4329 | Boot @a position out of range.
|
---|
4330 | </result>
|
---|
4331 | <result name="E_NOTIMPL">
|
---|
4332 | Booting from USB @a device currently not supported.
|
---|
4333 | </result>
|
---|
4334 |
|
---|
4335 | </desc>
|
---|
4336 | <param name="position" type="unsigned long" dir="in">
|
---|
4337 | <desc>
|
---|
4338 | Position in the boot order (@c 1 to the total number of
|
---|
4339 | devices the machine can boot from, as returned by
|
---|
4340 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4341 | </desc>
|
---|
4342 | </param>
|
---|
4343 | <param name="device" type="DeviceType" dir="in">
|
---|
4344 | <desc>
|
---|
4345 | The type of the device used to boot at the given position.
|
---|
4346 | </desc>
|
---|
4347 | </param>
|
---|
4348 | </method>
|
---|
4349 |
|
---|
4350 | <method name="getBootOrder" const="yes">
|
---|
4351 | <desc>
|
---|
4352 | Returns the device type that occupies the specified
|
---|
4353 | position in the boot order.
|
---|
4354 |
|
---|
4355 | @todo [remove?]
|
---|
4356 | If the machine can have more than one device of the returned type
|
---|
4357 | (such as hard disks), then a separate method should be used to
|
---|
4358 | retrieve the individual device that occupies the given position.
|
---|
4359 |
|
---|
4360 | If here are no devices at the given position, then
|
---|
4361 | <link to="DeviceType_Null"/> is returned.
|
---|
4362 |
|
---|
4363 | @todo getHardDiskBootOrder(), getNetworkBootOrder()
|
---|
4364 |
|
---|
4365 | <result name="E_INVALIDARG">
|
---|
4366 | Boot @a position out of range.
|
---|
4367 | </result>
|
---|
4368 |
|
---|
4369 | </desc>
|
---|
4370 | <param name="position" type="unsigned long" dir="in">
|
---|
4371 | <desc>
|
---|
4372 | Position in the boot order (@c 1 to the total number of
|
---|
4373 | devices the machine can boot from, as returned by
|
---|
4374 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4375 | </desc>
|
---|
4376 | </param>
|
---|
4377 | <param name="device" type="DeviceType" dir="return">
|
---|
4378 | <desc>
|
---|
4379 | Device at the given position.
|
---|
4380 | </desc>
|
---|
4381 | </param>
|
---|
4382 | </method>
|
---|
4383 |
|
---|
4384 | <method name="attachDevice">
|
---|
4385 | <desc>
|
---|
4386 | Attaches a device and optionally mounts a medium to the given storage
|
---|
4387 | controller (<link to="IStorageController" />, identified by @a name),
|
---|
4388 | at the indicated port and device.
|
---|
4389 |
|
---|
4390 | This method is intended for managing storage devices in general while a
|
---|
4391 | machine is powered off. It can be used to attach and detach fixed
|
---|
4392 | and removable media. The following kind of media can be attached
|
---|
4393 | to a machine:
|
---|
4394 |
|
---|
4395 | <ul>
|
---|
4396 | <li>For fixed and removable media, you can pass in a medium that was
|
---|
4397 | previously opened using <link to="IVirtualBox::openMedium" />.
|
---|
4398 | </li>
|
---|
4399 |
|
---|
4400 | <li>Only for storage devices supporting removable media (such as
|
---|
4401 | DVDs and floppies), you can also specify a null pointer to
|
---|
4402 | indicate an empty drive or one of the medium objects listed
|
---|
4403 | in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
|
---|
4404 | arrays to indicate a host drive.
|
---|
4405 | For removable devices, you can also use <link to="IMachine::mountMedium"/>
|
---|
4406 | to change the media while the machine is running.
|
---|
4407 | </li>
|
---|
4408 | </ul>
|
---|
4409 |
|
---|
4410 | In a VM's default configuration of virtual machines, the secondary
|
---|
4411 | master of the IDE controller is used for a CD/DVD drive.
|
---|
4412 |
|
---|
4413 | After calling this returns successfully, a new instance of
|
---|
4414 | <link to="IMediumAttachment"/> will appear in the machine's list of medium
|
---|
4415 | attachments (see <link to="IMachine::mediumAttachments"/>).
|
---|
4416 |
|
---|
4417 | See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
|
---|
4418 | information about attaching media.
|
---|
4419 |
|
---|
4420 | The specified device slot must not have a device attached to it,
|
---|
4421 | or this method will fail.
|
---|
4422 |
|
---|
4423 | <note>
|
---|
4424 | You cannot attach a device to a newly created machine until
|
---|
4425 | this machine's settings are saved to disk using
|
---|
4426 | <link to="#saveSettings"/>.
|
---|
4427 | </note>
|
---|
4428 | <note>
|
---|
4429 | If the medium is being attached indirectly, a new differencing medium
|
---|
4430 | will implicitly be created for it and attached instead. If the
|
---|
4431 | changes made to the machine settings (including this indirect
|
---|
4432 | attachment) are later cancelled using <link to="#discardSettings"/>,
|
---|
4433 | this implicitly created differencing medium will implicitly
|
---|
4434 | be deleted.
|
---|
4435 | </note>
|
---|
4436 |
|
---|
4437 | <result name="E_INVALIDARG">
|
---|
4438 | SATA device, SATA port, IDE port or IDE slot out of range, or
|
---|
4439 | file or UUID not found.
|
---|
4440 | </result>
|
---|
4441 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4442 | Machine must be registered before media can be attached.
|
---|
4443 | </result>
|
---|
4444 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4445 | Invalid machine state.
|
---|
4446 | </result>
|
---|
4447 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4448 | A medium is already attached to this or another virtual machine.
|
---|
4449 | </result>
|
---|
4450 |
|
---|
4451 | </desc>
|
---|
4452 | <param name="name" type="wstring" dir="in">
|
---|
4453 | <desc>Name of the storage controller to attach the device to.</desc>
|
---|
4454 | </param>
|
---|
4455 | <param name="controllerPort" type="long" dir="in">
|
---|
4456 | <desc>Port to attach the device to. For an IDE controller, 0 specifies
|
---|
4457 | the primary controller and 1 specifies the secondary controller.
|
---|
4458 | For a SCSI controller, this must range from 0 to 15; for a SATA controller,
|
---|
4459 | from 0 to 29; for an SAS controller, from 0 to 7.</desc>
|
---|
4460 | </param>
|
---|
4461 | <param name="device" type="long" dir="in">
|
---|
4462 | <desc>Device slot in the given port to attach the device to. This is only
|
---|
4463 | relevant for IDE controllers, for which 0 specifies the master device and
|
---|
4464 | 1 specifies the slave device. For all other controller types, this must
|
---|
4465 | be 0.</desc>
|
---|
4466 | </param>
|
---|
4467 | <param name="type" type="DeviceType" dir="in">
|
---|
4468 | <desc>Device type of the attached device. For media opened by
|
---|
4469 | <link to="IVirtualBox::openMedium" />, this must match the device type
|
---|
4470 | specified there.</desc>
|
---|
4471 | </param>
|
---|
4472 | <param name="medium" type="IMedium" dir="in">
|
---|
4473 | <desc>Medium to mount or NULL for an empty drive.</desc>
|
---|
4474 | </param>
|
---|
4475 | </method>
|
---|
4476 |
|
---|
4477 | <method name="detachDevice">
|
---|
4478 | <desc>
|
---|
4479 | Detaches the device attached to a device slot of the specified bus.
|
---|
4480 |
|
---|
4481 | Detaching the device from the virtual machine is deferred. This means
|
---|
4482 | that the medium remains associated with the machine when this method
|
---|
4483 | returns and gets actually de-associated only after a successful
|
---|
4484 | <link to="#saveSettings"/> call. See <link to="IMedium"/>
|
---|
4485 | for more detailed information about attaching media.
|
---|
4486 |
|
---|
4487 | <note>
|
---|
4488 | You cannot detach a device from a running machine.
|
---|
4489 | </note>
|
---|
4490 | <note>
|
---|
4491 | Detaching differencing media implicitly created by <link
|
---|
4492 | to="#attachDevice"/> for the indirect attachment using this
|
---|
4493 | method will <b>not</b> implicitly delete them. The
|
---|
4494 | <link to="IMedium::deleteStorage"/> operation should be
|
---|
4495 | explicitly performed by the caller after the medium is successfully
|
---|
4496 | detached and the settings are saved with
|
---|
4497 | <link to="#saveSettings"/>, if it is the desired action.
|
---|
4498 | </note>
|
---|
4499 |
|
---|
4500 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4501 | Attempt to detach medium from a running virtual machine.
|
---|
4502 | </result>
|
---|
4503 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4504 | No medium attached to given slot/bus.
|
---|
4505 | </result>
|
---|
4506 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
4507 | Medium format does not support storage deletion.
|
---|
4508 | </result>
|
---|
4509 |
|
---|
4510 | </desc>
|
---|
4511 | <param name="name" type="wstring" dir="in">
|
---|
4512 | <desc>Name of the storage controller to detach the medium from.</desc>
|
---|
4513 | </param>
|
---|
4514 | <param name="controllerPort" type="long" dir="in">
|
---|
4515 | <desc>Port number to detach the medium from.</desc>
|
---|
4516 | </param>
|
---|
4517 | <param name="device" type="long" dir="in">
|
---|
4518 | <desc>Device slot number to detach the medium from.</desc>
|
---|
4519 | </param>
|
---|
4520 | </method>
|
---|
4521 |
|
---|
4522 | <method name="passthroughDevice">
|
---|
4523 | <desc>
|
---|
4524 | Sets the passthrough mode of an existing DVD device. Changing the
|
---|
4525 | setting while the VM is running is forbidden. The setting is only used
|
---|
4526 | if at VM start the device is configured as a host DVD drive, in all
|
---|
4527 | other cases it is ignored. The device must already exist; see
|
---|
4528 | <link to="IMachine::attachDevice"/> for how to attach a new device.
|
---|
4529 |
|
---|
4530 | The @a controllerPort and @a device parameters specify the device slot and
|
---|
4531 | have have the same meaning as with <link to="IMachine::attachDevice" />.
|
---|
4532 |
|
---|
4533 | <result name="E_INVALIDARG">
|
---|
4534 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4535 | </result>
|
---|
4536 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4537 | Attempt to modify an unregistered virtual machine.
|
---|
4538 | </result>
|
---|
4539 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4540 | Invalid machine state.
|
---|
4541 | </result>
|
---|
4542 |
|
---|
4543 | </desc>
|
---|
4544 | <param name="name" type="wstring" dir="in">
|
---|
4545 | <desc>Name of the storage controller.</desc>
|
---|
4546 | </param>
|
---|
4547 | <param name="controllerPort" type="long" dir="in">
|
---|
4548 | <desc>Storage controller port.</desc>
|
---|
4549 | </param>
|
---|
4550 | <param name="device" type="long" dir="in">
|
---|
4551 | <desc>Device slot in the given port.</desc>
|
---|
4552 | </param>
|
---|
4553 | <param name="passthrough" type="boolean" dir="in">
|
---|
4554 | <desc>New value for the passthrough setting.</desc>
|
---|
4555 | </param>
|
---|
4556 | </method>
|
---|
4557 |
|
---|
4558 | <method name="setBandwidthGroupForDevice">
|
---|
4559 | <desc>
|
---|
4560 | Sets the bandwidth group of an existing storage device.
|
---|
4561 | The device must already exist; see <link to="IMachine::attachDevice"/>
|
---|
4562 | for how to attach a new device.
|
---|
4563 |
|
---|
4564 | The @a controllerPort and @a device parameters specify the device slot and
|
---|
4565 | have have the same meaning as with <link to="IMachine::attachDevice" />.
|
---|
4566 |
|
---|
4567 | <result name="E_INVALIDARG">
|
---|
4568 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4569 | </result>
|
---|
4570 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4571 | Attempt to modify an unregistered virtual machine.
|
---|
4572 | </result>
|
---|
4573 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4574 | Invalid machine state.
|
---|
4575 | </result>
|
---|
4576 |
|
---|
4577 | </desc>
|
---|
4578 | <param name="name" type="wstring" dir="in">
|
---|
4579 | <desc>Name of the storage controller.</desc>
|
---|
4580 | </param>
|
---|
4581 | <param name="controllerPort" type="long" dir="in">
|
---|
4582 | <desc>Storage controller port.</desc>
|
---|
4583 | </param>
|
---|
4584 | <param name="device" type="long" dir="in">
|
---|
4585 | <desc>Device slot in the given port.</desc>
|
---|
4586 | </param>
|
---|
4587 | <param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
|
---|
4588 | <desc>New value for the bandwidth group or NULL for no group.</desc>
|
---|
4589 | </param>
|
---|
4590 | </method>
|
---|
4591 |
|
---|
4592 | <method name="mountMedium">
|
---|
4593 | <desc>
|
---|
4594 | Mounts a medium (<link to="IMedium" />, identified
|
---|
4595 | by the given UUID @a id) to the given storage controller
|
---|
4596 | (<link to="IStorageController" />, identified by @a name),
|
---|
4597 | at the indicated port and device. The device must already exist;
|
---|
4598 | see <link to="IMachine::attachDevice"/> for how to attach a new device.
|
---|
4599 |
|
---|
4600 | This method is intended only for managing removable media, where the
|
---|
4601 | device is fixed but media is changeable at runtime (such as DVDs
|
---|
4602 | and floppies). It cannot be used for fixed media such as hard disks.
|
---|
4603 |
|
---|
4604 | The @a controllerPort and @a device parameters specify the device slot and
|
---|
4605 | have have the same meaning as with <link to="IMachine::attachDevice" />.
|
---|
4606 |
|
---|
4607 | The specified device slot can have a medium mounted, which will be
|
---|
4608 | unmounted first. Specifying a zero UUID (or an empty string) for
|
---|
4609 | @a medium does just an unmount.
|
---|
4610 |
|
---|
4611 | See <link to="IMedium"/> for more detailed information about
|
---|
4612 | attaching media.
|
---|
4613 |
|
---|
4614 | <result name="E_INVALIDARG">
|
---|
4615 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4616 | </result>
|
---|
4617 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4618 | Attempt to attach medium to an unregistered virtual machine.
|
---|
4619 | </result>
|
---|
4620 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4621 | Invalid machine state.
|
---|
4622 | </result>
|
---|
4623 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4624 | Medium already attached to this or another virtual machine.
|
---|
4625 | </result>
|
---|
4626 |
|
---|
4627 | </desc>
|
---|
4628 | <param name="name" type="wstring" dir="in">
|
---|
4629 | <desc>Name of the storage controller to attach the medium to.</desc>
|
---|
4630 | </param>
|
---|
4631 | <param name="controllerPort" type="long" dir="in">
|
---|
4632 | <desc>Port to attach the medium to.</desc>
|
---|
4633 | </param>
|
---|
4634 | <param name="device" type="long" dir="in">
|
---|
4635 | <desc>Device slot in the given port to attach the medium to.</desc>
|
---|
4636 | </param>
|
---|
4637 | <param name="medium" type="IMedium" dir="in">
|
---|
4638 | <desc>Medium to mount or NULL for an empty drive.</desc>
|
---|
4639 | </param>
|
---|
4640 | <param name="force" type="boolean" dir="in">
|
---|
4641 | <desc>Allows to force unmount/mount of a medium which is locked by
|
---|
4642 | the device slot in the given port to attach the medium to.</desc>
|
---|
4643 | </param>
|
---|
4644 | </method>
|
---|
4645 |
|
---|
4646 | <method name="getMedium" const="yes">
|
---|
4647 | <desc>
|
---|
4648 | Returns the virtual medium attached to a device slot of the specified
|
---|
4649 | bus.
|
---|
4650 |
|
---|
4651 | Note that if the medium was indirectly attached by
|
---|
4652 | <link to="#mountMedium"/> to the given device slot then this
|
---|
4653 | method will return not the same object as passed to the
|
---|
4654 | <link to="#mountMedium"/> call. See <link to="IMedium"/> for
|
---|
4655 | more detailed information about mounting a medium.
|
---|
4656 |
|
---|
4657 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4658 | No medium attached to given slot/bus.
|
---|
4659 | </result>
|
---|
4660 |
|
---|
4661 | </desc>
|
---|
4662 | <param name="name" type="wstring" dir="in">
|
---|
4663 | <desc>Name of the storage controller the medium is attached to.</desc>
|
---|
4664 | </param>
|
---|
4665 | <param name="controllerPort" type="long" dir="in">
|
---|
4666 | <desc>Port to query.</desc>
|
---|
4667 | </param>
|
---|
4668 | <param name="device" type="long" dir="in">
|
---|
4669 | <desc>Device slot in the given port to query.</desc>
|
---|
4670 | </param>
|
---|
4671 | <param name="medium" type="IMedium" dir="return">
|
---|
4672 | <desc>Attached medium object.</desc>
|
---|
4673 | </param>
|
---|
4674 | </method>
|
---|
4675 |
|
---|
4676 | <method name="getMediumAttachmentsOfController" const="yes">
|
---|
4677 | <desc>
|
---|
4678 | Returns an array of medium attachments which are attached to the
|
---|
4679 | the controller with the given name.
|
---|
4680 |
|
---|
4681 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4682 | A storage controller with given name doesn't exist.
|
---|
4683 | </result>
|
---|
4684 | </desc>
|
---|
4685 | <param name="name" type="wstring" dir="in"/>
|
---|
4686 | <param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
|
---|
4687 | </method>
|
---|
4688 |
|
---|
4689 | <method name="getMediumAttachment" const="yes">
|
---|
4690 | <desc>
|
---|
4691 | Returns a medium attachment which corresponds to the controller with
|
---|
4692 | the given name, on the given port and device slot.
|
---|
4693 |
|
---|
4694 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4695 | No attachment exists for the given controller/port/device combination.
|
---|
4696 | </result>
|
---|
4697 | </desc>
|
---|
4698 | <param name="name" type="wstring" dir="in"/>
|
---|
4699 | <param name="controllerPort" type="long" dir="in"/>
|
---|
4700 | <param name="device" type="long" dir="in"/>
|
---|
4701 | <param name="attachment" type="IMediumAttachment" dir="return"/>
|
---|
4702 | </method>
|
---|
4703 |
|
---|
4704 | <method name="attachHostPciDevice">
|
---|
4705 | <desc>
|
---|
4706 | Attaches host PCI device with the given (host) PCI address to the
|
---|
4707 | PCI bus of the virtual machine. Please note, that this operation
|
---|
4708 | is two phase, as real attachment will happen when VM will start,
|
---|
4709 | and most information will be delivered as IHostPciDevicePlugEvent
|
---|
4710 | on IVirtualBox event source.
|
---|
4711 |
|
---|
4712 | <see>IHostPciDevicePlugEvent</see>
|
---|
4713 |
|
---|
4714 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4715 | Virtual machine state is not stopped (PCI hotplug not yet implemented).
|
---|
4716 | </result>
|
---|
4717 | <result name="VBOX_E_PDM_ERROR">
|
---|
4718 | Virtual machine does not have a PCI controller allowing attachment of physical devices.
|
---|
4719 | </result>
|
---|
4720 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
4721 | Hardware or host OS doesn't allow PCI device passthrought.
|
---|
4722 | </result>
|
---|
4723 | </desc>
|
---|
4724 | <param name="hostAddress" type="long" dir="in">
|
---|
4725 | <desc>Address of the host PCI device.</desc>
|
---|
4726 | </param>
|
---|
4727 | <param name="desiredGuestAddress" type="long" dir="in">
|
---|
4728 | <desc>Desired position of this device on guest PCI bus.</desc>
|
---|
4729 | </param>
|
---|
4730 | <param name="tryToUnbind" type="boolean" dir="in">
|
---|
4731 | <desc>If VMM shall try to unbind existing drivers from the
|
---|
4732 | device before attaching it to the guest.</desc>
|
---|
4733 | </param>
|
---|
4734 | </method>
|
---|
4735 |
|
---|
4736 | <method name="detachHostPciDevice">
|
---|
4737 | <desc>
|
---|
4738 | Detach host PCI device from the virtual machine.
|
---|
4739 | Also HostPciDevicePlugEvent on IVirtualBox event source
|
---|
4740 | will be delivered. As currently we don't support hot device
|
---|
4741 | unplug, IHostPciDevicePlugEvent event is delivered immediately.
|
---|
4742 |
|
---|
4743 | <see>IHostPciDevicePlugEvent</see>
|
---|
4744 |
|
---|
4745 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4746 | Virtual machine state is not stopped (PCI hotplug not yet implemented).
|
---|
4747 | </result>
|
---|
4748 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4749 | This host device is not attached to this machine.
|
---|
4750 | </result>
|
---|
4751 | <result name="VBOX_E_PDM_ERROR">
|
---|
4752 | Virtual machine does not have a PCI controller allowing attachment of physical devices.
|
---|
4753 | </result>
|
---|
4754 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
4755 | Hardware or host OS doesn't allow PCI device passthrought.
|
---|
4756 | </result>
|
---|
4757 | </desc>
|
---|
4758 | <param name="hostAddress" type="long" dir="in">
|
---|
4759 | <desc>Address of the host PCI device.</desc>
|
---|
4760 | </param>
|
---|
4761 | </method>
|
---|
4762 |
|
---|
4763 | <method name="getNetworkAdapter" const="yes">
|
---|
4764 | <desc>
|
---|
4765 | Returns the network adapter associated with the given slot.
|
---|
4766 | Slots are numbered sequentially, starting with zero. The total
|
---|
4767 | number of adapters per machine is defined by the
|
---|
4768 | <link to="ISystemProperties::getMaxNetworkAdapters"/> property,
|
---|
4769 | so the maximum slot number is one less than that property's value.
|
---|
4770 |
|
---|
4771 | <result name="E_INVALIDARG">
|
---|
4772 | Invalid @a slot number.
|
---|
4773 | </result>
|
---|
4774 |
|
---|
4775 | </desc>
|
---|
4776 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4777 | <param name="adapter" type="INetworkAdapter" dir="return"/>
|
---|
4778 | </method>
|
---|
4779 |
|
---|
4780 | <method name="addStorageController">
|
---|
4781 | <desc>
|
---|
4782 | Adds a new storage controller (SCSI, SAS or SATA controller) to the
|
---|
4783 | machine and returns it as an instance of
|
---|
4784 | <link to="IStorageController" />.
|
---|
4785 |
|
---|
4786 | @a name identifies the controller for subsequent calls such as
|
---|
4787 | <link to="#getStorageControllerByName" />,
|
---|
4788 | <link to="#getStorageControllerByInstance" />,
|
---|
4789 | <link to="#removeStorageController" />,
|
---|
4790 | <link to="#attachDevice" /> or <link to="#mountMedium" />.
|
---|
4791 |
|
---|
4792 | After the controller has been added, you can set its exact
|
---|
4793 | type by setting the <link to="IStorageController::controllerType" />.
|
---|
4794 |
|
---|
4795 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4796 | A storage controller with given name exists already.
|
---|
4797 | </result>
|
---|
4798 | <result name="E_INVALIDARG">
|
---|
4799 | Invalid @a controllerType.
|
---|
4800 | </result>
|
---|
4801 | </desc>
|
---|
4802 | <param name="name" type="wstring" dir="in"/>
|
---|
4803 | <param name="connectionType" type="StorageBus" dir="in"/>
|
---|
4804 | <param name="controller" type="IStorageController" dir="return"/>
|
---|
4805 | </method>
|
---|
4806 |
|
---|
4807 | <method name="getStorageControllerByName" const="yes">
|
---|
4808 | <desc>
|
---|
4809 | Returns a storage controller with the given name.
|
---|
4810 |
|
---|
4811 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4812 | A storage controller with given name doesn't exist.
|
---|
4813 | </result>
|
---|
4814 | </desc>
|
---|
4815 | <param name="name" type="wstring" dir="in"/>
|
---|
4816 | <param name="storageController" type="IStorageController" dir="return"/>
|
---|
4817 | </method>
|
---|
4818 |
|
---|
4819 | <method name="getStorageControllerByInstance" const="yes">
|
---|
4820 | <desc>
|
---|
4821 | Returns a storage controller with the given instance number.
|
---|
4822 |
|
---|
4823 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4824 | A storage controller with given instance number doesn't exist.
|
---|
4825 | </result>
|
---|
4826 | </desc>
|
---|
4827 | <param name="instance" type="unsigned long" dir="in"/>
|
---|
4828 | <param name="storageController" type="IStorageController" dir="return"/>
|
---|
4829 | </method>
|
---|
4830 |
|
---|
4831 | <method name="removeStorageController">
|
---|
4832 | <desc>
|
---|
4833 | Removes a storage controller from the machine.
|
---|
4834 |
|
---|
4835 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4836 | A storage controller with given name doesn't exist.
|
---|
4837 | </result>
|
---|
4838 | </desc>
|
---|
4839 | <param name="name" type="wstring" dir="in"/>
|
---|
4840 | </method>
|
---|
4841 |
|
---|
4842 | <method name="setStorageControllerBootable">
|
---|
4843 | <desc>
|
---|
4844 | Sets the bootable flag of the storage controller with the given name.
|
---|
4845 |
|
---|
4846 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4847 | A storage controller with given name doesn't exist.
|
---|
4848 | </result>
|
---|
4849 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4850 | Another storage controller is marked as bootable already.
|
---|
4851 | </result>
|
---|
4852 | </desc>
|
---|
4853 | <param name="name" type="wstring" dir="in"/>
|
---|
4854 | <param name="bootable" type="boolean" dir="in"/>
|
---|
4855 | </method>
|
---|
4856 |
|
---|
4857 | <method name="getSerialPort" const="yes">
|
---|
4858 | <desc>
|
---|
4859 | Returns the serial port associated with the given slot.
|
---|
4860 | Slots are numbered sequentially, starting with zero. The total
|
---|
4861 | number of serial ports per machine is defined by the
|
---|
4862 | <link to="ISystemProperties::serialPortCount"/> property,
|
---|
4863 | so the maximum slot number is one less than that property's value.
|
---|
4864 |
|
---|
4865 | <result name="E_INVALIDARG">
|
---|
4866 | Invalid @a slot number.
|
---|
4867 | </result>
|
---|
4868 |
|
---|
4869 | </desc>
|
---|
4870 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4871 | <param name="port" type="ISerialPort" dir="return"/>
|
---|
4872 | </method>
|
---|
4873 |
|
---|
4874 | <method name="getParallelPort" const="yes">
|
---|
4875 | <desc>
|
---|
4876 | Returns the parallel port associated with the given slot.
|
---|
4877 | Slots are numbered sequentially, starting with zero. The total
|
---|
4878 | number of parallel ports per machine is defined by the
|
---|
4879 | <link to="ISystemProperties::parallelPortCount"/> property,
|
---|
4880 | so the maximum slot number is one less than that property's value.
|
---|
4881 |
|
---|
4882 | <result name="E_INVALIDARG">
|
---|
4883 | Invalid @a slot number.
|
---|
4884 | </result>
|
---|
4885 |
|
---|
4886 | </desc>
|
---|
4887 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4888 | <param name="port" type="IParallelPort" dir="return"/>
|
---|
4889 | </method>
|
---|
4890 |
|
---|
4891 | <method name="getExtraDataKeys">
|
---|
4892 | <desc>
|
---|
4893 | Returns an array representing the machine-specific extra data keys
|
---|
4894 | which currently have values defined.
|
---|
4895 | </desc>
|
---|
4896 | <param name="value" type="wstring" dir="return" safearray="yes">
|
---|
4897 | <desc>Array of extra data keys.</desc>
|
---|
4898 | </param>
|
---|
4899 | </method>
|
---|
4900 |
|
---|
4901 | <method name="getExtraData">
|
---|
4902 | <desc>
|
---|
4903 | Returns associated machine-specific extra data.
|
---|
4904 |
|
---|
4905 | If the requested data @a key does not exist, this function will
|
---|
4906 | succeed and return an empty string in the @a value argument.
|
---|
4907 |
|
---|
4908 | <result name="VBOX_E_FILE_ERROR">
|
---|
4909 | Settings file not accessible.
|
---|
4910 | </result>
|
---|
4911 | <result name="VBOX_E_XML_ERROR">
|
---|
4912 | Could not parse the settings file.
|
---|
4913 | </result>
|
---|
4914 |
|
---|
4915 | </desc>
|
---|
4916 | <param name="key" type="wstring" dir="in">
|
---|
4917 | <desc>Name of the data key to get.</desc>
|
---|
4918 | </param>
|
---|
4919 | <param name="value" type="wstring" dir="return">
|
---|
4920 | <desc>Value of the requested data key.</desc>
|
---|
4921 | </param>
|
---|
4922 | </method>
|
---|
4923 |
|
---|
4924 | <method name="setExtraData">
|
---|
4925 | <desc>
|
---|
4926 | Sets associated machine-specific extra data.
|
---|
4927 |
|
---|
4928 | If you pass @c null or an empty string as a key @a value, the given
|
---|
4929 | @a key will be deleted.
|
---|
4930 |
|
---|
4931 | <note>
|
---|
4932 | Before performing the actual data change, this method will ask all
|
---|
4933 | registered listeners using the
|
---|
4934 | <link to="IExtraDataCanChangeEvent"/>
|
---|
4935 | notification for a permission. If one of the listeners refuses the
|
---|
4936 | new value, the change will not be performed.
|
---|
4937 | </note>
|
---|
4938 | <note>
|
---|
4939 | On success, the
|
---|
4940 | <link to="IExtraDataChangedEvent"/> notification
|
---|
4941 | is called to inform all registered listeners about a successful data
|
---|
4942 | change.
|
---|
4943 | </note>
|
---|
4944 | <note>
|
---|
4945 | This method can be called outside the machine session and therefore
|
---|
4946 | it's a caller's responsibility to handle possible race conditions
|
---|
4947 | when several clients change the same key at the same time.
|
---|
4948 | </note>
|
---|
4949 |
|
---|
4950 | <result name="VBOX_E_FILE_ERROR">
|
---|
4951 | Settings file not accessible.
|
---|
4952 | </result>
|
---|
4953 | <result name="VBOX_E_XML_ERROR">
|
---|
4954 | Could not parse the settings file.
|
---|
4955 | </result>
|
---|
4956 |
|
---|
4957 | </desc>
|
---|
4958 | <param name="key" type="wstring" dir="in">
|
---|
4959 | <desc>Name of the data key to set.</desc>
|
---|
4960 | </param>
|
---|
4961 | <param name="value" type="wstring" dir="in">
|
---|
4962 | <desc>Value to assign to the key.</desc>
|
---|
4963 | </param>
|
---|
4964 | </method>
|
---|
4965 |
|
---|
4966 | <method name="getCPUProperty" const="yes">
|
---|
4967 | <desc>
|
---|
4968 | Returns the virtual CPU boolean value of the specified property.
|
---|
4969 |
|
---|
4970 | <result name="E_INVALIDARG">
|
---|
4971 | Invalid property.
|
---|
4972 | </result>
|
---|
4973 |
|
---|
4974 | </desc>
|
---|
4975 | <param name="property" type="CPUPropertyType" dir="in">
|
---|
4976 | <desc>
|
---|
4977 | Property type to query.
|
---|
4978 | </desc>
|
---|
4979 | </param>
|
---|
4980 | <param name="value" type="boolean" dir="return">
|
---|
4981 | <desc>
|
---|
4982 | Property value.
|
---|
4983 | </desc>
|
---|
4984 | </param>
|
---|
4985 | </method>
|
---|
4986 |
|
---|
4987 | <method name="setCPUProperty">
|
---|
4988 | <desc>
|
---|
4989 | Sets the virtual CPU boolean value of the specified property.
|
---|
4990 |
|
---|
4991 | <result name="E_INVALIDARG">
|
---|
4992 | Invalid property.
|
---|
4993 | </result>
|
---|
4994 |
|
---|
4995 | </desc>
|
---|
4996 | <param name="property" type="CPUPropertyType" dir="in">
|
---|
4997 | <desc>
|
---|
4998 | Property type to query.
|
---|
4999 | </desc>
|
---|
5000 | </param>
|
---|
5001 | <param name="value" type="boolean" dir="in">
|
---|
5002 | <desc>
|
---|
5003 | Property value.
|
---|
5004 | </desc>
|
---|
5005 | </param>
|
---|
5006 | </method>
|
---|
5007 |
|
---|
5008 | <method name="getCPUIDLeaf" const="yes">
|
---|
5009 | <desc>
|
---|
5010 | Returns the virtual CPU cpuid information for the specified leaf.
|
---|
5011 |
|
---|
5012 | Currently supported index values for cpuid:
|
---|
5013 | Standard CPUID leafs: 0 - 0xA
|
---|
5014 | Extended CPUID leafs: 0x80000000 - 0x8000000A
|
---|
5015 |
|
---|
5016 | See the Intel and AMD programmer's manuals for detailed information
|
---|
5017 | about the cpuid instruction and its leafs.
|
---|
5018 | <result name="E_INVALIDARG">
|
---|
5019 | Invalid id.
|
---|
5020 | </result>
|
---|
5021 |
|
---|
5022 | </desc>
|
---|
5023 | <param name="id" type="unsigned long" dir="in">
|
---|
5024 | <desc>
|
---|
5025 | CPUID leaf index.
|
---|
5026 | </desc>
|
---|
5027 | </param>
|
---|
5028 | <param name="valEax" type="unsigned long" dir="out">
|
---|
5029 | <desc>
|
---|
5030 | CPUID leaf value for register eax.
|
---|
5031 | </desc>
|
---|
5032 | </param>
|
---|
5033 | <param name="valEbx" type="unsigned long" dir="out">
|
---|
5034 | <desc>
|
---|
5035 | CPUID leaf value for register ebx.
|
---|
5036 | </desc>
|
---|
5037 | </param>
|
---|
5038 | <param name="valEcx" type="unsigned long" dir="out">
|
---|
5039 | <desc>
|
---|
5040 | CPUID leaf value for register ecx.
|
---|
5041 | </desc>
|
---|
5042 | </param>
|
---|
5043 | <param name="valEdx" type="unsigned long" dir="out">
|
---|
5044 | <desc>
|
---|
5045 | CPUID leaf value for register edx.
|
---|
5046 | </desc>
|
---|
5047 | </param>
|
---|
5048 | </method>
|
---|
5049 |
|
---|
5050 | <method name="setCPUIDLeaf">
|
---|
5051 | <desc>
|
---|
5052 | Sets the virtual CPU cpuid information for the specified leaf. Note that these values
|
---|
5053 | are not passed unmodified. VirtualBox clears features that it doesn't support.
|
---|
5054 |
|
---|
5055 | Currently supported index values for cpuid:
|
---|
5056 | Standard CPUID leafs: 0 - 0xA
|
---|
5057 | Extended CPUID leafs: 0x80000000 - 0x8000000A
|
---|
5058 |
|
---|
5059 | See the Intel and AMD programmer's manuals for detailed information
|
---|
5060 | about the cpuid instruction and its leafs.
|
---|
5061 |
|
---|
5062 | Do not use this method unless you know exactly what you're doing. Misuse can lead to
|
---|
5063 | random crashes inside VMs.
|
---|
5064 | <result name="E_INVALIDARG">
|
---|
5065 | Invalid id.
|
---|
5066 | </result>
|
---|
5067 |
|
---|
5068 | </desc>
|
---|
5069 | <param name="id" type="unsigned long" dir="in">
|
---|
5070 | <desc>
|
---|
5071 | CPUID leaf index.
|
---|
5072 | </desc>
|
---|
5073 | </param>
|
---|
5074 | <param name="valEax" type="unsigned long" dir="in">
|
---|
5075 | <desc>
|
---|
5076 | CPUID leaf value for register eax.
|
---|
5077 | </desc>
|
---|
5078 | </param>
|
---|
5079 | <param name="valEbx" type="unsigned long" dir="in">
|
---|
5080 | <desc>
|
---|
5081 | CPUID leaf value for register ebx.
|
---|
5082 | </desc>
|
---|
5083 | </param>
|
---|
5084 | <param name="valEcx" type="unsigned long" dir="in">
|
---|
5085 | <desc>
|
---|
5086 | CPUID leaf value for register ecx.
|
---|
5087 | </desc>
|
---|
5088 | </param>
|
---|
5089 | <param name="valEdx" type="unsigned long" dir="in">
|
---|
5090 | <desc>
|
---|
5091 | CPUID leaf value for register edx.
|
---|
5092 | </desc>
|
---|
5093 | </param>
|
---|
5094 | </method>
|
---|
5095 |
|
---|
5096 | <method name="removeCPUIDLeaf">
|
---|
5097 | <desc>
|
---|
5098 | Removes the virtual CPU cpuid leaf for the specified index
|
---|
5099 |
|
---|
5100 | <result name="E_INVALIDARG">
|
---|
5101 | Invalid id.
|
---|
5102 | </result>
|
---|
5103 |
|
---|
5104 | </desc>
|
---|
5105 | <param name="id" type="unsigned long" dir="in">
|
---|
5106 | <desc>
|
---|
5107 | CPUID leaf index.
|
---|
5108 | </desc>
|
---|
5109 | </param>
|
---|
5110 | </method>
|
---|
5111 |
|
---|
5112 | <method name="removeAllCPUIDLeaves">
|
---|
5113 | <desc>
|
---|
5114 | Removes all the virtual CPU cpuid leaves
|
---|
5115 | </desc>
|
---|
5116 | </method>
|
---|
5117 |
|
---|
5118 | <method name="getHWVirtExProperty" const="yes">
|
---|
5119 | <desc>
|
---|
5120 | Returns the value of the specified hardware virtualization boolean property.
|
---|
5121 |
|
---|
5122 | <result name="E_INVALIDARG">
|
---|
5123 | Invalid property.
|
---|
5124 | </result>
|
---|
5125 |
|
---|
5126 | </desc>
|
---|
5127 | <param name="property" type="HWVirtExPropertyType" dir="in">
|
---|
5128 | <desc>
|
---|
5129 | Property type to query.
|
---|
5130 | </desc>
|
---|
5131 | </param>
|
---|
5132 | <param name="value" type="boolean" dir="return">
|
---|
5133 | <desc>
|
---|
5134 | Property value.
|
---|
5135 | </desc>
|
---|
5136 | </param>
|
---|
5137 | </method>
|
---|
5138 |
|
---|
5139 | <method name="setHWVirtExProperty">
|
---|
5140 | <desc>
|
---|
5141 | Sets a new value for the specified hardware virtualization boolean property.
|
---|
5142 |
|
---|
5143 | <result name="E_INVALIDARG">
|
---|
5144 | Invalid property.
|
---|
5145 | </result>
|
---|
5146 |
|
---|
5147 | </desc>
|
---|
5148 | <param name="property" type="HWVirtExPropertyType" dir="in">
|
---|
5149 | <desc>
|
---|
5150 | Property type to set.
|
---|
5151 | </desc>
|
---|
5152 | </param>
|
---|
5153 | <param name="value" type="boolean" dir="in">
|
---|
5154 | <desc>
|
---|
5155 | New property value.
|
---|
5156 | </desc>
|
---|
5157 | </param>
|
---|
5158 | </method>
|
---|
5159 |
|
---|
5160 | <method name="saveSettings">
|
---|
5161 | <desc>
|
---|
5162 | Saves any changes to machine settings made since the session
|
---|
5163 | has been opened or a new machine has been created, or since the
|
---|
5164 | last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
|
---|
5165 | For registered machines, new settings become visible to all
|
---|
5166 | other VirtualBox clients after successful invocation of this
|
---|
5167 | method.
|
---|
5168 | <note>
|
---|
5169 | The method sends <link to="IMachineDataChangedEvent"/>
|
---|
5170 | notification event after the configuration has been successfully
|
---|
5171 | saved (only for registered machines).
|
---|
5172 | </note>
|
---|
5173 | <note>
|
---|
5174 | Calling this method is only valid on instances returned
|
---|
5175 | by <link to="ISession::machine"/> and on new machines
|
---|
5176 | created by <link to="IVirtualBox::createMachine"/> but not
|
---|
5177 | yet registered, or on unregistered machines after calling
|
---|
5178 | <link to="IMachine::unregister"/>.
|
---|
5179 | </note>
|
---|
5180 |
|
---|
5181 | <result name="VBOX_E_FILE_ERROR">
|
---|
5182 | Settings file not accessible.
|
---|
5183 | </result>
|
---|
5184 | <result name="VBOX_E_XML_ERROR">
|
---|
5185 | Could not parse the settings file.
|
---|
5186 | </result>
|
---|
5187 | <result name="E_ACCESSDENIED">
|
---|
5188 | Modification request refused.
|
---|
5189 | </result>
|
---|
5190 |
|
---|
5191 | </desc>
|
---|
5192 | </method>
|
---|
5193 |
|
---|
5194 | <method name="discardSettings">
|
---|
5195 | <desc>
|
---|
5196 | Discards any changes to the machine settings made since the session
|
---|
5197 | has been opened or since the last call to <link to="#saveSettings"/>
|
---|
5198 | or <link to="#discardSettings"/>.
|
---|
5199 | <note>
|
---|
5200 | Calling this method is only valid on instances returned
|
---|
5201 | by <link to="ISession::machine"/> and on new machines
|
---|
5202 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
5203 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
5204 | yet registered, or on unregistered machines after calling
|
---|
5205 | <link to="IMachine::unregister"/>.
|
---|
5206 | </note>
|
---|
5207 |
|
---|
5208 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5209 | Virtual machine is not mutable.
|
---|
5210 | </result>
|
---|
5211 |
|
---|
5212 | </desc>
|
---|
5213 | </method>
|
---|
5214 |
|
---|
5215 | <method name="unregister">
|
---|
5216 | <desc>
|
---|
5217 | Unregisters a machine previously registered with
|
---|
5218 | <link to="IVirtualBox::registerMachine"/> and optionally do additional
|
---|
5219 | cleanup before the machine is unregistered.
|
---|
5220 |
|
---|
5221 | This method does not delete any files. It only changes the machine configuration and
|
---|
5222 | the list of registered machines in the VirtualBox object. To delete the files which
|
---|
5223 | belonged to the machine, including the XML file of the machine itself, call
|
---|
5224 | <link to="#delete"/>, optionally with the array of IMedium objects which was returned
|
---|
5225 | from this method.
|
---|
5226 |
|
---|
5227 | How thoroughly this method cleans up the machine configuration before unregistering
|
---|
5228 | the machine depends on the @a cleanupMode argument.
|
---|
5229 |
|
---|
5230 | <ul>
|
---|
5231 | <li>With "UnregisterOnly", the machine will only be unregistered, but no additional
|
---|
5232 | cleanup will be performed. The call will fail if the machine is in "Saved" state
|
---|
5233 | or has any snapshots or any media attached (see <link to="IMediumAttachment" />).
|
---|
5234 | It is the responsibility of the caller to delete all such configuration in this mode.
|
---|
5235 | In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
|
---|
5236 | which it replaces.</li>
|
---|
5237 | <li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
|
---|
5238 | state or if it has snapshots or media attached. All media attached to the current machine
|
---|
5239 | state or in snapshots will be detached. No medium objects will be returned;
|
---|
5240 | all of the machine's media will remain open.</li>
|
---|
5241 | <li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
|
---|
5242 | except that all the hard disk medium objects which were detached from the machine will
|
---|
5243 | be returned as an array. This allows for quickly passing them to the <link to="#delete" />
|
---|
5244 | API for closing and deletion.</li>
|
---|
5245 | <li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
|
---|
5246 | that all media will be returned in the array, including removable media like DVDs and
|
---|
5247 | floppies. This might be useful if the user wants to inspect in detail which media were
|
---|
5248 | attached to the machine. Be careful when passing the media array to <link to="#delete" />
|
---|
5249 | in that case because users will typically want to preserve ISO and RAW image files.</li>
|
---|
5250 | </ul>
|
---|
5251 |
|
---|
5252 | A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
|
---|
5253 | resulting IMedium array to <link to="#delete"/>. This way, the machine is completely
|
---|
5254 | deleted with all its saved states and hard disk images, but images for removable
|
---|
5255 | drives (such as ISO and RAW files) will remain on disk.
|
---|
5256 |
|
---|
5257 | This API does not verify whether the media files returned in the array are still
|
---|
5258 | attached to other machines (i.e. shared between several machines). If such a shared
|
---|
5259 | image is passed to <link to="#delete" /> however, closing the image will fail there
|
---|
5260 | and the image will be silently skipped.
|
---|
5261 |
|
---|
5262 | This API may, however, move media from this machine's media registry to other media
|
---|
5263 | registries (see <link to="IMedium" /> for details on media registries). For machines
|
---|
5264 | created with VirtualBox 4.0 or later, if media from this machine's media registry
|
---|
5265 | are also attached to another machine (shared attachments), each such medium will be
|
---|
5266 | moved to another machine's registry. This is because without this machine's media
|
---|
5267 | registry, the other machine cannot find its media any more and would become inaccessible.
|
---|
5268 |
|
---|
5269 | This API implicitly calls <link to="#saveSettings"/> to save all current machine settings
|
---|
5270 | before unregistering it. It may also silently call saveSettings() on other machines
|
---|
5271 | if media are moved to other machines' media registries.
|
---|
5272 |
|
---|
5273 | After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
|
---|
5274 | is fired.
|
---|
5275 |
|
---|
5276 | The call will fail if the machine is currently locked (see <link to="ISession" />).
|
---|
5277 |
|
---|
5278 | <note>
|
---|
5279 | If the given machine is inaccessible (see <link to="#accessible"/>), it
|
---|
5280 | will be unregistered and fully uninitialized right afterwards. As a result,
|
---|
5281 | the returned machine object will be unusable and an attempt to call
|
---|
5282 | <b>any</b> method will return the "Object not ready" error.
|
---|
5283 | </note>
|
---|
5284 |
|
---|
5285 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5286 | Machine is currently locked for a session.
|
---|
5287 | </result>
|
---|
5288 | </desc>
|
---|
5289 |
|
---|
5290 | <param name="cleanupMode" type="CleanupMode" dir="in">
|
---|
5291 | <desc>How to clean up after the machine has been unregistered.</desc>
|
---|
5292 | </param>
|
---|
5293 | <param name="aMedia" type="IMedium" safearray="yes" dir="return">
|
---|
5294 | <desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
|
---|
5295 | </param>
|
---|
5296 | </method>
|
---|
5297 |
|
---|
5298 | <method name="delete">
|
---|
5299 | <desc>
|
---|
5300 | Deletes the files associated with this machine from disk. If medium objects are passed
|
---|
5301 | in with the @a aMedia argument, they are closed and, if closing was successful, their
|
---|
5302 | storage files are deleted as well. For convenience, this array of media files can be
|
---|
5303 | the same as the one returned from a previous <link to="#unregister" /> call.
|
---|
5304 |
|
---|
5305 | This method must only be called on machines which are either write-locked (i.e. on instances
|
---|
5306 | returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
|
---|
5307 | registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
|
---|
5308 | <link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
|
---|
5309 |
|
---|
5310 | The following files will be deleted by this method:
|
---|
5311 | <ul>
|
---|
5312 | <li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
|
---|
5313 | argument other than "UnregisterOnly", this will delete all saved state files that
|
---|
5314 | the machine had in use; possibly one if the machine was in "Saved" state and one
|
---|
5315 | for each online snapshot that the machine had.</li>
|
---|
5316 | <li>On each medium object passed in the @a aMedia array, this will call
|
---|
5317 | <link to="IMedium::close" />. If that succeeds, this will attempt to delete the
|
---|
5318 | medium's storage on disk. Since the close() call will fail if the medium is still
|
---|
5319 | in use, e.g. because it is still attached to a second machine; in that case the
|
---|
5320 | storage will not be deleted.</li>
|
---|
5321 | <li>Finally, the machine's own XML file will be deleted.</li>
|
---|
5322 | </ul>
|
---|
5323 |
|
---|
5324 | Since deleting large disk image files can be a time-consuming I/O operation, this
|
---|
5325 | method operates asynchronously and returns an IProgress object to allow the caller
|
---|
5326 | to monitor the progress. There will be one sub-operation for each file that is
|
---|
5327 | being deleted (saved state or medium storage file).
|
---|
5328 |
|
---|
5329 | <note>
|
---|
5330 | <link to="#settingsModified"/> will return @c true after this
|
---|
5331 | method successfully returns.
|
---|
5332 | </note>
|
---|
5333 |
|
---|
5334 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5335 | Machine is registered but not write-locked.
|
---|
5336 | </result>
|
---|
5337 | <result name="VBOX_E_IPRT_ERROR">
|
---|
5338 | Could not delete the settings file.
|
---|
5339 | </result>
|
---|
5340 | </desc>
|
---|
5341 | <param name="aMedia" type="IMedium" safearray="yes" dir="in">
|
---|
5342 | <desc>List of media to be closed and whose storage files will be deleted.</desc>
|
---|
5343 | </param>
|
---|
5344 | <param name="aProgress" type="IProgress" dir="return">
|
---|
5345 | <desc>Progress object to track the operation completion.</desc>
|
---|
5346 | </param>
|
---|
5347 | </method>
|
---|
5348 |
|
---|
5349 | <method name="export">
|
---|
5350 | <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
|
---|
5351 | steps required to export VirtualBox machines to OVF.
|
---|
5352 | </desc>
|
---|
5353 |
|
---|
5354 | <param name="aAppliance" type="IAppliance" dir="in">
|
---|
5355 | <desc>Appliance to export this machine to.</desc>
|
---|
5356 | </param>
|
---|
5357 | <param name="location" type="wstring" dir="in">
|
---|
5358 | <desc>The target location.</desc>
|
---|
5359 | </param>
|
---|
5360 | <param name="aDescription" type="IVirtualSystemDescription" dir="return">
|
---|
5361 | <desc>VirtualSystemDescription object which is created for this machine.</desc>
|
---|
5362 | </param>
|
---|
5363 | </method >
|
---|
5364 |
|
---|
5365 | <method name="findSnapshot">
|
---|
5366 | <desc>
|
---|
5367 | Returns a snapshot of this machine with the given name or UUID.
|
---|
5368 |
|
---|
5369 | Returns a snapshot of this machine with the given UUID.
|
---|
5370 | A @c null argument can be used to obtain the first snapshot
|
---|
5371 | taken on this machine. To traverse the whole tree of snapshots
|
---|
5372 | starting from the root, inspect the root snapshot's
|
---|
5373 | <link to="ISnapshot::children" /> attribute and recurse over those children.
|
---|
5374 |
|
---|
5375 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5376 | Virtual machine has no snapshots or snapshot not found.
|
---|
5377 | </result>
|
---|
5378 |
|
---|
5379 | </desc>
|
---|
5380 | <param name="nameOrId" type="wstring" dir="in">
|
---|
5381 | <desc>What to search for. Name or UUID of the snapshot to find</desc>
|
---|
5382 | </param>
|
---|
5383 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
5384 | <desc>Snapshot object with the given name.</desc>
|
---|
5385 | </param>
|
---|
5386 | </method>
|
---|
5387 |
|
---|
5388 | <method name="createSharedFolder">
|
---|
5389 | <desc>
|
---|
5390 | Creates a new permanent shared folder by associating the given logical
|
---|
5391 | name with the given host path, adds it to the collection of shared
|
---|
5392 | folders and starts sharing it. Refer to the description of
|
---|
5393 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
5394 |
|
---|
5395 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
5396 | Shared folder already exists.
|
---|
5397 | </result>
|
---|
5398 | <result name="VBOX_E_FILE_ERROR">
|
---|
5399 | Shared folder @a hostPath not accessible.
|
---|
5400 | </result>
|
---|
5401 |
|
---|
5402 | </desc>
|
---|
5403 | <param name="name" type="wstring" dir="in">
|
---|
5404 | <desc>Unique logical name of the shared folder.</desc>
|
---|
5405 | </param>
|
---|
5406 | <param name="hostPath" type="wstring" dir="in">
|
---|
5407 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
5408 | </param>
|
---|
5409 | <param name="writable" type="boolean" dir="in">
|
---|
5410 | <desc>Whether the share is writable or readonly.</desc>
|
---|
5411 | </param>
|
---|
5412 | <param name="automount" type="boolean" dir="in">
|
---|
5413 | <desc>Whether the share gets automatically mounted by the guest
|
---|
5414 | or not.</desc>
|
---|
5415 | </param>
|
---|
5416 | </method>
|
---|
5417 |
|
---|
5418 | <method name="removeSharedFolder">
|
---|
5419 | <desc>
|
---|
5420 | Removes the permanent shared folder with the given name previously
|
---|
5421 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
5422 | shared folders and stops sharing it.
|
---|
5423 |
|
---|
5424 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5425 | Virtual machine is not mutable.
|
---|
5426 | </result>
|
---|
5427 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5428 | Shared folder @a name does not exist.
|
---|
5429 | </result>
|
---|
5430 |
|
---|
5431 | </desc>
|
---|
5432 | <param name="name" type="wstring" dir="in">
|
---|
5433 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
5434 | </param>
|
---|
5435 | </method>
|
---|
5436 |
|
---|
5437 | <method name="canShowConsoleWindow">
|
---|
5438 | <desc>
|
---|
5439 | Returns @c true if the VM console process can activate the
|
---|
5440 | console window and bring it to foreground on the desktop of
|
---|
5441 | the host PC.
|
---|
5442 | <note>
|
---|
5443 | This method will fail if a session for this machine is not
|
---|
5444 | currently open.
|
---|
5445 | </note>
|
---|
5446 |
|
---|
5447 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5448 | Machine session is not open.
|
---|
5449 | </result>
|
---|
5450 |
|
---|
5451 | </desc>
|
---|
5452 | <param name="canShow" type="boolean" dir="return">
|
---|
5453 | <desc>
|
---|
5454 | @c true if the console window can be shown and @c false otherwise.
|
---|
5455 | </desc>
|
---|
5456 | </param>
|
---|
5457 | </method>
|
---|
5458 |
|
---|
5459 | <method name="showConsoleWindow">
|
---|
5460 | <desc>
|
---|
5461 | Activates the console window and brings it to foreground on
|
---|
5462 | the desktop of the host PC. Many modern window managers on
|
---|
5463 | many platforms implement some sort of focus stealing
|
---|
5464 | prevention logic, so that it may be impossible to activate
|
---|
5465 | a window without the help of the currently active
|
---|
5466 | application. In this case, this method will return a non-zero
|
---|
5467 | identifier that represents the top-level window of the VM
|
---|
5468 | console process. The caller, if it represents a currently
|
---|
5469 | active process, is responsible to use this identifier (in a
|
---|
5470 | platform-dependent manner) to perform actual window
|
---|
5471 | activation.
|
---|
5472 | <note>
|
---|
5473 | This method will fail if a session for this machine is not
|
---|
5474 | currently open.
|
---|
5475 | </note>
|
---|
5476 |
|
---|
5477 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5478 | Machine session is not open.
|
---|
5479 | </result>
|
---|
5480 |
|
---|
5481 | </desc>
|
---|
5482 | <param name="winId" type="long long" dir="return">
|
---|
5483 | <desc>
|
---|
5484 | Platform-dependent identifier of the top-level VM console
|
---|
5485 | window, or zero if this method has performed all actions
|
---|
5486 | necessary to implement the <i>show window</i> semantics for
|
---|
5487 | the given platform and/or VirtualBox front-end.
|
---|
5488 | </desc>
|
---|
5489 | </param>
|
---|
5490 | </method>
|
---|
5491 |
|
---|
5492 | <method name="getGuestProperty" const="yes">
|
---|
5493 | <desc>
|
---|
5494 | Reads an entry from the machine's guest property store.
|
---|
5495 |
|
---|
5496 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5497 | Machine session is not open.
|
---|
5498 | </result>
|
---|
5499 |
|
---|
5500 | </desc>
|
---|
5501 | <param name="name" type="wstring" dir="in">
|
---|
5502 | <desc>
|
---|
5503 | The name of the property to read.
|
---|
5504 | </desc>
|
---|
5505 | </param>
|
---|
5506 | <param name="value" type="wstring" dir="out">
|
---|
5507 | <desc>
|
---|
5508 | The value of the property. If the property does not exist then this
|
---|
5509 | will be empty.
|
---|
5510 | </desc>
|
---|
5511 | </param>
|
---|
5512 | <param name="timestamp" type="long long" dir="out">
|
---|
5513 | <desc>
|
---|
5514 | The time at which the property was last modified, as seen by the
|
---|
5515 | server process.
|
---|
5516 | </desc>
|
---|
5517 | </param>
|
---|
5518 | <param name="flags" type="wstring" dir="out">
|
---|
5519 | <desc>
|
---|
5520 | Additional property parameters, passed as a comma-separated list of
|
---|
5521 | "name=value" type entries.
|
---|
5522 | </desc>
|
---|
5523 | </param>
|
---|
5524 | </method>
|
---|
5525 |
|
---|
5526 | <method name="getGuestPropertyValue" const="yes">
|
---|
5527 | <desc>
|
---|
5528 | Reads a value from the machine's guest property store.
|
---|
5529 |
|
---|
5530 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5531 | Machine session is not open.
|
---|
5532 | </result>
|
---|
5533 |
|
---|
5534 | </desc>
|
---|
5535 | <param name="property" type="wstring" dir="in">
|
---|
5536 | <desc>
|
---|
5537 | The name of the property to read.
|
---|
5538 | </desc>
|
---|
5539 | </param>
|
---|
5540 | <param name="value" type="wstring" dir="return">
|
---|
5541 | <desc>
|
---|
5542 | The value of the property. If the property does not exist then this
|
---|
5543 | will be empty.
|
---|
5544 | </desc>
|
---|
5545 | </param>
|
---|
5546 | </method>
|
---|
5547 |
|
---|
5548 | <method name="getGuestPropertyTimestamp" const="yes">
|
---|
5549 | <desc>
|
---|
5550 | Reads a property timestamp from the machine's guest property store.
|
---|
5551 |
|
---|
5552 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5553 | Machine session is not open.
|
---|
5554 | </result>
|
---|
5555 |
|
---|
5556 | </desc>
|
---|
5557 | <param name="property" type="wstring" dir="in">
|
---|
5558 | <desc>
|
---|
5559 | The name of the property to read.
|
---|
5560 | </desc>
|
---|
5561 | </param>
|
---|
5562 | <param name="value" type="long long" dir="return">
|
---|
5563 | <desc>
|
---|
5564 | The timestamp. If the property does not exist then this will be
|
---|
5565 | empty.
|
---|
5566 | </desc>
|
---|
5567 | </param>
|
---|
5568 | </method>
|
---|
5569 |
|
---|
5570 | <method name="setGuestProperty">
|
---|
5571 | <desc>
|
---|
5572 | Sets, changes or deletes an entry in the machine's guest property
|
---|
5573 | store.
|
---|
5574 |
|
---|
5575 | <result name="E_ACCESSDENIED">
|
---|
5576 | Property cannot be changed.
|
---|
5577 | </result>
|
---|
5578 | <result name="E_INVALIDARG">
|
---|
5579 | Invalid @a flags.
|
---|
5580 | </result>
|
---|
5581 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5582 | Virtual machine is not mutable or session not open.
|
---|
5583 | </result>
|
---|
5584 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5585 | Cannot set transient property when machine not running.
|
---|
5586 | </result>
|
---|
5587 |
|
---|
5588 | </desc>
|
---|
5589 | <param name="property" type="wstring" dir="in">
|
---|
5590 | <desc>
|
---|
5591 | The name of the property to set, change or delete.
|
---|
5592 | </desc>
|
---|
5593 | </param>
|
---|
5594 | <param name="value" type="wstring" dir="in">
|
---|
5595 | <desc>
|
---|
5596 | The new value of the property to set, change or delete. If the
|
---|
5597 | property does not yet exist and value is non-empty, it will be
|
---|
5598 | created. If the value is @c null or empty, the property will be
|
---|
5599 | deleted if it exists.
|
---|
5600 | </desc>
|
---|
5601 | </param>
|
---|
5602 | <param name="flags" type="wstring" dir="in">
|
---|
5603 | <desc>
|
---|
5604 | Additional property parameters, passed as a comma-separated list of
|
---|
5605 | "name=value" type entries.
|
---|
5606 | </desc>
|
---|
5607 | </param>
|
---|
5608 | </method>
|
---|
5609 |
|
---|
5610 | <method name="setGuestPropertyValue">
|
---|
5611 | <desc>
|
---|
5612 | Sets, changes or deletes a value in the machine's guest property
|
---|
5613 | store. The flags field will be left unchanged or created empty for a
|
---|
5614 | new property.
|
---|
5615 |
|
---|
5616 | <result name="E_ACCESSDENIED">
|
---|
5617 | Property cannot be changed.
|
---|
5618 | </result>
|
---|
5619 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5620 | Virtual machine is not mutable or session not open.
|
---|
5621 | </result>
|
---|
5622 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5623 | Cannot set transient property when machine not running.
|
---|
5624 | </result>
|
---|
5625 | </desc>
|
---|
5626 |
|
---|
5627 | <param name="property" type="wstring" dir="in">
|
---|
5628 | <desc>
|
---|
5629 | The name of the property to set, change or delete.
|
---|
5630 | </desc>
|
---|
5631 | </param>
|
---|
5632 | <param name="value" type="wstring" dir="in">
|
---|
5633 | <desc>
|
---|
5634 | The new value of the property to set, change or delete. If the
|
---|
5635 | property does not yet exist and value is non-empty, it will be
|
---|
5636 | created. If the value is @c null or empty, the property will be
|
---|
5637 | deleted if it exists.
|
---|
5638 | </desc>
|
---|
5639 | </param>
|
---|
5640 | </method>
|
---|
5641 |
|
---|
5642 | <method name="enumerateGuestProperties">
|
---|
5643 | <desc>
|
---|
5644 | Return a list of the guest properties matching a set of patterns along
|
---|
5645 | with their values, time stamps and flags.
|
---|
5646 | </desc>
|
---|
5647 | <param name="patterns" type="wstring" dir="in">
|
---|
5648 | <desc>
|
---|
5649 | The patterns to match the properties against, separated by '|'
|
---|
5650 | characters. If this is empty or @c null, all properties will match.
|
---|
5651 | </desc>
|
---|
5652 | </param>
|
---|
5653 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
5654 | <desc>
|
---|
5655 | The names of the properties returned.
|
---|
5656 | </desc>
|
---|
5657 | </param>
|
---|
5658 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
5659 | <desc>
|
---|
5660 | The values of the properties returned. The array entries match the
|
---|
5661 | corresponding entries in the @a name array.
|
---|
5662 | </desc>
|
---|
5663 | </param>
|
---|
5664 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
5665 | <desc>
|
---|
5666 | The time stamps of the properties returned. The array entries match
|
---|
5667 | the corresponding entries in the @a name array.
|
---|
5668 | </desc>
|
---|
5669 | </param>
|
---|
5670 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
5671 | <desc>
|
---|
5672 | The flags of the properties returned. The array entries match the
|
---|
5673 | corresponding entries in the @a name array.
|
---|
5674 | </desc>
|
---|
5675 | </param>
|
---|
5676 | </method>
|
---|
5677 |
|
---|
5678 | <method name="querySavedGuestSize">
|
---|
5679 | <desc>
|
---|
5680 | Returns the guest dimensions from the saved state.
|
---|
5681 | </desc>
|
---|
5682 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5683 | <desc>
|
---|
5684 | Saved guest screen to query info from.
|
---|
5685 | </desc>
|
---|
5686 | </param>
|
---|
5687 | <param name="width" type="unsigned long" dir="out">
|
---|
5688 | <desc>
|
---|
5689 | Guest width at the time of the saved state was taken.
|
---|
5690 | </desc>
|
---|
5691 | </param>
|
---|
5692 | <param name="height" type="unsigned long" dir="out">
|
---|
5693 | <desc>
|
---|
5694 | Guest height at the time of the saved state was taken.
|
---|
5695 | </desc>
|
---|
5696 | </param>
|
---|
5697 | </method>
|
---|
5698 |
|
---|
5699 | <method name="querySavedThumbnailSize">
|
---|
5700 | <desc>
|
---|
5701 | Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
|
---|
5702 | </desc>
|
---|
5703 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5704 | <desc>
|
---|
5705 | Saved guest screen to query info from.
|
---|
5706 | </desc>
|
---|
5707 | </param>
|
---|
5708 | <param name="size" type="unsigned long" dir="out">
|
---|
5709 | <desc>
|
---|
5710 | Size of buffer required to store the bitmap.
|
---|
5711 | </desc>
|
---|
5712 | </param>
|
---|
5713 | <param name="width" type="unsigned long" dir="out">
|
---|
5714 | <desc>
|
---|
5715 | Bitmap width.
|
---|
5716 | </desc>
|
---|
5717 | </param>
|
---|
5718 | <param name="height" type="unsigned long" dir="out">
|
---|
5719 | <desc>
|
---|
5720 | Bitmap height.
|
---|
5721 | </desc>
|
---|
5722 | </param>
|
---|
5723 | </method>
|
---|
5724 |
|
---|
5725 | <method name="readSavedThumbnailToArray">
|
---|
5726 | <desc>
|
---|
5727 | Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
|
---|
5728 | </desc>
|
---|
5729 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5730 | <desc>
|
---|
5731 | Saved guest screen to read from.
|
---|
5732 | </desc>
|
---|
5733 | </param>
|
---|
5734 | <param name="BGR" type="boolean" dir="in">
|
---|
5735 | <desc>
|
---|
5736 | How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
|
---|
5737 | bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
|
---|
5738 | </desc>
|
---|
5739 | </param>
|
---|
5740 | <param name="width" type="unsigned long" dir="out">
|
---|
5741 | <desc>
|
---|
5742 | Bitmap width.
|
---|
5743 | </desc>
|
---|
5744 | </param>
|
---|
5745 | <param name="height" type="unsigned long" dir="out">
|
---|
5746 | <desc>
|
---|
5747 | Bitmap height.
|
---|
5748 | </desc>
|
---|
5749 | </param>
|
---|
5750 | <param name="data" type="octet" safearray="yes" dir="return">
|
---|
5751 | <desc>
|
---|
5752 | Array with resulting bitmap data.
|
---|
5753 | </desc>
|
---|
5754 | </param>
|
---|
5755 | </method>
|
---|
5756 |
|
---|
5757 | <method name="readSavedThumbnailPNGToArray">
|
---|
5758 | <desc>
|
---|
5759 | Thumbnail in PNG format is retrieved to an array of bytes.
|
---|
5760 | </desc>
|
---|
5761 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5762 | <desc>
|
---|
5763 | Saved guest screen to read from.
|
---|
5764 | </desc>
|
---|
5765 | </param>
|
---|
5766 | <param name="width" type="unsigned long" dir="out">
|
---|
5767 | <desc>
|
---|
5768 | Image width.
|
---|
5769 | </desc>
|
---|
5770 | </param>
|
---|
5771 | <param name="height" type="unsigned long" dir="out">
|
---|
5772 | <desc>
|
---|
5773 | Image height.
|
---|
5774 | </desc>
|
---|
5775 | </param>
|
---|
5776 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5777 | <desc>
|
---|
5778 | Array with resulting PNG data.
|
---|
5779 | </desc>
|
---|
5780 | </param>
|
---|
5781 | </method>
|
---|
5782 |
|
---|
5783 | <method name="querySavedScreenshotPNGSize">
|
---|
5784 | <desc>
|
---|
5785 | Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
|
---|
5786 | </desc>
|
---|
5787 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5788 | <desc>
|
---|
5789 | Saved guest screen to query info from.
|
---|
5790 | </desc>
|
---|
5791 | </param>
|
---|
5792 | <param name="size" type="unsigned long" dir="out">
|
---|
5793 | <desc>
|
---|
5794 | Size of buffer required to store the PNG binary data.
|
---|
5795 | </desc>
|
---|
5796 | </param>
|
---|
5797 | <param name="width" type="unsigned long" dir="out">
|
---|
5798 | <desc>
|
---|
5799 | Image width.
|
---|
5800 | </desc>
|
---|
5801 | </param>
|
---|
5802 | <param name="height" type="unsigned long" dir="out">
|
---|
5803 | <desc>
|
---|
5804 | Image height.
|
---|
5805 | </desc>
|
---|
5806 | </param>
|
---|
5807 | </method>
|
---|
5808 |
|
---|
5809 | <method name="readSavedScreenshotPNGToArray">
|
---|
5810 | <desc>
|
---|
5811 | Screenshot in PNG format is retrieved to an array of bytes.
|
---|
5812 | </desc>
|
---|
5813 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5814 | <desc>
|
---|
5815 | Saved guest screen to read from.
|
---|
5816 | </desc>
|
---|
5817 | </param>
|
---|
5818 | <param name="width" type="unsigned long" dir="out">
|
---|
5819 | <desc>
|
---|
5820 | Image width.
|
---|
5821 | </desc>
|
---|
5822 | </param>
|
---|
5823 | <param name="height" type="unsigned long" dir="out">
|
---|
5824 | <desc>
|
---|
5825 | Image height.
|
---|
5826 | </desc>
|
---|
5827 | </param>
|
---|
5828 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5829 | <desc>
|
---|
5830 | Array with resulting PNG data.
|
---|
5831 | </desc>
|
---|
5832 | </param>
|
---|
5833 | </method>
|
---|
5834 |
|
---|
5835 | <method name="hotPlugCPU">
|
---|
5836 | <desc>
|
---|
5837 | Plugs a CPU into the machine.
|
---|
5838 | </desc>
|
---|
5839 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5840 | <desc>
|
---|
5841 | The CPU id to insert.
|
---|
5842 | </desc>
|
---|
5843 | </param>
|
---|
5844 | </method>
|
---|
5845 |
|
---|
5846 | <method name="hotUnplugCPU">
|
---|
5847 | <desc>
|
---|
5848 | Removes a CPU from the machine.
|
---|
5849 | </desc>
|
---|
5850 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5851 | <desc>
|
---|
5852 | The CPU id to remove.
|
---|
5853 | </desc>
|
---|
5854 | </param>
|
---|
5855 | </method>
|
---|
5856 |
|
---|
5857 | <method name="getCPUStatus">
|
---|
5858 | <desc>
|
---|
5859 | Returns the current status of the given CPU.
|
---|
5860 | </desc>
|
---|
5861 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5862 | <desc>
|
---|
5863 | The CPU id to check for.
|
---|
5864 | </desc>
|
---|
5865 | </param>
|
---|
5866 | <param name="attached" type="boolean" dir="return">
|
---|
5867 | <desc>
|
---|
5868 | Status of the CPU.
|
---|
5869 | </desc>
|
---|
5870 | </param>
|
---|
5871 | </method>
|
---|
5872 |
|
---|
5873 | <method name="queryLogFilename">
|
---|
5874 | <desc>
|
---|
5875 | Queries for the VM log file name of an given index. Returns an empty
|
---|
5876 | string if a log file with that index doesn't exists.
|
---|
5877 | </desc>
|
---|
5878 | <param name="idx" type="unsigned long" dir="in">
|
---|
5879 | <desc>
|
---|
5880 | Which log file name to query. 0=current log file.
|
---|
5881 | </desc>
|
---|
5882 | </param>
|
---|
5883 | <param name="filename" type="wstring" dir="return">
|
---|
5884 | <desc>
|
---|
5885 | On return the full path to the log file or an empty string on error.
|
---|
5886 | </desc>
|
---|
5887 | </param>
|
---|
5888 | </method>
|
---|
5889 |
|
---|
5890 | <method name="readLog">
|
---|
5891 | <desc>
|
---|
5892 | Reads the VM log file. The chunk size is limited, so even if you
|
---|
5893 | ask for a big piece there might be less data returned.
|
---|
5894 | </desc>
|
---|
5895 | <param name="idx" type="unsigned long" dir="in">
|
---|
5896 | <desc>
|
---|
5897 | Which log file to read. 0=current log file.
|
---|
5898 | </desc>
|
---|
5899 | </param>
|
---|
5900 | <param name="offset" type="long long" dir="in">
|
---|
5901 | <desc>
|
---|
5902 | Offset in the log file.
|
---|
5903 | </desc>
|
---|
5904 | </param>
|
---|
5905 | <param name="size" type="long long" dir="in">
|
---|
5906 | <desc>
|
---|
5907 | Chunk size to read in the log file.
|
---|
5908 | </desc>
|
---|
5909 | </param>
|
---|
5910 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5911 | <desc>
|
---|
5912 | Data read from the log file. A data size of 0 means end of file
|
---|
5913 | if the requested chunk size was not 0. This is the unprocessed
|
---|
5914 | file data, i.e. the line ending style depends on the platform of
|
---|
5915 | the system the server is running on.
|
---|
5916 | </desc>
|
---|
5917 | </param>
|
---|
5918 | </method>
|
---|
5919 |
|
---|
5920 | <method name="cloneTo">
|
---|
5921 | <desc>
|
---|
5922 | Creates a clone of this machine, either as a full clone (which means
|
---|
5923 | creating independent copies of the hard disk media), or as a linked
|
---|
5924 | clone (which uses its own differencing media, sharing the parent media
|
---|
5925 | with the source machine).
|
---|
5926 |
|
---|
5927 | The target machine object must have been created previously with
|
---|
5928 | <link to="IVirtualBox::createMachine"/>, and all the settings will be
|
---|
5929 | transferred except the VM name, hardware UUID and the network card
|
---|
5930 | MAC addresses. These can be set after the clone operation if required.
|
---|
5931 | The operation is performed asynchronously, so the machine object will
|
---|
5932 | be not be usable until the @a progress object signals completion. If
|
---|
5933 | any step of the machine clone operation fails this will abort the
|
---|
5934 | operation. The result will be a machine which is not a complete clone.
|
---|
5935 | It is the responsibility of the caller to delete this incomplete
|
---|
5936 | machine if desired with <link to="#unregister"/> and/or
|
---|
5937 | <link to="#delete"/>.
|
---|
5938 |
|
---|
5939 | <result name="E_INVALIDARG">
|
---|
5940 | @a target is @c null.
|
---|
5941 | </result>
|
---|
5942 | </desc>
|
---|
5943 |
|
---|
5944 | <param name="target" type="IMachine" dir="in">
|
---|
5945 | <desc>Target machine object.</desc>
|
---|
5946 | </param>
|
---|
5947 | <param name="fullClone" type="boolean" dir="in">
|
---|
5948 | <desc>Selects whether a full or linked clone is created.</desc>
|
---|
5949 | </param>
|
---|
5950 | <param name="progress" type="IProgress" dir="return">
|
---|
5951 | <desc>Progress object to track the operation completion.</desc>
|
---|
5952 | </param>
|
---|
5953 | </method>
|
---|
5954 |
|
---|
5955 | </interface>
|
---|
5956 |
|
---|
5957 | <!--
|
---|
5958 | // IConsole
|
---|
5959 | /////////////////////////////////////////////////////////////////////////
|
---|
5960 | -->
|
---|
5961 |
|
---|
5962 | <interface
|
---|
5963 | name="IVRDEServerInfo" extends="$unknown"
|
---|
5964 | uuid="714434a1-58c3-4aab-9049-7652c5df113b"
|
---|
5965 | wsmap="struct"
|
---|
5966 | >
|
---|
5967 | <desc>
|
---|
5968 | Contains information about the remote desktop (VRDE) server capabilities and status.
|
---|
5969 | This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
|
---|
5970 | </desc>
|
---|
5971 |
|
---|
5972 | <attribute name="active" type="boolean" readonly="yes">
|
---|
5973 | <desc>
|
---|
5974 | Whether the remote desktop connection is active.
|
---|
5975 | </desc>
|
---|
5976 | </attribute>
|
---|
5977 |
|
---|
5978 | <attribute name="port" type="long" readonly="yes">
|
---|
5979 | <desc>
|
---|
5980 | VRDE server port number. If this property is equal to <tt>0</tt>, then
|
---|
5981 | the VRDE server failed to start, usually because there are no free IP
|
---|
5982 | ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
|
---|
5983 | server has not yet been started.
|
---|
5984 | </desc>
|
---|
5985 | </attribute>
|
---|
5986 |
|
---|
5987 | <attribute name="numberOfClients" type="unsigned long" readonly="yes">
|
---|
5988 | <desc>
|
---|
5989 | How many times a client connected.
|
---|
5990 | </desc>
|
---|
5991 | </attribute>
|
---|
5992 |
|
---|
5993 | <attribute name="beginTime" type="long long" readonly="yes">
|
---|
5994 | <desc>
|
---|
5995 | When the last connection was established, in milliseconds since 1970-01-01 UTC.
|
---|
5996 | </desc>
|
---|
5997 | </attribute>
|
---|
5998 |
|
---|
5999 | <attribute name="endTime" type="long long" readonly="yes">
|
---|
6000 | <desc>
|
---|
6001 | When the last connection was terminated or the current time, if
|
---|
6002 | connection is still active, in milliseconds since 1970-01-01 UTC.
|
---|
6003 | </desc>
|
---|
6004 | </attribute>
|
---|
6005 |
|
---|
6006 | <attribute name="bytesSent" type="long long" readonly="yes">
|
---|
6007 | <desc>
|
---|
6008 | How many bytes were sent in last or current, if still active, connection.
|
---|
6009 | </desc>
|
---|
6010 | </attribute>
|
---|
6011 |
|
---|
6012 | <attribute name="bytesSentTotal" type="long long" readonly="yes">
|
---|
6013 | <desc>
|
---|
6014 | How many bytes were sent in all connections.
|
---|
6015 | </desc>
|
---|
6016 | </attribute>
|
---|
6017 |
|
---|
6018 | <attribute name="bytesReceived" type="long long" readonly="yes">
|
---|
6019 | <desc>
|
---|
6020 | How many bytes were received in last or current, if still active, connection.
|
---|
6021 | </desc>
|
---|
6022 | </attribute>
|
---|
6023 |
|
---|
6024 | <attribute name="bytesReceivedTotal" type="long long" readonly="yes">
|
---|
6025 | <desc>
|
---|
6026 | How many bytes were received in all connections.
|
---|
6027 | </desc>
|
---|
6028 | </attribute>
|
---|
6029 |
|
---|
6030 | <attribute name="user" type="wstring" readonly="yes">
|
---|
6031 | <desc>
|
---|
6032 | Login user name supplied by the client.
|
---|
6033 | </desc>
|
---|
6034 | </attribute>
|
---|
6035 |
|
---|
6036 | <attribute name="domain" type="wstring" readonly="yes">
|
---|
6037 | <desc>
|
---|
6038 | Login domain name supplied by the client.
|
---|
6039 | </desc>
|
---|
6040 | </attribute>
|
---|
6041 |
|
---|
6042 | <attribute name="clientName" type="wstring" readonly="yes">
|
---|
6043 | <desc>
|
---|
6044 | The client name supplied by the client.
|
---|
6045 | </desc>
|
---|
6046 | </attribute>
|
---|
6047 |
|
---|
6048 | <attribute name="clientIP" type="wstring" readonly="yes">
|
---|
6049 | <desc>
|
---|
6050 | The IP address of the client.
|
---|
6051 | </desc>
|
---|
6052 | </attribute>
|
---|
6053 |
|
---|
6054 | <attribute name="clientVersion" type="unsigned long" readonly="yes">
|
---|
6055 | <desc>
|
---|
6056 | The client software version number.
|
---|
6057 | </desc>
|
---|
6058 | </attribute>
|
---|
6059 |
|
---|
6060 | <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
|
---|
6061 | <desc>
|
---|
6062 | Public key exchange method used when connection was established.
|
---|
6063 | Values: 0 - RDP4 public key exchange scheme.
|
---|
6064 | 1 - X509 certificates were sent to client.
|
---|
6065 | </desc>
|
---|
6066 | </attribute>
|
---|
6067 |
|
---|
6068 | </interface>
|
---|
6069 |
|
---|
6070 | <interface
|
---|
6071 | name="IConsole" extends="$unknown"
|
---|
6072 | uuid="515e8e8d-f932-4d8e-9f32-79a52aead882"
|
---|
6073 | wsmap="managed"
|
---|
6074 | >
|
---|
6075 | <desc>
|
---|
6076 | The IConsole interface represents an interface to control virtual
|
---|
6077 | machine execution.
|
---|
6078 |
|
---|
6079 | A console object gets created when a machine has been locked for a
|
---|
6080 | particular session (client process) using <link to="IMachine::lockMachine" />
|
---|
6081 | or <link to="IMachine::launchVMProcess"/>. The console object can
|
---|
6082 | then be found in the session's <link to="ISession::console" /> attribute.
|
---|
6083 |
|
---|
6084 | Methods of the IConsole interface allow the caller to query the current
|
---|
6085 | virtual machine execution state, pause the machine or power it down, save
|
---|
6086 | the machine state or take a snapshot, attach and detach removable media
|
---|
6087 | and so on.
|
---|
6088 |
|
---|
6089 | <see>ISession</see>
|
---|
6090 | </desc>
|
---|
6091 |
|
---|
6092 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
6093 | <desc>
|
---|
6094 | Machine object for this console session.
|
---|
6095 | <note>
|
---|
6096 | This is a convenience property, it has the same value as
|
---|
6097 | <link to="ISession::machine"/> of the corresponding session
|
---|
6098 | object.
|
---|
6099 | </note>
|
---|
6100 | </desc>
|
---|
6101 | </attribute>
|
---|
6102 |
|
---|
6103 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
6104 | <desc>
|
---|
6105 | Current execution state of the machine.
|
---|
6106 | <note>
|
---|
6107 | This property always returns the same value as the corresponding
|
---|
6108 | property of the IMachine object for this console session.
|
---|
6109 | For the process that owns (executes) the VM, this is the
|
---|
6110 | preferable way of querying the VM state, because no IPC
|
---|
6111 | calls are made.
|
---|
6112 | </note>
|
---|
6113 | </desc>
|
---|
6114 | </attribute>
|
---|
6115 |
|
---|
6116 | <attribute name="guest" type="IGuest" readonly="yes">
|
---|
6117 | <desc>Guest object.</desc>
|
---|
6118 | </attribute>
|
---|
6119 |
|
---|
6120 | <attribute name="keyboard" type="IKeyboard" readonly="yes">
|
---|
6121 | <desc>
|
---|
6122 | Virtual keyboard object.
|
---|
6123 | <note>
|
---|
6124 | If the machine is not running, any attempt to use
|
---|
6125 | the returned object will result in an error.
|
---|
6126 | </note>
|
---|
6127 | </desc>
|
---|
6128 | </attribute>
|
---|
6129 |
|
---|
6130 | <attribute name="mouse" type="IMouse" readonly="yes">
|
---|
6131 | <desc>
|
---|
6132 | Virtual mouse object.
|
---|
6133 | <note>
|
---|
6134 | If the machine is not running, any attempt to use
|
---|
6135 | the returned object will result in an error.
|
---|
6136 | </note>
|
---|
6137 | </desc>
|
---|
6138 | </attribute>
|
---|
6139 |
|
---|
6140 | <attribute name="display" type="IDisplay" readonly="yes">
|
---|
6141 | <desc>Virtual display object.
|
---|
6142 | <note>
|
---|
6143 | If the machine is not running, any attempt to use
|
---|
6144 | the returned object will result in an error.
|
---|
6145 | </note>
|
---|
6146 | </desc>
|
---|
6147 | </attribute>
|
---|
6148 |
|
---|
6149 | <attribute name="debugger" type="IMachineDebugger" readonly="yes">
|
---|
6150 | <desc>Debugging interface.</desc>
|
---|
6151 | </attribute>
|
---|
6152 |
|
---|
6153 | <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
|
---|
6154 | <desc>
|
---|
6155 | Collection of USB devices currently attached to the virtual
|
---|
6156 | USB controller.
|
---|
6157 | <note>
|
---|
6158 | The collection is empty if the machine is not running.
|
---|
6159 | </note>
|
---|
6160 | </desc>
|
---|
6161 | </attribute>
|
---|
6162 |
|
---|
6163 | <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
6164 | <desc>
|
---|
6165 | List of USB devices currently attached to the remote VRDE client.
|
---|
6166 | Once a new device is physically attached to the remote host computer,
|
---|
6167 | it appears in this list and remains there until detached.
|
---|
6168 | </desc>
|
---|
6169 | </attribute>
|
---|
6170 |
|
---|
6171 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
6172 | <desc>
|
---|
6173 | Collection of shared folders for the current session. These folders
|
---|
6174 | are called transient shared folders because they are available to the
|
---|
6175 | guest OS running inside the associated virtual machine only for the
|
---|
6176 | duration of the session (as opposed to
|
---|
6177 | <link to="IMachine::sharedFolders"/> which represent permanent shared
|
---|
6178 | folders). When the session is closed (e.g. the machine is powered down),
|
---|
6179 | these folders are automatically discarded.
|
---|
6180 |
|
---|
6181 | New shared folders are added to the collection using
|
---|
6182 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
6183 | removed using <link to="#removeSharedFolder"/>.
|
---|
6184 | </desc>
|
---|
6185 | </attribute>
|
---|
6186 |
|
---|
6187 | <attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
|
---|
6188 | <desc>
|
---|
6189 | Interface that provides information on Remote Desktop Extension (VRDE) connection.
|
---|
6190 | </desc>
|
---|
6191 | </attribute>
|
---|
6192 |
|
---|
6193 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
6194 | <desc>
|
---|
6195 | Event source for console events.
|
---|
6196 | </desc>
|
---|
6197 | </attribute>
|
---|
6198 |
|
---|
6199 | <attribute name="attachedPciDevices" type="IPciDeviceAttachment" readonly="yes" safearray="yes">
|
---|
6200 | <desc>Array of PCI devices attached to this machine.</desc>
|
---|
6201 | </attribute>
|
---|
6202 |
|
---|
6203 | <method name="powerUp">
|
---|
6204 | <desc>
|
---|
6205 | Starts the virtual machine execution using the current machine
|
---|
6206 | state (that is, its current execution state, current settings and
|
---|
6207 | current storage devices).
|
---|
6208 |
|
---|
6209 | <note>
|
---|
6210 | This method is only useful for front-ends that want to actually
|
---|
6211 | execute virtual machines in their own process (like the VirtualBox
|
---|
6212 | or VBoxSDL front-ends). Unless you are intending to write such a
|
---|
6213 | front-end, do not call this method. If you simply want to
|
---|
6214 | start virtual machine execution using one of the existing front-ends
|
---|
6215 | (for example the VirtualBox GUI or headless server), use
|
---|
6216 | <link to="IMachine::launchVMProcess"/> instead; these
|
---|
6217 | front-ends will power up the machine automatically for you.
|
---|
6218 | </note>
|
---|
6219 |
|
---|
6220 | If the machine is powered off or aborted, the execution will
|
---|
6221 | start from the beginning (as if the real hardware were just
|
---|
6222 | powered on).
|
---|
6223 |
|
---|
6224 | If the machine is in the <link to="MachineState_Saved"/> state,
|
---|
6225 | it will continue its execution the point where the state has
|
---|
6226 | been saved.
|
---|
6227 |
|
---|
6228 | If the machine <link to="IMachine::teleporterEnabled"/> property is
|
---|
6229 | enabled on the machine being powered up, the machine will wait for an
|
---|
6230 | incoming teleportation in the <link to="MachineState_TeleportingIn"/>
|
---|
6231 | state. The returned progress object will have at least three
|
---|
6232 | operations where the last three are defined as: (1) powering up and
|
---|
6233 | starting TCP server, (2) waiting for incoming teleportations, and
|
---|
6234 | (3) perform teleportation. These operations will be reflected as the
|
---|
6235 | last three operations of the progress objected returned by
|
---|
6236 | <link to="IMachine::launchVMProcess"/> as well.
|
---|
6237 |
|
---|
6238 | <see>#saveState</see>
|
---|
6239 |
|
---|
6240 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6241 | Virtual machine already running.
|
---|
6242 | </result>
|
---|
6243 | <result name="VBOX_E_HOST_ERROR">
|
---|
6244 | Host interface does not exist or name not set.
|
---|
6245 | </result>
|
---|
6246 | <result name="VBOX_E_FILE_ERROR">
|
---|
6247 | Invalid saved state file.
|
---|
6248 | </result>
|
---|
6249 | </desc>
|
---|
6250 | <param name="progress" type="IProgress" dir="return">
|
---|
6251 | <desc>Progress object to track the operation completion.</desc>
|
---|
6252 | </param>
|
---|
6253 | </method>
|
---|
6254 |
|
---|
6255 | <method name="powerUpPaused">
|
---|
6256 | <desc>
|
---|
6257 | Identical to powerUp except that the VM will enter the
|
---|
6258 | <link to="MachineState_Paused"/> state, instead of
|
---|
6259 | <link to="MachineState_Running"/>.
|
---|
6260 |
|
---|
6261 | <see>#powerUp</see>
|
---|
6262 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6263 | Virtual machine already running.
|
---|
6264 | </result>
|
---|
6265 | <result name="VBOX_E_HOST_ERROR">
|
---|
6266 | Host interface does not exist or name not set.
|
---|
6267 | </result>
|
---|
6268 | <result name="VBOX_E_FILE_ERROR">
|
---|
6269 | Invalid saved state file.
|
---|
6270 | </result>
|
---|
6271 | </desc>
|
---|
6272 | <param name="progress" type="IProgress" dir="return">
|
---|
6273 | <desc>Progress object to track the operation completion.</desc>
|
---|
6274 | </param>
|
---|
6275 | </method>
|
---|
6276 |
|
---|
6277 | <method name="powerDown">
|
---|
6278 | <desc>
|
---|
6279 | Initiates the power down procedure to stop the virtual machine
|
---|
6280 | execution.
|
---|
6281 |
|
---|
6282 | The completion of the power down procedure is tracked using the returned
|
---|
6283 | IProgress object. After the operation is complete, the machine will go
|
---|
6284 | to the PoweredOff state.
|
---|
6285 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6286 | Virtual machine must be Running, Paused or Stuck to be powered down.
|
---|
6287 | </result>
|
---|
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="reset">
|
---|
6295 | <desc>Resets the virtual machine.
|
---|
6296 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6297 | Virtual machine not in Running state.
|
---|
6298 | </result>
|
---|
6299 | <result name="VBOX_E_VM_ERROR">
|
---|
6300 | Virtual machine error in reset operation.
|
---|
6301 | </result>
|
---|
6302 | </desc>
|
---|
6303 | </method>
|
---|
6304 |
|
---|
6305 | <method name="pause">
|
---|
6306 | <desc>Pauses the virtual machine execution.
|
---|
6307 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6308 | Virtual machine not in Running state.
|
---|
6309 | </result>
|
---|
6310 | <result name="VBOX_E_VM_ERROR">
|
---|
6311 | Virtual machine error in suspend operation.
|
---|
6312 | </result>
|
---|
6313 | </desc>
|
---|
6314 | </method>
|
---|
6315 |
|
---|
6316 | <method name="resume">
|
---|
6317 | <desc>Resumes the virtual machine execution.
|
---|
6318 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6319 | Virtual machine not in Paused state.
|
---|
6320 | </result>
|
---|
6321 | <result name="VBOX_E_VM_ERROR">
|
---|
6322 | Virtual machine error in resume operation.
|
---|
6323 | </result>
|
---|
6324 | </desc>
|
---|
6325 | </method>
|
---|
6326 |
|
---|
6327 | <method name="powerButton">
|
---|
6328 | <desc>Sends the ACPI power button event to the guest.
|
---|
6329 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6330 | Virtual machine not in Running state.
|
---|
6331 | </result>
|
---|
6332 | <result name="VBOX_E_PDM_ERROR">
|
---|
6333 | Controlled power off failed.
|
---|
6334 | </result>
|
---|
6335 | </desc>
|
---|
6336 | </method>
|
---|
6337 |
|
---|
6338 | <method name="sleepButton">
|
---|
6339 | <desc>Sends the ACPI sleep button event to the guest.
|
---|
6340 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6341 | Virtual machine not in Running state.
|
---|
6342 | </result>
|
---|
6343 | <result name="VBOX_E_PDM_ERROR">
|
---|
6344 | Sending sleep button event failed.
|
---|
6345 | </result>
|
---|
6346 | </desc>
|
---|
6347 | </method>
|
---|
6348 |
|
---|
6349 | <method name="getPowerButtonHandled">
|
---|
6350 | <desc>Checks if the last power button event was handled by guest.
|
---|
6351 | <result name="VBOX_E_PDM_ERROR">
|
---|
6352 | Checking if the event was handled by the guest OS failed.
|
---|
6353 | </result>
|
---|
6354 | </desc>
|
---|
6355 | <param name="handled" type="boolean" dir="return"/>
|
---|
6356 | </method>
|
---|
6357 |
|
---|
6358 | <method name="getGuestEnteredACPIMode">
|
---|
6359 | <desc>Checks if the guest entered the ACPI mode G0 (working) or
|
---|
6360 | G1 (sleeping). If this method returns @c false, the guest will
|
---|
6361 | most likely not respond to external ACPI events.
|
---|
6362 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6363 | Virtual machine not in Running state.
|
---|
6364 | </result>
|
---|
6365 | </desc>
|
---|
6366 | <param name="entered" type="boolean" dir="return"/>
|
---|
6367 | </method>
|
---|
6368 |
|
---|
6369 | <method name="saveState">
|
---|
6370 | <desc>
|
---|
6371 | Saves the current execution state of a running virtual machine
|
---|
6372 | and stops its execution.
|
---|
6373 |
|
---|
6374 | After this operation completes, the machine will go to the
|
---|
6375 | Saved state. Next time it is powered up, this state will
|
---|
6376 | be restored and the machine will continue its execution from
|
---|
6377 | the place where it was saved.
|
---|
6378 |
|
---|
6379 | This operation differs from taking a snapshot to the effect
|
---|
6380 | that it doesn't create new differencing media. Also, once
|
---|
6381 | the machine is powered up from the state saved using this method,
|
---|
6382 | the saved state is deleted, so it will be impossible to return
|
---|
6383 | to this state later.
|
---|
6384 |
|
---|
6385 | <note>
|
---|
6386 | On success, this method implicitly calls
|
---|
6387 | <link to="IMachine::saveSettings"/> to save all current machine
|
---|
6388 | settings (including runtime changes to the DVD medium, etc.).
|
---|
6389 | Together with the impossibility to change any VM settings when it is
|
---|
6390 | in the Saved state, this guarantees adequate hardware
|
---|
6391 | configuration of the machine when it is restored from the saved
|
---|
6392 | state file.
|
---|
6393 | </note>
|
---|
6394 |
|
---|
6395 | <note>
|
---|
6396 | The machine must be in the Running or Paused state, otherwise
|
---|
6397 | the operation will fail.
|
---|
6398 | </note>
|
---|
6399 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6400 | Virtual machine state neither Running nor Paused.
|
---|
6401 | </result>
|
---|
6402 | <result name="VBOX_E_FILE_ERROR">
|
---|
6403 | Failed to create directory for saved state file.
|
---|
6404 | </result>
|
---|
6405 |
|
---|
6406 | <see><link to="#takeSnapshot"/></see>
|
---|
6407 | </desc>
|
---|
6408 | <param name="progress" type="IProgress" dir="return">
|
---|
6409 | <desc>Progress object to track the operation completion.</desc>
|
---|
6410 | </param>
|
---|
6411 | </method>
|
---|
6412 |
|
---|
6413 | <method name="adoptSavedState">
|
---|
6414 | <desc>
|
---|
6415 | Associates the given saved state file to the virtual machine.
|
---|
6416 |
|
---|
6417 | On success, the machine will go to the Saved state. Next time it is
|
---|
6418 | powered up, it will be restored from the adopted saved state and
|
---|
6419 | continue execution from the place where the saved state file was
|
---|
6420 | created.
|
---|
6421 |
|
---|
6422 | The specified saved state file path may be absolute or relative to the
|
---|
6423 | folder the VM normally saves the state to (usually,
|
---|
6424 | <link to="IMachine::snapshotFolder"/>).
|
---|
6425 |
|
---|
6426 | <note>
|
---|
6427 | It's a caller's responsibility to make sure the given saved state
|
---|
6428 | file is compatible with the settings of this virtual machine that
|
---|
6429 | represent its virtual hardware (memory size, storage disk configuration
|
---|
6430 | etc.). If there is a mismatch, the behavior of the virtual machine
|
---|
6431 | is undefined.
|
---|
6432 | </note>
|
---|
6433 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6434 | Virtual machine state neither PoweredOff nor Aborted.
|
---|
6435 | </result>
|
---|
6436 | </desc>
|
---|
6437 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
6438 | <desc>Path to the saved state file to adopt.</desc>
|
---|
6439 | </param>
|
---|
6440 | </method>
|
---|
6441 |
|
---|
6442 | <method name="discardSavedState">
|
---|
6443 | <desc>
|
---|
6444 | Forcibly resets the machine to "Powered Off" state if it is
|
---|
6445 | currently in the "Saved" state (previously created by <link to="#saveState"/>).
|
---|
6446 | Next time the machine is powered up, a clean boot will occur.
|
---|
6447 | <note>
|
---|
6448 | This operation is equivalent to resetting or powering off
|
---|
6449 | the machine without doing a proper shutdown of the guest
|
---|
6450 | operating system; as with resetting a running phyiscal
|
---|
6451 | computer, it can can lead to data loss.
|
---|
6452 | </note>
|
---|
6453 | If @a fRemoveFile is @c true, the file in the machine directory
|
---|
6454 | into which the machine state was saved is also deleted. If
|
---|
6455 | this is @c false, then the state can be recovered and later
|
---|
6456 | re-inserted into a machine using <link to="#adoptSavedState" />.
|
---|
6457 | The location of the file can be found in the
|
---|
6458 | <link to="IMachine::stateFilePath" /> attribute.
|
---|
6459 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6460 | Virtual machine not in state Saved.
|
---|
6461 | </result>
|
---|
6462 | </desc>
|
---|
6463 | <param name="fRemoveFile" type="boolean" dir="in" >
|
---|
6464 | <desc>Whether to also remove the saved state file.</desc>
|
---|
6465 | </param>
|
---|
6466 | </method>
|
---|
6467 |
|
---|
6468 | <method name="getDeviceActivity">
|
---|
6469 | <desc>
|
---|
6470 | Gets the current activity type of a given device or device group.
|
---|
6471 | <result name="E_INVALIDARG">
|
---|
6472 | Invalid device type.
|
---|
6473 | </result>
|
---|
6474 | </desc>
|
---|
6475 | <param name="type" type="DeviceType" dir="in"/>
|
---|
6476 | <param name="activity" type="DeviceActivity" dir="return"/>
|
---|
6477 | </method>
|
---|
6478 |
|
---|
6479 | <method name="attachUSBDevice">
|
---|
6480 | <desc>
|
---|
6481 | Attaches a host USB device with the given UUID to the
|
---|
6482 | USB controller of the virtual machine.
|
---|
6483 |
|
---|
6484 | The device needs to be in one of the following states:
|
---|
6485 | <link to="USBDeviceState_Busy"/>,
|
---|
6486 | <link to="USBDeviceState_Available"/> or
|
---|
6487 | <link to="USBDeviceState_Held"/>,
|
---|
6488 | otherwise an error is immediately returned.
|
---|
6489 |
|
---|
6490 | When the device state is
|
---|
6491 | <link to="USBDeviceState_Busy">Busy</link>, an error may also
|
---|
6492 | be returned if the host computer refuses to release it for some reason.
|
---|
6493 |
|
---|
6494 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6495 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6496 | Virtual machine state neither Running nor Paused.
|
---|
6497 | </result>
|
---|
6498 | <result name="VBOX_E_PDM_ERROR">
|
---|
6499 | Virtual machine does not have a USB controller.
|
---|
6500 | </result>
|
---|
6501 | </desc>
|
---|
6502 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6503 | <desc>UUID of the host USB device to attach.</desc>
|
---|
6504 | </param>
|
---|
6505 | </method>
|
---|
6506 |
|
---|
6507 | <method name="detachUSBDevice">
|
---|
6508 | <desc>
|
---|
6509 | Detaches an USB device with the given UUID from the USB controller
|
---|
6510 | of the virtual machine.
|
---|
6511 |
|
---|
6512 | After this method succeeds, the VirtualBox server re-initiates
|
---|
6513 | all USB filters as if the device were just physically attached
|
---|
6514 | to the host, but filters of this machine are ignored to avoid
|
---|
6515 | a possible automatic re-attachment.
|
---|
6516 |
|
---|
6517 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6518 |
|
---|
6519 | <result name="VBOX_E_PDM_ERROR">
|
---|
6520 | Virtual machine does not have a USB controller.
|
---|
6521 | </result>
|
---|
6522 | <result name="E_INVALIDARG">
|
---|
6523 | USB device not attached to this virtual machine.
|
---|
6524 | </result>
|
---|
6525 | </desc>
|
---|
6526 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6527 | <desc>UUID of the USB device to detach.</desc>
|
---|
6528 | </param>
|
---|
6529 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6530 | <desc>Detached USB device.</desc>
|
---|
6531 | </param>
|
---|
6532 | </method>
|
---|
6533 |
|
---|
6534 | <method name="findUSBDeviceByAddress">
|
---|
6535 | <desc>
|
---|
6536 | Searches for a USB device with the given host address.
|
---|
6537 |
|
---|
6538 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6539 | Given @c name does not correspond to any USB device.
|
---|
6540 | </result>
|
---|
6541 |
|
---|
6542 | <see>IUSBDevice::address</see>
|
---|
6543 | </desc>
|
---|
6544 | <param name="name" type="wstring" dir="in">
|
---|
6545 | <desc>
|
---|
6546 | Address of the USB device (as assigned by the host) to
|
---|
6547 | search for.
|
---|
6548 | </desc>
|
---|
6549 | </param>
|
---|
6550 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6551 | <desc>Found USB device object.</desc>
|
---|
6552 | </param>
|
---|
6553 | </method>
|
---|
6554 |
|
---|
6555 | <method name="findUSBDeviceById">
|
---|
6556 | <desc>
|
---|
6557 | Searches for a USB device with the given UUID.
|
---|
6558 |
|
---|
6559 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6560 | Given @c id does not correspond to any USB device.
|
---|
6561 | </result>
|
---|
6562 |
|
---|
6563 | <see>IUSBDevice::id</see>
|
---|
6564 | </desc>
|
---|
6565 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6566 | <desc>UUID of the USB device to search for.</desc>
|
---|
6567 | </param>
|
---|
6568 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6569 | <desc>Found USB device object.</desc>
|
---|
6570 | </param>
|
---|
6571 | </method>
|
---|
6572 |
|
---|
6573 | <method name="createSharedFolder">
|
---|
6574 | <desc>
|
---|
6575 | Creates a transient new shared folder by associating the given logical
|
---|
6576 | name with the given host path, adds it to the collection of shared
|
---|
6577 | folders and starts sharing it. Refer to the description of
|
---|
6578 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
6579 |
|
---|
6580 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6581 | Virtual machine in Saved state or currently changing state.
|
---|
6582 | </result>
|
---|
6583 | <result name="VBOX_E_FILE_ERROR">
|
---|
6584 | Shared folder already exists or not accessible.
|
---|
6585 | </result>
|
---|
6586 | </desc>
|
---|
6587 | <param name="name" type="wstring" dir="in">
|
---|
6588 | <desc>Unique logical name of the shared folder.</desc>
|
---|
6589 | </param>
|
---|
6590 | <param name="hostPath" type="wstring" dir="in">
|
---|
6591 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
6592 | </param>
|
---|
6593 | <param name="writable" type="boolean" dir="in">
|
---|
6594 | <desc>Whether the share is writable or readonly</desc>
|
---|
6595 | </param>
|
---|
6596 | <param name="automount" type="boolean" dir="in">
|
---|
6597 | <desc>Whether the share gets automatically mounted by the guest
|
---|
6598 | or not.</desc>
|
---|
6599 | </param>
|
---|
6600 | </method>
|
---|
6601 |
|
---|
6602 | <method name="removeSharedFolder">
|
---|
6603 | <desc>
|
---|
6604 | Removes a transient shared folder with the given name previously
|
---|
6605 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
6606 | shared folders and stops sharing it.
|
---|
6607 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6608 | Virtual machine in Saved state or currently changing state.
|
---|
6609 | </result>
|
---|
6610 | <result name="VBOX_E_FILE_ERROR">
|
---|
6611 | Shared folder does not exists.
|
---|
6612 | </result>
|
---|
6613 | </desc>
|
---|
6614 | <param name="name" type="wstring" dir="in">
|
---|
6615 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
6616 | </param>
|
---|
6617 | </method>
|
---|
6618 |
|
---|
6619 | <method name="takeSnapshot">
|
---|
6620 | <desc>
|
---|
6621 | Saves the current execution state
|
---|
6622 | and all settings of the machine and creates differencing images
|
---|
6623 | for all normal (non-independent) media.
|
---|
6624 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6625 |
|
---|
6626 | This method can be called for a PoweredOff, Saved (see
|
---|
6627 | <link to="#saveState"/>), Running or
|
---|
6628 | Paused virtual machine. When the machine is PoweredOff, an
|
---|
6629 | offline snapshot is created. When the machine is Running a live
|
---|
6630 | snapshot is created, and an online snapshot is is created when Paused.
|
---|
6631 |
|
---|
6632 | The taken snapshot is always based on the
|
---|
6633 | <link to="IMachine::currentSnapshot">current snapshot</link>
|
---|
6634 | of the associated virtual machine and becomes a new current snapshot.
|
---|
6635 |
|
---|
6636 | <note>
|
---|
6637 | This method implicitly calls <link to="IMachine::saveSettings"/> to
|
---|
6638 | save all current machine settings before taking an offline snapshot.
|
---|
6639 | </note>
|
---|
6640 |
|
---|
6641 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6642 | Virtual machine currently changing state.
|
---|
6643 | </result>
|
---|
6644 | </desc>
|
---|
6645 | <param name="name" type="wstring" dir="in">
|
---|
6646 | <desc>Short name for the snapshot.</desc>
|
---|
6647 | </param>
|
---|
6648 | <param name="description" type="wstring" dir="in">
|
---|
6649 | <desc>Optional description of the snapshot.</desc>
|
---|
6650 | </param>
|
---|
6651 | <param name="progress" type="IProgress" dir="return">
|
---|
6652 | <desc>Progress object to track the operation completion.</desc>
|
---|
6653 | </param>
|
---|
6654 | </method>
|
---|
6655 |
|
---|
6656 | <method name="deleteSnapshot">
|
---|
6657 | <desc>
|
---|
6658 | Starts deleting the specified snapshot asynchronously.
|
---|
6659 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6660 |
|
---|
6661 | The execution state and settings of the associated machine stored in
|
---|
6662 | the snapshot will be deleted. The contents of all differencing media of
|
---|
6663 | this snapshot will be merged with the contents of their dependent child
|
---|
6664 | media to keep the medium chain valid (in other words, all changes
|
---|
6665 | represented by media being deleted will be propagated to their child
|
---|
6666 | medium). After that, this snapshot's differencing medium will be
|
---|
6667 | deleted. The parent of this snapshot will become a new parent for all
|
---|
6668 | its child snapshots.
|
---|
6669 |
|
---|
6670 | If the deleted snapshot is the current one, its parent snapshot will
|
---|
6671 | become a new current snapshot. The current machine state is not directly
|
---|
6672 | affected in this case, except that currently attached differencing
|
---|
6673 | media based on media of the deleted snapshot will be also merged as
|
---|
6674 | described above.
|
---|
6675 |
|
---|
6676 | If the deleted snapshot is the first or current snapshot, then the
|
---|
6677 | respective IMachine attributes will be adjusted. Deleting the current
|
---|
6678 | snapshot will also implicitly call <link to="IMachine::saveSettings"/>
|
---|
6679 | to make all current machine settings permanent.
|
---|
6680 |
|
---|
6681 | Deleting a snapshot has the following preconditions:
|
---|
6682 |
|
---|
6683 | <ul>
|
---|
6684 | <li>Child media of all normal media of the deleted snapshot
|
---|
6685 | must be accessible (see <link to="IMedium::state"/>) for this
|
---|
6686 | operation to succeed. In particular, this means that all virtual
|
---|
6687 | machines whose media are directly or indirectly based on the
|
---|
6688 | media of deleted snapshot must be powered off.</li>
|
---|
6689 |
|
---|
6690 | <li>You cannot delete the snapshot if a medium attached to it has
|
---|
6691 | more than once child medium (differencing images) because otherwise
|
---|
6692 | merging would be impossible. This might be the case if there is
|
---|
6693 | more than one child snapshot or differencing images were created
|
---|
6694 | for other reason (e.g. implicitly because of multiple machine
|
---|
6695 | attachments).</li>
|
---|
6696 | </ul>
|
---|
6697 |
|
---|
6698 |
|
---|
6699 | The virtual machine's <link to="IMachine::state">state</link> is
|
---|
6700 | changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
|
---|
6701 | "DeletingSnapshotPaused" while this operation is in progress.
|
---|
6702 |
|
---|
6703 | <note>
|
---|
6704 | Merging medium contents can be very time and disk space
|
---|
6705 | consuming, if these media are big in size and have many
|
---|
6706 | children. However, if the snapshot being deleted is the last
|
---|
6707 | (head) snapshot on the branch, the operation will be rather
|
---|
6708 | quick.
|
---|
6709 | </note>
|
---|
6710 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6711 | The running virtual machine prevents deleting this snapshot. This
|
---|
6712 | happens only in very specific situations, usually snapshots can be
|
---|
6713 | deleted without trouble while a VM is running. The error message
|
---|
6714 | text explains the reason for the failure.
|
---|
6715 | </result>
|
---|
6716 | </desc>
|
---|
6717 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6718 | <desc>UUID of the snapshot to delete.</desc>
|
---|
6719 | </param>
|
---|
6720 | <param name="progress" type="IProgress" dir="return">
|
---|
6721 | <desc>Progress object to track the operation completion.</desc>
|
---|
6722 | </param>
|
---|
6723 | </method>
|
---|
6724 |
|
---|
6725 | <method name="restoreSnapshot">
|
---|
6726 | <desc>
|
---|
6727 | Starts resetting the machine's current state to the state contained
|
---|
6728 | in the given snapshot, asynchronously. All current settings of the
|
---|
6729 | machine will be reset and changes stored in differencing media
|
---|
6730 | will be lost.
|
---|
6731 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6732 |
|
---|
6733 | After this operation is successfully completed, new empty differencing
|
---|
6734 | media are created for all normal media of the machine.
|
---|
6735 |
|
---|
6736 | If the given snapshot is an online snapshot, the machine will go to
|
---|
6737 | the <link to="MachineState_Saved"> saved state</link>, so that the
|
---|
6738 | next time it is powered on, the execution state will be restored
|
---|
6739 | from the state of the snapshot.
|
---|
6740 |
|
---|
6741 | <note>
|
---|
6742 | The machine must not be running, otherwise the operation will fail.
|
---|
6743 | </note>
|
---|
6744 |
|
---|
6745 | <note>
|
---|
6746 | If the machine state is <link to="MachineState_Saved">Saved</link>
|
---|
6747 | prior to this operation, the saved state file will be implicitly
|
---|
6748 | deleted (as if <link to="IConsole::discardSavedState"/> were
|
---|
6749 | called).
|
---|
6750 | </note>
|
---|
6751 |
|
---|
6752 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6753 | Virtual machine is running.
|
---|
6754 | </result>
|
---|
6755 | </desc>
|
---|
6756 | <param name="snapshot" type="ISnapshot" dir="in">
|
---|
6757 | <desc>The snapshot to restore the VM state from.</desc>
|
---|
6758 | </param>
|
---|
6759 | <param name="progress" type="IProgress" dir="return">
|
---|
6760 | <desc>Progress object to track the operation completion.</desc>
|
---|
6761 | </param>
|
---|
6762 | </method>
|
---|
6763 |
|
---|
6764 | <method name="teleport">
|
---|
6765 | <desc>
|
---|
6766 | Teleport the VM to a different host machine or process.
|
---|
6767 |
|
---|
6768 | TODO explain the details.
|
---|
6769 |
|
---|
6770 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6771 | Virtual machine not running or paused.
|
---|
6772 | </result>
|
---|
6773 | </desc>
|
---|
6774 | <param name="hostname" type="wstring" dir="in">
|
---|
6775 | <desc>The name or IP of the host to teleport to.</desc>
|
---|
6776 | </param>
|
---|
6777 | <param name="tcpport" type="unsigned long" dir="in">
|
---|
6778 | <desc>The TCP port to connect to (1..65535).</desc>
|
---|
6779 | </param>
|
---|
6780 | <param name="password" type="wstring" dir="in">
|
---|
6781 | <desc>The password.</desc>
|
---|
6782 | </param>
|
---|
6783 | <param name="maxDowntime" type="unsigned long" dir="in">
|
---|
6784 | <desc>
|
---|
6785 | The maximum allowed downtime given as milliseconds. 0 is not a valid
|
---|
6786 | value. Recommended value: 250 ms.
|
---|
6787 |
|
---|
6788 | The higher the value is, the greater the chance for a successful
|
---|
6789 | teleportation. A small value may easily result in the teleportation
|
---|
6790 | process taking hours and eventually fail.
|
---|
6791 |
|
---|
6792 | <note>
|
---|
6793 | The current implementation treats this a guideline, not as an
|
---|
6794 | absolute rule.
|
---|
6795 | </note>
|
---|
6796 | </desc>
|
---|
6797 | </param>
|
---|
6798 | <param name="progress" type="IProgress" dir="return">
|
---|
6799 | <desc>Progress object to track the operation completion.</desc>
|
---|
6800 | </param>
|
---|
6801 | </method>
|
---|
6802 |
|
---|
6803 | </interface>
|
---|
6804 |
|
---|
6805 | <!--
|
---|
6806 | // IHost
|
---|
6807 | /////////////////////////////////////////////////////////////////////////
|
---|
6808 | -->
|
---|
6809 |
|
---|
6810 | <enum
|
---|
6811 | name="HostNetworkInterfaceMediumType"
|
---|
6812 | uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
|
---|
6813 | >
|
---|
6814 | <desc>
|
---|
6815 | Type of encapsulation. Ethernet encapsulation includes both wired and
|
---|
6816 | wireless Ethernet connections.
|
---|
6817 | <see>IHostNetworkInterface</see>
|
---|
6818 | </desc>
|
---|
6819 |
|
---|
6820 | <const name="Unknown" value="0">
|
---|
6821 | <desc>
|
---|
6822 | The type of interface cannot be determined.
|
---|
6823 | </desc>
|
---|
6824 | </const>
|
---|
6825 | <const name="Ethernet" value="1">
|
---|
6826 | <desc>
|
---|
6827 | Ethernet frame encapsulation.
|
---|
6828 | </desc>
|
---|
6829 | </const>
|
---|
6830 | <const name="PPP" value="2">
|
---|
6831 | <desc>
|
---|
6832 | Point-to-point protocol encapsulation.
|
---|
6833 | </desc>
|
---|
6834 | </const>
|
---|
6835 | <const name="SLIP" value="3">
|
---|
6836 | <desc>
|
---|
6837 | Serial line IP encapsulation.
|
---|
6838 | </desc>
|
---|
6839 | </const>
|
---|
6840 | </enum>
|
---|
6841 |
|
---|
6842 | <enum
|
---|
6843 | name="HostNetworkInterfaceStatus"
|
---|
6844 | uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
|
---|
6845 | >
|
---|
6846 | <desc>
|
---|
6847 | Current status of the interface.
|
---|
6848 | <see>IHostNetworkInterface</see>
|
---|
6849 | </desc>
|
---|
6850 |
|
---|
6851 | <const name="Unknown" value="0">
|
---|
6852 | <desc>
|
---|
6853 | The state of interface cannot be determined.
|
---|
6854 | </desc>
|
---|
6855 | </const>
|
---|
6856 | <const name="Up" value="1">
|
---|
6857 | <desc>
|
---|
6858 | The interface is fully operational.
|
---|
6859 | </desc>
|
---|
6860 | </const>
|
---|
6861 | <const name="Down" value="2">
|
---|
6862 | <desc>
|
---|
6863 | The interface is not functioning.
|
---|
6864 | </desc>
|
---|
6865 | </const>
|
---|
6866 | </enum>
|
---|
6867 |
|
---|
6868 | <enum
|
---|
6869 | name="HostNetworkInterfaceType"
|
---|
6870 | uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
|
---|
6871 | >
|
---|
6872 | <desc>
|
---|
6873 | Network interface type.
|
---|
6874 | </desc>
|
---|
6875 | <const name="Bridged" value="1"/>
|
---|
6876 | <const name="HostOnly" value="2"/>
|
---|
6877 | </enum>
|
---|
6878 |
|
---|
6879 | <interface
|
---|
6880 | name="IHostNetworkInterface" extends="$unknown"
|
---|
6881 | uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
|
---|
6882 | wsmap="managed"
|
---|
6883 | >
|
---|
6884 | <desc>
|
---|
6885 | Represents one of host's network interfaces. IP V6 address and network
|
---|
6886 | mask are strings of 32 hexdecimal digits grouped by four. Groups are
|
---|
6887 | separated by colons.
|
---|
6888 | For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
|
---|
6889 | </desc>
|
---|
6890 | <attribute name="name" type="wstring" readonly="yes">
|
---|
6891 | <desc>Returns the host network interface name.</desc>
|
---|
6892 | </attribute>
|
---|
6893 |
|
---|
6894 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
6895 | <desc>Returns the interface UUID.</desc>
|
---|
6896 | </attribute>
|
---|
6897 |
|
---|
6898 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
6899 | <desc>Returns the name of a virtual network the interface gets attached to.</desc>
|
---|
6900 | </attribute>
|
---|
6901 |
|
---|
6902 | <attribute name="dhcpEnabled" type="boolean" readonly="yes">
|
---|
6903 | <desc>Specifies whether the DHCP is enabled for the interface.</desc>
|
---|
6904 | </attribute>
|
---|
6905 |
|
---|
6906 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
6907 | <desc>Returns the IP V4 address of the interface.</desc>
|
---|
6908 | </attribute>
|
---|
6909 |
|
---|
6910 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
6911 | <desc>Returns the network mask of the interface.</desc>
|
---|
6912 | </attribute>
|
---|
6913 |
|
---|
6914 | <attribute name="IPV6Supported" type="boolean" readonly="yes">
|
---|
6915 | <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
|
---|
6916 | </attribute>
|
---|
6917 |
|
---|
6918 | <attribute name="IPV6Address" type="wstring" readonly="yes">
|
---|
6919 | <desc>Returns the IP V6 address of the interface.</desc>
|
---|
6920 | </attribute>
|
---|
6921 |
|
---|
6922 | <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
|
---|
6923 | <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
|
---|
6924 | </attribute>
|
---|
6925 |
|
---|
6926 | <attribute name="hardwareAddress" type="wstring" readonly="yes">
|
---|
6927 | <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
|
---|
6928 | </attribute>
|
---|
6929 |
|
---|
6930 | <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
|
---|
6931 | <desc>Type of protocol encapsulation used.</desc>
|
---|
6932 | </attribute>
|
---|
6933 |
|
---|
6934 | <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
|
---|
6935 | <desc>Status of the interface.</desc>
|
---|
6936 | </attribute>
|
---|
6937 |
|
---|
6938 | <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
|
---|
6939 | <desc>specifies the host interface type.</desc>
|
---|
6940 | </attribute>
|
---|
6941 |
|
---|
6942 | <method name="enableStaticIpConfig">
|
---|
6943 | <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
|
---|
6944 | <param name="IPAddress" type="wstring" dir="in">
|
---|
6945 | <desc>
|
---|
6946 | IP address.
|
---|
6947 | </desc>
|
---|
6948 | </param>
|
---|
6949 | <param name="networkMask" type="wstring" dir="in">
|
---|
6950 | <desc>
|
---|
6951 | network mask.
|
---|
6952 | </desc>
|
---|
6953 | </param>
|
---|
6954 | </method>
|
---|
6955 |
|
---|
6956 | <method name="enableStaticIpConfigV6">
|
---|
6957 | <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
|
---|
6958 | <param name="IPV6Address" type="wstring" dir="in">
|
---|
6959 | <desc>
|
---|
6960 | IP address.
|
---|
6961 | </desc>
|
---|
6962 | </param>
|
---|
6963 | <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
|
---|
6964 | <desc>
|
---|
6965 | network mask.
|
---|
6966 | </desc>
|
---|
6967 | </param>
|
---|
6968 | </method>
|
---|
6969 |
|
---|
6970 | <method name="enableDynamicIpConfig">
|
---|
6971 | <desc>enables the dynamic IP configuration.</desc>
|
---|
6972 | </method>
|
---|
6973 |
|
---|
6974 | <method name="dhcpRediscover">
|
---|
6975 | <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
|
---|
6976 | </method>
|
---|
6977 |
|
---|
6978 | </interface>
|
---|
6979 |
|
---|
6980 | <interface
|
---|
6981 | name="IHost" extends="$unknown"
|
---|
6982 | uuid="dab4a2b8-c735-4f08-94fc-9bec84182e2f"
|
---|
6983 | wsmap="managed"
|
---|
6984 | >
|
---|
6985 | <desc>
|
---|
6986 | The IHost interface represents the physical machine that this VirtualBox
|
---|
6987 | installation runs on.
|
---|
6988 |
|
---|
6989 | An object implementing this interface is returned by the
|
---|
6990 | <link to="IVirtualBox::host" /> attribute. This interface contains
|
---|
6991 | read-only information about the host's physical hardware (such as what
|
---|
6992 | processors and disks are available, what the host operating system is,
|
---|
6993 | and so on) and also allows for manipulating some of the host's hardware,
|
---|
6994 | such as global USB device filters and host interface networking.
|
---|
6995 |
|
---|
6996 | </desc>
|
---|
6997 | <attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
|
---|
6998 | <desc>List of DVD drives available on the host.</desc>
|
---|
6999 | </attribute>
|
---|
7000 |
|
---|
7001 | <attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
|
---|
7002 | <desc>List of floppy drives available on the host.</desc>
|
---|
7003 | </attribute>
|
---|
7004 |
|
---|
7005 | <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
7006 | <desc>
|
---|
7007 | List of USB devices currently attached to the host.
|
---|
7008 | Once a new device is physically attached to the host computer,
|
---|
7009 | it appears in this list and remains there until detached.
|
---|
7010 |
|
---|
7011 | <note>
|
---|
7012 | If USB functionality is not available in the given edition of
|
---|
7013 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7014 | </note>
|
---|
7015 | </desc>
|
---|
7016 | </attribute>
|
---|
7017 |
|
---|
7018 | <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
7019 | <desc>
|
---|
7020 | List of USB device filters in action.
|
---|
7021 | When a new device is physically attached to the host computer,
|
---|
7022 | filters from this list are applied to it (in order they are stored
|
---|
7023 | in the list). The first matched filter will determine the
|
---|
7024 | <link to="IHostUSBDeviceFilter::action">action</link>
|
---|
7025 | performed on the device.
|
---|
7026 |
|
---|
7027 | Unless the device is ignored by these filters, filters of all
|
---|
7028 | currently running virtual machines
|
---|
7029 | (<link to="IUSBController::deviceFilters"/>) are applied to it.
|
---|
7030 |
|
---|
7031 | <note>
|
---|
7032 | If USB functionality is not available in the given edition of
|
---|
7033 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7034 | </note>
|
---|
7035 |
|
---|
7036 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
7037 | </desc>
|
---|
7038 | </attribute>
|
---|
7039 |
|
---|
7040 | <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
|
---|
7041 | <desc>List of host network interfaces currently defined on the host.</desc>
|
---|
7042 | </attribute>
|
---|
7043 |
|
---|
7044 | <attribute name="processorCount" type="unsigned long" readonly="yes">
|
---|
7045 | <desc>Number of (logical) CPUs installed in the host system.</desc>
|
---|
7046 | </attribute>
|
---|
7047 |
|
---|
7048 | <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
|
---|
7049 | <desc>Number of (logical) CPUs online in the host system.</desc>
|
---|
7050 | </attribute>
|
---|
7051 |
|
---|
7052 | <attribute name="processorCoreCount" type="unsigned long" readonly="yes">
|
---|
7053 | <desc>Number of physical processor cores installed in the host system.</desc>
|
---|
7054 | </attribute>
|
---|
7055 |
|
---|
7056 | <method name="getProcessorSpeed">
|
---|
7057 | <desc>Query the (approximate) maximum speed of a specified host CPU in
|
---|
7058 | Megahertz.
|
---|
7059 | </desc>
|
---|
7060 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7061 | <desc>
|
---|
7062 | Identifier of the CPU.
|
---|
7063 | </desc>
|
---|
7064 | </param>
|
---|
7065 | <param name="speed" type="unsigned long" dir="return">
|
---|
7066 | <desc>
|
---|
7067 | Speed value. 0 is returned if value is not known or @a cpuId is
|
---|
7068 | invalid.
|
---|
7069 | </desc>
|
---|
7070 | </param>
|
---|
7071 | </method>
|
---|
7072 |
|
---|
7073 | <method name="getProcessorFeature">
|
---|
7074 | <desc>Query whether a CPU feature is supported or not.</desc>
|
---|
7075 | <param name="feature" type="ProcessorFeature" dir="in">
|
---|
7076 | <desc>
|
---|
7077 | CPU Feature identifier.
|
---|
7078 | </desc>
|
---|
7079 | </param>
|
---|
7080 | <param name="supported" type="boolean" dir="return">
|
---|
7081 | <desc>
|
---|
7082 | Feature is supported or not.
|
---|
7083 | </desc>
|
---|
7084 | </param>
|
---|
7085 | </method>
|
---|
7086 |
|
---|
7087 | <method name="getProcessorDescription">
|
---|
7088 | <desc>Query the model string of a specified host CPU.
|
---|
7089 | </desc>
|
---|
7090 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7091 | <desc>
|
---|
7092 | Identifier of the CPU.
|
---|
7093 | <note>
|
---|
7094 | The current implementation might not necessarily return the
|
---|
7095 | description for this exact CPU.
|
---|
7096 | </note>
|
---|
7097 | </desc>
|
---|
7098 | </param>
|
---|
7099 | <param name="description" type="wstring" dir="return">
|
---|
7100 | <desc>
|
---|
7101 | Model string. An empty string is returned if value is not known or
|
---|
7102 | @a cpuId is invalid.
|
---|
7103 | </desc>
|
---|
7104 | </param>
|
---|
7105 | </method>
|
---|
7106 |
|
---|
7107 | <method name="getProcessorCPUIDLeaf">
|
---|
7108 | <desc>
|
---|
7109 | Returns the CPU cpuid information for the specified leaf.
|
---|
7110 | </desc>
|
---|
7111 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
7112 | <desc>
|
---|
7113 | Identifier of the CPU. The CPU most be online.
|
---|
7114 | <note>
|
---|
7115 | The current implementation might not necessarily return the
|
---|
7116 | description for this exact CPU.
|
---|
7117 | </note>
|
---|
7118 | </desc>
|
---|
7119 | </param>
|
---|
7120 | <param name="leaf" type="unsigned long" dir="in">
|
---|
7121 | <desc>
|
---|
7122 | CPUID leaf index (eax).
|
---|
7123 | </desc>
|
---|
7124 | </param>
|
---|
7125 | <param name="subLeaf" type="unsigned long" dir="in">
|
---|
7126 | <desc>
|
---|
7127 | CPUID leaf sub index (ecx). This currently only applies to cache
|
---|
7128 | information on Intel CPUs. Use 0 if retrieving values for
|
---|
7129 | <link to="IMachine::setCPUIDLeaf"/>.
|
---|
7130 | </desc>
|
---|
7131 | </param>
|
---|
7132 | <param name="valEax" type="unsigned long" dir="out">
|
---|
7133 | <desc>
|
---|
7134 | CPUID leaf value for register eax.
|
---|
7135 | </desc>
|
---|
7136 | </param>
|
---|
7137 | <param name="valEbx" type="unsigned long" dir="out">
|
---|
7138 | <desc>
|
---|
7139 | CPUID leaf value for register ebx.
|
---|
7140 | </desc>
|
---|
7141 | </param>
|
---|
7142 | <param name="valEcx" type="unsigned long" dir="out">
|
---|
7143 | <desc>
|
---|
7144 | CPUID leaf value for register ecx.
|
---|
7145 | </desc>
|
---|
7146 | </param>
|
---|
7147 | <param name="valEdx" type="unsigned long" dir="out">
|
---|
7148 | <desc>
|
---|
7149 | CPUID leaf value for register edx.
|
---|
7150 | </desc>
|
---|
7151 | </param>
|
---|
7152 | </method>
|
---|
7153 |
|
---|
7154 | <attribute name="memorySize" type="unsigned long" readonly="yes">
|
---|
7155 | <desc>Amount of system memory in megabytes installed in the host system.</desc>
|
---|
7156 | </attribute>
|
---|
7157 |
|
---|
7158 | <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
|
---|
7159 | <desc>Available system memory in the host system.</desc>
|
---|
7160 | </attribute>
|
---|
7161 |
|
---|
7162 | <attribute name="operatingSystem" type="wstring" readonly="yes">
|
---|
7163 | <desc>Name of the host system's operating system.</desc>
|
---|
7164 | </attribute>
|
---|
7165 |
|
---|
7166 | <attribute name="OSVersion" type="wstring" readonly="yes">
|
---|
7167 | <desc>Host operating system's version string.</desc>
|
---|
7168 | </attribute>
|
---|
7169 |
|
---|
7170 | <attribute name="UTCTime" type="long long" readonly="yes">
|
---|
7171 | <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
|
---|
7172 | </attribute>
|
---|
7173 |
|
---|
7174 | <attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
|
---|
7175 | <desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
|
---|
7176 | </attribute>
|
---|
7177 |
|
---|
7178 | <method name="createHostOnlyNetworkInterface">
|
---|
7179 | <desc>
|
---|
7180 | Creates a new adapter for Host Only Networking.
|
---|
7181 | <result name="E_INVALIDARG">
|
---|
7182 | Host network interface @a name already exists.
|
---|
7183 | </result>
|
---|
7184 | </desc>
|
---|
7185 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
7186 | <desc>
|
---|
7187 | Created host interface object.
|
---|
7188 | </desc>
|
---|
7189 | </param>
|
---|
7190 | <param name="progress" type="IProgress" dir="return">
|
---|
7191 | <desc>
|
---|
7192 | Progress object to track the operation completion.
|
---|
7193 | </desc>
|
---|
7194 | </param>
|
---|
7195 | </method>
|
---|
7196 |
|
---|
7197 | <method name="removeHostOnlyNetworkInterface">
|
---|
7198 | <desc>
|
---|
7199 | Removes the given Host Only Networking interface.
|
---|
7200 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7201 | No host network interface matching @a id found.
|
---|
7202 | </result>
|
---|
7203 | </desc>
|
---|
7204 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
7205 | <desc>
|
---|
7206 | Adapter GUID.
|
---|
7207 | </desc>
|
---|
7208 | </param>
|
---|
7209 | <param name="progress" type="IProgress" dir="return">
|
---|
7210 | <desc>
|
---|
7211 | Progress object to track the operation completion.
|
---|
7212 | </desc>
|
---|
7213 | </param>
|
---|
7214 | </method>
|
---|
7215 |
|
---|
7216 | <method name="createUSBDeviceFilter">
|
---|
7217 | <desc>
|
---|
7218 | Creates a new USB device filter. All attributes except
|
---|
7219 | the filter name are set to empty (any match),
|
---|
7220 | <i>active</i> is @c false (the filter is not active).
|
---|
7221 |
|
---|
7222 | The created filter can be added to the list of filters using
|
---|
7223 | <link to="#insertUSBDeviceFilter"/>.
|
---|
7224 |
|
---|
7225 | <see>#USBDeviceFilters</see>
|
---|
7226 | </desc>
|
---|
7227 | <param name="name" type="wstring" dir="in">
|
---|
7228 | <desc>
|
---|
7229 | Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
|
---|
7230 | </desc>
|
---|
7231 | </param>
|
---|
7232 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
7233 | <desc>Created filter object.</desc>
|
---|
7234 | </param>
|
---|
7235 | </method>
|
---|
7236 |
|
---|
7237 | <method name="insertUSBDeviceFilter">
|
---|
7238 | <desc>
|
---|
7239 | Inserts the given USB device to the specified position
|
---|
7240 | in the list of filters.
|
---|
7241 |
|
---|
7242 | Positions are numbered starting from @c 0. If the specified
|
---|
7243 | position is equal to or greater than the number of elements in
|
---|
7244 | the list, the filter is added at the end of the collection.
|
---|
7245 |
|
---|
7246 | <note>
|
---|
7247 | Duplicates are not allowed, so an attempt to insert a
|
---|
7248 | filter already in the list is an error.
|
---|
7249 | </note>
|
---|
7250 | <note>
|
---|
7251 | If USB functionality is not available in the given edition of
|
---|
7252 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7253 | </note>
|
---|
7254 |
|
---|
7255 | <see>#USBDeviceFilters</see>
|
---|
7256 |
|
---|
7257 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
7258 | USB device filter is not created within this VirtualBox instance.
|
---|
7259 | </result>
|
---|
7260 | <result name="E_INVALIDARG">
|
---|
7261 | USB device filter already in list.
|
---|
7262 | </result>
|
---|
7263 |
|
---|
7264 | </desc>
|
---|
7265 | <param name="position" type="unsigned long" dir="in">
|
---|
7266 | <desc>Position to insert the filter to.</desc>
|
---|
7267 | </param>
|
---|
7268 | <param name="filter" type="IHostUSBDeviceFilter" dir="in">
|
---|
7269 | <desc>USB device filter to insert.</desc>
|
---|
7270 | </param>
|
---|
7271 | </method>
|
---|
7272 |
|
---|
7273 | <method name="removeUSBDeviceFilter">
|
---|
7274 | <desc>
|
---|
7275 | Removes a USB device filter from the specified position in the
|
---|
7276 | list of filters.
|
---|
7277 |
|
---|
7278 | Positions are numbered starting from @c 0. Specifying a
|
---|
7279 | position equal to or greater than the number of elements in
|
---|
7280 | the list will produce an error.
|
---|
7281 |
|
---|
7282 | <note>
|
---|
7283 | If USB functionality is not available in the given edition of
|
---|
7284 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7285 | </note>
|
---|
7286 |
|
---|
7287 | <see>#USBDeviceFilters</see>
|
---|
7288 |
|
---|
7289 | <result name="E_INVALIDARG">
|
---|
7290 | USB device filter list empty or invalid @a position.
|
---|
7291 | </result>
|
---|
7292 |
|
---|
7293 | </desc>
|
---|
7294 | <param name="position" type="unsigned long" dir="in">
|
---|
7295 | <desc>Position to remove the filter from.</desc>
|
---|
7296 | </param>
|
---|
7297 | </method>
|
---|
7298 |
|
---|
7299 | <method name="findHostDVDDrive">
|
---|
7300 | <desc>
|
---|
7301 | Searches for a host DVD drive with the given @c name.
|
---|
7302 |
|
---|
7303 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7304 | Given @c name does not correspond to any host drive.
|
---|
7305 | </result>
|
---|
7306 |
|
---|
7307 | </desc>
|
---|
7308 | <param name="name" type="wstring" dir="in">
|
---|
7309 | <desc>Name of the host drive to search for</desc>
|
---|
7310 | </param>
|
---|
7311 | <param name="drive" type="IMedium" dir="return">
|
---|
7312 | <desc>Found host drive object</desc>
|
---|
7313 | </param>
|
---|
7314 | </method>
|
---|
7315 |
|
---|
7316 | <method name="findHostFloppyDrive">
|
---|
7317 | <desc>
|
---|
7318 | Searches for a host floppy drive with the given @c name.
|
---|
7319 |
|
---|
7320 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7321 | Given @c name does not correspond to any host floppy drive.
|
---|
7322 | </result>
|
---|
7323 |
|
---|
7324 | </desc>
|
---|
7325 | <param name="name" type="wstring" dir="in">
|
---|
7326 | <desc>Name of the host floppy drive to search for</desc>
|
---|
7327 | </param>
|
---|
7328 | <param name="drive" type="IMedium" dir="return">
|
---|
7329 | <desc>Found host floppy drive object</desc>
|
---|
7330 | </param>
|
---|
7331 | </method>
|
---|
7332 |
|
---|
7333 | <method name="findHostNetworkInterfaceByName">
|
---|
7334 | <desc>
|
---|
7335 | Searches through all host network interfaces for an interface with
|
---|
7336 | the given @c name.
|
---|
7337 | <note>
|
---|
7338 | The method returns an error if the given @c name does not
|
---|
7339 | correspond to any host network interface.
|
---|
7340 | </note>
|
---|
7341 | </desc>
|
---|
7342 | <param name="name" type="wstring" dir="in">
|
---|
7343 | <desc>Name of the host network interface to search for.</desc>
|
---|
7344 | </param>
|
---|
7345 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7346 | <desc>Found host network interface object.</desc>
|
---|
7347 | </param>
|
---|
7348 | </method>
|
---|
7349 | <method name="findHostNetworkInterfaceById">
|
---|
7350 | <desc>
|
---|
7351 | Searches through all host network interfaces for an interface with
|
---|
7352 | the given GUID.
|
---|
7353 | <note>
|
---|
7354 | The method returns an error if the given GUID does not
|
---|
7355 | correspond to any host network interface.
|
---|
7356 | </note>
|
---|
7357 | </desc>
|
---|
7358 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
7359 | <desc>GUID of the host network interface to search for.</desc>
|
---|
7360 | </param>
|
---|
7361 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7362 | <desc>Found host network interface object.</desc>
|
---|
7363 | </param>
|
---|
7364 | </method>
|
---|
7365 | <method name="findHostNetworkInterfacesOfType">
|
---|
7366 | <desc>
|
---|
7367 | Searches through all host network interfaces and returns a list of interfaces of the specified type
|
---|
7368 | </desc>
|
---|
7369 | <param name="type" type="HostNetworkInterfaceType" dir="in">
|
---|
7370 | <desc>type of the host network interfaces to search for.</desc>
|
---|
7371 | </param>
|
---|
7372 | <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
|
---|
7373 | <desc>Found host network interface objects.</desc>
|
---|
7374 | </param>
|
---|
7375 | </method>
|
---|
7376 |
|
---|
7377 | <method name="findUSBDeviceById">
|
---|
7378 | <desc>
|
---|
7379 | Searches for a USB device with the given UUID.
|
---|
7380 |
|
---|
7381 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7382 | Given @c id does not correspond to any USB device.
|
---|
7383 | </result>
|
---|
7384 |
|
---|
7385 | <see>IHostUSBDevice::id</see>
|
---|
7386 | </desc>
|
---|
7387 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
7388 | <desc>UUID of the USB device to search for.</desc>
|
---|
7389 | </param>
|
---|
7390 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7391 | <desc>Found USB device object.</desc>
|
---|
7392 | </param>
|
---|
7393 | </method>
|
---|
7394 |
|
---|
7395 | <method name="findUSBDeviceByAddress">
|
---|
7396 | <desc>
|
---|
7397 | Searches for a USB device with the given host address.
|
---|
7398 |
|
---|
7399 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7400 | Given @c name does not correspond to any USB device.
|
---|
7401 | </result>
|
---|
7402 |
|
---|
7403 | <see>IHostUSBDevice::address</see>
|
---|
7404 | </desc>
|
---|
7405 | <param name="name" type="wstring" dir="in">
|
---|
7406 | <desc>
|
---|
7407 | Address of the USB device (as assigned by the host) to
|
---|
7408 | search for.
|
---|
7409 | </desc>
|
---|
7410 | </param>
|
---|
7411 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7412 | <desc>Found USB device object.</desc>
|
---|
7413 | </param>
|
---|
7414 | </method>
|
---|
7415 |
|
---|
7416 | <method name="generateMACAddress">
|
---|
7417 | <desc>
|
---|
7418 | Generates a valid Ethernet MAC address, 12 hexadecimal characters.
|
---|
7419 | </desc>
|
---|
7420 | <param name="address" type="wstring" dir="return">
|
---|
7421 | <desc>New Ethernet MAC address.</desc>
|
---|
7422 | </param>
|
---|
7423 | </method>
|
---|
7424 |
|
---|
7425 | </interface>
|
---|
7426 |
|
---|
7427 | <!--
|
---|
7428 | // ISystemProperties
|
---|
7429 | /////////////////////////////////////////////////////////////////////////
|
---|
7430 | -->
|
---|
7431 |
|
---|
7432 | <interface
|
---|
7433 | name="ISystemProperties"
|
---|
7434 | extends="$unknown"
|
---|
7435 | uuid="2f89cdfe-2d10-43d4-b37f-61760f877f29"
|
---|
7436 | wsmap="managed"
|
---|
7437 | >
|
---|
7438 | <desc>
|
---|
7439 | The ISystemProperties interface represents global properties of the given
|
---|
7440 | VirtualBox installation.
|
---|
7441 |
|
---|
7442 | These properties define limits and default values for various attributes
|
---|
7443 | and parameters. Most of the properties are read-only, but some can be
|
---|
7444 | changed by a user.
|
---|
7445 | </desc>
|
---|
7446 |
|
---|
7447 | <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
|
---|
7448 | <desc>Minimum guest system memory in Megabytes.</desc>
|
---|
7449 | </attribute>
|
---|
7450 |
|
---|
7451 | <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
|
---|
7452 | <desc>Maximum guest system memory in Megabytes.</desc>
|
---|
7453 | </attribute>
|
---|
7454 |
|
---|
7455 | <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7456 | <desc>Minimum guest video memory in Megabytes.</desc>
|
---|
7457 | </attribute>
|
---|
7458 |
|
---|
7459 | <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7460 | <desc>Maximum guest video memory in Megabytes.</desc>
|
---|
7461 | </attribute>
|
---|
7462 |
|
---|
7463 | <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7464 | <desc>Minimum CPU count.</desc>
|
---|
7465 | </attribute>
|
---|
7466 |
|
---|
7467 | <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7468 | <desc>Maximum CPU count.</desc>
|
---|
7469 | </attribute>
|
---|
7470 |
|
---|
7471 | <attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
|
---|
7472 | <desc>Maximum of monitors which could be connected.</desc>
|
---|
7473 | </attribute>
|
---|
7474 |
|
---|
7475 | <attribute name="infoVDSize" type="long long" readonly="yes">
|
---|
7476 | <desc>Maximum size of a virtual disk image in bytes. Informational value,
|
---|
7477 | does not reflect the limits of any virtual disk image format.</desc>
|
---|
7478 | </attribute>
|
---|
7479 |
|
---|
7480 | <attribute name="serialPortCount" type="unsigned long" readonly="yes">
|
---|
7481 | <desc>
|
---|
7482 | Maximum number of serial ports associated with every
|
---|
7483 | <link to="IMachine"/> instance.
|
---|
7484 | </desc>
|
---|
7485 | </attribute>
|
---|
7486 |
|
---|
7487 | <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
|
---|
7488 | <desc>
|
---|
7489 | Maximum number of parallel ports associated with every
|
---|
7490 | <link to="IMachine"/> instance.
|
---|
7491 | </desc>
|
---|
7492 | </attribute>
|
---|
7493 |
|
---|
7494 | <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
|
---|
7495 | <desc>
|
---|
7496 | Maximum device position in the boot order. This value corresponds
|
---|
7497 | to the total number of devices a machine can boot from, to make it
|
---|
7498 | possible to include all possible devices to the boot list.
|
---|
7499 | <see><link to="IMachine::setBootOrder"/></see>
|
---|
7500 | </desc>
|
---|
7501 | </attribute>
|
---|
7502 |
|
---|
7503 | <attribute name="defaultMachineFolder" type="wstring">
|
---|
7504 | <desc>
|
---|
7505 | Full path to the default directory used to create new or open
|
---|
7506 | existing machines when a machine settings file name contains no
|
---|
7507 | path.
|
---|
7508 |
|
---|
7509 | Starting with VirtualBox 4.0, by default, this attribute contains
|
---|
7510 | the full path of folder named "VirtualBox VMs" in the user's
|
---|
7511 | home directory, which depends on the host platform.
|
---|
7512 |
|
---|
7513 | When setting this attribute, a full path must be specified.
|
---|
7514 | Setting this property to @c null or an empty string or the
|
---|
7515 | special value "Machines" (for compatibility reasons) will restore
|
---|
7516 | that default value.
|
---|
7517 |
|
---|
7518 | If the folder specified herein does not exist, it will be created
|
---|
7519 | automatically as needed.
|
---|
7520 |
|
---|
7521 | <see>
|
---|
7522 | <link to="IVirtualBox::createMachine"/>,
|
---|
7523 | <link to="IVirtualBox::openMachine"/>
|
---|
7524 | </see>
|
---|
7525 | </desc>
|
---|
7526 | </attribute>
|
---|
7527 |
|
---|
7528 | <attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
|
---|
7529 | <desc>
|
---|
7530 | List of all medium storage formats supported by this VirtualBox
|
---|
7531 | installation.
|
---|
7532 |
|
---|
7533 | Keep in mind that the medium format identifier
|
---|
7534 | (<link to="IMediumFormat::id"/>) used in other API calls like
|
---|
7535 | <link to="IVirtualBox::createHardDisk"/> to refer to a particular
|
---|
7536 | medium format is a case-insensitive string. This means that, for
|
---|
7537 | example, all of the following strings:
|
---|
7538 | <pre>
|
---|
7539 | "VDI"
|
---|
7540 | "vdi"
|
---|
7541 | "VdI"</pre>
|
---|
7542 | refer to the same medium format.
|
---|
7543 |
|
---|
7544 | Note that the virtual medium framework is backend-based, therefore
|
---|
7545 | the list of supported formats depends on what backends are currently
|
---|
7546 | installed.
|
---|
7547 |
|
---|
7548 | <see>
|
---|
7549 | <link to="IMediumFormat"/>,
|
---|
7550 | </see>
|
---|
7551 | </desc>
|
---|
7552 | </attribute>
|
---|
7553 |
|
---|
7554 | <attribute name="defaultHardDiskFormat" type="wstring">
|
---|
7555 | <desc>
|
---|
7556 | Identifier of the default medium format used by VirtualBox.
|
---|
7557 |
|
---|
7558 | The medium format set by this attribute is used by VirtualBox
|
---|
7559 | when the medium format was not specified explicitly. One example is
|
---|
7560 | <link to="IVirtualBox::createHardDisk"/> with the empty
|
---|
7561 | format argument. A more complex example is implicit creation of
|
---|
7562 | differencing media when taking a snapshot of a virtual machine:
|
---|
7563 | this operation will try to use a format of the parent medium first
|
---|
7564 | and if this format does not support differencing media the default
|
---|
7565 | format specified by this argument will be used.
|
---|
7566 |
|
---|
7567 | The list of supported medium formats may be obtained by the
|
---|
7568 | <link to="#mediumFormats"/> call. Note that the default medium
|
---|
7569 | format must have a capability to create differencing media;
|
---|
7570 | otherwise operations that create media implicitly may fail
|
---|
7571 | unexpectedly.
|
---|
7572 |
|
---|
7573 | The initial value of this property is <tt>"VDI"</tt> in the current
|
---|
7574 | version of the VirtualBox product, but may change in the future.
|
---|
7575 |
|
---|
7576 | <note>
|
---|
7577 | Setting this property to @c null or empty string will restore the
|
---|
7578 | initial value.
|
---|
7579 | </note>
|
---|
7580 |
|
---|
7581 | <see>
|
---|
7582 | <link to="#mediumFormats"/>,
|
---|
7583 | <link to="IMediumFormat::id"/>,
|
---|
7584 | <link to="IVirtualBox::createHardDisk"/>
|
---|
7585 | </see>
|
---|
7586 | </desc>
|
---|
7587 | </attribute>
|
---|
7588 |
|
---|
7589 | <attribute name="freeDiskSpaceWarning" type="long long">
|
---|
7590 | <desc>Issue a warning if the free disk space is below (or in some disk
|
---|
7591 | intensive operation is expected to go below) the given size in
|
---|
7592 | bytes.</desc>
|
---|
7593 | </attribute>
|
---|
7594 |
|
---|
7595 | <attribute name="freeDiskSpacePercentWarning" type="unsigned long">
|
---|
7596 | <desc>Issue a warning if the free disk space is below (or in some disk
|
---|
7597 | intensive operation is expected to go below) the given percentage.</desc>
|
---|
7598 | </attribute>
|
---|
7599 |
|
---|
7600 | <attribute name="freeDiskSpaceError" type="long long">
|
---|
7601 | <desc>Issue an error if the free disk space is below (or in some disk
|
---|
7602 | intensive operation is expected to go below) the given size in
|
---|
7603 | bytes.</desc>
|
---|
7604 | </attribute>
|
---|
7605 |
|
---|
7606 | <attribute name="freeDiskSpacePercentError" type="unsigned long">
|
---|
7607 | <desc>Issue an error if the free disk space is below (or in some disk
|
---|
7608 | intensive operation is expected to go below) the given percentage.</desc>
|
---|
7609 | </attribute>
|
---|
7610 |
|
---|
7611 | <attribute name="VRDEAuthLibrary" type="wstring">
|
---|
7612 | <desc>
|
---|
7613 | Library that provides authentication for Remote Desktop clients. The library
|
---|
7614 | is used if a virtual machine's authentication type is set to "external"
|
---|
7615 | in the VM RemoteDisplay configuration.
|
---|
7616 |
|
---|
7617 | The system library extension (".DLL" or ".so") must be omitted.
|
---|
7618 | A full path can be specified; if not, then the library must reside on the
|
---|
7619 | system's default library path.
|
---|
7620 |
|
---|
7621 | The default value of this property is <tt>"VBoxAuth"</tt>. There is a library
|
---|
7622 | of that name in one of the default VirtualBox library directories.
|
---|
7623 |
|
---|
7624 | For details about VirtualBox authentication libraries and how to implement
|
---|
7625 | them, please refer to the VirtualBox manual.
|
---|
7626 |
|
---|
7627 | <note>
|
---|
7628 | Setting this property to @c null or empty string will restore the
|
---|
7629 | initial value.
|
---|
7630 | </note>
|
---|
7631 | </desc>
|
---|
7632 | </attribute>
|
---|
7633 |
|
---|
7634 | <attribute name="webServiceAuthLibrary" type="wstring">
|
---|
7635 | <desc>
|
---|
7636 | Library that provides authentication for webservice clients. The library
|
---|
7637 | is used if a virtual machine's authentication type is set to "external"
|
---|
7638 | in the VM RemoteDisplay configuration and will be called from
|
---|
7639 | within the <link to="IWebsessionManager::logon" /> implementation.
|
---|
7640 |
|
---|
7641 | As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
|
---|
7642 | there is no per-VM setting for this, as the webservice is a global
|
---|
7643 | resource (if it is running). Only for this setting (for the webservice),
|
---|
7644 | setting this value to a literal <tt>"null"</tt> string disables authentication,
|
---|
7645 | meaning that <link to="IWebsessionManager::logon" /> will always succeed,
|
---|
7646 | no matter what user name and password are supplied.
|
---|
7647 |
|
---|
7648 | The initial value of this property is <tt>"VBoxAuth"</tt>,
|
---|
7649 | meaning that the webservice will use the same authentication
|
---|
7650 | library that is used by default for VRDE (again, see
|
---|
7651 | <link to="ISystemProperties::VRDEAuthLibrary" />).
|
---|
7652 | The format and calling convention of authentication libraries
|
---|
7653 | is the same for the webservice as it is for VRDE.
|
---|
7654 |
|
---|
7655 | <note>
|
---|
7656 | Setting this property to @c null or empty string will restore the
|
---|
7657 | initial value.
|
---|
7658 | </note>
|
---|
7659 | </desc>
|
---|
7660 | </attribute>
|
---|
7661 |
|
---|
7662 | <attribute name="defaultVRDEExtPack" type="wstring">
|
---|
7663 | <desc>
|
---|
7664 | The name of the extension pack providing the default VRDE.
|
---|
7665 |
|
---|
7666 | This attribute is for choosing between multiple extension packs
|
---|
7667 | providing VRDE. If only one is installed, it will automatically be the
|
---|
7668 | default one. The attribute value can be empty if no VRDE extension
|
---|
7669 | pack is installed.
|
---|
7670 |
|
---|
7671 | For details about VirtualBox Remote Desktop Extension and how to
|
---|
7672 | implement one, please refer to the VirtualBox SDK.
|
---|
7673 | </desc>
|
---|
7674 | </attribute>
|
---|
7675 |
|
---|
7676 | <attribute name="LogHistoryCount" type="unsigned long">
|
---|
7677 | <desc>
|
---|
7678 | This value specifies how many old release log files are kept.
|
---|
7679 | </desc>
|
---|
7680 | </attribute>
|
---|
7681 |
|
---|
7682 | <attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
|
---|
7683 | <desc>This value hold the default audio driver for the current
|
---|
7684 | system.</desc>
|
---|
7685 | </attribute>
|
---|
7686 |
|
---|
7687 |
|
---|
7688 | <method name="getMaxNetworkAdapters">
|
---|
7689 | <desc>
|
---|
7690 | Maximum total number of network adapters associated with every
|
---|
7691 | <link to="IMachine"/> instance.
|
---|
7692 | </desc>
|
---|
7693 |
|
---|
7694 | <param name="chipset" type="ChipsetType" dir="in">
|
---|
7695 | <desc>The chipset type to get the value for.</desc>
|
---|
7696 | </param>
|
---|
7697 |
|
---|
7698 |
|
---|
7699 | <param name="maxNetworkAdapters" type="unsigned long" dir="return">
|
---|
7700 | <desc>The maximum total number of network adapters allowed.</desc>
|
---|
7701 | </param>
|
---|
7702 |
|
---|
7703 | </method>
|
---|
7704 |
|
---|
7705 | <method name="getMaxNetworkAdaptersOfType">
|
---|
7706 | <desc>
|
---|
7707 | Maximum number of network adapters of a given attachment type,
|
---|
7708 | associated with every <link to="IMachine"/> instance.
|
---|
7709 | </desc>
|
---|
7710 |
|
---|
7711 | <param name="chipset" type="ChipsetType" dir="in">
|
---|
7712 | <desc>The chipset type to get the value for.</desc>
|
---|
7713 | </param>
|
---|
7714 |
|
---|
7715 | <param name="type" type="NetworkAttachmentType" dir="in">
|
---|
7716 | <desc>Type of attachment.</desc>
|
---|
7717 | </param>
|
---|
7718 |
|
---|
7719 | <param name="maxNetworkAdapters" type="unsigned long" dir="return">
|
---|
7720 | <desc>The maximum number of network adapters allowed for
|
---|
7721 | particular chipset and attachment type.</desc>
|
---|
7722 | </param>
|
---|
7723 |
|
---|
7724 | </method>
|
---|
7725 |
|
---|
7726 |
|
---|
7727 | <method name="getMaxDevicesPerPortForStorageBus">
|
---|
7728 | <desc>Returns the maximum number of devices which can be attached to a port
|
---|
7729 | for the given storage bus.</desc>
|
---|
7730 |
|
---|
7731 | <param name="bus" type="StorageBus" dir="in">
|
---|
7732 | <desc>The storage bus type to get the value for.</desc>
|
---|
7733 | </param>
|
---|
7734 |
|
---|
7735 | <param name="maxDevicesPerPort" type="unsigned long" dir="return">
|
---|
7736 | <desc>The maximum number of devices which can be attached to the port for the given
|
---|
7737 | storage bus.</desc>
|
---|
7738 | </param>
|
---|
7739 | </method>
|
---|
7740 |
|
---|
7741 | <method name="getMinPortCountForStorageBus">
|
---|
7742 | <desc>Returns the minimum number of ports the given storage bus supports.</desc>
|
---|
7743 |
|
---|
7744 | <param name="bus" type="StorageBus" dir="in">
|
---|
7745 | <desc>The storage bus type to get the value for.</desc>
|
---|
7746 | </param>
|
---|
7747 |
|
---|
7748 | <param name="minPortCount" type="unsigned long" dir="return">
|
---|
7749 | <desc>The minimum number of ports for the given storage bus.</desc>
|
---|
7750 | </param>
|
---|
7751 | </method>
|
---|
7752 |
|
---|
7753 | <method name="getMaxPortCountForStorageBus">
|
---|
7754 | <desc>Returns the maximum number of ports the given storage bus supports.</desc>
|
---|
7755 |
|
---|
7756 | <param name="bus" type="StorageBus" dir="in">
|
---|
7757 | <desc>The storage bus type to get the value for.</desc>
|
---|
7758 | </param>
|
---|
7759 |
|
---|
7760 | <param name="maxPortCount" type="unsigned long" dir="return">
|
---|
7761 | <desc>The maximum number of ports for the given storage bus.</desc>
|
---|
7762 | </param>
|
---|
7763 | </method>
|
---|
7764 |
|
---|
7765 | <method name="getMaxInstancesOfStorageBus">
|
---|
7766 | <desc>Returns the maximum number of storage bus instances which
|
---|
7767 | can be configured for each VM. This corresponds to the number of
|
---|
7768 | storage controllers one can have. Value may depend on chipset type
|
---|
7769 | used.</desc>
|
---|
7770 |
|
---|
7771 | <param name="chipset" type="ChipsetType" dir="in">
|
---|
7772 | <desc>The chipset type to get the value for.</desc>
|
---|
7773 | </param>
|
---|
7774 |
|
---|
7775 | <param name="bus" type="StorageBus" dir="in">
|
---|
7776 | <desc>The storage bus type to get the value for.</desc>
|
---|
7777 | </param>
|
---|
7778 |
|
---|
7779 | <param name="maxInstances" type="unsigned long" dir="return">
|
---|
7780 | <desc>The maximum number of instances for the given storage bus.</desc>
|
---|
7781 | </param>
|
---|
7782 | </method>
|
---|
7783 |
|
---|
7784 | <method name="getDeviceTypesForStorageBus">
|
---|
7785 | <desc>Returns list of all the supported device types
|
---|
7786 | (<link to="DeviceType"/>) for the given type of storage
|
---|
7787 | bus.</desc>
|
---|
7788 |
|
---|
7789 | <param name="bus" type="StorageBus" dir="in">
|
---|
7790 | <desc>The storage bus type to get the value for.</desc>
|
---|
7791 | </param>
|
---|
7792 |
|
---|
7793 | <param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
|
---|
7794 | <desc>The list of all supported device types for the given storage bus.</desc>
|
---|
7795 | </param>
|
---|
7796 | </method>
|
---|
7797 |
|
---|
7798 | <method name="getDefaultIoCacheSettingForStorageController">
|
---|
7799 | <desc>Returns the default I/O cache setting for the
|
---|
7800 | given storage controller</desc>
|
---|
7801 |
|
---|
7802 | <param name="controllerType" type="StorageControllerType" dir="in">
|
---|
7803 | <desc>The storage controller to the setting for.</desc>
|
---|
7804 | </param>
|
---|
7805 |
|
---|
7806 | <param name="enabled" type="boolean" dir="return">
|
---|
7807 | <desc>Returned flag indicating the default value</desc>
|
---|
7808 | </param>
|
---|
7809 | </method>
|
---|
7810 | </interface>
|
---|
7811 |
|
---|
7812 | <!--
|
---|
7813 | // IGuest
|
---|
7814 | /////////////////////////////////////////////////////////////////////////
|
---|
7815 | -->
|
---|
7816 |
|
---|
7817 | <interface
|
---|
7818 | name="IGuestOSType" extends="$unknown"
|
---|
7819 | uuid="432c1546-1354-4abf-bf08-878a32a373f5"
|
---|
7820 | wsmap="struct"
|
---|
7821 | >
|
---|
7822 | <desc>
|
---|
7823 | </desc>
|
---|
7824 |
|
---|
7825 | <attribute name="familyId" type="wstring" readonly="yes">
|
---|
7826 | <desc>Guest OS family identifier string.</desc>
|
---|
7827 | </attribute>
|
---|
7828 |
|
---|
7829 | <attribute name="familyDescription" type="wstring" readonly="yes">
|
---|
7830 | <desc>Human readable description of the guest OS family.</desc>
|
---|
7831 | </attribute>
|
---|
7832 |
|
---|
7833 | <attribute name="id" type="wstring" readonly="yes">
|
---|
7834 | <desc>Guest OS identifier string.</desc>
|
---|
7835 | </attribute>
|
---|
7836 |
|
---|
7837 | <attribute name="description" type="wstring" readonly="yes">
|
---|
7838 | <desc>Human readable description of the guest OS.</desc>
|
---|
7839 | </attribute>
|
---|
7840 |
|
---|
7841 | <attribute name="is64Bit" type="boolean" readonly="yes">
|
---|
7842 | <desc>Returns @c true if the given OS is 64-bit</desc>
|
---|
7843 | </attribute>
|
---|
7844 |
|
---|
7845 | <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
|
---|
7846 | <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
|
---|
7847 | </attribute>
|
---|
7848 |
|
---|
7849 | <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
|
---|
7850 | <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
|
---|
7851 | </attribute>
|
---|
7852 |
|
---|
7853 | <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
|
---|
7854 | <desc>Recommended RAM size in Megabytes.</desc>
|
---|
7855 | </attribute>
|
---|
7856 |
|
---|
7857 | <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
|
---|
7858 | <desc>Recommended video RAM size in Megabytes.</desc>
|
---|
7859 | </attribute>
|
---|
7860 |
|
---|
7861 | <attribute name="recommendedHDD" type="long long" readonly="yes">
|
---|
7862 | <desc>Recommended hard disk size in bytes.</desc>
|
---|
7863 | </attribute>
|
---|
7864 |
|
---|
7865 | <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
|
---|
7866 | <desc>Returns recommended network adapter for this OS type.</desc>
|
---|
7867 | </attribute>
|
---|
7868 |
|
---|
7869 | <attribute name="recommendedPae" type="boolean" readonly="yes">
|
---|
7870 | <desc>Returns @c true if using PAE is recommended for this OS type.</desc>
|
---|
7871 | </attribute>
|
---|
7872 |
|
---|
7873 | <attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
|
---|
7874 | <desc>Recommended storage controller type for DVD/CD drives.</desc>
|
---|
7875 | </attribute>
|
---|
7876 |
|
---|
7877 | <attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
|
---|
7878 | <desc>Recommended storage bus type for DVD/CD drives.</desc>
|
---|
7879 | </attribute>
|
---|
7880 |
|
---|
7881 | <attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
|
---|
7882 | <desc>Recommended storage controller type for HD drives.</desc>
|
---|
7883 | </attribute>
|
---|
7884 |
|
---|
7885 | <attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
|
---|
7886 | <desc>Recommended storage bus type for HD drives.</desc>
|
---|
7887 | </attribute>
|
---|
7888 |
|
---|
7889 | <attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
|
---|
7890 | <desc>Recommended firmware type.</desc>
|
---|
7891 | </attribute>
|
---|
7892 |
|
---|
7893 | <attribute name="recommendedUsbHid" type="boolean" readonly="yes">
|
---|
7894 | <desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
|
---|
7895 | </attribute>
|
---|
7896 |
|
---|
7897 | <attribute name="recommendedHpet" type="boolean" readonly="yes">
|
---|
7898 | <desc>Returns @c true if using HPET is recommended for this OS type.</desc>
|
---|
7899 | </attribute>
|
---|
7900 |
|
---|
7901 | <attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
|
---|
7902 | <desc>Returns @c true if using a USB Tablet is recommended.</desc>
|
---|
7903 | </attribute>
|
---|
7904 |
|
---|
7905 | <attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
|
---|
7906 | <desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
|
---|
7907 | </attribute>
|
---|
7908 |
|
---|
7909 | <attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
|
---|
7910 | <desc>Recommended chipset type.</desc>
|
---|
7911 | </attribute>
|
---|
7912 |
|
---|
7913 | <attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
|
---|
7914 | <desc>Recommended audio type.</desc>
|
---|
7915 | </attribute>
|
---|
7916 |
|
---|
7917 | </interface>
|
---|
7918 |
|
---|
7919 | <enum
|
---|
7920 | name="AdditionsFacilityType"
|
---|
7921 | uuid="98f7f957-89fb-49b6-a3b1-31e3285eb1d8"
|
---|
7922 | >
|
---|
7923 | <desc>
|
---|
7924 | Guest Additions facility IDs.
|
---|
7925 | </desc>
|
---|
7926 |
|
---|
7927 | <const name="None" value="0">
|
---|
7928 | <desc>No/invalid facility.</desc>
|
---|
7929 | </const>
|
---|
7930 | <const name="VBoxGuestDriver" value="20">
|
---|
7931 | <desc>VirtualBox base driver (VBoxGuest).</desc>
|
---|
7932 | </const>
|
---|
7933 | <const name="VBoxService" value="100">
|
---|
7934 | <desc>VirtualBox system service (VBoxService).</desc>
|
---|
7935 | </const>
|
---|
7936 | <const name="VBoxTrayClient" value="101">
|
---|
7937 | <desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc>
|
---|
7938 | </const>
|
---|
7939 | <const name="Seamless" value="1000">
|
---|
7940 | <desc>Seamless guest desktop integration.</desc>
|
---|
7941 | </const>
|
---|
7942 | <const name="Graphics" value="1100">
|
---|
7943 | <desc>Guest graphics mode. If not enabled, seamless rendering will not work, resize hints
|
---|
7944 | are not immediately acted on and guest display resizes are probably not initiated by
|
---|
7945 | the guest additions.
|
---|
7946 | </desc>
|
---|
7947 | </const>
|
---|
7948 | <const name="All" value="2147483646">
|
---|
7949 | <desc>All facilities selected.</desc>
|
---|
7950 | </const>
|
---|
7951 | </enum>
|
---|
7952 |
|
---|
7953 | <enum
|
---|
7954 | name="AdditionsFacilityClass"
|
---|
7955 | uuid="446451b2-c88d-4e5d-84c9-91bc7f533f5f"
|
---|
7956 | >
|
---|
7957 | <desc>
|
---|
7958 | Guest Additions facility classes.
|
---|
7959 | </desc>
|
---|
7960 |
|
---|
7961 | <const name="None" value="0">
|
---|
7962 | <desc>No/invalid class.</desc>
|
---|
7963 | </const>
|
---|
7964 | <const name="Driver" value="10">
|
---|
7965 | <desc>Driver.</desc>
|
---|
7966 | </const>
|
---|
7967 | <const name="Service" value="30">
|
---|
7968 | <desc>System service.</desc>
|
---|
7969 | </const>
|
---|
7970 | <const name="Program" value="50">
|
---|
7971 | <desc>Program.</desc>
|
---|
7972 | </const>
|
---|
7973 | <const name="Feature" value="100">
|
---|
7974 | <desc>Feature.</desc>
|
---|
7975 | </const>
|
---|
7976 | <const name="ThirdParty" value="999">
|
---|
7977 | <desc>Third party.</desc>
|
---|
7978 | </const>
|
---|
7979 | <const name="All" value="2147483646">
|
---|
7980 | <desc>All facility classes selected.</desc>
|
---|
7981 | </const>
|
---|
7982 | </enum>
|
---|
7983 |
|
---|
7984 | <enum
|
---|
7985 | name="AdditionsFacilityStatus"
|
---|
7986 | uuid="ce06f9e1-394e-4fe9-9368-5a88c567dbde"
|
---|
7987 | >
|
---|
7988 | <desc>
|
---|
7989 | Guest Additions facility states.
|
---|
7990 | </desc>
|
---|
7991 |
|
---|
7992 | <const name="Inactive" value="0">
|
---|
7993 | <desc>Facility is not active.</desc>
|
---|
7994 | </const>
|
---|
7995 | <const name="Paused" value="1">
|
---|
7996 | <desc>Facility has been paused.</desc>
|
---|
7997 | </const>
|
---|
7998 | <const name="PreInit" value="20">
|
---|
7999 | <desc>Facility is preparing to initialize.</desc>
|
---|
8000 | </const>
|
---|
8001 | <const name="Init" value="30">
|
---|
8002 | <desc>Facility is initializing.</desc>
|
---|
8003 | </const>
|
---|
8004 | <const name="Active" value="50">
|
---|
8005 | <desc>Facility is up and running.</desc>
|
---|
8006 | </const>
|
---|
8007 | <const name="Terminating" value="100">
|
---|
8008 | <desc>Facility is shutting down.</desc>
|
---|
8009 | </const>
|
---|
8010 | <const name="Terminated" value="101">
|
---|
8011 | <desc>Facility successfully shut down.</desc>
|
---|
8012 | </const>
|
---|
8013 | <const name="Failed" value="800">
|
---|
8014 | <desc>Facility failed to start.</desc>
|
---|
8015 | </const>
|
---|
8016 | <const name="Unknown" value="999">
|
---|
8017 | <desc>Facility status is unknown.</desc>
|
---|
8018 | </const>
|
---|
8019 | </enum>
|
---|
8020 |
|
---|
8021 | <interface
|
---|
8022 | name="IAdditionsFacility" extends="$unknown"
|
---|
8023 | uuid="54992946-6af1-4e49-98ec-58b558b7291e"
|
---|
8024 | wsmap="struct"
|
---|
8025 | >
|
---|
8026 | <desc>
|
---|
8027 | Structure representing a Guest Additions facility.
|
---|
8028 | </desc>
|
---|
8029 |
|
---|
8030 | <attribute name="classType" type="AdditionsFacilityClass" readonly="yes">
|
---|
8031 | <desc>The class this facility is part of.</desc>
|
---|
8032 | </attribute>
|
---|
8033 |
|
---|
8034 | <attribute name="lastUpdated" type="long long" readonly="yes">
|
---|
8035 | <desc>
|
---|
8036 | Time stamp of the last status update,
|
---|
8037 | in milliseconds since 1970-01-01 UTC.
|
---|
8038 | </desc>
|
---|
8039 | </attribute>
|
---|
8040 |
|
---|
8041 | <attribute name="name" type="wstring" readonly="yes">
|
---|
8042 | <desc>The facility's friendly name.</desc>
|
---|
8043 | </attribute>
|
---|
8044 |
|
---|
8045 | <attribute name="status" type="AdditionsFacilityStatus" readonly="yes">
|
---|
8046 | <desc>The current status.</desc>
|
---|
8047 | </attribute>
|
---|
8048 |
|
---|
8049 | <attribute name="type" type="AdditionsFacilityType" readonly="yes">
|
---|
8050 | <desc>The facility's type ID.</desc>
|
---|
8051 | </attribute>
|
---|
8052 | </interface>
|
---|
8053 |
|
---|
8054 | <enum
|
---|
8055 | name="AdditionsRunLevelType"
|
---|
8056 | uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
|
---|
8057 | >
|
---|
8058 | <desc>
|
---|
8059 | Guest Additions run level type.
|
---|
8060 | </desc>
|
---|
8061 |
|
---|
8062 | <const name="None" value="0">
|
---|
8063 | <desc>Guest Additions are not loaded.</desc>
|
---|
8064 | </const>
|
---|
8065 | <const name="System" value="1">
|
---|
8066 | <desc>Guest drivers are loaded.</desc>
|
---|
8067 | </const>
|
---|
8068 | <const name="Userland" value="2">
|
---|
8069 | <desc>Common components (such as application services) are loaded.</desc>
|
---|
8070 | </const>
|
---|
8071 | <const name="Desktop" value="3">
|
---|
8072 | <desc>Per-user desktop components are loaded.</desc>
|
---|
8073 | </const>
|
---|
8074 | </enum>
|
---|
8075 |
|
---|
8076 | <enum
|
---|
8077 | name="AdditionsUpdateFlag"
|
---|
8078 | uuid="726a818d-18d6-4389-94e8-3e9e6826171a"
|
---|
8079 | >
|
---|
8080 | <desc>
|
---|
8081 | Guest Additions update flags.
|
---|
8082 | </desc>
|
---|
8083 |
|
---|
8084 | <const name="None" value="0">
|
---|
8085 | <desc>No flag set.</desc>
|
---|
8086 | </const>
|
---|
8087 | <const name="WaitForUpdateStartOnly" value="1">
|
---|
8088 | <desc>Only wait for the update process being started and do not
|
---|
8089 | wait while peforming the actual update.</desc>
|
---|
8090 | </const>
|
---|
8091 | </enum>
|
---|
8092 |
|
---|
8093 | <enum
|
---|
8094 | name="ExecuteProcessFlag"
|
---|
8095 | uuid="3258e8a5-ba0c-43d5-86b5-cf91405fddc0"
|
---|
8096 | >
|
---|
8097 | <desc>
|
---|
8098 | Guest process execution flags.
|
---|
8099 | </desc>
|
---|
8100 |
|
---|
8101 | <const name="None" value="0">
|
---|
8102 | <desc>No flag set.</desc>
|
---|
8103 | </const>
|
---|
8104 |
|
---|
8105 | <const name="WaitForProcessStartOnly" value="1">
|
---|
8106 | <desc>Only use the specified timeout value to wait for starting the guest process - the guest
|
---|
8107 | process itself then uses an infinite timeout.</desc>
|
---|
8108 | </const>
|
---|
8109 |
|
---|
8110 | <const name="IgnoreOrphanedProcesses" value="2">
|
---|
8111 | <desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
|
---|
8112 | </const>
|
---|
8113 |
|
---|
8114 | <const name="Hidden" value="4">
|
---|
8115 | <desc>Don't show the started process according to the guest OS guidelines.</desc>
|
---|
8116 | </const>
|
---|
8117 | </enum>
|
---|
8118 |
|
---|
8119 | <enum
|
---|
8120 | name="ExecuteProcessStatus"
|
---|
8121 | uuid="153768d9-d971-4098-8b5a-c5cb1ab9ea88"
|
---|
8122 | >
|
---|
8123 | <desc>
|
---|
8124 | Guest process execution status.
|
---|
8125 | </desc>
|
---|
8126 |
|
---|
8127 | <const name="Undefined" value="0">
|
---|
8128 | <desc>Process is in an undefined state.</desc>
|
---|
8129 | </const>
|
---|
8130 |
|
---|
8131 | <const name="Started" value="1">
|
---|
8132 | <desc>Process has been started.</desc>
|
---|
8133 | </const>
|
---|
8134 |
|
---|
8135 | <const name="TerminatedNormally" value="2">
|
---|
8136 | <desc>Process terminated normally.</desc>
|
---|
8137 | </const>
|
---|
8138 |
|
---|
8139 | <const name="TerminatedSignal" value="3">
|
---|
8140 | <desc>Process terminated via signal.</desc>
|
---|
8141 | </const>
|
---|
8142 |
|
---|
8143 | <const name="TerminatedAbnormally" value="4">
|
---|
8144 | <desc>Process terminated abnormally.</desc>
|
---|
8145 | </const>
|
---|
8146 |
|
---|
8147 | <const name="TimedOutKilled" value="5">
|
---|
8148 | <desc>Process timed out and was killed.</desc>
|
---|
8149 | </const>
|
---|
8150 |
|
---|
8151 | <const name="TimedOutAbnormally" value="6">
|
---|
8152 | <desc>Process timed out and was not killed successfully.</desc>
|
---|
8153 | </const>
|
---|
8154 |
|
---|
8155 | <const name="Down" value="7">
|
---|
8156 | <desc>Service/OS is stopping, process was killed.</desc>
|
---|
8157 | </const>
|
---|
8158 |
|
---|
8159 | <const name="Error" value="8">
|
---|
8160 | <desc>Something went wrong (error code in flags).</desc>
|
---|
8161 | </const>
|
---|
8162 | </enum>
|
---|
8163 |
|
---|
8164 | <enum
|
---|
8165 | name="ProcessInputFlag"
|
---|
8166 | uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
|
---|
8167 | >
|
---|
8168 | <desc>
|
---|
8169 | Guest process input flags.
|
---|
8170 | </desc>
|
---|
8171 |
|
---|
8172 | <const name="None" value="0">
|
---|
8173 | <desc>No flag set.</desc>
|
---|
8174 | </const>
|
---|
8175 |
|
---|
8176 | <const name="EndOfFile" value="1">
|
---|
8177 | <desc>End of file (input) reached.</desc>
|
---|
8178 | </const>
|
---|
8179 | </enum>
|
---|
8180 |
|
---|
8181 | <enum
|
---|
8182 | name="ProcessOutputFlag"
|
---|
8183 | uuid="9979e85a-52bb-40b7-870c-57115e27e0f1"
|
---|
8184 | >
|
---|
8185 | <desc>
|
---|
8186 | Guest process output flags for specifying which
|
---|
8187 | type of output to retrieve.
|
---|
8188 | </desc>
|
---|
8189 |
|
---|
8190 | <const name="None" value="0">
|
---|
8191 | <desc>No flags set. Get output from stdout.</desc>
|
---|
8192 | </const>
|
---|
8193 |
|
---|
8194 | <const name="StdErr" value="1">
|
---|
8195 | <desc>Get output from stderr.</desc>
|
---|
8196 | </const>
|
---|
8197 | </enum>
|
---|
8198 |
|
---|
8199 | <enum
|
---|
8200 | name="CopyFileFlag"
|
---|
8201 | uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
|
---|
8202 | >
|
---|
8203 | <desc>
|
---|
8204 | Host/Guest copy flags. At the moment none of these flags
|
---|
8205 | are implemented.
|
---|
8206 | </desc>
|
---|
8207 |
|
---|
8208 | <const name="None" value="0">
|
---|
8209 | <desc>No flag set.</desc>
|
---|
8210 | </const>
|
---|
8211 |
|
---|
8212 | <const name="Recursive" value="1">
|
---|
8213 | <desc>Copy directories recursively.</desc>
|
---|
8214 | </const>
|
---|
8215 |
|
---|
8216 | <const name="Update" value="2">
|
---|
8217 | <desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc>
|
---|
8218 | </const>
|
---|
8219 |
|
---|
8220 | <const name="FollowLinks" value="4">
|
---|
8221 | <desc>Follow symbolic links.</desc>
|
---|
8222 | </const>
|
---|
8223 | </enum>
|
---|
8224 |
|
---|
8225 | <enum
|
---|
8226 | name="CreateDirectoryFlag"
|
---|
8227 | uuid="26ff5bdd-c81f-4304-857b-b8be5e3f9cd6"
|
---|
8228 | >
|
---|
8229 | <desc>
|
---|
8230 | Directory creation flags.
|
---|
8231 | </desc>
|
---|
8232 |
|
---|
8233 | <const name="None" value="0">
|
---|
8234 | <desc>No flag set.</desc>
|
---|
8235 | </const>
|
---|
8236 |
|
---|
8237 | <const name="Parents" value="1">
|
---|
8238 | <desc>No error if existing, make parent directories as needed.</desc>
|
---|
8239 | </const>
|
---|
8240 | </enum>
|
---|
8241 |
|
---|
8242 | <interface
|
---|
8243 | name="IGuest" extends="$unknown"
|
---|
8244 | uuid="4e78f7dd-8ca1-47e5-a344-5207f793df71"
|
---|
8245 | wsmap="managed"
|
---|
8246 | >
|
---|
8247 | <desc>
|
---|
8248 | The IGuest interface represents information about the operating system
|
---|
8249 | running inside the virtual machine. Used in
|
---|
8250 | <link to="IConsole::guest"/>.
|
---|
8251 |
|
---|
8252 | IGuest provides information about the guest operating system, whether
|
---|
8253 | Guest Additions are installed and other OS-specific virtual machine
|
---|
8254 | properties.
|
---|
8255 | </desc>
|
---|
8256 |
|
---|
8257 | <attribute name="OSTypeId" type="wstring" readonly="yes">
|
---|
8258 | <desc>
|
---|
8259 | Identifier of the Guest OS type as reported by the Guest
|
---|
8260 | Additions.
|
---|
8261 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
8262 | an IGuestOSType object representing details about the given
|
---|
8263 | Guest OS type.
|
---|
8264 | <note>
|
---|
8265 | If Guest Additions are not installed, this value will be
|
---|
8266 | the same as <link to="IMachine::OSTypeId"/>.
|
---|
8267 | </note>
|
---|
8268 | </desc>
|
---|
8269 | </attribute>
|
---|
8270 |
|
---|
8271 | <attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
|
---|
8272 | <desc>
|
---|
8273 | Current run level of the Guest Additions.
|
---|
8274 | </desc>
|
---|
8275 | </attribute>
|
---|
8276 |
|
---|
8277 | <attribute name="additionsVersion" type="wstring" readonly="yes">
|
---|
8278 | <desc>
|
---|
8279 | Version of the Guest Additions including the revision (3 decimal numbers
|
---|
8280 | separated by dots + revision number) installed on the guest or empty
|
---|
8281 | when the Additions are not installed.
|
---|
8282 | </desc>
|
---|
8283 | </attribute>
|
---|
8284 |
|
---|
8285 | <attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes">
|
---|
8286 | <desc>
|
---|
8287 | Array of current known facilities. Only returns facilities where a status is known,
|
---|
8288 | e.g. facilities with an unknown status will not be returned.
|
---|
8289 | </desc>
|
---|
8290 | </attribute>
|
---|
8291 |
|
---|
8292 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
8293 | <desc>Guest system memory balloon size in megabytes (transient property).</desc>
|
---|
8294 | </attribute>
|
---|
8295 |
|
---|
8296 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
8297 | <desc>Interval to update guest statistics in seconds.</desc>
|
---|
8298 | </attribute>
|
---|
8299 |
|
---|
8300 | <method name="internalGetStatistics">
|
---|
8301 | <desc>
|
---|
8302 | Internal method; do not use as it might change at any time.
|
---|
8303 | </desc>
|
---|
8304 | <param name="cpuUser" type="unsigned long" dir="out">
|
---|
8305 | <desc>Percentage of processor time spent in user mode as seen by the guest.</desc>
|
---|
8306 | </param>
|
---|
8307 | <param name="cpuKernel" type="unsigned long" dir="out">
|
---|
8308 | <desc>Percentage of processor time spent in kernel mode as seen by the guest.</desc>
|
---|
8309 | </param>
|
---|
8310 | <param name="cpuIdle" type="unsigned long" dir="out">
|
---|
8311 | <desc>Percentage of processor time spent idling as seen by the guest.</desc>
|
---|
8312 | </param>
|
---|
8313 | <param name="memTotal" type="unsigned long" dir="out">
|
---|
8314 | <desc>Total amount of physical guest RAM.</desc>
|
---|
8315 | </param>
|
---|
8316 | <param name="memFree" type="unsigned long" dir="out">
|
---|
8317 | <desc>Free amount of physical guest RAM.</desc>
|
---|
8318 | </param>
|
---|
8319 | <param name="memBalloon" type="unsigned long" dir="out">
|
---|
8320 | <desc>Amount of ballooned physical guest RAM.</desc>
|
---|
8321 | </param>
|
---|
8322 | <param name="memShared" type="unsigned long" dir="out">
|
---|
8323 | <desc>Amount of shared physical guest RAM.</desc>
|
---|
8324 | </param>
|
---|
8325 | <param name="memCache" type="unsigned long" dir="out">
|
---|
8326 | <desc>Total amount of guest (disk) cache memory.</desc>
|
---|
8327 | </param>
|
---|
8328 | <param name="pagedTotal" type="unsigned long" dir="out">
|
---|
8329 | <desc>Total amount of space in the page file.</desc>
|
---|
8330 | </param>
|
---|
8331 | <param name="memAllocTotal" type="unsigned long" dir="out">
|
---|
8332 | <desc>Total amount of memory allocated by the hypervisor.</desc>
|
---|
8333 | </param>
|
---|
8334 | <param name="memFreeTotal" type="unsigned long" dir="out">
|
---|
8335 | <desc>Total amount of free memory available in the hypervisor.</desc>
|
---|
8336 | </param>
|
---|
8337 | <param name="memBalloonTotal" type="unsigned long" dir="out">
|
---|
8338 | <desc>Total amount of memory ballooned by the hypervisor.</desc>
|
---|
8339 | </param>
|
---|
8340 | <param name="memSharedTotal" type="unsigned long" dir="out">
|
---|
8341 | <desc>Total amount of shared memory in the hypervisor.</desc>
|
---|
8342 | </param>
|
---|
8343 | </method>
|
---|
8344 |
|
---|
8345 | <method name="getFacilityStatus">
|
---|
8346 | <desc>
|
---|
8347 | Get the current status of a Guest Additions facility.
|
---|
8348 | </desc>
|
---|
8349 | <param name="facility" type="AdditionsFacilityType" dir="in">
|
---|
8350 | <desc>Facility to check status for.</desc>
|
---|
8351 | </param>
|
---|
8352 | <param name="timestamp" type="long long" dir="out">
|
---|
8353 | <desc>Timestamp (in ms) of last status update seen by the host.</desc>
|
---|
8354 | </param>
|
---|
8355 | <param name="status" type="AdditionsFacilityStatus" dir="return">
|
---|
8356 | <desc>The current (latest) facility status.</desc>
|
---|
8357 | </param>
|
---|
8358 | </method>
|
---|
8359 |
|
---|
8360 | <method name="getAdditionsStatus">
|
---|
8361 | <desc>
|
---|
8362 | Retrieve the current status of a certain Guest Additions run level.
|
---|
8363 |
|
---|
8364 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
8365 | Wrong status level specified.
|
---|
8366 | </result>
|
---|
8367 |
|
---|
8368 | </desc>
|
---|
8369 | <param name="level" type="AdditionsRunLevelType" dir="in">
|
---|
8370 | <desc>Status level to check</desc>
|
---|
8371 | </param>
|
---|
8372 | <param name="active" type="boolean" dir="return">
|
---|
8373 | <desc>Flag whether the status level has been reached or not</desc>
|
---|
8374 | </param>
|
---|
8375 | </method>
|
---|
8376 |
|
---|
8377 | <method name="setCredentials">
|
---|
8378 | <desc>
|
---|
8379 | Store login credentials that can be queried by guest operating
|
---|
8380 | systems with Additions installed. The credentials are transient
|
---|
8381 | to the session and the guest may also choose to erase them. Note
|
---|
8382 | that the caller cannot determine whether the guest operating system
|
---|
8383 | has queried or made use of the credentials.
|
---|
8384 |
|
---|
8385 | <result name="VBOX_E_VM_ERROR">
|
---|
8386 | VMM device is not available.
|
---|
8387 | </result>
|
---|
8388 |
|
---|
8389 | </desc>
|
---|
8390 | <param name="userName" type="wstring" dir="in">
|
---|
8391 | <desc>User name string, can be empty</desc>
|
---|
8392 | </param>
|
---|
8393 | <param name="password" type="wstring" dir="in">
|
---|
8394 | <desc>Password string, can be empty</desc>
|
---|
8395 | </param>
|
---|
8396 | <param name="domain" type="wstring" dir="in">
|
---|
8397 | <desc>Domain name (guest logon scheme specific), can be empty</desc>
|
---|
8398 | </param>
|
---|
8399 | <param name="allowInteractiveLogon" type="boolean" dir="in">
|
---|
8400 | <desc>
|
---|
8401 | Flag whether the guest should alternatively allow the user to
|
---|
8402 | interactively specify different credentials. This flag might
|
---|
8403 | not be supported by all versions of the Additions.
|
---|
8404 | </desc>
|
---|
8405 | </param>
|
---|
8406 | </method>
|
---|
8407 |
|
---|
8408 | <method name="executeProcess">
|
---|
8409 | <desc>
|
---|
8410 | Executes an existing program inside the guest VM.
|
---|
8411 |
|
---|
8412 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8413 | Could not execute process.
|
---|
8414 | </result>
|
---|
8415 |
|
---|
8416 | </desc>
|
---|
8417 | <param name="execName" type="wstring" dir="in">
|
---|
8418 | <desc>
|
---|
8419 | Full path name of the command to execute on the guest; the
|
---|
8420 | commands has to exists in the guest VM in order to be executed.
|
---|
8421 | </desc>
|
---|
8422 | </param>
|
---|
8423 | <param name="flags" type="unsigned long" dir="in">
|
---|
8424 | <desc>
|
---|
8425 | <link to="ExecuteProcessFlag"/> flags.
|
---|
8426 | </desc>
|
---|
8427 | </param>
|
---|
8428 | <param name="arguments" type="wstring" safearray="yes" dir="in">
|
---|
8429 | <desc>
|
---|
8430 | Array of arguments passed to the execution command.
|
---|
8431 | </desc>
|
---|
8432 | </param>
|
---|
8433 | <param name="environment" type="wstring" safearray="yes" dir="in">
|
---|
8434 | <desc>
|
---|
8435 | Environment variables that can be set while the command is being
|
---|
8436 | executed, in form of "NAME=VALUE"; one pair per entry. To unset a
|
---|
8437 | variable just set its name ("NAME") without a value.
|
---|
8438 | </desc>
|
---|
8439 | </param>
|
---|
8440 | <param name="userName" type="wstring" dir="in">
|
---|
8441 | <desc>
|
---|
8442 | User name under which the command will be executed; has to exist
|
---|
8443 | and have the appropriate rights to execute programs in the VM.
|
---|
8444 | </desc>
|
---|
8445 | </param>
|
---|
8446 | <param name="password" type="wstring" dir="in">
|
---|
8447 | <desc>
|
---|
8448 | Password of the user account specified.
|
---|
8449 | </desc>
|
---|
8450 | </param>
|
---|
8451 | <param name="timeoutMS" type="unsigned long" dir="in">
|
---|
8452 | <desc>
|
---|
8453 | The maximum timeout value (in msec) to wait for finished program
|
---|
8454 | execution. Pass 0 for an infinite timeout.
|
---|
8455 | </desc>
|
---|
8456 | </param>
|
---|
8457 | <param name="pid" type="unsigned long" dir="out">
|
---|
8458 | <desc>
|
---|
8459 | The PID (process ID) of the started command for later reference.
|
---|
8460 | </desc>
|
---|
8461 | </param>
|
---|
8462 | <param name="progress" type="IProgress" dir="return">
|
---|
8463 | <desc>Progress object to track the operation completion.</desc>
|
---|
8464 | </param>
|
---|
8465 | </method>
|
---|
8466 |
|
---|
8467 | <method name="getProcessOutput">
|
---|
8468 | <desc>
|
---|
8469 | Retrieves output of a formerly started process.
|
---|
8470 |
|
---|
8471 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8472 | Could not retrieve output.
|
---|
8473 | </result>
|
---|
8474 |
|
---|
8475 | </desc>
|
---|
8476 | <param name="pid" type="unsigned long" dir="in">
|
---|
8477 | <desc>
|
---|
8478 | Process id returned by earlier executeProcess() call.
|
---|
8479 | </desc>
|
---|
8480 | </param>
|
---|
8481 | <param name="flags" type="unsigned long" dir="in">
|
---|
8482 | <desc>
|
---|
8483 | <link to="ProcessOutputFlag"/> flags.
|
---|
8484 | </desc>
|
---|
8485 | </param>
|
---|
8486 | <param name="timeoutMS" type="unsigned long" dir="in">
|
---|
8487 | <desc>
|
---|
8488 | The maximum timeout value (in msec) to wait for output
|
---|
8489 | data. Pass 0 for an infinite timeout.
|
---|
8490 | </desc>
|
---|
8491 | </param>
|
---|
8492 | <param name="size" type="long long" dir="in">
|
---|
8493 | <desc>
|
---|
8494 | Size in bytes to read in the buffer.
|
---|
8495 | </desc>
|
---|
8496 | </param>
|
---|
8497 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
8498 | <desc>
|
---|
8499 | Buffer for retrieving the actual output. A data size of 0 means end of file
|
---|
8500 | if the requested size was not 0. This is the unprocessed
|
---|
8501 | output data, i.e. the line ending style depends on the platform of
|
---|
8502 | the system the server is running on.
|
---|
8503 | </desc>
|
---|
8504 | </param>
|
---|
8505 | </method>
|
---|
8506 |
|
---|
8507 | <method name="getProcessStatus">
|
---|
8508 | <desc>
|
---|
8509 | Retrieves status, exit code and the exit reason of a formerly started process.
|
---|
8510 |
|
---|
8511 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8512 | Process with specified PID was not found.
|
---|
8513 | </result>
|
---|
8514 |
|
---|
8515 | </desc>
|
---|
8516 | <param name="pid" type="unsigned long" dir="in">
|
---|
8517 | <desc>
|
---|
8518 | Process id returned by earlier executeProcess() call.
|
---|
8519 | </desc>
|
---|
8520 | </param>
|
---|
8521 | <param name="exitcode" type="unsigned long" dir="out">
|
---|
8522 | <desc>
|
---|
8523 | The exit code (if available).
|
---|
8524 | </desc>
|
---|
8525 | </param>
|
---|
8526 | <param name="flags" type="unsigned long" dir="out">
|
---|
8527 | <desc>
|
---|
8528 | Additional flags of process status. Not used at the moment and
|
---|
8529 | must be set to 0.
|
---|
8530 | </desc>
|
---|
8531 | </param>
|
---|
8532 | <param name="reason" type="ExecuteProcessStatus" dir="return">
|
---|
8533 | <desc>
|
---|
8534 | The current process status.
|
---|
8535 | </desc>
|
---|
8536 | </param>
|
---|
8537 | </method>
|
---|
8538 |
|
---|
8539 | <method name="copyToGuest">
|
---|
8540 | <desc>
|
---|
8541 | Copies files/directories from host to the guest.
|
---|
8542 |
|
---|
8543 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8544 | Error while copying.
|
---|
8545 | </result>
|
---|
8546 |
|
---|
8547 | </desc>
|
---|
8548 | <param name="source" type="wstring" dir="in">
|
---|
8549 | <desc>
|
---|
8550 | Source file on the host to copy.
|
---|
8551 | </desc>
|
---|
8552 | </param>
|
---|
8553 | <param name="dest" type="wstring" dir="in">
|
---|
8554 | <desc>
|
---|
8555 | Destination path on the guest.
|
---|
8556 | </desc>
|
---|
8557 | </param>
|
---|
8558 | <param name="userName" type="wstring" dir="in">
|
---|
8559 | <desc>
|
---|
8560 | User name under which the copy command will be executed; the
|
---|
8561 | user has to exist and have the appropriate rights to write to
|
---|
8562 | the destination path.
|
---|
8563 | </desc>
|
---|
8564 | </param>
|
---|
8565 | <param name="password" type="wstring" dir="in">
|
---|
8566 | <desc>
|
---|
8567 | Password of the user account specified.
|
---|
8568 | </desc>
|
---|
8569 | </param>
|
---|
8570 | <param name="flags" type="unsigned long" dir="in">
|
---|
8571 | <desc>
|
---|
8572 | <link to="CopyFileFlag"/> flags. Not used at the moment and should be set to 0.
|
---|
8573 | </desc>
|
---|
8574 | </param>
|
---|
8575 | <param name="progress" type="IProgress" dir="return">
|
---|
8576 | <desc>Progress object to track the operation completion.</desc>
|
---|
8577 | </param>
|
---|
8578 | </method>
|
---|
8579 |
|
---|
8580 | <method name="createDirectory">
|
---|
8581 | <desc>
|
---|
8582 | Creates a directory on the guest.
|
---|
8583 |
|
---|
8584 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8585 | Error while creating directory.
|
---|
8586 | </result>
|
---|
8587 |
|
---|
8588 | </desc>
|
---|
8589 | <param name="directory" type="wstring" dir="in">
|
---|
8590 | <desc>
|
---|
8591 | Directory to create.
|
---|
8592 | </desc>
|
---|
8593 | </param>
|
---|
8594 | <param name="userName" type="wstring" dir="in">
|
---|
8595 | <desc>
|
---|
8596 | User name under which the directory creation will be executed; the
|
---|
8597 | user has to exist and have the appropriate rights to create the
|
---|
8598 | desired directory.
|
---|
8599 | </desc>
|
---|
8600 | </param>
|
---|
8601 | <param name="password" type="wstring" dir="in">
|
---|
8602 | <desc>
|
---|
8603 | Password of the user account specified.
|
---|
8604 | </desc>
|
---|
8605 | </param>
|
---|
8606 | <param name="mode" type="unsigned long" dir="in">
|
---|
8607 | <desc>
|
---|
8608 | File mode.
|
---|
8609 | </desc>
|
---|
8610 | </param>
|
---|
8611 | <param name="flags" type="unsigned long" dir="in">
|
---|
8612 | <desc>
|
---|
8613 | <link to="CreateDirectoryFlag"/> flags.
|
---|
8614 | </desc>
|
---|
8615 | </param>
|
---|
8616 | <param name="progress" type="IProgress" dir="return">
|
---|
8617 | <desc>Progress object to track the operation completion.</desc>
|
---|
8618 | </param>
|
---|
8619 | </method>
|
---|
8620 |
|
---|
8621 | <method name="setProcessInput">
|
---|
8622 | <desc>
|
---|
8623 | Sends input into a formerly started process.
|
---|
8624 |
|
---|
8625 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8626 | Could not send input.
|
---|
8627 | </result>
|
---|
8628 |
|
---|
8629 | </desc>
|
---|
8630 | <param name="pid" type="unsigned long" dir="in">
|
---|
8631 | <desc>
|
---|
8632 | Process id returned by earlier executeProcess() call.
|
---|
8633 | </desc>
|
---|
8634 | </param>
|
---|
8635 | <param name="flags" type="unsigned long" dir="in">
|
---|
8636 | <desc>
|
---|
8637 | <link to="ProcessInputFlag"/> flags.
|
---|
8638 | </desc>
|
---|
8639 | </param>
|
---|
8640 | <param name="timeoutMS" type="unsigned long" dir="in">
|
---|
8641 | <desc>
|
---|
8642 | The maximum timeout value (in msec) to wait for getting the
|
---|
8643 | data transfered to the guest. Pass 0 for an infinite timeout.
|
---|
8644 | </desc>
|
---|
8645 | </param>
|
---|
8646 | <param name="data" type="octet" dir="in" safearray="yes">
|
---|
8647 | <desc>
|
---|
8648 | Buffer of input data to send to the started process to.
|
---|
8649 | </desc>
|
---|
8650 | </param>
|
---|
8651 | <param name="written" type="unsigned long" dir="return">
|
---|
8652 | <desc>
|
---|
8653 | Number of bytes written.
|
---|
8654 | </desc>
|
---|
8655 | </param>
|
---|
8656 | </method>
|
---|
8657 |
|
---|
8658 | <method name="updateGuestAdditions">
|
---|
8659 | <desc>
|
---|
8660 | Updates already installed Guest Additions in a VM
|
---|
8661 | (Windows guests only).
|
---|
8662 |
|
---|
8663 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8664 | Error while updating.
|
---|
8665 | </result>
|
---|
8666 |
|
---|
8667 | </desc>
|
---|
8668 | <param name="source" type="wstring" dir="in">
|
---|
8669 | <desc>
|
---|
8670 | Path to the Guest Additions .ISO file to use for the upate.
|
---|
8671 | </desc>
|
---|
8672 | </param>
|
---|
8673 | <param name="flags" type="unsigned long" dir="in">
|
---|
8674 | <desc>
|
---|
8675 | <link to="AdditionsUpdateFlag"/> flags.
|
---|
8676 | </desc>
|
---|
8677 | </param>
|
---|
8678 | <param name="progress" type="IProgress" dir="return">
|
---|
8679 | <desc>Progress object to track the operation completion.</desc>
|
---|
8680 | </param>
|
---|
8681 | </method>
|
---|
8682 |
|
---|
8683 | </interface>
|
---|
8684 |
|
---|
8685 |
|
---|
8686 | <!--
|
---|
8687 | // IProgress
|
---|
8688 | /////////////////////////////////////////////////////////////////////////
|
---|
8689 | -->
|
---|
8690 |
|
---|
8691 | <interface
|
---|
8692 | name="IProgress" extends="$unknown"
|
---|
8693 | uuid="A163C98F-8635-4AA8-B770-A9941737F3EF"
|
---|
8694 | wsmap="managed"
|
---|
8695 | >
|
---|
8696 | <desc>
|
---|
8697 | The IProgress interface is used to track and control
|
---|
8698 | asynchronous tasks within VirtualBox.
|
---|
8699 |
|
---|
8700 | An instance of this is returned every time VirtualBox starts
|
---|
8701 | an asynchronous task (in other words, a separate thread) which
|
---|
8702 | continues to run after a method call returns. For example,
|
---|
8703 | <link to="IConsole::saveState" />, which saves the state of
|
---|
8704 | a running virtual machine, can take a long time to complete.
|
---|
8705 | To be able to display a progress bar, a user interface such as
|
---|
8706 | the VirtualBox graphical user interface can use the IProgress
|
---|
8707 | object returned by that method.
|
---|
8708 |
|
---|
8709 | Note that IProgress is a "read-only" interface in the sense
|
---|
8710 | that only the VirtualBox internals behind the Main API can
|
---|
8711 | create and manipulate progress objects, whereas client code
|
---|
8712 | can only use the IProgress object to monitor a task's
|
---|
8713 | progress and, if <link to="#cancelable" /> is @c true,
|
---|
8714 | cancel the task by calling <link to="#cancel" />.
|
---|
8715 |
|
---|
8716 | A task represented by IProgress consists of either one or
|
---|
8717 | several sub-operations that run sequentially, one by one (see
|
---|
8718 | <link to="#operation" /> and <link to="#operationCount" />).
|
---|
8719 | Every operation is identified by a number (starting from 0)
|
---|
8720 | and has a separate description.
|
---|
8721 |
|
---|
8722 | You can find the individual percentage of completion of the current
|
---|
8723 | operation in <link to="#operationPercent" /> and the
|
---|
8724 | percentage of completion of the task as a whole
|
---|
8725 | in <link to="#percent" />.
|
---|
8726 |
|
---|
8727 | Similarly, you can wait for the completion of a particular
|
---|
8728 | operation via <link to="#waitForOperationCompletion" /> or
|
---|
8729 | for the completion of the whole task via
|
---|
8730 | <link to="#waitForCompletion" />.
|
---|
8731 | </desc>
|
---|
8732 |
|
---|
8733 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
8734 | <desc>ID of the task.</desc>
|
---|
8735 | </attribute>
|
---|
8736 |
|
---|
8737 | <attribute name="description" type="wstring" readonly="yes">
|
---|
8738 | <desc>Description of the task.</desc>
|
---|
8739 | </attribute>
|
---|
8740 |
|
---|
8741 | <attribute name="initiator" type="$unknown" readonly="yes">
|
---|
8742 | <desc>Initiator of the task.</desc>
|
---|
8743 | </attribute>
|
---|
8744 |
|
---|
8745 | <attribute name="cancelable" type="boolean" readonly="yes">
|
---|
8746 | <desc>Whether the task can be interrupted.</desc>
|
---|
8747 | </attribute>
|
---|
8748 |
|
---|
8749 | <attribute name="percent" type="unsigned long" readonly="yes">
|
---|
8750 | <desc>
|
---|
8751 | Current progress value of the task as a whole, in percent.
|
---|
8752 | This value depends on how many operations are already complete.
|
---|
8753 | Returns 100 if <link to="#completed" /> is @c true.
|
---|
8754 | </desc>
|
---|
8755 | </attribute>
|
---|
8756 |
|
---|
8757 | <attribute name="timeRemaining" type="long" readonly="yes">
|
---|
8758 | <desc>
|
---|
8759 | Estimated remaining time until the task completes, in
|
---|
8760 | seconds. Returns 0 once the task has completed; returns -1
|
---|
8761 | if the remaining time cannot be computed, in particular if
|
---|
8762 | the current progress is 0.
|
---|
8763 |
|
---|
8764 | Even if a value is returned, the estimate will be unreliable
|
---|
8765 | for low progress values. It will become more reliable as the
|
---|
8766 | task progresses; it is not recommended to display an ETA
|
---|
8767 | before at least 20% of a task have completed.
|
---|
8768 | </desc>
|
---|
8769 | </attribute>
|
---|
8770 |
|
---|
8771 | <attribute name="completed" type="boolean" readonly="yes">
|
---|
8772 | <desc>Whether the task has been completed.</desc>
|
---|
8773 | </attribute>
|
---|
8774 |
|
---|
8775 | <attribute name="canceled" type="boolean" readonly="yes">
|
---|
8776 | <desc>Whether the task has been canceled.</desc>
|
---|
8777 | </attribute>
|
---|
8778 |
|
---|
8779 | <attribute name="resultCode" type="long" readonly="yes">
|
---|
8780 | <desc>
|
---|
8781 | Result code of the progress task.
|
---|
8782 | Valid only if <link to="#completed"/> is @c true.
|
---|
8783 | </desc>
|
---|
8784 | </attribute>
|
---|
8785 |
|
---|
8786 | <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
8787 | <desc>
|
---|
8788 | Extended information about the unsuccessful result of the
|
---|
8789 | progress operation. May be @c null if no extended information
|
---|
8790 | is available.
|
---|
8791 | Valid only if <link to="#completed"/> is @c true and
|
---|
8792 | <link to="#resultCode"/> indicates a failure.
|
---|
8793 | </desc>
|
---|
8794 | </attribute>
|
---|
8795 |
|
---|
8796 | <attribute name="operationCount" type="unsigned long" readonly="yes">
|
---|
8797 | <desc>
|
---|
8798 | Number of sub-operations this task is divided into.
|
---|
8799 | Every task consists of at least one suboperation.
|
---|
8800 | </desc>
|
---|
8801 | </attribute>
|
---|
8802 |
|
---|
8803 | <attribute name="operation" type="unsigned long" readonly="yes">
|
---|
8804 | <desc>Number of the sub-operation being currently executed.</desc>
|
---|
8805 | </attribute>
|
---|
8806 |
|
---|
8807 | <attribute name="operationDescription" type="wstring" readonly="yes">
|
---|
8808 | <desc>
|
---|
8809 | Description of the sub-operation being currently executed.
|
---|
8810 | </desc>
|
---|
8811 | </attribute>
|
---|
8812 |
|
---|
8813 | <attribute name="operationPercent" type="unsigned long" readonly="yes">
|
---|
8814 | <desc>Progress value of the current sub-operation only, in percent.</desc>
|
---|
8815 | </attribute>
|
---|
8816 |
|
---|
8817 | <attribute name="operationWeight" type="unsigned long" readonly="yes">
|
---|
8818 | <desc>Weight value of the current sub-operation only.</desc>
|
---|
8819 | </attribute>
|
---|
8820 |
|
---|
8821 | <attribute name="timeout" type="unsigned long">
|
---|
8822 | <desc>
|
---|
8823 | When non-zero, this specifies the number of milliseconds after which
|
---|
8824 | the operation will automatically be canceled. This can only be set on
|
---|
8825 | cancelable objects.
|
---|
8826 | </desc>
|
---|
8827 | </attribute>
|
---|
8828 |
|
---|
8829 | <method name="setCurrentOperationProgress">
|
---|
8830 | <desc>Internal method, not to be called externally.</desc>
|
---|
8831 | <param name="percent" type="unsigned long" dir="in" />
|
---|
8832 | </method>
|
---|
8833 | <method name="setNextOperation">
|
---|
8834 | <desc>Internal method, not to be called externally.</desc>
|
---|
8835 | <param name="nextOperationDescription" type="wstring" dir="in" />
|
---|
8836 | <param name="nextOperationsWeight" type="unsigned long" dir="in" />
|
---|
8837 | </method>
|
---|
8838 |
|
---|
8839 | <method name="waitForCompletion">
|
---|
8840 | <desc>
|
---|
8841 | Waits until the task is done (including all sub-operations)
|
---|
8842 | with a given timeout in milliseconds; specify -1 for an indefinite wait.
|
---|
8843 |
|
---|
8844 | Note that the VirtualBox/XPCOM/COM/native event queues of the calling
|
---|
8845 | thread are not processed while waiting. Neglecting event queues may
|
---|
8846 | have dire consequences (degrade performance, resource hogs,
|
---|
8847 | deadlocks, etc.), this is specially so for the main thread on
|
---|
8848 | platforms using XPCOM. Callers are adviced wait for short periods
|
---|
8849 | and service their event queues between calls, or to create a worker
|
---|
8850 | thread to do the waiting.
|
---|
8851 |
|
---|
8852 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8853 | Failed to wait for task completion.
|
---|
8854 | </result>
|
---|
8855 | </desc>
|
---|
8856 |
|
---|
8857 | <param name="timeout" type="long" dir="in">
|
---|
8858 | <desc>
|
---|
8859 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
8860 | </desc>
|
---|
8861 | </param>
|
---|
8862 | </method>
|
---|
8863 |
|
---|
8864 | <method name="waitForOperationCompletion">
|
---|
8865 | <desc>
|
---|
8866 | Waits until the given operation is done with a given timeout in
|
---|
8867 | milliseconds; specify -1 for an indefinite wait.
|
---|
8868 |
|
---|
8869 | See <link to="#waitForCompletion"> for event queue considerations.</link>
|
---|
8870 |
|
---|
8871 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8872 | Failed to wait for operation completion.
|
---|
8873 | </result>
|
---|
8874 |
|
---|
8875 | </desc>
|
---|
8876 | <param name="operation" type="unsigned long" dir="in">
|
---|
8877 | <desc>
|
---|
8878 | Number of the operation to wait for.
|
---|
8879 | Must be less than <link to="#operationCount"/>.
|
---|
8880 | </desc>
|
---|
8881 | </param>
|
---|
8882 | <param name="timeout" type="long" dir="in">
|
---|
8883 | <desc>
|
---|
8884 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
8885 | </desc>
|
---|
8886 | </param>
|
---|
8887 | </method>
|
---|
8888 |
|
---|
8889 | <method name="cancel">
|
---|
8890 | <desc>
|
---|
8891 | Cancels the task.
|
---|
8892 | <note>
|
---|
8893 | If <link to="#cancelable"/> is @c false, then this method will fail.
|
---|
8894 | </note>
|
---|
8895 |
|
---|
8896 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8897 | Operation cannot be canceled.
|
---|
8898 | </result>
|
---|
8899 |
|
---|
8900 | </desc>
|
---|
8901 | </method>
|
---|
8902 |
|
---|
8903 | </interface>
|
---|
8904 |
|
---|
8905 | <!--
|
---|
8906 | // ISnapshot
|
---|
8907 | /////////////////////////////////////////////////////////////////////////
|
---|
8908 | -->
|
---|
8909 |
|
---|
8910 | <interface
|
---|
8911 | name="ISnapshot" extends="$unknown"
|
---|
8912 | uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
|
---|
8913 | wsmap="managed"
|
---|
8914 | >
|
---|
8915 | <desc>
|
---|
8916 | The ISnapshot interface represents a snapshot of the virtual
|
---|
8917 | machine.
|
---|
8918 |
|
---|
8919 | Together with the differencing media that are created
|
---|
8920 | when a snapshot is taken, a machine can be brought back to
|
---|
8921 | the exact state it was in when the snapshot was taken.
|
---|
8922 |
|
---|
8923 | The ISnapshot interface has no methods, only attributes; snapshots
|
---|
8924 | are controlled through methods of the <link to="IConsole" /> interface
|
---|
8925 | which also manage the media associated with the snapshot.
|
---|
8926 | The following operations exist:
|
---|
8927 |
|
---|
8928 | <ul>
|
---|
8929 | <li><link to="IConsole::takeSnapshot"/> creates a new snapshot
|
---|
8930 | by creating new, empty differencing images for the machine's
|
---|
8931 | media and saving the VM settings and (if the VM is running)
|
---|
8932 | the current VM state in the snapshot.
|
---|
8933 |
|
---|
8934 | The differencing images will then receive all data written to
|
---|
8935 | the machine's media, while their parent (base) images
|
---|
8936 | remain unmodified after the snapshot has been taken (see
|
---|
8937 | <link to="IMedium" /> for details about differencing images).
|
---|
8938 | This simplifies restoring a machine to the state of a snapshot:
|
---|
8939 | only the differencing images need to be deleted.
|
---|
8940 |
|
---|
8941 | The current machine state is not changed by taking a snapshot
|
---|
8942 | except that <link to="IMachine::currentSnapshot" /> is set to
|
---|
8943 | the newly created snapshot, which is also added to the machine's
|
---|
8944 | snapshots tree.
|
---|
8945 | </li>
|
---|
8946 |
|
---|
8947 | <li><link to="IConsole::restoreSnapshot"/> resets a machine to
|
---|
8948 | the state of a previous snapshot by deleting the differencing
|
---|
8949 | image of each of the machine's media and setting the machine's
|
---|
8950 | settings and state to the state that was saved in the snapshot (if any).
|
---|
8951 |
|
---|
8952 | This destroys the machine's current state. After calling this,
|
---|
8953 | <link to="IMachine::currentSnapshot" /> points to the snapshot
|
---|
8954 | that was restored.
|
---|
8955 | </li>
|
---|
8956 |
|
---|
8957 | <li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
|
---|
8958 | without affecting the current machine state.
|
---|
8959 |
|
---|
8960 | This does not change the current machine state, but instead frees the
|
---|
8961 | resources allocated when the snapshot was taken: the settings and machine
|
---|
8962 | state file are deleted (if any), and the snapshot's differencing image for
|
---|
8963 | each of the machine's media gets merged with its parent image.
|
---|
8964 |
|
---|
8965 | Neither the current machine state nor other snapshots are affected
|
---|
8966 | by this operation, except that parent media will be modified
|
---|
8967 | to contain the disk data associated with the snapshot being deleted.
|
---|
8968 |
|
---|
8969 | When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
|
---|
8970 | attribute is set to the current snapshot's parent or NULL if it
|
---|
8971 | has no parent. Otherwise the attribute is unchanged.
|
---|
8972 | </li>
|
---|
8973 | </ul>
|
---|
8974 |
|
---|
8975 | Each snapshot contains a copy of virtual machine's settings (hardware
|
---|
8976 | configuration etc.). This copy is contained in an immutable (read-only)
|
---|
8977 | instance of <link to="IMachine" /> which is available from the snapshot's
|
---|
8978 | <link to="#machine" /> attribute. When restoring the snapshot, these
|
---|
8979 | settings are copied back to the original machine.
|
---|
8980 |
|
---|
8981 | In addition, if the machine was running when the
|
---|
8982 | snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
|
---|
8983 | the current VM state is saved in the snapshot (similarly to what happens
|
---|
8984 | when a VM's state is saved). The snapshot is then said to be <i>online</i>
|
---|
8985 | because when restoring it, the VM will be running.
|
---|
8986 |
|
---|
8987 | If the machine was in <link to="MachineState_Saved">saved</link> saved,
|
---|
8988 | the snapshot receives a copy of the execution state file
|
---|
8989 | (<link to="IMachine::stateFilePath"/>).
|
---|
8990 |
|
---|
8991 | Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
|
---|
8992 | or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
|
---|
8993 | it then contains a so-called "zero execution state", representing a
|
---|
8994 | machine that is powered off.
|
---|
8995 | </desc>
|
---|
8996 |
|
---|
8997 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
8998 | <desc>UUID of the snapshot.</desc>
|
---|
8999 | </attribute>
|
---|
9000 |
|
---|
9001 | <attribute name="name" type="wstring">
|
---|
9002 | <desc>Short name of the snapshot.
|
---|
9003 | <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
|
---|
9004 | be called implicitly.</note>
|
---|
9005 | </desc>
|
---|
9006 | </attribute>
|
---|
9007 |
|
---|
9008 | <attribute name="description" type="wstring">
|
---|
9009 | <desc>Optional description of the snapshot.
|
---|
9010 | <note>Setting this attribute causes <link to="IMachine::saveSettings" /> to
|
---|
9011 | be called implicitly.</note>
|
---|
9012 | </desc>
|
---|
9013 | </attribute>
|
---|
9014 |
|
---|
9015 | <attribute name="timeStamp" type="long long" readonly="yes">
|
---|
9016 | <desc>
|
---|
9017 | Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
|
---|
9018 | </desc>
|
---|
9019 | </attribute>
|
---|
9020 |
|
---|
9021 | <attribute name="online" type="boolean" readonly="yes">
|
---|
9022 | <desc>
|
---|
9023 | @c true if this snapshot is an online snapshot and @c false otherwise.
|
---|
9024 |
|
---|
9025 | When this attribute is @c true, the
|
---|
9026 | <link to="IMachine::stateFilePath"/> attribute of the
|
---|
9027 | <link to="#machine"/> object associated with this snapshot
|
---|
9028 | will point to the saved state file. Otherwise, it will be
|
---|
9029 | an empty string.
|
---|
9030 | </desc>
|
---|
9031 | </attribute>
|
---|
9032 |
|
---|
9033 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
9034 | <desc>
|
---|
9035 | Virtual machine this snapshot is taken on. This object
|
---|
9036 | stores all settings the machine had when taking this snapshot.
|
---|
9037 | <note>
|
---|
9038 | The returned machine object is immutable, i.e. no
|
---|
9039 | any settings can be changed.
|
---|
9040 | </note>
|
---|
9041 | </desc>
|
---|
9042 | </attribute>
|
---|
9043 |
|
---|
9044 | <attribute name="parent" type="ISnapshot" readonly="yes">
|
---|
9045 | <desc>
|
---|
9046 | Parent snapshot (a snapshot this one is based on), or
|
---|
9047 | @c null if the snapshot has no parent (i.e. is the first snapshot).
|
---|
9048 | </desc>
|
---|
9049 | </attribute>
|
---|
9050 |
|
---|
9051 | <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
|
---|
9052 | <desc>
|
---|
9053 | Child snapshots (all snapshots having this one as a parent).
|
---|
9054 | By inspecting this attribute starting with a machine's root snapshot
|
---|
9055 | (which can be obtained by calling <link to="IMachine::findSnapshot" />
|
---|
9056 | with a @c null UUID), a machine's snapshots tree can be iterated over.
|
---|
9057 | </desc>
|
---|
9058 | </attribute>
|
---|
9059 |
|
---|
9060 | </interface>
|
---|
9061 |
|
---|
9062 |
|
---|
9063 | <!--
|
---|
9064 | // IMedium
|
---|
9065 | /////////////////////////////////////////////////////////////////////////
|
---|
9066 | -->
|
---|
9067 |
|
---|
9068 | <enum
|
---|
9069 | name="MediumState"
|
---|
9070 | uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
|
---|
9071 | >
|
---|
9072 | <desc>
|
---|
9073 | Virtual medium state.
|
---|
9074 | <see>IMedium</see>
|
---|
9075 | </desc>
|
---|
9076 |
|
---|
9077 | <const name="NotCreated" value="0">
|
---|
9078 | <desc>
|
---|
9079 | Associated medium storage does not exist (either was not created yet or
|
---|
9080 | was deleted).
|
---|
9081 | </desc>
|
---|
9082 | </const>
|
---|
9083 | <const name="Created" value="1">
|
---|
9084 | <desc>
|
---|
9085 | Associated storage exists and accessible; this gets set if the
|
---|
9086 | accessibility check performed by <link to="IMedium::refreshState" />
|
---|
9087 | was successful.
|
---|
9088 | </desc>
|
---|
9089 | </const>
|
---|
9090 | <const name="LockedRead" value="2">
|
---|
9091 | <desc>
|
---|
9092 | Medium is locked for reading (see <link to="IMedium::lockRead"/>),
|
---|
9093 | no data modification is possible.
|
---|
9094 | </desc>
|
---|
9095 | </const>
|
---|
9096 | <const name="LockedWrite" value="3">
|
---|
9097 | <desc>
|
---|
9098 | Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
|
---|
9099 | no concurrent data reading or modification is possible.
|
---|
9100 | </desc>
|
---|
9101 | </const>
|
---|
9102 | <const name="Inaccessible" value="4">
|
---|
9103 | <desc>
|
---|
9104 | Medium accessibility check (see <link to="IMedium::refreshState" />) has
|
---|
9105 | not yet been performed, or else, associated medium storage is not
|
---|
9106 | accessible. In the first case, <link to="IMedium::lastAccessError"/>
|
---|
9107 | is empty, in the second case, it describes the error that occurred.
|
---|
9108 | </desc>
|
---|
9109 | </const>
|
---|
9110 | <const name="Creating" value="5">
|
---|
9111 | <desc>
|
---|
9112 | Associated medium storage is being created.
|
---|
9113 | </desc>
|
---|
9114 | </const>
|
---|
9115 | <const name="Deleting" value="6">
|
---|
9116 | <desc>
|
---|
9117 | Associated medium storage is being deleted.
|
---|
9118 | </desc>
|
---|
9119 | </const>
|
---|
9120 | </enum>
|
---|
9121 |
|
---|
9122 | <enum
|
---|
9123 | name="MediumType"
|
---|
9124 | uuid="fe663fb5-c244-4e1b-9d81-c628b417dd04"
|
---|
9125 | >
|
---|
9126 | <desc>
|
---|
9127 | Virtual medium type. For each <link to="IMedium" />, this defines how the medium is
|
---|
9128 | attached to a virtual machine (see <link to="IMediumAttachment" />) and what happens
|
---|
9129 | when a snapshot (see <link to="ISnapshot" />) is taken of a virtual machine which has
|
---|
9130 | the medium attached. At the moment DVD and floppy media are always of type "writethrough".
|
---|
9131 | </desc>
|
---|
9132 |
|
---|
9133 | <const name="Normal" value="0">
|
---|
9134 | <desc>
|
---|
9135 | Normal medium (attached directly or indirectly, preserved
|
---|
9136 | when taking snapshots).
|
---|
9137 | </desc>
|
---|
9138 | </const>
|
---|
9139 | <const name="Immutable" value="1">
|
---|
9140 | <desc>
|
---|
9141 | Immutable medium (attached indirectly, changes are wiped out
|
---|
9142 | the next time the virtual machine is started).
|
---|
9143 | </desc>
|
---|
9144 | </const>
|
---|
9145 | <const name="Writethrough" value="2">
|
---|
9146 | <desc>
|
---|
9147 | Write through medium (attached directly, ignored when
|
---|
9148 | taking snapshots).
|
---|
9149 | </desc>
|
---|
9150 | </const>
|
---|
9151 | <const name="Shareable" value="3">
|
---|
9152 | <desc>
|
---|
9153 | Allow using this medium concurrently by several machines.
|
---|
9154 | <note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
|
---|
9155 | </desc>
|
---|
9156 | </const>
|
---|
9157 | <const name="Readonly" value="4">
|
---|
9158 | <desc>
|
---|
9159 | A readonly medium, which can of course be used by several machines.
|
---|
9160 | <note>Present and accepted since VirtualBox 4.0.</note>
|
---|
9161 | </desc>
|
---|
9162 | </const>
|
---|
9163 | <const name="MultiAttach" value="5">
|
---|
9164 | <desc>
|
---|
9165 | A medium which is is indirectly attached, so that one base medium can
|
---|
9166 | be used for several VMs which have their own differencing medium to
|
---|
9167 | store their modifications. In some sense a variant of Immutable
|
---|
9168 | with unset AutoReset flag in each differencing medium.
|
---|
9169 | <note>Present and accepted since VirtualBox 4.0.</note>
|
---|
9170 | </desc>
|
---|
9171 | </const>
|
---|
9172 | </enum>
|
---|
9173 |
|
---|
9174 | <enum
|
---|
9175 | name="MediumVariant"
|
---|
9176 | uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
|
---|
9177 | >
|
---|
9178 | <desc>
|
---|
9179 | Virtual medium image variant. More than one flag may be set.
|
---|
9180 | <see>IMedium</see>
|
---|
9181 | </desc>
|
---|
9182 |
|
---|
9183 | <const name="Standard" value="0">
|
---|
9184 | <desc>
|
---|
9185 | No particular variant requested, results in using the backend default.
|
---|
9186 | </desc>
|
---|
9187 | </const>
|
---|
9188 | <const name="VmdkSplit2G" value="0x01">
|
---|
9189 | <desc>
|
---|
9190 | VMDK image split in chunks of less than 2GByte.
|
---|
9191 | </desc>
|
---|
9192 | </const>
|
---|
9193 | <const name="VmdkStreamOptimized" value="0x04">
|
---|
9194 | <desc>
|
---|
9195 | VMDK streamOptimized image. Special import/export format which is
|
---|
9196 | read-only/append-only.
|
---|
9197 | </desc>
|
---|
9198 | </const>
|
---|
9199 | <const name="VmdkESX" value="0x08">
|
---|
9200 | <desc>
|
---|
9201 | VMDK format variant used on ESX products.
|
---|
9202 | </desc>
|
---|
9203 | </const>
|
---|
9204 | <const name="Fixed" value="0x10000">
|
---|
9205 | <desc>
|
---|
9206 | Fixed image. Only allowed for base images.
|
---|
9207 | </desc>
|
---|
9208 | </const>
|
---|
9209 | <const name="Diff" value="0x20000">
|
---|
9210 | <desc>
|
---|
9211 | Differencing image. Only allowed for child images.
|
---|
9212 | </desc>
|
---|
9213 | </const>
|
---|
9214 | </enum>
|
---|
9215 |
|
---|
9216 | <interface
|
---|
9217 | name="IMediumAttachment" extends="$unknown"
|
---|
9218 | uuid="aa4b4840-934f-454d-9a28-23e8f4235edf"
|
---|
9219 | wsmap="struct"
|
---|
9220 | >
|
---|
9221 | <desc>
|
---|
9222 | The IMediumAttachment interface links storage media to virtual machines.
|
---|
9223 | For each medium (<link to="IMedium"/>) which has been attached to a
|
---|
9224 | storage controller (<link to="IStorageController"/>) of a machine
|
---|
9225 | (<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
|
---|
9226 | method, one instance of IMediumAttachment is added to the machine's
|
---|
9227 | <link to="IMachine::mediumAttachments"/> array attribute.
|
---|
9228 |
|
---|
9229 | Each medium attachment specifies the storage controller as well as a
|
---|
9230 | port and device number and the IMedium instance representing a virtual
|
---|
9231 | hard disk or floppy or DVD image.
|
---|
9232 |
|
---|
9233 | For removable media (DVDs or floppies), there are two additional
|
---|
9234 | options. For one, the IMedium instance can be @c null to represent
|
---|
9235 | an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
|
---|
9236 | secondly, the medium can be one of the pseudo-media for host drives
|
---|
9237 | listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
|
---|
9238 |
|
---|
9239 | <h3>Attaching Hard Disks</h3>
|
---|
9240 |
|
---|
9241 | Hard disks are attached to virtual machines using the
|
---|
9242 | <link to="IMachine::attachDevice"/> method and detached using the
|
---|
9243 | <link to="IMachine::detachDevice"/> method. Depending on a medium's
|
---|
9244 | type (see <link to="IMedium::type" />), hard disks are attached either
|
---|
9245 | <i>directly</i> or <i>indirectly</i>.
|
---|
9246 |
|
---|
9247 | When a hard disk is being attached directly, it is associated with the
|
---|
9248 | virtual machine and used for hard disk operations when the machine is
|
---|
9249 | running. When a hard disk is being attached indirectly, a new differencing
|
---|
9250 | hard disk linked to it is implicitly created and this differencing hard
|
---|
9251 | disk is associated with the machine and used for hard disk operations.
|
---|
9252 | This also means that if <link to="IMachine::attachDevice"/> performs
|
---|
9253 | a direct attachment then the same hard disk will be returned in response
|
---|
9254 | to the subsequent <link to="IMachine::getMedium"/> call; however if
|
---|
9255 | an indirect attachment is performed then
|
---|
9256 | <link to="IMachine::getMedium"/> will return the implicitly created
|
---|
9257 | differencing hard disk, not the original one passed to <link
|
---|
9258 | to="IMachine::attachDevice"/>. In detail:
|
---|
9259 |
|
---|
9260 | <ul>
|
---|
9261 | <li><b>Normal base</b> hard disks that do not have children (i.e.
|
---|
9262 | differencing hard disks linked to them) and that are not already
|
---|
9263 | attached to virtual machines in snapshots are attached <b>directly</b>.
|
---|
9264 | Otherwise, they are attached <b>indirectly</b> because having
|
---|
9265 | dependent children or being part of the snapshot makes it impossible
|
---|
9266 | to modify hard disk contents without breaking the integrity of the
|
---|
9267 | dependent party. The <link to="IMedium::readOnly"/> attribute allows to
|
---|
9268 | quickly determine the kind of the attachment for the given hard
|
---|
9269 | disk. Note that if a normal base hard disk is to be indirectly
|
---|
9270 | attached to a virtual machine with snapshots then a special
|
---|
9271 | procedure called <i>smart attachment</i> is performed (see below).</li>
|
---|
9272 | <li><b>Normal differencing</b> hard disks are like normal base hard disks:
|
---|
9273 | they are attached <b>directly</b> if they do not have children and are
|
---|
9274 | not attached to virtual machines in snapshots, and <b>indirectly</b>
|
---|
9275 | otherwise. Note that the smart attachment procedure is never performed
|
---|
9276 | for differencing hard disks.</li>
|
---|
9277 | <li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
|
---|
9278 | they are designed to be non-writable. If an immutable hard disk is
|
---|
9279 | attached to a virtual machine with snapshots then a special
|
---|
9280 | procedure called smart attachment is performed (see below).</li>
|
---|
9281 | <li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
|
---|
9282 | also as designed. This also means that writethrough hard disks cannot
|
---|
9283 | have other hard disks linked to them at all.</li>
|
---|
9284 | <li><b>Shareable</b> hard disks are always attached <b>directly</b>,
|
---|
9285 | also as designed. This also means that shareable hard disks cannot
|
---|
9286 | have other hard disks linked to them at all. They behave almost
|
---|
9287 | like writethrough hard disks, except that shareable hard disks can
|
---|
9288 | be attached to several virtual machines which are running, allowing
|
---|
9289 | concurrent accesses. You need special cluster software running in
|
---|
9290 | the virtual machines to make use of such disks.</li>
|
---|
9291 | </ul>
|
---|
9292 |
|
---|
9293 | Note that the same hard disk, regardless of its type, may be attached to
|
---|
9294 | more than one virtual machine at a time. In this case, the machine that is
|
---|
9295 | started first gains exclusive access to the hard disk and attempts to
|
---|
9296 | start other machines having this hard disk attached will fail until the
|
---|
9297 | first machine is powered down.
|
---|
9298 |
|
---|
9299 | Detaching hard disks is performed in a <i>deferred</i> fashion. This means
|
---|
9300 | that the given hard disk remains associated with the given machine after a
|
---|
9301 | successful <link to="IMachine::detachDevice"/> call until
|
---|
9302 | <link to="IMachine::saveSettings"/> is called to save all changes to
|
---|
9303 | machine settings to disk. This deferring is necessary to guarantee that
|
---|
9304 | the hard disk configuration may be restored at any time by a call to
|
---|
9305 | <link to="IMachine::discardSettings"/> before the settings
|
---|
9306 | are saved (committed).
|
---|
9307 |
|
---|
9308 | Note that if <link to="IMachine::discardSettings"/> is called after
|
---|
9309 | indirectly attaching some hard disks to the machine but before a call to
|
---|
9310 | <link to="IMachine::saveSettings"/> is made, it will implicitly delete
|
---|
9311 | all differencing hard disks implicitly created by
|
---|
9312 | <link to="IMachine::attachDevice"/> for these indirect attachments.
|
---|
9313 | Such implicitly created hard disks will also be immediately deleted when
|
---|
9314 | detached explicitly using the <link to="IMachine::detachDevice"/>
|
---|
9315 | call if it is made before <link to="IMachine::saveSettings"/>. This
|
---|
9316 | implicit deletion is safe because newly created differencing hard
|
---|
9317 | disks do not contain any user data.
|
---|
9318 |
|
---|
9319 | However, keep in mind that detaching differencing hard disks that were
|
---|
9320 | implicitly created by <link to="IMachine::attachDevice"/>
|
---|
9321 | before the last <link to="IMachine::saveSettings"/> call will
|
---|
9322 | <b>not</b> implicitly delete them as they may already contain some data
|
---|
9323 | (for example, as a result of virtual machine execution). If these hard
|
---|
9324 | disks are no more necessary, the caller can always delete them explicitly
|
---|
9325 | using <link to="IMedium::deleteStorage"/> after they are actually de-associated
|
---|
9326 | from this machine by the <link to="IMachine::saveSettings"/> call.
|
---|
9327 |
|
---|
9328 | <h3>Smart Attachment</h3>
|
---|
9329 |
|
---|
9330 | When normal base or immutable hard disks are indirectly attached to a
|
---|
9331 | virtual machine then some additional steps are performed to make sure the
|
---|
9332 | virtual machine will have the most recent "view" of the hard disk being
|
---|
9333 | attached. These steps include walking through the machine's snapshots
|
---|
9334 | starting from the current one and going through ancestors up to the first
|
---|
9335 | snapshot. Hard disks attached to the virtual machine in all
|
---|
9336 | of the encountered snapshots are checked whether they are descendants of
|
---|
9337 | the given normal base or immutable hard disk. The first found child (which
|
---|
9338 | is the differencing hard disk) will be used instead of the normal base or
|
---|
9339 | immutable hard disk as a parent for creating a new differencing hard disk
|
---|
9340 | that will be actually attached to the machine. And only if no descendants
|
---|
9341 | are found or if the virtual machine does not have any snapshots then the
|
---|
9342 | normal base or immutable hard disk will be used itself as a parent for
|
---|
9343 | this differencing hard disk.
|
---|
9344 |
|
---|
9345 | It is easier to explain what smart attachment does using the
|
---|
9346 | following example:
|
---|
9347 | <pre>
|
---|
9348 | BEFORE attaching B.vdi: AFTER attaching B.vdi:
|
---|
9349 |
|
---|
9350 | Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
|
---|
9351 | Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
|
---|
9352 | Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
|
---|
9353 | Snapshot 4 (none) Snapshot 4 (none)
|
---|
9354 | CurState (none) CurState (D3->D2.vdi)
|
---|
9355 |
|
---|
9356 | NOT
|
---|
9357 | ...
|
---|
9358 | CurState (D3->B.vdi)
|
---|
9359 | </pre>
|
---|
9360 | The first column is the virtual machine configuration before the base hard
|
---|
9361 | disk <tt>B.vdi</tt> is attached, the second column shows the machine after
|
---|
9362 | this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
|
---|
9363 | mean that the hard disk that is actually attached to the machine is a
|
---|
9364 | differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
|
---|
9365 | another hard disk, <tt>B.vdi</tt>.
|
---|
9366 |
|
---|
9367 | As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
|
---|
9368 | from the machine before taking Snapshot 4. Later, after Snapshot 4 was
|
---|
9369 | taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
|
---|
9370 | dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
|
---|
9371 | it cannot be attached directly and needs an indirect attachment (i.e.
|
---|
9372 | implicit creation of a new differencing hard disk). Due to the smart
|
---|
9373 | attachment procedure, the new differencing hard disk
|
---|
9374 | (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
|
---|
9375 | <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
|
---|
9376 | <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
|
---|
9377 | machine.
|
---|
9378 |
|
---|
9379 | Note that if there is more than one descendant hard disk of the given base
|
---|
9380 | hard disk found in a snapshot, and there is an exact device, channel and
|
---|
9381 | bus match, then this exact match will be used. Otherwise, the youngest
|
---|
9382 | descendant will be picked up.
|
---|
9383 |
|
---|
9384 | There is one more important aspect of the smart attachment procedure which
|
---|
9385 | is not related to snapshots at all. Before walking through the snapshots
|
---|
9386 | as described above, the backup copy of the current list of hard disk
|
---|
9387 | attachment is searched for descendants. This backup copy is created when
|
---|
9388 | the hard disk configuration is changed for the first time after the last
|
---|
9389 | <link to="IMachine::saveSettings"/> call and used by
|
---|
9390 | <link to="IMachine::discardSettings"/> to undo the recent hard disk
|
---|
9391 | changes. When such a descendant is found in this backup copy, it will be
|
---|
9392 | simply re-attached back, without creating a new differencing hard disk for
|
---|
9393 | it. This optimization is necessary to make it possible to re-attach the
|
---|
9394 | base or immutable hard disk to a different bus, channel or device slot
|
---|
9395 | without losing the contents of the differencing hard disk actually
|
---|
9396 | attached to the machine in place of it.
|
---|
9397 |
|
---|
9398 | </desc>
|
---|
9399 |
|
---|
9400 | <attribute name="medium" type="IMedium" readonly="yes">
|
---|
9401 | <desc>Medium object associated with this attachment; it
|
---|
9402 | can be @c null for removable devices.</desc>
|
---|
9403 | </attribute>
|
---|
9404 |
|
---|
9405 | <attribute name="controller" type="wstring" readonly="yes">
|
---|
9406 | <desc>Name of the storage controller of this attachment; this
|
---|
9407 | refers to one of the controllers in <link to="IMachine::storageControllers" />
|
---|
9408 | by name.</desc>
|
---|
9409 | </attribute>
|
---|
9410 |
|
---|
9411 | <attribute name="port" type="long" readonly="yes">
|
---|
9412 | <desc>Port number of this attachment.
|
---|
9413 | See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
|
---|
9414 | </desc>
|
---|
9415 | </attribute>
|
---|
9416 |
|
---|
9417 | <attribute name="device" type="long" readonly="yes">
|
---|
9418 | <desc>Device slot number of this attachment.
|
---|
9419 | See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
|
---|
9420 | </desc>
|
---|
9421 | </attribute>
|
---|
9422 |
|
---|
9423 | <attribute name="type" type="DeviceType" readonly="yes">
|
---|
9424 | <desc>Device type of this attachment.</desc>
|
---|
9425 | </attribute>
|
---|
9426 |
|
---|
9427 | <attribute name="passthrough" type="boolean" readonly="yes">
|
---|
9428 | <desc>Pass I/O requests through to a device on the host.</desc>
|
---|
9429 | </attribute>
|
---|
9430 |
|
---|
9431 | <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
|
---|
9432 | <desc>The bandwidth group this medium attachment is assigned to.</desc>
|
---|
9433 | </attribute>
|
---|
9434 |
|
---|
9435 | </interface>
|
---|
9436 |
|
---|
9437 | <interface
|
---|
9438 | name="IMedium" extends="$unknown"
|
---|
9439 | uuid="9edda847-1279-4b0a-9af7-9d66251ccc18"
|
---|
9440 | wsmap="managed"
|
---|
9441 | >
|
---|
9442 | <desc>
|
---|
9443 | The IMedium interface represents virtual storage for a machine's
|
---|
9444 | hard disks, CD/DVD or floppy drives. It will typically represent
|
---|
9445 | a disk image on the host, for example a VDI or VMDK file representing
|
---|
9446 | a virtual hard disk, or an ISO or RAW file representing virtual
|
---|
9447 | removable media, but can also point to a network location (e.g.
|
---|
9448 | for iSCSI targets).
|
---|
9449 |
|
---|
9450 | Instances of IMedium are connected to virtual machines by way of medium
|
---|
9451 | attachments, which link the storage medium to a particular device slot
|
---|
9452 | of a storage controller of the virtual machine.
|
---|
9453 | In the VirtualBox API, virtual storage is therefore always represented
|
---|
9454 | by the following chain of object links:
|
---|
9455 |
|
---|
9456 | <ul>
|
---|
9457 | <li><link to="IMachine::storageControllers"/> contains an array of
|
---|
9458 | storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
|
---|
9459 | these are instances of <link to="IStorageController"/>).</li>
|
---|
9460 | <li><link to="IMachine::mediumAttachments"/> contains an array of
|
---|
9461 | medium attachments (instances of <link to="IMediumAttachment"/>
|
---|
9462 | created by <link to="IMachine::attachDevice" />),
|
---|
9463 | each containing a storage controller from the above array, a
|
---|
9464 | port/device specification, and an instance of IMedium representing
|
---|
9465 | the medium storage (image file).
|
---|
9466 |
|
---|
9467 | For removable media, the storage medium is optional; a medium
|
---|
9468 | attachment with no medium represents a CD/DVD or floppy drive
|
---|
9469 | with no medium inserted. By contrast, hard disk attachments
|
---|
9470 | will always have an IMedium object attached.</li>
|
---|
9471 | <li>Each IMedium in turn points to a storage unit (such as a file
|
---|
9472 | on the host computer or a network resource) that holds actual
|
---|
9473 | data. This location is represented by the <link to="#location"/>
|
---|
9474 | attribute.</li>
|
---|
9475 | </ul>
|
---|
9476 |
|
---|
9477 | Existing media are opened using <link to="IVirtualBox::openMedium"/>;
|
---|
9478 | new hard disk media can be created with the VirtualBox API using the
|
---|
9479 | <link to="IVirtualBox::createHardDisk"/> method. Differencing hard
|
---|
9480 | disks (see below) are usually implicitly created by VirtualBox as
|
---|
9481 | needed, but may also be created explicitly using <link to="#createDiffStorage"/>.
|
---|
9482 | VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
|
---|
9483 | should be created with external tools and then opened from within VirtualBox.
|
---|
9484 |
|
---|
9485 | Only for CD/DVDs and floppies, an IMedium instance can also represent a host
|
---|
9486 | drive. In that case the <link to="#id" /> attribute contains the UUID of
|
---|
9487 | one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
|
---|
9488 |
|
---|
9489 | <h3>Media registries</h3>
|
---|
9490 |
|
---|
9491 | When a medium has been opened or created using one of the aforementioned
|
---|
9492 | APIs, it becomes "known" to VirtualBox. Known media can be attached
|
---|
9493 | to virtual machines and accessed through <link to="IVirtualBox::findMedium"/>.
|
---|
9494 | They also appear in the global
|
---|
9495 | <link to="IVirtualBox::hardDisks" />,
|
---|
9496 | <link to="IVirtualBox::DVDImages" /> and
|
---|
9497 | <link to="IVirtualBox::floppyImages" /> arrays.
|
---|
9498 |
|
---|
9499 | Prior to VirtualBox 4.0, opening a medium added it to a global media registry
|
---|
9500 | in the VirtualBox.xml file, which was shared between all machines and made
|
---|
9501 | transporting machines and their media from one host to another difficult.
|
---|
9502 |
|
---|
9503 | Starting with VirtualBox 4.0, media are only added to a registry when they are
|
---|
9504 | <i>attached</i> to a machine using <link to="IMachine::attachDevice" />. For
|
---|
9505 | backwards compatibility, which registry a medium is added to depends on which
|
---|
9506 | VirtualBox version created a machine:
|
---|
9507 |
|
---|
9508 | <ul>
|
---|
9509 | <li>If the medium has first been attached to a machine which was created by
|
---|
9510 | VirtualBox 4.0 or later, it is added to that machine's media registry in
|
---|
9511 | the machine XML settings file. This way all information about a machine's
|
---|
9512 | media attachments is contained in a single file and can be transported
|
---|
9513 | easily.</li>
|
---|
9514 | <li>For older media attachments (i.e. if the medium was first attached to a
|
---|
9515 | machine which was created with a VirtualBox version before 4.0), media
|
---|
9516 | continue to be registered in the global VirtualBox settings file, for
|
---|
9517 | backwards compatibility.</li>
|
---|
9518 | </ul>
|
---|
9519 |
|
---|
9520 | See <link to="IVirtualBox::openMedium" /> for more information.
|
---|
9521 |
|
---|
9522 | Media are removed from media registries by the <link to="#close"/>,
|
---|
9523 | <link to="#deleteStorage"/> and <link to="#mergeTo"/> methods.
|
---|
9524 |
|
---|
9525 | <h3>Accessibility checks</h3>
|
---|
9526 |
|
---|
9527 | VirtualBox defers media accessibility checks until the <link to="#refreshState" />
|
---|
9528 | method is called explicitly on a medium. This is done to make the VirtualBox object
|
---|
9529 | ready for serving requests as fast as possible and let the end-user
|
---|
9530 | application decide if it needs to check media accessibility right away or not.
|
---|
9531 |
|
---|
9532 | As a result, when VirtualBox starts up (e.g. the VirtualBox
|
---|
9533 | object gets created for the first time), all known media are in the
|
---|
9534 | "Inaccessible" state, but the value of the <link to="#lastAccessError"/>
|
---|
9535 | attribute is an empty string because no actual accessibility check has
|
---|
9536 | been made yet.
|
---|
9537 |
|
---|
9538 | After calling <link to="#refreshState" />, a medium is considered
|
---|
9539 | <i>accessible</i> if its storage unit can be read. In that case, the
|
---|
9540 | <link to="#state"/> attribute has a value of "Created". If the storage
|
---|
9541 | unit cannot be read (for example, because it is located on a disconnected
|
---|
9542 | network resource, or was accidentally deleted outside VirtualBox),
|
---|
9543 | the medium is considered <i>inaccessible</i>, which is indicated by the
|
---|
9544 | "Inaccessible" state. The exact reason why the medium is inaccessible can be
|
---|
9545 | obtained by reading the <link to="#lastAccessError"/> attribute.
|
---|
9546 |
|
---|
9547 | <h3>Medium types</h3>
|
---|
9548 |
|
---|
9549 | There are five types of medium behavior which are stored in the
|
---|
9550 | <link to="#type"/> attribute (see <link to="MediumType" />) and
|
---|
9551 | which define the medium's behavior with attachments and snapshots.
|
---|
9552 |
|
---|
9553 | All media can be also divided in two groups: <i>base</i> media and
|
---|
9554 | <i>differencing</i> media. A base medium contains all sectors of the
|
---|
9555 | medium data in its own storage and therefore can be used independently.
|
---|
9556 | In contrast, a differencing medium is a "delta" to some other medium and
|
---|
9557 | contains only those sectors which differ from that other medium, which is
|
---|
9558 | then called a <i>parent</i>. The differencing medium is said to be
|
---|
9559 | <i>linked to</i> that parent. The parent may be itself a differencing
|
---|
9560 | medium, thus forming a chain of linked media. The last element in that
|
---|
9561 | chain must always be a base medium. Note that several differencing
|
---|
9562 | media may be linked to the same parent medium.
|
---|
9563 |
|
---|
9564 | Differencing media can be distinguished from base media by querying the
|
---|
9565 | <link to="#parent"/> attribute: base media do not have parents they would
|
---|
9566 | depend on, so the value of this attribute is always @c null for them.
|
---|
9567 | Using this attribute, it is possible to walk up the medium tree (from the
|
---|
9568 | child medium to its parent). It is also possible to walk down the tree
|
---|
9569 | using the <link to="#children"/> attribute.
|
---|
9570 |
|
---|
9571 | Note that the type of all differencing media is "normal"; all other
|
---|
9572 | values are meaningless for them. Base media may be of any type.
|
---|
9573 |
|
---|
9574 | <h3>Automatic composition of the file name part</h3>
|
---|
9575 |
|
---|
9576 | Another extension to the <link to="IMedium::location"/> attribute is that
|
---|
9577 | there is a possibility to cause VirtualBox to compose a unique value for
|
---|
9578 | the file name part of the location using the UUID of the hard disk. This
|
---|
9579 | applies only to hard disks in <link to="MediumState_NotCreated"/> state,
|
---|
9580 | e.g. before the storage unit is created, and works as follows. You set the
|
---|
9581 | value of the <link to="IMedium::location"/> attribute to a location
|
---|
9582 | specification which only contains the path specification but not the file
|
---|
9583 | name part and ends with either a forward slash or a backslash character.
|
---|
9584 | In response, VirtualBox will generate a new UUID for the hard disk and
|
---|
9585 | compose the file name using the following pattern:
|
---|
9586 | <pre>
|
---|
9587 | <path>/{<uuid>}.<ext>
|
---|
9588 | </pre>
|
---|
9589 | where <tt><path></tt> is the supplied path specification,
|
---|
9590 | <tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
|
---|
9591 | is the default extension for the storage format of this hard disk. After
|
---|
9592 | that, you may call any of the methods that create a new hard disk storage
|
---|
9593 | unit and they will use the generated UUID and file name.
|
---|
9594 | </desc>
|
---|
9595 |
|
---|
9596 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
9597 | <desc>
|
---|
9598 | UUID of the medium. For a newly created medium, this value is a randomly
|
---|
9599 | generated UUID.
|
---|
9600 |
|
---|
9601 | <note>
|
---|
9602 | For media in one of MediumState_NotCreated, MediumState_Creating or
|
---|
9603 | MediumState_Deleting states, the value of this property is undefined
|
---|
9604 | and will most likely be an empty UUID.
|
---|
9605 | </note>
|
---|
9606 | </desc>
|
---|
9607 | </attribute>
|
---|
9608 |
|
---|
9609 | <attribute name="description" type="wstring">
|
---|
9610 | <desc>
|
---|
9611 | Optional description of the medium. For a newly created medium the value
|
---|
9612 | of this attribute is an empty string.
|
---|
9613 |
|
---|
9614 | Medium types that don't support this attribute will return E_NOTIMPL in
|
---|
9615 | attempt to get or set this attribute's value.
|
---|
9616 |
|
---|
9617 | <note>
|
---|
9618 | For some storage types, reading this attribute may return an outdated
|
---|
9619 | (last known) value when <link to="#state"/> is <link
|
---|
9620 | to="MediumState_Inaccessible"/> or <link
|
---|
9621 | to="MediumState_LockedWrite"/> because the value of this attribute is
|
---|
9622 | stored within the storage unit itself. Also note that changing the
|
---|
9623 | attribute value is not possible in such case, as well as when the
|
---|
9624 | medium is the <link to="MediumState_LockedRead"/> state.
|
---|
9625 | </note>
|
---|
9626 | </desc>
|
---|
9627 | </attribute>
|
---|
9628 |
|
---|
9629 | <attribute name="state" type="MediumState" readonly="yes">
|
---|
9630 | <desc>
|
---|
9631 | Returns the current medium state, which is the last state set by
|
---|
9632 | the accessibility check performed by <link to="#refreshState"/>.
|
---|
9633 | If that method has not yet been called on the medium, the state
|
---|
9634 | is "Inaccessible"; as opposed to truly inaccessible media, the
|
---|
9635 | value of <link to="#lastAccessError"/> will be an empty string in
|
---|
9636 | that case.
|
---|
9637 |
|
---|
9638 | <note>As of version 3.1, this no longer performs an accessibility check
|
---|
9639 | automatically; call <link to="#refreshState"/> for that.
|
---|
9640 | </note>
|
---|
9641 | </desc>
|
---|
9642 | </attribute>
|
---|
9643 |
|
---|
9644 | <attribute name="variant" type="unsigned long" readonly="yes">
|
---|
9645 | <desc>
|
---|
9646 | Returns the storage format variant information for this medium
|
---|
9647 | as a combination of the flags described at <link to="MediumVariant" />.
|
---|
9648 | Before <link to="#refreshState"/> is called this method returns
|
---|
9649 | an undefined value.
|
---|
9650 | </desc>
|
---|
9651 | </attribute>
|
---|
9652 |
|
---|
9653 | <attribute name="location" type="wstring">
|
---|
9654 | <desc>
|
---|
9655 | Location of the storage unit holding medium data.
|
---|
9656 |
|
---|
9657 | The format of the location string is medium type specific. For medium
|
---|
9658 | types using regular files in a host's file system, the location
|
---|
9659 | string is the full file name.
|
---|
9660 |
|
---|
9661 | Some medium types may support changing the storage unit location by
|
---|
9662 | simply changing the value of this property. If this operation is not
|
---|
9663 | supported, the implementation will return E_NOTIMPL in attempt to set
|
---|
9664 | this attribute's value.
|
---|
9665 |
|
---|
9666 | When setting a value of the location attribute which is a regular file
|
---|
9667 | in the host's file system, the given file name may be either relative to
|
---|
9668 | the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
|
---|
9669 | absolute. Note that if the given location specification does not contain
|
---|
9670 | the file extension part then a proper default extension will be
|
---|
9671 | automatically appended by the implementation depending on the medium type.
|
---|
9672 | </desc>
|
---|
9673 | </attribute>
|
---|
9674 |
|
---|
9675 | <attribute name="name" type="wstring" readonly="yes">
|
---|
9676 | <desc>
|
---|
9677 | Name of the storage unit holding medium data.
|
---|
9678 |
|
---|
9679 | The returned string is a short version of the <link to="#location"/>
|
---|
9680 | attribute that is suitable for representing the medium in situations
|
---|
9681 | where the full location specification is too long (such as lists
|
---|
9682 | and comboboxes in GUI frontends). This string is also used by frontends
|
---|
9683 | to sort the media list alphabetically when needed.
|
---|
9684 |
|
---|
9685 | For example, for locations that are regular files in the host's file
|
---|
9686 | system, the value of this attribute is just the file name (+ extension),
|
---|
9687 | without the path specification.
|
---|
9688 |
|
---|
9689 | Note that as opposed to the <link to="#location"/> attribute, the name
|
---|
9690 | attribute will not necessary be unique for a list of media of the
|
---|
9691 | given type and format.
|
---|
9692 | </desc>
|
---|
9693 | </attribute>
|
---|
9694 |
|
---|
9695 | <attribute name="deviceType" type="DeviceType" readonly="yes">
|
---|
9696 | <desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
|
---|
9697 | medium.</desc>
|
---|
9698 | </attribute>
|
---|
9699 |
|
---|
9700 | <attribute name="hostDrive" type="boolean" readonly="yes">
|
---|
9701 | <desc>True if this corresponds to a drive on the host.</desc>
|
---|
9702 | </attribute>
|
---|
9703 |
|
---|
9704 | <attribute name="size" type="long long" readonly="yes">
|
---|
9705 | <desc>
|
---|
9706 | Physical size of the storage unit used to hold medium data (in bytes).
|
---|
9707 |
|
---|
9708 | <note>
|
---|
9709 | For media whose <link to="#state"/> is <link
|
---|
9710 | to="MediumState_Inaccessible"/>, the value of this property is the
|
---|
9711 | last known size. For <link to="MediumState_NotCreated"/> media,
|
---|
9712 | the returned value is zero.
|
---|
9713 | </note>
|
---|
9714 | </desc>
|
---|
9715 | </attribute>
|
---|
9716 |
|
---|
9717 | <attribute name="format" type="wstring" readonly="yes">
|
---|
9718 | <desc>
|
---|
9719 | Storage format of this medium.
|
---|
9720 |
|
---|
9721 | The value of this attribute is a string that specifies a backend used
|
---|
9722 | to store medium data. The storage format is defined when you create a
|
---|
9723 | new medium or automatically detected when you open an existing medium,
|
---|
9724 | and cannot be changed later.
|
---|
9725 |
|
---|
9726 | The list of all storage formats supported by this VirtualBox
|
---|
9727 | installation can be obtained using
|
---|
9728 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
9729 | </desc>
|
---|
9730 | </attribute>
|
---|
9731 |
|
---|
9732 | <attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
|
---|
9733 | <desc>
|
---|
9734 | Storage medium format object corresponding to this medium.
|
---|
9735 |
|
---|
9736 | The value of this attribute is a reference to the medium format object
|
---|
9737 | that specifies the backend properties used to store medium data. The
|
---|
9738 | storage format is defined when you create a new medium or automatically
|
---|
9739 | detected when you open an existing medium, and cannot be changed later.
|
---|
9740 |
|
---|
9741 | <note>@c null is returned if there is no associated medium format
|
---|
9742 | object. This can e.g. happen for medium objects representing host
|
---|
9743 | drives and other special medium objects.</note>
|
---|
9744 | </desc>
|
---|
9745 | </attribute>
|
---|
9746 |
|
---|
9747 | <attribute name="type" type="MediumType">
|
---|
9748 | <desc>
|
---|
9749 | Type (role) of this medium.
|
---|
9750 |
|
---|
9751 | The following constraints apply when changing the value of this
|
---|
9752 | attribute:
|
---|
9753 | <ul>
|
---|
9754 | <li>If a medium is attached to a virtual machine (either in the
|
---|
9755 | current state or in one of the snapshots), its type cannot be
|
---|
9756 | changed.
|
---|
9757 | </li>
|
---|
9758 | <li>As long as the medium has children, its type cannot be set
|
---|
9759 | to <link to="MediumType_Writethrough"/>.
|
---|
9760 | </li>
|
---|
9761 | <li>The type of all differencing media is
|
---|
9762 | <link to="MediumType_Normal"/> and cannot be changed.
|
---|
9763 | </li>
|
---|
9764 | </ul>
|
---|
9765 |
|
---|
9766 | The type of a newly created or opened medium is set to
|
---|
9767 | <link to="MediumType_Normal"/>, except for DVD and floppy media,
|
---|
9768 | which have a type of <link to="MediumType_Writethrough"/>.
|
---|
9769 | </desc>
|
---|
9770 | </attribute>
|
---|
9771 |
|
---|
9772 | <attribute name="parent" type="IMedium" readonly="yes">
|
---|
9773 | <desc>
|
---|
9774 | Parent of this medium (the medium this medium is directly based
|
---|
9775 | on).
|
---|
9776 |
|
---|
9777 | Only differencing media have parents. For base (non-differencing)
|
---|
9778 | media, @c null is returned.
|
---|
9779 | </desc>
|
---|
9780 | </attribute>
|
---|
9781 |
|
---|
9782 | <attribute name="children" type="IMedium" safearray="yes" readonly="yes">
|
---|
9783 | <desc>
|
---|
9784 | Children of this medium (all differencing media directly based
|
---|
9785 | on this medium). A @c null array is returned if this medium
|
---|
9786 | does not have any children.
|
---|
9787 | </desc>
|
---|
9788 | </attribute>
|
---|
9789 |
|
---|
9790 | <attribute name="base" type="IMedium" readonly="yes">
|
---|
9791 | <desc>
|
---|
9792 | Base medium of this medium.
|
---|
9793 |
|
---|
9794 | If this is a differencing medium, its base medium is the medium
|
---|
9795 | the given medium branch starts from. For all other types of media, this
|
---|
9796 | property returns the medium object itself (i.e. the same object this
|
---|
9797 | property is read on).
|
---|
9798 | </desc>
|
---|
9799 | </attribute>
|
---|
9800 |
|
---|
9801 | <attribute name="readOnly" type="boolean" readonly="yes">
|
---|
9802 | <desc>
|
---|
9803 | Returns @c true if this medium is read-only and @c false otherwise.
|
---|
9804 |
|
---|
9805 | A medium is considered to be read-only when its contents cannot be
|
---|
9806 | modified without breaking the integrity of other parties that depend on
|
---|
9807 | this medium such as its child media or snapshots of virtual machines
|
---|
9808 | where this medium is attached to these machines. If there are no
|
---|
9809 | children and no such snapshots then there is no dependency and the
|
---|
9810 | medium is not read-only.
|
---|
9811 |
|
---|
9812 | The value of this attribute can be used to determine the kind of the
|
---|
9813 | attachment that will take place when attaching this medium to a
|
---|
9814 | virtual machine. If the value is @c false then the medium will
|
---|
9815 | be attached directly. If the value is @c true then the medium
|
---|
9816 | will be attached indirectly by creating a new differencing child
|
---|
9817 | medium for that. See the interface description for more information.
|
---|
9818 |
|
---|
9819 | Note that all <link to="MediumType_Immutable">Immutable</link> media
|
---|
9820 | are always read-only while all
|
---|
9821 | <link to="MediumType_Writethrough">Writethrough</link> media are
|
---|
9822 | always not.
|
---|
9823 |
|
---|
9824 | <note>
|
---|
9825 | The read-only condition represented by this attribute is related to
|
---|
9826 | the medium type and usage, not to the current
|
---|
9827 | <link to="IMedium::state">medium state</link> and not to the read-only
|
---|
9828 | state of the storage unit.
|
---|
9829 | </note>
|
---|
9830 | </desc>
|
---|
9831 | </attribute>
|
---|
9832 |
|
---|
9833 | <attribute name="logicalSize" type="long long" readonly="yes">
|
---|
9834 | <desc>
|
---|
9835 | Logical size of this medium (in bytes), as reported to the
|
---|
9836 | guest OS running inside the virtual machine this medium is
|
---|
9837 | attached to. The logical size is defined when the medium is created
|
---|
9838 | and cannot be changed later.
|
---|
9839 |
|
---|
9840 | <note>
|
---|
9841 | Reading this property on a differencing medium will return the size
|
---|
9842 | of its <link to="#base"/> medium.
|
---|
9843 | </note>
|
---|
9844 | <note>
|
---|
9845 | For media whose state is <link to="#state"/> is <link
|
---|
9846 | to="MediumState_Inaccessible"/>, the value of this property is the
|
---|
9847 | last known logical size. For <link to="MediumState_NotCreated"/>
|
---|
9848 | media, the returned value is zero.
|
---|
9849 | </note>
|
---|
9850 | </desc>
|
---|
9851 | </attribute>
|
---|
9852 |
|
---|
9853 | <attribute name="autoReset" type="boolean">
|
---|
9854 | <desc>
|
---|
9855 | Whether this differencing medium will be automatically reset each
|
---|
9856 | time a virtual machine it is attached to is powered up. This
|
---|
9857 | attribute is automatically set to @c true for the last
|
---|
9858 | differencing image of an "immutable" medium (see
|
---|
9859 | <link to="MediumType" />).
|
---|
9860 |
|
---|
9861 | See <link to="#reset"/> for more information about resetting
|
---|
9862 | differencing media.
|
---|
9863 |
|
---|
9864 | <note>
|
---|
9865 | Reading this property on a base (non-differencing) medium will
|
---|
9866 | always @c false. Changing the value of this property in this
|
---|
9867 | case is not supported.
|
---|
9868 | </note>
|
---|
9869 |
|
---|
9870 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9871 | This is not a differencing medium (when changing the attribute
|
---|
9872 | value).
|
---|
9873 | </result>
|
---|
9874 | </desc>
|
---|
9875 | </attribute>
|
---|
9876 |
|
---|
9877 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
9878 | <desc>
|
---|
9879 | Text message that represents the result of the last accessibility
|
---|
9880 | check performed by <link to="#refreshState"/>.
|
---|
9881 |
|
---|
9882 | An empty string is returned if the last accessibility check
|
---|
9883 | was successful or has not yet been called. As a result, if
|
---|
9884 | <link to="#state" /> is "Inaccessible" and this attribute is empty,
|
---|
9885 | then <link to="#refreshState"/> has yet to be called; this is the
|
---|
9886 | default value of media after VirtualBox initialization.
|
---|
9887 | A non-empty string indicates a failure and should normally describe
|
---|
9888 | a reason of the failure (for example, a file read error).
|
---|
9889 | </desc>
|
---|
9890 | </attribute>
|
---|
9891 |
|
---|
9892 | <attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
|
---|
9893 | <desc>
|
---|
9894 | Array of UUIDs of all machines this medium is attached to.
|
---|
9895 |
|
---|
9896 | A @c null array is returned if this medium is not attached to any
|
---|
9897 | machine or to any machine's snapshot.
|
---|
9898 |
|
---|
9899 | <note>
|
---|
9900 | The returned array will include a machine even if this medium is not
|
---|
9901 | attached to that machine in the current state but attached to it in
|
---|
9902 | one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
|
---|
9903 | details.
|
---|
9904 | </note>
|
---|
9905 | </desc>
|
---|
9906 | </attribute>
|
---|
9907 |
|
---|
9908 | <method name="setIDs">
|
---|
9909 | <desc>
|
---|
9910 | Changes the UUID and parent UUID for a hard disk medium.
|
---|
9911 | </desc>
|
---|
9912 | <param name="setImageId" type="boolean" dir="in">
|
---|
9913 | <desc>
|
---|
9914 | Select whether a new image UUID is set or not.
|
---|
9915 | </desc>
|
---|
9916 | </param>
|
---|
9917 | <param name="imageId" type="uuid" mod="string" dir="in">
|
---|
9918 | <desc>
|
---|
9919 | New UUID for the image. If an empty string is passed, then a new
|
---|
9920 | UUID is automatically created, provided that @a setImageId is @c true.
|
---|
9921 | Specifying a zero UUID is not allowed.
|
---|
9922 | </desc>
|
---|
9923 | </param>
|
---|
9924 | <param name="setParentId" type="boolean" dir="in">
|
---|
9925 | <desc>
|
---|
9926 | Select whether a new parent UUID is set or not.
|
---|
9927 | </desc>
|
---|
9928 | </param>
|
---|
9929 | <param name="parentId" type="uuid" mod="string" dir="in">
|
---|
9930 | <desc>
|
---|
9931 | New parent UUID for the image. If an empty string is passed, then a
|
---|
9932 | new UUID is automatically created, provided @a setParentId is
|
---|
9933 | @c true. A zero UUID is valid.
|
---|
9934 | </desc>
|
---|
9935 | </param>
|
---|
9936 | <result name="E_INVALIDARG">
|
---|
9937 | Invalid parameter combination.
|
---|
9938 | </result>
|
---|
9939 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9940 | Medium is not a hard disk medium.
|
---|
9941 | </result>
|
---|
9942 | </method>
|
---|
9943 |
|
---|
9944 | <method name="refreshState">
|
---|
9945 | <desc>
|
---|
9946 | If the current medium state (see <link to="MediumState"/>) is one of
|
---|
9947 | "Created", "Inaccessible" or "LockedRead", then this performs an
|
---|
9948 | accessibility check on the medium and sets the value of the <link to="#state"/>
|
---|
9949 | attribute accordingly; that value is also returned for convenience.
|
---|
9950 |
|
---|
9951 | For all other state values, this does not perform a refresh but returns
|
---|
9952 | the state only.
|
---|
9953 |
|
---|
9954 | The refresh, if performed, may take a long time (several seconds or even
|
---|
9955 | minutes, depending on the storage unit location and format) because it performs an
|
---|
9956 | accessibility check of the storage unit. This check may cause a significant
|
---|
9957 | delay if the storage unit of the given medium is, for example, a file located
|
---|
9958 | on a network share which is not currently accessible due to connectivity
|
---|
9959 | problems. In that case, the call will not return until a timeout
|
---|
9960 | interval defined by the host OS for this operation expires. For this reason,
|
---|
9961 | it is recommended to never read this attribute on the main UI thread to avoid
|
---|
9962 | making the UI unresponsive.
|
---|
9963 |
|
---|
9964 | If the last known state of the medium is "Created" and the accessibility
|
---|
9965 | check fails, then the state would be set to "Inaccessible", and
|
---|
9966 | <link to="#lastAccessError"/> may be used to get more details about the
|
---|
9967 | failure. If the state of the medium is "LockedRead", then it remains the
|
---|
9968 | same, and a non-empty value of <link to="#lastAccessError"/> will
|
---|
9969 | indicate a failed accessibility check in this case.
|
---|
9970 |
|
---|
9971 | Note that not all medium states are applicable to all medium types.
|
---|
9972 | </desc>
|
---|
9973 | <param name="state" type="MediumState" dir="return">
|
---|
9974 | <desc>
|
---|
9975 | New medium state.
|
---|
9976 | </desc>
|
---|
9977 | </param>
|
---|
9978 | </method>
|
---|
9979 |
|
---|
9980 | <method name="getSnapshotIds">
|
---|
9981 | <desc>
|
---|
9982 | Returns an array of UUIDs of all snapshots of the given machine where
|
---|
9983 | this medium is attached to.
|
---|
9984 |
|
---|
9985 | If the medium is attached to the machine in the current state, then the
|
---|
9986 | first element in the array will always be the ID of the queried machine
|
---|
9987 | (i.e. the value equal to the @c machineId argument), followed by
|
---|
9988 | snapshot IDs (if any).
|
---|
9989 |
|
---|
9990 | If the medium is not attached to the machine in the current state, then
|
---|
9991 | the array will contain only snapshot IDs.
|
---|
9992 |
|
---|
9993 | The returned array may be @c null if this medium is not attached
|
---|
9994 | to the given machine at all, neither in the current state nor in one of
|
---|
9995 | the snapshots.
|
---|
9996 | </desc>
|
---|
9997 | <param name="machineId" type="uuid" mod="string" dir="in">
|
---|
9998 | <desc>
|
---|
9999 | UUID of the machine to query.
|
---|
10000 | </desc>
|
---|
10001 | </param>
|
---|
10002 | <param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
|
---|
10003 | <desc>
|
---|
10004 | Array of snapshot UUIDs of the given machine using this medium.
|
---|
10005 | </desc>
|
---|
10006 | </param>
|
---|
10007 | </method>
|
---|
10008 |
|
---|
10009 | <method name="lockRead">
|
---|
10010 | <desc>
|
---|
10011 | Locks this medium for reading.
|
---|
10012 |
|
---|
10013 | A read lock is shared: many clients can simultaneously lock the
|
---|
10014 | same medium for reading unless it is already locked for writing (see
|
---|
10015 | <link to="#lockWrite"/>) in which case an error is returned.
|
---|
10016 |
|
---|
10017 | When the medium is locked for reading, it cannot be modified
|
---|
10018 | from within VirtualBox. This means that any method that changes
|
---|
10019 | the properties of this medium or contents of the storage unit
|
---|
10020 | will return an error (unless explicitly stated otherwise). That
|
---|
10021 | includes an attempt to start a virtual machine that wants to
|
---|
10022 | write to the the medium.
|
---|
10023 |
|
---|
10024 | When the virtual machine is started up, it locks for reading all
|
---|
10025 | media it uses in read-only mode. If some medium cannot be locked
|
---|
10026 | for reading, the startup procedure will fail.
|
---|
10027 | A medium is typically locked for reading while it is used by a running
|
---|
10028 | virtual machine but has a depending differencing image that receives
|
---|
10029 | the actual write operations. This way one base medium can have
|
---|
10030 | multiple child differencing images which can be written to
|
---|
10031 | simultaneously. Read-only media such as DVD and floppy images are
|
---|
10032 | also locked for reading only (so they can be in use by multiple
|
---|
10033 | machines simultaneously).
|
---|
10034 |
|
---|
10035 | A medium is also locked for reading when it is the source of a
|
---|
10036 | write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
|
---|
10037 |
|
---|
10038 | The medium locked for reading must be unlocked using the <link
|
---|
10039 | to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
|
---|
10040 | can be nested and must be followed by the same number of paired
|
---|
10041 | <link to="#unlockRead"/> calls.
|
---|
10042 |
|
---|
10043 | This method sets the medium state (see <link to="#state"/>) to
|
---|
10044 | "LockedRead" on success. The medium's previous state must be
|
---|
10045 | one of "Created", "Inaccessible" or "LockedRead".
|
---|
10046 |
|
---|
10047 | Locking an inaccessible medium is not an error; this method performs
|
---|
10048 | a logical lock that prevents modifications of this medium through
|
---|
10049 | the VirtualBox API, not a physical file-system lock of the underlying
|
---|
10050 | storage unit.
|
---|
10051 |
|
---|
10052 | This method returns the current state of the medium
|
---|
10053 | <i>before</i> the operation.
|
---|
10054 |
|
---|
10055 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10056 | Invalid medium state (e.g. not created, locked, inaccessible,
|
---|
10057 | creating, deleting).
|
---|
10058 | </result>
|
---|
10059 |
|
---|
10060 | </desc>
|
---|
10061 | <param name="state" type="MediumState" dir="return">
|
---|
10062 | <desc>
|
---|
10063 | State of the medium after the operation.
|
---|
10064 | </desc>
|
---|
10065 | </param>
|
---|
10066 | </method>
|
---|
10067 |
|
---|
10068 | <method name="unlockRead">
|
---|
10069 | <desc>
|
---|
10070 | Cancels the read lock previously set by <link to="#lockRead"/>.
|
---|
10071 |
|
---|
10072 | For both success and failure, this method returns the current state
|
---|
10073 | of the medium <i>after</i> the operation.
|
---|
10074 |
|
---|
10075 | See <link to="#lockRead"/> for more details.
|
---|
10076 |
|
---|
10077 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10078 | Medium not locked for reading.
|
---|
10079 | </result>
|
---|
10080 |
|
---|
10081 | </desc>
|
---|
10082 | <param name="state" type="MediumState" dir="return">
|
---|
10083 | <desc>
|
---|
10084 | State of the medium after the operation.
|
---|
10085 | </desc>
|
---|
10086 | </param>
|
---|
10087 | </method>
|
---|
10088 |
|
---|
10089 | <method name="lockWrite">
|
---|
10090 | <desc>
|
---|
10091 | Locks this medium for writing.
|
---|
10092 |
|
---|
10093 | A write lock, as opposed to <link to="#lockRead"/>, is
|
---|
10094 | exclusive: there may be only one client holding a write lock,
|
---|
10095 | and there may be no read locks while the write lock is held.
|
---|
10096 | As a result, read-locking fails if a write lock is held, and
|
---|
10097 | write-locking fails if either a read or another write lock is held.
|
---|
10098 |
|
---|
10099 | When a medium is locked for writing, it cannot be modified
|
---|
10100 | from within VirtualBox, and it is not guaranteed that the values
|
---|
10101 | of its properties are up-to-date. Any method that changes the
|
---|
10102 | properties of this medium or contents of the storage unit will
|
---|
10103 | return an error (unless explicitly stated otherwise).
|
---|
10104 |
|
---|
10105 | When a virtual machine is started up, it locks for writing all
|
---|
10106 | media it uses to write data to. If any medium could not be locked
|
---|
10107 | for writing, the startup procedure will fail. If a medium has
|
---|
10108 | differencing images, then while the machine is running, only
|
---|
10109 | the last ("leaf") differencing image is locked for writing,
|
---|
10110 | whereas its parents are locked for reading only.
|
---|
10111 |
|
---|
10112 | A medium is also locked for writing when it is the target of a
|
---|
10113 | write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
|
---|
10114 |
|
---|
10115 | The medium locked for writing must be unlocked using the <link
|
---|
10116 | to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
|
---|
10117 |
|
---|
10118 | This method sets the medium state (see <link to="#state"/>) to
|
---|
10119 | "LockedWrite" on success. The medium's previous state must be
|
---|
10120 | either "Created" or "Inaccessible".
|
---|
10121 |
|
---|
10122 | Locking an inaccessible medium is not an error; this method performs
|
---|
10123 | a logical lock that prevents modifications of this medium through
|
---|
10124 | the VirtualBox API, not a physical file-system lock of the underlying
|
---|
10125 | storage unit.
|
---|
10126 |
|
---|
10127 | For both, success and failure, this method returns the current
|
---|
10128 | state of the medium <i>before</i> the operation.
|
---|
10129 |
|
---|
10130 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10131 | Invalid medium state (e.g. not created, locked, inaccessible,
|
---|
10132 | creating, deleting).
|
---|
10133 | </result>
|
---|
10134 |
|
---|
10135 | </desc>
|
---|
10136 | <param name="state" type="MediumState" dir="return">
|
---|
10137 | <desc>
|
---|
10138 | State of the medium after the operation.
|
---|
10139 | </desc>
|
---|
10140 | </param>
|
---|
10141 | </method>
|
---|
10142 |
|
---|
10143 | <method name="unlockWrite">
|
---|
10144 | <desc>
|
---|
10145 | Cancels the write lock previously set by <link to="#lockWrite"/>.
|
---|
10146 |
|
---|
10147 | For both success and failure, this method returns the current
|
---|
10148 | state of the medium <i>after</i> the operation.
|
---|
10149 |
|
---|
10150 | See <link to="#lockWrite"/> for more details.
|
---|
10151 |
|
---|
10152 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10153 | Medium not locked for writing.
|
---|
10154 | </result>
|
---|
10155 |
|
---|
10156 | </desc>
|
---|
10157 | <param name="state" type="MediumState" dir="return">
|
---|
10158 | <desc>
|
---|
10159 | State of the medium after the operation.
|
---|
10160 | </desc>
|
---|
10161 | </param>
|
---|
10162 | </method>
|
---|
10163 |
|
---|
10164 | <method name="close">
|
---|
10165 | <desc>
|
---|
10166 | Closes this medium.
|
---|
10167 |
|
---|
10168 | The medium must not be attached to any known virtual machine
|
---|
10169 | and must not have any known child media, otherwise the
|
---|
10170 | operation will fail.
|
---|
10171 |
|
---|
10172 | When the medium is successfully closed, it is removed from
|
---|
10173 | the list of registered media, but its storage unit is not
|
---|
10174 | deleted. In particular, this means that this medium can
|
---|
10175 | later be opened again using the <link to="IVirtualBox::openMedium"/>
|
---|
10176 | call.
|
---|
10177 |
|
---|
10178 | Note that after this method successfully returns, the given medium
|
---|
10179 | object becomes uninitialized. This means that any attempt
|
---|
10180 | to call any of its methods or attributes will fail with the
|
---|
10181 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
|
---|
10182 |
|
---|
10183 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10184 | Invalid medium state (other than not created, created or
|
---|
10185 | inaccessible).
|
---|
10186 | </result>
|
---|
10187 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
10188 | Medium attached to virtual machine.
|
---|
10189 | </result>
|
---|
10190 | <result name="VBOX_E_FILE_ERROR">
|
---|
10191 | Settings file not accessible.
|
---|
10192 | </result>
|
---|
10193 | <result name="VBOX_E_XML_ERROR">
|
---|
10194 | Could not parse the settings file.
|
---|
10195 | </result>
|
---|
10196 |
|
---|
10197 | </desc>
|
---|
10198 | </method>
|
---|
10199 |
|
---|
10200 | <!-- storage methods -->
|
---|
10201 |
|
---|
10202 | <method name="getProperty">
|
---|
10203 | <desc>
|
---|
10204 | Returns the value of the custom medium property with the given name.
|
---|
10205 |
|
---|
10206 | The list of all properties supported by the given medium format can
|
---|
10207 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
10208 |
|
---|
10209 | Note that if this method returns an empty string in @a value, the
|
---|
10210 | requested property is supported but currently not assigned any value.
|
---|
10211 |
|
---|
10212 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
10213 | Requested property does not exist (not supported by the format).
|
---|
10214 | </result>
|
---|
10215 | <result name="E_INVALIDARG">@a name is @c null or empty.</result>
|
---|
10216 | </desc>
|
---|
10217 | <param name="name" type="wstring" dir="in">
|
---|
10218 | <desc>Name of the property to get.</desc>
|
---|
10219 | </param>
|
---|
10220 | <param name="value" type="wstring" dir="return">
|
---|
10221 | <desc>Current property value.</desc>
|
---|
10222 | </param>
|
---|
10223 | </method>
|
---|
10224 |
|
---|
10225 | <method name="setProperty">
|
---|
10226 | <desc>
|
---|
10227 | Sets the value of the custom medium property with the given name.
|
---|
10228 |
|
---|
10229 | The list of all properties supported by the given medium format can
|
---|
10230 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
10231 |
|
---|
10232 | Note that setting the property value to @c null or an empty string is
|
---|
10233 | equivalent to deleting the existing value. A default value (if it is
|
---|
10234 | defined for this property) will be used by the format backend in this
|
---|
10235 | case.
|
---|
10236 |
|
---|
10237 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
10238 | Requested property does not exist (not supported by the format).
|
---|
10239 | </result>
|
---|
10240 | <result name="E_INVALIDARG">@a name is @c null or empty.</result>
|
---|
10241 | </desc>
|
---|
10242 | <param name="name" type="wstring" dir="in">
|
---|
10243 | <desc>Name of the property to set.</desc>
|
---|
10244 | </param>
|
---|
10245 | <param name="value" type="wstring" dir="in">
|
---|
10246 | <desc>Property value to set.</desc>
|
---|
10247 | </param>
|
---|
10248 | </method>
|
---|
10249 |
|
---|
10250 | <method name="getProperties">
|
---|
10251 | <desc>
|
---|
10252 | Returns values for a group of properties in one call.
|
---|
10253 |
|
---|
10254 | The names of the properties to get are specified using the @a names
|
---|
10255 | argument which is a list of comma-separated property names or
|
---|
10256 | an empty string if all properties are to be returned. Note that currently
|
---|
10257 | the value of this argument is ignored and the method always returns all
|
---|
10258 | existing properties.
|
---|
10259 |
|
---|
10260 | The list of all properties supported by the given medium format can
|
---|
10261 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
10262 |
|
---|
10263 | The method returns two arrays, the array of property names corresponding
|
---|
10264 | to the @a names argument and the current values of these properties.
|
---|
10265 | Both arrays have the same number of elements with each elemend at the
|
---|
10266 | given index in the first array corresponds to an element at the same
|
---|
10267 | index in the second array.
|
---|
10268 |
|
---|
10269 | Note that for properties that do not have assigned values,
|
---|
10270 | an empty string is returned at the appropriate index in the
|
---|
10271 | @a returnValues array.
|
---|
10272 |
|
---|
10273 | </desc>
|
---|
10274 | <param name="names" type="wstring" dir="in">
|
---|
10275 | <desc>
|
---|
10276 | Names of properties to get.
|
---|
10277 | </desc>
|
---|
10278 | </param>
|
---|
10279 | <param name="returnNames" type="wstring" safearray="yes" dir="out">
|
---|
10280 | <desc>Names of returned properties.</desc>
|
---|
10281 | </param>
|
---|
10282 | <param name="returnValues" type="wstring" safearray="yes" dir="return">
|
---|
10283 | <desc>Values of returned properties.</desc>
|
---|
10284 | </param>
|
---|
10285 | </method>
|
---|
10286 |
|
---|
10287 | <method name="setProperties">
|
---|
10288 | <desc>
|
---|
10289 | Sets values for a group of properties in one call.
|
---|
10290 |
|
---|
10291 | The names of the properties to set are passed in the @a names
|
---|
10292 | array along with the new values for them in the @a values array. Both
|
---|
10293 | arrays have the same number of elements with each elemend at the given
|
---|
10294 | index in the first array corresponding to an element at the same index
|
---|
10295 | in the second array.
|
---|
10296 |
|
---|
10297 | If there is at least one property name in @a names that is not valid,
|
---|
10298 | the method will fail before changing the values of any other properties
|
---|
10299 | from the @a names array.
|
---|
10300 |
|
---|
10301 | Using this method over <link to="#setProperty"/> is preferred if you
|
---|
10302 | need to set several properties at once since it will result into less
|
---|
10303 | IPC calls.
|
---|
10304 |
|
---|
10305 | The list of all properties supported by the given medium format can
|
---|
10306 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
10307 |
|
---|
10308 | Note that setting the property value to @c null or an empty string is
|
---|
10309 | equivalent to deleting the existing value. A default value (if it is
|
---|
10310 | defined for this property) will be used by the format backend in this
|
---|
10311 | case.
|
---|
10312 | </desc>
|
---|
10313 | <param name="names" type="wstring" safearray="yes" dir="in">
|
---|
10314 | <desc>Names of properties to set.</desc>
|
---|
10315 | </param>
|
---|
10316 | <param name="values" type="wstring" safearray="yes" dir="in">
|
---|
10317 | <desc>Values of properties to set.</desc>
|
---|
10318 | </param>
|
---|
10319 | </method>
|
---|
10320 |
|
---|
10321 | <!-- storage methods -->
|
---|
10322 |
|
---|
10323 | <method name="createBaseStorage">
|
---|
10324 | <desc>
|
---|
10325 | Starts creating a hard disk storage unit (fixed/dynamic, according
|
---|
10326 | to the variant flags) in in the background. The previous storage unit
|
---|
10327 | created for this object, if any, must first be deleted using
|
---|
10328 | <link to="#deleteStorage"/>, otherwise the operation will fail.
|
---|
10329 |
|
---|
10330 | Before the operation starts, the medium is placed in
|
---|
10331 | <link to="MediumState_Creating"/> state. If the create operation
|
---|
10332 | fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
|
---|
10333 | state.
|
---|
10334 |
|
---|
10335 | After the returned progress object reports that the operation has
|
---|
10336 | successfully completed, the medium state will be set to <link
|
---|
10337 | to="MediumState_Created"/>, the medium will be remembered by this
|
---|
10338 | VirtualBox installation and may be attached to virtual machines.
|
---|
10339 |
|
---|
10340 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10341 | The variant of storage creation operation is not supported. See <link
|
---|
10342 | to="IMediumFormat::capabilities"/>.
|
---|
10343 | </result>
|
---|
10344 | </desc>
|
---|
10345 | <param name="logicalSize" type="long long" dir="in">
|
---|
10346 | <desc>Maximum logical size of the medium in bytes.</desc>
|
---|
10347 | </param>
|
---|
10348 | <param name="variant" type="unsigned long" dir="in">
|
---|
10349 | <desc>Exact image variant which should be created (as a combination of
|
---|
10350 | <link to="MediumVariant" /> flags).</desc>
|
---|
10351 | </param>
|
---|
10352 | <param name="progress" type="IProgress" dir="return">
|
---|
10353 | <desc>Progress object to track the operation completion.</desc>
|
---|
10354 | </param>
|
---|
10355 | </method>
|
---|
10356 |
|
---|
10357 | <method name="deleteStorage">
|
---|
10358 | <desc>
|
---|
10359 | Starts deleting the storage unit of this medium.
|
---|
10360 |
|
---|
10361 | The medium must not be attached to any known virtual machine and must
|
---|
10362 | not have any known child media, otherwise the operation will fail.
|
---|
10363 | It will also fail if there is no storage unit to delete or if deletion
|
---|
10364 | is already in progress, or if the medium is being in use (locked for
|
---|
10365 | read or for write) or inaccessible. Therefore, the only valid state for
|
---|
10366 | this operation to succeed is <link to="MediumState_Created"/>.
|
---|
10367 |
|
---|
10368 | Before the operation starts, the medium is placed in
|
---|
10369 | <link to="MediumState_Deleting"/> state and gets removed from the list
|
---|
10370 | of remembered hard disks (media registry). If the delete operation
|
---|
10371 | fails, the medium will be remembered again and placed back to
|
---|
10372 | <link to="MediumState_Created"/> state.
|
---|
10373 |
|
---|
10374 | After the returned progress object reports that the operation is
|
---|
10375 | complete, the medium state will be set to
|
---|
10376 | <link to="MediumState_NotCreated"/> and you will be able to use one of
|
---|
10377 | the storage creation methods to create it again.
|
---|
10378 |
|
---|
10379 | <see>#close()</see>
|
---|
10380 |
|
---|
10381 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
10382 | Medium is attached to a virtual machine.
|
---|
10383 | </result>
|
---|
10384 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10385 | Storage deletion is not allowed because neither of storage creation
|
---|
10386 | operations are supported. See
|
---|
10387 | <link to="IMediumFormat::capabilities"/>.
|
---|
10388 | </result>
|
---|
10389 |
|
---|
10390 | <note>
|
---|
10391 | If the deletion operation fails, it is not guaranteed that the storage
|
---|
10392 | unit still exists. You may check the <link to="IMedium::state"/> value
|
---|
10393 | to answer this question.
|
---|
10394 | </note>
|
---|
10395 | </desc>
|
---|
10396 | <param name="progress" type="IProgress" dir="return">
|
---|
10397 | <desc>Progress object to track the operation completion.</desc>
|
---|
10398 | </param>
|
---|
10399 | </method>
|
---|
10400 |
|
---|
10401 | <!-- diff methods -->
|
---|
10402 |
|
---|
10403 | <method name="createDiffStorage">
|
---|
10404 | <desc>
|
---|
10405 | Starts creating an empty differencing storage unit based on this
|
---|
10406 | medium in the format and at the location defined by the @a target
|
---|
10407 | argument.
|
---|
10408 |
|
---|
10409 | The target medium must be in <link to="MediumState_NotCreated"/>
|
---|
10410 | state (i.e. must not have an existing storage unit). Upon successful
|
---|
10411 | completion, this operation will set the type of the target medium to
|
---|
10412 | <link to="MediumType_Normal"/> and create a storage unit necessary to
|
---|
10413 | represent the differencing medium data in the given format (according
|
---|
10414 | to the storage format of the target object).
|
---|
10415 |
|
---|
10416 | After the returned progress object reports that the operation is
|
---|
10417 | successfully complete, the target medium gets remembered by this
|
---|
10418 | VirtualBox installation and may be attached to virtual machines.
|
---|
10419 |
|
---|
10420 | <note>
|
---|
10421 | The medium will be set to <link to="MediumState_LockedRead"/>
|
---|
10422 | state for the duration of this operation.
|
---|
10423 | </note>
|
---|
10424 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
10425 | Medium not in @c NotCreated state.
|
---|
10426 | </result>
|
---|
10427 | </desc>
|
---|
10428 | <param name="target" type="IMedium" dir="in">
|
---|
10429 | <desc>Target medium.</desc>
|
---|
10430 | </param>
|
---|
10431 | <param name="variant" type="unsigned long" dir="in">
|
---|
10432 | <desc>Exact image variant which should be created (as a combination of
|
---|
10433 | <link to="MediumVariant" /> flags).</desc>
|
---|
10434 | </param>
|
---|
10435 | <param name="progress" type="IProgress" dir="return">
|
---|
10436 | <desc>Progress object to track the operation completion.</desc>
|
---|
10437 | </param>
|
---|
10438 | </method>
|
---|
10439 |
|
---|
10440 | <method name="mergeTo">
|
---|
10441 | <desc>
|
---|
10442 | Starts merging the contents of this medium and all intermediate
|
---|
10443 | differencing media in the chain to the given target medium.
|
---|
10444 |
|
---|
10445 | The target medium must be either a descendant of this medium or
|
---|
10446 | its ancestor (otherwise this method will immediately return a failure).
|
---|
10447 | It follows that there are two logical directions of the merge operation:
|
---|
10448 | from ancestor to descendant (<i>forward merge</i>) and from descendant to
|
---|
10449 | ancestor (<i>backward merge</i>). Let us consider the following medium
|
---|
10450 | chain:
|
---|
10451 |
|
---|
10452 | <pre>Base <- Diff_1 <- Diff_2</pre>
|
---|
10453 |
|
---|
10454 | Here, calling this method on the <tt>Base</tt> medium object with
|
---|
10455 | <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
|
---|
10456 | <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
|
---|
10457 | merge. Note that in both cases the contents of the resulting medium
|
---|
10458 | will be the same, the only difference is the medium object that takes
|
---|
10459 | the result of the merge operation. In case of the forward merge in the
|
---|
10460 | above example, the result will be written to <tt>Diff_2</tt>; in case of
|
---|
10461 | the backward merge, the result will be written to <tt>Base</tt>. In
|
---|
10462 | other words, the result of the operation is always stored in the target
|
---|
10463 | medium.
|
---|
10464 |
|
---|
10465 | Upon successful operation completion, the storage units of all media in
|
---|
10466 | the chain between this (source) medium and the target medium, including
|
---|
10467 | the source medium itself, will be automatically deleted and the
|
---|
10468 | relevant medium objects (including this medium) will become
|
---|
10469 | uninitialized. This means that any attempt to call any of
|
---|
10470 | their methods or attributes will fail with the
|
---|
10471 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
|
---|
10472 | example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
|
---|
10473 | delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
|
---|
10474 | Note that <tt>Diff_2</tt> in this case will become a base medium
|
---|
10475 | itself since it will no longer be based on any other medium.
|
---|
10476 |
|
---|
10477 | Considering the above, all of the following conditions must be met in
|
---|
10478 | order for the merge operation to succeed:
|
---|
10479 | <ul>
|
---|
10480 | <li>
|
---|
10481 | Neither this (source) medium nor any intermediate
|
---|
10482 | differencing medium in the chain between it and the target
|
---|
10483 | medium is attached to any virtual machine.
|
---|
10484 | </li>
|
---|
10485 | <li>
|
---|
10486 | Neither the source medium nor the target medium is an
|
---|
10487 | <link to="MediumType_Immutable"/> medium.
|
---|
10488 | </li>
|
---|
10489 | <li>
|
---|
10490 | The part of the medium tree from the source medium to the
|
---|
10491 | target medium is a linear chain, i.e. all medium in this
|
---|
10492 | chain have exactly one child which is the next medium in this
|
---|
10493 | chain. The only exception from this rule is the target medium in
|
---|
10494 | the forward merge operation; it is allowed to have any number of
|
---|
10495 | child media because the merge operation will not change its
|
---|
10496 | logical contents (as it is seen by the guest OS or by children).
|
---|
10497 | </li>
|
---|
10498 | <li>
|
---|
10499 | None of the involved media are in
|
---|
10500 | <link to="MediumState_LockedRead"/> or
|
---|
10501 | <link to="MediumState_LockedWrite"/> state.
|
---|
10502 | </li>
|
---|
10503 | </ul>
|
---|
10504 |
|
---|
10505 | <note>
|
---|
10506 | This (source) medium and all intermediates will be placed to <link
|
---|
10507 | to="MediumState_Deleting"/> state and the target medium will be
|
---|
10508 | placed to <link to="MediumState_LockedWrite"/> state and for the
|
---|
10509 | duration of this operation.
|
---|
10510 | </note>
|
---|
10511 | </desc>
|
---|
10512 | <param name="target" type="IMedium" dir="in">
|
---|
10513 | <desc>Target medium.</desc>
|
---|
10514 | </param>
|
---|
10515 | <param name="progress" type="IProgress" dir="return">
|
---|
10516 | <desc>Progress object to track the operation completion.</desc>
|
---|
10517 | </param>
|
---|
10518 | </method>
|
---|
10519 |
|
---|
10520 | <!-- clone method -->
|
---|
10521 |
|
---|
10522 | <method name="cloneTo">
|
---|
10523 | <desc>
|
---|
10524 | Starts creating a clone of this medium in the format and at the
|
---|
10525 | location defined by the @a target argument.
|
---|
10526 |
|
---|
10527 | The target medium must be either in <link to="MediumState_NotCreated"/>
|
---|
10528 | state (i.e. must not have an existing storage unit) or in
|
---|
10529 | <link to="MediumState_Created"/> state (i.e. created and not locked, and
|
---|
10530 | big enough to hold the data or else the copy will be partial). Upon
|
---|
10531 | successful completion, the cloned medium will contain exactly the
|
---|
10532 | same sector data as the medium being cloned, except that in the
|
---|
10533 | first case a new UUID for the clone will be randomly generated, and in
|
---|
10534 | the second case the UUID will remain unchanged.
|
---|
10535 |
|
---|
10536 | The @a parent argument defines which medium will be the parent
|
---|
10537 | of the clone. Passing a @c null reference indicates that the clone will
|
---|
10538 | be a base image, i.e. completely independent. It is possible to specify
|
---|
10539 | an arbitrary medium for this parameter, including the parent of the
|
---|
10540 | medium which is being cloned. Even cloning to a child of the source
|
---|
10541 | medium is possible. Note that when cloning to an existing image, the
|
---|
10542 | @a parent irgument is ignored.
|
---|
10543 |
|
---|
10544 | After the returned progress object reports that the operation is
|
---|
10545 | successfully complete, the target medium gets remembered by this
|
---|
10546 | VirtualBox installation and may be attached to virtual machines.
|
---|
10547 |
|
---|
10548 | <note>
|
---|
10549 | This medium will be placed to <link to="MediumState_LockedRead"/>
|
---|
10550 | state for the duration of this operation.
|
---|
10551 | </note>
|
---|
10552 | <result name="E_NOTIMPL">
|
---|
10553 | The specified cloning variant is not supported at the moment.
|
---|
10554 | </result>
|
---|
10555 | </desc>
|
---|
10556 | <param name="target" type="IMedium" dir="in">
|
---|
10557 | <desc>Target medium.</desc>
|
---|
10558 | </param>
|
---|
10559 | <param name="variant" type="unsigned long" dir="in">
|
---|
10560 | <desc>Exact image variant which should be created (as a combination of
|
---|
10561 | <link to="MediumVariant" /> flags).</desc>
|
---|
10562 | </param>
|
---|
10563 | <param name="parent" type="IMedium" dir="in">
|
---|
10564 | <desc>Parent of the cloned medium.</desc>
|
---|
10565 | </param>
|
---|
10566 | <param name="progress" type="IProgress" dir="return">
|
---|
10567 | <desc>Progress object to track the operation completion.</desc>
|
---|
10568 | </param>
|
---|
10569 | </method>
|
---|
10570 |
|
---|
10571 | <!-- other methods -->
|
---|
10572 |
|
---|
10573 | <method name="compact">
|
---|
10574 | <desc>
|
---|
10575 | Starts compacting of this medium. This means that the medium is
|
---|
10576 | transformed into a possibly more compact storage representation.
|
---|
10577 | This potentially creates temporary images, which can require a
|
---|
10578 | substantial amount of additional disk space.
|
---|
10579 |
|
---|
10580 | This medium will be placed to <link to="MediumState_LockedWrite"/>
|
---|
10581 | state and all its parent media (if any) will be placed to
|
---|
10582 | <link to="MediumState_LockedRead"/> state for the duration of this
|
---|
10583 | operation.
|
---|
10584 |
|
---|
10585 | Please note that the results can be either returned straight away,
|
---|
10586 | or later as the result of the background operation via the object
|
---|
10587 | returned via the @a progress parameter.
|
---|
10588 |
|
---|
10589 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10590 | Medium format does not support compacting (but potentially
|
---|
10591 | needs it).
|
---|
10592 | </result>
|
---|
10593 | </desc>
|
---|
10594 | <param name="progress" type="IProgress" dir="return">
|
---|
10595 | <desc>Progress object to track the operation completion.</desc>
|
---|
10596 | </param>
|
---|
10597 | </method>
|
---|
10598 |
|
---|
10599 | <method name="resize">
|
---|
10600 | <desc>
|
---|
10601 | Starts resizing this medium. This means that the nominal size of the
|
---|
10602 | medium is set to the new value. Both increasing and decreasing the
|
---|
10603 | size is possible, and there are no safety checks, since VirtualBox
|
---|
10604 | does not make any assumptions about the medium contents.
|
---|
10605 |
|
---|
10606 | Resizing usually needs additional disk space, and possibly also
|
---|
10607 | some temporary disk space. Note that resize does not create a full
|
---|
10608 | temporary copy of the medium, so the additional disk space requirement
|
---|
10609 | is usually much lower than using the clone operation.
|
---|
10610 |
|
---|
10611 | This medium will be placed to <link to="MediumState_LockedWrite"/>
|
---|
10612 | state for the duration of this operation.
|
---|
10613 |
|
---|
10614 | Please note that the results can be either returned straight away,
|
---|
10615 | or later as the result of the background operation via the object
|
---|
10616 | returned via the @a progress parameter.
|
---|
10617 |
|
---|
10618 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10619 | Medium format does not support resizing.
|
---|
10620 | </result>
|
---|
10621 | </desc>
|
---|
10622 | <param name="logicalSize" type="long long" dir="in">
|
---|
10623 | <desc>New nominal capacity of the medium in bytes.</desc>
|
---|
10624 | </param>
|
---|
10625 | <param name="progress" type="IProgress" dir="return">
|
---|
10626 | <desc>Progress object to track the operation completion.</desc>
|
---|
10627 | </param>
|
---|
10628 | </method>
|
---|
10629 |
|
---|
10630 | <method name="reset">
|
---|
10631 | <desc>
|
---|
10632 | Starts erasing the contents of this differencing medium.
|
---|
10633 |
|
---|
10634 | This operation will reset the differencing medium to its initial
|
---|
10635 | state when it does not contain any sector data and any read operation is
|
---|
10636 | redirected to its parent medium. This automatically gets called
|
---|
10637 | during VM power-up for every medium whose <link to="#autoReset" />
|
---|
10638 | attribute is @c true.
|
---|
10639 |
|
---|
10640 | The medium will be write-locked for the duration of this operation (see
|
---|
10641 | <link to="#lockWrite" />).
|
---|
10642 |
|
---|
10643 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10644 | This is not a differencing medium.
|
---|
10645 | </result>
|
---|
10646 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10647 | Medium is not in <link to="MediumState_Created"/> or
|
---|
10648 | <link to="MediumState_Inaccessible"/> state.
|
---|
10649 | </result>
|
---|
10650 | </desc>
|
---|
10651 | <param name="progress" type="IProgress" dir="return">
|
---|
10652 | <desc>Progress object to track the operation completion.</desc>
|
---|
10653 | </param>
|
---|
10654 | </method>
|
---|
10655 |
|
---|
10656 | </interface>
|
---|
10657 |
|
---|
10658 |
|
---|
10659 | <!--
|
---|
10660 | // IMediumFormat
|
---|
10661 | /////////////////////////////////////////////////////////////////////////
|
---|
10662 | -->
|
---|
10663 |
|
---|
10664 | <enum
|
---|
10665 | name="DataType"
|
---|
10666 | uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
|
---|
10667 | >
|
---|
10668 | <const name="Int32" value="0"/>
|
---|
10669 | <const name="Int8" value="1"/>
|
---|
10670 | <const name="String" value="2"/>
|
---|
10671 | </enum>
|
---|
10672 |
|
---|
10673 | <enum
|
---|
10674 | name="DataFlags"
|
---|
10675 | uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
|
---|
10676 | >
|
---|
10677 | <const name="None" value="0x00"/>
|
---|
10678 | <const name="Mandatory" value="0x01"/>
|
---|
10679 | <const name="Expert" value="0x02"/>
|
---|
10680 | <const name="Array" value="0x04"/>
|
---|
10681 | <const name="FlagMask" value="0x07"/>
|
---|
10682 | </enum>
|
---|
10683 |
|
---|
10684 | <enum
|
---|
10685 | name="MediumFormatCapabilities"
|
---|
10686 | uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
|
---|
10687 | >
|
---|
10688 | <desc>
|
---|
10689 | Medium format capability flags.
|
---|
10690 | </desc>
|
---|
10691 |
|
---|
10692 | <const name="Uuid" value="0x01">
|
---|
10693 | <desc>
|
---|
10694 | Supports UUIDs as expected by VirtualBox code.
|
---|
10695 | </desc>
|
---|
10696 | </const>
|
---|
10697 |
|
---|
10698 | <const name="CreateFixed" value="0x02">
|
---|
10699 | <desc>
|
---|
10700 | Supports creating fixed size images, allocating all space instantly.
|
---|
10701 | </desc>
|
---|
10702 | </const>
|
---|
10703 |
|
---|
10704 | <const name="CreateDynamic" value="0x04">
|
---|
10705 | <desc>
|
---|
10706 | Supports creating dynamically growing images, allocating space on
|
---|
10707 | demand.
|
---|
10708 | </desc>
|
---|
10709 | </const>
|
---|
10710 |
|
---|
10711 | <const name="CreateSplit2G" value="0x08">
|
---|
10712 | <desc>
|
---|
10713 | Supports creating images split in chunks of a bit less than 2 GBytes.
|
---|
10714 | </desc>
|
---|
10715 | </const>
|
---|
10716 |
|
---|
10717 | <const name="Differencing" value="0x10">
|
---|
10718 | <desc>
|
---|
10719 | Supports being used as a format for differencing media (see <link
|
---|
10720 | to="IMedium::createDiffStorage"/>).
|
---|
10721 | </desc>
|
---|
10722 | </const>
|
---|
10723 |
|
---|
10724 | <const name="Asynchronous" value="0x20">
|
---|
10725 | <desc>
|
---|
10726 | Supports asynchronous I/O operations for at least some configurations.
|
---|
10727 | </desc>
|
---|
10728 | </const>
|
---|
10729 |
|
---|
10730 | <const name="File" value="0x40">
|
---|
10731 | <desc>
|
---|
10732 | The format backend operates on files (the <link to="IMedium::location"/>
|
---|
10733 | attribute of the medium specifies a file used to store medium
|
---|
10734 | data; for a list of supported file extensions see
|
---|
10735 | <link to="IMediumFormat::describeFileExtensions"/>).
|
---|
10736 | </desc>
|
---|
10737 | </const>
|
---|
10738 |
|
---|
10739 | <const name="Properties" value="0x80">
|
---|
10740 | <desc>
|
---|
10741 | The format backend uses the property interface to configure the storage
|
---|
10742 | location and properties (the <link to="IMediumFormat::describeProperties"/>
|
---|
10743 | method is used to get access to properties supported by the given medium format).
|
---|
10744 | </desc>
|
---|
10745 | </const>
|
---|
10746 |
|
---|
10747 | <const name="TcpNetworking" value="0x100">
|
---|
10748 | <desc>
|
---|
10749 | The format backend uses the TCP networking interface for network access.
|
---|
10750 | </desc>
|
---|
10751 | </const>
|
---|
10752 |
|
---|
10753 | <const name="VFS" value="0x200">
|
---|
10754 | <desc>
|
---|
10755 | The format backend supports virtual filesystem functionality.
|
---|
10756 | </desc>
|
---|
10757 | </const>
|
---|
10758 |
|
---|
10759 | <const name="CapabilityMask" value="0x3FF"/>
|
---|
10760 | </enum>
|
---|
10761 |
|
---|
10762 | <interface
|
---|
10763 | name="IMediumFormat" extends="$unknown"
|
---|
10764 | uuid="4e9a873f-0599-434a-8345-619ef3fb3111"
|
---|
10765 | wsmap="managed"
|
---|
10766 | >
|
---|
10767 | <desc>
|
---|
10768 | The IMediumFormat interface represents a medium format.
|
---|
10769 |
|
---|
10770 | Each medium format has an associated backend which is used to handle
|
---|
10771 | media stored in this format. This interface provides information
|
---|
10772 | about the properties of the associated backend.
|
---|
10773 |
|
---|
10774 | Each medium format is identified by a string represented by the
|
---|
10775 | <link to="#id"/> attribute. This string is used in calls like
|
---|
10776 | <link to="IVirtualBox::createHardDisk"/> to specify the desired
|
---|
10777 | format.
|
---|
10778 |
|
---|
10779 | The list of all supported medium formats can be obtained using
|
---|
10780 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
10781 |
|
---|
10782 | <see>IMedium</see>
|
---|
10783 | </desc>
|
---|
10784 |
|
---|
10785 | <attribute name="id" type="wstring" readonly="yes">
|
---|
10786 | <desc>
|
---|
10787 | Identifier of this format.
|
---|
10788 |
|
---|
10789 | The format identifier is a non-@c null non-empty ASCII string. Note that
|
---|
10790 | this string is case-insensitive. This means that, for example, all of
|
---|
10791 | the following strings:
|
---|
10792 | <pre>
|
---|
10793 | "VDI"
|
---|
10794 | "vdi"
|
---|
10795 | "VdI"</pre>
|
---|
10796 | refer to the same medium format.
|
---|
10797 |
|
---|
10798 | This string is used in methods of other interfaces where it is necessary
|
---|
10799 | to specify a medium format, such as
|
---|
10800 | <link to="IVirtualBox::createHardDisk"/>.
|
---|
10801 | </desc>
|
---|
10802 | </attribute>
|
---|
10803 |
|
---|
10804 | <attribute name="name" type="wstring" readonly="yes">
|
---|
10805 | <desc>
|
---|
10806 | Human readable description of this format.
|
---|
10807 |
|
---|
10808 | Mainly for use in file open dialogs.
|
---|
10809 | </desc>
|
---|
10810 | </attribute>
|
---|
10811 |
|
---|
10812 | <attribute name="capabilities" type="unsigned long" readonly="yes">
|
---|
10813 | <desc>
|
---|
10814 | Capabilities of the format as a set of bit flags.
|
---|
10815 |
|
---|
10816 | For the meaning of individual capability flags see
|
---|
10817 | <link to="MediumFormatCapabilities"/>.
|
---|
10818 | </desc>
|
---|
10819 | </attribute>
|
---|
10820 |
|
---|
10821 | <method name="describeFileExtensions">
|
---|
10822 | <desc>
|
---|
10823 | Returns two arrays describing the supported file extensions.
|
---|
10824 |
|
---|
10825 | The first array contains the supported extensions and the seconds one
|
---|
10826 | the type each extension supports. Both have the same size.
|
---|
10827 |
|
---|
10828 | Note that some backends do not work on files, so this array may be
|
---|
10829 | empty.
|
---|
10830 |
|
---|
10831 | <see>IMediumFormat::capabilities</see>
|
---|
10832 | </desc>
|
---|
10833 | <param name="extensions" type="wstring" safearray="yes" dir="out">
|
---|
10834 | <desc>The array of supported extensions.</desc>
|
---|
10835 | </param>
|
---|
10836 | <param name="type" type="DeviceType" safearray="yes" dir="out">
|
---|
10837 | <desc>The array which indicates the device type for every given extension.</desc>
|
---|
10838 | </param>
|
---|
10839 | </method>
|
---|
10840 |
|
---|
10841 | <method name="describeProperties">
|
---|
10842 | <desc>
|
---|
10843 | Returns several arrays describing the properties supported by this
|
---|
10844 | format.
|
---|
10845 |
|
---|
10846 | An element with the given index in each array describes one
|
---|
10847 | property. Thus, the number of elements in each returned array is the
|
---|
10848 | same and corresponds to the number of supported properties.
|
---|
10849 |
|
---|
10850 | The returned arrays are filled in only if the
|
---|
10851 | <link to="MediumFormatCapabilities_Properties"/> flag is set.
|
---|
10852 | All arguments must be non-@c null.
|
---|
10853 |
|
---|
10854 | <see>DataType</see>
|
---|
10855 | <see>DataFlags</see>
|
---|
10856 | </desc>
|
---|
10857 |
|
---|
10858 | <param name="names" type="wstring" safearray="yes" dir="out">
|
---|
10859 | <desc>Array of property names.</desc>
|
---|
10860 | </param>
|
---|
10861 | <param name="description" type="wstring" safearray="yes" dir="out">
|
---|
10862 | <desc>Array of property descriptions.</desc>
|
---|
10863 | </param>
|
---|
10864 | <param name="types" type="DataType" safearray="yes" dir="out">
|
---|
10865 | <desc>Array of property types.</desc>
|
---|
10866 | </param>
|
---|
10867 | <param name="flags" type="unsigned long" safearray="yes" dir="out">
|
---|
10868 | <desc>Array of property flags.</desc>
|
---|
10869 | </param>
|
---|
10870 | <param name="defaults" type="wstring" safearray="yes" dir="out">
|
---|
10871 | <desc>Array of default property values.</desc>
|
---|
10872 | </param>
|
---|
10873 | </method>
|
---|
10874 |
|
---|
10875 | </interface>
|
---|
10876 |
|
---|
10877 |
|
---|
10878 | <!--
|
---|
10879 | // IKeyboard
|
---|
10880 | /////////////////////////////////////////////////////////////////////////
|
---|
10881 | -->
|
---|
10882 |
|
---|
10883 | <interface
|
---|
10884 | name="IKeyboard" extends="$unknown"
|
---|
10885 | uuid="f6916ec5-a881-4237-898f-7de58cf88672"
|
---|
10886 | wsmap="managed"
|
---|
10887 | >
|
---|
10888 | <desc>
|
---|
10889 | The IKeyboard interface represents the virtual machine's keyboard. Used
|
---|
10890 | in <link to="IConsole::keyboard"/>.
|
---|
10891 |
|
---|
10892 | Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
|
---|
10893 | to the virtual machine.
|
---|
10894 |
|
---|
10895 | </desc>
|
---|
10896 | <method name="putScancode">
|
---|
10897 | <desc>Sends a scancode to the keyboard.
|
---|
10898 |
|
---|
10899 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10900 | Could not send scan code to virtual keyboard.
|
---|
10901 | </result>
|
---|
10902 |
|
---|
10903 | </desc>
|
---|
10904 | <param name="scancode" type="long" dir="in"/>
|
---|
10905 | </method>
|
---|
10906 |
|
---|
10907 | <method name="putScancodes">
|
---|
10908 | <desc>Sends an array of scancodes to the keyboard.
|
---|
10909 |
|
---|
10910 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10911 | Could not send all scan codes to virtual keyboard.
|
---|
10912 | </result>
|
---|
10913 |
|
---|
10914 | </desc>
|
---|
10915 | <param name="scancodes" type="long" dir="in" safearray="yes"/>
|
---|
10916 | <param name="codesStored" type="unsigned long" dir="return"/>
|
---|
10917 | </method>
|
---|
10918 |
|
---|
10919 | <method name="putCAD">
|
---|
10920 | <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
|
---|
10921 | function is nothing special, it is just a convenience function
|
---|
10922 | calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
|
---|
10923 |
|
---|
10924 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10925 | Could not send all scan codes to virtual keyboard.
|
---|
10926 | </result>
|
---|
10927 |
|
---|
10928 | </desc>
|
---|
10929 | </method>
|
---|
10930 |
|
---|
10931 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
10932 | <desc>
|
---|
10933 | Event source for keyboard events.
|
---|
10934 | </desc>
|
---|
10935 | </attribute>
|
---|
10936 |
|
---|
10937 | </interface>
|
---|
10938 |
|
---|
10939 |
|
---|
10940 | <!--
|
---|
10941 | // IMouse
|
---|
10942 | /////////////////////////////////////////////////////////////////////////
|
---|
10943 | -->
|
---|
10944 |
|
---|
10945 | <enum
|
---|
10946 | name="MouseButtonState"
|
---|
10947 | uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
|
---|
10948 | >
|
---|
10949 | <desc>
|
---|
10950 | Mouse button state.
|
---|
10951 | </desc>
|
---|
10952 |
|
---|
10953 | <const name="LeftButton" value="0x01"/>
|
---|
10954 | <const name="RightButton" value="0x02"/>
|
---|
10955 | <const name="MiddleButton" value="0x04"/>
|
---|
10956 | <const name="WheelUp" value="0x08"/>
|
---|
10957 | <const name="WheelDown" value="0x10"/>
|
---|
10958 | <const name="XButton1" value="0x20"/>
|
---|
10959 | <const name="XButton2" value="0x40"/>
|
---|
10960 | <const name="MouseStateMask" value="0x7F"/>
|
---|
10961 | </enum>
|
---|
10962 |
|
---|
10963 | <interface
|
---|
10964 | name="IMouse" extends="$unknown"
|
---|
10965 | uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
|
---|
10966 | wsmap="managed"
|
---|
10967 | >
|
---|
10968 | <desc>
|
---|
10969 | The IMouse interface represents the virtual machine's mouse. Used in
|
---|
10970 | <link to="IConsole::mouse"/>.
|
---|
10971 |
|
---|
10972 | Through this interface, the virtual machine's virtual mouse can be
|
---|
10973 | controlled.
|
---|
10974 | </desc>
|
---|
10975 |
|
---|
10976 | <attribute name="absoluteSupported" type="boolean" readonly="yes">
|
---|
10977 | <desc>
|
---|
10978 | Whether the guest OS supports absolute mouse pointer positioning
|
---|
10979 | or not.
|
---|
10980 | <note>
|
---|
10981 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
10982 | event to be instantly informed about changes of this attribute
|
---|
10983 | during virtual machine execution.
|
---|
10984 | </note>
|
---|
10985 | <see><link to="#putMouseEventAbsolute"/></see>
|
---|
10986 | </desc>
|
---|
10987 | </attribute>
|
---|
10988 |
|
---|
10989 | <attribute name="relativeSupported" type="boolean" readonly="yes">
|
---|
10990 | <desc>
|
---|
10991 | Whether the guest OS supports relative mouse pointer positioning
|
---|
10992 | or not.
|
---|
10993 | <note>
|
---|
10994 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
10995 | event to be instantly informed about changes of this attribute
|
---|
10996 | during virtual machine execution.
|
---|
10997 | </note>
|
---|
10998 | <see><link to="#putMouseEvent"/></see>
|
---|
10999 | </desc>
|
---|
11000 | </attribute>
|
---|
11001 |
|
---|
11002 | <attribute name="needsHostCursor" type="boolean" readonly="yes">
|
---|
11003 | <desc>
|
---|
11004 | Whether the guest OS can currently switch to drawing it's own mouse
|
---|
11005 | cursor on demand.
|
---|
11006 | <note>
|
---|
11007 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
11008 | event to be instantly informed about changes of this attribute
|
---|
11009 | during virtual machine execution.
|
---|
11010 | </note>
|
---|
11011 | <see><link to="#putMouseEvent"/></see>
|
---|
11012 | </desc>
|
---|
11013 | </attribute>
|
---|
11014 |
|
---|
11015 | <method name="putMouseEvent">
|
---|
11016 | <desc>
|
---|
11017 | Initiates a mouse event using relative pointer movements
|
---|
11018 | along x and y axis.
|
---|
11019 |
|
---|
11020 | <result name="E_ACCESSDENIED">
|
---|
11021 | Console not powered up.
|
---|
11022 | </result>
|
---|
11023 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11024 | Could not send mouse event to virtual mouse.
|
---|
11025 | </result>
|
---|
11026 |
|
---|
11027 | </desc>
|
---|
11028 |
|
---|
11029 | <param name="dx" type="long" dir="in">
|
---|
11030 | <desc>
|
---|
11031 | Amount of pixels the mouse should move to the right.
|
---|
11032 | Negative values move the mouse to the left.
|
---|
11033 | </desc>
|
---|
11034 | </param>
|
---|
11035 | <param name="dy" type="long" dir="in">
|
---|
11036 | <desc>
|
---|
11037 | Amount of pixels the mouse should move downwards.
|
---|
11038 | Negative values move the mouse upwards.
|
---|
11039 | </desc>
|
---|
11040 | </param>
|
---|
11041 | <param name="dz" type="long" dir="in">
|
---|
11042 | <desc>
|
---|
11043 | Amount of mouse wheel moves.
|
---|
11044 | Positive values describe clockwise wheel rotations,
|
---|
11045 | negative values describe counterclockwise rotations.
|
---|
11046 | </desc>
|
---|
11047 | </param>
|
---|
11048 | <param name="dw" type="long" dir="in">
|
---|
11049 | <desc>
|
---|
11050 | Amount of horizontal mouse wheel moves.
|
---|
11051 | Positive values describe a movement to the left,
|
---|
11052 | negative values describe a movement to the right.
|
---|
11053 | </desc>
|
---|
11054 | </param>
|
---|
11055 | <param name="buttonState" type="long" dir="in">
|
---|
11056 | <desc>
|
---|
11057 | The current state of mouse buttons. Every bit represents
|
---|
11058 | a mouse button as follows:
|
---|
11059 | <table>
|
---|
11060 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
11061 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
11062 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
11063 | </table>
|
---|
11064 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
11065 | otherwise it is released.
|
---|
11066 | </desc>
|
---|
11067 | </param>
|
---|
11068 | </method>
|
---|
11069 |
|
---|
11070 | <method name="putMouseEventAbsolute">
|
---|
11071 | <desc>
|
---|
11072 | Positions the mouse pointer using absolute x and y coordinates.
|
---|
11073 | These coordinates are expressed in pixels and
|
---|
11074 | start from <tt>[1,1]</tt> which corresponds to the top left
|
---|
11075 | corner of the virtual display.
|
---|
11076 |
|
---|
11077 | <result name="E_ACCESSDENIED">
|
---|
11078 | Console not powered up.
|
---|
11079 | </result>
|
---|
11080 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11081 | Could not send mouse event to virtual mouse.
|
---|
11082 | </result>
|
---|
11083 |
|
---|
11084 | <note>
|
---|
11085 | This method will have effect only if absolute mouse
|
---|
11086 | positioning is supported by the guest OS.
|
---|
11087 | </note>
|
---|
11088 |
|
---|
11089 | <see><link to="#absoluteSupported"/></see>
|
---|
11090 | </desc>
|
---|
11091 |
|
---|
11092 | <param name="x" type="long" dir="in">
|
---|
11093 | <desc>
|
---|
11094 | X coordinate of the pointer in pixels, starting from @c 1.
|
---|
11095 | </desc>
|
---|
11096 | </param>
|
---|
11097 | <param name="y" type="long" dir="in">
|
---|
11098 | <desc>
|
---|
11099 | Y coordinate of the pointer in pixels, starting from @c 1.
|
---|
11100 | </desc>
|
---|
11101 | </param>
|
---|
11102 | <param name="dz" type="long" dir="in">
|
---|
11103 | <desc>
|
---|
11104 | Amount of mouse wheel moves.
|
---|
11105 | Positive values describe clockwise wheel rotations,
|
---|
11106 | negative values describe counterclockwise rotations.
|
---|
11107 | </desc>
|
---|
11108 | </param>
|
---|
11109 | <param name="dw" type="long" dir="in">
|
---|
11110 | <desc>
|
---|
11111 | Amount of horizontal mouse wheel moves.
|
---|
11112 | Positive values describe a movement to the left,
|
---|
11113 | negative values describe a movement to the right.
|
---|
11114 | </desc>
|
---|
11115 | </param>
|
---|
11116 | <param name="buttonState" type="long" dir="in">
|
---|
11117 | <desc>
|
---|
11118 | The current state of mouse buttons. Every bit represents
|
---|
11119 | a mouse button as follows:
|
---|
11120 | <table>
|
---|
11121 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
11122 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
11123 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
11124 | </table>
|
---|
11125 | A value of @c 1 means the corresponding button is pressed.
|
---|
11126 | otherwise it is released.
|
---|
11127 | </desc>
|
---|
11128 | </param>
|
---|
11129 | </method>
|
---|
11130 |
|
---|
11131 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
11132 | <desc>
|
---|
11133 | Event source for mouse events.
|
---|
11134 | </desc>
|
---|
11135 | </attribute>
|
---|
11136 |
|
---|
11137 | </interface>
|
---|
11138 |
|
---|
11139 | <!--
|
---|
11140 | // IDisplay
|
---|
11141 | /////////////////////////////////////////////////////////////////////////
|
---|
11142 | -->
|
---|
11143 |
|
---|
11144 | <enum
|
---|
11145 | name="FramebufferPixelFormat"
|
---|
11146 | uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
|
---|
11147 | >
|
---|
11148 | <desc>
|
---|
11149 | Format of the video memory buffer. Constants represented by this enum can
|
---|
11150 | be used to test for particular values of <link
|
---|
11151 | to="IFramebuffer::pixelFormat"/>. See also <link
|
---|
11152 | to="IFramebuffer::requestResize"/>.
|
---|
11153 |
|
---|
11154 | See also www.fourcc.org for more information about FOURCC pixel formats.
|
---|
11155 | </desc>
|
---|
11156 |
|
---|
11157 | <const name="Opaque" value="0">
|
---|
11158 | <desc>
|
---|
11159 | Unknown buffer format (the user may not assume any particular format of
|
---|
11160 | the buffer).
|
---|
11161 | </desc>
|
---|
11162 | </const>
|
---|
11163 | <const name="FOURCC_RGB" value="0x32424752">
|
---|
11164 | <desc>
|
---|
11165 | Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
|
---|
11166 | bit layout).
|
---|
11167 | </desc>
|
---|
11168 | </const>
|
---|
11169 | </enum>
|
---|
11170 |
|
---|
11171 | <interface
|
---|
11172 | name="IFramebuffer" extends="$unknown"
|
---|
11173 | uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
|
---|
11174 | wsmap="suppress"
|
---|
11175 | >
|
---|
11176 | <attribute name="address" type="octet" mod="ptr" readonly="yes">
|
---|
11177 | <desc>Address of the start byte of the frame buffer.</desc>
|
---|
11178 | </attribute>
|
---|
11179 |
|
---|
11180 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
11181 | <desc>Frame buffer width, in pixels.</desc>
|
---|
11182 | </attribute>
|
---|
11183 |
|
---|
11184 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
11185 | <desc>Frame buffer height, in pixels.</desc>
|
---|
11186 | </attribute>
|
---|
11187 |
|
---|
11188 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
11189 | <desc>
|
---|
11190 | Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
|
---|
11191 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
|
---|
11192 | are: 8, 15, 16, 24 and 32.
|
---|
11193 | </desc>
|
---|
11194 | </attribute>
|
---|
11195 |
|
---|
11196 | <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
|
---|
11197 | <desc>
|
---|
11198 | Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
|
---|
11199 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
|
---|
11200 | size of the scan line must be aligned to 32 bits.
|
---|
11201 | </desc>
|
---|
11202 | </attribute>
|
---|
11203 |
|
---|
11204 | <attribute name="pixelFormat" type="unsigned long" readonly="yes">
|
---|
11205 | <desc>
|
---|
11206 | Frame buffer pixel format. It's either one of the values defined by <link
|
---|
11207 | to="FramebufferPixelFormat"/> or a raw FOURCC code.
|
---|
11208 | <note>
|
---|
11209 | This attribute must never return <link
|
---|
11210 | to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
|
---|
11211 | <link to="#address"/> points to must be always known.
|
---|
11212 | </note>
|
---|
11213 | </desc>
|
---|
11214 | </attribute>
|
---|
11215 |
|
---|
11216 | <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
|
---|
11217 | <desc>
|
---|
11218 | Defines whether this frame buffer uses the virtual video card's memory
|
---|
11219 | buffer (guest VRAM) directly or not. See <link
|
---|
11220 | to="IFramebuffer::requestResize"/> for more information.
|
---|
11221 | </desc>
|
---|
11222 | </attribute>
|
---|
11223 |
|
---|
11224 | <attribute name="heightReduction" type="unsigned long" readonly="yes">
|
---|
11225 | <desc>
|
---|
11226 | Hint from the frame buffer about how much of the standard
|
---|
11227 | screen height it wants to use for itself. This information is
|
---|
11228 | exposed to the guest through the VESA BIOS and VMMDev interface
|
---|
11229 | so that it can use it for determining its video mode table. It
|
---|
11230 | is not guaranteed that the guest respects the value.
|
---|
11231 | </desc>
|
---|
11232 | </attribute>
|
---|
11233 |
|
---|
11234 | <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
|
---|
11235 | <desc>
|
---|
11236 | An alpha-blended overlay which is superposed over the frame buffer.
|
---|
11237 | The initial purpose is to allow the display of icons providing
|
---|
11238 | information about the VM state, including disk activity, in front
|
---|
11239 | ends which do not have other means of doing that. The overlay is
|
---|
11240 | designed to controlled exclusively by IDisplay. It has no locking
|
---|
11241 | of its own, and any changes made to it are not guaranteed to be
|
---|
11242 | visible until the affected portion of IFramebuffer is updated. The
|
---|
11243 | overlay can be created lazily the first time it is requested. This
|
---|
11244 | attribute can also return @c null to signal that the overlay is not
|
---|
11245 | implemented.
|
---|
11246 | </desc>
|
---|
11247 | </attribute>
|
---|
11248 |
|
---|
11249 | <attribute name="winId" type="long long" readonly="yes">
|
---|
11250 | <desc>
|
---|
11251 | Platform-dependent identifier of the window where context of this
|
---|
11252 | frame buffer is drawn, or zero if there's no such window.
|
---|
11253 | </desc>
|
---|
11254 | </attribute>
|
---|
11255 |
|
---|
11256 | <method name="lock">
|
---|
11257 | <desc>
|
---|
11258 | Locks the frame buffer.
|
---|
11259 | Gets called by the IDisplay object where this frame buffer is
|
---|
11260 | bound to.
|
---|
11261 | </desc>
|
---|
11262 | </method>
|
---|
11263 |
|
---|
11264 | <method name="unlock">
|
---|
11265 | <desc>
|
---|
11266 | Unlocks the frame buffer.
|
---|
11267 | Gets called by the IDisplay object where this frame buffer is
|
---|
11268 | bound to.
|
---|
11269 | </desc>
|
---|
11270 | </method>
|
---|
11271 |
|
---|
11272 | <method name="notifyUpdate">
|
---|
11273 | <desc>
|
---|
11274 | Informs about an update.
|
---|
11275 | Gets called by the display object where this buffer is
|
---|
11276 | registered.
|
---|
11277 | </desc>
|
---|
11278 | <param name="x" type="unsigned long" dir="in"/>
|
---|
11279 | <param name="y" type="unsigned long" dir="in"/>
|
---|
11280 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11281 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11282 | </method>
|
---|
11283 |
|
---|
11284 | <method name="requestResize">
|
---|
11285 | <desc>
|
---|
11286 | Requests a size and pixel format change.
|
---|
11287 |
|
---|
11288 | There are two modes of working with the video buffer of the virtual
|
---|
11289 | machine. The <i>indirect</i> mode implies that the IFramebuffer
|
---|
11290 | implementation allocates a memory buffer for the requested display mode
|
---|
11291 | and provides it to the virtual machine. In <i>direct</i> mode, the
|
---|
11292 | IFramebuffer implementation uses the memory buffer allocated and owned
|
---|
11293 | by the virtual machine. This buffer represents the video memory of the
|
---|
11294 | emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
|
---|
11295 | usually faster because the implementation gets a raw pointer to the
|
---|
11296 | guest VRAM buffer which it can directly use for visualizing the contents
|
---|
11297 | of the virtual display, as opposed to the indirect mode where the
|
---|
11298 | contents of guest VRAM are copied to the memory buffer provided by
|
---|
11299 | the implementation every time a display update occurs.
|
---|
11300 |
|
---|
11301 | It is important to note that the direct mode is really fast only when
|
---|
11302 | the implementation uses the given guest VRAM buffer directly, for
|
---|
11303 | example, by blitting it to the window representing the virtual machine's
|
---|
11304 | display, which saves at least one copy operation comparing to the
|
---|
11305 | indirect mode. However, using the guest VRAM buffer directly is not
|
---|
11306 | always possible: the format and the color depth of this buffer may be
|
---|
11307 | not supported by the target window, or it may be unknown (opaque) as in
|
---|
11308 | case of text or non-linear multi-plane VGA video modes. In this case,
|
---|
11309 | the indirect mode (that is always available) should be used as a
|
---|
11310 | fallback: when the guest VRAM contents are copied to the
|
---|
11311 | implementation-provided memory buffer, color and format conversion is
|
---|
11312 | done automatically by the underlying code.
|
---|
11313 |
|
---|
11314 | The @a pixelFormat parameter defines whether the direct mode is
|
---|
11315 | available or not. If @a pixelFormat is <link
|
---|
11316 | to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
|
---|
11317 | VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
|
---|
11318 | @a bytesPerLine parameters must be ignored and the implementation must use
|
---|
11319 | the indirect mode (where it provides its own buffer in one of the
|
---|
11320 | supported formats). In all other cases, @a pixelFormat together with
|
---|
11321 | @a bitsPerPixel and @a bytesPerLine define the format of the video memory
|
---|
11322 | buffer pointed to by the @a VRAM parameter and the implementation is
|
---|
11323 | free to choose which mode to use. To indicate that this frame buffer uses
|
---|
11324 | the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
|
---|
11325 | attribute must return @c true and <link to="#address"/> must
|
---|
11326 | return exactly the same address that is passed in the @a VRAM parameter
|
---|
11327 | of this method; otherwise it is assumed that the indirect strategy is
|
---|
11328 | chosen.
|
---|
11329 |
|
---|
11330 | The @a width and @a height parameters represent the size of the
|
---|
11331 | requested display mode in both modes. In case of indirect mode, the
|
---|
11332 | provided memory buffer should be big enough to store data of the given
|
---|
11333 | display mode. In case of direct mode, it is guaranteed that the given
|
---|
11334 | @a VRAM buffer contains enough space to represent the display mode of the
|
---|
11335 | given size. Note that this frame buffer's <link to="#width"/> and <link
|
---|
11336 | to="#height"/> attributes must return exactly the same values as
|
---|
11337 | passed to this method after the resize is completed (see below).
|
---|
11338 |
|
---|
11339 | The @a finished output parameter determines if the implementation has
|
---|
11340 | finished resizing the frame buffer or not. If, for some reason, the
|
---|
11341 | resize cannot be finished immediately during this call, @a finished
|
---|
11342 | must be set to @c false, and the implementation must call
|
---|
11343 | <link to="IDisplay::resizeCompleted"/> after it has returned from
|
---|
11344 | this method as soon as possible. If @a finished is @c false, the
|
---|
11345 | machine will not call any frame buffer methods until
|
---|
11346 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
11347 |
|
---|
11348 | Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
|
---|
11349 | <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
|
---|
11350 | this frame buffer must return exactly the same values as specified in the
|
---|
11351 | parameters of this method, after the resize is completed. If the
|
---|
11352 | indirect mode is chosen, these attributes must return values describing
|
---|
11353 | the format of the implementation's own memory buffer <link
|
---|
11354 | to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
|
---|
11355 | value must always correlate with <link to="#pixelFormat"/>. Note that
|
---|
11356 | the <link to="#pixelFormat"/> attribute must never return <link
|
---|
11357 | to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
|
---|
11358 |
|
---|
11359 | <note>
|
---|
11360 | This method is called by the IDisplay object under the
|
---|
11361 | <link to="#lock"/> provided by this IFramebuffer
|
---|
11362 | implementation. If this method returns @c false in @a finished, then
|
---|
11363 | this lock is not released until
|
---|
11364 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
11365 | </note>
|
---|
11366 | </desc>
|
---|
11367 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11368 | <desc>
|
---|
11369 | Logical screen number. Must be used in the corresponding call to
|
---|
11370 | <link to="IDisplay::resizeCompleted"/> if this call is made.
|
---|
11371 | </desc>
|
---|
11372 | </param>
|
---|
11373 | <param name="pixelFormat" type="unsigned long" dir="in">
|
---|
11374 | <desc>
|
---|
11375 | Pixel format of the memory buffer pointed to by @a VRAM.
|
---|
11376 | See also <link to="FramebufferPixelFormat"/>.
|
---|
11377 | </desc>
|
---|
11378 | </param>
|
---|
11379 | <param name="VRAM" type="octet" mod="ptr" dir="in">
|
---|
11380 | <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
|
---|
11381 | </param>
|
---|
11382 | <param name="bitsPerPixel" type="unsigned long" dir="in">
|
---|
11383 | <desc>Color depth, bits per pixel.</desc>
|
---|
11384 | </param>
|
---|
11385 | <param name="bytesPerLine" type="unsigned long" dir="in">
|
---|
11386 | <desc>Size of one scan line, in bytes.</desc>
|
---|
11387 | </param>
|
---|
11388 | <param name="width" type="unsigned long" dir="in">
|
---|
11389 | <desc>Width of the guest display, in pixels.</desc>
|
---|
11390 | </param>
|
---|
11391 | <param name="height" type="unsigned long" dir="in">
|
---|
11392 | <desc>Height of the guest display, in pixels.</desc>
|
---|
11393 | </param>
|
---|
11394 | <param name="finished" type="boolean" dir="return">
|
---|
11395 | <desc>
|
---|
11396 | Can the VM start using the new frame buffer immediately
|
---|
11397 | after this method returns or it should wait for
|
---|
11398 | <link to="IDisplay::resizeCompleted"/>.
|
---|
11399 | </desc>
|
---|
11400 | </param>
|
---|
11401 | </method>
|
---|
11402 |
|
---|
11403 | <method name="videoModeSupported">
|
---|
11404 | <desc>
|
---|
11405 | Returns whether the frame buffer implementation is willing to
|
---|
11406 | support a given video mode. In case it is not able to render
|
---|
11407 | the video mode (or for some reason not willing), it should
|
---|
11408 | return @c false. Usually this method is called when the guest
|
---|
11409 | asks the VMM device whether a given video mode is supported
|
---|
11410 | so the information returned is directly exposed to the guest.
|
---|
11411 | It is important that this method returns very quickly.
|
---|
11412 | </desc>
|
---|
11413 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11414 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11415 | <param name="bpp" type="unsigned long" dir="in"/>
|
---|
11416 | <param name="supported" type="boolean" dir="return"/>
|
---|
11417 | </method>
|
---|
11418 |
|
---|
11419 | <method name="getVisibleRegion">
|
---|
11420 | <desc>
|
---|
11421 | Returns the visible region of this frame buffer.
|
---|
11422 |
|
---|
11423 | If the @a rectangles parameter is @c null then the value of the
|
---|
11424 | @a count parameter is ignored and the number of elements necessary to
|
---|
11425 | describe the current visible region is returned in @a countCopied.
|
---|
11426 |
|
---|
11427 | If @a rectangles is not @c null but @a count is less
|
---|
11428 | than the required number of elements to store region data, the method
|
---|
11429 | will report a failure. If @a count is equal or greater than the
|
---|
11430 | required number of elements, then the actual number of elements copied
|
---|
11431 | to the provided array will be returned in @a countCopied.
|
---|
11432 |
|
---|
11433 | <note>
|
---|
11434 | The address of the provided array must be in the process space of
|
---|
11435 | this IFramebuffer object.
|
---|
11436 | </note>
|
---|
11437 | <note>
|
---|
11438 | Method not yet implemented.
|
---|
11439 | </note>
|
---|
11440 | </desc>
|
---|
11441 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
11442 | <desc>Pointer to the @c RTRECT array to receive region data.</desc>
|
---|
11443 | </param>
|
---|
11444 | <param name="count" type="unsigned long" dir="in">
|
---|
11445 | <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
|
---|
11446 | </param>
|
---|
11447 | <param name="countCopied" type="unsigned long" dir="return">
|
---|
11448 | <desc>Number of elements copied to the @a rectangles array.</desc>
|
---|
11449 | </param>
|
---|
11450 | </method>
|
---|
11451 |
|
---|
11452 | <method name="setVisibleRegion">
|
---|
11453 | <desc>
|
---|
11454 | Suggests a new visible region to this frame buffer. This region
|
---|
11455 | represents the area of the VM display which is a union of regions of
|
---|
11456 | all top-level windows of the guest operating system running inside the
|
---|
11457 | VM (if the Guest Additions for this system support this
|
---|
11458 | functionality). This information may be used by the frontends to
|
---|
11459 | implement the seamless desktop integration feature.
|
---|
11460 |
|
---|
11461 | <note>
|
---|
11462 | The address of the provided array must be in the process space of
|
---|
11463 | this IFramebuffer object.
|
---|
11464 | </note>
|
---|
11465 | <note>
|
---|
11466 | The IFramebuffer implementation must make a copy of the provided
|
---|
11467 | array of rectangles.
|
---|
11468 | </note>
|
---|
11469 | <note>
|
---|
11470 | Method not yet implemented.
|
---|
11471 | </note>
|
---|
11472 | </desc>
|
---|
11473 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
11474 | <desc>Pointer to the @c RTRECT array.</desc>
|
---|
11475 | </param>
|
---|
11476 | <param name="count" type="unsigned long" dir="in">
|
---|
11477 | <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
|
---|
11478 | </param>
|
---|
11479 | </method>
|
---|
11480 |
|
---|
11481 | <method name="processVHWACommand">
|
---|
11482 | <desc>
|
---|
11483 | Posts a Video HW Acceleration Command to the frame buffer for processing.
|
---|
11484 | The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
|
---|
11485 | are posted from quest to the host to be processed by the host hardware.
|
---|
11486 |
|
---|
11487 | <note>
|
---|
11488 | The address of the provided command must be in the process space of
|
---|
11489 | this IFramebuffer object.
|
---|
11490 | </note>
|
---|
11491 | </desc>
|
---|
11492 |
|
---|
11493 | <param name="command" type="octet" mod="ptr" dir="in">
|
---|
11494 | <desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
|
---|
11495 | </param>
|
---|
11496 | </method>
|
---|
11497 |
|
---|
11498 | </interface>
|
---|
11499 |
|
---|
11500 | <interface
|
---|
11501 | name="IFramebufferOverlay" extends="IFramebuffer"
|
---|
11502 | uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
|
---|
11503 | wsmap="suppress"
|
---|
11504 | >
|
---|
11505 | <desc>
|
---|
11506 | The IFramebufferOverlay interface represents an alpha blended overlay
|
---|
11507 | for displaying status icons above an IFramebuffer. It is always created
|
---|
11508 | not visible, so that it must be explicitly shown. It only covers a
|
---|
11509 | portion of the IFramebuffer, determined by its width, height and
|
---|
11510 | co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
|
---|
11511 | that order) format, and may be written to directly. Do re-read the
|
---|
11512 | width though, after setting it, as it may be adjusted (increased) to
|
---|
11513 | make it more suitable for the front end.
|
---|
11514 | </desc>
|
---|
11515 | <attribute name="x" type="unsigned long" readonly="yes">
|
---|
11516 | <desc>X position of the overlay, relative to the frame buffer.</desc>
|
---|
11517 | </attribute>
|
---|
11518 |
|
---|
11519 | <attribute name="y" type="unsigned long" readonly="yes">
|
---|
11520 | <desc>Y position of the overlay, relative to the frame buffer.</desc>
|
---|
11521 | </attribute>
|
---|
11522 |
|
---|
11523 | <attribute name="visible" type="boolean" readonly="no">
|
---|
11524 | <desc>
|
---|
11525 | Whether the overlay is currently visible.
|
---|
11526 | </desc>
|
---|
11527 | </attribute>
|
---|
11528 |
|
---|
11529 | <attribute name="alpha" type="unsigned long" readonly="no">
|
---|
11530 | <desc>
|
---|
11531 | The global alpha value for the overlay. This may or may not be
|
---|
11532 | supported by a given front end.
|
---|
11533 | </desc>
|
---|
11534 | </attribute>
|
---|
11535 |
|
---|
11536 | <method name="move">
|
---|
11537 | <desc>
|
---|
11538 | Changes the overlay's position relative to the IFramebuffer.
|
---|
11539 | </desc>
|
---|
11540 | <param name="x" type="unsigned long" dir="in"/>
|
---|
11541 | <param name="y" type="unsigned long" dir="in"/>
|
---|
11542 | </method>
|
---|
11543 |
|
---|
11544 | </interface>
|
---|
11545 |
|
---|
11546 | <interface
|
---|
11547 | name="IDisplay" extends="$unknown"
|
---|
11548 | uuid="09EED313-CD56-4D06-BD56-FAC0F716B5DD"
|
---|
11549 | wsmap="managed"
|
---|
11550 | >
|
---|
11551 | <desc>
|
---|
11552 | The IDisplay interface represents the virtual machine's display.
|
---|
11553 |
|
---|
11554 | The object implementing this interface is contained in each
|
---|
11555 | <link to="IConsole::display"/> attribute and represents the visual
|
---|
11556 | output of the virtual machine.
|
---|
11557 |
|
---|
11558 | The virtual display supports pluggable output targets represented by the
|
---|
11559 | IFramebuffer interface. Examples of the output target are a window on
|
---|
11560 | the host computer or an RDP session's display on a remote computer.
|
---|
11561 | </desc>
|
---|
11562 | <method name="getScreenResolution">
|
---|
11563 | <desc>Queries display width, height and color depth for given screen.</desc>
|
---|
11564 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11565 | <param name="width" type="unsigned long" dir="out"/>
|
---|
11566 | <param name="height" type="unsigned long" dir="out"/>
|
---|
11567 | <param name="bitsPerPixel" type="unsigned long" dir="out"/>
|
---|
11568 | </method>
|
---|
11569 |
|
---|
11570 | <method name="setFramebuffer">
|
---|
11571 | <desc>
|
---|
11572 | Sets the framebuffer for given screen.
|
---|
11573 | </desc>
|
---|
11574 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11575 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
11576 | </method>
|
---|
11577 |
|
---|
11578 | <method name="getFramebuffer">
|
---|
11579 | <desc>
|
---|
11580 | Queries the framebuffer for given screen.
|
---|
11581 | </desc>
|
---|
11582 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11583 | <param name="framebuffer" type="IFramebuffer" dir="out"/>
|
---|
11584 | <param name="xOrigin" type="long" dir="out"/>
|
---|
11585 | <param name="yOrigin" type="long" dir="out"/>
|
---|
11586 | </method>
|
---|
11587 |
|
---|
11588 | <method name="setVideoModeHint">
|
---|
11589 | <desc>
|
---|
11590 | Asks VirtualBox to request the given video mode from
|
---|
11591 | the guest. This is just a hint and it cannot be guaranteed
|
---|
11592 | that the requested resolution will be used. Guest Additions
|
---|
11593 | are required for the request to be seen by guests. The caller
|
---|
11594 | should issue the request and wait for a resolution change and
|
---|
11595 | after a timeout retry.
|
---|
11596 |
|
---|
11597 | Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
|
---|
11598 | parameters means that the corresponding values should be taken from the
|
---|
11599 | current video mode (i.e. left unchanged).
|
---|
11600 |
|
---|
11601 | If the guest OS supports multi-monitor configuration then the @a display
|
---|
11602 | parameter specifies the number of the guest display to send the hint to:
|
---|
11603 | @c 0 is the primary display, @c 1 is the first secondary and
|
---|
11604 | so on. If the multi-monitor configuration is not supported, @a display
|
---|
11605 | must be @c 0.
|
---|
11606 |
|
---|
11607 | <result name="E_INVALIDARG">
|
---|
11608 | The @a display is not associated with any monitor.
|
---|
11609 | </result>
|
---|
11610 |
|
---|
11611 | </desc>
|
---|
11612 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11613 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11614 | <param name="bitsPerPixel" type="unsigned long" dir="in"/>
|
---|
11615 | <param name="display" type="unsigned long" dir="in"/>
|
---|
11616 | </method>
|
---|
11617 |
|
---|
11618 | <method name="setSeamlessMode">
|
---|
11619 | <desc>
|
---|
11620 | Enables or disables seamless guest display rendering (seamless desktop
|
---|
11621 | integration) mode.
|
---|
11622 | <note>
|
---|
11623 | Calling this method has no effect if <link
|
---|
11624 | to="IGuest::getFacilityStatus"/> with facility <link to="AdditionsFacilityType::Seamless"/>
|
---|
11625 | does not return <link to="AdditionsFacilityStatus::Active"/>.
|
---|
11626 | </note>
|
---|
11627 | </desc>
|
---|
11628 | <param name="enabled" type="boolean" dir="in"/>
|
---|
11629 | </method>
|
---|
11630 |
|
---|
11631 | <method name="takeScreenShot">
|
---|
11632 | <desc>
|
---|
11633 | Takes a screen shot of the requested size and copies it to the
|
---|
11634 | 32-bpp buffer allocated by the caller and pointed to by @a address.
|
---|
11635 | A pixel consists of 4 bytes in order: B, G, R, 0.
|
---|
11636 |
|
---|
11637 | <note>This API can be used only locally by a VM process through the
|
---|
11638 | COM/XPCOM C++ API as it requires pointer support. It is not
|
---|
11639 | available for scripting langages, Java or any webservice clients.
|
---|
11640 | Unless you are writing a new VM frontend use
|
---|
11641 | <link to="#takeScreenShotToArray" />.
|
---|
11642 | </note>
|
---|
11643 |
|
---|
11644 | <result name="E_NOTIMPL">
|
---|
11645 | Feature not implemented.
|
---|
11646 | </result>
|
---|
11647 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11648 | Could not take a screenshot.
|
---|
11649 | </result>
|
---|
11650 |
|
---|
11651 | </desc>
|
---|
11652 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11653 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
11654 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11655 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11656 | </method>
|
---|
11657 |
|
---|
11658 | <method name="takeScreenShotToArray">
|
---|
11659 | <desc>
|
---|
11660 | Takes a guest screen shot of the requested size and returns it as
|
---|
11661 | an array of bytes in uncompressed 32-bit RGBA format.
|
---|
11662 | A pixel consists of 4 bytes in order: R, G, B, 0xFF.
|
---|
11663 |
|
---|
11664 | This API is slow, but could be the only option to get guest screenshot
|
---|
11665 | for scriptable languages not allowed to manipulate with addresses
|
---|
11666 | directly.
|
---|
11667 |
|
---|
11668 | <result name="E_NOTIMPL">
|
---|
11669 | Feature not implemented.
|
---|
11670 | </result>
|
---|
11671 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11672 | Could not take a screenshot.
|
---|
11673 | </result>
|
---|
11674 | </desc>
|
---|
11675 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11676 | <desc>
|
---|
11677 | Monitor to take screenshot from.
|
---|
11678 | </desc>
|
---|
11679 | </param>
|
---|
11680 | <param name="width" type="unsigned long" dir="in">
|
---|
11681 | <desc>
|
---|
11682 | Desired image width.
|
---|
11683 | </desc>
|
---|
11684 | </param>
|
---|
11685 | <param name="height" type="unsigned long" dir="in">
|
---|
11686 | <desc>
|
---|
11687 | Desired image height.
|
---|
11688 | </desc>
|
---|
11689 | </param>
|
---|
11690 | <param name="screenData" type="octet" dir="return" safearray="yes">
|
---|
11691 | <desc>
|
---|
11692 | Array with resulting screen data.
|
---|
11693 | </desc>
|
---|
11694 | </param>
|
---|
11695 | </method>
|
---|
11696 |
|
---|
11697 | <method name="takeScreenShotPNGToArray">
|
---|
11698 | <desc>
|
---|
11699 | Takes a guest screen shot of the requested size and returns it as
|
---|
11700 | PNG image in array.
|
---|
11701 |
|
---|
11702 | <result name="E_NOTIMPL">
|
---|
11703 | Feature not implemented.
|
---|
11704 | </result>
|
---|
11705 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11706 | Could not take a screenshot.
|
---|
11707 | </result>
|
---|
11708 | </desc>
|
---|
11709 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11710 | <desc>
|
---|
11711 | Monitor to take the screenshot from.
|
---|
11712 | </desc>
|
---|
11713 | </param>
|
---|
11714 | <param name="width" type="unsigned long" dir="in">
|
---|
11715 | <desc>
|
---|
11716 | Desired image width.
|
---|
11717 | </desc>
|
---|
11718 | </param>
|
---|
11719 | <param name="height" type="unsigned long" dir="in">
|
---|
11720 | <desc>
|
---|
11721 | Desired image height.
|
---|
11722 | </desc>
|
---|
11723 | </param>
|
---|
11724 | <param name="screenData" type="octet" dir="return" safearray="yes">
|
---|
11725 | <desc>
|
---|
11726 | Array with resulting screen data.
|
---|
11727 | </desc>
|
---|
11728 | </param>
|
---|
11729 | </method>
|
---|
11730 |
|
---|
11731 | <method name="drawToScreen">
|
---|
11732 | <desc>
|
---|
11733 | Draws a 32-bpp image of the specified size from the given buffer
|
---|
11734 | to the given point on the VM display.
|
---|
11735 |
|
---|
11736 | <result name="E_NOTIMPL">
|
---|
11737 | Feature not implemented.
|
---|
11738 | </result>
|
---|
11739 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11740 | Could not draw to screen.
|
---|
11741 | </result>
|
---|
11742 |
|
---|
11743 | </desc>
|
---|
11744 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11745 | <desc>
|
---|
11746 | Monitor to take the screenshot from.
|
---|
11747 | </desc>
|
---|
11748 | </param>
|
---|
11749 | <param name="address" type="octet" mod="ptr" dir="in">
|
---|
11750 | <desc>
|
---|
11751 | Address to store the screenshot to
|
---|
11752 | </desc>
|
---|
11753 | </param>
|
---|
11754 | <param name="x" type="unsigned long" dir="in">
|
---|
11755 | <desc>
|
---|
11756 | Relative to the screen top left corner.
|
---|
11757 | </desc>
|
---|
11758 | </param>
|
---|
11759 | <param name="y" type="unsigned long" dir="in">
|
---|
11760 | <desc>
|
---|
11761 | Relative to the screen top left corner.
|
---|
11762 | </desc>
|
---|
11763 | </param>
|
---|
11764 | <param name="width" type="unsigned long" dir="in">
|
---|
11765 | <desc>
|
---|
11766 | Desired image width.
|
---|
11767 | </desc>
|
---|
11768 | </param>
|
---|
11769 | <param name="height" type="unsigned long" dir="in">
|
---|
11770 | <desc>
|
---|
11771 | Desired image height.
|
---|
11772 | </desc>
|
---|
11773 | </param>
|
---|
11774 | </method>
|
---|
11775 |
|
---|
11776 | <method name="invalidateAndUpdate">
|
---|
11777 | <desc>
|
---|
11778 | Does a full invalidation of the VM display and instructs the VM
|
---|
11779 | to update it.
|
---|
11780 |
|
---|
11781 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11782 | Could not invalidate and update screen.
|
---|
11783 | </result>
|
---|
11784 |
|
---|
11785 | </desc>
|
---|
11786 | </method>
|
---|
11787 |
|
---|
11788 | <method name="resizeCompleted">
|
---|
11789 | <desc>
|
---|
11790 | Signals that a framebuffer has completed the resize operation.
|
---|
11791 |
|
---|
11792 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
11793 | Operation only valid for external frame buffers.
|
---|
11794 | </result>
|
---|
11795 |
|
---|
11796 | </desc>
|
---|
11797 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11798 | </method>
|
---|
11799 |
|
---|
11800 | <method name="completeVHWACommand">
|
---|
11801 | <desc>
|
---|
11802 | Signals that the Video HW Acceleration command has completed.
|
---|
11803 | </desc>
|
---|
11804 |
|
---|
11805 | <param name="command" type="octet" mod="ptr" dir="in">
|
---|
11806 | <desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
|
---|
11807 | </param>
|
---|
11808 | </method>
|
---|
11809 |
|
---|
11810 | </interface>
|
---|
11811 |
|
---|
11812 | <!--
|
---|
11813 | // INetworkAdapter
|
---|
11814 | /////////////////////////////////////////////////////////////////////////
|
---|
11815 | -->
|
---|
11816 |
|
---|
11817 | <enum
|
---|
11818 | name="NetworkAttachmentType"
|
---|
11819 | uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
|
---|
11820 | >
|
---|
11821 | <desc>
|
---|
11822 | Network attachment type.
|
---|
11823 | </desc>
|
---|
11824 |
|
---|
11825 | <const name="Null" value="0">
|
---|
11826 | <desc>Null value, also means "not attached".</desc>
|
---|
11827 | </const>
|
---|
11828 | <const name="NAT" value="1"/>
|
---|
11829 | <const name="Bridged" value="2"/>
|
---|
11830 | <const name="Internal" value="3"/>
|
---|
11831 | <const name="HostOnly" value="4"/>
|
---|
11832 | <const name="VDE" value="5"/>
|
---|
11833 | </enum>
|
---|
11834 |
|
---|
11835 | <enum
|
---|
11836 | name="NetworkAdapterType"
|
---|
11837 | uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
|
---|
11838 | >
|
---|
11839 | <desc>
|
---|
11840 | Network adapter type.
|
---|
11841 | </desc>
|
---|
11842 |
|
---|
11843 | <const name="Null" value="0">
|
---|
11844 | <desc>Null value (never used by the API).</desc>
|
---|
11845 | </const>
|
---|
11846 | <const name="Am79C970A" value="1">
|
---|
11847 | <desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
|
---|
11848 | </const>
|
---|
11849 | <const name="Am79C973" value="2">
|
---|
11850 | <desc>AMD PCNet-FAST III network card (Am79C973).</desc>
|
---|
11851 | </const>
|
---|
11852 | <const name="I82540EM" value="3">
|
---|
11853 | <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
|
---|
11854 | </const>
|
---|
11855 | <const name="I82543GC" value="4">
|
---|
11856 | <desc>Intel PRO/1000 T Server network card (82543GC).</desc>
|
---|
11857 | </const>
|
---|
11858 | <const name="I82545EM" value="5">
|
---|
11859 | <desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
|
---|
11860 | </const>
|
---|
11861 | <const name="Virtio" value="6">
|
---|
11862 | <desc>Virtio network device.</desc>
|
---|
11863 | </const>
|
---|
11864 | </enum>
|
---|
11865 |
|
---|
11866 | <enum
|
---|
11867 | name="NetworkAdapterPromiscModePolicy"
|
---|
11868 | uuid="c963768a-376f-4c85-8d84-d8ced4b7269e"
|
---|
11869 | >
|
---|
11870 | <desc>
|
---|
11871 | The promiscuous mode policy of an interface.
|
---|
11872 | </desc>
|
---|
11873 |
|
---|
11874 | <const name="Deny" value="1">
|
---|
11875 | <desc>Deny promiscuous mode requests.</desc>
|
---|
11876 | </const>
|
---|
11877 | <const name="AllowNetwork" value="2">
|
---|
11878 | <desc>
|
---|
11879 | Allow promicuous mode, but restrict the scope it to the internal
|
---|
11880 | network so that it only applies to other VMs.
|
---|
11881 | </desc>
|
---|
11882 | </const>
|
---|
11883 | <const name="AllowAll" value="3">
|
---|
11884 | <desc>
|
---|
11885 | Allow promicuous mode, include unrelated traffic going over the wire
|
---|
11886 | and internally on the host.
|
---|
11887 | </desc>
|
---|
11888 | </const>
|
---|
11889 | </enum>
|
---|
11890 |
|
---|
11891 | <interface
|
---|
11892 | name="INetworkAdapter" extends="$unknown"
|
---|
11893 | uuid="6aa240a1-dd58-478e-92e8-aac001ce5547"
|
---|
11894 | wsmap="managed"
|
---|
11895 | >
|
---|
11896 | <desc>
|
---|
11897 | Represents a virtual network adapter that is attached to a virtual machine.
|
---|
11898 | Each virtual machine has a fixed number of network adapter slots with one
|
---|
11899 | instance of this attached to each of them. Call
|
---|
11900 | <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
|
---|
11901 | is attached to a given slot in a given machine.
|
---|
11902 |
|
---|
11903 | Each network adapter can be in one of five attachment modes, which are
|
---|
11904 | represented by the <link to="NetworkAttachmentType" /> enumeration;
|
---|
11905 | see the <link to="#attachmentType" /> attribute.
|
---|
11906 | </desc>
|
---|
11907 |
|
---|
11908 | <attribute name="adapterType" type="NetworkAdapterType">
|
---|
11909 | <desc>
|
---|
11910 | Type of the virtual network adapter. Depending on this value,
|
---|
11911 | VirtualBox will provide a different virtual network hardware
|
---|
11912 | to the guest.
|
---|
11913 | </desc>
|
---|
11914 | </attribute>
|
---|
11915 |
|
---|
11916 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11917 | <desc>
|
---|
11918 | Slot number this adapter is plugged into. Corresponds to
|
---|
11919 | the value you pass to <link to="IMachine::getNetworkAdapter"/>
|
---|
11920 | to obtain this instance.
|
---|
11921 | </desc>
|
---|
11922 | </attribute>
|
---|
11923 |
|
---|
11924 | <attribute name="enabled" type="boolean">
|
---|
11925 | <desc>
|
---|
11926 | Flag whether the network adapter is present in the
|
---|
11927 | guest system. If disabled, the virtual guest hardware will
|
---|
11928 | not contain this network adapter. Can only be changed when
|
---|
11929 | the VM is not running.
|
---|
11930 | </desc>
|
---|
11931 | </attribute>
|
---|
11932 |
|
---|
11933 | <attribute name="MACAddress" type="wstring">
|
---|
11934 | <desc>
|
---|
11935 | Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
|
---|
11936 | it to @c null or an empty string, VirtualBox will generate a unique MAC address.
|
---|
11937 | </desc>
|
---|
11938 | </attribute>
|
---|
11939 |
|
---|
11940 | <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
|
---|
11941 |
|
---|
11942 | <attribute name="hostInterface" type="wstring">
|
---|
11943 | <desc>
|
---|
11944 | Name of the host network interface the VM is attached to.
|
---|
11945 | </desc>
|
---|
11946 | </attribute>
|
---|
11947 |
|
---|
11948 | <attribute name="internalNetwork" type="wstring">
|
---|
11949 | <desc>
|
---|
11950 | Name of the internal network the VM is attached to.
|
---|
11951 | </desc>
|
---|
11952 | </attribute>
|
---|
11953 |
|
---|
11954 | <attribute name="NATNetwork" type="wstring">
|
---|
11955 | <desc>
|
---|
11956 | Name of the NAT network the VM is attached to.
|
---|
11957 | </desc>
|
---|
11958 | </attribute>
|
---|
11959 |
|
---|
11960 | <attribute name="VDENetwork" type="wstring">
|
---|
11961 | <desc>
|
---|
11962 | Name of the VDE switch the VM is attached to.
|
---|
11963 | </desc>
|
---|
11964 | </attribute>
|
---|
11965 |
|
---|
11966 | <attribute name="cableConnected" type="boolean">
|
---|
11967 | <desc>
|
---|
11968 | Flag whether the adapter reports the cable as connected or not.
|
---|
11969 | It can be used to report offline situations to a VM.
|
---|
11970 | </desc>
|
---|
11971 | </attribute>
|
---|
11972 |
|
---|
11973 | <attribute name="lineSpeed" type="unsigned long">
|
---|
11974 | <desc>
|
---|
11975 | Line speed reported by custom drivers, in units of 1 kbps.
|
---|
11976 | </desc>
|
---|
11977 | </attribute>
|
---|
11978 |
|
---|
11979 | <attribute name="promiscModePolicy" type="NetworkAdapterPromiscModePolicy">
|
---|
11980 | <desc>
|
---|
11981 | The promiscuous mode policy of the network adapter when attached to an
|
---|
11982 | internal network, host only network or a bridge.
|
---|
11983 | </desc>
|
---|
11984 | </attribute>
|
---|
11985 |
|
---|
11986 | <attribute name="traceEnabled" type="boolean">
|
---|
11987 | <desc>
|
---|
11988 | Flag whether network traffic from/to the network card should be traced.
|
---|
11989 | Can only be toggled when the VM is turned off.
|
---|
11990 | </desc>
|
---|
11991 | </attribute>
|
---|
11992 |
|
---|
11993 | <attribute name="traceFile" type="wstring">
|
---|
11994 | <desc>
|
---|
11995 | Filename where a network trace will be stored. If not set, VBox-pid.pcap
|
---|
11996 | will be used.
|
---|
11997 | </desc>
|
---|
11998 | </attribute>
|
---|
11999 |
|
---|
12000 | <attribute name="natDriver" type="INATEngine" readonly="yes">
|
---|
12001 | <desc>
|
---|
12002 | Points to the NAT engine which handles the network address translation
|
---|
12003 | for this interface. This is active only when the interface actually uses
|
---|
12004 | NAT (see <link to="#attachToNAT" />).
|
---|
12005 | </desc>
|
---|
12006 | </attribute>
|
---|
12007 |
|
---|
12008 | <attribute name="bootPriority" type="unsigned long">
|
---|
12009 | <desc>
|
---|
12010 | Network boot priority of the adapter. Priority 1 is highest. If not set,
|
---|
12011 | the priority is considered to be at the lowest possible setting.
|
---|
12012 | </desc>
|
---|
12013 | </attribute>
|
---|
12014 |
|
---|
12015 | <attribute name="bandwidthGroup" type="IBandwidthGroup">
|
---|
12016 | <desc>The bandwidth group this network adapter is assigned to.</desc>
|
---|
12017 | </attribute>
|
---|
12018 |
|
---|
12019 | <method name="attachToNAT">
|
---|
12020 | <desc>
|
---|
12021 | Attach the network adapter to the Network Address Translation (NAT) interface.
|
---|
12022 | </desc>
|
---|
12023 | </method>
|
---|
12024 |
|
---|
12025 | <method name="attachToBridgedInterface">
|
---|
12026 | <desc>
|
---|
12027 | Attach the network adapter to a bridged host interface.
|
---|
12028 | </desc>
|
---|
12029 | </method>
|
---|
12030 |
|
---|
12031 | <method name="attachToInternalNetwork">
|
---|
12032 | <desc>
|
---|
12033 | Attach the network adapter to an internal network.
|
---|
12034 | </desc>
|
---|
12035 | </method>
|
---|
12036 |
|
---|
12037 | <method name="attachToHostOnlyInterface">
|
---|
12038 | <desc>
|
---|
12039 | Attach the network adapter to the host-only network.
|
---|
12040 | </desc>
|
---|
12041 | </method>
|
---|
12042 |
|
---|
12043 | <method name="attachToVDE">
|
---|
12044 | <desc>
|
---|
12045 | Attach the network adapter to a VDE network.
|
---|
12046 | </desc>
|
---|
12047 | </method>
|
---|
12048 |
|
---|
12049 | <method name="detach">
|
---|
12050 | <desc>
|
---|
12051 | Detach the network adapter
|
---|
12052 | </desc>
|
---|
12053 | </method>
|
---|
12054 | </interface>
|
---|
12055 |
|
---|
12056 |
|
---|
12057 | <!--
|
---|
12058 | // ISerialPort
|
---|
12059 | /////////////////////////////////////////////////////////////////////////
|
---|
12060 | -->
|
---|
12061 |
|
---|
12062 | <enum
|
---|
12063 | name="PortMode"
|
---|
12064 | uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
|
---|
12065 | >
|
---|
12066 | <desc>
|
---|
12067 | The PortMode enumeration represents possible communication modes for
|
---|
12068 | the virtual serial port device.
|
---|
12069 | </desc>
|
---|
12070 |
|
---|
12071 | <const name="Disconnected" value="0">
|
---|
12072 | <desc>Virtual device is not attached to any real host device.</desc>
|
---|
12073 | </const>
|
---|
12074 | <const name="HostPipe" value="1">
|
---|
12075 | <desc>Virtual device is attached to a host pipe.</desc>
|
---|
12076 | </const>
|
---|
12077 | <const name="HostDevice" value="2">
|
---|
12078 | <desc>Virtual device is attached to a host device.</desc>
|
---|
12079 | </const>
|
---|
12080 | <const name="RawFile" value="3">
|
---|
12081 | <desc>Virtual device is attached to a raw file.</desc>
|
---|
12082 | </const>
|
---|
12083 | </enum>
|
---|
12084 |
|
---|
12085 | <interface
|
---|
12086 | name="ISerialPort" extends="$unknown"
|
---|
12087 | uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
|
---|
12088 | wsmap="managed"
|
---|
12089 | >
|
---|
12090 |
|
---|
12091 | <desc>
|
---|
12092 | The ISerialPort interface represents the virtual serial port device.
|
---|
12093 |
|
---|
12094 | The virtual serial port device acts like an ordinary serial port
|
---|
12095 | inside the virtual machine. This device communicates to the real
|
---|
12096 | serial port hardware in one of two modes: host pipe or host device.
|
---|
12097 |
|
---|
12098 | In host pipe mode, the #path attribute specifies the path to the pipe on
|
---|
12099 | the host computer that represents a serial port. The #server attribute
|
---|
12100 | determines if this pipe is created by the virtual machine process at
|
---|
12101 | machine startup or it must already exist before starting machine
|
---|
12102 | execution.
|
---|
12103 |
|
---|
12104 | In host device mode, the #path attribute specifies the name of the
|
---|
12105 | serial port device on the host computer.
|
---|
12106 |
|
---|
12107 | There is also a third communication mode: the disconnected mode. In this
|
---|
12108 | mode, the guest OS running inside the virtual machine will be able to
|
---|
12109 | detect the serial port, but all port write operations will be discarded
|
---|
12110 | and all port read operations will return no data.
|
---|
12111 |
|
---|
12112 | <see>IMachine::getSerialPort</see>
|
---|
12113 | </desc>
|
---|
12114 |
|
---|
12115 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
12116 | <desc>
|
---|
12117 | Slot number this serial port is plugged into. Corresponds to
|
---|
12118 | the value you pass to <link to="IMachine::getSerialPort"/>
|
---|
12119 | to obtain this instance.
|
---|
12120 | </desc>
|
---|
12121 | </attribute>
|
---|
12122 |
|
---|
12123 | <attribute name="enabled" type="boolean">
|
---|
12124 | <desc>
|
---|
12125 | Flag whether the serial port is enabled. If disabled,
|
---|
12126 | the serial port will not be reported to the guest OS.
|
---|
12127 | </desc>
|
---|
12128 | </attribute>
|
---|
12129 |
|
---|
12130 | <attribute name="IOBase" type="unsigned long">
|
---|
12131 | <desc>Base I/O address of the serial port.</desc>
|
---|
12132 | </attribute>
|
---|
12133 |
|
---|
12134 | <attribute name="IRQ" type="unsigned long">
|
---|
12135 | <desc>IRQ number of the serial port.</desc>
|
---|
12136 | </attribute>
|
---|
12137 |
|
---|
12138 | <attribute name="hostMode" type="PortMode">
|
---|
12139 | <desc>
|
---|
12140 | How is this port connected to the host.
|
---|
12141 | <note>
|
---|
12142 | Changing this attribute may fail if the conditions for
|
---|
12143 | <link to="#path"/> are not met.
|
---|
12144 | </note>
|
---|
12145 | </desc>
|
---|
12146 | </attribute>
|
---|
12147 |
|
---|
12148 | <attribute name="server" type="boolean">
|
---|
12149 | <desc>
|
---|
12150 | Flag whether this serial port acts as a server (creates a new pipe on
|
---|
12151 | the host) or as a client (uses the existing pipe). This attribute is
|
---|
12152 | used only when <link to="#hostMode"/> is PortMode_HostPipe.
|
---|
12153 | </desc>
|
---|
12154 | </attribute>
|
---|
12155 |
|
---|
12156 | <attribute name="path" type="wstring">
|
---|
12157 | <desc>
|
---|
12158 | Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
|
---|
12159 | PortMode_HostPipe, or the host serial device name when
|
---|
12160 | <link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
|
---|
12161 | cases, setting a @c null or empty string as the attribute's value
|
---|
12162 | is an error. Otherwise, the value of this property is ignored.
|
---|
12163 | </desc>
|
---|
12164 | </attribute>
|
---|
12165 |
|
---|
12166 | </interface>
|
---|
12167 |
|
---|
12168 | <!--
|
---|
12169 | // IParallelPort
|
---|
12170 | /////////////////////////////////////////////////////////////////////////
|
---|
12171 | -->
|
---|
12172 |
|
---|
12173 | <interface
|
---|
12174 | name="IParallelPort" extends="$unknown"
|
---|
12175 | uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
|
---|
12176 | wsmap="managed"
|
---|
12177 | >
|
---|
12178 |
|
---|
12179 | <desc>
|
---|
12180 | The IParallelPort interface represents the virtual parallel port device.
|
---|
12181 |
|
---|
12182 | The virtual parallel port device acts like an ordinary parallel port
|
---|
12183 | inside the virtual machine. This device communicates to the real
|
---|
12184 | parallel port hardware using the name of the parallel device on the host
|
---|
12185 | computer specified in the #path attribute.
|
---|
12186 |
|
---|
12187 | Each virtual parallel port device is assigned a base I/O address and an
|
---|
12188 | IRQ number that will be reported to the guest operating system and used
|
---|
12189 | to operate the given parallel port from within the virtual machine.
|
---|
12190 |
|
---|
12191 | <see>IMachine::getParallelPort</see>
|
---|
12192 | </desc>
|
---|
12193 |
|
---|
12194 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
12195 | <desc>
|
---|
12196 | Slot number this parallel port is plugged into. Corresponds to
|
---|
12197 | the value you pass to <link to="IMachine::getParallelPort"/>
|
---|
12198 | to obtain this instance.
|
---|
12199 | </desc>
|
---|
12200 | </attribute>
|
---|
12201 |
|
---|
12202 | <attribute name="enabled" type="boolean">
|
---|
12203 | <desc>
|
---|
12204 | Flag whether the parallel port is enabled. If disabled,
|
---|
12205 | the parallel port will not be reported to the guest OS.
|
---|
12206 | </desc>
|
---|
12207 | </attribute>
|
---|
12208 |
|
---|
12209 | <attribute name="IOBase" type="unsigned long">
|
---|
12210 | <desc>Base I/O address of the parallel port.</desc>
|
---|
12211 | </attribute>
|
---|
12212 |
|
---|
12213 | <attribute name="IRQ" type="unsigned long">
|
---|
12214 | <desc>IRQ number of the parallel port.</desc>
|
---|
12215 | </attribute>
|
---|
12216 |
|
---|
12217 | <attribute name="path" type="wstring">
|
---|
12218 | <desc>
|
---|
12219 | Host parallel device name. If this parallel port is enabled, setting a
|
---|
12220 | @c null or an empty string as this attribute's value will result into
|
---|
12221 | an error.
|
---|
12222 | </desc>
|
---|
12223 | </attribute>
|
---|
12224 |
|
---|
12225 | </interface>
|
---|
12226 |
|
---|
12227 |
|
---|
12228 | <!--
|
---|
12229 | // IMachineDebugger
|
---|
12230 | /////////////////////////////////////////////////////////////////////////
|
---|
12231 | -->
|
---|
12232 |
|
---|
12233 | <interface
|
---|
12234 | name="IMachineDebugger" extends="$unknown"
|
---|
12235 | uuid="1bfd2fa9-0d91-44d3-9515-368dcbb3eb4d"
|
---|
12236 | wsmap="suppress"
|
---|
12237 | >
|
---|
12238 | <method name="dumpGuestCore">
|
---|
12239 | <desc>
|
---|
12240 | Takes a core dump of the guest.
|
---|
12241 |
|
---|
12242 | See include/VBox/dbgfcorefmt.h for details on the file format.
|
---|
12243 | </desc>
|
---|
12244 | <param name="filename" type="wstring" dir="in">
|
---|
12245 | <desc>
|
---|
12246 | The name of the output file. The file must not exist.
|
---|
12247 | </desc>
|
---|
12248 | </param>
|
---|
12249 | <param name="compression" type="wstring" dir="in">
|
---|
12250 | <desc>
|
---|
12251 | Reserved for future compression method indicator.
|
---|
12252 | </desc>
|
---|
12253 | </param>
|
---|
12254 | </method>
|
---|
12255 |
|
---|
12256 | <method name="dumpHostProcessCore">
|
---|
12257 | <desc>
|
---|
12258 | Takes a core dump of the VM process on the host.
|
---|
12259 |
|
---|
12260 | This feature is not implemented in the 4.0.0 release but it may show up
|
---|
12261 | in a dot release.
|
---|
12262 | </desc>
|
---|
12263 | <param name="filename" type="wstring" dir="in">
|
---|
12264 | <desc>
|
---|
12265 | The name of the output file. The file must not exist.
|
---|
12266 | </desc>
|
---|
12267 | </param>
|
---|
12268 | <param name="compression" type="wstring" dir="in">
|
---|
12269 | <desc>
|
---|
12270 | Reserved for future compression method indicator.
|
---|
12271 | </desc>
|
---|
12272 | </param>
|
---|
12273 | </method>
|
---|
12274 |
|
---|
12275 | <method name="info">
|
---|
12276 | <desc>
|
---|
12277 | Interfaces with the info dumpers (DBGFInfo).
|
---|
12278 |
|
---|
12279 | This feature is not implemented in the 4.0.0 release but it may show up
|
---|
12280 | in a dot release.
|
---|
12281 | </desc>
|
---|
12282 | <param name="name" type="wstring" dir="in">
|
---|
12283 | <desc>
|
---|
12284 | The name of the info item.
|
---|
12285 | </desc>
|
---|
12286 | </param>
|
---|
12287 | <param name="args" type="wstring" dir="in">
|
---|
12288 | <desc>
|
---|
12289 | Arguments to the info dumper.
|
---|
12290 | </desc>
|
---|
12291 | </param>
|
---|
12292 | <param name="info" type="wstring" dir="return">
|
---|
12293 | <desc>
|
---|
12294 | The into string.
|
---|
12295 | </desc>
|
---|
12296 | </param>
|
---|
12297 | </method>
|
---|
12298 |
|
---|
12299 | <method name="injectNMI">
|
---|
12300 | <desc>
|
---|
12301 | Inject an NMI into a running VT-x/AMD-V VM.
|
---|
12302 | </desc>
|
---|
12303 | </method>
|
---|
12304 |
|
---|
12305 | <method name="modifyLogGroups">
|
---|
12306 | <desc>
|
---|
12307 | Modifies the group settings of the debug logger.
|
---|
12308 |
|
---|
12309 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12310 | in a dot release.
|
---|
12311 | </desc>
|
---|
12312 | <param name="settings" type="wstring" dir="in">
|
---|
12313 | <desc>The group settings string. See iprt/log.h for details.</desc>
|
---|
12314 | </param>
|
---|
12315 | </method>
|
---|
12316 |
|
---|
12317 | <method name="modifyLogFlags">
|
---|
12318 | <desc>
|
---|
12319 | Modifies the debug logger flags.
|
---|
12320 |
|
---|
12321 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12322 | in a dot release.
|
---|
12323 | </desc>
|
---|
12324 | <param name="settings" type="wstring" dir="in">
|
---|
12325 | <desc>The flags settings string. See iprt/log.h for details.</desc>
|
---|
12326 | </param>
|
---|
12327 | </method>
|
---|
12328 |
|
---|
12329 | <method name="modifyLogDestinations">
|
---|
12330 | <desc>
|
---|
12331 | Modifies the debug logger destinations.
|
---|
12332 |
|
---|
12333 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12334 | in a dot release.
|
---|
12335 | </desc>
|
---|
12336 | <param name="settings" type="wstring" dir="in">
|
---|
12337 | <desc>The destination settings string. See iprt/log.h for details.</desc>
|
---|
12338 | </param>
|
---|
12339 | </method>
|
---|
12340 |
|
---|
12341 | <method name="readPhysicalMemory">
|
---|
12342 | <desc>
|
---|
12343 | Reads guest physical memory, no side effects (MMIO++).
|
---|
12344 |
|
---|
12345 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12346 | in a dot release.
|
---|
12347 | </desc>
|
---|
12348 | <param name="address" type="long long" dir="in">
|
---|
12349 | <desc>The guest physical address.</desc>
|
---|
12350 | </param>
|
---|
12351 | <param name="size" type="unsigned long" dir="in">
|
---|
12352 | <desc>The number of bytes to read.</desc>
|
---|
12353 | </param>
|
---|
12354 | <param name="bytes" type="octet" safearray="yes" dir="return">
|
---|
12355 | <desc>The bytes read.</desc>
|
---|
12356 | </param>
|
---|
12357 | </method>
|
---|
12358 |
|
---|
12359 | <method name="writePhysicalMemory">
|
---|
12360 | <desc>
|
---|
12361 | Writes guest physical memory, access handles (MMIO++) are ignored.
|
---|
12362 |
|
---|
12363 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12364 | in a dot release.
|
---|
12365 | </desc>
|
---|
12366 | <param name="address" type="long long" dir="in">
|
---|
12367 | <desc>The guest physical address.</desc>
|
---|
12368 | </param>
|
---|
12369 | <param name="size" type="unsigned long" dir="in">
|
---|
12370 | <desc>The number of bytes to read.</desc>
|
---|
12371 | </param>
|
---|
12372 | <param name="bytes" type="octet" safearray="yes" dir="in">
|
---|
12373 | <desc>The bytes to write.</desc>
|
---|
12374 | </param>
|
---|
12375 | </method>
|
---|
12376 |
|
---|
12377 | <method name="readVirtualMemory">
|
---|
12378 | <desc>
|
---|
12379 | Reads guest virtual memory, no side effects (MMIO++).
|
---|
12380 |
|
---|
12381 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12382 | in a dot release.
|
---|
12383 | </desc>
|
---|
12384 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12385 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12386 | </param>
|
---|
12387 | <param name="address" type="long long" dir="in">
|
---|
12388 | <desc>The guest virtual address.</desc>
|
---|
12389 | </param>
|
---|
12390 | <param name="size" type="unsigned long" dir="in">
|
---|
12391 | <desc>The number of bytes to read.</desc>
|
---|
12392 | </param>
|
---|
12393 | <param name="bytes" type="octet" safearray="yes" dir="return">
|
---|
12394 | <desc>The bytes read.</desc>
|
---|
12395 | </param>
|
---|
12396 | </method>
|
---|
12397 |
|
---|
12398 | <method name="writeVirtualMemory">
|
---|
12399 | <desc>
|
---|
12400 | Writes guest virtual memory, access handles (MMIO++) are ignored.
|
---|
12401 |
|
---|
12402 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12403 | in a dot release.
|
---|
12404 | </desc>
|
---|
12405 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12406 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12407 | </param>
|
---|
12408 | <param name="address" type="long long" dir="in">
|
---|
12409 | <desc>The guest virtual address.</desc>
|
---|
12410 | </param>
|
---|
12411 | <param name="size" type="unsigned long" dir="in">
|
---|
12412 | <desc>The number of bytes to read.</desc>
|
---|
12413 | </param>
|
---|
12414 | <param name="bytes" type="octet" safearray="yes" dir="in">
|
---|
12415 | <desc>The bytes to write.</desc>
|
---|
12416 | </param>
|
---|
12417 | </method>
|
---|
12418 |
|
---|
12419 | <method name="detectOS">
|
---|
12420 | <desc>
|
---|
12421 | Tries to (re-)detect the guest OS kernel.
|
---|
12422 |
|
---|
12423 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12424 | in a dot release.
|
---|
12425 | </desc>
|
---|
12426 | <param name="os" type="wstring" dir="return">
|
---|
12427 | <desc>
|
---|
12428 | The detected OS kernel on success.
|
---|
12429 | </desc>
|
---|
12430 | </param>
|
---|
12431 | </method>
|
---|
12432 |
|
---|
12433 | <method name="getRegister">
|
---|
12434 | <desc>
|
---|
12435 | Gets one register.
|
---|
12436 |
|
---|
12437 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12438 | in a dot release.
|
---|
12439 | </desc>
|
---|
12440 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12441 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12442 | </param>
|
---|
12443 | <param name="name" type="wstring" dir="in">
|
---|
12444 | <desc>The register name, case is ignored.</desc>
|
---|
12445 | </param>
|
---|
12446 | <param name="value" type="wstring" dir="return">
|
---|
12447 | <desc>
|
---|
12448 | The register value. This is usually a hex value (always 0x prefixed)
|
---|
12449 | but other format may be used for floating point registers (TBD).
|
---|
12450 | </desc>
|
---|
12451 | </param>
|
---|
12452 | </method>
|
---|
12453 |
|
---|
12454 | <method name="getRegisters">
|
---|
12455 | <desc>
|
---|
12456 | Gets all the registers for the given CPU.
|
---|
12457 |
|
---|
12458 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12459 | in a dot release.
|
---|
12460 | </desc>
|
---|
12461 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12462 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12463 | </param>
|
---|
12464 | <param name="names" type="wstring" dir="out" safearray="yes">
|
---|
12465 | <desc>Array containing the lowercase register names.</desc>
|
---|
12466 | </param>
|
---|
12467 | <param name="values" type="wstring" dir="out" safearray="yes">
|
---|
12468 | <desc>
|
---|
12469 | Array paralell to the names holding the register values as if the
|
---|
12470 | register was returned by <link to="IMachineDebugger::getRegister"/>.
|
---|
12471 | </desc>
|
---|
12472 | </param>
|
---|
12473 | </method>
|
---|
12474 |
|
---|
12475 | <method name="setRegister">
|
---|
12476 | <desc>
|
---|
12477 | Gets one register.
|
---|
12478 |
|
---|
12479 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12480 | in a dot release.
|
---|
12481 | </desc>
|
---|
12482 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12483 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12484 | </param>
|
---|
12485 | <param name="name" type="wstring" dir="in">
|
---|
12486 | <desc>The register name, case is ignored.</desc>
|
---|
12487 | </param>
|
---|
12488 | <param name="value" type="wstring" dir="in">
|
---|
12489 | <desc>
|
---|
12490 | The new register value. Hexadecimal, decimal and octal formattings
|
---|
12491 | are supported in addition to any special formattings returned by
|
---|
12492 | the getters.
|
---|
12493 | </desc>
|
---|
12494 | </param>
|
---|
12495 | </method>
|
---|
12496 |
|
---|
12497 | <method name="setRegisters">
|
---|
12498 | <desc>
|
---|
12499 | Sets zero or more registers atomically.
|
---|
12500 |
|
---|
12501 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12502 | in a dot release.
|
---|
12503 | </desc>
|
---|
12504 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12505 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12506 | </param>
|
---|
12507 | <param name="names" type="wstring" dir="in" safearray="yes">
|
---|
12508 | <desc>Array containing the register names, case ignored.</desc>
|
---|
12509 | </param>
|
---|
12510 | <param name="values" type="wstring" dir="in" safearray="yes">
|
---|
12511 | <desc>
|
---|
12512 | Array paralell to the names holding the register values. See
|
---|
12513 | <link to="IMachineDebugger::setRegister"/> for formatting
|
---|
12514 | guidelines.
|
---|
12515 | </desc>
|
---|
12516 | </param>
|
---|
12517 | </method>
|
---|
12518 |
|
---|
12519 | <method name="dumpGuestStack">
|
---|
12520 | <desc>
|
---|
12521 | Produce a simple stack dump using the current guest state.
|
---|
12522 |
|
---|
12523 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12524 | in a dot release.
|
---|
12525 | </desc>
|
---|
12526 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
12527 | <desc>The identifier of the Virtual CPU.</desc>
|
---|
12528 | </param>
|
---|
12529 | <param name="stack" type="wstring" dir="return">
|
---|
12530 | <desc>String containing the formatted stack dump.</desc>
|
---|
12531 | </param>
|
---|
12532 | </method>
|
---|
12533 |
|
---|
12534 | <method name="resetStats">
|
---|
12535 | <desc>
|
---|
12536 | Reset VM statistics.
|
---|
12537 | </desc>
|
---|
12538 | <param name="pattern" type="wstring" dir="in">
|
---|
12539 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
12540 | </param>
|
---|
12541 | </method>
|
---|
12542 |
|
---|
12543 | <method name="dumpStats">
|
---|
12544 | <desc>
|
---|
12545 | Dumps VM statistics.
|
---|
12546 | </desc>
|
---|
12547 | <param name="pattern" type="wstring" dir="in">
|
---|
12548 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
12549 | </param>
|
---|
12550 | </method>
|
---|
12551 |
|
---|
12552 | <method name="getStats">
|
---|
12553 | <desc>
|
---|
12554 | Get the VM statistics in a XMLish format.
|
---|
12555 | </desc>
|
---|
12556 | <param name="pattern" type="wstring" dir="in">
|
---|
12557 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
12558 | </param>
|
---|
12559 | <param name="withDescriptions" type="boolean" dir="in">
|
---|
12560 | <desc>Whether to include the descriptions.</desc>
|
---|
12561 | </param>
|
---|
12562 | <param name="stats" type="wstring" dir="out">
|
---|
12563 | <desc>The XML document containing the statistics.</desc>
|
---|
12564 | </param>
|
---|
12565 | </method>
|
---|
12566 |
|
---|
12567 | <attribute name="singlestep" type="boolean">
|
---|
12568 | <desc>Switch for enabling singlestepping.</desc>
|
---|
12569 | </attribute>
|
---|
12570 |
|
---|
12571 | <attribute name="recompileUser" type="boolean">
|
---|
12572 | <desc>Switch for forcing code recompilation for user mode code.</desc>
|
---|
12573 | </attribute>
|
---|
12574 |
|
---|
12575 | <attribute name="recompileSupervisor" type="boolean">
|
---|
12576 | <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
|
---|
12577 | </attribute>
|
---|
12578 |
|
---|
12579 | <attribute name="PATMEnabled" type="boolean">
|
---|
12580 | <desc>Switch for enabling and disabling the PATM component.</desc>
|
---|
12581 | </attribute>
|
---|
12582 |
|
---|
12583 | <attribute name="CSAMEnabled" type="boolean">
|
---|
12584 | <desc>Switch for enabling and disabling the CSAM component.</desc>
|
---|
12585 | </attribute>
|
---|
12586 |
|
---|
12587 | <attribute name="logEnabled" type="boolean">
|
---|
12588 | <desc>Switch for enabling and disabling the debug logger.</desc>
|
---|
12589 | </attribute>
|
---|
12590 |
|
---|
12591 | <attribute name="logFlags" type="wstring" readonly="yes">
|
---|
12592 | <desc>The debug logger flags.</desc>
|
---|
12593 | </attribute>
|
---|
12594 |
|
---|
12595 | <attribute name="logGroups" type="wstring" readonly="yes">
|
---|
12596 | <desc>The debug logger's group settings.</desc>
|
---|
12597 | </attribute>
|
---|
12598 |
|
---|
12599 | <attribute name="logDestinations" type="wstring" readonly="yes">
|
---|
12600 | <desc>The debug logger's destination settings.</desc>
|
---|
12601 | </attribute>
|
---|
12602 |
|
---|
12603 | <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
|
---|
12604 | <desc>
|
---|
12605 | Flag indicating whether the VM is currently making use of CPU hardware
|
---|
12606 | virtualization extensions.
|
---|
12607 | </desc>
|
---|
12608 | </attribute>
|
---|
12609 |
|
---|
12610 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
|
---|
12611 | <desc>
|
---|
12612 | Flag indicating whether the VM is currently making use of the nested paging
|
---|
12613 | CPU hardware virtualization extension.
|
---|
12614 | </desc>
|
---|
12615 | </attribute>
|
---|
12616 |
|
---|
12617 | <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
|
---|
12618 | <desc>
|
---|
12619 | Flag indicating whether the VM is currently making use of the VPID
|
---|
12620 | VT-x extension.
|
---|
12621 | </desc>
|
---|
12622 | </attribute>
|
---|
12623 |
|
---|
12624 | <attribute name="OSName" type="wstring" readonly="yes">
|
---|
12625 | <desc>
|
---|
12626 | Query the guest OS kernel name as detected by the DBGF.
|
---|
12627 |
|
---|
12628 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12629 | in a dot release.
|
---|
12630 | </desc>
|
---|
12631 | </attribute>
|
---|
12632 |
|
---|
12633 | <attribute name="OSVersion" type="wstring" readonly="yes">
|
---|
12634 | <desc>
|
---|
12635 | Query the guest OS kernel version string as detected by the DBGF.
|
---|
12636 |
|
---|
12637 | This feature is not implemented in the 4.0.0 release but may show up
|
---|
12638 | in a dot release.
|
---|
12639 | </desc>
|
---|
12640 | </attribute>
|
---|
12641 |
|
---|
12642 | <attribute name="PAEEnabled" type="boolean" readonly="yes">
|
---|
12643 | <desc>
|
---|
12644 | Flag indicating whether the VM is currently making use of the Physical
|
---|
12645 | Address Extension CPU feature.
|
---|
12646 | </desc>
|
---|
12647 | </attribute>
|
---|
12648 |
|
---|
12649 | <attribute name="virtualTimeRate" type="unsigned long">
|
---|
12650 | <desc>
|
---|
12651 | The rate at which the virtual time runs expressed as a percentage.
|
---|
12652 | The accepted range is 2% to 20000%.
|
---|
12653 | </desc>
|
---|
12654 | </attribute>
|
---|
12655 |
|
---|
12656 | <attribute name="VM" type="long long" readonly="yes">
|
---|
12657 | <desc>
|
---|
12658 | Gets the VM handle. This is only for internal use while
|
---|
12659 | we carve the details of this interface.
|
---|
12660 | </desc>
|
---|
12661 | </attribute>
|
---|
12662 |
|
---|
12663 | </interface>
|
---|
12664 |
|
---|
12665 | <!--
|
---|
12666 | // IUSBController
|
---|
12667 | /////////////////////////////////////////////////////////////////////////
|
---|
12668 | -->
|
---|
12669 |
|
---|
12670 | <interface
|
---|
12671 | name="IUSBController" extends="$unknown"
|
---|
12672 | uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
|
---|
12673 | wsmap="managed"
|
---|
12674 | >
|
---|
12675 | <attribute name="enabled" type="boolean">
|
---|
12676 | <desc>
|
---|
12677 | Flag whether the USB controller is present in the
|
---|
12678 | guest system. If disabled, the virtual guest hardware will
|
---|
12679 | not contain any USB controller. Can only be changed when
|
---|
12680 | the VM is powered off.
|
---|
12681 | </desc>
|
---|
12682 | </attribute>
|
---|
12683 |
|
---|
12684 | <attribute name="enabledEhci" type="boolean">
|
---|
12685 | <desc>
|
---|
12686 | Flag whether the USB EHCI controller is present in the
|
---|
12687 | guest system. If disabled, the virtual guest hardware will
|
---|
12688 | not contain a USB EHCI controller. Can only be changed when
|
---|
12689 | the VM is powered off.
|
---|
12690 | </desc>
|
---|
12691 | </attribute>
|
---|
12692 |
|
---|
12693 | <attribute name="proxyAvailable" type="boolean" readonly="yes">
|
---|
12694 | <desc>
|
---|
12695 | Flag whether there is an USB proxy available.
|
---|
12696 | </desc>
|
---|
12697 | </attribute>
|
---|
12698 |
|
---|
12699 | <attribute name="USBStandard" type="unsigned short" readonly="yes">
|
---|
12700 | <desc>
|
---|
12701 | USB standard version which the controller implements.
|
---|
12702 | This is a BCD which means that the major version is in the
|
---|
12703 | high byte and minor version is in the low byte.
|
---|
12704 | </desc>
|
---|
12705 | </attribute>
|
---|
12706 |
|
---|
12707 | <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
12708 | <desc>
|
---|
12709 | List of USB device filters associated with the machine.
|
---|
12710 |
|
---|
12711 | If the machine is currently running, these filters are activated
|
---|
12712 | every time a new (supported) USB device is attached to the host
|
---|
12713 | computer that was not ignored by global filters
|
---|
12714 | (<link to="IHost::USBDeviceFilters"/>).
|
---|
12715 |
|
---|
12716 | These filters are also activated when the machine is powered up.
|
---|
12717 | They are run against a list of all currently available USB
|
---|
12718 | devices (in states
|
---|
12719 | <link to="USBDeviceState_Available"/>,
|
---|
12720 | <link to="USBDeviceState_Busy"/>,
|
---|
12721 | <link to="USBDeviceState_Held"/>) that were not previously
|
---|
12722 | ignored by global filters.
|
---|
12723 |
|
---|
12724 | If at least one filter matches the USB device in question, this
|
---|
12725 | device is automatically captured (attached to) the virtual USB
|
---|
12726 | controller of this machine.
|
---|
12727 |
|
---|
12728 | <see>IUSBDeviceFilter, ::IUSBController</see>
|
---|
12729 | </desc>
|
---|
12730 | </attribute>
|
---|
12731 |
|
---|
12732 | <method name="createDeviceFilter">
|
---|
12733 | <desc>
|
---|
12734 | Creates a new USB device filter. All attributes except
|
---|
12735 | the filter name are set to empty (any match),
|
---|
12736 | <i>active</i> is @c false (the filter is not active).
|
---|
12737 |
|
---|
12738 | The created filter can then be added to the list of filters using
|
---|
12739 | <link to="#insertDeviceFilter"/>.
|
---|
12740 |
|
---|
12741 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12742 | The virtual machine is not mutable.
|
---|
12743 | </result>
|
---|
12744 |
|
---|
12745 | <see>#deviceFilters</see>
|
---|
12746 | </desc>
|
---|
12747 | <param name="name" type="wstring" dir="in">
|
---|
12748 | <desc>
|
---|
12749 | Filter name. See <link to="IUSBDeviceFilter::name"/>
|
---|
12750 | for more info.
|
---|
12751 | </desc>
|
---|
12752 | </param>
|
---|
12753 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
12754 | <desc>Created filter object.</desc>
|
---|
12755 | </param>
|
---|
12756 | </method>
|
---|
12757 |
|
---|
12758 | <method name="insertDeviceFilter">
|
---|
12759 | <desc>
|
---|
12760 | Inserts the given USB device to the specified position
|
---|
12761 | in the list of filters.
|
---|
12762 |
|
---|
12763 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
12764 | position is equal to or greater than the number of elements in
|
---|
12765 | the list, the filter is added to the end of the collection.
|
---|
12766 |
|
---|
12767 | <note>
|
---|
12768 | Duplicates are not allowed, so an attempt to insert a
|
---|
12769 | filter that is already in the collection, will return an
|
---|
12770 | error.
|
---|
12771 | </note>
|
---|
12772 |
|
---|
12773 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12774 | Virtual machine is not mutable.
|
---|
12775 | </result>
|
---|
12776 | <result name="E_INVALIDARG">
|
---|
12777 | USB device filter not created within this VirtualBox instance.
|
---|
12778 | </result>
|
---|
12779 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12780 | USB device filter already in list.
|
---|
12781 | </result>
|
---|
12782 |
|
---|
12783 | <see>#deviceFilters</see>
|
---|
12784 | </desc>
|
---|
12785 | <param name="position" type="unsigned long" dir="in">
|
---|
12786 | <desc>Position to insert the filter to.</desc>
|
---|
12787 | </param>
|
---|
12788 | <param name="filter" type="IUSBDeviceFilter" dir="in">
|
---|
12789 | <desc>USB device filter to insert.</desc>
|
---|
12790 | </param>
|
---|
12791 | </method>
|
---|
12792 |
|
---|
12793 | <method name="removeDeviceFilter">
|
---|
12794 | <desc>
|
---|
12795 | Removes a USB device filter from the specified position in the
|
---|
12796 | list of filters.
|
---|
12797 |
|
---|
12798 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
12799 | position equal to or greater than the number of elements in
|
---|
12800 | the list will produce an error.
|
---|
12801 |
|
---|
12802 | <see>#deviceFilters</see>
|
---|
12803 |
|
---|
12804 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12805 | Virtual machine is not mutable.
|
---|
12806 | </result>
|
---|
12807 | <result name="E_INVALIDARG">
|
---|
12808 | USB device filter list empty or invalid @a position.
|
---|
12809 | </result>
|
---|
12810 |
|
---|
12811 | </desc>
|
---|
12812 | <param name="position" type="unsigned long" dir="in">
|
---|
12813 | <desc>Position to remove the filter from.</desc>
|
---|
12814 | </param>
|
---|
12815 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
12816 | <desc>Removed USB device filter.</desc>
|
---|
12817 | </param>
|
---|
12818 | </method>
|
---|
12819 |
|
---|
12820 | </interface>
|
---|
12821 |
|
---|
12822 |
|
---|
12823 | <!--
|
---|
12824 | // IUSBDevice
|
---|
12825 | /////////////////////////////////////////////////////////////////////////
|
---|
12826 | -->
|
---|
12827 |
|
---|
12828 | <interface
|
---|
12829 | name="IUSBDevice" extends="$unknown"
|
---|
12830 | uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
|
---|
12831 | wsmap="managed"
|
---|
12832 | >
|
---|
12833 | <desc>
|
---|
12834 | The IUSBDevice interface represents a virtual USB device attached to the
|
---|
12835 | virtual machine.
|
---|
12836 |
|
---|
12837 | A collection of objects implementing this interface is stored in the
|
---|
12838 | <link to="IConsole::USBDevices"/> attribute which lists all USB devices
|
---|
12839 | attached to a running virtual machine's USB controller.
|
---|
12840 | </desc>
|
---|
12841 |
|
---|
12842 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
12843 | <desc>
|
---|
12844 | Unique USB device ID. This ID is built from #vendorId,
|
---|
12845 | #productId, #revision and #serialNumber.
|
---|
12846 | </desc>
|
---|
12847 | </attribute>
|
---|
12848 |
|
---|
12849 | <attribute name="vendorId" type="unsigned short" readonly="yes">
|
---|
12850 | <desc>Vendor ID.</desc>
|
---|
12851 | </attribute>
|
---|
12852 |
|
---|
12853 | <attribute name="productId" type="unsigned short" readonly="yes">
|
---|
12854 | <desc>Product ID.</desc>
|
---|
12855 | </attribute>
|
---|
12856 |
|
---|
12857 | <attribute name="revision" type="unsigned short" readonly="yes">
|
---|
12858 | <desc>
|
---|
12859 | Product revision number. This is a packed BCD represented as
|
---|
12860 | unsigned short. The high byte is the integer part and the low
|
---|
12861 | byte is the decimal.
|
---|
12862 | </desc>
|
---|
12863 | </attribute>
|
---|
12864 |
|
---|
12865 | <attribute name="manufacturer" type="wstring" readonly="yes">
|
---|
12866 | <desc>Manufacturer string.</desc>
|
---|
12867 | </attribute>
|
---|
12868 |
|
---|
12869 | <attribute name="product" type="wstring" readonly="yes">
|
---|
12870 | <desc>Product string.</desc>
|
---|
12871 | </attribute>
|
---|
12872 |
|
---|
12873 | <attribute name="serialNumber" type="wstring" readonly="yes">
|
---|
12874 | <desc>Serial number string.</desc>
|
---|
12875 | </attribute>
|
---|
12876 |
|
---|
12877 | <attribute name="address" type="wstring" readonly="yes">
|
---|
12878 | <desc>Host specific address of the device.</desc>
|
---|
12879 | </attribute>
|
---|
12880 |
|
---|
12881 | <attribute name="port" type="unsigned short" readonly="yes">
|
---|
12882 | <desc>
|
---|
12883 | Host USB port number the device is physically
|
---|
12884 | connected to.
|
---|
12885 | </desc>
|
---|
12886 | </attribute>
|
---|
12887 |
|
---|
12888 | <attribute name="version" type="unsigned short" readonly="yes">
|
---|
12889 | <desc>
|
---|
12890 | The major USB version of the device - 1 or 2.
|
---|
12891 | </desc>
|
---|
12892 | </attribute>
|
---|
12893 |
|
---|
12894 | <attribute name="portVersion" type="unsigned short" readonly="yes">
|
---|
12895 | <desc>
|
---|
12896 | The major USB version of the host USB port the device is
|
---|
12897 | physically connected to - 1 or 2. For devices not connected to
|
---|
12898 | anything this will have the same value as the version attribute.
|
---|
12899 | </desc>
|
---|
12900 | </attribute>
|
---|
12901 |
|
---|
12902 | <attribute name="remote" type="boolean" readonly="yes">
|
---|
12903 | <desc>
|
---|
12904 | Whether the device is physically connected to a remote VRDE
|
---|
12905 | client or to a local host machine.
|
---|
12906 | </desc>
|
---|
12907 | </attribute>
|
---|
12908 |
|
---|
12909 | </interface>
|
---|
12910 |
|
---|
12911 |
|
---|
12912 | <!--
|
---|
12913 | // IUSBDeviceFilter
|
---|
12914 | /////////////////////////////////////////////////////////////////////////
|
---|
12915 | -->
|
---|
12916 |
|
---|
12917 | <interface
|
---|
12918 | name="IUSBDeviceFilter" extends="$unknown"
|
---|
12919 | uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
|
---|
12920 | wsmap="managed"
|
---|
12921 | >
|
---|
12922 | <desc>
|
---|
12923 | The IUSBDeviceFilter interface represents an USB device filter used
|
---|
12924 | to perform actions on a group of USB devices.
|
---|
12925 |
|
---|
12926 | This type of filters is used by running virtual machines to
|
---|
12927 | automatically capture selected USB devices once they are physically
|
---|
12928 | attached to the host computer.
|
---|
12929 |
|
---|
12930 | A USB device is matched to the given device filter if and only if all
|
---|
12931 | attributes of the device match the corresponding attributes of the
|
---|
12932 | filter (that is, attributes are joined together using the logical AND
|
---|
12933 | operation). On the other hand, all together, filters in the list of
|
---|
12934 | filters carry the semantics of the logical OR operation. So if it is
|
---|
12935 | desirable to create a match like "this vendor id OR this product id",
|
---|
12936 | one needs to create two filters and specify "any match" (see below)
|
---|
12937 | for unused attributes.
|
---|
12938 |
|
---|
12939 | All filter attributes used for matching are strings. Each string
|
---|
12940 | is an expression representing a set of values of the corresponding
|
---|
12941 | device attribute, that will match the given filter. Currently, the
|
---|
12942 | following filtering expressions are supported:
|
---|
12943 |
|
---|
12944 | <ul>
|
---|
12945 | <li><i>Interval filters</i>. Used to specify valid intervals for
|
---|
12946 | integer device attributes (Vendor ID, Product ID and Revision).
|
---|
12947 | The format of the string is:
|
---|
12948 |
|
---|
12949 | <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
|
---|
12950 |
|
---|
12951 | where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
|
---|
12952 | (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
|
---|
12953 | or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
|
---|
12954 | is omitted before a dash (<tt>-</tt>), the minimum possible integer
|
---|
12955 | is assumed; if <tt>n</tt> is omitted after a dash, the maximum
|
---|
12956 | possible integer is assumed.
|
---|
12957 | </li>
|
---|
12958 | <li><i>Boolean filters</i>. Used to specify acceptable values for
|
---|
12959 | boolean device attributes. The format of the string is:
|
---|
12960 |
|
---|
12961 | <tt>true|false|yes|no|0|1</tt>
|
---|
12962 |
|
---|
12963 | </li>
|
---|
12964 | <li><i>Exact match</i>. Used to specify a single value for the given
|
---|
12965 | device attribute. Any string that doesn't start with <tt>int:</tt>
|
---|
12966 | represents the exact match. String device attributes are compared to
|
---|
12967 | this string including case of symbols. Integer attributes are first
|
---|
12968 | converted to a string (see individual filter attributes) and then
|
---|
12969 | compared ignoring case.
|
---|
12970 |
|
---|
12971 | </li>
|
---|
12972 | <li><i>Any match</i>. Any value of the corresponding device attribute
|
---|
12973 | will match the given filter. An empty or @c null string is
|
---|
12974 | used to construct this type of filtering expressions.
|
---|
12975 |
|
---|
12976 | </li>
|
---|
12977 | </ul>
|
---|
12978 |
|
---|
12979 | <note>
|
---|
12980 | On the Windows host platform, interval filters are not currently
|
---|
12981 | available. Also all string filter attributes
|
---|
12982 | (<link to="#manufacturer"/>, <link to="#product"/>,
|
---|
12983 | <link to="#serialNumber"/>) are ignored, so they behave as
|
---|
12984 | <i>any match</i> no matter what string expression is specified.
|
---|
12985 | </note>
|
---|
12986 |
|
---|
12987 | <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
|
---|
12988 | </desc>
|
---|
12989 |
|
---|
12990 | <attribute name="name" type="wstring">
|
---|
12991 | <desc>
|
---|
12992 | Visible name for this filter.
|
---|
12993 | This name is used to visually distinguish one filter from another,
|
---|
12994 | so it can neither be @c null nor an empty string.
|
---|
12995 | </desc>
|
---|
12996 | </attribute>
|
---|
12997 |
|
---|
12998 | <attribute name="active" type="boolean">
|
---|
12999 | <desc>Whether this filter active or has been temporarily disabled.</desc>
|
---|
13000 | </attribute>
|
---|
13001 |
|
---|
13002 | <attribute name="vendorId" type="wstring">
|
---|
13003 | <desc>
|
---|
13004 | <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
|
---|
13005 | The string representation for the <i>exact matching</i>
|
---|
13006 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
13007 | (including leading zeroes).
|
---|
13008 | </desc>
|
---|
13009 | </attribute>
|
---|
13010 |
|
---|
13011 | <attribute name="productId" type="wstring">
|
---|
13012 | <desc>
|
---|
13013 | <link to="IUSBDevice::productId">Product ID</link> filter.
|
---|
13014 | The string representation for the <i>exact matching</i>
|
---|
13015 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
13016 | (including leading zeroes).
|
---|
13017 | </desc>
|
---|
13018 | </attribute>
|
---|
13019 |
|
---|
13020 | <attribute name="revision" type="wstring">
|
---|
13021 | <desc>
|
---|
13022 | <link to="IUSBDevice::productId">Product revision number</link>
|
---|
13023 | filter. The string representation for the <i>exact matching</i>
|
---|
13024 | has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
|
---|
13025 | of the integer part of the revision, and <tt>F</tt> is the
|
---|
13026 | decimal digit of its fractional part (including leading and
|
---|
13027 | trailing zeros).
|
---|
13028 | Note that for interval filters, it's best to use the hexadecimal
|
---|
13029 | form, because the revision is stored as a 16 bit packed BCD value;
|
---|
13030 | so the expression <tt>int:0x0100-0x0199</tt> will match any
|
---|
13031 | revision from <tt>1.0</tt> to <tt>1.99</tt>.
|
---|
13032 | </desc>
|
---|
13033 | </attribute>
|
---|
13034 |
|
---|
13035 | <attribute name="manufacturer" type="wstring">
|
---|
13036 | <desc>
|
---|
13037 | <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
|
---|
13038 | </desc>
|
---|
13039 | </attribute>
|
---|
13040 |
|
---|
13041 | <attribute name="product" type="wstring">
|
---|
13042 | <desc>
|
---|
13043 | <link to="IUSBDevice::product">Product</link> filter.
|
---|
13044 | </desc>
|
---|
13045 | </attribute>
|
---|
13046 |
|
---|
13047 | <attribute name="serialNumber" type="wstring">
|
---|
13048 | <desc>
|
---|
13049 | <link to="IUSBDevice::serialNumber">Serial number</link> filter.
|
---|
13050 | </desc>
|
---|
13051 | </attribute>
|
---|
13052 |
|
---|
13053 | <attribute name="port" type="wstring">
|
---|
13054 | <desc>
|
---|
13055 | <link to="IUSBDevice::port">Host USB port</link> filter.
|
---|
13056 | </desc>
|
---|
13057 | </attribute>
|
---|
13058 |
|
---|
13059 | <attribute name="remote" type="wstring">
|
---|
13060 | <desc>
|
---|
13061 | <link to="IUSBDevice::remote">Remote state</link> filter.
|
---|
13062 | <note>
|
---|
13063 | This filter makes sense only for machine USB filters,
|
---|
13064 | i.e. it is ignored by IHostUSBDeviceFilter objects.
|
---|
13065 | </note>
|
---|
13066 | </desc>
|
---|
13067 | </attribute>
|
---|
13068 |
|
---|
13069 | <attribute name="maskedInterfaces" type="unsigned long">
|
---|
13070 | <desc>
|
---|
13071 | This is an advanced option for hiding one or more USB interfaces
|
---|
13072 | from the guest. The value is a bit mask where the bits that are set
|
---|
13073 | means the corresponding USB interface should be hidden, masked off
|
---|
13074 | if you like.
|
---|
13075 | This feature only works on Linux hosts.
|
---|
13076 | </desc>
|
---|
13077 | </attribute>
|
---|
13078 |
|
---|
13079 | </interface>
|
---|
13080 |
|
---|
13081 |
|
---|
13082 | <!--
|
---|
13083 | // IHostUSBDevice
|
---|
13084 | /////////////////////////////////////////////////////////////////////////
|
---|
13085 | -->
|
---|
13086 |
|
---|
13087 | <enum
|
---|
13088 | name="USBDeviceState"
|
---|
13089 | uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
|
---|
13090 | >
|
---|
13091 | <desc>
|
---|
13092 | USB device state. This enumeration represents all possible states
|
---|
13093 | of the USB device physically attached to the host computer regarding
|
---|
13094 | its state on the host computer and availability to guest computers
|
---|
13095 | (all currently running virtual machines).
|
---|
13096 |
|
---|
13097 | Once a supported USB device is attached to the host, global USB
|
---|
13098 | filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
|
---|
13099 | either ignore the device, or put it to USBDeviceState_Held state, or do
|
---|
13100 | nothing. Unless the device is ignored by global filters, filters of all
|
---|
13101 | currently running guests (<link to="IUSBController::deviceFilters"/>) are
|
---|
13102 | activated that can put it to USBDeviceState_Captured state.
|
---|
13103 |
|
---|
13104 | If the device was ignored by global filters, or didn't match
|
---|
13105 | any filters at all (including guest ones), it is handled by the host
|
---|
13106 | in a normal way. In this case, the device state is determined by
|
---|
13107 | the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
|
---|
13108 | or USBDeviceState_Available, depending on the current device usage.
|
---|
13109 |
|
---|
13110 | Besides auto-capturing based on filters, the device can be manually
|
---|
13111 | captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
|
---|
13112 | state is USBDeviceState_Busy, USBDeviceState_Available or
|
---|
13113 | USBDeviceState_Held.
|
---|
13114 |
|
---|
13115 | <note>
|
---|
13116 | Due to differences in USB stack implementations in Linux and Win32,
|
---|
13117 | states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
|
---|
13118 | only to the Linux version of the product. This also means that (<link
|
---|
13119 | to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
|
---|
13120 | device state is USBDeviceState_Held.
|
---|
13121 | </note>
|
---|
13122 |
|
---|
13123 | <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
|
---|
13124 | </desc>
|
---|
13125 |
|
---|
13126 | <const name="NotSupported" value="0">
|
---|
13127 | <desc>
|
---|
13128 | Not supported by the VirtualBox server, not available to guests.
|
---|
13129 | </desc>
|
---|
13130 | </const>
|
---|
13131 | <const name="Unavailable" value="1">
|
---|
13132 | <desc>
|
---|
13133 | Being used by the host computer exclusively,
|
---|
13134 | not available to guests.
|
---|
13135 | </desc>
|
---|
13136 | </const>
|
---|
13137 | <const name="Busy" value="2">
|
---|
13138 | <desc>
|
---|
13139 | Being used by the host computer, potentially available to guests.
|
---|
13140 | </desc>
|
---|
13141 | </const>
|
---|
13142 | <const name="Available" value="3">
|
---|
13143 | <desc>
|
---|
13144 | Not used by the host computer, available to guests (the host computer
|
---|
13145 | can also start using the device at any time).
|
---|
13146 | </desc>
|
---|
13147 | </const>
|
---|
13148 | <const name="Held" value="4">
|
---|
13149 | <desc>
|
---|
13150 | Held by the VirtualBox server (ignored by the host computer),
|
---|
13151 | available to guests.
|
---|
13152 | </desc>
|
---|
13153 | </const>
|
---|
13154 | <const name="Captured" value="5">
|
---|
13155 | <desc>
|
---|
13156 | Captured by one of the guest computers, not available
|
---|
13157 | to anybody else.
|
---|
13158 | </desc>
|
---|
13159 | </const>
|
---|
13160 | </enum>
|
---|
13161 |
|
---|
13162 | <interface
|
---|
13163 | name="IHostUSBDevice" extends="IUSBDevice"
|
---|
13164 | uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
|
---|
13165 | wsmap="managed"
|
---|
13166 | >
|
---|
13167 | <desc>
|
---|
13168 | The IHostUSBDevice interface represents a physical USB device attached
|
---|
13169 | to the host computer.
|
---|
13170 |
|
---|
13171 | Besides properties inherited from IUSBDevice, this interface adds the
|
---|
13172 | <link to="#state"/> property that holds the current state of the USB
|
---|
13173 | device.
|
---|
13174 |
|
---|
13175 | <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
|
---|
13176 | </desc>
|
---|
13177 |
|
---|
13178 | <attribute name="state" type="USBDeviceState" readonly="yes">
|
---|
13179 | <desc>
|
---|
13180 | Current state of the device.
|
---|
13181 | </desc>
|
---|
13182 | </attribute>
|
---|
13183 |
|
---|
13184 | <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
|
---|
13185 |
|
---|
13186 | </interface>
|
---|
13187 |
|
---|
13188 |
|
---|
13189 | <!--
|
---|
13190 | // IHostUSBDeviceFilter
|
---|
13191 | /////////////////////////////////////////////////////////////////////////
|
---|
13192 | -->
|
---|
13193 |
|
---|
13194 | <enum
|
---|
13195 | name="USBDeviceFilterAction"
|
---|
13196 | uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
|
---|
13197 | >
|
---|
13198 | <desc>
|
---|
13199 | Actions for host USB device filters.
|
---|
13200 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
13201 | </desc>
|
---|
13202 |
|
---|
13203 | <const name="Null" value="0">
|
---|
13204 | <desc>Null value (never used by the API).</desc>
|
---|
13205 | </const>
|
---|
13206 | <const name="Ignore" value="1">
|
---|
13207 | <desc>Ignore the matched USB device.</desc>
|
---|
13208 | </const>
|
---|
13209 | <const name="Hold" value="2">
|
---|
13210 | <desc>Hold the matched USB device.</desc>
|
---|
13211 | </const>
|
---|
13212 | </enum>
|
---|
13213 |
|
---|
13214 | <interface
|
---|
13215 | name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
|
---|
13216 | uuid="4cc70246-d74a-400f-8222-3900489c0374"
|
---|
13217 | wsmap="managed"
|
---|
13218 | >
|
---|
13219 | <desc>
|
---|
13220 | The IHostUSBDeviceFilter interface represents a global filter for a
|
---|
13221 | physical USB device used by the host computer. Used indirectly in
|
---|
13222 | <link to="IHost::USBDeviceFilters"/>.
|
---|
13223 |
|
---|
13224 | Using filters of this type, the host computer determines the initial
|
---|
13225 | state of the USB device after it is physically attached to the
|
---|
13226 | host's USB controller.
|
---|
13227 |
|
---|
13228 | <note>
|
---|
13229 | The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
|
---|
13230 | filters, because it makes sense only for
|
---|
13231 | <link to="IUSBController::deviceFilters">machine USB filters</link>.
|
---|
13232 | </note>
|
---|
13233 |
|
---|
13234 | <see>IHost::USBDeviceFilters</see>
|
---|
13235 | </desc>
|
---|
13236 |
|
---|
13237 | <attribute name="action" type="USBDeviceFilterAction">
|
---|
13238 | <desc>
|
---|
13239 | Action performed by the host when an attached USB device
|
---|
13240 | matches this filter.
|
---|
13241 | </desc>
|
---|
13242 | </attribute>
|
---|
13243 |
|
---|
13244 | </interface>
|
---|
13245 |
|
---|
13246 | <!--
|
---|
13247 | // IAudioAdapter
|
---|
13248 | /////////////////////////////////////////////////////////////////////////
|
---|
13249 | -->
|
---|
13250 |
|
---|
13251 | <enum
|
---|
13252 | name="AudioDriverType"
|
---|
13253 | uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
|
---|
13254 | >
|
---|
13255 | <desc>
|
---|
13256 | Host audio driver type.
|
---|
13257 | </desc>
|
---|
13258 |
|
---|
13259 | <const name="Null" value="0">
|
---|
13260 | <desc>Null value, also means "dummy audio driver".</desc>
|
---|
13261 | </const>
|
---|
13262 | <const name="WinMM" value="1">
|
---|
13263 | <desc>Windows multimedia (Windows hosts only).</desc>
|
---|
13264 | </const>
|
---|
13265 | <const name="OSS" value="2">
|
---|
13266 | <desc>Open Sound System (Linux hosts only).</desc>
|
---|
13267 | </const>
|
---|
13268 | <const name="ALSA" value="3">
|
---|
13269 | <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
|
---|
13270 | </const>
|
---|
13271 | <const name="DirectSound" value="4">
|
---|
13272 | <desc>DirectSound (Windows hosts only).</desc>
|
---|
13273 | </const>
|
---|
13274 | <const name="CoreAudio" value="5">
|
---|
13275 | <desc>CoreAudio (Mac hosts only).</desc>
|
---|
13276 | </const>
|
---|
13277 | <const name="MMPM" value="6">
|
---|
13278 | <desc>Reserved for historical reasons.</desc>
|
---|
13279 | </const>
|
---|
13280 | <const name="Pulse" value="7">
|
---|
13281 | <desc>PulseAudio (Linux hosts only).</desc>
|
---|
13282 | </const>
|
---|
13283 | <const name="SolAudio" value="8">
|
---|
13284 | <desc>Solaris audio (Solaris hosts only).</desc>
|
---|
13285 | </const>
|
---|
13286 | </enum>
|
---|
13287 |
|
---|
13288 | <enum
|
---|
13289 | name="AudioControllerType"
|
---|
13290 | uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
|
---|
13291 | >
|
---|
13292 | <desc>
|
---|
13293 | Virtual audio controller type.
|
---|
13294 | </desc>
|
---|
13295 |
|
---|
13296 | <const name="AC97" value="0"/>
|
---|
13297 | <const name="SB16" value="1"/>
|
---|
13298 | <const name="HDA" value="2"/>
|
---|
13299 | </enum>
|
---|
13300 |
|
---|
13301 | <interface
|
---|
13302 | name="IAudioAdapter" extends="$unknown"
|
---|
13303 | uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
|
---|
13304 | wsmap="managed"
|
---|
13305 | >
|
---|
13306 | <desc>
|
---|
13307 | The IAudioAdapter interface represents the virtual audio adapter of
|
---|
13308 | the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
|
---|
13309 | </desc>
|
---|
13310 | <attribute name="enabled" type="boolean">
|
---|
13311 | <desc>
|
---|
13312 | Flag whether the audio adapter is present in the
|
---|
13313 | guest system. If disabled, the virtual guest hardware will
|
---|
13314 | not contain any audio adapter. Can only be changed when
|
---|
13315 | the VM is not running.
|
---|
13316 | </desc>
|
---|
13317 | </attribute>
|
---|
13318 | <attribute name="audioController" type="AudioControllerType">
|
---|
13319 | <desc>
|
---|
13320 | The audio hardware we emulate.
|
---|
13321 | </desc>
|
---|
13322 | </attribute>
|
---|
13323 | <attribute name="audioDriver" type="AudioDriverType">
|
---|
13324 | <desc>
|
---|
13325 | Audio driver the adapter is connected to. This setting
|
---|
13326 | can only be changed when the VM is not running.
|
---|
13327 | </desc>
|
---|
13328 | </attribute>
|
---|
13329 | </interface>
|
---|
13330 |
|
---|
13331 | <enum
|
---|
13332 | name="AuthType"
|
---|
13333 | uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
|
---|
13334 | >
|
---|
13335 | <desc>
|
---|
13336 | VirtualBox authentication type.
|
---|
13337 | </desc>
|
---|
13338 |
|
---|
13339 | <const name="Null" value="0">
|
---|
13340 | <desc>Null value, also means "no authentication".</desc>
|
---|
13341 | </const>
|
---|
13342 | <const name="External" value="1"/>
|
---|
13343 | <const name="Guest" value="2"/>
|
---|
13344 | </enum>
|
---|
13345 |
|
---|
13346 | <!--
|
---|
13347 | // IVRDEServer
|
---|
13348 | /////////////////////////////////////////////////////////////////////////
|
---|
13349 | -->
|
---|
13350 |
|
---|
13351 | <interface
|
---|
13352 | name="IVRDEServer" extends="$unknown"
|
---|
13353 | uuid="be24e0db-e1d6-4d58-b85b-21053d1511b4"
|
---|
13354 | wsmap="managed"
|
---|
13355 | >
|
---|
13356 | <attribute name="enabled" type="boolean">
|
---|
13357 | <desc>VRDE server status.</desc>
|
---|
13358 | </attribute>
|
---|
13359 |
|
---|
13360 | <attribute name="authType" type="AuthType">
|
---|
13361 | <desc>VRDE authentication method.</desc>
|
---|
13362 | </attribute>
|
---|
13363 |
|
---|
13364 | <attribute name="authTimeout" type="unsigned long">
|
---|
13365 | <desc>Timeout for guest authentication. Milliseconds.</desc>
|
---|
13366 | </attribute>
|
---|
13367 |
|
---|
13368 | <attribute name="allowMultiConnection" type="boolean">
|
---|
13369 | <desc>
|
---|
13370 | Flag whether multiple simultaneous connections to the VM are permitted.
|
---|
13371 | Note that this will be replaced by a more powerful mechanism in the future.
|
---|
13372 | </desc>
|
---|
13373 | </attribute>
|
---|
13374 |
|
---|
13375 | <attribute name="reuseSingleConnection" type="boolean">
|
---|
13376 | <desc>
|
---|
13377 | Flag whether the existing connection must be dropped and a new connection
|
---|
13378 | must be established by the VRDE server, when a new client connects in single
|
---|
13379 | connection mode.
|
---|
13380 | </desc>
|
---|
13381 | </attribute>
|
---|
13382 |
|
---|
13383 | <attribute name="VRDEExtPack" type="wstring">
|
---|
13384 | <desc>
|
---|
13385 | The name of Extension Pack providing VRDE for this VM. Overrides
|
---|
13386 | <link to="ISystemProperties::defaultVRDEExtPack"/>.
|
---|
13387 | </desc>
|
---|
13388 | </attribute>
|
---|
13389 |
|
---|
13390 | <attribute name="AuthLibrary" type="wstring">
|
---|
13391 | <desc>
|
---|
13392 | Library used for authentication of RDP clients by this VM. Overrides
|
---|
13393 | <link to="ISystemProperties::VRDEAuthLibrary"/>.
|
---|
13394 | </desc>
|
---|
13395 | </attribute>
|
---|
13396 |
|
---|
13397 | <attribute name="VRDEProperties" type="wstring" readonly="yes" safearray="yes">
|
---|
13398 | <desc>
|
---|
13399 | Array of names of properties, which are supported by this VRDE server.
|
---|
13400 | </desc>
|
---|
13401 | </attribute>
|
---|
13402 |
|
---|
13403 | <method name="setVRDEProperty">
|
---|
13404 | <desc>
|
---|
13405 | Sets a VRDE specific property string.
|
---|
13406 |
|
---|
13407 | If you pass @c null or empty string as a key @a value, the given @a key
|
---|
13408 | will be deleted.
|
---|
13409 |
|
---|
13410 | </desc>
|
---|
13411 | <param name="key" type="wstring" dir="in">
|
---|
13412 | <desc>Name of the key to set.</desc>
|
---|
13413 | </param>
|
---|
13414 | <param name="value" type="wstring" dir="in">
|
---|
13415 | <desc>Value to assign to the key.</desc>
|
---|
13416 | </param>
|
---|
13417 | </method>
|
---|
13418 |
|
---|
13419 | <method name="getVRDEProperty">
|
---|
13420 | <desc>
|
---|
13421 | Returns a VRDE specific property string.
|
---|
13422 |
|
---|
13423 | If the requested data @a key does not exist, this function will
|
---|
13424 | succeed and return an empty string in the @a value argument.
|
---|
13425 |
|
---|
13426 | </desc>
|
---|
13427 | <param name="key" type="wstring" dir="in">
|
---|
13428 | <desc>Name of the key to get.</desc>
|
---|
13429 | </param>
|
---|
13430 | <param name="value" type="wstring" dir="return">
|
---|
13431 | <desc>Value of the requested key.</desc>
|
---|
13432 | </param>
|
---|
13433 | </method>
|
---|
13434 |
|
---|
13435 | </interface>
|
---|
13436 |
|
---|
13437 |
|
---|
13438 | <!--
|
---|
13439 | // ISharedFolder
|
---|
13440 | /////////////////////////////////////////////////////////////////////////
|
---|
13441 | -->
|
---|
13442 |
|
---|
13443 | <interface
|
---|
13444 | name="ISharedFolder" extends="$unknown"
|
---|
13445 | uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
|
---|
13446 | wsmap="struct"
|
---|
13447 | >
|
---|
13448 | <desc>
|
---|
13449 | The ISharedFolder interface represents a folder in the host computer's
|
---|
13450 | file system accessible from the guest OS running inside a virtual
|
---|
13451 | machine using an associated logical name.
|
---|
13452 |
|
---|
13453 | There are three types of shared folders:
|
---|
13454 | <ul>
|
---|
13455 | <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
|
---|
13456 | folders available to all virtual machines.</li>
|
---|
13457 | <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
|
---|
13458 | VM-specific shared folders available to the given virtual machine at
|
---|
13459 | startup.</li>
|
---|
13460 | <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
|
---|
13461 | VM-specific shared folders created in the session context (for
|
---|
13462 | example, when the virtual machine is running) and automatically
|
---|
13463 | discarded when the session is closed (the VM is powered off).</li>
|
---|
13464 | </ul>
|
---|
13465 |
|
---|
13466 | Logical names of shared folders must be unique within the given scope
|
---|
13467 | (global, permanent or transient). However, they do not need to be unique
|
---|
13468 | across scopes. In this case, the definition of the shared folder in a
|
---|
13469 | more specific scope takes precedence over definitions in all other
|
---|
13470 | scopes. The order of precedence is (more specific to more general):
|
---|
13471 | <ol>
|
---|
13472 | <li>Transient definitions</li>
|
---|
13473 | <li>Permanent definitions</li>
|
---|
13474 | <li>Global definitions</li>
|
---|
13475 | </ol>
|
---|
13476 |
|
---|
13477 | For example, if MyMachine has a shared folder named
|
---|
13478 | <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
|
---|
13479 | transient shared folder named <tt>C_DRIVE</tt> (that points
|
---|
13480 | to <tt>C:\\\\WINDOWS</tt>) will change the definition
|
---|
13481 | of <tt>C_DRIVE</tt> in the guest OS so
|
---|
13482 | that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
|
---|
13483 | to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
|
---|
13484 | PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
|
---|
13485 | the previous (permanent) definition of <tt>C_DRIVE</tt> that points
|
---|
13486 | to <tt>C:\\</tt> if it still exists.
|
---|
13487 |
|
---|
13488 | Note that permanent and transient shared folders of different machines
|
---|
13489 | are in different name spaces, so they don't overlap and don't need to
|
---|
13490 | have unique logical names.
|
---|
13491 |
|
---|
13492 | <note>
|
---|
13493 | Global shared folders are not implemented in the current version of the
|
---|
13494 | product.
|
---|
13495 | </note>
|
---|
13496 | </desc>
|
---|
13497 |
|
---|
13498 | <attribute name="name" type="wstring" readonly="yes">
|
---|
13499 | <desc>Logical name of the shared folder.</desc>
|
---|
13500 | </attribute>
|
---|
13501 |
|
---|
13502 | <attribute name="hostPath" type="wstring" readonly="yes">
|
---|
13503 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
13504 | </attribute>
|
---|
13505 |
|
---|
13506 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
13507 | <desc>
|
---|
13508 | Whether the folder defined by the host path is currently
|
---|
13509 | accessible or not.
|
---|
13510 | For example, the folder can be inaccessible if it is placed
|
---|
13511 | on the network share that is not available by the time
|
---|
13512 | this property is read.
|
---|
13513 | </desc>
|
---|
13514 | </attribute>
|
---|
13515 |
|
---|
13516 | <attribute name="writable" type="boolean" readonly="yes">
|
---|
13517 | <desc>
|
---|
13518 | Whether the folder defined by the host path is writable or
|
---|
13519 | not.
|
---|
13520 | </desc>
|
---|
13521 | </attribute>
|
---|
13522 |
|
---|
13523 | <attribute name="autoMount" type="boolean" readonly="yes">
|
---|
13524 | <desc>
|
---|
13525 | Whether the folder gets automatically mounted by the guest or not.
|
---|
13526 | </desc>
|
---|
13527 | </attribute>
|
---|
13528 |
|
---|
13529 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
13530 | <desc>
|
---|
13531 | Text message that represents the result of the last accessibility
|
---|
13532 | check.
|
---|
13533 |
|
---|
13534 | Accessibility checks are performed each time the <link to="#accessible"/>
|
---|
13535 | attribute is read. An empty string is returned if the last
|
---|
13536 | accessibility check was successful. A non-empty string indicates a
|
---|
13537 | failure and should normally describe a reason of the failure (for
|
---|
13538 | example, a file read error).
|
---|
13539 | </desc>
|
---|
13540 | </attribute>
|
---|
13541 |
|
---|
13542 | </interface>
|
---|
13543 |
|
---|
13544 | <!--
|
---|
13545 | // ISession
|
---|
13546 | /////////////////////////////////////////////////////////////////////////
|
---|
13547 | -->
|
---|
13548 |
|
---|
13549 | <interface
|
---|
13550 | name="IInternalSessionControl" extends="$unknown"
|
---|
13551 | uuid="3a975b65-27e7-42fa-9176-d097d7bd78d4"
|
---|
13552 | internal="yes"
|
---|
13553 | wsmap="suppress"
|
---|
13554 | >
|
---|
13555 | <method name="getPID">
|
---|
13556 | <desc>PID of the process that has created this Session object.
|
---|
13557 | </desc>
|
---|
13558 | <param name="pid" type="unsigned long" dir="return"/>
|
---|
13559 | </method>
|
---|
13560 |
|
---|
13561 | <method name="getRemoteConsole">
|
---|
13562 | <desc>
|
---|
13563 | Returns the console object suitable for remote control.
|
---|
13564 |
|
---|
13565 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13566 | Session state prevents operation.
|
---|
13567 | </result>
|
---|
13568 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13569 | Session type prevents operation.
|
---|
13570 | </result>
|
---|
13571 |
|
---|
13572 | </desc>
|
---|
13573 | <param name="console" type="IConsole" dir="return"/>
|
---|
13574 | </method>
|
---|
13575 |
|
---|
13576 | <method name="assignMachine">
|
---|
13577 | <desc>
|
---|
13578 | Assigns the machine object associated with this direct-type
|
---|
13579 | session or informs the session that it will be a remote one
|
---|
13580 | (if @a machine == @c null).
|
---|
13581 |
|
---|
13582 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13583 | Session state prevents operation.
|
---|
13584 | </result>
|
---|
13585 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13586 | Session type prevents operation.
|
---|
13587 | </result>
|
---|
13588 |
|
---|
13589 | </desc>
|
---|
13590 | <param name="machine" type="IMachine" dir="in"/>
|
---|
13591 | </method>
|
---|
13592 |
|
---|
13593 | <method name="assignRemoteMachine">
|
---|
13594 | <desc>
|
---|
13595 | Assigns the machine and the (remote) console object associated with
|
---|
13596 | this remote-type session.
|
---|
13597 |
|
---|
13598 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13599 | Session state prevents operation.
|
---|
13600 | </result>
|
---|
13601 |
|
---|
13602 | </desc>
|
---|
13603 | <param name="machine" type="IMachine" dir="in"/>
|
---|
13604 | <param name="console" type="IConsole" dir="in"/>
|
---|
13605 | </method>
|
---|
13606 |
|
---|
13607 | <method name="updateMachineState">
|
---|
13608 | <desc>
|
---|
13609 | Updates the machine state in the VM process.
|
---|
13610 | Must be called only in certain cases
|
---|
13611 | (see the method implementation).
|
---|
13612 |
|
---|
13613 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13614 | Session state prevents operation.
|
---|
13615 | </result>
|
---|
13616 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13617 | Session type prevents operation.
|
---|
13618 | </result>
|
---|
13619 |
|
---|
13620 | </desc>
|
---|
13621 | <param name="aMachineState" type="MachineState" dir="in"/>
|
---|
13622 | </method>
|
---|
13623 |
|
---|
13624 | <method name="uninitialize">
|
---|
13625 | <desc>
|
---|
13626 | Uninitializes (closes) this session. Used by VirtualBox to close
|
---|
13627 | the corresponding remote session when the direct session dies
|
---|
13628 | or gets closed.
|
---|
13629 |
|
---|
13630 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13631 | Session state prevents operation.
|
---|
13632 | </result>
|
---|
13633 |
|
---|
13634 | </desc>
|
---|
13635 | </method>
|
---|
13636 |
|
---|
13637 | <method name="onNetworkAdapterChange">
|
---|
13638 | <desc>
|
---|
13639 | Triggered when settings of a network adapter of the
|
---|
13640 | associated virtual machine have changed.
|
---|
13641 |
|
---|
13642 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13643 | Session state prevents operation.
|
---|
13644 | </result>
|
---|
13645 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13646 | Session type prevents operation.
|
---|
13647 | </result>
|
---|
13648 |
|
---|
13649 | </desc>
|
---|
13650 | <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
|
---|
13651 | <param name="changeAdapter" type="boolean" dir="in"/>
|
---|
13652 | </method>
|
---|
13653 |
|
---|
13654 | <method name="onSerialPortChange">
|
---|
13655 | <desc>
|
---|
13656 | Triggered when settings of a serial port of the
|
---|
13657 | associated virtual machine have changed.
|
---|
13658 |
|
---|
13659 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13660 | Session state prevents operation.
|
---|
13661 | </result>
|
---|
13662 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13663 | Session type prevents operation.
|
---|
13664 | </result>
|
---|
13665 |
|
---|
13666 | </desc>
|
---|
13667 | <param name="serialPort" type="ISerialPort" dir="in"/>
|
---|
13668 | </method>
|
---|
13669 |
|
---|
13670 | <method name="onParallelPortChange">
|
---|
13671 | <desc>
|
---|
13672 | Triggered when settings of a parallel port of the
|
---|
13673 | associated virtual machine have changed.
|
---|
13674 |
|
---|
13675 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13676 | Session state prevents operation.
|
---|
13677 | </result>
|
---|
13678 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13679 | Session type prevents operation.
|
---|
13680 | </result>
|
---|
13681 |
|
---|
13682 | </desc>
|
---|
13683 | <param name="parallelPort" type="IParallelPort" dir="in"/>
|
---|
13684 | </method>
|
---|
13685 |
|
---|
13686 | <method name="onStorageControllerChange">
|
---|
13687 | <desc>
|
---|
13688 | Triggered when settings of a storage controller of the
|
---|
13689 | associated virtual machine have changed.
|
---|
13690 |
|
---|
13691 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13692 | Session state prevents operation.
|
---|
13693 | </result>
|
---|
13694 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13695 | Session type prevents operation.
|
---|
13696 | </result>
|
---|
13697 |
|
---|
13698 | </desc>
|
---|
13699 | </method>
|
---|
13700 |
|
---|
13701 | <method name="onMediumChange">
|
---|
13702 | <desc>
|
---|
13703 | Triggered when attached media of the
|
---|
13704 | associated virtual machine have changed.
|
---|
13705 |
|
---|
13706 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13707 | Session state prevents operation.
|
---|
13708 | </result>
|
---|
13709 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13710 | Session type prevents operation.
|
---|
13711 | </result>
|
---|
13712 |
|
---|
13713 | </desc>
|
---|
13714 |
|
---|
13715 | <param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
|
---|
13716 | <param name="force" type="boolean" dir="in"/>
|
---|
13717 | </method>
|
---|
13718 |
|
---|
13719 | <method name="onStorageDeviceChange">
|
---|
13720 | <desc>
|
---|
13721 | Triggered when attached storage devices of the
|
---|
13722 | associated virtual machine have changed.
|
---|
13723 |
|
---|
13724 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13725 | Session state prevents operation.
|
---|
13726 | </result>
|
---|
13727 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13728 | Session type prevents operation.
|
---|
13729 | </result>
|
---|
13730 |
|
---|
13731 | </desc>
|
---|
13732 |
|
---|
13733 | <param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
|
---|
13734 | <param name="remove" type="boolean" dir="in">
|
---|
13735 | <desc>TRUE if the device is removed, FALSE if it was added.</desc>
|
---|
13736 | </param>
|
---|
13737 | </method>
|
---|
13738 |
|
---|
13739 | <method name="onCPUChange">
|
---|
13740 | <desc>
|
---|
13741 | Notification when a CPU changes.
|
---|
13742 | </desc>
|
---|
13743 | <param name="cpu" type="unsigned long" dir="in">
|
---|
13744 | <desc>The CPU which changed</desc>
|
---|
13745 | </param>
|
---|
13746 | <param name="add" type="boolean" dir="in">
|
---|
13747 | <desc>Flag whether the CPU was added or removed</desc>
|
---|
13748 | </param>
|
---|
13749 | </method>
|
---|
13750 |
|
---|
13751 | <method name="onCPUExecutionCapChange">
|
---|
13752 | <desc>
|
---|
13753 | Notification when the CPU execution cap changes.
|
---|
13754 | </desc>
|
---|
13755 | <param name="executionCap" type="unsigned long" dir="in">
|
---|
13756 | <desc>The new CPU execution cap value. (1-100)</desc>
|
---|
13757 | </param>
|
---|
13758 | </method>
|
---|
13759 |
|
---|
13760 | <method name="onVRDEServerChange">
|
---|
13761 | <desc>
|
---|
13762 | Triggered when settings of the VRDE server object of the
|
---|
13763 | associated virtual machine have changed.
|
---|
13764 |
|
---|
13765 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13766 | Session state prevents operation.
|
---|
13767 | </result>
|
---|
13768 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13769 | Session type prevents operation.
|
---|
13770 | </result>
|
---|
13771 |
|
---|
13772 | </desc>
|
---|
13773 | <param name="restart" type="boolean" dir="in">
|
---|
13774 | <desc>Flag whether the server must be restarted</desc>
|
---|
13775 | </param>
|
---|
13776 | </method>
|
---|
13777 |
|
---|
13778 | <method name="onUSBControllerChange">
|
---|
13779 | <desc>
|
---|
13780 | Triggered when settings of the USB controller object of the
|
---|
13781 | associated virtual machine have changed.
|
---|
13782 |
|
---|
13783 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13784 | Session state prevents operation.
|
---|
13785 | </result>
|
---|
13786 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13787 | Session type prevents operation.
|
---|
13788 | </result>
|
---|
13789 |
|
---|
13790 | </desc>
|
---|
13791 | </method>
|
---|
13792 |
|
---|
13793 | <method name="onSharedFolderChange">
|
---|
13794 | <desc>
|
---|
13795 | Triggered when a permanent (global or machine) shared folder has been
|
---|
13796 | created or removed.
|
---|
13797 | <note>
|
---|
13798 | We don't pass shared folder parameters in this notification because
|
---|
13799 | the order in which parallel notifications are delivered is not defined,
|
---|
13800 | therefore it could happen that these parameters were outdated by the
|
---|
13801 | time of processing this notification.
|
---|
13802 | </note>
|
---|
13803 |
|
---|
13804 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13805 | Session state prevents operation.
|
---|
13806 | </result>
|
---|
13807 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13808 | Session type prevents operation.
|
---|
13809 | </result>
|
---|
13810 |
|
---|
13811 | </desc>
|
---|
13812 | <param name="global" type="boolean" dir="in"/>
|
---|
13813 | </method>
|
---|
13814 |
|
---|
13815 | <method name="onUSBDeviceAttach">
|
---|
13816 | <desc>
|
---|
13817 | Triggered when a request to capture a USB device (as a result
|
---|
13818 | of matched USB filters or direct call to
|
---|
13819 | <link to="IConsole::attachUSBDevice"/>) has completed.
|
---|
13820 | A @c null @a error object means success, otherwise it
|
---|
13821 | describes a failure.
|
---|
13822 |
|
---|
13823 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13824 | Session state prevents operation.
|
---|
13825 | </result>
|
---|
13826 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13827 | Session type prevents operation.
|
---|
13828 | </result>
|
---|
13829 |
|
---|
13830 | </desc>
|
---|
13831 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
13832 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
13833 | <param name="maskedInterfaces" type="unsigned long" dir="in"/>
|
---|
13834 | </method>
|
---|
13835 |
|
---|
13836 | <method name="onUSBDeviceDetach">
|
---|
13837 | <desc>
|
---|
13838 | Triggered when a request to release the USB device (as a result
|
---|
13839 | of machine termination or direct call to
|
---|
13840 | <link to="IConsole::detachUSBDevice"/>) has completed.
|
---|
13841 | A @c null @a error object means success, otherwise it
|
---|
13842 | describes a failure.
|
---|
13843 |
|
---|
13844 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13845 | Session state prevents operation.
|
---|
13846 | </result>
|
---|
13847 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13848 | Session type prevents operation.
|
---|
13849 | </result>
|
---|
13850 |
|
---|
13851 | </desc>
|
---|
13852 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
13853 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
13854 | </method>
|
---|
13855 |
|
---|
13856 | <method name="onShowWindow">
|
---|
13857 | <desc>
|
---|
13858 | Called by <link to="IMachine::canShowConsoleWindow"/> and by
|
---|
13859 | <link to="IMachine::showConsoleWindow"/> in order to notify
|
---|
13860 | console listeners
|
---|
13861 | <link to="ICanShowWindowEvent"/>
|
---|
13862 | and <link to="IShowWindowEvent"/>.
|
---|
13863 |
|
---|
13864 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13865 | Session type prevents operation.
|
---|
13866 | </result>
|
---|
13867 |
|
---|
13868 | </desc>
|
---|
13869 | <param name="check" type="boolean" dir="in"/>
|
---|
13870 | <param name="canShow" type="boolean" dir="out"/>
|
---|
13871 | <param name="winId" type="long long" dir="out"/>
|
---|
13872 | </method>
|
---|
13873 |
|
---|
13874 | <method name="onBandwidthGroupChange">
|
---|
13875 | <desc>
|
---|
13876 | Notification when one of the bandwidth groups change.
|
---|
13877 | </desc>
|
---|
13878 | <param name="bandwidthGroup" type="IBandwidthGroup" dir="in">
|
---|
13879 | <desc>The bandwidth group which changed.</desc>
|
---|
13880 | </param>
|
---|
13881 | </method>
|
---|
13882 |
|
---|
13883 | <method name="accessGuestProperty">
|
---|
13884 | <desc>
|
---|
13885 | Called by <link to="IMachine::getGuestProperty"/> and by
|
---|
13886 | <link to="IMachine::setGuestProperty"/> in order to read and
|
---|
13887 | modify guest properties.
|
---|
13888 |
|
---|
13889 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13890 | Machine session is not open.
|
---|
13891 | </result>
|
---|
13892 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13893 | Session type is not direct.
|
---|
13894 | </result>
|
---|
13895 |
|
---|
13896 | </desc>
|
---|
13897 | <param name="name" type="wstring" dir="in"/>
|
---|
13898 | <param name="value" type="wstring" dir="in"/>
|
---|
13899 | <param name="flags" type="wstring" dir="in"/>
|
---|
13900 | <param name="isSetter" type="boolean" dir="in"/>
|
---|
13901 | <param name="retValue" type="wstring" dir="out"/>
|
---|
13902 | <param name="retTimestamp" type="long long" dir="out"/>
|
---|
13903 | <param name="retFlags" type="wstring" dir="out"/>
|
---|
13904 | </method>
|
---|
13905 |
|
---|
13906 | <method name="enumerateGuestProperties">
|
---|
13907 | <desc>
|
---|
13908 | Return a list of the guest properties matching a set of patterns along
|
---|
13909 | with their values, time stamps and flags.
|
---|
13910 |
|
---|
13911 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13912 | Machine session is not open.
|
---|
13913 | </result>
|
---|
13914 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13915 | Session type is not direct.
|
---|
13916 | </result>
|
---|
13917 |
|
---|
13918 | </desc>
|
---|
13919 | <param name="patterns" type="wstring" dir="in">
|
---|
13920 | <desc>
|
---|
13921 | The patterns to match the properties against as a comma-separated
|
---|
13922 | string. If this is empty, all properties currently set will be
|
---|
13923 | returned.
|
---|
13924 | </desc>
|
---|
13925 | </param>
|
---|
13926 | <param name="key" type="wstring" dir="out" safearray="yes">
|
---|
13927 | <desc>
|
---|
13928 | The key names of the properties returned.
|
---|
13929 | </desc>
|
---|
13930 | </param>
|
---|
13931 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
13932 | <desc>
|
---|
13933 | The values of the properties returned. The array entries match the
|
---|
13934 | corresponding entries in the @a key array.
|
---|
13935 | </desc>
|
---|
13936 | </param>
|
---|
13937 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
13938 | <desc>
|
---|
13939 | The time stamps of the properties returned. The array entries match
|
---|
13940 | the corresponding entries in the @a key array.
|
---|
13941 | </desc>
|
---|
13942 | </param>
|
---|
13943 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
13944 | <desc>
|
---|
13945 | The flags of the properties returned. The array entries match the
|
---|
13946 | corresponding entries in the @a key array.
|
---|
13947 | </desc>
|
---|
13948 | </param>
|
---|
13949 | </method>
|
---|
13950 |
|
---|
13951 | <method name="onlineMergeMedium">
|
---|
13952 | <desc>
|
---|
13953 | Triggers online merging of a hard disk. Used internally when deleting
|
---|
13954 | a snapshot while a VM referring to the same hard disk chain is running.
|
---|
13955 |
|
---|
13956 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
13957 | Machine session is not open.
|
---|
13958 | </result>
|
---|
13959 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13960 | Session type is not direct.
|
---|
13961 | </result>
|
---|
13962 |
|
---|
13963 | </desc>
|
---|
13964 | <param name="mediumAttachment" type="IMediumAttachment" dir="in">
|
---|
13965 | <desc>The medium attachment to identify the medium chain.</desc>
|
---|
13966 | </param>
|
---|
13967 | <param name="sourceIdx" type="unsigned long" dir="in">
|
---|
13968 | <desc>The index of the source image in the chain.
|
---|
13969 | Redundant, but drastically reduces IPC.</desc>
|
---|
13970 | </param>
|
---|
13971 | <param name="targetIdx" type="unsigned long" dir="in">
|
---|
13972 | <desc>The index of the target image in the chain.
|
---|
13973 | Redundant, but drastically reduces IPC.</desc>
|
---|
13974 | </param>
|
---|
13975 | <param name="source" type="IMedium" dir="in">
|
---|
13976 | <desc>Merge source medium.</desc>
|
---|
13977 | </param>
|
---|
13978 | <param name="target" type="IMedium" dir="in">
|
---|
13979 | <desc>Merge target medium.</desc>
|
---|
13980 | </param>
|
---|
13981 | <param name="mergeForward" type="boolean" dir="in">
|
---|
13982 | <desc>Merge direction.</desc>
|
---|
13983 | </param>
|
---|
13984 | <param name="parentForTarget" type="IMedium" dir="in">
|
---|
13985 | <desc>For forward merges: new parent for target medium.</desc>
|
---|
13986 | </param>
|
---|
13987 | <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
|
---|
13988 | <desc>For backward merges: list of media which need their parent UUID
|
---|
13989 | updated.</desc>
|
---|
13990 | </param>
|
---|
13991 | <param name="progress" type="IProgress" dir="in">
|
---|
13992 | <desc>
|
---|
13993 | Progress object for this operation.
|
---|
13994 | </desc>
|
---|
13995 | </param>
|
---|
13996 | </method>
|
---|
13997 |
|
---|
13998 | </interface>
|
---|
13999 |
|
---|
14000 | <interface
|
---|
14001 | name="ISession" extends="$unknown"
|
---|
14002 | uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
|
---|
14003 | wsmap="managed"
|
---|
14004 | >
|
---|
14005 | <desc>
|
---|
14006 | The ISession interface represents a client process and allows for locking
|
---|
14007 | virtual machines (represented by IMachine objects) to prevent conflicting
|
---|
14008 | changes to the machine.
|
---|
14009 |
|
---|
14010 | Any caller wishing to manipulate a virtual machine needs to create a session
|
---|
14011 | object first, which lives in its own process space. Such session objects are
|
---|
14012 | then associated with <link to="IMachine" /> objects living in the VirtualBox
|
---|
14013 | server process to coordinate such changes.
|
---|
14014 |
|
---|
14015 | There are two typical scenarios in which sessions are used:
|
---|
14016 |
|
---|
14017 | <ul>
|
---|
14018 | <li>To alter machine settings or control a running virtual machine, one
|
---|
14019 | needs to lock a machine for a given session (client process) by calling
|
---|
14020 | <link to="IMachine::lockMachine"/>.
|
---|
14021 |
|
---|
14022 | Whereas multiple sessions may control a running virtual machine, only
|
---|
14023 | one process can obtain a write lock on the machine to prevent conflicting
|
---|
14024 | changes. A write lock is also needed if a process wants to actually run a
|
---|
14025 | virtual machine in its own context, such as the VirtualBox GUI or
|
---|
14026 | VBoxHeadless front-ends. They must also lock a machine for their own
|
---|
14027 | sessions before they are allowed to power up the virtual machine.
|
---|
14028 |
|
---|
14029 | As a result, no machine settings can be altered while another process is
|
---|
14030 | already using it, either because that process is modifying machine settings
|
---|
14031 | or because the machine is running.
|
---|
14032 | </li>
|
---|
14033 | <li>
|
---|
14034 | To start a VM using one of the existing VirtualBox front-ends (e.g. the
|
---|
14035 | VirtualBox GUI or VBoxHeadless), one would use
|
---|
14036 | <link to="IMachine::launchVMProcess"/>, which also takes a session object
|
---|
14037 | as its first parameter. This session then identifies the caller and lets the
|
---|
14038 | caller control the started machine (for example, pause machine execution or
|
---|
14039 | power it down) as well as be notified about machine execution state changes.
|
---|
14040 | </li>
|
---|
14041 | </ul>
|
---|
14042 |
|
---|
14043 | How sessions objects are created in a client process depends on whether you use
|
---|
14044 | the Main API via COM or via the webservice:
|
---|
14045 |
|
---|
14046 | <ul>
|
---|
14047 | <li>When using the COM API directly, an object of the Session class from the
|
---|
14048 | VirtualBox type library needs to be created. In regular COM C++ client code,
|
---|
14049 | this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
|
---|
14050 | This object will then act as a local session object in further calls to open
|
---|
14051 | a session.
|
---|
14052 | </li>
|
---|
14053 |
|
---|
14054 | <li>In the webservice, the session manager (IWebsessionManager) instead creates
|
---|
14055 | a session object automatically whenever <link to="IWebsessionManager::logon" />
|
---|
14056 | is called. A managed object reference to that session object can be retrieved by
|
---|
14057 | calling <link to="IWebsessionManager::getSessionObject" />.
|
---|
14058 | </li>
|
---|
14059 | </ul>
|
---|
14060 | </desc>
|
---|
14061 |
|
---|
14062 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
14063 | <desc>Current state of this session.</desc>
|
---|
14064 | </attribute>
|
---|
14065 |
|
---|
14066 | <attribute name="type" type="SessionType" readonly="yes">
|
---|
14067 | <desc>
|
---|
14068 | Type of this session. The value of this attribute is valid only
|
---|
14069 | if the session currently has a machine locked (i.e. its
|
---|
14070 | <link to="#state" /> is Locked), otherwise an error will be returned.
|
---|
14071 | </desc>
|
---|
14072 | </attribute>
|
---|
14073 |
|
---|
14074 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
14075 | <desc>Machine object associated with this session.</desc>
|
---|
14076 | </attribute>
|
---|
14077 |
|
---|
14078 | <attribute name="console" type="IConsole" readonly="yes">
|
---|
14079 | <desc>Console object associated with this session.</desc>
|
---|
14080 | </attribute>
|
---|
14081 |
|
---|
14082 | <method name="unlockMachine">
|
---|
14083 | <desc>
|
---|
14084 | Unlocks a machine that was previously locked for the current session.
|
---|
14085 |
|
---|
14086 | Calling this method is required every time a machine has been locked
|
---|
14087 | for a particular session using the <link to="IMachine::launchVMProcess" />
|
---|
14088 | or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
|
---|
14089 | the machine will be set to <link to="MachineState_Aborted" /> on the
|
---|
14090 | server, and changes made to the machine settings will be lost.
|
---|
14091 |
|
---|
14092 | Generally, it is recommended to unlock all machines explicitly
|
---|
14093 | before terminating the application (regardless of the reason for
|
---|
14094 | the termination).
|
---|
14095 |
|
---|
14096 | <note>
|
---|
14097 | Do not expect the session state (<link to="ISession::state" />
|
---|
14098 | to return to "Unlocked" immediately after you invoke this method,
|
---|
14099 | particularly if you have started a new VM process. The session
|
---|
14100 | state will automatically return to "Unlocked" once the VM is no
|
---|
14101 | longer executing, which can of course take a very long time.
|
---|
14102 | </note>
|
---|
14103 |
|
---|
14104 | <result name="E_UNEXPECTED">
|
---|
14105 | Session is not locked.
|
---|
14106 | </result>
|
---|
14107 |
|
---|
14108 | </desc>
|
---|
14109 | </method>
|
---|
14110 |
|
---|
14111 | </interface>
|
---|
14112 |
|
---|
14113 | <!--
|
---|
14114 | // IStorageController
|
---|
14115 | /////////////////////////////////////////////////////////////////////////
|
---|
14116 | -->
|
---|
14117 |
|
---|
14118 | <enum
|
---|
14119 | name="StorageBus"
|
---|
14120 | uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
|
---|
14121 | >
|
---|
14122 | <desc>
|
---|
14123 | The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
|
---|
14124 | see <link to="IStorageController::bus" />.
|
---|
14125 | </desc>
|
---|
14126 | <const name="Null" value="0">
|
---|
14127 | <desc>@c null value. Never used by the API.</desc>
|
---|
14128 | </const>
|
---|
14129 | <const name="IDE" value="1"/>
|
---|
14130 | <const name="SATA" value="2"/>
|
---|
14131 | <const name="SCSI" value="3"/>
|
---|
14132 | <const name="Floppy" value="4"/>
|
---|
14133 | <const name="SAS" value="5"/>
|
---|
14134 | </enum>
|
---|
14135 |
|
---|
14136 | <enum
|
---|
14137 | name="StorageControllerType"
|
---|
14138 | uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
|
---|
14139 | >
|
---|
14140 | <desc>
|
---|
14141 | The exact variant of storage controller hardware presented
|
---|
14142 | to the guest; see <link to="IStorageController::controllerType" />.
|
---|
14143 | </desc>
|
---|
14144 |
|
---|
14145 | <const name="Null" value="0">
|
---|
14146 | <desc>@c null value. Never used by the API.</desc>
|
---|
14147 | </const>
|
---|
14148 | <const name="LsiLogic" value="1">
|
---|
14149 | <desc>A SCSI controller of the LsiLogic variant.</desc>
|
---|
14150 | </const>
|
---|
14151 | <const name="BusLogic" value="2">
|
---|
14152 | <desc>A SCSI controller of the BusLogic variant.</desc>
|
---|
14153 | </const>
|
---|
14154 | <const name="IntelAhci" value="3">
|
---|
14155 | <desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
|
---|
14156 | </const>
|
---|
14157 | <const name="PIIX3" value="4">
|
---|
14158 | <desc>An IDE controller of the PIIX3 variant.</desc>
|
---|
14159 | </const>
|
---|
14160 | <const name="PIIX4" value="5">
|
---|
14161 | <desc>An IDE controller of the PIIX4 variant.</desc>
|
---|
14162 | </const>
|
---|
14163 | <const name="ICH6" value="6">
|
---|
14164 | <desc>An IDE controller of the ICH6 variant.</desc>
|
---|
14165 | </const>
|
---|
14166 | <const name="I82078" value="7">
|
---|
14167 | <desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
|
---|
14168 | </const>
|
---|
14169 | <const name="LsiLogicSas" value="8">
|
---|
14170 | <desc>A variant of the LsiLogic controller using SAS.</desc>
|
---|
14171 | </const>
|
---|
14172 | </enum>
|
---|
14173 |
|
---|
14174 | <enum
|
---|
14175 | name="ChipsetType"
|
---|
14176 | uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
|
---|
14177 | >
|
---|
14178 | <desc>
|
---|
14179 | Type of emulated chipset (mostly southbridge).
|
---|
14180 | </desc>
|
---|
14181 |
|
---|
14182 | <const name="Null" value="0">
|
---|
14183 | <desc>@c null value. Never used by the API.</desc>
|
---|
14184 | </const>
|
---|
14185 | <const name="PIIX3" value="1">
|
---|
14186 | <desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
|
---|
14187 | </const>
|
---|
14188 | <const name="ICH9" value="2">
|
---|
14189 | <desc>A ICH9 (I/O Controller Hub) chipset.</desc>
|
---|
14190 | </const>
|
---|
14191 | </enum>
|
---|
14192 |
|
---|
14193 | <interface
|
---|
14194 | name="IStorageController" extends="$unknown"
|
---|
14195 | uuid="a1556333-09b6-46d9-bfb7-fc239b7fbe1e"
|
---|
14196 | wsmap="managed"
|
---|
14197 | >
|
---|
14198 | <desc>
|
---|
14199 | Represents a storage controller that is attached to a virtual machine
|
---|
14200 | (<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
|
---|
14201 | attached to storage controllers in a real computer, virtual drives
|
---|
14202 | (represented by <link to="IMediumAttachment" />) are attached to virtual
|
---|
14203 | storage controllers, represented by this interface.
|
---|
14204 |
|
---|
14205 | As opposed to physical hardware, VirtualBox has a very generic concept
|
---|
14206 | of a storage controller, and for purposes of the Main API, all virtual
|
---|
14207 | storage is attached to virtual machines via instances of this interface.
|
---|
14208 | There are five types of such virtual storage controllers: IDE, SCSI, SATA,
|
---|
14209 | SAS and Floppy (see <link to="#bus" />). Depending on which of these four
|
---|
14210 | is used, certain sub-types may be available and can be selected in
|
---|
14211 | <link to="#controllerType" />.
|
---|
14212 |
|
---|
14213 | Depending on these settings, the guest operating system might see
|
---|
14214 | significantly different virtual hardware.
|
---|
14215 | </desc>
|
---|
14216 |
|
---|
14217 | <attribute name="name" type="wstring" readonly="yes">
|
---|
14218 | <desc>
|
---|
14219 | Name of the storage controller, as originally specified with
|
---|
14220 | <link to="IMachine::addStorageController" />. This then uniquely
|
---|
14221 | identifies this controller with other method calls such as
|
---|
14222 | <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
|
---|
14223 | </desc>
|
---|
14224 | </attribute>
|
---|
14225 |
|
---|
14226 | <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
|
---|
14227 | <desc>
|
---|
14228 | Maximum number of devices which can be attached to one port.
|
---|
14229 | </desc>
|
---|
14230 | </attribute>
|
---|
14231 |
|
---|
14232 | <attribute name="minPortCount" type="unsigned long" readonly="yes">
|
---|
14233 | <desc>
|
---|
14234 | Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
14235 | </desc>
|
---|
14236 | </attribute>
|
---|
14237 |
|
---|
14238 | <attribute name="maxPortCount" type="unsigned long" readonly="yes">
|
---|
14239 | <desc>
|
---|
14240 | Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
14241 | </desc>
|
---|
14242 | </attribute>
|
---|
14243 |
|
---|
14244 | <attribute name="instance" type="unsigned long">
|
---|
14245 | <desc>
|
---|
14246 | The instance number of the device in the running VM.
|
---|
14247 | </desc>
|
---|
14248 | </attribute>
|
---|
14249 |
|
---|
14250 | <attribute name="portCount" type="unsigned long">
|
---|
14251 | <desc>
|
---|
14252 | The number of currently usable ports on the controller.
|
---|
14253 | The minimum and maximum number of ports for one controller are
|
---|
14254 | stored in <link to="IStorageController::minPortCount"/>
|
---|
14255 | and <link to="IStorageController::maxPortCount"/>.
|
---|
14256 | </desc>
|
---|
14257 | </attribute>
|
---|
14258 |
|
---|
14259 | <attribute name="bus" type="StorageBus" readonly="yes">
|
---|
14260 | <desc>
|
---|
14261 | The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
|
---|
14262 | </desc>
|
---|
14263 | </attribute>
|
---|
14264 |
|
---|
14265 | <attribute name="controllerType" type="StorageControllerType">
|
---|
14266 | <desc>
|
---|
14267 | The exact variant of storage controller hardware presented
|
---|
14268 | to the guest.
|
---|
14269 | Depending on this value, VirtualBox will provide a different
|
---|
14270 | virtual storage controller hardware to the guest.
|
---|
14271 | For SATA, SAS and floppy controllers, only one variant is
|
---|
14272 | available, but for IDE and SCSI, there are several.
|
---|
14273 |
|
---|
14274 | For SCSI controllers, the default type is LsiLogic.
|
---|
14275 | </desc>
|
---|
14276 | </attribute>
|
---|
14277 |
|
---|
14278 | <attribute name="useHostIOCache" type="boolean">
|
---|
14279 | <desc>
|
---|
14280 | If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
|
---|
14281 | caches and use synchronous file APIs on the host. This was the only option in the API before
|
---|
14282 | VirtualBox 3.2 and is still the default for IDE controllers.
|
---|
14283 |
|
---|
14284 | If false, the host I/O cache will be disabled for image files attached to this storage controller.
|
---|
14285 | Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
|
---|
14286 | it possible to turn off the host I/O caches because the emulation can handle unaligned access to
|
---|
14287 | the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
|
---|
14288 | virtual machines are running at the same time to prevent I/O cache related hangs.
|
---|
14289 | This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
|
---|
14290 | </desc>
|
---|
14291 | </attribute>
|
---|
14292 |
|
---|
14293 | <attribute name="bootable" type="boolean" readonly="yes">
|
---|
14294 | <desc>
|
---|
14295 | Returns whether it is possible to boot from disks attached to this controller.
|
---|
14296 | </desc>
|
---|
14297 | </attribute>
|
---|
14298 |
|
---|
14299 | <method name="getIDEEmulationPort">
|
---|
14300 | <desc>
|
---|
14301 | Gets the corresponding port number which is emulated as an IDE device.
|
---|
14302 | Works only with SATA controllers.
|
---|
14303 |
|
---|
14304 | <result name="E_INVALIDARG">
|
---|
14305 | The @a devicePosition is not in the range 0 to 3.
|
---|
14306 | </result>
|
---|
14307 | <result name="E_NOTIMPL">
|
---|
14308 | The storage controller type is not SATAIntelAhci.
|
---|
14309 | </result>
|
---|
14310 |
|
---|
14311 | </desc>
|
---|
14312 | <param name="devicePosition" type="long" dir="in"/>
|
---|
14313 | <param name="portNumber" type="long" dir="return"/>
|
---|
14314 | </method>
|
---|
14315 |
|
---|
14316 | <method name="setIDEEmulationPort">
|
---|
14317 | <desc>
|
---|
14318 | Sets the port number which is emulated as an IDE device.
|
---|
14319 | Works only with SATA controllers.
|
---|
14320 |
|
---|
14321 | <result name="E_INVALIDARG">
|
---|
14322 | The @a devicePosition is not in the range 0 to 3 or the
|
---|
14323 | @a portNumber is not in the range 0 to 29.
|
---|
14324 | </result>
|
---|
14325 | <result name="E_NOTIMPL">
|
---|
14326 | The storage controller type is not SATAIntelAhci.
|
---|
14327 | </result>
|
---|
14328 |
|
---|
14329 | </desc>
|
---|
14330 | <param name="devicePosition" type="long" dir="in"/>
|
---|
14331 | <param name="portNumber" type="long" dir="in"/>
|
---|
14332 | </method>
|
---|
14333 |
|
---|
14334 | </interface>
|
---|
14335 |
|
---|
14336 | <if target="wsdl">
|
---|
14337 |
|
---|
14338 | <!--
|
---|
14339 | // IManagedObjectRef
|
---|
14340 | /////////////////////////////////////////////////////////////////////////
|
---|
14341 | -->
|
---|
14342 |
|
---|
14343 | <interface
|
---|
14344 | name="IManagedObjectRef" extends="$unknown"
|
---|
14345 | uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
|
---|
14346 | internal="yes"
|
---|
14347 | wsmap="managed"
|
---|
14348 | wscpp="hardcoded"
|
---|
14349 | >
|
---|
14350 | <desc>
|
---|
14351 | Managed object reference.
|
---|
14352 |
|
---|
14353 | Only within the webservice, a managed object reference (which is really
|
---|
14354 | an opaque number) allows a webservice client to address an object
|
---|
14355 | that lives in the address space of the webservice server.
|
---|
14356 |
|
---|
14357 | Behind each managed object reference, there is a COM object that lives
|
---|
14358 | in the webservice server's address space. The COM object is not freed
|
---|
14359 | until the managed object reference is released, either by an explicit
|
---|
14360 | call to <link to="IManagedObjectRef::release" /> or by logging off from
|
---|
14361 | the webservice (<link to="IWebsessionManager::logoff" />), which releases
|
---|
14362 | all objects created during the webservice session.
|
---|
14363 |
|
---|
14364 | Whenever a method call of the VirtualBox API returns a COM object, the
|
---|
14365 | webservice representation of that method will instead return a
|
---|
14366 | managed object reference, which can then be used to invoke methods
|
---|
14367 | on that object.
|
---|
14368 | </desc>
|
---|
14369 |
|
---|
14370 | <method name="getInterfaceName">
|
---|
14371 | <desc>
|
---|
14372 | Returns the name of the interface that this managed object represents,
|
---|
14373 | for example, "IMachine", as a string.
|
---|
14374 | </desc>
|
---|
14375 | <param name="return" type="wstring" dir="return"/>
|
---|
14376 | </method>
|
---|
14377 |
|
---|
14378 | <method name="release">
|
---|
14379 | <desc>
|
---|
14380 | Releases this managed object reference and frees the resources that
|
---|
14381 | were allocated for it in the webservice server process. After calling
|
---|
14382 | this method, the identifier of the reference can no longer be used.
|
---|
14383 | </desc>
|
---|
14384 | </method>
|
---|
14385 |
|
---|
14386 | </interface>
|
---|
14387 |
|
---|
14388 | <!--
|
---|
14389 | // IWebsessionManager
|
---|
14390 | /////////////////////////////////////////////////////////////////////////
|
---|
14391 | -->
|
---|
14392 |
|
---|
14393 | <interface
|
---|
14394 | name="IWebsessionManager" extends="$unknown"
|
---|
14395 | uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
|
---|
14396 | internal="yes"
|
---|
14397 | wsmap="global"
|
---|
14398 | wscpp="hardcoded"
|
---|
14399 | >
|
---|
14400 | <desc>
|
---|
14401 | Websession manager. This provides essential services
|
---|
14402 | to webservice clients.
|
---|
14403 | </desc>
|
---|
14404 | <method name="logon">
|
---|
14405 | <desc>
|
---|
14406 | Logs a new client onto the webservice and returns a managed object reference to
|
---|
14407 | the IVirtualBox instance, which the client can then use as a basis to further
|
---|
14408 | queries, since all calls to the VirtualBox API are based on the IVirtualBox
|
---|
14409 | interface, in one way or the other.
|
---|
14410 | </desc>
|
---|
14411 | <param name="username" type="wstring" dir="in"/>
|
---|
14412 | <param name="password" type="wstring" dir="in"/>
|
---|
14413 | <param name="return" type="IVirtualBox" dir="return"/>
|
---|
14414 | </method>
|
---|
14415 |
|
---|
14416 | <method name="getSessionObject">
|
---|
14417 | <desc>
|
---|
14418 | Returns a managed object reference to the internal ISession object that was created
|
---|
14419 | for this web service session when the client logged on.
|
---|
14420 |
|
---|
14421 | <see>ISession</see>
|
---|
14422 | </desc>
|
---|
14423 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
14424 | <param name="return" type="ISession" dir="return"/>
|
---|
14425 | </method>
|
---|
14426 |
|
---|
14427 | <method name="logoff">
|
---|
14428 | <desc>
|
---|
14429 | Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
|
---|
14430 | and destroys all resources associated with the session (most importantly, all
|
---|
14431 | managed objects created in the server while the session was active).
|
---|
14432 | </desc>
|
---|
14433 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
14434 | </method>
|
---|
14435 |
|
---|
14436 | </interface>
|
---|
14437 |
|
---|
14438 | </if>
|
---|
14439 |
|
---|
14440 | <!--
|
---|
14441 | // IPerformanceCollector & friends
|
---|
14442 | /////////////////////////////////////////////////////////////////////////
|
---|
14443 | -->
|
---|
14444 |
|
---|
14445 | <interface
|
---|
14446 | name="IPerformanceMetric" extends="$unknown"
|
---|
14447 | uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
|
---|
14448 | >
|
---|
14449 | <desc>
|
---|
14450 | The IPerformanceMetric interface represents parameters of the given
|
---|
14451 | performance metric.
|
---|
14452 | </desc>
|
---|
14453 |
|
---|
14454 | <attribute name="metricName" type="wstring" readonly="yes">
|
---|
14455 | <desc>
|
---|
14456 | Name of the metric.
|
---|
14457 | </desc>
|
---|
14458 | </attribute>
|
---|
14459 |
|
---|
14460 | <attribute name="object" type="$unknown" readonly="yes">
|
---|
14461 | <desc>
|
---|
14462 | Object this metric belongs to.
|
---|
14463 | </desc>
|
---|
14464 | </attribute>
|
---|
14465 |
|
---|
14466 | <attribute name="description" type="wstring" readonly="yes">
|
---|
14467 | <desc>
|
---|
14468 | Textual description of the metric.
|
---|
14469 | </desc>
|
---|
14470 | </attribute>
|
---|
14471 |
|
---|
14472 | <attribute name="period" type="unsigned long" readonly="yes">
|
---|
14473 | <desc>
|
---|
14474 | Time interval between samples, measured in seconds.
|
---|
14475 | </desc>
|
---|
14476 | </attribute>
|
---|
14477 |
|
---|
14478 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
14479 | <desc>
|
---|
14480 | Number of recent samples retained by the performance collector for this
|
---|
14481 | metric.
|
---|
14482 |
|
---|
14483 | When the collected sample count exceeds this number, older samples
|
---|
14484 | are discarded.
|
---|
14485 | </desc>
|
---|
14486 | </attribute>
|
---|
14487 |
|
---|
14488 | <attribute name="unit" type="wstring" readonly="yes">
|
---|
14489 | <desc>
|
---|
14490 | Unit of measurement.
|
---|
14491 | </desc>
|
---|
14492 | </attribute>
|
---|
14493 |
|
---|
14494 | <attribute name="minimumValue" type="long" readonly="yes">
|
---|
14495 | <desc>
|
---|
14496 | Minimum possible value of this metric.
|
---|
14497 | </desc>
|
---|
14498 | </attribute>
|
---|
14499 |
|
---|
14500 | <attribute name="maximumValue" type="long" readonly="yes">
|
---|
14501 | <desc>
|
---|
14502 | Maximum possible value of this metric.
|
---|
14503 | </desc>
|
---|
14504 | </attribute>
|
---|
14505 | </interface>
|
---|
14506 |
|
---|
14507 | <interface
|
---|
14508 | name="IPerformanceCollector" extends="$unknown"
|
---|
14509 | uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
|
---|
14510 | wsmap="managed"
|
---|
14511 | >
|
---|
14512 | <desc>
|
---|
14513 | The IPerformanceCollector interface represents a service that collects
|
---|
14514 | and stores performance metrics data.
|
---|
14515 |
|
---|
14516 | Performance metrics are associated with objects of interfaces like IHost
|
---|
14517 | and IMachine. Each object has a distinct set of performance metrics. The
|
---|
14518 | set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
|
---|
14519 |
|
---|
14520 | Metric data is collected at the specified intervals and is retained
|
---|
14521 | internally. The interval and the number of retained samples can be set
|
---|
14522 | with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
|
---|
14523 | and collection settings are not persistent, they are discarded as soon as
|
---|
14524 | VBoxSVC process terminates. Moreover, metric settings and data associated
|
---|
14525 | with a particular VM only exist while VM is running. They disappear as
|
---|
14526 | soon as VM shuts down. It is not possible to set up metrics for machines
|
---|
14527 | that are powered off. One needs to start VM first, then set up metric
|
---|
14528 | collection parameters.
|
---|
14529 |
|
---|
14530 | Metrics are organized hierarchically, with each level separated by a
|
---|
14531 | slash (/) character. Generally, the scheme for metric names is like this:
|
---|
14532 |
|
---|
14533 | <tt>Category/Metric[/SubMetric][:aggregation]</tt>
|
---|
14534 |
|
---|
14535 | "Category/Metric" together form the base metric name. A base metric is
|
---|
14536 | the smallest unit for which a sampling interval and the number of
|
---|
14537 | retained samples can be set. Only base metrics can be enabled and
|
---|
14538 | disabled. All sub-metrics are collected when their base metric is
|
---|
14539 | collected. Collected values for any set of sub-metrics can be queried
|
---|
14540 | with <link to="IPerformanceCollector::queryMetricsData" />.
|
---|
14541 |
|
---|
14542 | For example "CPU/Load/User:avg" metric name stands for the "CPU"
|
---|
14543 | category, "Load" metric, "User" submetric, "average" aggregate. An
|
---|
14544 | aggregate function is computed over all retained data. Valid aggregate
|
---|
14545 | functions are:
|
---|
14546 |
|
---|
14547 | <ul>
|
---|
14548 | <li>avg -- average</li>
|
---|
14549 | <li>min -- minimum</li>
|
---|
14550 | <li>max -- maximum</li>
|
---|
14551 | </ul>
|
---|
14552 |
|
---|
14553 | When setting up metric parameters, querying metric data, enabling or
|
---|
14554 | disabling metrics wildcards can be used in metric names to specify a
|
---|
14555 | subset of metrics. For example, to select all CPU-related metrics
|
---|
14556 | use <tt>CPU/*</tt>, all averages can be queried using <tt>*:avg</tt> and
|
---|
14557 | so on. To query metric values without aggregates <tt>*:</tt> can be used.
|
---|
14558 |
|
---|
14559 | The valid names for base metrics are:
|
---|
14560 |
|
---|
14561 | <ul>
|
---|
14562 | <li>CPU/Load</li>
|
---|
14563 | <li>CPU/MHz</li>
|
---|
14564 | <li>RAM/Usage</li>
|
---|
14565 | <li>RAM/VMM</li>
|
---|
14566 | </ul>
|
---|
14567 |
|
---|
14568 | The general sequence for collecting and retrieving the metrics is:
|
---|
14569 | <ul>
|
---|
14570 | <li>
|
---|
14571 | Obtain an instance of IPerformanceCollector with
|
---|
14572 | <link to="IVirtualBox::performanceCollector" />
|
---|
14573 | </li>
|
---|
14574 | <li>
|
---|
14575 | Allocate and populate an array with references to objects the metrics
|
---|
14576 | will be collected for. Use references to IHost and IMachine objects.
|
---|
14577 | </li>
|
---|
14578 | <li>
|
---|
14579 | Allocate and populate an array with base metric names the data will
|
---|
14580 | be collected for.
|
---|
14581 | </li>
|
---|
14582 | <li>
|
---|
14583 | Call <link to="IPerformanceCollector::setupMetrics" />. From now on
|
---|
14584 | the metric data will be collected and stored.
|
---|
14585 | </li>
|
---|
14586 | <li>
|
---|
14587 | Wait for the data to get collected.
|
---|
14588 | </li>
|
---|
14589 | <li>
|
---|
14590 | Allocate and populate an array with references to objects the metric
|
---|
14591 | values will be queried for. You can re-use the object array used for
|
---|
14592 | setting base metrics.
|
---|
14593 | </li>
|
---|
14594 | <li>
|
---|
14595 | Allocate and populate an array with metric names the data will be
|
---|
14596 | collected for. Note that metric names differ from base metric names.
|
---|
14597 | </li>
|
---|
14598 | <li>
|
---|
14599 | Call <link to="IPerformanceCollector::queryMetricsData" />. The data
|
---|
14600 | that have been collected so far are returned. Note that the values
|
---|
14601 | are still retained internally and data collection continues.
|
---|
14602 | </li>
|
---|
14603 | </ul>
|
---|
14604 |
|
---|
14605 | For an example of usage refer to the following files in VirtualBox SDK:
|
---|
14606 | <ul>
|
---|
14607 | <li>
|
---|
14608 | Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
|
---|
14609 | </li>
|
---|
14610 | <li>
|
---|
14611 | Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
|
---|
14612 | </li>
|
---|
14613 | </ul>
|
---|
14614 | </desc>
|
---|
14615 |
|
---|
14616 | <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
|
---|
14617 | <desc>
|
---|
14618 | Array of unique names of metrics.
|
---|
14619 |
|
---|
14620 | This array represents all metrics supported by the performance
|
---|
14621 | collector. Individual objects do not necessarily support all of them.
|
---|
14622 | <link to="IPerformanceCollector::getMetrics"/> can be used to get the
|
---|
14623 | list of supported metrics for a particular object.
|
---|
14624 | </desc>
|
---|
14625 | </attribute>
|
---|
14626 |
|
---|
14627 | <method name="getMetrics">
|
---|
14628 | <desc>
|
---|
14629 | Returns parameters of specified metrics for a set of objects.
|
---|
14630 | <note>
|
---|
14631 | @c Null metrics array means all metrics. @c Null object array means
|
---|
14632 | all existing objects.
|
---|
14633 | </note>
|
---|
14634 | </desc>
|
---|
14635 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
14636 | <desc>
|
---|
14637 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
14638 | is supported.
|
---|
14639 | </desc>
|
---|
14640 | </param>
|
---|
14641 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
14642 | <desc>
|
---|
14643 | Set of objects to return metric parameters for.
|
---|
14644 | </desc>
|
---|
14645 | </param>
|
---|
14646 | <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
14647 | <desc>
|
---|
14648 | Array of returned metric parameters.
|
---|
14649 | </desc>
|
---|
14650 | </param>
|
---|
14651 | </method>
|
---|
14652 |
|
---|
14653 | <method name="setupMetrics">
|
---|
14654 | <desc>
|
---|
14655 | Sets parameters of specified base metrics for a set of objects. Returns
|
---|
14656 | an array of <link to="IPerformanceMetric" /> describing the metrics
|
---|
14657 | have been affected.
|
---|
14658 | <note>
|
---|
14659 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
14660 | empty object array means all existing objects. If metric name array
|
---|
14661 | contains a single element and object array contains many, the single
|
---|
14662 | metric name array element is applied to each object array element to
|
---|
14663 | form metric/object pairs.
|
---|
14664 | </note>
|
---|
14665 | </desc>
|
---|
14666 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
14667 | <desc>
|
---|
14668 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
14669 | support.
|
---|
14670 | </desc>
|
---|
14671 | </param>
|
---|
14672 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
14673 | <desc>
|
---|
14674 | Set of objects to setup metric parameters for.
|
---|
14675 | </desc>
|
---|
14676 | </param>
|
---|
14677 | <param name="period" type="unsigned long" dir="in">
|
---|
14678 | <desc>
|
---|
14679 | Time interval in seconds between two consecutive samples of
|
---|
14680 | performance data.
|
---|
14681 | </desc>
|
---|
14682 | </param>
|
---|
14683 | <param name="count" type="unsigned long" dir="in">
|
---|
14684 | <desc>
|
---|
14685 | Number of samples to retain in performance data history. Older
|
---|
14686 | samples get discarded.
|
---|
14687 | </desc>
|
---|
14688 | </param>
|
---|
14689 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
14690 | <desc>
|
---|
14691 | Array of metrics that have been modified by the call to this method.
|
---|
14692 | </desc>
|
---|
14693 | </param>
|
---|
14694 | </method>
|
---|
14695 |
|
---|
14696 | <method name="enableMetrics">
|
---|
14697 | <desc>
|
---|
14698 | Turns on collecting specified base metrics. Returns an array of
|
---|
14699 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
14700 | affected.
|
---|
14701 | <note>
|
---|
14702 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
14703 | empty object array means all existing objects. If metric name array
|
---|
14704 | contains a single element and object array contains many, the single
|
---|
14705 | metric name array element is applied to each object array element to
|
---|
14706 | form metric/object pairs.
|
---|
14707 | </note>
|
---|
14708 | </desc>
|
---|
14709 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
14710 | <desc>
|
---|
14711 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
14712 | support.
|
---|
14713 | </desc>
|
---|
14714 | </param>
|
---|
14715 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
14716 | <desc>
|
---|
14717 | Set of objects to enable metrics for.
|
---|
14718 | </desc>
|
---|
14719 | </param>
|
---|
14720 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
14721 | <desc>
|
---|
14722 | Array of metrics that have been modified by the call to this method.
|
---|
14723 | </desc>
|
---|
14724 | </param>
|
---|
14725 | </method>
|
---|
14726 |
|
---|
14727 | <method name="disableMetrics">
|
---|
14728 | <desc>
|
---|
14729 | Turns off collecting specified base metrics. Returns an array of
|
---|
14730 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
14731 | affected.
|
---|
14732 | <note>
|
---|
14733 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
14734 | empty object array means all existing objects. If metric name array
|
---|
14735 | contains a single element and object array contains many, the single
|
---|
14736 | metric name array element is applied to each object array element to
|
---|
14737 | form metric/object pairs.
|
---|
14738 | </note>
|
---|
14739 | </desc>
|
---|
14740 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
14741 | <desc>
|
---|
14742 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
14743 | support.
|
---|
14744 | </desc>
|
---|
14745 | </param>
|
---|
14746 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
14747 | <desc>
|
---|
14748 | Set of objects to disable metrics for.
|
---|
14749 | </desc>
|
---|
14750 | </param>
|
---|
14751 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
14752 | <desc>
|
---|
14753 | Array of metrics that have been modified by the call to this method.
|
---|
14754 | </desc>
|
---|
14755 | </param>
|
---|
14756 | </method>
|
---|
14757 |
|
---|
14758 | <method name="queryMetricsData">
|
---|
14759 | <desc>
|
---|
14760 | Queries collected metrics data for a set of objects.
|
---|
14761 |
|
---|
14762 | The data itself and related metric information are returned in seven
|
---|
14763 | parallel and one flattened array of arrays. Elements of
|
---|
14764 | <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
|
---|
14765 | returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
|
---|
14766 | the same index describe one set of values corresponding to a single
|
---|
14767 | metric.
|
---|
14768 |
|
---|
14769 | The <tt>returnData</tt> parameter is a flattened array of arrays. Each
|
---|
14770 | start and length of a sub-array is indicated by
|
---|
14771 | <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
|
---|
14772 | value for metric <tt>metricNames[i]</tt> is at
|
---|
14773 | <tt>returnData[returnIndices[i]]</tt>.
|
---|
14774 |
|
---|
14775 | <note>
|
---|
14776 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
14777 | empty object array means all existing objects. If metric name array
|
---|
14778 | contains a single element and object array contains many, the single
|
---|
14779 | metric name array element is applied to each object array element to
|
---|
14780 | form metric/object pairs.
|
---|
14781 | </note>
|
---|
14782 | <note>
|
---|
14783 | Data collection continues behind the scenes after call to @c
|
---|
14784 | queryMetricsData. The return data can be seen as the snapshot of the
|
---|
14785 | current state at the time of @c queryMetricsData call. The internally
|
---|
14786 | kept metric values are not cleared by the call. This makes possible
|
---|
14787 | querying different subsets of metrics or aggregates with subsequent
|
---|
14788 | calls. If periodic querying is needed it is highly suggested to query
|
---|
14789 | the values with @c interval*count period to avoid confusion. This way
|
---|
14790 | a completely new set of data values will be provided by each query.
|
---|
14791 | </note>
|
---|
14792 | </desc>
|
---|
14793 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
14794 | <desc>
|
---|
14795 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
14796 | support.
|
---|
14797 | </desc>
|
---|
14798 | </param>
|
---|
14799 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
14800 | <desc>
|
---|
14801 | Set of objects to query metrics for.
|
---|
14802 | </desc>
|
---|
14803 | </param>
|
---|
14804 | <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
|
---|
14805 | <desc>
|
---|
14806 | Names of metrics returned in @c returnData.
|
---|
14807 | </desc>
|
---|
14808 | </param>
|
---|
14809 | <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
|
---|
14810 | <desc>
|
---|
14811 | Objects associated with metrics returned in @c returnData.
|
---|
14812 | </desc>
|
---|
14813 | </param>
|
---|
14814 | <param name="returnUnits" type="wstring" dir="out" safearray="yes">
|
---|
14815 | <desc>
|
---|
14816 | Units of measurement for each returned metric.
|
---|
14817 | </desc>
|
---|
14818 | </param>
|
---|
14819 | <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
|
---|
14820 | <desc>
|
---|
14821 | Divisor that should be applied to return values in order to get
|
---|
14822 | floating point values. For example:
|
---|
14823 | <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
|
---|
14824 | will retrieve the floating point value of i-th sample of the first
|
---|
14825 | metric.
|
---|
14826 | </desc>
|
---|
14827 | </param>
|
---|
14828 | <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
|
---|
14829 | <desc>
|
---|
14830 | Sequence numbers of the first elements of value sequences of
|
---|
14831 | particular metrics returned in @c returnData. For aggregate metrics
|
---|
14832 | it is the sequence number of the sample the aggregate started
|
---|
14833 | calculation from.
|
---|
14834 | </desc>
|
---|
14835 | </param>
|
---|
14836 | <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
|
---|
14837 | <desc>
|
---|
14838 | Indices of the first elements of value sequences of particular
|
---|
14839 | metrics returned in @c returnData.
|
---|
14840 | </desc>
|
---|
14841 | </param>
|
---|
14842 | <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
|
---|
14843 | <desc>
|
---|
14844 | Lengths of value sequences of particular metrics.
|
---|
14845 | </desc>
|
---|
14846 | </param>
|
---|
14847 | <param name="returnData" type="long" dir="return" safearray="yes">
|
---|
14848 | <desc>
|
---|
14849 | Flattened array of all metric data containing sequences of values for
|
---|
14850 | each metric.
|
---|
14851 | </desc>
|
---|
14852 | </param>
|
---|
14853 | </method>
|
---|
14854 |
|
---|
14855 | </interface>
|
---|
14856 |
|
---|
14857 | <enum
|
---|
14858 | name="NATAliasMode"
|
---|
14859 | uuid="67772168-50d9-11df-9669-7fb714ee4fa1"
|
---|
14860 | >
|
---|
14861 | <desc></desc>
|
---|
14862 | <const name="AliasLog" value="0x1">
|
---|
14863 | <desc></desc>
|
---|
14864 | </const>
|
---|
14865 | <const name="AliasProxyOnly" value="0x02">
|
---|
14866 | <desc></desc>
|
---|
14867 | </const>
|
---|
14868 | <const name="AliasUseSamePorts" value="0x04">
|
---|
14869 | <desc></desc>
|
---|
14870 | </const>
|
---|
14871 | </enum>
|
---|
14872 |
|
---|
14873 | <enum
|
---|
14874 | name="NATProtocol"
|
---|
14875 | uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
|
---|
14876 | >
|
---|
14877 | <desc>Protocol definitions used with NAT port-forwarding rules.</desc>
|
---|
14878 | <const name="UDP" value="0">
|
---|
14879 | <desc>Port-forwarding uses UDP protocol.</desc>
|
---|
14880 | </const>
|
---|
14881 | <const name="TCP" value="1">
|
---|
14882 | <desc>Port-forwarding uses TCP protocol.</desc>
|
---|
14883 | </const>
|
---|
14884 | </enum>
|
---|
14885 |
|
---|
14886 | <interface
|
---|
14887 | name="INATEngine" extends="$unknown"
|
---|
14888 | uuid="4b286616-eb03-11de-b0fb-1701eca42246"
|
---|
14889 | wsmap="managed"
|
---|
14890 | >
|
---|
14891 | <desc>Interface for managing a NAT engine which is used with a virtual machine. This
|
---|
14892 | allows for changing NAT behavior such as port-forwarding rules. This interface is
|
---|
14893 | used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
|
---|
14894 | <attribute name="network" type="wstring">
|
---|
14895 | <desc>The network attribute of the NAT engine (the same value is used with built-in
|
---|
14896 | DHCP server to fill corresponding fields of DHCP leases).</desc>
|
---|
14897 | </attribute>
|
---|
14898 | <attribute name="hostIP" type="wstring">
|
---|
14899 | <desc>IP of host interface to bind all opened sockets to.
|
---|
14900 | <note>Changing this does not change binding of port forwarding.</note>
|
---|
14901 | </desc>
|
---|
14902 | </attribute>
|
---|
14903 | <attribute name="tftpPrefix" type="wstring">
|
---|
14904 | <desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
|
---|
14905 | the corresponding fields of DHCP leases.</desc>
|
---|
14906 | </attribute>
|
---|
14907 | <attribute name="tftpBootFile" type="wstring">
|
---|
14908 | <desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
|
---|
14909 | the corresponding fields of DHCP leases.</desc>
|
---|
14910 | </attribute>
|
---|
14911 | <attribute name="tftpNextServer" type="wstring">
|
---|
14912 | <desc>TFTP server attribute which is used with the built-in DHCP server to fill
|
---|
14913 | the corresponding fields of DHCP leases.
|
---|
14914 | <note>The preferred form is IPv4 addresses.</note>
|
---|
14915 | </desc>
|
---|
14916 | </attribute>
|
---|
14917 | <attribute name="aliasMode" type="unsigned long">
|
---|
14918 | <desc></desc>
|
---|
14919 | </attribute>
|
---|
14920 | <attribute name="dnsPassDomain" type="boolean">
|
---|
14921 | <desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
|
---|
14922 | </attribute>
|
---|
14923 | <attribute name="dnsProxy" type="boolean">
|
---|
14924 | <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
|
---|
14925 | of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
|
---|
14926 | </attribute>
|
---|
14927 | <attribute name="dnsUseHostResolver" type="boolean">
|
---|
14928 | <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
|
---|
14929 | of the DNS proxy and process traffic using the host resolver mechanism.</desc>
|
---|
14930 | </attribute>
|
---|
14931 | <attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
|
---|
14932 | <desc>Array of NAT port-forwarding rules in string representation, in the following
|
---|
14933 | format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
|
---|
14934 | </attribute>
|
---|
14935 | <method name="setNetworkSettings">
|
---|
14936 | <desc>Sets network configuration of the NAT engine.</desc>
|
---|
14937 | <param name="mtu" type="unsigned long" dir="in">
|
---|
14938 | <desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
|
---|
14939 | </param>
|
---|
14940 | <param name="sockSnd" type="unsigned long" dir="in">
|
---|
14941 | <desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
|
---|
14942 | </param>
|
---|
14943 | <param name="sockRcv" type="unsigned long" dir="in">
|
---|
14944 | <desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
|
---|
14945 | </param>
|
---|
14946 | <param name="TcpWndSnd" type="unsigned long" dir="in">
|
---|
14947 | <desc>Initial size of the NAT engine's sending TCP window in bytes when
|
---|
14948 | establishing a new TCP connection.</desc>
|
---|
14949 | </param>
|
---|
14950 | <param name="TcpWndRcv" type="unsigned long" dir="in">
|
---|
14951 | <desc>Initial size of the NAT engine's receiving TCP window in bytes when
|
---|
14952 | establishing a new TCP connection.</desc>
|
---|
14953 | </param>
|
---|
14954 | </method>
|
---|
14955 | <method name="getNetworkSettings">
|
---|
14956 | <desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
|
---|
14957 | for parameter descriptions.</desc>
|
---|
14958 | <param name="mtu" type="unsigned long" dir="out" />
|
---|
14959 | <param name="sockSnd" type="unsigned long" dir="out" />
|
---|
14960 | <param name="sockRcv" type="unsigned long" dir="out" />
|
---|
14961 | <param name="TcpWndSnd" type="unsigned long" dir="out" />
|
---|
14962 | <param name="TcpWndRcv" type="unsigned long" dir="out" />
|
---|
14963 | </method>
|
---|
14964 | <method name="addRedirect">
|
---|
14965 | <desc>Adds a new NAT port-forwarding rule.</desc>
|
---|
14966 | <param name="name" type="wstring" dir="in">
|
---|
14967 | <desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
|
---|
14968 | auto-generates one using the other parameters.</desc>
|
---|
14969 | </param>
|
---|
14970 | <param name="proto" type="NATProtocol" dir="in">
|
---|
14971 | <desc>Protocol handled with the rule.</desc>
|
---|
14972 | </param>
|
---|
14973 | <param name="hostIp" type="wstring" dir="in">
|
---|
14974 | <desc>IP of the host interface to which the rule should apply. An empty ip address is
|
---|
14975 | acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
|
---|
14976 | </param>
|
---|
14977 | <param name="hostPort" type="unsigned short" dir="in">
|
---|
14978 | <desc>The port number to listen on.</desc>
|
---|
14979 | </param>
|
---|
14980 | <param name="guestIp" type="wstring" dir="in">
|
---|
14981 | <desc>The IP address of the guest which the NAT engine will forward matching packets
|
---|
14982 | to. An empty IP address is acceptable, in which case the NAT engine will forward
|
---|
14983 | packets to the first DHCP lease (x.x.x.15).</desc>
|
---|
14984 | </param>
|
---|
14985 | <param name="guestPort" type="unsigned short" dir="in">
|
---|
14986 | <desc>The port number to forward.</desc>
|
---|
14987 | </param>
|
---|
14988 | </method>
|
---|
14989 | <method name="removeRedirect">
|
---|
14990 | <desc>Removes a port-forwarding rule that was previously registered.</desc>
|
---|
14991 | <param name="name" type="wstring" dir="in">
|
---|
14992 | <desc>The name of the rule to delete.</desc>
|
---|
14993 | </param>
|
---|
14994 | </method>
|
---|
14995 | </interface>
|
---|
14996 |
|
---|
14997 | <!--
|
---|
14998 | // IExtPackManager
|
---|
14999 | /////////////////////////////////////////////////////////////////////////
|
---|
15000 | -->
|
---|
15001 |
|
---|
15002 | <interface
|
---|
15003 | name="IExtPackPlugIn" extends="$unknown"
|
---|
15004 | uuid="58000040-e718-4746-bbce-4b86d96da461"
|
---|
15005 | wsmap="suppress"
|
---|
15006 | >
|
---|
15007 | <desc>
|
---|
15008 | Interface for keeping information about a plug-in that ships with an
|
---|
15009 | extension pack.
|
---|
15010 | </desc>
|
---|
15011 | <attribute name="name" type="wstring" readonly="yes">
|
---|
15012 | <desc>The plug-in name.</desc>
|
---|
15013 | </attribute>
|
---|
15014 | <attribute name="description" type="wstring" readonly="yes">
|
---|
15015 | <desc>The plug-in description.</desc>
|
---|
15016 | </attribute>
|
---|
15017 | <attribute name="frontend" type="wstring" readonly="yes">
|
---|
15018 | <desc>
|
---|
15019 | The name of the frontend or component name this plug-in plugs into.
|
---|
15020 | </desc>
|
---|
15021 | </attribute>
|
---|
15022 | <attribute name="modulePath" type="wstring" readonly="yes">
|
---|
15023 | <desc> The module path. </desc>
|
---|
15024 | </attribute>
|
---|
15025 | </interface>
|
---|
15026 |
|
---|
15027 | <interface
|
---|
15028 | name="IExtPackBase" extends="$unknown"
|
---|
15029 | uuid="5ffb0b64-0ad6-467d-af62-1157e7dc3c99"
|
---|
15030 | wsmap="suppress"
|
---|
15031 | >
|
---|
15032 | <desc>
|
---|
15033 | Interface for querying information about an extension pack as well as
|
---|
15034 | accessing COM objects within it.
|
---|
15035 | </desc>
|
---|
15036 | <attribute name="name" type="wstring" readonly="yes">
|
---|
15037 | <desc>The extension pack name. This is unique.</desc>
|
---|
15038 | </attribute>
|
---|
15039 | <attribute name="description" type="wstring" readonly="yes">
|
---|
15040 | <desc>The extension pack description.</desc>
|
---|
15041 | </attribute>
|
---|
15042 | <attribute name="version" type="wstring" readonly="yes">
|
---|
15043 | <desc>
|
---|
15044 | The extension pack version string. This is on the same form as
|
---|
15045 | other VirtualBox version strings, i.e.: "1.2.3", "1.2.3_BETA1",
|
---|
15046 | "1.2.3-OSE", "1.2.3r45678", "1.2.3r45678-OSE", "1.2.3_BETA1-r45678"
|
---|
15047 | or "1.2.3_BETA1-r45678-OSE"
|
---|
15048 | </desc>
|
---|
15049 | </attribute>
|
---|
15050 | <attribute name="revision" type="unsigned long" readonly="yes">
|
---|
15051 | <desc>The extension pack internal revision number.</desc>
|
---|
15052 | </attribute>
|
---|
15053 | <attribute name="VRDEModule" type="wstring" readonly="yes">
|
---|
15054 | <desc>The name of the VRDE module if the extension pack sports one.</desc>
|
---|
15055 | </attribute>
|
---|
15056 | <attribute name="plugIns" type="IExtPackPlugIn" safearray="yes" readonly="yes">
|
---|
15057 | <desc>Plug-ins provided by this extension pack.</desc>
|
---|
15058 | </attribute>
|
---|
15059 | <attribute name="usable" type="boolean" readonly="yes">
|
---|
15060 | <desc>
|
---|
15061 | Indicates whether the extension pack is usable or not.
|
---|
15062 |
|
---|
15063 | There are a number of reasons why an extension pack might be unusable,
|
---|
15064 | typical examples would be broken installation/file or that it is
|
---|
15065 | incompatible with the current VirtualBox version.
|
---|
15066 | </desc>
|
---|
15067 | </attribute>
|
---|
15068 | <attribute name="whyUnusable" type="wstring" readonly="yes">
|
---|
15069 | <desc>
|
---|
15070 | String indicating why the extension pack is not usable. This is an
|
---|
15071 | empty string if usable and always a non-empty string if not usable.
|
---|
15072 | </desc>
|
---|
15073 | </attribute>
|
---|
15074 | <attribute name="showLicense" type="boolean" readonly="yes">
|
---|
15075 | <desc>Whether to show the license before installation</desc>
|
---|
15076 | </attribute>
|
---|
15077 | <attribute name="license" type="wstring" readonly="yes">
|
---|
15078 | <desc>
|
---|
15079 | The default HTML license text for the extension pack. Same as
|
---|
15080 | calling <link to="#queryLicense">queryLicense</link> with
|
---|
15081 | preferredLocale and preferredLanguage as empty strings and format set
|
---|
15082 | to html.
|
---|
15083 | </desc>
|
---|
15084 | </attribute>
|
---|
15085 |
|
---|
15086 | <method name="queryLicense">
|
---|
15087 | <desc>
|
---|
15088 | Full feature version of the license attribute.
|
---|
15089 | </desc>
|
---|
15090 | <param name="preferredLocale" type="wstring" dir="in">
|
---|
15091 | <desc>
|
---|
15092 | The preferred license locale. Pass an empty string to get the default
|
---|
15093 | license.
|
---|
15094 | </desc>
|
---|
15095 | </param>
|
---|
15096 | <param name="preferredLanguage" type="wstring" dir="in">
|
---|
15097 | <desc>
|
---|
15098 | The preferred license language. Pass an empty string to get the
|
---|
15099 | default language for the locale.
|
---|
15100 | </desc>
|
---|
15101 | </param>
|
---|
15102 | <param name="format" type="wstring" dir="in">
|
---|
15103 | <desc>
|
---|
15104 | The license format: html, rtf or txt. If a license is present there
|
---|
15105 | will always be an HTML of it, the rich text format (RTF) and plain
|
---|
15106 | text (txt) versions are optional. If
|
---|
15107 | </desc>
|
---|
15108 | </param>
|
---|
15109 | <param name="licenseText" type="wstring" dir="return">
|
---|
15110 | <desc>The license text.</desc>
|
---|
15111 | </param>
|
---|
15112 | </method>
|
---|
15113 |
|
---|
15114 | </interface>
|
---|
15115 |
|
---|
15116 | <interface
|
---|
15117 | name="IExtPack" extends="IExtPackBase"
|
---|
15118 | uuid="431685da-3618-4ebc-b038-833ba829b4b2"
|
---|
15119 | wsmap="suppress"
|
---|
15120 | >
|
---|
15121 | <desc>
|
---|
15122 | Interface for querying information about an extension pack as well as
|
---|
15123 | accessing COM objects within it.
|
---|
15124 | </desc>
|
---|
15125 | <method name="queryObject">
|
---|
15126 | <desc>
|
---|
15127 | Queries the IUnknown interface to an object in the extension pack
|
---|
15128 | main module. This allows plug-ins and others to talk directly to an
|
---|
15129 | extension pack.
|
---|
15130 | </desc>
|
---|
15131 | <param name="objUuid" type="wstring" dir="in">
|
---|
15132 | <desc>The object ID. What exactly this is </desc>
|
---|
15133 | </param>
|
---|
15134 | <param name="returnInterface" type="$unknown" dir="return">
|
---|
15135 | <desc>The queried interface.</desc>
|
---|
15136 | </param>
|
---|
15137 | </method>
|
---|
15138 | </interface>
|
---|
15139 |
|
---|
15140 | <interface
|
---|
15141 | name="IExtPackFile" extends="IExtPackBase"
|
---|
15142 | uuid="b6b49f55-efcc-4f08-b486-56e8d8afb10b"
|
---|
15143 | wsmap="suppress"
|
---|
15144 | >
|
---|
15145 | <desc>
|
---|
15146 | Extension pack file (aka tarball, .vbox-extpack) representation returned
|
---|
15147 | by IExtPackManager::openExtPackFile. This provides the base extension
|
---|
15148 | pack information with the addition of the file name. It also provides an
|
---|
15149 | alternative to IExtPackManager::install.
|
---|
15150 | </desc>
|
---|
15151 | <attribute name="filePath" type="wstring" readonly="yes">
|
---|
15152 | <desc>
|
---|
15153 | The path to the extension pack file.
|
---|
15154 | </desc>
|
---|
15155 | </attribute>
|
---|
15156 |
|
---|
15157 | <method name="install">
|
---|
15158 | <desc>
|
---|
15159 | Install the extension pack.
|
---|
15160 | </desc>
|
---|
15161 | <param name="replace" type="boolean" dir="in">
|
---|
15162 | <desc>
|
---|
15163 | Set this to automatically uninstall any existing extension pack with
|
---|
15164 | the same name as the one being installed.
|
---|
15165 | </desc>
|
---|
15166 | </param>
|
---|
15167 | <param name="displayInfo" type="wstring" dir="in">
|
---|
15168 | <desc>
|
---|
15169 | Platform specific display information. Reserved for future hacks.
|
---|
15170 | </desc>
|
---|
15171 | </param>
|
---|
15172 | <param name="progess" type="IProgress" dir="return">
|
---|
15173 | <desc>
|
---|
15174 | Progress object for the operation.
|
---|
15175 | </desc>
|
---|
15176 | </param>
|
---|
15177 | </method>
|
---|
15178 | </interface>
|
---|
15179 |
|
---|
15180 | <interface
|
---|
15181 | name="IExtPackManager" extends="$unknown"
|
---|
15182 | uuid="2451b1ba-ab1c-42fb-b453-c58433bea8c7"
|
---|
15183 | wsmap="suppress"
|
---|
15184 | >
|
---|
15185 | <desc>
|
---|
15186 | Interface for managing VirtualBox Extension Packs.
|
---|
15187 |
|
---|
15188 | TODO: Describe extension packs, how they are managed and how to create
|
---|
15189 | one.
|
---|
15190 | </desc>
|
---|
15191 |
|
---|
15192 | <attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
|
---|
15193 | <desc>
|
---|
15194 | List of the installed extension packs.
|
---|
15195 | </desc>
|
---|
15196 | </attribute>
|
---|
15197 |
|
---|
15198 | <method name="find">
|
---|
15199 | <desc>
|
---|
15200 | Returns the extension pack with the specified name if found.
|
---|
15201 |
|
---|
15202 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
15203 | No extension pack matching @a name was found.
|
---|
15204 | </result>
|
---|
15205 | </desc>
|
---|
15206 | <param name="name" type="wstring" dir="in">
|
---|
15207 | <desc>The name of the extension pack to locate.</desc>
|
---|
15208 | </param>
|
---|
15209 | <param name="returnData" type="IExtPack" dir="return">
|
---|
15210 | <desc>The extension pack if found.</desc>
|
---|
15211 | </param>
|
---|
15212 | </method>
|
---|
15213 |
|
---|
15214 | <method name="openExtPackFile">
|
---|
15215 | <desc>
|
---|
15216 | Attempts to open an extension pack file in preparation for
|
---|
15217 | installation.
|
---|
15218 | </desc>
|
---|
15219 | <param name="path" type="wstring" dir="in">
|
---|
15220 | <desc>The path of the extension pack tarball.</desc>
|
---|
15221 | </param>
|
---|
15222 | <param name="file" type="IExtPackFile" dir="return">
|
---|
15223 | <desc>The interface of the extension pack file object.</desc>
|
---|
15224 | </param>
|
---|
15225 | </method>
|
---|
15226 |
|
---|
15227 | <method name="uninstall">
|
---|
15228 | <desc>Uninstalls an extension pack, removing all related files.</desc>
|
---|
15229 | <param name="name" type="wstring" dir="in">
|
---|
15230 | <desc>The name of the extension pack to uninstall.</desc>
|
---|
15231 | </param>
|
---|
15232 | <param name="forcedRemoval" type="boolean" dir="in">
|
---|
15233 | <desc>
|
---|
15234 | Forced removal of the extension pack. This means that the uninstall
|
---|
15235 | hook will not be called.
|
---|
15236 | </desc>
|
---|
15237 | </param>
|
---|
15238 | <param name="displayInfo" type="wstring" dir="in">
|
---|
15239 | <desc>
|
---|
15240 | Platform specific display information. Reserved for future hacks.
|
---|
15241 | </desc>
|
---|
15242 | </param>
|
---|
15243 | <param name="progess" type="IProgress" dir="return">
|
---|
15244 | <desc>
|
---|
15245 | Progress object for the operation.
|
---|
15246 | </desc>
|
---|
15247 | </param>
|
---|
15248 | </method>
|
---|
15249 |
|
---|
15250 | <method name="cleanup">
|
---|
15251 | <desc>Cleans up failed installs and uninstalls</desc>
|
---|
15252 | </method>
|
---|
15253 |
|
---|
15254 | <method name="QueryAllPlugInsForFrontend">
|
---|
15255 | <desc>
|
---|
15256 | Gets the path to all the plug-in modules for a given frontend.
|
---|
15257 |
|
---|
15258 | This is a convenience method that is intended to simplify the plug-in
|
---|
15259 | loading process for a frontend.
|
---|
15260 | </desc>
|
---|
15261 | <param name="frontendName" type="wstring" dir="in">
|
---|
15262 | <desc>The name of the frontend or component.</desc>
|
---|
15263 | </param>
|
---|
15264 | <param name="plugInModules" type="wstring" dir="return" safearray="yes">
|
---|
15265 | <desc>Array containing the plug-in modules (full paths).</desc>
|
---|
15266 | </param>
|
---|
15267 | </method>
|
---|
15268 |
|
---|
15269 | <method name="IsExtPackUsable">
|
---|
15270 | <desc>Check if the given extension pack is loaded and usable.</desc>
|
---|
15271 | <param name="name" type="wstring" dir="in">
|
---|
15272 | <desc>The name of the extension pack to check for.</desc>
|
---|
15273 | </param>
|
---|
15274 | <param name="usable" type="boolean" dir="return">
|
---|
15275 | <desc>Is the given extension pack loaded and usable.</desc>
|
---|
15276 | </param>
|
---|
15277 | </method>
|
---|
15278 |
|
---|
15279 | </interface>
|
---|
15280 |
|
---|
15281 | <!--
|
---|
15282 | // BandwidthGroupType
|
---|
15283 | /////////////////////////////////////////////////////////////////////////
|
---|
15284 | -->
|
---|
15285 | <enum
|
---|
15286 | name="BandwidthGroupType"
|
---|
15287 | uuid="1d92b67d-dc69-4be9-ad4c-93a01e1e0c8e">
|
---|
15288 |
|
---|
15289 | <desc>
|
---|
15290 | Type of a bandwidth control group.
|
---|
15291 | </desc>
|
---|
15292 |
|
---|
15293 | <const name="Null" value="0">
|
---|
15294 | <desc>
|
---|
15295 | Null type, must be first.
|
---|
15296 | </desc>
|
---|
15297 | </const>
|
---|
15298 |
|
---|
15299 | <const name="Disk" value="1">
|
---|
15300 | <desc>
|
---|
15301 | The bandwidth group controls disk I/O.
|
---|
15302 | </desc>
|
---|
15303 | </const>
|
---|
15304 |
|
---|
15305 | <const name="Network" value="2">
|
---|
15306 | <desc>
|
---|
15307 | The bandwidth group controls network I/O.
|
---|
15308 | </desc>
|
---|
15309 | </const>
|
---|
15310 |
|
---|
15311 | </enum>
|
---|
15312 |
|
---|
15313 | <!--
|
---|
15314 | // IBandwidthGroup
|
---|
15315 | /////////////////////////////////////////////////////////////////////////
|
---|
15316 | -->
|
---|
15317 | <interface
|
---|
15318 | name="IBandwidthGroup" extends="$unknown"
|
---|
15319 | uuid="badea2d7-0261-4146-89f0-6a57cc34833d"
|
---|
15320 | wsmap="managed"
|
---|
15321 | >
|
---|
15322 | <desc>Represents one bandwidth group.</desc>
|
---|
15323 |
|
---|
15324 | <attribute name="name" type="wstring" readonly="yes">
|
---|
15325 | <desc>Name of the group.</desc>
|
---|
15326 | </attribute>
|
---|
15327 |
|
---|
15328 | <attribute name="type" type="BandwidthGroupType" readonly="yes">
|
---|
15329 | <desc>Type of the group.</desc>
|
---|
15330 | </attribute>
|
---|
15331 |
|
---|
15332 | <attribute name="reference" type="unsigned long" readonly="yes">
|
---|
15333 | <desc>How many devices/medium attachements use this group.</desc>
|
---|
15334 | </attribute>
|
---|
15335 |
|
---|
15336 | <attribute name="maxMbPerSec" type="unsigned long">
|
---|
15337 | <desc>The maximum number of MBytes which can be transfered by all
|
---|
15338 | entities attached to this group during one second.</desc>
|
---|
15339 | </attribute>
|
---|
15340 |
|
---|
15341 | </interface>
|
---|
15342 |
|
---|
15343 | <!--
|
---|
15344 | // IBandwidthControl
|
---|
15345 | /////////////////////////////////////////////////////////////////////////
|
---|
15346 | -->
|
---|
15347 | <interface
|
---|
15348 | name="IBandwidthControl" extends="$unknown"
|
---|
15349 | uuid="d0a24db0-f756-11df-98cf-0800200c9a66"
|
---|
15350 | wsmap="managed"
|
---|
15351 | >
|
---|
15352 | <desc>
|
---|
15353 | Controls the bandwidth groups of one machine used to cap I/O done by a VM.
|
---|
15354 | This includes network and disk I/O.
|
---|
15355 | </desc>
|
---|
15356 |
|
---|
15357 | <attribute name="numGroups" type="unsigned long" readonly="yes">
|
---|
15358 | <desc>
|
---|
15359 | The current number of existing bandwidth groups managed.
|
---|
15360 | </desc>
|
---|
15361 | </attribute>
|
---|
15362 |
|
---|
15363 | <method name="CreateBandwidthGroup">
|
---|
15364 | <desc>
|
---|
15365 | Creates a new bandwidth group.
|
---|
15366 | </desc>
|
---|
15367 |
|
---|
15368 | <param name="name" type="wstring" dir="in">
|
---|
15369 | <desc>Name of the bandwidth group.</desc>
|
---|
15370 | </param>
|
---|
15371 | <param name="type" type="BandwidthGroupType" dir="in">
|
---|
15372 | <desc>The type of the bandwidth group (network or disk).</desc>
|
---|
15373 | </param>
|
---|
15374 | <param name="maxMbPerSec" type="unsigned long" dir="in">
|
---|
15375 | <desc>The maximum number of MBytes which can be transfered by all
|
---|
15376 | entities attached to this group during one second.</desc>
|
---|
15377 | </param>
|
---|
15378 | </method>
|
---|
15379 |
|
---|
15380 | <method name="DeleteBandwidthGroup">
|
---|
15381 | <desc>
|
---|
15382 | Deletes a new bandwidth group.
|
---|
15383 | </desc>
|
---|
15384 |
|
---|
15385 | <param name="name" type="wstring" dir="in">
|
---|
15386 | <desc>Name of the bandwidth group to delete.</desc>
|
---|
15387 | </param>
|
---|
15388 | </method>
|
---|
15389 |
|
---|
15390 | <method name="GetBandwidthGroup" const="yes">
|
---|
15391 | <desc>
|
---|
15392 | Get a bandwidth group by name.
|
---|
15393 | </desc>
|
---|
15394 |
|
---|
15395 | <param name="name" type="wstring" dir="in">
|
---|
15396 | <desc>Name of the bandwidth group to get.</desc>
|
---|
15397 | </param>
|
---|
15398 | <param name="bandwidthGroup" type="IBandwidthGroup" dir="return">
|
---|
15399 | <desc>Where to store the bandwidth group on success.</desc>
|
---|
15400 | </param>
|
---|
15401 | </method>
|
---|
15402 |
|
---|
15403 | <method name="GetAllBandwidthGroups" const="yes">
|
---|
15404 | <desc>
|
---|
15405 | Get all managed bandwidth groups.
|
---|
15406 | </desc>
|
---|
15407 |
|
---|
15408 | <param name="bandwidthGroups" type="IBandwidthGroup" dir="return" safearray="yes">
|
---|
15409 | <desc>The array of managed bandwidth groups.</desc>
|
---|
15410 | </param>
|
---|
15411 | </method>
|
---|
15412 | </interface>
|
---|
15413 |
|
---|
15414 | <!--
|
---|
15415 | // IVirtualBoxClient
|
---|
15416 | /////////////////////////////////////////////////////////////////////////
|
---|
15417 | -->
|
---|
15418 |
|
---|
15419 | <interface
|
---|
15420 | name="IVirtualBoxClient" extends="$unknown"
|
---|
15421 | uuid="5fe0bd48-1181-40d1-991f-3b02f269a823"
|
---|
15422 | wsmap="suppress"
|
---|
15423 | >
|
---|
15424 | <desc>
|
---|
15425 | Convenience interface for client applications. Treat this as a
|
---|
15426 | singleton, i.e. never create more than one instance of this interface.
|
---|
15427 |
|
---|
15428 | At the moment only available for clients of the local API (not usable
|
---|
15429 | via the webservice). Once the session logic is redesigned this might
|
---|
15430 | change.
|
---|
15431 | </desc>
|
---|
15432 |
|
---|
15433 | <attribute name="virtualBox" type="IVirtualBox" readonly="yes">
|
---|
15434 | <desc>
|
---|
15435 | Reference to the server-side API root object.
|
---|
15436 | </desc>
|
---|
15437 | </attribute>
|
---|
15438 |
|
---|
15439 | <attribute name="session" type="ISession" readonly="yes">
|
---|
15440 | <desc>
|
---|
15441 | Create a new session object and return the reference to it.
|
---|
15442 | </desc>
|
---|
15443 | </attribute>
|
---|
15444 |
|
---|
15445 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
15446 | <desc>
|
---|
15447 | Event source for VirtualBoxClient events.
|
---|
15448 | </desc>
|
---|
15449 | </attribute>
|
---|
15450 |
|
---|
15451 | </interface>
|
---|
15452 |
|
---|
15453 | <!--
|
---|
15454 | // Events
|
---|
15455 | /////////////////////////////////////////////////////////////////////////
|
---|
15456 | -->
|
---|
15457 | <enum
|
---|
15458 | name="VBoxEventType"
|
---|
15459 | uuid="cce48db6-8561-479d-8d46-1358bab45d4e"
|
---|
15460 | >
|
---|
15461 |
|
---|
15462 | <desc>
|
---|
15463 | Type of an event.
|
---|
15464 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
15465 | </desc>
|
---|
15466 |
|
---|
15467 | <const name="Invalid" value="0">
|
---|
15468 | <desc>
|
---|
15469 | Invalid event, must be first.
|
---|
15470 | </desc>
|
---|
15471 | </const>
|
---|
15472 |
|
---|
15473 | <const name="Any" value="1">
|
---|
15474 | <desc>
|
---|
15475 | Wildcard for all events.
|
---|
15476 | Events of this type are never delivered, and only used in
|
---|
15477 | registerListener() call to simplify registration.
|
---|
15478 | </desc>
|
---|
15479 | </const>
|
---|
15480 |
|
---|
15481 | <const name="Vetoable" value="2">
|
---|
15482 | <desc>
|
---|
15483 | Wildcard for all vetoable events. Events of this type are never delivered, and only
|
---|
15484 | used in registerListener() call to simplify registration.
|
---|
15485 | </desc>
|
---|
15486 | </const>
|
---|
15487 |
|
---|
15488 | <const name="MachineEvent" value="3">
|
---|
15489 | <desc>
|
---|
15490 | Wildcard for all machine events. Events of this type are never delivered, and only used in
|
---|
15491 | registerListener() call to simplify registration.
|
---|
15492 | </desc>
|
---|
15493 | </const>
|
---|
15494 |
|
---|
15495 | <const name="SnapshotEvent" value="4">
|
---|
15496 | <desc>
|
---|
15497 | Wildcard for all snapshot events. Events of this type are never delivered, and only used in
|
---|
15498 | registerListener() call to simplify registration.
|
---|
15499 | </desc>
|
---|
15500 | </const>
|
---|
15501 |
|
---|
15502 | <const name="InputEvent" value="5">
|
---|
15503 | <desc>
|
---|
15504 | Wildcard for all input device (keyboard, mouse) events.
|
---|
15505 | Events of this type are never delivered, and only used in
|
---|
15506 | registerListener() call to simplify registration.
|
---|
15507 | </desc>
|
---|
15508 | </const>
|
---|
15509 |
|
---|
15510 | <const name="LastWildcard" value="31">
|
---|
15511 | <desc>
|
---|
15512 | Last wildcard.
|
---|
15513 | </desc>
|
---|
15514 | </const>
|
---|
15515 |
|
---|
15516 | <const name="OnMachineStateChanged" value="32">
|
---|
15517 | <desc>
|
---|
15518 | See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
|
---|
15519 | </desc>
|
---|
15520 | </const>
|
---|
15521 | <const name="OnMachineDataChanged" value="33">
|
---|
15522 | <desc>
|
---|
15523 | See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
|
---|
15524 | </desc>
|
---|
15525 | </const>
|
---|
15526 | <const name="OnExtraDataChanged" value="34">
|
---|
15527 | <desc>
|
---|
15528 | See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
|
---|
15529 | </desc>
|
---|
15530 | </const>
|
---|
15531 | <const name="OnExtraDataCanChange" value="35">
|
---|
15532 | <desc>
|
---|
15533 | See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
|
---|
15534 | </desc>
|
---|
15535 | </const>
|
---|
15536 | <const name="OnMediumRegistered" value="36">
|
---|
15537 | <desc>
|
---|
15538 | See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
|
---|
15539 | </desc>
|
---|
15540 | </const>
|
---|
15541 | <const name="OnMachineRegistered" value="37">
|
---|
15542 | <desc>
|
---|
15543 | See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
|
---|
15544 | </desc>
|
---|
15545 | </const>
|
---|
15546 | <const name="OnSessionStateChanged" value="38">
|
---|
15547 | <desc>
|
---|
15548 | See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
|
---|
15549 | </desc>
|
---|
15550 | </const>
|
---|
15551 | <const name="OnSnapshotTaken" value="39">
|
---|
15552 | <desc>
|
---|
15553 | See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
|
---|
15554 | </desc>
|
---|
15555 | </const>
|
---|
15556 | <const name="OnSnapshotDeleted" value="40">
|
---|
15557 | <desc>
|
---|
15558 | See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
|
---|
15559 | </desc>
|
---|
15560 | </const>
|
---|
15561 | <const name="OnSnapshotChanged" value="41">
|
---|
15562 | <desc>
|
---|
15563 | See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
|
---|
15564 | </desc>
|
---|
15565 | </const>
|
---|
15566 | <const name="OnGuestPropertyChanged" value="42">
|
---|
15567 | <desc>
|
---|
15568 | See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
|
---|
15569 | </desc>
|
---|
15570 | </const>
|
---|
15571 | <!-- Console events -->
|
---|
15572 | <const name="OnMousePointerShapeChanged" value="43">
|
---|
15573 | <desc>
|
---|
15574 | See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
|
---|
15575 | </desc>
|
---|
15576 | </const>
|
---|
15577 | <const name="OnMouseCapabilityChanged" value="44">
|
---|
15578 | <desc>
|
---|
15579 | See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
|
---|
15580 | </desc>
|
---|
15581 | </const>
|
---|
15582 | <const name="OnKeyboardLedsChanged" value="45">
|
---|
15583 | <desc>
|
---|
15584 | See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
|
---|
15585 | </desc>
|
---|
15586 | </const>
|
---|
15587 | <const name="OnStateChanged" value="46">
|
---|
15588 | <desc>
|
---|
15589 | See <link to="IStateChangedEvent">IStateChangedEvent</link>.
|
---|
15590 | </desc>
|
---|
15591 | </const>
|
---|
15592 | <const name="OnAdditionsStateChanged" value="47">
|
---|
15593 | <desc>
|
---|
15594 | See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
|
---|
15595 | </desc>
|
---|
15596 | </const>
|
---|
15597 | <const name="OnNetworkAdapterChanged" value="48">
|
---|
15598 | <desc>
|
---|
15599 | See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
|
---|
15600 | </desc>
|
---|
15601 | </const>
|
---|
15602 | <const name="OnSerialPortChanged" value="49">
|
---|
15603 | <desc>
|
---|
15604 | See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
|
---|
15605 | </desc>
|
---|
15606 | </const>
|
---|
15607 | <const name="OnParallelPortChanged" value="50">
|
---|
15608 | <desc>
|
---|
15609 | See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
|
---|
15610 | </desc>
|
---|
15611 | </const>
|
---|
15612 | <const name="OnStorageControllerChanged" value="51">
|
---|
15613 | <desc>
|
---|
15614 | See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
|
---|
15615 | </desc>
|
---|
15616 | </const>
|
---|
15617 | <const name="OnMediumChanged" value="52">
|
---|
15618 | <desc>
|
---|
15619 | See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
|
---|
15620 | </desc>
|
---|
15621 | </const>
|
---|
15622 | <const name="OnVRDEServerChanged" value="53">
|
---|
15623 | <desc>
|
---|
15624 | See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
|
---|
15625 | </desc>
|
---|
15626 | </const>
|
---|
15627 | <const name="OnUSBControllerChanged" value="54">
|
---|
15628 | <desc>
|
---|
15629 | See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
|
---|
15630 | </desc>
|
---|
15631 | </const>
|
---|
15632 | <const name="OnUSBDeviceStateChanged" value="55">
|
---|
15633 | <desc>
|
---|
15634 | See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
|
---|
15635 | </desc>
|
---|
15636 | </const>
|
---|
15637 | <const name="OnSharedFolderChanged" value="56">
|
---|
15638 | <desc>
|
---|
15639 | See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
|
---|
15640 | </desc>
|
---|
15641 | </const>
|
---|
15642 | <const name="OnRuntimeError" value="57">
|
---|
15643 | <desc>
|
---|
15644 | See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
|
---|
15645 | </desc>
|
---|
15646 | </const>
|
---|
15647 | <const name="OnCanShowWindow" value="58">
|
---|
15648 | <desc>
|
---|
15649 | See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
|
---|
15650 | </desc>
|
---|
15651 | </const>
|
---|
15652 | <const name="OnShowWindow" value="59">
|
---|
15653 | <desc>
|
---|
15654 | See <link to="IShowWindowEvent">IShowWindowEvent</link>.
|
---|
15655 | </desc>
|
---|
15656 | </const>
|
---|
15657 | <const name="OnCPUChanged" value="60">
|
---|
15658 | <desc>
|
---|
15659 | See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
|
---|
15660 | </desc>
|
---|
15661 | </const>
|
---|
15662 | <const name="OnVRDEServerInfoChanged" value="61">
|
---|
15663 | <desc>
|
---|
15664 | See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
|
---|
15665 | </desc>
|
---|
15666 | </const>
|
---|
15667 | <const name="OnEventSourceChanged" value="62">
|
---|
15668 | <desc>
|
---|
15669 | See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
|
---|
15670 | </desc>
|
---|
15671 | </const>
|
---|
15672 | <const name="OnCPUExecutionCapChanged" value="63">
|
---|
15673 | <desc>
|
---|
15674 | See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
|
---|
15675 | </desc>
|
---|
15676 | </const>
|
---|
15677 | <const name="OnGuestKeyboard" value="64">
|
---|
15678 | <desc>
|
---|
15679 | See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
|
---|
15680 | </desc>
|
---|
15681 | </const>
|
---|
15682 | <const name="OnGuestMouse" value="65">
|
---|
15683 | <desc>
|
---|
15684 | See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
|
---|
15685 | </desc>
|
---|
15686 | </const>
|
---|
15687 | <const name="OnNATRedirect" value="66">
|
---|
15688 | <desc>
|
---|
15689 | See <link to="INATRedirectEvent">INATRedirectEvent</link>.
|
---|
15690 | </desc>
|
---|
15691 | </const>
|
---|
15692 | <const name="OnHostPciDevicePlug" value="67">
|
---|
15693 | <desc>
|
---|
15694 | See <link to="IHostPciDevicePlugEvent">IHostPciDevicePlugEvent</link>.
|
---|
15695 | </desc>
|
---|
15696 | </const>
|
---|
15697 | <const name="OnVBoxSVCAvailabilityChanged" value="68">
|
---|
15698 | <desc>
|
---|
15699 | See <link to="IVBoxSVCAvailabilityChangedEvent">IVBoxSVCAvailablityChangedEvent</link>.
|
---|
15700 | </desc>
|
---|
15701 | </const>
|
---|
15702 | <const name="OnBandwidthGroupChanged" value="69">
|
---|
15703 | <desc>
|
---|
15704 | See <link to="IBandwidthGroupChangedEvent">IBandwidthGroupChangedEvent</link>.
|
---|
15705 | </desc>
|
---|
15706 | </const>
|
---|
15707 | <const name="OnGuestMonitorChanged" value="70">
|
---|
15708 | <desc>
|
---|
15709 | See <link to="IGuestMonitorChangedEvent">IGuestMonitorChangedEvent</link>.
|
---|
15710 | </desc>
|
---|
15711 | </const>
|
---|
15712 | <const name="OnStorageDeviceChanged" value="71">
|
---|
15713 | <desc>
|
---|
15714 | See <link to="IStorageDeviceChangedEvent">IStorageDeviceChangedEvent</link>.
|
---|
15715 | </desc>
|
---|
15716 | </const>
|
---|
15717 |
|
---|
15718 | <!-- Last event marker -->
|
---|
15719 | <const name="Last" value="72">
|
---|
15720 | <desc>
|
---|
15721 | Must be last event, used for iterations and structures relying on numerical event values.
|
---|
15722 | </desc>
|
---|
15723 | </const>
|
---|
15724 |
|
---|
15725 | </enum>
|
---|
15726 |
|
---|
15727 | <interface
|
---|
15728 | name="IEventSource" extends="$unknown"
|
---|
15729 | uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
|
---|
15730 | wsmap="managed"
|
---|
15731 | >
|
---|
15732 | <desc>
|
---|
15733 | Event source. Generally, any object which could generate events can be an event source,
|
---|
15734 | or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
|
---|
15735 | an event source can work with listeners in either active or passive mode. In active mode it is up to
|
---|
15736 | the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
|
---|
15737 | event source keeps track of pending events for each listener and returns available events on demand.
|
---|
15738 |
|
---|
15739 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
15740 | </desc>
|
---|
15741 |
|
---|
15742 | <method name="createListener">
|
---|
15743 | <desc>
|
---|
15744 | Creates a new listener object, useful for passive mode.
|
---|
15745 | </desc>
|
---|
15746 | <param name="listener" type="IEventListener" dir="return"/>
|
---|
15747 | </method>
|
---|
15748 |
|
---|
15749 | <method name="createAggregator">
|
---|
15750 | <desc>
|
---|
15751 | Creates an aggregator event source, collecting events from multiple sources.
|
---|
15752 | This way a single listener can listen for events coming from multiple sources,
|
---|
15753 | using a single blocking getEvent() on the returned aggregator.
|
---|
15754 | </desc>
|
---|
15755 | <param name="subordinates" type="IEventSource" dir="in" safearray="yes">
|
---|
15756 | <desc>
|
---|
15757 | Subordinate event source this one aggregatres.
|
---|
15758 | </desc>
|
---|
15759 | </param>
|
---|
15760 | <param name="result" type="IEventSource" dir="return">
|
---|
15761 | <desc>
|
---|
15762 | Event source aggregating passed sources.
|
---|
15763 | </desc>
|
---|
15764 | </param>
|
---|
15765 | </method>
|
---|
15766 |
|
---|
15767 | <method name="registerListener">
|
---|
15768 | <desc>
|
---|
15769 | Register an event listener.
|
---|
15770 |
|
---|
15771 | <note>
|
---|
15772 | To avoid system overload, the VirtualBox server process checks if passive event
|
---|
15773 | listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
|
---|
15774 | current implementation, if more than 500 pending events are detected for a passive
|
---|
15775 | event listener, it is forcefully unregistered by the system, and further
|
---|
15776 | <link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
|
---|
15777 | </note>
|
---|
15778 | </desc>
|
---|
15779 | <param name="listener" type="IEventListener" dir="in">
|
---|
15780 | <desc>Listener to register.</desc>
|
---|
15781 | </param>
|
---|
15782 | <param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
|
---|
15783 | <desc>
|
---|
15784 | Event types listener is interested in. One can use wildcards like -
|
---|
15785 | <link to="VBoxEventType_Any"/> to specify wildcards, matching more
|
---|
15786 | than one event.
|
---|
15787 | </desc>
|
---|
15788 | </param>
|
---|
15789 | <param name="active" type="boolean" dir="in">
|
---|
15790 | <desc>
|
---|
15791 | Which mode this listener is operating in.
|
---|
15792 | In active mode, <link to="IEventListener::handleEvent" /> is called directly.
|
---|
15793 | In passive mode, an internal event queue is created for this this IEventListener.
|
---|
15794 | For each event coming in, it is added to queues for all interested registered passive
|
---|
15795 | listeners. It is then up to the external code to call the listener's
|
---|
15796 | <link to="IEventListener::handleEvent" /> method. When done with an event, the
|
---|
15797 | external code must call <link to="#eventProcessed" />.
|
---|
15798 | </desc>
|
---|
15799 | </param>
|
---|
15800 | </method>
|
---|
15801 |
|
---|
15802 | <method name="unregisterListener">
|
---|
15803 | <desc>
|
---|
15804 | Unregister an event listener. If listener is passive, and some waitable events are still
|
---|
15805 | in queue they are marked as processed automatically.
|
---|
15806 | </desc>
|
---|
15807 | <param name="listener" type="IEventListener" dir="in">
|
---|
15808 | <desc>Listener to unregister.</desc>
|
---|
15809 | </param>
|
---|
15810 | </method>
|
---|
15811 |
|
---|
15812 | <method name="fireEvent">
|
---|
15813 | <desc>
|
---|
15814 | Fire an event for this source.
|
---|
15815 | </desc>
|
---|
15816 | <param name="event" type="IEvent" dir="in">
|
---|
15817 | <desc>Event to deliver.</desc>
|
---|
15818 | </param>
|
---|
15819 | <param name="timeout" type="long" dir="in">
|
---|
15820 | <desc>
|
---|
15821 | Maximum time to wait for event processing (if event is waitable), in ms;
|
---|
15822 | 0 = no wait, -1 = indefinite wait.
|
---|
15823 | </desc>
|
---|
15824 | </param>
|
---|
15825 | <param name="result" type="boolean" dir="return">
|
---|
15826 | <desc>true if an event was delivered to all targets, or is non-waitable.</desc>
|
---|
15827 | </param>
|
---|
15828 | </method>
|
---|
15829 |
|
---|
15830 | <method name="getEvent">
|
---|
15831 | <desc>
|
---|
15832 | Get events from this peer's event queue (for passive mode). Calling this method
|
---|
15833 | regularly is required for passive event listeners to avoid system overload;
|
---|
15834 | see <link to="IEventSource::registerListener" /> for details.
|
---|
15835 |
|
---|
15836 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
15837 | Listener is not registered, or autounregistered.
|
---|
15838 | </result>
|
---|
15839 | </desc>
|
---|
15840 | <param name="listener" type="IEventListener" dir="in">
|
---|
15841 | <desc>Which listener to get data for.</desc>
|
---|
15842 | </param>
|
---|
15843 | <param name="timeout" type="long" dir="in">
|
---|
15844 | <desc>
|
---|
15845 | Maximum time to wait for events, in ms;
|
---|
15846 | 0 = no wait, -1 = indefinite wait.
|
---|
15847 | </desc>
|
---|
15848 | </param>
|
---|
15849 | <param name="event" type="IEvent" dir="return">
|
---|
15850 | <desc>Event retrieved, or null if none available.</desc>
|
---|
15851 | </param>
|
---|
15852 | </method>
|
---|
15853 |
|
---|
15854 | <method name="eventProcessed">
|
---|
15855 | <desc>
|
---|
15856 | Must be called for waitable events after a particular listener finished its
|
---|
15857 | event processing. When all listeners of a particular event have called this
|
---|
15858 | method, the system will then call <link to="IEvent::setProcessed" />.
|
---|
15859 | </desc>
|
---|
15860 | <param name="listener" type="IEventListener" dir="in">
|
---|
15861 | <desc>Which listener processed event.</desc>
|
---|
15862 | </param>
|
---|
15863 | <param name="event" type="IEvent" dir="in">
|
---|
15864 | <desc>Which event.</desc>
|
---|
15865 | </param>
|
---|
15866 | </method>
|
---|
15867 |
|
---|
15868 | </interface>
|
---|
15869 |
|
---|
15870 | <interface
|
---|
15871 | name="IEventListener" extends="$unknown"
|
---|
15872 | uuid="67099191-32e7-4f6c-85ee-422304c71b90"
|
---|
15873 | wsmap="managed"
|
---|
15874 | >
|
---|
15875 | <desc>
|
---|
15876 | Event listener. An event listener can work in either active or passive mode, depending on the way
|
---|
15877 | it was registered.
|
---|
15878 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
15879 | </desc>
|
---|
15880 |
|
---|
15881 | <method name="handleEvent">
|
---|
15882 | <desc>
|
---|
15883 | Handle event callback for active listeners. It is not called for passive listeners. After
|
---|
15884 | calling handleEvent() on all active listeners and having received acknowledgement from all
|
---|
15885 | passive listeners via IEventSource::eventProcessed(), the event is marked as processed and
|
---|
15886 | IEvent::waitProcessed() will return immediately.
|
---|
15887 | </desc>
|
---|
15888 | <param name="event" type="IEvent" dir="in">
|
---|
15889 | <desc>Event available.</desc>
|
---|
15890 | </param>
|
---|
15891 | </method>
|
---|
15892 |
|
---|
15893 | </interface>
|
---|
15894 |
|
---|
15895 | <interface
|
---|
15896 | name="IEvent" extends="$unknown"
|
---|
15897 | uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
|
---|
15898 | wsmap="managed"
|
---|
15899 | >
|
---|
15900 | <desc>
|
---|
15901 | Abstract parent interface for VirtualBox events. Actual events will typically implement
|
---|
15902 | a more specific interface which derives from this (see below).
|
---|
15903 |
|
---|
15904 | <b>Introduction to VirtualBox events</b>
|
---|
15905 |
|
---|
15906 | Generally speaking, an event (represented by this interface) signals that something
|
---|
15907 | happened, while an event listener (see <link to="IEventListener" />) represents an
|
---|
15908 | entity that is interested in certain events. In order for this to work with
|
---|
15909 | unidirectional protocols (i.e. web services), the concepts of passive and active
|
---|
15910 | listener are used.
|
---|
15911 |
|
---|
15912 | Event consumers can register themselves as listeners, providing an array of
|
---|
15913 | events they are interested in (see <link to="IEventSource::registerListener" />).
|
---|
15914 | When an event triggers, the listener is notified about the event. The exact
|
---|
15915 | mechanism of the notification depends on whether the listener was registered as
|
---|
15916 | an active or passive listener:
|
---|
15917 |
|
---|
15918 | <ul>
|
---|
15919 | <li>An active listener is very similar to a callback: it is a function invoked
|
---|
15920 | by the API. As opposed to the callbacks that were used in the API before
|
---|
15921 | VirtualBox 4.0 however, events are now objects with an interface hierarchy.
|
---|
15922 | </li>
|
---|
15923 |
|
---|
15924 | <li>Passive listeners are somewhat trickier to implement, but do not require
|
---|
15925 | a client function to be callable, which is not an option with scripting
|
---|
15926 | languages or web service clients. Internally the <link to="IEventSource" />
|
---|
15927 | implementation maintains an event queue for each passive listener, and
|
---|
15928 | newly arrived events are put in this queue. When the listener calls
|
---|
15929 | <link to="IEventSource::getEvent"/>, first element from its internal event
|
---|
15930 | queue is returned. When the client completes processing of an event,
|
---|
15931 | the <link to="IEventSource::eventProcessed" /> function must be called,
|
---|
15932 | acknowledging that the event was processed. It supports implementing
|
---|
15933 | waitable events. On passive listener unregistration, all events from its
|
---|
15934 | queue are auto-acknowledged.
|
---|
15935 | </li>
|
---|
15936 | </ul>
|
---|
15937 |
|
---|
15938 | Waitable events are useful in situations where the event generator wants to track
|
---|
15939 | delivery or a party wants to wait until all listeners have completed the event. A
|
---|
15940 | typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
|
---|
15941 | listeners might veto a certain action, and thus the event producer has to make
|
---|
15942 | sure that all listeners have processed the event and not vetoed before taking
|
---|
15943 | the action.
|
---|
15944 |
|
---|
15945 | A given event may have both passive and active listeners at the same time.
|
---|
15946 |
|
---|
15947 | <b>Using events</b>
|
---|
15948 |
|
---|
15949 | Any VirtualBox object capable of producing externally visible events provides an
|
---|
15950 | @c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
|
---|
15951 | This event source object is notified by VirtualBox once something has happened, so
|
---|
15952 | consumers may register event listeners with this event source. To register a listener,
|
---|
15953 | an object implementing the <link to="IEventListener" /> interface must be provided.
|
---|
15954 | For active listeners, such an object is typically created by the consumer, while for
|
---|
15955 | passive listeners <link to="IEventSource::createListener" /> should be used. Please
|
---|
15956 | note that a listener created with @c createListener() must not be used as an active listener.
|
---|
15957 |
|
---|
15958 | Once created, the listener must be registered to listen for the desired events
|
---|
15959 | (see <link to="IEventSource::registerListener" />), providing an array of
|
---|
15960 | <link to="VBoxEventType" /> enums. Those elements can either be the individual
|
---|
15961 | event IDs or wildcards matching multiple event IDs.
|
---|
15962 |
|
---|
15963 | After registration, the callback's <link to="IEventListener::handleEvent" /> method is
|
---|
15964 | called automatically when the event is triggered, while passive listeners have to call
|
---|
15965 | <link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
|
---|
15966 | an event processing loop.
|
---|
15967 |
|
---|
15968 | The IEvent interface is an abstract parent interface for all such VirtualBox events
|
---|
15969 | coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
|
---|
15970 | or the event processing loop is to check the <link to="#type" /> attribute of the event and
|
---|
15971 | then cast to the appropriate specific interface using @c QueryInterface().
|
---|
15972 | </desc>
|
---|
15973 |
|
---|
15974 | <attribute name="type" readonly="yes" type="VBoxEventType">
|
---|
15975 | <desc>
|
---|
15976 | Event type.
|
---|
15977 | </desc>
|
---|
15978 | </attribute>
|
---|
15979 |
|
---|
15980 | <attribute name="source" readonly="yes" type="IEventSource">
|
---|
15981 | <desc>
|
---|
15982 | Source of this event.
|
---|
15983 | </desc>
|
---|
15984 | </attribute>
|
---|
15985 |
|
---|
15986 | <attribute name="waitable" readonly="yes" type="boolean">
|
---|
15987 | <desc>
|
---|
15988 | If we can wait for this event being processed. If false, waitProcessed() returns immediately,
|
---|
15989 | and setProcessed() doesn't make sense. Non-waitable events are generally better performing,
|
---|
15990 | as no additional overhead associated with waitability imposed.
|
---|
15991 | Waitable events are needed when one need to be able to wait for particular event processed,
|
---|
15992 | for example for vetoable changes, or if event refers to some resource which need to be kept immutable
|
---|
15993 | until all consumers confirmed events.
|
---|
15994 | </desc>
|
---|
15995 | </attribute>
|
---|
15996 |
|
---|
15997 | <method name="setProcessed">
|
---|
15998 | <desc>
|
---|
15999 | Internal method called by the system when all listeners of a particular event have called
|
---|
16000 | <link to="IEventSource::eventProcessed" />. This should not be called by client code.
|
---|
16001 | </desc>
|
---|
16002 | </method>
|
---|
16003 |
|
---|
16004 | <method name="waitProcessed">
|
---|
16005 | <desc>
|
---|
16006 | Wait until time outs, or this event is processed. Event must be waitable for this operation to have
|
---|
16007 | described semantics, for non-waitable returns true immediately.
|
---|
16008 | </desc>
|
---|
16009 | <param name="timeout" type="long" dir="in">
|
---|
16010 | <desc>
|
---|
16011 | Maximum time to wait for event processeing, in ms;
|
---|
16012 | 0 = no wait, -1 = indefinite wait.
|
---|
16013 | </desc>
|
---|
16014 | </param>
|
---|
16015 | <param name="result" type="boolean" dir="return">
|
---|
16016 | <desc>If this event was processed before timeout.</desc>
|
---|
16017 | </param>
|
---|
16018 | </method>
|
---|
16019 | </interface>
|
---|
16020 |
|
---|
16021 |
|
---|
16022 | <interface
|
---|
16023 | name="IReusableEvent" extends="IEvent"
|
---|
16024 | uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
|
---|
16025 | wsmap="managed"
|
---|
16026 | >
|
---|
16027 | <desc>Base abstract interface for all reusable events.</desc>
|
---|
16028 |
|
---|
16029 | <attribute name="generation" readonly="yes" type="unsigned long">
|
---|
16030 | <desc>Current generation of event, incremented on reuse.</desc>
|
---|
16031 | </attribute>
|
---|
16032 |
|
---|
16033 | <method name="reuse">
|
---|
16034 | <desc>
|
---|
16035 | Marks an event as reused, increments 'generation', fields shall no
|
---|
16036 | longer be considered valid.
|
---|
16037 | </desc>
|
---|
16038 | </method>
|
---|
16039 | </interface>
|
---|
16040 |
|
---|
16041 | <interface
|
---|
16042 | name="IMachineEvent" extends="IEvent"
|
---|
16043 | uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
|
---|
16044 | wsmap="managed" id="MachineEvent"
|
---|
16045 | >
|
---|
16046 | <desc>Base abstract interface for all machine events.</desc>
|
---|
16047 |
|
---|
16048 | <attribute name="machineId" readonly="yes" type="uuid" mod="string">
|
---|
16049 | <desc>ID of the machine this event relates to.</desc>
|
---|
16050 | </attribute>
|
---|
16051 |
|
---|
16052 | </interface>
|
---|
16053 |
|
---|
16054 | <interface
|
---|
16055 | name="IMachineStateChangedEvent" extends="IMachineEvent"
|
---|
16056 | uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
|
---|
16057 | wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
|
---|
16058 | >
|
---|
16059 | <desc>Machine state change event.</desc>
|
---|
16060 |
|
---|
16061 | <attribute name="state" readonly="yes" type="MachineState">
|
---|
16062 | <desc>New execution state.</desc>
|
---|
16063 | </attribute>
|
---|
16064 | </interface>
|
---|
16065 |
|
---|
16066 | <interface
|
---|
16067 | name="IMachineDataChangedEvent" extends="IMachineEvent"
|
---|
16068 | uuid="6AA70A6C-0DCA-4810-8C5C-457B278E3D49"
|
---|
16069 | wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
|
---|
16070 | >
|
---|
16071 | <desc>
|
---|
16072 | Any of the settings of the given machine has changed.
|
---|
16073 | </desc>
|
---|
16074 | </interface>
|
---|
16075 |
|
---|
16076 | <interface
|
---|
16077 | name="IMediumRegisteredEvent" extends="IEvent"
|
---|
16078 | uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
|
---|
16079 | wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
|
---|
16080 | >
|
---|
16081 | <desc>
|
---|
16082 | The given medium was registered or unregistered
|
---|
16083 | within this VirtualBox installation.
|
---|
16084 | </desc>
|
---|
16085 |
|
---|
16086 | <attribute name="mediumId" readonly="yes" type="uuid" mod="string">
|
---|
16087 | <desc>ID of the medium this event relates to.</desc>
|
---|
16088 | </attribute>
|
---|
16089 |
|
---|
16090 | <attribute name="mediumType" readonly="yes" type="DeviceType">
|
---|
16091 | <desc>Type of the medium this event relates to.</desc>
|
---|
16092 | </attribute>
|
---|
16093 |
|
---|
16094 | <attribute name="registered" type="boolean" readonly="yes">
|
---|
16095 | <desc>
|
---|
16096 | If @c true, the medium was registered, otherwise it was
|
---|
16097 | unregistered.
|
---|
16098 | </desc>
|
---|
16099 | </attribute>
|
---|
16100 | </interface>
|
---|
16101 |
|
---|
16102 | <interface
|
---|
16103 | name="IMachineRegisteredEvent" extends="IMachineEvent"
|
---|
16104 | uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
|
---|
16105 | wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
|
---|
16106 | >
|
---|
16107 | <desc>
|
---|
16108 | The given machine was registered or unregistered
|
---|
16109 | within this VirtualBox installation.
|
---|
16110 | </desc>
|
---|
16111 |
|
---|
16112 | <attribute name="registered" type="boolean" readonly="yes">
|
---|
16113 | <desc>
|
---|
16114 | If @c true, the machine was registered, otherwise it was
|
---|
16115 | unregistered.
|
---|
16116 | </desc>
|
---|
16117 | </attribute>
|
---|
16118 | </interface>
|
---|
16119 |
|
---|
16120 | <interface
|
---|
16121 | name="ISessionStateChangedEvent" extends="IMachineEvent"
|
---|
16122 | uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
|
---|
16123 | wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
|
---|
16124 | >
|
---|
16125 | <desc>
|
---|
16126 | The state of the session for the given machine was changed.
|
---|
16127 | <see>IMachine::sessionState</see>
|
---|
16128 | </desc>
|
---|
16129 |
|
---|
16130 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
16131 | <desc>
|
---|
16132 | New session state.
|
---|
16133 | </desc>
|
---|
16134 | </attribute>
|
---|
16135 | </interface>
|
---|
16136 |
|
---|
16137 | <interface
|
---|
16138 | name="IGuestPropertyChangedEvent" extends="IMachineEvent"
|
---|
16139 | uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
|
---|
16140 | wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
|
---|
16141 | >
|
---|
16142 | <desc>
|
---|
16143 | Notification when a guest property has changed.
|
---|
16144 | </desc>
|
---|
16145 |
|
---|
16146 | <attribute name="name" readonly="yes" type="wstring">
|
---|
16147 | <desc>
|
---|
16148 | The name of the property that has changed.
|
---|
16149 | </desc>
|
---|
16150 | </attribute>
|
---|
16151 |
|
---|
16152 | <attribute name="value" readonly="yes" type="wstring">
|
---|
16153 | <desc>
|
---|
16154 | The new property value.
|
---|
16155 | </desc>
|
---|
16156 | </attribute>
|
---|
16157 |
|
---|
16158 | <attribute name="flags" readonly="yes" type="wstring">
|
---|
16159 | <desc>
|
---|
16160 | The new property flags.
|
---|
16161 | </desc>
|
---|
16162 | </attribute>
|
---|
16163 |
|
---|
16164 | </interface>
|
---|
16165 |
|
---|
16166 | <interface
|
---|
16167 | name="ISnapshotEvent" extends="IMachineEvent"
|
---|
16168 | uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
|
---|
16169 | wsmap="managed" id="SnapshotEvent"
|
---|
16170 | >
|
---|
16171 | <desc>Base interface for all snapshot events.</desc>
|
---|
16172 |
|
---|
16173 | <attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
|
---|
16174 | <desc>ID of the snapshot this event relates to.</desc>
|
---|
16175 | </attribute>
|
---|
16176 |
|
---|
16177 | </interface>
|
---|
16178 |
|
---|
16179 | <interface
|
---|
16180 | name="ISnapshotTakenEvent" extends="ISnapshotEvent"
|
---|
16181 | uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
|
---|
16182 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
|
---|
16183 | >
|
---|
16184 | <desc>
|
---|
16185 | A new snapshot of the machine has been taken.
|
---|
16186 | <see>ISnapshot</see>
|
---|
16187 | </desc>
|
---|
16188 | </interface>
|
---|
16189 |
|
---|
16190 | <interface
|
---|
16191 | name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
|
---|
16192 | uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
|
---|
16193 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
|
---|
16194 | >
|
---|
16195 | <desc>
|
---|
16196 | Snapshot of the given machine has been deleted.
|
---|
16197 |
|
---|
16198 | <note>
|
---|
16199 | This notification is delivered <b>after</b> the snapshot
|
---|
16200 | object has been uninitialized on the server (so that any
|
---|
16201 | attempt to call its methods will return an error).
|
---|
16202 | </note>
|
---|
16203 |
|
---|
16204 | <see>ISnapshot</see>
|
---|
16205 | </desc>
|
---|
16206 | </interface>
|
---|
16207 |
|
---|
16208 | <interface
|
---|
16209 | name="ISnapshotChangedEvent" extends="ISnapshotEvent"
|
---|
16210 | uuid="07541941-8079-447a-a33e-47a69c7980db"
|
---|
16211 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
|
---|
16212 | >
|
---|
16213 | <desc>
|
---|
16214 | Snapshot properties (name and/or description) have been changed.
|
---|
16215 | <see>ISnapshot</see>
|
---|
16216 | </desc>
|
---|
16217 | </interface>
|
---|
16218 |
|
---|
16219 | <interface
|
---|
16220 | name="IMousePointerShapeChangedEvent" extends="IEvent"
|
---|
16221 | uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
|
---|
16222 | wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
|
---|
16223 | >
|
---|
16224 | <desc>
|
---|
16225 | Notification when the guest mouse pointer shape has
|
---|
16226 | changed. The new shape data is given.
|
---|
16227 | </desc>
|
---|
16228 |
|
---|
16229 | <attribute name="visible" type="boolean" readonly="yes">
|
---|
16230 | <desc>
|
---|
16231 | Flag whether the pointer is visible.
|
---|
16232 | </desc>
|
---|
16233 | </attribute>
|
---|
16234 | <attribute name="alpha" type="boolean" readonly="yes">
|
---|
16235 | <desc>
|
---|
16236 | Flag whether the pointer has an alpha channel.
|
---|
16237 | </desc>
|
---|
16238 | </attribute>
|
---|
16239 | <attribute name="xhot" type="unsigned long" readonly="yes">
|
---|
16240 | <desc>
|
---|
16241 | The pointer hot spot X coordinate.
|
---|
16242 | </desc>
|
---|
16243 | </attribute>
|
---|
16244 | <attribute name="yhot" type="unsigned long" readonly="yes">
|
---|
16245 | <desc>
|
---|
16246 | The pointer hot spot Y coordinate.
|
---|
16247 | </desc>
|
---|
16248 | </attribute>
|
---|
16249 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
16250 | <desc>
|
---|
16251 | Width of the pointer shape in pixels.
|
---|
16252 | </desc>
|
---|
16253 | </attribute>
|
---|
16254 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
16255 | <desc>
|
---|
16256 | Height of the pointer shape in pixels.
|
---|
16257 | </desc>
|
---|
16258 | </attribute>
|
---|
16259 | <attribute name="shape" type="octet" safearray="yes" readonly="yes">
|
---|
16260 | <desc>
|
---|
16261 | Shape buffer arrays.
|
---|
16262 |
|
---|
16263 | The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
|
---|
16264 | followed by a 32-bpp XOR (color) mask.
|
---|
16265 |
|
---|
16266 | For pointers without alpha channel the XOR mask pixels are 32
|
---|
16267 | bit values: (lsb)BGR0(msb). For pointers with alpha channel
|
---|
16268 | the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
|
---|
16269 |
|
---|
16270 | An AND mask is used for pointers with alpha channel, so if the
|
---|
16271 | callback does not support alpha, the pointer could be
|
---|
16272 | displayed as a normal color pointer.
|
---|
16273 |
|
---|
16274 | The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
|
---|
16275 | size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
|
---|
16276 | height</tt>. The padding bits at the end of each scanline are
|
---|
16277 | undefined.
|
---|
16278 |
|
---|
16279 | The XOR mask follows the AND mask on the next 4-byte aligned
|
---|
16280 | offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
|
---|
16281 | Bytes in the gap between the AND and the XOR mask are undefined.
|
---|
16282 | The XOR mask scanlines have no gap between them and the size of
|
---|
16283 | the XOR mask is: <tt>cXor = width * 4 * height</tt>.
|
---|
16284 |
|
---|
16285 | <note>
|
---|
16286 | If @a shape is 0, only the pointer visibility is changed.
|
---|
16287 | </note>
|
---|
16288 | </desc>
|
---|
16289 | </attribute>
|
---|
16290 | </interface>
|
---|
16291 |
|
---|
16292 | <interface
|
---|
16293 | name="IMouseCapabilityChangedEvent" extends="IEvent"
|
---|
16294 | uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
|
---|
16295 | wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
|
---|
16296 | >
|
---|
16297 | <desc>
|
---|
16298 | Notification when the mouse capabilities reported by the
|
---|
16299 | guest have changed. The new capabilities are passed.
|
---|
16300 | </desc>
|
---|
16301 | <attribute name="supportsAbsolute" type="boolean" readonly="yes">
|
---|
16302 | <desc>
|
---|
16303 | Supports absolute coordinates.
|
---|
16304 | </desc>
|
---|
16305 | </attribute>
|
---|
16306 | <attribute name="supportsRelative" type="boolean" readonly="yes">
|
---|
16307 | <desc>
|
---|
16308 | Supports relative coordinates.
|
---|
16309 | </desc>
|
---|
16310 | </attribute>
|
---|
16311 | <attribute name="needsHostCursor" type="boolean" readonly="yes">
|
---|
16312 | <desc>
|
---|
16313 | If host cursor is needed.
|
---|
16314 | </desc>
|
---|
16315 | </attribute>
|
---|
16316 | </interface>
|
---|
16317 |
|
---|
16318 | <interface
|
---|
16319 | name="IKeyboardLedsChangedEvent" extends="IEvent"
|
---|
16320 | uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
|
---|
16321 | wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
|
---|
16322 | >
|
---|
16323 | <desc>
|
---|
16324 | Notification when the guest OS executes the KBD_CMD_SET_LEDS command
|
---|
16325 | to alter the state of the keyboard LEDs.
|
---|
16326 | </desc>
|
---|
16327 | <attribute name="numLock" type="boolean" readonly="yes">
|
---|
16328 | <desc>
|
---|
16329 | NumLock status.
|
---|
16330 | </desc>
|
---|
16331 | </attribute>
|
---|
16332 | <attribute name="capsLock" type="boolean" readonly="yes">
|
---|
16333 | <desc>
|
---|
16334 | CapsLock status.
|
---|
16335 | </desc>
|
---|
16336 | </attribute>
|
---|
16337 | <attribute name="scrollLock" type="boolean" readonly="yes">
|
---|
16338 | <desc>
|
---|
16339 | ScrollLock status.
|
---|
16340 | </desc>
|
---|
16341 | </attribute>
|
---|
16342 | </interface>
|
---|
16343 |
|
---|
16344 | <interface
|
---|
16345 | name="IStateChangedEvent" extends="IEvent"
|
---|
16346 | uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
|
---|
16347 | wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
|
---|
16348 | >
|
---|
16349 | <desc>
|
---|
16350 | Notification when the execution state of the machine has changed.
|
---|
16351 | The new state is given.
|
---|
16352 | </desc>
|
---|
16353 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
16354 | <desc>
|
---|
16355 | New machine state.
|
---|
16356 | </desc>
|
---|
16357 | </attribute>
|
---|
16358 | </interface>
|
---|
16359 |
|
---|
16360 | <interface
|
---|
16361 | name="IAdditionsStateChangedEvent" extends="IEvent"
|
---|
16362 | uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
|
---|
16363 | wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
|
---|
16364 | >
|
---|
16365 | <desc>
|
---|
16366 | Notification when a Guest Additions property changes.
|
---|
16367 | Interested callees should query IGuest attributes to
|
---|
16368 | find out what has changed.
|
---|
16369 | </desc>
|
---|
16370 | </interface>
|
---|
16371 |
|
---|
16372 | <interface
|
---|
16373 | name="INetworkAdapterChangedEvent" extends="IEvent"
|
---|
16374 | uuid="08889892-1EC6-4883-801D-77F56CFD0103"
|
---|
16375 | wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
|
---|
16376 | >
|
---|
16377 | <desc>
|
---|
16378 | Notification when a property of one of the
|
---|
16379 | virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
|
---|
16380 | changes. Interested callees should use INetworkAdapter methods and
|
---|
16381 | attributes to find out what has changed.
|
---|
16382 | </desc>
|
---|
16383 | <attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
|
---|
16384 | <desc>
|
---|
16385 | Network adapter that is subject to change.
|
---|
16386 | </desc>
|
---|
16387 | </attribute>
|
---|
16388 | </interface>
|
---|
16389 |
|
---|
16390 | <interface
|
---|
16391 | name="ISerialPortChangedEvent" extends="IEvent"
|
---|
16392 | uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
|
---|
16393 | wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
|
---|
16394 | >
|
---|
16395 | <desc>
|
---|
16396 | Notification when a property of one of the
|
---|
16397 | virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
|
---|
16398 | Interested callees should use ISerialPort methods and attributes
|
---|
16399 | to find out what has changed.
|
---|
16400 | </desc>
|
---|
16401 | <attribute name="serialPort" type="ISerialPort" readonly="yes">
|
---|
16402 | <desc>
|
---|
16403 | Serial port that is subject to change.
|
---|
16404 | </desc>
|
---|
16405 | </attribute>
|
---|
16406 | </interface>
|
---|
16407 |
|
---|
16408 | <interface
|
---|
16409 | name="IParallelPortChangedEvent" extends="IEvent"
|
---|
16410 | uuid="813C99FC-9849-4F47-813E-24A75DC85615"
|
---|
16411 | wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
|
---|
16412 | >
|
---|
16413 | <desc>
|
---|
16414 | Notification when a property of one of the
|
---|
16415 | virtual <link to="IMachine::getParallelPort">parallel ports</link>
|
---|
16416 | changes. Interested callees should use ISerialPort methods and
|
---|
16417 | attributes to find out what has changed.
|
---|
16418 | </desc>
|
---|
16419 | <attribute name="parallelPort" type="IParallelPort" readonly="yes">
|
---|
16420 | <desc>
|
---|
16421 | Parallel port that is subject to change.
|
---|
16422 | </desc>
|
---|
16423 | </attribute>
|
---|
16424 | </interface>
|
---|
16425 |
|
---|
16426 | <interface
|
---|
16427 | name="IStorageControllerChangedEvent" extends="IEvent"
|
---|
16428 | uuid="715212BF-DA59-426E-8230-3831FAA52C56"
|
---|
16429 | wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
|
---|
16430 | >
|
---|
16431 | <desc>
|
---|
16432 | Notification when a
|
---|
16433 | <link to="IMachine::mediumAttachments">medium attachment</link>
|
---|
16434 | changes.
|
---|
16435 | </desc>
|
---|
16436 | </interface>
|
---|
16437 |
|
---|
16438 | <interface
|
---|
16439 | name="IMediumChangedEvent" extends="IEvent"
|
---|
16440 | uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
|
---|
16441 | wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
|
---|
16442 | >
|
---|
16443 | <desc>
|
---|
16444 | Notification when a
|
---|
16445 | <link to="IMachine::mediumAttachments">medium attachment</link>
|
---|
16446 | changes.
|
---|
16447 | </desc>
|
---|
16448 | <attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
|
---|
16449 | <desc>
|
---|
16450 | Medium attachment that is subject to change.
|
---|
16451 | </desc>
|
---|
16452 | </attribute>
|
---|
16453 | </interface>
|
---|
16454 |
|
---|
16455 | <interface
|
---|
16456 | name="ICPUChangedEvent" extends="IEvent"
|
---|
16457 | uuid="D0F0BECC-EE17-4D17-A8CC-383B0EB55E9D"
|
---|
16458 | wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
|
---|
16459 | >
|
---|
16460 | <desc>
|
---|
16461 | Notification when a CPU changes.
|
---|
16462 | </desc>
|
---|
16463 | <attribute name="cpu" type="unsigned long" readonly="yes">
|
---|
16464 | <desc>
|
---|
16465 | The CPU which changed.
|
---|
16466 | </desc>
|
---|
16467 | </attribute>
|
---|
16468 | <attribute name="add" type="boolean" readonly="yes">
|
---|
16469 | <desc>
|
---|
16470 | Flag whether the CPU was added or removed.
|
---|
16471 | </desc>
|
---|
16472 | </attribute>
|
---|
16473 | </interface>
|
---|
16474 |
|
---|
16475 | <interface
|
---|
16476 | name="ICPUExecutionCapChangedEvent" extends="IEvent"
|
---|
16477 | uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
|
---|
16478 | wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
|
---|
16479 | >
|
---|
16480 | <desc>
|
---|
16481 | Notification when the CPU execution cap changes.
|
---|
16482 | </desc>
|
---|
16483 | <attribute name="executionCap" type="unsigned long" readonly="yes">
|
---|
16484 | <desc>
|
---|
16485 | The new CPU execution cap value. (1-100)
|
---|
16486 | </desc>
|
---|
16487 | </attribute>
|
---|
16488 | </interface>
|
---|
16489 |
|
---|
16490 | <interface
|
---|
16491 | name="IGuestKeyboardEvent" extends="IEvent"
|
---|
16492 | uuid="88394258-7006-40d4-b339-472ee3801844"
|
---|
16493 | wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboard"
|
---|
16494 | >
|
---|
16495 | <desc>
|
---|
16496 | Notification when guest keyboard event happens.
|
---|
16497 | </desc>
|
---|
16498 | <attribute name="scancodes" type="long" safearray="yes" readonly="yes">
|
---|
16499 | <desc>
|
---|
16500 | Array of scancodes.
|
---|
16501 | </desc>
|
---|
16502 | </attribute>
|
---|
16503 | </interface>
|
---|
16504 |
|
---|
16505 | <interface
|
---|
16506 | name="IGuestMouseEvent" extends="IReusableEvent"
|
---|
16507 | uuid="1f85d35c-c524-40ff-8e98-307000df0992"
|
---|
16508 | wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse"
|
---|
16509 | >
|
---|
16510 | <desc>
|
---|
16511 | Notification when guest mouse event happens.
|
---|
16512 | </desc>
|
---|
16513 |
|
---|
16514 | <attribute name="absolute" type="boolean" readonly="yes">
|
---|
16515 | <desc>
|
---|
16516 | If this event is relative or absolute.
|
---|
16517 | </desc>
|
---|
16518 | </attribute>
|
---|
16519 |
|
---|
16520 | <attribute name="x" type="long" readonly="yes">
|
---|
16521 | <desc>
|
---|
16522 | New X position, or X delta.
|
---|
16523 | </desc>
|
---|
16524 | </attribute>
|
---|
16525 |
|
---|
16526 | <attribute name="y" type="long" readonly="yes">
|
---|
16527 | <desc>
|
---|
16528 | New Y position, or Y delta.
|
---|
16529 | </desc>
|
---|
16530 | </attribute>
|
---|
16531 |
|
---|
16532 | <attribute name="z" type="long" readonly="yes">
|
---|
16533 | <desc>
|
---|
16534 | Z delta.
|
---|
16535 | </desc>
|
---|
16536 | </attribute>
|
---|
16537 |
|
---|
16538 | <attribute name="w" type="long" readonly="yes">
|
---|
16539 | <desc>
|
---|
16540 | W delta.
|
---|
16541 | </desc>
|
---|
16542 | </attribute>
|
---|
16543 |
|
---|
16544 | <attribute name="buttons" type="long" readonly="yes">
|
---|
16545 | <desc>
|
---|
16546 | Button state bitmask.
|
---|
16547 | </desc>
|
---|
16548 | </attribute>
|
---|
16549 |
|
---|
16550 | </interface>
|
---|
16551 |
|
---|
16552 |
|
---|
16553 | <interface
|
---|
16554 | name="IVRDEServerChangedEvent" extends="IEvent"
|
---|
16555 | uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
|
---|
16556 | wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
|
---|
16557 | >
|
---|
16558 | <desc>
|
---|
16559 | Notification when a property of the
|
---|
16560 | <link to="IMachine::VRDEServer">VRDE server</link> changes.
|
---|
16561 | Interested callees should use IVRDEServer methods and attributes to
|
---|
16562 | find out what has changed.
|
---|
16563 | </desc>
|
---|
16564 | </interface>
|
---|
16565 |
|
---|
16566 | <interface
|
---|
16567 | name="IVRDEServerInfoChangedEvent" extends="IEvent"
|
---|
16568 | uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
|
---|
16569 | wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
|
---|
16570 | >
|
---|
16571 | <desc>
|
---|
16572 | Notification when the status of the VRDE server changes. Interested callees
|
---|
16573 | should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
|
---|
16574 | attributes to find out what is the current status.
|
---|
16575 | </desc>
|
---|
16576 | </interface>
|
---|
16577 |
|
---|
16578 | <interface
|
---|
16579 | name="IUSBControllerChangedEvent" extends="IEvent"
|
---|
16580 | uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
|
---|
16581 | wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
|
---|
16582 | >
|
---|
16583 | <desc>
|
---|
16584 | Notification when a property of the virtual
|
---|
16585 | <link to="IMachine::USBController">USB controller</link> changes.
|
---|
16586 | Interested callees should use IUSBController methods and attributes to
|
---|
16587 | find out what has changed.
|
---|
16588 | </desc>
|
---|
16589 | </interface>
|
---|
16590 |
|
---|
16591 | <interface
|
---|
16592 | name="IUSBDeviceStateChangedEvent" extends="IEvent"
|
---|
16593 | uuid="806da61b-6679-422a-b629-51b06b0c6d93"
|
---|
16594 | wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
|
---|
16595 | >
|
---|
16596 | <desc>
|
---|
16597 | Notification when a USB device is attached to or detached from
|
---|
16598 | the virtual USB controller.
|
---|
16599 |
|
---|
16600 | This notification is sent as a result of the indirect
|
---|
16601 | request to attach the device because it matches one of the
|
---|
16602 | machine USB filters, or as a result of the direct request
|
---|
16603 | issued by <link to="IConsole::attachUSBDevice"/> or
|
---|
16604 | <link to="IConsole::detachUSBDevice"/>.
|
---|
16605 |
|
---|
16606 | This notification is sent in case of both a succeeded and a
|
---|
16607 | failed request completion. When the request succeeds, the
|
---|
16608 | @a error parameter is @c null, and the given device has been
|
---|
16609 | already added to (when @a attached is @c true) or removed from
|
---|
16610 | (when @a attached is @c false) the collection represented by
|
---|
16611 | <link to="IConsole::USBDevices"/>. On failure, the collection
|
---|
16612 | doesn't change and the @a error parameter represents the error
|
---|
16613 | message describing the failure.
|
---|
16614 | </desc>
|
---|
16615 | <attribute name="device" type="IUSBDevice" readonly="yes">
|
---|
16616 | <desc>
|
---|
16617 | Device that is subject to state change.
|
---|
16618 | </desc>
|
---|
16619 | </attribute>
|
---|
16620 | <attribute name="attached" type="boolean" readonly="yes">
|
---|
16621 | <desc>
|
---|
16622 | @c true if the device was attached and @c false otherwise.
|
---|
16623 | </desc>
|
---|
16624 | </attribute>
|
---|
16625 | <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
16626 | <desc>
|
---|
16627 | @c null on success or an error message object on failure.
|
---|
16628 | </desc>
|
---|
16629 | </attribute>
|
---|
16630 | </interface>
|
---|
16631 |
|
---|
16632 | <interface
|
---|
16633 | name="ISharedFolderChangedEvent" extends="IEvent"
|
---|
16634 | uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
|
---|
16635 | wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
|
---|
16636 | >
|
---|
16637 | <desc>
|
---|
16638 | Notification when a shared folder is added or removed.
|
---|
16639 | The @a scope argument defines one of three scopes:
|
---|
16640 | <link to="IVirtualBox::sharedFolders">global shared folders</link>
|
---|
16641 | (<link to="Scope_Global">Global</link>),
|
---|
16642 | <link to="IMachine::sharedFolders">permanent shared folders</link> of
|
---|
16643 | the machine (<link to="Scope_Machine">Machine</link>) or <link
|
---|
16644 | to="IConsole::sharedFolders">transient shared folders</link> of the
|
---|
16645 | machine (<link to="Scope_Session">Session</link>). Interested callees
|
---|
16646 | should use query the corresponding collections to find out what has
|
---|
16647 | changed.
|
---|
16648 | </desc>
|
---|
16649 | <attribute name="scope" type="Scope" readonly="yes">
|
---|
16650 | <desc>
|
---|
16651 | Scope of the notification.
|
---|
16652 | </desc>
|
---|
16653 | </attribute>
|
---|
16654 | </interface>
|
---|
16655 |
|
---|
16656 | <interface
|
---|
16657 | name="IRuntimeErrorEvent" extends="IEvent"
|
---|
16658 | uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
|
---|
16659 | wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
|
---|
16660 | >
|
---|
16661 | <desc>
|
---|
16662 | Notification when an error happens during the virtual
|
---|
16663 | machine execution.
|
---|
16664 |
|
---|
16665 | There are three kinds of runtime errors:
|
---|
16666 | <ul>
|
---|
16667 | <li><i>fatal</i></li>
|
---|
16668 | <li><i>non-fatal with retry</i></li>
|
---|
16669 | <li><i>non-fatal warnings</i></li>
|
---|
16670 | </ul>
|
---|
16671 |
|
---|
16672 | <b>Fatal</b> errors are indicated by the @a fatal parameter set
|
---|
16673 | to @c true. In case of fatal errors, the virtual machine
|
---|
16674 | execution is always paused before calling this notification, and
|
---|
16675 | the notification handler is supposed either to immediately save
|
---|
16676 | the virtual machine state using <link to="IConsole::saveState"/>
|
---|
16677 | or power it off using <link to="IConsole::powerDown"/>.
|
---|
16678 | Resuming the execution can lead to unpredictable results.
|
---|
16679 |
|
---|
16680 | <b>Non-fatal</b> errors and warnings are indicated by the
|
---|
16681 | @a fatal parameter set to @c false. If the virtual machine
|
---|
16682 | is in the Paused state by the time the error notification is
|
---|
16683 | received, it means that the user can <i>try to resume</i> the machine
|
---|
16684 | execution after attempting to solve the problem that caused the
|
---|
16685 | error. In this case, the notification handler is supposed
|
---|
16686 | to show an appropriate message to the user (depending on the
|
---|
16687 | value of the @a id parameter) that offers several actions such
|
---|
16688 | as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
|
---|
16689 | wants to retry, the notification handler should continue
|
---|
16690 | the machine execution using the <link to="IConsole::resume"/>
|
---|
16691 | call. If the machine execution is not Paused during this
|
---|
16692 | notification, then it means this notification is a <i>warning</i>
|
---|
16693 | (for example, about a fatal condition that can happen very soon);
|
---|
16694 | no immediate action is required from the user, the machine
|
---|
16695 | continues its normal execution.
|
---|
16696 |
|
---|
16697 | Note that in either case the notification handler
|
---|
16698 | <b>must not</b> perform any action directly on a thread
|
---|
16699 | where this notification is called. Everything it is allowed to
|
---|
16700 | do is to post a message to another thread that will then talk
|
---|
16701 | to the user and take the corresponding action.
|
---|
16702 |
|
---|
16703 | Currently, the following error identifiers are known:
|
---|
16704 | <ul>
|
---|
16705 | <li><tt>"HostMemoryLow"</tt></li>
|
---|
16706 | <li><tt>"HostAudioNotResponding"</tt></li>
|
---|
16707 | <li><tt>"VDIStorageFull"</tt></li>
|
---|
16708 | <li><tt>"3DSupportIncompatibleAdditions"</tt></li>
|
---|
16709 | </ul>
|
---|
16710 | </desc>
|
---|
16711 | <attribute name="fatal" type="boolean" readonly="yes">
|
---|
16712 | <desc>
|
---|
16713 | Whether the error is fatal or not.
|
---|
16714 | </desc>
|
---|
16715 | </attribute>
|
---|
16716 | <attribute name="id" type="wstring" readonly="yes">
|
---|
16717 | <desc>
|
---|
16718 | Error identifier.
|
---|
16719 | </desc>
|
---|
16720 | </attribute>
|
---|
16721 | <attribute name="message" type="wstring" readonly="yes">
|
---|
16722 | <desc>
|
---|
16723 | Optional error message.
|
---|
16724 | </desc>
|
---|
16725 | </attribute>
|
---|
16726 | </interface>
|
---|
16727 |
|
---|
16728 |
|
---|
16729 | <interface
|
---|
16730 | name="IEventSourceChangedEvent" extends="IEvent"
|
---|
16731 | uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
|
---|
16732 | waitable="yes"
|
---|
16733 | wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
|
---|
16734 | >
|
---|
16735 | <desc>
|
---|
16736 | Notification when an event source state changes (listener added or removed).
|
---|
16737 | </desc>
|
---|
16738 |
|
---|
16739 | <attribute name="listener" type="IEventListener" readonly="yes">
|
---|
16740 | <desc>
|
---|
16741 | Event listener which has changed.
|
---|
16742 | </desc>
|
---|
16743 | </attribute>
|
---|
16744 |
|
---|
16745 | <attribute name="add" type="boolean" readonly="yes">
|
---|
16746 | <desc>
|
---|
16747 | Flag whether listener was added or removed.
|
---|
16748 | </desc>
|
---|
16749 | </attribute>
|
---|
16750 | </interface>
|
---|
16751 |
|
---|
16752 | <interface
|
---|
16753 | name="IExtraDataChangedEvent" extends="IEvent"
|
---|
16754 | uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
|
---|
16755 | wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
|
---|
16756 | >
|
---|
16757 | <desc>
|
---|
16758 | Notification when machine specific or global extra data
|
---|
16759 | has changed.
|
---|
16760 | </desc>
|
---|
16761 | <attribute name="machineId" type="uuid" mod="string" readonly="yes">
|
---|
16762 | <desc>
|
---|
16763 | ID of the machine this event relates to.
|
---|
16764 | Null for global extra data changes.
|
---|
16765 | </desc>
|
---|
16766 | </attribute>
|
---|
16767 | <attribute name="key" type="wstring" readonly="yes">
|
---|
16768 | <desc>
|
---|
16769 | Extra data key that has changed.
|
---|
16770 | </desc>
|
---|
16771 | </attribute>
|
---|
16772 | <attribute name="value" type="wstring" readonly="yes">
|
---|
16773 | <desc>
|
---|
16774 | Extra data value for the given key.
|
---|
16775 | </desc>
|
---|
16776 | </attribute>
|
---|
16777 | </interface>
|
---|
16778 |
|
---|
16779 | <interface
|
---|
16780 | name="IVetoEvent" extends="IEvent"
|
---|
16781 | uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
|
---|
16782 | wsmap="managed"
|
---|
16783 | >
|
---|
16784 | <desc>Base abstract interface for veto events.</desc>
|
---|
16785 |
|
---|
16786 | <method name="addVeto">
|
---|
16787 | <desc>
|
---|
16788 | Adds a veto on this event.
|
---|
16789 | </desc>
|
---|
16790 | <param name="reason" type="wstring" dir="in">
|
---|
16791 | <desc>
|
---|
16792 | Reason for veto, could be null or empty string.
|
---|
16793 | </desc>
|
---|
16794 | </param>
|
---|
16795 | </method>
|
---|
16796 |
|
---|
16797 | <method name="isVetoed">
|
---|
16798 | <desc>
|
---|
16799 | If this event was vetoed.
|
---|
16800 | </desc>
|
---|
16801 | <param name="result" type="boolean" dir="return">
|
---|
16802 | <desc>
|
---|
16803 | Reason for veto.
|
---|
16804 | </desc>
|
---|
16805 | </param>
|
---|
16806 | </method>
|
---|
16807 |
|
---|
16808 | <method name="getVetos">
|
---|
16809 | <desc>
|
---|
16810 | Current veto reason list, if size is 0 - no veto.
|
---|
16811 | </desc>
|
---|
16812 | <param name="result" type="wstring" dir="return" safearray="yes">
|
---|
16813 | <desc>
|
---|
16814 | Array of reasons for veto provided by different event handlers.
|
---|
16815 | </desc>
|
---|
16816 | </param>
|
---|
16817 | </method>
|
---|
16818 |
|
---|
16819 | </interface>
|
---|
16820 |
|
---|
16821 | <interface
|
---|
16822 | name="IExtraDataCanChangeEvent" extends="IVetoEvent"
|
---|
16823 | uuid="245d88bd-800a-40f8-87a6-170d02249a55"
|
---|
16824 | wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
|
---|
16825 | waitable="true"
|
---|
16826 | >
|
---|
16827 | <desc>
|
---|
16828 | Notification when someone tries to change extra data for
|
---|
16829 | either the given machine or (if @c null) global extra data.
|
---|
16830 | This gives the chance to veto against changes.
|
---|
16831 | </desc>
|
---|
16832 | <attribute name="machineId" type="uuid" mod="string" readonly="yes">
|
---|
16833 | <desc>
|
---|
16834 | ID of the machine this event relates to.
|
---|
16835 | Null for global extra data changes.
|
---|
16836 | </desc>
|
---|
16837 | </attribute>
|
---|
16838 | <attribute name="key" type="wstring" readonly="yes">
|
---|
16839 | <desc>
|
---|
16840 | Extra data key that has changed.
|
---|
16841 | </desc>
|
---|
16842 | </attribute>
|
---|
16843 | <attribute name="value" type="wstring" readonly="yes">
|
---|
16844 | <desc>
|
---|
16845 | Extra data value for the given key.
|
---|
16846 | </desc>
|
---|
16847 | </attribute>
|
---|
16848 | </interface>
|
---|
16849 |
|
---|
16850 | <interface
|
---|
16851 | name="ICanShowWindowEvent" extends="IVetoEvent"
|
---|
16852 | uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
|
---|
16853 | wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
|
---|
16854 | waitable="true"
|
---|
16855 | >
|
---|
16856 | <desc>
|
---|
16857 | Notification when a call to
|
---|
16858 | <link to="IMachine::canShowConsoleWindow"/> is made by a
|
---|
16859 | front-end to check if a subsequent call to
|
---|
16860 | <link to="IMachine::showConsoleWindow"/> can succeed.
|
---|
16861 |
|
---|
16862 | The callee should give an answer appropriate to the current
|
---|
16863 | machine state using event veto. This answer must
|
---|
16864 | remain valid at least until the next
|
---|
16865 | <link to="IConsole::state">machine state</link> change.
|
---|
16866 | </desc>
|
---|
16867 | </interface>
|
---|
16868 |
|
---|
16869 | <interface
|
---|
16870 | name="IShowWindowEvent" extends="IEvent"
|
---|
16871 | uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
|
---|
16872 | wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
|
---|
16873 | waitable="true"
|
---|
16874 | >
|
---|
16875 | <desc>
|
---|
16876 | Notification when a call to
|
---|
16877 | <link to="IMachine::showConsoleWindow"/>
|
---|
16878 | requests the console window to be activated and brought to
|
---|
16879 | foreground on the desktop of the host PC.
|
---|
16880 |
|
---|
16881 | This notification should cause the VM console process to
|
---|
16882 | perform the requested action as described above. If it is
|
---|
16883 | impossible to do it at a time of this notification, this
|
---|
16884 | method should return a failure.
|
---|
16885 |
|
---|
16886 | Note that many modern window managers on many platforms
|
---|
16887 | implement some sort of focus stealing prevention logic, so
|
---|
16888 | that it may be impossible to activate a window without the
|
---|
16889 | help of the currently active application (which is supposedly
|
---|
16890 | an initiator of this notification). In this case, this method
|
---|
16891 | must return a non-zero identifier that represents the
|
---|
16892 | top-level window of the VM console process. The caller, if it
|
---|
16893 | represents a currently active process, is responsible to use
|
---|
16894 | this identifier (in a platform-dependent manner) to perform
|
---|
16895 | actual window activation.
|
---|
16896 |
|
---|
16897 | This method must set @a winId to zero if it has performed all
|
---|
16898 | actions necessary to complete the request and the console
|
---|
16899 | window is now active and in foreground, to indicate that no
|
---|
16900 | further action is required on the caller's side.
|
---|
16901 | </desc>
|
---|
16902 | <attribute name="winId" type="long long">
|
---|
16903 | <desc>
|
---|
16904 | Platform-dependent identifier of the top-level VM console
|
---|
16905 | window, or zero if this method has performed all actions
|
---|
16906 | necessary to implement the <i>show window</i> semantics for
|
---|
16907 | the given platform and/or this VirtualBox front-end.
|
---|
16908 | </desc>
|
---|
16909 | </attribute>
|
---|
16910 | </interface>
|
---|
16911 |
|
---|
16912 | <interface
|
---|
16913 | name="INATRedirectEvent" extends="IMachineEvent"
|
---|
16914 | uuid="57DE97D7-3CBB-42A0-888F-610D5832D16B"
|
---|
16915 | wsmap="managed" autogen="VBoxEvent" id="OnNATRedirect"
|
---|
16916 | >
|
---|
16917 | <desc>
|
---|
16918 | Notification when NAT redirect rule added or removed.
|
---|
16919 | </desc>
|
---|
16920 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
16921 | <desc>
|
---|
16922 | Adapter which NAT attached to.
|
---|
16923 | </desc>
|
---|
16924 | </attribute>
|
---|
16925 | <attribute name="remove" type="boolean" readonly="yes">
|
---|
16926 | <desc>
|
---|
16927 | Whether rule remove or add.
|
---|
16928 | </desc>
|
---|
16929 | </attribute>
|
---|
16930 | <attribute name="name" type="wstring" readonly="yes">
|
---|
16931 | <desc>
|
---|
16932 | Name of the rule.
|
---|
16933 | </desc>
|
---|
16934 | </attribute>
|
---|
16935 | <attribute name="proto" type="NATProtocol" readonly="yes">
|
---|
16936 | <desc>
|
---|
16937 | Protocol (TCP or UDP) of the redirect rule.
|
---|
16938 | </desc>
|
---|
16939 | </attribute>
|
---|
16940 | <attribute name="hostIp" type="wstring" readonly="yes">
|
---|
16941 | <desc>
|
---|
16942 | Host ip address to bind socket on.
|
---|
16943 | </desc>
|
---|
16944 | </attribute>
|
---|
16945 | <attribute name="hostPort" type="long" readonly="yes">
|
---|
16946 | <desc>
|
---|
16947 | Host port to bind socket on.
|
---|
16948 | </desc>
|
---|
16949 | </attribute>
|
---|
16950 | <attribute name="guestIp" type="wstring" readonly="yes">
|
---|
16951 | <desc>
|
---|
16952 | Guest ip address to redirect to.
|
---|
16953 | </desc>
|
---|
16954 | </attribute>
|
---|
16955 | <attribute name="guestPort" type="long" readonly="yes">
|
---|
16956 | <desc>
|
---|
16957 | Guest port to redirect to.
|
---|
16958 | </desc>
|
---|
16959 | </attribute>
|
---|
16960 | </interface>
|
---|
16961 |
|
---|
16962 | <interface
|
---|
16963 | name="IHostPciDevicePlugEvent" extends="IMachineEvent"
|
---|
16964 | waitable="yes"
|
---|
16965 | uuid="9cebfc27-c579-4965-8eb7-d31794cd7dcf"
|
---|
16966 | wsmap="managed" autogen="VBoxEvent" id="OnHostPciDevicePlug"
|
---|
16967 | >
|
---|
16968 | <desc>
|
---|
16969 | Notification when host PCI device is plugged/unplugged. Plugging
|
---|
16970 | usually takes place on VM startup, unplug - when
|
---|
16971 | IMachine::DetachHostPciDevice is called.
|
---|
16972 |
|
---|
16973 | <see>IMachine::DetachHostPciDevice</see>
|
---|
16974 |
|
---|
16975 | </desc>
|
---|
16976 |
|
---|
16977 | <attribute name="plugged" type="boolean" readonly="yes">
|
---|
16978 | <desc>
|
---|
16979 | If device successfully plugged or unplugged.
|
---|
16980 | </desc>
|
---|
16981 | </attribute>
|
---|
16982 |
|
---|
16983 | <attribute name="success" type="boolean" readonly="yes">
|
---|
16984 | <desc>
|
---|
16985 | If operation was successful, if false - 'message' attribute
|
---|
16986 | may be of interest.
|
---|
16987 | </desc>
|
---|
16988 | </attribute>
|
---|
16989 |
|
---|
16990 | <attribute name="attachment" type="IPciDeviceAttachment" readonly="yes">
|
---|
16991 | <desc>
|
---|
16992 | Attachment info for this device.
|
---|
16993 | </desc>
|
---|
16994 | </attribute>
|
---|
16995 |
|
---|
16996 | <attribute name="message" type="wstring" readonly="yes">
|
---|
16997 | <desc>
|
---|
16998 | Optional error message.
|
---|
16999 | </desc>
|
---|
17000 | </attribute>
|
---|
17001 |
|
---|
17002 | </interface>
|
---|
17003 |
|
---|
17004 | <interface
|
---|
17005 | name="IVBoxSVCAvailabilityChangedEvent" extends="IEvent"
|
---|
17006 | uuid="97c78fcd-d4fc-485f-8613-5af88bfcfcdc"
|
---|
17007 | wsmap="managed" autogen="VBoxEvent" id="OnVBoxSVCAvailabilityChanged"
|
---|
17008 | >
|
---|
17009 | <desc>
|
---|
17010 | Notification when VBoxSVC becomes unavailable (due to a crash or similar
|
---|
17011 | unexpected circumstances) or available again.
|
---|
17012 | </desc>
|
---|
17013 |
|
---|
17014 | <attribute name="available" type="boolean" readonly="yes">
|
---|
17015 | <desc>
|
---|
17016 | Whether VBoxSVC is available now.
|
---|
17017 | </desc>
|
---|
17018 | </attribute>
|
---|
17019 | </interface>
|
---|
17020 |
|
---|
17021 | <interface
|
---|
17022 | name="IBandwidthGroupChangedEvent" extends="IEvent"
|
---|
17023 | uuid="334df94a-7556-4cbc-8c04-043096b02d82"
|
---|
17024 | wsmap="managed" autogen="VBoxEvent" id="OnBandwidthGroupChanged"
|
---|
17025 | >
|
---|
17026 | <desc>
|
---|
17027 | Notification when one of the bandwidth groups changed
|
---|
17028 | </desc>
|
---|
17029 | <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes">
|
---|
17030 | <desc>
|
---|
17031 | The changed bandwidth group.
|
---|
17032 | </desc>
|
---|
17033 | </attribute>
|
---|
17034 | </interface>
|
---|
17035 |
|
---|
17036 | <enum
|
---|
17037 | name="GuestMonitorChangedEventType"
|
---|
17038 | uuid="ef172985-7e36-4297-95be-e46396968d66"
|
---|
17039 | >
|
---|
17040 |
|
---|
17041 | <desc>
|
---|
17042 | How the guest monitor has been changed.
|
---|
17043 | </desc>
|
---|
17044 |
|
---|
17045 | <const name="Enabled" value="0">
|
---|
17046 | <desc>
|
---|
17047 | The guest monitor has been enabled by the guest.
|
---|
17048 | </desc>
|
---|
17049 | </const>
|
---|
17050 |
|
---|
17051 | <const name="Disabled" value="1">
|
---|
17052 | <desc>
|
---|
17053 | The guest monitor has been disabled by the guest.
|
---|
17054 | </desc>
|
---|
17055 | </const>
|
---|
17056 |
|
---|
17057 | <const name="NewOrigin" value="2">
|
---|
17058 | <desc>
|
---|
17059 | The guest monitor origin has changed in the guest.
|
---|
17060 | </desc>
|
---|
17061 | </const>
|
---|
17062 | </enum>
|
---|
17063 |
|
---|
17064 | <interface
|
---|
17065 | name="IGuestMonitorChangedEvent" extends="IEvent"
|
---|
17066 | uuid="0f7b8a22-c71f-4a36-8e5f-a77d01d76090"
|
---|
17067 | wsmap="managed" autogen="VBoxEvent" id="OnGuestMonitorChanged"
|
---|
17068 | >
|
---|
17069 | <desc>
|
---|
17070 | Notification when the guest enables one of its monitors.
|
---|
17071 | </desc>
|
---|
17072 |
|
---|
17073 | <attribute name="changeType" type="GuestMonitorChangedEventType" readonly="yes">
|
---|
17074 | <desc>
|
---|
17075 | What was changed for this guest monitor.
|
---|
17076 | </desc>
|
---|
17077 | </attribute>
|
---|
17078 |
|
---|
17079 | <attribute name="screenId" type="unsigned long" readonly="yes">
|
---|
17080 | <desc>
|
---|
17081 | The monitor which was changed.
|
---|
17082 | </desc>
|
---|
17083 | </attribute>
|
---|
17084 |
|
---|
17085 | <attribute name="originX" type="unsigned long" readonly="yes">
|
---|
17086 | <desc>
|
---|
17087 | Physical X origin relative to the primary screen.
|
---|
17088 | Valid for Enabled and NewOrigin.
|
---|
17089 | </desc>
|
---|
17090 | </attribute>
|
---|
17091 |
|
---|
17092 | <attribute name="originY" type="unsigned long" readonly="yes">
|
---|
17093 | <desc>
|
---|
17094 | Physical Y origin relative to the primary screen.
|
---|
17095 | Valid for Enabled and NewOrigin.
|
---|
17096 | </desc>
|
---|
17097 | </attribute>
|
---|
17098 |
|
---|
17099 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
17100 | <desc>
|
---|
17101 | Width of the screen.
|
---|
17102 | Valid for Enabled.
|
---|
17103 | </desc>
|
---|
17104 | </attribute>
|
---|
17105 |
|
---|
17106 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
17107 | <desc>
|
---|
17108 | Height of the screen.
|
---|
17109 | Valid for Enabled.
|
---|
17110 | </desc>
|
---|
17111 | </attribute>
|
---|
17112 |
|
---|
17113 | </interface>
|
---|
17114 |
|
---|
17115 | <interface
|
---|
17116 | name="IStorageDeviceChangedEvent" extends="IEvent"
|
---|
17117 | uuid="8a5c2dce-e341-49d4-afce-c95979f7d70c"
|
---|
17118 | wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged"
|
---|
17119 | >
|
---|
17120 | <desc>
|
---|
17121 | Notification when a
|
---|
17122 | <link to="IMachine::mediumAttachments">storage device</link>
|
---|
17123 | is attached or removed.
|
---|
17124 | </desc>
|
---|
17125 | <attribute name="storageDevice" type="IMediumAttachment" readonly="yes">
|
---|
17126 | <desc>
|
---|
17127 | Storage device that is subject to change.
|
---|
17128 | </desc>
|
---|
17129 | </attribute>
|
---|
17130 | <attribute name="removed" type="boolean" readonly="yes">
|
---|
17131 | <desc>
|
---|
17132 | Flag whether the device was removed or added to the VM.
|
---|
17133 | </desc>
|
---|
17134 | </attribute>
|
---|
17135 | </interface>
|
---|
17136 |
|
---|
17137 | <module name="VBoxSVC" context="LocalServer">
|
---|
17138 | <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
|
---|
17139 | namespace="virtualbox.org">
|
---|
17140 | <interface name="IVirtualBox" default="yes"/>
|
---|
17141 | </class>
|
---|
17142 | </module>
|
---|
17143 |
|
---|
17144 | <module name="VBoxC" context="InprocServer" threadingModel="Free">
|
---|
17145 | <class name="VirtualBoxClient" uuid="dd3fc71d-26c0-4fe1-bf6f-67f633265bba"
|
---|
17146 | namespace="virtualbox.org">
|
---|
17147 | <interface name="IVirtualBoxClient" default="yes"/>
|
---|
17148 | </class>
|
---|
17149 |
|
---|
17150 | <class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
|
---|
17151 | namespace="virtualbox.org">
|
---|
17152 | <interface name="ISession" default="yes"/>
|
---|
17153 | </class>
|
---|
17154 | </module>
|
---|
17155 |
|
---|
17156 | </library>
|
---|
17157 |
|
---|
17158 | </idl>
|
---|
17159 |
|
---|
17160 | <!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->
|
---|