Home | History | Annotate | Download | only in win 
      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:
     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 
     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