VariantClear (Compact 2013)

3/26/2014

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.

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.

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

See Also

Reference

Automation Functions
VARIANT and VARIANTARG