通过

TraceMessage 函数 (evntrace.h)

  • 项目

基于 RegisterTraceGuids 的 (“Classic”) 事件提供程序使用 TraceMessage 函数将基于消息 (基于 TMF 的 WPP) 事件发送到事件跟踪会话。

语法

ULONG TraceMessage(
  [in] TRACEHANDLE LoggerHandle,
  [in] ULONG       MessageFlags,
  [in] LPCGUID     MessageGuid,
  [in] USHORT      MessageNumber,
       ...         
);

参数

[in] LoggerHandle

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

[in] MessageFlags

将其他信息添加到事件的特定于提供程序的数据部分的开头。 事件的特定于提供程序的数据部分将仅包含已设置的标志的数据。 参数数据的变量列表将遵循此信息。 此参数可使用以下一个或多个值。

  • TRACE_MESSAGE_COMPONENTID

    在消息中包含组件标识符。 MessageGuid 参数包含组件标识符。

  • TRACE_MESSAGE_GUID

    在消息中包含事件跟踪类 GUID。 MessageGuid 参数包含事件跟踪类 GUID。

  • TRACE_MESSAGE_SEQUENCE

    在消息中包含序列号。 序列号从 1 开始。 若要使用此标志，控制器必须在创建会话时设置 EVENT_TRACE_USE_GLOBAL_SEQUENCE 或 EVENT_TRACE_USE_LOCAL_SEQUENCE 日志文件模式。

  • TRACE_MESSAGE_SYSTEMINFO

    在消息中包含线程标识符和进程标识符。

  • TRACE_MESSAGE_TIMESTAMP

    在邮件中包含时间戳。

TRACE_MESSAGE_COMPONENTID 和 TRACE_MESSAGE_GUID 是互斥的。

信息按以下顺序包含在事件数据中：

  • 序列号
  • 事件跟踪类 GUID (或组件标识符)
  • 时间戳
  • 线程标识符
  • 进程标识符

[in] MessageGuid

标识消息的类 GUID 或组件 ID。 取决于 MessageFlags 是否包含 TRACE_MESSAGE_COMPONENTID 或 TRACE_MESSAGE_GUID 标志。

[in] MessageNumber

唯一标识消息的每个匹配项的数字。 必须定义为此参数指定的值;值应对应用程序有意义。

...

要追加到消息的变量参数列表。 使用此列表可以指定特定于提供程序的事件数据。 列表必须由参数对组成，如下所示。

  • PVOID：指向参数数据的指针。
  • size_t：参数数据的大小（以字节为单位）。

使用由指向 NULL 和零的指针组成的参数对终止列表。

调用方必须确保参数大小 + 72 的总和不超过事件跟踪会话缓冲区的大小。

返回值

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

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

  • ERROR_INVALID_HANDLE

    LoggerHandle 为 NULL 或指定 NT 内核记录器会话句柄。

  • ERROR_NOT_ENOUGH_MEMORY

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

    Windows 2000 和 Windows XP： 不支持。

  • ERROR_OUTOFMEMORY

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

  • ERROR_INVALID_PARAMETER

    MessageFlags 包含无效的值。

  • ERROR_MORE_DATA

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

备注

基于 TMF 的 WPP 提供程序调用此函数。

注意

大多数开发人员不会直接调用此函数。 WPP 提供程序使用由 tracewpp.exe 生成的包装函数，而不是调用 ETW API。

如果需要从包装函数访问消息跟踪功能，请调用此函数的 TraceMessageVa 版本。

如果 MessageFlags 参数不包含 TRACE_MESSAGE_GUID 标志，则使用者必须使用 EventCallback 回调来接收和处理事件。 如果未指定 TRACE_MESSAGE_GUID 标志，使用者将无法使用 EventClassCallback，因为 EVENT_TRACE 结构的 Header.Guid 成员将不包含事件跟踪类 GUID。

请注意，仅当指定了相应的标志时，才会设置对应于 MessageFlags 标志的 EVENT_TRACE 和 EVENT_TRACE_HEADER 结构的成员。 例如，仅当指定 TRACE_MESSAGE_SYSTEMINFO 标志时，才会填充 EVENT_TRACE_HEADER 的 ThreadId 和 ProcessId 成员。

要求

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

请参阅

TraceEvent

TraceEventInstance

TraceMessageVa