FltCreateFileEx 関数 (fltkernel.h)

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

ミニフィルタードライバーは 、FltCreateFileEx を呼び出して、新しいファイルを作成するか、既存のファイルを開きます。

構文

NTSTATUS FLTAPI FltCreateFileEx(
  [in]           PFLT_FILTER        Filter,
  [in, optional] PFLT_INSTANCE      Instance,
  [out]          PHANDLE            FileHandle,
  [out]          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] Filter

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

[in, optional] Instance

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

[out] FileHandle

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

[out] FileObject

FltCreateFileEx の呼び出しが成功した場合にファイルオブジェクトポインターを受け取る呼び出し元によって割り当てられた変数へのポインター。このパラメーターは省略可能であり、 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 パラメーターを参照してください。

戻り値

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

注意

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

注釈

ファイルシステムミニフィルタードライバーは、FltCreateFile ではなく FltCreateFileEx を呼び出して、FltReadFile や FltQueryInformationFile などの FltXxx I/O ルーチンで使用するファイルオブジェクトポインターを取得する必要があります。

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

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

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

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

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

注意

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

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

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

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

共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess が、FltClose でまだリリースされていない上記のすべてのオープンの DesiredAccess 仕様と ShareAccess 仕様の両方と互換性がある必要があります。つまり、特定のファイルに対して FltCreateFileEx に指定された 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を使用して FltCreateFileEx を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。これは、ファイルが既に別のスレッドによって開かれている場合は、FILE_SHARE_DELETE フラグが設定された ShareAccess パラメーターを指定してファイルを開くことを意味します。この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。

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

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

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

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

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

FltReadFile、ZwReadFile、FltWriteFile、または ZwWriteFile に渡されるバイト オフセット値は、セクターサイズの倍数である必要があります。
FltReadFile、ZwReadFile、FltWriteFile、または ZwWriteFile に渡される長さは、セクターサイズの倍数である必要があります。長さがセクターサイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有意なバイト数が少なくなる可能性があることに注意してください。
バッファーは、基になるストレージデバイスの配置要件に従って配置する必要があります。この情報を取得するには、 FltCreateFileEx を呼び出して物理デバイスを表すファイルオブジェクトのハンドルを取得し、そのハンドル で ZwQueryInformationFile を呼び出し、FileAlignmentInformation を FileInformationClass として指定します。 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 フラグが指定されておらず、FltCreateFileEx が再解析ポイントを使用してファイルを開こうとした場合、ファイルに対して通常の再解析ポイント処理が行われます。一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行われず、 FltCreateFileEx は再解析ポイントファイルを直接開こうとします。どちらの場合も、開いている操作が成功した場合、 FltCreateFileEx はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラーコードを返します。 FltCreateFileEx は STATUS_REPARSEを返しません。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サードパーティがファイルを開いて共有違反を取得できる可能性のある oplock を要求するまでの時間が不要になります。アプリケーションでは、 FltCreateFileEx で 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

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

要件

要件	値
サポートされている最小のクライアント	Microsoft Windows 2000 Update Rollup 1 for SP4、Windows XP SP3、Windows Server 2003 SP1、およびそれ以降のバージョンの Windows オペレーティングシステムで使用できます。
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (FltKernel.h を含む)
Library	Fltmgr.lib
IRQL	PASSIVE_LEVEL