Share via

EventWriteString 函数 (evntprov.h)

  • 项目

写入包含字符串作为其数据的 ETW 事件。 不应使用此函数。

语法

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

参数

[in] RegHandle

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

[in] Level

用于描述事件的严重性或重要性的 8 位数字。

重要

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

有关事件级别的详细信息，请参阅 EVENT_DESCRIPTOR 。

[in] Keyword

一个 64 位位掩码，用于指示事件在一组事件类别中的成员身份。

重要

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

有关事件关键字 (keyword) 的详细信息，请参阅EVENT_DESCRIPTOR。

[in] String

要写入为事件数据的 NUL 终止字符串。

返回值

如果成功或错误代码，则返回 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 事件，因此发布版本通常应忽略错误代码。

备注

此 API 没有用，不应使用。

  • 大多数 ETW 分析工具不支持没有清单的仅字符串事件。
  • 如果没有清单，则有关事件 (重要信息（例如提供程序名称、事件 ID 和事件名称) ）不可用，因此即使分析工具支持仅字符串事件，生成的事件也很难使用。
  • 对于清单，此函数的行为几乎与基于清单的事件中的代码完全相同，其中包含单个字符串字段。 但是，跟踪分析工具可以更好地支持基于清单的事件。 此外， MC.exe 为具有单个字符串字段的事件生成的代码比 EventWriteString 函数更高效。

请考虑以下替代方法，而不是使用此 API：

  • 使用 TraceLoggingProvider.h 编写 ETW 分析工具非常支持的事件，无需清单即可工作，并包含提供程序名称和事件名称等元数据。
  • 编写检测清单。 使用单个 NUL 终止的字符串值创建简单事件。 即使没有清单，也可以编写和收集事件。 只需清单即可解码收集的跟踪。

EventWriteString 写入包含指定字符串的数据有效负载的事件。 此 API 几乎等效于以下代码：

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

生成的事件与 EventWrite 生成的任何其他事件相同，只不过生成的事件设置了 EVENT_HEADER_FLAG_STRING_ONLY 标志， (有关) 事件标志的信息，请参阅 EVENT_HEADER 。

请注意，写入事件时，ID、版本、操作码、任务和通道设置为 0。

请注意，事件使用当前线程的活动 ID。

识别 EVENT_HEADER_FLAG_STRING_ONLY 标志的 ETW 分析工具可以提取字符串值，即使解码器找不到事件提供程序的任何其他解码信息。 但是，如果没有清单，工具将无法确定事件的提供程序名称。

要求

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

请参阅

EventWrite

TraceLoggingProvider.h