ProcessTrace function
The ProcessTrace function delivers events from one or more event tracing sessions to the consumer.
Syntax
ULONG ProcessTrace( _In_ PTRACEHANDLE HandleArray, _In_ ULONG HandleCount, _In_ LPFILETIME StartTime, _In_ LPFILETIME EndTime );
Parameters
- HandleArray [in]
-
Pointer to an array of trace handles obtained from earlier calls to the OpenTrace function. The number of handles that you can specify is limited to 64.
The array can contain the handles to multiple log files, but only one real-time trace session.
- HandleCount [in]
-
Number of elements in HandleArray.
- StartTime [in]
-
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 recorded prior to StartTime.
- EndTime [in]
-
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 recorded 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 table includes some common errors and their causes.
| Return code | Description |
|---|---|
|
HandleCount is not valid or the number of handles is greater than 64. |
|
An element of HandleArray is not a valid event tracing session handle. |
|
EndTime is less than StartTime. |
|
HandleArray is NULL. |
|
An exception occurred in one of the callback functions that receives the events. |
|
Indicates the consumer canceled processing by returning FALSE in their BufferCallback function. |
|
The 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. |
|
The HandleArray parameter contains the handle to more than one real-time session. |
Remarks
Consumers call this function.
You must call the OpenTrace function prior to calling ProcessTrace.
The ProcessTrace function delivers the events to the consumer's BufferCallback, EventCallback, and EventClassCallback callback functions.
The ProcessTrace function sorts the events chronologically and delivers all events generated between StartTime and EndTime. Note that events can appear out of order if the session specifies system time as the clock (low resolution) and the volume of events is high. In this case, it is possible for multiple events to contain the same time stamp. If multiple events contain the same time stamp, ETW cannot guarantee the order of those events.
The ProcessTrace function blocks the thread until it delivers all events, the BufferCallback function returns FALSE, or you call CloseTrace. 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 several-second delay 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 or Retrieving Event Data Using MOF.
Requirements
|
Minimum supported client |
Windows 2000 Professional [desktop apps | Windows Store apps] |
|---|---|
|
Minimum supported server |
Windows 2000 Server [desktop apps | Windows Store apps] |
|
Header |
|
|
Library |
|
|
DLL |
|
See also