FltGetTunneledName 関数 (fltkernel.h)

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

FltGetTunneledName ルーチンは、FltGetFileNameInformation、FltGetFileNameInformationUnsafe、または FltGetDestinationFileNameInformation への以前の呼び出しによってファイルに対して返される正規化された名前を指定して、ファイルのトンネル名を取得します。

構文

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

パラメーター

[in] CallbackData

I/O 操作のコールバックデータ構造へのポインター (FLT_CALLBACK_DATA)。このパラメーターは必須であり、 NULL にすることはできません。

[in] FileNameInformation

ファイルの FltGetFileNameInformation、FltGetFileNameInformationUnsafe、または FltGetDestinationFileNameInformation の以前の呼び出しによって返された正規化された名前情報を含むFLT_FILE_NAME_INFORMATION構造体へのポインター。

[out] RetTunneledFileNameInformation

トンネリングされたファイル名を含む新しく割り当てられた構造体のアドレスを受け取る呼び出し元によって割り当てられた変数へのポインター。トンネル名が見つからない場合、この変数は NULL を受け取ります。このパラメーターは必須であり、入力時に NULL にすることはできません。

戻り値

FltGetTunneledName は、トンネル名が見つかった場合、またはファイルのトンネル名がない場合にSTATUS_SUCCESSを返します。それ以外の場合は、次のような NTSTATUS 値を返します。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName でプール割り当てエラーが発生しました。これはエラーコードです。

注釈

NTFS や FAT などのファイルシステムでは、ボリュームごとのトンネルキャッシュを使用して、名前変更、リンク、または削除されるファイルのファイル名やその他のメタデータを簡単に保持します。ファイル名トンネリングにより、FltGetFileNameInformation、FltGetFileNameInformationUnsafe、または FltGetDestinationFileNameInformation への事前操作呼び出しによって返される正規化されたファイル名情報の最終的なコンポーネントが無効になる可能性があります。

ミニフィルタードライバーが、作成 (IRP_MJ_CREATE)、ハードリンク (FILE_INFORMATION_CLASSが FileRenameInformation に設定されたIRP_MJ_SET_INFORMATION)、または名前変更操作 (FILE_INFORMATION_CLASSが FileLinkInformation に設定されている IRP_MJ_SET_INFORMATION場合) に対して、事前操作コールバックルーチン (PFLT_PRE_OPERATION_CALLBACK) で正規化されたファイル名情報を取得する場合は、その事後操作コールバックルーチン ( から FltGetTunneledName を呼び出す必要があります)PFLT_POST_OPERATION_CALLBACK) を使用して、ファイルの正しいファイル名情報を取得します。

正規化されたファイル名情報のみがトンネリングの影響を受けます。フィルターマネージャーは、作成、ハードリンク、または名前変更の操作が実際に行われるまで、最終的なコンポーネントが正規化されていることを確認できません。これは、トンネリングによって短い名前が長い名前に変更される可能性があるためです。したがって、ミニフィルタードライバーは、事前操作コールバックルーチンで取得された正規化されたファイル名情報が有効かどうかを判断するために、その操作後コールバックルーチンから FltGetTunneledName を呼び出す必要があります。

正規化されたファイル名の情報の詳細については、「 FLT_FILE_NAME_INFORMATION」を参照してください。

短いファイル名または開いているファイル名の情報のみを取得するミニフィルタードライバーは 、FltGetTunneledName を呼び出さないでください。

Preoperation コールバックルーチンで FltGetFileNameInformation、 FltGetFileNameInformationUnsafe、または FltGetDestinationFileNameInformation を呼び出した後、ミニフィルタードライバーは、返された FileNameInformation ポインターを事前操作コールバックルーチンの CompletionContext 構造体に格納して、事後処理コールバックが FileNameInformation パラメーターでこのポインターを FltGetTunneledName に渡すことができるようにする必要があります。

注意

ファイル名トンネリングは、この方法で作成、ハードリンク、名前変更の操作にのみ影響します。読み取りと書き込みなど、他の I/O 操作には影響しません。

次のペアの操作により、ファイル名がトンネリングされる可能性があります。

delete(name)/create(name)
delete(name)/rename(source, name)
rename(name, newname)/create(name)
rename(name, newname)/rename(source, name)

ファイルのトンネル名が見つからない場合、 RetTunneledFileNameInformation パラメーターは NULL を受け取ります。

FltGetTunneledName を正常に呼び出した後、呼び出し元は FltReleaseFileNameInformation を呼び出して不要になった RetTunneledFileNameInformation ポインターと FileNameInformation ポインターを解放する必要があります。

FltGetTunneledName は、ミニフィルタードライバーのIRP_MJ_CREATEまたはIRP_MJ_SET_INFORMATIONのポスト操作コールバックルーチンからのみ呼び出す必要があります。他の種類の I/O 操作に対して、運用後コールバックルーチンから FltGetTunneledName を呼び出すか、事前操作コールバックルーチンから呼び出すことはプログラミングエラーです。

呼び出し元は、 RetTunneledFileNameInformation パラメーターで返される構造体の内容を変更しないでください。これは、この構造体はフィルターマネージャーによってキャッシュされ、すべてのミニフィルタードライバーで使用できるためです。

ファイルトンネリングを使用すると、ファイルシステムに依存するプログラムと互換性があり、ファイルメタ情報を短時間保持できます。たとえば、安全な保存プロセスの場合などです。トンネリングでは、ファイルの長い名前と短い名前 (8.3) の間の関連付けが保持されます。ファイル名がディレクトリから削除されると (名前の変更または削除)、短い名前と長い名前のペアと作成時間がトンネルキャッシュに保存され、削除された名前でキーが設定されます。名前をディレクトリに追加 (名前の変更または作成) すると、キャッシュが検索され、復元する情報があるかどうかを判断します。キャッシュは、ディレクトリのインスタンスごとに有効です。ディレクトリが削除されると、そのキャッシュが削除されます。

要件

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