ProcessTrace-Funktion (evntrace.h)

Artikel
08/23/2023

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

Weitere Informationen