Changeset 13580 in vbox for trunk/include

Timestamp:

Oct 27, 2008 2:04:18 PM (16 years ago)

Author:

vboxsync

Message:

Ported s2 branch (r37120:38456).

Location:

trunk/include

Files:

• VBox/com/ErrorInfo.h (modified) (4 diffs)
• VBox/com/Guid.h (modified) (1 diff)
• VBox/com/SupportErrorInfo.h (added)
• VBox/com/VirtualBoxErrorInfo.h (added)
• VBox/com/array.h (modified) (23 diffs)
• VBox/com/defs.h (modified) (11 diffs)
• VBox/com/string.h (modified) (5 diffs)
• VBox/settings.h (modified) (2 diffs)
• iprt/log.h (modified) (1 diff)

trunk/include/VBox/com/ErrorInfo.h

@@ -362 +362 @@
      */
     ErrorInfoKeeper (bool aIsNull = false)
-        : ErrorInfo (false), mForgot (false)
+        : ErrorInfo (false), mForgot (aIsNull)
     {
         if (!aIsNull)
@@ -371 +371 @@
      *  Destroys this instance and automatically calls #restore() which will
      *  either restore error info fetched by the constructor or do nothing
-     *  if #forget() was called before destruction. */
+     *  if #forget() was called before destruction.
+     */
     ~ErrorInfoKeeper() { if (!mForgot) restore(); }
 
@@ -383 +384 @@
     {
         setNull();
+        mForgot = false;
         init (true /* aKeepObj */);
     }
@@ -388 +390 @@
     /**
      *  Restores error info fetched by the constructor and forgets it
-     *  afterwards.
+     *  afterwards. Does nothing if the error info was forgotten by #forget().
      *
      *  @return COM result of the restore operation.

trunk/include/VBox/com/Guid.h

@@ -65 +65 @@
     Guid (const Guid &that) { uuid = that.uuid; }
     Guid (const RTUUID &that) { uuid = that; }
-    Guid (const GUID &that) { ::memcpy (&uuid, &that, sizeof (GUID)); }
+
+    Guid (const GUID &that)
+    {
+        AssertCompileSize (GUID, sizeof (RTUUID));
+        ::memcpy (&uuid, &that, sizeof (GUID));
+    }
+
     Guid (const char *that)
     {

trunk/include/VBox/com/array.h

@@ -153 +153 @@
  * supported and therefore cannot be used as element types.
  *
- * In order to pass input BSTR array parameters delcared using the
- * ComSafeArrayIn (INPTR BSTR, aParam) macro to the SafeArray<> constructor
- * using the ComSafeArrayInArg() macro, you should use INPTR BSTR as the
- * SafeArray<> template argument, not just BSTR.
+ * Note that for GUID arrays you should use SafeGUIDArray and
+ * SafeConstGUIDArray, customized SafeArray<> specializations.
+ *
+ * Also note that in order to pass input BSTR array parameters delcared
+ * using the ComSafeArrayIn (INPTR BSTR, aParam) macro to the SafeArray<>
+ * constructor using the ComSafeArrayInArg() macro, you should use INPTR BSTR
+ * as the SafeArray<> template argument, not just BSTR.
  *
  * Arrays of interface pointers are also supported but they require to use a
@@ -183 +186 @@
  */
 #define ComSafeArrayAsInParam(aArray)   \
-    (aArray).size(), (aArray).__asInParam_Arr (aArray.raw())
+    (aArray).size(), (aArray).__asInParam_Arr ((aArray).raw())
 
 /**
@@ -214 +217 @@
 
 /**
- * Contains various helper constants for SafeArray.
+ * Provides various helpers for SafeArray.
+ *
+ * @param T Type of array elements.
  */
 template <typename T>
@@ -221 +226 @@
 protected:
 
+    /** Initializes memory for aElem. */
     static void Init (T &aElem) { aElem = 0; }
+
+    /** Initializes memory occupied by aElem. */
     static void Uninit (T &aElem) { aElem = 0; }
+
+    /** Creates a deep copy of aFrom and stores it in aTo. */
     static void Copy (const T &aFrom, T &aTo) { aTo = aFrom; }
 
@@ -248 +258 @@
 
     static void Init (PRUnichar * &aElem) { aElem = NULL; }
+
     static void Uninit (PRUnichar * &aElem)
     {
@@ -300 +311 @@
 };
 
+template<>
+struct SafeArrayTraits <nsID *>
+{
+protected:
+
+    static void Init (nsID * &aElem) { aElem = NULL; }
+
+    static void Uninit (nsID * &aElem)
+    {
+        if (aElem)
+        {
+            ::nsMemory::Free (aElem);
+            aElem = NULL;
+        }
+    }
+
+    static void Copy (const nsID * aFrom, nsID * &aTo)
+    {
+        if (aFrom)
+        {
+            aTo = (nsID *) ::nsMemory::Alloc (sizeof (nsID));
+            if (aTo)
+                *aTo = *aFrom;
+        }
+        else
+            aTo = NULL;
+    }
+
+    /* This specification is also reused for SafeConstGUIDArray, so provide a
+     * no-op Init() and Uninit() which are necessary for SafeArray<> but should
+     * be never called in context of SafeConstGUIDArray. */
+
+    static void Init (const nsID * &aElem) { NOREF (aElem); AssertFailed(); }
+    static void Uninit (const nsID * &aElem) { NOREF (aElem); AssertFailed(); }
+
+public:
+
+    /** Magic to workaround strict rules of par. 4.4.4 of the C++ standard. */
+    static const nsID **__asInParam_Arr (nsID **aArr)
+    {
+        return const_cast <const nsID **> (aArr);
+    }
+    static const nsID **__asInParam_Arr (const nsID **aArr) { return aArr; }
+};
+
 #else /* defined (VBOX_WITH_XPCOM) */
 
@@ -305 +361 @@
 
 /**
- * Contains various helper constants for SafeArray.
+ * Provides various helpers for SafeArray.
+ *
+ * @param T Type of array elements.
+ *
+ * Specializations of this template must provide the following methods:
+ *
+    // Returns the VARTYPE of COM SafeArray elements to be used for T
+    static VARTYPE VarType();
+
+    // Returns the number of VarType() elements necessary for aSize
+    // elements of T
+    static ULONG VarCount (size_t aSize);
+
+    // Returns the number of elements of T that occupy the given number of
+    // VarType() elements (opposite to VarCount (size_t aSize)).
+    static size_t Size (ULONG aVarCount);
+
+    // Creates a deep copy of aFrom and stores it in aTo
+    static void Copy (ULONG aFrom, ULONG &aTo);
  */
 template <typename T>
 struct SafeArrayTraits
 {
-    // Arbitrary types are not supported
+    // Arbitrary types are not supported -- no helpers
 };
 
@@ -319 +393 @@
 
     static VARTYPE VarType() { return VT_I4; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
+
     static void Copy (LONG aFrom, LONG &aTo) { aTo = aFrom; }
 };
@@ -328 +405 @@
 
     static VARTYPE VarType() { return VT_UI4; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
+
     static void Copy (ULONG aFrom, ULONG &aTo) { aTo = aFrom; }
 };
@@ -337 +417 @@
 
     static VARTYPE VarType() { return VT_I8; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
+
     static void Copy (LONG64 aFrom, LONG64 &aTo) { aTo = aFrom; }
 };
@@ -346 +429 @@
 
     static VARTYPE VarType() { return VT_UI8; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
+
     static void Copy (ULONG64 aFrom, ULONG64 &aTo) { aTo = aFrom; }
 };
@@ -355 +441 @@
 
     static VARTYPE VarType() { return VT_BSTR; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
 
     static void Copy (BSTR aFrom, BSTR &aTo)
@@ -360 +448 @@
         aTo = aFrom ? ::SysAllocString ((const OLECHAR *) aFrom) : NULL;
     }
+};
+
+template<>
+struct SafeArrayTraits <GUID>
+{
+protected:
+
+    /* Use the 64-bit unsigned integer type for GUID */
+    static VARTYPE VarType() { return VT_UI8; }
+
+    /* GUID is 128 bit, so we need two VT_UI8 */
+    static ULONG VarCount (size_t aSize)
+    {
+        AssertCompileSize (GUID, 16);
+        return (ULONG) (aSize * 2);
+    }
+
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount / 2; }
+
+    static void Copy (GUID aFrom, GUID &aTo) { aTo = aFrom; }
 };
 
@@ -418 +526 @@
      * 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
+     * always wrap the parameter name in the ComSafeArrayInArg macro call like
      * this:
      * <pre>
@@ -460 +568 @@
         m.isWeak = true;
 
-        AssertReturnVoid (accessRaw() != NULL);
+        AssertReturnVoid (m.arr == NULL || accessRaw() != NULL);
 
 #endif /* defined (VBOX_WITH_XPCOM) */
@@ -466 +574 @@
 
     /**
-     * Creates a deep copy of the goven standard C++ container.
+     * Creates a deep copy of the given standard C++ container.
      *
      * @param aCntr Container object to copy.
@@ -479 +587 @@
         AssertReturnVoid (!isNull());
 
-        int i = 0;
+        size_t i = 0;
         for (typename C <T>::const_iterator it = aCntr.begin();
              it != aCntr.end(); ++ it, ++ i)
@@ -526 +634 @@
 #else
         if (m.arr)
-            return m.arr->rgsabound [0].cElements;
+            return Size (m.arr->rgsabound [0].cElements);
         return 0;
 #endif
@@ -576 +684 @@
 #else
 
-        SAFEARRAYBOUND bound = { (ULONG)aNewSize, 0 };
+        SAFEARRAYBOUND bound = { VarCount (aNewSize), 0 };
         m.arr = SafeArrayCreate (VarType(), 1, &bound);
         AssertReturn (m.arr != NULL, false);
@@ -678 +786 @@
 
     /**
-     * Transfers the ownership of this array's data to a method parameter
+     * Transfers the ownership of this array's data to the specified location
      * declared using the ComSafeArrayOut macro and makes this array a null
      * array. When using this call, always wrap the parameter name in the
@@ -686 +794 @@
      * </pre>
      *
+     * Detaching the null array is also possible in which case the location will
+     * receive NULL.
+     *
      * @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.
+     * @param aArg  Location to detach to.
      */
     virtual SafeArray &detachTo (ComSafeArrayOut (T, aArg))
@@ -842 +953 @@
 #if defined (VBOX_WITH_XPCOM)
 
+/**
+ * Version of com::SafeArray for arrays of GUID.
+ *
+ * In MS COM, GUID arrays store GUIDs by value and therefore input arrays are
+ * represented using |GUID *| and out arrays -- using |GUID **|. In XPCOM,
+ * GUID arrays store pointers to nsID so that input arrays are |const nsID **|
+ * and out arrays are |nsID ***|. Due to this difference, it is impossible to
+ * work with arrays of GUID on both platforms by simply using com::SafeArray
+ * <GUID>. This class is intended to provide some leve of cross-platform
+ * behavior.
+ *
+ * The basic usage pattern is basically similar to com::SafeArray<> except that
+ * you use ComSafeGUIDArrayIn* and ComSafeGUIDArrayOut* macros instead of
+ * ComSafeArrayIn* and ComSafeArrayOut*. Another important nuance is that the
+ * raw() array type is different (nsID **, or GUID ** on XPCOM and GUID * on MS
+ * COM) so it is recommended to use operator[] instead that always returns a
+ * GUID by value.
+ *
+ * Note that due to const modifiers, you cannot use SafeGUIDArray for input GUID
+ * arrays. Please use SafeConstGUIDArray for this instead.
+ *
+ * Other than mentioned above, the functionality of this class is equivalent to
+ * com::SafeArray<>. See the description of that template and its methods for
+ * more information.
+ *
+ * Output GUID arrays are handled by a separate class, SafeGUIDArrayOut, since
+ * this class cannot handle them because of const modifiers.
+ */
+class SafeGUIDArray : public SafeArray <nsID *>
+{
+public:
+
+    typedef SafeArray <nsID *> Base;
+
+    class nsIDRef
+    {
+    public:
+
+        nsIDRef (nsID * &aVal) : mVal (aVal) {}
+
+        operator const nsID &() const { return mVal ? *mVal : *Empty; }
+        operator nsID() const { return mVal ? *mVal : *Empty; }
+
+        const nsID *operator&() const { return mVal ? mVal : Empty; }
+
+        nsIDRef &operator= (const nsID &aThat)
+        {
+            if (mVal == NULL)
+                Copy (&aThat, mVal);
+            else
+                *mVal = aThat;
+            return *this;
+        }
+
+    private:
+
+        nsID * &mVal;
+
+        static const nsID *Empty;
+
+        friend class SafeGUIDArray;
+    };
+
+    /** See SafeArray<>::SafeArray(). */
+    SafeGUIDArray() {}
+
+    /** See SafeArray<>::SafeArray (size_t). */
+    SafeGUIDArray (size_t aSize) : Base (aSize) {}
+
+    /**
+     * Array access operator that returns an array element by reference. As a
+     * special case, the return value of this operator on XPCOM is a nsID (GUID)
+     * reference, instead of a nsID pointer (the actual SafeArray template
+     * argument), for compatibility with the MS COM version.
+     *
+     * The rest is equivalent to SafeArray<>::operator[].
+     */
+    nsIDRef operator[] (size_t aIdx)
+    {
+        Assert (m.arr != NULL);
+        Assert (aIdx < size());
+        return nsIDRef (m.arr [aIdx]);
+    }
+
+    /**
+    * Const version of #operator[] that returns an array element by value.
+    */
+    const nsID &operator[] (size_t aIdx) const
+    {
+        Assert (m.arr != NULL);
+        Assert (aIdx < size());
+        return m.arr [aIdx] ? *m.arr [aIdx] : *nsIDRef::Empty;
+    }
+};
+
+/**
+ * Version of com::SafeArray for const arrays of GUID.
+ *
+ * This class is used to work with input GUID array parameters in method
+ * implementaitons. See SafeGUIDArray for more details.
+ */
+class SafeConstGUIDArray : public SafeArray <const nsID *,
+                                            SafeArrayTraits <nsID *> >
+{
+public:
+
+    typedef SafeArray <const nsID *, SafeArrayTraits <nsID *> > Base;
+
+    /** See SafeArray<>::SafeArray(). */
+    SafeConstGUIDArray() {}
+
+    /* See SafeArray<>::SafeArray (ComSafeArrayIn (T, aArg)). */
+    SafeConstGUIDArray (ComSafeGUIDArrayIn (aArg))
+        : Base (ComSafeGUIDArrayInArg (aArg)) {}
+
+    /**
+     * Array access operator that returns an array element by reference. As a
+     * special case, the return value of this operator on XPCOM is nsID (GUID)
+     * instead of nsID *, for compatibility with the MS COM version.
+     *
+     * The rest is equivalent to SafeArray<>::operator[].
+     */
+    const nsID &operator[] (size_t aIdx) const
+    {
+        AssertReturn (m.arr != NULL,  **((const nsID * *) NULL));
+        AssertReturn (aIdx < size(), **((const nsID * *) NULL));
+        return *m.arr [aIdx];
+    }
+
+private:
+
+    /* These are disabled because of const */
+    bool reset (size_t aNewSize) { NOREF (aNewSize); return false; }
+};
+
+#else /* defined (VBOX_WITH_XPCOM) */
+
+typedef SafeArray <GUID> SafeGUIDArray;
+typedef SafeArray <const GUID, SafeArrayTraits <GUID> > SafeConstGUIDArray;
+
+#endif /* defined (VBOX_WITH_XPCOM) */
+
+////////////////////////////////////////////////////////////////////////////////
+
+#if defined (VBOX_WITH_XPCOM)
+
 template <class I>
 struct SafeIfaceArrayTraits
@@ -883 +1140 @@
 
     static VARTYPE VarType() { return VT_UNKNOWN; }
+    static ULONG VarCount (size_t aSize) { return (ULONG) aSize; }
+    static size_t Size (ULONG aVarCount) { return (size_t) aVarCount; }
 
     static void Copy (I * aFrom, I * &aTo)

trunk/include/VBox/com/defs.h

@@ -71 +71 @@
 #ifndef VBOX_COM_NO_ATL
 # include <atlbase.h>
+#include <atlcom.h>
 #endif
 
@@ -85 +86 @@
 #define SUCCEEDED_WARNING(rc)   (SUCCEEDED (rc) && (rc) != S_OK)
 
-/* input pointer argument to method */
+/** Input pointer argument prefix in the interface method declaration. */
 #define INPTR
 
-/* makes the name of the getter interface function (n must be capitalized) */
+/** Makes the name of the getter interface function (n must be capitalized). */
 #define COMGETTER(n)    get_##n
-/* makes the name of the setter interface function (n must be capitalized) */
+/** Makes the name of the setter interface function (n must be capitalized). */
 #define COMSETTER(n)    put_##n
 
-/* a type for an input GUID parameter in the interface method declaration */
+/** Type for an input GUID parameter in the interface method declaration. */
 #define GUIDPARAM           GUID
-/* a type for an output GUID parameter in the interface method declaration */
+/** Type for an output GUID parameter in the interface method declaration. */
 #define GUIDPARAMOUT        GUID*
 
@@ -120 +121 @@
  * which makes it impossible to use it for reading safearray data.
  */
-#define ComSafeArrayInIsNull(aArg)      (aArg == NULL || *aArg == NULL)
+#define ComSafeArrayInIsNull(aArg)      ((aArg) == NULL || *(aArg) == NULL)
 
 /**
@@ -155 +156 @@
  * which makes it impossible to use it for returning a safearray.
  */
-#define ComSafeArrayOutIsNull(aArg)     (aArg == NULL)
+#define ComSafeArrayOutIsNull(aArg)     ((aArg) == NULL)
 
 /**
@@ -166 +167 @@
  */
 #define ComSafeArrayOutArg(aArg)        aArg
+
+/**
+ * Version of ComSafeArrayIn for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayIn(aArg)        SAFEARRAY **aArg
+
+/**
+ * Version of ComSafeArrayInIsNull for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayInIsNull(aArg)  ComSafeArrayInIsNull (aArg)
+
+/**
+ * Version of ComSafeArrayInArg for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayInArg(aArg)     ComSafeArrayInArg (aArg)
+
+/**
+ * Version of ComSafeArrayOut for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayOut(aArg)       SAFEARRAY **aArg
+
+/**
+ * Version of ComSafeArrayOutIsNull for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayOutIsNull(aArg) ComSafeArrayOutIsNull (aArg)
+
+/**
+ * Version of ComSafeArrayOutArg for GUID.
+ * @param aArg Parameter name to wrap.
+ */
+#define ComSafeGUIDArrayOutArg(aArg)    ComSafeArrayOutArg (aArg)
 
 /**
@@ -230 +267 @@
 #define TRUE PR_TRUE
 
-/* makes the name of the getter interface function (n must be capitalized) */
+/** Input pointer argument prefix in the interface method declaration. */
+#define INPTR const
+
+/** Makes the name of the getter interface function (n must be capitalized). */
 #define COMGETTER(n)    Get##n
-/* makes the name of the setter interface function (n must be capitalized) */
+/** Makes the name of the setter interface function (n must be capitalized). */
 #define COMSETTER(n)    Set##n
 
-/* a type to define a raw GUID variable (better to use the Guid class) */
+/**
+ * Type to define a raw GUID variable (for members use the com::Guid class
+ * instead).
+ */
 #define GUID                nsID
-/* a type for an input GUID parameter in the interface method declaration */
+/** Type for an input GUID parameter in the interface method declaration. */
 #define GUIDPARAM           nsID &
-/* a type for an output GUID parameter in the interface method declaration */
+/** 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 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 ComSafeArrayOutIsNull(aArg)         ((aArg) == NULL)
 #define ComSafeArrayOutArg(aArg)            aArg##Size, aArg
+
+/* safearray input parameter macros for GUID */
+#define ComSafeGUIDArrayIn(aArg)            PRUint32 aArg##Size, const nsID **aArg
+#define ComSafeGUIDArrayInIsNull(aArg)      ComSafeArrayInIsNull (aArg)
+#define ComSafeGUIDArrayInArg(aArg)         ComSafeArrayInArg (aArg)
+
+/* safearray output parameter macros for GUID */
+#define ComSafeGUIDArrayOut(aArg)           PRUint32 *aArg##Size, nsID ***aArg
+#define ComSafeGUIDArrayOutIsNull(aArg)     ComSafeArrayOutIsNull (aArg)
+#define ComSafeGUIDArrayOutArg(aArg)        ComSafeArrayOutArg (aArg)
 
 /* CLSID and IID for compatibility with Win32 */
@@ -257 +310 @@
 
 /* OLE error codes */
-#define S_OK                NS_OK
+#define S_OK                ((nsresult) NS_OK)
 #define E_UNEXPECTED        NS_ERROR_UNEXPECTED
 #define E_NOTIMPL           NS_ERROR_NOT_IMPLEMENTED
@@ -290 +343 @@
     virtual ~CComObject() { this->FinalRelease(); }
 };
-
-/* input pointer argument to method */
-#define INPTR const
 
 /* helper functions */
@@ -403 +453 @@
 
 /**
+ * "First worst" result type.
+ *
+ * Variables of this class are used instead of HRESULT variables when it is
+ * desirable to memorize the "first worst" result code instead of the last
+ * assigned one. In other words, an assignment operation to a variable of this
+ * class will succeed only if the result code to assign has worse severity. The
+ * following table demonstrate this (the first column lists the previous result
+ * code stored in the variable, the first row lists the new result code being
+ * assigned, 'A' means the assignment will take place, '> S_OK' means a warning
+ * result code):
+ *
+ * {{{
+ *             FAILED    > S_OK    S_OK
+ * FAILED        -         -         -
+ * > S_OK        A         -         -
+ * S_OK          A         A         -
+ *
+ * }}}
+ *
+ * On practice, you will need to use a FWResult variable when you call some COM
+ * method B after another COM method A fails and want to return the result code
+ * of A even if B also fails, but want to return the failed result code of B if
+ * A issues a warning or succeeds.
+ */
+class FWResult
+{
+
+public:
+
+    /**
+     * Constructs a new variable. Note that by default this constructor sets the
+     * result code to E_FAIL to make sure a failure is returned to the caller if
+     * the variable is never assigned another value (which is considered as the
+     * improper use of this class).
+     */
+    FWResult (HRESULT aRC = E_FAIL) : mRC (aRC) {}
+
+    FWResult &operator= (HRESULT aRC)
+    {
+        if ((FAILED (aRC) && !FAILED (mRC)) ||
+            (mRC == S_OK && aRC != S_OK))
+            mRC = aRC;
+
+        return *this;
+    }
+
+    operator HRESULT() const { return mRC; }
+
+    HRESULT *operator&() { return &mRC; }
+
+private:
+
+    HRESULT mRC;
+};
+
+/**
  * "Last worst" result type.
  *
@@ -411 +517 @@
  * severity. The following table demonstrate this (the first column lists the
  * previous result code stored in the variable, the first row lists the new
- * result code being assigned, 'A' means the assignment will take place):
+ * assigned, 'A' means the assignment will take place, '> S_OK' means a warning
+ * result code):
  *
  * {{{
@@ -420 +527 @@
  *
  * }}}
+ *
+ * On practice, you will need to use a LWResult variable when you call some COM
+ * method B after COM method A fails and want to return the result code of B
+ * if B also fails, but still want to return the failed result code of A if B
+ * issues a warning or succeeds.
  */
 class LWResult

trunk/include/VBox/com/string.h

@@ -243 +243 @@
     static const Bstr Null;
 
-private:
+protected:
 
     void safe_assign (const BSTR str)
@@ -273 +273 @@
     BSTR bstr;
 
-    friend class Utf8Str; // to access our raw_copy()
+    friend class Utf8Str; /* to access our raw_copy() */
 };
 
-// symmetric compare operators
+/* symmetric compare operators */
 inline bool operator== (const BSTR l, const Bstr &r) { return r.operator== (l); }
 inline bool operator!= (const BSTR l, const Bstr &r) { return r.operator!= (l); }
@@ -479 +479 @@
     static const Utf8Str Null;
 
-private:
+protected:
 
     void safe_assign (const char *s)
@@ -517 +517 @@
     char *str;
 
-    friend class Bstr; // to access our raw_copy()
+    friend class Bstr; /* to access our raw_copy() */
 };
 
@@ -628 +628 @@
 };
 
+/**
+ * THe BstrFmt class is a shortcut to <tt>Bstr (Utf8StrFmt (...))</tt>.
+ */
+class BstrFmt : public Bstr
+{
+public:
+
+    /**
+     * Constructs a new string given the format string and the list of the
+     * arguments for the format string.
+     *
+     * @param aFormat   printf-like format string (in UTF-8 encoding).
+     * @param ...       List of the arguments for the format string.
+     */
+    explicit BstrFmt (const char *aFormat, ...)
+    {
+        va_list args;
+        va_start (args, aFormat);
+        raw_copy (bstr, Utf8StrFmtVA (aFormat, args));
+        va_end (args);
+    }
+};
+
+/**
+ * THe BstrFmtVA class is a shortcut to <tt>Bstr (Utf8StrFmtVA (...))</tt>.
+ */
+class BstrFmtVA : public Bstr
+{
+public:
+
+    /**
+     * Constructs a new string given the format string and the list of the
+     * arguments for the format string.
+     *
+     * @param aFormat   printf-like format string (in UTF-8 encoding).
+     * @param aArgs     List of arguments for the format string
+     */
+    BstrFmtVA (const char *aFormat, va_list aArgs)
+    {
+        raw_copy (bstr, Utf8StrFmtVA (aFormat, aArgs));
+    }
+};
+
 } /* namespace com */
 

trunk/include/VBox/settings.h

@@ -250 +250 @@
  * Shut up MSVC complaining that auto_ptr[_ref] template instantiations (as a
  * result of private data member declarations of some classes below) need to
- * be exported too to in order to be accessible by clients. I don't
+ * be exported too to in order to be accessible by clients.
  *
  * The alternative is to instantiate a template before the data member
  * declaration with the VBOXSETTINGS_CLASS prefix, but the standard disables
- * explicit instantiations in a foreign namespace. However, a declaration
+ * explicit instantiations in a foreign namespace. In other words, a declaration
  * like:
  *
@@ -261 +261 @@
  * right before the member declaration makes MSVC happy too, but this is not a
  * valid C++ construct (and G++ spits it out). So, for now we just disable the
- * warning and will come back to this problem one dat later.
+ * warning and will come back to this problem one day later.
  *
  * We also disable another warning (4275) saying that a DLL-exported class

trunk/include/iprt/log.h

@@ -621 +621 @@
 #ifdef LOG_USE_C99
 # define LogTraceMsg(a) \
-    _LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, ">>>>> %s (%d): %M" LOG_FN_FMT, __FILE__, __LINE__, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
+    _LogIt(LOG_INSTANCE, RTLOGGRPFLAGS_FLOW, LOG_GROUP, ">>>>> %s (%d): " LOG_FN_FMT ": %M", __FILE__, __LINE__, __PRETTY_FUNCTION__, _LogRemoveParentheseis a )
 #else
 # define LogTraceMsg(a) \
-    do {  LogFlow((">>>>> %s (%d): " LOG_FN_FMT, __FILE__, __LINE__, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
+    do {  LogFlow((">>>>> %s (%d): " LOG_FN_FMT ": ", __FILE__, __LINE__, __PRETTY_FUNCTION__)); LogFlow(a); } while (0)
 #endif