scoped_variant.h 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190
  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_VARIANT_H_
  5. #define BASE_WIN_SCOPED_VARIANT_H_
  6. #include <windows.h>
  7. #include <oleauto.h>
  8. #include <stdint.h>
  9. #include "base/base_export.h"
  10. namespace base {
  11. namespace win {
  12. // Scoped VARIANT class for automatically freeing a COM VARIANT at the
  13. // end of a scope. Additionally provides a few functions to make the
  14. // encapsulated VARIANT easier to use.
  15. // Instead of inheriting from VARIANT, we take the containment approach
  16. // in order to have more control over the usage of the variant and guard
  17. // against memory leaks.
  18. class BASE_EXPORT ScopedVariant {
  19. public:
  20. // Declaration of a global variant variable that's always VT_EMPTY
  21. static const VARIANT kEmptyVariant;
  22. // Default constructor.
  23. ScopedVariant() {
  24. // This is equivalent to what VariantInit does, but less code.
  25. var_.vt = VT_EMPTY;
  26. }
  27. // Constructor to create a new VT_BSTR VARIANT.
  28. // NOTE: Do not pass a BSTR to this constructor expecting ownership to
  29. // be transferred
  30. explicit ScopedVariant(const wchar_t* str);
  31. // Creates a new VT_BSTR variant of a specified length.
  32. ScopedVariant(const wchar_t* str, UINT length);
  33. // Creates a new integral type variant and assigns the value to
  34. // VARIANT.lVal (32 bit sized field).
  35. explicit ScopedVariant(long value, // NOLINT(runtime/int)
  36. VARTYPE vt = VT_I4);
  37. // Creates a new integral type variant for the int type and assigns the value
  38. // to VARIANT.lVal (32 bit sized field).
  39. explicit ScopedVariant(int value);
  40. // Creates a new boolean (VT_BOOL) variant and assigns the value to
  41. // VARIANT.boolVal.
  42. explicit ScopedVariant(bool value);
  43. // Creates a new double-precision type variant. |vt| must be either VT_R8
  44. // or VT_DATE.
  45. explicit ScopedVariant(double value, VARTYPE vt = VT_R8);
  46. // VT_DISPATCH
  47. explicit ScopedVariant(IDispatch* dispatch);
  48. // VT_UNKNOWN
  49. explicit ScopedVariant(IUnknown* unknown);
  50. // SAFEARRAY
  51. explicit ScopedVariant(SAFEARRAY* safearray);
  52. // Copies the variant.
  53. explicit ScopedVariant(const VARIANT& var);
  54. // Moves the wrapped variant into another ScopedVariant.
  55. ScopedVariant(ScopedVariant&& var);
  56. ScopedVariant(const ScopedVariant&) = delete;
  57. ScopedVariant& operator=(const ScopedVariant&) = delete;
  58. ~ScopedVariant();
  59. inline VARTYPE type() const { return var_.vt; }
  60. // Give ScopedVariant ownership over an already allocated VARIANT.
  61. void Reset(const VARIANT& var = kEmptyVariant);
  62. // Releases ownership of the VARIANT to the caller.
  63. VARIANT Release();
  64. // Swap two ScopedVariant's.
  65. void Swap(ScopedVariant& var);
  66. // Returns a copy of the variant.
  67. VARIANT Copy() const;
  68. // The return value is 0 if the variants are equal, 1 if this object is
  69. // greater than |other|, -1 if it is smaller.
  70. // Comparison with an array VARIANT is not supported.
  71. // 1. VT_NULL and VT_EMPTY is always considered less-than any other VARTYPE.
  72. // 2. If both VARIANTS have either VT_UNKNOWN or VT_DISPATCH even if the
  73. // VARTYPEs do not match, the address of its IID_IUnknown is compared to
  74. // guarantee a logical ordering even though it is not a meaningful order.
  75. // e.g. (a.Compare(b) != b.Compare(a)) unless (a == b).
  76. // 3. If the VARTYPEs do not match, then the value of the VARTYPE is compared.
  77. // 4. Comparing VT_BSTR values is a lexicographical comparison of the contents
  78. // of the BSTR, taking into account |ignore_case|.
  79. // 5. Otherwise returns the lexicographical comparison of the values held by
  80. // the two VARIANTS that share the same VARTYPE.
  81. int Compare(const VARIANT& other, bool ignore_case = false) const;
  82. // Retrieves the pointer address.
  83. // Used to receive a VARIANT as an out argument (and take ownership).
  84. // The function DCHECKs on the current value being empty/null.
  85. // Usage: GetVariant(var.receive());
  86. VARIANT* Receive();
  87. void Set(const wchar_t* str);
  88. // Setters for simple types.
  89. void Set(int8_t i8);
  90. void Set(uint8_t ui8);
  91. void Set(int16_t i16);
  92. void Set(uint16_t ui16);
  93. void Set(int32_t i32);
  94. void Set(uint32_t ui32);
  95. void Set(int64_t i64);
  96. void Set(uint64_t ui64);
  97. void Set(float r32);
  98. void Set(double r64);
  99. void Set(bool b);
  100. // Creates a copy of |var| and assigns as this instance's value.
  101. // Note that this is different from the Reset() method that's used to
  102. // free the current value and assume ownership.
  103. void Set(const VARIANT& var);
  104. // COM object setters
  105. void Set(IDispatch* disp);
  106. void Set(IUnknown* unk);
  107. // SAFEARRAY support
  108. void Set(SAFEARRAY* array);
  109. // Special setter for DATE since DATE is a double and we already have
  110. // a setter for double.
  111. void SetDate(DATE date);
  112. // Allows const access to the contained variant without DCHECKs etc.
  113. // This support is necessary for the V_XYZ (e.g. V_BSTR) set of macros to
  114. // work properly but still doesn't allow modifications since we want control
  115. // over that.
  116. const VARIANT* ptr() const { return &var_; }
  117. // Moves the ScopedVariant to another instance.
  118. ScopedVariant& operator=(ScopedVariant&& var);
  119. // Like other scoped classes (e.g. scoped_refptr, ScopedBstr,
  120. // Microsoft::WRL::ComPtr) we support the assignment operator for the type we
  121. // wrap.
  122. ScopedVariant& operator=(const VARIANT& var);
  123. // A hack to pass a pointer to the variant where the accepting
  124. // function treats the variant as an input-only, read-only value
  125. // but the function prototype requires a non const variant pointer.
  126. // There's no DCHECK or anything here. Callers must know what they're doing.
  127. VARIANT* AsInput() const {
  128. // The nature of this function is const, so we declare
  129. // it as such and cast away the constness here.
  130. return const_cast<VARIANT*>(&var_);
  131. }
  132. // Allows the ScopedVariant instance to be passed to functions either by value
  133. // or by const reference.
  134. operator const VARIANT&() const { return var_; }
  135. // Used as a debug check to see if we're leaking anything.
  136. static bool IsLeakableVarType(VARTYPE vt);
  137. protected:
  138. VARIANT var_;
  139. private:
  140. // Comparison operators for ScopedVariant are not supported at this point.
  141. // Use the Compare method instead.
  142. bool operator==(const ScopedVariant& var) const;
  143. bool operator!=(const ScopedVariant& var) const;
  144. };
  145. } // namespace win
  146. } // namespace base
  147. #endif // BASE_WIN_SCOPED_VARIANT_H_