FltLockUserBuffer function (fltkernel.h)

Article
10/02/2023

The FltLockUserBuffer routine locks the user buffer for a given I/O operation.

Syntax

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parameters

[in] CallbackData

Pointer to the FLT_CALLBACK_DATA callback data structure for the I/O operation.

Return value

FltLockUserBuffer returns STATUS_SUCCESS if it successfully locks the user buffer (or if the buffer was already locked by a previous call to FltLockUserBuffer.) Otherwise, it returns an appropriate NTSTATUS value, such as one of the following:

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer encountered a pool allocation failure. This is an error code.
STATUS_INVALID_PARAMETER	An invalid parameter was encountered. For example, the I/O operation does not have an MDL parameter, or the IRP_MJ_READ or IRP_MJ_WRITE I/O operations have a minor code of IRP_MN_MDL. This is an error code.

Remarks

For best performance, filter drivers should not call FltLockUserBuffer unless absolutely necessary. The performance slowdown is not because of FltLockUserBuffer itself, but rather because of the performance penalty incurred by the subsequent call to MmGetSystemAddressForMdlSafe; see later Remarks for more information.

A minifilter driver can call FltLockUserBuffer to lock the user buffer for one of the following I/O operations:

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 (except with IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (except with IRP_MN_MDL)

FltLockUserBuffer determines the appropriate access method (IoReadAccess, IoWriteAccess, or IoModifyAccess) to apply for the locked buffer based on the type of I/O operation.

FltLockUserBuffer sets the MdlAddress (or OutputMdlAddress) member in the callback data parameter structure (FLT_PARAMETERS) to point to the MDL for the locked pages. If there is no MDL, FltLockUserBuffer allocates one. (Note that FltMgr cannot generate an MDL before the file system does, which is why FltLockUserBuffer returns STATUS_INVALID_PARAMETER for IRP_MJ_READ or IRP_MJ_WRITE with IRP_MN_MDL).

If the callback data parameter structure contains a system buffer (Irp->AssociatedIrp.SystemBuffer) and does not contain a user buffer (Irp->UserBuffer), FltLockUserBuffer locks the system buffer. If there is no MDL for the system buffer, FltLockUserBuffer allocates one.

If the callback data parameter structure contains a user buffer, FltLockUserBuffer probes and locks the user buffer.

The caller can be running in any process context. FltLockUserBuffer automatically locks the buffer in the correct process context.

If FltLockUserBuffer is called from a pre-operation callback routine (PFLT_PRE_OPERATION_CALLBACK) and it allocates an MDL, FltLockUserBuffer sets the FLTFL_CALLBACK_DATA_DIRTY flag in the callback data structure (FLT_CALLBACK_DATA) so that the I/O system frees the MDL when the I/O operation is completed.

To conserve system page table entries (PTEs), FltLockUserBuffer doesn't map the locked pages. After calling FltLockUserBuffer, the caller must call MmGetSystemAddressForMdlSafe, passing the MdlAddress (or OutputMdlAddress) member in the callback data parameter structure as the value of the Mdl parameter, to get a system buffer that represents this memory.

When the callback data structure is freed, the locked buffer is automatically unlocked, and the MDL is freed. The caller should never free the MDL; the I/O system does this automatically.

FltLockUserBuffer can be called for fast I/O and IRP-based operations.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltkernel.h (include Fltkernel.h)
Library	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL