FltRetrieveFileInfoOnCreateCompletionEx 関数 (fltkernel.h)

[アーティクル]
05/23/2024

FltRetrieveFileInfoOnCreateCompletionEx は、ファイルの作成時に指定されたファイル情報を照会します。

構文

NTSTATUS FLTAPI FltRetrieveFileInfoOnCreateCompletionEx(
  [in]  PFLT_FILTER        Filter,
  [in]  PFLT_CALLBACK_DATA Data,
  [in]  ULONG              InfoClass,
  [out] PULONG             RetInfoSize,
  [out] PVOID              *RetInfoBuffer
);

パラメーター

[in] Filter

ミニフィルタードライバーを一意に識別する不透明なフィルターポインター。 FltRegisterFilter によって返され、ミニフィルタードライバーが読み込まれる限り、一定のままになります。

[in] Data

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

[in] InfoClass

返すファイル情報の種類を示すフラグ。フラグは結合できないことに注意してください。値は、次のいずれかです。

フラグ	説明
QoCFileStatInformation (0x00000001)	ファイルシステムは、 QUERY_ON_CREATE_FILE_STAT_INFORMATION 構造体内のファイル統計情報を返します。
QoCFileLxInformation (0x00000002)	ファイルシステムは、 QUERY_ON_CREATE_FILE_LX_INFORMATION 構造内の拡張 Linux に似た情報を返します。
QoCFileEaInformation (0x00000004)	ファイルシステムは、 QUERY_ON_CREATE_EA_INFORMATION 構造の拡張属性 (EA) を返します。
QoCFileUsnInformation (0x00000008)	ファイルシステムは、 QUERY_ON_CREATE_USN_INFORMATION 構造体で USN 情報を返します。
QoCFileSecurityInformation (0x00000010)	ファイルシステムは、 QUERY_ON_CREATE_SECURITY_INFORMATION 構造のファイルセキュリティ情報を返します。

[out] RetInfoSize

RetInfoBuffer が指すバッファーのサイズをバイト単位で受け取る ULONG へのポインター。

[out] RetInfoBuffer

要求された InfoClass 構造体へのポインターを受け取ります。ファイルシステムが要求を処理できても、要求されたファイル情報が見つからない場合、このパラメーターは NULL に設定されます。

戻り値

リターンコード	説明
STATUS_SUCCESS	ファイルシステムは、要求されたファイル情報を正常に返しました。
STATUS_NOT_FOUND	ファイルシステムは要求を処理しましたが、要求された情報がファイルに存在しないか、ファイルシステムが InfoClass の情報要求を認識しません。呼び出し元は、従来のファイルシステム API を使用して情報を要求しないでください。
STATUS_NOT_SUPPORTED	ファイルシステムは、要求された情報を取得できませんでした。このエラーは、ファイルシステムが情報要求または関連付けられた ECP をサポートしていない場合、またはファイルの事前作成時に FltRequestFileInfoOnCreateCompletion が呼び出されなかった場合に発生します。呼び出し元は、代わりに従来のファイルシステム API を使用して、情報の要求を再試行する必要があります。
STATUS_UNSUCCESSFUL	要求された情報を取得しようとしたときに、ファイルシステムにエラーが発生しました。呼び出し元は、通常のファイルシステム API を使用して情報の要求を試みることができますが、失敗する可能性があります。

注釈

FltRequestFileInfoOnCreateCompletion と FltRetrieveFileInfoOnCreateCompletionEx を使用すると、ファイルの作成時にミニフィルターでファイルに関する情報を取得できるため、スタックトラバーサルを必要とする後のクエリのパフォーマンスコストを回避できます。

事前作成では、ミニフィルターは FltRequestFileInfoOnCreateCompletion を 1 回呼び出し、入力 InfoClassFlags を組み合わせて要求された情報を識別します。
ファイルシステムは適切な構造体を割り当て、サポートされている場合は、作成の処理中に要求された情報を入力します。
作成後、ミニフィルターは FltRetrieveFileInfoOnCreateCompletionEx を呼び出して、事前作成呼び出しで要求した情報を取得します。ミニフィルターが複数の情報の種類を要求した場合は、情報の種類ごとに FltRetrieveFileInfoOnCreateCompletionEx を 1 回呼び出す必要があります。例:


// Pre-create:
NTSTATUS status;
status = FltRequestFileInfoOnCreateCompletion( Filter,
                                               CallbackData,
                                               QoCFileStatInformation
                                                | QoCFileLxInformation
                                                | QoCFileEaInformation 
                                                | QoCFileUsnInformation );

// Post-create:
NTSTATUS status;
ULONG fileStatSize, fileLxSize, fileEaSize;
QUERY_ON_CREATE_FILE_STAT_INFORMATION* fileStatInfo;
QUERY_ON_CREATE_FILE_LX_INFORMATION* fileLxInfo;
QUERY_ON_CREATE_EA_INFORMATION* fileEaInfo;
QUERY_ON_CREATE_USN_INFORMATION* fileUsnInfo;
QUERY_ON_CREATE_SECURITY_INFORMATION* fileSecurityInfo;

status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileStatInformation,
                                                  &fileStatSize,
                                                  &fileStatInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileLxInformation,
                                                  &fileLxSize,
                                                  &fileLxInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileEaInformation, 
                                                  &fileEaSize, 
                                                  &fileEaInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileUsnInformation, 
                                                  &fileUsnInfo, 
                                                  &fileUsnInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileSecurityInformation,
                                                  &fileSecurityInfo,
                                                  &fileSecurityInfo);

FltRetrieveFileInfoOnCreateCompletionEx が返されると、ミニフィルターは RetInfoBuffer が指すバッファーに書き込むことができます。そのミニフィルターの上にあるフィルターは、変更された情報の種類で FltRetrieveFileInfoOnCreateCompletionEx を呼び出すと変更が表示されます。