EvtSubscribe 関数 (winevt.h)

指定したクエリ条件に一致するチャネルまたはログ ファイルから現在および将来のイベントを受信するサブスクリプションを作成します。

構文

EVT_HANDLE EvtSubscribe(
  [in] EVT_HANDLE             Session,
  [in] HANDLE                 SignalEvent,
  [in] LPCWSTR                ChannelPath,
  [in] LPCWSTR                Query,
  [in] EVT_HANDLE             Bookmark,
  [in] PVOID                  Context,
  [in] EVT_SUBSCRIBE_CALLBACK Callback,
  [in] DWORD                  Flags
);

パラメーター

[in] Session

EvtOpenSession 関数が返すリモート セッション ハンドル。 ローカル コンピューター上のイベントをサブスクライブするには 、NULL に設定します。

[in] SignalEvent

クエリ条件に一致する新しいイベントが使用可能になったときにサービスによって通知されるイベント オブジェクトのハンドル。 Callback パラメーターが NULL でない場合、このパラメーターは NULL である必要があります。

[in] ChannelPath

サブスクライブするイベントを含む管理または運用チャネルの名前 (分析チャネルまたはデバッグ チャネルをサブスクライブすることはできません)。 Query パラメーターに XPath クエリが含まれている場合は、パスが必要です。Query パラメーターに構造化 XML クエリが含まれている場合、パスは無視されます。

[in] Query

サブスクリプション サービスから返されるイベントの種類を指定するクエリ。 XPath 1.0 クエリまたは構造化 XML クエリを指定できます。 XPath に 20 を超える式が含まれている場合は、構造化 XML クエリを使用します。 すべてのイベントを受信するには、このパラメーターを NULL または "*" に設定します。

[in] Bookmark

サブスクリプションの開始点を識別するブックマークへのハンドル。 ブックマーク ハンドルを取得するには、 EvtCreateBookmark 関数を呼び出します。 Flags パラメーターに EvtSubscribeStartAfterBookmark フラグが含まれている場合は、このパラメーターを設定する必要があります。それ以外の場合は NULL。

[in] Context

サブスクリプション サービスがイベントを配信するたびに指定されたコールバックに渡す呼び出し元定義のコンテキスト値。

[in] Callback

サブスクリプション イベントを受信 するEVT_SUBSCRIBE_CALLBACK コールバック関数へのポインター。 SignalEvent パラメーターが NULL でない場合、このパラメーターは NULL である必要があります。

[in] Flags

イベントのサブスクライブを開始するタイミングを指定する 1 つ以上のフラグ。 たとえば、EvtSubscribeStartAtOldestRecord を指定した場合、サービスはクエリ条件に一致するすべての現在および将来のイベントを取得します。ただし、EvtSubscribeToFutureEvents を指定すると、クエリ条件に一致する将来のイベントのみが返されます。 使用可能な値については、 EVT_SUBSCRIBE_FLAGS 列挙を参照してください。

戻り値

成功した場合のサブスクリプションへのハンドル。それ以外の場合は NULL。 関数が NULL を返す場合は、 GetLastError 関数を呼び出してエラー コードを取得します。 完了したら、サブスクリプション ハンドルを使用して EvtClose 関数を呼び出す必要があります。

解説

サブスクリプションを取り消すには、返されたサブスクリプション ハンドルを EvtClose 関数に渡します。

ポーリング モデルとプッシュ モデルの 2 つのサブスクリプション モデルがあります。 プッシュ モデルでは、サブスクリプション コールバックを実装し、 Callback パラメーターを実装に設定します。 サービスは、クエリ条件に一致するイベント (またはエラーが発生した場合) ごとにコールバックを呼び出します。

ポーリング モデルでは、サービスが通知するイベント オブジェクトを作成します。 通知されたら、サブスクリプション ハンドルを使用して EvtNext 関数を呼び出して、イベントを列挙します。 列挙する各イベントで EvtClose 関数を呼び出す必要があります。 次に、オブジェクトをリセットし、サービスが再度通知されるまで待ちます。 このプロセスは、サブスクリプションを取り消すまで繰り返されます。

例

この関数の使用方法を示す例については、「 イベントのサブスクライブ」を参照してください。

要件

関連項目

EVT_SUBSCRIBE_CALLBACK

EvtQuery