Fonction VariantClear (oleauto.h)

Efface une variante.

Syntaxe

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

Paramètres

[in, out] pvarg

Variante à effacer.

Valeur retournée

Cette fonction peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Réussite.
DISP_E_ARRAYISLOCKED	La variante contient un tableau verrouillé.
DISP_E_BADVARTYPE	Le type variant n’est pas un type de variant valide.
E_INVALIDARG	L’un des arguments n’est pas valide.

Remarques

Utilisez cette fonction pour effacer les variables de type VARIANTARG (ou VARIANT) avant que la mémoire contenant le VARIANTARG soit libérée (comme lorsqu’une variable locale sort de l’étendue).

La fonction efface un VARIANTARG en définissant le champ vt sur VT_EMPTY. Le contenu actuel de VARIANTARG est publié en premier. Si le champ vtfield est VT_BSTR, la chaîne est libérée. Si le champ vtfield est VT_DISPATCH, l’objet est libéré. Si le champ vt a le VT_ARRAY bit défini, le tableau est libéré.

Si la variante à effacer est un objet COM transmis par référence, le champ vtfield du pvargparameter est VT_DISPATCH | VT_BYREF ou VT_UNKNOWN | VT_BYREF. Dans ce cas, VariantClear ne libère pas l’objet. Étant donné que la variante effacée est un pointeur vers une référence à un objet, VariantClear n’a aucun moyen de déterminer s’il est nécessaire de libérer l’objet. Il incombe donc à l’appelant de libérer ou non l’objet, le cas échéant.

Dans certains cas, il peut être préférable d’effacer une variante dans le code sans appeler VariantClear. Par exemple, vous pouvez changer le type d’un VT_I4 variante par un autre type sans appeler cette fonction. SysFreeString sera appelé sur chaque élément non VariantClear dans les safearrays de BSTR. Toutefois, vous devez appeler VariantClear si une VT_type est reçue mais ne peut pas être gérée. Les safearrays de variant auront également VariantClear appelé sur chaque membre. L’utilisation de VariantClear dans ces cas garantit que le code continuera de fonctionner si Automation ajoute de nouveaux types de variantes à l’avenir.

N’utilisez pas VariantClear sur les variantes non initialisées ; utilisez VariantInit pour initialiser un nouveau VARIANTARG ou VARIANT.

Les variantes contenant des tableaux avec des références en suspens ne peuvent pas être effacées. Les tentatives de ce type retournent un HRESULT contenant DISP_E_ARRAYISLOCKED.

Exemples

L’exemple suivant montre comment effacer un tableau de variantes, où celt est le nombre d’éléments dans le tableau.

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

Configuration requise

Condition requise	Valeur
Plateforme cible	Windows
En-tête	oleauto.h
Bibliothèque	OleAut32.lib
DLL	OleAut32.dll

Voir aussi

Fonctions de manipulation des variantes