StopTrace function

The StopTrace function stops the specified event tracing session.

The ControlTrace function supersedes this function.

Syntax


ULONG StopTrace(
  _In_   TRACEHANDLE SessionHandle,
  _In_   LPCTSTR SessionName,
  _Out_  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

SessionHandle [in]

Handle to the event tracing session that you want to stop, or NULL. You must specify SessionHandle if SessionName is NULL. However, ETW ignores the handle if SessionName is not NULL. The handle is returned by the StartTrace function.

SessionName [in]

Pointer to a null-terminated string that specifies the name of the event tracing session that you want to stop, or NULL. You must specify SessionName if SessionHandle is NULL.

To specify the NT Kernel Logger session, set SessionName to KERNEL_LOGGER_NAME.

Properties [out]

Pointer to an EVENT_TRACE_PROPERTIES structure that receives the final properties and statistics for the session.

If you are using a newly initialized structure, you only need to set the Wnode.BufferSize, Wnode.Guid, LoggerNameOffset, and LogFileNameOffset members of the structure. You can use the maximum session name (1024 characters) and maximum log file name (1024 characters) lengths to calculate the buffer size and offsets if not known.

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

One of the following is true:

  • The Wnode.BufferSize member of Properties specifies an incorrect size.
  • Properties does not have sufficient space allocated to hold a copy of the session name and log file name (if used).
ERROR_INVALID_PARAMETER

One of the following is true:

  • Properties is NULL.
  • SessionName and SessionHandle are both NULL.
ERROR_ACCESS_DENIED

Only users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can control event tracing sessions. To grant a restricted user the ability to control trace sessions, add them to the Performance Log Users group.

Windows XP and Windows 2000:  Anyone can control a trace session.

 

Remarks

Controllers call this function.

If LogFileMode contains EVENT_TRACE_FILE_MODE_PREALLOCATE, StartTrace extends the log file to MaximumFileSize bytes. The file occupies the entire space during logging, for both circular and sequential logs. When you stop the logger, the log file is reduced to the size needed.

Note that it is not safe to stop a trace session from DllMain.

Windows Phone 8.1: This API is supported.

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

StopTraceW (Unicode) and StopTraceA (ANSI)

See also

ControlTrace
StartTrace

 

 

Community Additions

ADD
Show:
© 2014 Microsoft