StopTraceA-Funktion (evntrace.h)

  • Artikel

Die StopTrace-Funktion beendet die angegebene Ereignisablaufverfolgungssitzung.

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

Syntax

ULONG WMIAPI StopTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameter

TraceHandle

Handle für die zu beendende Ereignisablaufverfolgungssitzung oder 0. Sie müssen ein TraceHandle ungleich Null angeben, wenn InstanceNameNULL ist. Dieser Parameter wird nur verwendet, wenn InstanceNameNULL ist. Das Handle wird vom StartTrace zurückgegeben.

InstanceName

Name der zu beendenden Ereignisablaufverfolgungssitzung oder NULL. Sie müssen InstanceName angeben, wenn TraceHandle den Wert 0 hat.

Um die NT Kernel Logger-Sitzung anzugeben, legen Sie InstanceName auf KERNEL_LOGGER_NAME fest.

Properties

Zeiger auf eine EVENT_TRACE_PROPERTIES Struktur, die die endgültigen Eigenschaften und Statistiken für die Sitzung empfängt.

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 die maximale Länge des Sitzungsnamens (1024 Zeichen) und die maximale Länge des Protokolldateinamens (1024 Zeichen) verwenden, um die Puffergröße und die Offsets zu berechnen, wenn sie nicht bekannt sind.

Ab Windows 10 Version 1703: Für eine bessere Leistung in prozessübergreifenden Szenarien können Sie die Filterung jetzt für systemweite private Protokollierungen an StopTrace übergeben. Sie müssen die neue EVENT_TRACE_PROPERTIES_V2-Struktur übergeben, um Filterinformationen einzuschließen. Weitere Informationen finden Sie unter Konfigurieren und Starten einer privaten Protokollierungssitzung .

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_BAD_LENGTH

    Es trifft eine der folgenden Bedingungen zu:

    • Der Wnode.BufferSize-Member 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) zu speichern.

  • ERROR_INVALID_PARAMETER

    Es trifft eine der folgenden Bedingungen zu:

    • Eigenschaften sind NULL.
    • InstanceName und TraceHandle sind beide NULL.
    • InstanceName ist NULL , und TraceHandle ist kein gültiges Handle.

  • 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_STOP festgelegt ist.

Wenn LogFileModeEVENT_TRACE_FILE_MODE_PREALLOCATE enthält, erweitert StartTrace die Protokolldatei auf MaximumFileSize-Bytes . Die Datei belegt während der Protokollierung den gesamten Speicherplatz, sowohl für zirkuläre als auch für sequenzielle Protokolle. Wenn Sie die Protokollierung beenden, wird die Protokolldatei auf die erforderliche Größe reduziert.

Rufen Sie StopTrace nicht aus DllMain auf (kann zu einem Deadlock führen).

Hinweis

Der evntrace.h-Header definiert StopTrace 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 Code, der nicht Codierungsneutral ist, 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 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Sechost.lib auf Windows 8.1 und Windows Server 2012 R2; Advapi32.lib unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP
DLL Sechost.dll auf Windows 8.1 und Windows Server 2012 R2; Advapi32.dll unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista und Windows XP

Weitere Informationen

ControlTrace

StartTrace