Share via

VariantClear

  • Article

This function clears a variant.

HRESULT VariantClear(
  VARIANTARG FAR* pvarg 
);

Parameters

  • pvarg
    [in, out] Pointer to the VARIANTARG to clear.

Return Values

The following table shows the HRESULT values that can be returned by this function.

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 invalid (and under some circumstances NULL) pointers to this function causes an 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.

Requirements

OS Versions: Windows CE 2.0 and later.
Header: Oleauto.h.
Link Library: Oleaut32.lib.

See Also

VARIANTARG

Last updated on Wednesday, April 13, 2005

© 2005 Microsoft Corporation. All rights reserved.