+{
+public:
+
+ /**
+ * Creates a null array.
+ */
+ SafeArray() {}
+
+ /**
+ * Creates a new array of the given size. All elements of the newly created
+ * array initialized with null values.
+ *
+ * @param aSize Initial number of elements in the array. Must be greater
+ * than 0.
+ *
+ * @note If this object remains null after construction it means that there
+ * was not enough memory for creating an array of the requested size.
+ * The constructor will also assert in this case.
+ */
+ SafeArray (size_t aSize) { reset (aSize); }
+
+ /**
+ * Weakly attaches this instance to the existing array passed in a method
+ * parameter declared using the ComSafeArrayIn macro. When using this call,
+ * always wrap the parameter name in the ComSafeArrayOutArg macro call like
+ * this:
+ *
+ * SafeArray safeArray (ComSafeArrayInArg (aArg));
+ *
+ *
+ * Note that this constructor doesn't take the ownership of the array. In
+ * particular, it means that operations that operate on the ownership (e.g.
+ * #detachTo()) are forbidden and will assert.
+ *
+ * @param aArg Input method parameter to attach to.
+ */
+ SafeArray (ComSafeArrayIn (T, aArg))
+ {
+#if defined (VBOX_WITH_XPCOM)
+
+ AssertReturnVoid (aArg != NULL);
+
+ m.size = aArgSize;
+ m.arr = aArg;
+ m.isWeak = true;
+
+#else /* defined (VBOX_WITH_XPCOM) */
+
+ AssertReturnVoid (aArg != NULL);
+ SAFEARRAY *arg = *aArg;
+
+ if (arg)
+ {
+ AssertReturnVoid (arg->cDims == 1);
+
+ VARTYPE vt;
+ HRESULT rc = SafeArrayGetVartype (arg, &vt);
+ AssertComRCReturnVoid (rc);
+ AssertMsgReturnVoid (vt == VarType(),
+ ("Expected vartype %d, got %d.\n",
+ VarType(), vt));
+ }
+
+ m.arr = arg;
+ m.isWeak = true;
+
+ AssertReturnVoid (accessRaw() != NULL);
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+ }
+
+ /**
+ * Destroys this instance after calling #setNull() to release allocated
+ * resources. See #setNull() for more details.
+ */
+ ~SafeArray() { setNull(); }
+
+ /**
+ * Returns @c true if this instance represents a null array.
+ */
+ bool isNull() const { return m.arr == NULL; }
+
+ /**
+ * Resets this instance to null and, if this instance is not a weak one,
+ * releases any resources ocuppied by the array data.
+ *
+ * @note This method destroys (cleans up) all elements of the array using
+ * the corresponding cleanup routine for the element type before the
+ * array itself is destroyed.
+ */
+ void setNull() { m.uninit(); }
+
+ /**
+ * Returns @c true if this instance is weak. A weak instance doesn't own the
+ * array data and therefore operations manipulating the ownership (e.g.
+ * #detachTo()) are forbidden and will assert.
+ */
+ bool isWeak() const { return m.isWeak; }
+
+ /** Number of elements in the array. */
+ size_t size() const
+ {
+#if defined (VBOX_WITH_XPCOM)
+ if (m.arr)
+ return m.size;
+ return 0;
+#else
+ if (m.arr)
+ return m.arr->rgsabound [0].cElements;
+ return 0;
+#endif
+ }
+
+ /**
+ * Resizes the array preserving its contents when possible. If the new size
+ * is bigger than the old size, new elements are initialized with null
+ * values. If the new size is smaller than the old size, the contents of the
+ * array above the new size is lost.
+ *
+ * @param aNewSize New number of elements in the array.
+ * @return @c true on success and false if there is not enough
+ * memory for resizing.
+ */
+ bool resize (size_t aNewSize)
+ {
+ /// @todo Implement me!
+ AssertFailedReturn (false);
+ }
+
+ /**
+ * Reinitializes this instance by preallocating space for the given number
+ * of elements. The previous array contents is lost.
+ *
+ * @param aNewSize New number of elements in the array.
+ * @return @c true on success and false if there is not enough
+ * memory for resizing.
+ */
+ bool reset (size_t aNewSize)
+ {
+ m.uninit();
+
+#if defined (VBOX_WITH_XPCOM)
+
+ AssertReturn (aNewSize > 0, false);
+
+ m.arr = (T *) nsMemory::Alloc (aNewSize * sizeof (T));
+ AssertReturn (m.arr != NULL, false);
+
+ m.size = aNewSize;
+
+ for (size_t i = 0; i < m.size; ++ i)
+ Init (m.arr [i]);
+
+#else
+
+ AssertReturn (aNewSize > 0, false);
+
+ SAFEARRAYBOUND bound = { aNewSize, 0 };
+ m.arr = SafeArrayCreate (VarType(), 1, &bound);
+ AssertReturn (m.arr != NULL, false);
+
+ AssertReturn (accessRaw() != NULL, false);
+
+#endif
+ return true;
+ }
+
+ /**
+ * Returns a pointer to the raw array data. Use this raw pointer with care
+ * as no type or bound checking is done for you in this case.
+ *
+ * @note This method returns @c NULL when this instance is null.
+ * @see #operator[]
+ */
+ T *raw()
+ {
+#if defined (VBOX_WITH_XPCOM)
+ return m.arr;
+#else
+ return accessRaw();
+#endif
+ }
+
+ /**
+ * Const version of #raw().
+ */
+ const T *raw() const
+ {
+#if defined (VBOX_WITH_XPCOM)
+ return m.arr;
+#else
+ return accessRaw();
+#endif
+ }
+
+ /**
+ * Array access operator that returns an array element by reference. A bit
+ * safer than #raw(): asserts and returns an invalid reference if this
+ * instance is null or if the index is out of bounds.
+ *
+ * @note For weak instances, this call will succeed but the beiavior of
+ * changing the contents of an element of the weak array instance is
+ * undefined and may lead to a program crash on some platforms.
+ */
+ T &operator[] (size_t aIdx)
+ {
+ AssertReturn (m.arr != NULL, *((T *) NULL));
+ AssertReturn (aIdx < size(), *((T *) NULL));
+#if defined (VBOX_WITH_XPCOM)
+ return m.arr [aIdx];
+#else
+
+ AssertReturn (accessRaw() != NULL, *((T *) NULL));
+ return m.raw [aIdx];
+#endif
+ }
+
+ /**
+ * Const version of #operator[] that returns an array element by value.
+ */
+ const T operator[] (size_t aIdx) const
+ {
+ AssertReturn (m.arr != NULL, *((T *) NULL));
+ AssertReturn (aIdx < size(), *((T *) NULL));
+#if defined (VBOX_WITH_XPCOM)
+ return m.arr [aIdx];
+#else
+ AssertReturn (unconst (this)->accessRaw() != NULL, *((T *) NULL));
+ return m.raw [aIdx];
+#endif
+ }
+
+ /**
+ * Creates a copy of this array and stores it in a method parameter declared
+ * using the ComSafeArrayOut macro. When using this call, always wrap the
+ * parameter name in the ComSafeArrayOutArg macro call like this:
+ *
+ * safeArray.cloneTo (ComSafeArrayOutArg (aArg));
+ *
+ *
+ * @note It is assumed that the ownership of the returned copy is
+ * transferred to the caller of the method and he is responsible to free the
+ * array data when it is no more necessary.
+ *
+ * @param aArg Output method parameter to clone to.
+ */
+ const SafeArray &cloneTo (ComSafeArrayOut (T, aArg)) const
+ {
+ /// @todo Implement me!
+ AssertFailedReturn (*this);
+ }
+
+ /**
+ * Transfers the ownership of this array's data to a method parameter
+ * declared using the ComSafeArrayOut macro and makes this array a null
+ * array. When using this call, always wrap the parameter name in the
+ * ComSafeArrayOutArg macro call like this:
+ *
+ * safeArray.detachTo (ComSafeArrayOutArg (aArg));
+ *
+ *
+ * @note Since the ownership of the array data is transferred to the
+ * caller of the method, he is responsible to free the array data when it is
+ * no more necessary.
+ *
+ * @param aArg Output method parameter to detach to.
+ */
+ SafeArray &detachTo (ComSafeArrayOut (T, aArg))
+ {
+ AssertReturn (m.isWeak == false, *this);
+
+#if defined (VBOX_WITH_XPCOM)
+
+ AssertReturn (aArgSize != NULL, *this);
+ AssertReturn (aArg != NULL, *this);
+
+ *aArgSize = m.size;
+ *aArg = m.arr;
+
+ m.isWeak = false;
+ m.size = 0;
+ m.arr = NULL;
+
+#else /* defined (VBOX_WITH_XPCOM) */
+
+ AssertReturn (aArg != NULL, *this);
+ *aArg = m.arr;
+
+ if (m.raw)
+ {
+ HRESULT rc = SafeArrayUnaccessData (m.arr);
+ AssertComRCReturn (rc, *this);
+ m.raw = NULL;
+ }
+
+ m.isWeak = false;
+ m.arr = NULL;
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+
+ return *this;
+ }
+
+ // public methods for internal purposes only
+
+#if defined (VBOX_WITH_XPCOM)
+
+ /** Internal funciton. Never call it directly. */
+ PRUint32 *__asOutParam_Size() { setNull(); return &m.size; }
+
+ /** Internal funciton. Never call it directly. */
+ T **__asOutParam_Arr() { Assert (isNull()); return &m.arr; }
+
+#else /* defined (VBOX_WITH_XPCOM) */
+
+ /** Internal funciton. Never call it directly. */
+ SAFEARRAY ** __asInParam() { return &m.arr; }
+
+ /** Internal funciton. Never call it directly. */
+ SAFEARRAY ** __asOutParam() { setNull(); return &m.arr; }
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+
+ static const SafeArray Null;
+
+private:
+
+ DECLARE_CLS_COPY_CTOR_ASSIGN_NOOP(SafeArray)
+
+#if defined (VBOX_WITH_XPCOM)
+#else /* defined (VBOX_WITH_XPCOM) */
+
+ /** Requests access to the raw data pointer. */
+ T *accessRaw()
+ {
+ if (m.arr && m.raw == NULL)
+ {
+ HRESULT rc = SafeArrayAccessData (m.arr, (void HUGEP **) &m.raw);
+ AssertComRCReturn (rc, NULL);
+ }
+ return m.raw;
+ }
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+
+ struct Data
+ {
+ Data()
+ : isWeak (false)
+#if defined (VBOX_WITH_XPCOM)
+ , size (0), arr (NULL)
+#else
+ , arr (NULL), raw (NULL)
+#endif
+ {}
+
+ ~Data() { uninit(); }
+
+ void uninit()
+ {
+#if defined (VBOX_WITH_XPCOM)
+
+ if (arr)
+ {
+ if (!isWeak)
+ {
+ for (size_t i = 0; i < size; ++ i)
+ Uninit (arr [i]);
+
+ nsMemory::Free ((void *) arr);
+
+ isWeak = false;
+ }
+ arr = NULL;
+ }
+
+#else /* defined (VBOX_WITH_XPCOM) */
+
+ if (arr)
+ {
+ if (raw)
+ {
+ SafeArrayUnaccessData (arr);
+ raw = NULL;
+ }
+
+ if (!isWeak)
+ {
+ HRESULT rc = SafeArrayDestroy (arr);
+ AssertComRCReturnVoid (rc);
+
+ isWeak = false;
+ }
+ arr = NULL;
+ }
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+ }
+
+ bool isWeak : 1;
+
+#if defined (VBOX_WITH_XPCOM)
+ PRUint32 size;
+ T *arr;
+#else
+ SAFEARRAY *arr;
+ T *raw;
+#endif
+ };
+
+ Data m;
+};
+
+} /* namespace com */
+
+/** @} */
+
+#endif /* ___VBox_com_array_h */
Index: /trunk/include/VBox/com/defs.h
===================================================================
--- /trunk/include/VBox/com/defs.h (revision 6850)
+++ /trunk/include/VBox/com/defs.h (revision 6851)
@@ -70,4 +70,73 @@
/**
+ * Declares an input safearray parameter in the COM method implementation. Also
+ * used to declare the COM attribute setter parameter. Corresponds to either of
+ * the following XIDL definitions:
+ *
+ *
+ * ...
+ *
+ *
+ *
+ * The method implementation should use the com::SafeArray helper class to work
+ * with parameters declared using this define.
+ *
+ * @param aType Array element type.
+ * @param aArg Parameter/attribute name.
+ */
+#define ComSafeArrayIn(aType, aArg) SAFEARRAY **aArg
+
+/**
+ * Expands to @true if the given input safearray parameter is a "null pointer"
+ * which makes it impossible to use it for reading safearray data.
+ */
+#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
+
+/**
+ * Wraps the given parameter name to generate an expression that is suitable for
+ * passing the parameter to functions that take input safearray parameters
+ * declared using the ComSafeArrayIn marco.
+ *
+ * @param aArg Parameter name to wrap. The given parameter must be declared
+ * within the calling function using the ComSafeArrayIn macro.
+ */
+#define ComSafeArrayInArg(aArg) aArg
+
+/**
+ * Declares an output safearray parameter in the COM method implementation. Also
+ * used to declare the COM attribute getter parameter. Corresponds to either of
+ * the following XIDL definitions:
+ *
+ *
+ *
+ * ...
+ *
+ *
+ *
+ * The method implementation should use the com::SafeArray helper class to work
+ * with parameters declared using this define.
+ *
+ * @param aType Array element type.
+ * @param aArg Parameter/attribute name.
+ */
+#define ComSafeArrayOut(aType, aArg) SAFEARRAY **aArg
+
+/**
+ * Expands to @true if the given output safearray parameter is a "null pointer"
+ * which makes it impossible to use it for returning a safearray.
+ */
+#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
+
+/**
+ * Wraps the given parameter name to generate an expression that is suitable for
+ * passing the parameter to functions that take output safearray parameters
+ * declared using the ComSafeArrayOut marco.
+ *
+ * @param aArg Parameter name to wrap. The given parameter must be declared
+ * within the calling function using the ComSafeArrayOut macro.
+ */
+#define ComSafeArrayOutArg(aArg) aArg
+
+/**
* Returns the const reference to the IID (i.e., |const GUID &|) of the given
* interface.
@@ -79,5 +148,5 @@
#else /* defined (RT_OS_WINDOWS) */
-#error "VBOX_WITH_XPCOM is not defined!"
+#error "VBOX_WITH_XPCOM must be defined on a platform other than Windows!"
#endif /* defined (RT_OS_WINDOWS) */
@@ -156,4 +225,14 @@
/* a type for an output GUID parameter in the interface method declaration */
#define GUIDPARAMOUT nsID **
+
+/* safearray input parameter macros */
+#define ComSafeArrayIn(aType, aArg) PRUint32 aArg##Size, aType *aArg
+#define ComSafeArrayInIsNull(aArg) (aArg == NULL)
+#define ComSafeArrayInArg(aArg) aArg##Size, aArg
+
+/* safearray output parameter macros */
+#define ComSafeArrayOut(aType, aArg) PRUint32 *aArg##Size, aType **aArg
+#define ComSafeArrayOutIsNull(aArg) (aArg == NULL)
+#define ComSafeArrayOutArg(aArg) aArg##Size, aArg
/* CLSID and IID for compatibility with Win32 */
Index: /trunk/include/VBox/com/string.h
===================================================================
--- /trunk/include/VBox/com/string.h (revision 6850)
+++ /trunk/include/VBox/com/string.h (revision 6851)
@@ -184,7 +184,7 @@
/**
- * Intended to assign instances to |BSTR| out parameters from within the
- * interface method. Transfers the ownership of the duplicated string to
- * the caller.
+ * Intended to assign copies of instances to |BSTR| out parameters from
+ * within the interface method. Transfers the ownership of the duplicated
+ * string to the caller.
*/
const Bstr &cloneTo (BSTR *pstr) const
@@ -199,7 +199,22 @@
/**
- * Intended to assign instances to |char *| out parameters from within the
- * interface method. Transfers the ownership of the duplicated string to
- * the caller.
+ * Intended to assign instances to |BSTR| out parameters from within the
+ * interface method. Transfers the ownership of the original string to the
+ * caller and resets the instance to null.
+ *
+ * As opposed to cloneTo(), this method doesn't create a copy of the
+ * string.
+ */
+ Bstr &detachTo (BSTR *pstr)
+ {
+ *pstr = bstr;
+ bstr = NULL;
+ return *this;
+ }
+
+ /**
+ * Intended to assign copies of instances to |char *| out parameters from
+ * within the interface method. Transfers the ownership of the duplicated
+ * string to the caller.
*/
const Bstr &cloneTo (char **pstr) const;
@@ -211,5 +226,5 @@
BSTR *asOutParam() { setNull(); return &bstr; }
- /**
+ /**
* Static immutable null object. May be used for comparison purposes.
*/
@@ -405,4 +420,19 @@
/**
+ * Intended to assign instances to |char *| out parameters from within the
+ * interface method. Transfers the ownership of the original string to the
+ * caller and resets the instance to null.
+ *
+ * As opposed to cloneTo(), this method doesn't create a copy of the
+ * string.
+ */
+ Utf8Str &detachTo (char **pstr)
+ {
+ *pstr = str;
+ str = NULL;
+ return *this;
+ }
+
+ /**
* Intended to assign instances to |BSTR| out parameters from within the
* interface method. Transfers the ownership of the duplicated string to the
@@ -425,5 +455,5 @@
char **asOutParam() { setNull(); return &str; }
- /**
+ /**
* Static immutable null object. May be used for comparison purposes.
*/
Index: /trunk/src/VBox/Frontends/VirtualBox/include/COMDefs.h
===================================================================
--- /trunk/src/VBox/Frontends/VirtualBox/include/COMDefs.h (revision 6850)
+++ /trunk/src/VBox/Frontends/VirtualBox/include/COMDefs.h (revision 6851)
@@ -24,4 +24,45 @@
#define __COMDefs_h__
+/** @defgroup grp_QT_COM Qt-COM Support Layer
+ * @{
+ *
+ * The Qt-COM support layer provides a set of defintions and smart classes for
+ * writing simple, clean and platform-independent code to access COM/XPCOM
+ * components through exposed COM interfaces. This layer is based on the
+ * COM/XPCOM Abstarction Layer library (the VBoxCOM glue library defined in
+ * include/VBox/com and implemented in src/VBox/Main/glue).
+ *
+ * ...
+ *
+ * @defgroup grp_QT_COM_arrays Arrays
+ * @{
+ *
+ * COM/XPCOM arrays are mapped to QValueVector objects. QValueVector templates
+ * declared with a type that corresponds to the COM type of elements in the
+ * array using normal Qt-COM type mapping rules. Here is a code example that
+ * demonstrates how to call interface methods that take and return arrays (this
+ * example is based on examples given in @ref grp_COM_arrays):
+ * @code
+
+ CSomething component;
+
+ // ...
+
+ QValueVector in (3);
+ in [0] = -1;
+ in [1] = -2;
+ in [2] = -3;
+
+ QValueVector out;
+ QValueVector ret;
+
+ ret = component.TestArrays (in, out);
+
+ for (size_t i = 0; i < ret.size(); ++ i)
+ LogFlow (("*** ret[%u]=%d\n", i, ret [i]));
+
+ * @endcode
+ * @}
+ */
/* Both VBox/com/assert.h and qglobal.h contain a definition of ASSERT.
@@ -30,4 +71,5 @@
#include
+#include
#include
@@ -37,4 +79,5 @@
#include
#include
+#include
#include // for auto_copy_ptr
@@ -139,28 +182,6 @@
public:
- static HRESULT initializeCOM();
- static HRESULT cleanupCOM();
-
-#if !defined (VBOX_WITH_XPCOM)
-
- /** Converts a GUID value to QUuid */
- static QUuid toQUuid (const GUID &id)
- {
- return QUuid (id.Data1, id.Data2, id.Data3,
- id.Data4[0], id.Data4[1], id.Data4[2], id.Data4[3],
- id.Data4[4], id.Data4[5], id.Data4[6], id.Data4[7]);
- }
-
-#else /* !defined (VBOX_WITH_XPCOM) */
-
- /** Converts a GUID value to QUuid */
- static QUuid toQUuid (const nsID &id)
- {
- return QUuid (id.m0, id.m1, id.m2,
- id.m3[0], id.m3[1], id.m3[2], id.m3[3],
- id.m3[4], id.m3[5], id.m3[6], id.m3[7]);
- }
-
-#endif /* !defined (VBOX_WITH_XPCOM) */
+ static HRESULT InitializeCOM();
+ static HRESULT CleanupCOM();
/**
@@ -178,4 +199,109 @@
virtual COMErrorInfo errorInfo() const { return COMErrorInfo(); }
+#if !defined (VBOX_WITH_XPCOM)
+
+ /** Converts a GUID value to QUuid */
+ static QUuid ToQUuid (const GUID &id)
+ {
+ return QUuid (id.Data1, id.Data2, id.Data3,
+ id.Data4[0], id.Data4[1], id.Data4[2], id.Data4[3],
+ id.Data4[4], id.Data4[5], id.Data4[6], id.Data4[7]);
+ }
+
+#else /* !defined (VBOX_WITH_XPCOM) */
+
+ /** Converts a GUID value to QUuid */
+ static QUuid ToQUuid (const nsID &id)
+ {
+ return QUuid (id.m0, id.m1, id.m2,
+ id.m3[0], id.m3[1], id.m3[2], id.m3[3],
+ id.m3[4], id.m3[5], id.m3[6], id.m3[7]);
+ }
+
+#endif /* !defined (VBOX_WITH_XPCOM) */
+
+ /* Arrays of arbitrary types */
+
+ template
+ static void ToSafeArray (const QValueVector &aVec, com::SafeArray &aArr)
+ {
+ AssertMsgFailedReturnVoid (("No conversion!\n"));
+ }
+
+ template
+ static void FromSafeArray (const com::SafeArray &aArr, QValueVector &aVec)
+ {
+ AssertMsgFailedReturnVoid (("No conversion!\n"));
+ }
+
+ template
+ static void ToSafeArray (const QValueVector &aVec, com::SafeArray &aArr)
+ {
+ AssertMsgFailedReturnVoid (("No conversion!\n"));
+ }
+
+ template
+ static void FromSafeArray (const com::SafeArray &aArr, QValueVector &aVec)
+ {
+ AssertMsgFailedReturnVoid (("No conversion!\n"));
+ }
+
+ /* Arrays of equal types */
+
+ template
+ static void ToSafeArray (const QValueVector &aVec, com::SafeArray &aArr)
+ {
+ aArr.reset (aVec.size());
+ size_t i = 0;
+ for (typename QValueVector ::const_iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ aArr [i] = *it;
+ }
+
+ template
+ static void FromSafeArray (const com::SafeArray &aArr, QValueVector &aVec)
+ {
+ aVec = QValueVector (aArr.size());
+ size_t i = 0;
+ for (typename QValueVector ::iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ *it = aArr [i];
+ }
+
+ /* Arrays of interface pointers */
+
+ template
+ static void ToSafeArray (const QValueVector &aVec,
+ com::SafeArray &aArr)
+ {
+ aArr.reset (aVec.size());
+ size_t i = 0;
+ for (typename QValueVector ::const_iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ {
+ aArr [i] = (*it).iface();
+ if (aArr [i])
+ aArr [i]->AddRef();
+ }
+ }
+
+ template
+ void FromSafeArray (const com::SafeArray &aArr,
+ QValueVector &aVec)
+ {
+ aVec = QValueVector (aArr.size());
+ size_t i = 0;
+ for (typename QValueVector ::iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ (*it).attach (aArr [i]);
+ }
+
+ /* Arrays of strings */
+
+ static void ToSafeArray (const QValueVector &aVec,
+ com::SafeArray &aArr);
+ static void FromSafeArray (const com::SafeArray &aArr,
+ QValueVector &aVec);
+
protected:
@@ -230,18 +356,23 @@
};
- /** Adapter to pass CEnums enums as output VirtualBox enum params (*_T) */
- template
+ /**
+ * Adapter to pass CEnums enums as output COM enum params (*_T).
+ *
+ * @param QE CEnums enum.
+ * @param CE COM enum.
+ */
+ template
class ENUMOut
{
public:
- ENUMOut (CE &e) : ce (e), ve ((VE) 0) {}
- ~ENUMOut() { ce = (CE) ve; }
- operator VE *() { return &ve; }
+ ENUMOut (QE &e) : qe (e), ce ((CE) 0) {}
+ ~ENUMOut() { qe = (QE) ce; }
+ operator CE *() { return &ce; }
private:
- CE &ce;
- VE ve;
+ QE &qe;
+ CE ce;
};
@@ -605,3 +736,5 @@
#include "COMWrappers.h"
+/** @} */
+
#endif // __COMDefs_h__
Index: /trunk/src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl
===================================================================
--- /trunk/src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl (revision 6850)
+++ /trunk/src/VBox/Frontends/VirtualBox/include/COMWrappers.xsl (revision 6851)
@@ -12,5 +12,5 @@
/*
Copyright (C) 2006-2007 innotek GmbH
-
+
This file is part of VirtualBox Open Source Edition (OSE), as
available from http://www.virtualbox.org. This file is free software;
@@ -126,5 +126,5 @@
enum
- {
+
{
@@ -360,5 +360,5 @@
C
- & operator = (const CUnknown & that) {
return (C
+ & operator = (const CUnknown & that)
{
return (C
&) Base::operator = (that);
}
@@ -431,5 +431,12 @@
+
+
+
+
+ 'array' attributes are not supported, use 'safearray="yes"' instead.
+
+
@@ -446,4 +453,5 @@
+
@@ -468,5 +476,5 @@
inline ULONG C
- ::GetCount () const {
+ ::GetCount () const
{
ULONG count = 0;
Assert (mIface);
@@ -481,5 +489,5 @@
C
- ::GetItemAt (ULONG index) const {
+ ::GetItemAt (ULONG index) const
{
item;
@@ -495,5 +503,5 @@
C
- ::Enumerate () const {
+ ::Enumerate () const
{
enumerator;
@@ -510,5 +518,5 @@
inline BOOL C
- ::HasMore () const {
+ ::HasMore () const
{
BOOL more = FALSE;
Assert (mIface);
@@ -523,5 +531,5 @@
C
- ::GetNext () const {
+ ::GetNext () const
{
next;
@@ -545,4 +553,5 @@
+
@@ -563,4 +572,5 @@
+
@@ -625,5 +635,5 @@
- {
+
{
Assert (mIface);
@@ -658,33 +668,26 @@
- {
+
{
- a_
-
-
-
+
;
Assert (mIface);
- if (!mIface)
return a_
-
-
+
;
- return a_
-
-
+
;
}
@@ -720,9 +723,8 @@
- a_
-
-
+
)
@@ -749,9 +751,8 @@
- a_
-
-
+
,
@@ -767,4 +768,21 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
mRC = mIface->
@@ -807,4 +825,21 @@
);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
@@ -855,5 +890,5 @@
- if (FAILED (mRC)) {
+ if (FAILED (mRC))
{
fetchErrorInfo (mIface, &COM_IIDOF (Base::Iface));
@@ -868,4 +903,5 @@
+
@@ -874,21 +910,34 @@
+
+
+
+
+ ComSafeArrayAsInParam (
+
+ )
+
+
+ ComSafeArrayAsOutParam (
+
+ )
+
+
+
- BSTRIn (a_
-
-
+
)
- BSTROut (a_
-
-
+
)
@@ -899,17 +948,15 @@
- GUIDIn (a_
-
-
+
)
- GUIDOut (a_
-
-
+
)
@@ -925,9 +972,8 @@
(
- _T) a_
-
-
+
@@ -936,9 +982,8 @@
,
- _T> (a_
-
-
+
)
@@ -960,9 +1005,8 @@
- a_
-
-
+
@@ -975,9 +1019,8 @@
- &a_
-
-
+
@@ -1003,16 +1046,14 @@
- a_
-
-
+
- &a_
-
-
+
@@ -1023,5 +1064,5 @@
-
+
+
+
+ either 'array' or 'safearray="yes"' attribute is allowed, but not both!
+
+
+
+
- return array parameters are not currently supported
+ return 'array' parameters and 'array' attributes are not supported, use 'safearray="yes"' instead.
@@ -1041,7 +1089,13 @@
+
+
+
+ either 'safearray' or 'mod' attribute is allowed, but not both!
+
+
-
+
either 'array' or 'mod' attribute is allowed, but not both!
@@ -1079,5 +1133,5 @@
- of attibute 'mod' is invalid!
+ of attribute 'mod' is invalid!
@@ -1086,4 +1140,7 @@
+
+ QValueVector <
+
@@ -1139,4 +1196,7 @@
+
+ >
+
@@ -1157,12 +1217,9 @@
+
+
+
-
-
-
- either 'array' or 'mod' attribute is allowed, but not both!
-
-
@@ -1197,5 +1254,5 @@
- of attibute 'mod' is invalid!
+ of attribute 'mod' is invalid!
@@ -1247,4 +1304,5 @@
.='string' or
.='wstring' or
+ ../@safearray='yes' or
((ancestor::library/enum[@name=current()]) or
(ancestor::library/if[@target=$self_target]/enum[@name=current()])
@@ -1270,10 +1328,4 @@
-
-
-
- arrays of non-scalar types are not currently supported
-
-
@@ -1324,4 +1376,185 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+ BOOL *
+ BYTE *
+ SHORT *
+ USHORT *
+ LONG *
+ LONG64 *
+ ULONG *
+ ULONG64 *
+ CHAR *
+
+ OLECHAR *
+
+
+
+
+ attribute 'mod=
+
+ ' cannot be used with type
+
+
+
+
+
+
+
+
+
+ of attribute 'mod' is invalid!
+
+
+
+
+
+
+
+
+ HRESULT
+ BOOL
+ BYTE
+ SHORT
+ USHORT
+ LONG
+ LONG64
+ ULONG
+ ULONG64
+ CHAR
+ CHAR *
+ OLECHAR
+ BSTR
+
+ GUID
+
+ IUnknown *
+
+
+
+
+
+
+
+
+ *
+
+
+
+
+ Unknown parameter type:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ com::SafeArray <
+
+ >
+
+ ;
+
+
+ ToSafeArray (
+ a
+
+
+
+ ,
+
+ );
+
+
+
+
+
+
+
+
+
+ FromSafeArray (
+
+ ,
+ a
+
+
+
+ );
+
+
+
+
+
+
+ Invalid when value:
+
+
+
+
+
+
+
+
Index: /trunk/src/VBox/Frontends/VirtualBox/src/COMDefs.cpp
===================================================================
--- /trunk/src/VBox/Frontends/VirtualBox/src/COMDefs.cpp (revision 6850)
+++ /trunk/src/VBox/Frontends/VirtualBox/src/COMDefs.cpp (revision 6851)
@@ -86,5 +86,5 @@
* Initializes COM/XPCOM.
*/
-HRESULT COMBase::initializeCOM()
+HRESULT COMBase::InitializeCOM()
{
LogFlowFuncEnter();
@@ -126,5 +126,5 @@
if (FAILED (rc))
- cleanupCOM();
+ CleanupCOM();
AssertComRC (rc);
@@ -139,5 +139,5 @@
* Cleans up COM/XPCOM.
*/
-HRESULT COMBase::cleanupCOM()
+HRESULT COMBase::CleanupCOM()
{
LogFlowFuncEnter();
@@ -182,4 +182,26 @@
}
+/* static */
+void COMBase::ToSafeArray (const QValueVector &aVec,
+ com::SafeArray &aArr)
+{
+ aArr.reset (aVec.size());
+ size_t i = 0;
+ for (QValueVector ::const_iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ aArr [i] = SysAllocString ((const OLECHAR *) (*it).ucs2());
+}
+
+/* static */
+void COMBase::FromSafeArray (const com::SafeArray &aArr,
+ QValueVector &aVec)
+{
+ aVec = QValueVector (aArr.size());
+ size_t i = 0;
+ for (QValueVector ::iterator it = aVec.begin();
+ it != aVec.end(); ++ it, ++ i)
+ *it = QString::fromUcs2 (aArr [i]);
+}
+
////////////////////////////////////////////////////////////////////////////////
@@ -351,5 +373,5 @@
if (callee && calleeIID && mIsBasicAvailable)
{
- mCalleeIID = COMBase::toQUuid (*calleeIID);
+ mCalleeIID = COMBase::ToQUuid (*calleeIID);
mCalleeName = getInterfaceNameFromIID (mCalleeIID);
}
Index: /trunk/src/VBox/Frontends/VirtualBox/src/VBoxGlobal.cpp
===================================================================
--- /trunk/src/VBox/Frontends/VirtualBox/src/VBoxGlobal.cpp (revision 6850)
+++ /trunk/src/VBox/Frontends/VirtualBox/src/VBoxGlobal.cpp (revision 6851)
@@ -190,5 +190,5 @@
STDMETHOD(OnMachineStateChange) (IN_GUIDPARAM id, MachineState_T state)
{
- postEvent (new VBoxMachineStateChangeEvent (COMBase::toQUuid (id),
+ postEvent (new VBoxMachineStateChangeEvent (COMBase::ToQUuid (id),
(CEnums::MachineState) state));
return S_OK;
@@ -197,5 +197,5 @@
STDMETHOD(OnMachineDataChange) (IN_GUIDPARAM id)
{
- postEvent (new VBoxMachineDataChangeEvent (COMBase::toQUuid (id)));
+ postEvent (new VBoxMachineDataChangeEvent (COMBase::ToQUuid (id)));
return S_OK;
}
@@ -208,5 +208,5 @@
return E_INVALIDARG;
- if (COMBase::toQUuid (id).isNull())
+ if (COMBase::ToQUuid (id).isNull())
{
/* it's a global extra data key someone wants to change */
@@ -257,5 +257,5 @@
IN_BSTRPARAM key, IN_BSTRPARAM value)
{
- if (COMBase::toQUuid (id).isNull())
+ if (COMBase::ToQUuid (id).isNull())
{
QString sKey = QString::fromUcs2 (key);
@@ -300,5 +300,5 @@
STDMETHOD(OnMachineRegistered) (IN_GUIDPARAM id, BOOL registered)
{
- postEvent (new VBoxMachineRegisteredEvent (COMBase::toQUuid (id),
+ postEvent (new VBoxMachineRegisteredEvent (COMBase::ToQUuid (id),
registered));
return S_OK;
@@ -307,5 +307,5 @@
STDMETHOD(OnSessionStateChange) (IN_GUIDPARAM id, SessionState_T state)
{
- postEvent (new VBoxSessionStateChangeEvent (COMBase::toQUuid (id),
+ postEvent (new VBoxSessionStateChangeEvent (COMBase::ToQUuid (id),
(CEnums::SessionState) state));
return S_OK;
@@ -314,6 +314,6 @@
STDMETHOD(OnSnapshotTaken) (IN_GUIDPARAM aMachineId, IN_GUIDPARAM aSnapshotId)
{
- postEvent (new VBoxSnapshotEvent (COMBase::toQUuid (aMachineId),
- COMBase::toQUuid (aSnapshotId),
+ postEvent (new VBoxSnapshotEvent (COMBase::ToQUuid (aMachineId),
+ COMBase::ToQUuid (aSnapshotId),
VBoxSnapshotEvent::Taken));
return S_OK;
@@ -322,6 +322,6 @@
STDMETHOD(OnSnapshotDiscarded) (IN_GUIDPARAM aMachineId, IN_GUIDPARAM aSnapshotId)
{
- postEvent (new VBoxSnapshotEvent (COMBase::toQUuid (aMachineId),
- COMBase::toQUuid (aSnapshotId),
+ postEvent (new VBoxSnapshotEvent (COMBase::ToQUuid (aMachineId),
+ COMBase::ToQUuid (aSnapshotId),
VBoxSnapshotEvent::Discarded));
return S_OK;
@@ -330,6 +330,6 @@
STDMETHOD(OnSnapshotChange) (IN_GUIDPARAM aMachineId, IN_GUIDPARAM aSnapshotId)
{
- postEvent (new VBoxSnapshotEvent (COMBase::toQUuid (aMachineId),
- COMBase::toQUuid (aSnapshotId),
+ postEvent (new VBoxSnapshotEvent (COMBase::ToQUuid (aMachineId),
+ COMBase::ToQUuid (aSnapshotId),
VBoxSnapshotEvent::Changed));
return S_OK;
@@ -1934,5 +1934,5 @@
{
LogFlow (("MediaEnumThread started.\n"));
- COMBase::initializeCOM();
+ COMBase::InitializeCOM();
CVirtualBox mVBox = vboxGlobal().virtualBox();
@@ -2010,5 +2010,5 @@
QApplication::postEvent (target, new VBoxEnumerateMediaEvent());
- COMBase::cleanupCOM();
+ COMBase::CleanupCOM();
LogFlow (("MediaEnumThread finished.\n"));
}
@@ -3770,5 +3770,5 @@
/* COM for the main thread is initialized in main() */
#else
- HRESULT rc = COMBase::initializeCOM();
+ HRESULT rc = COMBase::InitializeCOM();
if (FAILED (rc))
{
@@ -4030,5 +4030,5 @@
/* COM for the main thread is shutdown in main() */
#else
- COMBase::cleanupCOM();
+ COMBase::CleanupCOM();
#endif
Index: /trunk/src/VBox/Frontends/VirtualBox/src/main.cpp
===================================================================
--- /trunk/src/VBox/Frontends/VirtualBox/src/main.cpp (revision 6850)
+++ /trunk/src/VBox/Frontends/VirtualBox/src/main.cpp (revision 6851)
@@ -138,5 +138,5 @@
* for some unknown reason), see also src/VBox/Main/glue/initterm.cpp. */
/// @todo find a proper solution that satisfies both OLE and VBox
- HRESULT hrc = COMBase::initializeCOM();
+ HRESULT hrc = COMBase::InitializeCOM();
#endif
@@ -267,5 +267,5 @@
/* See COMBase::initializeCOM() above */
if (SUCCEEDED (hrc))
- COMBase::cleanupCOM();
+ COMBase::CleanupCOM();
#endif
Index: /trunk/src/VBox/Main/Doxyfile.Main
===================================================================
--- /trunk/src/VBox/Main/Doxyfile.Main (revision 6850)
+++ /trunk/src/VBox/Main/Doxyfile.Main (revision 6851)
@@ -86,5 +86,5 @@
# "is" "provides" "specifies" "contains" "represents" "a" "an" "the"
-ABBREVIATE_BRIEF = "The $name interface" "represents" "a" "an" "the"
+ABBREVIATE_BRIEF = "The $name class" "The $name interface" "is" "provides" "represents" "a" "an" "the"
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
Index: /trunk/src/VBox/Main/Makefile.kmk
===================================================================
--- /trunk/src/VBox/Main/Makefile.kmk (revision 6850)
+++ /trunk/src/VBox/Main/Makefile.kmk (revision 6851)
@@ -394,5 +394,5 @@
ConsoleImpl.cpp_DEFS = VBOX_BUILD_TARGET=\"$(BUILD_TARGET).$(BUILD_TARGET_ARCH)\"
-win32/VBoxC.rc_DEPS = $(PATH_TARGET)/VBoxC.rgs
+win32/VBoxC.rc_DEPS = $(PATH_TARGET)/VBoxC.rgs $(PATH_VBoxCOM)/VirtualBox.tlb
Index: /trunk/src/VBox/Main/VirtualBoxBase.cpp
===================================================================
--- /trunk/src/VBox/Main/VirtualBoxBase.cpp (revision 6850)
+++ /trunk/src/VBox/Main/VirtualBoxBase.cpp (revision 6851)
@@ -932,8 +932,197 @@
}
-#if defined VBOX_MAIN_SETTINGS_ADDONS
+// VirtualBoxBaseWithChildrenNEXT methods
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Uninitializes all dependent children registered with #addDependentChild().
+ *
+ * Typically called from the uninit() method. Note that this method will call
+ * uninit() methods of child objects. If these methods need to call the parent
+ * object during initialization, uninitDependentChildren() must be called before
+ * the relevant part of the parent is uninitialized, usually at the begnning of
+ * the parent uninitialization sequence.
+ */
+void VirtualBoxBaseWithChildrenNEXT::uninitDependentChildren()
+{
+ LogFlowThisFuncEnter();
+
+ AutoLock mapLock (mMapLock);
+
+ LogFlowThisFunc (("count=%u...\n", mDependentChildren.size()));
+
+ if (mDependentChildren.size())
+ {
+ /* We keep the lock until we have enumerated all children.
+ * Those ones that will try to call removeDependentChild() from a
+ * different thread will have to wait */
+
+ Assert (mUninitDoneSem == NIL_RTSEMEVENT);
+ int vrc = RTSemEventCreate (&mUninitDoneSem);
+ AssertRC (vrc);
+
+ Assert (mChildrenLeft == 0);
+ mChildrenLeft = mDependentChildren.size();
+
+ for (DependentChildren::iterator it = mDependentChildren.begin();
+ it != mDependentChildren.end(); ++ it)
+ {
+ VirtualBoxBase *child = (*it).second;
+ Assert (child);
+ if (child)
+ child->uninit();
+ }
+
+ mDependentChildren.clear();
+ }
+
+ /* Wait until all children that called uninit() on their own on other
+ * threads but stuck waiting for the map lock in removeDependentChild() have
+ * finished uninitialization. */
+
+ if (mUninitDoneSem != NIL_RTSEMEVENT)
+ {
+ /* let stuck children run */
+ mapLock.leave();
+
+ LogFlowThisFunc (("Waiting for uninitialization of all children...\n"));
+
+ RTSemEventWait (mUninitDoneSem, RT_INDEFINITE_WAIT);
+
+ mapLock.enter();
+
+ RTSemEventDestroy (mUninitDoneSem);
+ mUninitDoneSem = NIL_RTSEMEVENT;
+ Assert (mChildrenLeft == 0);
+ }
+
+ LogFlowThisFuncLeave();
+}
+
+/**
+ * Returns a pointer to the dependent child corresponding to the given
+ * interface pointer (used as a key in the map of dependent children) or NULL
+ * if the interface pointer doesn't correspond to any child registered using
+ * #addDependentChild().
+ *
+ * Note that ComPtr is used as an argument instead of IUnknown * in
+ * order to guarantee IUnknown identity and disambiguation by doing
+ * QueryInterface (IUnknown) rather than a regular C cast.
+ *
+ * @param aUnk Pointer to map to the dependent child object.
+ * @return Pointer to the dependent child object.
+ */
+VirtualBoxBaseNEXT *
+VirtualBoxBaseWithChildrenNEXT::getDependentChild (const ComPtr &aUnk)
+{
+ AssertReturn (!!aUnk, NULL);
+
+ AutoLock alock (mMapLock);
+
+ /* return NULL if uninitDependentChildren() is in action */
+ if (mUninitDoneSem != NIL_RTSEMEVENT)
+ return NULL;
+
+ DependentChildren::const_iterator it = mDependentChildren.find (aUnk);
+ if (it == mDependentChildren.end())
+ return NULL;
+ return (*it).second;
+}
+
+void VirtualBoxBaseWithChildrenNEXT::doAddDependentChild (
+ IUnknown *aUnk, VirtualBoxBaseNEXT *aChild)
+{
+ AssertReturnVoid (aUnk && aChild);
+
+ AutoLock alock (mMapLock);
+
+ if (mUninitDoneSem != NIL_RTSEMEVENT)
+ {
+ /* uninitDependentChildren() is being run. For this very unlikely case,
+ * we have to increase the number of children left, for symmetry with
+ * a later #removeDependentChild() call. */
+ ++ mChildrenLeft;
+ return;
+ }
+
+ std::pair result =
+ mDependentChildren.insert (DependentChildren::value_type (aUnk, aChild));
+ AssertMsg (result.second, ("Failed to insert a child to the map\n"));
+}
+
+void VirtualBoxBaseWithChildrenNEXT::doRemoveDependentChild (IUnknown *aUnk)
+{
+ AssertReturnVoid (aUnk);
+
+ AutoLock alock (mMapLock);
+
+ if (mUninitDoneSem != NIL_RTSEMEVENT)
+ {
+ /* uninitDependentChildren() is being run. Just decrease the number of
+ * children left and signal a semaphore if it reaches zero. */
+ Assert (mChildrenLeft != 0);
+ -- mChildrenLeft;
+ if (mChildrenLeft == 0)
+ {
+ int vrc = RTSemEventSignal (mUninitDoneSem);
+ AssertRC (vrc);
+ }
+ return;
+ }
+
+ DependentChildren::size_type result = mDependentChildren.erase (aUnk);
+ AssertMsg (result == 1, ("Failed to remove the child %p from the map\n",
+ aUnk));
+ NOREF (result);
+}
+
+// VirtualBoxBaseWithTypedChildrenNEXT methods
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Uninitializes all dependent children registered with
+ * #addDependentChild().
+ *
+ * @note This method will call uninit() methods of children. If these
+ * methods access the parent object, uninitDependentChildren() must be
+ * called either at the beginning of the parent uninitialization
+ * sequence (when it is still operational) or after setReady(false) is
+ * called to indicate the parent is out of action.
+ */
+template
+void VirtualBoxBaseWithTypedChildrenNEXT ::uninitDependentChildren()
+{
+ AutoLock mapLock (mMapLock);
+
+ if (mDependentChildren.size())
+ {
+ /* set flag to ignore #removeDependentChild() called from
+ * child->uninit() */
+ mInUninit = true;
+
+ /* leave the locks to let children waiting for
+ * #removeDependentChild() run */
+ mapLock.leave();
+
+ for (typename DependentChildren::iterator it = mDependentChildren.begin();
+ it != mDependentChildren.end(); ++ it)
+ {
+ C *child = (*it);
+ Assert (child);
+ if (child)
+ child->uninit();
+ }
+ mDependentChildren.clear();
+
+ mapLock.enter();
+
+ mInUninit = false;
+ }
+}
// Settings API additions
////////////////////////////////////////////////////////////////////////////////
+
+#if defined VBOX_MAIN_SETTINGS_ADDONS
namespace settings
Index: /trunk/src/VBox/Main/idl/midl.xsl
===================================================================
--- /trunk/src/VBox/Main/idl/midl.xsl (revision 6850)
+++ /trunk/src/VBox/Main/idl/midl.xsl (revision 6851)
@@ -6,5 +6,5 @@
Copyright (C) 2006-2007 innotek GmbH
-
+
This file is part of VirtualBox Open Source Edition (OSE), as
available from http://www.virtualbox.org. This file is free software;
@@ -199,4 +199,11 @@
+
+
+
+ 'array' attributes are not supported, use 'safearray="yes"' instead.
+
+
+
[propget] HRESULT
@@ -204,5 +211,11 @@
([out, retval]
+
+ SAFEARRAY(
+
+
+ )
+
* a
@@ -210,4 +223,5 @@
);
+
[propput] HRESULT
@@ -215,6 +229,17 @@
- ([in]
+ ([in
+
+
+ , out
+
+ ]
+
+ SAFEARRAY(
+
+
+ ) *
+
a
@@ -392,9 +417,13 @@
in
+
+
+ , out
+
- return array parameters are not currently supported
+ return 'array' parameters are not supported, use 'safearray="yes"' instead.
@@ -410,10 +439,6 @@
, size_is(
- ,
+ , *
-
- *
-
-
a
@@ -432,14 +457,18 @@
]
+
+ SAFEARRAY(
+
-
+
+ )
+
- *
-
-
- *
-
-
- a
+ *
+
+
+ *
+
+ a
@@ -457,13 +486,14 @@
+
+
+
+ either 'array' or 'safearray="yes"' attribute is allowed, but not both!
+
+
+
-
-
-
- either 'array' or 'mod' attribute is allowed, but not both!
-
-
@@ -498,5 +528,5 @@
- of attibute 'mod' is invalid!
+ of attribute 'mod' is invalid!
Index: /trunk/src/VBox/Main/idl/xpidl.xsl
===================================================================
--- /trunk/src/VBox/Main/idl/xpidl.xsl (revision 6850)
+++ /trunk/src/VBox/Main/idl/xpidl.xsl (revision 6851)
@@ -26,4 +26,17 @@
/////////////////////////////////////////////////////////////////////////////
-->
+
+
+
+
+
+
+
+
+
+ 'array' attributes are not supported, use 'safearray="yes"' instead.
+
+
@@ -219,13 +238,59 @@
[noscript]
-
-
- readonly
-
- attribute
-
-
-
- ;
+
+
+
+
+ void get
+
+
+
+ (
+
+ out unsigned long
+
+ Size,
+
+ [array, size_is(
+
+ Size), retval] out
+
+
+
+
);
+
+
+ void set
+
+
+
+ (
+
+ in unsigned long
+
+ Size,
+
+ [array, size_is(
+
+ Size)] in
+
+
+
+
);
+
+
+
+
+
+
+ readonly
+
+ attribute
+
+
+
+ ;
+
+
@@ -408,50 +473,75 @@
-->
-
-
-
-
- return array parameters are not currently supported
-
-
- [array,
-
-
-
+
+
+
+
+
+ in
+ out
+ out
+ in
+
+ unsigned long
+
+ Size,
+
+ [array, size_is(
+
+ Size)
+
+ ] in
+ ] out
+ , retval] out
+ ] in
+
+
+
+
+
+
+
+
+
-
-
- must have the same direction
+
+ return 'array' parameters are not supported, use 'safearray="yes"' instead.
- size_is(
-
- ,
-
-
- *
-
-
- )
-
-
-
-
- array attribute refers to non-existent param:
-
-
-
-
- ]
-
-
- in
- out
- [retval] out
- in
+ [array,
+
+
+
+
+
+
+ must have the same direction
+
+
+ size_is(
+
+ )
+
+
+
+
+ array attribute refers to non-existent param:
+
+
+
+
+ ]
+
+
+ in
+ out
+ [retval] out
+ in
+
+
+
+
+
-
-
-
@@ -466,13 +556,14 @@
+
+
+
+ either 'array' or 'safearray="yes"' attribute is allowed, but not both!
+
+
+
-
-
-
- either 'array' or 'mod' attribute is allowed, but not both!
-
-
@@ -507,5 +598,5 @@
- of attibute 'mod' is invalid!
+ of attribute 'mod' is invalid!
Index: /trunk/src/VBox/Main/include/USBControllerImpl.h
===================================================================
--- /trunk/src/VBox/Main/include/USBControllerImpl.h (revision 6850)
+++ /trunk/src/VBox/Main/include/USBControllerImpl.h (revision 6851)
@@ -137,5 +137,5 @@
ComObjPtr getDependentChild (IUSBDeviceFilter *aFilter)
{
- VirtualBoxBase *child = VirtualBoxBaseWithChildren::
+ VirtualBoxBase *child = VirtualBoxBaseWithChildrenNEXT::
getDependentChild (ComPtr (aFilter));
return child ? static_cast (child)
Index: /trunk/src/VBox/Main/include/VirtualBoxBase.h
===================================================================
--- /trunk/src/VBox/Main/include/VirtualBoxBase.h (revision 6850)
+++ /trunk/src/VBox/Main/include/VirtualBoxBase.h (revision 6851)
@@ -1446,5 +1446,5 @@
* VirtualBoxBase::uninit() implementations). This is done simply by
* calling the #uninitDependentChildren() method.
- *
+ *
*
* In order to let the above work, the following must be done:
@@ -1459,5 +1459,5 @@
* uninit() implementation must do is to check for readiness after acquiring
* the object's lock and return immediately if not ready.
- *
+ *
*
* Children added by #addDependentChild() are weakly referenced
@@ -1471,4 +1471,6 @@
* if #addDependentChild() or #removeDependentChild() are used incorrectly
* (called at inappropriate times). Check the above rules once more.
+ *
+ * @deprecated Use VirtualBoxBaseWithChildrenNEXT for new classes.
*/
class VirtualBoxBaseWithChildren : public VirtualBoxBase
@@ -1544,19 +1546,145 @@
};
-/**
- * Temporary class to disable deprecated methods of VirtualBoxBase.
- * Can be used as a base for components that are completely switched to
- * the new locking scheme (VirtualBoxBaseNEXT_base).
- *
- * @todo remove after we switch to VirtualBoxBaseNEXT completely.
- */
-class VirtualBoxBaseWithChildrenNEXT : public VirtualBoxBaseWithChildren
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ *
+ * Base class to track VirtualBoxBaseNEXT chlidren of the component.
+ *
+ * This class is a preferrable VirtualBoxBase replacement for components that
+ * operate with collections of child components. It gives two useful
+ * possibilities:
+ *
+ * -
+ * Given an IUnknown instance, it's possible to quickly determine
+ * whether this instance represents a child object created by the given
+ * component, and if so, get a valid VirtualBoxBase pointer to the child
+ * object. The returned pointer can be then safely casted to the
+ * actual class of the child object (to get access to its "internal"
+ * non-interface methods) provided that no other child components implement
+ * the same initial interface IUnknown is queried from.
+ *
-
+ * When the parent object uninitializes itself, it can easily unintialize
+ * all its VirtualBoxBase derived children (using their
+ * VirtualBoxBase::uninit() implementations). This is done simply by
+ * calling the #uninitDependentChildren() method.
+ *
+ *
+ * In order to let the above work, the following must be done:
+ * -
+ * When a child object is initialized, it calls #addDependentChild() of
+ * its parent to register itself within the list of dependent children.
+ *
-
+ * When a child object it is uninitialized, it calls
+ * #removeDependentChild() to unregister itself. Since the child's
+ * uninitialization may originate both from this method and from the child
+ * itself calling its uninit() on another thread at the same time, please
+ * make sure that #removeDependentChild() is called:
+ *
-
+ * after the child has successfully entered AutoUninitSpan -- to make
+ * sure this method is called only once for the given child object
+ * transitioning from Ready to NotReady. A failure to do so will at
+ * least likely cause an assertion ("Failed to remove the child from
+ * the map").
+ *
-
+ * outside the child object's lock -- to avoid guaranteed deadlocks
+ * caused by different lock order: (child_lock, map_lock) in uninit()
+ * and (map_lock, child_lock) in this method.
+ *
+ *
+ *
+ * Note that children added by #addDependentChild() are weakly referenced
+ * (i.e. AddRef() is not called), so when a child object is deleted externally
+ * (because it's reference count goes to zero), it will automatically remove
+ * itself from the map of dependent children provided that it follows the rules
+ * described here.
+ *
+ * @note Once again: because of weak referencing, deadlocks and assertions are
+ * very likely if #addDependentChild() or #removeDependentChild() are used
+ * incorrectly (called at inappropriate times). Check the above rules once
+ * more.
+ *
+ * @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
+ * VirtualBoxBaseNEXT implementation. Will completely supercede
+ * VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
+ * has gone.
+ */
+class VirtualBoxBaseWithChildrenNEXT : public VirtualBoxBaseNEXT
{
+public:
+
+ VirtualBoxBaseWithChildrenNEXT()
+ : mUninitDoneSem (NIL_RTSEMEVENT), mChildrenLeft (0)
+ {}
+
+ virtual ~VirtualBoxBaseWithChildrenNEXT()
+ {}
+
+ /**
+ * Adds the given child to the map of dependent children.
+ *
+ * Typically called from the child's init() method, from within the
+ * AutoInitSpan scope. Otherwise, VirtualBoxBase::AutoCaller must be
+ * used on @a aChild to make sure it is not uninitialized during this
+ * method's call.
+ *
+ * @param aChild Child object to add (must inherit VirtualBoxBase AND
+ * implement some interface).
+ */
+ template
+ void addDependentChild (C *aChild)
+ {
+ AssertReturnVoid (aChild);
+ doAddDependentChild (ComPtr (aChild), aChild);
+ }
+
+ /**
+ * Removes the given child from the map of dependent children.
+ *
+ * Make sure this method is called after the child has successfully entered
+ * AutoUninitSpan and outside the child lock.
+ *
+ * If called not from within the AutoUninitSpan scope,
+ * VirtualBoxBase::AutoCaller must be used on @a aChild to make sure it is
+ * not uninitialized during this method's call.
+ *
+ * @param aChild Child object to remove (must inherit VirtualBoxBase AND
+ * implement some interface).
+ */
+ template
+ void removeDependentChild (C *aChild)
+ {
+ AssertReturnVoid (aChild);
+ Assert (!aChild->isLockedOnCurrentThread());
+ doRemoveDependentChild (ComPtr (aChild));
+ }
+
+protected:
+
+ void uninitDependentChildren();
+
+ VirtualBoxBaseNEXT *getDependentChild (const ComPtr &aUnk);
+
private:
- void lock();
- void unlock();
- void setReady (bool isReady);
- bool isReady();
+ /// @todo temporarily reinterpret VirtualBoxBase * as VirtualBoxBaseNEXT *
+ // until ported HardDisk and Progress to the new scheme.
+ void doAddDependentChild (IUnknown *aUnk, VirtualBoxBase *aChild)
+ {
+ doAddDependentChild (aUnk,
+ reinterpret_cast (aChild));
+ }
+
+ void doAddDependentChild (IUnknown *aUnk, VirtualBoxBaseNEXT *aChild);
+ void doRemoveDependentChild (IUnknown *aUnk);
+
+ typedef std::map DependentChildren;
+ DependentChildren mDependentChildren;
+
+ RTSEMEVENT mUninitDoneSem;
+ size_t mChildrenLeft;
+
+ /* Protects all the fields above */
+ AutoLock::Handle mMapLock;
};
@@ -1579,4 +1707,6 @@
* @param C type of child objects (must inherit VirtualBoxBase AND
* implement some interface)
+ *
+ * @deprecated Use VirtualBoxBaseWithTypedChildrenNEXT for new classes.
*/
template
@@ -1709,25 +1839,124 @@
};
-/**
- * Temporary class to disable deprecated methods of VirtualBoxBase.
- * Can be used as a base for components that are completely switched to
- * the new locking scheme (VirtualBoxBaseNEXT_base).
- *
- * @todo remove after we switch to VirtualBoxBaseNEXT completely.
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Base class to track component's chlidren of the particular type.
+ *
+ * This class is similar to VirtualBoxBaseWithChildren, with the exception that
+ * all children must be of the same type. For this reason, it's not necessary to
+ * use a map to store children, so a list is used instead.
+ *
+ * As opposed to VirtualBoxBaseWithChildren, children added by
+ * #addDependentChild() are strongly referenced, so that they cannot be
+ * externally deleted until #removeDependentChild() is called. For this
+ * reason, strict rules of calling #removeDependentChild() don't apply to
+ * instances of this class -- it can be called anywhere in the child's uninit()
+ * implementation.
+ *
+ * @param C Type of child objects (must inherit VirtualBoxBase AND implementsome
+ * interface).
+ *
+ * @todo This is a VirtualBoxBaseWithChildren equivalent that uses the
+ * VirtualBoxBaseNEXT implementation. Will completely supercede
+ * VirtualBoxBaseWithChildren after the old VirtualBoxBase implementation
+ * has gone.
*/
template
-class VirtualBoxBaseWithTypedChildrenNEXT : public VirtualBoxBaseWithTypedChildren
+class VirtualBoxBaseWithTypedChildrenNEXT : public VirtualBoxBaseNEXT
{
public:
- typedef util::AutoLock AutoLock;
+ typedef std::list > DependentChildren;
+
+ VirtualBoxBaseWithTypedChildrenNEXT() : mInUninit (false) {}
+
+ virtual ~VirtualBoxBaseWithTypedChildrenNEXT() {}
+
+ /**
+ * Adds the given child to the list of dependent children.
+ *
+ * VirtualBoxBase::AutoCaller must be used on @a aChild to make sure it is
+ * not uninitialized during this method's call.
+ *
+ * @param aChild Child object to add (must inherit VirtualBoxBase AND
+ * implement some interface).
+ */
+ void addDependentChild (C *aChild)
+ {
+ AssertReturnVoid (aChild);
+
+ AutoLock alock (mMapLock);
+ if (mInUninit)
+ return;
+
+ mDependentChildren.push_back (aChild);
+ }
+
+ /**
+ * Removes the given child from the list of dependent children.
+ *
+ * VirtualBoxBase::AutoCaller must be used on @a aChild to make sure it is
+ * not uninitialized during this method's call.
+ *
+ * @param aChild the child object to remove (must inherit VirtualBoxBase
+ * AND implement some interface).
+ */
+ void removeDependentChild (C *aChild)
+ {
+ AssertReturnVoid (aChild);
+
+ AutoLock alock (mMapLock);
+ if (mInUninit)
+ return;
+
+ mDependentChildren.remove (aChild);
+ }
+
+protected:
+
+ /**
+ * Returns an internal lock handle used to lock the list of children
+ * returned by #dependentChildren(). This lock is to be used by AutoLock as
+ * follows:
+ *
+ * AutoLock alock (dependentChildrenLock());
+ *
+ */
+ AutoLock::Handle &dependentChildrenLock() const { return mMapLock; }
+
+ /**
+ * Returns the read-only list of all dependent children.
+ *
+ * @note Access the returned list (iterate, get size etc.) only after doing
+ * AutoLock alock (dependentChildrenLock())!
+ */
+ const DependentChildren &dependentChildren() const { return mDependentChildren; }
+
+ void uninitDependentChildren();
+
+ /**
+ * Removes (detaches) all dependent children registered with
+ * #addDependentChild(), without uninitializing them.
+ *
+ * @note This method must be called from under the main object's lock.
+ */
+ void removeDependentChildren()
+ {
+ /// @todo why?..
+ AssertReturnVoid (isLockedOnCurrentThread());
+
+ AutoLock alock (mMapLock);
+ mDependentChildren.clear();
+ }
private:
- void lock();
- void unlock();
- bool isLockedOnCurrentThread();
- void setReady (bool isReady);
- bool isReady();
+ DependentChildren mDependentChildren;
+
+ bool mInUninit;
+
+ /* Protects the two fields above */
+ mutable AutoLock::Handle mMapLock;
};