Функция VariantClear (oleauto.h)

Статья
03/01/2024

Очищает вариант.

Синтаксис

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

Параметры

[in, out] pvarg

Вариант для очистки.

Возвращаемое значение

Эта функция может возвращать одно из этих значений.

Код возврата	Описание
S_OK	Успешно.
DISP_E_ARRAYISLOCKED	Вариант содержит заблокированный массив.
DISP_E_BADVARTYPE	Тип variant не является допустимым типом variant.
E_INVALIDARG	Один из аргументов недопустим.

Функция очищает VARIANTARG, задавая для поля vt значение VT_EMPTY. Сначала освобождается текущее содержимое VARIANTARG. Если поле vt VT_BSTR, строка освобождается. Если поле vt VT_DISPATCH, объект освобождается. Если для поля vt задан бит VT_ARRAY, массив освобождается.

Если очищаемый вариант является COM-объектом, передаваемым по ссылке, поле vt для pvargparameter равно VT_DISPATCH | VT_BYREF или VT_UNKNOWN | VT_BYREF. В этом случае VariantClear не освобождает объект . Поскольку очищаемый вариант является указателем на ссылку на объект, VariantClear не может определить, нужно ли освободить объект. Поэтому вызывающий объект должен освободить объект или нет соответствующим образом.

В некоторых случаях может быть предпочтительнее очистить вариант в коде без вызова VariantClear. Например, можно изменить тип варианта VT_I4 на другой, не вызывая эту функцию. В safearrays BSTR будет вызываться SysFreeString для каждого элемента, а не VariantClear. Однако необходимо вызвать VariantClear , если VT_type получено, но не может быть обработано. Для safearrays variant также будет вызываться VariantClear для каждого элемента. Использование VariantClear в этих случаях гарантирует, что код будет продолжать работать, если служба автоматизации добавит новые типы вариантов в будущем.

Не используйте VariantClear для неинициализированных вариантов; используйте VariantInit для инициализации новой версии VARIANTARG или VARIANT.

Варианты, содержащие массивы с невыполненными ссылками, не могут быть очищены. Попытки сделать это будут возвращать HRESULT, содержащий DISP_E_ARRAYISLOCKED.

Примеры

В следующем примере показано, как очистить массив вариантов, где celt — количество элементов в массиве.

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

Требования

Требование	Значение
Целевая платформа	Windows
Header	oleauto.h
Библиотека	OleAut32.lib
DLL	OleAut32.dll

См. также раздел

Функции обработки вариантов