VariantClear 函式 (oleauto.h)
清除變體。
語法
HRESULT VariantClear(
[in, out] VARIANTARG *pvarg
);
參數
[in, out] pvarg
要清除的變體。
傳回值
此函式可以傳回其中一個值。
| 傳回碼 | 描述 |
|---|---|
|
成功。 |
|
Variant 包含已鎖定的陣列。 |
|
Variant 類型不是有效的 Variant 類型。 |
|
其中一個自變數無效。 |
備註
使用此函式可清除 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 |