Fungsi IoBuildSynchronousFsdRequest (wdm.h)

Artikel
08/08/2023

Rutinitas IoBuildSynchronousFsdRequest mengalokasikan dan menyiapkan IRP untuk permintaan I/O yang diproses secara sinkron.

Sintaks

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

Parameter

[in] MajorFunction

Kode fungsi utama untuk IRP. Kode ini dapat IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS, atau IRP_MJ_SHUTDOWN.

[in] DeviceObject

Penunjuk ke struktur DEVICE_OBJECT untuk objek perangkat driver berikutnya yang lebih rendah, yang mewakili perangkat target.

[in, out] Buffer

Penunjuk ke buffer data. Jika MajorFunctionIRP_MJ_WRITE, buffer berisi data yang akan ditulis. Jika MajorFunctionIRP_MJ_READ, buffer akan menerima data. Jika MajorFunctionIRP_MJ_FLUSH_BUFFERS atau IRP_MJ_SHUTDOWN, parameter ini harus NULL.

[in, optional] Length

Panjangnya, dalam byte, dari buffer yang diacu oleh Buffer. Untuk perangkat seperti disk, nilai ini harus berupa kelipatan bilangan bulat dari ukuran sektor. Dimulai dengan Windows 8, ukuran sektor bisa 4.096 atau 512 byte. Di versi Windows sebelumnya, ukuran sektor selalu 512 byte. Parameter ini diperlukan untuk permintaan baca dan tulis, tetapi harus nol untuk permintaan flush dan shutdown.

[in, optional] StartingOffset

Penunjuk ke offset pada disk, untuk permintaan baca dan tulis. Unit dan arti dari nilai ini khusus untuk driver. Parameter ini diperlukan untuk permintaan baca dan tulis, tetapi harus nol untuk permintaan flush dan shutdown.

[in] Event

Penunjuk 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.

[out] IoStatusBlock

Penunjuk ke lokasi yang menerima blok status I/O yang diatur ketika IRP diselesaikan oleh driver tingkat bawah.

Nilai kembali

Jika operasi berhasil, IoBuildSynchronousFsdRequest mengembalikan pointer ke struktur IRP yang diinisialisasi, dengan lokasi tumpukan I/O driver berikutnya yang lebih rendah disiapkan dari parameter yang disediakan. Jika tidak, rutinitas mengembalikan NULL.

Keterangan

Driver sistem file (FSD) atau driver tingkat lebih tinggi lainnya dapat memanggil IoBuildSynchronousFsdRequest untuk mengatur RUN yang dikirim secara sinkron ke driver tingkat bawah.

IoBuildSynchronousFsdRequest mengalokasikan dan menyiapkan IRP yang meminta driver tingkat bawah untuk melakukan operasi baca, tulis, hapus, atau matikan sinkron. IRP berisi informasi yang cukup untuk memulai operasi.

Driver tingkat bawah mungkin memberlakukan pembatasan pada parameter yang disediakan untuk rutinitas ini. Misalnya, driver disk mungkin mengharuskan nilai yang disediakan untuk Panjang dan StartingOffset adalah kelipatan bilangan bulat dari ukuran sektor perangkat.

Setelah memanggil IoBuildSynchronousFsdRequest untuk membuat permintaan, driver harus memanggil IoCallDriver untuk mengirim permintaan ke driver yang lebih rendah berikutnya. 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 IoBuildSynchronousFsdRequest harus diselesaikan dengan panggilan driver ke IoCompleteRequest. Driver yang memanggil IoBuildSynchronousFsdRequest tidak boleh memanggil IoFreeIrp, karena manajer I/O membebaskan IRP sinkron ini setelah IoCompleteRequest dipanggil.

IoBuildSynchronousFsdRequest mengantre IRP yang dibuatnya ke antrean IRP yang khusus untuk utas saat ini. Jika utas keluar, manajer I/O membatalkan IRP.

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	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)