scoped_bstr.h 3.0 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798
  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. #ifndef BASE_WIN_SCOPED_BSTR_H_
  5. #define BASE_WIN_SCOPED_BSTR_H_
  6. #include <windows.h>
  7. #include <oleauto.h>
  8. #include <stddef.h>
  9. #include "base/base_export.h"
  10. #include "base/check.h"
  11. #include "base/strings/string_piece.h"
  12. namespace base {
  13. namespace win {
  14. // Manages a BSTR string pointer.
  15. // The class interface is based on unique_ptr.
  16. class BASE_EXPORT ScopedBstr {
  17. public:
  18. ScopedBstr() = default;
  19. // Constructor to create a new BSTR.
  20. //
  21. // NOTE: Do not pass a BSTR to this constructor expecting ownership to
  22. // be transferred - even though it compiles! ;-)
  23. explicit ScopedBstr(WStringPiece non_bstr);
  24. ScopedBstr(const ScopedBstr&) = delete;
  25. ScopedBstr& operator=(const ScopedBstr&) = delete;
  26. ~ScopedBstr();
  27. BSTR Get() const { return bstr_; }
  28. // Give ScopedBstr ownership over an already allocated BSTR or null.
  29. // If you need to allocate a new BSTR instance, use |allocate| instead.
  30. void Reset(BSTR bstr = nullptr);
  31. // Releases ownership of the BSTR to the caller.
  32. BSTR Release();
  33. // Creates a new BSTR from a 16-bit C-style string.
  34. //
  35. // If you already have a BSTR and want to transfer ownership to the
  36. // ScopedBstr instance, call |reset| instead.
  37. //
  38. // Returns a pointer to the new BSTR.
  39. BSTR Allocate(WStringPiece str);
  40. // Allocates a new BSTR with the specified number of bytes.
  41. // Returns a pointer to the new BSTR.
  42. BSTR AllocateBytes(size_t bytes);
  43. // Sets the allocated length field of the already-allocated BSTR to be
  44. // |bytes|. This is useful when the BSTR was preallocated with e.g.
  45. // SysAllocStringLen or SysAllocStringByteLen (call |AllocateBytes|) and then
  46. // not all the bytes are being used.
  47. //
  48. // Note that if you want to set the length to a specific number of
  49. // characters, you need to multiply by sizeof(wchar_t). Oddly, there's no
  50. // public API to set the length, so we do this ourselves by hand.
  51. //
  52. // NOTE: The actual allocated size of the BSTR MUST be >= bytes. That
  53. // responsibility is with the caller.
  54. void SetByteLen(size_t bytes);
  55. // Swap values of two ScopedBstr's.
  56. void Swap(ScopedBstr& bstr2);
  57. // Retrieves the pointer address.
  58. // Used to receive BSTRs as out arguments (and take ownership).
  59. // The function DCHECKs on the current value being null.
  60. // Usage: GetBstr(bstr.Receive());
  61. BSTR* Receive();
  62. // Returns number of chars in the BSTR.
  63. size_t Length() const;
  64. // Returns the number of bytes allocated for the BSTR.
  65. size_t ByteLength() const;
  66. // Forbid comparison of ScopedBstr types. You should never have the same
  67. // BSTR owned by two different scoped_ptrs.
  68. bool operator==(const ScopedBstr& bstr2) const = delete;
  69. bool operator!=(const ScopedBstr& bstr2) const = delete;
  70. protected:
  71. BSTR bstr_ = nullptr;
  72. };
  73. } // namespace win
  74. } // namespace base
  75. #endif // BASE_WIN_SCOPED_BSTR_H_