FltCreateFile 関数 (fltkernel.h)

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

構文

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

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

[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 パラメーターを参照してください。

戻り値

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

注釈

Microsoft Windows Update Rollup for Windows 2000 SP4 および Windows Server 2003 SP1 より前のバージョンの Windows では、ミニフィルター ドライバーは IoCreateFile、IoCreateFileSpecifyDeviceObjectHint、または ZwCreateFile ではなく FltCreateFile を呼び出して、ZwReadFile や ZwQueryInformationFile などの ZwXxx I/O ルーチンで使用するファイル ハンドルを取得する必要があります。

Windows 2000 SP4、Windows Server 2003 SP1 以降の Microsoft Windows Update ロールアップでは、ミニフィルター ドライバーは FltCreateFileEx を使用して、FltReadFile や FltWriteFile などの FltXxxファイル ルーチンで使用するファイル オブジェクト ポインターを取得できます。 以前のバージョンの Windows では、 FltCreateFile から取得したハンドルは、次のように ObReferenceObjectByHandle を呼び出すことによってファイル オブジェクト ポインターに変換できます。

status = ObReferenceObjectByHandle(
           handle,                 //Handle
           0,                      //DesiredAccess
           NULL,                   //ObjectType
           KernelMode,             //AccessMode
           &handleFileObject,      //Object
           NULL);                  //HandleInformation</pre>

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

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

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

FltCreateFile から取得したハンドルは、FltClose を呼び出して最終的に解放する必要があります。

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

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

• 呼び出し元が、返された FileHandle が Signaled 状態に設定されるのを待って I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。

• FILE_APPEND_DATAフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。

• ファイルのFILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも行われます。 ファイルは、この種類の書き込みでも自動的に拡張されます。

• FILE_EXECUTEフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandle を 使用して、ファイルとの間でデータを直接読み書きすることはできません。 つまり、ファイルに対するすべての操作では、システム ページング I/O を使用してファイル データの読み取りまたは書き込みを行う必要があります。

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

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

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

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

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

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

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

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

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

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

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

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求する時間がなくなります。 アプリケーションは FltCreateFile で 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 要求が失敗したことを検出した後でハンドルを閉じる必要があります。

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

1. 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のエラーも発生します。

2. 作成要求が成功した場合は、oplock を要求します。

3. ファイルへの別のハンドルを開いて I/O を実行します。

手順 3 では、これはフィルター 操作に対してのみ実用的です。 手順 3 で開いたハンドルには、最大FILE_READ_ATTRIBUTES | を含む DesiredAccess を含めることができます。FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROLし、フィルター oplock を中断しません。 ただし、desiredAccess が FILE_READ_ATTRIBUTES より大きい場合 |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチ oplock が中断され、FILE_RESERVE_OPFILTER フラグがこれらの oplock 型では役に立たなくなります。

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

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

要件

こちらもご覧ください

ACCESS_MASK

ACL

DEVICE_OBJECT

FILE_FULL_EA_INFORMATION

FltClose

FltCreateFileEx

FltCreateFileEx2

FltReadFile

FltWriteFile

InitializeObjectAttributes

IoCreateFile

IoCreateFileSpecifyDeviceObjectHint

ObReferenceObjectByHandle

SECURITY_DESCRIPTOR

UNICODE_STRING

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile