Identificadores de evento (log de eventos)

Os identificadores de evento identificam exclusivamente um evento específico. Cada origem do evento pode definir seus próprios eventos numerados e as cadeias de caracteres de descrição para as quais eles são mapeados em seu arquivo de mensagem. Os visualizadores de eventos podem apresentar essas cadeias de caracteres ao usuário. Eles devem ajudar o usuário a entender o que deu errado e sugerir quais ações devem ser tomadas. Direcione a descrição para os usuários que resolvem seus próprios problemas, não em administradores ou técnicos de suporte. Para obter mais informações, consulte Diretrizes de mensagem de erro.

Formatar

O diagrama a seguir ilustra o formato de um identificador de evento.

  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

Gravidade. A gravidade é definida da seguinte maneira:

00 - Sucesso

01 – Informativo

10 – Aviso

11 – Erro

C

Bit do cliente. Esse bit é definido da seguinte maneira:

0 – Código do sistema

1 – Código do cliente

R

Bit reservado.

Instalação

Código da instalação. Esse valor pode ser FACILITY_NULL.

Código

Código de status para a instalação.

Definições de mensagem

As mensagens são definidas no arquivo de mensagem de evento. As cadeias de caracteres de descrição no arquivo de mensagem de evento são indexadas pelo identificador de evento, permitindo que Visualizador de Eventos exibam texto específico do evento para qualquer evento com base no identificador de evento. Todas as descrições são localizadas e dependem do idioma. Para obter mais informações sobre como criar um arquivo de mensagem, consulte Arquivos de texto de mensagem.

As cadeias de caracteres de descrição podem conter espaços reservados de cadeia de caracteres de inserção, do formulário %n, em que %1 indica a primeira cadeia de caracteres de inserção e assim por diante. Por exemplo, o seguinte é uma entrada de exemplo no arquivo .mc:

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

Nesse caso, o buffer retornado por ReadEventLog contém cadeias de caracteres de inserção. O membro NumStrings da estrutura EVENTLOGRECORD indica o número de cadeias de caracteres de inserção. O membro StringOffset da estrutura EVENTLOGRECORD indica o local da primeira cadeia de caracteres de inserção no buffer. Você pode passar uma matriz de DWORD_PTRs que apontam para o endereço de cada cadeia de caracteres no buffer ao chamar a função FormatMessage e ela inserirá as cadeias de caracteres na mensagem.

A cadeia de caracteres de descrição também pode conter espaços reservados para cadeias de caracteres de parâmetro do arquivo de mensagem de parâmetro. Os espaços reservados são do formato %%n, em que %%1 é substituído pela cadeia de caracteres de parâmetro pelo identificador de 1 e assim por diante. No entanto, cabe a você inserir as cadeias de caracteres de parâmetro na cadeia de caracteres de mensagem retornada por FormatMessage . Normalmente, você chama FormatMessage para obter a cadeia de caracteres de mensagem para o evento. Em seguida, analise a cadeia de caracteres de mensagem para parâmetros %%n . Se a mensagem contiver um ou mais parâmetros, carregue o valor do Registro ParameterMessageFile para a origem. Para cada parâmetro na cadeia de caracteres de mensagem, obtenha o identificador e passe-o para FormatMessage para obter a cadeia de caracteres de parâmetro. Substitua o parâmetro na cadeia de caracteres de mensagem pela cadeia de caracteres de parâmetro que FormatMessage retornou.

Cadeias de caracteres de inserção

Cadeias de caracteres de inserção são cadeias de caracteres opcionais independentes de idioma usadas para preencher valores para espaços reservados em cadeias de caracteres de descrição. Como as cadeias de caracteres não são localizadas, é fundamental que esses espaços reservados sejam usados apenas para representar cadeias de caracteres independentes de idioma, como valores numéricos, nomes de arquivo, nomes de usuário e assim por diante. O comprimento da cadeia de caracteres não deve exceder 32 quilobytes – 1 caractere.

Evite usar várias cadeias de caracteres para criar uma descrição maior. Uma cadeia de caracteres de inserção deve ser tratada como dados, não como texto. Por exemplo, no exemplo a seguir, pszString1 e pszString2 não devem ser usados como cadeias de caracteres de inserção para pszDescription.

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

No exemplo a seguir, é apropriado usar pszString1 ou pszString2 para a cadeia de caracteres de inserção em pszDescription.

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