FltGetDestinationFileNameInformation 関数 (fltkernel.h)
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) fltGetDestinationFileNameInformation 現在のスレッドの TopLevelIrp フィールドが NULL でない場合、ファイル名情報を取得できません。これは、結果として 結果のファイル システムの再帰によってデッドロックまたはスタック オーバーフローがされる可能性があるためです。 (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という名前の既存のファイルに、name2 のハード リンクを追加する場合、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)
必要条件
要件 | 価値 |
---|---|
ターゲット プラットフォーム の | 万国 |
ヘッダー | fltkernel.h (Fltkernel.h を含む) |
ライブラリ | FltMgr.lib |
DLL | Fltmgr.sys |
IRQL | <= APC_LEVEL |
関連項目
FltGetFileNameInformation の
FltGetFileNameInformationUnsafe の
FltGetTunneledName を する
FltParseFileNameInformation の
FltReferenceFileNameInformation の
FltReleaseFileNameInformation の
IoGetTopLevelIrp の