PFLT_NORMALIZE_NAME_COMPONENT_EX コールバック関数 (fltkernel.h)

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

フィルターマネージャーの名前キャッシュのファイル名を提供するミニフィルタードライバーは、ミニフィルタードライバーの NormalizeNameComponentExCallback コールバックルーチンとしてPFLT_NORMALIZE_NAME_COMPONENT_EX型のルーチンを登録できます。

構文

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

パラメーター

[in] Instance

このコールバックルーチンが登録されているミニフィルタードライバーインスタンスの不透明なインスタンスポインター。

[in] FileObject

名前が要求されているファイルのファイルオブジェクトへのポインター。FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME フラグが設定されている場合は、IRP_MJ_SET_INFORMATION 操作のターゲットであるファイル。詳細については、以下の Flags パラメーターを参照してください。

[in] ParentDirectory

この名前コンポーネントの親ディレクトリの名前を含むUNICODE_STRING構造体へのポインター。

[in] VolumeNameLength

ParentDirectory パラメーターが指す構造体に格納されている親ディレクトリ名の長さ (バイト単位)。

[in] Component

展開する名前コンポーネントを含むUNICODE_STRING構造体へのポインター。

[out] ExpandComponentName

名前コンポーネントの展開された (正規化された) ファイル名情報を受け取るFILE_NAMES_INFORMATION構造体へのポインター。

[in] ExpandComponentNameLength

ExpandComponentName パラメーターが指すバッファーの長さ (バイト単位)。

[in] Flags

名前正規化フラグ。 FLTFL_NORMALIZE_NAME_CASE_SENSITIVEは、正規化する名前で大文字と小文字が区別されることを指定します。 FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAMEは、 FltGetDestinationFileNameInformation ルーチン呼び出しを処理するためにコールバックルーチンが呼び出されたことを指定します。 FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME フラグが設定されている場合、 FileObject は、IRP_MJ_SET_INFORMATION操作のターゲットであるファイル/ディレクトリを表します。 FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME フラグが設定されていない場合、 FileObject は、名前が要求されているファイル/ディレクトリを表します。

[in, out] NormalizationContext

同じファイル名パス内の残りのコンポーネントを正規化するために行われる、このコールバックルーチンへの後続の呼び出しで渡されるミニフィルタードライバーによって提供されるコンテキスト情報へのポインター。

戻り値

このコールバックルーチンは、STATUS_SUCCESSまたは適切な NTSTATUS 値を返します。 Component パラメーターが指定する名前コンポーネントが ParentDirectory パラメーターが指定する親ディレクトリに存在しない場合、このコールバックルーチンはSTATUS_NO_SUCH_FILEを返す必要があります。このコールバックルーチンが親ディレクトリにIRP_MN_QUERY_DIRECTORY (FileNamesInformation) 要求を発行すると、ファイルシステムは正しい状態コードを返します。このような状況では、このコールバックは、ファイルシステムが返す状態コードを返すだけです。

注釈

NormalizeNameComponentExCallback コールバックルーチンと NormalizeNameComponentCallback コールバックルーチン (型PFLT_NORMALIZE_NAME_COMPONENT) の主な違いは、NormalizeNameComponentExCallback コールバックルーチンが追加の FileObject パラメーターをサポートしていることです。ファイルオブジェクト (FileObject) は、ミニフィルタードライバーが IoGetTransactionParameterBlock ルーチンを呼び出すことによって、ファイル/ディレクトリが参加している操作のTXN_PARAMETER_BLOCK構造体を取得するために使用できます。ミニフィルタードライバーでは、TXN_PARAMETER_BLOCK構造体を使用して、このファイルオブジェクトが参加しているトランザクションのコンテキストで独自の作成要求を発行できます。

このコールバックルーチンを登録するために、ミニフィルタードライバーは、PFLT_NORMALIZE_NAME_COMPONENT_EX型のルーチンのアドレスを、ミニフィルタードライバーが FltRegisterFilter にパラメーターとして渡すFLT_REGISTRATION構造体の NormalizeNameComponentExCallback メンバーに格納します。

フィルターマネージャーは、このコールバックルーチンを呼び出して、ミニフィルタードライバーの名前が変更されたファイル名パス内のコンポーネントの正規化された名前をミニフィルタードライバーに照会します。ファイル名パスにこのようなコンポーネントが複数含まれている場合、フィルターマネージャーは、パス内のすべてのコンポーネントを正規化するプロセスで、このコールバックルーチンを複数回呼び出すことができます。ミニフィルタードライバーは 、NormalizationContext パラメーターを使用して、このコールバックルーチンの後続の呼び出しにコンテキスト情報を渡すことができます。

ミニフィルタードライバーで NormalizationContext パラメーターを使用する場合は、正規化コンテキストクリーンアップコールバックルーチンも登録する必要があります。詳細については、 PFLT_NORMALIZE_CONTEXT_CLEANUPのリファレンスエントリを参照してください。