IWbemEventConsumerProvider

イベントコンシューマープロバイダーの主要なインターフェイスを提供します。このインターフェイスと FindConsumer メソッドを通じて、イベントコンシューマープロバイダーは、指定されたイベントをどのイベントコンシューマーが受信すべきかを示すことができます。

FindConsumer 関数は、WMI がイベントを送信できるシンクオブジェクトを見つけて返します。

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

Windows Management は、スキーマ内に登録された論理コンシューマーに対して、 IWbemClassObject の形式でイベントを配信します。コンシューマープロバイダーは FindConsumer を実装し、論理コンシューマーにイベントを配信する必要が生じるたびに、イベントシンクを Windows Management に提供します。

Windows Management は論理コンシューマーオブジェクトを認識し、配信の準備が整ったイベントオブジェクトを保持しています。イベントオブジェクトを配信するために、WMI は FindConsumer を呼び出します。コンシューマープロバイダーはイベントシンクオブジェクト( IWbemUnboundObjectSink へのポインター)を作成し、そのポインターを Windows Management に返す必要があります。これによりイベントが配信されます。

この手法を用いると、単一のイベントコンシューマープロバイダーが、論理コンシューマーごとに異なる IWbemUnboundObjectSink ポインターを返すことで、多数の異なる論理コンシューマーへのイベント配信を処理できます。

FindConsumer は、いくつかの方法で実装できます。

• すべての論理コンシューマーに対して単一のシンクを提供する。

  この方法は、メモリ上に COM オブジェクトが 1 つだけ保持されるため、空間効率の面で最も優れています。たとえば、メッセージをファイルに記録する論理コンシューマー向けにシンクを提供するイベントコンシューマープロバイダーを考えます。この場合、単一のシンクが、各論理コンシューマーに含まれるデータを調べ、どのように処理するかを判断する責任を負います。受信するイベントごとに、ログファイルを開き、メッセージを記録し、ファイルを閉じるという処理が必要になる可能性が高くなります。空間効率は良いものの、この方法は処理時間を大幅に消費します。

• 論理コンシューマーごとに異なるシンクを提供する。

  この方法は、イベント発生時に受信可能な専用のシンクを用意することで、パフォーマンスを最適化します。単一のシンクよりも高速ですが、メモリコストの面では効率が劣ります。各シンクが独自のログファイルを保持するため、ファイルを常に開いたままにでき、イベント発生時に直ちにメッセージを記録できます。タイムアウト後に WMI がシンクを解放した時点で、シンクはファイルを閉じることができ、高速な配信シナリオでも低速な配信シナリオでも効率的なパフォーマンスが得られます。

• 論理コンシューマーをグループに分け、グループごとに異なるシンクを提供する。

  この方法は、パフォーマンスと効率の折衷案です。このハイブリッドな手法では、記録するメッセージの種類ごとにログファイルを対応付けるなど、複数の異なるログファイルを使用できます。複数の COM オブジェクトが複数の開いたファイルを処理します。この方法を採用するイベントコンシューマープロバイダーは、 FindConsumer の呼び出し時にログファイル名を読み取ってファイルを開き、そのファイルにすべてのメッセージを記録するシンクを返します。プロバイダーは、Release メソッドの最後の呼び出し時にファイルを閉じます。この方法では、どのファイルを使用するかが正確に分かっているため、効率が保たれます。コンシューマーは新しいファイルを検索したり開いたりする必要がありません。また、異なるメッセージを同じファイルに記録するシンクを統合することで、メモリを節約できます。

いずれの方法を採用する場合でも、実装はイベントコンシューマープロバイダーの存在に依存すべきではありません。WMI は、呼び出しの間に指定された時間が経過すると、イベントコンシューマープロバイダーを解放します。WMI がイベントコンシューマープロバイダーを必要とするのは、新しい論理コンシューマー向けのシンクへのポインターを取得するときだけであるため、対象となるすべての論理コンシューマーへの対応が完了すると、WMI はイベントコンシューマープロバイダーを解放できます。ただし、シンクは、発生するすべてのイベントを受信するために残っている必要があります。

例

次のコード例は、 FindConsumer の実装を示しています。以下の実装では、登録された 2 つの異なるイベントフィルターそれぞれに対応する、イベント受信用のシンクが 2 つ存在すると仮定します。 FindConsumer がどのシンクを WMI に返すかを判断するために、このコードは渡された論理コンシューマーオブジェクトを調べます。

HRESULT MyEventConsumerClass::FindConsumer(
   /* [in] */ IWbemClassObject __RPC_FAR *pLogicalConsumer,
   /* [out] */ IWbemUnboundObjectSink __RPC_FAR *__RPC_FAR *ppConsumer
   )
{
   // Examine the logical consumer to see which one it is.
   // ====================================================

   VARIANT v;    
   VariantInit(&v);

   HRESULT hRes = WBEM_E_NOT_FOUND;
   *ppConsumer = 0;

   pLogicalConsumer->Get(_bstr_t(L"Name"), 0, &v, 0, 0);

   // Decide which of the two logical consumers to send back.
   // =======================================================

   if (_wcsicmp(V_BSTR(&v), L"Consumer1") == 0)
   {

    //send back the Consumer1 sink to WMI
    // For example:
      /*hRes =  m_pConsumer1->
         QueryInterface(IID_IWbemUnboundObjectSink,
                           (LPVOID*)ppConsumer);*/
   }
   else if (_wcsicmp(V_BSTR(&v), L"Consumer2") == 0)
   {
    //send back the Consumer2 sink to WMI
    // For example:
      /*hRes =  m_pConsumer2->
          QueryInterface(IID_IWbemUnboundObjectSink,
                            (LPVOID*)ppConsumer);*/
   }

   VariantClear(&v);
   return hRes;
}

#define global IID_IWbemEventConsumerProvider "{E246107A-B06E-11D0-AD61-00C04FD8FDFF}"
#usecom global IWbemEventConsumerProvider IID_IWbemEventConsumerProvider "{}"
#comfunc global IWbemEventConsumerProvider_FindConsumer  3 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。