IoCancelFileOpen 函数 (ntddk.h)

项目
08/07/2023

文件系统筛选器驱动程序可以使用 IoCancelFileOpen 例程关闭文件系统驱动程序在筛选器驱动程序的设备堆栈中打开的文件。

语法

void IoCancelFileOpen(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PFILE_OBJECT   FileObject
);

参数

[in] DeviceObject

指向紧邻筛选器驱动程序的设备对象下方的设备堆栈顶部的指针。

[in] FileObject

指向要关闭的文件的文件对象的指针。

返回值

无

备注

如果文件系统筛选器驱动程序确定在较低级别驱动程序使用 STATUS_SUCCESS 完成请求后，文件打开或文件创建请求必须失败，则它可以使用 IoCancelFileOpen 关闭由较低级别驱动程序打开的文件。

尽管 STATUS_REPARSE 是成功的 NTSTATUS 值，但对于使用 STATUS_REPARSE 完成的创建操作，无需调用 IoCancelFileOpen ，因为此状态值指示文件未成功打开。

成功调用 IoCancelFileOpen 将产生以下效果：对文件系统堆栈中调用方上方的微筛选器和旧筛选器，创建请求似乎已失败。对调用方下方的用户，该文件似乎已打开 (或创建) ，然后关闭。

请注意， IoCancelFileOpen 不会撤消对文件的任何修改。例如， IoCancelFileOpen 不会删除新创建的文件，也不会还原被覆盖或取代到其先前状态的文件。

典型示例如下：

筛选器驱动程序存在于较高级别的筛选器驱动程序和较低级别的文件系统驱动程序之间。
筛选器驱动程序将设备堆栈中的IRP_MJ_CREATE请求传递到文件系统驱动程序，文件系统驱动程序完成状态STATUS_SUCCESS IRP_MJ_CREATE请求。
在筛选器驱动程序完成创建请求之前，它确定必须关闭文件。
筛选器驱动程序使用 IoCancelFileOpen 关闭文件系统驱动程序打开的文件。

调用 IoCancelFileOpen 后，筛选器驱动程序应使用相应的错误代码（如 STATUS_UNSUCCESSFUL 或 STATUS_ACCESS_DENIED）完成创建请求。此外，它应将 Irp-IoStatus.Information> 字段设置为零。

在为文件创建任何句柄之前，必须调用 IoCancelFileOpen。调用方可以检查 FileObject 参数指向的 FILE_OBJECT 结构的 Flags 成员。如果设置了 FO_HANDLE_CREATED 标志，这意味着已为文件创建了一个或多个句柄，因此调用 IoCancelFileOpen 不安全。

IoCancelFileOpen 在 FileObject 指向的文件对象的 Flags 成员中设置FO_FILE_OPEN_CANCELLED标志。此标志指示已取消IRP_MJ_CREATE请求，并将为此文件对象发出IRP_MJ_CLOSE请求。取消创建操作后，无法重新发出创建操作，也就是说，如果旧筛选器驱动程序调用了 IoCreateFileOpen 例程，则无法返回STATUS_REPARSE。

微筛选器应使用 FltCancelFileOpen 而不是 IoCancelFileOpen。

要求

要求	值
最低受支持的客户端	此例程在 Microsoft Windows 2000 及更高版本上可用。
目标平台	通用
标头	ntddk.h (包括 Ntddk.h、Ntifs.h、Fltkernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL