traceEventInstance 函数 (evntrace.h)

项目
08/23/2023

基于 RegisterTraceGuids 的 (“Classic”) 事件提供程序使用 TraceEventInstance 函数将结构化事件发送到具有实例标识符的事件跟踪会话。

事件使用实例标识符将事件与事务相关联。此函数还可用于跟踪相关事件之间的分层关系。

语法

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

参数

[in] TraceHandle

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

[in] EventTrace

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

大小
标志
RegHandle

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

Class.Type
Class.Level

若要跟踪相关事件之间的分层关系，还需设置 ParentRegHandle 成员。

[in] InstInfo

指向 EVENT_INSTANCE_INFO 结构的指针，该结构包含此事件跟踪类的注册句柄和实例标识符。使用 CreateTraceInstanceId 函数初始化结构。

[in] ParentInstInfo

指向 EVENT_INSTANCE_INFO 结构的指针，该结构包含父事件跟踪类及其实例标识符的注册句柄。使用 CreateTraceInstanceId 函数初始化结构。如果不跟踪分层关系，则设置为 NULL 。

返回值

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

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

ERROR_INVALID_FLAGS

EVENT_INSTANCE_HEADER的 Flags 成员不包含WNODE_FLAG_TRACED_GUID。
ERROR_OUTOFMEMORY

内存不足，无法完成函数调用。以下“备注”部分描述了导致此错误代码的原因。
ERROR_INVALID_PARAMETER

下列情况之一存在：
- EventTrace 为 NULL。
- pInstInfo 为 NULL。
- pInstInfo 的成员为 NULL。
- TraceHandle 为 NULL。
- EVENT_INSTANCE_HEADER的 Size 成员不正确。
ERROR_INVALID_HANDLE

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

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

Windows 2000 和 Windows XP： 不支持。
ERROR_OUTOFMEMORY

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

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

备注

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

注意

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

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

必须调用 RegisterTraceGuids 函数来注册自身和事件跟踪类。
必须调用 CreateTraceInstanceId 函数，以便为已注册的事件跟踪类创建实例标识符。
必须启用。控制器调用 EnableTrace 函数来启用提供程序。

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

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

若要跟踪不相关的事件，请使用 TraceEvent 函数。

Windowsxp： 无法正常工作。

示例

有关使用 CreateTraceInstanceId 和 TraceEventInstance 生成相关事件集的示例，请参阅跟踪事件实例。

要求


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