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