VariantClear 函数 (oleauto.h)
清除变体。
语法
HRESULT VariantClear(
[in, out] VARIANTARG *pvarg
);
参数
[in, out] pvarg
要清除的变体。
返回值
此函数可以返回其中一个值。
| 返回代码 | 说明 |
|---|---|
|
成功。 |
|
变体包含已锁定的数组。 |
|
变体类型不是有效的变体类型。 |
|
其中一个参数无效。 |
注解
使用此函数在释放包含 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 |