Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function clears a variant.

Syntax 

HRESULT VariantClear(
  VARIANTARG FAR* 
pvarg 
);

Parameters

pvarg

[in, out] Pointer to the VARIANTARGto clear.

Return Value

Returns the HRESULT values shown in the following table.

Value Description

S_OK

Success.

DISP_E_ARRAYISLOCKED

The variant contains an array that is locked.

DISP_E_BADVARTYPE

The variant type pvargis not a valid type of variant.

E_INVALIDARG

An argument is invalid.

Remarks

Use this function to clear variables of type VARIANTARG(or VARIANT) before the memory that contains the VARIANTARGis freed (as when a local variable goes out of scope).

The function clears a VARIANTARGby setting the vtmember to VT_EMPTY and the wReservedmember to 0. The current contents of the VARIANTARGare released first.

If the vtmember is VT_BSTR, the string is freed.

If the vtmember is VT_DISPATCH, the object is released.

If the vtmember has the VT_ARRAY bit set, the array is freed.

In certain cases, it might be preferable to clear a variant in code without calling VariantClear. For example, you can change the type of a VT_I4 variant to another type without calling this function.

However, you must call VariantClearif a VT_* type is received but cannot be handled. Using VariantClearin these cases ensures that code will continue to work if Automation adds variant types in the future.

Passing invalid (and under some circumstances NULL) pointers to this function causes an unexpected termination of the application.

In this context, an invalid pointer is one that points to an invalid region in memory, is NULL, contains an unaligned pointer, points to memory block smaller than necessary, and so on.

Requirements

Header oleauto.h
Library oleaut32.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also