EventWrite-Funktion (evntprov.h)
Schreibt ein ETW-Ereignis, das die Aktivitäts-ID des aktuellen Threads verwendet.
Syntax
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parameter
[in] RegHandle
Registrierungshandle des Anbieters. Das Handle stammt aus EventRegister. Das generierte Ereignis verwendet die dem Handle zugeordnete ProviderId.
[in] EventDescriptor
EVENT_DESCRIPTOR mit Ereignisinformationen (Metadaten), einschließlich ID, Version, Ebene, Schlüsselwort, Kanal, Opcode und Task.
Wichtig
ProviderId, Level und Keyword sind die wichtigsten Mittel zum Filtern von Ereignissen. Andere Filterarten sind möglich, haben aber einen viel höheren Aufwand. Weisen Sie jedem Ereignis immer eine nonzero-Ebene zu und Schlüsselwort (keyword).
[in] UserDataCount
Anzahl der EVENT_DATA_DESCRIPTOR Strukturen in UserData. Die maximale Zahl ist 128.
[in, optional] UserData
Ein Array von UserDataCountEVENT_DATA_DESCRIPTOR Strukturen, die die daten beschreiben, die in das Ereignis eingeschlossen werden sollen. UserData kann NULL sein, wenn UserDataCount null ist.
Jede EVENT_DATA_DESCRIPTOR beschreibt einen Speicherblock, der in das Ereignis eingeschlossen werden soll. Die angegebenen Blöcke werden so verkettet, dass keine Auffüllung oder Ausrichtung vorhanden ist, um den Ereignisinhalt zu bilden. Bei Verwendung der manifestbasierten Decodierung muss der Ereignisinhalt mit dem Layout übereinstimmen, das in der Vorlage angegeben ist, die dem Ereignis im Manifest zugeordnet ist.
Rückgabewert
Gibt bei erfolgreicher Ausführung ERROR_SUCCESS oder einen Fehlercode zurück. Mögliche Fehlercodes sind:
- ERROR_INVALID_PARAMETER: Mindestens ein Parameter ist ungültig.
- ERROR_INVALID_HANDLE: Der Registrierungshandle des Anbieters ist ungültig.
- ERROR_ARITHMETIC_OVERFLOW: Die Ereignisgröße ist größer als das zulässige Maximum (64 KB – Header).
- ERROR_MORE_DATA: Die Sitzungspuffergröße ist für das Ereignis zu klein.
- ERROR_NOT_ENOUGH_MEMORY: Tritt auf, wenn gefüllte Puffer versuchen, auf den Datenträger zu leeren, aber Datenträger-IOs nicht schnell genug ausgeführt werden. Dies geschieht, wenn der Datenträger langsam ist und der Ereignisdatenverkehr hoch ist. Schließlich gibt es keine freien (leeren) Puffer mehr, und das Ereignis wird gelöscht.
- STATUS_LOG_FILE_FULL: Die Echtzeitwiedergabedatei ist voll. Ereignisse werden erst in der Sitzung protokolliert, wenn ein Echtzeit-Consumer die Ereignisse aus der Wiedergabedatei nutzt.
Der Fehlercode ist in erster Linie für die Verwendung in Debug- und Diagnoseszenarien vorgesehen. Der meiste Produktionscode sollte weiterhin ausgeführt werden und weiterhin Ereignisse melden, auch wenn ein ETW-Ereignis nicht geschrieben werden konnte. Daher sollten Releasebuilds den Fehlercode normalerweise ignorieren.
Hinweise
Die meisten Ereignisanbieter rufen EventWrite nicht direkt auf. Stattdessen werden die meisten Ereignisanbieter mithilfe eines ETW-Frameworks implementiert, das die Aufrufe von EventRegister, EventWrite und EventUnregister umschließt. Sie können beispielsweise ein Ereignismanifest schreiben und dann den Nachrichtencompiler verwenden, um C/C++-Code für die Ereignisse zu generieren, oder Sie können TraceLogging verwenden, um die Notwendigkeit eines Manifests zu vermeiden.
EventWrite leitet das Ereignis an die entsprechenden Ablaufverfolgungssitzungen basierend auf der ProviderId (ermittelt aus regHandle), Level, Keyword und anderen Ereignismerkmalen weiter. Wenn dieses Ereignis nicht von Ablaufverfolgungssitzungen aufgezeichnet wird, tut diese Funktion nichts und gibt ERROR_SUCCESS zurück.
Um die Leistungseinbußen von Ereignissen zu reduzieren, die nicht von einer Ablaufverfolgungssitzung aufgezeichnet werden, können Sie EventEnabled aufrufen, um zu bestimmen, ob eine Ablaufverfolgungssitzung Ihr Ereignis vor dem Vorbereiten der Daten und aufrufen EventWrite aufzeichnet.
EventWrite legt die Aktivitäts-ID des Ereignisses auf die Aktivitäts-ID des aktuellen Threads fest. EventWrite enthält keine zugehörige Aktivitäts-ID im Ereignis. Verwenden Sie EventWriteTransfer, um eine andere Aktivitäts-ID anzugeben oder eine zugehörige Aktivitäts-ID hinzuzufügen.
EventWrite entspricht EventWriteEx mit 0 für Filter, 0 für Flags, NULL für ActivityId und NULL für RelatedActivityId.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | evntprov.h |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |