Index: /trunk/src/VBox/Frontends/VBoxHeadless/VBoxHeadless.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxHeadless/VBoxHeadless.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxHeadless/VBoxHeadless.cpp (revision 31070) @@ -1161,5 +1161,5 @@ */ Log(("VBoxHeadless: Closing the session...\n")); - session->Close(); + session->UnlockMachine(); } Index: /trunk/src/VBox/Frontends/VBoxHeadless/testcase/tstHeadless.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxHeadless/testcase/tstHeadless.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxHeadless/testcase/tstHeadless.cpp (revision 31070) @@ -201,6 +201,6 @@ } - 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); Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp (revision 31070) @@ -416,5 +416,5 @@ * 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); Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageControlVM.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageControlVM.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageControlVM.cpp (revision 31070) @@ -881,5 +881,5 @@ } while (0); - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestCtrl.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestCtrl.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestCtrl.cpp (revision 31070) @@ -520,5 +520,5 @@ } } - a->session->Close(); + a->session->UnlockMachine(); } while (0); } Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestProp.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestProp.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageGuestProp.cpp (revision 31070) @@ -168,5 +168,5 @@ CHECK_ERROR(machine, SaveSettings()); - a->session->Close(); + a->session->UnlockMachine(); } return SUCCEEDED(rc) ? 0 : 1; Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageInfo.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageInfo.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageInfo.cpp (revision 31070) @@ -2146,5 +2146,5 @@ if (console) - a->session->Close(); + a->session->UnlockMachine(); } Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageMisc.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageMisc.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageMisc.cpp (revision 31070) @@ -393,5 +393,5 @@ /* it's important to always close sessions */ - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; @@ -425,5 +425,5 @@ CHECK_ERROR_BREAK(console, ForgetSavedState(true)); } while (0); - CHECK_ERROR_BREAK(a->session, Close()); + CHECK_ERROR_BREAK(a->session, UnlockMachine()); } while (0); } @@ -459,5 +459,5 @@ 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,5 +735,5 @@ fWritable, fAutoMount)); if (console) - a->session->Close(); + a->session->UnlockMachine(); } else @@ -751,5 +751,5 @@ CHECK_ERROR(machine, SaveSettings()); - a->session->Close(); + a->session->UnlockMachine(); } } @@ -800,5 +800,5 @@ if (console) - a->session->Close(); + a->session->UnlockMachine(); } else @@ -814,5 +814,5 @@ /* commit and close the session */ CHECK_ERROR(machine, SaveSettings()); - a->session->Close(); + a->session->UnlockMachine(); } } @@ -904,5 +904,5 @@ } } - a->session->Close(); + a->session->UnlockMachine(); } } Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageModifyVM.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageModifyVM.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageModifyVM.cpp (revision 31070) @@ -2048,5 +2048,5 @@ /* it's important to always close sessions */ - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageSnapshot.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageSnapshot.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageSnapshot.cpp (revision 31070) @@ -499,5 +499,5 @@ } while (0); - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageStorageController.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageStorageController.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageStorageController.cpp (revision 31070) @@ -636,5 +636,5 @@ leave: /* it's important to always close sessions */ - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; @@ -765,5 +765,5 @@ { /* 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,5 +954,5 @@ /* it's important to always close sessions */ - a->session->Close(); + a->session->UnlockMachine(); return SUCCEEDED(rc) ? 0 : 1; Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageUSB.cpp (revision 31070) @@ -562,5 +562,5 @@ } /* close the session */ - a->session->Close(); + a->session->UnlockMachine(); } Index: /trunk/src/VBox/Frontends/VBoxSDL/VBoxSDL.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxSDL/VBoxSDL.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VBoxSDL/VBoxSDL.cpp (revision 31070) @@ -2747,5 +2747,5 @@ if (sessionOpened) { - rc = session->Close(); + rc = session->UnlockMachine(); AssertComRC(rc); } Index: /trunk/src/VBox/Frontends/VirtualBox/src/VBoxMediaManagerDlg.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/VBoxMediaManagerDlg.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/VBoxMediaManagerDlg.cpp (revision 31070) @@ -1263,5 +1263,5 @@ /* If a new session was opened, we must close it */ if (!session.isNull()) - session.Close(); + session.UnlockMachine(); return success; Index: /trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIMachine.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIMachine.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIMachine.cpp (revision 31070) @@ -418,5 +418,5 @@ delete m_pActionsPool; m_pActionsPool = 0; - m_session.Close(); + m_session.UnlockMachine(); m_session.detach(); QApplication::quit(); Index: /trunk/src/VBox/Frontends/VirtualBox/src/selector/UIVMPreviewWindow.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/selector/UIVMPreviewWindow.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/selector/UIVMPreviewWindow.cpp (revision 31070) @@ -90,5 +90,5 @@ /* Close any open session */ if (m_session.GetState() == KSessionState_Locked) - m_session.Close(); + m_session.UnlockMachine(); } @@ -363,5 +363,5 @@ /* Close any open session */ if (m_session.GetState() == KSessionState_Locked) - m_session.Close(); + m_session.UnlockMachine(); if (!m_machine.isNull()) { Index: /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSelectorWnd.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSelectorWnd.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSelectorWnd.cpp (revision 31070) @@ -628,5 +628,5 @@ mVMListView->setFocus(); - session.Close(); + session.UnlockMachine(); } @@ -672,5 +672,5 @@ else ok = true; - session.Close(); + session.UnlockMachine(); } else @@ -771,5 +771,5 @@ vboxProblem().cannotOpenSession(vbox, item->machine(), progress); - session.Close(); + session.UnlockMachine(); } @@ -809,5 +809,5 @@ vboxProblem().cannotDiscardSavedState (console); - session.Close(); + session.UnlockMachine(); } @@ -841,5 +841,5 @@ } - session.Close(); + session.UnlockMachine(); } Index: /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSnapshotsWgt.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSnapshotsWgt.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/selector/VBoxSnapshotsWgt.cpp (revision 31070) @@ -544,5 +544,5 @@ vboxProblem().cannotRestoreSnapshot (progress, snapshot.GetName()); - session.Close(); + session.UnlockMachine(); } @@ -590,5 +590,5 @@ vboxProblem().cannotDeleteSnapshot (console, snapshot.GetName()); - session.Close(); + session.UnlockMachine(); } @@ -661,5 +661,5 @@ vboxProblem().cannotTakeSnapshot (console); - session.Close(); + session.UnlockMachine(); } } Index: /trunk/src/VBox/Frontends/VirtualBox/src/wizards/newvm/UINewVMWzd.cpp =================================================================== --- /trunk/src/VBox/Frontends/VirtualBox/src/wizards/newvm/UINewVMWzd.cpp (revision 31069) +++ /trunk/src/VBox/Frontends/VirtualBox/src/wizards/newvm/UINewVMWzd.cpp (revision 31070) @@ -777,5 +777,5 @@ } - session.Close(); + session.UnlockMachine(); } if (!success) Index: /trunk/src/VBox/Main/ApplianceImplImport.cpp =================================================================== --- /trunk/src/VBox/Main/ApplianceImplImport.cpp (revision 31069) +++ /trunk/src/VBox/Main/ApplianceImplImport.cpp (revision 31070) @@ -1243,5 +1243,5 @@ rc2 = sMachine->SaveSettings(); } - stack.pSession->Close(); + stack.pSession->UnlockMachine(); } } @@ -1850,5 +1850,5 @@ // 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,5 +1857,5 @@ { if (stack.fSessionOpen) - stack.pSession->Close(); + stack.pSession->UnlockMachine(); throw; @@ -1942,5 +1942,5 @@ // 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,5 +1949,5 @@ { if (stack.fSessionOpen) - stack.pSession->Close(); + stack.pSession->UnlockMachine(); throw; Index: /trunk/src/VBox/Main/MachineImpl.cpp =================================================================== --- /trunk/src/VBox/Main/MachineImpl.cpp (revision 31069) +++ /trunk/src/VBox/Main/MachineImpl.cpp (revision 31070) @@ -2698,5 +2698,5 @@ tr("The given session is busy")); - /* get the IInternalSessionControl interface */ + // get the client's IInternalSessionControl interface ComPtr pSessionControl = aSession; ComAssertMsgRet(!!pSessionControl, ("No IInternalSessionControl interface"), @@ -2727,76 +2727,76 @@ // 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 pDirectControl = mData->mSession.mDirectControl; - ComObjPtr 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 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 pSessionW = mData->mSession.mDirectControl; + ComAssertRet(!pSessionW.isNull(), E_FAIL); + ComObjPtr 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 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,9 +2807,11 @@ 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,5 +2869,5 @@ if ( SUCCEEDED(rc) - && origState == SessionState_Spawning + && fLaunchingVMProcess ) { @@ -2911,6 +2913,6 @@ } - /* 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 */ Index: /trunk/src/VBox/Main/SessionImpl.cpp =================================================================== --- /trunk/src/VBox/Main/SessionImpl.cpp (revision 31069) +++ /trunk/src/VBox/Main/SessionImpl.cpp (revision 31070) @@ -64,5 +64,5 @@ LogFlowThisFunc(("\n")); - uninit(true /* aFinalRelease */); + uninit(); } @@ -109,8 +109,7 @@ * @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,5 +130,5 @@ mState == SessionState_Spawning); - HRESULT rc = close(aFinalRelease, false /* aFromServer */); + HRESULT rc = unlockMachine(true /* aFinalRelease */, false /* aFromServer */); AssertComRC(rc); } @@ -233,5 +232,5 @@ ///////////////////////////////////////////////////////////////////////////// -STDMETHODIMP Session::Close() +STDMETHODIMP Session::UnlockMachine() { LogFlowThisFunc(("mState=%d, mType=%d\n", mState, mType)); @@ -245,5 +244,5 @@ CHECK_OPEN(); - return close(false /* aFinalRelease */, false /* aFromServer */); + return unlockMachine(false /* aFinalRelease */, false /* aFromServer */); } @@ -491,5 +490,5 @@ /* close ourselves */ - rc = close(false /* aFinalRelease */, true /* aFromServer */); + rc = unlockMachine(false /* aFinalRelease */, true /* aFromServer */); } else if (autoCaller.state() == InUninit) @@ -793,13 +792,13 @@ /** - * 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(); Index: /trunk/src/VBox/Main/cbinding/tstXPCOMCGlue.c =================================================================== --- /trunk/src/VBox/Main/cbinding/tstXPCOMCGlue.c (revision 31069) +++ /trunk/src/VBox/Main/cbinding/tstXPCOMCGlue.c (revision 31070) @@ -365,5 +365,5 @@ listVMs(vbox, session); - session->vtbl->Close(session); + session->vtbl->UnlockMachine(session); printf("----------------------------------------------------\n"); Index: /trunk/src/VBox/Main/glue/glue-java.xsl =================================================================== --- /trunk/src/VBox/Main/glue/glue-java.xsl (revision 31069) +++ /trunk/src/VBox/Main/glue/glue-java.xsl (revision 31070) @@ -2504,5 +2504,5 @@ { if (s != null) - s.close(); + s.unlockMachine(); } @@ -2569,5 +2569,5 @@ IProgress p = m.launchVMProcess(session, type, ""); progressBar(p, timeout); - session.close(); + session.unlockMachine(); return true; } @@ -3020,5 +3020,5 @@ { if (s != null) - s.close(); + s.unlockMachine(); } @@ -3068,5 +3068,5 @@ IProgress p = vbox.openRemoteSession(session, mid, type, ""); progressBar(p, timeout); - session.close(); + session.unlockMachine(); return true; } @@ -3466,5 +3466,5 @@ { if (s != null) - s.close(); + s.unlockMachine(); } @@ -3513,5 +3513,5 @@ IProgress p = m.launchVMProcess(session, type, ""); progressBar(p, timeout); - session.close(); + session.unlockMachine(); return true; } Index: /trunk/src/VBox/Main/idl/VirtualBox.xidl =================================================================== --- /trunk/src/VBox/Main/idl/VirtualBox.xidl (revision 31069) +++ /trunk/src/VBox/Main/idl/VirtualBox.xidl (revision 31070) @@ -4259,7 +4259,7 @@ object which controls VM execution. - Also in all of the above cases, one must always call - 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 + 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,9 +4271,9 @@
  • Obtain a mutable IMachine object from .
    • -
  • Change the settings of the machine.
    • +
  • Change the settings of the machine by invoking IMachine methods.
  • Call .
    • -
  • Close the session by calling .
    • +
  • Release the write lock by calling .
    • @@ -4307,7 +4307,26 @@ - 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 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 call. + + The caller must eventually release the session's shared lock by calling + on the local session object once this call + has returned. However, the session's state (see ) + 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 object is returned to allow the caller to wait @@ -4320,22 +4339,13 @@ 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 - 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 call. - - As with all objects, it is recommended to call - on the local session object once this call - has returned. However, the session's state (see ) - 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 + progress object. Because may require + some extra sub-operations, the + may change at the completion of operation. + + For details on the teleportation progress operation, see + . The @a environment argument is a string containing definitions of @@ -4354,14 +4364,4 @@ 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 - progress object. Because may require - some extra sub-operations, the - may change at the completion of operation. - - For details on the teleportation progress operation, see - . @@ -12771,40 +12771,43 @@ > - 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 - 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 objects living in the VirtualBox + server process to coordinate such changes. There are two typical scenarios in which sessions are used:
      -
    • To alter machine settings, one needs to lock a machine for a given session - (client process) by calling . 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. +
    • To alter machine settings or control a running virtual machine, one + needs to lock a machine for a given session (client process) by calling + . + + 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.
    • - To initiate virtual machine execution using one of the existing VirtualBox - front-ends (e.g. the GUI or VBoxHeadless), one would instead call - , 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 + , 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.
    - 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:
      @@ -12844,15 +12847,15 @@ - - - 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 - or ) calls. Otherwise the state of + + + 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 + or calls. Otherwise the state of the machine will be set to 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,13 +12863,12 @@ Do not expect the session 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. - Session is not open. + Session is not locked. Index: /trunk/src/VBox/Main/include/SessionImpl.h =================================================================== --- /trunk/src/VBox/Main/include/SessionImpl.h (revision 31069) +++ /trunk/src/VBox/Main/include/SessionImpl.h (revision 31070) @@ -66,5 +66,5 @@ // public initializers/uninitializers only for internal purposes HRESULT init(); - void uninit(bool aFinalRelease); + void uninit(); // ISession properties @@ -75,5 +75,5 @@ // ISession methods - STDMETHOD(Close)(); + STDMETHOD(UnlockMachine)(); // IInternalSessionControl methods @@ -112,5 +112,5 @@ private: - HRESULT close(bool aFinalRelease, bool aFromServer); + HRESULT unlockMachine(bool aFinalRelease, bool aFromServer); HRESULT grabIPCSemaphore(); void releaseIPCSemaphore(); Index: /trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp =================================================================== --- /trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp (revision 31069) +++ /trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp (revision 31070) @@ -406,5 +406,5 @@ * necessary any more. */ - session->Close(); + session->UnlockMachine(); } Index: /trunk/src/VBox/Main/testcase/tstVBoxAPIWin.cpp =================================================================== --- /trunk/src/VBox/Main/testcase/tstVBoxAPIWin.cpp (revision 31069) +++ /trunk/src/VBox/Main/testcase/tstVBoxAPIWin.cpp (revision 31070) @@ -238,5 +238,5 @@ /* Close the session. */ - rc = session->Close(); + rc = session->UnlockMachine(); } while (0);