FlushTrace function

The FlushTrace function causes an event tracing session to immediately deliver buffered events for the specified session. (An event tracing session does not deliver events until an active buffer is full.)

The ControlTrace function supersedes this function.

Syntax


ULONG FlushTrace(
  _In_     TRACEHANDLE SessionHandle,
  _In_     LPCTSTR SessionName,
  _Inout_  PEVENT_TRACE_PROPERTIES Properties
);

Parameters

SessionHandle [in]

Handle to the event tracing session for whose buffers you want to flush, 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 whose buffers you want to flush, or NULL. You must specify SessionName if SessionHandle is NULL.

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

Properties [in, out]

Pointer to an initialized EVENT_TRACE_PROPERTIES structure.

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.

On output, the structure receives the property settings and session statistics of the event tracing session, which reflect the state of the session after the flush.

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_INVALID_PARAMETER

One of the following is true:

  • Properties is NULL.
  • SessionName and SessionHandle are both NULL.
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_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.

Typically, you do not need to flush buffers yourself. However, you may want to flush buffers if the event rate is low and you are delivering events in real time.

Note that it is not safe to flush buffers from DllMain.

Requirements

Minimum supported client

Windows XP [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Header

Evntrace.h

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

FlushTraceW (Unicode) and FlushTraceA (ANSI)

See also

ControlTrace

 

 

Community Additions

ADD
Show:
© 2015 Microsoft