Changeset 8836 in vbox for trunk/src

Timestamp:

May 15, 2008 9:19:00 AM (17 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

30847

Message:

Main: API doc fixes

File:

• trunk/src/VBox/Main/idl/VirtualBox.xidl (modified) (5 diffs)

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -1875 +1875 @@
     <method name="openRemoteSession">
       <desc>
-        Opens a new remote session with the given virtual
-        machine.
+        Opens a new remote session with the given virtual machine.
 
         Opening a remote session causes the VirtualBox server to start a new
@@ -1884 +1883 @@
         session context, not all VM settings are available for modification.
 
-        This operation can take some time, so the progress object
-        is returned to let the caller be informed when the session is
-        actually open. Until then, the remote session object remains in
-        the closed state and accessing the machine or its console through
-        it is invalid.
+        This operation can take some time (a new VM is started in a new process,
+        for which memory and other resources need to be set up, which can take
+        a few seconds). Because of this, a progress object is returned to allow the
+        caller to wait for this asynchronous operation to be completed. Until then,
+        the remote session object remains in the closed state and accessing the
+        machine or its console through it is invalid. It is recommended to use
+        <link to="IProgress::waitForCompletion" /> or similar calls to wait for
+        completion.
 
         Currently supported session types (values of the @a type
@@ -4089 +4091 @@
         If the machine is in the <link to="MachineState::Saved"/> state,
         it will continue its execution the point where the state has
-        beem saved.
+        been saved.
+
+        <note>
+            Unless you are trying to write a new VirtualBox front-end that
+            performs direct machine execution (like the VirtualBox or VBoxSDL
+            front-ends), don't call <link to="IConsole::powerUp"/> in a direct
+            session opened by <link to="IVirtualBox::openSession"/> and use this
+            session only to change virtual machine settings. If you simply want to
+            start virtual machine execution using one of the existing front-ends
+            (for example the VirtualBox GUI or headless server), simply use
+            <link to="IVirtualBox::openRemoteSession"/>; these front-ends
+            will power up the machine automatically for you.
+        </note>
 
         <see>#saveState</see>
@@ -4134 +4148 @@
       <desc>
         Saves the current execution state of a running virtual machine
-        and stops its executiuon.
+        and stops its execution.
 
         After this operation completes, the machine will go to the
@@ -9764 +9778 @@
         Unless you are trying to write a new VirtualBox front-end that
         performs direct machine execution (like the VirtualBox or VBoxSDL
-        frontends), don't call <link to="IConsole::powerUp"/> in a direct
+        front-ends), don't call <link to="IConsole::powerUp"/> in a direct
         session opened by <link to="IVirtualBox::openSession"/> and use this
         session only to change virtual machine settings. If you simply want to
-        start virtual machine execution using one of the existing frontends
-        (for example the VirtualBox GUI frontend), use
-        <link to="IVirtualBox::openRemoteSession"/>. In the latter case, on
-        sucess, the machine will be powered up for you by the front-end so you
-        don't need to call <link to="IConsole::powerUp"/> too.
+        start virtual machine execution using one of the existing front-ends
+        (for example the VirtualBox GUI or headless server), simply use
+        <link to="IVirtualBox::openRemoteSession"/>; these front-ends
+        will power up the machine automatically for you.
       </note>
     </desc>