Schreiben in das Systemereignisprotokoll
Fehler werden durch ihren NTSTATUS-Wert angegeben. Das System definiert bestimmte NTSTATUS-Werte, die von Treibern verwendet werden können, und Treiberschreiber können zusätzliche Fehler definieren. Beachten Sie, dass bei der Protokollierung von Fehlern nur bestimmte NTSTATUS-Werte verwendet werden können.
Jeder NTSTATUS-Wert, der beim Protokollieren von Fehlern verwendet werden kann, weist eine zugeordnete Fehlermeldung auf. Der Treiber für parallele Ports verwendet beispielsweise den NTSTATUS-Wert PAR_INTERRUPT_CONFLICT, um Hardwareunterbrechungskonflikte mit dem Meldungstext "Interruptkonflikt für %1 erkannt" darzustellen.
Die Ereignisanzeige zeigt den Meldungstext im Textfeld Beschreibung auf dem Eigenschaftenblatt des Protokolleintrags an. Wenn die Nachrichtentextzeichenfolge "%1" enthält, ersetzt die Ereignisanzeige sie durch den Namen des Geräts, das den Eintrag protokolliert hat. Der Nachrichtentext kann zusätzliche Parameter im Format "%2", "%3" usw. enthalten. Wenn der Treiber den Fehler protokolliert, kann er Zeichenfolgenwerte für diese Parameter bereitstellen. Diese Zeichenfolgenwerte werden als Einfügezeichenfolgen bezeichnet. Die Ereignisanzeige fügt sie automatisch anstelle der Prozentwerte ein.
Der Treiber kann auch Binärdaten in den Protokolleintrag einschließen, die als Dumpdaten bezeichnet werden. Die Ereignisanzeige zeigt die Sicherungsdaten im Textfeld Daten des Eigenschaftenblatts des Protokolleintrags an.
Sie können das Eigenschaftenblatt für einen Protokolleintrag aufrufen, indem Sie im Ereignisanzeige auf den Eintrag doppelklicken. Der folgende Screenshot zeigt ein Beispiel für ein Protokolleintragseigenschaftenblatt.
Treiber verwenden die IoAllocateErrorLogEntry-Routine , um einen Fehlerprotokolleintrag zuzuordnen. Protokolleinträge bestehen aus einem IO_ERROR_LOG_PACKET Header mit variabler Länge, gefolgt von Einfügezeichenfolgen.
Das folgende Diagramm zeigt das Layout eines Fehlerprotokolleintrags im Arbeitsspeicher.
Der ErrorCode-Member von IO_ERROR_LOG_PACKET gibt den NTSTATUS-Wert des Fehlers an. Das DumpData-Element gibt alle Sicherungsdaten für den Protokolleintrag an. DumpData ist ein Array mit variabler Größe, dessen Größe durch das DumpDataSize-Element angegeben wird. Treiber geben den Anfang der ersten Einfügezeichenfolge mit dem StringOffset-Element und die Anzahl der Zeichenfolgen im NumberOfStrings-Element an. Jede Einfügezeichenfolge selbst ist eine Unicode-Zeichenfolge mit Null-Beendigung.
Nachdem der Treiber den zugeordneten Fehlerprotokolleintrag ausgefüllt hat, schreibt er den Eintrag mithilfe von IoWriteErrorLogEntry in das Fehlerprotokoll. IoWriteErrorLogEntry gibt den für den Protokolleintrag zugewiesenen Arbeitsspeicher automatisch frei. Treiber können IoFreeErrorLogEntry verwenden, um nicht verwendete Protokolleinträge frei zu geben.
Vordefinierte Fehlercodes (in der Form IO_ERR_XXX) werden in der Headerdatei ntiologc.h definiert, die im Windows Driver Kit (WDK) enthalten ist. Die fehlermeldung, die jedem Fehlercode zugeordnet ist, finden Sie in den Kommentaren für ntiologc.h neben der Deklaration des Fehlercodes. Um einen vordefinierten Fehlercode zu verwenden, muss der Treiber die Systemdatei iologmsg.dll als Quelle der zugehörigen Fehlermeldungen registrieren. Weitere Informationen finden Sie unter Registrieren als Quelle von Fehlermeldungen.
Treiber können auch eigene benutzerdefinierte Fehlertypen und zugehörige Fehlermeldungen definieren. Weitere Informationen finden Sie unter Definieren benutzerdefinierter Fehlertypen.