FltLockUserBuffer 関数 (fltkernel.h)

[アーティクル]
10/05/2023

FltLockUserBuffer ルーチンは、特定の I/O 操作のユーザーバッファーをロックします。

構文

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

パラメーター

[in] CallbackData

I/O 操作の FLT_CALLBACK_DATA コールバックデータ構造へのポインター。

戻り値

FltLockUserBuffer は 、ユーザーバッファーを正常にロックした場合 (または FltLockUserBuffer の以前の呼び出しによってバッファーが既にロックされている場合) にSTATUS_SUCCESSを返します。それ以外の場合は、次のいずれかの適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer でプール割り当てエラーが発生しました。これはエラーコードです。
STATUS_INVALID_PARAMETER	無効なパラメーターが見つかりました。たとえば、I/O 操作に MDL パラメーターがない場合、IRP_MJ_READまたはIRP_MJ_WRITE I/O 操作には、IRP_MN_MDLのマイナーコードがあります。これはエラーコードです。

注釈

最適なパフォーマンスを得るためのフィルタードライバーは、絶対に必要でない限り FltLockUserBuffer を 呼び出さないでください。パフォーマンスの低下は FltLockUserBuffer 自体のためではなく、 MmGetSystemAddressForMdlSafe の後続の呼び出しによって発生するパフォーマンスの低下のためです。詳細については、後の「解説」を参照してください。

ミニフィルタードライバーは 、FltLockUserBuffer を呼び出して、次のいずれかの I/O 操作のユーザーバッファーをロックできます。

IRP_MJ_DEVICE_CONTROL
IRP_MJ_DIRECTORY_CONTROL
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_QUERY_EA
IRP_MJ_QUERY_QUOTA
IRP_MJ_QUERY_SECURITY
IRP_MJ_READ (IRP_MN_MDLを除く)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (IRP_MN_MDLを除く)

FltLockUserBuffer は、I/O 操作の種類に基づいてロックされたバッファーに適用する適切なアクセス方法 (IoReadAccess、IoWriteAccess、または IoModifyAccess) を決定します。

FltLockUserBuffer は、コールバックデータパラメーター構造体 (FLT_PARAMETERS) の MdlAddress (または OutputMdlAddress) メンバーを、ロックされたページの MDL を指すように設定します。 MDL がない場合は、 FltLockUserBuffer によって割り当てられます。 (FltMgr は、ファイルシステムが行う前に MDL を生成できないことに注意してください。そのため、 FltLockUserBuffer は IRP_MJ_READ または IRP_MN_MDL でIRP_MJ_WRITEのSTATUS_INVALID_PARAMETERを返します)。

コールバックデータパラメーター構造体にシステムバッファー (Irp-AssociatedIrp.SystemBuffer>) が含まれており、ユーザーバッファー (Irp-UserBuffer>) が含まれていない場合、FltLockUserBuffer はシステムバッファーをロックします。システムバッファーに MDL がない場合は、 FltLockUserBuffer によって割り当てられます。

コールバックデータパラメーター構造にユーザーバッファーが含まれている場合、FltLockUserBuffer はユーザーバッファーをプローブしてロックします。

呼び出し元は、任意のプロセスコンテキストで実行できます。 FltLockUserBuffer は 、適切なプロセスコンテキストでバッファーを自動的にロックします。

FltLockUserBuffer が操作前コールバックルーチン (PFLT_PRE_OPERATION_CALLBACK) から呼び出され、MDL を割り当てる場合、FltLockUserBuffer はコールバックデータ構造 (FLT_CALLBACK_DATA) にFLTFL_CALLBACK_DATA_DIRTY フラグを設定して、I/O 操作が完了したときに I/O システムが MDL を解放できるようにします。

システムページテーブルエントリ (PTEs) を節約するために、 FltLockUserBuffer はロックされたページをマップしません。 FltLockUserBuffer を呼び出した後、呼び出し元は MmGetSystemAddressForMdlSafe を呼び出し、コールバックデータパラメーター構造体の MdlAddress (または OutputMdlAddress) メンバーを Mdl パラメーターの値として渡して、このメモリを表すシステムバッファーを取得する必要があります。

コールバックデータ構造が解放されると、ロックされたバッファーは自動的にロック解除され、MDL は解放されます。呼び出し元は MDL を解放しないでください。I/O システムはこれを自動的に実行します。

FltLockUserBuffer は、高速 I/O および IRP ベースの操作に対して呼び出すことができます。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	fltkernel.h (Fltkernel.h を含む)
Library	FltMgr.lib
[DLL]	Fltmgr.sys
IRQL	<= APC_LEVEL