Функция VariantClear (oleauto.h)
Очищает вариант.
Синтаксис
HRESULT VariantClear(
[in, out] VARIANTARG *pvarg
);
Параметры
[in, out] pvarg
Вариант для очистки.
Возвращаемое значение
Эта функция может возвращать одно из этих значений.
| Код возврата | Описание |
|---|---|
|
Успешно. |
|
Вариант содержит заблокированный массив. |
|
Тип variant не является допустимым типом variant. |
|
Один из аргументов недопустим. |
Комментарии
Используйте эту функцию для очистки переменных типа 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 |