FltLockUserBuffer function

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

Syntax

NTSTATUS FLTAPI FltLockUserBuffer(
  PFLT_CALLBACK_DATA CallbackData
);

Parameters

CallbackData

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

Return Value

If the user buffer is successfully locked, FltLockUserBuffer returns STATUS_SUCCESS. (This is the case even 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
The I/O operation is not one of the operations listed in the following Remarks section. This is an error code.

Remarks

A minifilter driver calls 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

  • IRP_MJ_SET_EA

  • IRP_MJ_SET_QUOTA

  • IRP_MJ_WRITE

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.

If the callback data parameter structure contains a system buffer and does not contain a user buffer, FltLockUserBuffer locks the system buffer. If there is no MDL for the system buffer, FltLockUserBuffer allocates one.

If FltLockUserBuffer is called from a preoperation 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 (PTE), FltLockUserBuffer does not 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.

Use of FltLockUserBuffer can slow system performance. This is not because of FltLockUserBuffer itself, but rather because of the performance penalty incurred by MmGetSystemAddressForMdlSafe.

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

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

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

See Also

FLT_CALLBACK_DATA

FLT_IS_FASTIO_OPERATION

FLT_IS_IRP_OPERATION

FLT_IS_SYSTEM_BUFFER

FLT_PARAMETERS

FLT_PARAMETERS for IRP_MJ_DEVICE_CONTROL and IRP_MJ_INTERNAL_DEVICE_CONTROL

FLT_PARAMETERS for IRP_MJ_DIRECTORY_CONTROL

FLT_PARAMETERS for IRP_MJ_FILE_SYSTEM_CONTROL

FLT_PARAMETERS for IRP_MJ_QUERY_EA

FLT_PARAMETERS for IRP_MJ_QUERY_QUOTA

FLT_PARAMETERS for IRP_MJ_QUERY_SECURITY

FLT_PARAMETERS for IRP_MJ_READ

FLT_PARAMETERS for IRP_MJ_SET_EA

FLT_PARAMETERS for IRP_MJ_SET_QUOTA

FLT_PARAMETERS for IRP_MJ_WRITE

FltDecodeParameters

MmGetSystemAddressForMdlSafe

PFLT_POST_OPERATION_CALLBACK

PFLT_PRE_OPERATION_CALLBACK