IoCancelFileOpen 函式 (ntddk.h)

發行項
02/29/2024

IoCancelFileOpen 例程可由文件系統篩選驅動程式使用，以關閉篩選驅動程式裝置堆疊中文件系統驅動程式已開啟的檔案。

語法

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

參數

[in] DeviceObject

緊接在篩選驅動程式裝置物件下方之裝置堆疊頂端的指標。

[in] FileObject

要關閉之檔案之檔案物件的指標。

傳回值

無

備註

如果文件系統篩選驅動程式判斷檔案開啟或檔案建立要求必須在較低層級驅動程式完成STATUS_SUCCESS要求之後失敗，它可以使用 IoCancelFileOpen 來關閉較低層級驅動程式所開啟的檔案。

雖然 STATUS_REPARSE 是成功的NTSTATUS值，但不需要呼叫 IoCancelFileOpen 以取得使用 STATUS_REPARSE完成的建立作業，因為此狀態值表示檔案未成功開啟。

成功呼叫 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。

Minifilters 應該使用 FltCancelFileOpen ，而不是 IoCancelFileOpen。

規格需求

需求	值
最低支援的用戶端	此例程適用於 Microsoft Windows 2000 和更新版本。
目標平台	Universal
標頭	ntddk.h (包含 Ntddk.h、Ntifs.h、Fltkernel.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL