EvtFormatMessage function (winevt.h)

Artikel
07/27/2022

Formats a message string.

Syntax

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
);

Parameters

[in] PublisherMetadata

A handle to the provider's metadata that the EvtOpenPublisherMetadata function returns. The handle acts as a formatting context for the event or message identifier.

You can set this parameter to NULL if the Windows Event Collector service forwarded the event. Forwarded events include a RenderingInfo section that contains the rendered message strings. You can also set this parameter to NULL if the event property that you are formatting is defined in the Winmeta.xml file (for example, if level is set to win:Error). In the latter case, the service uses the Winmeta provider as the formatting context and will format only those message strings that you reference in your event that are defined in the Winmeta.xml file.

[in] Event

A handle to an event. The Flags parameter specifies the message string in the event that you want to format. This parameter must be NULL if the Flags parameter is set to EvtFormatMessageId.

[in] MessageId

The resource identifier of the message string that you want to format. To get the resource identifier for a message string, call the GetPublisherMetadataProperty function. Set this parameter only if the Flags parameter is set to EvtFormatMessageId.

[in] ValueCount

The number of values in the Values parameter.

[in] Values

An array of insertion values to use when formatting the event's message string. Typically, you set this parameter to NULL and the function gets the insertion values from the event data itself. You would use this parameter to override the default behavior and supply the insertion values to use. For example, you might use this parameter if you wanted to resolve a SID to a principal name before inserting the value.

To override the insertion values, the Flags parameter must be set to EvtFormatMessageEvent, EvtFormatMessageXML, or EvtFormatMessageId. If Flags is set to EvtFormatMessageId, the resource identifier must identify the event's message string.

[in] Flags

A flag that specifies the message string in the event to format. For possible values, see the EVT_FORMAT_MESSAGE_FLAGS enumeration.

[in] BufferSize

The size of the Buffer buffer, in characters.

[in] Buffer

A caller-allocated buffer that will receive the formatted message string. You can set this parameter to NULL to determine the required buffer size.

[out] BufferUsed

The size, in characters of the caller-allocated buffer that the function used or the required buffer size if the function fails with ERROR_INSUFFICIENT_BUFFER.

Return value

Return code/value	Description
TRUE	The function succeeded.
FALSE	The function failed. Call the GetLastError function to get the error code.

Remarks

When the service attempts to find a message for an event, the service looks in the message table resources of the publisher indicated by the PublisherMetadata parameter. After the message ID is found, the following search algorithms are used.

For event messages:

Search the file specified in messageFileName attribute of the provider element.
If not found, search system messages.

For the Level, Opcode, and Keyword attributes of the event element:

Search the Winmeta provider resources.
Search the file specified in messageFileName attribute of the provider element.

For the Task attribute of the event element:

Search the file specified in messageFileName attribute of the provider element.
If not found, search the Winmeta provider resources.

For localizable parameters referenced as %%n (where n is the message ID) in the event message:

Search files listed in parameterFileName attribute of the provider element from left to right.
If not found, search system messages.

Examples

For an example that shows how to use this function, see Formatting Event Messages and Getting a Provider's Metadata.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	winevt.h
Library	Wevtapi.lib
DLL	Wevtapi.dll

Dela via