Changeset 11444 in vbox for trunk/include/VBox

Timestamp:

Aug 15, 2008 2:33:02 PM (16 years ago)

Author:

vboxsync

Message:

Storage/VBoxHDD-new: introduced VD interfaces per image and per operation, completely unifying callback handling.

File:

• trunk/include/VBox/VBoxHDD-new.h (modified) (14 diffs)

trunk/include/VBox/VBoxHDD-new.h

@@ -237 +237 @@
     /** First valid interface. */
     VDINTERFACETYPE_FIRST = 0,
-    /** Interface to pass error message to upper layers. */
+    /** Interface to pass error message to upper layers. Per-disk. */
     VDINTERFACETYPE_ERROR = VDINTERFACETYPE_FIRST,
-    /** Interface for asynchronous I/O operations. */
+    /** Interface for asynchronous I/O operations. Per-disk. */
     VDINTERFACETYPE_ASYNCIO,
-    /** Interface for progress notification. */
+    /** Interface for progress notification. Per-operation. */
     VDINTERFACETYPE_PROGRESS,
-    /** Interface for configuration information. */
+    /** Interface for configuration information. Per-image. */
     VDINTERFACETYPE_CONFIG,
     /** invalid interface. */
@@ -274 +274 @@
 /**
  * Helper functions to handle interface lists.
+ *
+ * @note These interface lists are used consistently to pass per-disk,
+ * per-image and/or per-operation callbacks. Those three purposes are strictly
+ * separate. See the individual interface declarations for what context they
+ * apply to. The caller is responsible for ensuring that the lifetime of the
+ * interface descriptors is appropriate for the category of interface.
  */
 
@@ -349 +355 @@
 /**
  * Interface to deliver error messages to upper layers.
+ *
+ * Per disk interface. Optional, but think twice if you want to miss the
+ * opportunity of reporting better human-readable error messages.
  */
 typedef struct VDINTERFACEERROR
@@ -401 +410 @@
  * Completion callback which is called by the interface owner
  * to inform the backend that a task finished.
- * 
+ *
  * @return  VBox status code.
  * @param   pvUser          Opaque user data which is passed on request submission.
@@ -412 +421 @@
 /**
  * Support interface for asynchronous I/O
+ *
+ * Per-disk. Optional.
  */
 typedef struct VDINTERFACEASYNCIO
@@ -551 +562 @@
 /**
  * Progress notification interface
+ * 
+ * Per-operation. Optional.
  */
 typedef struct VDINTERFACEPROGRESS
@@ -614 +627 @@
 /**
  * Configuration information interface
+ *
+ * Per-image. Optional for most backends, but mandatory for images which do
+ * not operate on files (including standard block or character devices).
  */
 typedef struct VDINTERFACECONFIG
@@ -902 +918 @@
  *
  * @return  VBox status code.
- * @param   pVDIfs          Pointer to the VD interface list.
+ * @param   pVDIfsDisk      Pointer to the per-disk VD interface list.
  * @param   ppDisk          Where to store the reference to HDD container.
  */
-VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfs, PVBOXHDD *ppDisk);
+VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, PVBOXHDD *ppDisk);
 
 /**
@@ -943 +959 @@
  * @param   pszFilename     Name of the image file to open.
  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
+ * @param   pVDIfsImage     Pointer to the per-image VD interface list.
  */
 VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
-                         const char *pszFilename, unsigned uOpenFlags);
+                         const char *pszFilename, unsigned uOpenFlags,
+                         PVDINTERFACE pVDIfsImage);
 
 /**
@@ -962 +980 @@
  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
- * @param   pfnProgress     Progress callback. Optional. NULL if not to be used.
- * @param   pvUser          User argument for the progress callback.
+ * @param   pVDIfsImage     Pointer to the per-image VD interface list.
+ * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
  */
 VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
@@ -972 +990 @@
                                PCPDMMEDIAGEOMETRY pLCHSGeometry,
                                PCRTUUID pUuid, unsigned uOpenFlags,
-                               PFNVMPROGRESS pfnProgress, void *pvUser);
+                               PVDINTERFACE pVDIfsImage,
+                               PVDINTERFACE pVDIfsOperation);
 
 /**
@@ -986 +1005 @@
  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
- * @param   pfnProgress     Progress callback. Optional. NULL if not to be used.
- * @param   pvUser          User argument for the progress callback.
+ * @param   pVDIfsImage     Pointer to the per-image VD interface list.
+ * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
  */
 VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
                                const char *pszFilename, unsigned uImageFlags,
                                const char *pszComment, PCRTUUID pUuid,
-                               unsigned uOpenFlags, PFNVMPROGRESS pfnProgress,
-                               void *pvUser);
+                               unsigned uOpenFlags, PVDINTERFACE pVDIfsImage,
+                               PVDINTERFACE pVDIfsOperation);
 
 /**
@@ -1006 +1025 @@
  * @param   nImageFrom      Name of the image file to merge from.
  * @param   nImageTo        Name of the image file to merge to.
- * @param   pfnProgress     Progress callback. Optional. NULL if not to be used.
- * @param   pvUser          User argument for the progress callback.
+ * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
  */
 VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
-                          unsigned nImageTo, PFNVMPROGRESS pfnProgress,
-                          void *pvUser);
+                          unsigned nImageTo, PVDINTERFACE pVDIfsOperation);
 
 /**
@@ -1032 +1049 @@
  * @param   fMoveByRename   If true, attempt to perform a move by renaming (if successful the new size is ignored).
  * @param   cbSize          New image size (0 means leave unchanged).
- * @param   pfnProgress     Progress callback. Optional. NULL if not to be used.
- * @param   pvUser          User argument for the progress callback.
+ * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
+ * @param   pDstVDIfsImage  Pointer to the per-image VD interface list, for the
+ *                          destination image.
+ * @param   pDstVDIfsOperation Pointer to the per-operation VD interface list,
+ *                          for the destination operation.
  */
 VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
                          const char *pszBackend, const char *pszFilename,
                          bool fMoveByRename, uint64_t cbSize,
-                         PFNVMPROGRESS pfnProgress, void *pvUser);
+                         PVDINTERFACE pVDIfsOperation,
+                         PVDINTERFACE pDstVDIfsImage,
+                         PVDINTERFACE pDstVDIfsOperation);
 
 /**