VariantClear

HRESULT VariantClear( 
  VARIANTARG FAR*  pvarg  
);
 

Clears a variant.

Parameter

pvarg
Pointer to the VARIANTARG to clear.

Return Value

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.

Comments

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.

Example

for(i = 0; i < celt; ++i)
    VariantClear(&rgvar[i]);

QuickInfo

  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.