Función VariantClear (oleauto.h)

Borra una variante.

Sintaxis

HRESULT VariantClear(
  [in, out] VARIANTARG *pvarg
);

Parámetros

[in, out] pvarg

Variante que se va a borrar.

Valor devuelto

Esta función puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	Correcto.
DISP_E_ARRAYISLOCKED	La variante contiene una matriz bloqueada.
DISP_E_BADVARTYPE	El tipo de variante no es un tipo válido de variante.
E_INVALIDARG	Uno de los argumentos no es válido.

Comentarios

Use esta función para borrar variables de tipo VARIANTARG (o VARIANT) antes de liberar la memoria que contiene VARIANTARG (como cuando una variable local sale del ámbito).

La función borra un VARIANTARG estableciendo el campo vt en VT_EMPTY. El contenido actual de VARIANTARG se publica primero. Si vtfield es VT_BSTR, se libera la cadena. Si el campo virtual está VT_DISPATCH, se libera el objeto . Si el campo vt tiene el VT_ARRAY bit establecido, se libera la matriz.

Si la variante que se va a borrar es un objeto COM que se pasa por referencia, el campo vtfield del pvargparameter se VT_DISPATCH | VT_BYREF o VT_UNKNOWN | VT_BYREF. En este caso, VariantClear no libera el objeto . Dado que la variante que se borra es un puntero a una referencia a un objeto, VariantClear no tiene forma de determinar si es necesario liberar el objeto. Por lo tanto, es responsabilidad del autor de la llamada liberar el objeto o no, según corresponda.

En ciertos casos, puede ser preferible borrar una variante en el código sin llamar a VariantClear. Por ejemplo, puede cambiar el tipo de una variante de VT_I4 a otro tipo sin llamar a esta función. Safearrays de BSTR tendrá SysFreeString llamado en cada elemento que no sea VariantClear. Sin embargo, debe llamar a VariantClear si se recibe un VT_type pero no se puede controlar. Safearrays de variante también tendrá VariantClear llamado en cada miembro. El uso de VariantClear en estos casos garantiza que el código seguirá funcionando si Automation agrega nuevos tipos de variantes en el futuro.

No utilice VariantClear en variantes sin inicializar; use VariantInit para inicializar un nuevo VARIANTARG o VARIANT.

No se pueden borrar las variantes que contienen matrices con referencias pendientes. Los intentos de hacerlo devolverán un HRESULT que contenga DISP_E_ARRAYISLOCKED.

Ejemplos

En el ejemplo siguiente se muestra cómo borrar una matriz de variantes, donde celt es el número de elementos de la matriz.

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

Requisitos

Requisito	Value
Plataforma de destino	Windows
Encabezado	oleauto.h
Library	OleAut32.lib
Archivo DLL	OleAut32.dll

Consulte también

Funciones de manipulación de variantes