1 // Copyright 2011 The Chromium Authors 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_WIN_SCOPED_BSTR_H_ 6 #define BASE_WIN_SCOPED_BSTR_H_ 7 8 #include <windows.h> 9 10 #include <oleauto.h> 11 #include <stddef.h> 12 13 #include "base/base_export.h" 14 #include "base/check.h" 15 #include "base/strings/string_piece.h" 16 17 namespace base { 18 namespace win { 19 20 // Manages a BSTR string pointer. 21 // The class interface is based on unique_ptr. 22 class BASE_EXPORT ScopedBstr { 23 public: 24 ScopedBstr() = default; 25 26 // Constructor to create a new BSTR. 27 // 28 // NOTE: Do not pass a BSTR to this constructor expecting ownership to 29 // be transferred - even though it compiles! ;-) 30 explicit ScopedBstr(WStringPiece non_bstr); 31 32 ScopedBstr(const ScopedBstr&) = delete; 33 ScopedBstr& operator=(const ScopedBstr&) = delete; 34 35 ~ScopedBstr(); 36 Get()37 BSTR Get() const { return bstr_; } 38 39 // Give ScopedBstr ownership over an already allocated BSTR or null. 40 // If you need to allocate a new BSTR instance, use |allocate| instead. 41 void Reset(BSTR bstr = nullptr); 42 43 // Releases ownership of the BSTR to the caller. 44 BSTR Release(); 45 46 // Creates a new BSTR from a 16-bit C-style string. 47 // 48 // If you already have a BSTR and want to transfer ownership to the 49 // ScopedBstr instance, call |reset| instead. 50 // 51 // Returns a pointer to the new BSTR. 52 BSTR Allocate(WStringPiece str); 53 54 // Allocates a new BSTR with the specified number of bytes. 55 // Returns a pointer to the new BSTR. 56 BSTR AllocateBytes(size_t bytes); 57 58 // Sets the allocated length field of the already-allocated BSTR to be 59 // |bytes|. This is useful when the BSTR was preallocated with e.g. 60 // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and then 61 // not all the bytes are being used. 62 // 63 // Note that if you want to set the length to a specific number of 64 // characters, you need to multiply by sizeof(wchar_t). Oddly, there's no 65 // public API to set the length, so we do this ourselves by hand. 66 // 67 // NOTE: The actual allocated size of the BSTR MUST be >= bytes. That 68 // responsibility is with the caller. 69 void SetByteLen(size_t bytes); 70 71 // Swap values of two ScopedBstr's. 72 void Swap(ScopedBstr& bstr2); 73 74 // Retrieves the pointer address. 75 // Used to receive BSTRs as out arguments (and take ownership). 76 // The function DCHECKs on the current value being null. 77 // Usage: GetBstr(bstr.Receive()); 78 BSTR* Receive(); 79 80 // Returns number of chars in the BSTR. 81 size_t Length() const; 82 83 // Returns the number of bytes allocated for the BSTR. 84 size_t ByteLength() const; 85 86 // Forbid comparison of ScopedBstr types. You should never have the same 87 // BSTR owned by two different scoped_ptrs. 88 bool operator==(const ScopedBstr& bstr2) const = delete; 89 bool operator!=(const ScopedBstr& bstr2) const = delete; 90 91 protected: 92 BSTR bstr_ = nullptr; 93 }; 94 95 } // namespace win 96 } // namespace base 97 98 #endif // BASE_WIN_SCOPED_BSTR_H_ 99