EvtSubscribe-Funktion (winevt.h)

  • Artikel

Erstellt ein Abonnement, das aktuelle und zukünftige Ereignisse von einem Kanal oder einer Protokolldatei empfängt, die den angegebenen Abfragekriterien entsprechen.

Syntax

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
);

Parameter

[in] Session

Ein Remotesitzungshandle, das von der EvtOpenSession-Funktion zurückgegeben wird. Legen Sie auf NULL fest, um Ereignisse auf dem lokalen Computer zu abonnieren.

[in] SignalEvent

Das Handle für ein Ereignisobjekt, das der Dienst signalisiert, wenn neue Ereignisse verfügbar sind, die Ihren Abfragekriterien entsprechen. Dieser Parameter muss NULL sein, wenn der Callback-Parameter nicht NULL ist.

[in] ChannelPath

Der Name des Admin- oder Operational-Kanals, der die Ereignisse enthält, die Sie abonnieren möchten (Sie können keine Analyse- oder Debugkanäle abonnieren). Der Pfad ist erforderlich, wenn der Query-Parameter eine XPath-Abfrage enthält. der Pfad wird ignoriert, wenn der Query-Parameter eine strukturierte XML-Abfrage enthält.

[in] Query

Eine Abfrage, die die Ereignistypen angibt, die vom Abonnementdienst zurückgegeben werden sollen. Sie können eine XPath 1.0-Abfrage oder eine strukturierte XML-Abfrage angeben. Wenn Ihr XPath mehr als 20 Ausdrücke enthält, verwenden Sie eine strukturierte XML-Abfrage. Um alle Ereignisse zu empfangen, legen Sie diesen Parameter auf NULL oder "*" fest.

[in] Bookmark

Ein Handle für ein Lesezeichen, das den Ausgangspunkt für das Abonnement identifiziert. Um ein Lesezeichenhandle zu erhalten, rufen Sie die EvtCreateBookmark-Funktion auf . Sie müssen diesen Parameter festlegen, wenn der Flags-Parameter das Flag EvtSubscribeStartAfterBookmark enthält. andernfalls NULL.

[in] Context

Ein vom Aufrufer definierter Kontextwert, den der Abonnementdienst jedes Mal an den angegebenen Rückruf übergibt, wenn er ein Ereignis übermittelt.

[in] Callback

Zeiger auf Ihre EVT_SUBSCRIBE_CALLBACK Rückruffunktion, die die Abonnementereignisse empfängt. Dieser Parameter muss NULL sein, wenn der SignalEvent-Parameter nicht NULL ist.

[in] Flags

Mindestens ein Flag, das angibt, wann mit dem Abonnieren von Ereignissen begonnen werden soll. Wenn Sie beispielsweise EvtSubscribeStartAtOldestRecord angeben, ruft der Dienst alle aktuellen und zukünftigen Ereignisse ab, die Ihren Abfragekriterien entsprechen. Wenn Sie jedoch EvtSubscribeToFutureEvents angeben, gibt der Dienst nur zukünftige Ereignisse zurück, die Ihren Abfragekriterien entsprechen. Mögliche Werte finden Sie in der EVT_SUBSCRIBE_FLAGS-Enumeration .

Rückgabewert

Ein Handle für das Abonnement bei erfolgreicher Ausführung; andernfalls NULL. Wenn die Funktion NULL zurückgibt, rufen Sie die GetLastError-Funktion auf, um den Fehlercode abzurufen. Wenn Sie fertig sind, müssen Sie die EvtClose-Funktion mit dem Abonnementhandle aufrufen.

Hinweise

Um das Abonnement zu kündigen, übergeben Sie das zurückgegebene Abonnementhandle an die EvtClose-Funktion .

Es gibt zwei Abonnementmodelle: das Umfragemodell und das Pushmodell. Im Pushmodell implementieren Sie einen Abonnementrückruf und legen den Callback-Parameter auf Ihre Implementierung fest. Der Dienst ruft Ihren Rückruf für jedes Ereignis auf, das Ihren Abfragekriterien entspricht (oder wenn ein Fehler auftritt).

Im Abfragemodell erstellen Sie ein Ereignisobjekt, das vom Dienst signalisiert wird. Wenn signalisiert wird, rufen Sie die EvtNext-Funktion mithilfe des Abonnementhandles auf, um die Ereignisse aufzulisten. Sie müssen die EvtClose-Funktion für jedes Ereignis aufrufen, das Sie auflisten. Anschließend setzen Sie das Objekt zurück und warten, bis der Dienst erneut signalisiert. Dieser Vorgang wird wiederholt, bis Sie das Abonnement kündigen.

Beispiele

Ein Beispiel für die Verwendung dieser Funktion finden Sie unter Abonnieren von Ereignissen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winevt.h
Bibliothek Wevtapi.lib
DLL Wevtapi.dll

Weitere Informationen

EVT_SUBSCRIBE_CALLBACK

EvtQuery