Partager via

Définition de types d'erreurs personnalisés

  • Article

Les pilotes peuvent spécifier leurs propres types d’erreurs et messages d’erreur. Pour définir un message d’erreur personnalisé, vous devez d’abord définir une nouvelle valeur IO_ERR_XXX pour spécifier comme membre ErrorCode de l’entrée du journal des erreurs. L’Observateur d’événements utilise la valeur IO_ERR_XXX pour rechercher le message d’erreur du pilote.

Pour prendre en charge les messages d’erreur personnalisés dans votre pilote, procédez comme suit :

  1. Créez un fichier texte de message qui spécifie la valeur IO_ERR_XXX personnalisée et les messages d’erreur correspondants. Pour plus d’informations, consultez Création du fichier texte du message d’erreur.

  2. Compilez le fichier texte du message d’erreur dans une ressource et joignez la ressource à l’image du pilote. Pour plus d’informations, consultez Compilation du fichier texte du message d’erreur.

  3. Inscrivez l’image du pilote comme contenant des messages d’erreur. Pour plus d’informations, consultez Inscription en tant que source de messages d’erreur.

Création du fichier texte du message d’erreur

La définition des valeurs personnalisées IO_ERR_XXX d’un pilote et des modèles de message d’erreur correspondants sont attachées en tant que ressource de table de messages à l’image du pilote. Vous pouvez décrire les messages d’un pilote dans un fichier texte de message (qui a une extension de nom de fichier .mc).

Un fichier texte de message se compose de deux sections : une section d’en-tête et une section de message. La section d’en-tête autorise la déclaration de noms symboliques pour les valeurs numériques, tandis que la section de message spécifie les valeurs IO_ERR_XXX et les modèles de message d’erreur correspondants.

Pour obtenir un exemple de fichier texte de message, consultez le fichier Serlog.mc dans l’exemple de pilote série disponible sur GitHub.

Section d'en-tête

La section d’en-tête doit contenir cette ligne :

MessageIdTypedef=NTSTATUS

Cela garantit que le type de valeurs IO_ERR_XXX générées par le compilateur de messages est déclaré comme NTSTATUS.

Les autres directives qui apparaissent dans la section d’en-tête définissent des valeurs symboliques utilisées à la place de valeurs numériques dans la section du message.

Les directives SeverityNames et FacilityNames définissent des valeurs symboliques pour les champs de gravité et d’installation des valeurs NTSTATUS. Les directives sont du mot clé de formulaire = ( valeurs ), où les valeurs se composent d’une ou plusieurs instructions de la valeur de nom = de formulaire : header_name, séparées par des espaces blancs. Le paramètre de nom est le nom que vous utilisez pour spécifier la valeur numérique dans le fichier texte du message, tandis que le header_name est le nom de cette valeur déclarée dans le fichier d’en-tête C généré par le compilateur de messages. La clause : header_name est facultative.

Voici un exemple de déclaration d’en-tête de noms symboliques pour les codes de gravité :

SeverityNames = (
  Success       = 0x0:STATUS_SEVERITY_SUCCESS
  Informational = 0x1:STATUS_SEVERITY_INFORMATIONAL
  Warning       = 0x2:STATUS_SEVERITY_WARNING
  Error         = 0x3:STATUS_SEVERITY_ERROR
)

La directive LanguageNames définit des valeurs symboliques pour les ID de paramètres régionaux (LCID). La directive est de la forme LanguageNames = ( valeurs ), où les valeurs se composent d’une ou plusieurs instructions du formulaire language_name = lcid : langfile, séparées par des espaces blancs. Le paramètre language_name est le nom que vous utilisez à la place du lcid dans le fichier texte du message, tandis que le nom de fichier spécifie un nom de fichier unique (sans extension). Lorsque le compilateur de messages génère le script de ressource à partir du fichier texte du message, il stocke toutes les ressources de chaîne pour cette langue dans un fichier nommé langfile.bin.

Message Section

Chaque définition de message commence par la définition de la valeur IO_ERR_XXX personnalisée utilisée par le pilote pour signaler ce type d’erreur particulier. La valeur IO_ERR_XXX est définie par une série de paires de valeurs de mot clé = . Les mots clés possibles et leur signification sont les suivants.

Mot clé Valeur

MessageId

Champ de code de la nouvelle valeur IO_ERR_XXX .

Niveau de gravité

Champ Gravité de la nouvelle valeur IO_ERR_XXX . La valeur spécifiée doit être l’un des noms symboliques définis par la directive d’en-tête SeverityNames .

Installation

Champ d’installation de la nouvelle valeur IO_ERR_XXX . La valeur spécifiée doit être l’un des noms symboliques définis par la directive d’en-tête FacilityNames .

SymbolicName

Nom symbolique de la nouvelle valeur IO_ERR_XXX . Le compilateur de messages génère un fichier d’en-tête C qui contient une déclaration #define du nom comme valeur NTSTATUS correspondante. Le pilote utilise ce nom lors de la spécification du type d’erreur.

Le premier mot clé doit toujours être MessageId.

Le reste de la définition du message se compose d’une ou plusieurs versions localisées du message d’erreur. Chaque version est de la forme suivante :

Language=language_name
localized_message

La valeur language_name , qui doit être l’un des noms symboliques définis par la directive d’en-tête LanguageNames , spécifie la langue du texte du message. Le texte du message localisé se compose d’une chaîne Unicode. Toutes les chaînes incorporées de la forme « %n » sont traitées comme des modèles que l’Observateur d’événements remplacera lorsque l’erreur est enregistrée. La chaîne « %1 » est remplacée par le nom de l’objet de périphérique du pilote, tandis que « %2 » à « %n » sont remplacées par toutes les chaînes d’insertion fournies par le pilote.

La définition du message est arrêtée par une seule période sur une ligne.

Si vous définissez des messages d’erreur personnalisés, vous ne devez pas utiliser de chaînes d’insertion, sauf si nécessaire. Les chaînes d’insertion ne peuvent pas être localisées. Elles doivent donc être utilisées pour les chaînes indépendantes de la langue, telles que les nombres ou les noms de fichiers. La plupart des pilotes n’utilisent pas de chaînes d’insertion.

Compilation du fichier texte du message d’erreur

Utilisez le compilateur de messages (mc.exe) pour compiler votre fichier texte de message dans un fichier de script de ressources (qui a une extension de nom de fichier .rc). Commande du formulaire

mc filename.mc

provoque la génération des fichiers suivants par le compilateur de messages :

  • filename.h, fichier d’en-tête qui contient des déclarations de chaque valeur IO_ERR_XXX personnalisée dans le nom de fichier.mc.

  • filename.rc, un script de ressource.

  • Un fichier pour chaque langue qui apparaît dans le fichier texte du message. Chacun de ces fichiers stocke toutes les ressources de chaîne de message d’erreur pour une langue. Le fichier de chaque langue est nommé langfile.bin, où langfile est la valeur spécifiée pour la langue dans la directive LanguageNames du fichier texte du message.

Vous trouverez plus d’informations sur le compilateur de messages dans le Kit de développement logiciel (SDK) Microsoft Windows.

Le compilateur de ressources convertit un script de ressource en fichier de ressources que vous pouvez attacher à votre image de pilote. Si vous utilisez l’utilitaire build pour générer votre pilote, vous pouvez vous assurer que le script de ressource est converti en fichier de ressources et attaché à votre image de pilote simplement en incluant le nom du script de ressource dans la variable SOURCES pour le pilote. Pour plus d’informations sur le compilateur de ressources, consultez la documentation du Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur l’utilisation de l’utilitaire build pour générer votre pilote, consultez Génération d’un pilote.