Функция EvtFormatMessage (winevt.h)

Статья
08/27/2023

Форматирует строку сообщения.

Синтаксис

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 . Дескриптор выступает в качестве контекста форматирования для события или идентификатора сообщения.

Для этого параметра можно задать значение NULL , если служба сборщика событий Windows перенаправила событие. Перенаправленные события включают раздел RenderingInfo , содержащий отрисованные строки сообщений. Можно также задать для этого параметра значение NULL , если свойство события, которое вы форматируете, определено в файле Winmeta.xml (например, если для параметра level задано значение win:Error). В последнем случае служба использует поставщик Winmeta в качестве контекста форматирования и будет форматировать только те строки сообщений, на которые вы ссылаетесь в событии, определенные в файле Winmeta.xml.

[in] Event

Дескриптор события. Параметр Flags указывает строку сообщения в событии, которое требуется отформатировать. Этот параметр должен иметь значение NULL , если для параметра Flags задано значение EvtFormatMessageId.

[in] MessageId

Идентификатор ресурса строки сообщения, которую требуется отформатировать. Чтобы получить идентификатор ресурса для строки сообщения, вызовите функцию GetPublisherMetadataProperty . Задайте этот параметр, только если для параметра Flags задано значение EvtFormatMessageId.

[in] ValueCount

Количество значений в параметре Values .

[in] Values

Массив значений вставки, используемый при форматировании строки сообщения события. Как правило, для этого параметра устанавливается значение NULL , а функция получает значения вставки из самих данных события. Этот параметр используется для переопределения поведения по умолчанию и предоставления используемых значений вставки. Например, этот параметр можно использовать, если требуется разрешить идентификатор безопасности в имя участника перед вставкой значения.

Чтобы переопределить значения вставки, параметру 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 . После обнаружения идентификатора сообщения используются следующие алгоритмы поиска.

Для сообщений о событиях:

Выполните поиск в файле, указанном в атрибуте messageFileName элемента provider .
Если не найдено, выполните поиск системных сообщений.

Для атрибутов Level, Opcode и Keyword элемента event :

Выполните поиск ресурсов поставщика Winmeta.
Выполните поиск в файле, указанном в атрибуте messageFileName элемента provider .

Для атрибута Task элемента event :

Выполните поиск в файле, указанном в атрибуте messageFileName элемента provider .
Если не найдено, выполните поиск по ресурсам поставщика Winmeta.

Для локализуемых параметров, на которые ссылается %%n (где n — идентификатор сообщения) в сообщении о событии:

Поиск файлов, перечисленных в атрибуте parameterFileName элемента поставщика слева направо.
Если не найдено, выполните поиск системных сообщений.

Примеры

Пример использования этой функции см. в разделах Форматирование сообщений о событиях и Получение метаданных поставщика.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winevt.h
Библиотека	Wevtapi.lib
DLL	Wevtapi.dll

См. также раздел

FormatMessage

Поделиться через