EventWrite 函数 (evntprov.h)

  • 项目

写入使用当前线程的活动 ID 的 ETW 事件。

语法

ULONG EVNTAPI EventWrite(
  [in]           REGHANDLE              RegHandle,
  [in]           PCEVENT_DESCRIPTOR     EventDescriptor,
  [in]           ULONG                  UserDataCount,
  [in, optional] PEVENT_DATA_DESCRIPTOR UserData
);

参数

[in] RegHandle

提供程序的注册句柄。 句柄来自 EventRegister。 生成的事件将使用与句柄关联的 ProviderId。

[in] EventDescriptor

EVENT_DESCRIPTOR 事件信息 (元数据) 包括 ID、版本、级别、关键字、通道、操作码和任务。

重要

ProviderId、Level 和 Keyword 是筛选事件的主要方法。 其他类型的筛选是可能的，但开销要高得多。 始终为每个事件分配非零级别和关键字 (keyword) 。

[in] UserDataCount

UserData 中的EVENT_DATA_DESCRIPTOR结构数。 最大数目为 128。

[in, optional] UserData

UserDataCount的数组EVENT_DATA_DESCRIPTOR描述事件中要包含的数据的结构。 如果 UserDataCount 为零，UserData 可能为 NULL。

每个 EVENT_DATA_DESCRIPTOR 描述要包含在事件中的一个内存块。 指定的块将按没有填充或对齐的顺序连接，以形成事件内容。 如果使用基于清单的解码，则事件内容必须与与清单中的事件关联的模板中指定的布局匹配。

返回值

如果成功或返回错误代码，则返回 ERROR_SUCCESS 。 可能的错误代码包括：

  • ERROR_INVALID_PARAMETER：一个或多个参数无效。
  • ERROR_INVALID_HANDLE：提供程序的注册句柄无效。
  • ERROR_ARITHMETIC_OVERFLOW：事件大小大于允许的最大 (64KB - 标头) 。
  • ERROR_MORE_DATA：会话缓冲区大小对于事件来说太小。
  • ERROR_NOT_ENOUGH_MEMORY：当已填充缓冲区尝试刷新到磁盘，但磁盘 IO 发生速度不够快时发生。 当磁盘速度缓慢且事件流量过大时，会发生这种情况。 最终，不再有空 () 缓冲区，事件将被删除。
  • STATUS_LOG_FILE_FULL：实时播放文件已满。 在实时使用者使用播放文件中的事件之前，事件不会记录到会话中。

错误代码主要用于调试和诊断方案。 即使无法编写 ETW 事件，大多数生产代码也应继续运行并继续报告事件，因此发布版本通常应忽略错误代码。

备注

大多数事件提供程序不会直接调用 EventWrite 。 相反，大多数事件提供程序都是使用 ETW 框架实现的，该框架包装对 EventRegister、 EventWrite 和 EventUnregister 的调用。 例如，可以 编写事件清单 ，然后使用 消息编译器 为事件生成 C/C++ 代码，或者使用 TraceLogging 来避免需要清单。

EventWrite 将根据 RegHandle) 、Level、Keyword 和其他事件特征确定的 ProviderId (将事件路由到相应的跟踪会话。 如果没有跟踪会话正在记录此事件，此函数将不执行任何操作并返回 ERROR_SUCCESS。

若要降低未由任何跟踪会话记录的事件的性能影响，可以在准备数据和调用 EventWrite 之前调用 EventEnabled 来确定是否有任何跟踪会话正在记录事件。

EventWrite 将事件的活动 ID 设置为当前线程的活动 ID。 EventWrite 不包括事件中的相关活动 ID。 若要指定其他活动 ID 或添加相关活动 ID，请使用 EventWriteTransfer。

EventWrite 等效于 EventWriteEx，筛选器为 0，标志为 0，ActivityId 为 NULL，RelatedActivityId 为 NULL。

要求

   
最低受支持的客户端 Windows Vista [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 | UWP 应用]
目标平台 Windows
标头 evntprov.h
Library Advapi32.lib
DLL Advapi32.dll

请参阅

EventActivityIdControl

EventRegister

EventWriteTransfer

EventWriteEx

编写基于清单的事件。