Changeset 5390 in vbox for trunk/src

Timestamp:

Oct 19, 2007 4:47:52 PM (17 years ago)

Author:

vboxsync

Message:

Main: Implemented IConsole::AdoptSavedState(); Prototyped IVirtualBox::WaitForPropertyChange().

Location:

trunk/src/VBox/Main

Files:

• ConsoleImpl.cpp (modified) (1 diff)
• MachineImpl.cpp (modified) (3 diffs)
• VirtualBoxImpl.cpp (modified) (5 diffs)
• idl/VirtualBox.xidl (modified) (7 diffs)
• include/ConsoleImpl.h (modified) (1 diff)
• include/MachineImpl.h (modified) (1 diff)
• include/VirtualBoxImpl.h (modified) (1 diff)

trunk/src/VBox/Main/ConsoleImpl.cpp

@@ -1784 +1784 @@
     LogFlowThisFuncLeave();
     return rc;
+}
+
+STDMETHODIMP Console::AdoptSavedState (INPTR BSTR aSavedStateFile)
+{
+    if (!aSavedStateFile)
+        return E_INVALIDARG;
+
+    AutoCaller autoCaller (this);
+    CheckComRCReturnRC (autoCaller.rc());
+
+    AutoLock alock (this);
+
+    if (mMachineState != MachineState_PoweredOff &&
+        mMachineState != MachineState_Aborted)
+        return setError (E_FAIL,
+            tr ("Cannot adopt the saved machine state as the machine is "
+                "not in Powered Off or Aborted state (machine state: %d)"),
+            mMachineState);
+
+    return mControl->AdoptSavedState (aSavedStateFile);
 }
 

trunk/src/VBox/Main/MachineImpl.cpp

@@ -6874 +6874 @@
         {
             if (mSSData->mStateFilePath)
-                CFGLDRSetBSTR (machineNode, "stateFile", mSSData->mStateFilePath);
+            {
+                /* try to make the file name relative to the settings file dir */
+                Utf8Str stateFilePath = mSSData->mStateFilePath;
+                calculateRelativePath (stateFilePath, stateFilePath);
+                CFGLDRSetString (machineNode, "stateFile", stateFilePath);
+            }
             else
                 CFGLDRDeleteAttribute (machineNode, "stateFile");
@@ -8728 +8733 @@
 
 /**
+ *  @note Locks this objects for writing.
+ */
+STDMETHODIMP SessionMachine::AdoptSavedState (INPTR BSTR aSavedStateFile)
+{
+    LogFlowThisFunc (("\n"));
+
+    AssertReturn (aSavedStateFile, E_INVALIDARG);
+
+    AutoCaller autoCaller (this);
+    AssertComRCReturn (autoCaller.rc(), autoCaller.rc());
+
+    AutoLock alock (this);
+
+    AssertReturn (mData->mMachineState == MachineState_PoweredOff ||
+                  mData->mMachineState == MachineState_Aborted,
+                  E_FAIL);
+
+    Utf8Str stateFilePathFull = aSavedStateFile;
+    int vrc = calculateFullPath (stateFilePathFull, stateFilePathFull);
+    if (VBOX_FAILURE (vrc))
+        return setError (E_FAIL,
+            tr ("Invalid saved state file path: '%ls' (%Vrc)"),
+                aSavedStateFile, vrc);
+
+    mSSData->mStateFilePath = stateFilePathFull;
+
+    /* The below setMachineState() will detect the state transition and will
+     * update the settings file */
+
+    return setMachineState (MachineState_Saved);
+}
+
+/**
  *  @note Locks mParent + this objects for writing.
  */
@@ -10543 +10581 @@
         aMachineState == MachineState_Saved)
     {
+        /* the machine has stopped execution
+         * (or the saved state file was adopted) */
         stsFlags |= SaveSTS_StateTimeStamp;
+    }
+
+    if ((oldMachineState == MachineState_PoweredOff ||
+         oldMachineState == MachineState_Aborted) &&
+        aMachineState == MachineState_Saved)
+    {
+        /* the saved state file was adopted */
+        Assert (!mSSData->mStateFilePath.isNull());
+        stsFlags |= SaveSTS_StateFilePath;
     }
 

trunk/src/VBox/Main/VirtualBoxImpl.cpp

@@ -2020 +2020 @@
 
 /**
- *  Registers a new client callback on this instance. The methods of the
- *  callback interface will be called by this instance when the appropriate
- *  event occurs.
- *
  *  @note Locks this object for writing.
  */
-STDMETHODIMP VirtualBox::RegisterCallback (IVirtualBoxCallback *callback)
-{
-    LogFlowMember (("VirtualBox::RegisterCallback(): callback=%p\n", callback));
-
-    if (!callback)
+STDMETHODIMP VirtualBox::RegisterCallback (IVirtualBoxCallback *aCallback)
+{
+    LogFlowThisFunc (("aCallback=%p\n", aCallback));
+
+    if (!aCallback)
         return E_INVALIDARG;
 
@@ -2037 +2033 @@
 
     AutoLock alock (this);
-    mData.mCallbacks.push_back (CallbackList::value_type (callback));
+    mData.mCallbacks.push_back (CallbackList::value_type (aCallback));
 
     return S_OK;
@@ -2043 +2039 @@
 
 /**
- *  Unregisters the previously registered client callback.
- *
  *  @note Locks this object for writing.
  */
-STDMETHODIMP VirtualBox::UnregisterCallback (IVirtualBoxCallback *callback)
-{
-    if (!callback)
+STDMETHODIMP VirtualBox::UnregisterCallback (IVirtualBoxCallback *aCallback)
+{
+    if (!aCallback)
         return E_INVALIDARG;
 
@@ -2062 +2056 @@
     it = std::find (mData.mCallbacks.begin(),
                     mData.mCallbacks.end(),
-                    CallbackList::value_type (callback));
+                    CallbackList::value_type (aCallback));
     if (it == mData.mCallbacks.end())
         rc = E_INVALIDARG;
@@ -2068 +2062 @@
         mData.mCallbacks.erase (it);
 
-    LogFlowMember (("VirtualBox::UnregisterCallback(): callback=%p, rc=%08X\n",
-                    callback, rc));
-    return rc;
+    LogFlowThisFunc (("aCallback=%p, rc=%08X\n", aCallback, rc));
+    return rc;
+}
+
+STDMETHODIMP VirtualBox::WaitForPropertyChange (INPTR BSTR aWhat, ULONG aTimeout,
+                                                BSTR *aChanged, BSTR *aValues)
+{
+    return E_NOTIMPL;
 }
 

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

@@ -809 +809 @@
   <interface
      name="IVirtualBox" extends="$dispatched"
-     uuid="e1606565-8954-4703-b22a-620941b85a1c"
+     uuid="64f652cb-7fdf-482d-ae19-4dbb289a5ca0"
      wsmap="managed"
      >
@@ -1774 +1774 @@
 
     <method name="registerCallback">
-      <param name="callback" type="IVirtualBoxCallback" dir="in"/>
+      <desc>
+        Registers a new global VirtualBox callback. The methods of the given
+        callback object will be called by VirtualBox when an appropriate
+        event occurs.
+      </desc>
+      <param name="callback" type="IVirtualBoxCallback" dir="in">
+        <desc>Callback object to register.</desc>
+      </param>
     </method>
 
     <method name="unregisterCallback">
-      <param name="callback" type="IVirtualBoxCallback" dir="in"/>
+      <desc>
+        Unregisters the previously registered global VirtualBox callback.
+      </desc>
+      <param name="callback" type="IVirtualBoxCallback" dir="in">
+        <desc>Callback object to unregister.</desc>
+      </param>
+    </method>
+
+    <method name="waitForPropertyChange">
+      <desc>
+        Blocks the caller until any of the properties represented by the @a
+        what argument changes the value or until the given timeout interval
+        expires.
+
+        The @a what argument is a comma separated list of propertiy masks that
+        describe properties the caller is interested in. The property mask is
+        a string in the following format:
+
+        @code
+        [[group.]subgroup.]name
+        @endcode
+
+        where @c name is the property name and @c group, @c subgroup are zero
+        or or more property group specifiers. Each element (group or name) in
+        the property mask may be either a latin string or an asterisk symbol
+        (@c "*") which is used to match any string for the given element. A
+        property mask that doesn't contain asterisk symbols represents a
+        single fully qualified property name.
+
+        Groups in the fully qualified property name go from more generic (the
+        left-most part) to more specific (the right-most part). The first
+        element is usually a name of the object the property belongs to.  The
+        second element may be either a property name, or a child object name,
+        or an index if the preceeding element names an object which is one of
+        many objects of the same type. This way, property names form a
+        hierarchy of properties.  Here are some examples of property names:
+
+        <table>
+          <tr>
+            <td><tt>VirtualBox.version</tt></td>
+            <td><link to="IVirtualBox::version"/> property</td>
+          </tr>
+          <tr>
+            <td><tt>Machine.&lt;UUID&gt;.name</tt></td>
+            <td><link to="IMachine::name"/> property of the machine with the
+            given UUID</td>
+            </tr>
+        </table>
+
+        Most property names directly correspond to the properties of objects
+        (components) provided by the VirtualBox library and may be used to
+        track changes to these properties. However, there may be
+        pseudo-property names that don't correspond to any existing object's
+        property directly, as well as there may be object properties that
+        don't have a corresponding property name that is understood by this
+        method, and therefore changes to such properties cannot be
+        tracked. See individual object's property descrcriptions to get a
+        fully qualified property name that can be used with this method (if
+        any).
+
+        There is a special property mask @c "*" (i.e. a string consisting of a
+        single asterisk symbol) that can be used to match all properties.
+        Below are more examples of property masks:
+
+        <table>
+          <tr>
+            <td><tt>VirtualBox.*</tt></td>
+            <td>Track all properties of the VirtualBox object</td>
+          </tr>
+          <tr>
+            <td><tt>Machine.*.name</tt></td>
+            <td>Track changes to the <link to="IMachine::name"/> property of
+            all registered virtual machines</td>
+          </tr>
+        </table>
+
+      </desc>
+      <param name="what" type="wstring" dir="in">
+        <desc>Comma separated list of property masks.</desc>
+      </param>
+      <param name="timeout" type="unsigned long" dir="in">
+        <desc>
+          Wait timeout in milliseconds.
+          Specify -1 for an indefinite wait.
+        </desc>
+      </param>
+      <param name="changed" type="wstring" dir="out">
+        <desc>
+          Comma separated list of properties that have been changed and caused
+          this method to return to the caller.
+        </desc>
+      </param>
+      <param name="values" type="wstring" dir="out">
+        <desc>Reserved, not currently used.</desc>
+      </param>
     </method>
 
@@ -1801 +1902 @@
   <interface
      name="IInternalMachineControl" extends="$unknown"
-     uuid="83c4e00c-be0b-4c10-a48e-7bf832615f7b"
+     uuid="f33740bf-53b2-4519-b950-104260c6a189"
      internal="yes"
      wsmap="suppress"
@@ -1932 +2033 @@
       <param name="success" type="boolean" dir="in">
         <desc><tt>true</tt> to indicate success and <tt>false</tt> otherwise</desc>
+      </param>
+    </method>
+
+    <method name="adoptSavedState">
+      <desc>
+        Gets called by IConsole::adoptSavedState.
+      </desc>
+      <param name="savedStateFile" type="wstring" dir="in">
+        <desc>Path to the saved state file to adopt.</desc>
       </param>
     </method>
@@ -3380 +3490 @@
   <interface
      name="IConsole" extends="$unknown"
-     uuid="1DEA5C4B-0753-4193-B909-22330F64EC45"
+     uuid="d5a1cbda-f5d7-4824-9afe-d640c94c7dcf"
      wsmap="managed"
      >
@@ -3564 +3674 @@
       <param name="progress" type="IProgress" dir="return">
         <desc>Progress object to track the operation completion.</desc>
+      </param>
+    </method>
+
+    <method name="adoptSavedState">
+      <desc>
+        Associates the given saved state file to the virtual machine.
+
+        On success, the machine will go to the Saved state. Next time it is
+        powered up, it will be restored from the adopted saved state and
+        continue execution from the place where the saved state file was
+        created.
+
+        The specified saved state file path may be full or relative to the
+        folder the VM normally saves the state to (usually,
+        <link to="IMachine::snapshotFolder"/>).
+
+        <note>
+          It's a caller's responsibility to make sure the given saved state
+          file is compatible with the settings of this virtual machine that
+          represent its virtual hardware (memory size, hard disk configuration
+          etc.). If there is a mismatch, the behavior of the virtual machine
+          is undefined.
+        </note>
+      </desc>
+      <param name="savedStateFile" type="wstring" dir="in">
+        <desc>Path to the saved state file to adopt.</desc>
       </param>
     </method>
@@ -3785 +3921 @@
       <desc>
         This operation is similar to <link to="#discardSnapshot()"/> but
-        affects the current machine state. This means that the state stored
-        in the current snapshot will become a new current state, and
-        all current settings of the machine and changes stored in
-        differencing hard disks will be lost.
-
-        After this operation is successfully completed, new empty
-        differencing hard disks are created for all normal hard disks
-        of the machine.
-
-        If the current snapshot of the machine is an online snapshot,
-        the machine will go to the <link to="MachineState::Saved">
-          saved state</link>, so that the next time it is powered on,
-        the execution state will be restored from the current snapshot.
-
-        <note>The machine must not be running, otherwise the operation
-          will fail.</note>
-
-        <note>If the machine state is <link
-                                         to="MachineState::Saved">Saved</link> prior to this operation,
-          the saved state file will be implicitly discarded (as if <link
-                                                                      to="IConsole::discardSavedState()"/> were called).</note>
+        affects the current machine state. This means that the state stored in
+        the current snapshot will become a new current state, and all current
+        settings of the machine and changes stored in differencing hard disks
+        will be lost.
+
+        After this operation is successfully completed, new empty differencing
+        hard disks are created for all normal hard disks of the machine.
+
+        If the current snapshot of the machine is an online snapshot, the
+        machine will go to the <link to="MachineState::Saved"> saved
+        state</link>, so that the next time it is powered on, the execution
+        state will be restored from the current snapshot.
+
+        <note>
+          The machine must not be running, otherwise the operation will fail.
+        </note>
+
+        <note>
+          If the machine state is <link to="MachineState::Saved">Saved</link>
+          prior to this operation, the saved state file will be implicitly
+          discarded (as if <link to="IConsole::discardSavedState()"/> were
+          called).
+        </note>
 
       </desc>

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

@@ -127 +127 @@
     STDMETHOD(PowerButton)();
     STDMETHOD(SaveState) (IProgress **aProgress);
+    STDMETHOD(AdoptSavedState) (INPTR BSTR aSavedStateFile);
     STDMETHOD(DiscardSavedState)();
     STDMETHOD(GetDeviceActivity) (DeviceType_T aDeviceType,

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

@@ -758 +758 @@
     STDMETHOD(BeginSavingState) (IProgress *aProgress, BSTR *aStateFilePath);
     STDMETHOD(EndSavingState) (BOOL aSuccess);
+    STDMETHOD(AdoptSavedState) (INPTR BSTR aSavedStateFile);
     STDMETHOD(BeginTakingSnapshot) (IConsole *aInitiator,
                                     INPTR BSTR aName, INPTR BSTR aDescription,

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

@@ -173 +173 @@
                                   IProgress **aProgress);
     STDMETHOD(OpenExistingSession) (ISession *aSession, INPTR GUIDPARAM aMachineId);
-    STDMETHOD(RegisterCallback) (IVirtualBoxCallback *callback);
-    STDMETHOD(UnregisterCallback) (IVirtualBoxCallback *callback);
+
+    STDMETHOD(RegisterCallback) (IVirtualBoxCallback *aCallback);
+    STDMETHOD(UnregisterCallback) (IVirtualBoxCallback *aCallback);
+
+    STDMETHOD(WaitForPropertyChange) (INPTR BSTR aWhat, ULONG aTimeout,
+                                      BSTR *aChanged, BSTR *aValues);
 
     /* public methods only for internal purposes */