VariantClear 関数 (oleauto.h)

バリアントをクリアします。

構文

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

パラメーター

[in, out] pvarg

クリアするバリアント。

戻り値

この関数は、これらの値のいずれかを返すことができます。

リターン コード 説明
S_OK
正常終了しました。
DISP_E_ARRAYISLOCKED
バリアントには、ロックされている配列が含まれています。
DISP_E_BADVARTYPE
バリアント型が有効なバリアント型ではありません。
E_INVALIDARG
引数の 1 つが無効です。

注釈

VARIANTARG を含むメモリが解放される前に (ローカル変数がスコープ外になったときと同様に) VARIANTARG 型 (または VARIANT) 型の変数をクリアするには、この関数を使用します。

この関数は、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 はオブジェクトを解放しません。 消去されるバリアントはオブジェクトへの参照へのポインターであるため、 VariantClear はオブジェクトを解放する必要があるかどうかを判断する方法はありません。 したがって、必要に応じて、オブジェクトを解放するかどうかは呼び出し元の責任です。

場合によっては、 VariantClear を呼び出さずにコード内のバリアントをクリアすることをお勧めします。 たとえば、この関数を呼び出さずに、VT_I4バリアントの型を別の型に変更できます。 BSTR の Safearrays では、VariantClear ではなく各要素で SysFreeString が呼び出されます。 ただし、VT_typeを受信しても処理できない場合は、 VariantClear を 呼び出す必要があります。 variant の Safearray では、各メンバーで VariantClear も呼び出されます。 このような場合に VariantClear を 使用すると、Automation によって将来新しいバリアント型が追加された場合でも、コードは引き続き機能します。

初期化されていない バリアントには 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

こちらもご覧ください

バリアント操作関数