scoped_bstr.h revision 868fa2fe829687343ffae624259930155e16dbd8
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2011 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef BASE_WIN_SCOPED_BSTR_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define BASE_WIN_SCOPED_BSTR_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <windows.h> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <oleauto.h> 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/base_export.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/logging.h" 13868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles)#include "base/strings/string16.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base { 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace win { 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Manages a BSTR string pointer. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The class interface is based on scoped_ptr. 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BASE_EXPORT ScopedBstr { 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ScopedBstr() : bstr_(NULL) { 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Constructor to create a new BSTR. 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NOTE: Do not pass a BSTR to this constructor expecting ownership to 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be transferred - even though it compiles! ;-) 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit ScopedBstr(const char16* non_bstr); 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ~ScopedBstr(); 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Give ScopedBstr ownership over an already allocated BSTR or NULL. 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If you need to allocate a new BSTR instance, use |allocate| instead. 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Reset(BSTR bstr = NULL); 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Releases ownership of the BSTR to the caller. 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) BSTR Release(); 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Creates a new BSTR from a 16-bit C-style string. 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If you already have a BSTR and want to transfer ownership to the 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // ScopedBstr instance, call |reset| instead. 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns a pointer to the new BSTR, or NULL if allocation failed. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) BSTR Allocate(const char16* str); 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Allocates a new BSTR with the specified number of bytes. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns a pointer to the new BSTR, or NULL if allocation failed. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) BSTR AllocateBytes(size_t bytes); 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Sets the allocated length field of the already-allocated BSTR to be 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |bytes|. This is useful when the BSTR was preallocated with e.g. 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and then 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not all the bytes are being used. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Note that if you want to set the length to a specific number of 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // characters, you need to multiply by sizeof(wchar_t). Oddly, there's no 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // public API to set the length, so we do this ourselves by hand. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NOTE: The actual allocated size of the BSTR MUST be >= bytes. That 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // responsibility is with the caller. 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void SetByteLen(size_t bytes); 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Swap values of two ScopedBstr's. 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Swap(ScopedBstr& bstr2); 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Retrieves the pointer address. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Used to receive BSTRs as out arguments (and take ownership). 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The function DCHECKs on the current value being NULL. 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Usage: GetBstr(bstr.Receive()); 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) BSTR* Receive(); 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns number of chars in the BSTR. 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) size_t Length() const; 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the number of bytes allocated for the BSTR. 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) size_t ByteLength() const; 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) operator BSTR() const { 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return bstr_; 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected: 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) BSTR bstr_; 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Forbid comparison of ScopedBstr types. You should never have the same 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // BSTR owned by two different scoped_ptrs. 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool operator==(const ScopedBstr& bstr2) const; 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool operator!=(const ScopedBstr& bstr2) const; 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(ScopedBstr); 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace win 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace base 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // BASE_SCOPED_BSTR_H_ 98