ProcessTrace function (evntrace.h)
The ProcessTrace function delivers events from one or more ETW trace processing sessions to the consumer.
Syntax
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
[in] PROCESSTRACE_HANDLE *HandleArray,
[in] ULONG HandleCount,
[in] LPFILETIME StartTime,
[in] LPFILETIME EndTime
);
Parameters
[in] HandleArray
Pointer to an array of trace processing session handles obtained from earlier calls to the OpenTrace function.
The array can contain up to 64 handles to file processing sessions or it can contain one handle to a real-time processing session. The array cannot contain both file processing session handles and real-time processing session handles.
[in] HandleCount
Number of elements in HandleArray.
[in] StartTime
Pointer to an optional FILETIME structure that specifies the beginning time period for which you want to receive events. The function does not deliver events with timestamps prior to StartTime.
[in] EndTime
Pointer to an optional FILETIME structure that specifies the ending time period for which you want to receive events. The function does not deliver events with timestamps after EndTime.
Windows Server 2003: This value is ignored for real-time event delivery.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the system error codes. The following are some common errors and their causes.
ERROR_BAD_LENGTH
HandleCount is not valid or the number of handles is greater than 64.
ERROR_INVALID_HANDLE
An element of HandleArray is not a valid event tracing session handle.
ERROR_INVALID_TIME
EndTime is less than StartTime.
ERROR_INVALID_PARAMETER
HandleArray is NULL, contains both file processing sessions and real-time processing sessions, or contains more than one real-time processing session.
ERROR_NOACCESS
An exception occurred in one of the callback functions that receives the events.
ERROR_CANCELLED
Indicates the consumer canceled processing by returning FALSE in their BufferCallback function.
ERROR_WMI_INSTANCE_NOT_FOUND
The trace collection session from which you are trying to consume events in real time is not running or does not have the real-time trace mode enabled.
Remarks
Trace consumers call this function to process the events from one or more trace processing sessions. This function blocks until processing ends.
Before calling ProcessTrace, use OpenTrace to open handles to trace processing sessions.
The ProcessTrace function delivers the events from the sessions by invoking the consumer's BufferCallback, EventCallback, and EventRecordCallback callback functions.
The ProcessTrace function attempts to deliver events in order based on the event's timestamp (i.e. it tries to deliver events oldest to newest). In certain cases, ProcessTrace might deliver events out of order.
- If the clock used for the event timestamps is adjusted backwards during trace collection, the delivery order of the events is unpredictable. To avoid this issue, use the QPC clock instead of the system time clock when collecting the trace.
- If multiple events are collected with the same timestamp on different CPUs, the delivery order of the events is unpredictable.
- If an event has an invalid timestamp (e.g. due to file corruption), the delivery order of that event and other events in the trace may be unpredictable.
The ProcessTrace function blocks the thread until it delivers all events, the BufferCallback function returns FALSE, or you call CloseTrace. In addition, if the consumer is consuming events in real time, the ProcessTrace function returns after the controller stops the trace session. (Note that there may be a delay of several seconds before the function returns.)
Windows Server 2003: You can call CloseTrace only after ProcessTrace returns.
Examples
For an example that uses ProcessTrace, see Using TdhFormatProperty to Consume Event Data.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps | UWP apps] |
| Minimum supported server | Windows 2000 Server [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | evntrace.h |
| Library | Sechost.lib on Windows 8.1 and Windows Server 2012 R2; Advapi32.lib on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista and Windows XP |
| DLL | Sechost.dll on Windows 8.1 and Windows Server 2012 R2; Advapi32.dll on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista and Windows XP |