Changeset 31070 in vbox

Timestamp:

Jul 23, 2010 4:00:09 PM (14 years ago)

Author:

vboxsync

Message:

Main: rename ISession::close() to ISession::unlockMachine(); API documentation

Location:

trunk/src/VBox

Files:

• Frontends/VBoxHeadless/VBoxHeadless.cpp (modified) (1 diff)
• Frontends/VBoxHeadless/testcase/tstHeadless.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageControlVM.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageGuestCtrl.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageGuestProp.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageInfo.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageMisc.cpp (modified) (8 diffs)
• Frontends/VBoxManage/VBoxManageModifyVM.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageSnapshot.cpp (modified) (1 diff)
• Frontends/VBoxManage/VBoxManageStorageController.cpp (modified) (3 diffs)
• Frontends/VBoxManage/VBoxManageUSB.cpp (modified) (1 diff)
• Frontends/VBoxSDL/VBoxSDL.cpp (modified) (1 diff)
• Frontends/VirtualBox/src/VBoxMediaManagerDlg.cpp (modified) (1 diff)
• Frontends/VirtualBox/src/runtime/UIMachine.cpp (modified) (1 diff)
• Frontends/VirtualBox/src/selector/UIVMPreviewWindow.cpp (modified) (2 diffs)
• Frontends/VirtualBox/src/selector/VBoxSelectorWnd.cpp (modified) (5 diffs)
• Frontends/VirtualBox/src/selector/VBoxSnapshotsWgt.cpp (modified) (3 diffs)
• Frontends/VirtualBox/src/wizards/newvm/UINewVMWzd.cpp (modified) (1 diff)
• Main/ApplianceImplImport.cpp (modified) (5 diffs)
• Main/MachineImpl.cpp (modified) (5 diffs)
• Main/SessionImpl.cpp (modified) (7 diffs)
• Main/cbinding/tstXPCOMCGlue.c (modified) (1 diff)
• Main/glue/glue-java.xsl (modified) (6 diffs)
• Main/idl/VirtualBox.xidl (modified) (8 diffs)
• Main/include/SessionImpl.h (modified) (3 diffs)
• Main/testcase/tstVBoxAPILinux.cpp (modified) (1 diff)
• Main/testcase/tstVBoxAPIWin.cpp (modified) (1 diff)

trunk/src/VBox/Frontends/VBoxHeadless/VBoxHeadless.cpp

@@ -1161 +1161 @@
          */
         Log(("VBoxHeadless: Closing the session...\n"));
-        session->Close();
+        session->UnlockMachine();
     }
 

trunk/src/VBox/Frontends/VBoxHeadless/testcase/tstHeadless.cpp

@@ -201 +201 @@
         }
 
-        RTPrintf ("Closing the session (may fail after power off)...\n");
-        CHECK_ERROR (session, Close());
+        RTPrintf("Closing the session (may fail after power off)...\n");
+        CHECK_ERROR(session, UnlockMachine());
     }
     while (0);

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

@@ -416 +416 @@
      * Aborted which may have unwanted side effects like killing the saved
      * state file (if the machine was in the Saved state before). */
-    session->Close();
+    session->UnlockMachine();
 
     EventQueue::getMainEventQueue()->processEventQueue(0);

trunk/src/VBox/Frontends/VBoxManage/VBoxManageControlVM.cpp

@@ -881 +881 @@
     } while (0);
 
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestCtrl.cpp

@@ -520 +520 @@
                 }
             }
-            a->session->Close();
+            a->session->UnlockMachine();
         } while (0);
     }

trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestProp.cpp

@@ -168 +168 @@
             CHECK_ERROR(machine, SaveSettings());
 
-        a->session->Close();
+        a->session->UnlockMachine();
     }
     return SUCCEEDED(rc) ? 0 : 1;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageInfo.cpp

@@ -2146 +2146 @@
 
         if (console)
-            a->session->Close();
+            a->session->UnlockMachine();
     }
 

trunk/src/VBox/Frontends/VBoxManage/VBoxManageMisc.cpp

@@ -393 +393 @@
 
     /* it's important to always close sessions */
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;
@@ -425 +425 @@
                 CHECK_ERROR_BREAK(console, ForgetSavedState(true));
             } while (0);
-            CHECK_ERROR_BREAK(a->session, Close());
+            CHECK_ERROR_BREAK(a->session, UnlockMachine());
         } while (0);
     }
@@ -459 +459 @@
                 CHECK_ERROR_BREAK(console, AdoptSavedState(Bstr(a->argv[1])));
             } while (0);
-            CHECK_ERROR_BREAK(a->session, Close());
+            CHECK_ERROR_BREAK(a->session, UnlockMachine());
         } while (0);
     }
@@ -735 +735 @@
                                                     fWritable, fAutoMount));
             if (console)
-                a->session->Close();
+                a->session->UnlockMachine();
         }
         else
@@ -751 +751 @@
                 CHECK_ERROR(machine, SaveSettings());
 
-            a->session->Close();
+            a->session->UnlockMachine();
         }
     }
@@ -800 +800 @@
 
             if (console)
-                a->session->Close();
+                a->session->UnlockMachine();
         }
         else
@@ -814 +814 @@
             /* commit and close the session */
             CHECK_ERROR(machine, SaveSettings());
-            a->session->Close();
+            a->session->UnlockMachine();
         }
     }
@@ -904 +904 @@
                 }
             }
-            a->session->Close();
+            a->session->UnlockMachine();
         }
     }

trunk/src/VBox/Frontends/VBoxManage/VBoxManageModifyVM.cpp

@@ -2048 +2048 @@
 
     /* it's important to always close sessions */
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageSnapshot.cpp

@@ -499 +499 @@
     } while (0);
 
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageStorageController.cpp

@@ -636 +636 @@
 leave:
     /* it's important to always close sessions */
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;
@@ -765 +765 @@
     {
         /* it's important to always close sessions */
-        a->session->Close();
+        a->session->UnlockMachine();
         errorSyntax(USAGE_STORAGECONTROLLER, "Storage controller name not specified\n");
         return 1;
@@ -954 +954 @@
 
     /* it's important to always close sessions */
-    a->session->Close();
+    a->session->UnlockMachine();
 
     return SUCCEEDED(rc) ? 0 : 1;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp

@@ -562 +562 @@
         }
         /* close the session */
-        a->session->Close();
+        a->session->UnlockMachine();
     }
 

trunk/src/VBox/Frontends/VBoxSDL/VBoxSDL.cpp

@@ -2747 +2747 @@
     if (sessionOpened)
     {
-        rc = session->Close();
+        rc = session->UnlockMachine();
         AssertComRC(rc);
     }

trunk/src/VBox/Frontends/VirtualBox/src/VBoxMediaManagerDlg.cpp

@@ -1263 +1263 @@
     /* If a new session was opened, we must close it */
     if (!session.isNull())
-        session.Close();
+        session.UnlockMachine();
 
     return success;

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIMachine.cpp

@@ -418 +418 @@
     delete m_pActionsPool;
     m_pActionsPool = 0;
-    m_session.Close();
+    m_session.UnlockMachine();
     m_session.detach();
     QApplication::quit();

trunk/src/VBox/Frontends/VirtualBox/src/selector/UIVMPreviewWindow.cpp

@@ -90 +90 @@
     /* Close any open session */
     if (m_session.GetState() == KSessionState_Locked)
-        m_session.Close();
+        m_session.UnlockMachine();
 }
 
@@ -363 +363 @@
     /* Close any open session */
     if (m_session.GetState() == KSessionState_Locked)
-        m_session.Close();
+        m_session.UnlockMachine();
     if (!m_machine.isNull())
     {

trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSelectorWnd.cpp

@@ -628 +628 @@
     mVMListView->setFocus();
 
-    session.Close();
+    session.UnlockMachine();
 }
 
@@ -672 +672 @@
             else
                 ok = true;
-            session.Close();
+            session.UnlockMachine();
         }
         else
@@ -771 +771 @@
         vboxProblem().cannotOpenSession(vbox, item->machine(), progress);
 
-    session.Close();
+    session.UnlockMachine();
 }
 
@@ -809 +809 @@
         vboxProblem().cannotDiscardSavedState (console);
 
-    session.Close();
+    session.UnlockMachine();
 }
 
@@ -841 +841 @@
     }
 
-    session.Close();
+    session.UnlockMachine();
 }
 

trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSnapshotsWgt.cpp

@@ -544 +544 @@
         vboxProblem().cannotRestoreSnapshot (progress, snapshot.GetName());
 
-    session.Close();
+    session.UnlockMachine();
 }
 
@@ -590 +590 @@
         vboxProblem().cannotDeleteSnapshot (console,  snapshot.GetName());
 
-    session.Close();
+    session.UnlockMachine();
 }
 
@@ -661 +661 @@
             vboxProblem().cannotTakeSnapshot (console);
 
-        session.Close();
+        session.UnlockMachine();
     }
 }

trunk/src/VBox/Frontends/VirtualBox/src/wizards/newvm/UINewVMWzd.cpp

@@ -777 +777 @@
             }
 
-            session.Close();
+            session.UnlockMachine();
         }
         if (!success)

trunk/src/VBox/Main/ApplianceImplImport.cpp

@@ -1243 +1243 @@
                     rc2 = sMachine->SaveSettings();
                 }
-                stack.pSession->Close();
+                stack.pSession->UnlockMachine();
             }
         }
@@ -1850 +1850 @@
 
             // only now that we're done with all disks, close the session
-            rc = stack.pSession->Close();
+            rc = stack.pSession->UnlockMachine();
             if (FAILED(rc)) DebugBreakThrow(rc);
             stack.fSessionOpen = false;
@@ -1857 +1857 @@
         {
             if (stack.fSessionOpen)
-                stack.pSession->Close();
+                stack.pSession->UnlockMachine();
 
             throw;
@@ -1942 +1942 @@
 
             // only now that we're done with all disks, close the session
-            rc = stack.pSession->Close();
+            rc = stack.pSession->UnlockMachine();
             if (FAILED(rc)) DebugBreakThrow(rc);
             stack.fSessionOpen = false;
@@ -1949 +1949 @@
         {
             if (stack.fSessionOpen)
-                stack.pSession->Close();
+                stack.pSession->UnlockMachine();
 
             throw;

trunk/src/VBox/Main/MachineImpl.cpp

@@ -2698 +2698 @@
                         tr("The given session is busy"));
 
-    /* get the IInternalSessionControl interface */
+    // get the client's IInternalSessionControl interface
     ComPtr<IInternalSessionControl> pSessionControl = aSession;
     ComAssertMsgRet(!!pSessionControl, ("No IInternalSessionControl interface"),
@@ -2727 +2727 @@
 
     // try again now
-    if (    mData->mSession.mState == SessionState_Locked
-         || mData->mSession.mState == SessionState_Unlocking
+    if (    (mData->mSession.mState == SessionState_Locked)         // machine is write-locked already (i.e. session machine exists)
+         && (lockType == LockType_Shared)                           // caller wants a shared link to the existing session that holds the write lock:
        )
     {
-        // If the machine is write-locked already (i.e. SessionMachine exists) and
-        // caller permits sharing, then try to do that now
-        if (    (mData->mSession.mState == SessionState_Locked)
-             && (lockType == LockType_Shared)
-           )
-        {
-            ComAssertRet(!mData->mSession.mDirectControl.isNull(), E_FAIL);
-
-            // copy member variables before leaving lock
-            ComPtr<IInternalSessionControl> pDirectControl = mData->mSession.mDirectControl;
-            ComObjPtr<SessionMachine> pSessionMachine = mData->mSession.mMachine;
-            AssertReturn(!pSessionMachine.isNull(), E_FAIL);
-
-            /*
-             *  Leave the lock before calling the client process. It's safe here
-             *  since the only thing to do after we get the lock again is to add
-             *  the remote control to the list (which doesn't directly influence
-             *  anything).
-             */
-            alock.leave();
-
-            // get the console from the direct session (this is a remote call)
-            ComPtr<IConsole> pConsole;
-            LogFlowThisFunc(("Calling GetRemoteConsole()...\n"));
-            rc = pDirectControl->GetRemoteConsole(pConsole.asOutParam());
-            LogFlowThisFunc(("GetRemoteConsole() returned %08X\n", rc));
-            if (FAILED(rc))
-                /* The failure may occur w/o any error info (from RPC), so provide one */
-                return setError(VBOX_E_VM_ERROR,
-                                tr("Failed to get a console object from the direct session (%Rrc)"), rc);
-
-            ComAssertRet(!pConsole.isNull(), E_FAIL);
-
-            /* attach the remote session to the machine */
-            LogFlowThisFunc(("Calling AssignRemoteMachine()...\n"));
-            rc = pSessionControl->AssignRemoteMachine(pSessionMachine, pConsole);
-            LogFlowThisFunc(("AssignRemoteMachine() returned %08X\n", rc));
-
-            /* The failure may occur w/o any error info (from RPC), so provide one */
-            if (FAILED(rc))
-                return setError(VBOX_E_VM_ERROR,
-                                tr("Failed to assign the machine to the session (%Rrc)"),
-                                rc);
-            alock.enter();
-
-            /* need to revalidate the state after entering the lock again */
-            if (mData->mSession.mState != SessionState_Locked)
-            {
-                pSessionControl->Uninitialize();
-                return setError(VBOX_E_INVALID_SESSION_STATE,
-                                tr("The machine '%ls' was unlocked unexpectedly while attempting to share its session"),
-                                mUserData->mName.raw());
-            }
-
-            // add the caller's control to the list
-            mData->mSession.mRemoteControls.push_back(pSessionControl);
-        }
-        else
-            // still unlocking, or caller has not permitted sharing:
-            return setError(VBOX_E_INVALID_OBJECT_STATE,
-                            tr("The machine '%ls' is already locked for a session (or being unlocked)"),
-                            mUserData->mName.raw());
+        // OK, share the session... we are now dealing with three processes:
+        // 1) VBoxSVC (where this code runs);
+        // 2) process C: the caller's client process (who wants a shared session);
+        // 3) process W: the process which already holds the write lock on the machine (write-locking session)
+
+        // copy pointers to W (the write-locking session) before leaving lock (these must not be NULL)
+        ComPtr<IInternalSessionControl> pSessionW = mData->mSession.mDirectControl;
+        ComAssertRet(!pSessionW.isNull(), E_FAIL);
+        ComObjPtr<SessionMachine> pSessionMachine = mData->mSession.mMachine;
+        AssertReturn(!pSessionMachine.isNull(), E_FAIL);
+
+        /*
+         *  Leave the lock before calling the client process. It's safe here
+         *  since the only thing to do after we get the lock again is to add
+         *  the remote control to the list (which doesn't directly influence
+         *  anything).
+         */
+        alock.leave();
+
+        // get the console of the session holding the write lock (this is a remote call)
+        ComPtr<IConsole> pConsoleW;
+        LogFlowThisFunc(("Calling GetRemoteConsole()...\n"));
+        rc = pSessionW->GetRemoteConsole(pConsoleW.asOutParam());
+        LogFlowThisFunc(("GetRemoteConsole() returned %08X\n", rc));
+        if (FAILED(rc))
+            // the failure may occur w/o any error info (from RPC), so provide one
+            return setError(VBOX_E_VM_ERROR,
+                            tr("Failed to get a console object from the direct session (%Rrc)"), rc);
+
+        ComAssertRet(!pConsoleW.isNull(), E_FAIL);
+
+        // share the session machine and W's console with the caller's session
+        LogFlowThisFunc(("Calling AssignRemoteMachine()...\n"));
+        rc = pSessionControl->AssignRemoteMachine(pSessionMachine, pConsoleW);
+        LogFlowThisFunc(("AssignRemoteMachine() returned %08X\n", rc));
+
+        if (FAILED(rc))
+            // the failure may occur w/o any error info (from RPC), so provide one
+            return setError(VBOX_E_VM_ERROR,
+                            tr("Failed to assign the machine to the session (%Rrc)"), rc);
+        alock.enter();
+
+        // need to revalidate the state after entering the lock again
+        if (mData->mSession.mState != SessionState_Locked)
+        {
+            pSessionControl->Uninitialize();
+            return setError(VBOX_E_INVALID_SESSION_STATE,
+                            tr("The machine '%ls' was unlocked unexpectedly while attempting to share its session"),
+                               mUserData->mName.raw());
+        }
+
+        // add the caller's session to the list
+        mData->mSession.mRemoteControls.push_back(pSessionControl);
+    }
+    else if (    mData->mSession.mState == SessionState_Locked
+              || mData->mSession.mState == SessionState_Unlocking
+            )
+    {
+        // sharing not permitted, or machine still unlocking:
+        return setError(VBOX_E_INVALID_OBJECT_STATE,
+                        tr("The machine '%ls' is already locked for a session (or being unlocked)"),
+                        mUserData->mName.raw());
     }
     else
     {
-        // no lock exists or sharing not permitted: then create the session machine
-
-        /* may not be busy */
+        // machine is not locked: then write-lock the machine (create the session machine)
+
+        // must not be busy
         AssertReturn(!Global::IsOnlineOrTransient(mData->mMachineState), E_FAIL);
 
@@ -2807 +2807 @@
         Assert(pid != NIL_RTPROCESS);
 
-        if (mData->mSession.mState == SessionState_Spawning)
-        {
-            /* This machine is awaiting for a spawning session to be opened, so
-             * reject any other open attempts from processes other than one
-             * started by #openRemoteSession(). */
+        bool fLaunchingVMProcess = (mData->mSession.mState == SessionState_Spawning);
+
+        if (fLaunchingVMProcess)
+        {
+            // this machine is awaiting for a spawning session to be opened:
+            // then the calling process must be the one that got started by
+            // launchVMProcess()
 
             LogFlowThisFunc(("mSession.mPid=%d(0x%x)\n", mData->mSession.mPid, mData->mSession.mPid));
@@ -2867 +2869 @@
 
             if (    SUCCEEDED(rc)
-                 && origState == SessionState_Spawning
+                 && fLaunchingVMProcess
                )
             {
@@ -2911 +2913 @@
         }
 
-        /* finalize spawning anyway (this is why we don't return on errors above) */
-        if (mData->mSession.mState == SessionState_Spawning)
+        // finalize spawning anyway (this is why we don't return on errors above)
+        if (fLaunchingVMProcess)
         {
             /* Note that the progress object is finalized later */

trunk/src/VBox/Main/SessionImpl.cpp

@@ -64 +64 @@
     LogFlowThisFunc(("\n"));
 
-    uninit(true /* aFinalRelease */);
+    uninit();
 }
 
@@ -109 +109 @@
  *  @note Locks this object for writing.
  */
-void Session::uninit(bool aFinalRelease)
+void Session::uninit()
 {
     LogFlowThisFuncEnter();
-    LogFlowThisFunc(("aFinalRelease=%d\n", aFinalRelease));
 
     /* Enclose the state transition Ready->InUninit->NotReady */
@@ -131 +130 @@
                mState == SessionState_Spawning);
 
-        HRESULT rc = close(aFinalRelease, false /* aFromServer */);
+        HRESULT rc = unlockMachine(true /* aFinalRelease */, false /* aFromServer */);
         AssertComRC(rc);
     }
@@ -233 +232 @@
 /////////////////////////////////////////////////////////////////////////////
 
-STDMETHODIMP Session::Close()
+STDMETHODIMP Session::UnlockMachine()
 {
     LogFlowThisFunc(("mState=%d, mType=%d\n", mState, mType));
@@ -245 +244 @@
     CHECK_OPEN();
 
-    return close(false /* aFinalRelease */, false /* aFromServer */);
+    return unlockMachine(false /* aFinalRelease */, false /* aFromServer */);
 }
 
@@ -491 +490 @@
 
         /* close ourselves */
-        rc = close(false /* aFinalRelease */, true /* aFromServer */);
+        rc = unlockMachine(false /* aFinalRelease */, true /* aFromServer */);
     }
     else if (autoCaller.state() == InUninit)
@@ -793 +792 @@
 
 /**
- *  Closes the current session.
+ *  Unlocks a machine associated with the current session.
  *
  *  @param aFinalRelease    called as a result of FinalRelease()
  *  @param aFromServer      called as a result of Uninitialize()
  *
- *  @note To be called only from #uninit(), #Close() or #Uninitialize().
+ *  @note To be called only from #uninit(), #UnlockMachine() or #Uninitialize().
  *  @note Locks this object for writing.
  */
-HRESULT Session::close(bool aFinalRelease, bool aFromServer)
+HRESULT Session::unlockMachine(bool aFinalRelease, bool aFromServer)
 {
     LogFlowThisFuncEnter();

trunk/src/VBox/Main/cbinding/tstXPCOMCGlue.c

@@ -365 +365 @@
 
     listVMs(vbox, session);
-    session->vtbl->Close(session);
+    session->vtbl->UnlockMachine(session);
 
     printf("----------------------------------------------------\n");

trunk/src/VBox/Main/glue/glue-java.xsl

@@ -2504 +2504 @@
     {
           if (s != null)
-            s.close();
+            s.unlockMachine();
     }
 
@@ -2569 +2569 @@
         IProgress p = m.launchVMProcess(session, type, "");
         progressBar(p, timeout);
-        session.close();
+        session.unlockMachine();
         return true;
     }
@@ -3020 +3020 @@
     {
           if (s != null)
-            s.close();
+          s.unlockMachine();
     }
 
@@ -3068 +3068 @@
         IProgress p = vbox.openRemoteSession(session, mid, type, "");
         progressBar(p, timeout);
-        session.close();
+        session.unlockMachine();
         return true;
     }
@@ -3466 +3466 @@
     {
           if (s != null)
-            s.close();
+            s.unlockMachine();
     }
 
@@ -3513 +3513 @@
         IProgress p = m.launchVMProcess(session, type, "");
         progressBar(p, timeout);
-        session.close();
+        session.unlockMachine();
         return true;
     }

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

@@ -4259 +4259 @@
         object which controls VM execution.
 
-        Also in all of the above cases, one must always call <link to="ISession::close" />
-        to release the lock on the machine, or the machine's state will
-        eventually be set to "Aborted".
+        Also in all of the above cases, one must always call
+        <link to="ISession::unlockMachine" /> to release the lock on the machine, or
+        the machine's state will eventually be set to "Aborted".
 
         To change settings on a machine, the following sequence is typically
@@ -4271 +4271 @@
           <li>Obtain a mutable IMachine object from <link to="ISession::machine" />.</li>
 
-          <li>Change the settings of the machine.</li>
+          <li>Change the settings of the machine by invoking IMachine methods.</li>
 
           <li>Call <link to="IMachine::saveSettings" />.</li>
 
-          <li>Close the session by calling <link to="ISession::close"/>.</li>
+          <li>Release the write lock by calling <link to="ISession::unlockMachine"/>.</li>
         </ol>
 
@@ -4307 +4307 @@
     <method name="launchVMProcess">
       <desc>
-        Spawns a new process that will execute the virtual machine.
-
-        This operation can take some time (a new VM is started in a new process,
+        Spawns a new process that will execute the virtual machine and obtains a shared
+        lock on the machine for the calling session.
+
+        If launching the VM succeeds, the new VM process will create its own session
+        and write-lock the machine for it, preventing conflicting changes from other
+        processes. If the machine is already locked (because it is already running or
+        because another session has a write lock), launching the VM process will therefore
+        fail. Reversely, future attempts to obtain a write lock will also fail while the
+        machine is running.
+
+        The caller's session object remains separate from the session opened by the new
+        VM process. It receives its own <link to="IConsole" /> object which can be used
+        to control machine execution, but it cannot be used to change all VM settings
+        which would be available after a <link to="#lockMachine" /> call.
+
+        The caller must eventually release the session's shared lock by calling
+        <link to="ISession::unlockMachine" /> on the local session object once this call
+        has returned. However, the session's state (see <link to="ISession::state" />)
+        will not return to "Unlocked" until the remote session has also unlocked
+        the machine (i.e. the machine has stopped running).
+
+        Lauching a VM process can take some time (a new VM is started in a new process,
         for which memory and other resources need to be set up). Because of this,
         an <link to="IProgress" /> object is returned to allow the caller to wait
@@ -4320 +4339 @@
         via the progress object, if available.
 
-        If launching the VM succeeds, the new VM process will create its own
-        session and lock the machine for it, preventing conflicting changes
-        from other processes. If the machine is already locked (because it
-        is already running or because another session is making changes),
-        launching the VM process will therefore fail. Reversely, future
-        locking attempts will also fail while the machine is running.
-
-        The caller's session object remains separate from the session opened
-        by the new VM process. It receives its own <link to="IConsole" />
-        object which can be used to control machine execution, but it cannot
-        be used to change all VM settings which would be available after
-        a <link to="#lockMachine" /> call.
-
-        As with all <link to="ISession" /> objects, it is recommended to call
-        <link to="ISession::close" /> on the local session object once this call
-        has returned. However, the session's state (see <link to="ISession::state" />)
-        will not return to "Unlocked" until the remote session has also unlocked
-        the machine.
+        The progress object will have at least 2 sub-operations. The first
+        operation covers the period up to the new VM process calls powerUp.
+        The subsequent operations mirror the <link to="IConsole::powerUp"/>
+        progress object. Because <link to="IConsole::powerUp"/> may require
+        some extra sub-operations, the <link to="IProgress::operationCount"/>
+        may change at the completion of operation.
+
+        For details on the teleportation progress operation, see
+        <link to="IConsole::powerUp"/>.
 
         The @a environment argument is a string containing definitions of
@@ -4354 +4364 @@
         If the environment string is @c null or empty, the server environment
         is inherited by the started process as is.
-
-        The progress object will have at least 2 sub-operations. The first
-        operation covers the period up to the new VM process calls powerUp.
-        The subsequent operations mirror the <link to="IConsole::powerUp"/>
-        progress object. Because <link to="IConsole::powerUp"/> may require
-        some extra sub-operations, the <link to="IProgress::operationCount"/>
-        may change at the completion of operation.
-
-        For details on the teleportation progress operation, see
-        <link to="IConsole::powerUp"/>.
 
         <result name="E_UNEXPECTED">
@@ -12771 +12771 @@
      >
     <desc>
-      The ISession interface represents a serialization primitive for virtual
-      machines. Any caller wishing to manipulate a virtual machine (represented
-      by an IMachine object) needs to create a session object first, which lives
-      in its own process space. Such session objects are then attached to the
-      <link to="IMachine" /> objects living in the VirtualBox server process to
-      coordinate possibly conflicting changes.
+      The ISession interface represents a client process and allows for locking
+      virtual machines (represented by IMachine objects) to prevent conflicting
+      changes to the machine.
+
+      Any caller wishing to manipulate a virtual machine needs to create a session
+      object first, which lives in its own process space. Such session objects are
+      then associated with <link to="IMachine" /> objects living in the VirtualBox
+      server process to coordinate such changes.
 
       There are two typical scenarios in which sessions are used:
 
       <ul>
-        <li>To alter machine settings, one needs to lock a machine for a given session
-          (client process) by calling <link to="IMachine::lockMachine"/>. While a
-          machine is thus locked, no any other process may lock the machine again.
-
-          The same applies for any process which indends to actually run a virtual
-          machine in its own context, such as the VirtualBox GUI or VBoxHeadless
-          executables. They must also lock a machine for their own sessions before
-          being allowed to power up the virtual machine.
-
-          As a result, no machine can be altered while another process is already
-          using it, either because that process is modifying machine settings or
-          because the machine is running.
+        <li>To alter machine settings or control a running virtual machine, one
+          needs to lock a machine for a given session (client process) by calling
+          <link to="IMachine::lockMachine"/>.
+
+          Whereas multiple sessions may control a running virtual machine, only
+          one process can obtain a write lock on the machine to prevent conflicting
+          changes. A write lock is also needed if a process wants to actually run a
+          virtual machine in its own context, such as the VirtualBox GUI or
+          VBoxHeadless front-ends. They must also lock a machine for their own
+          sessions before they are allowed to power up the virtual machine.
+
+          As a result, no machine settings can be altered while another process is
+          already using it, either because that process is modifying machine settings
+          or because the machine is running.
         </li>
         <li>
-          To initiate virtual machine execution using one of the existing VirtualBox
-          front-ends (e.g. the GUI or VBoxHeadless), one would instead call
-          <link to="IMachine::launchVMProcess"/>, which also requires a session
-          object as its first parameter. This session then identifies the caller
-          and lets the caller control the started machine (for example, pause machine
-          execution or power it down) as well as be notified about machine execution
-          state changes.
+          To start a VM using one of the existing VirtualBox front-ends (e.g. the
+          VirtualBox GUI or VBoxHeadless), one would use
+          <link to="IMachine::launchVMProcess"/>, which also takes a session object
+          as its first parameter. This session then identifies the caller and lets the
+          caller control the started machine (for example, pause machine execution or
+          power it down) as well as be notified about machine execution state changes.
         </li>
       </ul>
 
-      How sessions objects are used depends on whether you use the Main API
-      via COM or via the webservice:
+      How sessions objects are created in a client process depends on whether you use
+      the Main API via COM or via the webservice:
 
       <ul>
@@ -12844 +12847 @@
     </attribute>
 
-    <method name="close">
-      <desc>
-        Closes a session that was previously opened.
-
-        Calling this method is eventually required every time a machine has been
-        locked for a particular session using the <link to="IMachine::launchVMProcess" />
-        or <link to="IMachine::lockMachine" />) calls. Otherwise the state of
+    <method name="unlockMachine">
+      <desc>
+        Unlocks a machine that was previously locked for the current session.
+
+        Calling this method is required every time a machine has been locked
+        for a particular session using the <link to="IMachine::launchVMProcess" />
+        or <link to="IMachine::lockMachine" /> calls. Otherwise the state of
         the machine will be set to <link to="MachineState_Aborted" /> on the
         server, and changes made to the machine settings will be lost.
 
-        Generally, it is recommended to close all open sessions explicitly
+        Generally, it is recommended to unlock all machines explicitly
         before terminating the application (regardless of the reason for
         the termination).
@@ -12860 +12863 @@
         <note>
           Do not expect the session state (<link to="ISession::state" />
-          to return to "Closed" immediately after you invoke
-          ISession::close(), particularly if you have started a remote
-          session to execute the VM in a new process. The session state will
-          automatically return to "Closed" once the VM is no longer executing,
-          which can of course take a very long time.
+          to return to "Unlocked" immediately after you invoke this method,
+          particularly if you have started a new VM process. The session
+          state will automatically return to "Unlocked" once the VM is no
+          longer executing, which can of course take a very long time.
         </note>
 
         <result name="E_UNEXPECTED">
-          Session is not open.
+          Session is not locked.
         </result>
 

trunk/src/VBox/Main/include/SessionImpl.h

@@ -66 +66 @@
     // public initializers/uninitializers only for internal purposes
     HRESULT init();
-    void uninit(bool aFinalRelease);
+    void uninit();
 
     // ISession properties
@@ -75 +75 @@
 
     // ISession methods
-    STDMETHOD(Close)();
+    STDMETHOD(UnlockMachine)();
 
     // IInternalSessionControl methods
@@ -112 +112 @@
 private:
 
-    HRESULT close(bool aFinalRelease, bool aFromServer);
+    HRESULT unlockMachine(bool aFinalRelease, bool aFromServer);
     HRESULT grabIPCSemaphore();
     void releaseIPCSemaphore();

trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp

@@ -406 +406 @@
      * necessary any more.
      */
-    session->Close();
+    session->UnlockMachine();
 }
 

trunk/src/VBox/Main/testcase/tstVBoxAPIWin.cpp

@@ -238 +238 @@
 
             /* Close the session. */
-            rc = session->Close();
+            rc = session->UnlockMachine();
 
         } while (0);