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 code | Description |
|---|---|
|
One of the following is true:
|
|
One of the following is true:
|
|
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 |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
FlushTraceW (Unicode) and FlushTraceA (ANSI) |
See also