Função VariantClear (oleauto.h)

Limpa uma variante.

Sintaxe

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

Parâmetros

[in, out] pvarg

A variante a ser limpa.

Retornar valor

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	Êxito.
DISP_E_ARRAYISLOCKED	A variante contém uma matriz bloqueada.
DISP_E_BADVARTYPE	O tipo variante não é um tipo válido de variante.
E_INVALIDARG	Um dos argumentos não é válido.

Comentários

Use essa função para limpar variáveis do tipo VARIANTARG (ou VARIANT) antes que a memória que contém VARIANTARG seja liberada (como quando uma variável local sai do escopo).

A função limpa um VARIANTARG definindo o campo vt como VT_EMPTY. O conteúdo atual do VARIANTARG é lançado primeiro. Se o vtfield for VT_BSTR, a cadeia de caracteres será liberada. Se o vtfield for VT_DISPATCH, o objeto será liberado. Se o campo vt tiver o VT_ARRAY bit definido, a matriz será liberada.

Se a variante a ser desmarcada for um objeto COM passado por referência, o vtfield do pvargparameter será VT_DISPATCH | VT_BYREF ou VT_UNKNOWN | VT_BYREF. Nesse caso, VariantClear não libera o objeto . Como a variante que está sendo desmarcada é um ponteiro para uma referência a um objeto , VariantClear não tem como determinar se é necessário liberar o objeto. Portanto, é responsabilidade do chamador liberar o objeto ou não, conforme apropriado.

Em determinados casos, pode ser preferível limpar uma variante no código sem chamar VariantClear. Por exemplo, você pode alterar o tipo de uma variante VT_I4 para outro tipo sem chamar essa função. Safearrays do BSTR terá SysFreeString chamado em cada elemento, não VariantClear. No entanto, você deverá chamar VariantClear se um VT_type for recebido, mas não puder ser tratado. As safearrays de variant também terão VariantClear chamado em cada membro. Usar VariantClear nesses casos garante que o código continue funcionando se a Automação adicionar novos tipos de variante no futuro.

Não use VariantClear em variantes não inicializadas; use VariantInit para inicializar um novo VARIANTARG ou VARIANT.

As variantes que contêm matrizes com referências pendentes não podem ser limpas. As tentativas de fazer isso retornarão um HRESULT que contém DISP_E_ARRAYISLOCKED.

Exemplos

O exemplo a seguir mostra como limpar uma matriz de variantes, em que celt é o número de elementos na matriz.

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

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	oleauto.h
Biblioteca	OleAut32.lib
DLL	OleAut32.dll

Confira também

Funções de manipulação de variantes