FltGetDestinationFileNameInformation 関数 (fltkernel.h)

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

FltGetDestinationFileNameInformation ルーチンは、変換先の親ディレクトリのファイル名に対してクエリを実行し、名前が変更されているファイルまたはディレクトリ、または NTFS ハードリンクが作成されているファイルまたはディレクトリの完全な宛先パス名を作成します。

構文

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

パラメーター

[in] Instance

ファイルが存在するボリュームにアタッチされているミニフィルタードライバーインスタンスの不透明なインスタンスポインター。

[in] FileObject

ファイルのファイルオブジェクトへのポインター。このパラメーターは必須であり、NULL にすることはできません。

[in, optional] RootDirectory

リンク操作の場合: リンク先のファイルと同じディレクトリにリンクを作成する場合、または FileName に作成するリンクの完全なパス名が含まれている場合、このパラメーターは NULL です。それ以外の場合は、リンクを作成するディレクトリのハンドルです。

名前変更操作の場合: ファイルが別のディレクトリに移動されていない場合、または FileName に完全なパス名が含まれている場合、このパラメーターは NULL です。それ以外の場合は、ファイルの名前が変更された後に存在するディレクトリのハンドルです。

[in] FileName

リンク操作の場合: 新しく作成されたリンクに割り当てる名前を含むワイド文字列へのポインター。

名前変更操作の場合: ファイルの新しい名前を含むワイド文字列へのポインター。

[in] FileNameLength

FileName が指すワイド文字列の長さ (バイト単位)。

[in] NameOptions

返される名前情報の形式、フィルターマネージャーで使用するクエリメソッド、および追加のファイル名フラグを指定するフラグを含むFLT_FILE_NAME_OPTIONS値。 このパラメーターは必須であり、NULL にすることはできません。

名前書式フラグの値を次に示します。名前書式フラグを 1 つだけ指定できます。 (FLT_FILE_NAME_SHORTはこのパラメーターの有効なフラグ値ではないことに注意してください)。

名前書式フラグ値	意味
FLT_FILE_NAME_NORMALIZED	FileName パラメーターは、ファイルの正規化された宛先名を受け取ります。
FLT_FILE_NAME_OPENED	FileName パラメーターは、ファイルを開いたときに使用された名前に基づいて、ファイルの宛先名を受け取ります。このファイル名は正規化されません。

クエリメソッドのフラグ値を次に示します。指定できるクエリメソッドフラグは 1 つだけです。

Query メソッドフラグ値	意味
FLT_FILE_NAME_QUERY_DEFAULT	現在、ファイルシステムに対して宛先ファイル名のクエリを実行しても安全でない場合、 FltGetDestinationFileNameInformation では何も実行されません。それ以外の場合、 FltGetDestinationFileNameInformation は、フィルターマネージャーの名前キャッシュに対して、宛先の親ディレクトリのファイル名情報を照会し、宛先名を追加します。結果の名前がキャッシュに見つからない場合、 FltGetDestinationFileNameInformation はファイルシステムに対してクエリを実行し、結果をキャッシュします。
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation は、フィルターマネージャーの名前キャッシュに対して、宛先の親ディレクトリのファイル名情報を照会し、宛先名を追加します。ファイルシステムに対するクエリは実行されません。
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation は、ファイルシステムに対して、変換先の親ディレクトリのファイル名情報を照会し、宛先名を追加します。フィルターマネージャーの名前キャッシュに対してクエリを実行せず、ファイルシステムクエリの結果をキャッシュしません。
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation は、フィルターマネージャーの名前キャッシュに対して、宛先の親ディレクトリのファイル名情報を照会し、宛先名を追加します。キャッシュに名前が見つかっていなくても、現在安全に実行できる場合、 FltGetDestinationFileNameInformation はファイルシステムに対してファイル名情報を照会し、結果をキャッシュします。

ファイル名フラグの値を次に示します。これらのフラグの任意の組み合わせを指定できます。 ( fltGetDestinationFileNameInformation は作成後のコールバックでは使用されないため、FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSEはこのパラメーターに関連するフラグではないことに注意してください)。

ファイル名フラグ値	意味
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation は、名前要求を呼び出し元のフィルターインスタンスに送信して完了します。
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation は、取得したファイル名をキャッシュしません。名前プロバイダーのミニフィルターは、中間クエリを実行して名前を生成する際に、このフラグを使用します。

[out] RetFileNameInformation

ファイル名情報を含むシステム割り当て FLT_FILE_NAME_INFORMATION 構造体のアドレスを受け取る呼び出し元によって割り当てられた変数へのポインター。 FltGetDestinationFileNameInformation は、この構造体をページプールから割り当てます。このパラメーターは必須であり、NULL にすることはできません。

戻り値

FltGetDestinationFileNameInformation は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

リターンコード	説明
STATUS_FLT_INVALID_NAME_REQUEST	この値は、次のいずれかの理由で返されます。(1) 現在のスレッドの TopLevelIrp フィールドが NULL でない場合、FltGetDestinationFileNameInformation はファイル名情報を取得できません。結果としてファイルシステムの再帰によってデッドロックやスタックオーバーフローが発生する可能性があるためです。 (2) NameOptions パラメーターの名前書式フラグにFLT_FILE_NAME_SHORTが指定されました。
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation でプール割り当てエラーが発生しました。これはエラーコードです。
STATUS_INVALID_PARAMETER	NameOptions パラメーターに無効な値が指定されました。これはエラーコードです。
STATUS_MOUNT_POINT_NOT_RESOLVED	宛先パス名には、ファイルが存在するボリューム以外のボリュームに解決されるマウントポイントが含まれています。 (名前変更操作またはハードリンク作成操作はボリューム内でのみ実行でき、ボリューム間では実行できないため、操作は失敗します)。これはエラーコードです。

注釈

ミニフィルターは通常、名前変更またはハードリンク作成操作の事前操作コールバックルーチンで FltGetDestinationFileNameInformation を呼び出します。これは、宛先ファイル名が存在しない可能性が最も高いことを意味します。 "destination" 名は次のとおりです。

ファイルの名前変更の場合、名前の変更が成功した場合にファイルに付ける名前。たとえば、 name1 の 名前を name2 に変更する場合、 name2 は宛先名になります。
ハードリンク作成操作の場合、ファイルシステムに追加される名前。たとえば、name1 という名前の既存のファイルにハードリンク名 2 を追加する場合、name2 は宛先名です。

FltGetDestinationFileNameInformation は、正規化されたファイルまたは "開かれたファイル" 形式の宛先ファイル名情報を返します。これらの形式の詳細については、 FLT_FILE_NAME_INFORMATION 構造に関するページを参照してください。

FileObject パラメーターに渡されるファイルオブジェクトポインターは、操作のFLT_RELATED_OBJECTS構造体の FileObject メンバーか、操作の Data-Iopb-TargetFileObject>> ポインターである必要があります。ここで、Data は操作のコールバックデータ構造 (FLT_CALLBACK_DATA)。このフィールドはファイルシステム間で一様に使用されないため、ファイルオブジェクトポインターを Data-Iopb-Parameters.SetFileInformation.FileObject>> メンバーにすることはできません。

ユーザーがファイル ID を使用してファイルを開いたが、パス全体に対する走査特権がない場合、 FltGetDestinationFileNameInformation は、ユーザーが特権を持つパスの一部のみを返します。

名前変更操作またはハードリンク作成操作は、ボリューム内でのみ実行でき、ボリューム間では実行できません。そのため、宛先パス名に、ファイルが存在するボリューム以外のボリュームに解決されるマウントポイントが含まれている場合、このような操作は失敗します。名前変更操作の詳細については、 FILE_RENAME_INFORMATION 構造体に関するページを参照してください。ハードリンク作成操作の詳細については、 FILE_LINK_INFORMATION 構造体に関するページを参照してください。

FltGetDestinationFileNameInformation の呼び出しが正常に行われると、呼び出し元は FltReleaseFileNameInformation を呼び出して不要になったときに、RetFileNameInformation パラメーターで返されるポインターを解放する必要があります。

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

作成、ハードリンク、および名前変更の操作では、ファイル名トンネリングによって、ミニフィルタードライバーが事前操作コールバックルーチンで取得する正規化されたファイル名情報の最終的なコンポーネントが無効になる可能性があります。ミニフィルタードライバーは、FltGetDestinationFileNameInformation などのルーチンを呼び出すことによって、事前操作コールバック (PFLT_PRE_OPERATION_CALLBACK) ルーチンで正規化されたファイル名情報を取得する場合は、その後操作コールバックルーチンから FltGetTunneledName を呼び出して、ファイルの正しいファイル名情報を取得する必要があります。

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

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

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

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

要件

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