NTSTATUS
  FltReadFile(
    IN PFLT_INSTANCE  InitiatingInstance,
    IN PFILE_OBJECT  FileObject,
    IN PLARGE_INTEGER  ByteOffset OPTIONAL,
    IN ULONG  Length,
    OUT PVOID  Buffer,
    IN FLT_IO_OPERATION_FLAGS  Flags,
    OUT PULONG  BytesRead OPTIONAL,
    IN PFLT_COMPLETED_ASYNC_IO_CALLBACK  CallbackRoutine OPTIONAL,
    IN PVOID  CallbackContext OPTIONAL
    ); 

参数

InitiatingInstance

Opaque instance pointer for the minifilter driver instance that is initiating the read request. This parameter is required and cannot be NULL.

FileObject

Pointer to a file object for the file that the data is to be read from. This file object must be currently open. Calling FltReadFile 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.

ByteOffset

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, FltReadFile 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 FltReadFile 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, FltReadFile 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.

Length

Size, in bytes, of the buffer that the Buffer parameter points to.

Buffer

Pointer to a caller-allocated buffer that receives the data that is read from the file.

Flags

Bitmask of flags specifying 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 FltReadFile 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.

 

BytesRead

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.

CallbackRoutine

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.

CallbackContext

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. 

返回值

FltReadFile returns the NTSTATUS value that was returned by the file system.

注释

微过滤器调用 FltReadFile 从一个打开的文件中读取数据。

FltReadFile 创建一个读请求并发送到微过滤器驱动挂载的进程后到文件系统。指定的进程之上的挂载进程则收不到读请求。

FltReadFile 在下列条件成立时，准备非缓存I/O：

• 调用者在参数 Flags 中设置了 FLTFL_IO_OPERATION_NON_CACHED 标志；
• 文件对象使用非缓存I/O打开的。通常是在调用 FltCreateFile, FltCreateFileEx, 或 ZwCreateFile 时，在参数CreateOptions 标志中指定了FILE_NO_INTERMEDIATE_BUFFERING 。 

Noncached I/O imposes the following restrictions on the parameter values passed to FltReadFile:

• The buffer that the Buffer parameter points to must be aligned in accordance with the alignment requirement of the underlying storage device. To allocate such an aligned buffer, call FltAllocatePoolAlignedWithTag.
• The byte offset that the ByteOffset parameter points to must be a nonnegative multiple of the volume’s sector size.
• The length specified in the Length parameter must be a nonnegative multiple of the volume’s sector size.

If an attempt is made to read beyond the end of the file, FltReadFile returns an error.

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, FltReadFile 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 FltReadFile 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, FltReadFile differs from ZwReadFile.

Requirements

IRQL: PASSIVE_LEVEL

Headers: Declared in fltkernel.h. Include fltkernel.h.

• 文件(Files，Vista及后续操作系统)
• 实例
• 卷
• 流
• 流句柄（File objects）
• Transactions(Files，Vista及后续操作系统)

除了卷上下文必须在非分页的内存池上分配，其他的既可以在非分页也可以在分页内存池中分配。

过滤管理器在他们挂载的对象删除后、微过滤器驱动实例从卷上解挂载或微过滤器卸载，自动删除相关的上下文。

注册上下文类型

当微过滤器驱动在DriverEntry中调用 FsRegisterFilter时，必须注册好每个要使用的上下文类型。

要注册上下文类型，微过滤器驱动创建一个类型为 FLT_CONTEXT_REGISTRATION 的变长数组。保持在 FLT_REGISTRATION 结构的 ContextRegistration 域中，传递到 FltRegisterFilter 函数的 Registration 参数。数组中的成员的顺序没有关系，但最后一个成员必须是 {FLT_CONTEXT_END}。

对于微过滤器驱动使用到的每一个上下文类型，FLT_CONTEXT_REGISTRATION 结构必须至少提供一个上下文定义。每一个FLT_CONTEXT_REGISTRATION结构定义了上下文的类型、大小和其他信息。

微过滤器驱动调用FltAllocateContext创建一个新的上下文，过滤管理器使用size参数

对于固定大小的上下文，FLT_CONTEXT_REGISTRATION结构的Size成员指定了字节大小，上下文的大小最大为MAXUSHORT(64KB)。0也是一个有效的值。过滤管理器用旁视列表分配固定大小的上下文。

对于不定大小的上下文，Size成员必须设置为FLT_VARIABLE_SIZED_CONTEXTS。过滤管理器直接从分页或非分页的内存池中分配不定长的上下文。

FLT_CONTEXT_REGISTRATION结构的Flags成员，可以指定FLTFL_CONTEXT_REGISTRATION_NO_EXACT_SIZE_MATCH。如果微过滤器驱动使用定长的上下文，并且指定了这个标志，上下文的大小大于等于请求的长度的话，过滤管理器从旁视列表里分配内存。否则上下文大小必须等于请求大小。

对于一个给定的上下文类型，微过滤器驱动可以支持3种固定大小（每一个大小不同）的上下文定义和1种变长定义。【更多信息，参见FLT_CONTEXT_REGISTRATION】

微过滤器驱动支持可选上下文释放前的清理回调例程。【参见 PFLT_CONTEXT_CLEANUP_CALLBACK】

微过滤器驱动可以定义一个他自己的分配、释放回调例程。【参见PFLT_CONTEXT_ALLOCATE_CALLBACK 和 PFLT_CONTEXT_FREE_CALLBACK】。

下面是从CTX示例中的部分代码，展示了一个用于注册实例、文件、流和文件对象（流句柄）的FLT_CONTEXT_REGISTRATION结构数组。