ProcessTrace-Funktion (evntrace.h)
Die ProcessTrace-Funktion übermittelt Ereignisse aus einer oder mehreren ETW-Ablaufverfolgungsverarbeitungssitzungen an den Consumer.
Syntax
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
[in] PTRACEHANDLE HandleArray,
[in] ULONG HandleCount,
[in] LPFILETIME StartTime,
[in] LPFILETIME EndTime
);
Parameter
[in] HandleArray
Zeiger auf ein Array von Ablaufverfolgungsverarbeitungssitzungshandles, die von früheren Aufrufen der OpenTrace-Funktion abgerufen wurden.
Das Array kann bis zu 64 Handles für Dateiverarbeitungssitzungen oder ein Handle für eine Echtzeitverarbeitungssitzung enthalten. Das Array kann nicht sowohl Dateiverarbeitungssitzungshandles als auch Echtzeitverarbeitungssitzungshandles enthalten.
[in] HandleCount
Anzahl der Elemente in HandleArray.
[in] StartTime
Zeiger auf eine optionale FILETIME-Struktur , die den Anfangszeitraum angibt, für den Sie Ereignisse empfangen möchten. Die Funktion liefert keine Ereignisse mit Zeitstempeln vor StartTime.
[in] EndTime
Zeiger auf eine optionale FILETIME-Struktur , die den Endzeitraum angibt, für den Sie Ereignisse empfangen möchten. Die Funktion liefert keine Ereignisse mit Zeitstempeln nach EndTime.
Windows Server 2003: Dieser Wert wird für die Ereignisübermittlung in Echtzeit ignoriert.
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
HandleCount ist ungültig, oder die Anzahl der Handles ist größer als 64.
ERROR_INVALID_HANDLE
Ein Element von HandleArray ist kein gültiges Ereignisablaufverfolgungssitzungshandle.
ERROR_INVALID_TIME
EndTime ist kleiner als StartTime.
ERROR_INVALID_PARAMETER
HandleArray ist NULL, enthält sowohl Dateiverarbeitungssitzungen als auch Echtzeitverarbeitungssitzungen oder mehr als eine Echtzeitverarbeitungssitzung.
ERROR_NOACCESS
Eine Ausnahme ist in einer der Rückruffunktionen aufgetreten, die die Ereignisse empfängt.
ERROR_CANCELLED
Gibt an, dass der Consumer die Verarbeitung abgebrochen hat, indem er in seiner BufferCallback-Funktion FALSE zurückgibt.
ERROR_WMI_INSTANCE_NOT_FOUND
Die Ablaufverfolgungssammlungssitzung, aus der Sie Ereignisse in Echtzeit nutzen möchten, wird nicht ausgeführt oder ist nicht im Echtzeit-Ablaufverfolgungsmodus aktiviert.
Hinweise
Ablaufverfolgungsconsumer rufen diese Funktion auf, um die Ereignisse aus einer oder mehreren Ablaufverfolgungsverarbeitungssitzungen zu verarbeiten. Diese Funktion blockiert, bis die Verarbeitung endet.
Verwenden Sie vor dem Aufrufen von ProcessTraceOpenTrace , um Handles für Ablaufverfolgungsverarbeitungssitzungen zu öffnen.
Die ProcessTrace-Funktion übermittelt die Ereignisse aus den Sitzungen, indem die Rückruffunktionen BufferCallback, EventCallback und EventRecordCallback des Consumers aufgerufen werden.
Die ProcessTrace-Funktion versucht, Ereignisse basierend auf dem Zeitstempel des Ereignisses in der Reihenfolge zu übermitteln (d. h. es wird versucht, Ereignisse zu übermitteln, die am ältesten an das neueste Ereignis gesendet werden). In bestimmten Fällen kann ProcessTrace Ereignisse in einer anderen Reihenfolge übermitteln.
- Wenn die für die Ereigniszeitstempel verwendete Uhr während der Ablaufverfolgungssammlung rückwärts angepasst wird, ist die Übermittlungsreihenfolge der Ereignisse unvorhersehbar. Um dieses Problem zu vermeiden, verwenden Sie beim Erfassen der Ablaufverfolgung anstelle der Systemzeituhr die QPC-Uhr .
- Wenn mehrere Ereignisse mit demselben Zeitstempel auf verschiedenen CPUs gesammelt werden, ist die Übermittlungsreihenfolge der Ereignisse unvorhersehbar.
- Wenn ein Ereignis einen ungültigen Zeitstempel aufweist (z. B. aufgrund einer Dateibeschädigung), kann die Übermittlungsreihenfolge dieses Ereignisses und anderer Ereignisse in der Ablaufverfolgung unvorhersehbar sein.
Die ProcessTrace-Funktion blockiert den Thread, bis alle Ereignisse übermittelt werden, die BufferCallback-FunktionFALSE zurückgibt oder Sie CloseTrace aufrufen. Wenn der Consumer Ereignisse in Echtzeit verarbeitet, wird die ProcessTrace-Funktion zurückgegeben, nachdem der Controller die Ablaufverfolgungssitzung beendet hat. (Beachten Sie, dass es eine Verzögerung von mehreren Sekunden geben kann, bevor die Funktion zurückgegeben wird.)
Windows Server 2003: Sie können CloseTrace nur aufrufen, nachdem ProcessTrace zurückgegeben wurde.
Beispiele
Ein Beispiel, das ProcessTrace verwendet, finden Sie unter Verwenden von TdhFormatProperty zum Nutzen von Ereignisdaten.
Anforderungen
| 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 unter 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 |