Поделиться через


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

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

Синтаксис

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

Параметры

[in, out] pvarg

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

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

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

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

Комментарии

Используйте эту функцию для очистки переменных типа VARIANTARG (или VARIANT) перед освобождением памяти, содержащей VARIANTARG (как при выходе локальной переменной из область).

Функция очищает 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

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

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