OpenTrace function

The OpenTrace function opens a real-time trace session or log file for consuming.

Syntax


TRACEHANDLE OpenTrace(
  _Inout_  PEVENT_TRACE_LOGFILE Logfile
);

Parameters

Logfile [in, out]

Pointer to an EVENT_TRACE_LOGFILE structure. The structure specifies the source from which to consume events (from a log file or the session in real time) and specifies the callbacks the consumer wants to use to receive the events.

Return value

If the function succeeds, it returns a handle to the trace.

If the function fails, it returns INVALID_PROCESSTRACE_HANDLE.

Note  If your code base supports Windows 7 and Windows Vista, and also supports earlier operating systems such as Windows XP and Windows Server 2003, do not use the constants described above. Instead, determine the operating system on which you are running and compare the return value to the following values.

Operating systemApplicationReturn value to compare
Windows 7 and Windows Vista32-bit0x00000000FFFFFFFF
Windows 7 and Windows Vista64-bit0XFFFFFFFFFFFFFFFF
Windows XP and Windows Server 200332- or 64-bit0XFFFFFFFFFFFFFFFF

 

If the function returns INVALID_PROCESSTRACE_HANDLE, you can use the GetLastError function to obtain extended error information. The following table lists some common errors and their causes.

Return codeDescription
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

Consumers call this function.

After calling OpenTrace, call the ProcessTrace function to process the events. When you have finished processing events, call the CloseTrace function.

Note that you can process events from only one real-time session.

Windows Vista and earlier: If the function fails it will returns INVALID_HANDLE_VALUE. To avoid compile-time errors, cast INVALID_HANDLE_VALUE to TRACEHANDLE as follows: (TRACEHANDLE)INVALID_HANDLE_VALUE.

Examples

For an example that uses OpenTrace, 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

Unicode and ANSI names

OpenTraceW (Unicode) and OpenTraceA (ANSI)

See also

CloseTrace
EVENT_TRACE_LOGFILE
ProcessTrace

 

 

Community Additions

ADD
Show:
© 2014 Microsoft