This function clears a variant.
At a Glance
| Header file: | Oleauto.h |
| Windows CE versions: | 2.0 and later |
Syntax
HRESULT VariantClear(VARIANTARG FAR * pvarg);
Parameters
pvarg
Pointer to the VARIANTARG to clear.
Return Values
One of the values obtained from the returned HRESULT and described in the following table is returned.
| 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 | One of the arguments is invalid. |
Remarks
Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application.
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 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.
Example
for(i = 0; i < celt; ++i)
VariantClear(&rgvar[i]);