diff options
Diffstat (limited to 'src/VBox/Main/idl')
| -rw-r--r-- | src/VBox/Main/idl/VirtualBox.dtd | 55 | ||||
| -rw-r--r-- | src/VBox/Main/idl/VirtualBox.xidl | 3858 | ||||
| -rw-r--r-- | src/VBox/Main/idl/apiwrap-server.xsl | 1394 | ||||
| -rw-r--r-- | src/VBox/Main/idl/comimpl.xsl | 36 | ||||
| -rw-r--r-- | src/VBox/Main/idl/docstrip.xsl | 2 | ||||
| -rw-r--r-- | src/VBox/Main/idl/doxygen.xsl | 2 | ||||
| -rw-r--r-- | src/VBox/Main/idl/midl.xsl | 3 | ||||
| -rw-r--r-- | src/VBox/Main/idl/typemap-shared.inc.xsl | 360 | ||||
| -rw-r--r-- | src/VBox/Main/idl/xpidl.xsl | 45 | ||||
| -rw-r--r-- | src/VBox/Main/idl/xpidl_iid.xsl | 154 |
10 files changed, 4936 insertions, 973 deletions
diff --git a/src/VBox/Main/idl/VirtualBox.dtd b/src/VBox/Main/idl/VirtualBox.dtd index a62540e0..0af06e2c 100644 --- a/src/VBox/Main/idl/VirtualBox.dtd +++ b/src/VBox/Main/idl/VirtualBox.dtd @@ -5,7 +5,7 @@ It is still the only sort-of-documentation available about what is valid XIDL syntax. - Copyright (C) 2008-2010 Oracle Corporation + Copyright (C) 2008-2013 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; @@ -15,26 +15,32 @@ VirtualBox OSE distribution. VirtualBox OSE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. --> -<!DOCTYPE idl [ - <!ELEMENT idl (if|module)*> <!-- done --> + <!ELEMENT idl (desc|if|library)*> <!-- done --> <!ELEMENT if ANY> <!ATTLIST if target (midl|xpidl|wsdl) #REQUIRED> <!-- done --> - <!ELEMENT ifnot ANY> - <!ATTLIST if target (midl|xpidl|wsdl) #REQUIRED> <!-- done --> <!ELEMENT cpp ANY> <!ATTLIST cpp line CDATA #IMPLIED> <!-- done --> - <!ELEMENT module (enum|interface|class|collection|if|enumerator)*> <!-- done --> + <!ELEMENT library (descGroup|if|result|enum|interface|module)*> + <!ATTLIST library name CDATA #REQUIRED> + <!ATTLIST library uuid CDATA #REQUIRED> + <!ATTLIST library version CDATA #REQUIRED> + <!ATTLIST library desc CDATA #REQUIRED> + <!ATTLIST library appUuid CDATA #REQUIRED> + <!ATTLIST library supportsErrorInfo CDATA #REQUIRED> + <!ELEMENT result (#PCDATA|desc|link)*> <!-- done --> + <!ATTLIST result name CDATA #REQUIRED> + <!ATTLIST result value CDATA #IMPLIED> + <!ELEMENT module (class)*> <!-- done --> <!ATTLIST module name CDATA #REQUIRED> - <!ATTLIST module uuid CDATA #REQUIRED> - <!ATTLIST module version CDATA #REQUIRED> - <!ATTLIST module desc CDATA #REQUIRED> - <!ATTLIST module supportsErrorInfo (yes|no) #REQUIRED> + <!ATTLIST module context CDATA #REQUIRED> + <!ATTLIST module threadingModel CDATA #IMPLIED> <!ELEMENT enum (desc?, const+)> <!-- done --> <!ATTLIST enum name CDATA #REQUIRED> <!ATTLIST enum uuid CDATA #REQUIRED> <!ELEMENT const (desc?)> <!-- done --> <!ATTLIST const name CDATA #REQUIRED> <!ATTLIST const value CDATA #REQUIRED> + <!ATTLIST const wsmap (managed|suppress) "managed"> <!ELEMENT interface (desc?, (attribute|method|class|if)*)> <!-- done --> <!ATTLIST interface name CDATA #REQUIRED> <!ATTLIST interface extends CDATA #IMPLIED> @@ -42,7 +48,7 @@ <!ATTLIST interface supportsErrorInfo (yes|no) #IMPLIED> <!ATTLIST interface default (yes|no) "no"> <!ATTLIST interface internal (yes|no) "no"> - <!ATTLIST interface wsmap (fail|none|uuid|wstring|global|struct|managed) "fail"> + <!ATTLIST interface wsmap (fail|global|struct|managed|suppress) "fail"> <!-- wsmap specifies how this interface is mapped to the web services API (WSDL). One of the following must be specified: fail: the default value, for which vboxweb.xsl will raise an error and die. @@ -56,42 +62,59 @@ to "hardcoded", then no automatic C++ code should be generated. This is done for webservice APIs that have no counterpart in COM and are hard-coded in the webservice server, such as IManagedObjectReference and ISessionManager. --> - <!ELEMENT class (interface)> <!-- done (ignoring) --> + <!ATTLIST interface autogen CDATA #IMPLIED> + <!-- autogen names the style of code auto-generation for this + interface (currently only VBoxEvent). --> + <!ATTLIST interface id CDATA #IMPLIED> + <!-- id is only relevant for event interfaces, and specifies + which const name will be generated. --> + <!ATTLIST interface waitable (yes|no) "no"> + <!-- waitable is only relevant for event interfaces, and + specifies that this event can be waited for. --> + <!ELEMENT class (interface)> <!-- done --> <!ATTLIST class name CDATA #REQUIRED> <!ATTLIST class uuid CDATA #REQUIRED> + <!ATTLIST class namespace CDATA #REQUIRED> <!ELEMENT attribute (desc?)> <!-- done --> <!ATTLIST attribute name CDATA #REQUIRED> <!ATTLIST attribute type CDATA #REQUIRED> + <!ATTLIST attribute default CDATA #IMPLIED> <!ATTLIST attribute readonly (yes|no) "no"> <!ATTLIST attribute mod (ptr|string) #IMPLIED> <!ATTLIST attribute internal (yes|no) "no"> <!ATTLIST attribute safearray (yes|no) "no"> - <!ELEMENT method (desc?,param*, note*)> <!-- done --> + <!ATTLIST attribute wsmap (managed|suppress) "managed"> + <!ELEMENT method (desc?,param*,result*)> <!-- done --> <!ATTLIST method name CDATA #REQUIRED> <!ATTLIST method const CDATA "no"> <!ATTLIST method internal (yes|no) "no"> + <!ATTLIST method wsmap (managed|suppress) "managed"> <!ELEMENT param (desc?)> <!-- done --> <!ATTLIST param name CDATA #REQUIRED> <!ATTLIST param type CDATA #REQUIRED> <!ATTLIST param dir (in|out|return) #REQUIRED> <!ATTLIST param mod (ptr|string) #IMPLIED> <!ATTLIST param safearray (yes|no) "no"> - <!ELEMENT desc (#PCDATA|link|note|see|b|tt|i|pre|p|ul|h3|table)*> <!-- done (ignoring) --> + <!ELEMENT descGroup (desc)*> <!-- done (ignoring, butt-ugly hack, improper nesting enforced all over the .xsl files!) --> + <!ATTLIST descGroup id CDATA #IMPLIED> + <!ATTLIST descGroup title CDATA #IMPLIED> + <!ELEMENT desc (#PCDATA|link|note|see|b|tt|i|pre|para|ul|ol|h3|table|result)*> <!-- done (ignoring) --> <!-- the following only appear within descriptions --> <!ELEMENT link (#PCDATA)> <!ATTLIST link to CDATA #REQUIRED> <!ELEMENT h3 ANY> - <!ELEMENT p ANY> + <!ELEMENT para ANY> <!ELEMENT b ANY> <!ELEMENT i ANY> <!ELEMENT ul (#PCDATA|li)*> + <!ELEMENT ol (#PCDATA|li)*> <!ELEMENT li ANY> <!ELEMENT pre ANY> <!ELEMENT tt ANY> <!ELEMENT see (#PCDATA|link)*> <!ELEMENT note ANY> + <!ATTLIST note internal (yes|no) "no"> <!ELEMENT table (tr)+> <!ELEMENT tr (td|th)+> <!ELEMENT th ANY> <!ELEMENT td ANY> -]> diff --git a/src/VBox/Main/idl/VirtualBox.xidl b/src/VBox/Main/idl/VirtualBox.xidl index aa096271..6f2739c1 100644 --- a/src/VBox/Main/idl/VirtualBox.xidl +++ b/src/VBox/Main/idl/VirtualBox.xidl @@ -1,8 +1,8 @@ -<?xml version="1.0" encoding="utf-8"?> +<?xml version="1.0" encoding="utf-8"?> <!-- - Copyright (C) 2006-2012 Oracle Corporation + Copyright (C) 2006-2014 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; @@ -118,7 +118,7 @@ <if target="midl"> <cpp line="enum {"/> <cpp line=" kTypeLibraryMajorVersion = 1,"/> - <cpp line=" kTypeLibraryMinorVersion = 0"/> + <cpp line=" kTypeLibraryMinorVersion = 3"/> <cpp line="};"/> </if> @@ -127,10 +127,14 @@ <cpp> /* 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_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 @@ -165,6 +169,38 @@ 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) \ @@ -232,9 +268,13 @@ </cpp> </if> +<!-- + Note!! Don't forget to update the python bindings (++) when changing the + UUID or version!! +--> <library name="VirtualBox" - uuid="46137EEC-703B-4fe5-AFD4-7C9BBBBA0259" + uuid="d7569351-1750-46f0-936e-bd127d5bc264" version="1.3" desc="VirtualBox Type Library" appUuid="819B4D85-9CEE-493C-B6FC-64FFE759B3C9" @@ -393,7 +433,7 @@ <enum name="SettingsVersion" - uuid="52bd6f5f-1adb-4493-975d-581a9c4b803f" + uuid="d5b15ca7-3de7-46b2-a63a-ddcce42bfa3f" > <desc> Settings version of VirtualBox settings files. This is written to @@ -401,35 +441,35 @@ file XML and indicates which VirtualBox version wrote the file. </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>Null value, indicates invalid version.</desc> </const> - <const name="v1_0" value="1"> + <const name="v1_0" value="1"> <desc>Legacy settings version, not currently supported.</desc> </const> - <const name="v1_1" value="2"> + <const name="v1_1" value="2"> <desc>Legacy settings version, not currently supported.</desc> </const> - <const name="v1_2" value="3"> + <const name="v1_2" value="3"> <desc>Legacy settings version, not currently supported.</desc> </const> - <const name="v1_3pre" value="4"> + <const name="v1_3pre" value="4"> <desc>Legacy settings version, not currently supported.</desc> </const> - <const name="v1_3" value="5"> + <const name="v1_3" value="5"> <desc>Settings version "1.3", written by VirtualBox 2.0.12.</desc> <!-- Machine XML: Capitalization of Uart, Lpt elements and many attributes changed. --> </const> - <const name="v1_4" value="6"> + <const name="v1_4" value="6"> <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc> <!-- VirtualBox.xml: big DiskRegistry -> MediaRegistry revamp, various HardDisk types merged (was VirtualDiskImage, VMDKImage, VHDImage, ISCSIHardDisk, CustomHardDisk, DiffHardDisk) --> </const> - <const name="v1_5" value="7"> + <const name="v1_5" value="7"> <desc>Intermediate settings version, understood by VirtualBox 2.1.x.</desc> <!-- 2008-09-04: 2.0.0 released @@ -442,7 +482,7 @@ Machine/Hardware/CPU/CPUCount/@count changed to CPU/@count --> </const> - <const name="v1_6" value="8"> + <const name="v1_6" value="8"> <desc>Settings version "1.6", written by VirtualBox 2.1.4 (at least).</desc> <!-- 2008-12-17: 2.1.0 released @@ -451,7 +491,7 @@ Machine changes: remove all Machine/Hardware/Network/Adapter/HostInterface[@TAPSetup or @TAPTerminate]/ attributes (done) --> </const> - <const name="v1_7" value="9"> + <const name="v1_7" value="9"> <desc>Settings version "1.7", written by VirtualBox 2.2.x and 3.0.x.</desc> <!-- 2008-12-17: 2.1.0 released @@ -461,48 +501,54 @@ Machine changes: HardDiskAttachments is now StorageControllers (done) --> </const> - <const name="v1_8" value="10"> + <const name="v1_8" value="10"> <desc>Intermediate settings version "1.8", understood by VirtualBox 3.1.x.</desc> <!-- Machine additions: Display/@accelerate2DVideo (done) --> </const> - <const name="v1_9" value="11"> + <const name="v1_9" value="11"> <desc>Settings version "1.9", written by VirtualBox 3.1.x.</desc> <!-- The big storage controller / DVD / Floppy rework (done) --> </const> - <const name="v1_10" value="12"> + <const name="v1_10" value="12"> <desc>Settings version "1.10", written by VirtualBox 3.2.x.</desc> <!-- Machine changes: RTC localOrUTC (done) CPU hot-plug support --> </const> - <const name="v1_11" value="13"> + <const name="v1_11" value="13"> <desc>Settings version "1.11", written by VirtualBox 4.0.x.</desc> <!-- Machine changes: HD Audio controller, per-machine disk registries, /@format attribute for DVD and floppy images. --> </const> - <const name="v1_12" value="14"> + <const name="v1_12" value="14"> <desc>Settings version "1.12", written by VirtualBox 4.1.x.</desc> <!-- Machine changes: raw PCI device attachment; NetworkAdapter changes: bandwidth group. --> </const> - <const name="v1_13" value="15"> + <const name="v1_13" value="15"> <desc>Settings version "1.13", written by VirtualBox 4.2.x.</desc> <!-- Machine changes: tracing config, groups, autostart; NetworkAdapter changes: unit for bandwidth group limits. --> </const> + <const name="v1_14" value="16"> + <desc>Settings version "1.14", written by VirtualBox 4.3.x.</desc> + <!-- + Machine changes: default frontend, USB rework. + --> + </const> - <const name="Future" value="99999"> + <const name="Future" value="99999"> <desc>Settings version greater than "1.13", written by a future VirtualBox version.</desc> </const> </enum> @@ -515,8 +561,8 @@ Access mode for opening files. </desc> - <const name="ReadOnly" value="1"/> - <const name="ReadWrite" value="2"/> + <const name="ReadOnly" value="1"/> + <const name="ReadWrite" value="2"/> </enum> <enum @@ -648,37 +694,37 @@ </note> </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>Null value (never used by the API).</desc> </const> - <const name="PoweredOff" value="1"> + <const name="PoweredOff" value="1"> <desc> The machine is not running and has no saved execution state; it has either never been started or been shut down successfully. </desc> </const> - <const name="Saved" value="2"> + <const name="Saved" value="2"> <desc> 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. </desc> </const> - <const name="Teleported" value="3"> + <const name="Teleported" value="3"> <desc> The machine was teleported to a different host (or process) and then - powered off. Take care when powering it on again may corrupt resources + powered off. Take care when powering it on again may corrupt resources it shares with the teleportation target (e.g. disk and network). </desc> </const> - <const name="Aborted" value="4"> + <const name="Aborted" value="4"> <desc> 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. </desc> </const> - <const name="Running" value="5"> + <const name="Running" value="5"> <desc> The machine is currently being executed. <note internal="yes"> @@ -689,7 +735,7 @@ </note> </desc> </const> - <const name="Paused" value="6"> + <const name="Paused" value="6"> <desc> Execution of the machine has been paused. <note internal="yes"> @@ -700,7 +746,7 @@ </note> </desc> </const> - <const name="Stuck" value="7"> + <const name="Stuck" value="7"> <desc> Execution of the machine has reached the "Guru Meditation" condition. This indicates a severe error in the hypervisor itself. @@ -711,7 +757,7 @@ </note> </desc> </const> - <const name="Teleporting" value="8"> + <const name="Teleporting" value="8"> <desc> 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 @@ -719,81 +765,81 @@ possible to resume it again unless the teleportation fails. </desc> </const> - <const name="LiveSnapshotting" value="9"> + <const name="LiveSnapshotting" value="9"> <desc> - A live snapshot is being taken. The machine is running normally, but - some of the runtime configuration options are inaccessible. Also, if + 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 Saving and it will not be resume the execution until the snapshot operation has completed. </desc> </const> - <const name="Starting" value="10"> + <const name="Starting" value="10"> <desc> Machine is being started after powering it on from a zero execution state. </desc> </const> - <const name="Stopping" value="11"> + <const name="Stopping" value="11"> <desc> Machine is being normally stopped powering it off, or after the guest OS has initiated a shutdown sequence. </desc> </const> - <const name="Saving" value="12"> + <const name="Saving" value="12"> <desc> Machine is saving its execution state to a file, or an online snapshot of the machine is being taken. </desc> </const> - <const name="Restoring" value="13"> + <const name="Restoring" value="13"> <desc> Execution state of the machine is being restored from a file after powering it on from the saved execution state. </desc> </const> - <const name="TeleportingPausedVM" value="14"> + <const name="TeleportingPausedVM" value="14"> <desc> The machine is being teleported to another host or process, but it is - not running. This is the paused variant of the + not running. This is the paused variant of the @c state. </desc> </const> - <const name="TeleportingIn" value="15"> + <const name="TeleportingIn" value="15"> <desc> Teleporting the machine state in from another host or process. </desc> </const> - <const name="FaultTolerantSyncing" value="16"> + <const name="FaultTolerantSyncing" value="16"> <desc> The machine is being synced with a fault tolerant VM running elsewhere. </desc> </const> - <const name="DeletingSnapshotOnline" value="17"> + <const name="DeletingSnapshotOnline" value="17"> <desc> Like @c DeletingSnapshot, but the merging of media is ongoing in the background while the machine is running. </desc> </const> - <const name="DeletingSnapshotPaused" value="18"> + <const name="DeletingSnapshotPaused" value="18"> <desc> Like @c DeletingSnapshotOnline, but the machine was paused when the merging of differencing media was started. </desc> </const> - <const name="RestoringSnapshot" value="19"> + <const name="RestoringSnapshot" value="19"> <desc> A machine snapshot is being restored; this typically does not take long. </desc> </const> - <const name="DeletingSnapshot" value="20"> + <const name="DeletingSnapshot" value="20"> <desc> 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. </desc> </const> - <const name="SettingUp" value="21"> + <const name="SettingUp" value="21"> <desc> Lengthy setup operation is in progress. </desc> @@ -804,7 +850,7 @@ Pseudo-state: first online state (for use in relational expressions). </desc> </const> - <const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused --> + <const name="LastOnline" value="18" wsmap="suppress"> <!-- DeletingSnapshotPaused --> <desc> Pseudo-state: last online state (for use in relational expressions). </desc> @@ -815,7 +861,7 @@ Pseudo-state: first transient state (for use in relational expressions). </desc> </const> - <const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp --> + <const name="LastTransient" value="21" wsmap="suppress"> <!-- SettingUp --> <desc> Pseudo-state: last transient state (for use in relational expressions). </desc> @@ -874,7 +920,7 @@ <enum name="CPUPropertyType" - uuid="24d356a6-2f45-4abd-b977-1cbe9c4701f5" + uuid="52bc41f4-a279-45da-88ab-3a1d86fb73eb" > <desc> Virtual CPU property type. This enumeration represents possible values of the @@ -896,50 +942,60 @@ teleporting between host systems that differ significantly. </desc> </const> + <const name="LongMode" value="3"> + <desc> + This setting determines whether VirtualBox will advertise long mode + (i.e. 64-bit guest support) and let the guest enter it. + </desc> + </const> + <const name="TripleFaultReset" value="4"> + <desc> + 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 and continue execution. + </desc> + </const> </enum> <enum name="HWVirtExPropertyType" - uuid="ce81dfdd-d2b8-4a90-bbea-40ee8b7ffcee" + uuid="411ad0ea-aeeb-44cb-9d03-1624d0d025ac" > <desc> Hardware virtualization property type. This enumeration represents possible values for the <link to="IMachine::getHWVirtExProperty"/> and <link to="IMachine::setHWVirtExProperty"/> methods. </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>Null value (never used by the API).</desc> </const> - <const name="Enabled" value="1"> + <const name="Enabled" value="1"> <desc> Whether hardware virtualization (VT-x/AMD-V) is enabled at all. If such extensions are not available, they will not be used. </desc> </const> - <const name="Exclusive" value="2"> + <const name="VPID" value="2"> <desc> - Whether hardware virtualization is used exclusively by VirtualBox. When enabled, - VirtualBox assumes it can acquire full and exclusive access to the VT-x or AMD-V - feature of the host. To share these with other hypervisors, you must disable this property. + Whether VT-x VPID is enabled. If this extension is not available, it will not be used. </desc> </const> - <const name="VPID" value="3"> + <const name="NestedPaging" value="3"> <desc> - 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. </desc> </const> - <const name="NestedPaging" value="4"> + <const name="UnrestrictedExecution" value="4"> <desc> - 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. </desc> </const> - <const name="LargePages" value="5"> + <const name="LargePages" value="5"> <desc> - Whether large page allocation is enabled; requires nested paging and a 64 bits host. + Whether large page allocation is enabled; requires nested paging and a 64-bit host. </desc> </const> - <const name="Force" value="6"> + <const name="Force" value="6"> <desc> 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. @@ -973,10 +1029,16 @@ Used with <link to="IMachine::lockMachine" />. </desc> <const name="Write" value="2"> - <desc>Lock the machine for writing.</desc> + <desc>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.</desc> </const> <const name="Shared" value="1"> - <desc>Request only a shared read lock for remote-controlling the machine.</desc> + <desc>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.</desc> </const> <const name="VM" value="3"> <desc>Lock the machine for writing, and create objects necessary for @@ -1128,10 +1190,10 @@ CPU features. </desc> - <const name="HWVirtEx" value="0"/> - <const name="PAE" value="1"/> - <const name="LongMode" value="2"/> - <const name="NestedPaging" value="3"/> + <const name="HWVirtEx" value="0"/> + <const name="PAE" value="1"/> + <const name="LongMode" value="2"/> + <const name="NestedPaging" value="3"/> </enum> <enum @@ -1141,45 +1203,55 @@ <desc> Firmware type. </desc> - <const name="BIOS" value="1"> + <const name="BIOS" value="1"> <desc>BIOS Firmware.</desc> </const> - <const name="EFI" value="2"> + <const name="EFI" value="2"> <desc>EFI Firmware, bitness detected basing on OS type.</desc> </const> - <const name="EFI32" value="3"> - <desc>Efi firmware, 32-bit.</desc> + <const name="EFI32" value="3"> + <desc>EFI firmware, 32-bit.</desc> </const> - <const name="EFI64" value="4"> - <desc>Efi firmware, 64-bit.</desc> + <const name="EFI64" value="4"> + <desc>EFI firmware, 64-bit.</desc> </const> - <const name="EFIDUAL" value="5"> - <desc>Efi firmware, combined 32 and 64-bit.</desc> + <const name="EFIDUAL" value="5"> + <desc>EFI firmware, combined 32 and 64-bit.</desc> </const> </enum> <enum name="PointingHIDType" - uuid="e44b2f7b-72ba-44fb-9e53-2186014f0d17" + uuid="19964e93-0050-45c4-9382-a7bccc53e666" > <desc> Type of pointing device used in a virtual machine. </desc> - <const name="None" value="1"> + <const name="None" value="1"> <desc>No mouse.</desc> </const> - <const name="PS2Mouse" value="2"> + <const name="PS2Mouse" value="2"> <desc>PS/2 auxiliary device, a.k.a. mouse.</desc> </const> - <const name="USBMouse" value="3"> + <const name="USBMouse" value="3"> <desc>USB mouse (relative pointer).</desc> </const> - <const name="USBTablet" value="4"> - <desc>USB tablet (absolute pointer).</desc> + <const name="USBTablet" value="4"> + <desc> + USB tablet (absolute pointer). Also enables a relative USB mouse in + addition. + </desc> </const> - <const name="ComboMouse" value="5"> - <desc>Combined device, working as PS/2 or USB mouse, depending on guest behavior. - Using of such device can have negative performance implications. </desc> + <const name="ComboMouse" value="5"> + <desc> + Combined device, working as PS/2 or USB mouse, depending on guest + behavior. Using this device can have negative performance implications. + </desc> + </const> + <const name="USBMultiTouch" value="6"> + <desc> + USB multi-touch device. Also enables the USB tablet and mouse devices. + </desc> </const> </enum> @@ -1201,7 +1273,7 @@ </const> <const name="ComboKeyboard" value="4"> <desc>Combined device, working as PS/2 or USB keyboard, depending on guest behavior. - Using of such device can have negative performance implications. </desc> + Using of such device can have negative performance implications.</desc> </const> </enum> @@ -1212,7 +1284,7 @@ <interface name="IVirtualBoxErrorInfo" extends="$errorinfo" - uuid="f91e6e91-49e1-4fd2-b21e-269003350d06" + uuid="c1bcc6d5-7966-481d-ab0b-d0ed73e28135" supportsErrorInfo="no" wsmap="managed" > @@ -1262,6 +1334,13 @@ </desc> </attribute> + <attribute name="resultDetail" type="long" readonly="yes"> + <desc> + Optional result data of this error. This will vary depending on the + actual error usage. By default this attribute is not being used. + </desc> + </attribute> + <attribute name="interfaceID" type="uuid" mod="string" readonly="yes"> <desc> UUID of the interface that defined the error. @@ -1310,18 +1389,193 @@ ///////////////////////////////////////////////////////////////////////// --> + <interface name="INATNetwork" extends="$unknown" + uuid="a63c75da-4c99-4e9d-8351-eb73651c18cc" + wsmap="managed"> + <attribute name="networkName" type="wstring"> + <desc> + 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. + </desc> + </attribute> + <attribute name="enabled" type="boolean"/> + <attribute name="network" type="wstring"> + <desc> + 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). + </desc> + </attribute> + <attribute name="gateway" type="wstring" readonly="yes"> + <desc> + This attribute is read-only. It's recalculated on changing + network attribute (low address of network + 1). + </desc> + </attribute> + <attribute name="IPv6Enabled" type="boolean"> + <desc> + This attribute define whether gateway will support IPv6 or not. + </desc> + </attribute> + <attribute name="IPv6Prefix" type="wstring"> + <desc> + This a CIDR IPv6 defining prefix for link-local addresses + autoconfiguration within network. Note: ignored if attribute + IPv6Enabled is false. + </desc> + </attribute> + <attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean"/> + <attribute name="needDhcpServer" type="boolean"/> + <attribute name="eventSource" type="IEventSource" readonly="yes"/> + <attribute name="portForwardRules4" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of NAT port-forwarding rules in string representation, + in the following format: + "name:protocolid:[host ip]:host port:[guest ip]:guest port". + </desc> + </attribute> + <attribute name="localMappings" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of mappings (address,offset),e.g. ("127.0.1.1=4") maps 127.0.1.1 to networkid + 4. + </desc> + </attribute> + + <method name="addLocalMapping"> + <desc> + </desc> + <param name="hostid" type="wstring" dir="in"/> + <param name="offset" type="long" dir="in"/> + </method> + + <attribute name="loopbackIp6" type="long"> + <desc>Offset in ipv6 network from network id for address mapped into loopback6 interface of the host. + </desc> + </attribute> + + <attribute name="portForwardRules6" type="wstring" readonly="yes" safearray="yes"> + <desc>Array of NAT port-forwarding rules in string representation, in the + following format: "name:protocolid:[host ip]:host port:[guest ip]:guest port". + </desc> + </attribute> + <method name="addPortForwardRule"> + <param name="isIpv6" type="boolean" dir="in"/> + <param name="ruleName" type="wstring" dir="in"/> + <param name="proto" type="NATProtocol" dir="in"> + <desc>Protocol handled with the rule.</desc> + </param> + <param name="hostIP" type="wstring" dir="in"> + <desc>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. + </desc> + </param> + <param name="hostPort" type="unsigned short" dir="in"> + <desc>The port number to listen on.</desc> + </param> + <param name="guestIP" type="wstring" dir="in"> + <desc>The IP address of the guest which the NAT engine will forward + matching packets to. An empty IP address is not acceptable.</desc> + </param> + <param name="guestPort" type="unsigned short" dir="in"> + <desc>The port number to forward.</desc> + </param> + </method> + <method name="removePortForwardRule"> + <param name="iSipv6" type="boolean" dir="in"/> + <param name="ruleName" type="wstring" dir="in"/> + </method> + <method name="start"> + <param name="trunkType" type="wstring" dir="in"> + <desc> + Type of internal network trunk. + </desc> + </param> + </method> + <method name="stop"/> + </interface> + + <enum + name="DhcpOpt" + uuid="40d99bd3-3ece-44d2-a07e-1085fe9c4f0b"> + <const name="SubnetMask" value="1"/> + <const name="TimeOffset" value="2"/> + <const name="Router" value="3"/> + <const name="TimeServer" value="4"/> + <const name="NameServer" value="5"/> + <const name="DomainNameServer" value="6"/> + <const name="LogServer" value="7"/> + <const name="Cookie" value="8"/> + <const name="LPRServer" value="9"/> + <const name="ImpressServer" value="10"/> + <const name="ResourseLocationServer" value="11"/> + <const name="HostName" value="12"/> + <const name="BootFileSize" value="13"/> + <const name="MeritDumpFile" value="14"/> + <const name="DomainName" value="15"/> + <const name="SwapServer" value="16"/> + <const name="RootPath" value="17"/> + <const name="ExtensionPath" value="18"/> + <const name="IPForwardingEnableDisable" value="19"/> + <const name="NonLocalSourceRoutingEnableDisable" value="20"/> + <const name="PolicyFilter" value="21"/> + <const name="MaximumDatagramReassemblySize" value="22"/> + <const name="DefaultIPTime2Live" value="23"/> + <const name="PathMTUAgingTimeout" value="24"/> + <const name="IPLayerParametersPerInterface" value="25"/> + <const name="InterfaceMTU" value="26"/> + <const name="AllSubnetsAreLocal" value="27"/> + <const name="BroadcastAddress" value="28"/> + <const name="PerformMaskDiscovery" value="29"/> + <const name="MaskSupplier" value="30"/> + <const name="PerformRouteDiscovery" value="31"/> + <const name="RouterSolicitationAddress" value="32"/> + <const name="StaticRoute" value="33"/> + <const name="TrailerEncapsulation" value="34"/> + <const name="ARPCacheTimeout" value="35"/> + <const name="EthernetEncapsulation" value="36"/> + <const name="TCPDefaultTTL" value="37"/> + <const name="TCPKeepAliveInterval" value="38"/> + <const name="TCPKeepAliveGarbage" value="39"/> + <const name="NetworkInformationServiceDomain" value="40"/> + <const name="NetworkInformationServiceServers" value="41"/> + <const name="NetworkTimeProtocolServers" value="42"/> + <const name="VendorSpecificInformation" value="43"/> + <const name="Option_44" value="44"/> + <const name="Option_45" value="45"/> + <const name="Option_46" value="46"/> + <const name="Option_47" value="47"/> + <const name="Option_48" value="48"/> + <const name="Option_49" value="49"/> + <const name="IPAddressLeaseTime" value="51"/> + <const name="Option_64" value="64"/> + <const name="Option_65" value="65"/> + <const name="TFTPServerName" value="66"/> + <const name="BootfileName" value="67"/> + <const name="Option_68" value="68"/> + <const name="Option_69" value="69"/> + <const name="Option_70" value="70"/> + <const name="Option_71" value="71"/> + <const name="Option_72" value="72"/> + <const name="Option_73" value="73"/> + <const name="Option_74" value="74"/> + <const name="Option_75" value="75"/> + <const name="Option_119" value="119"/> + </enum> + <interface name="IDHCPServer" extends="$unknown" - uuid="6cfe387c-74fb-4ca7-bff6-973bec8af7a3" + uuid="ff0774c5-1f62-4bc3-919c-7fc942bf1d25" wsmap="managed" > <desc> - The IDHCPServer interface represents the vbox DHCP server configuration. + The IDHCPServer interface represents the VirtualBox DHCP server configuration. To enumerate all the DHCP servers on the host, use the <link to="IVirtualBox::DHCPServers"/> attribute. </desc> - + <!-- We want to keep our "real" servers updated about configuration changes --> + <attribute name="eventSource" type="IEventSource" readonly="yes"/> <attribute name="enabled" type="boolean"> <desc> specifies if the DHCP server is enabled @@ -1358,6 +1612,62 @@ </desc> </attribute> + <method name="addGlobalOption"> + <param name="option" type="DhcpOpt" dir="in"/> + <param name="value" type="wstring" dir="in" /> + </method> + + <!-- string in format: "option_id:value" --> + <attribute name="globalOptions" type="wstring" safearray="yes" readonly="yes"/> + + <!-- string in format: "[vm name]:slot" --> + <attribute name="vmConfigs" type="wstring" safearray="yes" readonly="yes"/> + + <!-- VM-slot settings + It's corresponds to dhcpd.conf entries, like: + + host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } + + - in Main we can match (vm name, slot) to ethernet address + that why it's easy to configure dhcp server in such way, + then ask user to to enter valid name, + + - mac address might change because of adapter type (e1k <-> pcnet) or because + of import/export + + - it's easy to provide vm-name.rom in boot filename VM with network boot. + + XXX: do we need classic getOptionValueByMAC? + + XML: O-o-oh, this settings are per VM, so perhaps they should be stored in + VM configuration files. And we haven't got the attachment type for + NATNetwork. + --> + <method name="addVmSlotOption"> + <param name="vmname" type="wstring" dir="in"/> + <param name="slot" type="long" dir="in"/> + <param name="option" type="DhcpOpt" dir="in"/> + <param name="value" type="wstring" dir="in" /> + </method> + + <method name="removeVmSlotOptions"> + <param name="vmname" type="wstring" dir="in"/> + <param name="slot" type="long" dir="in"/> + </method> + + <!-- returns array of strings in format: "option_id:value" for a given pair (vm, slot) --> + <method name="getVmSlotOptions"> + <param name="vmname" type="wstring" dir="in"/> + <param name="slot" type="long" dir="in"/> + <param name="option" type="wstring" safearray="yes" dir="return"/> + </method> + + <!-- Returns options by MAC address --> + <method name="getMacOptions"> + <param name="mac" type="wstring" dir="in"/> + <param name="option" type="wstring" safearray="yes" dir="return"/> + </method> + <method name="setConfiguration"> <desc> configures the server @@ -1423,7 +1733,7 @@ <interface name="IVirtualBox" extends="$unknown" - uuid="3b2f08eb-b810-4715-bee0-bb06b9880ad2" + uuid="fafa4e17-1ee2-4905-a10e-fe7c18bf5554" wsmap="managed" > <desc> @@ -1448,8 +1758,8 @@ 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 + 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. </desc> </attribute> @@ -1591,6 +1901,8 @@ DHCP servers. </desc> </attribute> + <!-- Array of NAT networks --> + <attribute name="NATNetworks" type="INATNetwork" safearray="yes" readonly="yes"/> <attribute name="eventSource" type="IEventSource" readonly="yes"> <desc> @@ -1726,6 +2038,12 @@ array. <note> + <link to="IMachine::settingsModified"/> will return + @c false for the created machine, until any of machine settings + are changed. + </note> + + <note> There is no way to change the name of the settings file or subfolder of the created machine directly. </note> @@ -1784,6 +2102,12 @@ The file must exist and be a valid machine XML settings file whose contents will be used to construct the machine object. + <note> + <link to="IMachine::settingsModified"/> will return + @c false for the opened machine, until any of machine settings + are changed. + </note> + <result name="VBOX_E_FILE_ERROR"> Settings file name invalid, not found or sharing violation. </result> @@ -1796,11 +2120,6 @@ <param name="machine" type="IMachine" dir="return"> <desc>Opened machine object.</desc> </param> - <note> - <link to="IMachine::settingsModified"/> will return - @c false for the created machine, until any of machine settings - are changed. - </note> </method> <method name="registerMachine"> @@ -2110,7 +2429,7 @@ Returns an array representing the global extra data keys which currently have values defined. </desc> - <param name="value" type="wstring" dir="return" safearray="yes"> + <param name="keys" type="wstring" dir="return" safearray="yes"> <desc>Array of extra data keys.</desc> </param> </method> @@ -2268,6 +2587,30 @@ </param> </method> + <!-- bunch of methods to create NAT --> + <method name="createNATNetwork"> + <!-- Here we create a record in NAT network array with name + and gateway/network parameters this information should + be enough for VBoxNetNAT and VBoxNetDHCP for + servicing the guests. + --> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="INATNetwork" dir="return"/> + </method> + + <!-- + Returns the NATNetwork by name, e.g. for adding port forward rule or deletion. + --> + <method name="findNATNetworkByName"> + <param name="networkName" type="wstring" dir="in"/> + <param name="network" type="INATNetwork" dir="return"/> + </method> + <!-- + Deletes given NAT network. + --> + <method name="removeNATNetwork"> + <param name="network" type="INATNetwork" dir="in"/> + </method> <method name="checkFirmwarePresent"> <desc> @@ -2344,7 +2687,7 @@ <interface name="IVFSExplorer" extends="$unknown" - uuid="003d7f92-d38e-487f-b790-8c5e8631cb2f" + uuid="fb220201-2fd3-47e2-a5dc-2c2431d833cc" wsmap="managed" > <desc> @@ -2367,7 +2710,7 @@ current directory level. Use <link to="#entryList" /> to get the full list after a call to this method.</desc> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2375,11 +2718,11 @@ <method name="cd"> <desc>Change the current directory level.</desc> - <param name="aDir" type="wstring" dir="in"> + <param name="dir" type="wstring" dir="in"> <desc>The name of the directory to go in.</desc> </param> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2387,7 +2730,7 @@ <method name="cdUp"> <desc>Go one directory upwards from the current directory level.</desc> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2397,19 +2740,19 @@ to="#update" />. The user is responsible for keeping this internal list up do date.</desc> - <param name="aNames" type="wstring" safearray="yes" dir="out"> + <param name="names" type="wstring" safearray="yes" dir="out"> <desc>The list of names for the entries.</desc> </param> - <param name="aTypes" type="unsigned long" safearray="yes" dir="out"> + <param name="types" type="unsigned long" safearray="yes" dir="out"> <desc>The list of types for the entries.</desc> </param> - <param name="aSizes" type="unsigned long" safearray="yes" dir="out"> + <param name="sizes" type="long long" safearray="yes" dir="out"> <desc>The list of sizes (in bytes) for the entries.</desc> </param> - <param name="aModes" type="unsigned long" safearray="yes" dir="out"> + <param name="modes" type="unsigned long" safearray="yes" dir="out"> <desc>The list of file modes (in octal form) for the entries.</desc> </param> </method> @@ -2418,11 +2761,11 @@ <desc>Checks if the given file list exists in the current directory level.</desc> - <param name="aNames" type="wstring" safearray="yes" dir="in"> + <param name="names" type="wstring" safearray="yes" dir="in"> <desc>The names to check.</desc> </param> - <param name="aExists" type="wstring" safearray="yes" dir="return"> + <param name="exists" type="wstring" safearray="yes" dir="return"> <desc>The names which exist.</desc> </param> </method> @@ -2430,11 +2773,11 @@ <method name="remove"> <desc>Deletes the given files in the current directory level.</desc> - <param name="aNames" type="wstring" safearray="yes" dir="in"> + <param name="names" type="wstring" safearray="yes" dir="in"> <desc>The names to remove.</desc> </param> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2442,7 +2785,7 @@ </interface> <enum - name="ImportOptions" extends="$unknown" + name="ImportOptions" uuid="0a981523-3b20-4004-8ee3-dfd322202ace" > @@ -2450,15 +2793,47 @@ Import options, used with <link to="IAppliance::importMachines" />. </desc> - <const name="KeepAllMACs" value="1"> + <const name="KeepAllMACs" value="1"> <desc>Don't generate new MAC addresses of the attached network adapters.</desc> </const> - <const name="KeepNATMACs" value="2"> + <const name="KeepNATMACs" value="2"> <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc> </const> </enum> + <enum + name="ExportOptions" + uuid="8f45eb08-fd34-41ee-af95-a880bdee5554" + > + + <desc> + Export options, used with <link to="IAppliance::write" />. + </desc> + + <const name="CreateManifest" value="1"> + <desc>Write the optional manifest file (.mf) which is used for integrity + checks prior import.</desc> + </const> + <const name="ExportDVDImages" value="2"> + <desc>Export DVD images. Default is not to export them as it is rarely + needed for typical VMs.</desc> + </const> + <const name="StripAllMACs" value="3"> + <desc>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.</desc> + </const> + <const name="StripAllNonNATMACs" value="4"> + <desc>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.</desc> + </const> + + </enum> + <!-- // IAppliance @@ -2517,7 +2892,7 @@ virtual system (machine) to override the suggestions made by the <link to="#interpret" /> routine. </li> - <li>Finally, call <link to="#importMachines" /> to create virtual machines in + <li>Finally, call <link to="#importMachines" /> to create virtual machines in VirtualBox as instances of <link to="IMachine" /> that match the information in the virtual system descriptions. After this call succeeded, the UUIDs of the machines created can be found in the <link to="#machines" /> array attribute. @@ -2531,13 +2906,13 @@ an empty IAppliance object. </li> - <li>For each machine you would like to export, call <link to="IMachine::export" /> + <li>For each machine you would like to export, call <link to="IMachine::exportTo" /> with the IAppliance object you just created. Each such call creates one instance of <link to="IVirtualSystemDescription" /> inside the appliance. </li> <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each - virtual system (machine) to override the suggestions made by the <link to="IMachine::export"/> routine. + virtual system (machine) to override the suggestions made by the <link to="IMachine::exportTo"/> routine. </li> <li>Finally, call <link to="#write" /> with a path specification to have the OVF @@ -2588,7 +2963,7 @@ <li>Chunk size (optional unsigned integer if the image is split into chunks; presently unsupported and always -1)</li> - <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li> + <li>Compression (optional string equaling "gzip" if the image is gzip-compressed)</li> </ol> </desc> </attribute> @@ -2596,7 +2971,7 @@ <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes"> <desc> 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 <link to="#interpret" /> (for import) or <link to="IMachine::export" /> + This array is empty until either <link to="#interpret" /> (for import) or <link to="IMachine::exportTo" /> (for export) has been called. </desc> </attribute> @@ -2623,7 +2998,7 @@ on whether the appliance is distributed as a set of files or as a single file, respectively). </desc> </param> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2667,7 +3042,7 @@ <desc>Options for the importing operation.</desc> </param> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> @@ -2675,11 +3050,11 @@ <method name="createVFSExplorer"> <desc>Returns a <link to="IVFSExplorer" /> object for the given URI.</desc> - <param name="aUri" type="wstring" dir="in"> + <param name="URI" type="wstring" dir="in"> <desc>The URI describing the file system to use.</desc> </param> - <param name="aExplorer" type="IVFSExplorer" dir="return"> + <param name="explorer" type="IVFSExplorer" dir="return"> <desc></desc> </param> </method> @@ -2701,11 +3076,8 @@ and "ovf-2.0"; future versions of VirtualBox may support additional formats. </desc> </param> - <param name="manifest" type="boolean" dir="in"> - <desc> - Indicate if the optional manifest file (.mf) should be written. The manifest file - is used for integrity checks prior import. - </desc> + <param name="options" type="ExportOptions" dir="in" safearray="yes"> + <desc>Options for the exporting operation.</desc> </param> <param name="path" type="wstring" dir="in"> <desc> @@ -2721,7 +3093,7 @@ <method name="getWarnings"> <desc>Returns textual warnings which occurred during execution of <link to="#interpret" />.</desc> - <param name="aWarnings" type="wstring" dir="return" safearray="yes"> + <param name="warnings" type="wstring" dir="return" safearray="yes"> <desc></desc> </param> </method> @@ -2801,7 +3173,7 @@ The list below identifies the value sets that are possible depending on the <link to="VirtualSystemDescriptionType" /> enum value in the array item in @a aTypes[]. In each case, - the array item with the same index in @a aOvfValues[] will contain the original value as contained + 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. @@ -2809,14 +3181,14 @@ <ul> <li> "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. + corresponding item in @a aVBoxValues[] contains the suggested guest operating system for VirtualBox. This will be one of the values listed in <link to="IVirtualBox::guestOSTypes" />. The corresponding - item in @a aOvfValues[] will contain a numerical value that described the operating system in the OVF. + item in @a OVFValues[] will contain a numerical value that described the operating system in the OVF. </li> <li> "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 aOvfValues[] will contain the suggested virtual machine name + 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 <link to="IMachine" /> name that does not exist yet. </li> @@ -2840,7 +3212,7 @@ </li> <li> "HardDiskControllerIDE": an IDE hard disk controller. There can be at most two such items. - An optional value in @a aOvfValues[] and @a aVBoxValues[] can be "PIIX3" or "PIIX4" to specify + 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" @@ -2852,12 +3224,12 @@ </li> <li> "HardDiskControllerSATA": an SATA hard disk controller. There can be at most one such item. This - has no value in @a aOvfValues[] or @a aVBoxValues[]. + 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). </li> <li> "HardDiskControllerSCSI": a SCSI hard disk controller. There can be at most one such item. - The items in @a aOvfValues[] and @a aVBoxValues[] will either be "LsiLogic", "BusLogic" or + 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 <link to="StorageControllerType" />). @@ -2867,7 +3239,7 @@ "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 aOvfValues[] will contain the file specification from the OVF file (without + 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 @@ -2897,8 +3269,8 @@ of the "type=<X>" format, where <X> must be either "NAT" or "Bridged". </li> <li> - "USBController": a USB controller. There can be at most one such item. If and only if such an - item ispresent, USB support will be enabled for the new virtual machine. + "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. </li> <li> "SoundCard": a sound card. There can be at most one such item. If and only if such an item is @@ -2910,23 +3282,23 @@ </desc> - <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> + <param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aRefs" type="wstring" dir="out" safearray="yes"> + <param name="refs" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aOvfValues" type="wstring" dir="out" safearray="yes"> + <param name="OVFValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aVBoxValues" type="wstring" dir="out" safearray="yes"> + <param name="VBoxValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes"> + <param name="extraConfigValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> @@ -2936,27 +3308,27 @@ <desc>This is the same as <link to="#getDescription" /> except that you can specify which types should be returned.</desc> - <param name="aType" type="VirtualSystemDescriptionType" dir="in"> + <param name="type" type="VirtualSystemDescriptionType" dir="in"> <desc></desc> </param> - <param name="aTypes" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> + <param name="types" type="VirtualSystemDescriptionType" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aRefs" type="wstring" dir="out" safearray="yes"> + <param name="refs" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aOvfValues" type="wstring" dir="out" safearray="yes"> + <param name="OVFValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aVBoxValues" type="wstring" dir="out" safearray="yes"> + <param name="VBoxValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> - <param name="aExtraConfigValues" type="wstring" dir="out" safearray="yes"> + <param name="extraConfigValues" type="wstring" dir="out" safearray="yes"> <desc></desc> </param> @@ -2967,15 +3339,15 @@ value types should be returned. See <link to="VirtualSystemDescriptionValueType" /> for possible values.</desc> - <param name="aType" type="VirtualSystemDescriptionType" dir="in"> + <param name="type" type="VirtualSystemDescriptionType" dir="in"> <desc></desc> </param> - <param name="aWhich" type="VirtualSystemDescriptionValueType" dir="in"> + <param name="which" type="VirtualSystemDescriptionValueType" dir="in"> <desc></desc> </param> - <param name="aValues" type="wstring" dir="return" safearray="yes"> + <param name="values" type="wstring" dir="return" safearray="yes"> <desc></desc> </param> @@ -3000,15 +3372,15 @@ corresponding item in the aEnabled array is @c false, the configuration value is ignored. </desc> - <param name="aEnabled" type="boolean" dir="in" safearray="yes"> + <param name="enabled" type="boolean" dir="in" safearray="yes"> <desc></desc> </param> - <param name="aVBoxValues" type="wstring" dir="in" safearray="yes"> + <param name="VBoxValues" type="wstring" dir="in" safearray="yes"> <desc></desc> </param> - <param name="aExtraConfigValues" type="wstring" dir="in" safearray="yes"> + <param name="extraConfigValues" type="wstring" dir="in" safearray="yes"> <desc></desc> </param> </method> @@ -3021,15 +3393,15 @@ be the License type of <link to="VirtualSystemDescriptionType" />. </desc> - <param name="aType" type="VirtualSystemDescriptionType" dir="in"> + <param name="type" type="VirtualSystemDescriptionType" dir="in"> <desc></desc> </param> - <param name="aVBoxValue" type="wstring" dir="in"> + <param name="VBoxValue" type="wstring" dir="in"> <desc></desc> </param> - <param name="aExtraConfigValue" type="wstring" dir="in"> + <param name="extraConfigValue" type="wstring" dir="in"> <desc></desc> </param> </method> @@ -3043,7 +3415,7 @@ <interface name="IInternalMachineControl" extends="$unknown" - uuid="ec824977-e43f-479c-81c9-ac6cae1423a5" + uuid="2d9ce4b7-0ab2-4931-ac4a-e45aa66465ef" internal="yes" wsmap="suppress" > @@ -3052,7 +3424,7 @@ Updates the flag whether the saved state file is removed on a machine state change from Saved to PoweredOff. </desc> - <param name="aRemove" type="boolean" dir="in"/> + <param name="remove" type="boolean" dir="in"/> </method> <method name="updateState"> @@ -3067,21 +3439,17 @@ <param name="state" type="MachineState" dir="in"/> </method> - <method name="getIPCId"> - <param name="id" type="wstring" dir="return"/> - </method> - <method name="beginPowerUp"> <desc> Tells VBoxSVC that <link to="IConsole::powerUp"/> is under ways and gives it the progress object that should be part of any pending - <link to="IMachine::launchVMProcess"/> operations. The progress + <link to="IMachine::launchVMProcess"/> 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 <link to="IInternalMachineControl::endPowerUp"/> to signal the completion of the progress object. </desc> - <param name="aProgress" type="IProgress" dir="in" /> + <param name="progress" type="IProgress" dir="in" /> </method> <method name="endPowerUp"> @@ -3366,26 +3734,8 @@ <method name="finishOnlineMergeMedium"> <desc> Gets called by <link to="IInternalSessionControl::onlineMergeMedium"/>. + All necessary state information is available at the called object. </desc> - <param name="mediumAttachment" type="IMediumAttachment" dir="in"> - <desc>The medium attachment which needs to be cleaned up.</desc> - </param> - <param name="source" type="IMedium" dir="in"> - <desc>Merge source medium.</desc> - </param> - <param name="target" type="IMedium" dir="in"> - <desc>Merge target medium.</desc> - </param> - <param name="mergeForward" type="boolean" dir="in"> - <desc>Merge direction.</desc> - </param> - <param name="parentForTarget" type="IMedium" dir="in"> - <desc>For forward merges: new parent for target medium.</desc> - </param> - <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in"> - <desc>For backward merges: list of media which need their parent UUID - updated.</desc> - </param> </method> <method name="restoreSnapshot"> @@ -3412,26 +3762,26 @@ with their values, time stamps and flags and give responsibility for managing properties to the console. </desc> - <param name="name" type="wstring" dir="out" safearray="yes"> + <param name="names" type="wstring" dir="out" safearray="yes"> <desc> The names of the properties returned. </desc> </param> - <param name="value" type="wstring" dir="out" safearray="yes"> + <param name="values" type="wstring" dir="out" safearray="yes"> <desc> - The values of the properties returned. The array entries match the + The values of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> - <param name="timestamp" type="long long" dir="out" safearray="yes"> + <param name="timestamps" type="long long" dir="out" safearray="yes"> <desc> - The time stamps of the properties returned. The array entries match + The time stamps of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> <param name="flags" type="wstring" dir="out" safearray="yes"> <desc> - The flags of the properties returned. The array entries match the + The flags of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> @@ -3502,9 +3852,9 @@ </param> </method> - <method name="reportGuestStatistics"> + <method name="reportVmStatistics"> <desc> - Passes collected guest statistics to VBoxSVC. + Passes statistics collected by VM (including guest statistics) to VBoxSVC. </desc> <param name="validStats" type="unsigned long" dir="in"> <desc> @@ -3551,6 +3901,12 @@ <param name="memSharedTotal" type="unsigned long" dir="in"> <desc>Total amount of shared memory in the hypervisor.</desc> </param> + <param name="vmNetRx" type="unsigned long" dir="in"> + <desc>Network receive rate for VM.</desc> + </param> + <param name="vmNetTx" type="unsigned long" dir="in"> + <desc>Network transmit rate for VM.</desc> + </param> </method> </interface> @@ -3613,32 +3969,22 @@ PXE trace information to the release log. </desc> </attribute> - </interface> - <enum - name="CleanupMode" - uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441" - > - <desc>Cleanup mode, used with <link to="IMachine::unregister" />. - </desc> - <const name="UnregisterOnly" value="1"> - <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc> - </const> - <const name="DetachAllReturnNone" value="2"> - <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc> - </const> - <const name="DetachAllReturnHardDisksOnly" value="3"> - <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc> - </const> - <const name="Full" value="4"> - <desc>Delete all snapshots, detach all media and return all media for closing.</desc> - </const> - </enum> + <attribute name="nonVolatileStorageFile" type="wstring" readonly="yes"> + <desc> + The location of the file storing the non-volatile memory content when + the VM is powered off. The file does not always exist. + + This feature will be realized after VirtualBox v4.3.0. + </desc> + </attribute> + + </interface> <interface name="IPCIAddress" extends="$unknown" - uuid="D88B324F-DB19-4D3B-A1A9-BF5B127199A8" - wsmap="struct" + uuid="c984d15f-e191-400b-840e-970f3dad7296" + wsmap="managed" > <desc> @@ -3715,7 +4061,44 @@ </interface> <enum - name="CloneMode" extends="$unknown" + name="GraphicsControllerType" + uuid="79c96ca0-9f39-4900-948e-68c41cbe127a" + > + <desc>Graphics controller type, used with <link to="IMachine::unregister" />. + </desc> + <const name="Null" value="0"> + <desc>Reserved value, invalid.</desc> + </const> + <const name="VBoxVGA" value="1"> + <desc>Default VirtualBox VGA device.</desc> + </const> + <const name="VMSVGA" value="2"> + <desc>VMware SVGA II device.</desc> + </const> + </enum> + + <enum + name="CleanupMode" + uuid="67897c50-7cca-47a9-83f6-ce8fd8eb5441" + > + <desc>Cleanup mode, used with <link to="IMachine::unregister" />. + </desc> + <const name="UnregisterOnly" value="1"> + <desc>Unregister only the machine, but neither delete snapshots nor detach media.</desc> + </const> + <const name="DetachAllReturnNone" value="2"> + <desc>Delete all snapshots and detach all media but return none; this will keep all media registered.</desc> + </const> + <const name="DetachAllReturnHardDisksOnly" value="3"> + <desc>Delete all snapshots, detach all media and return hard disks for closing, but not removable media.</desc> + </const> + <const name="Full" value="4"> + <desc>Delete all snapshots, detach all media and return all media for closing.</desc> + </const> + </enum> + + <enum + name="CloneMode" uuid="A7A159FE-5096-4B8D-8C3C-D033CB0B35A8" > @@ -3723,20 +4106,20 @@ Clone mode, used with <link to="IMachine::cloneTo" />. </desc> - <const name="MachineState" value="1"> + <const name="MachineState" value="1"> <desc>Clone the state of the selected machine.</desc> </const> - <const name="MachineAndChildStates" value="2"> + <const name="MachineAndChildStates" value="2"> <desc>Clone the state of the selected machine and its child snapshots if present.</desc> </const> - <const name="AllStates" value="3"> + <const name="AllStates" value="3"> <desc>Clone all states (including all snapshots) of the machine, regardless of the machine object used.</desc> </const> </enum> <enum - name="CloneOptions" extends="$unknown" + name="CloneOptions" uuid="22243f8e-96ab-497c-8cf0-f40a566c630b" > @@ -3744,23 +4127,23 @@ Clone options, used with <link to="IMachine::cloneTo" />. </desc> - <const name="Link" value="1"> + <const name="Link" value="1"> <desc>Create a clone VM where all virtual disks are linked to the original VM.</desc> </const> - <const name="KeepAllMACs" value="2"> + <const name="KeepAllMACs" value="2"> <desc>Don't generate new MAC addresses of the attached network adapters.</desc> </const> - <const name="KeepNATMACs" value="3"> + <const name="KeepNATMACs" value="3"> <desc>Don't generate new MAC addresses of the attached network adapters when they are using NAT.</desc> </const> - <const name="KeepDiskNames" value="4"> + <const name="KeepDiskNames" value="4"> <desc>Don't change the disk names.</desc> </const> </enum> <enum - name="AutostopType" extends="$unknown" + name="AutostopType" uuid="6bb96740-cf34-470d-aab2-2cd48ea2e10e" > @@ -3768,16 +4151,16 @@ Autostop types, used with <link to="IMachine::autostopType" />. </desc> - <const name="Disabled" value="1"> + <const name="Disabled" value="1"> <desc>Stopping the VM during system shutdown is disabled.</desc> </const> - <const name="SaveState" value="2"> + <const name="SaveState" value="2"> <desc>The state of the VM will be saved when the system shuts down.</desc> </const> - <const name="PowerOff" value="3"> + <const name="PowerOff" value="3"> <desc>The VM is powered off when the system shuts down.</desc> </const> - <const name="AcpiShutdown" value="4"> + <const name="AcpiShutdown" value="4"> <desc>An ACPI shutdown event is generated.</desc> </const> @@ -3786,7 +4169,7 @@ <interface name="IMachine" extends="$unknown" - uuid="22781af3-1c96-4126-9edf-67a020e0e858" + uuid="480cf695-2d8d-4256-9c7c-cce4184fa048" wsmap="managed" > <desc> @@ -3829,6 +4212,10 @@ <desc>Associated parent object.</desc> </attribute> + <attribute name="icon" type="octet" safearray="yes"> + <desc>Overridden VM Icon details.</desc> + </attribute> + <attribute name="accessible" type="boolean" readonly="yes"> <desc> Whether this virtual machine is currently accessible or not. @@ -3972,7 +4359,7 @@ <attribute name="hardwareUUID" type="uuid" mod="string"> <desc> 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 + 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. @@ -4008,10 +4395,14 @@ <attribute name="pageFusionEnabled" type="boolean"> <desc> This setting determines whether VirtualBox allows page - fusion for this machine (64 bits host only). + fusion for this machine (64-bit hosts only). </desc> </attribute> + <attribute name="graphicsControllerType" type="GraphicsControllerType"> + <desc>Graphics controller type.</desc> + </attribute> + <attribute name="VRAMSize" type="unsigned long"> <desc>Video memory size in megabytes.</desc> </attribute> @@ -4038,28 +4429,64 @@ </desc> </attribute> - <attribute name="VideoCaptureEnabled" type="boolean" default="false"> + <attribute name="videoCaptureEnabled" type="boolean" default="false"> <desc> This setting determines whether VirtualBox uses video recording to record VM session.</desc> </attribute> - <attribute name="VideoCaptureFile" type="wstring" default="Test.webm"> + <attribute name="videoCaptureScreens" type="boolean" safearray="yes"> <desc> - This setting determines what filename VirtualBox uses to save - the recorded content.</desc> + This setting determines for which screens video recording is + enabled.</desc> </attribute> - <attribute name="VideoCaptureWidth" type="unsigned long" default="640"> + <attribute name="videoCaptureFile" type="wstring"> <desc> - This setting determines what should be the horizontal resolution of - recorded video.</desc> + This setting determines the filename VirtualBox uses to save + the recorded content. This setting cannot be changed while video + capturing is enabled. + <note> + When setting this attribute, the specified path has to be + absolute (full path). When reading this attribute, a full path is + always returned. + </note> + </desc> </attribute> - <attribute name="VideoCaptureHeight" type="unsigned long" default="480"> + <attribute name="videoCaptureWidth" type="unsigned long" default="640"> <desc> - This setting determines what should be the vertical resolution - of recorded video.</desc> + This setting determines the horizontal resolution of the recorded + video. This setting cannot be changed while video capturing is + enabled. + </desc> + </attribute> + + <attribute name="videoCaptureHeight" type="unsigned long" default="480"> + <desc> + This setting determines the vertical resolution of the recorded + video. This setting cannot be changed while video capturing is + enabled. + </desc> + </attribute> + + <attribute name="videoCaptureRate" type="unsigned long" default="512"> + <desc> + This setting determines the bitrate in kilobits per second. + Increasing this value makes the video look better for the + cost of an increased file size. This setting cannot be changed + while video capturing is enabled. + </desc> + </attribute> + + <attribute name="videoCaptureFPS" type="unsigned long" default="25"> + <desc> + This setting determines the maximum number of frames per second. + Frames with a higher frequency will be skipped. Reducing this + value increases the number of skipped frames and reduces the + file size. This setting cannot be changed while video capturing + is enabled. + </desc> </attribute> <attribute name="BIOSSettings" type="IBIOSSettings" readonly="yes"> @@ -4132,16 +4559,26 @@ <desc>VirtualBox Remote Desktop Extension (VRDE) server object.</desc> </attribute> - <attribute name="emulatedUSBWebcameraEnabled" type="boolean" default="false"/> <attribute name="emulatedUSBCardReaderEnabled" type="boolean" default="false"/> <attribute name="mediumAttachments" type="IMediumAttachment" readonly="yes" safearray="yes"> <desc>Array of media attached to this machine.</desc> </attribute> - <attribute name="USBController" type="IUSBController" readonly="yes"> + <attribute name="USBControllers" type="IUSBController" readonly="yes" safearray="yes"> <desc> - Associated USB controller object. + Array of USB controllers attached to this machine. + + <note> + If USB functionality is not available in the given edition of + VirtualBox, this method will set the result code to @c E_NOTIMPL. + </note> + </desc> + </attribute> + + <attribute name="USBDeviceFilters" type="IUSBDeviceFilters" readonly="yes"> + <desc> + Associated USB device filters object. <note> If USB functionality is not available in the given edition of @@ -4193,7 +4630,7 @@ <attribute name="sessionType" type="wstring" readonly="yes"> <desc> - Type of the session. If <link to="#sessionState"/> is + Type of the session. If <link to="#sessionState"/> is Spawning or Locked, this attribute contains the same value as passed to the <link to="IMachine::launchVMProcess"/> method in the @@ -4324,7 +4761,7 @@ <attribute name="guestPropertyNotificationPatterns" type="wstring"> <desc> - A comma-separated list of simple glob patterns. Changes to guest + A comma-separated list of simple glob patterns. Changes to guest properties whose name matches one of the patterns will generate an <link to="IGuestPropertyChangedEvent"/> signal. </desc> @@ -4333,7 +4770,7 @@ <attribute name="teleporterEnabled" type="boolean"> <desc> 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 + 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. <!-- This property is automatically set to @a false when the VM is powered @@ -4346,7 +4783,7 @@ The TCP port the target teleporter will listen for incoming teleportations on. - 0 means the port is automatically selected upon power on. The actual + 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. </desc> @@ -4354,7 +4791,7 @@ <attribute name="teleporterAddress" type="wstring"> <desc> - The address the target teleporter will listen on. If set to an empty + The address the target teleporter will listen on. If set to an empty string, it will listen on all addresses. </desc> </attribute> @@ -4366,7 +4803,7 @@ 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. + password. Setting a hashed password is currently not supported. </desc> </attribute> @@ -4393,7 +4830,7 @@ <attribute name="faultTolerancePassword" type="wstring"> <desc> - The password to check for on the standby VM. This is just a + The password to check for on the standby VM. This is just a very basic measure to prevent simple hacks and operators accidentally choosing the wrong standby VM. </desc> @@ -4445,7 +4882,7 @@ <attribute name="tracingEnabled" type="boolean"> <desc> Enables the tracing facility in the VMM (including PDM devices + - drivers). The VMM will consume about 0.5MB of more memory when + 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. </desc> @@ -4454,13 +4891,13 @@ <attribute name="tracingConfig" type="wstring"> <desc> Tracepoint configuration to apply at startup when - <link to="IMachine::tracingEnabled" /> is true. The string specifies - a space separated of tracepoint group names to enable. The special - group 'all' enables all tracepoints. Check DBGFR3TracingConfig for + <link to="IMachine::tracingEnabled" /> 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 exclusivly as DTrace probes. So, the + tracepoints may be implemented exclusively as DTrace probes. So, the effect of the same config may differ between Solaris and Windows for example. </desc> @@ -4469,7 +4906,7 @@ <attribute name="allowTracingToAccessVM" type="boolean"> <desc> Enables tracepoints in PDM devices and drivers to use the VMCPU or VM - structures when firing off trace points. This is especially useful + 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. @@ -4497,6 +4934,28 @@ </desc> </attribute> + <attribute name="defaultFrontend" type="wstring"> + <desc> + Selects which VM frontend should be used by default when launching + this VM through the <link to="IMachine::launchVMProcess" /> method. + Empty or @c null strings do not define a particular default, it is up + to <link to="IMachine::launchVMProcess" /> to select one. See the + description of <link to="IMachine::launchVMProcess" /> for the valid + frontend types. + + This per-VM setting overrides the default defined by + <link to="ISystemProperties::defaultFrontend" /> attribute, and is + overridden by a frontend type passed to + <link to="IMachine::launchVMProcess" />. + </desc> + </attribute> + + <attribute name="USBProxyAvailable" type="boolean" readonly="yes"> + <desc> + Returns whether there is an USB proxy available. + </desc> + </attribute> + <method name="lockMachine"> <desc> Locks the machine for the given session to enable the caller @@ -4693,6 +5152,12 @@ @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.</li> + <li><tt>""</tt>: 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 <tt>"gui"</tt> session, which may + fail if there is no windowing environment available. See + <link to="IMachine::defaultFrontend"/> and + <link to="ISystemProperties::defaultFrontend"/>.</li> </ul> </desc> </param> @@ -5110,7 +5575,7 @@ <method name="setAutoDiscardForDevice"> <desc> Sets a flag in the device information which indicates that the medium - supports discarding unsused blocks (called trimming for SATA or unmap + 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 @@ -5146,6 +5611,46 @@ </param> </method> + <method name="setHotPluggableForDevice"> + <desc> + 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 <link to="IMachine::attachDevice"/> + 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 <link to="IMachine::attachDevice" />. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to modify an unregistered virtual machine. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Controller doesn't support hot plugging. + </result> + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Storage controller port.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port.</desc> + </param> + <param name="hotPluggable" type="boolean" dir="in"> + <desc>New value for the hot-pluggable device flag.</desc> + </param> + </method> + <method name="setBandwidthGroupForDevice"> <desc> Sets the bandwidth group of an existing storage device. @@ -5211,56 +5716,56 @@ <method name="unmountMedium"> - <desc> - Unmounts any currently mounted medium (<link to="IMedium" />, - identified by the given UUID @a id) to the given storage controller - (<link to="IStorageController" />, 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 - <link to="IMachine::attachDevice" />. - - The specified device slot must have a medium mounted, which will be - unmounted. If there is no mounted medium it will do nothing. - See <link to="IMedium"/> for more detailed information about - attaching/unmounting media. - - <result name="E_INVALIDARG"> - SATA device, SATA port, IDE port or IDE slot out of range. - </result> - <result name="VBOX_E_INVALID_OBJECT_STATE"> - Attempt to unmount medium that is not removeable - not dvd or floppy. - </result> - <result name="VBOX_E_INVALID_VM_STATE"> - Invalid machine state. - </result> - <result name="VBOX_E_OBJECT_IN_USE"> - Medium already attached to this or another virtual machine. - </result> - <result name="VBOX_E_OBJECT_NOT_FOUND"> - Medium not attached to specified port, device, controller. - </result> - - </desc> - <param name="name" type="wstring" dir="in"> - <desc>Name of the storage controller to unmount the medium from.</desc> - </param> - <param name="controllerPort" type="long" dir="in"> - <desc>Port to unmount the medium from.</desc> - </param> - <param name="device" type="long" dir="in"> - <desc>Device slot in the given port to unmount the medium from.</desc> - </param> - <param name="force" type="boolean" dir="in"> - <desc>Allows to force unmount of a medium which is locked by - the device slot in the given port medium is attached to.</desc> - </param> - </method> + <desc> + Unmounts any currently mounted medium (<link to="IMedium" />, + identified by the given UUID @a id) to the given storage controller + (<link to="IStorageController" />, 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 + <link to="IMachine::attachDevice" />. + + The specified device slot must have a medium mounted, which will be + unmounted. If there is no mounted medium it will do nothing. + See <link to="IMedium"/> for more detailed information about + attaching/unmounting media. + + <result name="E_INVALIDARG"> + SATA device, SATA port, IDE port or IDE slot out of range. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Attempt to unmount medium that is not removable - not DVD or floppy. + </result> + <result name="VBOX_E_INVALID_VM_STATE"> + Invalid machine state. + </result> + <result name="VBOX_E_OBJECT_IN_USE"> + Medium already attached to this or another virtual machine. + </result> + <result name="VBOX_E_OBJECT_NOT_FOUND"> + Medium not attached to specified port, device, controller. + </result> + </desc> + + <param name="name" type="wstring" dir="in"> + <desc>Name of the storage controller to unmount the medium from.</desc> + </param> + <param name="controllerPort" type="long" dir="in"> + <desc>Port to unmount the medium from.</desc> + </param> + <param name="device" type="long" dir="in"> + <desc>Device slot in the given port to unmount the medium from.</desc> + </param> + <param name="force" type="boolean" dir="in"> + <desc>Allows to force unmount of a medium which is locked by + the device slot in the given port medium is attached to.</desc> + </param> + </method> <method name="mountMedium"> <desc> @@ -5391,7 +5896,7 @@ Virtual machine does not have a PCI controller allowing attachment of physical devices. </result> <result name="VBOX_E_NOT_SUPPORTED"> - Hardware or host OS doesn't allow PCI device passthrought. + Hardware or host OS doesn't allow PCI device passthrough. </result> </desc> <param name="hostAddress" type="long" dir="in"> @@ -5425,7 +5930,7 @@ Virtual machine does not have a PCI controller allowing attachment of physical devices. </result> <result name="VBOX_E_NOT_SUPPORTED"> - Hardware or host OS doesn't allow PCI device passthrought. + Hardware or host OS doesn't allow PCI device passthrough. </result> </desc> <param name="hostAddress" type="long" dir="in"> @@ -5531,6 +6036,54 @@ <param name="bootable" type="boolean" dir="in"/> </method> + <method name="addUSBController"> + <desc> + Adds a new USB controller to the machine and returns it as an instance of + <link to="IUSBController" />. + + <result name="VBOX_E_OBJECT_IN_USE"> + A USB controller with given type exists already. + </result> + <result name="E_INVALIDARG"> + Invalid @a controllerType. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="type" type="USBControllerType" dir="in"/> + <param name="controller" type="IUSBController" dir="return"/> + </method> + + <method name="removeUSBController"> + <desc> + Removes a USB controller from the machine. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A USB controller with given type doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + </method> + + <method name="getUSBControllerByName" const="yes"> + <desc> + Returns a USB controller with the given type. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + A USB controller with given name doesn't exist. + </result> + </desc> + <param name="name" type="wstring" dir="in"/> + <param name="controller" type="IUSBController" dir="return"/> + </method> + + <method name="getUSBControllerCountByType" const="yes"> + <desc> + Returns the number of USB controllers of the given type attached to the VM. + </desc> + <param name="type" type="USBControllerType" dir="in"/> + <param name="controllers" type="unsigned long" dir="return"/> + </method> + <method name="getSerialPort" const="yes"> <desc> Returns the serial port associated with the given slot. @@ -5570,7 +6123,7 @@ Returns an array representing the machine-specific extra data keys which currently have values defined. </desc> - <param name="value" type="wstring" dir="return" safearray="yes"> + <param name="keys" type="wstring" dir="return" safearray="yes"> <desc>Array of extra data keys.</desc> </param> </method> @@ -5834,6 +6387,35 @@ </param> </method> + <method name="setSettingsFilePath"> + <desc> + 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. + + <note> + 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. + </note> + + <result name="E_NOTIMPL"> + The operation is not implemented yet. + </result> + </desc> + + <param name="settingsFilePath" type="wstring" dir="in"> + <desc>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.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + <method name="saveSettings"> <desc> Saves any changes to machine settings made since the session @@ -5898,7 +6480,7 @@ 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 - <link to="#delete"/>, optionally with the array of IMedium objects which was returned + <link to="#deleteConfig"/>, optionally with the array of IMedium objects which was returned from this method. How thoroughly this method cleans up the machine configuration before unregistering @@ -5917,23 +6499,23 @@ all of the machine's media will remain open.</li> <li>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 <link to="#delete" /> + be returned as an array. This allows for quickly passing them to the <link to="#deleteConfig" /> API for closing and deletion.</li> <li>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 <link to="#delete" /> + attached to the machine. Be careful when passing the media array to <link to="#deleteConfig" /> in that case because users will typically want to preserve ISO and RAW image files.</li> </ul> A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the - resulting IMedium array to <link to="#delete"/>. This way, the machine is completely + resulting IMedium array to <link to="#deleteConfig"/>. 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 <link to="#delete" /> however, closing the image will fail there + image is passed to <link to="#deleteConfig" /> 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 @@ -5967,12 +6549,12 @@ <param name="cleanupMode" type="CleanupMode" dir="in"> <desc>How to clean up after the machine has been unregistered.</desc> </param> - <param name="aMedia" type="IMedium" safearray="yes" dir="return"> + <param name="media" type="IMedium" safearray="yes" dir="return"> <desc>List of media detached from the machine, depending on the @a cleanupMode parameter.</desc> </param> </method> - <method name="delete"> + <method name="deleteConfig"> <desc> 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 @@ -6015,29 +6597,29 @@ Could not delete the settings file. </result> </desc> - <param name="aMedia" type="IMedium" safearray="yes" dir="in"> + <param name="media" type="IMedium" safearray="yes" dir="in"> <desc>List of media to be closed and whose storage files will be deleted.</desc> </param> - <param name="aProgress" type="IProgress" dir="return"> + <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> </param> </method> - <method name="export"> + <method name="exportTo"> <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the steps required to export VirtualBox machines to OVF. </desc> - <param name="aAppliance" type="IAppliance" dir="in"> + <param name="appliance" type="IAppliance" dir="in"> <desc>Appliance to export this machine to.</desc> </param> <param name="location" type="wstring" dir="in"> <desc>The target location.</desc> </param> - <param name="aDescription" type="IVirtualSystemDescription" dir="return"> + <param name="description" type="IVirtualSystemDescription" dir="return"> <desc>VirtualSystemDescription object which is created for this machine.</desc> </param> - </method > + </method> <method name="findSnapshot"> <desc> @@ -6084,7 +6666,7 @@ <desc>Full path to the shared folder in the host file system.</desc> </param> <param name="writable" type="boolean" dir="in"> - <desc>Whether the share is writable or readonly.</desc> + <desc>Whether the share is writable or read-only.</desc> </param> <param name="automount" type="boolean" dir="in"> <desc>Whether the share gets automatically mounted by the guest @@ -6182,7 +6764,7 @@ </param> <param name="value" type="wstring" dir="out"> <desc> - The value of the property. If the property does not exist then this + The value of the property. If the property does not exist then this will be empty. </desc> </param> @@ -6216,7 +6798,7 @@ </param> <param name="value" type="wstring" dir="return"> <desc> - The value of the property. If the property does not exist then this + The value of the property. If the property does not exist then this will be empty. </desc> </param> @@ -6238,7 +6820,7 @@ </param> <param name="value" type="long long" dir="return"> <desc> - The timestamp. If the property does not exist then this will be + The timestamp. If the property does not exist then this will be empty. </desc> </param> @@ -6270,9 +6852,9 @@ </param> <param name="value" type="wstring" dir="in"> <desc> - The new value of the property to set, change or delete. If the + 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 + created. If the value is @c null or empty, the property will be deleted if it exists. </desc> </param> @@ -6286,8 +6868,8 @@ <method name="setGuestPropertyValue"> <desc> - Sets, changes or deletes a value in the machine's guest property - store. The flags field will be left unchanged or created empty for a + 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. <result name="E_ACCESSDENIED"> @@ -6303,15 +6885,14 @@ <param name="property" type="wstring" dir="in"> <desc> - The name of the property to set, change or delete. + The name of the property to set or change. </desc> </param> <param name="value" type="wstring" dir="in"> <desc> - The new value of the property to set, change or delete. If the + 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. If the value is @c null or empty, the property will be - deleted if it exists. + created. </desc> </param> </method> @@ -6340,29 +6921,29 @@ <param name="patterns" type="wstring" dir="in"> <desc> The patterns to match the properties against, separated by '|' - characters. If this is empty or @c null, all properties will match. + characters. If this is empty or @c null, all properties will match. </desc> </param> - <param name="name" type="wstring" dir="out" safearray="yes"> + <param name="names" type="wstring" dir="out" safearray="yes"> <desc> The names of the properties returned. </desc> </param> - <param name="value" type="wstring" dir="out" safearray="yes"> + <param name="values" type="wstring" dir="out" safearray="yes"> <desc> - The values of the properties returned. The array entries match the + The values of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> - <param name="timestamp" type="long long" dir="out" safearray="yes"> + <param name="timestamps" type="long long" dir="out" safearray="yes"> <desc> - The time stamps of the properties returned. The array entries match + The time stamps of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> <param name="flags" type="wstring" dir="out" safearray="yes"> <desc> - The flags of the properties returned. The array entries match the + The flags of the properties returned. The array entries match the corresponding entries in the @a name array. </desc> </param> @@ -6636,7 +7217,7 @@ to="IVirtualBox::createMachine"/>, 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 newtwork adapters. You + network MAC addresses are newly created for all 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. @@ -6662,6 +7243,41 @@ </interface> + <interface + name="IEmulatedUSB" extends="$unknown" + uuid="38cc4dfd-8bb2-4d40-aebe-699eead8c2dd" + wsmap="managed" + > + <desc> + Manages emulated USB devices. + </desc> + + <method name="webcamAttach"> + <desc> + Attaches the emulated USB webcam to the VM, which will use a host video capture device. + </desc> + <param name="path" type="wstring" dir="in"> + <desc>The host path of the capture device to use.</desc> + </param> + <param name="settings" type="wstring" dir="in"> + <desc>Optional settings.</desc> + </param> + </method> + + <method name="webcamDetach"> + <desc> + Detaches the emulated USB webcam from the VM + </desc> + <param name="path" type="wstring" dir="in"> + <desc>The host path of the capture device to detach.</desc> + </param> + </method> + + <attribute name="webcams" type="wstring" safearray="yes" readonly="yes"> + <desc>Lists attached virtual webcams.</desc> + </attribute> + </interface> + <!-- // IConsole ///////////////////////////////////////////////////////////////////////// @@ -6777,7 +7393,7 @@ <interface name="IConsole" extends="$unknown" - uuid="db7ab4ca-2a3f-4183-9243-c1208da92392" + uuid="8ab7c520-2442-4b66-8d74-4ff1e195d2b6" wsmap="managed" > <desc> @@ -6878,7 +7494,7 @@ <attribute name="sharedFolders" type="ISharedFolder" readonly="yes" safearray="yes"> <desc> - Collection of shared folders for the current session. These folders + 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 @@ -6911,12 +7527,18 @@ <attribute name="useHostClipboard" type="boolean"> <desc> Whether the guest clipboard should be connected to the host one or - whether it should only be allowed access to the VRDE clipboard. This + 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. </desc> </attribute> + <attribute name="emulatedUSB" type="IEmulatedUSB" readonly="yes"> + <desc> + Interface that manages emulated USB devices. + </desc> + </attribute> + <method name="powerUp"> <desc> Starts the virtual machine execution using the current machine @@ -6927,7 +7549,7 @@ 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 + 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 <link to="IMachine::launchVMProcess"/> instead; these @@ -7208,7 +7830,7 @@ <link to="USBDeviceState_Busy">Busy</link>, an error may also be returned if the host computer refuses to release it for some reason. - <see><link to="IUSBController::deviceFilters"/>, + <see><link to="IUSBDeviceFilters::deviceFilters"/>, <link to="USBDeviceState"/></see> <result name="VBOX_E_INVALID_VM_STATE"> Virtual machine state neither Running nor Paused. @@ -7232,7 +7854,7 @@ to the host, but filters of this machine are ignored to avoid a possible automatic re-attachment. - <see><link to="IUSBController::deviceFilters"/>, + <see><link to="IUSBDeviceFilters::deviceFilters"/>, <link to="USBDeviceState"/></see> <result name="VBOX_E_PDM_ERROR"> @@ -7574,11 +8196,11 @@ </param> <param name="maxDowntime" type="unsigned long" dir="in"> <desc> - The maximum allowed downtime given as milliseconds. 0 is not a valid - value. Recommended value: 250 ms. + 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 + teleportation. A small value may easily result in the teleportation process taking hours and eventually fail. <note> @@ -7664,18 +8286,18 @@ <desc> Network interface type. </desc> - <const name="Bridged" value="1"/> - <const name="HostOnly" value="2"/> + <const name="Bridged" value="1"/> + <const name="HostOnly" value="2"/> </enum> <interface name="IHostNetworkInterface" extends="$unknown" - uuid="87a4153d-6889-4dd6-9654-2e9ff0ae8dec" + uuid="f6e556f9-d598-409b-898c-8ba99d9b05ae" wsmap="managed" > <desc> Represents one of host's network interfaces. IP V6 address and network - mask are strings of 32 hexdecimal digits grouped by four. Groups are + 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. </desc> @@ -7683,6 +8305,10 @@ <desc>Returns the host network interface name.</desc> </attribute> + <attribute name="shortName" type="wstring" readonly="yes"> + <desc>Returns the host network interface short name.</desc> + </attribute> + <attribute name="id" type="uuid" mod="string" readonly="yes"> <desc>Returns the interface UUID.</desc> </attribute> @@ -7770,8 +8396,30 @@ </interface> <interface + name="IHostVideoInputDevice" extends="$unknown" + uuid="a1ceae44-d65e-4156-9359-d390f93ee9a0" + wsmap="managed" + > + <desc> + Represents one of host's video capture devices, for example a webcam. + </desc> + <attribute name="name" type="wstring" readonly="yes"> + <desc>User friendly name.</desc> + </attribute> + + <attribute name="path" type="wstring" readonly="yes"> + <desc>The host path of the device.</desc> + </attribute> + + <attribute name="alias" type="wstring" readonly="yes"> + <desc>An alias which can be used for IConsole::webcamAttach</desc> + </attribute> + + </interface> + + <interface name="IHost" extends="$unknown" - uuid="30678943-32df-4830-b413-931b25ac86a0" + uuid="93269330-48ca-4096-b4a2-1189df336267" wsmap="managed" > <desc> @@ -7818,7 +8466,7 @@ Unless the device is ignored by these filters, filters of all currently running virtual machines - (<link to="IUSBController::deviceFilters"/>) are applied to it. + (<link to="IUSBDeviceFilters::deviceFilters"/>) are applied to it. <note> If USB functionality is not available in the given edition of @@ -7834,6 +8482,18 @@ <desc>List of host network interfaces currently defined on the host.</desc> </attribute> + <attribute name="nameServers" type="wstring" safearray="yes" readonly="yes"> + <desc> The list of nameservers registered in host's name resolving system.</desc> + </attribute> + + <attribute name="domainName" type="wstring" readonly="yes"> + <desc>Domain name used for name resolving.</desc> + </attribute> + + <attribute name="searchStrings" type="wstring" safearray="yes" readonly="yes"> + <desc>Search string registered for name resolving.</desc> + </attribute> + <attribute name="processorCount" type="unsigned long" readonly="yes"> <desc>Number of (logical) CPUs installed in the host system.</desc> </attribute> @@ -7846,6 +8506,10 @@ <desc>Number of physical processor cores installed in the host system.</desc> </attribute> + <attribute name="processorOnlineCoreCount" type="unsigned long" readonly="yes"> + <desc>Number of physical processor cores online in the host system.</desc> + </attribute> + <method name="getProcessorSpeed"> <desc>Query the (approximate) maximum speed of a specified host CPU in Megahertz. @@ -7903,7 +8567,7 @@ </desc> <param name="cpuId" type="unsigned long" dir="in"> <desc> - Identifier of the CPU. The CPU most be online. + Identifier of the CPU. The CPU most be online. <note> The current implementation might not necessarily return the description for this exact CPU. @@ -7917,8 +8581,8 @@ </param> <param name="subLeaf" type="unsigned long" dir="in"> <desc> - CPUID leaf sub index (ecx). This currently only applies to cache - information on Intel CPUs. Use 0 if retrieving values for + CPUID leaf sub index (ecx). This currently only applies to cache + information on Intel CPUs. Use 0 if retrieving values for <link to="IMachine::setCPUIDLeaf"/>. </desc> </param> @@ -8215,6 +8879,10 @@ </param> </method> + <attribute name="videoInputDevices" type="IHostVideoInputDevice" safearray="yes" readonly="yes"> + <desc>List of currently available host video capture devices.</desc> + </attribute> + </interface> <!-- @@ -8225,7 +8893,7 @@ <interface name="ISystemProperties" extends="$unknown" - uuid="1d7aca29-97f0-4287-9874-a60ec4f80ea6" + uuid="1254a96a-ae57-4484-946a-22d86c1f98af" wsmap="managed" > <desc> @@ -8293,6 +8961,15 @@ </desc> </attribute> + <attribute name="exclusiveHwVirt" type="boolean"> + <desc> + 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. + </desc> + </attribute> + <attribute name="defaultMachineFolder" type="wstring"> <desc> Full path to the default directory used to create new or open @@ -8318,6 +8995,12 @@ </desc> </attribute> + <attribute name="loggingLevel" type="wstring"> + <desc> + Specifies the logging level in current use by VirtualBox. + </desc> + </attribute> + <attribute name="mediumFormats" type="IMediumFormat" safearray="yes" readonly="yes"> <desc> List of all medium storage formats supported by this VirtualBox @@ -8356,7 +9039,7 @@ format specified by this argument will be used. The list of supported medium formats may be obtained by the - <link to="#mediumFormats"/> call. Note that the default medium + <link to="#mediumFormats"/> call. Note that the default medium format must have a capability to create differencing media; otherwise operations that create media implicitly may fail unexpectedly. @@ -8455,8 +9138,8 @@ 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 + 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 @@ -8489,6 +9172,21 @@ </desc> </attribute> + <attribute name="defaultFrontend" type="wstring"> + <desc> + Selects which VM frontend should be used by default when launching + a VM through the <link to="IMachine::launchVMProcess" /> method. + Empty or @c null strings do not define a particular default, it is up + to <link to="IMachine::launchVMProcess" /> to select one. See the + description of <link to="IMachine::launchVMProcess" /> for the valid + frontend types. + + This global setting is overridden by the per-VM attribute + <link to="IMachine::defaultFrontend" /> or a frontend type + passed to <link to="IMachine::launchVMProcess" />. + </desc> + </attribute> + <method name="getMaxNetworkAdapters"> <desc> Maximum total number of network adapters associated with every @@ -8522,7 +9220,7 @@ <param name="maxNetworkAdapters" type="unsigned long" dir="return"> <desc>The maximum number of network adapters allowed for - particular chipset and attachment type.</desc> + particular chipset and attachment type.</desc> </param> </method> @@ -8611,6 +9309,25 @@ <desc>Returned flag indicating the default value</desc> </param> </method> + + <method name="getMaxInstancesOfUSBControllerType"> + <desc>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.</desc> + + <param name="chipset" type="ChipsetType" dir="in"> + <desc>The chipset type to get the value for.</desc> + </param> + + <param name="type" type="USBControllerType" dir="in"> + <desc>The USB controller type to get the value for.</desc> + </param> + + <param name="maxInstances" type="unsigned long" dir="return"> + <desc>The maximum number of instances for the given USB controller type.</desc> + </param> + </method> </interface> <!-- @@ -8744,31 +9461,31 @@ Guest Additions facility IDs. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No/invalid facility.</desc> </const> - <const name="VBoxGuestDriver" value="20"> + <const name="VBoxGuestDriver" value="20"> <desc>VirtualBox base driver (VBoxGuest).</desc> </const> - <const name="AutoLogon" value="90"> + <const name="AutoLogon" value="90"> <desc>Auto-logon modules (VBoxGINA, VBoxCredProv, pam_vbox).</desc> </const> - <const name="VBoxService" value="100"> + <const name="VBoxService" value="100"> <desc>VirtualBox system service (VBoxService).</desc> </const> - <const name="VBoxTrayClient" value="101"> + <const name="VBoxTrayClient" value="101"> <desc>VirtualBox desktop integration (VBoxTray on Windows, VBoxClient on non-Windows).</desc> </const> - <const name="Seamless" value="1000"> + <const name="Seamless" value="1000"> <desc>Seamless guest desktop integration.</desc> </const> - <const name="Graphics" value="1100"> + <const name="Graphics" value="1100"> <desc>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. </desc> </const> - <const name="All" value="2147483646"> + <const name="All" value="2147483646"> <desc>All facilities selected.</desc> </const> </enum> @@ -8781,25 +9498,25 @@ Guest Additions facility classes. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No/invalid class.</desc> </const> - <const name="Driver" value="10"> + <const name="Driver" value="10"> <desc>Driver.</desc> </const> - <const name="Service" value="30"> + <const name="Service" value="30"> <desc>System service.</desc> </const> - <const name="Program" value="50"> + <const name="Program" value="50"> <desc>Program.</desc> </const> - <const name="Feature" value="100"> + <const name="Feature" value="100"> <desc>Feature.</desc> </const> - <const name="ThirdParty" value="999"> + <const name="ThirdParty" value="999"> <desc>Third party.</desc> </const> - <const name="All" value="2147483646"> + <const name="All" value="2147483646"> <desc>All facility classes selected.</desc> </const> </enum> @@ -8812,31 +9529,31 @@ Guest Additions facility states. </desc> - <const name="Inactive" value="0"> + <const name="Inactive" value="0"> <desc>Facility is not active.</desc> </const> - <const name="Paused" value="1"> + <const name="Paused" value="1"> <desc>Facility has been paused.</desc> </const> - <const name="PreInit" value="20"> + <const name="PreInit" value="20"> <desc>Facility is preparing to initialize.</desc> </const> - <const name="Init" value="30"> + <const name="Init" value="30"> <desc>Facility is initializing.</desc> </const> - <const name="Active" value="50"> + <const name="Active" value="50"> <desc>Facility is up and running.</desc> </const> - <const name="Terminating" value="100"> + <const name="Terminating" value="100"> <desc>Facility is shutting down.</desc> </const> - <const name="Terminated" value="101"> + <const name="Terminated" value="101"> <desc>Facility successfully shut down.</desc> </const> - <const name="Failed" value="800"> + <const name="Failed" value="800"> <desc>Facility failed to start.</desc> </const> - <const name="Unknown" value="999"> + <const name="Unknown" value="999"> <desc>Facility status is unknown.</desc> </const> </enum> @@ -8882,16 +9599,16 @@ Guest Additions run level type. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>Guest Additions are not loaded.</desc> </const> - <const name="System" value="1"> + <const name="System" value="1"> <desc>Guest drivers are loaded.</desc> </const> - <const name="Userland" value="2"> + <const name="Userland" value="2"> <desc>Common components (such as application services) are loaded.</desc> </const> - <const name="Desktop" value="3"> + <const name="Desktop" value="3"> <desc>Per-user desktop components are loaded.</desc> </const> </enum> @@ -8904,10 +9621,10 @@ Guest Additions update flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="WaitForUpdateStartOnly" value="1"> + <const name="WaitForUpdateStartOnly" value="1"> <desc>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 @@ -8916,6 +9633,221 @@ </enum> <enum + name="GuestSessionStatus" + uuid="ac2669da-4624-44f2-85b5-0b0bfb8d8673" + > + <desc> + Guest session status. This enumeration represents possible values of + the <link to="IGuestSession::status"/> attribute. + </desc> + <const name="Undefined" value="0"> + <desc>Guest session is in an undefined state.</desc> + </const> + <const name="Starting" value="10"> + <desc>Guest session is being started.</desc> + </const> + <const name="Started" value="100"> + <desc>Guest session has been started.</desc> + </const> + <const name="Terminating" value="480"> + <desc>Guest session is being terminated.</desc> + </const> + <const name="Terminated" value="500"> + <desc>Guest session terminated normally.</desc> + </const> + <const name="TimedOutKilled" value="512"> + <desc>Guest session timed out and was killed.</desc> + </const> + <const name="TimedOutAbnormally" value="513"> + <desc>Guest session timed out and was not killed successfully.</desc> + </const> + <const name="Down" value="600"> + <desc>Service/OS is stopping, guest session was killed.</desc> + </const> + <const name="Error" value="800"> + <desc>Something went wrong.</desc> + </const> + </enum> + + <enum + name="GuestSessionWaitForFlag" + uuid="bb7a372a-f635-4e11-a81a-e707f3a52ef5" + > + <desc> + Guest session waiting flags. Multiple flags can be combined. + </desc> + + <const name="None" value="0"> + <desc>No waiting flags specified. Do not use this.</desc> + </const> + <const name="Start" value="1"> + <desc>Wait for the guest session being started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>Wait for the guest session being terminated.</desc> + </const> + <const name="Status" value="4"> + <desc>Wait for the next guest session status change.</desc> + </const> + </enum> + + <enum + name="GuestSessionWaitResult" + uuid="c0f6a8a5-fdb6-42bf-a582-56c6f82bcd2d" + > + <desc> + Guest session waiting results. Depending on the session waiting flags (for + more information see <link to="GuestSessionWaitForFlag"/>) 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 <link to="IGuest::createSession"/> one would specify + GuestSessionWaitResult_Terminate. + </desc> + + <const name="None" value="0"> + <desc>No result was returned. Not being used.</desc> + </const> + <const name="Start" value="1"> + <desc>The guest session has been started.</desc> + </const> + <const name="Terminate" value="2"> + <desc>The guest session has been terminated.</desc> + </const> + <const name="Status" value="3"> + <desc> + The guest session has changed its status. The status then can + be retrieved via <link to="IGuestSession::status"/>. + </desc> + </const> + <const name="Error" value="4"> + <desc>Error while executing the process.</desc> + </const> + <const name="Timeout" value="5"> + <desc> + The waiting operation timed out. This also will happen + when no event has been occurred matching the + current waiting flags in a <link to="IGuestSession::waitFor"/> call. + </desc> + </const> + <const name="WaitFlagNotSupported" value="6"> + <desc> + A waiting flag specified in the <link to="IGuestSession::waitFor"/> call + is not supported by the guest. + </desc> + </const> + </enum> + + <enum + name="GuestUserState" + uuid="b2a82b02-fd3d-4fc2-ba84-6ba5ac8be198" + > + <desc> + State a guest user has been changed to. + </desc> + + <const name="Unknown" value="0"> + <desc>Unknown state. Not being used.</desc> + </const> + <const name="LoggedIn" value="1"> + <desc>A guest user has been successfully logged into + the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="LoggedOut" value="2"> + <desc>A guest user has been successfully logged out + of the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Locked" value="3"> + <desc>A guest user has locked its account. This might + include running a password-protected screensaver + on the guest. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Unlocked" value="4"> + <desc>A guest user has unlocked its account. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Disabled" value="5"> + <desc>A guest user has been disabled by the guest OS. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Idle" value="6"> + <desc> + A guest user currently is not using the guest OS. + <note>Currently only available for Windows guests since + Windows 2000 SP2.</note> + <note>On Windows guests this function currently only supports + reporting contiguous idle times up to 49.7 days per user.</note> + 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 on the guest to + <pre>--vminfo-user-idle-threshold <ms></pre> + , or by setting the per-VM guest property + <pre>/VirtualBox/GuestAdd/VBoxService/--vminfo-user-idle-threshold <ms></pre> + with the RDONLYGUEST flag on the host. In both cases VBoxService needs + to be restarted in order to get the changes applied. + </desc> + </const> + <const name="InUse" value="7"> + <desc>A guest user continued using the guest OS after + being idle.</desc> + </const> + <const name="Created" value="8"> + <desc>A guest user has been successfully created. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Deleted" value="9"> + <desc>A guest user has been successfully deleted. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="SessionChanged" value="10"> + <desc>To guest OS has changed the session of a user. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="CredentialsChanged" value="11"> + <desc>To guest OS has changed the authentication + credentials of a user. This might include changed passwords + and authentication types. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="RoleChanged" value="12"> + <desc>To guest OS has changed the role of a user permanently, + e.g. granting / denying administrative rights. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="GroupAdded" value="13"> + <desc>To guest OS has added a user to a specific + user group. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="GroupRemoved" value="14"> + <desc>To guest OS has removed a user from a specific + user group. + <note>This property is not implemented yet!</note> + </desc> + </const> + <const name="Elevated" value="15"> + <desc>To guest OS temporarily has elevated a user + to perform a certain task. + <note>This property is not implemented yet!</note> + </desc> + </const> + </enum> + + <enum name="FileSeekType" uuid="1b73f4f3-3515-4073-a506-76878d9e2541" > @@ -8923,10 +9855,10 @@ File seeking types. </desc> - <const name="Set" value="0"> + <const name="Set" value="0"> <desc>Seek from the start of the file.</desc> </const> - <const name="Current" value="1"> + <const name="Current" value="1"> <desc>Seek from the current file position.</desc> </const> </enum> @@ -8938,10 +9870,10 @@ <desc> Guest process input flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="EndOfFile" value="1"> + <const name="EndOfFile" value="1"> <desc>End of file (input) reached.</desc> </const> </enum> @@ -8954,10 +9886,10 @@ Guest process output flags for specifying which type of output to retrieve. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flags set. Get output from stdout.</desc> </const> - <const name="StdErr" value="1"> + <const name="StdErr" value="1"> <desc>Get output from stderr.</desc> </const> </enum> @@ -8970,22 +9902,22 @@ Process waiting flags. Multiple flags can be combined. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No waiting flags specified. Do not use this.</desc> </const> - <const name="Start" value="1"> + <const name="Start" value="1"> <desc>Wait for the process being started.</desc> </const> - <const name="Terminate" value="2"> + <const name="Terminate" value="2"> <desc>Wait for the process being terminated.</desc> </const> - <const name="StdIn" value="4"> + <const name="StdIn" value="4"> <desc>Wait for stdin becoming available.</desc> </const> - <const name="StdOut" value="8"> + <const name="StdOut" value="8"> <desc>Wait for data becoming available on stdout.</desc> </const> - <const name="StdErr" value="16"> + <const name="StdErr" value="16"> <desc>Wait for data becoming available on stderr.</desc> </const> </enum> @@ -8999,7 +9931,7 @@ more information see <link to="ProcessWaitForFlag"/>) the waiting result can vary based on the processes' current status. - To wait for a gust process to terminate after it has been + To wait for a guest process to terminate after it has been created by <link to="IGuestSession::processCreate"/> or <link to="IGuestSession::processCreateEx"/> one would specify ProcessWaitResult_Terminate. @@ -9009,43 +9941,43 @@ ProcessWaitResult_StdErr. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No result was returned. Not being used.</desc> </const> - <const name="Start" value="1"> + <const name="Start" value="1"> <desc>The process has been started.</desc> </const> - <const name="Terminate" value="2"> + <const name="Terminate" value="2"> <desc>The process has been terminated.</desc> </const> - <const name="Status" value="3"> + <const name="Status" value="3"> <desc> The process has changed its status. The status then can be retrieved via <link to="IProcess::status"/>. </desc> </const> - <const name="Error" value="4"> + <const name="Error" value="4"> <desc>Error while executing the process.</desc> </const> - <const name="Timeout" value="5"> + <const name="Timeout" value="5"> <desc> The waiting operation timed out. This also will happen - when no event has been occured matching the + when no event has been occurred matching the current waiting flags in a <link to="IProcess::waitFor"/> call. </desc> </const> - <const name="StdIn" value="6"> + <const name="StdIn" value="6"> <desc> The process signalled that stdin became available for writing and that the process awaits input now.</desc> </const> - <const name="StdOut" value="7"> + <const name="StdOut" value="7"> <desc>Data on stdout became available for reading.</desc> </const> - <const name="StdErr" value="8"> + <const name="StdErr" value="8"> <desc>Data on stderr became available for reading.</desc> </const> - <const name="WaitFlagNotSupported" value="9"> + <const name="WaitFlagNotSupported" value="9"> <desc> A waiting flag specified in the <link to="IProcess::waitFor"/> call is not supported by the guest. @@ -9060,17 +9992,20 @@ <desc> File copying flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="Recursive" value="1"> - <desc>Copy directories recursively.</desc> + <const name="Recursive" value="1"> + <desc>Copy directories recursively. + This flag is not implemented yet.</desc> </const> - <const name="Update" value="2"> - <desc>Only copy when the source file is newer than the destination file or when the destination file is missing.</desc> + <const name="Update" value="2"> + <desc>Only copy when the source file is newer than the destination file + or when the destination file is missing. This flag is not implemented + yet.</desc> </const> - <const name="FollowLinks" value="4"> - <desc>Follow symbolic links.</desc> + <const name="FollowLinks" value="4"> + <desc>Follow symbolic links. This flag is not implemented yet.</desc> </const> </enum> @@ -9081,10 +10016,10 @@ <desc> Directory creation flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="Parents" value="1"> + <const name="Parents" value="1"> <desc>No error if existing, make parent directories as needed.</desc> </const> </enum> @@ -9097,13 +10032,13 @@ Directory recursive removement flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="ContentAndDir" value="1"> + <const name="ContentAndDir" value="1"> <desc>Delete the content of the directory and the directory itself.</desc> </const> - <const name="ContentOnly" value="2"> + <const name="ContentOnly" value="2"> <desc>Only delete the content of the directory, omit the directory it self.</desc> </const> </enum> @@ -9116,16 +10051,16 @@ Path renaming flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="NoReplace" value="1"> + <const name="NoReplace" value="1"> <desc>Do not replace anything.</desc> </const> - <const name="Replace" value="2"> + <const name="Replace" value="2"> <desc>This will replace attempt any target which isn't a directory.</desc> </const> - <const name="NoSymlinks" value="4"> + <const name="NoSymlinks" value="4"> <desc>Don't allow symbolic links as part of the path.</desc> </const> </enum> @@ -9138,29 +10073,29 @@ Guest process execution flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="WaitForProcessStartOnly" value="1"> + <const name="WaitForProcessStartOnly" value="1"> <desc>Only use the specified timeout value to wait for starting the guest process - the guest process itself then uses an infinite timeout.</desc> </const> - <const name="IgnoreOrphanedProcesses" value="2"> + <const name="IgnoreOrphanedProcesses" value="2"> <desc>Do not report an error when executed processes are still alive when VBoxService or the guest OS is shutting down.</desc> </const> - <const name="Hidden" value="4"> + <const name="Hidden" value="4"> <desc>Do not show the started process according to the guest OS guidelines.</desc> </const> - <const name="NoProfile" value="8"> + <const name="NoProfile" value="8"> <desc>Do not use the user's profile data when exeuting a process. Only available for Windows guests.</desc> </const> - <const name="WaitForStdOut" value="16"> + <const name="WaitForStdOut" value="16"> <desc>The guest process waits until all data from stdout is read out.</desc> </const> - <const name="WaitForStdErr" value="32"> + <const name="WaitForStdErr" value="32"> <desc>The guest process waits until all data from stderr is read out.</desc> </const> - <const name="ExpandArguments" value="64"> + <const name="ExpandArguments" value="64"> <desc>Expands environment variables in process arguments.</desc> </const> </enum> @@ -9173,10 +10108,10 @@ Process priorities. </desc> - <const name="Invalid" value="0"> + <const name="Invalid" value="0"> <desc>Invalid priority, do not use.</desc> </const> - <const name="Default" value="1"> + <const name="Default" value="1"> <desc>Default process priority determined by the OS.</desc> </const> </enum> @@ -9189,13 +10124,13 @@ Symbolic link types. </desc> - <const name="Unknown" value="0"> + <const name="Unknown" value="0"> <desc>It is not known what is being targeted.</desc> </const> - <const name="Directory" value="1"> + <const name="Directory" value="1"> <desc>The link targets a directory.</desc> </const> - <const name="File" value="2"> + <const name="File" value="2"> <desc>The link targets a file (or whatever else).</desc> </const> </enum> @@ -9208,10 +10143,10 @@ Symbolic link reading flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flags set.</desc> </const> - <const name="NoSymlinks" value="1"> + <const name="NoSymlinks" value="1"> <desc>Don't allow symbolic links as part of the path.</desc> </const> </enum> @@ -9223,41 +10158,97 @@ <desc> Process execution statuses. </desc> - <const name="Undefined" value="0"> + + <const name="Undefined" value="0"> <desc>Process is in an undefined state.</desc> </const> - - <const name="Starting" value="10"> + <const name="Starting" value="10"> <desc>Process is being started.</desc> </const> - <const name="Started" value="100"> + <const name="Started" value="100"> <desc>Process has been started.</desc> </const> - <const name="Paused" value="110"> + <const name="Paused" value="110"> <desc>Process has been paused.</desc> </const> - <const name="Terminating" value="480"> + <const name="Terminating" value="480"> <desc>Process is being terminated.</desc> </const> - <const name="TerminatedNormally" value="500"> + <const name="TerminatedNormally" value="500"> <desc>Process terminated normally.</desc> </const> - <const name="TerminatedSignal" value="510"> + <const name="TerminatedSignal" value="510"> <desc>Process terminated via signal.</desc> </const> - <const name="TerminatedAbnormally" value="511"> + <const name="TerminatedAbnormally" value="511"> <desc>Process terminated abnormally.</desc> </const> - <const name="TimedOutKilled" value="512"> + <const name="TimedOutKilled" value="512"> <desc>Process timed out and was killed.</desc> </const> - <const name="TimedOutAbnormally" value="513"> + <const name="TimedOutAbnormally" value="513"> <desc>Process timed out and was not killed successfully.</desc> </const> - <const name="Down" value="600"> + <const name="Down" value="600"> <desc>Service/OS is stopping, process was killed.</desc> </const> - <const name="Error" value="800"> + <const name="Error" value="800"> + <desc>Something went wrong.</desc> + </const> + </enum> + + <enum + name="ProcessInputStatus" + uuid="a4a0ef9c-29cc-4805-9803-c8215ae9da6c" + > + <desc> + Process input statuses. + </desc> + + <const name="Undefined" value="0"> + <desc>Undefined state.</desc> + </const> + <const name="Broken" value="1"> + <desc>Input pipe is broken.</desc> + </const> + <const name="Available" value="10"> + <desc>Input pipe became available for writing.</desc> + </const> + <const name="Written" value="50"> + <desc>Data has been successfully written.</desc> + </const> + <const name="Overflow" value="100"> + <desc>Too much input data supplied, data overflow.</desc> + </const> + </enum> + + <enum + name="FileStatus" + uuid="8c86468b-b97b-4080-8914-e29f5b0abd2c" + > + <desc> + File statuses. + </desc> + + <const name="Undefined" value="0"> + <desc>File is in an undefined state.</desc> + </const> + <const name="Opening" value="10"> + <desc>Guest file is opening.</desc> + </const> + <const name="Open" value="100"> + <desc>Guest file has been successfully opened.</desc> + </const> + <const name="Closing" value="150"> + <desc>Guest file closing.</desc> + </const> + <const name="Closed" value="200"> + <desc>Guest file has been closed.</desc> + </const> + <const name="Down" value="600"> + <desc>Service/OS is stopping, guest file was closed.</desc> + </const> + <const name="Error" value="800"> <desc>Something went wrong.</desc> </const> </enum> @@ -9270,31 +10261,31 @@ File system object type. </desc> - <const name="Undefined" value="0"> + <const name="Undefined" value="0"> <desc>Type is undefined / unknown.</desc> </const> - <const name="FIFO" value="1"> + <const name="FIFO" value="1"> <desc>Named pipe.</desc> </const> - <const name="DevChar" value="10"> + <const name="DevChar" value="10"> <desc>Character device.</desc> </const> - <const name="DevBlock" value="11"> + <const name="DevBlock" value="11"> <desc>Block device.</desc> </const> - <const name="Directory" value="50"> + <const name="Directory" value="50"> <desc>Directory.</desc> </const> - <const name="File" value="80"> + <const name="File" value="80"> <desc>File.</desc> </const> - <const name="Symlink" value="100"> + <const name="Symlink" value="100"> <desc>Symlink.</desc> </const> - <const name="Socket" value="200"> + <const name="Socket" value="200"> <desc>Socket.</desc> </const> - <const name="Whiteout" value="400"> + <const name="Whiteout" value="400"> <desc>Whiteout.</desc> </const> </enum> @@ -9307,19 +10298,19 @@ Possible actions within an Drag and Drop operation. </desc> - <const name="Ignore" value="0"> + <const name="Ignore" value="0"> <desc>Do nothing.</desc> </const> - <const name="Copy" value="1"> + <const name="Copy" value="1"> <desc>Copy the item to the target.</desc> </const> - <const name="Move" value="2"> + <const name="Move" value="2"> <desc>Move the item to the target.</desc> </const> - <const name="Link" value="3"> + <const name="Link" value="3"> <desc>Link the item from within the target.</desc> </const> </enum> @@ -9331,17 +10322,17 @@ <desc> Directory open flags. </desc> - <const name="None" value="0"> + <const name="None" value="0"> <desc>No flag set.</desc> </const> - <const name="NoSymlinks" value="1"> + <const name="NoSymlinks" value="1"> <desc>Don't allow symbolic links as part of the path.</desc> </const> </enum> <interface name="IGuestSession" extends="$unknown" - uuid="57eb82a8-822b-42c1-9d1c-5c54bc3d3250" + uuid="5b28703c-07b6-4fcb-afba-ac199b309752" wsmap="managed" > <desc> @@ -9349,8 +10340,11 @@ every operation will use the same credentials specified when creating the session object via <link to="IGuest::createSession"/>. - There can be a maximum of 32 sessions at once per VM. Each session keeps - track of its started guest processes, opened guest files or guest directories. + There can be a maximum of 32 sessions at once per VM, whereas session 0 + is reserved for the root session. 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 its started + guest processes, opened guest files or guest directories. To work on guest files or directories a guest session offers methods to open or create such objects (see <link to="IGuestSession::fileOpen"/> or <link to="IGuestSession::directoryOpen"/> for example). @@ -9371,22 +10365,18 @@ users on the guest. </desc> </attribute> - <attribute name="domain" type="wstring" readonly="yes"> <desc>Returns the domain name used by this session to impersonate users on the guest. </desc> </attribute> - <attribute name="name" type="wstring" readonly="yes"> <desc>Returns the session's friendly name.</desc> </attribute> - <attribute name="id" type="unsigned long" readonly="yes"> <desc>Returns the internal session ID.</desc> </attribute> - - <attribute name="timeout" type="unsigned long" readonly="no"> + <attribute name="timeout" type="unsigned long"> <desc> Returns the session timeout (in ms). <result name="E_NOTIMPL"> @@ -9394,36 +10384,45 @@ </result> </desc> </attribute> - + <attribute name="protocolVersion" type="unsigned long" readonly="yes"> + <desc>Returns the protocol version which is used by this session to + communicate with the guest.</desc> + </attribute> + <attribute name="status" type="GuestSessionStatus" readonly="yes"> + <desc>Returns the current session status.</desc> + </attribute> <attribute name="environment" type="wstring" safearray="yes"> <desc> Returns the current session environment. </desc> </attribute> - <attribute name="processes" type="IGuestProcess" readonly="yes" safearray="yes"> <desc> Returns all current guest processes. </desc> </attribute> - <attribute name="directories" type="IGuestDirectory" readonly="yes" safearray="yes"> <desc> Returns all currently opened guest directories. </desc> </attribute> - <attribute name="files" type="IGuestFile" readonly="yes" safearray="yes"> <desc> Returns all currently opened guest files. </desc> </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for guest session events. + </desc> + </attribute> <method name="close"> <desc> Closes this session. All opened guest directories, files and processes which are not referenced by clients anymore will be - uninitialized. + closed. Guest processes which fall into this category and still + are running on the guest will be terminated automatically. </desc> </method> @@ -9499,24 +10498,24 @@ guest type. </result> <result name="E_INVALIDARG"> - Invalid argument. This includes an incorrectly formatted template, + Invalid argument. This includes an incorrectly formatted template, or a non-absolute path. </result> <result name="VBOX_E_IPRT_ERROR"> - The temporary directory could not be created. Possible reasons + The temporary directory could not be created. Possible reasons include a non-existing path or an insecure path when the secure option was requested. </result> </desc> <param name="templateName" type="wstring" dir="in"> - <desc>Template for the name of the directory to create. This must - contain at least one 'X' character. The first group of consecutive + <desc>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.</desc> </param> <param name="mode" type="unsigned long" dir="in"> - <desc>The mode of the directory to create. Use 0700 unless there are - reasons not to. This parameter is ignored if "secure" is specified. + <desc>The mode of the directory to create. Use 0700 unless there are + reasons not to. This parameter is ignored if "secure" is specified. </desc> </param> <param name="path" type="wstring" dir="in"> @@ -9526,8 +10525,8 @@ <desc>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.</desc> + after it has been created. Also causes the mode specified to be + ignored. May not be supported on all guest types.</desc> </param> <param name="directory" type="wstring" dir="return"> <desc>On success this will contain the name of the directory created @@ -9599,10 +10598,6 @@ <method name="directoryRemove"> <desc> Removes a guest directory if not empty. - - <result name="E_NOTIMPL"> - The method is not implemented yet. - </result> </desc> <param name="path" type="wstring" dir="in"> <desc>Full path of directory to remove.</desc> @@ -9612,10 +10607,6 @@ <method name="directoryRemoveRecursive"> <desc> Removes a guest directory recursively. - - <result name="E_NOTIMPL"> - The method is not implemented yet. - </result> </desc> <param name="path" type="wstring" dir="in"> <desc>Full path of directory to remove recursively.</desc> @@ -9624,17 +10615,14 @@ <desc>Remove flags; see <link to="DirectoryRemoveRecFlag"/> for more information.</desc> </param> <param name="progress" type="IProgress" dir="return"> - <desc>Progress object to track the operation completion.</desc> + <desc>Progress object to track the operation completion. This is not implemented + yet and therefore this method call will block until deletion is completed.</desc> </param> </method> <method name="directoryRename"> <desc> Renames a directory on the guest. - - <result name="E_NOTIMPL"> - The method is not implemented yet. - </result> </desc> <param name="source" type="wstring" dir="in"> <desc>Source directory to rename.</desc> @@ -9710,7 +10698,7 @@ <method name="environmentUnset"> <desc> - Unsets session environment variable. + Unsets a session environment variable. <result name="VBOX_E_IPRT_ERROR"> Error while unsetting the session environment variable. @@ -9741,14 +10729,14 @@ </desc> <param name="templateName" type="wstring" dir="in"> <desc>Template for the name of the file to create. This must contain - at least one 'X' character. The first group of consecutive 'X' + 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. </desc> </param> <param name="mode" type="unsigned long" dir="in"> <desc>The mode of the file to create. Use 0700 unless there are - reasons not to. This parameter is ignored if "secure" is specified. + reasons not to. This parameter is ignored if "secure" is specified. </desc> </param> <param name="path" type="wstring" dir="in"> @@ -9758,7 +10746,7 @@ <desc>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. + it has been created. Also causes the mode specified to be ignored. May not be supported on all guest types.</desc> </param> <param name="file" type="IGuestFile" dir="return"> @@ -9816,16 +10804,91 @@ <desc>Full path to file to open.</desc> </param> <param name="openMode" type="wstring" dir="in"> - <desc>The file open mode.</desc> + <desc>The file opening mode. This describes the wanted access to a file, whereas + the parameter must be one of the following: + <ul> + <li><tt>"r"</tt>: Opens a file for reading.</li> + <li><tt>"r+"</tt>: Opens a file for reading and writing.</li> + <li><tt>"w"</tt>: Opens a file for writing.</li> + <li><tt>"w+"</tt>: Opens a file for writing and reading.</li> + </ul> + </desc> </param> <param name="disposition" type="wstring" dir="in"> - <desc>The file disposition.</desc> + <desc>The file disposition. This describes the action to take in case a + file exists or does not exist, whereas the parameter must be one of the + following: + <ul> + <li><tt>"ca"</tt>: Creates a new file, always. Overwrites an existing file.</li> + <li><tt>"ce"</tt>: Creates a new file if it does not exist. Fail if exist.</li> + <li><tt>"oa"</tt>: Opens an existing file and places the file pointer at the + end of the file, if opened with write access. Create the file if it does not exist.</li> + <li><tt>"oc"</tt>: Opens an existing file or create it if it does not exist.</li> + <li><tt>"oe"</tt>: Opens an existing file or fail if it does not exist.</li> + <li><tt>"ot"</tt>: Opens and truncate an existing file or fail if it does not exist.</li> + </ul> + </desc> </param> <param name="creationMode" type="unsigned long" dir="in"> - <desc>The file creation mode.</desc> + <desc>The mode to create the file with. Must be a three-digit octal number which + represents the access rights for the file.</desc> + </param> + <param name="file" type="IGuestFile" dir="return"> + <desc><link to="IGuestFile"/> object representing the opened file.</desc> + </param> + </method> + + <method name="fileOpenEx"> + <desc> + Opens a file and creates a <link to="IGuestFile"/> object that + can be used for further operations, extended version. + + <result name="VBOX_E_OBJECT_NOT_FOUND"> + File to open was not found. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Error while opening the file. + </result> + </desc> + <param name="path" type="wstring" dir="in"> + <desc>Full path to file to open.</desc> + </param> + <param name="openMode" type="wstring" dir="in"> + <desc>The file opening mode. This describes the wanted access to a file, whereas + the parameter must be one of the following: + <ul> + <li><tt>"r"</tt>: Opens a file for reading.</li> + <li><tt>"r+"</tt>: Opens a file for reading and writing.</li> + <li><tt>"w"</tt>: Opens a file for writing.</li> + <li><tt>"w+"</tt>: Opens a file for writing and reading.</li> + </ul> + </desc> + </param> + <param name="disposition" type="wstring" dir="in"> + <desc>The file disposition. This describes the action to take in case a + file exists or does not exist, whereas the parameter must be one of the + following: + <ul> + <li><tt>"ca"</tt>: Creates a new file, always. Overwrites an existing file.</li> + <li><tt>"ce"</tt>: Creates a new file if it does not exist. Fail if exist.</li> + <li><tt>"oa"</tt>: Opens an existing file and places the file pointer at the + end of the file, if opened with write access. Create the file if it does not exist.</li> + <li><tt>"oc"</tt>: Opens an existing file or create it if it does not exist.</li> + <li><tt>"oe"</tt>: Opens an existing file or fail if it does not exist.</li> + <li><tt>"ot"</tt>: Opens and truncate an existing file or fail if it does not exist.</li> + </ul> + </desc> + </param> + <param name="sharingMode" type="wstring" dir="in"> + <desc>The file sharing mode on the guest. This parameter + is not implemented yet. Pass an empty string here.</desc> + </param> + <param name="creationMode" type="unsigned long" dir="in"> + <desc>The mode to create the file with. Must be a three-digit octal number which + represents the access rights for the file.</desc> </param> <param name="offset" type="long long" dir="in"> - <desc>The initial read/write offset.</desc> + <desc>The initial read/write offset (in bytes).</desc> </param> <param name="file" type="IGuestFile" dir="return"> <desc><link to="IGuestFile"/> object representing the opened file.</desc> @@ -9873,10 +10936,6 @@ <method name="fileRename"> <desc> Renames a file on the guest. - - <result name="E_NOTIMPL"> - The method is not implemented yet. - </result> </desc> <param name="source" type="wstring" dir="in"> <desc>Source file to rename.</desc> @@ -9907,27 +10966,24 @@ <method name="processCreate"> <desc> - Executes an existing program inside the guest VM. + Creates a new process running on the guest. The new process will be + started asynchronously, meaning on return of this function it is not + guaranteed that the guest process is in a started state. To wait for + successful startup, use the <link to="IProcess::waitFor"/> call. <note> Starting at VirtualBox 4.2 guest process execution by default is limited to serve up to 255 guest processes at a time. If all 255 guest processes - are still active and running, starting a new guest process will result in an + are still active and running, creating a new guest process will result in an appropriate error message. If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr is / are set, the guest process will not exit until all data from the specified stream(s) is / are read out. - - To raise or lower the guest process execution limit, either the guest property - "/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService' - command line by specifying "--control-procs-max-kept" needs to be modified. - A restart of the guest OS is required afterwards. To serve unlimited guest - processes, a value of "0" needs to be set (not recommended). </note> <result name="VBOX_E_IPRT_ERROR"> - Could not create process. + Error creating guest process. </result> </desc> <param name="command" type="wstring" dir="in"> @@ -9941,13 +10997,12 @@ </param> <param name="environment" type="wstring" dir="in" safearray="yes"> <desc> - Environment variables that can be set while the command is being + <para>Environment variables that can be set while the command is being executed, in form of "NAME=VALUE"; one pair per entry. To unset a - variable just set its name ("NAME") without a value. - - This parameter can be used to override environment variables set by + variable just set its name ("NAME") without a value.</para> + <para>This parameter can be used to override environment variables set by the guest session, which will be applied to the newly started process - in any case. + in any case.</para> </desc> </param> <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes"> @@ -9958,8 +11013,10 @@ </param> <param name="timeoutMS" type="unsigned long" dir="in"> <desc> - Timeout (in ms) to wait for the operation to complete. - Pass 0 for an infinite timeout. + 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 + <link to="ProcessStatus"/> for more information. </desc> </param> <param name="guestProcess" type="IGuestProcess" dir="return"> @@ -9969,29 +11026,11 @@ <method name="processCreateEx"> <desc> - Executes an existing program inside the guest VM. Extended version for - also setting the process priority and affinity. - - <note> - Starting at VirtualBox 4.2 guest process execution by default is limited - to serve up to 255 guest processes at a time. If all 255 guest processes - are still active and running, starting a new guest process will result in an - appropriate error message. - - If ProcessCreateFlag_WaitForStdOut and / or respectively ProcessCreateFlag_WaitForStdErr - is / are set, the guest process will not exit until all data from the specified - stream(s) is / are read out. - - To raise or lower the guest process execution limit, either the guest property - "/VirtualBox/GuestAdd/VBoxService/--control-procs-max-kept" or VBoxService' - command line by specifying "--control-procs-max-kept" needs to be modified. - A restart of the guest OS is required afterwards. To serve unlimited guest - processes, a value of "0" needs to be set (not recommended). - </note> + <para>Creates a new process running on the guest. Extended version for + also setting the process priority and affinity.</para> - <result name="VBOX_E_IPRT_ERROR"> - Could not create process. - </result> + <para>See <link to="IGuestSession::processCreate"/> for more + information.</para> </desc> <param name="command" type="wstring" dir="in"> <desc> @@ -10004,13 +11043,12 @@ </param> <param name="environment" type="wstring" dir="in" safearray="yes"> <desc> - Environment variables that can be set while the command is being + <para>Environment variables that can be set while the command is being executed, in form of "NAME=VALUE"; one pair per entry. To unset a - variable just set its name ("NAME") without a value. - - This parameter can be used to override environment variables set by + variable just set its name ("NAME") without a value.</para> + <para>This parameter can be used to override environment variables set by the guest session, which will be applied to the newly started process - in any case. + in any case.</para> </desc> </param> <param name="flags" type="ProcessCreateFlag" dir="in" safearray="yes"> @@ -10021,8 +11059,10 @@ </param> <param name="timeoutMS" type="unsigned long" dir="in"> <desc> - Timeout (in ms) to wait for the operation to complete. - Pass 0 for an infinite timeout. + 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 + <link to="ProcessStatus"/> for more information. </desc> </param> <param name="priority" type="ProcessPriority" dir="in"> @@ -10140,48 +11180,105 @@ </param> </method> + <method name="waitFor"> + <desc> + Waits for one more events to happen. + </desc> + <param name="waitFor" type="unsigned long" dir="in"> + <desc> + Specifies what to wait for; + see <link to="GuestSessionWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="GuestSessionWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="GuestSessionWaitResult"/> for more information. + </desc> + </param> + </method> + + <method name="waitForArray"> + <desc> + Waits for one more events to happen. + Scriptable version of <link to="#waitFor" />. + </desc> + <param name="waitFor" type="GuestSessionWaitForFlag" dir="in" safearray="yes"> + <desc> + Specifies what to wait for; + see <link to="GuestSessionWaitForFlag"/> for more information. + </desc> + </param> + <param name="timeoutMS" type="unsigned long" dir="in"> + <desc> + Timeout (in ms) to wait for the operation to complete. + Pass 0 for an infinite timeout. + </desc> + </param> + <param name="reason" type="GuestSessionWaitResult" dir="return"> + <desc> + The overall wait result; + see <link to="GuestSessionWaitResult"/> for more information. + </desc> + </param> + </method> + </interface> <interface name="IProcess" extends="$unknown" - uuid="08864d56-96ab-418b-adbc-5a679532aeb0" + uuid="5a4fe06d-8cb1-40ff-ac9e-9676e32f706e" wsmap="managed" > <desc> Abstract parent interface for processes handled by VirtualBox. </desc> - <attribute name="PID" type="unsigned long" readonly="yes"> + + <attribute name="arguments" type="wstring" readonly="yes" safearray="yes"> <desc> - The process ID (PID). + The arguments this process is using for execution. </desc> </attribute> - <attribute name="status" type="ProcessStatus" readonly="yes"> + <attribute name="environment" type="wstring" readonly="yes" safearray="yes"> <desc> - The current process status; see <link to="ProcessStatus"/> - for more information. + The environment block this process is using during execution. </desc> </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for VirtualBox events. + </desc> + </attribute> + <attribute name="executablePath" type="wstring" readonly="yes"> + <desc>Full path of the actual executable image.</desc> + </attribute> <attribute name="exitCode" type="long" readonly="yes"> <desc> The exit code. Only available when the process has been terminated normally. </desc> </attribute> - <attribute name="environment" type="wstring" readonly="yes" safearray="yes"> + <attribute name="name" type="wstring" readonly="yes"> <desc> - The environment block this process is using during execution. + The friendly name of this process. </desc> </attribute> - <attribute name="arguments" type="wstring" readonly="yes" safearray="yes"> + <attribute name="PID" type="unsigned long" readonly="yes"> <desc> - The arguments this process is using for execution. + The process ID (PID). </desc> </attribute> - <attribute name="executablePath" type="wstring" readonly="yes"> - <desc>Full path of the actual executable image.</desc> - </attribute> - <attribute name="name" type="wstring" readonly="yes"> - <desc>The friendly name of this process.</desc> + <attribute name="status" type="ProcessStatus" readonly="yes"> + <desc> + The current process status; see <link to="ProcessStatus"/> + for more information. + </desc> </attribute> <method name="waitFor"> @@ -10316,6 +11413,9 @@ <method name="terminate"> <desc> Terminates (kills) a running process. + <note>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.</note> </desc> </method> </interface> @@ -10367,7 +11467,8 @@ </result> </desc> <param name="objInfo" type="IFsObjInfo" dir="return"> - <desc>Object information of the current directory entry read. Also see <link to="IFsObjInfo"/>.</desc> + <desc>Object information of the current directory entry read. Also see + <link to="IFsObjInfo"/>.</desc> </param> </method> </interface> @@ -10385,7 +11486,7 @@ <interface name="IFile" extends="$unknown" - uuid="b702a560-6139-4a8e-a892-bbf14b97bf97" + uuid="5ec56ea3-b55d-4bdb-8c4f-5f9fb26b894b" wsmap="managed" > <desc> @@ -10396,22 +11497,32 @@ The creation mode. </desc> </attribute> - <attribute name="disposition" type="unsigned long" readonly="yes"> + <attribute name="disposition" type="wstring" readonly="yes"> <desc> The disposition mode. </desc> </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for guest session events. + </desc> + </attribute> <attribute name="fileName" type="wstring" readonly="yes"> <desc> Full path of the actual file name of this file. </desc> </attribute> + <attribute name="id" type="unsigned long" readonly="yes"> + <desc> + The file's ID. + </desc> + </attribute> <attribute name="initialSize" type="long long" readonly="yes"> <desc> The initial size in bytes when opened. </desc> </attribute> - <attribute name="openMode" type="unsigned long" readonly="yes"> + <attribute name="openMode" type="wstring" readonly="yes"> <desc> The open mode. </desc> @@ -10421,6 +11532,11 @@ Current read/write offset in bytes. </desc> </attribute> + <attribute name="status" type="FileStatus" readonly="yes"> + <desc> + Current file status. + </desc> + </attribute> <method name="close"> <desc> @@ -10438,7 +11554,8 @@ </result> </desc> <param name="objInfo" type="IFsObjInfo" dir="return"> - <desc>Object information of this file. Also see <link to="IFsObjInfo"/>.</desc> + <desc>Object information of this file. Also see + <link to="IFsObjInfo"/>.</desc> </param> </method> @@ -10705,7 +11822,7 @@ <interface name="IGuest" extends="$unknown" - uuid="19c32350-0618-4ede-b0c3-2b4311bf0d9b" + uuid="8011a1b1-6adb-4ffb-a37e-20abdaee4650" wsmap="managed" > <desc> @@ -10753,6 +11870,12 @@ </desc> </attribute> + <attribute name="eventSource" type="IEventSource" readonly="yes"> + <desc> + Event source for guest events. + </desc> + </attribute> + <attribute name="facilities" type="IAdditionsFacility" readonly="yes" safearray="yes"> <desc> Array of current known facilities. Only returns facilities where a status is known, @@ -10892,7 +12015,7 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> <param name="y" type="unsigned long" dir="in"> <desc>y-position of the event.</desc> @@ -10926,7 +12049,7 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> <param name="x" type="unsigned long" dir="in"> <desc>x-position of the event.</desc> @@ -10960,7 +12083,7 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> </method> @@ -10976,7 +12099,7 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> <param name="x" type="unsigned long" dir="in"> <desc>x-position of the event.</desc> @@ -11013,7 +12136,7 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> <param name="format" type="wstring" dir="in"> <desc>The mime type the data is in.</desc> @@ -11040,9 +12163,9 @@ </desc> <param name="screenId" type="unsigned long" dir="in"> - <desc>The screen id where the Drag and Drop event occured.</desc> + <desc>The screen id where the Drag and Drop event occurred.</desc> </param> - <param name="format" type="wstring" dir="out" safearray="yes"> + <param name="formats" type="wstring" dir="out" safearray="yes"> <desc>On return the supported mime types.</desc> </param> <param name="allowedActions" type="DragAndDropAction" dir="out" safearray="yes"> @@ -11055,7 +12178,7 @@ <method name="dragGHDropped"> <desc> - Informs the guest that a drop event occured for a pending Drag and Drop event. + Informs the guest that a drop event occurred for a pending Drag and Drop event. This is used in Guest - Host direction. @@ -11095,7 +12218,11 @@ <method name="createSession"> <desc> - Creates a new guest session for controlling the guest. + 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 <link to="IGuestSession::waitFor"/> + call. A guest session represents one impersonated user account on the guest, so every operation will use the same credentials specified when creating @@ -11109,6 +12236,10 @@ or create such objects (see <link to="IGuestSession::fileOpen"/> or <link to="IGuestSession::directoryOpen"/> for example). + There can be up to 2048 objects (guest processes, files or directories) + a time per guest session. Exceeding the limit will result in an appropriate + error message. + 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. @@ -11198,7 +12329,14 @@ </desc> <param name="source" type="wstring" dir="in"> <desc> - Path to the Guest Additions .ISO file to use for the upate. + Path to the Guest Additions .ISO file to use for the update. + </desc> + </param> + <param name="arguments" type="wstring" dir="in" safearray="yes"> + <desc> + Optional command line arguments to use for the Guest Additions + installer. Useful for retrofitting features which weren't installed + before on the guest. </desc> </param> <param name="flags" type="AdditionsUpdateFlag" dir="in" safearray="yes"> @@ -11352,7 +12490,7 @@ <attribute name="timeout" type="unsigned long"> <desc> When non-zero, this specifies the number of milliseconds after which - the operation will automatically be canceled. This can only be set on + the operation will automatically be canceled. This can only be set on cancelable objects. </desc> </attribute> @@ -11373,10 +12511,10 @@ 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 + 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 adviced wait for short periods + 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. @@ -11618,7 +12756,7 @@ <method name="getChildrenCount" const="yes"> <desc> - Returns the number of direct childrens of this snapshot. + Returns the number of direct children of this snapshot. </desc> <param name="childrenCount" type="unsigned long" dir="return"> <desc> @@ -11749,43 +12887,43 @@ <see><link to="IMedium"/></see> </desc> - <const name="Standard" value="0"> + <const name="Standard" value="0"> <desc> No particular variant requested, results in using the backend default. </desc> </const> - <const name="VmdkSplit2G" value="0x01"> + <const name="VmdkSplit2G" value="0x01"> <desc> VMDK image split in chunks of less than 2GByte. </desc> </const> - <const name="VmdkRawDisk" value="0x02"> + <const name="VmdkRawDisk" value="0x02"> <desc> VMDK image representing a raw disk. </desc> </const> - <const name="VmdkStreamOptimized" value="0x04"> + <const name="VmdkStreamOptimized" value="0x04"> <desc> VMDK streamOptimized image. Special import/export format which is read-only/append-only. </desc> </const> - <const name="VmdkESX" value="0x08"> + <const name="VmdkESX" value="0x08"> <desc> VMDK format variant used on ESX products. </desc> </const> - <const name="Fixed" value="0x10000"> + <const name="Fixed" value="0x10000"> <desc> Fixed image. Only allowed for base images. </desc> </const> - <const name="Diff" value="0x20000"> + <const name="Diff" value="0x20000"> <desc> Differencing image. Only allowed for child images. </desc> </const> - <const name="NoCreateDir" value="0x40000000"> + <const name="NoCreateDir" value="0x40000000"> <desc> Special flag which suppresses automatic creation of the subdirectory. Only used when passing the medium variant as an input parameter. @@ -11795,7 +12933,7 @@ <interface name="IMediumAttachment" extends="$unknown" - uuid="5ee464d6-0613-4331-b154-7ce12170ef9f" + uuid="4b252567-5d4e-4db8-b3c8-569ec1c9236c" wsmap="struct" > <desc> @@ -11831,7 +12969,7 @@ disk is associated with the machine and used for hard disk operations. This also means that if <link to="IMachine::attachDevice"/> performs a direct attachment then the same hard disk will be returned in response - to the subsequent <link to="IMachine::getMedium"/> call; however if + to the subsequent <link to="IMachine::getMedium"/> call; however if an indirect attachment is performed then <link to="IMachine::getMedium"/> will return the implicitly created differencing hard disk, not the original one passed to <link @@ -11882,7 +13020,7 @@ <link to="IMachine::saveSettings"/> 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 - <link to="IMachine::discardSettings"/> before the settings + <link to="IMachine::discardSettings"/> before the settings are saved (committed). Note that if <link to="IMachine::discardSettings"/> is called after @@ -12025,6 +13163,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc>Whether the associated medium supports discarding unused blocks.</desc> </attribute> + <attribute name="hotPluggable" type="boolean" readonly="yes"> + <desc>Whether this attachment is hot pluggable or not.</desc> + </attribute> + <attribute name="bandwidthGroup" type="IBandwidthGroup" readonly="yes"> <desc>The bandwidth group this medium attachment is assigned to.</desc> </attribute> @@ -12033,7 +13175,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IMedium" extends="$unknown" - uuid="29989373-b111-4654-8493-2e1176cba890" + uuid="05f2bbb6-a3a6-4fb9-9b49-6d0dda7142ac" wsmap="managed" > <desc> @@ -12117,7 +13259,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) See <link to="IVirtualBox::openMedium" /> for more information. Media are removed from media registries by the <link to="IMedium::close"/>, - <link to="#deleteStorage"/> and <link to="#mergeTo"/> methods. + <link to="#deleteStorage"/> and <link to="#mergeTo"/> methods. <h3>Accessibility checks</h3> @@ -12238,34 +13380,22 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> - <attribute name="variant" type="unsigned long" readonly="yes"> + <attribute name="variant" type="MediumVariant" safearray="yes" readonly="yes"> <desc> Returns the storage format variant information for this medium - as a combination of the flags described at <link to="MediumVariant" />. + as an array of the flags described at <link to="MediumVariant" />. Before <link to="#refreshState"/> is called this method returns an undefined value. </desc> </attribute> - <attribute name="location" type="wstring"> + <attribute name="location" type="wstring" readonly="yes"> <desc> 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. - - Some medium types may support changing the storage unit location by - simply changing the value of this property. If this operation is not - supported, the implementation will return E_NOTIMPL in attempt to set - this attribute's value. - - When setting a value of the location attribute which is a regular file - in the host's file system, the given file name may be either relative to - the <link to="IVirtualBox::homeFolder">VirtualBox home folder</link> 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. </desc> </attribute> @@ -12445,10 +13575,6 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) and cannot be changed later. <note> - Reading this property on a differencing medium will return the size - of its <link to="#base"/> medium. - </note> - <note> For media whose state is <link to="#state"/> is <link to="MediumState_Inaccessible"/>, the value of this property is the last known logical size. For <link to="MediumState_NotCreated"/> @@ -12642,10 +13768,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) A medium is also locked for reading when it is the source of a write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>. - The medium locked for reading must be unlocked using the <link - to="#unlockRead"/> method. Calls to <link to="#lockRead"/> - can be nested and must be followed by the same number of paired - <link to="#unlockRead"/> calls. + The medium locked for reading must be unlocked by abandoning the + returned token object, see <link to="IToken"/>. Calls to + <link to="#lockRead"/> can be nested and the lock is actually released + when all callers have abandoned the token. This method sets the medium state (see <link to="#state"/>) to "LockedRead" on success. The medium's previous state must be @@ -12665,30 +13791,11 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </result> </desc> - <param name="state" type="MediumState" dir="return"> + <param name="token" type="IToken" dir="return"> <desc> - State of the medium after the operation. - </desc> - </param> - </method> - - <method name="unlockRead"> - <desc> - Cancels the read lock previously set by <link to="#lockRead"/>. - - For both success and failure, this method returns the current state - of the medium <i>after</i> the operation. - - See <link to="#lockRead"/> for more details. - - <result name="VBOX_E_INVALID_OBJECT_STATE"> - Medium not locked for reading. - </result> - - </desc> - <param name="state" type="MediumState" dir="return"> - <desc> - State of the medium after the operation. + 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. </desc> </param> </method> @@ -12719,8 +13826,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) A medium is also locked for writing when it is the target of a write operation such as <link to="#cloneTo"/> or <link to="#mergeTo"/>. - The medium locked for writing must be unlocked using the <link - to="#unlockWrite"/> method. Write locks <i>cannot</i> be nested. + The medium locked for writing must be unlocked by abandoning the + returned token object, see <link to="IToken"/>. Write locks + <i>cannot</i> be nested. This method sets the medium state (see <link to="#state"/>) to "LockedWrite" on success. The medium's previous state must be @@ -12731,39 +13839,16 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) the VirtualBox API, not a physical file-system lock of the underlying storage unit. - For both, success and failure, this method returns the current - state of the medium <i>before</i> the operation. - <result name="VBOX_E_INVALID_OBJECT_STATE"> Invalid medium state (e.g. not created, locked, inaccessible, creating, deleting). </result> </desc> - <param name="state" type="MediumState" dir="return"> + <param name="token" type="IToken" dir="return"> <desc> - State of the medium after the operation. - </desc> - </param> - </method> - - <method name="unlockWrite"> - <desc> - Cancels the write lock previously set by <link to="#lockWrite"/>. - - For both success and failure, this method returns the current - state of the medium <i>after</i> the operation. - - See <link to="#lockWrite"/> for more details. - - <result name="VBOX_E_INVALID_OBJECT_STATE"> - Medium not locked for writing. - </result> - - </desc> - <param name="state" type="MediumState" dir="return"> - <desc> - State of the medium after the operation. + Token object, when this is released (reference count reaches 0) then + the lock is released. </desc> </param> </method> @@ -12949,7 +14034,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="logicalSize" type="long long" dir="in"> <desc>Maximum logical size of the medium in bytes.</desc> </param> - <param name="variant" type="unsigned long" dir="in"> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> <desc>Exact image variant which should be created (as a combination of <link to="MediumVariant" /> flags).</desc> </param> @@ -13032,7 +14117,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="target" type="IMedium" dir="in"> <desc>Target medium.</desc> </param> - <param name="variant" type="unsigned long" dir="in"> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> <desc>Exact image variant which should be created (as a combination of <link to="MediumVariant" /> flags).</desc> </param> @@ -13160,7 +14245,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="target" type="IMedium" dir="in"> <desc>Target medium.</desc> </param> - <param name="variant" type="unsigned long" dir="in"> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> <desc>Exact image variant which should be created (as a combination of <link to="MediumVariant" /> flags).</desc> </param> @@ -13209,9 +14294,8 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="target" type="IMedium" dir="in"> <desc>Target medium.</desc> </param> - <param name="variant" type="unsigned long" dir="in"> - <desc>Exact image variant which should be created (as a combination of - <link to="MediumVariant" /> flags).</desc> + <param name="variant" type="MediumVariant" safearray="yes" dir="in"> + <desc><link to="MediumVariant" /> flags).</desc> </param> <param name="progress" type="IProgress" dir="return"> <desc>Progress object to track the operation completion.</desc> @@ -13220,6 +14304,42 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <!-- other methods --> + <method name="setLocation"> + <desc> + 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 <link to="IVirtualBox::homeFolder">VirtualBox + home folder</link> 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. + + <result name="E_NOTIMPL"> + The operation is not implemented yet. + </result> + <result name="VBOX_E_NOT_SUPPORTED"> + Medium format does not support changing the location. + </result> + </desc> + <param name="location" type="wstring" dir="in"> + <desc>New location.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + <method name="compact"> <desc> Starts compacting of this medium. This means that the medium is @@ -13411,7 +14531,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IMediumFormat" extends="$unknown" - uuid="9bd5b655-ea47-4637-99f3-aad0948be35b" + uuid="6238e1cf-a17d-4ec1-8172-418bfb22b93a" wsmap="managed" > <desc> @@ -13459,9 +14579,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> - <attribute name="capabilities" type="unsigned long" readonly="yes"> + <attribute name="capabilities" type="MediumFormatCapabilities" safearray="yes" readonly="yes"> <desc> - Capabilities of the format as a set of bit flags. + Capabilities of the format as an array of the flags. For the meaning of individual capability flags see <link to="MediumFormatCapabilities"/>. @@ -13480,10 +14600,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <see><link to="IMediumFormat::capabilities"/></see> </desc> - <param name="extensions" type="wstring" safearray="yes" dir="out"> + <param name="extensions" type="wstring" safearray="yes" dir="out"> <desc>The array of supported extensions.</desc> </param> - <param name="type" type="DeviceType" safearray="yes" dir="out"> + <param name="types" type="DeviceType" safearray="yes" dir="out"> <desc>The array which indicates the device type for every given extension.</desc> </param> </method> @@ -13507,7 +14627,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="names" type="wstring" safearray="yes" dir="out"> <desc>Array of property names.</desc> </param> - <param name="description" type="wstring" safearray="yes" dir="out"> + <param name="descriptions" type="wstring" safearray="yes" dir="out"> <desc>Array of property descriptions.</desc> </param> <param name="types" type="DataType" safearray="yes" dir="out"> @@ -13525,6 +14645,46 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <!-- + // IToken + ///////////////////////////////////////////////////////////////////////// + --> + + <interface + name="IToken" extends="$unknown" + uuid="3b1c4797-e289-4d4c-b74c-50c9b86a36f8" + wsmap="managed" + > + <desc> + The IToken interface represents a token passed to an API client, which + triggers cleanup actions when it is explicitly released by calling the + <link to="#abandon"/> 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. + </desc> + + <method name="abandon" wrap-hint-server="passcaller"> + <desc>Releases this token. Cannot be undone in any way, and makes the + token object unusable (even the <link to="#dummy"/> 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. + </desc> + </method> + + <method name="dummy"> + <desc>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. + </desc> + </method> + + </interface> + + + <!-- // IKeyboard ///////////////////////////////////////////////////////////////////////// --> @@ -13540,8 +14700,8 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Use this interface to send keystrokes or the Ctrl-Alt-Del sequence to the virtual machine. - </desc> + <method name="putScancode"> <desc>Sends a scancode to the keyboard. @@ -13609,9 +14769,31 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <const name="MouseStateMask" value="0x7F"/> </enum> + <enum + name="TouchContactState" + uuid="3f942686-2506-421c-927c-90d4b45f4a38" + > + <desc> + Touch event contact state. + </desc> + + <const name="None" value="0x00"> + <desc>The touch has finished.</desc> + </const> + <const name="InContact" value="0x01"> + <desc>Whether the touch is really touching the device.</desc> + </const> + <const name="InRange" value="0x02"> + <desc> + Whether the touch is close enough to the device to be detected. + </desc> + </const> + <const name="ContactStateMask" value="0x03"/> + </enum> + <interface name="IMouse" extends="$unknown" - uuid="05044a52-7811-4f00-ae3a-0ab7ff707b10" + uuid="ee770393-415f-4421-b2d5-28b73cacf86a" wsmap="managed" > <desc> @@ -13648,6 +14830,18 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> + <attribute name="multiTouchSupported" type="boolean" readonly="yes"> + <desc> + Whether the guest OS has enabled the multi-touch reporting device. + <note> + You can use the <link to="IMouseCapabilityChangedEvent"/> + event to be instantly informed about changes of this attribute + during virtual machine execution. + </note> + <see><link to="#putMouseEvent"/></see> + </desc> + </attribute> + <attribute name="needsHostCursor" type="boolean" readonly="yes"> <desc> Whether the guest OS can currently switch to drawing it's own mouse @@ -13777,6 +14971,77 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> + <method name="putEventMultiTouch"> + <desc> + Sends a multi-touch pointer event. The coordinates are expressed in + pixels and start from <tt>[1,1]</tt> which corresponds to the top left + corner of the virtual display. + + <result name="E_ACCESSDENIED"> + Console not powered up. + </result> + <result name="VBOX_E_IPRT_ERROR"> + Could not send event to virtual device. + </result> + + <note> + The guest may not understand or may choose to ignore this event. + </note> + + <see><link to="#multiTouchSupported"/></see> + </desc> + + <param name="count" type="long" dir="in"> + <desc> + Number of contacts in the event. + </desc> + </param> + + <param name="contacts" type="long long" dir="in" safearray="yes"> + <desc> + Each array element contains packed information about one contact. + Bits 0..15: X coordinate in pixels. + Bits 16..31: Y coordinate in pixels. + 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. + </desc> + </param> + + <param name="scanTime" type="unsigned long" dir="in"> + <desc> + Timestamp of the event in milliseconds. Only relative time between events is important. + </desc> + </param> + </method> + + <method name="putEventMultiTouchString"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + + <param name="count" type="long" dir="in"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + </param> + + <param name="contacts" type="wstring" dir="in"> + <desc> + 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" + </desc> + </param> + + <param name="scanTime" type="unsigned long" dir="in"> + <desc> + <see><link to="#putEventMultiTouch"/></see> + </desc> + </param> + </method> + <attribute name="eventSource" type="IEventSource" readonly="yes"> <desc> Event source for mouse events. @@ -13797,19 +15062,18 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc> Format of the video memory buffer. Constants represented by this enum can be used to test for particular values of <link - to="IFramebuffer::pixelFormat"/>. See also <link - to="IFramebuffer::requestResize"/>. + to="IFramebuffer::pixelFormat"/>. See also www.fourcc.org for more information about FOURCC pixel formats. </desc> - <const name="Opaque" value="0"> + <const name="Opaque" value="0"> <desc> Unknown buffer format (the user may not assume any particular format of the buffer). </desc> </const> - <const name="FOURCC_RGB" value="0x32424752"> + <const name="FOURCC_RGB" value="0x32424752"> <desc> Basic RGB format (<link to="IFramebuffer::bitsPerPixel"/> determines the bit layout). @@ -13819,10 +15083,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IFramebuffer" extends="$unknown" - uuid="b7ed347a-5765-40a0-ae1c-f543eb4ddeaf" - wsmap="suppress" + uuid="e3f122c0-adab-4fc9-a8dc-da112fb48428" + wsmap="managed" > - <attribute name="address" type="octet" mod="ptr" readonly="yes"> + <attribute name="address" type="octet" mod="ptr" readonly="yes" wsmap="suppress"> <desc>Address of the start byte of the frame buffer.</desc> </attribute> @@ -13855,9 +15119,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Frame buffer pixel format. It's either one of the values defined by <link to="FramebufferPixelFormat"/> or a raw FOURCC code. <note> - This attribute must never return <link - to="FramebufferPixelFormat_Opaque"/> -- the format of the buffer - <link to="#address"/> points to must be always known. + This attribute must never (and will never) return <link + to="FramebufferPixelFormat_Opaque"/> -- the format of the frame + buffer must be always known. </note> </desc> </attribute> @@ -13865,8 +15129,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <attribute name="usesGuestVRAM" type="boolean" readonly="yes"> <desc> Defines whether this frame buffer uses the virtual video card's memory - buffer (guest VRAM) directly or not. See <link - to="IFramebuffer::requestResize"/> for more information. + buffer (guest VRAM) directly or not. </desc> </attribute> @@ -13885,24 +15148,24 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) 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 + 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 + 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. </desc> </attribute> - <attribute name="winId" type="long long" readonly="yes"> + <attribute name="winId" type="long long" readonly="yes" wsmap="suppress"> <desc> Platform-dependent identifier of the window where context of this frame buffer is drawn, or zero if there's no such window. </desc> </attribute> - <method name="lock"> + <method name="lock" wsmap="suppress"> <desc> Locks the frame buffer. Gets called by the IDisplay object where this frame buffer is @@ -13910,7 +15173,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </method> - <method name="unlock"> + <method name="unlock" wsmap="suppress"> <desc> Unlocks the frame buffer. Gets called by the IDisplay object where this frame buffer is @@ -13918,7 +15181,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </method> - <method name="notifyUpdate"> + <method name="notifyUpdate" wsmap="suppress"> <desc> Informs about an update. Gets called by the display object where this buffer is @@ -13930,7 +15193,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="height" type="unsigned long" dir="in"/> </method> - <method name="requestResize"> + <method name="requestResize" wsmap="suppress"> <desc> Requests a size and pixel format change. @@ -14065,7 +15328,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="supported" type="boolean" dir="return"/> </method> - <method name="getVisibleRegion"> + <method name="getVisibleRegion" wsmap="suppress"> <desc> Returns the visible region of this frame buffer. @@ -14098,9 +15361,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> - <method name="setVisibleRegion"> + <method name="setVisibleRegion" wsmap="suppress"> <desc> - Suggests a new visible region to this frame buffer. This region + 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 @@ -14127,7 +15390,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> - <method name="processVHWACommand"> + <method name="processVHWACommand" wsmap="suppress"> <desc> 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.) @@ -14144,20 +15407,33 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> + <method name="notify3DEvent"> + <desc> + Notifies framebuffer about 3D backend event. + </desc> + + <param name="type" type="unsigned long" dir="in"> + <desc>event type. Currently only VBOX3D_NOTIFY_EVENT_TYPE_VISIBLE_3DDATA is supported.</desc> + </param> + <param name="data" type="octet" mod="ptr" dir="in"> + <desc>event-specific data, depends on the supplied event type</desc> + </param> + </method> + </interface> <interface name="IFramebufferOverlay" extends="IFramebuffer" uuid="0bcc1c7e-e415-47d2-bfdb-e4c705fb0f47" - wsmap="suppress" + wsmap="managed" > <desc> 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 + 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 + 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. </desc> @@ -14169,15 +15445,15 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc>Y position of the overlay, relative to the frame buffer.</desc> </attribute> - <attribute name="visible" type="boolean" readonly="no"> + <attribute name="visible" type="boolean"> <desc> Whether the overlay is currently visible. </desc> </attribute> - <attribute name="alpha" type="unsigned long" readonly="no"> + <attribute name="alpha" type="unsigned long"> <desc> - The global alpha value for the overlay. This may or may not be + The global alpha value for the overlay. This may or may not be supported by a given front end. </desc> </attribute> @@ -14194,7 +15470,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IDisplay" extends="$unknown" - uuid="b83ee395-8679-40ca-8d60-1a0cbe724930" + uuid="480b372c-c0b5-4c23-9bd7-dcbb85b1594c" wsmap="managed" > <desc> @@ -14214,6 +15490,8 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="width" type="unsigned long" dir="out"/> <param name="height" type="unsigned long" dir="out"/> <param name="bitsPerPixel" type="unsigned long" dir="out"/> + <param name="xOrigin" type="long" dir="out"/> + <param name="yOrigin" type="long" dir="out"/> </method> <method name="setFramebuffer"> @@ -14311,7 +15589,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <note>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 langages, Java or any webservice clients. + available for scripting languages, Java or any webservice clients. Unless you are writing a new VM frontend use <link to="#takeScreenShotToArray" />. </note> @@ -14333,7 +15611,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <method name="takeScreenShotToArray"> <desc> Takes a guest screen shot of the requested size and returns it as - an array of bytes in uncompressed 32-bit RGBA format. + an array of bytes in uncompressed 32-bpp RGBA format. A pixel consists of 4 bytes in order: R, G, B, 0xFF. This API is slow, but could be the only option to get guest screenshot @@ -14527,7 +15805,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <enum name="NetworkAttachmentType" - uuid="2ac4bc71-6b82-417a-acd1-f7426d2570d6" + uuid="524a8f9d-4b86-4b51-877d-1aa27c4ebeac" > <desc> Network attachment type. @@ -14541,6 +15819,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <const name="Internal" value="3"/> <const name="HostOnly" value="4"/> <const name="Generic" value="5"/> + <const name="NATNetwork" value="6"/> </enum> <enum @@ -14587,13 +15866,13 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </const> <const name="AllowNetwork" value="2"> <desc> - Allow promicuous mode, but restrict the scope it to the internal + Allow promiscuous mode, but restrict the scope it to the internal network so that it only applies to other VMs. </desc> </const> <const name="AllowAll" value="3"> <desc> - Allow promicuous mode, include unrelated traffic going over the wire + Allow promiscuous mode, include unrelated traffic going over the wire and internally on the host. </desc> </const> @@ -14819,16 +16098,16 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) the virtual serial port device. </desc> - <const name="Disconnected" value="0"> + <const name="Disconnected" value="0"> <desc>Virtual device is not attached to any real host device.</desc> </const> - <const name="HostPipe" value="1"> + <const name="HostPipe" value="1"> <desc>Virtual device is attached to a host pipe.</desc> </const> - <const name="HostDevice" value="2"> + <const name="HostDevice" value="2"> <desc>Virtual device is attached to a host device.</desc> </const> - <const name="RawFile" value="3"> + <const name="RawFile" value="3"> <desc>Virtual device is attached to a raw file.</desc> </const> </enum> @@ -14983,8 +16262,8 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IMachineDebugger" extends="$unknown" - uuid="a9abbb7c-d678-43b2-bed2-19ec0e32303d" - wsmap="suppress" + uuid="5e4534dc-21b8-4f6b-8a08-eef50e1a0aa1" + wsmap="managed" > <method name="dumpGuestCore"> <desc> @@ -14994,7 +16273,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> <param name="filename" type="wstring" dir="in"> <desc> - The name of the output file. The file must not exist. + The name of the output file. The file must not exist. </desc> </param> <param name="compression" type="wstring" dir="in"> @@ -15013,7 +16292,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> <param name="filename" type="wstring" dir="in"> <desc> - The name of the output file. The file must not exist. + The name of the output file. The file must not exist. </desc> </param> <param name="compression" type="wstring" dir="in"> @@ -15196,7 +16475,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> <param name="value" type="wstring" dir="return"> <desc> - The register value. This is usually a hex value (always 0x prefixed) + The register value. This is usually a hex value (always 0x prefixed) but other format may be used for floating point registers (TBD). </desc> </param> @@ -15217,7 +16496,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> <param name="values" type="wstring" dir="out" safearray="yes"> <desc> - Array paralell to the names holding the register values as if the + Array parallel to the names holding the register values as if the register was returned by <link to="IMachineDebugger::getRegister"/>. </desc> </param> @@ -15238,7 +16517,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> <param name="value" type="wstring" dir="in"> <desc> - The new register value. Hexadecimal, decimal and octal formattings + The new register value. Hexadecimal, decimal and octal formattings are supported in addition to any special formattings returned by the getters. </desc> @@ -15310,7 +16589,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="withDescriptions" type="boolean" dir="in"> <desc>Whether to include the descriptions.</desc> </param> - <param name="stats" type="wstring" dir="out"> + <param name="stats" type="wstring" dir="return"> <desc>The XML document containing the statistics.</desc> </param> </method> @@ -15327,6 +16606,14 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc>Switch for forcing code recompilation for supervisor mode code.</desc> </attribute> + <attribute name="executeAllInIEM" type="boolean"> + <desc> + 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. + </desc> + </attribute> + <attribute name="PATMEnabled" type="boolean"> <desc>Switch for enabling and disabling the PATM component.</desc> </attribute> @@ -15384,6 +16671,13 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> + <attribute name="HWVirtExUXEnabled" type="boolean" readonly="yes"> + <desc> + Flag indicating whether the VM is currently making use of the + unrestricted execution feature of VT-x. + </desc> + </attribute> + <attribute name="OSName" type="wstring" readonly="yes"> <desc> Query the guest OS kernel name as detected by the DBGF. @@ -15416,56 +16710,26 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> - <attribute name="VM" type="long long" readonly="yes"> + <attribute name="VM" type="long long" readonly="yes" wsmap="suppress"> <desc> - Gets the VM handle. This is only for internal use while - we carve the details of this interface. + Gets the user-mode VM handle, with a reference. Must be passed to + VMR3ReleaseUVM when done. This is only for internal use while we carve + the details of this interface. </desc> </attribute> </interface> <!-- - // IUSBController + // IUSBDeviceFilters ///////////////////////////////////////////////////////////////////////// --> <interface - name="IUSBController" extends="$unknown" - uuid="01e6f13a-0580-452f-a40f-74e32a5e4921" + name="IUSBDeviceFilters" extends="$unknown" + uuid="2ab550b2-53cc-4c2e-ae07-0adf4114e75c" wsmap="managed" > - <attribute name="enabled" type="boolean"> - <desc> - Flag whether the USB controller is present in the - guest system. If disabled, the virtual guest hardware will - not contain any USB controller. Can only be changed when - the VM is powered off. - </desc> - </attribute> - - <attribute name="enabledEHCI" type="boolean"> - <desc> - Flag whether the USB EHCI controller is present in the - guest system. If disabled, the virtual guest hardware will - not contain a USB EHCI controller. Can only be changed when - the VM is powered off. - </desc> - </attribute> - - <attribute name="proxyAvailable" type="boolean" readonly="yes"> - <desc> - Flag whether there is an USB proxy available. - </desc> - </attribute> - - <attribute name="USBStandard" type="unsigned short" readonly="yes"> - <desc> - 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. - </desc> - </attribute> <attribute name="deviceFilters" type="IUSBDeviceFilter" readonly="yes" safearray="yes"> <desc> @@ -15582,6 +16846,56 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </interface> + <!-- + // IUSBController + ///////////////////////////////////////////////////////////////////////// + --> + + <enum + name="USBControllerType" + uuid="8fdd1c6a-5412-41da-ab07-7baed7d6e18e" + > + <desc> + The USB controller type. <link to="IUSBController::type" />. + </desc> + <const name="Null" value="0"> + <desc>@c null value. Never used by the API.</desc> + </const> + <const name="OHCI" value="1"/> + <const name="EHCI" value="2"/> + <const name="Last" value="3"> + <desc>Last element (invalid). Used for parameter checks.</desc> + </const> + </enum> + + <interface + name="IUSBController" extends="$unknown" + uuid="d2745291-65f7-4d75-9556-38047d802319" + wsmap="managed" + > + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + The USB Controller name. + </desc> + </attribute> + + <attribute name="type" type="USBControllerType" readonly="yes"> + <desc> + The USB Controller type. + </desc> + </attribute> + + <attribute name="USBStandard" type="unsigned short" readonly="yes"> + <desc> + 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. + </desc> + </attribute> + + </interface> + <!-- // IUSBDevice @@ -15747,7 +17061,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <i>any match</i> no matter what string expression is specified. </note> - <see><link to="IUSBController::deviceFilters"/>, + <see><link to="IUSBDeviceFilters::deviceFilters"/>, <link to="IHostUSBDeviceFilter"/></see> </desc> @@ -15862,7 +17176,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) filters (<link to="IHost::USBDeviceFilters"/>) 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 (<link to="IUSBController::deviceFilters"/>) are + currently running guests (<link to="IUSBDeviceFilters::deviceFilters"/>) are activated that can put it to USBDeviceState_Captured state. If the device was ignored by global filters, or didn't match @@ -15993,7 +17307,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <note> The <link to="IUSBDeviceFilter::remote"/> attribute is ignored by this type of filters, because it makes sense only for - <link to="IUSBController::deviceFilters">machine USB filters</link>. + <link to="IUSBDeviceFilters::deviceFilters">machine USB filters</link>. </note> <see><link to="IHost::USBDeviceFilters"/></see> @@ -16058,9 +17372,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Virtual audio controller type. </desc> - <const name="AC97" value="0"/> - <const name="SB16" value="1"/> - <const name="HDA" value="2"/> + <const name="AC97" value="0"/> + <const name="SB16" value="1"/> + <const name="HDA" value="2"/> </enum> <interface @@ -16101,11 +17415,11 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) VirtualBox authentication type. </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>Null value, also means "no authentication".</desc> </const> - <const name="External" value="1"/> - <const name="Guest" value="2"/> + <const name="External" value="1"/> + <const name="Guest" value="2"/> </enum> <!-- @@ -16118,8 +17432,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) uuid="d38de40a-c2c1-4e95-b5a4-167b05f5694c" wsmap="managed" > + <attribute name="enabled" type="boolean"> - <desc>VRDE server status.</desc> + <desc>Flag if VRDE server is enabled.</desc> </attribute> <attribute name="authType" type="AuthType"> @@ -16147,7 +17462,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <attribute name="VRDEExtPack" type="wstring"> <desc> - The name of Extension Pack providing VRDE for this VM. Overrides + The name of Extension Pack providing VRDE for this VM. Overrides <link to="ISystemProperties::defaultVRDEExtPack"/>. </desc> </attribute> @@ -16311,9 +17626,31 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) ///////////////////////////////////////////////////////////////////////// --> + <enum + name="Reason" + uuid="e7e8e097-299d-4e98-8bbc-c31c2d47d0cc" + > + <desc> + Internal event reason type. + </desc> + + <const name="Unspecified" value="0"> + <desc>Null value, means "no known reason".</desc> + </const> + <const name="HostSuspend" value="1"> + <desc>Host is being suspended (power management event).</desc> + </const> + <const name="HostResume" value="2"> + <desc>Host is being resumed (power management event).</desc> + </const> + <const name="HostBatteryLow" value="3"> + <desc>Host is running low on battery (power management event).</desc> + </const> + </enum> + <interface name="IInternalSessionControl" extends="$unknown" - uuid="3e83963a-1c3b-400d-8c5f-f2d077b0a597" + uuid="2d2124a7-0f62-4907-ae21-eee5a559bdde" internal="yes" wsmap="suppress" > @@ -16338,6 +17675,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="console" type="IConsole" dir="return"/> </method> +<if target="midl"> <method name="assignMachine"> <desc> Assigns the machine object associated with this direct-type @@ -16354,7 +17692,29 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> <param name="machine" type="IMachine" dir="in"/> <param name="lockType" type="LockType" dir="in"/> + <param name="tokenId" type="wstring" dir="in"/> </method> +</if> +<if target="xpidl"> + <method name="assignMachine"> + <desc> + 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). + + <result name="VBOX_E_INVALID_VM_STATE"> + Session state prevents operation. + </result> + <result name="VBOX_E_INVALID_OBJECT_STATE"> + Session type prevents operation. + </result> + + </desc> + <param name="machine" type="IMachine" dir="in"/> + <param name="lockType" type="LockType" dir="in"/> + <param name="token" type="IToken" dir="in"/> + </method> +</if> <method name="assignRemoteMachine"> <desc> @@ -16384,7 +17744,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </result> </desc> - <param name="aMachineState" type="MachineState" dir="in"/> + <param name="machineState" type="MachineState" dir="in"/> </method> <method name="uninitialize"> @@ -16506,6 +17866,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="remove" type="boolean" dir="in"> <desc>TRUE if the device is removed, FALSE if it was added.</desc> </param> + <param name="silent" type="boolean" dir="in"> + <desc>TRUE if the device is is silently reconfigured without + notifying the guest about it.</desc> + </param> </method> <method name="onClipboardModeChange"> @@ -16565,6 +17929,12 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> + <method name="onVideoCaptureChange"> + <desc> + Triggered when video capture settings have changed. + </desc> + </method> + <method name="onUSBControllerChange"> <desc> Triggered when settings of the USB controller object of the @@ -16709,30 +18079,30 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <param name="patterns" type="wstring" dir="in"> <desc> The patterns to match the properties against as a comma-separated - string. If this is empty, all properties currently set will be + string. If this is empty, all properties currently set will be returned. </desc> </param> - <param name="key" type="wstring" dir="out" safearray="yes"> + <param name="keys" type="wstring" dir="out" safearray="yes"> <desc> The key names of the properties returned. </desc> </param> - <param name="value" type="wstring" dir="out" safearray="yes"> + <param name="values" type="wstring" dir="out" safearray="yes"> <desc> - The values of the properties returned. The array entries match the + The values of the properties returned. The array entries match the corresponding entries in the @a key array. </desc> </param> - <param name="timestamp" type="long long" dir="out" safearray="yes"> + <param name="timestamps" type="long long" dir="out" safearray="yes"> <desc> - The time stamps of the properties returned. The array entries match + The time stamps of the properties returned. The array entries match the corresponding entries in the @a key array. </desc> </param> <param name="flags" type="wstring" dir="out" safearray="yes"> <desc> - The flags of the properties returned. The array entries match the + The flags of the properties returned. The array entries match the corresponding entries in the @a key array. </desc> </param> @@ -16762,22 +18132,6 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc>The index of the target image in the chain. Redundant, but drastically reduces IPC.</desc> </param> - <param name="source" type="IMedium" dir="in"> - <desc>Merge source medium.</desc> - </param> - <param name="target" type="IMedium" dir="in"> - <desc>Merge target medium.</desc> - </param> - <param name="mergeForward" type="boolean" dir="in"> - <desc>Merge direction.</desc> - </param> - <param name="parentForTarget" type="IMedium" dir="in"> - <desc>For forward merges: new parent for target medium.</desc> - </param> - <param name="childrenToReparent" type="IMedium" safearray="yes" dir="in"> - <desc>For backward merges: list of media which need their parent UUID - updated.</desc> - </param> <param name="progress" type="IProgress" dir="in"> <desc> Progress object for this operation. @@ -16802,6 +18156,69 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> </method> + <method name="pauseWithReason"> + <desc> + 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. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Running state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in suspend operation. + </result> + <see><link to="IConsole::pause"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + </method> + + <method name="resumeWithReason"> + <desc> + 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. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine not in Paused state. + </result> + <result name="VBOX_E_VM_ERROR"> + Virtual machine error in resume operation. + </result> + <see><link to="IConsole::resume"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + </method> + + <method name="saveStateWithReason"> + <desc> + 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. + + <result name="VBOX_E_INVALID_VM_STATE"> + Virtual machine state neither Running nor Paused. + </result> + <result name="VBOX_E_FILE_ERROR"> + Failed to create directory for saved state file. + </result> + <see><link to="IConsole::saveState"/></see> + </desc> + + <param name="reason" type="Reason" dir="in"> + <desc>Specify the best matching reason code please.</desc> + </param> + <param name="progress" type="IProgress" dir="return"> + <desc>Progress object to track the operation completion.</desc> + </param> + </method> + </interface> <interface @@ -16854,7 +18271,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <li>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 <tt>createLocalObject()</tt>, a standard COM API. - This object will then act as a local session object in further calls to open + This object will then act as a local session object in further calls to open a session. </li> @@ -16930,7 +18347,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) The bus type of the storage controller (IDE, SATA, SCSI, SAS or Floppy); see <link to="IStorageController::bus" />. </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>@c null value. Never used by the API.</desc> </const> <const name="IDE" value="1"/> @@ -16949,31 +18366,31 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) to the guest; see <link to="IStorageController::controllerType" />. </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>@c null value. Never used by the API.</desc> </const> - <const name="LsiLogic" value="1"> + <const name="LsiLogic" value="1"> <desc>A SCSI controller of the LsiLogic variant.</desc> </const> - <const name="BusLogic" value="2"> + <const name="BusLogic" value="2"> <desc>A SCSI controller of the BusLogic variant.</desc> </const> - <const name="IntelAhci" value="3"> + <const name="IntelAhci" value="3"> <desc>An Intel AHCI SATA controller; this is the only variant for SATA.</desc> </const> - <const name="PIIX3" value="4"> + <const name="PIIX3" value="4"> <desc>An IDE controller of the PIIX3 variant.</desc> </const> - <const name="PIIX4" value="5"> + <const name="PIIX4" value="5"> <desc>An IDE controller of the PIIX4 variant.</desc> </const> - <const name="ICH6" value="6"> + <const name="ICH6" value="6"> <desc>An IDE controller of the ICH6 variant.</desc> </const> - <const name="I82078" value="7"> + <const name="I82078" value="7"> <desc>A floppy disk controller; this is the only variant for floppy drives.</desc> </const> - <const name="LsiLogicSas" value="8"> + <const name="LsiLogicSas" value="8"> <desc>A variant of the LsiLogic controller using SAS.</desc> </const> </enum> @@ -16986,10 +18403,10 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Type of emulated chipset (mostly southbridge). </desc> - <const name="Null" value="0"> + <const name="Null" value="0"> <desc>@c null value. Never used by the API.</desc> </const> - <const name="PIIX3" value="1"> + <const name="PIIX3" value="1"> <desc>A PIIX3 (PCI IDE ISA Xcelerator) chipset.</desc> </const> <const name="ICH9" value="2"> @@ -17026,7 +18443,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Name of the storage controller, as originally specified with <link to="IMachine::addStorageController" />. This then uniquely identifies this controller with other method calls such as - <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />. + <link to="IMachine::attachDevice" /> and <link to="IMachine::mountMedium" />. </desc> </attribute> @@ -17128,7 +18545,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) 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 <link to="IManagedObjectRef::release" /> or by logging off from + call to <link to="IManagedObjectRef::release" /> or by logging off from the webservice (<link to="IWebsessionManager::logoff" />), which releases all objects created during the webservice session. @@ -17285,7 +18702,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) 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 + and IMachine. Each object has a distinct set of performance metrics. The set can be obtained with <link to="IPerformanceCollector::getMetrics"/>. Metric data is collected at the specified intervals and is retained @@ -17307,7 +18724,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) 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 + collected. Collected values for any set of sub-metrics can be queried with <link to="IPerformanceCollector::queryMetricsData" />. For example "CPU/Load/User:avg" metric name stands for the "CPU" @@ -17551,14 +18968,15 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) form metric/object pairs. </note> <note> - 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 makes possible - 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. + 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. </note> </desc> <param name="metricNames" type="wstring" dir="in" safearray="yes"> @@ -17805,17 +19223,17 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) accessing COM objects within it. </desc> <attribute name="name" type="wstring" readonly="yes"> - <desc>The extension pack name. This is unique.</desc> + <desc>The extension pack name. This is unique.</desc> </attribute> <attribute name="description" type="wstring" readonly="yes"> <desc>The extension pack description.</desc> </attribute> <attribute name="version" type="wstring" readonly="yes"> <desc> - The extension pack version string. This is restricted to the dotted - version number and optionally a build indicator. No tree revision or + 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 + separate properties. An optional publisher tag may be present like for <link to="IVirtualBox::version"/>. Examples: "1.2.3", "1.2.3_BETA1" and "1.2.3_RC2". @@ -17826,11 +19244,11 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </attribute> <attribute name="edition" type="wstring" readonly="yes"> <desc> - Edition indicator. This is usually empty. + 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. + 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. </desc> </attribute> <attribute name="VRDEModule" type="wstring" readonly="yes"> @@ -17850,7 +19268,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </attribute> <attribute name="whyUnusable" type="wstring" readonly="yes"> <desc> - String indicating why the extension pack is not usable. This is an + 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. </desc> </attribute> @@ -17859,7 +19277,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </attribute> <attribute name="license" type="wstring" readonly="yes"> <desc> - The default HTML license text for the extension pack. Same as + The default HTML license text for the extension pack. Same as calling <link to="#queryLicense">queryLicense</link> with preferredLocale and preferredLanguage as empty strings and format set to html. @@ -17908,11 +19326,11 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <method name="queryObject"> <desc> Queries the IUnknown interface to an object in the extension pack - main module. This allows plug-ins and others to talk directly to an + main module. This allows plug-ins and others to talk directly to an extension pack. </desc> <param name="objUuid" type="wstring" dir="in"> - <desc>The object ID. What exactly this is </desc> + <desc>The object ID. What exactly this is </desc> </param> <param name="returnInterface" type="$unknown" dir="return"> <desc>The queried interface.</desc> @@ -17927,7 +19345,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) > <desc> Extension pack file (aka tarball, .vbox-extpack) representation returned - by <link to="IExtPackManager::openExtPackFile"/>. This provides the base + by <link to="IExtPackManager::openExtPackFile"/>. This provides the base extension pack information with the addition of the file name. </desc> <attribute name="filePath" type="wstring" readonly="yes"> @@ -17948,7 +19366,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> <param name="displayInfo" type="wstring" dir="in"> <desc> - Platform specific display information. Reserved for future hacks. + Platform specific display information. Reserved for future hacks. </desc> </param> <param name="progess" type="IProgress" dir="return"> @@ -17999,7 +19417,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) installation. </desc> <param name="path" type="wstring" dir="in"> - <desc>The path of the extension pack tarball. This can optionally be + <desc>The path of the extension pack tarball. This can optionally be followed by a "::SHA-256=hex-digit" of the tarball. </desc> </param> <param name="file" type="IExtPackFile" dir="return"> @@ -18014,13 +19432,13 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </param> <param name="forcedRemoval" type="boolean" dir="in"> <desc> - Forced removal of the extension pack. This means that the uninstall + Forced removal of the extension pack. This means that the uninstall hook will not be called. </desc> </param> <param name="displayInfo" type="wstring" dir="in"> <desc> - Platform specific display information. Reserved for future hacks. + Platform specific display information. Reserved for future hacks. </desc> </param> <param name="progess" type="IProgress" dir="return"> @@ -18113,7 +19531,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </attribute> <attribute name="reference" type="unsigned long" readonly="yes"> - <desc>How many devices/medium attachements use this group.</desc> + <desc>How many devices/medium attachments use this group.</desc> </attribute> <attribute name="maxBytesPerSec" type="long long"> @@ -18201,7 +19619,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IVirtualBoxClient" extends="$unknown" - uuid="5fe0bd48-1181-40d1-991f-3b02f269a823" + uuid="d191281f-b0cb-4d83-a8fa-0d9fd6ba234c" wsmap="suppress" > <desc> @@ -18231,6 +19649,18 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> </attribute> + <method name="checkMachineError"> + <desc> + Perform error checking before using an <link to="IMachine"/> 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. + </desc> + + <param name="machine" type="IMachine" dir="in"> + <desc>The machine object to check.</desc> + </param> + </method> </interface> <!-- @@ -18239,7 +19669,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) --> <enum name="VBoxEventType" - uuid="0d67e79e-b7b1-4919-aab3-b36866075515" + uuid="5248e377-e578-47d7-b07b-84b1db6db8a8" > <desc> @@ -18507,9 +19937,120 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) See <link to="IDragAndDropModeChangedEvent">IDragAndDropModeChangedEvent</link>. </desc> </const> + <const name="OnNATNetworkChanged" value="74"> + <desc> + See <link to="INATNetworkChangedEvent">INATNetworkChangedEvent</link>. + </desc> + </const> + <const name="OnNATNetworkStartStop" value="75"> + <desc> + See <link to="INATNetworkStartStopEvent">INATNetworkStartStopEvent</link>. + </desc> + </const> + <const name="OnNATNetworkAlter" value="76"> + <desc> + See <link to="INATNetworkAlterEvent">INATNetworkAlterEvent</link>. + </desc> + </const> + <const name="OnNATNetworkCreationDeletion" value="77"> + <desc> + See <link to="INATNetworkCreationDeletionEvent">INATNetworkCreationDeletionEvent</link>. + </desc> + </const> + <const name="OnNATNetworkSetting" value="78"> + <desc> + See <link to="INATNetworkSettingEvent">INATNetworkSettingEvent</link>. + </desc> + </const> + <const name="OnNATNetworkPortForward" value="79"> + <desc> + See <link to="INATNetworkPortForwardEvent">INATNetworkPortForwardEvent</link>. + </desc> + </const> + <const name="OnGuestSessionStateChanged" value="80"> + <desc> + See <link to="IGuestSessionStateChangedEvent">IGuestSessionStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestSessionRegistered" value="81"> + <desc> + See <link to="IGuestSessionRegisteredEvent">IGuestSessionRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestProcessRegistered" value="82"> + <desc> + See <link to="IGuestProcessRegisteredEvent">IGuestProcessRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestProcessStateChanged" value="83"> + <desc> + See <link to="IGuestProcessStateChangedEvent">IGuestProcessStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestProcessInputNotify" value="84"> + <desc> + See <link to="IGuestProcessInputNotifyEvent">IGuestProcessInputNotifyEvent</link>. + </desc> + </const> + <const name="OnGuestProcessOutput" value="85"> + <desc> + See <link to="IGuestProcessOutputEvent">IGuestProcessOutputEvent</link>. + </desc> + </const> + <const name="OnGuestFileRegistered" value="86"> + <desc> + See <link to="IGuestFileRegisteredEvent">IGuestFileRegisteredEvent</link>. + </desc> + </const> + <const name="OnGuestFileStateChanged" value="87"> + <desc> + See <link to="IGuestFileStateChangedEvent">IGuestFileStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestFileOffsetChanged" value="88"> + <desc> + See <link to="IGuestFileOffsetChangedEvent">IGuestFileOffsetChangedEvent</link>. + </desc> + </const> + <const name="OnGuestFileRead" value="89"> + <desc> + See <link to="IGuestFileReadEvent">IGuestFileReadEvent</link>. + <note internal="yes">For performance reasons this is a separate event to + not unnecessarily overflow the event queue.</note> + </desc> + </const> + <const name="OnGuestFileWrite" value="90"> + <desc> + See <link to="IGuestFileWriteEvent">IGuestFileWriteEvent</link>. + + <note internal="yes">For performance reasons this is a separate event to + not unnecessarily overflow the event queue.</note> + </desc> + </const> + <const name="OnVideoCaptureChanged" value="91"> + <desc> + See <link to="IVideoCaptureChangedEvent">IVideoCapturedChangeEvent</link>. + </desc> + </const> + <const name="OnGuestUserStateChanged" value="92"> + <desc> + See <link to="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link>. + </desc> + </const> + <const name="OnGuestMultiTouch" value="93"> + <desc> + See <link to="IGuestMouseEvent">IGuestMouseEvent</link>. + </desc> + </const> + <const name="OnHostNameResolutionConfigurationChange" value="94"> + <desc> + See <link to="IHostNameResolutionConfigurationChangeEvent">IHostNameResolutionConfigurationChangeEvent</link>. + </desc> + </const> + <!-- OnHostNameResolutionConfigurationChange --> <!-- Last event marker --> - <const name="Last" value="74"> + <const name="Last" value="95"> <desc> Must be last event, used for iterations and structures relying on numerical event values. </desc> @@ -18547,7 +20088,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> <param name="subordinates" type="IEventSource" dir="in" safearray="yes"> <desc> - Subordinate event source this one aggregatres. + Subordinate event source this one aggregates. </desc> </param> <param name="result" type="IEventSource" dir="return"> @@ -18747,7 +20288,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) consumers may register event listeners with this event source. To register a listener, an object implementing the <link to="IEventListener" /> interface must be provided. For active listeners, such an object is typically created by the consumer, while for - passive listeners <link to="IEventSource::createListener" /> should be used. Please + passive listeners <link to="IEventSource::createListener" /> should be used. Please note that a listener created with <link to="IEventSource::createListener"/> must not be used as an active listener. Once created, the listener must be registered to listen for the desired events @@ -18803,7 +20344,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </desc> <param name="timeout" type="long" dir="in"> <desc> - Maximum time to wait for event processeing, in ms; + Maximum time to wait for event processing, in ms; 0 = no wait, -1 = indefinite wait. </desc> </param> @@ -19065,9 +20606,9 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) 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. + 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 @@ -19093,7 +20634,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <interface name="IMouseCapabilityChangedEvent" extends="IEvent" - uuid="d633ad48-820c-4207-b46c-6bd3596640d5" + uuid="70e7779a-e64a-4908-804e-371cad23a756" wsmap="managed" autogen="VBoxEvent" id="OnMouseCapabilityChanged" > <desc> @@ -19110,6 +20651,11 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Supports relative coordinates. </desc> </attribute> + <attribute name="supportsMultiTouch" type="boolean" readonly="yes"> + <desc> + Supports multi-touch events coordinates. + </desc> + </attribute> <attribute name="needsHostCursor" type="boolean" readonly="yes"> <desc> If host cursor is needed. @@ -19179,7 +20725,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc> Notification when a property of one of the virtual <link to="IMachine::getNetworkAdapter">network adapters</link> - changes. Interested callees should use INetworkAdapter methods and + changes. Interested callees should use INetworkAdapter methods and attributes to find out what has changed. </desc> <attribute name="networkAdapter" type="INetworkAdapter" readonly="yes"> @@ -19215,7 +20761,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc> Notification when a property of one of the virtual <link to="IMachine::getParallelPort">parallel ports</link> - changes. Interested callees should use ISerialPort methods and + changes. Interested callees should use ISerialPort methods and attributes to find out what has changed. </desc> <attribute name="parallelPort" type="IParallelPort" readonly="yes"> @@ -19327,25 +20873,51 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc> Notification when guest keyboard event happens. </desc> - <attribute name="scancodes" type="long" safearray="yes" readonly="yes"> + <attribute name="scancodes" type="long" safearray="yes" readonly="yes"> <desc> Array of scancodes. </desc> </attribute> </interface> + <enum + name="GuestMouseEventMode" + uuid="4b500146-ebba-4b7c-bc29-69c2d57a5caf" + > + + <desc> + 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. + </desc> + + <const name="Relative" value="0"> + <desc> + Relative event. + </desc> + </const> + + <const name="Absolute" value="1"> + <desc> + Absolute event. + </desc> + </const> + </enum> + <interface name="IGuestMouseEvent" extends="IReusableEvent" - uuid="1f85d35c-c524-40ff-8e98-307000df0992" + uuid="179f8647-319c-4e7e-8150-c5837bd265f6" wsmap="managed" autogen="VBoxEvent" id="OnGuestMouse" > <desc> Notification when guest mouse event happens. </desc> - <attribute name="absolute" type="boolean" readonly="yes"> + <attribute name="mode" type="GuestMouseEventMode" readonly="yes"> <desc> - If this event is relative or absolute. + If this event is relative, absolute or multi-touch. </desc> </attribute> @@ -19381,6 +20953,355 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </interface> + <interface + name="IGuestMultiTouchEvent" extends="IEvent" + uuid="be8a0eb5-f4f4-4dd0-9d30-c89b873247ec" + wsmap="managed" autogen="VBoxEvent" id="OnGuestMultiTouch" + > + <desc> + Notification when guest touch screen event happens. + </desc> + <attribute name="contactCount" type="long" readonly="yes"> + <desc> + Number of contacts in the event. + </desc> + </attribute> + <attribute name="xPositions" type="short" safearray="yes" readonly="yes"> + <desc> + X positions. + </desc> + </attribute> + <attribute name="yPositions" type="short" safearray="yes" readonly="yes"> + <desc> + Y positions. + </desc> + </attribute> + <attribute name="contactIds" type="unsigned short" safearray="yes" readonly="yes"> + <desc> + Contact identifiers. + </desc> + </attribute> + <attribute name="contactFlags" type="unsigned short" safearray="yes" readonly="yes"> + <desc> + Contact state. + Bit 0: in contact. + Bit 1: in range. + </desc> + </attribute> + <attribute name="scanTime" type="unsigned long" readonly="yes"> + <desc> + Timestamp of the event in milliseconds. Only relative time between events is important. + </desc> + </attribute> + </interface> + + <interface + name="IGuestSessionEvent" extends="IEvent" + uuid="b9acd33f-647d-45ac-8fe9-f49b3183ba37" + wsmap="managed" + > + <desc>Base abstract interface for all guest session events.</desc> + + <attribute name="session" type="IGuestSession" readonly="yes"> + <desc>Guest session that is subject to change.</desc> + </attribute> + + </interface> + + <interface + name="IGuestSessionStateChangedEvent" extends="IGuestSessionEvent" + uuid="327e3c00-ee61-462f-aed3-0dff6cbf9904" + wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionStateChanged" + > + <desc> + Notification when a guest session changed its state. + </desc> + + <attribute name="id" type="unsigned long" readonly="yes"> + <desc> + Session ID of guest session which was changed. + </desc> + </attribute> + <attribute name="status" type="GuestSessionStatus" readonly="yes"> + <desc> + New session status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestSessionRegisteredEvent" extends="IGuestSessionEvent" + uuid="b79de686-eabd-4fa6-960a-f1756c99ea1c" + wsmap="managed" autogen="VBoxEvent" id="OnGuestSessionRegistered" + > + <desc> + Notification when a guest session was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest session was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessEvent" extends="IGuestSessionEvent" + uuid="2405f0e5-6588-40a3-9b0a-68c05ba52c4b" + wsmap="managed" + > + <desc>Base abstract interface for all guest process events.</desc> + + <attribute name="process" type="IGuestProcess" readonly="yes"> + <desc> + Guest process object which is related to this event. + </desc> + </attribute> + <attribute name="pid" type="unsigned long" readonly="yes"> + <desc> + Guest process ID (PID). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessRegisteredEvent" extends="IGuestProcessEvent" + uuid="1d89e2b3-c6ea-45b6-9d43-dc6f70cc9f02" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessRegistered" + > + <desc> + Notification when a guest process was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest process was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessStateChangedEvent" extends="IGuestProcessEvent" + uuid="c365fb7b-4430-499f-92c8-8bed814a567a" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessStateChanged" + > + <desc> + Notification when a guest process changed its state. + </desc> + + <attribute name="status" type="ProcessStatus" readonly="yes"> + <desc> + New guest process status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessIOEvent" extends="IGuestProcessEvent" + uuid="9ea9227c-e9bb-49b3-bfc7-c5171e93ef38" + wsmap="managed" + > + <desc> + Base abstract interface for all guest process input/output (IO) events. + </desc> + + <attribute name="handle" type="unsigned long" readonly="yes"> + <desc> + Input/output (IO) handle involved in this event. Usually 0 is stdin, + 1 is stdout and 2 is stderr. + </desc> + </attribute> + + <attribute name="processed" type="unsigned long" readonly="yes"> + <desc> + Processed input or output (in bytes). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessInputNotifyEvent" extends="IGuestProcessIOEvent" + uuid="0de887f2-b7db-4616-aac6-cfb94d89ba78" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessInputNotify" + > + <desc> + Notification when a guest process' stdin became available. + <note>This event is right now not implemented!</note> + </desc> + + <attribute name="status" type="ProcessInputStatus" readonly="yes"> + <desc> + Current process input status. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestProcessOutputEvent" extends="IGuestProcessIOEvent" + uuid="d3d5f1ee-bcb2-4905-a7ab-cc85448a742b" + wsmap="managed" autogen="VBoxEvent" id="OnGuestProcessOutput" + > + <desc> + Notification when there is guest process output available for reading. + </desc> + + <attribute name="data" type="octet" safearray="yes" readonly="yes"> + <desc> + Actual output data. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileEvent" extends="IGuestSessionEvent" + uuid="c8adb7b0-057d-4391-b928-f14b06b710c5" + wsmap="managed" + > + <desc>Base abstract interface for all guest file events.</desc> + + <attribute name="file" type="IGuestFile" readonly="yes"> + <desc> + Guest file object which is related to this event. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileRegisteredEvent" extends="IGuestFileEvent" + uuid="d0d93830-70a2-487e-895e-d3fc9679f7b3" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRegistered" + > + <desc> + Notification when a guest file was registered or unregistered. + </desc> + + <attribute name="registered" type="boolean" readonly="yes"> + <desc> + If @c true, the guest file was registered, otherwise it was + unregistered. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileStateChangedEvent" extends="IGuestFileEvent" + uuid="d37fe88f-0979-486c-baa1-3abb144dc82d" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileStateChanged" + > + <desc> + Notification when a guest file changed its state. + </desc> + + <attribute name="status" type="FileStatus" readonly="yes"> + <desc> + New guest file status. + </desc> + </attribute> + <attribute name="error" type="IVirtualBoxErrorInfo" readonly="yes"> + <desc> + Error information in case of new session status is indicating an error. + + The attribute <link to="IVirtualBoxErrorInfo::resultDetail"/> will contain + the runtime (IPRT) error code from the guest. See include/iprt/err.h and + include/VBox/err.h for details. + </desc> + </attribute> + <!-- Note: No events for reads/writes for performance reasons. + See dedicated events IGuestFileReadEvent and + IGuestFileWriteEvent. --> + + </interface> + + <interface + name="IGuestFileIOEvent" extends="IGuestFileEvent" + uuid="b5191a7c-9536-4ef8-820e-3b0e17e5bbc8" + wsmap="managed" + > + <desc> + Base abstract interface for all guest file input/output (IO) events. + </desc> + + <attribute name="offset" type="long long" readonly="yes"> + <desc> + Current offset (in bytes). + </desc> + </attribute> + <attribute name="processed" type="unsigned long" readonly="yes"> + <desc> + Processed input or output (in bytes). + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileOffsetChangedEvent" extends="IGuestFileIOEvent" + uuid="e8f79a21-1207-4179-94cf-ca250036308f" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileOffsetChanged" + > + <desc> + Notification when a guest file changed its current offset. + </desc> + + </interface> + + <interface + name="IGuestFileReadEvent" extends="IGuestFileIOEvent" + uuid="4ee3cbcb-486f-40db-9150-deee3fd24189" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileRead" + > + <desc> + Notification when data has been read from a guest file. + </desc> + + <attribute name="data" type="octet" safearray="yes" readonly="yes"> + <desc> + Actual data read. + </desc> + </attribute> + + </interface> + + <interface + name="IGuestFileWriteEvent" extends="IGuestFileIOEvent" + uuid="e062a915-3cf5-4c0a-bc90-9b8d4cc94d89" + wsmap="managed" autogen="VBoxEvent" id="OnGuestFileWrite" + > + <desc> + Notification when data has been written to a guest file. + </desc> + + </interface> <interface name="IVRDEServerChangedEvent" extends="IEvent" @@ -19408,13 +21329,23 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </interface> <interface + name="IVideoCaptureChangedEvent" extends="IEvent" + uuid="6215d169-25dd-4719-ab34-c908701efb58" + wsmap="managed" autogen="VBoxEvent" id="OnVideoCaptureChanged" + > + <desc> + Notification when video capture settings have changed. + </desc> + </interface> + + <interface name="IUSBControllerChangedEvent" extends="IEvent" uuid="93BADC0C-61D9-4940-A084-E6BB29AF3D83" wsmap="managed" autogen="VBoxEvent" id="OnUSBControllerChanged" > <desc> Notification when a property of the virtual - <link to="IMachine::USBController">USB controller</link> changes. + <link to="IMachine::USBControllers">USB controllers</link> changes. Interested callees should use IUSBController methods and attributes to find out what has changed. </desc> @@ -19654,7 +21585,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) name="IExtraDataCanChangeEvent" extends="IVetoEvent" uuid="245d88bd-800a-40f8-87a6-170d02249a55" wsmap="managed" autogen="VBoxEvent" id="OnExtraDataCanChange" - waitable="true" + waitable="yes" > <desc> Notification when someone tries to change extra data for @@ -19683,7 +21614,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) name="ICanShowWindowEvent" extends="IVetoEvent" uuid="adf292b0-92c9-4a77-9d35-e058b39fe0b9" wsmap="managed" autogen="VBoxEvent" id="OnCanShowWindow" - waitable="true" + waitable="yes" > <desc> Notification when a call to @@ -19702,7 +21633,7 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) name="IShowWindowEvent" extends="IEvent" uuid="B0A0904D-2F05-4D28-855F-488F96BAD2B2" wsmap="managed" autogen="VBoxEvent" id="OnShowWindow" - waitable="true" + waitable="yes" > <desc> Notification when a call to @@ -19749,42 +21680,42 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) <desc> Notification when NAT redirect rule added or removed. </desc> - <attribute name="slot" type="unsigned long" readonly="yes"> + <attribute name="slot" type="unsigned long" readonly="yes"> <desc> Adapter which NAT attached to. </desc> </attribute> - <attribute name="remove" type="boolean" readonly="yes"> + <attribute name="remove" type="boolean" readonly="yes"> <desc> Whether rule remove or add. </desc> </attribute> - <attribute name="name" type="wstring" readonly="yes"> + <attribute name="name" type="wstring" readonly="yes"> <desc> Name of the rule. </desc> </attribute> - <attribute name="proto" type="NATProtocol" readonly="yes"> + <attribute name="proto" type="NATProtocol" readonly="yes"> <desc> Protocol (TCP or UDP) of the redirect rule. </desc> </attribute> - <attribute name="hostIP" type="wstring" readonly="yes"> + <attribute name="hostIP" type="wstring" readonly="yes"> <desc> Host ip address to bind socket on. </desc> </attribute> - <attribute name="hostPort" type="long" readonly="yes"> + <attribute name="hostPort" type="long" readonly="yes"> <desc> Host port to bind socket on. </desc> </attribute> - <attribute name="guestIP" type="wstring" readonly="yes"> + <attribute name="guestIP" type="wstring" readonly="yes"> <desc> Guest ip address to redirect to. </desc> </attribute> - <attribute name="guestPort" type="long" readonly="yes"> + <attribute name="guestPort" type="long" readonly="yes"> <desc> Guest port to redirect to. </desc> @@ -19945,8 +21876,42 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) </interface> <interface + name="IGuestUserStateChangedEvent" extends="IEvent" + uuid="39b4e759-1ec0-4c0f-857f-fbe2a737a256" + wsmap="managed" autogen="VBoxEvent" id="OnGuestUserStateChanged" + > + <desc> + Notification when a guest user changed its state. + </desc> + + <attribute name="name" type="wstring" readonly="yes"> + <desc> + Name of the guest user whose state changed. + </desc> + </attribute> + <attribute name="domain" type="wstring" readonly="yes"> + <desc> + Name of the FQDN (fully qualified domain name) this user is bound + to. Optional. + </desc> + </attribute> + <attribute name="state" type="GuestUserState" readonly="yes"> + <desc> + What was changed for this guest user. See <link to="GuestUserState"/> for + more information. + </desc> + </attribute> + <attribute name="stateDetails" type="wstring" readonly="yes"> + <desc> + Optional state details, depending on the <link to="#state"/> attribute. + </desc> + </attribute> + + </interface> + + <interface name="IStorageDeviceChangedEvent" extends="IEvent" - uuid="8a5c2dce-e341-49d4-afce-c95979f7d70c" + uuid="232e9151-ae84-4b8e-b0f3-5c20c35caac9" wsmap="managed" autogen="VBoxEvent" id="OnStorageDeviceChanged" > <desc> @@ -19964,6 +21929,69 @@ Snapshot 1 (B.vdi) Snapshot 1 (B.vdi) Flag whether the device was removed or added to the VM. </desc> </attribute> + <attribute name="silent" type="boolean" readonly="yes"> + <desc> + Flag whether the guest should be notified about the change. + </desc> + </attribute> + </interface> + + <interface + name="INATNetworkChangedEvent" extends="IEvent" + uuid="101ae042-1a29-4a19-92cf-02285773f3b5" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkChanged" + > + <!-- network name is common setting for all event types --> + <attribute name="networkName" type="wstring" readonly="yes"/> + </interface> + <!-- base class for start/stop events --> + <interface name="INATNetworkStartStopEvent" extends="INATNetworkChangedEvent" + uuid="269d8f6b-fa1e-4cee-91c7-6d8496bea3c1" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkStartStop"> + <attribute name="startEvent" type="boolean" readonly="yes"> + <desc> + IsStartEvent is true when NAT network is started and false on stopping. + </desc> + </attribute> + </interface> + + <!-- base class for modification events --> + <interface name="INATNetworkAlterEvent" extends="INATNetworkChangedEvent" + uuid="3f5a0822-163a-43b1-ad16-8d58b0ef6e75" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkAlter"/> + + <interface name="INATNetworkCreationDeletionEvent" extends="INATNetworkAlterEvent" + uuid="8d984a7e-b855-40b8-ab0c-44d3515b4528" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkCreationDeletion"> + <attribute name="creationEvent" type="boolean" readonly="yes"/> + </interface> + <interface name="INATNetworkSettingEvent" extends="INATNetworkAlterEvent" + uuid="9db3a9e6-7f29-4aae-a627-5a282c83092c" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkSetting"> + <attribute name="enabled" type="boolean" readonly="yes"/> + <attribute name="network" type="wstring" readonly="yes"/> + <attribute name="gateway" type="wstring" readonly="yes"/> + <attribute name="advertiseDefaultIPv6RouteEnabled" type="boolean" readonly="yes"/> + <attribute name="needDhcpServer" type="boolean" readonly="yes"/> + </interface> + <interface name="INATNetworkPortForwardEvent" extends="INATNetworkAlterEvent" + uuid="2514881b-23d0-430a-a7ff-7ed7f05534bc" + wsmap="managed" autogen="VBoxEvent" id="OnNATNetworkPortForward"> + <attribute name="create" type="boolean" readonly="yes"/> + <attribute name="ipv6" type="boolean" readonly="yes"/> + <attribute name="name" type="wstring" readonly="yes"/> + <attribute name="proto" type="NATProtocol" readonly="yes"/> + <attribute name="hostIp" type="wstring" readonly="yes"/> + <attribute name="hostPort" type="long" readonly="yes"/> + <attribute name="guestIp" type="wstring" readonly="yes"/> + <attribute name="guestPort" type="long" readonly="yes"/> + </interface> + + <interface + name="IHostNameResolutionConfigurationChangeEvent" extends="IEvent" + uuid="f9b9e1cf-cb63-47a1-84fb-02c4894b89a9" + wsmap="managed" autogen="VBoxEvent" id="OnHostNameResolutionConfigurationChange" + > </interface> <module name="VBoxSVC" context="LocalServer"> diff --git a/src/VBox/Main/idl/apiwrap-server.xsl b/src/VBox/Main/idl/apiwrap-server.xsl new file mode 100644 index 00000000..2f08e714 --- /dev/null +++ b/src/VBox/Main/idl/apiwrap-server.xsl @@ -0,0 +1,1394 @@ +<?xml version="1.0"?> + +<!-- + apiwrap-server.xsl: + XSLT stylesheet that generates C++ API wrappers (server side) from + VirtualBox.xidl. + + Copyright (C) 2010-2014 Oracle Corporation + + This file is part of VirtualBox Open Source Edition (OSE), as + available from http://www.virtualbox.org. This file is free software; + you can redistribute it and/or modify it under the terms of the GNU + General Public License (GPL) as published by the Free Software + Foundation, in version 2 as it comes in the "COPYING" file of the + VirtualBox OSE distribution. VirtualBox OSE is distributed in the + hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. +--> + +<xsl:stylesheet + version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + extension-element-prefixes="exsl"> + +<xsl:output method="text"/> + +<xsl:strip-space elements="*"/> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + global XSLT variables + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:variable name="G_xsltFilename" select="'apiwrap-server.xsl'"/> + +<xsl:include href="typemap-shared.inc.xsl"/> + +<!-- - - - - - - - - - - - - - - - - - - - - - - +templates for file separation + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="interface" mode="listfile"> + <xsl:param name="file"/> + + <xsl:value-of select="concat('	', $file, ' \ ')"/> +</xsl:template> + +<xsl:template match="interface" mode="startfile"> + <xsl:param name="file"/> + + <xsl:value-of select="concat(' // ##### BEGINFILE "', $file, '" ')"/> +</xsl:template> + +<xsl:template match="interface" mode="endfile"> + <xsl:param name="file"/> + + <xsl:value-of select="concat(' // ##### ENDFILE "', $file, '" ')"/> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - +templates for file headers/footers + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template name="fileheader"> + <xsl:param name="class"/> + <xsl:param name="name"/> + <xsl:param name="type"/> + + <xsl:text>/** @file + * +</xsl:text> + <xsl:value-of select="concat(' * VirtualBox API class wrapper ', $type, ' for I', $class, '.')"/> + <xsl:text> + * + * DO NOT EDIT! This is a generated file. + * Generated from: src/VBox/Main/idl/VirtualBox.xidl + * Generator: src/VBox/Main/idl/apiwrap-server.xsl + */ + +/** + * Copyright (C) 2010-2014 Oracle Corporation + * + * This file is part of VirtualBox Open Source Edition (OSE), as + * available from http://www.virtualbox.org. This file is free software; + * you can redistribute it and/or modify it under the terms of the GNU + * General Public License (GPL) as published by the Free Software + * Foundation, in version 2 as it comes in the "COPYING" file of the + * VirtualBox OSE distribution. VirtualBox OSE is distributed in the + * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. + */ + +</xsl:text> +</xsl:template> + +<xsl:template name="emitCOMInterfaces"> + <xsl:param name="iface"/> + + <xsl:value-of select="concat(' COM_INTERFACE_ENTRY(', $iface/@name, ') ')"/> + <!-- now recurse to emit all base interfaces --> + <xsl:variable name="extends" select="$iface/@extends"/> + <xsl:if test="$extends and not($extends='$unknown') and not($extends='$errorinfo')"> + <xsl:call-template name="emitCOMInterfaces"> + <xsl:with-param name="iface" select="//interface[@name=$extends]"/> + </xsl:call-template> + </xsl:if> +</xsl:template> + +<xsl:template match="interface" mode="classheader"> + <xsl:value-of select="concat('#ifndef ', substring(@name, 2), 'Wrap_H_ ')"/> + <xsl:value-of select="concat('#define ', substring(@name, 2), 'Wrap_H_')"/> + <xsl:text> + +#include "VirtualBoxBase.h" +#include "Wrapper.h" + +</xsl:text> + <xsl:value-of select="concat('class ATL_NO_VTABLE ', substring(@name, 2), 'Wrap:')"/> + <xsl:text> + public VirtualBoxBase, +</xsl:text> + <xsl:value-of select="concat(' VBOX_SCRIPTABLE_IMPL(', @name, ') ')"/> + <xsl:text>{ + Q_OBJECT + +public: +</xsl:text> + <xsl:value-of select="concat(' VIRTUALBOXBASE_ADD_ERRORINFO_SUPPORT(', substring(@name, 2), 'Wrap, ', @name, ') ')"/> + <xsl:value-of select="concat(' DECLARE_NOT_AGGREGATABLE(', substring(@name, 2), 'Wrap) ')"/> + <xsl:text> DECLARE_PROTECT_FINAL_CONSTRUCT() + +</xsl:text> + <xsl:value-of select="concat(' BEGIN_COM_MAP(', substring(@name, 2), 'Wrap) ')"/> + <xsl:text> COM_INTERFACE_ENTRY(ISupportErrorInfo) +</xsl:text> + <xsl:call-template name="emitCOMInterfaces"> + <xsl:with-param name="iface" select="."/> + </xsl:call-template> + <xsl:value-of select="concat(' COM_INTERFACE_ENTRY2(IDispatch, ', @name, ') ')"/> + <xsl:text> END_COM_MAP() + +</xsl:text> + <xsl:value-of select="concat(' DECLARE_EMPTY_CTOR_DTOR(', substring(@name, 2), 'Wrap) ')"/> +</xsl:template> + +<xsl:template match="interface" mode="classfooter"> + <xsl:text>}; + +</xsl:text> + <xsl:value-of select="concat('#endif // !', substring(@name, 2), 'Wrap_H_ ')"/> +</xsl:template> + +<xsl:template match="interface" mode="codeheader"> + <xsl:value-of select="concat('#define LOG_GROUP_MAIN_OVERRIDE LOG_GROUP_MAIN_', translate(substring(@name, 2), $G_lowerCase, $G_upperCase), ' ')"/> + <xsl:value-of select="concat('#include "', substring(@name, 2), 'Wrap.h" ')"/> + <xsl:text>#include "Logging.h" + +</xsl:text> +</xsl:template> + +<xsl:template name="emitISupports"> + <xsl:param name="classname"/> + <xsl:param name="extends"/> + <xsl:param name="depth"/> + <xsl:param name="interfacelist"/> + + <xsl:choose> + <xsl:when test="$extends and not($extends='$unknown') and not($extends='$dispatched') and not($extends='$errorinfo')"> + <xsl:variable name="newextends" select="//interface[@name=$extends]/@extends"/> + <xsl:variable name="newiflist" select="concat($interfacelist, ', ', $extends)"/> + <xsl:call-template name="emitISupports"> + <xsl:with-param name="classname" select="$classname"/> + <xsl:with-param name="extends" select="$newextends"/> + <xsl:with-param name="depth" select="$depth + 1"/> + <xsl:with-param name="interfacelist" select="$newiflist"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat('NS_IMPL_THREADSAFE_ISUPPORTS', $depth, '_CI(', $classname, ', ', $interfacelist, ') ')"/> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template match="interface" mode="codefooter"> + <xsl:text>#ifdef VBOX_WITH_XPCOM +</xsl:text> + <xsl:value-of select="concat('NS_DECL_CLASSINFO(', substring(@name, 2), 'Wrap) ')"/> + + <xsl:call-template name="emitISupports"> + <xsl:with-param name="classname" select="concat(substring(@name, 2), 'Wrap')"/> + <xsl:with-param name="extends" select="@extends"/> + <xsl:with-param name="depth" select="1"/> + <xsl:with-param name="interfacelist" select="@name"/> + </xsl:call-template> + + <xsl:text>#endif // VBOX_WITH_XPCOM +</xsl:text> +</xsl:template> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + templates for dealing with names and parameters + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template name="tospace"> + <xsl:param name="str"/> + <xsl:value-of select="translate($str, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_', ' ')"/> +</xsl:template> + +<xsl:template name="checkoption"> + <xsl:param name="optionlist"/> + <xsl:param name="option"/> + <xsl:value-of select="string-length($option) > 0 and contains(concat(',', translate($optionlist, ' ', ''), ','), concat(',', $option, ','))"/> +</xsl:template> + +<xsl:template name="translatepublictype"> + <xsl:param name="type"/> + <xsl:param name="dir"/> + + <!-- get C++ glue type from IDL type from table in typemap-shared.inc.xsl --> + <xsl:variable name="gluetypefield" select="exsl:node-set($G_aSharedTypes)/type[@idlname=$type]/@gluename"/> + <xsl:choose> + <xsl:when test="$type='wstring' or $type='uuid'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>IN_BSTR</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>BSTR</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="string-length($gluetypefield)"> + <xsl:value-of select="$gluetypefield"/> + </xsl:when> + <xsl:when test="//enum[@name=$type]"> + <xsl:value-of select="concat($type, '_T')"/> + </xsl:when> + <xsl:when test="$type='$unknown'"> + <xsl:text>IUnknown *</xsl:text> + </xsl:when> + <xsl:when test="//interface[@name=$type]"> + <xsl:variable name="thatif" select="//interface[@name=$type]"/> + <xsl:variable name="thatifname" select="$thatif/@name"/> + <xsl:value-of select="concat($thatifname, ' *')"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="fatalError"> + <xsl:with-param name="msg" select="concat('translatepublictype: Type "', $type, '" is not supported.')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template name="translatewrappedtype"> + <xsl:param name="type"/> + <xsl:param name="dir"/> + <xsl:param name="safearray"/> + + <!-- get C++ wrap type from IDL type from table in typemap-shared.inc.xsl --> + <xsl:variable name="wraptypefield" select="exsl:node-set($G_aSharedTypes)/type[@idlname=$type]/@gluename"/> + <xsl:choose> + <xsl:when test="$type='wstring'"> + <xsl:if test="$dir='in' and not($safearray='yes')"> + <xsl:text>const </xsl:text> + </xsl:if> + <xsl:text>com::Utf8Str &</xsl:text> + </xsl:when> + <xsl:when test="$type='uuid'"> + <xsl:if test="$dir='in'"> + <xsl:text>const </xsl:text> + </xsl:if> + <xsl:text>com::Guid &</xsl:text> + </xsl:when> + <xsl:when test="string-length($wraptypefield)"> + <xsl:value-of select="$wraptypefield"/> + </xsl:when> + <xsl:when test="//enum[@name=$type]"> + <xsl:value-of select="concat($type, '_T')"/> + </xsl:when> + <xsl:when test="$type='$unknown'"> + <xsl:if test="$dir='in' and not($safearray='yes')"> + <xsl:text>const </xsl:text> + </xsl:if> + <xsl:text>ComPtr<IUnknown> &</xsl:text> + </xsl:when> + <xsl:when test="//interface[@name=$type]"> + <xsl:variable name="thatif" select="//interface[@name=$type]"/> + <xsl:variable name="thatifname" select="$thatif/@name"/> + <xsl:if test="$dir='in' and not($safearray='yes')"> + <xsl:text>const </xsl:text> + </xsl:if> + <xsl:value-of select="concat('ComPtr<', $thatifname, '> &')"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="fatalError"> + <xsl:with-param name="msg" select="concat('translatewrappedtype: Type "', $type, '" is not supported.')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template name="translatefmtspectype"> + <xsl:param name="type"/> + <xsl:param name="dir"/> + <xsl:param name="safearray"/> + <xsl:param name="mod"/> + + <!-- get C format string for IDL type from table in typemap-shared.inc.xsl --> + <xsl:variable name="wrapfmt" select="exsl:node-set($G_aSharedTypes)/type[@idlname=$type]/@gluefmt"/> + <xsl:choose> + <xsl:when test="$mod='ref' and $dir!='in'"> + <xsl:text>%p</xsl:text> + </xsl:when> + <xsl:when test="$safearray='yes'"> + <xsl:text>%zu</xsl:text> + </xsl:when> + <xsl:when test="string-length($wrapfmt)"> + <xsl:value-of select="$wrapfmt"/> + </xsl:when> + <xsl:when test="//enum[@name=$type]"> + <xsl:text>%RU32</xsl:text> + </xsl:when> + <xsl:when test="$type='$unknown'"> + <xsl:text>%p</xsl:text> + </xsl:when> + <xsl:when test="//interface[@name=$type]"> + <xsl:text>%p</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="fatalError"> + <xsl:with-param name="msg" select="concat('translatefmtcpectype: Type "', $type, '" is not supported.')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template match="attribute/@type | param/@type" mode="public"> + <xsl:param name="dir"/> + + <xsl:variable name="gluetype"> + <xsl:call-template name="translatepublictype"> + <xsl:with-param name="type" select="."/> + <xsl:with-param name="dir" select="$dir"/> + </xsl:call-template> + </xsl:variable> + + <xsl:if test="../@safearray='yes'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayIn(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOut(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + <xsl:value-of select="$gluetype"/> + <xsl:choose> + <xsl:when test="../@safearray='yes'"> + <xsl:text>, </xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:if test="substring($gluetype,string-length($gluetype))!='*'"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$dir='in'"> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="'*'"/> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + <xsl:text>a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="../@name"/> + </xsl:call-template> + <xsl:if test="../@safearray='yes'"> + <xsl:value-of select="')'"/> + </xsl:if> +</xsl:template> + +<xsl:template match="attribute/@type | param/@type" mode="wrapped"> + <xsl:param name="dir"/> + + <xsl:variable name="wraptype"> + <xsl:call-template name="translatewrappedtype"> + <xsl:with-param name="type" select="."/> + <xsl:with-param name="dir" select="$dir"/> + <xsl:with-param name="safearray" select="../@safearray"/> + </xsl:call-template> + </xsl:variable> + + <xsl:choose> + <xsl:when test="../@safearray='yes'"> + <xsl:if test="$dir='in'"> + <xsl:text>const </xsl:text> + </xsl:if> + <xsl:text>std::vector<</xsl:text> + <xsl:choose> + <xsl:when test="substring($wraptype,string-length($wraptype))='&'"> + <xsl:variable name="wraptype2"> + <xsl:value-of select="substring($wraptype,1,string-length($wraptype)-2)"/> + </xsl:variable> + + <xsl:choose> + <xsl:when test="substring($wraptype2,string-length($wraptype2))='>'"> + <xsl:value-of select="concat($wraptype2, ' ')"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$wraptype2"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="substring($wraptype,string-length($wraptype))='>'"> + <xsl:value-of select="concat($wraptype, ' ')"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$wraptype"/> + </xsl:otherwise> + </xsl:choose> + <xsl:text>> &</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$wraptype"/> + <xsl:if test="substring($wraptype,string-length($wraptype))!='&'"> + <xsl:if test="substring($wraptype,string-length($wraptype))!='*'"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$dir='in'"> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="'*'"/> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + <xsl:text>a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="../@name"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="attribute/@type | param/@type" mode="logparamtext"> + <xsl:param name="dir"/> + <xsl:param name="mod"/> + + <xsl:if test="$mod!='ref' and ($dir='out' or $dir='ret')"> + <xsl:text>*</xsl:text> + </xsl:if> + <xsl:text>a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="../@name"/> + </xsl:call-template> + <xsl:text>=</xsl:text> + <xsl:call-template name="translatefmtspectype"> + <xsl:with-param name="type" select="."/> + <xsl:with-param name="dir" select="$dir"/> + <xsl:with-param name="safearray" select="../@safearray"/> + <xsl:with-param name="mod" select="$mod"/> + </xsl:call-template> +</xsl:template> + +<xsl:template match="attribute/@type | param/@type" mode="logparamval"> + <xsl:param name="dir"/> + <xsl:param name="mod"/> + + <xsl:choose> + <xsl:when test="../@safearray='yes' and $mod!='ref'"> + <xsl:text>ComSafeArraySize(</xsl:text> + <xsl:if test="$mod!='ref' and $dir!='in'"> + <xsl:text>*</xsl:text> + </xsl:if> + </xsl:when> + <xsl:when test="$mod!='ref' and $dir!='in'"> + <xsl:text>*</xsl:text> + </xsl:when> + </xsl:choose> + <xsl:text>a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="../@name"/> + </xsl:call-template> + <xsl:choose> + <xsl:when test="../@safearray='yes' and $mod!='ref'"> + <xsl:text>)</xsl:text> + </xsl:when> + </xsl:choose> +</xsl:template> + +<xsl:template match="attribute/@type | param/@type" mode="paramvalconversion"> + <xsl:param name="dir"/> + + <xsl:variable name="gluetype"> + <xsl:call-template name="translatepublictype"> + <xsl:with-param name="type" select="."/> + <xsl:with-param name="dir" select="$dir"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="type" select="."/> + <xsl:variable name="thatif" select="../../../..//interface[@name=$type]"/> + <xsl:choose> + <xsl:when test="$type='$unknown'"> + <xsl:if test="../@safearray='yes'"> + <xsl:text>Array</xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComTypeInConverter<IUnknown>(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComTypeOutConverter<IUnknown>(</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="../@safearray='yes'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayInArg(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOutArg(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:when> + <xsl:when test="$thatif"> + <xsl:if test="../@safearray='yes'"> + <xsl:text>Array</xsl:text> + </xsl:if> + <xsl:variable name="thatifname" select="$thatif/@name"/> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComTypeInConverter</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComTypeOutConverter</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:value-of select="concat('<', $thatifname, '>(')"/> + <xsl:if test="../@safearray='yes'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayInArg(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOutArg(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:when> + <xsl:when test="$type='wstring'"> + <xsl:if test="../@safearray='yes'"> + <xsl:text>Array</xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>BSTRInConverter(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>BSTROutConverter(</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="../@safearray='yes'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayInArg(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOutArg(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:when> + <xsl:when test="$type='uuid'"> + <xsl:if test="../@safearray='yes'"> + <xsl:text>Array</xsl:text> + </xsl:if> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>UuidInConverter(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>UuidOutConverter(</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="../@safearray='yes'"> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayInArg(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOutArg(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:when> + <xsl:otherwise> + <xsl:if test="../@safearray='yes'"> + <xsl:text>Array</xsl:text> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>InConverter</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>OutConverter</xsl:text> + </xsl:otherwise> + </xsl:choose> + <xsl:value-of select="concat('<', $gluetype, '>(')"/> + <xsl:choose> + <xsl:when test="$dir='in'"> + <xsl:text>ComSafeArrayInArg(</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>ComSafeArrayOutArg(</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:if> + </xsl:otherwise> + </xsl:choose> + <xsl:text>a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="../@name"/> + </xsl:call-template> + <xsl:choose> + <xsl:when test="$type='$unknown' or $thatif"> + <xsl:choose> + <xsl:when test="../@safearray='yes'"> + <xsl:text>)).array()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>).ptr()</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="$type='wstring'"> + <xsl:choose> + <xsl:when test="../@safearray='yes'"> + <xsl:text>)).array()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>).str()</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="$type='uuid'"> + <xsl:choose> + <xsl:when test="../@safearray='yes'"> + <xsl:text>)).array()</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>).uuid()</xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:otherwise> + <xsl:if test="../@safearray='yes'"> + <xsl:text>)).array()</xsl:text> + </xsl:if> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit attribute + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="attribute" mode="public"> + <xsl:variable name="attrbasename"> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:value-of select="concat(' STDMETHOD(COMGETTER(', $attrbasename, '))(')"/> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text>); +</xsl:text> + + <xsl:if test="not(@readonly) or @readonly!='yes'"> + <xsl:value-of select="concat(' STDMETHOD(COMSETTER(', $attrbasename, '))(')"/> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <xsl:text>); +</xsl:text> + </xsl:if> +</xsl:template> + +<xsl:template match="attribute" mode="wrapped"> + <xsl:variable name="attrbasename"> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:value-of select="concat(' virtual HRESULT get', $attrbasename, '(')"/> + <xsl:variable name="passAutoCaller"> + <xsl:call-template name="checkoption"> + <xsl:with-param name="optionlist" select="@wrap-hint-server"/> + <xsl:with-param name="option" select="'passcaller'"/> + </xsl:call-template> + </xsl:variable> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>AutoCaller &aAutoCaller, </xsl:text> + </xsl:if> + <xsl:apply-templates select="@type" mode="wrapped"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text>) = 0; +</xsl:text> + + <xsl:if test="not(@readonly) or @readonly!='yes'"> + <xsl:value-of select="concat(' virtual HRESULT set', $attrbasename, '(')"/> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>AutoCaller &aAutoCaller, </xsl:text> + </xsl:if> + <xsl:apply-templates select="@type" mode="wrapped"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <xsl:text>) = 0; +</xsl:text> + </xsl:if> +</xsl:template> + +<xsl:template match="attribute" mode="code"> + <xsl:param name="topclass"/> + + <xsl:variable name="attrbasename"> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:value-of select="concat('STDMETHODIMP ', $topclass, 'Wrap::COMGETTER(', $attrbasename, ')(')"/> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text>) +{ + LogRelFlow(("{%p} %s: enter </xsl:text> + <xsl:apply-templates select="@type" mode="logparamtext"> + <xsl:with-param name="dir" select="'out'"/> + <xsl:with-param name="mod" select="'ref'"/> + </xsl:apply-templates> + <xsl:text>\n", this, </xsl:text> + <xsl:value-of select="concat('"', $topclass, '::get', $attrbasename, '", ')"/> + <xsl:apply-templates select="@type" mode="logparamval"> + <xsl:with-param name="dir" select="'out'"/> + <xsl:with-param name="mod" select="'ref'"/> + </xsl:apply-templates> + <xsl:text>)); + + VirtualBoxBase::clearError(); + + HRESULT hrc; + + try + { + CheckComArgOutPointerValidThrow(a</xsl:text> + <xsl:value-of select="$attrbasename"/> + <xsl:text>); + + AutoCaller autoCaller(this); + if (FAILED(autoCaller.rc())) + throw autoCaller.rc(); + +</xsl:text> + <xsl:value-of select="concat(' hrc = get', $attrbasename, '(')"/> + <xsl:variable name="passAutoCaller"> + <xsl:call-template name="checkoption"> + <xsl:with-param name="optionlist" select="@wrap-hint-server"/> + <xsl:with-param name="option" select="'passcaller'"/> + </xsl:call-template> + </xsl:variable> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>autoCaller, </xsl:text> + </xsl:if> + <xsl:apply-templates select="@type" mode="paramvalconversion"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text>); + } + catch (HRESULT hrc2) + { + hrc = hrc2; + } + catch (...) + { + hrc = VirtualBoxBase::handleUnexpectedExceptions(this, RT_SRC_POS); + } + + LogRelFlow(("{%p} %s: leave </xsl:text> + <xsl:apply-templates select="@type" mode="logparamtext"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text> hrc=%Rhrc\n", this, </xsl:text> + <xsl:value-of select="concat('"', $topclass, '::get', $attrbasename, '", ')"/> + <xsl:apply-templates select="@type" mode="logparamval"> + <xsl:with-param name="dir" select="'out'"/> + </xsl:apply-templates> + <xsl:text>, hrc)); + return hrc; +} + +</xsl:text> + <xsl:if test="not(@readonly) or @readonly!='yes'"> + <xsl:value-of select="concat('STDMETHODIMP ', $topclass, 'Wrap::COMSETTER(', $attrbasename, ')(')"/> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <!-- @todo check in parameters if possible --> + <xsl:text>) +{ + LogRelFlow(("{%p} %s: enter </xsl:text> + <xsl:apply-templates select="@type" mode="logparamtext"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <xsl:text>\n", this, </xsl:text> + <xsl:value-of select="concat('"', $topclass, '::set', $attrbasename, '", ')"/> + <xsl:apply-templates select="@type" mode="logparamval"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <xsl:text>)); + + VirtualBoxBase::clearError(); + + HRESULT hrc; + + try + { + AutoCaller autoCaller(this); + if (FAILED(autoCaller.rc())) + throw autoCaller.rc(); + +</xsl:text> + <xsl:value-of select="concat(' hrc = set', $attrbasename, '(')"/> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>autoCaller, </xsl:text> + </xsl:if> + <xsl:apply-templates select="@type" mode="paramvalconversion"> + <xsl:with-param name="dir" select="'in'"/> + </xsl:apply-templates> + <xsl:text>); + } + catch (HRESULT hrc2) + { + hrc = hrc2; + } + catch (...) + { + hrc = VirtualBoxBase::handleUnexpectedExceptions(this, RT_SRC_POS); + } + + LogRelFlow(("{%p} %s: leave hrc=%Rhrc\n", this, </xsl:text> + <xsl:value-of select="concat('"', $topclass, '::set', $attrbasename, '", ')"/> + <xsl:text>hrc)); + return hrc; +} + +</xsl:text> + </xsl:if> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit all attributes of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitAttributes"> + <xsl:param name="iface"/> + <xsl:param name="topclass"/> + <xsl:param name="pmode"/> + + <!-- first recurse to emit all base interfaces --> + <xsl:variable name="extends" select="$iface/@extends"/> + <xsl:if test="$extends and not($extends='$unknown') and not($extends='$errorinfo')"> + <xsl:call-template name="emitAttributes"> + <xsl:with-param name="iface" select="//interface[@name=$extends]"/> + <xsl:with-param name="topclass" select="$topclass"/> + <xsl:with-param name="pmode" select="$pmode"/> + </xsl:call-template> + </xsl:if> + + <xsl:choose> + <xsl:when test="$pmode='code'"> + <xsl:text>// +</xsl:text> + <xsl:value-of select="concat('// ', $iface/@name, ' properties')"/> + <xsl:text> +// + +</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat(' // ', $pmode, ' ', $iface/@name, ' properties ')"/> + </xsl:otherwise> + </xsl:choose> + <xsl:choose> + <xsl:when test="$pmode='public'"> + <xsl:apply-templates select="$iface/attribute" mode="public"/> + </xsl:when> + <xsl:when test="$pmode='wrapped'"> + <xsl:apply-templates select="$iface/attribute" mode="wrapped"/> + </xsl:when> + <xsl:when test="$pmode='code'"> + <xsl:apply-templates select="$iface/attribute" mode="code"> + <xsl:with-param name="topclass" select="$topclass"/> + </xsl:apply-templates> + </xsl:when> + <xsl:otherwise/> + </xsl:choose> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit method + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="method" mode="public"> + <xsl:variable name="methodindent"> + <xsl:call-template name="tospace"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:text> STDMETHOD(</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + <xsl:text>)(</xsl:text> + <xsl:for-each select="param"> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + <xsl:if test="not(position()=last())"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodindent"/> + </xsl:if> + </xsl:for-each> + <xsl:text>); +</xsl:text> +</xsl:template> + +<xsl:template match="method" mode="wrapped"> + <xsl:variable name="methodindent"> + <xsl:call-template name="tospace"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:text> virtual HRESULT </xsl:text> + <xsl:call-template name="uncapitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + <xsl:text>(</xsl:text> + <xsl:variable name="passAutoCaller"> + <xsl:call-template name="checkoption"> + <xsl:with-param name="optionlist" select="@wrap-hint-server"/> + <xsl:with-param name="option" select="'passcaller'"/> + </xsl:call-template> + </xsl:variable> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>AutoCaller &aAutoCaller</xsl:text> + <xsl:if test="count(param) > 0"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodindent"/> + </xsl:if> + </xsl:if> + <xsl:for-each select="param"> + <xsl:apply-templates select="@type" mode="wrapped"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + <xsl:if test="not(position()=last())"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodindent"/> + </xsl:if> + </xsl:for-each> + <xsl:text>) = 0; +</xsl:text> +</xsl:template> + +<xsl:template match="method" mode="code"> + <xsl:param name="topclass"/> + + <xsl:variable name="methodindent"> + <xsl:call-template name="tospace"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="methodclassindent"> + <xsl:call-template name="tospace"> + <xsl:with-param name="str" select="concat($topclass, @name)"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="methodbasename"> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + </xsl:variable> + + <xsl:value-of select="concat('STDMETHODIMP ', $topclass, 'Wrap::', $methodbasename, '(')"/> + <xsl:for-each select="param"> + <xsl:apply-templates select="@type" mode="public"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + <xsl:if test="not(position()=last())"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodclassindent"/> + </xsl:if> + </xsl:for-each> + <xsl:text>) +{ + LogRelFlow(("{%p} %s:enter</xsl:text> + <xsl:for-each select="param"> + <xsl:text> </xsl:text> + <xsl:apply-templates select="@type" mode="logparamtext"> + <xsl:with-param name="dir" select="@dir"/> + <xsl:with-param name="mod" select="'ref'"/> + </xsl:apply-templates> + </xsl:for-each> + <xsl:text>\n", this</xsl:text> + <xsl:value-of select="concat(', "', $topclass, '::', @name, '"')"/> + <xsl:for-each select="param"> + <xsl:text>, </xsl:text> + <xsl:apply-templates select="@type" mode="logparamval"> + <xsl:with-param name="dir" select="@dir"/> + <xsl:with-param name="mod" select="'ref'"/> + </xsl:apply-templates> + </xsl:for-each> + <xsl:text>)); + + VirtualBoxBase::clearError(); + + HRESULT hrc; + + try + { +</xsl:text> + <!-- @todo check in parameters if possible --> + <xsl:for-each select="param"> + <xsl:if test="@dir!='in'"> + <xsl:text> CheckComArgOutPointerValidThrow(a</xsl:text> + <xsl:call-template name="capitalize"> + <xsl:with-param name="str" select="@name"/> + </xsl:call-template> + <xsl:text>); +</xsl:text> + </xsl:if> + </xsl:for-each> + <xsl:text> + AutoCaller autoCaller(this); + if (FAILED(autoCaller.rc())) + throw autoCaller.rc(); + +</xsl:text> + <xsl:value-of select="concat(' hrc = ', @name, '(')"/> + <xsl:variable name="passAutoCaller"> + <xsl:call-template name="checkoption"> + <xsl:with-param name="optionlist" select="@wrap-hint-server"/> + <xsl:with-param name="option" select="'passcaller'"/> + </xsl:call-template> + </xsl:variable> + <xsl:if test="$passAutoCaller = 'true'"> + <xsl:text>autoCaller</xsl:text> + <xsl:if test="count(param) > 0"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodindent"/> + </xsl:if> + </xsl:if> + <xsl:for-each select="param"> + <xsl:apply-templates select="@type" mode="paramvalconversion"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + <xsl:if test="not(position()=last())"> + <xsl:text>, + </xsl:text> + <xsl:value-of select="$methodindent"/> + </xsl:if> + </xsl:for-each> + <xsl:text>); + } + catch (HRESULT hrc2) + { + hrc = hrc2; + } + catch (...) + { + hrc = VirtualBoxBase::handleUnexpectedExceptions(this, RT_SRC_POS); + } + + LogRelFlow(("{%p} %s: leave</xsl:text> + <xsl:for-each select="param"> + <xsl:if test="@dir!='in'"> + <xsl:text> </xsl:text> + <xsl:apply-templates select="@type" mode="logparamtext"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + </xsl:if> + </xsl:for-each> + <xsl:text> hrc=%Rhrc\n", this</xsl:text> + <xsl:value-of select="concat(', "', $topclass, '::', @name, '"')"/> + <xsl:for-each select="param"> + <xsl:if test="@dir!='in'"> + <xsl:text>, </xsl:text> + <xsl:apply-templates select="@type" mode="logparamval"> + <xsl:with-param name="dir" select="@dir"/> + </xsl:apply-templates> + </xsl:if> + </xsl:for-each> + <xsl:text>, hrc)); + return hrc; +} + +</xsl:text> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit all methods of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitMethods"> + <xsl:param name="iface"/> + <xsl:param name="topclass"/> + <xsl:param name="pmode"/> + + <!-- first recurse to emit all base interfaces --> + <xsl:variable name="extends" select="$iface/@extends"/> + <xsl:if test="$extends and not($extends='$unknown') and not($extends='$errorinfo')"> + <xsl:call-template name="emitMethods"> + <xsl:with-param name="iface" select="//interface[@name=$extends]"/> + <xsl:with-param name="topclass" select="$topclass"/> + <xsl:with-param name="pmode" select="$pmode"/> + </xsl:call-template> + </xsl:if> + + <xsl:choose> + <xsl:when test="$pmode='code'"> + <xsl:text>// +</xsl:text> + <xsl:value-of select="concat('// ', $iface/@name, ' methods')"/> + <xsl:text> +// + +</xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat(' // ', $pmode, ' ', $iface/@name, ' methods ')"/> + </xsl:otherwise> + </xsl:choose> + <xsl:choose> + <xsl:when test="$pmode='public'"> + <xsl:apply-templates select="$iface/method" mode="public"/> + </xsl:when> + <xsl:when test="$pmode='wrapped'"> + <xsl:apply-templates select="$iface/method" mode="wrapped"/> + </xsl:when> + <xsl:when test="$pmode='code'"> + <xsl:apply-templates select="$iface/method" mode="code"> + <xsl:with-param name="topclass" select="$topclass"/> + </xsl:apply-templates> + </xsl:when> + <xsl:otherwise/> + </xsl:choose> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit all attributes and methods declarations of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitInterfaceDecls"> + <xsl:param name="iface"/> + <xsl:param name="pmode"/> + + <!-- attributes --> + <xsl:call-template name="emitAttributes"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="pmode" select="$pmode"/> + </xsl:call-template> + + <!-- methods --> + <xsl:call-template name="emitMethods"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="pmode" select="$pmode"/> + </xsl:call-template> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit auxiliary method declarations of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitAuxMethodDecls"> + <xsl:param name="iface"/> + <!-- currently nothing, maybe later some generic FinalConstruct/... helper declaration for ComObjPtr --> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit the header file of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitHeader"> + <xsl:param name="iface"/> + + <xsl:variable name="filename" select="concat(substring(@name, 2), 'Wrap.h')"/> + + <xsl:choose> + <xsl:when test="$filelistonly=''"> + <xsl:apply-templates select="$iface" mode="startfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + <xsl:call-template name="fileheader"> + <xsl:with-param name="name" select="$filename"/> + <xsl:with-param name="class" select="substring(@name, 2)"/> + <xsl:with-param name="type" select="'header'"/> + </xsl:call-template> + <xsl:apply-templates select="." mode="classheader"/> + + <!-- interface attributes/methods (public) --> + <xsl:call-template name="emitInterfaceDecls"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="pmode" select="'public'"/> + </xsl:call-template> + + <!-- auxiliary methods (public) --> + <xsl:call-template name="emitAuxMethodDecls"> + <xsl:with-param name="iface" select="$iface"/> + </xsl:call-template> + + <!-- switch to private --> + <xsl:text> +private:</xsl:text> + + <!-- wrapped interface attributes/methods (private) --> + <xsl:call-template name="emitInterfaceDecls"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="pmode" select="'wrapped'"/> + </xsl:call-template> + + <xsl:apply-templates select="." mode="classfooter"/> + <xsl:apply-templates select="$iface" mode="endfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates select="$iface" mode="listfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit all attributes and methods definitions of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitInterfaceDefs"> + <xsl:param name="iface"/> + + <xsl:value-of select="concat('DEFINE_EMPTY_CTOR_DTOR(', substring($iface/@name, 2), 'Wrap) ')"/> + + <!-- attributes --> + <xsl:call-template name="emitAttributes"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="topclass" select="substring($iface/@name, 2)"/> + <xsl:with-param name="pmode" select="'code'"/> + </xsl:call-template> + + <!-- methods --> + <xsl:call-template name="emitMethods"> + <xsl:with-param name="iface" select="$iface"/> + <xsl:with-param name="topclass" select="substring($iface/@name, 2)"/> + <xsl:with-param name="pmode" select="'code'"/> + </xsl:call-template> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit auxiliary method declarations of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitAuxMethodDefs"> + <xsl:param name="iface"/> + <!-- currently nothing, maybe later some generic FinalConstruct/... implementation --> +</xsl:template> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + emit the code file of an interface + - - - - - - - - - - - - - - - - - - - - - - --> +<xsl:template name="emitCode"> + <xsl:param name="iface"/> + + <xsl:variable name="filename" select="concat(substring(@name, 2), 'Wrap.cpp')"/> + + <xsl:choose> + <xsl:when test="$filelistonly=''"> + <xsl:apply-templates select="$iface" mode="startfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + <xsl:call-template name="fileheader"> + <xsl:with-param name="name" select="$filename"/> + <xsl:with-param name="class" select="substring(@name, 2)"/> + <xsl:with-param name="type" select="'code'"/> + </xsl:call-template> + <xsl:apply-templates select="." mode="codeheader"/> + + <!-- @todo special thread logging for API methods returning IProgress??? would be very usefulcurrently nothing, maybe later some generic FinalConstruct/... implementation --> + + <!-- interface attributes/methods (public) --> + <xsl:call-template name="emitInterfaceDefs"> + <xsl:with-param name="iface" select="$iface"/> + </xsl:call-template> + + <!-- auxiliary methods (public) --> + <xsl:call-template name="emitAuxMethodDefs"> + <xsl:with-param name="iface" select="$iface"/> + </xsl:call-template> + + <xsl:apply-templates select="." mode="codefooter"/> + <xsl:apply-templates select="$iface" mode="endfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + </xsl:when> + <xsl:otherwise> + <xsl:apply-templates select="$iface" mode="listfile"> + <xsl:with-param name="file" select="$filename"/> + </xsl:apply-templates> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - + wildcard match, ignore everything which has no explicit match + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="*"/> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + ignore all if tags except those for XPIDL or MIDL target + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="if"> + <xsl:if test="(@target = 'xpidl') or (@target = 'midl')"> + <xsl:apply-templates/> + </xsl:if> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + library match + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="interface"> + <xsl:if test="not(@supportsErrorInfo='no')"> + <xsl:call-template name="emitHeader"> + <xsl:with-param name="iface" select="."/> + </xsl:call-template> + + <xsl:call-template name="emitCode"> + <xsl:with-param name="iface" select="."/> + </xsl:call-template> + </xsl:if> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + library match + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="library"> + <xsl:apply-templates/> +</xsl:template> + +<!-- - - - - - - - - - - - - - - - - - - - - - - + root match + - - - - - - - - - - - - - - - - - - - - - - --> + +<xsl:template match="/idl"> + <xsl:choose> + <xsl:when test="$filelistonly=''"> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($filelistonly, ' := \ ')"/> + </xsl:otherwise> + </xsl:choose> + <xsl:apply-templates/> + <xsl:choose> + <xsl:when test="$filelistonly=''"> + </xsl:when> + <xsl:otherwise> + <xsl:text> +</xsl:text> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> +<!-- vi: set tabstop=4 shiftwidth=4 expandtab: --> diff --git a/src/VBox/Main/idl/comimpl.xsl b/src/VBox/Main/idl/comimpl.xsl index 58889cbd..59ae42b8 100644 --- a/src/VBox/Main/idl/comimpl.xsl +++ b/src/VBox/Main/idl/comimpl.xsl @@ -13,7 +13,7 @@ rather trivial container classes for their read-only attributes. Further extension to other interfaces is possible and anticipated. - Copyright (C) 2010-2012 Oracle Corporation + Copyright (C) 2010-2013 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; @@ -30,7 +30,7 @@ encoding="utf-8" indent="no"/> -<xsl:include href="../webservice/websrv-shared.inc.xsl" /> +<xsl:include href="typemap-shared.inc.xsl" /> <!-- $G_kind contains what kind of COM class implementation we generate --> <xsl:variable name="G_xsltFilename" select="'autogen.xsl'" /> @@ -46,7 +46,7 @@ */ /* - * Copyright (C) 2010-2012 Oracle Corporation + * Copyright (C) 2010-2013 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; @@ -149,6 +149,12 @@ <xsl:when test="$type='octet'"> <xsl:value-of select="'BYTE'" /> </xsl:when> + <xsl:when test="$type='unsigned short'"> + <xsl:value-of select="'USHORT'" /> + </xsl:when> + <xsl:when test="$type='short'"> + <xsl:value-of select="'SHORT'" /> + </xsl:when> <xsl:when test="$type='unsigned long'"> <xsl:value-of select="'ULONG'" /> </xsl:when> @@ -189,7 +195,7 @@ <xsl:when test="$safearray='yes'"> <xsl:variable name="elemtype"> <xsl:call-template name="typeIdl2Back"> - <xsl:with-param name="type" select="@type" /> + <xsl:with-param name="type" select="$type" /> <xsl:with-param name="safearray" select="''" /> <xsl:with-param name="dir" select="'in'" /> </xsl:call-template> @@ -212,7 +218,7 @@ <xsl:when test="$safearray='yes'"> <xsl:variable name="elemtype"> <xsl:call-template name="typeIdl2Back"> - <xsl:with-param name="type" select="@type" /> + <xsl:with-param name="type" select="$type" /> <xsl:with-param name="safearray" select="''" /> <xsl:with-param name="dir" select="'in'" /> </xsl:call-template> @@ -293,14 +299,14 @@ </xsl:call-template> </xsl:variable> <xsl:value-of select=" '#ifdef RT_OS_WINDOWS '"/> - <xsl:value-of select=" ' SAFEARRAY * aPtr = va_arg(args, SAFEARRAY *); '"/> - <xsl:value-of select="concat(' com::SafeArray<', $elemtype,'> aArr(aPtr); ')"/> + <xsl:value-of select="concat(' SAFEARRAY *aPtr_', @name, ' = va_arg(args, SAFEARRAY *); ')"/> + <xsl:value-of select="concat(' com::SafeArray<', $elemtype,'> aArr_', @name, '(aPtr_', @name, '); ')"/> <xsl:value-of select=" '#else '"/> - <xsl:value-of select=" ' PRUint32 aArrSize = va_arg(args, PRUint32); '"/> - <xsl:value-of select=" ' void* aPtr = va_arg(args, void*); '"/> - <xsl:value-of select="concat(' com::SafeArray<', $elemtype,'> aArr(aArrSize, (', $elemtype,'*)aPtr); ')"/> + <xsl:value-of select="concat(' PRUint32 aArrSize_', @name, ' = va_arg(args, PRUint32); ')"/> + <xsl:value-of select="concat(' void* aPtr_', @name, ' = va_arg(args, void*); ')"/> + <xsl:value-of select="concat(' com::SafeArray<', $elemtype,'> aArr_', @name, '(aArrSize_', @name, ', (', $elemtype,'*)aPtr_', @name, '); ')"/> <xsl:value-of select=" '#endif '"/> - <xsl:value-of select="concat(' ',$obj, '->set_', @name, '(ComSafeArrayAsInParam(aArr)); ')"/> + <xsl:value-of select="concat(' ',$obj, '->set_', @name, '(ComSafeArrayAsInParam(aArr_', @name, ')); ')"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="concat(' ',$aTypeName, ' = va_arg(args, ',$aType,'); ')"/> @@ -321,10 +327,10 @@ </xsl:variable> <xsl:choose> - <xsl:when test="$extends='IEvent'"> + <xsl:when test="$name='IEvent'"> <xsl:value-of select=" '#ifdef VBOX_WITH_XPCOM '" /> <xsl:value-of select="concat('NS_DECL_CLASSINFO(', $impl, ') ')" /> - <xsl:value-of select="concat('NS_IMPL_THREADSAFE_ISUPPORTS',$depth,'_CI(', $impl, ', ', $name, $parents, ', IEvent) ')" /> + <xsl:value-of select="concat('NS_IMPL_THREADSAFE_ISUPPORTS',$depth,'_CI(', $impl, $parents, ', IEvent) ')" /> <xsl:value-of select=" '#endif '"/> </xsl:when> <xsl:when test="//interface[@name=$extends]"> @@ -332,7 +338,7 @@ <xsl:with-param name="impl" select="$impl" /> <xsl:with-param name="name" select="$extends" /> <xsl:with-param name="depth" select="$depth+1" /> - <xsl:with-param name="parents" select="concat($parents, ', ', @name)" /> + <xsl:with-param name="parents" select="concat($parents, ', ', $name)" /> </xsl:call-template> </xsl:when> <xsl:otherwise> @@ -585,7 +591,7 @@ private: <xsl:call-template name="genImplList"> <xsl:with-param name="impl" select="$implName" /> <xsl:with-param name="name" select="@name" /> - <xsl:with-param name="depth" select="'2'" /> + <xsl:with-param name="depth" select="'1'" /> <xsl:with-param name="parents" select="''" /> </xsl:call-template> diff --git a/src/VBox/Main/idl/docstrip.xsl b/src/VBox/Main/idl/docstrip.xsl index 0cbdac4a..9efb49ae 100644 --- a/src/VBox/Main/idl/docstrip.xsl +++ b/src/VBox/Main/idl/docstrip.xsl @@ -9,7 +9,7 @@ original XIDL should not cause a full recompile of nearly all of VirtualBox. - Copyright (C) 2009-2010 Oracle Corporation + Copyright (C) 2009-2012 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; diff --git a/src/VBox/Main/idl/doxygen.xsl b/src/VBox/Main/idl/doxygen.xsl index bc55d3d9..df12cd20 100644 --- a/src/VBox/Main/idl/doxygen.xsl +++ b/src/VBox/Main/idl/doxygen.xsl @@ -5,7 +5,7 @@ * definition expressed in XML. The generated file is intended solely to * generate the documentation using Doxygen. - Copyright (C) 2006-2010 Oracle Corporation + Copyright (C) 2006-2012 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; diff --git a/src/VBox/Main/idl/midl.xsl b/src/VBox/Main/idl/midl.xsl index 0ded778f..5ee2c302 100644 --- a/src/VBox/Main/idl/midl.xsl +++ b/src/VBox/Main/idl/midl.xsl @@ -5,7 +5,7 @@ * A template to generate a MS IDL compatible interface definition file * from the generic interface definition expressed in XML. - Copyright (C) 2006-2012 Oracle Corporation + Copyright (C) 2006-2014 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; @@ -206,7 +206,6 @@ <xsl:text> : </xsl:text> <xsl:choose> <xsl:when test="@extends='$unknown'">IDispatch</xsl:when> - <xsl:when test="@extends='$dispatched'">IDispatch</xsl:when> <xsl:when test="@extends='$errorinfo'">IErrorInfo</xsl:when> <xsl:otherwise><xsl:value-of select="@extends"/></xsl:otherwise> </xsl:choose> diff --git a/src/VBox/Main/idl/typemap-shared.inc.xsl b/src/VBox/Main/idl/typemap-shared.inc.xsl new file mode 100644 index 00000000..845f8fad --- /dev/null +++ b/src/VBox/Main/idl/typemap-shared.inc.xsl @@ -0,0 +1,360 @@ +<!-- + typemap-shared.inc.xsl: + this gets included from other XSLT stylesheets including those + for the webservice, so we can share some definitions that must + be the same for all of them (like method prefixes/suffices). + + Copyright (C) 2006-2013 Oracle Corporation + + This file is part of VirtualBox Open Source Edition (OSE), as + available from http://www.virtualbox.org. This file is free software; + you can redistribute it and/or modify it under the terms of the GNU + General Public License (GPL) as published by the Free Software + Foundation, in version 2 as it comes in the "COPYING" file of the + VirtualBox OSE distribution. VirtualBox OSE is distributed in the + hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. +--> + + +<xsl:stylesheet + version="1.0" + targetNamespace="http://schemas.xmlsoap.org/wsdl/" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:xsd="http://www.w3.org/2001/XMLSchema" + xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" + xmlns:vbox="http://www.virtualbox.org/"> + +<xsl:variable name="G_xsltIncludeFilename" select="'typemap-shared.inc.xsl'" /> + +<xsl:variable name="G_lowerCase" select="'abcdefghijklmnopqrstuvwxyz'" /> +<xsl:variable name="G_upperCase" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'" /> + +<!-- target namespace; this must match the xmlns:vbox in stylesheet opening tags! --> +<xsl:variable name="G_targetNamespace" + select='"http://www.virtualbox.org/"' /> +<xsl:variable name="G_targetNamespaceSeparator" + select='""' /> + +<!-- ENCODING SCHEME + + See: http://www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/ + + Essentially "document" style means that each SOAP message is a complete and + self-explanatory document that does not rely on outside information for + validation. + + By contrast, the (older) "RPC" style allows for much shorter SOAP messages + that do not contain validation info like all types that are used, but then + again, caller and receiver must have agreed on a valid format in some other way. + With RPC, WSDL typically looks like this: + + <message name="myMethodRequest"> + <part name="x" type="xsd:int"/> + <part name="y" type="xsd:float"/> + </message> + + This is why today "document" style is preferred. However, with document style, + one _cannot_ use "type" in <part> elements. Instead, one must use "element" + attributes that refer to <element> items in the type section. Like this: + + <types> + <schema> + <element name="xElement" type="xsd:int"/> + <element name="yElement" type="xsd:float"/> + </schema> + </types> + + <message name="myMethodRequest"> + <part name="x" element="xElement"/> + <part name="y" element="yElement"/> + </message> + + The "encoded" and "literal" sub-styles then only determine whether the + individual types in the soap messages carry additional information in + attributes. "Encoded" was only used with RPC styles, really, and even that + is not widely supported any more. + +--> +<!-- These are the settings: all the other XSLTs react on this and are supposed + to be able to generate both valid RPC and document-style code. The only + allowed values are 'rpc' or 'document'. --> +<xsl:variable name="G_basefmt" + select='"document"' /> +<xsl:variable name="G_parmfmt" + select='"literal"' /> +<!-- <xsl:variable name="G_basefmt" + select='"rpc"' /> +<xsl:variable name="G_parmfmt" + select='"encoded"' /> --> + +<!-- with document style, this is how we name the request and return element structures --> +<xsl:variable name="G_requestElementVarName" + select='"req"' /> +<xsl:variable name="G_responseElementVarName" + select='"resp"' /> +<!-- this is how we name the result parameter in messages --> +<xsl:variable name="G_result" + select='"returnval"' /> + +<!-- we represent interface attributes by creating "get" and "set" methods; these + are the prefixes we use for that --> +<xsl:variable name="G_attributeGetPrefix" + select='"get"' /> +<xsl:variable name="G_attributeSetPrefix" + select='"set"' /> +<!-- separator between class name and method/attribute name; would be "::" in C++ + but i'm unsure whether WSDL appreciates that (WSDL only) --> +<xsl:variable name="G_classSeparator" + select='"_"' /> +<!-- for each interface method, we need to create both a "request" and a "response" + message; these are the suffixes we append to the method names for that --> +<xsl:variable name="G_methodRequest" + select='"RequestMsg"' /> +<xsl:variable name="G_methodResponse" + select='"ResultMsg"' /> +<!-- suffix for element declarations that describe request message parameters (WSDL only) --> +<xsl:variable name="G_requestMessageElementSuffix" + select='""' /> +<!-- suffix for element declarations that describe request message parameters (WSDL only) --> +<xsl:variable name="G_responseMessageElementSuffix" + select='"Response"' /> +<!-- suffix for portType names (WSDL only) --> +<xsl:variable name="G_portTypeSuffix" + select='"PortType"' /> +<!-- suffix for binding names (WSDL only) --> +<xsl:variable name="G_bindingSuffix" + select='"Binding"' /> +<!-- schema type to use for object references; while it is theoretically + possible to use a self-defined type (e.g. some vboxObjRef type that's + really an int), gSOAP gets a bit nasty and creates complicated structs + for function parameters when these types are used as output parameters. + So we just use "int" even though it's not as lucid. + One setting is for the WSDL emitter, one for the C++ emitter --> +<!-- +<xsl:variable name="G_typeObjectRef" + select='"xsd:unsignedLong"' /> +<xsl:variable name="G_typeObjectRef_gsoapH" + select='"ULONG64"' /> +<xsl:variable name="G_typeObjectRef_CPP" + select='"WSDLT_ID"' /> +--> +<xsl:variable name="G_typeObjectRef" + select='"xsd:string"' /> +<xsl:variable name="G_typeObjectRef_gsoapH" + select='"std::string"' /> +<xsl:variable name="G_typeObjectRef_CPP" + select='"std::string"' /> +<!-- and what to call first the object parameter --> +<xsl:variable name="G_nameObjectRef" + select='"_this"' /> +<!-- gSOAP encodes underscores with USCORE so this is used in our C++ code --> +<xsl:variable name="G_nameObjectRefEncoded" + select='"_USCOREthis"' /> + +<!-- type to represent enums within C++ COM callers --> +<xsl:variable name="G_funcPrefixInputEnumConverter" + select='"EnumSoap2Com_"' /> +<xsl:variable name="G_funcPrefixOutputEnumConverter" + select='"EnumCom2Soap_"' /> + +<!-- type to represent structs within C++ COM callers --> +<xsl:variable name="G_funcPrefixOutputStructConverter" + select='"StructCom2Soap_"' /> + +<xsl:variable name="G_aSharedTypes"> + <type idlname="octet" xmlname="unsignedByte" cname="unsigned char" gluename="BYTE" gluefmt="%RU8" javaname="byte" /> + <type idlname="boolean" xmlname="boolean" cname="bool" gluename="BOOL" gluefmt="%RTbool" javaname="Boolean" /> + <type idlname="short" xmlname="short" cname="short" gluename="SHORT" gluefmt="%RI16" javaname="Short" /> + <type idlname="unsigned short" xmlname="unsignedShort" cname="unsigned short" gluename="USHORT" gluefmt="%RU16" javaname="Integer" /> + <type idlname="long" xmlname="int" cname="int" gluename="LONG" gluefmt="%RI32" javaname="Integer" /> + <type idlname="unsigned long" xmlname="unsignedInt" cname="unsigned int" gluename="ULONG" gluefmt="%RU32" javaname="Long" /> + <type idlname="long long" xmlname="long" cname="LONG64" gluename="LONG64" gluefmt="%RI64" javaname="Long" /> + <type idlname="unsigned long long" xmlname="unsignedLong" cname="ULONG64" gluename="ULONG64" gluefmt="%RU64" javaname="BigInteger" /> + <type idlname="double" xmlname="double" cname="double" gluename="DOUBLE" gluefmt="%#RX64" javaname="Double" /> + <type idlname="float" xmlname="float" cname="float" gluename="FLOAT" gluefmt="%#RX32" javaname="Float" /> + <type idlname="wstring" xmlname="string" cname="std::string" gluename="BSTR" gluefmt="%ls" javaname="String" /> + <type idlname="uuid" xmlname="string" cname="std::string" gluename="BSTR" gluefmt="%ls" javaname="String" /> + <type idlname="result" xmlname="unsignedInt" cname="unsigned int" gluename="HRESULT" gluefmt="%Rhrc" javaname="Long" /> +</xsl:variable> + +<!-- + warning: + --> + +<xsl:template name="warning"> + <xsl:param name="msg" /> + + <xsl:message terminate="no"> + <xsl:value-of select="concat('[', $G_xsltFilename, '] Warning in ', $msg)" /> + </xsl:message> +</xsl:template> + +<!-- + fatalError: + --> + +<xsl:template name="fatalError"> + <xsl:param name="msg" /> + + <xsl:message terminate="yes"> + <xsl:value-of select="concat('[', $G_xsltFilename, '] Error in ', $msg)" /> + </xsl:message> +</xsl:template> + +<!-- + debugMsg + --> + +<xsl:template name="debugMsg"> + <xsl:param name="msg" /> + + <xsl:if test="$G_argDebug"> + <xsl:message terminate="no"> + <xsl:value-of select="concat('[', $G_xsltFilename, '] ', $msg)" /> + </xsl:message> + </xsl:if> +</xsl:template> + +<!-- + uncapitalize + --> + +<xsl:template name="uncapitalize"> + <xsl:param name="str" select="."/> + <xsl:value-of select=" + concat( + translate(substring($str,1,1),$G_upperCase,$G_lowerCase), + substring($str,2) + ) + "/> +</xsl:template> +<!-- + uncapitalize in the way JAX-WS understands, see #2910 + --> + +<xsl:template name="uncapitalize2"> + <xsl:param name="str" select="."/> + <xsl:variable name="strlen"> + <xsl:value-of select="string-length($str)"/> + </xsl:variable> + <xsl:choose> + <xsl:when test="$strlen>1"> + <xsl:choose> + <xsl:when test="contains($G_upperCase,substring($str,1,1)) + and + contains($G_upperCase,substring($str,2,1))"> + <xsl:variable name="cdr"> + <xsl:call-template name="uncapitalize2"> + <xsl:with-param name="str" select="substring($str,2)"/> + </xsl:call-template> + </xsl:variable> + <xsl:value-of select=" + concat( + translate(substring($str,1,1), + $G_upperCase, + $G_lowerCase), + $cdr + ) + "/> + </xsl:when> + <xsl:otherwise> + <!--<xsl:value-of select="concat(substring($str,1,1),$cdr)"/>--> + <xsl:value-of select="$str"/> + </xsl:otherwise> + </xsl:choose> + </xsl:when> + <xsl:when test="$strlen=1"> + <xsl:value-of select=" + translate($str, + $G_upperCase, + $G_lowerCase) + "/> + </xsl:when> + <xsl:otherwise> + </xsl:otherwise> + </xsl:choose> +</xsl:template> +<!-- + capitalize + --> + +<xsl:template name="capitalize"> + <xsl:param name="str" select="."/> + <xsl:value-of select=" + concat( + translate(substring($str,1,1),$G_lowerCase,$G_upperCase), + substring($str,2) + ) + "/> +</xsl:template> + +<!-- + makeGetterName: + --> +<xsl:template name="makeGetterName"> + <xsl:param name="attrname" /> + <xsl:variable name="capsname"><xsl:call-template name="capitalize"><xsl:with-param name="str" select="$attrname" /></xsl:call-template></xsl:variable> + <xsl:value-of select="concat($G_attributeGetPrefix, $capsname)" /> +</xsl:template> + +<!-- + makeSetterName: + --> +<xsl:template name="makeSetterName"> + <xsl:param name="attrname" /> + <xsl:variable name="capsname"><xsl:call-template name="capitalize"><xsl:with-param name="str" select="$attrname" /></xsl:call-template></xsl:variable> + <xsl:value-of select="concat($G_attributeSetPrefix, $capsname)" /> +</xsl:template> + +<!-- + makeJaxwsMethod: compose idevInterfaceMethod out of IDEVInterface::method + --> +<xsl:template name="makeJaxwsMethod"> + <xsl:param name="ifname" /> + <xsl:param name="methodname" /> + <xsl:variable name="uncapsif"><xsl:call-template name="uncapitalize2"><xsl:with-param name="str" select="$ifname" /></xsl:call-template></xsl:variable> + <xsl:variable name="capsmethod"><xsl:call-template name="capitalize"><xsl:with-param name="str" select="$methodname" /></xsl:call-template></xsl:variable> + <xsl:value-of select="concat($uncapsif, $capsmethod)" /> +</xsl:template> + + +<!-- + makeJaxwsMethod2: compose iInterfaceMethod out of IInterface::method + --> +<xsl:template name="makeJaxwsMethod2"> + <xsl:param name="ifname" /> + <xsl:param name="methodname" /> + <xsl:variable name="uncapsif"><xsl:call-template name="uncapitalize"><xsl:with-param name="str" select="$ifname" /></xsl:call-template></xsl:variable> + <xsl:variable name="capsmethod"><xsl:call-template name="capitalize"><xsl:with-param name="str" select="$methodname" /></xsl:call-template></xsl:variable> + <xsl:value-of select="concat($uncapsif, $capsmethod)" /> +</xsl:template> + +<!-- + emitNewline: + --> +<xsl:template name="emitNewline"> + <xsl:text> +</xsl:text> +</xsl:template> + +<!-- + emitNewlineIndent8: + --> +<xsl:template name="emitNewlineIndent8"> + <xsl:text> + </xsl:text> +</xsl:template> + +<!-- + escapeUnderscores + --> +<xsl:template name="escapeUnderscores"> + <xsl:param name="string" /> + <xsl:if test="contains($string, '_')"> + <xsl:value-of select="substring-before($string, '_')" />_USCORE<xsl:call-template name="escapeUnderscores"><xsl:with-param name="string"><xsl:value-of select="substring-after($string, '_')" /></xsl:with-param></xsl:call-template> + </xsl:if> + <xsl:if test="not(contains($string, '_'))"><xsl:value-of select="$string" /> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/src/VBox/Main/idl/xpidl.xsl b/src/VBox/Main/idl/xpidl.xsl index 18796ba6..8a8597b1 100644 --- a/src/VBox/Main/idl/xpidl.xsl +++ b/src/VBox/Main/idl/xpidl.xsl @@ -5,7 +5,7 @@ * A template to generate a XPCOM IDL compatible interface definition file * from the generic interface definition expressed in XML. - Copyright (C) 2006-2009 Oracle Corporation + Copyright (C) 2006-2014 Oracle Corporation This file is part of VirtualBox Open Source Edition (OSE), as available from http://www.virtualbox.org. This file is free software; @@ -102,19 +102,6 @@ #include "nsISupports.idl" #include "nsIException.idl" -%{C++ -/** - * For escaping compound expression so they don't cause trouble when -pedantic - * is used. - * @internal - */ -#if defined(__cplusplus) && defined(__GNUC__) -# define VBOX_GCC_EXTENSION __extension__ -#endif -#ifndef VBOX_GCC_EXTENSION -# define VBOX_GCC_EXTENSION -#endif -%} </xsl:text> <!-- native typedefs for the 'mod="ptr"' attribute --> <xsl:text> @@ -199,8 +186,16 @@ * libraries --> <xsl:template match="library"> - <!-- result codes --> <xsl:text>%{C++
</xsl:text> + <xsl:text>#ifndef VBOX_EXTERN_C
</xsl:text> + <xsl:text># ifdef __cplusplus
</xsl:text> + <xsl:text># define VBOX_EXTERN_C extern "C"
</xsl:text> + <xsl:text># else // !__cplusplus
</xsl:text> + <xsl:text># define VBOX_EXTERN_C extern
</xsl:text> + <xsl:text># endif // !__cplusplus
</xsl:text> + <xsl:text>#endif // !VBOX_EXTERN_C
</xsl:text> + <!-- result codes --> + <xsl:text>// result codes declared in API spec
</xsl:text> <xsl:for-each select="result"> <xsl:apply-templates select="."/> </xsl:for-each> @@ -248,7 +243,6 @@ <xsl:text> : </xsl:text> <xsl:choose> <xsl:when test="@extends='$unknown'">nsISupports</xsl:when> - <xsl:when test="@extends='$dispatched'">nsISupports</xsl:when> <xsl:when test="@extends='$errorinfo'">nsIException</xsl:when> <xsl:otherwise><xsl:value-of select="@extends"/></xsl:otherwise> </xsl:choose> @@ -289,8 +283,12 @@ <xsl:value-of select="@name"/> <xsl:text>_TO_BASE(base) COM_FORWARD_</xsl:text> <xsl:value-of select="@name"/> - <xsl:text>_TO (base::)
</xsl:text> + <xsl:text>_TO (base::)

</xsl:text> <!-- --> + <xsl:text>// for compatibility with Win32
</xsl:text> + <xsl:text>VBOX_EXTERN_C const nsID IID_</xsl:text> + <xsl:value-of select="@name"/> + <xsl:text>;
</xsl:text> <xsl:text>%}

</xsl:text> <!-- end --> </xsl:template> @@ -660,6 +658,11 @@ <xsl:template match="module/class"> <!-- class and contract id --> <xsl:text>%{C++
</xsl:text> + <xsl:text>// Definitions for module </xsl:text> + <xsl:value-of select="../@name"/> + <xsl:text>, class </xsl:text> + <xsl:value-of select="@name"/> + <xsl:text>:
</xsl:text> <xsl:text>#define NS_</xsl:text> <xsl:call-template name="uppercase"> <xsl:with-param name="str" select="@name"/> @@ -690,13 +693,9 @@ <xsl:text>;1"
</xsl:text> <!-- CLSID_xxx declarations for XPCOM, for compatibility with Win32 --> <xsl:text>// for compatibility with Win32
</xsl:text> - <xsl:text>#define CLSID_</xsl:text> + <xsl:text>VBOX_EXTERN_C const nsCID CLSID_</xsl:text> <xsl:value-of select="@name"/> - <xsl:text> VBOX_GCC_EXTENSION (nsCID) NS_</xsl:text> - <xsl:call-template name="uppercase"> - <xsl:with-param name="str" select="@name"/> - </xsl:call-template> - <xsl:text>_CID
</xsl:text> + <xsl:text>;
</xsl:text> <xsl:text>%}

</xsl:text> </xsl:template> diff --git a/src/VBox/Main/idl/xpidl_iid.xsl b/src/VBox/Main/idl/xpidl_iid.xsl new file mode 100644 index 00000000..1e216085 --- /dev/null +++ b/src/VBox/Main/idl/xpidl_iid.xsl @@ -0,0 +1,154 @@ +<?xml version="1.0"?> +<!-- $Id: xpidl_iid.xsl $ --> + +<!-- + * A template to generate a header file containing IIDs for XPCOM + * from the generic interface definition expressed in XML. + + Copyright (C) 2006-2014 Oracle Corporation + + This file is part of VirtualBox Open Source Edition (OSE), as + available from http://www.virtualbox.org. This file is free software; + you can redistribute it and/or modify it under the terms of the GNU + General Public License (GPL) as published by the Free Software + Foundation, in version 2 as it comes in the "COPYING" file of the + VirtualBox OSE distribution. VirtualBox OSE is distributed in the + hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. +--> + +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> +<xsl:output method="text"/> + +<xsl:strip-space elements="*"/> + +<!-- +// templates +///////////////////////////////////////////////////////////////////////////// +--> + + +<!-- + * not explicitly matched elements and attributes +--> +<xsl:template match="*"/> + + +<!-- + * header +--> +<xsl:template match="/idl"> + <xsl:text> +/* + * DO NOT EDIT! This is a generated file. + * + * XPCOM C definitions for VirtualBox Main API (IIDs for COM interfaces) + * generated from XIDL (XML interface definition). + * + * Source : src/VBox/Main/idl/VirtualBox.xidl + * Generator : src/VBox/Main/idl/xpidl_iid.xsl + */ + +#ifndef nsID_h__ +struct nsID +{ + unsigned int m0; + unsigned short m1; + unsigned short m2; + unsigned char m3[8]; +}; + +typedef struct nsID nsID; +typedef struct nsID nsIID; +typedef struct nsID nsCID; +#endif /* nsID_h__ */ + +#ifdef __cplusplus +extern "C" { +#endif + +</xsl:text> + <xsl:apply-templates/> + <xsl:text> + +#ifdef __cplusplus +} +#endif + +</xsl:text> +</xsl:template> + + +<!-- + * ignore all |if|s except those for XPIDL target +--> +<xsl:template match="if"> + <xsl:if test="@target='xpidl'"> + <xsl:apply-templates/> + </xsl:if> +</xsl:template> + + +<!-- + * libraries +--> +<xsl:template match="library"> + <xsl:apply-templates select="if | interface"/> + <xsl:apply-templates select="module"/> +</xsl:template> + + +<!-- + * interfaces +--> +<xsl:template match="interface"> + <xsl:text>const nsID IID_</xsl:text> + <xsl:value-of select="@name"/> + <xsl:text> = {
</xsl:text> + <xsl:text> 0x</xsl:text><xsl:value-of select="substring(@uuid,1,8)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,10,4)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,15,4)"/> + <xsl:text>, \
 </xsl:text> + <xsl:text>{ 0x</xsl:text><xsl:value-of select="substring(@uuid,20,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,22,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,25,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,27,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,29,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,31,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,33,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,35,2)"/> + <xsl:text> } \
};

</xsl:text> +</xsl:template> + + +<!-- + * modules +--> +<xsl:template match="module"> + <xsl:apply-templates select="class"/> +</xsl:template> + + +<!-- + * co-classes +--> +<xsl:template match="module/class"> + <xsl:text>const nsCID CLSID_</xsl:text> + <xsl:value-of select="@name"/> + <xsl:text> = {
</xsl:text> + <xsl:text> 0x</xsl:text><xsl:value-of select="substring(@uuid,1,8)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,10,4)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,15,4)"/> + <xsl:text>, \
 </xsl:text> + <xsl:text>{ 0x</xsl:text><xsl:value-of select="substring(@uuid,20,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,22,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,25,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,27,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,29,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,31,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,33,2)"/> + <xsl:text>, 0x</xsl:text><xsl:value-of select="substring(@uuid,35,2)"/> + <xsl:text> } \
};

</xsl:text> +</xsl:template> + +</xsl:stylesheet> + |