FltGetFileNameInformation 関数 (fltkernel.h)

  • [アーティクル]

FltGetFileNameInformation ルーチンは、ファイルまたはディレクトリの名前情報を返します。

構文

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

パラメーター

[in] CallbackData

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

[in] NameOptions

返 される 名前情報の形式とフィルター マネージャーで使用するクエリ メソッドを指定するフラグを含むFLT_FILE_NAME_OPTIONS値。 呼び出し元には、名前形式フラグとクエリ メソッド フラグを含める必要があります。 名前プロバイダーのミニフィルター ドライバーで追加のフラグを使用して、名前クエリ オプションを指定できます。 このパラメーターは必須であり、 NULL にすることはできません。

ファイル名形式のフラグ値を次に示します。 次のいずれかのフラグのみを指定できます。 これらの形式の詳細については、「 FLT_FILE_NAME_INFORMATION」を参照してください。

Name Format Flag Value 意味
FLT_FILE_NAME_NORMALIZED FileNameInformation パラメーターは、ファイルの正規化された名前を含む構造体のアドレスを受け取ります。
FLT_FILE_NAME_OPENED FileNameInformation パラメーターは、ファイルを開いたときに使用された名前を含む構造体のアドレスを受け取ります。
FLT_FILE_NAME_SHORT FileNameInformation パラメーターは、ファイルの短い (8.3) 名を含む構造体のアドレスを受け取ります。 短い名前は、最大 8 文字で構成され、その直後にピリオドが続き、さらに 3 文字まで続きます。 ファイルの短い名前には、ボリューム名、ディレクトリ パス、またはストリーム名は含まれません。 事前作成パスでは無効です。

ファイル名のクエリ メソッド フラグ値を次に示します。 次のいずれかのフラグのみを指定できます。

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

名前プロバイダーのミニフィルターでは、次のフラグを使用して、ファイル名操作のプロパティを指定します。

Name Provider Flag Value 意味
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER 名前プロバイダーミニフィルターは、このフラグを使用して、名前クエリ要求を、スタック内の下位の名前プロバイダーによって満たされるのではなく、それ自体 (名前プロバイダー ミニフィルター) にリダイレクトするように指定できます。
FLT_FILE_NAME_DO_NOT_CACHE このフラグは、このクエリから取得した名前をキャッシュしないことを示します。 名前プロバイダーのミニフィルターは、中間クエリを実行して名前を生成する際に、このフラグを使用します。
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE 名前プロバイダーのミニフィルターでは、このフラグを使用して、STATUS_REPARSEが返された場合でも、作成後のパスの名前に対してクエリを実行しても安全であることを指定できます。 FileObject-FileName> フィールドが変更されていないことを確認するのは呼び出し元の責任です。 マウント ポイントまたはシンボリック リンクの再解析ポイントでは、このフラグを使用しないでください。

[out] FileNameInformation

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

戻り値

名前情報が正常に返された場合、 FltGetFileNameInformation はSTATUS_SUCCESSを返します。 それ以外の場合は、次のいずれかの適切な NTSTATUS 値を返します。

リターン コード 説明
STATUS_FLT_INVALID_NAME_REQUEST

FltGetFileNameInformation は、フィルター マネージャーの名前キャッシュからクエリを満たすことができない場合、次の状況ではファイル名情報を取得できません。

  • ページング I/O パス。
  • 現在のスレッドの TopLevelIrp フィールドが NULL でない場合は、結果として生成されるファイル システムの再帰によってデッドロックまたはスタック オーバーフローが発生する可能性があるためです。 (この問題の詳細については、「 IoGetTopLevelIrp」を参照してください)。
  • IRP_MJ_CLEANUP操作が完了した後。つまり、ポスト クリーンアップ、プリクローズ、またはポストクローズ パス (ターゲット ファイル オブジェクトには FO_CLEANUP_COMPLETE フラグが設定されています)。
  • 次のいずれかの操作の事前操作 (PFLT_PRE_OPERATION_CALLBACK) または postoperation (PFLT_POST_OPERATION_CALLBACK) コールバック ルーチン。
    • IRP_MJ_ACQUIRE_FOR_CC_FLUSH
    • IRP_MJ_ACQUIRE_FOR_MOD_WRITE
    • IRP_MJ_RELEASE_FOR_CC_FLUSH
    • IRP_MJ_RELEASE_FOR_MOD_WRITE
    • IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION
  • IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATIONの事後操作コールバック ルーチン。
  • すべての APC が無効になっている場合。つまり、 KeAreAllApcsDisabled が TRUE を返す場合です。

FltGetFileNameInformation は、事前作成パス内のファイルの短い名前を取得できません。

STATUS_FLT_INVALID_NAME_REQUESTはエラー コードです。
STATUS_INSUFFICIENT_RESOURCES
 FltGetFileNameInformation で プール割り当てエラーが発生しました。 これはエラー コードです。
STATUS_INVALID_PARAMETER
 次のいずれかの無効なパラメーターが渡されたときに返されます。
  • FileNameInformation パラメーターを NULL にすることはできません。
  • CallbackData パラメーターを NULL にすることはできません。
STATUS_INVALID_PARAMETERはエラー コードです。
STATUS_FLT_NAME_CACHE_MISS
 ファイル名の情報が名前キャッシュに見つからず、 NameOptions にFLT_FILE_NAME_QUERY_CACHE_ONLYが含まれています。

または

NameOptions にFLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUPが含まれており、ファイル システムからファイル名情報を照会できない場合、ファイル名情報は名前キャッシュに見つかりません。

NameOptions に FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY設定された FltGetFileNameInformation を追加で呼び出すと、ファイル名情報が返される場合があります。
STATUS_NOT_SAME_DEVICE
 事前作成中に照会されるファイルは、親ディレクトリとは異なるボリューム上にあります。 このエラーは、正規化された名前クエリに対して返されます。ファイルは、別のボリュームに解決されたジャンクションまたはシンボリック リンクでした。
STATUS_ACCESS_DENIED
 ユーザーがファイル ID でファイルを開いたが、パス全体に対する走査特権がない場合、 FltGetFileNameInformation はこの戻り値で失敗します。

STATUS_ACCESS_DENIEDはエラー コードです。

または

ファイルは、すべてのアクセスが拒否されたシステム ファイルです。

注釈

FltGetFileNameInformation は、 CallbackData によって記述された操作のターゲットであるファイルまたはディレクトリの要求された名前情報を、指定された形式で返します。 ファイルまたはディレクトリをファイル システムでまだ開く必要はありません。

事前作成操作の場合、CallbackData-Iopb-OperationFlags>> メンバーにSL_OPEN_TARGET_DIRECTORYビットごとのフラグが含まれている場合、FltGetFileNameInformation は、指定されたファイルの格納 (親) ディレクトリの名前を返します。 この名前は、作成操作が開く実際のパスです。

FltGetFileNameInformation によって返されるFLT_FILE_NAME_INFORMATION構造体の内容を解析するには、FltParseFileNameInformation を呼び出します。 (ファイル名の形式の詳細については、「 FLT_FILE_NAME_INFORMATION」を参照してください。

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

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

開いている名前を取得する作成操作の事前操作コールバック ルーチンで FltGetFileNameInformation が呼び出された場合、開いているファイルへのパスがボリューム上に存在しない場合でも、 FltGetFileNameInformation は成功します。

正規化された名前を取得する作成操作の事前操作コールバック ルーチンで FltGetFileNameInformation が呼び出された場合、開いているファイルへのパスの最終的なコンポーネントがボリューム上に存在しない場合でも、 FltGetFileNameInformation は成功します。

注意

リモート ボリュームで正規化されたファイル名のクエリを実行するためのサーバー メッセージ ブロック (SMB) のサポートは、Windows 10バージョンによって異なります。 詳細については、 MS-SMB2 プロトコル に関するページを参照してください。

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

Windows 8.1以前の場合、FltGetFileNameInformation には、フィルターの事前作成コールバックから呼び出された場合にのみストリームの種類を含めることができます。 ファイルの既定のストリームストリームとメタデータ ストリームを区別するには、事前作成操作でこの呼び出しを行う必要があります。 結果のストリームの種類は、ファイルの有効期間中も有効なままです。

Windows 8する前に、Filter Manager は、ファイル パスの各コンポーネントの名前情報を収集することで、ファイルまたはディレクトリの正規化された名前を取得しました。 これには、完全なパスをコンパイルするために、ファイル システムに対する複数のクエリが必要でした。 Windows 8以降、ローカル ファイル システムでは FileNormalizedNameInformation ファイル情報クラスがサポートされており、正規化された名前を取得するために必要なクエリは 1 つだけです。 リモート ファイル システムでは、 FileNormalizedNameInformation ファイル情報クラスがサポートされていない場合があります。 この場合、正規化された名前をアセンブルするには、ファイル パスの各コンポーネントに対するクエリが必要です。 特定のネットワーク条件下では、フル ネーム クエリの完了にかなりの時間が必要になる場合があります。

正規化されたファイル名の情報の詳細については、「 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 (戻り値を参照)

こちらもご覧ください

FLT_CALLBACK_DATA

FLT_FILE_NAME_INFORMATION

FLT_FILE_NAME_OPTIONS

FltGetDestinationFileNameInformation

FltGetFileNameInformationUnsafe

FltGetTunneledName

FltParseFileNameInformation

FltReferenceFileNameInformation

FltReleaseFileNameInformation

IoGetTopLevelIrp

PFLT_POST_OPERATION_CALLBACK

PFLT_PRE_OPERATION_CALLBACK