structure IO_ERROR_LOG_PACKET (wdm.h)

Article
02/27/2024

La structure IO_ERROR_LOG_PACKET sert d’en-tête pour une entrée de journal des erreurs.

Syntaxe

typedef struct _IO_ERROR_LOG_PACKET {
  UCHAR         MajorFunctionCode;
  UCHAR         RetryCount;
  USHORT        DumpDataSize;
  USHORT        NumberOfStrings;
  USHORT        StringOffset;
  USHORT        EventCategory;
  NTSTATUS      ErrorCode;
  ULONG         UniqueErrorValue;
  NTSTATUS      FinalStatus;
  ULONG         SequenceNumber;
  ULONG         IoControlCode;
  LARGE_INTEGER DeviceOffset;
  ULONG         DumpData[1];
} IO_ERROR_LOG_PACKET, *PIO_ERROR_LOG_PACKET;

Membres

MajorFunctionCode

Indique le code de fonction principale IRP_MJ_XXX de l’IRP que le pilote gérait lorsque l’erreur s’est produite. La définition de cette valeur est facultative.

RetryCount

Indique le nombre de fois où le pilote a retenté l’opération et rencontré cette erreur. Utilisez zéro pour indiquer que le pilote a tenté l’opération une fois, ou ajoutez-en une pour chaque nouvelle tentative au-delà de la tentative initiale.

DumpDataSize

Indique la taille, en octets, du membre DumpData de longueur variable de cette structure. La valeur spécifiée doit être un multiple de sizeof(ULONG).

NumberOfStrings

Indique le nombre de chaînes d’insertion que le pilote fournira avec cette entrée de journal des erreurs. Les pilotes définissent cette valeur sur zéro pour les erreurs qui n’ont pas besoin de chaînes d’insertion. Le observateur d'événements utilise ces chaînes pour remplir les entrées « %2 » à « %n » dans le modèle de chaîne pour ce code d’erreur.

Les chaînes Unicode terminées par null suivent elles-mêmes la structure IO_ERROR_LOG_PACKET en mémoire.

StringOffset

Indique le décalage, en octets, à partir du début de la structure, auquel commencent les données de chaîne d’insertion fournies par le pilote. Normalement, il s’agit de sizeof(IO_ERROR_LOG_PACKET) plus la valeur du membre DumpDataSize . S’il n’existe aucune chaîne d’insertion fournie par le pilote, StringOffset peut être égal à zéro.

EventCategory

Spécifie la catégorie d’événement pour l’erreur. Un pilote spécifie les catégories d’événements qu’il prend en charge et les chaînes descriptives correspondantes dans son catalogue de messages. Le observateur d'événements affiche la chaîne descriptive comme valeur Category pour l’erreur.

ErrorCode

Spécifie le type d’erreur. Le observateur d'événements utilise le code d’erreur pour déterminer la chaîne à afficher comme valeur Description de l’erreur. Le observateur d'événements prend le modèle de chaîne pour l’erreur fournie dans le catalogue de messages du pilote, remplace « %1 » dans le modèle par le nom de l’objet d’appareil du pilote et remplace « %2 » à « %n » par les chaînes d’insertion fournies avec l’entrée du journal des erreurs.

ErrorCode est une constante définie par le système ou par le pilote ; Pour plus d’informations, consultez Erreurs de journalisation .

UniqueErrorValue

Valeur spécifique au pilote qui indique où l’erreur a été détectée dans le pilote. La définition de cette valeur est facultative.

FinalStatus

Spécifie la valeur NTSTATUS à retourner pour l’opération qui a déclenché l’erreur. La définition de cette valeur est facultative.

SequenceNumber

Spécifie un numéro de séquence attribué par le pilote pour l’IRP actuel, qui doit être constant pendant la durée d’une requête donnée. La définition de cette valeur est facultative.

IoControlCode

Pour un IRP_MJ_DEVICE_CONTROL ou IRP_MJ_INTERNAL_DEVICE_CONTROL IRP, ce membre spécifie le code de contrôle d’E/S pour la demande qui a trié l’erreur. Sinon, cette valeur est égale à zéro. La définition de cette valeur est facultative.

DeviceOffset

Spécifie le décalage spécifié par le pilote dans l’appareil où l’erreur s’est produite. La définition de cette valeur est facultative.

DumpData[1]

Tableau de taille variable qui peut être utilisé pour stocker des données binaires spécifiques au pilote, telles que des valeurs de registre ou toute autre information utile pour identifier la cause de l’erreur. Les pilotes doivent spécifier la taille, en octets, du tableau dans le membre DumpDataSize de cette structure.

Remarques

Les pilotes utilisent la routine IoAllocateErrorLogEntry pour allouer une entrée de journal des erreurs. La structure IO_ERROR_LOG_PACKET sert d’en-tête pour la mémoire tampon retournée. Il est suivi en mémoire de toutes les chaînes d’insertion pour l’entrée de journal.

Notez que le gestionnaire d’E/S lui-même insère certaines informations dans le journal des erreurs système, telles que le nom du périphérique et du pilote. Le gestionnaire d’E/S réserve 80 octets pour contenir ces informations. Si la taille de ces informations dépasse 80 octets, le gestionnaire d’E/S tronque les chaînes d’insertion du pilote si nécessaire.

Pour plus d’informations sur l’utilisation de cette structure, consultez Erreurs de journalisation.