Fungsi FltLockUserBuffer (fltkernel.h)

Artikel
07/16/2024

FltLockUserBuffer rutin mengunci buffer pengguna untuk operasi I/O tertentu.

Sintaksis

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] CallbackData

Arahkan ke struktur data panggilan balik FLT_CALLBACK_DATA untuk operasi I/O.

Mengembalikan nilai

FltLockUserBuffer mengembalikan STATUS_SUCCESS jika berhasil mengunci buffer pengguna (atau jika buffer sudah dikunci oleh panggilan sebelumnya ke FltLockUserBuffer.) Jika tidak, nilai NTSTATUS yang sesuai akan ditampilkan, seperti salah satu hal berikut ini:

Mengembalikan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditemukan. Misalnya, operasi I/O tidak memiliki parameter MDL, atau operasi I/O IRP_MJ_READ atau IRP_MJ_WRITE memiliki kode kecil IRP_MN_MDL. Ini adalah kode kesalahan.

Komentar

Untuk performa terbaik, driver filter tidak boleh memanggil FltLockUserBuffer kecuali benar-benar diperlukan. Perlambatan performa bukan karena FltLockUserBuffer itu sendiri, melainkan karena penalti performa yang dikeluarkan oleh panggilan berikutnya ke MmGetSystemAddressForMdlSafe; lihat Keterangan selanjutnya untuk informasi selengkapnya.

Driver minifilter dapat memanggil FltLockUserBuffer untuk mengunci buffer pengguna untuk salah satu operasi I/O berikut:

IRP_MJ_DEVICE_CONTROL
IRP_MJ_DIRECTORY_CONTROL
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_QUERY_EA
IRP_MJ_QUERY_QUOTA
IRP_MJ_QUERY_SECURITY
IRP_MJ_READ (kecuali dengan IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (kecuali dengan IRP_MN_MDL)

FltLockUserBuffer menentukan metode akses yang sesuai (IoReadAccess, IoWriteAccess, atau IoModifyAccess) untuk diterapkan pada buffer terkunci berdasarkan jenis operasi I/O.

FltLockUserBuffer mengatur anggota MdlAddress (atau OutputMdlAddress) dalam struktur parameter data panggilan balik (FLT_PARAMETERS) untuk menunjuk ke MDL untuk halaman terkunci. Jika tidak ada MDL, FltLockUserBuffer mengalokasikannya. (Perhatikan bahwa FltMgr tidak dapat menghasilkan MDL sebelum sistem file melakukannya, itulah sebabnya FltLockUserBuffer mengembalikan STATUS_INVALID_PARAMETER untuk IRP_MJ_READ atau IRP_MJ_WRITE dengan IRP_MN_MDL).

Jika struktur parameter data panggilan balik berisi buffer sistem (Irp->AssociatedIrp.SystemBuffer) dan tidak berisi buffer pengguna (Irp->UserBuffer), FltLockUserBuffer mengunci buffer sistem. Jika tidak ada MDL untuk buffer sistem, FltLockUserBuffer mengalokasikannya.

Jika struktur parameter data panggilan balik berisi buffer pengguna, FltLockUserBufferpemeriksaan dan kunci buffer pengguna.

Pemanggil dapat berjalan dalam konteks proses apa pun. FltLockUserBuffer secara otomatis mengunci buffer dalam konteks proses yang benar.

Jika FltLockUserBuffer dipanggil dari rutinitas panggilan balik pra-operasi (PFLT_PRE_OPERATION_CALLBACK) dan mengalokasikan MDL, FltLockUserBuffer mengatur bendera FLTFL_CALLBACK_DATA_DIRTY dalam struktur data panggilan balik (FLT_CALLBACK_DATA) sehingga sistem I/O membebaskan MDL ketika operasi I/O selesai.

Untuk menghemat entri tabel halaman sistem (PTEs), FltLockUserBuffer tidak memetakan halaman terkunci. Setelah memanggilFltLockUserBuffer , pemanggil harus memanggil MmGetSystemAddressForMdlSafe, melewati MdlAdd (atau anggota OutputMdlAddress) dalam struktur parameter data panggilan balik sebagai nilai parameter Mdl, untuk mendapatkan buffer sistem yang mewakili memori ini.

Ketika struktur data panggilan balik dibebaskan, buffer terkunci secara otomatis tidak terkunci, dan MDL dibebaskan. Pemanggil tidak boleh membebaskan MDL; sistem I/O melakukan ini secara otomatis.

FltLockUserBuffer dapat dipanggil untuk operasi berbasis I/O dan IRP yang cepat.