Definování vlastních typů chyb

Řidiči mohou specifikovat své vlastní typy chyb a chybové zprávy. Chcete-li definovat vlastní chybovou zprávu, musíte nejprve definovat novou hodnotu IO_ERR_XXX, která se má zadat jako ErrorCode člen položky protokolu chyb. Prohlížeč událostí používá hodnotu IO_ERR_XXX k vyhledání chybové zprávy ovladače.

Pokud chcete podporovat vlastní chybové zprávy v ovladači, postupujte takto:

1. Vytvořte textový soubor zprávy, který určuje vlastní hodnotu IO_ERR_XXX a odpovídající chybové zprávy. Další informace naleznete v tématu Vytvoření textového souboru chybové zprávy.

2. Kompilujte textový soubor chybové zprávy do samostatného prostředku a připojte ho k obrazu ovladače. Další informace najdete v tématu Kompilace textového souboru chybové zprávy.

3. Zaregistrujte image ovladače jako obsahující chybové zprávy. Další informace najdete v tématu Registrace jako zdroje chybových zpráv.

Vytvoření textového souboru chybové zprávy

Definice vlastních hodnot IO_ERR_XXX ovladače a odpovídající šablony chybových zpráv jsou připojeny k obrazu ovladače jako prostředek tabulky zpráv. Zprávy ovladače můžete popsat v textovém souboru zprávy (který má příponu názvu souboru .mc).

Textový soubor zprávy se skládá ze dvou částí: oddíl záhlaví a oddíl zprávy. Oddíl záhlaví umožňuje deklaraci symbolických názvů číselných hodnot, zatímco oddíl zprávy určuje IO_ERR_XXX hodnoty a odpovídající šablony chybových zpráv.

Příklad textového souboru zprávy najdete v Serlog.mc souboru v ukázce sériového ovladače dostupné na GitHubu.

Oddíl záhlaví

Oddíl záhlaví musí obsahovat tento řádek:

MessageIdTypedef=NTSTATUS

Tím se zajistí, že typ IO_ERR_XXX hodnot vygenerovaných kompilátorem zpráv je deklarován jako NTSTATUS.

Ostatní direktivy, které se zobrazí v oddílu záhlaví, definují symbolické hodnoty, které se používají místo číselných hodnot v oddílu zprávy.

Direktivy SeverityNames a FacilityNames definují symbolické hodnoty pro pole závažnosti a pole zařízení hodnot NTSTATUS. Direktivy jsou ve formě klíčové slovo= (hodnoty), kde hodnoty se skládají z jednoho nebo více příkazů formy název=hodnota:header_name, oddělené mezerami. Parametr název je název, který použijete k zadání číselné hodnoty v textovém souboru zprávy, zatímco header_name je název této hodnoty deklarovaný v souboru záhlaví jazyka C vygenerovaném kompilátorem zpráv. Klauzule :header_name je nepovinná.

Tady je příklad deklarace záhlaví symbolických názvů pro kódy závažnosti:

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

Direktiva LanguageNames definuje symbolické hodnoty pro ID národního prostředí (LCID). Direktiva je ve formátu LanguageNames = (hodnoty), kde hodnoty se skládá z jednoho nebo více příkazů ve formátu language_name=lcid:langfile, oddělené mezerou. Parametr language_name je název, který použijete místo lcid v textovém souboru zprávy, zatímco název souboru určuje jedinečný název souboru (bez přípony). Když kompilátor zpráv vygeneruje skript prostředku z textového souboru zprávy, uloží všechny řetězcové prostředky pro tento jazyk do souboru s názvem langfile.bin.

Oddíl zprávy

Každá definice zprávy začíná definicí vlastní hodnoty IO_ERR_XXX, kterou ovladač používá k hlášení tohoto konkrétního typu chyby. Hodnota IO_ERR_XXX je definována řadou klíčových slov = párů hodnot. Možná klíčová slova a jejich význam jsou následující.

Klíčové slovo	Hodnota
IdentifikátorZprávy	Pole kódu nové hodnoty IO_ERR_XXX.
Závažnost	Pole závažnosti nové hodnoty IO_ERR_XXX Zadaná hodnota musí být jedním z symbolických názvů definovaných direktivou SeverityNames header.
Zařízení	Pole zařízení nové hodnoty IO_ERR_XXX. Zadaná hodnota musí být jedním z symbolických názvů definovaných direktivou FacilityNames header.
symbolický název	Symbolický název nové hodnoty IO_ERR_XXX. Kompilátor zpráv vygeneruje soubor hlaviček jazyka C, který obsahuje #define deklaraci názvu jako odpovídající hodnotu NTSTATUS. Ovladač používá tento název při zadávání typu chyby.

První klíčové slovo musí být vždy MessageId.

Zbytek definice zprávy se skládá z jedné nebo více lokalizovaných verzí chybové zprávy. Každá verze je ve tvaru:

Language=language_name
localized_message

Hodnota language_name, která musí být jedním z symbolických názvů definovaných direktivou LanguageNames header, určuje jazyk textu zprávy. Lokalizovaný text zprávy se skládá z řetězce Unicode. Všechny vložené řetězce formuláře "%n" budou považovány za šablony, které prohlížeč událostí nahradí při zaprotokolování chyby. Řetězec "%1" je nahrazen názvem objektu zařízení ovladače, zatímco "%2" až "%n" jsou nahrazeny všemi vloženými řetězci, které poskytuje ovladač.

Definice zprávy je ukončena jedinou tečkou na řádku.

Pokud definujete vlastní chybové zprávy, neměli byste používat vložené řetězce, pokud to není nutné. Řetězce vložení nelze lokalizovat, takže by se měly používat pro řetězce, které jsou nezávislé na jazyce, jako jsou čísla nebo názvy souborů. Většina ovladačů nepoužívá vkládací řetězce.

Sestavení textového souboru chybových zpráv

Pomocí kompilátoru zpráv (mc.exe) zkompilujte textový soubor zprávy do souboru skriptu prostředku (který má příponu názvu souboru .rc). Příkaz formuláře

mc filename.mc

způsobí, že kompilátor zpráv vygeneruje následující soubory:

• soubor.h, hlavičkový soubor, který obsahuje deklarace každé vlastní hodnoty IO_ERR_XXX v souboru .mc.

• název souboru.rc, skript zdrojů.

• Jeden soubor pro každý jazyk, který se zobrazí v textovém souboru zprávy. Každý z těchto souborů ukládá všechny řetězce prostředků chybových zpráv pro jeden jazyk. Soubor pro každý jazyk má název langfile.bin, kde langfile je hodnota zadaná pro jazyk v souboru s textem zprávy v direktivě LanguageNames.

Další informace o kompilátoru zpráv naleznete v sadě Microsoft Windows SDK.

Kompilátor prostředků převede skript prostředku na soubor prostředků, který můžete připojit k obrazu ovladače. Pokud k sestavení ovladače použijete nástroj Sestavení, můžete zajistit, aby byl skript prostředku převeden na soubor prostředků a připojen k imagi ovladače jednoduše tak, že do proměnné SOURCES pro ovladač zahrnete název skriptu prostředku. Další informace o kompilátoru prostředků najdete v dokumentaci k sadě Windows SDK. Informace o použití nástroje Sestavení k sestavení ovladače naleznete v tématu Sestavení ovladače.