CComVariant class

This class wraps the VARIANT type, providing a member indicating the type of data stored.

Syntax

class CComVariant : public tagVARIANT

Members

Public constructors

Public methods

Public operators

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 is 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 is 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 is 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 is VT_R4.

dblSrc
[in] The double used to initialize the CComVariant object. The type of the CComVariant object is VT_R8.

cySrc
[in] The CY used to initialize the CComVariant object. The type of the CComVariant object is VT_CY.

pSrc
[in] The IDispatch or IUnknown pointer used to initialize the CComVariant object. AddRef is called on the interface pointer. The type of the CComVariant object is 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 is 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 is VT_I1.

bstrSrc
[in] The BSTR used to initialize the CComVariant object. The type of the CComVariant object is 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 is converted to the new type. The default value is NULL, meaning the CComVariant object is 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 is 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

The contents of the VARIANT referenced by pDest are automatically 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 value for 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 sizeof(CLSID) and sizeof(VARTYPE). If the interface pointer is NULL, GetSize returns sizeof(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 can't 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 is 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 is 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 is 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 is 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 is VT_R4.

dblSrc
[in] The double to be assigned to the CComVariant object. The type of the CComVariant object is VT_R8.

cySrc
[in] The CY to be assigned to the CComVariant object. The type of the CComVariant object is VT_CY.

pSrc
[in] The IDispatch or IUnknown pointer to be assigned to the CComVariant object. AddRef is called on the interface pointer. The type of the CComVariant object is 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 is 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 is 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 doesn't equal the specified VARIANT.

bool operator!=(const VARIANT& varSrc) const throw();

Remarks

Returns TRUE if either the value or type of varSrc isn't 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.

See also

Class overview