共用方式為


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 操作函式