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