FltCreateFileEx2 関数 (fltkernel.h)

[アーティクル]
03/08/2023

ミニフィルタードライバーは 、FltCreateFileEx2 を呼び出して新しいファイルを作成するか、既存のファイルを開きます。このルーチンには、オプションの create context パラメーター (ECP) が含まれています。

構文

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

パラメーター

[in] Filter

呼び出し元の不透明なフィルターポインター。

[in, optional] Instance

作成要求の送信先となるミニフィルタードライバーインスタンスの不透明なインスタンスポインター。インスタンスは、ファイルまたはディレクトリが存在するボリュームにアタッチされている必要があります。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターが NULL の場合、ボリュームのファイルシステムドライバースタックの上部にあるデバイスオブジェクトに要求が送信されます。このパラメーターが NULL 以外の場合、要求は、指定されたインスタンスの下にアタッチされているミニフィルタードライバーインスタンスにのみ送信されます。

[out] FileHandle

FltCreateFileEx2 の呼び出しが成功した場合にファイルハンドルを受け取る呼び出し元によって割り当てられた変数へのポインター。

[out, optional] FileObject

FltCreateFileEx2 の呼び出しが成功した場合にファイルオブジェクトポインターを受け取る呼び出し元によって割り当てられた変数へのポインター。このパラメーターは省略可能であり、 NULL にすることができます。

[in] DesiredAccess

呼び出し元が必要とするファイルまたはディレクトリへのアクセスの種類を指定するフラグのビットマスク。このパラメーターの詳細とフラグ値の一覧については、IoCreateFileEx の DesiredAccess パラメーターを参照してください。

[in] ObjectAttributes

InitializeObjectAttributes で既に初期化されている不透明なOBJECT_ATTRIBUTES構造体へのポインター。各構造体メンバーの詳細と説明については、IoCreateFileEx の ObjectAttributes パラメーターを参照してください。

[out] IoStatusBlock

最終的 な完了 状態と要求された操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。このパラメーターの詳細については、IoCreateFileEx の IoStatusBlock パラメーターを参照してください。

[in, optional] AllocationSize

必要に応じて、ファイルストリームの初期割り当てサイズをバイト単位で指定します。ファイルが作成、上書き、または置き換えられる場合を除き、0 以外の値は有効になりません。

[in] FileAttributes

1 つ以上のFILE_ATTRIBUTE_XXX フラグを指定します。これは、ファイルを作成、上書き、または上書きする場合に設定するファイル属性を表します。詳細とフラグの一覧については、IoCreateFileEx の FileAttributes パラメーターを参照してください。

[in] ShareAccess

呼び出し元が必要とするファイルへの共有アクセスの種類を 0 または 1、またはフラグの組み合わせとして指定します。詳細とフラグの一覧については、IoCreateFileEx の ShareAccess パラメーターを参照してください。

[in] CreateDisposition

ファイルが既に存在するかどうかに応じて、実行するアクションを決定する値を指定します。使用可能な値の一覧については、IoCreateFileEx の Disposition パラメーターを参照してください。

[in] CreateOptions

ファイルを作成または開くときに適用するオプションを指定します。このパラメーターは、IoCreateFileEx の CreateOptions パラメーターに記載され、説明されているフラグの互換性のある組み合わせです。

[in, optional] EaBuffer

ファイルに適用される拡張属性 (EA) 情報を含む、呼び出し元から提供された FILE_FULL_EA_INFORMATION バッファーへのポインター。

[in] EaLength

EaBuffer の長さ (バイト単位)。

[in] Flags

作成要求の作成時に使用するオプションを指定します。使用可能な オプション の一覧については、 IoCreateFileEx の Options パラメーターを参照してください。

[in, optional] DriverContext

IoInitializeDriverCreateContext によって既に初期化されているIO_DRIVER_CREATE_CONTEXT構造体への省略可能なポインター。

戻り値

FltCreateFileEx2 は、STATUS_SUCCESSまたは適切な NTSTATUS 値を返します。可能なリターンコードの一覧については、「IoCreateFileEx」の「戻り値」セクションを参照してください。

注意

FltCreateFileEx2 は、STATUS_FILE_LOCK_CONFLICTを戻り値として返すか、IoStatusBlock パラメーターによって指されるIO_STATUS_BLOCK構造体の Status メンバーで返される場合があります。これは、NTFS ログファイルがいっぱいで、 FltCreateFileEx2 がこの状況の処理を試みる間にエラーが発生した場合にのみ発生します。

注釈

FltCreateFileEx2 は、DriverContext 入力パラメーターをサポートする点を除き、FltCreateFile および FltCreateFileEx に似ています。

作成操作の一部として ECP を指定するには、FltAllocateExtraCreateParameterList ルーチンを使用して、IO_DRIVER_CREATE_CONTEXT構造体の ExtraCreateParameter メンバーを初期化します。 ECP を使用する場合は、適切なルーチンを使用して作成、操作、解放する必要があります。

FltCreateFileEx2 の呼び出し元の下にあるフィルタードライバーは、呼び出し元の ECP を追加または削除しないでください。したがって、 FltCreateFileEx2 の呼び出しから戻ると、ECP リストは変更されず、他の作成操作のために FltCreateFileEx2 の追加の呼び出しに渡される可能性があります。オペレーティングシステムは ECP リスト構造の割り当てを自動的に解除しないことに注意してください。 FltCreateFileEx2 の 呼び出し元は 、FltFreeExtraCreateParameterList ルーチンを呼び出して、この構造体の割り当てを解除する必要があります。

トランザクションのコンテキストでファイルを作成または開くには、IO_DRIVER_CREATE_CONTEXT構造体の TxnParameters メンバーを IoGetTransactionParameterBlock ルーチンによって返される値に設定します。

FltCreateFileEx2 は、指定されたミニフィルタードライバーインスタンスの下にアタッチされたインスタンスとファイルシステムにのみ作成要求を送信します。指定したインスタンスとその上にアタッチされたインスタンスは、作成要求を受け取りません。インスタンスが指定されていない場合、要求はスタックの先頭に移動し、すべてのインスタンスとファイルシステムによって受信されます。

FltCreateFileEx2 を使用して作成または開くファイルの名前を指定するには、次の 2 つの方法があります。

完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
入力 ObjectAttributes の RootDirectory メンバーのハンドルによって表されるディレクトリファイルを基準とするパス名。

FltCreateFileEx2 から取得した FileHandle は、最終的に FltClose を呼び出して解放する必要があります。さらに、返される FileObject ポインターは、 ObDereferenceObject を呼び出すことによって不要になったときに逆参照する必要があります。

システムプロセスコンテキストで実行されないドライバールーチンは、FltCreateFileEx2 の ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性を設定する必要があります。この属性を設定すると、 FltCreateFileEx2 によって返されるハンドルの使用が、カーネルモードで実行されているプロセスに制限されます。それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。

注意

NULL 以外の最上位レベルの IRP 値を使用してこのルーチンを呼び出さないでください。これにより、システムのデッドロックが発生する可能性があります。

特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。

呼び出し元が、返された FileHandle が Signaled 状態に設定されるのを待って I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。
FILE_APPEND_DATAフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込み要求に関するオフセット情報は無視されます。ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。
ファイルのFILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込み要求も発生します。ファイルは、この種類の書き込み要求にも自動的に拡張されます。
FILE_EXECUTEフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は FileHandle パラメーターで返されたハンドルを使用して、ファイルとの間でデータを直接読み取ったり書き込んだりすることはできません。つまり、ファイルに対するすべての操作では、システムページング I/O を使用してファイルデータの読み取りまたは書き込みを行う必要があります。

ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。両方のファイル・オープン機能が、指定された方法でファイルにアクセスする特権を持っている場合は、ファイルを正常に開いて共有できます。 FltCreateFileEx2 の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定していない場合、元の呼び出し元にはファイルへの排他的アクセス権が与えられているため、ファイルに対して他の開いている操作を実行することはできません。

共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess が、FltClose でまだリリースされていない、上記のすべてのオープン要求の DesiredAccess 仕様と ShareAccess 仕様の両方と互換性がある必要があります。つまり、特定のファイルに対して FltCreateFileEx2 に指定された DesiredAccess パラメーターは、ファイルの他の opener が許可していないアクセスと競合しないようにする必要があります。

注意

flags パラメーターにIO_IGNORE_SHARE_ACCESS_CHECKが指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。ただし、ファイルシステムは引き続きアクセスチェックを実行する可能性があります。したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、 ShareAccessパラメーターに必要な共有モードを指定することが重要です。さらに、IO_IGNORE_SHARE_ACCESS_CHECKが指定されている場合、ファイルシステムは現在開いている目的のアクセスまたは共有アクセスを追跡しないことに注意してください。このため、同じファイルに対する後続のオープン呼び出しは成功する可能性があります。

CreateDisposition 値FILE_SUPERSEDE、呼び出し元が既存のファイルオブジェクトに対する DELETE アクセス権を持っている必要があります。その場合、既存のファイルに対する FILE_SUPERSEDE を使用して FltCreateFileEx2 を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。これは、ファイルが既に別のスレッドによって開かれている場合は、FILE_SHARE_DELETE フラグが設定された ShareAccessパラメーターを指定してファイルを開くことを意味します。この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。

CreateDisposition の値FILE_OVERWRITE_IFとFILE_SUPERSEDEは似ています。 FltCreateFileEx2 が既存のファイルで呼び出され、これらの CreateDisposition 値のいずれかが呼び出された場合、ファイルは置き換えられます。

ファイルの上書きは、次を除き、置き換え操作と意味的に同等です。

呼び出し元は、アクセス権を削除するのではなく、ファイルへの書き込みアクセス権を持っている必要があります。これは、ファイルが既に別のスレッドによって開かれている場合は、入力 ShareAccess パラメーターに FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
指定されたファイル属性は、ビットごとの OR 演算を使用してファイルに既に適用されている属性と組み合わされます。これは、ファイルが既に別のスレッドによって開かれている場合、 FltCreateFileEx2 の後続の呼び出し元は既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。このファイルの上書きスタイルは、MS-DOS、Windows 3.1、OS/2 と一致することに注意してください。

CreateOptions FILE_DIRECTORY_FILE値は、作成または開くファイルがディレクトリファイルであることを指定します。ディレクトリファイルが作成されると、ファイルシステムはディスク上に適切な構造を作成し、その特定のファイルシステムのディスク上の構造の空のディレクトリを表します。このオプションが指定されていて、開く指定されたファイルがディレクトリファイルではない場合、または呼び出し元が一貫性のない CreateOptions または CreateDisposition 値を指定した場合、 FltCreateFileEx2 の呼び出しは失敗します。

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイルシステムが呼び出し元の代わりに中間バッファリングを実行できなくなります。この値を指定すると、呼び出し元のパラメーターに特定の制限が他の Flt に設定されます。ファイル ルーチンまたは Zw..ファイル ルーチン(次を含む):

FltReadFile、ZwReadFile、FltWriteFile、または ZwWriteFile の ByteOffset パラメーターに渡されるバイトオフセット値は、セクターサイズの倍数である必要があります。
FltReadFile、ZwReadFile、FltWriteFile、または ZwWriteFile に渡される Length パラメーターは、セクターサイズの倍数である必要があります。長さがセクターサイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有意なバイト数が少なくなる可能性があることに注意してください。
バッファーは、基になるストレージデバイスの配置要件に従って配置する必要があります。この情報を取得するには、FltCreateFileEx2 を呼び出して物理デバイスを表すファイルオブジェクトのハンドルを取得し、そのハンドルで ZwQueryInformationFile を呼び出し、FileInformationClass パラメーターの値として FileAlignmentInformation を指定します。 Ntifs.h で定義されているシステム FILE_XXX_ALIGNMENT 値の詳細については、「デバイスオブジェクトのDEVICE_OBJECTと初期化」を参照してください。
FileInformationClass パラメーターを FilePositionInformation に設定して FltSetInformationFile または ZwSetInformationFile を呼び出すには、セクターサイズの倍数であるオフセットを指定する必要があります。

CreateOptions FILE_SYNCHRONOUS_IO_ALERTフラグとFILE_SYNCHRONOUS_IO_NONALERT フラグは、名前が示すように相互に排他的であり、同期 I/O 用にファイルを開くように指定します。つまり、返された FileHandle が参照するファイルオブジェクトを介して行われる限り、ファイルに対するすべての I/O 操作は同期的になります。このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドにわたってシリアル化されます。これらの CreateOptions フラグのいずれかを設定すると、I/O マネージャーは、ファイルオブジェクトの CurrentByteOffset フィールド内の現在のファイル位置オフセットを保持します。このオフセットは、ZwReadFile と ZwWriteFile の呼び出しで使用できます。また、 ZwQueryInformationFile または ZwSetInformationFile を呼び出してクエリまたは設定することもできます。

CreateOptions FILE_OPEN_REPARSE_POINT フラグが指定されておらず、FltCreateFileEx2 が再解析ポイントを使用してファイルを開こうとした場合、ファイルに対して通常の再解析ポイント処理が行われます。一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行 われず 、 FltCreateFileEx2 は再解析ポイントファイルを直接開こうとします。どちらの場合も、開いている操作が成功した場合、 FltCreateFileEx2 は STATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラーコードを返します。 FltCreateFileEx2 はSTATUS_REPARSEを返しません。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サードパーティがファイルを開いて共有違反を取得できる可能性のある oplock を要求するまでの時間が不要になります。アプリケーションでは、 FltCreateFileEx2 で FILE_OPEN_REQUIRING_OPLOCK フラグを使用し、任意の oplock を要求できます。これにより、oplock 所有者に、共有違反の原因となる後で開いている要求が確実に通知されます。

Windows 7 では、アプリケーションが FILE_OPEN_REQUIRING_OPLOCK フラグを使用するときにファイルに他のハンドルが存在する場合、作成操作はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。この制限は、Windows 8以降は存在しません。

この作成操作によってファイルに既に存在する oplock が中断される場合、FILE_OPEN_REQUIRING_OPLOCK フラグを設定すると、作成操作は STATUS_CANNOT_BREAK_OPLOCK で失敗します。この作成操作では、既存の oplock は破損しません。

このフラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。または、一般的な oplock 処理の利点なしに、ファイルを開こうとするすべての試行がブロックされます。同様に、この呼び出しが成功しても後の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後、ハンドルを閉じる必要があります。

注意

FILE_OPEN_REQUIRING_OPLOCK フラグは、Windows 7、Windows Server 2008 R2 以降の Windows オペレーティングシステムで使用できます。 Windows 7 でこのフラグを実装する Microsoft ファイルシステムは、NTFS、FAT、exFAT です。

CreateOptions フラグ FILE_RESERVE_OPFILTERを使用すると、アプリケーションはレベル 1、バッチ、またはフィルター oplock を要求して、他のアプリケーションで共有違反が発生しないようにすることができます。ただし、FILE_RESERVE_OPFILTERは、フィルター操作ロックに対してのみ実用的に役立ちます。これを使用するには、次の手順を実行する必要があります。

CreateOptions が FILE_RESERVE_OPFILTER、DesiredAccess が正確にFILE_READ_ATTRIBUTES、ShareAccess が正確にFILE_SHARE_READで作成要求を発行する |FILE_SHARE_WRITE |FILE_SHARE_DELETE。
- 既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。
- より多くのアクセス権またはより少ない共有で開くと、STATUS_OPLOCK_NOT_GRANTEDのエラーも発生します。
作成要求が成功した場合は、oplock を要求します。
ファイルの別のハンドルを開いて I/O を実行します。

NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイルシステムです。

ミニフィルタードライバーでは、ファイルの名前を変更するには、ZwSetInformationFile ではなく FltSetInformationFile を使用する必要があります。

注意

ボリュームを開こうとしても、 DesiredAccess パラメーターに対して次のフラグの組み合わせを指定した場合、 FltCreateFileEx2 は、ボリュームのストレージデバイスに直接アクセスできるハンドルをファイルシステムに関係なく開きます。

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

FltCreateFileEx2 を使用して、ボリュームのストレージデバイスに直接アクセスできるハンドルを開かないようにするか、システムリソースをリークさせる必要があります。ストレージデバイスに直接アクセスできるハンドルを開く場合は、代わりに IoCreateFileEx、 IoCreateFileSpecifyDeviceObjectHint、または ZwCreateFile 関数を 呼び出します。

FltCreateFileEx2 の呼び出し元がボリュームターゲットの再解析を有効にしたい場合は、FLT_CREATEFILE_TARGET_ECP_CONTEXTを DriverContext パラメーターの ECP リストに ECP として含めることができます。この ECP が存在する場合、 FltCreateFileEx2 は作成操作のターゲットデバイスを調整し、指定されたファイル情報に適したボリュームのフィルター処理されたインスタンスを検索しようとします。この ECP の使用は、Windows 8 以降で使用できます。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (FltKernel.h を含む)
Library	Fltmgr.lib
IRQL	PASSIVE_LEVEL