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

IWbemEventProviderQuerySink

COM
📘 Microsoft Learn (日本語) · English
IID580acaf8-fa1c-11d0-ad72-00c04fd8fdff継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IWbemEventProviderQuerySink インターフェイスは、パフォーマンスを最適化するために現在どのようなイベントクエリフィルターが有効になっているかを知りたいイベントプロバイダーが、任意で実装するインターフェイスです。

解説(Remarks)

WMI は、イベントプロバイダーがアクティブになった後に IWbemEventProvider のメソッドを一度だけ呼び出しますが、 IWbemEventProviderQuerySink のメソッドは必要に応じて継続的に呼び出します。プロバイダーは、必要に応じて IWbemEventProviderQuerySink メソッドへのすべての呼び出しを無視できます。この点は非常に重要です。 IWbemEventProviderQuerySink をサポートするということは、プロバイダーが少なくともクエリによって要求されたイベントを提供することを示します。

プロバイダーは要求された以上のイベントを生成することもでき、WMI が適切にそれらをフィルター処理します。この機能により、WMI クエリ言語 (WQL) のすべての部分に対応しなくても、 IWbemEventProviderQuerySink を実装して処理を最適化できます。たとえば、プロバイダーが特定のクエリを個別に処理しない場合、そのクエリに対して発生し得るすべてのイベントを生成できます。

メソッド 2

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

vtbl 3 HRESULT NewQuery(DWORD dwId, WORD* wszQueryLanguage, WORD* wszQuery)

論理イベントコンシューマーが関連するイベントクエリフィルターを Windows Management に登録したときに、IWbemEventProviderQuerySink::NewQuery メソッドを呼び出します。

dwIdDWORDinクエリに対して Windows Management が生成した識別子です。プロバイダーはこれを追跡することで、後に CancelQuery が呼び出された際に、どのクエリがキャンセルされたのかを知ることができます。
wszQueryLanguageWORD*in後続のクエリフィルターの言語です。このバージョンの WMI では、常に "WQL" になります。
wszQueryWORD*in論理コンシューマーによって登録されたイベントクエリフィルターのテキストです。イベントプロバイダーは、wszQuery パラメーターでクエリフィルターのテキストを、wszQueryLanguage パラメーターでクエリフィルターの言語を調べることにより、コンシューマーがどのイベント通知を要求しているかを把握できます。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下のリストは NewQuery が返す戻り値コードの一覧です。さらに、サードパーティ製イベントプロバイダーは有効な任意の WMI または COM の戻り値コードを返すことができ、それらは NewQuery の戻り値として渡される可能性があります。

解説(Remarks)

コンシューマーがイベントフィルタークエリを Windows Management に登録し、そのクエリに現在のイベントプロバイダーが提供するイベントへの参照が含まれている場合、Windows Management はそのクエリをイベントプロバイダーに通知できます。

プロバイダーが IWbemEventProviderQuerySink インターフェイスを実装している場合、Windows Management はクエリテキストのコピーをプロバイダーに提供します。プロバイダーはクエリを解析し、内部的な最適化を行えるかどうかを判断します。

Windows Management は、プロバイダーが何らかの形で動作を変更することを期待しているわけではありません。むしろこれは、プロバイダーの内部的な最適化を支援するための助言的な呼び出しです。

たとえば、プロバイダーが数百種類ものイベントを提供できるものの、そのすべてを提供するためのオーバーヘッドが大きい場合、これらのイベントの大半が現在のイベントコンシューマーの集合から要求されていないと分かれば、大幅なコスト削減を実現できます。プロバイダーが IWbemEventProviderQuerySink を実装していれば、すべてのコンシューマーによって要求されている現在のイベントの集合を把握できます。これにより、コンシューマーが実際にそのようなイベントを要求し始めるまで、サポートするイベント型の大半について配信の仕組みを準備することを回避できる場合があります。

新しいコンシューマーのクエリフィルターごとに、一意の dwId を伴ってこのメソッドが個別に呼び出されます。ただし、Windows Management は同じ dwId 値に対して NewQuery を複数回呼び出す権利を留保している点に注意してください。たとえば、システムの別の場所でスキーマの変更があった場合などです。このバージョンの WMI では、クエリ言語は常に "WQL" です。

IWbemEventProviderQuerySink::NewQuery メソッドは、 IWbemEventProvider::ProvideEvents メソッドより前に呼び出されることがあります。

vtbl 4 HRESULT CancelQuery(DWORD dwId)

論理イベントコンシューマーが関連するイベントクエリフィルターを Windows Management に対してキャンセルするたびに、IWbemEventProviderQuerySink::CancelQuery メソッドを呼び出します。

dwIdDWORDinキャンセルされたクエリの識別子です。この識別子は、このインターフェイスの NewQuery メソッドによって、もともとプロバイダーに渡されたものです。

戻り値

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

解説(Remarks)

コンシューマーが新しいイベントクエリフィルターを登録するたびに、Windows Management はクエリ識別子を指定して IWbemEventProviderQuerySink::NewQuery メソッドを呼び出します。その後、そのクエリの登録が解除されると、どのクエリがもはや有効でないかを示すためにこのメソッドが呼び出されます。

プロバイダーは、内部的なイベント生成の最適化を支援するためにこのメソッドを使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IWbemEventProviderQuerySink "{580ACAF8-FA1C-11D0-AD72-00C04FD8FDFF}"
#usecom global IWbemEventProviderQuerySink IID_IWbemEventProviderQuerySink "{}"
#comfunc global IWbemEventProviderQuerySink_NewQuery     3 int,var,var
#comfunc global IWbemEventProviderQuerySink_CancelQuery  4 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。