Changeset 14786 in vbox for trunk/src/VBox

Timestamp:

Nov 28, 2008 3:17:42 PM (16 years ago)

Author:

vboxsync

Message:

#3285: Improve error handling API to include unique error numbers
Document

• IConsole::getPowerButtonHandled
• IConsole::getGuestEnteredACPIMode
• IConsole::saveState
• IConsole::adoptSavedState
• IConsole::discardSavedState

Location:

trunk/src/VBox/Main

Files:

• ConsoleImpl.cpp (modified) (4 diffs)
• idl/VirtualBox.xidl (modified) (7 diffs)

trunk/src/VBox/Main/ConsoleImpl.cpp

@@ -1630 +1630 @@
 
     HRESULT rc = VBOX_SUCCESS (vrc) ? S_OK :
-        setError (E_FAIL,
+        setError (VBOX_E_PDM_ERROR,
             tr ("Checking if the ACPI Power Button event was handled by the "
                 "guest OS failed (%Rrc)"), vrc);
@@ -1655 +1655 @@
 
     if (mMachineState != MachineState_Running)
-        return E_FAIL;
+        return setError (VBOX_E_INVALID_VM_STATE,
+            tr ("Cannot get guest ACPI mode as it is "
+            "not running (machine state: %d)"), mMachineState);
 
     /* protect mpVM */
@@ -1731 +1733 @@
         mMachineState != MachineState_Paused)
     {
-        return setError (E_FAIL,
+        return setError (VBOX_E_INVALID_VM_STATE,
             tr ("Cannot save the execution state as the machine "
                 "is not running (machine state: %d)"), mMachineState);
@@ -1798 +1800 @@
                 if (VBOX_FAILURE (vrc))
                 {
-                    rc = setError (E_FAIL,
+                    rc = setError (VBOX_E_FILE_ERROR,
                         tr ("Could not create a directory '%s' to save the state to (%Rrc)"),
                         dir.raw(), vrc);

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

@@ -4719 +4719 @@
     <method name="getPowerButtonHandled">
       <desc>Checks if the last power button event was handled by guest.
+        <result name="VBOX_E_PDM_ERROR">
+          Checking if the event was handled by the guest OS failed.
+        </result>
       </desc>
       <param name="handled" type="boolean" dir="return"/>
@@ -4726 +4729 @@
       <desc>Checks if the guest entered the ACPI mode G0 (working) or
         G1 (sleeping). If this method returns false, the guest will
-        most likely not respond to external ACPI events.</desc>
+        most likely not respond to external ACPI events.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Running state.
+        </result>
+      </desc>
       <param name="entered" type="boolean" dir="return"/>
     </method>
@@ -4751 +4758 @@
           settings (including runtime changes to the DVD drive, etc.).
           Together with the impossibility to change any VM settings when it is
-          in the Saved state, this guarantees the adequate hardware
+          in the Saved state, this guarantees adequate hardware
           configuration of the machine when it is restored from the saved
           state file.
@@ -4760 +4767 @@
           the operation will fail.
         </note>
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine state neither Running nor Paused.
+        </result>
+        <result name="VBOX_E_FILE_ERROR">
+          Failed to create directory for saved state file.
+        </result>
 
         <see><link to="#takeSnapshot"/></see>
@@ -4777 +4790 @@
         created.
 
-        The specified saved state file path may be full or relative to the
+        The specified saved state file path may be absolute or relative to the
         folder the VM normally saves the state to (usually,
         <link to="IMachine::snapshotFolder"/>).
@@ -4788 +4801 @@
           is undefined.
         </note>
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine state neither PoweredOff nor Aborted.
+        </result>
       </desc>
       <param name="savedStateFile" type="wstring" dir="in">
@@ -4803 +4819 @@
           the machine without doing a proper shutdown in the guest OS.
         </note>
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in state Saved.
+        </result>
       </desc>
     </method>