Идентификаторы событий (ведение журнала событий)

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

Формат

На следующей схеме показан формат идентификатора события.

  3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
  1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
 +---+-+-+-----------------------+-------------------------------+
 |Sev|C|R|     Facility          |               Code            |
 +---+-+-+-----------------------+-------------------------------+

Sev

серьезность. Уровень серьезности определяется следующим образом:

00 — успех

01 — информационные

10 — предупреждение

11 — ошибка

C

Бит клиента. Этот бит определяется следующим образом:

0 — системный код

1. Код клиента

R

Зарезервированный бит.

Объекта

Код объекта. Это значение можно FACILITY_NULL.

Код

Код состояния для объекта.

Определения сообщений

Сообщения определяются в файле сообщений о событиях. Строки описания в файле сообщения о событии индексируются по идентификатору события, что позволяет Просмотр событий отображать текст для любого события на основе идентификатора события. Все описания локализованы и зависят от языка. Дополнительные сведения о создании файла сообщения см. в разделе Текстовые файлы сообщений.

Строки описания могут содержать заполнители строки вставки в формате %n, где %1 указывает первую строку вставки и т. д. Например, ниже приведен пример записи в MC-файле:

MessageId=0x4
Severity=Error
Facility=System
SymbolicName=MSG_CMD_DELETE
Language=English
File %1 contains %2, which is in error.
.

В этом случае буфер, возвращаемый ReadEventLog , содержит строки вставки. Элемент NumStrings структуры EVENTLOGRECORD указывает количество строк вставки. Элемент StringOffset структуры EVENTLOGRECORD указывает расположение первой строки вставки в буфере. Можно передать массив DWORD_PTRs, указывающих на адрес каждой строки в буфере при вызове функции FormatMessage , и он вставляет строки в сообщение.

Строка описания также может содержать заполнители для строк параметров из файла сообщения о параметрах. Заполнители имеют вид %%n, где %%1 заменяется строкой параметра с идентификатором 1 и т. д. Однако вы можете вставить строки параметров в строку сообщения, возвращаемую FormatMessage . Как правило, вы вызываете FormatMessage , чтобы получить строку сообщения для события. Затем вы анализируете строку сообщения для параметров %%n . Если сообщение содержит один или несколько параметров, загрузите значение реестра ParameterMessageFile для источника. Для каждого параметра в строке сообщения получите идентификатор и передайте его в FormatMessage , чтобы получить строку параметра. Замените параметр в строке сообщения строкой параметра, возвращенной FormatMessage .

Строки вставки

Строки вставки — это необязательные строки, не зависящие от языка, используемые для заполнения значений заполнителей в строках описания. Так как строки не локализованы, очень важно, чтобы эти заполнители использовались только для представления независимых от языка строк, таких как числовые значения, имена файлов, имена пользователей и т. д. Длина строки не должна превышать 32 килобайта — 1 символ.

Избегайте использования нескольких строк для создания описания большего размера. Строка вставки должна рассматриваться как данные, а не как текст. Например, в следующем примере pszString1 и pszString2 не следует использовать в качестве строк вставки для pszDescription.

LPSTR pszString1 = "successfully"; 
LPSTR pszString2 = "not"; 
LPSTR pszDescription = "The user was %1 added to the database.";

В следующем примере целесообразно использовать pszString1 или pszString2 для строки вставки в pszDescription.

LPSTR pszString1 = "c:\\testapp1.c"; 
LPSTR pszString2 = "c:\\testapp2.c"; 
LPSTR pszDescription = "Access denied. Attempted to open the file %1."