Fungsi ZwDeviceIoControlFile (ntifs.h)

Artikel
07/11/2023

Rutinitas ZwDeviceIoControlFile mengirimkan kode kontrol langsung ke driver perangkat tertentu, menyebabkan driver yang sesuai melakukan operasi yang ditentukan.

Sintaks

NTSYSAPI NTSTATUS ZwDeviceIoControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            IoControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

Parameter

[in] FileHandle

Tangani yang dikembalikan oleh ZwCreateFile atau ZwOpenFile untuk objek file yang mewakili perangkat tempat informasi kontrol harus diberikan atau dari mana informasi harus dikembalikan. Objek file harus dibuka untuk I/O asinkron jika pemanggil menentukan Peristiwa, ApcRoutine, dan konteks APC (dalam ApcContext), atau konteks penyelesaian (dalam ApcContext). Untuk I/O ke perangkat penyimpanan massal yang mendasar, objek file harus telah dibuka untuk akses Akses Langsung ke Perangkat Penyimpanan (DASD).

[in, optional] Event

Menangani peristiwa yang dibuat penelepon. Jika parameter ini disediakan, pemanggil akan dimasukkan ke dalam status tunggu hingga operasi yang diminta selesai dan peristiwa yang diberikan diatur ke status Sinyal. Parameter ini bersifat opsional dan dapat berupa NULL. Ini harus NULL jika pemanggil akan menunggu FileHandle diatur ke status Sinyal.

[in, optional] ApcRoutine

Alamat rutinitas APC opsional yang disediakan penelepon untuk dipanggil ketika operasi yang diminta selesai. Parameter ini bisa NULL. Ini harus NULL jika ada objek penyelesaian I/O yang terkait dengan objek file.

[in, optional] ApcContext

Penunjuk ke area konteks yang ditentukan penelepon. Nilai parameter ini digunakan sebagai konteks APC jika pemanggil memasok APC, atau digunakan sebagai konteks penyelesaian jika objek penyelesaian I/O telah dikaitkan dengan objek file. Ketika operasi selesai, konteks APC diteruskan ke APC, jika ditentukan, atau konteks penyelesaian disertakan sebagai bagian dari pesan penyelesaian yang diposting Manajer I/O ke objek penyelesaian I/O terkait.

Parameter ini bersifat opsional dan dapat berupa NULL. Ini harus NULL jika ApcRoutine adalah NULL dan tidak ada objek penyelesaian I/O yang terkait dengan objek file.

[out] IoStatusBlock

Penunjuk ke variabel yang menerima status penyelesaian akhir dan informasi tentang operasi. Untuk panggilan berhasil yang mengembalikan data, jumlah byte yang ditulis ke OutputBuffer dikembalikan di anggota Informasi .

[in] IoControlCode

IOCTL_XXX yang menunjukkan operasi kontrol I/O perangkat mana yang akan dilakukan, biasanya oleh driver perangkat yang mendasar. Nilai parameter ini menentukan format dan panjang inputBuffer dan OutputBuffer yang diperlukan, serta pasangan parameter berikut mana yang diperlukan. Untuk informasi terperinci tentang kode IOCTL_XXXX khusus jenis perangkat yang ditentukan sistem, lihat bagian khusus teknologi perangkat dari dokumentasi Microsoft Windows Driver Kit (WDK) dan Kode Kontrol Input dan Output Perangkat dalam dokumentasi Microsoft Windows SDK.

[in, optional] InputBuffer

Penunjuk ke buffer input yang dialokasikan penelepon yang berisi informasi khusus perangkat yang akan diberikan ke perangkat target. Jika IoControlCode menentukan operasi yang tidak memerlukan data input, pointer ini bisa null.

[in] InputBufferLength

Ukuran, dalam byte, dari buffer di InputBuffer. Jika InputBuffer adalah NULL, atur InputBufferLength ke nol.

[out, optional] OutputBuffer

Penunjuk ke buffer output yang dialokasikan penelepon tempat informasi dikembalikan dari perangkat target. Jika IoControlCode menentukan operasi yang tidak menghasilkan data output, pointer ini bisa null.

[in] OutputBufferLength

Ukuran, dalam byte, dari buffer di OutputBuffer. Jika OutputBufferADALAH NULL, atur OutputBufferLength ke nol.

Nilai kembali

ZwDeviceIoControlFile mengembalikan STATUS_SUCCESS jika driver dasar berhasil melakukan operasi yang diminta. Jika tidak, nilai yang dikembalikan dapat menjadi kode status kesalahan yang disebarluaskan dari driver yang mendasar. Kemungkinan kode status kesalahan meliputi yang berikut ini:

Keterangan

ZwDeviceIoControlFile memberikan tampilan data input dan output yang konsisten ke sistem dan driver mode kernel, sambil menyediakan aplikasi dan driver yang mendasar dengan metode yang bergantung pada perangkat untuk menentukan antarmuka komunikasi.

Untuk informasi selengkapnya tentang kode IOCTL_XXXX yang ditentukan sistem, dan tentang menentukan nilai IOCTL_XXXX atau FSCTL_XXXX khusus driver, lihat Menggunakan Kode Kontrol I/O dalam Panduan Arsitektur Mode Kernel dan Kode Kontrol Input dan Output Perangkat dalam dokumentasi Microsoft Windows SDK.

Jika pemanggil membuka file untuk I/O asinkron (dengan tidak ada opsi buat/buka FILE_SYNCHRONOUS_XXX ), peristiwa yang ditentukan, jika ada, akan diatur ke status yang disinyalkan saat operasi kontrol perangkat selesai. Jika tidak, objek file yang ditentukan oleh FileHandle akan diatur ke status yang disinyalkan. Jika ApcRoutine ditentukan, apcRoutine dipanggil dengan pointer ApcContext dan IoStatusBlock .

Minifilter harus menggunakan FltDeviceIoControlFile alih-alih ZwDeviceIoControlFile.

Pemanggil ZwDeviceIoControlFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

Catatan Jika panggilan ke fungsi ZwDeviceIoControlFile terjadi dalam mode pengguna, Anda harus menggunakan nama "NtDeviceIoControlFile" alih-alih "ZwDeviceIoControlFile".

Untuk panggilan dari driver mode kernel, versi **Nt*Xxx*** dan **Zw*Xxx*** dari rutinitas Layanan Sistem Asli Windows dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi **Nt*Xxx*** dan **Zw*Xxx*** dari rutinitas, lihat [Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli](/windows-hardware/drivers/kernel/using-nt-and-zw-versions-of-the-native-system-services-routines).

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000.
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h, Ntddk.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)