VariantClear-Funktion (oleauto.h)

  • Artikel

Löscht eine Variante.

Syntax

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

Parameter

[in, out] pvarg

Die zu löschende Variante.

Rückgabewert

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Erfolg.
DISP_E_ARRAYISLOCKED
 Die Variante enthält ein Array, das gesperrt ist.
DISP_E_BADVARTYPE
 Der Variant-Typ ist kein gültiger Variant-Typ.
E_INVALIDARG
Eines der Argumente ist ungültig.

Hinweise

Verwenden Sie diese Funktion, um Variablen vom Typ VARIANTARG (oder VARIANT) zu löschen, bevor der Arbeitsspeicher, der das VARIANTARG enthält, freigegeben wird (wie wenn eine lokale Variable den Gültigkeitsbereich überschreitet).

Die Funktion löscht ein VARIANTARG,indem das vt-Feld auf VT_EMPTY festgelegt wird. Die aktuellen Inhalte des VARIANTARG werden zuerst veröffentlicht. Wenn das vtfield VT_BSTR ist, wird die Zeichenfolge freigegeben. Wenn das vtfield VT_DISPATCH ist, wird das Objekt freigegeben. Wenn für das vt-Feld das VT_ARRAY Bit festgelegt ist, wird das Array freigegeben.

Wenn es sich bei der zu löschenden Variante um ein COM-Objekt handelt, das per Verweis übergeben wird, wird das vt-Feld des pvargparameters VT_DISPATCH | VT_BYREF oder VT_UNKNOWN | VT_BYREF. In diesem Fall gibt VariantClear das -Objekt nicht frei. Da die zu löschende Variante ein Zeiger auf einen Verweis auf ein Objekt ist, kann VariantClear nicht bestimmen, ob das Objekt freigegeben werden muss. Es liegt daher in der Verantwortung des Aufrufers, das Objekt gegebenenfalls freizugeben oder nicht.

In bestimmten Fällen kann es besser sein, eine Variante im Code zu löschen, ohne VariantClear aufzurufen. Beispielsweise können Sie den Typ einer VT_I4 Variante in einen anderen Typ ändern, ohne diese Funktion aufzurufen. Für Safearrays von BSTR wird SysFreeString für jedes Element aufgerufen, nicht VariantClear. Sie müssen VariantClear jedoch aufrufen, wenn ein VT_type empfangen wird, aber nicht verarbeitet werden kann. Safearrays von variant wird auch VariantClear für jedes Element aufgerufen. Die Verwendung von VariantClear stellt in diesen Fällen sicher, dass Code weiterhin funktioniert, wenn Automation in Zukunft neue Variantentypen hinzufügt.

Verwenden Sie VariantClear nicht für nicht initialisierte Varianten. verwenden Sie VariantInit , um eine neue VARIANTARG- oder VARIANT-Instanz zu initialisieren.

Varianten, die Arrays mit ausstehenden Verweisen enthalten, können nicht gelöscht werden. Versuche, dies zu tun, geben ein HRESULT zurück, das DISP_E_ARRAYISLOCKED enthält.

Beispiele

Das folgende Beispiel zeigt, wie ein Array von Varianten gelöscht wird, wobei celt die Anzahl der Elemente im Array ist.

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

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile oleauto.h
Bibliothek OleAut32.lib
DLL OleAut32.dll

Weitere Informationen

Variantenbearbeitungsfunktionen