FltAllocateCallbackData 関数 (fltkernel.h)

[アーティクル]
08/07/2023

FltAllocateCallbackData は、ミニフィルタードライバーが I/O 要求を開始するために使用できるコールバックデータ構造を割り当てます。

構文

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

パラメーター

[in] Instance

I/O 操作を開始しているミニフィルタードライバーインスタンスの不透明なインスタンスポインター。このパラメーターは必須であり、 NULL にすることはできません。

[in, optional] FileObject

I/O 操作で使用されるファイルオブジェクトポインター。このパラメーターは省略可能であり、 NULL にすることができます。

[out] RetNewCallbackData

新しく割り当てられたコールバックデータ (FLT_CALLBACK_DATA) 構造体のアドレスを受け取る呼び出し元割り当て変数へのポインター。

戻り値

FltAllocateCallbackData は、次のようなSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData で、コールバックデータ構造を割り当てようとしたときにプール割り当てエラーが発生しました。これはエラーコードです。

注釈

ミニフィルタードライバーは 、FltAllocateCallbackData を呼び出して、ミニフィルタードライバーによって開始される I/O 操作のコールバックデータ (FLT_CALLBACK_DATA) 構造を割り当てることができます。

メモFltAllocateCallbackData ルーチンは、後続の I/O 要求で必要になる可能性のあるすべてのメモリを割り当てるわけではありません。 FltPerformSynchronousIo や FltPerformAsynchronousIo などの I/O 要求で何らかの構造体に追加のメモリが必要な場合、要求でメモリ割り当てが発生する可能性があります。 FltAllocateCallbackDataEx ルーチンを使用すると、I/O 要求で使用される追加の構造体のメモリを事前に割り当てることで、この潜在的な問題を回避できます。 RetNewCallbackData 構造体または追加の必須構造体のいずれかにメモリ割り当ての問題がある場合は、コールバックデータ割り当ての時点で処理できます。

コールバックデータ構造は、非ページプールから割り当てられます。

FltAllocateCallbackData によって返されるコールバックデータ構造体のパラメーターを初期化した後、呼び出し元は構造体を FltPerformSynchronousIo または FltPerformAsynchronousIo に渡すことによって I/O 操作を開始します。これらのルーチンは、開始インスタンスの下にアタッチされているミニフィルタードライバーインスタンス ( Instance パラメーターで 指定) とファイルシステムにのみ I/O 操作を送信します。指定したインスタンスの上に接続されているミニフィルタードライバーは、I/O 操作を受け取りません。

ミニフィルタードライバーは、IRP ベースの I/O 操作のみを開始できます。高速 I/O またはファイルシステムフィルター (FSFilter) コールバック操作を開始できません。

ミニフィルタードライバーでは、次のようなルーチンを使用できない I/O 操作にのみ、 FltAllocateCallbackData、 FltPerformAsynchronousIo、および FltPerformSynchronousIo を使用する必要があります。

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

FltAllocateCallbackData によって割り当てられたコールバックデータ構造が不要になった場合、呼び出し元は FltFreeCallbackData を呼び出して解放する必要があります。