EvtSubscribe-Funktion (winevt.h)
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 |