EventWriteString-Funktion (evntprov.h)

Artikel
08/23/2023

Schreibt ein ETW-Ereignis, das eine Zeichenfolge als Daten enthält. Diese Funktion sollte nicht verwendet werden.

Syntax

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parameter

[in] RegHandle

Registrierungshandle des Anbieters. Das Handle stammt aus EventRegister. Das generierte Ereignis verwendet die dem Handle zugeordnete ProviderId.

[in] Level

Eine 8-Bit-Zahl, die verwendet wird, um den Schweregrad oder die Wichtigkeit eines Ereignisses zu beschreiben.

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 Ebene ungleich null zu und Schlüsselwort (keyword).

Ausführliche Informationen zur Ereignisebene finden Sie unter EVENT_DESCRIPTOR .

[in] Keyword

Eine 64-Bit-Bitmaske, die verwendet wird, um die Mitgliedschaft eines Ereignisses in einer Reihe von Ereigniskategorien anzugeben.

Wichtig

Weitere Informationen zum ereignisbasierten Schlüsselwort (keyword) finden Sie unter EVENT_DESCRIPTOR.

[in] String

NUL-beendete Zeichenfolge, die als Ereignisdaten geschrieben werden soll.

Rückgabewert

Gibt ERROR_SUCCESS zurück, wenn erfolgreich oder ein Fehlercode vorhanden ist. Mögliche Fehlercodes sind:

ERROR_INVALID_PARAMETER: Mindestens ein Parameter ist ungültig.
ERROR_INVALID_HANDLE: Das 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, Datenträger-IOs jedoch 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 Echtzeitconsumer 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 in der Regel ignorieren.

Hinweise

Diese API ist nicht nützlich und sollte nicht verwendet werden.

Die meisten ETW-Analysetools unterstützen nur Zeichenfolgenereignisse ohne Manifest nicht ordnungsgemäß.
Ohne ein Manifest sind wichtige Informationen zum Ereignis (z. B. Anbietername, Ereignis-ID und Ereignisname) nicht verfügbar, sodass die resultierenden Ereignisse auch dann schwer zu verwenden sind, wenn das Analysetool nur Zeichenfolgenereignisse unterstützt.
Bei einem Manifest verhält sich diese Funktion fast genau wie der Code aus einem manifestbasierten Ereignis mit einem einzelnen Zeichenfolgenfeld. Das manifestbasierte Ereignis wird jedoch besser von Ablaufverfolgungsanalysetools unterstützt. Darüber hinaus ist der von MC.exe für ein Ereignis mit einem einzelnen Zeichenfolgenfeld generierte Code effizienter als die EventWriteString-Funktion .

Anstatt diese API zu verwenden, sollten Sie die folgenden Alternativen in Betracht ziehen:

Verwenden Sie TraceLoggingProvider.h , um Ereignisse zu schreiben, die von ETW-Analysetools gut unterstützt werden, ohne Manifest arbeiten und Metadaten wie Anbietername und Ereignisname einschließen.
Schreiben sie ein Instrumentierungsmanifest. Erstellen Sie ein einfaches Ereignis mit einem einzelnen NUL-beendeten Zeichenfolgenwert. Sie können Ereignisse auch ohne Manifest schreiben und sammeln. Sie benötigen das Manifest nur zum Decodieren der gesammelten Ablaufverfolgung.

EventWriteString schreibt ein Ereignis mit einer Datennutzlast, die aus der angegebenen Zeichenfolge besteht. Diese API entspricht nahezu dem folgenden Code:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

Das resultierende Ereignis entspricht jedem anderen Ereignis, das von EventWrite generiert wird, außer dass für das resultierende Ereignis das flag EVENT_HEADER_FLAG_STRING_ONLY festgelegt ist (Informationen zu Ereignisflags finden Sie unter EVENT_HEADER ).

Beachten Sie, dass das Ereignis geschrieben wird, wobei ID, Version, Opcode, Task und Channel auf 0 festgelegt sind.

Beachten Sie, dass das Ereignis die Aktivitäts-ID des aktuellen Threads verwendet.

ETW-Analysetools, die das EVENT_HEADER_FLAG_STRING_ONLY-Flags kennen, können den Zeichenfolgenwert auch dann extrahieren, wenn der Decoder keine anderen Decodierungsinformationen für den Ereignisanbieter finden kann. Ohne ein Manifest können die Tools den Anbieternamen des Ereignisses jedoch nicht ermitteln.

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

Weitere Informationen

EventWrite

TraceLoggingProvider.h