Changeset 7283 in vbox for trunk/src/VBox

Timestamp:

Mar 4, 2008 8:45:05 PM (17 years ago)

Author:

vboxsync

Message:

Main: improve session documentation

File:

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

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

@@ -927 +927 @@
     </attribute>
 
-        <attribute name="machines" type="IMachineCollection" readonly="yes">
+    <attribute name="machines" type="IMachineCollection" readonly="yes">
       <desc>
         Collection of machine objects registered within this VirtualBox
@@ -980 +980 @@
         Creates a new virtual machine.
 
+        The new machine will have "empty" default settings and will not
+        yet be registered. The typical sequence to create a virtual machine
+        is therefore something like this:
+
+        <ol>
+           <li>Call this method (IVirtualBox::createMachine) to have a new
+           machine created. The machine object returned is "mutable", i.e.
+           automatically locked for the current session, as if
+           <link to="#openSession" /> had been called on it.</li>
+
+           <li>Assign meaningful settings to the new machine by calling the
+           respective methods.</li>
+
+           <li>Call <link to="IMachine::saveSettings" /> to have the settings written
+           to the machine's XML settings file. The configuration of the newly
+           created machine will not be saved to disk (and the settings subfolder
+           and file, as described below, will not be created) until this method
+           is called.</li>
+
+           <li>Call <link to="#registerMachine" /> to have the
+           machine show up in the list of machines registered with VirtualBox.</li>
+        </ol>
+
         Every machine has a <i>settings file</i> that is used to store
         the machine configuration. This file is stored in the directory
-        called <i>machine settings subfolder</i>. Both the subfolder
-        and the settings file have the same name that corresponds to the
-        name of the virtual machine. You can specify where
-        to create the machine settings subfolder using the @a
+        called <i>machine settings subfolder</i>. Unless specified otherwise,
+        both the subfolder and the settings file will have a name that
+        corresponds to the name of the virtual machine. You can specify
+        where to create the machine settings subfolder using the @a
         baseFolder argument. The base folder can be absolute (full path)
         or relative to the <link to="IVirtualBox::homeFolder">
@@ -1001 +1024 @@
         not desired (i.e. a new UUID should be generated), pass just an
         empty or null UUID.
-
-        Note that the configuration of the newly created machine is not
-        saved to disk (and therefore no settings subfolder and file are
-        created) until <link to="IMachine::saveSettings()"/> is called.
 
         You should also specify a valid name for the machine.
@@ -1739 +1758 @@
         all VM settings, as well as to execute the VM in the process
         space of the session object. There can be only one direct
-        session open at a time for every virtual machine.
+        session open at a time for every virtual machine. In VirtualBox
+        terminology, the machine becomes "mutable" after a session has
+        been opened.
 
         Upon successful return, the session object can be used to
         get access to the machine and to the VM console.
+
+        Note that the "mutable" machine object, on which you may want
+        to invoke IMachine methods to change its settings, will be a
+        different object from the immutable IMachine objects returned
+        by various IVirtualBox methods. To obtain a mutable
+        IMachine object, upon which you can invoke settings methods,
+        use the "machine" attribute of the ISession object which represents
+        your open session.
+
+        In other words, to change settings on a machine, the following
+        sequence is typically performed:
+
+        <ol>
+        <li>Call this method (openSession) to have a machine locked for
+        the current session.</li>
+
+        <li>Obtain a mutable IMachine object from ISession::machine.</li>
+
+        <li>Change the settings of the machine.</li>
+
+        <li>Call IMachine::saveSettings.</li>
+
+        <li>Close the session by calling <link to="#close" />.</li>
+        </ol>
       </desc>
       <param name="session" type="ISession" dir="in">
@@ -9381 +9426 @@
       same virtual machine.
 
-      When using the COM API directly, an object of the Session class from the
-      VirtualBox type library needs to be created. This object will then act
-      as a local session object in further calls to open a session.
-
-      In the webservice, the session manager creates one session object during
-      <link to="IWebsessionManager::logon" /> automatically; a managed object
-      reference to that session object can be retrieved by calling
-      <link to="IWebsessionManager::getSessionObject" />.
-
+      How sessions objects are used depends on whether you use the Main API
+      via COM or via the web service:
+
+      <ul>
+      <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
+      a session.
+      </li>
+
+      <li>In the webservice, the session manager (IWebsessionManager) instead creates
+      one session object automatically when <link to="IWebsessionManager::logon" />
+      is called. A managed object reference to that session object can be retrieved by
+      calling <link to="IWebsessionManager::getSessionObject" />. This session object
+      reference can then be used to open sessions.
+      </li>
+      </ul>
+
+      Sessions are mainly used in two variations:
+
+      <ul>
+      <li>
       To start a virtual machine in a separate process, one would call
       <link to="IVirtualBox::openRemoteSession"/>, which requires a session
@@ -9396 +9455 @@
       execution or power it down) as well as be notified about machine
       execution state changes.
-
-      To alter machine settings, or to start machine execution within its own
-      process, one needs to open a direct session for the machine first by
-      calling <link to="IVirtualBox::openSession"/>. Once the direct session
-      is successfully opened within one process, no any other process may open
-      a direct session for the same machine as long as the successful direct
-      session remains open. This prevents the machine from being changed by
-      other processes while it is running or while the machine is being
-      configured.
+      </li>
+
+      <li>To alter machine settings, or to start machine execution within the
+      current process, one needs to open a direct session for the machine first by
+      calling <link to="IVirtualBox::openSession"/>. While a direct session
+      is open within one process, no any other process may open another direct
+      session for the same machine. This prevents the machine from being changed
+      by other processes while it is running or while the machine is being configured.
+      </li>
+      </ul>
 
       One also can attach to an existing direct session alreay opened by
@@ -9410 +9470 @@
       virtual machine such as the pause or the reset request). This is done by
       calling <link to="IVirtualBox::openExistingSession"/>.
-
-      In regular COM C++ client code, one can simply create a session object,
-      for example by calling <tt>createLocalObject().</tt>
 
       <note>