Changeset 49525 in vbox for trunk/doc/manual/en_US

Timestamp:

Nov 18, 2013 12:25:40 PM (11 years ago)

Author:

vboxsync

Message:

manual/SDKRef: touch up the C binding documentation

File:

• trunk/doc/manual/en_US/SDKRef.xml (modified) (8 diffs)

trunk/doc/manual/en_US/SDKRef.xml

@@ -1722 +1722 @@
 
         <note>
-          <para>This section currently applies to Linux hosts only.</para>
+          <para>This section currently applies to Linux, Mac OS X and Solaris
+          hosts only.</para>
         </note>
 
@@ -1737 +1738 @@
           C program.</para>
 
-          <para>For Linux, a sample program is provided which demonstrates use
-          of the C binding to initialize XPCOM, get handles for VirtualBox and
-          Session objects, make calls to list and start virtual machines, and
-          uninitialize resources when done. The program uses the VBoxGlue
-          library to open the C binding layer during runtime.</para>
+          <para>As part of the SDK, a sample program is provided which
+          demonstrates using the C binding to initialize XPCOM, 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>
 
           <para>The sample program
@@ -1758 +1760 @@
 
           <para>Just like in C++, XPCOM needs to be initialized before it can
-          be used. The <computeroutput>VBoxCAPI_v2_5.h</computeroutput> header
+          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_v2_5.h"
+          <screen>#include "VBoxCAPI_v4_3.h"
 ...
 PCVBOXXPCOM g_pVBoxFuncs = NULL;
@@ -1784 +1786 @@
 
 g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION);
-g_pVBoxFuncs-&gt;pfnComInitialize(&amp;vbox, &amp;session);</screen>
+g_pVBoxFuncs-&gt;pfnComInitialize(IVIRTUALBOX_IID_STR, &amp;vbox,
+                               ISESSION_IID_STR, &amp;session);</screen>
 
           <para>If either <computeroutput>vbox</computeroutput> or
@@ -1790 +1793 @@
           <computeroutput>NULL</computeroutput>, initialization failed and the
           XPCOM 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>
         </sect3>
 
@@ -1886 +1897 @@
           take pointers to that type. Prototypes for the following conversion
           functions are declared in
-          <computeroutput>VBoxCAPI_v2_5.h</computeroutput>.</para>
+          <computeroutput>VBoxCAPI_v4_3.h</computeroutput>.</para>
 
           <sect4>
@@ -1946 +1957 @@
           calling
           <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize()</computeroutput>
-          later on (usually <emphasis>not</emphasis> from the handler itself
-          .)</para>
+          later on, <emphasis>not</emphasis> from the handler itself.</para>
 
           <para>That said, if a client program forgets to call
           <computeroutput>g_pVBoxFuncs-&gt;pfnComUninitialize()</computeroutput>
           before it terminates, there is a mechanism in place which will
-          eventually release references held by the client. You should not
-          rely on this, however.</para>
+          eventually release references held by the client.</para>
         </sect3>
 
@@ -1976 +1985 @@
 
 # Compile.
-program.o: program.c VBoxCAPI_v2_5.h
+program.o: program.c VBoxCAPI_v4_3.h
     $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $&lt;