Changeset 14858 in vbox for trunk/src/VBox

Timestamp:

Dec 1, 2008 1:56:37 PM (16 years ago)

Author:

vboxsync

Message:

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

• IVirtualBox::createMachine
• IVirtualBox::createLegacyMachine
• IVirtualBox::openMachine
• IVirtualBox::registerMachine
• IVirtualBox::getMachine
• IVirtualBox::findMachine
• IVirtualBox::unregisterMachine

Location:

trunk/src/VBox/Main

Files:

• MachineImpl.cpp (modified) (5 diffs)
• VirtualBoxImpl.cpp (modified) (3 diffs)
• idl/VirtualBox.xidl (modified) (5 diffs)

trunk/src/VBox/Main/MachineImpl.cpp

@@ -4159 +4159 @@
     {
         if (mData->mRegistered)
-            return setError (E_FAIL,
+            return setError (VBOX_E_INVALID_OBJECT_STATE,
                 tr ("The machine '%ls' with UUID {%s} is already registered"),
                 mUserData->mName.raw(),
@@ -4167 +4167 @@
     {
         if (mData->mMachineState == MachineState_Saved)
-            return setError (E_FAIL,
+            return setError (VBOX_E_INVALID_VM_STATE,
                 tr ("Cannot unregister the machine '%ls' because it "
                     "is in the Saved state"),
@@ -4176 +4176 @@
             snapshotCount = mData->mFirstSnapshot->descendantCount() + 1;
         if (snapshotCount)
-            return setError (E_FAIL,
+            return setError (VBOX_E_INVALID_OBJECT_STATE,
                 tr ("Cannot unregister the machine '%ls' because it "
                     "has %d snapshots"),
@@ -4182 +4182 @@
 
         if (mData->mSession.mState != SessionState_Closed)
-            return setError (E_FAIL,
+            return setError (VBOX_E_INVALID_OBJECT_STATE,
                 tr ("Cannot unregister the machine '%ls' because it has an "
                     "open session"),
@@ -4188 +4188 @@
 
         if (mHDData->mAttachments.size() != 0)
-            return setError (E_FAIL,
+            return setError (VBOX_E_INVALID_OBJECT_STATE,
                 tr ("Cannot unregister the machine '%ls' because it "
                     "has %d hard disks attached"),

trunk/src/VBox/Main/VirtualBoxImpl.cpp

@@ -962 +962 @@
          *  or opened by OpenMachine() or loaded during startup
          */
-        return setError (E_FAIL,
+        return setError (VBOX_E_INVALID_OBJECT_STATE,
             tr ("The machine named '%ls' is not created within this "
                 "VirtualBox instance"), name.raw());
@@ -1041 +1041 @@
     HRESULT rc = machine
         ? S_OK
-        : setError (E_INVALIDARG,
+        : setError (VBOX_E_FILE_ERROR,
             tr ("Could not find a registered machine named '%ls'"), aName);
 
@@ -2635 +2635 @@
     if (aSetError && !found)
     {
-        setError (E_INVALIDARG,
+        setError (VBOX_E_FILE_ERROR,
             tr ("Could not find a registered machine with UUID {%RTuuid}"),
             aId.raw());

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

@@ -1484 +1484 @@
 
         @deprecated Will be removed soon.
+        <result name="VBOX_E_FILE_ERROR">
+          Settings file name invalid, not found or sharing violation.
+        </result>
       </desc>
       <param name="settingsFile" type="wstring" dir="in">
@@ -1515 +1518 @@
         </note>
 
+        <result name="VBOX_E_INVALID_OBJECT_STATE">
+          Virtual machine was not created within this VirtualBox instance.
+        </result>
+
       </desc>
       <param name="machine" type="IMachine" dir="in"/>
@@ -1522 +1529 @@
       <desc>
         Attempts to find a virtual machine given its UUID.
-        To look up a machine by name, use <link to="IVirtualBox::findMachine" /> instead.
+        To look up a machine by name, use <link to="IVirtualBox::findMachine" />
+        instead.
+
+        <result name="VBOX_E_FILE_ERROR">
+          Could not find registered machine matching @a id.
+        </result>
+
       </desc>
       <param name="id" type="uuid" dir="in"/>
@@ -1531 +1544 @@
       <desc>
         Attempts to find a virtual machine given its name.
-        To look up a machine by UUID, use <link to="IVirtualBox::getMachine" /> instead.
+        To look up a machine by UUID, use <link to="IVirtualBox::getMachine" />
+        instead.
+
+        <result name="VBOX_E_FILE_ERROR">
+          Could not find registered machine matching @a name.
+        </result>
+
       </desc>
       <param name="name" type="wstring" dir="in"/>
@@ -1563 +1582 @@
           <b>any</b> method will return the "Object not ready" error.
         </note>
+
+        <result name="VBOX_E_FILE_ERROR">
+          Could not find registered machine matching @a id.
+        </result>
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Machine is in Saved state.
+        </result>
+        <result name="VBOX_E_INVALID_OBJECT_STATE">
+          Machine has snapshot or open session or hard disk attached.
+        </result>
 
       </desc>