TraceEvent 函数 (evntrace.h)

基于 RegisterTraceGuids 的 (“Classic”) 事件提供程序使用 TraceEvent 函数将结构化事件发送到事件跟踪会话。

语法

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

[in] TraceHandle

记录事件的事件跟踪会话的句柄。提供程序在其 ControlCallback 实现中调用 GetTraceLoggerHandle 函数时获取句柄。

[in] EventTrace

指向 EVENT_TRACE_HEADER 结构的指针。可以选择将特定于事件的数据追加到结构中。可以记录的最大事件略低于 64K。必须为 EVENT_TRACE_HEADER 结构的以下成员指定值。

根据提供程序提供的信息的复杂性，还应考虑为以下成员指定值。

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

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

ERROR_INVALID_FLAG_NUMBER

EVENT_TRACE_HEADER 结构的 Flags 成员不正确。
ERROR_INVALID_HANDLE

TraceHandle 无效或指定 NT 内核记录器会话句柄。
ERROR_NOT_ENOUGH_MEMORY

该会话已没有可用缓冲区可供写入。这种情况可能会在事件发生率过高时出现，因为此时磁盘子系统会过载或者缓冲区数目会太小。 TraceEvent 不会阻止更多缓冲区可用，而是放弃事件。

请考虑增加该会话缓冲区的数目和大小，或者减少写入事件的数目或大小。

Windows 2000： 不支持。
ERROR_OUTOFMEMORY

该事件被丢弃，因为尽管缓冲池尚未达到其最大大小，但没有足够的可用内存来分配额外的缓冲区，并且没有可用于接收事件的缓冲区。
ERROR_INVALID_PARAMETER

下列情况之一存在：
- TraceHandle 为 NULL。
- EventTrace 为 NULL。
- EVENT_TRACE_HEADER 结构的 Size 成员不正确。
ERROR_MORE_DATA

单个事件中的数据不能跨多个缓冲区。跟踪事件限制为事件跟踪会话缓冲区的大小减去 EVENT_TRACE_HEADER 结构的大小。

基于 MOF 的 ETW 提供程序调用此函数。

注意

大多数开发人员不会调用此函数。此 API 支持基于 MOF 的 ETW，但基于 MOF 的 ETW 已弃用，改用基于清单的 ETW。此外，大多数基于 MOF 的提供程序使用由 MC.exe 生成的包装函数，而不是直接调用 ETW API。

提供程序在调用此函数之前，提供程序

事件要么写入日志文件，要么实时发送到事件跟踪使用者，要么同时写入两者。传递给 StartTrace 的 EVENT_TRACE_PROPERTIES 结构的 LogFileMode 成员定义发送事件的位置。

跟踪事件按其发生顺序写入。

若要跟踪一组相关事件，请使用 TraceEventInstance 函数。

在 Windows Vista 上，应使用 EventWrite 函数来记录事件。

有关使用 TraceEvent 的示例，请参阅跟踪事件。


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	evntrace.h
Library	Advapi32.lib
DLL	Advapi32.dll