FlushTraceA 函数 (evntrace.h)

FlushTrace 函数会导致事件跟踪会话立即为指定会话传递缓冲事件。 默认情况下，当缓冲区已满、会话的 FlushTimer 过期或会话关闭时，事件跟踪会话将传递事件。

此函数已过时。 ControlTrace 函数取代此函数。

语法

ULONG WMIAPI FlushTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

参数

[in] TraceHandle

要刷新的事件跟踪会话的句柄，或 0。 如果 InstanceName 为 NULL，则必须指定非零 TraceHandle。 仅当 InstanceName 为 NULL 时，才会使用此参数。 该句柄由 StartTrace 返回。

[in] InstanceName

要刷新的事件跟踪会话的名称，或 NULL。 如果 TraceHandle 为 0，则必须指定 InstanceName。

若要指定 NT 内核记录器会话，请将 InstanceName 设置为 KERNEL_LOGGER_NAME。

[in, out] Properties

指向已初始化 EVENT_TRACE_PROPERTIES 结构的指针。

如果使用新初始化的结构，则只需设置结构的 Wnode.BufferSize、 Wnode.Guid、 LoggerNameOffset 和 LogFileNameOffset 成员。 可以使用最大会话名称 (1024 个字符) 和最大日志文件名 (1024 个字符) 长度来计算缓冲区大小和偏移量（如果未知）。

在输出时，结构接收事件跟踪会话的属性设置和会话统计信息，这些属性设置和会话统计信息反映刷新后的会话状态。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值为 系统错误代码之一。 下表包含一些常见错误及其原因。

• ERROR_INVALID_PARAMETER

  下列情况之一存在：

  • 属性 为 NULL。
  • InstanceName 和 TraceHandle 均为 NULL。
  • InstanceName 为 NULL，TraceHandle 不是有效的句柄。

• ERROR_BAD_LENGTH

  下列情况之一存在：

  • 属性的 Wnode.BufferSize 成员指定了不正确的大小。
  • 如果) 使用，属性没有分配足够的空间来保存会话名称和日志文件名称的副本 (。

• ERROR_ACCESS_DENIED

  只有具有管理权限的用户、性能日志用户组中的用户以及作为 LocalSystem、LocalService、NetworkService 运行的服务才能控制事件跟踪会话。 若要授予受限用户控制跟踪会话的能力，请将这些用户添加到“性能日志用户”组。

  Windows XP 和 Windows 2000： 任何人都可以控制跟踪会话。

注解

事件跟踪控制器调用此函数。

此函数已过时。 请改用 ControlTrace ，将 ControlCode 设置为 EVENT_TRACE_CONTROL_FLUSH。

此函数可与内存中会话一起使用， (以 EVENT_TRACE_BUFFERING_MODE 标志) 启动的会话，以将数据从跟踪写入文件。

通常不需要刷新基于文件或实时的会话，因为当缓冲区已满 (即当缓冲区没有空间用于下一个事件) 、跟踪会话的 FlushTimer 过期或跟踪会话关闭时，ETW 会自动刷新缓冲区。

不要从 DllMain 调用 FlushTrace (可能会导致死锁) 。

注意

evntrace.h 标头将 FlushTrace 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 | UWP 应用]
目标平台	Windows
标头	evntrace.h
Library	Advapi32.lib
DLL	Advapi32.dll

另请参阅

ControlTrace