Expand Minimize

FltLockUserBuffer routine

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

Syntax


NTSTATUS FltLockUserBuffer(
  _In_  PFLT_CALLBACK_DATA CallbackData
);

Parameters

CallbackData [in]

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 codeDescription
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

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

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

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft