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