Edit

StopTraceA function (evntrace.h)

  • Article

The StopTrace function stops the specified event tracing session.

This function is obsolete. The ControlTrace function supersedes this function.

Syntax

ULONG WMIAPI StopTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

TraceHandle

Handle to the event tracing session to be stopped, or 0. You must specify a non-zero TraceHandle if InstanceName is NULL. This parameter will be used only if InstanceName is NULL. The handle is returned by the StartTrace.

InstanceName

Name of the event tracing session to be stopped, or NULL. You must specify InstanceName if TraceHandle is 0.

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

Properties

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.

Starting with Windows 10, version 1703: For better performance in cross process scenarios, you can now pass filtering in to StopTrace for system wide private loggers. You will need to pass in the new EVENT_TRACE_PROPERTIES_V2 structure to include filtering information. See Configuring and Starting a Private Logger Session for more details.

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_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.
    • InstanceName and TraceHandle are both NULL.
    • InstanceName is NULL and TraceHandle is not a valid handle.

  • 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

Event trace controllers call this function.

This function is obsolete. Instead, use ControlTrace with ControlCode set to EVENT_TRACE_CONTROL_STOP.

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.

Do not call StopTrace from DllMain (may cause deadlock).

Note

The evntrace.h header defines StopTrace 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

See also

ControlTrace

StartTrace