CloseTrace function (evntrace.h)
The CloseTrace function closes a trace processing session that was created with OpenTrace.
Syntax
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI CloseTrace(
[in] PROCESSTRACE_HANDLE 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 |