VariantClear 函式 (oleauto.h)

清除變體。

語法

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

參數

[in, out] pvarg

要清除的變體。

傳回值

此函式可以傳回其中一個值。

傳回碼	描述
S_OK	成功。
DISP_E_ARRAYISLOCKED	Variant 包含已鎖定的陣列。
DISP_E_BADVARTYPE	Variant 類型不是有效的 Variant 類型。
E_INVALIDARG	其中一個自變數無效。

備註

使用此函式可清除 VARIANTARG 類型變數 (或 VARIANT) ，再釋出包含 VARIANTARG 的記憶體 (，如同局部變數超出範圍) 時一樣。

函式會將 vt 字段設定為 VT_EMPTY，以清除 VARIANTARG。 VARIANTARG 的目前內容會先發行。 如果 vtfield 是VT_BSTR，則會釋放字串。 如果 vtfield 是VT_DISPATCH，則會釋放物件。 如果 vt 欄位已設定VT_ARRAY位，則會釋放數位。

如果要清除的變體是以傳址方式傳遞的 COM 物件，pvargparameter 的 vtfield 會VT_DISPATCH |VT_BYREF或VT_UNKNOWN |VT_BYREF。 在此情況下， VariantClear 不會釋放 物件。 因為所清除的 Variant 是對象的參考指標， VariantClear 無法判斷是否需要釋放物件。 因此，呼叫端必須視需要釋放對象的責任。

在某些情況下，最好清除程序代碼中的變體，而不呼叫 VariantClear。 例如，您可以將VT_I4變體的類型變更為另一個類型，而不呼叫此函式。 BSTR 的 Safearrays 會在不是 VariantClear 的每個元素上呼叫 SysFreeString。 不過，如果收到VT_type但無法處理，您必須呼叫 VariantClear 。 Variant 的 Safearray 也會在每個成員上呼叫 VariantClear 。 在這些情況下使用 VariantClear 可確保如果自動化在未來加入新的變體類型，程式代碼將會繼續運作。

請勿在未初始化的 變體上使用 VariantClear ;使用 VariantInit 初始化新的 VARIANTARG 或 VARIANT。

無法清除包含具有未處理參考之陣列的變體。 嘗試這樣做會傳回包含DISP_E_ARRAYISLOCKED的 HRESULT。

範例

下列範例示範如何清除 Variant 的陣列，其中 celt 是陣列中的元素數目。

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

規格需求

需求	值
目標平台	Windows
標頭	oleauto.h
程式庫	OleAut32.lib
Dll	OleAut32.dll

另請參閱

Variant 操作函式