Funzione VariantClear (oleauto.h)

  • Articolo

Cancella una variante.

Sintassi

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

Parametri

[in, out] pvarg

Variante da cancellare.

Valore restituito

Questa funzione può restituire uno di questi valori.

Codice restituito Descrizione
S_OK
 Operazione completata.
DISP_E_ARRAYISLOCKED
 La variante contiene una matrice bloccata.
DISP_E_BADVARTYPE
 Il tipo variant non è un tipo valido di variant.
E_INVALIDARG
Uno degli argomenti non è valido.

Commenti

Usare questa funzione per cancellare le variabili di tipo VARIANTARG (o VARIANT) prima che la memoria contenente VARIANTARG venga liberata (come quando una variabile locale esce dall'ambito).

La funzione cancella un valore VARIANTARG impostando il campo vt su VT_EMPTY. Il contenuto corrente di VARIANTARG viene rilasciato per primo. Se il vtfield è VT_BSTR, la stringa viene liberata. Se il vtfield è VT_DISPATCH, l'oggetto viene rilasciato. Se il campo vt ha il VT_ARRAY bit impostato, la matrice viene liberata.

Se la variante da cancellare è un oggetto COM passato per riferimento, il campo vtfield del pvargparameter è VT_DISPATCH | VT_BYREF o VT_UNKNOWN | VT_BYREF. In questo caso , VariantClear non rilascia l'oggetto . Poiché la variante da cancellare è un puntatore a un riferimento a un oggetto, VariantClear non può determinare se è necessario rilasciare l'oggetto. È quindi responsabilità del chiamante rilasciare o meno l'oggetto, in base alle esigenze.

In alcuni casi, può essere preferibile cancellare una variante nel codice senza chiamare VariantClear. Ad esempio, è possibile modificare il tipo di una variante VT_I4 in un altro tipo senza chiamare questa funzione. Safearrays di BSTR avrà SysFreeString chiamato su ogni elemento non VariantClear. Tuttavia, è necessario chiamare VariantClear se viene ricevuto un VT_type ma non può essere gestito. Safearrays di variant avrà anche VariantClear chiamato su ogni membro. L'uso di VariantClear in questi casi garantisce che il codice continuerà a funzionare se Automazione aggiunge nuovi tipi varianti in futuro.

Non utilizzare VariantClear su varianti non inizializzate; utilizzare VariantInit per inizializzare un nuovo VARIANTARG o VARIANT.

Le varianti contenenti matrici con riferimenti in sospeso non possono essere cancellate. I tentativi di eseguire questa operazione restituiranno un valore HRESULT contenente DISP_E_ARRAYISLOCKED.

Esempio

Nell'esempio seguente viene illustrato come cancellare una matrice di varianti, dove celt è il numero di elementi nella matrice.

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

Requisiti

Requisito Valore
Piattaforma di destinazione Windows
Intestazione oleauto.h
Libreria OleAut32.lib
DLL OleAut32.dll

Vedi anche

Funzioni di manipolazione varianti