Download EaseFilter Filter Driver SDK Setup File Download EaseFilter Filter Driver SDK Zip File
FltReadFileEx reads data from an open file, stream, or device. This function extends FltReadFile to allow the optional use of an MDL for read data instead of a mapped buffer address.
NTSTATUS FLTAPI FltReadFileEx( PFLT_INSTANCE InitiatingInstance, PFILE_OBJECT FileObject, PLARGE_INTEGER ByteOffset, ULONG Length, PVOID Buffer, FLT_IO_OPERATION_FLAGS Flags, PULONG BytesRead, PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine, PVOID CallbackContext, PULONG Key, PMDL Mdl );
An opaque instance pointer for the minifilter driver instance that is initiating the read request. This parameter is required and cannot be NULL.
A pointer to a file object for the file that the data is to be read from. This file object must be currently open. Calling FltReadFileEx when the file object is not yet open or is no longer open (for example, in a pre-create or post-cleanup callback routine) causes the system to ASSERT on a checked build. This parameter is required and cannot be NULL.
A pointer to a caller-allocated variable that specifies the starting byte offset within the file where the read operation is to begin.
If this offset is supplied, or if the FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET flag is specified in the Flags parameter, FltReadFileEx does not update the file object's CurrentByteOffset field.
If the file object that FileObject points to was opened for synchronous I/O, the caller of FltReadFileEx can specify that the current file position offset be used instead of an explicit ByteOffset value by setting this parameter to NULL. If the current file position is used, FltReadFileEx updates the file object's CurrentByteOffset field by adding the number of bytes read when it completes the read operation.
If the file object that FileObject points to was opened for asynchronous I/O, this parameter is required and cannot be NULL.
The size, in bytes, of the buffer that the Buffer parameter points to.
A pointer to a caller-allocated buffer that receives the data that is read from the file. If an MDL is provided in Mdl, Buffer must be NULL.
A bitmask of flags that specify the type of read operation to be performed.
|FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET||Minifilter drivers can set this flag to specify that FltReadFileEx should not update the file object's CurrentByteOffset field.|
|FLTFL_IO_OPERATION_NON_CACHED||Minifilter drivers can set this flag to specify a noncached read, even if the file object was not opened with FILE_NO_INTERMEDIATE_BUFFERING.|
|FLTFL_IO_OPERATION_PAGING||Minifilter drivers can set this flag to specify a paging read.|
|FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING||Minifilter drivers can set this flag to specify a synchronous paging I/O read. Minifilter drivers that set this flag must also set the FLTFL_IO_OPERATION_PAGING flag.
This flag is available for Windows Vista and later versions of the Windows operating system.
A pointer to a caller-allocated variable that receives the number of bytes read from the file. If CallbackRoutine is not NULL, this parameter is ignored. Otherwise, this parameter is optional and can be NULL.
A pointer to a PFLT_COMPLETED_ASYNC_IO_CALLBACK-typed callback routine to call when the read operation is complete. This parameter is optional and can be NULL.
A context pointer to be passed to the CallbackRoutine if one is present. This parameter is optional and can be NULL. If CallbackRoutine is NULL, this parameter is ignored.
An optional key associated with a byte range lock.
An optional MDL that describes the memory where the data is read. If a buffer is provided in Buffer , then Mdl must be NULL.
FltReadFileEx returns the NTSTATUS value that was returned by the file system.
A minifilter driver calls FltReadFileEx to read data from an open file.
FltReadFileEx creates a read request and sends it to the minifilter driver instances attached below the initiating instance, and to the file system. The specified instance and the instances attached above it do not receive the read request.
FltReadFileEx performs noncached I/O if either of the following is true:
If the value of the CallbackRoutine parameter is not NULL, the read operation is performed asynchronously.
If the value of the CallbackRoutine parameter is NULL, the read operation is performed synchronously. That is, FltReadFileEx waits until the read operation is complete before returning. This is true even if the file object that FileObject points to was opened for asynchronous I/O.
If multiple threads call FltReadFileEx for the same file object, and the file object was opened for synchronous I/O, the filter manager does not attempt to serialize I/O on the file. In this respect, FltReadFileEx differs from ZwReadFile.
The Mdl parameter is provided as a convenience when a minifilter already has an MDL available. The MDL is used directly and the additional step of mapping an address for Buffer can be avoided.
|Minimum supported client||The FltReadFileEx function is available starting with Windows 8.|
|Header||fltkernel.h (include Fltkernel.h)|