1 | <?xml version="1.0" ?>
|
---|
2 |
|
---|
3 | <!--
|
---|
4 |
|
---|
5 | Copyright (C) 2006-2010 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 name="SettingsVersion"
|
---|
388 | uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f"
|
---|
389 | >
|
---|
390 | <desc>Settings version of VirtualBox settings files. This is written to
|
---|
391 | the "version" attribute of the root "VirtualBox" element in the settings
|
---|
392 | file XML and indicates which VirtualBox version wrote the file.
|
---|
393 | </desc>
|
---|
394 |
|
---|
395 | <const name="Null" value="0">
|
---|
396 | <desc>Null value, indicates invalid version.</desc>
|
---|
397 | </const>
|
---|
398 | <const name="v1_0" value="1">
|
---|
399 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
400 | </const>
|
---|
401 | <const name="v1_1" value="2">
|
---|
402 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
403 | </const>
|
---|
404 | <const name="v1_2" value="3">
|
---|
405 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
406 | </const>
|
---|
407 | <const name="v1_3pre" value="4">
|
---|
408 | <desc>Legacy settings version, not currently supported.</desc>
|
---|
409 | </const>
|
---|
410 | <const name="v1_3" value="5">
|
---|
411 | <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc>
|
---|
412 | <!--
|
---|
413 | Machine XML: Capitalization of Uart, Lpt elements and many attributes changed.
|
---|
414 | -->
|
---|
415 | </const>
|
---|
416 | <const name="v1_4" value="6">
|
---|
417 | <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
|
---|
418 | <!--
|
---|
419 | VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged
|
---|
420 | (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk)
|
---|
421 | -->
|
---|
422 | </const>
|
---|
423 | <const name="v1_5" value="7">
|
---|
424 | <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc>
|
---|
425 | <!-- 2008-09-04: 2.0.0 released
|
---|
426 | 2008-11-20: settings version 1.5 introduced
|
---|
427 | 2008-12-17: 2.1.0 released
|
---|
428 | Machine changes:
|
---|
429 | guest OS identifiers changed;
|
---|
430 | Machine/Hardware/Display/MonitorCount renamed to monitorCount;
|
---|
431 | Machine/Hardware/Display/Accelerate3D renamed to accelerate3D;
|
---|
432 | Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count
|
---|
433 | -->
|
---|
434 | </const>
|
---|
435 | <const name="v1_6" value="8">
|
---|
436 | <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc>
|
---|
437 | <!-- 2008-12-17: 2.1.0 released
|
---|
438 | 2008-12-19: settings version 1.6 introduced (is in 2.1 branch)
|
---|
439 | 2009-04-08: 2.2.0 released
|
---|
440 | Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done)
|
---|
441 | -->
|
---|
442 | </const>
|
---|
443 | <const name="v1_7" value="9">
|
---|
444 | <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc>
|
---|
445 | <!-- 2008-12-17: 2.1.0 released
|
---|
446 | 2009-03-11: settings version 1.7 introduced (is in 2.2 branch)
|
---|
447 | 2009-04-08: 2.2.0 released
|
---|
448 | VirtualBox.xml additions: NetserviceRegistry with DHCPServers (done)
|
---|
449 | Machine changes: HardDiskAttachments is now StorageControllers (done)
|
---|
450 | -->
|
---|
451 | </const>
|
---|
452 | <const name="v1_8" value="10">
|
---|
453 | <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc>
|
---|
454 | <!-- Machine additions: Display/@accelerate2DVideo (done)
|
---|
455 | -->
|
---|
456 | </const>
|
---|
457 | <const name="v1_9" value="11">
|
---|
458 | <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc>
|
---|
459 | <!-- The big storage controller / DVD / Floppy rework (done)
|
---|
460 | -->
|
---|
461 | </const>
|
---|
462 | <const name="v1_10" value="12">
|
---|
463 | <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc>
|
---|
464 | <!-- Machine changes: RTC localOrUTC (done)
|
---|
465 | CPU hot-plug support
|
---|
466 | -->
|
---|
467 | </const>
|
---|
468 | <const name="v1_11" value="13">
|
---|
469 | <desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc>
|
---|
470 | <!-- Machine changes: HD Audio controller, per-machine disk registries,
|
---|
471 | /@format attribute for DVD and floppy images.
|
---|
472 | -->
|
---|
473 | </const>
|
---|
474 | <const name="Future" value="99999">
|
---|
475 | <desc>Settings version greater than "1.11", written by a future VirtualBox version.</desc>
|
---|
476 | </const>
|
---|
477 | </enum>
|
---|
478 |
|
---|
479 | <enum
|
---|
480 | name="AccessMode"
|
---|
481 | uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
|
---|
482 | >
|
---|
483 | <desc>
|
---|
484 | Access mode for opening files.
|
---|
485 | </desc>
|
---|
486 |
|
---|
487 | <const name="ReadOnly" value="1"/>
|
---|
488 | <const name="ReadWrite" value="2"/>
|
---|
489 | </enum>
|
---|
490 |
|
---|
491 | <enum
|
---|
492 | name="MachineState"
|
---|
493 | uuid="ec6c6a9e-113d-4ff4-b44f-0b69f21c97fe"
|
---|
494 | >
|
---|
495 | <desc>
|
---|
496 | Virtual machine execution state.
|
---|
497 |
|
---|
498 | This enumeration represents possible values of the <link
|
---|
499 | to="IMachine::state"/> attribute.
|
---|
500 |
|
---|
501 | Below is the basic virtual machine state diagram. It shows how the state
|
---|
502 | changes during virtual machine execution. The text in square braces shows
|
---|
503 | a method of the IConsole interface that performs the given state
|
---|
504 | transition.
|
---|
505 |
|
---|
506 | <pre>
|
---|
507 | +---------[powerDown()] <- Stuck <--[failure]-+
|
---|
508 | V |
|
---|
509 | +-> PoweredOff --+-->[powerUp()]--> Starting --+ | +-----[resume()]-----+
|
---|
510 | | | | | V |
|
---|
511 | | Aborted -----+ +--> Running --[pause()]--> Paused
|
---|
512 | | | ^ | ^ |
|
---|
513 | | Saved -----------[powerUp()]--> Restoring -+ | | | |
|
---|
514 | | ^ | | | |
|
---|
515 | | | +-----------------------------------------+-|-------------------+ +
|
---|
516 | | | | | |
|
---|
517 | | | +-- Saving <--------[takeSnapshot()]<-------+---------------------+
|
---|
518 | | | | |
|
---|
519 | | +-------- Saving <--------[saveState()]<----------+---------------------+
|
---|
520 | | | |
|
---|
521 | +-------------- Stopping -------[powerDown()]<----------+---------------------+
|
---|
522 | </pre>
|
---|
523 |
|
---|
524 | Note that states to the right from PoweredOff, Aborted and Saved in the
|
---|
525 | above diagram are called <i>online VM states</i>. These states
|
---|
526 | represent the virtual machine which is being executed in a dedicated
|
---|
527 | process (usually with a GUI window attached to it where you can see the
|
---|
528 | activity of the virtual machine and interact with it). There are two
|
---|
529 | special pseudo-states, FirstOnline and LastOnline, that can be used in
|
---|
530 | relational expressions to detect if the given machine state is online or
|
---|
531 | not:
|
---|
532 |
|
---|
533 | <pre>
|
---|
534 | if (machine.GetState() >= MachineState_FirstOnline &&
|
---|
535 | machine.GetState() <= MachineState_LastOnline)
|
---|
536 | {
|
---|
537 | ...the machine is being executed...
|
---|
538 | }
|
---|
539 | </pre>
|
---|
540 |
|
---|
541 | When the virtual machine is in one of the online VM states (that is, being
|
---|
542 | executed), only a few machine settings can be modified. Methods working
|
---|
543 | with such settings contain an explicit note about that. An attempt to
|
---|
544 | change any oter setting or perform a modifying operation during this time
|
---|
545 | will result in the <link to="VBOX_E_INVALID_VM_STATE"/> error.
|
---|
546 |
|
---|
547 | All online states except Running, Paused and Stuck are transitional: they
|
---|
548 | represent temporary conditions of the virtual machine that will last as
|
---|
549 | long as the operation that initiated such a condition.
|
---|
550 |
|
---|
551 | The Stuck state is a special case. It means that execution of the machine
|
---|
552 | has reached the "Guru Meditation" condition. This condition indicates an
|
---|
553 | internal VMM (virtual machine manager) failure which may happen as a
|
---|
554 | result of either an unhandled low-level virtual hardware exception or one
|
---|
555 | of the recompiler exceptions (such as the <i>too-many-traps</i>
|
---|
556 | condition).
|
---|
557 |
|
---|
558 | Note also that any online VM state may transit to the Aborted state. This
|
---|
559 | happens if the process that is executing the virtual machine terminates
|
---|
560 | unexpectedly (for example, crashes). Other than that, the Aborted state is
|
---|
561 | equivalent to PoweredOff.
|
---|
562 |
|
---|
563 | There are also a few additional state diagrams that do not deal with
|
---|
564 | virtual machine execution and therefore are shown separately. The states
|
---|
565 | shown on these diagrams are called <i>offline VM states</i> (this includes
|
---|
566 | PoweredOff, Aborted and Saved too).
|
---|
567 |
|
---|
568 | The first diagram shows what happens when a lengthy setup operation is
|
---|
569 | being executed (such as <link to="IMachine::attachDevice"/>).
|
---|
570 |
|
---|
571 | <pre>
|
---|
572 | +----------------------------------(same state as before the call)------+
|
---|
573 | | |
|
---|
574 | +-> PoweredOff --+ |
|
---|
575 | | | |
|
---|
576 | |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
|
---|
577 | | |
|
---|
578 | +-> Saved -------+
|
---|
579 | </pre>
|
---|
580 |
|
---|
581 | The next two diagrams demonstrate the process of taking a snapshot of a
|
---|
582 | powered off virtual machine, restoring the state to that as of a snapshot
|
---|
583 | or deleting a snapshot, respectively.
|
---|
584 |
|
---|
585 | <pre>
|
---|
586 | +----------------------------------(same state as before the call)------+
|
---|
587 | | |
|
---|
588 | +-> PoweredOff --+ |
|
---|
589 | | +-->[takeSnapshot()] -------------------> Saving ------+
|
---|
590 | +-> Aborted -----+
|
---|
591 |
|
---|
592 | +-> PoweredOff --+
|
---|
593 | | |
|
---|
594 | | Aborted -----+-->[restoreSnapshot() ]-------> RestoringSnapshot -+
|
---|
595 | | | [deleteSnapshot() ]-------> DeletingSnapshot --+
|
---|
596 | +-> Saved -------+ |
|
---|
597 | | |
|
---|
598 | +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
|
---|
599 | </pre>
|
---|
600 |
|
---|
601 | Note that the Saving state is present in both the offline state group and
|
---|
602 | online state group. Currently, the only way to determine what group is
|
---|
603 | assumed in a particular case is to remember the previous machine state: if
|
---|
604 | it was Running or Paused, then Saving is an online state, otherwise it is
|
---|
605 | an offline state. This inconsistency may be removed in one of the future
|
---|
606 | versions of VirtualBox by adding a new state.
|
---|
607 |
|
---|
608 | <note internal="yes">
|
---|
609 | For whoever decides to touch this enum: In order to keep the
|
---|
610 | comparisons involving FirstOnline and LastOnline pseudo-states valid,
|
---|
611 | the numeric values of these states must be correspondingly updated if
|
---|
612 | needed: for any online VM state, the condition
|
---|
613 | <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
614 | @c true. The same relates to transient states for which
|
---|
615 | the condition <tt>FirstOnline <= state <= LastOnline</tt> must be
|
---|
616 | @c true.
|
---|
617 | </note>
|
---|
618 | </desc>
|
---|
619 |
|
---|
620 | <const name="Null" value="0">
|
---|
621 | <desc>Null value (never used by the API).</desc>
|
---|
622 | </const>
|
---|
623 | <const name="PoweredOff" value="1">
|
---|
624 | <desc>
|
---|
625 | The machine is not running and has no saved execution state; it has
|
---|
626 | either never been started or been shut down successfully.
|
---|
627 | </desc>
|
---|
628 | </const>
|
---|
629 | <const name="Saved" value="2">
|
---|
630 | <desc>
|
---|
631 | The machine is not currently running, but the execution state of the machine
|
---|
632 | has been saved to an external file when it was running, from where
|
---|
633 | it can be resumed.
|
---|
634 | </desc>
|
---|
635 | </const>
|
---|
636 | <const name="Teleported" value="3">
|
---|
637 | <desc>
|
---|
638 | The machine was teleported to a different host (or process) and then
|
---|
639 | powered off. Take care when powering it on again may corrupt resources
|
---|
640 | it shares with the teleportation target (e.g. disk and network).
|
---|
641 | </desc>
|
---|
642 | </const>
|
---|
643 | <const name="Aborted" value="4">
|
---|
644 | <desc>
|
---|
645 | The process running the machine has terminated abnormally. This may
|
---|
646 | indicate a crash of the VM process in host execution context, or
|
---|
647 | the VM process has been terminated externally.
|
---|
648 | </desc>
|
---|
649 | </const>
|
---|
650 | <const name="Running" value="5">
|
---|
651 | <desc>
|
---|
652 | The machine is currently being executed.
|
---|
653 | <note internal="yes">
|
---|
654 | For whoever decides to touch this enum: In order to keep the
|
---|
655 | comparisons in the old source code valid, this state must immediately
|
---|
656 | precede the Paused state.
|
---|
657 | TODO: Lift this spectacularly wonderful restriction.
|
---|
658 | </note>
|
---|
659 | </desc>
|
---|
660 | </const>
|
---|
661 | <const name="Paused" value="6">
|
---|
662 | <desc>
|
---|
663 | Execution of the machine has been paused.
|
---|
664 | <note internal="yes">
|
---|
665 | For whoever decides to touch this enum: In order to keep the
|
---|
666 | comparisons in the old source code valid, this state must immediately
|
---|
667 | follow the Running state.
|
---|
668 | TODO: Lift this spectacularly wonderful restriction.
|
---|
669 | </note>
|
---|
670 | </desc>
|
---|
671 | </const>
|
---|
672 | <const name="Stuck" value="7">
|
---|
673 | <desc>
|
---|
674 | Execution of the machine has reached the "Guru Meditation"
|
---|
675 | condition. This indicates a severe error in the hypervisor itself.
|
---|
676 | <note internal="yes">
|
---|
677 | bird: Why this uncool name? Could we rename it to "GuruMeditation" or
|
---|
678 | "Guru", perhaps? Or are there some other VMM states that are
|
---|
679 | intended to be lumped in here as well?
|
---|
680 | </note>
|
---|
681 | </desc>
|
---|
682 | </const>
|
---|
683 | <const name="Teleporting" value="8">
|
---|
684 | <desc>
|
---|
685 | The machine is about to be teleported to a different host or process.
|
---|
686 | It is possible to pause a machine in this state, but it will go to the
|
---|
687 | @c TeleportingPausedVM state and it will not be
|
---|
688 | possible to resume it again unless the teleportation fails.
|
---|
689 | </desc>
|
---|
690 | </const>
|
---|
691 | <const name="LiveSnapshotting" value="9">
|
---|
692 | <desc>
|
---|
693 | A live snapshot is being taken. The machine is running normally, but
|
---|
694 | some of the runtime configuration options are inaccessible. Also, if
|
---|
695 | paused while in this state it will transition to
|
---|
696 | @c Saving and it will not be resume the
|
---|
697 | execution until the snapshot operation has completed.
|
---|
698 | </desc>
|
---|
699 | </const>
|
---|
700 | <const name="Starting" value="10">
|
---|
701 | <desc>
|
---|
702 | Machine is being started after powering it on from a
|
---|
703 | zero execution state.
|
---|
704 | </desc>
|
---|
705 | </const>
|
---|
706 | <const name="Stopping" value="11">
|
---|
707 | <desc>
|
---|
708 | Machine is being normally stopped powering it off, or after the guest OS
|
---|
709 | has initiated a shutdown sequence.
|
---|
710 | </desc>
|
---|
711 | </const>
|
---|
712 | <const name="Saving" value="12">
|
---|
713 | <desc>
|
---|
714 | Machine is saving its execution state to a file, or an online
|
---|
715 | snapshot of the machine is being taken.
|
---|
716 | </desc>
|
---|
717 | </const>
|
---|
718 | <const name="Restoring" value="13">
|
---|
719 | <desc>
|
---|
720 | Execution state of the machine is being restored from a file
|
---|
721 | after powering it on from the saved execution state.
|
---|
722 | </desc>
|
---|
723 | </const>
|
---|
724 | <const name="TeleportingPausedVM" value="14">
|
---|
725 | <desc>
|
---|
726 | The machine is being teleported to another host or process, but it is
|
---|
727 | not running. This is the paused variant of the
|
---|
728 | @c state.
|
---|
729 | </desc>
|
---|
730 | </const>
|
---|
731 | <const name="TeleportingIn" value="15">
|
---|
732 | <desc>
|
---|
733 | Teleporting the machine state in from another host or process.
|
---|
734 | </desc>
|
---|
735 | </const>
|
---|
736 | <const name="FaultTolerantSyncing" value="16">
|
---|
737 | <desc>
|
---|
738 | The machine is being synced with a fault tolerant VM running elsewhere.
|
---|
739 | </desc>
|
---|
740 | </const>
|
---|
741 | <const name="DeletingSnapshotOnline" value="17">
|
---|
742 | <desc>
|
---|
743 | Like @c DeletingSnapshot, but the merging of media is ongoing in
|
---|
744 | the background while the machine is running.
|
---|
745 | </desc>
|
---|
746 | </const>
|
---|
747 | <const name="DeletingSnapshotPaused" value="18">
|
---|
748 | <desc>
|
---|
749 | Like @c DeletingSnapshotOnline, but the machine was paused when the
|
---|
750 | merging of differencing media was started.
|
---|
751 | </desc>
|
---|
752 | </const>
|
---|
753 | <const name="RestoringSnapshot" value="19">
|
---|
754 | <desc>
|
---|
755 | A machine snapshot is being restored; this typically does not take long.
|
---|
756 | </desc>
|
---|
757 | </const>
|
---|
758 | <const name="DeletingSnapshot" value="20">
|
---|
759 | <desc>
|
---|
760 | A machine snapshot is being deleted; this can take a long time since this
|
---|
761 | may require merging differencing media. This value indicates that the
|
---|
762 | machine is not running while the snapshot is being deleted.
|
---|
763 | </desc>
|
---|
764 | </const>
|
---|
765 | <const name="SettingUp" value="21">
|
---|
766 | <desc>
|
---|
767 | Lengthy setup operation is in progress.
|
---|
768 | </desc>
|
---|
769 | </const>
|
---|
770 |
|
---|
771 | <const name="FirstOnline" value="5" wsmap="suppress"> <!-- Running -->
|
---|
772 | <desc>
|
---|
773 | Pseudo-state: first online state (for use in relational expressions).
|
---|
774 | </desc>
|
---|
775 | </const>
|
---|
776 | <const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused -->
|
---|
777 | <desc>
|
---|
778 | Pseudo-state: last online state (for use in relational expressions).
|
---|
779 | </desc>
|
---|
780 | </const>
|
---|
781 |
|
---|
782 | <const name="FirstTransient" value="8" wsmap="suppress"> <!-- Teleporting -->
|
---|
783 | <desc>
|
---|
784 | Pseudo-state: first transient state (for use in relational expressions).
|
---|
785 | </desc>
|
---|
786 | </const>
|
---|
787 | <const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp -->
|
---|
788 | <desc>
|
---|
789 | Pseudo-state: last transient state (for use in relational expressions).
|
---|
790 | </desc>
|
---|
791 | </const>
|
---|
792 |
|
---|
793 | </enum>
|
---|
794 |
|
---|
795 | <enum
|
---|
796 | name="SessionState"
|
---|
797 | uuid="cf2700c0-ea4b-47ae-9725-7810114b94d8"
|
---|
798 | >
|
---|
799 | <desc>
|
---|
800 | Session state. This enumeration represents possible values of
|
---|
801 | <link to="IMachine::sessionState"/> and <link to="ISession::state"/>
|
---|
802 | attributes.
|
---|
803 | </desc>
|
---|
804 |
|
---|
805 | <const name="Null" value="0">
|
---|
806 | <desc>Null value (never used by the API).</desc>
|
---|
807 | </const>
|
---|
808 | <const name="Unlocked" value="1">
|
---|
809 | <desc>
|
---|
810 | In <link to="IMachine::sessionState"/>, this means that the machine
|
---|
811 | is not locked for any sessions.
|
---|
812 |
|
---|
813 | In <link to="ISession::state"/>, this means that no machine is
|
---|
814 | currently locked for this session.
|
---|
815 | </desc>
|
---|
816 | </const>
|
---|
817 | <const name="Locked" value="2">
|
---|
818 | <desc>
|
---|
819 | In <link to="IMachine::sessionState"/>, this means that the machine
|
---|
820 | is currently locked for a session, whose process identifier can
|
---|
821 | then be found in the <link to="IMachine::sessionPid" /> attribute.
|
---|
822 |
|
---|
823 | In <link to="ISession::state"/>, this means that a machine is
|
---|
824 | currently locked for this session, and the mutable machine object
|
---|
825 | can be found in the <link to="ISession::machine"/> attribute
|
---|
826 | (see <link to="IMachine::lockMachine" /> for details).
|
---|
827 | </desc>
|
---|
828 | </const>
|
---|
829 | <const name="Spawning" value="3">
|
---|
830 | <desc>
|
---|
831 | A new process is being spawned for the machine as a result of
|
---|
832 | <link to="IMachine::launchVMProcess"/> call. This state also occurs
|
---|
833 | as a short transient state during an <link to="IMachine::lockMachine"/>
|
---|
834 | call.
|
---|
835 | </desc>
|
---|
836 | </const>
|
---|
837 | <const name="Unlocking" value="4">
|
---|
838 | <desc>
|
---|
839 | The session is being unlocked.
|
---|
840 | </desc>
|
---|
841 | </const>
|
---|
842 | </enum>
|
---|
843 |
|
---|
844 | <enum
|
---|
845 | name="CPUPropertyType"
|
---|
846 | uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5"
|
---|
847 | >
|
---|
848 | <desc>
|
---|
849 | Virtual CPU property type. This enumeration represents possible values of the
|
---|
850 | IMachine get- and setCPUProperty methods.
|
---|
851 | </desc>
|
---|
852 | <const name="Null" value="0">
|
---|
853 | <desc>Null value (never used by the API).</desc>
|
---|
854 | </const>
|
---|
855 | <const name="PAE" value="1">
|
---|
856 | <desc>
|
---|
857 | This setting determines whether VirtualBox will expose the Physical Address
|
---|
858 | Extension (PAE) feature of the host CPU to the guest. Note that in case PAE
|
---|
859 | is not available, it will not be reported.
|
---|
860 | </desc>
|
---|
861 | </const>
|
---|
862 | <const name="Synthetic" value="2">
|
---|
863 | <desc>
|
---|
864 | This setting determines whether VirtualBox will expose a synthetic CPU to the guest to allow
|
---|
865 | teleporting between host systems that differ significantly.
|
---|
866 | </desc>
|
---|
867 | </const>
|
---|
868 | </enum>
|
---|
869 |
|
---|
870 |
|
---|
871 | <enum
|
---|
872 | name="HWVirtExPropertyType"
|
---|
873 | uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee"
|
---|
874 | >
|
---|
875 | <desc>
|
---|
876 | Hardware virtualization property type. This enumeration represents possible values
|
---|
877 | for the <link to="IMachine::getHWVirtExProperty"/> and
|
---|
878 | <link to="IMachine::setHWVirtExProperty"/> methods.
|
---|
879 | </desc>
|
---|
880 | <const name="Null" value="0">
|
---|
881 | <desc>Null value (never used by the API).</desc>
|
---|
882 | </const>
|
---|
883 | <const name="Enabled" value="1">
|
---|
884 | <desc>
|
---|
885 | Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If
|
---|
886 | such extensions are not available, they will not be used.
|
---|
887 | </desc>
|
---|
888 | </const>
|
---|
889 | <const name="Exclusive" value="2">
|
---|
890 | <desc>
|
---|
891 | Whether hardware virtualization is used exclusively by VirtualBox. When enabled,
|
---|
892 | VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V
|
---|
893 | feature of the host. To share these with other hypervisors, you must disable this property.
|
---|
894 | </desc>
|
---|
895 | </const>
|
---|
896 | <const name="VPID" value="3">
|
---|
897 | <desc>
|
---|
898 | Whether VT-x VPID is enabled. If this extension is not available, it will not be used.
|
---|
899 | </desc>
|
---|
900 | </const>
|
---|
901 | <const name="NestedPaging" value="4">
|
---|
902 | <desc>
|
---|
903 | Whether Nested Paging is enabled. If this extension is not available, it will not be used.
|
---|
904 | </desc>
|
---|
905 | </const>
|
---|
906 | <const name="LargePages" value="5">
|
---|
907 | <desc>
|
---|
908 | Whether large page allocation is enabled; requires nested paging and a 64 bits host.
|
---|
909 | </desc>
|
---|
910 | </const>
|
---|
911 | <const name="Force" value="6">
|
---|
912 | <desc>
|
---|
913 | Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If
|
---|
914 | not set, there will be an automatic fallback to software virtualization.
|
---|
915 | </desc>
|
---|
916 | </const>
|
---|
917 | </enum>
|
---|
918 |
|
---|
919 | <enum
|
---|
920 | name="FaultToleranceState"
|
---|
921 | uuid="5124f7ec-6b67-493c-9dee-ee45a44114e1"
|
---|
922 | >
|
---|
923 | <desc>
|
---|
924 | Used with <link to="IMachine::faultToleranceState" />.
|
---|
925 | </desc>
|
---|
926 | <const name="Inactive" value="1">
|
---|
927 | <desc>No fault tolerance enabled.</desc>
|
---|
928 | </const>
|
---|
929 | <const name="Master" value="2">
|
---|
930 | <desc>Fault tolerant master VM.</desc>
|
---|
931 | </const>
|
---|
932 | <const name="Standby" value="3">
|
---|
933 | <desc>Fault tolerant standby VM.</desc>
|
---|
934 | </const>
|
---|
935 | </enum>
|
---|
936 |
|
---|
937 | <enum
|
---|
938 | name="LockType"
|
---|
939 | uuid="138b53f8-db4b-47c5-b32b-4ef52f769413"
|
---|
940 | >
|
---|
941 | <desc>
|
---|
942 | Used with <link to="IMachine::lockMachine" />.
|
---|
943 | </desc>
|
---|
944 | <const name="Write" value="2">
|
---|
945 | <desc>Lock the machine for writing.</desc>
|
---|
946 | </const>
|
---|
947 | <const name="Shared" value="1">
|
---|
948 | <desc>Request only a shared read lock for remote-controlling the machine.</desc>
|
---|
949 | </const>
|
---|
950 | </enum>
|
---|
951 |
|
---|
952 | <enum
|
---|
953 | name="SessionType"
|
---|
954 | uuid="A13C02CB-0C2C-421E-8317-AC0E8AAA153A"
|
---|
955 | >
|
---|
956 | <desc>
|
---|
957 | Session type. This enumeration represents possible values of the
|
---|
958 | <link to="ISession::type"/> attribute.
|
---|
959 | </desc>
|
---|
960 |
|
---|
961 | <const name="Null" value="0">
|
---|
962 | <desc>Null value (never used by the API).</desc>
|
---|
963 | </const>
|
---|
964 | <const name="WriteLock" value="1">
|
---|
965 | <desc>
|
---|
966 | Session has acquired an exclusive write lock on a machine
|
---|
967 | using <link to="IMachine::lockMachine"/>.
|
---|
968 | </desc>
|
---|
969 | </const>
|
---|
970 | <const name="Remote" value="2">
|
---|
971 | <desc>
|
---|
972 | Session has launched a VM process using
|
---|
973 | <link to="IMachine::launchVMProcess"/>
|
---|
974 | </desc>
|
---|
975 | </const>
|
---|
976 | <const name="Shared" value="3">
|
---|
977 | <desc>
|
---|
978 | Session has obtained a link to another session using
|
---|
979 | <link to="IMachine::lockMachine"/>
|
---|
980 | </desc>
|
---|
981 | </const>
|
---|
982 | </enum>
|
---|
983 |
|
---|
984 | <enum
|
---|
985 | name="DeviceType"
|
---|
986 | uuid="6d9420f7-0b56-4636-99f9-7346f1b01e57"
|
---|
987 | >
|
---|
988 | <desc>
|
---|
989 | Device type.
|
---|
990 | </desc>
|
---|
991 | <const name="Null" value="0">
|
---|
992 | <desc>
|
---|
993 | Null value, may also mean "no device" (not allowed for
|
---|
994 | <link to="IConsole::getDeviceActivity"/>).
|
---|
995 | </desc>
|
---|
996 | </const>
|
---|
997 | <const name="Floppy" value="1">
|
---|
998 | <desc>Floppy device.</desc>
|
---|
999 | </const>
|
---|
1000 | <const name="DVD" value="2">
|
---|
1001 | <desc>CD/DVD-ROM device.</desc>
|
---|
1002 | </const>
|
---|
1003 | <const name="HardDisk" value="3">
|
---|
1004 | <desc>Hard disk device.</desc>
|
---|
1005 | </const>
|
---|
1006 | <const name="Network" value="4">
|
---|
1007 | <desc>Network device.</desc>
|
---|
1008 | </const>
|
---|
1009 | <const name="USB" value="5">
|
---|
1010 | <desc>USB device.</desc>
|
---|
1011 | </const>
|
---|
1012 | <const name="SharedFolder" value="6">
|
---|
1013 | <desc>Shared folder device.</desc>
|
---|
1014 | </const>
|
---|
1015 | </enum>
|
---|
1016 |
|
---|
1017 | <enum
|
---|
1018 | name="DeviceActivity"
|
---|
1019 | uuid="6FC8AEAA-130A-4eb5-8954-3F921422D707"
|
---|
1020 | >
|
---|
1021 | <desc>
|
---|
1022 | Device activity for <link to="IConsole::getDeviceActivity"/>.
|
---|
1023 | </desc>
|
---|
1024 |
|
---|
1025 | <const name="Null" value="0"/>
|
---|
1026 | <const name="Idle" value="1"/>
|
---|
1027 | <const name="Reading" value="2"/>
|
---|
1028 | <const name="Writing" value="3"/>
|
---|
1029 | </enum>
|
---|
1030 |
|
---|
1031 | <enum
|
---|
1032 | name="ClipboardMode"
|
---|
1033 | uuid="33364716-4008-4701-8f14-be0fa3d62950"
|
---|
1034 | >
|
---|
1035 | <desc>
|
---|
1036 | Host-Guest clipboard interchange mode.
|
---|
1037 | </desc>
|
---|
1038 |
|
---|
1039 | <const name="Disabled" value="0"/>
|
---|
1040 | <const name="HostToGuest" value="1"/>
|
---|
1041 | <const name="GuestToHost" value="2"/>
|
---|
1042 | <const name="Bidirectional" value="3"/>
|
---|
1043 | </enum>
|
---|
1044 |
|
---|
1045 | <enum
|
---|
1046 | name="Scope"
|
---|
1047 | uuid="7c91096e-499e-4eca-9f9b-9001438d7855"
|
---|
1048 | >
|
---|
1049 | <desc>
|
---|
1050 | Scope of the operation.
|
---|
1051 |
|
---|
1052 | A generic enumeration used in various methods to define the action or
|
---|
1053 | argument scope.
|
---|
1054 | </desc>
|
---|
1055 |
|
---|
1056 | <const name="Global" value="0"/>
|
---|
1057 | <const name="Machine" value="1"/>
|
---|
1058 | <const name="Session" value="2"/>
|
---|
1059 | </enum>
|
---|
1060 |
|
---|
1061 | <enum
|
---|
1062 | name="BIOSBootMenuMode"
|
---|
1063 | uuid="ae4fb9f7-29d2-45b4-b2c7-d579603135d5"
|
---|
1064 | >
|
---|
1065 | <desc>
|
---|
1066 | BIOS boot menu mode.
|
---|
1067 | </desc>
|
---|
1068 |
|
---|
1069 | <const name="Disabled" value="0"/>
|
---|
1070 | <const name="MenuOnly" value="1"/>
|
---|
1071 | <const name="MessageAndMenu" value="2"/>
|
---|
1072 | </enum>
|
---|
1073 |
|
---|
1074 | <enum
|
---|
1075 | name="ProcessorFeature"
|
---|
1076 | uuid="64c38e6b-8bcf-45ad-ac03-9b406287c5bf"
|
---|
1077 | >
|
---|
1078 | <desc>
|
---|
1079 | CPU features.
|
---|
1080 | </desc>
|
---|
1081 |
|
---|
1082 | <const name="HWVirtEx" value="0"/>
|
---|
1083 | <const name="PAE" value="1"/>
|
---|
1084 | <const name="LongMode" value="2"/>
|
---|
1085 | <const name="NestedPaging" value="3"/>
|
---|
1086 | </enum>
|
---|
1087 |
|
---|
1088 | <enum
|
---|
1089 | name="FirmwareType"
|
---|
1090 | uuid="b903f264-c230-483e-ac74-2b37ce60d371"
|
---|
1091 | >
|
---|
1092 | <desc>
|
---|
1093 | Firmware type.
|
---|
1094 | </desc>
|
---|
1095 | <const name="BIOS" value="1">
|
---|
1096 | <desc>BIOS Firmware.</desc>
|
---|
1097 | </const>
|
---|
1098 | <const name="EFI" value="2">
|
---|
1099 | <desc>EFI Firmware, bitness detected basing on OS type.</desc>
|
---|
1100 | </const>
|
---|
1101 | <const name="EFI32" value="3">
|
---|
1102 | <desc>Efi firmware, 32-bit.</desc>
|
---|
1103 | </const>
|
---|
1104 | <const name="EFI64" value="4">
|
---|
1105 | <desc>Efi firmware, 64-bit.</desc>
|
---|
1106 | </const>
|
---|
1107 | <const name="EFIDUAL" value="5">
|
---|
1108 | <desc>Efi firmware, combined 32 and 64-bit.</desc>
|
---|
1109 | </const>
|
---|
1110 | </enum>
|
---|
1111 |
|
---|
1112 | <enum
|
---|
1113 | name="PointingHidType"
|
---|
1114 | uuid="0d3c17a2-821a-4b2e-ae41-890c6c60aa97"
|
---|
1115 | >
|
---|
1116 | <desc>
|
---|
1117 | Type of pointing device used in a virtual machine.
|
---|
1118 | </desc>
|
---|
1119 | <const name="None" value="1">
|
---|
1120 | <desc>No mouse.</desc>
|
---|
1121 | </const>
|
---|
1122 | <const name="PS2Mouse" value="2">
|
---|
1123 | <desc>PS/2 auxiliary device, a.k.a. mouse.</desc>
|
---|
1124 | </const>
|
---|
1125 | <const name="USBMouse" value="3">
|
---|
1126 | <desc>USB mouse (relative pointer).</desc>
|
---|
1127 | </const>
|
---|
1128 | <const name="USBTablet" value="4">
|
---|
1129 | <desc>USB tablet (absolute pointer).</desc>
|
---|
1130 | </const>
|
---|
1131 | <const name="ComboMouse" value="5">
|
---|
1132 | <desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior.
|
---|
1133 | Using of such device can have negative performance implications. </desc>
|
---|
1134 | </const>
|
---|
1135 | </enum>
|
---|
1136 |
|
---|
1137 | <enum
|
---|
1138 | name="KeyboardHidType"
|
---|
1139 | uuid="5a5b0996-3a3e-44bb-9019-56979812cbcc"
|
---|
1140 | >
|
---|
1141 | <desc>
|
---|
1142 | Type of keyboard device used in a virtual machine.
|
---|
1143 | </desc>
|
---|
1144 | <const name="None" value="1">
|
---|
1145 | <desc>No keyboard.</desc>
|
---|
1146 | </const>
|
---|
1147 | <const name="PS2Keyboard" value="2">
|
---|
1148 | <desc>PS/2 keyboard.</desc>
|
---|
1149 | </const>
|
---|
1150 | <const name="USBKeyboard" value="3">
|
---|
1151 | <desc>USB keyboard.</desc>
|
---|
1152 | </const>
|
---|
1153 | <const name="ComboKeyboard" value="4">
|
---|
1154 | <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior.
|
---|
1155 | Using of such device can have negative performance implications. </desc>
|
---|
1156 | </const>
|
---|
1157 | </enum>
|
---|
1158 |
|
---|
1159 | <!--
|
---|
1160 | // IVirtualBoxErrorInfo
|
---|
1161 | /////////////////////////////////////////////////////////////////////////
|
---|
1162 | -->
|
---|
1163 |
|
---|
1164 | <interface
|
---|
1165 | name="IVirtualBoxErrorInfo" extends="$errorinfo"
|
---|
1166 | uuid="e053d3c0-f493-491b-a735-3a9f0b1feed4"
|
---|
1167 | supportsErrorInfo="no"
|
---|
1168 | wsmap="managed"
|
---|
1169 | >
|
---|
1170 | <desc>
|
---|
1171 | The IVirtualBoxErrorInfo interface represents extended error information.
|
---|
1172 |
|
---|
1173 | Extended error information can be set by VirtualBox components after
|
---|
1174 | unsuccessful or partially successful method invocation. This information
|
---|
1175 | can be retrieved by the calling party as an IVirtualBoxErrorInfo object
|
---|
1176 | and then shown to the client in addition to the plain 32-bit result code.
|
---|
1177 |
|
---|
1178 | In MS COM, this interface extends the IErrorInfo interface,
|
---|
1179 | in XPCOM, it extends the nsIException interface. In both cases,
|
---|
1180 | it provides a set of common attributes to retrieve error
|
---|
1181 | information.
|
---|
1182 |
|
---|
1183 | Sometimes invocation of some component's method may involve methods of
|
---|
1184 | other components that may also fail (independently of this method's
|
---|
1185 | failure), or a series of non-fatal errors may precede a fatal error that
|
---|
1186 | causes method failure. In cases like that, it may be desirable to preserve
|
---|
1187 | information about all errors happened during method invocation and deliver
|
---|
1188 | it to the caller. The <link to="#next"/> attribute is intended
|
---|
1189 | specifically for this purpose and allows to represent a chain of errors
|
---|
1190 | through a single IVirtualBoxErrorInfo object set after method invocation.
|
---|
1191 |
|
---|
1192 | Note that errors are stored to a chain in the reverse order, i.e. the
|
---|
1193 | initial error object you query right after method invocation is the last
|
---|
1194 | error set by the callee, the object it points to in the @a next attribute
|
---|
1195 | is the previous error and so on, up to the first error (which is the last
|
---|
1196 | in the chain).
|
---|
1197 | </desc>
|
---|
1198 |
|
---|
1199 | <attribute name="resultCode" type="long" readonly="yes">
|
---|
1200 | <desc>
|
---|
1201 | Result code of the error.
|
---|
1202 | Usually, it will be the same as the result code returned
|
---|
1203 | by the method that provided this error information, but not
|
---|
1204 | always. For example, on Win32, CoCreateInstance() will most
|
---|
1205 | likely return E_NOINTERFACE upon unsuccessful component
|
---|
1206 | instantiation attempt, but not the value the component factory
|
---|
1207 | returned. Value is typed 'long', not 'result',
|
---|
1208 | to make interface usable from scripting languages.
|
---|
1209 | <note>
|
---|
1210 | In MS COM, there is no equivalent.
|
---|
1211 | In XPCOM, it is the same as nsIException::result.
|
---|
1212 | </note>
|
---|
1213 | </desc>
|
---|
1214 | </attribute>
|
---|
1215 |
|
---|
1216 | <attribute name="interfaceID" type="uuid" mod="string" readonly="yes">
|
---|
1217 | <desc>
|
---|
1218 | UUID of the interface that defined the error.
|
---|
1219 | <note>
|
---|
1220 | In MS COM, it is the same as IErrorInfo::GetGUID, except for the
|
---|
1221 | data type.
|
---|
1222 | In XPCOM, there is no equivalent.
|
---|
1223 | </note>
|
---|
1224 | </desc>
|
---|
1225 | </attribute>
|
---|
1226 |
|
---|
1227 | <attribute name="component" type="wstring" readonly="yes">
|
---|
1228 | <desc>
|
---|
1229 | Name of the component that generated the error.
|
---|
1230 | <note>
|
---|
1231 | In MS COM, it is the same as IErrorInfo::GetSource.
|
---|
1232 | In XPCOM, there is no equivalent.
|
---|
1233 | </note>
|
---|
1234 | </desc>
|
---|
1235 | </attribute>
|
---|
1236 |
|
---|
1237 | <attribute name="text" type="wstring" readonly="yes">
|
---|
1238 | <desc>
|
---|
1239 | Text description of the error.
|
---|
1240 | <note>
|
---|
1241 | In MS COM, it is the same as IErrorInfo::GetDescription.
|
---|
1242 | In XPCOM, it is the same as nsIException::message.
|
---|
1243 | </note>
|
---|
1244 | </desc>
|
---|
1245 | </attribute>
|
---|
1246 |
|
---|
1247 | <attribute name="next" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
1248 | <desc>
|
---|
1249 | Next error object if there is any, or @c null otherwise.
|
---|
1250 | <note>
|
---|
1251 | In MS COM, there is no equivalent.
|
---|
1252 | In XPCOM, it is the same as nsIException::inner.
|
---|
1253 | </note>
|
---|
1254 | </desc>
|
---|
1255 | </attribute>
|
---|
1256 |
|
---|
1257 | </interface>
|
---|
1258 |
|
---|
1259 | <!--
|
---|
1260 | // IVirtualBox
|
---|
1261 | /////////////////////////////////////////////////////////////////////////
|
---|
1262 | -->
|
---|
1263 |
|
---|
1264 | <interface
|
---|
1265 | name="IDHCPServer" extends="$unknown"
|
---|
1266 | uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3"
|
---|
1267 | wsmap="managed"
|
---|
1268 | >
|
---|
1269 | <desc>
|
---|
1270 | The IDHCPServer interface represents the vbox dhcp server configuration.
|
---|
1271 |
|
---|
1272 | To enumerate all the dhcp servers on the host, use the
|
---|
1273 | <link to="IVirtualBox::DHCPServers"/> attribute.
|
---|
1274 | </desc>
|
---|
1275 |
|
---|
1276 | <attribute name="enabled" type="boolean">
|
---|
1277 | <desc>
|
---|
1278 | specifies if the dhcp server is enabled
|
---|
1279 | </desc>
|
---|
1280 | </attribute>
|
---|
1281 |
|
---|
1282 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
1283 | <desc>
|
---|
1284 | specifies server IP
|
---|
1285 | </desc>
|
---|
1286 | </attribute>
|
---|
1287 |
|
---|
1288 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
1289 | <desc>
|
---|
1290 | specifies server network mask
|
---|
1291 | </desc>
|
---|
1292 | </attribute>
|
---|
1293 |
|
---|
1294 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
1295 | <desc>
|
---|
1296 | specifies internal network name the server is used for
|
---|
1297 | </desc>
|
---|
1298 | </attribute>
|
---|
1299 |
|
---|
1300 | <attribute name="lowerIP" type="wstring" readonly="yes">
|
---|
1301 | <desc>
|
---|
1302 | specifies from IP address in server address range
|
---|
1303 | </desc>
|
---|
1304 | </attribute>
|
---|
1305 |
|
---|
1306 | <attribute name="upperIP" type="wstring" readonly="yes">
|
---|
1307 | <desc>
|
---|
1308 | specifies to IP address in server address range
|
---|
1309 | </desc>
|
---|
1310 | </attribute>
|
---|
1311 |
|
---|
1312 | <method name="setConfiguration">
|
---|
1313 | <desc>
|
---|
1314 | configures the server
|
---|
1315 | <result name="E_INVALIDARG">
|
---|
1316 | invalid configuration supplied
|
---|
1317 | </result>
|
---|
1318 | </desc>
|
---|
1319 | <param name="IPAddress" type="wstring" dir="in">
|
---|
1320 | <desc>
|
---|
1321 | server IP address
|
---|
1322 | </desc>
|
---|
1323 | </param>
|
---|
1324 | <param name="networkMask" type="wstring" dir="in">
|
---|
1325 | <desc>
|
---|
1326 | server network mask
|
---|
1327 | </desc>
|
---|
1328 | </param>
|
---|
1329 | <param name="FromIPAddress" type="wstring" dir="in">
|
---|
1330 | <desc>
|
---|
1331 | server From IP address for address range
|
---|
1332 | </desc>
|
---|
1333 | </param>
|
---|
1334 | <param name="ToIPAddress" type="wstring" dir="in">
|
---|
1335 | <desc>
|
---|
1336 | server To IP address for address range
|
---|
1337 | </desc>
|
---|
1338 | </param>
|
---|
1339 | </method>
|
---|
1340 |
|
---|
1341 | <method name="start">
|
---|
1342 | <desc>
|
---|
1343 | Starts DHCP server process.
|
---|
1344 | <result name="E_FAIL">
|
---|
1345 | Failed to start the process.
|
---|
1346 | </result>
|
---|
1347 | </desc>
|
---|
1348 | <param name="networkName" type="wstring" dir="in">
|
---|
1349 | <desc>
|
---|
1350 | Name of internal network DHCP server should attach to.
|
---|
1351 | </desc>
|
---|
1352 | </param>
|
---|
1353 | <param name="trunkName" type="wstring" dir="in">
|
---|
1354 | <desc>
|
---|
1355 | Name of internal network trunk.
|
---|
1356 | </desc>
|
---|
1357 | </param>
|
---|
1358 | <param name="trunkType" type="wstring" dir="in">
|
---|
1359 | <desc>
|
---|
1360 | Type of internal network trunk.
|
---|
1361 | </desc>
|
---|
1362 | </param>
|
---|
1363 | </method>
|
---|
1364 |
|
---|
1365 | <method name="stop">
|
---|
1366 | <desc>
|
---|
1367 | Stops DHCP server process.
|
---|
1368 | <result name="E_FAIL">
|
---|
1369 | Failed to stop the process.
|
---|
1370 | </result>
|
---|
1371 | </desc>
|
---|
1372 | </method>
|
---|
1373 | </interface>
|
---|
1374 |
|
---|
1375 | <interface
|
---|
1376 | name="IVirtualBox" extends="$unknown"
|
---|
1377 | uuid="e03d6527-9b72-43b5-b87f-88f1033d3866"
|
---|
1378 | wsmap="managed"
|
---|
1379 | >
|
---|
1380 | <desc>
|
---|
1381 | The IVirtualBox interface represents the main interface exposed by the
|
---|
1382 | product that provides virtual machine management.
|
---|
1383 |
|
---|
1384 | An instance of IVirtualBox is required for the product to do anything
|
---|
1385 | useful. Even though the interface does not expose this, internally,
|
---|
1386 | IVirtualBox is implemented as a singleton and actually lives in the
|
---|
1387 | process of the VirtualBox server (VBoxSVC.exe). This makes sure that
|
---|
1388 | IVirtualBox can track the state of all virtual machines on a particular
|
---|
1389 | host, regardless of which frontend started them.
|
---|
1390 |
|
---|
1391 | To enumerate all the virtual machines on the host, use the
|
---|
1392 | <link to="IVirtualBox::machines"/> attribute.
|
---|
1393 | </desc>
|
---|
1394 |
|
---|
1395 | <attribute name="version" type="wstring" readonly="yes">
|
---|
1396 | <desc>
|
---|
1397 | A string representing the version number of the product. The
|
---|
1398 | format is 3 integer numbers divided by dots (e.g. 1.0.1). The
|
---|
1399 | last number represents the build number and will frequently change.
|
---|
1400 | </desc>
|
---|
1401 | </attribute>
|
---|
1402 |
|
---|
1403 | <attribute name="revision" type="unsigned long" readonly="yes">
|
---|
1404 | <desc>
|
---|
1405 | The internal build revision number of the product.
|
---|
1406 | </desc>
|
---|
1407 | </attribute>
|
---|
1408 |
|
---|
1409 | <attribute name="packageType" type="wstring" readonly="yes">
|
---|
1410 | <desc>
|
---|
1411 | A string representing the package type of this product. The
|
---|
1412 | format is OS_ARCH_DIST where OS is either WINDOWS, LINUX,
|
---|
1413 | SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST
|
---|
1414 | is either GENERIC, UBUNTU_606, UBUNTU_710, or something like
|
---|
1415 | this.
|
---|
1416 | </desc>
|
---|
1417 | </attribute>
|
---|
1418 |
|
---|
1419 | <attribute name="homeFolder" type="wstring" readonly="yes">
|
---|
1420 | <desc>
|
---|
1421 | Full path to the directory where the global settings file,
|
---|
1422 | <tt>VirtualBox.xml</tt>, is stored.
|
---|
1423 |
|
---|
1424 | In this version of VirtualBox, the value of this property is
|
---|
1425 | always <tt><user_dir>/.VirtualBox</tt> (where
|
---|
1426 | <tt><user_dir></tt> is the path to the user directory,
|
---|
1427 | as determined by the host OS), and cannot be changed.
|
---|
1428 |
|
---|
1429 | This path is also used as the base to resolve relative paths in
|
---|
1430 | places where relative paths are allowed (unless otherwise
|
---|
1431 | expressly indicated).
|
---|
1432 | </desc>
|
---|
1433 | </attribute>
|
---|
1434 |
|
---|
1435 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
1436 | <desc>
|
---|
1437 | Full name of the global settings file.
|
---|
1438 | The value of this property corresponds to the value of
|
---|
1439 | <link to="#homeFolder"/> plus <tt>/VirtualBox.xml</tt>.
|
---|
1440 | </desc>
|
---|
1441 | </attribute>
|
---|
1442 |
|
---|
1443 | <attribute name="host" type="IHost" readonly="yes">
|
---|
1444 | <desc>Associated host object.</desc>
|
---|
1445 | </attribute>
|
---|
1446 |
|
---|
1447 | <attribute name="systemProperties" type="ISystemProperties" readonly="yes">
|
---|
1448 | <desc>Associated system information object.</desc>
|
---|
1449 | </attribute>
|
---|
1450 |
|
---|
1451 | <attribute name="machines" type="IMachine" readonly="yes" safearray="yes">
|
---|
1452 | <desc>
|
---|
1453 | Array of machine objects registered within this VirtualBox instance.
|
---|
1454 | </desc>
|
---|
1455 | </attribute>
|
---|
1456 |
|
---|
1457 | <attribute name="hardDisks" type="IMedium" readonly="yes" safearray="yes">
|
---|
1458 | <desc>
|
---|
1459 | Array of medium objects known to this VirtualBox installation.
|
---|
1460 |
|
---|
1461 | This array contains only base media. All differencing
|
---|
1462 | media of the given base medium can be enumerated using
|
---|
1463 | <link to="IMedium::children"/>.
|
---|
1464 | </desc>
|
---|
1465 | </attribute>
|
---|
1466 |
|
---|
1467 | <attribute name="DVDImages" type="IMedium" readonly="yes" safearray="yes">
|
---|
1468 | <desc>
|
---|
1469 | Array of CD/DVD image objects currently in use by this VirtualBox instance.
|
---|
1470 | </desc>
|
---|
1471 | </attribute>
|
---|
1472 |
|
---|
1473 | <attribute name="floppyImages" type="IMedium" readonly="yes" safearray="yes">
|
---|
1474 | <desc>
|
---|
1475 | Array of floppy image objects currently in use by this VirtualBox instance.
|
---|
1476 | </desc>
|
---|
1477 | </attribute>
|
---|
1478 |
|
---|
1479 | <attribute name="progressOperations" type="IProgress" readonly="yes" safearray="yes"/>
|
---|
1480 |
|
---|
1481 | <attribute name="guestOSTypes" type="IGuestOSType" readonly="yes" safearray="yes"/>
|
---|
1482 |
|
---|
1483 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
1484 | <desc>
|
---|
1485 | Collection of global shared folders. Global shared folders are
|
---|
1486 | available to all virtual machines.
|
---|
1487 |
|
---|
1488 | New shared folders are added to the collection using
|
---|
1489 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
1490 | removed using <link to="#removeSharedFolder"/>.
|
---|
1491 |
|
---|
1492 | <note>
|
---|
1493 | In the current version of the product, global shared folders are not
|
---|
1494 | implemented and therefore this collection is always empty.
|
---|
1495 | </note>
|
---|
1496 | </desc>
|
---|
1497 | </attribute>
|
---|
1498 |
|
---|
1499 | <attribute name="performanceCollector" type="IPerformanceCollector" readonly="yes">
|
---|
1500 | <desc>
|
---|
1501 | Associated performance collector object.
|
---|
1502 | </desc>
|
---|
1503 | </attribute>
|
---|
1504 |
|
---|
1505 | <attribute name="DHCPServers" type="IDHCPServer" safearray="yes" readonly="yes">
|
---|
1506 | <desc>
|
---|
1507 | DHCP servers.
|
---|
1508 | </desc>
|
---|
1509 | </attribute>
|
---|
1510 |
|
---|
1511 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
1512 | <desc>
|
---|
1513 | Event source for VirtualBox events.
|
---|
1514 | </desc>
|
---|
1515 | </attribute>
|
---|
1516 |
|
---|
1517 | <attribute name="extensionPackManager" type="IExtPackManager" readonly="yes">
|
---|
1518 | <desc>
|
---|
1519 | The extension pack manager.
|
---|
1520 | </desc>
|
---|
1521 | </attribute>
|
---|
1522 |
|
---|
1523 |
|
---|
1524 | <method name="composeMachineFilename">
|
---|
1525 | <desc>
|
---|
1526 | Returns a recommended full path of the settings file name for a new virtual
|
---|
1527 | machine.
|
---|
1528 |
|
---|
1529 | This API serves two purposes:
|
---|
1530 |
|
---|
1531 | <ul>
|
---|
1532 | <li>It gets called by <link to="#createMachine" /> if NULL is specified
|
---|
1533 | for the @a settingsFile argument there, which means that API should use
|
---|
1534 | a recommended default file name.</li>
|
---|
1535 |
|
---|
1536 | <li>It can be called manually by a client software before creating a machine,
|
---|
1537 | e.g. if that client wants to pre-create the machine directory to create
|
---|
1538 | virtual hard disks in that directory together with the new machine
|
---|
1539 | settings file. In that case, the file name should be stripped from the
|
---|
1540 | full settings file path returned by this function to obtain the
|
---|
1541 | machine directory.</li>
|
---|
1542 | </ul>
|
---|
1543 |
|
---|
1544 | See <link to="IMachine::name"/> and <link to="#createMachine"/> for more
|
---|
1545 | details about the machine name.
|
---|
1546 |
|
---|
1547 | If @a baseFolder is a @c null or empty string (which is recommended), the
|
---|
1548 | default machine settings folder
|
---|
1549 | (see <link to="ISystemProperties::defaultMachineFolder" />) will be used as
|
---|
1550 | a base folder for the created machine, resulting in a file name like
|
---|
1551 | "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder
|
---|
1552 | will be used.
|
---|
1553 |
|
---|
1554 | This method does not access the host disks. In particular, it does not check
|
---|
1555 | for whether a machine of this name already exists.
|
---|
1556 | </desc>
|
---|
1557 | <param name="name" type="wstring" dir="in">
|
---|
1558 | <desc>Suggested machine name.</desc>
|
---|
1559 | </param>
|
---|
1560 | <param name="baseFolder" type="wstring" dir="in">
|
---|
1561 | <desc>Base machine folder (optional).</desc>
|
---|
1562 | </param>
|
---|
1563 | <param name="file" type="wstring" dir="return">
|
---|
1564 | <desc>Fully qualified path where the machine would be created.</desc>
|
---|
1565 | </param>
|
---|
1566 | </method>
|
---|
1567 |
|
---|
1568 | <method name="createMachine">
|
---|
1569 | <desc>
|
---|
1570 | Creates a new virtual machine by creating a machine settings file at
|
---|
1571 | the given location.
|
---|
1572 |
|
---|
1573 | VirtualBox machine settings files use a custom XML dialect. Starting
|
---|
1574 | with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced,
|
---|
1575 | and machine files can be created at arbitrary locations.
|
---|
1576 |
|
---|
1577 | However, it is is recommended that machines be created in the default
|
---|
1578 | machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see
|
---|
1579 | <link to="ISystemProperties::defaultMachineFolder" />). If you specify
|
---|
1580 | NULL for the @a settingsFile argument, <link to="#composeMachineFilename" />
|
---|
1581 | is called automatically to have such a recommended name composed based
|
---|
1582 | on the machine name given in the @a name argument.
|
---|
1583 |
|
---|
1584 | If the resulting settings file already exists, this method will fail,
|
---|
1585 | unless @a forceOverwrite is set.
|
---|
1586 |
|
---|
1587 | The new machine is created unregistered, with the initial configuration
|
---|
1588 | set according to the specified guest OS type. A typical sequence of
|
---|
1589 | actions to create a new virtual machine is as follows:
|
---|
1590 |
|
---|
1591 | <ol>
|
---|
1592 | <li>
|
---|
1593 | Call this method to have a new machine created. The returned machine
|
---|
1594 | object will be "mutable" allowing to change any machine property.
|
---|
1595 | </li>
|
---|
1596 |
|
---|
1597 | <li>
|
---|
1598 | Configure the machine using the appropriate attributes and methods.
|
---|
1599 | </li>
|
---|
1600 |
|
---|
1601 | <li>
|
---|
1602 | Call <link to="IMachine::saveSettings" /> to write the settings
|
---|
1603 | to the machine's XML settings file. The configuration of the newly
|
---|
1604 | created machine will not be saved to disk until this method is
|
---|
1605 | called.
|
---|
1606 | </li>
|
---|
1607 |
|
---|
1608 | <li>
|
---|
1609 | Call <link to="#registerMachine" /> to add the machine to the list
|
---|
1610 | of machines known to VirtualBox.
|
---|
1611 | </li>
|
---|
1612 | </ol>
|
---|
1613 |
|
---|
1614 | The specified guest OS type identifier must match an ID of one of known
|
---|
1615 | guest OS types listed in the <link to="IVirtualBox::guestOSTypes"/>
|
---|
1616 | array.
|
---|
1617 |
|
---|
1618 | Optionally, you may specify an UUID of to assign to the created machine.
|
---|
1619 | However, this is not recommended and you should normally pass an empty
|
---|
1620 | (@c null) UUID to this method so that a new UUID will be automatically
|
---|
1621 | generated for every created machine. You can use UUID
|
---|
1622 | 00000000-0000-0000-0000-000000000000 as @c null value.
|
---|
1623 |
|
---|
1624 | <note>
|
---|
1625 | There is no way to change the name of the settings file or
|
---|
1626 | subfolder of the created machine directly.
|
---|
1627 | </note>
|
---|
1628 |
|
---|
1629 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1630 | @a osTypeId is invalid.
|
---|
1631 | </result>
|
---|
1632 | <result name="VBOX_E_FILE_ERROR">
|
---|
1633 | Resulting settings file name is invalid or the settings file already
|
---|
1634 | exists or could not be created due to an I/O error.
|
---|
1635 | </result>
|
---|
1636 | <result name="E_INVALIDARG">
|
---|
1637 | @a name is empty or @c null.
|
---|
1638 | </result>
|
---|
1639 | </desc>
|
---|
1640 |
|
---|
1641 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1642 | <desc>Fully qualified path where the settings file should be created,
|
---|
1643 | or NULL for a default folder and file based on the @a name argument
|
---|
1644 | (see <link to="#composeMachineFilename" />).</desc>
|
---|
1645 | </param>
|
---|
1646 | <param name="name" type="wstring" dir="in">
|
---|
1647 | <desc>Machine name.</desc>
|
---|
1648 | </param>
|
---|
1649 | <param name="osTypeId" type="wstring" dir="in">
|
---|
1650 | <desc>Guest OS Type ID.</desc>
|
---|
1651 | </param>
|
---|
1652 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
1653 | <desc>Machine UUID (optional).</desc>
|
---|
1654 | </param>
|
---|
1655 | <param name="forceOverwrite" type="boolean" dir="in">
|
---|
1656 | <desc>If true, an existing machine settings file will be overwritten.</desc>
|
---|
1657 | </param>
|
---|
1658 | <param name="machine" type="IMachine" dir="return">
|
---|
1659 | <desc>Created machine object.</desc>
|
---|
1660 | </param>
|
---|
1661 | </method>
|
---|
1662 |
|
---|
1663 | <method name="openMachine">
|
---|
1664 | <desc>
|
---|
1665 | Opens a virtual machine from the existing settings file.
|
---|
1666 | The opened machine remains unregistered until you call
|
---|
1667 | <link to="#registerMachine"/>.
|
---|
1668 |
|
---|
1669 | The specified settings file name can be absolute
|
---|
1670 | (full path) or relative to the <link to="IVirtualBox::homeFolder">
|
---|
1671 | VirtualBox home directory</link>. This file must exist
|
---|
1672 | and must be a valid machine settings file whose contents
|
---|
1673 | will be used to construct the machine object.
|
---|
1674 |
|
---|
1675 | <result name="VBOX_E_FILE_ERROR">
|
---|
1676 | Settings file name invalid, not found or sharing violation.
|
---|
1677 | </result>
|
---|
1678 | </desc>
|
---|
1679 | <param name="settingsFile" type="wstring" dir="in">
|
---|
1680 | <desc>
|
---|
1681 | Name of the machine settings file.
|
---|
1682 | </desc>
|
---|
1683 | </param>
|
---|
1684 | <param name="machine" type="IMachine" dir="return">
|
---|
1685 | <desc>Opened machine object.</desc>
|
---|
1686 | </param>
|
---|
1687 | <note>
|
---|
1688 | <link to="IMachine::settingsModified"/> will return
|
---|
1689 | @c false for the created machine, until any of machine settings
|
---|
1690 | are changed.
|
---|
1691 | </note>
|
---|
1692 | </method>
|
---|
1693 |
|
---|
1694 | <method name="registerMachine">
|
---|
1695 | <desc>
|
---|
1696 |
|
---|
1697 | Registers the machine previously created using
|
---|
1698 | <link to="#createMachine"/> or opened using
|
---|
1699 | <link to="#openMachine"/> within this VirtualBox installation. After
|
---|
1700 | successful method invocation, the
|
---|
1701 | <link to="IMachineRegisteredEvent"/> event is fired.
|
---|
1702 |
|
---|
1703 | <note>
|
---|
1704 | This method implicitly calls <link to="IMachine::saveSettings"/>
|
---|
1705 | to save all current machine settings before registering it.
|
---|
1706 | </note>
|
---|
1707 |
|
---|
1708 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1709 | No matching virtual machine found.
|
---|
1710 | </result>
|
---|
1711 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1712 | Virtual machine was not created within this VirtualBox instance.
|
---|
1713 | </result>
|
---|
1714 |
|
---|
1715 | </desc>
|
---|
1716 | <param name="machine" type="IMachine" dir="in"/>
|
---|
1717 | </method>
|
---|
1718 |
|
---|
1719 | <method name="findMachine">
|
---|
1720 | <desc>
|
---|
1721 | Attempts to find a virtual machine given its name or UUID.
|
---|
1722 |
|
---|
1723 | <note>Inaccessible machines cannot be found by name, only by UUID, because their name
|
---|
1724 | cannot safely be determined.</note>
|
---|
1725 |
|
---|
1726 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1727 | Could not find registered machine matching @a nameOrId.
|
---|
1728 | </result>
|
---|
1729 |
|
---|
1730 | </desc>
|
---|
1731 | <param name="nameOrId" type="wstring" dir="in">
|
---|
1732 | <desc>What to search for. This can either be the UUID or the name of a virtual machine.</desc>
|
---|
1733 | </param>
|
---|
1734 | <param name="machine" type="IMachine" dir="return">
|
---|
1735 | <desc>Machine object, if found.</desc>
|
---|
1736 | </param>
|
---|
1737 | </method>
|
---|
1738 |
|
---|
1739 | <method name="createAppliance">
|
---|
1740 | <desc>
|
---|
1741 | Creates a new appliance object, which represents an appliance in the Open Virtual Machine
|
---|
1742 | Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
|
---|
1743 | machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
|
---|
1744 | </desc>
|
---|
1745 | <param name="appliance" type="IAppliance" dir="return">
|
---|
1746 | <desc>New appliance.</desc>
|
---|
1747 | </param>
|
---|
1748 | </method>
|
---|
1749 |
|
---|
1750 | <method name="createHardDisk">
|
---|
1751 | <desc>
|
---|
1752 | Creates a new base medium object that will use the given storage
|
---|
1753 | format and location for medium data.
|
---|
1754 |
|
---|
1755 | Note that the actual storage unit is not created by this method. In
|
---|
1756 | order to do it, and before you are able to attach the created medium
|
---|
1757 | to virtual machines, you must call one of the following methods to
|
---|
1758 | allocate a format-specific storage unit at the specified location:
|
---|
1759 | <ul>
|
---|
1760 | <li><link to="IMedium::createBaseStorage"/></li>
|
---|
1761 | <li><link to="IMedium::createDiffStorage"/></li>
|
---|
1762 | </ul>
|
---|
1763 |
|
---|
1764 | Some medium attributes, such as <link to="IMedium::id"/>, may
|
---|
1765 | remain uninitialized until the medium storage unit is successfully
|
---|
1766 | created by one of the above methods.
|
---|
1767 |
|
---|
1768 | After the storage unit is successfully created, it will be
|
---|
1769 | accessible through the <link to="#findMedium"/> method and can
|
---|
1770 | be found in the <link to="#hardDisks"/> array.
|
---|
1771 |
|
---|
1772 | The list of all storage formats supported by this VirtualBox
|
---|
1773 | installation can be obtained using
|
---|
1774 | <link to="ISystemProperties::mediumFormats"/>. If the @a format
|
---|
1775 | attribute is empty or @c null then the default storage format
|
---|
1776 | specified by <link to="ISystemProperties::defaultHardDiskFormat"/> will
|
---|
1777 | be used for creating a storage unit of the medium.
|
---|
1778 |
|
---|
1779 | Note that the format of the location string is storage format specific.
|
---|
1780 | See <link to="IMedium::location"/> and IMedium for more details.
|
---|
1781 |
|
---|
1782 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1783 | @a format identifier is invalid. See
|
---|
1784 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
1785 | </result>
|
---|
1786 | <result name="VBOX_E_FILE_ERROR">
|
---|
1787 | @a location is a not valid file name (for file-based formats only).
|
---|
1788 | </result>
|
---|
1789 | </desc>
|
---|
1790 | <param name="format" type="wstring" dir="in">
|
---|
1791 | <desc>
|
---|
1792 | Identifier of the storage format to use for the new medium.
|
---|
1793 | </desc>
|
---|
1794 | </param>
|
---|
1795 | <param name="location" type="wstring" dir="in">
|
---|
1796 | <desc>
|
---|
1797 | Location of the storage unit for the new medium.
|
---|
1798 | </desc>
|
---|
1799 | </param>
|
---|
1800 | <param name="medium" type="IMedium" dir="return">
|
---|
1801 | <desc>Created medium object.</desc>
|
---|
1802 | </param>
|
---|
1803 | </method>
|
---|
1804 |
|
---|
1805 | <method name="openMedium">
|
---|
1806 | <desc>
|
---|
1807 | Opens a medium from an existing storage location.
|
---|
1808 |
|
---|
1809 | Once a medium has been opened, it can be passed to other VirtualBox
|
---|
1810 | methods, in particular to <link to="IMachine::attachDevice" />.
|
---|
1811 |
|
---|
1812 | Depending on the given device type, the file at the storage location
|
---|
1813 | must be in one of the media formats understood by VirtualBox:
|
---|
1814 |
|
---|
1815 | <ul>
|
---|
1816 | <li>With a "HardDisk" device type, the file must be a hard disk image
|
---|
1817 | in one of the formats supported by VirtualBox (see
|
---|
1818 | <link to="ISystemProperties::mediumFormats" />).
|
---|
1819 | After this method succeeds, if the medium is a base medium, it
|
---|
1820 | will be added to the <link to="#hardDisks"/> array attribute. </li>
|
---|
1821 | <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
|
---|
1822 | After this method succeeds, the medium will be added to the
|
---|
1823 | <link to="#DVDImages"/> array attribute.</li>
|
---|
1824 | <li>With a "Floppy" device type, the file must be an RAW floppy image.
|
---|
1825 | After this method succeeds, the medium will be added to the
|
---|
1826 | <link to="#floppyImages"/> array attribute.</li>
|
---|
1827 | </ul>
|
---|
1828 |
|
---|
1829 | After having been opened, the medium can be found by the <link to="#findMedium"/>
|
---|
1830 | method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
|
---|
1831 |
|
---|
1832 | The UUID of the newly opened medium will either be retrieved from the
|
---|
1833 | storage location, if the format supports it (e.g. for hard disk images),
|
---|
1834 | or a new UUID will be randomly generated (e.g. for ISO and RAW files).
|
---|
1835 | If for some reason you need to change the medium's UUID, use
|
---|
1836 | <link to="IMedium::setIDs" />.
|
---|
1837 |
|
---|
1838 | If a differencing hard disk medium is to be opened by this method, the
|
---|
1839 | operation will succeed only if its parent medium and all ancestors,
|
---|
1840 | if any, are already known to this VirtualBox installation (for example,
|
---|
1841 | were opened by this method before).
|
---|
1842 |
|
---|
1843 | This method attempts to guess the storage format of the specified medium
|
---|
1844 | by reading medium data at the specified location.
|
---|
1845 |
|
---|
1846 | If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
|
---|
1847 | the image is opened for read/write access and must have according permissions,
|
---|
1848 | as VirtualBox may actually write status information into the disk's metadata
|
---|
1849 | sections.
|
---|
1850 |
|
---|
1851 | Note that write access is required for all typical hard disk usage in VirtualBox,
|
---|
1852 | since VirtualBox may need to write metadata such as a UUID into the image.
|
---|
1853 | The only exception is opening a source image temporarily for copying and
|
---|
1854 | cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
|
---|
1855 | again soon.
|
---|
1856 |
|
---|
1857 | The format of the location string is storage format specific. See
|
---|
1858 | <link to="IMedium::location"/> and IMedium for more details.
|
---|
1859 |
|
---|
1860 | Prior to VirtualBox 4.0, opening a medium added it to a global media
|
---|
1861 | registry in the VirtualBox.xml file, which was shared between all machines
|
---|
1862 | and made transporting machines and their media from one host to another
|
---|
1863 | difficult.
|
---|
1864 |
|
---|
1865 | Starting with VirtualBox 4.0, media are only added to a registry when
|
---|
1866 | they are attached to a machine. Machines created with VirtualBox 4.0
|
---|
1867 | or later can have their own media registry. As a result, a medium attached
|
---|
1868 | to such a machine will be remembered in that machine's XML settings file.
|
---|
1869 | Media attached to older machines will continue to be added to the global
|
---|
1870 | registry.
|
---|
1871 |
|
---|
1872 | <result name="VBOX_E_FILE_ERROR">
|
---|
1873 | Invalid medium storage file location or could not find the medium
|
---|
1874 | at the specified location.
|
---|
1875 | </result>
|
---|
1876 | <result name="VBOX_E_IPRT_ERROR">
|
---|
1877 | Could not get medium storage format.
|
---|
1878 | </result>
|
---|
1879 | <result name="E_INVALIDARG">
|
---|
1880 | Invalid medium storage format.
|
---|
1881 | </result>
|
---|
1882 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
1883 | Medium has already been added to a media registry.
|
---|
1884 | </result>
|
---|
1885 | </desc>
|
---|
1886 | <param name="location" type="wstring" dir="in">
|
---|
1887 | <desc>
|
---|
1888 | Location of the storage unit that contains medium data in one of
|
---|
1889 | the supported storage formats.
|
---|
1890 | </desc>
|
---|
1891 | </param>
|
---|
1892 | <param name="deviceType" type="DeviceType" dir="in">
|
---|
1893 | <desc>
|
---|
1894 | Must be one of "HardDisk", "DVD" or "Floppy".
|
---|
1895 | </desc>
|
---|
1896 | </param>
|
---|
1897 | <param name="accessMode" type="AccessMode" dir="in">
|
---|
1898 | <desc>Whether to open the image in read/write or read-only mode. For
|
---|
1899 | a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
|
---|
1900 | </param>
|
---|
1901 | <param name="medium" type="IMedium" dir="return">
|
---|
1902 | <desc>Opened medium object.</desc>
|
---|
1903 | </param>
|
---|
1904 | </method>
|
---|
1905 |
|
---|
1906 | <method name="findMedium">
|
---|
1907 | <desc>
|
---|
1908 | Returns a medium of the given type that uses the given fully qualified
|
---|
1909 | location or UUID to store medium data.
|
---|
1910 |
|
---|
1911 | The given medium must be known to this VirtualBox installation, i.e.
|
---|
1912 | it must be previously created by <link to="#createHardDisk"/> or opened
|
---|
1913 | by <link to="#openMedium"/>.
|
---|
1914 |
|
---|
1915 | The search is done by comparing the value of the @a location argument to
|
---|
1916 | the <link to="IMedium::location"/> and <link to="IMedium::id" />
|
---|
1917 | attributes of each known medium.
|
---|
1918 |
|
---|
1919 | On case sensitive file systems, a case sensitive comparison is performed,
|
---|
1920 | otherwise the case of symbols in the file path is ignored.
|
---|
1921 |
|
---|
1922 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
1923 | No medium object matching @a location found.
|
---|
1924 | </result>
|
---|
1925 | </desc>
|
---|
1926 | <param name="location" type="wstring" dir="in">
|
---|
1927 | <desc>What to search for. This can either be the UUID or the location string of an open medium.</desc>
|
---|
1928 | </param>
|
---|
1929 | <param name="type" type="DeviceType" dir="in">
|
---|
1930 | <desc>Device type (must be HardDisk, DVD or Floppy)</desc>
|
---|
1931 | </param>
|
---|
1932 | <param name="medium" type="IMedium" dir="return">
|
---|
1933 | <desc>Medium object, if found.</desc>
|
---|
1934 | </param>
|
---|
1935 | </method>
|
---|
1936 |
|
---|
1937 | <method name="getGuestOSType">
|
---|
1938 | <desc>
|
---|
1939 | Returns an object describing the specified guest OS type.
|
---|
1940 |
|
---|
1941 | The requested guest OS type is specified using a string which is a
|
---|
1942 | mnemonic identifier of the guest operating system, such as
|
---|
1943 | <tt>"win31"</tt> or <tt>"ubuntu"</tt>. The guest OS type ID of a
|
---|
1944 | particular virtual machine can be read or set using the
|
---|
1945 | <link to="IMachine::OSTypeId"/> attribute.
|
---|
1946 |
|
---|
1947 | The <link to="IVirtualBox::guestOSTypes"/> collection contains all
|
---|
1948 | available guest OS type objects. Each object has an
|
---|
1949 | <link to="IGuestOSType::id"/> attribute which contains an identifier of
|
---|
1950 | the guest OS this object describes.
|
---|
1951 |
|
---|
1952 | <result name="E_INVALIDARG">
|
---|
1953 | @a id is not a valid Guest OS type.
|
---|
1954 | </result>
|
---|
1955 |
|
---|
1956 | </desc>
|
---|
1957 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
1958 | <desc>Guest OS type ID string.</desc>
|
---|
1959 | </param>
|
---|
1960 | <param name="type" type="IGuestOSType" dir="return">
|
---|
1961 | <desc>Guest OS type object.</desc>
|
---|
1962 | </param>
|
---|
1963 | </method>
|
---|
1964 |
|
---|
1965 | <method name="createSharedFolder">
|
---|
1966 | <desc>
|
---|
1967 | Creates a new global shared folder by associating the given logical
|
---|
1968 | name with the given host path, adds it to the collection of shared
|
---|
1969 | folders and starts sharing it. Refer to the description of
|
---|
1970 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
1971 | <note>
|
---|
1972 | In the current implementation, this operation is not
|
---|
1973 | implemented.
|
---|
1974 | </note>
|
---|
1975 | </desc>
|
---|
1976 | <param name="name" type="wstring" dir="in">
|
---|
1977 | <desc>Unique logical name of the shared folder.</desc>
|
---|
1978 | </param>
|
---|
1979 | <param name="hostPath" type="wstring" dir="in">
|
---|
1980 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
1981 | </param>
|
---|
1982 | <param name="writable" type="boolean" dir="in">
|
---|
1983 | <desc>Whether the share is writable or readonly</desc>
|
---|
1984 | </param>
|
---|
1985 | <param name="automount" type="boolean" dir="in">
|
---|
1986 | <desc>Whether the share gets automatically mounted by the guest
|
---|
1987 | or not.</desc>
|
---|
1988 | </param>
|
---|
1989 | </method>
|
---|
1990 |
|
---|
1991 | <method name="removeSharedFolder">
|
---|
1992 | <desc>
|
---|
1993 | Removes the global shared folder with the given name previously
|
---|
1994 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
1995 | shared folders and stops sharing it.
|
---|
1996 | <note>
|
---|
1997 | In the current implementation, this operation is not
|
---|
1998 | implemented.
|
---|
1999 | </note>
|
---|
2000 | </desc>
|
---|
2001 | <param name="name" type="wstring" dir="in">
|
---|
2002 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
2003 | </param>
|
---|
2004 | </method>
|
---|
2005 |
|
---|
2006 | <method name="getExtraDataKeys">
|
---|
2007 | <desc>
|
---|
2008 | Returns an array representing the global extra data keys which currently
|
---|
2009 | have values defined.
|
---|
2010 | </desc>
|
---|
2011 | <param name="value" type="wstring" dir="return" safearray="yes">
|
---|
2012 | <desc>Array of extra data keys.</desc>
|
---|
2013 | </param>
|
---|
2014 | </method>
|
---|
2015 |
|
---|
2016 | <method name="getExtraData">
|
---|
2017 | <desc>
|
---|
2018 | Returns associated global extra data.
|
---|
2019 |
|
---|
2020 | If the requested data @a key does not exist, this function will
|
---|
2021 | succeed and return an empty string in the @a value argument.
|
---|
2022 |
|
---|
2023 | <result name="VBOX_E_FILE_ERROR">
|
---|
2024 | Settings file not accessible.
|
---|
2025 | </result>
|
---|
2026 | <result name="VBOX_E_XML_ERROR">
|
---|
2027 | Could not parse the settings file.
|
---|
2028 | </result>
|
---|
2029 |
|
---|
2030 | </desc>
|
---|
2031 | <param name="key" type="wstring" dir="in">
|
---|
2032 | <desc>Name of the data key to get.</desc>
|
---|
2033 | </param>
|
---|
2034 | <param name="value" type="wstring" dir="return">
|
---|
2035 | <desc>Value of the requested data key.</desc>
|
---|
2036 | </param>
|
---|
2037 | </method>
|
---|
2038 |
|
---|
2039 | <method name="setExtraData">
|
---|
2040 | <desc>
|
---|
2041 | Sets associated global extra data.
|
---|
2042 |
|
---|
2043 | If you pass @c null or empty string as a key @a value, the given @a key
|
---|
2044 | will be deleted.
|
---|
2045 |
|
---|
2046 | <note>
|
---|
2047 | Before performing the actual data change, this method will ask all
|
---|
2048 | registered event listener using the
|
---|
2049 | <link to="IExtraDataCanChangeEvent"/>
|
---|
2050 | notification for a permission. If one of the listeners refuses the
|
---|
2051 | new value, the change will not be performed.
|
---|
2052 | </note>
|
---|
2053 | <note>
|
---|
2054 | On success, the
|
---|
2055 | <link to="IExtraDataChangedEvent"/> notification
|
---|
2056 | is called to inform all registered listeners about a successful data
|
---|
2057 | change.
|
---|
2058 | </note>
|
---|
2059 |
|
---|
2060 | <result name="VBOX_E_FILE_ERROR">
|
---|
2061 | Settings file not accessible.
|
---|
2062 | </result>
|
---|
2063 | <result name="VBOX_E_XML_ERROR">
|
---|
2064 | Could not parse the settings file.
|
---|
2065 | </result>
|
---|
2066 | <result name="E_ACCESSDENIED">
|
---|
2067 | Modification request refused.
|
---|
2068 | </result>
|
---|
2069 |
|
---|
2070 | </desc>
|
---|
2071 | <param name="key" type="wstring" dir="in">
|
---|
2072 | <desc>Name of the data key to set.</desc>
|
---|
2073 | </param>
|
---|
2074 | <param name="value" type="wstring" dir="in">
|
---|
2075 | <desc>Value to assign to the key.</desc>
|
---|
2076 | </param>
|
---|
2077 | </method>
|
---|
2078 |
|
---|
2079 | <!--method name="createDHCPServerForInterface">
|
---|
2080 | <desc>
|
---|
2081 | Creates a dhcp server settings to be used for the given interface
|
---|
2082 | <result name="E_INVALIDARG">
|
---|
2083 | Host network interface @a name already exists.
|
---|
2084 | </result>
|
---|
2085 | </desc>
|
---|
2086 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2087 | <desc>Network Interface</desc>
|
---|
2088 | </param>
|
---|
2089 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2090 | <desc>Dhcp server settings</desc>
|
---|
2091 | </param>
|
---|
2092 | </method-->
|
---|
2093 |
|
---|
2094 | <method name="createDHCPServer">
|
---|
2095 | <desc>
|
---|
2096 | Creates a dhcp server settings to be used for the given internal network name
|
---|
2097 | <result name="E_INVALIDARG">
|
---|
2098 | Host network interface @a name already exists.
|
---|
2099 | </result>
|
---|
2100 | </desc>
|
---|
2101 | <param name="name" type="wstring" dir="in">
|
---|
2102 | <desc>server name</desc>
|
---|
2103 | </param>
|
---|
2104 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2105 | <desc>Dhcp server settings</desc>
|
---|
2106 | </param>
|
---|
2107 | </method>
|
---|
2108 |
|
---|
2109 | <method name="findDHCPServerByNetworkName">
|
---|
2110 | <desc>
|
---|
2111 | Searches a dhcp server settings to be used for the given internal network name
|
---|
2112 | <result name="E_INVALIDARG">
|
---|
2113 | Host network interface @a name already exists.
|
---|
2114 | </result>
|
---|
2115 |
|
---|
2116 | </desc>
|
---|
2117 | <param name="name" type="wstring" dir="in">
|
---|
2118 | <desc>server name</desc>
|
---|
2119 | </param>
|
---|
2120 | <param name="server" type="IDHCPServer" dir="return">
|
---|
2121 | <desc>Dhcp server settings</desc>
|
---|
2122 | </param>
|
---|
2123 | </method>
|
---|
2124 |
|
---|
2125 | <!--method name="findDHCPServerForInterface">
|
---|
2126 | <desc>
|
---|
2127 | Searches a dhcp server settings to be used for the given interface
|
---|
2128 | <result name="E_INVALIDARG">
|
---|
2129 | Host network interface @a name already exists.
|
---|
2130 | </result>
|
---|
2131 | </desc>
|
---|
2132 | <param name="interface" type="IHostNetworkInterface" dir="in">
|
---|
2133 | <desc>Network Interface</desc>
|
---|
2134 | </param>
|
---|
2135 | <param name="server" type="IDHCPServer" dir="out">
|
---|
2136 | <desc>Dhcp server settings</desc>
|
---|
2137 | </param>
|
---|
2138 | </method-->
|
---|
2139 |
|
---|
2140 | <method name="removeDHCPServer">
|
---|
2141 | <desc>
|
---|
2142 | Removes the dhcp server settings
|
---|
2143 | <result name="E_INVALIDARG">
|
---|
2144 | Host network interface @a name already exists.
|
---|
2145 | </result>
|
---|
2146 | </desc>
|
---|
2147 | <param name="server" type="IDHCPServer" dir="in">
|
---|
2148 | <desc>Dhcp server settings to be removed</desc>
|
---|
2149 | </param>
|
---|
2150 | </method>
|
---|
2151 |
|
---|
2152 |
|
---|
2153 | <method name="checkFirmwarePresent">
|
---|
2154 | <desc>
|
---|
2155 | Check if this VirtualBox installation has a firmware
|
---|
2156 | of the given type available, either system-wide or per-user.
|
---|
2157 | Optionally, this may return a hint where this firmware can be
|
---|
2158 | downloaded from.
|
---|
2159 | </desc>
|
---|
2160 | <param name="firmwareType" type="FirmwareType" dir="in">
|
---|
2161 | <desc>
|
---|
2162 | Type of firmware to check.
|
---|
2163 | </desc>
|
---|
2164 | </param>
|
---|
2165 | <param name="version" type="wstring" dir="in">
|
---|
2166 | <desc>Expected version number, usually empty string (presently ignored).</desc>
|
---|
2167 | </param>
|
---|
2168 |
|
---|
2169 | <param name="url" type="wstring" dir="out">
|
---|
2170 | <desc>
|
---|
2171 | Suggested URL to download this firmware from.
|
---|
2172 | </desc>
|
---|
2173 | </param>
|
---|
2174 |
|
---|
2175 | <param name="file" type="wstring" dir="out">
|
---|
2176 | <desc>
|
---|
2177 | Filename of firmware, only valid if result == TRUE.
|
---|
2178 | </desc>
|
---|
2179 | </param>
|
---|
2180 |
|
---|
2181 | <param name="result" type="boolean" dir="return">
|
---|
2182 | <desc>If firmware of this type and version is available.</desc>
|
---|
2183 | </param>
|
---|
2184 | </method>
|
---|
2185 |
|
---|
2186 | <method name="VRDERegisterLibrary">
|
---|
2187 | <desc>
|
---|
2188 | Appends a VRDE library to this VirtualBox installation.
|
---|
2189 |
|
---|
2190 | The library implements a VirtualBox Remote Desktop Extension (VRDE),
|
---|
2191 | which is used to remotely connect to the virtual machines.
|
---|
2192 |
|
---|
2193 | The system library extension (".DLL" or ".so") must be omitted.
|
---|
2194 | The library must reside in the VirtualBox installation directory.
|
---|
2195 | </desc>
|
---|
2196 | <param name="name" type="wstring" dir="in">
|
---|
2197 | <desc>The library name.</desc>
|
---|
2198 | </param>
|
---|
2199 | </method>
|
---|
2200 |
|
---|
2201 | <method name="VRDEUnregisterLibrary">
|
---|
2202 | <desc>
|
---|
2203 | Removes a VRDE library from this VirtualBox installation.
|
---|
2204 | </desc>
|
---|
2205 | <param name="name" type="wstring" dir="in">
|
---|
2206 | <desc>The library name.</desc>
|
---|
2207 | </param>
|
---|
2208 | </method>
|
---|
2209 |
|
---|
2210 | <method name="VRDEListLibraries">
|
---|
2211 | <desc>
|
---|
2212 | List registered libraries.
|
---|
2213 | </desc>
|
---|
2214 | <param name="names" type="wstring" dir="return" safearray="yes">
|
---|
2215 | <desc>Array of names of the libraries.</desc>
|
---|
2216 | </param>
|
---|
2217 | </method>
|
---|
2218 |
|
---|
2219 | <method name="VRDEIsLibraryRegistered">
|
---|
2220 | <desc>
|
---|
2221 | Check if the library is registered.
|
---|
2222 | </desc>
|
---|
2223 | <param name="name" type="wstring" dir="in">
|
---|
2224 | <desc>The library name.</desc>
|
---|
2225 | </param>
|
---|
2226 | <param name="registered" type="boolean" dir="return">
|
---|
2227 | <desc>Whether the library is registered.</desc>
|
---|
2228 | </param>
|
---|
2229 | </method>
|
---|
2230 |
|
---|
2231 | </interface>
|
---|
2232 |
|
---|
2233 | <!--
|
---|
2234 | // IVFSExplorer
|
---|
2235 | /////////////////////////////////////////////////////////////////////////
|
---|
2236 | -->
|
---|
2237 |
|
---|
2238 | <enum
|
---|
2239 | name="VFSType"
|
---|
2240 | uuid="813999ba-b949-48a8-9230-aadc6285e2f2"
|
---|
2241 | >
|
---|
2242 | <desc>
|
---|
2243 | Virtual file systems supported by VFSExplorer.
|
---|
2244 | </desc>
|
---|
2245 |
|
---|
2246 | <const name="File" value="1" />
|
---|
2247 | <const name="Cloud" value="2" />
|
---|
2248 | <const name="S3" value="3" />
|
---|
2249 | <const name="WebDav" value="4" />
|
---|
2250 | </enum>
|
---|
2251 |
|
---|
2252 | <enum
|
---|
2253 | name="VFSFileType"
|
---|
2254 | uuid="714333cd-44e2-415f-a245-d378fa9b1242"
|
---|
2255 | >
|
---|
2256 | <desc>
|
---|
2257 | File types known by VFSExplorer.
|
---|
2258 | </desc>
|
---|
2259 |
|
---|
2260 | <const name="Unknown" value="1" />
|
---|
2261 | <const name="Fifo" value="2" />
|
---|
2262 | <const name="DevChar" value="3" />
|
---|
2263 | <const name="Directory" value="4" />
|
---|
2264 | <const name="DevBlock" value="5" />
|
---|
2265 | <const name="File" value="6" />
|
---|
2266 | <const name="SymLink" value="7" />
|
---|
2267 | <const name="Socket" value="8" />
|
---|
2268 | <const name="WhiteOut" value="9" />
|
---|
2269 | </enum>
|
---|
2270 |
|
---|
2271 | <interface
|
---|
2272 | name="IVFSExplorer" extends="$unknown"
|
---|
2273 | uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f"
|
---|
2274 | wsmap="managed"
|
---|
2275 | >
|
---|
2276 | <desc>
|
---|
2277 | The VFSExplorer interface unifies access to different file system
|
---|
2278 | types. This includes local file systems as well remote file systems like
|
---|
2279 | S3. For a list of supported types see <link to="VFSType" />.
|
---|
2280 | An instance of this is returned by <link to="IAppliance::createVFSExplorer" />.
|
---|
2281 | </desc>
|
---|
2282 |
|
---|
2283 | <attribute name="path" type="wstring" readonly="yes">
|
---|
2284 | <desc>Returns the current path in the virtual file system.</desc>
|
---|
2285 | </attribute>
|
---|
2286 |
|
---|
2287 | <attribute name="type" type="VFSType" readonly="yes">
|
---|
2288 | <desc>Returns the file system type which is currently in use.</desc>
|
---|
2289 | </attribute>
|
---|
2290 |
|
---|
2291 | <method name="update">
|
---|
2292 | <desc>Updates the internal list of files/directories from the
|
---|
2293 | current directory level. Use <link to="#entryList" /> to get the full list
|
---|
2294 | after a call to this method.</desc>
|
---|
2295 |
|
---|
2296 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2297 | <desc>Progress object to track the operation completion.</desc>
|
---|
2298 | </param>
|
---|
2299 | </method>
|
---|
2300 |
|
---|
2301 | <method name="cd">
|
---|
2302 | <desc>Change the current directory level.</desc>
|
---|
2303 |
|
---|
2304 | <param name="aDir" type="wstring" dir="in">
|
---|
2305 | <desc>The name of the directory to go in.</desc>
|
---|
2306 | </param>
|
---|
2307 |
|
---|
2308 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2309 | <desc>Progress object to track the operation completion.</desc>
|
---|
2310 | </param>
|
---|
2311 | </method>
|
---|
2312 |
|
---|
2313 | <method name="cdUp">
|
---|
2314 | <desc>Go one directory upwards from the current directory level.</desc>
|
---|
2315 |
|
---|
2316 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2317 | <desc>Progress object to track the operation completion.</desc>
|
---|
2318 | </param>
|
---|
2319 | </method>
|
---|
2320 |
|
---|
2321 | <method name="entryList">
|
---|
2322 | <desc>Returns a list of files/directories after a call to <link
|
---|
2323 | to="#update" />. The user is responsible for keeping this internal
|
---|
2324 | list up do date.</desc>
|
---|
2325 |
|
---|
2326 | <param name="aNames" type="wstring" safearray="yes" dir="out">
|
---|
2327 | <desc>The list of names for the entries.</desc>
|
---|
2328 | </param>
|
---|
2329 |
|
---|
2330 | <param name="aTypes" type="unsigned long" safearray="yes" dir="out">
|
---|
2331 | <desc>The list of types for the entries.</desc>
|
---|
2332 | </param>
|
---|
2333 |
|
---|
2334 | <param name="aSizes" type="unsigned long" safearray="yes" dir="out">
|
---|
2335 | <desc>The list of sizes (in bytes) for the entries.</desc>
|
---|
2336 | </param>
|
---|
2337 |
|
---|
2338 | <param name="aModes" type="unsigned long" safearray="yes" dir="out">
|
---|
2339 | <desc>The list of file modes (in octal form) for the entries.</desc>
|
---|
2340 | </param>
|
---|
2341 | </method>
|
---|
2342 |
|
---|
2343 | <method name="exists">
|
---|
2344 | <desc>Checks if the given file list exists in the current directory
|
---|
2345 | level.</desc>
|
---|
2346 |
|
---|
2347 | <param name="aNames" type="wstring" safearray="yes" dir="in">
|
---|
2348 | <desc>The names to check.</desc>
|
---|
2349 | </param>
|
---|
2350 |
|
---|
2351 | <param name="aExists" type="wstring" safearray="yes" dir="return">
|
---|
2352 | <desc>The names which exist.</desc>
|
---|
2353 | </param>
|
---|
2354 | </method>
|
---|
2355 |
|
---|
2356 | <method name="remove">
|
---|
2357 | <desc>Deletes the given files in the current directory level.</desc>
|
---|
2358 |
|
---|
2359 | <param name="aNames" type="wstring" safearray="yes" dir="in">
|
---|
2360 | <desc>The names to remove.</desc>
|
---|
2361 | </param>
|
---|
2362 |
|
---|
2363 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2364 | <desc>Progress object to track the operation completion.</desc>
|
---|
2365 | </param>
|
---|
2366 | </method>
|
---|
2367 |
|
---|
2368 | </interface>
|
---|
2369 |
|
---|
2370 | <!--
|
---|
2371 | // IAppliance
|
---|
2372 | /////////////////////////////////////////////////////////////////////////
|
---|
2373 | -->
|
---|
2374 |
|
---|
2375 | <interface
|
---|
2376 | name="IAppliance" extends="$unknown"
|
---|
2377 | uuid="7b148032-4124-4f46-b56a-b48ac1273f5a"
|
---|
2378 | wsmap="managed"
|
---|
2379 | >
|
---|
2380 | <desc>
|
---|
2381 | Represents a platform-independent appliance in OVF format. An instance of this is returned
|
---|
2382 | by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
|
---|
2383 | virtual machines within an appliance with VirtualBox.
|
---|
2384 |
|
---|
2385 | The OVF standard suggests two different physical file formats:
|
---|
2386 |
|
---|
2387 | <ol>
|
---|
2388 | <li>If the appliance is distributed as a set of files, there must be at least one XML descriptor
|
---|
2389 | file that conforms to the OVF standard and carries an <tt>.ovf</tt> file extension. If
|
---|
2390 | this descriptor file references other files such as disk images, as OVF appliances typically
|
---|
2391 | do, those additional files must be in the same directory as the descriptor file.</li>
|
---|
2392 |
|
---|
2393 | <li>If the appliance is distributed as a single file, it must be in TAR format and have the
|
---|
2394 | <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
|
---|
2395 | files and optionally other files.
|
---|
2396 |
|
---|
2397 | At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
|
---|
2398 | be added with a later version.</li>
|
---|
2399 | </ol>
|
---|
2400 |
|
---|
2401 | <b>Importing</b> an OVF appliance into VirtualBox as instances of
|
---|
2402 | <link to="IMachine" /> involves the following sequence of API calls:
|
---|
2403 |
|
---|
2404 | <ol>
|
---|
2405 | <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
|
---|
2406 | </li>
|
---|
2407 |
|
---|
2408 | <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
|
---|
2409 | would like to import. So long as this file is syntactically valid, this will succeed
|
---|
2410 | and fill the appliance object with the parsed data from the OVF file.
|
---|
2411 | </li>
|
---|
2412 |
|
---|
2413 | <li>Next, call <link to="#interpret" />, which analyzes the OVF data and sets up the
|
---|
2414 | contents of the IAppliance attributes accordingly. These can be inspected by a
|
---|
2415 | VirtualBox front-end such as the GUI, and the suggestions can be displayed to the
|
---|
2416 | user. In particular, the <link to="#virtualSystemDescriptions" /> array contains
|
---|
2417 | instances of <link to="IVirtualSystemDescription" /> which represent the virtual
|
---|
2418 | systems (machines) in the OVF, which in turn describe the virtual hardware prescribed
|
---|
2419 | by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
|
---|
2420 | The GUI can then give the user the option to confirm and/or change these suggestions.
|
---|
2421 | </li>
|
---|
2422 |
|
---|
2423 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
2424 | virtual system (machine) to override the suggestions made by the interpret() routine.
|
---|
2425 | </li>
|
---|
2426 |
|
---|
2427 | <li>Finally, call <link to="#importMachines" /> to create virtual machines in
|
---|
2428 | VirtualBox as instances of <link to="IMachine" /> that match the information in the
|
---|
2429 | virtual system descriptions. After this call succeeded, the UUIDs of the machines created
|
---|
2430 | can be found in the <link to="#machines" /> array attribute.
|
---|
2431 | </li>
|
---|
2432 | </ol>
|
---|
2433 |
|
---|
2434 | <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
|
---|
2435 |
|
---|
2436 | <ol>
|
---|
2437 | <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
|
---|
2438 | an empty IAppliance object.
|
---|
2439 | </li>
|
---|
2440 |
|
---|
2441 | <li>For each machine you would like to export, call <link to="IMachine::export" />
|
---|
2442 | with the IAppliance object you just created. Each such call creates one instance of
|
---|
2443 | <link to="IVirtualSystemDescription" /> inside the appliance.
|
---|
2444 | </li>
|
---|
2445 |
|
---|
2446 | <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
|
---|
2447 | virtual system (machine) to override the suggestions made by the export() routine.
|
---|
2448 | </li>
|
---|
2449 |
|
---|
2450 | <li>Finally, call <link to="#write" /> with a path specification to have the OVF
|
---|
2451 | file written.</li>
|
---|
2452 | </ol>
|
---|
2453 |
|
---|
2454 | </desc>
|
---|
2455 |
|
---|
2456 | <attribute name="path" type="wstring" readonly="yes">
|
---|
2457 | <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
|
---|
2458 | the <tt>.ova</tt> file passed to <link to="#read" /> (for import) or
|
---|
2459 | <link to="#write" /> (for export).
|
---|
2460 | This attribute is empty until one of these methods has been called.
|
---|
2461 | </desc>
|
---|
2462 | </attribute>
|
---|
2463 |
|
---|
2464 | <attribute name="disks" type="wstring" readonly="yes" safearray="yes">
|
---|
2465 | <desc>
|
---|
2466 | Array of virtual disk definitions. One such description exists for each
|
---|
2467 | disk definition in the OVF; each string array item represents one such piece of
|
---|
2468 | disk information, with the information fields separated by tab (\t) characters.
|
---|
2469 |
|
---|
2470 | The caller should be prepared for additional fields being appended to
|
---|
2471 | this string in future versions of VirtualBox and therefore check for
|
---|
2472 | the number of tabs in the strings returned.
|
---|
2473 |
|
---|
2474 | In the current version, the following eight fields are returned per string
|
---|
2475 | in the array:
|
---|
2476 |
|
---|
2477 | <ol>
|
---|
2478 | <li>Disk ID (unique string identifier given to disk)</li>
|
---|
2479 |
|
---|
2480 | <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
|
---|
2481 |
|
---|
2482 | <li>Populated size (optional unsigned integer indicating the current size of the
|
---|
2483 | disk; can be approximate; -1 if unspecified)</li>
|
---|
2484 |
|
---|
2485 | <li>Format (string identifying the disk format, typically
|
---|
2486 | "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
|
---|
2487 |
|
---|
2488 | <li>Reference (where to find the disk image, typically a file name; if empty,
|
---|
2489 | then the disk should be created on import)</li>
|
---|
2490 |
|
---|
2491 | <li>Image size (optional unsigned integer indicating the size of the image,
|
---|
2492 | which need not necessarily be the same as the values specified above, since
|
---|
2493 | the image may be compressed or sparse; -1 if not specified)</li>
|
---|
2494 |
|
---|
2495 | <li>Chunk size (optional unsigned integer if the image is split into chunks;
|
---|
2496 | presently unsupported and always -1)</li>
|
---|
2497 |
|
---|
2498 | <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
|
---|
2499 | </ol>
|
---|
2500 | </desc>
|
---|
2501 | </attribute>
|
---|
2502 |
|
---|
2503 | <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
|
---|
2504 | <desc> Array of virtual system descriptions. One such description is created
|
---|
2505 | for each virtual system (machine) found in the OVF.
|
---|
2506 | This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::export" />
|
---|
2507 | (for export) has been called.
|
---|
2508 | </desc>
|
---|
2509 | </attribute>
|
---|
2510 |
|
---|
2511 | <attribute name="machines" type="wstring" readonly="yes" safearray="yes">
|
---|
2512 | <desc>
|
---|
2513 | Contains the UUIDs of the machines created from the information in this appliances. This is only
|
---|
2514 | relevant for the import case, and will only contain data after a call to <link to="#importMachines" />
|
---|
2515 | succeeded.
|
---|
2516 | </desc>
|
---|
2517 | </attribute>
|
---|
2518 |
|
---|
2519 | <method name="read">
|
---|
2520 | <desc>
|
---|
2521 | Reads an OVF file into the appliance object.
|
---|
2522 |
|
---|
2523 | This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
|
---|
2524 | mere fact that this method returns successfully does not mean that VirtualBox supports all
|
---|
2525 | features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
|
---|
2526 | </desc>
|
---|
2527 | <param name="file" type="wstring" dir="in">
|
---|
2528 | <desc>
|
---|
2529 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
2530 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
2531 | </desc>
|
---|
2532 | </param>
|
---|
2533 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2534 | <desc>Progress object to track the operation completion.</desc>
|
---|
2535 | </param>
|
---|
2536 | </method>
|
---|
2537 |
|
---|
2538 | <method name="interpret">
|
---|
2539 | <desc>
|
---|
2540 | Interprets the OVF data that was read when the appliance was constructed. After
|
---|
2541 | calling this method, one can inspect the
|
---|
2542 | <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
|
---|
2543 | one <link to="IVirtualSystemDescription" /> for each virtual machine found in
|
---|
2544 | the appliance.
|
---|
2545 |
|
---|
2546 | Calling this method is the second step of importing an appliance into VirtualBox;
|
---|
2547 | see <link to="IAppliance" /> for an overview.
|
---|
2548 |
|
---|
2549 | After calling this method, one should call <link to="#getWarnings" /> to find out
|
---|
2550 | if problems were encountered during the processing which might later lead to
|
---|
2551 | errors.
|
---|
2552 | </desc>
|
---|
2553 | </method>
|
---|
2554 |
|
---|
2555 | <method name="importMachines">
|
---|
2556 | <desc>
|
---|
2557 | Imports the appliance into VirtualBox by creating instances of <link to="IMachine" />
|
---|
2558 | and other interfaces that match the information contained in the appliance as
|
---|
2559 | closely as possible, as represented by the import instructions in the
|
---|
2560 | <link to="#virtualSystemDescriptions" /> array.
|
---|
2561 |
|
---|
2562 | Calling this method is the final step of importing an appliance into VirtualBox;
|
---|
2563 | see <link to="IAppliance" /> for an overview.
|
---|
2564 |
|
---|
2565 | Since importing the appliance will most probably involve copying and converting
|
---|
2566 | disk images, which can take a long time, this method operates asynchronously and
|
---|
2567 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
2568 |
|
---|
2569 | After the import succeeded, the UUIDs of the IMachine instances created can be
|
---|
2570 | retrieved from the <link to="#machines" /> array attribute.
|
---|
2571 | </desc>
|
---|
2572 |
|
---|
2573 | <param name="aProgress" type="IProgress" dir="return">
|
---|
2574 | <desc>Progress object to track the operation completion.</desc>
|
---|
2575 | </param>
|
---|
2576 | </method>
|
---|
2577 |
|
---|
2578 | <method name="createVFSExplorer">
|
---|
2579 | <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc>
|
---|
2580 |
|
---|
2581 | <param name="aUri" type="wstring" dir="in">
|
---|
2582 | <desc>The URI describing the file system to use.</desc>
|
---|
2583 | </param>
|
---|
2584 |
|
---|
2585 | <param name="aExplorer" type="IVFSExplorer" dir="return">
|
---|
2586 | <desc></desc>
|
---|
2587 | </param>
|
---|
2588 | </method>
|
---|
2589 |
|
---|
2590 | <method name="write">
|
---|
2591 | <desc>
|
---|
2592 | Writes the contents of the appliance exports into a new OVF file.
|
---|
2593 |
|
---|
2594 | Calling this method is the final step of exporting an appliance from VirtualBox;
|
---|
2595 | see <link to="IAppliance" /> for an overview.
|
---|
2596 |
|
---|
2597 | Since exporting the appliance will most probably involve copying and converting
|
---|
2598 | disk images, which can take a long time, this method operates asynchronously and
|
---|
2599 | returns an IProgress object to allow the caller to monitor the progress.
|
---|
2600 | </desc>
|
---|
2601 | <param name="format" type="wstring" dir="in">
|
---|
2602 | <desc>
|
---|
2603 | Output format, as a string. Currently supported formats are "ovf-0.9" and "ovf-1.0";
|
---|
2604 | future versions of VirtualBox may support additional formats.
|
---|
2605 | </desc>
|
---|
2606 | </param>
|
---|
2607 | <param name="manifest" type="boolean" dir="in">
|
---|
2608 | <desc>
|
---|
2609 | Indicate if the optional manifest file (.mf) should be written. The manifest file
|
---|
2610 | is used for integrity checks prior import.
|
---|
2611 | </desc>
|
---|
2612 | </param>
|
---|
2613 | <param name="path" type="wstring" dir="in">
|
---|
2614 | <desc>
|
---|
2615 | Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
|
---|
2616 | on whether the appliance is distributed as a set of files or as a single file, respectively).
|
---|
2617 | </desc>
|
---|
2618 | </param>
|
---|
2619 | <param name="progress" type="IProgress" dir="return">
|
---|
2620 | <desc>Progress object to track the operation completion.</desc>
|
---|
2621 | </param>
|
---|
2622 | </method>
|
---|
2623 |
|
---|
2624 | <method name="getWarnings">
|
---|
2625 | <desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc>
|
---|
2626 |
|
---|
2627 | <param name="aWarnings" type="wstring" dir="return" safearray="yes">
|
---|
2628 | <desc></desc>
|
---|
2629 | </param>
|
---|
2630 | </method>
|
---|
2631 |
|
---|
2632 | </interface>
|
---|
2633 |
|
---|
2634 | <enum
|
---|
2635 | name="VirtualSystemDescriptionType"
|
---|
2636 | uuid="c0f8f135-3a1d-417d-afa6-b38b95a91f90"
|
---|
2637 | >
|
---|
2638 | <desc>Used with <link to="IVirtualSystemDescription" /> to describe the type of
|
---|
2639 | a configuration value.</desc>
|
---|
2640 |
|
---|
2641 | <const name="Ignore" value="1" />
|
---|
2642 | <const name="OS" value="2" />
|
---|
2643 | <const name="Name" value="3" />
|
---|
2644 | <const name="Product" value="4" />
|
---|
2645 | <const name="Vendor" value="5" />
|
---|
2646 | <const name="Version" value="6" />
|
---|
2647 | <const name="ProductUrl" value="7" />
|
---|
2648 | <const name="VendorUrl" value="8" />
|
---|
2649 | <const name="Description" value="9" />
|
---|
2650 | <const name="License" value="10" />
|
---|
2651 | <const name="Miscellaneous" value="11" />
|
---|
2652 | <const name="CPU" value="12" />
|
---|
2653 | <const name="Memory" value="13" />
|
---|
2654 | <const name="HardDiskControllerIDE" value="14" />
|
---|
2655 | <const name="HardDiskControllerSATA" value="15" />
|
---|
2656 | <const name="HardDiskControllerSCSI" value="16" />
|
---|
2657 | <const name="HardDiskControllerSAS" value="17" />
|
---|
2658 | <const name="HardDiskImage" value="18" />
|
---|
2659 | <const name="Floppy" value="19" />
|
---|
2660 | <const name="CDROM" value="20" />
|
---|
2661 | <const name="NetworkAdapter" value="21" />
|
---|
2662 | <const name="USBController" value="22" />
|
---|
2663 | <const name="SoundCard" value="23" />
|
---|
2664 |
|
---|
2665 | </enum>
|
---|
2666 |
|
---|
2667 | <enum
|
---|
2668 | name="VirtualSystemDescriptionValueType"
|
---|
2669 | uuid="56d9403f-3425-4118-9919-36f2a9b8c77c"
|
---|
2670 | >
|
---|
2671 | <desc>Used with <link to="IVirtualSystemDescription::getValuesByType" /> to describe the value
|
---|
2672 | type to fetch.</desc>
|
---|
2673 |
|
---|
2674 | <const name="Reference" value="1" />
|
---|
2675 | <const name="Original" value="2" />
|
---|
2676 | <const name="Auto" value="3" />
|
---|
2677 | <const name="ExtraConfig" value="4" />
|
---|
2678 |
|
---|
2679 | </enum>
|
---|
2680 |
|
---|
2681 | <interface
|
---|
2682 | name="IVirtualSystemDescription" extends="$unknown"
|
---|
2683 | uuid="d7525e6c-531a-4c51-8e04-41235083a3d8"
|
---|
2684 | wsmap="managed"
|
---|
2685 | >
|
---|
2686 |
|
---|
2687 | <desc>Represents one virtual system (machine) in an appliance. This interface is used in
|
---|
2688 | the <link to="IAppliance::virtualSystemDescriptions" /> array. After
|
---|
2689 | <link to="IAppliance::interpret" /> has been called, that array contains information
|
---|
2690 | about how the virtual systems described in the OVF should best be imported into
|
---|
2691 | VirtualBox virtual machines. See <link to="IAppliance" /> for the steps required to
|
---|
2692 | import an OVF into VirtualBox.
|
---|
2693 | </desc>
|
---|
2694 |
|
---|
2695 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
2696 | <desc>Return the number of virtual system description entries.</desc>
|
---|
2697 | </attribute>
|
---|
2698 |
|
---|
2699 | <method name="getDescription">
|
---|
2700 | <desc>Returns information about the virtual system as arrays of instruction items. In each array, the
|
---|
2701 | items with the same indices correspond and jointly represent an import instruction for VirtualBox.
|
---|
2702 |
|
---|
2703 | The list below identifies the value sets that are possible depending on the
|
---|
2704 | <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case,
|
---|
2705 | the array item with the same index in @a aOvfValues[] will contain the original value as contained
|
---|
2706 | in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[]
|
---|
2707 | will contain a suggested value to be used for VirtualBox. Depending on the description type,
|
---|
2708 | the @a aExtraConfigValues[] array item may also be used.
|
---|
2709 |
|
---|
2710 | <ul>
|
---|
2711 | <li>
|
---|
2712 | "OS": the guest operating system type. There must be exactly one such array item on import. The
|
---|
2713 | corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox.
|
---|
2714 | This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding
|
---|
2715 | item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF.
|
---|
2716 | </li>
|
---|
2717 | <li>
|
---|
2718 | "Name": the name to give to the new virtual machine. There can be at most one such array item;
|
---|
2719 | if none is present on import, then an automatic name will be created from the operating system
|
---|
2720 | type. The corresponding item im @a aOvfValues[] will contain the suggested virtual machine name
|
---|
2721 | from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox
|
---|
2722 | <link to="IMachine" /> name that does not exist yet.
|
---|
2723 | </li>
|
---|
2724 | <li>
|
---|
2725 | "Description": an arbitrary description.
|
---|
2726 | </li>
|
---|
2727 | <li>
|
---|
2728 | "License": the EULA section from the OVF, if present. It is the responsibility of the calling
|
---|
2729 | code to display such a license for agreement; the Main API does not enforce any such policy.
|
---|
2730 | </li>
|
---|
2731 | <li>
|
---|
2732 | Miscellaneous: reserved for future use.
|
---|
2733 | </li>
|
---|
2734 | <li>
|
---|
2735 | "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored.
|
---|
2736 | </li>
|
---|
2737 | <li>
|
---|
2738 | "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none
|
---|
2739 | is present on import, then VirtualBox will set a meaningful default based on the operating system
|
---|
2740 | type.
|
---|
2741 | </li>
|
---|
2742 | <li>
|
---|
2743 | "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items.
|
---|
2744 | An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify
|
---|
2745 | the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox
|
---|
2746 | writes into the OVF.
|
---|
2747 | The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk"
|
---|
2748 | type can use to specify which hard disk controller a virtual disk should be connected to.
|
---|
2749 | Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave"
|
---|
2750 | in traditional terminology, whereas the IDE storage controller that VirtualBox supports in
|
---|
2751 | its virtual machines supports four channels (primary master, primary slave, secondary master,
|
---|
2752 | secondary slave) and thus maps to two IDE controllers in the OVF sense.
|
---|
2753 | </li>
|
---|
2754 | <li>
|
---|
2755 | "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This
|
---|
2756 | has no value in @a aOvfValues[] or @a aVBoxValues[].
|
---|
2757 | The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
|
---|
2758 | </li>
|
---|
2759 | <li>
|
---|
2760 | "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item.
|
---|
2761 | The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or
|
---|
2762 | "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller
|
---|
2763 | whereas VirtualBox considers it a class of storage controllers of its own; see
|
---|
2764 | <link to="StorageControllerType" />).
|
---|
2765 | The matching item in the @a aRefs[] array will be used as with IDE controllers (see above).
|
---|
2766 | </li>
|
---|
2767 | <li>
|
---|
2768 | "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an
|
---|
2769 | arbitrary number of these items, one for each virtual disk image that accompanies the OVF.
|
---|
2770 |
|
---|
2771 | The array item in @a aOvfValues[] will contain the file specification from the OVF file (without
|
---|
2772 | a path since the image file should be in the same location as the OVF file itself), whereas the
|
---|
2773 | item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the
|
---|
2774 | hard disk image. This means that on import the image will be copied and converted from the
|
---|
2775 | "ovf" location to the "vbox" location; on export, this will be handled the other way round.
|
---|
2776 |
|
---|
2777 | The matching item in the @a aExtraConfigValues[] array must contain a string of the following
|
---|
2778 | format: "controller=<index>;channel=<c>"
|
---|
2779 | In this string, <index> must be an integer specifying the hard disk controller to connect
|
---|
2780 | the image to. That number must be the index of an array item with one of the hard disk controller
|
---|
2781 | types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE).
|
---|
2782 | In addition, <c> must specify the channel to use on that controller. For IDE controllers,
|
---|
2783 | this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions
|
---|
2784 | before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but
|
---|
2785 | no longer exported. For SATA and SCSI controllers, the channel can range from 0-29.
|
---|
2786 | </li>
|
---|
2787 | <li>
|
---|
2788 | "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same
|
---|
2789 | attachment information as with "HardDiskImage" items.
|
---|
2790 | </li>
|
---|
2791 | <li>
|
---|
2792 | "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same
|
---|
2793 | attachment information as with "HardDiskImage" items.
|
---|
2794 | </li>
|
---|
2795 | <li>
|
---|
2796 | "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware
|
---|
2797 | for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string
|
---|
2798 | of the "type=<X>" format, where <X> must be either "NAT" or "Bridged".
|
---|
2799 | </li>
|
---|
2800 | <li>
|
---|
2801 | "USBController": a USB controller. There can be at most one such item. If and only if such an
|
---|
2802 | item ispresent, USB support will be enabled for the new virtual machine.
|
---|
2803 | </li>
|
---|
2804 | <li>
|
---|
2805 | "SoundCard": a sound card. There can be at most one such item. If and only if such an item is
|
---|
2806 | present, sound support will be enabled for the new virtual machine. Note that the virtual
|
---|
2807 | machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which
|
---|
2808 | may be different from the virtual soundcard expected by the appliance.
|
---|
2809 | </li>
|
---|
2810 | </ul>
|
---|
2811 |
|
---|
2812 | </desc>
|
---|
2813 |
|
---|
2814 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
2815 | <desc></desc>
|
---|
2816 | </param>
|
---|
2817 |
|
---|
2818 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
2819 | <desc></desc>
|
---|
2820 | </param>
|
---|
2821 |
|
---|
2822 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
2823 | <desc></desc>
|
---|
2824 | </param>
|
---|
2825 |
|
---|
2826 | <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
|
---|
2827 | <desc></desc>
|
---|
2828 | </param>
|
---|
2829 |
|
---|
2830 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
2831 | <desc></desc>
|
---|
2832 | </param>
|
---|
2833 |
|
---|
2834 | </method>
|
---|
2835 |
|
---|
2836 | <method name="getDescriptionByType">
|
---|
2837 | <desc>This is the same as <link to="#getDescription" /> except that you can specify which types
|
---|
2838 | should be returned.</desc>
|
---|
2839 |
|
---|
2840 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2841 | <desc></desc>
|
---|
2842 | </param>
|
---|
2843 |
|
---|
2844 | <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes">
|
---|
2845 | <desc></desc>
|
---|
2846 | </param>
|
---|
2847 |
|
---|
2848 | <param name="aRefs" type="wstring" dir="out" safearray="yes">
|
---|
2849 | <desc></desc>
|
---|
2850 | </param>
|
---|
2851 |
|
---|
2852 | <param name="aOvfValues" type="wstring" dir="out" safearray="yes">
|
---|
2853 | <desc></desc>
|
---|
2854 | </param>
|
---|
2855 |
|
---|
2856 | <param name="aVBoxValues" type="wstring" dir="out" safearray="yes">
|
---|
2857 | <desc></desc>
|
---|
2858 | </param>
|
---|
2859 |
|
---|
2860 | <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes">
|
---|
2861 | <desc></desc>
|
---|
2862 | </param>
|
---|
2863 |
|
---|
2864 | </method>
|
---|
2865 |
|
---|
2866 | <method name="getValuesByType">
|
---|
2867 | <desc>This is the same as <link to="#getDescriptionByType" /> except that you can specify which
|
---|
2868 | value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible
|
---|
2869 | values.</desc>
|
---|
2870 |
|
---|
2871 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2872 | <desc></desc>
|
---|
2873 | </param>
|
---|
2874 |
|
---|
2875 | <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in">
|
---|
2876 | <desc></desc>
|
---|
2877 | </param>
|
---|
2878 |
|
---|
2879 | <param name="aValues" type="wstring" dir="return" safearray="yes">
|
---|
2880 | <desc></desc>
|
---|
2881 | </param>
|
---|
2882 |
|
---|
2883 | </method>
|
---|
2884 |
|
---|
2885 | <method name="setFinalValues">
|
---|
2886 | <desc>
|
---|
2887 | This method allows the appliance's user to change the configuration for the virtual
|
---|
2888 | system descriptions. For each array item returned from <link to="#getDescription" />,
|
---|
2889 | you must pass in one boolean value and one configuration value.
|
---|
2890 |
|
---|
2891 | Each item in the boolean array determines whether the particular configuration item
|
---|
2892 | should be enabled.
|
---|
2893 | You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA,
|
---|
2894 | HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController
|
---|
2895 | and SoundCard.
|
---|
2896 |
|
---|
2897 | For the "vbox" and "extra configuration" values, if you pass in the same arrays
|
---|
2898 | as returned in the aVBoxValues and aExtraConfigValues arrays from getDescription(),
|
---|
2899 | the configuration remains unchanged. Please see the documentation for getDescription()
|
---|
2900 | for valid configuration values for the individual array item types. If the
|
---|
2901 | corresponding item in the aEnabled array is @c false, the configuration value is ignored.
|
---|
2902 | </desc>
|
---|
2903 |
|
---|
2904 | <param name="aEnabled" type="boolean" dir="in" safearray="yes">
|
---|
2905 | <desc></desc>
|
---|
2906 | </param>
|
---|
2907 |
|
---|
2908 | <param name="aVBoxValues" type="wstring" dir="in" safearray="yes">
|
---|
2909 | <desc></desc>
|
---|
2910 | </param>
|
---|
2911 |
|
---|
2912 | <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes">
|
---|
2913 | <desc></desc>
|
---|
2914 | </param>
|
---|
2915 | </method>
|
---|
2916 |
|
---|
2917 | <method name="addDescription">
|
---|
2918 | <desc>
|
---|
2919 | This method adds an additional description entry to the stack of already
|
---|
2920 | available descriptions for this virtual system. This is handy for writing
|
---|
2921 | values which aren't directly supported by VirtualBox. One example would
|
---|
2922 | be the License type of <link to="VirtualSystemDescriptionType" />.
|
---|
2923 | </desc>
|
---|
2924 |
|
---|
2925 | <param name="aType" type="VirtualSystemDescriptionType" dir="in">
|
---|
2926 | <desc></desc>
|
---|
2927 | </param>
|
---|
2928 |
|
---|
2929 | <param name="aVBoxValue" type="wstring" dir="in">
|
---|
2930 | <desc></desc>
|
---|
2931 | </param>
|
---|
2932 |
|
---|
2933 | <param name="aExtraConfigValue" type="wstring" dir="in">
|
---|
2934 | <desc></desc>
|
---|
2935 | </param>
|
---|
2936 | </method>
|
---|
2937 | </interface>
|
---|
2938 |
|
---|
2939 |
|
---|
2940 | <!--
|
---|
2941 | // IMachine
|
---|
2942 | /////////////////////////////////////////////////////////////////////////
|
---|
2943 | -->
|
---|
2944 |
|
---|
2945 | <interface
|
---|
2946 | name="IInternalMachineControl" extends="$unknown"
|
---|
2947 | uuid="476126af-e223-4490-a8a0-b1f1575be013"
|
---|
2948 | internal="yes"
|
---|
2949 | wsmap="suppress"
|
---|
2950 | >
|
---|
2951 | <method name="setRemoveSavedStateFile">
|
---|
2952 | <desc>
|
---|
2953 | Updates the flag whether the saved state file is removed on a
|
---|
2954 | machine state change from Saved to PoweredOff.
|
---|
2955 | </desc>
|
---|
2956 | <param name="aRemove" type="boolean" dir="in"/>
|
---|
2957 | </method>
|
---|
2958 |
|
---|
2959 | <method name="updateState">
|
---|
2960 | <desc>
|
---|
2961 | Updates the VM state.
|
---|
2962 | <note>
|
---|
2963 | This operation will also update the settings file with the correct
|
---|
2964 | information about the saved state file and delete this file from disk
|
---|
2965 | when appropriate.
|
---|
2966 | </note>
|
---|
2967 | </desc>
|
---|
2968 | <param name="state" type="MachineState" dir="in"/>
|
---|
2969 | </method>
|
---|
2970 |
|
---|
2971 | <method name="getIPCId">
|
---|
2972 | <param name="id" type="wstring" dir="return"/>
|
---|
2973 | </method>
|
---|
2974 |
|
---|
2975 | <method name="beginPowerUp">
|
---|
2976 | <desc>
|
---|
2977 | Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and
|
---|
2978 | gives it the progress object that should be part of any pending
|
---|
2979 | <link to="IMachine::launchVMProcess"/> operations. The progress
|
---|
2980 | object may be called back to reflect an early cancelation, so some care
|
---|
2981 | have to be taken with respect to any cancelation callbacks. The console
|
---|
2982 | object will call <link to="IInternalMachineControl::endPowerUp"/>
|
---|
2983 | to signal the completion of the progress object.
|
---|
2984 | </desc>
|
---|
2985 | <param name="aProgress" type="IProgress" dir="in" />
|
---|
2986 | </method>
|
---|
2987 |
|
---|
2988 | <method name="endPowerUp">
|
---|
2989 | <desc>
|
---|
2990 | Tells VBoxSVC that <link to="IConsole::powerUp"/> has completed.
|
---|
2991 | This method may query status information from the progress object it
|
---|
2992 | received in <link to="IInternalMachineControl::beginPowerUp"/> and copy
|
---|
2993 | it over to any in-progress <link to="IMachine::launchVMProcess"/>
|
---|
2994 | call in order to complete that progress object.
|
---|
2995 | </desc>
|
---|
2996 | <param name="result" type="long" dir="in"/>
|
---|
2997 | </method>
|
---|
2998 |
|
---|
2999 | <method name="runUSBDeviceFilters">
|
---|
3000 | <desc>
|
---|
3001 | Asks the server to run USB devices filters of the associated
|
---|
3002 | machine against the given USB device and tell if there is
|
---|
3003 | a match.
|
---|
3004 | <note>
|
---|
3005 | Intended to be used only for remote USB devices. Local
|
---|
3006 | ones don't require to call this method (this is done
|
---|
3007 | implicitly by the Host and USBProxyService).
|
---|
3008 | </note>
|
---|
3009 | </desc>
|
---|
3010 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
3011 | <param name="matched" type="boolean" dir="out"/>
|
---|
3012 | <param name="maskedInterfaces" type="unsigned long" dir="out"/>
|
---|
3013 | </method>
|
---|
3014 |
|
---|
3015 | <method name="captureUSBDevice">
|
---|
3016 | <desc>
|
---|
3017 | Requests a capture of the given host USB device.
|
---|
3018 | When the request is completed, the VM process will
|
---|
3019 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3020 | notification.
|
---|
3021 | </desc>
|
---|
3022 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
3023 | </method>
|
---|
3024 |
|
---|
3025 | <method name="detachUSBDevice">
|
---|
3026 | <desc>
|
---|
3027 | Notification that a VM is going to detach (@a done = @c false) or has
|
---|
3028 | already detached (@a done = @c true) the given USB device.
|
---|
3029 | When the @a done = @c true request is completed, the VM process will
|
---|
3030 | get a <link to="IInternalSessionControl::onUSBDeviceDetach"/>
|
---|
3031 | notification.
|
---|
3032 | <note>
|
---|
3033 | In the @a done = @c true case, the server must run its own filters
|
---|
3034 | and filters of all VMs but this one on the detached device
|
---|
3035 | as if it were just attached to the host computer.
|
---|
3036 | </note>
|
---|
3037 | </desc>
|
---|
3038 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
3039 | <param name="done" type="boolean" dir="in"/>
|
---|
3040 | </method>
|
---|
3041 |
|
---|
3042 | <method name="autoCaptureUSBDevices">
|
---|
3043 | <desc>
|
---|
3044 | Requests a capture all matching USB devices attached to the host.
|
---|
3045 | When the request is completed, the VM process will
|
---|
3046 | get a <link to="IInternalSessionControl::onUSBDeviceAttach"/>
|
---|
3047 | notification per every captured device.
|
---|
3048 | </desc>
|
---|
3049 | </method>
|
---|
3050 |
|
---|
3051 | <method name="detachAllUSBDevices">
|
---|
3052 | <desc>
|
---|
3053 | Notification that a VM that is being powered down. The done
|
---|
3054 | parameter indicates whether which stage of the power down
|
---|
3055 | we're at. When @a done = @c false the VM is announcing its
|
---|
3056 | intentions, while when @a done = @c true the VM is reporting
|
---|
3057 | what it has done.
|
---|
3058 | <note>
|
---|
3059 | In the @a done = @c true case, the server must run its own filters
|
---|
3060 | and filters of all VMs but this one on all detach devices as
|
---|
3061 | if they were just attached to the host computer.
|
---|
3062 | </note>
|
---|
3063 | </desc>
|
---|
3064 | <param name="done" type="boolean" dir="in"/>
|
---|
3065 | </method>
|
---|
3066 |
|
---|
3067 | <method name="onSessionEnd">
|
---|
3068 | <desc>
|
---|
3069 | Triggered by the given session object when the session is about
|
---|
3070 | to close normally.
|
---|
3071 | </desc>
|
---|
3072 | <param name="session" type="ISession" dir="in">
|
---|
3073 | <desc>Session that is being closed</desc>
|
---|
3074 | </param>
|
---|
3075 | <param name="progress" type="IProgress" dir="return">
|
---|
3076 | <desc>
|
---|
3077 | Used to wait until the corresponding machine is actually
|
---|
3078 | dissociated from the given session on the server.
|
---|
3079 | Returned only when this session is a direct one.
|
---|
3080 | </desc>
|
---|
3081 | </param>
|
---|
3082 | </method>
|
---|
3083 |
|
---|
3084 | <method name="beginSavingState">
|
---|
3085 | <desc>
|
---|
3086 | Called by the VM process to inform the server it wants to
|
---|
3087 | save the current state and stop the VM execution.
|
---|
3088 | </desc>
|
---|
3089 | <param name="progress" type="IProgress" dir="out">
|
---|
3090 | <desc>
|
---|
3091 | Progress object created by VBoxSVC to wait until
|
---|
3092 | the state is saved.
|
---|
3093 | </desc>
|
---|
3094 | </param>
|
---|
3095 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3096 | <desc>
|
---|
3097 | File path the VM process must save the execution state to.
|
---|
3098 | </desc>
|
---|
3099 | </param>
|
---|
3100 | </method>
|
---|
3101 |
|
---|
3102 | <method name="endSavingState">
|
---|
3103 | <desc>
|
---|
3104 | Called by the VM process to inform the server that saving
|
---|
3105 | the state previously requested by #beginSavingState is either
|
---|
3106 | successfully finished or there was a failure.
|
---|
3107 |
|
---|
3108 | <result name="VBOX_E_FILE_ERROR">
|
---|
3109 | Settings file not accessible.
|
---|
3110 | </result>
|
---|
3111 | <result name="VBOX_E_XML_ERROR">
|
---|
3112 | Could not parse the settings file.
|
---|
3113 | </result>
|
---|
3114 |
|
---|
3115 | </desc>
|
---|
3116 |
|
---|
3117 | <param name="result" type="long" dir="in">
|
---|
3118 | <desc>@c S_OK to indicate success.
|
---|
3119 | </desc>
|
---|
3120 | </param>
|
---|
3121 | <param name="errMsg" type="wstring" dir="in">
|
---|
3122 | <desc>@c human readable error message in case of failure.
|
---|
3123 | </desc>
|
---|
3124 | </param>
|
---|
3125 | </method>
|
---|
3126 |
|
---|
3127 | <method name="adoptSavedState">
|
---|
3128 | <desc>
|
---|
3129 | Gets called by IConsole::adoptSavedState.
|
---|
3130 | <result name="VBOX_E_FILE_ERROR">
|
---|
3131 | Invalid saved state file path.
|
---|
3132 | </result>
|
---|
3133 | </desc>
|
---|
3134 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
3135 | <desc>Path to the saved state file to adopt.</desc>
|
---|
3136 | </param>
|
---|
3137 | </method>
|
---|
3138 |
|
---|
3139 | <method name="beginTakingSnapshot">
|
---|
3140 | <desc>
|
---|
3141 | Called from the VM process to request from the server to perform the
|
---|
3142 | server-side actions of creating a snapshot (creating differencing images
|
---|
3143 | and the snapshot object).
|
---|
3144 |
|
---|
3145 | <result name="VBOX_E_FILE_ERROR">
|
---|
3146 | Settings file not accessible.
|
---|
3147 | </result>
|
---|
3148 | <result name="VBOX_E_XML_ERROR">
|
---|
3149 | Could not parse the settings file.
|
---|
3150 | </result>
|
---|
3151 | </desc>
|
---|
3152 | <param name="initiator" type="IConsole" dir="in">
|
---|
3153 | <desc>The console object that initiated this call.</desc>
|
---|
3154 | </param>
|
---|
3155 | <param name="name" type="wstring" dir="in">
|
---|
3156 | <desc>Snapshot name.</desc>
|
---|
3157 | </param>
|
---|
3158 | <param name="description" type="wstring" dir="in">
|
---|
3159 | <desc>Snapshot description.</desc>
|
---|
3160 | </param>
|
---|
3161 | <param name="consoleProgress" type="IProgress" dir="in">
|
---|
3162 | <desc>
|
---|
3163 | Progress object created by the VM process tracking the
|
---|
3164 | snapshot's progress. This has the following sub-operations:
|
---|
3165 | <ul>
|
---|
3166 | <li>setting up (weight 1);</li>
|
---|
3167 | <li>one for each medium attachment that needs a differencing image (weight 1 each);</li>
|
---|
3168 | <li>another one to copy the VM state (if offline with saved state, weight is VM memory size in MB);</li>
|
---|
3169 | <li>another one to save the VM state (if online, weight is VM memory size in MB);</li>
|
---|
3170 | <li>finishing up (weight 1)</li>
|
---|
3171 | </ul>
|
---|
3172 | </desc>
|
---|
3173 | </param>
|
---|
3174 | <param name="fTakingSnapshotOnline" type="boolean" dir="in">
|
---|
3175 | <desc>
|
---|
3176 | Whether this is an online snapshot (i.e. the machine is running).
|
---|
3177 | </desc>
|
---|
3178 | </param>
|
---|
3179 | <param name="stateFilePath" type="wstring" dir="out">
|
---|
3180 | <desc>
|
---|
3181 | File path the VM process must save the execution state to.
|
---|
3182 | </desc>
|
---|
3183 | </param>
|
---|
3184 | </method>
|
---|
3185 |
|
---|
3186 | <method name="endTakingSnapshot">
|
---|
3187 | <desc>
|
---|
3188 | Called by the VM process to inform the server that the snapshot
|
---|
3189 | previously requested by #beginTakingSnapshot is either
|
---|
3190 | successfully taken or there was a failure.
|
---|
3191 | </desc>
|
---|
3192 |
|
---|
3193 | <param name="success" type="boolean" dir="in">
|
---|
3194 | <desc>@c true to indicate success and @c false otherwise</desc>
|
---|
3195 | </param>
|
---|
3196 | </method>
|
---|
3197 |
|
---|
3198 | <method name="deleteSnapshot">
|
---|
3199 | <desc>
|
---|
3200 | Gets called by IConsole::deleteSnapshot.
|
---|
3201 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
3202 | Snapshot has more than one child snapshot.
|
---|
3203 | </result>
|
---|
3204 | </desc>
|
---|
3205 | <param name="initiator" type="IConsole" dir="in">
|
---|
3206 | <desc>The console object that initiated this call.</desc>
|
---|
3207 | </param>
|
---|
3208 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
3209 | <desc>UUID of the snapshot to delete.</desc>
|
---|
3210 | </param>
|
---|
3211 | <param name="machineState" type="MachineState" dir="out">
|
---|
3212 | <desc>New machine state after this operation is started.</desc>
|
---|
3213 | </param>
|
---|
3214 | <param name="progress" type="IProgress" dir="return">
|
---|
3215 | <desc>Progress object to track the operation completion.</desc>
|
---|
3216 | </param>
|
---|
3217 | </method>
|
---|
3218 |
|
---|
3219 | <method name="finishOnlineMergeMedium">
|
---|
3220 | <desc>
|
---|
3221 | Gets called by IConsole::onlineMergeMedium.
|
---|
3222 | </desc>
|
---|
3223 | <param name="mediumAttachment" type="IMediumAttachment" dir="in">
|
---|
3224 | <desc>The medium attachment which needs to be cleaned up.</desc>
|
---|
3225 | </param>
|
---|
3226 | <param name="source" type="IMedium" dir="in">
|
---|
3227 | <desc>Merge source medium.</desc>
|
---|
3228 | </param>
|
---|
3229 | <param name="target" type="IMedium" dir="in">
|
---|
3230 | <desc>Merge target medium.</desc>
|
---|
3231 | </param>
|
---|
3232 | <param name="mergeForward" type="boolean" dir="in">
|
---|
3233 | <desc>Merge direction.</desc>
|
---|
3234 | </param>
|
---|
3235 | <param name="parentForTarget" type="IMedium" dir="in">
|
---|
3236 | <desc>For forward merges: new parent for target medium.</desc>
|
---|
3237 | </param>
|
---|
3238 | <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
|
---|
3239 | <desc>For backward merges: list of media which need their parent UUID
|
---|
3240 | updated.</desc>
|
---|
3241 | </param>
|
---|
3242 | </method>
|
---|
3243 |
|
---|
3244 | <method name="restoreSnapshot">
|
---|
3245 | <desc>
|
---|
3246 | Gets called by IConsole::RestoreSnapshot.
|
---|
3247 | </desc>
|
---|
3248 | <param name="initiator" type="IConsole" dir="in">
|
---|
3249 | <desc>The console object that initiated this call.</desc>
|
---|
3250 | </param>
|
---|
3251 | <param name="snapshot" type="ISnapshot" dir="in">
|
---|
3252 | <desc>The snapshot to restore the VM state from.</desc>
|
---|
3253 | </param>
|
---|
3254 | <param name="machineState" type="MachineState" dir="out">
|
---|
3255 | <desc>New machine state after this operation is started.</desc>
|
---|
3256 | </param>
|
---|
3257 | <param name="progress" type="IProgress" dir="return">
|
---|
3258 | <desc>Progress object to track the operation completion.</desc>
|
---|
3259 | </param>
|
---|
3260 | </method>
|
---|
3261 |
|
---|
3262 | <method name="pullGuestProperties">
|
---|
3263 | <desc>
|
---|
3264 | Get the list of the guest properties matching a set of patterns along
|
---|
3265 | with their values, time stamps and flags and give responsibility for
|
---|
3266 | managing properties to the console.
|
---|
3267 | </desc>
|
---|
3268 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
3269 | <desc>
|
---|
3270 | The names of the properties returned.
|
---|
3271 | </desc>
|
---|
3272 | </param>
|
---|
3273 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
3274 | <desc>
|
---|
3275 | The values of the properties returned. The array entries match the
|
---|
3276 | corresponding entries in the @a name array.
|
---|
3277 | </desc>
|
---|
3278 | </param>
|
---|
3279 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
3280 | <desc>
|
---|
3281 | The time stamps of the properties returned. The array entries match
|
---|
3282 | the corresponding entries in the @a name array.
|
---|
3283 | </desc>
|
---|
3284 | </param>
|
---|
3285 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
3286 | <desc>
|
---|
3287 | The flags of the properties returned. The array entries match the
|
---|
3288 | corresponding entries in the @a name array.
|
---|
3289 | </desc>
|
---|
3290 | </param>
|
---|
3291 | </method>
|
---|
3292 |
|
---|
3293 | <method name="pushGuestProperty">
|
---|
3294 | <desc>
|
---|
3295 | Update a single guest property in IMachine.
|
---|
3296 | </desc>
|
---|
3297 | <param name="name" type="wstring" dir="in">
|
---|
3298 | <desc>
|
---|
3299 | The name of the property to be updated.
|
---|
3300 | </desc>
|
---|
3301 | </param>
|
---|
3302 | <param name="value" type="wstring" dir="in">
|
---|
3303 | <desc>
|
---|
3304 | The value of the property.
|
---|
3305 | </desc>
|
---|
3306 | </param>
|
---|
3307 | <param name="timestamp" type="long long" dir="in">
|
---|
3308 | <desc>
|
---|
3309 | The timestamp of the property.
|
---|
3310 | </desc>
|
---|
3311 | </param>
|
---|
3312 | <param name="flags" type="wstring" dir="in">
|
---|
3313 | <desc>
|
---|
3314 | The flags of the property.
|
---|
3315 | </desc>
|
---|
3316 | </param>
|
---|
3317 | </method>
|
---|
3318 |
|
---|
3319 | <method name="lockMedia">
|
---|
3320 | <desc>
|
---|
3321 | Locks all media attached to the machine for writing and parents of
|
---|
3322 | attached differencing media (if any) for reading. This operation is
|
---|
3323 | atomic so that if it fails no media is actually locked.
|
---|
3324 |
|
---|
3325 | This method is intended to be called when the machine is in Starting or
|
---|
3326 | Restoring state. The locked media will be automatically unlocked when
|
---|
3327 | the machine is powered off or crashed.
|
---|
3328 | </desc>
|
---|
3329 | </method>
|
---|
3330 | <method name="unlockMedia">
|
---|
3331 | <desc>
|
---|
3332 | Unlocks all media previously locked using
|
---|
3333 | <link to="IInternalMachineControl::lockMedia"/>.
|
---|
3334 |
|
---|
3335 | This method is intended to be used with teleportation so that it is
|
---|
3336 | possible to teleport between processes on the same machine.
|
---|
3337 | </desc>
|
---|
3338 | </method>
|
---|
3339 | </interface>
|
---|
3340 |
|
---|
3341 | <interface
|
---|
3342 | name="IBIOSSettings" extends="$unknown"
|
---|
3343 | uuid="38b54279-dc35-4f5e-a431-835b867c6b5e"
|
---|
3344 | wsmap="managed"
|
---|
3345 | >
|
---|
3346 | <desc>
|
---|
3347 | The IBIOSSettings interface represents BIOS settings of the virtual
|
---|
3348 | machine. This is used only in the <link to="IMachine::BIOSSettings" /> attribute.
|
---|
3349 | </desc>
|
---|
3350 | <attribute name="logoFadeIn" type="boolean">
|
---|
3351 | <desc>Fade in flag for BIOS logo animation.</desc>
|
---|
3352 | </attribute>
|
---|
3353 |
|
---|
3354 | <attribute name="logoFadeOut" type="boolean">
|
---|
3355 | <desc>Fade out flag for BIOS logo animation.</desc>
|
---|
3356 | </attribute>
|
---|
3357 |
|
---|
3358 | <attribute name="logoDisplayTime" type="unsigned long">
|
---|
3359 | <desc>BIOS logo display time in milliseconds (0 = default).</desc>
|
---|
3360 | </attribute>
|
---|
3361 |
|
---|
3362 | <attribute name="logoImagePath" type="wstring">
|
---|
3363 | <desc>
|
---|
3364 | Local file system path for external BIOS splash image. Empty string
|
---|
3365 | means the default image is shown on boot.
|
---|
3366 | </desc>
|
---|
3367 | </attribute>
|
---|
3368 |
|
---|
3369 | <attribute name="bootMenuMode" type="BIOSBootMenuMode">
|
---|
3370 | <desc>Mode of the BIOS boot device menu.</desc>
|
---|
3371 | </attribute>
|
---|
3372 |
|
---|
3373 | <attribute name="ACPIEnabled" type="boolean">
|
---|
3374 | <desc>ACPI support flag.</desc>
|
---|
3375 | </attribute>
|
---|
3376 |
|
---|
3377 | <attribute name="IOAPICEnabled" type="boolean">
|
---|
3378 | <desc>
|
---|
3379 | IO APIC support flag. If set, VirtualBox will provide an IO APIC
|
---|
3380 | and support IRQs above 15.
|
---|
3381 | </desc>
|
---|
3382 | </attribute>
|
---|
3383 |
|
---|
3384 | <attribute name="timeOffset" type="long long">
|
---|
3385 | <desc>
|
---|
3386 | Offset in milliseconds from the host system time. This allows for
|
---|
3387 | guests running with a different system date/time than the host.
|
---|
3388 | It is equivalent to setting the system date/time in the BIOS except
|
---|
3389 | it is not an absolute value but a relative one. Guest Additions
|
---|
3390 | time synchronization honors this offset.
|
---|
3391 | </desc>
|
---|
3392 | </attribute>
|
---|
3393 |
|
---|
3394 | <attribute name="PXEDebugEnabled" type="boolean">
|
---|
3395 | <desc>
|
---|
3396 | PXE debug logging flag. If set, VirtualBox will write extensive
|
---|
3397 | PXE trace information to the release log.
|
---|
3398 | </desc>
|
---|
3399 | </attribute>
|
---|
3400 |
|
---|
3401 | </interface>
|
---|
3402 |
|
---|
3403 | <enum name="CleanupMode"
|
---|
3404 | uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441">
|
---|
3405 | <desc>Cleanup mode, used with <link to="IMachine::unregister" />.
|
---|
3406 | </desc>
|
---|
3407 | <const name="UnregisterOnly" value="1">
|
---|
3408 | <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc>
|
---|
3409 | </const>
|
---|
3410 | <const name="DetachAllReturnNone" value="2">
|
---|
3411 | <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc>
|
---|
3412 | </const>
|
---|
3413 | <const name="DetachAllReturnHardDisksOnly" value="3">
|
---|
3414 | <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removeable media.</desc>
|
---|
3415 | </const>
|
---|
3416 | <const name="Full" value="4">
|
---|
3417 | <desc>Delete all snapshots, detach all media and return all media for closing.</desc>
|
---|
3418 | </const>
|
---|
3419 | </enum>
|
---|
3420 |
|
---|
3421 | <interface
|
---|
3422 | name="IMachine" extends="$unknown"
|
---|
3423 | uuid="cc4fec9a-3150-45df-9ee9-f00ba54d6ac3"
|
---|
3424 | wsmap="managed"
|
---|
3425 | >
|
---|
3426 | <desc>
|
---|
3427 | The IMachine interface represents a virtual machine, or guest, created
|
---|
3428 | in VirtualBox.
|
---|
3429 |
|
---|
3430 | This interface is used in two contexts. First of all, a collection of
|
---|
3431 | objects implementing this interface is stored in the
|
---|
3432 | <link to="IVirtualBox::machines"/> attribute which lists all the virtual
|
---|
3433 | machines that are currently registered with this VirtualBox
|
---|
3434 | installation. Also, once a session has been opened for the given virtual
|
---|
3435 | machine (e.g. the virtual machine is running), the machine object
|
---|
3436 | associated with the open session can be queried from the session object;
|
---|
3437 | see <link to="ISession"/> for details.
|
---|
3438 |
|
---|
3439 | The main role of this interface is to expose the settings of the virtual
|
---|
3440 | machine and provide methods to change various aspects of the virtual
|
---|
3441 | machine's configuration. For machine objects stored in the
|
---|
3442 | <link to="IVirtualBox::machines"/> collection, all attributes are
|
---|
3443 | read-only unless explicitly stated otherwise in individual attribute
|
---|
3444 | and method descriptions.
|
---|
3445 |
|
---|
3446 | In order to change a machine setting, a session for this machine must be
|
---|
3447 | opened using one of the <link to="IMachine::lockMachine" /> or
|
---|
3448 | <link to="IMachine::launchVMProcess"/> methods. After the
|
---|
3449 | machine has been successfully locked for a session, a mutable machine object
|
---|
3450 | needs to be queried from the session object and then the desired settings
|
---|
3451 | changes can be applied to the returned object using IMachine attributes and
|
---|
3452 | methods. See the <link to="ISession"/> interface description for more
|
---|
3453 | information about sessions.
|
---|
3454 |
|
---|
3455 | Note that IMachine does not provide methods to control virtual machine
|
---|
3456 | execution (such as start the machine, or power it down) -- these methods
|
---|
3457 | are grouped in a separate interface called <link to="IConsole" />.
|
---|
3458 |
|
---|
3459 | <see>ISession, IConsole</see>
|
---|
3460 | </desc>
|
---|
3461 |
|
---|
3462 | <attribute name="parent" type="IVirtualBox" readonly="yes">
|
---|
3463 | <desc>Associated parent object.</desc>
|
---|
3464 | </attribute>
|
---|
3465 |
|
---|
3466 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
3467 | <desc>
|
---|
3468 | Whether this virtual machine is currently accessible or not.
|
---|
3469 |
|
---|
3470 | A machine is always deemed accessible unless it is registered <i>and</i>
|
---|
3471 | its settings file cannot be read or parsed (either because the file itself
|
---|
3472 | is unavailable or has invalid XML contents).
|
---|
3473 |
|
---|
3474 | Every time this property is read, the accessibility state of
|
---|
3475 | this machine is re-evaluated. If the returned value is @c false,
|
---|
3476 | the <link to="#accessError"/> property may be used to get the
|
---|
3477 | detailed error information describing the reason of
|
---|
3478 | inaccessibility, including XML error messages.
|
---|
3479 |
|
---|
3480 | When the machine is inaccessible, only the following properties
|
---|
3481 | can be used on it:
|
---|
3482 | <ul>
|
---|
3483 | <li><link to="#parent"/></li>
|
---|
3484 | <li><link to="#id"/></li>
|
---|
3485 | <li><link to="#settingsFilePath"/></li>
|
---|
3486 | <li><link to="#accessible"/></li>
|
---|
3487 | <li><link to="#accessError"/></li>
|
---|
3488 | </ul>
|
---|
3489 |
|
---|
3490 | An attempt to access any other property or method will return
|
---|
3491 | an error.
|
---|
3492 |
|
---|
3493 | The only possible action you can perform on an inaccessible
|
---|
3494 | machine is to unregister it using the
|
---|
3495 | <link to="IMachine::unregister"/> call (or, to check
|
---|
3496 | for the accessibility state once more by querying this
|
---|
3497 | property).
|
---|
3498 |
|
---|
3499 | <note>
|
---|
3500 | In the current implementation, once this property returns
|
---|
3501 | @c true, the machine will never become inaccessible
|
---|
3502 | later, even if its settings file cannot be successfully
|
---|
3503 | read/written any more (at least, until the VirtualBox
|
---|
3504 | server is restarted). This limitation may be removed in
|
---|
3505 | future releases.
|
---|
3506 | </note>
|
---|
3507 | </desc>
|
---|
3508 | </attribute>
|
---|
3509 |
|
---|
3510 | <attribute name="accessError" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
3511 | <desc>
|
---|
3512 | Error information describing the reason of machine
|
---|
3513 | inaccessibility.
|
---|
3514 |
|
---|
3515 | Reading this property is only valid after the last call to
|
---|
3516 | <link to="#accessible"/> returned @c false (i.e. the
|
---|
3517 | machine is currently inaccessible). Otherwise, a @c null
|
---|
3518 | IVirtualBoxErrorInfo object will be returned.
|
---|
3519 | </desc>
|
---|
3520 | </attribute>
|
---|
3521 |
|
---|
3522 | <attribute name="name" type="wstring">
|
---|
3523 | <desc>
|
---|
3524 | Name of the virtual machine.
|
---|
3525 |
|
---|
3526 | Besides being used for human-readable identification purposes
|
---|
3527 | everywhere in VirtualBox, the virtual machine name is also used
|
---|
3528 | as a name of the machine's settings file and as a name of the
|
---|
3529 | subdirectory this settings file resides in. Thus, every time you
|
---|
3530 | change the value of this property, the settings file will be
|
---|
3531 | renamed once you call <link to="#saveSettings"/> to confirm the
|
---|
3532 | change. The containing subdirectory will be also renamed, but
|
---|
3533 | only if it has exactly the same name as the settings file
|
---|
3534 | itself prior to changing this property (for backward compatibility
|
---|
3535 | with previous API releases). The above implies the following
|
---|
3536 | limitations:
|
---|
3537 | <ul>
|
---|
3538 | <li>The machine name cannot be empty.</li>
|
---|
3539 | <li>The machine name can contain only characters that are valid
|
---|
3540 | file name characters according to the rules of the file
|
---|
3541 | system used to store VirtualBox configuration.</li>
|
---|
3542 | <li>You cannot have two or more machines with the same name
|
---|
3543 | if they use the same subdirectory for storing the machine
|
---|
3544 | settings files.</li>
|
---|
3545 | <li>You cannot change the name of the machine if it is running,
|
---|
3546 | or if any file in the directory containing the settings file
|
---|
3547 | is being used by another running machine or by any other
|
---|
3548 | process in the host operating system at a time when
|
---|
3549 | <link to="#saveSettings"/> is called.
|
---|
3550 | </li>
|
---|
3551 | </ul>
|
---|
3552 | If any of the above limitations are hit, <link to="#saveSettings"/>
|
---|
3553 | will return an appropriate error message explaining the exact
|
---|
3554 | reason and the changes you made to this machine will not be saved.
|
---|
3555 |
|
---|
3556 | Starting with VirtualBox 4.0, a “.vbox” extension of the settings
|
---|
3557 | file is recommended, but not enforced. (Previous versions always
|
---|
3558 | used a generic ".xml" extension.)
|
---|
3559 | </desc>
|
---|
3560 | </attribute>
|
---|
3561 |
|
---|
3562 | <attribute name="description" type="wstring">
|
---|
3563 | <desc>
|
---|
3564 | Description of the virtual machine.
|
---|
3565 |
|
---|
3566 | The description attribute can contain any text and is
|
---|
3567 | typically used to describe the hardware and software
|
---|
3568 | configuration of the virtual machine in detail (i.e. network
|
---|
3569 | settings, versions of the installed software and so on).
|
---|
3570 | </desc>
|
---|
3571 | </attribute>
|
---|
3572 |
|
---|
3573 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
3574 | <desc>UUID of the virtual machine.</desc>
|
---|
3575 | </attribute>
|
---|
3576 |
|
---|
3577 | <attribute name="OSTypeId" type="wstring">
|
---|
3578 | <desc>
|
---|
3579 | User-defined identifier of the Guest OS type.
|
---|
3580 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
3581 | an IGuestOSType object representing details about the given
|
---|
3582 | Guest OS type.
|
---|
3583 | <note>
|
---|
3584 | This value may differ from the value returned by
|
---|
3585 | <link to="IGuest::OSTypeId"/> if Guest Additions are
|
---|
3586 | installed to the guest OS.
|
---|
3587 | </note>
|
---|
3588 | </desc>
|
---|
3589 | </attribute>
|
---|
3590 |
|
---|
3591 | <attribute name="HardwareVersion" type="wstring">
|
---|
3592 | <desc>Hardware version identifier. Internal use only for now.</desc>
|
---|
3593 | </attribute>
|
---|
3594 |
|
---|
3595 | <attribute name="hardwareUUID" type="uuid" mod="string">
|
---|
3596 | <desc>
|
---|
3597 | The UUID presented to the guest via memory tables, hardware and guest
|
---|
3598 | properties. For most VMs this is the same as the @a id, but for VMs
|
---|
3599 | which have been cloned or teleported it may be the same as the source
|
---|
3600 | VM. This latter is because the guest shouldn't notice that it was
|
---|
3601 | cloned or teleported.
|
---|
3602 | </desc>
|
---|
3603 | </attribute>
|
---|
3604 |
|
---|
3605 | <attribute name="CPUCount" type="unsigned long">
|
---|
3606 | <desc>Number of virtual CPUs in the VM.</desc>
|
---|
3607 | </attribute>
|
---|
3608 |
|
---|
3609 | <attribute name="CPUHotPlugEnabled" type="boolean">
|
---|
3610 | <desc>
|
---|
3611 | This setting determines whether VirtualBox allows CPU
|
---|
3612 | hotplugging for this machine.</desc>
|
---|
3613 | </attribute>
|
---|
3614 |
|
---|
3615 | <attribute name="CPUExecutionCap" type="unsigned long">
|
---|
3616 | <desc>
|
---|
3617 | Means to limit the number of CPU cycles a guest can use. The unit
|
---|
3618 | is percentage of host CPU cycles per second. The valid range
|
---|
3619 | is 1 - 100. 100 (the default) implies no limit.
|
---|
3620 | </desc>
|
---|
3621 | </attribute>
|
---|
3622 |
|
---|
3623 | <attribute name="memorySize" type="unsigned long">
|
---|
3624 | <desc>System memory size in megabytes.</desc>
|
---|
3625 | </attribute>
|
---|
3626 |
|
---|
3627 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
3628 | <desc>Memory balloon size in megabytes.</desc>
|
---|
3629 | </attribute>
|
---|
3630 |
|
---|
3631 | <attribute name="PageFusionEnabled" type="boolean">
|
---|
3632 | <desc>
|
---|
3633 | This setting determines whether VirtualBox allows page
|
---|
3634 | fusion for this machine (64 bits host only).
|
---|
3635 | </desc>
|
---|
3636 | </attribute>
|
---|
3637 |
|
---|
3638 | <attribute name="VRAMSize" type="unsigned long">
|
---|
3639 | <desc>Video memory size in megabytes.</desc>
|
---|
3640 | </attribute>
|
---|
3641 |
|
---|
3642 | <attribute name="accelerate3DEnabled" type="boolean" default="false">
|
---|
3643 | <desc>
|
---|
3644 | This setting determines whether VirtualBox allows this machine to make
|
---|
3645 | use of the 3D graphics support available on the host.</desc>
|
---|
3646 | </attribute>
|
---|
3647 |
|
---|
3648 | <attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
|
---|
3649 | <desc>
|
---|
3650 | This setting determines whether VirtualBox allows this machine to make
|
---|
3651 | use of the 2D video acceleration support available on the host.</desc>
|
---|
3652 | </attribute>
|
---|
3653 |
|
---|
3654 | <attribute name="monitorCount" type="unsigned long">
|
---|
3655 | <desc>
|
---|
3656 | Number of virtual monitors.
|
---|
3657 | <note>
|
---|
3658 | Only effective on Windows XP and later guests with
|
---|
3659 | Guest Additions installed.
|
---|
3660 | </note>
|
---|
3661 | </desc>
|
---|
3662 | </attribute>
|
---|
3663 |
|
---|
3664 | <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes">
|
---|
3665 | <desc>Object containing all BIOS settings.</desc>
|
---|
3666 | </attribute>
|
---|
3667 |
|
---|
3668 | <attribute name="firmwareType" type="FirmwareType">
|
---|
3669 | <desc>Type of firmware (such as legacy BIOS or EFI), used for initial
|
---|
3670 | bootstrap in this VM.</desc>
|
---|
3671 | </attribute>
|
---|
3672 |
|
---|
3673 | <attribute name="pointingHidType" type="PointingHidType">
|
---|
3674 | <desc>Type of pointing HID (such as mouse or tablet) used in this VM.
|
---|
3675 | The default is typically "PS2Mouse" but can vary depending on the
|
---|
3676 | requirements of the guest operating system.</desc>
|
---|
3677 | </attribute>
|
---|
3678 |
|
---|
3679 | <attribute name="keyboardHidType" type="KeyboardHidType">
|
---|
3680 | <desc>Type of keyboard HID used in this VM.
|
---|
3681 | The default is typically "PS2Keyboard" but can vary depending on the
|
---|
3682 | requirements of the guest operating system.</desc>
|
---|
3683 | </attribute>
|
---|
3684 |
|
---|
3685 | <attribute name="hpetEnabled" type="boolean">
|
---|
3686 | <desc>This attribute controls if High Precision Event Timer (HPET) is
|
---|
3687 | enabled in this VM. Use this property if you want to provide guests
|
---|
3688 | with additional time source, or if guest requires HPET to function correctly.
|
---|
3689 | Default is false.</desc>
|
---|
3690 | </attribute>
|
---|
3691 |
|
---|
3692 | <attribute name="chipsetType" type="ChipsetType">
|
---|
3693 | <desc>Chipset type used in this VM.</desc>
|
---|
3694 | </attribute>
|
---|
3695 |
|
---|
3696 | <attribute name="snapshotFolder" type="wstring">
|
---|
3697 | <desc>
|
---|
3698 | Full path to the directory used to store snapshot data
|
---|
3699 | (differencing media and saved state files) of this machine.
|
---|
3700 |
|
---|
3701 | The initial value of this property is
|
---|
3702 | <tt><</tt><link to="#settingsFilePath">
|
---|
3703 | path_to_settings_file</link><tt>>/<</tt>
|
---|
3704 | <link to="#id">machine_uuid</link>
|
---|
3705 | <tt>></tt>.
|
---|
3706 |
|
---|
3707 | Currently, it is an error to try to change this property on
|
---|
3708 | a machine that has snapshots (because this would require to
|
---|
3709 | move possibly large files to a different location).
|
---|
3710 | A separate method will be available for this purpose later.
|
---|
3711 |
|
---|
3712 | <note>
|
---|
3713 | Setting this property to @c null or to an empty string will restore
|
---|
3714 | the initial value.
|
---|
3715 | </note>
|
---|
3716 | <note>
|
---|
3717 | When setting this property, the specified path can be
|
---|
3718 | absolute (full path) or relative to the directory where the
|
---|
3719 | <link to="#settingsFilePath">machine settings file</link>
|
---|
3720 | is located. When reading this property, a full path is
|
---|
3721 | always returned.
|
---|
3722 | </note>
|
---|
3723 | <note>
|
---|
3724 | The specified path may not exist, it will be created
|
---|
3725 | when necessary.
|
---|
3726 | </note>
|
---|
3727 | </desc>
|
---|
3728 | </attribute>
|
---|
3729 |
|
---|
3730 | <attribute name="VRDEServer" type="IVRDEServer" readonly="yes">
|
---|
3731 | <desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc>
|
---|
3732 | </attribute>
|
---|
3733 |
|
---|
3734 | <attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes">
|
---|
3735 | <desc>Array of media attached to this machine.</desc>
|
---|
3736 | </attribute>
|
---|
3737 |
|
---|
3738 | <attribute name="USBController" type="IUSBController" readonly="yes">
|
---|
3739 | <desc>
|
---|
3740 | Associated USB controller object.
|
---|
3741 |
|
---|
3742 | <note>
|
---|
3743 | If USB functionality is not available in the given edition of
|
---|
3744 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
3745 | </note>
|
---|
3746 | </desc>
|
---|
3747 | </attribute>
|
---|
3748 |
|
---|
3749 | <attribute name="audioAdapter" type="IAudioAdapter" readonly="yes">
|
---|
3750 | <desc>Associated audio adapter, always present.</desc>
|
---|
3751 | </attribute>
|
---|
3752 |
|
---|
3753 | <attribute name="storageControllers" type="IStorageController" readonly="yes" safearray="yes">
|
---|
3754 | <desc>Array of storage controllers attached to this machine.</desc>
|
---|
3755 | </attribute>
|
---|
3756 |
|
---|
3757 | <attribute name="settingsFilePath" type="wstring" readonly="yes">
|
---|
3758 | <desc>
|
---|
3759 | Full name of the file containing machine settings data.
|
---|
3760 | </desc>
|
---|
3761 | </attribute>
|
---|
3762 |
|
---|
3763 | <attribute name="settingsModified" type="boolean" readonly="yes">
|
---|
3764 | <desc>
|
---|
3765 | Whether the settings of this machine have been modified
|
---|
3766 | (but neither yet saved nor discarded).
|
---|
3767 | <note>
|
---|
3768 | Reading this property is only valid on instances returned
|
---|
3769 | by <link to="ISession::machine"/> and on new machines
|
---|
3770 | created by <link to="IVirtualBox::createMachine"/> or opened
|
---|
3771 | by <link to="IVirtualBox::openMachine"/> but not
|
---|
3772 | yet registered, or on unregistered machines after calling
|
---|
3773 | <link to="IMachine::unregister"/>. For all other
|
---|
3774 | cases, the settings can never be modified.
|
---|
3775 | </note>
|
---|
3776 | <note>
|
---|
3777 | For newly created unregistered machines, the value of this
|
---|
3778 | property is always @c true until <link to="#saveSettings"/>
|
---|
3779 | is called (no matter if any machine settings have been
|
---|
3780 | changed after the creation or not). For opened machines
|
---|
3781 | the value is set to @c false (and then follows to normal rules).
|
---|
3782 | </note>
|
---|
3783 | </desc>
|
---|
3784 | </attribute>
|
---|
3785 |
|
---|
3786 | <attribute name="sessionState" type="SessionState" readonly="yes">
|
---|
3787 | <desc>Current session state for this machine.</desc>
|
---|
3788 | </attribute>
|
---|
3789 |
|
---|
3790 | <attribute name="sessionType" type="wstring" readonly="yes">
|
---|
3791 | <desc>
|
---|
3792 | Type of the session. If <link to="#sessionState"/> is
|
---|
3793 | Spawning or Locked, this attribute contains the
|
---|
3794 | same value as passed to the
|
---|
3795 | <link to="IMachine::launchVMProcess"/> method in the
|
---|
3796 | @a type parameter. If the session was used with
|
---|
3797 | <link to="IMachine::lockMachine" />, or if
|
---|
3798 | <link to="#sessionState"/> is SessionClosed, the value of this
|
---|
3799 | attribute is an empty string.
|
---|
3800 | </desc>
|
---|
3801 | </attribute>
|
---|
3802 |
|
---|
3803 | <attribute name="sessionPid" type="unsigned long" readonly="yes">
|
---|
3804 | <desc>
|
---|
3805 | Identifier of the session process. This attribute contains the
|
---|
3806 | platform-dependent identifier of the process whose session was
|
---|
3807 | used with <link to="IMachine::lockMachine" /> call. The returned
|
---|
3808 | value is only valid if <link to="#sessionState"/> is Locked or
|
---|
3809 | Unlocking by the time this property is read.
|
---|
3810 | </desc>
|
---|
3811 | </attribute>
|
---|
3812 |
|
---|
3813 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
3814 | <desc>Current execution state of this machine.</desc>
|
---|
3815 | </attribute>
|
---|
3816 |
|
---|
3817 | <attribute name="lastStateChange" type="long long" readonly="yes">
|
---|
3818 | <desc>
|
---|
3819 | Time stamp of the last execution state change,
|
---|
3820 | in milliseconds since 1970-01-01 UTC.
|
---|
3821 | </desc>
|
---|
3822 | </attribute>
|
---|
3823 |
|
---|
3824 | <attribute name="stateFilePath" type="wstring" readonly="yes">
|
---|
3825 | <desc>
|
---|
3826 | Full path to the file that stores the execution state of
|
---|
3827 | the machine when it is in the <link to="MachineState_Saved"/> state.
|
---|
3828 | <note>
|
---|
3829 | When the machine is not in the Saved state, this attribute is
|
---|
3830 | an empty string.
|
---|
3831 | </note>
|
---|
3832 | </desc>
|
---|
3833 | </attribute>
|
---|
3834 |
|
---|
3835 | <attribute name="logFolder" type="wstring" readonly="yes">
|
---|
3836 | <desc>
|
---|
3837 | Full path to the folder that stores a set of rotated log files
|
---|
3838 | recorded during machine execution. The most recent log file is
|
---|
3839 | named <tt>VBox.log</tt>, the previous log file is
|
---|
3840 | named <tt>VBox.log.1</tt> and so on (up to <tt>VBox.log.3</tt>
|
---|
3841 | in the current version).
|
---|
3842 | </desc>
|
---|
3843 | </attribute>
|
---|
3844 |
|
---|
3845 | <attribute name="currentSnapshot" type="ISnapshot" readonly="yes">
|
---|
3846 | <desc>
|
---|
3847 | Current snapshot of this machine. This is @c null if the machine
|
---|
3848 | currently has no snapshots. If it is not @c null, then it was
|
---|
3849 | set by one of <link to="IConsole::takeSnapshot" />,
|
---|
3850 | <link to="IConsole::deleteSnapshot" />
|
---|
3851 | or <link to="IConsole::restoreSnapshot" />, depending on which
|
---|
3852 | was called last. See <link to="ISnapshot"/> for details.
|
---|
3853 | </desc>
|
---|
3854 | </attribute>
|
---|
3855 |
|
---|
3856 | <attribute name="snapshotCount" type="unsigned long" readonly="yes">
|
---|
3857 | <desc>
|
---|
3858 | Number of snapshots taken on this machine. Zero means the
|
---|
3859 | machine doesn't have any snapshots.
|
---|
3860 | </desc>
|
---|
3861 | </attribute>
|
---|
3862 |
|
---|
3863 | <attribute name="currentStateModified" type="boolean" readonly="yes">
|
---|
3864 | <desc>
|
---|
3865 | Returns @c true if the current state of the machine is not
|
---|
3866 | identical to the state stored in the current snapshot.
|
---|
3867 |
|
---|
3868 | The current state is identical to the current snapshot only
|
---|
3869 | directly after one of the following calls are made:
|
---|
3870 |
|
---|
3871 | <ul>
|
---|
3872 | <li><link to="IConsole::restoreSnapshot"/>
|
---|
3873 | </li>
|
---|
3874 | <li><link to="IConsole::takeSnapshot"/> (issued on a
|
---|
3875 | "powered off" or "saved" machine, for which
|
---|
3876 | <link to="#settingsModified"/> returns @c false)
|
---|
3877 | </li>
|
---|
3878 | </ul>
|
---|
3879 |
|
---|
3880 | The current state remains identical until one of the following
|
---|
3881 | happens:
|
---|
3882 | <ul>
|
---|
3883 | <li>settings of the machine are changed</li>
|
---|
3884 | <li>the saved state is deleted</li>
|
---|
3885 | <li>the current snapshot is deleted</li>
|
---|
3886 | <li>an attempt to execute the machine is made</li>
|
---|
3887 | </ul>
|
---|
3888 |
|
---|
3889 | <note>
|
---|
3890 | For machines that don't have snapshots, this property is
|
---|
3891 | always @c false.
|
---|
3892 | </note>
|
---|
3893 | </desc>
|
---|
3894 | </attribute>
|
---|
3895 |
|
---|
3896 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
3897 | <desc>
|
---|
3898 | Collection of shared folders for this machine (permanent shared
|
---|
3899 | folders). These folders are shared automatically at machine startup
|
---|
3900 | and available only to the guest OS installed within this machine.
|
---|
3901 |
|
---|
3902 | New shared folders are added to the collection using
|
---|
3903 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
3904 | removed using <link to="#removeSharedFolder"/>.
|
---|
3905 | </desc>
|
---|
3906 | </attribute>
|
---|
3907 |
|
---|
3908 | <attribute name="clipboardMode" type="ClipboardMode">
|
---|
3909 | <desc>
|
---|
3910 | Synchronization mode between the host OS clipboard
|
---|
3911 | and the guest OS clipboard.
|
---|
3912 | </desc>
|
---|
3913 | </attribute>
|
---|
3914 |
|
---|
3915 | <attribute name="guestPropertyNotificationPatterns" type="wstring">
|
---|
3916 | <desc>
|
---|
3917 | A comma-separated list of simple glob patterns. Changes to guest
|
---|
3918 | properties whose name matches one of the patterns will generate an
|
---|
3919 | <link to="IGuestPropertyChangedEvent"/> signal.
|
---|
3920 | </desc>
|
---|
3921 | </attribute>
|
---|
3922 |
|
---|
3923 | <attribute name="teleporterEnabled" type="boolean">
|
---|
3924 | <desc>
|
---|
3925 | When set to @a true, the virtual machine becomes a target teleporter
|
---|
3926 | the next time it is powered on. This can only set to @a true when the
|
---|
3927 | VM is in the @a PoweredOff or @a Aborted state.
|
---|
3928 |
|
---|
3929 | <!-- This property is automatically set to @a false when the VM is powered
|
---|
3930 | on. (bird: This doesn't work yet ) -->
|
---|
3931 | </desc>
|
---|
3932 | </attribute>
|
---|
3933 |
|
---|
3934 | <attribute name="teleporterPort" type="unsigned long">
|
---|
3935 | <desc>
|
---|
3936 | The TCP port the target teleporter will listen for incoming
|
---|
3937 | teleportations on.
|
---|
3938 |
|
---|
3939 | 0 means the port is automatically selected upon power on. The actual
|
---|
3940 | value can be read from this property while the machine is waiting for
|
---|
3941 | incoming teleportations.
|
---|
3942 | </desc>
|
---|
3943 | </attribute>
|
---|
3944 |
|
---|
3945 | <attribute name="teleporterAddress" type="wstring">
|
---|
3946 | <desc>
|
---|
3947 | The address the target teleporter will listen on. If set to an empty
|
---|
3948 | string, it will listen on all addresses.
|
---|
3949 | </desc>
|
---|
3950 | </attribute>
|
---|
3951 |
|
---|
3952 | <attribute name="teleporterPassword" type="wstring">
|
---|
3953 | <desc>
|
---|
3954 | The password to check for on the target teleporter. This is just a
|
---|
3955 | very basic measure to prevent simple hacks and operators accidentally
|
---|
3956 | beaming a virtual machine to the wrong place.
|
---|
3957 | </desc>
|
---|
3958 | </attribute>
|
---|
3959 |
|
---|
3960 | <attribute name="faultToleranceState" type="FaultToleranceState">
|
---|
3961 | <desc>
|
---|
3962 | Fault tolerance state; disabled, source or target.
|
---|
3963 | This property can be changed at any time. If you change it for a running
|
---|
3964 | VM, then the fault tolerance address and port must be set beforehand.
|
---|
3965 | </desc>
|
---|
3966 | </attribute>
|
---|
3967 |
|
---|
3968 | <attribute name="faultTolerancePort" type="unsigned long">
|
---|
3969 | <desc>
|
---|
3970 | The TCP port the fault tolerance source or target will use for
|
---|
3971 | communication.
|
---|
3972 | </desc>
|
---|
3973 | </attribute>
|
---|
3974 |
|
---|
3975 | <attribute name="faultToleranceAddress" type="wstring">
|
---|
3976 | <desc>
|
---|
3977 | The address the fault tolerance source or target.
|
---|
3978 | </desc>
|
---|
3979 | </attribute>
|
---|
3980 |
|
---|
3981 | <attribute name="faultTolerancePassword" type="wstring">
|
---|
3982 | <desc>
|
---|
3983 | The password to check for on the standby VM. This is just a
|
---|
3984 | very basic measure to prevent simple hacks and operators accidentally
|
---|
3985 | choosing the wrong standby VM.
|
---|
3986 | </desc>
|
---|
3987 | </attribute>
|
---|
3988 |
|
---|
3989 | <attribute name="faultToleranceSyncInterval" type="unsigned long">
|
---|
3990 | <desc>
|
---|
3991 | The interval in ms used for syncing the state between source and target.
|
---|
3992 | </desc>
|
---|
3993 | </attribute>
|
---|
3994 |
|
---|
3995 | <attribute name="RTCUseUTC" type="boolean">
|
---|
3996 | <desc>
|
---|
3997 | When set to @a true, the RTC device of the virtual machine will run
|
---|
3998 | in UTC time, otherwise in local time. Especially Unix guests prefer
|
---|
3999 | the time in UTC.
|
---|
4000 | </desc>
|
---|
4001 | </attribute>
|
---|
4002 |
|
---|
4003 | <attribute name="ioCacheEnabled" type="boolean">
|
---|
4004 | <desc>
|
---|
4005 | When set to @a true, the builtin I/O cache of the virtual machine
|
---|
4006 | will be enabled.
|
---|
4007 | </desc>
|
---|
4008 | </attribute>
|
---|
4009 |
|
---|
4010 | <attribute name="ioCacheSize" type="unsigned long">
|
---|
4011 | <desc>
|
---|
4012 | Maximum size of the I/O cache in MB.
|
---|
4013 | </desc>
|
---|
4014 | </attribute>
|
---|
4015 |
|
---|
4016 | <method name="lockMachine">
|
---|
4017 | <desc>
|
---|
4018 | Locks the machine for the given session to enable the caller
|
---|
4019 | to make changes to the machine or start the VM or control
|
---|
4020 | VM execution.
|
---|
4021 |
|
---|
4022 | There are two ways to lock a machine for such uses:
|
---|
4023 |
|
---|
4024 | <ul>
|
---|
4025 | <li>If you want to make changes to the machine settings,
|
---|
4026 | you must obtain an exclusive write lock on the machine
|
---|
4027 | by setting @a lockType to @c Write.
|
---|
4028 |
|
---|
4029 | This will only succeed if no other process has locked
|
---|
4030 | the machine to prevent conflicting changes. Only after
|
---|
4031 | an exclusive write lock has been obtained using this method, one
|
---|
4032 | can change all VM settings or execute the VM in the process
|
---|
4033 | space of the session object. (Note that the latter is only of
|
---|
4034 | interest if you actually want to write a new front-end for
|
---|
4035 | virtual machines; but this API gets called internally by
|
---|
4036 | the existing front-ends such as VBoxHeadless and the VirtualBox
|
---|
4037 | GUI to acquire a write lock on the machine that they are running.)
|
---|
4038 |
|
---|
4039 | On success, write-locking the machine for a session creates
|
---|
4040 | a second copy of the IMachine object. It is this second object
|
---|
4041 | upon which changes can be made; in VirtualBox terminology, the
|
---|
4042 | second copy is "mutable". It is only this second, mutable machine
|
---|
4043 | object upon which you can call methods that change the
|
---|
4044 | machine state. After having called this method, you can
|
---|
4045 | obtain this second, mutable machine object using the
|
---|
4046 | <link to="ISession::machine" /> attribute.
|
---|
4047 | </li>
|
---|
4048 | <li>If you only want to check the machine state or control
|
---|
4049 | machine execution without actually changing machine
|
---|
4050 | settings (e.g. to get access to VM statistics or take
|
---|
4051 | a snapshot or save the machine state), then set the
|
---|
4052 | @a lockType argument to @c Shared.
|
---|
4053 |
|
---|
4054 | If no other session has obtained a lock, you will obtain an
|
---|
4055 | exclusive write lock as described above. However, if another
|
---|
4056 | session has already obtained such a lock, then a link to that
|
---|
4057 | existing session will be established which allows you
|
---|
4058 | to control that existing session.
|
---|
4059 |
|
---|
4060 | To find out which type of lock was obtained, you can
|
---|
4061 | inspect <link to="ISession::type" />, which will have been
|
---|
4062 | set to either @c WriteLock or @c Shared.
|
---|
4063 | </li>
|
---|
4064 | </ul>
|
---|
4065 |
|
---|
4066 | In either case, you can get access to the <link to="IConsole" />
|
---|
4067 | object which controls VM execution.
|
---|
4068 |
|
---|
4069 | Also in all of the above cases, one must always call
|
---|
4070 | <link to="ISession::unlockMachine" /> to release the lock on the machine, or
|
---|
4071 | the machine's state will eventually be set to "Aborted".
|
---|
4072 |
|
---|
4073 | To change settings on a machine, the following sequence is typically
|
---|
4074 | performed:
|
---|
4075 |
|
---|
4076 | <ol>
|
---|
4077 | <li>Call this method to obtain an exclusive write lock for the current session.</li>
|
---|
4078 |
|
---|
4079 | <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
|
---|
4080 |
|
---|
4081 | <li>Change the settings of the machine by invoking IMachine methods.</li>
|
---|
4082 |
|
---|
4083 | <li>Call <link to="IMachine::saveSettings" />.</li>
|
---|
4084 |
|
---|
4085 | <li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
|
---|
4086 | </ol>
|
---|
4087 |
|
---|
4088 | <result name="E_UNEXPECTED">
|
---|
4089 | Virtual machine not registered.
|
---|
4090 | </result>
|
---|
4091 | <result name="E_ACCESSDENIED">
|
---|
4092 | Process not started by OpenRemoteSession.
|
---|
4093 | </result>
|
---|
4094 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4095 | Session already open or being opened.
|
---|
4096 | </result>
|
---|
4097 | <result name="VBOX_E_VM_ERROR">
|
---|
4098 | Failed to assign machine to session.
|
---|
4099 | </result>
|
---|
4100 | </desc>
|
---|
4101 | <param name="session" type="ISession" dir="in">
|
---|
4102 | <desc>
|
---|
4103 | Session object for which the machine will be locked.
|
---|
4104 | </desc>
|
---|
4105 | </param>
|
---|
4106 | <param name="lockType" type="LockType" dir="in">
|
---|
4107 | <desc>
|
---|
4108 | If set to @c Write, then attempt to acquire an exclusive write lock or fail.
|
---|
4109 | If set to @c Shared, then either acquire an exclusive write lock or establish
|
---|
4110 | a link to an existing session.
|
---|
4111 | </desc>
|
---|
4112 | </param>
|
---|
4113 | </method>
|
---|
4114 |
|
---|
4115 | <method name="launchVMProcess">
|
---|
4116 | <desc>
|
---|
4117 | Spawns a new process that will execute the virtual machine and obtains a shared
|
---|
4118 | lock on the machine for the calling session.
|
---|
4119 |
|
---|
4120 | If launching the VM succeeds, the new VM process will create its own session
|
---|
4121 | and write-lock the machine for it, preventing conflicting changes from other
|
---|
4122 | processes. If the machine is already locked (because it is already running or
|
---|
4123 | because another session has a write lock), launching the VM process will therefore
|
---|
4124 | fail. Reversely, future attempts to obtain a write lock will also fail while the
|
---|
4125 | machine is running.
|
---|
4126 |
|
---|
4127 | The caller's session object remains separate from the session opened by the new
|
---|
4128 | VM process. It receives its own <link to="IConsole" /> object which can be used
|
---|
4129 | to control machine execution, but it cannot be used to change all VM settings
|
---|
4130 | which would be available after a <link to="#lockMachine" /> call.
|
---|
4131 |
|
---|
4132 | The caller must eventually release the session's shared lock by calling
|
---|
4133 | <link to="ISession::unlockMachine" /> on the local session object once this call
|
---|
4134 | has returned. However, the session's state (see <link to="ISession::state" />)
|
---|
4135 | will not return to "Unlocked" until the remote session has also unlocked
|
---|
4136 | the machine (i.e. the machine has stopped running).
|
---|
4137 |
|
---|
4138 | Launching a VM process can take some time (a new VM is started in a new process,
|
---|
4139 | for which memory and other resources need to be set up). Because of this,
|
---|
4140 | an <link to="IProgress" /> object is returned to allow the caller to wait
|
---|
4141 | for this asynchronous operation to be completed. Until then, the caller's
|
---|
4142 | session object remains in the "Unlocked" state, and its <link to="ISession::machine" />
|
---|
4143 | and <link to="ISession::console" /> attributes cannot be accessed.
|
---|
4144 | It is recommended to use <link to="IProgress::waitForCompletion" /> or
|
---|
4145 | similar calls to wait for completion. Completion is signalled when the VM
|
---|
4146 | is powered on. If launching the VM fails, error messages can be queried
|
---|
4147 | via the progress object, if available.
|
---|
4148 |
|
---|
4149 | The progress object will have at least 2 sub-operations. The first
|
---|
4150 | operation covers the period up to the new VM process calls powerUp.
|
---|
4151 | The subsequent operations mirror the <link to="IConsole::powerUp"/>
|
---|
4152 | progress object. Because <link to="IConsole::powerUp"/> may require
|
---|
4153 | some extra sub-operations, the <link to="IProgress::operationCount"/>
|
---|
4154 | may change at the completion of operation.
|
---|
4155 |
|
---|
4156 | For details on the teleportation progress operation, see
|
---|
4157 | <link to="IConsole::powerUp"/>.
|
---|
4158 |
|
---|
4159 | The @a environment argument is a string containing definitions of
|
---|
4160 | environment variables in the following format:
|
---|
4161 | @code
|
---|
4162 | NAME[=VALUE]\n
|
---|
4163 | NAME[=VALUE]\n
|
---|
4164 | ...
|
---|
4165 | @endcode
|
---|
4166 | where <tt>\\n</tt> is the new line character. These environment
|
---|
4167 | variables will be appended to the environment of the VirtualBox server
|
---|
4168 | process. If an environment variable exists both in the server process
|
---|
4169 | and in this list, the value from this list takes precedence over the
|
---|
4170 | server's variable. If the value of the environment variable is
|
---|
4171 | omitted, this variable will be removed from the resulting environment.
|
---|
4172 | If the environment string is @c null or empty, the server environment
|
---|
4173 | is inherited by the started process as is.
|
---|
4174 |
|
---|
4175 | <result name="E_UNEXPECTED">
|
---|
4176 | Virtual machine not registered.
|
---|
4177 | </result>
|
---|
4178 | <result name="E_INVALIDARG">
|
---|
4179 | Invalid session type @a type.
|
---|
4180 | </result>
|
---|
4181 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4182 | No machine matching @a machineId found.
|
---|
4183 | </result>
|
---|
4184 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4185 | Session already open or being opened.
|
---|
4186 | </result>
|
---|
4187 | <result name="VBOX_E_IPRT_ERROR">
|
---|
4188 | Launching process for machine failed.
|
---|
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 | Client session object to which the VM process will be connected (this
|
---|
4197 | must be in "Unlocked" state).
|
---|
4198 | </desc>
|
---|
4199 | </param>
|
---|
4200 | <param name="type" type="wstring" dir="in">
|
---|
4201 | <desc>
|
---|
4202 | Front-end to use for the new VM process. The following are currently supported:
|
---|
4203 | <ul>
|
---|
4204 | <li><tt>"gui"</tt>: VirtualBox Qt GUI front-end</li>
|
---|
4205 | <li><tt>"headless"</tt>: VBoxHeadless (VRDE Server) front-end</li>
|
---|
4206 | <li><tt>"sdl"</tt>: VirtualBox SDL front-end</li>
|
---|
4207 | </ul>
|
---|
4208 | </desc>
|
---|
4209 | </param>
|
---|
4210 | <param name="environment" type="wstring" dir="in">
|
---|
4211 | <desc>
|
---|
4212 | Environment to pass to the VM process.
|
---|
4213 | </desc>
|
---|
4214 | </param>
|
---|
4215 | <param name="progress" type="IProgress" dir="return">
|
---|
4216 | <desc>Progress object to track the operation completion.</desc>
|
---|
4217 | </param>
|
---|
4218 | </method>
|
---|
4219 |
|
---|
4220 | <method name="setBootOrder">
|
---|
4221 | <desc>
|
---|
4222 | Puts the given device to the specified position in
|
---|
4223 | the boot order.
|
---|
4224 |
|
---|
4225 | To indicate that no device is associated with the given position,
|
---|
4226 | <link to="DeviceType_Null"/> should be used.
|
---|
4227 |
|
---|
4228 | @todo setHardDiskBootOrder(), setNetworkBootOrder()
|
---|
4229 |
|
---|
4230 | <result name="E_INVALIDARG">
|
---|
4231 | Boot @a position out of range.
|
---|
4232 | </result>
|
---|
4233 | <result name="E_NOTIMPL">
|
---|
4234 | Booting from USB @a device currently not supported.
|
---|
4235 | </result>
|
---|
4236 |
|
---|
4237 | </desc>
|
---|
4238 | <param name="position" type="unsigned long" dir="in">
|
---|
4239 | <desc>
|
---|
4240 | Position in the boot order (@c 1 to the total number of
|
---|
4241 | devices the machine can boot from, as returned by
|
---|
4242 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4243 | </desc>
|
---|
4244 | </param>
|
---|
4245 | <param name="device" type="DeviceType" dir="in">
|
---|
4246 | <desc>
|
---|
4247 | The type of the device used to boot at the given position.
|
---|
4248 | </desc>
|
---|
4249 | </param>
|
---|
4250 | </method>
|
---|
4251 |
|
---|
4252 | <method name="getBootOrder" const="yes">
|
---|
4253 | <desc>
|
---|
4254 | Returns the device type that occupies the specified
|
---|
4255 | position in the boot order.
|
---|
4256 |
|
---|
4257 | @todo [remove?]
|
---|
4258 | If the machine can have more than one device of the returned type
|
---|
4259 | (such as hard disks), then a separate method should be used to
|
---|
4260 | retrieve the individual device that occupies the given position.
|
---|
4261 |
|
---|
4262 | If here are no devices at the given position, then
|
---|
4263 | <link to="DeviceType_Null"/> is returned.
|
---|
4264 |
|
---|
4265 | @todo getHardDiskBootOrder(), getNetworkBootOrder()
|
---|
4266 |
|
---|
4267 | <result name="E_INVALIDARG">
|
---|
4268 | Boot @a position out of range.
|
---|
4269 | </result>
|
---|
4270 |
|
---|
4271 | </desc>
|
---|
4272 | <param name="position" type="unsigned long" dir="in">
|
---|
4273 | <desc>
|
---|
4274 | Position in the boot order (@c 1 to the total number of
|
---|
4275 | devices the machine can boot from, as returned by
|
---|
4276 | <link to="ISystemProperties::maxBootPosition"/>).
|
---|
4277 | </desc>
|
---|
4278 | </param>
|
---|
4279 | <param name="device" type="DeviceType" dir="return">
|
---|
4280 | <desc>
|
---|
4281 | Device at the given position.
|
---|
4282 | </desc>
|
---|
4283 | </param>
|
---|
4284 | </method>
|
---|
4285 |
|
---|
4286 | <method name="attachDevice">
|
---|
4287 | <desc>
|
---|
4288 | Attaches a device and optionally mounts a medium to the given storage
|
---|
4289 | controller (<link to="IStorageController" />, identified by @a name),
|
---|
4290 | at the indicated port and device.
|
---|
4291 |
|
---|
4292 | This method is intended for managing storage devices in general while a
|
---|
4293 | machine is powered off. It can be used to attach and detach fixed
|
---|
4294 | and removeable media. The following kind of media can be attached
|
---|
4295 | to a machine:
|
---|
4296 |
|
---|
4297 | <ul>
|
---|
4298 | <li>For fixed and removable media, you can pass in a medium that was
|
---|
4299 | previously opened using <link to="IVirtualBox::openMedium" />.
|
---|
4300 | </li>
|
---|
4301 |
|
---|
4302 | <li>Only for storage devices supporting removable media (such as
|
---|
4303 | DVDs and floppies), you can also specify a null pointer to
|
---|
4304 | indicate an empty drive or one of the medium objects listed
|
---|
4305 | in the <link to="IHost::DVDDrives" /> and <link to="IHost::floppyDrives"/>
|
---|
4306 | arrays to indicate a host drive.
|
---|
4307 | For removeable devices, you can also use <link to="IMachine::mountMedium"/>
|
---|
4308 | to change the media while the machine is running.
|
---|
4309 | </li>
|
---|
4310 | </ul>
|
---|
4311 |
|
---|
4312 | In a VM's default configuration of virtual machines, the secondary
|
---|
4313 | master of the IDE controller is used for a CD/DVD drive.
|
---|
4314 |
|
---|
4315 | After calling this returns successfully, a new instance of
|
---|
4316 | <link to="IMediumAttachment"/> will appear in the machine's list of medium
|
---|
4317 | attachments (see <link to="IMachine::mediumAttachments"/>).
|
---|
4318 |
|
---|
4319 | See <link to="IMedium"/> and <link to="IMediumAttachment"/> for more
|
---|
4320 | information about attaching media.
|
---|
4321 |
|
---|
4322 | The specified device slot must not have a device attached to it,
|
---|
4323 | or this method will fail.
|
---|
4324 |
|
---|
4325 | <note>
|
---|
4326 | You cannot attach a device to a newly created machine until
|
---|
4327 | this machine's settings are saved to disk using
|
---|
4328 | <link to="#saveSettings"/>.
|
---|
4329 | </note>
|
---|
4330 | <note>
|
---|
4331 | If the medium is being attached indirectly, a new differencing medium
|
---|
4332 | will implicitly be created for it and attached instead. If the
|
---|
4333 | changes made to the machine settings (including this indirect
|
---|
4334 | attachment) are later cancelled using <link to="#discardSettings"/>,
|
---|
4335 | this implicitly created differencing medium will implicitly
|
---|
4336 | be deleted.
|
---|
4337 | </note>
|
---|
4338 |
|
---|
4339 | <result name="E_INVALIDARG">
|
---|
4340 | SATA device, SATA port, IDE port or IDE slot out of range, or
|
---|
4341 | file or UUID not found.
|
---|
4342 | </result>
|
---|
4343 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4344 | Machine must be registered before media can be attached.
|
---|
4345 | </result>
|
---|
4346 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4347 | Invalid machine state.
|
---|
4348 | </result>
|
---|
4349 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4350 | A medium is already attached to this or another virtual machine.
|
---|
4351 | </result>
|
---|
4352 |
|
---|
4353 | </desc>
|
---|
4354 | <param name="name" type="wstring" dir="in">
|
---|
4355 | <desc>Name of the storage controller to attach the device to.</desc>
|
---|
4356 | </param>
|
---|
4357 | <param name="controllerPort" type="long" dir="in">
|
---|
4358 | <desc>Port to attach the device to. For an IDE controller, 0 specifies
|
---|
4359 | the primary controller and 1 specifies the secondary controller.
|
---|
4360 | For a SCSI controller, this must range from 0 to 15; for a SATA controller,
|
---|
4361 | from 0 to 29; for an SAS controller, from 0 to 7.</desc>
|
---|
4362 | </param>
|
---|
4363 | <param name="device" type="long" dir="in">
|
---|
4364 | <desc>Device slot in the given port to attach the device to. This is only
|
---|
4365 | relevant for IDE controllers, for which 0 specifies the master device and
|
---|
4366 | 1 specifies the slave device. For all other controller types, this must
|
---|
4367 | be 0.</desc>
|
---|
4368 | </param>
|
---|
4369 | <param name="type" type="DeviceType" dir="in">
|
---|
4370 | <desc>Device type of the attached device. For media opened by
|
---|
4371 | <link to="IVirtualBox::openMedium" />, this must match the device type
|
---|
4372 | specified there.</desc>
|
---|
4373 | </param>
|
---|
4374 | <param name="medium" type="IMedium" dir="in">
|
---|
4375 | <desc>Medium to mount or NULL for an empty drive.</desc>
|
---|
4376 | </param>
|
---|
4377 | </method>
|
---|
4378 |
|
---|
4379 | <method name="detachDevice">
|
---|
4380 | <desc>
|
---|
4381 | Detaches the device attached to a device slot of the specified bus.
|
---|
4382 |
|
---|
4383 | Detaching the device from the virtual machine is deferred. This means
|
---|
4384 | that the medium remains associated with the machine when this method
|
---|
4385 | returns and gets actually de-associated only after a successful
|
---|
4386 | <link to="#saveSettings"/> call. See <link to="IMedium"/>
|
---|
4387 | for more detailed information about attaching media.
|
---|
4388 |
|
---|
4389 | <note>
|
---|
4390 | You cannot detach a device from a running machine.
|
---|
4391 | </note>
|
---|
4392 | <note>
|
---|
4393 | Detaching differencing media implicitly created by <link
|
---|
4394 | to="#attachDevice"/> for the indirect attachment using this
|
---|
4395 | method will <b>not</b> implicitly delete them. The
|
---|
4396 | <link to="IMedium::deleteStorage"/> operation should be
|
---|
4397 | explicitly performed by the caller after the medium is successfully
|
---|
4398 | detached and the settings are saved with
|
---|
4399 | <link to="#saveSettings"/>, if it is the desired action.
|
---|
4400 | </note>
|
---|
4401 |
|
---|
4402 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4403 | Attempt to detach medium from a running virtual machine.
|
---|
4404 | </result>
|
---|
4405 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4406 | No medium attached to given slot/bus.
|
---|
4407 | </result>
|
---|
4408 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
4409 | Medium format does not support storage deletion.
|
---|
4410 | </result>
|
---|
4411 |
|
---|
4412 | </desc>
|
---|
4413 | <param name="name" type="wstring" dir="in">
|
---|
4414 | <desc>Name of the storage controller to detach the medium from.</desc>
|
---|
4415 | </param>
|
---|
4416 | <param name="controllerPort" type="long" dir="in">
|
---|
4417 | <desc>Port number to detach the medium from.</desc>
|
---|
4418 | </param>
|
---|
4419 | <param name="device" type="long" dir="in">
|
---|
4420 | <desc>Device slot number to detach the medium from.</desc>
|
---|
4421 | </param>
|
---|
4422 | </method>
|
---|
4423 |
|
---|
4424 | <method name="passthroughDevice">
|
---|
4425 | <desc>
|
---|
4426 | Sets the passthrough mode of an existing DVD device. Changing the
|
---|
4427 | setting while the VM is running is forbidden. The setting is only used
|
---|
4428 | if at VM start the device is configured as a host DVD drive, in all
|
---|
4429 | other cases it is ignored. The device must already exist; see
|
---|
4430 | <link to="IMachine::attachDevice"/> for how to attach a new device.
|
---|
4431 |
|
---|
4432 | The @a controllerPort and @a device parameters specify the device slot and
|
---|
4433 | have have the same meaning as with <link to="IMachine::attachDevice" />.
|
---|
4434 |
|
---|
4435 | <result name="E_INVALIDARG">
|
---|
4436 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4437 | </result>
|
---|
4438 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4439 | Attempt to modify an unregistered virtual machine.
|
---|
4440 | </result>
|
---|
4441 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4442 | Invalid machine state.
|
---|
4443 | </result>
|
---|
4444 |
|
---|
4445 | </desc>
|
---|
4446 | <param name="name" type="wstring" dir="in">
|
---|
4447 | <desc>Name of the storage controller.</desc>
|
---|
4448 | </param>
|
---|
4449 | <param name="controllerPort" type="long" dir="in">
|
---|
4450 | <desc>Storage controller port.</desc>
|
---|
4451 | </param>
|
---|
4452 | <param name="device" type="long" dir="in">
|
---|
4453 | <desc>Device slot in the given port.</desc>
|
---|
4454 | </param>
|
---|
4455 | <param name="passthrough" type="boolean" dir="in">
|
---|
4456 | <desc>New value for the passthrough setting.</desc>
|
---|
4457 | </param>
|
---|
4458 | </method>
|
---|
4459 |
|
---|
4460 | <method name="mountMedium">
|
---|
4461 | <desc>
|
---|
4462 | Mounts a medium (<link to="IMedium" />, identified
|
---|
4463 | by the given UUID @a id) to the given storage controller
|
---|
4464 | (<link to="IStorageController" />, identified by @a name),
|
---|
4465 | at the indicated port and device. The device must already exist;
|
---|
4466 | see <link to="IMachine::attachDevice"/> for how to attach a new device.
|
---|
4467 |
|
---|
4468 | This method is intended only for managing removable media, where the
|
---|
4469 | device is fixed but media is changeable at runtime (such as DVDs
|
---|
4470 | and floppies). It cannot be used for fixed media such as hard disks.
|
---|
4471 |
|
---|
4472 | The @a controllerPort and @a device parameters specify the device slot and
|
---|
4473 | have have the same meaning as with <link to="IMachine::attachDevice" />.
|
---|
4474 |
|
---|
4475 | The specified device slot can have a medium mounted, which will be
|
---|
4476 | unmounted first. Specifying a zero UUID (or an empty string) for
|
---|
4477 | @a medium does just an unmount.
|
---|
4478 |
|
---|
4479 | See <link to="IMedium"/> for more detailed information about
|
---|
4480 | attaching media.
|
---|
4481 |
|
---|
4482 | <result name="E_INVALIDARG">
|
---|
4483 | SATA device, SATA port, IDE port or IDE slot out of range.
|
---|
4484 | </result>
|
---|
4485 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
4486 | Attempt to attach medium to an unregistered virtual machine.
|
---|
4487 | </result>
|
---|
4488 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
4489 | Invalid machine state.
|
---|
4490 | </result>
|
---|
4491 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4492 | Medium already attached to this or another virtual machine.
|
---|
4493 | </result>
|
---|
4494 |
|
---|
4495 | </desc>
|
---|
4496 | <param name="name" type="wstring" dir="in">
|
---|
4497 | <desc>Name of the storage controller to attach the medium to.</desc>
|
---|
4498 | </param>
|
---|
4499 | <param name="controllerPort" type="long" dir="in">
|
---|
4500 | <desc>Port to attach the medium to.</desc>
|
---|
4501 | </param>
|
---|
4502 | <param name="device" type="long" dir="in">
|
---|
4503 | <desc>Device slot in the given port to attach the medium to.</desc>
|
---|
4504 | </param>
|
---|
4505 | <param name="medium" type="IMedium" dir="in">
|
---|
4506 | <desc>Medium to mount or NULL for an empty drive.</desc>
|
---|
4507 | </param>
|
---|
4508 | <param name="force" type="boolean" dir="in">
|
---|
4509 | <desc>Allows to force unmount/mount of a medium which is locked by
|
---|
4510 | the device slot in the given port to attach the medium to.</desc>
|
---|
4511 | </param>
|
---|
4512 | </method>
|
---|
4513 |
|
---|
4514 | <method name="getMedium" const="yes">
|
---|
4515 | <desc>
|
---|
4516 | Returns the virtual medium attached to a device slot of the specified
|
---|
4517 | bus.
|
---|
4518 |
|
---|
4519 | Note that if the medium was indirectly attached by
|
---|
4520 | <link to="#mountMedium"/> to the given device slot then this
|
---|
4521 | method will return not the same object as passed to the
|
---|
4522 | <link to="#mountMedium"/> call. See <link to="IMedium"/> for
|
---|
4523 | more detailed information about mounting a medium.
|
---|
4524 |
|
---|
4525 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4526 | No medium attached to given slot/bus.
|
---|
4527 | </result>
|
---|
4528 |
|
---|
4529 | </desc>
|
---|
4530 | <param name="name" type="wstring" dir="in">
|
---|
4531 | <desc>Name of the storage controller the medium is attached to.</desc>
|
---|
4532 | </param>
|
---|
4533 | <param name="controllerPort" type="long" dir="in">
|
---|
4534 | <desc>Port to query.</desc>
|
---|
4535 | </param>
|
---|
4536 | <param name="device" type="long" dir="in">
|
---|
4537 | <desc>Device slot in the given port to query.</desc>
|
---|
4538 | </param>
|
---|
4539 | <param name="medium" type="IMedium" dir="return">
|
---|
4540 | <desc>Attached medium object.</desc>
|
---|
4541 | </param>
|
---|
4542 | </method>
|
---|
4543 |
|
---|
4544 | <method name="getMediumAttachmentsOfController" const="yes">
|
---|
4545 | <desc>
|
---|
4546 | Returns an array of medium attachments which are attached to the
|
---|
4547 | the controller with the given name.
|
---|
4548 |
|
---|
4549 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4550 | A storage controller with given name doesn't exist.
|
---|
4551 | </result>
|
---|
4552 | </desc>
|
---|
4553 | <param name="name" type="wstring" dir="in"/>
|
---|
4554 | <param name="mediumAttachments" type="IMediumAttachment" safearray="yes" dir="return"/>
|
---|
4555 | </method>
|
---|
4556 |
|
---|
4557 | <method name="getMediumAttachment" const="yes">
|
---|
4558 | <desc>
|
---|
4559 | Returns a medium attachment which corresponds to the controller with
|
---|
4560 | the given name, on the given port and device slot.
|
---|
4561 |
|
---|
4562 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4563 | No attachment exists for the given controller/port/device combination.
|
---|
4564 | </result>
|
---|
4565 | </desc>
|
---|
4566 | <param name="name" type="wstring" dir="in"/>
|
---|
4567 | <param name="controllerPort" type="long" dir="in"/>
|
---|
4568 | <param name="device" type="long" dir="in"/>
|
---|
4569 | <param name="attachment" type="IMediumAttachment" dir="return"/>
|
---|
4570 | </method>
|
---|
4571 |
|
---|
4572 | <method name="getNetworkAdapter" const="yes">
|
---|
4573 | <desc>
|
---|
4574 | Returns the network adapter associated with the given slot.
|
---|
4575 | Slots are numbered sequentially, starting with zero. The total
|
---|
4576 | number of adapters per machine is defined by the
|
---|
4577 | <link to="ISystemProperties::networkAdapterCount"/> property,
|
---|
4578 | so the maximum slot number is one less than that property's value.
|
---|
4579 |
|
---|
4580 | <result name="E_INVALIDARG">
|
---|
4581 | Invalid @a slot number.
|
---|
4582 | </result>
|
---|
4583 |
|
---|
4584 | </desc>
|
---|
4585 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4586 | <param name="adapter" type="INetworkAdapter" dir="return"/>
|
---|
4587 | </method>
|
---|
4588 |
|
---|
4589 | <method name="addStorageController">
|
---|
4590 | <desc>
|
---|
4591 | Adds a new storage controller (SCSI, SAS or SATA controller) to the
|
---|
4592 | machine and returns it as an instance of
|
---|
4593 | <link to="IStorageController" />.
|
---|
4594 |
|
---|
4595 | @a name identifies the controller for subsequent calls such as
|
---|
4596 | <link to="#getStorageControllerByName" />,
|
---|
4597 | <link to="#getStorageControllerByInstance" />,
|
---|
4598 | <link to="#removeStorageController" />,
|
---|
4599 | <link to="#attachDevice" /> or <link to="#mountMedium" />.
|
---|
4600 |
|
---|
4601 | After the controller has been added, you can set its exact
|
---|
4602 | type by setting the <link to="IStorageController::controllerType" />.
|
---|
4603 |
|
---|
4604 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
4605 | A storage controller with given name exists already.
|
---|
4606 | </result>
|
---|
4607 | <result name="E_INVALIDARG">
|
---|
4608 | Invalid @a controllerType.
|
---|
4609 | </result>
|
---|
4610 | </desc>
|
---|
4611 | <param name="name" type="wstring" dir="in"/>
|
---|
4612 | <param name="connectionType" type="StorageBus" dir="in"/>
|
---|
4613 | <param name="controller" type="IStorageController" dir="return"/>
|
---|
4614 | </method>
|
---|
4615 |
|
---|
4616 | <method name="getStorageControllerByName" const="yes">
|
---|
4617 | <desc>
|
---|
4618 | Returns a storage controller with the given name.
|
---|
4619 |
|
---|
4620 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4621 | A storage controller with given name doesn't exist.
|
---|
4622 | </result>
|
---|
4623 | </desc>
|
---|
4624 | <param name="name" type="wstring" dir="in"/>
|
---|
4625 | <param name="storageController" type="IStorageController" dir="return"/>
|
---|
4626 | </method>
|
---|
4627 |
|
---|
4628 | <method name="getStorageControllerByInstance" const="yes">
|
---|
4629 | <desc>
|
---|
4630 | Returns a storage controller with the given instance number.
|
---|
4631 |
|
---|
4632 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4633 | A storage controller with given instance number doesn't exist.
|
---|
4634 | </result>
|
---|
4635 | </desc>
|
---|
4636 | <param name="instance" type="unsigned long" dir="in"/>
|
---|
4637 | <param name="storageController" type="IStorageController" dir="return"/>
|
---|
4638 | </method>
|
---|
4639 |
|
---|
4640 | <method name="removeStorageController">
|
---|
4641 | <desc>
|
---|
4642 | Removes a storage controller from the machine.
|
---|
4643 |
|
---|
4644 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
4645 | A storage controller with given name doesn't exist.
|
---|
4646 | </result>
|
---|
4647 | </desc>
|
---|
4648 | <param name="name" type="wstring" dir="in"/>
|
---|
4649 | </method>
|
---|
4650 |
|
---|
4651 | <method name="getSerialPort" const="yes">
|
---|
4652 | <desc>
|
---|
4653 | Returns the serial port associated with the given slot.
|
---|
4654 | Slots are numbered sequentially, starting with zero. The total
|
---|
4655 | number of serial ports per machine is defined by the
|
---|
4656 | <link to="ISystemProperties::serialPortCount"/> property,
|
---|
4657 | so the maximum slot number is one less than that property's value.
|
---|
4658 |
|
---|
4659 | <result name="E_INVALIDARG">
|
---|
4660 | Invalid @a slot number.
|
---|
4661 | </result>
|
---|
4662 |
|
---|
4663 | </desc>
|
---|
4664 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4665 | <param name="port" type="ISerialPort" dir="return"/>
|
---|
4666 | </method>
|
---|
4667 |
|
---|
4668 | <method name="getParallelPort" const="yes">
|
---|
4669 | <desc>
|
---|
4670 | Returns the parallel port associated with the given slot.
|
---|
4671 | Slots are numbered sequentially, starting with zero. The total
|
---|
4672 | number of parallel ports per machine is defined by the
|
---|
4673 | <link to="ISystemProperties::parallelPortCount"/> property,
|
---|
4674 | so the maximum slot number is one less than that property's value.
|
---|
4675 |
|
---|
4676 | <result name="E_INVALIDARG">
|
---|
4677 | Invalid @a slot number.
|
---|
4678 | </result>
|
---|
4679 |
|
---|
4680 | </desc>
|
---|
4681 | <param name="slot" type="unsigned long" dir="in"/>
|
---|
4682 | <param name="port" type="IParallelPort" dir="return"/>
|
---|
4683 | </method>
|
---|
4684 |
|
---|
4685 | <method name="getExtraDataKeys">
|
---|
4686 | <desc>
|
---|
4687 | Returns an array representing the machine-specific extra data keys
|
---|
4688 | which currently have values defined.
|
---|
4689 | </desc>
|
---|
4690 | <param name="value" type="wstring" dir="return" safearray="yes">
|
---|
4691 | <desc>Array of extra data keys.</desc>
|
---|
4692 | </param>
|
---|
4693 | </method>
|
---|
4694 |
|
---|
4695 | <method name="getExtraData">
|
---|
4696 | <desc>
|
---|
4697 | Returns associated machine-specific extra data.
|
---|
4698 |
|
---|
4699 | If the requested data @a key does not exist, this function will
|
---|
4700 | succeed and return an empty string in the @a value argument.
|
---|
4701 |
|
---|
4702 | <result name="VBOX_E_FILE_ERROR">
|
---|
4703 | Settings file not accessible.
|
---|
4704 | </result>
|
---|
4705 | <result name="VBOX_E_XML_ERROR">
|
---|
4706 | Could not parse the settings file.
|
---|
4707 | </result>
|
---|
4708 |
|
---|
4709 | </desc>
|
---|
4710 | <param name="key" type="wstring" dir="in">
|
---|
4711 | <desc>Name of the data key to get.</desc>
|
---|
4712 | </param>
|
---|
4713 | <param name="value" type="wstring" dir="return">
|
---|
4714 | <desc>Value of the requested data key.</desc>
|
---|
4715 | </param>
|
---|
4716 | </method>
|
---|
4717 |
|
---|
4718 | <method name="setExtraData">
|
---|
4719 | <desc>
|
---|
4720 | Sets associated machine-specific extra data.
|
---|
4721 |
|
---|
4722 | If you pass @c null or an empty string as a key @a value, the given
|
---|
4723 | @a key will be deleted.
|
---|
4724 |
|
---|
4725 | <note>
|
---|
4726 | Before performing the actual data change, this method will ask all
|
---|
4727 | registered listeners using the
|
---|
4728 | <link to="IExtraDataCanChangeEvent"/>
|
---|
4729 | notification for a permission. If one of the listeners refuses the
|
---|
4730 | new value, the change will not be performed.
|
---|
4731 | </note>
|
---|
4732 | <note>
|
---|
4733 | On success, the
|
---|
4734 | <link to="IExtraDataChangedEvent"/> notification
|
---|
4735 | is called to inform all registered listeners about a successful data
|
---|
4736 | change.
|
---|
4737 | </note>
|
---|
4738 | <note>
|
---|
4739 | This method can be called outside the machine session and therefore
|
---|
4740 | it's a caller's responsibility to handle possible race conditions
|
---|
4741 | when several clients change the same key at the same time.
|
---|
4742 | </note>
|
---|
4743 |
|
---|
4744 | <result name="VBOX_E_FILE_ERROR">
|
---|
4745 | Settings file not accessible.
|
---|
4746 | </result>
|
---|
4747 | <result name="VBOX_E_XML_ERROR">
|
---|
4748 | Could not parse the settings file.
|
---|
4749 | </result>
|
---|
4750 |
|
---|
4751 | </desc>
|
---|
4752 | <param name="key" type="wstring" dir="in">
|
---|
4753 | <desc>Name of the data key to set.</desc>
|
---|
4754 | </param>
|
---|
4755 | <param name="value" type="wstring" dir="in">
|
---|
4756 | <desc>Value to assign to the key.</desc>
|
---|
4757 | </param>
|
---|
4758 | </method>
|
---|
4759 |
|
---|
4760 | <method name="getCPUProperty" const="yes">
|
---|
4761 | <desc>
|
---|
4762 | Returns the virtual CPU boolean value of the specified property.
|
---|
4763 |
|
---|
4764 | <result name="E_INVALIDARG">
|
---|
4765 | Invalid property.
|
---|
4766 | </result>
|
---|
4767 |
|
---|
4768 | </desc>
|
---|
4769 | <param name="property" type="CPUPropertyType" dir="in">
|
---|
4770 | <desc>
|
---|
4771 | Property type to query.
|
---|
4772 | </desc>
|
---|
4773 | </param>
|
---|
4774 | <param name="value" type="boolean" dir="return">
|
---|
4775 | <desc>
|
---|
4776 | Property value.
|
---|
4777 | </desc>
|
---|
4778 | </param>
|
---|
4779 | </method>
|
---|
4780 |
|
---|
4781 | <method name="setCPUProperty">
|
---|
4782 | <desc>
|
---|
4783 | Sets the virtual CPU boolean value of the specified property.
|
---|
4784 |
|
---|
4785 | <result name="E_INVALIDARG">
|
---|
4786 | Invalid property.
|
---|
4787 | </result>
|
---|
4788 |
|
---|
4789 | </desc>
|
---|
4790 | <param name="property" type="CPUPropertyType" dir="in">
|
---|
4791 | <desc>
|
---|
4792 | Property type to query.
|
---|
4793 | </desc>
|
---|
4794 | </param>
|
---|
4795 | <param name="value" type="boolean" dir="in">
|
---|
4796 | <desc>
|
---|
4797 | Property value.
|
---|
4798 | </desc>
|
---|
4799 | </param>
|
---|
4800 | </method>
|
---|
4801 |
|
---|
4802 | <method name="getCPUIDLeaf" const="yes">
|
---|
4803 | <desc>
|
---|
4804 | Returns the virtual CPU cpuid information for the specified leaf.
|
---|
4805 |
|
---|
4806 | Currently supported index values for cpuid:
|
---|
4807 | Standard CPUID leafs: 0 - 0xA
|
---|
4808 | Extended CPUID leafs: 0x80000000 - 0x8000000A
|
---|
4809 |
|
---|
4810 | See the Intel and AMD programmer's manuals for detailed information
|
---|
4811 | about the cpuid instruction and its leafs.
|
---|
4812 | <result name="E_INVALIDARG">
|
---|
4813 | Invalid id.
|
---|
4814 | </result>
|
---|
4815 |
|
---|
4816 | </desc>
|
---|
4817 | <param name="id" type="unsigned long" dir="in">
|
---|
4818 | <desc>
|
---|
4819 | CPUID leaf index.
|
---|
4820 | </desc>
|
---|
4821 | </param>
|
---|
4822 | <param name="valEax" type="unsigned long" dir="out">
|
---|
4823 | <desc>
|
---|
4824 | CPUID leaf value for register eax.
|
---|
4825 | </desc>
|
---|
4826 | </param>
|
---|
4827 | <param name="valEbx" type="unsigned long" dir="out">
|
---|
4828 | <desc>
|
---|
4829 | CPUID leaf value for register ebx.
|
---|
4830 | </desc>
|
---|
4831 | </param>
|
---|
4832 | <param name="valEcx" type="unsigned long" dir="out">
|
---|
4833 | <desc>
|
---|
4834 | CPUID leaf value for register ecx.
|
---|
4835 | </desc>
|
---|
4836 | </param>
|
---|
4837 | <param name="valEdx" type="unsigned long" dir="out">
|
---|
4838 | <desc>
|
---|
4839 | CPUID leaf value for register edx.
|
---|
4840 | </desc>
|
---|
4841 | </param>
|
---|
4842 | </method>
|
---|
4843 |
|
---|
4844 | <method name="setCPUIDLeaf">
|
---|
4845 | <desc>
|
---|
4846 | Sets the virtual CPU cpuid information for the specified leaf. Note that these values
|
---|
4847 | are not passed unmodified. VirtualBox clears features that it doesn't support.
|
---|
4848 |
|
---|
4849 | Currently supported index values for cpuid:
|
---|
4850 | Standard CPUID leafs: 0 - 0xA
|
---|
4851 | Extended CPUID leafs: 0x80000000 - 0x8000000A
|
---|
4852 |
|
---|
4853 | See the Intel and AMD programmer's manuals for detailed information
|
---|
4854 | about the cpuid instruction and its leafs.
|
---|
4855 |
|
---|
4856 | Do not use this method unless you know exactly what you're doing. Misuse can lead to
|
---|
4857 | random crashes inside VMs.
|
---|
4858 | <result name="E_INVALIDARG">
|
---|
4859 | Invalid id.
|
---|
4860 | </result>
|
---|
4861 |
|
---|
4862 | </desc>
|
---|
4863 | <param name="id" type="unsigned long" dir="in">
|
---|
4864 | <desc>
|
---|
4865 | CPUID leaf index.
|
---|
4866 | </desc>
|
---|
4867 | </param>
|
---|
4868 | <param name="valEax" type="unsigned long" dir="in">
|
---|
4869 | <desc>
|
---|
4870 | CPUID leaf value for register eax.
|
---|
4871 | </desc>
|
---|
4872 | </param>
|
---|
4873 | <param name="valEbx" type="unsigned long" dir="in">
|
---|
4874 | <desc>
|
---|
4875 | CPUID leaf value for register ebx.
|
---|
4876 | </desc>
|
---|
4877 | </param>
|
---|
4878 | <param name="valEcx" type="unsigned long" dir="in">
|
---|
4879 | <desc>
|
---|
4880 | CPUID leaf value for register ecx.
|
---|
4881 | </desc>
|
---|
4882 | </param>
|
---|
4883 | <param name="valEdx" type="unsigned long" dir="in">
|
---|
4884 | <desc>
|
---|
4885 | CPUID leaf value for register edx.
|
---|
4886 | </desc>
|
---|
4887 | </param>
|
---|
4888 | </method>
|
---|
4889 |
|
---|
4890 | <method name="removeCPUIDLeaf">
|
---|
4891 | <desc>
|
---|
4892 | Removes the virtual CPU cpuid leaf for the specified index
|
---|
4893 |
|
---|
4894 | <result name="E_INVALIDARG">
|
---|
4895 | Invalid id.
|
---|
4896 | </result>
|
---|
4897 |
|
---|
4898 | </desc>
|
---|
4899 | <param name="id" type="unsigned long" dir="in">
|
---|
4900 | <desc>
|
---|
4901 | CPUID leaf index.
|
---|
4902 | </desc>
|
---|
4903 | </param>
|
---|
4904 | </method>
|
---|
4905 |
|
---|
4906 | <method name="removeAllCPUIDLeaves">
|
---|
4907 | <desc>
|
---|
4908 | Removes all the virtual CPU cpuid leaves
|
---|
4909 | </desc>
|
---|
4910 | </method>
|
---|
4911 |
|
---|
4912 | <method name="getHWVirtExProperty" const="yes">
|
---|
4913 | <desc>
|
---|
4914 | Returns the value of the specified hardware virtualization boolean property.
|
---|
4915 |
|
---|
4916 | <result name="E_INVALIDARG">
|
---|
4917 | Invalid property.
|
---|
4918 | </result>
|
---|
4919 |
|
---|
4920 | </desc>
|
---|
4921 | <param name="property" type="HWVirtExPropertyType" dir="in">
|
---|
4922 | <desc>
|
---|
4923 | Property type to query.
|
---|
4924 | </desc>
|
---|
4925 | </param>
|
---|
4926 | <param name="value" type="boolean" dir="return">
|
---|
4927 | <desc>
|
---|
4928 | Property value.
|
---|
4929 | </desc>
|
---|
4930 | </param>
|
---|
4931 | </method>
|
---|
4932 |
|
---|
4933 | <method name="setHWVirtExProperty">
|
---|
4934 | <desc>
|
---|
4935 | Sets a new value for the specified hardware virtualization boolean property.
|
---|
4936 |
|
---|
4937 | <result name="E_INVALIDARG">
|
---|
4938 | Invalid property.
|
---|
4939 | </result>
|
---|
4940 |
|
---|
4941 | </desc>
|
---|
4942 | <param name="property" type="HWVirtExPropertyType" dir="in">
|
---|
4943 | <desc>
|
---|
4944 | Property type to set.
|
---|
4945 | </desc>
|
---|
4946 | </param>
|
---|
4947 | <param name="value" type="boolean" dir="in">
|
---|
4948 | <desc>
|
---|
4949 | New property value.
|
---|
4950 | </desc>
|
---|
4951 | </param>
|
---|
4952 | </method>
|
---|
4953 |
|
---|
4954 | <method name="saveSettings">
|
---|
4955 | <desc>
|
---|
4956 | Saves any changes to machine settings made since the session
|
---|
4957 | has been opened or a new machine has been created, or since the
|
---|
4958 | last call to <link to="#saveSettings"/> or <link to="#discardSettings"/>.
|
---|
4959 | For registered machines, new settings become visible to all
|
---|
4960 | other VirtualBox clients after successful invocation of this
|
---|
4961 | method.
|
---|
4962 | <note>
|
---|
4963 | The method sends <link to="IMachineDataChangedEvent"/>
|
---|
4964 | notification event after the configuration has been successfully
|
---|
4965 | saved (only for registered machines).
|
---|
4966 | </note>
|
---|
4967 | <note>
|
---|
4968 | Calling this method is only valid on instances returned
|
---|
4969 | by <link to="ISession::machine"/> and on new machines
|
---|
4970 | created by <link to="IVirtualBox::createMachine"/> but not
|
---|
4971 | yet registered, or on unregistered machines after calling
|
---|
4972 | <link to="IMachine::unregister"/>.
|
---|
4973 | </note>
|
---|
4974 |
|
---|
4975 | <result name="VBOX_E_FILE_ERROR">
|
---|
4976 | Settings file not accessible.
|
---|
4977 | </result>
|
---|
4978 | <result name="VBOX_E_XML_ERROR">
|
---|
4979 | Could not parse the settings file.
|
---|
4980 | </result>
|
---|
4981 | <result name="E_ACCESSDENIED">
|
---|
4982 | Modification request refused.
|
---|
4983 | </result>
|
---|
4984 |
|
---|
4985 | </desc>
|
---|
4986 | </method>
|
---|
4987 |
|
---|
4988 | <method name="discardSettings">
|
---|
4989 | <desc>
|
---|
4990 | Discards any changes to the machine settings made since the session
|
---|
4991 | has been opened or since the last call to <link to="#saveSettings"/>
|
---|
4992 | or <link to="#discardSettings"/>.
|
---|
4993 | <note>
|
---|
4994 | Calling this method is only valid on instances returned
|
---|
4995 | by <link to="ISession::machine"/> and on new machines
|
---|
4996 | created by <link to="IVirtualBox::createMachine"/> or
|
---|
4997 | opened by <link to="IVirtualBox::openMachine"/> but not
|
---|
4998 | yet registered, or on unregistered machines after calling
|
---|
4999 | <link to="IMachine::unregister"/>.
|
---|
5000 | </note>
|
---|
5001 |
|
---|
5002 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5003 | Virtual machine is not mutable.
|
---|
5004 | </result>
|
---|
5005 |
|
---|
5006 | </desc>
|
---|
5007 | </method>
|
---|
5008 |
|
---|
5009 | <method name="unregister">
|
---|
5010 | <desc>
|
---|
5011 | Unregisters the machine, which must have been previously registered using
|
---|
5012 | <link to="IVirtualBox::registerMachine"/>, and optionally do additional
|
---|
5013 | cleanup before the machine is unregistered.
|
---|
5014 |
|
---|
5015 | This method does not delete any files. It only changes the machine configuration and
|
---|
5016 | the list of registered machines in the VirtualBox object. To delete the files which
|
---|
5017 | belonged to the machine, including the XML file of the machine itself, call
|
---|
5018 | <link to="#delete"/>, optionally with the array of IMedium objects which was returned
|
---|
5019 | from this method.
|
---|
5020 |
|
---|
5021 | How thoroughly this method cleans up the machine configuration before unregistering
|
---|
5022 | the machine depends on the @a cleanupMode argument.
|
---|
5023 |
|
---|
5024 | <ul>
|
---|
5025 | <li>With "UnregisterOnly", the machine will only be unregistered, but no additional
|
---|
5026 | cleanup will be performed. The call will fail if the machine is in "Saved" state
|
---|
5027 | or has any snapshots or any media attached (see <link to="IMediumAttachment" />.
|
---|
5028 | It is the responsibility of the caller to delete all such configuration in this mode.
|
---|
5029 | In this mode, the API behaves like the former @c IVirtualBox::unregisterMachine() API
|
---|
5030 | which it replaces.</li>
|
---|
5031 | <li>With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved"
|
---|
5032 | state or if it has snapshots or media attached. All media attached to the current machine
|
---|
5033 | state or in snapshots will be detached. No medium objects will be returned; all of the
|
---|
5034 | machine's media will remain open.</li>
|
---|
5035 | <li>With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone",
|
---|
5036 | except that all the hard disk medium objects which were detached from the machine will
|
---|
5037 | be returned as an array. This allows for quickly passing them to the <link to="#delete" />
|
---|
5038 | API for closing and deletion.</li>
|
---|
5039 | <li>With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except
|
---|
5040 | that all media will be returned in the array, including removeable media like DVDs and
|
---|
5041 | floppies. This might be useful if the user wants to inspect in detail which media were
|
---|
5042 | attached to the machine. Be careful when passing the media array to <link to="#delete" />
|
---|
5043 | in that case because users will typically want to preserve ISO and RAW image files.</li>
|
---|
5044 | </ul>
|
---|
5045 |
|
---|
5046 | This API does not verify whether the media files returned in the array are still
|
---|
5047 | attached to other machines (i.e. shared between several machines). If such a shared
|
---|
5048 | image is passed to <link to="#delete" /> however, closing the image will fail there
|
---|
5049 | and the image will be silently skipped.
|
---|
5050 |
|
---|
5051 | A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the
|
---|
5052 | resulting IMedia array to <link to="#delete"/>. This way, the machine is completely
|
---|
5053 | deleted with all its saved states and hard disk images, but images for removeable
|
---|
5054 | drives (such as ISO and RAW files) will remain on disk.
|
---|
5055 |
|
---|
5056 | The call will fail if the machine is currently locked (see <link to="ISession" />).
|
---|
5057 | It implicitly calls <link to="#saveSettings"/> to save all current machine settings
|
---|
5058 | before unregistering it.
|
---|
5059 |
|
---|
5060 | After successful method invocation, the <link to="IMachineRegisteredEvent"/> event
|
---|
5061 | is fired.
|
---|
5062 |
|
---|
5063 | <note>
|
---|
5064 | If the given machine is inaccessible (see <link to="#accessible"/>), it
|
---|
5065 | will be unregistered and fully uninitialized right afterwards. As a result,
|
---|
5066 | the returned machine object will be unusable and an attempt to call
|
---|
5067 | <b>any</b> method will return the "Object not ready" error.
|
---|
5068 | </note>
|
---|
5069 |
|
---|
5070 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5071 | Machine is currently locked for a session.
|
---|
5072 | </result>
|
---|
5073 | </desc>
|
---|
5074 |
|
---|
5075 | <param name="cleanupMode" type="CleanupMode" dir="in">
|
---|
5076 | <desc>How to clean up after the machine has been unregistered.</desc>
|
---|
5077 | </param>
|
---|
5078 | <param name="aMedia" type="IMedium" safearray="yes" dir="return">
|
---|
5079 | <desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc>
|
---|
5080 | </param>
|
---|
5081 | </method>
|
---|
5082 |
|
---|
5083 | <method name="delete">
|
---|
5084 | <desc>
|
---|
5085 | Deletes the files associated with this machine from disk. If medium objects are passed
|
---|
5086 | in with the @a aMedia argument, they are closed and, if closing was successful, their
|
---|
5087 | storage files are deleted as well. For convenience, this array of media files can be
|
---|
5088 | the same as the one returned from a previous <link to="#unregister" /> call.
|
---|
5089 |
|
---|
5090 | This method must only be called on machines which are either write-locked (i.e. on instances
|
---|
5091 | returned by <link to="ISession::machine"/>) or on unregistered machines (i.e. not yet
|
---|
5092 | registered machines created by <link to="IVirtualBox::createMachine"/> or opened by
|
---|
5093 | <link to="IVirtualBox::openMachine"/>, or after having called <link to="#unregister"/>).
|
---|
5094 |
|
---|
5095 | The following files will be deleted by this method:
|
---|
5096 | <ul>
|
---|
5097 | <li>If <link to="#unregister" /> had been previously called with a @a cleanupMode
|
---|
5098 | argument other than "UnregisterOnly", this will delete all saved state files that
|
---|
5099 | the machine had in use; possibly one if the machine was in "Saved" state and one
|
---|
5100 | for each online snapshot that the machine had.</li>
|
---|
5101 | <li>On each medium object passed in the @a aMedia array, this will call
|
---|
5102 | <link to="IMedium::close" />. If that succeeds, this will attempt to delete the
|
---|
5103 | medium's storage on disk. Since the close() call will fail if the medium is still
|
---|
5104 | in use, e.g. because it is still attached to a second machine; in that case the
|
---|
5105 | storage will not be deleted.</li>
|
---|
5106 | <li>Finally, the machine's own XML file will be deleted.</li>
|
---|
5107 | </ul>
|
---|
5108 |
|
---|
5109 | Since deleting large disk image files can be a time-consuming I/O operation, this
|
---|
5110 | method operates asynchronously and returns an IProgress object to allow the caller
|
---|
5111 | to monitor the progress. There will be one sub-operation for each file that is
|
---|
5112 | being deleted (saved state or medium storage file).
|
---|
5113 |
|
---|
5114 | <note>
|
---|
5115 | <link to="#settingsModified"/> will return @c true after this
|
---|
5116 | method successfully returns.
|
---|
5117 | </note>
|
---|
5118 |
|
---|
5119 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5120 | Machine is registered but not write-locked.
|
---|
5121 | </result>
|
---|
5122 | <result name="VBOX_E_IPRT_ERROR">
|
---|
5123 | Could not delete the settings file.
|
---|
5124 | </result>
|
---|
5125 | </desc>
|
---|
5126 | <param name="aMedia" type="IMedium" safearray="yes" dir="in">
|
---|
5127 | <desc>List of media to be closed and whose storage files will be deleted.</desc>
|
---|
5128 | </param>
|
---|
5129 | <param name="aProgress" type="IProgress" dir="return">
|
---|
5130 | <desc>Progress object to track the operation completion.</desc>
|
---|
5131 | </param>
|
---|
5132 | </method>
|
---|
5133 |
|
---|
5134 | <method name="export">
|
---|
5135 | <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
|
---|
5136 | steps required to export VirtualBox machines to OVF.
|
---|
5137 | </desc>
|
---|
5138 |
|
---|
5139 | <param name="aAppliance" type="IAppliance" dir="in">
|
---|
5140 | <desc>Appliance to export this machine to.</desc>
|
---|
5141 | </param>
|
---|
5142 | <param name="location" type="wstring" dir="in">
|
---|
5143 | <desc>The target location.</desc>
|
---|
5144 | </param>
|
---|
5145 | <param name="aDescription" type="IVirtualSystemDescription" dir="return">
|
---|
5146 | <desc>VirtualSystemDescription object which is created for this machine.</desc>
|
---|
5147 | </param>
|
---|
5148 | </method >
|
---|
5149 |
|
---|
5150 | <method name="findSnapshot">
|
---|
5151 | <desc>
|
---|
5152 | Returns a snapshot of this machine with the given name or UUID.
|
---|
5153 |
|
---|
5154 | Returns a snapshot of this machine with the given UUID.
|
---|
5155 | A @c null argument can be used to obtain the first snapshot
|
---|
5156 | taken on this machine. This is useful if you want to traverse
|
---|
5157 | the whole tree of snapshots starting from the root.
|
---|
5158 |
|
---|
5159 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5160 | Virtual machine has no snapshots or snapshot not found.
|
---|
5161 | </result>
|
---|
5162 |
|
---|
5163 | </desc>
|
---|
5164 | <param name="nameOrId" type="wstring" dir="in">
|
---|
5165 | <desc>What to search for. Name or UUID of the snapshot to find</desc>
|
---|
5166 | </param>
|
---|
5167 | <param name="snapshot" type="ISnapshot" dir="return">
|
---|
5168 | <desc>Snapshot object with the given name.</desc>
|
---|
5169 | </param>
|
---|
5170 | </method>
|
---|
5171 |
|
---|
5172 | <method name="createSharedFolder">
|
---|
5173 | <desc>
|
---|
5174 | Creates a new permanent shared folder by associating the given logical
|
---|
5175 | name with the given host path, adds it to the collection of shared
|
---|
5176 | folders and starts sharing it. Refer to the description of
|
---|
5177 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
5178 |
|
---|
5179 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
5180 | Shared folder already exists.
|
---|
5181 | </result>
|
---|
5182 | <result name="VBOX_E_FILE_ERROR">
|
---|
5183 | Shared folder @a hostPath not accessible.
|
---|
5184 | </result>
|
---|
5185 |
|
---|
5186 | </desc>
|
---|
5187 | <param name="name" type="wstring" dir="in">
|
---|
5188 | <desc>Unique logical name of the shared folder.</desc>
|
---|
5189 | </param>
|
---|
5190 | <param name="hostPath" type="wstring" dir="in">
|
---|
5191 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
5192 | </param>
|
---|
5193 | <param name="writable" type="boolean" dir="in">
|
---|
5194 | <desc>Whether the share is writable or readonly.</desc>
|
---|
5195 | </param>
|
---|
5196 | <param name="automount" type="boolean" dir="in">
|
---|
5197 | <desc>Whether the share gets automatically mounted by the guest
|
---|
5198 | or not.</desc>
|
---|
5199 | </param>
|
---|
5200 | </method>
|
---|
5201 |
|
---|
5202 | <method name="removeSharedFolder">
|
---|
5203 | <desc>
|
---|
5204 | Removes the permanent shared folder with the given name previously
|
---|
5205 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
5206 | shared folders and stops sharing it.
|
---|
5207 |
|
---|
5208 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5209 | Virtual machine is not mutable.
|
---|
5210 | </result>
|
---|
5211 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
5212 | Shared folder @a name does not exist.
|
---|
5213 | </result>
|
---|
5214 |
|
---|
5215 | </desc>
|
---|
5216 | <param name="name" type="wstring" dir="in">
|
---|
5217 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
5218 | </param>
|
---|
5219 | </method>
|
---|
5220 |
|
---|
5221 | <method name="canShowConsoleWindow">
|
---|
5222 | <desc>
|
---|
5223 | Returns @c true if the VM console process can activate the
|
---|
5224 | console window and bring it to foreground on the desktop of
|
---|
5225 | the host PC.
|
---|
5226 | <note>
|
---|
5227 | This method will fail if a session for this machine is not
|
---|
5228 | currently open.
|
---|
5229 | </note>
|
---|
5230 |
|
---|
5231 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5232 | Machine session is not open.
|
---|
5233 | </result>
|
---|
5234 |
|
---|
5235 | </desc>
|
---|
5236 | <param name="canShow" type="boolean" dir="return">
|
---|
5237 | <desc>
|
---|
5238 | @c true if the console window can be shown and @c false otherwise.
|
---|
5239 | </desc>
|
---|
5240 | </param>
|
---|
5241 | </method>
|
---|
5242 |
|
---|
5243 | <method name="showConsoleWindow">
|
---|
5244 | <desc>
|
---|
5245 | Activates the console window and brings it to foreground on
|
---|
5246 | the desktop of the host PC. Many modern window managers on
|
---|
5247 | many platforms implement some sort of focus stealing
|
---|
5248 | prevention logic, so that it may be impossible to activate
|
---|
5249 | a window without the help of the currently active
|
---|
5250 | application. In this case, this method will return a non-zero
|
---|
5251 | identifier that represents the top-level window of the VM
|
---|
5252 | console process. The caller, if it represents a currently
|
---|
5253 | active process, is responsible to use this identifier (in a
|
---|
5254 | platform-dependent manner) to perform actual window
|
---|
5255 | activation.
|
---|
5256 | <note>
|
---|
5257 | This method will fail if a session for this machine is not
|
---|
5258 | currently open.
|
---|
5259 | </note>
|
---|
5260 |
|
---|
5261 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5262 | Machine session is not open.
|
---|
5263 | </result>
|
---|
5264 |
|
---|
5265 | </desc>
|
---|
5266 | <param name="winId" type="long long" dir="return">
|
---|
5267 | <desc>
|
---|
5268 | Platform-dependent identifier of the top-level VM console
|
---|
5269 | window, or zero if this method has performed all actions
|
---|
5270 | necessary to implement the <i>show window</i> semantics for
|
---|
5271 | the given platform and/or VirtualBox front-end.
|
---|
5272 | </desc>
|
---|
5273 | </param>
|
---|
5274 | </method>
|
---|
5275 |
|
---|
5276 | <method name="getGuestProperty" const="yes">
|
---|
5277 | <desc>
|
---|
5278 | Reads an entry from the machine's guest property store.
|
---|
5279 |
|
---|
5280 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5281 | Machine session is not open.
|
---|
5282 | </result>
|
---|
5283 |
|
---|
5284 | </desc>
|
---|
5285 | <param name="name" type="wstring" dir="in">
|
---|
5286 | <desc>
|
---|
5287 | The name of the property to read.
|
---|
5288 | </desc>
|
---|
5289 | </param>
|
---|
5290 | <param name="value" type="wstring" dir="out">
|
---|
5291 | <desc>
|
---|
5292 | The value of the property. If the property does not exist then this
|
---|
5293 | will be empty.
|
---|
5294 | </desc>
|
---|
5295 | </param>
|
---|
5296 | <param name="timestamp" type="long long" dir="out">
|
---|
5297 | <desc>
|
---|
5298 | The time at which the property was last modified, as seen by the
|
---|
5299 | server process.
|
---|
5300 | </desc>
|
---|
5301 | </param>
|
---|
5302 | <param name="flags" type="wstring" dir="out">
|
---|
5303 | <desc>
|
---|
5304 | Additional property parameters, passed as a comma-separated list of
|
---|
5305 | "name=value" type entries.
|
---|
5306 | </desc>
|
---|
5307 | </param>
|
---|
5308 | </method>
|
---|
5309 |
|
---|
5310 | <method name="getGuestPropertyValue" const="yes">
|
---|
5311 | <desc>
|
---|
5312 | Reads a value from the machine's guest property store.
|
---|
5313 |
|
---|
5314 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5315 | Machine session is not open.
|
---|
5316 | </result>
|
---|
5317 |
|
---|
5318 | </desc>
|
---|
5319 | <param name="property" type="wstring" dir="in">
|
---|
5320 | <desc>
|
---|
5321 | The name of the property to read.
|
---|
5322 | </desc>
|
---|
5323 | </param>
|
---|
5324 | <param name="value" type="wstring" dir="return">
|
---|
5325 | <desc>
|
---|
5326 | The value of the property. If the property does not exist then this
|
---|
5327 | will be empty.
|
---|
5328 | </desc>
|
---|
5329 | </param>
|
---|
5330 | </method>
|
---|
5331 |
|
---|
5332 | <method name="getGuestPropertyTimestamp" const="yes">
|
---|
5333 | <desc>
|
---|
5334 | Reads a property timestamp from the machine's guest property store.
|
---|
5335 |
|
---|
5336 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5337 | Machine session is not open.
|
---|
5338 | </result>
|
---|
5339 |
|
---|
5340 | </desc>
|
---|
5341 | <param name="property" type="wstring" dir="in">
|
---|
5342 | <desc>
|
---|
5343 | The name of the property to read.
|
---|
5344 | </desc>
|
---|
5345 | </param>
|
---|
5346 | <param name="value" type="long long" dir="return">
|
---|
5347 | <desc>
|
---|
5348 | The timestamp. If the property does not exist then this will be
|
---|
5349 | empty.
|
---|
5350 | </desc>
|
---|
5351 | </param>
|
---|
5352 | </method>
|
---|
5353 |
|
---|
5354 | <method name="setGuestProperty">
|
---|
5355 | <desc>
|
---|
5356 | Sets, changes or deletes an entry in the machine's guest property
|
---|
5357 | store.
|
---|
5358 |
|
---|
5359 | <result name="E_ACCESSDENIED">
|
---|
5360 | Property cannot be changed.
|
---|
5361 | </result>
|
---|
5362 | <result name="E_INVALIDARG">
|
---|
5363 | Invalid @a flags.
|
---|
5364 | </result>
|
---|
5365 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5366 | Virtual machine is not mutable or session not open.
|
---|
5367 | </result>
|
---|
5368 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5369 | Cannot set transient property when machine not running.
|
---|
5370 | </result>
|
---|
5371 |
|
---|
5372 | </desc>
|
---|
5373 | <param name="property" type="wstring" dir="in">
|
---|
5374 | <desc>
|
---|
5375 | The name of the property to set, change or delete.
|
---|
5376 | </desc>
|
---|
5377 | </param>
|
---|
5378 | <param name="value" type="wstring" dir="in">
|
---|
5379 | <desc>
|
---|
5380 | The new value of the property to set, change or delete. If the
|
---|
5381 | property does not yet exist and value is non-empty, it will be
|
---|
5382 | created. If the value is @c null or empty, the property will be
|
---|
5383 | deleted if it exists.
|
---|
5384 | </desc>
|
---|
5385 | </param>
|
---|
5386 | <param name="flags" type="wstring" dir="in">
|
---|
5387 | <desc>
|
---|
5388 | Additional property parameters, passed as a comma-separated list of
|
---|
5389 | "name=value" type entries.
|
---|
5390 | </desc>
|
---|
5391 | </param>
|
---|
5392 | </method>
|
---|
5393 |
|
---|
5394 | <method name="setGuestPropertyValue">
|
---|
5395 | <desc>
|
---|
5396 | Sets, changes or deletes a value in the machine's guest property
|
---|
5397 | store. The flags field will be left unchanged or created empty for a
|
---|
5398 | new property.
|
---|
5399 |
|
---|
5400 | <result name="E_ACCESSDENIED">
|
---|
5401 | Property cannot be changed.
|
---|
5402 | </result>
|
---|
5403 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5404 | Virtual machine is not mutable or session not open.
|
---|
5405 | </result>
|
---|
5406 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
5407 | Cannot set transient property when machine not running.
|
---|
5408 | </result>
|
---|
5409 | </desc>
|
---|
5410 |
|
---|
5411 | <param name="property" type="wstring" dir="in">
|
---|
5412 | <desc>
|
---|
5413 | The name of the property to set, change or delete.
|
---|
5414 | </desc>
|
---|
5415 | </param>
|
---|
5416 | <param name="value" type="wstring" dir="in">
|
---|
5417 | <desc>
|
---|
5418 | The new value of the property to set, change or delete. If the
|
---|
5419 | property does not yet exist and value is non-empty, it will be
|
---|
5420 | created. If the value is @c null or empty, the property will be
|
---|
5421 | deleted if it exists.
|
---|
5422 | </desc>
|
---|
5423 | </param>
|
---|
5424 | </method>
|
---|
5425 |
|
---|
5426 | <method name="enumerateGuestProperties">
|
---|
5427 | <desc>
|
---|
5428 | Return a list of the guest properties matching a set of patterns along
|
---|
5429 | with their values, time stamps and flags.
|
---|
5430 | </desc>
|
---|
5431 | <param name="patterns" type="wstring" dir="in">
|
---|
5432 | <desc>
|
---|
5433 | The patterns to match the properties against, separated by '|'
|
---|
5434 | characters. If this is empty or @c null, all properties will match.
|
---|
5435 | </desc>
|
---|
5436 | </param>
|
---|
5437 | <param name="name" type="wstring" dir="out" safearray="yes">
|
---|
5438 | <desc>
|
---|
5439 | The names of the properties returned.
|
---|
5440 | </desc>
|
---|
5441 | </param>
|
---|
5442 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
5443 | <desc>
|
---|
5444 | The values of the properties returned. The array entries match the
|
---|
5445 | corresponding entries in the @a name array.
|
---|
5446 | </desc>
|
---|
5447 | </param>
|
---|
5448 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
5449 | <desc>
|
---|
5450 | The time stamps of the properties returned. The array entries match
|
---|
5451 | the corresponding entries in the @a name array.
|
---|
5452 | </desc>
|
---|
5453 | </param>
|
---|
5454 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
5455 | <desc>
|
---|
5456 | The flags of the properties returned. The array entries match the
|
---|
5457 | corresponding entries in the @a name array.
|
---|
5458 | </desc>
|
---|
5459 | </param>
|
---|
5460 | </method>
|
---|
5461 |
|
---|
5462 | <method name="querySavedGuestSize">
|
---|
5463 | <desc>
|
---|
5464 | Returns the guest dimensions from the saved state.
|
---|
5465 | </desc>
|
---|
5466 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5467 | <desc>
|
---|
5468 | Saved guest screen to query info from.
|
---|
5469 | </desc>
|
---|
5470 | </param>
|
---|
5471 | <param name="width" type="unsigned long" dir="out">
|
---|
5472 | <desc>
|
---|
5473 | Guest width at the time of the saved state was taken.
|
---|
5474 | </desc>
|
---|
5475 | </param>
|
---|
5476 | <param name="height" type="unsigned long" dir="out">
|
---|
5477 | <desc>
|
---|
5478 | Guest height at the time of the saved state was taken.
|
---|
5479 | </desc>
|
---|
5480 | </param>
|
---|
5481 | </method>
|
---|
5482 |
|
---|
5483 | <method name="querySavedThumbnailSize">
|
---|
5484 | <desc>
|
---|
5485 | Returns size in bytes and dimensions in pixels of a saved thumbnail bitmap from saved state.
|
---|
5486 | </desc>
|
---|
5487 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5488 | <desc>
|
---|
5489 | Saved guest screen to query info from.
|
---|
5490 | </desc>
|
---|
5491 | </param>
|
---|
5492 | <param name="size" type="unsigned long" dir="out">
|
---|
5493 | <desc>
|
---|
5494 | Size of buffer required to store the bitmap.
|
---|
5495 | </desc>
|
---|
5496 | </param>
|
---|
5497 | <param name="width" type="unsigned long" dir="out">
|
---|
5498 | <desc>
|
---|
5499 | Bitmap width.
|
---|
5500 | </desc>
|
---|
5501 | </param>
|
---|
5502 | <param name="height" type="unsigned long" dir="out">
|
---|
5503 | <desc>
|
---|
5504 | Bitmap height.
|
---|
5505 | </desc>
|
---|
5506 | </param>
|
---|
5507 | </method>
|
---|
5508 |
|
---|
5509 | <method name="readSavedThumbnailToArray">
|
---|
5510 | <desc>
|
---|
5511 | Thumbnail is retrieved to an array of bytes in uncompressed 32-bit BGRA or RGBA format.
|
---|
5512 | </desc>
|
---|
5513 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5514 | <desc>
|
---|
5515 | Saved guest screen to read from.
|
---|
5516 | </desc>
|
---|
5517 | </param>
|
---|
5518 | <param name="BGR" type="boolean" dir="in">
|
---|
5519 | <desc>
|
---|
5520 | How to order bytes in the pixel. A pixel consists of 4 bytes. If this parameter is true, then
|
---|
5521 | bytes order is: B, G, R, 0xFF. If this parameter is false, then bytes order is: R, G, B, 0xFF.
|
---|
5522 | </desc>
|
---|
5523 | </param>
|
---|
5524 | <param name="width" type="unsigned long" dir="out">
|
---|
5525 | <desc>
|
---|
5526 | Bitmap width.
|
---|
5527 | </desc>
|
---|
5528 | </param>
|
---|
5529 | <param name="height" type="unsigned long" dir="out">
|
---|
5530 | <desc>
|
---|
5531 | Bitmap height.
|
---|
5532 | </desc>
|
---|
5533 | </param>
|
---|
5534 | <param name="data" type="octet" safearray="yes" dir="return">
|
---|
5535 | <desc>
|
---|
5536 | Array with resulting bitmap data.
|
---|
5537 | </desc>
|
---|
5538 | </param>
|
---|
5539 | </method>
|
---|
5540 |
|
---|
5541 | <method name="readSavedThumbnailPNGToArray">
|
---|
5542 | <desc>
|
---|
5543 | Thumbnail in PNG format is retrieved to an array of bytes.
|
---|
5544 | </desc>
|
---|
5545 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5546 | <desc>
|
---|
5547 | Saved guest screen to read from.
|
---|
5548 | </desc>
|
---|
5549 | </param>
|
---|
5550 | <param name="width" type="unsigned long" dir="out">
|
---|
5551 | <desc>
|
---|
5552 | Image width.
|
---|
5553 | </desc>
|
---|
5554 | </param>
|
---|
5555 | <param name="height" type="unsigned long" dir="out">
|
---|
5556 | <desc>
|
---|
5557 | Image height.
|
---|
5558 | </desc>
|
---|
5559 | </param>
|
---|
5560 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5561 | <desc>
|
---|
5562 | Array with resulting PNG data.
|
---|
5563 | </desc>
|
---|
5564 | </param>
|
---|
5565 | </method>
|
---|
5566 |
|
---|
5567 | <method name="querySavedScreenshotPNGSize">
|
---|
5568 | <desc>
|
---|
5569 | Returns size in bytes and dimensions of a saved PNG image of screenshot from saved state.
|
---|
5570 | </desc>
|
---|
5571 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5572 | <desc>
|
---|
5573 | Saved guest screen to query info from.
|
---|
5574 | </desc>
|
---|
5575 | </param>
|
---|
5576 | <param name="size" type="unsigned long" dir="out">
|
---|
5577 | <desc>
|
---|
5578 | Size of buffer required to store the PNG binary data.
|
---|
5579 | </desc>
|
---|
5580 | </param>
|
---|
5581 | <param name="width" type="unsigned long" dir="out">
|
---|
5582 | <desc>
|
---|
5583 | Image width.
|
---|
5584 | </desc>
|
---|
5585 | </param>
|
---|
5586 | <param name="height" type="unsigned long" dir="out">
|
---|
5587 | <desc>
|
---|
5588 | Image height.
|
---|
5589 | </desc>
|
---|
5590 | </param>
|
---|
5591 | </method>
|
---|
5592 |
|
---|
5593 | <method name="readSavedScreenshotPNGToArray">
|
---|
5594 | <desc>
|
---|
5595 | Screenshot in PNG format is retrieved to an array of bytes.
|
---|
5596 | </desc>
|
---|
5597 | <param name="screenId" type="unsigned long" dir="in">
|
---|
5598 | <desc>
|
---|
5599 | Saved guest screen to read from.
|
---|
5600 | </desc>
|
---|
5601 | </param>
|
---|
5602 | <param name="width" type="unsigned long" dir="out">
|
---|
5603 | <desc>
|
---|
5604 | Image width.
|
---|
5605 | </desc>
|
---|
5606 | </param>
|
---|
5607 | <param name="height" type="unsigned long" dir="out">
|
---|
5608 | <desc>
|
---|
5609 | Image height.
|
---|
5610 | </desc>
|
---|
5611 | </param>
|
---|
5612 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5613 | <desc>
|
---|
5614 | Array with resulting PNG data.
|
---|
5615 | </desc>
|
---|
5616 | </param>
|
---|
5617 | </method>
|
---|
5618 |
|
---|
5619 | <method name="hotPlugCPU">
|
---|
5620 | <desc>
|
---|
5621 | Plugs a CPU into the machine.
|
---|
5622 | </desc>
|
---|
5623 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5624 | <desc>
|
---|
5625 | The CPU id to insert.
|
---|
5626 | </desc>
|
---|
5627 | </param>
|
---|
5628 | </method>
|
---|
5629 |
|
---|
5630 | <method name="hotUnplugCPU">
|
---|
5631 | <desc>
|
---|
5632 | Removes a CPU from the machine.
|
---|
5633 | </desc>
|
---|
5634 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5635 | <desc>
|
---|
5636 | The CPU id to remove.
|
---|
5637 | </desc>
|
---|
5638 | </param>
|
---|
5639 | </method>
|
---|
5640 |
|
---|
5641 | <method name="getCPUStatus">
|
---|
5642 | <desc>
|
---|
5643 | Returns the current status of the given CPU.
|
---|
5644 | </desc>
|
---|
5645 | <param name="cpu" type="unsigned long" dir="in">
|
---|
5646 | <desc>
|
---|
5647 | The CPU id to check for.
|
---|
5648 | </desc>
|
---|
5649 | </param>
|
---|
5650 | <param name="attached" type="boolean" dir="return">
|
---|
5651 | <desc>
|
---|
5652 | Status of the CPU.
|
---|
5653 | </desc>
|
---|
5654 | </param>
|
---|
5655 | </method>
|
---|
5656 |
|
---|
5657 | <method name="queryLogFilename">
|
---|
5658 | <desc>
|
---|
5659 | Queries for the VM log file name of an given index. Returns an empty
|
---|
5660 | string if a log file with that index doesn't exists.
|
---|
5661 | </desc>
|
---|
5662 | <param name="idx" type="unsigned long" dir="in">
|
---|
5663 | <desc>
|
---|
5664 | Which log file name to query. 0=current log file.
|
---|
5665 | </desc>
|
---|
5666 | </param>
|
---|
5667 | <param name="filename" type="wstring" dir="return">
|
---|
5668 | <desc>
|
---|
5669 | On return the full path to the log file or an empty string on error.
|
---|
5670 | </desc>
|
---|
5671 | </param>
|
---|
5672 | </method>
|
---|
5673 |
|
---|
5674 | <method name="readLog">
|
---|
5675 | <desc>
|
---|
5676 | Reads the VM log file. The chunk size is limited, so even if you
|
---|
5677 | ask for a big piece there might be less data returned.
|
---|
5678 | </desc>
|
---|
5679 | <param name="idx" type="unsigned long" dir="in">
|
---|
5680 | <desc>
|
---|
5681 | Which log file to read. 0=current log file.
|
---|
5682 | </desc>
|
---|
5683 | </param>
|
---|
5684 | <param name="offset" type="long long" dir="in">
|
---|
5685 | <desc>
|
---|
5686 | Offset in the log file.
|
---|
5687 | </desc>
|
---|
5688 | </param>
|
---|
5689 | <param name="size" type="long long" dir="in">
|
---|
5690 | <desc>
|
---|
5691 | Chunk size to read in the log file.
|
---|
5692 | </desc>
|
---|
5693 | </param>
|
---|
5694 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
5695 | <desc>
|
---|
5696 | Data read from the log file. A data size of 0 means end of file
|
---|
5697 | if the requested chunk size was not 0. This is the unprocessed
|
---|
5698 | file data, i.e. the line ending style depends on the platform of
|
---|
5699 | the system the server is running on.
|
---|
5700 | </desc>
|
---|
5701 | </param>
|
---|
5702 | </method>
|
---|
5703 | </interface>
|
---|
5704 |
|
---|
5705 | <!--
|
---|
5706 | // IConsole
|
---|
5707 | /////////////////////////////////////////////////////////////////////////
|
---|
5708 | -->
|
---|
5709 |
|
---|
5710 | <interface
|
---|
5711 | name="IVRDEServerInfo" extends="$unknown"
|
---|
5712 | uuid="714434a1-58c3-4aab-9049-7652c5df113b"
|
---|
5713 | wsmap="struct"
|
---|
5714 | >
|
---|
5715 | <desc>
|
---|
5716 | Contains information about the remote desktop (VRDE) server capabilities and status.
|
---|
5717 | This is used in the <link to="IConsole::VRDEServerInfo" /> attribute.
|
---|
5718 | </desc>
|
---|
5719 |
|
---|
5720 | <attribute name="active" type="boolean" readonly="yes">
|
---|
5721 | <desc>
|
---|
5722 | Whether the remote desktop connection is active.
|
---|
5723 | </desc>
|
---|
5724 | </attribute>
|
---|
5725 |
|
---|
5726 | <attribute name="port" type="long" readonly="yes">
|
---|
5727 | <desc>
|
---|
5728 | VRDE server port number. If this property is equal to <tt>0</tt>, then
|
---|
5729 | the VRDE server failed to start, usually because there are no free IP
|
---|
5730 | ports to bind to. If this property is equal to <tt>-1</tt>, then the VRDE
|
---|
5731 | server has not yet been started.
|
---|
5732 | </desc>
|
---|
5733 | </attribute>
|
---|
5734 |
|
---|
5735 | <attribute name="numberOfClients" type="unsigned long" readonly="yes">
|
---|
5736 | <desc>
|
---|
5737 | How many times a client connected.
|
---|
5738 | </desc>
|
---|
5739 | </attribute>
|
---|
5740 |
|
---|
5741 | <attribute name="beginTime" type="long long" readonly="yes">
|
---|
5742 | <desc>
|
---|
5743 | When the last connection was established, in milliseconds since 1970-01-01 UTC.
|
---|
5744 | </desc>
|
---|
5745 | </attribute>
|
---|
5746 |
|
---|
5747 | <attribute name="endTime" type="long long" readonly="yes">
|
---|
5748 | <desc>
|
---|
5749 | When the last connection was terminated or the current time, if
|
---|
5750 | connection is still active, in milliseconds since 1970-01-01 UTC.
|
---|
5751 | </desc>
|
---|
5752 | </attribute>
|
---|
5753 |
|
---|
5754 | <attribute name="bytesSent" type="long long" readonly="yes">
|
---|
5755 | <desc>
|
---|
5756 | How many bytes were sent in last or current, if still active, connection.
|
---|
5757 | </desc>
|
---|
5758 | </attribute>
|
---|
5759 |
|
---|
5760 | <attribute name="bytesSentTotal" type="long long" readonly="yes">
|
---|
5761 | <desc>
|
---|
5762 | How many bytes were sent in all connections.
|
---|
5763 | </desc>
|
---|
5764 | </attribute>
|
---|
5765 |
|
---|
5766 | <attribute name="bytesReceived" type="long long" readonly="yes">
|
---|
5767 | <desc>
|
---|
5768 | How many bytes were received in last or current, if still active, connection.
|
---|
5769 | </desc>
|
---|
5770 | </attribute>
|
---|
5771 |
|
---|
5772 | <attribute name="bytesReceivedTotal" type="long long" readonly="yes">
|
---|
5773 | <desc>
|
---|
5774 | How many bytes were received in all connections.
|
---|
5775 | </desc>
|
---|
5776 | </attribute>
|
---|
5777 |
|
---|
5778 | <attribute name="user" type="wstring" readonly="yes">
|
---|
5779 | <desc>
|
---|
5780 | Login user name supplied by the client.
|
---|
5781 | </desc>
|
---|
5782 | </attribute>
|
---|
5783 |
|
---|
5784 | <attribute name="domain" type="wstring" readonly="yes">
|
---|
5785 | <desc>
|
---|
5786 | Login domain name supplied by the client.
|
---|
5787 | </desc>
|
---|
5788 | </attribute>
|
---|
5789 |
|
---|
5790 | <attribute name="clientName" type="wstring" readonly="yes">
|
---|
5791 | <desc>
|
---|
5792 | The client name supplied by the client.
|
---|
5793 | </desc>
|
---|
5794 | </attribute>
|
---|
5795 |
|
---|
5796 | <attribute name="clientIP" type="wstring" readonly="yes">
|
---|
5797 | <desc>
|
---|
5798 | The IP address of the client.
|
---|
5799 | </desc>
|
---|
5800 | </attribute>
|
---|
5801 |
|
---|
5802 | <attribute name="clientVersion" type="unsigned long" readonly="yes">
|
---|
5803 | <desc>
|
---|
5804 | The client software version number.
|
---|
5805 | </desc>
|
---|
5806 | </attribute>
|
---|
5807 |
|
---|
5808 | <attribute name="encryptionStyle" type="unsigned long" readonly="yes">
|
---|
5809 | <desc>
|
---|
5810 | Public key exchange method used when connection was established.
|
---|
5811 | Values: 0 - RDP4 public key exchange scheme.
|
---|
5812 | 1 - X509 certificates were sent to client.
|
---|
5813 | </desc>
|
---|
5814 | </attribute>
|
---|
5815 |
|
---|
5816 | </interface>
|
---|
5817 |
|
---|
5818 | <interface
|
---|
5819 | name="IConsole" extends="$unknown"
|
---|
5820 | uuid="3c4a453e-d27b-44a2-b59d-dda6e1835e57"
|
---|
5821 | wsmap="managed"
|
---|
5822 | >
|
---|
5823 | <desc>
|
---|
5824 | The IConsole interface represents an interface to control virtual
|
---|
5825 | machine execution.
|
---|
5826 |
|
---|
5827 | A console object gets created when a machine has been locked for a
|
---|
5828 | particular session (client process) using <link to="IMachine::lockMachine" />
|
---|
5829 | or <link to="IMachine::launchVMProcess"/>. The console object can
|
---|
5830 | then be found in the session's <link to="ISession::console" /> attribute.
|
---|
5831 |
|
---|
5832 | Methods of the IConsole interface allow the caller to query the current
|
---|
5833 | virtual machine execution state, pause the machine or power it down, save
|
---|
5834 | the machine state or take a snapshot, attach and detach removable media
|
---|
5835 | and so on.
|
---|
5836 |
|
---|
5837 | <see>ISession</see>
|
---|
5838 | </desc>
|
---|
5839 |
|
---|
5840 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
5841 | <desc>
|
---|
5842 | Machine object for this console session.
|
---|
5843 | <note>
|
---|
5844 | This is a convenience property, it has the same value as
|
---|
5845 | <link to="ISession::machine"/> of the corresponding session
|
---|
5846 | object.
|
---|
5847 | </note>
|
---|
5848 | </desc>
|
---|
5849 | </attribute>
|
---|
5850 |
|
---|
5851 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
5852 | <desc>
|
---|
5853 | Current execution state of the machine.
|
---|
5854 | <note>
|
---|
5855 | This property always returns the same value as the corresponding
|
---|
5856 | property of the IMachine object for this console session.
|
---|
5857 | For the process that owns (executes) the VM, this is the
|
---|
5858 | preferable way of querying the VM state, because no IPC
|
---|
5859 | calls are made.
|
---|
5860 | </note>
|
---|
5861 | </desc>
|
---|
5862 | </attribute>
|
---|
5863 |
|
---|
5864 | <attribute name="guest" type="IGuest" readonly="yes">
|
---|
5865 | <desc>Guest object.</desc>
|
---|
5866 | </attribute>
|
---|
5867 |
|
---|
5868 | <attribute name="keyboard" type="IKeyboard" readonly="yes">
|
---|
5869 | <desc>
|
---|
5870 | Virtual keyboard object.
|
---|
5871 | <note>
|
---|
5872 | If the machine is not running, any attempt to use
|
---|
5873 | the returned object will result in an error.
|
---|
5874 | </note>
|
---|
5875 | </desc>
|
---|
5876 | </attribute>
|
---|
5877 |
|
---|
5878 | <attribute name="mouse" type="IMouse" readonly="yes">
|
---|
5879 | <desc>
|
---|
5880 | Virtual mouse object.
|
---|
5881 | <note>
|
---|
5882 | If the machine is not running, any attempt to use
|
---|
5883 | the returned object will result in an error.
|
---|
5884 | </note>
|
---|
5885 | </desc>
|
---|
5886 | </attribute>
|
---|
5887 |
|
---|
5888 | <attribute name="display" type="IDisplay" readonly="yes">
|
---|
5889 | <desc>Virtual display object.
|
---|
5890 | <note>
|
---|
5891 | If the machine is not running, any attempt to use
|
---|
5892 | the returned object will result in an error.
|
---|
5893 | </note>
|
---|
5894 | </desc>
|
---|
5895 | </attribute>
|
---|
5896 |
|
---|
5897 | <attribute name="debugger" type="IMachineDebugger" readonly="yes">
|
---|
5898 | <desc>Debugging interface.</desc>
|
---|
5899 | </attribute>
|
---|
5900 |
|
---|
5901 | <attribute name="USBDevices" type="IUSBDevice" readonly="yes" safearray="yes">
|
---|
5902 | <desc>
|
---|
5903 | Collection of USB devices currently attached to the virtual
|
---|
5904 | USB controller.
|
---|
5905 | <note>
|
---|
5906 | The collection is empty if the machine is not running.
|
---|
5907 | </note>
|
---|
5908 | </desc>
|
---|
5909 | </attribute>
|
---|
5910 |
|
---|
5911 | <attribute name="remoteUSBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
5912 | <desc>
|
---|
5913 | List of USB devices currently attached to the remote VRDE client.
|
---|
5914 | Once a new device is physically attached to the remote host computer,
|
---|
5915 | it appears in this list and remains there until detached.
|
---|
5916 | </desc>
|
---|
5917 | </attribute>
|
---|
5918 |
|
---|
5919 | <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes">
|
---|
5920 | <desc>
|
---|
5921 | Collection of shared folders for the current session. These folders
|
---|
5922 | are called transient shared folders because they are available to the
|
---|
5923 | guest OS running inside the associated virtual machine only for the
|
---|
5924 | duration of the session (as opposed to
|
---|
5925 | <link to="IMachine::sharedFolders"/> which represent permanent shared
|
---|
5926 | folders). When the session is closed (e.g. the machine is powered down),
|
---|
5927 | these folders are automatically discarded.
|
---|
5928 |
|
---|
5929 | New shared folders are added to the collection using
|
---|
5930 | <link to="#createSharedFolder"/>. Existing shared folders can be
|
---|
5931 | removed using <link to="#removeSharedFolder"/>.
|
---|
5932 | </desc>
|
---|
5933 | </attribute>
|
---|
5934 |
|
---|
5935 | <attribute name="VRDEServerInfo" type="IVRDEServerInfo" readonly="yes">
|
---|
5936 | <desc>
|
---|
5937 | Interface that provides information on Remote Desktop Extension (VRDE) connection.
|
---|
5938 | </desc>
|
---|
5939 | </attribute>
|
---|
5940 |
|
---|
5941 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
5942 | <desc>
|
---|
5943 | Event source for console events.
|
---|
5944 | </desc>
|
---|
5945 | </attribute>
|
---|
5946 |
|
---|
5947 | <method name="powerUp">
|
---|
5948 | <desc>
|
---|
5949 | Starts the virtual machine execution using the current machine
|
---|
5950 | state (that is, its current execution state, current settings and
|
---|
5951 | current storage devices).
|
---|
5952 |
|
---|
5953 | <note>
|
---|
5954 | This method is only useful for front-ends that want to actually
|
---|
5955 | execute virtual machines in their own process (like the VirtualBox
|
---|
5956 | or VBoxSDL front-ends). Unless you are intending to write such a
|
---|
5957 | front-end, do not call this method. If you simply want to
|
---|
5958 | start virtual machine execution using one of the existing front-ends
|
---|
5959 | (for example the VirtualBox GUI or headless server), use
|
---|
5960 | <link to="IMachine::launchVMProcess"/> instead; these
|
---|
5961 | front-ends will power up the machine automatically for you.
|
---|
5962 | </note>
|
---|
5963 |
|
---|
5964 | If the machine is powered off or aborted, the execution will
|
---|
5965 | start from the beginning (as if the real hardware were just
|
---|
5966 | powered on).
|
---|
5967 |
|
---|
5968 | If the machine is in the <link to="MachineState_Saved"/> state,
|
---|
5969 | it will continue its execution the point where the state has
|
---|
5970 | been saved.
|
---|
5971 |
|
---|
5972 | If the machine <link to="IMachine::teleporterEnabled"/> property is
|
---|
5973 | enabled on the machine being powered up, the machine will wait for an
|
---|
5974 | incoming teleportation in the <link to="MachineState_TeleportingIn"/>
|
---|
5975 | state. The returned progress object will have at least three
|
---|
5976 | operations where the last three are defined as: (1) powering up and
|
---|
5977 | starting TCP server, (2) waiting for incoming teleportations, and
|
---|
5978 | (3) perform teleportation. These operations will be reflected as the
|
---|
5979 | last three operations of the progress objected returned by
|
---|
5980 | <link to="IMachine::launchVMProcess"/> as well.
|
---|
5981 |
|
---|
5982 | <see>#saveState</see>
|
---|
5983 |
|
---|
5984 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
5985 | Virtual machine already running.
|
---|
5986 | </result>
|
---|
5987 | <result name="VBOX_E_HOST_ERROR">
|
---|
5988 | Host interface does not exist or name not set.
|
---|
5989 | </result>
|
---|
5990 | <result name="VBOX_E_FILE_ERROR">
|
---|
5991 | Invalid saved state file.
|
---|
5992 | </result>
|
---|
5993 | </desc>
|
---|
5994 | <param name="progress" type="IProgress" dir="return">
|
---|
5995 | <desc>Progress object to track the operation completion.</desc>
|
---|
5996 | </param>
|
---|
5997 | </method>
|
---|
5998 |
|
---|
5999 | <method name="powerUpPaused">
|
---|
6000 | <desc>
|
---|
6001 | Identical to powerUp except that the VM will enter the
|
---|
6002 | <link to="MachineState_Paused"/> state, instead of
|
---|
6003 | <link to="MachineState_Running"/>.
|
---|
6004 |
|
---|
6005 | <see>#powerUp</see>
|
---|
6006 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6007 | Virtual machine already running.
|
---|
6008 | </result>
|
---|
6009 | <result name="VBOX_E_HOST_ERROR">
|
---|
6010 | Host interface does not exist or name not set.
|
---|
6011 | </result>
|
---|
6012 | <result name="VBOX_E_FILE_ERROR">
|
---|
6013 | Invalid saved state file.
|
---|
6014 | </result>
|
---|
6015 | </desc>
|
---|
6016 | <param name="progress" type="IProgress" dir="return">
|
---|
6017 | <desc>Progress object to track the operation completion.</desc>
|
---|
6018 | </param>
|
---|
6019 | </method>
|
---|
6020 |
|
---|
6021 | <method name="powerDown">
|
---|
6022 | <desc>
|
---|
6023 | Initiates the power down procedure to stop the virtual machine
|
---|
6024 | execution.
|
---|
6025 |
|
---|
6026 | The completion of the power down procedure is tracked using the returned
|
---|
6027 | IProgress object. After the operation is complete, the machine will go
|
---|
6028 | to the PoweredOff state.
|
---|
6029 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6030 | Virtual machine must be Running, Paused or Stuck to be powered down.
|
---|
6031 | </result>
|
---|
6032 | </desc>
|
---|
6033 | <param name="progress" type="IProgress" dir="return">
|
---|
6034 | <desc>Progress object to track the operation completion.</desc>
|
---|
6035 | </param>
|
---|
6036 | </method>
|
---|
6037 |
|
---|
6038 | <method name="reset">
|
---|
6039 | <desc>Resets the virtual machine.
|
---|
6040 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6041 | Virtual machine not in Running state.
|
---|
6042 | </result>
|
---|
6043 | <result name="VBOX_E_VM_ERROR">
|
---|
6044 | Virtual machine error in reset operation.
|
---|
6045 | </result>
|
---|
6046 | </desc>
|
---|
6047 | </method>
|
---|
6048 |
|
---|
6049 | <method name="pause">
|
---|
6050 | <desc>Pauses the virtual machine execution.
|
---|
6051 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6052 | Virtual machine not in Running state.
|
---|
6053 | </result>
|
---|
6054 | <result name="VBOX_E_VM_ERROR">
|
---|
6055 | Virtual machine error in suspend operation.
|
---|
6056 | </result>
|
---|
6057 | </desc>
|
---|
6058 | </method>
|
---|
6059 |
|
---|
6060 | <method name="resume">
|
---|
6061 | <desc>Resumes the virtual machine execution.
|
---|
6062 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6063 | Virtual machine not in Paused state.
|
---|
6064 | </result>
|
---|
6065 | <result name="VBOX_E_VM_ERROR">
|
---|
6066 | Virtual machine error in resume operation.
|
---|
6067 | </result>
|
---|
6068 | </desc>
|
---|
6069 | </method>
|
---|
6070 |
|
---|
6071 | <method name="powerButton">
|
---|
6072 | <desc>Sends the ACPI power button event to the guest.
|
---|
6073 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6074 | Virtual machine not in Running state.
|
---|
6075 | </result>
|
---|
6076 | <result name="VBOX_E_PDM_ERROR">
|
---|
6077 | Controlled power off failed.
|
---|
6078 | </result>
|
---|
6079 | </desc>
|
---|
6080 | </method>
|
---|
6081 |
|
---|
6082 | <method name="sleepButton">
|
---|
6083 | <desc>Sends the ACPI sleep button event to the guest.
|
---|
6084 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6085 | Virtual machine not in Running state.
|
---|
6086 | </result>
|
---|
6087 | <result name="VBOX_E_PDM_ERROR">
|
---|
6088 | Sending sleep button event failed.
|
---|
6089 | </result>
|
---|
6090 | </desc>
|
---|
6091 | </method>
|
---|
6092 |
|
---|
6093 | <method name="getPowerButtonHandled">
|
---|
6094 | <desc>Checks if the last power button event was handled by guest.
|
---|
6095 | <result name="VBOX_E_PDM_ERROR">
|
---|
6096 | Checking if the event was handled by the guest OS failed.
|
---|
6097 | </result>
|
---|
6098 | </desc>
|
---|
6099 | <param name="handled" type="boolean" dir="return"/>
|
---|
6100 | </method>
|
---|
6101 |
|
---|
6102 | <method name="getGuestEnteredACPIMode">
|
---|
6103 | <desc>Checks if the guest entered the ACPI mode G0 (working) or
|
---|
6104 | G1 (sleeping). If this method returns @c false, the guest will
|
---|
6105 | most likely not respond to external ACPI events.
|
---|
6106 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6107 | Virtual machine not in Running state.
|
---|
6108 | </result>
|
---|
6109 | </desc>
|
---|
6110 | <param name="entered" type="boolean" dir="return"/>
|
---|
6111 | </method>
|
---|
6112 |
|
---|
6113 | <method name="saveState">
|
---|
6114 | <desc>
|
---|
6115 | Saves the current execution state of a running virtual machine
|
---|
6116 | and stops its execution.
|
---|
6117 |
|
---|
6118 | After this operation completes, the machine will go to the
|
---|
6119 | Saved state. Next time it is powered up, this state will
|
---|
6120 | be restored and the machine will continue its execution from
|
---|
6121 | the place where it was saved.
|
---|
6122 |
|
---|
6123 | This operation differs from taking a snapshot to the effect
|
---|
6124 | that it doesn't create new differencing media. Also, once
|
---|
6125 | the machine is powered up from the state saved using this method,
|
---|
6126 | the saved state is deleted, so it will be impossible to return
|
---|
6127 | to this state later.
|
---|
6128 |
|
---|
6129 | <note>
|
---|
6130 | On success, this method implicitly calls
|
---|
6131 | <link to="IMachine::saveSettings"/> to save all current machine
|
---|
6132 | settings (including runtime changes to the DVD medium, etc.).
|
---|
6133 | Together with the impossibility to change any VM settings when it is
|
---|
6134 | in the Saved state, this guarantees adequate hardware
|
---|
6135 | configuration of the machine when it is restored from the saved
|
---|
6136 | state file.
|
---|
6137 | </note>
|
---|
6138 |
|
---|
6139 | <note>
|
---|
6140 | The machine must be in the Running or Paused state, otherwise
|
---|
6141 | the operation will fail.
|
---|
6142 | </note>
|
---|
6143 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6144 | Virtual machine state neither Running nor Paused.
|
---|
6145 | </result>
|
---|
6146 | <result name="VBOX_E_FILE_ERROR">
|
---|
6147 | Failed to create directory for saved state file.
|
---|
6148 | </result>
|
---|
6149 |
|
---|
6150 | <see><link to="#takeSnapshot"/></see>
|
---|
6151 | </desc>
|
---|
6152 | <param name="progress" type="IProgress" dir="return">
|
---|
6153 | <desc>Progress object to track the operation completion.</desc>
|
---|
6154 | </param>
|
---|
6155 | </method>
|
---|
6156 |
|
---|
6157 | <method name="adoptSavedState">
|
---|
6158 | <desc>
|
---|
6159 | Associates the given saved state file to the virtual machine.
|
---|
6160 |
|
---|
6161 | On success, the machine will go to the Saved state. Next time it is
|
---|
6162 | powered up, it will be restored from the adopted saved state and
|
---|
6163 | continue execution from the place where the saved state file was
|
---|
6164 | created.
|
---|
6165 |
|
---|
6166 | The specified saved state file path may be absolute or relative to the
|
---|
6167 | folder the VM normally saves the state to (usually,
|
---|
6168 | <link to="IMachine::snapshotFolder"/>).
|
---|
6169 |
|
---|
6170 | <note>
|
---|
6171 | It's a caller's responsibility to make sure the given saved state
|
---|
6172 | file is compatible with the settings of this virtual machine that
|
---|
6173 | represent its virtual hardware (memory size, storage disk configuration
|
---|
6174 | etc.). If there is a mismatch, the behavior of the virtual machine
|
---|
6175 | is undefined.
|
---|
6176 | </note>
|
---|
6177 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6178 | Virtual machine state neither PoweredOff nor Aborted.
|
---|
6179 | </result>
|
---|
6180 | </desc>
|
---|
6181 | <param name="savedStateFile" type="wstring" dir="in">
|
---|
6182 | <desc>Path to the saved state file to adopt.</desc>
|
---|
6183 | </param>
|
---|
6184 | </method>
|
---|
6185 |
|
---|
6186 | <method name="discardSavedState">
|
---|
6187 | <desc>
|
---|
6188 | Forcibly resets the machine to "Powered Off" state if it is
|
---|
6189 | currently in the "Saved" state (previously created by <link to="#saveState"/>).
|
---|
6190 | Next time the machine is powered up, a clean boot will occur.
|
---|
6191 | <note>
|
---|
6192 | This operation is equivalent to resetting or powering off
|
---|
6193 | the machine without doing a proper shutdown of the guest
|
---|
6194 | operating system; as with resetting a running phyiscal
|
---|
6195 | computer, it can can lead to data loss.
|
---|
6196 | </note>
|
---|
6197 | If @a fRemoveFile is @c true, the file in the machine directory
|
---|
6198 | into which the machine state was saved is also deleted. If
|
---|
6199 | this is @c false, then the state can be recovered and later
|
---|
6200 | re-inserted into a machine using <link to="#adoptSavedState" />.
|
---|
6201 | The location of the file can be found in the
|
---|
6202 | <link to="IMachine::stateFilePath" /> attribute.
|
---|
6203 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6204 | Virtual machine not in state Saved.
|
---|
6205 | </result>
|
---|
6206 | </desc>
|
---|
6207 | <param name="fRemoveFile" type="boolean" dir="in" >
|
---|
6208 | <desc>Whether to also remove the saved state file.</desc>
|
---|
6209 | </param>
|
---|
6210 | </method>
|
---|
6211 |
|
---|
6212 | <method name="getDeviceActivity">
|
---|
6213 | <desc>
|
---|
6214 | Gets the current activity type of a given device or device group.
|
---|
6215 | <result name="E_INVALIDARG">
|
---|
6216 | Invalid device type.
|
---|
6217 | </result>
|
---|
6218 | </desc>
|
---|
6219 | <param name="type" type="DeviceType" dir="in"/>
|
---|
6220 | <param name="activity" type="DeviceActivity" dir="return"/>
|
---|
6221 | </method>
|
---|
6222 |
|
---|
6223 | <method name="attachUSBDevice">
|
---|
6224 | <desc>
|
---|
6225 | Attaches a host USB device with the given UUID to the
|
---|
6226 | USB controller of the virtual machine.
|
---|
6227 |
|
---|
6228 | The device needs to be in one of the following states:
|
---|
6229 | <link to="USBDeviceState_Busy"/>,
|
---|
6230 | <link to="USBDeviceState_Available"/> or
|
---|
6231 | <link to="USBDeviceState_Held"/>,
|
---|
6232 | otherwise an error is immediately returned.
|
---|
6233 |
|
---|
6234 | When the device state is
|
---|
6235 | <link to="USBDeviceState_Busy">Busy</link>, an error may also
|
---|
6236 | be returned if the host computer refuses to release it for some reason.
|
---|
6237 |
|
---|
6238 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6239 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6240 | Virtual machine state neither Running nor Paused.
|
---|
6241 | </result>
|
---|
6242 | <result name="VBOX_E_PDM_ERROR">
|
---|
6243 | Virtual machine does not have a USB controller.
|
---|
6244 | </result>
|
---|
6245 | </desc>
|
---|
6246 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6247 | <desc>UUID of the host USB device to attach.</desc>
|
---|
6248 | </param>
|
---|
6249 | </method>
|
---|
6250 |
|
---|
6251 | <method name="detachUSBDevice">
|
---|
6252 | <desc>
|
---|
6253 | Detaches an USB device with the given UUID from the USB controller
|
---|
6254 | of the virtual machine.
|
---|
6255 |
|
---|
6256 | After this method succeeds, the VirtualBox server re-initiates
|
---|
6257 | all USB filters as if the device were just physically attached
|
---|
6258 | to the host, but filters of this machine are ignored to avoid
|
---|
6259 | a possible automatic re-attachment.
|
---|
6260 |
|
---|
6261 | <see>IUSBController::deviceFilters, USBDeviceState</see>
|
---|
6262 |
|
---|
6263 | <result name="VBOX_E_PDM_ERROR">
|
---|
6264 | Virtual machine does not have a USB controller.
|
---|
6265 | </result>
|
---|
6266 | <result name="E_INVALIDARG">
|
---|
6267 | USB device not attached to this virtual machine.
|
---|
6268 | </result>
|
---|
6269 | </desc>
|
---|
6270 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6271 | <desc>UUID of the USB device to detach.</desc>
|
---|
6272 | </param>
|
---|
6273 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6274 | <desc>Detached USB device.</desc>
|
---|
6275 | </param>
|
---|
6276 | </method>
|
---|
6277 |
|
---|
6278 | <method name="findUSBDeviceByAddress">
|
---|
6279 | <desc>
|
---|
6280 | Searches for a USB device with the given host address.
|
---|
6281 |
|
---|
6282 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6283 | Given @c name does not correspond to any USB device.
|
---|
6284 | </result>
|
---|
6285 |
|
---|
6286 | <see>IUSBDevice::address</see>
|
---|
6287 | </desc>
|
---|
6288 | <param name="name" type="wstring" dir="in">
|
---|
6289 | <desc>
|
---|
6290 | Address of the USB device (as assigned by the host) to
|
---|
6291 | search for.
|
---|
6292 | </desc>
|
---|
6293 | </param>
|
---|
6294 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6295 | <desc>Found USB device object.</desc>
|
---|
6296 | </param>
|
---|
6297 | </method>
|
---|
6298 |
|
---|
6299 | <method name="findUSBDeviceById">
|
---|
6300 | <desc>
|
---|
6301 | Searches for a USB device with the given UUID.
|
---|
6302 |
|
---|
6303 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6304 | Given @c id does not correspond to any USB device.
|
---|
6305 | </result>
|
---|
6306 |
|
---|
6307 | <see>IUSBDevice::id</see>
|
---|
6308 | </desc>
|
---|
6309 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6310 | <desc>UUID of the USB device to search for.</desc>
|
---|
6311 | </param>
|
---|
6312 | <param name="device" type="IUSBDevice" dir="return">
|
---|
6313 | <desc>Found USB device object.</desc>
|
---|
6314 | </param>
|
---|
6315 | </method>
|
---|
6316 |
|
---|
6317 | <method name="createSharedFolder">
|
---|
6318 | <desc>
|
---|
6319 | Creates a transient new shared folder by associating the given logical
|
---|
6320 | name with the given host path, adds it to the collection of shared
|
---|
6321 | folders and starts sharing it. Refer to the description of
|
---|
6322 | <link to="ISharedFolder"/> to read more about logical names.
|
---|
6323 |
|
---|
6324 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6325 | Virtual machine in Saved state or currently changing state.
|
---|
6326 | </result>
|
---|
6327 | <result name="VBOX_E_FILE_ERROR">
|
---|
6328 | Shared folder already exists or not accessible.
|
---|
6329 | </result>
|
---|
6330 | </desc>
|
---|
6331 | <param name="name" type="wstring" dir="in">
|
---|
6332 | <desc>Unique logical name of the shared folder.</desc>
|
---|
6333 | </param>
|
---|
6334 | <param name="hostPath" type="wstring" dir="in">
|
---|
6335 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
6336 | </param>
|
---|
6337 | <param name="writable" type="boolean" dir="in">
|
---|
6338 | <desc>Whether the share is writable or readonly</desc>
|
---|
6339 | </param>
|
---|
6340 | <param name="automount" type="boolean" dir="in">
|
---|
6341 | <desc>Whether the share gets automatically mounted by the guest
|
---|
6342 | or not.</desc>
|
---|
6343 | </param>
|
---|
6344 | </method>
|
---|
6345 |
|
---|
6346 | <method name="removeSharedFolder">
|
---|
6347 | <desc>
|
---|
6348 | Removes a transient shared folder with the given name previously
|
---|
6349 | created by <link to="#createSharedFolder"/> from the collection of
|
---|
6350 | shared folders and stops sharing it.
|
---|
6351 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6352 | Virtual machine in Saved state or currently changing state.
|
---|
6353 | </result>
|
---|
6354 | <result name="VBOX_E_FILE_ERROR">
|
---|
6355 | Shared folder does not exists.
|
---|
6356 | </result>
|
---|
6357 | </desc>
|
---|
6358 | <param name="name" type="wstring" dir="in">
|
---|
6359 | <desc>Logical name of the shared folder to remove.</desc>
|
---|
6360 | </param>
|
---|
6361 | </method>
|
---|
6362 |
|
---|
6363 | <method name="takeSnapshot">
|
---|
6364 | <desc>
|
---|
6365 | Saves the current execution state
|
---|
6366 | and all settings of the machine and creates differencing images
|
---|
6367 | for all normal (non-independent) media.
|
---|
6368 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6369 |
|
---|
6370 | This method can be called for a PoweredOff, Saved (see
|
---|
6371 | <link to="#saveState"/>), Running or
|
---|
6372 | Paused virtual machine. When the machine is PoweredOff, an
|
---|
6373 | offline snapshot is created. When the machine is Running a live
|
---|
6374 | snapshot is created, and an online snapshot is is created when Paused.
|
---|
6375 |
|
---|
6376 | The taken snapshot is always based on the
|
---|
6377 | <link to="IMachine::currentSnapshot">current snapshot</link>
|
---|
6378 | of the associated virtual machine and becomes a new current snapshot.
|
---|
6379 |
|
---|
6380 | <note>
|
---|
6381 | This method implicitly calls <link to="IMachine::saveSettings"/> to
|
---|
6382 | save all current machine settings before taking an offline snapshot.
|
---|
6383 | </note>
|
---|
6384 |
|
---|
6385 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6386 | Virtual machine currently changing state.
|
---|
6387 | </result>
|
---|
6388 | </desc>
|
---|
6389 | <param name="name" type="wstring" dir="in">
|
---|
6390 | <desc>Short name for the snapshot.</desc>
|
---|
6391 | </param>
|
---|
6392 | <param name="description" type="wstring" dir="in">
|
---|
6393 | <desc>Optional description of the snapshot.</desc>
|
---|
6394 | </param>
|
---|
6395 | <param name="progress" type="IProgress" dir="return">
|
---|
6396 | <desc>Progress object to track the operation completion.</desc>
|
---|
6397 | </param>
|
---|
6398 | </method>
|
---|
6399 |
|
---|
6400 | <method name="deleteSnapshot">
|
---|
6401 | <desc>
|
---|
6402 | Starts deleting the specified snapshot asynchronously.
|
---|
6403 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6404 |
|
---|
6405 | The execution state and settings of the associated machine stored in
|
---|
6406 | the snapshot will be deleted. The contents of all differencing media of
|
---|
6407 | this snapshot will be merged with the contents of their dependent child
|
---|
6408 | media to keep the medium chain valid (in other words, all changes
|
---|
6409 | represented by media being deleted will be propagated to their child
|
---|
6410 | medium). After that, this snapshot's differencing medium will be
|
---|
6411 | deleted. The parent of this snapshot will become a new parent for all
|
---|
6412 | its child snapshots.
|
---|
6413 |
|
---|
6414 | If the deleted snapshot is the current one, its parent snapshot will
|
---|
6415 | become a new current snapshot. The current machine state is not directly
|
---|
6416 | affected in this case, except that currently attached differencing
|
---|
6417 | media based on media of the deleted snapshot will be also merged as
|
---|
6418 | described above.
|
---|
6419 |
|
---|
6420 | If the deleted snapshot is the first or current snapshot, then the
|
---|
6421 | respective IMachine attributes will be adjusted. Deleting the current
|
---|
6422 | snapshot will also implicitly call <link to="IMachine::saveSettings"/>
|
---|
6423 | to make all current machine settings permanent.
|
---|
6424 |
|
---|
6425 | Deleting a snapshot has the following preconditions:
|
---|
6426 |
|
---|
6427 | <ul>
|
---|
6428 | <li>Child media of all normal media of the deleted snapshot
|
---|
6429 | must be accessible (see <link to="IMedium::state"/>) for this
|
---|
6430 | operation to succeed. In particular, this means that all virtual
|
---|
6431 | machines whose media are directly or indirectly based on the
|
---|
6432 | media of deleted snapshot must be powered off.</li>
|
---|
6433 |
|
---|
6434 | <li>You cannot delete the snapshot if a medium attached to it has
|
---|
6435 | more than once child medium (differencing images) because otherwise
|
---|
6436 | merging would be impossible. This might be the case if there is
|
---|
6437 | more than one child snapshot or differencing images were created
|
---|
6438 | for other reason (e.g. implicitly because of multiple machine
|
---|
6439 | attachments).</li>
|
---|
6440 | </ul>
|
---|
6441 |
|
---|
6442 |
|
---|
6443 | The virtual machine's <link to="IMachine::state">state</link> is
|
---|
6444 | changed to "DeletingSnapshot", "DeletingSnapshotOnline" or
|
---|
6445 | "DeletingSnapshotPaused" while this operation is in progress.
|
---|
6446 |
|
---|
6447 | <note>
|
---|
6448 | Merging medium contents can be very time and disk space
|
---|
6449 | consuming, if these media are big in size and have many
|
---|
6450 | children. However, if the snapshot being deleted is the last
|
---|
6451 | (head) snapshot on the branch, the operation will be rather
|
---|
6452 | quick.
|
---|
6453 | </note>
|
---|
6454 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6455 | The running virtual machine prevents deleting this snapshot. This
|
---|
6456 | happens only in very specific situations, usually snapshots can be
|
---|
6457 | deleted without trouble while a VM is running. The error message
|
---|
6458 | text explains the reason for the failure.
|
---|
6459 | </result>
|
---|
6460 | </desc>
|
---|
6461 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6462 | <desc>UUID of the snapshot to delete.</desc>
|
---|
6463 | </param>
|
---|
6464 | <param name="progress" type="IProgress" dir="return">
|
---|
6465 | <desc>Progress object to track the operation completion.</desc>
|
---|
6466 | </param>
|
---|
6467 | </method>
|
---|
6468 |
|
---|
6469 | <method name="restoreSnapshot">
|
---|
6470 | <desc>
|
---|
6471 | Starts resetting the machine's current state to the state contained
|
---|
6472 | in the given snapshot, asynchronously. All current settings of the
|
---|
6473 | machine will be reset and changes stored in differencing media
|
---|
6474 | will be lost.
|
---|
6475 | See <link to="ISnapshot" /> for an introduction to snapshots.
|
---|
6476 |
|
---|
6477 | After this operation is successfully completed, new empty differencing
|
---|
6478 | media are created for all normal media of the machine.
|
---|
6479 |
|
---|
6480 | If the given snapshot is an online snapshot, the machine will go to
|
---|
6481 | the <link to="MachineState_Saved"> saved state</link>, so that the
|
---|
6482 | next time it is powered on, the execution state will be restored
|
---|
6483 | from the state of the snapshot.
|
---|
6484 |
|
---|
6485 | <note>
|
---|
6486 | The machine must not be running, otherwise the operation will fail.
|
---|
6487 | </note>
|
---|
6488 |
|
---|
6489 | <note>
|
---|
6490 | If the machine state is <link to="MachineState_Saved">Saved</link>
|
---|
6491 | prior to this operation, the saved state file will be implicitly
|
---|
6492 | deleted (as if <link to="IConsole::discardSavedState"/> were
|
---|
6493 | called).
|
---|
6494 | </note>
|
---|
6495 |
|
---|
6496 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6497 | Virtual machine is running.
|
---|
6498 | </result>
|
---|
6499 | </desc>
|
---|
6500 | <param name="snapshot" type="ISnapshot" dir="in">
|
---|
6501 | <desc>The snapshot to restore the VM state from.</desc>
|
---|
6502 | </param>
|
---|
6503 | <param name="progress" type="IProgress" dir="return">
|
---|
6504 | <desc>Progress object to track the operation completion.</desc>
|
---|
6505 | </param>
|
---|
6506 | </method>
|
---|
6507 |
|
---|
6508 | <method name="teleport">
|
---|
6509 | <desc>
|
---|
6510 | Teleport the VM to a different host machine or process.
|
---|
6511 |
|
---|
6512 | TODO explain the details.
|
---|
6513 |
|
---|
6514 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
6515 | Virtual machine not running or paused.
|
---|
6516 | </result>
|
---|
6517 | </desc>
|
---|
6518 | <param name="hostname" type="wstring" dir="in">
|
---|
6519 | <desc>The name or IP of the host to teleport to.</desc>
|
---|
6520 | </param>
|
---|
6521 | <param name="tcpport" type="unsigned long" dir="in">
|
---|
6522 | <desc>The TCP port to connect to (1..65535).</desc>
|
---|
6523 | </param>
|
---|
6524 | <param name="password" type="wstring" dir="in">
|
---|
6525 | <desc>The password.</desc>
|
---|
6526 | </param>
|
---|
6527 | <param name="maxDowntime" type="unsigned long" dir="in">
|
---|
6528 | <desc>
|
---|
6529 | The maximum allowed downtime given as milliseconds. 0 is not a valid
|
---|
6530 | value. Recommended value: 250 ms.
|
---|
6531 |
|
---|
6532 | The higher the value is, the greater the chance for a successful
|
---|
6533 | teleportation. A small value may easily result in the teleportation
|
---|
6534 | process taking hours and eventually fail.
|
---|
6535 |
|
---|
6536 | <note>
|
---|
6537 | The current implementation treats this a guideline, not as an
|
---|
6538 | absolute rule.
|
---|
6539 | </note>
|
---|
6540 | </desc>
|
---|
6541 | </param>
|
---|
6542 | <param name="progress" type="IProgress" dir="return">
|
---|
6543 | <desc>Progress object to track the operation completion.</desc>
|
---|
6544 | </param>
|
---|
6545 | </method>
|
---|
6546 |
|
---|
6547 | </interface>
|
---|
6548 |
|
---|
6549 | <!--
|
---|
6550 | // IHost
|
---|
6551 | /////////////////////////////////////////////////////////////////////////
|
---|
6552 | -->
|
---|
6553 |
|
---|
6554 | <enum
|
---|
6555 | name="HostNetworkInterfaceMediumType"
|
---|
6556 | uuid="1aa54aaf-2497-45a2-bfb1-8eb225e93d5b"
|
---|
6557 | >
|
---|
6558 | <desc>
|
---|
6559 | Type of encapsulation. Ethernet encapsulation includes both wired and
|
---|
6560 | wireless Ethernet connections.
|
---|
6561 | <see>IHostNetworkInterface</see>
|
---|
6562 | </desc>
|
---|
6563 |
|
---|
6564 | <const name="Unknown" value="0">
|
---|
6565 | <desc>
|
---|
6566 | The type of interface cannot be determined.
|
---|
6567 | </desc>
|
---|
6568 | </const>
|
---|
6569 | <const name="Ethernet" value="1">
|
---|
6570 | <desc>
|
---|
6571 | Ethernet frame encapsulation.
|
---|
6572 | </desc>
|
---|
6573 | </const>
|
---|
6574 | <const name="PPP" value="2">
|
---|
6575 | <desc>
|
---|
6576 | Point-to-point protocol encapsulation.
|
---|
6577 | </desc>
|
---|
6578 | </const>
|
---|
6579 | <const name="SLIP" value="3">
|
---|
6580 | <desc>
|
---|
6581 | Serial line IP encapsulation.
|
---|
6582 | </desc>
|
---|
6583 | </const>
|
---|
6584 | </enum>
|
---|
6585 |
|
---|
6586 | <enum
|
---|
6587 | name="HostNetworkInterfaceStatus"
|
---|
6588 | uuid="CC474A69-2710-434B-8D99-C38E5D5A6F41"
|
---|
6589 | >
|
---|
6590 | <desc>
|
---|
6591 | Current status of the interface.
|
---|
6592 | <see>IHostNetworkInterface</see>
|
---|
6593 | </desc>
|
---|
6594 |
|
---|
6595 | <const name="Unknown" value="0">
|
---|
6596 | <desc>
|
---|
6597 | The state of interface cannot be determined.
|
---|
6598 | </desc>
|
---|
6599 | </const>
|
---|
6600 | <const name="Up" value="1">
|
---|
6601 | <desc>
|
---|
6602 | The interface is fully operational.
|
---|
6603 | </desc>
|
---|
6604 | </const>
|
---|
6605 | <const name="Down" value="2">
|
---|
6606 | <desc>
|
---|
6607 | The interface is not functioning.
|
---|
6608 | </desc>
|
---|
6609 | </const>
|
---|
6610 | </enum>
|
---|
6611 |
|
---|
6612 | <enum
|
---|
6613 | name="HostNetworkInterfaceType"
|
---|
6614 | uuid="67431b00-9946-48a2-bc02-b25c5919f4f3"
|
---|
6615 | >
|
---|
6616 | <desc>
|
---|
6617 | Network interface type.
|
---|
6618 | </desc>
|
---|
6619 | <const name="Bridged" value="1"/>
|
---|
6620 | <const name="HostOnly" value="2"/>
|
---|
6621 | </enum>
|
---|
6622 |
|
---|
6623 | <interface
|
---|
6624 | name="IHostNetworkInterface" extends="$unknown"
|
---|
6625 | uuid="ce6fae58-7642-4102-b5db-c9005c2320a8"
|
---|
6626 | wsmap="managed"
|
---|
6627 | >
|
---|
6628 | <desc>
|
---|
6629 | Represents one of host's network interfaces. IP V6 address and network
|
---|
6630 | mask are strings of 32 hexdecimal digits grouped by four. Groups are
|
---|
6631 | separated by colons.
|
---|
6632 | For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030.
|
---|
6633 | </desc>
|
---|
6634 | <attribute name="name" type="wstring" readonly="yes">
|
---|
6635 | <desc>Returns the host network interface name.</desc>
|
---|
6636 | </attribute>
|
---|
6637 |
|
---|
6638 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
6639 | <desc>Returns the interface UUID.</desc>
|
---|
6640 | </attribute>
|
---|
6641 |
|
---|
6642 | <attribute name="networkName" type="wstring" readonly="yes">
|
---|
6643 | <desc>Returns the name of a virtual network the interface gets attached to.</desc>
|
---|
6644 | </attribute>
|
---|
6645 |
|
---|
6646 | <attribute name="dhcpEnabled" type="boolean" readonly="yes">
|
---|
6647 | <desc>Specifies whether the DHCP is enabled for the interface.</desc>
|
---|
6648 | </attribute>
|
---|
6649 |
|
---|
6650 | <attribute name="IPAddress" type="wstring" readonly="yes">
|
---|
6651 | <desc>Returns the IP V4 address of the interface.</desc>
|
---|
6652 | </attribute>
|
---|
6653 |
|
---|
6654 | <attribute name="networkMask" type="wstring" readonly="yes">
|
---|
6655 | <desc>Returns the network mask of the interface.</desc>
|
---|
6656 | </attribute>
|
---|
6657 |
|
---|
6658 | <attribute name="IPV6Supported" type="boolean" readonly="yes">
|
---|
6659 | <desc>Specifies whether the IP V6 is supported/enabled for the interface.</desc>
|
---|
6660 | </attribute>
|
---|
6661 |
|
---|
6662 | <attribute name="IPV6Address" type="wstring" readonly="yes">
|
---|
6663 | <desc>Returns the IP V6 address of the interface.</desc>
|
---|
6664 | </attribute>
|
---|
6665 |
|
---|
6666 | <attribute name="IPV6NetworkMaskPrefixLength" type="unsigned long" readonly="yes">
|
---|
6667 | <desc>Returns the length IP V6 network mask prefix of the interface.</desc>
|
---|
6668 | </attribute>
|
---|
6669 |
|
---|
6670 | <attribute name="hardwareAddress" type="wstring" readonly="yes">
|
---|
6671 | <desc>Returns the hardware address. For Ethernet it is MAC address.</desc>
|
---|
6672 | </attribute>
|
---|
6673 |
|
---|
6674 | <attribute name="mediumType" type="HostNetworkInterfaceMediumType" readonly="yes">
|
---|
6675 | <desc>Type of protocol encapsulation used.</desc>
|
---|
6676 | </attribute>
|
---|
6677 |
|
---|
6678 | <attribute name="status" type="HostNetworkInterfaceStatus" readonly="yes">
|
---|
6679 | <desc>Status of the interface.</desc>
|
---|
6680 | </attribute>
|
---|
6681 |
|
---|
6682 | <attribute name="interfaceType" type="HostNetworkInterfaceType" readonly="yes">
|
---|
6683 | <desc>specifies the host interface type.</desc>
|
---|
6684 | </attribute>
|
---|
6685 |
|
---|
6686 | <method name="enableStaticIpConfig">
|
---|
6687 | <desc>sets and enables the static IP V4 configuration for the given interface.</desc>
|
---|
6688 | <param name="IPAddress" type="wstring" dir="in">
|
---|
6689 | <desc>
|
---|
6690 | IP address.
|
---|
6691 | </desc>
|
---|
6692 | </param>
|
---|
6693 | <param name="networkMask" type="wstring" dir="in">
|
---|
6694 | <desc>
|
---|
6695 | network mask.
|
---|
6696 | </desc>
|
---|
6697 | </param>
|
---|
6698 | </method>
|
---|
6699 |
|
---|
6700 | <method name="enableStaticIpConfigV6">
|
---|
6701 | <desc>sets and enables the static IP V6 configuration for the given interface.</desc>
|
---|
6702 | <param name="IPV6Address" type="wstring" dir="in">
|
---|
6703 | <desc>
|
---|
6704 | IP address.
|
---|
6705 | </desc>
|
---|
6706 | </param>
|
---|
6707 | <param name="IPV6NetworkMaskPrefixLength" type="unsigned long" dir="in">
|
---|
6708 | <desc>
|
---|
6709 | network mask.
|
---|
6710 | </desc>
|
---|
6711 | </param>
|
---|
6712 | </method>
|
---|
6713 |
|
---|
6714 | <method name="enableDynamicIpConfig">
|
---|
6715 | <desc>enables the dynamic IP configuration.</desc>
|
---|
6716 | </method>
|
---|
6717 |
|
---|
6718 | <method name="dhcpRediscover">
|
---|
6719 | <desc>refreshes the IP configuration for dhcp-enabled interface.</desc>
|
---|
6720 | </method>
|
---|
6721 |
|
---|
6722 | </interface>
|
---|
6723 |
|
---|
6724 | <interface
|
---|
6725 | name="IHost" extends="$unknown"
|
---|
6726 | uuid="35b004f4-7806-4009-bfa8-d1308adba7e5"
|
---|
6727 | wsmap="managed"
|
---|
6728 | >
|
---|
6729 | <desc>
|
---|
6730 | The IHost interface represents the physical machine that this VirtualBox
|
---|
6731 | installation runs on.
|
---|
6732 |
|
---|
6733 | An object implementing this interface is returned by the
|
---|
6734 | <link to="IVirtualBox::host" /> attribute. This interface contains
|
---|
6735 | read-only information about the host's physical hardware (such as what
|
---|
6736 | processors and disks are available, what the host operating system is,
|
---|
6737 | and so on) and also allows for manipulating some of the host's hardware,
|
---|
6738 | such as global USB device filters and host interface networking.
|
---|
6739 |
|
---|
6740 | </desc>
|
---|
6741 | <attribute name="DVDDrives" type="IMedium" readonly="yes" safearray="yes">
|
---|
6742 | <desc>List of DVD drives available on the host.</desc>
|
---|
6743 | </attribute>
|
---|
6744 |
|
---|
6745 | <attribute name="floppyDrives" type="IMedium" readonly="yes" safearray="yes">
|
---|
6746 | <desc>List of floppy drives available on the host.</desc>
|
---|
6747 | </attribute>
|
---|
6748 |
|
---|
6749 | <attribute name="USBDevices" type="IHostUSBDevice" readonly="yes" safearray="yes">
|
---|
6750 | <desc>
|
---|
6751 | List of USB devices currently attached to the host.
|
---|
6752 | Once a new device is physically attached to the host computer,
|
---|
6753 | it appears in this list and remains there until detached.
|
---|
6754 |
|
---|
6755 | <note>
|
---|
6756 | If USB functionality is not available in the given edition of
|
---|
6757 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
6758 | </note>
|
---|
6759 | </desc>
|
---|
6760 | </attribute>
|
---|
6761 |
|
---|
6762 | <attribute name="USBDeviceFilters" type="IHostUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
6763 | <desc>
|
---|
6764 | List of USB device filters in action.
|
---|
6765 | When a new device is physically attached to the host computer,
|
---|
6766 | filters from this list are applied to it (in order they are stored
|
---|
6767 | in the list). The first matched filter will determine the
|
---|
6768 | <link to="IHostUSBDeviceFilter::action">action</link>
|
---|
6769 | performed on the device.
|
---|
6770 |
|
---|
6771 | Unless the device is ignored by these filters, filters of all
|
---|
6772 | currently running virtual machines
|
---|
6773 | (<link to="IUSBController::deviceFilters"/>) are applied to it.
|
---|
6774 |
|
---|
6775 | <note>
|
---|
6776 | If USB functionality is not available in the given edition of
|
---|
6777 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
6778 | </note>
|
---|
6779 |
|
---|
6780 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
6781 | </desc>
|
---|
6782 | </attribute>
|
---|
6783 |
|
---|
6784 | <attribute name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" readonly="yes">
|
---|
6785 | <desc>List of host network interfaces currently defined on the host.</desc>
|
---|
6786 | </attribute>
|
---|
6787 |
|
---|
6788 | <attribute name="processorCount" type="unsigned long" readonly="yes">
|
---|
6789 | <desc>Number of (logical) CPUs installed in the host system.</desc>
|
---|
6790 | </attribute>
|
---|
6791 |
|
---|
6792 | <attribute name="processorOnlineCount" type="unsigned long" readonly="yes">
|
---|
6793 | <desc>Number of (logical) CPUs online in the host system.</desc>
|
---|
6794 | </attribute>
|
---|
6795 |
|
---|
6796 | <attribute name="processorCoreCount" type="unsigned long" readonly="yes">
|
---|
6797 | <desc>Number of physical processor cores installed in the host system.</desc>
|
---|
6798 | </attribute>
|
---|
6799 |
|
---|
6800 | <method name="getProcessorSpeed">
|
---|
6801 | <desc>Query the (approximate) maximum speed of a specified host CPU in
|
---|
6802 | Megahertz.
|
---|
6803 | </desc>
|
---|
6804 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
6805 | <desc>
|
---|
6806 | Identifier of the CPU.
|
---|
6807 | </desc>
|
---|
6808 | </param>
|
---|
6809 | <param name="speed" type="unsigned long" dir="return">
|
---|
6810 | <desc>
|
---|
6811 | Speed value. 0 is returned if value is not known or @a cpuId is
|
---|
6812 | invalid.
|
---|
6813 | </desc>
|
---|
6814 | </param>
|
---|
6815 | </method>
|
---|
6816 |
|
---|
6817 | <method name="getProcessorFeature">
|
---|
6818 | <desc>Query whether a CPU feature is supported or not.</desc>
|
---|
6819 | <param name="feature" type="ProcessorFeature" dir="in">
|
---|
6820 | <desc>
|
---|
6821 | CPU Feature identifier.
|
---|
6822 | </desc>
|
---|
6823 | </param>
|
---|
6824 | <param name="supported" type="boolean" dir="return">
|
---|
6825 | <desc>
|
---|
6826 | Feature is supported or not.
|
---|
6827 | </desc>
|
---|
6828 | </param>
|
---|
6829 | </method>
|
---|
6830 |
|
---|
6831 | <method name="getProcessorDescription">
|
---|
6832 | <desc>Query the model string of a specified host CPU.
|
---|
6833 | </desc>
|
---|
6834 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
6835 | <desc>
|
---|
6836 | Identifier of the CPU.
|
---|
6837 | <note>
|
---|
6838 | The current implementation might not necessarily return the
|
---|
6839 | description for this exact CPU.
|
---|
6840 | </note>
|
---|
6841 | </desc>
|
---|
6842 | </param>
|
---|
6843 | <param name="description" type="wstring" dir="return">
|
---|
6844 | <desc>
|
---|
6845 | Model string. An empty string is returned if value is not known or
|
---|
6846 | @a cpuId is invalid.
|
---|
6847 | </desc>
|
---|
6848 | </param>
|
---|
6849 | </method>
|
---|
6850 |
|
---|
6851 | <method name="getProcessorCPUIDLeaf">
|
---|
6852 | <desc>
|
---|
6853 | Returns the CPU cpuid information for the specified leaf.
|
---|
6854 | </desc>
|
---|
6855 | <param name="cpuId" type="unsigned long" dir="in">
|
---|
6856 | <desc>
|
---|
6857 | Identifier of the CPU. The CPU most be online.
|
---|
6858 | <note>
|
---|
6859 | The current implementation might not necessarily return the
|
---|
6860 | description for this exact CPU.
|
---|
6861 | </note>
|
---|
6862 | </desc>
|
---|
6863 | </param>
|
---|
6864 | <param name="leaf" type="unsigned long" dir="in">
|
---|
6865 | <desc>
|
---|
6866 | CPUID leaf index (eax).
|
---|
6867 | </desc>
|
---|
6868 | </param>
|
---|
6869 | <param name="subLeaf" type="unsigned long" dir="in">
|
---|
6870 | <desc>
|
---|
6871 | CPUID leaf sub index (ecx). This currently only applies to cache
|
---|
6872 | information on Intel CPUs. Use 0 if retrieving values for
|
---|
6873 | <link to="IMachine::setCPUIDLeaf"/>.
|
---|
6874 | </desc>
|
---|
6875 | </param>
|
---|
6876 | <param name="valEax" type="unsigned long" dir="out">
|
---|
6877 | <desc>
|
---|
6878 | CPUID leaf value for register eax.
|
---|
6879 | </desc>
|
---|
6880 | </param>
|
---|
6881 | <param name="valEbx" type="unsigned long" dir="out">
|
---|
6882 | <desc>
|
---|
6883 | CPUID leaf value for register ebx.
|
---|
6884 | </desc>
|
---|
6885 | </param>
|
---|
6886 | <param name="valEcx" type="unsigned long" dir="out">
|
---|
6887 | <desc>
|
---|
6888 | CPUID leaf value for register ecx.
|
---|
6889 | </desc>
|
---|
6890 | </param>
|
---|
6891 | <param name="valEdx" type="unsigned long" dir="out">
|
---|
6892 | <desc>
|
---|
6893 | CPUID leaf value for register edx.
|
---|
6894 | </desc>
|
---|
6895 | </param>
|
---|
6896 | </method>
|
---|
6897 |
|
---|
6898 | <attribute name="memorySize" type="unsigned long" readonly="yes">
|
---|
6899 | <desc>Amount of system memory in megabytes installed in the host system.</desc>
|
---|
6900 | </attribute>
|
---|
6901 |
|
---|
6902 | <attribute name="memoryAvailable" type="unsigned long" readonly="yes">
|
---|
6903 | <desc>Available system memory in the host system.</desc>
|
---|
6904 | </attribute>
|
---|
6905 |
|
---|
6906 | <attribute name="operatingSystem" type="wstring" readonly="yes">
|
---|
6907 | <desc>Name of the host system's operating system.</desc>
|
---|
6908 | </attribute>
|
---|
6909 |
|
---|
6910 | <attribute name="OSVersion" type="wstring" readonly="yes">
|
---|
6911 | <desc>Host operating system's version string.</desc>
|
---|
6912 | </attribute>
|
---|
6913 |
|
---|
6914 | <attribute name="UTCTime" type="long long" readonly="yes">
|
---|
6915 | <desc>Returns the current host time in milliseconds since 1970-01-01 UTC.</desc>
|
---|
6916 | </attribute>
|
---|
6917 |
|
---|
6918 | <attribute name="Acceleration3DAvailable" type="boolean" readonly="yes">
|
---|
6919 | <desc>Returns @c true when the host supports 3D hardware acceleration.</desc>
|
---|
6920 | </attribute>
|
---|
6921 |
|
---|
6922 | <method name="createHostOnlyNetworkInterface">
|
---|
6923 | <desc>
|
---|
6924 | Creates a new adapter for Host Only Networking.
|
---|
6925 | <result name="E_INVALIDARG">
|
---|
6926 | Host network interface @a name already exists.
|
---|
6927 | </result>
|
---|
6928 | </desc>
|
---|
6929 | <param name="hostInterface" type="IHostNetworkInterface" dir="out">
|
---|
6930 | <desc>
|
---|
6931 | Created host interface object.
|
---|
6932 | </desc>
|
---|
6933 | </param>
|
---|
6934 | <param name="progress" type="IProgress" dir="return">
|
---|
6935 | <desc>
|
---|
6936 | Progress object to track the operation completion.
|
---|
6937 | </desc>
|
---|
6938 | </param>
|
---|
6939 | </method>
|
---|
6940 |
|
---|
6941 | <method name="removeHostOnlyNetworkInterface">
|
---|
6942 | <desc>
|
---|
6943 | Removes the given Host Only Networking interface.
|
---|
6944 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
6945 | No host network interface matching @a id found.
|
---|
6946 | </result>
|
---|
6947 | </desc>
|
---|
6948 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
6949 | <desc>
|
---|
6950 | Adapter GUID.
|
---|
6951 | </desc>
|
---|
6952 | </param>
|
---|
6953 | <param name="progress" type="IProgress" dir="return">
|
---|
6954 | <desc>
|
---|
6955 | Progress object to track the operation completion.
|
---|
6956 | </desc>
|
---|
6957 | </param>
|
---|
6958 | </method>
|
---|
6959 |
|
---|
6960 | <method name="createUSBDeviceFilter">
|
---|
6961 | <desc>
|
---|
6962 | Creates a new USB device filter. All attributes except
|
---|
6963 | the filter name are set to empty (any match),
|
---|
6964 | <i>active</i> is @c false (the filter is not active).
|
---|
6965 |
|
---|
6966 | The created filter can be added to the list of filters using
|
---|
6967 | <link to="#insertUSBDeviceFilter"/>.
|
---|
6968 |
|
---|
6969 | <see>#USBDeviceFilters</see>
|
---|
6970 | </desc>
|
---|
6971 | <param name="name" type="wstring" dir="in">
|
---|
6972 | <desc>
|
---|
6973 | Filter name. See <link to="IUSBDeviceFilter::name"/> for more information.
|
---|
6974 | </desc>
|
---|
6975 | </param>
|
---|
6976 | <param name="filter" type="IHostUSBDeviceFilter" dir="return">
|
---|
6977 | <desc>Created filter object.</desc>
|
---|
6978 | </param>
|
---|
6979 | </method>
|
---|
6980 |
|
---|
6981 | <method name="insertUSBDeviceFilter">
|
---|
6982 | <desc>
|
---|
6983 | Inserts the given USB device to the specified position
|
---|
6984 | in the list of filters.
|
---|
6985 |
|
---|
6986 | Positions are numbered starting from @c 0. If the specified
|
---|
6987 | position is equal to or greater than the number of elements in
|
---|
6988 | the list, the filter is added at the end of the collection.
|
---|
6989 |
|
---|
6990 | <note>
|
---|
6991 | Duplicates are not allowed, so an attempt to insert a
|
---|
6992 | filter already in the list is an error.
|
---|
6993 | </note>
|
---|
6994 | <note>
|
---|
6995 | If USB functionality is not available in the given edition of
|
---|
6996 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
6997 | </note>
|
---|
6998 |
|
---|
6999 | <see>#USBDeviceFilters</see>
|
---|
7000 |
|
---|
7001 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
7002 | USB device filter is not created within this VirtualBox instance.
|
---|
7003 | </result>
|
---|
7004 | <result name="E_INVALIDARG">
|
---|
7005 | USB device filter already in list.
|
---|
7006 | </result>
|
---|
7007 |
|
---|
7008 | </desc>
|
---|
7009 | <param name="position" type="unsigned long" dir="in">
|
---|
7010 | <desc>Position to insert the filter to.</desc>
|
---|
7011 | </param>
|
---|
7012 | <param name="filter" type="IHostUSBDeviceFilter" dir="in">
|
---|
7013 | <desc>USB device filter to insert.</desc>
|
---|
7014 | </param>
|
---|
7015 | </method>
|
---|
7016 |
|
---|
7017 | <method name="removeUSBDeviceFilter">
|
---|
7018 | <desc>
|
---|
7019 | Removes a USB device filter from the specified position in the
|
---|
7020 | list of filters.
|
---|
7021 |
|
---|
7022 | Positions are numbered starting from @c 0. Specifying a
|
---|
7023 | position equal to or greater than the number of elements in
|
---|
7024 | the list will produce an error.
|
---|
7025 |
|
---|
7026 | <note>
|
---|
7027 | If USB functionality is not available in the given edition of
|
---|
7028 | VirtualBox, this method will set the result code to @c E_NOTIMPL.
|
---|
7029 | </note>
|
---|
7030 |
|
---|
7031 | <see>#USBDeviceFilters</see>
|
---|
7032 |
|
---|
7033 | <result name="E_INVALIDARG">
|
---|
7034 | USB device filter list empty or invalid @a position.
|
---|
7035 | </result>
|
---|
7036 |
|
---|
7037 | </desc>
|
---|
7038 | <param name="position" type="unsigned long" dir="in">
|
---|
7039 | <desc>Position to remove the filter from.</desc>
|
---|
7040 | </param>
|
---|
7041 | </method>
|
---|
7042 |
|
---|
7043 | <method name="findHostDVDDrive">
|
---|
7044 | <desc>
|
---|
7045 | Searches for a host DVD drive with the given @c name.
|
---|
7046 |
|
---|
7047 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7048 | Given @c name does not correspond to any host drive.
|
---|
7049 | </result>
|
---|
7050 |
|
---|
7051 | </desc>
|
---|
7052 | <param name="name" type="wstring" dir="in">
|
---|
7053 | <desc>Name of the host drive to search for</desc>
|
---|
7054 | </param>
|
---|
7055 | <param name="drive" type="IMedium" dir="return">
|
---|
7056 | <desc>Found host drive object</desc>
|
---|
7057 | </param>
|
---|
7058 | </method>
|
---|
7059 |
|
---|
7060 | <method name="findHostFloppyDrive">
|
---|
7061 | <desc>
|
---|
7062 | Searches for a host floppy drive with the given @c name.
|
---|
7063 |
|
---|
7064 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7065 | Given @c name does not correspond to any host floppy drive.
|
---|
7066 | </result>
|
---|
7067 |
|
---|
7068 | </desc>
|
---|
7069 | <param name="name" type="wstring" dir="in">
|
---|
7070 | <desc>Name of the host floppy drive to search for</desc>
|
---|
7071 | </param>
|
---|
7072 | <param name="drive" type="IMedium" dir="return">
|
---|
7073 | <desc>Found host floppy drive object</desc>
|
---|
7074 | </param>
|
---|
7075 | </method>
|
---|
7076 |
|
---|
7077 | <method name="findHostNetworkInterfaceByName">
|
---|
7078 | <desc>
|
---|
7079 | Searches through all host network interfaces for an interface with
|
---|
7080 | the given @c name.
|
---|
7081 | <note>
|
---|
7082 | The method returns an error if the given @c name does not
|
---|
7083 | correspond to any host network interface.
|
---|
7084 | </note>
|
---|
7085 | </desc>
|
---|
7086 | <param name="name" type="wstring" dir="in">
|
---|
7087 | <desc>Name of the host network interface to search for.</desc>
|
---|
7088 | </param>
|
---|
7089 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7090 | <desc>Found host network interface object.</desc>
|
---|
7091 | </param>
|
---|
7092 | </method>
|
---|
7093 | <method name="findHostNetworkInterfaceById">
|
---|
7094 | <desc>
|
---|
7095 | Searches through all host network interfaces for an interface with
|
---|
7096 | the given GUID.
|
---|
7097 | <note>
|
---|
7098 | The method returns an error if the given GUID does not
|
---|
7099 | correspond to any host network interface.
|
---|
7100 | </note>
|
---|
7101 | </desc>
|
---|
7102 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
7103 | <desc>GUID of the host network interface to search for.</desc>
|
---|
7104 | </param>
|
---|
7105 | <param name="networkInterface" type="IHostNetworkInterface" dir="return">
|
---|
7106 | <desc>Found host network interface object.</desc>
|
---|
7107 | </param>
|
---|
7108 | </method>
|
---|
7109 | <method name="findHostNetworkInterfacesOfType">
|
---|
7110 | <desc>
|
---|
7111 | Searches through all host network interfaces and returns a list of interfaces of the specified type
|
---|
7112 | </desc>
|
---|
7113 | <param name="type" type="HostNetworkInterfaceType" dir="in">
|
---|
7114 | <desc>type of the host network interfaces to search for.</desc>
|
---|
7115 | </param>
|
---|
7116 | <param name="networkInterfaces" type="IHostNetworkInterface" safearray="yes" dir="return">
|
---|
7117 | <desc>Found host network interface objects.</desc>
|
---|
7118 | </param>
|
---|
7119 | </method>
|
---|
7120 |
|
---|
7121 | <method name="findUSBDeviceById">
|
---|
7122 | <desc>
|
---|
7123 | Searches for a USB device with the given UUID.
|
---|
7124 |
|
---|
7125 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7126 | Given @c id does not correspond to any USB device.
|
---|
7127 | </result>
|
---|
7128 |
|
---|
7129 | <see>IHostUSBDevice::id</see>
|
---|
7130 | </desc>
|
---|
7131 | <param name="id" type="uuid" mod="string" dir="in">
|
---|
7132 | <desc>UUID of the USB device to search for.</desc>
|
---|
7133 | </param>
|
---|
7134 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7135 | <desc>Found USB device object.</desc>
|
---|
7136 | </param>
|
---|
7137 | </method>
|
---|
7138 |
|
---|
7139 | <method name="findUSBDeviceByAddress">
|
---|
7140 | <desc>
|
---|
7141 | Searches for a USB device with the given host address.
|
---|
7142 |
|
---|
7143 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
7144 | Given @c name does not correspond to any USB device.
|
---|
7145 | </result>
|
---|
7146 |
|
---|
7147 | <see>IHostUSBDevice::address</see>
|
---|
7148 | </desc>
|
---|
7149 | <param name="name" type="wstring" dir="in">
|
---|
7150 | <desc>
|
---|
7151 | Address of the USB device (as assigned by the host) to
|
---|
7152 | search for.
|
---|
7153 | </desc>
|
---|
7154 | </param>
|
---|
7155 | <param name="device" type="IHostUSBDevice" dir="return">
|
---|
7156 | <desc>Found USB device object.</desc>
|
---|
7157 | </param>
|
---|
7158 | </method>
|
---|
7159 |
|
---|
7160 | </interface>
|
---|
7161 |
|
---|
7162 | <!--
|
---|
7163 | // ISystemProperties
|
---|
7164 | /////////////////////////////////////////////////////////////////////////
|
---|
7165 | -->
|
---|
7166 |
|
---|
7167 | <interface
|
---|
7168 | name="ISystemProperties"
|
---|
7169 | extends="$unknown"
|
---|
7170 | uuid="2af0100b-fda2-4c6a-8e8f-31e4ba871886"
|
---|
7171 | wsmap="managed"
|
---|
7172 | >
|
---|
7173 | <desc>
|
---|
7174 | The ISystemProperties interface represents global properties of the given
|
---|
7175 | VirtualBox installation.
|
---|
7176 |
|
---|
7177 | These properties define limits and default values for various attributes
|
---|
7178 | and parameters. Most of the properties are read-only, but some can be
|
---|
7179 | changed by a user.
|
---|
7180 | </desc>
|
---|
7181 |
|
---|
7182 | <attribute name="minGuestRAM" type="unsigned long" readonly="yes">
|
---|
7183 | <desc>Minimum guest system memory in Megabytes.</desc>
|
---|
7184 | </attribute>
|
---|
7185 |
|
---|
7186 | <attribute name="maxGuestRAM" type="unsigned long" readonly="yes">
|
---|
7187 | <desc>Maximum guest system memory in Megabytes.</desc>
|
---|
7188 | </attribute>
|
---|
7189 |
|
---|
7190 | <attribute name="minGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7191 | <desc>Minimum guest video memory in Megabytes.</desc>
|
---|
7192 | </attribute>
|
---|
7193 |
|
---|
7194 | <attribute name="maxGuestVRAM" type="unsigned long" readonly="yes">
|
---|
7195 | <desc>Maximum guest video memory in Megabytes.</desc>
|
---|
7196 | </attribute>
|
---|
7197 |
|
---|
7198 | <attribute name="minGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7199 | <desc>Minimum CPU count.</desc>
|
---|
7200 | </attribute>
|
---|
7201 |
|
---|
7202 | <attribute name="maxGuestCPUCount" type="unsigned long" readonly="yes">
|
---|
7203 | <desc>Maximum CPU count.</desc>
|
---|
7204 | </attribute>
|
---|
7205 |
|
---|
7206 | <attribute name="maxGuestMonitors" type="unsigned long" readonly="yes">
|
---|
7207 | <desc>Maximum of monitors which could be connected.</desc>
|
---|
7208 | </attribute>
|
---|
7209 |
|
---|
7210 | <attribute name="infoVDSize" type="long long" readonly="yes">
|
---|
7211 | <desc>Maximum size of a virtual disk image in bytes. Informational value,
|
---|
7212 | does not reflect the limits of any virtual disk image format.</desc>
|
---|
7213 | </attribute>
|
---|
7214 |
|
---|
7215 | <attribute name="networkAdapterCount" type="unsigned long" readonly="yes">
|
---|
7216 | <desc>
|
---|
7217 | Number of network adapters associated with every
|
---|
7218 | <link to="IMachine"/> instance.
|
---|
7219 | </desc>
|
---|
7220 | </attribute>
|
---|
7221 |
|
---|
7222 | <attribute name="serialPortCount" type="unsigned long" readonly="yes">
|
---|
7223 | <desc>
|
---|
7224 | Number of serial ports associated with every
|
---|
7225 | <link to="IMachine"/> instance.
|
---|
7226 | </desc>
|
---|
7227 | </attribute>
|
---|
7228 |
|
---|
7229 | <attribute name="parallelPortCount" type="unsigned long" readonly="yes">
|
---|
7230 | <desc>
|
---|
7231 | Number of parallel ports associated with every
|
---|
7232 | <link to="IMachine"/> instance.
|
---|
7233 | </desc>
|
---|
7234 | </attribute>
|
---|
7235 |
|
---|
7236 | <attribute name="maxBootPosition" type="unsigned long" readonly="yes">
|
---|
7237 | <desc>
|
---|
7238 | Maximum device position in the boot order. This value corresponds
|
---|
7239 | to the total number of devices a machine can boot from, to make it
|
---|
7240 | possible to include all possible devices to the boot list.
|
---|
7241 | <see><link to="IMachine::setBootOrder"/></see>
|
---|
7242 | </desc>
|
---|
7243 | </attribute>
|
---|
7244 |
|
---|
7245 | <attribute name="defaultMachineFolder" type="wstring">
|
---|
7246 | <desc>
|
---|
7247 | Full path to the default directory used to create new or open
|
---|
7248 | existing machines when a machine settings file name contains no
|
---|
7249 | path.
|
---|
7250 |
|
---|
7251 | Starting with VirtualBox 4.0, by default, this attribute contains
|
---|
7252 | the full path of folder named "VirtualBox VMs" in the user's
|
---|
7253 | home directory, which depends on the host platform.
|
---|
7254 |
|
---|
7255 | When setting this attribute, a full path must be specified.
|
---|
7256 | Setting this property to @c null or an empty string or the
|
---|
7257 | special value "Machines" (for compatibility reasons) will restore
|
---|
7258 | that default value.
|
---|
7259 |
|
---|
7260 | If the folder specified herein does not exist, it will be created
|
---|
7261 | automatically as needed.
|
---|
7262 |
|
---|
7263 | <see>
|
---|
7264 | <link to="IVirtualBox::createMachine"/>,
|
---|
7265 | <link to="IVirtualBox::openMachine"/>
|
---|
7266 | </see>
|
---|
7267 | </desc>
|
---|
7268 | </attribute>
|
---|
7269 |
|
---|
7270 | <attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes">
|
---|
7271 | <desc>
|
---|
7272 | List of all medium storage formats supported by this VirtualBox
|
---|
7273 | installation.
|
---|
7274 |
|
---|
7275 | Keep in mind that the medium format identifier
|
---|
7276 | (<link to="IMediumFormat::id"/>) used in other API calls like
|
---|
7277 | <link to="IVirtualBox::createHardDisk"/> to refer to a particular
|
---|
7278 | medium format is a case-insensitive string. This means that, for
|
---|
7279 | example, all of the following strings:
|
---|
7280 | <pre>
|
---|
7281 | "VDI"
|
---|
7282 | "vdi"
|
---|
7283 | "VdI"</pre>
|
---|
7284 | refer to the same medium format.
|
---|
7285 |
|
---|
7286 | Note that the virtual medium framework is backend-based, therefore
|
---|
7287 | the list of supported formats depends on what backends are currently
|
---|
7288 | installed.
|
---|
7289 |
|
---|
7290 | <see>
|
---|
7291 | <link to="IMediumFormat"/>,
|
---|
7292 | </see>
|
---|
7293 | </desc>
|
---|
7294 | </attribute>
|
---|
7295 |
|
---|
7296 | <attribute name="defaultHardDiskFormat" type="wstring">
|
---|
7297 | <desc>
|
---|
7298 | Identifier of the default medium format used by VirtualBox.
|
---|
7299 |
|
---|
7300 | The medium format set by this attribute is used by VirtualBox
|
---|
7301 | when the medium format was not specified explicitly. One example is
|
---|
7302 | <link to="IVirtualBox::createHardDisk"/> with the empty
|
---|
7303 | format argument. A more complex example is implicit creation of
|
---|
7304 | differencing media when taking a snapshot of a virtual machine:
|
---|
7305 | this operation will try to use a format of the parent medium first
|
---|
7306 | and if this format does not support differencing media the default
|
---|
7307 | format specified by this argument will be used.
|
---|
7308 |
|
---|
7309 | The list of supported medium formats may be obtained by the
|
---|
7310 | <link to="#mediumFormats"/> call. Note that the default medium
|
---|
7311 | format must have a capability to create differencing media;
|
---|
7312 | otherwise operations that create media implicitly may fail
|
---|
7313 | unexpectedly.
|
---|
7314 |
|
---|
7315 | The initial value of this property is <tt>"VDI"</tt> in the current
|
---|
7316 | version of the VirtualBox product, but may change in the future.
|
---|
7317 |
|
---|
7318 | <note>
|
---|
7319 | Setting this property to @c null or empty string will restore the
|
---|
7320 | initial value.
|
---|
7321 | </note>
|
---|
7322 |
|
---|
7323 | <see>
|
---|
7324 | <link to="#mediumFormats"/>,
|
---|
7325 | <link to="IMediumFormat::id"/>,
|
---|
7326 | <link to="IVirtualBox::createHardDisk"/>
|
---|
7327 | </see>
|
---|
7328 | </desc>
|
---|
7329 | </attribute>
|
---|
7330 |
|
---|
7331 | <attribute name="freeDiskSpaceWarning" type="long long">
|
---|
7332 | <desc>Issue a warning if the free disk space is below (or in some disk
|
---|
7333 | intensive operation is expected to go below) the given size in
|
---|
7334 | bytes.</desc>
|
---|
7335 | </attribute>
|
---|
7336 |
|
---|
7337 | <attribute name="freeDiskSpacePercentWarning" type="unsigned long">
|
---|
7338 | <desc>Issue a warning if the free disk space is below (or in some disk
|
---|
7339 | intensive operation is expected to go below) the given percentage.</desc>
|
---|
7340 | </attribute>
|
---|
7341 |
|
---|
7342 | <attribute name="freeDiskSpaceError" type="long long">
|
---|
7343 | <desc>Issue an error if the free disk space is below (or in some disk
|
---|
7344 | intensive operation is expected to go below) the given size in
|
---|
7345 | bytes.</desc>
|
---|
7346 | </attribute>
|
---|
7347 |
|
---|
7348 | <attribute name="freeDiskSpacePercentError" type="unsigned long">
|
---|
7349 | <desc>Issue an error if the free disk space is below (or in some disk
|
---|
7350 | intensive operation is expected to go below) the given percentage.</desc>
|
---|
7351 | </attribute>
|
---|
7352 |
|
---|
7353 | <attribute name="VRDEAuthLibrary" type="wstring">
|
---|
7354 | <desc>
|
---|
7355 | Library that provides authentication for Remote Desktop clients. The library
|
---|
7356 | is used if a virtual machine's authentication type is set to "external"
|
---|
7357 | in the VM RemoteDisplay configuration.
|
---|
7358 |
|
---|
7359 | The system library extension (".DLL" or ".so") must be omitted.
|
---|
7360 | A full path can be specified; if not, then the library must reside on the
|
---|
7361 | system's default library path.
|
---|
7362 |
|
---|
7363 | The default value of this property is <tt>"VRDPAuth"</tt>. There is a library
|
---|
7364 | of that name in one of the default VirtualBox library directories.
|
---|
7365 |
|
---|
7366 | For details about VirtualBox authentication libraries and how to implement
|
---|
7367 | them, please refer to the VirtualBox manual.
|
---|
7368 |
|
---|
7369 | <note>
|
---|
7370 | Setting this property to @c null or empty string will restore the
|
---|
7371 | initial value.
|
---|
7372 | </note>
|
---|
7373 | </desc>
|
---|
7374 | </attribute>
|
---|
7375 |
|
---|
7376 | <attribute name="webServiceAuthLibrary" type="wstring">
|
---|
7377 | <desc>
|
---|
7378 | Library that provides authentication for webservice clients. The library
|
---|
7379 | is used if a virtual machine's authentication type is set to "external"
|
---|
7380 | in the VM RemoteDisplay configuration and will be called from
|
---|
7381 | within the <link to="IWebsessionManager::logon" /> implementation.
|
---|
7382 |
|
---|
7383 | As opposed to <link to="ISystemProperties::VRDEAuthLibrary" />,
|
---|
7384 | there is no per-VM setting for this, as the webservice is a global
|
---|
7385 | resource (if it is running). Only for this setting (for the webservice),
|
---|
7386 | setting this value to a literal <tt>"null"</tt> string disables authentication,
|
---|
7387 | meaning that <link to="IWebsessionManager::logon" /> will always succeed,
|
---|
7388 | no matter what user name and password are supplied.
|
---|
7389 |
|
---|
7390 | The initial value of this property is <tt>"VRDPAuth"</tt>,
|
---|
7391 | meaning that the webservice will use the same authentication
|
---|
7392 | library that is used by default for VRDE (again, see
|
---|
7393 | <link to="ISystemProperties::VRDEAuthLibrary" />).
|
---|
7394 | The format and calling convention of authentication libraries
|
---|
7395 | is the same for the webservice as it is for VRDE.
|
---|
7396 |
|
---|
7397 | <note>
|
---|
7398 | Setting this property to @c null or empty string will restore the
|
---|
7399 | initial value.
|
---|
7400 | </note>
|
---|
7401 | </desc>
|
---|
7402 | </attribute>
|
---|
7403 |
|
---|
7404 | <attribute name="defaultVRDELibrary" type="wstring">
|
---|
7405 | <desc>
|
---|
7406 | Default VRDE library.
|
---|
7407 |
|
---|
7408 | The default value of this property is an empty string, which means that the
|
---|
7409 | VRDE is not available.
|
---|
7410 |
|
---|
7411 | For details about VirtualBox Remote Desktop Extension and how to implement
|
---|
7412 | it, please refer to the VirtualBox SDK.
|
---|
7413 | </desc>
|
---|
7414 | </attribute>
|
---|
7415 |
|
---|
7416 | <attribute name="LogHistoryCount" type="unsigned long">
|
---|
7417 | <desc>
|
---|
7418 | This value specifies how many old release log files are kept.
|
---|
7419 | </desc>
|
---|
7420 | </attribute>
|
---|
7421 |
|
---|
7422 | <attribute name="defaultAudioDriver" type="AudioDriverType" readonly="yes">
|
---|
7423 | <desc>This value hold the default audio driver for the current
|
---|
7424 | system.</desc>
|
---|
7425 | </attribute>
|
---|
7426 |
|
---|
7427 | <method name="getMaxDevicesPerPortForStorageBus">
|
---|
7428 | <desc>Returns the maximum number of devices which can be attached to a port
|
---|
7429 | for the given storage bus.</desc>
|
---|
7430 |
|
---|
7431 | <param name="bus" type="StorageBus" dir="in">
|
---|
7432 | <desc>The storage bus type to get the value for.</desc>
|
---|
7433 | </param>
|
---|
7434 |
|
---|
7435 | <param name="maxDevicesPerPort" type="unsigned long" dir="return">
|
---|
7436 | <desc>The maximum number of devices which can eb attached to the port for the given
|
---|
7437 | storage bus.</desc>
|
---|
7438 | </param>
|
---|
7439 | </method>
|
---|
7440 |
|
---|
7441 | <method name="getMinPortCountForStorageBus">
|
---|
7442 | <desc>Returns the minimum number of ports the given storage bus supports.</desc>
|
---|
7443 |
|
---|
7444 | <param name="bus" type="StorageBus" dir="in">
|
---|
7445 | <desc>The storage bus type to get the value for.</desc>
|
---|
7446 | </param>
|
---|
7447 |
|
---|
7448 | <param name="minPortCount" type="unsigned long" dir="return">
|
---|
7449 | <desc>The minimum number of ports for the given storage bus.</desc>
|
---|
7450 | </param>
|
---|
7451 | </method>
|
---|
7452 |
|
---|
7453 | <method name="getMaxPortCountForStorageBus">
|
---|
7454 | <desc>Returns the maximum number of ports the given storage bus supports.</desc>
|
---|
7455 |
|
---|
7456 | <param name="bus" type="StorageBus" dir="in">
|
---|
7457 | <desc>The storage bus type to get the value for.</desc>
|
---|
7458 | </param>
|
---|
7459 |
|
---|
7460 | <param name="maxPortCount" type="unsigned long" dir="return">
|
---|
7461 | <desc>The maximum number of ports for the given storage bus.</desc>
|
---|
7462 | </param>
|
---|
7463 | </method>
|
---|
7464 |
|
---|
7465 | <method name="getMaxInstancesOfStorageBus">
|
---|
7466 | <desc>Returns the maximum number of storage bus instances which
|
---|
7467 | can be configured for each VM. This corresponds to the number of
|
---|
7468 | storage controllers one can have.</desc>
|
---|
7469 |
|
---|
7470 | <param name="bus" type="StorageBus" dir="in">
|
---|
7471 | <desc>The storage bus type to get the value for.</desc>
|
---|
7472 | </param>
|
---|
7473 |
|
---|
7474 | <param name="maxInstances" type="unsigned long" dir="return">
|
---|
7475 | <desc>The maximum number of instances for the given storage bus.</desc>
|
---|
7476 | </param>
|
---|
7477 | </method>
|
---|
7478 |
|
---|
7479 | <method name="getDeviceTypesForStorageBus">
|
---|
7480 | <desc>Returns list of all the supported device types
|
---|
7481 | (<link to="DeviceType"/>) for the given type of storage
|
---|
7482 | bus.</desc>
|
---|
7483 |
|
---|
7484 | <param name="bus" type="StorageBus" dir="in">
|
---|
7485 | <desc>The storage bus type to get the value for.</desc>
|
---|
7486 | </param>
|
---|
7487 |
|
---|
7488 | <param name="deviceTypes" type="DeviceType" safearray="yes" dir="return">
|
---|
7489 | <desc>The list of all supported device types for the given storage bus.</desc>
|
---|
7490 | </param>
|
---|
7491 | </method>
|
---|
7492 |
|
---|
7493 | <method name="getDefaultIoCacheSettingForStorageController">
|
---|
7494 | <desc>Returns the default I/O cache setting for the
|
---|
7495 | given storage controller</desc>
|
---|
7496 |
|
---|
7497 | <param name="controllerType" type="StorageControllerType" dir="in">
|
---|
7498 | <desc>The storage controller to the setting for.</desc>
|
---|
7499 | </param>
|
---|
7500 |
|
---|
7501 | <param name="enabled" type="boolean" dir="return">
|
---|
7502 | <desc>Returned flag indicating the default value</desc>
|
---|
7503 | </param>
|
---|
7504 | </method>
|
---|
7505 | </interface>
|
---|
7506 |
|
---|
7507 | <!--
|
---|
7508 | // IGuest
|
---|
7509 | /////////////////////////////////////////////////////////////////////////
|
---|
7510 | -->
|
---|
7511 |
|
---|
7512 | <interface
|
---|
7513 | name="IGuestOSType" extends="$unknown"
|
---|
7514 | uuid="432c1546-1354-4abf-bf08-878a32a373f5"
|
---|
7515 | wsmap="struct"
|
---|
7516 | >
|
---|
7517 | <desc>
|
---|
7518 | </desc>
|
---|
7519 |
|
---|
7520 | <attribute name="familyId" type="wstring" readonly="yes">
|
---|
7521 | <desc>Guest OS family identifier string.</desc>
|
---|
7522 | </attribute>
|
---|
7523 |
|
---|
7524 | <attribute name="familyDescription" type="wstring" readonly="yes">
|
---|
7525 | <desc>Human readable description of the guest OS family.</desc>
|
---|
7526 | </attribute>
|
---|
7527 |
|
---|
7528 | <attribute name="id" type="wstring" readonly="yes">
|
---|
7529 | <desc>Guest OS identifier string.</desc>
|
---|
7530 | </attribute>
|
---|
7531 |
|
---|
7532 | <attribute name="description" type="wstring" readonly="yes">
|
---|
7533 | <desc>Human readable description of the guest OS.</desc>
|
---|
7534 | </attribute>
|
---|
7535 |
|
---|
7536 | <attribute name="is64Bit" type="boolean" readonly="yes">
|
---|
7537 | <desc>Returns @c true if the given OS is 64-bit</desc>
|
---|
7538 | </attribute>
|
---|
7539 |
|
---|
7540 | <attribute name="recommendedIOAPIC" type="boolean" readonly="yes">
|
---|
7541 | <desc>Returns @c true if IO APIC recommended for this OS type.</desc>
|
---|
7542 | </attribute>
|
---|
7543 |
|
---|
7544 | <attribute name="recommendedVirtEx" type="boolean" readonly="yes">
|
---|
7545 | <desc>Returns @c true if VT-x or AMD-V recommended for this OS type.</desc>
|
---|
7546 | </attribute>
|
---|
7547 |
|
---|
7548 | <attribute name="recommendedRAM" type="unsigned long" readonly="yes">
|
---|
7549 | <desc>Recommended RAM size in Megabytes.</desc>
|
---|
7550 | </attribute>
|
---|
7551 |
|
---|
7552 | <attribute name="recommendedVRAM" type="unsigned long" readonly="yes">
|
---|
7553 | <desc>Recommended video RAM size in Megabytes.</desc>
|
---|
7554 | </attribute>
|
---|
7555 |
|
---|
7556 | <attribute name="recommendedHDD" type="long long" readonly="yes">
|
---|
7557 | <desc>Recommended hard disk size in bytes.</desc>
|
---|
7558 | </attribute>
|
---|
7559 |
|
---|
7560 | <attribute name="adapterType" type="NetworkAdapterType" readonly="yes">
|
---|
7561 | <desc>Returns recommended network adapter for this OS type.</desc>
|
---|
7562 | </attribute>
|
---|
7563 |
|
---|
7564 | <attribute name="recommendedPae" type="boolean" readonly="yes">
|
---|
7565 | <desc>Returns @c true if using PAE is recommended for this OS type.</desc>
|
---|
7566 | </attribute>
|
---|
7567 |
|
---|
7568 | <attribute name="recommendedDvdStorageController" type="StorageControllerType" readonly="yes">
|
---|
7569 | <desc>Recommended storage controller type for DVD/CD drives.</desc>
|
---|
7570 | </attribute>
|
---|
7571 |
|
---|
7572 | <attribute name="recommendedDvdStorageBus" type="StorageBus" readonly="yes">
|
---|
7573 | <desc>Recommended storage bus type for DVD/CD drives.</desc>
|
---|
7574 | </attribute>
|
---|
7575 |
|
---|
7576 | <attribute name="recommendedHdStorageController" type="StorageControllerType" readonly="yes">
|
---|
7577 | <desc>Recommended storage controller type for HD drives.</desc>
|
---|
7578 | </attribute>
|
---|
7579 |
|
---|
7580 | <attribute name="recommendedHdStorageBus" type="StorageBus" readonly="yes">
|
---|
7581 | <desc>Recommended storage bus type for HD drives.</desc>
|
---|
7582 | </attribute>
|
---|
7583 |
|
---|
7584 | <attribute name="recommendedFirmware" type="FirmwareType" readonly="yes">
|
---|
7585 | <desc>Recommended firmware type.</desc>
|
---|
7586 | </attribute>
|
---|
7587 |
|
---|
7588 | <attribute name="recommendedUsbHid" type="boolean" readonly="yes">
|
---|
7589 | <desc>Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended.</desc>
|
---|
7590 | </attribute>
|
---|
7591 |
|
---|
7592 | <attribute name="recommendedHpet" type="boolean" readonly="yes">
|
---|
7593 | <desc>Returns @c true if using HPET is recommended for this OS type.</desc>
|
---|
7594 | </attribute>
|
---|
7595 |
|
---|
7596 | <attribute name="recommendedUsbTablet" type="boolean" readonly="yes">
|
---|
7597 | <desc>Returns @c true if using a USB Tablet is recommended.</desc>
|
---|
7598 | </attribute>
|
---|
7599 |
|
---|
7600 | <attribute name="recommendedRtcUseUtc" type="boolean" readonly="yes">
|
---|
7601 | <desc>Returns @c true if the RTC of this VM should be set to UTC</desc>
|
---|
7602 | </attribute>
|
---|
7603 |
|
---|
7604 | <attribute name="recommendedChipset" type="ChipsetType" readonly="yes">
|
---|
7605 | <desc>Recommended chipset type.</desc>
|
---|
7606 | </attribute>
|
---|
7607 |
|
---|
7608 | <attribute name="recommendedAudioController" type="AudioControllerType" readonly="yes">
|
---|
7609 | <desc>Recommended audio type.</desc>
|
---|
7610 | </attribute>
|
---|
7611 |
|
---|
7612 | </interface>
|
---|
7613 |
|
---|
7614 | <enum
|
---|
7615 | name="AdditionsRunLevelType"
|
---|
7616 | uuid="a25417ee-a9dd-4f5b-b0dc-377860087754"
|
---|
7617 | >
|
---|
7618 | <desc>
|
---|
7619 | Guest Additions run level type.
|
---|
7620 | </desc>
|
---|
7621 |
|
---|
7622 | <const name="None" value="0">
|
---|
7623 | <desc>Guest Additions are not loaded.</desc>
|
---|
7624 | </const>
|
---|
7625 | <const name="System" value="1">
|
---|
7626 | <desc>Guest drivers are loaded.</desc>
|
---|
7627 | </const>
|
---|
7628 | <const name="Userland" value="2">
|
---|
7629 | <desc>Common components (such as application services) are loaded.</desc>
|
---|
7630 | </const>
|
---|
7631 | <const name="Desktop" value="3">
|
---|
7632 | <desc>Per-user desktop components are loaded.</desc>
|
---|
7633 | </const>
|
---|
7634 | </enum>
|
---|
7635 |
|
---|
7636 | <enum
|
---|
7637 | name="ExecuteProcessFlag"
|
---|
7638 | uuid="3258e8a5-ba0c-43d5-86b5-cf91405fddc0"
|
---|
7639 | >
|
---|
7640 | <desc>
|
---|
7641 | Guest process execution flags.
|
---|
7642 | </desc>
|
---|
7643 |
|
---|
7644 | <const name="None" value="0">
|
---|
7645 | <desc>No flag set.</desc>
|
---|
7646 | </const>
|
---|
7647 |
|
---|
7648 | <const name="WaitForProcessStartOnly" value="1">
|
---|
7649 | <desc>Only use the specified timeout value to wait for starting the guest process - the guest
|
---|
7650 | process itself then uses an infinite timeout.</desc>
|
---|
7651 | </const>
|
---|
7652 |
|
---|
7653 | <const name="IgnoreOrphanedProcesses" value="2">
|
---|
7654 | <desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc>
|
---|
7655 | </const>
|
---|
7656 | </enum>
|
---|
7657 |
|
---|
7658 | <enum
|
---|
7659 | name="ProcessInputFlag"
|
---|
7660 | uuid="5d38c1dd-2604-4ddf-92e5-0c0cdd3bdbd5"
|
---|
7661 | >
|
---|
7662 | <desc>
|
---|
7663 | Guest process input flags.
|
---|
7664 | </desc>
|
---|
7665 |
|
---|
7666 | <const name="None" value="0">
|
---|
7667 | <desc>No flag set.</desc>
|
---|
7668 | </const>
|
---|
7669 | <const name="EndOfFile" value="1">
|
---|
7670 | <desc>End of file (input) reached.</desc>
|
---|
7671 | </const>
|
---|
7672 | </enum>
|
---|
7673 |
|
---|
7674 | <enum
|
---|
7675 | name="CopyFileFlag"
|
---|
7676 | uuid="23f79fdf-738a-493d-b80b-42d607c9b916"
|
---|
7677 | >
|
---|
7678 | <desc>
|
---|
7679 | Host/Guest copy flags.
|
---|
7680 | </desc>
|
---|
7681 |
|
---|
7682 | <const name="None" value="0">
|
---|
7683 | <desc>No flag set.</desc>
|
---|
7684 | </const>
|
---|
7685 |
|
---|
7686 | <const name="Recursive" value="1">
|
---|
7687 | <desc>Copy directories recursively.</desc>
|
---|
7688 | </const>
|
---|
7689 |
|
---|
7690 | <const name="Update" value="2">
|
---|
7691 | <desc>Copy only when the source file is newer than the destination file or when the destination file is missing.</desc>
|
---|
7692 | </const>
|
---|
7693 |
|
---|
7694 | <const name="FollowLinks" value="4">
|
---|
7695 | <desc>Follow symbolic links.</desc>
|
---|
7696 | </const>
|
---|
7697 | </enum>
|
---|
7698 |
|
---|
7699 | <interface
|
---|
7700 | name="IGuest" extends="$unknown"
|
---|
7701 | uuid="ded6983f-5c81-4bf9-90af-73f65fd9b728"
|
---|
7702 | wsmap="managed"
|
---|
7703 | >
|
---|
7704 | <desc>
|
---|
7705 | The IGuest interface represents information about the operating system
|
---|
7706 | running inside the virtual machine. Used in
|
---|
7707 | <link to="IConsole::guest"/>.
|
---|
7708 |
|
---|
7709 | IGuest provides information about the guest operating system, whether
|
---|
7710 | Guest Additions are installed and other OS-specific virtual machine
|
---|
7711 | properties.
|
---|
7712 | </desc>
|
---|
7713 |
|
---|
7714 | <attribute name="OSTypeId" type="wstring" readonly="yes">
|
---|
7715 | <desc>
|
---|
7716 | Identifier of the Guest OS type as reported by the Guest
|
---|
7717 | Additions.
|
---|
7718 | You may use <link to="IVirtualBox::getGuestOSType"/> to obtain
|
---|
7719 | an IGuestOSType object representing details about the given
|
---|
7720 | Guest OS type.
|
---|
7721 | <note>
|
---|
7722 | If Guest Additions are not installed, this value will be
|
---|
7723 | the same as <link to="IMachine::OSTypeId"/>.
|
---|
7724 | </note>
|
---|
7725 | </desc>
|
---|
7726 | </attribute>
|
---|
7727 |
|
---|
7728 | <attribute name="additionsRunLevel" type="AdditionsRunLevelType" readonly="yes">
|
---|
7729 | <desc>
|
---|
7730 | Current run level of the Guest Additions.
|
---|
7731 | </desc>
|
---|
7732 | </attribute>
|
---|
7733 |
|
---|
7734 | <attribute name="additionsVersion" type="wstring" readonly="yes">
|
---|
7735 | <desc>
|
---|
7736 | Version of the Guest Additions including the revision (3 decimal numbers
|
---|
7737 | separated by dots + revision number) installed on the guest or empty
|
---|
7738 | when the Additions are not installed.
|
---|
7739 | </desc>
|
---|
7740 | </attribute>
|
---|
7741 |
|
---|
7742 | <attribute name="supportsSeamless" type="boolean" readonly="yes">
|
---|
7743 | <desc>
|
---|
7744 | Flag whether seamless guest display rendering (seamless desktop
|
---|
7745 | integration) is supported.
|
---|
7746 | </desc>
|
---|
7747 | </attribute>
|
---|
7748 |
|
---|
7749 | <attribute name="supportsGraphics" type="boolean" readonly="yes">
|
---|
7750 | <desc>
|
---|
7751 | Flag whether the guest is in graphics mode. If it is not, then
|
---|
7752 | seamless rendering will not work, resize hints are not immediately
|
---|
7753 | acted on and guest display resizes are probably not initiated by
|
---|
7754 | the guest additions.
|
---|
7755 | </desc>
|
---|
7756 | </attribute>
|
---|
7757 |
|
---|
7758 | <attribute name="memoryBalloonSize" type="unsigned long">
|
---|
7759 | <desc>Guest system memory balloon size in megabytes (transient property).</desc>
|
---|
7760 | </attribute>
|
---|
7761 |
|
---|
7762 | <attribute name="statisticsUpdateInterval" type="unsigned long">
|
---|
7763 | <desc>Interval to update guest statistics in seconds.</desc>
|
---|
7764 | </attribute>
|
---|
7765 |
|
---|
7766 | <method name="internalGetStatistics">
|
---|
7767 | <desc>
|
---|
7768 | Internal method; do not use as it might change at any time
|
---|
7769 | </desc>
|
---|
7770 | <param name="cpuUser" type="unsigned long" dir="out">
|
---|
7771 | <desc>Percentage of processor time spent in user mode as seen by the guest</desc>
|
---|
7772 | </param>
|
---|
7773 | <param name="cpuKernel" type="unsigned long" dir="out">
|
---|
7774 | <desc>Percentage of processor time spent in kernel mode as seen by the guest</desc>
|
---|
7775 | </param>
|
---|
7776 | <param name="cpuIdle" type="unsigned long" dir="out">
|
---|
7777 | <desc>Percentage of processor time spent idling as seen by the guest</desc>
|
---|
7778 | </param>
|
---|
7779 | <param name="memTotal" type="unsigned long" dir="out">
|
---|
7780 | <desc>Total amount of physical guest RAM</desc>
|
---|
7781 | </param>
|
---|
7782 | <param name="memFree" type="unsigned long" dir="out">
|
---|
7783 | <desc>Free amount of physical guest RAM</desc>
|
---|
7784 | </param>
|
---|
7785 | <param name="memBalloon" type="unsigned long" dir="out">
|
---|
7786 | <desc>Amount of ballooned physical guest RAM</desc>
|
---|
7787 | </param>
|
---|
7788 | <param name="memShared" type="unsigned long" dir="out">
|
---|
7789 | <desc>Amount of shared physical guest RAM</desc>
|
---|
7790 | </param>
|
---|
7791 | <param name="memCache" type="unsigned long" dir="out">
|
---|
7792 | <desc>Total amount of guest (disk) cache memory</desc>
|
---|
7793 | </param>
|
---|
7794 | <param name="pagedTotal" type="unsigned long" dir="out">
|
---|
7795 | <desc>Total amount of space in the page file</desc>
|
---|
7796 | </param>
|
---|
7797 | <param name="memAllocTotal" type="unsigned long" dir="out">
|
---|
7798 | <desc>Total amount of memory allocated by the hypervisor</desc>
|
---|
7799 | </param>
|
---|
7800 | <param name="memFreeTotal" type="unsigned long" dir="out">
|
---|
7801 | <desc>Total amount of free memory available in the hypervisor</desc>
|
---|
7802 | </param>
|
---|
7803 | <param name="memBalloonTotal" type="unsigned long" dir="out">
|
---|
7804 | <desc>Total amount of memory ballooned by the hypervisor</desc>
|
---|
7805 | </param>
|
---|
7806 | <param name="memSharedTotal" type="unsigned long" dir="out">
|
---|
7807 | <desc>Total amount of shared memory in the hypervisor</desc>
|
---|
7808 | </param>
|
---|
7809 | </method>
|
---|
7810 |
|
---|
7811 | <method name="getAdditionsStatus">
|
---|
7812 | <desc>
|
---|
7813 | Retrieve the current status of a certain Guest Additions run level.
|
---|
7814 |
|
---|
7815 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
7816 | Wrong status level specified.
|
---|
7817 | </result>
|
---|
7818 |
|
---|
7819 | </desc>
|
---|
7820 | <param name="level" type="AdditionsRunLevelType" dir="in">
|
---|
7821 | <desc>Status level to check</desc>
|
---|
7822 | </param>
|
---|
7823 | <param name="active" type="boolean" dir="return">
|
---|
7824 | <desc>Flag whether the status level has been reached or not</desc>
|
---|
7825 | </param>
|
---|
7826 | </method>
|
---|
7827 |
|
---|
7828 | <method name="setCredentials">
|
---|
7829 | <desc>
|
---|
7830 | Store login credentials that can be queried by guest operating
|
---|
7831 | systems with Additions installed. The credentials are transient
|
---|
7832 | to the session and the guest may also choose to erase them. Note
|
---|
7833 | that the caller cannot determine whether the guest operating system
|
---|
7834 | has queried or made use of the credentials.
|
---|
7835 |
|
---|
7836 | <result name="VBOX_E_VM_ERROR">
|
---|
7837 | VMM device is not available.
|
---|
7838 | </result>
|
---|
7839 |
|
---|
7840 | </desc>
|
---|
7841 | <param name="userName" type="wstring" dir="in">
|
---|
7842 | <desc>User name string, can be empty</desc>
|
---|
7843 | </param>
|
---|
7844 | <param name="password" type="wstring" dir="in">
|
---|
7845 | <desc>Password string, can be empty</desc>
|
---|
7846 | </param>
|
---|
7847 | <param name="domain" type="wstring" dir="in">
|
---|
7848 | <desc>Domain name (guest logon scheme specific), can be empty</desc>
|
---|
7849 | </param>
|
---|
7850 | <param name="allowInteractiveLogon" type="boolean" dir="in">
|
---|
7851 | <desc>
|
---|
7852 | Flag whether the guest should alternatively allow the user to
|
---|
7853 | interactively specify different credentials. This flag might
|
---|
7854 | not be supported by all versions of the Additions.
|
---|
7855 | </desc>
|
---|
7856 | </param>
|
---|
7857 | </method>
|
---|
7858 |
|
---|
7859 | <method name="executeProcess">
|
---|
7860 | <desc>
|
---|
7861 | Executes an existing program inside the guest VM.
|
---|
7862 |
|
---|
7863 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7864 | Could not execute process.
|
---|
7865 | </result>
|
---|
7866 |
|
---|
7867 | </desc>
|
---|
7868 | <param name="execName" type="wstring" dir="in">
|
---|
7869 | <desc>
|
---|
7870 | Full path name of the command to execute on the guest; the
|
---|
7871 | commands has to exists in the guest VM in order to be executed.
|
---|
7872 | </desc>
|
---|
7873 | </param>
|
---|
7874 | <param name="flags" type="unsigned long" dir="in">
|
---|
7875 | <desc>
|
---|
7876 | Execution flags - currently not supported and therefore
|
---|
7877 | has to be set to 0.
|
---|
7878 | </desc>
|
---|
7879 | </param>
|
---|
7880 | <param name="arguments" type="wstring" safearray="yes" dir="in">
|
---|
7881 | <desc>
|
---|
7882 | Array of arguments passed to the execution command.
|
---|
7883 | </desc>
|
---|
7884 | </param>
|
---|
7885 | <param name="environment" type="wstring" safearray="yes" dir="in">
|
---|
7886 | <desc>
|
---|
7887 | Environment variables that can be set while the command is being
|
---|
7888 | executed, in form of "NAME=VALUE"; one pair per entry. To unset a
|
---|
7889 | variable just set its name ("NAME") without a value.
|
---|
7890 | </desc>
|
---|
7891 | </param>
|
---|
7892 | <param name="userName" type="wstring" dir="in">
|
---|
7893 | <desc>
|
---|
7894 | User name under which the command will be executed; has to exist
|
---|
7895 | and have the appropriate rights to execute programs in the VM.
|
---|
7896 | </desc>
|
---|
7897 | </param>
|
---|
7898 | <param name="password" type="wstring" dir="in">
|
---|
7899 | <desc>
|
---|
7900 | Password of the user account specified.
|
---|
7901 | </desc>
|
---|
7902 | </param>
|
---|
7903 | <param name="timeoutMS" type="unsigned long" dir="in">
|
---|
7904 | <desc>
|
---|
7905 | The maximum timeout value (in msec) to wait for finished program
|
---|
7906 | execution. Pass 0 for an infinite timeout.
|
---|
7907 | </desc>
|
---|
7908 | </param>
|
---|
7909 | <param name="pid" type="unsigned long" dir="out">
|
---|
7910 | <desc>
|
---|
7911 | The PID (process ID) of the started command for later reference.
|
---|
7912 | </desc>
|
---|
7913 | </param>
|
---|
7914 | <param name="progress" type="IProgress" dir="return">
|
---|
7915 | <desc>Progress object to track the operation completion.</desc>
|
---|
7916 | </param>
|
---|
7917 | </method>
|
---|
7918 |
|
---|
7919 | <method name="getProcessOutput">
|
---|
7920 | <desc>
|
---|
7921 | Retrieves output of a formerly started process.
|
---|
7922 |
|
---|
7923 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7924 | Could not retrieve output.
|
---|
7925 | </result>
|
---|
7926 |
|
---|
7927 | </desc>
|
---|
7928 | <param name="pid" type="unsigned long" dir="in">
|
---|
7929 | <desc>
|
---|
7930 | Process id returned by earlier executeProcess() call.
|
---|
7931 | </desc>
|
---|
7932 | </param>
|
---|
7933 | <param name="flags" type="unsigned long" dir="in">
|
---|
7934 | <desc>
|
---|
7935 | Flags describing which output to retrieve.
|
---|
7936 | </desc>
|
---|
7937 | </param>
|
---|
7938 | <param name="timeoutMS" type="unsigned long" dir="in">
|
---|
7939 | <desc>
|
---|
7940 | The maximum timeout value (in msec) to wait for output
|
---|
7941 | data. Pass 0 for an infinite timeout.
|
---|
7942 | </desc>
|
---|
7943 | </param>
|
---|
7944 | <param name="size" type="long long" dir="in">
|
---|
7945 | <desc>
|
---|
7946 | Size in bytes to read in the buffer.
|
---|
7947 | </desc>
|
---|
7948 | </param>
|
---|
7949 | <param name="data" type="octet" dir="return" safearray="yes">
|
---|
7950 | <desc>
|
---|
7951 | Buffer for retrieving the actual output. A data size of 0 means end of file
|
---|
7952 | if the requested size was not 0. This is the unprocessed
|
---|
7953 | output data, i.e. the line ending style depends on the platform of
|
---|
7954 | the system the server is running on.
|
---|
7955 | </desc>
|
---|
7956 | </param>
|
---|
7957 | </method>
|
---|
7958 |
|
---|
7959 | <method name="getProcessStatus">
|
---|
7960 | <desc>
|
---|
7961 | Retrieves status, exit code and the exit reason of a formerly started process.
|
---|
7962 |
|
---|
7963 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7964 | Process with specified PID was not found.
|
---|
7965 | </result>
|
---|
7966 |
|
---|
7967 | </desc>
|
---|
7968 | <param name="pid" type="unsigned long" dir="in">
|
---|
7969 | <desc>
|
---|
7970 | Process id returned by earlier executeProcess() call.
|
---|
7971 | </desc>
|
---|
7972 | </param>
|
---|
7973 | <param name="exitcode" type="unsigned long" dir="out">
|
---|
7974 | <desc>
|
---|
7975 | The exit code (if available).
|
---|
7976 | </desc>
|
---|
7977 | </param>
|
---|
7978 | <param name="flags" type="unsigned long" dir="out">
|
---|
7979 | <desc>
|
---|
7980 | Additional flags of process status. Not used at the moment and
|
---|
7981 | must be set to 0.
|
---|
7982 | </desc>
|
---|
7983 | </param>
|
---|
7984 | <param name="reason" type="unsigned long" dir="return">
|
---|
7985 | <desc>
|
---|
7986 | The current process status.
|
---|
7987 | </desc>
|
---|
7988 | </param>
|
---|
7989 | </method>
|
---|
7990 |
|
---|
7991 | <method name="copyToGuest">
|
---|
7992 | <desc>
|
---|
7993 | Copies files/directories from host to the guest.
|
---|
7994 |
|
---|
7995 | <result name="VBOX_E_IPRT_ERROR">
|
---|
7996 | Error while copying.
|
---|
7997 | </result>
|
---|
7998 |
|
---|
7999 | </desc>
|
---|
8000 | <param name="source" type="wstring" dir="in">
|
---|
8001 | <desc>
|
---|
8002 | Source file on the host to copy.
|
---|
8003 | </desc>
|
---|
8004 | </param>
|
---|
8005 | <param name="dest" type="wstring" dir="in">
|
---|
8006 | <desc>
|
---|
8007 | Destination path on the guest.
|
---|
8008 | </desc>
|
---|
8009 | </param>
|
---|
8010 | <param name="userName" type="wstring" dir="in">
|
---|
8011 | <desc>
|
---|
8012 | User name under which the copy command will be executed; the
|
---|
8013 | user has to exist and have the appropriate rights to write to
|
---|
8014 | the destination path.
|
---|
8015 | </desc>
|
---|
8016 | </param>
|
---|
8017 | <param name="password" type="wstring" dir="in">
|
---|
8018 | <desc>
|
---|
8019 | Password of the user account specified.
|
---|
8020 | </desc>
|
---|
8021 | </param>
|
---|
8022 | <param name="flags" type="unsigned long" dir="in">
|
---|
8023 | <desc>
|
---|
8024 | Copy flags.
|
---|
8025 | </desc>
|
---|
8026 | </param>
|
---|
8027 | <param name="progress" type="IProgress" dir="return">
|
---|
8028 | <desc>Progress object to track the operation completion.</desc>
|
---|
8029 | </param>
|
---|
8030 | </method>
|
---|
8031 |
|
---|
8032 | <method name="setProcessInput">
|
---|
8033 | <desc>
|
---|
8034 | Sends input into a formerly started process.
|
---|
8035 |
|
---|
8036 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8037 | Could not send input.
|
---|
8038 | </result>
|
---|
8039 |
|
---|
8040 | </desc>
|
---|
8041 | <param name="pid" type="unsigned long" dir="in">
|
---|
8042 | <desc>
|
---|
8043 | Process id returned by earlier executeProcess() call.
|
---|
8044 | </desc>
|
---|
8045 | </param>
|
---|
8046 | <param name="flags" type="unsigned long" dir="in">
|
---|
8047 | <desc>
|
---|
8048 | Not used, must be set to zero.
|
---|
8049 | </desc>
|
---|
8050 | </param>
|
---|
8051 | <param name="data" type="octet" dir="in" safearray="yes">
|
---|
8052 | <desc>
|
---|
8053 | Buffer of input data to send to the started process to.
|
---|
8054 | </desc>
|
---|
8055 | </param>
|
---|
8056 | <param name="written" type="unsigned long" dir="return">
|
---|
8057 | <desc>
|
---|
8058 | Number of bytes written.
|
---|
8059 | </desc>
|
---|
8060 | </param>
|
---|
8061 | </method>
|
---|
8062 |
|
---|
8063 | <method name="updateGuestAdditions">
|
---|
8064 | <desc>
|
---|
8065 | Updates already installed Guest Additions in a VM
|
---|
8066 | (Windows guests only).
|
---|
8067 |
|
---|
8068 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8069 | Error while updating.
|
---|
8070 | </result>
|
---|
8071 |
|
---|
8072 | </desc>
|
---|
8073 | <param name="source" type="wstring" dir="in">
|
---|
8074 | <desc>
|
---|
8075 | Path to the Guest Additions .ISO file to use for the upate.
|
---|
8076 | </desc>
|
---|
8077 | </param>
|
---|
8078 | <param name="flags" type="unsigned long" dir="in">
|
---|
8079 | <desc>
|
---|
8080 | Additional flags for update process. Not used at the moment and
|
---|
8081 | must be set to 0.
|
---|
8082 | </desc>
|
---|
8083 | </param>
|
---|
8084 | <param name="progress" type="IProgress" dir="return">
|
---|
8085 | <desc>Progress object to track the operation completion.</desc>
|
---|
8086 | </param>
|
---|
8087 | </method>
|
---|
8088 |
|
---|
8089 | </interface>
|
---|
8090 |
|
---|
8091 |
|
---|
8092 | <!--
|
---|
8093 | // IProgress
|
---|
8094 | /////////////////////////////////////////////////////////////////////////
|
---|
8095 | -->
|
---|
8096 |
|
---|
8097 | <interface
|
---|
8098 | name="IProgress" extends="$unknown"
|
---|
8099 | uuid="A163C98F-8635-4AA8-B770-A9941737F3EF"
|
---|
8100 | wsmap="managed"
|
---|
8101 | >
|
---|
8102 | <desc>
|
---|
8103 | The IProgress interface is used to track and control
|
---|
8104 | asynchronous tasks within VirtualBox.
|
---|
8105 |
|
---|
8106 | An instance of this is returned every time VirtualBox starts
|
---|
8107 | an asynchronous task (in other words, a separate thread) which
|
---|
8108 | continues to run after a method call returns. For example,
|
---|
8109 | <link to="IConsole::saveState" />, which saves the state of
|
---|
8110 | a running virtual machine, can take a long time to complete.
|
---|
8111 | To be able to display a progress bar, a user interface such as
|
---|
8112 | the VirtualBox graphical user interface can use the IProgress
|
---|
8113 | object returned by that method.
|
---|
8114 |
|
---|
8115 | Note that IProgress is a "read-only" interface in the sense
|
---|
8116 | that only the VirtualBox internals behind the Main API can
|
---|
8117 | create and manipulate progress objects, whereas client code
|
---|
8118 | can only use the IProgress object to monitor a task's
|
---|
8119 | progress and, if <link to="#cancelable" /> is @c true,
|
---|
8120 | cancel the task by calling <link to="#cancel" />.
|
---|
8121 |
|
---|
8122 | A task represented by IProgress consists of either one or
|
---|
8123 | several sub-operations that run sequentially, one by one (see
|
---|
8124 | <link to="#operation" /> and <link to="#operationCount" />).
|
---|
8125 | Every operation is identified by a number (starting from 0)
|
---|
8126 | and has a separate description.
|
---|
8127 |
|
---|
8128 | You can find the individual percentage of completion of the current
|
---|
8129 | operation in <link to="#operationPercent" /> and the
|
---|
8130 | percentage of completion of the task as a whole
|
---|
8131 | in <link to="#percent" />.
|
---|
8132 |
|
---|
8133 | Similarly, you can wait for the completion of a particular
|
---|
8134 | operation via <link to="#waitForOperationCompletion" /> or
|
---|
8135 | for the completion of the whole task via
|
---|
8136 | <link to="#waitForCompletion" />.
|
---|
8137 | </desc>
|
---|
8138 |
|
---|
8139 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
8140 | <desc>ID of the task.</desc>
|
---|
8141 | </attribute>
|
---|
8142 |
|
---|
8143 | <attribute name="description" type="wstring" readonly="yes">
|
---|
8144 | <desc>Description of the task.</desc>
|
---|
8145 | </attribute>
|
---|
8146 |
|
---|
8147 | <attribute name="initiator" type="$unknown" readonly="yes">
|
---|
8148 | <desc>Initiator of the task.</desc>
|
---|
8149 | </attribute>
|
---|
8150 |
|
---|
8151 | <attribute name="cancelable" type="boolean" readonly="yes">
|
---|
8152 | <desc>Whether the task can be interrupted.</desc>
|
---|
8153 | </attribute>
|
---|
8154 |
|
---|
8155 | <attribute name="percent" type="unsigned long" readonly="yes">
|
---|
8156 | <desc>
|
---|
8157 | Current progress value of the task as a whole, in percent.
|
---|
8158 | This value depends on how many operations are already complete.
|
---|
8159 | Returns 100 if <link to="#completed" /> is @c true.
|
---|
8160 | </desc>
|
---|
8161 | </attribute>
|
---|
8162 |
|
---|
8163 | <attribute name="timeRemaining" type="long" readonly="yes">
|
---|
8164 | <desc>
|
---|
8165 | Estimated remaining time until the task completes, in
|
---|
8166 | seconds. Returns 0 once the task has completed; returns -1
|
---|
8167 | if the remaining time cannot be computed, in particular if
|
---|
8168 | the current progress is 0.
|
---|
8169 |
|
---|
8170 | Even if a value is returned, the estimate will be unreliable
|
---|
8171 | for low progress values. It will become more reliable as the
|
---|
8172 | task progresses; it is not recommended to display an ETA
|
---|
8173 | before at least 20% of a task have completed.
|
---|
8174 | </desc>
|
---|
8175 | </attribute>
|
---|
8176 |
|
---|
8177 | <attribute name="completed" type="boolean" readonly="yes">
|
---|
8178 | <desc>Whether the task has been completed.</desc>
|
---|
8179 | </attribute>
|
---|
8180 |
|
---|
8181 | <attribute name="canceled" type="boolean" readonly="yes">
|
---|
8182 | <desc>Whether the task has been canceled.</desc>
|
---|
8183 | </attribute>
|
---|
8184 |
|
---|
8185 | <attribute name="resultCode" type="long" readonly="yes">
|
---|
8186 | <desc>
|
---|
8187 | Result code of the progress task.
|
---|
8188 | Valid only if <link to="#completed"/> is @c true.
|
---|
8189 | </desc>
|
---|
8190 | </attribute>
|
---|
8191 |
|
---|
8192 | <attribute name="errorInfo" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
8193 | <desc>
|
---|
8194 | Extended information about the unsuccessful result of the
|
---|
8195 | progress operation. May be @c null if no extended information
|
---|
8196 | is available.
|
---|
8197 | Valid only if <link to="#completed"/> is @c true and
|
---|
8198 | <link to="#resultCode"/> indicates a failure.
|
---|
8199 | </desc>
|
---|
8200 | </attribute>
|
---|
8201 |
|
---|
8202 | <attribute name="operationCount" type="unsigned long" readonly="yes">
|
---|
8203 | <desc>
|
---|
8204 | Number of sub-operations this task is divided into.
|
---|
8205 | Every task consists of at least one suboperation.
|
---|
8206 | </desc>
|
---|
8207 | </attribute>
|
---|
8208 |
|
---|
8209 | <attribute name="operation" type="unsigned long" readonly="yes">
|
---|
8210 | <desc>Number of the sub-operation being currently executed.</desc>
|
---|
8211 | </attribute>
|
---|
8212 |
|
---|
8213 | <attribute name="operationDescription" type="wstring" readonly="yes">
|
---|
8214 | <desc>
|
---|
8215 | Description of the sub-operation being currently executed.
|
---|
8216 | </desc>
|
---|
8217 | </attribute>
|
---|
8218 |
|
---|
8219 | <attribute name="operationPercent" type="unsigned long" readonly="yes">
|
---|
8220 | <desc>Progress value of the current sub-operation only, in percent.</desc>
|
---|
8221 | </attribute>
|
---|
8222 |
|
---|
8223 | <attribute name="operationWeight" type="unsigned long" readonly="yes">
|
---|
8224 | <desc>Weight value of the current sub-operation only.</desc>
|
---|
8225 | </attribute>
|
---|
8226 |
|
---|
8227 | <attribute name="timeout" type="unsigned long">
|
---|
8228 | <desc>
|
---|
8229 | When non-zero, this specifies the number of milliseconds after which
|
---|
8230 | the operation will automatically be canceled. This can only be set on
|
---|
8231 | cancelable objects.
|
---|
8232 | </desc>
|
---|
8233 | </attribute>
|
---|
8234 |
|
---|
8235 | <method name="setCurrentOperationProgress">
|
---|
8236 | <desc>Internal method, not to be called externally.</desc>
|
---|
8237 | <param name="percent" type="unsigned long" dir="in" />
|
---|
8238 | </method>
|
---|
8239 | <method name="setNextOperation">
|
---|
8240 | <desc>Internal method, not to be called externally.</desc>
|
---|
8241 | <param name="nextOperationDescription" type="wstring" dir="in" />
|
---|
8242 | <param name="nextOperationsWeight" type="unsigned long" dir="in" />
|
---|
8243 | </method>
|
---|
8244 |
|
---|
8245 | <method name="waitForCompletion">
|
---|
8246 | <desc>
|
---|
8247 | Waits until the task is done (including all sub-operations)
|
---|
8248 | with a given timeout in milliseconds; specify -1 for an indefinite wait.
|
---|
8249 |
|
---|
8250 | Note that the VirtualBox/XPCOM/COM/native event queues of the calling
|
---|
8251 | thread are not processed while waiting. Neglecting event queues may
|
---|
8252 | have dire consequences (degrade performance, resource hogs,
|
---|
8253 | deadlocks, etc.), this is specially so for the main thread on
|
---|
8254 | platforms using XPCOM. Callers are adviced wait for short periods
|
---|
8255 | and service their event queues between calls, or to create a worker
|
---|
8256 | thread to do the waiting.
|
---|
8257 |
|
---|
8258 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8259 | Failed to wait for task completion.
|
---|
8260 | </result>
|
---|
8261 | </desc>
|
---|
8262 |
|
---|
8263 | <param name="timeout" type="long" dir="in">
|
---|
8264 | <desc>
|
---|
8265 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
8266 | </desc>
|
---|
8267 | </param>
|
---|
8268 | </method>
|
---|
8269 |
|
---|
8270 | <method name="waitForOperationCompletion">
|
---|
8271 | <desc>
|
---|
8272 | Waits until the given operation is done with a given timeout in
|
---|
8273 | milliseconds; specify -1 for an indefinite wait.
|
---|
8274 |
|
---|
8275 | See <link to="#waitForCompletion"> for event queue considerations.</link>
|
---|
8276 |
|
---|
8277 | <result name="VBOX_E_IPRT_ERROR">
|
---|
8278 | Failed to wait for operation completion.
|
---|
8279 | </result>
|
---|
8280 |
|
---|
8281 | </desc>
|
---|
8282 | <param name="operation" type="unsigned long" dir="in">
|
---|
8283 | <desc>
|
---|
8284 | Number of the operation to wait for.
|
---|
8285 | Must be less than <link to="#operationCount"/>.
|
---|
8286 | </desc>
|
---|
8287 | </param>
|
---|
8288 | <param name="timeout" type="long" dir="in">
|
---|
8289 | <desc>
|
---|
8290 | Maximum time in milliseconds to wait or -1 to wait indefinitely.
|
---|
8291 | </desc>
|
---|
8292 | </param>
|
---|
8293 | </method>
|
---|
8294 |
|
---|
8295 | <method name="cancel">
|
---|
8296 | <desc>
|
---|
8297 | Cancels the task.
|
---|
8298 | <note>
|
---|
8299 | If <link to="#cancelable"/> is @c false, then this method will fail.
|
---|
8300 | </note>
|
---|
8301 |
|
---|
8302 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
8303 | Operation cannot be canceled.
|
---|
8304 | </result>
|
---|
8305 |
|
---|
8306 | </desc>
|
---|
8307 | </method>
|
---|
8308 |
|
---|
8309 | </interface>
|
---|
8310 |
|
---|
8311 | <!--
|
---|
8312 | // ISnapshot
|
---|
8313 | /////////////////////////////////////////////////////////////////////////
|
---|
8314 | -->
|
---|
8315 |
|
---|
8316 | <interface
|
---|
8317 | name="ISnapshot" extends="$unknown"
|
---|
8318 | uuid="1a2d0551-58a4-4107-857e-ef414fc42ffc"
|
---|
8319 | wsmap="managed"
|
---|
8320 | >
|
---|
8321 | <desc>
|
---|
8322 | The ISnapshot interface represents a snapshot of the virtual
|
---|
8323 | machine.
|
---|
8324 |
|
---|
8325 | Together with the differencing media that are created
|
---|
8326 | when a snapshot is taken, a machine can be brought back to
|
---|
8327 | the exact state it was in when the snapshot was taken.
|
---|
8328 |
|
---|
8329 | The ISnapshot interface has no methods, only attributes; snapshots
|
---|
8330 | are controlled through methods of the <link to="IConsole" /> interface
|
---|
8331 | which also manage the media associated with the snapshot.
|
---|
8332 | The following operations exist:
|
---|
8333 |
|
---|
8334 | <ul>
|
---|
8335 | <li><link to="IConsole::takeSnapshot"/> creates a new snapshot
|
---|
8336 | by creating new, empty differencing images for the machine's
|
---|
8337 | media and saving the VM settings and (if the VM is running)
|
---|
8338 | the current VM state in the snapshot.
|
---|
8339 |
|
---|
8340 | The differencing images will then receive all data written to
|
---|
8341 | the machine's media, while their parent (base) images
|
---|
8342 | remain unmodified after the snapshot has been taken (see
|
---|
8343 | <link to="IMedium" /> for details about differencing images).
|
---|
8344 | This simplifies restoring a machine to the state of a snapshot:
|
---|
8345 | only the differencing images need to be deleted.
|
---|
8346 |
|
---|
8347 | The current machine state is not changed by taking a snapshot.
|
---|
8348 | If the machine is running, it will resume execution after the
|
---|
8349 | snapshot has been taken. After calling this,
|
---|
8350 | <link to="IMachine::currentSnapshot" /> is set to the snapshot
|
---|
8351 | just created.
|
---|
8352 | </li>
|
---|
8353 |
|
---|
8354 | <li><link to="IConsole::restoreSnapshot"/> resets a machine to
|
---|
8355 | the state of a previous snapshot by deleting the differencing
|
---|
8356 | image of each of the machine's media and setting the machine's
|
---|
8357 | settings and state to the state that was saved in the snapshot (if any).
|
---|
8358 |
|
---|
8359 | This destroys the machine's current state. After calling this,
|
---|
8360 | <link to="IMachine::currentSnapshot" /> is set to the snapshot that was
|
---|
8361 | restored.
|
---|
8362 | </li>
|
---|
8363 |
|
---|
8364 | <li><link to="IConsole::deleteSnapshot"/> deletes a snapshot
|
---|
8365 | without affecting the current machine state.
|
---|
8366 |
|
---|
8367 | This does not change the current machine state, but instead frees the
|
---|
8368 | resources allocated when the snapshot was taken: the settings and machine
|
---|
8369 | state file are deleted (if any), and the snapshot's differencing image for
|
---|
8370 | each of the machine's media gets merged with its parent image.
|
---|
8371 |
|
---|
8372 | Neither the current machine state nor other snapshots are affected
|
---|
8373 | by this operation, except that parent media will be modified
|
---|
8374 | to contain the disk data associated with the snapshot being deleted.
|
---|
8375 |
|
---|
8376 | When deleting the current snapshot, the <link to="IMachine::currentSnapshot" />
|
---|
8377 | attribute is set to the current snapshot's parent or NULL if it
|
---|
8378 | has no parent. Otherwise the attribute is unchanged.
|
---|
8379 | </li>
|
---|
8380 | </ul>
|
---|
8381 |
|
---|
8382 | Each snapshot contains the settings of the virtual machine (hardware
|
---|
8383 | configuration etc.). In addition, if the machine was running when the
|
---|
8384 | snapshot was taken (<link to="IMachine::state"/> is <link to="MachineState_Running"/>),
|
---|
8385 | the current VM state is saved in the snapshot (similarly to what happens
|
---|
8386 | when a VM's state is saved). The snapshot is then said to
|
---|
8387 | be <i>online</i> because when restoring it, the VM will be running.
|
---|
8388 |
|
---|
8389 | If the machine is saved (<link to="MachineState_Saved"/>), the snapshot
|
---|
8390 | receives a copy of the execution state file (<link to="IMachine::stateFilePath"/>).
|
---|
8391 |
|
---|
8392 | Otherwise, if the machine was not running (<link to="MachineState_PoweredOff"/>
|
---|
8393 | or <link to="MachineState_Aborted"/>), the snapshot is <i>offline</i>;
|
---|
8394 | it then contains a so-called "zero execution state", representing a
|
---|
8395 | machine that is powered off.
|
---|
8396 | </desc>
|
---|
8397 |
|
---|
8398 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
8399 | <desc>UUID of the snapshot.</desc>
|
---|
8400 | </attribute>
|
---|
8401 |
|
---|
8402 | <attribute name="name" type="wstring">
|
---|
8403 | <desc>Short name of the snapshot.</desc>
|
---|
8404 | </attribute>
|
---|
8405 |
|
---|
8406 | <attribute name="description" type="wstring">
|
---|
8407 | <desc>Optional description of the snapshot.</desc>
|
---|
8408 | </attribute>
|
---|
8409 |
|
---|
8410 | <attribute name="timeStamp" type="long long" readonly="yes">
|
---|
8411 | <desc>
|
---|
8412 | Time stamp of the snapshot, in milliseconds since 1970-01-01 UTC.
|
---|
8413 | </desc>
|
---|
8414 | </attribute>
|
---|
8415 |
|
---|
8416 | <attribute name="online" type="boolean" readonly="yes">
|
---|
8417 | <desc>
|
---|
8418 | @c true if this snapshot is an online snapshot and @c false otherwise.
|
---|
8419 |
|
---|
8420 | When this attribute is @c true, the
|
---|
8421 | <link to="IMachine::stateFilePath"/> attribute of the
|
---|
8422 | <link to="#machine"/> object associated with this snapshot
|
---|
8423 | will point to the saved state file. Otherwise, it will be
|
---|
8424 | an empty string.
|
---|
8425 | </desc>
|
---|
8426 | </attribute>
|
---|
8427 |
|
---|
8428 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
8429 | <desc>
|
---|
8430 | Virtual machine this snapshot is taken on. This object
|
---|
8431 | stores all settings the machine had when taking this snapshot.
|
---|
8432 | <note>
|
---|
8433 | The returned machine object is immutable, i.e. no
|
---|
8434 | any settings can be changed.
|
---|
8435 | </note>
|
---|
8436 | </desc>
|
---|
8437 | </attribute>
|
---|
8438 |
|
---|
8439 | <attribute name="parent" type="ISnapshot" readonly="yes">
|
---|
8440 | <desc>
|
---|
8441 | Parent snapshot (a snapshot this one is based on), or
|
---|
8442 | @c null if the snapshot has no parent (i.e. is the first snapshot).
|
---|
8443 | </desc>
|
---|
8444 | </attribute>
|
---|
8445 |
|
---|
8446 | <attribute name="children" type="ISnapshot" readonly="yes" safearray="yes">
|
---|
8447 | <desc>
|
---|
8448 | Child snapshots (all snapshots having this one as a parent).
|
---|
8449 | </desc>
|
---|
8450 | </attribute>
|
---|
8451 |
|
---|
8452 | </interface>
|
---|
8453 |
|
---|
8454 |
|
---|
8455 | <!--
|
---|
8456 | // IMedium
|
---|
8457 | /////////////////////////////////////////////////////////////////////////
|
---|
8458 | -->
|
---|
8459 |
|
---|
8460 | <enum
|
---|
8461 | name="MediumState"
|
---|
8462 | uuid="ef41e980-e012-43cd-9dea-479d4ef14d13"
|
---|
8463 | >
|
---|
8464 | <desc>
|
---|
8465 | Virtual medium state.
|
---|
8466 | <see>IMedium</see>
|
---|
8467 | </desc>
|
---|
8468 |
|
---|
8469 | <const name="NotCreated" value="0">
|
---|
8470 | <desc>
|
---|
8471 | Associated medium storage does not exist (either was not created yet or
|
---|
8472 | was deleted).
|
---|
8473 | </desc>
|
---|
8474 | </const>
|
---|
8475 | <const name="Created" value="1">
|
---|
8476 | <desc>
|
---|
8477 | Associated storage exists and accessible; this gets set if the
|
---|
8478 | accessibility check performed by <link to="IMedium::refreshState" />
|
---|
8479 | was successful.
|
---|
8480 | </desc>
|
---|
8481 | </const>
|
---|
8482 | <const name="LockedRead" value="2">
|
---|
8483 | <desc>
|
---|
8484 | Medium is locked for reading (see <link to="IMedium::lockRead"/>),
|
---|
8485 | no data modification is possible.
|
---|
8486 | </desc>
|
---|
8487 | </const>
|
---|
8488 | <const name="LockedWrite" value="3">
|
---|
8489 | <desc>
|
---|
8490 | Medium is locked for writing (see <link to="IMedium::lockWrite"/>),
|
---|
8491 | no concurrent data reading or modification is possible.
|
---|
8492 | </desc>
|
---|
8493 | </const>
|
---|
8494 | <const name="Inaccessible" value="4">
|
---|
8495 | <desc>
|
---|
8496 | Medium accessibility check (see <link to="IMedium::refreshState" />) has
|
---|
8497 | not yet been performed, or else, associated medium storage is not
|
---|
8498 | accessible. In the first case, <link to="IMedium::lastAccessError"/>
|
---|
8499 | is empty, in the second case, it describes the error that occurred.
|
---|
8500 | </desc>
|
---|
8501 | </const>
|
---|
8502 | <const name="Creating" value="5">
|
---|
8503 | <desc>
|
---|
8504 | Associated medium storage is being created.
|
---|
8505 | </desc>
|
---|
8506 | </const>
|
---|
8507 | <const name="Deleting" value="6">
|
---|
8508 | <desc>
|
---|
8509 | Associated medium storage is being deleted.
|
---|
8510 | </desc>
|
---|
8511 | </const>
|
---|
8512 | </enum>
|
---|
8513 |
|
---|
8514 | <enum
|
---|
8515 | name="MediumType"
|
---|
8516 | uuid="19388a99-8e70-4bd4-9a95-90cbc513ef6d"
|
---|
8517 | >
|
---|
8518 | <desc>
|
---|
8519 | Virtual medium type.
|
---|
8520 | <see>IMedium</see>
|
---|
8521 | </desc>
|
---|
8522 |
|
---|
8523 | <const name="Normal" value="0">
|
---|
8524 | <desc>
|
---|
8525 | Normal medium (attached directly or indirectly, preserved
|
---|
8526 | when taking snapshots).
|
---|
8527 | </desc>
|
---|
8528 | </const>
|
---|
8529 | <const name="Immutable" value="1">
|
---|
8530 | <desc>
|
---|
8531 | Immutable medium (attached indirectly, changes are wiped out
|
---|
8532 | the next time the virtual machine is started).
|
---|
8533 | </desc>
|
---|
8534 | </const>
|
---|
8535 | <const name="Writethrough" value="2">
|
---|
8536 | <desc>
|
---|
8537 | Write through medium (attached directly, ignored when
|
---|
8538 | taking snapshots).
|
---|
8539 | </desc>
|
---|
8540 | </const>
|
---|
8541 | <const name="Shareable" value="3">
|
---|
8542 | <desc>
|
---|
8543 | Allow using this medium concurrently by several machines.
|
---|
8544 | <note>Present since VirtualBox 3.2.0, and accepted since 3.2.8.</note>
|
---|
8545 | </desc>
|
---|
8546 | </const>
|
---|
8547 | <const name="Readonly" value="4">
|
---|
8548 | <desc>
|
---|
8549 | A readonly medium, which can of course be used by several machines.
|
---|
8550 | <note>Present and accepted since VirtualBox 4.0.</note>
|
---|
8551 | </desc>
|
---|
8552 | </const>
|
---|
8553 | </enum>
|
---|
8554 |
|
---|
8555 | <enum
|
---|
8556 | name="MediumVariant"
|
---|
8557 | uuid="584ea502-143b-4ab0-ad14-d1028fdf0316"
|
---|
8558 | >
|
---|
8559 | <desc>
|
---|
8560 | Virtual medium image variant. More than one flag may be set.
|
---|
8561 | <see>IMedium</see>
|
---|
8562 | </desc>
|
---|
8563 |
|
---|
8564 | <const name="Standard" value="0">
|
---|
8565 | <desc>
|
---|
8566 | No particular variant requested, results in using the backend default.
|
---|
8567 | </desc>
|
---|
8568 | </const>
|
---|
8569 | <const name="VmdkSplit2G" value="0x01">
|
---|
8570 | <desc>
|
---|
8571 | VMDK image split in chunks of less than 2GByte.
|
---|
8572 | </desc>
|
---|
8573 | </const>
|
---|
8574 | <const name="VmdkStreamOptimized" value="0x04">
|
---|
8575 | <desc>
|
---|
8576 | VMDK streamOptimized image. Special import/export format which is
|
---|
8577 | read-only/append-only.
|
---|
8578 | </desc>
|
---|
8579 | </const>
|
---|
8580 | <const name="VmdkESX" value="0x08">
|
---|
8581 | <desc>
|
---|
8582 | VMDK format variant used on ESX products.
|
---|
8583 | </desc>
|
---|
8584 | </const>
|
---|
8585 | <const name="Fixed" value="0x10000">
|
---|
8586 | <desc>
|
---|
8587 | Fixed image. Only allowed for base images.
|
---|
8588 | </desc>
|
---|
8589 | </const>
|
---|
8590 | <const name="Diff" value="0x20000">
|
---|
8591 | <desc>
|
---|
8592 | Differencing image. Only allowed for child images.
|
---|
8593 | </desc>
|
---|
8594 | </const>
|
---|
8595 | </enum>
|
---|
8596 |
|
---|
8597 | <interface
|
---|
8598 | name="IMediumAttachment" extends="$unknown"
|
---|
8599 | uuid="c29452cc-ca72-404b-9261-cfc514f1e412"
|
---|
8600 | wsmap="struct"
|
---|
8601 | >
|
---|
8602 | <desc>
|
---|
8603 | The IMediumAttachment interface links storage media to virtual machines.
|
---|
8604 | For each medium (<link to="IMedium"/>) which has been attached to a
|
---|
8605 | storage controller (<link to="IStorageController"/>) of a machine
|
---|
8606 | (<link to="IMachine"/>) via the <link to="IMachine::attachDevice" />
|
---|
8607 | method, one instance of IMediumAttachment is added to the machine's
|
---|
8608 | <link to="IMachine::mediumAttachments"/> array attribute.
|
---|
8609 |
|
---|
8610 | Each medium attachment specifies the storage controller as well as a
|
---|
8611 | port and device number and the IMedium instance representing a virtual
|
---|
8612 | hard disk or floppy or DVD image.
|
---|
8613 |
|
---|
8614 | For removeable media (DVDs or floppies), there are two additional
|
---|
8615 | options. For one, the IMedium instance can be @c null to represent
|
---|
8616 | an empty drive with no media inserted (see <link to="IMachine::mountMedium" />);
|
---|
8617 | secondly, the medium can be one of the pseudo-media for host drives
|
---|
8618 | listed in <link to="IHost::DVDDrives"/> or <link to="IHost::floppyDrives"/>.
|
---|
8619 | </desc>
|
---|
8620 |
|
---|
8621 | <attribute name="medium" type="IMedium" readonly="yes">
|
---|
8622 | <desc>Medium object associated with this attachment; it
|
---|
8623 | can be @c null for removable devices.</desc>
|
---|
8624 | </attribute>
|
---|
8625 |
|
---|
8626 | <attribute name="controller" type="wstring" readonly="yes">
|
---|
8627 | <desc>Name of the storage controller of this attachment; this
|
---|
8628 | refers to one of the controllers in <link to="IMachine::storageControllers" />
|
---|
8629 | by name.</desc>
|
---|
8630 | </attribute>
|
---|
8631 |
|
---|
8632 | <attribute name="port" type="long" readonly="yes">
|
---|
8633 | <desc>Port number of this attachment.
|
---|
8634 | See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
|
---|
8635 | </desc>
|
---|
8636 | </attribute>
|
---|
8637 |
|
---|
8638 | <attribute name="device" type="long" readonly="yes">
|
---|
8639 | <desc>Device slot number of this attachment.
|
---|
8640 | See <link to="IMachine::attachDevice" /> for the meaning of this value for the different controller types.
|
---|
8641 | </desc>
|
---|
8642 | </attribute>
|
---|
8643 |
|
---|
8644 | <attribute name="type" type="DeviceType" readonly="yes">
|
---|
8645 | <desc>Device type of this attachment.</desc>
|
---|
8646 | </attribute>
|
---|
8647 |
|
---|
8648 | <attribute name="passthrough" type="boolean" readonly="yes">
|
---|
8649 | <desc>Pass I/O requests through to a device on the host.</desc>
|
---|
8650 | </attribute>
|
---|
8651 |
|
---|
8652 | <attribute name="bandwidthLimit" type="unsigned long">
|
---|
8653 | <desc>
|
---|
8654 | Maximum throughput allowed for this medium attachment, in units of 1 mbps.
|
---|
8655 | A zero value means uncapped/unlimited.
|
---|
8656 | </desc>
|
---|
8657 | </attribute>
|
---|
8658 |
|
---|
8659 | </interface>
|
---|
8660 |
|
---|
8661 | <interface
|
---|
8662 | name="IMedium" extends="$unknown"
|
---|
8663 | uuid="bfcf5b8c-5155-4f24-9414-9457054b16db"
|
---|
8664 | wsmap="managed"
|
---|
8665 | >
|
---|
8666 | <desc>
|
---|
8667 | The IMedium interface represents virtual storage for a machine's
|
---|
8668 | hard disks, CD/DVD or floppy drives. It will typically represent
|
---|
8669 | a disk image on the host, for example a VDI or VMDK file representing
|
---|
8670 | a virtual hard disk, or an ISO or RAW file representing virtual
|
---|
8671 | removable media, but can also point to a network location (e.g.
|
---|
8672 | for iSCSI targets).
|
---|
8673 |
|
---|
8674 | Instances of IMedium are connected to virtual machines by way of
|
---|
8675 | medium attachments (see <link to="IMediumAttachment" />), which link
|
---|
8676 | the storage medium to a particular device slot of a storage controller
|
---|
8677 | of the virtual machine.
|
---|
8678 | In the VirtualBox API, virtual storage is therefore always represented
|
---|
8679 | by the following chain of object links:
|
---|
8680 |
|
---|
8681 | <ul>
|
---|
8682 | <li><link to="IMachine::storageControllers"/> contains an array of
|
---|
8683 | storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
|
---|
8684 | these are instances of <link to="IStorageController"/>).</li>
|
---|
8685 | <li><link to="IMachine::mediumAttachments"/> contains an array of
|
---|
8686 | medium attachments (instances of <link to="IMediumAttachment"/>),
|
---|
8687 | each containing a storage controller from the above array, a
|
---|
8688 | port/device specification, and an instance of IMedium representing
|
---|
8689 | the medium storage (image file).
|
---|
8690 |
|
---|
8691 | For removable media, the storage medium is optional; a medium
|
---|
8692 | attachment with no medium represents a CD/DVD or floppy drive
|
---|
8693 | with no medium inserted. By contrast, hard disk attachments
|
---|
8694 | will always have an IMedium object attached.</li>
|
---|
8695 | <li>Each IMedium in turn points to a storage unit (such as a file
|
---|
8696 | on the host computer or a network resource) that holds actual
|
---|
8697 | data. This location is represented by the <link to="#location"/>
|
---|
8698 | attribute.</li>
|
---|
8699 | </ul>
|
---|
8700 |
|
---|
8701 | Existing media are opened using <link to="IVirtualBox::openMedium"/>;
|
---|
8702 | new hard disk media can be created with the VirtualBox API using the
|
---|
8703 | <link to="IVirtualBox::createHardDisk"/> method.
|
---|
8704 |
|
---|
8705 | CD/DVD and floppy images (ISO and RAW files) are usually created outside
|
---|
8706 | VirtualBox, e.g. by storing a copy of the real medium of the corresponding
|
---|
8707 | type in a regular file.
|
---|
8708 |
|
---|
8709 | Only for CD/DVDs and floppies, an IMedium instance can also represent a host
|
---|
8710 | drive; in that case the <link to="#id" /> attribute contains the UUID of
|
---|
8711 | one of the drives in <link to="IHost::DVDDrives" /> or <link to="IHost::floppyDrives" />.
|
---|
8712 |
|
---|
8713 | <h3>Known media</h3>
|
---|
8714 |
|
---|
8715 | When an existing medium is opened and attached to a virtual machine, it
|
---|
8716 | is automatically added to a media registry. If the medium has first
|
---|
8717 | been attached to a machine which was created by VirtualBox 4.0 or later,
|
---|
8718 | it is added to that machine's media registry (in the machine XML settings
|
---|
8719 | file; this way all information about a machine's media attachments is
|
---|
8720 | contained in a single file). For older media attachments (i.e. if the
|
---|
8721 | medium was first attached to a machine which was created with a VirtualBox
|
---|
8722 | version before 4.0), media continue to be registered in the global
|
---|
8723 | VirtualBox settings file, for backwards compatibility.
|
---|
8724 |
|
---|
8725 | See <link to="IVirtualBox::openMedium" /> for more information.
|
---|
8726 |
|
---|
8727 | All known media can be enumerated using
|
---|
8728 | <link to="IVirtualBox::hardDisks"/>,
|
---|
8729 | <link to="IVirtualBox::DVDImages"/> and
|
---|
8730 | <link to="IVirtualBox::floppyImages"/> attributes. Individual media can be
|
---|
8731 | quickly found using the <link to="IVirtualBox::findMedium"/> method.
|
---|
8732 |
|
---|
8733 | Only known media can be attached to virtual machines.
|
---|
8734 |
|
---|
8735 | Removing known media from the media registry is performed when the given
|
---|
8736 | medium is closed using the <link to="#close"/> method or when its
|
---|
8737 | associated storage unit is deleted.
|
---|
8738 |
|
---|
8739 | <h3>Accessibility checks</h3>
|
---|
8740 |
|
---|
8741 | VirtualBox defers media accessibility checks until the <link to="#refreshState" />
|
---|
8742 | method is called explicitly on a medium. This is done to make the VirtualBox object
|
---|
8743 | ready for serving requests as fast as possible and let the end-user
|
---|
8744 | application decide if it needs to check media accessibility right away or not.
|
---|
8745 |
|
---|
8746 | As a result, when VirtualBox starts up (e.g. the VirtualBox
|
---|
8747 | object gets created for the first time), all known media are in the
|
---|
8748 | "Inaccessible" state, but the value of the <link to="#lastAccessError"/>
|
---|
8749 | attribute is an empty string because no actual accessibility check has
|
---|
8750 | been made yet.
|
---|
8751 |
|
---|
8752 | After calling <link to="#refreshState" />, a medium is considered
|
---|
8753 | <i>accessible</i> if its storage unit can be read. In that case, the
|
---|
8754 | <link to="#state"/> attribute has a value of "Created". If the storage
|
---|
8755 | unit cannot be read (for example, because it is located on a disconnected
|
---|
8756 | network resource, or was accidentally deleted outside VirtualBox),
|
---|
8757 | the medium is considered <i>inaccessible</i>, which is indicated by the
|
---|
8758 | "Inaccessible" state. The exact reason why the medium is inaccessible can be
|
---|
8759 | obtained by reading the <link to="#lastAccessError"/> attribute.
|
---|
8760 |
|
---|
8761 | <h3>Medium types</h3>
|
---|
8762 |
|
---|
8763 | There are four types of medium behavior (see <link to="MediumType" />):
|
---|
8764 | "normal", "immutable", "writethrough" and "shareable", represented by the
|
---|
8765 | <link to="#type"/> attribute. The type of the medium defines how the
|
---|
8766 | medium is attached to a virtual machine and what happens when a
|
---|
8767 | <link to="ISnapshot">snapshot</link> of the virtual machine with the
|
---|
8768 | attached medium is taken. At the moment DVD and floppy media are always
|
---|
8769 | of type "writethrough".
|
---|
8770 |
|
---|
8771 | All media can be also divided in two groups: <i>base</i> media and
|
---|
8772 | <i>differencing</i> media. A base medium contains all sectors of the
|
---|
8773 | medium data in its own storage and therefore can be used independently.
|
---|
8774 | In contrast, a differencing medium is a "delta" to some other medium and
|
---|
8775 | contains only those sectors which differ from that other medium, which is
|
---|
8776 | then called a <i>parent</i>. The differencing medium is said to be
|
---|
8777 | <i>linked to</i> that parent. The parent may be itself a differencing
|
---|
8778 | medium, thus forming a chain of linked media. The last element in that
|
---|
8779 | chain must always be a base medium. Note that several differencing
|
---|
8780 | media may be linked to the same parent medium.
|
---|
8781 |
|
---|
8782 | Differencing media can be distinguished from base media by querying the
|
---|
8783 | <link to="#parent"/> attribute: base media do not have parents they would
|
---|
8784 | depend on, so the value of this attribute is always @c null for them.
|
---|
8785 | Using this attribute, it is possible to walk up the medium tree (from the
|
---|
8786 | child medium to its parent). It is also possible to walk down the tree
|
---|
8787 | using the <link to="#children"/> attribute.
|
---|
8788 |
|
---|
8789 | Note that the type of all differencing media is "normal"; all other
|
---|
8790 | values are meaningless for them. Base media may be of any type.
|
---|
8791 |
|
---|
8792 | <h3>Creating hard disks</h3>
|
---|
8793 |
|
---|
8794 | New base hard disks are created using
|
---|
8795 | <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
|
---|
8796 | opened using <link to="IVirtualBox::openMedium"/>. Differencing hard
|
---|
8797 | disks are usually implicitly created by VirtualBox when needed but may
|
---|
8798 | also be created explicitly using <link to="#createDiffStorage"/>.
|
---|
8799 |
|
---|
8800 | After the hard disk is successfully created (including the storage unit)
|
---|
8801 | or opened, it becomes a known hard disk (remembered in the internal media
|
---|
8802 | registry). Known hard disks can be attached to a virtual machine, accessed
|
---|
8803 | through <link to="IVirtualBox::findMedium"/> or enumerated using the
|
---|
8804 | <link to="IVirtualBox::hardDisks"/> array (only for base hard disks).
|
---|
8805 |
|
---|
8806 | The following methods, besides <link to="IMedium::close"/>,
|
---|
8807 | automatically remove the hard disk from the media registry:
|
---|
8808 | <ul>
|
---|
8809 | <li><link to="#deleteStorage"/></li>
|
---|
8810 | <li><link to="#mergeTo"/></li>
|
---|
8811 | </ul>
|
---|
8812 |
|
---|
8813 | If the storage unit of the hard disk is a regular file in the host's
|
---|
8814 | file system then the rules stated in the description of the
|
---|
8815 | <link to="IMedium::location"/> attribute apply when setting its value.
|
---|
8816 |
|
---|
8817 | <h4>Automatic composition of the file name part</h4>
|
---|
8818 |
|
---|
8819 | Another extension to the <link to="IMedium::location"/> attribute is that
|
---|
8820 | there is a possibility to cause VirtualBox to compose a unique value for
|
---|
8821 | the file name part of the location using the UUID of the hard disk. This
|
---|
8822 | applies only to hard disks in <link to="MediumState_NotCreated"/> state,
|
---|
8823 | e.g. before the storage unit is created, and works as follows. You set the
|
---|
8824 | value of the <link to="IMedium::location"/> attribute to a location
|
---|
8825 | specification which only contains the path specification but not the file
|
---|
8826 | name part and ends with either a forward slash or a backslash character.
|
---|
8827 | In response, VirtualBox will generate a new UUID for the hard disk and
|
---|
8828 | compose the file name using the following pattern:
|
---|
8829 | <pre>
|
---|
8830 | <path>/{<uuid>}.<ext>
|
---|
8831 | </pre>
|
---|
8832 | where <tt><path></tt> is the supplied path specification,
|
---|
8833 | <tt><uuid></tt> is the newly generated UUID and <tt><ext></tt>
|
---|
8834 | is the default extension for the storage format of this hard disk. After
|
---|
8835 | that, you may call any of the methods that create a new hard disk storage
|
---|
8836 | unit and they will use the generated UUID and file name.
|
---|
8837 |
|
---|
8838 | <h3>Attaching Hard Disks</h3>
|
---|
8839 |
|
---|
8840 | Hard disks are attached to virtual machines using the
|
---|
8841 | <link to="IMachine::attachDevice"/> method and detached using the
|
---|
8842 | <link to="IMachine::detachDevice"/> method. Depending on their
|
---|
8843 | <link to="#type"/>, hard disks are attached either
|
---|
8844 | <i>directly</i> or <i>indirectly</i>.
|
---|
8845 |
|
---|
8846 | When a hard disk is being attached directly, it is associated with the
|
---|
8847 | virtual machine and used for hard disk operations when the machine is
|
---|
8848 | running. When a hard disk is being attached indirectly, a new differencing
|
---|
8849 | hard disk linked to it is implicitly created and this differencing hard
|
---|
8850 | disk is associated with the machine and used for hard disk operations.
|
---|
8851 | This also means that if <link to="IMachine::attachDevice"/> performs
|
---|
8852 | a direct attachment then the same hard disk will be returned in response
|
---|
8853 | to the subsequent <link to="IMachine::getMedium"/> call; however if
|
---|
8854 | an indirect attachment is performed then
|
---|
8855 | <link to="IMachine::getMedium"/> will return the implicitly created
|
---|
8856 | differencing hard disk, not the original one passed to <link
|
---|
8857 | to="IMachine::attachDevice"/>. In detail:
|
---|
8858 |
|
---|
8859 | <ul>
|
---|
8860 | <li><b>Normal base</b> hard disks that do not have children (i.e.
|
---|
8861 | differencing hard disks linked to them) and that are not already
|
---|
8862 | attached to virtual machines in snapshots are attached <b>directly</b>.
|
---|
8863 | Otherwise, they are attached <b>indirectly</b> because having
|
---|
8864 | dependent children or being part of the snapshot makes it impossible
|
---|
8865 | to modify hard disk contents without breaking the integrity of the
|
---|
8866 | dependent party. The <link to="#readOnly"/> attribute allows to
|
---|
8867 | quickly determine the kind of the attachment for the given hard
|
---|
8868 | disk. Note that if a normal base hard disk is to be indirectly
|
---|
8869 | attached to a virtual machine with snapshots then a special
|
---|
8870 | procedure called <i>smart attachment</i> is performed (see below).</li>
|
---|
8871 | <li><b>Normal differencing</b> hard disks are like normal base hard disks:
|
---|
8872 | they are attached <b>directly</b> if they do not have children and are
|
---|
8873 | not attached to virtual machines in snapshots, and <b>indirectly</b>
|
---|
8874 | otherwise. Note that the smart attachment procedure is never performed
|
---|
8875 | for differencing hard disks.</li>
|
---|
8876 | <li><b>Immutable</b> hard disks are always attached <b>indirectly</b> because
|
---|
8877 | they are designed to be non-writable. If an immutable hard disk is
|
---|
8878 | attached to a virtual machine with snapshots then a special
|
---|
8879 | procedure called smart attachment is performed (see below).</li>
|
---|
8880 | <li><b>Writethrough</b> hard disks are always attached <b>directly</b>,
|
---|
8881 | also as designed. This also means that writethrough hard disks cannot
|
---|
8882 | have other hard disks linked to them at all.</li>
|
---|
8883 | <li><b>Shareable</b> hard disks are always attached <b>directly</b>,
|
---|
8884 | also as designed. This also means that shareable hard disks cannot
|
---|
8885 | have other hard disks linked to them at all. They behave almost
|
---|
8886 | like writethrough hard disks, except that shareable hard disks can
|
---|
8887 | be attached to several virtual machines which are running, allowing
|
---|
8888 | concurrent accesses. You need special cluster software running in
|
---|
8889 | the virtual machines to make use of such disks.</li>
|
---|
8890 | </ul>
|
---|
8891 |
|
---|
8892 | Note that the same hard disk, regardless of its type, may be attached to
|
---|
8893 | more than one virtual machine at a time. In this case, the machine that is
|
---|
8894 | started first gains exclusive access to the hard disk and attempts to
|
---|
8895 | start other machines having this hard disk attached will fail until the
|
---|
8896 | first machine is powered down.
|
---|
8897 |
|
---|
8898 | Detaching hard disks is performed in a <i>deferred</i> fashion. This means
|
---|
8899 | that the given hard disk remains associated with the given machine after a
|
---|
8900 | successful <link to="IMachine::detachDevice"/> call until
|
---|
8901 | <link to="IMachine::saveSettings"/> is called to save all changes to
|
---|
8902 | machine settings to disk. This deferring is necessary to guarantee that
|
---|
8903 | the hard disk configuration may be restored at any time by a call to
|
---|
8904 | <link to="IMachine::discardSettings"/> before the settings
|
---|
8905 | are saved (committed).
|
---|
8906 |
|
---|
8907 | Note that if <link to="IMachine::discardSettings"/> is called after
|
---|
8908 | indirectly attaching some hard disks to the machine but before a call to
|
---|
8909 | <link to="IMachine::saveSettings"/> is made, it will implicitly delete
|
---|
8910 | all differencing hard disks implicitly created by
|
---|
8911 | <link to="IMachine::attachDevice"/> for these indirect attachments.
|
---|
8912 | Such implicitly created hard disks will also be immediately deleted when
|
---|
8913 | detached explicitly using the <link to="IMachine::detachDevice"/>
|
---|
8914 | call if it is made before <link to="IMachine::saveSettings"/>. This
|
---|
8915 | implicit deletion is safe because newly created differencing hard
|
---|
8916 | disks do not contain any user data.
|
---|
8917 |
|
---|
8918 | However, keep in mind that detaching differencing hard disks that were
|
---|
8919 | implicitly created by <link to="IMachine::attachDevice"/>
|
---|
8920 | before the last <link to="IMachine::saveSettings"/> call will
|
---|
8921 | <b>not</b> implicitly delete them as they may already contain some data
|
---|
8922 | (for example, as a result of virtual machine execution). If these hard
|
---|
8923 | disks are no more necessary, the caller can always delete them explicitly
|
---|
8924 | using <link to="#deleteStorage"/> after they are actually de-associated
|
---|
8925 | from this machine by the <link to="IMachine::saveSettings"/> call.
|
---|
8926 |
|
---|
8927 | <h3>Smart Attachment</h3>
|
---|
8928 |
|
---|
8929 | When normal base or immutable hard disks are indirectly attached to a
|
---|
8930 | virtual machine then some additional steps are performed to make sure the
|
---|
8931 | virtual machine will have the most recent "view" of the hard disk being
|
---|
8932 | attached. These steps include walking through the machine's snapshots
|
---|
8933 | starting from the current one and going through ancestors up to the first
|
---|
8934 | snapshot. Hard disks attached to the virtual machine in all
|
---|
8935 | of the encountered snapshots are checked whether they are descendants of
|
---|
8936 | the given normal base or immutable hard disk. The first found child (which
|
---|
8937 | is the differencing hard disk) will be used instead of the normal base or
|
---|
8938 | immutable hard disk as a parent for creating a new differencing hard disk
|
---|
8939 | that will be actually attached to the machine. And only if no descendants
|
---|
8940 | are found or if the virtual machine does not have any snapshots then the
|
---|
8941 | normal base or immutable hard disk will be used itself as a parent for
|
---|
8942 | this differencing hard disk.
|
---|
8943 |
|
---|
8944 | It is easier to explain what smart attachment does using the
|
---|
8945 | following example:
|
---|
8946 | <pre>
|
---|
8947 | BEFORE attaching B.vdi: AFTER attaching B.vdi:
|
---|
8948 |
|
---|
8949 | Snapshot 1 (B.vdi) Snapshot 1 (B.vdi)
|
---|
8950 | Snapshot 2 (D1->B.vdi) Snapshot 2 (D1->B.vdi)
|
---|
8951 | Snapshot 3 (D2->D1.vdi) Snapshot 3 (D2->D1.vdi)
|
---|
8952 | Snapshot 4 (none) Snapshot 4 (none)
|
---|
8953 | CurState (none) CurState (D3->D2.vdi)
|
---|
8954 |
|
---|
8955 | NOT
|
---|
8956 | ...
|
---|
8957 | CurState (D3->B.vdi)
|
---|
8958 | </pre>
|
---|
8959 | The first column is the virtual machine configuration before the base hard
|
---|
8960 | disk <tt>B.vdi</tt> is attached, the second column shows the machine after
|
---|
8961 | this hard disk is attached. Constructs like <tt>D1->B.vdi</tt> and similar
|
---|
8962 | mean that the hard disk that is actually attached to the machine is a
|
---|
8963 | differencing hard disk, <tt>D1.vdi</tt>, which is linked to (based on)
|
---|
8964 | another hard disk, <tt>B.vdi</tt>.
|
---|
8965 |
|
---|
8966 | As we can see from the example, the hard disk <tt>B.vdi</tt> was detached
|
---|
8967 | from the machine before taking Snapshot 4. Later, after Snapshot 4 was
|
---|
8968 | taken, the user decides to attach <tt>B.vdi</tt> again. <tt>B.vdi</tt> has
|
---|
8969 | dependent child hard disks (<tt>D1.vdi</tt>, <tt>D2.vdi</tt>), therefore
|
---|
8970 | it cannot be attached directly and needs an indirect attachment (i.e.
|
---|
8971 | implicit creation of a new differencing hard disk). Due to the smart
|
---|
8972 | attachment procedure, the new differencing hard disk
|
---|
8973 | (<tt>D3.vdi</tt>) will be based on <tt>D2.vdi</tt>, not on
|
---|
8974 | <tt>B.vdi</tt> itself, since <tt>D2.vdi</tt> is the most recent view of
|
---|
8975 | <tt>B.vdi</tt> existing for this snapshot branch of the given virtual
|
---|
8976 | machine.
|
---|
8977 |
|
---|
8978 | Note that if there is more than one descendant hard disk of the given base
|
---|
8979 | hard disk found in a snapshot, and there is an exact device, channel and
|
---|
8980 | bus match, then this exact match will be used. Otherwise, the youngest
|
---|
8981 | descendant will be picked up.
|
---|
8982 |
|
---|
8983 | There is one more important aspect of the smart attachment procedure which
|
---|
8984 | is not related to snapshots at all. Before walking through the snapshots
|
---|
8985 | as described above, the backup copy of the current list of hard disk
|
---|
8986 | attachment is searched for descendants. This backup copy is created when
|
---|
8987 | the hard disk configuration is changed for the first time after the last
|
---|
8988 | <link to="IMachine::saveSettings"/> call and used by
|
---|
8989 | <link to="IMachine::discardSettings"/> to undo the recent hard disk
|
---|
8990 | changes. When such a descendant is found in this backup copy, it will be
|
---|
8991 | simply re-attached back, without creating a new differencing hard disk for
|
---|
8992 | it. This optimization is necessary to make it possible to re-attach the
|
---|
8993 | base or immutable hard disk to a different bus, channel or device slot
|
---|
8994 | without losing the contents of the differencing hard disk actually
|
---|
8995 | attached to the machine in place of it.
|
---|
8996 | </desc>
|
---|
8997 |
|
---|
8998 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
8999 | <desc>
|
---|
9000 | UUID of the medium. For a newly created medium, this value is a randomly
|
---|
9001 | generated UUID.
|
---|
9002 |
|
---|
9003 | <note>
|
---|
9004 | For media in one of MediumState_NotCreated, MediumState_Creating or
|
---|
9005 | MediumState_Deleting states, the value of this property is undefined
|
---|
9006 | and will most likely be an empty UUID.
|
---|
9007 | </note>
|
---|
9008 | </desc>
|
---|
9009 | </attribute>
|
---|
9010 |
|
---|
9011 | <attribute name="description" type="wstring">
|
---|
9012 | <desc>
|
---|
9013 | Optional description of the medium. For a newly created medium the value
|
---|
9014 | of this attribute is an empty string.
|
---|
9015 |
|
---|
9016 | Medium types that don't support this attribute will return E_NOTIMPL in
|
---|
9017 | attempt to get or set this attribute's value.
|
---|
9018 |
|
---|
9019 | <note>
|
---|
9020 | For some storage types, reading this attribute may return an outdated
|
---|
9021 | (last known) value when <link to="#state"/> is <link
|
---|
9022 | to="MediumState_Inaccessible"/> or <link
|
---|
9023 | to="MediumState_LockedWrite"/> because the value of this attribute is
|
---|
9024 | stored within the storage unit itself. Also note that changing the
|
---|
9025 | attribute value is not possible in such case, as well as when the
|
---|
9026 | medium is the <link to="MediumState_LockedRead"/> state.
|
---|
9027 | </note>
|
---|
9028 | </desc>
|
---|
9029 | </attribute>
|
---|
9030 |
|
---|
9031 | <attribute name="state" type="MediumState" readonly="yes">
|
---|
9032 | <desc>
|
---|
9033 | Returns the current medium state, which is the last state set by
|
---|
9034 | the accessibility check performed by <link to="#refreshState"/>.
|
---|
9035 | If that method has not yet been called on the medium, the state
|
---|
9036 | is "Inaccessible"; as opposed to truly inaccessible media, the
|
---|
9037 | value of <link to="#lastAccessError"/> will be an empty string in
|
---|
9038 | that case.
|
---|
9039 |
|
---|
9040 | <note>As of version 3.1, this no longer performs an accessibility check
|
---|
9041 | automatically; call <link to="#refreshState"/> for that.
|
---|
9042 | </note>
|
---|
9043 | </desc>
|
---|
9044 | </attribute>
|
---|
9045 |
|
---|
9046 | <attribute name="variant" type="MediumVariant" readonly="yes">
|
---|
9047 | <desc>
|
---|
9048 | Returns the storage format variant information for this medium.
|
---|
9049 | Before <link to="#refreshState"/> is called this method returns
|
---|
9050 | an undefined value.
|
---|
9051 | </desc>
|
---|
9052 | </attribute>
|
---|
9053 |
|
---|
9054 | <attribute name="location" type="wstring">
|
---|
9055 | <desc>
|
---|
9056 | Location of the storage unit holding medium data.
|
---|
9057 |
|
---|
9058 | The format of the location string is medium type specific. For medium
|
---|
9059 | types using regular files in a host's file system, the location
|
---|
9060 | string is the full file name.
|
---|
9061 |
|
---|
9062 | Some medium types may support changing the storage unit location by
|
---|
9063 | simply changing the value of this property. If this operation is not
|
---|
9064 | supported, the implementation will return E_NOTIMPL in attempt to set
|
---|
9065 | this attribute's value.
|
---|
9066 |
|
---|
9067 | When setting a value of the location attribute which is a regular file
|
---|
9068 | in the host's file system, the given file name may be either relative to
|
---|
9069 | the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> or
|
---|
9070 | absolute. Note that if the given location specification does not contain
|
---|
9071 | the file extension part then a proper default extension will be
|
---|
9072 | automatically appended by the implementation depending on the medium type.
|
---|
9073 | </desc>
|
---|
9074 | </attribute>
|
---|
9075 |
|
---|
9076 | <attribute name="name" type="wstring" readonly="yes">
|
---|
9077 | <desc>
|
---|
9078 | Name of the storage unit holding medium data.
|
---|
9079 |
|
---|
9080 | The returned string is a short version of the <link to="#location"/>
|
---|
9081 | attribute that is suitable for representing the medium in situations
|
---|
9082 | where the full location specification is too long (such as lists
|
---|
9083 | and comboboxes in GUI frontends). This string is also used by frontends
|
---|
9084 | to sort the media list alphabetically when needed.
|
---|
9085 |
|
---|
9086 | For example, for locations that are regular files in the host's file
|
---|
9087 | system, the value of this attribute is just the file name (+ extension),
|
---|
9088 | without the path specification.
|
---|
9089 |
|
---|
9090 | Note that as opposed to the <link to="#location"/> attribute, the name
|
---|
9091 | attribute will not necessary be unique for a list of media of the
|
---|
9092 | given type and format.
|
---|
9093 | </desc>
|
---|
9094 | </attribute>
|
---|
9095 |
|
---|
9096 | <attribute name="deviceType" type="DeviceType" readonly="yes">
|
---|
9097 | <desc>Kind of device (DVD/Floppy/HardDisk) which is applicable to this
|
---|
9098 | medium.</desc>
|
---|
9099 | </attribute>
|
---|
9100 |
|
---|
9101 | <attribute name="hostDrive" type="boolean" readonly="yes">
|
---|
9102 | <desc>True if this corresponds to a drive on the host.</desc>
|
---|
9103 | </attribute>
|
---|
9104 |
|
---|
9105 | <attribute name="size" type="long long" readonly="yes">
|
---|
9106 | <desc>
|
---|
9107 | Physical size of the storage unit used to hold medium data (in bytes).
|
---|
9108 |
|
---|
9109 | <note>
|
---|
9110 | For media whose <link to="#state"/> is <link
|
---|
9111 | to="MediumState_Inaccessible"/>, the value of this property is the
|
---|
9112 | last known size. For <link to="MediumState_NotCreated"/> media,
|
---|
9113 | the returned value is zero.
|
---|
9114 | </note>
|
---|
9115 | </desc>
|
---|
9116 | </attribute>
|
---|
9117 |
|
---|
9118 | <attribute name="format" type="wstring" readonly="yes">
|
---|
9119 | <desc>
|
---|
9120 | Storage format of this medium.
|
---|
9121 |
|
---|
9122 | The value of this attribute is a string that specifies a backend used
|
---|
9123 | to store medium data. The storage format is defined when you create a
|
---|
9124 | new medium or automatically detected when you open an existing medium,
|
---|
9125 | and cannot be changed later.
|
---|
9126 |
|
---|
9127 | The list of all storage formats supported by this VirtualBox
|
---|
9128 | installation can be obtained using
|
---|
9129 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
9130 | </desc>
|
---|
9131 | </attribute>
|
---|
9132 |
|
---|
9133 | <attribute name="mediumFormat" type="IMediumFormat" readonly="yes">
|
---|
9134 | <desc>
|
---|
9135 | Storage medium format object corresponding to this medium.
|
---|
9136 |
|
---|
9137 | The value of this attribute is a reference to the medium format object
|
---|
9138 | that specifies the backend properties used to store medium data. The
|
---|
9139 | storage format is defined when you create a new medium or automatically
|
---|
9140 | detected when you open an existing medium, and cannot be changed later.
|
---|
9141 |
|
---|
9142 | <note>@c null is returned if there is no associated medium format
|
---|
9143 | object. This can e.g. happen for medium objects representing host
|
---|
9144 | drives and other special medium objects.</note>
|
---|
9145 | </desc>
|
---|
9146 | </attribute>
|
---|
9147 |
|
---|
9148 | <attribute name="type" type="MediumType">
|
---|
9149 | <desc>
|
---|
9150 | Type (role) of this medium.
|
---|
9151 |
|
---|
9152 | The following constraints apply when changing the value of this
|
---|
9153 | attribute:
|
---|
9154 | <ul>
|
---|
9155 | <li>If a medium is attached to a virtual machine (either in the
|
---|
9156 | current state or in one of the snapshots), its type cannot be
|
---|
9157 | changed.
|
---|
9158 | </li>
|
---|
9159 | <li>As long as the medium has children, its type cannot be set
|
---|
9160 | to <link to="MediumType_Writethrough"/>.
|
---|
9161 | </li>
|
---|
9162 | <li>The type of all differencing media is
|
---|
9163 | <link to="MediumType_Normal"/> and cannot be changed.
|
---|
9164 | </li>
|
---|
9165 | </ul>
|
---|
9166 |
|
---|
9167 | The type of a newly created or opened medium is set to
|
---|
9168 | <link to="MediumType_Normal"/>, except for DVD and floppy media,
|
---|
9169 | which have a type of <link to="MediumType_Writethrough"/>.
|
---|
9170 | </desc>
|
---|
9171 | </attribute>
|
---|
9172 |
|
---|
9173 | <attribute name="parent" type="IMedium" readonly="yes">
|
---|
9174 | <desc>
|
---|
9175 | Parent of this medium (the medium this medium is directly based
|
---|
9176 | on).
|
---|
9177 |
|
---|
9178 | Only differencing media have parents. For base (non-differencing)
|
---|
9179 | media, @c null is returned.
|
---|
9180 | </desc>
|
---|
9181 | </attribute>
|
---|
9182 |
|
---|
9183 | <attribute name="children" type="IMedium" safearray="yes" readonly="yes">
|
---|
9184 | <desc>
|
---|
9185 | Children of this medium (all differencing media directly based
|
---|
9186 | on this medium). A @c null array is returned if this medium
|
---|
9187 | does not have any children.
|
---|
9188 | </desc>
|
---|
9189 | </attribute>
|
---|
9190 |
|
---|
9191 | <attribute name="base" type="IMedium" readonly="yes">
|
---|
9192 | <desc>
|
---|
9193 | Base medium of this medium.
|
---|
9194 |
|
---|
9195 | If this is a differencing medium, its base medium is the medium
|
---|
9196 | the given medium branch starts from. For all other types of media, this
|
---|
9197 | property returns the medium object itself (i.e. the same object this
|
---|
9198 | property is read on).
|
---|
9199 | </desc>
|
---|
9200 | </attribute>
|
---|
9201 |
|
---|
9202 | <attribute name="readOnly" type="boolean" readonly="yes">
|
---|
9203 | <desc>
|
---|
9204 | Returns @c true if this medium is read-only and @c false otherwise.
|
---|
9205 |
|
---|
9206 | A medium is considered to be read-only when its contents cannot be
|
---|
9207 | modified without breaking the integrity of other parties that depend on
|
---|
9208 | this medium such as its child media or snapshots of virtual machines
|
---|
9209 | where this medium is attached to these machines. If there are no
|
---|
9210 | children and no such snapshots then there is no dependency and the
|
---|
9211 | medium is not read-only.
|
---|
9212 |
|
---|
9213 | The value of this attribute can be used to determine the kind of the
|
---|
9214 | attachment that will take place when attaching this medium to a
|
---|
9215 | virtual machine. If the value is @c false then the medium will
|
---|
9216 | be attached directly. If the value is @c true then the medium
|
---|
9217 | will be attached indirectly by creating a new differencing child
|
---|
9218 | medium for that. See the interface description for more information.
|
---|
9219 |
|
---|
9220 | Note that all <link to="MediumType_Immutable">Immutable</link> media
|
---|
9221 | are always read-only while all
|
---|
9222 | <link to="MediumType_Writethrough">Writethrough</link> media are
|
---|
9223 | always not.
|
---|
9224 |
|
---|
9225 | <note>
|
---|
9226 | The read-only condition represented by this attribute is related to
|
---|
9227 | the medium type and usage, not to the current
|
---|
9228 | <link to="IMedium::state">medium state</link> and not to the read-only
|
---|
9229 | state of the storage unit.
|
---|
9230 | </note>
|
---|
9231 | </desc>
|
---|
9232 | </attribute>
|
---|
9233 |
|
---|
9234 | <attribute name="logicalSize" type="long long" readonly="yes">
|
---|
9235 | <desc>
|
---|
9236 | Logical size of this medium (in bytes), as reported to the
|
---|
9237 | guest OS running inside the virtual machine this medium is
|
---|
9238 | attached to. The logical size is defined when the medium is created
|
---|
9239 | and cannot be changed later.
|
---|
9240 |
|
---|
9241 | <note>
|
---|
9242 | Reading this property on a differencing medium will return the size
|
---|
9243 | of its <link to="#base"/> medium.
|
---|
9244 | </note>
|
---|
9245 | <note>
|
---|
9246 | For media whose state is <link to="#state"/> is <link
|
---|
9247 | to="MediumState_Inaccessible"/>, the value of this property is the
|
---|
9248 | last known logical size. For <link to="MediumState_NotCreated"/>
|
---|
9249 | media, the returned value is zero.
|
---|
9250 | </note>
|
---|
9251 | </desc>
|
---|
9252 | </attribute>
|
---|
9253 |
|
---|
9254 | <attribute name="autoReset" type="boolean">
|
---|
9255 | <desc>
|
---|
9256 | Whether this differencing medium will be automatically reset each
|
---|
9257 | time a virtual machine it is attached to is powered up. This
|
---|
9258 | attribute is automatically set to @c true for the last
|
---|
9259 | differencing image of an "immutable" medium (see
|
---|
9260 | <link to="MediumType" />).
|
---|
9261 |
|
---|
9262 | See <link to="#reset"/> for more information about resetting
|
---|
9263 | differencing media.
|
---|
9264 |
|
---|
9265 | <note>
|
---|
9266 | Reading this property on a base (non-differencing) medium will
|
---|
9267 | always @c false. Changing the value of this property in this
|
---|
9268 | case is not supported.
|
---|
9269 | </note>
|
---|
9270 |
|
---|
9271 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9272 | This is not a differencing medium (when changing the attribute
|
---|
9273 | value).
|
---|
9274 | </result>
|
---|
9275 | </desc>
|
---|
9276 | </attribute>
|
---|
9277 |
|
---|
9278 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
9279 | <desc>
|
---|
9280 | Text message that represents the result of the last accessibility
|
---|
9281 | check performed by <link to="#refreshState"/>.
|
---|
9282 |
|
---|
9283 | An empty string is returned if the last accessibility check
|
---|
9284 | was successful or has not yet been called. As a result, if
|
---|
9285 | <link to="#state" /> is "Inaccessible" and this attribute is empty,
|
---|
9286 | then <link to="#refreshState"/> has yet to be called; this is the
|
---|
9287 | default value of media after VirtualBox initialization.
|
---|
9288 | A non-empty string indicates a failure and should normally describe
|
---|
9289 | a reason of the failure (for example, a file read error).
|
---|
9290 | </desc>
|
---|
9291 | </attribute>
|
---|
9292 |
|
---|
9293 | <attribute name="machineIds" type="uuid" mod="string" safearray="yes" readonly="yes">
|
---|
9294 | <desc>
|
---|
9295 | Array of UUIDs of all machines this medium is attached to.
|
---|
9296 |
|
---|
9297 | A @c null array is returned if this medium is not attached to any
|
---|
9298 | machine or to any machine's snapshot.
|
---|
9299 |
|
---|
9300 | <note>
|
---|
9301 | The returned array will include a machine even if this medium is not
|
---|
9302 | attached to that machine in the current state but attached to it in
|
---|
9303 | one of the machine's snapshots. See <link to="#getSnapshotIds"/> for
|
---|
9304 | details.
|
---|
9305 | </note>
|
---|
9306 | </desc>
|
---|
9307 | </attribute>
|
---|
9308 |
|
---|
9309 | <method name="setIDs">
|
---|
9310 | <desc>
|
---|
9311 | Changes the UUID and parent UUID for a hard disk medium.
|
---|
9312 | </desc>
|
---|
9313 | <param name="setImageId" type="boolean" dir="in">
|
---|
9314 | <desc>
|
---|
9315 | Select whether a new image UUID is set or not.
|
---|
9316 | </desc>
|
---|
9317 | </param>
|
---|
9318 | <param name="imageId" type="uuid" mod="string" dir="in">
|
---|
9319 | <desc>
|
---|
9320 | New UUID for the image. If an empty string is passed, then a new
|
---|
9321 | UUID is automatically created, provided that @a setImageId is @c true.
|
---|
9322 | Specifying a zero UUID is not allowed.
|
---|
9323 | </desc>
|
---|
9324 | </param>
|
---|
9325 | <param name="setParentId" type="boolean" dir="in">
|
---|
9326 | <desc>
|
---|
9327 | Select whether a new parent UUID is set or not.
|
---|
9328 | </desc>
|
---|
9329 | </param>
|
---|
9330 | <param name="parentId" type="uuid" mod="string" dir="in">
|
---|
9331 | <desc>
|
---|
9332 | New parent UUID for the image. If an empty string is passed, then a
|
---|
9333 | new UUID is automatically created, provided @a setParentId is
|
---|
9334 | @c true. A zero UUID is valid.
|
---|
9335 | </desc>
|
---|
9336 | </param>
|
---|
9337 | <result name="E_INVALIDARG">
|
---|
9338 | Invalid parameter combination.
|
---|
9339 | </result>
|
---|
9340 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9341 | Medium is not a hard disk medium.
|
---|
9342 | </result>
|
---|
9343 | </method>
|
---|
9344 |
|
---|
9345 | <method name="refreshState">
|
---|
9346 | <desc>
|
---|
9347 | If the current medium state (see <link to="MediumState"/>) is one of
|
---|
9348 | "Created", "Inaccessible" or "LockedRead", then this performs an
|
---|
9349 | accessibility check on the medium and sets the value of the <link to="#state"/>
|
---|
9350 | attribute accordingly; that value is also returned for convenience.
|
---|
9351 |
|
---|
9352 | For all other state values, this does not perform a refresh but returns
|
---|
9353 | the state only.
|
---|
9354 |
|
---|
9355 | The refresh, if performed, may take a long time (several seconds or even
|
---|
9356 | minutes, depending on the storage unit location and format) because it performs an
|
---|
9357 | accessibility check of the storage unit. This check may cause a significant
|
---|
9358 | delay if the storage unit of the given medium is, for example, a file located
|
---|
9359 | on a network share which is not currently accessible due to connectivity
|
---|
9360 | problems. In that case, the call will not return until a timeout
|
---|
9361 | interval defined by the host OS for this operation expires. For this reason,
|
---|
9362 | it is recommended to never read this attribute on the main UI thread to avoid
|
---|
9363 | making the UI unresponsive.
|
---|
9364 |
|
---|
9365 | If the last known state of the medium is "Created" and the accessibility
|
---|
9366 | check fails, then the state would be set to "Inaccessible", and
|
---|
9367 | <link to="#lastAccessError"/> may be used to get more details about the
|
---|
9368 | failure. If the state of the medium is "LockedRead", then it remains the
|
---|
9369 | same, and a non-empty value of <link to="#lastAccessError"/> will
|
---|
9370 | indicate a failed accessibility check in this case.
|
---|
9371 |
|
---|
9372 | Note that not all medium states are applicable to all medium types.
|
---|
9373 | </desc>
|
---|
9374 | <param name="state" type="MediumState" dir="return">
|
---|
9375 | <desc>
|
---|
9376 | New medium state.
|
---|
9377 | </desc>
|
---|
9378 | </param>
|
---|
9379 | </method>
|
---|
9380 |
|
---|
9381 | <method name="getSnapshotIds">
|
---|
9382 | <desc>
|
---|
9383 | Returns an array of UUIDs of all snapshots of the given machine where
|
---|
9384 | this medium is attached to.
|
---|
9385 |
|
---|
9386 | If the medium is attached to the machine in the current state, then the
|
---|
9387 | first element in the array will always be the ID of the queried machine
|
---|
9388 | (i.e. the value equal to the @c machineId argument), followed by
|
---|
9389 | snapshot IDs (if any).
|
---|
9390 |
|
---|
9391 | If the medium is not attached to the machine in the current state, then
|
---|
9392 | the array will contain only snapshot IDs.
|
---|
9393 |
|
---|
9394 | The returned array may be @c null if this medium is not attached
|
---|
9395 | to the given machine at all, neither in the current state nor in one of
|
---|
9396 | the snapshots.
|
---|
9397 | </desc>
|
---|
9398 | <param name="machineId" type="uuid" mod="string" dir="in">
|
---|
9399 | <desc>
|
---|
9400 | UUID of the machine to query.
|
---|
9401 | </desc>
|
---|
9402 | </param>
|
---|
9403 | <param name="snapshotIds" type="uuid" mod="string" safearray="yes" dir="return">
|
---|
9404 | <desc>
|
---|
9405 | Array of snapshot UUIDs of the given machine using this medium.
|
---|
9406 | </desc>
|
---|
9407 | </param>
|
---|
9408 | </method>
|
---|
9409 |
|
---|
9410 | <method name="lockRead">
|
---|
9411 | <desc>
|
---|
9412 | Locks this medium for reading.
|
---|
9413 |
|
---|
9414 | A read lock is shared: many clients can simultaneously lock the
|
---|
9415 | same medium for reading unless it is already locked for writing (see
|
---|
9416 | <link to="#lockWrite"/>) in which case an error is returned.
|
---|
9417 |
|
---|
9418 | When the medium is locked for reading, it cannot be modified
|
---|
9419 | from within VirtualBox. This means that any method that changes
|
---|
9420 | the properties of this medium or contents of the storage unit
|
---|
9421 | will return an error (unless explicitly stated otherwise). That
|
---|
9422 | includes an attempt to start a virtual machine that wants to
|
---|
9423 | write to the the medium.
|
---|
9424 |
|
---|
9425 | When the virtual machine is started up, it locks for reading all
|
---|
9426 | media it uses in read-only mode. If some medium cannot be locked
|
---|
9427 | for reading, the startup procedure will fail.
|
---|
9428 | A medium is typically locked for reading while it is used by a running
|
---|
9429 | virtual machine but has a depending differencing image that receives
|
---|
9430 | the actual write operations. This way one base medium can have
|
---|
9431 | multiple child differencing images which can be written to
|
---|
9432 | simultaneously. Read-only media such as DVD and floppy images are
|
---|
9433 | also locked for reading only (so they can be in use by multiple
|
---|
9434 | machines simultaneously).
|
---|
9435 |
|
---|
9436 | A medium is also locked for reading when it is the source of a
|
---|
9437 | write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
|
---|
9438 |
|
---|
9439 | The medium locked for reading must be unlocked using the <link
|
---|
9440 | to="#unlockRead"/> method. Calls to <link to="#lockRead"/>
|
---|
9441 | can be nested and must be followed by the same number of paired
|
---|
9442 | <link to="#unlockRead"/> calls.
|
---|
9443 |
|
---|
9444 | This method sets the medium state (see <link to="#state"/>) to
|
---|
9445 | "LockedRead" on success. The medium's previous state must be
|
---|
9446 | one of "Created", "Inaccessible" or "LockedRead".
|
---|
9447 |
|
---|
9448 | Locking an inaccessible medium is not an error; this method performs
|
---|
9449 | a logical lock that prevents modifications of this medium through
|
---|
9450 | the VirtualBox API, not a physical file-system lock of the underlying
|
---|
9451 | storage unit.
|
---|
9452 |
|
---|
9453 | This method returns the current state of the medium
|
---|
9454 | <i>before</i> the operation.
|
---|
9455 |
|
---|
9456 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9457 | Invalid medium state (e.g. not created, locked, inaccessible,
|
---|
9458 | creating, deleting).
|
---|
9459 | </result>
|
---|
9460 |
|
---|
9461 | </desc>
|
---|
9462 | <param name="state" type="MediumState" dir="return">
|
---|
9463 | <desc>
|
---|
9464 | State of the medium after the operation.
|
---|
9465 | </desc>
|
---|
9466 | </param>
|
---|
9467 | </method>
|
---|
9468 |
|
---|
9469 | <method name="unlockRead">
|
---|
9470 | <desc>
|
---|
9471 | Cancels the read lock previously set by <link to="#lockRead"/>.
|
---|
9472 |
|
---|
9473 | For both success and failure, this method returns the current state
|
---|
9474 | of the medium <i>after</i> the operation.
|
---|
9475 |
|
---|
9476 | See <link to="#lockRead"/> for more details.
|
---|
9477 |
|
---|
9478 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9479 | Medium not locked for reading.
|
---|
9480 | </result>
|
---|
9481 |
|
---|
9482 | </desc>
|
---|
9483 | <param name="state" type="MediumState" dir="return">
|
---|
9484 | <desc>
|
---|
9485 | State of the medium after the operation.
|
---|
9486 | </desc>
|
---|
9487 | </param>
|
---|
9488 | </method>
|
---|
9489 |
|
---|
9490 | <method name="lockWrite">
|
---|
9491 | <desc>
|
---|
9492 | Locks this medium for writing.
|
---|
9493 |
|
---|
9494 | A write lock, as opposed to <link to="#lockRead"/>, is
|
---|
9495 | exclusive: there may be only one client holding a write lock,
|
---|
9496 | and there may be no read locks while the write lock is held.
|
---|
9497 | As a result, read-locking fails if a write lock is held, and
|
---|
9498 | write-locking fails if either a read or another write lock is held.
|
---|
9499 |
|
---|
9500 | When a medium is locked for writing, it cannot be modified
|
---|
9501 | from within VirtualBox, and it is not guaranteed that the values
|
---|
9502 | of its properties are up-to-date. Any method that changes the
|
---|
9503 | properties of this medium or contents of the storage unit will
|
---|
9504 | return an error (unless explicitly stated otherwise).
|
---|
9505 |
|
---|
9506 | When a virtual machine is started up, it locks for writing all
|
---|
9507 | media it uses to write data to. If any medium could not be locked
|
---|
9508 | for writing, the startup procedure will fail. If a medium has
|
---|
9509 | differencing images, then while the machine is running, only
|
---|
9510 | the last ("leaf") differencing image is locked for writing,
|
---|
9511 | whereas its parents are locked for reading only.
|
---|
9512 |
|
---|
9513 | A medium is also locked for writing when it is the target of a
|
---|
9514 | write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>.
|
---|
9515 |
|
---|
9516 | The medium locked for writing must be unlocked using the <link
|
---|
9517 | to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested.
|
---|
9518 |
|
---|
9519 | This method sets the medium state (see <link to="#state"/>) to
|
---|
9520 | "LockedWrite" on success. The medium's previous state must be
|
---|
9521 | either "Created" or "Inaccessible".
|
---|
9522 |
|
---|
9523 | Locking an inaccessible medium is not an error; this method performs
|
---|
9524 | a logical lock that prevents modifications of this medium through
|
---|
9525 | the VirtualBox API, not a physical file-system lock of the underlying
|
---|
9526 | storage unit.
|
---|
9527 |
|
---|
9528 | For both, success and failure, this method returns the current
|
---|
9529 | state of the medium <i>before</i> the operation.
|
---|
9530 |
|
---|
9531 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9532 | Invalid medium state (e.g. not created, locked, inaccessible,
|
---|
9533 | creating, deleting).
|
---|
9534 | </result>
|
---|
9535 |
|
---|
9536 | </desc>
|
---|
9537 | <param name="state" type="MediumState" dir="return">
|
---|
9538 | <desc>
|
---|
9539 | State of the medium after the operation.
|
---|
9540 | </desc>
|
---|
9541 | </param>
|
---|
9542 | </method>
|
---|
9543 |
|
---|
9544 | <method name="unlockWrite">
|
---|
9545 | <desc>
|
---|
9546 | Cancels the write lock previously set by <link to="#lockWrite"/>.
|
---|
9547 |
|
---|
9548 | For both success and failure, this method returns the current
|
---|
9549 | state of the medium <i>after</i> the operation.
|
---|
9550 |
|
---|
9551 | See <link to="#lockWrite"/> for more details.
|
---|
9552 |
|
---|
9553 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9554 | Medium not locked for writing.
|
---|
9555 | </result>
|
---|
9556 |
|
---|
9557 | </desc>
|
---|
9558 | <param name="state" type="MediumState" dir="return">
|
---|
9559 | <desc>
|
---|
9560 | State of the medium after the operation.
|
---|
9561 | </desc>
|
---|
9562 | </param>
|
---|
9563 | </method>
|
---|
9564 |
|
---|
9565 | <method name="close">
|
---|
9566 | <desc>
|
---|
9567 | Closes this medium.
|
---|
9568 |
|
---|
9569 | The medium must not be attached to any known virtual machine
|
---|
9570 | and must not have any known child media, otherwise the
|
---|
9571 | operation will fail.
|
---|
9572 |
|
---|
9573 | When the medium is successfully closed, it is removed from
|
---|
9574 | the list of registered media, but its storage unit is not
|
---|
9575 | deleted. In particular, this means that this medium can
|
---|
9576 | later be opened again using the <link to="IVirtualBox::openMedium"/>
|
---|
9577 | call.
|
---|
9578 |
|
---|
9579 | Note that after this method successfully returns, the given medium
|
---|
9580 | object becomes uninitialized. This means that any attempt
|
---|
9581 | to call any of its methods or attributes will fail with the
|
---|
9582 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error.
|
---|
9583 |
|
---|
9584 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
9585 | Invalid medium state (other than not created, created or
|
---|
9586 | inaccessible).
|
---|
9587 | </result>
|
---|
9588 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
9589 | Medium attached to virtual machine.
|
---|
9590 | </result>
|
---|
9591 | <result name="VBOX_E_FILE_ERROR">
|
---|
9592 | Settings file not accessible.
|
---|
9593 | </result>
|
---|
9594 | <result name="VBOX_E_XML_ERROR">
|
---|
9595 | Could not parse the settings file.
|
---|
9596 | </result>
|
---|
9597 |
|
---|
9598 | </desc>
|
---|
9599 | </method>
|
---|
9600 |
|
---|
9601 | <!-- storage methods -->
|
---|
9602 |
|
---|
9603 | <method name="getProperty">
|
---|
9604 | <desc>
|
---|
9605 | Returns the value of the custom medium property with the given name.
|
---|
9606 |
|
---|
9607 | The list of all properties supported by the given medium format can
|
---|
9608 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
9609 |
|
---|
9610 | Note that if this method returns an empty string in @a value, the
|
---|
9611 | requested property is supported but currently not assigned any value.
|
---|
9612 |
|
---|
9613 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9614 | Requested property does not exist (not supported by the format).
|
---|
9615 | </result>
|
---|
9616 | <result name="E_INVALIDARG">@a name is @c null or empty.</result>
|
---|
9617 | </desc>
|
---|
9618 | <param name="name" type="wstring" dir="in">
|
---|
9619 | <desc>Name of the property to get.</desc>
|
---|
9620 | </param>
|
---|
9621 | <param name="value" type="wstring" dir="return">
|
---|
9622 | <desc>Current property value.</desc>
|
---|
9623 | </param>
|
---|
9624 | </method>
|
---|
9625 |
|
---|
9626 | <method name="setProperty">
|
---|
9627 | <desc>
|
---|
9628 | Sets the value of the custom medium property with the given name.
|
---|
9629 |
|
---|
9630 | The list of all properties supported by the given medium format can
|
---|
9631 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
9632 |
|
---|
9633 | Note that setting the property value to @c null or an empty string is
|
---|
9634 | equivalent to deleting the existing value. A default value (if it is
|
---|
9635 | defined for this property) will be used by the format backend in this
|
---|
9636 | case.
|
---|
9637 |
|
---|
9638 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
9639 | Requested property does not exist (not supported by the format).
|
---|
9640 | </result>
|
---|
9641 | <result name="E_INVALIDARG">@a name is @c null or empty.</result>
|
---|
9642 | </desc>
|
---|
9643 | <param name="name" type="wstring" dir="in">
|
---|
9644 | <desc>Name of the property to set.</desc>
|
---|
9645 | </param>
|
---|
9646 | <param name="value" type="wstring" dir="in">
|
---|
9647 | <desc>Property value to set.</desc>
|
---|
9648 | </param>
|
---|
9649 | </method>
|
---|
9650 |
|
---|
9651 | <method name="getProperties">
|
---|
9652 | <desc>
|
---|
9653 | Returns values for a group of properties in one call.
|
---|
9654 |
|
---|
9655 | The names of the properties to get are specified using the @a names
|
---|
9656 | argument which is a list of comma-separated property names or
|
---|
9657 | an empty string if all properties are to be returned. Note that currently
|
---|
9658 | the value of this argument is ignored and the method always returns all
|
---|
9659 | existing properties.
|
---|
9660 |
|
---|
9661 | The list of all properties supported by the given medium format can
|
---|
9662 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
9663 |
|
---|
9664 | The method returns two arrays, the array of property names corresponding
|
---|
9665 | to the @a names argument and the current values of these properties.
|
---|
9666 | Both arrays have the same number of elements with each elemend at the
|
---|
9667 | given index in the first array corresponds to an element at the same
|
---|
9668 | index in the second array.
|
---|
9669 |
|
---|
9670 | Note that for properties that do not have assigned values,
|
---|
9671 | an empty string is returned at the appropriate index in the
|
---|
9672 | @a returnValues array.
|
---|
9673 |
|
---|
9674 | </desc>
|
---|
9675 | <param name="names" type="wstring" dir="in">
|
---|
9676 | <desc>
|
---|
9677 | Names of properties to get.
|
---|
9678 | </desc>
|
---|
9679 | </param>
|
---|
9680 | <param name="returnNames" type="wstring" safearray="yes" dir="out">
|
---|
9681 | <desc>Names of returned properties.</desc>
|
---|
9682 | </param>
|
---|
9683 | <param name="returnValues" type="wstring" safearray="yes" dir="return">
|
---|
9684 | <desc>Values of returned properties.</desc>
|
---|
9685 | </param>
|
---|
9686 | </method>
|
---|
9687 |
|
---|
9688 | <method name="setProperties">
|
---|
9689 | <desc>
|
---|
9690 | Sets values for a group of properties in one call.
|
---|
9691 |
|
---|
9692 | The names of the properties to set are passed in the @a names
|
---|
9693 | array along with the new values for them in the @a values array. Both
|
---|
9694 | arrays have the same number of elements with each elemend at the given
|
---|
9695 | index in the first array corresponding to an element at the same index
|
---|
9696 | in the second array.
|
---|
9697 |
|
---|
9698 | If there is at least one property name in @a names that is not valid,
|
---|
9699 | the method will fail before changing the values of any other properties
|
---|
9700 | from the @a names array.
|
---|
9701 |
|
---|
9702 | Using this method over <link to="#setProperty"/> is preferred if you
|
---|
9703 | need to set several properties at once since it will result into less
|
---|
9704 | IPC calls.
|
---|
9705 |
|
---|
9706 | The list of all properties supported by the given medium format can
|
---|
9707 | be obtained with <link to="IMediumFormat::describeProperties"/>.
|
---|
9708 |
|
---|
9709 | Note that setting the property value to @c null or an empty string is
|
---|
9710 | equivalent to deleting the existing value. A default value (if it is
|
---|
9711 | defined for this property) will be used by the format backend in this
|
---|
9712 | case.
|
---|
9713 | </desc>
|
---|
9714 | <param name="names" type="wstring" safearray="yes" dir="in">
|
---|
9715 | <desc>Names of properties to set.</desc>
|
---|
9716 | </param>
|
---|
9717 | <param name="values" type="wstring" safearray="yes" dir="in">
|
---|
9718 | <desc>Values of properties to set.</desc>
|
---|
9719 | </param>
|
---|
9720 | </method>
|
---|
9721 |
|
---|
9722 | <!-- storage methods -->
|
---|
9723 |
|
---|
9724 | <method name="createBaseStorage">
|
---|
9725 | <desc>
|
---|
9726 | Starts creating a hard disk storage unit (fixed/dynamic, according
|
---|
9727 | to the variant flags) in in the background. The previous storage unit
|
---|
9728 | created for this object, if any, must first be deleted using
|
---|
9729 | <link to="#deleteStorage"/>, otherwise the operation will fail.
|
---|
9730 |
|
---|
9731 | Before the operation starts, the medium is placed in
|
---|
9732 | <link to="MediumState_Creating"/> state. If the create operation
|
---|
9733 | fails, the medium will be placed back in <link to="MediumState_NotCreated"/>
|
---|
9734 | state.
|
---|
9735 |
|
---|
9736 | After the returned progress object reports that the operation has
|
---|
9737 | successfully completed, the medium state will be set to <link
|
---|
9738 | to="MediumState_Created"/>, the medium will be remembered by this
|
---|
9739 | VirtualBox installation and may be attached to virtual machines.
|
---|
9740 |
|
---|
9741 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9742 | The variant of storage creation operation is not supported. See <link
|
---|
9743 | to="IMediumFormat::capabilities"/>.
|
---|
9744 | </result>
|
---|
9745 | </desc>
|
---|
9746 | <param name="logicalSize" type="long long" dir="in">
|
---|
9747 | <desc>Maximum logical size of the medium in bytes.</desc>
|
---|
9748 | </param>
|
---|
9749 | <param name="variant" type="MediumVariant" dir="in">
|
---|
9750 | <desc>Exact image variant which should be created.</desc>
|
---|
9751 | </param>
|
---|
9752 | <param name="progress" type="IProgress" dir="return">
|
---|
9753 | <desc>Progress object to track the operation completion.</desc>
|
---|
9754 | </param>
|
---|
9755 | </method>
|
---|
9756 |
|
---|
9757 | <method name="deleteStorage">
|
---|
9758 | <desc>
|
---|
9759 | Starts deleting the storage unit of this medium.
|
---|
9760 |
|
---|
9761 | The medium must not be attached to any known virtual machine and must
|
---|
9762 | not have any known child media, otherwise the operation will fail.
|
---|
9763 | It will also fail if there is no storage unit to delete or if deletion
|
---|
9764 | is already in progress, or if the medium is being in use (locked for
|
---|
9765 | read or for write) or inaccessible. Therefore, the only valid state for
|
---|
9766 | this operation to succeed is <link to="MediumState_Created"/>.
|
---|
9767 |
|
---|
9768 | Before the operation starts, the medium is placed in
|
---|
9769 | <link to="MediumState_Deleting"/> state and gets removed from the list
|
---|
9770 | of remembered hard disks (media registry). If the delete operation
|
---|
9771 | fails, the medium will be remembered again and placed back to
|
---|
9772 | <link to="MediumState_Created"/> state.
|
---|
9773 |
|
---|
9774 | After the returned progress object reports that the operation is
|
---|
9775 | complete, the medium state will be set to
|
---|
9776 | <link to="MediumState_NotCreated"/> and you will be able to use one of
|
---|
9777 | the storage creation methods to create it again.
|
---|
9778 |
|
---|
9779 | <see>#close()</see>
|
---|
9780 |
|
---|
9781 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
9782 | Medium is attached to a virtual machine.
|
---|
9783 | </result>
|
---|
9784 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9785 | Storage deletion is not allowed because neither of storage creation
|
---|
9786 | operations are supported. See
|
---|
9787 | <link to="IMediumFormat::capabilities"/>.
|
---|
9788 | </result>
|
---|
9789 |
|
---|
9790 | <note>
|
---|
9791 | If the deletion operation fails, it is not guaranteed that the storage
|
---|
9792 | unit still exists. You may check the <link to="IMedium::state"/> value
|
---|
9793 | to answer this question.
|
---|
9794 | </note>
|
---|
9795 | </desc>
|
---|
9796 | <param name="progress" type="IProgress" dir="return">
|
---|
9797 | <desc>Progress object to track the operation completion.</desc>
|
---|
9798 | </param>
|
---|
9799 | </method>
|
---|
9800 |
|
---|
9801 | <!-- diff methods -->
|
---|
9802 |
|
---|
9803 | <method name="createDiffStorage">
|
---|
9804 | <desc>
|
---|
9805 | Starts creating an empty differencing storage unit based on this
|
---|
9806 | medium in the format and at the location defined by the @a target
|
---|
9807 | argument.
|
---|
9808 |
|
---|
9809 | The target medium must be in <link to="MediumState_NotCreated"/>
|
---|
9810 | state (i.e. must not have an existing storage unit). Upon successful
|
---|
9811 | completion, this operation will set the type of the target medium to
|
---|
9812 | <link to="MediumType_Normal"/> and create a storage unit necessary to
|
---|
9813 | represent the differencing medium data in the given format (according
|
---|
9814 | to the storage format of the target object).
|
---|
9815 |
|
---|
9816 | After the returned progress object reports that the operation is
|
---|
9817 | successfully complete, the target medium gets remembered by this
|
---|
9818 | VirtualBox installation and may be attached to virtual machines.
|
---|
9819 |
|
---|
9820 | <note>
|
---|
9821 | The medium will be set to <link to="MediumState_LockedRead"/>
|
---|
9822 | state for the duration of this operation.
|
---|
9823 | </note>
|
---|
9824 | <result name="VBOX_E_OBJECT_IN_USE">
|
---|
9825 | Medium not in @c NotCreated state.
|
---|
9826 | </result>
|
---|
9827 | </desc>
|
---|
9828 | <param name="target" type="IMedium" dir="in">
|
---|
9829 | <desc>Target medium.</desc>
|
---|
9830 | </param>
|
---|
9831 | <param name="variant" type="MediumVariant" dir="in">
|
---|
9832 | <desc>Exact image variant which should be created.</desc>
|
---|
9833 | </param>
|
---|
9834 | <param name="progress" type="IProgress" dir="return">
|
---|
9835 | <desc>Progress object to track the operation completion.</desc>
|
---|
9836 | </param>
|
---|
9837 | </method>
|
---|
9838 |
|
---|
9839 | <method name="mergeTo">
|
---|
9840 | <desc>
|
---|
9841 | Starts merging the contents of this medium and all intermediate
|
---|
9842 | differencing media in the chain to the given target medium.
|
---|
9843 |
|
---|
9844 | The target medium must be either a descendant of this medium or
|
---|
9845 | its ancestor (otherwise this method will immediately return a failure).
|
---|
9846 | It follows that there are two logical directions of the merge operation:
|
---|
9847 | from ancestor to descendant (<i>forward merge</i>) and from descendant to
|
---|
9848 | ancestor (<i>backward merge</i>). Let us consider the following medium
|
---|
9849 | chain:
|
---|
9850 |
|
---|
9851 | <pre>Base <- Diff_1 <- Diff_2</pre>
|
---|
9852 |
|
---|
9853 | Here, calling this method on the <tt>Base</tt> medium object with
|
---|
9854 | <tt>Diff_2</tt> as an argument will be a forward merge; calling it on
|
---|
9855 | <tt>Diff_2</tt> with <tt>Base</tt> as an argument will be a backward
|
---|
9856 | merge. Note that in both cases the contents of the resulting medium
|
---|
9857 | will be the same, the only difference is the medium object that takes
|
---|
9858 | the result of the merge operation. In case of the forward merge in the
|
---|
9859 | above example, the result will be written to <tt>Diff_2</tt>; in case of
|
---|
9860 | the backward merge, the result will be written to <tt>Base</tt>. In
|
---|
9861 | other words, the result of the operation is always stored in the target
|
---|
9862 | medium.
|
---|
9863 |
|
---|
9864 | Upon successful operation completion, the storage units of all media in
|
---|
9865 | the chain between this (source) medium and the target medium, including
|
---|
9866 | the source medium itself, will be automatically deleted and the
|
---|
9867 | relevant medium objects (including this medium) will become
|
---|
9868 | uninitialized. This means that any attempt to call any of
|
---|
9869 | their methods or attributes will fail with the
|
---|
9870 | <tt>"Object not ready" (E_ACCESSDENIED)</tt> error. Applied to the above
|
---|
9871 | example, the forward merge of <tt>Base</tt> to <tt>Diff_2</tt> will
|
---|
9872 | delete and uninitialize both <tt>Base</tt> and <tt>Diff_1</tt> media.
|
---|
9873 | Note that <tt>Diff_2</tt> in this case will become a base medium
|
---|
9874 | itself since it will no longer be based on any other medium.
|
---|
9875 |
|
---|
9876 | Considering the above, all of the following conditions must be met in
|
---|
9877 | order for the merge operation to succeed:
|
---|
9878 | <ul>
|
---|
9879 | <li>
|
---|
9880 | Neither this (source) medium nor any intermediate
|
---|
9881 | differencing medium in the chain between it and the target
|
---|
9882 | medium is attached to any virtual machine.
|
---|
9883 | </li>
|
---|
9884 | <li>
|
---|
9885 | Neither the source medium nor the target medium is an
|
---|
9886 | <link to="MediumType_Immutable"/> medium.
|
---|
9887 | </li>
|
---|
9888 | <li>
|
---|
9889 | The part of the medium tree from the source medium to the
|
---|
9890 | target medium is a linear chain, i.e. all medium in this
|
---|
9891 | chain have exactly one child which is the next medium in this
|
---|
9892 | chain. The only exception from this rule is the target medium in
|
---|
9893 | the forward merge operation; it is allowed to have any number of
|
---|
9894 | child media because the merge operation will not change its
|
---|
9895 | logical contents (as it is seen by the guest OS or by children).
|
---|
9896 | </li>
|
---|
9897 | <li>
|
---|
9898 | None of the involved media are in
|
---|
9899 | <link to="MediumState_LockedRead"/> or
|
---|
9900 | <link to="MediumState_LockedWrite"/> state.
|
---|
9901 | </li>
|
---|
9902 | </ul>
|
---|
9903 |
|
---|
9904 | <note>
|
---|
9905 | This (source) medium and all intermediates will be placed to <link
|
---|
9906 | to="MediumState_Deleting"/> state and the target medium will be
|
---|
9907 | placed to <link to="MediumState_LockedWrite"/> state and for the
|
---|
9908 | duration of this operation.
|
---|
9909 | </note>
|
---|
9910 | </desc>
|
---|
9911 | <param name="target" type="IMedium" dir="in">
|
---|
9912 | <desc>Target medium.</desc>
|
---|
9913 | </param>
|
---|
9914 | <param name="progress" type="IProgress" dir="return">
|
---|
9915 | <desc>Progress object to track the operation completion.</desc>
|
---|
9916 | </param>
|
---|
9917 | </method>
|
---|
9918 |
|
---|
9919 | <!-- clone method -->
|
---|
9920 |
|
---|
9921 | <method name="cloneTo">
|
---|
9922 | <desc>
|
---|
9923 | Starts creating a clone of this medium in the format and at the
|
---|
9924 | location defined by the @a target argument.
|
---|
9925 |
|
---|
9926 | The target medium must be either in <link to="MediumState_NotCreated"/>
|
---|
9927 | state (i.e. must not have an existing storage unit) or in
|
---|
9928 | <link to="MediumState_Created"/> state (i.e. created and not locked, and
|
---|
9929 | big enough to hold the data or else the copy will be partial). Upon
|
---|
9930 | successful completion, the cloned medium will contain exactly the
|
---|
9931 | same sector data as the medium being cloned, except that in the
|
---|
9932 | first case a new UUID for the clone will be randomly generated, and in
|
---|
9933 | the second case the UUID will remain unchanged.
|
---|
9934 |
|
---|
9935 | The @a parent argument defines which medium will be the parent
|
---|
9936 | of the clone. Passing a @c null reference indicates that the clone will
|
---|
9937 | be a base image, i.e. completely independent. It is possible to specify
|
---|
9938 | an arbitrary medium for this parameter, including the parent of the
|
---|
9939 | medium which is being cloned. Even cloning to a child of the source
|
---|
9940 | medium is possible. Note that when cloning to an existing image, the
|
---|
9941 | @a parent irgument is ignored.
|
---|
9942 |
|
---|
9943 | After the returned progress object reports that the operation is
|
---|
9944 | successfully complete, the target medium gets remembered by this
|
---|
9945 | VirtualBox installation and may be attached to virtual machines.
|
---|
9946 |
|
---|
9947 | <note>
|
---|
9948 | This medium will be placed to <link to="MediumState_LockedRead"/>
|
---|
9949 | state for the duration of this operation.
|
---|
9950 | </note>
|
---|
9951 | <result name="E_NOTIMPL">
|
---|
9952 | The specified cloning variant is not supported at the moment.
|
---|
9953 | </result>
|
---|
9954 | </desc>
|
---|
9955 | <param name="target" type="IMedium" dir="in">
|
---|
9956 | <desc>Target medium.</desc>
|
---|
9957 | </param>
|
---|
9958 | <param name="variant" type="MediumVariant" dir="in">
|
---|
9959 | <desc>Exact image variant which should be created.</desc>
|
---|
9960 | </param>
|
---|
9961 | <param name="parent" type="IMedium" dir="in">
|
---|
9962 | <desc>Parent of the cloned medium.</desc>
|
---|
9963 | </param>
|
---|
9964 | <param name="progress" type="IProgress" dir="return">
|
---|
9965 | <desc>Progress object to track the operation completion.</desc>
|
---|
9966 | </param>
|
---|
9967 | </method>
|
---|
9968 |
|
---|
9969 | <!-- other methods -->
|
---|
9970 |
|
---|
9971 | <method name="compact">
|
---|
9972 | <desc>
|
---|
9973 | Starts compacting of this medium. This means that the medium is
|
---|
9974 | transformed into a possibly more compact storage representation.
|
---|
9975 | This potentially creates temporary images, which can require a
|
---|
9976 | substantial amount of additional disk space.
|
---|
9977 |
|
---|
9978 | This medium will be placed to <link to="MediumState_LockedWrite"/>
|
---|
9979 | state and all its parent media (if any) will be placed to
|
---|
9980 | <link to="MediumState_LockedRead"/> state for the duration of this
|
---|
9981 | operation.
|
---|
9982 |
|
---|
9983 | Please note that the results can be either returned straight away,
|
---|
9984 | or later as the result of the background operation via the object
|
---|
9985 | returned via the @a progress parameter.
|
---|
9986 |
|
---|
9987 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
9988 | Medium format does not support compacting (but potentially
|
---|
9989 | needs it).
|
---|
9990 | </result>
|
---|
9991 | </desc>
|
---|
9992 | <param name="progress" type="IProgress" dir="return">
|
---|
9993 | <desc>Progress object to track the operation completion.</desc>
|
---|
9994 | </param>
|
---|
9995 | </method>
|
---|
9996 |
|
---|
9997 | <method name="resize">
|
---|
9998 | <desc>
|
---|
9999 | Starts resizing this medium. This means that the nominal size of the
|
---|
10000 | medium is set to the new value. Both increasing and decreasing the
|
---|
10001 | size is possible, and there are no safety checks, since VirtualBox
|
---|
10002 | does not make any assumptions about the medium contents.
|
---|
10003 |
|
---|
10004 | Resizing usually needs additional disk space, and possibly also
|
---|
10005 | some temporary disk space. Note that resize does not create a full
|
---|
10006 | temporary copy of the medium, so the additional disk space requirement
|
---|
10007 | is usually much lower than using the clone operation.
|
---|
10008 |
|
---|
10009 | This medium will be placed to <link to="MediumState_LockedWrite"/>
|
---|
10010 | state for the duration of this operation.
|
---|
10011 |
|
---|
10012 | Please note that the results can be either returned straight away,
|
---|
10013 | or later as the result of the background operation via the object
|
---|
10014 | returned via the @a progress parameter.
|
---|
10015 |
|
---|
10016 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10017 | Medium format does not support resizing.
|
---|
10018 | </result>
|
---|
10019 | </desc>
|
---|
10020 | <param name="logicalSize" type="long long" dir="in">
|
---|
10021 | <desc>New nominal capacity of the medium in bytes.</desc>
|
---|
10022 | </param>
|
---|
10023 | <param name="progress" type="IProgress" dir="return">
|
---|
10024 | <desc>Progress object to track the operation completion.</desc>
|
---|
10025 | </param>
|
---|
10026 | </method>
|
---|
10027 |
|
---|
10028 | <method name="reset">
|
---|
10029 | <desc>
|
---|
10030 | Starts erasing the contents of this differencing medium.
|
---|
10031 |
|
---|
10032 | This operation will reset the differencing medium to its initial
|
---|
10033 | state when it does not contain any sector data and any read operation is
|
---|
10034 | redirected to its parent medium. This automatically gets called
|
---|
10035 | during VM power-up for every medium whose <link to="#autoReset" />
|
---|
10036 | attribute is @c true.
|
---|
10037 |
|
---|
10038 | The medium will be write-locked for the duration of this operation (see
|
---|
10039 | <link to="#lockWrite" />).
|
---|
10040 |
|
---|
10041 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
10042 | This is not a differencing medium.
|
---|
10043 | </result>
|
---|
10044 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
10045 | Medium is not in <link to="MediumState_Created"/> or
|
---|
10046 | <link to="MediumState_Inaccessible"/> state.
|
---|
10047 | </result>
|
---|
10048 | </desc>
|
---|
10049 | <param name="progress" type="IProgress" dir="return">
|
---|
10050 | <desc>Progress object to track the operation completion.</desc>
|
---|
10051 | </param>
|
---|
10052 | </method>
|
---|
10053 |
|
---|
10054 | </interface>
|
---|
10055 |
|
---|
10056 |
|
---|
10057 | <!--
|
---|
10058 | // IMediumFormat
|
---|
10059 | /////////////////////////////////////////////////////////////////////////
|
---|
10060 | -->
|
---|
10061 |
|
---|
10062 | <enum
|
---|
10063 | name="DataType"
|
---|
10064 | uuid="d90ea51e-a3f1-4a01-beb1-c1723c0d3ba7"
|
---|
10065 | >
|
---|
10066 | <const name="Int32" value="0"/>
|
---|
10067 | <const name="Int8" value="1"/>
|
---|
10068 | <const name="String" value="2"/>
|
---|
10069 | </enum>
|
---|
10070 |
|
---|
10071 | <enum
|
---|
10072 | name="DataFlags"
|
---|
10073 | uuid="86884dcf-1d6b-4f1b-b4bf-f5aa44959d60"
|
---|
10074 | >
|
---|
10075 | <const name="None" value="0x00"/>
|
---|
10076 | <const name="Mandatory" value="0x01"/>
|
---|
10077 | <const name="Expert" value="0x02"/>
|
---|
10078 | <const name="Array" value="0x04"/>
|
---|
10079 | <const name="FlagMask" value="0x07"/>
|
---|
10080 | </enum>
|
---|
10081 |
|
---|
10082 | <enum
|
---|
10083 | name="MediumFormatCapabilities"
|
---|
10084 | uuid="7342ba79-7ce0-4d94-8f86-5ed5a185d9bd"
|
---|
10085 | >
|
---|
10086 | <desc>
|
---|
10087 | Medium format capability flags.
|
---|
10088 | </desc>
|
---|
10089 |
|
---|
10090 | <const name="Uuid" value="0x01">
|
---|
10091 | <desc>
|
---|
10092 | Supports UUIDs as expected by VirtualBox code.
|
---|
10093 | </desc>
|
---|
10094 | </const>
|
---|
10095 |
|
---|
10096 | <const name="CreateFixed" value="0x02">
|
---|
10097 | <desc>
|
---|
10098 | Supports creating fixed size images, allocating all space instantly.
|
---|
10099 | </desc>
|
---|
10100 | </const>
|
---|
10101 |
|
---|
10102 | <const name="CreateDynamic" value="0x04">
|
---|
10103 | <desc>
|
---|
10104 | Supports creating dynamically growing images, allocating space on
|
---|
10105 | demand.
|
---|
10106 | </desc>
|
---|
10107 | </const>
|
---|
10108 |
|
---|
10109 | <const name="CreateSplit2G" value="0x08">
|
---|
10110 | <desc>
|
---|
10111 | Supports creating images split in chunks of a bit less than 2 GBytes.
|
---|
10112 | </desc>
|
---|
10113 | </const>
|
---|
10114 |
|
---|
10115 | <const name="Differencing" value="0x10">
|
---|
10116 | <desc>
|
---|
10117 | Supports being used as a format for differencing media (see <link
|
---|
10118 | to="IMedium::createDiffStorage"/>).
|
---|
10119 | </desc>
|
---|
10120 | </const>
|
---|
10121 |
|
---|
10122 | <const name="Asynchronous" value="0x20">
|
---|
10123 | <desc>
|
---|
10124 | Supports asynchronous I/O operations for at least some configurations.
|
---|
10125 | </desc>
|
---|
10126 | </const>
|
---|
10127 |
|
---|
10128 | <const name="File" value="0x40">
|
---|
10129 | <desc>
|
---|
10130 | The format backend operates on files (the <link to="IMedium::location"/>
|
---|
10131 | attribute of the medium specifies a file used to store medium
|
---|
10132 | data; for a list of supported file extensions see
|
---|
10133 | <link to="IMediumFormat::describeFileExtensions"/>).
|
---|
10134 | </desc>
|
---|
10135 | </const>
|
---|
10136 |
|
---|
10137 | <const name="Properties" value="0x80">
|
---|
10138 | <desc>
|
---|
10139 | The format backend uses the property interface to configure the storage
|
---|
10140 | location and properties (the <link to="IMediumFormat::describeProperties"/>
|
---|
10141 | method is used to get access to properties supported by the given medium format).
|
---|
10142 | </desc>
|
---|
10143 | </const>
|
---|
10144 |
|
---|
10145 | <const name="TcpNetworking" value="0x100">
|
---|
10146 | <desc>
|
---|
10147 | The format backend uses the TCP networking interface for network access.
|
---|
10148 | </desc>
|
---|
10149 | </const>
|
---|
10150 |
|
---|
10151 | <const name="VFS" value="0x200">
|
---|
10152 | <desc>
|
---|
10153 | The format backend supports virtual filesystem functionality.
|
---|
10154 | </desc>
|
---|
10155 | </const>
|
---|
10156 |
|
---|
10157 | <const name="CapabilityMask" value="0x3FF"/>
|
---|
10158 | </enum>
|
---|
10159 |
|
---|
10160 | <interface
|
---|
10161 | name="IMediumFormat" extends="$unknown"
|
---|
10162 | uuid="4e9a873f-0599-434a-8345-619ef3fb3111"
|
---|
10163 | wsmap="managed"
|
---|
10164 | >
|
---|
10165 | <desc>
|
---|
10166 | The IMediumFormat interface represents a medium format.
|
---|
10167 |
|
---|
10168 | Each medium format has an associated backend which is used to handle
|
---|
10169 | media stored in this format. This interface provides information
|
---|
10170 | about the properties of the associated backend.
|
---|
10171 |
|
---|
10172 | Each medium format is identified by a string represented by the
|
---|
10173 | <link to="#id"/> attribute. This string is used in calls like
|
---|
10174 | <link to="IVirtualBox::createHardDisk"/> to specify the desired
|
---|
10175 | format.
|
---|
10176 |
|
---|
10177 | The list of all supported medium formats can be obtained using
|
---|
10178 | <link to="ISystemProperties::mediumFormats"/>.
|
---|
10179 |
|
---|
10180 | <see>IMedium</see>
|
---|
10181 | </desc>
|
---|
10182 |
|
---|
10183 | <attribute name="id" type="wstring" readonly="yes">
|
---|
10184 | <desc>
|
---|
10185 | Identifier of this format.
|
---|
10186 |
|
---|
10187 | The format identifier is a non-@c null non-empty ASCII string. Note that
|
---|
10188 | this string is case-insensitive. This means that, for example, all of
|
---|
10189 | the following strings:
|
---|
10190 | <pre>
|
---|
10191 | "VDI"
|
---|
10192 | "vdi"
|
---|
10193 | "VdI"</pre>
|
---|
10194 | refer to the same medium format.
|
---|
10195 |
|
---|
10196 | This string is used in methods of other interfaces where it is necessary
|
---|
10197 | to specify a medium format, such as
|
---|
10198 | <link to="IVirtualBox::createHardDisk"/>.
|
---|
10199 | </desc>
|
---|
10200 | </attribute>
|
---|
10201 |
|
---|
10202 | <attribute name="name" type="wstring" readonly="yes">
|
---|
10203 | <desc>
|
---|
10204 | Human readable description of this format.
|
---|
10205 |
|
---|
10206 | Mainly for use in file open dialogs.
|
---|
10207 | </desc>
|
---|
10208 | </attribute>
|
---|
10209 |
|
---|
10210 | <attribute name="capabilities" type="unsigned long" readonly="yes">
|
---|
10211 | <desc>
|
---|
10212 | Capabilities of the format as a set of bit flags.
|
---|
10213 |
|
---|
10214 | For the meaning of individual capability flags see
|
---|
10215 | <link to="MediumFormatCapabilities"/>.
|
---|
10216 | </desc>
|
---|
10217 | </attribute>
|
---|
10218 |
|
---|
10219 | <method name="describeFileExtensions">
|
---|
10220 | <desc>
|
---|
10221 | Returns two arrays describing the supported file extensions.
|
---|
10222 |
|
---|
10223 | The first array contains the supported extensions and the seconds one
|
---|
10224 | the type each extension supports. Both have the same size.
|
---|
10225 |
|
---|
10226 | Note that some backends do not work on files, so this array may be
|
---|
10227 | empty.
|
---|
10228 |
|
---|
10229 | <see>IMediumFormat::capabilities</see>
|
---|
10230 | </desc>
|
---|
10231 | <param name="extensions" type="wstring" safearray="yes" dir="out">
|
---|
10232 | <desc>The array of supported extensions.</desc>
|
---|
10233 | </param>
|
---|
10234 | <param name="type" type="DeviceType" safearray="yes" dir="out">
|
---|
10235 | <desc>The array which indicates the device type for every given extension.</desc>
|
---|
10236 | </param>
|
---|
10237 | </method>
|
---|
10238 |
|
---|
10239 | <method name="describeProperties">
|
---|
10240 | <desc>
|
---|
10241 | Returns several arrays describing the properties supported by this
|
---|
10242 | format.
|
---|
10243 |
|
---|
10244 | An element with the given index in each array describes one
|
---|
10245 | property. Thus, the number of elements in each returned array is the
|
---|
10246 | same and corresponds to the number of supported properties.
|
---|
10247 |
|
---|
10248 | The returned arrays are filled in only if the
|
---|
10249 | <link to="MediumFormatCapabilities_Properties"/> flag is set.
|
---|
10250 | All arguments must be non-@c null.
|
---|
10251 |
|
---|
10252 | <see>DataType</see>
|
---|
10253 | <see>DataFlags</see>
|
---|
10254 | </desc>
|
---|
10255 |
|
---|
10256 | <param name="names" type="wstring" safearray="yes" dir="out">
|
---|
10257 | <desc>Array of property names.</desc>
|
---|
10258 | </param>
|
---|
10259 | <param name="description" type="wstring" safearray="yes" dir="out">
|
---|
10260 | <desc>Array of property descriptions.</desc>
|
---|
10261 | </param>
|
---|
10262 | <param name="types" type="DataType" safearray="yes" dir="out">
|
---|
10263 | <desc>Array of property types.</desc>
|
---|
10264 | </param>
|
---|
10265 | <param name="flags" type="unsigned long" safearray="yes" dir="out">
|
---|
10266 | <desc>Array of property flags.</desc>
|
---|
10267 | </param>
|
---|
10268 | <param name="defaults" type="wstring" safearray="yes" dir="out">
|
---|
10269 | <desc>Array of default property values.</desc>
|
---|
10270 | </param>
|
---|
10271 | </method>
|
---|
10272 |
|
---|
10273 | </interface>
|
---|
10274 |
|
---|
10275 |
|
---|
10276 | <!--
|
---|
10277 | // IKeyboard
|
---|
10278 | /////////////////////////////////////////////////////////////////////////
|
---|
10279 | -->
|
---|
10280 |
|
---|
10281 | <interface
|
---|
10282 | name="IKeyboard" extends="$unknown"
|
---|
10283 | uuid="f6916ec5-a881-4237-898f-7de58cf88672"
|
---|
10284 | wsmap="managed"
|
---|
10285 | >
|
---|
10286 | <desc>
|
---|
10287 | The IKeyboard interface represents the virtual machine's keyboard. Used
|
---|
10288 | in <link to="IConsole::keyboard"/>.
|
---|
10289 |
|
---|
10290 | Use this interface to send keystrokes or the Ctrl-Alt-Del sequence
|
---|
10291 | to the virtual machine.
|
---|
10292 |
|
---|
10293 | </desc>
|
---|
10294 | <method name="putScancode">
|
---|
10295 | <desc>Sends a scancode to the keyboard.
|
---|
10296 |
|
---|
10297 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10298 | Could not send scan code to virtual keyboard.
|
---|
10299 | </result>
|
---|
10300 |
|
---|
10301 | </desc>
|
---|
10302 | <param name="scancode" type="long" dir="in"/>
|
---|
10303 | </method>
|
---|
10304 |
|
---|
10305 | <method name="putScancodes">
|
---|
10306 | <desc>Sends an array of scancodes to the keyboard.
|
---|
10307 |
|
---|
10308 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10309 | Could not send all scan codes to virtual keyboard.
|
---|
10310 | </result>
|
---|
10311 |
|
---|
10312 | </desc>
|
---|
10313 | <param name="scancodes" type="long" dir="in" safearray="yes"/>
|
---|
10314 | <param name="codesStored" type="unsigned long" dir="return"/>
|
---|
10315 | </method>
|
---|
10316 |
|
---|
10317 | <method name="putCAD">
|
---|
10318 | <desc>Sends the Ctrl-Alt-Del sequence to the keyboard. This
|
---|
10319 | function is nothing special, it is just a convenience function
|
---|
10320 | calling <link to="IKeyboard::putScancodes"/> with the proper scancodes.
|
---|
10321 |
|
---|
10322 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10323 | Could not send all scan codes to virtual keyboard.
|
---|
10324 | </result>
|
---|
10325 |
|
---|
10326 | </desc>
|
---|
10327 | </method>
|
---|
10328 |
|
---|
10329 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
10330 | <desc>
|
---|
10331 | Event source for keyboard events.
|
---|
10332 | </desc>
|
---|
10333 | </attribute>
|
---|
10334 |
|
---|
10335 | </interface>
|
---|
10336 |
|
---|
10337 |
|
---|
10338 | <!--
|
---|
10339 | // IMouse
|
---|
10340 | /////////////////////////////////////////////////////////////////////////
|
---|
10341 | -->
|
---|
10342 |
|
---|
10343 | <enum
|
---|
10344 | name="MouseButtonState"
|
---|
10345 | uuid="9ee094b8-b28a-4d56-a166-973cb588d7f8"
|
---|
10346 | >
|
---|
10347 | <desc>
|
---|
10348 | Mouse button state.
|
---|
10349 | </desc>
|
---|
10350 |
|
---|
10351 | <const name="LeftButton" value="0x01"/>
|
---|
10352 | <const name="RightButton" value="0x02"/>
|
---|
10353 | <const name="MiddleButton" value="0x04"/>
|
---|
10354 | <const name="WheelUp" value="0x08"/>
|
---|
10355 | <const name="WheelDown" value="0x10"/>
|
---|
10356 | <const name="XButton1" value="0x20"/>
|
---|
10357 | <const name="XButton2" value="0x40"/>
|
---|
10358 | <const name="MouseStateMask" value="0x7F"/>
|
---|
10359 | </enum>
|
---|
10360 |
|
---|
10361 | <interface
|
---|
10362 | name="IMouse" extends="$unknown"
|
---|
10363 | uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10"
|
---|
10364 | wsmap="managed"
|
---|
10365 | >
|
---|
10366 | <desc>
|
---|
10367 | The IMouse interface represents the virtual machine's mouse. Used in
|
---|
10368 | <link to="IConsole::mouse"/>.
|
---|
10369 |
|
---|
10370 | Through this interface, the virtual machine's virtual mouse can be
|
---|
10371 | controlled.
|
---|
10372 | </desc>
|
---|
10373 |
|
---|
10374 | <attribute name="absoluteSupported" type="boolean" readonly="yes">
|
---|
10375 | <desc>
|
---|
10376 | Whether the guest OS supports absolute mouse pointer positioning
|
---|
10377 | or not.
|
---|
10378 | <note>
|
---|
10379 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
10380 | event to be instantly informed about changes of this attribute
|
---|
10381 | during virtual machine execution.
|
---|
10382 | </note>
|
---|
10383 | <see><link to="#putMouseEventAbsolute"/></see>
|
---|
10384 | </desc>
|
---|
10385 | </attribute>
|
---|
10386 |
|
---|
10387 | <attribute name="relativeSupported" type="boolean" readonly="yes">
|
---|
10388 | <desc>
|
---|
10389 | Whether the guest OS supports relative mouse pointer positioning
|
---|
10390 | or not.
|
---|
10391 | <note>
|
---|
10392 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
10393 | event to be instantly informed about changes of this attribute
|
---|
10394 | during virtual machine execution.
|
---|
10395 | </note>
|
---|
10396 | <see><link to="#putMouseEvent"/></see>
|
---|
10397 | </desc>
|
---|
10398 | </attribute>
|
---|
10399 |
|
---|
10400 | <attribute name="needsHostCursor" type="boolean" readonly="yes">
|
---|
10401 | <desc>
|
---|
10402 | Whether the guest OS can currently switch to drawing it's own mouse
|
---|
10403 | cursor on demand.
|
---|
10404 | <note>
|
---|
10405 | You can use the <link to="IMouseCapabilityChangedEvent"/>
|
---|
10406 | event to be instantly informed about changes of this attribute
|
---|
10407 | during virtual machine execution.
|
---|
10408 | </note>
|
---|
10409 | <see><link to="#putMouseEvent"/></see>
|
---|
10410 | </desc>
|
---|
10411 | </attribute>
|
---|
10412 |
|
---|
10413 | <method name="putMouseEvent">
|
---|
10414 | <desc>
|
---|
10415 | Initiates a mouse event using relative pointer movements
|
---|
10416 | along x and y axis.
|
---|
10417 |
|
---|
10418 | <result name="E_ACCESSDENIED">
|
---|
10419 | Console not powered up.
|
---|
10420 | </result>
|
---|
10421 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10422 | Could not send mouse event to virtual mouse.
|
---|
10423 | </result>
|
---|
10424 |
|
---|
10425 | </desc>
|
---|
10426 |
|
---|
10427 | <param name="dx" type="long" dir="in">
|
---|
10428 | <desc>
|
---|
10429 | Amount of pixels the mouse should move to the right.
|
---|
10430 | Negative values move the mouse to the left.
|
---|
10431 | </desc>
|
---|
10432 | </param>
|
---|
10433 | <param name="dy" type="long" dir="in">
|
---|
10434 | <desc>
|
---|
10435 | Amount of pixels the mouse should move downwards.
|
---|
10436 | Negative values move the mouse upwards.
|
---|
10437 | </desc>
|
---|
10438 | </param>
|
---|
10439 | <param name="dz" type="long" dir="in">
|
---|
10440 | <desc>
|
---|
10441 | Amount of mouse wheel moves.
|
---|
10442 | Positive values describe clockwise wheel rotations,
|
---|
10443 | negative values describe counterclockwise rotations.
|
---|
10444 | </desc>
|
---|
10445 | </param>
|
---|
10446 | <param name="dw" type="long" dir="in">
|
---|
10447 | <desc>
|
---|
10448 | Amount of horizontal mouse wheel moves.
|
---|
10449 | Positive values describe a movement to the left,
|
---|
10450 | negative values describe a movement to the right.
|
---|
10451 | </desc>
|
---|
10452 | </param>
|
---|
10453 | <param name="buttonState" type="long" dir="in">
|
---|
10454 | <desc>
|
---|
10455 | The current state of mouse buttons. Every bit represents
|
---|
10456 | a mouse button as follows:
|
---|
10457 | <table>
|
---|
10458 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
10459 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
10460 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
10461 | </table>
|
---|
10462 | A value of <tt>1</tt> means the corresponding button is pressed.
|
---|
10463 | otherwise it is released.
|
---|
10464 | </desc>
|
---|
10465 | </param>
|
---|
10466 | </method>
|
---|
10467 |
|
---|
10468 | <method name="putMouseEventAbsolute">
|
---|
10469 | <desc>
|
---|
10470 | Positions the mouse pointer using absolute x and y coordinates.
|
---|
10471 | These coordinates are expressed in pixels and
|
---|
10472 | start from <tt>[1,1]</tt> which corresponds to the top left
|
---|
10473 | corner of the virtual display.
|
---|
10474 |
|
---|
10475 | <result name="E_ACCESSDENIED">
|
---|
10476 | Console not powered up.
|
---|
10477 | </result>
|
---|
10478 | <result name="VBOX_E_IPRT_ERROR">
|
---|
10479 | Could not send mouse event to virtual mouse.
|
---|
10480 | </result>
|
---|
10481 |
|
---|
10482 | <note>
|
---|
10483 | This method will have effect only if absolute mouse
|
---|
10484 | positioning is supported by the guest OS.
|
---|
10485 | </note>
|
---|
10486 |
|
---|
10487 | <see><link to="#absoluteSupported"/></see>
|
---|
10488 | </desc>
|
---|
10489 |
|
---|
10490 | <param name="x" type="long" dir="in">
|
---|
10491 | <desc>
|
---|
10492 | X coordinate of the pointer in pixels, starting from @c 1.
|
---|
10493 | </desc>
|
---|
10494 | </param>
|
---|
10495 | <param name="y" type="long" dir="in">
|
---|
10496 | <desc>
|
---|
10497 | Y coordinate of the pointer in pixels, starting from @c 1.
|
---|
10498 | </desc>
|
---|
10499 | </param>
|
---|
10500 | <param name="dz" type="long" dir="in">
|
---|
10501 | <desc>
|
---|
10502 | Amount of mouse wheel moves.
|
---|
10503 | Positive values describe clockwise wheel rotations,
|
---|
10504 | negative values describe counterclockwise rotations.
|
---|
10505 | </desc>
|
---|
10506 | </param>
|
---|
10507 | <param name="dw" type="long" dir="in">
|
---|
10508 | <desc>
|
---|
10509 | Amount of horizontal mouse wheel moves.
|
---|
10510 | Positive values describe a movement to the left,
|
---|
10511 | negative values describe a movement to the right.
|
---|
10512 | </desc>
|
---|
10513 | </param>
|
---|
10514 | <param name="buttonState" type="long" dir="in">
|
---|
10515 | <desc>
|
---|
10516 | The current state of mouse buttons. Every bit represents
|
---|
10517 | a mouse button as follows:
|
---|
10518 | <table>
|
---|
10519 | <tr><td>Bit 0 (<tt>0x01</tt>)</td><td>left mouse button</td></tr>
|
---|
10520 | <tr><td>Bit 1 (<tt>0x02</tt>)</td><td>right mouse button</td></tr>
|
---|
10521 | <tr><td>Bit 2 (<tt>0x04</tt>)</td><td>middle mouse button</td></tr>
|
---|
10522 | </table>
|
---|
10523 | A value of @c 1 means the corresponding button is pressed.
|
---|
10524 | otherwise it is released.
|
---|
10525 | </desc>
|
---|
10526 | </param>
|
---|
10527 | </method>
|
---|
10528 |
|
---|
10529 | <attribute name="eventSource" type="IEventSource" readonly="yes">
|
---|
10530 | <desc>
|
---|
10531 | Event source for mouse events.
|
---|
10532 | </desc>
|
---|
10533 | </attribute>
|
---|
10534 |
|
---|
10535 | </interface>
|
---|
10536 |
|
---|
10537 | <!--
|
---|
10538 | // IDisplay
|
---|
10539 | /////////////////////////////////////////////////////////////////////////
|
---|
10540 | -->
|
---|
10541 |
|
---|
10542 | <enum
|
---|
10543 | name="FramebufferPixelFormat"
|
---|
10544 | uuid="7acfd5ed-29e3-45e3-8136-73c9224f3d2d"
|
---|
10545 | >
|
---|
10546 | <desc>
|
---|
10547 | Format of the video memory buffer. Constants represented by this enum can
|
---|
10548 | be used to test for particular values of <link
|
---|
10549 | to="IFramebuffer::pixelFormat"/>. See also <link
|
---|
10550 | to="IFramebuffer::requestResize"/>.
|
---|
10551 |
|
---|
10552 | See also www.fourcc.org for more information about FOURCC pixel formats.
|
---|
10553 | </desc>
|
---|
10554 |
|
---|
10555 | <const name="Opaque" value="0">
|
---|
10556 | <desc>
|
---|
10557 | Unknown buffer format (the user may not assume any particular format of
|
---|
10558 | the buffer).
|
---|
10559 | </desc>
|
---|
10560 | </const>
|
---|
10561 | <const name="FOURCC_RGB" value="0x32424752">
|
---|
10562 | <desc>
|
---|
10563 | Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the
|
---|
10564 | bit layout).
|
---|
10565 | </desc>
|
---|
10566 | </const>
|
---|
10567 | </enum>
|
---|
10568 |
|
---|
10569 | <interface
|
---|
10570 | name="IFramebuffer" extends="$unknown"
|
---|
10571 | uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf"
|
---|
10572 | wsmap="suppress"
|
---|
10573 | >
|
---|
10574 | <attribute name="address" type="octet" mod="ptr" readonly="yes">
|
---|
10575 | <desc>Address of the start byte of the frame buffer.</desc>
|
---|
10576 | </attribute>
|
---|
10577 |
|
---|
10578 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
10579 | <desc>Frame buffer width, in pixels.</desc>
|
---|
10580 | </attribute>
|
---|
10581 |
|
---|
10582 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
10583 | <desc>Frame buffer height, in pixels.</desc>
|
---|
10584 | </attribute>
|
---|
10585 |
|
---|
10586 | <attribute name="bitsPerPixel" type="unsigned long" readonly="yes">
|
---|
10587 | <desc>
|
---|
10588 | Color depth, in bits per pixel. When <link to="#pixelFormat"/> is <link
|
---|
10589 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, valid values
|
---|
10590 | are: 8, 15, 16, 24 and 32.
|
---|
10591 | </desc>
|
---|
10592 | </attribute>
|
---|
10593 |
|
---|
10594 | <attribute name="bytesPerLine" type="unsigned long" readonly="yes">
|
---|
10595 | <desc>
|
---|
10596 | Scan line size, in bytes. When <link to="#pixelFormat"/> is <link
|
---|
10597 | to="FramebufferPixelFormat_FOURCC_RGB">FOURCC_RGB</link>, the
|
---|
10598 | size of the scan line must be aligned to 32 bits.
|
---|
10599 | </desc>
|
---|
10600 | </attribute>
|
---|
10601 |
|
---|
10602 | <attribute name="pixelFormat" type="unsigned long" readonly="yes">
|
---|
10603 | <desc>
|
---|
10604 | Frame buffer pixel format. It's either one of the values defined by <link
|
---|
10605 | to="FramebufferPixelFormat"/> or a raw FOURCC code.
|
---|
10606 | <note>
|
---|
10607 | This attribute must never return <link
|
---|
10608 | to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer
|
---|
10609 | <link to="#address"/> points to must be always known.
|
---|
10610 | </note>
|
---|
10611 | </desc>
|
---|
10612 | </attribute>
|
---|
10613 |
|
---|
10614 | <attribute name="usesGuestVRAM" type="boolean" readonly="yes">
|
---|
10615 | <desc>
|
---|
10616 | Defines whether this frame buffer uses the virtual video card's memory
|
---|
10617 | buffer (guest VRAM) directly or not. See <link
|
---|
10618 | to="IFramebuffer::requestResize"/> for more information.
|
---|
10619 | </desc>
|
---|
10620 | </attribute>
|
---|
10621 |
|
---|
10622 | <attribute name="heightReduction" type="unsigned long" readonly="yes">
|
---|
10623 | <desc>
|
---|
10624 | Hint from the frame buffer about how much of the standard
|
---|
10625 | screen height it wants to use for itself. This information is
|
---|
10626 | exposed to the guest through the VESA BIOS and VMMDev interface
|
---|
10627 | so that it can use it for determining its video mode table. It
|
---|
10628 | is not guaranteed that the guest respects the value.
|
---|
10629 | </desc>
|
---|
10630 | </attribute>
|
---|
10631 |
|
---|
10632 | <attribute name="overlay" type="IFramebufferOverlay" readonly="yes">
|
---|
10633 | <desc>
|
---|
10634 | An alpha-blended overlay which is superposed over the frame buffer.
|
---|
10635 | The initial purpose is to allow the display of icons providing
|
---|
10636 | information about the VM state, including disk activity, in front
|
---|
10637 | ends which do not have other means of doing that. The overlay is
|
---|
10638 | designed to controlled exclusively by IDisplay. It has no locking
|
---|
10639 | of its own, and any changes made to it are not guaranteed to be
|
---|
10640 | visible until the affected portion of IFramebuffer is updated. The
|
---|
10641 | overlay can be created lazily the first time it is requested. This
|
---|
10642 | attribute can also return @c null to signal that the overlay is not
|
---|
10643 | implemented.
|
---|
10644 | </desc>
|
---|
10645 | </attribute>
|
---|
10646 |
|
---|
10647 | <attribute name="winId" type="long long" readonly="yes">
|
---|
10648 | <desc>
|
---|
10649 | Platform-dependent identifier of the window where context of this
|
---|
10650 | frame buffer is drawn, or zero if there's no such window.
|
---|
10651 | </desc>
|
---|
10652 | </attribute>
|
---|
10653 |
|
---|
10654 | <method name="lock">
|
---|
10655 | <desc>
|
---|
10656 | Locks the frame buffer.
|
---|
10657 | Gets called by the IDisplay object where this frame buffer is
|
---|
10658 | bound to.
|
---|
10659 | </desc>
|
---|
10660 | </method>
|
---|
10661 |
|
---|
10662 | <method name="unlock">
|
---|
10663 | <desc>
|
---|
10664 | Unlocks the frame buffer.
|
---|
10665 | Gets called by the IDisplay object where this frame buffer is
|
---|
10666 | bound to.
|
---|
10667 | </desc>
|
---|
10668 | </method>
|
---|
10669 |
|
---|
10670 | <method name="notifyUpdate">
|
---|
10671 | <desc>
|
---|
10672 | Informs about an update.
|
---|
10673 | Gets called by the display object where this buffer is
|
---|
10674 | registered.
|
---|
10675 | </desc>
|
---|
10676 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10677 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10678 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10679 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10680 | </method>
|
---|
10681 |
|
---|
10682 | <method name="requestResize">
|
---|
10683 | <desc>
|
---|
10684 | Requests a size and pixel format change.
|
---|
10685 |
|
---|
10686 | There are two modes of working with the video buffer of the virtual
|
---|
10687 | machine. The <i>indirect</i> mode implies that the IFramebuffer
|
---|
10688 | implementation allocates a memory buffer for the requested display mode
|
---|
10689 | and provides it to the virtual machine. In <i>direct</i> mode, the
|
---|
10690 | IFramebuffer implementation uses the memory buffer allocated and owned
|
---|
10691 | by the virtual machine. This buffer represents the video memory of the
|
---|
10692 | emulated video adapter (so called <i>guest VRAM</i>). The direct mode is
|
---|
10693 | usually faster because the implementation gets a raw pointer to the
|
---|
10694 | guest VRAM buffer which it can directly use for visualizing the contents
|
---|
10695 | of the virtual display, as opposed to the indirect mode where the
|
---|
10696 | contents of guest VRAM are copied to the memory buffer provided by
|
---|
10697 | the implementation every time a display update occurs.
|
---|
10698 |
|
---|
10699 | It is important to note that the direct mode is really fast only when
|
---|
10700 | the implementation uses the given guest VRAM buffer directly, for
|
---|
10701 | example, by blitting it to the window representing the virtual machine's
|
---|
10702 | display, which saves at least one copy operation comparing to the
|
---|
10703 | indirect mode. However, using the guest VRAM buffer directly is not
|
---|
10704 | always possible: the format and the color depth of this buffer may be
|
---|
10705 | not supported by the target window, or it may be unknown (opaque) as in
|
---|
10706 | case of text or non-linear multi-plane VGA video modes. In this case,
|
---|
10707 | the indirect mode (that is always available) should be used as a
|
---|
10708 | fallback: when the guest VRAM contents are copied to the
|
---|
10709 | implementation-provided memory buffer, color and format conversion is
|
---|
10710 | done automatically by the underlying code.
|
---|
10711 |
|
---|
10712 | The @a pixelFormat parameter defines whether the direct mode is
|
---|
10713 | available or not. If @a pixelFormat is <link
|
---|
10714 | to="FramebufferPixelFormat_Opaque"/> then direct access to the guest
|
---|
10715 | VRAM buffer is not available -- the @a VRAM, @a bitsPerPixel and
|
---|
10716 | @a bytesPerLine parameters must be ignored and the implementation must use
|
---|
10717 | the indirect mode (where it provides its own buffer in one of the
|
---|
10718 | supported formats). In all other cases, @a pixelFormat together with
|
---|
10719 | @a bitsPerPixel and @a bytesPerLine define the format of the video memory
|
---|
10720 | buffer pointed to by the @a VRAM parameter and the implementation is
|
---|
10721 | free to choose which mode to use. To indicate that this frame buffer uses
|
---|
10722 | the direct mode, the implementation of the <link to="#usesGuestVRAM"/>
|
---|
10723 | attribute must return @c true and <link to="#address"/> must
|
---|
10724 | return exactly the same address that is passed in the @a VRAM parameter
|
---|
10725 | of this method; otherwise it is assumed that the indirect strategy is
|
---|
10726 | chosen.
|
---|
10727 |
|
---|
10728 | The @a width and @a height parameters represent the size of the
|
---|
10729 | requested display mode in both modes. In case of indirect mode, the
|
---|
10730 | provided memory buffer should be big enough to store data of the given
|
---|
10731 | display mode. In case of direct mode, it is guaranteed that the given
|
---|
10732 | @a VRAM buffer contains enough space to represent the display mode of the
|
---|
10733 | given size. Note that this frame buffer's <link to="#width"/> and <link
|
---|
10734 | to="#height"/> attributes must return exactly the same values as
|
---|
10735 | passed to this method after the resize is completed (see below).
|
---|
10736 |
|
---|
10737 | The @a finished output parameter determines if the implementation has
|
---|
10738 | finished resizing the frame buffer or not. If, for some reason, the
|
---|
10739 | resize cannot be finished immediately during this call, @a finished
|
---|
10740 | must be set to @c false, and the implementation must call
|
---|
10741 | <link to="IDisplay::resizeCompleted"/> after it has returned from
|
---|
10742 | this method as soon as possible. If @a finished is @c false, the
|
---|
10743 | machine will not call any frame buffer methods until
|
---|
10744 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
10745 |
|
---|
10746 | Note that if the direct mode is chosen, the <link to="#bitsPerPixel"/>,
|
---|
10747 | <link to="#bytesPerLine"/> and <link to="#pixelFormat"/> attributes of
|
---|
10748 | this frame buffer must return exactly the same values as specified in the
|
---|
10749 | parameters of this method, after the resize is completed. If the
|
---|
10750 | indirect mode is chosen, these attributes must return values describing
|
---|
10751 | the format of the implementation's own memory buffer <link
|
---|
10752 | to="#address"/> points to. Note also that the <link to="#bitsPerPixel"/>
|
---|
10753 | value must always correlate with <link to="#pixelFormat"/>. Note that
|
---|
10754 | the <link to="#pixelFormat"/> attribute must never return <link
|
---|
10755 | to="FramebufferPixelFormat_Opaque"/> regardless of the selected mode.
|
---|
10756 |
|
---|
10757 | <note>
|
---|
10758 | This method is called by the IDisplay object under the
|
---|
10759 | <link to="#lock"/> provided by this IFramebuffer
|
---|
10760 | implementation. If this method returns @c false in @a finished, then
|
---|
10761 | this lock is not released until
|
---|
10762 | <link to="IDisplay::resizeCompleted"/> is called.
|
---|
10763 | </note>
|
---|
10764 | </desc>
|
---|
10765 | <param name="screenId" type="unsigned long" dir="in">
|
---|
10766 | <desc>
|
---|
10767 | Logical screen number. Must be used in the corresponding call to
|
---|
10768 | <link to="IDisplay::resizeCompleted"/> if this call is made.
|
---|
10769 | </desc>
|
---|
10770 | </param>
|
---|
10771 | <param name="pixelFormat" type="unsigned long" dir="in">
|
---|
10772 | <desc>
|
---|
10773 | Pixel format of the memory buffer pointed to by @a VRAM.
|
---|
10774 | See also <link to="FramebufferPixelFormat"/>.
|
---|
10775 | </desc>
|
---|
10776 | </param>
|
---|
10777 | <param name="VRAM" type="octet" mod="ptr" dir="in">
|
---|
10778 | <desc>Pointer to the virtual video card's VRAM (may be @c null).</desc>
|
---|
10779 | </param>
|
---|
10780 | <param name="bitsPerPixel" type="unsigned long" dir="in">
|
---|
10781 | <desc>Color depth, bits per pixel.</desc>
|
---|
10782 | </param>
|
---|
10783 | <param name="bytesPerLine" type="unsigned long" dir="in">
|
---|
10784 | <desc>Size of one scan line, in bytes.</desc>
|
---|
10785 | </param>
|
---|
10786 | <param name="width" type="unsigned long" dir="in">
|
---|
10787 | <desc>Width of the guest display, in pixels.</desc>
|
---|
10788 | </param>
|
---|
10789 | <param name="height" type="unsigned long" dir="in">
|
---|
10790 | <desc>Height of the guest display, in pixels.</desc>
|
---|
10791 | </param>
|
---|
10792 | <param name="finished" type="boolean" dir="return">
|
---|
10793 | <desc>
|
---|
10794 | Can the VM start using the new frame buffer immediately
|
---|
10795 | after this method returns or it should wait for
|
---|
10796 | <link to="IDisplay::resizeCompleted"/>.
|
---|
10797 | </desc>
|
---|
10798 | </param>
|
---|
10799 | </method>
|
---|
10800 |
|
---|
10801 | <method name="videoModeSupported">
|
---|
10802 | <desc>
|
---|
10803 | Returns whether the frame buffer implementation is willing to
|
---|
10804 | support a given video mode. In case it is not able to render
|
---|
10805 | the video mode (or for some reason not willing), it should
|
---|
10806 | return @c false. Usually this method is called when the guest
|
---|
10807 | asks the VMM device whether a given video mode is supported
|
---|
10808 | so the information returned is directly exposed to the guest.
|
---|
10809 | It is important that this method returns very quickly.
|
---|
10810 | </desc>
|
---|
10811 | <param name="width" type="unsigned long" dir="in"/>
|
---|
10812 | <param name="height" type="unsigned long" dir="in"/>
|
---|
10813 | <param name="bpp" type="unsigned long" dir="in"/>
|
---|
10814 | <param name="supported" type="boolean" dir="return"/>
|
---|
10815 | </method>
|
---|
10816 |
|
---|
10817 | <method name="getVisibleRegion">
|
---|
10818 | <desc>
|
---|
10819 | Returns the visible region of this frame buffer.
|
---|
10820 |
|
---|
10821 | If the @a rectangles parameter is @c null then the value of the
|
---|
10822 | @a count parameter is ignored and the number of elements necessary to
|
---|
10823 | describe the current visible region is returned in @a countCopied.
|
---|
10824 |
|
---|
10825 | If @a rectangles is not @c null but @a count is less
|
---|
10826 | than the required number of elements to store region data, the method
|
---|
10827 | will report a failure. If @a count is equal or greater than the
|
---|
10828 | required number of elements, then the actual number of elements copied
|
---|
10829 | to the provided array will be returned in @a countCopied.
|
---|
10830 |
|
---|
10831 | <note>
|
---|
10832 | The address of the provided array must be in the process space of
|
---|
10833 | this IFramebuffer object.
|
---|
10834 | </note>
|
---|
10835 | <note>
|
---|
10836 | Method not yet implemented.
|
---|
10837 | </note>
|
---|
10838 | </desc>
|
---|
10839 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
10840 | <desc>Pointer to the @c RTRECT array to receive region data.</desc>
|
---|
10841 | </param>
|
---|
10842 | <param name="count" type="unsigned long" dir="in">
|
---|
10843 | <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
|
---|
10844 | </param>
|
---|
10845 | <param name="countCopied" type="unsigned long" dir="return">
|
---|
10846 | <desc>Number of elements copied to the @a rectangles array.</desc>
|
---|
10847 | </param>
|
---|
10848 | </method>
|
---|
10849 |
|
---|
10850 | <method name="setVisibleRegion">
|
---|
10851 | <desc>
|
---|
10852 | Suggests a new visible region to this frame buffer. This region
|
---|
10853 | represents the area of the VM display which is a union of regions of
|
---|
10854 | all top-level windows of the guest operating system running inside the
|
---|
10855 | VM (if the Guest Additions for this system support this
|
---|
10856 | functionality). This information may be used by the frontends to
|
---|
10857 | implement the seamless desktop integration feature.
|
---|
10858 |
|
---|
10859 | <note>
|
---|
10860 | The address of the provided array must be in the process space of
|
---|
10861 | this IFramebuffer object.
|
---|
10862 | </note>
|
---|
10863 | <note>
|
---|
10864 | The IFramebuffer implementation must make a copy of the provided
|
---|
10865 | array of rectangles.
|
---|
10866 | </note>
|
---|
10867 | <note>
|
---|
10868 | Method not yet implemented.
|
---|
10869 | </note>
|
---|
10870 | </desc>
|
---|
10871 | <param name="rectangles" type="octet" mod="ptr" dir="in">
|
---|
10872 | <desc>Pointer to the @c RTRECT array.</desc>
|
---|
10873 | </param>
|
---|
10874 | <param name="count" type="unsigned long" dir="in">
|
---|
10875 | <desc>Number of @c RTRECT elements in the @a rectangles array.</desc>
|
---|
10876 | </param>
|
---|
10877 | </method>
|
---|
10878 |
|
---|
10879 | <method name="processVHWACommand">
|
---|
10880 | <desc>
|
---|
10881 | Posts a Video HW Acceleration Command to the frame buffer for processing.
|
---|
10882 | The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.)
|
---|
10883 | are posted from quest to the host to be processed by the host hardware.
|
---|
10884 |
|
---|
10885 | <note>
|
---|
10886 | The address of the provided command must be in the process space of
|
---|
10887 | this IFramebuffer object.
|
---|
10888 | </note>
|
---|
10889 | </desc>
|
---|
10890 |
|
---|
10891 | <param name="command" type="octet" mod="ptr" dir="in">
|
---|
10892 | <desc>Pointer to VBOXVHWACMD containing the command to execute.</desc>
|
---|
10893 | </param>
|
---|
10894 | </method>
|
---|
10895 |
|
---|
10896 | </interface>
|
---|
10897 |
|
---|
10898 | <interface
|
---|
10899 | name="IFramebufferOverlay" extends="IFramebuffer"
|
---|
10900 | uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47"
|
---|
10901 | wsmap="suppress"
|
---|
10902 | >
|
---|
10903 | <desc>
|
---|
10904 | The IFramebufferOverlay interface represents an alpha blended overlay
|
---|
10905 | for displaying status icons above an IFramebuffer. It is always created
|
---|
10906 | not visible, so that it must be explicitly shown. It only covers a
|
---|
10907 | portion of the IFramebuffer, determined by its width, height and
|
---|
10908 | co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in
|
---|
10909 | that order) format, and may be written to directly. Do re-read the
|
---|
10910 | width though, after setting it, as it may be adjusted (increased) to
|
---|
10911 | make it more suitable for the front end.
|
---|
10912 | </desc>
|
---|
10913 | <attribute name="x" type="unsigned long" readonly="yes">
|
---|
10914 | <desc>X position of the overlay, relative to the frame buffer.</desc>
|
---|
10915 | </attribute>
|
---|
10916 |
|
---|
10917 | <attribute name="y" type="unsigned long" readonly="yes">
|
---|
10918 | <desc>Y position of the overlay, relative to the frame buffer.</desc>
|
---|
10919 | </attribute>
|
---|
10920 |
|
---|
10921 | <attribute name="visible" type="boolean" readonly="no">
|
---|
10922 | <desc>
|
---|
10923 | Whether the overlay is currently visible.
|
---|
10924 | </desc>
|
---|
10925 | </attribute>
|
---|
10926 |
|
---|
10927 | <attribute name="alpha" type="unsigned long" readonly="no">
|
---|
10928 | <desc>
|
---|
10929 | The global alpha value for the overlay. This may or may not be
|
---|
10930 | supported by a given front end.
|
---|
10931 | </desc>
|
---|
10932 | </attribute>
|
---|
10933 |
|
---|
10934 | <method name="move">
|
---|
10935 | <desc>
|
---|
10936 | Changes the overlay's position relative to the IFramebuffer.
|
---|
10937 | </desc>
|
---|
10938 | <param name="x" type="unsigned long" dir="in"/>
|
---|
10939 | <param name="y" type="unsigned long" dir="in"/>
|
---|
10940 | </method>
|
---|
10941 |
|
---|
10942 | </interface>
|
---|
10943 |
|
---|
10944 | <interface
|
---|
10945 | name="IDisplay" extends="$unknown"
|
---|
10946 | uuid="09EED313-CD56-4D06-BD56-FAC0F716B5DD"
|
---|
10947 | wsmap="managed"
|
---|
10948 | >
|
---|
10949 | <desc>
|
---|
10950 | The IDisplay interface represents the virtual machine's display.
|
---|
10951 |
|
---|
10952 | The object implementing this interface is contained in each
|
---|
10953 | <link to="IConsole::display"/> attribute and represents the visual
|
---|
10954 | output of the virtual machine.
|
---|
10955 |
|
---|
10956 | The virtual display supports pluggable output targets represented by the
|
---|
10957 | IFramebuffer interface. Examples of the output target are a window on
|
---|
10958 | the host computer or an RDP session's display on a remote computer.
|
---|
10959 | </desc>
|
---|
10960 | <method name="getScreenResolution">
|
---|
10961 | <desc>Queries display width, height and color depth for given screen.</desc>
|
---|
10962 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10963 | <param name="width" type="unsigned long" dir="out"/>
|
---|
10964 | <param name="height" type="unsigned long" dir="out"/>
|
---|
10965 | <param name="bitsPerPixel" type="unsigned long" dir="out"/>
|
---|
10966 | </method>
|
---|
10967 |
|
---|
10968 | <method name="setFramebuffer">
|
---|
10969 | <desc>
|
---|
10970 | Sets the framebuffer for given screen.
|
---|
10971 | </desc>
|
---|
10972 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10973 | <param name="framebuffer" type="IFramebuffer" dir="in"/>
|
---|
10974 | </method>
|
---|
10975 |
|
---|
10976 | <method name="getFramebuffer">
|
---|
10977 | <desc>
|
---|
10978 | Queries the framebuffer for given screen.
|
---|
10979 | </desc>
|
---|
10980 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
10981 | <param name="framebuffer" type="IFramebuffer" dir="out"/>
|
---|
10982 | <param name="xOrigin" type="long" dir="out"/>
|
---|
10983 | <param name="yOrigin" type="long" dir="out"/>
|
---|
10984 | </method>
|
---|
10985 |
|
---|
10986 | <method name="setVideoModeHint">
|
---|
10987 | <desc>
|
---|
10988 | Asks VirtualBox to request the given video mode from
|
---|
10989 | the guest. This is just a hint and it cannot be guaranteed
|
---|
10990 | that the requested resolution will be used. Guest Additions
|
---|
10991 | are required for the request to be seen by guests. The caller
|
---|
10992 | should issue the request and wait for a resolution change and
|
---|
10993 | after a timeout retry.
|
---|
10994 |
|
---|
10995 | Specifying @c 0 for either @a width, @a height or @a bitsPerPixel
|
---|
10996 | parameters means that the corresponding values should be taken from the
|
---|
10997 | current video mode (i.e. left unchanged).
|
---|
10998 |
|
---|
10999 | If the guest OS supports multi-monitor configuration then the @a display
|
---|
11000 | parameter specifies the number of the guest display to send the hint to:
|
---|
11001 | @c 0 is the primary display, @c 1 is the first secondary and
|
---|
11002 | so on. If the multi-monitor configuration is not supported, @a display
|
---|
11003 | must be @c 0.
|
---|
11004 |
|
---|
11005 | <result name="E_INVALIDARG">
|
---|
11006 | The @a display is not associated with any monitor.
|
---|
11007 | </result>
|
---|
11008 |
|
---|
11009 | </desc>
|
---|
11010 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11011 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11012 | <param name="bitsPerPixel" type="unsigned long" dir="in"/>
|
---|
11013 | <param name="display" type="unsigned long" dir="in"/>
|
---|
11014 | </method>
|
---|
11015 |
|
---|
11016 | <method name="setSeamlessMode">
|
---|
11017 | <desc>
|
---|
11018 | Enables or disables seamless guest display rendering (seamless desktop
|
---|
11019 | integration) mode.
|
---|
11020 | <note>
|
---|
11021 | Calling this method has no effect if <link
|
---|
11022 | to="IGuest::supportsSeamless"/> returns @c false.
|
---|
11023 | </note>
|
---|
11024 | </desc>
|
---|
11025 | <param name="enabled" type="boolean" dir="in"/>
|
---|
11026 | </method>
|
---|
11027 |
|
---|
11028 | <method name="takeScreenShot">
|
---|
11029 | <desc>
|
---|
11030 | Takes a screen shot of the requested size and copies it to the
|
---|
11031 | 32-bpp buffer allocated by the caller and pointed to by @a address.
|
---|
11032 | A pixel consists of 4 bytes in order: B, G, R, 0.
|
---|
11033 |
|
---|
11034 | <note>This API can be used only by the COM/XPCOM C++ API as it
|
---|
11035 | requires pointer support. Use <link to="#takeScreenShotToArray" />
|
---|
11036 | with other language bindings.
|
---|
11037 | </note>
|
---|
11038 |
|
---|
11039 | <result name="E_NOTIMPL">
|
---|
11040 | Feature not implemented.
|
---|
11041 | </result>
|
---|
11042 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11043 | Could not take a screenshot.
|
---|
11044 | </result>
|
---|
11045 |
|
---|
11046 | </desc>
|
---|
11047 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11048 | <param name="address" type="octet" mod="ptr" dir="in"/>
|
---|
11049 | <param name="width" type="unsigned long" dir="in"/>
|
---|
11050 | <param name="height" type="unsigned long" dir="in"/>
|
---|
11051 | </method>
|
---|
11052 |
|
---|
11053 | <method name="takeScreenShotToArray">
|
---|
11054 | <desc>
|
---|
11055 | Takes a guest screen shot of the requested size and returns it as
|
---|
11056 | an array of bytes in uncompressed 32-bit RGBA format.
|
---|
11057 | A pixel consists of 4 bytes in order: R, G, B, 0xFF.
|
---|
11058 |
|
---|
11059 | This API is slow, but could be the only option to get guest screenshot
|
---|
11060 | for scriptable languages not allowed to manipulate with addresses
|
---|
11061 | directly.
|
---|
11062 |
|
---|
11063 | <result name="E_NOTIMPL">
|
---|
11064 | Feature not implemented.
|
---|
11065 | </result>
|
---|
11066 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11067 | Could not take a screenshot.
|
---|
11068 | </result>
|
---|
11069 | </desc>
|
---|
11070 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11071 | <desc>
|
---|
11072 | Monitor to take screenshot from.
|
---|
11073 | </desc>
|
---|
11074 | </param>
|
---|
11075 | <param name="width" type="unsigned long" dir="in">
|
---|
11076 | <desc>
|
---|
11077 | Desired image width.
|
---|
11078 | </desc>
|
---|
11079 | </param>
|
---|
11080 | <param name="height" type="unsigned long" dir="in">
|
---|
11081 | <desc>
|
---|
11082 | Desired image height.
|
---|
11083 | </desc>
|
---|
11084 | </param>
|
---|
11085 | <param name="screenData" type="octet" dir="return" safearray="yes">
|
---|
11086 | <desc>
|
---|
11087 | Array with resulting screen data.
|
---|
11088 | </desc>
|
---|
11089 | </param>
|
---|
11090 | </method>
|
---|
11091 |
|
---|
11092 | <method name="takeScreenShotPNGToArray">
|
---|
11093 | <desc>
|
---|
11094 | Takes a guest screen shot of the requested size and returns it as
|
---|
11095 | PNG image in array.
|
---|
11096 |
|
---|
11097 | <result name="E_NOTIMPL">
|
---|
11098 | Feature not implemented.
|
---|
11099 | </result>
|
---|
11100 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11101 | Could not take a screenshot.
|
---|
11102 | </result>
|
---|
11103 | </desc>
|
---|
11104 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11105 | <desc>
|
---|
11106 | Monitor to take the screenshot from.
|
---|
11107 | </desc>
|
---|
11108 | </param>
|
---|
11109 | <param name="width" type="unsigned long" dir="in">
|
---|
11110 | <desc>
|
---|
11111 | Desired image width.
|
---|
11112 | </desc>
|
---|
11113 | </param>
|
---|
11114 | <param name="height" type="unsigned long" dir="in">
|
---|
11115 | <desc>
|
---|
11116 | Desired image height.
|
---|
11117 | </desc>
|
---|
11118 | </param>
|
---|
11119 | <param name="screenData" type="octet" dir="return" safearray="yes">
|
---|
11120 | <desc>
|
---|
11121 | Array with resulting screen data.
|
---|
11122 | </desc>
|
---|
11123 | </param>
|
---|
11124 | </method>
|
---|
11125 |
|
---|
11126 | <method name="drawToScreen">
|
---|
11127 | <desc>
|
---|
11128 | Draws a 32-bpp image of the specified size from the given buffer
|
---|
11129 | to the given point on the VM display.
|
---|
11130 |
|
---|
11131 | <result name="E_NOTIMPL">
|
---|
11132 | Feature not implemented.
|
---|
11133 | </result>
|
---|
11134 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11135 | Could not draw to screen.
|
---|
11136 | </result>
|
---|
11137 |
|
---|
11138 | </desc>
|
---|
11139 | <param name="screenId" type="unsigned long" dir="in">
|
---|
11140 | <desc>
|
---|
11141 | Monitor to take the screenshot from.
|
---|
11142 | </desc>
|
---|
11143 | </param>
|
---|
11144 | <param name="address" type="octet" mod="ptr" dir="in">
|
---|
11145 | <desc>
|
---|
11146 | Address to store the screenshot to
|
---|
11147 | </desc>
|
---|
11148 | </param>
|
---|
11149 | <param name="x" type="unsigned long" dir="in">
|
---|
11150 | <desc>
|
---|
11151 | Relative to the screen top left corner.
|
---|
11152 | </desc>
|
---|
11153 | </param>
|
---|
11154 | <param name="y" type="unsigned long" dir="in">
|
---|
11155 | <desc>
|
---|
11156 | Relative to the screen top left corner.
|
---|
11157 | </desc>
|
---|
11158 | </param>
|
---|
11159 | <param name="width" type="unsigned long" dir="in">
|
---|
11160 | <desc>
|
---|
11161 | Desired image width.
|
---|
11162 | </desc>
|
---|
11163 | </param>
|
---|
11164 | <param name="height" type="unsigned long" dir="in">
|
---|
11165 | <desc>
|
---|
11166 | Desired image height.
|
---|
11167 | </desc>
|
---|
11168 | </param>
|
---|
11169 | </method>
|
---|
11170 |
|
---|
11171 | <method name="invalidateAndUpdate">
|
---|
11172 | <desc>
|
---|
11173 | Does a full invalidation of the VM display and instructs the VM
|
---|
11174 | to update it.
|
---|
11175 |
|
---|
11176 | <result name="VBOX_E_IPRT_ERROR">
|
---|
11177 | Could not invalidate and update screen.
|
---|
11178 | </result>
|
---|
11179 |
|
---|
11180 | </desc>
|
---|
11181 | </method>
|
---|
11182 |
|
---|
11183 | <method name="resizeCompleted">
|
---|
11184 | <desc>
|
---|
11185 | Signals that a framebuffer has completed the resize operation.
|
---|
11186 |
|
---|
11187 | <result name="VBOX_E_NOT_SUPPORTED">
|
---|
11188 | Operation only valid for external frame buffers.
|
---|
11189 | </result>
|
---|
11190 |
|
---|
11191 | </desc>
|
---|
11192 | <param name="screenId" type="unsigned long" dir="in"/>
|
---|
11193 | </method>
|
---|
11194 |
|
---|
11195 | <method name="completeVHWACommand">
|
---|
11196 | <desc>
|
---|
11197 | Signals that the Video HW Acceleration command has completed.
|
---|
11198 | </desc>
|
---|
11199 |
|
---|
11200 | <param name="command" type="octet" mod="ptr" dir="in">
|
---|
11201 | <desc>Pointer to VBOXVHWACMD containing the completed command.</desc>
|
---|
11202 | </param>
|
---|
11203 | </method>
|
---|
11204 |
|
---|
11205 | </interface>
|
---|
11206 |
|
---|
11207 | <!--
|
---|
11208 | // INetworkAdapter
|
---|
11209 | /////////////////////////////////////////////////////////////////////////
|
---|
11210 | -->
|
---|
11211 |
|
---|
11212 | <enum
|
---|
11213 | name="NetworkAttachmentType"
|
---|
11214 | uuid="44bce1ee-99f7-4e8e-89fc-80597fd9eeaf"
|
---|
11215 | >
|
---|
11216 | <desc>
|
---|
11217 | Network attachment type.
|
---|
11218 | </desc>
|
---|
11219 |
|
---|
11220 | <const name="Null" value="0">
|
---|
11221 | <desc>Null value, also means "not attached".</desc>
|
---|
11222 | </const>
|
---|
11223 | <const name="NAT" value="1"/>
|
---|
11224 | <const name="Bridged" value="2"/>
|
---|
11225 | <const name="Internal" value="3"/>
|
---|
11226 | <const name="HostOnly" value="4"/>
|
---|
11227 | <const name="VDE" value="5"/>
|
---|
11228 | </enum>
|
---|
11229 |
|
---|
11230 | <enum
|
---|
11231 | name="NetworkAdapterType"
|
---|
11232 | uuid="3c2281e4-d952-4e87-8c7d-24379cb6a81c"
|
---|
11233 | >
|
---|
11234 | <desc>
|
---|
11235 | Network adapter type.
|
---|
11236 | </desc>
|
---|
11237 |
|
---|
11238 | <const name="Null" value="0">
|
---|
11239 | <desc>Null value (never used by the API).</desc>
|
---|
11240 | </const>
|
---|
11241 | <const name="Am79C970A" value="1">
|
---|
11242 | <desc>AMD PCNet-PCI II network card (Am79C970A).</desc>
|
---|
11243 | </const>
|
---|
11244 | <const name="Am79C973" value="2">
|
---|
11245 | <desc>AMD PCNet-FAST III network card (Am79C973).</desc>
|
---|
11246 | </const>
|
---|
11247 | <const name="I82540EM" value="3">
|
---|
11248 | <desc>Intel PRO/1000 MT Desktop network card (82540EM).</desc>
|
---|
11249 | </const>
|
---|
11250 | <const name="I82543GC" value="4">
|
---|
11251 | <desc>Intel PRO/1000 T Server network card (82543GC).</desc>
|
---|
11252 | </const>
|
---|
11253 | <const name="I82545EM" value="5">
|
---|
11254 | <desc>Intel PRO/1000 MT Server network card (82545EM).</desc>
|
---|
11255 | </const>
|
---|
11256 | <const name="Virtio" value="6">
|
---|
11257 | <desc>Virtio network device.</desc>
|
---|
11258 | </const>
|
---|
11259 | </enum>
|
---|
11260 |
|
---|
11261 | <interface
|
---|
11262 | name="INetworkAdapter" extends="$unknown"
|
---|
11263 | uuid="9bf58a46-c3f7-4f31-80fa-dde9a5dc0b7b"
|
---|
11264 | wsmap="managed"
|
---|
11265 | >
|
---|
11266 | <desc>
|
---|
11267 | Represents a virtual network adapter that is attached to a virtual machine.
|
---|
11268 | Each virtual machine has a fixed number of network adapter slots with one
|
---|
11269 | instance of this attached to each of them. Call
|
---|
11270 | <link to="IMachine::getNetworkAdapter" /> to get the network adapter that
|
---|
11271 | is attached to a given slot in a given machine.
|
---|
11272 |
|
---|
11273 | Each network adapter can be in one of five attachment modes, which are
|
---|
11274 | represented by the <link to="NetworkAttachmentType" /> enumeration;
|
---|
11275 | see the <link to="#attachmentType" /> attribute.
|
---|
11276 | </desc>
|
---|
11277 |
|
---|
11278 | <attribute name="adapterType" type="NetworkAdapterType">
|
---|
11279 | <desc>
|
---|
11280 | Type of the virtual network adapter. Depending on this value,
|
---|
11281 | VirtualBox will provide a different virtual network hardware
|
---|
11282 | to the guest.
|
---|
11283 | </desc>
|
---|
11284 | </attribute>
|
---|
11285 |
|
---|
11286 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11287 | <desc>
|
---|
11288 | Slot number this adapter is plugged into. Corresponds to
|
---|
11289 | the value you pass to <link to="IMachine::getNetworkAdapter"/>
|
---|
11290 | to obtain this instance.
|
---|
11291 | </desc>
|
---|
11292 | </attribute>
|
---|
11293 |
|
---|
11294 | <attribute name="enabled" type="boolean">
|
---|
11295 | <desc>
|
---|
11296 | Flag whether the network adapter is present in the
|
---|
11297 | guest system. If disabled, the virtual guest hardware will
|
---|
11298 | not contain this network adapter. Can only be changed when
|
---|
11299 | the VM is not running.
|
---|
11300 | </desc>
|
---|
11301 | </attribute>
|
---|
11302 |
|
---|
11303 | <attribute name="MACAddress" type="wstring">
|
---|
11304 | <desc>
|
---|
11305 | Ethernet MAC address of the adapter, 12 hexadecimal characters. When setting
|
---|
11306 | it to @c null or an empty string, VirtualBox will generate a unique MAC address.
|
---|
11307 | </desc>
|
---|
11308 | </attribute>
|
---|
11309 |
|
---|
11310 | <attribute name="attachmentType" type="NetworkAttachmentType" readonly="yes"/>
|
---|
11311 |
|
---|
11312 | <attribute name="hostInterface" type="wstring">
|
---|
11313 | <desc>
|
---|
11314 | Name of the host network interface the VM is attached to.
|
---|
11315 | </desc>
|
---|
11316 | </attribute>
|
---|
11317 |
|
---|
11318 | <attribute name="internalNetwork" type="wstring">
|
---|
11319 | <desc>
|
---|
11320 | Name of the internal network the VM is attached to.
|
---|
11321 | </desc>
|
---|
11322 | </attribute>
|
---|
11323 |
|
---|
11324 | <attribute name="NATNetwork" type="wstring">
|
---|
11325 | <desc>
|
---|
11326 | Name of the NAT network the VM is attached to.
|
---|
11327 | </desc>
|
---|
11328 | </attribute>
|
---|
11329 |
|
---|
11330 | <attribute name="VDENetwork" type="wstring">
|
---|
11331 | <desc>
|
---|
11332 | Name of the VDE switch the VM is attached to.
|
---|
11333 | </desc>
|
---|
11334 | </attribute>
|
---|
11335 |
|
---|
11336 | <attribute name="cableConnected" type="boolean">
|
---|
11337 | <desc>
|
---|
11338 | Flag whether the adapter reports the cable as connected or not.
|
---|
11339 | It can be used to report offline situations to a VM.
|
---|
11340 | </desc>
|
---|
11341 | </attribute>
|
---|
11342 |
|
---|
11343 | <attribute name="lineSpeed" type="unsigned long">
|
---|
11344 | <desc>
|
---|
11345 | Line speed reported by custom drivers, in units of 1 kbps.
|
---|
11346 | </desc>
|
---|
11347 | </attribute>
|
---|
11348 |
|
---|
11349 | <attribute name="traceEnabled" type="boolean">
|
---|
11350 | <desc>
|
---|
11351 | Flag whether network traffic from/to the network card should be traced.
|
---|
11352 | Can only be toggled when the VM is turned off.
|
---|
11353 | </desc>
|
---|
11354 | </attribute>
|
---|
11355 |
|
---|
11356 | <attribute name="traceFile" type="wstring">
|
---|
11357 | <desc>
|
---|
11358 | Filename where a network trace will be stored. If not set, VBox-pid.pcap
|
---|
11359 | will be used.
|
---|
11360 | </desc>
|
---|
11361 | </attribute>
|
---|
11362 |
|
---|
11363 | <attribute name="natDriver" type="INATEngine" readonly="yes">
|
---|
11364 | <desc>
|
---|
11365 | Points to the NAT engine which handles the network address translation
|
---|
11366 | for this interface. This is active only when the interface actually uses
|
---|
11367 | NAT (see <link to="#attachToNAT" />).
|
---|
11368 | </desc>
|
---|
11369 | </attribute>
|
---|
11370 |
|
---|
11371 | <attribute name="bootPriority" type="unsigned long">
|
---|
11372 | <desc>
|
---|
11373 | Network boot priority of the adapter. Priority 1 is highest. If not set,
|
---|
11374 | the priority is considered to be at the lowest possible setting.
|
---|
11375 | </desc>
|
---|
11376 | </attribute>
|
---|
11377 |
|
---|
11378 | <attribute name="bandwidthLimit" type="unsigned long">
|
---|
11379 | <desc>
|
---|
11380 | Maximum throughput allowed for this network adapter, in units of 1 mbps.
|
---|
11381 | A zero value means uncapped/unlimited.
|
---|
11382 | </desc>
|
---|
11383 | </attribute>
|
---|
11384 |
|
---|
11385 | <method name="attachToNAT">
|
---|
11386 | <desc>
|
---|
11387 | Attach the network adapter to the Network Address Translation (NAT) interface.
|
---|
11388 | </desc>
|
---|
11389 | </method>
|
---|
11390 |
|
---|
11391 | <method name="attachToBridgedInterface">
|
---|
11392 | <desc>
|
---|
11393 | Attach the network adapter to a bridged host interface.
|
---|
11394 | </desc>
|
---|
11395 | </method>
|
---|
11396 |
|
---|
11397 | <method name="attachToInternalNetwork">
|
---|
11398 | <desc>
|
---|
11399 | Attach the network adapter to an internal network.
|
---|
11400 | </desc>
|
---|
11401 | </method>
|
---|
11402 |
|
---|
11403 | <method name="attachToHostOnlyInterface">
|
---|
11404 | <desc>
|
---|
11405 | Attach the network adapter to the host-only network.
|
---|
11406 | </desc>
|
---|
11407 | </method>
|
---|
11408 |
|
---|
11409 | <method name="attachToVDE">
|
---|
11410 | <desc>
|
---|
11411 | Attach the network adapter to a VDE network.
|
---|
11412 | </desc>
|
---|
11413 | </method>
|
---|
11414 |
|
---|
11415 | <method name="detach">
|
---|
11416 | <desc>
|
---|
11417 | Detach the network adapter
|
---|
11418 | </desc>
|
---|
11419 | </method>
|
---|
11420 | </interface>
|
---|
11421 |
|
---|
11422 |
|
---|
11423 | <!--
|
---|
11424 | // ISerialPort
|
---|
11425 | /////////////////////////////////////////////////////////////////////////
|
---|
11426 | -->
|
---|
11427 |
|
---|
11428 | <enum
|
---|
11429 | name="PortMode"
|
---|
11430 | uuid="533b5fe3-0185-4197-86a7-17e37dd39d76"
|
---|
11431 | >
|
---|
11432 | <desc>
|
---|
11433 | The PortMode enumeration represents possible communication modes for
|
---|
11434 | the virtual serial port device.
|
---|
11435 | </desc>
|
---|
11436 |
|
---|
11437 | <const name="Disconnected" value="0">
|
---|
11438 | <desc>Virtual device is not attached to any real host device.</desc>
|
---|
11439 | </const>
|
---|
11440 | <const name="HostPipe" value="1">
|
---|
11441 | <desc>Virtual device is attached to a host pipe.</desc>
|
---|
11442 | </const>
|
---|
11443 | <const name="HostDevice" value="2">
|
---|
11444 | <desc>Virtual device is attached to a host device.</desc>
|
---|
11445 | </const>
|
---|
11446 | <const name="RawFile" value="3">
|
---|
11447 | <desc>Virtual device is attached to a raw file.</desc>
|
---|
11448 | </const>
|
---|
11449 | </enum>
|
---|
11450 |
|
---|
11451 | <interface
|
---|
11452 | name="ISerialPort" extends="$unknown"
|
---|
11453 | uuid="937f6970-5103-4745-b78e-d28dcf1479a8"
|
---|
11454 | wsmap="managed"
|
---|
11455 | >
|
---|
11456 |
|
---|
11457 | <desc>
|
---|
11458 | The ISerialPort interface represents the virtual serial port device.
|
---|
11459 |
|
---|
11460 | The virtual serial port device acts like an ordinary serial port
|
---|
11461 | inside the virtual machine. This device communicates to the real
|
---|
11462 | serial port hardware in one of two modes: host pipe or host device.
|
---|
11463 |
|
---|
11464 | In host pipe mode, the #path attribute specifies the path to the pipe on
|
---|
11465 | the host computer that represents a serial port. The #server attribute
|
---|
11466 | determines if this pipe is created by the virtual machine process at
|
---|
11467 | machine startup or it must already exist before starting machine
|
---|
11468 | execution.
|
---|
11469 |
|
---|
11470 | In host device mode, the #path attribute specifies the name of the
|
---|
11471 | serial port device on the host computer.
|
---|
11472 |
|
---|
11473 | There is also a third communication mode: the disconnected mode. In this
|
---|
11474 | mode, the guest OS running inside the virtual machine will be able to
|
---|
11475 | detect the serial port, but all port write operations will be discarded
|
---|
11476 | and all port read operations will return no data.
|
---|
11477 |
|
---|
11478 | <see>IMachine::getSerialPort</see>
|
---|
11479 | </desc>
|
---|
11480 |
|
---|
11481 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11482 | <desc>
|
---|
11483 | Slot number this serial port is plugged into. Corresponds to
|
---|
11484 | the value you pass to <link to="IMachine::getSerialPort"/>
|
---|
11485 | to obtain this instance.
|
---|
11486 | </desc>
|
---|
11487 | </attribute>
|
---|
11488 |
|
---|
11489 | <attribute name="enabled" type="boolean">
|
---|
11490 | <desc>
|
---|
11491 | Flag whether the serial port is enabled. If disabled,
|
---|
11492 | the serial port will not be reported to the guest OS.
|
---|
11493 | </desc>
|
---|
11494 | </attribute>
|
---|
11495 |
|
---|
11496 | <attribute name="IOBase" type="unsigned long">
|
---|
11497 | <desc>Base I/O address of the serial port.</desc>
|
---|
11498 | </attribute>
|
---|
11499 |
|
---|
11500 | <attribute name="IRQ" type="unsigned long">
|
---|
11501 | <desc>IRQ number of the serial port.</desc>
|
---|
11502 | </attribute>
|
---|
11503 |
|
---|
11504 | <attribute name="hostMode" type="PortMode">
|
---|
11505 | <desc>
|
---|
11506 | How is this port connected to the host.
|
---|
11507 | <note>
|
---|
11508 | Changing this attribute may fail if the conditions for
|
---|
11509 | <link to="#path"/> are not met.
|
---|
11510 | </note>
|
---|
11511 | </desc>
|
---|
11512 | </attribute>
|
---|
11513 |
|
---|
11514 | <attribute name="server" type="boolean">
|
---|
11515 | <desc>
|
---|
11516 | Flag whether this serial port acts as a server (creates a new pipe on
|
---|
11517 | the host) or as a client (uses the existing pipe). This attribute is
|
---|
11518 | used only when <link to="#hostMode"/> is PortMode_HostPipe.
|
---|
11519 | </desc>
|
---|
11520 | </attribute>
|
---|
11521 |
|
---|
11522 | <attribute name="path" type="wstring">
|
---|
11523 | <desc>
|
---|
11524 | Path to the serial port's pipe on the host when <link to="ISerialPort::hostMode"/> is
|
---|
11525 | PortMode_HostPipe, or the host serial device name when
|
---|
11526 | <link to="ISerialPort::hostMode"/> is PortMode_HostDevice. For both
|
---|
11527 | cases, setting a @c null or empty string as the attribute's value
|
---|
11528 | is an error. Otherwise, the value of this property is ignored.
|
---|
11529 | </desc>
|
---|
11530 | </attribute>
|
---|
11531 |
|
---|
11532 | </interface>
|
---|
11533 |
|
---|
11534 | <!--
|
---|
11535 | // IParallelPort
|
---|
11536 | /////////////////////////////////////////////////////////////////////////
|
---|
11537 | -->
|
---|
11538 |
|
---|
11539 | <interface
|
---|
11540 | name="IParallelPort" extends="$unknown"
|
---|
11541 | uuid="0c925f06-dd10-4b77-8de8-294d738c3214"
|
---|
11542 | wsmap="managed"
|
---|
11543 | >
|
---|
11544 |
|
---|
11545 | <desc>
|
---|
11546 | The IParallelPort interface represents the virtual parallel port device.
|
---|
11547 |
|
---|
11548 | The virtual parallel port device acts like an ordinary parallel port
|
---|
11549 | inside the virtual machine. This device communicates to the real
|
---|
11550 | parallel port hardware using the name of the parallel device on the host
|
---|
11551 | computer specified in the #path attribute.
|
---|
11552 |
|
---|
11553 | Each virtual parallel port device is assigned a base I/O address and an
|
---|
11554 | IRQ number that will be reported to the guest operating system and used
|
---|
11555 | to operate the given parallel port from within the virtual machine.
|
---|
11556 |
|
---|
11557 | <see>IMachine::getParallelPort</see>
|
---|
11558 | </desc>
|
---|
11559 |
|
---|
11560 | <attribute name="slot" type="unsigned long" readonly="yes">
|
---|
11561 | <desc>
|
---|
11562 | Slot number this parallel port is plugged into. Corresponds to
|
---|
11563 | the value you pass to <link to="IMachine::getParallelPort"/>
|
---|
11564 | to obtain this instance.
|
---|
11565 | </desc>
|
---|
11566 | </attribute>
|
---|
11567 |
|
---|
11568 | <attribute name="enabled" type="boolean">
|
---|
11569 | <desc>
|
---|
11570 | Flag whether the parallel port is enabled. If disabled,
|
---|
11571 | the parallel port will not be reported to the guest OS.
|
---|
11572 | </desc>
|
---|
11573 | </attribute>
|
---|
11574 |
|
---|
11575 | <attribute name="IOBase" type="unsigned long">
|
---|
11576 | <desc>Base I/O address of the parallel port.</desc>
|
---|
11577 | </attribute>
|
---|
11578 |
|
---|
11579 | <attribute name="IRQ" type="unsigned long">
|
---|
11580 | <desc>IRQ number of the parallel port.</desc>
|
---|
11581 | </attribute>
|
---|
11582 |
|
---|
11583 | <attribute name="path" type="wstring">
|
---|
11584 | <desc>
|
---|
11585 | Host parallel device name. If this parallel port is enabled, setting a
|
---|
11586 | @c null or an empty string as this attribute's value will result into
|
---|
11587 | an error.
|
---|
11588 | </desc>
|
---|
11589 | </attribute>
|
---|
11590 |
|
---|
11591 | </interface>
|
---|
11592 |
|
---|
11593 |
|
---|
11594 | <!--
|
---|
11595 | // IMachineDebugger
|
---|
11596 | /////////////////////////////////////////////////////////////////////////
|
---|
11597 | -->
|
---|
11598 |
|
---|
11599 | <interface
|
---|
11600 | name="IMachineDebugger" extends="$unknown"
|
---|
11601 | uuid="b0b2a2dd-0627-4502-91c2-ddc5e77609e0"
|
---|
11602 | wsmap="suppress"
|
---|
11603 | >
|
---|
11604 | <method name="resetStats">
|
---|
11605 | <desc>
|
---|
11606 | Reset VM statistics.
|
---|
11607 | </desc>
|
---|
11608 | <param name="pattern" type="wstring" dir="in">
|
---|
11609 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11610 | </param>
|
---|
11611 | </method>
|
---|
11612 |
|
---|
11613 | <method name="dumpStats">
|
---|
11614 | <desc>
|
---|
11615 | Dumps VM statistics.
|
---|
11616 | </desc>
|
---|
11617 | <param name="pattern" type="wstring" dir="in">
|
---|
11618 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11619 | </param>
|
---|
11620 | </method>
|
---|
11621 |
|
---|
11622 | <method name="getStats">
|
---|
11623 | <desc>
|
---|
11624 | Get the VM statistics in a XMLish format.
|
---|
11625 | </desc>
|
---|
11626 | <param name="pattern" type="wstring" dir="in">
|
---|
11627 | <desc>The selection pattern. A bit similar to filename globbing.</desc>
|
---|
11628 | </param>
|
---|
11629 | <param name="withDescriptions" type="boolean" dir="in">
|
---|
11630 | <desc>Whether to include the descriptions.</desc>
|
---|
11631 | </param>
|
---|
11632 | <param name="stats" type="wstring" dir="out">
|
---|
11633 | <desc>The XML document containing the statistics.</desc>
|
---|
11634 | </param>
|
---|
11635 | </method>
|
---|
11636 |
|
---|
11637 | <method name="injectNMI">
|
---|
11638 | <desc>
|
---|
11639 | Inject an NMI into a running VT-x/AMD-V VM.
|
---|
11640 | </desc>
|
---|
11641 | </method>
|
---|
11642 |
|
---|
11643 | <attribute name="singlestep" type="boolean">
|
---|
11644 | <desc>Switch for enabling singlestepping.</desc>
|
---|
11645 | </attribute>
|
---|
11646 |
|
---|
11647 | <attribute name="recompileUser" type="boolean">
|
---|
11648 | <desc>Switch for forcing code recompilation for user mode code.</desc>
|
---|
11649 | </attribute>
|
---|
11650 |
|
---|
11651 | <attribute name="recompileSupervisor" type="boolean">
|
---|
11652 | <desc>Switch for forcing code recompilation for supervisor mode code.</desc>
|
---|
11653 | </attribute>
|
---|
11654 |
|
---|
11655 | <attribute name="PATMEnabled" type="boolean">
|
---|
11656 | <desc>Switch for enabling and disabling the PATM component.</desc>
|
---|
11657 | </attribute>
|
---|
11658 |
|
---|
11659 | <attribute name="CSAMEnabled" type="boolean">
|
---|
11660 | <desc>Switch for enabling and disabling the CSAM component.</desc>
|
---|
11661 | </attribute>
|
---|
11662 |
|
---|
11663 | <attribute name="logEnabled" type="boolean">
|
---|
11664 | <desc>Switch for enabling and disabling logging.</desc>
|
---|
11665 | </attribute>
|
---|
11666 |
|
---|
11667 | <attribute name="HWVirtExEnabled" type="boolean" readonly="yes">
|
---|
11668 | <desc>
|
---|
11669 | Flag indicating whether the VM is currently making use of CPU hardware
|
---|
11670 | virtualization extensions.
|
---|
11671 | </desc>
|
---|
11672 | </attribute>
|
---|
11673 |
|
---|
11674 | <attribute name="HWVirtExNestedPagingEnabled" type="boolean" readonly="yes">
|
---|
11675 | <desc>
|
---|
11676 | Flag indicating whether the VM is currently making use of the nested paging
|
---|
11677 | CPU hardware virtualization extension.
|
---|
11678 | </desc>
|
---|
11679 | </attribute>
|
---|
11680 |
|
---|
11681 | <attribute name="HWVirtExVPIDEnabled" type="boolean" readonly="yes">
|
---|
11682 | <desc>
|
---|
11683 | Flag indicating whether the VM is currently making use of the VPID
|
---|
11684 | VT-x extension.
|
---|
11685 | </desc>
|
---|
11686 | </attribute>
|
---|
11687 |
|
---|
11688 | <attribute name="PAEEnabled" type="boolean" readonly="yes">
|
---|
11689 | <desc>
|
---|
11690 | Flag indicating whether the VM is currently making use of the Physical
|
---|
11691 | Address Extension CPU feature.
|
---|
11692 | </desc>
|
---|
11693 | </attribute>
|
---|
11694 |
|
---|
11695 | <attribute name="virtualTimeRate" type="unsigned long">
|
---|
11696 | <desc>
|
---|
11697 | The rate at which the virtual time runs expressed as a percentage.
|
---|
11698 | The accepted range is 2% to 20000%.
|
---|
11699 | </desc>
|
---|
11700 | </attribute>
|
---|
11701 |
|
---|
11702 | <!-- @todo method for setting log flags, groups and destination! -->
|
---|
11703 |
|
---|
11704 | <attribute name="VM" type="long long" readonly="yes">
|
---|
11705 | <desc>
|
---|
11706 | Gets the VM handle. This is only for internal use while
|
---|
11707 | we carve the details of this interface.
|
---|
11708 | </desc>
|
---|
11709 | </attribute>
|
---|
11710 |
|
---|
11711 | </interface>
|
---|
11712 |
|
---|
11713 | <!--
|
---|
11714 | // IUSBController
|
---|
11715 | /////////////////////////////////////////////////////////////////////////
|
---|
11716 | -->
|
---|
11717 |
|
---|
11718 | <interface
|
---|
11719 | name="IUSBController" extends="$unknown"
|
---|
11720 | uuid="6fdcccc5-abd3-4fec-9387-2ad3914fc4a8"
|
---|
11721 | wsmap="managed"
|
---|
11722 | >
|
---|
11723 | <attribute name="enabled" type="boolean">
|
---|
11724 | <desc>
|
---|
11725 | Flag whether the USB controller is present in the
|
---|
11726 | guest system. If disabled, the virtual guest hardware will
|
---|
11727 | not contain any USB controller. Can only be changed when
|
---|
11728 | the VM is powered off.
|
---|
11729 | </desc>
|
---|
11730 | </attribute>
|
---|
11731 |
|
---|
11732 | <attribute name="enabledEhci" type="boolean">
|
---|
11733 | <desc>
|
---|
11734 | Flag whether the USB EHCI controller is present in the
|
---|
11735 | guest system. If disabled, the virtual guest hardware will
|
---|
11736 | not contain a USB EHCI controller. Can only be changed when
|
---|
11737 | the VM is powered off.
|
---|
11738 | </desc>
|
---|
11739 | </attribute>
|
---|
11740 |
|
---|
11741 | <attribute name="proxyAvailable" type="boolean" readonly="yes">
|
---|
11742 | <desc>
|
---|
11743 | Flag whether there is an USB proxy available.
|
---|
11744 | </desc>
|
---|
11745 | </attribute>
|
---|
11746 |
|
---|
11747 | <attribute name="USBStandard" type="unsigned short" readonly="yes">
|
---|
11748 | <desc>
|
---|
11749 | USB standard version which the controller implements.
|
---|
11750 | This is a BCD which means that the major version is in the
|
---|
11751 | high byte and minor version is in the low byte.
|
---|
11752 | </desc>
|
---|
11753 | </attribute>
|
---|
11754 |
|
---|
11755 | <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes">
|
---|
11756 | <desc>
|
---|
11757 | List of USB device filters associated with the machine.
|
---|
11758 |
|
---|
11759 | If the machine is currently running, these filters are activated
|
---|
11760 | every time a new (supported) USB device is attached to the host
|
---|
11761 | computer that was not ignored by global filters
|
---|
11762 | (<link to="IHost::USBDeviceFilters"/>).
|
---|
11763 |
|
---|
11764 | These filters are also activated when the machine is powered up.
|
---|
11765 | They are run against a list of all currently available USB
|
---|
11766 | devices (in states
|
---|
11767 | <link to="USBDeviceState_Available"/>,
|
---|
11768 | <link to="USBDeviceState_Busy"/>,
|
---|
11769 | <link to="USBDeviceState_Held"/>) that were not previously
|
---|
11770 | ignored by global filters.
|
---|
11771 |
|
---|
11772 | If at least one filter matches the USB device in question, this
|
---|
11773 | device is automatically captured (attached to) the virtual USB
|
---|
11774 | controller of this machine.
|
---|
11775 |
|
---|
11776 | <see>IUSBDeviceFilter, ::IUSBController</see>
|
---|
11777 | </desc>
|
---|
11778 | </attribute>
|
---|
11779 |
|
---|
11780 | <method name="createDeviceFilter">
|
---|
11781 | <desc>
|
---|
11782 | Creates a new USB device filter. All attributes except
|
---|
11783 | the filter name are set to empty (any match),
|
---|
11784 | <i>active</i> is @c false (the filter is not active).
|
---|
11785 |
|
---|
11786 | The created filter can then be added to the list of filters using
|
---|
11787 | <link to="#insertDeviceFilter"/>.
|
---|
11788 |
|
---|
11789 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11790 | The virtual machine is not mutable.
|
---|
11791 | </result>
|
---|
11792 |
|
---|
11793 | <see>#deviceFilters</see>
|
---|
11794 | </desc>
|
---|
11795 | <param name="name" type="wstring" dir="in">
|
---|
11796 | <desc>
|
---|
11797 | Filter name. See <link to="IUSBDeviceFilter::name"/>
|
---|
11798 | for more info.
|
---|
11799 | </desc>
|
---|
11800 | </param>
|
---|
11801 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
11802 | <desc>Created filter object.</desc>
|
---|
11803 | </param>
|
---|
11804 | </method>
|
---|
11805 |
|
---|
11806 | <method name="insertDeviceFilter">
|
---|
11807 | <desc>
|
---|
11808 | Inserts the given USB device to the specified position
|
---|
11809 | in the list of filters.
|
---|
11810 |
|
---|
11811 | Positions are numbered starting from <tt>0</tt>. If the specified
|
---|
11812 | position is equal to or greater than the number of elements in
|
---|
11813 | the list, the filter is added to the end of the collection.
|
---|
11814 |
|
---|
11815 | <note>
|
---|
11816 | Duplicates are not allowed, so an attempt to insert a
|
---|
11817 | filter that is already in the collection, will return an
|
---|
11818 | error.
|
---|
11819 | </note>
|
---|
11820 |
|
---|
11821 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11822 | Virtual machine is not mutable.
|
---|
11823 | </result>
|
---|
11824 | <result name="E_INVALIDARG">
|
---|
11825 | USB device filter not created within this VirtualBox instance.
|
---|
11826 | </result>
|
---|
11827 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
11828 | USB device filter already in list.
|
---|
11829 | </result>
|
---|
11830 |
|
---|
11831 | <see>#deviceFilters</see>
|
---|
11832 | </desc>
|
---|
11833 | <param name="position" type="unsigned long" dir="in">
|
---|
11834 | <desc>Position to insert the filter to.</desc>
|
---|
11835 | </param>
|
---|
11836 | <param name="filter" type="IUSBDeviceFilter" dir="in">
|
---|
11837 | <desc>USB device filter to insert.</desc>
|
---|
11838 | </param>
|
---|
11839 | </method>
|
---|
11840 |
|
---|
11841 | <method name="removeDeviceFilter">
|
---|
11842 | <desc>
|
---|
11843 | Removes a USB device filter from the specified position in the
|
---|
11844 | list of filters.
|
---|
11845 |
|
---|
11846 | Positions are numbered starting from <tt>0</tt>. Specifying a
|
---|
11847 | position equal to or greater than the number of elements in
|
---|
11848 | the list will produce an error.
|
---|
11849 |
|
---|
11850 | <see>#deviceFilters</see>
|
---|
11851 |
|
---|
11852 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
11853 | Virtual machine is not mutable.
|
---|
11854 | </result>
|
---|
11855 | <result name="E_INVALIDARG">
|
---|
11856 | USB device filter list empty or invalid @a position.
|
---|
11857 | </result>
|
---|
11858 |
|
---|
11859 | </desc>
|
---|
11860 | <param name="position" type="unsigned long" dir="in">
|
---|
11861 | <desc>Position to remove the filter from.</desc>
|
---|
11862 | </param>
|
---|
11863 | <param name="filter" type="IUSBDeviceFilter" dir="return">
|
---|
11864 | <desc>Removed USB device filter.</desc>
|
---|
11865 | </param>
|
---|
11866 | </method>
|
---|
11867 |
|
---|
11868 | </interface>
|
---|
11869 |
|
---|
11870 |
|
---|
11871 | <!--
|
---|
11872 | // IUSBDevice
|
---|
11873 | /////////////////////////////////////////////////////////////////////////
|
---|
11874 | -->
|
---|
11875 |
|
---|
11876 | <interface
|
---|
11877 | name="IUSBDevice" extends="$unknown"
|
---|
11878 | uuid="f8967b0b-4483-400f-92b5-8b675d98a85b"
|
---|
11879 | wsmap="managed"
|
---|
11880 | >
|
---|
11881 | <desc>
|
---|
11882 | The IUSBDevice interface represents a virtual USB device attached to the
|
---|
11883 | virtual machine.
|
---|
11884 |
|
---|
11885 | A collection of objects implementing this interface is stored in the
|
---|
11886 | <link to="IConsole::USBDevices"/> attribute which lists all USB devices
|
---|
11887 | attached to a running virtual machine's USB controller.
|
---|
11888 | </desc>
|
---|
11889 |
|
---|
11890 | <attribute name="id" type="uuid" mod="string" readonly="yes">
|
---|
11891 | <desc>
|
---|
11892 | Unique USB device ID. This ID is built from #vendorId,
|
---|
11893 | #productId, #revision and #serialNumber.
|
---|
11894 | </desc>
|
---|
11895 | </attribute>
|
---|
11896 |
|
---|
11897 | <attribute name="vendorId" type="unsigned short" readonly="yes">
|
---|
11898 | <desc>Vendor ID.</desc>
|
---|
11899 | </attribute>
|
---|
11900 |
|
---|
11901 | <attribute name="productId" type="unsigned short" readonly="yes">
|
---|
11902 | <desc>Product ID.</desc>
|
---|
11903 | </attribute>
|
---|
11904 |
|
---|
11905 | <attribute name="revision" type="unsigned short" readonly="yes">
|
---|
11906 | <desc>
|
---|
11907 | Product revision number. This is a packed BCD represented as
|
---|
11908 | unsigned short. The high byte is the integer part and the low
|
---|
11909 | byte is the decimal.
|
---|
11910 | </desc>
|
---|
11911 | </attribute>
|
---|
11912 |
|
---|
11913 | <attribute name="manufacturer" type="wstring" readonly="yes">
|
---|
11914 | <desc>Manufacturer string.</desc>
|
---|
11915 | </attribute>
|
---|
11916 |
|
---|
11917 | <attribute name="product" type="wstring" readonly="yes">
|
---|
11918 | <desc>Product string.</desc>
|
---|
11919 | </attribute>
|
---|
11920 |
|
---|
11921 | <attribute name="serialNumber" type="wstring" readonly="yes">
|
---|
11922 | <desc>Serial number string.</desc>
|
---|
11923 | </attribute>
|
---|
11924 |
|
---|
11925 | <attribute name="address" type="wstring" readonly="yes">
|
---|
11926 | <desc>Host specific address of the device.</desc>
|
---|
11927 | </attribute>
|
---|
11928 |
|
---|
11929 | <attribute name="port" type="unsigned short" readonly="yes">
|
---|
11930 | <desc>
|
---|
11931 | Host USB port number the device is physically
|
---|
11932 | connected to.
|
---|
11933 | </desc>
|
---|
11934 | </attribute>
|
---|
11935 |
|
---|
11936 | <attribute name="version" type="unsigned short" readonly="yes">
|
---|
11937 | <desc>
|
---|
11938 | The major USB version of the device - 1 or 2.
|
---|
11939 | </desc>
|
---|
11940 | </attribute>
|
---|
11941 |
|
---|
11942 | <attribute name="portVersion" type="unsigned short" readonly="yes">
|
---|
11943 | <desc>
|
---|
11944 | The major USB version of the host USB port the device is
|
---|
11945 | physically connected to - 1 or 2. For devices not connected to
|
---|
11946 | anything this will have the same value as the version attribute.
|
---|
11947 | </desc>
|
---|
11948 | </attribute>
|
---|
11949 |
|
---|
11950 | <attribute name="remote" type="boolean" readonly="yes">
|
---|
11951 | <desc>
|
---|
11952 | Whether the device is physically connected to a remote VRDE
|
---|
11953 | client or to a local host machine.
|
---|
11954 | </desc>
|
---|
11955 | </attribute>
|
---|
11956 |
|
---|
11957 | </interface>
|
---|
11958 |
|
---|
11959 |
|
---|
11960 | <!--
|
---|
11961 | // IUSBDeviceFilter
|
---|
11962 | /////////////////////////////////////////////////////////////////////////
|
---|
11963 | -->
|
---|
11964 |
|
---|
11965 | <interface
|
---|
11966 | name="IUSBDeviceFilter" extends="$unknown"
|
---|
11967 | uuid="d6831fb4-1a94-4c2c-96ef-8d0d6192066d"
|
---|
11968 | wsmap="managed"
|
---|
11969 | >
|
---|
11970 | <desc>
|
---|
11971 | The IUSBDeviceFilter interface represents an USB device filter used
|
---|
11972 | to perform actions on a group of USB devices.
|
---|
11973 |
|
---|
11974 | This type of filters is used by running virtual machines to
|
---|
11975 | automatically capture selected USB devices once they are physically
|
---|
11976 | attached to the host computer.
|
---|
11977 |
|
---|
11978 | A USB device is matched to the given device filter if and only if all
|
---|
11979 | attributes of the device match the corresponding attributes of the
|
---|
11980 | filter (that is, attributes are joined together using the logical AND
|
---|
11981 | operation). On the other hand, all together, filters in the list of
|
---|
11982 | filters carry the semantics of the logical OR operation. So if it is
|
---|
11983 | desirable to create a match like "this vendor id OR this product id",
|
---|
11984 | one needs to create two filters and specify "any match" (see below)
|
---|
11985 | for unused attributes.
|
---|
11986 |
|
---|
11987 | All filter attributes used for matching are strings. Each string
|
---|
11988 | is an expression representing a set of values of the corresponding
|
---|
11989 | device attribute, that will match the given filter. Currently, the
|
---|
11990 | following filtering expressions are supported:
|
---|
11991 |
|
---|
11992 | <ul>
|
---|
11993 | <li><i>Interval filters</i>. Used to specify valid intervals for
|
---|
11994 | integer device attributes (Vendor ID, Product ID and Revision).
|
---|
11995 | The format of the string is:
|
---|
11996 |
|
---|
11997 | <tt>int:((m)|([m]-[n]))(,(m)|([m]-[n]))*</tt>
|
---|
11998 |
|
---|
11999 | where <tt>m</tt> and <tt>n</tt> are integer numbers, either in octal
|
---|
12000 | (starting from <tt>0</tt>), hexadecimal (starting from <tt>0x</tt>)
|
---|
12001 | or decimal (otherwise) form, so that <tt>m < n</tt>. If <tt>m</tt>
|
---|
12002 | is omitted before a dash (<tt>-</tt>), the minimum possible integer
|
---|
12003 | is assumed; if <tt>n</tt> is omitted after a dash, the maximum
|
---|
12004 | possible integer is assumed.
|
---|
12005 | </li>
|
---|
12006 | <li><i>Boolean filters</i>. Used to specify acceptable values for
|
---|
12007 | boolean device attributes. The format of the string is:
|
---|
12008 |
|
---|
12009 | <tt>true|false|yes|no|0|1</tt>
|
---|
12010 |
|
---|
12011 | </li>
|
---|
12012 | <li><i>Exact match</i>. Used to specify a single value for the given
|
---|
12013 | device attribute. Any string that doesn't start with <tt>int:</tt>
|
---|
12014 | represents the exact match. String device attributes are compared to
|
---|
12015 | this string including case of symbols. Integer attributes are first
|
---|
12016 | converted to a string (see individual filter attributes) and then
|
---|
12017 | compared ignoring case.
|
---|
12018 |
|
---|
12019 | </li>
|
---|
12020 | <li><i>Any match</i>. Any value of the corresponding device attribute
|
---|
12021 | will match the given filter. An empty or @c null string is
|
---|
12022 | used to construct this type of filtering expressions.
|
---|
12023 |
|
---|
12024 | </li>
|
---|
12025 | </ul>
|
---|
12026 |
|
---|
12027 | <note>
|
---|
12028 | On the Windows host platform, interval filters are not currently
|
---|
12029 | available. Also all string filter attributes
|
---|
12030 | (<link to="#manufacturer"/>, <link to="#product"/>,
|
---|
12031 | <link to="#serialNumber"/>) are ignored, so they behave as
|
---|
12032 | <i>any match</i> no matter what string expression is specified.
|
---|
12033 | </note>
|
---|
12034 |
|
---|
12035 | <see>IUSBController::deviceFilters, IHostUSBDeviceFilter</see>
|
---|
12036 | </desc>
|
---|
12037 |
|
---|
12038 | <attribute name="name" type="wstring">
|
---|
12039 | <desc>
|
---|
12040 | Visible name for this filter.
|
---|
12041 | This name is used to visually distinguish one filter from another,
|
---|
12042 | so it can neither be @c null nor an empty string.
|
---|
12043 | </desc>
|
---|
12044 | </attribute>
|
---|
12045 |
|
---|
12046 | <attribute name="active" type="boolean">
|
---|
12047 | <desc>Whether this filter active or has been temporarily disabled.</desc>
|
---|
12048 | </attribute>
|
---|
12049 |
|
---|
12050 | <attribute name="vendorId" type="wstring">
|
---|
12051 | <desc>
|
---|
12052 | <link to="IUSBDevice::vendorId">Vendor ID</link> filter.
|
---|
12053 | The string representation for the <i>exact matching</i>
|
---|
12054 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
12055 | (including leading zeroes).
|
---|
12056 | </desc>
|
---|
12057 | </attribute>
|
---|
12058 |
|
---|
12059 | <attribute name="productId" type="wstring">
|
---|
12060 | <desc>
|
---|
12061 | <link to="IUSBDevice::productId">Product ID</link> filter.
|
---|
12062 | The string representation for the <i>exact matching</i>
|
---|
12063 | has the form <tt>XXXX</tt>, where <tt>X</tt> is the hex digit
|
---|
12064 | (including leading zeroes).
|
---|
12065 | </desc>
|
---|
12066 | </attribute>
|
---|
12067 |
|
---|
12068 | <attribute name="revision" type="wstring">
|
---|
12069 | <desc>
|
---|
12070 | <link to="IUSBDevice::productId">Product revision number</link>
|
---|
12071 | filter. The string representation for the <i>exact matching</i>
|
---|
12072 | has the form <tt>IIFF</tt>, where <tt>I</tt> is the decimal digit
|
---|
12073 | of the integer part of the revision, and <tt>F</tt> is the
|
---|
12074 | decimal digit of its fractional part (including leading and
|
---|
12075 | trailing zeros).
|
---|
12076 | Note that for interval filters, it's best to use the hexadecimal
|
---|
12077 | form, because the revision is stored as a 16 bit packed BCD value;
|
---|
12078 | so the expression <tt>int:0x0100-0x0199</tt> will match any
|
---|
12079 | revision from <tt>1.0</tt> to <tt>1.99</tt>.
|
---|
12080 | </desc>
|
---|
12081 | </attribute>
|
---|
12082 |
|
---|
12083 | <attribute name="manufacturer" type="wstring">
|
---|
12084 | <desc>
|
---|
12085 | <link to="IUSBDevice::manufacturer">Manufacturer</link> filter.
|
---|
12086 | </desc>
|
---|
12087 | </attribute>
|
---|
12088 |
|
---|
12089 | <attribute name="product" type="wstring">
|
---|
12090 | <desc>
|
---|
12091 | <link to="IUSBDevice::product">Product</link> filter.
|
---|
12092 | </desc>
|
---|
12093 | </attribute>
|
---|
12094 |
|
---|
12095 | <attribute name="serialNumber" type="wstring">
|
---|
12096 | <desc>
|
---|
12097 | <link to="IUSBDevice::serialNumber">Serial number</link> filter.
|
---|
12098 | </desc>
|
---|
12099 | </attribute>
|
---|
12100 |
|
---|
12101 | <attribute name="port" type="wstring">
|
---|
12102 | <desc>
|
---|
12103 | <link to="IUSBDevice::port">Host USB port</link> filter.
|
---|
12104 | </desc>
|
---|
12105 | </attribute>
|
---|
12106 |
|
---|
12107 | <attribute name="remote" type="wstring">
|
---|
12108 | <desc>
|
---|
12109 | <link to="IUSBDevice::remote">Remote state</link> filter.
|
---|
12110 | <note>
|
---|
12111 | This filter makes sense only for machine USB filters,
|
---|
12112 | i.e. it is ignored by IHostUSBDeviceFilter objects.
|
---|
12113 | </note>
|
---|
12114 | </desc>
|
---|
12115 | </attribute>
|
---|
12116 |
|
---|
12117 | <attribute name="maskedInterfaces" type="unsigned long">
|
---|
12118 | <desc>
|
---|
12119 | This is an advanced option for hiding one or more USB interfaces
|
---|
12120 | from the guest. The value is a bit mask where the bits that are set
|
---|
12121 | means the corresponding USB interface should be hidden, masked off
|
---|
12122 | if you like.
|
---|
12123 | This feature only works on Linux hosts.
|
---|
12124 | </desc>
|
---|
12125 | </attribute>
|
---|
12126 |
|
---|
12127 | </interface>
|
---|
12128 |
|
---|
12129 |
|
---|
12130 | <!--
|
---|
12131 | // IHostUSBDevice
|
---|
12132 | /////////////////////////////////////////////////////////////////////////
|
---|
12133 | -->
|
---|
12134 |
|
---|
12135 | <enum
|
---|
12136 | name="USBDeviceState"
|
---|
12137 | uuid="b99a2e65-67fb-4882-82fd-f3e5e8193ab4"
|
---|
12138 | >
|
---|
12139 | <desc>
|
---|
12140 | USB device state. This enumeration represents all possible states
|
---|
12141 | of the USB device physically attached to the host computer regarding
|
---|
12142 | its state on the host computer and availability to guest computers
|
---|
12143 | (all currently running virtual machines).
|
---|
12144 |
|
---|
12145 | Once a supported USB device is attached to the host, global USB
|
---|
12146 | filters (<link to="IHost::USBDeviceFilters"/>) are activated. They can
|
---|
12147 | either ignore the device, or put it to USBDeviceState_Held state, or do
|
---|
12148 | nothing. Unless the device is ignored by global filters, filters of all
|
---|
12149 | currently running guests (<link to="IUSBController::deviceFilters"/>) are
|
---|
12150 | activated that can put it to USBDeviceState_Captured state.
|
---|
12151 |
|
---|
12152 | If the device was ignored by global filters, or didn't match
|
---|
12153 | any filters at all (including guest ones), it is handled by the host
|
---|
12154 | in a normal way. In this case, the device state is determined by
|
---|
12155 | the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy
|
---|
12156 | or USBDeviceState_Available, depending on the current device usage.
|
---|
12157 |
|
---|
12158 | Besides auto-capturing based on filters, the device can be manually
|
---|
12159 | captured by guests (<link to="IConsole::attachUSBDevice"/>) if its
|
---|
12160 | state is USBDeviceState_Busy, USBDeviceState_Available or
|
---|
12161 | USBDeviceState_Held.
|
---|
12162 |
|
---|
12163 | <note>
|
---|
12164 | Due to differences in USB stack implementations in Linux and Win32,
|
---|
12165 | states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable
|
---|
12166 | only to the Linux version of the product. This also means that (<link
|
---|
12167 | to="IConsole::attachUSBDevice"/>) can only succeed on Win32 if the
|
---|
12168 | device state is USBDeviceState_Held.
|
---|
12169 | </note>
|
---|
12170 |
|
---|
12171 | <see>IHostUSBDevice, IHostUSBDeviceFilter</see>
|
---|
12172 | </desc>
|
---|
12173 |
|
---|
12174 | <const name="NotSupported" value="0">
|
---|
12175 | <desc>
|
---|
12176 | Not supported by the VirtualBox server, not available to guests.
|
---|
12177 | </desc>
|
---|
12178 | </const>
|
---|
12179 | <const name="Unavailable" value="1">
|
---|
12180 | <desc>
|
---|
12181 | Being used by the host computer exclusively,
|
---|
12182 | not available to guests.
|
---|
12183 | </desc>
|
---|
12184 | </const>
|
---|
12185 | <const name="Busy" value="2">
|
---|
12186 | <desc>
|
---|
12187 | Being used by the host computer, potentially available to guests.
|
---|
12188 | </desc>
|
---|
12189 | </const>
|
---|
12190 | <const name="Available" value="3">
|
---|
12191 | <desc>
|
---|
12192 | Not used by the host computer, available to guests (the host computer
|
---|
12193 | can also start using the device at any time).
|
---|
12194 | </desc>
|
---|
12195 | </const>
|
---|
12196 | <const name="Held" value="4">
|
---|
12197 | <desc>
|
---|
12198 | Held by the VirtualBox server (ignored by the host computer),
|
---|
12199 | available to guests.
|
---|
12200 | </desc>
|
---|
12201 | </const>
|
---|
12202 | <const name="Captured" value="5">
|
---|
12203 | <desc>
|
---|
12204 | Captured by one of the guest computers, not available
|
---|
12205 | to anybody else.
|
---|
12206 | </desc>
|
---|
12207 | </const>
|
---|
12208 | </enum>
|
---|
12209 |
|
---|
12210 | <interface
|
---|
12211 | name="IHostUSBDevice" extends="IUSBDevice"
|
---|
12212 | uuid="173b4b44-d268-4334-a00d-b6521c9a740a"
|
---|
12213 | wsmap="managed"
|
---|
12214 | >
|
---|
12215 | <desc>
|
---|
12216 | The IHostUSBDevice interface represents a physical USB device attached
|
---|
12217 | to the host computer.
|
---|
12218 |
|
---|
12219 | Besides properties inherited from IUSBDevice, this interface adds the
|
---|
12220 | <link to="#state"/> property that holds the current state of the USB
|
---|
12221 | device.
|
---|
12222 |
|
---|
12223 | <see>IHost::USBDevices, IHost::USBDeviceFilters</see>
|
---|
12224 | </desc>
|
---|
12225 |
|
---|
12226 | <attribute name="state" type="USBDeviceState" readonly="yes">
|
---|
12227 | <desc>
|
---|
12228 | Current state of the device.
|
---|
12229 | </desc>
|
---|
12230 | </attribute>
|
---|
12231 |
|
---|
12232 | <!-- @todo add class, subclass, bandwidth, configs, interfaces endpoints and such later. -->
|
---|
12233 |
|
---|
12234 | </interface>
|
---|
12235 |
|
---|
12236 |
|
---|
12237 | <!--
|
---|
12238 | // IHostUSBDeviceFilter
|
---|
12239 | /////////////////////////////////////////////////////////////////////////
|
---|
12240 | -->
|
---|
12241 |
|
---|
12242 | <enum
|
---|
12243 | name="USBDeviceFilterAction"
|
---|
12244 | uuid="cbc30a49-2f4e-43b5-9da6-121320475933"
|
---|
12245 | >
|
---|
12246 | <desc>
|
---|
12247 | Actions for host USB device filters.
|
---|
12248 | <see>IHostUSBDeviceFilter, USBDeviceState</see>
|
---|
12249 | </desc>
|
---|
12250 |
|
---|
12251 | <const name="Null" value="0">
|
---|
12252 | <desc>Null value (never used by the API).</desc>
|
---|
12253 | </const>
|
---|
12254 | <const name="Ignore" value="1">
|
---|
12255 | <desc>Ignore the matched USB device.</desc>
|
---|
12256 | </const>
|
---|
12257 | <const name="Hold" value="2">
|
---|
12258 | <desc>Hold the matched USB device.</desc>
|
---|
12259 | </const>
|
---|
12260 | </enum>
|
---|
12261 |
|
---|
12262 | <interface
|
---|
12263 | name="IHostUSBDeviceFilter" extends="IUSBDeviceFilter"
|
---|
12264 | uuid="4cc70246-d74a-400f-8222-3900489c0374"
|
---|
12265 | wsmap="managed"
|
---|
12266 | >
|
---|
12267 | <desc>
|
---|
12268 | The IHostUSBDeviceFilter interface represents a global filter for a
|
---|
12269 | physical USB device used by the host computer. Used indirectly in
|
---|
12270 | <link to="IHost::USBDeviceFilters"/>.
|
---|
12271 |
|
---|
12272 | Using filters of this type, the host computer determines the initial
|
---|
12273 | state of the USB device after it is physically attached to the
|
---|
12274 | host's USB controller.
|
---|
12275 |
|
---|
12276 | <note>
|
---|
12277 | The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of
|
---|
12278 | filters, because it makes sense only for
|
---|
12279 | <link to="IUSBController::deviceFilters">machine USB filters</link>.
|
---|
12280 | </note>
|
---|
12281 |
|
---|
12282 | <see>IHost::USBDeviceFilters</see>
|
---|
12283 | </desc>
|
---|
12284 |
|
---|
12285 | <attribute name="action" type="USBDeviceFilterAction">
|
---|
12286 | <desc>
|
---|
12287 | Action performed by the host when an attached USB device
|
---|
12288 | matches this filter.
|
---|
12289 | </desc>
|
---|
12290 | </attribute>
|
---|
12291 |
|
---|
12292 | </interface>
|
---|
12293 |
|
---|
12294 | <!--
|
---|
12295 | // IAudioAdapter
|
---|
12296 | /////////////////////////////////////////////////////////////////////////
|
---|
12297 | -->
|
---|
12298 |
|
---|
12299 | <enum
|
---|
12300 | name="AudioDriverType"
|
---|
12301 | uuid="4bcc3d73-c2fe-40db-b72f-0c2ca9d68496"
|
---|
12302 | >
|
---|
12303 | <desc>
|
---|
12304 | Host audio driver type.
|
---|
12305 | </desc>
|
---|
12306 |
|
---|
12307 | <const name="Null" value="0">
|
---|
12308 | <desc>Null value, also means "dummy audio driver".</desc>
|
---|
12309 | </const>
|
---|
12310 | <const name="WinMM" value="1">
|
---|
12311 | <desc>Windows multimedia (Windows hosts only).</desc>
|
---|
12312 | </const>
|
---|
12313 | <const name="OSS" value="2">
|
---|
12314 | <desc>Open Sound System (Linux hosts only).</desc>
|
---|
12315 | </const>
|
---|
12316 | <const name="ALSA" value="3">
|
---|
12317 | <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
|
---|
12318 | </const>
|
---|
12319 | <const name="DirectSound" value="4">
|
---|
12320 | <desc>DirectSound (Windows hosts only).</desc>
|
---|
12321 | </const>
|
---|
12322 | <const name="CoreAudio" value="5">
|
---|
12323 | <desc>CoreAudio (Mac hosts only).</desc>
|
---|
12324 | </const>
|
---|
12325 | <const name="MMPM" value="6">
|
---|
12326 | <desc>Reserved for historical reasons.</desc>
|
---|
12327 | </const>
|
---|
12328 | <const name="Pulse" value="7">
|
---|
12329 | <desc>PulseAudio (Linux hosts only).</desc>
|
---|
12330 | </const>
|
---|
12331 | <const name="SolAudio" value="8">
|
---|
12332 | <desc>Solaris audio (Solaris hosts only).</desc>
|
---|
12333 | </const>
|
---|
12334 | </enum>
|
---|
12335 |
|
---|
12336 | <enum
|
---|
12337 | name="AudioControllerType"
|
---|
12338 | uuid="7afd395c-42c3-444e-8788-3ce80292f36c"
|
---|
12339 | >
|
---|
12340 | <desc>
|
---|
12341 | Virtual audio controller type.
|
---|
12342 | </desc>
|
---|
12343 |
|
---|
12344 | <const name="AC97" value="0"/>
|
---|
12345 | <const name="SB16" value="1"/>
|
---|
12346 | <const name="HDA" value="2"/>
|
---|
12347 | </enum>
|
---|
12348 |
|
---|
12349 | <interface
|
---|
12350 | name="IAudioAdapter" extends="$unknown"
|
---|
12351 | uuid="921873db-5f3f-4b69-91f9-7be9e535a2cb"
|
---|
12352 | wsmap="managed"
|
---|
12353 | >
|
---|
12354 | <desc>
|
---|
12355 | The IAudioAdapter interface represents the virtual audio adapter of
|
---|
12356 | the virtual machine. Used in <link to="IMachine::audioAdapter"/>.
|
---|
12357 | </desc>
|
---|
12358 | <attribute name="enabled" type="boolean">
|
---|
12359 | <desc>
|
---|
12360 | Flag whether the audio adapter is present in the
|
---|
12361 | guest system. If disabled, the virtual guest hardware will
|
---|
12362 | not contain any audio adapter. Can only be changed when
|
---|
12363 | the VM is not running.
|
---|
12364 | </desc>
|
---|
12365 | </attribute>
|
---|
12366 | <attribute name="audioController" type="AudioControllerType">
|
---|
12367 | <desc>
|
---|
12368 | The audio hardware we emulate.
|
---|
12369 | </desc>
|
---|
12370 | </attribute>
|
---|
12371 | <attribute name="audioDriver" type="AudioDriverType">
|
---|
12372 | <desc>
|
---|
12373 | Audio driver the adapter is connected to. This setting
|
---|
12374 | can only be changed when the VM is not running.
|
---|
12375 | </desc>
|
---|
12376 | </attribute>
|
---|
12377 | </interface>
|
---|
12378 |
|
---|
12379 | <enum
|
---|
12380 | name="AuthType"
|
---|
12381 | uuid="7eef6ef6-98c2-4dc2-ab35-10d2b292028d"
|
---|
12382 | >
|
---|
12383 | <desc>
|
---|
12384 | VirtualBox authentication type.
|
---|
12385 | </desc>
|
---|
12386 |
|
---|
12387 | <const name="Null" value="0">
|
---|
12388 | <desc>Null value, also means "no authentication".</desc>
|
---|
12389 | </const>
|
---|
12390 | <const name="External" value="1"/>
|
---|
12391 | <const name="Guest" value="2"/>
|
---|
12392 | </enum>
|
---|
12393 |
|
---|
12394 | <!--
|
---|
12395 | // IVRDEServer
|
---|
12396 | /////////////////////////////////////////////////////////////////////////
|
---|
12397 | -->
|
---|
12398 |
|
---|
12399 | <interface
|
---|
12400 | name="IVRDEServer" extends="$unknown"
|
---|
12401 | uuid="f68a6b34-6f09-4040-8de1-e8d746c4a9ea"
|
---|
12402 | wsmap="managed"
|
---|
12403 | >
|
---|
12404 | <attribute name="enabled" type="boolean">
|
---|
12405 | <desc>VRDE server status.</desc>
|
---|
12406 | </attribute>
|
---|
12407 |
|
---|
12408 | <attribute name="authType" type="AuthType">
|
---|
12409 | <desc>VRDE authentication method.</desc>
|
---|
12410 | </attribute>
|
---|
12411 |
|
---|
12412 | <attribute name="authTimeout" type="unsigned long">
|
---|
12413 | <desc>Timeout for guest authentication. Milliseconds.</desc>
|
---|
12414 | </attribute>
|
---|
12415 |
|
---|
12416 | <attribute name="allowMultiConnection" type="boolean">
|
---|
12417 | <desc>
|
---|
12418 | Flag whether multiple simultaneous connections to the VM are permitted.
|
---|
12419 | Note that this will be replaced by a more powerful mechanism in the future.
|
---|
12420 | </desc>
|
---|
12421 | </attribute>
|
---|
12422 |
|
---|
12423 | <attribute name="reuseSingleConnection" type="boolean">
|
---|
12424 | <desc>
|
---|
12425 | Flag whether the existing connection must be dropped and a new connection
|
---|
12426 | must be established by the VRDE server, when a new client connects in single
|
---|
12427 | connection mode.
|
---|
12428 | </desc>
|
---|
12429 | </attribute>
|
---|
12430 |
|
---|
12431 | <attribute name="videoChannel" type="boolean">
|
---|
12432 | <desc>
|
---|
12433 | Flag whether video redirectiron channel is enabled.
|
---|
12434 | </desc>
|
---|
12435 | </attribute>
|
---|
12436 |
|
---|
12437 | <attribute name="videoChannelQuality" type="unsigned long">
|
---|
12438 | <desc>
|
---|
12439 | Image quality in percents.
|
---|
12440 | </desc>
|
---|
12441 | </attribute>
|
---|
12442 |
|
---|
12443 | <attribute name="VRDELibrary" type="wstring">
|
---|
12444 | <desc>
|
---|
12445 | VRDE library used by this VM. Overrides
|
---|
12446 | <link to="ISystemProperties::defaultVRDELibrary"/>.
|
---|
12447 | </desc>
|
---|
12448 | </attribute>
|
---|
12449 |
|
---|
12450 | <method name="setVRDEProperty">
|
---|
12451 | <desc>
|
---|
12452 | Sets a VRDE specific property string.
|
---|
12453 |
|
---|
12454 | If you pass @c null or empty string as a key @a value, the given @a key
|
---|
12455 | will be deleted.
|
---|
12456 |
|
---|
12457 | </desc>
|
---|
12458 | <param name="key" type="wstring" dir="in">
|
---|
12459 | <desc>Name of the key to set.</desc>
|
---|
12460 | </param>
|
---|
12461 | <param name="value" type="wstring" dir="in">
|
---|
12462 | <desc>Value to assign to the key.</desc>
|
---|
12463 | </param>
|
---|
12464 | </method>
|
---|
12465 |
|
---|
12466 | <method name="getVRDEProperty">
|
---|
12467 | <desc>
|
---|
12468 | Returns a VRDE specific property string.
|
---|
12469 |
|
---|
12470 | If the requested data @a key does not exist, this function will
|
---|
12471 | succeed and return an empty string in the @a value argument.
|
---|
12472 |
|
---|
12473 | </desc>
|
---|
12474 | <param name="key" type="wstring" dir="in">
|
---|
12475 | <desc>Name of the key to get.</desc>
|
---|
12476 | </param>
|
---|
12477 | <param name="value" type="wstring" dir="return">
|
---|
12478 | <desc>Value of the requested key.</desc>
|
---|
12479 | </param>
|
---|
12480 | </method>
|
---|
12481 |
|
---|
12482 | </interface>
|
---|
12483 |
|
---|
12484 |
|
---|
12485 | <!--
|
---|
12486 | // ISharedFolder
|
---|
12487 | /////////////////////////////////////////////////////////////////////////
|
---|
12488 | -->
|
---|
12489 |
|
---|
12490 | <interface
|
---|
12491 | name="ISharedFolder" extends="$unknown"
|
---|
12492 | uuid="8388da11-b559-4574-a5b7-2bd7acd5cef8"
|
---|
12493 | wsmap="struct"
|
---|
12494 | >
|
---|
12495 | <desc>
|
---|
12496 | The ISharedFolder interface represents a folder in the host computer's
|
---|
12497 | file system accessible from the guest OS running inside a virtual
|
---|
12498 | machine using an associated logical name.
|
---|
12499 |
|
---|
12500 | There are three types of shared folders:
|
---|
12501 | <ul>
|
---|
12502 | <li><i>Global</i> (<link to="IVirtualBox::sharedFolders"/>), shared
|
---|
12503 | folders available to all virtual machines.</li>
|
---|
12504 | <li><i>Permanent</i> (<link to="IMachine::sharedFolders"/>),
|
---|
12505 | VM-specific shared folders available to the given virtual machine at
|
---|
12506 | startup.</li>
|
---|
12507 | <li><i>Transient</i> (<link to="IConsole::sharedFolders"/>),
|
---|
12508 | VM-specific shared folders created in the session context (for
|
---|
12509 | example, when the virtual machine is running) and automatically
|
---|
12510 | discarded when the session is closed (the VM is powered off).</li>
|
---|
12511 | </ul>
|
---|
12512 |
|
---|
12513 | Logical names of shared folders must be unique within the given scope
|
---|
12514 | (global, permanent or transient). However, they do not need to be unique
|
---|
12515 | across scopes. In this case, the definition of the shared folder in a
|
---|
12516 | more specific scope takes precedence over definitions in all other
|
---|
12517 | scopes. The order of precedence is (more specific to more general):
|
---|
12518 | <ol>
|
---|
12519 | <li>Transient definitions</li>
|
---|
12520 | <li>Permanent definitions</li>
|
---|
12521 | <li>Global definitions</li>
|
---|
12522 | </ol>
|
---|
12523 |
|
---|
12524 | For example, if MyMachine has a shared folder named
|
---|
12525 | <tt>C_DRIVE</tt> (that points to <tt>C:\\</tt>), then creating a
|
---|
12526 | transient shared folder named <tt>C_DRIVE</tt> (that points
|
---|
12527 | to <tt>C:\\\\WINDOWS</tt>) will change the definition
|
---|
12528 | of <tt>C_DRIVE</tt> in the guest OS so
|
---|
12529 | that <tt>\\\\VBOXSVR\\C_DRIVE</tt> will give access
|
---|
12530 | to <tt>C:\\WINDOWS</tt> instead of <tt>C:\\</tt> on the host
|
---|
12531 | PC. Removing the transient shared folder <tt>C_DRIVE</tt> will restore
|
---|
12532 | the previous (permanent) definition of <tt>C_DRIVE</tt> that points
|
---|
12533 | to <tt>C:\\</tt> if it still exists.
|
---|
12534 |
|
---|
12535 | Note that permanent and transient shared folders of different machines
|
---|
12536 | are in different name spaces, so they don't overlap and don't need to
|
---|
12537 | have unique logical names.
|
---|
12538 |
|
---|
12539 | <note>
|
---|
12540 | Global shared folders are not implemented in the current version of the
|
---|
12541 | product.
|
---|
12542 | </note>
|
---|
12543 | </desc>
|
---|
12544 |
|
---|
12545 | <attribute name="name" type="wstring" readonly="yes">
|
---|
12546 | <desc>Logical name of the shared folder.</desc>
|
---|
12547 | </attribute>
|
---|
12548 |
|
---|
12549 | <attribute name="hostPath" type="wstring" readonly="yes">
|
---|
12550 | <desc>Full path to the shared folder in the host file system.</desc>
|
---|
12551 | </attribute>
|
---|
12552 |
|
---|
12553 | <attribute name="accessible" type="boolean" readonly="yes">
|
---|
12554 | <desc>
|
---|
12555 | Whether the folder defined by the host path is currently
|
---|
12556 | accessible or not.
|
---|
12557 | For example, the folder can be inaccessible if it is placed
|
---|
12558 | on the network share that is not available by the time
|
---|
12559 | this property is read.
|
---|
12560 | </desc>
|
---|
12561 | </attribute>
|
---|
12562 |
|
---|
12563 | <attribute name="writable" type="boolean" readonly="yes">
|
---|
12564 | <desc>
|
---|
12565 | Whether the folder defined by the host path is writable or
|
---|
12566 | not.
|
---|
12567 | </desc>
|
---|
12568 | </attribute>
|
---|
12569 |
|
---|
12570 | <attribute name="autoMount" type="boolean" readonly="yes">
|
---|
12571 | <desc>
|
---|
12572 | Whether the folder gets automatically mounted by the guest or not.
|
---|
12573 | </desc>
|
---|
12574 | </attribute>
|
---|
12575 |
|
---|
12576 | <attribute name="lastAccessError" type="wstring" readonly="yes">
|
---|
12577 | <desc>
|
---|
12578 | Text message that represents the result of the last accessibility
|
---|
12579 | check.
|
---|
12580 |
|
---|
12581 | Accessibility checks are performed each time the <link to="#accessible"/>
|
---|
12582 | attribute is read. An empty string is returned if the last
|
---|
12583 | accessibility check was successful. A non-empty string indicates a
|
---|
12584 | failure and should normally describe a reason of the failure (for
|
---|
12585 | example, a file read error).
|
---|
12586 | </desc>
|
---|
12587 | </attribute>
|
---|
12588 |
|
---|
12589 | </interface>
|
---|
12590 |
|
---|
12591 | <!--
|
---|
12592 | // ISession
|
---|
12593 | /////////////////////////////////////////////////////////////////////////
|
---|
12594 | -->
|
---|
12595 |
|
---|
12596 | <interface
|
---|
12597 | name="IInternalSessionControl" extends="$unknown"
|
---|
12598 | uuid="06ef98a7-f7c0-45ba-bf99-9aca7a4d5530"
|
---|
12599 | internal="yes"
|
---|
12600 | wsmap="suppress"
|
---|
12601 | >
|
---|
12602 | <method name="getPID">
|
---|
12603 | <desc>PID of the process that has created this Session object.
|
---|
12604 | </desc>
|
---|
12605 | <param name="pid" type="unsigned long" dir="return"/>
|
---|
12606 | </method>
|
---|
12607 |
|
---|
12608 | <method name="getRemoteConsole">
|
---|
12609 | <desc>
|
---|
12610 | Returns the console object suitable for remote control.
|
---|
12611 |
|
---|
12612 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12613 | Session state prevents operation.
|
---|
12614 | </result>
|
---|
12615 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12616 | Session type prevents operation.
|
---|
12617 | </result>
|
---|
12618 |
|
---|
12619 | </desc>
|
---|
12620 | <param name="console" type="IConsole" dir="return"/>
|
---|
12621 | </method>
|
---|
12622 |
|
---|
12623 | <method name="assignMachine">
|
---|
12624 | <desc>
|
---|
12625 | Assigns the machine object associated with this direct-type
|
---|
12626 | session or informs the session that it will be a remote one
|
---|
12627 | (if @a machine == @c null).
|
---|
12628 |
|
---|
12629 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12630 | Session state prevents operation.
|
---|
12631 | </result>
|
---|
12632 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12633 | Session type prevents operation.
|
---|
12634 | </result>
|
---|
12635 |
|
---|
12636 | </desc>
|
---|
12637 | <param name="machine" type="IMachine" dir="in"/>
|
---|
12638 | </method>
|
---|
12639 |
|
---|
12640 | <method name="assignRemoteMachine">
|
---|
12641 | <desc>
|
---|
12642 | Assigns the machine and the (remote) console object associated with
|
---|
12643 | this remote-type session.
|
---|
12644 |
|
---|
12645 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12646 | Session state prevents operation.
|
---|
12647 | </result>
|
---|
12648 |
|
---|
12649 | </desc>
|
---|
12650 | <param name="machine" type="IMachine" dir="in"/>
|
---|
12651 | <param name="console" type="IConsole" dir="in"/>
|
---|
12652 | </method>
|
---|
12653 |
|
---|
12654 | <method name="updateMachineState">
|
---|
12655 | <desc>
|
---|
12656 | Updates the machine state in the VM process.
|
---|
12657 | Must be called only in certain cases
|
---|
12658 | (see the method implementation).
|
---|
12659 |
|
---|
12660 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12661 | Session state prevents operation.
|
---|
12662 | </result>
|
---|
12663 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12664 | Session type prevents operation.
|
---|
12665 | </result>
|
---|
12666 |
|
---|
12667 | </desc>
|
---|
12668 | <param name="aMachineState" type="MachineState" dir="in"/>
|
---|
12669 | </method>
|
---|
12670 |
|
---|
12671 | <method name="uninitialize">
|
---|
12672 | <desc>
|
---|
12673 | Uninitializes (closes) this session. Used by VirtualBox to close
|
---|
12674 | the corresponding remote session when the direct session dies
|
---|
12675 | or gets closed.
|
---|
12676 |
|
---|
12677 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12678 | Session state prevents operation.
|
---|
12679 | </result>
|
---|
12680 |
|
---|
12681 | </desc>
|
---|
12682 | </method>
|
---|
12683 |
|
---|
12684 | <method name="onNetworkAdapterChange">
|
---|
12685 | <desc>
|
---|
12686 | Triggered when settings of a network adapter of the
|
---|
12687 | associated virtual machine have changed.
|
---|
12688 |
|
---|
12689 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12690 | Session state prevents operation.
|
---|
12691 | </result>
|
---|
12692 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12693 | Session type prevents operation.
|
---|
12694 | </result>
|
---|
12695 |
|
---|
12696 | </desc>
|
---|
12697 | <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
|
---|
12698 | <param name="changeAdapter" type="boolean" dir="in"/>
|
---|
12699 | </method>
|
---|
12700 |
|
---|
12701 | <method name="onNATRedirectRuleChange">
|
---|
12702 | <desc>
|
---|
12703 | Triggered on adding/removing of NAT Engine redirection rule of the
|
---|
12704 | associated virtual machine.
|
---|
12705 |
|
---|
12706 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12707 | Session state prevents operation.
|
---|
12708 | </result>
|
---|
12709 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12710 | Session type prevents operation.
|
---|
12711 | </result>
|
---|
12712 |
|
---|
12713 | </desc>
|
---|
12714 | <param name="networkAdapter" type="INetworkAdapter" dir="in"/>
|
---|
12715 | <param name="natRedirectRemove" type="boolean" dir="in"/>
|
---|
12716 | <param name="natRuleName" type="wstring" dir="in"/>
|
---|
12717 | <param name="natProto" type="NATProtocol" dir="in"/>
|
---|
12718 | <param name="natHostIp" type="wstring" dir="in"/>
|
---|
12719 | <param name="natHostPort" type="long" dir="in"/>
|
---|
12720 | <param name="natGuestIp" type="wstring" dir="in"/>
|
---|
12721 | <param name="natGuestPort" type="long" dir="in"/>
|
---|
12722 | </method>
|
---|
12723 |
|
---|
12724 | <method name="onSerialPortChange">
|
---|
12725 | <desc>
|
---|
12726 | Triggered when settings of a serial port of the
|
---|
12727 | associated virtual machine have changed.
|
---|
12728 |
|
---|
12729 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12730 | Session state prevents operation.
|
---|
12731 | </result>
|
---|
12732 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12733 | Session type prevents operation.
|
---|
12734 | </result>
|
---|
12735 |
|
---|
12736 | </desc>
|
---|
12737 | <param name="serialPort" type="ISerialPort" dir="in"/>
|
---|
12738 | </method>
|
---|
12739 |
|
---|
12740 | <method name="onParallelPortChange">
|
---|
12741 | <desc>
|
---|
12742 | Triggered when settings of a parallel port of the
|
---|
12743 | associated virtual machine have changed.
|
---|
12744 |
|
---|
12745 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12746 | Session state prevents operation.
|
---|
12747 | </result>
|
---|
12748 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12749 | Session type prevents operation.
|
---|
12750 | </result>
|
---|
12751 |
|
---|
12752 | </desc>
|
---|
12753 | <param name="parallelPort" type="IParallelPort" dir="in"/>
|
---|
12754 | </method>
|
---|
12755 |
|
---|
12756 | <method name="onStorageControllerChange">
|
---|
12757 | <desc>
|
---|
12758 | Triggered when settings of a storage controller of the
|
---|
12759 | associated virtual machine have changed.
|
---|
12760 |
|
---|
12761 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12762 | Session state prevents operation.
|
---|
12763 | </result>
|
---|
12764 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12765 | Session type prevents operation.
|
---|
12766 | </result>
|
---|
12767 |
|
---|
12768 | </desc>
|
---|
12769 | </method>
|
---|
12770 |
|
---|
12771 | <method name="onMediumChange">
|
---|
12772 | <desc>
|
---|
12773 | Triggered when attached media of the
|
---|
12774 | associated virtual machine have changed.
|
---|
12775 |
|
---|
12776 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12777 | Session state prevents operation.
|
---|
12778 | </result>
|
---|
12779 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12780 | Session type prevents operation.
|
---|
12781 | </result>
|
---|
12782 |
|
---|
12783 | </desc>
|
---|
12784 |
|
---|
12785 | <param name="mediumAttachment" type="IMediumAttachment" dir="in"/>
|
---|
12786 | <param name="force" type="boolean" dir="in"/>
|
---|
12787 | </method>
|
---|
12788 |
|
---|
12789 | <method name="onCPUChange">
|
---|
12790 | <desc>
|
---|
12791 | Notification when a CPU changes.
|
---|
12792 | </desc>
|
---|
12793 | <param name="cpu" type="unsigned long" dir="in">
|
---|
12794 | <desc>The CPU which changed</desc>
|
---|
12795 | </param>
|
---|
12796 | <param name="add" type="boolean" dir="in">
|
---|
12797 | <desc>Flag whether the CPU was added or removed</desc>
|
---|
12798 | </param>
|
---|
12799 | </method>
|
---|
12800 |
|
---|
12801 | <method name="onCPUExecutionCapChange">
|
---|
12802 | <desc>
|
---|
12803 | Notification when the CPU execution cap changes.
|
---|
12804 | </desc>
|
---|
12805 | <param name="executionCap" type="unsigned long" dir="in">
|
---|
12806 | <desc>The new CPU execution cap value. (1-100)</desc>
|
---|
12807 | </param>
|
---|
12808 | </method>
|
---|
12809 |
|
---|
12810 | <method name="onVRDEServerChange">
|
---|
12811 | <desc>
|
---|
12812 | Triggered when settings of the VRDE server object of the
|
---|
12813 | associated virtual machine have changed.
|
---|
12814 |
|
---|
12815 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12816 | Session state prevents operation.
|
---|
12817 | </result>
|
---|
12818 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12819 | Session type prevents operation.
|
---|
12820 | </result>
|
---|
12821 |
|
---|
12822 | </desc>
|
---|
12823 | <param name="restart" type="boolean" dir="in">
|
---|
12824 | <desc>Flag whether the server must be restarted</desc>
|
---|
12825 | </param>
|
---|
12826 | </method>
|
---|
12827 |
|
---|
12828 | <method name="onUSBControllerChange">
|
---|
12829 | <desc>
|
---|
12830 | Triggered when settings of the USB controller object of the
|
---|
12831 | associated virtual machine have changed.
|
---|
12832 |
|
---|
12833 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12834 | Session state prevents operation.
|
---|
12835 | </result>
|
---|
12836 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12837 | Session type prevents operation.
|
---|
12838 | </result>
|
---|
12839 |
|
---|
12840 | </desc>
|
---|
12841 | </method>
|
---|
12842 |
|
---|
12843 | <method name="onSharedFolderChange">
|
---|
12844 | <desc>
|
---|
12845 | Triggered when a permanent (global or machine) shared folder has been
|
---|
12846 | created or removed.
|
---|
12847 | <note>
|
---|
12848 | We don't pass shared folder parameters in this notification because
|
---|
12849 | the order in which parallel notifications are delivered is not defined,
|
---|
12850 | therefore it could happen that these parameters were outdated by the
|
---|
12851 | time of processing this notification.
|
---|
12852 | </note>
|
---|
12853 |
|
---|
12854 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12855 | Session state prevents operation.
|
---|
12856 | </result>
|
---|
12857 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12858 | Session type prevents operation.
|
---|
12859 | </result>
|
---|
12860 |
|
---|
12861 | </desc>
|
---|
12862 | <param name="global" type="boolean" dir="in"/>
|
---|
12863 | </method>
|
---|
12864 |
|
---|
12865 | <method name="onUSBDeviceAttach">
|
---|
12866 | <desc>
|
---|
12867 | Triggered when a request to capture a USB device (as a result
|
---|
12868 | of matched USB filters or direct call to
|
---|
12869 | <link to="IConsole::attachUSBDevice"/>) has completed.
|
---|
12870 | A @c null @a error object means success, otherwise it
|
---|
12871 | describes a failure.
|
---|
12872 |
|
---|
12873 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12874 | Session state prevents operation.
|
---|
12875 | </result>
|
---|
12876 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12877 | Session type prevents operation.
|
---|
12878 | </result>
|
---|
12879 |
|
---|
12880 | </desc>
|
---|
12881 | <param name="device" type="IUSBDevice" dir="in"/>
|
---|
12882 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
12883 | <param name="maskedInterfaces" type="unsigned long" dir="in"/>
|
---|
12884 | </method>
|
---|
12885 |
|
---|
12886 | <method name="onUSBDeviceDetach">
|
---|
12887 | <desc>
|
---|
12888 | Triggered when a request to release the USB device (as a result
|
---|
12889 | of machine termination or direct call to
|
---|
12890 | <link to="IConsole::detachUSBDevice"/>) has completed.
|
---|
12891 | A @c null @a error object means success, otherwise it
|
---|
12892 | describes a failure.
|
---|
12893 |
|
---|
12894 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12895 | Session state prevents operation.
|
---|
12896 | </result>
|
---|
12897 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12898 | Session type prevents operation.
|
---|
12899 | </result>
|
---|
12900 |
|
---|
12901 | </desc>
|
---|
12902 | <param name="id" type="uuid" mod="string" dir="in"/>
|
---|
12903 | <param name="error" type="IVirtualBoxErrorInfo" dir="in"/>
|
---|
12904 | </method>
|
---|
12905 |
|
---|
12906 | <method name="onShowWindow">
|
---|
12907 | <desc>
|
---|
12908 | Called by <link to="IMachine::canShowConsoleWindow"/> and by
|
---|
12909 | <link to="IMachine::showConsoleWindow"/> in order to notify
|
---|
12910 | console listeners
|
---|
12911 | <link to="ICanShowWindowEvent"/>
|
---|
12912 | and <link to="IShowWindowEvent"/>.
|
---|
12913 |
|
---|
12914 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12915 | Session type prevents operation.
|
---|
12916 | </result>
|
---|
12917 |
|
---|
12918 | </desc>
|
---|
12919 | <param name="check" type="boolean" dir="in"/>
|
---|
12920 | <param name="canShow" type="boolean" dir="out"/>
|
---|
12921 | <param name="winId" type="long long" dir="out"/>
|
---|
12922 | </method>
|
---|
12923 |
|
---|
12924 | <method name="accessGuestProperty">
|
---|
12925 | <desc>
|
---|
12926 | Called by <link to="IMachine::getGuestProperty"/> and by
|
---|
12927 | <link to="IMachine::setGuestProperty"/> in order to read and
|
---|
12928 | modify guest properties.
|
---|
12929 |
|
---|
12930 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12931 | Machine session is not open.
|
---|
12932 | </result>
|
---|
12933 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12934 | Session type is not direct.
|
---|
12935 | </result>
|
---|
12936 |
|
---|
12937 | </desc>
|
---|
12938 | <param name="name" type="wstring" dir="in"/>
|
---|
12939 | <param name="value" type="wstring" dir="in"/>
|
---|
12940 | <param name="flags" type="wstring" dir="in"/>
|
---|
12941 | <param name="isSetter" type="boolean" dir="in"/>
|
---|
12942 | <param name="retValue" type="wstring" dir="out"/>
|
---|
12943 | <param name="retTimestamp" type="long long" dir="out"/>
|
---|
12944 | <param name="retFlags" type="wstring" dir="out"/>
|
---|
12945 | </method>
|
---|
12946 |
|
---|
12947 | <method name="enumerateGuestProperties">
|
---|
12948 | <desc>
|
---|
12949 | Return a list of the guest properties matching a set of patterns along
|
---|
12950 | with their values, time stamps and flags.
|
---|
12951 |
|
---|
12952 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12953 | Machine session is not open.
|
---|
12954 | </result>
|
---|
12955 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
12956 | Session type is not direct.
|
---|
12957 | </result>
|
---|
12958 |
|
---|
12959 | </desc>
|
---|
12960 | <param name="patterns" type="wstring" dir="in">
|
---|
12961 | <desc>
|
---|
12962 | The patterns to match the properties against as a comma-separated
|
---|
12963 | string. If this is empty, all properties currently set will be
|
---|
12964 | returned.
|
---|
12965 | </desc>
|
---|
12966 | </param>
|
---|
12967 | <param name="key" type="wstring" dir="out" safearray="yes">
|
---|
12968 | <desc>
|
---|
12969 | The key names of the properties returned.
|
---|
12970 | </desc>
|
---|
12971 | </param>
|
---|
12972 | <param name="value" type="wstring" dir="out" safearray="yes">
|
---|
12973 | <desc>
|
---|
12974 | The values of the properties returned. The array entries match the
|
---|
12975 | corresponding entries in the @a key array.
|
---|
12976 | </desc>
|
---|
12977 | </param>
|
---|
12978 | <param name="timestamp" type="long long" dir="out" safearray="yes">
|
---|
12979 | <desc>
|
---|
12980 | The time stamps of the properties returned. The array entries match
|
---|
12981 | the corresponding entries in the @a key array.
|
---|
12982 | </desc>
|
---|
12983 | </param>
|
---|
12984 | <param name="flags" type="wstring" dir="out" safearray="yes">
|
---|
12985 | <desc>
|
---|
12986 | The flags of the properties returned. The array entries match the
|
---|
12987 | corresponding entries in the @a key array.
|
---|
12988 | </desc>
|
---|
12989 | </param>
|
---|
12990 | </method>
|
---|
12991 |
|
---|
12992 | <method name="onlineMergeMedium">
|
---|
12993 | <desc>
|
---|
12994 | Triggers online merging of a hard disk. Used internally when deleting
|
---|
12995 | a snapshot while a VM referring to the same hard disk chain is running.
|
---|
12996 |
|
---|
12997 | <result name="VBOX_E_INVALID_VM_STATE">
|
---|
12998 | Machine session is not open.
|
---|
12999 | </result>
|
---|
13000 | <result name="VBOX_E_INVALID_OBJECT_STATE">
|
---|
13001 | Session type is not direct.
|
---|
13002 | </result>
|
---|
13003 |
|
---|
13004 | </desc>
|
---|
13005 | <param name="mediumAttachment" type="IMediumAttachment" dir="in">
|
---|
13006 | <desc>The medium attachment to identify the medium chain.</desc>
|
---|
13007 | </param>
|
---|
13008 | <param name="sourceIdx" type="unsigned long" dir="in">
|
---|
13009 | <desc>The index of the source image in the chain.
|
---|
13010 | Redundant, but drastically reduces IPC.</desc>
|
---|
13011 | </param>
|
---|
13012 | <param name="targetIdx" type="unsigned long" dir="in">
|
---|
13013 | <desc>The index of the target image in the chain.
|
---|
13014 | Redundant, but drastically reduces IPC.</desc>
|
---|
13015 | </param>
|
---|
13016 | <param name="source" type="IMedium" dir="in">
|
---|
13017 | <desc>Merge source medium.</desc>
|
---|
13018 | </param>
|
---|
13019 | <param name="target" type="IMedium" dir="in">
|
---|
13020 | <desc>Merge target medium.</desc>
|
---|
13021 | </param>
|
---|
13022 | <param name="mergeForward" type="boolean" dir="in">
|
---|
13023 | <desc>Merge direction.</desc>
|
---|
13024 | </param>
|
---|
13025 | <param name="parentForTarget" type="IMedium" dir="in">
|
---|
13026 | <desc>For forward merges: new parent for target medium.</desc>
|
---|
13027 | </param>
|
---|
13028 | <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in">
|
---|
13029 | <desc>For backward merges: list of media which need their parent UUID
|
---|
13030 | updated.</desc>
|
---|
13031 | </param>
|
---|
13032 | <param name="progress" type="IProgress" dir="in">
|
---|
13033 | <desc>
|
---|
13034 | Progress object for this operation.
|
---|
13035 | </desc>
|
---|
13036 | </param>
|
---|
13037 | </method>
|
---|
13038 |
|
---|
13039 | </interface>
|
---|
13040 |
|
---|
13041 | <interface
|
---|
13042 | name="ISession" extends="$unknown"
|
---|
13043 | uuid="12F4DCDB-12B2-4EC1-B7CD-DDD9F6C5BF4D"
|
---|
13044 | wsmap="managed"
|
---|
13045 | >
|
---|
13046 | <desc>
|
---|
13047 | The ISession interface represents a client process and allows for locking
|
---|
13048 | virtual machines (represented by IMachine objects) to prevent conflicting
|
---|
13049 | changes to the machine.
|
---|
13050 |
|
---|
13051 | Any caller wishing to manipulate a virtual machine needs to create a session
|
---|
13052 | object first, which lives in its own process space. Such session objects are
|
---|
13053 | then associated with <link to="IMachine" /> objects living in the VirtualBox
|
---|
13054 | server process to coordinate such changes.
|
---|
13055 |
|
---|
13056 | There are two typical scenarios in which sessions are used:
|
---|
13057 |
|
---|
13058 | <ul>
|
---|
13059 | <li>To alter machine settings or control a running virtual machine, one
|
---|
13060 | needs to lock a machine for a given session (client process) by calling
|
---|
13061 | <link to="IMachine::lockMachine"/>.
|
---|
13062 |
|
---|
13063 | Whereas multiple sessions may control a running virtual machine, only
|
---|
13064 | one process can obtain a write lock on the machine to prevent conflicting
|
---|
13065 | changes. A write lock is also needed if a process wants to actually run a
|
---|
13066 | virtual machine in its own context, such as the VirtualBox GUI or
|
---|
13067 | VBoxHeadless front-ends. They must also lock a machine for their own
|
---|
13068 | sessions before they are allowed to power up the virtual machine.
|
---|
13069 |
|
---|
13070 | As a result, no machine settings can be altered while another process is
|
---|
13071 | already using it, either because that process is modifying machine settings
|
---|
13072 | or because the machine is running.
|
---|
13073 | </li>
|
---|
13074 | <li>
|
---|
13075 | To start a VM using one of the existing VirtualBox front-ends (e.g. the
|
---|
13076 | VirtualBox GUI or VBoxHeadless), one would use
|
---|
13077 | <link to="IMachine::launchVMProcess"/>, which also takes a session object
|
---|
13078 | as its first parameter. This session then identifies the caller and lets the
|
---|
13079 | caller control the started machine (for example, pause machine execution or
|
---|
13080 | power it down) as well as be notified about machine execution state changes.
|
---|
13081 | </li>
|
---|
13082 | </ul>
|
---|
13083 |
|
---|
13084 | How sessions objects are created in a client process depends on whether you use
|
---|
13085 | the Main API via COM or via the webservice:
|
---|
13086 |
|
---|
13087 | <ul>
|
---|
13088 | <li>When using the COM API directly, an object of the Session class from the
|
---|
13089 | VirtualBox type library needs to be created. In regular COM C++ client code,
|
---|
13090 | this can be done by calling <tt>createLocalObject()</tt>, a standard COM API.
|
---|
13091 | This object will then act as a local session object in further calls to open
|
---|
13092 | a session.
|
---|
13093 | </li>
|
---|
13094 |
|
---|
13095 | <li>In the webservice, the session manager (IWebsessionManager) instead creates
|
---|
13096 | a session object automatically whenever <link to="IWebsessionManager::logon" />
|
---|
13097 | is called. A managed object reference to that session object can be retrieved by
|
---|
13098 | calling <link to="IWebsessionManager::getSessionObject" />.
|
---|
13099 | </li>
|
---|
13100 | </ul>
|
---|
13101 | </desc>
|
---|
13102 |
|
---|
13103 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
13104 | <desc>Current state of this session.</desc>
|
---|
13105 | </attribute>
|
---|
13106 |
|
---|
13107 | <attribute name="type" type="SessionType" readonly="yes">
|
---|
13108 | <desc>
|
---|
13109 | Type of this session. The value of this attribute is valid only
|
---|
13110 | if the session currently has a machine locked (i.e. its
|
---|
13111 | <link to="#state" /> is Locked), otherwise an error will be returned.
|
---|
13112 | </desc>
|
---|
13113 | </attribute>
|
---|
13114 |
|
---|
13115 | <attribute name="machine" type="IMachine" readonly="yes">
|
---|
13116 | <desc>Machine object associated with this session.</desc>
|
---|
13117 | </attribute>
|
---|
13118 |
|
---|
13119 | <attribute name="console" type="IConsole" readonly="yes">
|
---|
13120 | <desc>Console object associated with this session.</desc>
|
---|
13121 | </attribute>
|
---|
13122 |
|
---|
13123 | <method name="unlockMachine">
|
---|
13124 | <desc>
|
---|
13125 | Unlocks a machine that was previously locked for the current session.
|
---|
13126 |
|
---|
13127 | Calling this method is required every time a machine has been locked
|
---|
13128 | for a particular session using the <link to="IMachine::launchVMProcess" />
|
---|
13129 | or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
|
---|
13130 | the machine will be set to <link to="MachineState_Aborted" /> on the
|
---|
13131 | server, and changes made to the machine settings will be lost.
|
---|
13132 |
|
---|
13133 | Generally, it is recommended to unlock all machines explicitly
|
---|
13134 | before terminating the application (regardless of the reason for
|
---|
13135 | the termination).
|
---|
13136 |
|
---|
13137 | <note>
|
---|
13138 | Do not expect the session state (<link to="ISession::state" />
|
---|
13139 | to return to "Unlocked" immediately after you invoke this method,
|
---|
13140 | particularly if you have started a new VM process. The session
|
---|
13141 | state will automatically return to "Unlocked" once the VM is no
|
---|
13142 | longer executing, which can of course take a very long time.
|
---|
13143 | </note>
|
---|
13144 |
|
---|
13145 | <result name="E_UNEXPECTED">
|
---|
13146 | Session is not locked.
|
---|
13147 | </result>
|
---|
13148 |
|
---|
13149 | </desc>
|
---|
13150 | </method>
|
---|
13151 |
|
---|
13152 | </interface>
|
---|
13153 |
|
---|
13154 | <!--
|
---|
13155 | // IStorageController
|
---|
13156 | /////////////////////////////////////////////////////////////////////////
|
---|
13157 | -->
|
---|
13158 |
|
---|
13159 | <enum
|
---|
13160 | name="StorageBus"
|
---|
13161 | uuid="eee67ab3-668d-4ef5-91e0-7025fe4a0d7a"
|
---|
13162 | >
|
---|
13163 | <desc>
|
---|
13164 | The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy);
|
---|
13165 | see <link to="IStorageController::bus" />.
|
---|
13166 | </desc>
|
---|
13167 | <const name="Null" value="0">
|
---|
13168 | <desc>@c null value. Never used by the API.</desc>
|
---|
13169 | </const>
|
---|
13170 | <const name="IDE" value="1"/>
|
---|
13171 | <const name="SATA" value="2"/>
|
---|
13172 | <const name="SCSI" value="3"/>
|
---|
13173 | <const name="Floppy" value="4"/>
|
---|
13174 | <const name="SAS" value="5"/>
|
---|
13175 | </enum>
|
---|
13176 |
|
---|
13177 | <enum
|
---|
13178 | name="StorageControllerType"
|
---|
13179 | uuid="8a412b8a-f43e-4456-bd37-b474f0879a58"
|
---|
13180 | >
|
---|
13181 | <desc>
|
---|
13182 | The exact variant of storage controller hardware presented
|
---|
13183 | to the guest; see <link to="IStorageController::controllerType" />.
|
---|
13184 | </desc>
|
---|
13185 |
|
---|
13186 | <const name="Null" value="0">
|
---|
13187 | <desc>@c null value. Never used by the API.</desc>
|
---|
13188 | </const>
|
---|
13189 | <const name="LsiLogic" value="1">
|
---|
13190 | <desc>A SCSI controller of the LsiLogic variant.</desc>
|
---|
13191 | </const>
|
---|
13192 | <const name="BusLogic" value="2">
|
---|
13193 | <desc>A SCSI controller of the BusLogic variant.</desc>
|
---|
13194 | </const>
|
---|
13195 | <const name="IntelAhci" value="3">
|
---|
13196 | <desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc>
|
---|
13197 | </const>
|
---|
13198 | <const name="PIIX3" value="4">
|
---|
13199 | <desc>An IDE controller of the PIIX3 variant.</desc>
|
---|
13200 | </const>
|
---|
13201 | <const name="PIIX4" value="5">
|
---|
13202 | <desc>An IDE controller of the PIIX4 variant.</desc>
|
---|
13203 | </const>
|
---|
13204 | <const name="ICH6" value="6">
|
---|
13205 | <desc>An IDE controller of the ICH6 variant.</desc>
|
---|
13206 | </const>
|
---|
13207 | <const name="I82078" value="7">
|
---|
13208 | <desc>A floppy disk controller; this is the only variant for floppy drives.</desc>
|
---|
13209 | </const>
|
---|
13210 | <const name="LsiLogicSas" value="8">
|
---|
13211 | <desc>A variant of the LsiLogic controller using SAS.</desc>
|
---|
13212 | </const>
|
---|
13213 | </enum>
|
---|
13214 |
|
---|
13215 | <enum
|
---|
13216 | name="ChipsetType"
|
---|
13217 | uuid="8b4096a8-a7c3-4d3b-bbb1-05a0a51ec394"
|
---|
13218 | >
|
---|
13219 | <desc>
|
---|
13220 | Type of emulated chipset (mostly southbridge).
|
---|
13221 | </desc>
|
---|
13222 |
|
---|
13223 | <const name="Null" value="0">
|
---|
13224 | <desc>@c null value. Never used by the API.</desc>
|
---|
13225 | </const>
|
---|
13226 | <const name="PIIX3" value="1">
|
---|
13227 | <desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc>
|
---|
13228 | </const>
|
---|
13229 | <const name="ICH9" value="2">
|
---|
13230 | <desc>A ICH9 (I/O Controller Hub) chipset.</desc>
|
---|
13231 | </const>
|
---|
13232 | </enum>
|
---|
13233 |
|
---|
13234 | <interface
|
---|
13235 | name="IStorageController" extends="$unknown"
|
---|
13236 | uuid="fd93adc0-bbaa-4256-9e6e-00e29f9151c9"
|
---|
13237 | wsmap="managed"
|
---|
13238 | >
|
---|
13239 | <desc>
|
---|
13240 | Represents a storage controller that is attached to a virtual machine
|
---|
13241 | (<link to="IMachine" />). Just as drives (hard disks, DVDs, FDs) are
|
---|
13242 | attached to storage controllers in a real computer, virtual drives
|
---|
13243 | (represented by <link to="IMediumAttachment" />) are attached to virtual
|
---|
13244 | storage controllers, represented by this interface.
|
---|
13245 |
|
---|
13246 | As opposed to physical hardware, VirtualBox has a very generic concept
|
---|
13247 | of a storage controller, and for purposes of the Main API, all virtual
|
---|
13248 | storage is attached to virtual machines via instances of this interface.
|
---|
13249 | There are five types of such virtual storage controllers: IDE, SCSI, SATA,
|
---|
13250 | SAS and Floppy (see <link to="#bus" />). Depending on which of these four
|
---|
13251 | is used, certain sub-types may be available and can be selected in
|
---|
13252 | <link to="#controllerType" />.
|
---|
13253 |
|
---|
13254 | Depending on these settings, the guest operating system might see
|
---|
13255 | significantly different virtual hardware.
|
---|
13256 | </desc>
|
---|
13257 |
|
---|
13258 | <attribute name="name" type="wstring" readonly="yes">
|
---|
13259 | <desc>
|
---|
13260 | Name of the storage controller, as originally specified with
|
---|
13261 | <link to="IMachine::addStorageController" />. This then uniquely
|
---|
13262 | identifies this controller with other method calls such as
|
---|
13263 | <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />.
|
---|
13264 | </desc>
|
---|
13265 | </attribute>
|
---|
13266 |
|
---|
13267 | <attribute name="maxDevicesPerPortCount" type="unsigned long" readonly="yes">
|
---|
13268 | <desc>
|
---|
13269 | Maximum number of devices which can be attached to one port.
|
---|
13270 | </desc>
|
---|
13271 | </attribute>
|
---|
13272 |
|
---|
13273 | <attribute name="minPortCount" type="unsigned long" readonly="yes">
|
---|
13274 | <desc>
|
---|
13275 | Minimum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
13276 | </desc>
|
---|
13277 | </attribute>
|
---|
13278 |
|
---|
13279 | <attribute name="maxPortCount" type="unsigned long" readonly="yes">
|
---|
13280 | <desc>
|
---|
13281 | Maximum number of ports that <link to="IStorageController::portCount"/> can be set to.
|
---|
13282 | </desc>
|
---|
13283 | </attribute>
|
---|
13284 |
|
---|
13285 | <attribute name="instance" type="unsigned long">
|
---|
13286 | <desc>
|
---|
13287 | The instance number of the device in the running VM.
|
---|
13288 | </desc>
|
---|
13289 | </attribute>
|
---|
13290 |
|
---|
13291 | <attribute name="portCount" type="unsigned long">
|
---|
13292 | <desc>
|
---|
13293 | The number of currently usable ports on the controller.
|
---|
13294 | The minimum and maximum number of ports for one controller are
|
---|
13295 | stored in <link to="IStorageController::minPortCount"/>
|
---|
13296 | and <link to="IStorageController::maxPortCount"/>.
|
---|
13297 | </desc>
|
---|
13298 | </attribute>
|
---|
13299 |
|
---|
13300 | <attribute name="bus" type="StorageBus" readonly="yes">
|
---|
13301 | <desc>
|
---|
13302 | The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy).
|
---|
13303 | </desc>
|
---|
13304 | </attribute>
|
---|
13305 |
|
---|
13306 | <attribute name="controllerType" type="StorageControllerType">
|
---|
13307 | <desc>
|
---|
13308 | The exact variant of storage controller hardware presented
|
---|
13309 | to the guest.
|
---|
13310 | Depending on this value, VirtualBox will provide a different
|
---|
13311 | virtual storage controller hardware to the guest.
|
---|
13312 | For SATA, SAS and floppy controllers, only one variant is
|
---|
13313 | available, but for IDE and SCSI, there are several.
|
---|
13314 |
|
---|
13315 | For SCSI controllers, the default type is LsiLogic.
|
---|
13316 | </desc>
|
---|
13317 | </attribute>
|
---|
13318 |
|
---|
13319 | <attribute name="useHostIOCache" type="boolean">
|
---|
13320 | <desc>
|
---|
13321 | If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O
|
---|
13322 | caches and use synchronous file APIs on the host. This was the only option in the API before
|
---|
13323 | VirtualBox 3.2 and is still the default for IDE controllers.
|
---|
13324 |
|
---|
13325 | If false, the host I/O cache will be disabled for image files attached to this storage controller.
|
---|
13326 | Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes
|
---|
13327 | it possible to turn off the host I/O caches because the emulation can handle unaligned access to
|
---|
13328 | the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many
|
---|
13329 | virtual machines are running at the same time to prevent I/O cache related hangs.
|
---|
13330 | This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers.
|
---|
13331 | </desc>
|
---|
13332 | </attribute>
|
---|
13333 |
|
---|
13334 | <method name="getIDEEmulationPort">
|
---|
13335 | <desc>
|
---|
13336 | Gets the corresponding port number which is emulated as an IDE device.
|
---|
13337 | Works only with SATA controllers.
|
---|
13338 |
|
---|
13339 | <result name="E_INVALIDARG">
|
---|
13340 | The @a devicePosition is not in the range 0 to 3.
|
---|
13341 | </result>
|
---|
13342 | <result name="E_NOTIMPL">
|
---|
13343 | The storage controller type is not SATAIntelAhci.
|
---|
13344 | </result>
|
---|
13345 |
|
---|
13346 | </desc>
|
---|
13347 | <param name="devicePosition" type="long" dir="in"/>
|
---|
13348 | <param name="portNumber" type="long" dir="return"/>
|
---|
13349 | </method>
|
---|
13350 |
|
---|
13351 | <method name="setIDEEmulationPort">
|
---|
13352 | <desc>
|
---|
13353 | Sets the port number which is emulated as an IDE device.
|
---|
13354 | Works only with SATA controllers.
|
---|
13355 |
|
---|
13356 | <result name="E_INVALIDARG">
|
---|
13357 | The @a devicePosition is not in the range 0 to 3 or the
|
---|
13358 | @a portNumber is not in the range 0 to 29.
|
---|
13359 | </result>
|
---|
13360 | <result name="E_NOTIMPL">
|
---|
13361 | The storage controller type is not SATAIntelAhci.
|
---|
13362 | </result>
|
---|
13363 |
|
---|
13364 | </desc>
|
---|
13365 | <param name="devicePosition" type="long" dir="in"/>
|
---|
13366 | <param name="portNumber" type="long" dir="in"/>
|
---|
13367 | </method>
|
---|
13368 |
|
---|
13369 | </interface>
|
---|
13370 |
|
---|
13371 | <if target="wsdl">
|
---|
13372 |
|
---|
13373 | <!--
|
---|
13374 | // IManagedObjectRef
|
---|
13375 | /////////////////////////////////////////////////////////////////////////
|
---|
13376 | -->
|
---|
13377 |
|
---|
13378 | <interface
|
---|
13379 | name="IManagedObjectRef" extends="$unknown"
|
---|
13380 | uuid="9474d09d-2313-46de-b568-a42b8718e8ed"
|
---|
13381 | internal="yes"
|
---|
13382 | wsmap="managed"
|
---|
13383 | wscpp="hardcoded"
|
---|
13384 | >
|
---|
13385 | <desc>
|
---|
13386 | Managed object reference.
|
---|
13387 |
|
---|
13388 | Only within the webservice, a managed object reference (which is really
|
---|
13389 | an opaque number) allows a webservice client to address an object
|
---|
13390 | that lives in the address space of the webservice server.
|
---|
13391 |
|
---|
13392 | Behind each managed object reference, there is a COM object that lives
|
---|
13393 | in the webservice server's address space. The COM object is not freed
|
---|
13394 | until the managed object reference is released, either by an explicit
|
---|
13395 | call to <link to="IManagedObjectRef::release" /> or by logging off from
|
---|
13396 | the webservice (<link to="IWebsessionManager::logoff" />), which releases
|
---|
13397 | all objects created during the webservice session.
|
---|
13398 |
|
---|
13399 | Whenever a method call of the VirtualBox API returns a COM object, the
|
---|
13400 | webservice representation of that method will instead return a
|
---|
13401 | managed object reference, which can then be used to invoke methods
|
---|
13402 | on that object.
|
---|
13403 | </desc>
|
---|
13404 |
|
---|
13405 | <method name="getInterfaceName">
|
---|
13406 | <desc>
|
---|
13407 | Returns the name of the interface that this managed object represents,
|
---|
13408 | for example, "IMachine", as a string.
|
---|
13409 | </desc>
|
---|
13410 | <param name="return" type="wstring" dir="return"/>
|
---|
13411 | </method>
|
---|
13412 |
|
---|
13413 | <method name="release">
|
---|
13414 | <desc>
|
---|
13415 | Releases this managed object reference and frees the resources that
|
---|
13416 | were allocated for it in the webservice server process. After calling
|
---|
13417 | this method, the identifier of the reference can no longer be used.
|
---|
13418 | </desc>
|
---|
13419 | </method>
|
---|
13420 |
|
---|
13421 | </interface>
|
---|
13422 |
|
---|
13423 | <!--
|
---|
13424 | // IWebsessionManager
|
---|
13425 | /////////////////////////////////////////////////////////////////////////
|
---|
13426 | -->
|
---|
13427 |
|
---|
13428 | <interface
|
---|
13429 | name="IWebsessionManager" extends="$unknown"
|
---|
13430 | uuid="dea1b4c7-2de3-418a-850d-7868617f7733"
|
---|
13431 | internal="yes"
|
---|
13432 | wsmap="global"
|
---|
13433 | wscpp="hardcoded"
|
---|
13434 | >
|
---|
13435 | <desc>
|
---|
13436 | Websession manager. This provides essential services
|
---|
13437 | to webservice clients.
|
---|
13438 | </desc>
|
---|
13439 | <method name="logon">
|
---|
13440 | <desc>
|
---|
13441 | Logs a new client onto the webservice and returns a managed object reference to
|
---|
13442 | the IVirtualBox instance, which the client can then use as a basis to further
|
---|
13443 | queries, since all calls to the VirtualBox API are based on the IVirtualBox
|
---|
13444 | interface, in one way or the other.
|
---|
13445 | </desc>
|
---|
13446 | <param name="username" type="wstring" dir="in"/>
|
---|
13447 | <param name="password" type="wstring" dir="in"/>
|
---|
13448 | <param name="return" type="IVirtualBox" dir="return"/>
|
---|
13449 | </method>
|
---|
13450 |
|
---|
13451 | <method name="getSessionObject">
|
---|
13452 | <desc>
|
---|
13453 | Returns a managed object reference to the internal ISession object that was created
|
---|
13454 | for this web service session when the client logged on.
|
---|
13455 |
|
---|
13456 | <see>ISession</see>
|
---|
13457 | </desc>
|
---|
13458 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
13459 | <param name="return" type="ISession" dir="return"/>
|
---|
13460 | </method>
|
---|
13461 |
|
---|
13462 | <method name="logoff">
|
---|
13463 | <desc>
|
---|
13464 | Logs off the client who has previously logged on with <link to="IWebsessionManager::logoff" />
|
---|
13465 | and destroys all resources associated with the session (most importantly, all
|
---|
13466 | managed objects created in the server while the session was active).
|
---|
13467 | </desc>
|
---|
13468 | <param name="refIVirtualBox" type="IVirtualBox" dir="in"/>
|
---|
13469 | </method>
|
---|
13470 |
|
---|
13471 | </interface>
|
---|
13472 |
|
---|
13473 | </if>
|
---|
13474 |
|
---|
13475 | <!--
|
---|
13476 | // IPerformanceCollector & friends
|
---|
13477 | /////////////////////////////////////////////////////////////////////////
|
---|
13478 | -->
|
---|
13479 |
|
---|
13480 | <interface
|
---|
13481 | name="IPerformanceMetric" extends="$unknown"
|
---|
13482 | uuid="2a1a60ae-9345-4019-ad53-d34ba41cbfe9" wsmap="managed"
|
---|
13483 | >
|
---|
13484 | <desc>
|
---|
13485 | The IPerformanceMetric interface represents parameters of the given
|
---|
13486 | performance metric.
|
---|
13487 | </desc>
|
---|
13488 |
|
---|
13489 | <attribute name="metricName" type="wstring" readonly="yes">
|
---|
13490 | <desc>
|
---|
13491 | Name of the metric.
|
---|
13492 | </desc>
|
---|
13493 | </attribute>
|
---|
13494 |
|
---|
13495 | <attribute name="object" type="$unknown" readonly="yes">
|
---|
13496 | <desc>
|
---|
13497 | Object this metric belongs to.
|
---|
13498 | </desc>
|
---|
13499 | </attribute>
|
---|
13500 |
|
---|
13501 | <attribute name="description" type="wstring" readonly="yes">
|
---|
13502 | <desc>
|
---|
13503 | Textual description of the metric.
|
---|
13504 | </desc>
|
---|
13505 | </attribute>
|
---|
13506 |
|
---|
13507 | <attribute name="period" type="unsigned long" readonly="yes">
|
---|
13508 | <desc>
|
---|
13509 | Time interval between samples, measured in seconds.
|
---|
13510 | </desc>
|
---|
13511 | </attribute>
|
---|
13512 |
|
---|
13513 | <attribute name="count" type="unsigned long" readonly="yes">
|
---|
13514 | <desc>
|
---|
13515 | Number of recent samples retained by the performance collector for this
|
---|
13516 | metric.
|
---|
13517 |
|
---|
13518 | When the collected sample count exceeds this number, older samples
|
---|
13519 | are discarded.
|
---|
13520 | </desc>
|
---|
13521 | </attribute>
|
---|
13522 |
|
---|
13523 | <attribute name="unit" type="wstring" readonly="yes">
|
---|
13524 | <desc>
|
---|
13525 | Unit of measurement.
|
---|
13526 | </desc>
|
---|
13527 | </attribute>
|
---|
13528 |
|
---|
13529 | <attribute name="minimumValue" type="long" readonly="yes">
|
---|
13530 | <desc>
|
---|
13531 | Minimum possible value of this metric.
|
---|
13532 | </desc>
|
---|
13533 | </attribute>
|
---|
13534 |
|
---|
13535 | <attribute name="maximumValue" type="long" readonly="yes">
|
---|
13536 | <desc>
|
---|
13537 | Maximum possible value of this metric.
|
---|
13538 | </desc>
|
---|
13539 | </attribute>
|
---|
13540 | </interface>
|
---|
13541 |
|
---|
13542 | <interface
|
---|
13543 | name="IPerformanceCollector" extends="$unknown"
|
---|
13544 | uuid="e22e1acb-ac4a-43bb-a31c-17321659b0c6"
|
---|
13545 | wsmap="managed"
|
---|
13546 | >
|
---|
13547 | <desc>
|
---|
13548 | The IPerformanceCollector interface represents a service that collects
|
---|
13549 | and stores performance metrics data.
|
---|
13550 |
|
---|
13551 | Performance metrics are associated with objects of interfaces like IHost
|
---|
13552 | and IMachine. Each object has a distinct set of performance metrics. The
|
---|
13553 | set can be obtained with <link to="IPerformanceCollector::getMetrics"/>.
|
---|
13554 |
|
---|
13555 | Metric data is collected at the specified intervals and is retained
|
---|
13556 | internally. The interval and the number of retained samples can be set
|
---|
13557 | with <link to="IPerformanceCollector::setupMetrics" />. Both metric data
|
---|
13558 | and collection settings are not persistent, they are discarded as soon as
|
---|
13559 | VBoxSVC process terminates. Moreover, metric settings and data associated
|
---|
13560 | with a particular VM only exist while VM is running. They disappear as
|
---|
13561 | soon as VM shuts down. It is not possible to set up metrics for machines
|
---|
13562 | that are powered off. One needs to start VM first, then set up metric
|
---|
13563 | collection parameters.
|
---|
13564 |
|
---|
13565 | Metrics are organized hierarchically, with each level separated by a
|
---|
13566 | slash (/) character. Generally, the scheme for metric names is like this:
|
---|
13567 |
|
---|
13568 | <tt>Category/Metric[/SubMetric][:aggregation]</tt>
|
---|
13569 |
|
---|
13570 | "Category/Metric" together form the base metric name. A base metric is
|
---|
13571 | the smallest unit for which a sampling interval and the number of
|
---|
13572 | retained samples can be set. Only base metrics can be enabled and
|
---|
13573 | disabled. All sub-metrics are collected when their base metric is
|
---|
13574 | collected. Collected values for any set of sub-metrics can be queried
|
---|
13575 | with <link to="IPerformanceCollector::queryMetricsData" />.
|
---|
13576 |
|
---|
13577 | For example "CPU/Load/User:avg" metric name stands for the "CPU"
|
---|
13578 | category, "Load" metric, "User" submetric, "average" aggregate. An
|
---|
13579 | aggregate function is computed over all retained data. Valid aggregate
|
---|
13580 | functions are:
|
---|
13581 |
|
---|
13582 | <ul>
|
---|
13583 | <li>avg -- average</li>
|
---|
13584 | <li>min -- minimum</li>
|
---|
13585 | <li>max -- maximum</li>
|
---|
13586 | </ul>
|
---|
13587 |
|
---|
13588 | When setting up metric parameters, querying metric data, enabling or
|
---|
13589 | disabling metrics wildcards can be used in metric names to specify a
|
---|
13590 | subset of metrics. For example, to select all CPU-related metrics
|
---|
13591 | use <tt>CPU/*</tt>, all averages can be queried using <tt>*:avg</tt> and
|
---|
13592 | so on. To query metric values without aggregates <tt>*:</tt> can be used.
|
---|
13593 |
|
---|
13594 | The valid names for base metrics are:
|
---|
13595 |
|
---|
13596 | <ul>
|
---|
13597 | <li>CPU/Load</li>
|
---|
13598 | <li>CPU/MHz</li>
|
---|
13599 | <li>RAM/Usage</li>
|
---|
13600 | </ul>
|
---|
13601 |
|
---|
13602 | The general sequence for collecting and retrieving the metrics is:
|
---|
13603 | <ul>
|
---|
13604 | <li>
|
---|
13605 | Obtain an instance of IPerformanceCollector with
|
---|
13606 | <link to="IVirtualBox::performanceCollector" />
|
---|
13607 | </li>
|
---|
13608 | <li>
|
---|
13609 | Allocate and populate an array with references to objects the metrics
|
---|
13610 | will be collected for. Use references to IHost and IMachine objects.
|
---|
13611 | </li>
|
---|
13612 | <li>
|
---|
13613 | Allocate and populate an array with base metric names the data will
|
---|
13614 | be collected for.
|
---|
13615 | </li>
|
---|
13616 | <li>
|
---|
13617 | Call <link to="IPerformanceCollector::setupMetrics" />. From now on
|
---|
13618 | the metric data will be collected and stored.
|
---|
13619 | </li>
|
---|
13620 | <li>
|
---|
13621 | Wait for the data to get collected.
|
---|
13622 | </li>
|
---|
13623 | <li>
|
---|
13624 | Allocate and populate an array with references to objects the metric
|
---|
13625 | values will be queried for. You can re-use the object array used for
|
---|
13626 | setting base metrics.
|
---|
13627 | </li>
|
---|
13628 | <li>
|
---|
13629 | Allocate and populate an array with metric names the data will be
|
---|
13630 | collected for. Note that metric names differ from base metric names.
|
---|
13631 | </li>
|
---|
13632 | <li>
|
---|
13633 | Call <link to="IPerformanceCollector::queryMetricsData" />. The data
|
---|
13634 | that have been collected so far are returned. Note that the values
|
---|
13635 | are still retained internally and data collection continues.
|
---|
13636 | </li>
|
---|
13637 | </ul>
|
---|
13638 |
|
---|
13639 | For an example of usage refer to the following files in VirtualBox SDK:
|
---|
13640 | <ul>
|
---|
13641 | <li>
|
---|
13642 | Java: <tt>bindings/webservice/java/jax-ws/samples/metrictest.java</tt>
|
---|
13643 | </li>
|
---|
13644 | <li>
|
---|
13645 | Python: <tt>bindings/xpcom/python/sample/shellcommon.py</tt>
|
---|
13646 | </li>
|
---|
13647 | </ul>
|
---|
13648 | </desc>
|
---|
13649 |
|
---|
13650 | <attribute name="metricNames" type="wstring" readonly="yes" safearray="yes">
|
---|
13651 | <desc>
|
---|
13652 | Array of unique names of metrics.
|
---|
13653 |
|
---|
13654 | This array represents all metrics supported by the performance
|
---|
13655 | collector. Individual objects do not necessarily support all of them.
|
---|
13656 | <link to="IPerformanceCollector::getMetrics"/> can be used to get the
|
---|
13657 | list of supported metrics for a particular object.
|
---|
13658 | </desc>
|
---|
13659 | </attribute>
|
---|
13660 |
|
---|
13661 | <method name="getMetrics">
|
---|
13662 | <desc>
|
---|
13663 | Returns parameters of specified metrics for a set of objects.
|
---|
13664 | <note>
|
---|
13665 | @c Null metrics array means all metrics. @c Null object array means
|
---|
13666 | all existing objects.
|
---|
13667 | </note>
|
---|
13668 | </desc>
|
---|
13669 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13670 | <desc>
|
---|
13671 | Metric name filter. Currently, only a comma-separated list of metrics
|
---|
13672 | is supported.
|
---|
13673 | </desc>
|
---|
13674 | </param>
|
---|
13675 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13676 | <desc>
|
---|
13677 | Set of objects to return metric parameters for.
|
---|
13678 | </desc>
|
---|
13679 | </param>
|
---|
13680 | <param name="metrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13681 | <desc>
|
---|
13682 | Array of returned metric parameters.
|
---|
13683 | </desc>
|
---|
13684 | </param>
|
---|
13685 | </method>
|
---|
13686 |
|
---|
13687 | <method name="setupMetrics">
|
---|
13688 | <desc>
|
---|
13689 | Sets parameters of specified base metrics for a set of objects. Returns
|
---|
13690 | an array of <link to="IPerformanceMetric" /> describing the metrics
|
---|
13691 | have been affected.
|
---|
13692 | <note>
|
---|
13693 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
13694 | empty object array means all existing objects. If metric name array
|
---|
13695 | contains a single element and object array contains many, the single
|
---|
13696 | metric name array element is applied to each object array element to
|
---|
13697 | form metric/object pairs.
|
---|
13698 | </note>
|
---|
13699 | </desc>
|
---|
13700 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13701 | <desc>
|
---|
13702 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13703 | support.
|
---|
13704 | </desc>
|
---|
13705 | </param>
|
---|
13706 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13707 | <desc>
|
---|
13708 | Set of objects to setup metric parameters for.
|
---|
13709 | </desc>
|
---|
13710 | </param>
|
---|
13711 | <param name="period" type="unsigned long" dir="in">
|
---|
13712 | <desc>
|
---|
13713 | Time interval in seconds between two consecutive samples of
|
---|
13714 | performance data.
|
---|
13715 | </desc>
|
---|
13716 | </param>
|
---|
13717 | <param name="count" type="unsigned long" dir="in">
|
---|
13718 | <desc>
|
---|
13719 | Number of samples to retain in performance data history. Older
|
---|
13720 | samples get discarded.
|
---|
13721 | </desc>
|
---|
13722 | </param>
|
---|
13723 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13724 | <desc>
|
---|
13725 | Array of metrics that have been modified by the call to this method.
|
---|
13726 | </desc>
|
---|
13727 | </param>
|
---|
13728 | </method>
|
---|
13729 |
|
---|
13730 | <method name="enableMetrics">
|
---|
13731 | <desc>
|
---|
13732 | Turns on collecting specified base metrics. Returns an array of
|
---|
13733 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
13734 | affected.
|
---|
13735 | <note>
|
---|
13736 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
13737 | empty object array means all existing objects. If metric name array
|
---|
13738 | contains a single element and object array contains many, the single
|
---|
13739 | metric name array element is applied to each object array element to
|
---|
13740 | form metric/object pairs.
|
---|
13741 | </note>
|
---|
13742 | </desc>
|
---|
13743 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13744 | <desc>
|
---|
13745 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13746 | support.
|
---|
13747 | </desc>
|
---|
13748 | </param>
|
---|
13749 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13750 | <desc>
|
---|
13751 | Set of objects to enable metrics for.
|
---|
13752 | </desc>
|
---|
13753 | </param>
|
---|
13754 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13755 | <desc>
|
---|
13756 | Array of metrics that have been modified by the call to this method.
|
---|
13757 | </desc>
|
---|
13758 | </param>
|
---|
13759 | </method>
|
---|
13760 |
|
---|
13761 | <method name="disableMetrics">
|
---|
13762 | <desc>
|
---|
13763 | Turns off collecting specified base metrics. Returns an array of
|
---|
13764 | <link to="IPerformanceMetric" /> describing the metrics have been
|
---|
13765 | affected.
|
---|
13766 | <note>
|
---|
13767 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
13768 | empty object array means all existing objects. If metric name array
|
---|
13769 | contains a single element and object array contains many, the single
|
---|
13770 | metric name array element is applied to each object array element to
|
---|
13771 | form metric/object pairs.
|
---|
13772 | </note>
|
---|
13773 | </desc>
|
---|
13774 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13775 | <desc>
|
---|
13776 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13777 | support.
|
---|
13778 | </desc>
|
---|
13779 | </param>
|
---|
13780 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13781 | <desc>
|
---|
13782 | Set of objects to disable metrics for.
|
---|
13783 | </desc>
|
---|
13784 | </param>
|
---|
13785 | <param name="affectedMetrics" type="IPerformanceMetric" dir="return" safearray="yes">
|
---|
13786 | <desc>
|
---|
13787 | Array of metrics that have been modified by the call to this method.
|
---|
13788 | </desc>
|
---|
13789 | </param>
|
---|
13790 | </method>
|
---|
13791 |
|
---|
13792 | <method name="queryMetricsData">
|
---|
13793 | <desc>
|
---|
13794 | Queries collected metrics data for a set of objects.
|
---|
13795 |
|
---|
13796 | The data itself and related metric information are returned in seven
|
---|
13797 | parallel and one flattened array of arrays. Elements of
|
---|
13798 | <tt>returnMetricNames, returnObjects, returnUnits, returnScales,
|
---|
13799 | returnSequenceNumbers, returnDataIndices and returnDataLengths</tt> with
|
---|
13800 | the same index describe one set of values corresponding to a single
|
---|
13801 | metric.
|
---|
13802 |
|
---|
13803 | The <tt>returnData</tt> parameter is a flattened array of arrays. Each
|
---|
13804 | start and length of a sub-array is indicated by
|
---|
13805 | <tt>returnDataIndices</tt> and <tt>returnDataLengths</tt>. The first
|
---|
13806 | value for metric <tt>metricNames[i]</tt> is at
|
---|
13807 | <tt>returnData[returnIndices[i]]</tt>.
|
---|
13808 |
|
---|
13809 | <note>
|
---|
13810 | @c Null or empty metric name array means all metrics. @c Null or
|
---|
13811 | empty object array means all existing objects. If metric name array
|
---|
13812 | contains a single element and object array contains many, the single
|
---|
13813 | metric name array element is applied to each object array element to
|
---|
13814 | form metric/object pairs.
|
---|
13815 | </note>
|
---|
13816 | <note>
|
---|
13817 | Data collection continues behind the scenes after call to @c
|
---|
13818 | queryMetricsData. The return data can be seen as the snapshot of the
|
---|
13819 | current state at the time of @c queryMetricsData call. The internally
|
---|
13820 | kept metric values are not cleared by the call. This makes possible
|
---|
13821 | querying different subsets of metrics or aggregates with subsequent
|
---|
13822 | calls. If periodic querying is needed it is highly suggested to query
|
---|
13823 | the values with @c interval*count period to avoid confusion. This way
|
---|
13824 | a completely new set of data values will be provided by each query.
|
---|
13825 | </note>
|
---|
13826 | </desc>
|
---|
13827 | <param name="metricNames" type="wstring" dir="in" safearray="yes">
|
---|
13828 | <desc>
|
---|
13829 | Metric name filter. Comma-separated list of metrics with wildcard
|
---|
13830 | support.
|
---|
13831 | </desc>
|
---|
13832 | </param>
|
---|
13833 | <param name="objects" type="$unknown" dir="in" safearray="yes">
|
---|
13834 | <desc>
|
---|
13835 | Set of objects to query metrics for.
|
---|
13836 | </desc>
|
---|
13837 | </param>
|
---|
13838 | <param name="returnMetricNames" type="wstring" dir="out" safearray="yes">
|
---|
13839 | <desc>
|
---|
13840 | Names of metrics returned in @c returnData.
|
---|
13841 | </desc>
|
---|
13842 | </param>
|
---|
13843 | <param name="returnObjects" type="$unknown" dir="out" safearray="yes">
|
---|
13844 | <desc>
|
---|
13845 | Objects associated with metrics returned in @c returnData.
|
---|
13846 | </desc>
|
---|
13847 | </param>
|
---|
13848 | <param name="returnUnits" type="wstring" dir="out" safearray="yes">
|
---|
13849 | <desc>
|
---|
13850 | Units of measurement for each returned metric.
|
---|
13851 | </desc>
|
---|
13852 | </param>
|
---|
13853 | <param name="returnScales" type="unsigned long" dir="out" safearray="yes">
|
---|
13854 | <desc>
|
---|
13855 | Divisor that should be applied to return values in order to get
|
---|
13856 | floating point values. For example:
|
---|
13857 | <tt>(double)returnData[returnDataIndices[0]+i] / returnScales[0]</tt>
|
---|
13858 | will retrieve the floating point value of i-th sample of the first
|
---|
13859 | metric.
|
---|
13860 | </desc>
|
---|
13861 | </param>
|
---|
13862 | <param name="returnSequenceNumbers" type="unsigned long" dir="out" safearray="yes">
|
---|
13863 | <desc>
|
---|
13864 | Sequence numbers of the first elements of value sequences of
|
---|
13865 | particular metrics returned in @c returnData. For aggregate metrics
|
---|
13866 | it is the sequence number of the sample the aggregate started
|
---|
13867 | calculation from.
|
---|
13868 | </desc>
|
---|
13869 | </param>
|
---|
13870 | <param name="returnDataIndices" type="unsigned long" dir="out" safearray="yes">
|
---|
13871 | <desc>
|
---|
13872 | Indices of the first elements of value sequences of particular
|
---|
13873 | metrics returned in @c returnData.
|
---|
13874 | </desc>
|
---|
13875 | </param>
|
---|
13876 | <param name="returnDataLengths" type="unsigned long" dir="out" safearray="yes">
|
---|
13877 | <desc>
|
---|
13878 | Lengths of value sequences of particular metrics.
|
---|
13879 | </desc>
|
---|
13880 | </param>
|
---|
13881 | <param name="returnData" type="long" dir="return" safearray="yes">
|
---|
13882 | <desc>
|
---|
13883 | Flattened array of all metric data containing sequences of values for
|
---|
13884 | each metric.
|
---|
13885 | </desc>
|
---|
13886 | </param>
|
---|
13887 | </method>
|
---|
13888 |
|
---|
13889 | </interface>
|
---|
13890 | <enum
|
---|
13891 | name="NATAliasMode"
|
---|
13892 | uuid="67772168-50d9-11df-9669-7fb714ee4fa1">
|
---|
13893 | <desc></desc>
|
---|
13894 | <const name="AliasLog" value="0x1">
|
---|
13895 | <desc></desc>
|
---|
13896 | </const>
|
---|
13897 | <const name="AliasProxyOnly" value="0x02">
|
---|
13898 | <desc></desc>
|
---|
13899 | </const>
|
---|
13900 | <const name="AliasUseSamePorts" value="0x04">
|
---|
13901 | <desc></desc>
|
---|
13902 | </const>
|
---|
13903 | </enum>
|
---|
13904 | <enum
|
---|
13905 | name="NATProtocol"
|
---|
13906 | uuid="e90164be-eb03-11de-94af-fff9b1c1b19f"
|
---|
13907 | >
|
---|
13908 | <desc>Protocol definitions used with NAT port-forwarding rules.</desc>
|
---|
13909 | <const name="UDP" value="0">
|
---|
13910 | <desc>Port-forwarding uses UDP protocol.</desc>
|
---|
13911 | </const>
|
---|
13912 | <const name="TCP" value="1">
|
---|
13913 | <desc>Port-forwarding uses TCP protocol.</desc>
|
---|
13914 | </const>
|
---|
13915 | </enum>
|
---|
13916 |
|
---|
13917 | <interface
|
---|
13918 | name="INATEngine" extends="$unknown"
|
---|
13919 | uuid="4b286616-eb03-11de-b0fb-1701eca42246"
|
---|
13920 | wsmap="managed"
|
---|
13921 | >
|
---|
13922 | <desc>Interface for managing a NAT engine which is used with a virtual machine. This
|
---|
13923 | allows for changing NAT behavior such as port-forwarding rules. This interface is
|
---|
13924 | used in the <link to="INetworkAdapter::natDriver" /> attribute.</desc>
|
---|
13925 | <attribute name="network" type="wstring">
|
---|
13926 | <desc>The network attribute of the NAT engine (the same value is used with built-in
|
---|
13927 | DHCP server to fill corresponding fields of DHCP leases).</desc>
|
---|
13928 | </attribute>
|
---|
13929 | <attribute name="hostIP" type="wstring">
|
---|
13930 | <desc>IP of host interface to bind all opened sockets to.
|
---|
13931 | <note>Changing this does not change binding of port forwarding.</note>
|
---|
13932 | </desc>
|
---|
13933 | </attribute>
|
---|
13934 | <attribute name="tftpPrefix" type="wstring">
|
---|
13935 | <desc>TFTP prefix attribute which is used with the built-in DHCP server to fill
|
---|
13936 | the corresponding fields of DHCP leases.</desc>
|
---|
13937 | </attribute>
|
---|
13938 | <attribute name="tftpBootFile" type="wstring">
|
---|
13939 | <desc>TFTP boot file attribute which is used with the built-in DHCP server to fill
|
---|
13940 | the corresponding fields of DHCP leases.</desc>
|
---|
13941 | </attribute>
|
---|
13942 | <attribute name="tftpNextServer" type="wstring">
|
---|
13943 | <desc>TFTP server attribute which is used with the built-in DHCP server to fill
|
---|
13944 | the corresponding fields of DHCP leases.
|
---|
13945 | <note>The preferred form is IPv4 addresses.</note>
|
---|
13946 | </desc>
|
---|
13947 | </attribute>
|
---|
13948 | <attribute name="aliasMode" type="unsigned long">
|
---|
13949 | <desc></desc>
|
---|
13950 | </attribute>
|
---|
13951 | <attribute name="dnsPassDomain" type="boolean">
|
---|
13952 | <desc>Whether the DHCP server should pass the DNS domain used by the host.</desc>
|
---|
13953 | </attribute>
|
---|
13954 | <attribute name="dnsProxy" type="boolean">
|
---|
13955 | <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
|
---|
13956 | of the DNS proxy and process traffic using DNS servers registered on the host.</desc>
|
---|
13957 | </attribute>
|
---|
13958 | <attribute name="dnsUseHostResolver" type="boolean">
|
---|
13959 | <desc>Whether the DHCP server (and the DNS traffic by NAT) should pass the address
|
---|
13960 | of the DNS proxy and process traffic using the host resolver mechanism.</desc>
|
---|
13961 | </attribute>
|
---|
13962 | <attribute name="redirects" type="wstring" readonly="yes" safearray="yes">
|
---|
13963 | <desc>Array of NAT port-forwarding rules in string representation, in the following
|
---|
13964 | format: "name,protocol id,host ip,host port,guest ip,guest port".</desc>
|
---|
13965 | </attribute>
|
---|
13966 | <method name="setNetworkSettings">
|
---|
13967 | <desc>Sets network configuration of the NAT engine.</desc>
|
---|
13968 | <param name="mtu" type="unsigned long" dir="in">
|
---|
13969 | <desc>MTU (maximum transmission unit) of the NAT engine in bytes.</desc>
|
---|
13970 | </param>
|
---|
13971 | <param name="sockSnd" type="unsigned long" dir="in">
|
---|
13972 | <desc>Capacity of the socket send buffer in bytes when creating a new socket.</desc>
|
---|
13973 | </param>
|
---|
13974 | <param name="sockRcv" type="unsigned long" dir="in">
|
---|
13975 | <desc>Capacity of the socket receive buffer in bytes when creating a new socket.</desc>
|
---|
13976 | </param>
|
---|
13977 | <param name="TcpWndSnd" type="unsigned long" dir="in">
|
---|
13978 | <desc>Initial size of the NAT engine's sending TCP window in bytes when
|
---|
13979 | establishing a new TCP connection.</desc>
|
---|
13980 | </param>
|
---|
13981 | <param name="TcpWndRcv" type="unsigned long" dir="in">
|
---|
13982 | <desc>Initial size of the NAT engine's receiving TCP window in bytes when
|
---|
13983 | establishing a new TCP connection.</desc>
|
---|
13984 | </param>
|
---|
13985 | </method>
|
---|
13986 | <method name="getNetworkSettings">
|
---|
13987 | <desc>Returns network configuration of NAT engine. See <link to="#setNetworkSettings" />
|
---|
13988 | for parameter descriptions.</desc>
|
---|
13989 | <param name="mtu" type="unsigned long" dir="out" />
|
---|
13990 | <param name="sockSnd" type="unsigned long" dir="out" />
|
---|
13991 | <param name="sockRcv" type="unsigned long" dir="out" />
|
---|
13992 | <param name="TcpWndSnd" type="unsigned long" dir="out" />
|
---|
13993 | <param name="TcpWndRcv" type="unsigned long" dir="out" />
|
---|
13994 | </method>
|
---|
13995 | <method name="addRedirect">
|
---|
13996 | <desc>Adds a new NAT port-forwarding rule.</desc>
|
---|
13997 | <param name="name" type="wstring" dir="in">
|
---|
13998 | <desc>The name of the rule. An empty name is acceptable, in which case the NAT engine
|
---|
13999 | auto-generates one using the other parameters.</desc>
|
---|
14000 | </param>
|
---|
14001 | <param name="proto" type="NATProtocol" dir="in">
|
---|
14002 | <desc>Protocol handled with the rule.</desc>
|
---|
14003 | </param>
|
---|
14004 | <param name="hostIp" type="wstring" dir="in">
|
---|
14005 | <desc>IP of the host interface to which the rule should apply. An empty ip address is
|
---|
14006 | acceptable, in which case the NAT engine binds the handling socket to any interface.</desc>
|
---|
14007 | </param>
|
---|
14008 | <param name="hostPort" type="unsigned short" dir="in">
|
---|
14009 | <desc>The port number to listen on.</desc>
|
---|
14010 | </param>
|
---|
14011 | <param name="guestIp" type="wstring" dir="in">
|
---|
14012 | <desc>The IP address of the guest which the NAT engine will forward matching packets
|
---|
14013 | to. An empty IP address is acceptable, in which case the NAT engine will forward
|
---|
14014 | packets to the first DHCP lease (x.x.x.15).</desc>
|
---|
14015 | </param>
|
---|
14016 | <param name="guestPort" type="unsigned short" dir="in">
|
---|
14017 | <desc>The port number to forward.</desc>
|
---|
14018 | </param>
|
---|
14019 | </method>
|
---|
14020 | <method name="removeRedirect">
|
---|
14021 | <desc>Removes a port-forwarding rule that was previously registered.</desc>
|
---|
14022 | <param name="name" type="wstring" dir="in">
|
---|
14023 | <desc>The name of the rule to delete.</desc>
|
---|
14024 | </param>
|
---|
14025 | </method>
|
---|
14026 | </interface>
|
---|
14027 |
|
---|
14028 | <!--
|
---|
14029 | // IExtPackManager
|
---|
14030 | /////////////////////////////////////////////////////////////////////////
|
---|
14031 | -->
|
---|
14032 |
|
---|
14033 | <interface
|
---|
14034 | name="IExtPack" extends="$unknown"
|
---|
14035 | uuid="ab26b24e-d46c-4d09-aa44-e5092d2fe9ae"
|
---|
14036 | wsmap="suppress"
|
---|
14037 | >
|
---|
14038 | <desc>
|
---|
14039 | Interface for querying interfaces and information relating to an
|
---|
14040 | extension pack. The extension pack specific interfaces can be queried
|
---|
14041 | via the IUnknown::QueryInterface method.
|
---|
14042 | </desc>
|
---|
14043 | <attribute name="name" type="wstring" readonly="yes">
|
---|
14044 | <desc>The extension pack name. This is unique.</desc>
|
---|
14045 | </attribute>
|
---|
14046 | <attribute name="description" type="wstring" readonly="yes">
|
---|
14047 | <desc>The extension pack description.</desc>
|
---|
14048 | </attribute>
|
---|
14049 | <attribute name="version" type="wstring" readonly="yes">
|
---|
14050 | <desc>
|
---|
14051 | The extension pack version string. This is on the same form as
|
---|
14052 | other VirtualBox version strings, i.e.: "1.2.3", "1.2.3_BETA1",
|
---|
14053 | "1.2.3-OSE", "1.2.3r45678", "1.2.3r45678-OSE", "1.2.3_BETA1-r45678"
|
---|
14054 | or "1.2.3_BETA1-r45678-OSE"
|
---|
14055 | </desc>
|
---|
14056 | </attribute>
|
---|
14057 | <attribute name="revision" type="unsigned long" readonly="yes">
|
---|
14058 | <desc>The extension pack internal revision number.</desc>
|
---|
14059 | </attribute>
|
---|
14060 | <attribute name="usable" type="boolean" readonly="yes">
|
---|
14061 | <desc>
|
---|
14062 | Indicates whether the extension pack is usable or not. An
|
---|
14063 | extension pack that is not compatible with the current VirtualBox
|
---|
14064 | version will be flagged as not usable.
|
---|
14065 | </desc>
|
---|
14066 | </attribute>
|
---|
14067 | <attribute name="whyUnusable" type="wstring" readonly="yes">
|
---|
14068 | <desc>
|
---|
14069 | String indicating why the extension pack is not usable. This is an
|
---|
14070 | empty string if usable and always a non-empty string if not usable.
|
---|
14071 | </desc>
|
---|
14072 | </attribute>
|
---|
14073 | </interface>
|
---|
14074 |
|
---|
14075 | <interface
|
---|
14076 | name="IExtPackManager" extends="$unknown"
|
---|
14077 | uuid="ba1fbfca-53f1-471c-b5a1-416386f0f52b"
|
---|
14078 | wsmap="suppress"
|
---|
14079 | >
|
---|
14080 | <desc>
|
---|
14081 | Interface for managing VirtualBox Extension Packs.
|
---|
14082 |
|
---|
14083 | TODO: Describe extension packs, how they are managed and how to create
|
---|
14084 | one.
|
---|
14085 | </desc>
|
---|
14086 |
|
---|
14087 | <attribute name="installedExtPacks" type="IExtPack" safearray="yes" readonly="yes">
|
---|
14088 | <desc>
|
---|
14089 | List of the installed extension packs.
|
---|
14090 | </desc>
|
---|
14091 | </attribute>
|
---|
14092 |
|
---|
14093 | <method name="find">
|
---|
14094 | <desc>
|
---|
14095 | Returns the extension pack with the specified name if found.
|
---|
14096 |
|
---|
14097 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
14098 | No extension pack matching @a name was found.
|
---|
14099 | </result>
|
---|
14100 | </desc>
|
---|
14101 | <param name="name" type="wstring" dir="in">
|
---|
14102 | <desc>The name of the extension pack to locate.</desc>
|
---|
14103 | </param>
|
---|
14104 | <param name="returnData" type="IExtPack" dir="return">
|
---|
14105 | <desc>The extension pack if found.</desc>
|
---|
14106 | </param>
|
---|
14107 | </method>
|
---|
14108 |
|
---|
14109 | <method name="install">
|
---|
14110 | <param name="path" type="wstring" dir="in">
|
---|
14111 | <desc>The path of the extension pack tarball.</desc>
|
---|
14112 | </param>
|
---|
14113 | <param name="name" type="wstring" dir="out">
|
---|
14114 | <desc>The name of the installed extension pack.</desc>
|
---|
14115 | </param>
|
---|
14116 | </method>
|
---|
14117 |
|
---|
14118 | <method name="uninstall">
|
---|
14119 | <desc>Uninstalls an extension pack, removing all related files.</desc>
|
---|
14120 | <param name="name" type="wstring" dir="in">
|
---|
14121 | <desc>The name of the extension pack to uninstall.</desc>
|
---|
14122 | </param>
|
---|
14123 | <param name="forcedRemoval" type="boolean" dir="in">
|
---|
14124 | <desc>
|
---|
14125 | Forced removal of the extension pack. This means that the uninstall
|
---|
14126 | hook will not be called.
|
---|
14127 | </desc>
|
---|
14128 | </param>
|
---|
14129 | </method>
|
---|
14130 | </interface>
|
---|
14131 |
|
---|
14132 | <!--
|
---|
14133 | // Events
|
---|
14134 | /////////////////////////////////////////////////////////////////////////
|
---|
14135 | -->
|
---|
14136 | <enum
|
---|
14137 | name="VBoxEventType"
|
---|
14138 | uuid="e085d0b1-05e6-4f40-a709-b7266fbdb236">
|
---|
14139 |
|
---|
14140 | <desc>
|
---|
14141 | Type of an event.
|
---|
14142 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
14143 | </desc>
|
---|
14144 |
|
---|
14145 | <const name="Invalid" value="0">
|
---|
14146 | <desc>
|
---|
14147 | Invalid event, must be first.
|
---|
14148 | </desc>
|
---|
14149 | </const>
|
---|
14150 |
|
---|
14151 | <const name="Any" value="1">
|
---|
14152 | <desc>
|
---|
14153 | Wildcard for all events.
|
---|
14154 | Events of this type are never delivered, and only used in
|
---|
14155 | registerListener() call to simplify registration.
|
---|
14156 | </desc>
|
---|
14157 | </const>
|
---|
14158 |
|
---|
14159 | <const name="Vetoable" value="2">
|
---|
14160 | <desc>
|
---|
14161 | Wildcard for all vetoable events. Events of this type are never delivered, and only
|
---|
14162 | used in registerListener() call to simplify registration.
|
---|
14163 | </desc>
|
---|
14164 | </const>
|
---|
14165 |
|
---|
14166 | <const name="MachineEvent" value="3">
|
---|
14167 | <desc>
|
---|
14168 | Wildcard for all machine events. Events of this type are never delivered, and only used in
|
---|
14169 | registerListener() call to simplify registration.
|
---|
14170 | </desc>
|
---|
14171 | </const>
|
---|
14172 |
|
---|
14173 | <const name="SnapshotEvent" value="4">
|
---|
14174 | <desc>
|
---|
14175 | Wildcard for all snapshot events. Events of this type are never delivered, and only used in
|
---|
14176 | registerListener() call to simplify registration.
|
---|
14177 | </desc>
|
---|
14178 | </const>
|
---|
14179 |
|
---|
14180 | <const name="InputEvent" value="5">
|
---|
14181 | <desc>
|
---|
14182 | Wildcard for all input device (keyboard, mouse) events.
|
---|
14183 | Events of this type are never delivered, and only used in
|
---|
14184 | registerListener() call to simplify registration.
|
---|
14185 | </desc>
|
---|
14186 | </const>
|
---|
14187 |
|
---|
14188 | <const name="LastWildcard" value="31">
|
---|
14189 | <desc>
|
---|
14190 | Last wildcard.
|
---|
14191 | </desc>
|
---|
14192 | </const>
|
---|
14193 |
|
---|
14194 | <const name="OnMachineStateChanged" value="32">
|
---|
14195 | <desc>
|
---|
14196 | See <link to="IMachineStateChangedEvent">IMachineStateChangedEvent</link>.
|
---|
14197 | </desc>
|
---|
14198 | </const>
|
---|
14199 | <const name="OnMachineDataChanged" value="33">
|
---|
14200 | <desc>
|
---|
14201 | See <link to="IMachineDataChangedEvent">IMachineDataChangedEvent</link>.
|
---|
14202 | </desc>
|
---|
14203 | </const>
|
---|
14204 | <const name="OnExtraDataChanged" value="34">
|
---|
14205 | <desc>
|
---|
14206 | See <link to="IExtraDataChangedEvent">IExtraDataChangedEvent</link>.
|
---|
14207 | </desc>
|
---|
14208 | </const>
|
---|
14209 | <const name="OnExtraDataCanChange" value="35">
|
---|
14210 | <desc>
|
---|
14211 | See <link to="IExtraDataCanChangeEvent">IExtraDataCanChangeEvent</link>.
|
---|
14212 | </desc>
|
---|
14213 | </const>
|
---|
14214 | <const name="OnMediumRegistered" value="36">
|
---|
14215 | <desc>
|
---|
14216 | See <link to="IMediumRegisteredEvent">IMediumRegisteredEvent</link>.
|
---|
14217 | </desc>
|
---|
14218 | </const>
|
---|
14219 | <const name="OnMachineRegistered" value="37">
|
---|
14220 | <desc>
|
---|
14221 | See <link to="IMachineRegisteredEvent">IMachineRegisteredEvent</link>.
|
---|
14222 | </desc>
|
---|
14223 | </const>
|
---|
14224 | <const name="OnSessionStateChanged" value="38">
|
---|
14225 | <desc>
|
---|
14226 | See <link to="ISessionStateChangedEvent">ISessionStateChangedEvent</link>.
|
---|
14227 | </desc>
|
---|
14228 | </const>
|
---|
14229 | <const name="OnSnapshotTaken" value="39">
|
---|
14230 | <desc>
|
---|
14231 | See <link to="ISnapshotTakenEvent">ISnapshotTakenEvent</link>.
|
---|
14232 | </desc>
|
---|
14233 | </const>
|
---|
14234 | <const name="OnSnapshotDeleted" value="40">
|
---|
14235 | <desc>
|
---|
14236 | See <link to="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>.
|
---|
14237 | </desc>
|
---|
14238 | </const>
|
---|
14239 | <const name="OnSnapshotChanged" value="41">
|
---|
14240 | <desc>
|
---|
14241 | See <link to="ISnapshotChangedEvent">ISnapshotChangedEvent</link>.
|
---|
14242 | </desc>
|
---|
14243 | </const>
|
---|
14244 | <const name="OnGuestPropertyChanged" value="42">
|
---|
14245 | <desc>
|
---|
14246 | See <link to="IGuestPropertyChangedEvent">IGuestPropertyChangedEvent</link>.
|
---|
14247 | </desc>
|
---|
14248 | </const>
|
---|
14249 | <!-- Console events -->
|
---|
14250 | <const name="OnMousePointerShapeChanged" value="43">
|
---|
14251 | <desc>
|
---|
14252 | See <link to="IMousePointerShapeChangedEvent">IMousePointerShapeChangedEvent</link>.
|
---|
14253 | </desc>
|
---|
14254 | </const>
|
---|
14255 | <const name="OnMouseCapabilityChanged" value="44">
|
---|
14256 | <desc>
|
---|
14257 | See <link to="IMouseCapabilityChangedEvent">IMouseCapabilityChangedEvent</link>.
|
---|
14258 | </desc>
|
---|
14259 | </const>
|
---|
14260 | <const name="OnKeyboardLedsChanged" value="45">
|
---|
14261 | <desc>
|
---|
14262 | See <link to="IKeyboardLedsChangedEvent">IKeyboardLedsChangedEvent</link>.
|
---|
14263 | </desc>
|
---|
14264 | </const>
|
---|
14265 | <const name="OnStateChanged" value="46">
|
---|
14266 | <desc>
|
---|
14267 | See <link to="IStateChangedEvent">IStateChangedEvent</link>.
|
---|
14268 | </desc>
|
---|
14269 | </const>
|
---|
14270 | <const name="OnAdditionsStateChanged" value="47">
|
---|
14271 | <desc>
|
---|
14272 | See <link to="IAdditionsStateChangedEvent">IAdditionsStateChangedEvent</link>.
|
---|
14273 | </desc>
|
---|
14274 | </const>
|
---|
14275 | <const name="OnNetworkAdapterChanged" value="48">
|
---|
14276 | <desc>
|
---|
14277 | See <link to="INetworkAdapterChangedEvent">INetworkAdapterChangedEvent</link>.
|
---|
14278 | </desc>
|
---|
14279 | </const>
|
---|
14280 | <const name="OnSerialPortChanged" value="49">
|
---|
14281 | <desc>
|
---|
14282 | See <link to="ISerialPortChangedEvent">ISerialPortChangedEvent</link>.
|
---|
14283 | </desc>
|
---|
14284 | </const>
|
---|
14285 | <const name="OnParallelPortChanged" value="50">
|
---|
14286 | <desc>
|
---|
14287 | See <link to="IParallelPortChangedEvent">IParallelPortChangedEvent</link>.
|
---|
14288 | </desc>
|
---|
14289 | </const>
|
---|
14290 | <const name="OnStorageControllerChanged" value="51">
|
---|
14291 | <desc>
|
---|
14292 | See <link to="IStorageControllerChangedEvent">IStorageControllerChangedEvent</link>.
|
---|
14293 | </desc>
|
---|
14294 | </const>
|
---|
14295 | <const name="OnMediumChanged" value="52">
|
---|
14296 | <desc>
|
---|
14297 | See <link to="IMediumChangedEvent">IMediumChangedEvent</link>.
|
---|
14298 | </desc>
|
---|
14299 | </const>
|
---|
14300 | <const name="OnVRDEServerChanged" value="53">
|
---|
14301 | <desc>
|
---|
14302 | See <link to="IVRDEServerChangedEvent">IVRDEServerChangedEvent</link>.
|
---|
14303 | </desc>
|
---|
14304 | </const>
|
---|
14305 | <const name="OnUSBControllerChanged" value="54">
|
---|
14306 | <desc>
|
---|
14307 | See <link to="IUSBControllerChangedEvent">IUSBControllerChangedEvent</link>.
|
---|
14308 | </desc>
|
---|
14309 | </const>
|
---|
14310 | <const name="OnUSBDeviceStateChanged" value="55">
|
---|
14311 | <desc>
|
---|
14312 | See <link to="IUSBDeviceStateChangedEvent">IUSBDeviceStateChangedEvent</link>.
|
---|
14313 | </desc>
|
---|
14314 | </const>
|
---|
14315 | <const name="OnSharedFolderChanged" value="56">
|
---|
14316 | <desc>
|
---|
14317 | See <link to="ISharedFolderChangedEvent">ISharedFolderChangedEvent</link>.
|
---|
14318 | </desc>
|
---|
14319 | </const>
|
---|
14320 | <const name="OnRuntimeError" value="57">
|
---|
14321 | <desc>
|
---|
14322 | See <link to="IRuntimeErrorEvent">IRuntimeErrorEvent</link>.
|
---|
14323 | </desc>
|
---|
14324 | </const>
|
---|
14325 | <const name="OnCanShowWindow" value="58">
|
---|
14326 | <desc>
|
---|
14327 | See <link to="ICanShowWindowEvent">ICanShowWindowEvent</link>.
|
---|
14328 | </desc>
|
---|
14329 | </const>
|
---|
14330 | <const name="OnShowWindow" value="59">
|
---|
14331 | <desc>
|
---|
14332 | See <link to="IShowWindowEvent">IShowWindowEvent</link>.
|
---|
14333 | </desc>
|
---|
14334 | </const>
|
---|
14335 | <const name="OnCPUChanged" value="60">
|
---|
14336 | <desc>
|
---|
14337 | See <link to="ICPUChangedEvent">ICPUChangedEvent</link>.
|
---|
14338 | </desc>
|
---|
14339 | </const>
|
---|
14340 | <const name="OnVRDEServerInfoChanged" value="61">
|
---|
14341 | <desc>
|
---|
14342 | See <link to="IVRDEServerInfoChangedEvent">IVRDEServerInfoChangedEvent</link>.
|
---|
14343 | </desc>
|
---|
14344 | </const>
|
---|
14345 | <const name="OnEventSourceChanged" value="62">
|
---|
14346 | <desc>
|
---|
14347 | See <link to="IEventSourceChangedEvent">IEventSourceChangedEvent</link>.
|
---|
14348 | </desc>
|
---|
14349 | </const>
|
---|
14350 | <const name="OnCPUExecutionCapChanged" value="63">
|
---|
14351 | <desc>
|
---|
14352 | See <link to="ICPUExecutionCapChangedEvent">ICPUExecutionCapChangedEvent</link>.
|
---|
14353 | </desc>
|
---|
14354 | </const>
|
---|
14355 | <const name="OnGuestKeyboardEvent" value="64">
|
---|
14356 | <desc>
|
---|
14357 | See <link to="IGuestKeyboardEvent">IGuestKeyboardEvent</link>.
|
---|
14358 | </desc>
|
---|
14359 | </const>
|
---|
14360 | <const name="OnGuestMouseEvent" value="65">
|
---|
14361 | <desc>
|
---|
14362 | See <link to="IGuestMouseEvent">IGuestMouseEvent</link>.
|
---|
14363 | </desc>
|
---|
14364 | </const>
|
---|
14365 | <!-- Last event marker -->
|
---|
14366 | <const name="Last" value="66">
|
---|
14367 | <desc>
|
---|
14368 | Must be last event, used for iterations and structures relying on numerical event values.
|
---|
14369 | </desc>
|
---|
14370 | </const>
|
---|
14371 |
|
---|
14372 | </enum>
|
---|
14373 |
|
---|
14374 | <interface
|
---|
14375 | name="IEventSource" extends="$unknown"
|
---|
14376 | uuid="9b6e1aee-35f3-4f4d-b5bb-ed0ecefd8538"
|
---|
14377 | wsmap="managed"
|
---|
14378 | >
|
---|
14379 | <desc>
|
---|
14380 | Event source. Generally, any object which could generate events can be an event source,
|
---|
14381 | or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S),
|
---|
14382 | an event source can work with listeners in either active or passive mode. In active mode it is up to
|
---|
14383 | the IEventSource implementation to call <link to="IEventListener::handleEvent" />, in passive mode the
|
---|
14384 | event source keeps track of pending events for each listener and returns available events on demand.
|
---|
14385 |
|
---|
14386 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
14387 | </desc>
|
---|
14388 |
|
---|
14389 | <method name="createListener">
|
---|
14390 | <desc>
|
---|
14391 | Creates a new listener object, useful for passive mode.
|
---|
14392 | </desc>
|
---|
14393 | <param name="listener" type="IEventListener" dir="return"/>
|
---|
14394 | </method>
|
---|
14395 |
|
---|
14396 | <method name="createAggregator">
|
---|
14397 | <desc>
|
---|
14398 | Creates a aggregator event source, collecting events from multiple sources.
|
---|
14399 | This way single listener can listen for events coming from multiple sources,
|
---|
14400 | using single blocking getEvent() of this aggregator.
|
---|
14401 | </desc>
|
---|
14402 | <param name="subordinates" type="IEventSource" dir="in" safearray="yes">
|
---|
14403 | <desc>
|
---|
14404 | Subordinate event source this one aggregatres.
|
---|
14405 | </desc>
|
---|
14406 | </param>
|
---|
14407 | <param name="result" type="IEventSource" dir="return"/>
|
---|
14408 | </method>
|
---|
14409 |
|
---|
14410 | <method name="registerListener">
|
---|
14411 | <desc>
|
---|
14412 | Register an event listener.
|
---|
14413 |
|
---|
14414 | <note>
|
---|
14415 | To avoid system overload, the VirtualBox server process checks if passive event
|
---|
14416 | listeners call <link to="IEventSource::getEvent"/> frequently enough. In the
|
---|
14417 | current implementation, if more than 500 pending events are detected for a passive
|
---|
14418 | event listener, it is forcefully unregistered by the system, and further
|
---|
14419 | <link to="#getEvent" /> calls will return @c VBOX_E_OBJECT_NOT_FOUND.
|
---|
14420 | </note>
|
---|
14421 | </desc>
|
---|
14422 | <param name="listener" type="IEventListener" dir="in">
|
---|
14423 | <desc>Listener to register.</desc>
|
---|
14424 | </param>
|
---|
14425 | <param name="interesting" type="VBoxEventType" dir="in" safearray="yes">
|
---|
14426 | <desc>
|
---|
14427 | Event types listener is interested in. One can use wildcards like -
|
---|
14428 | <link to="VBoxEventType_Any"/> to specify wildcards, matching more
|
---|
14429 | than one event.
|
---|
14430 | </desc>
|
---|
14431 | </param>
|
---|
14432 | <param name="active" type="boolean" dir="in">
|
---|
14433 | <desc>
|
---|
14434 | Which mode this listener is operating in.
|
---|
14435 | In active mode, <link to="IEventListener::handleEvent" /> is called directly.
|
---|
14436 | In passive mode, an internal event queue is created for this this IEventListener.
|
---|
14437 | For each event coming in, it is added to queues for all interested registered passive
|
---|
14438 | listeners. It is then up to the external code to call the listener's
|
---|
14439 | <link to="IEventListener::handleEvent" /> method. When done with an event, the
|
---|
14440 | external code must call <link to="#eventProcessed" />.
|
---|
14441 | </desc>
|
---|
14442 | </param>
|
---|
14443 | </method>
|
---|
14444 |
|
---|
14445 | <method name="unregisterListener">
|
---|
14446 | <desc>
|
---|
14447 | Unregister an event listener. If listener is passive, and some waitable events are still
|
---|
14448 | in queue they are marked as processed automatically.
|
---|
14449 | </desc>
|
---|
14450 | <param name="listener" type="IEventListener" dir="in">
|
---|
14451 | <desc>Listener to unregister.</desc>
|
---|
14452 | </param>
|
---|
14453 | </method>
|
---|
14454 |
|
---|
14455 | <method name="fireEvent">
|
---|
14456 | <desc>
|
---|
14457 | Fire an event for this source.
|
---|
14458 | </desc>
|
---|
14459 | <param name="event" type="IEvent" dir="in">
|
---|
14460 | <desc>Event to deliver.</desc>
|
---|
14461 | </param>
|
---|
14462 | <param name="timeout" type="long" dir="in">
|
---|
14463 | <desc>
|
---|
14464 | Maximum time to wait for event processing (if event is waitable), in ms;
|
---|
14465 | 0 = no wait, -1 = indefinite wait.
|
---|
14466 | </desc>
|
---|
14467 | </param>
|
---|
14468 | <param name="result" type="boolean" dir="return">
|
---|
14469 | <desc>true if an event was delivered to all targets, or is non-waitable.</desc>
|
---|
14470 | </param>
|
---|
14471 | </method>
|
---|
14472 |
|
---|
14473 | <method name="getEvent">
|
---|
14474 | <desc>
|
---|
14475 | Get events from this peer's event queue (for passive mode). Calling this method
|
---|
14476 | regularly is required for passive event listeners to avoid system overload;
|
---|
14477 | see <link to="IEventSource::registerListener" /> for details.
|
---|
14478 |
|
---|
14479 | <result name="VBOX_E_OBJECT_NOT_FOUND">
|
---|
14480 | Listener is not registered, or autounregistered.
|
---|
14481 | </result>
|
---|
14482 | </desc>
|
---|
14483 | <param name="listener" type="IEventListener" dir="in">
|
---|
14484 | <desc>Which listener to get data for.</desc>
|
---|
14485 | </param>
|
---|
14486 | <param name="timeout" type="long" dir="in">
|
---|
14487 | <desc>
|
---|
14488 | Maximum time to wait for events, in ms;
|
---|
14489 | 0 = no wait, -1 = indefinite wait.
|
---|
14490 | </desc>
|
---|
14491 | </param>
|
---|
14492 | <param name="event" type="IEvent" dir="return">
|
---|
14493 | <desc>Event retrieved, or null if none available.</desc>
|
---|
14494 | </param>
|
---|
14495 | </method>
|
---|
14496 |
|
---|
14497 | <method name="eventProcessed">
|
---|
14498 | <desc>
|
---|
14499 | Must be called for waitable events after a particular listener finished its
|
---|
14500 | event processing. When all listeners of a particular event have called this
|
---|
14501 | method, the system will then call <link to="IEvent::setProcessed" />.
|
---|
14502 | </desc>
|
---|
14503 | <param name="listener" type="IEventListener" dir="in">
|
---|
14504 | <desc>Which listener processed event.</desc>
|
---|
14505 | </param>
|
---|
14506 | <param name="event" type="IEvent" dir="in">
|
---|
14507 | <desc>Which event.</desc>
|
---|
14508 | </param>
|
---|
14509 | </method>
|
---|
14510 |
|
---|
14511 | </interface>
|
---|
14512 |
|
---|
14513 | <interface
|
---|
14514 | name="IEventListener" extends="$unknown"
|
---|
14515 | uuid="67099191-32e7-4f6c-85ee-422304c71b90"
|
---|
14516 | wsmap="managed"
|
---|
14517 | >
|
---|
14518 | <desc>
|
---|
14519 | Event listener. An event listener can work in either active or passive mode, depending on the way
|
---|
14520 | it was registered.
|
---|
14521 | See <link to="IEvent" /> for an introduction to VirtualBox event handling.
|
---|
14522 | </desc>
|
---|
14523 |
|
---|
14524 | <method name="handleEvent">
|
---|
14525 | <desc>
|
---|
14526 | Handle event callback (called directly by IEventSource in active mode, or could be
|
---|
14527 | called by event processor thread in passive mode).
|
---|
14528 | </desc>
|
---|
14529 | <param name="event" type="IEvent" dir="in">
|
---|
14530 | <desc>Event available.</desc>
|
---|
14531 | </param>
|
---|
14532 | </method>
|
---|
14533 |
|
---|
14534 | </interface>
|
---|
14535 |
|
---|
14536 | <interface
|
---|
14537 | name="IEvent" extends="$unknown"
|
---|
14538 | uuid="0ca2adba-8f30-401b-a8cd-fe31dbe839c0"
|
---|
14539 | wsmap="managed"
|
---|
14540 | >
|
---|
14541 | <desc>
|
---|
14542 | Abstract parent interface for VirtualBox events. Actual events will typically implement
|
---|
14543 | a more specific interface which derives from this (see below).
|
---|
14544 |
|
---|
14545 | <b>Introduction to VirtualBox events</b>
|
---|
14546 |
|
---|
14547 | Generally speaking, an event (represented by this interface) signals that something
|
---|
14548 | happened, while an event listener (see <link to="IEventListener" />) represents an
|
---|
14549 | entity that is interested in certain events. In order for this to work with
|
---|
14550 | unidirectional protocols (i.e. web services), the concepts of passive and active
|
---|
14551 | listener are used.
|
---|
14552 |
|
---|
14553 | Event consumers can register themselves as listeners, providing an array of
|
---|
14554 | events they are interested in (see <link to="IEventSource::registerListener" />).
|
---|
14555 | When an event triggers, the listener is notified about the event. The exact
|
---|
14556 | mechanism of the notification depends on whether the listener was registered as
|
---|
14557 | an active or passive listener:
|
---|
14558 |
|
---|
14559 | <ul>
|
---|
14560 | <li>An active listener is very similar to a callback: it is a function invoked
|
---|
14561 | by the API. As opposed to the callbacks that were used in the API before
|
---|
14562 | VirtualBox 4.0 however, events are now objects with an interface hierarchy.
|
---|
14563 | </li>
|
---|
14564 |
|
---|
14565 | <li>Passive listeners are somewhat trickier to implement, but do not require
|
---|
14566 | a client function to be callable, which is not an option with scripting
|
---|
14567 | languages or web service clients. Internally the <link to="IEventSource" />
|
---|
14568 | implementation maintains an event queue for each passive listener, and
|
---|
14569 | newly arrived events are put in this queue. When the listener calls
|
---|
14570 | <link to="IEventSource::getEvent"/>, first element from its internal event
|
---|
14571 | queue is returned. When the client completes processing of an event,
|
---|
14572 | the <link to="IEventSource::eventProcessed" /> function must be called,
|
---|
14573 | acknowledging that the event was processed. It supports implementing
|
---|
14574 | waitable events. On passive listener unregistration, all events from its
|
---|
14575 | queue are auto-acknowledged.
|
---|
14576 | </li>
|
---|
14577 | </ul>
|
---|
14578 |
|
---|
14579 | Waitable events are useful in situations where the event generator wants to track
|
---|
14580 | delivery or a party wants to wait until all listeners have completed the event. A
|
---|
14581 | typical example would be a vetoable event (see <link to="IVetoEvent" />) where a
|
---|
14582 | listeners might veto a certain action, and thus the event producer has to make
|
---|
14583 | sure that all listeners have processed the event and not vetoed before taking
|
---|
14584 | the action.
|
---|
14585 |
|
---|
14586 | A given event may have both passive and active listeners at the same time.
|
---|
14587 |
|
---|
14588 | <b>Using events</b>
|
---|
14589 |
|
---|
14590 | Any VirtualBox object capable of producing externally visible events provides an
|
---|
14591 | @c eventSource read-only attribute, which is of the type <link to="IEventSource" />.
|
---|
14592 | This event source object is notified by VirtualBox once something has happened, so
|
---|
14593 | consumers may register event listeners with this event source. To register a listener,
|
---|
14594 | an object implementing the <link to="IEventListener" /> interface must be provided.
|
---|
14595 | For active listeners, such an object is typically created by the consumer, while for
|
---|
14596 | passive listeners <link to="IEventSource::createListener" /> should be used. Please
|
---|
14597 | note that a listener created with @c createListener() must not be used as an active listener.
|
---|
14598 |
|
---|
14599 | Once created, the listener must be registered to listen for the desired events
|
---|
14600 | (see <link to="IEventSource::registerListener" />), providing an array of
|
---|
14601 | <link to="VBoxEventType" /> enums. Those elements can either be the individual
|
---|
14602 | event IDs or wildcards matching multiple event IDs.
|
---|
14603 |
|
---|
14604 | After registration, the callback's <link to="IEventListener::handleEvent" /> method is
|
---|
14605 | called automatically when the event is triggered, while passive listeners have to call
|
---|
14606 | <link to="IEventSource::getEvent" /> and <link to="IEventSource::eventProcessed" /> in
|
---|
14607 | an event processing loop.
|
---|
14608 |
|
---|
14609 | The IEvent interface is an abstract parent interface for all such VirtualBox events
|
---|
14610 | coming in. As a result, the standard use pattern inside <link to="IEventListener::handleEvent" />
|
---|
14611 | or the event processing loop is to check the <link to="#type" /> attribute of the event and
|
---|
14612 | then cast to the appropriate specific interface using @c QueryInterface().
|
---|
14613 | </desc>
|
---|
14614 |
|
---|
14615 | <attribute name="type" readonly="yes" type="VBoxEventType">
|
---|
14616 | <desc>
|
---|
14617 | Event type.
|
---|
14618 | </desc>
|
---|
14619 | </attribute>
|
---|
14620 |
|
---|
14621 | <attribute name="source" readonly="yes" type="IEventSource">
|
---|
14622 | <desc>
|
---|
14623 | Source of this event.
|
---|
14624 | </desc>
|
---|
14625 | </attribute>
|
---|
14626 |
|
---|
14627 | <attribute name="waitable" readonly="yes" type="boolean">
|
---|
14628 | <desc>
|
---|
14629 | If we can wait for this event being processed. If false, waitProcessed() returns immediately,
|
---|
14630 | and setProcessed() doesn't make sense. Non-waitable events are generally better performing,
|
---|
14631 | as no additional overhead associated with waitability imposed.
|
---|
14632 | Waitable events are needed when one need to be able to wait for particular event processed,
|
---|
14633 | for example for vetoable changes, or if event refers to some resource which need to be kept immutable
|
---|
14634 | until all consumers confirmed events.
|
---|
14635 | </desc>
|
---|
14636 | </attribute>
|
---|
14637 |
|
---|
14638 | <method name="setProcessed">
|
---|
14639 | <desc>
|
---|
14640 | Internal method called by the system when all listeners of a particular event have called
|
---|
14641 | <link to="IEventSource::eventProcessed" />. This should not be called by client code.
|
---|
14642 | </desc>
|
---|
14643 | </method>
|
---|
14644 |
|
---|
14645 | <method name="waitProcessed">
|
---|
14646 | <desc>
|
---|
14647 | Wait until time outs, or this event is processed. Event must be waitable for this operation to have
|
---|
14648 | described semantics, for non-waitable returns true immediately.
|
---|
14649 | </desc>
|
---|
14650 | <param name="timeout" type="long" dir="in">
|
---|
14651 | <desc>
|
---|
14652 | Maximum time to wait for event processeing, in ms;
|
---|
14653 | 0 = no wait, -1 = indefinite wait.
|
---|
14654 | </desc>
|
---|
14655 | </param>
|
---|
14656 | <param name="result" type="boolean" dir="return">
|
---|
14657 | <desc>If this event was processed before timeout.</desc>
|
---|
14658 | </param>
|
---|
14659 | </method>
|
---|
14660 | </interface>
|
---|
14661 |
|
---|
14662 |
|
---|
14663 | <interface
|
---|
14664 | name="IReusableEvent" extends="IEvent"
|
---|
14665 | uuid="69bfb134-80f6-4266-8e20-16371f68fa25"
|
---|
14666 | wsmap="managed"
|
---|
14667 | >
|
---|
14668 | <desc>Base abstract interface for all reusable events.</desc>
|
---|
14669 |
|
---|
14670 | <attribute name="generation" readonly="yes" type="unsigned long">
|
---|
14671 | <desc>Current generation of event, incremented on reuse.</desc>
|
---|
14672 | </attribute>
|
---|
14673 |
|
---|
14674 | <method name="reuse">
|
---|
14675 | <desc>
|
---|
14676 | Marks an event as reused, increments 'generation', fields shall no
|
---|
14677 | longer be considered valid.
|
---|
14678 | </desc>
|
---|
14679 | </method>
|
---|
14680 | </interface>
|
---|
14681 |
|
---|
14682 | <interface
|
---|
14683 | name="IMachineEvent" extends="IEvent"
|
---|
14684 | uuid="92ed7b1a-0d96-40ed-ae46-a564d484325e"
|
---|
14685 | wsmap="managed" id="MachineEvent"
|
---|
14686 | >
|
---|
14687 | <desc>Base abstract interface for all machine events.</desc>
|
---|
14688 |
|
---|
14689 | <attribute name="machineId" readonly="yes" type="uuid" mod="string">
|
---|
14690 | <desc>ID of the machine this event relates to.</desc>
|
---|
14691 | </attribute>
|
---|
14692 |
|
---|
14693 | </interface>
|
---|
14694 |
|
---|
14695 | <interface
|
---|
14696 | name="IMachineStateChangedEvent" extends="IMachineEvent"
|
---|
14697 | uuid="5748F794-48DF-438D-85EB-98FFD70D18C9"
|
---|
14698 | wsmap="managed" autogen="VBoxEvent" id="OnMachineStateChanged"
|
---|
14699 | >
|
---|
14700 | <desc>Machine state change event.</desc>
|
---|
14701 |
|
---|
14702 | <attribute name="state" readonly="yes" type="MachineState">
|
---|
14703 | <desc>New execution state.</desc>
|
---|
14704 | </attribute>
|
---|
14705 | </interface>
|
---|
14706 |
|
---|
14707 | <interface
|
---|
14708 | name="IMachineDataChangedEvent" extends="IMachineEvent"
|
---|
14709 | uuid="6AA70A6C-0DCA-4810-8C5C-457B278E3D49"
|
---|
14710 | wsmap="managed" autogen="VBoxEvent" id="OnMachineDataChanged"
|
---|
14711 | >
|
---|
14712 | <desc>
|
---|
14713 | Any of the settings of the given machine has changed.
|
---|
14714 | </desc>
|
---|
14715 | </interface>
|
---|
14716 |
|
---|
14717 | <interface
|
---|
14718 | name="IMediumRegisteredEvent" extends="IEvent"
|
---|
14719 | uuid="53fac49a-b7f1-4a5a-a4ef-a11dd9c2a458"
|
---|
14720 | wsmap="managed" autogen="VBoxEvent" id="OnMediumRegistered"
|
---|
14721 | >
|
---|
14722 | <desc>
|
---|
14723 | The given medium was registered or unregistered
|
---|
14724 | within this VirtualBox installation.
|
---|
14725 | </desc>
|
---|
14726 |
|
---|
14727 | <attribute name="mediumId" readonly="yes" type="uuid" mod="string">
|
---|
14728 | <desc>ID of the medium this event relates to.</desc>
|
---|
14729 | </attribute>
|
---|
14730 |
|
---|
14731 | <attribute name="mediumType" readonly="yes" type="DeviceType">
|
---|
14732 | <desc>Type of the medium this event relates to.</desc>
|
---|
14733 | </attribute>
|
---|
14734 |
|
---|
14735 | <attribute name="registered" type="boolean" readonly="yes">
|
---|
14736 | <desc>
|
---|
14737 | If @c true, the medium was registered, otherwise it was
|
---|
14738 | unregistered.
|
---|
14739 | </desc>
|
---|
14740 | </attribute>
|
---|
14741 | </interface>
|
---|
14742 |
|
---|
14743 | <interface
|
---|
14744 | name="IMachineRegisteredEvent" extends="IMachineEvent"
|
---|
14745 | uuid="c354a762-3ff2-4f2e-8f09-07382ee25088"
|
---|
14746 | wsmap="managed" autogen="VBoxEvent" id="OnMachineRegistered"
|
---|
14747 | >
|
---|
14748 | <desc>
|
---|
14749 | The given machine was registered or unregistered
|
---|
14750 | within this VirtualBox installation.
|
---|
14751 | </desc>
|
---|
14752 |
|
---|
14753 | <attribute name="registered" type="boolean" readonly="yes">
|
---|
14754 | <desc>
|
---|
14755 | If @c true, the machine was registered, otherwise it was
|
---|
14756 | unregistered.
|
---|
14757 | </desc>
|
---|
14758 | </attribute>
|
---|
14759 | </interface>
|
---|
14760 |
|
---|
14761 | <interface
|
---|
14762 | name="ISessionStateChangedEvent" extends="IMachineEvent"
|
---|
14763 | uuid="714a3eef-799a-4489-86cd-fe8e45b2ff8e"
|
---|
14764 | wsmap="managed" autogen="VBoxEvent" id="OnSessionStateChanged"
|
---|
14765 | >
|
---|
14766 | <desc>
|
---|
14767 | The state of the session for the given machine was changed.
|
---|
14768 | <see>IMachine::sessionState</see>
|
---|
14769 | </desc>
|
---|
14770 |
|
---|
14771 | <attribute name="state" type="SessionState" readonly="yes">
|
---|
14772 | <desc>
|
---|
14773 | New session state.
|
---|
14774 | </desc>
|
---|
14775 | </attribute>
|
---|
14776 | </interface>
|
---|
14777 |
|
---|
14778 | <interface
|
---|
14779 | name="IGuestPropertyChangedEvent" extends="IMachineEvent"
|
---|
14780 | uuid="3f63597a-26f1-4edb-8dd2-6bddd0912368"
|
---|
14781 | wsmap="managed" autogen="VBoxEvent" id="OnGuestPropertyChanged"
|
---|
14782 | >
|
---|
14783 | <desc>
|
---|
14784 | Notification when a guest property has changed.
|
---|
14785 | </desc>
|
---|
14786 |
|
---|
14787 | <attribute name="name" readonly="yes" type="wstring">
|
---|
14788 | <desc>
|
---|
14789 | The name of the property that has changed.
|
---|
14790 | </desc>
|
---|
14791 | </attribute>
|
---|
14792 |
|
---|
14793 | <attribute name="value" readonly="yes" type="wstring">
|
---|
14794 | <desc>
|
---|
14795 | The new property value.
|
---|
14796 | </desc>
|
---|
14797 | </attribute>
|
---|
14798 |
|
---|
14799 | <attribute name="flags" readonly="yes" type="wstring">
|
---|
14800 | <desc>
|
---|
14801 | The new property flags.
|
---|
14802 | </desc>
|
---|
14803 | </attribute>
|
---|
14804 |
|
---|
14805 | </interface>
|
---|
14806 |
|
---|
14807 | <interface
|
---|
14808 | name="ISnapshotEvent" extends="IMachineEvent"
|
---|
14809 | uuid="21637b0e-34b8-42d3-acfb-7e96daf77c22"
|
---|
14810 | wsmap="managed" id="SnapshotEvent"
|
---|
14811 | >
|
---|
14812 | <desc>Base interface for all snapshot events.</desc>
|
---|
14813 |
|
---|
14814 | <attribute name="snapshotId" readonly="yes" type="uuid" mod="string">
|
---|
14815 | <desc>ID of the snapshot this event relates to.</desc>
|
---|
14816 | </attribute>
|
---|
14817 |
|
---|
14818 | </interface>
|
---|
14819 |
|
---|
14820 | <interface
|
---|
14821 | name="ISnapshotTakenEvent" extends="ISnapshotEvent"
|
---|
14822 | uuid="d27c0b3d-6038-422c-b45e-6d4a0503d9f1"
|
---|
14823 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotTaken"
|
---|
14824 | >
|
---|
14825 | <desc>
|
---|
14826 | A new snapshot of the machine has been taken.
|
---|
14827 | <see>ISnapshot</see>
|
---|
14828 | </desc>
|
---|
14829 | </interface>
|
---|
14830 |
|
---|
14831 | <interface
|
---|
14832 | name="ISnapshotDeletedEvent" extends="ISnapshotEvent"
|
---|
14833 | uuid="c48f3401-4a9e-43f4-b7a7-54bd285e22f4"
|
---|
14834 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotDeleted"
|
---|
14835 | >
|
---|
14836 | <desc>
|
---|
14837 | Snapshot of the given machine has been deleted.
|
---|
14838 |
|
---|
14839 | <note>
|
---|
14840 | This notification is delivered <b>after</b> the snapshot
|
---|
14841 | object has been uninitialized on the server (so that any
|
---|
14842 | attempt to call its methods will return an error).
|
---|
14843 | </note>
|
---|
14844 |
|
---|
14845 | <see>ISnapshot</see>
|
---|
14846 | </desc>
|
---|
14847 | </interface>
|
---|
14848 |
|
---|
14849 | <interface
|
---|
14850 | name="ISnapshotChangedEvent" extends="ISnapshotEvent"
|
---|
14851 | uuid="07541941-8079-447a-a33e-47a69c7980db"
|
---|
14852 | wsmap="managed" autogen="VBoxEvent" id="OnSnapshotChanged"
|
---|
14853 | >
|
---|
14854 | <desc>
|
---|
14855 | Snapshot properties (name and/or description) have been changed.
|
---|
14856 | <see>ISnapshot</see>
|
---|
14857 | </desc>
|
---|
14858 | </interface>
|
---|
14859 |
|
---|
14860 | <interface
|
---|
14861 | name="IMousePointerShapeChangedEvent" extends="IEvent"
|
---|
14862 | uuid="a6dcf6e8-416b-4181-8c4a-45ec95177aef"
|
---|
14863 | wsmap="managed" autogen="VBoxEvent" id="OnMousePointerShapeChanged"
|
---|
14864 | >
|
---|
14865 | <desc>
|
---|
14866 | Notification when the guest mouse pointer shape has
|
---|
14867 | changed. The new shape data is given.
|
---|
14868 | </desc>
|
---|
14869 |
|
---|
14870 | <attribute name="visible" type="boolean" readonly="yes">
|
---|
14871 | <desc>
|
---|
14872 | Flag whether the pointer is visible.
|
---|
14873 | </desc>
|
---|
14874 | </attribute>
|
---|
14875 | <attribute name="alpha" type="boolean" readonly="yes">
|
---|
14876 | <desc>
|
---|
14877 | Flag whether the pointer has an alpha channel.
|
---|
14878 | </desc>
|
---|
14879 | </attribute>
|
---|
14880 | <attribute name="xhot" type="unsigned long" readonly="yes">
|
---|
14881 | <desc>
|
---|
14882 | The pointer hot spot X coordinate.
|
---|
14883 | </desc>
|
---|
14884 | </attribute>
|
---|
14885 | <attribute name="yhot" type="unsigned long" readonly="yes">
|
---|
14886 | <desc>
|
---|
14887 | The pointer hot spot Y coordinate.
|
---|
14888 | </desc>
|
---|
14889 | </attribute>
|
---|
14890 | <attribute name="width" type="unsigned long" readonly="yes">
|
---|
14891 | <desc>
|
---|
14892 | Width of the pointer shape in pixels.
|
---|
14893 | </desc>
|
---|
14894 | </attribute>
|
---|
14895 | <attribute name="height" type="unsigned long" readonly="yes">
|
---|
14896 | <desc>
|
---|
14897 | Height of the pointer shape in pixels.
|
---|
14898 | </desc>
|
---|
14899 | </attribute>
|
---|
14900 | <attribute name="shape" type="octet" safearray="yes" readonly="yes">
|
---|
14901 | <desc>
|
---|
14902 | Shape buffer arrays.
|
---|
14903 |
|
---|
14904 | The @a shape buffer contains a 1-bpp (bits per pixel) AND mask
|
---|
14905 | followed by a 32-bpp XOR (color) mask.
|
---|
14906 |
|
---|
14907 | For pointers without alpha channel the XOR mask pixels are 32
|
---|
14908 | bit values: (lsb)BGR0(msb). For pointers with alpha channel
|
---|
14909 | the XOR mask consists of (lsb)BGRA(msb) 32 bit values.
|
---|
14910 |
|
---|
14911 | An AND mask is used for pointers with alpha channel, so if the
|
---|
14912 | callback does not support alpha, the pointer could be
|
---|
14913 | displayed as a normal color pointer.
|
---|
14914 |
|
---|
14915 | The AND mask is a 1-bpp bitmap with byte aligned scanlines. The
|
---|
14916 | size of the AND mask therefore is <tt>cbAnd = (width + 7) / 8 *
|
---|
14917 | height</tt>. The padding bits at the end of each scanline are
|
---|
14918 | undefined.
|
---|
14919 |
|
---|
14920 | The XOR mask follows the AND mask on the next 4-byte aligned
|
---|
14921 | offset: <tt>uint8_t *pXor = pAnd + (cbAnd + 3) & ~3</tt>.
|
---|
14922 | Bytes in the gap between the AND and the XOR mask are undefined.
|
---|
14923 | The XOR mask scanlines have no gap between them and the size of
|
---|
14924 | the XOR mask is: <tt>cXor = width * 4 * height</tt>.
|
---|
14925 |
|
---|
14926 | <note>
|
---|
14927 | If @a shape is 0, only the pointer visibility is changed.
|
---|
14928 | </note>
|
---|
14929 | </desc>
|
---|
14930 | </attribute>
|
---|
14931 | </interface>
|
---|
14932 |
|
---|
14933 | <interface
|
---|
14934 | name="IMouseCapabilityChangedEvent" extends="IEvent"
|
---|
14935 | uuid="d633ad48-820c-4207-b46c-6bd3596640d5"
|
---|
14936 | wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged"
|
---|
14937 | >
|
---|
14938 | <desc>
|
---|
14939 | Notification when the mouse capabilities reported by the
|
---|
14940 | guest have changed. The new capabilities are passed.
|
---|
14941 | </desc>
|
---|
14942 | <attribute name="supportsAbsolute" type="boolean" readonly="yes">
|
---|
14943 | <desc>
|
---|
14944 | Supports absolute coordinates.
|
---|
14945 | </desc>
|
---|
14946 | </attribute>
|
---|
14947 | <attribute name="supportsRelative" type="boolean" readonly="yes">
|
---|
14948 | <desc>
|
---|
14949 | Supports relative coordinates.
|
---|
14950 | </desc>
|
---|
14951 | </attribute>
|
---|
14952 | <attribute name="needsHostCursor" type="boolean" readonly="yes">
|
---|
14953 | <desc>
|
---|
14954 | If host cursor is needed.
|
---|
14955 | </desc>
|
---|
14956 | </attribute>
|
---|
14957 | </interface>
|
---|
14958 |
|
---|
14959 | <interface
|
---|
14960 | name="IKeyboardLedsChangedEvent" extends="IEvent"
|
---|
14961 | uuid="6DDEF35E-4737-457B-99FC-BC52C851A44F"
|
---|
14962 | wsmap="managed" autogen="VBoxEvent" id="OnKeyboardLedsChanged"
|
---|
14963 | >
|
---|
14964 | <desc>
|
---|
14965 | Notification when the guest OS executes the KBD_CMD_SET_LEDS command
|
---|
14966 | to alter the state of the keyboard LEDs.
|
---|
14967 | </desc>
|
---|
14968 | <attribute name="numLock" type="boolean" readonly="yes">
|
---|
14969 | <desc>
|
---|
14970 | NumLock status.
|
---|
14971 | </desc>
|
---|
14972 | </attribute>
|
---|
14973 | <attribute name="capsLock" type="boolean" readonly="yes">
|
---|
14974 | <desc>
|
---|
14975 | CapsLock status.
|
---|
14976 | </desc>
|
---|
14977 | </attribute>
|
---|
14978 | <attribute name="scrollLock" type="boolean" readonly="yes">
|
---|
14979 | <desc>
|
---|
14980 | ScrollLock status.
|
---|
14981 | </desc>
|
---|
14982 | </attribute>
|
---|
14983 | </interface>
|
---|
14984 |
|
---|
14985 | <interface
|
---|
14986 | name="IStateChangedEvent" extends="IEvent"
|
---|
14987 | uuid="4376693C-CF37-453B-9289-3B0F521CAF27"
|
---|
14988 | wsmap="managed" autogen="VBoxEvent" id="OnStateChanged"
|
---|
14989 | >
|
---|
14990 | <desc>
|
---|
14991 | Notification when the execution state of the machine has changed.
|
---|
14992 | The new state is given.
|
---|
14993 | </desc>
|
---|
14994 | <attribute name="state" type="MachineState" readonly="yes">
|
---|
14995 | <desc>
|
---|
14996 | New machine state.
|
---|
14997 | </desc>
|
---|
14998 | </attribute>
|
---|
14999 | </interface>
|
---|
15000 |
|
---|
15001 | <interface
|
---|
15002 | name="IAdditionsStateChangedEvent" extends="IEvent"
|
---|
15003 | uuid="D70F7915-DA7C-44C8-A7AC-9F173490446A"
|
---|
15004 | wsmap="managed" autogen="VBoxEvent" id="OnAdditionsStateChanged"
|
---|
15005 | >
|
---|
15006 | <desc>
|
---|
15007 | Notification when a Guest Additions property changes.
|
---|
15008 | Interested callees should query IGuest attributes to
|
---|
15009 | find out what has changed.
|
---|
15010 | </desc>
|
---|
15011 | </interface>
|
---|
15012 |
|
---|
15013 | <interface
|
---|
15014 | name="INetworkAdapterChangedEvent" extends="IEvent"
|
---|
15015 | uuid="08889892-1EC6-4883-801D-77F56CFD0103"
|
---|
15016 | wsmap="managed" autogen="VBoxEvent" id="OnNetworkAdapterChanged"
|
---|
15017 | >
|
---|
15018 | <desc>
|
---|
15019 | Notification when a property of one of the
|
---|
15020 | virtual <link to="IMachine::getNetworkAdapter">network adapters</link>
|
---|
15021 | changes. Interested callees should use INetworkAdapter methods and
|
---|
15022 | attributes to find out what has changed.
|
---|
15023 | </desc>
|
---|
15024 | <attribute name="networkAdapter" type="INetworkAdapter" readonly="yes">
|
---|
15025 | <desc>
|
---|
15026 | Network adapter that is subject to change.
|
---|
15027 | </desc>
|
---|
15028 | </attribute>
|
---|
15029 | </interface>
|
---|
15030 |
|
---|
15031 | <interface
|
---|
15032 | name="ISerialPortChangedEvent" extends="IEvent"
|
---|
15033 | uuid="3BA329DC-659C-488B-835C-4ECA7AE71C6C"
|
---|
15034 | wsmap="managed" autogen="VBoxEvent" id="OnSerialPortChanged"
|
---|
15035 | >
|
---|
15036 | <desc>
|
---|
15037 | Notification when a property of one of the
|
---|
15038 | virtual <link to="IMachine::getSerialPort">serial ports</link> changes.
|
---|
15039 | Interested callees should use ISerialPort methods and attributes
|
---|
15040 | to find out what has changed.
|
---|
15041 | </desc>
|
---|
15042 | <attribute name="serialPort" type="ISerialPort" readonly="yes">
|
---|
15043 | <desc>
|
---|
15044 | Serial port that is subject to change.
|
---|
15045 | </desc>
|
---|
15046 | </attribute>
|
---|
15047 | </interface>
|
---|
15048 |
|
---|
15049 | <interface
|
---|
15050 | name="IParallelPortChangedEvent" extends="IEvent"
|
---|
15051 | uuid="813C99FC-9849-4F47-813E-24A75DC85615"
|
---|
15052 | wsmap="managed" autogen="VBoxEvent" id="OnParallelPortChanged"
|
---|
15053 | >
|
---|
15054 | <desc>
|
---|
15055 | Notification when a property of one of the
|
---|
15056 | virtual <link to="IMachine::getParallelPort">parallel ports</link>
|
---|
15057 | changes. Interested callees should use ISerialPort methods and
|
---|
15058 | attributes to find out what has changed.
|
---|
15059 | </desc>
|
---|
15060 | <attribute name="parallelPort" type="IParallelPort" readonly="yes">
|
---|
15061 | <desc>
|
---|
15062 | Parallel port that is subject to change.
|
---|
15063 | </desc>
|
---|
15064 | </attribute>
|
---|
15065 | </interface>
|
---|
15066 |
|
---|
15067 | <interface
|
---|
15068 | name="IStorageControllerChangedEvent" extends="IEvent"
|
---|
15069 | uuid="715212BF-DA59-426E-8230-3831FAA52C56"
|
---|
15070 | wsmap="managed" autogen="VBoxEvent" id="OnStorageControllerChanged"
|
---|
15071 | >
|
---|
15072 | <desc>
|
---|
15073 | Notification when a
|
---|
15074 | <link to="IMachine::mediumAttachments">medium attachment</link>
|
---|
15075 | changes.
|
---|
15076 | </desc>
|
---|
15077 | </interface>
|
---|
15078 |
|
---|
15079 | <interface
|
---|
15080 | name="IMediumChangedEvent" extends="IEvent"
|
---|
15081 | uuid="0FE2DA40-5637-472A-9736-72019EABD7DE"
|
---|
15082 | wsmap="managed" autogen="VBoxEvent" id="OnMediumChanged"
|
---|
15083 | >
|
---|
15084 | <desc>
|
---|
15085 | Notification when a
|
---|
15086 | <link to="IMachine::mediumAttachments">medium attachment</link>
|
---|
15087 | changes.
|
---|
15088 | </desc>
|
---|
15089 | <attribute name="mediumAttachment" type="IMediumAttachment" readonly="yes">
|
---|
15090 | <desc>
|
---|
15091 | Medium attachment that is subject to change.
|
---|
15092 | </desc>
|
---|
15093 | </attribute>
|
---|
15094 | </interface>
|
---|
15095 |
|
---|
15096 | <interface
|
---|
15097 | name="ICPUChangedEvent" extends="IEvent"
|
---|
15098 | uuid="D0F0BECC-EE17-4D17-A8CC-383B0EB55E9D"
|
---|
15099 | wsmap="managed" autogen="VBoxEvent" id="OnCPUChanged"
|
---|
15100 | >
|
---|
15101 | <desc>
|
---|
15102 | Notification when a CPU changes.
|
---|
15103 | </desc>
|
---|
15104 | <attribute name="cpu" type="unsigned long" readonly="yes">
|
---|
15105 | <desc>
|
---|
15106 | The CPU which changed.
|
---|
15107 | </desc>
|
---|
15108 | </attribute>
|
---|
15109 | <attribute name="add" type="boolean" readonly="yes">
|
---|
15110 | <desc>
|
---|
15111 | Flag whether the CPU was added or removed.
|
---|
15112 | </desc>
|
---|
15113 | </attribute>
|
---|
15114 | </interface>
|
---|
15115 |
|
---|
15116 | <interface
|
---|
15117 | name="ICPUExecutionCapChangedEvent" extends="IEvent"
|
---|
15118 | uuid="dfa7e4f5-b4a4-44ce-85a8-127ac5eb59dc"
|
---|
15119 | wsmap="managed" autogen="VBoxEvent" id="OnCPUExecutionCapChanged"
|
---|
15120 | >
|
---|
15121 | <desc>
|
---|
15122 | Notification when the CPU execution cap changes.
|
---|
15123 | </desc>
|
---|
15124 | <attribute name="executionCap" type="unsigned long" readonly="yes">
|
---|
15125 | <desc>
|
---|
15126 | The new CPU execution cap value. (1-100)
|
---|
15127 | </desc>
|
---|
15128 | </attribute>
|
---|
15129 | </interface>
|
---|
15130 |
|
---|
15131 | <interface
|
---|
15132 | name="IGuestKeyboardEvent" extends="IEvent"
|
---|
15133 | uuid="88394258-7006-40d4-b339-472ee3801844"
|
---|
15134 | wsmap="managed" autogen="VBoxEvent" id="OnGuestKeyboardEvent"
|
---|
15135 | >
|
---|
15136 | <desc>
|
---|
15137 | Notification when guest keyboard event happens.
|
---|
15138 | </desc>
|
---|
15139 | <attribute name="scancodes" type="long" safearray="yes" readonly="yes">
|
---|
15140 | <desc>
|
---|
15141 | Array of scancodes.
|
---|
15142 | </desc>
|
---|
15143 | </attribute>
|
---|
15144 | </interface>
|
---|
15145 |
|
---|
15146 | <interface
|
---|
15147 | name="IGuestMouseEvent" extends="IReusableEvent"
|
---|
15148 | uuid="1f85d35c-c524-40ff-8e98-307000df0992"
|
---|
15149 | wsmap="managed" autogen="VBoxEvent" id="OnGuestMouseEvent"
|
---|
15150 | >
|
---|
15151 | <desc>
|
---|
15152 | Notification when guest mouse event happens.
|
---|
15153 | </desc>
|
---|
15154 |
|
---|
15155 | <attribute name="absolute" type="boolean" readonly="yes">
|
---|
15156 | <desc>
|
---|
15157 | If this event is relative or absolute.
|
---|
15158 | </desc>
|
---|
15159 | </attribute>
|
---|
15160 |
|
---|
15161 | <attribute name="x" type="long" readonly="yes">
|
---|
15162 | <desc>
|
---|
15163 | New X position, or X delta.
|
---|
15164 | </desc>
|
---|
15165 | </attribute>
|
---|
15166 |
|
---|
15167 | <attribute name="y" type="long" readonly="yes">
|
---|
15168 | <desc>
|
---|
15169 | New Y position, or Y delta.
|
---|
15170 | </desc>
|
---|
15171 | </attribute>
|
---|
15172 |
|
---|
15173 | <attribute name="z" type="long" readonly="yes">
|
---|
15174 | <desc>
|
---|
15175 | Z delta.
|
---|
15176 | </desc>
|
---|
15177 | </attribute>
|
---|
15178 |
|
---|
15179 | <attribute name="w" type="long" readonly="yes">
|
---|
15180 | <desc>
|
---|
15181 | W delta.
|
---|
15182 | </desc>
|
---|
15183 | </attribute>
|
---|
15184 |
|
---|
15185 | <attribute name="buttons" type="long" readonly="yes">
|
---|
15186 | <desc>
|
---|
15187 | Button state bitmask.
|
---|
15188 | </desc>
|
---|
15189 | </attribute>
|
---|
15190 |
|
---|
15191 | </interface>
|
---|
15192 |
|
---|
15193 |
|
---|
15194 | <interface
|
---|
15195 | name="IVRDEServerChangedEvent" extends="IEvent"
|
---|
15196 | uuid="a06fd66a-3188-4c8c-8756-1395e8cb691c"
|
---|
15197 | wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerChanged"
|
---|
15198 | >
|
---|
15199 | <desc>
|
---|
15200 | Notification when a property of the
|
---|
15201 | <link to="IMachine::VRDEServer">VRDE server</link> changes.
|
---|
15202 | Interested callees should use IVRDEServer methods and attributes to
|
---|
15203 | find out what has changed.
|
---|
15204 | </desc>
|
---|
15205 | </interface>
|
---|
15206 |
|
---|
15207 | <interface
|
---|
15208 | name="IVRDEServerInfoChangedEvent" extends="IEvent"
|
---|
15209 | uuid="dd6a1080-e1b7-4339-a549-f0878115596e"
|
---|
15210 | wsmap="managed" autogen="VBoxEvent" id="OnVRDEServerInfoChanged"
|
---|
15211 | >
|
---|
15212 | <desc>
|
---|
15213 | Notification when the status of the VRDE server changes. Interested callees
|
---|
15214 | should use <link to="IConsole::VRDEServerInfo">IVRDEServerInfo</link>
|
---|
15215 | attributes to find out what is the current status.
|
---|
15216 | </desc>
|
---|
15217 | </interface>
|
---|
15218 |
|
---|
15219 | <interface
|
---|
15220 | name="IUSBControllerChangedEvent" extends="IEvent"
|
---|
15221 | uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83"
|
---|
15222 | wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged"
|
---|
15223 | >
|
---|
15224 | <desc>
|
---|
15225 | Notification when a property of the virtual
|
---|
15226 | <link to="IMachine::USBController">USB controller</link> changes.
|
---|
15227 | Interested callees should use IUSBController methods and attributes to
|
---|
15228 | find out what has changed.
|
---|
15229 | </desc>
|
---|
15230 | </interface>
|
---|
15231 |
|
---|
15232 | <interface
|
---|
15233 | name="IUSBDeviceStateChangedEvent" extends="IEvent"
|
---|
15234 | uuid="806da61b-6679-422a-b629-51b06b0c6d93"
|
---|
15235 | wsmap="managed" autogen="VBoxEvent" id="OnUSBDeviceStateChanged"
|
---|
15236 | >
|
---|
15237 | <desc>
|
---|
15238 | Notification when a USB device is attached to or detached from
|
---|
15239 | the virtual USB controller.
|
---|
15240 |
|
---|
15241 | This notification is sent as a result of the indirect
|
---|
15242 | request to attach the device because it matches one of the
|
---|
15243 | machine USB filters, or as a result of the direct request
|
---|
15244 | issued by <link to="IConsole::attachUSBDevice"/> or
|
---|
15245 | <link to="IConsole::detachUSBDevice"/>.
|
---|
15246 |
|
---|
15247 | This notification is sent in case of both a succeeded and a
|
---|
15248 | failed request completion. When the request succeeds, the
|
---|
15249 | @a error parameter is @c null, and the given device has been
|
---|
15250 | already added to (when @a attached is @c true) or removed from
|
---|
15251 | (when @a attached is @c false) the collection represented by
|
---|
15252 | <link to="IConsole::USBDevices"/>. On failure, the collection
|
---|
15253 | doesn't change and the @a error parameter represents the error
|
---|
15254 | message describing the failure.
|
---|
15255 | </desc>
|
---|
15256 | <attribute name="device" type="IUSBDevice" readonly="yes">
|
---|
15257 | <desc>
|
---|
15258 | Device that is subject to state change.
|
---|
15259 | </desc>
|
---|
15260 | </attribute>
|
---|
15261 | <attribute name="attached" type="boolean" readonly="yes">
|
---|
15262 | <desc>
|
---|
15263 | @c true if the device was attached and @c false otherwise.
|
---|
15264 | </desc>
|
---|
15265 | </attribute>
|
---|
15266 | <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes">
|
---|
15267 | <desc>
|
---|
15268 | @c null on success or an error message object on failure.
|
---|
15269 | </desc>
|
---|
15270 | </attribute>
|
---|
15271 | </interface>
|
---|
15272 |
|
---|
15273 | <interface
|
---|
15274 | name="ISharedFolderChangedEvent" extends="IEvent"
|
---|
15275 | uuid="B66349B5-3534-4239-B2DE-8E1535D94C0B"
|
---|
15276 | wsmap="managed" autogen="VBoxEvent" id="OnSharedFolderChanged"
|
---|
15277 | >
|
---|
15278 | <desc>
|
---|
15279 | Notification when a shared folder is added or removed.
|
---|
15280 | The @a scope argument defines one of three scopes:
|
---|
15281 | <link to="IVirtualBox::sharedFolders">global shared folders</link>
|
---|
15282 | (<link to="Scope_Global">Global</link>),
|
---|
15283 | <link to="IMachine::sharedFolders">permanent shared folders</link> of
|
---|
15284 | the machine (<link to="Scope_Machine">Machine</link>) or <link
|
---|
15285 | to="IConsole::sharedFolders">transient shared folders</link> of the
|
---|
15286 | machine (<link to="Scope_Session">Session</link>). Interested callees
|
---|
15287 | should use query the corresponding collections to find out what has
|
---|
15288 | changed.
|
---|
15289 | </desc>
|
---|
15290 | <attribute name="scope" type="Scope" readonly="yes">
|
---|
15291 | <desc>
|
---|
15292 | Scope of the notification.
|
---|
15293 | </desc>
|
---|
15294 | </attribute>
|
---|
15295 | </interface>
|
---|
15296 |
|
---|
15297 | <interface
|
---|
15298 | name="IRuntimeErrorEvent" extends="IEvent"
|
---|
15299 | uuid="883DD18B-0721-4CDE-867C-1A82ABAF914C"
|
---|
15300 | wsmap="managed" autogen="VBoxEvent" id="OnRuntimeError"
|
---|
15301 | >
|
---|
15302 | <desc>
|
---|
15303 | Notification when an error happens during the virtual
|
---|
15304 | machine execution.
|
---|
15305 |
|
---|
15306 | There are three kinds of runtime errors:
|
---|
15307 | <ul>
|
---|
15308 | <li><i>fatal</i></li>
|
---|
15309 | <li><i>non-fatal with retry</i></li>
|
---|
15310 | <li><i>non-fatal warnings</i></li>
|
---|
15311 | </ul>
|
---|
15312 |
|
---|
15313 | <b>Fatal</b> errors are indicated by the @a fatal parameter set
|
---|
15314 | to @c true. In case of fatal errors, the virtual machine
|
---|
15315 | execution is always paused before calling this notification, and
|
---|
15316 | the notification handler is supposed either to immediately save
|
---|
15317 | the virtual machine state using <link to="IConsole::saveState"/>
|
---|
15318 | or power it off using <link to="IConsole::powerDown"/>.
|
---|
15319 | Resuming the execution can lead to unpredictable results.
|
---|
15320 |
|
---|
15321 | <b>Non-fatal</b> errors and warnings are indicated by the
|
---|
15322 | @a fatal parameter set to @c false. If the virtual machine
|
---|
15323 | is in the Paused state by the time the error notification is
|
---|
15324 | received, it means that the user can <i>try to resume</i> the machine
|
---|
15325 | execution after attempting to solve the problem that caused the
|
---|
15326 | error. In this case, the notification handler is supposed
|
---|
15327 | to show an appropriate message to the user (depending on the
|
---|
15328 | value of the @a id parameter) that offers several actions such
|
---|
15329 | as <i>Retry</i>, <i>Save</i> or <i>Power Off</i>. If the user
|
---|
15330 | wants to retry, the notification handler should continue
|
---|
15331 | the machine execution using the <link to="IConsole::resume"/>
|
---|
15332 | call. If the machine execution is not Paused during this
|
---|
15333 | notification, then it means this notification is a <i>warning</i>
|
---|
15334 | (for example, about a fatal condition that can happen very soon);
|
---|
15335 | no immediate action is required from the user, the machine
|
---|
15336 | continues its normal execution.
|
---|
15337 |
|
---|
15338 | Note that in either case the notification handler
|
---|
15339 | <b>must not</b> perform any action directly on a thread
|
---|
15340 | where this notification is called. Everything it is allowed to
|
---|
15341 | do is to post a message to another thread that will then talk
|
---|
15342 | to the user and take the corresponding action.
|
---|
15343 |
|
---|
15344 | Currently, the following error identifiers are known:
|
---|
15345 | <ul>
|
---|
15346 | <li><tt>"HostMemoryLow"</tt></li>
|
---|
15347 | <li><tt>"HostAudioNotResponding"</tt></li>
|
---|
15348 | <li><tt>"VDIStorageFull"</tt></li>
|
---|
15349 | <li><tt>"3DSupportIncompatibleAdditions"</tt></li>
|
---|
15350 | </ul>
|
---|
15351 | </desc>
|
---|
15352 | <attribute name="fatal" type="boolean" readonly="yes">
|
---|
15353 | <desc>
|
---|
15354 | Whether the error is fatal or not.
|
---|
15355 | </desc>
|
---|
15356 | </attribute>
|
---|
15357 | <attribute name="id" type="wstring" readonly="yes">
|
---|
15358 | <desc>
|
---|
15359 | Error identifier.
|
---|
15360 | </desc>
|
---|
15361 | </attribute>
|
---|
15362 | <attribute name="message" type="wstring" readonly="yes">
|
---|
15363 | <desc>
|
---|
15364 | Optional error message.
|
---|
15365 | </desc>
|
---|
15366 | </attribute>
|
---|
15367 | </interface>
|
---|
15368 |
|
---|
15369 |
|
---|
15370 | <interface
|
---|
15371 | name="IEventSourceChangedEvent" extends="IEvent"
|
---|
15372 | uuid="e7932cb8-f6d4-4ab6-9cbf-558eb8959a6a"
|
---|
15373 | waitable="yes"
|
---|
15374 | wsmap="managed" autogen="VBoxEvent" id="OnEventSourceChanged"
|
---|
15375 | >
|
---|
15376 | <desc>
|
---|
15377 | Notification when an event source state changes (listener added or removed).
|
---|
15378 | </desc>
|
---|
15379 |
|
---|
15380 | <attribute name="listener" type="IEventListener" readonly="yes">
|
---|
15381 | <desc>
|
---|
15382 | Event listener which has changed.
|
---|
15383 | </desc>
|
---|
15384 | </attribute>
|
---|
15385 |
|
---|
15386 | <attribute name="add" type="boolean" readonly="yes">
|
---|
15387 | <desc>
|
---|
15388 | Flag whether listener was added or removed.
|
---|
15389 | </desc>
|
---|
15390 | </attribute>
|
---|
15391 | </interface>
|
---|
15392 |
|
---|
15393 | <interface
|
---|
15394 | name="IExtraDataChangedEvent" extends="IEvent"
|
---|
15395 | uuid="024F00CE-6E0B-492A-A8D0-968472A94DC7"
|
---|
15396 | wsmap="managed" autogen="VBoxEvent" id="OnExtraDataChanged"
|
---|
15397 | >
|
---|
15398 | <desc>
|
---|
15399 | Notification when machine specific or global extra data
|
---|
15400 | has changed.
|
---|
15401 | </desc>
|
---|
15402 | <attribute name="machineId" type="uuid" mod="string" readonly="yes">
|
---|
15403 | <desc>
|
---|
15404 | ID of the machine this event relates to.
|
---|
15405 | Null for global extra data changes.
|
---|
15406 | </desc>
|
---|
15407 | </attribute>
|
---|
15408 | <attribute name="key" type="wstring" readonly="yes">
|
---|
15409 | <desc>
|
---|
15410 | Extra data key that has changed.
|
---|
15411 | </desc>
|
---|
15412 | </attribute>
|
---|
15413 | <attribute name="value" type="wstring" readonly="yes">
|
---|
15414 | <desc>
|
---|
15415 | Extra data value for the given key.
|
---|
15416 | </desc>
|
---|
15417 | </attribute>
|
---|
15418 | </interface>
|
---|
15419 |
|
---|
15420 | <interface
|
---|
15421 | name="IVetoEvent" extends="IEvent"
|
---|
15422 | uuid="9a1a4130-69fe-472f-ac10-c6fa25d75007"
|
---|
15423 | wsmap="managed"
|
---|
15424 | >
|
---|
15425 | <desc>Base abstract interface for veto events.</desc>
|
---|
15426 |
|
---|
15427 | <method name="addVeto">
|
---|
15428 | <desc>
|
---|
15429 | Adds a veto on this event.
|
---|
15430 | </desc>
|
---|
15431 | <param name="reason" type="wstring" dir="in">
|
---|
15432 | <desc>
|
---|
15433 | Reason for veto, could be null or empty string.
|
---|
15434 | </desc>
|
---|
15435 | </param>
|
---|
15436 | </method>
|
---|
15437 |
|
---|
15438 | <method name="isVetoed">
|
---|
15439 | <desc>
|
---|
15440 | If this event was vetoed.
|
---|
15441 | </desc>
|
---|
15442 | <param name="result" type="boolean" dir="return">
|
---|
15443 | <desc>
|
---|
15444 | Reason for veto.
|
---|
15445 | </desc>
|
---|
15446 | </param>
|
---|
15447 | </method>
|
---|
15448 |
|
---|
15449 | <method name="getVetos">
|
---|
15450 | <desc>
|
---|
15451 | Current veto reason list, if size is 0 - no veto.
|
---|
15452 | </desc>
|
---|
15453 | <param name="result" type="wstring" dir="return" safearray="yes">
|
---|
15454 | <desc>
|
---|
15455 | Array of reasons for veto provided by different event handlers.
|
---|
15456 | </desc>
|
---|
15457 | </param>
|
---|
15458 | </method>
|
---|
15459 |
|
---|
15460 | </interface>
|
---|
15461 |
|
---|
15462 | <interface
|
---|
15463 | name="IExtraDataCanChangeEvent" extends="IVetoEvent"
|
---|
15464 | uuid="245d88bd-800a-40f8-87a6-170d02249a55"
|
---|
15465 | wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange"
|
---|
15466 | waitable="true"
|
---|
15467 | >
|
---|
15468 | <desc>
|
---|
15469 | Notification when someone tries to change extra data for
|
---|
15470 | either the given machine or (if @c null) global extra data.
|
---|
15471 | This gives the chance to veto against changes.
|
---|
15472 | </desc>
|
---|
15473 | <attribute name="machineId" type="uuid" mod="string" readonly="yes">
|
---|
15474 | <desc>
|
---|
15475 | ID of the machine this event relates to.
|
---|
15476 | Null for global extra data changes.
|
---|
15477 | </desc>
|
---|
15478 | </attribute>
|
---|
15479 | <attribute name="key" type="wstring" readonly="yes">
|
---|
15480 | <desc>
|
---|
15481 | Extra data key that has changed.
|
---|
15482 | </desc>
|
---|
15483 | </attribute>
|
---|
15484 | <attribute name="value" type="wstring" readonly="yes">
|
---|
15485 | <desc>
|
---|
15486 | Extra data value for the given key.
|
---|
15487 | </desc>
|
---|
15488 | </attribute>
|
---|
15489 | </interface>
|
---|
15490 |
|
---|
15491 | <interface
|
---|
15492 | name="ICanShowWindowEvent" extends="IVetoEvent"
|
---|
15493 | uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9"
|
---|
15494 | wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow"
|
---|
15495 | waitable="true"
|
---|
15496 | >
|
---|
15497 | <desc>
|
---|
15498 | Notification when a call to
|
---|
15499 | <link to="IMachine::canShowConsoleWindow"/> is made by a
|
---|
15500 | front-end to check if a subsequent call to
|
---|
15501 | <link to="IMachine::showConsoleWindow"/> can succeed.
|
---|
15502 |
|
---|
15503 | The callee should give an answer appropriate to the current
|
---|
15504 | machine state using event veto. This answer must
|
---|
15505 | remain valid at least until the next
|
---|
15506 | <link to="IConsole::state">machine state</link> change.
|
---|
15507 | </desc>
|
---|
15508 | </interface>
|
---|
15509 |
|
---|
15510 | <interface
|
---|
15511 | name="IShowWindowEvent" extends="IEvent"
|
---|
15512 | uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2"
|
---|
15513 | wsmap="managed" autogen="VBoxEvent" id="OnShowWindow"
|
---|
15514 | waitable="true"
|
---|
15515 | >
|
---|
15516 | <desc>
|
---|
15517 | Notification when a call to
|
---|
15518 | <link to="IMachine::showConsoleWindow"/>
|
---|
15519 | requests the console window to be activated and brought to
|
---|
15520 | foreground on the desktop of the host PC.
|
---|
15521 |
|
---|
15522 | This notification should cause the VM console process to
|
---|
15523 | perform the requested action as described above. If it is
|
---|
15524 | impossible to do it at a time of this notification, this
|
---|
15525 | method should return a failure.
|
---|
15526 |
|
---|
15527 | Note that many modern window managers on many platforms
|
---|
15528 | implement some sort of focus stealing prevention logic, so
|
---|
15529 | that it may be impossible to activate a window without the
|
---|
15530 | help of the currently active application (which is supposedly
|
---|
15531 | an initiator of this notification). In this case, this method
|
---|
15532 | must return a non-zero identifier that represents the
|
---|
15533 | top-level window of the VM console process. The caller, if it
|
---|
15534 | represents a currently active process, is responsible to use
|
---|
15535 | this identifier (in a platform-dependent manner) to perform
|
---|
15536 | actual window activation.
|
---|
15537 |
|
---|
15538 | This method must set @a winId to zero if it has performed all
|
---|
15539 | actions necessary to complete the request and the console
|
---|
15540 | window is now active and in foreground, to indicate that no
|
---|
15541 | further action is required on the caller's side.
|
---|
15542 | </desc>
|
---|
15543 | <attribute name="winId" type="long long">
|
---|
15544 | <desc>
|
---|
15545 | Platform-dependent identifier of the top-level VM console
|
---|
15546 | window, or zero if this method has performed all actions
|
---|
15547 | necessary to implement the <i>show window</i> semantics for
|
---|
15548 | the given platform and/or this VirtualBox front-end.
|
---|
15549 | </desc>
|
---|
15550 | </attribute>
|
---|
15551 | </interface>
|
---|
15552 |
|
---|
15553 | <module name="VBoxSVC" context="LocalServer">
|
---|
15554 | <class name="VirtualBox" uuid="B1A7A4F2-47B9-4A1E-82B2-07CCD5323C3F"
|
---|
15555 | namespace="virtualbox.org">
|
---|
15556 | <interface name="IVirtualBox" default="yes"/>
|
---|
15557 | </class>
|
---|
15558 | </module>
|
---|
15559 |
|
---|
15560 | <module name="VBoxC" context="InprocServer" threadingModel="Free">
|
---|
15561 | <class name="Session" uuid="3C02F46D-C9D2-4F11-A384-53F0CF917214"
|
---|
15562 | namespace="virtualbox.org">
|
---|
15563 | <interface name="ISession" default="yes"/>
|
---|
15564 | </class>
|
---|
15565 |
|
---|
15566 | <class name="Console" uuid="577230FF-164F-4CAC-8548-312D8275A4A7"
|
---|
15567 | namespace="virtualbox.org">
|
---|
15568 | <interface name="IConsole" default="yes"/>
|
---|
15569 | </class>
|
---|
15570 | </module>
|
---|
15571 |
|
---|
15572 | </library>
|
---|
15573 |
|
---|
15574 | </idl>
|
---|
15575 |
|
---|
15576 | <!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->
|
---|