EvtSubscribe-Funktion (winevt.h)
Erstellt ein Abonnement, das aktuelle und zukünftige Ereignisse aus einer Kanal- oder Protokolldatei empfängt, die den angegebenen Abfragekriterien entspricht.
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
Eine Remotesitzung behandelt, die die EvtOpenSession-Funktion zurückgibt. Legen Sie auf NULL fest, um Ereignisse auf dem lokalen Computer zu abonnieren.
[in] SignalEvent
Der Handle zu einem Ereignisobjekt, das der Dienst signalisiert, wenn neue Ereignisse verfügbar sind, die Ihren Abfragekriterien entsprechen. Dieser Parameter muss NULL sein, wenn der Rückrufparameter nicht NULL ist.
[in] ChannelPath
Der Name des Admin- oder Betriebskanals, 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 Abfrageparameter eine XPath-Abfrage enthält; der Pfad wird ignoriert, wenn der Abfrageparameter eine strukturierte XML-Abfrage enthält.
[in] Query
Eine Abfrage, die die Typen von Ereignissen angibt, die der Abonnementdienst zurückgeben soll. Sie können eine XPath 1.0-Abfrage oder 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 zu einer Textmarke, die den Ausgangspunkt für das Abonnement identifiziert. Um ein Textmarke-Handle abzurufen, rufen Sie die Funktion EvtCreateBookmark auf. Sie müssen diesen Parameter festlegen, wenn der Flags-Parameter das EvtSubscribeStartAfterBookmark-Flag enthält; andernfalls NULL.
[in] Context
Ein anruferdefinierter Kontextwert, den der Abonnementdienst bei jedem Bereitstellen eines Ereignisses an den angegebenen Rückruf übergeben wird.
[in] Callback
Zeigen Sie 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
Eine oder mehrere Flags, die angeben, wann Sie mit dem Abonnieren von Ereignissen beginnen. Wenn Sie z. B. 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-Aufzählung .
Rückgabewert
Ein Handle an das Abonnement, wenn es erfolgreich ist; andernfalls NULL. Wenn die Funktion NULL zurückgibt, rufen Sie die GetLastError-Funktion auf, um den Fehlercode abzurufen. Sie müssen die Funktion EvtClose mit dem Abonnementhandpunkt aufrufen, wenn sie fertig ist.
Hinweise
Um das Abonnement zu kündigen, übergeben Sie den zurückgegebenen Abonnementhandpunkt an die Funktion EvtClose .
Es gibt zwei Abonnementmodelle: das Umfragemodell und das Pushmodell. Im Pushmodell implementieren Sie einen Abonnementrückruf und legen den Rückrufparameter 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 Umfragemodell erstellen Sie ein Ereignisobjekt, das den Dienst signalisiert. Wenn sie signalisiert werden, rufen Sie die EvtNext-Funktion mithilfe des Abonnementhandpunkts auf, um die Ereignisse aufzählen zu können. Sie müssen die EvtClose-Funktion für jedes Ereignis aufrufen, das Sie aufzählen. Anschließend setzen Sie das Objekt zurück, und warten Sie erneut, bis der Dienst signalisiert. Dieser Prozess wiederholt, bis Sie das Abonnement kündigen.
Beispiele
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 |