Definizione di tipi di errore personalizzati

I driver possono specificare i propri tipi di errore e i messaggi di errore. Per definire un messaggio di errore personalizzato, è necessario innanzitutto definire un nuovo valore IO_ERR_XXX per specificare come membro ErrorCode della voce del log degli errori. Il Visualizzatore eventi usa il valore IO_ERR_XXX per cercare il messaggio di errore del driver.

Per supportare messaggi di errore personalizzati nel driver, seguire questa procedura:

1. Creare un file di testo del messaggio che specifica il valore personalizzato IO_ERR_XXX e i messaggi di errore corrispondenti. Per altre informazioni, vedere Creazione del file di testo del messaggio di errore.

2. Compilare il file di testo del messaggio di errore in una risorsa e allegare la risorsa all'immagine del driver. Per altre informazioni, vedere Compilazione del file di testo del messaggio di errore.

3. Registrare l'immagine del driver come contenente i messaggi di errore. Per altre informazioni, vedere Registrazione come origine dei messaggi di errore.

Creazione del file di testo del messaggio di errore

La definizione dei valori personalizzati di un driver IO_ERR_XXX e i modelli di messaggio di errore corrispondenti vengono associati come risorsa di tabella messaggi all'immagine del driver. È possibile descrivere i messaggi per un driver in un file di testo del messaggio (con estensione mc).

Un file di testo del messaggio è costituito da due sezioni: una sezione di intestazione e una sezione del messaggio. La sezione intestazione consente la dichiarazione dei nomi simbolici per i valori numerici, mentre la sezione del messaggio specifica i valori IO_ERR_XXX e i modelli di messaggio di errore corrispondenti.

Per un esempio di file di testo del messaggio, vedere il file Serlog.mc nell'esempio di driver seriale disponibile in GitHub.

Sezione di intestazione

La sezione intestazione deve contenere questa riga:

MessageIdTypedef=NTSTATUS

In questo modo si garantisce che il tipo di valori IO_ERR_XXX generati dal compilatore di messaggi sia dichiarato NTSTATUS.

Le altre direttive visualizzate nella sezione intestazione definiscono i valori simbolici usati al posto dei valori numerici nella sezione messaggio.

Le direttive SeverityNames e FacilityNames definiscono valori simbolici per i campi gravità e struttura dei valori NTSTATUS. Le direttive sono della parola chiave form = ( valori ), dove i valori sono costituiti da una o più istruzioni del valore del nome = modulo : header_name, separati da spazi vuoti. Il parametro name è il nome usato per specificare il valore numerico nel file di testo del messaggio, mentre il header_name è il nome di questo valore dichiarato nel file di intestazione C generato dal compilatore di messaggi. La clausola : header_name è facoltativa.

Di seguito è riportato un esempio di dichiarazione di intestazione di nomi simbolici per i codici di gravità:

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

La direttiva LanguageNames definisce i valori simbolici per gli ID delle impostazioni locali (LCID). La direttiva è del formato LanguageNames = ( valori ), dove i valori sono costituiti da una o più istruzioni del formato language_name = lcid : langfile, separati da spazi vuoti. Il parametro language_name è il nome usato al posto di lcid nel file di testo del messaggio, mentre il nome file specifica un nome file univoco (senza estensione). Quando il compilatore di messaggi genera lo script di risorsa dal file di testo del messaggio, archivia tutte le risorse stringa per questa lingua in un file denominato langfile.bin.

Sezione Message

Ogni definizione di messaggio inizia con la definizione del valore personalizzato IO_ERR_XXX usato dal driver per segnalare questo particolare tipo di errore. Il valore IO_ERR_XXX è definito da una serie di coppie di valori di parola chiave = . Le possibili parole chiave e il loro significato sono le seguenti.

Parola chiave	Valore
MessageId	Campo codice del nuovo valore IO_ERR_XXX .
Gravità	Campo Gravità del nuovo valore IO_ERR_XXX . Il valore specificato deve essere uno dei nomi simbolici definiti dalla direttiva di intestazione SeverityNames .
Struttura	Campo struttura del nuovo valore IO_ERR_XXX . Il valore specificato deve essere uno dei nomi simbolici definiti dalla direttiva di intestazione FacilityNames .
SymbolicName	Nome simbolico per il nuovo valore IO_ERR_XXX . Il compilatore di messaggi genera un file di intestazione C che contiene una dichiarazione #define del nome come valore NTSTATUS corrispondente. Il driver usa tale nome quando si specifica il tipo di errore.

La prima parola chiave deve essere sempre MessageId.

Il resto della definizione del messaggio è costituito da una o più versioni localizzate del messaggio di errore. Ogni versione è del formato:

Language=language_name
localized_message

Il valore language_name , che deve essere uno dei nomi simbolici definiti dalla direttiva di intestazione LanguageNames , specifica la lingua del testo del messaggio. Il testo localizzato del messaggio è costituito da una stringa Unicode. Tutte le stringhe incorporate del formato "%n" verranno considerate come modelli che verranno sostituiti dal Visualizzatore eventi quando viene registrato l'errore. La stringa "%1" viene sostituita con il nome dell'oggetto dispositivo del driver, mentre "%2" e "%n" vengono sostituite con tutte le stringhe di inserimento fornite dal driver.

La definizione del messaggio viene terminata da un singolo punto solo su una riga.

Se si definiscono messaggi di errore personalizzati, non è consigliabile usare stringhe di inserimento, a meno che non sia necessario. Le stringhe di inserimento non possono essere localizzate, pertanto devono essere usate per stringhe indipendenti dalla lingua, ad esempio numeri o nomi di file. La maggior parte dei driver non usa stringhe di inserimento.

Compilazione del file di testo del messaggio di errore

Usare il compilatore di messaggi (mc.exe) per compilare il file di testo del messaggio in un file script di risorse (con estensione rc). Comando del modulo

mc filename.mc

fa sì che il compilatore di messaggi generi i file seguenti:

• filename.h, un file di intestazione che contiene dichiarazioni di ogni valore personalizzato IO_ERR_XXX nel nome file.mc.

• filename.rc, uno script di risorsa.

• Un file per ogni lingua visualizzata nel file di testo del messaggio. Ognuno di questi file archivia tutte le risorse stringa del messaggio di errore per una lingua. Il file per ogni lingua è denominato langfile.bin, dove langfile è il valore specificato per la lingua nella direttiva LanguageNames del file di testo del messaggio.

Altre informazioni sul compilatore di messaggi sono disponibili in Microsoft Windows SDK.

Il compilatore di risorse converte uno script di risorsa in un file di risorse che è possibile collegare all'immagine del driver. Se si usa l'utilità di compilazione per compilare il driver, è possibile assicurarsi che lo script della risorsa venga convertito in un file di risorse e collegato all'immagine del driver semplicemente includendo il nome dello script di risorsa nella variabile SOURCES per il driver. Per altre informazioni sul compilatore di risorse, vedere la documentazione di Windows SDK. Per informazioni sull'uso dell'utilità di compilazione per compilare il driver, vedere Compilazione di un driver.