Fungsi DbgPrintEx (wdm.h)

Artikel
08/08/2023

Rutinitas DbgPrintEx mengirimkan string ke debugger kernel jika kondisi yang Anda tentukan terpenuhi.

Sintaks

NTSYSAPI ULONG DbgPrintEx(
  [in] ULONG ComponentId,
  [in] ULONG Level,
  [in] PCSTR Format,
       ...   
);

Parameter

[in] ComponentId

Menentukan komponen yang memanggil rutinitas ini. Ini harus menjadi salah satu ID filter nama komponen yang ditentukan dalam file header Dpfilter.h. Untuk menghindari pencampuran output driver Anda dengan output komponen Windows, Anda hanya boleh menggunakan nilai berikut untuk ComponentId:

DPFLTR_IHVVIDEO_ID
DPFLTR_IHVAUDIO_ID
DPFLTR_IHVNETWORK_ID
DPFLTR_IHVSTREAMING_ID
DPFLTR_IHVBUS_ID
DPFLTR_IHVDRIVER_ID

[in] Level

Menentukan tingkat keparahan pesan yang dikirim. Ini bisa berupa bilangan bulat 32-bit. Nilai antara 0 dan 31 (inklusif) diperlakukan berbeda dari nilai antara 32 dan 0xFFFFFFFF. Untuk detailnya, lihat Membaca dan Memfilter Pesan Penelusuran Kesalahan.

[in] Format

Menentukan penunjuk ke string format yang akan dicetak. String Format mendukung sebagian besar bidang spesifikasi format gaya cetak. Namun, kode format Unicode (%C, %S, %lc, %ls, %wc, %ws, dan %wZ) hanya dapat digunakan dengan IRQL = PASSIVE_LEVEL. Rutinitas DbgPrintEx tidak mendukung tipe titik mengambang (%f, %e, %E, %g, %G, %a, atau %A).

...

Menentukan argumen untuk string format, seperti dalam printf.

Nilai kembali

Jika berhasil, DbgPrintEx mengembalikan kode NTSTATUS STATUS_SUCCESS; jika tidak, ia mengembalikan kode kesalahan yang sesuai.

Keterangan

Hanya driver mode kernel yang dapat memanggil rutinitas DbgPrintEx .

DbgPrint dan DbgPrintEx dapat dipanggil di IRQL<=DIRQL. Namun, kode format Unicode (%wc dan %ws) hanya dapat digunakan pada IRQL = PASSIVE_LEVEL. Selain itu, karena debugger menggunakan interupsi interproses (IPI) untuk berkomunikasi dengan prosesor lain, memanggil DbgPrint di IRQL>DIRQL dapat menyebabkan kebuntuan.

DbgPrintEx meneruskan string yang ditentukan ke debugger kernel atau tidak melakukan apa pun, tergantung pada nilai ComponentId, Level, dan masker filter komponen yang sesuai. Untuk detailnya, lihat Membaca dan Memfilter Pesan Penelusuran Kesalahan.

Kecuali jika benar-benar diperlukan, Anda tidak boleh mendapatkan string dari input pengguna atau proses lain dan meneruskannya ke DbgPrintEx. Jika Anda menggunakan string yang tidak Anda buat, Anda harus memverifikasi bahwa ini adalah string format yang valid, dan bahwa kode format cocok dengan daftar argumen dalam jenis dan kuantitas. Praktik pengkodean terbaik adalah agar semua string Format statis dan didefinisikan pada waktu kompilasi.

Tidak ada batas atas untuk ukuran string Format atau jumlah argumen. Namun, setiap panggilan tunggal ke DbgPrintEx hanya akan mengirimkan informasi 512 byte. Ada juga batasan ukuran buffer DbgPrint. Lihat Buffer DbgPrint dan Debugger untuk detailnya.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Microsoft Windows XP dan yang lebih baru.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h)
Pustaka	NtDll.lib (mode pengguna); NtosKrnl.lib (mode kernel)
DLL	NtDll.dll (mode pengguna); NtosKrnl.exe (mode kernel)
IRQL	<= DIRQL (lihat bagian Komentar)

Lihat juga