VirtualBox

Changeset 14934 in vbox for trunk/src/VBox/Main/idl


Ignore:
Timestamp:
Dec 3, 2008 10:39:39 AM (16 years ago)
Author:
vboxsync
Message:

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

  • IVirtualBox::getDVDImage
  • IVirtualBox::findDVDImage
  • IVirtualBox::openFloppyImage
  • IVirtualBox::getFloppyImage
  • IVirtualBox::findFloppyImage
  • IVirtualBox::getGuestOSType
  • IVirtualBox::createSharedFolder
  • IVirtualBox::removeSharedFolder
  • IVirtualBox::getNextExtraDataKey
  • IVirtualBox::getExtraData
  • IVirtualBox::setExtraData
  • IVirtualBox::openSession
  • IVirtualBox::openRemoteSession
  • IVirtualBox::openExistingSession
  • IVirtualBox::registerCallback
  • IVirtualBox::unregisterCallback
  • IVirtualBox::waitForPropertyChange
  • IVirtualBox::saveSettings
  • IVirtualBox::saveSettingsWithBackup
File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r14931 r14934  
    322322  </result>
    323323
     324  <result name="VBOX_E_XML_ERROR" value="0x80BB000A">
     325    <desc>
     326      Invalid XML found.
     327    </desc>
     328  </result>
     329
     330  <result name="VBOX_E_INVALID_SESSION_STATE" value="0x80BB000B">
     331    <desc>
     332      Current session state prohibits operation.
     333    </desc>
     334  </result>
     335
    324336  <!--
    325337    Note that src/VBox/Runtime/common/err/errmsgvboxcom.xsl will ignore
    … …  
    17871799        </note>
    17881800
    1789         <result name="VBOX_E_FILE_ERROR">
    1790           Image conflicts with another in the media registry.
     1801        <result name="VBOX_E_INVALID_OBJECT_STATE">
     1802          CD/DVD image already exists in the media registry.
    17911803        </result>
    17921804
    … …  
    18161828        installation, i.e. it must be previously opened by <link
    18171829        to="#openDVDImage()"/>, or mounted to some known virtual machine.
     1830
     1831        <result name="VBOX_E_OBJECT_NOT_FOUND">
     1832          No matching DVD image found in the media registry.
     1833        </result>
     1834
    18181835      </desc>
    18191836      <param name="id" type="uuid" dir="in">
    … …  
    18351852        The search is done by comparing the value of the @a location argument to
    18361853        the <link to="IMedium::location"/> attribute of each known CD/DVD image.
     1854
     1855        The requested location can be a path relative to the
     1856        <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
     1857        only a file name without any path is given, the
     1858        <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
     1859        folder</link> will be prepended to the file name before searching. Note
     1860        that on case sensitive file systems, a case sensitive comparison is
     1861        performed, otherwise the case in the file path is ignored.
     1862
     1863        <result name="VBOX_E_FILE_ERROR">
     1864          Invalid image file location.
     1865        </result>
     1866        <result name="VBOX_E_OBJECT_NOT_FOUND">
     1867          No matching DVD image found in the media registry.
     1868        </result>
     1869
     1870      </desc>
     1871      <param name="location" type="wstring" dir="in">
     1872        <desc>CD/DVD image file path to look for.</desc>
     1873      </param>
     1874      <param name="image" type="IDVDImage2" dir="return">
     1875        <desc>Found CD/DVD image object.</desc>
     1876      </param>
     1877    </method>
     1878
     1879    <method name="openFloppyImage">
     1880      <desc>
     1881        Opens a floppy image contained in the specified file of the supported
     1882        format and assigns it the given UUID.
     1883
     1884        After the image is successfully opened by this method, it gets
     1885        remembered by (known to) this VirtualBox installation and will be
     1886        accessible through <link to="#getFloppyImage()"/> and
     1887        <link to="#findFloppyImage()"/> methods. Remembered images are also
     1888        returned as part of the <link to="#floppyImages"/> array and can be
     1889        mounted to virtual machines. See IMedium for more details.
     1890
     1891        See <link to="IMedium::location"/> to get more details about the format
     1892        of the location string.
     1893
     1894        <result name="VBOX_E_FILE_ERROR">
     1895          Floppy image specified by @a location not accessible.
     1896        </result>
     1897        <result name="VBOX_E_INVALID_OBJECT_STATE">
     1898          Floppy image already exists in the media registry.
     1899        </result>
     1900
     1901        <note>
     1902          Currently, only raw floppy images are supported by VirtualBox.
     1903        </note>
     1904      </desc>
     1905      <param name="location" type="wstring" dir="in">
     1906        <desc>
     1907          Full path to the file that contains a valid floppy image.
     1908        </desc>
     1909      </param>
     1910      <param name="id" type="uuid" dir="in">
     1911        <desc>
     1912          UUID to assign to the given image file within this VirtualBox
     1913          installation. If an empty (null) UUID is specified, the system will
     1914          randomly generate a new UUID.
     1915        </desc>
     1916      </param>
     1917      <param name="image" type="IFloppyImage2" dir="return">
     1918        <desc>Opened floppy image object.</desc>
     1919      </param>
     1920    </method>
     1921
     1922    <method name="getFloppyImage">
     1923      <desc>
     1924        Returns a floppy image with the given UUID.
     1925
     1926        The image with the given UUID must be known to this VirtualBox
     1927        installation, i.e. it must be previously opened by <link
     1928        to="#openFloppyImage()"/>, or mounted to some known virtual machine.
     1929
     1930        <result name="VBOX_E_OBJECT_NOT_FOUND">
     1931          No matching floppy image found in the media registry.
     1932        </result>
     1933
     1934      </desc>
     1935      <param name="id" type="uuid" dir="in">
     1936        <desc>UUID of the image to look for.</desc>
     1937      </param>
     1938      <param name="image" type="IFloppyImage2" dir="return">
     1939        <desc>Found floppy image object.</desc>
     1940      </param>
     1941    </method>
     1942
     1943    <method name="findFloppyImage">
     1944      <desc>
     1945        Returns a floppy image with the given image location.
     1946
     1947        The image with the given UUID must be known to this VirtualBox
     1948        installation, i.e. it must be previously opened by <link
     1949        to="#openFloppyImage()"/>, or mounted to some known virtual machine.
     1950
     1951        The search is done by comparing the value of the @a location argument to
     1952        the <link to="IMedium::location"/> attribute of each known floppy image.
    18371953
    18381954        The requested location can be a path relative to the
    … …  
    18431959        that on case sensitive file systems, a case sensitive comparison is
    18441960        performed, otherwise the case of symbols in the file path is ignored.
    1845       </desc>
    1846       <param name="location" type="wstring" dir="in">
    1847         <desc>CD/DVD image file path to look for.</desc>
    1848       </param>
    1849       <param name="image" type="IDVDImage2" dir="return">
    1850         <desc>Found CD/DVD image object.</desc>
    1851       </param>
    1852     </method>
    1853 
    1854     <method name="openFloppyImage">
    1855       <desc>
    1856         Opens a floppy image contained in the specified file of the supported
    1857         format and assigns it the given UUID.
    1858 
    1859         After the image is successfully opened by this method, it gets
    1860         remembered by (known to) this VirtualBox installation and will be
    1861         accessible through <link to="#getFloppyImage()"/> and
    1862         <link to="#findFloppyImage()"/> methods. Remembered images are also
    1863         returned as part of the <link to="#floppyImages"/> array and can be
    1864         mounted to virtual machines. See IMedium for more details.
    1865 
    1866         See <link to="IMedium::location"/> to get more details about the format
    1867         of the location string.
    1868 
    1869         <note>
    1870           Currently, only raw floppy images are supported by VirtualBox.
    1871         </note>
    1872       </desc>
    1873       <param name="location" type="wstring" dir="in">
    1874         <desc>
    1875           Full path to the file that contains a valid floppy image.
    1876         </desc>
    1877       </param>
    1878       <param name="id" type="uuid" dir="in">
    1879         <desc>
    1880           UUID to assign to the given image file within this VirtualBox
    1881           installation. If an empty (null) UUID is specified, the system will
    1882           randomly generate a new UUID.
    1883         </desc>
    1884       </param>
    1885       <param name="image" type="IFloppyImage2" dir="return">
    1886         <desc>Opened floppy image object.</desc>
    1887       </param>
    1888     </method>
    1889 
    1890     <method name="getFloppyImage">
    1891       <desc>
    1892         Returns a floppy image with the given UUID.
    1893 
    1894         The image with the given UUID must be known to this VirtualBox
    1895         installation, i.e. it must be previously opened by <link
    1896         to="#openFloppyImage()"/>, or mounted to some known virtual machine.
    1897       </desc>
    1898       <param name="id" type="uuid" dir="in">
    1899         <desc>UUID of the image to look for.</desc>
    1900       </param>
    1901       <param name="image" type="IFloppyImage2" dir="return">
    1902         <desc>Found floppy image object.</desc>
    1903       </param>
    1904     </method>
    1905 
    1906     <method name="findFloppyImage">
    1907       <desc>
    1908         Returns a floppy image with the given image location.
    1909 
    1910         The image with the given UUID must be known to this VirtualBox
    1911         installation, i.e. it must be previously opened by <link
    1912         to="#openFloppyImage()"/>, or mounted to some known virtual machine.
    1913 
    1914         The search is done by comparing the value of the @a location argument to
    1915         the <link to="IMedium::location"/> attribute of each known floppy image.
    1916 
    1917         The requested location can be a path relative to the
    1918         <link to="IVirtualBox::homeFolder">VirtualBox home folder</link>. If
    1919         only a file name without any path is given, the
    1920         <link to="ISystemProperties::defaultHardDiskFolder"> default hard disk
    1921         folder</link> will be prepended to the file name before searching. Note
    1922         that on case sensitive file systems, a case sensitive comparison is
    1923         performed, otherwise the case of symbols in the file path is ignored.
     1961
     1962        <result name="VBOX_E_FILE_ERROR">
     1963          Invalid image file location.
     1964        </result>
     1965        <result name="VBOX_E_OBJECT_NOT_FOUND">
     1966          No matching floppy image found in the media registry.
     1967        </result>
     1968
    19241969      </desc>
    19251970      <param name="location" type="wstring" dir="in">
    … …  
    19451990        <link to="IGuestOSType::id"/> attribute which contains an identifier of
    19461991        the guest OS this object describes.
     1992
     1993        <result name="E_INVALIDARG">
     1994          @a id is not a valid Guest OS type.
     1995        </result>
     1996
    19471997      </desc>
    19481998      <param name="id" type="wstring" dir="in">
    … …  
    19602010        folders and starts sharing it. Refer to the description of
    19612011        <link to="ISharedFolder"/> to read more about logical names.
     2012        <note>
     2013          In the current implementation, this operation is not
     2014          implemented.
     2015        </note>
    19622016      </desc>
    19632017      <param name="name" type="wstring" dir="in">
    … …  
    19772031        created by <link to="#createSharedFolder"/> from the collection of
    19782032        shared folders and stops sharing it.
     2033        <note>
     2034          In the current implementation, this operation is not
     2035          implemented.
     2036        </note>
    19792037      </desc>
    19802038      <param name="name" type="wstring" dir="in">
    … …  
    19922050        nextKey (if there is any). @a nextValue is an optional parameter and
    19932051        if supplied, the next key's value is returned in it.
     2052
     2053        <result name="VBOX_E_OBJECT_NOT_FOUND">
     2054          Extra data @a key not found.
     2055        </result>
     2056
    19942057      </desc>
    19952058      <param name="key" type="wstring" dir="in">
    … …  
    20102073        If the requested data @a key does not exist, this function will
    20112074        succeed and return @c NULL in the @a value argument.
     2075
     2076        <result name="VBOX_E_FILE_ERROR">
     2077          Settings file not accessible.
     2078        </result>
     2079        <result name="VBOX_E_XML_ERROR">
     2080          Could not parse the settings file.
     2081        </result>
     2082
    20122083      </desc>
    20132084      <param name="key" type="wstring" dir="in">
    … …  
    20392110          change.
    20402111        </note>
     2112
     2113        <result name="VBOX_E_FILE_ERROR">
     2114          Settings file not accessible.
     2115        </result>
     2116        <result name="VBOX_E_XML_ERROR">
     2117          Could not parse the settings file.
     2118        </result>
     2119        <result name="E_ACCESSDENIED">
     2120          Modification request refused.
     2121        </result>
     2122
    20412123      </desc>
    20422124      <param name="key" type="wstring" dir="in">
    … …  
    20992181        <li>Close the session by calling <link to="ISession::close()"/>.</li>
    21002182        </ol>
     2183
     2184        <result name="E_UNEXPECTED">
     2185          Virtual machine not registered.
     2186        </result>
     2187        <result name="E_ACCESSDENIED">
     2188          Process not started by OpenRemoteSession.
     2189        </result>
     2190        <result name="VBOX_E_INVALID_OBJECT_STATE">
     2191          Session already open or being opened.
     2192        </result>
     2193        <result name="VBOX_E_VM_ERROR">
     2194          Failed to assign machine to session.
     2195        </result>
     2196
    21012197      </desc>
    21022198      <param name="session" type="ISession" dir="in">
    … …  
    21272223        that such prevent conflicting changes, one cannot open a remote session
    21282224        for a VM that already has another open session (direct or remote), or
    2129         is currently in the process of opening one (see <link to="IMachine::sessionState"/>).
     2225        is currently in the process of opening one (see <link
     2226          to="IMachine::sessionState"/>).
    21302227
    21312228        While the remote session still provides some level of control over the
    … …  
    21742271
    21752272        <see>openExistingSession</see>
     2273
     2274        <result name="E_UNEXPECTED">
     2275          Virtual machine not registered.
     2276        </result>
     2277        <result name="E_INVALIDARG">
     2278          Invalid session type @a type.
     2279        </result>
     2280        <result name="VBOX_E_OBJECT_NOT_FOUND">
     2281          No machine matching @a machineId found.
     2282        </result>
     2283        <result name="VBOX_E_INVALID_OBJECT_STATE">
     2284          Session already open or being opened.
     2285        </result>
     2286        <result name="VBOX_E_IPRT_ERROR">
     2287          Launching process for machine failed.
     2288        </result>
     2289        <result name="VBOX_E_VM_ERROR">
     2290          Failed to assign machine to session.
     2291        </result>
     2292
    21762293      </desc>
    21772294      <param name="session" type="ISession" dir="in">
    … …  
    22172334          doesn't have an open direct session.
    22182335        </note>
     2336
     2337        <result name="E_UNEXPECTED">
     2338          Virtual machine not registered.
     2339        </result>
     2340        <result name="VBOX_E_OBJECT_NOT_FOUND">
     2341          No machine matching @a machineId found.
     2342        </result>
     2343        <result name="VBOX_E_INVALID_OBJECT_STATE">
     2344          Session already open or being opened.
     2345        </result>
     2346        <result name="VBOX_E_INVALID_SESSION_STATE">
     2347          Direct session state not Open.
     2348        </result>
     2349        <result name="VBOX_E_VM_ERROR">
     2350          Failed to get console object from direct session or assign
     2351          machine to session.
     2352        </result>
    22192353
    22202354        <see>openRemoteSession</see>
    … …  
    22412375        callback object will be called by VirtualBox when an appropriate
    22422376        event occurs.
     2377
     2378        <result name="E_INVALIDARG">
     2379          Registering a @c NULL @a callback is pretty pointless, ain't it?
     2380          <!-- See if someone is actually reading this and objects :-) -->
     2381        </result>
     2382
    22432383      </desc>
    22442384      <param name="callback" type="IVirtualBoxCallback" dir="in">
    … …  
    22502390      <desc>
    22512391        Unregisters the previously registered global VirtualBox callback.
     2392
     2393        <result name="E_INVALIDARG">
     2394          Specified @a callback not registered.
     2395        </result>
     2396
    22522397      </desc>
    22532398      <param name="callback" type="IVirtualBoxCallback" dir="in">
    … …  
    23242469        </table>
    23252470
     2471        <note>
     2472          This function is not implemented in the current version of the
     2473          product.
     2474        </note>
    23262475      </desc>
    23272476      <param name="what" type="wstring" dir="in">
    … …  
    23552504        Normally, the global settings file is implicitly saved when a global
    23562505        setting is changed.
     2506
     2507        <result name="VBOX_E_FILE_ERROR">
     2508          Settings file not accessible.
     2509        </result>
     2510        <result name="VBOX_E_XML_ERROR">
     2511          Could not parse the settings file.
     2512        </result>
     2513
    23572514      </desc>
    23582515    </method>
    … …  
    23982555
    23992556        <see>settingsFileVersion</see>
     2557
     2558        <result name="VBOX_E_FILE_ERROR">
     2559          Settings file not accessible.
     2560        </result>
     2561        <result name="VBOX_E_XML_ERROR">
     2562          Could not parse the settings file.
     2563        </result>
     2564        <result name="VBOX_E_IPRT_ERROR">
     2565          Could not copy the settings file.
     2566        </result>
     2567
    24002568      </desc>
    24012569      <param name="bakFileName" type="wstring" dir="return">
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette