Edit

CloseTrace function (evntrace.h)

  • Article

The CloseTrace function closes a trace processing session that was created with OpenTrace.

Syntax

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI CloseTrace(
  [in] TRACEHANDLE TraceHandle
);

Parameters

[in] TraceHandle

Handle to the trace processing session to close. The OpenTrace function returns this handle.

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_INVALID_HANDLE

    One of the following is true:

    • TraceHandle is 0.
    • TraceHandle is INVALID_PROCESSTRACE_HANDLE.
    • TraceHandle is not a valid handle.

  • ERROR_BUSY

    Prior to Windows Vista, you cannot close the trace until the ProcessTrace function completes.

  • ERROR_CTX_CLOSE_PENDING

    The call was successful. The ProcessTrace function will stop after it has processed all real-time events in its buffers (it will not receive any new events).

Remarks

Consumers call this function to close a trace handle returned by OpenTrace.

Important

Do not use this function to close the trace handle returned by StartTrace.

If you are processing events from a log file, you call this function only after the ProcessTrace function returns. However, if you are processing real-time events, you can call this function before ProcessTrace returns. (Another way to stop trace processing is to return FALSE from BufferCallback.)

If you call this function before ProcessTrace returns, the CloseTrace function returns ERROR_CTX_CLOSE_PENDING. The ERROR_CTX_CLOSE_PENDING code indicates that the CloseTrace function call was successful; the ProcessTrace function will stop processing events after it processes all previously-queued events (ProcessTrace will not receive any new events after you call the CloseTrace function). You can call the CloseTrace function from your BufferCallback, EventCallback, or EventClassCallback callback.

Prior to Windows Vista: You can call CloseTrace only after ProcessTrace returns.

Examples

For an example that uses CloseTrace, see Retrieving Event Data Using TDH.

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

See also

OpenTrace

ProcessTrace