FltLockUserBuffer function (fltkernel.h)
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 |
See also
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