Definiera anpassade feltyper

Drivrutiner kan ange sina egna feltyper och felmeddelanden. Om du vill definiera ett anpassat felmeddelande måste du först definiera ett nytt IO_ERR_XXX-värde som ska anges som medlemmen ErrorCode i felloggposten. Händelseloggaren använder värdet IO_ERR_XXX för att slå upp drivrutinens felmeddelande.

Följ dessa steg för att stödja anpassade felmeddelanden i drivrutinen:

1. Skapa en meddelandetextfil som anger det anpassade IO_ERR_XXX-värdet och motsvarande felmeddelanden. Mer information finns i Skapa textfilen för felmeddelande.

2. Kompilera textfilen för felmeddelandet till en resurs och koppla resursen till drivrutinsbilden. Mer information finns i Kompilera textfilen för felmeddelanden.

3. Registrera drivrutinsbilden som innehåller felmeddelanden. Mer information finns i Registrera som en källa för felmeddelanden.

Skapa textfilen för felmeddelandet

Definitionen av en drivrutins anpassade IO_ERR_XXX-värden och matchande mallar för felmeddelanden bifogas som en meddelandetabellresurs till drivrutinsbilden. Du kan beskriva meddelandena för en drivrutin i en meddelandetextfil (som har filnamnstillägget .mc).

En meddelandetextfil består av två avsnitt: ett rubrikavsnitt och ett meddelandeavsnitt. Rubrikavsnittet tillåter deklaration av symboliska namn för numeriska värden, medan meddelandeavsnittet anger IO_ERR_XXX-värden och matchande mallar för felmeddelanden.

Ett exempel på en meddelandetextfil finns i filen Serlog.mc i exemplet på seriedrivrutiner som är tillgängligt på GitHub.

Rubrikavsnitt

Rubrikavsnittet måste innehålla den här raden:

MessageIdTypedef=NTSTATUS

Detta säkerställer att typen av IO_ERR_XXX-värden som genereras av meddelandekompilatorn deklareras som NTSTATUS.

De andra direktiven som visas i rubrikavsnittet definierar symboliska värden som används i stället för numeriska värden i meddelandeavsnittet.

I direktiven SeverityNames och FacilityNames definieras symboliska värden för allvarlighetsgrads- och anläggningsfälten för NTSTATUS-värden. Direktiven är av formuläret keyword= (values), där värden består av en eller flera instruktioner av formulärets namnvärde=:header_name, avgränsade med blanksteg. Namnparametern är det namn som du använder för att ange det numeriska värdet i meddelandetextfilen, medan header_name är namnet på det här värdet som deklareras i C-huvudfilen som genereras av meddelandekompilatorn. Satsen :header_name är valfri.

Här är ett exempel på en rubrikdeklaration med symboliska namn för allvarlighetsgradskoder:

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

LanguageNames-direktivet definierar symboliska värden för språk-ID(LCID). Direktivet är av formatet LanguageNames = (values), där värden består av en eller flera instruktioner i formuläret language_name=lcid:langfile, avgränsade med blanksteg. Parametern language_name är det namn som du använder i stället för lcid i meddelandetextfilen, medan filnamnet anger ett unikt filnamn (utan tillägg). När meddelandekompilatorn genererar resursskriptet från meddelandetextfilen lagrar den alla strängresurser för det här språket i en fil med namnet langfile. bin.

Meddelandeavsnitt

Varje meddelandedefinition börjar med definitionen av det anpassade IO_ERR_XXX-värdet som drivrutinen använder för att rapportera den här typen av fel. Värdet IO_ERR_XXX definieras av en serienyckelordsvärdepar = . De möjliga nyckelorden och deras betydelse är följande.

Nyckelord	Värde
MessageId	Kodfält för det nya IO_ERR_XXX-värdet .
allvarlighetsgrad	Allvarlighetsgrad för det nya IO_ERR_XXX-värdet. Det angivna värdet måste vara ett av de symboliska namn som definieras av huvuddirektivet SeverityNames .
Anläggning	Anläggningsfältet för det nya värdet IO_ERR_XXX. Det angivna värdet måste vara ett av de symboliska namn som definieras av FacilityNames-huvuddirektivet .
Symboliskt namn	Det symboliska namnet på det nya IO_ERR_XXX-värdet . Meddelandekompilatorn genererar en C-huvudfil som innehåller en #define deklaration av namnet som motsvarande NTSTATUS-värde. Drivrutinen använder det namnet när den specificerar feltypen.

Det första nyckelordet måste alltid vara MessageId.

Resten av meddelandedefinitionen består av en eller flera lokaliserade versioner av felmeddelandet. Varje version är av typen

Language=language_name
localized_message

Värdet language_name , som måste vara ett av de symboliska namn som definieras av languageNames-huvuddirektivet , anger språket i meddelandetexten. Den lokaliserade meddelandetexten består av en Unicode-sträng. Inbäddade strängar i formuläret "%n" behandlas som mallar som Händelsevisaren ersätter när felet loggas. Strängen "%1" ersätts med namnet på drivrutinens enhetsobjekt, medan "%2" via "%n" ersätts med eventuella insättningssträngar som tillhandahålls av drivrutinen.

Meddelandedefinitionen avslutas enbart med en enskild punkt på en rad.

Om du definierar anpassade felmeddelanden bör du inte använda insättningssträngar om det inte behövs. Infogningssträngar kan inte lokaliseras, så de bör användas för strängar som är språkoberoende, till exempel siffror eller filnamn. De flesta drivrutiner använder inte insättningssträngar.

Kompilera textfilen för felmeddelande

Använd meddelandekompileraren (mc.exe) för att kompilera meddelandetextfilen till en resursskriptfil (som har filnamnstillägget .rc). Ett kommando i formuläret

mc filename.mc

gör att meddelandekompilatorn genererar följande filer:

• filename.h, en rubrikfil som innehåller deklarationer av varje anpassat IO_ERR_XXX-värde i filnamnet. mc.

• filename.rc, ett resursskript.

• En fil för varje språk som visas i meddelandetextfilen. Var och en av dessa filer lagrar alla resurser för felmeddelandesträngen för ett språk. Filen för varje språk heter langfile. bin, där langfile är det värde som anges för språket i meddelandetextfilens LanguageNames-direktiv .

Mer information om meddelandekompilatorn finns i Microsoft Windows SDK.

Resurskompilatorn konverterar ett resursskript till en resursfil som du kan koppla till drivrutinsbilden. Om du använder verktyget Build för att skapa drivrutinen kan du se till att resursskriptet konverteras till en resursfil och kopplas till drivrutinsbilden genom att bara inkludera namnet på resursskriptet i variabeln SOURCES för drivrutinen. Mer information om resurskompileraren finns i Windows SDK-dokumentationen. Information om hur du använder build-verktyget för att skapa drivrutinen finns i Skapa en drivrutin.