Export (0) Print
Expand All
Expand Minimize

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 and Windows XP:  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 codeDescription
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.

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 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.

ERROR_WMI_ALREADY_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.)

Prior to Windows Vista:  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

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

See also

BufferCallback
EventCallback
EventClassCallback
OpenTrace
SetTraceCallback

 

 

Community Additions

ADD
Show:
© 2014 Microsoft