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 して、ファイル オブジェクトの CurrentByteSet フィールドで 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 用に開かれました。 通常、これは、前の呼び出しで FILE_NO_INTERMEDIATE_BUFFERING CreateOptions フラグを指定して、FltCreateFile、FltCreateFileEx、または ZwCreateFileします。
キャッシュされていない I/O では、FltWriteFile に渡されるパラメーター値次の制限が適用されます。
Buffer パラメーターが指すバッファーは、基になるストレージ デバイスの配置要件に従って配置する必要があります。 このようなアラインバッファーを割り当てるには、FltAllocatePoolAlignedWithTag呼び出します。
ByteOffset パラメーターが指すバイト オフセットは、ボリュームのセクター サイズの負でない倍数である必要があります。
Length パラメーターに指定する長さは、ボリュームのセクター サイズの負でない倍数である必要があります。
CallbackRoutine パラメーターの値が NULL でない場合、書き込み操作は非同期的に実行されます。
CallbackRoutine パラメーターの値が NULL の場合、書き込み操作は同期的に実行されます。 つまり、FltWriteFile 書き込み操作が完了するまで待機してから戻ります。 これは、FileObject が指すファイル オブジェクトが非同期 I/O 用に開かれた場合でも当てはまります。
複数のスレッドが同じファイル オブジェクト FltWriteFile を呼び出し、ファイル オブジェクトが同期 I/O 用に開かれた場合、フィルター マネージャーはファイルの I/O のシリアル化を試みません。 この点で、FltWriteFile は ZwWriteFileとは異なります。
必要条件
要件 | 価値 |
---|---|
ターゲット プラットフォーム の | 万国 |
ヘッダー | fltkernel.h (Fltkernel.h を含む) |
ライブラリ | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | PASSIVE_LEVEL |
関連項目
FltAllocatePoolAlignedWithTagの
FltCreateFileの
FltCreateFileExの
FltReadFileの