ProcessTrace-Funktion (evntrace.h)

Die ProcessTrace-Funktion liefert Ereignisse aus einer oder mehreren ETW-Ablaufverfolgungsverarbeitungssitzungen an den Verbraucher.

Syntax

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PROCESSTRACE_HANDLE *HandleArray,
  [in] ULONG               HandleCount,
  [in] LPFILETIME          StartTime,
  [in] LPFILETIME          EndTime
);

Die 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 enthalten 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

Zeigen Sie 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

Zeigen Sie auf eine optionale FILETIME-Struktur , die den Endzeitzeitraum 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 Echtzeitereignisübermittlung 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 Ziehpunkte 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 in der BufferCallback-Funktion FALSE zurückgegeben wird.

• ERROR_WMI_INSTANCE_NOT_FOUND

  Die Ablaufverfolgungssammlungssitzung, aus der Sie Ereignisse in Echtzeit nutzen möchten, wird nicht ausgeführt oder der Echtzeitablaufverfolgungsmodus ist aktiviert.

Bemerkungen

Ablaufverfolgungskunden 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 ProcessTrace OpenTrace zum Öffnen von Handles zur Ablaufverfolgung von Verarbeitungssitzungen.

Die ProcessTrace-Funktion liefert die Ereignisse aus den Sitzungen, indem die Rückruffunktionen BufferCallback, EventCallback und EventRecordCallback aufgerufen werden.

Die ProcessTrace-Funktion versucht, Ereignisse basierend auf dem Zeitstempel des Ereignisses in der Reihenfolge zu liefern (d. h. es versucht, Ereignisse am ältesten zu übermitteln). In bestimmten Fällen kann ProcessTrace Ereignisse außerhalb der Reihenfolge liefern.

• Wenn die für die Ereigniszeitstempel verwendete Uhr während der Ablaufverfolgungsauflistung rückwärts angepasst wird, ist die Lieferreihenfolge der Ereignisse unvorhersehbar. Um dieses Problem zu vermeiden, verwenden Sie die QPC-Uhr anstelle der Systemzeituhr beim Sammeln der Ablaufverfolgung.
• Wenn mehrere Ereignisse mit dem gleichen Zeitstempel auf verschiedenen CPUs gesammelt werden, ist die Lieferreihenfolge der Ereignisse unvorhersehbar.
• Wenn ein Ereignis einen ungültigen Zeitstempel hat (z. B. aufgrund einer Dateibeschädigung), kann die Zustellungsreihenfolge dieses Ereignisses und andere Ereignisse in der Ablaufverfolgung unvorhersehbar sein.

Die ProcessTrace-Funktion blockiert den Thread, bis er alle Ereignisse liefert, gibt die BufferCallback-FunktionFALSCH zurück, oder Sie rufen CloseTrace auf. Wenn der Verbraucher Ereignisse in Echtzeit in Anspruch nimmt, gibt die ProcessTrace-Funktion zurück, nachdem der Controller die Ablaufverfolgungssitzung beendet hat. (Beachten Sie, dass es eine Verzögerung von mehreren Sekunden vor dem Zurückgeben der Funktion geben kann.)

Windows Server 2003:Sie können CloseTrace erst aufrufen, nachdem ProcessTrace zurückgegeben wurde .

Examples

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

Anforderungen

Siehe auch

BufferCallback

EventCallback

EventRecordCallback

OpenTrace