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 して、ファイル オブジェクトの CurrentByteSet フィールドで 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で MDL が指定されている場合は、バッファー 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 用に開かれました。 通常、これは、前の呼び出しで FILE_NO_INTERMEDIATE_BUFFERING CreateOptions フラグを指定して、FltCreateFile、FltCreateFileEx、または ZwCreateFileします。
キャッシュされていない 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 |
| ターゲット プラットフォーム の | 万国 |
| ヘッダー | fltkernel.h (Fltkernel.h を含む) |
| ライブラリ | FltMgr.lib |
| DLL | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |
関連項目
FltAllocatePoolAlignedWithTagの
FltCreateFileの
FltCreateFileExの
FltWriteFileをする