Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Side by Side Diff: src/plugin/COM_Value.h

Issue 5070706781978624: Issue #276 - introduce class BSTR_Argument (Closed)
Patch Set: Created July 29, 2014, 4:58 p.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « src/plugin/AdblockPlusDomTraverser.cpp ('k') | src/plugin/COM_Value.cpp » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 /**
2 * \file COM_Value.h Support for the values used in COM and Automation.
3 */
4 #ifndef COM_VALUE_H
5 #define COM_VALUE_H
6
7 #include <wtypes.h>
8 #include <string>
9
10 namespace AdblockPlus
11 {
12 namespace COM
13 {
14 /**
15 * BSTR life cycle manager. Used by a caller to pass BSTR as an argument to a COM call.
16 *
17 * This class manages the life cycle of a BSTR passed as an argument to a CO M call.
18 * There are two different life cycles relevant here.
19 * In the first, the BSTR acts as an ordinary argument; in the second, the B STR is a return value.
20 * Both these are implemented as arguments to a COM function;
21 * the difference is that one is an [in] param and the other is an [out].
22 * In both cases, we must release an allocated string, whether or not we all ocated it.
23 * Because of this commonality, it's possible to combine these two uses into a single class.
24 *
25 * The two life cycles differ in how the allocation is done.
26 * When used as an argument, the caller must allocate.
27 * In this case the caller uses the non-trivial constructor, which allocates a copy of its argument.
28 * When used for a result, the called function allocates.
29 * In this case the caller uses the default constructor and the address-of o perator;
30 * the address-of operator does not allocate and its pointer must be assig ned an allocated value.
31 *
32 * Copy/move constructor/assignment are all deleted, not because they couldn 't be implemented,
33 * but because these class are meant to be used in tight conjunction with API calls.
34 * Thus their design use requires that they not leave this proximity.
35 *
36 * \par Reference
37 * MSDN "Allocating and Releasing Memory for a BSTR" http://msdn.microsoft .com/en-us/library/vstudio/xda6xzx7%28v=vs.120%29.aspx
38 * "When you call into a function that expects a BSTR argument, you must a llocate the memory for the BSTR before the call and release it afterwards."
39 * "When you call into a function that returns a BSTR, you must free the s tring yourself."
40 *
41 * \invariant Either bstr == nullptr or bstr is a non-null system-allocated BSTR.
42 */
43 class BSTR_Argument
44 {
45 /**
46 * The underlying BSTR pointer.
47 */
48 BSTR bstr;
49
50 public:
51 /**
52 * Default constructor has the value of the empty string.
53 */
54 BSTR_Argument()
55 : bstr(nullptr)
56 {
57 }
58
59 /**
60 * Constructor from std::wstring.
61 */
62 BSTR_Argument(const std::wstring& s);
63
64 /**
65 * Destructor
66 *
67 * The destructor frees the BSTR.
68 * Do not use this class when freeing the BSTR is not our responsibility.
69 */
70 ~BSTR_Argument();
71
72 /**
73 * Conversion operator to BSTR.
74 */
75 operator BSTR() const
76 {
77 return bstr;
78 }
79
80 /**
81 * Conversion operator to std::wstring
82 */
83 operator std::wstring() const;
84
85 /**
86 * Address-of operator.
87 *
88 * This operator is used for assignment directly into our underlying point er.
89 * In order to avoid leaking memory, this operator also implicitly assigns the null string.
90 * Specifically, this operator is not 'const'.
91 *
92 * \par postcondition
93 * bstr == nullptr
94 */
95 BSTR* operator&();
96
97 private:
98 /**
99 * Copy constructor is deleted
100 */
101 BSTR_Argument(const BSTR_Argument&); // = delete
102
103 /**
104 * Move constructor is deleted
105 */
106 BSTR_Argument(BSTR_Argument&&); // = delete
107
108 /**
109 * Copy assignment is deleted
110 */
111 BSTR_Argument& operator=(const BSTR_Argument&); // = delete
112
113 /**
114 * Move assignment is deleted
115 */
116 BSTR_Argument& operator=(BSTR_Argument&&); // = delete
117 };
118 }
119 }
120
121 #endif
OLDNEW
« no previous file with comments | « src/plugin/AdblockPlusDomTraverser.cpp ('k') | src/plugin/COM_Value.cpp » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld