VariantClear 函数 (oleauto.h)

  • 项目

清除变体。

语法

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

参数

[in, out] pvarg

要清除的变体。

返回值

此函数可以返回其中一个值。

返回代码 说明
S_OK
 成功。
DISP_E_ARRAYISLOCKED
 变体包含已锁定的数组。
DISP_E_BADVARTYPE
 变体类型不是有效的变体类型。
E_INVALIDARG
其中一个参数无效。

注解

使用此函数在释放包含 VARIANTARG 的内存之前清除 VARIANTARG (或 VARIANT) 类型的变量， (为局部变量超出范围) 。

函数通过将 vt 字段设置为 VT_EMPTY 来清除 VARIANTARG。 首先发布 VARIANTARG 的当前内容。 如果 vtfield 为VT_BSTR，则释放字符串。 如果 vtfield 是VT_DISPATCH，则释放 对象。 如果 vt 字段设置了VT_ARRAY位，则释放数组。

如果要清除的变体是通过引用传递的 COM 对象，则会VT_DISPATCH pvargparameter 的 vtfield |VT_BYREF或VT_UNKNOWN |VT_BYREF。 在本例中， VariantClear 不会释放 对象。 由于要清除的变体是指向对象引用的指针， 因此 VariantClear 无法确定是否需要释放对象。 因此，调用方负责根据需要释放对象。

在某些情况下，最好在不调用 VariantClear 的情况下清除代码中的变体。 例如，可以将VT_I4变体的类型更改为另一种类型，而无需调用此函数。 BSTR 的 Safearray 将对每个元素（而不是 VariantClear）调用 SysFreeString。 但是，如果收到VT_type但无法处理，则必须调用 VariantClear 。 variant 的 Safearray 还将在每个成员上调用 VariantClear 。 在这些情况下，使用 VariantClear 可确保如果自动化将来添加新的变体类型，代码将继续工作。

不要对未初始化的变体使用 VariantClear ;使用 VariantInit 初始化新的 VARIANTARG 或 VARIANT。

无法清除包含具有未完成引用的数组的变体。 尝试这样做将返回包含DISP_E_ARRAYISLOCKED的 HRESULT。

示例

以下示例演示如何清除变体数组，其中 celt 是数组中的元素数。

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

要求

要求 值
目标平台 Windows
标头 oleauto.h
Library OleAut32.lib
DLL OleAut32.dll

另请参阅

变体操作函数