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 |