FltReadFileEx 関数 (fltkernel.h)
FltReadFileEx は 、開いているファイル、ストリーム、またはデバイスからデータを読み取ります。 この関数は FltReadFile を 拡張して、マップされたバッファー アドレスではなく、読み取りデータに MDL をオプションで使用できるようにします。
構文
NTSTATUS FLTAPI FltReadFileEx(
[in] PFLT_INSTANCE InitiatingInstance,
[in] PFILE_OBJECT FileObject,
[in, optional] PLARGE_INTEGER ByteOffset,
[in] ULONG Length,
[out] PVOID Buffer,
[in] FLT_IO_OPERATION_FLAGS Flags,
[out, optional] PULONG BytesRead,
[in, optional] PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
[in, optional] PVOID CallbackContext,
[in, optional] PULONG Key,
[in, optional] PMDL Mdl
);
パラメーター
[in] InitiatingInstance
操作の送信先となるミニフィルター ドライバー インスタンスの不透明なインスタンス ポインター。 インスタンスは、ファイルが存在するボリュームにアタッチされている必要があります。 このパラメーターは必須であり、NULL にすることはできません。
[in] FileObject
データの読み取り元となるファイルの FILE_OBJECT へのポインター。 このファイル オブジェクトは現在開いている必要があります。 ファイル オブジェクトがまだ開いていないか、または開かなくなったときに FltReadFileEx を呼び出すと (作成前またはクリーンアップ後のコールバック ルーチンなど)、チェックされたビルドでシステムが ASSERT されます。 このパラメーターは必須であり、NULL にすることはできません。
[in, optional] ByteOffset
読み取り操作を開始するファイル内の開始バイト オフセットを指定する呼び出し元割り当て変数へのポインター。
ByteOffset を指定すると、ファイル オブジェクトの CurrentByteOffset フィールドの現在の値に関係なく、そのオフセットで I/O が実行されます。
- 同期 I/O 用にファイルが開かれた場合 (FO_SYNCHRONOUS_IOファイル オブジェクトの Flags フィールドに設定されている場合、呼び出し元は ByteOffset-LowPart> を FILE_USE_FILE_POINTER_POSITION に設定し、ByteOffset-HighPart> を -1 に設定して、ファイル オブジェクトの CurrentByteOffset フィールドで I/O を実行できます。
- 同期 I/O 用にファイルが開かれなかった場合は、FILE_USE_FILE_POINTER_POSITION を使用するとエラーになります。
ByteOffset が指定されていない場合:
- 同期 I/O 用にファイルが開かれなかった場合は、エラーになります。
- それ以外の場合、I/O はファイル オブジェクトの CurrentByteOffset で実行されます。
同期 I/O 用にファイル オブジェクトが開かれた場合、呼び出し元が FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET フラグを渡さない限り、 CurrentByteOffset フィールドが更新されます。
- 注: この場合も、ファイル システムは CurrentByteOffset を更新します。 フィルター マネージャーは、I/O をスタックに送信する前に CurrentByteOffset 値を保存し、I/O が返されたときに復元します。 FltReadFileEx の呼び出し元 (および高度の高いフィルター) の観点から、CurrrentByteOffset は更新されません。 ただし、呼び出し元の下のフィルターには、読み取り/書き込み後のコールバックで更新された CurrentByteOffset 値が表示されます。
同期 I/O 用にファイル オブジェクトが開かれなかった場合、ByteOffset パラメーターの状態に関係なく、CurrentByteOffset フィールドは更新されません。
[in] Length
Buffer パラメーターが指すバッファーのサイズ (バイト単位)。
[out] Buffer
ファイルから読み取られたデータを受け取る呼び出し元によって割り当てられたバッファーへのポインター。 Mdl に MDL が指定されている場合、 Buffer は NULL である必要があります。
[in] Flags
実行する読み取り操作の種類を指定するフラグのビットマスク。
| フラグ | 説明 |
|---|---|
| FLTFL_IO_OPERATION_DO_NOT_UPDATE_BYTE_OFFSET | ミニフィルター ドライバーは、 FltReadFile が ファイル オブジェクトの CurrentByteOffset フィールドを更新しないように指定するには、このフラグを設定できます。 |
| FLTFL_IO_OPERATION_NON_CACHED | ミニフィルター ドライバーは、ファイル オブジェクトがFILE_NO_INTERMEDIATE_BUFFERINGで開かれていた場合でも、キャッシュされていない読み取りを指定するには、このフラグを設定できます。 |
| FLTFL_IO_OPERATION_PAGING | ミニフィルター ドライバーでは、このフラグを設定して、ページングの読み取りを指定できます。 |
| FLTFL_IO_OPERATION_SYNCHRONOUS_PAGING | ミニフィルター ドライバーでは、同期ページング I/O 読み取りを指定するには、このフラグを設定できます。 このフラグを設定するミニフィルター ドライバーでは、FLTFL_IO_OPERATION_PAGING フラグも設定する必要があります。 Windows Vista 以降で使用できます。 |
[out, optional] BytesRead
ファイルから読み取られたバイト数を受け取る呼び出し元によって割り当てられた変数へのポインター。 CallbackRoutine が NULL でない場合、このパラメーターは無視されます。 それ以外の場合、このパラメーターは省略可能であり、NULL にすることができます。
[in, optional] CallbackRoutine
読み取 り操作が完了したときに呼び出すPFLT_COMPLETED_ASYNC_IO_CALLBACK型指定コールバック ルーチンへのポインター。 このパラメーターは省略可能であり、NULL にすることができます。
[in, optional] CallbackContext
CallbackRoutine に渡されるコンテキスト ポインター (存在する場合)。 このパラメーターは省略可能であり、NULL にすることができます。 CallbackRoutine が NULL の場合、このパラメーターは無視されます。
[in, optional] Key
バイト範囲ロックに関連付けられている省略可能なキー。
[in, optional] Mdl
データが読み取られたメモリを記述するオプションの MDL。 バッファーが Buffer に指定されている場合、Mdl は NULL である必要があります。
戻り値
FltReadFileEx は、ファイル システムによって返された NTSTATUS 値を返します。
注釈
ミニフィルター ドライバーは、開いているファイルからデータを読み取るために FltReadFileEx を呼び出します。
FltReadFileEx は 読み取り要求を作成し、開始インスタンスの下にアタッチされたミニフィルター ドライバー インスタンスとファイル システムに送信します。 指定されたインスタンスと、その上にアタッチされているインスタンスは、読み取り要求を受け取りません。
FltReadFileEx は、次のいずれかが当てはまる場合、キャッシュされていない I/O を実行します。
呼び出し元は Flags パラメーターにFLTFL_IO_OPERATION_NON_CACHED フラグを設定します。
ファイル オブジェクトは、キャッシュされていない I/O 用に開かれました。 通常、これは、FltCreateFile、FltCreateFileEx、または ZwCreateFile の前の呼び出しで、FILE_NO_INTERMEDIATE_BUFFERING CreateOptions フラグを指定することによって行われます。
キャッシュされていない I/O では、 FltReadFileEx に渡されるパラメーター値に次の制限があります。
Buffer パラメーターが指す バッファー は、基になるストレージ デバイスの配置要件に従って配置する必要があります。 このようなアラインバッファーを割り当てるには、 FltAllocatePoolAlignedWithTag を呼び出します。
ByteOffset パラメーターが指すバイト オフセットは、ボリュームのセクター サイズの負でない倍数である必要があります。
Length パラメーターで指定する長さは、ボリュームのセクター サイズの負でない倍数である必要があります。
ファイルの末尾を超えて読み取ろうとすると、 FltReadFileEx はエラーを返します。
CallbackRoutine パラメーターの値が NULL でない場合、読み取り操作は非同期的に実行されます。
CallbackRoutine パラメーターの値が NULL の場合、読み取り操作は同期的に実行されます。 つまり、 FltReadFileEx は読み取り操作が完了するまで待機してから、 を返します。 これは、 FileObject が指すファイル オブジェクトが非同期 I/O 用に開かれた場合でも当てはまります。
複数のスレッドが同じファイル オブジェクトに対して FltReadFileEx を呼び出し、ファイル オブジェクトが同期 I/O 用に開かれた場合、フィルター マネージャーはファイルの I/O のシリアル化を試みません。 この点で、 FltReadFileEx はZwReadFile とは異なります。
Mdl パラメーターは、ミニフィルターに既に MDL が使用可能な場合に便利です。 MDL は直接使用され、 Buffer のアドレスをマッピングする追加の手順は回避できます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 |
| 対象プラットフォーム | ユニバーサル |
| Header | fltkernel.h (Fltkernel.h を含む) |
| Library | FltMgr.lib |
| [DLL] | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示