Changeset 34287 in vbox for trunk/include/VBox/ExtPack

Timestamp:

Nov 23, 2010 3:20:03 PM (14 years ago)

Author:

vboxsync

Message:

ExtPack: Don't hold any locks when calling extension pack hooks (except for pfnUnload and pfnUninstall).

File:

• trunk/include/VBox/ExtPack/ExtPack.h (modified) (7 diffs)

trunk/include/VBox/ExtPack/ExtPack.h

@@ -62 +62 @@
 } VBOXEXTPACKMODKIND;
 
+/**
+ * Contexts returned by VBOXEXTPACKHLP::pfnGetContext.
+ */
+typedef enum VBOXEXTPACKCTX
+{
+    /** Zero is invalid as alwasy. */
+    VBOXEXTPACKCTX_INVALID = 0,
+    /** The per-user daemon process (VBoxSVC). */
+    VBOXEXTPACKCTX_PER_USER_DAEMON,
+    /** A VM process.
+     * @remarks This will also include the client processes in v4.0.  */
+    VBOXEXTPACKCTX_VM_PROCESS,
+    /** A API client process.
+     * @remarks This will not be returned by VirtualBox 4.0. */
+    VBOXEXTPACKCTX_CLIENT_PROCESS,
+    /** End of the valid values (exclusive). */
+    VBOXEXTPACKCTX_END,
+    /** The usual 32-bit type hack. */
+    VBOXEXTPACKCTX_32BIT_HACK = 0x7fffffff
+} VBOXEXTPACKCTX;
+
 
 /** Pointer to const helpers passed to the VBoxExtPackRegister() call. */
@@ -119 +140 @@
     DECLR3CALLBACKMEMBER(int, pfnGetFilePath,(PCVBOXEXTPACKHLP pHlp, const char *pszFilename, char *pszPath, size_t cbPath));
 
+    /**
+     * Gets the context the extension pack is operating in.
+     *
+     * @returns The context.
+     * @retval  VBOXEXTPACKCTX_INVALID if @a pHlp is invalid.
+     *
+     * @param   pHlp            Pointer to this helper structure.
+     */
+    DECLR3CALLBACKMEMBER(VBOXEXTPACKCTX, pfnGetContext,(PCVBOXEXTPACKHLP pHlp));
+
+    DECLR3CALLBACKMEMBER(int, pfnReserved1,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved2,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved3,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved4,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved5,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved6,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved7,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved8,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+    DECLR3CALLBACKMEMBER(int, pfnReserved9,(PCVBOXEXTPACKHLP pHlp)); /**< Reserved for minor structure revisions. */
+
     /** End of structure marker (VBOXEXTPACKHLP_VERSION). */
     uint32_t                    u32EndMarker;
 } VBOXEXTPACKHLP;
 /** Current version of the VBOXEXTPACKHLP structure.  */
-#define VBOXEXTPACKHLP_VERSION          RT_MAKE_U32(1, 0)
+#define VBOXEXTPACKHLP_VERSION          RT_MAKE_U32(0, 1)
 
 
@@ -157 +198 @@
      * @param   pThis       Pointer to this structure.
      * @param   pVirtualBox The VirtualBox interface.
+     * @todo    This is currently called holding locks making pVirtualBox
+     *          relatively unusable.
      */
     DECLCALLBACKMEMBER(int, pfnUninstall)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
@@ -163 +206 @@
      * Hook for doing work after the VirtualBox object is ready.
      *
-     * This is called in the context of the per-user service (VBoxSVC).  There
-     * will not be any similar call from the VM process.
+     * This is called in the context of the per-user service (VBoxSVC).  The
+     * pfnConsoleReady method is the equivalent for the VM/client process.
      *
      * @param   pThis       Pointer to this structure.
@@ -170 +213 @@
      */
     DECLCALLBACKMEMBER(void, pfnVirtualBoxReady)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IVirtualBox) *pVirtualBox);
+
+    /**
+     * Hook for doing work after the Console object is ready.
+     *
+     * This is called in the context of the VM/client process.  The
+     * pfnVirtualBoxReady method is the equivalent for the per-user service
+     * (VBoxSVC).
+     *
+     * @param   pThis       Pointer to this structure.
+     * @param   pConsole    The Console interface.
+     */
+    DECLCALLBACKMEMBER(void, pfnConsoleReady)(PCVBOXEXTPACKREG pThis, VBOXEXTPACK_IF_CS(IConsole) *pConsole);
 
     /**
@@ -248 +303 @@
 } VBOXEXTPACKREG;
 /** Current version of the VBOXEXTPACKREG structure.  */
-#define VBOXEXTPACKREG_VERSION        RT_MAKE_U32(1, 0)
+#define VBOXEXTPACKREG_VERSION        RT_MAKE_U32(0, 1)
 
 
@@ -275 +330 @@
 
 
+/**
+ * Checks if extension pack interface version is compatible.
+ *
+ * @returns true if the do, false if they don't.
+ * @param   u32Provider     The provider version.
+ * @param   u32User         The user version.
+ */
+#define VBOXEXTPACK_IS_VER_COMPAT(u32Provider, u32User) \
+    (    VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Provider, u32User) \
+      && RT_LOWORD(u32Provider) >= RT_LOWORD(u32User) )
+
+/**
+ * Check if two extension pack interface versions has the same major version.
+ *
+ * @returns true if the do, false if they don't.
+ * @param   u32Ver1         The first version number.
+ * @param   u32Ver2         The second version number.
+ */
+#define VBOXEXTPACK_IS_MAJOR_VER_EQUAL(u32Ver1, u32Ver2)  (RT_HIWORD(u32Ver1) == RT_HIWORD(u32Ver2))
+
 #endif