The FltLockUserBuffer routine locks the user buffer for a given I/O operation.
- CallbackData [in]
Pointer to the callback data structure for the I/O operation (FLT_CALLBACK_DATA).
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:
FltLockUserBuffer encountered a pool allocation failure. This is an error code.
The I/O operation is not one of the operations listed in the following Remarks section. This is an error code.
A minifilter driver calls FltLockUserBuffer to lock the user buffer for one of the following I/O operations:
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.
- 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