Scrittura nel registro eventi di sistema

Gli errori vengono specificati dal valore NTSTATUS. Il sistema definisce valori NTSTATUS specifici che possono essere usati dai driver e i writer di driver possono definire errori aggiuntivi. Si noti che è possibile usare solo determinati valori NTSTATUS durante la registrazione degli errori.

Ogni valore NTSTATUS che può essere utilizzato durante la registrazione degli errori presenta un messaggio di errore associato. Ad esempio, il driver della porta parallela utilizza il valore NTSTATUS PAR_INTERRUPT_CONFLICT per rappresentare i conflitti di interrupt hardware, con il messaggio "Conflitto di interrupt rilevato per %1".

Nel Visualizzatore eventi viene visualizzato il testo del messaggio nella casella di testo Descrizione nella finestra delle proprietà della voce di log. Se la stringa di testo del messaggio contiene "%1", il Visualizzatore eventi lo sostituisce con il nome del dispositivo che ha registrato la voce. Il testo del messaggio può contenere parametri aggiuntivi del formato "%2", "%3" e così via. Quando il driver registra l'errore, può fornire valori stringa per tali parametri. Questi valori stringa sono noti come stringhe di inserimento . Il Visualizzatore eventi li inserisce automaticamente al posto dei valori di percentuale.

Il driver può includere anche dati binari nella voce di log, noti come dati di dump . Nel Visualizzatore eventi vengono visualizzati i dati di dump nella casella di testo Data della finestra delle proprietà della voce di log.

È possibile visualizzare la finestra delle proprietà per una voce di log facendo doppio clic sulla voce nel Visualizzatore eventi. La schermata seguente mostra una scheda delle proprietà di una voce di log di esempio.

I driver usano la routine IoAllocateErrorLogEntry per allocare una voce del log degli errori. Le voci di log sono costituite da un'intestazione di IO_ERROR_LOG_PACKET a lunghezza variabile, seguita da stringhe di inserimento.

Il diagramma seguente mostra il layout di una voce del registro degli errori in memoria.

Il membro ErrorCode di IO_ERROR_LOG_PACKET specifica il valore NTSTATUS dell'errore. Il membro DumpData specifica i dati di dump per la voce di log. DumpData è una matrice di dimensioni variabili, le cui dimensioni sono specificate dal membro DumpDataSize. I driver specificano l'inizio della prima stringa di inserimento con il membro StringOffset e il numero di stringhe nel membro NumeroDiStringhe. Ogni stringa di inserimento è una stringa Unicode con terminazione Null.

Dopo che il driver ha compilato l'entrata del log degli errori assegnata, scrive l'entrata nel log degli errori usando IoWriteErrorLogEntry. IoWriteErrorLogEntry libera automaticamente la memoria allocata per la voce di log. I driver possono usare IoFreeErrorLogEntry per liberare eventuali voci di log inutilizzate.

I codici di errore predefiniti (del modulo IO_ERR_XXX) sono definiti nel file di intestazione ntiologc.h incluso in Windows Driver Kit (WDK). Il messaggio di errore associato a ogni codice di errore è reperibile nei commenti per ntiologc.h, accanto alla dichiarazione del codice di errore. Per usare un codice di errore predefinito, il driver deve registrare il file di sistema, iologmsg.dll, come origine dei messaggi di errore associati. Per ulteriori informazioni, vedere Registrarsi come fonte dei messaggi di errore.

I driver possono anche definire i propri tipi di errore personalizzati e i messaggi di errore associati. Per altre informazioni, vedere Definizione di tipi di errore personalizzati.