Fungsi IoBuildDeviceIoControlRequest (wdm.h)
Rutinitas IoBuildDeviceIoControlRequest mengalokasikan dan menyiapkan IRP untuk permintaan kontrol perangkat yang diproses secara sinkron.
Sintaks
__drv_aliasesMem PIRP IoBuildDeviceIoControlRequest(
[in] ULONG IoControlCode,
[in] PDEVICE_OBJECT DeviceObject,
[in, optional] PVOID InputBuffer,
[in] ULONG InputBufferLength,
[out, optional] PVOID OutputBuffer,
[in] ULONG OutputBufferLength,
[in] BOOLEAN InternalDeviceIoControl,
[in, optional] PKEVENT Event,
[out] PIO_STATUS_BLOCK IoStatusBlock
);
Parameter
[in] IoControlCode
Menyediakan kode kontrol I/O (IOCTL) yang akan digunakan dalam permintaan. Untuk informasi tentang kode kontrol I/O khusus jenis perangkat, lihat bagian khusus jenis perangkat di Windows Driver Kit (WDK).
[in] DeviceObject
Memasok pointer ke struktur DEVICE_OBJECT untuk objek perangkat driver berikutnya yang lebih rendah, yang mewakili perangkat target.
[in, optional] InputBuffer
Memasok pointer ke buffer input untuk diteruskan ke driver yang lebih rendah, atau NULL jika permintaan tidak meneruskan data input ke driver yang lebih rendah.
[in] InputBufferLength
Memasok panjang, dalam byte, dari buffer input. Jika InputBufferNULL, InputBufferLength harus nol.
[out, optional] OutputBuffer
Memasok pointer ke buffer output di mana driver yang lebih rendah adalah mengembalikan data, atau NULL jika permintaan tidak memerlukan driver yang lebih rendah untuk mengembalikan data.
[in] OutputBufferLength
Memasok panjang, dalam byte, dari buffer output. Jika OutputBufferNULL, OutputBufferLength harus nol.
[in] InternalDeviceIoControl
Jika TRUE, rutin mengatur kode fungsi utama IRP ke IRP_MJ_INTERNAL_DEVICE_CONTROL. Jika tidak, rutinitas mengatur kode fungsi utama IRP ke IRP_MJ_DEVICE_CONTROL.
[in, optional] Event
Memasok pointer ke objek peristiwa yang dialokasikan dan diinisialisasi penelepon. Manajer I/O mengatur peristiwa ke status Sinyal ketika driver tingkat bawah menyelesaikan operasi yang diminta. Setelah memanggil IoCallDriver, driver dapat menunggu objek peristiwa. Parameter Peristiwa bersifat opsional dan dapat diatur ke NULL. Namun, jika Peristiwa NULL, pemanggil harus menyediakan rutinitas IoCompletion agar IRP memberi tahu pemanggil ketika operasi selesai.
[out] IoStatusBlock
Menentukan blok status I/O yang akan diatur ketika permintaan diselesaikan oleh driver yang lebih rendah.
Nilai kembali
Jika operasi berhasil, IoBuildDeviceIoControlRequest mengembalikan penunjuk ke IRP, dengan lokasi tumpukan I/O driver berikutnya yang lebih rendah diatur dari parameter yang disediakan. Jika tidak, rutinitas mengembalikan NULL.
Keterangan
Driver dapat memanggil IoBuildDeviceIoControlRequest untuk menyiapkan IRP untuk permintaan kontrol perangkat yang dikirimnya secara sinkron ke driver tingkat bawah.
Setelah memanggil IoBuildDeviceIoControlRequest untuk membuat permintaan, driver harus memanggil IoCallDriver untuk mengirim permintaan ke driver berikutnya yang lebih rendah. Jika IoCallDriver mengembalikan STATUS_PENDING, driver harus menunggu penyelesaian IRP dengan memanggil KeWaitForSingleObject pada Peristiwa yang diberikan. Sebagian besar driver tidak perlu mengatur rutinitas IoCompletion untuk IRP.
IRP yang dibuat oleh IoBuildDeviceIoControlRequest harus diselesaikan dengan panggilan driver ke IoCompleteRequest. Driver yang memanggil IoBuildDeviceIoControlRequest tidak boleh memanggil IoFreeIrp, karena manajer I/O membebaskan IRP sinkron ini setelah IoCompleteRequest dipanggil.
IoBuildDeviceIoControlRequest mengantre IRP yang dibuatnya ke antrean IRP yang khusus untuk utas saat ini. Jika utas keluar, manajer I/O membatalkan IRP.
Jika pemanggil menyediakan parameter InputBuffer atau OutputBuffer , parameter ini harus menunjuk ke buffer yang berada di memori sistem. Pemanggil bertanggung jawab untuk memvalidasi nilai parameter apa pun yang disalin ke buffer input dari buffer mode pengguna. Buffer input mungkin berisi nilai parameter yang ditafsirkan secara berbeda tergantung pada apakah pencacah permintaan adalah aplikasi mode pengguna atau driver mode kernel. Di IRP yang dikembalikan IoBuildDeviceIoControlRequest , bidang RequestorMode selalu diatur ke KernelMode. Nilai ini menunjukkan bahwa permintaan, dan informasi apa pun yang terkandung dalam permintaan, berasal dari komponen mode kernel tepercaya.
Jika pemanggil tidak dapat memvalidasi nilai parameter yang disalin dari buffer mode pengguna ke buffer input, atau jika nilai-nilai ini tidak boleh ditafsirkan sebagai berasal dari komponen mode kernel, pemanggil harus mengatur bidang RequestorMode di IRP ke UserMode. Pengaturan ini menginformasikan driver yang menangani permintaan kontrol I/O bahwa buffer berisi data mode pengguna yang tidak tepercaya.
Metode aktual di mana konten parameter InputBuffer dan OutputBuffer disimpan di IRP tergantung pada nilai TransferType untuk IOCTL. Untuk informasi selengkapnya tentang nilai ini, lihat Deskripsi Buffer untuk Kode Kontrol I/O.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia dimulai dengan Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoAllocateIrpSignalEventInCompletion2(wdm), IoAllocateIrpSignalEventInCompletion3(wdm), IoBuildDeviceControlNoFree(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildDeviceIoControlSetEvent(wdm), IrqlIoPassive1(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm) |