Identificateurs d’événements (journalisation des événements)

  • Article

Les identificateurs d’événement identifient un événement particulier de manière unique. Chaque source d’événement peut définir ses propres événements numérotés et les chaînes de description auxquelles ils sont mappés dans son fichier de message. Les observateurs d’événements peuvent présenter ces chaînes à l’utilisateur. Ils doivent aider l’utilisateur à comprendre ce qui s’est passé et suggérer les actions à prendre. Dirigez la description vers les utilisateurs qui résolvent leurs propres problèmes, et non vers les administrateurs ou les techniciens du support technique. Pour plus d’informations, consultez Instructions relatives aux messages d’erreur.

Format

Le diagramme suivant illustre le format d’un identificateur d’événement.

  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

la gravité. La gravité est définie comme suit :

00 - Réussite
01 - Information
10 - Avertissement
11 - Erreur

C

Bit client. Ce bit est défini comme suit :

0 - Code système
1 - Code client

R

Bit réservé.

Installation

Code de l’installation. Cette valeur peut être FACILITY_NULL.

Code

Code d’état de l’installation.

Définitions de message

Les messages sont définis dans le fichier de message d’événement. Les chaînes de description dans le fichier de message d’événement sont indexées par identificateur d’événement, ce qui permet observateur d'événements d’afficher du texte spécifique à l’événement pour n’importe quel événement en fonction de l’identificateur d’événement. Toutes les descriptions sont localisées et dépendent de la langue. Pour plus d’informations sur la création d’un fichier de message, consultez Fichiers texte de message.

Les chaînes de description peuvent contenir des espaces réservés de chaîne d’insertion, de la forme %n, où %1 indique la première chaîne d’insertion, etc. Par exemple, voici un exemple d’entrée dans le fichier .mc :

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

Dans ce cas, la mémoire tampon retournée par ReadEventLog contient des chaînes d’insertion. Le membre NumStrings de la structure EVENTLOGRECORD indique le nombre de chaînes d’insertion. Le membre StringOffset de la structure EVENTLOGRECORD indique l’emplacement de la première chaîne d’insertion dans la mémoire tampon. Vous pouvez passer un tableau de DWORD_PTRs qui pointent vers l’adresse de chaque chaîne dans la mémoire tampon lors de l’appel de la fonction FormatMessage et insérera les chaînes dans le message.

La chaîne de description peut également contenir des espaces réservés pour les chaînes de paramètres du fichier de message de paramètre. Les espaces réservés sont de la forme %%n, où %%1 est remplacé par la chaîne de paramètre avec l’identificateur 1, et ainsi de suite. Toutefois, il vous incombe d’insérer les chaînes de paramètres dans la chaîne de message retournée par FormatMessage . En règle générale, vous appelez FormatMessage pour obtenir la chaîne de message de l’événement. Vous analysez ensuite la chaîne de message pour les paramètres %%n . Si le message contient un ou plusieurs paramètres, chargez la valeur de Registre ParameterMessageFile pour la source. Pour chaque paramètre de la chaîne de message, obtenez l’identificateur et passez-le à FormatMessage pour obtenir la chaîne de paramètre. Remplacez le paramètre dans la chaîne de message par la chaîne de paramètre retournée par FormatMessage .

Chaînes d’insertion

Les chaînes d’insertion sont des chaînes facultatives indépendantes de la langue utilisées pour remplir des valeurs pour les espaces réservés dans les chaînes de description. Étant donné que les chaînes ne sont pas localisées, il est essentiel que ces espaces réservés soient utilisés uniquement pour représenter des chaînes indépendantes de la langue, telles que des valeurs numériques, des noms de fichiers, des noms d’utilisateur, etc. La longueur de chaîne ne doit pas dépasser 32 kilo-octets - 1 caractères.

Évitez d’utiliser plusieurs chaînes pour créer une description plus grande. Une chaîne d’insertion doit être traitée comme des données, et non comme du texte. Par exemple, dans l’exemple suivant, pszString1 et pszString2 ne doivent pas être utilisés comme chaînes d’insertion pour pszDescription.

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

Dans l’exemple suivant, il convient d’utiliser pszString1 ou pszString2 pour la chaîne d’insertion dans pszDescription.

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