HRESULT VariantClear(
VARIANTARG FAR* pvarg
);
Clears a variant.
The return value obtained from the returned HRESULT is one of the following.
Return value | Meaning |
---|---|
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 | One of the arguments is invalid. |
Use this function to clear variables of type VARIANTARG (or VARIANT) before the memory containing the VARIANTARG is freed (as when a local variable goes out of scope).
The function clears a VARIANTARG by setting the vt field to VT_EMPTY and the wReserved field to 0. The current contents of the VARIANTARG are released first. If the vt field is VT_BSTR, the string is freed. If the vt field is VT_DISPATCH, the object is released. If the vt field has the VT_ARRAY bit set, the array is freed.
In certain cases, it may 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 new variant types in the future.
for(i = 0; i < celt; ++i)
VariantClear(&rgvar[i]);
Windows NT: Use version 3.1 and later.
Windows: Use Windows 95 and later.
Header: Declared in oleauto.h.
Import Library: Link with oleaut32.lib.