Issue #276 - introduce class BSTR_Argument

src/plugin/COM_Value.h

+/**
+ * \file COM_Value.h Support for the values used in COM and Automation.

[sergei, 2014/07/28 09:18:26]

All current comments in this file look redundant.

+ */
+#ifndef COM_VALUE_H
+#define COM_VALUE_H
+
+#include <wtypes.h>
+#include <string>
+
+namespace AdblockPlus
+{
+  namespace COM
+  {
+    /**
+     * BSTR life cycle manager. Used by a caller to pass BSTR as an argument to a COM call.
+     *
+     * This class manages the life cycle of a BSTR passed as an argument to a COM call.
+     * There are two different life cycles relevant here.
+     * In the first, the BSTR acts as an ordinary argument; in the second, the BSTR is a return value.
+     * Both these are implemented as arguments to a COM function;
+     *   the difference is that one is an [in] param and the other is an [out].
+     * In both cases, we must release an allocated string, whether or not we allocated it.
+     * Because of this commonality, it's possible to combine these two uses into a single class.
+     *
+     * The two life cycles differ in how the allocation is done.
+     * When used as an argument, the caller must allocate.
+     * In this case the caller uses the non-trivial constructor, which allocates a copy of its argument.
+     * When used for a result, the called function allocates.
+     * In this case the caller uses the default constructor and the address-of operator;
+     *   the address-of operator does not allocate and its pointer must be assigned an allocated value.
+     *
+     * Copy/move constructor/assignment are all deleted, not because they couldn't be implemented, 
+     *   but because these class are meant to be used in tight conjunction with API calls.
+     * Thus their design use requires that they not leave this proximity.
+     *
+     * \par Reference
+     *   MSDN "Allocating and Releasing Memory for a BSTR" http://msdn.microsoft.com/en-us/library/vstudio/xda6xzx7%28v=vs.120%29.aspx
+     *   "When you call into a function that expects a BSTR argument, you must allocate the memory for the BSTR before the call and release it afterwards."
+     *   "When you call into a function that returns a BSTR, you must free the string yourself."
+     *
+     * \invariant Either bstr == nullptr or bstr is a non-null system-allocated BSTR.
+     */
+    class BSTR_Argument
+    {
+      /**
+       * The underlying BSTR pointer.
+       */
+       BSTR bstr;
+
+    public:
+      /**
+       * Default constructor has the value of the empty string.
+       */
+      BSTR_Argument()
+        : bstr( nullptr )
+      {
+      }
+
+      /**
+       * Constructor from std::wstring.
+       */
+      BSTR_Argument( const std::wstring& s );

[sergei, 2014/07/28 09:18:26]

explicit

[Eric, 2014/07/29 16:59:27]

Why? There's no need for it. There's no context where there will ever be any
ambiguity. This class will never be an argument to anything.

[sergei, 2014/07/30 10:10:54]

No assumptions.

+
+      /**
+       * Destructor
+       *
+       * The destructor frees the BSTR.
+       * Do not use this class when freeing the BSTR is not our responsibility.
+       */
+      ~BSTR_Argument();
+
+      /**
+       * Conversion operator to BSTR.
+       */
+      operator BSTR() const

[sergei, 2014/07/28 09:18:26]

operator const BSTR() const

[Eric, 2014/07/29 16:59:27]

There's no such thing as a 'const BSTR'. Tried it before; it causes all sorts of
havoc with respect to the rest of the Microsoft declarations.

[sergei, 2014/07/30 10:10:54]

I've tried it also and it works.
struct X {
  operator const BSTR() const;
};

[Eric, 2014/07/30 14:14:42]

I did not say you couldn't declare it. What I said is that if you do declare it
wreaks havoc when you start using it.

I also said that I have been down that road. If you don't trust my experience,
perhaps you might develop some of your own. I assure you it will be nothing but
frustration.

+      {
+        return bstr;
+      }
+
+      /**
+       * Conversion operator to std::wstring
+       */
+      operator std::wstring() const;
+
+      /**
+       * Address-of operator.
+       *
+       * This operator is used for assignment directly into our underlying pointer.
+       * In order to avoid leaking memory, this operator also implicitly assigns the null string.
+       * Specifically, this operator is not 'const'.
+       *
+       * \postcondition
+       *   bstr == nullptr
+       */
+      BSTR* operator&();
+
+    private:
+      /**
+       * Copy constructor is deleted
+       */
+      BSTR_Argument( const BSTR_Argument& ); // = delete
+
+      /**
+       * Move constructor is deleted
+       */
+      BSTR_Argument( BSTR_Argument&& ); // = delete
+
+      /**
+       * Copy assignment is deleted
+       */
+      BSTR_Argument& operator=( const BSTR_Argument& ); // = delete
+
+      /**
+       * Move assignment is deleted
+       */
+      BSTR_Argument& operator=( BSTR_Argument&& ); // = delete
+    };
+  }
+}
+
+#endif