共用方式為

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 。 轉寄的事件包含 RenderInfo 區段，其中包含轉譯的訊息字串。 如果您格式化的事件屬性是在 Winmeta.xml 檔案中定義， (例如，如果 level 設定為 win：Error) ，您也可以將此參數設定為 NULL 。 在後者的情況下，服務會使用 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而失敗，則為呼叫端配置緩衝區的大小，或是所需的緩衝區大小。

傳回值

傳回碼/值 Description
TRUE
 此函數已成功。
FALSE
 函式失敗。 呼叫 GetLastError 函 式以取得錯誤碼。

備註

當服務嘗試尋找事件的訊息時，服務會在 PublisherMetadata 參數所指出之發行者的訊息數據表資源中尋找。 找到訊息標識碼之後，會使用下列搜尋演算法。

針對事件訊息：

  1. 搜尋提供者專案的 messageFileName 屬性中指定的檔案。
  2. 如果找不到，請搜尋系統訊息。
針對 事件 專案的 Level、Opcode 和 Keyword 屬性：
  1. 搜尋 Winmeta 提供者資源。
  2. 搜尋提供者專案的 messageFileName 屬性中指定的檔案。
事件 專案的 Task 屬性：
  1. 搜尋提供者專案的 messageFileName 屬性中指定的檔案。
  2. 如果找不到，請搜尋 Winmeta 提供者資源。
若為參考為 %%n 的可本地化參數， (其中 n 是事件訊息中的訊息識別碼) ：
  1. 搜尋提供者元素的parameterFileName屬性中所列的檔案，從左至右。
  2. 如果找不到，請搜尋系統訊息。

範例

如需示範如何使用此函式的範例，請參閱 格式化事件訊息 和 取得提供者的元數據。

規格需求

需求 值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平台 Windows
標頭 winevt.h
程式庫 Wevtapi.lib
Dll Wevtapi.dll

另請參閱

FormatMessage