Changeset 31568 in vbox for trunk/src/VBox/Main

Timestamp:

Aug 11, 2010 1:35:59 PM (14 years ago)

Author:

vboxsync

Message:

Main: combine IVirtualBox::openHardDisk(), openDVDImage(), openFloppyImage() into new IVirtualBox::openMedium(); add new IMedium::setImageUUIDs() method for a rare use case of the old openHardDisk(); optimize client code now that code is mostly the same

Location:

trunk/src/VBox/Main

Files:

• ApplianceImplImport.cpp (modified) (1 diff)
• MediumImpl.cpp (modified) (9 diffs)
• VirtualBoxImpl.cpp (modified) (4 diffs)
• idl/VirtualBox.xidl (modified) (10 diffs)
• include/MediumImpl.h (modified) (3 diffs)
• include/VirtualBoxImpl.h (modified) (1 diff)
• testcase/tstVBoxAPILinux.cpp (modified) (1 diff)

trunk/src/VBox/Main/ApplianceImplImport.cpp

@@ -1342 +1342 @@
 
             // First open the existing disk image
-            rc = mVirtualBox->OpenHardDisk(Bstr(strSrcFilePath),
-                                           AccessMode_ReadOnly,
-                                           false,
-                                           NULL,
-                                           false,
-                                           NULL,
-                                           pSourceHD.asOutParam());
+            rc = mVirtualBox->OpenMedium(Bstr(strSrcFilePath),
+                                         DeviceType_HardDisk,
+                                         AccessMode_ReadOnly,
+                                         pSourceHD.asOutParam());
             if (FAILED(rc)) DebugBreakThrow(rc);
             fSourceHdNeedsClosing = true;

trunk/src/VBox/Main/MediumImpl.cpp

@@ -97 +97 @@
           hddOpenMode(OpenReadWrite),
           autoReset(false),
-          setImageId(false),
-          setParentId(false),
           hostDrive(false),
           implicit(false),
@@ -143 +141 @@
 
     /** the following members are invalid after changing UUID on open */
-    bool setImageId : 1;
-    bool setParentId : 1;
-    const Guid imageId;
-    const Guid parentId;
+    const Guid uuidImage;
+    const Guid uuidParentImage;
 
     bool hostDrive : 1;
@@ -824 +820 @@
  * @param enOpenMode    Whether to open the medium read/write or read-only.
  * @param aDeviceType   Device type of medium.
- * @param aSetImageId   Whether to set the medium UUID or not.
- * @param aImageId      New medium UUID if @aSetId is true. Empty string means
- *                      create a new UUID, and a zero UUID is invalid.
- * @param aSetParentId  Whether to set the parent UUID or not.
- * @param aParentId     New parent UUID if @aSetParentId is true. Empty string
- *                      means create a new UUID, and a zero UUID is valid.
  */
 HRESULT Medium::init(VirtualBox *aVirtualBox,
                      const Utf8Str &aLocation,
                      HDDOpenMode enOpenMode,
-                     DeviceType_T aDeviceType,
-                     BOOL aSetImageId,
-                     const Guid &aImageId,
-                     BOOL aSetParentId,
-                     const Guid &aParentId)
+                     DeviceType_T aDeviceType)
 {
     AssertReturn(aVirtualBox, E_INVALIDARG);
@@ -870 +856 @@
     if (FAILED(rc)) return rc;
 
-    /* save the new uuid values, will be used by queryInfo() */
-    m->setImageId = !!aSetImageId;
-    unconst(m->imageId) = aImageId;
-    m->setParentId = !!aSetParentId;
-    unconst(m->parentId) = aParentId;
-
     /* get all the information about the medium from the storage unit */
-    rc = queryInfo();
+    rc = queryInfo(false /* fSetImageId */, false /* fSetParentId */);
 
     if (SUCCEEDED(rc))
@@ -1655 +1635 @@
 }
 
+STDMETHODIMP Medium::SetIDs(BOOL aSetImageId,
+                            IN_BSTR aImageId,
+                            BOOL aSetParentId,
+                            IN_BSTR aParentId)
+{
+    AutoCaller autoCaller(this);
+    if (FAILED(autoCaller.rc())) return autoCaller.rc();
+
+    AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
+
+    Guid imageId, parentId;
+    if (aSetImageId)
+    {
+        imageId = Guid(aImageId);
+        if (imageId.isEmpty())
+            return setError(E_INVALIDARG, tr("Argument %s is empty"), "aImageId");
+    }
+    if (aSetParentId)
+        parentId = Guid(aParentId);
+
+    unconst(m->uuidImage) = imageId;
+    unconst(m->uuidParentImage) = parentId;
+
+    HRESULT rc = queryInfo(!!aSetImageId /* fSetImageId */,
+                           !!aSetParentId /* fSetParentId */);
+
+    return rc;
+}
+
 STDMETHODIMP Medium::RefreshState(MediumState_T *aState)
 {
@@ -1673 +1682 @@
         case MediumState_LockedRead:
         {
-            rc = queryInfo();
+            rc = queryInfo(false /* fSetImageId */, false /* fSetParentId */);
             break;
         }
@@ -3437 +3446 @@
  *       for the first time). Locks mParent for reading. Locks this object for
  *       writing.
- */
-HRESULT Medium::queryInfo()
+ *
+ * @param fSetImageId Whether to reset the UUID contained in the image file to the UUID in the medium instance data (see SetIDs())
+ * @param fSetParentId Whether to reset the parent UUID contained in the image file to the parent UUID in the medium instance data (see SetIDs())
+ * @return
+ */
+HRESULT Medium::queryInfo(bool fSetImageId, bool fSetParentId)
 {
     AutoWriteLock alock(this COMMA_LOCKVAL_SRC_POS);
@@ -3550 +3563 @@
                 /* Modify the UUIDs if necessary. The associated fields are
                  * not modified by other code, so no need to copy. */
-                if (m->setImageId)
+                if (fSetImageId)
                 {
-                    vrc = VDSetUuid(hdd, 0, m->imageId);
+                    vrc = VDSetUuid(hdd, 0, m->uuidImage);
                     ComAssertRCThrow(vrc, E_FAIL);
                 }
-                if (m->setParentId)
+                if (fSetParentId)
                 {
-                    vrc = VDSetParentUuid(hdd, 0, m->parentId);
+                    vrc = VDSetParentUuid(hdd, 0, m->uuidParentImage);
                     ComAssertRCThrow(vrc, E_FAIL);
                 }
                 /* zap the information, these are no long-term members */
-                m->setImageId = false;
-                unconst(m->imageId).clear();
-                m->setParentId = false;
-                unconst(m->parentId).clear();
+                unconst(m->uuidImage).clear();
+                unconst(m->uuidParentImage).clear();
 
                 /* check the UUID */
@@ -3603 +3614 @@
                 if (isImport)
                 {
-                    if (m->setImageId)
-                        mediumId = m->imageId;
+                    if (fSetImageId)
+                        mediumId = m->uuidImage;
                     else
                         mediumId.create();

trunk/src/VBox/Main/VirtualBoxImpl.cpp

@@ -1404 +1404 @@
 }
 
-STDMETHODIMP VirtualBox::OpenHardDisk(IN_BSTR aLocation,
-                                      AccessMode_T accessMode,
-                                      BOOL aSetImageId,
-                                      IN_BSTR aImageId,
-                                      BOOL aSetParentId,
-                                      IN_BSTR aParentId,
-                                      IMedium **aHardDisk)
+STDMETHODIMP VirtualBox::OpenMedium(IN_BSTR aLocation,
+                                    DeviceType_T deviceType,
+                                    AccessMode_T accessMode,
+                                    IMedium **aMedium)
 {
     CheckComArgStrNotEmptyOrNull(aLocation);
-    CheckComArgOutSafeArrayPointerValid(aHardDisk);
+    CheckComArgOutSafeArrayPointerValid(aMedium);
 
     AutoCaller autoCaller(this);
@@ -1419 +1416 @@
 
     /* we don't access non-const data members so no need to lock */
-
     HRESULT rc = E_FAIL;
 
-    ComObjPtr<Medium> hardDisk;
-    hardDisk.createObject();
-    Guid imageId, parentId;
-    if (aSetImageId)
-    {
-        imageId = Guid(aImageId);
-        if (imageId.isEmpty())
-            return setError(E_INVALIDARG, tr("Argument %s is empty"), "aImageId");
-    }
-    if (aSetParentId)
-        parentId = Guid(aParentId);
-    rc = hardDisk->init(this,
-                        aLocation,
-                        (accessMode == AccessMode_ReadWrite) ? Medium::OpenReadWrite : Medium::OpenReadOnly,
-                        DeviceType_HardDisk,
-                        aSetImageId,
-                        imageId,
-                        aSetParentId,
-                        parentId);
+    switch (deviceType)
+    {
+        case DeviceType_HardDisk:
+        case DeviceType_Floppy:
+        break;
+
+        case DeviceType_DVD:
+            accessMode = AccessMode_ReadOnly;
+        break;
+
+        default:
+            return setError(E_INVALIDARG, "Device type must be HardDisk, DVD or Floppy");
+    }
+
+    ComObjPtr<Medium> pMedium;
+    pMedium.createObject();
+    rc = pMedium->init(this,
+                       aLocation,
+                       (accessMode == AccessMode_ReadWrite) ? Medium::OpenReadWrite : Medium::OpenReadOnly,
+                       deviceType);
 
     if (SUCCEEDED(rc))
     {
-        bool fNeedsSaveSettings = false;
-        {
-            AutoWriteLock treeLock(getMediaTreeLockHandle() COMMA_LOCKVAL_SRC_POS);
-            rc = registerHardDisk(hardDisk, &fNeedsSaveSettings);
-        }
+        bool fNeedsGlobalSaveSettings = false;
+
+        AutoWriteLock treeLock(getMediaTreeLockHandle() COMMA_LOCKVAL_SRC_POS);
+
+        switch (deviceType)
+        {
+            case DeviceType_HardDisk:
+                rc = registerHardDisk(pMedium, &fNeedsGlobalSaveSettings);
+            break;
+
+            case DeviceType_DVD:
+            case DeviceType_Floppy:
+                rc = registerImage(pMedium, deviceType, &fNeedsGlobalSaveSettings);
+            break;
+        }
+
+        treeLock.release();
 
         /* Note that it's important to call uninit() on failure to register
@@ -1455 +1464 @@
 
         if (SUCCEEDED(rc))
-            hardDisk.queryInterfaceTo(aHardDisk);
+            pMedium.queryInterfaceTo(aMedium);
         else
-            hardDisk->uninit();
-
-        if (fNeedsSaveSettings)
+            pMedium->uninit();
+
+        if (fNeedsGlobalSaveSettings)
         {
             AutoWriteLock vboxlock(this COMMA_LOCKVAL_SRC_POS);
@@ -1508 +1517 @@
     /* the below will set *aHardDisk to NULL if hardDisk is null */
     pMedium.queryInterfaceTo(aMedium);
-
-    return rc;
-}
-
-/** @note Doesn't lock anything. */
-STDMETHODIMP VirtualBox::OpenDVDImage(IN_BSTR aLocation,
-                                      IN_BSTR aId,
-                                      IMedium **aDVDImage)
-{
-    CheckComArgStrNotEmptyOrNull(aLocation);
-    CheckComArgOutSafeArrayPointerValid(aDVDImage);
-
-    AutoCaller autoCaller(this);
-    if (FAILED(autoCaller.rc())) return autoCaller.rc();
-
-    HRESULT rc = VBOX_E_FILE_ERROR;
-
-    Guid id(aId);
-    /* generate an UUID if not specified */
-    if (id.isEmpty())
-        id.create();
-
-    ComObjPtr<Medium> image;
-    image.createObject();
-    rc = image->init(this,
-                     aLocation,
-                     Medium::OpenReadOnly,
-                     DeviceType_DVD,
-                     true /* aSetImageId */,
-                     id,
-                     false /* aSetParentId */,
-                     Guid());
-    if (SUCCEEDED(rc))
-    {
-        AutoWriteLock treeLock(getMediaTreeLockHandle() COMMA_LOCKVAL_SRC_POS);
-        bool fNeedsSaveSettings = false;
-        rc = registerImage(image, DeviceType_DVD, &fNeedsSaveSettings);
-        treeLock.release();
-
-        if (SUCCEEDED(rc))
-            image.queryInterfaceTo(aDVDImage);
-
-        if (fNeedsSaveSettings)
-        {
-            AutoWriteLock vboxlock(this COMMA_LOCKVAL_SRC_POS);
-            saveSettings();
-        }
-    }
-
-    return rc;
-}
-
-/** @note Doesn't lock anything. */
-STDMETHODIMP VirtualBox::OpenFloppyImage(IN_BSTR aLocation,
-                                         IN_BSTR aId,
-                                         IMedium **aFloppyImage)
-{
-    CheckComArgStrNotEmptyOrNull(aLocation);
-    CheckComArgOutSafeArrayPointerValid(aFloppyImage);
-
-    AutoCaller autoCaller(this);
-    if (FAILED(autoCaller.rc())) return autoCaller.rc();
-
-    HRESULT rc = VBOX_E_FILE_ERROR;
-
-    Guid id(aId);
-    /* generate an UUID if not specified */
-    if (id.isEmpty())
-        id.create();
-
-    ComObjPtr<Medium> image;
-    image.createObject();
-    rc = image->init(this,
-                     aLocation,
-                     Medium::OpenReadWrite,
-                     DeviceType_Floppy,
-                     true /* aSetImageId */,
-                     id,
-                     false /* aSetParentId */,
-                     Guid());
-    if (SUCCEEDED(rc))
-    {
-        AutoWriteLock treeLock(getMediaTreeLockHandle() COMMA_LOCKVAL_SRC_POS);
-        bool fNeedsSaveSettings = false;
-        rc = registerImage(image, DeviceType_Floppy, &fNeedsSaveSettings);
-        treeLock.release();
-
-        if (SUCCEEDED(rc))
-            image.queryInterfaceTo(aFloppyImage);
-
-        if (fNeedsSaveSettings)
-        {
-            AutoWriteLock vboxlock(this COMMA_LOCKVAL_SRC_POS);
-            saveSettings();
-        }
-    }
 
     return rc;

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

@@ -1806 +1806 @@
     </method>
 
-    <method name="openHardDisk">
-      <desc>
-        Opens a medium from an existing location, optionally replacing
-        the image UUID and/or parent UUID.
-
-        After the medium is successfully opened by this method, it gets
-        remembered by (known to) this VirtualBox installation and will be
-        accessible through the <link to="#findMedium"/> method. Remembered base media
-        are also returned as part of the <link to="#hardDisks"/> array and can
-        be attached to virtual machines. See <link to="IMedium" /> for more details.
-
-        If a differencing medium is to be opened by this method, the
+    <method name="openMedium">
+      <desc>
+        Opens a medium from an existing storage location.
+
+        Once a medium has been opened, VirtualBox saves the medium in a media
+        registry. Prior to VirtualBox 3.3, this registry had to be the global
+        media registry in the VirtualBox.xml file, which was shared between
+        all machines and made transporting machines from one host to another
+        difficult. Now you can optionally specify an <link to="IMachine" />
+        instance, in which case the medium will be remembered in that machine's
+        registry. This is the recommended procedure for machines created with
+        VirtualBox 3.3 or later. <i>(not yet implemented)</i>
+
+        Depending on the given device type, the file at the storage location
+        must be in one of the media formats understood by VirtualBox:
+
+        <ul>
+          <li>With a "HardDisk" device type, the file must be a hard disk image
+            in one of the formats supported by VirtualBox (see
+            <link to="ISystemProperties::mediumFormats" />).
+            After this method succeeds, if the medium is a base medium, it
+            will be added to the <link to="#hardDisks"/> array attribute. </li>
+          <li>With a "DVD" device type, the file must be an ISO 9960 CD/DVD image.
+            After this method succeeds, the medium will be added to the
+            <link to="#DVDImages"/> array attribute.</li>
+          <li>With a "Floppy" device type, the file must be an RAW floppy image.
+            After this method succeeds, the medium will be added to the
+            <link to="#floppyImages"/> array attribute.</li>
+        </ul>
+
+        After having been opened, the medium can be found by the <link to="#findMedium"/>
+        method and can be attached to virtual machines. See <link to="IMedium" /> for more details.
+
+        The UUID of the newly opened medium will either be retrieved from the
+        storage location, if the format supports it (e.g. for hard disk images),
+        or a new UUID will be randomly generated (e.g. for ISO and RAW files).
+        If for some reason you need to change the medium's UUID, use
+        <link to="IMedium::setIDs" />.
+
+        If a differencing hard disk medium is to be opened by this method, the
         operation will succeed only if its parent medium and all ancestors,
         if any, are already known to this VirtualBox installation (for example,
         were opened by this method before).
 
-        This method tries to guess the storage format of the specified medium
+        This method attempts to guess the storage format of the specified medium
         by reading medium data at the specified location.
 
-        If @a accessMode is ReadWrite (which it should be), the image is opened
-        for read/write access and must have according permissions, as VirtualBox
-        may actually write status information into the disk's metadata sections.
-
-        Note that write access is required for all typical image usage in VirtualBox,
+        If @a accessMode is ReadWrite (which it should be for hard disks and floppies),
+        the image is opened for read/write access and must have according permissions,
+        as VirtualBox may actually write status information into the disk's metadata
+        sections.
+
+        Note that write access is required for all typical hard disk usage in VirtualBox,
         since VirtualBox may need to write metadata such as a UUID into the image.
         The only exception is opening a source image temporarily for copying and
-        cloning when the image will quickly be closed again.
-
-        Note that the format of the location string is storage format specific.
-        See <link to="IMedium::location"/>, IMedium and
+        cloning (see <link to="IMedium::cloneTo" /> when the image will be closed
+        again soon.
+
+        The format of the location string is storage format specific. See
+        <link to="IMedium::location"/>, IMedium and
         <link to="ISystemProperties::defaultHardDiskFolder"/> for more details.
 
@@ -1848 +1878 @@
           Invalid medium storage format.
         </result>
-
+        <result name="VBOX_E_INVALID_OBJECT_STATE">
+          Medium has already been added to a media registry.
+        </result>
       </desc>
       <param name="location" type="wstring" dir="in">
@@ -1856 +1888 @@
         </desc>
       </param>
+      <param name="deviceType" type="DeviceType" dir="in">
+        <desc>
+          Must be one of "HardDisk", "DVD" or "Floppy".
+        </desc>
+      </param>
       <param name="accessMode" type="AccessMode" dir="in">
-          <desc>
-              Determines whether to open the image in read/write or read-only mode.
-          </desc>
-      </param>
-      <param name="setImageId" type="boolean" dir="in">
-          <desc>
-              Select whether a new image UUID is set or not.
-          </desc>
-      </param>
-      <param name="imageId" type="uuid" mod="string" dir="in">
-          <desc>
-              New UUID for the image. If an empty string is passed, then a new
-              UUID is automatically created. Specifying a zero UUIDs is not valid.
-          </desc>
-      </param>
-      <param name="setParentId" type="boolean" dir="in">
-          <desc>
-              Select whether a new parent UUID is set or not.
-          </desc>
-      </param>
-      <param name="parentId" type="uuid" mod="string" dir="in">
-          <desc>
-              New parent UUID for the image. If an empty string is passed, then a
-              new UUID is automatically created, provided @a setParentId is
-              @c true. A zero UUID is valid.
-          </desc>
+        <desc>Whether to open the image in read/write or read-only mode. For
+        a "DVD" device type, this is ignored and read-only mode is always assumed.</desc>
       </param>
       <param name="medium" type="IMedium" dir="return">
@@ -1896 +1909 @@
         The given medium must be known to this VirtualBox installation, i.e.
         it must be previously created by <link to="#createHardDisk"/> or opened
-        by <link to="#openHardDisk"/> or <link to="#openDVDImage" /> or
-        <link to="#openFloppyImage" />.
+        by <link to="#openMedium"/>.
 
         The search is done by comparing the value of the @a location argument to
@@ -1924 +1936 @@
       <param name="medium" type="IMedium" dir="return">
         <desc>Medium object, if found.</desc>
-      </param>
-    </method>
-
-    <method name="openDVDImage">
-      <desc>
-        Opens a CD/DVD image contained in the specified file of the supported
-        format and assigns it the given UUID.
-
-        After the image is successfully opened by this method, it gets
-        remembered by (known to) this VirtualBox installation and will be
-        accessible through the <link to="#findMedium"/> method.
-        Remembered images are also returned as part of the <link to="#DVDImages"/>
-        array and can be mounted to virtual machines. See <link to="IMedium" />
-        for more details.
-
-        See <link to="IMedium::location"/> to get more details about the format
-        of the location string.
-
-        <note>
-          Currently only ISO 9960 CD/DVD images are supported by VirtualBox.
-        </note>
-
-        <result name="VBOX_E_FILE_ERROR">
-          Invalid CD/DVD image file location or could not find the CD/DVD
-          image at the specified location.
-        </result>
-        <result name="VBOX_E_INVALID_OBJECT_STATE">
-          CD/DVD image already exists in the media registry.
-        </result>
-
-      </desc>
-      <param name="location" type="wstring" dir="in">
-        <desc>
-          Full path to the file that contains a valid CD/DVD image.
-        </desc>
-      </param>
-      <param name="id" type="uuid" mod="string" dir="in">
-        <desc>
-          UUID to assign to the given image within this VirtualBox installation.
-          If an empty (@c null) UUID is specified, the system will randomly
-          generate a new UUID.
-        </desc>
-      </param>
-      <param name="image" type="IMedium" dir="return">
-        <desc>Opened CD/DVD image object.</desc>
-      </param>
-    </method>
-
-    <method name="openFloppyImage">
-      <desc>
-        Opens a floppy image contained in the specified file of the supported
-        format and assigns it the given UUID.
-
-        After the image is successfully opened by this method, it gets
-        remembered by (known to) this VirtualBox installation and will be
-        accessible through the <link to="#findMedium"/> method.
-        Remembered images are also returned as part of the <link to="#floppyImages"/>
-        array and can be mounted to virtual machines. See <link to="IMedium" />
-        for more details.
-
-        See <link to="IMedium::location"/> to get more details about the format
-        of the location string.
-
-        <result name="VBOX_E_FILE_ERROR">
-          Invalid floppy image file location or could not find the floppy
-          image at the specified location.
-        </result>
-        <result name="VBOX_E_INVALID_OBJECT_STATE">
-          Floppy image already exists in the media registry.
-        </result>
-
-        <note>
-          Currently, only raw floppy images are supported by VirtualBox.
-        </note>
-      </desc>
-      <param name="location" type="wstring" dir="in">
-        <desc>
-          Full path to the file that contains a valid floppy image.
-        </desc>
-      </param>
-      <param name="id" type="uuid" mod="string" dir="in">
-        <desc>
-          UUID to assign to the given image file within this VirtualBox
-          installation. If an empty (@c null) UUID is specified, the system will
-          randomly generate a new UUID.
-        </desc>
-      </param>
-      <param name="image" type="IMedium" dir="return">
-        <desc>Opened floppy image object.</desc>
       </param>
     </method>
@@ -7342 +7265 @@
           IMedium,
           <link to="IVirtualBox::createHardDisk"/>,
-          <link to="IVirtualBox::openHardDisk"/>,
+          <link to="IVirtualBox::openMedium"/>,
           <link to="IMedium::location"/>
         </see>
@@ -8554 +8477 @@
       </ul>
 
-      Existing media are opened using the following methods, depending on the
-      media type:
-      <ul>
-        <li><link to="IVirtualBox::openHardDisk"/></li>
-        <li><link to="IVirtualBox::openDVDImage"/></li>
-        <li><link to="IVirtualBox::openFloppyImage"/></li>
-      </ul>
-
-      New hard disk media can be created with the VirtualBox API using the
+      Existing media are opened using <link to="IVirtualBox::openMedium"/>;
+      new hard disk media can be created with the VirtualBox API using the
       <link to="IVirtualBox::createHardDisk"/> method.
 
@@ -8653 +8569 @@
       New base hard disks are created using
       <link to="IVirtualBox::createHardDisk"/>. Existing hard disks are
-      opened using <link to="IVirtualBox::openHardDisk"/>. Differencing hard
+      opened using <link to="IVirtualBox::openMedium"/>. Differencing hard
       disks are usually implicitly created by VirtualBox when needed but may
       also be created explicitly using <link to="#createDiffStorage"/>.
@@ -9169 +9085 @@
     </attribute>
 
+    <method name="setIDs">
+      <desc>
+        Changes the UUID and parent UUID for a hard disk medium.
+      </desc>
+      <param name="setImageId" type="boolean" dir="in">
+        <desc>
+          Select whether a new image UUID is set or not.
+        </desc>
+      </param>
+      <param name="imageId" type="uuid" mod="string" dir="in">
+        <desc>
+          New UUID for the image. If an empty string is passed, then a new
+          UUID is automatically created, provided that @a setImageId is @c true.
+          Specifying a zero UUID is not allowed.
+        </desc>
+      </param>
+      <param name="setParentId" type="boolean" dir="in">
+        <desc>
+          Select whether a new parent UUID is set or not.
+        </desc>
+      </param>
+      <param name="parentId" type="uuid" mod="string" dir="in">
+        <desc>
+          New parent UUID for the image. If an empty string is passed, then a
+          new UUID is automatically created, provided @a setParentId is
+          @c true. A zero UUID is valid.
+        </desc>
+      </param>
+        <result name="E_INVALIDARG">
+          Invalid parameter combination.
+        </result>
+      <result name="VBOX_E_NOT_SUPPORTED">
+        Medium is not a hard disk medium.
+      </result>
+    </method>
+
     <method name="refreshState">
       <desc>
@@ -9397 +9349 @@
         operation will fail.
 
-        When the medium is successfully closed, it gets removed from
-        the list of remembered media, but its storage unit is not
-        deleted. In particular, this means that this medium can be
-        later opened again using the <link
-        to="IVirtualBox::openHardDisk"/> call.
+        When the medium is successfully closed, it is removed from
+        the list of registered media, but its storage unit is not
+        deleted. In particular, this means that this medium can
+        later be opened again using the <link to="IVirtualBox::openMedium"/>
+        call.
 
         Note that after this method successfully returns, the given medium

trunk/src/VBox/Main/include/MediumImpl.h

@@ -79 +79 @@
                  const Utf8Str &aLocation,
                  HDDOpenMode enOpenMode,
-                 DeviceType_T aDeviceType,
-                 BOOL aSetImageId,
-                 const Guid &aImageId,
-                 BOOL aSetParentId,
-                 const Guid &aParentId);
+                 DeviceType_T aDeviceType);
 
     // initializer used when loading settings
@@ -129 +125 @@
 
     // IMedium methods
+    STDMETHOD(SetIDs)(BOOL aSetImageId, IN_BSTR aImageId,
+                      BOOL aSetParentId, IN_BSTR aParentId);
     STDMETHOD(RefreshState)(MediumState_T *aState);
     STDMETHOD(GetSnapshotIds)(IN_BSTR aMachineId,
@@ -245 +243 @@
 private:
 
-    HRESULT queryInfo();
+    HRESULT queryInfo(bool fSetImageId, bool fSetParentId);
 
     HRESULT canClose();

trunk/src/VBox/Main/include/VirtualBoxImpl.h

@@ -132 +132 @@
     STDMETHOD(CreateHardDisk)(IN_BSTR aFormat, IN_BSTR aLocation,
                                IMedium **aHardDisk);
-    STDMETHOD(OpenHardDisk) (IN_BSTR aLocation, AccessMode_T accessMode,
-                             BOOL aSetImageId, IN_BSTR aImageId,
-                             BOOL aSetParentId, IN_BSTR aParentId,
-                             IMedium **aHardDisk);
-    STDMETHOD(FindMedium) (IN_BSTR aLocation, DeviceType_T deviceType, IMedium **aMedium);
-
-    STDMETHOD(OpenDVDImage) (IN_BSTR aLocation, IN_BSTR aId,
-                             IMedium **aDVDImage);
-    STDMETHOD(OpenFloppyImage) (IN_BSTR aLocation, IN_BSTR aId,
-                                IMedium **aFloppyImage);
+    STDMETHOD(OpenMedium)(IN_BSTR aLocation,
+                          DeviceType_T deviceType,
+                          AccessMode_T accessMode,
+                          IMedium **aMedium);
+    STDMETHOD(FindMedium)(IN_BSTR aLocation,
+                          DeviceType_T deviceType,
+                          IMedium **aMedium);
 
     STDMETHOD(GetGuestOSType) (IN_BSTR aId, IGuestOSType **aType);

trunk/src/VBox/Main/testcase/tstVBoxAPILinux.cpp

@@ -356 +356 @@
      */
     nsCOMPtr<IMedium> dvdImage;
-
-    rc = virtualBox->OpenDVDImage(NS_LITERAL_STRING("/home/vbox/isos/winnt4ger.iso").get(),
-                                  nsnull, /* NULL UUID, i.e. a new one will be created */
-                                  getter_AddRefs(dvdImage));
+    rc = virtualBox->OpenMedium(NS_LITERAL_STRING("/home/vbox/isos/winnt4ger.iso").get(),
+                                DeviceType_DVD,
+                                AccessMode_ReadOnly,
+                                getter_AddRefs(dvdImage));
     if (NS_FAILED(rc))
-    {
         printf("Error: could not open CD image! rc=%08X\n", rc);
-    }
     else
     {