Share via

EvtFormatMessage 函数 (winevt.h)

  • 项目

设置消息字符串的格式。

语法

BOOL EvtFormatMessage(
  [in]  EVT_HANDLE   PublisherMetadata,
  [in]  EVT_HANDLE   Event,
  [in]  DWORD        MessageId,
  [in]  DWORD        ValueCount,
  [in]  PEVT_VARIANT Values,
  [in]  DWORD        Flags,
  [in]  DWORD        BufferSize,
  [in]  LPWSTR       Buffer,
  [out] PDWORD       BufferUsed
);

参数

[in] PublisherMetadata

EvtOpenPublisherMetadata 函数返回的提供程序元数据的句柄。 句柄充当事件或消息标识符的格式设置上下文。

如果 Windows 事件收集器服务转发了事件，则可以将此参数设置为 NULL 。 转发事件包括包含呈现的消息字符串的 RenderingInfo 部分。 如果在 Winmeta.xml 文件中定义了要设置格式的事件属性 (，则还可以将此参数设置为 NULL ，例如，如果 level 设置为 win：Error) 。 在后一种情况下，该服务使用 Winmeta 提供程序作为格式设置上下文，并且将仅设置你在事件中引用 Winmeta.xml 文件中定义的那些消息字符串的格式。

[in] Event

事件的句柄。 Flags 参数指定要格式化的事件中的消息字符串。 如果将 Flags 参数设置为 EvtFormatMessageId，此参数必须为 NULL。

[in] MessageId

要设置格式的消息字符串的资源标识符。 若要获取消息字符串的资源标识符，请调用 GetPublisherMetadataProperty 函数。 仅当 Flags 参数设置为 EvtFormatMessageId 时，才设置此参数。

[in] ValueCount

Values 参数中的值数。

[in] Values

设置事件的消息字符串格式时要使用的插入值的数组。 通常，将此参数设置为 NULL ，函数将从事件数据本身获取插入值。 可以使用此参数替代默认行为并提供要使用的插入值。 例如，如果要在插入值之前将 SID 解析为主体名称，则可以使用此参数。

若要替代插入值， 必须将 Flags 参数设置为 EvtFormatMessageEvent、 EvtFormatMessageXML 或 EvtFormatMessageId。 如果 Flags 设置为 EvtFormatMessageId，则资源标识符必须标识事件的消息字符串。

[in] Flags

一个标志，指定要格式化的事件中的消息字符串。 有关可能的值，请参阅 EVT_FORMAT_MESSAGE_FLAGS 枚举。

[in] BufferSize

缓冲区的大小（以字符为单位）。

[in] Buffer

将接收格式化消息字符串的调用方分配的缓冲区。 可以将此参数设置为 NULL ，以确定所需的缓冲区大小。

[out] BufferUsed

大小（以函数使用的调用方分配的缓冲区的字符为单位），如果函数失败并出现ERROR_INSUFFICIENT_BUFFER，则为所需的缓冲区大小。

返回值

返回代码/值 说明
TRUE
 函数成功。
FALSE
 函数失败。 调用 GetLastError 函数以获取错误代码。

注解

当服务尝试查找事件的消息时，该服务将在 PublisherMetadata 参数指示的发布服务器的消息表中查找资源。 找到消息 ID 后，使用以下搜索算法。

对于事件消息：

  1. 搜索提供程序元素的 messageFileName 属性中指定的文件。
  2. 如果未找到，请搜索系统消息。
对于 事件 元素的 Level、Opcode 和 Keyword 属性：
  1. 搜索 Winmeta 提供程序资源。
  2. 搜索提供程序元素的 messageFileName 属性中指定的文件。
对于 事件 元素的 Task 属性：
  1. 搜索提供程序元素的 messageFileName 属性中指定的文件。
  2. 如果未找到，请搜索 Winmeta 提供程序资源。
对于引用为 %%n 的可本地化参数 (其中 n 是事件消息中的消息 ID) ：
  1. 从左到右搜索提供程序元素的 parameterFileName 属性中列出的文件。
  2. 如果未找到，请搜索系统消息。

示例

有关演示如何使用此函数的示例，请参阅 设置事件消息格式 和 获取提供程序的元数据。

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 winevt.h
Library Wevtapi.lib
DLL Wevtapi.dll

另请参阅

FormatMessage