Egyéni hibatípusok definiálása

Az illesztőprogramok saját hibatípusokat és hibaüzeneteket adhatnak meg. Egyéni hibaüzenet definiálásához először meg kell adnia egy új IO_ERR_XXX-értéket , amely a hibanapló-bejegyzés ErrorCode-tagjaként van megadva. Az Eseménynapló a IO_ERR_XXX értékkel keresi meg az illesztőprogram hibaüzenetét.

Az illesztőprogramban lévő egyéni hibaüzenetek támogatásához kövesse az alábbi lépéseket:

1. Hozzon létre egy üzenetszövegfájlt, amely megadja az egyéni IO_ERR_XXX értéket és a megfelelő hibaüzeneteket. További információ: A hibaüzenet szövegfájljának létrehozása.

2. Fordítsa le a hibaüzenet szövegfájlt egy erőforrásra, és csatolja az erőforrást az illesztőprogram lemezképéhez. További információ: A hibaüzenet szövegfájljának összeállítása.

3. Regisztrálja az illesztőprogram rendszerképét hibaüzeneteket tartalmazóként. További információért lásd: Regisztrálás hibaüzenetek forrásaként.

A hibaüzenet szövegfájljának létrehozása

Az illesztőprogram egyéni IO_ERR_XXX értékeinek és a megfelelő hibaüzenetsablonok definíciója üzenettáblázat-erőforrásként van csatolva az illesztőprogram lemezképéhez. Az illesztő üzeneteinek leírása egy üzenetszövegfájlban (amely .mc fájlnévkiterjesztéssel rendelkezik).

Az üzenetszövegfájl két szakaszból áll: egy fejlécszakaszból és egy üzenetszakaszból. A fejlécszakasz lehetővé teszi a numerikus értékek szimbolikus nevének deklarálását, míg az üzenetszakasz a IO_ERR_XXX értékeket és az egyező hibaüzenetsablonokat határozza meg.

Egy üzenetszövegfájlra példaként tekintse meg a GitHubon elérhető Soros-illesztő minta Serlog.mc fájlját.

Fejléc rész

A fejlécszakasznak tartalmaznia kell ezt a sort:

MessageIdTypedef=NTSTATUS

Ez biztosítja, hogy a Message Compiler által létrehozott IO_ERR_XXX értékek NTSTATUS típusként legyenek deklarálva.

A fejlécszakaszban megjelenő egyéb irányelvek olyan szimbolikus értékeket határoznak meg, amelyeket az üzenetszakasz numerikus értékei helyett használnak.

A SeverityNames és az FacilityNames irányelvek az NTSTATUS-értékek súlyossági és létesítménymezőinek szimbolikus értékeit határozzák meg. Az irányelvek a következő formátumúak: kulcsszó= (értékek), ahol az értékek egy vagy több név=érték:header_name formátumú kijelentésből állnak, szóközökkel elválasztva. A névparaméter az a név, amelyet az üzenet szövegfájljában a numerikus érték megadásakor használ, míg a header_name az üzenetfordító által létrehozott C fejlécfájlban deklarált érték neve. A :header_name záradék megadása nem kötelező.

Íme egy példa a súlyossági kódok szimbólumneveinek fejlécdeklarációjára:

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

A LanguageNames direktíva a területi azonosítók (LCID) szimbolikus értékeit határozza meg. Az irányelv a LanguageNames = (értékek) formából áll, ahol az értékekaz language_namelcid:langfile űrlap = egy vagy több utasításából állnak, szóközzel elválasztva. A language_name paraméter az üzenet szövegfájljában az lcid helyett használt név, míg a fájlnév egy egyedi fájlnevet ad meg (kiterjesztés nélkül). Amikor az Üzenetfordító létrehozza az erőforrásszkriptet az üzenet szövegfájljából, az ehhez a nyelvhez tartozó összes sztringerőforrást egy langfile nevű fájlban tárolja. bin.

Üzenetszakasz

Minden üzenetdefiníció annak az egyéni IO_ERR_XXX-értéknek a definíciójával kezdődik, amelyet az illesztőprogram az adott hibatípus jelentéséhez használ. A IO_ERR_XXX értéketkulcsszóértékpárok = sorozata határozza meg. A lehetséges kulcsszavak és azok jelentése a következő.

Kulcsszó	Érték
MessageId	Az új IO_ERR_XXX érték kódmezője.
Súlyosság	Az új IO_ERR_XXX érték súlyossági mezője. A megadott értéknek a SeverityNames fejléc direktíva által meghatározott szimbolikus nevek egyike kell legyen.
Létesítmény	Az új IO_ERR_XXX érték létesítménymezője. A megadott értéknek az FacilityNames fejlécirányelmében meghatározott szimbolikus nevek egyikének kell lennie.
SymbolicName	Az új IO_ERR_XXX érték szimbolikus neve. Az Üzenetfordító létrehoz egy C fejlécfájlt, amely a név #define deklarációját tartalmazza a megfelelő NTSTATUS-értékként. Az illesztőprogram ezt a nevet használja a hibatípus megadásakor.

Az első kulcsszónak mindig MessageId értékűnek kell lennie.

Az üzenetdefiníció többi része a hibaüzenet egy vagy több honosított verziójából áll. Minden verzió a következő formátumban van:

Language=language_name
localized_message

Az language_name érték, amelynek a LanguageNames fejlécirányelmében meghatározott szimbólumnevek egyikének kell lennie, meghatározza az üzenet szövegének nyelvét. Maga a honosított üzenetszöveg Unicode-sztringből áll. Az "%n" űrlap beágyazott sztringjei sablonként lesznek kezelve, amelyeket az Eseménynapló lecserél a hiba naplózásakor. A "%1" sztring helyébe az illesztőprogram eszközobjektumának neve kerül, míg a "%2" és "%n" karakterláncok helyébe az illesztő által biztosított beszúrási sztringek lépnek.

Az üzenetdefiníciót egyetlen pont szakítja meg egy sorban.

Ha egyéni hibaüzeneteket definiál, csak akkor használjon beszúrási karakterláncokat, ha szükséges. A beszúrási sztringek nem honosíthetők, ezért nyelvfüggetlen sztringekhez, például számokhoz vagy fájlnevekhez kell használni őket. A legtöbb illesztőprogram nem használ beszúrási sztringeket.

A hibaüzenet szövegfájljának összeállítása

Az Üzenetfordítóval (mc.exe) lefordíthatja az üzenet szövegfájlját egy erőforrásszkriptfájlba (amely .rc fájlnévkiterjesztéssel rendelkezik). Egy ilyen formájú parancs

mc filename.mc

az Üzenetfordító a következő fájlokat hozza létre:

• filename.h, egy fejlécfájl, amely az egyes egyéni IO_ERR_XXX-értékek deklarációit tartalmazza a fájlnévben. mc.

• filename.rc, erőforrás-szkript.

• Egy fájl minden nyelvhez, amely megjelenik az üzenet szövegfájljában. Ezek a fájlok egy nyelven tárolják a hibaüzenet-sztring összes erőforrását. Az egyes nyelvekhez tartozó fájl neve langfile. bin, ahol a langfile az üzenetszövegfájl LanguageNames irányelvében megadott nyelvhez megadott érték.

Az üzenetfordítóval kapcsolatos további információk a Microsoft Windows SDK-ban találhatók.

A Resource Compiler egy erőforrásszkriptet átalakít egy erőforrásfájllá, amelyet csatolhat az illesztőprogram lemezképéhez. Ha a Build segédprogrammal hozza létre az illesztőprogramot, győződjön meg arról, hogy az erőforrásszkript erőforrásfájllá lesz konvertálva, és egyszerűen csatolva van az illesztőprogram lemezképéhez egyszerűen úgy, hogy az erőforrásszkript nevét az illesztőprogram SOURCES változójában szerepelteti. Az erőforrás-fordítóról további információt a Windows SDK dokumentációjában talál. Az illesztőprogram buildelésére szolgáló Build segédprogrammal kapcsolatos információkért lásd: Illesztőprogram létrehozása.