CComVariant Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CComVariant Class.
This class wraps the VARIANT type, providing a member indicating the type of data stored.
Syntax
cpp
class CComVariant : public tagVARIANT
Members
Public Constructors
| Name | Description |
|---|---|
| CComVariant::CComVariant | The constructor. |
| CComVariant::~CComVariant | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CComVariant::Attach | Attaches a VARIANT to the CComVariant object. |
| CComVariant::ChangeType | Converts the CComVariant object to a new type. |
| CComVariant::Clear | Clears the CComVariant object. |
| CComVariant::Copy | Copies a VARIANT to the CComVariant object. |
| CComVariant::CopyTo | Copies the contents of the CComVariant object. |
| CComVariant::Detach | Detaches the underlying VARIANT from the CComVariant object. |
| CComVariant::GetSize | Returns the size in number of bytes of the contents of the CComVariant object. |
| CComVariant::ReadFromStream | Loads a VARIANT from a stream. |
| CComVariant::SetByRef | Initializes the CComVariant object and sets the vt member to VT_BYREF. |
| CComVariant::WriteToStream | Saves the underlying VARIANT to a stream. |
Public Operators
| CComVariant::operator < | Indicates whether the CComVariant object is less than the specified VARIANT. |
| CComVariant::operator > | Indicates whether the CComVariant object is greater than the specified VARIANT. |
| operator != | Indicates whether the CComVariant object does not equal the specified VARIANT. |
| operator = | Assigns a value to the CComVariant object. |
| operator == | Indicates whether the CComVariant object equals the specified VARIANT. |
Remarks
CComVariant wraps the VARIANT and VARIANTARG type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation.
CComVariant derives from the VARIANT type so it can be used wherever a VARIANT can be used. You can, for example, use the V_VT macro to extract the type of a CComVariant or you can access the vt member directly just as you can with a VARIANT.
Inheritance Hierarchy
tagVARIANT
CComVariant
Requirements
Header: atlcomcli.h
CComVariant::Attach
Safely clears the current contents of the CComVariant object, copies the contents of pSrc into this object, then sets the variant type of pSrc to VT_EMPTY.
HRESULT Attach(VARIANT* pSrc);
Parameters
pSrc
[in] Points to the VARIANT to be attached to the object.
Return Value
A standard HRESULT value.
Remarks
Ownership of the data held by pSrc is transferred to the CComVariant object.
CComVariant::CComVariant
Each constructor handles the safe initialization of the CComVariant object by calling the VariantInit Win32 function or by setting the object's value and type according to the parameters passed.
CComVariant() throw();
CComVariant(const CComVariant& varSrc);
CComVariant(const VARIANT& varSrc);
CComVariant(LPCOLESTR lpszSrc);
CComVariant(LPCSTR lpszSrc);
CComVariant(bool bSrc);
CComVariant(BYTE nSrc) throw();
CComVariant(int nSrc, VARTYPE vtSrc = VT_I4) throw();
CComVariant(unsigned int nSrc, VARTYPE vtSrc = VT_UI4) throw();
CComVariant(shor nSrc) throw();
CComVariant(unsigned short nSrc) throw();
CComVariant(long nSrc, VARTYPE vtSrc = VT_I4) throw();
CComVariant(unsigned long nSrc) throw();
CComVariant(LONGLONG nSrc) throw();
CComVariant(ULONGLONG nSrc) throw();
CComVariant(float fltSrc) throw();
CComVariant(double dblSrc, VARTYPE vtSrc = VT_R8) throw();
CComVariant(CY cySrc) throw();
CComVariant(IDispatch* pSrc) throw();
CComVariant(IUnknown* pSrc) throw();
CComVariant(const SAFEARRAY* pSrc);
CComVariant(char cSrc) throw();
CComVariant(const CComBSTR& bstrSrc);
Parameters
varSrc
[in] The CComVariant or VARIANT used to initialize the CComVariant object. The contents of the source variant are copied to the destination without conversion.
lpszSrc
[in] The character string used to initialize the CComVariant object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the constructor or an ANSI string to the LPCSTR version. In either case the string is converted to a Unicode BSTR allocated using SysAllocString. The type of the CComVariant object will be VT_BSTR.
bSrc
[in] The bool used to initialize the CComVariant object. The bool argument is converted to a VARIANT_BOOL before being stored. The type of the CComVariant object will be VT_BOOL.
nSrc
[in] The int, BYTE, short, long, LONGLONG, ULONGLONG, unsigned short, unsigned long, or unsigned int used to initialize the CComVariant object. The type of the CComVariant object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively.
vtSrc
[in] The type of the variant. When the first parameter is int, valid types are VT_I4 and VT_INT. When the first parameter is long, valid types are VT_I4 and VT_ERROR. When the first parameter is double, valid types are VT_R8 and VT_DATE. When the first parameter is unsigned int, valid types are VT_UI4 and VT_UINT.
fltSrc
[in] The float used to initialize the CComVariant object. The type of the CComVariant object will be VT_R4.
dblSrc
[in] The double used to initialize the CComVariant object. The type of the CComVariant object will be VT_R8.
cySrc
[in] The CY used to initialize the CComVariant object. The type of the CComVariant object will be VT_CY.
pSrc
[in] The IDispatch or IUnknown pointer used to initialize the CComVariant object. AddRef will be called on the interface pointer. The type of the CComVariant object will be VT_DISPATCH or VT_UNKNOWN, respectively.
Or, the SAFERRAY pointer used to initialize the CComVariant object. A copy of the SAFEARRAY is stored in the CComVariant object. The type of the CComVariant object will be a combination of the original type of the SAFEARRAY and VT_ARRAY.
cSrc
[in] The char used to initialize the CComVariant object. The type of the CComVariant object will be VT_I1.
bstrSrc
[in] The BSTR used to initialize the CComVariant object. The type of the CComVariant object will be VT_BSTR.
Remarks
The destructor manages cleanup by calling CComVariant::Clear.
CComVariant::~CComVariant
The destructor.
~CComVariant() throw();
Remarks
This method manages cleanup by calling CComVariant::Clear.
CComVariant::ChangeType
Converts the CComVariant object to a new type.
HRESULT ChangeType(VARTYPE vtNew, const VARIANT* pSrc = NULL);
Parameters
vtNew
[in] The new type for the CComVariant object.
pSrc
[in] A pointer to the VARIANT whose value will be converted to the new type. The default value is NULL, meaning the CComVariant object will be converted in place.
Return Value
A standard HRESULT value.
Remarks
If you pass a value for pSrc, ChangeType will use this VARIANT as the source for the conversion. Otherwise, the CComVariant object will be the source.
CComVariant::Clear
Clears the CComVariant object by calling the VariantClear Win32 function.
HRESULT Clear();
Return Value
A standard HRESULT value.
Remarks
The destructor automatically calls Clear.
CComVariant::Copy
Frees the CComVariant object and then assigns it a copy of the specified VARIANT.
HRESULT Copy(const VARIANT* pSrc);
Parameters
pSrc
[in] A pointer to the VARIANT to be copied.
Return Value
A standard HRESULT value.
CComVariant::CopyTo
Copies the contents of the CComVariant object.
HRESULT CopyTo(BSTR* pstrDest);
Parameters
pstrDest
Points to a BSTR that will receive a copy of the contents of the CComVariant object.
Return Value
A standard HRESULT value.
Remarks
The CComVariant object must be of type VT_BSTR.
CComVariant::Detach
Detaches the underlying VARIANT from the CComVariant object and sets the object's type to VT_EMPTY.
HRESULT Detach(VARIANT* pDest);
Parameters
pDest
[out] Returns the underlying VARIANT value of the object.
Return Value
A standard HRESULT value.
Remarks
Note that the contents of the VARIANT referenced by pDest will automatically be cleared before being assigned the value and type of the calling CComVariant object.
CComVariant::GetSize
For simple-fixed size VARIANTs, this method returns the sizeof the underlying data type plus sizeof(VARTYPE).
ULONG GetSize() const;
Return Value
The size in bytes of the current contents of the CComVariant object.
Remarks
If the VARIANT contains an interface pointer, GetSize queries for IPersistStream or IPersistStreamInit. If successful, the return value is the low-order 32 bits of the value returned by GetSizeMax plus the sizeof a CLSID and sizeof(VARTYPE). If the interface pointer is NULL, GetSize returns the sizeof a CLSID plus sizeof(VARTYPE). If the total size is larger than ULONG_MAX, GetSize returns sizeof(VARTYPE) which indicates an error.
In all other cases, a temporary VARIANT of type VT_BSTR is coerced from the current VARIANT. The length of this BSTR is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus sizeof(VARTYPE). If the VARIANT cannot be coerced to a VARIANT of type VT_BSTR, GetSize returns sizeof(VARTYPE).
The size returned by this method matches the number of bytes used by CComVariant::WriteToStream under successful conditions.
CComVariant::operator =
Assigns a value and corresponding type to the CComVariant object.
CComVariant& operator=(const CComVariant& varSrc);
CComVariant& operator=(const VARIANT& varSrc);
CComVariant& operator=(const CComBSTR& bstrSrc);
CComVariant& operator=(LPCOLESTR lpszSrc);
CComVariant& operator=(LPCSTR lpszSrc);
CComVariant& operator=(bool bSrc);
CComVariant& operator=(BYTE nSrc) throw();
CComVariant& operator=(int nSrc) throw();
CComVariant& operator=(unsigned int nSrc) throw();
CComVariant& operator=(short nSrc) throw();
CComVariant& operator=(unsigned short nSrc) throw();
CComVariant& operator=(long nSrc) throw();
CComVariant& operator=(unsigned long nSrc) throw();
CComVariant& operator=(LONGLONG nSrc) throw();
CComVariant& operator=(ULONGLONG nSrc) throw();
CComVariant& operator=(float fltSrc) throw();
CComVariant& operator=(double dblSrc) throw();
CComVariant& operator=(CY cySrc) throw();
CComVariant& operator=(IDispatch* pSrc) throw();
CComVariant& operator=(IUnknown* pSrc) throw();
CComVariant& operator=(const SAFEARRAY* pSrc);
CComVariant& operator=(char cSrc) throw();
Parameters
varSrc
[in] The CComVariant or VARIANT to be assigned to the CComVariant object. The contents of the source variant are copied to the destination without conversion.
bstrSrc
[in] The BSTR to be assigned to the CComVariant object. The type of the CComVariant object will be VT_BSTR.
lpszSrc
[in] The character string to be assigned to the CComVariant object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the operator or an ANSI string to the LPCSTR version. In either case, the string is converted to a Unicode BSTR allocated using SysAllocString. The type of the CComVariant object will be VT_BSTR.
bSrc
[in] The bool to be assigned to the CComVariant object. The bool argument is converted to a VARIANT_BOOL before being stored. The type of the CComVariant object will be VT_BOOL.
nSrc
[in] The int, BYTE, short, long, LONGLONG, ULONGLONG, unsigned short, unsigned long, or unsigned int to be assigned to the CComVariant object. The type of the CComVariant object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively.
fltSrc
[in] The float to be assigned to the CComVariant object. The type of the CComVariant object will be VT_R4.
dblSrc
[in] The double to be assigned to the CComVariant object. The type of the CComVariant object will be VT_R8.
cySrc
[in] The CY to be assigned to the CComVariant object. The type of the CComVariant object will be VT_CY.
pSrc
[in] The IDispatch or IUnknown pointer to be assigned to the CComVariant object. AddRef will be called on the interface pointer. The type of the CComVariant object will be VT_DISPATCH or VT_UNKNOWN, respectively.
Or, a SAFEARRAY pointer to be assigned to the CComVariant object. A copy of the SAFEARRAY is stored in the CComVariant object. The type of the CComVariant object will be a combination of the original type of the SAFEARRAY and VT_ARRAY.
cSrc
[in] The char to be assigned to the CComVariant object. The type of the CComVariant object will be VT_I1.
CComVariant::operator ==
Indicates whether the CComVariant object equals the specified VARIANT.
bool operator==(const VARIANT& varSrc) const throw();
Remarks
Returns true if the value and type of varSrc are equal to the value and type, respectively, of the CComVariant object. Otherwise, false. The operator uses the user's default locale to perform the comparison.
The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records.
CComVariant::operator !=
Indicates whether the CComVariant object does not equal the specified VARIANT.
bool operator!=(const VARIANT& varSrc) const throw();
Remarks
Returns true if either the value or type of varSrc is not equal to the value or type, respectively, of the CComVariant object. Otherwise, false. The operator uses the user's default locale to perform the comparison.
The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records.
CComVariant::operator <
Indicates whether the CComVariant object is less than the specified VARIANT.
bool operator<(const VARIANT& varSrc) const throw();
Remarks
Returns true if the value of the CComVariant object is less than the value of varSrc. Otherwise, false. The operator uses the user's default locale to perform the comparison.
CComVariant::operator >
Indicates whether the CComVariant object is greater than the specified VARIANT.
bool operator>(const VARIANT& varSrc) const throw();
Remarks
Returns true if the value of the CComVariant object is greater than the value of varSrc. Otherwise, false. The operator uses the user's default locale to perform the comparison.
CComVariant::ReadFromStream
Sets the underlying VARIANT to the VARIANT contained in the specified stream.
HRESULT ReadFromStream(IStream* pStream);
Parameters
pStream
[in] A pointer to the IStream interface on the stream containing the data.
Return Value
A standard HRESULT value.
Remarks
ReadToStream requires a previous call to WriteToStream.
CComVariant::SetByRef
Initializes the CComVariant object and sets the vt member to VT_BYREF.
template < typename T >
void SetByRef(T* pT) throw();
Parameters
T
The type of VARIANT, for example, BSTR, int, or char.
pT
The pointer used to initialize the CComVariant object.
Remarks
SetByRef is a function template that initializes the CComVariant object to the pointer pT and sets the vt member to VT_BYREF. For example:
CComVariant var;
int nData = 10;
var.SetByRef(&nData);
CComVariant::WriteToStream
Saves the underlying VARIANT to a stream.
HRESULT WriteToStream(IStream* pStream);
Parameters
pStream
[in] A pointer to the IStream interface on a stream.
Return Value
A standard HRESULT value.