Definiowanie niestandardowych typów błędów

Sterowniki mogą określać własne typy błędów i komunikaty o błędach. Aby zdefiniować niestandardowy komunikat o błędzie, należy najpierw zdefiniować nową wartość IO_ERR_XXX , aby określić jako element członkowski ErrorCode wpisu dziennika błędów. Podgląd zdarzeń używa wartości IO_ERR_XXX , aby wyszukać komunikat o błędzie sterownika.

Aby obsługiwać niestandardowe komunikaty o błędach w sterowniku, wykonaj następujące kroki:

1. Utwórz plik tekstowy wiadomości, który określa niestandardową wartość IO_ERR_XXX i odpowiednie komunikaty o błędach. Aby uzyskać więcej informacji, zobacz Tworzenie pliku tekstowego komunikatu o błędzie.

2. Skompiluj plik tekstowy komunikatu o błędzie do zasobu i dołącz zasób do obrazu sterownika. Aby uzyskać więcej informacji, zobacz Kompilowanie pliku tekstowego komunikatu o błędzie.

3. Zarejestruj obraz sterownika jako zawierający komunikaty o błędach. Aby uzyskać więcej informacji, zobacz Rejestrowanie jako źródło komunikatów o błędach.

Tworzenie pliku tekstowego komunikatu o błędzie

Definicja niestandardowych wartości IO_ERR_XXX sterownika i pasujących szablonów komunikatów o błędach jest dołączana jako zasób tabeli komunikatów do obrazu sterownika. Komunikaty dotyczące sterownika można opisać w pliku tekstowym wiadomości (który ma rozszerzenie nazwy pliku .mc).

Plik tekstowy wiadomości składa się z dwóch sekcji: sekcji nagłówka i sekcji komunikatu. Sekcja nagłówka zezwala na deklarowanie nazw symbolicznych wartości liczbowych, podczas gdy sekcja komunikatu określa wartości IO_ERR_XXX i pasujące szablony komunikatów o błędach.

Aby zapoznać się z przykładem pliku tekstowego wiadomości, zobacz plik Serlog.mc w przykładzie sterownika szeregowego dostępnym w witrynie GitHub.

Sekcja nagłówka

Sekcja nagłówka musi zawierać następujący wiersz:

MessageIdTypedef=NTSTATUS

Gwarantuje to, że typ wartości IO_ERR_XXX wygenerowanych przez kompilator komunikatów jest zadeklarowany jako NTSTATUS.

Inne dyrektywy, które pojawiają się w sekcji nagłówka, definiują wartości symboliczne, które są używane zamiast wartości liczbowych w sekcji komunikatu.

Dyrektywy SeverityNames i FacilityNames definiują wartości symboliczne dla pól surowości i funkcji wartości NTSTATUS. Dyrektywy mają format słowo kluczowe= (wartości), gdzie wartości składają się z jednej lub więcej instrukcji w formacie nazwa=wartość:nazwa_nagłówka, oddzielone białymi spacjami. Parametr name to nazwa, której używasz, określając wartość liczbową w pliku tekstowym wiadomości, a header_name jest nazwą tej wartości zadeklarowaną w pliku nagłówka języka C wygenerowany przez kompilator komunikatów. Klauzula :header_name jest opcjonalna.

Oto przykład deklaracji nagłówkowej nazw symbolicznych dla kodów dotyczących poziomu istotności.

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

Dyrektywa LanguageNames definiuje wartości symboliczne dla identyfikatorów ustawień regionalnych (LCID). Dyrektywa jest formą LanguageNames = (wartości), gdzie wartości składają się z co najmniej jednej instrukcji formularza language_name=lcid:langfile oddzielonej białym znakiem. Parametr language_name to nazwa, której używasz zamiast lcid w pliku tekstowym wiadomości, natomiast nazwa pliku określa unikatową nazwę pliku (bez rozszerzenia). Gdy kompilator komunikatów generuje skrypt zasobu z pliku tekstowego wiadomości, przechowuje wszystkie zasoby ciągów dla tego języka w pliku o nazwie langfile. bin.

Sekcja komunikatów

Każda definicja komunikatu zaczyna się od definicji niestandardowej wartości IO_ERR_XXX używanej przez sterownik do raportowania tego konkretnego typu błędu. Wartość IO_ERR_XXX jest definiowana przez serię par słowa kluczowego = wartości. Możliwe słowa kluczowe i ich znaczenie są następujące.

Pierwsze słowo kluczowe musi zawsze mieć wartość MessageId.

Pozostała część definicji komunikatu składa się z co najmniej jednej zlokalizowanej wersji komunikatu o błędzie. Każda wersja ma postać:

Language=language_name
localized_message

Wartość language_name , która musi być jedną z nazw symbolicznych zdefiniowanych przez dyrektywę nagłówka LanguageNames , określa język tekstu wiadomości. Zlokalizowany tekst wiadomości składa się z ciągu Unicode. Wszystkie osadzone ciągi formularza "%n" będą traktowane jako szablony, które Podgląd zdarzeń zastąpi po zarejestrowaniu błędu. Ciąg "%1" jest zastępowany nazwą obiektu urządzenia sterownika, podczas gdy "%2" za pośrednictwem "%n" są zastępowane dowolnymi ciągami wstawiania dostarczonymi przez sterownik.

Definicja komunikatu jest przerywana tylko przez pojedynczy okres w wierszu.

Jeśli zdefiniujesz niestandardowe komunikaty o błędach, nie należy używać ciągów wstawiania, chyba że jest to konieczne. Nie można lokalizować ciągów wstawiania, dlatego powinny być używane dla ciągów niezależnych od języka, takich jak liczby lub nazwy plików. Większość sterowników nie używa ciągów wstawiania.

Kompilowanie pliku tekstowego komunikatu o błędzie

Użyj Kompilatora wiadomości (mc.exe), aby skompilować plik tekstowy wiadomości na plik skryptu zasobu (który ma rozszerzenie .rc). Polecenie formularza

mc filename.mc

polecenie powoduje wygenerowanie następujących plików przez kompilator komunikatów:

• nazwa_pliku.h, plik nagłówka zawierający deklaracje każdej niestandardowej wartości IO_ERR_XXX w nazwie pliku. mc.

• nazwa_pliku.rc— skrypt zasobów.

• Jeden plik dla każdego języka wyświetlanego w pliku tekstowym wiadomości. Każdy z tych plików przechowuje wszystkie zasoby ciągu komunikatu o błędzie dla jednego języka. Plik dla każdego języka nosi nazwę langfile. bin, gdzie langfile jest wartością określoną dla języka w dyrektywie LanguageNames pliku tekstowego wiadomości.

Więcej informacji na temat kompilatora komunikatów można znaleźć w zestawie Microsoft Windows SDK.

Kompilator zasobów konwertuje skrypt zasobu na plik zasobów, który można dołączyć do obrazu sterownika. Jeśli używasz narzędzia kompilacji do kompilowania sterownika, możesz upewnić się, że skrypt zasobu jest konwertowany na plik zasobu i dołączony do obrazu sterownika, po prostu dołączając nazwę skryptu zasobu w zmiennej SOURCES sterownika. Aby uzyskać więcej informacji na temat kompilatora zasobów, zobacz dokumentację zestawu Windows SDK. Aby uzyskać informacje o używaniu narzędzia kompilacji do kompilowania sterownika, zobacz Tworzenie sterownika.