Fungsi ZwFsControlFile (ntifs.h)

Artikel
02/29/2024

Rutinitas ZwFsControlFile mengirimkan kode kontrol langsung ke sistem file atau driver filter sistem file tertentu, menyebabkan driver yang sesuai melakukan tindakan yang ditentukan.

Sintaks

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

Parameter

[in] FileHandle

Menangani yang dikembalikan oleh ZwCreateFile atau ZwOpenFile untuk objek file yang mewakili file atau direktori tempat tindakan yang ditentukan akan dilakukan. Objek file harus dibuka untuk I/O asinkron jika pemanggil menentukan Peristiwa, ApcRoutine, dan konteks APC (dalam ApcContext), atau konteks penyelesaian (dalam ApcContext).

[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 penelepon akan menunggu FileHandle diatur ke status Sinyal.

[in, optional] ApcRoutine

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

[in, optional] ApcContext

Arahkan 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 satu 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 ApcRoutineADALAH NULL dan tidak ada objek penyelesaian I/O yang terkait dengan objek file.

[out] IoStatusBlock

Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi. Untuk panggilan yang berhasil yang mengembalikan data, jumlah byte yang ditulis ke OutputBuffer dikembalikan dalam anggota Informasi struktur ini.

[in] FsControlCode

FSCTL_XXX yang menunjukkan operasi kontrol sistem file mana yang akan dilakukan. Nilai parameter ini menentukan format dan panjang inputBuffer dan OutputBuffer yang diperlukan, serta pasangan parameter berikut mana yang diperlukan. Untuk informasi terperinci tentang kode FSCTL_XXX yang ditentukan sistem, lihat bagian "Keterangan" dari entri referensi untuk DeviceIoControl dalam dokumentasi Microsoft Windows SDK.

[in, optional] InputBuffer

Penunjuk ke buffer input yang dialokasikan pemanggil yang berisi informasi khusus perangkat untuk diberikan kepada driver target. Jika FsControlCode menentukan operasi yang tidak memerlukan data input, penunjuk ini bersifat opsional dan dapat berupa NULL.

[in] InputBufferLength

Ukuran, dalam byte, dari buffer di InputBuffer. Nilai ini diabaikan jika InputBuffer ADALAH NULL.

[out, optional] OutputBuffer

Pointer ke buffer output yang dialokasikan penelepon tempat informasi dikembalikan dari driver target. Jika FsControlCode menentukan operasi yang tidak menghasilkan data output, penunjuk ini bersifat opsional dan dapat berupa NULL.

[in] OutputBufferLength

Ukuran, dalam byte, dari buffer di OutputBuffer. Nilai ini diabaikan jika OutputBufferADALAH NULL.

Mengembalikan nilai

ZwFsControlFile mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Keterangan

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

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

Kode FSCTL berikut saat ini didokumenkan untuk driver mode kernel:

FSCTL_DELETE_REPARSE_POINT

FSCTL_GET_REPARSE_POINT

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_SET_REPARSE_POINT

Untuk informasi selengkapnya tentang kode FSCTL_XXXX yang ditentukan sistem, lihat bagian "Keterangan" dari entri referensi untuk DeviceIoControl dalam dokumentasi Microsoft Windows SDK.

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 Windows SDK.

Minifilter harus menggunakan FltFsControlFile alih-alih ZwFsControlFile.

Penelepon ZwFsControlFile harus berjalan di IRQL = PASSIVE_LEVEL dan dengan APC kernel khusus diaktifkan.

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

Untuk panggilan dari driver mode kernel, versi **Nt*Xxx*** dan **Zw*Xxx*** dari rutinitas Windows Native System Services dapat berperilaku berbeda dengan 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)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)