Changeset 14778 in vbox for trunk/src/VBox

Timestamp:

Nov 28, 2008 2:02:01 PM (16 years ago)

Author:

vboxsync

Message:

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

• IConsole::reset
• IConsole::pause
• IConsole::resume
• IConsole::powerButton
• IConsole::sleepButton

Location:

trunk/src/VBox/Main

Files:

• ConsoleImpl.cpp (modified) (2 diffs)
• idl/VirtualBox.xidl (modified) (1 diff)

trunk/src/VBox/Main/ConsoleImpl.cpp

@@ -1688 +1688 @@
 
     if (mMachineState != MachineState_Running)
-        return setError (E_FAIL, tr ("Cannot send the sleep button event as it is "
-                                     "not running (machine state: %d)"),
-                         mMachineState);
+        return setError (VBOX_E_INVALID_VM_STATE,
+            tr ("Cannot send the sleep button event as it is "
+            "not running (machine state: %d)"), mMachineState);
 
     /* protect mpVM */
@@ -1707 +1707 @@
 
     HRESULT rc = VBOX_SUCCESS (vrc) ? S_OK :
-        setError (E_FAIL,
+        setError (VBOX_E_PDM_ERROR,
             tr ("Sending sleep button event failed (%Rrc)"), vrc);
 

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

@@ -4646 +4646 @@
 
     <method name="reset">
-      <desc>Resets the virtual machine.</desc>
+      <desc>Resets the virtual machine.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Running state.
+        </result>
+        <result name="VBOX_E_VM_ERROR">
+          Virtual machine error in reset operation.
+        </result>
+      </desc>
     </method>
 
     <method name="pause">
-      <desc>Pauses the virtual machine execution.</desc>
+      <desc>Pauses the virtual machine execution.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Running state.
+        </result>
+        <result name="VBOX_E_VM_ERROR">
+          Virtual machine error in suspend operation.
+        </result>
+      </desc>
     </method>
 
     <method name="resume">
-      <desc>Resumes the virtual machine execution.</desc>
+      <desc>Resumes the virtual machine execution.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Paused state.
+        </result>
+        <result name="VBOX_E_VM_ERROR">
+          Virtual machine error in resume operation.
+        </result>
+      </desc>
     </method>
 
     <method name="powerButton">
-      <desc>Send the ACPI power button event to the guest.</desc>
+      <desc>Send the ACPI power button event to the guest.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Running state.
+        </result>
+        <result name="VBOX_E_PDM_ERROR">
+          Controlled power off failed.
+        </result>
+      </desc>
     </method>
 
     <method name="sleepButton">
-      <desc>Send the ACPI sleep button event to the guest.</desc>
+      <desc>Sends the ACPI sleep button event to the guest.
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Virtual machine not in Running state.
+        </result>
+        <result name="VBOX_E_PDM_ERROR">
+          Sending sleep button event failed.
+        </result>
+      </desc>
     </method>
 
     <method name="getPowerButtonHandled">
-      <desc>Check if the last power button event was handled by guest.</desc>
+      <desc>Checks if the last power button event was handled by guest.
+      </desc>
       <param name="handled" type="boolean" dir="return"/>
     </method>
 
     <method name="getGuestEnteredACPIMode">
-      <desc>Check if the guest entered the ACPI mode G0 (working) or
+      <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>