Fungsi NtFsControlFile (ntifs.h)

Artikel
02/26/2024

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

Sintaks

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [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 NtCreateFile atau NtOpenFile 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 ApcRoutine ADALAH 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.

[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 OutputBuffer ADALAH NULL.

Mengembalikan nilai

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

Keterangan

NtFsControlFile memberikan tampilan yang konsisten dari data input dan output ke sistem dan ke 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 .

Berikut ini adalah beberapa kode FSCTL yang didokumentasikan untuk driver mode kernel:

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

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 dan Kode Kontrol Input dan Output Perangkat.

Minifilter harus menggunakan FltFsControlFile alih-alih NtFsControlFile.

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

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

Untuk panggilan dari driver mode kernel, rutinitas NtXXX dan ZwXXX dari Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menginterpretasikan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXXX dan ZwXXX dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

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, PowerIrpDDis