VariantClear 関数 (oleauto.h)

  • [アーティクル]

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

構文

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

パラメーター

[in, out] pvarg

クリアするバリアント。

戻り値

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

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

注釈

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

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

初期化されていない バリアントでは VariantClear を使用しないでください。 新しい VARIANTARG または VARIANT を初期化するには、VariantInit を使用します。

未処理の参照を持つ配列を含むバリアントはクリアできません。 これを試みると、DISP_E_ARRAYISLOCKEDを含む HRESULT が返されます。

例

次の例は、バリアントの配列をクリアする方法を示しています。ここで celt 、 は配列内の要素の数です。

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

要件

要件 値
対象プラットフォーム Windows
ヘッダー oleauto.h
Library OleAut32.lib
[DLL] OleAut32.dll

こちらもご覧ください

バリアント操作関数