base/win/scoped_bstr.h

   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:
  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
  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_WIN_SCOPED_BSTR_H_