FlushTraceA-Funktion (evntrace.h)

  • Artikel

Die FlushTrace-Funktion bewirkt, dass eine Ereignisablaufverfolgungssitzung sofort gepufferte Ereignisse für die angegebene Sitzung liefert. Standardmäßig liefert eine Ereignisablaufverfolgungssitzung Ereignisse, wenn der Puffer voll ist, der FlushTimer der Sitzung abläuft oder die Sitzung geschlossen wird.

Diese Funktion ist veraltet. Die ControlTrace-Funktion ersetzt diese Funktion.

Syntax

ULONG WMIAPI FlushTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parameter

[in] TraceHandle

Behandeln Sie die Ereignisablaufverfolgungssitzung, die geleert werden soll, oder 0. Sie müssen eine TraceHandle-Instanz ohne Null angeben, wenn InstanceNameNULL ist. Dieser Parameter wird nur verwendet, wenn InstanceNameNULL ist. Das Handle wird vom StartTrace zurückgegeben.

[in] InstanceName

Name der zu leerenden Ereignisablaufverfolgungssitzung oder NULL. Sie müssen InstanceName angeben, wenn TraceHandle 0 ist.

Um die NT-Kernelprotokollierungssitzung anzugeben, legen Sie InstanceName auf KERNEL_LOGGER_NAME fest.

[in, out] Properties

Zeiger auf eine initialisierte EVENT_TRACE_PROPERTIES-Struktur .

Wenn Sie eine neu initialisierte Struktur verwenden, müssen Sie nur die Elemente Wnode.BufferSize, Wnode.Guid, LoggerNameOffset und LogFileNameOffset der Struktur festlegen. Sie können den maximalen Sitzungsnamen (1024 Zeichen) und die maximale Protokolldateinamelänge (1024 Zeichen) verwenden, um die Puffergröße und die Offsets zu berechnen, falls nicht bekannt.

Bei der Ausgabe empfängt die Struktur die Eigenschafteneinstellungen und Sitzungsstatistiken der Ereignisablaufverfolgungssitzung, die den Zustand der Sitzung nach dem Leeren widerspiegeln.

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. Die folgende Tabelle enthält einige häufige Fehler und deren Ursachen.

  • ERROR_INVALID_PARAMETER

    Es trifft eine der folgenden Bedingungen zu:

    • Eigenschaften sind NULL.
    • InstanceName und TraceHandlesind null.
    • InstanceName ist NULL und TraceHandle ist kein gültiges Handle.

  • ERROR_BAD_LENGTH

    Es trifft eine der folgenden Bedingungen zu:

    • Das Wnode.BufferSize-Element von Properties gibt eine falsche Größe an.
    • Eigenschaften verfügen nicht über genügend Speicherplatz, um eine Kopie des Sitzungsnamens und des Protokolldateinamens (falls verwendet) aufzunehmen.

  • ERROR_ACCESS_DENIED

    Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe Leistungsprotokollbenutzer und Dienste, die als LocalSystem, LocalService und NetworkService ausgeführt werden, können Ereignisablaufverfolgungssitzungen steuern. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, Ablaufverfolgungssitzungen zu steuern, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu.

    Windows XP und Windows 2000: Jeder kann eine Ablaufverfolgungssitzung steuern.

Hinweise

Ereignisablaufverfolgungscontroller rufen diese Funktion auf.

Diese Funktion ist veraltet. Verwenden Sie stattdessen ControlTrace , wobei ControlCode auf EVENT_TRACE_CONTROL_FLUSH festgelegt ist.

Diese Funktion kann mit einer In-Memory-Sitzung (einer Sitzung, die mit dem flag EVENT_TRACE_BUFFERING_MODE gestartet wurde) verwendet werden, um die Daten aus der Ablaufverfolgung in eine Datei zu schreiben.

Sie müssen normalerweise keine dateibasierten Sitzungen oder Echtzeitsitzungen leeren, da ETW einen Puffer automatisch leert, wenn er voll ist (d. h. wenn er keinen Platz für das nächste Ereignis hat), wenn der FlushTimer der Ablaufverfolgungssitzung abläuft oder wenn die Ablaufverfolgungssitzung geschlossen wird.

Rufen Sie FlushTrace nicht über DllMain auf (kann deadlock verursachen).

Hinweis

Der evntrace.h-Header definiert FlushTrace als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

ControlTrace