Fungsi IoBuildDeviceIoControlRequest (wdm.h)

Artikel
08/08/2023

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)