OpenTraceA-Funktion (evntrace.h)
Die OpenTrace-Funktion öffnet ein ETW-Ablaufverfolgungsverarbeitungshandle zum Verbrauch von Ereignissen aus einer ETW-Echtzeitablaufverfolgungssitzung oder einer ETW-Protokolldatei.
Syntax
PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
[in, out] PEVENT_TRACE_LOGFILEA 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 |