[vbox-dev] Updated French translation
Michael Thayer
michael.thayer at oracle.com
Mon Feb 24 08:05:05 GMT 2014
Hello Jean-Philippe,
On 24/02/14 01:11, MENGUAL Jean-Philippe wrote:
> I've not given any news for a while. But I go on following the workflow
> and here's a patch to update the French manual.
>
> http://manager.accelibreinfo.eu/patchvb.txt
Thank you, applied!
I am attaching a current difference between the trunk and the 4.3
manual, and additionally a difference between current 4.3 and the last
time you updated it. If you would like the difference in some other
form just tell me.
Regards,
Michael
--
ORACLE Deutschland B.V. & Co. KG Michael Thayer
Werkstrasse 24 VirtualBox engineering
71384 Weinstadt, Germany mailto:michael.thayer at oracle.com
Hauptverwaltung: Riesstr. 25, D-80992 München
Registergericht: Amtsgericht München, HRA 95603
Geschäftsführer: Jürgen Kunz
Komplementärin: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Handelsregister der Handelskammer Midden-Niederlande, Nr. 30143697
Geschäftsführer: Alexander van der Ven, Astrid Kepper, Val Maher
-------------- next part --------------
diff -dur doc/manual/en_US/user_AdvancedTopics.xml ../branches/VBox-4.3/doc/manual/en_US/user_AdvancedTopics.xml
--- doc/manual/en_US/user_AdvancedTopics.xml 2014-01-29 10:32:20.130784654 +0100
+++ ../branches/VBox-4.3/doc/manual/en_US/user_AdvancedTopics.xml 2014-02-13 12:11:40.592113480 +0100
@@ -943,7 +943,7 @@
</sect2>
<sect2>
- <title>Linux and Solaris hosts</title>
+ <title>Linux hosts</title>
<para>When the webcam is detached from the host the emulated webcam device is
automatically detached from the guest only if the webcam is streaming video.
@@ -2138,355 +2138,6 @@
the default behavior, use</para>
<screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
- <para>You can also disable (i.e. blacklist) certain menu actions of certain
- menus. Use the following command to disable certain actions of the
- <emphasis>Application</emphasis> menu (only available on Mac OS X hosts):</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords:</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>About</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>About</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeMenus</screen>
-
- <para>Use the following command to disable certain actions of the <emphasis>Machine</emphasis>
- menu:</para>
-
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords:</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>SettingsDialog</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Settings</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>TakeSnapshot</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Take Snapshot</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>TakeScreenshot</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Take Screenshot</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>InformationDialog</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Session Information</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>MouseIntegration</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Disable Mouse Integration</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>TypeCAD</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Insert Ctrl+Alt+Del</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>TypeCABS</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Insert Ctrl+Alt+Backspace</emphasis> menu item in
- this menu (available on X11 hosts only).</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Pause</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Pause</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Reset</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Reset</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>SaveState</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Save the machine state</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Shutdown</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>ACPI Shutdown</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>PowerOff</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Power Off the machine</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeApplicationMenuActions</screen>
-
- <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
- menu:</para>
-
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords:</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Fullscreen</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Switch to Fullscreen</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Seamless</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Switch to Seamless Mode</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Scale</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Switch to Scaled Mode</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>GuestAutoresize</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Auto-resize Guest Display</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>AdjustWindow</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Adjust Window Size</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Multiscreen</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Multiscreen</emphasis> menu item in this menu (only visible in fullscreen/seamless mode).</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeViewMenuActions</screen>
-
- <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
- menu:</para>
-
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords to disable actions in the <emphasis>Devices</emphasis> menu:</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>OpticalDevices</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>CD/DVD Devices</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>FloppyDevices</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>FLoppy Devices</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>USBDevices</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>USB Devices</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>SharedClipboard</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Shared Clipboard</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>DragAndDrop</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Drag'n'Drop</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>NetworkSettings</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Network Settings...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>SharedFoldersSettings</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Shared Folders Settings...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>VRDEServer</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Remove Display</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>InstallGuestTools</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Insert Guest Additions CD imnage...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDevicesMenuActions</screen>
-
- <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
- menu:</para>
-
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords to disable actions in the <emphasis>Debug</emphasis> menu (normally completely disabled):</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Statistics</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Statistics...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>CommandLine</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Command Line...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Logging</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Logging...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>LogDialog</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Show Log...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeDebuggerMenuActions</screen>
-
- <para>Use the following command to disable certain actions of the <emphasis>View</emphasis>
- menu:</para>
-
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions OPTION[,OPTION...]</screen>
-
- <para>where <computeroutput>OPTION</computeroutput> is one of the
- following keywords to disable actions in the <emphasis>Help</emphasis> menu (normally completely disabled):</para><glosslist>
- <glossentry>
- <glossterm><computeroutput>All</computeroutput></glossterm>
- <glossdef>
- <para>Don't show any menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Contents</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>WebSite</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>VirtualBox Web Site...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>ResetWarnings</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Reset All Warnings</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>NetworkAccessManager</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Network Operations Manager</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>About</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>About</emphasis> menu item in this menu (only on non Mac OS X hosts).</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Contents</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm><computeroutput>Contents</computeroutput></glossterm>
- <glossdef>
- <para>Don't show the <emphasis>Contents...</emphasis> menu item in this menu.</para>
- </glossdef>
- </glossentry>
- </glosslist>
-
- <para>This is a per-VM setting. Any combination of the above is allowed. To restore
- the default behavior, use</para>
- <screen>VBoxManage setextradata "VM name" GUI/RestrictedRuntimeHelpMenuActions</screen>
-
</sect2>
<sect2>
@@ -3435,4 +3086,36 @@
</sect1>
+ <sect1 id="sse412passthrough">
+ <title>Experimental support for passing through SSE4.1 / SSE4.2 instructions</title>
+ <para>
+ To provide SSE 4.1 / SSE 4.2 support to guests, the host CPU has to
+ implement these instruction sets. Starting with VirtualBox 4.3.8 it is
+ possible to enable these instructions for certain guests using the
+ following commands:</para><screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.1 1
+VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.2 1</screen>
+ <para>
+ These are a per-VM settings and they are turned off by default.
+ </para>
+ </sect1>
+
+ <sect1 id="hidledssync">
+ <title>Support for keyboard indicators synchronization</title>
+
+ <para>
+ This feature makes the host keyboard lights match those of the virtual machine's virtual
+ keyboard when the machine window is selected. It is currently implemented for Mac OS X and
+ Windows hosts and available as of releases 4.2.24 and 4.3.8. The feature can be enabled using
+ the following command:
+ </para>
+
+ <screen>VBoxManage setextradata "VM name" GUI/HidLedsSync "1"</screen>
+
+ <para>
+ In order to disable it, use the same command but change "1" to "0", or use the VBoxManage
+ command to remove the extra data. This is a per-VM setting and it is disabled by default.
+ </para>
+
+ </sect1>
+
</chapter>
diff -dur doc/manual/en_US/user_GuestAdditions.xml ../branches/VBox-4.3/doc/manual/en_US/user_GuestAdditions.xml
--- doc/manual/en_US/user_GuestAdditions.xml 2014-01-07 12:07:50.564808472 +0100
+++ ../branches/VBox-4.3/doc/manual/en_US/user_GuestAdditions.xml 2013-11-04 13:18:04.702823462 +0100
@@ -1079,14 +1079,6 @@
<para>Currently only Linux and Solaris Guest Additions support
symlinks.</para>
</listitem>
-
- <listitem>
- <para>For security reasons the guest OS is not allowed to create
- symlinks by default. If you trust the guest OS to not abuse the
- functionality, you can enable creation of symlinks for "sharename"
- with:
- <screen>VBoxManage setextradata "VM name" VBoxInternal2/SharedFoldersEnableSymlinksCreate/sharename 1</screen></para>
- </listitem>
</orderedlist></para>
<sect2 id="sf_mount_manual">
diff -dur doc/manual/en_US/user_Installation.xml ../branches/VBox-4.3/doc/manual/en_US/user_Installation.xml
--- doc/manual/en_US/user_Installation.xml 2013-12-12 12:10:24.371210371 +0100
+++ ../branches/VBox-4.3/doc/manual/en_US/user_Installation.xml 2013-10-16 10:44:59.299988346 +0200
@@ -825,6 +825,11 @@
<sect2 id="solaris-zones">
<title>Configuring a zone for running VirtualBox</title>
+ <para>Starting with VirtualBox 1.6 it is possible to run VirtualBox from
+ within Solaris zones. For an introduction of Solaris zones, please refer
+ to <ulink
+ url="http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp">http://www.sun.com/bigadmin/features/articles/solaris_zones.jsp</ulink>.</para>
+
<para>Assuming that VirtualBox has already been installed into your
zone, you need to give the zone access to VirtualBox's device node. This
is done by performing the following steps. Start a root terminal and
@@ -832,9 +837,6 @@
<screen>zonecfg -z vboxzone</screen>
- <para>Replace "vboxzone" with the name of the zone in which you intend
- to run VirtualBox.</para>
-
<para>Inside the <computeroutput>zonecfg</computeroutput> prompt add the
<computeroutput>device</computeroutput> resource and
<computeroutput>match</computeroutput> properties to the zone. Here's
@@ -843,18 +845,19 @@
<screen>zonecfg:vboxzone>add device
zonecfg:vboxzone:device>set match=/dev/vboxdrv
zonecfg:vboxzone:device>end
-zonecfg:vboxzone>add device
-zonecfg:vboxzone:device>set match=/dev/vboxdrvu
-zonecfg:vboxzone:device>end
+zonecfg:vboxzone>verify
zonecfg:vboxzone>exit</screen>
- <para>If you are running VirtualBox 2.2.0 or above on Solaris 11 or
- above, you may add a device for <computeroutput>/dev/vboxusbmon</computeroutput>
- too, similar to what was shown above. This does not apply to Solaris 10
- hosts due to lack of USB support.</para>
-
- <para>Next reboot the zone using <computeroutput>zoneadm</computeroutput>
- and you should be able to run VirtualBox from within the configured zone.</para>
+ <para>If you are running VirtualBox 2.2.0 or above on Solaris 11 or
+ Nevada hosts, you should add a device for
+ <computeroutput>/dev/vboxusbmon</computeroutput> too, similar to what
+ was shown above. This does not apply to Solaris 10 hosts due to lack of
+ USB support.</para>
+
+ <para>Replace "vboxzone" with the name of the zone in which you intend
+ to run VirtualBox. Next reboot the zone using
+ <computeroutput>zoneadm</computeroutput> and you should be able to run
+ VirtualBox from within the configured zone.</para>
</sect2>
</sect1>
</chapter>
diff -dur doc/manual/en_US/user_KnownIssues.xml ../branches/VBox-4.3/doc/manual/en_US/user_KnownIssues.xml
--- doc/manual/en_US/user_KnownIssues.xml 2013-12-09 15:57:57.356519634 +0100
+++ ../branches/VBox-4.3/doc/manual/en_US/user_KnownIssues.xml 2013-10-16 10:44:59.291988347 +0200
@@ -247,12 +247,6 @@
snv_124 or higher. Webcams and other isochronous devices are known
to have poor performance.</para>
</listitem>
-
- <listitem>
- <para>Host Webcam passthrough is restricted to 640x480 frames at
- 20 frames per second due to limitations in the Solaris V4L2 API.
- This may be addressed in a future Solaris release.</para>
- </listitem>
<listitem>
<para>No ACPI information (battery status, power source) is
Only in doc/manual/en_US/: UserManual.asciidoc
Only in doc/manual/en_US/: user_Networking.xml~
diff -dur doc/manual/en_US/user_VBoxManage.xml ../branches/VBox-4.3/doc/manual/en_US/user_VBoxManage.xml
--- doc/manual/en_US/user_VBoxManage.xml 2014-02-12 09:41:42.498391647 +0100
+++ ../branches/VBox-4.3/doc/manual/en_US/user_VBoxManage.xml 2014-02-13 12:11:40.588113479 +0100
@@ -1991,7 +1991,7 @@
[--add <ide/sata/scsi/floppy>]
[--controller <LsiLogic|LSILogicSAS|BusLogic|
IntelAhci|PIIX3|PIIX4|ICH6|I82078>]
- [--sataportcount <1-30>]
+ [--portcount <1-30>]
[--hostiocache on|off]
[--bootable on|off]
[--remove]</screen>
@@ -2032,7 +2032,7 @@
</glossentry>
<glossentry>
- <glossterm><computeroutput>--sataportcount</computeroutput></glossterm>
+ <glossterm><computeroutput>--portcount</computeroutput></glossterm>
<glossdef>
<para>This determines how many ports the SATA controller should
-------------- next part --------------
Index: doc/manual/en_US/user_VBoxManage.xml
===================================================================
--- doc/manual/en_US/user_VBoxManage.xml (revision 90995)
+++ doc/manual/en_US/user_VBoxManage.xml (working copy)
@@ -1230,7 +1230,7 @@
when the network type is NAT
(<computeroutput>keepnatmacs</computeroutput>). If you add
<computeroutput>keepdisknames</computeroutput> all new disk images
- are called like the original once, otherwise they are
+ are called like the original ones, otherwise they are
renamed.</para>
</listitem>
<listitem>
@@ -1252,7 +1252,7 @@
<listitem>
<para><computeroutput>--register</computeroutput>:
Automatically register the new clone in this VirtualBox
- installation. If you manually want register the new VM later, see
+ installation. If you manually want to register the new VM later, see
<xref linkend="vboxmanage-registervm" /> for instructions how to do
so.</para>
</listitem>
Index: doc/manual/en_US/user_AdvancedTopics.xml
===================================================================
--- doc/manual/en_US/user_AdvancedTopics.xml (revision 90995)
+++ doc/manual/en_US/user_AdvancedTopics.xml (working copy)
@@ -455,7 +455,7 @@
Ubuntu, or simply restart the guest.</para></note>
<note><para>vbox-greeter is independent of the graphical session chosen
- by the user (like Gnome, KDE, Unity etc). However it requires FLTK 1.3
+ by the user (like Gnome, KDE, Unity etc). However, it requires FLTK 1.3
for representing its own user interface.</para></note>
<para>There are numerous guest properties which can be used to further
@@ -908,7 +908,7 @@
<computeroutput>MaxPayloadTransferSize</computeroutput> How many bytes the emulated
webcam can send to the guest at a time. Default value is 3060 bytes, which is used by
some webcams. Higher values can slightly reduce CPU load, if the guest is able to use
- larger buffers. However a high <computeroutput>MaxPayloadTransferSize</computeroutput>
+ larger buffers. However, a high <computeroutput>MaxPayloadTransferSize</computeroutput>
might be not supported by some guests.
</listitem>
</itemizedlist>
@@ -3021,4 +3021,101 @@
<para>Storage attachments can be reconfigured while the VM is paused afterwards using:</para>
<screen>VBoxManage storageattach ...</screen>
</sect1>
+
+ <sect1 id="hostpowertweaks">
+ <title>Handling of host power management events</title>
+
+ <para>Some host power management events are handled by VirtualBox. The
+ actual behavior depends on the platform:</para>
+
+ <para>
+ <glosslist>
+ <glossentry>
+ <glossterm>Host Suspends</glossterm>
+ <glossdef>
+ <para>
+ This event is generated when the host is about to suspend, that is,
+ the host saves the state to some non-volatile storage and powers off.
+ </para>
+ <para>
+ This event is currently only handled on Windows hosts and Mac OS X hosts.
+ When this event is generated, VirtualBox will pause all running VMs.
+ </para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>Host Resumes</glossterm>
+ <glossdef>
+ <para>
+ This event is generated when the host woke up from the suspended
+ state.
+ </para>
+ <para>
+ This event is currently only handled on Windows hosts and Mac OS X hosts.
+ When this event is generated, VirtualBox will resume all VMs which
+ are where paused before.
+ </para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>Battery Low</glossterm>
+ <glossdef>
+ <para>
+ The battery level reached a critical level (usually less than 5
+ percent charged).
+ </para>
+ <para>
+ This event is currently only handled on Windows hosts and Mac OS X hosts.
+ When this event is generated, VirtualBox will save the state and
+ terminate all VMs in preperation of a potential host powerdown.
+ </para>
+ <para>The behavior can be configured. By executing the following command,
+ no VM is saved:</para>
+ <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
+ <para>This is a global setting as well as a per-VM setting. The per-VM
+ value has higher precedence than the global value. The following command
+ will save the state of all VMs but will not save the state of VM "foo":</para>
+ <screen>VBoxManage setextradata global "VBoxInternal2/SavestateOnBatteryLow" 1
+VBoxManage setextradata "foo" "VBoxInternal2/SavestateOnBatteryLow" 0</screen>
+ <para>The first line is actually not required as by default the savestate
+ action is performed.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+ </para>
+
+ </sect1>
+
+ <sect1 id="sse412passthrough">
+ <title>Experimental support for passing through SSE4.1 / SSE4.2 instructions</title>
+ <para>
+ To provide SSE 4.1 / SSE 4.2 support to guests, the host CPU has to
+ implement these instruction sets. Starting with VirtualBox 4.3.8 it is
+ possible to enable these instructions for certain guests using the
+ following commands:</para><screen>VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.1 1
+VBoxManage setextradata "VM name" VBoxInternal/CPUM/SSE4.2 1</screen>
+ <para>
+ These are a per-VM settings and they are turned off by default.
+ </para>
+ </sect1>
+
+ <sect1 id="hidledssync">
+ <title>Support for keyboard indicators synchronization</title>
+
+ <para>
+ This feature makes the host keyboard lights match those of the virtual machine's virtual
+ keyboard when the machine window is selected. It is currently implemented for Mac OS X and
+ Windows hosts and available as of releases 4.2.24 and 4.3.8. The feature can be enabled using
+ the following command:
+ </para>
+
+ <screen>VBoxManage setextradata "VM name" GUI/HidLedsSync "1"</screen>
+
+ <para>
+ In order to disable it, use the same command but change "1" to "0", or use the VBoxManage
+ command to remove the extra data. This is a per-VM setting and it is disabled by default.
+ </para>
+
+ </sect1>
+
</chapter>
Index: doc/manual/en_US/SDKRef.xml
===================================================================
--- doc/manual/en_US/SDKRef.xml (revision 90995)
+++ doc/manual/en_US/SDKRef.xml (working copy)
@@ -1718,167 +1718,211 @@
</sect2>
<sect2 id="cbinding">
- <title>C binding to XPCOM API</title>
+ <title>C binding to VirtualBox API</title>
- <note>
- <para>This section currently applies to Linux, Mac OS X and Solaris
- hosts only.</para>
- </note>
+ <para>The VirtualBox API originally is designed as object oriented,
+ using XPCOM or COM as the middleware, which translates natively to C++.
+ This means that in order to use it from C there needs to be some
+ helper code to bridge the language differences and reduce the
+ differences between platforms.</para>
- <para>Starting with version 2.2, VirtualBox offers a C binding for the
- XPCOM API.</para>
+ <sect3 id="capi_glue">
+ <title>Cross-platform C binding to VirtualBox API</title>
- <para>The C binding provides a layer enabling object creation, method
- invocation and attribute access from C.</para>
+ <para>Starting with version 4.3, VirtualBox offers a C binding
+ which allows using the same C client sources for all platforms,
+ covering Windows, Linux, Mac OS X and Solaris. It is the
+ preferred way to write API clients, even though the old style
+ is still available.</para>
+ </sect3>
+
<sect3 id="c-gettingstarted">
<title>Getting started</title>
- <para>The following sections describe how to use the C binding in a
- C program.</para>
+ <para>The following sections describe how to use the VirtualBox API
+ in a C program. The necessary files are included in the SDK, in the
+ directories <computeroutput>sdk/bindings/c/include</computeroutput>
+ and <computeroutput>sdk/bindings/c/glue</computeroutput>.</para>
- <para>As part of the SDK, a sample program is provided which
- demonstrates using the C binding to initialize XPCOM, get handles for
+ <para>As part of the SDK, a sample program
+ <computeroutput>tstCAPIGlue.c</computeroutput> is provided in the
+ directory <computeroutput>sdk/bindings/c/samples</computeroutput>
+ which demonstrates
+ using the C binding to initialize the API, get handles for
VirtualBox and Session objects, make calls to list and start virtual
machines, monitor events, and uninitialize resources when done. The
- program uses the VBoxGlue library to open the C binding layer during
- runtime.</para>
+ sample program is trying to illustrate all relevant concepts, so it
+ is a great source of detail information. Among many other generally
+ useful code sequences it contains a function which shows how to
+ retrieve error details in C code if they are available from the API
+ call.</para>
- <para>The sample program
- <computeroutput>tstXPCOMCGlue</computeroutput> is located in the bin
- directory and can be run without arguments. It lists registered
- machines on the host along with some additional information and ask
- for a machine to start. The source for this program is available in
- <computeroutput>sdk/bindings/xpcom/cbinding/samples/</computeroutput>
- directory. The source for the VBoxGlue library is available in the
- <computeroutput>sdk/bindings/xpcom/cbinding/</computeroutput>
- directory.</para>
+ <para>The sample program <computeroutput>tstCAPIGlue</computeroutput>
+ can be built using the provided <computeroutput>Makefile</computeroutput>
+ and can be run without arguments.</para>
+
+ <para>It uses the VBoxCAPIGlue library (source code is in directory
+ <computeroutput>sdk/bindings/c/glue</computeroutput>, to be used in
+ your API client code) to open the C binding layer during runtime,
+ which is preferred to other means as it isolates the code which
+ locates the necessary dynamic library, using a known working way
+ which works on all platforms. If you encounter problems with this
+ glue code in <computeroutput>VBoxCAPIGlue.c</computeroutput>, let the
+ VirtualBox developers know, rather than inventing incompatible
+ solutions.</para>
+
+ <para>The following sections document the important concepts needed
+ to correctly use the C binding, as it is vital for developing API
+ client code which manages memory correctly, updates the reference
+ counters correctly, avoiding crashes and memory leaks. Often API
+ clients need to handle events, so the C API specifics are also
+ described below.</para>
</sect3>
<sect3 id="c-initialization">
- <title>XPCOM initialization</title>
+ <title>VirtualBox C API initialization</title>
- <para>Just like in C++, XPCOM needs to be initialized before it can
- be used. The <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header
- provides the interface to the C binding. Here's how to initialize
- XPCOM:</para>
-
- <screen>#include "VBoxCAPI_v4_3.h"
+ <para>Just like in C++, the API and the underlying middleware needs
+ to be initialized before it can be used. The
+ <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header provides the
+ interface to the C binding, but you can alternatively and more
+ conveniently also include <computeroutput>VBoxCAPIGlue.h</computeroutput>,
+ as this avoids the VirtualBox version dependent header file name and
+ makes sure the global variable <code>g_pVBoxFuncs</code> contains a
+ pointer to the structure which contains the helper function pointers.
+ Here's how to initialize the C API:<screen>#include "VBoxCAPIGlue.h"
...
-PCVBOXXPCOM g_pVBoxFuncs = NULL;
-IVirtualBox *vbox = NULL;
-ISession *session = NULL;
+IVirtualBoxClient *vboxclient = NULL;
+IVirtualBox *vbox = NULL;
+ISession *session = NULL;
+HRESULT rc;
+ULONG revision;
/*
- * VBoxGetXPCOMCFunctions() is the only function exported by
- * VBoxXPCOMC.so and the only one needed to make virtualbox
- * work with C. This functions gives you the pointer to the
- * function table (g_pVBoxFuncs).
+ * VBoxCGlueInit() loads the necessary dynamic library, handles errors
+ * (producing an error message hinting what went wrong) and gives you
+ * the pointer to the function table (g_pVBoxFuncs).
*
* Once you get the function table, then how and which functions
* to use is explained below.
*
- * g_pVBoxFuncs->pfnComInitialize does all the necessary startup
- * action and provides us with pointers to vbox and session handles.
- * It should be matched by a call to g_pVBoxFuncs->pfnComUninitialize()
+ * g_pVBoxFuncs->pfnClientInitialize does all the necessary startup
+ * action and provides us with pointers to an IVirtualBoxClient instance.
+ * It should be matched by a call to g_pVBoxFuncs->pfnClientUninitialize()
* when done.
*/
-g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION);
-g_pVBoxFuncs->pfnComInitialize(IVIRTUALBOX_IID_STR, &vbox,
- ISESSION_IID_STR, &session);</screen>
+if (VBoxCGlueInit())
+{
+ fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n",
+ argv[0], g_szVBoxErrMsg);
+ return EXIT_FAILURE;
+}
+
+g_pVBoxFuncs->pfnClientInitialize(NULL, &vboxclient);
+if (!vboxclient)
+{
+ fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n",
+ argv[0]);
+ return EXIT_FAILURE;
+}</screen></para>
- <para>If either <computeroutput>vbox</computeroutput> or
- <computeroutput>session</computeroutput> is still
- <computeroutput>NULL</computeroutput>, initialization failed and the
- XPCOM API cannot be used.</para>
+ <para>If <computeroutput>vboxclient</computeroutput> is still
+ <computeroutput>NULL</computeroutput> this means the initializationi
+ failed and the VirtualBox C API cannot be used.</para>
- <para>There is now also a way to use the
- <xref linkend="IVirtualBoxClient" xreflabel="IVirtualBoxClient" />
- helper interface, which in comparison to the original (and still
- available) initialization method above simplifies creating multiple
- sessions, and also allows handling termination and crashes of the API
- server (VBoxSVC) in a graceful way. See the sample program how this
- is used.</para>
+ <para>It is possible to write C applications using multiple threads
+ which all use the VirtualBox API, as long as you're initializing
+ the C API in each thread which your application creates. This is done
+ with <code>g_pVBoxFuncs->pfnClientThreadInitialize()</code> and
+ likewise before the thread is terminated the API must be
+ uninitialized with
+ <code>g_pVBoxFuncs->pfnClientThreadUninitialize()</code>. You don't
+ have to use these functions in worker threads created by COM/XPCOM
+ (which you might observe if your code uses active event handling),
+ everything is initialized correctly already. On Windows the C
+ bindings create a marshaller which supports a wide range of COM
+ threading models, from STA to MTA, so you don't have to worry about
+ these details unless you plan to use active event handlers. See
+ the sample code how to get this to work reliably (in other words
+ think twice if passive event handling isn't the better solution after
+ you looked at the sample code).</para>
</sect3>
<sect3 id="c-invocation">
- <title>XPCOM method invocation</title>
+ <title>C API attribute and method invocation</title>
<para>Method invocation is straightforward. It looks pretty much
- like the C++ way, augmented with an extra indirection due to
- accessing the vtable and passing a pointer to the object as the
- first argument to serve as the <computeroutput>this</computeroutput>
- pointer.</para>
+ like the C++ way, by using a macro which internally accesses the
+ vtable, and additionally needs to be passed a pointer to the objecti
+ as the first argument to serve as the
+ <computeroutput>this</computeroutput> pointer.</para>
<para>Using the C binding, all method invocations return a numeric
- result code.</para>
+ result code of type <code>HRESULT</code> (with a few exceptions
+ which normally are not relevant).</para>
<para>If an interface is specified as returning an object, a pointer
to a pointer to the appropriate object must be passed as the last
argument. The method will then store an object pointer in that
location.</para>
- <para>In other words, to call an object's method what you need
- is</para>
+ <para>Likewise, attributes (properties) can be queried or set using
+ method invocations, using specially named methods. For each
+ attribute there exists a getter method, the name of which is composed
+ of <computeroutput>get_</computeroutput> followed by the capitalized
+ attribute name. Unless the attribute is read-only, an analogous
+ <computeroutput>set_</computeroutput> method exists. Let's apply
+ these rules to get the <computeroutput>IVirtualBox</computeroutput>
+ reference, an <computeroutput>ISession</computeroutput> instance
+ reference and read the <xref linkend="IVirtualBox__revision"
+ xreflabel="IVirtualBox::revision" /> attribute:<screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &vbox);
+if (FAILED(rc) || !vbox)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc);
+ return EXIT_FAILURE;
+}
+rc = IVirtualBoxClient_get_Session(vboxclient, &session);
+if (FAILED(rc) || !session)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc);
+ return EXIT_FAILURE;
+}
- <screen>IObject *object;
-nsresult rc;
-...
-/*
- * Calling void IObject::method(arg, ...)
- */
-rc = object->vtbl->Method(object, arg, ...);
+rc = IVirtualBox_get_Revision(vbox, &revision);
+if (SUCCEEDED(rc))
+{
+ printf("Revision: %u\n", revision);
+}</screen></para>
+ <para>The convenience macros for calling a method are named by
+ prepending the method name with the interface name (using
+ <code>_</code>as the separator).</para>
+
+ <para>So far only attribute getters were illustrated, but generic
+ method calls are straightforward, too:<screen>IMachine *machine = NULL;
+BSTR vmname = ...;
...
-IFoo *foo;
/*
- * Calling IFoo IObject::method(arg, ...)
+ * Calling IMachine::findMachine(...)
*/
-rc = object->vtbl->Method(object, args, ..., &foo);</screen>
+rc = IVirtualBox_FindMachine(vbox, vmname, &machine);</screen></para>
- <para>As a real-world example of a method invocation, let's call
- <xref linkend="IMachine__launchVMProcess"
+ <para>As a more complicated example of a method invocation, let's
+ call <xref linkend="IMachine__launchVMProcess"
xreflabel="IMachine::launchVMProcess" /> which returns an
IProgress object. Note again that the method name is
- capitalized.</para>
-
- <screen>IProgress *progress;
+ capitalized:<screen>IProgress *progress;
...
-rc = vbox->vtbl->LaunchVMProcess(
+rc = IMachine_LaunchVMProcess(
machine, /* this */
session, /* arg 1 */
sessionType, /* arg 2 */
env, /* arg 3 */
&progress /* Out */
-);</screen>
- </sect3>
+);</screen></para>
- <sect3 id="c-attributes">
- <title>XPCOM attribute access</title>
-
- <para>A construct similar to calling non-void methods is used to
- access object attributes. For each attribute there exists a getter
- method, the name of which is composed of
- <computeroutput>Get</computeroutput> followed by the capitalized
- attribute name. Unless the attribute is read-only, an analogous
- <computeroutput>Set</computeroutput> method exists. Let's apply
- these rules to read the <xref linkend="IVirtualBox__revision"
- xreflabel="IVirtualBox::revision" /> attribute.</para>
-
- <para>Using the <computeroutput>IVirtualBox</computeroutput> handle
- <computeroutput>vbox</computeroutput> obtained above, calling its
- <computeroutput>GetRevision</computeroutput> method looks like
- this:</para>
-
- <screen>PRUint32 rev;
-
-rc = vbox->vtbl->GetRevision(vbox, &rev);
-if (NS_SUCCEEDED(rc))
-{
- printf("Revision: %u\n", (unsigned)rev);
-}</screen>
-
<para>All objects with their methods and attributes are documented
in <xref linkend="sdkref_classes" />.</para>
</sect3>
@@ -1889,63 +1933,173 @@
<para>When dealing with strings you have to be aware of a string's
encoding and ownership.</para>
- <para>Internally, XPCOM uses UTF-16 encoded strings. A set of
+ <para>Internally, the API uses UTF-16 encoded strings. A set of
conversion functions is provided to convert other encodings to and
from UTF-16. The type of a UTF-16 character is
- <computeroutput>PRUnichar</computeroutput>. Strings of UTF-16
- characters are arrays of that type. Most string handling functions
- take pointers to that type. Prototypes for the following conversion
- functions are declared in
- <computeroutput>VBoxCAPI_v4_3.h</computeroutput>.</para>
+ <computeroutput>BSTR</computeroutput> (or its constant counterpart
+ <computeroutput>CBSTR</computeroutput>), which is an array type,
+ represented by a pointer to the start of the zero-terminated string.
+ There are functions for converting between UTF-8 and UTF-16 strings
+ available through <code>g_pVBoxFuncs</code>:<screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString);
+int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString);</screen></para>
- <sect4>
- <title>Conversion of UTF-16 to and from UTF-8</title>
+ <para>The ownership of a string determines who is responsible for
+ releasing resources associated with the string. Whenever the API
+ creates a string (essentially for output parameters), ownership is
+ transferred to the caller. To avoid resource leaks, the caller
+ should release resources once the string is no longer needed.
+ There are plenty of examples in the sample code.</para>
+ </sect3>
- <screen>int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
-int (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);</screen>
- </sect4>
+ <sect3 id="c-safearray">
+ <title>Array handling</title>
- <sect4>
- <title>Ownership</title>
+ <para>Arrays are handled somewhat similarly to strings, with the
+ additional information of the number of elements in the array. The
+ exact details of string passing depends on the platform middleware
+ (COM/XPCOM), and therefore the C binding offers helper functions to
+ gloss over these differences.</para>
- <para>The ownership of a string determines who is responsible for
- releasing resources associated with the string. Whenever XPCOM
- creates a string, ownership is transferred to the caller. To avoid
- resource leaks, the caller should release resources once the
- string is no longer needed.</para>
- </sect4>
+ <para>Passing arrays as input parameters to API methods is usually
+ done by the following sequence, calling a hypothetical
+ <code>IArrayDemo_PassArray</code> API method:<screen>static const ULONG aElements[] = { 1, 2, 3, 4 };
+ULONG cElements = sizeof(aElements) / sizeof(aElements[0]);
+SAFEARRAY *psa = NULL;
+psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_I4, 0, cElements);
+g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, aElements, sizeof(aElements));
+IArrayDemo_PassArray(pThis, ComSafeArrayAsInParam(psa));
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para>
+
+ <para>Likewise, getting arrays results from output parameters is done
+ using helper functions which manage memory allocations as part of
+ their other functionality:<screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
+ULONG *pData;
+ULONG cElements;
+IArrayDemo_ReturnArray(pThis, ComSafeArrayAsOutParam(psa));
+g_pVBoxFuncs->pfnSafeArrayCopyOutParamHelper((void **)&pData, &cElements, VT_I4, psa);
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para>
+
+ <para>This covers the necessary functionality for all array element
+ types except interface references. These need special helpers to
+ manage the reference counting correctly. The following code snippet
+ gets the list of VMs, and passes the first IMachine reference to
+ another API function (assuming that there is at least one element
+ in the array, to simplify the example):<screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
+IMachine **machines = NULL;
+ULONG machineCnt = 0;
+ULONG i;
+IVirtualBox_get_Machines(virtualBox, ComSafeArrayAsOutIfaceParam(machinesSA, IMachine *));
+g_pVBoxFuncs->pfnSafeArrayCopyOutIfaceParamHelper((IUnknown ***)&machines, &machineCnt, machinesSA);
+g_pVBoxFuncs->pfnSafeArrayDestroy(machinesSA);
+/* Now "machines" contains the IMachine references, and machineCnt the
+ * number of elements in the array. */
+...
+SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_IUNKNOWN, 0, 1);
+g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, (void *)&machines[0], sizeof(machines[0]));
+IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...);
+...
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);
+for (i = 0; i < machineCnt; ++i)
+{
+ IMachine *machine = machines[i];
+ IMachine_Release(machine);
+}
+free(machines);</screen></para>
+
+ <para>Handling output parameters needs more special effort than
+ input parameters, thus only for the former there are special helpers,
+ and the latter is handled through the generic array support.</para>
</sect3>
+ <sect3 id="c-eventhandling">
+ <title>Event handling</title>
+
+ <para>The VirtualBox API offers two types of event handling, active
+ and passive, and consequently there is support for both with the
+ C API binding. Active event handling (based on asynchronous
+ callback invocation for event delivery) is more difficult, as it
+ requires the construction of valid C++ objects in C, which is
+ inherently platform and compiler dependent. Passive event handling
+ is much simpler, it relies on an event loop, fetching events and
+ triggering the necessary handlers explicitly in the API client code.
+ Both approaches depend on an event loop to make sure that events
+ get delivered in a timely manner, with differences what exactly needs
+ to be done.</para>
+
+ <para>The C API sample contains code for both event handling styles,
+ and one has to modify the appropriate <code>#define</code> to select
+ which style is actually used by the compiled program. It allows a
+ good comparison between the two variants, and the code sequences are
+ probably worth reusing without much change in other API clients
+ with only minor adaptions.</para>
+
+ <para>Active event handling needs to ensure that the following helper
+ function is called frequently enough in the primary thread:
+ <screen>g_pVBoxFuncs->pfnProcessEventQueue(cTimeoutMS);</screen></para>
+
+ <para>The actual event handler implementation is quite tedious, as
+ it has to implement a complete API interface. Especially on Windows
+ it is a lot of work to implement the complicated <code>IDispatch</code>
+ interface, requiring to load COM type information and using it
+ in the <code>IDispatch</code> method implementation. Overall this is
+ quite tedious compared to passive event handling.</para>
+
+ <para>Passive event handling uses a similar event loop structure,
+ which requires calling the following function in a loop, and
+ processing the returned event appropriately:
+ <screen>rc = IEventSource_GetEvent(pEventSource, pListener, cTimeoutMS, &pEvent);</screen></para>
+
+ <para>After processing the event it needs to be marked as processed
+ with the following method call:
+ <screen>rc = IEventSource_EventProcessed(pEventSource, pListener, pEvent);</screen></para>
+
+ <para>This is vital for vetoable events, as they would be stuck
+ otherwise, waiting whether the veto comes or not. It does not do any
+ harm for other event types, and in the end is cheaper than checking
+ if the event at hand is vetoable or not.</para>
+
+ <para>The general event handling concepts are described in the API
+ specification (see <xref linkend="events" />), including how to
+ aggregate multiple event sources for processing in one event loop.
+ As mentioned, the sample illustrates the practical aspects of how to
+ use both types of event handling, active and passive, from a C
+ application. Additional hints are in the comments documenting
+ the helper methods in <computeroutput>VBoxCAPI_v4_3.h</computeroutput>.
+ The code complexity of active event handling (and its inherenly
+ platform/compiler specific aspects) should be motivation to use
+ passive event handling whereever possible.</para>
+ </sect3>
+
<sect3 id="c-uninitialization">
- <title>XPCOM uninitialization</title>
+ <title>C API uninitialization</title>
<para>Uninitialization is performed by
- <computeroutput>g_pVBoxFuncs->pfnComUninitialize().</computeroutput>
+ <computeroutput>g_pVBoxFuncs->pfnClientUninitialize().</computeroutput>
If your program can exit from more than one place, it is a good idea
to install this function as an exit handler with Standard C's
<computeroutput>atexit()</computeroutput> just after calling
- <computeroutput>g_pVBoxFuncs->pfnComInitialize()</computeroutput>
+ <computeroutput>g_pVBoxFuncs->pfnClientInitialize()</computeroutput>
, e.g. <screen>#include <stdlib.h>
#include <stdio.h>
...
/*
- * Make sure g_pVBoxFuncs->pfnComUninitialize() is called at exit, no
+ * Make sure g_pVBoxFuncs->pfnClientUninitialize() is called at exit, no
* matter if we return from the initial call to main or call exit()
* somewhere else. Note that atexit registered functions are not
* called upon abnormal termination, i.e. when calling abort() or
- * signal(). Separate provisions must be taken for these cases.
+ * signal().
*/
-if (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) {
- fprintf(stderr, "failed to register g_pVBoxFuncs->pfnComUninitialize()\n");
+if (atexit(g_pVBoxFuncs->pfnClientUninitialize()) != 0) {
+ fprintf(stderr, "failed to register g_pVBoxFuncs->pfnClientUninitialize()\n");
exit(EXIT_FAILURE);
}</screen></para>
<para>Another idea would be to write your own <computeroutput>void
myexit(int status)</computeroutput> function, calling
- <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
+ <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput>
followed by the real <computeroutput>exit()</computeroutput>, and
use it instead of <computeroutput>exit()</computeroutput> throughout
your program and at the end of
@@ -1955,13 +2109,14 @@
user types CTRL-C sending SIGINT) you might want to install a signal
handler setting a flag noting that a signal was sent and then
calling
- <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
+ <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput>
later on, <emphasis>not</emphasis> from the handler itself.</para>
<para>That said, if a client program forgets to call
- <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
+ <computeroutput>g_pVBoxFuncs->pfnClientUninitialize()</computeroutput>
before it terminates, there is a mechanism in place which will
- eventually release references held by the client.</para>
+ eventually release references held by the client. On Windows it can
+ take quite a while, in the order of 6-7 minutes.</para>
</sect3>
<sect3 id="c-linking">
@@ -1969,28 +2124,102 @@
<para>A program using the C binding has to open the library during
runtime using the help of glue code provided and as shown in the
- example <computeroutput>tstXPCOMCGlue.c</computeroutput>.
- Compilation and linking can be achieved, e.g., with a makefile
- fragment similar to</para>
+ example <computeroutput>tstCAPIGlue.c</computeroutput>.
+ Compilation and linking can be achieved with a makefile fragment
+ similar to:<screen># Where is the SDK directory?
+PATH_SDK = ../../..
+CAPI_INC = -I$(PATH_SDK)/bindings/c/include
+ifeq ($(BUILD_PLATFORM),win)
+PLATFORM_INC = -I$(PATH_SDK)/bindings/mscom/include
+PLATFORM_LIB = $(PATH_SDK)/bindings/mscom/lib
+else
+PLATFORM_INC = -I$(PATH_SDK)/bindings/xpcom/include
+PLATFORM_LIB = $(PATH_SDK)/bindings/xpcom/lib
+endif
+GLUE_DIR = $(PATH_SDK)/bindings/c/glue
+GLUE_INC = -I$(GLUE_DIR)
- <screen># Where is the XPCOM include directory?
-INCS_XPCOM = -I../../include
-# Where is the glue code directory?
-GLUE_DIR = ..
-GLUE_INC = -I..
+# Compile Glue Library
+VBoxCAPIGlue.o: $(GLUE_DIR)/VBoxCAPIGlue.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $<
-#Compile Glue Library
-VBoxXPCOMCGlue.o: $(GLUE_DIR)/VBoxXPCOMCGlue.c
- $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
+# Compile interface ID list
+VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $<
-# Compile.
-program.o: program.c VBoxCAPI_v4_3.h
- $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
+# Compile program code
+program.o: program.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $<
-# Link.
-program: program.o VBoxXPCOMCGlue.o
- $(CC) -o $@ $^ -ldl</screen>
+# Link program.
+program: program.o VBoxCAPICGlue.o VirtualBox_i.o
+ $(CC) -o $@ $^ -ldl -lpthread</screen></para>
</sect3>
+
+ <sect3 id="capi_conversion">
+ <title>Conversion of code using legacy C binding</title>
+
+ <para>This section aims to make the task of converting code using
+ the legacy C binding to the new style a breeze, by pointing out some
+ key steps.</para>
+
+ <para>One necessary change is adjusting your Makefile to reflect the
+ different include paths. See above. There are now 3 relevant include
+ directories, and most of it is pointing to the C binding directory.
+ The XPCOM include directory is still relevant for platforms where
+ the XPCOM middleware is used, but most of the include files live
+ elsewhere now, so it's good to have it last. Additionally the
+ <computeroutput>VirtualBox_i.c</computeroutput> file needs to be
+ compiled and linked to the program, it contains the IIDs relevant
+ for the VirtualBox API, making sure they are not replicated endlessly
+ if the code refers to them frequently.</para>
+
+ <para>The C API client code should include <computeroutput>VBoxCAPIGlue.h</computeroutput>
+ instead of <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or
+ <computeroutput>VBoxCAPI_v4_3.h</computeroutput>, as this makes sure
+ the correct macros and internal translations are selected.</para>
+
+ <para>All API method calls (anything mentioning <code>vtbl</code>)
+ should be rewritten using the convenience macros for calling methods,
+ as these hide the internal details, are generally easier to use and
+ shorter to type. You should remove as many as possible
+ <code>(nsISupports **)</code> or similar typecasts, as the new style
+ should use the correct type in most places, increasing the type
+ safety in case of an error in the source code.</para>
+
+ <para>To gloss over the platform differences, API client code should
+ no longer rely on XPCOM specific interface names such as
+ <code>nsISupports</code>, <code>nsIException</code> and
+ <code>nsIEventQueue</code>, and replace them by the platform
+ independent interface names <code>IUnknown</code> and
+ <code>IErrorInfo</code> for the first two respectively. Event queue
+ handling should be replaced by using the platform independent way
+ described in <xref linkend="c-eventhandling" />.</para>
+
+ <para>Finally adjust the string and array handling to use the new
+ helpers, as these make sure the code works without changes with
+ both COM and XPCOM, which are significantly different in this area.
+ The code should be double checked if it uses the correct way to
+ manage memory, and is freeing it only after the last use.</para>
+ </sect3>
+
+ <sect3 id="xpcom_cbinding">
+ <title>Legacy C binding to VirtualBox API for XPCOM</title>
+
+ <note>
+ <para>This section applies to Linux, Mac OS X and Solaris
+ hosts only and describes deprecated use of the API from C.</para>
+ </note>
+
+ <para>Starting with version 2.2, VirtualBox offers a C binding for
+ its API which works only on platforms using XPCOM. Refer to the
+ old SDK documentation (included in the SDK packages for version 4.3.6
+ or earlier), it still applies unchanged. The fundamental concepts are
+ similar (but the syntactical details are quite different) to the
+ newer cross-platform C binding which should be used for all new code,
+ as the support for the old C binding will go away in a major release
+ after version 4.3.</para>
+ </sect3>
</sect2>
</sect1>
</chapter>
@@ -2138,7 +2367,7 @@
stopped, snapshotted or other things.</para>
</sect1>
- <sect1>
+ <sect1 id="events">
<title>VirtualBox events</title>
<para>In VirtualBox, "events" provide a uniform mechanism to register
More information about the vbox-dev
mailing list