TraceEvent-Funktion (evntrace.h)
Ein RegisterTraceGuids-basierter ("Classic")-Ereignisanbieter verwendet die TraceEvent-Funktion , um ein strukturiertes Ereignis an eine Ereignisablaufverfolgungssitzung zu senden.
Syntax
ULONG WMIAPI TraceEvent(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_TRACE_HEADER EventTrace
);
Parameter
[in] TraceHandle
Behandeln Sie die Ereignisablaufverfolgungssitzung, die das Ereignis aufzeichnet. Der Anbieter ruft das Handle ab, wenn er die GetTraceLoggerHandle-Funktion in seiner ControlCallback-Implementierung aufruft.
[in] EventTrace
Zeiger auf eine EVENT_TRACE_HEADER-Struktur . Ereignisspezifische Daten werden optional an die -Struktur angefügt. Das größte Ereignis, das Sie protokollieren können, ist etwas kleiner als 64.000. Sie müssen Werte für die folgenden Member der EVENT_TRACE_HEADER-Struktur angeben.
- Größe
- Guid oder GuidPtr
- Flags
Abhängig von der Komplexität der Informationen, die Ihr Anbieter bereitstellt, sollten Sie auch die Angabe von Werten für die folgenden Member in Betracht ziehen.
- Class.Type
- Class.Level
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes. Im Folgenden finden Sie einige häufige Fehler und deren Ursachen.
ERROR_INVALID_FLAG_NUMBER
Der Flags-Member der EVENT_TRACE_HEADER-Struktur ist falsch.
ERROR_INVALID_HANDLE
TraceHandle ist ungültig oder gibt das Nt Kernel Logger-Sitzungshandle an.
ERROR_NOT_ENOUGH_MEMORY
Es sind nicht genügend freie Puffer zum Schreiben der Sitzung vorhanden. Dieser Fall kann während hoher Ereignisraten auftreten, weil das Datenträgersubsystem überlastet ist oder nicht genügend Puffer vorhanden sind. Anstatt zu blockieren, bis mehr Puffer verfügbar sind, verwirft TraceEvent das Ereignis.
Sie sollten die Anzahl und Größe der Puffer für die Sitzung erhöhen oder die Anzahl oder Größe der zu schreibenden Ereignisse verringern.
Windows 2000: Nicht unterstützt.
ERROR_OUTOFMEMORY
Das Ereignis wird verworfen, da, obwohl der Pufferpool seine maximale Größe nicht erreicht hat, nicht genügend Arbeitsspeicher verfügbar ist, um einen zusätzlichen Puffer zuzuweisen, und es ist kein Puffer für den Empfang des Ereignisses verfügbar.
ERROR_INVALID_PARAMETER
Es trifft eine der folgenden Bedingungen zu:
- TraceHandle ist NULL.
- EventTrace ist NULL.
- Der Size-Member der EVENT_TRACE_HEADER-Struktur ist falsch.
ERROR_MORE_DATA
Daten aus einem einzelnen Ereignis können sich nicht über mehrere Puffer erstrecken. Ein Ablaufverfolgungsereignis ist auf die Größe des Puffers der Ereignisablaufverfolgungssitzung abzüglich der Größe der EVENT_TRACE_HEADER-Struktur beschränkt.
Hinweise
MOF-basierte ETW-Anbieter rufen diese Funktion auf.
Hinweis
Die meisten Entwickler rufen diese Funktion nicht auf. Diese API unterstützt MOF-basierte ETW, aber MOF-basierte ETW ist zugunsten von manifestbasiertem ETW veraltet. Darüber hinaus verwenden die meisten MOF-basierten Anbieter Wrapperfunktionen, die von MC.exe generiert werden, anstatt etw-APIs direkt aufzurufen.
Bevor der Anbieter diese Funktion aufrufen kann, muss der Anbieter
- Muss die RegisterTraceGuids-Funktion aufrufen, um sich selbst und die Ereignisablaufverfolgungsklasse zu registrieren.
- Muss aktiviert sein. Ein Controller ruft die EnableTrace-Funktion auf, um einen Anbieter zu aktivieren.
Das Ereignis wird entweder in eine Protokolldatei geschrieben, in Echtzeit an Consumer der Ereignisablaufverfolgung gesendet oder beides. Das LogFileMode-Element der EVENT_TRACE_PROPERTIES-Struktur , die an startTrace übergeben wird, definiert, wohin das Ereignis gesendet wird.
Die Ablaufverfolgungsereignisse werden in der Reihenfolge geschrieben, in der sie auftreten.
Verwenden Sie die Funktion TraceEventInstance , um eine Reihe verwandter Ereignisse nachzuverfolgen.
Unter Windows Vista sollten Sie die EventWrite-Funktion verwenden, um Ereignisse zu protokollieren.
Beispiele
Ein Beispiel, das TraceEvent verwendet, finden Sie unter Ablaufverfolgungsereignisse.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | evntrace.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |