OpenTraceW-Funktion (evntrace.h)

Die OpenTrace-Funktion öffnet ein ETW-Ablaufverfolgungsverarbeitungshandle zum Verbrauch von Ereignissen aus einer ETW-Echtzeitablaufverfolgungssitzung oder einer ETW-Protokolldatei.

Syntax

ETW_APP_DECLSPEC_DEPRECATED TRACEHANDLE WMIAPI OpenTraceW(
  [in, out] PEVENT_TRACE_LOGFILEW Logfile
);

Parameter

[in, out] Logfile

Zeiger auf eine EVENT_TRACE_LOGFILE-Struktur . Die -Struktur gibt die Quelle an, von der Ereignisse (aus einer ETW-Protokolldatei oder einer ETW-Sitzung in Echtzeit) genutzt werden sollen, und gibt die Rückrufe an, die der Consumer zum Empfangen der Ereignisse verwenden möchte. Bei Erfolg aktualisiert OpenTrace die Struktur mit Informationen aus der geöffneten Datei oder Sitzung.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie das Ablaufverfolgungsverarbeitungshandle zurück. Das Handle sollte mit CloseTrace geschlossen werden.

Wenn die Funktion fehlschlägt, gibt sie INVALID_PROCESSTRACE_HANDLE zurück. (INVALID_PROCESSTRACE_HANDLE entspricht (UINT64)UINTPTR_MAX.)

Hinweis

Vor Windows Vista wurde UINT64_MAX OpenTrace im Falle eines Fehlers zurückgegeben. Wenn Ihr Code sowohl ältere Betriebssysteme (Windows XP oder Windows Server 2003) als auch neuere Versionen von Windows (Windows Vista und höher) unterstützt, müssen Sie das Betriebssystem ermitteln, unter dem Sie ausgeführt werden, und den Rückgabewert mit dem entsprechenden Wert vergleichen.

Betriebssystem	Prozesstyp	Wert, der einen Fehler angibt
Vor Windows Vista	32- oder 64-Bit	0XFFFFFFFFFFFFFFFF = UINT64_MAX
Windows Vista oder höher	32 Bit	0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX
Windows Vista oder höher	64 Bit	0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX

Wenn die Funktion fehlschlägt, können Sie die GetLastError-Funktion verwenden, um erweiterte Fehlerinformationen abzurufen. Im Folgenden sind einige häufige Fehler und deren Ursachen aufgeführt.

• ERROR_INVALID_PARAMETER

  Der Logfile-Parameter ist NULL.

• ERROR_BAD_PATHNAME

  Wenn Sie das LoggerName-Element von EVENT_TRACE_LOGFILE nicht angegeben haben, müssen Sie einen gültigen Protokolldateinamen angeben.

• 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 Ereignisse in Echtzeit nutzen. Um einem eingeschränkten Benutzer die Möglichkeit zu geben, Ereignisse in Echtzeit zu nutzen, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu.

  Windows XP und Windows 2000: Jeder kann Echtzeitereignisse nutzen.

Hinweise

Ablaufverfolgungsverbraucher rufen diese Funktion auf, um eine Ablaufverfolgungsverarbeitungssitzung zu öffnen.

Rufen Sie nach dem Aufrufen von OpenTrace die ProcessTrace-Funktion auf, um die Ereignisse zu verarbeiten. Rufen Sie nach Abschluss der Verarbeitungsereignisse die CloseTrace-Funktion auf, um das Ablaufverfolgungsverarbeitungshandle zu schließen.

Beispiele

Ein Beispiel, das OpenTrace verwendet, finden Sie unter Using TdhFormatProperty to Consume Event Data.

Hinweis

Der evntrace.h-Header definiert OpenTrace 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 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 unter 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

EVENT_TRACE_LOGFILE

CloseTrace

ProcessTrace