Funzione VariantClear (oleauto.h)
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 |
|---|---|
|
Operazione completata. |
|
La variante contiene una matrice bloccata. |
|
Il tipo variant non è un tipo valido di variant. |
|
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 |