IoCancelFileOpen 関数 (ntddk.h)

[アーティクル]
03/08/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> フィールドを 0 に設定する必要があります。

IoCancelFileOpen は、ファイルのハンドルが作成される前に呼び出す必要があります。呼び出し元は、FileObject パラメーターが指すFILE_OBJECT構造体の Flags メンバーをチェックできます。 FO_HANDLE_CREATED フラグが設定されている場合は、ファイルに対して 1 つ以上のハンドルが作成されているため、 IoCancelFileOpen を呼び出しても安全ではありません。

IoCancelFileOpenは、FileObject が指すファイルオブジェクトの Flags メンバーのFO_FILE_OPEN_CANCELLED フラグを設定します。このフラグは、IRP_MJ_CREATE要求が取り消され、このファイルオブジェクトに対してIRP_MJ_CLOSE要求が発行されることを示します。作成操作が取り消されると、その操作は再発行できません。つまり、 IoCreateFileOpen ルーチンを呼び出した場合、STATUS_REPARSEレガシフィルタードライバーから返すことはできません。

ミニフィルターでは、 IoCancelFileOpen の代わりに FltCancelFileOpen を使用する必要があります。

要件

要件	値
サポートされている最小のクライアント	このルーチンは、Microsoft Windows 2000 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	ntddk.h (Ntddk.h、Ntifs.h、Fltkernel.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL