VariantClear
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 VARIANTARG to 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 pvarg is 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 VARIANTARG is freed (as when a local variable goes out of scope).
The function clears a VARIANTARG by setting the vt member to VT_EMPTY and the wReserved member to 0. The current contents of the VARIANTARG are released first.
If the vt member is VT_BSTR, the string is freed.
If the vt member is VT_DISPATCH, the object is released.
If the vt member 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 VariantClear if a VT_* type is received but cannot be handled. Using VariantClear in 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 |