Fungsi ZwFsControlFile (ntifs.h)

Artikel
12/21/2024

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

Sintaksis

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 Event, 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 NULL. Ini harus NULL jika pemanggil akan menunggu FileHandle diatur ke status Sinyal.

[in, optional] ApcRoutine

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

[in, optional] ApcContext

Penunjuk ke area konteks yang ditentukan pemanggil. Nilai parameter ini digunakan sebagai konteks APC jika pemanggil menyediakan 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 salah 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 NULL. Ini harus NULL jika ApcRoutine NULL dan tidak ada objek penyelesaian I/O yang terkait dengan objek file.

[out] IoStatusBlock

Penunjuk 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 informasi anggota struktur ini.

[in] FsControlCode

FSCTL_kode XXX yang menunjukkan operasi kontrol sistem file mana yang akan dilakukan. Nilai parameter ini menentukan format dan panjang yang diperlukan dari InputBuffer dan OutputBuffer, serta pasangan parameter mana yang diperlukan. Untuk informasi terperinci tentang kode FSCTL_XXX yang ditentukan sistem, lihat bagian "Komentar" 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 yang akan diberikan kepada driver target. Jika FsControlCode menentukan operasi yang tidak memerlukan data input, pointer ini bersifat opsional dan dapat NULL.

[in] InputBufferLength

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

[out, optional] OutputBuffer

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

[in] OutputBufferLength

Ukuran, dalam byte, buffer di OutputBuffer. Nilai ini diabaikan jika OutputBufferNULL.

Mengembalikan nilai

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

Komentar

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 tergantung driver untuk menentukan antarmuka komunikasi.

Jika penelepon membuka file untuk I/O asinkron (tanpa opsi FILE_SYNCHRONOUS_XXX buat/buka), peristiwa yang ditentukan, jika ada, akan diatur ke status yang disinyalir saat operasi kontrol perangkat selesai. Jika tidak, objek file yang ditentukan oleh FileHandle akan diatur ke status yang disinyalir. Jika ApcRoutine ditentukan, itu dipanggil dengan ApcContext dan pointer 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 XXX FSCTL_yang ditentukan sistem, lihat bagian "Keterangan" dari entri referensi untuk DeviceIoControl dalam dokumentasi Microsoft Windows SDK.

Untuk informasi selengkapnya tentang kode IOCTL_XXX yang ditentukan sistem, dan tentang menentukan nilai IOCTL_ XXX khusus driver atau XXX FSCTL_, 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 yang 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

Syarat	Nilai
klien minimum yang didukung	Windows 2000.
Platform Target	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (lihat bagian Keterangan)
aturan kepatuhan DDI	HwStorPortProhibitedDIs (storport), PowerIrpDDis(wdm)