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