OpenTraceA function (evntrace.h)
The OpenTrace function opens an ETW trace processing handle for consuming events from an ETW real-time trace session or an ETW log file.
Syntax
PROCESSTRACE_HANDLE WMIAPI OpenTraceA(
[in, out] PEVENT_TRACE_LOGFILEA Logfile
);
Parameters
[in, out] Logfile
Pointer to an EVENT_TRACE_LOGFILE structure. The structure specifies the source from which to consume events (from an ETW log file or a real-time ETW session) and specifies the callbacks the consumer wants to use to receive the events. On success, OpenTrace will update the structure with information from the opened file or session.
Return value
If the function succeeds, it returns the trace processing handle. The handle should be closed using CloseTrace.
If the function fails, it returns INVALID_PROCESSTRACE_HANDLE.
(INVALID_PROCESSTRACE_HANDLE is equivalent to (UINT64)UINTPTR_MAX.)
Note
Prior to Windows Vista, OpenTrace returned UINT64_MAX in case of
failure. If your code supports both older operating systems (Windows XP or
Windows Server 2003) and newer versions of Windows (Windows Vista and later),
you must determine the operating system on which you are running and compare
the return value to the appropriate value.
| Operating system | Process Type | Value indicating failure |
|---|---|---|
| Prior to Windows Vista | 32- or 64-bit | 0XFFFFFFFFFFFFFFFF = UINT64_MAX |
| Windows Vista or later | 32-bit | 0x00000000FFFFFFFF = (UINT64)UINTPTR_MAX |
| Windows Vista or later | 64-bit | 0XFFFFFFFFFFFFFFFF = (UINT64)UINTPTR_MAX |
If the function fails, you can use the GetLastError function to obtain extended error information. The following are some common errors and their causes.
ERROR_INVALID_PARAMETER
The Logfile parameter is NULL.
ERROR_BAD_PATHNAME
If you did not specify the LoggerName member of EVENT_TRACE_LOGFILE, you must specify a valid log file name.
ERROR_ACCESS_DENIED
Only users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can consume events in real time. To grant a restricted user the ability to consume events in real time, add them to the Performance Log Users group.
Windows XP and Windows 2000: Anyone can consume real time events.
Remarks
Trace consumers call this function to open a trace processing session.
After calling OpenTrace, call the ProcessTrace function to process the events. When you have finished processing events, call the CloseTrace function to close the trace processing handle.
Examples
For an example that uses OpenTrace, see Using TdhFormatProperty to Consume Event Data.
Note
The evntrace.h header defines OpenTrace as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
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 |