FltReadFile 関数 (fltkernel.h)
FltReadFile は 、開いているファイル、ストリーム、またはデバイスからデータを読み取ります。
構文
NTSTATUS FLTAPI FltReadFile(
[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] InitiatingInstance
操作の送信先となるミニフィルター ドライバー インスタンスの不透明なインスタンス ポインター。 インスタンスは、ファイルが存在するボリュームにアタッチする必要があります。 このパラメーターは必須であり、NULL にすることはできません。
[in] FileObject
データの読み取り元となるファイルの FILE_OBJECT へのポインター。 このファイル オブジェクトは現在開いている必要があります。 ファイル オブジェクトがまだ開いていないか、または開かなくなったときに FltReadFile を呼び出すと (作成前またはクリーンアップ後のコールバック ルーチンなど)、システムはチェックされたビルドで 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 が返されたときに復元します。 FltReadFile の呼び出し元 (および高度の高いフィルター) の観点から、CurrrentByteOffset は更新されません。 ただし、呼び出し元の下のフィルターでは、読み取り/書き込み後のコールバックに更新された CurrentByteOffset 値が表示されます。
同期 I/O 用にファイル オブジェクトが開かれなかった場合、ByteOffset パラメーターの状態に関係なく、CurrentByteOffset フィールドは更新されません。
[in] Length
Buffer パラメーターが指すバッファーのサイズ (バイト単位)。
[out] Buffer
ファイルから読み取られたデータを受け取る呼び出し元によって割り当てられたバッファーへのポインター。
[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 の場合、このパラメーターは無視されます。
戻り値
FltReadFile は、 ファイル システムによって返された NTSTATUS 値を返します。
注釈
ミニフィルター ドライバーは FltReadFile を呼び出して、開いているファイルからデータを読み取ります。
FltReadFile は 、読み取り要求を作成し、開始インスタンスの下にアタッチされたミニフィルター ドライバー インスタンスとファイル システムに送信します。 指定されたインスタンスとその上にアタッチされたインスタンスは、読み取り要求を受け取りません。
FltReadFile は、次のいずれかに該当する場合、キャッシュされていない I/O を実行します。
呼び出し元は、 Flags パラメーターにFLTFL_IO_OPERATION_NON_CACHED フラグを設定します。
ファイル オブジェクトは、キャッシュされていない I/O 用に開かれています。 通常、これは、FltCreateFile、FltCreateFileEx、または ZwCreateFile の前の呼び出しで CreateOptions フラグをFILE_NO_INTERMEDIATE_BUFFERING指定することによって行われます。
キャッシュされていない I/O では、 FltReadFile に渡されるパラメーター値に次の制限があります。
Buffer パラメーターが指す バッファー は、基になるストレージ デバイスのアラインメント要件に従って配置する必要があります。 このようなアラインされたバッファーを割り当てるには、 FltAllocatePoolAlignedWithTag を呼び出します。
ByteOffset パラメーターが指すバイト オフセットは、ボリュームのセクター サイズの負でない倍数である必要があります。
Length パラメーターで指定する 長 さは、ボリュームのセクター サイズの負でない倍数である必要があります。
ファイルの末尾を超えて読み取ろうとすると、 FltReadFile はエラーを返します。
CallbackRoutine パラメーターの値が NULL でない場合、読み取り操作は非同期的に実行されます。
CallbackRoutine パラメーターの値が NULL の場合、読み取り操作は同期的に実行されます。 つまり、 FltReadFile は読み取り操作が完了するまで待機してから、 を返します。 これは、 FileObject が指すファイル オブジェクトが非同期 I/O 用に開かれた場合でも当てはまります。
複数のスレッドが同じファイル オブジェクトに対して FltReadFile を呼び出し、ファイル オブジェクトが同期 I/O 用に開かれた場合、フィルター マネージャーはファイルの I/O のシリアル化を試行しません。 この点で、 FltReadFile はZwReadFile と異なります。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | fltkernel.h (Fltkernel.h を含む) |
| Library | FltMgr.lib |
| [DLL] | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |