Fungsi FltLockUserBuffer (fltkernel.h)

Artikel
10/05/2023

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

Sintaks

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] CallbackData

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

Nilai kembali

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:

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid ditemui. 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.

Keterangan

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 yang dikunci. 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, FltLockUserBuffermemeriksa dan mengunci 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 memanggil FltLockUserBuffer, pemanggil harus memanggil MmGetSystemAddressForMdlSafe, melewati anggota MdlAddress (atau OutputMdlAddress) dalam struktur parameter data panggilan balik sebagai nilai parameter Mdl , untuk mendapatkan buffer sistem yang mewakili memori ini.

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

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