Changeset 63905 in vbox for trunk/include

Timestamp:

Sep 20, 2016 8:31:05 AM (9 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

110782

Message:

Storage/VD: Add proper versioning of the backend structures instead of just relying on the structure size to make changing callback signatures possible in the future and still being able to reject incompatible plugins

Location:

trunk/include/VBox

Files:

• vd-cache-backend.h (modified) (5 diffs)
• vd-filter-backend.h (modified) (5 diffs)
• vd-image-backend.h (modified) (6 diffs)
• vd-plugin.h (modified) (3 diffs)

trunk/include/VBox/vd-cache-backend.h

@@ -28 +28 @@
 
 #include <VBox/vd.h>
+#include <VBox/vd-common.h>
 #include <VBox/vd-ifs-internal.h>
 
@@ -35 +36 @@
 typedef struct VDCACHEBACKEND
 {
-    /**
-     * The name of the backend (constant string).
-     */
-    const char *pszBackendName;
-
-    /**
-     * The size of the structure.
-     */
-    uint32_t cbSize;
-
-    /**
-     * The capabilities of the backend.
-     */
-    uint64_t uBackendCaps;
+    /** Structure version. VD_CACHEBACKEND_VERSION defines the current version. */
+    uint32_t            u32Version;
+    /** The name of the backend (constant string). */
+    const char          *pszBackendName;
+    /** The capabilities of the backend. */
+    uint64_t            uBackendCaps;
 
     /**
@@ -63 +56 @@
      * Mandatory if the backend sets VD_CAP_CONFIG.
      */
-    PCVDCONFIGINFO paConfigInfo;
+    PCVDCONFIGINFO      paConfigInfo;
 
     /**
@@ -312 +305 @@
     DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
 
+    /** Initialization safty marker. */
+    uint32_t            u32VersionEnd;
+
 } VDCACHEBACKEND;
 /** Pointer to VD cache backend. */
@@ -318 +314 @@
 typedef const VDCACHEBACKEND *PCVDCACHEBACKEND;
 
+/** The current version of the VDCACHEBACKEND structure. */
+#define VD_CACHEBACKEND_VERSION                 VD_VERSION_MAKE(0xff03, 1, 0)
+
 #endif

trunk/include/VBox/vd-filter-backend.h

@@ -28 +28 @@
 
 #include <VBox/vd.h>
+#include <VBox/vd-common.h>
 #include <VBox/vd-ifs-internal.h>
 
@@ -35 +36 @@
 typedef struct VDFILTERBACKEND
 {
-    /**
-     * The name of the backend (constant string).
-     */
-    const char *pszBackendName;
-
-    /**
-     * The size of the structure.
-     */
-    uint32_t cbSize;
+    /** Structure version. VD_FLTBACKEND_VERSION defines the current version. */
+    uint32_t            u32Version;
+    /** The name of the backend (constant string). */
+    const char          *pszBackendName;
 
     /**
@@ -51 +47 @@
      * Mandatory if the backend sets VD_CAP_CONFIG.
      */
-    PCVDCONFIGINFO paConfigInfo;
+    PCVDCONFIGINFO      paConfigInfo;
 
     /**
@@ -100 +96 @@
                                                PVDIOCTX pIoCtx));
 
+    /** Initialization safty marker. */
+    uint32_t            u32VersionEnd;
 } VDFILTERBACKEND;
 /** Pointer to VD filter backend. */
@@ -106 +104 @@
 typedef const VDFILTERBACKEND *PCVDFILTERBACKEND;
 
+/** The current version of the VDFILTERBACKEND structure. */
+#define VD_FLTBACKEND_VERSION                   VD_VERSION_MAKE(0xff02, 1, 0)
+
 #endif

trunk/include/VBox/vd-image-backend.h

@@ -28 +28 @@
 
 #include <VBox/vd.h>
+#include <VBox/vd-common.h>
 #include <VBox/vd-ifs-internal.h>
 
@@ -63 +64 @@
 typedef struct VDIMAGEBACKEND
 {
-    /**
-     * The name of the backend (constant string).
-     */
-    const char *pszBackendName;
-
-    /**
-     * The size of the structure.
-     */
-    uint32_t cbSize;
-
-    /**
-     * The capabilities of the backend.
-     */
-    uint64_t uBackendCaps;
+    /** Structure version. VD_IMGBACKEND_VERSION defines the current version. */
+    uint32_t            u32Version;
+    /** The name of the backend (constant string). */
+    const char          *pszBackendName;
+    /** The capabilities of the backend. */
+    uint64_t            uBackendCaps;
 
     /**
@@ -83 +76 @@
      * pointer may just contain NULL.
      */
-    PCVDFILEEXTENSION paFileExtensions;
+    PCVDFILEEXTENSION   paFileExtensions;
 
     /**
@@ -91 +84 @@
      * Mandatory if the backend sets VD_CAP_CONFIG.
      */
-    PCVDCONFIGINFO paConfigInfo;
+    PCVDCONFIGINFO      paConfigInfo;
 
     /**
@@ -585 +578 @@
                                                     PVDINTERFACE pVDIfsOperation));
 
+    /** Initialization safty marker. */
+    uint32_t            u32VersionEnd;
+
 } VDIMAGEBACKEND;
 
@@ -592 +588 @@
 typedef const VDIMAGEBACKEND *PCVDIMAGEBACKEND;
 
+/** The current version of the VDIMAGEBACKEND structure. */
+#define VD_IMGBACKEND_VERSION                   VD_VERSION_MAKE(0xff01, 1, 0)
+
 /** @copydoc VDIMAGEBACKEND::pfnComposeLocation */
 DECLCALLBACK(int) genericFileComposeLocation(PVDINTERFACE pConfig, char **pszLocation);

trunk/include/VBox/vd-plugin.h

@@ -28 +28 @@
 
 #include <VBox/vd.h>
+#include <VBox/vd-common.h>
 #include <VBox/vd-image-backend.h>
 #include <VBox/vd-cache-backend.h>
@@ -37 +38 @@
 typedef struct VDBACKENDREGISTER
 {
+    /** Interface version.
+     * This is set to VD_BACKENDREG_CB_VERSION. */
+    uint32_t                    u32Version;
+
     /**
      * Registers a new image backend.
@@ -66 +71 @@
 typedef VDBACKENDREGISTER *PVDBACKENDREGISTER;
 
+/** Current version of the VDBACKENDREGISTER structure.  */
+#define VD_BACKENDREG_CB_VERSION                VD_VERSION_MAKE(0xff00, 1, 0)
+
 /**
  * Initialization entry point called by the generic VD layer when