From f215e02bf85f68d3a6106c2a1f4f7f063f819064 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 11 Apr 2024 10:17:27 +0200 Subject: Adding upstream version 7.0.14-dfsg. Signed-off-by: Daniel Baumann --- src/VBox/Main/idl/VirtualBox.xidl | 30777 ++++++++++++++++++++++++++++++++++++ 1 file changed, 30777 insertions(+) create mode 100644 src/VBox/Main/idl/VirtualBox.xidl (limited to 'src/VBox/Main/idl/VirtualBox.xidl') diff --git a/src/VBox/Main/idl/VirtualBox.xidl b/src/VBox/Main/idl/VirtualBox.xidl new file mode 100644 index 00000000..8654afec --- /dev/null +++ b/src/VBox/Main/idl/VirtualBox.xidl @@ -0,0 +1,30777 @@ + + + + + + + + + + + + Welcome to the VirtualBox Main API documentation. This documentation + describes the so-called VirtualBox Main API which comprises all public + COM interfaces and components provided by the VirtualBox server and by the + VirtualBox client library. + + VirtualBox employs a client-server design, meaning that whenever any part of + VirtualBox is running -- be it the Qt GUI, the VBoxManage command-line + interface or any virtual machine --, a dedicated server process named + VBoxSVC runs in the background. This allows multiple processes working with + VirtualBox to cooperate without conflicts. These processes communicate to each + other using inter-process communication facilities provided by the COM + implementation of the host computer. + + On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM + implementation. On all other platforms, Mozilla XPCOM, an open-source COM + implementation, is used. + + All the parts that a typical VirtualBox user interacts with (the Qt GUI + and the VBoxManage command-line interface) are technically + front-ends to the Main API and only use the interfaces that are documented + in this Main API documentation. This ensures that, with any given release + version of VirtualBox, all capabilities of the product that could be useful + to an external client program are always exposed by way of this API. + + The VirtualBox Main API (also called the VirtualBox COM library) + contains two public component classes: + %VirtualBox.VirtualBox and %VirtualBox.Session, which + implement IVirtualBox and ISession interfaces respectively. These two classes + are of supreme importance and will be needed in order for any front-end + program to do anything useful. It is recommended to read the documentation of + the mentioned interfaces first. + + The %VirtualBox.VirtualBox class is a singleton. This means that + there can be only one object of this class on the local machine at any given + time. This object is a parent of many other objects in the VirtualBox COM + library and lives in the VBoxSVC process. In fact, when you create an instance + of the VirtualBox.VirtualBox, the COM subsystem checks if the VBoxSVC + process is already running, starts it if not, and returns you a reference to + the VirtualBox object created in this process. When the last reference + to this object is released, the VBoxSVC process ends (with a 5 second delay to + protect from too frequent restarts). + + The %VirtualBox.Session class is a regular component. You can create + as many Session objects as you need but all of them will live in a + process which issues the object instantiation call. Session objects + represent virtual machine sessions which are used to configure virtual + machines and control their execution. + + The naming of methods and attributes is very clearly defined: they all start + with a lowercase letter (except if they start with an acronym), and are using + CamelCase style otherwise. This naming only applies to the IDL description, + and is modified by the various language bindings (some convert the first + character to upper case, some not). See the SDK reference for more details + about how to call a method or attribute from a specific programming language. + + + + + + + + + + + + +/* currently, nsISupportsImpl.h lacks the below-like macros */ + +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI NS_IMPL_QUERY_INTERFACE1_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI NS_IMPL_QUERY_INTERFACE2_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI NS_IMPL_QUERY_INTERFACE3_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI NS_IMPL_QUERY_INTERFACE4_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI NS_IMPL_QUERY_INTERFACE5_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI NS_IMPL_QUERY_INTERFACE6_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI NS_IMPL_QUERY_INTERFACE7_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI NS_IMPL_QUERY_INTERFACE8_CI + + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS1_CI(_class, _interface) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE1_CI(_class, _interface) \ + NS_IMPL_CI_INTERFACE_GETTER1(_class, _interface) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS2_CI(_class, _i1, _i2) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE2_CI(_class, _i1, _i2) \ + NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS3_CI(_class, _i1, _i2, _i3) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE3_CI(_class, _i1, _i2, _i3) \ + NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS4_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS4_CI(_class, _i1, _i2, _i3, _i4) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE4_CI(_class, _i1, _i2, _i3, _i4) \ + NS_IMPL_CI_INTERFACE_GETTER4(_class, _i1, _i2, _i3, _i4) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS5_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS5_CI(_class, _i1, _i2, _i3, _i4, _i5) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE5_CI(_class, _i1, _i2, _i3, _i4, _i5) \ + NS_IMPL_CI_INTERFACE_GETTER5(_class, _i1, _i2, _i3, _i4, _i5) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS6_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE6_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6) \ + NS_IMPL_CI_INTERFACE_GETTER6(_class, _i1, _i2, _i3, _i4, _i5, _i6) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS7_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE7_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) \ + NS_IMPL_CI_INTERFACE_GETTER7(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS8_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE8_CI(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) \ + NS_IMPL_CI_INTERFACE_GETTER8(_class, _i1, _i2, _i3, _i4, _i5, _i6, _i7, _i8) +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#ifndef NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI +# define NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_INTERFACE_MAP_BEGIN(_class) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i1, _ic1) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i2, _ic2) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(_i3, _ic3) \ + NS_INTERFACE_MAP_ENTRY_AMBIGUOUS(nsISupports, _ic1) \ + NS_IMPL_QUERY_CLASSINFO(_class) \ + NS_INTERFACE_MAP_END +#endif + +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE1_AMBIGUOUS_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE2_AMBIGUOUS_CI +#define NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI NS_IMPL_QUERY_INTERFACE3_AMBIGUOUS_CI + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE1_AMBIGUOUS_CI(_class, _i1, _ic1) \ + NS_IMPL_CI_INTERFACE_GETTER1(_class, _i1) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE2_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2) \ + NS_IMPL_CI_INTERFACE_GETTER2(_class, _i1, _i2) +#endif + +#ifndef NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI +# define NS_IMPL_THREADSAFE_ISUPPORTS3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_IMPL_THREADSAFE_ADDREF(_class) \ + NS_IMPL_THREADSAFE_RELEASE(_class) \ + NS_IMPL_THREADSAFE_QUERY_INTERFACE3_AMBIGUOUS_CI(_class, _i1, _ic1, \ + _i2, _ic2, _i3, _ic3) \ + NS_IMPL_CI_INTERFACE_GETTER3(_class, _i1, _i2, _i3) +#endif + + + + + + + + + + + + + + + This section describes all VirtualBox-specific COM result codes that may + be returned by methods of VirtualBox COM interfaces in addition to + standard COM result codes. + + Note that along with the result code, every VirtualBox method returns + extended error information through the IVirtualBoxErrorInfo interface on + failure. This interface is a preferred way to present the error to the end + user because it contains a human readable description of the error. Raw + result codes, both standard and described in this section, are intended to + be used by programs to analyze the reason of a failure and select an + appropriate course of action without involving the end user (for example, + retry the operation later or make a different call). + + The standard COM result codes that may originate from our methods include: + +
+
E_INVALIDARG
+
+ Returned when the value of the method's argument is not within the range + of valid values. This should not be confused with situations when the + value is within the range but simply doesn't suit the current object + state and there is a possibility that it will be accepted later (in such + cases VirtualBox-specific codes are returned, for example, + ). +
+
E_POINTER
+
+ Returned if a memory pointer for the output argument is invalid (for + example, @c null). When pointers representing input arguments (such + as strings) are invalid, E_INVALIDARG is returned. +
+
E_ACCESSDENIED
+
+ Returned when the called object is not ready. Since the lifetime of a + public COM object cannot be fully controlled by the implementation, + VirtualBox maintains the readiness state for all objects it creates and + returns this code in response to any method call on the object that was + deactivated by VirtualBox and is not functioning any more. +
+
E_OUTOFMEMORY
+
+ Returned when a memory allocation operation fails. +
+
+ + + + + + + + Object corresponding to the supplied arguments does not exist. + + + + + + Current virtual machine state prevents the operation. + + + + + + Virtual machine error occurred attempting the operation. + + + + + + File not accessible or erroneous file contents. + + + + + + Runtime subsystem error. + + + + + + Pluggable Device Manager error. + + + + + + Current object state prohibits operation. + + + + + + Host operating system related error. + + + + + + Requested operation is not supported. + + + + + + Invalid XML found. + + + + + + Current session state prohibits operation. + + + + + + Object being in use prohibits operation. + + + + + + A provided password was incorrect. + + + + + + A maximum has been reached. + + + + + + Guest Control reported an error from the guest side. + + + + + + The operation ran into an explicitly requested timeout. + + + + + + A drag and drop error has occurred. + + + + + + + + + + + + Settings version of VirtualBox settings files. This is written to + the "version" attribute of the root "VirtualBox" element in the settings + file XML and indicates which VirtualBox version wrote the file. + + + + Null value, indicates invalid version. + + + Legacy settings version, not currently supported. + + + Legacy settings version, not currently supported. + + + Legacy settings version, not currently supported. + + + Legacy settings version, not currently supported. + + + Settings version "1.3", written by VirtualBox 2.0.12. + + + + Intermediate settings version, understood by VirtualBox 2.1.x. + + + + Intermediate settings version, understood by VirtualBox 2.1.x. + + + + Settings version "1.6", written by VirtualBox 2.1.4 (at least). + + + + Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x. + + + + Intermediate settings version "1.8", understood by VirtualBox 3.1.x. + + + + Settings version "1.9", written by VirtualBox 3.1.x. + + + + Settings version "1.10", written by VirtualBox 3.2.x. + + + + Settings version "1.11", written by VirtualBox 4.0.x. + + + + Settings version "1.12", written by VirtualBox 4.1.x. + + + + Settings version "1.13", written by VirtualBox 4.2.x. + + + + Settings version "1.14", written by VirtualBox 4.3.x. + + + + Settings version "1.15", written by VirtualBox 5.0.x. + + + + Settings version "1.16", written by VirtualBox 5.1.x. + + + + Settings version "1.17", written by VirtualBox 6.0.x. + + + + Settings version "1.18", written by VirtualBox 6.1.x. + + + + Settings version "1.19", written by VirtualBox 7.0.x. + + + + Settings version greater than "1.19", written by a future VirtualBox version. + + + + + + Access mode for opening files. + + + + + + + + + Virtual machine execution state. + + This enumeration represents possible values of the attribute. + + Below is the basic virtual machine state diagram. It shows how the state + changes during virtual machine execution. The text in square braces shows + a method of the IConsole or IMachine interface that performs the given state + transition. + + 
+            +---------[powerDown()] <- Stuck <--[failure]-+
+            V                                             |
+    +-> PoweredOff --+-->[powerUp()]--> Starting --+      | +-----[resume()]-----+
+    |                |                             |      | V                    |
+    |   Aborted <----+                             +--> Running --[pause()]--> Paused
+    |                                              |      ^ |                   ^ |
+    |  AbortedSaved <-----------[failure]-----<----+      | |                   | |
+    |       |                                      |      | |                   | |
+    |       +-------------+                        |      | |                   | |
+    |                     V                        |      | |                   | |
+    |   Saved --------[powerUp()]-----> Restoring -+      | |                   | |
+    |     ^                                               | |                   | |
+    |     |     +-----------------------------------------+-|-------------------+ +
+    |     |     |                                           |                     |
+    |     |     +- OnlineSnapshotting <--[takeSnapshot()]<--+---------------------+
+    |     |                                                 |                     |
+    |     +-------- Saving <--------[saveState()]<----------+---------------------+
+    |                                                       |                     |
+    +-------------- Stopping -------[powerDown()]<----------+---------------------+
+
+ + Note that states to the right of PoweredOff, Aborted, AbortedSaved, and + Saved in the above diagram are called online VM states. These + states represent the virtual machine which is being executed in a + dedicated process (usually with a GUI window attached to it where you can + see the activity of the virtual machine and interact with it). There are + two special pseudo-states, FirstOnline and LastOnline, that can be used + in relational expressions to detect if the given machine state is online + or not: + + 
+        if (machine.GetState() >= MachineState_FirstOnline &&
+            machine.GetState() <= MachineState_LastOnline)
+        {
+            ...the machine is being executed...
+        }
+
+ + When the virtual machine is in one of the online VM states (that is, being + executed), only a few machine settings can be modified. Methods working + with such settings contain an explicit note about that. An attempt to + change any other setting or perform a modifying operation during this time + will result in the @c VBOX_E_INVALID_VM_STATE error. + + All online states except Running, Paused and Stuck are transitional: they + represent temporary conditions of the virtual machine that will last as + long as the operation that initiated such a condition. + + The Stuck state is a special case. It means that execution of the machine + has reached the "Guru Meditation" condition. This condition indicates an + internal VMM (virtual machine manager) failure which may happen as a + result of either an unhandled low-level virtual hardware exception or one + of the recompiler exceptions (such as the too-many-traps + condition). + + Note also that any online VM state may transit to the Aborted state. This + happens if the process that is executing the virtual machine terminates + unexpectedly (for example, crashes). Other than that, the Aborted state is + equivalent to PoweredOff. + + There are also a few additional state diagrams that do not deal with + virtual machine execution and therefore are shown separately. The states + shown on these diagrams are called offline VM states (this includes + PoweredOff, Aborted, AbortedSaved and Saved too). + + The first diagram shows what happens when a lengthy setup operation is + being executed (such as ). + + 
+    +----------------------------------(same state as before the call)------+
+    |                                                                       |
+    +-> PoweredOff --+                                                      |
+    |                |                                                      |
+    |-> Aborted -----+-->[lengthy VM configuration call] --> SettingUp -----+
+    |                |
+    +-> Saved -------+
+
+ + The next two diagrams demonstrate the process of taking a snapshot of a + powered off virtual machine, restoring the state to that as of a snapshot + or deleting a snapshot, respectively. + + 
+    +----------------------------------(same state as before the call)------+
+    |                                                                       |
+    +-> PoweredOff --+                                                      |
+    |                +-->[takeSnapshot()] ------------------> Snapshotting -+
+    +-> Aborted -----+
+
+    +-> PoweredOff --+
+    |                |
+    |   Aborted -----+-->[restoreSnapshot()    ]-------> RestoringSnapshot -+
+    |                |   [deleteSnapshot()     ]-------> DeletingSnapshot --+
+    +-> Saved -------+                                                      |
+    |                                                                       |
+    +---(Saved if restored from an online snapshot, PoweredOff otherwise)---+
+
+ + + For whoever decides to touch this enum: In order to keep the + comparisons involving FirstOnline and LastOnline pseudo-states valid, + the numeric values of these states must be correspondingly updated if + needed: for any online VM state, the condition + FirstOnline <= state <= LastOnline must be + @c true. The same relates to transient states for which + the condition FirstOnline <= state <= LastOnline must be + @c true. + + + + + Null value (never used by the API). + + + + The machine is not running and has no saved execution state; it has + either never been started or been shut down successfully. + + + + + The machine is not currently running, but the execution state of the machine + has been saved to an external file when it was running, from where + it can be resumed. + + + + + The machine was teleported to a different host (or process) and then + powered off. Take care when powering it on again may corrupt resources + it shares with the teleportation target (e.g. disk and network). + + + + + The process running the machine has terminated abnormally. This may + indicate a crash of the VM process in host execution context, or + the VM process has been terminated externally. + + + + + A machine in the @c Saved stated has terminated abnormally before + reaching the @c Running state. Similar to the @c Aborted state, + this may indicate a crash of the VM process in host execution + context, or the VM process has been terminated externally. + + + + + + The machine is currently being executed. + + For whoever decides to touch this enum: In order to keep the + comparisons in the old source code valid, this state must immediately + precede the Paused state. + + @todo Lift this spectacularly wonderful restriction. + + + + + + Execution of the machine has been paused. + + For whoever decides to touch this enum: In order to keep the + comparisons in the old source code valid, this state must immediately + follow the Running state. + + @todo Lift this spectacularly wonderful restriction. + + + + + + Execution of the machine has reached the "Guru Meditation" + condition. This indicates a severe error in the hypervisor itself. + + bird: Why this uncool name? Could we rename it to "GuruMeditation" or + "Guru", perhaps? Or are there some other VMM states that are + intended to be lumped in here as well? + + + + + + The machine is about to be teleported to a different host or process. + It is possible to pause a machine in this state, but it will go to the + @c TeleportingPausedVM state and it will not be + possible to resume it again unless the teleportation fails. + + + + + A live snapshot is being taken. The machine is running normally, but + some of the runtime configuration options are inaccessible. Also, if + paused while in this state it will transition to + @c OnlineSnapshotting and it will not be resume the + execution until the snapshot operation has completed. + + + + + Machine is being started after powering it on from a + zero execution state. + + + + + Machine is being normally stopped powering it off, or after the guest OS + has initiated a shutdown sequence. + + + + + Machine is saving its execution state to a file. + + + + + Execution state of the machine is being restored from a file + after powering it on from either the @c Saved or @c AbortedSaved + execution state. + + + + + The machine is being teleported to another host or process, but it is + not running. This is the paused variant of the + @c Teleporting state. + + + + + Teleporting the machine state in from another host or process. + + + + + Like @c DeletingSnapshot, but the merging of media is ongoing in + the background while the machine is running. + + + + + Like @c DeletingSnapshotOnline, but the machine was paused when the + merging of differencing media was started. + + + + + Like @c LiveSnapshotting, but the machine was paused when the + merging of differencing media was started. + + + + + A machine snapshot is being restored; this typically does not take long. + + + + + A machine snapshot is being deleted; this can take a long time since this + may require merging differencing media. This value indicates that the + machine is not running while the snapshot is being deleted. + + + + + Lengthy setup operation is in progress. + + + + + Taking an (offline) snapshot. + + + + + + Pseudo-state: first online state (for use in relational expressions). + + + + + Pseudo-state: last online state (for use in relational expressions). + + + + + + Pseudo-state: first transient state (for use in relational expressions). + + + + + Pseudo-state: last transient state (for use in relational expressions). + + + + + + + + Session state. This enumeration represents possible values of + and + attributes. + + + + Null value (never used by the API). + + + + In , this means that the machine + is not locked for any sessions. + + In , this means that no machine is + currently locked for this session. + + + + + In , this means that the machine + is currently locked for a session, whose process identifier can + then be found in the attribute. + + In , this means that a machine is + currently locked for this session, and the mutable machine object + can be found in the attribute + (see for details). + + + + + A new process is being spawned for the machine as a result of + call. This state also occurs + as a short transient state during an + call. + + + + + The session is being unlocked. + + + + + + Basic CPU architecture types. + + Matches any CPU architecture. + + + 32-bit (and 16-bit) x86. + + + 64-bit x86. (Also known as x86-64 or x64.) + + + + + + Virtual CPU property type. This enumeration represents possible values of the + IMachine get- and setCPUProperty methods. + + + Null value (never used by the API). + + + + This setting determines whether VirtualBox will expose the Physical Address + Extension (PAE) feature of the host CPU to the guest. Note that in case PAE + is not available, it will not be reported. + + + + + This setting determines whether VirtualBox will advertise long mode + (i.e. 64-bit guest support) and let the guest enter it. + + + + + This setting determines whether a triple fault within a guest will + trigger an internal error condition and stop the VM (default) or reset + the virtual CPU/VM and continue execution. + + + + + This setting determines whether an APIC is part of the virtual CPU. + This feature can only be turned off when the X2APIC feature is off. + + + + + This setting determines whether an x2APIC is part of the virtual CPU. + Since this feature implies that the APIC feature is present, it + automatically enables the APIC feature when set. + + + + + If set, force an indirect branch prediction barrier on VM exits if the + host CPU supports it. This setting will significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + + + + + If set, force an indirect branch prediction barrier on VM entry if the + host CPU supports it. This setting will significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + + + + + Enabled the hardware virtualization (AMD-V/VT-x) feature on the guest CPU. + This requires hardware virtualization on the host CPU. + + + + + If set, the speculation control CPUID bits and MSRs, when available on the + host, are exposed to the guest. Depending on the host CPU and operating + system, this may significantly slow down workloads causing many VM exits. + + + + + If set, the speculation controls are managed by the host. This is intended + for guests which do not set the speculation controls themselves. + Note! This has not yet been implemented beyond leaving everything to the host OS. + + + + + If set and the host is affected by CVE-2018-3646, flushes the level 1 data + cache when the EMT is scheduled to do ring-0 guest execution. There could + be a small performance penalty for certain typs of workloads. + For security reasons this setting will be enabled by default. + + + + + If set and the host is affected by CVE-2018-3646, flushes the level 1 data + on every VM entry. This setting may significantly slow down workloads + causing many VM exits, so it is only recommended for situation where there + is a real need to be paranoid. + + + + + If set and the host is affected by CVE-2018-12126, CVE-2018-12127, or + CVE-2018-12130, clears the relevant MDS buffers when the EMT is scheduled + to do ring-0 guest execution. There could be a small performance penalty + for certain typs of workloads. For security reasons this setting will be + enabled by default. + + + + + If set and the host is affected by CVE-2018-12126, CVE-2018-12127, or + CVE-2018-12130, clears the relevant MDS buffers on every VM entry. This + setting may slow down workloads causing many VM exits, so it is only + recommended for situation where there is a real need to be paranoid. + + + + + + + + Hardware virtualization property type. This enumeration represents possible values + for the and + methods. + + + Null value (never used by the API). + + + + Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If + such extensions are not available, they will not be used. + + + + + Whether VT-x VPID is enabled. If this extension is not available, it will not be used. + + + + + Whether Nested Paging is enabled. If this extension is not available, it will not be used. + + + + + Whether VT-x unrestricted execution is enabled. If this feature is not available, it will not be used. + + + + + Whether large page allocation is enabled; requires nested paging and a 64-bit host. + + + + + Whether the VM should fail to start if hardware virtualization (VT-x/AMD-V) cannot be used. If + not set, there will be an automatic fallback to software virtualization. + + + + + Use the native hypervisor API instead of the VirtualBox one (HM) for VT-X/AMD-V. This is + ignored if isn't set. + + + + + Whether AMD-V Virtualized VMSAVE/VMLOAD is enabled. If this feature is not available, it will not + be used. + + + + + + + The paravirtualized guest interface provider. This enumeration represents possible + values for the attribute. + + + No provider is used. + + + A default provider is automatically chosen according to the guest OS type. + + + Used for VMs which didn't used to have any provider settings. Usually + interpreted as @c None for most VMs. + + + A minimal set of features to expose to the paravirtualized guest. + + + Microsoft Hyper-V. + + + Linux KVM. + + + + + + Used with . + + + Placeholder value, do not use when obtaining a lock. + + + Request only a shared lock for remote-controlling the machine. + Such a lock allows changing certain VM settings which can be safely + modified for a running VM. + + + Lock the machine for writing. This requests an exclusive lock, i.e. + there cannot be any other API client holding any type of lock for this + VM concurrently. Remember that a VM process counts as an API client + which implicitly holds the equivalent of a shared lock during the + entire VM runtime. + + + Lock the machine for writing, and create objects necessary for + running a VM in this process. + + + + + + Session type. This enumeration represents possible values of the + attribute. + + + + Null value (never used by the API). + + + + Session has acquired an exclusive write lock on a machine + using . + + + + + Session has launched a VM process using + + + + + + Session has obtained a link to another session using + + + + + + + + Device type. + + + + Null value, may also mean "no device" (not allowed for + ). + + + + Floppy device. + + + CD/DVD-ROM device. + + + Hard disk device. + + + Network device. + + + USB device. + + + Shared folder device. + + + Graphics device 3D activity. + + + End of valid device types (exclusive). Used for invalid validation and such. + + + + + + Device activity for . + + + + + + + + + + + Host-Guest clipboard interchange mode. + + + + + + + + + + + Drag and drop interchange mode. + + + + + + + + + + + Scope of the operation. + + A generic enumeration used in various methods to define the action or + argument scope. + + + + + + + + + + BIOS boot menu mode. + + + + + + + + + + BIOS APIC initialization mode. If the hardware does not support the + mode then the code falls back to a lower mode. + + + + + + + + + + CPU features. + + + + + + + + + + + + + + Firmware type. + + + BIOS Firmware. + + + EFI Firmware, bitness detected basing on OS type. + + + EFI firmware, 32-bit. + + + EFI firmware, 64-bit. + + + EFI firmware, combined 32 and 64-bit. + + + + + + Type of pointing device used in a virtual machine. + + + No mouse. + + + PS/2 auxiliary device, a.k.a. mouse. + + + USB mouse (relative pointer). + + + + USB tablet (absolute pointer). Also enables a relative USB mouse in + addition. + + + + + Combined device, working as PS/2 or USB mouse, depending on guest + behavior. Using this device can have negative performance implications. + + + + + USB multi-touch device, just touchscreen. It is a specific mode of the + USB tablet and also enables the mouse device. + + + + + USB multi-touch device, touchscreen plus touchpad. It also enables the + mouse device. + + + + + + + Type of keyboard device used in a virtual machine. + + + No keyboard. + + + PS/2 keyboard. + + + USB keyboard. + + + Combined device, working as PS/2 or USB keyboard, depending on guest behavior. + Using of such device can have negative performance implications. + + + + + + Format of a bitmap. Generic values for formats used by + the source bitmap, the screen shot or image update APIs. + + + + + Unknown buffer format (the user may not assume any particular format of + the buffer). + + + + + Generic BGR format without alpha channel. + Pixel layout depends on the number of bits per pixel: +
    +
  • + 32 - bits 31:24 undefined, bits 23:16 R, bits 15:8 G, bits 7:0 B. +
    • + +
  • + 16 - bits 15:11 R, bits 10:5 G, bits 4:0 B. +
    • +
+ + + + + 4 bytes per pixel: B, G, R, 0. + + + + + 4 bytes per pixel: B, G, R, A. + + + + + 4 bytes per pixel: R, G, B, A. + + + + + PNG image. + + + + + JPEG image. + + + + + + + The type of the disk partition. + + + + + + + + + + + Empty partition entry + FAT12 if partition size less than 65536 sectors + FAT16 if partition size less than 65536 sectors + FAT12 or FAT16 if partition size greater or equal than 65536 sectors + NT and OS/2 installable file system, e.g. NTFS, exFAT, HPFS. + The FAT32 with CHS addressing. + The FAT32 with LBA addressing. + The FAT16 with LBA addressing. + The extended partition with LBA addressing. + Windows Recovery Environment (RE) partition (hidden NTFS partition). + The linux swap partition (old versions). + The linux native partition (old versions). + The BSD slice. + The linux swap partition. + The linux native partition. + The linux extended partition. + The linux LVM partition. + The BSD slice. + The Apple UFS partition. + The Apple HFS partition. + The Apple HFS partition. + The GPT protective MBR partition. + The EFI system partition. + + + Unknown partition type. + + + MBR partition scheme. + Intel Fast Flash (iFFS) partition. + Sony boot partition. + Lenovo boot partition. + + Microsoft Reserved Partition (MSR). + Windows Basic data partition + Windows Logical Disk Manager (LDM) metadata partition. + Windows Logical Disk Manager data partition. + Windows Recovery Environment. + Windows Storage Spaces partition. + Windows Storage Replica partition. + IBM General Parallel File System (GPFS) partition. + + Linux filesystem data. + Linux RAID partition. + Linux root partition for x86. + Linux root partition for AMD64. + Linux root partition for ARM32. + Linux root partition for ARM64 / AArch64. + Linux /home partition. + Linux /srv partition. + Linux plain dm-crypt partition. + Linux unitified key setup (LUKS) partition. + Linux reserved partition. + + FreeBSD boot partition. + FreeBSD data partition. + FreeBSD swap partition. + FreeBSD unix file system (UFS) partition. + FreeBSD Vinum volume manager partition. + FreeBSD ZFS partition. + Unknown FreeBSD partition. + + Apple hierarchical file system plus (HFS+) partition. + Apple APFS/FileFault container partition. + Apple RAID partition. + Apple RAID partition, offline. + Apple boot partition. + Apple label. + Apple TV recovery partition. + Apple Core Storage Containe. + SoftRAID status. + SoftRAID scratch. + SoftRAID volume. + SoftRAID cache. + Unknown Apple partition. + + Solaris boot partition. + Solaris root partition. + Solaris swap partition. + Solaris backup partition. + Solaris /usr partition. + Solaris /var partition. + Solaris /home partition. + Solaris alternate sector. + Solaris reserved partition. + Unknown Solaris partition. + + NetBSD swap partition. + NetBSD fast file system (FFS) partition. + NetBSD log structured file system (LFS) partition. + NetBSD RAID partition. + NetBSD concatenated partition. + NetBSD encrypted partition. + Unknown NetBSD partition. + + Chrome OS kernel partition. + Chrome OS root file system partition. + Chrome OS partition reserved for future. + + Container Linux /usr partition. + Container Linux resizable root filesystem partition. + Container Linux OEM customization partition. + Container Linux root filesystem on RAID partition. + + Haiku BFS + + MidnightBSD boot partition. + MidnightBSD data partition. + MidnightBSD swap partition. + MidnightBSD unix file system (UFS) partition. + MidnightBSD Vinum volume manager partition. + MidnightBSD ZFS partition. + Unknown MidnightBSD partition. + + OpenBSD data partition. + + QNX power-safe file system partition. + + Plan 9 partition. + + VMWare ESX coredump partition. + VMWare ESX virtual machine file system (VMFS) partition. + VMWare ESX reserved partition. + Unknown VMWare partition. + + Android x86 bootloader partition. + Android x86 bootloader2 partition. + Android x86 boot partition. + Android x86 recovery partition. + Android x86 misc partition. + Android x86 metadata partition. + Android x86 system partition. + Android x86 cache partition. + Android x86 data partition. + Android x86 persistent data partition. + Android x86 vendor partition. + Android x86 config partition. + Android x86 factory partition. + Android x86 alternative factory partition. + Android x86 fastboot partition. + Android x86 OEM partition. + + Android ARM meta partition. + Android ARM EXT partition. + + Open Network Install Environment (ONIE) boot partition. + Open Network Install Environment (ONIE) config partition. + + PowerPC PReP boot partition. + + freedesktop.org shared boot loader configuration partition. + + Ceph block partition. + Ceph block DB partition. + Ceph dm-crypt block DB partition. + Ceph dm-crypt Linux unitified key setup (LUKS) block DB partition. + Ceph dm-crypt block partition. + Ceph dm-crypt Linux unitified key setup (LUKS) block partition. + Ceph block write-ahead log partition. + Ceph dm-crypt block write-ahead log partition. + Ceph dm-crypt Linux unitified key setup (LUKS) block write-ahead log partition. + Ceph disk in creation partition. + Ceph dm-crypt disk in creation partition. + Ceph Journal partition. + Ceph dm-crypt journal partition. + Ceph dm-crypt Linux unitified key setup (LUKS) journal partition. + Ceph Lockbox for dm-crypt keys partition. + Ceph multipath block 1 partition. + Ceph multipath block 2 partition. + Ceph multipath block DB partition. + Ceph multipath block write-ahead log partition. + Ceph multipath journal partition. + Ceph multipath object storage deamon (OSD) partition. + Ceph object storage deamon (OSD) partition. + Ceph dm-crypt object storage deamon (OSD) partition. + Ceph dm-crypt Linux unitified key setup (LUKS) object storage deamon (OSD) partition. + + + + + + + + The IVirtualBoxErrorInfo interface represents extended error information. + + Extended error information can be set by VirtualBox components after + unsuccessful or partially successful method invocation. This information + can be retrieved by the calling party as an IVirtualBoxErrorInfo object + and then shown to the client in addition to the plain 32-bit result code. + + In MS COM, this interface extends the IErrorInfo interface, + in XPCOM, it extends the nsIException interface. In both cases, + it provides a set of common attributes to retrieve error + information. + + Sometimes invocation of some component's method may involve methods of + other components that may also fail (independently of this method's + failure), or a series of non-fatal errors may precede a fatal error that + causes method failure. In cases like that, it may be desirable to preserve + information about all errors happened during method invocation and deliver + it to the caller. The attribute is intended + specifically for this purpose and allows to represent a chain of errors + through a single IVirtualBoxErrorInfo object set after method invocation. + + errors are stored to a chain in the reverse order, i.e. the + initial error object you query right after method invocation is the last + error set by the callee, the object it points to in the @a next attribute + is the previous error and so on, up to the first error (which is the last + in the chain). + + + + + Result code of the error. + Usually, it will be the same as the result code returned + by the method that provided this error information, but not + always. For example, on Win32, CoCreateInstance() will most + likely return E_NOINTERFACE upon unsuccessful component + instantiation attempt, but not the value the component factory + returned. Value is typed 'long', not 'result', + to make interface usable from scripting languages. + + In MS COM, there is no equivalent. + In XPCOM, it is the same as nsIException::result. + + + + + + + Optional result data of this error. This will vary depending on the + actual error usage. By default this attribute is not being used. + + + + + + UUID of the interface that defined the error. + + In MS COM, it is the same as IErrorInfo::GetGUID, except for the + data type. + In XPCOM, there is no equivalent. + + + + + + + Name of the component that generated the error. + + In MS COM, it is the same as IErrorInfo::GetSource. + In XPCOM, there is no equivalent. + + + + + + + Text description of the error. + + In MS COM, it is the same as IErrorInfo::GetDescription. + In XPCOM, it is the same as nsIException::message. + + + + + + + Next error object if there is any, or @c null otherwise. + + In MS COM, there is no equivalent. + In XPCOM, it is the same as nsIException::inner. + + + + + + + + + + + + + TBD: the idea, technically we can start any number of the NAT networks, + but we should expect that at some point we will get collisions because of + port-forwanding rules. so perhaps we should support only single instance of NAT + network. + + + + + + This is CIDR IPv4 string. Specifying it user defines IPv4 addresses + of gateway (low address + 1) and DHCP server (= low address + 2). + Note: If there are defined IPv4 port-forward rules update of network + will be ignored (because new assignment could break existing rules). + + + + + This attribute is read-only. It's recalculated on changing + network attribute (low address of network + 1). + + + + + This attribute define whether gateway will support IPv6 or not. + + + + + This a CIDR IPv6 defining prefix for link-local addresses + autoconfiguration within network. Note: ignored if attribute + IPv6Enabled is false. + + + + + + + Array of NAT port-forwarding rules in string representation, + in the following format: + "name:protocolid:[host ip]:host port:[guest ip]:guest port". + + + + Array of mappings (address,offset),e.g. ("127.0.1.1=4") maps 127.0.1.1 to networkid + 4. + + + + + + + + + + + + + Offset in ipv6 network from network id for address mapped into loopback6 interface of the host. + + + + + Array of NAT port-forwarding rules in string representation, in the + following format: "name:protocolid:[host ip]:host port:[guest ip]:guest port". + + + + + + + + Protocol handled with the rule. + + + IP of the host interface to which the rule should apply. + An empty ip address is acceptable, in which case the NAT engine + binds the handling socket to any interface. + + + + The port number to listen on. + + + The IP address of the guest which the NAT engine will forward + matching packets to. An empty IP address is not acceptable. + + + The port number to forward. + + + + + + + + + + + + + + + + + + + + + + + TBD: User-friendly, descriptive name of cloud subnet. For example, domain + names of subnet and vcn, separated by dot. + + + + + + Cloud provider short name. + + + + + Cloud profile name. + + + + + Cloud network id. + + + + + + + + + + + TBD: User-friendly, descriptive name of host-only network. For example, + "Host-only network 192.168.56.0". + + + + + + specifies network mask + + + + + + host IP address, which usually is the lower IP address of DHCP range. + + + + + + specifies from IP address in DHCP address range + + + + + + specifies to IP address in DHCP address range + + + + + + Host-only network ID. + + + + + + + + + IPv4 netmask. Set to by default. + UTC offset in seconds (32-bit decimal value). + Space separated list of IPv4 router addresses. + Space separated list of IPv4 time server (RFC 868) addresses. + Space separated list of IPv4 name server (IEN 116) addresses. + Space separated list of IPv4 DNS addresses. + Space separated list of IPv4 log server addresses. + Space separated list of IPv4 cookie server (RFC 865) addresses. + Space separated list of IPv4 line printer server (RFC 1179) addresses. + Space separated list of IPv4 imagen impress server addresses. + Space separated list of IPv4 resource location (RFC 887) addresses. + The client name. See RFC 1035 for character limits. + Number of 512 byte blocks making up the boot file (16-bit decimal value). + Client core file. + Domain name for the client. + IPv4 address of the swap server that the client should use. + The path to the root disk the client should use. + Path to a file containing additional DHCP options (RFC2123). + Whether IP forwarding should be enabled by the client (boolean). + Whether non-local datagrams should be forwarded by the client (boolean) + List of IPv4 addresses and masks paris controlling non-local source routing. + The maximum datagram size the client should reassemble (16-bit decimal value). + The default time-to-leave on outgoing (IP) datagrams (8-bit decimal value). + RFC1191 path MTU discovery timeout value in seconds (32-bit decimal value). + RFC1191 path MTU discovery size table, sorted in ascending order (list of 16-bit decimal values). + The MTU size for the interface (16-bit decimal value). + Indicates whether the MTU size is the same for all subnets (boolean). + Broadcast address (RFC1122) for the client to use (IPv4 address). + Whether to perform subnet mask discovery via ICMP (boolean). + Whether to respond to subnet mask requests via ICMP (boolean). + Whether to perform router discovery (RFC1256) (boolean). + Where to send router solicitation requests (RFC1256) (IPv4 address). + List of network and router address pairs addresses. + Whether to negotiate the use of trailers for ARP (RTF893) (boolean). + The timeout in seconds for ARP cache entries (32-bit decimal value). + Whether to use IEEE 802.3 (RTF1042) rather than of v2 (RFC894) ethernet encapsulation (boolean). + Default time-to-live for TCP sends (non-zero 8-bit decimal value). + The interface in seconds between TCP keepalive messages (32-bit decimal value). + Whether to include a byte of garbage in TCP keepalive messages for backward compatibility (boolean). + The NIS (Sun Network Information Services) domain name (string). + Space separated list of IPv4 NIS server addresses. + Space separated list of IPv4 NTP (RFC1035) server addresses. + Vendor specific information. Only accessible using . + Space separated list of IPv4 NetBIOS name server (NBNS) addresses (RFC1001,RFC1002). + Space separated list of IPv4 NetBIOS datagram distribution server (NBDD) addresses (RFC1001,RFC1002). + NetBIOS node type (RFC1001,RFC1002): 1=B-node, 2=P-node, 4=M-node, and 8=H-node (8-bit decimal value). + NetBIOS scope (RFC1001,RFC1002). Only accessible using . + Space separated list of IPv4 X windows font server addresses. + Space separated list of IPv4 X windows display manager addresses. + + Netware IP domain name (RFC2242) (string). + Netware IP information (RFC2242). Only accessible using . + The NIS+ domain name (string). + Space separated list of IPv4 NIS+ server addresses. + TFTP server name (string). + Bootfile name (string). + Space separated list of IPv4 mobile IP agent addresses. + Space separated list of IPv4 simple mail transport protocol (SMPT) server addresses. + Space separated list of IPv4 post office protocol 3 (POP3) server addresses. + Space separated list of IPv4 network news transport protocol (NTTP) server addresses. + Space separated list of default IPv4 world wide web (WWW) server addresses. + Space separated list of default IPv4 finger server addresses. + Space separated list of default IPv4 internet relay chat (IRC) server addresses. + Space separated list of IPv4 StreetTalk server addresses. + Space separated list of IPv4 StreetTalk directory assistance (STDA) server addresses. + + Addresses of one or more service location protocol (SLP) directory agent, and an indicator of whether their use is mandatory. Only accessible using . + List of service scopes for the service location protocol (SLP) and whether using the list is mandator. Only accessible using . + + Domain search list, see RFC3397 and section 4.1.4 in RFC1035 for encoding. Only accessible using . + + + + + Value format is specific to the option and generally user friendly. + + + Value format is a series of hex bytes (09314f3200fe), + optionally colons as byte separators (9:31:4f:32::fe). + + + + + + + + + + + + MAC address + MAC address wildcard pattern. + Vendor class ID + Vendor class ID wildcard pattern. + User class ID + User class ID wildcard pattern. + + + + + The IDHCPServer interface represents the VirtualBox DHCP server configuration. + + To enumerate all the DHCP servers on the host, use the + attribute. + + + + + + specifies if the DHCP server is enabled + + + + + + specifies server IP + + + + + + specifies server network mask + + + + + + specifies internal network name the server is used for + + + + + + specifies from IP address in server address range + + + + + + specifies to IP address in server address range + + + + + Global configuration that applies to all clients. + + + + Configuration groups that applies to selected clients, selection is flexible. + + + + Individual NIC configurations either by MAC address or VM + NIC number. + + + + + + + configures the server + + invalid configuration supplied + + + + + server IP address + + + + + server network mask + + + + + server From IP address for address range + + + + + server To IP address for address range + + + + + + + + Starts DHCP server process. + + Failed to start the process. + + + + + Name of internal network trunk. + + + + + Type of internal network trunk. + + + + + + + + Stops DHCP server process. + + Failed to stop the process. + + + + + + + + Restart running DHCP server process. + + Failed to restart the process. + + + + + + + Queries the persistent lease database by MAC address. + + This is handy if the host wants to connect to a server running inside + a VM on a host only network. + + If MAC address not in the database. + If not able to read the lease database file. + + + The MAC address to look up. + + + Reserved, MBZ. + + + The assigned address. + + + The lease state. + + + Timestamp of when the lease was issued, in seconds since 1970-01-01 UTC. + + + Timestamp of when the lease expires/expired, in seconds since 1970-01-01 UTC. + + + + + + + Gets or adds a configuration. + + + The kind of configuration being sought or added. + + + + Meaning depends on the @a scope: + - Ignored when the @a scope is . + - A VM name or UUID for . + - A MAC address for . + - A group name for . + + + + The NIC slot when @a scope is set to , + must be zero for all other scope values. + + + + + Set to @c TRUE if the configuration should be added if not found. + If set to @c FALSE the method will fail with VBOX_E_OBJECT_NOT_FOUND. + + + + The requested configuration. + + + + + + + + + + + The DHCP server has several configuration levels: global, group and + individual MAC. This interface implements the settings common to + each level. + + + + + Indicates the kind of config this is (mostly for IDHCPIndividualConfig). + + + + + The minimum lease time in seconds, ignored if zero. + + + The default lease time in seconds, ignored if zero. + + + The maximum lease time in seconds, ignored if zero. + + + + List of DHCP options which should be forced upon the clients in this + config scope when they are available, whether the clients asks for them + or not. + + + + List of DHCP options which should not be sent to the clients in + this config scope. This is intended for cases where one client or a + group of clients shouldn't see one or more (typically global) options. + + + + + Sets a DHCP option. + + + The DHCP option. + + + The value encoding. + + + The DHCP option value. The exact format depends on the DHCP + @a option value and @a encoding, see see + for the format. + + + + + + Removes the given DHCP option. + + + + + + Removes all the options. + + One exception here is the DhcpOpt_SubnetMask option in the global scope + that is linked to the attribute + and therefore cannot be removed. + + + + + Gets the value of a single DHCP option. + + The DHCP option being sought. + + + The value encoding. + + + The value of the requested DHCP option. The exact format depends on + the DHCP @a option value and the @a encoding, see + for the format. + + + + + + Gets all DHCP options and their values + + Array containing the DHCP option numbers. + + + Array of value encodings that runs parallel to @a options. + + + Array of values that runs parallel to @a options and @a encodings. The + format depends on both of those. + + + + + + + Remove this group or individual configuration. + Will of course not work on global configurations. + + + + + + + + The global DHCP server configuration, see . + + + + + + + Whether this is an inclusive or exclusive group membership condition + + + Defines how the is interpreted. + + + The condition value. + + + Remove this condition from the group. + + + + + + A configuration that applies to a group of NICs. + + + + The group name. + + + + + Group membership conditions. + + Add new conditions by calling + and use to remove. + + + + + Adds a new condition. + + + + + + + + Removes all conditions. + + + + + + + Configuration for a single NIC, either given directly by MAC address or by + VM + adaptor slot number. + + + + + The MAC address. If a config, this + will be queried via the VM ID. + + + + + + The virtual machine ID if a config, + null UUID for . + + + + + The NIC slot number of the VM if a config. + + + + Fixed IPv4 address assignment, dynamic if empty. + + + + + + + The IVirtualBox interface represents the main interface exposed by the + product that provides virtual machine management. + + An instance of IVirtualBox is required for the product to do anything + useful. Even though the interface does not expose this, internally, + IVirtualBox is implemented as a singleton and actually lives in the + process of the VirtualBox server (VBoxSVC.exe). This makes sure that + IVirtualBox can track the state of all virtual machines on a particular + host, regardless of which frontend started them. + + To enumerate all the virtual machines on the host, use the + attribute. + + Error information handling is a bit special with IVirtualBox: creating + an instance will always succeed. The return of the actual error + code/information is postponed to any attribute or method call. The + reason for this is that COM likes to mutilate the error code and lose + the detailed error information returned by instance creation. + + + + + A string representing the version number of the product. The + format is 3 integer numbers divided by dots (e.g. 1.0.1). The + last number represents the build number and will frequently change. + + This may be followed by a _ALPHA[0-9]*, _BETA[0-9]* or _RC[0-9]* tag + in prerelease builds. Non-Oracle builds may (/shall) also have a + publisher tag, at the end. The publisher tag starts with an underscore + just like the prerelease build type tag. + + + + + + A string representing the version number of the product, + without the publisher information (but still with other tags). + See . + + + + + + The internal build revision number of the product. + + + + + + A string representing the package type of this product. The + format is OS_ARCH_DIST where OS is either WINDOWS, LINUX, + SOLARIS, DARWIN. ARCH is either 32BITS or 64BITS. DIST + is either GENERIC, UBUNTU_606, UBUNTU_710, or something like + this. + + + + + + A string representing the VirtualBox API version number. The format is + 2 integer numbers divided by an underscore (e.g. 1_0). After the + first public release of packages with a particular API version the + API will not be changed in an incompatible way. Note that this + guarantee does not apply to development builds, and also there is no + guarantee that this version is identical to the first two integer + numbers of the package version. + + + + + + This is mainly intended for the VBox Validation Kit so it can fluently + deal with incompatible API changes and new functionality during + development (i.e. on trunk). + + The high 7 bits (62:56) is the major version number, the next 8 bits + (55:48) are the minor version number, the next 8 bits (47:40) are the + build number, and the rest (39:0) is the API revision number. + + The API revision number is manually increased on trunk when making + incompatible changes that the validation kit or others needs to be able + to detect and cope with dynamically. It can also be used to indicate + the presence of new features on both trunk and branches. + + + + + + Full path to the directory where the global settings file, + VirtualBox.xml, is stored. + + In this version of VirtualBox, the value of this property is + always <user_dir>/.VirtualBox (where + <user_dir> is the path to the user directory, + as determined by the host OS), and cannot be changed. + + This path is also used as the base to resolve relative paths in + places where relative paths are allowed (unless otherwise + expressly indicated). + + + + + + Full name of the global settings file. + The value of this property corresponds to the value of + plus /VirtualBox.xml. + + + + + Associated host object. + + + + Associated system information object. + + + + + Array of machine objects registered within this VirtualBox instance. + + + + + + Array of all machine group names which are used by the machines which + are accessible. Each group is only listed once, however they are listed + in no particular order and there is no guarantee that there are no gaps + in the group hierarchy (i.e. "/", "/group/subgroup" + is a valid result). + + + + + + Array of medium objects known to this VirtualBox installation. + + This array contains only base media. All differencing + media of the given base medium can be enumerated using + . + + + + + + Array of CD/DVD image objects currently in use by this VirtualBox instance. + + + + + + Array of floppy image objects currently in use by this VirtualBox instance. + + + + + + + + + + Collection of global shared folders. Global shared folders are + available to all virtual machines. + + New shared folders are added to the collection using + . Existing shared folders can be + removed using . + + + In the current version of the product, global shared folders are not + implemented and therefore this collection is always empty. + + + + + + + Associated performance collector object. + + + + + + DHCP servers. + + + + + + + + Event source for VirtualBox events. + + + + + + The extension pack manager. + + + + + + + Names of all internal networks. + + + + + + Names of all host-only networks. + + + + + + Names of all generic network drivers. + + + + + + Names of all configured cloud networks. + + + + + + The cloud provider manager (singleton). + + + + + + + Returns a recommended full path of the settings file name for a new virtual + machine. + + This API serves two purposes: + +
    +
  • It gets called by if @c null or + empty string (which is recommended) is specified for the + @a settingsFile argument there, which means that API should use + a recommended default file name.
    • + +
  • It can be called manually by a client software before creating a machine, + e.g. if that client wants to pre-create the machine directory to create + virtual hard disks in that directory together with the new machine + settings file. In that case, the file name should be stripped from the + full settings file path returned by this function to obtain the + machine directory.
    • +
+ + See and for more + details about the machine name. + + @a groupName defines which additional subdirectory levels should be + included. It must be either a valid group name or @c null or empty + string which designates that the machine will not be related to a + machine group. + + If @a baseFolder is a @c null or empty string (which is recommended), the + default machine settings folder + (see ) will be used as + a base folder for the created machine, resulting in a file name like + "/home/user/VirtualBox VMs/name/name.vbox". Otherwise the given base folder + will be used. + + This method does not access the host disks. In particular, it does not check + for whether a machine with this name already exists. + + + Suggested machine name. + + + Machine group name for the new machine or machine group. It is + used to determine the right subdirectory. + + + Machine creation flags, see (optional). + + + Base machine folder (optional). + + + Fully qualified path where the machine would be created. + + + + + + + Creates a new virtual machine by creating a machine settings file at + the given location. + + VirtualBox machine settings files use a custom XML dialect. Starting + with VirtualBox 4.0, a ".vbox" extension is recommended, but not enforced, + and machine files can be created at arbitrary locations. + + However, it is recommended that machines are created in the default + machine folder (e.g. "/home/user/VirtualBox VMs/name/name.vbox"; see + ). If you specify + @c null or empty string (which is recommended) for the @a settingsFile + argument, is called automatically + to have such a recommended name composed based on the machine name + given in the @a name argument and the primary group. + + If the resulting settings file already exists, this method will fail, + unless the forceOverwrite flag is set. + + The new machine is created unregistered, with the initial configuration + set according to the specified guest OS type. A typical sequence of + actions to create a new virtual machine is as follows: + +
    +
  1. + Call this method to have a new machine created. The returned machine + object will be "mutable" allowing to change any machine property. +
    2. + +
  2. + Configure the machine using the appropriate attributes and methods. +
    3. + +
  3. + Call to write the settings + to the machine's XML settings file. The configuration of the newly + created machine will not be saved to disk until this method is + called. +
    4. + +
  4. + Call to add the machine to the list + of machines known to VirtualBox. +
    5. +
+ + The specified guest OS type identifier must match an ID of one of known + guest OS types listed in the + array. + + + will return + @c false for the created machine, until any of machine settings + are changed. + + + + There is no way to change the name of the settings file or + subfolder of the created machine directly. + + + + @a osTypeId is invalid. + + + Resulting settings file name is invalid or the settings file already + exists or could not be created due to an I/O error. + + + @a name is empty or @c null. + + + + + Fully qualified path where the settings file should be created, + empty string or @c null for a default folder and file based on the + @a name argument and the primary group. + (see ). + + + Machine name. + + + Array of group names. @c null or an empty array have the same + meaning as an array with just the empty string or "/", i.e. + create a machine without group association. + + + Guest OS Type ID. + + + + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. The following ones are recognized: + forceOverwrite=1 to overwrite an existing machine settings + file, UUID=<uuid> to specify a machine UUID and + directoryIncludesUUID=1 to switch to a special VM directory + naming scheme which should not be used unless necessary. + + + + + The cipher. It should be empty if encryption is not required. + + + + + The password id. It should be empty if encryption is not required. + + + + + The password. It should be empty if encryption is not required. + + + + Created machine object. + + + + + + + Opens a virtual machine from the existing settings file. + The opened machine remains unregistered until you call + . + + The specified settings file name must be fully qualified. + The file must exist and be a valid machine XML settings file + whose contents will be used to construct the machine object. + + + If the VM is encrypted and password is incorrect + the method returns success allowing you to register the + encrypted machine but it remains in inaccessible state. You + can check and + properties to determine the + real machine state. + + + + will return + @c false for the opened machine, until any of machine settings + are changed. + + + + Settings file name invalid, not found or sharing violation. + + + + + Name of the machine settings file. + + + + + The password. If the machine is not encrypted the parameter is + ignored. + + + + Opened machine object. + + + + + + + + Registers the machine previously created using + or opened using + within this VirtualBox installation. After + successful method invocation, the + event is fired. + + + This method implicitly calls + to save all current machine settings before registering it. + + + + No matching virtual machine found. + + + Virtual machine was not created within this VirtualBox instance. + + + + + + + + + + Attempts to find a virtual machine given its name or UUID. + + Inaccessible machines cannot be found by name, only by UUID, because their name + cannot safely be determined. + + + Could not find registered machine matching @a nameOrId. + + + + + What to search for. This can either be the UUID or the name of a virtual machine. + + + Machine object, if found. + + + + + + + Gets all machine references which are in one of the specified groups. + + + What groups to match. The usual group list rules apply, i.e. + passing an empty list will match VMs in the toplevel group, likewise + the empty string. + + + All machines which matched. + + + + + + + Gets the state of several machines in a single operation. + + + Array with the machine references. + + + Machine states, corresponding to the machines. + + + + + + + Creates a new appliance object, which represents an appliance in the Open Virtual Machine + Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export + machines as an OVF appliance; see the documentation for for details. + + + New appliance. + + + + + + + Creates a new guest installation object. This can be used to + analyze an installation ISO to create and configure a new machine for it to be installed + on. It can also be used to (re)install an existing machine. + + + New unattended object. + + + + + + + Creates a new base medium object that will use the given storage + format and location for medium data. + + The actual storage unit is not created by this method. In order to + do it, and before you are able to attach the created medium to + virtual machines, you must call one of the following methods to + allocate a format-specific storage unit at the specified location: +
    +
    • +
    • +
+ + Some medium attributes, such as , may + remain uninitialized until the medium storage unit is successfully + created by one of the above methods. + + Depending on the given device type, the file at the storage location + must be in one of the media formats understood by VirtualBox: + +
    +
  • With a "HardDisk" device type, the file must be a hard disk image + in one of the formats supported by VirtualBox (see + ). + After the storage unit is successfully created and this method succeeds, + if the medium is a base medium, it + will be added to the array attribute.
    • +
  • With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. + After this method succeeds, the medium will be added to the + array attribute.
    • +
  • With a "Floppy" device type, the file must be an RAW floppy image. + After this method succeeds, the medium will be added to the + array attribute.
    • +
+ + The list of all storage formats supported by this VirtualBox + installation can be obtained using + . If the @a format + attribute is empty or @c null then the default storage format + specified by will + be used for disks r creating a storage unit of the medium. + + Note that the format of the location string is storage format specific. + See and IMedium for more details. + + + @a format identifier is invalid. See + . + + + @a location is a not valid file name (for file-based formats only). + + + + + Identifier of the storage format to use for the new medium. + + + + + Location of the storage unit for the new medium. + + + + Whether to open the image in read/write or read-only mode. For + a "DVD" device type, this is ignored and read-only mode is always assumed. + + + + Must be one of "HardDisk", "DVD" or "Floppy". + + + + Created medium object. + + + + + + + Finds existing media or opens a medium from an existing storage location. + + Once a medium has been opened, it can be passed to other VirtualBox + methods, in particular to . + + Depending on the given device type, the file at the storage location + must be in one of the media formats understood by VirtualBox: + +
    +
  • With a "HardDisk" device type, the file must be a hard disk image + in one of the formats supported by VirtualBox (see + ). + After this method succeeds, if the medium is a base medium, it + will be added to the array attribute.
    • +
  • With a "DVD" device type, the file must be an ISO 9960 CD/DVD image. + After this method succeeds, the medium will be added to the + array attribute.
    • +
  • With a "Floppy" device type, the file must be an RAW floppy image. + After this method succeeds, the medium will be added to the + array attribute.
    • +
+ + After having been opened, the medium can be re-found by this method + and can be attached to virtual machines. See for + more details. + + The UUID of the newly opened medium will either be retrieved from the + storage location, if the format supports it (e.g. for hard disk images), + or a new UUID will be randomly generated (e.g. for ISO and RAW files). + If for some reason you need to change the medium's UUID, use + . + + If a differencing hard disk medium is to be opened by this method, the + operation will succeed only if its parent medium and all ancestors, + if any, are already known to this VirtualBox installation (for example, + were opened by this method before). + + This method attempts to guess the storage format of the specified medium + by reading medium data at the specified location. + + If @a accessMode is ReadWrite (which it should be for hard disks and floppies), + the image is opened for read/write access and must have according permissions, + as VirtualBox may actually write status information into the disk's metadata + sections. + + Note that write access is required for all typical hard disk usage in VirtualBox, + since VirtualBox may need to write metadata such as a UUID into the image. + The only exception is opening a source image temporarily for copying and + cloning (see when the image will be closed + again soon. + + The format of the location string is storage format specific. See + and IMedium for more details. + + + Invalid medium storage file location or could not find the medium + at the specified location. + + + Could not get medium storage format. + + + Invalid medium storage format. + + + Medium has already been added to a media registry. + + + + + Location of the storage unit that contains medium data in one of + the supported storage formats. + + + + + Must be one of "HardDisk", "DVD" or "Floppy". + + + + Whether to open the image in read/write or read-only mode. For + a "DVD" device type, this is ignored and read-only mode is always assumed. + + + Allows the caller to request a completely new medium UUID for + the image which is to be opened. Useful if one intends to open an exact + copy of a previously opened image, as this would normally fail due to + the duplicate UUID. + + + Opened medium object. + + + + + + + Returns an object describing the specified guest OS type. + + The requested guest OS type is specified using a string which is a + mnemonic identifier of the guest operating system, such as + "win31" or "ubuntu". The guest OS type ID of a + particular virtual machine can be read or set using the + attribute. + + The collection contains all + available guest OS type objects. Each object has an + attribute which contains an identifier of + the guest OS this object describes. + + While this function returns an error for unknown guest OS types, they + can be still used without serious problems (if one accepts the fact + that there is no default VM config information). + + + @a id is not a valid Guest OS type. + + + + + Guest OS type ID string. + + + Guest OS type object. + + + + + + + Creates a new global shared folder by associating the given logical + name with the given host path, adds it to the collection of shared + folders and starts sharing it. Refer to the description of + to read more about logical names. + + In the current implementation, this operation is not + implemented. + + + + Unique logical name of the shared folder. + + + Full path to the shared folder in the host file system. + + + Whether the share is writable or readonly + + + Whether the share gets automatically mounted by the guest + or not. + + + Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + + + + + + + + Removes the global shared folder with the given name previously + created by from the collection of + shared folders and stops sharing it. + + In the current implementation, this operation is not + implemented. + + + + Logical name of the shared folder to remove. + + + + + + + Returns an array representing the global extra data keys which currently + have values defined. + + + Array of extra data keys. + + + + + + + Returns associated global extra data. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + + Settings file not accessible. + + + Could not parse the settings file. + + + + + Name of the data key to get. + + + Value of the requested data key. + + + + + + + Sets associated global extra data. + + If you pass @c null or an empty string as a key @a value, the given + @a key will be deleted. + + + Key must contain printable (non-control) UTF-8 characters only. + + + Before performing the actual data change, this method will ask all + registered event listeners using the + + notification for a permission. If one of the listeners refuses the + new value, the change will not be performed. + + + On success, the + notification + is called to inform all registered listeners about a successful data + change. + + + + Settings file not accessible. + + + Could not parse the settings file. + + + Modification request refused. + + + Key contains invalid characters. + + + + + Name of the data key to set. + + + Value to assign to the key. + + + + + + Unlocks the secret data by passing the unlock password to the + server. The server will cache the password for that machine. + + + Virtual machine is not mutable. + + + + + + The cipher key. + + + + + + + + + + Creates a DHCP server settings to be used for the given internal network name + + Host network interface @a name already exists. + + + + server name + + + DHCP server settings + + + + + + + Searches a DHCP server settings to be used for the given internal network name + + Host network interface @a name already exists. + + + + + server name + + + DHCP server settings + + + + + + + + + Removes the DHCP server settings + + Host network interface @a name already exists. + + + + DHCP server settings to be removed + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Searches through all host networks for one with + the given GUID. + + The method returns an error if the given GUID does not + correspond to any host network. + + + + GUID of the host-only network to search for. + + + Found host-only network object. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Check if this VirtualBox installation has a firmware + of the given type available, either system-wide or per-user. + Optionally, this may return a hint where this firmware can be + downloaded from. + + + + Type of firmware to check. + + + + Expected version number, usually empty string (presently ignored). + + + + + Suggested URL to download this firmware from. + + + + + + Filename of firmware, only valid if result == TRUE. + + + + + If firmware of this type and version is available. + + + + + + + Searches through all progress objects known to VBoxSVC for an + instance with the given GUID. + + The method returns an error if the given GUID does not + correspond to any currently known progress object. + + + + GUID of the progress object to search for. + + + Found progress object. + + + + + + + + + + Virtual file systems supported by VFSExplorer. + + + + + + + + + + + The VFSExplorer interface unifies access to different file system + types. This includes local file systems as well remote file systems like + S3. For a list of supported types see . + An instance of this is returned by . + + + + Returns the current path in the virtual file system. + + + + Returns the file system type which is currently in use. + + + + Updates the internal list of files/directories from the + current directory level. Use to get the full list + after a call to this method. + + + Progress object to track the operation completion. + + + + + Change the current directory level. + + + The name of the directory to go in. + + + + Progress object to track the operation completion. + + + + + Go one directory upwards from the current directory level. + + + Progress object to track the operation completion. + + + + + Returns a list of files/directories after a call to . The user is responsible for keeping this internal + list up do date. + + + The list of names for the entries. + + + + The list of types for the entries. + + + + The list of sizes (in bytes) for the entries. + + + + The list of file modes (in octal form) for the entries. + + + + + Checks if the given file list exists in the current directory + level. + + + The names to check. + + + + The names which exist. + + + + + Deletes the given files in the current directory level. + + + The names to remove. + + + + Progress object to track the operation completion. + + + + + + + + + Import options, used with . + + + + Don't generate new MAC addresses of the attached network adapters. + + + Don't generate new MAC addresses of the attached network adapters when they are using NAT. + + + + Import all disks to VDI format + + + + + + + + Export options, used with . + + + + Write the optional manifest file (.mf) which is used for integrity + checks prior import. + + + Export DVD images. Default is not to export them as it is rarely + needed for typical VMs. + + + Do not export any MAC address information. Default is to keep them + to avoid losing information which can cause trouble after import, at the + price of risking duplicate MAC addresses, if the import options are used + to keep them. + + + Do not export any MAC address information, except for adapters + using NAT. Default is to keep them to avoid losing information which can + cause trouble after import, at the price of risking duplicate MAC + addresses, if the import options are used to keep them. + + + + + + + X.509 certificate version numbers. + + + + + + + + + + + X.509 certificate details. + + + Certificate version number. + + + Certificate serial number. + + + The dotted OID of the signature algorithm. + + + The signature algorithm name if known (if known). + + + Issuer name. Each member of the array is on the format + COMPONENT=NAME, e.g. "C=DE", "ST=Example", "L=For Instance", "O=Beispiel GmbH", + "CN=beispiel.example.org". + + + + Subject name. Same format as issuerName. + + + Friendly subject name or similar. + + + Certificate not valid before ISO timestamp. + + + Certificate not valid after ISO timestamp. + + + The dotted OID of the public key algorithm. + + + The public key algorithm name (if known). + + + The raw public key bytes. + + + Unique identifier of the issuer (empty string if not present). + + + Unique identifier of this certificate (empty string if not present). + + + Whether this certificate is a certificate authority. Will return E_FAIL + if this attribute is not present. + + + + Key usage mask. Will return 0 if not present. + + + Array of dotted extended key usage OIDs. Empty array if not present. + + + The raw certificate bytes. + + + Set if self signed certificate. + + + + + Set if the certificate is trusted (by the parent object). + + + Set if the certificate has expired (relevant to the parent object)/ + + + + + Tests if the certificate has expired at the present time according to + the X.509 validity of the certificate. + + + + + Way to extend the interface. + + + + + + + + + + + Represents a platform-independent appliance in OVF format. An instance of this is returned + by , which can then be used to import and export + virtual machines within an appliance with VirtualBox. + + The OVF standard suggests two different physical file formats: + +
    +
  1. If the appliance is distributed as a set of files, there must be at least one XML descriptor + file that conforms to the OVF standard and carries an .ovf file extension. If + this descriptor file references other files such as disk images, as OVF appliances typically + do, those additional files must be in the same directory as the descriptor file. +
    2. + +
  2. If the appliance is distributed as a single file, it must be in TAR format and have the + .ova file extension. This TAR file must then contain at least the OVF descriptor + files and optionally other files. + + At this time, VirtualBox does not not yet support the packed (TAR) variant; support will + be added with a later version. +
    3. +
+ + Importing an OVF appliance into VirtualBox as instances of + involves the following sequence of API calls: + +
    +
  1. Call . This will create an empty IAppliance object. +
    2. + +
  2. On the new object, call with the full path of the OVF file you + would like to import. So long as this file is syntactically valid, this will succeed + and fill the appliance object with the parsed data from the OVF file. +
    3. + +
  3. Next, call , which analyzes the OVF data and sets up the + contents of the IAppliance attributes accordingly. These can be inspected by a + VirtualBox front-end such as the GUI, and the suggestions can be displayed to the + user. In particular, the array contains + instances of which represent the virtual + systems (machines) in the OVF, which in turn describe the virtual hardware prescribed + by the OVF (network and hardware adapters, virtual disk images, memory size and so on). + The GUI can then give the user the option to confirm and/or change these suggestions. +
    4. + +
  4. If desired, call for each + virtual system (machine) to override the suggestions made by the routine. +
    5. + +
  5. Finally, call to create virtual machines in + VirtualBox as instances of that match the information in the + virtual system descriptions. After this call succeeded, the UUIDs of the machines created + can be found in the array attribute. +
    6. +
+ + Exporting VirtualBox machines into an OVF appliance involves the following steps: + +
    +
  1. As with importing, first call to create + an empty IAppliance object. +
    2. + +
  2. For each machine you would like to export, call + with the IAppliance object you just created. Each such call creates one instance of + inside the appliance. +
    3. + +
  3. If desired, call for each + virtual system (machine) to override the suggestions made by the routine. +
    4. + +
  4. Finally, call with a path specification to have the OVF + file written.
    5. +
+ + + + + Path to the main file of the OVF appliance, which is either the .ovf or + the .ova file passed to (for import) or + (for export). + This attribute is empty until one of these methods has been called. + + + + + + Array of virtual disk definitions. One such description exists for each + disk definition in the OVF; each string array item represents one such piece of + disk information, with the information fields separated by tab (\\t) characters. + + The caller should be prepared for additional fields being appended to + this string in future versions of VirtualBox and therefore check for + the number of tabs in the strings returned. + + In the current version, the following eight fields are returned per string + in the array: + +
    +
  1. Disk ID (unique string identifier given to disk)
    2. + +
  2. Capacity (unsigned integer indicating the maximum capacity of the disk)
    3. + +
  3. Populated size (optional unsigned integer indicating the current size of the + disk; can be approximate; -1 if unspecified)
    4. + +
  4. Format (string identifying the disk format, typically + "http://www.vmware.com/specifications/vmdk.html#sparse")
    5. + +
  5. Reference (where to find the disk image, typically a file name; if empty, + then the disk should be created on import)
    6. + +
  6. Image size (optional unsigned integer indicating the size of the image, + which need not necessarily be the same as the values specified above, since + the image may be compressed or sparse; -1 if not specified)
    7. + +
  7. Chunk size (optional unsigned integer if the image is split into chunks; + presently unsupported and always -1)
    8. + +
  8. Compression (optional string equaling "gzip" if the image is gzip-compressed)
    9. +
+ + + + + Array of virtual system descriptions. One such description is created + for each virtual system (machine) found in the OVF. + This array is empty until either (for import) or + (for export) has been called. + + + + + + Contains the UUIDs of the machines created from the information in this appliances. This is only + relevant for the import case, and will only contain data after a call to + succeeded. + + + + + + The X.509 signing certificate, if the imported OVF was signed, @c null + if not signed. This is available after calling . + + + + + + + Reads an OVF file into the appliance object. + + This method succeeds if the OVF is syntactically valid and, by itself, without errors. The + mere fact that this method returns successfully does not mean that VirtualBox supports all + features requested by the appliance; this can only be examined after a call to . + + + + Name of appliance file to open (either with an .ovf or .ova extension, depending + on whether the appliance is distributed as a set of files or as a single file, respectively). + + + + Progress object to track the operation completion. + + + + + + + Interprets the OVF data that was read when the appliance was constructed. After + calling this method, one can inspect the + array attribute, which will then contain + one for each virtual machine found in + the appliance. + + Calling this method is the second step of importing an appliance into VirtualBox; + see for an overview. + + After calling this method, one should call to find out + if problems were encountered during the processing which might later lead to + errors. + + + + + + + Imports the appliance into VirtualBox by creating instances of + and other interfaces that match the information contained in the appliance as + closely as possible, as represented by the import instructions in the + array. + + Calling this method is the final step of importing an appliance into VirtualBox; + see for an overview. + + Since importing the appliance will most probably involve copying and converting + disk images, which can take a long time, this method operates asynchronously and + returns an IProgress object to allow the caller to monitor the progress. + + After the import succeeded, the UUIDs of the IMachine instances created can be + retrieved from the array attribute. + + + + Options for the importing operation. + + + + Progress object to track the operation completion. + + + + + Returns a object for the given URI. + + + The URI describing the file system to use. + + + + + + + + + + + Writes the contents of the appliance exports into a new OVF file. + + Calling this method is the final step of exporting an appliance from VirtualBox; + see for an overview. + + Since exporting the appliance will most probably involve copying and converting + disk images, which can take a long time, this method operates asynchronously and + returns an IProgress object to allow the caller to monitor the progress. + + + + Output format, as a string. Currently supported formats are "ovf-0.9", "ovf-1.0", + "ovf-2.0" and "opc-1.0"; future versions of VirtualBox may support additional formats. + The "opc-1.0" format is for creating tarballs for the Oracle Public Cloud. + + + + Options for the exporting operation. + + + + Name of appliance file to create. There are certain restrictions with regard + to the file name suffix. If the format parameter is "opc-1.0" a .tar.gz + suffix is required. Otherwise the suffix must either be .ovf or + .ova, depending on whether the appliance is distributed as a set of + files or as a single file, respectively. + + + + Progress object to track the operation completion. + + + + + + Returns textual warnings which occurred during execution of . + + + + + + + + + + Returns a list of password identifiers which must be supplied to import or export + encrypted virtual machines. + + + + The list of password identifiers required for export on success. + + + + + + + Returns a list of medium identifiers which use the given password identifier. + + + + The password identifier to get the medium identifiers for. + + + The list of medium identifiers returned on success. + + + + + + + Adds a list of passwords required to import or export encrypted virtual + machines. + + + + List of identifiers. + + + + List of matching passwords. + + + + + + Creates a number of objects and store them + in the array. + + + + Requested number of new virtual system description objects + + + + Actually created number of virtual system description objects + + + + + + + Used with to describe the type of + a configuration value. + + + + + + + + + + + + + + + + + + + + + + + + + + Optional, may be unset by the API caller. If this is changed by the + API caller it defines the absolute path of the VM settings file and + therefore also the VM folder with highest priority. + + + Optional, may be unset by the API caller. If set (and + is not changed), + defines the VM base folder (taking the primary group into account if + also set). + + + Optional, empty by default and may be unset by the API caller. + Defines the primary group of the VM after import. May influence the + selection of the VM folder. Additional groups may be configured later + using , after importing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Used with to describe the value + type to fetch. + + + + + + + + + + + + Represents one virtual system (machine) in an appliance. This interface is used in + the array. After + has been called, that array contains information + about how the virtual systems described in the OVF should best be imported into + VirtualBox virtual machines. See for the steps required to + import an OVF into VirtualBox. + + + + Return the number of virtual system description entries. + + + + Returns information about the virtual system as arrays of instruction items. In each array, the + items with the same indices correspond and jointly represent an import instruction for VirtualBox. + + The list below identifies the value sets that are possible depending on the + enum value in the array item in @a aTypes[]. In each case, + the array item with the same index in @a OVFValues[] will contain the original value as contained + in the OVF file (just for informational purposes), and the corresponding item in @a aVBoxValues[] + will contain a suggested value to be used for VirtualBox. Depending on the description type, + the @a aExtraConfigValues[] array item may also be used. + +
    +
  • + "OS": the guest operating system type. There must be exactly one such array item on import. The + corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox. + This will be one of the values listed in . The corresponding + item in @a OVFValues[] will contain a numerical value that described the operating system in the OVF. +
    • +
  • + "Name": the name to give to the new virtual machine. There can be at most one such array item; + if none is present on import, then an automatic name will be created from the operating system + type. The corresponding item im @a OVFValues[] will contain the suggested virtual machine name + from the OVF file, and @a aVBoxValues[] will contain a suggestion for a unique VirtualBox + name that does not exist yet. +
    • +
  • + "Description": an arbitrary description. +
    • +
  • + "License": the EULA section from the OVF, if present. It is the responsibility of the calling + code to display such a license for agreement; the Main API does not enforce any such policy. +
    • +
  • + Miscellaneous: reserved for future use. +
    • +
  • + "CPU": the number of CPUs. There can be at most one such item, which will presently be ignored. +
    • +
  • + "Memory": the amount of guest RAM, in bytes. There can be at most one such array item; if none + is present on import, then VirtualBox will set a meaningful default based on the operating system + type. +
    • +
  • + "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items. + An optional value in @a OVFValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify + the type of IDE controller; this corresponds to the ResourceSubType element which VirtualBox + writes into the OVF. + The matching item in the @a aRefs[] array will contain an integer that items of the "Harddisk" + type can use to specify which hard disk controller a virtual disk should be connected to. + Note that in OVF, an IDE controller has two channels, corresponding to "master" and "slave" + in traditional terminology, whereas the IDE storage controller that VirtualBox supports in + its virtual machines supports four channels (primary master, primary slave, secondary master, + secondary slave) and thus maps to two IDE controllers in the OVF sense. +
    • +
  • + "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This + has no value in @a OVFValues[] or @a aVBoxValues[]. + The matching item in the @a aRefs[] array will be used as with IDE controllers (see above). +
    • +
  • + "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item. + The items in @a OVFValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or + "LsiLogicSas". (Note that in OVF, the LsiLogicSas controller is treated as a SCSI controller + whereas VirtualBox considers it a class of storage controllers of its own; see + ). + The matching item in the @a aRefs[] array will be used as with IDE controllers (see above). +
    • +
  • + "HardDiskImage": a virtual hard disk, most probably as a reference to an image file. There can be an + arbitrary number of these items, one for each virtual disk image that accompanies the OVF. + + The array item in @a OVFValues[] will contain the file specification from the OVF file (without + a path since the image file should be in the same location as the OVF file itself), whereas the + item in @a aVBoxValues[] will contain a qualified path specification to where VirtualBox uses the + hard disk image. This means that on import the image will be copied and converted from the + "ovf" location to the "vbox" location; on export, this will be handled the other way round. + + The matching item in the @a aExtraConfigValues[] array must contain a string of the following + format: "controller=<index>;channel=<c>" + In this string, <index> must be an integer specifying the hard disk controller to connect + the image to. That number must be the index of an array item with one of the hard disk controller + types (HardDiskControllerSCSI, HardDiskControllerSATA, HardDiskControllerIDE). + In addition, <c> must specify the channel to use on that controller. For IDE controllers, + this can be 0 or 1 for master or slave, respectively. For compatibility with VirtualBox versions + before 3.2, the values 2 and 3 (for secondary master and secondary slave) are also supported, but + no longer exported. For SATA and SCSI controllers, the channel can range from 0-29. +
    • +
  • + "CDROM": a virtual CD-ROM drive. The matching item in @a aExtraConfigValue[] contains the same + attachment information as with "HardDiskImage" items. +
    • +
  • + "CDROM": a virtual floppy drive. The matching item in @a aExtraConfigValue[] contains the same + attachment information as with "HardDiskImage" items. +
    • +
  • + "NetworkAdapter": a network adapter. The array item in @a aVBoxValues[] will specify the hardware + for the network adapter, whereas the array item in @a aExtraConfigValues[] will have a string + of the "type=<X>" format, where <X> must be either "NAT" or "Bridged". +
    • +
  • + "USBController": a USB controller. There can be at most one such item. If, and only if, such an + item is present, USB support will be enabled for the new virtual machine. +
    • +
  • + "SoundCard": a sound card. There can be at most one such item. If and only if such an item is + present, sound support will be enabled for the new virtual machine. Note that the virtual + machine in VirtualBox will always be presented with the standard VirtualBox soundcard, which + may be different from the virtual soundcard expected by the appliance. +
    • +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + This is the same as except that you can specify which types + should be returned. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Delete all records which are equal to the passed type from the list + + + + + + + + This is the same as except that you can specify which + value types should be returned. See for possible + values. + + + + + + + + + + + + + + + + + + This method allows the appliance's user to change the configuration for the virtual + system descriptions. For each array item returned from , + you must pass in one boolean value and one configuration value. + + Each item in the boolean array determines whether the particular configuration item + should be enabled. + You can only disable items of the types HardDiskControllerIDE, HardDiskControllerSATA, + HardDiskControllerSCSI, HardDiskImage, CDROM, Floppy, NetworkAdapter, USBController + and SoundCard. + + For the "vbox" and "extra configuration" values, if you pass in the same arrays + as returned in the aVBoxValues and aExtraConfigValues arrays from , + the configuration remains unchanged. Please see the documentation for + for valid configuration values for the individual array item types. If the + corresponding item in the aEnabled array is @c false, the configuration value is ignored. + + + + + + + + + + + + + + + + + + This method adds an additional description entry to the stack of already + available descriptions for this virtual system. This is handy for writing + values which aren't directly supported by VirtualBox. One example would + be the License type of . + + + + + + + + + + + + + + + + + + + + + + + The IUnattended interface represents the pipeline for preparing + the Guest OS for fully automated install. + + The typical workflow is: +
    +
  1. Call to create the object
    2. +
  2. Set and call
    3. +
  3. Create, configure and register a machine according to + and the other detectedOS* attributes.
    4. +
  4. Set to the new IMachine instance.
    5. +
  5. Set the other IUnattended attributes as desired.
    6. +
  6. Call for the object to check the + attribute values and create an internal installer instance.
    7. +
  7. Call to create additional + media files (ISO/floppy) needed.
    8. +
  8. Call to reconfigure the VM + with the installation ISO, additional media files and whatnot
    9. +
  9. Optionally call to destroy the internal + installer and allow restarting from the second step.
    10. +
+ + Note! Step two is currently not implemented. + + + + + Guest operating system ISO image + + + + + + The associated machine object. + + This must be set before is called. + The VM must be registered. + + + + + + Assign an user login name. + + + + + + Assign a password to the user. The password is the same for both + normal user and for Administrator / 'root' accounts. + + + + + + The full name of the user. This is optional and defaults to + . Please note that not all guests picks + up this attribute. + + + + + + Any key which is used as authorization of access to install genuine OS + + + + + + Guest Additions ISO image path. This defaults to + when the Unattended + object is instantiated. + + This property is ignored when is false. + + + + + + Indicates whether the Guest Additions should be installed or not. + + Setting this to false does not affect additions shipped with the linux + distribution, only the installation of additions pointed to by + . + + + + + + VirtualBox ValidationKit ISO image path. This is used when + is set to true. + + + + + + Indicates whether the test execution service (TXS) from the VBox + ValidationKit should be installed. + + The TXS binary will be taken from the ISO indicated by + . + + + + + + The guest time zone specifier. + + This is unfortunately guest OS specific. + + Windows XP and earlier takes the index number from this table: + https://support.microsoft.com/en-gb/help/973627/microsoft-time-zone-index-values + + Windows Vista and later takes the time zone string from this table: + https://technet.microsoft.com/en-us/library/cc749073(v=ws.10).aspx + + Linux usually takes the TZ string from this table: + https://en.wikipedia.org/wiki/List_of_tz_database_time_zones + + The default is currently UTC/GMT, but this may change to be same as + the host later. + + TODO: Investigate automatic mapping between linux and the two windows + time zone formats. + TODO: Take default from host (this requires mapping). + + + + + + The 5 letter locale identifier, no codesets or such. + + The format is two lower case language letters (ISO 639-1), underscore ('_'), + and two upper case country letters (ISO 3166-1 alpha-2). For instance + 'en_US', 'de_DE', or 'ny_NO'. + + The default is taken from the host if possible, with 'en_US' as fallback. + + + + + + This is more or less a Windows specific setting for choosing the UI language + setting of the installer. + + The value should be from the list available via . + The typical format is {language-code}-{COUNTRY} but windows may also use + {16-bit code}:{32-bit code} or insert another component between the language + and country codes. We consider the format guest OS specific. + + Note that it is crucial that this is correctly specified for Windows + installations. If an unsupported value is given the installer will ask + for an installation language and wait for user input. Best to leave it + to the default value. + + The default is the first one from . + + + + + + The 2 upper case letter country identifier, ISO 3166-1 alpha-2. + + This is used for mirrors and such. + + The default is taken from the host when possible, falling back on + . + + + + + + Proxy incantation to pass on to the guest OS installer. + + This is important to get right if the guest OS installer is of the type + that goes online to fetch the packages (e.g. debian-*-netinst.iso) or + to fetch updates during the install process. + + Format: [schema=]schema://[login[:password]@]proxy[:port][;...] + + The default is taken from the host proxy configuration (once implemented). + + + + + + Guest OS specific package selection adjustments. + + This is a semicolon separated list of keywords, and later maybe guest OS + package specifiers. Currently the 'minimal' is the only recognized value, + and this only works with a selection of linux installers. + + + + + + The fully qualified guest hostname. + + This defaults to machine-name + ".myguest.virtualbox.org", though it may + change to the host domain name later. + + + + + + The path + basename for auxiliary files generated by the unattended + installation. This defaults to the VM folder + Unattended + VM UUID. + + The files which gets generated depends on the OS being installed. When + installing Windows there is currently only a auxiliaryBasePath + "floppy.img" + being created. But for linux, a "cdrom.viso" and one or more configuration + files are generate generated. + + + + + + The image index on installation CD/DVD used to install. This index should be + one of the indices of . + + Changing this after ISO detection may cause + , , + , , + and to be updated with values + specific to the selected image. + + Used only with Windows installation CD/DVD: + https://technet.microsoft.com/en-us/library/cc766022%28v=ws.10%29.aspx + + + + + + The unattended installation script template file. + + The template default is based on the guest OS type and is determined by the + internal installer when when is invoked. + Most users will want the defaults. + + After is called, it can be read to see + which file is being used. + + + + + + The post installation (shell/batch) script template file. + + The template default is based on the guest OS type and is determined by the + internal installer when when is invoked. + Most users will want the defaults. + + After is called, it can be read to see + which file is being used. + + + + + + Custom post installation command. + + Exactly what is expected as input here depends on the guest OS installer + and the post installation script template (see + ). + Most users will not need to set this attribute. + + + + + + Extra kernel arguments passed to the install kernel of some guests. + + This is currently only picked up by linux guests. The exact parameters + are specific to the guest OS being installed of course. + + After is called, it can be read to see + which parameters are being used. + + + + + + The detected OS type ID (). + + Set by or . + + Not yet implemented. + + + + + + The detected OS version string. + + Set by or . + + Not yet implemented. + + + + + + The detected OS flavor (e.g. server, desktop, etc) + + Set by or . + + Not yet implemented. + + + + + + The space separated list of (Windows) installation UI languages we detected (lang.ini). + + The language specifier format is specific to the guest OS. They are + used to set . + + Set by or . + + Partially implemented. + + + + + + Space separated list of other stuff detected about the OS and the + installation ISO. + + Set by or . + + Not yet implemented. + + + + + + A list of names of the images detected from install.wim file of a Windows Vista + or later ISO. This array is parallel to . + This will be empty for older Windows ISOs and non-Windows ISOs. + + + + + + A list of image indexes detected from install.wim file of a Windows ISO. This array + is parallel to . + should be set to one of these indices for Vista and later Windows ISOs. + + + + + + Checks the detected OS type and version against a set of rules and returns + whether unattended install is supported or not. Note that failing detecting + OS type from the ISO causes this attribute to be false by default. + + + + + + When set to true installation is configured to abstain from + using network to update/get data. Especially useful when network + is not available (as in our test boxes). + + + + + + Detects the OS on the ISO given by and sets + , + , , + , , + and , + + Not really yet implemented. + + + + + + Prepare for running the unattended process of installation. + + This will perform if not yet called on the + current value. It may then may cause + , , + , , + and to be updated with values + specific to the image selected by if the ISO + contains images. + + This method will then instantiate the installer based on the detected guest type + (see ). + + + + + + Constructors the necessary ISO/VISO/Floppy images, with unattended scripts + and all necessary bits on them. + + + + + + Reconfigures the machine to start the installation. + + This involves mounting the ISOs and floppy images created by + , attaching new DVD and floppy + drives as necessary, and possibly modifying the boot order. + + + + + + Done - time to start the VM. + + This deletes the internal installer instance that + created. Before done() is called, it is not possible to start over again + from . + + + + + + + + + + + + Updates the VM state. + + This operation will also update the settings file with the correct + information about the saved state file and delete this file from disk + when appropriate. + + + + + + + + Tells VBoxSVC that is under ways and + gives it the progress object that should be part of any pending + operations. The progress + object may be called back to reflect an early cancelation, so some care + have to be taken with respect to any cancelation callbacks. The console + object will call + to signal the completion of the progress object. + + + + + + + Tells VBoxSVC that has completed. + This method may query status information from the progress object it + received in and copy + it over to any in-progress + call in order to complete that progress object. + + + + + + + Called by the VM process to inform the server it wants to + stop the VM execution and power down. + + + + Progress object created by VBoxSVC to wait until + the VM is powered down. + + + + + + + Called by the VM process to inform the server that powering + down previously requested by #beginPoweringDown is either + successfully finished or there was a failure. + + + Settings file not accessible. + + + Could not parse the settings file. + + + + + + @c S_OK to indicate success. + + + + @c human readable error message in case of failure. + + + + + + + Asks the server to run USB devices filters of the associated + machine against the given USB device and tell if there is + a match. + + Intended to be used only for remote USB devices. Local + ones don't require to call this method (this is done + implicitly by the Host and USBProxyService). + + + + + + + + + + Requests a capture of the given host USB device. + When the request is completed, the VM process will + get a + notification. + + + + + + + + Notification that a VM is going to detach (@a done = @c false) or has + already detached (@a done = @c true) the given USB device. + When the @a done = @c true request is completed, the VM process will + get a + notification. + + In the @a done = @c true case, the server must run its own filters + and filters of all VMs but this one on the detached device + as if it were just attached to the host computer. + + + + + + + + + Requests a capture all matching USB devices attached to the host. + When the request is completed, the VM process will + get a + notification per every captured device. + + + + + + Notification that a VM that is being powered down. The done + parameter indicates whether which stage of the power down + we're at. When @a done = @c false the VM is announcing its + intentions, while when @a done = @c true the VM is reporting + what it has done. + + In the @a done = @c true case, the server must run its own filters + and filters of all VMs but this one on all detach devices as + if they were just attached to the host computer. + + + + + + + + Triggered by the given session object when the session is about + to close normally. + + + Session that is being closed + + + + Used to wait until the corresponding machine is actually + dissociated from the given session on the server. + Returned only when this session is a direct one. + + + + + + + Gets called by . + All necessary state information is available at the called object. + + + + + + Get the list of the guest properties matching a set of patterns along + with their values, timestamps and flags and give responsibility for + managing properties to the console. + + + + The names of the properties returned. + + + + + The values of the properties returned. The array entries match the + corresponding entries in the @a name array. + + + + + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a name array. + + + + + The flags of the properties returned. The array entries match the + corresponding entries in the @a name array. + + + + + + Update a single guest property in IMachine. + + + + The name of the property to be updated. + + + + + The value of the property. + + + + + The timestamp of the property. + + + + + The flags of the property. + + + + + The flag which indicates if property was deleted. + + + + + + + Locks all media attached to the machine for writing and parents of + attached differencing media (if any) for reading. This operation is + atomic so that if it fails no media is actually locked. + + This method is intended to be called when the machine is in Starting or + Restoring state. The locked media will be automatically unlocked when + the machine is powered off or crashed. + + + + + Unlocks all media previously locked using + . + + This method is intended to be used with teleportation so that it is + possible to teleport between processes on the same machine. + + + + + + Tells VBoxSVC that the guest has ejected the medium associated with + the medium attachment. + + + + The medium attachment where the eject happened. + + + + + A new reference to the medium attachment, as the config change can + result in the creation of a new instance. + + + + + + + Passes statistics collected by VM (including guest statistics) to VBoxSVC. + + + + Mask defining which parameters are valid. For example: 0x11 means + that cpuIdle and XXX are valid. Other parameters should be ignored. + + + + Percentage of processor time spent in user mode as seen by the guest. + + + Percentage of processor time spent in kernel mode as seen by the guest. + + + Percentage of processor time spent idling as seen by the guest. + + + Total amount of physical guest RAM. + + + Free amount of physical guest RAM. + + + Amount of ballooned physical guest RAM. + + + Amount of shared physical guest RAM. + + + Total amount of guest (disk) cache memory. + + + Total amount of space in the page file. + + + Total amount of memory allocated by the hypervisor. + + + Total amount of free memory available in the hypervisor. + + + Total amount of memory ballooned by the hypervisor. + + + Total amount of shared memory in the hypervisor. + + + Network receive rate for VM. + + + Network transmit rate for VM. + + + + + + Verify credentials using the external auth library. + + + + The auth parameters, credentials, etc. + + + + + The authentification result. + + + + + + + + The IGraphicsAdapter interface represents the graphics adapter + of the virtual machine. + + + + Graphics controller type. + + + + Video memory size in megabytes. + + + + + This setting determines whether VirtualBox allows this machine to make + use of the 3D graphics support available on the host. + + + + + This setting determines whether VirtualBox allows this machine to make + use of the 2D video acceleration support available on the host. + + + + + Number of virtual monitors. + + Only effective on Windows XP and later guests with + Guest Additions installed. + + + + + + + + + The IBIOSSettings interface represents BIOS settings of the virtual + machine. This is used only in the attribute. + + + Fade in flag for BIOS logo animation. + + + + Fade out flag for BIOS logo animation. + + + + BIOS logo display time in milliseconds (0 = default). + + + + + Local file system path for external BIOS splash image. Empty string + means the default image is shown on boot. + + + + + Mode of the BIOS boot device menu. + + + + ACPI support flag. + + + + + I/O-APIC support flag. If set, VirtualBox will provide an I/O-APIC + and support IRQs above 15. + + + + + + APIC mode to set up by the firmware. + + + + + + Offset in milliseconds from the host system time. This allows for + guests running with a different system date/time than the host. + It is equivalent to setting the system date/time in the BIOS except + it is not an absolute value but a relative one. Guest Additions + time synchronization honors this offset. + + + + + + PXE debug logging flag. If set, VirtualBox will write extensive + PXE trace information to the release log. + + + + + + Flag to control whether the SMBIOS system UUID is presented in little endian + form to the guest as mandated by the SMBIOS spec chapter 7.2.1. + Before VirtualBox version 6.1 it was always presented in big endian form + and to retain the old behavior this flag was introduced so it can be changed. + VMs created with VBox 6.1 will default to true for this flag. + + + + + + + + TPM type enumeration. + + + + No TPM present in the virtual machine. + + + A TPM compliant to the 1.2 TCG specification is emulated. + + + A TPM compliant to the 2.0 TCG specification is emulated. + + + The host TPM is passed through, might not be available on all host platforms. + + + The VM will attach to an external software TPM emulation compliant to swtpm. + + + + + + The ITrustedPlatformModule interface represents the settings of the virtual + machine's trusted platform module. This is used only in the attribute. + + + + + Type of TPM configured for the virtual machine. + + + + + + Location of the TPM. This is only used for the TpmType_Swtpm type of TPM + where the location denotes a hostname:port where to connect to. + + + + + + + + Recording destination enumeration. + + + + No destination. + + + Destination is a regular file. + + + + + + Recording feature flags. More than one flag may be set. + + + + No feature set. + + + Video recording. + + + Audio recording. + + + + + + Recording audio codec enumeration. + + + + No codec set. + + + WAV format, linear PCM, uncompressed. + + + MPEG-2 Audio Layer III. + + + Ogg Vorbis. + + + Opus Audio. + + + Other codec. + + + + + + Recording codec deadline. + + How (and if at all) this deadline is being implemented depends on the codec being used. + + + + Default deadline. + + + Realtime quality, often resulting in poor / basic quality. + + + Balance between realtime and best deadline. + + + Best quality, slowest. + + + + + + Recording video codec enumeration. + + + + No codec set. + + + Motion JPEG. + + + MPEG-2, Part 2. + + + Advanced Video Coding (AVC), MPEG-4 Part 10. + + + High Efficiency Video Coding (HEVC), MPEG-H Part 2. + + + Versatile Video Coding (VVC), MPEG-I Part 3. + + + VP8 codec. + + + VP9 codec. + + + AOMedia Video 1 codec. + + + Other codec. + + + + + + Recording video scaling method enumeration. + + + + No scaling performed. + The image wil be cropped when the source is bigger than the target size. + + + Performs scaling via nearest-neighbor interpolation. + Not yet implemented. + + + Performs scaling via bilinear interpolation. + Not yet implemented. + + + Performs scaling via bicubic interpolation. + Not yet implemented. + + + + + + Recording video rate control mode enumeration. + Not all codecs may support all rate control modes. + + + + Average bit rate (ABR). Constrained to a certain size. + + + Constant bit rate (CBR). Constrained to a certain size. + + + Variable bit rate (VBR). Constrained to a certain quality. + + + + + + + The IRecordingScreenSettings interface represents recording settings of a + single virtual screen. This is used only in the + interface. + + + + Returns whether a particular recording feature is enabled for this + screen or not. + + Feature to check for. + + + @c true if the feature is enabled, @c false if not. + + + + + + This attribute contains the screen ID bound to these settings. + + + + + + This setting determines whether this screen is enabled while recording. + + + + + This setting determines all enabled recording features for this + screen. + + + + This setting determines the recording destination for this + screen. + + + + + This setting determines the filename VirtualBox uses to save + the recorded content. This setting cannot be changed while video + recording is enabled. + + When setting this attribute, the specified path has to be + absolute (full path). When reading this attribute, a full path is + always returned. + + + + + + + This setting defines the maximum amount of time in seconds + to record. Recording will stop as soon as the defined time + interval has elapsed. If this value is zero, recording will not be + limited by time. This setting cannot be changed while recording is + enabled. + + + + + + This setting determines the maximal number of recording file + size in MB. Recording will stop as soon as the file size has + reached the defined value. If this value is zero, recording + will not be limited by the file size. This setting cannot be changed + while recording is enabled. + + + + + + This setting contains any additional recording options required in + comma-separated key=value format, which are currently not represented + via own attribtues. Consider these options as experimental and mostly + for codec-specific settings, and are subject to change. This setting + cannot be changed while recording is enabled. + + + + + + Determines the audio codec to use for encoding the + recorded audio data. This setting cannot be changed while recording is + enabled. + + + Only the Opus codec is supported currently. + + + + + + + Determines the audio rate control mode. This setting cannot be changed + while recording is enabled. + + + + + + Determines the audio deadline to use. + This setting cannot be changed while recording is enabled. + + + + + + Determines the Hertz (Hz) rate of the recorded audio data. This setting + cannot be changed while recording is enabled. + + + + + + Determines the bits per sample of the recorded audio data. This setting + cannot be changed while recording is enabled. + + + + + + Determines the audio channels of the recorded audio data. + Specifiy 2 for stereo or 1 for mono. More than stereo (2) channels + are not supported at the moment. This setting cannot be changed while + recording is enabled. + + + + + + Determines the video codec to use for encoding the recorded video data. + This setting cannot be changed while recording is enabled. + + + Only the VP8 codec is supported currently. + + + + + + + Determines the video deadline to use. + This setting cannot be changed while recording is enabled. + + + + + + Determines the horizontal resolution of the recorded video data. This + setting cannot be changed while recording is enabled. + + + + + + Determines the vertical resolution of the recorded video data. This + setting cannot be changed while recording is enabled. + + + + + + Determines the bitrate in kilobits per second. Increasing this value + makes the video look better for the cost of an increased file size or + transfer rate. This setting cannot be changed while recording is enabled. + + + + + + Determines the video rate control mode. This setting cannot be changed + while recording is enabled. + + + + + + Determines the maximum number of frames per second (FPS). Frames with + a higher frequency will be skipped. Reducing this value increases the + number of skipped frames and reduces the file size or transfer rate. + This setting cannot be changed while recording is enabled. + + + + + + Determines the video scaling mode to use. + This setting cannot be changed while recording is enabled. + + + + + + + + + The IRecordingSettings interface represents recording settings of the virtual + machine. This is used only in the + attribute. + + + + Returns the recording settings for a particular screen. + + Screen ID to retrieve recording screen settings for. + + + Recording screen settings for the requested screen. + + + + + + This setting determines whether VirtualBox uses recording to record a + VM session. + + + + + This setting returns an array for recording settings of all configured + virtual screens. + + + + + + + + Address on the PCI bus. + + + + + Bus number. + + + + + + Device number. + + + + + + Device function number. + + + + + + Convert PCI address into long. + + + + + + + Make PCI address from long. + + + + + + + + + Information about PCI attachments. + + + + + Device name. + + + + + + If this is physical or virtual device. + + + + + + Address of device on the host, applicable only to host devices. + + + + + + Address of device in the guest. + + + + + + + + UEFI signature type enumeration. + + + + X.509 certificate. + + + SHA256 hash. + + + + + + Possible variable attributes. More than one flag may be set. + + + + + No attributes set. + + + Variable is stored in non volatile storage. + + + Variable can be accessed from the boot services. + + + Variable can be accessed from the runtime. + + + Variable contains a hardware error record. + + + Writing to this variable requires an authenticated source. + + + Variable was written with a time based authentication. + + + The variable can be appended only. + + + + + + The IUefiVariableStore interface allows inspecting and manipulating the content + of an existing UEFI variable store in a NVRAM file. This is used only in the + attribute. + + + + Flag whether secure boot is currently enabled for the VM. + + + + Adds a new variable to the non volatile storage area. + + Name of the variable. + + + UUID of the variable owner. + + + Attributes of the variable. + + + The variable data. + + + + + Deletes the given variable from the non volatile storage area. + + Name of the variable. + + + UUID of the variable owner. + + + + + Changes the data of the given variable. + + Name of the variable. + + + The new variable data. + + + + + Queries the variable content variable by the given name. + + Name of the variable to look for. + + + UUID of the variable owner returned on success. + + + Attributes of the variable. + + + The variable data returned on success. + + + + + + Queries all variables in the non volatile storage and returns their names. + + + The variable names returned on success. + + + UUID of the variable owners returned on success. + + + + + + Enroll the default platform key from Oracle for enabling Secure Boot. + + + + + + Convenience method to enroll a new platform key (PK) for enabling Secure Boot. + + + The platform key (PK) to enroll. + + + UUID of the PK owner. + + + + + + Convenience method to add a new Key Encryption Key (KEK) for Secure Boot. + + + The Key Encryption Key (KEK) to add. + + + UUID of the KEK owner. + + + Type of the signature. + + + + + + Convenience method to add a new entry to the signature database. + + + The signature to add. + + + UUID of the signature owner. + + + Type of the signature. + + + + + + Convenience method to add a new entry to the forbidden signature database. + + + The signature to add. + + + UUID of the signature owner. + + + Type of the signature. + + + + + + Convenience method to enroll the standard Microsoft KEK and signatures + in the signature databases. + + + + + + Convenience method to add a new entry to the MOK (Machine Owner Key) signature database. + + + The signature to add. + + + UUID of the signature owner. + + + Type of the signature. + + + + + + + + + Provides access to the NVRAM store collecting all permanent states from different sources + (UEFI, TPM, etc.). + + + + + The location of the file storing the non-volatile memory content when + the VM is powered off. The file does not always exist. + + + + + Object to manipulate the data in an existing UEFI variable store. + + + + + Key Id of the password used for encrypting the NVRAM file. + Internal use only for now. + + + + + + Key store used for encrypting the NVRAM file. + Internal use only for now. + + + + + Initializes the UEFI variable store. + + + Size in bytes of the UEFI variable store. Must be 0 for now to initialize to the + default size. + + + + + + + + Graphics controller type, used with . + + + Reserved value, invalid. + + + VirtualBox VGA device. + + + VMware SVGA II device. + + + VirtualBox VGA device with VMware SVGA II extensions. + + + + + Cleanup mode, used with . + + + Unregister only the machine, but neither delete snapshots nor detach media. + + + Delete all snapshots and detach all media but return none; this will keep all media registered. + + + Delete all snapshots, detach all media and return hard disks for closing, but not removable media. + + + Delete all snapshots, detach all media and return all media for closing. + + + Delete all snapshots, detach all media and return hard disks and removable + media located in the folder of the machine to be deleted and referenced only + by this machine, for closing. + + + + + + + Clone mode, used with . + + + + Clone the state of the selected machine. + + + Clone the state of the selected machine and its child snapshots if present. + + + Clone all states (including all snapshots) of the machine, regardless of the machine object used. + + + + + + + + Clone options, used with . + + + + Create a clone VM where all virtual disks are linked to the original VM. + + + Don't generate new MAC addresses of the attached network adapters. + + + Don't generate new MAC addresses of the attached network adapters when they are using NAT. + + + Don't change the disk names. + + + Don't change UUID of the machine hardware. + + + + + + + + Autostop types, used with . + + + + Stopping the VM during system shutdown is disabled. + + + The state of the VM will be saved when the system shuts down. + + + The VM is powered off when the system shuts down. + + + An ACPI shutdown event is generated. + + + + + + + Virtual machine process priorities. + + + + Invalid priority, do not use. + + + Default process priority determined by the OS. + + + + Assumes a scheduling policy which puts the process at the default + priority and with all threads at the same priority + + + + + Assumes a scheduling policy which puts the process mostly below the + default priority of the host OS. + + + + + Assume a scheduling policy which shares the CPU resources fairly with + other processes running with the default priority of the host OS. + + + + + Assumes a scheduling policy which puts the task above the default + priority of the host OS. This policy might easily cause other tasks + in the system to starve. + + + + + + + The IOMMU type. This enumeration represents possible + values for the attribute. + + + No IOMMU is present. + + + No IOMMU is present. + + + An AMD IOMMU. + + + An Intel IOMMU. + + + + + + + The IMachine interface represents a virtual machine, or guest, created + in VirtualBox. + + This interface is used in two contexts. First of all, a collection of + objects implementing this interface is stored in the + attribute which lists all the virtual + machines that are currently registered with this VirtualBox + installation. Also, once a session has been opened for the given virtual + machine (e.g. the virtual machine is running), the machine object + associated with the open session can be queried from the session object; + see for details. + + The main role of this interface is to expose the settings of the virtual + machine and provide methods to change various aspects of the virtual + machine's configuration. For machine objects stored in the + collection, all attributes are + read-only unless explicitly stated otherwise in individual attribute + and method descriptions. + + In order to change a machine setting, a session for this machine must be + opened using one of the or + methods. After the + machine has been successfully locked for a session, a mutable machine object + needs to be queried from the session object and then the desired settings + changes can be applied to the returned object using IMachine attributes and + methods. See the interface description for more + information about sessions. + + Note that IMachine does not provide methods to control virtual machine + execution (such as start the machine, or power it down) -- these methods + are grouped in a separate interface called . + + , + + + + Associated parent object. + + + + Overridden VM Icon details. + + + + + Whether this virtual machine is currently accessible or not. + + A machine is always deemed accessible unless it is registered and + its settings file cannot be read or parsed (either because the file itself + is unavailable or has invalid XML contents). + + Every time this property is read, the accessibility state of + this machine is re-evaluated. If the returned value is @c false, + the property may be used to get the + detailed error information describing the reason of + inaccessibility, including XML error messages. + + When the machine is inaccessible, only the following properties + can be used on it: +
    +
    • +
    • +
    • +
    • +
    • +
+ + An attempt to access any other property or method will return + an error. + + The only possible action you can perform on an inaccessible + machine is to unregister it using the + call (or, to check + for the accessibility state once more by querying this + property). + + + In the current implementation, once this property returns + @c true, the machine will never become inaccessible + later, even if its settings file cannot be successfully + read/written any more (at least, until the VirtualBox + server is restarted). This limitation may be removed in + future releases. + + + + + + + Error information describing the reason of machine + inaccessibility. + + Reading this property is only valid after the last call to + returned @c false (i.e. the + machine is currently inaccessible). Otherwise, a @c null + IVirtualBoxErrorInfo object will be returned. + + + + + + Name of the virtual machine. + + Besides being used for human-readable identification purposes + everywhere in VirtualBox, the virtual machine name is also used + as a name of the machine's settings file and as a name of the + subdirectory this settings file resides in. Thus, every time you + change the value of this property, the settings file will be + renamed once you call to confirm the + change. The containing subdirectory will be also renamed, but + only if it has exactly the same name as the settings file + itself prior to changing this property (for backward compatibility + with previous API releases). The above implies the following + limitations: +
    +
  • The machine name cannot be empty.
    • +
  • The machine name can contain only characters that are valid + file name characters according to the rules of the file + system used to store VirtualBox configuration.
    • +
  • You cannot have two or more machines with the same name + if they use the same subdirectory for storing the machine + settings files.
    • +
  • You cannot change the name of the machine if it is running, + or if any file in the directory containing the settings file + is being used by another running machine or by any other + process in the host operating system at a time when + is called. +
    • +
+ If any of the above limitations are hit, + will return an appropriate error message explaining the exact + reason and the changes you made to this machine will not be saved. + + Starting with VirtualBox 4.0, a ".vbox" extension of the settings + file is recommended, but not enforced. (Previous versions always + used a generic ".xml" extension.) + + + + + + Description of the virtual machine. + + The description attribute can contain any text and is + typically used to describe the hardware and software + configuration of the virtual machine in detail (i.e. network + settings, versions of the installed software and so on). + + + + + UUID of the virtual machine. + + + + + Array of machine group names of which this machine is a member. + "" and "/" are synonyms for the toplevel group. Each + group is only listed once, however they are listed in no particular + order and there is no guarantee that there are no gaps in the group + hierarchy (i.e. "/group", + "/group/subgroup/subsubgroup" is a valid result). + + + + + + User-defined identifier of the Guest OS type. + You may use to obtain + an IGuestOSType object representing details about the given + Guest OS type. All Guest OS types are considered valid, even those + which are not known to . + + This value may differ from the value returned by + if Guest Additions are + installed to the guest OS. + + + + + + Hardware version identifier. Internal use only for now. + + + + + The UUID presented to the guest via memory tables, hardware and guest + properties. For most VMs this is the same as the @a id, but for VMs + which have been cloned or teleported it may be the same as the source + VM. The latter is because the guest shouldn't notice that it was + cloned or teleported. + + + + + Number of virtual CPUs in the VM. + + + + + This setting determines whether VirtualBox allows CPU + hotplugging for this machine. + + + + + Means to limit the number of CPU cycles a guest can use. The unit + is percentage of host CPU cycles per second. The valid range + is 1 - 100. 100 (the default) implies no limit. + + + + + Virtual CPUID portability level, the higher number the fewer newer + or vendor specific CPU feature is reported to the guest (via the CPUID + instruction). The default level of zero (0) means that all virtualized + features supported by the host is pass thru to the guest. While the + three (3) is currently the level supressing the most features. + + Exactly which of the CPUID features are left out by the VMM at which + level is subject to change with each major version. + + + + + System memory size in megabytes. + + + + Memory balloon size in megabytes. + + + + + This setting determines whether VirtualBox allows page + fusion for this machine (64-bit hosts only). + + + + + Graphics adapter object. + + + + Object containing all BIOS settings. + + + + Object containing all TPM settings. + + + + Object to manipulate data in the non volatile storage file. + + + + Object containing all recording settings. + + + + Type of firmware (such as legacy BIOS or EFI), used for initial + bootstrap in this VM. + + + + Type of pointing HID (such as mouse or tablet) used in this VM. + The default is typically "PS2Mouse" but can vary depending on the + requirements of the guest operating system. + + + + Type of keyboard HID used in this VM. + The default is typically "PS2Keyboard" but can vary depending on the + requirements of the guest operating system. + + + + This attribute controls if High Precision Event Timer (HPET) is + enabled in this VM. Use this property if you want to provide guests + with additional time source, or if guest requires HPET to function correctly. + Default is false. + + + + Chipset type used in this VM. + + + + IOMMU type used in this VM. + + + + + Full path to the directory used to store snapshot data + (differencing media and saved state files) of this machine. + + The initial value of this property is + < + path_to_settings_file>/< + machine_uuid + >. + + Currently, it is an error to try to change this property on + a machine that has snapshots (because this would require to + move possibly large files to a different location). + A separate method will be available for this purpose later. + + + Setting this property to @c null or to an empty string will restore + the initial value. + + + When setting this property, the specified path can be + absolute (full path) or relative to the directory where the + machine settings file + is located. When reading this property, a full path is + always returned. + + + The specified path may not exist, it will be created + when necessary. + + + + + + VirtualBox Remote Desktop Extension (VRDE) server object. + + + + + + Array of media attached to this machine. + + + + + Array of USB controllers attached to this machine. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + + + + + Associated USB device filters object. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + + + + + The machine's audio settings. + + + + + Array of storage controllers attached to this machine. + + + + + Full name of the file containing machine settings data. + + + + + + Full name of the file containing auxiliary machine settings data. + + + + + + Whether the settings of this machine have been modified + (but neither yet saved nor discarded). + + Reading this property is only valid on instances returned + by and on new machines + created by or opened + by but not + yet registered, or on unregistered machines after calling + . For all other + cases, the settings can never be modified. + + + For newly created unregistered machines, the value of this + property is always @c true until + is called (no matter if any machine settings have been + changed after the creation or not). For opened machines + the value is set to @c false (and then follows to normal rules). + + + + + + Current session state for this machine. + + + + + Name of the session. If is + Spawning or Locked, this attribute contains the + same value as passed to the + method in the + @a name parameter. If the session was established with + , it is the name of the session + (if set, otherwise empty string). If + is SessionClosed, the value of this + attribute is an empty string. + + + + + + Identifier of the session process. This attribute contains the + platform-dependent identifier of the process whose session was + used with call. The returned + value is only valid if is Locked or + Unlocking by the time this property is read. + + + + + Current execution state of this machine. + + + + + Timestamp of the last execution state change, + in milliseconds since 1970-01-01 UTC. + + + + + + Full path to the file that stores the execution state of + the machine when it is in either the + or state. + + When the machine is not in the Saved or AbortedSaved state, this + attribute is an empty string. + + + + + + + Full path to the folder that stores a set of rotated log files + recorded during machine execution. The most recent log file is + named VBox.log, the previous log file is + named VBox.log.1 and so on (up to VBox.log.3 + in the current version). + + + + + + Current snapshot of this machine. This is @c null if the machine + currently has no snapshots. If it is not @c null, then it was + set by one of , + or , depending on which was called last. + See for details. + + + + + + Number of snapshots taken on this machine. Zero means the + machine doesn't have any snapshots. + + + + + + Returns @c true if the current state of the machine is not + identical to the state stored in the current snapshot. + + The current state is identical to the current snapshot only + directly after one of the following calls are made: + +
    +
  • +
    • +
  • (issued on a "powered off" or "saved" + machine, for which returns @c false) +
    • +
+ + The current state remains identical until one of the following + happens: +
    +
  • settings of the machine are changed
    • +
  • the saved state is deleted
    • +
  • the current snapshot is deleted
    • +
  • an attempt to execute the machine is made
    • +
+ + + For machines that don't have snapshots, this property is + always @c false. + + + + + + + Collection of shared folders for this machine (permanent shared + folders). These folders are shared automatically at machine startup + and available only to the guest OS installed within this machine. + + New shared folders are added to the collection using + . Existing shared folders can be + removed using . + + + + + + Synchronization mode between the host OS clipboard + and the guest OS clipboard. + + + + + + Sets or retrieves whether clipboard file transfers are allowed or not. + + When set to @a true, clipboard file transfers between supported + host and guest OSes are allowed. + + + + + + Sets or retrieves the current drag'n drop mode. + + + + + + When set to @a true, the virtual machine becomes a target teleporter + the next time it is powered on. This can only set to @a true when the + VM is in the @a PoweredOff or @a Aborted state. + + + + + + + + The TCP port the target teleporter will listen for incoming + teleportations on. + + 0 means the port is automatically selected upon power on. The actual + value can be read from this property while the machine is waiting for + incoming teleportations. + + + + + + The address the target teleporter will listen on. If set to an empty + string, it will listen on all addresses. + + + + + + The password to check for on the target teleporter. This is just a + very basic measure to prevent simple hacks and operators accidentally + beaming a virtual machine to the wrong place. + + Note that you SET a plain text password while reading back a HASHED + password. Setting a hashed password is currently not supported. + + + + + + The paravirtualized guest interface provider. + + + + + + When set to @a true, the RTC device of the virtual machine will run + in UTC time, otherwise in local time. Especially Unix guests prefer + the time in UTC. + + + + + + When set to @a true, the builtin I/O cache of the virtual machine + will be enabled. + + + + + + Maximum size of the I/O cache in MB. + + + + + Array of PCI devices assigned to this machine, to get list of all + PCI devices attached to the machine use + attribute, as this attribute + is intended to list only devices additional to what described in + virtual hardware config. Usually, this list keeps host's physical + devices assigned to the particular machine. + + + + + + Bandwidth control manager. + + + + + + Enables the tracing facility in the VMM (including PDM devices + + drivers). The VMM will consume about 0.5MB of more memory when + enabled and there may be some extra overhead from tracepoints that are + always enabled. + + + + + + Tracepoint configuration to apply at startup when + is true. The string specifies + a space separated of tracepoint group names to enable. The special + group 'all' enables all tracepoints. Check DBGFR3TracingConfig for + more details on available tracepoint groups and such. + + Note that on hosts supporting DTrace (or similar), a lot of the + tracepoints may be implemented exclusively as DTrace probes. So, the + effect of the same config may differ between Solaris and Windows for + example. + + + + + + Enables tracepoints in PDM devices and drivers to use the VMCPU or VM + structures when firing off trace points. This is especially useful + with DTrace tracepoints, as it allows you to use the VMCPU or VM + pointer to obtain useful information such as guest register state. + + This is disabled by default because devices and drivers normally has no + business accessing the VMCPU or VM structures, and are therefore unable + to get any pointers to these. + + + + + + Enables autostart of the VM during system boot. + + + + + + Number of seconds to wait until the VM should be started during system boot. + + + + + + Action type to do when the system is shutting down. + + + + + + Selects which VM frontend should be used by default when launching + this VM through the method. + Empty or @c null strings do not define a particular default, it is up + to to select one. See the + description of for the valid + frontend types. + + This per-VM setting overrides the default defined by + attribute, and is + overridden by a frontend type passed to + . + + + + + + Returns whether there is a USB proxy available. + + + + + + Sets the priority of the VM process. It is a VM setting which can + be changed both before starting the VM and at runtime. + + The default value is 'Default', which selects the default + process priority. + + + This attribute is currently not implemented. + + + + + + + Debug parameters for the paravirtualized guest interface provider. + + + + + + Experimental feature to select the guest CPU profile. The default + is "host", which indicates the host CPU. All other names are subject + to change. + + Use the method to get + currently available CPU profiles. + + + + + + Key Id of the password used for encrypting the state file. + Internal use only for now. + + + + + + Key store used for encrypting the state file. + Internal use only for now. + + + + + Key Id of the password used for encrypting the log files. + Internal use only for now. + + + + + + Key store used for encrypting the log files. + Internal use only for now. + + + + + + Guest debugging configuration. + + + + + + + Locks the machine for the given session to enable the caller + to make changes to the machine or start the VM or control + VM execution. + + There are two ways to lock a machine for such uses: + +
    +
  • If you want to make changes to the machine settings, + you must obtain an exclusive write lock on the machine + by setting @a lockType to @c Write. + + This will only succeed if no other process has locked + the machine to prevent conflicting changes. Only after + an exclusive write lock has been obtained using this method, one + can change all VM settings or execute the VM in the process + space of the session object. (Note that the latter is only of + interest if you actually want to write a new front-end for + virtual machines; but this API gets called internally by + the existing front-ends such as VBoxHeadless and the VirtualBox + GUI to acquire a write lock on the machine that they are running.) + + On success, write-locking the machine for a session creates + a second copy of the IMachine object. It is this second object + upon which changes can be made; in VirtualBox terminology, the + second copy is "mutable". It is only this second, mutable machine + object upon which you can call methods that change the + machine state. After having called this method, you can + obtain this second, mutable machine object using the + attribute. +
    • +
  • If you only want to check the machine state or control + machine execution without actually changing machine + settings (e.g. to get access to VM statistics or take + a snapshot or save the machine state), then set the + @a lockType argument to @c Shared. + + If no other session has obtained a lock, you will obtain an + exclusive write lock as described above. However, if another + session has already obtained such a lock, then a link to that + existing session will be established which allows you + to control that existing session. + + To find out which type of lock was obtained, you can + inspect , which will have been + set to either @c WriteLock or @c Shared. +
    • +
+ + In either case, you can get access to the + object which controls VM execution. + + Also in all of the above cases, one must always call + to release the lock on the machine, or + the machine's state will eventually be set to "Aborted". + + To change settings on a machine, the following sequence is typically + performed: + +
    +
  1. Call this method to obtain an exclusive write lock for the current session.
    2. + +
  2. Obtain a mutable IMachine object from .
    3. + +
  3. Change the settings of the machine by invoking IMachine methods.
    4. + +
  4. Call .
    5. + +
  5. Release the write lock by calling .
    6. +
+ + + Virtual machine not registered. + + + Process not started by . + + + Session already open or being opened. + + + Failed to assign machine to session. + + + + + Session object for which the machine will be locked. + + + + + If set to @c Write, then attempt to acquire an exclusive write lock or fail. + If set to @c Shared, then either acquire an exclusive write lock or establish + a link to an existing session. + + + + + + + + Spawns a new process that will execute the virtual machine and obtains a shared + lock on the machine for the calling session. + + If launching the VM succeeds, the new VM process will create its own session + and write-lock the machine for it, preventing conflicting changes from other + processes. If the machine is already locked (because it is already running or + because another session has a write lock), launching the VM process will therefore + fail. Reversely, future attempts to obtain a write lock will also fail while the + machine is running. + + The caller's session object remains separate from the session opened by the new + VM process. It receives its own object which can be used + to control machine execution, but it cannot be used to change all VM settings + which would be available after a call. + + The caller must eventually release the session's shared lock by calling + on the local session object once this call + has returned. However, the session's state (see ) + will not return to "Unlocked" until the remote session has also unlocked + the machine (i.e. the machine has stopped running). + + Launching a VM process can take some time (a new VM is started in a new process, + for which memory and other resources need to be set up). Because of this, + an object is returned to allow the caller to wait + for this asynchronous operation to be completed. Until then, the caller's + session object remains in the "Unlocked" state, and its + and attributes cannot be accessed. + It is recommended to use or + similar calls to wait for completion. Completion is signalled when the VM + is powered on. If launching the VM fails, error messages can be queried + via the progress object, if available. + + The progress object will have at least 2 sub-operations. The first + operation covers the period up to the new VM process calls powerUp. + The subsequent operations mirror the + progress object. Because may require + some extra sub-operations, the + may change at the completion of operation. + + For details on the teleportation progress operation, see + . + + The @a environmentChanges argument is a list of strings where every string contains + environment variable in the putenv style, i.e. "VAR=VALUE" for setting/replacing + and "VAR" for unsetting. These environment variables will be applied to the environment + of the VirtualBox server process. If an environment variable exists both in the server + process and in this list, the value from this list takes precedence over the + server's variable. If the value of the environment variable is omitted, this variable + will be removed from the resulting environment. If the list is empty, the server + environment is inherited by the started process as is. + + + Virtual machine not registered. + + + Invalid session type @a type. + + + No machine matching @a machineId found. + + + Session already open or being opened. + + + Launching process for machine failed. + + + Failed to assign machine to session. + + + + + Client session object to which the VM process will be connected (this + must be in "Unlocked" state). + + + + + Front-end to use for the new VM process. The following are currently supported: +
    +
  • "gui": VirtualBox Qt GUI front-end
    • +
  • "headless": VBoxHeadless (VRDE Server) front-end
    • +
  • "sdl": VirtualBox SDL front-end
    • +
  • "emergencystop": reserved value, used for aborting + the currently running VM or session owner. In this case the + @a session parameter may be @c null (if it is non-null it isn't + used in any way), and the @a progress return value will be always + @c null. The operation completes immediately.
    • +
  • "": use the per-VM default frontend if set, otherwise + the global default defined in the system properties. If neither + are set, the API will launch a "gui" session, which may + fail if there is no windowing environment available. See + and + .
    • +
+ + + + + The list of putenv-style changes to the VM process environment. + + + + Progress object to track the operation completion. + + + + + + + Puts the given device to the specified position in + the boot order. + + To indicate that no device is associated with the given position, + should be used. + + @todo setHardDiskBootOrder(), setNetworkBootOrder() + + + Boot @a position out of range. + + + Booting from USB @a device currently not supported. + + + + + + Position in the boot order (@c 1 to the total number of + devices the machine can boot from, as returned by + ). + + + + + The type of the device used to boot at the given position. + + + + + + + + Returns the device type that occupies the specified + position in the boot order. + + @todo [remove?] + If the machine can have more than one device of the returned type + (such as hard disks), then a separate method should be used to + retrieve the individual device that occupies the given position. + + If here are no devices at the given position, then + is returned. + + @todo getHardDiskBootOrder(), getNetworkBootOrder() + + + Boot @a position out of range. + + + + + + Position in the boot order (@c 1 to the total number of + devices the machine can boot from, as returned by + ). + + + + + Device at the given position. + + + + + + + + Attaches a device and optionally mounts a medium to the given storage + controller (, identified by @a name), + at the indicated port and device. + + This method is intended for managing storage devices in general while a + machine is powered off. It can be used to attach and detach fixed + and removable media. The following kind of media can be attached + to a machine: + +
    +
  • For fixed and removable media, you can pass in a medium that was + previously opened using . +
    • + +
  • Only for storage devices supporting removable media (such as + DVDs and floppies), you can also specify a null pointer to + indicate an empty drive or one of the medium objects listed + in the and + arrays to indicate a host drive. + For removable devices, you can also use + to change the media while the machine is running. +
    • +
+ + In a VM's default configuration of virtual machines, the secondary + master of the IDE controller is used for a CD/DVD drive. + + After calling this returns successfully, a new instance of + will appear in the machine's list of medium + attachments (see ). + + See and for more + information about attaching media. + + The specified device slot must not have a device attached to it, + or this method will fail. + + + You cannot attach a device to a newly created machine until + this machine's settings are saved to disk using + . + + + If the medium is being attached indirectly, a new differencing medium + will implicitly be created for it and attached instead. If the + changes made to the machine settings (including this indirect + attachment) are later cancelled using , + this implicitly created differencing medium will implicitly + be deleted. + + + + SATA device, SATA port, IDE port or IDE slot out of range, or + file or UUID not found. + + + Machine must be registered before media can be attached. + + + Invalid machine state. + + + A medium is already attached to this or another virtual machine. + + + + + Name of the storage controller to attach the device to. + + + Port to attach the device to. For an IDE controller, 0 specifies + the primary controller and 1 specifies the secondary controller. + For a SCSI controller, this must range from 0 to 15; for a SATA controller, + from 0 to 29; for an SAS controller, from 0 to 7. + + + Device slot in the given port to attach the device to. This is only + relevant for IDE controllers, for which 0 specifies the master device and + 1 specifies the slave device. For all other controller types, this must + be 0. + + + Device type of the attached device. For media opened by + , this must match the device type + specified there. + + + Medium to mount or @c null for an empty drive. + + + + + + + Attaches a device and optionally mounts a medium to the given storage + controller (, identified by @a name), + at the indicated port and device. + + This method is intended for managing storage devices in general while a + machine is powered off. It can be used to attach and detach fixed + and removable media. The following kind of media can be attached + to a machine: +
    +
  • + For fixed and removable media, you can pass in a medium that was + previously opened using . +
    • + +
  • Only for storage devices supporting removable media (such as + DVDs and floppies) with an empty drive or one of the medium objects listed + in the and + arrays to indicate a host drive. + For removable devices, you can also use + to change the media while the machine is running. +
    • +
+ + In a VM's default configuration of virtual machines, the secondary + master of the IDE controller is used for a CD/DVD drive. + will appear in the machine's list of medium + attachments (see ). + + See and for more + information about attaching media. + + The specified device slot must not have a device attached to it, + or this method will fail. + + You cannot attach a device to a newly created machine until + this machine's settings are saved to disk using + . + + + If the medium is being attached indirectly, a new differencing medium + will implicitly be created for it and attached instead. If the + changes made to the machine settings (including this indirect + attachment) are later cancelled using , + this implicitly created differencing medium will implicitly + be deleted. + + + + SATA device, SATA port, IDE port or IDE slot out of range, or + file or UUID not found. + + + Machine must be registered before media can be attached. + + + Invalid machine state. + + + A medium is already attached to this or another virtual machine. + + + + Name of the storage controller to attach the device to. + + + Port to attach the device to. For an IDE controller, 0 specifies + the primary controller and 1 specifies the secondary controller. + For a SCSI controller, this must range from 0 to 15; for a SATA controller, + from 0 to 29; for an SAS controller, from 0 to 7. + + + Device slot in the given port to attach the device to. This is only + relevant for IDE controllers, for which 0 specifies the master device and + 1 specifies the slave device. For all other controller types, this must + be 0. + + + Device type of the attached device. For media opened by + , this must match the device type + specified there. + + + + + + + Detaches the device attached to a device slot of the specified bus. + + Detaching the device from the virtual machine is deferred. This means + that the medium remains associated with the machine when this method + returns and gets actually de-associated only after a successful + call. See + for more detailed information about attaching media. + + + You cannot detach a device from a running machine. + + + Detaching differencing media implicitly created by for the indirect attachment using this + method will not implicitly delete them. The + operation should be + explicitly performed by the caller after the medium is successfully + detached and the settings are saved with + , if it is the desired action. + + + + Attempt to detach medium from a running virtual machine. + + + No medium attached to given slot/bus. + + + Medium format does not support storage deletion (only for implicitly + created differencing media, should not happen). + + + + + Name of the storage controller to detach the medium from. + + + Port number to detach the medium from. + + + Device slot number to detach the medium from. + + + + + + + Sets the passthrough mode of an existing DVD device. Changing the + setting while the VM is running is forbidden. The setting is only used + if at VM start the device is configured as a host DVD drive, in all + other cases it is ignored. The device must already exist; see + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the passthrough setting. + + + + + + + Sets the behavior for guest-triggered medium eject. In some situations + it is desirable that such ejects update the VM configuration, and in + others the eject should keep the VM configuration. The device must + already exist; see for how to + attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the eject behavior. + + + + + + + Sets a flag in the device information which indicates that the medium + is not based on rotational technology, i.e. that the access times are + more or less independent of the position on the medium. This may or may + not be supported by a particular drive, and is silently ignored in the + latter case. At the moment only hard disks (which is a misnomer in this + context) accept this setting. Changing the setting while the VM is + running is forbidden. The device must already exist; see + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the non-rotational device flag. + + + + + + + Sets a flag in the device information which indicates that the medium + supports discarding unused blocks (called trimming for SATA or unmap + for SCSI devices) .This may or may not be supported by a particular drive, + and is silently ignored in the latter case. At the moment only hard disks + (which is a misnomer in this context) accept this setting. Changing the + setting while the VM is running is forbidden. The device must already + exist; see for how to attach a new + device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, SCSI port out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the discard device flag. + + + + + + + Sets a flag in the device information which indicates that the attached + device is hot pluggable or not. This may or may not be supported by a + particular controller and/or drive, and is silently ignored in the + latter case. Changing the setting while the VM is running is forbidden. + The device must already exist; see + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + Controller doesn't support hot plugging. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the hot-pluggable device flag. + + + + + + + Sets the bandwidth group of an existing storage device. + The device must already exist; see + for how to attach a new device. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + New value for the bandwidth group or @c null for no group. + + + + + + + Sets no bandwidth group for an existing storage device. + The device must already exist; see + for how to attach a new device. + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to modify an unregistered virtual machine. + + + Invalid machine state. + + + + + Name of the storage controller. + + + Storage controller port. + + + Device slot in the given port. + + + + + + + Unmounts any currently mounted medium (, + identified by the given UUID @a id) to the given storage controller + (, identified by @a name), + at the indicated port and device. The device must already exist; + + This method is intended only for managing removable media, where the + device is fixed but media is changeable at runtime (such as DVDs + and floppies). It cannot be used for fixed media such as hard disks. + + The @a controllerPort and @a device parameters specify the device slot + and have have the same meaning as with + . + + The specified device slot must have a medium mounted, which will be + unmounted. If there is no mounted medium it will do nothing. + See for more detailed information about + attaching/unmounting media. + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to unmount medium that is not removable - not DVD or floppy. + + + Invalid machine state. + + + Medium already attached to this or another virtual machine. + + + Medium not attached to specified port, device, controller. + + + + + Name of the storage controller to unmount the medium from. + + + Port to unmount the medium from. + + + Device slot in the given port to unmount the medium from. + + + Allows to force unmount of a medium which is locked by + the device slot in the given port medium is attached to. + + + + + + + Mounts a medium (, identified + by the given UUID @a id) to the given storage controller + (, identified by @a name), + at the indicated port and device. The device must already exist; + see for how to attach a new device. + + This method is intended only for managing removable media, where the + device is fixed but media is changeable at runtime (such as DVDs + and floppies). It cannot be used for fixed media such as hard disks. + + The @a controllerPort and @a device parameters specify the device slot and + have have the same meaning as with . + + The specified device slot can have a medium mounted, which will be + unmounted first. Specifying a zero UUID (or an empty string) for + @a medium does just an unmount. + + See for more detailed information about + attaching media. + + + SATA device, SATA port, IDE port or IDE slot out of range. + + + Attempt to attach medium to an unregistered virtual machine. + + + Invalid machine state. + + + Medium already attached to this or another virtual machine. + + + + + Name of the storage controller to attach the medium to. + + + Port to attach the medium to. + + + Device slot in the given port to attach the medium to. + + + Medium to mount or @c null for an empty drive. + + + Allows to force unmount/mount of a medium which is locked by + the device slot in the given port to attach the medium to. + + + + + + + Returns the virtual medium attached to a device slot of the specified + bus. + + Note that if the medium was indirectly attached by + to the given device slot then this + method will return not the same object as passed to the + call. See for + more detailed information about mounting a medium. + + + No medium attached to given slot/bus. + + + + + Name of the storage controller the medium is attached to. + + + Port to query. + + + Device slot in the given port to query. + + + Attached medium object. + + + + + + + Returns an array of medium attachments which are attached to the + the controller with the given name. + + + A storage controller with given name doesn't exist. + + + + + + + + + + Returns a medium attachment which corresponds to the controller with + the given name, on the given port and device slot. + + + No attachment exists for the given controller/port/device combination. + + + + + + + + + + + + Attaches host PCI device with the given (host) PCI address to the + PCI bus of the virtual machine. Please note, that this operation + is two phase, as real attachment will happen when VM will start, + and most information will be delivered as IHostPCIDevicePlugEvent + on IVirtualBox event source. + + + + + Virtual machine state is not stopped (PCI hotplug not yet implemented). + + + Virtual machine does not have a PCI controller allowing attachment of physical devices. + + + Hardware or host OS doesn't allow PCI device passthrough. + + + + Address of the host PCI device. + + + Desired position of this device on guest PCI bus. + + + If VMM shall try to unbind existing drivers from the + device before attaching it to the guest. + + + + + + + Detach host PCI device from the virtual machine. + Also HostPCIDevicePlugEvent on IVirtualBox event source + will be delivered. As currently we don't support hot device + unplug, IHostPCIDevicePlugEvent event is delivered immediately. + + + + + Virtual machine state is not stopped (PCI hotplug not yet implemented). + + + This host device is not attached to this machine. + + + Virtual machine does not have a PCI controller allowing attachment of physical devices. + + + Hardware or host OS doesn't allow PCI device passthrough. + + + + Address of the host PCI device. + + + + + + + Returns the network adapter associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of adapters per machine is defined by the + property, + so the maximum slot number is one less than that property's value. + + + Invalid @a slot number. + + + + + + + + + + + Adds a new storage controller (SCSI, SAS or SATA controller) to the + machine and returns it as an instance of + . + + @a name identifies the controller for subsequent calls such as + , + , + , + or . + + After the controller has been added, you can set its exact + type by setting the . + + + A storage controller with given name exists already. + + + Invalid @a controllerType. + + + + + + + + + + + Returns a storage controller with the given name. + + + A storage controller with given name doesn't exist. + + + + + + + + + + Returns a storage controller of a specific storage bus + with the given instance number. + + + A storage controller with given instance number doesn't exist. + + + + + + + + + + + Removes a storage controller from the machine with all devices attached to it. + + + A storage controller with given name doesn't exist. + + + Medium format does not support storage deletion (only for implicitly + created differencing media, should not happen). + + + + + + + + + Sets the bootable flag of the storage controller with the given name. + + + A storage controller with given name doesn't exist. + + + Another storage controller is marked as bootable already. + + + + + + + + + + Adds a new USB controller to the machine and returns it as an instance of + . + + + A USB controller with given type exists already. + + + Invalid @a controllerType. + + + + + + + + + + + Removes a USB controller from the machine. + + + A USB controller with given type doesn't exist. + + + + + + + + + Returns a USB controller with the given type. + + + A USB controller with given name doesn't exist. + + + + + + + + + + Returns the number of USB controllers of the given type attached to the VM. + + + + + + + + + Returns the serial port associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of serial ports per machine is defined by the + property, + so the maximum slot number is one less than that property's value. + + + Invalid @a slot number. + + + + + + + + + + + Returns the parallel port associated with the given slot. + Slots are numbered sequentially, starting with zero. The total + number of parallel ports per machine is defined by the + property, + so the maximum slot number is one less than that property's value. + + + Invalid @a slot number. + + + + + + + + + + + Returns an array representing the machine-specific extra data keys + which currently have values defined. + + + Array of extra data keys. + + + + + + + Returns associated machine-specific extra data. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + + Settings file not accessible. + + + Could not parse the settings file. + + + + + Name of the data key to get. + + + Value of the requested data key. + + + + + + + Sets associated machine-specific extra data. + + If you pass @c null or an empty string as a key @a value, the given + @a key will be deleted. + + + Key must contain printable (non-control) UTF-8 characters only. + + + Before performing the actual data change, this method will ask all + registered event listeners using the + + notification for a permission. If one of the listeners refuses the + new value, the change will not be performed. + + + On success, the + notification + is called to inform all registered listeners about a successful data + change. + + + This method can be called outside the machine session and therefore + it's a caller's responsibility to handle possible race conditions + when several clients change the same key at the same time. + + + + Settings file not accessible. + + + Could not parse the settings file. + + + Key contains invalid characters. + + + + + Name of the data key to set. + + + Value to assign to the key. + + + + + + + Returns the virtual CPU boolean value of the specified property. + + + Invalid property. + + + + + + Property type to query. + + + + + Property value. + + + + + + + + Sets the virtual CPU boolean value of the specified property. + + + Invalid property. + + + + + + Property type to query. + + + + + Property value. + + + + + + + Used to enumerate CPUID information override values. + + + Invalid ordinal number is out of range. + + + + + The ordinal number of the leaf to get. + + + + + CPUID leaf index. + + + + + CPUID leaf sub-index. + + + + + CPUID leaf value for register eax. + + + + + CPUID leaf value for register ebx. + + + + + CPUID leaf value for register ecx. + + + + + CPUID leaf value for register edx. + + + + + + + Returns the virtual CPU cpuid information for the specified leaf. + + Currently supported index values for cpuid: + Standard CPUID leaves: 0 - 0x1f + Extended CPUID leaves: 0x80000000 - 0x8000001f + VIA CPUID leaves: 0xc0000000 - 0xc000000f + + See the Intel, AMD and VIA programmer's manuals for detailed information + about the CPUID instruction and its leaves. + + Invalid index. + + + + + + CPUID leaf index. + + + + + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + + + + + CPUID leaf value for register eax. + + + + + CPUID leaf value for register ebx. + + + + + CPUID leaf value for register ecx. + + + + + CPUID leaf value for register edx. + + + + + + + Sets the virtual CPU cpuid information for the specified leaf. Note that these values + are not passed unmodified. VirtualBox clears features that it doesn't support. + + Currently supported index values for cpuid: + Standard CPUID leaves: 0 - 0x1f + Extended CPUID leaves: 0x80000000 - 0x8000001f + VIA CPUID leaves: 0xc0000000 - 0xc000000f + + The subleaf index is only applicable to certain leaves (see manuals as this is + subject to change). + + See the Intel, AMD and VIA programmer's manuals for detailed information + about the cpuid instruction and its leaves. + + Do not use this method unless you know exactly what you're doing. Misuse can lead to + random crashes inside VMs. + + Invalid index. + + + + + + CPUID leaf index. + + + + + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + The 0xffffffff causes it to remove all other subleaves before adding one + with sub-index 0. + + + + + CPUID leaf value for register eax. + + + + + CPUID leaf value for register ebx. + + + + + CPUID leaf value for register ecx. + + + + + CPUID leaf value for register edx. + + + + + + + Removes the virtual CPU cpuid leaf for the specified index + + + Invalid index. + + + + + + CPUID leaf index. + + + + + CPUID leaf sub-index (ECX). Set to 0xffffffff (or 0) if not applicable. + The 0xffffffff value works like a wildcard. + + + + + + + Removes all the virtual CPU cpuid leaves + + + + + + + Returns the value of the specified hardware virtualization boolean property. + + + Invalid property. + + + + + + Property type to query. + + + + + Property value. + + + + + + + + Sets a new value for the specified hardware virtualization boolean property. + + + Invalid property. + + + + + + Property type to set. + + + + + New property value. + + + + + + + + Currently, it is an error to change this property on any machine. + Later this will allow setting a new path for the settings file, with + automatic relocation of all files (including snapshots and disk images) + which are inside the base directory. This operation is only allowed + when there are no pending unsaved settings. + + + Setting this property to @c null or to an empty string is forbidden. + When setting this property, the specified path must be absolute. + The specified path may not exist, it will be created when necessary. + + + + The operation is not implemented yet. + + + + + New settings file path, will be used to determine the new + location for the attached media if it is in the same directory or + below as the original settings file. + + + Progress object to track the operation completion. + + + + + + + Saves any changes to machine settings made since the session + has been opened or a new machine has been created, or since the + last call to or . + For registered machines, new settings become visible to all + other VirtualBox clients after successful invocation of this + method. + + The method sends + notification event after the configuration has been successfully + saved (only for registered machines). + + + Calling this method is only valid on instances returned + by and on new machines + created by but not + yet registered, or on unregistered machines after calling + . + + + + Settings file not accessible. + + + Could not parse the settings file. + + + Modification request refused. + + + + + + + + + Discards any changes to the machine settings made since the session + has been opened or since the last call to + or . + + Calling this method is only valid on instances returned + by and on new machines + created by or + opened by but not + yet registered, or on unregistered machines after calling + . + + + + Virtual machine is not mutable. + + + + + + + + + Unregisters a machine previously registered with + and optionally do additional + cleanup before the machine is unregistered. + + This method does not delete any files. It only changes the machine configuration and + the list of registered machines in the VirtualBox object. To delete the files which + belonged to the machine, including the XML file of the machine itself, call + , optionally with the array of IMedium objects which was returned + from this method. + + How thoroughly this method cleans up the machine configuration before unregistering + the machine depends on the @a cleanupMode argument. + +
    +
  • With "UnregisterOnly", the machine will only be unregistered, but no additional + cleanup will be performed. The call will fail if the machine has any snapshots or + any media attached (see ). It is the responsibility + of the caller to delete all such configuration in this mode. In this mode, the API + behaves like the former @c IVirtualBox::unregisterMachine() API which it replaces.
    • +
  • With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved" + state or if it has snapshots or media attached. All media attached to the current machine + state or in snapshots will be detached. No medium objects will be returned; + all of the machine's media will remain open.
    • +
  • With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone", + except that all the hard disk medium objects which were detached from the machine will + be returned as an array. This allows for quickly passing them to the + API for closing and deletion.
    • +
  • With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except + that all media will be returned in the array, including removable media like DVDs and + floppies. This might be useful if the user wants to inspect in detail which media were + attached to the machine. Be careful when passing the media array to + in that case because users will typically want to preserve ISO and RAW image files.
    • +
+ + A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the + resulting IMedium array to . This way, the machine is completely + deleted with all its saved states and hard disk images, but images for removable + drives (such as ISO and RAW files) will remain on disk. + + This API does not verify whether the media files returned in the array are still + attached to other machines (i.e. shared between several machines). If such a shared + image is passed to however, closing the image will fail there + and the image will be silently skipped. + + This API may, however, move media from this machine's media registry to other media + registries (see for details on media registries). For machines + created with VirtualBox 4.0 or later, if media from this machine's media registry + are also attached to another machine (shared attachments), each such medium will be + moved to another machine's registry. This is because without this machine's media + registry, the other machine cannot find its media any more and would become inaccessible. + + This API implicitly calls to save all current machine settings + before unregistering it. It may also silently call on other machines + if media are moved to other machines' media registries. + + After successful method invocation, the event + is fired. + + The call will fail if the machine is currently locked (see ). + + + If the given machine is inaccessible (see ), it + will be unregistered and fully uninitialized right afterwards. As a result, + the returned machine object will be unusable and an attempt to call + any method will return the "Object not ready" error. + + + + Machine is currently locked for a session. + + + + + How to clean up after the machine has been unregistered. + + + List of media detached from the machine, depending on the @a cleanupMode parameter. + + + + + + + Deletes the files associated with this machine from disk. If medium objects are passed + in with the @a aMedia argument, they are closed and, if closing was successful, their + storage files are deleted as well. For convenience, this array of media files can be + the same as the one returned from a previous call. + + This method must only be called on machines which are either write-locked (i.e. on instances + returned by ) or on unregistered machines (i.e. not yet + registered machines created by or opened by + , or after having called ). + + The following files will be deleted by this method: +
    +
  • If had been previously called with a @a cleanupMode + argument other than "UnregisterOnly", this will delete all saved state files that + the machine had in use; possibly one if the machine was in either the "Saved" or + "AbortedSaved" state and one for each online snapshot that the machine had.
    • +
  • On each medium object passed in the @a aMedia array, this will call + . If that succeeds, this will attempt to delete the + medium's storage on disk. Since the call will fail if the medium is still + in use, e.g. because it is still attached to a second machine; in that case the + storage will not be deleted.
    • +
  • Finally, the machine's own XML file will be deleted.
    • +
+ + Since deleting large disk image files can be a time-consuming I/O operation, this + method operates asynchronously and returns an IProgress object to allow the caller + to monitor the progress. There will be one sub-operation for each file that is + being deleted (saved state or medium storage file). + + + will return @c true after this + method successfully returns. + + + + Machine is registered but not write-locked. + + + Could not delete the settings file. + + + + List of media to be closed and whose storage files will be deleted. + + + Progress object to track the operation completion. + + + + + + Exports the machine to an OVF appliance. See for the + steps required to export VirtualBox machines to OVF. + + + + Appliance to export this machine to. + + + The target location. + + + VirtualSystemDescription object which is created for this machine. + + + + + + + Returns a snapshot of this machine with the given name or UUID. + + Returns a snapshot of this machine with the given UUID. + A @c null argument can be used to obtain the first snapshot + taken on this machine. To traverse the whole tree of snapshots + starting from the root, inspect the root snapshot's + attribute and recurse over those children. + + + Virtual machine has no snapshots or snapshot not found. + + + + + What to search for. Name or UUID of the snapshot to find + + + Snapshot object with the given name. + + + + + + + Creates a new permanent shared folder by associating the given logical + name with the given host path, adds it to the collection of shared + folders and starts sharing it. Refer to the description of + to read more about logical names. + + + Shared folder already exists. + + + Shared folder @a hostPath not accessible. + + + + + Unique logical name of the shared folder. + + + Full path to the shared folder in the host file system. + + + Whether the share is writable or read-only. + + + Whether the share gets automatically mounted by the guest + or not. + + + Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + + + + + + + + Removes the permanent shared folder with the given name previously + created by from the collection of + shared folders and stops sharing it. + + + Virtual machine is not mutable. + + + Shared folder @a name does not exist. + + + + + Logical name of the shared folder to remove. + + + + + + Returns @c true if the VM console process can activate the + console window and bring it to foreground on the desktop of + the host PC. + + This method will fail if a session for this machine is not + currently open. + + + + Machine session is not open. + + + + + + @c true if the console window can be shown and @c false otherwise. + + + + + + + Activates the console window and brings it to foreground on + the desktop of the host PC. Many modern window managers on + many platforms implement some sort of focus stealing + prevention logic, so that it may be impossible to activate + a window without the help of the currently active + application. In this case, this method will return a non-zero + identifier that represents the top-level window of the VM + console process. The caller, if it represents a currently + active process, is responsible to use this identifier (in a + platform-dependent manner) to perform actual window + activation. + + This method will fail if a session for this machine is not + currently open. + + + + Machine session is not open. + + + + + + Platform-dependent identifier of the top-level VM console + window, or zero if this method has performed all actions + necessary to implement the show window semantics for + the given platform and/or VirtualBox front-end. + + + + + + + + + Reads an entry from the machine's guest property store. + + + Machine session is not open. + + + + + + The name of the property to read. + + + + + The value of the property. If the property does not exist then this + will be empty. + + + + + The time at which the property was last modified, as seen by the + server process. + + + + + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. + + + + + + + Reads a value from the machine's guest property store. + + + Machine session is not open. + + + + + + The name of the property to read. + + + + + The value of the property. If the property does not exist then this + will be empty. + + + + + + + Reads a property timestamp from the machine's guest property store. + + + Machine session is not open. + + + + + + The name of the property to read. + + + + + The timestamp. If the property does not exist then this will be + empty. + + + + + + + + Sets, changes or deletes an entry in the machine's guest property + store. + + + Property cannot be changed. + + + Invalid @a flags. + + + Virtual machine is not mutable or session not open. + + + Cannot set transient property when machine not running. + + + + + + The name of the property to set, change or delete. + + + + + The new value of the property to set, change or delete. If the + property does not yet exist and value is non-empty, it will be + created. If the value is @c null or empty, the property will be + deleted if it exists. + + + + + Additional property parameters, passed as a comma-separated list of + "name=value" type entries. + + + + + + + Sets or changes a value in the machine's guest property + store. The flags field will be left unchanged or created empty for a + new property. + + + Property cannot be changed. + + + Virtual machine is not mutable or session not open. + + + Cannot set transient property when machine not running. + + + + + + The name of the property to set or change. + + + + + The new value of the property to set or change. If the + property does not yet exist and value is non-empty, it will be + created. + + + + + + + + Deletes an entry from the machine's guest property store. + + + Machine session is not open. + + + + + + The name of the property to delete. + + + + + + + Return a list of the guest properties matching a set of patterns along + with their values, timestamps and flags. + + + + The patterns to match the properties against, separated by '|' + characters. If this is empty or @c null, all properties will match. + + + + + The names of the properties returned. + + + + + The values of the properties returned. The array entries match the + corresponding entries in the @a name array. + + + + + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a name array. + + + + + The flags of the properties returned. The array entries match the + corresponding entries in the @a name array. + + + + + + + Returns the guest dimensions from the saved state. + + + + Saved guest screen to query info from. + + + + + The X position of the guest monitor top left corner. + + + + + The Y position of the guest monitor top left corner. + + + + + Guest width at the time of the saved state was taken. + + + + + Guest height at the time of the saved state was taken. + + + + + Whether the monitor is enabled in the guest. + + + + + + + Thumbnail is retrieved to an array of bytes in the requested format. + + + + Saved guest screen to read from. + + + + + The requested format. + + + + + Bitmap width. + + + + + Bitmap height. + + + + + Array with resulting bitmap data. + + + + + + + Returns available formats and size of the screenshot from saved state. + + + + Saved guest screen to query info from. + + + + + Image width. + + + + + Image height. + + + + + Formats supported by readSavedScreenshotToArray. + + + + + + + Screenshot in requested format is retrieved to an array of bytes. + + + + Saved guest screen to read from. + + + + + The requested format. + + + + + Image width. + + + + + Image height. + + + + + Array with resulting image data. + + + + + + + + Plugs a CPU into the machine. + + + + The CPU id to insert. + + + + + + + + Removes a CPU from the machine. + + + + The CPU id to remove. + + + + + + + + Returns the current status of the given CPU. + + + + The CPU id to check for. + + + + + Status of the CPU. + + + + + + + + Returns the effective paravirtualization provider for this VM. + + + + The effective paravirtualization provider for this VM. + + + + + + + + Queries for the VM log file name of an given index. Returns an empty + string if a log file with that index doesn't exists. + + + + Which log file name to query. 0=current log file. + + + + + On return the full path to the log file or an empty string on error. + + + + + + + Reads the VM log file. The chunk size is limited, so even if you + ask for a big piece there might be less data returned. + + + + Which log file to read. 0=current log file. + + + + + Offset in the log file. + + + + + Chunk size to read in the log file. + + + + + Data read from the log file. A data size of 0 means end of file + if the requested chunk size was not 0. This is the unprocessed + file data, i.e. the line ending style depends on the platform of + the system the server is running on. + + + + + + + + Creates a clone of this machine, either as a full clone (which means + creating independent copies of the hard disk media, save states and so + on), or as a linked clone (which uses its own differencing media, + sharing the parent media with the source machine). + + The target machine object must have been created previously with , and all the settings will be + transferred except the VM name and the hardware UUID. You can set the + VM name and the new hardware UUID when creating the target machine. The + network MAC addresses are newly created for all enabled network + adapters. You can change that behaviour with the options parameter. + The operation is performed asynchronously, so the machine object will + be not be usable until the @a progress object signals completion. + + + @a target is @c null. + + + + + Target machine object. + + + Which states should be cloned. + + + Options for the cloning operation. + + + Progress object to track the operation completion. + + + + + + + Move machine on to new place/folder + + + + Target folder where machine is moved. May be the same folder + where the VM already is located or the empty string, in which + case the machine is kept in this location and the disk images + and other files which are stored elsewhere are moved. + + + + Type of moving. + Possible values: + basic - Only the files which belong solely to this machine + are moved from the original machine's folder to + a new folder. + + + + + Progress object to track the operation completion. + + + + + + + Saves the current execution state of a running virtual machine + and stops its execution. + + After this operation completes, the machine will go to the + Saved state. The next time it is powered up this state will + be restored and the machine will continue its execution from + the place where it was saved. + + This operation differs from taking a snapshot to the effect + that it doesn't create new differencing media. Also, once + the machine is powered up from the state saved using this method, + the saved state is deleted, so it will be impossible to return + to this state later. + + + On success, this method implicitly calls + to save all current machine + settings (including runtime changes to the DVD medium, etc.). + Together with the impossibility to change any VM settings when it is + in the Saved state, this guarantees adequate hardware + configuration of the machine when it is restored from the saved + state file. + + + + The machine must be in the Running or Paused state, otherwise + the operation will fail. + + + Virtual machine state neither Running nor Paused. + + + Failed to create directory for saved state file. + + + + + + Progress object to track the operation completion. + + + + + + Associates the given saved state file to the virtual machine. + + On success, the machine will go to the Saved state. The next time it is + powered up it will be restored from the adopted saved state and + continue execution from the place where the saved state file was + created. + + The specified saved state file path may be absolute or relative to the + folder the VM normally saves the state to (usually, + ). + + + It's a caller's responsibility to make sure the given saved state + file is compatible with the settings of this virtual machine that + represent its virtual hardware (memory size, storage disk configuration + etc.). If there is a mismatch, the behavior of the virtual machine + is undefined. + + + Virtual machine state neither PoweredOff nor Aborted. + + + + Path to the saved state file to adopt. + + + + + + + Forcibly resets the machine to "Powered Off" state if it is + currently in the "Saved" state previously created by ) + or in the "AbortedSaved" state. The next time the machine is powered up + a clean boot will occur. + + This operation is equivalent to resetting or powering off + the machine without doing a proper shutdown of the guest + operating system; as with resetting a running phyiscal + computer, it can can lead to data loss. + + If @a fRemoveFile is @c true, the file in the machine directory + into which the machine state was saved is also deleted. If + this is @c false, then the state can be recovered and later + re-inserted into a machine using . + The location of the file can be found in the + attribute. + + Virtual machine not in either the Saved or AbortedSaved state. + + + + Whether to also remove the saved state file. + + + + + + + Saves the current execution state + and all settings of the machine and creates differencing images + for all normal (non-independent) media. + See for an introduction to snapshots. + + This method can be called for a PoweredOff, Saved (see + ), AbortedSaved, Running or + Paused virtual machine. When the machine is PoweredOff, an + offline snapshot is created. When the machine is Running a live + snapshot is created, and an online snapshot is created when Paused. + + The taken snapshot is always based on the + current snapshot + of the associated virtual machine and becomes a new current snapshot. + + + This method implicitly calls to + save all current machine settings before taking an offline snapshot. + + + + Virtual machine currently changing state. + + + + Short name for the snapshot. + + + Optional description of the snapshot. + + + Whether the VM should be paused while taking the snapshot. Only + relevant when the VM is running, and distinguishes between online + (@c true) and live (@c false) snapshots. When the VM is not running + the result is always an offline snapshot. + + + UUID of the snapshot which will be created. Useful for follow-up + operations after the snapshot has been created. + + + Progress object to track the operation completion. + + + + + + + Starts deleting the specified snapshot asynchronously. + See for an introduction to snapshots. + + The execution state and settings of the associated machine stored in + the snapshot will be deleted. The contents of all differencing media of + this snapshot will be merged with the contents of their dependent child + media to keep the medium chain valid (in other words, all changes + represented by media being deleted will be propagated to their child + medium). After that, this snapshot's differencing medium will be + deleted. The parent of this snapshot will become a new parent for all + its child snapshots. + + If the deleted snapshot is the current one, its parent snapshot will + become a new current snapshot. The current machine state is not directly + affected in this case, except that currently attached differencing + media based on media of the deleted snapshot will be also merged as + described above. + + If the deleted snapshot is the first or current snapshot, then the + respective IMachine attributes will be adjusted. Deleting the current + snapshot will also implicitly call + to make all current machine settings permanent. + + Deleting a snapshot has the following preconditions: + +
    +
  • Child media of all normal media of the deleted snapshot + must be accessible (see ) for this + operation to succeed. If only one running VM refers to all images + which participates in merging the operation can be performed while + the VM is running. Otherwise all virtual machines whose media are + directly or indirectly based on the media of deleted snapshot must + be powered off. In any case, online snapshot deleting usually is + slower than the same operation without any running VM.
    • + +
  • You cannot delete the snapshot if a medium attached to it has + more than one child medium (differencing images) because otherwise + merging would be impossible. This might be the case if there is + more than one child snapshot or differencing images were created + for other reason (e.g. implicitly because of multiple machine + attachments).
    • +
+ + The virtual machine's state is + changed to "DeletingSnapshot", "DeletingSnapshotOnline" or + "DeletingSnapshotPaused" while this operation is in progress. + + + Merging medium contents can be very time and disk space + consuming, if these media are big in size and have many + children. However, if the snapshot being deleted is the last + (head) snapshot on the branch, the operation will be rather + quick. + + + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + + + + UUID of the snapshot to delete. + + + Progress object to track the operation completion. + + + + + + + Starts deleting the specified snapshot and all its children + asynchronously. See for an introduction to + snapshots. The conditions and many details are the same as with + . + + This operation is very fast if the snapshot subtree does not include + the current state. It is still significantly faster than deleting the + snapshots one by one if the current state is in the subtree and there + are more than one snapshots from current state to the snapshot which + marks the subtree, since it eliminates the incremental image merging. + + This API method is right now not implemented! + + + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + + + The method is not implemented yet. + + + + UUID of the snapshot to delete, including all its children. + + + Progress object to track the operation completion. + + + + + + + Starts deleting the specified snapshot range. This is limited to + linear snapshot lists, which means there may not be any other child + snapshots other than the direct sequence between the start and end + snapshot. If the start and end snapshot point to the same snapshot this + method is completely equivalent to . See + for an introduction to snapshots. The + conditions and many details are the same as with + . + + This operation is generally faster than deleting snapshots one by one + and often also needs less extra disk space before freeing up disk space + by deleting the removed disk images corresponding to the snapshot. + + This API method is right now not implemented! + + + The running virtual machine prevents deleting this snapshot. This + happens only in very specific situations, usually snapshots can be + deleted without trouble while a VM is running. The error message + text explains the reason for the failure. + + + The method is not implemented yet. + + + + UUID of the first snapshot to delete. + + + UUID of the last snapshot to delete. + + + Progress object to track the operation completion. + + + + + + + Starts resetting the machine's current state to the state contained + in the given snapshot, asynchronously. All current settings of the + machine will be reset and changes stored in differencing media + will be lost. + See for an introduction to snapshots. + + After this operation is successfully completed, new empty differencing + media are created for all normal media of the machine. + + If the given snapshot is an online snapshot, the machine will go to + the Saved state, so that the + next time it is powered on, the execution state will be restored + from the state of the snapshot. + + + The machine must not be running, otherwise the operation will fail. + + + + If the machine is in the Saved + state prior to this operation, the saved state file will be implicitly + deleted (as if were + called). + + + + Virtual machine is running. + + + + The snapshot to restore the VM state from. + + + Progress object to track the operation completion. + + + + + + + Applies the defaults for the configured guest OS type. This is + primarily for getting sane settings straight after creating a + new VM, but it can also be applied later. + + + This is primarily a shortcut, centralizing the tedious job of + getting the recommended settings and translating them into + settings updates. The settings are made at the end of the call, + but not saved. + + + + General error. + + + The machine is in invalid state. + + + Some of the applied objects already exist. The method has been + called to already configured machine. + + + + + Additional flags, to be defined later. + + + + + + + Starts encryption of this VM. This means that the stored data of the VM is encrypted. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + + Encryption is not supported for various reasons e.g. unsupported cipher. + + + + + The current password the VM is protected with. Use an empty string to indicate + that the VM isn't encrypted. + + + + + The cipher to use for encryption. An empty string indicates no encryption for the + result. + + + + + The new password the VM should be protected with. An empty password and password ID + will result in the VM being encrypted with the current password. + + + + The ID of the new password when unlocking the VM. + + + + Force reencryption of the data if just password is changed. + Otherwise, if data already encrypted and cipher doesn't changed + only the password is changed. + + + + Progress object to track the operation completion. + + + + + + Returns the encryption settings for this VM. + + + Encryption is not configured for this VM. + + + + The cipher used for encryption. + + + The ID of the password when unlocking the VM. + + + + + + Checks whether the supplied password is correct for the VM. + + + Encryption is not configured for this VM. + + + The given password is incorrect. + + + + The password to check. + + + + + + Adds a password used for encryption. Updates the accesibility + state if password used the VM encryption. + + + The password provided wasn't correct for the VM using the provided + ID. + + + + + The identifier used for the password. Must match the identifier + used when the encrypted VM was created. + + + + The password. + + + + + + Adds passwords used for encryption. Updates the accesibility + state if the list contains password used the VM encryption. + + + The password provided wasn't correct for the VM using the provided + ID. + + + Id and passwords arrays have different size. + + + + + List of identifiers for the passwords. Must match the identifier + used when the encrypted VM was created. + + + + List of passwords. + + + + + + Removes a password used for the VM encryption/decryption. + The password can be removed only if the VM is powered off. + Removing the password causes the VM goes to the inaccessible + state and the password must be provided again. + + If machine becomes inaccessible all passwords are purged. + One has to add required passwords again using either + or + methods. + + + + The VM is not in proper state e.g powered on. + + + + The identifier used for the password. Must match the identifier + used when the encrypted VM was created. + + + + + + + Clears all provided VM passwords. + The passwords can be removed only if the VM is powered off. + Removing the passwords causes the VM goes to the inaccessible + state and the password must be provided again. + + + The VM is not in proper state e.g powered on. + + + + + + + + Manages emulated USB devices. + + + + + Attaches the emulated USB webcam to the VM, which will use a host video capture device. + + + The host path of the capture device to use. + + + Optional settings. + + + + + + Detaches the emulated USB webcam from the VM + + + The host path of the capture device to detach. + + + + + Lists attached virtual webcams. + + + + + + + + Contains information about the remote desktop (VRDE) server capabilities and status. + This is used in the attribute. + + + + + Whether the remote desktop connection is active. + + + + + + VRDE server port number. If this property is equal to 0, then + the VRDE server failed to start, usually because there are no free IP + ports to bind to. If this property is equal to -1, then the VRDE + server has not yet been started. + + + + + + How many times a client connected. + + + + + + When the last connection was established, in milliseconds since 1970-01-01 UTC. + + + + + + When the last connection was terminated or the current time, if + connection is still active, in milliseconds since 1970-01-01 UTC. + + + + + + How many bytes were sent in last or current, if still active, connection. + + + + + + How many bytes were sent in all connections. + + + + + + How many bytes were received in last or current, if still active, connection. + + + + + + How many bytes were received in all connections. + + + + + + Login user name supplied by the client. + + + + + + Login domain name supplied by the client. + + + + + + The client name supplied by the client. + + + + + + The IP address of the client. + + + + + + The client software version number. + + + + + + Public key exchange method used when connection was established. + Values: 0 - RDP4 public key exchange scheme. + 1 - X509 certificates were sent to client. + + + + + + + + The IConsole interface represents an interface to control virtual + machine execution. + + A console object gets created when a machine has been locked for a + particular session (client process) using + or . The console object can + then be found in the session's attribute. + + Methods of the IConsole interface allow the caller to query the current + virtual machine execution state, pause the machine or power it down, save + the machine state or take a snapshot, attach and detach removable media + and so on. + + + + + + + Machine object for this console session. + + This is a convenience property, it has the same value as + of the corresponding session + object. + + + + + + + Current execution state of the machine. + + This property always returns the same value as the corresponding + property of the IMachine object for this console session. + For the process that owns (executes) the VM, this is the + preferable way of querying the VM state, because no IPC + calls are made. + + + + + + Guest object. + + + + + Virtual keyboard object. + + If the machine is not running, any attempt to use + the returned object will result in an error. + + + + + + + Virtual mouse object. + + If the machine is not running, any attempt to use + the returned object will result in an error. + + + + + + Virtual display object. + + If the machine is not running, any attempt to use + the returned object will result in an error. + + + + + + Debugging interface. + + + + + Collection of USB devices currently attached to the virtual + USB controller. + + The collection is empty if the machine is not running. + + + + + + + List of USB devices currently attached to the remote VRDE client. + Once a new device is physically attached to the remote host computer, + it appears in this list and remains there until detached. + + + + + + Collection of shared folders for the current session. These folders + are called transient shared folders because they are available to the + guest OS running inside the associated virtual machine only for the + duration of the session (as opposed to + which represent permanent shared + folders). When the session is closed (e.g. the machine is powered down), + these folders are automatically discarded. + + New shared folders are added to the collection using + . Existing shared folders can be + removed using . + + + + + + Interface that provides information on Remote Desktop Extension (VRDE) connection. + + + + + + Event source for console events. + + + + + Array of PCI devices attached to this machine. + + + + + Whether the guest clipboard should be connected to the host one or + whether it should only be allowed access to the VRDE clipboard. This + setting may not affect existing guest clipboard connections which + are already connected to the host clipboard. + + + + + + Interface that manages emulated USB devices. + + + + + + + Starts the virtual machine execution using the current machine + state (that is, its current execution state, current settings and + current storage devices). + + + This method is only useful for front-ends that want to actually + execute virtual machines in their own process (like the VirtualBox + or VBoxSDL front-ends). Unless you are intending to write such a + front-end, do not call this method. If you simply want to + start virtual machine execution using one of the existing front-ends + (for example the VirtualBox GUI or headless server), use + instead; these + front-ends will power up the machine automatically for you. + + + If the machine is powered off or aborted, the execution will + start from the beginning (as if the real hardware were just + powered on). + + If the machine is in the state or the + state it will continue its + execution from the point where the state was saved. + + If the machine property is + enabled on the machine being powered up, the machine will wait for an + incoming teleportation in the + state. The returned progress object will have at least three + operations where the last three are defined as: (1) powering up and + starting TCP server, (2) waiting for incoming teleportations, and + (3) perform teleportation. These operations will be reflected as the + last three operations of the progress objected returned by + as well. + + + + + Virtual machine already running. + + + Host interface does not exist or name not set. + + + Invalid saved state file. + + + + Progress object to track the operation completion. + + + + + + + Identical to powerUp except that the VM will enter the + state, instead of + . + + + + Virtual machine already running. + + + Host interface does not exist or name not set. + + + Invalid saved state file. + + + + Progress object to track the operation completion. + + + + + + + Initiates the power down procedure to stop the virtual machine + execution. + + The completion of the power down procedure is tracked using the returned + IProgress object. After the operation is complete, the machine will go + to the PoweredOff state. + + Virtual machine must be Running, Paused or Stuck to be powered down. + + + + Progress object to track the operation completion. + + + + + + Resets the virtual machine. + + Virtual machine not in Running state. + + + Virtual machine error in reset operation. + + + + + + + Pauses the virtual machine execution. + + Virtual machine not in Running state. + + + Virtual machine error in suspend operation. + + + + + + + Resumes the virtual machine execution. + + Virtual machine not in Paused state. + + + Virtual machine error in resume operation. + + + + + + + Sends the ACPI power button event to the guest. + + Virtual machine not in Running state. + + + Controlled power off failed. + + + + + + + Sends the ACPI sleep button event to the guest. + + Virtual machine not in Running state. + + + Sending sleep button event failed. + + + + + + Checks if the last power button event was handled by guest. + + Checking if the event was handled by the guest OS failed. + + + + + + + Checks if the guest entered the ACPI mode G0 (working) or + G1 (sleeping). If this method returns @c false, the guest will + most likely not respond to external ACPI events. + + Virtual machine not in Running state. + + + + + + + + Gets the current activity type of given devices or device groups. + + Invalid device type. + + + + + + + + + + Attaches a host USB device with the given UUID to the + USB controller of the virtual machine. + + The device needs to be in one of the following states: + , + or + , + otherwise an error is immediately returned. + + When the device state is + Busy, an error may also + be returned if the host computer refuses to release it for some reason. + + , + + + Virtual machine state neither Running nor Paused. + + + Virtual machine does not have a USB controller. + + + + UUID of the host USB device to attach. + + + Filename to capture the USB traffic to. + + + + + + + Detaches a USB device with the given UUID from the USB controller + of the virtual machine. + + After this method succeeds, the VirtualBox server re-initiates + all USB filters as if the device were just physically attached + to the host, but filters of this machine are ignored to avoid + a possible automatic re-attachment. + + , + + + + Virtual machine does not have a USB controller. + + + USB device not attached to this virtual machine. + + + + UUID of the USB device to detach. + + + Detached USB device. + + + + + + + Searches for a USB device with the given host address. + + + Given @c name does not correspond to any USB device. + + + + + + + Address of the USB device (as assigned by the host) to + search for. + + + + Found USB device object. + + + + + + + Searches for a USB device with the given UUID. + + + Given @c id does not correspond to any USB device. + + + + + + UUID of the USB device to search for. + + + Found USB device object. + + + + + + + Creates a transient new shared folder by associating the given logical + name with the given host path, adds it to the collection of shared + folders and starts sharing it. Refer to the description of + to read more about logical names. + + + Virtual machine is in the Saved or AbortedSaved state or currently changing state. + + + Shared folder already exists or not accessible. + + + + Unique logical name of the shared folder. + + + Full path to the shared folder in the host file system. + + + Whether the share is writable or readonly + + + Whether the share gets automatically mounted by the guest + or not. + + + Where the guest should automatically mount the folder, if possible. + For Windows and OS/2 guests this should be a drive letter, while other + guests it should be a absolute directory. + + + + + + + + Removes a transient shared folder with the given name previously + created by from the collection of + shared folders and stops sharing it. + + Virtual machine is in the Saved or AbortedSaved state or currently changing state. + + + Shared folder does not exists. + + + + Logical name of the shared folder to remove. + + + + + + Teleport the VM to a different host machine or process. + + @todo Explain the details. + + + Virtual machine not running or paused. + + + + The name or IP of the host to teleport to. + + + The TCP port to connect to (1..65535). + + + The password. + + + + The maximum allowed downtime given as milliseconds. 0 is not a valid + value. Recommended value: 250 ms. + + The higher the value is, the greater the chance for a successful + teleportation. A small value may easily result in the teleportation + process taking hours and eventually fail. + + + The current implementation treats this a guideline, not as an + absolute rule. + + + + + Progress object to track the operation completion. + + + + + + + Adds a password used for encryption/decryption. + + + The password provided wasn't correct for at least one disk using the provided + ID. + + + + + The identifier used for the password. Must match the identifier + used when the encrypted medium was created. + + + + The password. + + + + Flag whether to clear the password on VM suspend (due to a suspending host + for example). The password must be supplied again before the VM can resume. + + + + + + + + Adds a password used for encryption/decryption. + + + The password provided wasn't correct for at least one disk using the provided + ID. + + + + + List of identifiers for the passwords. Must match the identifier + used when the encrypted medium was created. + + + + List of passwords. + + + + Flag whether to clear the given passwords on VM suspend (due to a suspending host + for example). The passwords must be supplied again before the VM can resume. + + + + + + + + Removes a password used for hard disk encryption/decryption from + the running VM. As soon as the medium requiring this password + is accessed the VM is paused with an error and the password must be + provided again. + + + + The identifier used for the password. Must match the identifier + used when the encrypted medium was created. + + + + + + + Clears all provided supplied encryption passwords. + + + + + + + + + Type of encapsulation. Ethernet encapsulation includes both wired and + wireless Ethernet connections. + + + + + + The type of interface cannot be determined. + + + + + Ethernet frame encapsulation. + + + + + Point-to-point protocol encapsulation. + + + + + Serial line IP encapsulation. + + + + + + + + Current status of the interface. + + + + + + The state of interface cannot be determined. + + + + + The interface is fully operational. + + + + + The interface is not functioning. + + + + + + + Network interface type. + + + + + + + + Represents one of host's network interfaces. IP V6 address and network + mask are strings of 32 hexadecimal digits grouped by four. Groups are + separated by colons. + For example, fe80:0000:0000:0000:021e:c2ff:fed2:b030. + + + Returns the host network interface name. + + + + Returns the host network interface short name. + + + + Returns the interface UUID. + + + + Returns the name of a virtual network the interface gets attached to. + + + + Specifies whether the DHCP is enabled for the interface. + + + + Returns the IP V4 address of the interface. + + + + Returns the network mask of the interface. + + + + Specifies whether the IP V6 is supported/enabled for the interface. + + + + Returns the IP V6 address of the interface. + + + + Returns the length IP V6 network mask prefix of the interface. + + + + Returns the hardware address. For Ethernet it is MAC address. + + + + Type of protocol encapsulation used. + + + + Status of the interface. + + + + specifies the host interface type. + + + + Specifies whether the interface is wireless. + + + + sets and enables the static IP V4 configuration for the given interface. + + + IP address. + + + + + network mask. + + + + + + sets and enables the static IP V6 configuration for the given interface. + + + IP address. + + + + + network mask. + + + + + + enables the dynamic IP configuration. + + + + refreshes the IP configuration for DHCP-enabled interface. + + + + + + + Represents one of host's video capture devices, for example a webcam. + + + + User friendly name. + + + + The host path of the device. + + + + An alias which can be used for + + + + + + + No channel specified. Do not use this. + + + All stable releases (maintenance and minor releases within the same major release). + + + All stable releases, including major versions. + + + All stable and major releases, including beta versions. + + + All stable, major and beta releases, including testing versions. + + + + + + No severity specified. Do not use this. + + + Update contains critical patches. + + + Update contains a major version. + + + Update contains a minor version. + + + Update contains a testing version. Use with caution! + + + + + + Invalid / not set update state. + + + An uppdate is available. + + + No update available. + + + Update is being downloaded currently. + + + Update has been successfully downloaded. + + + Update is being installed currently. + + + Update has been successfully installed. + + + Update requires user interaction to continue. + + + Update has been canceled. + + + Update service currently is in maintenance mode. + + + An error occurred while updating. + + + + + + + Abstract parent interface for handling updateable software components. + + + + + + Checks for an update. + + + Progress object to track operation completion. + + + + + + Downloads the update. + + + Downloading update not supported. + + + Progress object to track operation completion. + + + + + + Installs the update. + + + Installing update not supported. + + + Progress object to track operation completion. + + + + + + Rolls back installing the update. + + + Rolling back update not supported. + + + + + + Name of the update component. + + + + + + Event source for update agent events. + + + + + + Order hint the update component needs to run at, in conjunction with other update components. + + + No order preferred / disabled. + + + Lower numbers mean higher priority. 0 means no order or disabled. + + + + + + Array of other update component names this component depends on before being able to get installed. + + + Ordered entries, highest priority first. No dependencies when array is empty. + Dependency entries also can contain a minimum version number after the update component name, separated by an "@", + e.g. "Guest Additions@7.1.0_BETA2". + + + + + + Result not available yet. + + + Version the update contains. + + + + + + Result not available yet. + + + Download URL of the update. + + + + + + Result not available yet. + + + Web URL of the update. + + + + + + Result not available yet. + + + Release notes of the update. + + + + + + Enables or disables the update component. + + + + + + Whether the update component shall be hidden from the user or not. + + + + + + Returns the current update state. + + + + + + The update check frequency (in seconds). + + + + + + Update channel to use for checking for updates. + + + + + + Update repository URL to use for retrieving the update. + + + Only repositories with the https:// URL scheme are allowed. + + + + + + Date of last update check. + + + In ISO 8601 format (e.g. 2020-05-11T21:13:39.348416000Z). + + + + + + How many times the update check has happened already. + + + + + + Returns @c TRUE if an update check is needed, or @c FALSE if not. + + Compares the system's current date with the last + update check date and currently set check frequency. + + + + + + Returns a safe array of all supported update channels this agents offers. + + + + + + + + Implementation of the object + for VirtualBox host updates. + + + If no proxy is explicitly set, the proxy settings from will be used. + + + + + + + The IHostDrivePartition interface represents the partition of the host drive. + To enumerate all available drives partitions in the host, use the + attribute. + + + + + The number of the partition. Represents the system number of the + partition, e.g. /dev/sdX in the linux, where X is the number + returned. + + + + + + The partition size in bytes. + + + + + + The start byte offset of this partition in bytes relative to the + beginning of the hard disk. + + + + + + A translation of and + when possible, otherwise + set to . + + + + + + The partition is bootable when TRUE. + + + + + + + + The raw MBR partition type, 0 for non-MBR disks. + + + + + + The cylinder (0..1023) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + + + + + + The head (0..255) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + + + + + + The sector (0..63) of the first sector in the partition on an MBR disk, zero for not an MBR disk. + + + + + + The cylinder (0..1023) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + + + + + + The head (0..255) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + + + + + + The sector (1..63) of the last sector (inclusive) in the partition on an MBR disk, zero for not an MBR disk. + + + + + + + + The partition type when GUID partitioning scheme is used, NULL UUID value for not a GPT disks. + + + + + + The GUID of the partition when GUID partitioning scheme is used, NULL UUID value for not a GPT disks. + + + + + + The name of the partition if GPT partitioning is used, empty if not a GPT disk. + + + + + + + + The IHostDrive interface represents the drive of the physical machine. + It is not a complete medium description and, therefore, it is not IMedium + based. The interface is used to get information about a host drive and + its partitioning. + + The object operates in limited mode if the user cannot open the drive + and parse the partition table. In limited mode on the + and + attributes can be accessed, the rest will fail with E_ACCESSDENIED. + + + + + + The path of the drive. Platform dependent. + + + + + + The scheme of the partitions the disk has. + + + + + + The GUID of the disk. + + + + + + The size of the sector in bytes. + + + + + + The size of the disk in bytes. + + + + + + The model string of the drive if available. + + + + + List of partitions available on the host drive. + + + + + + + The IHost interface represents the physical machine that this VirtualBox + installation runs on. + + An object implementing this interface is returned by the + attribute. This interface contains + read-only information about the host's physical hardware (such as what + processors and disks are available, what the host operating system is, + and so on) and also allows for manipulating some of the host's hardware, + such as global USB device filters and host interface networking. + + + + List of DVD drives available on the host. + + + + List of floppy drives available on the host. + + + + List of audio devices currently available on the host. + + This attribute is not implemented yet. + + + + + + + List of USB devices currently attached to the host. + Once a new device is physically attached to the host computer, + it appears in this list and remains there until detached. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + + + + + List of USB device filters in action. + When a new device is physically attached to the host computer, + filters from this list are applied to it (in order they are stored + in the list). The first matched filter will determine the + action + performed on the device. + + Unless the device is ignored by these filters, filters of all + currently running virtual machines + () are applied to it. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + , + + + + + + List of host network interfaces currently defined on the host. + + + + The list of nameservers registered in host's name resolving system. + + + + Domain name used for name resolving. + + + + Search string registered for name resolving. + + + + Number of (logical) CPUs installed in the host system. + + + + Number of (logical) CPUs online in the host system. + + + + Number of physical processor cores installed in the host system. + + + + Number of physical processor cores online in the host system. + + + + List of the host drive available to use in the VirtualBox. + + + + Query the (approximate) maximum speed of a specified host CPU in + Megahertz. + + + + Identifier of the CPU. + + + + + Speed value. 0 is returned if value is not known or @a cpuId is + invalid. + + + + + + Query whether a CPU feature is supported or not. + + + CPU Feature identifier. + + + + + Feature is supported or not. + + + + + + Query the model string of a specified host CPU. + + + + Identifier of the CPU. + + The current implementation might not necessarily return the + description for this exact CPU. + + + + + + Model string. An empty string is returned if value is not known or + @a cpuId is invalid. + + + + + + + Returns the CPU cpuid information for the specified leaf. + + + + Identifier of the CPU. The CPU most be online. + + The current implementation might not necessarily return the + description for this exact CPU. + + + + + + CPUID leaf index (eax). + + + + + CPUID leaf sub index (ecx). This currently only applies to cache + information on Intel CPUs. Use 0 if retrieving values for + . + + + + + CPUID leaf value for register eax. + + + + + CPUID leaf value for register ebx. + + + + + CPUID leaf value for register ecx. + + + + + CPUID leaf value for register edx. + + + + + + Amount of system memory in megabytes installed in the host system. + + + + Available system memory in the host system. + + + + Name of the host system's operating system. + + + + Host operating system's version string. + + + + Returns the current host time in milliseconds since 1970-01-01 UTC. + + + + Returns @c true when the host supports 3D hardware acceleration. + + + + + Creates a new adapter for Host Only Networking. + + Host network interface @a name already exists. + + + + + Created host interface object. + + + + + Progress object to track the operation completion. + + + + + + + Removes the given Host Only Networking interface. + + No host network interface matching @a id found. + + + + + Adapter GUID. + + + + + Progress object to track the operation completion. + + + + + + + Creates a new USB device filter. All attributes except + the filter name are set to empty (any match), + active is @c false (the filter is not active). + + The created filter can be added to the list of filters using + . + + + + + + Filter name. See for more information. + + + + Created filter object. + + + + + + Inserts the given USB device to the specified position + in the list of filters. + + Positions are numbered starting from @c 0. If the specified + position is equal to or greater than the number of elements in + the list, the filter is added at the end of the collection. + + + Duplicates are not allowed, so an attempt to insert a + filter already in the list is an error. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + + + + USB device filter is not created within this VirtualBox instance. + + + USB device filter already in list. + + + + + Position to insert the filter to. + + + USB device filter to insert. + + + + + + Removes a USB device filter from the specified position in the + list of filters. + + Positions are numbered starting from @c 0. Specifying a + position equal to or greater than the number of elements in + the list will produce an error. + + + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + + + + + + USB device filter list empty or invalid @a position. + + + + + Position to remove the filter from. + + + + + + Searches for a host DVD drive with the given @c name. + + + Given @c name does not correspond to any host drive. + + + + + Name of the host drive to search for + + + Found host drive object + + + + + + Searches for a host floppy drive with the given @c name. + + + Given @c name does not correspond to any host floppy drive. + + + + + Name of the host floppy drive to search for + + + Found host floppy drive object + + + + + + Searches through all host network interfaces for an interface with + the given @c name. + + The method returns an error if the given @c name does not + correspond to any host network interface. + + + + Name of the host network interface to search for. + + + Found host network interface object. + + + + + Searches through all host network interfaces for an interface with + the given GUID. + + The method returns an error if the given GUID does not + correspond to any host network interface. + + + + GUID of the host network interface to search for. + + + Found host network interface object. + + + + + Searches through all host network interfaces and returns a list of interfaces of the specified type + + + type of the host network interfaces to search for. + + + Found host network interface objects. + + + + + + Searches for a USB device with the given UUID. + + + Given @c id does not correspond to any USB device. + + + + + + UUID of the USB device to search for. + + + Found USB device object. + + + + + + Searches for a USB device with the given host address. + + + Given @c name does not correspond to any USB device. + + + + + + + Address of the USB device (as assigned by the host) to + search for. + + + + Found USB device object. + + + + + + Generates a valid Ethernet MAC address, 12 hexadecimal characters. + + + New Ethernet MAC address. + + + + + List of currently available host video capture devices. + + + + + Adds a new USB device source. + + + The backend to use as the new device source. + + + Unique ID to identify the source. + + + + Address to use, the format is dependent on the backend. + For USB/IP backends for example the notation is host[:port]. + + + + Array of property names for more detailed configuration. Not used at the moment. + + + Array of property values for more detailed configuration. Not used at the moment. + + + + + + Removes a previously added USB device source. + + + The identifier used when the source was added. + + + + + Checks for new VirtualBox host versions. + + + + Checks for new VirtualBox Extension Pack versions. + + + + Checks for new Guest Additions versions. + + + + + + + CPU profile. Immutable. + + The name. + + + The full name. + + + The CPU architecture. + + + + + + + Proxy setting: System (default), NoProxy and Manual. + + Use the system proxy settings as far as possible. + + + Direct connection to the Internet. + + + Use the manual proxy from . + + + + + + The ISystemProperties interface represents global properties of the given + VirtualBox installation. + + These properties define limits and default values for various attributes + and parameters. Most of the properties are read-only, but some can be + changed by a user. + + + + Minimum guest system memory in Megabytes. + + + + Maximum guest system memory in Megabytes. + + + + Minimum guest video memory in Megabytes. + + + + Maximum guest video memory in Megabytes. + + + + Minimum CPU count. + + + + Maximum CPU count. + + + + Maximum of monitors which could be connected. + + + + Maximum size of a virtual disk image in bytes. Informational value, + does not reflect the limits of any virtual disk image format. + + + + + Maximum number of serial ports associated with every + instance. + + + + + + Maximum number of parallel ports associated with every + instance. + + + + + + Maximum device position in the boot order. This value corresponds + to the total number of devices a machine can boot from, to make it + possible to include all possible devices to the boot list. + + + + + + + Indicates whether VirtualBox was built with raw-mode support. + + When this reads as False, the + setting will be ignored and assumed to be True. + + + + + + Exclusive use of hardware virtualization by VirtualBox. When enabled, + VirtualBox assumes it can obtain full and exclusive access to the VT-x + or AMD-V feature of the host. To share hardware virtualization with + other hypervisors, this property must be disabled. + + This is ignored on OS X, the kernel mediates hardware + access there. + + + + + + Full path to the default directory used to create new or open + existing machines when a machine settings file name contains no + path. + + Starting with VirtualBox 4.0, by default, this attribute contains + the full path of folder named "VirtualBox VMs" in the user's + home directory, which depends on the host platform. + + When setting this attribute, a full path must be specified. + Setting this property to @c null or an empty string or the + special value "Machines" (for compatibility reasons) will restore + that default value. + + If the folder specified herein does not exist, it will be created + automatically as needed. + + + , + + + + + + + + Specifies the logging level in current use by VirtualBox. + + + + + + List of all medium storage formats supported by this VirtualBox + installation. + + Keep in mind that the medium format identifier + () used in other API calls like + to refer to a particular + medium format is a case-insensitive string. This means that, for + example, all of the following strings: + 
+          "VDI"
+          "vdi"
+          "VdI"
+ refer to the same medium format. + + Note that the virtual medium framework is backend-based, therefore + the list of supported formats depends on what backends are currently + installed. + + + + + + + + Identifier of the default medium format used by VirtualBox. + + The medium format set by this attribute is used by VirtualBox + when the medium format was not specified explicitly. One example is + with the empty + format argument. A more complex example is implicit creation of + differencing media when taking a snapshot of a virtual machine: + this operation will try to use a format of the parent medium first + and if this format does not support differencing media the default + format specified by this argument will be used. + + The list of supported medium formats may be obtained by the + call. Note that the default medium + format must have a capability to create differencing media; + otherwise operations that create media implicitly may fail + unexpectedly. + + The initial value of this property is "VDI" in the current + version of the VirtualBox product, but may change in the future. + + + Setting this property to @c null or empty string will restore the + initial value. + + + + , + , + + + + + + + Issue a warning if the free disk space is below (or in some disk + intensive operation is expected to go below) the given size in + bytes. + + + + Issue a warning if the free disk space is below (or in some disk + intensive operation is expected to go below) the given percentage. + + + + Issue an error if the free disk space is below (or in some disk + intensive operation is expected to go below) the given size in + bytes. + + + + Issue an error if the free disk space is below (or in some disk + intensive operation is expected to go below) the given percentage. + + + + + Library that provides authentication for Remote Desktop clients. The library + is used if a virtual machine's authentication type is set to "external" + in the VM RemoteDisplay configuration. + + The system library extension (".DLL" or ".so") must be omitted. + A full path can be specified; if not, then the library must reside on the + system's default library path. + + The default value of this property is "VBoxAuth". There is a library + of that name in one of the default VirtualBox library directories. + + For details about VirtualBox authentication libraries and how to implement + them, please refer to the VirtualBox manual. + + + Setting this property to @c null or empty string will restore the + initial value. + + + + + + + Library that provides authentication for webservice clients. The library + is used if a virtual machine's authentication type is set to "external" + in the VM RemoteDisplay configuration and will be called from + within the implementation. + + As opposed to , + there is no per-VM setting for this, as the webservice is a global + resource (if it is running). Only for this setting (for the webservice), + setting this value to a literal "null" string disables authentication, + meaning that will always succeed, + no matter what user name and password are supplied. + + The initial value of this property is "VBoxAuth", + meaning that the webservice will use the same authentication + library that is used by default for VRDE (again, see + ). + The format and calling convention of authentication libraries + is the same for the webservice as it is for VRDE. + + + Setting this property to @c null or empty string will restore the + initial value. + + + + + + + The name of the extension pack providing the default VRDE. + + This attribute is for choosing between multiple extension packs + providing VRDE. If only one is installed, it will automatically be the + default one. The attribute value can be empty if no VRDE extension + pack is installed. + + For details about VirtualBox Remote Desktop Extension and how to + implement one, please refer to the VirtualBox SDK. + + + + + + The name of the extension pack providing the default cryptographic support + for full VM encryption. + + This attribute is for choosing between multiple extension packs + providing cryptographic support. If only one is installed, it will automatically be the + default one. The attribute value can be empty if no cryptographic extension + pack is installed. + + + + + + This value specifies how many old release log files are kept. + + + + + This value hold the default audio driver for the current + system. + + + + + The path to the autostart database. Depending on the host this might + be a filesystem path or something else. + + + + + + The path to the default Guest Additions ISO image. Can be empty if + the location is not known in this installation. + + + + + + Selects which VM frontend should be used by default when launching + a VM through the method. + Empty or @c null strings do not define a particular default, it is up + to to select one. See the + description of for the valid + frontend types. + + This global setting is overridden by the per-VM attribute + or a frontend type + passed to . + + + + + + Supported bitmap formats which can be used with takeScreenShot + and takeScreenShotToArray methods. + + + + + The proxy mode setting: System, NoProxy or Manual. + + + + + Proxy server URL for the proxy mode. + + The format is: [{type}"://"][{userid}[:{password}]@]{server}[":"{port}] + + Valid types are: http (default), https, socks4, socks4a, socks5, socks5h and direct. + Please note that these are proxy types defining how the proxy operates rather than + how to proxy any similarly named protocol (i.e. don't confuse a http-proxy with + proxying the http protocol, as a http-proxy usually can proxy https and other protocols too). + + The port number defaults to 80 for http, 443 for https and 1080 for the socks ones. + + The password is currently stored as plain text! Use the + mode if you consider the proxy password to be sensitive. + + An empty string will cause the behavior to be identical to . + For compatibility with libproxy, an URL starting with "direct://" will cause + behavior. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported audio codec values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported video codec values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + Returns an array of officially supported values for enum , + in the sense of what is e.g. worth offering in the VirtualBox GUI. + + + + + + The API language ID used to translate messages to client. + + + + + + Maximum total number of network adapters associated with every + instance. + + + + The chipset type to get the value for. + + + + + The maximum total number of network adapters allowed. + + + + + + + Maximum number of network adapters of a given attachment type, + associated with every instance. + + + + The chipset type to get the value for. + + + + Type of attachment. + + + + The maximum number of network adapters allowed for + particular chipset and attachment type. + + + + + + + Returns the maximum number of devices which can be attached to a port + for the given storage bus. + + + The storage bus type to get the value for. + + + + The maximum number of devices which can be attached to the port for the given + storage bus. + + + + + Returns the minimum number of ports the given storage bus supports. + + + The storage bus type to get the value for. + + + + The minimum number of ports for the given storage bus. + + + + + Returns the maximum number of ports the given storage bus supports. + + + The storage bus type to get the value for. + + + + The maximum number of ports for the given storage bus. + + + + + Returns the maximum number of storage bus instances which + can be configured for each VM. This corresponds to the number of + storage controllers one can have. Value may depend on chipset type + used. + + + The chipset type to get the value for. + + + + The storage bus type to get the value for. + + + + The maximum number of instances for the given storage bus. + + + + + Returns list of all the supported device types + () for the given type of storage + bus. + + + The storage bus type to get the value for. + + + + The list of all supported device types for the given storage bus. + + + + + Returns the enum value + for a given storage controller type. + + + The storage controller type to get the value for. + + + + The storage bus which is applicable. + + + + + Returns the possible enum values + for a given storage bus. + + + The storage bus type to get the values for. + + + + The enum values (sorted by what should be a sensible decreasing + importance of the type) which are valid. + + + + + Returns the default I/O cache setting for the + given storage controller + + + The storage controller type to get the setting for. + + + + Returned flag indicating the default value + + + + + Returns whether the given storage controller supports + hot-plugging devices. + + + The storage controller to check the setting for. + + + + Returned flag indicating whether the controller is hotplug capable + + + + + Returns the maximum number of USB controller instances which + can be configured for each VM. This corresponds to the number of + USB controllers one can have. Value may depend on chipset type + used. + + + The chipset type to get the value for. + + + + The USB controller type to get the value for. + + + + The maximum number of instances for the given USB controller type. + + + + + Returns CPU profiles matching the given criteria. + + + The architecture to get profiles for. Required. + + + Name pattern. Simple wildcard matching using asterisk (*) and + question mark (?). + + + The matching CPU profiles. + + + + + + + + + + + + Guest OS family identifier string. + + + + Human readable description of the guest OS family. + + + + Guest OS identifier string. + + + + Human readable description of the guest OS. + + + + Returns @c true if the given OS is 64-bit + + + + Returns @c true if I/O-APIC recommended for this OS type. + + + + Returns @c true if VT-x or AMD-V recommended for this OS type. + + + + Recommended RAM size in Megabytes. + + + + Recommended graphics controller type. + + + + Recommended video RAM size in Megabytes. + + + + Returns @c true if 2D video acceleration is recommended for this OS type. + + + + Returns @c true if 3D acceleration is recommended for this OS type. + + + + Recommended hard disk size in bytes. + + + + Returns recommended network adapter for this OS type. + + + + Returns @c true if using PAE is recommended for this OS type. + + + + Recommended storage controller type for DVD/CD drives. + + + + Recommended storage bus type for DVD/CD drives. + + + + Recommended storage controller type for HD drives. + + + + Recommended storage bus type for HD drives. + + + + Recommended firmware type. + + + + Returns @c true if using USB Human Interface Devices, such as keyboard and mouse recommended. + + + + Returns @c true if using HPET is recommended for this OS type. + + + + Returns @c true if using a USB Tablet is recommended. + + + + Returns @c true if the RTC of this VM should be set to UTC + + + + Recommended chipset type. + + + + Recommended IOMMU type. + + + + Recommended audio controller type. + + + + Recommended audio codec type. + + + + Returns @c true a floppy drive is recommended for this OS type. + + + + Returns @c true a USB controller is recommended for this OS type. + + + + Returns @c true an xHCI (USB 3) controller is recommended for this OS type. + + + + Returns @c true if using VCPU reset on triple fault is recommended for this OS type. + + + + Returns @c true if X2APIC is recommended for this OS type. + + + + Number of vCPUs recommended for this OS type. + + + + Returns the recommended trusted platform module type for this OS type. + + + + Returns @c true if EFI secure boot is recommended for this OS type. + + + + Returns @c true if this OS usually has a WDDM graphics driver + from guest additions. + + + + + + + Guest Additions facility IDs. + + + + No/invalid facility. + + + VirtualBox base driver (VBoxGuest). + + + Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox). + + + VirtualBox system service (VBoxService). + + + VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows). + + + Seamless guest desktop integration. + + + Guest graphics mode. If not enabled, seamless rendering will not work, resize hints + are not immediately acted on and guest display resizes are probably not initiated by + the Guest Additions. + + + + Guest supports monitor hotplug. + + + + All facilities selected. + + + + + + Guest Additions facility classes. + + + + No/invalid class. + + + Driver. + + + System service. + + + Program. + + + Feature. + + + Third party. + + + All facility classes selected. + + + + + + Guest Additions facility states. + + + + Facility is not active. + + + Facility has been paused. + + + Facility is preparing to initialize. + + + Facility is initializing. + + + Facility is up and running. + + + Facility is shutting down. + + + Facility successfully shut down. + + + Facility failed to start. + + + Facility status is unknown. + + + + + + Structure representing a Guest Additions facility. + + + + The class this facility is part of. + + + + + Timestamp of the last status update, + in milliseconds since 1970-01-01 UTC. + + + + + The facility's friendly name. + + + + The current status. + + + + The facility's type ID. + + + + + + Guest Additions run level type. + + + + Guest Additions are not loaded. + + + Guest drivers are loaded. + + + Common components (such as application services) are loaded. + + + Per-user desktop components are loaded. + + + + + + Guest Additions update flags. + + + + No flag set. + + + Starts the regular updating process and waits until the + actual Guest Additions update inside the guest was started. + This can be necessary due to needed interaction with the guest + OS during the installation phase. + + + + + + Guest shutdown flags. + + + + No flag set. + + + Performs a reboot after shutdown. + + + Performs a reboot after shutdown. + + + Force the system to shutdown/reboot regardless of objecting + application or other stuff. This flag might not be realized on + all systems. + + + + + + Guest session status. This enumeration represents possible values of + the attribute. + + + Guest session is in an undefined state. + + + Guest session is being started. + + + Guest session has been started. + + + Guest session is being terminated. + + + Guest session terminated normally. + + + Guest session timed out and was killed. + + + Guest session timed out and was not killed successfully. + + + Service/OS is stopping, guest session was killed. + + + Something went wrong. + + + + + + Guest session waiting flags. + + + + No waiting flags specified. Do not use this. + + + Wait for the guest session being started. + + + Wait for the guest session being terminated. + + + Wait for the next guest session status change. + + + + + + Guest session waiting results. Depending on the session waiting flags (for + more information see ) the waiting result + can vary based on the session's current status. + + To wait for a guest session to terminate after it has been + created by one would specify + GuestSessionWaitResult_Terminate. + + + + No result was returned. Not being used. + + + The guest session has been started. + + + The guest session has been terminated. + + + + The guest session has changed its status. The status then can + be retrieved via . + + + + Error while executing the process. + + + + The waiting operation timed out. This also will happen + when no event has been occurred matching the + current waiting flags in a call. + + + + + A waiting flag specified in the call + is not supported by the guest. + + + + + + + State a guest user has been changed to. + + + + Unknown state. Not being used. + + + A guest user has been successfully logged into + the guest OS. + This property is not implemented yet! + + + + A guest user has been successfully logged out + of the guest OS. + This property is not implemented yet! + + + + A guest user has locked its account. This might + include running a password-protected screensaver + in the guest. + This property is not implemented yet! + + + + A guest user has unlocked its account. + This property is not implemented yet! + + + + A guest user has been disabled by the guest OS. + This property is not implemented yet! + + + + + A guest user currently is not using the guest OS. + Currently only available for Windows guests since + Windows 2000 SP2. + On Windows guests this function currently only supports + reporting contiguous idle times up to 49.7 days per user. + The event will be triggered if a guest user is not active for + at least 5 seconds. This threshold can be adjusted by either altering + VBoxService's command line in the guest to + 
--vminfo-user-idle-threshold <ms>
+ , or by setting the per-VM guest property + 
/VirtualBox/GuestAdd/VBoxService/--vminfo-user-idle-threshold <ms>
+ with the RDONLYGUEST flag on the host. In both cases VBoxService needs + to be restarted in order to get the changes applied. + + + + A guest user continued using the guest OS after + being idle. + + + A guest user has been successfully created. + This property is not implemented yet! + + + + A guest user has been successfully deleted. + This property is not implemented yet! + + + + To guest OS has changed the session of a user. + This property is not implemented yet! + + + + To guest OS has changed the authentication + credentials of a user. This might include changed passwords + and authentication types. + This property is not implemented yet! + + + + To guest OS has changed the role of a user permanently, + e.g. granting / denying administrative rights. + This property is not implemented yet! + + + + To guest OS has added a user to a specific + user group. + This property is not implemented yet! + + + + To guest OS has removed a user from a specific + user group. + This property is not implemented yet! + + + + To guest OS temporarily has elevated a user + to perform a certain task. + This property is not implemented yet! + + + + + + + What a file seek () is relative to. + + + + Seek from the beginning of the file. + + + Seek from the current file position. + + + Seek relative to the end of the file. To seek to the position two + bytes from the end of the file, specify -2 as the seek offset. + + + + + + Guest process input flags. + + + No flag set. + + + End of file (input) reached. + + + + + + Guest process output flags for specifying which + type of output to retrieve. + + + No flags set. Get output from stdout. + + + Get output from stderr. + + + + + + Process waiting flags. + + + + No waiting flags specified. Do not use this. + + + Wait for the process being started. + + + Wait for the process being terminated. + + + Wait for stdin becoming available. + + + Wait for data becoming available on stdout. + + + Wait for data becoming available on stderr. + + + + + + Process waiting results. Depending on the process waiting flags (for + more information see ) the waiting result + can vary based on the processes' current status. + + To wait for a guest process to terminate after it has been + created by or + one would specify ProcessWaitFor_Terminate. + + If a guest process has been started with ProcessCreateFlag_WaitForStdOut + a client can wait with ProcessWaitResult_StdOut for new data to arrive on + stdout; same applies for ProcessCreateFlag_WaitForStdErr and + ProcessWaitResult_StdErr. + + + + No result was returned. Not being used. + + + The process has been started. + + + The process has been terminated. + + + + The process has changed its status. The status then can + be retrieved via . + + + + Error while executing the process. + + + + The waiting operation timed out. Also use if the guest process has + timed out in the guest side (kill attempted). + + + + The process signalled that stdin became available for writing. + + + Data on stdout became available for reading. + + + Data on stderr became available for reading. + + + + A waiting flag specified in the call + is not supported by the guest. + + + + + + + File copying flags. + + + No flag set. + + + + + Do not replace the destination file if it exists. + + + + + Follow symbolic links. + + + + + Only copy when the source file is newer than the destination file + or when the destination file is missing. + + + + + + + File moving flags. + + + No flag set. + + + + Replace the destination file, symlink, etc if it exists, however this + does not allow replacing any directories. + + + + + Follow symbolic links in the final components or not (only applied to + the given source and target paths, not to anything else). + + + + + Allow moving directories accross file system boundraries. Because it + is could be a big undertaking, we require extra assurance that we + should do it when requested. + + + + + + + Directory creation flags. + + + No flag set. + + + No error if existing, make parent directories as needed. + + + + + + Directory copying flags. + + + No flag set. + + + Allow copying into an existing destination directory. + + + Copy directories recursively. + + + Follow symbolic links. + + + + + + + Directory recursive removement flags. + + + + No flag set. + + + Delete the content of the directory and the directory itself. + + + Only delete the content of the directory, omit the directory it self. + + + + + + Flags for use when renaming file system objects (files, directories, + symlink, etc), see . + + + + Do not replace any destination object. + + + This will attempt to replace any destination object other except + directories. (The default is to fail if the destination exists.) + + + + + + Guest process execution flags. + The values are passed to the Guest Additions, so its not possible + to change (move) or reuse values.here. See GUEST_PROC_CREATE_FLAG_XXX + in GuestControlSvc.h. + + + + No flag set. + + + Only use the specified timeout value to wait for starting the guest process - the guest + process itself then uses an infinite timeout. + + + Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down. + + + Do not show the started process according to the guest OS guidelines. + + + Utilize the user's profile data when exeuting a process. Only available for Windows guests at the moment. + + + The guest process waits until all data from stdout is read out. + + + The guest process waits until all data from stderr is read out. + + + Expands environment variables in process arguments. + + This is not yet implemented and is currently silently ignored. + We will document the protocolVersion number for this feature once it + appears, so don't use it till then. + + + + + Work around for Windows and OS/2 applications not following normal + argument quoting and escaping rules. The arguments are passed to the + application without any extra quoting, just a single space between each. + Present since VirtualBox 4.3.28 and 5.0 beta 3. + + + + + + + Process priorities. + + + + Invalid priority, do not use. + + + Default process priority determined by the OS. + + + + + + Symbolic link types. This is significant when creating links on the + Windows platform, ignored elsewhere. + + + + It is not known what is being targeted. + + + The link targets a directory. + + + The link targets a file (or whatever else except directories). + + + + + + Symbolic link reading flags. + + + + No flags set. + + + Don't allow symbolic links as part of the path. + + + + + + Process execution statuses. + + + + Process is in an undefined state. + + + Process is being started. + + + Process has been started. + + + Process has been paused. + + + Process is being terminated. + + + Process terminated normally. + + + Process terminated via signal. + + + Process terminated abnormally. + + + Process timed out and was killed. + + + Process timed out and was not killed successfully. + + + Service/OS is stopping, process was killed. + + + Something went wrong. + + + + + + Process input statuses. + + + + Undefined state. + + + Input pipe is broken. + + + Input pipe became available for writing. + + + Data has been successfully written. + + + Too much input data supplied, data overflow. + + + + + + The path style of a system. + (Values matches the RTPATH_STR_F_STYLE_XXX defines in iprt/path.h!) + + + DOS-style paths with forward and backward slashes, drive + letters and UNC. Known from DOS, OS/2 and Windows. + + + UNIX-style paths with forward slashes only. + + + + The path style is not known, most likely because the Guest Additions + aren't active yet. + + + + + + + File open access mode for use with + and . + + + Open the file only with read access. + + + Open the file only with write access. + + + Open the file with both read and write access. + + + Open the file for appending only, no read or seek access. + Not yet implemented. + + + + Open the file for appending and read. Writes always goes to the + end of the file while reads are done at the current or specified file + position. + Not yet implemented. + + + + + + + What action and + should take whether the file being opened exists or not. + + + Opens an existing file, fails if no file exists. (Was "oe".) + + + Opens an existing file, creates a new one if no file exists. (Was "oc".) + + + Creates a new file is no file exists, fails if there is a file there already. (Was "ce".) + + + + Creates a new file, replace any existing file. (Was "ca".) + + Currently undefined whether we will inherit mode and ACLs from the + existing file or replace them. + + + + + Opens and truncate an existing file, fails if no file exists. (Was "ot".) + + + Opens an existing file and places the file pointer at the end of + the file, creates the file if it does not exist. This action implies + write access. (Was "oa".) + + + Deprecated. Only here for historical reasons. Do not use! + + + + + + + + File sharing mode for . + + + Only share read access to the file. + + + Only share write access to the file. + + + Share both read and write access to the file, but deny deletion. + + + Only share delete access, denying read and write. + + + Share read and delete access to the file, denying writing. + + + Share write and delete access to the file, denying reading. + + + Share all access, i.e. read, write and delete, to the file. + + + + + + Open flags for . + + + No flag set. + + + + + + File statuses. + + + + File is in an undefined state. + + + Guest file is opening. + + + Guest file has been successfully opened. + + + Guest file closing. + + + Guest file has been closed. + + + Service/OS is stopping, guest file was closed. + + + Something went wrong. + + + + + + File system object (file) types. + + + Used either if the object has type that is not in this enum, or + if the type has not yet been determined or set. + + + FIFO or named pipe, depending on the platform/terminology. + + + Character device. + + + Directory. + + + Block device. + + + Regular file. + + + Symbolic link. + + + Socket. + + + A white-out file. Found in union mounts where it is used for + hiding files after deletion, I think. + + + + + + Possible actions of a drag'n drop operation. + + + + Do nothing. + + + + Copy the item to the target. + + + + Move the item to the target. + + + + Link the item from within the target. + + + + + + Directory open flags. + + + No flag set. + + + Don't allow symbolic links as part of the path. + + + + + + Base abstract interface for drag'n drop. + + + Returns all supported drag'n drop formats. + + + + + Checks if a specific drag'n drop MIME / Content-type format is supported. + + + Format to check for. + + + Returns @c true if the specified format is supported, @c false if not. + + + + + + Adds MIME / Content-type formats to the supported formats. + + + Collection of formats to add. + + + + + + Removes MIME / Content-type formats from the supported formats. + + + Collection of formats to remove. + + + + + + + Abstract interface for handling drag'n drop sources. + + + + Ask the source if there is any drag and drop operation pending. + If no drag and drop operation is pending currently, DnDAction_Ignore is returned. + + + VMM device is not available. + + + + The screen ID where the drag and drop event occurred. + + + On return the supported mime types. + + + On return the actions which are allowed. + + + On return the default action to use. + + + + + + Informs the source that a drop event occurred for a pending + drag and drop operation. + + + VMM device is not available. + + + + + The mime type the data must be in. + + + The action to use. + + + Progress object to track the operation completion. + + + + + + Receive the data of a previously drag and drop event from the source. + + + VMM device is not available. + + + + + + The actual data. + + + + + + + + Implementation of the object + for source drag'n drop operations on the guest. + + + + + + Abstract interface for handling drag'n drop targets. + + + + Informs the target about a drag and drop enter event. + + + VMM device is not available. + + + + The screen ID where the drag and drop event occurred. + + + Y-position of the event. + + + X-position of the event. + + + The default action to use. + + + The actions which are allowed. + + + The supported MIME types. + + + The resulting action of this event. + + + + + + Informs the target about a drag and drop move event. + + + VMM device is not available. + + + + The screen ID where the drag and drop event occurred. + + + X-position of the event. + + + Y-position of the event. + + + The default action to use. + + + The actions which are allowed. + + + The supported MIME types. + + + The resulting action of this event. + + + + + + Informs the target about a drag and drop leave event. + + + VMM device is not available. + + + + The screen ID where the drag and drop event occurred. + + + + + + Informs the target about a drop event. + + + VMM device is not available. + + + + + The screen ID where the Drag and Drop event occurred. + + + X-position of the event. + + + Y-position of the event. + + + The default action to use. + + + The actions which are allowed. + + + The supported MIME types. + + + The resulting format of this event. + + + The resulting action of this event. + + + + + + Initiates sending data to the target. + + + VMM device is not available. + + + + + The screen ID where the drag and drop event occurred. + + + The MIME type the data is in. + + + The actual data. + + + Progress object to track the operation completion. + + + + + + Requests cancelling the current operation. The target can veto + the request in case the operation is not cancelable at the moment. + + + VMM device is not available. + + + + + + Whether the target has vetoed cancelling the operation. + + + + + + + + Implementation of the object + for target drag'n drop operations on the guest. + + + + + + + A guest session represents one impersonated user account in the guest, so + every operation will use the same credentials specified when creating + the session object via . + + There can be a maximum of 32 sessions at once per VM, whereas session 0 + always is reserved for the root session (the root session is part of that + limit). + + This root session is controlling all other guest sessions and also is + responsible for actions which require system level privileges. + + Each guest session keeps track of the guest directories and files that + it opened as well as guest processes it has created. To work on guest + files or directories a guest session offers methods to open or create + such objects (see or + for instance). Similarly, + there a methods for creating guest processes. + + There can be up to 2048 objects (guest processes, files and directories) + a time per guest session. Exceeding the limit will result in an error (see + the corresponding functions for more). + + When done with either of these objects, including the guest session itself, + use the appropriate close() method to let the object do its cleanup work. + + Closing a session via will try to close + all the mentioned objects above unless these objects are still used by + a client. + + A set of environment variables changes is associated with each session + (). These are applied to + the base environment of the impersonated guest user when creating a new + guest process. For additional flexibility the + and methods allows you to + specify individual environment changes for each process you create. + With newer guest addition versions, the base environment is also made + available via . (One reason + for why we record changes to a base environment instead of working + directly on an environment block is that we need to be compatible + with older Guest Additions. Another reason is that this way it is always + possible to undo all the changes you've scheduled.) + + + + Returns the user name used by this session to impersonate + users in the guest. + + + + Returns the domain name used by this session to impersonate + users in the guest. + + + + Returns the session's friendly name. + + + Returns the internal session ID. + + + + + Returns the session timeout (in ms). + + This attribute is not implemented yet. + + + + + Returns the protocol version which is used by this session to + communicate with the guest. + + + Returns the current session status. + + + + The set of scheduled environment changes to the base environment of the + session. They are in putenv format, i.e. "VAR=VALUE" for setting and + "VAR" for unsetting. One entry per variable (change). The changes are + applied when creating new guest processes. + + This is writable, so to undo all the scheduled changes, assign it an + empty array. + + + + + The base environment of the session. They are on the "VAR=VALUE" form, + one array entry per variable. + + + Access fails with VBOX_E_NOT_SUPPORTED if the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX. + + Access fails with VBOX_E_INVALID_OBJECT_STATE if the Guest Additions + has yet to report the session base environment. + + + + + Returns all current guest processes. + + + + + The style of paths used by the guest. Handy for giving the right kind + of path specifications to and similar methods. + + + + + Gets or sets the current directory of the session. Guest path style. + + This attribute is not implemented yet. + + + + + + Returns the user's home / profile directory. Guest path style. + + + + + Returns the user's documents directory. Guest path style. + + + + + Returns all currently opened guest directories. + + + + + Returns all currently opened guest files. + + + + + Event source for guest session events. + + + + + + Closes this session. All opened guest directories, files and + processes which are not referenced by clients anymore will be + closed. Guest processes which fall into this category and still + are running in the guest will be terminated automatically. + + + + + + Copies directories and/or files from guest to the host. + + This function requires several parallel arrays to be supplied, one + set for each source. + + + Paths to directories and/or files on the guest side that should be + copied to the host. If the path ends with a path delimiter, only + the directory's content is being copied. Guest path style. + + + Array of source filters. This uses the + DOS/NT style wildcard characters '?' and '*'. + + + Array of comma-separated list of source flags. + + The following flags are available: + +
+
CopyIntoExisting
+
Allow copying into an existing destination directory.
+
NoReplace
+
Do not replace any existing destination files on + the destination.
+
FollowLinks
+
Follows (and handles) (symbolic) links.
+
Update
+
Only copy when the source file is newer than the destination + file or when the destination file is missing.
+
+ + + + Where to put the sources on the host. Host path style. + + + Progress object to track the operation to completion. + + + + + + Copies directories and/or files from host to the guest. + + This function requires several parallel arrays to be supplied, one + set for each source. + + + Paths to directories and/or files on the host side that should be + copied to the guest. If the path ends with a path delimiter, only + the directory's content is being copied. Host path style. + + + Array of source filters. This uses the + DOS/NT style wildcard characters '?' and '*'. + + + Array of comma-separated list of source flags. + + The following flags are available: + +
+
CopyIntoExisting
+
Allow copying into an existing destination directory.
+
NoReplace
+
Do not replace any existing destination files on + the destination.
+
FollowLinks
+
Follows (and handles) (symbolic) links.
+
Update
+
Only copy when the source file is newer than the destination + file or when the destination file is missing.
+
+ + + + + Where to put the sources on the guest. Guest path style. + + + Progress object to track the operation to completion. + + + + + + + + Recursively copies a directory from one guest location to another. + + + Not yet implemented. + + + + The path to the directory to copy (in the guest). Guest path style. + + + The path to the target directory (in the guest). Unless the + flag is given, the + directory shall not already exist. Guest path style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Recursively copies a directory from the guest to the host. + + + Path to the directory on the guest side that should be copied to + the host. Guest path style. + + + Where to put the directory on the host. Unless the + flag is given, the + directory shall not already exist. Host path style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Recursively copies a directory from the host to the guest. + + + Path to the directory on the host side that should be copied to + the guest. Host path style. + + + Where to put the file in the guest. Unless the + flag is given, the + directory shall not already exist. Guest style path. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Creates a directory in the guest. + + + Error while creating the directory. + + + + Path to the directory directory to be created. Guest path style. + + + + The UNIX-style access mode mask to create the directory with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + + + + Zero or more flags. + + + + + + Creates a temporary directory in the guest. + + + The operation is not possible as requested on this particular + guest type. + + + Invalid argument. This includes an incorrectly formatted template, + or a non-absolute path. + + + The temporary directory could not be created. Possible reasons + include a non-existing path or an insecure path when the secure + option was requested. + + + + Template for the name of the directory to create. This must + contain at least one 'X' character. The first group of consecutive + 'X' characters in the template will be replaced by a random + alphanumeric string to produce a unique name. + + + + The UNIX-style access mode mask to create the directory with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + + This parameter is ignored if the @a secure parameter is set to @c true. + It is strongly recommended to use 0700. + + + + The path to the directory in which the temporary directory should + be created. Guest path style. + + + + Whether to fail if the directory can not be securely created. + Currently this means that another unprivileged user cannot + manipulate the path specified or remove the temporary directory + after it has been created. Also causes the mode specified to be + ignored. May not be supported on all guest types. + + + + On success this will contain the full path to the created + directory. Guest path style. + + + + + + Checks whether a directory exists in the guest or not. + + + Error while checking existence of the directory specified. + + + + Path to the directory to check if exists. Guest path style. + + + + If @c true, symbolic links in the final component will be followed + and the existance of the symlink target made the question for this method. + If @c false, a symbolic link in the final component will make the + method return @c false (because a symlink isn't a directory). + + + + Returns @c true if the directory exists, @c false if not, or is not a directory. + + + + + + Opens a directory in the guest and creates a + object that can be used for further operations. + + This method follows symbolic links by default at the moment, this + may change in the future. + + One idiosyncrasy of the current implementation is that you will NOT + get VBOX_E_OBJECT_NOT_FOUND returned here if the directory doesn't exist. + Instead the read function will fail with VBOX_E_IPRT_ERROR. This will + be fixed soon. + + + Directory to open was not found. + + + Error while opening the directory. + + + The maximum of concurrent guest directories has been reached. + + + + Path to the directory to open. Guest path style. + + + Optional directory listing filter to apply. This uses the DOS/NT + style wildcard characters '?' and '*'. + + + Zero or more flags. + + + object containing the opened directory. + + + + + + Removes a guest directory if empty. + + Symbolic links in the final component will not be followed, + instead an not-a-directory error is reported. + + + Path to the directory that should be removed. Guest path style. + + + + + + Removes a guest directory recursively. + + + + WARNING!! THE FLAGS ARE NOT CURRENTLY IMPLEMENTED. THE IMPLEMENTATION + WORKS AS IF FLAGS WAS SET TO . + + + If the final path component is a symbolic link, this method will + fail as it can only be applied to directories. + + + Path of the directory that is to be removed recursively. Guest + path style. + + + Zero or more flags. + WARNING! SPECIFYING IS + MANDATORY AT THE MOMENT!! + + + + Progress object to track the operation completion. This is not implemented + yet and therefore this method call will block until deletion is completed. + + + + + + + + Schedules setting an environment variable when creating the next guest + process. This affects the + attribute. + + + Name of the environment variable to set. This cannot be empty + nor can it contain any equal signs. + + + Value to set the session environment variable to. + + + + + + Schedules unsetting (removing) an environment variable when creating + the next guest process. This affects the + attribute. + + + Name of the environment variable to unset. This cannot be empty + nor can it contain any equal signs. + + + + + + Gets an environment variable from the session's base environment + (). + + If the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX. + If the Guest Additions has + yet to report the session base environment. + + + Name of the environment variable to get.This cannot be empty + nor can it contain any equal signs. + + + + The value of the variable. Empty if not found. To deal with + variables that may have empty values, use + . + + + + + + + Checks if the given environment variable exists in the session's base + environment (). + + If the Guest Additions does not + support the session base environment feature. Support for this was + introduced with protocol version XXXX. + If the Guest Additions has + yet to report the session base environment. + + + Name of the environment variable to look for. This cannot be + empty nor can it contain any equal signs. + + + TRUE if the variable exists, FALSE if not. + + + + + + + + Copies a file from one guest location to another. + + Will overwrite the destination file unless + is specified. + + + Not yet implemented. + + + + The path to the file to copy (in the guest). Guest path style. + + + The path to the target file (in the guest). This cannot be a + directory. Guest path style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Copies a file from the guest to the host. + + Will overwrite the destination file unless + is specified. + + + Error starting the copy operation. + + + + Path to the file on the guest side that should be copied to the + host. Guest path style. + + + Where to put the file on the host (file, not directory). Host + path style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Copies a file from the host to the guest. + + Will overwrite the destination file unless + is specified. + + + Error starting the copy operation. + + + + Path to the file on the host side that should be copied to the + guest. Host path style. + + + Where to put the file in the guest (file, not directory). Guest + style path. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Creates a temporary file in the guest. + + + The operation is not possible as requested on this particular + guest OS. + + + Invalid argument. This includes an incorrectly formatted template, + or a non-absolute path. + + + The temporary file could not be created. Possible reasons include + a non-existing path or an insecure path when the secure + option was requested. + + + + Template for the name of the file to create. This must contain + at least one 'X' character. The first group of consecutive 'X' + characters in the template will be replaced by a random + alphanumeric string to produce a unique name. + + + + + The UNIX-style access mode mask to create the file with. + Whether/how all three access groups and associated access rights are + realized is guest OS dependent. The API does the best it can on each + OS. + + This parameter is ignore if the @a secure parameter is set to @c true. + It is strongly recommended to use 0600. + + + + The path to the directory in which the temporary file should be + created. + + + Whether to fail if the file can not be securely created. + Currently this means that another unprivileged user cannot + manipulate the path specified or remove the temporary file after + it has been created. Also causes the mode specified to be ignored. + May not be supported on all guest types. + + + On success this will contain an open file object for the new + temporary file. + + + + + + + Checks whether a regular file exists in the guest or not. + + + Error while checking existence of the file specified. + + + + Path to the alleged regular file. Guest path style. + + + + If @c true, symbolic links in the final component will be followed + and the existance of the symlink target made the question for this method. + If @c false, a symbolic link in the final component will make the + method return @c false (because a symlink isn't a regular file). + + + + Returns @c true if the file exists, @c false if not. @c false is + also return if this @a path does not point to a file object. + + + + + + Opens a file and creates a object that + can be used for further operations. + + + File to open was not found. + + + Error while opening the file. + + + The maximum of concurrent guest files has been reached. + + + + Path to file to open. Guest path style. + + + The file access mode (read, write and/or append). + See for details. + + + What action to take depending on whether the file exists or not. + See for details. + + + + The UNIX-style access mode mask to create the file with if @a openAction + requested the file to be created (otherwise ignored). Whether/how all + three access groups and associated access rights are realized is guest + OS dependent. The API does the best it can on each OS. + + + + object representing the opened file. + + + + + + Opens a file and creates a object that + can be used for further operations, extended version. + + + File to open was not found. + + + Error while opening the file. + + + + Path to file to open. Guest path style. + + + The file access mode (read, write and/or append). + See for details. + + + What action to take depending on whether the file exists or not. + See for details. + + + The file sharing mode in the guest. This parameter is currently + ignore for all guest OSes. It will in the future be implemented for + Windows, OS/2 and maybe Solaris guests only, the others will ignore it. + Use . + + + + + The UNIX-style access mode mask to create the file with if @a openAction + requested the file to be created (otherwise ignored). Whether/how all + three access groups and associated access rights are realized is guest + OS dependent. The API does the best it can on each OS. + + + + Zero or more values. + + + object representing the opened file. + + + + + + Queries the size of a regular file in the guest. + + + File to was not found. + + + Error querying file size. + + + + Path to the file which size is requested. Guest path style. + + + + It @c true, symbolic links in the final path component will be + followed to their target, and the size of the target is returned. + If @c false, symbolic links in the final path component will make + the method call fail (symblink is not a regular file). + + + + Queried file size. + + + + + + + + Checks whether a file system object (file, directory, etc) exists in + the guest or not. + + + Error while checking existence of the file specified. + + + + Path to the file system object to check the existance of. Guest + path style. + + + + If @c true, symbolic links in the final component will be followed + and the method will instead check if the target exists. + If @c false, symbolic links in the final component will satisfy the + method and it will return @c true in @a exists. + + + + Returns @c true if the file exists, @c false if not. + + + + + + Queries information about a file system object (file, directory, etc) + in the guest. + + + The file system object was not found. + + + Error while querying information. + + + + Path to the file system object to gather information about. + Guest path style. + + + + Information about symbolic links is returned if @c false. Otherwise, + symbolic links are followed and the returned information concerns + itself with the symlink target if @c true. + + + + object containing the information. + + + + + + Removes a file system object (file, symlink, etc) in the guest. Will + not work on directories, use + to remove directories. + + This method will remove symbolic links in the final path + component, not follow them. + + + The method has not been implemented yet. + + + The file system object was not found. + + + For most other errors. We know this is unhelpful, will fix shortly... + + + + Path to the file system object to remove. Guest style path. + + + + + + Removes multiple file system objects (files, directories, symlinks, etc) + in the guest. Use with caution. + + This method is not implemented yet and will return E_NOTIMPL. + + This method will remove symbolic links in the final path + component, not follow them. + + + The method has not been implemented yet. + + + + Array of paths to the file system objects to remove. Guest style path. + + + Progress object to track the operation to completion. + + + + + + Renames a file system object (file, directory, symlink, etc) in the + guest. + + + The file system object was not found. + + + For most other errors. We know this is unhelpful, will fix shortly... + + + + The current path to the object. Guest path style. + + + The new path to the object. Guest path style. + + + Zero or more values. + + + + + + Moves a file system object (file, directory, symlink, etc) from one + guest location to another. + + This differs from in that it + can move accross file system boundraries. In that case it will + perform a copy and then delete the original. For directories, this + can take a while and is subject to races. + + + Not yet implemented. + + + + Path to the file to move. Guest path style. + + + Where to move the file to (file, not directory). Guest path + style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Moves file system objects (files, directories, symlinks, etc) from one + guest location to another. + + + Not yet implemented. + + + + Array of paths to the file system objects to move. Guest style path. + + + Where to move the file system objects to (directory). Guest path + style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Copies file system objects (files, directories, symlinks, etc) from one + guest location to another. + + + Not yet implemented. + + + + Array of paths to the file system objects to copy. Guest style path. + + + Where to copy the file system objects to (directory). Guest path + style. + + + Zero or more values. + + + Progress object to track the operation to completion. + + + + + + Sets the access control list (ACL) of a file system object (file, + directory, etc) in the guest. + + + The method is not implemented yet. + + + + Full path of the file system object which ACL to set. + + + + If @c true symbolic links in the final component will be followed, + otherwise, if @c false, the method will work directly on a symbolic + link in the final component. + + + + The ACL specification string. To-be-defined. + + + UNIX-style mode mask to use if @a acl is empty. As mention in + this is realized on + a best effort basis and the exact behavior depends on the Guest OS. + + + + + + + Returns the free space (in bytes) of a given path. + + + The method is not implemented yet. + + + + Full path to return the free space for. + + + Free space (in bytes). + + + + + + Returns file system information for a given path. + + + The method is not implemented yet. + + + + + Full path to return file system information for. + + + IGuestFsInfo object containing the information. + + + + + + + + + Creates a new process running in the guest. The new process will be + started asynchronously, meaning on return of this function it is not + be guaranteed that the guest process is in a started state. To wait for + successful startup, use the call. + + + Starting at VirtualBox 4.2 guest process execution by is default limited + to serve up to 255 guest processes at a time. If all 255 guest processes + are active and running, creating a new guest process will result in an + error. + + If ProcessCreateFlag_WaitForStdOut and/or ProcessCreateFlag_WaitForStdErr + are set, the guest process will not enter the terminated state until + all data from the specified streams have been read read. + + + + Error creating guest process. + + + + The maximum of concurrent guest processes has been reached. + + + + + Full path to the file to execute in the guest. The file has to + exists in the guest VM with executable right to the session user in + order to succeed. If empty/null, the first entry in the + @a arguments array will be used instead (i.e. argv[0]). + + + + Array of arguments passed to the new process. + + Starting with VirtualBox 5.0 this array starts with argument 0 + instead of argument 1 as in previous versions. Whether the zeroth + argument can be passed to the guest depends on the VBoxService + version running there. If you depend on this, check that the + is 3 or higher. + + + + + + Set of environment changes to complement + . Takes precedence + over the session ones. The changes are in putenv format, i.e. + "VAR=VALUE" for setting and "VAR" for unsetting. + + The changes are applied to the base environment of the impersonated + guest user () when + creating the process. (This is done on the guest side of things in + order to be compatible with older Guest Additions. That is one of + the motivations for not passing in the whole environment here.) + + + + + Process creation flags; + see for more information. + + + + + Timeout (in ms) for limiting the guest process' running time. + Pass 0 for an infinite timeout. On timeout the guest process will be + killed and its status will be put to an appropriate value. See + for more information. + + + + Guest process object of the newly created process. + + + + + + Creates a new process running in the guest with the extended options + for setting the process priority and affinity. + + See for more information. + + + + Full path to the file to execute in the guest. The file has to + exists in the guest VM with executable right to the session user in + order to succeed. If empty/null, the first entry in the + @a arguments array will be used instead (i.e. argv[0]). + + + + Array of arguments passed to the new process. + + Starting with VirtualBox 5.0 this array starts with argument 0 + instead of argument 1 as in previous versions. Whether the zeroth + argument can be passed to the guest depends on the VBoxService + version running there. If you depend on this, check that the + is 3 or higher. + + + + + + Set of environment changes to complement + . Takes precedence + over the session ones. The changes are in putenv format, i.e. + "VAR=VALUE" for setting and "VAR" for unsetting. + + The changes are applied to the base environment of the impersonated + guest user () when + creating the process. (This is done on the guest side of things in + order to be compatible with older Guest Additions. That is one of + the motivations for not passing in the whole environment here.) + + + + + Process creation flags, see for + detailed description of available flags. + + + + + Timeout (in ms) for limiting the guest process' running time. + Pass 0 for an infinite timeout. On timeout the guest process will be + killed and its status will be put to an appropriate value. See + for more information. + + + + + Process priority to use for execution, see + for available priority levels. + This is silently ignored if not supported by Guest Additions. + + + + + Processor affinity to set for the new process. This is a list of + guest CPU numbers the process is allowed to run on. + + This is silently ignored if the guest does not support setting the + affinity of processes, or if the Guest Additions does not implemet + this feature. + + + + + Guest process object of the newly created process. + + + + + + Gets a certain guest process by its process ID (PID). + + + Process ID (PID) to get guest process for. + + + Guest process of specified process ID (PID). + + + + + + + + Creates a symbolic link in the guest. + + + The method is not implemented yet. + + + + Path to the symbolic link that should be created. Guest path + style. + + + + The path to the symbolic link target. If not an absolute, this will + be relative to the @a symlink location at access time. Guest path + style. + + + + + The symbolic link type (mainly for Windows). See + for more information. + + + + + + + Checks whether a symbolic link exists in the guest. + + + The method is not implemented yet. + + + + Path to the alleged symbolic link. Guest path style. + + + + Returns @c true if the symbolic link exists. Returns @c false if it + does not exist, if the file system object identified by the path is + not a symbolic link, or if the object type is inaccessible to the + user, or if the @a symlink argument is empty. + + + + + + + Reads the target value of a symbolic link in the guest. + + + The method is not implemented yet. + + + + Path to the symbolic link to read. + + + Zero or more values. + + + Target value of the symbolic link. Guest path style. + + + + + + + + Waits for one or more events to happen. + + + + Specifies what to wait for; + see for more information. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + + The overall wait result; + see for more information. + + + + + + + Waits for one or more events to happen. + Scriptable version of . + + + + Specifies what to wait for; + see for more information. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + + The overall wait result; + see for more information. + + + + + + + + + Abstract parent interface for processes handled by VirtualBox. + + + + + The arguments this process is using for execution. + + + + + The initial process environment. Not yet implemented. + + + + + Event source for process events. + + + + Full path of the actual executable image. + + + + The exit code. Only available when the process has been + terminated normally. + + + + + The friendly name of this process. + + + + + The process ID (PID). + + + + + The current process status; see + for more information. + + + + + + Waits for one or more events to happen. + + + + Specifies what to wait for; + see for more information. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + + The overall wait result; + see for more information. + + + + + + + Waits for one or more events to happen. + Scriptable version of . + + + + Specifies what to wait for; + see for more information. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + + The overall wait result; + see for more information. + + + + + + + Reads data from a running process. + + + Handle to read from. Usually 0 is stdin. + + + Number of bytes to read. + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + Array of data read. + + + + + + Writes data to a running process. + + + Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr. + + + + A combination of flags. + + + + + Array of bytes to write. The size of the array also specifies + how much to write. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + How many bytes were written. + + + + + + Writes data to a running process. + Scriptable version of . + + + Handle to write to. Usually 0 is stdin, 1 is stdout and 2 is stderr. + + + + A combination of flags. + + + + + Array of bytes to write. The size of the array also specifies + how much to write. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + How may bytes were written. + + + + + + Terminates (kills) a running process. + It can take up to 30 seconds to get a guest process killed. In + case a guest process could not be killed an appropriate error is + returned. + + + + + + + Implementation of the object + for processes the host has started in the guest. + + + + + + + Abstract parent interface for directories handled by VirtualBox. + + + + The path specified when opening the directory. + + + + Directory listing filter to (specified when opening the directory). + + + + + Closes this directory. After closing operations like reading the next + directory entry will not be possible anymore. + + + + + + Reads the next directory entry of this directory. + + No more directory entries to read. + + + + Object information of the current directory entry read. Also see + . + + + + + + + + + + Implementation of the object + for directories in the guest. + + + + + + + Abstract parent interface for files handled by VirtualBox. + + + + + Event source for file events. + + + + + The ID VirtualBox internally assigned to the open file. + + + + + The initial size in bytes when opened. + + + + + The current file position. + + The file current position always applies to the + method, which updates it upon return. Same goes for the + method except when is + or , where it will always write + to the end of the file and will leave this attribute unchanged. + + The is used to change this attribute without + transfering any file data like read and write does. + + This will not always be correct with older Guest Additions + (version 5.2.30 and earlier, as well as versions 6.0.0 thru 6.0.8) + after a calling or , + or after calling on a file in append mode. + The correct file offset can be obtained using . + + + + + + Current file status. + + + + + + Full path of the actual file name of this file. + + + + + The UNIX-style creation mode specified when opening the file. + + + The opening action specified when opening the file. + + + The file access mode. + + + + + Closes this file. After closing operations like reading data, + writing data or querying information will not be possible anymore. + + + + + + Queries information about this file. + + + Object information of this file. Also see + . + + + + + + + Queries the current file size. + + + Queried file size. + + + + + + Reads data from this file. + + The file current position () is updated on success. + + + Number of bytes to read. + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + Array of data read. + + + + + + Reads data from an offset of this file. + + The file current position () is updated on success. + + + Offset in bytes to start reading. + + + Number of bytes to read. + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + Array of data read. + + + + + + Changes the current file position of this file. + + The file current position always applies to the + method. Same for the method it except when + the is + or . + + + Offset to seek relative to the position specified by @a whence. + + + + One of the seek starting points. + + + + The new file offset after the seek operation. + + + + + + Sets the ACL of this file. + + + The method is not implemented yet. + + + + The ACL specification string. To-be-defined. + + + UNIX-style mode mask to use if @a acl is empty. As mention in + this is realized on + a best effort basis and the exact behavior depends on the Guest OS. + + + + + + + Changes the file size. + + + The new file size. + + + + + + Writes bytes to this file. + + The file current position () is updated on success. + + + + Array of bytes to write. The size of the array also specifies + how much to write. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + How many bytes were written. + + + + + + Writes bytes at a certain offset to this file. + + The file current position () is updated on success. + + + Offset in bytes to start writing. If the file was opened with the + set to + or , the offset is ignored and the + write always goes to the end of the file. + + + + Array of bytes to write. The size of the array also specifies + how much to write. + + + + + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + + + + How many bytes were written. + + + + + + + + Implementation of the object + for files in the guest. + + + + + + + Abstract parent interface for VirtualBox file system information. + This can be information about a host or guest file system, for example. + + + + + Remaining free space (in bytes) of the filesystem. + + + + + Total space (in bytes) of the filesystem. + + + + + Block size (in bytes) of the filesystem. + + + + + Sector size (in bytes) of the filesystem. + + + + + Serial number of the filesystem. + + + + + @c TRUE if the filesystem is remote, @c FALSE if the filesystem is local. + + + + + @c TRUE if the filesystem is case sensitive, @c FALSE if the filesystem is case insensitive. + + + + + @c TRUE if the filesystem is mounted read only, @c FALSE if the filesystem is mounted read write. + + + + + @c TRUE if the filesystem is compressed, @c FALSE if it isn't or we don't know. + + + + + @c TRUE if the filesystem compresses of individual files, @c FALSE if it doesn't or we don't know. + + + + + The maximum size of a filesystem object name. + + + + + Name of the filesystem. + + + + + Label of the filesystem. + + + + + Mount point of the filesystem. + + + + + + + Abstract parent interface for VirtualBox file system object information. + This can be information about a file or a directory, for example. + + + + The object's name. + + + + + The object type. See for more. + + + + + File attributes. Not implemented yet. + + + + + The logical size (st_size). For normal files this is the size of the file. + For symbolic links, this is the length of the path name contained in the + symbolic link. For other objects this fields needs to be specified. + + + + + Disk allocation size (st_blocks * DEV_BSIZE). + + + + + + Time of last access (st_atime). + + + + + Time of file birth (st_birthtime). + + + + + Time of last status change (st_ctime). + + + + + Time of last data modification (st_mtime). + + + + + + The user owning the filesystem object (st_uid). This is -1 if not available. + + + + + The user name. + + + + + The group the filesystem object is assigned (st_gid). This is -1 if not available. + + + + + The group name. + + + + + + The unique identifier (within the filesystem) of this filesystem object (st_ino). + This is zero if not availalbe. + + + + + The device number of the device which this filesystem object resides on (st_dev). + + + + + Number of hard links to this filesystem object (st_nlink). + + + + + The device number of a character or block device type object (st_rdev). + + + + + The current generation number (st_gen). + + + + + User flags (st_flags). + + + + + + + Represents the guest implementation of the + object. + + + + + + + Represents the guest implementation of the + object. + + + + + + + The IGuest interface represents information about the operating system + running inside the virtual machine. Used in + . + + IGuest provides information about the guest operating system, whether + Guest Additions are installed and other OS-specific virtual machine + properties. + + + + + Identifier of the Guest OS type as reported by the Guest + Additions. + You may use to obtain + an IGuestOSType object representing details about the given + Guest OS type. + + If Guest Additions are not installed, this value will be + the same as . + + + + + + + Current run level of the installed Guest Additions. + + + + + + Version of the installed Guest Additions in the same format as + . + + + + + + The internal build revision number of the installed Guest Additions. + + See also . + + + + + + Retrieves the drag'n drop source implementation for the guest side, that + is, handling and retrieving drag'n drop data from the guest. + + + + + + Retrieves the drag'n drop source implementation for the host side. This + will allow the host to handle and initiate a drag'n drop operation to copy + data from the host to the guest. + + + + + + Event source for guest events. + + + + + + Returns a collection of current known facilities. Only returns facilities where + a status is known, e.g. facilities with an unknown status will not be returned. + + + + + Returns a collection of all opened guest sessions. + + + + Guest system memory balloon size in megabytes (transient property). + + + + Interval to update guest statistics in seconds. + + + + + Internal method; do not use as it might change at any time. + + + Percentage of processor time spent in user mode as seen by the guest. + + + Percentage of processor time spent in kernel mode as seen by the guest. + + + Percentage of processor time spent idling as seen by the guest. + + + Total amount of physical guest RAM. + + + Free amount of physical guest RAM. + + + Amount of ballooned physical guest RAM. + + + Amount of shared physical guest RAM. + + + Total amount of guest (disk) cache memory. + + + Total amount of space in the page file. + + + Total amount of memory allocated by the hypervisor. + + + Total amount of free memory available in the hypervisor. + + + Total amount of memory ballooned by the hypervisor. + + + Total amount of shared memory in the hypervisor. + + + + + + Get the current status of a Guest Additions facility. + + + Facility to check status for. + + + Timestamp (in ms) of last status update seen by the host. + + + The current (latest) facility status. + + + + + + Retrieve the current status of a certain Guest Additions run level. + + + Wrong status level specified. + + + + + Status level to check + + + Flag whether the status level has been reached or not + + + + + + Store login credentials that can be queried by guest operating + systems with Additions installed. The credentials are transient + to the session and the guest may also choose to erase them. Note + that the caller cannot determine whether the guest operating system + has queried or made use of the credentials. + + + VMM device is not available. + + + + + User name string, can be empty + + + Password string, can be empty + + + Domain name (guest logon scheme specific), can be empty + + + + Flag whether the guest should alternatively allow the user to + interactively specify different credentials. This flag might + not be supported by all versions of the Additions. + + + + + + + Creates a new guest session for controlling the guest. The new session + will be started asynchronously, meaning on return of this function it is + not guaranteed that the guest session is in a started and/or usable state. + To wait for successful startup, use the + call. + + A guest session represents one impersonated user account in the guest, so + every operation will use the same credentials specified when creating + the session object via . Anonymous + sessions, that is, sessions without specifying a valid + user account in the guest are not allowed reasons of security. + + There can be a maximum of 32 sessions at once per VM. An error will + be returned if this has been reached. + + For more information please consult + + + Error creating guest session. + + + + The maximum of concurrent guest sessions has been reached. + + + + + User name this session will be using to control the guest; has to exist + and have the appropriate rights to execute programs in the VM. Must not + be empty. + + + + + Password of the user account to be used. Empty passwords are allowed. + + + + + Domain name of the user account to be used if the guest is part of + a domain. Optional. This feature is not implemented yet. + + + + + The session's friendly name. Optional, can be empty. + + + + + The newly created session object. + + + + + + + Finds guest sessions by their friendly name and returns an interface + array with all found guest sessions. + + + + The session's friendly name to find. Wildcards like ? and * are allowed. + + + + + Array with all guest sessions found matching the name specified. + + + + + + + Shuts down (and optionally halts and/or reboots) the guest. + Needs supported Guest Additions installed. + + + Guest OS is not supported for shutting down, or the + already installed Guest Additions are not supported. + + + + Error while shutting down. + + + + + + flags. + + + + + + + Automatically updates already installed Guest Additions in a VM. + + At the moment only Windows and Linux guests are supported. + + Because the VirtualBox Guest Additions drivers are not WHQL-certified + yet there might be warning dialogs during the actual Guest Additions + update. These need to be confirmed manually in order to continue the + installation process. This applies to Windows 2000 and Windows XP guests + and therefore these guests can't be updated in a fully automated fashion + without user interaction. However, to start a Guest Additions update for + the mentioned Windows versions anyway, the flag + AdditionsUpdateFlag_WaitForUpdateStartOnly can be specified. See + for more information. + + The guest needs to be restarted in order to make use of the updated + Guest Additions. + + + Guest OS is not supported for automated Guest Additions updates or the + already installed Guest Additions are not ready yet. + + + + Error while updating. + + + + + + Path to the Guest Additions .ISO file to use for the update. + + + + + Optional command line arguments to use for the Guest Additions + installer. Useful for retrofitting features which weren't installed + before in the guest. + + + + + flags. + + + + Progress object to track the operation completion. + + + + + + + + + + + The IProgress interface is used to track and control + asynchronous tasks within VirtualBox. + + An instance of this is returned every time VirtualBox starts + an asynchronous task (in other words, a separate thread) which + continues to run after a method call returns. For example, + , which saves the state of + a running virtual machine, can take a long time to complete. + To be able to display a progress bar, a user interface such as + the VirtualBox graphical user interface can use the IProgress + object returned by that method. + + Note that IProgress is a "read-only" interface in the sense + that only the VirtualBox internals behind the Main API can + create and manipulate progress objects, whereas client code + can only use the IProgress object to monitor a task's + progress and, if is @c true, + cancel the task by calling . + + A task represented by IProgress consists of either one or + several sub-operations that run sequentially, one by one (see + and ). + Every operation is identified by a number (starting from 0) + and has a separate description. + + You can find the individual percentage of completion of the current + operation in and the + percentage of completion of the task as a whole + in . + + Similarly, you can wait for the completion of a particular + operation via or + for the completion of the whole task via + . + + + + ID of the task. + + + + Description of the task. + + + + Initiator of the task. + + + + Whether the task can be interrupted. + + + + + Current progress value of the task as a whole, in percent. + This value depends on how many operations are already complete. + Returns 100 if is @c true. + + + + + + Estimated remaining time until the task completes, in + seconds. Returns 0 once the task has completed; returns -1 + if the remaining time cannot be computed, in particular if + the current progress is 0. + + Even if a value is returned, the estimate will be unreliable + for low progress values. It will become more reliable as the + task progresses; it is not recommended to display an ETA + before at least 20% of a task have completed. + + + + + Whether the task has been completed. + + + + Whether the task has been canceled. + + + + + Result code of the progress task. + Valid only if is @c true. + + + + + + Extended information about the unsuccessful result of the + progress operation. May be @c null if no extended information + is available. + Valid only if is @c true and + indicates a failure. + + + + + + Number of sub-operations this task is divided into. + Every task consists of at least one suboperation. + + + + + Number of the sub-operation being currently executed. + + + + + Description of the sub-operation being currently executed. + + + + + Progress value of the current sub-operation only, in percent. + + + + Weight value of the current sub-operation only. + + + + + When non-zero, this specifies the number of milliseconds after which + the operation will automatically be canceled. This can only be set on + cancelable objects. + + + + + + + + + Waits until the task is done (including all sub-operations) + with a given timeout in milliseconds; specify -1 for an indefinite wait. + + Note that the VirtualBox/XPCOM/COM/native event queues of the calling + thread are not processed while waiting. Neglecting event queues may + have dire consequences (degrade performance, resource hogs, + deadlocks, etc.), this is specially so for the main thread on + platforms using XPCOM. Callers are advised wait for short periods + and service their event queues between calls, or to create a worker + thread to do the waiting. + + + Failed to wait for task completion. + + + + + + Maximum time in milliseconds to wait or -1 to wait indefinitely. + + + + + + + + Waits until the given operation is done with a given timeout in + milliseconds; specify -1 for an indefinite wait. + + See for event queue considerations. + + + Failed to wait for operation completion. + + + + + + Number of the operation to wait for. + Must be less than . + + + + + Maximum time in milliseconds to wait or -1 to wait indefinitely. + + + + + + + + Cancels the task. + + If is @c false, then this method will fail. + + + + Operation cannot be canceled. + + + + + + + + + + + Internal method, not to be called externally. + + + + + + Internal method, not to be called externally. + + Waits until the other task is completed (including all sub-operations) + and forward all changes from the other progress to this progress. This + means sub-operation number, description, percent and so on. + + The caller is responsible for having at least the same count of + sub-operations in this progress object as there are in the other + progress object. + + If the other progress object supports cancel and this object gets any + cancel request (when here enabled as well), it will be forwarded to + the other progress object. + + Error information is automatically preserved (by transferring it to + the current thread's error information). If the caller wants to set it + as the completion state of this progress it needs to be done separately. + + + Waiting time has expired. + + + + Other progress object to be "cloned". + + + Timeout (in ms). Pass 0 for an infinite timeout. + + + + + Internal method, not to be called externally. + + + + + + Internal method, not to be called externally. + + + + Internal method, not to be called externally. + + + + + + + + + + + The ISnapshot interface represents a snapshot of the virtual + machine. + + Together with the differencing media that are created + when a snapshot is taken, a machine can be brought back to + the exact state it was in when the snapshot was taken. + + The ISnapshot interface has no methods, only attributes; snapshots + are controlled through methods of the interface + which also manage the media associated with the snapshot. + The following operations exist: + +
    +
  • creates a new snapshot + by creating new, empty differencing images for the machine's + media and saving the VM settings and (if the VM is running) + the current VM state in the snapshot. + + The differencing images will then receive all data written to + the machine's media, while their parent (base) images + remain unmodified after the snapshot has been taken (see + for details about differencing images). + This simplifies restoring a machine to the state of a snapshot: + only the differencing images need to be deleted. + + The current machine state is not changed by taking a snapshot + except that is set to + the newly created snapshot, which is also added to the machine's + snapshots tree. +
    • + +
  • resets a machine to + the state of a previous snapshot by deleting the differencing + image of each of the machine's media and setting the machine's + settings and state to the state that was saved in the snapshot (if any). + + This destroys the machine's current state. After calling this, + points to the snapshot + that was restored. +
    • + +
  • deletes a snapshot + without affecting the current machine state. + + This does not change the current machine state, but instead frees the + resources allocated when the snapshot was taken: the settings and machine + state file are deleted (if any), and the snapshot's differencing image for + each of the machine's media gets merged with its parent image. + + Neither the current machine state nor other snapshots are affected + by this operation, except that parent media will be modified + to contain the disk data associated with the snapshot being deleted. + + When deleting the current snapshot, the + attribute is set to the current snapshot's parent or @c null if it + has no parent. Otherwise the attribute is unchanged. +
    • +
+ + Each snapshot contains a copy of virtual machine's settings (hardware + configuration etc.). This copy is contained in an immutable (read-only) + instance of which is available from the snapshot's + attribute. When restoring the snapshot, these + settings are copied back to the original machine. + + In addition, if the machine was running when the + snapshot was taken ( is ), + the current VM state is saved in the snapshot (similarly to what happens + when a VM's state is saved). The snapshot is then said to be online + because when restoring it, the VM will be running. + + If the machine was in the Saved or + AbortedSaved state, the snapshot + receives a copy of the execution state file (). + + Otherwise, if the machine was not running ( + or ), the snapshot is offline; + it then contains a so-called "zero execution state", representing a + machine that is powered off. + + + + UUID of the snapshot. + + + + Short name of the snapshot. + Setting this attribute causes to + be called implicitly. + + + + + Optional description of the snapshot. + Setting this attribute causes to + be called implicitly. + + + + + + Timestamp of the snapshot, in milliseconds since 1970-01-01 UTC. + + + + + + @c true if this snapshot is an online snapshot and @c false otherwise. + + When this attribute is @c true, the + attribute of the + object associated with this snapshot + will point to the saved state file. Otherwise, it will be + an empty string. + + + + + + Virtual machine this snapshot is taken on. This object + stores all settings the machine had when taking this snapshot. + + The returned machine object is immutable, i.e. no + any settings can be changed. + + + + + + + Parent snapshot (a snapshot this one is based on), or + @c null if the snapshot has no parent (i.e. is the first snapshot). + + + + + + Child snapshots (all snapshots having this one as a parent). + By inspecting this attribute starting with a machine's root snapshot + (which can be obtained by calling + with a @c null UUID), a machine's snapshots tree can be iterated over. + + + + + + Returns the number of direct children of this snapshot. + + + + + + + + + + + Virtual medium state. + + + + + + Associated medium storage does not exist (either was not created yet or + was deleted). + + + + + Associated storage exists and accessible; this gets set if the + accessibility check performed by + was successful. + + + + + Medium is locked for reading (see ), + no data modification is possible. + + + + + Medium is locked for writing (see ), + no concurrent data reading or modification is possible. + + + + + Medium accessibility check (see ) has + not yet been performed, or else, associated medium storage is not + accessible. In the first case, + is empty, in the second case, it describes the error that occurred. + + + + + Associated medium storage is being created. + + + + + Associated medium storage is being deleted. + + + + + + + Virtual medium type. For each , this defines how the medium is + attached to a virtual machine (see ) and what happens + when a snapshot (see ) is taken of a virtual machine which has + the medium attached. At the moment DVD and floppy media are always of type "writethrough". + + + + + Normal medium (attached directly or indirectly, preserved + when taking snapshots). + + + + + Immutable medium (attached indirectly, changes are wiped out + the next time the virtual machine is started). + + + + + Write through medium (attached directly, ignored when + taking snapshots). + + + + + Allow using this medium concurrently by several machines. + Present since VirtualBox 3.2.0, and accepted since 3.2.8. + + + + + A readonly medium, which can of course be used by several machines. + Present and accepted since VirtualBox 4.0. + + + + + A medium which is indirectly attached, so that one base medium can + be used for several VMs which have their own differencing medium to + store their modifications. In some sense a variant of Immutable + with unset AutoReset flag in each differencing medium. + Present and accepted since VirtualBox 4.0. + + + + + + + Virtual medium image variant. More than one flag may be set. + + + + + + No particular variant requested, results in using the backend default. + + + + + VMDK image split in chunks of less than 2GByte. + + + + + VMDK image representing a raw disk. + + + + + VMDK streamOptimized image. Special import/export format which is + read-only/append-only. + + + + + VMDK format variant used on ESX products. + + + + + Fill new blocks with zeroes while expanding image file. + + + + + Fixed image. Only allowed for base images. + + + + + Differencing image. Only allowed for child images. + + + + + Special flag which requests formatting the disk image. Right now + supported for floppy images only. + + + + + Special flag which suppresses automatic creation of the subdirectory. + Only used when passing the medium variant as an input parameter. + + + + + + + The IMediumAttachment interface links storage media to virtual machines. + For each medium () which has been attached to a + storage controller () of a machine + () via the + method, one instance of IMediumAttachment is added to the machine's + array attribute. + + Each medium attachment specifies the storage controller as well as a + port and device number and the IMedium instance representing a virtual + hard disk or floppy or DVD image. + + For removable media (DVDs or floppies), there are two additional + options. For one, the IMedium instance can be @c null to represent + an empty drive with no media inserted (see ); + secondly, the medium can be one of the pseudo-media for host drives + listed in or . + +

Attaching Hard Disks

+ + Hard disks are attached to virtual machines using the + method and detached using the + method. Depending on a medium's + type (see ), hard disks are attached either + directly or indirectly. + + When a hard disk is being attached directly, it is associated with the + virtual machine and used for hard disk operations when the machine is + running. When a hard disk is being attached indirectly, a new differencing + hard disk linked to it is implicitly created and this differencing hard + disk is associated with the machine and used for hard disk operations. + This also means that if performs + a direct attachment then the same hard disk will be returned in response + to the subsequent call; however if + an indirect attachment is performed then + will return the implicitly created + differencing hard disk, not the original one passed to . In detail: + +
    +
  • Normal base hard disks that do not have children (i.e. + differencing hard disks linked to them) and that are not already + attached to virtual machines in snapshots are attached directly. + Otherwise, they are attached indirectly because having + dependent children or being part of the snapshot makes it impossible + to modify hard disk contents without breaking the integrity of the + dependent party. The attribute allows to + quickly determine the kind of the attachment for the given hard + disk. Note that if a normal base hard disk is to be indirectly + attached to a virtual machine with snapshots then a special + procedure called smart attachment is performed (see below).
    • +
  • Normal differencing hard disks are like normal base hard disks: + they are attached directly if they do not have children and are + not attached to virtual machines in snapshots, and indirectly + otherwise. Note that the smart attachment procedure is never performed + for differencing hard disks.
    • +
  • Immutable hard disks are always attached indirectly because + they are designed to be non-writable. If an immutable hard disk is + attached to a virtual machine with snapshots then a special + procedure called smart attachment is performed (see below).
    • +
  • Writethrough hard disks are always attached directly, + also as designed. This also means that writethrough hard disks cannot + have other hard disks linked to them at all.
    • +
  • Shareable hard disks are always attached directly, + also as designed. This also means that shareable hard disks cannot + have other hard disks linked to them at all. They behave almost + like writethrough hard disks, except that shareable hard disks can + be attached to several virtual machines which are running, allowing + concurrent accesses. You need special cluster software running in + the virtual machines to make use of such disks.
    • +
+ + Note that the same hard disk, regardless of its type, may be attached to + more than one virtual machine at a time. In this case, the machine that is + started first gains exclusive access to the hard disk and attempts to + start other machines having this hard disk attached will fail until the + first machine is powered down. + + Detaching hard disks is performed in a deferred fashion. This means + that the given hard disk remains associated with the given machine after a + successful call until + is called to save all changes to + machine settings to disk. This deferring is necessary to guarantee that + the hard disk configuration may be restored at any time by a call to + before the settings + are saved (committed). + + Note that if is called after + indirectly attaching some hard disks to the machine but before a call to + is made, it will implicitly delete + all differencing hard disks implicitly created by + for these indirect attachments. + Such implicitly created hard disks will also be immediately deleted when + detached explicitly using the + call if it is made before . This + implicit deletion is safe because newly created differencing hard + disks do not contain any user data. + + However, keep in mind that detaching differencing hard disks that were + implicitly created by + before the last call will + not implicitly delete them as they may already contain some data + (for example, as a result of virtual machine execution). If these hard + disks are no more necessary, the caller can always delete them explicitly + using after they are actually de-associated + from this machine by the call. + +

Smart Attachment

+ + When normal base or immutable hard disks are indirectly attached to a + virtual machine then some additional steps are performed to make sure the + virtual machine will have the most recent "view" of the hard disk being + attached. These steps include walking through the machine's snapshots + starting from the current one and going through ancestors up to the first + snapshot. Hard disks attached to the virtual machine in all + of the encountered snapshots are checked whether they are descendants of + the given normal base or immutable hard disk. The first found child (which + is the differencing hard disk) will be used instead of the normal base or + immutable hard disk as a parent for creating a new differencing hard disk + that will be actually attached to the machine. And only if no descendants + are found or if the virtual machine does not have any snapshots then the + normal base or immutable hard disk will be used itself as a parent for + this differencing hard disk. + + It is easier to explain what smart attachment does using the + following example: + 
+BEFORE attaching B.vdi:       AFTER attaching B.vdi:
+
+Snapshot 1 (B.vdi)            Snapshot 1 (B.vdi)
+ Snapshot 2 (D1->B.vdi)        Snapshot 2 (D1->B.vdi)
+  Snapshot 3 (D2->D1.vdi)       Snapshot 3 (D2->D1.vdi)
+   Snapshot 4 (none)             Snapshot 4 (none)
+    CurState   (none)             CurState   (D3->D2.vdi)
+
+                              NOT
+                                 ...
+                                  CurState   (D3->B.vdi)
+
+ The first column is the virtual machine configuration before the base hard + disk B.vdi is attached, the second column shows the machine after + this hard disk is attached. Constructs like D1->B.vdi and similar + mean that the hard disk that is actually attached to the machine is a + differencing hard disk, D1.vdi, which is linked to (based on) + another hard disk, B.vdi. + + As we can see from the example, the hard disk B.vdi was detached + from the machine before taking Snapshot 4. Later, after Snapshot 4 was + taken, the user decides to attach B.vdi again. B.vdi has + dependent child hard disks (D1.vdi, D2.vdi), therefore + it cannot be attached directly and needs an indirect attachment (i.e. + implicit creation of a new differencing hard disk). Due to the smart + attachment procedure, the new differencing hard disk + (D3.vdi) will be based on D2.vdi, not on + B.vdi itself, since D2.vdi is the most recent view of + B.vdi existing for this snapshot branch of the given virtual + machine. + + Note that if there is more than one descendant hard disk of the given base + hard disk found in a snapshot, and there is an exact device, channel and + bus match, then this exact match will be used. Otherwise, the youngest + descendant will be picked up. + + There is one more important aspect of the smart attachment procedure which + is not related to snapshots at all. Before walking through the snapshots + as described above, the backup copy of the current list of hard disk + attachment is searched for descendants. This backup copy is created when + the hard disk configuration is changed for the first time after the last + call and used by + to undo the recent hard disk + changes. When such a descendant is found in this backup copy, it will be + simply re-attached back, without creating a new differencing hard disk for + it. This optimization is necessary to make it possible to re-attach the + base or immutable hard disk to a different bus, channel or device slot + without losing the contents of the differencing hard disk actually + attached to the machine in place of it. + + + + + Machine object for this medium attachment. + + + + Medium object associated with this attachment; it + can be @c null for removable devices. + + + + Name of the storage controller of this attachment; this + refers to one of the controllers in + by name. + + + + Port number of this attachment. + See for the meaning of this value for the different controller types. + + + + + Device slot number of this attachment. + See for the meaning of this value for the different controller types. + + + + + Device type of this attachment. + + + + Pass I/O requests through to a device on the host. + + + + Whether guest-triggered eject results in unmounting the medium. + + + + Signals that the removable medium has been ejected. This is not + necessarily equivalent to having a @c null medium association. + + + + Whether the associated medium is non-rotational. + + + + Whether the associated medium supports discarding unused blocks. + + + + Whether this attachment is hot pluggable or not. + + + + The bandwidth group this medium attachment is assigned to. + + + + + + + The IMedium interface represents virtual storage for a machine's + hard disks, CD/DVD or floppy drives. It will typically represent + a disk image on the host, for example a VDI or VMDK file representing + a virtual hard disk, or an ISO or RAW file representing virtual + removable media, but can also point to a network location (e.g. + for iSCSI targets). + + Instances of IMedium are connected to virtual machines by way of medium + attachments, which link the storage medium to a particular device slot + of a storage controller of the virtual machine. + In the VirtualBox API, virtual storage is therefore always represented + by the following chain of object links: + +
    +
  • contains an array of + storage controllers (IDE, SATA, SCSI, SAS or a floppy controller; + these are instances of ).
    • +
  • contains an array of + medium attachments (instances of + created by ), + each containing a storage controller from the above array, a + port/device specification, and an instance of IMedium representing + the medium storage (image file). + + For removable media, the storage medium is optional; a medium + attachment with no medium represents a CD/DVD or floppy drive + with no medium inserted. By contrast, hard disk attachments + will always have an IMedium object attached.
    • +
  • Each IMedium in turn points to a storage unit (such as a file + on the host computer or a network resource) that holds actual + data. This location is represented by the + attribute.
    • +
+ + Existing media are opened using ; + new hard disk media can be created with the VirtualBox API using the + method. Differencing hard + disks (see below) are usually implicitly created by VirtualBox as + needed, but may also be created explicitly using . + VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these + should be created with external tools and then opened from within VirtualBox. + + Only for CD/DVDs and floppies, an IMedium instance can also represent a host + drive. In that case the attribute contains the UUID of + one of the drives in or . + +

Media registries

+ + When a medium has been opened or created using one of the aforementioned + APIs, it becomes "known" to VirtualBox. Known media can be attached + to virtual machines and re-found through . + They also appear in the global + , + and + arrays. + + Prior to VirtualBox 4.0, opening a medium added it to a global media registry + in the VirtualBox.xml file, which was shared between all machines and made + transporting machines and their media from one host to another difficult. + + Starting with VirtualBox 4.0, media are only added to a registry when they are + attached to a machine using . For + backwards compatibility, which registry a medium is added to depends on which + VirtualBox version created a machine: + +
    +
  • If the medium has first been attached to a machine which was created by + VirtualBox 4.0 or later, it is added to that machine's media registry in + the machine XML settings file. This way all information about a machine's + media attachments is contained in a single file and can be transported + easily.
    • +
  • For older media attachments (i.e. if the medium was first attached to a + machine which was created with a VirtualBox version before 4.0), media + continue to be registered in the global VirtualBox settings file, for + backwards compatibility.
    • +
+ + See for more information. + + Media are removed from media registries by the , + and methods. + +

Accessibility checks

+ + VirtualBox defers media accessibility checks until the + method is called explicitly on a medium. This is done to make the VirtualBox object + ready for serving requests as fast as possible and let the end-user + application decide if it needs to check media accessibility right away or not. + + As a result, when VirtualBox starts up (e.g. the VirtualBox + object gets created for the first time), all known media are in the + "Inaccessible" state, but the value of the + attribute is an empty string because no actual accessibility check has + been made yet. + + After calling , a medium is considered + accessible if its storage unit can be read. In that case, the + attribute has a value of "Created". If the storage + unit cannot be read (for example, because it is located on a disconnected + network resource, or was accidentally deleted outside VirtualBox), + the medium is considered inaccessible, which is indicated by the + "Inaccessible" state. The exact reason why the medium is inaccessible can be + obtained by reading the attribute. + +

Medium types

+ + There are five types of medium behavior which are stored in the + attribute (see ) and + which define the medium's behavior with attachments and snapshots. + + All media can be also divided in two groups: base media and + differencing media. A base medium contains all sectors of the + medium data in its own storage and therefore can be used independently. + In contrast, a differencing medium is a "delta" to some other medium and + contains only those sectors which differ from that other medium, which is + then called a parent. The differencing medium is said to be + linked to that parent. The parent may be itself a differencing + medium, thus forming a chain of linked media. The last element in that + chain must always be a base medium. Note that several differencing + media may be linked to the same parent medium. + + Differencing media can be distinguished from base media by querying the + attribute: base media do not have parents they would + depend on, so the value of this attribute is always @c null for them. + Using this attribute, it is possible to walk up the medium tree (from the + child medium to its parent). It is also possible to walk down the tree + using the attribute. + + Note that the type of all differencing media is "normal"; all other + values are meaningless for them. Base media may be of any type. + +

Automatic composition of the file name part

+ + Another extension to the attribute is that + there is a possibility to cause VirtualBox to compose a unique value for + the file name part of the location using the UUID of the hard disk. This + applies only to hard disks in state, + e.g. before the storage unit is created, and works as follows. You set the + value of the attribute to a location + specification which only contains the path specification but not the file + name part and ends with either a forward slash or a backslash character. + In response, VirtualBox will generate a new UUID for the hard disk and + compose the file name using the following pattern: + 
+        <path>/{<uuid>}.<ext>
+
+ where <path> is the supplied path specification, + <uuid> is the newly generated UUID and <ext> + is the default extension for the storage format of this hard disk. After + that, you may call any of the methods that create a new hard disk storage + unit and they will use the generated UUID and file name. + + + + + UUID of the medium. For a newly created medium, this value is a randomly + generated UUID. + + + For media in one of MediumState_NotCreated, MediumState_Creating or + MediumState_Deleting states, the value of this property is undefined + and will most likely be an empty UUID. + + + + + + + Optional description of the medium. For a newly created medium the value + of this attribute is an empty string. + + Medium types that don't support this attribute will return E_NOTIMPL in + attempt to get or set this attribute's value. + + + For some storage types, reading this attribute may return an outdated + (last known) value when is or because the value of this attribute is + stored within the storage unit itself. Also note that changing the + attribute value is not possible in such case, as well as when the + medium is the state. + + + + + + + Returns the current medium state, which is the last state set by + the accessibility check performed by . + If that method has not yet been called on the medium, the state + is "Inaccessible"; as opposed to truly inaccessible media, the + value of will be an empty string in + that case. + + As of version 3.1, this no longer performs an accessibility check + automatically; call for that. + + + + + + + Returns the storage format variant information for this medium + as an array of the flags described at . + Before is called this method returns + an undefined value. + + + + + + Location of the storage unit holding medium data. + + The format of the location string is medium type specific. For medium + types using regular files in a host's file system, the location + string is the full file name. + + + + + + Name of the storage unit holding medium data. + + The returned string is a short version of the + attribute that is suitable for representing the medium in situations + where the full location specification is too long (such as lists + and comboboxes in GUI frontends). This string is also used by frontends + to sort the media list alphabetically when needed. + + For example, for locations that are regular files in the host's file + system, the value of this attribute is just the file name (+ extension), + without the path specification. + + Note that as opposed to the attribute, the name + attribute will not necessary be unique for a list of media of the + given type and format. + + + + + Kind of device (DVD/Floppy/HardDisk) which is applicable to this + medium. + + + + True if this corresponds to a drive on the host. + + + + + Physical size of the storage unit used to hold medium data (in bytes). + + + For media whose is , the value of this property is the + last known size. For media, + the returned value is zero. + + + + + + + Storage format of this medium. + + The value of this attribute is a string that specifies a backend used + to store medium data. The storage format is defined when you create a + new medium or automatically detected when you open an existing medium, + and cannot be changed later. + + The list of all storage formats supported by this VirtualBox + installation can be obtained using + . + + + + + + Storage medium format object corresponding to this medium. + + The value of this attribute is a reference to the medium format object + that specifies the backend properties used to store medium data. The + storage format is defined when you create a new medium or automatically + detected when you open an existing medium, and cannot be changed later. + + @c null is returned if there is no associated medium format + object. This can e.g. happen for medium objects representing host + drives and other special medium objects. + + + + + + Type (role) of this medium. + + The following constraints apply when changing the value of this + attribute: +
    +
  • If a medium is attached to a virtual machine (either in the + current state or in one of the snapshots), its type cannot be + changed. +
    • +
  • As long as the medium has children, its type cannot be set + to . +
    • +
  • The type of all differencing media is + and cannot be changed. +
    • +
+ + The type of a newly created or opened medium is set to + , except for DVD and floppy media, + which have a type of . + + + + + + Returns which medium types can selected for this medium. + + + This attribute is not implemented at the moment. + + + + + + + Parent of this medium (the medium this medium is directly based + on). + + Only differencing media have parents. For base (non-differencing) + media, @c null is returned. + + + + + + Children of this medium (all differencing media directly based + on this medium). A @c null array is returned if this medium + does not have any children. + + + + + + Base medium of this medium. + + If this is a differencing medium, its base medium is the medium + the given medium branch starts from. For all other types of media, this + property returns the medium object itself (i.e. the same object this + property is read on). + + + + + + Returns @c true if this medium is read-only and @c false otherwise. + + A medium is considered to be read-only when its contents cannot be + modified without breaking the integrity of other parties that depend on + this medium such as its child media or snapshots of virtual machines + where this medium is attached to these machines. If there are no + children and no such snapshots then there is no dependency and the + medium is not read-only. + + The value of this attribute can be used to determine the kind of the + attachment that will take place when attaching this medium to a + virtual machine. If the value is @c false then the medium will + be attached directly. If the value is @c true then the medium + will be attached indirectly by creating a new differencing child + medium for that. See the interface description for more information. + + Note that all Immutable media + are always read-only while all + Writethrough media are + always not. + + + The read-only condition represented by this attribute is related to + the medium type and usage, not to the current + medium state and not to the read-only + state of the storage unit. + + + + + + + Logical size of this medium (in bytes), as reported to the + guest OS running inside the virtual machine this medium is + attached to. The logical size is defined when the medium is created + and cannot be changed later. + + + For media whose state is is , the value of this property is the + last known logical size. For + media, the returned value is zero. + + + + + + + Whether this differencing medium will be automatically reset each + time a virtual machine it is attached to is powered up. This + attribute is automatically set to @c true for the last + differencing image of an "immutable" medium (see + ). + + See for more information about resetting + differencing media. + + + Reading this property on a base (non-differencing) medium will + always @c false. Changing the value of this property in this + case is not supported. + + + + This is not a differencing medium (when changing the attribute + value). + + + + + + + Text message that represents the result of the last accessibility + check performed by . + + An empty string is returned if the last accessibility check + was successful or has not yet been called. As a result, if + is "Inaccessible" and this attribute is empty, + then has yet to be called; this is the + default value of media after VirtualBox initialization. + A non-empty string indicates a failure and should normally describe + a reason of the failure (for example, a file read error). + + + + + + Array of UUIDs of all machines this medium is attached to. + + A @c null array is returned if this medium is not attached to any + machine or to any machine's snapshot. + + + The returned array will include a machine even if this medium is not + attached to that machine in the current state but attached to it in + one of the machine's snapshots. See for + details. + + + + + + + + Changes the UUID and parent UUID for a hard disk medium. + + + + Select whether a new image UUID is set or not. + + + + + New UUID for the image. If an empty string is passed, then a new + UUID is automatically created, provided that @a setImageId is @c true. + Specifying a zero UUID is not allowed. + + + + + Select whether a new parent UUID is set or not. + + + + + New parent UUID for the image. If an empty string is passed, then a + new UUID is automatically created, provided @a setParentId is + @c true. A zero UUID is valid. + + + + Invalid parameter combination. + + + Medium is not a hard disk medium. + + + + + + + If the current medium state (see ) is one of + "Created", "Inaccessible" or "LockedRead", then this performs an + accessibility check on the medium and sets the value of the + attribute accordingly; that value is also returned for convenience. + + For all other state values, this does not perform a refresh but returns + the state only. + + The refresh, if performed, may take a long time (several seconds or even + minutes, depending on the storage unit location and format) because it performs an + accessibility check of the storage unit. This check may cause a significant + delay if the storage unit of the given medium is, for example, a file located + on a network share which is not currently accessible due to connectivity + problems. In that case, the call will not return until a timeout + interval defined by the host OS for this operation expires. For this reason, + it is recommended to never read this attribute on the main UI thread to avoid + making the UI unresponsive. + + If the last known state of the medium is "Created" and the accessibility + check fails, then the state would be set to "Inaccessible", and + may be used to get more details about the + failure. If the state of the medium is "LockedRead", then it remains the + same, and a non-empty value of will + indicate a failed accessibility check in this case. + + Note that not all medium states are applicable to all medium types. + + + + New medium state. + + + + + + + + Returns an array of UUIDs of all snapshots of the given machine where + this medium is attached to. + + If the medium is attached to the machine in the current state, then the + first element in the array will always be the ID of the queried machine + (i.e. the value equal to the @c machineId argument), followed by + snapshot IDs (if any). + + If the medium is not attached to the machine in the current state, then + the array will contain only snapshot IDs. + + The returned array may be @c null if this medium is not attached + to the given machine at all, neither in the current state nor in one of + the snapshots. + + + + UUID of the machine to query. + + + + + Array of snapshot UUIDs of the given machine using this medium. + + + + + + + + Locks this medium for reading. + + A read lock is shared: many clients can simultaneously lock the + same medium for reading unless it is already locked for writing (see + ) in which case an error is returned. + + When the medium is locked for reading, it cannot be modified + from within VirtualBox. This means that any method that changes + the properties of this medium or contents of the storage unit + will return an error (unless explicitly stated otherwise). That + includes an attempt to start a virtual machine that wants to + write to the medium. + + When the virtual machine is started up, it locks for reading all + media it uses in read-only mode. If some medium cannot be locked + for reading, the startup procedure will fail. + A medium is typically locked for reading while it is used by a running + virtual machine but has a depending differencing image that receives + the actual write operations. This way one base medium can have + multiple child differencing images which can be written to + simultaneously. Read-only media such as DVD and floppy images are + also locked for reading only (so they can be in use by multiple + machines simultaneously). + + A medium is also locked for reading when it is the source of a + write operation such as or . + + The medium locked for reading must be unlocked by abandoning the + returned token object, see . Calls to + can be nested and the lock is actually released + when all callers have abandoned the token. + + This method sets the medium state (see ) to + "LockedRead" on success. The medium's previous state must be + one of "Created", "Inaccessible" or "LockedRead". + + Locking an inaccessible medium is not an error; this method performs + a logical lock that prevents modifications of this medium through + the VirtualBox API, not a physical file-system lock of the underlying + storage unit. + + This method returns the current state of the medium + before the operation. + + + Invalid medium state (e.g. not created, locked, inaccessible, + creating, deleting). + + + + + + Token object, when this is released (reference count reaches 0) then + the lock count is decreased. The lock is released when the lock count + reaches 0. + + + + + + + + Locks this medium for writing. + + A write lock, as opposed to , is + exclusive: there may be only one client holding a write lock, + and there may be no read locks while the write lock is held. + As a result, read-locking fails if a write lock is held, and + write-locking fails if either a read or another write lock is held. + + When a medium is locked for writing, it cannot be modified + from within VirtualBox, and it is not guaranteed that the values + of its properties are up-to-date. Any method that changes the + properties of this medium or contents of the storage unit will + return an error (unless explicitly stated otherwise). + + When a virtual machine is started up, it locks for writing all + media it uses to write data to. If any medium could not be locked + for writing, the startup procedure will fail. If a medium has + differencing images, then while the machine is running, only + the last ("leaf") differencing image is locked for writing, + whereas its parents are locked for reading only. + + A medium is also locked for writing when it is the target of a + write operation such as or . + + The medium locked for writing must be unlocked by abandoning the + returned token object, see . Write locks + cannot be nested. + + This method sets the medium state (see ) to + "LockedWrite" on success. The medium's previous state must be + either "Created" or "Inaccessible". + + Locking an inaccessible medium is not an error; this method performs + a logical lock that prevents modifications of this medium through + the VirtualBox API, not a physical file-system lock of the underlying + storage unit. + + + Invalid medium state (e.g. not created, locked, inaccessible, + creating, deleting). + + + + + + Token object, when this is released (reference count reaches 0) then + the lock is released. + + + + + + + + Closes this medium. + + The medium must not be attached to any known virtual machine + and must not have any known child media, otherwise the + operation will fail. + + When the medium is successfully closed, it is removed from + the list of registered media, but its storage unit is not + deleted. In particular, this means that this medium can + later be opened again using the + call. + + Note that after this method successfully returns, the given medium + object becomes uninitialized. This means that any attempt + to call any of its methods or attributes will fail with the + "Object not ready" (E_ACCESSDENIED) error. + + + Invalid medium state (other than not created, created or + inaccessible). + + + Medium attached to virtual machine. + + + Settings file not accessible. + + + Could not parse the settings file. + + + + + + + + + + + Returns the value of the custom medium property with the given name. + + The list of all properties supported by the given medium format can + be obtained with . + + If this method returns an empty string in @a value, the requested + property is supported but currently not assigned any value. + + + Requested property does not exist (not supported by the format). + + @a name is @c null or empty. + + + Name of the property to get. + + + Current property value. + + + + + + + Sets the value of the custom medium property with the given name. + + The list of all properties supported by the given medium format can + be obtained with . + + Setting the property value to @c null or an empty string is + equivalent to deleting the existing value. A default value (if it is + defined for this property) will be used by the format backend in this + case. + + + Requested property does not exist (not supported by the format). + + @a name is @c null or empty. + + + Name of the property to set. + + + Property value to set. + + + + + + + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + Currently the value of this argument is ignored and the method + always returns all existing properties. + + The list of all properties supported by the given medium format can + be obtained with . + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + + For properties that do not have assigned values, an empty string is + returned at the appropriate index in the @a returnValues array. + + + + + Names of properties to get. + + + + Names of returned properties. + + + Values of returned properties. + + + + + + + Sets values for a group of properties in one call. + + The names of the properties to set are passed in the @a names + array along with the new values for them in the @a values array. Both + arrays have the same number of elements with each element at the given + index in the first array corresponding to an element at the same index + in the second array. + + If there is at least one property name in @a names that is not valid, + the method will fail before changing the values of any other properties + from the @a names array. + + Using this method over is preferred if you + need to set several properties at once since it is more efficient. + + The list of all properties supported by the given medium format can + be obtained with . + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. A default value (if it is defined for + this property) will be used by the format backend in this case. + + + Names of properties to set. + + + Values of properties to set. + + + + + + + + + Starts creating a hard disk storage unit (fixed/dynamic, according + to the variant flags) in the background. The previous storage unit + created for this object, if any, must first be deleted using + , otherwise the operation will fail. + + Before the operation starts, the medium is placed in + state. If the create operation + fails, the medium will be placed back in + state. + + After the returned progress object reports that the operation has + successfully completed, the medium state will be set to , the medium will be remembered by this + VirtualBox installation and may be attached to virtual machines. + + + The variant of storage creation operation is not supported. See . + + + + Maximum logical size of the medium in bytes. + + + Exact image variant which should be created (as a combination of + flags). + + + Progress object to track the operation completion. + + + + + + + Starts deleting the storage unit of this medium. + + The medium must not be attached to any known virtual machine and must + not have any known child media, otherwise the operation will fail. + It will also fail if there is no storage unit to delete or if deletion + is already in progress, or if the medium is being in use (locked for + read or for write) or inaccessible. Therefore, the only valid state for + this operation to succeed is . + + Before the operation starts, the medium is placed in + state and gets removed from the list + of remembered hard disks (media registry). If the delete operation + fails, the medium will be remembered again and placed back to + state. + + After the returned progress object reports that the operation is + complete, the medium state will be set to + and you will be able to use one of + the storage creation methods to create it again. + + + + + Medium is attached to a virtual machine. + + + Storage deletion is not allowed because neither of storage creation + operations are supported. See + . + + + + If the deletion operation fails, it is not guaranteed that the storage + unit still exists. You may check the value + to answer this question. + + + + Progress object to track the operation completion. + + + + + + + + + Starts creating an empty differencing storage unit based on this + medium in the format and at the location defined by the @a target + argument. + + The target medium must be in + state (i.e. must not have an existing storage unit). Upon successful + completion, this operation will set the type of the target medium to + and create a storage unit necessary to + represent the differencing medium data in the given format (according + to the storage format of the target object). + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + + The medium will be set to + state for the duration of this operation. + + + Medium not in @c NotCreated state. + + + + Target medium. + + + Exact image variant which should be created (as a combination of + flags). + + + Progress object to track the operation completion. + + + + + + + Starts merging the contents of this medium and all intermediate + differencing media in the chain to the given target medium. + + The target medium must be either a descendant of this medium or + its ancestor (otherwise this method will immediately return a failure). + It follows that there are two logical directions of the merge operation: + from ancestor to descendant (forward merge) and from descendant to + ancestor (backward merge). Let us consider the following medium + chain: + + 
Base <- Diff_1 <- Diff_2
+ + Here, calling this method on the Base medium object with + Diff_2 as an argument will be a forward merge; calling it on + Diff_2 with Base as an argument will be a backward + merge. Note that in both cases the contents of the resulting medium + will be the same, the only difference is the medium object that takes + the result of the merge operation. In case of the forward merge in the + above example, the result will be written to Diff_2; in case of + the backward merge, the result will be written to Base. In + other words, the result of the operation is always stored in the target + medium. + + Upon successful operation completion, the storage units of all media in + the chain between this (source) medium and the target medium, including + the source medium itself, will be automatically deleted and the + relevant medium objects (including this medium) will become + uninitialized. This means that any attempt to call any of + their methods or attributes will fail with the + "Object not ready" (E_ACCESSDENIED) error. Applied to the above + example, the forward merge of Base to Diff_2 will + delete and uninitialize both Base and Diff_1 media. + Note that Diff_2 in this case will become a base medium + itself since it will no longer be based on any other medium. + + Considering the above, all of the following conditions must be met in + order for the merge operation to succeed: +
    +
  • + Neither this (source) medium nor any intermediate + differencing medium in the chain between it and the target + medium is attached to any virtual machine. +
    • +
  • + Neither the source medium nor the target medium is an + medium. +
    • +
  • + The part of the medium tree from the source medium to the + target medium is a linear chain, i.e. all medium in this + chain have exactly one child which is the next medium in this + chain. The only exception from this rule is the target medium in + the forward merge operation; it is allowed to have any number of + child media because the merge operation will not change its + logical contents (as it is seen by the guest OS or by children). +
    • +
  • + None of the involved media are in + or + state. +
    • +
+ + + This (source) medium and all intermediates will be placed to state and the target medium will be + placed to state and for the + duration of this operation. + + + + Target medium. + + + Progress object to track the operation completion. + + + + + + + + + Starts creating a clone of this medium in the format and at the + location defined by the @a target argument. + + The target medium must be either in + state (i.e. must not have an existing storage unit) or in + state (i.e. created and not locked, and + big enough to hold the data or else the copy will be partial). Upon + successful completion, the cloned medium will contain exactly the + same sector data as the medium being cloned, except that in the + first case a new UUID for the clone will be randomly generated, and in + the second case the UUID will remain unchanged. + + The @a parent argument defines which medium will be the parent + of the clone. Passing a @c null reference indicates that the clone will + be a base image, i.e. completely independent. It is possible to specify + an arbitrary medium for this parameter, including the parent of the + medium which is being cloned. Even cloning to a child of the source + medium is possible. Note that when cloning to an existing image, the + @a parent argument is ignored. + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + + This medium will be placed to + state for the duration of this operation. + + + The specified cloning variant is not supported at the moment. + + + + Target medium. + + + Exact image variant which should be created (as a combination of + flags). + + + Parent of the cloned medium. + + + Progress object to track the operation completion. + + + + + + + Starts creating a clone of this medium in the format and at the + location defined by the @a target argument. + + The target medium must be either in + state (i.e. must not have an existing storage unit) or in + state (i.e. created and not locked, and + big enough to hold the data or else the copy will be partial). Upon + successful completion, the cloned medium will contain exactly the + same sector data as the medium being cloned, except that in the + first case a new UUID for the clone will be randomly generated, and in + the second case the UUID will remain unchanged. + + The @a parent argument defines which medium will be the parent + of the clone. In this case the clone will be a base image, i.e. + completely independent. It is possible to specify an arbitrary + medium for this parameter, including the parent of the + medium which is being cloned. Even cloning to a child of the source + medium is possible. Note that when cloning to an existing image, the + @a parent argument is ignored. + + After the returned progress object reports that the operation is + successfully complete, the target medium gets remembered by this + VirtualBox installation and may be attached to virtual machines. + + + This medium will be placed to + state for the duration of this operation. + + + The specified cloning variant is not supported at the moment. + + + + Target medium. + + + flags). + + + Progress object to track the operation completion. + + + + + + + + + Changes the location of this medium. Some medium types may support + changing the storage unit location by simply changing the value of the + associated property. In this case the operation is performed + immediately, and @a progress is returning a @c null reference. + Otherwise on success there is a progress object returned, which + signals progress and completion of the operation. This distinction is + necessary because for some formats the operation is very fast, while + for others it can be very slow (moving the image file by copying all + data), and in the former case it'd be a waste of resources to create + a progress object which will immediately signal completion. + + When setting a location for a medium which corresponds to a/several + regular file(s) in the host's file system, the given file name may be + either relative to the VirtualBox + home folder or absolute. Note that if the given location + specification does not contain the file extension part then a proper + default extension will be automatically appended by the implementation + depending on the medium type. + + + The operation is not implemented yet. + + + Medium format does not support changing the location. + + + + New location. + + + Progress object to track the operation completion. + + + + + + + Starts compacting of this medium. This means that the medium is + transformed into a possibly more compact storage representation. + This potentially creates temporary images, which can require a + substantial amount of additional disk space. + + This medium will be placed to + state and all its parent media (if any) will be placed to + state for the duration of this + operation. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + + Medium format does not support compacting (but potentially + needs it). + + + + Progress object to track the operation completion. + + + + + + + Starts resizing this medium. This means that the nominal size of the + medium is set to the new value. Both increasing and decreasing the + size is possible, and there are no safety checks, since VirtualBox + does not make any assumptions about the medium contents. + + Resizing usually needs additional disk space, and possibly also + some temporary disk space. Note that resize does not create a full + temporary copy of the medium, so the additional disk space requirement + is usually much lower than using the clone operation. + + This medium will be placed to + state for the duration of this operation. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + + Medium format does not support resizing. + + + + New nominal capacity of the medium in bytes. + + + Progress object to track the operation completion. + + + + + + + Starts erasing the contents of this differencing medium. + + This operation will reset the differencing medium to its initial + state when it does not contain any sector data and any read operation is + redirected to its parent medium. This automatically gets called + during VM power-up for every medium whose + attribute is @c true. + + The medium will be write-locked for the duration of this operation (see + ). + + + This is not a differencing medium. + + + Medium is not in or + state. + + + + Progress object to track the operation completion. + + + + + + + Starts encryption of this medium. This means that the stored data in the + medium is encrypted. + + This medium will be placed to + state. + + Please note that the results can be either returned straight away, + or later as the result of the background operation via the object + returned via the @a progress parameter. + + + Encryption is not supported for this medium because it is attached to more than one VM + or has children. + + + + + The current password the medium is protected with. Use an empty string to indicate + that the medium isn't encrypted. + + + + + The cipher to use for encryption. An empty string indicates no encryption for the + result. + + + + + The new password the medium should be protected with. An empty password and password ID + will result in the medium being encrypted with the current password. + + + + The ID of the new password when unlocking the medium. + + + Progress object to track the operation completion. + + + + + + + Returns the encryption settings for this medium. + + + Encryption is not configured for this medium. + + + + The cipher used for encryption. + + + The ID of the password when unlocking the medium. + + + + + + + Checks whether the supplied password is correct for the medium. + + + Encryption is not configured for this medium. + + + The given password is incorrect. + + + + The password to check. + + + + + + Open the medium for I/O. + + + Set this to open the medium for both reading and writing. When + not set the medium is opened readonly. + + + Password for accessing an encrypted medium. Must be empty if not encrypted. + + + Medium I/O object. + + + + + + + + This is a helper function that combines the functionality of + and . The target medium will take the + contents of the calling medium. + + The specified cloning variant is not supported at the moment. + + + + Method will be moved to appropriate location at the next major API release. + + + + + Target medium. + + + New nominal capacity of the medium in bytes. + + + Exact image variant which should be created (as a combination of + flags). + + + Parent of the cloned medium. + + + Progress object to track the operation completion. + + + + + + + + + + + + + + + + + + + + + + + + + Medium format capability flags. + + + + + Supports UUIDs as expected by VirtualBox code. + + + + + + Supports creating fixed size images, allocating all space instantly. + + + + + + Supports creating dynamically growing images, allocating space on + demand. + + + + + + Supports creating images split in chunks of a bit less than 2 GBytes. + + + + + + Supports being used as a format for differencing media (see ). + + + + + + Supports asynchronous I/O operations for at least some configurations. + + + + + + The format backend operates on files (the + attribute of the medium specifies a file used to store medium + data; for a list of supported file extensions see + ). + + + + + + The format backend uses the property interface to configure the storage + location and properties (the + method is used to get access to properties supported by the given medium format). + + + + + + The format backend uses the TCP networking interface for network access. + + + + + + The format backend supports virtual filesystem functionality. + + + + + + The format backend supports discarding blocks. + + + + + + Indicates that this is a frequently used format backend. + + + + + + + + + The IMediumFormat interface represents a medium format. + + Each medium format has an associated backend which is used to handle + media stored in this format. This interface provides information + about the properties of the associated backend. + + Each medium format is identified by a string represented by the + attribute. This string is used in calls like + to specify the desired + format. + + The list of all supported medium formats can be obtained using + . + + + + + + + Identifier of this format. + + The format identifier is a non-@c null non-empty ASCII string. Note that + this string is case-insensitive. This means that, for example, all of + the following strings: + 
+          "VDI"
+          "vdi"
+          "VdI"
+ refer to the same medium format. + + This string is used in methods of other interfaces where it is necessary + to specify a medium format, such as + . + + + + + + Human readable description of this format. + + Mainly for use in file open dialogs. + + + + + + Capabilities of the format as an array of the flags. + + For the meaning of individual capability flags see + . + + + + + + Returns two arrays describing the supported file extensions. + + The first array contains the supported extensions and the seconds one + the type each extension supports. Both have the same size. + + Note that some backends do not work on files, so this array may be + empty. + + + + + The array of supported extensions. + + + The array which indicates the device type for every given extension. + + + + + + Returns several arrays describing the properties supported by this + format. + + An element with the given index in each array describes one + property. Thus, the number of elements in each returned array is the + same and corresponds to the number of supported properties. + + The returned arrays are filled in only if the + flag is set. + All arguments must be non-@c null. + + , + + + + Array of property names. + + + Array of property descriptions. + + + Array of property types. + + + Array of property flags. + + + Array of default property values. + + + + + + + + + + The IDataStream interface is used to retrieve a data stream. It is + returned by . + + + + Recommended size of a read. Requesting a larger read may be + possible in certain situations, but it is not guaranteed. + + + + + Read data from the stream. + + Waiting time has expired. + + + + How many bytes to try read. + + + + Timeout (in ms) for limiting the wait time for data to be available. + Pass 0 for an infinite timeout. + + + + Array of data read. This may be shorter than the specified size. + Returning a zero-sized array indicates the end of the stream, if the + status is successful. + + + + + + + + + + Partition table types. + + + + + + + + + + The IMediumIO interface is used to access and modify the content of a + medium. It is returned by . + + + + The open medium. + + + + Whether the medium can be written to. (It can always be read from.) + + + + + Returns the virtual file system explorer for the medium. + + This will attempt to recognize the format of the medium content and + present it as a virtual directory structure to the API user. + + A FAT floppy image will be represented will a single root subdir 'fat12' + that gives access to the file system content. + + A ISO-9660 image will have one subdir in the root for each format present + in the image, so the API user can select which data view to access (iso9660, + rockridge, joliet, udf, hfs, ...). + + A partitioned harddisk image will have subdirs for each partition. The + the filesystem content of each partition can be accessed thru the subdirs + if we have a file system interpreter for it. There will also be raw files + for each subdirectory, to provide a simple way of accessing raw partition + data from an API client. + + Please note that the explorer may show inconsistent information if + the API user modifies the raw image content after it was opened. + + + + + + Read data from the medium. + + + The byte offset into the medium to start reading at. + + + How many bytes to try read. + + + Array of data read. This may be shorter than the specified size. + + + + + + Write data to the medium. + + + The byte offset into the medium to start reading at. + + + Array of data to write. + + + How many bytes were actually written. + + + + + + Formats the medium as FAT. Generally only useful for floppy images as + no partition table will be created. + + + Quick format it when set. + + + + + + Writes an empty partition table to the disk. + + + The partition table format. + + + + When @c true a partition table entry for the whole disk is created. + Otherwise the partition table is empty. + + + + + + + Converts the currently opened image into a stream of the specified + image type/variant. It is sufficient to open the image in read-only + mode. Only few types and variants are supported due to the inherent + restrictions of the output style. + + The requested format/variant combination cannot handle stream output. + + + An error occurred during the conversion. + + + + Identifier of the storage format to use for output. + + + The partition table format. + + + + Requested buffer size (in bytes) for efficient conversion. Sizes + which are too small or too large are silently truncated to suitable + values. Tens to hundreds of Megabytes are a good choice. + + + + Data stream object for reading the target image. + + + Progress object to track the operation completion. + + + + + + Explictly close the medium I/O rather than waiting for garbage + collection and the destructor. + + This will wait for any pending reads and writes to complete and then + close down the I/O access without regard for open explorer instances or + anything like that. + + + + + + + + + + + The IToken interface represents a token passed to an API client, which + triggers cleanup actions when it is explicitly released by calling the + method (preferred, as it is accurately defined + when the release happens), or when the object reference count drops + to 0. The latter way is implicitly used when an API client crashes, + however the discovery that there was a crash can take rather long, + depending on the platform (COM needs 6 minutes). So better don't rely + on the crash behavior too much. + + + + Releases this token. Cannot be undone in any way, and makes the + token object unusable (even the method will return + an error), ready for releasing. It is a more defined way than just + letting the reference count drop to 0, because the latter (depending + on the platform) can trigger asynchronous cleanup activity. + + + + + Purely a NOOP. Useful when using proxy type API bindings (e.g. the + webservice) which manage objects on behalf of the actual client, using + an object reference expiration time based garbage collector. + + + + + + + + + + + Keyboard LED indicators. + + + + + + + + + + The IKeyboard interface represents the virtual machine's keyboard. Used + in . + + Use this interface to send keystrokes or the Ctrl-Alt-Del sequence + to the virtual machine. + + + + + Current status of the guest keyboard LEDs. + + + + + Sends a scancode to the keyboard. + + + Could not send scan code to virtual keyboard. + + + + + + + + Sends an array of scancodes to the keyboard. + + + Could not send all scan codes to virtual keyboard. + + + + + + + + + Sends the Ctrl-Alt-Del sequence to the keyboard. This + function is nothing special, it is just a convenience function + calling with the proper scancodes. + + + Could not send all scan codes to virtual keyboard. + + + + + + + Causes the virtual keyboard to release any keys which are + currently pressed. Useful when host and guest keyboard may be out + of sync. + + + Could not release some or all keys. + + + + + + + Sends a USB HID usage code and page to the keyboard. The + keyRelease flag is set when the key is being released. + + + Could not send usage code to virtual keyboard. + + + + + + + + + + + Event source for keyboard events. + + + + + + + + + + + Mouse button state. + + + + + + + + + + + + + + + Touch event contact state. + + + + The touch has finished. + + + Whether the touch is really touching the device. + + + + Whether the touch is close enough to the device to be detected. + + + + + + + + The guest mouse pointer description. + + + + + Flag whether the pointer is visible. + + + + + Flag whether the pointer has an alpha channel. + + + + + The pointer hot spot X coordinate. + + + + + The pointer hot spot Y coordinate. + + + + + Width of the pointer shape in pixels. + + + + + Height of the pointer shape in pixels. + + + + + Shape bitmaps. + + The @a shape buffer contains a 1bpp (bits per pixel) AND mask + followed by a 32bpp XOR (color) mask. + + For pointers without alpha channel the XOR mask pixels are + 32 bit values: (lsb)BGR0(msb). For pointers with alpha channel + the XOR mask consists of (lsb)BGRA(msb) 32 bit values. + + An AND mask is provided for pointers with alpha channel, so if the + client does not support alpha, the pointer could be + displayed as a normal color pointer. + + The AND mask is a 1bpp bitmap with byte aligned scanlines. The + size of the AND mask therefore is cbAnd = (width + 7) / 8 * + height. The padding bits at the end of each scanline are + undefined. + + The XOR mask follows the AND mask on the next 4-byte aligned + offset: uint8_t *pu8Xor = pu8And + (cbAnd + 3) & ~3. + Bytes in the gap between the AND and the XOR mask are undefined. + The XOR mask scanlines have no gap between them and the size of + the XOR mask is: cbXor = width * 4 * height. + + + If @a shape size is 0, then the shape is not known or did not change. + This can happen if only the pointer visibility is changed. + + + + + + + + The IMouse interface represents the virtual machine's mouse. Used in + . + + Through this interface, the virtual machine's virtual mouse can be + controlled. + + + + + Whether the guest OS supports absolute mouse pointer positioning + or not. + + You can use the + event to be instantly informed about changes of this attribute + during virtual machine execution. + + + + + + + + Whether the guest OS supports relative mouse pointer positioning + or not. + + You can use the + event to be instantly informed about changes of this attribute + during virtual machine execution. + + + + + + + + Whether the guest OS has enabled the multi-touch reporting device, + touchscreen variant. + + You can use the + event to be instantly informed about changes of this attribute + during virtual machine execution. + + + + + + + + Whether the guest OS has enabled the multi-touch reporting device, + touchpad variant. + + You can use the + event to be instantly informed about changes of this attribute + during virtual machine execution. + + + + + + + + Whether the guest OS can currently switch to drawing it's own mouse + cursor on demand. + + You can use the + event to be instantly informed about changes of this attribute + during virtual machine execution. + + + + + + + + The current mouse pointer used by the guest. + + + + + + Initiates a mouse event using relative pointer movements + along x and y axis. + + + Console not powered up. + + + Could not send mouse event to virtual mouse. + + + + + + + Amount of pixels the mouse should move to the right. + Negative values move the mouse to the left. + + + + + Amount of pixels the mouse should move downwards. + Negative values move the mouse upwards. + + + + + Amount of mouse wheel moves. + Positive values describe clockwise wheel rotations, + negative values describe counterclockwise rotations. + + + + + Amount of horizontal mouse wheel moves. + Positive values describe a movement to the left, + negative values describe a movement to the right. + + + + + The current state of mouse buttons. Every bit represents + a mouse button as follows: +
+
Bit 0 (0x01)
left mouse button
+
Bit 1 (0x02)
right mouse button
+
Bit 2 (0x04)
middle mouse button
+
+ A value of @c 1 means the corresponding button is pressed. + otherwise it is released. + + + + + + + Positions the mouse pointer using absolute x and y coordinates. + These coordinates are expressed in pixels and + start from [1,1] which corresponds to the top left + corner of the virtual display. The values [-1,-1] and + [0x7fffffff,0x7fffffff] have special meanings as + respectively "no data" (to signal that the host wishes to report + absolute pointer data in future) and "out of range" (the host + pointer is outside of all guest windows). + + + Console not powered up. + + + Could not send mouse event to virtual mouse. + + + + This method will have effect only if absolute mouse + positioning is supported by the guest OS. + + + + + + + + X coordinate of the pointer in pixels, starting from @c 1. + + + + + Y coordinate of the pointer in pixels, starting from @c 1. + + + + + Amount of mouse wheel moves. + Positive values describe clockwise wheel rotations, + negative values describe counterclockwise rotations. + + + + + Amount of horizontal mouse wheel moves. + Positive values describe a movement to the left, + negative values describe a movement to the right. + + + + + The current state of mouse buttons. Every bit represents + a mouse button as follows: +
+
Bit 0 (0x01)
left mouse button
+
Bit 1 (0x02)
right mouse button
+
Bit 2 (0x04)
middle mouse button
+
+ A value of @c 1 means the corresponding button is pressed. + otherwise it is released. + + + + + + + Sends a multi-touch pointer event. For touchscreen events the + coordinates are expressed in pixels and start from [1,1] which + corresponds to the top left corner of the virtual display, for + touchpad events the coordinates are normalized to the range 0..0xffff. + + + Console not powered up. + + + Could not send event to virtual device. + + + + The guest may not understand or may choose to ignore this event. + + + and + + + + + Number of contacts in the event. + + + + + + Each array element contains packed information about one contact. + Bits 0..15: X coordinate in pixels or normalized X position. + Bits 16..31: Y coordinate in pixels or normalized Y position. + Bits 32..39: contact identifier. + Bit 40: "in contact" flag, which indicates that there is a contact with the touch surface. + Bit 41: "in range" flag, the contact is close enough to the touch surface. + All other bits are reserved for future use and must be set to 0. + + + + + + Distinguishes between touchscreen and touchpad events. + + + + + + Timestamp of the event in milliseconds. Only relative time between events is important. + + + + + + + + + + + + + + + + + + Contains information about all contacts: + "id1,x1,y1,inContact1,inRange1;...;idN,xN,yN,inContactN,inRangeN". + For example for two contacts: "0,10,20,1,1;1,30,40,1,1" + + + + + + Distinguishes between touchscreen and touchpad events. + + + + + + + + + + + + + Event source for mouse events. + + + + + + + + + + + Information about the screen bitmap. + + + + + + + + + + + + + Framebuffer capability flags. + + + + + Requires NotifyUpdateImage. NotifyUpdate must not be called. + + + + + + Supports VHWA interface. If set, then + IFramebuffer::processVHWACommand can be called. + + + + + + Supports visible region. If set, then + IFramebuffer::setVisibleRegion can be called. + + + + + + This framebuffer implementation can render a pointer cursor itself. Unless the + MoveCursor capability is also set the cursor will always be rendered at the + location of (and usually using) the host pointer. + + + + + + Supports rendering a pointer cursor anywhere within the guest screen. Implies + RenderCursor. + + + + + + + Frame buffer width, in pixels. + + + + Frame buffer height, in pixels. + + + + + Color depth, in bits per pixel. + + + + + + Scan line size, in bytes. + + + + + + Frame buffer pixel format. It's one of the values defined by . + + This attribute must never (and will never) return -- the format of the frame + buffer must be always known. + + + + + + + Hint from the frame buffer about how much of the standard + screen height it wants to use for itself. This information is + exposed to the guest through the VESA BIOS and VMMDev interface + so that it can use it for determining its video mode table. It + is not guaranteed that the guest respects the value. + + + + + + An alpha-blended overlay which is superposed over the frame buffer. + The initial purpose is to allow the display of icons providing + information about the VM state, including disk activity, in front + ends which do not have other means of doing that. The overlay is + designed to controlled exclusively by IDisplay. It has no locking + of its own, and any changes made to it are not guaranteed to be + visible until the affected portion of IFramebuffer is updated. The + overlay can be created lazily the first time it is requested. This + attribute can also return @c null to signal that the overlay is not + implemented. + + + + + + Platform-dependent identifier of the window where context of this + frame buffer is drawn, or zero if there's no such window. + + + + + + Capabilities of the framebuffer instance. + + For the meaning of individual capability flags see + . + + + + + + Informs about an update. + Gets called by the display object where this buffer is + registered. + + + X position of update. + + + Y position of update. + + + Width of update. + + + Height of update. + + + + + + Informs about an update and provides 32bpp bitmap. + + + X position of update. + + + Y position of update. + + + Width of update. + + + Height of update. + + + Array with 32BPP image data. + + + + + + Requests a size change. + + + + Logical guest screen number. + + + + Location of the screen in the guest. + + + Location of the screen in the guest. + + + Width of the guest display, in pixels. + + + Height of the guest display, in pixels. + + + + + + Returns whether the frame buffer implementation is willing to + support a given video mode. In case it is not able to render + the video mode (or for some reason not willing), it should + return @c false. Usually this method is called when the guest + asks the VMM device whether a given video mode is supported + so the information returned is directly exposed to the guest. + It is important that this method returns very quickly. + + + + + + + + + + Returns the visible region of this frame buffer. + + If the @a rectangles parameter is @c null then the value of the + @a count parameter is ignored and the number of elements necessary to + describe the current visible region is returned in @a countCopied. + + If @a rectangles is not @c null but @a count is less + than the required number of elements to store region data, the method + will report a failure. If @a count is equal or greater than the + required number of elements, then the actual number of elements copied + to the provided array will be returned in @a countCopied. + + + The address of the provided array must be in the process space of + this IFramebuffer object. + + + Method not yet implemented. + + + + Pointer to the @c RTRECT array to receive region data. + + + Number of @c RTRECT elements in the @a rectangles array. + + + Number of elements copied to the @a rectangles array. + + + + + + Suggests a new visible region to this frame buffer. This region + represents the area of the VM display which is a union of regions of + all top-level windows of the guest operating system running inside the + VM (if the Guest Additions for this system support this + functionality). This information may be used by the frontends to + implement the seamless desktop integration feature. + + + The address of the provided array must be in the process space of + this IFramebuffer object. + + + The IFramebuffer implementation must make a copy of the provided + array of rectangles. + + + Method not yet implemented. + + + + Pointer to the @c RTRECT array. + + + Number of @c RTRECT elements in the @a rectangles array. + + + + + + Posts a Video HW Acceleration Command to the frame buffer for processing. + The commands used for 2D video acceleration (DDraw surface creation/destroying, blitting, scaling, color conversion, overlaying, etc.) + are posted from quest to the host to be processed by the host hardware. + + + The address of the provided command must be in the process space of + this IFramebuffer object. + + + + + Pointer to VBOXVHWACMD containing the command to execute. + + + The validated VBOXVHWACMD::enmCmd value from the command. + + + Set when the command origins from the guest, clear if host. + + + + + + Notifies framebuffer about 3D backend event. + + + + event type. VBOX3D_NOTIFY_TYPE_* in VBoxVideo3D.h + + + event-specific data, depends on the supplied event type + + + + + + + + The IFramebufferOverlay interface represents an alpha blended overlay + for displaying status icons above an IFramebuffer. It is always created + not visible, so that it must be explicitly shown. It only covers a + portion of the IFramebuffer, determined by its width, height and + co-ordinates. It is always in packed pixel little-endian 32bit ARGB (in + that order) format, and may be written to directly. Do re-read the + width though, after setting it, as it may be adjusted (increased) to + make it more suitable for the front end. + + + X position of the overlay, relative to the frame buffer. + + + + Y position of the overlay, relative to the frame buffer. + + + + + Whether the overlay is currently visible. + + + + + + The global alpha value for the overlay. This may or may not be + supported by a given front end. + + + + + + Changes the overlay's position relative to the IFramebuffer. + + + + + + + + + + The current status of the guest display. + + + + + The guest monitor is disabled in the guest. + + + + + + The guest monitor is enabled in the guest. + + + + + + The guest monitor is enabled in the guest but should display nothing. + + + + + + + How method should work. + + + + + If the guest is already at desired mode then the API might avoid setting the mode. + + + + + + Always set the new mode even if the guest is already at desired mode. + + + + + + Attach new screens and always set the new mode for existing screens. + + + + + + Do not notify the guest of the change. Normally this is wished, but it + might not be when re-setting monitor information from the last session + (no hotplug happened, as it is still the same virtual monitor). + + + + + + + + + + + + + + + + + + + + The IDisplay interface represents the virtual machine's display. + + The object implementing this interface is contained in each + attribute and represents the visual + output of the virtual machine. + + The virtual display supports pluggable output targets represented by the + IFramebuffer interface. Examples of the output target are a window on + the host computer or an RDP session's display on a remote computer. + + + + + Layout of the guest screens. + + + + + + Queries certain attributes such as display width, height, color depth + and the X and Y origin for a given guest screen. + + The parameters @a xOrigin and @a yOrigin return the X and Y + coordinates of the framebuffer's origin. + + All return parameters are optional. + + + + + + + + + + + + Sets the graphics update target for a screen. + + + + + + + + + Removes the graphics updates target for a screen. + + + + + + + + Queries the graphics updates targets for a screen. + + + + + + + + Changes the monitor information reported by a given output of the guest + graphics device. This information can be read by the guest if suitable + drivers and driver tools are available, including but not limited to + those in the Guest Additions. The guest will receive monitor hotplug + notification when the monitor information is changed, and the + information itself will be available to the guest until the next change. + The information should not be resent if the guest does not resize in + response. The guest might have chosen to ignore the change, or the + resize might happen later when a suitable driver is started. + + Specifying @c 0 for either @a width, @a height or @a bitsPerPixel + parameters means that the corresponding values should be taken from the + current video mode (i.e. left unchanged). + + @todo Rename this to @a setMonitorInfo for 7.0. + + + The @a display value is higher then the number of outputs. + + + + + + The number of the guest output to change. + + + + + @c True if a monitor is connected, + @c False otherwise. + For historical reasons the Windows drivers can + and do override this setting. Call this a virtual hardware quirk. + + + + + + @c True, if the position of the guest screen is specified, + @c False otherwise. + + + + + The X origin of the guest screen. + + + + + The Y origin of the guest screen. + + + + + The width of the guest screen. + + + + + The height of the guest screen. + + + + + The number of bits per pixel of the guest screen. + + + + + Whether the guest should be notified of the change. Normally this + is wished, but it might not be when re-setting monitor information + from the last session (no hotplug happened, as it is still the same + virtual monitor). Might also be useful if several monitors are to be + changed at once, but this would not reflect physical hardware well, + and we also have @a setScreenLayout for that. + + + + + + + Queries the monitor information for a given guest output. See + @a setVideoModeHint. If no monitor information has been set yet by a + front-end the preferred mode values returned will be zero. + + @todo Rename this to @a getMonitorInfo for 7.0. + + + The @a display value is higher than the number of outputs. + + + + + + The number of the guest output to query. + + + + + @c True if a monitor is connected, + @c False otherwise. + For historical reasons the Windows drivers can + and do override the setting requested by the host. + + + + + @c True, if the position of the guest screen was specified, + @c False otherwise. + + + + + The X origin of the guest screen. + + + + + The Y origin of the guest screen. + + + + + The width of the monitor preferred mode. + + + + + The height of the monitor preferred mode. + + + + + The number of bits per pixel of the monitor preferred mode. + + + + + + + Enables or disables seamless guest display rendering (seamless desktop + integration) mode. + + Calling this method has no effect if with facility @c Seamless + does not return @c Active. + + + + + + + + Takes a screen shot of the requested size and format and copies it to the + buffer allocated by the caller and pointed to by @a address. + The buffer size must be enough for a 32 bits per pixel bitmap, + i.e. width * height * 4 bytes. + + This API can be used only locally by a VM process through the + COM/XPCOM C++ API as it requires pointer support. It is not + available for scripting languages, Java or any webservice clients. + Unless you are writing a new VM frontend use + . + + + + + + + + + + + + Takes a guest screen shot of the requested size and format + and returns it as an array of bytes. + + + + The guest monitor to take screenshot from. + + + + + Desired image width. + + + + + Desired image height. + + + + + The requested format. + + + + + Array with resulting screen data. + + + + + + + Draws a 32-bpp image of the specified size from the given buffer + to the given point on the VM display. + + + Feature not implemented. + + + Could not draw to screen. + + + + + + Monitor to take the screenshot from. + + + + + Address to store the screenshot to + + + + + Relative to the screen top left corner. + + + + + Relative to the screen top left corner. + + + + + Desired image width. + + + + + Desired image height. + + + + + + + Does a full invalidation of the VM display and instructs the VM + to update it. + + + Could not invalidate and update screen. + + + + + + + + Redraw the specified VM screen. + + + + The guest screen to redraw. + + + + + + + Signals that the Video HW Acceleration command has completed. + + + + Pointer to VBOXVHWACMD containing the completed command. + + + + + + Signals that framebuffer window viewport has changed. + + + The specified viewport data is invalid. + + + + + + + Monitor to take the screenshot from. + + + + + Framebuffer x offset. + + + + + Framebuffer y offset. + + + + + Viewport width. + + + + + Viewport height. + + + + + + + Obtains the guest screen bitmap parameters. + + + + + + + + Notify OpenGL HGCM host service about graphics content scaling factor change. + + + + + + + + + Notify OpenGL HGCM host service about HiDPI monitor scaling policy change. + + + + + + + Set video modes for the guest screens. + + + + + + + + Unplugs monitors from the virtual graphics card. + + + + + + + Make a IGuestScreenInfo object with the provided parameters. + + + + The number of the guest display. + + + + + @c True, if this guest screen is enabled, + @c False otherwise. + + + + + Whether this guest monitor must be primary. + + + + + @c True, if the origin of the guest screen should be changed, + @c False otherwise. + + + + + The X origin of the guest screen. + + + + + The Y origin of the guest screen. + + + + + The width of the guest screen. + + + + + The height of the guest screen. + + + + + The number of bits per pixel of the guest screen. + + + + + The created object. + + + + + + + + + + + Network attachment type. + + + + Null value, also means "not attached". + + + + + + + + + + + + + + Network adapter type. + + + + Null value (never used by the API). + + + AMD PCNet-PCI II network card (Am79C970A). + + + AMD PCNet-FAST III network card (Am79C973). + + + Intel PRO/1000 MT Desktop network card (82540EM). + + + Intel PRO/1000 T Server network card (82543GC). + + + Intel PRO/1000 MT Server network card (82545EM). + + + Virtio network device. + + + AMD PCnet-ISA/NE2100 network card (Am79C960). + + + Novell NE2000 network card (NE2000). + + + Novell NE1000 network card (NE1000). + + + WD/SMC EtherCard Plus 16 network card (WD8013EBT). + + + WD/SMC EtherCard Plus network card (WD8003E). + + + 3Com EtherLink II network card (3C503). + + + 3Com EtherLink network card (3C501/3C500). + + + + + + The promiscuous mode policy of an interface. + + + + Deny promiscuous mode requests. + + + + Allow promiscuous mode, but restrict the scope it to the internal + network so that it only applies to other VMs. + + + + + Allow promiscuous mode, include unrelated traffic going over the wire + and internally on the host. + + + + + + + Represents a virtual network adapter that is attached to a virtual machine. + Each virtual machine has a fixed number of network adapter slots with one + instance of this attached to each of them. Call + to get the network adapter that + is attached to a given slot in a given machine. + + Each network adapter can be in one of five attachment modes, which are + represented by the enumeration; + see the attribute. + + + + + Type of the virtual network adapter. Depending on this value, + VirtualBox will provide a different virtual network hardware + to the guest. + + + + + + Slot number this adapter is plugged into. Corresponds to + the value you pass to + to obtain this instance. + + + + + + Flag whether the network adapter is present in the + guest system. If disabled, the virtual guest hardware will + not contain this network adapter. Can only be changed when + the VM is not running. + + + + + + Ethernet MAC address of the adapter, 12 hexadecimal characters. When + setting it to @c null or an empty string for an enabled adapter, + VirtualBox will generate a unique MAC address. Disabled adapters can + have an empty MAC address. + + + + + + Sets/Gets network attachment type of this network adapter. + + + + + + Name of the network interface the VM should be bridged to. + + + + + + Name of the host only network interface the VM is attached to. + + + + + + Name of the host only network the VM is attached to. + + + + + + Name of the internal network the VM is attached to. + + + + + + Name of the NAT network the VM is attached to. + + + + + + Name of the driver to use for the "Generic" network attachment type. + + + + + + Name of the cloud network the VM is attached to. + + + + + + Flag whether the adapter reports the cable as connected or not. + It can be used to report offline situations to a VM. + + + + + + Line speed reported by custom drivers, in units of 1 kbps. + + + + + + The promiscuous mode policy of the network adapter when attached to an + internal network, host only network or a bridge. + + + + + + Flag whether network traffic from/to the network card should be traced. + Can only be toggled when the VM is turned off. + + + + + + Filename where a network trace will be stored. If not set, VBox-pid.pcap + will be used. + + + + + + Points to the NAT engine which handles the network address translation + for this interface. This is active only when the interface actually uses + NAT. + + + + + + Network boot priority of the adapter. Priority 1 is highest. If not set, + the priority is considered to be at the lowest possible setting. + + + + + The bandwidth group this network adapter is assigned to. + + + + + + + Returns the value of the network attachment property with the given name. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + @a name is @c null or empty. + + + Name of the property to get. + + + Current property value. + + + + + + Sets the value of the network attachment property with the given name. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + + @a name is @c null or empty. + + + Name of the property to set. + + + Property value to set. + + + + + + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + Currently the value of this argument is ignored and the method + always returns all existing properties. + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + + + + Names of properties to get. + + + + Names of returned properties. + + + Values of returned properties. + + + + + + + + + + + The PortMode enumeration represents possible communication modes for + the virtual serial port device. + + + + Virtual device is not attached to any real host device. + + + Virtual device is attached to a host pipe. + + + Virtual device is attached to a host device. + + + Virtual device is attached to a raw file. + + + Virtual device is attached to a TCP socket. + + + + + + The UART type represents the emulated UART chip for the serial port device. + + + + The most basic emulated UART which doesn't support FIFO operation. + + + + The successor of the 16450 UART introducing a 16 byte FIFO to reduce + operational overhead. + + + + + This UART developed by Texas Instruments introduced a 64 byte FIFO + and hardware flow control. + + + + + + + + The ISerialPort interface represents the virtual serial port device. + + The virtual serial port device acts like an ordinary serial port + inside the virtual machine. This device communicates to the real + serial port hardware in one of two modes: host pipe or host device. + + In host pipe mode, the #path attribute specifies the path to the pipe on + the host computer that represents a serial port. The #server attribute + determines if this pipe is created by the virtual machine process at + machine startup or it must already exist before starting machine + execution. + + In host device mode, the #path attribute specifies the name of the + serial port device on the host computer. + + There is also a third communication mode: the disconnected mode. In this + mode, the guest OS running inside the virtual machine will be able to + detect the serial port, but all port write operations will be discarded + and all port read operations will return no data. + + + + + + + Slot number this serial port is plugged into. Corresponds to + the value you pass to + to obtain this instance. + + + + + + Flag whether the serial port is enabled. If disabled, + the serial port will not be reported to the guest OS. + + + + + Base I/O address of the serial port. + + + + IRQ number of the serial port. + + + + + How is this port connected to the host. + + Changing this attribute may fail if the conditions for + are not met. + + + + + + + Flag whether this serial port acts as a server (creates a new pipe on + the host) or as a client (uses the existing pipe). This attribute is + used only when is PortMode_HostPipe or PortMode_TCP. + + + + + + Path to the serial port's pipe on the host when is + PortMode_HostPipe, the host serial device name when + is PortMode_HostDevice or the TCP + port (server) or hostname:port (client) when + is PortMode_TCP. + For those cases, setting a @c null or empty string as the attribute's + value is an error. Otherwise, the value of this property is ignored. + + + + + Selects the emulated UART implementation. + + + + + + + + + + The IParallelPort interface represents the virtual parallel port device. + + The virtual parallel port device acts like an ordinary parallel port + inside the virtual machine. This device communicates to the real + parallel port hardware using the name of the parallel device on the host + computer specified in the #path attribute. + + Each virtual parallel port device is assigned a base I/O address and an + IRQ number that will be reported to the guest operating system and used + to operate the given parallel port from within the virtual machine. + + + + + + + Slot number this parallel port is plugged into. Corresponds to + the value you pass to + to obtain this instance. + + + + + + Flag whether the parallel port is enabled. If disabled, + the parallel port will not be reported to the guest OS. + + + + + Base I/O address of the parallel port. + + + + IRQ number of the parallel port. + + + + + Host parallel device name. If this parallel port is enabled, setting a + @c null or an empty string as this attribute's value will result in + the parallel port behaving as if not connected to any device. + + + + + + + + + + + The main execution engine of a VM. + + + Has not yet been set (try again later). + + + Emulated thru IEM. + + + Hardware assisted virtualization thru HM. + + + Hardware assisted virtualization thru native API (NEM). + + + + + + + Takes a core dump of the guest. + + See include/VBox/dbgfcorefmt.h for details on the file format. + + + + The name of the output file. The file must not exist. + + + + + Reserved for future compression method indicator. + + + + + + + Takes a core dump of the VM process on the host. + + This feature is not implemented in the 4.0.0 release but it may show up + in a dot release. + + + + The name of the output file. The file must not exist. + + + + + Reserved for future compression method indicator. + + + + + + + Interfaces with the info dumpers (DBGFInfo). + + This feature is not implemented in the 4.0.0 release but it may show up + in a dot release. + + + + The name of the info item. + + + + + Arguments to the info dumper. + + + + + The into string. + + + + + + + Inject an NMI into a running VT-x/AMD-V VM. + + + + + + Modifies the group settings of the debug or release logger. + + + + The group settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + + + + + + + Modifies the debug or release logger flags. + + + + The flags settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + + + + + + + Modifies the debug or release logger destinations. + + + + The destination settings string. See iprt/log.h for details. To target the + release logger, prefix the string with "release:". + + + + + + + Reads guest physical memory, no side effects (MMIO++). + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The guest physical address. + + + The number of bytes to read. + + + The bytes read. + + + + + + Writes guest physical memory, access handles (MMIO++) are ignored. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The guest physical address. + + + The number of bytes to read. + + + The bytes to write. + + + + + + Reads guest virtual memory, no side effects (MMIO++). + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The identifier of the Virtual CPU. + + + The guest virtual address. + + + The number of bytes to read. + + + The bytes read. + + + + + + Writes guest virtual memory, access handles (MMIO++) are ignored. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The identifier of the Virtual CPU. + + + The guest virtual address. + + + The number of bytes to read. + + + The bytes to write. + + + + + Loads a DBGF plug-in. + + The plug-in name or DLL. Special name 'all' loads all installed plug-ins. + + + The name of the loaded plug-in. + + + + + Unloads a DBGF plug-in. + + The plug-in name or DLL. Special name 'all' unloads all plug-ins. + + + + + + Tries to (re-)detect the guest OS kernel. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + + The detected OS kernel on success. + + + + + + + Tries to get the kernel log (dmesg) of the guest OS. + + + + Max number of messages to return, counting from the end of the + log. If 0, there is no limit. + + + + The kernel log. + + + + + + + Gets one register. + + + The identifier of the Virtual CPU. + + + The register name, case is ignored. + + + + The register value. This is usually a hex value (always 0x prefixed) + but other format may be used for floating point registers (TBD). + + + + + + + Gets all the registers for the given CPU. + + + The identifier of the Virtual CPU. + + + Array containing the lowercase register names. + + + + Array parallel to the names holding the register values as if the + register was returned by . + + + + + + + Gets one register. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The identifier of the Virtual CPU. + + + The register name, case is ignored. + + + + The new register value. Hexadecimal, decimal and octal formattings + are supported in addition to any special formattings returned by + the getters. + + + + + + + Sets zero or more registers atomically. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The identifier of the Virtual CPU. + + + Array containing the register names, case ignored. + + + + Array paralell to the names holding the register values. See + for formatting + guidelines. + + + + + + + Produce a simple stack dump using the current guest state. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + The identifier of the Virtual CPU. + + + String containing the formatted stack dump. + + + + + + Reset VM statistics. + + + The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them. + + + + + + Dumps VM statistics. + + + The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them. + + + + + + Get the VM statistics in a XMLish format. + + + The selection pattern. A bit similar to filename globbing. + Wildchars are '*' and '?', where the asterisk matches zero or + more characters and question mark matches exactly one character. + Multiple pattern can be joined by putting '|' between them. + + + Whether to include the descriptions. + + + The XML document containing the statistics. + + + + + + Get the load percentages (as observed by the VMM) for all virtual CPUs + or a specific one. + + + The ID of the virtual CPU to retrieve stats for, pass 0x7fffffff + or higher for the average accross all CPUs. + + + Percentage of the interval that the CPU(s) spend executing guest code. + + + Percentage of the interval that the CPU(s) spend halted. + + + Percentage of the interval that the CPU(s) preempted by the host + scheduler, on virtualization overhead and on other tasks. + + + The interval the percentage was calculated over in milliseconds + + + + + + Creates a sample report of the guest and emulated device activity. + + + The file to dump the report to. + + + The sample interval. + + + The number of microseconds to sample. + + + The progress object on return. + + + + + + Gets the user-mode VM handle, with a reference, and the VMM function table. + The VM handle must be passed to VMR3ReleaseUVM when done. This can only + be called from within the VM process, remote calls will always fail. + + + The VMMR3VTABLE_MAGIC_VERSION value of the caller. The method + will fail if this is not compatible with the VMM function table. + + + The VMM function table address. + + + The user-mode VM handle. + + + + + Switch for enabling single-stepping. + + + + + Whether to execute all the code in the instruction interpreter. This + is mainly for testing the interpreter and not an execution mode + intended for general consumption. + + + + + Switch for enabling and disabling the debug logger. + + + + The debug logger flags. + + + + The debug logger's group settings. + + + + The debug logger's destination settings. + + + + The release logger flags. + + + + The release logger's group settings. + + + + The relase logger's destination settings. + + + + Gets the main execution engine of the VM. + + + + + Flag indicating whether the VM is currently making use of the nested paging + CPU hardware virtualization extension. + + + + + + Flag indicating whether the VM is currently making use of the VPID + VT-x extension. + + + + + + Flag indicating whether the VM is currently making use of the + unrestricted execution feature of VT-x. + + + + + + Query the guest OS kernel name as detected by the DBGF. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + + + + Query the guest OS kernel version string as detected by the DBGF. + + This feature is not implemented in the 4.0.0 release but may show up + in a dot release. + + + + + + Flag indicating whether the VM is currently making use of the Physical + Address Extension CPU feature. + + + + + + The rate at which the virtual time runs expressed as a percentage. + The accepted range is 2% to 20000%. + + + + + VM uptime in milliseconds, i.e. time in which it could have been + executing guest code. Excludes the time when the VM was paused. + + + + + + + + + + + List of USB device filters associated with the machine. + + If the machine is currently running, these filters are activated + every time a new (supported) USB device is attached to the host + computer that was not ignored by global filters + (). + + These filters are also activated when the machine is powered up. + They are run against a list of all currently available USB + devices (in states + , + , + ) that were not previously + ignored by global filters. + + If at least one filter matches the USB device in question, this + device is automatically captured (attached to) the virtual USB + controller of this machine. + + , + + + + + + Creates a new USB device filter. All attributes except + the filter name are set to empty (any match), + active is @c false (the filter is not active). + + The created filter can then be added to the list of filters using + . + + + The virtual machine is not mutable. + + + + + + + Filter name. See + for more info. + + + + Created filter object. + + + + + + Inserts the given USB device to the specified position + in the list of filters. + + Positions are numbered starting from 0. If the specified + position is equal to or greater than the number of elements in + the list, the filter is added to the end of the collection. + + + Duplicates are not allowed, so an attempt to insert a + filter that is already in the collection, will return an + error. + + + + Virtual machine is not mutable. + + + USB device filter not created within this VirtualBox instance. + + + USB device filter already in list. + + + + + + Position to insert the filter to. + + + USB device filter to insert. + + + + + + Removes a USB device filter from the specified position in the + list of filters. + + Positions are numbered starting from 0. Specifying a + position equal to or greater than the number of elements in + the list will produce an error. + + + + + Virtual machine is not mutable. + + + USB device filter list empty or invalid @a position. + + + + + Position to remove the filter from. + + + Removed USB device filter. + + + + + + + + + + The USB controller type. . + + + @c null value. Never used by the API. + + + + + + Last element (invalid). Used for parameter checks. + + + + + + + + The USB Controller name. + + + + + + The USB Controller type. + + + + + + USB standard version which the controller implements. + This is a BCD which means that the major version is in the + high byte and minor version is in the low byte. + + + + + + + + + + + USB device/port speed state. This enumeration represents speeds at + which a USB device can communicate with the host. + + The speed is a function of both the device itself and the port which + it is attached to, including hubs and cables in the path. + + + Due to differences in USB stack implementations on various hosts, + the reported speed may not exactly match the actual speed. + + + + + + + + @c null value. Never returned by the API. + + + + + Low speed, 1.5 Mbps. + + + + + Full speed, 12 Mbps. + + + + + High speed, 480 Mbps. + + + + + SuperSpeed, 5 Gbps. + + + + + SuperSpeedPlus, 10 Gbps. + + + + + + + The IUSBDevice interface represents a virtual USB device attached to the + virtual machine. + + A collection of objects implementing this interface is stored in the + attribute which lists all USB devices + attached to a running virtual machine's USB controller. + + + + + Unique USB device ID. This ID is built from #vendorId, + #productId, #revision and #serialNumber. + + + + + Vendor ID. + + + + Product ID. + + + + + Product revision number. This is a packed BCD represented as + unsigned short. The high byte is the integer part and the low + byte is the decimal. + + + + + Manufacturer string. + + + + Product string. + + + + Serial number string. + + + + + Host-specific address of the device, uniquely + identifying a physically connected device in the system. + Note that the address of a USB device may change across + device re-plugs and host suspend/resume cycles or reboots. + + + + + + Host USB port number on the hub the device is physically + connected to. + + + + + + Host-specific identifier of the port (including hub) the USB + device is physically connected to. Note that hubs may be + dynamically added and removed, and that hub enumeration may not + be consistent across host reboots. + + + + + + The major USB version of the device - 1, 2 or 3. + + + + + + The speed at which the device is currently communicating. + + + + + + Whether the device is physically connected to a remote VRDE + client or to a local host machine. + + + + + + Array of device attributes as single strings. + + So far the following are used: + 0: The manufacturer string, if the device doesn't expose the ID one is taken + from an internal database or an empty string if none is found. + 1: The product string, if the device doesn't expose the ID one is taken + from an internal database or an empty string if none is found. + + + + + + The backend which will be used to communicate with this device. + + + + + + + + + + + The IUSBDeviceFilter interface represents a USB device filter used + to perform actions on one or more USB devices. + + USB device filters are used by running virtual machines to + automatically capture selected USB devices once they are physically + attached to the host computer. + + A USB device is matched to a specific device filter if and only if all + attributes of the device filter match the corresponding attributes of the + device (that is, attributes are joined together using a logical AND + operation). On the other hand filter attributes in separate USB + device filters are applied as a logical OR operation. So if one + would like to create a match such as "this vendor id OR this product id", + then one would need to create two filters and specify "any match" (see below) + for the other unused attributes. + + All filter attributes used for matching are strings. The following + filtering expressions are currently supported: + +
    +
  • Interval filters. Used to specify valid intervals for + integer device attributes (Vendor ID, Product ID, Revision and Port). + The format of the string is: + + int:((m)|([m]-[n]))(,(m)|([m]-[n]))* + + where m and n are integer numbers, either in octal + (starting with 0), hexadecimal (starting with 0x) + or decimal (otherwise), so that m < n. If m + is omitted before a dash (-), the minimum possible integer + is assumed; if n is omitted after a dash, the maximum + possible integer is assumed. +
    • +
  • Boolean filters. Used to specify acceptable values for + boolean device attributes. The format of the string is: + + true|false|yes|no|0|1 + +
    • +
  • Exact match. Used to specify a single value for the given + device attribute. Any string that doesn't start with int: + represents an exact match. String device attributes are compared to + this string in a case-sensitive manner. Integer attributes are first + converted to a string (see individual filter attributes) and then + compared in a case-insensitive manner. + +
    • +
  • Any match. Any value of the corresponding device attribute + will match the given filter. An empty or @c null string is + used to construct this type of filtering expressions. + +
    • +
+ + + On Windows hosts, interval filters are not currently available. + Also all string filter attributes + (, , + ) are ignored, so they behave as + any match no matter what string expression is specified. + + + , + + + + + + Visible name for this filter. + This name is used to visually distinguish one filter from another, + so it can neither be @c null nor an empty string. + + + + + Whether this filter active or has been temporarily disabled. + + + + + Vendor ID filter. + The string representation for the exact matching + has the form XXXX, where X is the hex digit + (including leading zeroes). + + + + + + Product ID filter. + The string representation for the exact matching + has the form XXXX, where X is the hex digit + (including leading zeroes). + + + + + + Product revision number + filter. The string representation for the exact matching + has the form IIFF, where I is the decimal digit + of the integer part of the revision, and F is the + decimal digit of its fractional part (including leading and + trailing zeros). + Note that for interval filters, it's best to use the hexadecimal + form, because the revision is stored as a 16 bit packed BCD value; + so the expression int:0x0100-0x0199 will match any + revision from 1.0 to 1.99. + + + + + + Manufacturer filter. + + + + + + Product filter. + + + + + + Serial number filter. + + + + + + Host USB port filter. + + + + + + Remote state filter. + + This filter makes sense only for machine USB filters, + i.e. it is ignored by IHostUSBDeviceFilter objects. + + + + + + + This is an advanced option for hiding one or more USB interfaces + from the guest. The value is a bit mask where the bits that are set + means the corresponding USB interface should be hidden, masked off + if you like. + This feature only works on Linux hosts. + + + + + + + + + + + USB device state. This enumeration represents all possible states + of the USB device physically attached to the host computer regarding + its state on the host computer and availability to guest computers + (all currently running virtual machines). + + Once a supported USB device is attached to the host, global USB + filters () are activated. They can + either ignore the device, or put it to USBDeviceState_Held state, or do + nothing. Unless the device is ignored by global filters, filters of all + currently running guests () are + activated that can put it to USBDeviceState_Captured state. + + If the device was ignored by global filters, or didn't match + any filters at all (including guest ones), it is handled by the host + in a normal way. In this case, the device state is determined by + the host and can be one of USBDeviceState_Unavailable, USBDeviceState_Busy + or USBDeviceState_Available, depending on the current device usage. + + Besides auto-capturing based on filters, the device can be manually + captured by guests () if its + state is USBDeviceState_Busy, USBDeviceState_Available or + USBDeviceState_Held. + + + Due to differences in USB stack implementations in Linux and Win32, + states USBDeviceState_Busy and USBDeviceState_Unavailable are applicable + only to the Linux version of the product. This also means that () can only succeed on Win32 if the + device state is USBDeviceState_Held. + + + , + + + + + Not supported by the VirtualBox server, not available to guests. + + + + + Being used by the host computer exclusively, + not available to guests. + + + + + Being used by the host computer, potentially available to guests. + + + + + Not used by the host computer, available to guests (the host computer + can also start using the device at any time). + + + + + Held by the VirtualBox server (ignored by the host computer), + available to guests. + + + + + Captured by one of the guest computers, not available + to anybody else. + + + + + + + The IHostUSBDevice interface represents a physical USB device attached + to the host computer. + + Besides properties inherited from IUSBDevice, this interface adds the + property that holds the current state of the USB + device. + + , + + + + + + Current state of the device. + + + + + + + + + + + + + Actions for host USB device filters. + , + + + + Null value (never used by the API). + + + Ignore the matched USB device. + + + Hold the matched USB device. + + + + + + The IHostUSBDeviceFilter interface represents a global filter for a + physical USB device used by the host computer. Used indirectly in + . + + Using filters of this type, the host computer determines the initial + state of the USB device after it is physically attached to the + host's USB controller. + + + The attribute is ignored by this type of + filters, because it makes sense only for + machine USB filters. + + + + + + + + Action performed by the host when an attached USB device + matches this filter. + + + + + + + + + + + The USBProxyBackend interface represents a source for USB devices available + to the host for attaching to the VM. + + + + + The unique name of the proxy backend. + + + + + + The type of the backend. + + + + + + + + + + Host audio driver type. + + + + Use the default audio driver automatically determined for the host + that this VirtualBox instance is running on. + Useful for VMs which need to run on different host OSes. + + + + + Null value, also means "dummy audio driver". + + + Open Sound System (Linux / Unix hosts only). + + + Advanced Linux Sound Architecture (Linux hosts only). + + + PulseAudio (Linux hosts only). + + + Windows multimedia (Windows hosts only, not supported at the moment). + + + DirectSound (Windows hosts only). + + + Windows Audio Session (Windows hosts only). + + + CoreAudio (Mac hosts only). + + + Reserved for historical reasons. + + + Reserved for historical reasons. + + + + + + Virtual audio controller type. + + + + + + + + + + The exact variant of audio codec hardware presented + to the guest; see . + + + + @c null value. Never used by the API. + + + SB16; this is the only option for the SB16 device. + + + A STAC9700 AC'97 codec. + + + An AD1980 AC'97 codec. Recommended for Linux guests. + + + A STAC9221 HDA codec. + + + + + + The IAudioAdapter interface represents the virtual audio adapter of + the virtual machine. Used in . + + + + Flag whether the audio adapter is present in the + guest system. If disabled, the virtual guest hardware will + not contain any audio adapter. Can only be changed when + the VM is not running. + + + + + Flag whether the audio adapter is enabled for audio + input. Only relevant if the adapter is enabled. + + + + + Flag whether the audio adapter is enabled for audio + output. Only relevant if the adapter is enabled. + + + + + The emulated audio controller. + + + + + The exact variant of audio codec hardware presented + to the guest. + For HDA and SB16, only one variant is available, but for AC'97, + there are several. + + + + + Audio driver the adapter is connected to. This setting + can only be changed when the VM is not running. + + + + + Array of names of tunable properties, which can be supported by audio driver. + + + + + + Sets an audio specific property string. + + If you pass @c null or empty string as a key @a value, the given @a key + will be deleted. + + + + Name of the key to set. + + + Value to assign to the key. + + + + + + Returns an audio specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + + + Name of the key to get. + + + Value of the requested key. + + + + + + + + Audio direction enumeration. + + + + Direction cannot be determined. + + + Input (Recording). + + + Output (Playback). + + + Duplex (Recording + Playback). + + + + + + Audio device type enumeration. + + + + Device type is unknown / cannot be determined + + + Built-in device (cannot be removed). + + + External device, connected via USB. + + + External device, connected via some other method. + + + + + + Audio device state enumeration. + + + + Device state is unknown / cannot be determined + + + Device is active and can be used. + + + Device is in a disabled state. + + + Device is marked as not being present. + + + Device has been unplugged. + + + + + + Represents an audio device provided by the host OS. + + + + + Unique device ID. + + + + + + Friendly name of the device. + + + + + Device type. + + + + + Usage type of the device. + + + + + Whether this device is being marked as the default input + device by the host OS. + + + + + Whether this device is being marked as the default output + device by the host OS. + + + + + Whether this device is being marked as a hotplug device, i.e. can + be removed from the system. + + + + + Current device state. + + + + + Returns an audio specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + + + Name of the key to get. + + + Value of the requested key. + + + + + + + + The IAudioSettings interface represents the audio settings for a virtual machine. + + + + + Returns the machine's current host audio device for the specified usage. + + This method is not implemented yet. + + + + Usage to retrieve audio device for. + + + Host audio device for the specified direction. + + + + + + Sets the machine's current host audio device for the specified usage. + + This method is not implemented yet. + + + + Sets the host audio device for the specified usage. + + + Usage to set audio device for. + + + + + Associated audio adapter, always present. + + + + + + + VirtualBox authentication type. + + + + Null value, also means "no authentication". + + + + + + + + + + + Flag if VRDE server is enabled. + + + + VRDE authentication method. + + + + Timeout for guest authentication. Milliseconds. + + + + + Flag whether multiple simultaneous connections to the VM are permitted. + Note that this will be replaced by a more powerful mechanism in the future. + + + + + + Flag whether the existing connection must be dropped and a new connection + must be established by the VRDE server, when a new client connects in single + connection mode. + + + + + + The name of Extension Pack providing VRDE for this VM. Overrides + . + + + + + + Library used for authentication of RDP clients by this VM. Overrides + . + + + + + + Array of names of properties, which are supported by this VRDE server. + + + + + + Sets a VRDE specific property string. + + If you pass @c null or empty string as a key @a value, the given @a key + will be deleted. + + + + Name of the key to set. + + + Value to assign to the key. + + + + + + Returns a VRDE specific property string. + + If the requested data @a key does not exist, this function will + succeed and return an empty string in the @a value argument. + + + + Name of the key to get. + + + Value of the requested key. + + + + + + + + + + + The ISharedFolder interface represents a folder in the host computer's + file system accessible from the guest OS running inside a virtual + machine using an associated logical name. + + There are three types of shared folders: +
    +
  • Global (), shared + folders available to all virtual machines.
    • +
  • Permanent (), + VM-specific shared folders available to the given virtual machine at + startup.
    • +
  • Transient (), + VM-specific shared folders created in the session context (for + example, when the virtual machine is running) and automatically + discarded when the session is closed (the VM is powered off).
    • +
+ + Logical names of shared folders must be unique within the given scope + (global, permanent or transient). However, they do not need to be unique + across scopes. In this case, the definition of the shared folder in a + more specific scope takes precedence over definitions in all other + scopes. The order of precedence is (more specific to more general): +
    +
  1. Transient definitions
    2. +
  2. Permanent definitions
    3. +
  3. Global definitions
    4. +
+ + For example, if MyMachine has a shared folder named + C_DRIVE (that points to C:\\), then creating a + transient shared folder named C_DRIVE (that points + to C:\\\\WINDOWS) will change the definition + of C_DRIVE in the guest OS so + that \\\\VBOXSVR\\C_DRIVE will give access + to C:\\WINDOWS instead of C:\\ on the host + PC. Removing the transient shared folder C_DRIVE will restore + the previous (permanent) definition of C_DRIVE that points + to C:\\ if it still exists. + + Note that permanent and transient shared folders of different machines + are in different name spaces, so they don't overlap and don't need to + have unique logical names. + + + Global shared folders are not implemented in the current version of the + product. + + + + + Logical name of the shared folder. + + + + Full path to the shared folder in the host file system. + + + + + Whether the folder defined by the host path is currently + accessible or not. + + For example, the folder can be inaccessible if it is placed + on the network share that is not available by the time + this property is read. + + + + + + Whether the folder defined by the host path is writable or + not. + + + + + + Whether the folder gets automatically mounted by the guest or not. + + + + + + Desired mount point in the guest for automatically mounting the folder + when is set. For Windows and + OS/2 guests this should be a drive letter, while other guests it should + be a absolute directory. It is possible to combine the two, e.g. + "T:/mnt/testrsrc" will be attached to "T:" by windows and OS/2 while + the unixy guests will mount it at "/mnt/testrsrc". + + When empty the guest will choose a mount point. The guest may do so + too should the specified mount point be in use or otherwise unusable. + + + + + + Text message that represents the result of the last accessibility + check. + + Accessibility checks are performed each time the + attribute is read. An empty string is returned if the last + accessibility check was successful. A non-empty string indicates a + failure and should normally describe a reason of the failure (for + example, a file read error). + + + + + + + + + + Internal event reason type. + + + + Null value, means "no known reason". + + + Host is being suspended (power management event). + + + Host is being resumed (power management event). + + + Host is running low on battery (power management event). + + + A snapshot of the VM is being taken. + + + + + + PID of the process that has created this Session object. + + + + + + Returns the console object suitable for remote control. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + Returns suitable machine state for the VM execution state. Useful + for choosing a sensible machine state after a complex operation which + failed or otherwise resulted in an unclear situation. + + + + + + + Assigns the machine object associated with this direct-type + session or informs the session that it will be a remote one + (if @a machine == @c null). + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + + + + Assigns the machine object associated with this direct-type + session or informs the session that it will be a remote one + (if @a machine == @c null). + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + + + + Assigns the machine and the (remote) console object associated with + this remote-type session. + + + Session state prevents operation. + + + + + + + + + + Updates the machine state in the VM process. + Must be called only in certain cases + (see the method implementation). + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Uninitializes (closes) this session. Used by VirtualBox to close + the corresponding remote session when the direct session dies + or gets closed. + + + Session state prevents operation. + + + + + + + + Triggered when settings of a network adapter of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + + Triggerd when settings of the audio adapter of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Triggerd when the state of a host audio device + has changed. + + + Device the state has been changed for. + + + Whether this is a newly detected device or not. + + + The new device state. + + + Error information. + + + + + + Triggered when settings of a serial port of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Triggered when settings of a parallel port of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Triggered when settings of a storage controller of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + The id of the machine containing the storage controller. + + + The name of the storage controller. + + + + + + Triggered when attached media of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + The medium attachment which changed. + + + If the medium change was forced. + + + + + + Triggered when attached storage devices of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + The medium attachment which changed. + + + TRUE if the device is removed, FALSE if it was added. + + + TRUE if the device is is silently reconfigured without + notifying the guest about it. + + + + + + Triggered when process priority of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + Error from underlying level. See additional error info. + + + + + + The priority which set. + + + + + + Notification when the shared clipboard mode changes. + + + The new shared clipboard mode. + + + + + + Notification when the shared clipboard file transfers mode changes. + + + Flag whether clipboard file transfers are allowed or not. + + + + + + Notification when the drag'n drop mode changes. + + + The new mode for drag'n drop. + + + + + + Notification when a CPU changes. + + + The CPU which changed + + + Flag whether the CPU was added or removed + + + + + + Notification when the CPU execution cap changes. + + + The new CPU execution cap value. (1-100) + + + + + + Triggered when settings of the VRDE server object of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + Flag whether the server must be restarted + + + + + + Triggered when recording settings have changed. + + + TODO + + + + + + Triggered when settings of the USB controller object of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + Triggered when a permanent (global or machine) shared folder has been + created or removed. + + We don't pass shared folder parameters in this notification because + the order in which parallel notifications are delivered is not defined, + therefore it could happen that these parameters were outdated by the + time of processing this notification. + + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Triggered when settings of the guest debug settings of the + associated virtual machine have changed. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + Triggered when a request to capture a USB device (as a result + of matched USB filters or direct call to + ) has completed. + A @c null @a error object means success, otherwise it + describes a failure. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + + + + Triggered when a request to release the USB device (as a result + of machine termination or direct call to + ) has completed. + A @c null @a error object means success, otherwise it + describes a failure. + + + Session state prevents operation. + + + Session type prevents operation. + + + + + + + + + + Called by and by + in order to notify + console listeners + + and . + + + Session type prevents operation. + + + + + + + + + + + Notification when one of the bandwidth groups change. + + + The bandwidth group which changed. + + + + + + Called by and by + in order to read and + modify guest properties. + + + Machine session is not open. + + + Session type is not direct. + + + + + Name of guest property. + + + Value of guest property. + + + Flags of guest property. + + + 0 = get, 1 = set, 2 = delete. + + + When getting: Value of guest property. + + + When getting: Timestamp of guest property. + + + When getting: Flags of guest property. + + + + + + Return a list of the guest properties matching a set of patterns along + with their values, timestamps and flags. + + + Machine session is not open. + + + Session type is not direct. + + + + + + The patterns to match the properties against as a comma-separated + string. If this is empty, all properties currently set will be + returned. + + + + + The key names of the properties returned. + + + + + The values of the properties returned. The array entries match the + corresponding entries in the @a key array. + + + + + The timestamps of the properties returned. The array entries match + the corresponding entries in the @a key array. + + + + + The flags of the properties returned. The array entries match the + corresponding entries in the @a key array. + + + + + + + Triggers online merging of a hard disk. Used internally when deleting + a snapshot while a VM referring to the same hard disk chain is running. + + + Machine session is not open. + + + Session type is not direct. + + + + + The medium attachment to identify the medium chain. + + + The index of the source image in the chain. + Redundant, but drastically reduces IPC. + + + The index of the target image in the chain. + Redundant, but drastically reduces IPC. + + + + Progress object for this operation. + + + + + + + Reconfigure all specified medium attachments in one go, making sure + the current state corresponds to the specified medium. + + + Machine session is not open. + + + Session type is not direct. + + + + Array containing the medium attachments which need to be + reconfigured. + + + + + + Enables or disables collection of VMM RAM statistics. + + + Machine session is not open. + + + Session type is not direct. + + + + + True enables statistics collection. + + + + + + Internal method for triggering a VM pause with a specified reason code. + The reason code can be interpreted by device/drivers and thus it might + behave slightly differently than a normal VM pause. + + + Virtual machine not in Running state. + + + Virtual machine error in suspend operation. + + + + + + Specify the best matching reason code please. + + + + + + Internal method for triggering a VM resume with a specified reason code. + The reason code can be interpreted by device/drivers and thus it might + behave slightly differently than a normal VM resume. + + + Virtual machine not in Paused state. + + + Virtual machine error in resume operation. + + + + + + Specify the best matching reason code please. + + + + + + Internal method for triggering a VM save state with a specified reason + code. The reason code can be interpreted by device/drivers and thus it + might behave slightly differently than a normal VM save state. + + This call is fully synchronous, and the caller is expected to have set + the machine state appropriately (and has to set the follow-up machine + state if this call failed). + + + Virtual machine state is not one of the expected values. + + + Failed to create directory for saved state file. + + + + + + Specify the best matching reason code please. + + + Progress object to track the operation completion. + + + Snapshot object for which this save state operation is executed. + + + File path the VM process must save the execution state to. + + + The VM should be paused before saving state. It is automatically + unpaused on error in the "vanilla save state" case. + + + Returns if the VM was left in paused state, which is necessary + in many situations (snapshots, teleportation). + + + + + + Internal method for cancelling a VM save state. + + + + + + + + + The ISession interface represents a client process and allows for locking + virtual machines (represented by IMachine objects) to prevent conflicting + changes to the machine. + + Any caller wishing to manipulate a virtual machine needs to create a session + object first, which lives in its own process space. Such session objects are + then associated with objects living in the VirtualBox + server process to coordinate such changes. + + There are two typical scenarios in which sessions are used: + +
    +
  • To alter machine settings or control a running virtual machine, one + needs to lock a machine for a given session (client process) by calling + . + + Whereas multiple sessions may control a running virtual machine, only + one process can obtain a write lock on the machine to prevent conflicting + changes. A write lock is also needed if a process wants to actually run a + virtual machine in its own context, such as the VirtualBox GUI or + VBoxHeadless front-ends. They must also lock a machine for their own + sessions before they are allowed to power up the virtual machine. + + As a result, no machine settings can be altered while another process is + already using it, either because that process is modifying machine settings + or because the machine is running. +
    • +
  • To start a VM using one of the existing VirtualBox front-ends (e.g. the + VirtualBox GUI or VBoxHeadless), one would use + , which also takes a session object + as its first parameter. This session then identifies the caller and lets the + caller control the started machine (for example, pause machine execution or + power it down) as well as be notified about machine execution state changes. +
    • +
+ + How sessions objects are created in a client process depends on whether you use + the Main API via COM or via the webservice: + +
    +
  • When using the COM API directly, an object of the Session class from the + VirtualBox type library needs to be created. In regular COM C++ client code, + this can be done by calling createLocalObject(), a standard COM API. + This object will then act as a local session object in further calls to open + a session. +
    • + +
  • In the webservice, the session manager (IWebsessionManager) instead creates + a session object automatically whenever + is called. A managed object reference to that session object can be retrieved by + calling . +
    • +
+ + + + Current state of this session. + + + + + Type of this session. The value of this attribute is valid only + if the session currently has a machine locked (i.e. its + is Locked), otherwise an error will be returned. + + + + + + Name of this session. Important only for VM sessions, otherwise it + it will be remembered, but not used for anything significant (and can + be left at the empty string which is the default). The value can only + be changed when the session state is SessionState_Unlocked. Make sure + that you use a descriptive name which does not conflict with the VM + process session names: "GUI/Qt", "GUI/SDL" and "headless". + + + + + Machine object associated with this session. + + + + Console object associated with this session. Only sessions + which locked the machine for a VM process have a non-null console. + + + + + Unlocks a machine that was previously locked for the current session. + + Calling this method is required every time a machine has been locked + for a particular session using the + or calls. Otherwise the state of + the machine will be set to on the + server, and changes made to the machine settings will be lost. + + Generally, it is recommended to unlock all machines explicitly + before terminating the application (regardless of the reason for + the termination). + + + Do not expect the session state ( + to return to "Unlocked" immediately after you invoke this method, + particularly if you have started a new VM process. The session + state will automatically return to "Unlocked" once the VM is no + longer executing, which can of course take a very long time. + + + + Session is not locked. + + + + + + + + + + + + The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy); + see . + + + @c null value. Never used by the API. + + + + + + + + + + + + + + The exact variant of storage controller hardware presented + to the guest; see . + + + + @c null value. Never used by the API. + + + A SCSI controller of the LsiLogic variant. + + + A SCSI controller of the BusLogic variant. + + + An Intel AHCI SATA controller; this is the only variant for SATA. + + + An IDE controller of the PIIX3 variant. + + + An IDE controller of the PIIX4 variant. + + + An IDE controller of the ICH6 variant. + + + A floppy disk controller; this is the only variant for floppy drives. + + + A variant of the LsiLogic controller using SAS. + + + Special USB based storage controller. + + + An NVMe storage controller. + + + Virtio SCSI storage controller. + + + + + + Type of emulated chipset (mostly southbridge). + + + + @c null value. Never used by the API. + + + A PIIX3 (PCI IDE ISA Xcelerator) chipset. + + + A ICH9 (I/O Controller Hub) chipset. + + + + + + Represents a storage controller that is attached to a virtual machine + (). Just as drives (hard disks, DVDs, FDs) are + attached to storage controllers in a real computer, virtual drives + (represented by ) are attached to virtual + storage controllers, represented by this interface. + + As opposed to physical hardware, VirtualBox has a very generic concept + of a storage controller, and for purposes of the Main API, all virtual + storage is attached to virtual machines via instances of this interface. + There are five types of such virtual storage controllers: IDE, SCSI, SATA, + SAS and Floppy (see ). Depending on which of these four + is used, certain sub-types may be available and can be selected in + . + + Depending on these settings, the guest operating system might see + significantly different virtual hardware. + + + + + Name of the storage controller, as originally specified with + . This then uniquely + identifies this controller with other method calls such as + and . + + + + + + Maximum number of devices which can be attached to one port. + + + + + + Minimum number of ports that can be set to. + + + + + + Maximum number of ports that can be set to. + + + + + + The instance number of the device in the running VM. + + + + + + The number of currently usable ports on the controller. + The minimum and maximum number of ports for one controller are + stored in + and . + + + + + + The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy). + + + + + + The exact variant of storage controller hardware presented + to the guest. + Depending on this value, VirtualBox will provide a different + virtual storage controller hardware to the guest. + For SATA, SAS and floppy controllers, only one variant is + available, but for IDE and SCSI, there are several. + + For SCSI controllers, the default type is LsiLogic. + + + + + + If true, the storage controller emulation will use a dedicated I/O thread, enable the host I/O + caches and use synchronous file APIs on the host. This was the only option in the API before + VirtualBox 3.2 and is still the default for IDE controllers. + + If false, the host I/O cache will be disabled for image files attached to this storage controller. + Instead, the storage controller emulation will use asynchronous I/O APIs on the host. This makes + it possible to turn off the host I/O caches because the emulation can handle unaligned access to + the file. This should be used on OS X and Linux hosts if a high I/O load is expected or many + virtual machines are running at the same time to prevent I/O cache related hangs. + This option new with the API of VirtualBox 3.2 and is now the default for non-IDE storage controllers. + + + + + + Returns whether it is possible to boot from disks attached to this controller. + + + + + + + + + + + Managed object reference. + + Only within the webservice, a managed object reference (which is really + an opaque number) allows a webservice client to address an object + that lives in the address space of the webservice server. + + Behind each managed object reference, there is a COM object that lives + in the webservice server's address space. The COM object is not freed + until the managed object reference is released, either by an explicit + call to or by logging off from + the webservice (), which releases + all objects created during the webservice session. + + Whenever a method call of the VirtualBox API returns a COM object, the + webservice representation of that method will instead return a + managed object reference, which can then be used to invoke methods + on that object. + + + + + Returns the name of the interface that this managed object represents, + for example, "IMachine", as a string. + + + + + + + Releases this managed object reference and frees the resources that + were allocated for it in the webservice server process. After calling + this method, the identifier of the reference can no longer be used. + + + + + + + + + + Websession manager. This provides essential services + to webservice clients. + + + + Logs a new client onto the webservice and returns a managed object reference to + the IVirtualBox instance, which the client can then use as a basis to further + queries, since all calls to the VirtualBox API are based on the IVirtualBox + interface, in one way or the other. + + + + + + + + + Returns a managed object reference to a new ISession object for every + call to this method. + + + + + + + + + + Logs off the client who has previously logged on with + and destroys all resources associated with the websession (most + importantly, all managed objects created in the server while the + websession was active). + + + + + + + + + + + + + The IPerformanceMetric interface represents parameters of the given + performance metric. + + + + + Name of the metric. + + + + + + Object this metric belongs to. + + + + + + Textual description of the metric. + + + + + + Time interval between samples, measured in seconds. + + + + + + Number of recent samples retained by the performance collector for this + metric. + + When the collected sample count exceeds this number, older samples + are discarded. + + + + + + Unit of measurement. + + + + + + Minimum possible value of this metric. + + + + + + Maximum possible value of this metric. + + + + + + + The IPerformanceCollector interface represents a service that collects + and stores performance metrics data. + + Performance metrics are associated with objects of interfaces like IHost + and IMachine. Each object has a distinct set of performance metrics. The + set can be obtained with . + + Metric data is collected at the specified intervals and is retained + internally. The interval and the number of retained samples can be set + with . Both metric data + and collection settings are not persistent, they are discarded as soon as + VBoxSVC process terminates. Moreover, metric settings and data associated + with a particular VM only exist while VM is running. They disappear as + soon as VM shuts down. It is not possible to set up metrics for machines + that are powered off. One needs to start VM first, then set up metric + collection parameters. + + Metrics are organized hierarchically, with each level separated by a + slash (/) character. Generally, the scheme for metric names is like this: + + Category/Metric[/SubMetric][:aggregation] + + "Category/Metric" together form the base metric name. A base metric is + the smallest unit for which a sampling interval and the number of + retained samples can be set. Only base metrics can be enabled and + disabled. All sub-metrics are collected when their base metric is + collected. Collected values for any set of sub-metrics can be queried + with . + + For example "CPU/Load/User:avg" metric name stands for the "CPU" + category, "Load" metric, "User" submetric, "average" aggregate. An + aggregate function is computed over all retained data. Valid aggregate + functions are: + +
    +
  • avg -- average
    • +
  • min -- minimum
    • +
  • max -- maximum
    • +
+ + When setting up metric parameters, querying metric data, enabling or + disabling metrics wildcards can be used in metric names to specify a + subset of metrics. For example, to select all CPU-related metrics + use CPU/*, all averages can be queried using *:avg and + so on. To query metric values without aggregates *: can be used. + + The valid names for base metrics are: + +
    +
  • CPU/Load
    • +
  • CPU/MHz
    • +
  • RAM/Usage
    • +
  • RAM/VMM
    • +
+ + The general sequence for collecting and retrieving the metrics is: +
    +
  • + Obtain an instance of IPerformanceCollector with + +
    • +
  • + Allocate and populate an array with references to objects the metrics + will be collected for. Use references to IHost and IMachine objects. +
    • +
  • + Allocate and populate an array with base metric names the data will + be collected for. +
    • +
  • + Call . From now on + the metric data will be collected and stored. +
    • +
  • + Wait for the data to get collected. +
    • +
  • + Allocate and populate an array with references to objects the metric + values will be queried for. You can re-use the object array used for + setting base metrics. +
    • +
  • + Allocate and populate an array with metric names the data will be + collected for. Note that metric names differ from base metric names. +
    • +
  • + Call . The data + that have been collected so far are returned. Note that the values + are still retained internally and data collection continues. +
    • +
+ + For an example of usage refer to the following files in VirtualBox SDK: +
    +
  • + Java: bindings/webservice/java/jax-ws/samples/metrictest.java +
    • +
  • + Python: bindings/xpcom/python/sample/shellcommon.py +
    • +
+ + + + + Array of unique names of metrics. + + This array represents all metrics supported by the performance + collector. Individual objects do not necessarily support all of them. + can be used to get the + list of supported metrics for a particular object. + + + + + + Returns parameters of specified metrics for a set of objects. + + @c Null metrics array means all metrics. @c Null object array means + all existing objects. + + + + + Metric name filter. Currently, only a comma-separated list of metrics + is supported. + + + + + Set of objects to return metric parameters for. + + + + + Array of returned metric parameters. + + + + + + + Sets parameters of specified base metrics for a set of objects. Returns + an array of describing the metrics + have been affected. + + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + + + + + Metric name filter. Comma-separated list of metrics with wildcard + support. + + + + + Set of objects to setup metric parameters for. + + + + + Time interval in seconds between two consecutive samples of + performance data. + + + + + Number of samples to retain in performance data history. Older + samples get discarded. + + + + + Array of metrics that have been modified by the call to this method. + + + + + + + Turns on collecting specified base metrics. Returns an array of + describing the metrics have been + affected. + + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + + + + + Metric name filter. Comma-separated list of metrics with wildcard + support. + + + + + Set of objects to enable metrics for. + + + + + Array of metrics that have been modified by the call to this method. + + + + + + + Turns off collecting specified base metrics. Returns an array of + describing the metrics have been + affected. + + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + + + + + Metric name filter. Comma-separated list of metrics with wildcard + support. + + + + + Set of objects to disable metrics for. + + + + + Array of metrics that have been modified by the call to this method. + + + + + + + Queries collected metrics data for a set of objects. + + The data itself and related metric information are returned in seven + parallel and one flattened array of arrays. Elements of + returnMetricNames, returnObjects, returnUnits, returnScales, + returnSequenceNumbers, returnDataIndices and returnDataLengths with + the same index describe one set of values corresponding to a single + metric. + + The returnData parameter is a flattened array of arrays. Each + start and length of a sub-array is indicated by + returnDataIndices and returnDataLengths. The first + value for metric metricNames[i] is at + returnData[returnIndices[i]]. + + + @c Null or empty metric name array means all metrics. @c Null or + empty object array means all existing objects. If metric name array + contains a single element and object array contains many, the single + metric name array element is applied to each object array element to + form metric/object pairs. + + + Data collection continues behind the scenes after call to + @c queryMetricsData. The return data can be seen as the snapshot of + the current state at the time of @c queryMetricsData call. The + internally kept metric values are not cleared by the call. This + allows querying different subsets of metrics or aggregates with + subsequent calls. If periodic querying is needed it is highly + suggested to query the values with @c interval*count period to avoid + confusion. This way a completely new set of data values will be + provided by each query. + + + + + Metric name filter. Comma-separated list of metrics with wildcard + support. + + + + + Set of objects to query metrics for. + + + + + Names of metrics returned in @c returnData. + + + + + Objects associated with metrics returned in @c returnData. + + + + + Units of measurement for each returned metric. + + + + + Divisor that should be applied to return values in order to get + floating point values. For example: + (double)returnData[returnDataIndices[0]+i] / returnScales[0] + will retrieve the floating point value of i-th sample of the first + metric. + + + + + Sequence numbers of the first elements of value sequences of + particular metrics returned in @c returnData. For aggregate metrics + it is the sequence number of the sample the aggregate started + calculation from. + + + + + Indices of the first elements of value sequences of particular + metrics returned in @c returnData. + + + + + Lengths of value sequences of particular metrics. + + + + + Flattened array of all metric data containing sequences of values for + each metric. + + + + + + + + + + + + + + + + + + + + + Protocol definitions used with NAT port-forwarding rules. + + Port-forwarding uses UDP protocol. + + + Port-forwarding uses TCP protocol. + + + + + Interface for managing a NAT engine which is used with a virtual machine. This + allows for changing NAT behavior such as port-forwarding rules. This interface is + used in the attribute. + + The network attribute of the NAT engine (the same value is used with built-in + DHCP server to fill corresponding fields of DHCP leases). + + + IP of host interface to bind all opened sockets to. + Changing this does not change binding of port forwarding. + + + + TFTP prefix attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases. + + + TFTP boot file attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases. + + + TFTP server attribute which is used with the built-in DHCP server to fill + the corresponding fields of DHCP leases. + The preferred form is IPv4 addresses. + + + + + + + Whether the DHCP server should pass the DNS domain used by the host. + + + Whether the DHCP server (and the DNS traffic by NAT) should pass the address + of the DNS proxy and process traffic using DNS servers registered on the host. + + + Whether the DHCP server (and the DNS traffic by NAT) should pass the address + of the DNS proxy and process traffic using the host resolver mechanism. + + + Array of NAT port-forwarding rules in string representation, in the following + format: "name,protocol id,host ip,host port,guest ip,guest port". + + + Whether traffic from the guest directed to 10.0.2.2 will reach the + host's loopback interface, i.e. localhost or 127.0.0.1. + + + Sets network configuration of the NAT engine. + + MTU (maximum transmission unit) of the NAT engine in bytes. + + + Capacity of the socket send buffer in bytes when creating a new socket. + + + Capacity of the socket receive buffer in bytes when creating a new socket. + + + Initial size of the NAT engine's sending TCP window in bytes when + establishing a new TCP connection. + + + Initial size of the NAT engine's receiving TCP window in bytes when + establishing a new TCP connection. + + + + Returns network configuration of NAT engine. See + for parameter descriptions. + + + + + + + + Adds a new NAT port-forwarding rule. + + The name of the rule. An empty name is acceptable, in which case the NAT engine + auto-generates one using the other parameters. + + + Protocol handled with the rule. + + + IP of the host interface to which the rule should apply. An empty ip address is + acceptable, in which case the NAT engine binds the handling socket to any interface. + + + The port number to listen on. + + + The IP address of the guest which the NAT engine will forward matching packets + to. An empty IP address is acceptable, in which case the NAT engine will forward + packets to the first DHCP lease (x.x.x.15). + + + The port number to forward. + + + + Removes a port-forwarding rule that was previously registered. + + The name of the rule to delete. + + + + + + + + + Interface for keeping information about a plug-in that ships with an + extension pack. + + + The plug-in name. + + + The plug-in description. + + + + The name of the frontend or component name this plug-in plugs into. + + + + The module path. + + + + + + Interface for querying information about an extension pack as well as + accessing COM objects within it. + + + The extension pack name. This is unique. + + + The extension pack description. + + + + The extension pack version string. This is restricted to the dotted + version number and optionally a build indicator. No tree revision or + tag will be included in the string as those things are available as + separate properties. An optional publisher tag may be present like for + . + + Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2". + + + + The extension pack internal revision number. + + + + Edition indicator. This is usually empty. + + Can for instance be used to help distinguishing between two editions + of the same extension pack where only the license, service contract or + something differs. + + + + The name of the VRDE module if the extension pack sports one. + + + + The name of the crypto module if the extension pack sports one. + This module is required for full VM encryption. + + + + Plug-ins provided by this extension pack. + + + + Indicates whether the extension pack is usable or not. + + There are a number of reasons why an extension pack might be unusable, + typical examples would be broken installation/file or that it is + incompatible with the current VirtualBox version. + + + + + String indicating why the extension pack is not usable. This is an + empty string if usable and always a non-empty string if not usable. + + + + Whether to show the license before installation + + + + The default HTML license text for the extension pack. Same as + calling queryLicense with + preferredLocale and preferredLanguage as empty strings and format set + to html. + + + + + + Full feature version of the license attribute. + + + + The preferred license locale. Pass an empty string to get the default + license. + + + + + The preferred license language. Pass an empty string to get the + default language for the locale. + + + + + The license format: html, rtf or txt. If a license is present there + will always be an HTML of it, the rich text format (RTF) and plain + text (txt) versions are optional. If + + + + The license text. + + + + + + + + Interface for querying information about an extension pack as well as + accessing COM objects within it. + + + + Queries the IUnknown interface to an object in the extension pack + main module. This allows plug-ins and others to talk directly to an + extension pack. + + + The object ID. What exactly this is + + + The queried interface. + + + + + + + Extension pack file (aka tarball, .vbox-extpack) representation returned + by . This provides the base + extension pack information with the addition of the file name. + + + + The path to the extension pack file. + + + + + + Install the extension pack. + + + + Set this to automatically uninstall any existing extension pack with + the same name as the one being installed. + + + + + Platform specific display information. Reserved for future hacks. + + + + + Progress object for the operation. + + + + + + + + Interface for managing VirtualBox Extension Packs. + + @todo Describe extension packs, how they are managed and how to create one. + + + + + List of the installed extension packs. + + + + + + Returns the extension pack with the specified name if found. + + + No extension pack matching @a name was found. + + + + The name of the extension pack to locate. + + + The extension pack if found. + + + + + + Attempts to open an extension pack file in preparation for + installation. + + + The path of the extension pack tarball. This can optionally be + followed by a "::SHA-256=hex-digit" of the tarball. + + + The interface of the extension pack file object. + + + + + Uninstalls an extension pack, removing all related files. + + The name of the extension pack to uninstall. + + + + Forced removal of the extension pack. This means that the uninstall + hook will not be called. + + + + + Platform specific display information. Reserved for future hacks. + + + + + Progress object for the operation. + + + + + + Cleans up failed installs and uninstalls + + + + + Gets the path to all the plug-in modules for a given frontend. + + This is a convenience method that is intended to simplify the plug-in + loading process for a frontend. + + + The name of the frontend or component. + + + Array containing the plug-in modules (full paths). + + + + + Check if the given extension pack is loaded and usable. + + The name of the extension pack to check for. + + + Is the given extension pack loaded and usable. + + + + + + + + + + Type of a bandwidth control group. + + + + + Null type, must be first. + + + + + + The bandwidth group controls disk I/O. + + + + + + The bandwidth group controls network I/O. + + + + + + + + Represents one bandwidth group. + + + Name of the group. + + + + Type of the group. + + + + How many devices/medium attachments use this group. + + + + The maximum number of bytes which can be transfered by all + entities attached to this group during one second. + + + + + + + + Controls the bandwidth groups of one machine used to cap I/O done by a VM. + This includes network and disk I/O. + + + + + The current number of existing bandwidth groups managed. + + + + + + Creates a new bandwidth group. + + + + Name of the bandwidth group. + + + The type of the bandwidth group (network or disk). + + + The maximum number of bytes which can be transfered by all + entities attached to this group during one second. + + + + + + Deletes a new bandwidth group. + + + + Name of the bandwidth group to delete. + + + + + + Get a bandwidth group by name. + + + + Name of the bandwidth group to get. + + + Where to store the bandwidth group on success. + + + + + + Get all managed bandwidth groups. + + + + The array of managed bandwidth groups. + + + + + + + + The enabled guest debug provider. This enumeration represents possible + values for the attribute. + + + Guest debugging is disabled. + + + The native debugger console is enabled. + + + The GDB remote stub is enabled. + + + The WinDbg/KD remote stub is enabled. + + + + + + The enabled guest debug I/O provider. This enumeration represents possible + values for the attribute. + + + No connection available (only useful with + ). + + + + The remote stub is available through a TCP connection. + + + The remote stub is available through a UDP connection. + + + The remote stub is available through a IPC connection, + namely a named pipe on Windows or a unix socket on other hosts. + + + + + + Controls the guest debug settings of one virtual machine. + + + + The currently active debug provider. + + + + The I/O backend for the selected debug provider. + + + + + The address to connect to or listen on, + depending on the type. + + + + + + The port to listen on or connect to, depending on the selected I/O + provider. Might be ignored by some providers. + + + + + + + + + Convenience interface for client applications. Treat this as a + singleton, i.e. never create more than one instance of this interface. + + At the moment only available for clients of the local API (not usable + via the webservice). Once the session logic is redesigned this might + change. + + Error information handling is a bit special with IVirtualBoxClient: + creating an instance will always succeed. The return of the actual error + code/information is postponed to any attribute or method call. The + reason for this is that COM likes to mutilate the error code and lose + the detailed error information returned by instance creation. + + + + + Reference to the server-side API root object. + + + + + + Create a new session object and return the reference to it. + + + + + + Event source for VirtualBoxClient events. + + + + + + Perform error checking before using an object. + Generally useful before starting a VM and all other uses. If anything + is not as it should be then this method will return an appropriate + error. + + + + The machine object to check. + + + + + + + + + Type of an event. + See for an introduction to VirtualBox event handling. + + + + + Invalid event, must be first. + + + + + + Wildcard for all events. + Events of this type are never delivered, and only used in + call to simplify registration. + + + + + + Wildcard for all vetoable events. Events of this type are never delivered, and only + used in call to simplify registration. + + + + + + Wildcard for all machine events. Events of this type are never delivered, and only used in + call to simplify registration. + + + + + + Wildcard for all snapshot events. Events of this type are never delivered, and only used in + call to simplify registration. + + + + + + Wildcard for all input device (keyboard, mouse) events. + Events of this type are never delivered, and only used in + call to simplify registration. + + + + + + Last wildcard. + + + + + + See IMachineStateChangedEvent. + + + + + See IMachineDataChangedEvent. + + + + + See IExtraDataChangedEvent. + + + + + See IExtraDataCanChangeEvent. + + + + + See IMediumRegisteredEvent. + + + + + See IMachineRegisteredEvent. + + + + + See ISessionStateChangedEvent. + + + + + See ISnapshotTakenEvent. + + + + + See ISnapshotDeletedEvent. + + + + + See ISnapshotChangedEvent. + + + + + See IGuestPropertyChangedEvent. + + + + + + See IMousePointerShapeChangedEvent. + + + + + See IMouseCapabilityChangedEvent. + + + + + See IKeyboardLedsChangedEvent. + + + + + See IStateChangedEvent. + + + + + See IAdditionsStateChangedEvent. + + + + + See INetworkAdapterChangedEvent. + + + + + See ISerialPortChangedEvent. + + + + + See IParallelPortChangedEvent. + + + + + See IStorageControllerChangedEvent. + + + + + See IMediumChangedEvent. + + + + + See IVRDEServerChangedEvent. + + + + + See IUSBControllerChangedEvent. + + + + + See IUSBDeviceStateChangedEvent. + + + + + See ISharedFolderChangedEvent. + + + + + See IRuntimeErrorEvent. + + + + + See ICanShowWindowEvent. + + + + + See IShowWindowEvent. + + + + + See ICPUChangedEvent. + + + + + See IVRDEServerInfoChangedEvent. + + + + + See IEventSourceChangedEvent. + + + + + See ICPUExecutionCapChangedEvent. + + + + + See IGuestKeyboardEvent. + + + + + See IGuestMouseEvent. + + + + + See INATRedirectEvent. + + + + + See IHostPCIDevicePlugEvent. + + + + + See IVBoxSVCAvailablityChangedEvent. + + + + + See IBandwidthGroupChangedEvent. + + + + + See IGuestMonitorChangedEvent. + + + + + See IStorageDeviceChangedEvent. + + + + + See IClipboardModeChangedEvent. + + + + + See IDnDModeChangedEvent. + + + + + See INATNetworkChangedEvent. + + + + + See INATNetworkStartStopEvent. + + + + + See INATNetworkAlterEvent. + + + + + See INATNetworkCreationDeletionEvent. + + + + + See INATNetworkSettingEvent. + + + + + See INATNetworkPortForwardEvent. + + + + + See IGuestSessionStateChangedEvent. + + + + + See IGuestSessionRegisteredEvent. + + + + + See IGuestProcessRegisteredEvent. + + + + + See IGuestProcessStateChangedEvent. + + + + + See IGuestProcessInputNotifyEvent. + + + + + See IGuestProcessOutputEvent. + + + + + See IGuestFileRegisteredEvent. + + + + + See IGuestFileStateChangedEvent. + + + + + See IGuestFileOffsetChangedEvent. + + + + + See IGuestFileReadEvent. + + For performance reasons this is a separate event to + not unnecessarily overflow the event queue. + + + + + See IGuestFileWriteEvent. + + For performance reasons this is a separate event to + not unnecessarily overflow the event queue. + + + + + See IRecordingChangeEvent. + + + + + See IGuestUserStateChangedEvent. + + + + + See IGuestMultiTouchEvent. + + + + + See IHostNameResolutionConfigurationChangeEvent. + + + + + See ISnapshotRestoredEvent. + + + + + See IMediumConfigChangedEvent. + + + + + See IAudioAdapterChangedEvent. + + + + + See IProgressPercentageChangedEvent. + + + + + See IProgressTaskCompletedEvent. + + + + + See ICursorPositionChangedEvent. + + + + + See IGuestAdditionsStatusChangedEvent. + + + + + See IGuestMonitorInfoChangedEvent. + + + + + See IGuestFileSizeChangedEvent. + + + + + See IClipboardFileTransferModeChangedEvent. + + + + + See . + + + + + See . + + + + + See . + + + + + See . + + + + + See . + + + + + See . + + + + + See . + + + + + See IUpdateAgentAvailableEvent. + + + + + See IUpdateAgentErrorEvent. + + + + + See IUpdateAgentSettingsChangedEvent. + + + + + See IUpdateAgentStateChangedEvent. + + + + + See IHostAudioDeviceChangedEvent. + + + + + See IGuestDebugControlChangedEvent. + + + + + See IMachineGroupsChangedEvent. + + + + + + Must be last event, used for iterations and structures relying on numerical event values. + + + + + + + + Event source. Generally, any object which could generate events can be an event source, + or aggregate one. To simplify using one-way protocols such as webservices running on top of HTTP(S), + an event source can work with listeners in either active or passive mode. In active mode it is up to + the IEventSource implementation to call , in passive mode the + event source keeps track of pending events for each listener and returns available events on demand. + + See for an introduction to VirtualBox event handling. + + + + + Creates a new listener object, useful for passive mode. + + + + + + + Creates an aggregator event source, collecting events from multiple sources. + This way a single listener can listen for events coming from multiple sources, + using a single blocking on the returned aggregator. + + + + Subordinate event source this one aggregates. + + + + + Event source aggregating passed sources. + + + + + + + Register an event listener. + + + To avoid system overload, the VirtualBox server process checks if passive event + listeners call frequently enough. In the + current implementation, if more than 500 pending events are detected for a passive + event listener, it is forcefully unregistered by the system, and further + calls will return @c VBOX_E_OBJECT_NOT_FOUND. + + + + Listener to register. + + + + Event types listener is interested in. One can use wildcards like - + to specify wildcards, matching more + than one event. + + + + + Which mode this listener is operating in. + In active mode, is called directly. + In passive mode, an internal event queue is created for this this IEventListener. + For each event coming in, it is added to queues for all interested registered passive + listeners. It is then up to the external code to call the listener's + method. When done with an event, the + external code must call . + + + + + + + Unregister an event listener. If listener is passive, and some waitable events are still + in queue they are marked as processed automatically. + + + Listener to unregister. + + + + + + Fire an event for this source. + + + Event to deliver. + + + + Maximum time to wait for event processing (if event is waitable), in ms; + 0 = no wait, -1 = indefinite wait. + + + + true if an event was delivered to all targets, or is non-waitable. + + + + + + Get events from this peer's event queue (for passive mode). Calling this method + regularly is required for passive event listeners to avoid system overload; + see for details. + + + Listener is not registered, or autounregistered. + + + + Which listener to get data for. + + + + Maximum time to wait for events, in ms; + 0 = no wait, -1 = indefinite wait. + + + + Event retrieved, or null if none available. + + + + + + Must be called for waitable events after a particular listener finished its + event processing. When all listeners of a particular event have called this + method, the system will then call . + + + Which listener processed event. + + + Which event. + + + + + + + + Event listener. An event listener can work in either active or passive mode, depending on the way + it was registered. + See for an introduction to VirtualBox event handling. + + + + + Handle event callback for active listeners. It is not called for + passive listeners. After calling on all active listeners + and having received acknowledgement from all passive listeners via + , the event is marked as + processed and will return + immediately. + + + Event available. + + + + + + + + Abstract parent interface for VirtualBox events. Actual events will typically implement + a more specific interface which derives from this (see below). + + Introduction to VirtualBox events + + Generally speaking, an event (represented by this interface) signals that something + happened, while an event listener (see ) represents an + entity that is interested in certain events. In order for this to work with + unidirectional protocols (i.e. web services), the concepts of passive and active + listener are used. + + Event consumers can register themselves as listeners, providing an array of + events they are interested in (see ). + When an event triggers, the listener is notified about the event. The exact + mechanism of the notification depends on whether the listener was registered as + an active or passive listener: + +
    +
  • An active listener is very similar to a callback: it is a function invoked + by the API. As opposed to the callbacks that were used in the API before + VirtualBox 4.0 however, events are now objects with an interface hierarchy. +
    • + +
  • Passive listeners are somewhat trickier to implement, but do not require + a client function to be callable, which is not an option with scripting + languages or web service clients. Internally the + implementation maintains an event queue for each passive listener, and + newly arrived events are put in this queue. When the listener calls + , first element from its internal event + queue is returned. When the client completes processing of an event, + the function must be called, + acknowledging that the event was processed. It supports implementing + waitable events. On passive listener unregistration, all events from its + queue are auto-acknowledged. +
    • +
+ + Waitable events are useful in situations where the event generator wants to track + delivery or a party wants to wait until all listeners have completed the event. A + typical example would be a vetoable event (see ) where a + listeners might veto a certain action, and thus the event producer has to make + sure that all listeners have processed the event and not vetoed before taking + the action. + + A given event may have both passive and active listeners at the same time. + + Using events + + Any VirtualBox object capable of producing externally visible events provides an + @c eventSource read-only attribute, which is of the type . + This event source object is notified by VirtualBox once something has happened, so + consumers may register event listeners with this event source. To register a listener, + an object implementing the interface must be provided. + For active listeners, such an object is typically created by the consumer, while for + passive listeners should be used. Please + note that a listener created with must not be used as an active listener. + + Once created, the listener must be registered to listen for the desired events + (see ), providing an array of + enums. Those elements can either be the individual + event IDs or wildcards matching multiple event IDs. + + After registration, the callback's method is + called automatically when the event is triggered, while passive listeners have to call + and in + an event processing loop. + + The IEvent interface is an abstract parent interface for all such VirtualBox events + coming in. As a result, the standard use pattern inside + or the event processing loop is to check the attribute of the event and + then cast to the appropriate specific interface using @c QueryInterface(). + + + + + Event type. + + + + + + Source of this event. + + + + + + If we can wait for this event being processed. If false, returns immediately, + and doesn't make sense. Non-waitable events are generally better performing, + as no additional overhead associated with waitability imposed. + Waitable events are needed when one need to be able to wait for particular event processed, + for example for vetoable changes, or if event refers to some resource which need to be kept immutable + until all consumers confirmed events. + + + + + + Internal method called by the system when all listeners of a particular event have called + . This should not be called by client code. + + + + + + Wait until time outs, or this event is processed. Event must be waitable for this operation to have + described semantics, for non-waitable returns true immediately. + + + + Maximum time to wait for event processing, in ms; + 0 = no wait, -1 = indefinite wait. + + + + If this event was processed before timeout. + + + + + + + Base abstract interface for all reusable events. + + + Current generation of event, incremented on reuse. + + + + + Marks an event as reused, increments 'generation', fields shall no + longer be considered valid. + + + + + + Base abstract interface for all machine events. + + + ID of the machine this event relates to. + + + + + + Machine state change event. + + + New execution state. + + + + + + Any of the settings of the given machine has changed. + + + + @c true if the settings change is temporary. All permanent + settings changes will trigger an event, and only temporary settings + changes for running VMs will trigger an event. Note: sending events + for temporary changes is NOT IMPLEMENTED. + + + + + + The given medium was registered or unregistered + within this VirtualBox installation. + + + + ID of the medium this event relates to. + + + + Type of the medium this event relates to. + + + + + If @c true, the medium was registered, otherwise it was + unregistered. + + + + + + + The configuration of the given medium was changed (location, properties, + child/parent or anything else). + + + + ID of the medium this event relates to. + + + + + + The given machine was registered or unregistered + within this VirtualBox installation. + + + + + If @c true, the machine was registered, otherwise it was + unregistered. + + + + + + + The state of the session for the given machine was changed. + + + + + + New session state. + + + + + + + Notification when a guest property has changed. + + + + + The name of the property that has changed. + + + + + + The new property value. + + + + + + The new property flags. + + + + + + A flag which indicates that property was deleted. + + + + + + + Base interface for all snapshot events. + + + ID of the snapshot this event relates to. + + + + + + + A new snapshot of the machine has been taken. + + + + + + + + Snapshot of the given machine has been deleted. + + + This notification is delivered after the snapshot + object has been uninitialized on the server (so that any + attempt to call its methods will return an error). + + + + + + + + + + Snapshot of the given machine has been restored. + + + + + + + + Snapshot properties (name and/or description) have been changed. + + + + + + + + Notification when the guest mouse pointer shape has + changed. The new shape data is given. + + + + + Flag whether the pointer is visible. + + + + + Flag whether the pointer has an alpha channel. + + + + + The pointer hot spot X coordinate. + + + + + The pointer hot spot Y coordinate. + + + + + Width of the pointer shape in pixels. + + + + + Height of the pointer shape in pixels. + + + + + Shape buffer arrays. + + The @a shape buffer contains a 1-bpp (bits per pixel) AND mask + followed by a 32-bpp XOR (color) mask. + + For pointers without alpha channel the XOR mask pixels are + 32-bit values: (lsb)BGR0(msb). For pointers with alpha channel + the XOR mask consists of (lsb)BGRA(msb) 32-bit values. + + An AND mask is used for pointers with alpha channel, so if the + callback does not support alpha, the pointer could be + displayed as a normal color pointer. + + The AND mask is a 1-bpp bitmap with byte aligned scanlines. The + size of the AND mask therefore is cbAnd = (width + 7) / 8 * + height. The padding bits at the end of each scanline are + undefined. + + The XOR mask follows the AND mask on the next 4-byte aligned + offset: uint8_t *pXor = pAnd + (cbAnd + 3) & ~3. + Bytes in the gap between the AND and the XOR mask are undefined. + The XOR mask scanlines have no gap between them and the size of + the XOR mask is: cXor = width * 4 * height. + + + If @a shape is 0, only the pointer visibility is changed. + + + + + + + + Notification when the mouse capabilities reported by the + guest have changed. The new capabilities are passed. + + + + Supports absolute coordinates. + + + + + Supports relative coordinates. + + + + + Supports multi-touch events, touchscreen variant. + + + + + Supports multi-touch events, touchpad variant. + + + + + If host cursor is needed. + + + + + + + Notification when the guest OS executes the KBD_CMD_SET_LEDS command + to alter the state of the keyboard LEDs. + + + + NumLock status. + + + + + CapsLock status. + + + + + ScrollLock status. + + + + + + + Notification when the execution state of the machine has changed. + The new state is given. + + + + New machine state. + + + + + + + Notification when a Guest Additions property changes. + Interested callees should query IGuest attributes to + find out what has changed. + + + + + + + Notification when a property of one of the + virtual network adapters + changes. Interested callees should use INetworkAdapter methods and + attributes to find out what has changed. + + + + Network adapter that is subject to change. + + + + + + + Notification when a property of the audio adapter changes. + Interested callees should use IAudioAdapter methods and attributes + to find out what has changed. + + + + Audio adapter that is subject to change. + + + + + + + Notification when a property of one of the + virtual serial ports changes. + Interested callees should use ISerialPort methods and attributes + to find out what has changed. + + + + Serial port that is subject to change. + + + + + + + Notification when a property of one of the + virtual parallel ports + changes. Interested callees should use ISerialPort methods and + attributes to find out what has changed. + + + + Parallel port that is subject to change. + + + + + + + Notification when a + storage controllers + changes. + + + + The id of the machine containing the storage controller. + + + + + The name of the storage controller. + + + + + + + Notification when a + medium attachment + changes. + + + + Medium attachment that is subject to change. + + + + + + + Notification when the shared clipboard mode changes. + + + + The new clipboard mode. + + + + + + + Notification when the shared clipboard file transfer mode changes. + + + + Whether file transfers are allowed or not. + + + + + + + Notification when the drag'n drop mode changes. + + + + The new drag'n drop mode. + + + + + + + Notification when a CPU changes. + + + + The CPU which changed. + + + + + Flag whether the CPU was added or removed. + + + + + + + Notification when the CPU execution cap changes. + + + + The new CPU execution cap value. (1-100) + + + + + + + Notification when guest keyboard event happens. + + + + Array of scancodes. + + + + + + + + The mode (relative, absolute, multi-touch) of a pointer event. + + @todo A clear pattern seems to be emerging that we should usually have + multiple input devices active for different types of reporting, so we + should really have different event types for relative (including wheel), + absolute (not including wheel) and multi-touch events. + + + + + Relative event. + + + + + + Absolute event. + + + + + + + Notification when guest mouse event happens. + + + + + If this event is relative, absolute or multi-touch. + + + + + + New X position, or X delta. + + + + + + New Y position, or Y delta. + + + + + + Z delta. + + + + + + W delta. + + + + + + Button state bitmask. + + + + + + + + Notification when guest touch screen event happens. + + + + Number of contacts in the event. + + + + + X positions. + + + + + Y positions. + + + + + Contact identifiers. + + + + + Contact state. + Bit 0: in contact. + Bit 1: in range. + + + + + Distinguishes between touchscreen and touchpad events. + + + + + Timestamp of the event in milliseconds. Only relative time between events is important. + + + + + + Base abstract interface for all guest session events. + + + Guest session that is subject to change. + + + + + + + Notification when a guest session changed its state. + + + + + Session ID of guest session which was changed. + + + + + New session status. + + + + + Error information in case of new session status is indicating an error. + + The attribute will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + + + + + + + + Notification when a guest session was registered or unregistered. + + + + + If @c true, the guest session was registered, otherwise it was + unregistered. + + + + + + + Base abstract interface for all guest process events. + + + + Guest process object which is related to this event. + + + + + Guest process ID (PID). + + + + + + + + Notification when a guest process was registered or unregistered. + + + + + If @c true, the guest process was registered, otherwise it was + unregistered. + + + + + + + + Notification when a guest process changed its state. + + + + + New guest process status. + + + + + Error information in case of new session status is indicating an error. + + The attribute will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + + + + + + + + Base abstract interface for all guest process input/output (IO) events. + + + + + Input/output (IO) handle involved in this event. Usually 0 is stdin, + 1 is stdout and 2 is stderr. + + + + + + Processed input or output (in bytes). + + + + + + + + Notification when a guest process' stdin became available. + This event is right now not implemented! + + + + + Current process input status. + + + + + + + + Notification when there is guest process output available for reading. + + + + + Actual output data. + + + + + + + Base abstract interface for all guest file events. + + + + Guest file object which is related to this event. + + + + + + + + Notification when a guest file was registered or unregistered. + + + + + If @c true, the guest file was registered, otherwise it was + unregistered. + + + + + + + + Notification when a guest file changed its state. + + + + + New guest file status. + + + + + Error information in case of new session status is indicating an error. + + The attribute will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + + + + + + + + + Base abstract interface for all guest file input/output (IO) events. + + + + + Current offset (in bytes). + + + + + Processed input or output (in bytes). + + + + + + + + Notification when a guest file changed its current offset via . + + + + + + + + Notification when a guest file changed its size via . + + + + + + + + + Notification when data has been read from a guest file. + + + + + Actual data read. + + + + + + + + Notification when data has been written to a guest file. + + + + + + + + Notification when a property of the + VRDE server changes. + Interested callees should use IVRDEServer methods and attributes to + find out what has changed. + + + + + + + Notification when the status of the VRDE server changes. Interested callees + should use IVRDEServerInfo + attributes to find out what is the current status. + + + + + + + Notification when recording settings have changed. + + + + + + + Notification when a property of the virtual + USB controllers changes. + Interested callees should use IUSBController methods and attributes to + find out what has changed. + + + + + + + Notification when a USB device is attached to or detached from + the virtual USB controller. + + This notification is sent as a result of the indirect + request to attach the device because it matches one of the + machine USB filters, or as a result of the direct request + issued by or + . + + This notification is sent in case of both a succeeded and a + failed request completion. When the request succeeds, the + @a error parameter is @c null, and the given device has been + already added to (when @a attached is @c true) or removed from + (when @a attached is @c false) the collection represented by + . On failure, the collection + doesn't change and the @a error parameter represents the error + message describing the failure. + + + + Device that is subject to state change. + + + + + @c true if the device was attached and @c false otherwise. + + + + + @c null on success or an error message object on failure. + + + + + + + Notification when a shared folder is added or removed. + The @a scope argument defines one of three scopes: + global shared folders + (Global), + permanent shared folders of + the machine (Machine) or transient shared folders of the + machine (Session). Interested callees + should use query the corresponding collections to find out what has + changed. + + + + Scope of the notification. + + + + + + + Notification when an error happens during the virtual + machine execution. + + There are three kinds of runtime errors: +
    +
  • fatal
    • +
  • non-fatal with retry
    • +
  • non-fatal warnings
    • +
+ + Fatal errors are indicated by the @a fatal parameter set + to @c true. In case of fatal errors, the virtual machine + execution is always paused before calling this notification, and + the notification handler is supposed either to immediately save + the virtual machine state using + or power it off using . + Resuming the execution can lead to unpredictable results. + + Non-fatal errors and warnings are indicated by the + @a fatal parameter set to @c false. If the virtual machine + is in the Paused state by the time the error notification is + received, it means that the user can try to resume the machine + execution after attempting to solve the problem that caused the + error. In this case, the notification handler is supposed + to show an appropriate message to the user (depending on the + value of the @a id parameter) that offers several actions such + as Retry, Save or Power Off. If the user + wants to retry, the notification handler should continue + the machine execution using the + call. If the machine execution is not Paused during this + notification, then it means this notification is a warning + (for example, about a fatal condition that can happen very soon); + no immediate action is required from the user, the machine + continues its normal execution. + + Note that in either case the notification handler + must not perform any action directly on a thread + where this notification is called. Everything it is allowed to + do is to post a message to another thread that will then talk + to the user and take the corresponding action. + + Currently, the following error identifiers are known: +
    +
  • "HostMemoryLow"
    • +
  • "HostAudioNotResponding"
    • +
  • "VDIStorageFull"
    • +
  • "3DSupportIncompatibleAdditions"
    • +
+ + + + Whether the error is fatal or not. + + + + + Error identifier. + + + + + Optional error message. + + + + + + + + Notification when an event source state changes (listener added or removed). + + + + + Event listener which has changed. + + + + + + Flag whether listener was added or removed. + + + + + + + Notification when machine specific or global extra data + has changed. + + + + ID of the machine this event relates to. + Null for global extra data changes. + + + + + Extra data key that has changed. + + + + + Extra data value for the given key. + + + + + + Base abstract interface for veto events. + + + + Adds a veto on this event. + + + + Reason for veto, could be null or empty string. + + + + + + + If this event was vetoed. + + + + Reason for veto. + + + + + + + Current veto reason list, if size is 0 - no veto. + + + + Array of reasons for veto provided by different event handlers. + + + + + + + Adds an approval on this event. + + + + Reason for approval, could be null or empty string. + + + + + + + If this event was approved. + + + + + + + Current approval reason list, if size is 0 - no approvals. + + + + Array of reasons for approval provided by different event handlers. + + + + + + + + + Notification when someone tries to change extra data for + either the given machine or (if @c null) global extra data. + This gives the chance to veto against changes. + + + + ID of the machine this event relates to. + Null for global extra data changes. + + + + + Extra data key that has changed. + + + + + Extra data value for the given key. + + + + + + + Notification when a call to + is made by a + front-end to check if a subsequent call to + can succeed. + + The callee should give an answer appropriate to the current + machine state using event veto. This answer must + remain valid at least until the next + machine state change. + + + + + + + Notification when a call to + + requests the console window to be activated and brought to + foreground on the desktop of the host PC. + + This notification should cause the VM console process to + perform the requested action as described above. If it is + impossible to do it at a time of this notification, this + method should return a failure. + + Note that many modern window managers on many platforms + implement some sort of focus stealing prevention logic, so + that it may be impossible to activate a window without the + help of the currently active application (which is supposedly + an initiator of this notification). In this case, this method + must return a non-zero identifier that represents the + top-level window of the VM console process. The caller, if it + represents a currently active process, is responsible to use + this identifier (in a platform-dependent manner) to perform + actual window activation. + + This method must set @a winId to zero if it has performed all + actions necessary to complete the request and the console + window is now active and in foreground, to indicate that no + further action is required on the caller's side. + + + + Platform-dependent identifier of the top-level VM console + window, or zero if this method has performed all actions + necessary to implement the show window semantics for + the given platform and/or this VirtualBox front-end. + + + + + + + Notification when NAT redirect rule added or removed. + + + + Adapter which NAT attached to. + + + + + Whether rule remove or add. + + + + + Name of the rule. + + + + + Protocol (TCP or UDP) of the redirect rule. + + + + + Host ip address to bind socket on. + + + + + Host port to bind socket on. + + + + + Guest ip address to redirect to. + + + + + Guest port to redirect to. + + + + + + + Notification when a host audio device state has changed. + + + + + Host audio device that has changed. + + + + + + @c true if the host device is a newly detected device, @c false if not. + + + + + + New audio device state. + + + + + + @c null on success or an error message object on failure. + + + + + + + + Notification when host PCI device is plugged/unplugged. Plugging + usually takes place on VM startup, unplug - when + is called. + + + + + + + + If device successfully plugged or unplugged. + + + + + + If operation was successful, if false - 'message' attribute + may be of interest. + + + + + + Attachment info for this device. + + + + + + Optional error message. + + + + + + + + Notification when VBoxSVC becomes unavailable (due to a crash or similar + unexpected circumstances) or available again. + + + + + Whether VBoxSVC is available now. + + + + + + + Notification when one of the bandwidth groups changed + + + + The changed bandwidth group. + + + + + + + + How the guest monitor has been changed. + + + + + The guest monitor has been enabled by the guest. + + + + + + The guest monitor has been disabled by the guest. + + + + + + The guest monitor origin has changed in the guest. + + + + + + + Notification when the guest enables one of its monitors. + + + + + What was changed for this guest monitor. + + + + + + The monitor which was changed. + + + + + + Physical X origin relative to the primary screen. + Valid for Enabled and NewOrigin. + + + + + + Physical Y origin relative to the primary screen. + Valid for Enabled and NewOrigin. + + + + + + Width of the screen. + Valid for Enabled. + + + + + + Height of the screen. + Valid for Enabled. + + + + + + + + Notification when a guest user changed its state. + + + + + Name of the guest user whose state changed. + + + + + Name of the FQDN (fully qualified domain name) this user is bound + to. Optional. + + + + + What was changed for this guest user. See for + more information. + + + + + Optional state details, depending on the attribute. + + + + + + + + Notification when a + storage device + is attached or removed. + + + + Storage device that is subject to change. + + + + + Flag whether the device was removed or added to the VM. + + + + + Flag whether the guest should be notified about the change. + + + + + + + + + + + + + + IsStartEvent is true when NAT network is started and false on stopping. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Base abstract interface for all progress events. + + + GUID of the progress this event relates to. + + + + + + Notification of a new progress object creation/deletion. + Covers purely projess objects in VBoxSVC. This + event is signaled on the event source of IVirtualBox, unlike + the other progress events. + + + If @c true, the progress object was created, otherwise it + was deleted. + + + + + + Progress state change event. + + + New percent + + + + + Progress task completion event. + + + + + The guest reports cursor position data. + + + Event contains valid data. If not set, switch back to using the host cursor. + + + Reported X position + + + Reported Y position + + + + + The guest addition status changed. + + + Facility this event relates to. + + + The new facility status. + + + The new run level. + + + The millisecond timestamp associated with the event. + + + + + The guest reports cursor position data. + + + The virtual display output on which the monitor has changed. + + + + + + Abstract base interface for update agent events. + + + Update agent this event belongs to. + + + + + + Notification when update agent settings have been changed. + + + + + + + Notification when an update agent error occurred. + + + + + Error message in human readable format. + + + + + + IPRT-style error code. + + + + + + + + Notification when an update is available. + + + + + Version of the update. + + + + + + Channel containing the update. + + + + + + Severity of the update. + + + + + + Download URL of the update. + + + + + + Web URL of the update. + + + + + + Release notes of the update. + + + + + + + + Notification when an update agent state has been changed. + + + + + New update agent state. + + + + + + + + Notification when a property of the guest debug + settings changes. Interested callees should use IGuestDebugControl methods and attributes + to find out what has changed. + + + + Guest debug control object that is subject to change. + + + + + + + The groups of the machine have changed. + + + + + Dummy state because you can't have an event without attributes apparently. + + + + + + + + + When you need to return an array of strings asynchronously + (under a progress) you cannot use by-value out parameter + type="wstring" safearray="yes" + dir="out", hence this wrapper. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Counterpart of the attribute. + May be null or empty. Usually used for units. + + + + + + + + + + + + + + + + + Counterpart of the attribute. + May be null or empty. Usually used for units. + + + + + + + + + + + + + + + + + + + + + + + + + + Intnded for cases when a read-only string value is used to + display information and different string is to be used when + copying to the clipboard. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Cloud instance execution state + + Invalid state + + + The machine is in the process of provisioning + + + The machine runs + + + The machine is in the process of starting + + + The machine is in the process of stopping + + + The machine was stopped + + + The machine is in the process of creating image + + + The machine is in the process of terminating + + + The machine was terminated + + + + + Cloud image state + + Invalid state + + + The image is in the process of provisioning + + + The image is in the process of importing + + + The image is avalable + + + The image is in the process of exporting + + + The image is disabled + + + The image was deleted + + + + + + + + + + + + + + + + + + + Virtual virtual machine (sic) in the cloud. + + Reading object attributes returns cached values, use + to refresh them. + + + + UUID of the cloud machine. + + + + + Whether this virtual machine is currently accessible or not. + TBD... + + + + + + Error information describing the reason of machine + inaccessibility. + + Reading this property is only valid after the last call to + returned @c false (i.e. the + machine is currently inaccessible). Otherwise, a @c null + IVirtualBoxErrorInfo object will be returned. + + + + + + Convenience shortcut to retrieve the name of the cloud + machine. The name is part of the machine settings that are + hidden behind the settings form (see ). + + + + + + Convenience shortcut to retrieve the OS Type id of the cloud + machine. It is part of the machine settings that are hidden + behind the settings form (see ). + + + + + + Machine state. + + + + + + Refresh information by reading it from the cloud. + + + + Progress object to track the operation completion. + + + + + + + Obtain a form with the current settings for this cloud + machine. The form is not editable. + + + + A form with the cloud machine settings. + + + + + + + Obtain a form with settings for this cloud machine. + The form is editable. + + + + A form with the cloud machine settings. + + + + + Progress object to track the operation completion. + + + + + + + Start cloud virtual machine execution. + + + + Progress object to track the operation completion. + + + + + + + Reboot cloud virtual machine. + + + + Progress object to track the operation completion. + + + + + + + Forcing reset or hard reset of a cloud virtual machine. + + + + Progress object to track the operation completion. + + + + + + + Shutdown cloud virtual machine. + + + + Progress object to track the operation completion. + + + + + + + Initiates the power down procedure to stop the virtual machine + execution. + + The completion of the power down procedure is tracked using the returned + IProgress object. After the operation is complete, the machine will go + to the PoweredOff state. + + Virtual machine must be Running, to be powered down. + + + + + Progress object to track the operation completion. + + + + + + + Terminate cloud virtual machine. + + + + Progress object to track the operation completion. + + + + + + + Unregister this cloud machine, but leave the cloud artifacts + intact. + + + + Progress object to track the operation completion. + + + + + + + Unregister this cloud machine and delete all its cloud artifacts. + + + + Progress object to track the operation completion. + + + + + + + Get the backlog of the machine's console. If you have ever + seen console teletypes, this is like looking at the last few + meters of the paper it spewed. + + + + Data stream object for reading the console history. For now + we are abusing/repurposing this interface from the media + convertion API to avoid marshalling a huge string through + xpcom. + + + + Progress object to track the operation completion. + + + + + + + + SSH public key authorized to connect to the console. + + + + + Progress object to track the operation completion. + + + + + + + + Progress object to track the operation completion. + + + + + + + The fingerprint of the ssh key that is authorized to access + the machine's console connection. + + + + + + The shell command to establish ssh connection to the cloud + machine serial console. + + + + + + The PowerShell command to establish ssh connection to the + cloud machine serial console using PuTTY's plink. + + + + + + The shell command to establish ssh port forwarding for the + VNC connection to the cloud machine console. + + + + + + The PowerShell command to establish ssh port forwarding for the + VNC connection to the cloud machine console using PuTTY's plink. + + + + + + + + + + + Returns a form for editing the virtual system description for + exporting a local VM into a cloud custom image. + + + + Virtual system description to be edited. + + + + + An IForm instance for editing the virtual system description. + + + + + Progress object to track the operation completion. + + + + + + + Export local VM into the cloud, creating a custom image. + + + + Virtual system description object which describes the + machine and all required parameters. + + + + + Progress object to track the operation completion. + + + + + + + + Virtual system description to be edited. + + + + + An IForm instance for editing the virtual system description. + + + + + Progress object to track the operation completion. + + + + + + + + Virtual system description object which describes the + machine and all required parameters. + + + + + Progress object to track the operation completion. + + + + + + + Returns a form for editing the virtual system description for + import from cloud. + + + + Virtual system description to be edited. + + + + + An IForm instance for editing the virtual system description. + + + + + Progress object to track the operation completion. + + + + + + + Import an existing cloud instance to the local host. + All needed parameters are passed in the description (VSD). + + + VirtualSystemDescription object which is describing a machine and all required parameters. + + + Progress object to track the operation completion. + + + + + + Create an object that represents a cloud machine with the + specified UUID. Note that the operation is synchronous. The + returned machine is initiatally in inaccessible state and + requires a refresh to get its data from the cloud. + + + + UUID of a cloud machine. + + + + + Object that represents the cloud machine with the specified UUID. + + + + + + + Make the list of cloud machines available via + attribute. + + + + Progress object to track the operation completion. + + + + + + See . + + + + + + Make the list of cloud machine stubs available via + attribute. + Like with , the returned machines + are initiatally inaccessible and require a refresh to get + their data from the cloud. + + + + Progress object to track the operation completion. + + + + + + See . + + + + + + Adopt a running instance and register it as cloud machine. + This is kinda like adding a local .vbox file as a local VM. + + + + ID of an instance to be added as a cloud machine. + + + + + Object that represents the newly registered cloud machine. + + + + Progress object to track the operation completion. + + + + + + This is transitional method that combines + and . + + + + Virtual system description object which describes the + machine and all required parameters. + + + + + Object that represents the newly created cloud machine. + + + + + Progress object to track the operation completion. + + + + + + + Returns the list of the instances in the Cloud. + + + State of each VM. + + + VM names. + + + VM ids. + + + + Progress object to track the operation completion. + + + + + + + Returns the list of instances in the cloud that can be + added/adopted as VirtualBox cloud machines. + + + Instance names. + + + Instance idss. + + + + Progress object to track the operation completion. + + + + + + + Returns the list of the images in the Cloud. + + + State of each image. + + + Images names. + + + Images ids. + + + + Progress object to track the operation completion. + + + + + + + + Returns the list of boot volumes in the Cloud. + + + Boot volume names. + + + Boot volume ids. + + + + Progress object to track the operation completion. + + + + + + + Returns the list of boot volumes in the cloud that can be + added/adopted as VirtualBox cloud machines. + + + Boot volume names. + + + Boot volume ids. + + + + Progress object to track the operation completion. + + + + + + + Returns the list of the Vnic attachements in the Cloud. + + + Each parameter in the array must be in the form "name=value". + + + VM ids. + + + VM ids. + + + + Progress object to track the operation completion. + + + + + + + Returns the information about an instance in the Cloud. + + + The id of instance in the Cloud. + + + VirtualSystemDescription object which is describing a machine + + + + Progress object to track the operation completion. + + + + + + + Start an existing instance with passed id. + + + The id of instance in the Cloud. + + + Progress object to track the operation completion. + + + + + + Pause an existing instance with passed id. + + + The id of instance in the Cloud. + + + Progress object to track the operation completion. + + + + + + Terminate an existing instance with passed id. + + + the id of instance in the Cloud. + + + Progress object to track the operation completion. + + + + + + Reset an existing instance with passed id. + + + The id of instance in the Cloud. + + + Progress object to track the operation completion. + + + + + + Create an image in the Cloud. + + + Each parameter in the array must be in the form "name=value". + + + Progress object to track the operation completion. + + + + + + Export an existing VBox image in the Cloud. + + + Reference to the existing VBox image. + + + Each parameter in the array must be in the form "name=value". + + + Progress object to track the operation completion. + + + + + + Import an existing image in the Cloud to the local host. + + + the id of image in the Cloud. + + + Each parameter in the array must be in the form "name=value". + + + Progress object to track the operation completion. + + + + + + Delete an existing image with passed id from the Cloud. + + + The id of image in the Cloud. + + + Progress object to track the operation completion. + + + + + + Returns the information about an image in the Cloud. + + + The id of image in the Cloud. + + + + An array where the image settings or properties is returned. + Each parameter in the array must be in the form "name=value". + + + + + Progress object to track the operation completion. + + + + + + + The id of image in the Cloud. + + + The id of image in the Cloud. + + + Information about the started gateway. + + + Progress object to track the operation completion. + + + + + + The name of tunnelling network to be created in the Cloud. If this parameter + is empty the default value "VirtualBox Tunneling Network" is assumed. + + + The IP address range of tunnelling network to be created in the Cloud. If this + parameter is empty the default value "10.0.0.0/16" is assumed. + + + The name of the operating system to be used for cloud gateway instances. + The default value is "Oracle Linux". + + + The version of the operating system to be used for cloud gateway instances. + The default value is "7.8". + + + The shape of cloud gateway instance. The default value is "VM.Standard2.1". + + + Information about the created network environment. + + + Progress object to track the operation completion. + + + + + + Returns the information about Vnic in the Cloud. + + + The id of vnic in the Cloud. + + + + An array where the Vnic settings/properties is returned. + Each parameter in the array must be in the form "name=value". + + + + + Progress object to track the operation completion. + + + + + + + + Virtual system description to be edited. + + + + + An IForm instance for editing the virtual system description. + + + + + Progress object to track the operation completion. + + + + + + + + + + + + + + Returns the profile name. + + + + + + Returns provider identifier tied with this profile. + + + + + + Returns the value of the cloud profile property with the given name. + + If the requested data @a name does not exist, this function will + succeed and return an empty string in the @a value argument. + + @a name is @c null or empty. + + + Name of the property to get. + + + Current property value. + + + + + + Sets the value of the cloud profile property with the given name. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + + @a name is @c null or empty. + + + Name of the property to set. + + + Property value to set. + + + + + + Returns values for a group of properties in one call. + + The names of the properties to get are specified using the @a names + argument which is a list of comma-separated property names or + an empty string if all properties are to be returned. + Currently the value of this argument is ignored and the method + always returns all existing properties. + + The method returns two arrays, the array of property names corresponding + to the @a names argument and the current values of these properties. + Both arrays have the same number of elements with each element at the + given index in the first array corresponds to an element at the same + index in the second array. + + + + Names of properties to get. + + + + Names of returned properties. + + + Values of returned properties. + + + + + + Updates profile, changing/adding/removing properties. + + The names of the properties to set are passed in the @a names + array along with the new values for them in the @a values array. Both + arrays have the same number of elements with each element at the given + index in the first array corresponding to an element at the same index + in the second array. + + If there is at least one property name in @a names that is not valid, + the method will fail before changing the values of any other properties + from the @a names array. + + Using this method over is preferred if you + need to set several properties at once since it is more efficient. + + Setting the property value to @c null or an empty string is equivalent + to deleting the existing value. + + + Names of properties. + + + Values of set properties. + + + + + + Deletes a profile. + + + + + + Creates a cloud client for this cloud profile. + + + + The cloud client object reference. + + + + + + + + + + + + Returns the long name of the provider. Includes vendor and precise + product name spelled out in the preferred way. + + + + Returns the short name of the provider. Less than 8 ASCII chars, + using acronyms. No vendor name, but can contain a hint if it's a 3rd + party implementation for this cloud provider, to keep it unique. + + + + Returns the UUID of this cloud provider. + + + + + + Returns all profiles for this cloud provider. + + + + Returns all profile names for this cloud provider. + + + + + Returns the supported property names. + + + + + + Property name. + + + Property description. + + + + + + Creates a new profile. + + + + The profile name. Must not exist, otherwise an error is raised. + + + + Names of properties. + + + Values of set properties. + + + + + + Import the profiles from the original source + + + + + + Restores the old local profiles if they exist + + + + + + Saves the local profiles + + + + + + + + + + + The caller requests the cloud provider to cease operation. Should + return an error if this is currently not possible (due to ongoing + cloud activity, possibly by a different API client). However, this + must not wait for the completion for a larger amount of time (ideally + stays below a second of execution time). If this succeeds it should + leave the cloud provider in a state which does not allow starting new + operations. + + + + + + + + + + Returns all supported cloud providers. + + + + + + + + + + + + + + + + + + + + + + Each individual provider that is installed or uninstalled is + reported as an . When + the batch is done this event is sent and listerns can get the + new list. + + + + + + + A cloud provider was installed or uninstalled. + See also . + + + + + + + + A cloud provider is about to be uninstalled. + Unlike this one is + waitable and is sent before an attempt is made to + uninstall a provider. Listerns should release references to the + provider and related objects if they have any, or the + uninstallation of the provider is going to fail because it's + still in use. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Implemented by the VirtualBox class factory and registered with VBoxSDS + so it can retrieve IVirtualBox on behalf of other VBoxSVCs. + + + + Gets an IUnknown interface to the VirtualBox object in the VBoxSVC process. + + Where to return the IUnknown interface. + + + + + + + + + + The IVirtualBoxSDS interface represents the system-wide directory service + helper. + + It exists only on Windows host, and its purpose is to work around design + flaws in Microsoft's (D)COM, in particular the local server instantiation + behavior. + + + + + Registers a VBoxSVC instance with VBoxSDS. If the caller is not running + in a Windows 0 session, the method attempts to run VBoxSVC in that + session. + + The caller is not running in a Windows session 0 and no VBoxSVC + is registered. VBoxSVC registration begins in Windows session 0. + You should call this method again later. + + + + Interface implemented by the VirtualBox class factory. + + + The process ID of the VBoxSVC instance. + + + If there is already an VBoxSVC for this user, the an IUnknown + interface to its VirtualBox object is returned here, otherwise it + is set to NULL. + + + + + Registers a VBoxSVC instance with the SDS. + + Same as specified during registration. + + + The process ID of the VBoxSVC instance (same as during registration). + + + + + + Spawns a new process that will execute the virtual machine in the interactive + windows session of calling user. Any additional checks are performed by created + process itself + + If launching the VM succeeds, the new VM process will create its own session + and write-lock the machine for it, preventing conflicting changes from other + processes. If the machine is already locked (because it is already running or + because another session has a write lock), launching the VM process will therefore + fail. Reversely, future attempts to obtain a write lock will also fail while the + machine is running. + + Launching a VM process can take some time (a new VM is started in a new process, + for which memory and other resources need to be set up) but the method does + not wait for completion and just returns the PID of created process. + + + Some of the parameters are invalid. + + + Launching process for machine failed. + + + + + The name or id of the machine the VM will start for. + + + + + The comment for VM. + + + + + Front-end to use for the new VM process. The following are currently supported: +
    +
  • "gui": VirtualBox Qt GUI front-end
    • +
  • "headless": VBoxHeadless (VRDE Server) front-end
    • +
  • "sdl": VirtualBox SDL front-end
    • +
  • "": use the per-VM default frontend if set, otherwise + the global default defined in the system properties. If neither + are set, the API will launch a "gui" session, which may + fail if there is no windowing environment available. See + and + .
    • +
+ + + + + The list of putenv-style changes to the VM process environment. + See for details. + + + + + Additional command line options to pass to the VM process. + + + + + Windows session where the VM process should be launched. + + + + The PID of created process. + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3