FltGetFileNameInformationUnsafe 関数 (fltkernel.h)

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

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

構文

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

パラメーター

[in] FileObject

ファイルまたはディレクトリのファイルオブジェクトへのポインター。ファイルオブジェクトは現在開いている必要があります。このパラメーターは必須であり、 NULL に設定することはできません。

[in, optional] Instance

呼び出し元のインスタンスポインター。このパラメーターは NULL に設定できます。

[in] NameOptions

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

次の表では、名前書式フラグの値について説明します。指定できるフラグは 1 つだけです。これらの形式の詳細については、「 FLT_FILE_NAME_INFORMATION」を参照してください。

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

次の表では、クエリメソッドのフラグ値について説明します。指定できるフラグは 1 つだけです。

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

[out] FileNameInformation

システム割り当てFLT_FILE_NAME_INFORMATION構造体のアドレスを受け取る呼び出し元割り当て変数へのポインター。 FltGetFileNameInformationUnsafe は、ページプールからこの構造体を割り当てます。この情報が不要になった場合、呼び出し元は FltReleaseFileNameInformation を呼び出して構造体を解放する必要があります。このパラメーターは必須であり、 NULL に設定することはできません。

戻り値

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

リターンコード	説明
STATUS_FLT_INVALID_NAME_REQUEST	FileObject パラメーターが指すファイルオブジェクトは、現在開いていません。これはエラーコードです。
STATUS_INVALID_PARAMETER	FileNameInformation パラメーターに無効な値が渡されました。これはエラーコードです。

注釈

FltGetFileNameInformationUnsafe ルーチンが用意されているため、そのファイルオブジェクトに対する I/O 操作のコンテキストの外部でファイルオブジェクトの名前を照会できます。それ以外の場合は、FltGetFileNameInformation を呼び出す必要があります。

FltGetFileNameInformation ルーチンとは異なり、FltGetFileNameInformationUnsafe は、ファイルシステムに名前情報を照会すると、FLT_FILE_NAME_QUERY_CACHE_ONLY以外のクエリメソッドのデッドロックが発生する可能性がある、次の種類の状況から呼び出し元を保護しません。

ページング I/O パス。
現在のスレッドの TopLevelIrp フィールドが NULL でない場合。詳細については、「 IoGetTopLevelIrp」を参照してください。
IRP_MJ_CLEANUP操作が完了した後。つまり、ポストクリーンアップ、プリクローズ、またはポストクローズパス (ターゲットファイルオブジェクトには FO_CLEANUP_COMPLETE フラグが設定されています)。
次のいずれかの操作の事前操作 (PFLT_PRE_OPERATION_CALLBACK) または事後操作 (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 を返す場合です。

Windows Vista/Server 2008 以降の場合、ミニフィルターに DriverEntry ルーチンなどのフィルターインスタンスがまだない場合は、Instance パラメーターにを使用NULLできます。これにより、 DriverEntry ルーチンはファイル名情報にアクセスできます。この場合を除き、 NULL インスタンスパラメーターの値はシステムで使用するために予約されています。

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

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

要件

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