Menentukan Jenis Kesalahan Kustom

Artikel
06/15/2023

Driver dapat menentukan jenis kesalahan dan pesan kesalahan mereka sendiri. Untuk menentukan pesan kesalahan kustom, Anda harus terlebih dahulu menentukan nilai IO_ERR_XXX baru untuk ditentukan sebagai anggota ErrorCode dari entri log kesalahan. Pemantau Peristiwa menggunakan nilai IO_ERR_XXX untuk mencari pesan kesalahan driver.

Untuk mendukung pesan kesalahan kustom di driver Anda, ikuti langkah-langkah berikut:

Buat file teks pesan yang menentukan nilai IO_ERR_XXX kustom dan pesan kesalahan yang sesuai. Untuk informasi selengkapnya, lihat Membuat File Teks Pesan Kesalahan.
Kompilasi file teks pesan kesalahan ke sumber daya, dan lampirkan sumber daya ke gambar driver. Untuk informasi selengkapnya, lihat Mengkompilasi File Teks Pesan Kesalahan.
Daftarkan gambar driver sebagai berisi pesan kesalahan. Untuk informasi selengkapnya, lihat Mendaftar sebagai Sumber Pesan Kesalahan.

Membuat File Teks Pesan Kesalahan

Definisi nilai IO_ERR_XXXX kustom driver dan templat pesan kesalahan yang cocok dilampirkan sebagai sumber daya tabel pesan ke gambar driver. Anda dapat menjelaskan pesan untuk driver dalam file teks pesan (yang memiliki ekstensi nama file .mc).

File teks pesan terdiri dari dua bagian: bagian header dan bagian pesan. Bagian header mengizinkan deklarasi nama simbolis untuk nilai numerik, sementara bagian pesan menentukan nilai IO_ERR_XXX dan templat pesan kesalahan yang cocok.

Untuk contoh file teks pesan, lihat file Serlog.mc dalam sampel Driver serial yang tersedia di GitHub.

Bagian Header

Bagian header harus berisi baris ini:

MessageIdTypedef=NTSTATUS

Ini memastikan bahwa jenis nilai IO_ERR_XXX yang dihasilkan oleh Pengkompilasi Pesan dinyatakan sebagai NTSTATUS.

Arahan lain yang muncul di bagian header menentukan nilai simbolis yang digunakan sebagai pengganti nilai numerik di bagian pesan.

Arahan SeverityNames dan FacilityNames menentukan nilai simbolis untuk bidang tingkat keparahan dan fasilitas nilai NTSTATUS. Direktif adalah kata kunci formulir= (nilai), di mana nilai terdiri dari satu atau beberapa pernyataandari nilainama= formulir:header_name, dipisahkan oleh spasi kosong. Parameter nama adalah nama yang Anda gunakan untuk menentukan nilai numerik dalam file teks pesan, sementara header_name adalah nama untuk nilai ini yang dideklarasikan dalam file header C yang dihasilkan oleh Pengkompilasi Pesan. Klausa :header_name bersifat opsional.

Berikut adalah contoh deklarasi header nama simbolis untuk kode tingkat keparahan:

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

Direktif LanguageNames mendefinisikan nilai simbolis untuk ID lokal (LCID). Direktif adalah dari bentuk LanguageNames = (nilai), di mana nilai terdiri dari satu atau beberapa pernyataan formulir language_name=lcid:langfile, dipisahkan oleh spasi kosong. Parameter language_name adalah nama yang Anda gunakan sebagai pengganti lcid dalam file teks pesan, sementara nama file menentukan nama file unik (tanpa ekstensi). Ketika Pengkompilasi Pesan menghasilkan skrip sumber daya dari file teks pesan, Pengkompilasi Pesan menyimpan semua sumber daya string untuk bahasa ini dalam file bernama langfile. bin.

Bagian Pesan

Setiap definisi pesan dimulai dengan definisi nilai IO_ERR_XXX kustom yang digunakan driver untuk melaporkan jenis kesalahan khusus ini. Nilai IO_ERR_XXX ditentukan oleh serangkaian pasangannilaikata kunci = . Kata kunci yang mungkin dan maknanya adalah sebagai berikut.

Kata kunci	Nilai
MessageId	Bidang kode dari nilai IO_ERR_XXX baru .
Keparahan	Bidang tingkat keparahan dari nilai IO_ERR_XXX baru . Nilai yang ditentukan harus merupakan salah satu nama simbolis yang ditentukan oleh direktif header SeverityNames .
Fasilitas	Bidang fasilitas dari nilai IO_ERR_XXX baru . Nilai yang ditentukan harus merupakan salah satu nama simbolis yang ditentukan oleh direktif header FacilityNames .
SymbolicName	Nama simbolis untuk nilai IO_ERR_XXXX baru. Pengkompilasi Pesan menghasilkan file header C yang berisi #define deklarasi nama sebagai nilai NTSTATUS yang sesuai. Driver menggunakan nama tersebut ketika menentukan jenis kesalahan.

Kata kunci pertama harus selalu MessageId.

Definisi pesan lainnya terdiri dari satu atau beberapa versi pesan kesalahan yang dilokalkan. Setiap versi berbentuk:

Language=language_name
localized_message

Nilai language_name , yang harus menjadi salah satu nama simbolis yang ditentukan oleh direktif header LanguageNames , menentukan bahasa teks pesan. Teks pesan yang dilokalkan sendiri terdiri dari string Unicode. Setiap string yang disematkan dari formulir "%n" akan diperlakukan sebagai templat yang akan digantikan Pemantau Peristiwa ketika kesalahan dicatat. String "%1" diganti dengan nama objek perangkat pengandar, sedangkan "%2" hingga "%n" diganti dengan string penyisipan yang disediakan oleh driver.

Definisi pesan dihentikan oleh satu periode saja pada baris.

Jika Anda menentukan pesan kesalahan kustom, Anda tidak boleh menggunakan string penyisipan kecuali diperlukan. String penyisipan tidak dapat dilokalkan, sehingga harus digunakan untuk string yang independen bahasa, seperti angka atau nama file. Sebagian besar driver tidak menggunakan string penyisipan.

Mengkompilasi File Teks Pesan Kesalahan

Gunakan Pengkompilasi Pesan (mc.exe) untuk mengkompilasi file teks pesan Anda ke dalam file skrip sumber daya (yang memiliki ekstensi nama file .rc). Perintah formulir

mc filename.mc

menyebabkan Pengkompilasi Pesan menghasilkan file berikut:

filename.h, file header yang berisi deklarasi setiap nilai IO_ERR_XXX kustom dalam nama file. mc.
filename.rc, skrip sumber daya.
Satu file untuk setiap bahasa yang muncul dalam file teks pesan. Masing-masing file ini menyimpan semua sumber daya string pesan kesalahan untuk satu bahasa. File untuk setiap bahasa diberi nama langfile. bin, di mana langfile adalah nilai yang ditentukan untuk bahasa dalam direktif LanguageNames file teks pesan.

Informasi selengkapnya tentang Pengkompilasi Pesan dapat ditemukan di Microsoft Windows SDK.

Pengkompilasi Sumber Daya mengonversi skrip sumber daya menjadi file sumber daya yang dapat Anda lampirkan ke gambar driver Anda. Jika Anda menggunakan utilitas Build untuk membangun driver, Anda dapat memastikan bahwa skrip sumber daya dikonversi ke file sumber daya dan dilampirkan ke gambar driver Anda hanya dengan menyertakan nama skrip sumber daya dalam variabel SOURCES untuk driver. Untuk informasi selengkapnya tentang Pengkompilasi Sumber Daya, lihat dokumentasi Windows SDK. Untuk informasi tentang menggunakan utilitas Build untuk membangun driver Anda, lihat Membangun Driver.