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 结构的以下成员指定值。
- 大小
- Guid 或 GuidPtr
- 标志
根据提供程序提供的信息的复杂性，还应考虑为以下成员指定值。
- Class.Type
- Class.Level
返回值
如果函数成功，则返回值为 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。
提供程序在调用此函数之前，提供程序
- 必须调用 RegisterTraceGuids 函数来注册自身和事件跟踪类。
- 必须启用。 控制器调用 EnableTrace 函数来启用提供程序。
事件要么写入日志文件，要么实时发送到事件跟踪使用者，要么同时写入两者。 传递给 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 |