1 // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_SCOPED_BSTR_WIN_H_ 6 #define BASE_SCOPED_BSTR_WIN_H_ 7 8 #include <windows.h> 9 #include <oleauto.h> 10 11 #include "base/logging.h" 12 13 // Manages a BSTR string pointer. 14 // The class interface is based on scoped_ptr. 15 class ScopedBstr { 16 public: 17 ScopedBstr() : bstr_(NULL) { 18 } 19 20 // Constructor to create a new BSTR. 21 // NOTE: Do not pass a BSTR to this constructor expecting ownership to 22 // be transferred - even though it compiles! ;-) 23 explicit ScopedBstr(const wchar_t* non_bstr); 24 ~ScopedBstr(); 25 26 // Give ScopedBstr ownership over an already allocated BSTR or NULL. 27 // If you need to allocate a new BSTR instance, use |allocate| instead. 28 void Reset(BSTR bstr = NULL); 29 30 // Releases ownership of the BSTR to the caller. 31 BSTR Release(); 32 33 // Creates a new BSTR from a wide string. 34 // If you already have a BSTR and want to transfer ownership to the 35 // ScopedBstr instance, call |reset| instead. 36 // Returns a pointer to the new BSTR, or NULL if allocation failed. 37 BSTR Allocate(const wchar_t* wide_str); 38 39 // Allocates a new BSTR with the specified number of bytes. 40 // Returns a pointer to the new BSTR, or NULL if allocation failed. 41 BSTR AllocateBytes(int bytes); 42 43 // Sets the allocated length field of the already-allocated BSTR to be 44 // |bytes|. This is useful when the BSTR was preallocated with e.g. 45 // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and 46 // then not all the bytes are being used. 47 // Note that if you want to set the length to a specific number of characters, 48 // you need to multiply by sizeof(wchar_t). Oddly, there's no public API to 49 // set the length, so we do this ourselves by hand. 50 // 51 // NOTE: The actual allocated size of the BSTR MUST be >= bytes. 52 // That responsibility is with the caller. 53 void SetByteLen(uint32 bytes); 54 55 // Swap values of two ScopedBstr's. 56 void Swap(ScopedBstr& bstr2); 57 58 // Retrieves the pointer address. 59 // Used to receive BSTRs as out arguments (and take ownership). 60 // The function DCHECKs on the current value being NULL. 61 // Usage: GetBstr(bstr.Receive()); 62 BSTR* Receive(); 63 64 // Returns number of chars in the BSTR. 65 uint32 Length() const; 66 67 // Returns the number of bytes allocated for the BSTR. 68 uint32 ByteLength() const; 69 70 operator BSTR() const { 71 return bstr_; 72 } 73 74 protected: 75 BSTR bstr_; 76 77 private: 78 // Forbid comparison of ScopedBstr types. You should never have the same 79 // BSTR owned by two different scoped_ptrs. 80 bool operator==(const ScopedBstr& bstr2) const; 81 bool operator!=(const ScopedBstr& bstr2) const; 82 DISALLOW_COPY_AND_ASSIGN(ScopedBstr); 83 }; 84 85 // Template class to generate a BSTR from a static wide string 86 // without touching the heap. Use this class via the StackBstrVar and 87 // StackBstr macros. 88 template <uint32 string_bytes> 89 class StackBstrT { 90 public: 91 // Try to stay as const as we can in an attempt to avoid someone 92 // using the class incorrectly (e.g. by supplying a variable instead 93 // of a verbatim string. We also have an assert in the constructor 94 // as an extra runtime check since the const-ness only catches one case. 95 explicit StackBstrT(const wchar_t* const str) { 96 // The BSTR API uses UINT, but we prefer uint32. 97 // Make sure we'll know about it if these types don't match. 98 COMPILE_ASSERT(sizeof(uint32) == sizeof(UINT), UintToUint32); 99 COMPILE_ASSERT(sizeof(wchar_t) == sizeof(OLECHAR), WcharToOlechar); 100 101 // You shouldn't pass string pointers to this constructor since 102 // there's no way for the compiler to calculate the length of the 103 // string (string_bytes will be equal to pointer size in those cases). 104 DCHECK(lstrlenW(str) == (string_bytes / sizeof(bstr_.str_[0])) - 1) << 105 "not expecting a string pointer"; 106 memcpy(bstr_.str_, str, string_bytes); 107 bstr_.len_ = string_bytes - sizeof(wchar_t); 108 } 109 110 operator BSTR() { 111 return bstr_.str_; 112 } 113 114 protected: 115 struct BstrInternal { 116 uint32 len_; 117 wchar_t str_[string_bytes / sizeof(wchar_t)]; 118 } bstr_; 119 }; 120 121 // Use this macro to generate an inline BSTR from a wide string. 122 // This is about 6 times faster than using the SysAllocXxx functions to 123 // allocate a BSTR and helps with keeping heap fragmentation down. 124 // Example: 125 // DoBstrStuff(StackBstr(L"This is my BSTR")); 126 // Where DoBstrStuff is: 127 // HRESULT DoBstrStuff(BSTR bstr) { ... } 128 #define StackBstr(str) \ 129 static_cast<BSTR>(StackBstrT<sizeof(str)>(str)) 130 131 // If you need a named BSTR variable that's based on a fixed string 132 // (e.g. if the BSTR is used inside a loop or more than one place), 133 // use StackBstrVar to declare a variable. 134 // Example: 135 // StackBstrVar(L"my_property", myprop); 136 // for (int i = 0; i < objects.length(); ++i) 137 // ProcessValue(objects[i].GetProp(myprop)); // GetProp accepts BSTR 138 #define StackBstrVar(str, var) \ 139 StackBstrT<sizeof(str)> var(str) 140 141 #endif // BASE_SCOPED_BSTR_WIN_H_ 142
