Changeset 15050 in vbox for trunk

Timestamp:

Dec 5, 2008 3:38:31 PM (16 years ago)

Author:

vboxsync

Message:

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

• IMachine::setBootOrder
• IMachine::getBootOrder
• IMachine::attachHardDisk2
• IMachine::getHardDisk2
• IMachine::detachHardDisk2

Location:

trunk/src/VBox/Main

Files:

• MachineImpl.cpp (modified) (13 diffs)
• idl/VirtualBox.xidl (modified) (7 diffs)

trunk/src/VBox/Main/MachineImpl.cpp

@@ -1808 +1808 @@
 
     if (aDevice == DeviceType_USB)
-        return setError (E_FAIL,
-            tr ("Booting from USB devices is not currently supported"));
+        return setError (E_NOTIMPL,
+            tr ("Booting from USB device is currently not supported"));
 
     AutoCaller autoCaller (this);
@@ -1865 +1865 @@
     {
         if (aChannel < 0 || aChannel > 1)
-            return setError (E_FAIL,
+            return setError (E_INVALIDARG,
                 tr ("Invalid IDE channel: %l (must be in range [0, 1])"),
                 aChannel);
@@ -1872 +1872 @@
         {
             if (aDevice < 0 || aDevice > 1)
-                return setError (E_FAIL,
+                return setError (E_INVALIDARG,
                     tr ("Invalid IDE device slot: %l (must be in range "
                         "[0, 1] for channel 0)"),
@@ -1882 +1882 @@
             /* Device slot 0 is reserved for the CD/DVD drive. */
             if (aDevice != 1)
-                return setError (E_FAIL,
+                return setError (E_INVALIDARG,
                     tr ("Invalid IDE device slot: %l (must be "
                         "1 for channel 1)"),
@@ -1904 +1904 @@
     /// @todo NEWMEDIA implicit machine registration
     if (!mData->mRegistered)
-        return setError (E_FAIL,
+        return setError (VBOX_E_INVALID_OBJECT_STATE,
             tr ("Cannot attach hard disks to an unregistered machine"));
 
@@ -1910 +1910 @@
 
     if (mData->mMachineState >= MachineState_Running)
-        return setError (E_FAIL,
+        return setError (VBOX_E_INVALID_VM_STATE,
             tr ("Invalid machine state: %d"), mData->mMachineState);
 
@@ -1923 +1923 @@
         ComObjPtr <HardDisk2> hd = (*it)->hardDisk();
         AutoReadLock hdLock (hd);
-        return setError (E_FAIL,
+        return setError (VBOX_E_OBJECT_IN_USE,
             tr ("Hard disk '%ls' is already attached to device slot %d on "
                 "channel %d of bus %d of this virtual machine"),
@@ -1946 +1946 @@
             mHDData->mAttachments.end())
     {
-        return setError (E_FAIL,
+        return setError (VBOX_E_OBJECT_IN_USE,
             tr ("Hard disk '%ls' is already attached to this virtual machine"),
             hd->locationFull().raw());
@@ -2189 +2189 @@
                                     LONG aDevice, IHardDisk2 **aHardDisk)
 {
-    if (aBus == StorageBus_Null)
-        return E_INVALIDARG;
+    CheckComArgExpr(aBus, aBus != StorageBus_Null);
+    CheckComArgOutPointerValid(aHardDisk);
 
     AutoCaller autoCaller (this);
@@ -2205 +2205 @@
 
     if (it == mHDData->mAttachments.end())
-        return setError (E_INVALIDARG,
+        return setError (VBOX_E_OBJECT_NOT_FOUND,
             tr ("No hard disk attached to device slot %d on channel %d of bus %d"),
             aDevice, aChannel, aBus);
@@ -2217 +2217 @@
                                        LONG aDevice)
 {
-    if (aBus == StorageBus_Null)
-        return E_INVALIDARG;
+    CheckComArgExpr(aBus, aBus != StorageBus_Null);
 
     AutoCaller autoCaller (this);
@@ -2231 +2230 @@
 
     if (mData->mMachineState >= MachineState_Running)
-        return setError (E_FAIL,
+        return setError (VBOX_E_INVALID_VM_STATE,
             tr ("Invalid machine state: %d"), mData->mMachineState);
 
@@ -2240 +2239 @@
 
     if (it == mHDData->mAttachments.end())
-        return setError (E_INVALIDARG,
+        return setError (VBOX_E_OBJECT_NOT_FOUND,
             tr ("No hard disk attached to device slot %d on channel %d of bus %d"),
             aDevice, aChannel, aBus);

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

@@ -3570 +3570 @@
 
         @todo setHardDiskBootOrder(), setNetworkBootOrder()
+
+        <result name="E_INVALIDARG">
+          Boot @a position out of range.
+        </result>
+        <result name="E_NOTIMPL">
+          Booting from USB @a device currently not supported.
+        </result>
+
       </desc>
       <param name="position" type="unsigned long" dir="in">
@@ -3599 +3607 @@
 
         @todo getHardDiskBootOrder(), getNetworkBootOrder()
-      </desc>
-      <param name="order" type="unsigned long" dir="in">
+
+        <result name="E_INVALIDARG">
+          Boot @a position out of range.
+        </result>
+
+      </desc>
+      <param name="position" type="unsigned long" dir="in">
         <desc>
           Position in the boot order (<tt>1</tt> to the total number of
@@ -3616 +3629 @@
     <method name="attachHardDisk2">
       <desc>
-        Attaches a virtual hard disk identified by the given UUID to a device
-        slot of the specified bus.
+        Attaches a virtual hard disk identified by the given UUID @a id
+        to a device slot of the specified bus.
 
         For the IDE bus, the @a channel parameter can be either @c 0 or @c 1, to
         specify the primary or secondary IDE controller, respectively. The
-        SATA bus supports 30 channels, so this parameter can be a number in
-        range from @c 0 to @c 29.
+        SATA bus supports 30 channels, so this parameter can be a number
+        ranging from @c 0 to @c 29.
 
         For the primary controller of the IDE bus, the @a device number can be
@@ -3629 +3642 @@
         always @c 1 because the master device is reserved for the CD-ROM drive.
 
-        For the SATA bus, the @a device parameter is not currently used and
-        must always be @c 0.
+        For the SATA bus, the @a device parameter is currently unused and
+        must be @c 0.
 
         The specified device slot must not have another disk attached to it, or
@@ -3645 +3658 @@
         <note>
           If the hard disk is being attached indirectly, a new differencing hard
-          disk will be implicitly created for it and attached instead. If the
+          disk will implicitly be created for it and attached instead. If the
           changes made to the machine settings (including this indirect
           attachment) are later cancelled using <link to="#discardSettings()"/>,
-          this implicitly created differencing hard disk will be implicitly
-          deleted.
-        </note>
+          this implicitly created differencing hard disk will implicitly
+          be deleted.
+        </note>
+
+        <result name="E_INVALIDARG">
+          SATA device, SATA channel, IDE channel or IDE slot out of range.
+        </result>
+        <result name="VBOX_E_INVALID_OBJECT_STATE">
+          Attempt to attach hard disk to an unregistered virtual machine.
+        </result>
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Invalid machine state.
+        </result>
+        <result name="VBOX_E_OBJECT_IN_USE">
+          Hard disk already attached to this or another virtual machine.
+        </result>
+
       </desc>
       <param name="id" type="uuid" dir="in">
@@ -3678 +3705 @@
         <link to="#attachHardDisk2()"/> call. See <link to="IHardDisk2"/> for
         more detailed information about attaching hard disks.
+
+        <result name="VBOX_E_OBJECT_NOT_FOUND">
+          No hard disk attached to given slot/bus.
+        </result>
+
       </desc>
       <param name="bus" type="StorageBus" dir="in">
@@ -3716 +3748 @@
           <link to="#saveSettings()"/>, if it is the desired action.
         </note>
+
+        <result name="VBOX_E_INVALID_VM_STATE">
+          Attempt to detach hard disk from a running virtual machine.
+        </result>
+        <result name="VBOX_E_OBJECT_NOT_FOUND">
+          No hard disk attached to given slot/bus.
+        </result>
+        <result name="VBOX_E_NOT_SUPPORTED">
+          Hard disk format does not support storage deletion.
+        </result>
 
       </desc>