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