1
    2
    3
    4
    5
    6
    7
    8
    9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99


base / win / scoped_bstr.h [blame]

// Copyright 2011 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_WIN_SCOPED_BSTR_H_
#define BASE_WIN_SCOPED_BSTR_H_

#include <windows.h>

#include <oleauto.h>
#include <stddef.h>

#include <string_view>

#include "base/base_export.h"
#include "base/check.h"

namespace base {
namespace win {

// Manages a BSTR string pointer.
// The class interface is based on unique_ptr.
class BASE_EXPORT ScopedBstr {
 public:
  ScopedBstr() = default;

  // Constructor to create a new BSTR.
  //
  // NOTE: Do not pass a BSTR to this constructor expecting ownership to
  // be transferred - even though it compiles! ;-)
  explicit ScopedBstr(std::wstring_view non_bstr);

  ScopedBstr(const ScopedBstr&) = delete;
  ScopedBstr& operator=(const ScopedBstr&) = delete;

  ~ScopedBstr();

  BSTR Get() const { return bstr_; }

  // Give ScopedBstr ownership over an already allocated BSTR or null.
  // If you need to allocate a new BSTR instance, use |allocate| instead.
  void Reset(BSTR bstr = nullptr);

  // Releases ownership of the BSTR to the caller.
  BSTR Release();

  // Creates a new BSTR from a 16-bit C-style string.
  //
  // If you already have a BSTR and want to transfer ownership to the
  // ScopedBstr instance, call |reset| instead.
  //
  // Returns a pointer to the new BSTR.
  BSTR Allocate(std::wstring_view str);

  // Allocates a new BSTR with the specified number of bytes.
  // Returns a pointer to the new BSTR.
  BSTR AllocateBytes(size_t bytes);

  // Sets the allocated length field of the already-allocated BSTR to be
  // |bytes|.  This is useful when the BSTR was preallocated with e.g.
  // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and then
  // not all the bytes are being used.
  //
  // Note that if you want to set the length to a specific number of
  // characters, you need to multiply by sizeof(wchar_t).  Oddly, there's no
  // public API to set the length, so we do this ourselves by hand.
  //
  // NOTE: The actual allocated size of the BSTR MUST be >= bytes.  That
  // responsibility is with the caller.
  void SetByteLen(size_t bytes);

  // Swap values of two ScopedBstr's.
  void Swap(ScopedBstr& bstr2);

  // Retrieves the pointer address.
  // Used to receive BSTRs as out arguments (and take ownership).
  // The function DCHECKs on the current value being null.
  // Usage: GetBstr(bstr.Receive());
  BSTR* Receive();

  // Returns number of chars in the BSTR.
  size_t Length() const;

  // Returns the number of bytes allocated for the BSTR.
  size_t ByteLength() const;

  // Forbid comparison of ScopedBstr types.  You should never have the same
  // BSTR owned by two different scoped_ptrs.
  bool operator==(const ScopedBstr& bstr2) const = delete;
  bool operator!=(const ScopedBstr& bstr2) const = delete;

 protected:
  BSTR bstr_ = nullptr;
};

}  // namespace win
}  // namespace base

#endif  // BASE_WIN_SCOPED_BSTR_H_