DRIVER_DISPATCH fungsi panggilan balik (wdm.h)
Layanan rutin panggilan balik berbagai IRP. Untuk daftar kode fungsi, lihat Keterangan.
Sintaks
DRIVER_DISPATCH DriverDispatch;
NTSTATUS DriverDispatch(
[in, out] _DEVICE_OBJECT *DeviceObject,
[in, out] _IRP *Irp
)
{...}
Parameter
[in, out] DeviceObject
Penunjuk yang disediakan penelepon ke struktur DEVICE_OBJECT . Ini adalah objek perangkat untuk perangkat target, yang sebelumnya dibuat oleh rutinitas AddDevice driver.
[in, out] Irp
Penunjuk yang disediakan penelepon ke struktur IRP yang menjelaskan operasi I/O yang diminta.
Nilai kembali
Jika rutinitas berhasil, rutinitas harus mengembalikan STATUS_SUCCESS. Jika tidak, itu harus mengembalikan salah satu nilai status kesalahan yang ditentukan dalam Ntstatus.h.
Keterangan
Parameter input untuk semua rutinitas Pengiriman disediakan dalam struktur IRP yang ditujukkan oleh Irp. Parameter tambahan disediakan di lokasi tumpukan I/O terkait driver, yang dijelaskan oleh struktur IO_STACK_LOCATION dan dapat diperoleh dengan memanggil IoGetCurrentIrpStackLocation.
Umumnya, semua rutinitas Pengiriman dijalankan dalam konteks utas arbitrer di IRQL = PASSIVE_LEVEL, tetapi ada pengecualian. Untuk informasi selengkapnya, lihat Mengirimkan Rutinitas dan IRQL.
Untuk informasi selengkapnya tentang rutinitas pengiriman, lihat Menulis Rutinitas Pengiriman. Untuk informasi selengkapnya tentang IRP, lihat Menangani IRP.
| IRP | Tentang menerapkan panggilan balik |
|---|---|
| IRP_MJ_CLEANUP | Rutinitas DispatchCleanup pengemudi harus diberi nama XxxDispatchCleanup, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchCleanup di DriverObject-MajorFunction>[IRP_MJ_CLEANUP]. |
| IRP_MJ_CLOSE | Rutinitas DispatchClose driver harus diberi nama XxxDispatchClose, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchClose di DriverObject-MajorFunction>[IRP_MJ_CLOSE]. |
| IRP_MJ_CREATE | Rutinitas DispatchCreate driver harus diberi nama XxxDispatchCreate, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchCreate di DriverObject-MajorFunction>[IRP_MJ_CREATE]. |
| IRP_MJ_CREATE atau IRP_MJ_CLOSE | Driver dapat menyediakan rutinitas DispatchCreateClose tunggal alih-alih rutinitas DispatchCreate dan DispatchClose terpisah. Rutinitas DispatchCreateClose driver harus diberi nama XxxDispatchCreateClose, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchCreateClose di DriverObject-MajorFunction>[IRP_MJ_CREATE] dan diDriverObject-MajorFunction>[IRP_MJ_CLOSE]. |
| IRP_MJ_DEVICE_CONTROL | Rutinitas DispatchDeviceControl driver harus diberi nama XxxDispatchDeviceControl, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchDeviceControl di DriverObject-MajorFunction>[IRP_MJ_DEVICE_CONTROL]. Sistem menggunakan bendera FILE_XXX dalam kode kontrol I/O untuk menentukan apakah pengirim IRP memiliki hak istimewa untuk mengirim IRP ke objek perangkat. Driver untuk Windows Server 2003 dan versi Windows yang lebih baru dapat menggunakan rutinitas IoValidateDeviceIoControlAccess untuk melakukan pemeriksaan akses yang lebih ketat dalam DispatchDeviceControl. |
| IRP_MJ_FLUSH_BUFFERS | Rutinitas DispatchFlushBuffers driver harus diberi nama XxxDispatchFlushBuffers, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchFlushBuffers di DriverObject-MajorFunction>[IRP_MJ_FLUSH_BUFFERS]. |
| IRP_MJ_INTERNAL_DEVICE_CONTROL | Rutinitas DispatchInternalDeviceControl driver harus diberi nama XxxDispatchInternalDeviceControl, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchInternalDeviceControl di DriverObject-MajorFunction>[IRP_MJ_INTERNAL_DEVICE_CONTROL]. |
| IRP_MJ_PNP | Rutinitas DispatchPnP driver harus diberi nama XxxDispatchPnP, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchPnP di DriverObject-MajorFunction>[IRP_MJ_PNP]. |
| IRP_MJ_POWER | Rutinitas DispatchPower driver harus diberi nama XxxDispatchPower, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchPower di DriverObject-MajorFunction>[IRP_MJ_POWER]. |
| IRP_MJ_QUERY_INFORMATION | Rutinitas DispatchQueryInformation driver harus diberi nama XxxDispatchQueryInformation, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchQueryInformation di DriverObject-MajorFunction>[IRP_MJ_QUERY_INFORMATION]. |
| IRP_MJ_READ | Rutinitas DispatchRead driver harus diberi nama XxxDispatchRead, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchRead di DriverObject-MajorFunction>[IRP_MJ_READ]. |
| IRP_MJ_READ atau IRP_MJ_WRITE | Driver dapat menyediakan rutinitas DispatchReadWrite tunggal alih-alih rutinitas DispatchRead dan DispatchWrite terpisah. Rutinitas DispatchReadWrite driver harus diberi nama XxxDispatchReadWrite, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchReadWrite di DriverObject-MajorFunction>[IRP_MJ_READ] dan diDriverObject-MajorFunction>[IRP_MJ_WRITE]. |
| IRP_MJ_SET_INFORMATION | Rutinitas DispatchSetInformation driver harus diberi nama XxxDispatchSetInformation, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchSetInformation di DriverObject-MajorFunction>[IRP_MJ_SET_INFORMATION]. |
| IRP_MJ_SHUTDOWN | Rutinitas DispatchShutdown driver harus diberi nama XxxDispatchShutdown, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchShutdown di DriverObject-MajorFunction>[IRP_MJ_SHUTDOWN]. Selain itu, untuk menerima permintaan IRP_MJ_SHUTDOWN , driver harus memanggil IoRegisterShutdownNotification atau IoRegisterLastChanceShutdownNotification untuk mendaftarkan rutinitas DispatchShutdown-nya dengan sistem. |
| IRP_MJ_SYSTEM_CONTROL | Rutinitas DispatchSystemControl driver harus diberi nama XxxDispatchSystemControl, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchSystemControl di DriverObject-MajorFunction>[IRP_MJ_SYSTEM_CONTROL]. |
| IRP_MJ_WRITE | Rutinitas DispatchWrite driver harus diberi nama XxxDispatchWrite, di mana Xxx adalah awalan khusus driver. Rutinitas DriverEntry driver harus menyimpan alamat rutin DispatchWrite di DriverObject-MajorFunction>[IRP_MJ_WRITE]. |
Contoh
Untuk menentukan rutinitas panggilan balik, Anda harus terlebih dahulu memberikan deklarasi fungsi yang mengidentifikasi jenis rutinitas panggilan balik yang Anda tentukan. Windows menyediakan sekumpulan tipe fungsi panggilan balik untuk pengandar. Mendeklarasikan fungsi menggunakan jenis fungsi panggilan balik membantu Analisis Kode untuk Driver, Pemverifikasi Driver Statis (SDV), dan alat verifikasi lainnya menemukan kesalahan, dan itu adalah persyaratan untuk menulis driver untuk sistem operasi Windows.
Misalnya, untuk menentukan rutinitas panggilan balik DispatchCleanup yang diberi nama MyDispatchCleanup, gunakan jenis DRIVER_DISPATCH seperti yang ditunjukkan dalam contoh kode ini:
DRIVER_DISPATCH MyDispatchCleanup;
Kemudian, terapkan rutinitas panggilan balik Anda sebagai berikut:
_Use_decl_annotations_
NTSTATUS
MyDispatchCleanup(
struct _DEVICE_OBJECT *DeviceObject,
struct _IRP *Irp
)
{
// Function body
}
Jenis fungsi DRIVER_DISPATCH ditentukan dalam file header Wdm.h. Untuk mengidentifikasi kesalahan secara lebih akurat saat Anda menjalankan alat analisis kode, pastikan untuk menambahkan the_Use_decl_annotations_annotation ke definisi fungsi Anda. The_Use_decl_annotations_annotation memastikan bahwa anotasi yang diterapkan ke jenis fungsi DRIVER_DISPATCH dalam file header digunakan. Untuk informasi selengkapnya tentang persyaratan untuk deklarasi fungsi, lihat Mendeklarasikan Fungsi dengan Menggunakan Jenis Peran Fungsi untuk Driver WDM. Untuk informasi tentang Use_decl_annotations, lihat Perilaku Fungsi Anotasi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Target Platform | Desktop |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| IRQL | Dipanggil di PASSIVE_LEVEL (lihat bagian Keterangan). |
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk