Changeset 54266 in vbox for trunk/doc

Timestamp:

Feb 18, 2015 3:38:34 PM (10 years ago)

Author:

vboxsync

Message:

Main/webservice: change code to support multiple ISession instances per websession, lots of cleanup and wording changes
Main/idl,doc: matching updates

File:

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

trunk/doc/manual/en_US/SDKRef.xml

@@ -1217 +1217 @@
 
                 <para>Upon logon, the websession manager creates one instance
-                of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> and
-                another object of <xref linkend="ISession"
-                xreflabel="ISession" /> representing the web service session.
-                This can be retrieved using <xref
+                of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />,
+                which can be used for directly performing calls to its
+                methods, or used as a parameter for calling some methods of
+                <xref linkend="IWebsessionManager" xreflabel="IWebsessionManager" />.
+                Creating Main API session objects is performed using <xref
                 linkend="IWebsessionManager__getSessionObject"
                 xreflabel="IWebsessionManager::getSessionObject()" />.</para>
@@ -1226 +1227 @@
                 <para>(Technically, there is always only one <xref
                 linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which
-                is shared between all sessions and clients, as it is a COM
+                is shared between all websessions and clients, as it is a COM
                 singleton. However, each session receives its own managed
-                object reference to it. The <xref linkend="ISession"
-                xreflabel="ISession" /> object, however, is created and
-                destroyed for each session.)</para>
+                object reference to it.)</para>
               </listitem>
 
@@ -1528 +1527 @@
 name = "Linux"
 mach = vbox.findMachine(name)
-session = mgr.mgr.getSessionObject(vbox)
+session = mgr.getSessionObject(vbox)
 progress = mach.launchVMProcess(session, "gui", "")
 progress.waitForCompletion(-1)
@@ -1549 +1548 @@
         available virtual machines in case of XPCOM), and a mechanism of
         uniform session creation and closing
-        (<computeroutput>mgr.mgr.getSessionObject()</computeroutput>).</para>
+        (<computeroutput>mgr.getSessionObject()</computeroutput>).</para>
 
         <para>In case you want to use the glue layer with a different Python
@@ -2292 +2291 @@
       xreflabel="ISession" /> interface. Each process which talks to
       VirtualBox needs its own instance of ISession. In the web service, you
-      cannot create such an object, but
-      <computeroutput>vboxwebsrv</computeroutput> creates one for you when you
-      log on, which you can obtain by calling <xref
+      can request the creation of such an object by calling <xref
       linkend="IWebsessionManager__getSessionObject"
-      xreflabel="IWebsessionManager::getSessionObject()" />.</para>
+      xreflabel="IWebsessionManager::getSessionObject()" />. More complex
+      management tasks might need multiple instances of ISession, and each call
+      returns a new one.</para>
 
       <para>This session object must then be used like a mutex semaphore in
@@ -3908 +3907 @@
           </itemizedlist></para>
         </listitem>
+
+        <listitem>
+          <para>The method <xref linkend="IWebsessionManager__getSessionObject"
+          xreflabel="IWebsessionManager::getSessionObject()" /> now returns
+          a new <xref linkend="ISession" xreflabel="ISession" /> instance for
+          every invocation. This puts the behavior in line with other binding
+          styles, which never forced the equivalent of establishing another
+          connection and logging in again to get another instance.</para>
+        </listitem>
       </itemizedlist>
     </sect1>