Win32 API 日本語リファレンス
ホーム › System.Wmi › IWbemContext

IWbemContext

COM
📘 Microsoft Learn (日本語) · English
IID44aca674-e8fc-11d0-a07c-00c04fb68820継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IWbemContext インターフェイスは、IWbemServices の呼び出しを WMI に送信する際に、追加のコンテキスト情報をプロバイダーへ伝えるために任意で使用します。IWbemServices の主要な呼び出しはいずれも、この型のオブジェクトを指す省略可能なパラメーターを受け取ります。

解説(Remarks)

動的プロバイダーは、 IWbemServices メソッドの通常のパラメーターで指定される情報だけでは足りない場合がよくあります。たとえば、提供する WMI スキーマオブジェクトを操作するために、プロバイダーが Simple Network Management Protocol (SNMP) のコミュニティ名や、Structured Query Language (SQL) のデータベース名およびテーブル名を必要とすることがあります。クライアントはこうした情報を IWbemContext オブジェクトに追加し、その IWbemContext オブジェクトをパラメーターの 1 つとして呼び出しに渡すことができます。

プロバイダーはコンテキストオブジェクトの使用を最小限にとどめるべきです。理想的には必須にしないことが推奨されます。要求に応答するために大量の固有なコンテキスト情報を必要とするプロバイダーがあると、すべてのクライアントがその情報を渡すように実装しなければならず、WMI の基盤である統一的なアクセスモデルが損なわれます。とはいえ、避けられない場合もあります。そのため、こうしたプロバイダーにアクセスできるようにこの仕組みが用意されています。そのようなプロバイダーの開発者は、クライアントソフトウェアの開発者が CIM オブジェクトを正しく操作できるよう、十分なドキュメントを提供してください。

クライアントが要求により多くの情報を指定できるように IWbemContext の使用をサポートするプロバイダーは、サポートする値の型を次の一覧の型に限定してください。

メモ VT_UNKNOWN 型のバリアントを使用して IWbemContext インスタンス内で IUnknown メソッドをマーシャリングできるのは、 IWbemClassObject をサポートするオブジェクトのみです。
CoCreateInstanceEx を使用して作成される IWbemContext オブジェクトは、名前付きの値を保持する単純なコンテナーです。これらのメソッドを利用して、動的プロバイダーが必要とするコンテキスト情報を設定します。 IWbemServices のいずれかのメソッドを呼び出した後、 IWbemContext オブジェクトは別の呼び出しで再利用できます。あるいは Release で解放し、 IWbemServices メソッドへの他の呼び出し用に別のオブジェクトを作成することもできます。

IWbemContext オブジェクトに含まれる情報の内容は、基になるプロバイダーによって完全に決定されます。WMI はその情報を使用せず、プロバイダーへ転送するだけです。プロバイダーは、これらのサービス要求に必要なコンテキスト情報を公開する必要があります。

クライアントアプリケーションは CoCreateInstanceEx を呼び出して 1 つのコンテキストオブジェクトを作成します。次に SetValue を 1 回以上呼び出して、プロバイダー向けのコンテキスト値を設定します。最後に、そのオブジェクトを IWbemServices のいずれかのメソッドに渡します。メソッドは呼び出しから戻った直後に、コンテキストオブジェクトに対して Release を呼び出します。その他のメソッドは、主にコンテキストオブジェクトを受け取って情報を取り出すプロバイダーが使用します。

メソッド 9

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Clone(IWbemContext** ppNewCopy)

IWbemContext::Clone メソッドは、現在の IWbemContext オブジェクトの論理コピーを作成します。このメソッドは、ほぼ同一の IWbemContext オブジェクトを伴う呼び出しを多数行う必要がある場合に便利です。

ppNewCopyIWbemContext**out入力時に NULL を指している必要があります。現在のオブジェクトのクローンを含む新しいオブジェクトへのポインターを受け取ります。返されるポインターは正の参照カウントを持ちます。呼び出し元は、不要になった時点でこのポインターに対して IWbemServices::Release を呼び出す必要があります。エラー時には、このポインターは変更されず、新しいオブジェクトも返されません。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 4 HRESULT GetNames(INT lFlags, SAFEARRAY** pNames)

IWbemContext::GetNames メソッドは、名前付きコンテキスト値のすべての名前を格納した SAFEARRAY 構造体を返します。

lFlagsINTin予約済みです。このパラメーターは 0 でなければなりません。
pNamesSAFEARRAY**out

このパラメーターを NULL にすることはできませんが、入力時には NULL を指している必要があります。エラーが返されなかった場合、終了時に pstrNames は、すべてのコンテキスト値名を格納した VT_BSTR 型の新しい SAFEARRAY 構造体へのポインターを受け取ります。呼び出し元は、配列が不要になった時点で、返されたポインターに対して SafeArrayDestroy を呼び出す必要があります。エラーコードが返された場合、ポインターは変更されません。

メモ オブジェクトに名前付きの値が 1 つも存在しない場合、呼び出しは成功し、長さ 0 の配列を返します。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

解説(Remarks)

BSTR 値の SAFEARRAY 構造体の使用方法の詳細については、 Retrieving Part of a WMI Instance を参照してください。

vtbl 5 HRESULT BeginEnumeration(INT lFlags)

IWbemContext::BeginEnumeration メソッドは、オブジェクト内のすべてのコンテキスト値の列挙をリセットします。

lFlagsINTin予約済みです。このパラメーターは 0 でなければなりません。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 6 HRESULT Next(INT lFlags, LPWSTR* pstrName, VARIANT* pValue)

IWbemContext::Next メソッドは、IWbemContext::BeginEnumeration で開始したすべてのコンテキスト値の列挙において、次の値を取得します。

lFlagsINTin予約済みです。このパラメーターは 0 でなければなりません。
pstrNameLPWSTR*out

このパラメーターを NULL にすることはできません。入力時に、このポインターが有効な BSTR を指していてはならず、NULL を指すように設定しておくのが理想的です。エラーコードが返されなかった場合、コンテキスト値の名前を含む新しく割り当てられた BSTR を指すように設定されます。

呼び出し元は、返された文字列が不要になった時点で SysFreeString を呼び出す必要があります。WBEM_S_NO_MORE_DATA が返された場合、pstrName は NULL を指すように設定されるため、SysFreeString を呼び出さないでください。なお、入力時に pstrName が有効な BSTR を指している場合、その BSTR は解放されず、メモリリークが発生します。

pValueVARIANT*out

このパラメーターを NULL にすることはできず、空または未初期化の VARIANT を指している必要があります。エラーが返されなかった場合、VARIANT は VariantInit で初期化され、コンテキスト値が格納されます。呼び出し元は、値が不要になった時点でこのポインターに対して VariantClear を呼び出す必要があります。エラーコードが返された場合、pValue が指す VARIANT は変更されません。

WBEM_S_NO_MORE_DATA が返された場合、このパラメーターは VT_NULL 型の VARIANT を指すように設定されます。

VARIANT の中で IWbemClassObject オブジェクト全体が返される場合もあります。その場合、VARIANT の型は VT_UNKNOWN になります。呼び出し元は IUnknown ポインターを取得し、QueryInterface を実行して IWbemClassObject ポインターを取得できます。

メモ 列挙の終わりでは WBEM_S_NO_MORE_DATA が返されます。返される VARIANT は VT_NULL 型となり、返される pstrName は NULL になります。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 7 HRESULT EndEnumeration()

IWbemContext::EndEnumeration メソッドは、IWbemContext::BeginEnumeration で開始した列挙シーケンスを終了します。この呼び出しは必須ではありませんが、列挙に関連付けられたシステムリソースをできるだけ早く解放します。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 8 HRESULT SetValue(LPWSTR wszName, INT lFlags, VARIANT* pValue)

IWbemContext::SetValue メソッドは、名前付きコンテキスト値を作成または上書きします。

wszNameLPWSTRinNULL にすることはできません。コンテキスト値の名前を示す読み取り専用のポインターです。この値は null で終端されている必要があります。
lFlagsINTin予約済みです。このパラメーターは 0 (ゼロ) でなければなりません。
pValueVARIANT*in

有効な VARIANT を指している必要があり、この VARIANT は読み取り専用として扱われます。VARIANT 内の値が名前付きコンテキスト値になります。単純な値だけでなく、VT_UNKNOWN 型を使用する VARIANT に格納することで IWbemClassObject オブジェクト全体を格納することもできます。呼び出し元は、IID_IUnknown を要求して IWbemClassObject オブジェクトに対して QueryInterface を実行し、返されたポインターを VARIANT 内で使用する必要があります。

pValue に埋め込みの IWbemClassObject オブジェクトを格納する場合、呼び出し元は IID_IUnknown を指定して IWbemClassObject::QueryInterface を呼び出し、得られたポインターを VT_UNKNOWN 型の VARIANT に格納する必要があります。元の埋め込みオブジェクトは書き込み操作の際にコピーされるため、この操作によって変更されることはありません。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を列挙して説明します。

vtbl 9 HRESULT GetValue(LPWSTR wszName, INT lFlags, VARIANT* pValue)

IWbemContext::GetValue メソッドは、特定の名前付きコンテキスト値を名前によって取得するために使用します。

wszNameLPWSTRin値を取得する対象の名前です。有効な BSTR を指している必要があります。このポインターは読み取り専用として扱われます。
lFlagsINTin予約済みです。このパラメーターは 0 でなければなりません。
pValueVARIANT*out

このパラメーターを NULL にすることはできず、未初期化の VARIANT を指している必要があります。エラーが返されなかった場合、VARIANT は VariantInit で初期化され、コンテキスト値が格納されます。呼び出し元は、値が不要になった時点でこのポインターに対して VariantClear を呼び出す必要があります。エラーコードが返された場合、pValue が指す VARIANT は変更されません。

VARIANT の中で IWbemClassObject オブジェクト全体が返される場合もあります。その場合、VARIANT の型は VT_UNKNOWN になります。呼び出し元は IUnknown ポインターを取得し、QueryInterface を実行して IWbemClassObject ポインターを取得できます。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 10 HRESULT DeleteValue(LPWSTR wszName, INT lFlags)

IWbemContext::DeleteValue メソッドは、IWbemContext::SetValue で作成された名前付きコンテキスト値を削除します。

wszNameLPWSTRin削除する名前付きコンテキスト値を含む有効な BSTR へのポインターです。このポインターは読み取り専用として扱われます。
lFlagsINTin予約済みです。このパラメーターは 0 でなければなりません。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

vtbl 11 HRESULT DeleteAll()

IWbemContext::DeleteAll メソッドは、現在のオブジェクトからすべての名前付きコンテキスト値を削除し、オブジェクトを空にします。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下の一覧は、HRESULT に含まれる値を示します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IWbemContext "{44ACA674-E8FC-11D0-A07C-00C04FB68820}"
#usecom global IWbemContext IID_IWbemContext "{674B6698-EE92-11D0-AD71-00C04FD8FDFF}"
#comfunc global IWbemContext_Clone             3 sptr
#comfunc global IWbemContext_GetNames          4 int,var
#comfunc global IWbemContext_BeginEnumeration  5 int
#comfunc global IWbemContext_Next              6 int,var,var
#comfunc global IWbemContext_EndEnumeration    7
#comfunc global IWbemContext_SetValue          8 wstr,int,var
#comfunc global IWbemContext_GetValue          9 wstr,int,var
#comfunc global IWbemContext_DeleteValue       10 wstr,int
#comfunc global IWbemContext_DeleteAll         11
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。