11:25 p.m.
The vboxGlobalData and the vboxUniformedAPI is defined here. It defines
the middle layer interface. When using this file, it needs a context
to explain how *.c files treat vbox structs in vboxGlobalData(vboxObj,
vboxSession and so on). See annotate in this file.
---
src/vbox/vbox_common.h | 108 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 108 insertions(+)
create mode 100644 src/vbox/vbox_common.h
diff --git a/src/vbox/vbox_common.h b/src/vbox/vbox_common.h
new file mode 100644
index 0000000..eba360e
--- /dev/null
+++ b/src/vbox/vbox_common.h
@@ -0,0 +1,108 @@
+/*
+ * Copyright 2014, Taowei Luo (uaedante(a)gmail.com)
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see
+ * <http://www.gnu.org/licenses/>;.
+ */
+
+#include "internal.h"
+
+/* This file may be used in three place. That is vbox_tmpl.c,
+ * vbox_common.c and vbox_driver.c. Two important things is defined
+ * here, which is vboxGlobalData and vboxUniformedAPI.
+ *
+ * The vbox_tmpl.c is the only place where the driver knows the inside
+ * architecture of those vbox structs(vboxObj, vboxSession,
+ * pFuncs, vboxCallback and vboxQueue). The file should be included
+ * after the currect vbox_CAPI_v*.h, then we can use the vbox structs
+ * in vboxGlobalData. The vbox_tmpl.c should implement functions
+ * defined in vboxUniformedAPI.
+ *
+ * In vbox_driver.c, it is used to define the struct vboxUniformedAPI.
+ * The vbox_driver.c collects vboxUniformedAPI for all versions.
+ * Then vboxRegister calls the vboxRegisterUniformedAPI to register.
+ * Note: In vbox_driver.c, the vbox structs in vboxGlobalData is
+ * defined by vbox_CAPI_v2.2.h.
+ *
+ * The vbox_common.c, it is used to generate common codes for all vbox
+ * versions. Bacause the same member varible's offset in a vbox struct
+ * may change between different vbox versions. The vbox_common.c
+ * shouldn't directly use struct's member varibles defined in
+ * vbox_CAPI_v*.h. To make things safety, we include the
+ * vbox_commondef.h in vbox_common.c. In this case, we treat structs
+ * defined by vbox as a void*. The common codes don't concern about
+ * the inside of this structs(actually, we can't, in the common level).
+ * With the help of vboxUniformed API, we call VirtualBox's API and
+ * implement the vbox driver in a high level.
+ *
+ * In conclusion:
+ * * In vbox_tmpl.c, this file is included after vbox_CAPI_v*.h
+ * * In vbox_driver.c, this file is included after vbox_glue.h
+ * * In vbox_common.c, this file is included after vbox_commondef.h
+ *
+ */
+
+typedef struct {
+ virMutex lock;
+ unsigned long version;
+
+ virCapsPtr caps;
+ virDomainXMLOptionPtr xmlopt;
+
+ IVirtualBox *vboxObj;
+ ISession *vboxSession;
+
+ /** Our version specific API table pointer. */
+ PCVBOXXPCOM pFuncs;
+
+ /* The next is used when VBOX_API_VERSION > 2002000 */
+ /* Async event handling */
+ virObjectEventStatePtr domainEvents;
+ int fdWatch;
+# if VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000
+ /* IVirtualBoxCallback is used in VirtualBox 3.x only */
+ IVirtualBoxCallback *vboxCallback;
+# else /* VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000 */
+ void *vboxCallback;
+# endif /* VBOX_API_VERSION > 2002000 && VBOX_API_VERSION <= 3002000 */
+
+# if VBOX_API_VERSION > 2002000
+ nsIEventQueue *vboxQueue;
+# else /* VBOX_API_VERSION == 2002000 or undefined */
+ void *vboxQueue;
+# endif /* VBOX_API_VERSION == 2002000 or undefined */
+ int volatile vboxCallBackRefCount;
+
+ /* pointer back to the connection */
+ virConnectPtr conn;
+
+} vboxGlobalData;
+
+/* vboxUniformedAPI gives vbox_common.c a uniformed layer to see
+ * vbox API.
+ */
+typedef struct {
+ /* vbox API version */
+ uint32_t uVersion;
+ /* vbox APIs */
+ int (*pfnInitialize)(vboxGlobalData *data);
+ int (*initializeFWatch)(vboxGlobalData *data);
+ /* vbox API features */
+ bool fWatchNeedInitialize;
+} vboxUniformedAPI;
+
+/* Register the vboxUniformedAPI based on the current vbox version */
+void vboxRegisterUniformedAPI(vboxUniformedAPI *vboxAPI);
+
+int vboxInitialize(vboxGlobalData *data);
--
1.7.9.5