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

Les identificateurs d’événements identifient de manière unique un événement particulier. Chaque source d’événement peut définir ses propres événements numérotés et les chaînes de description auxquelles elles sont mappées dans son fichier de message. Les visionneuses d’événements peuvent présenter ces chaînes à l’utilisateur. Ils doivent aider l’utilisateur à comprendre ce qui a été incorrect et suggérer les actions à entreprendre. Dirigez la description des utilisateurs qui résolvent leurs propres problèmes, et non aux administrateurs ou aux techniciens de support. 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 d’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 messages d’événement. Les chaînes de description du 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épendantes 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, et ainsi de suite. 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 pointe vers l’adresse de chaque chaîne de 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 à partir 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 par l’identificateur de 1, et ainsi de suite. Toutefois, il vous suffit d’insérer les chaînes de paramètre 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 transmettez-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 du langage 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 du langage, 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 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 est approprié 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."