FltGetFileNameInformationUnsafe 函式 (fltkernel.h)

發行項
02/26/2024

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。

下表描述名稱格式旗標值。只能指定其中一個旗標。如需這些格式的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION。

值	意義
FLT_FILE_NAME_NORMALIZED	FileNameInformation 參數會接收包含檔案正規化名稱的結構位址。
FLT_FILE_NAME_OPENED	FileNameInformation 參數會接收結構位址，其中包含開啟檔案時所使用的名稱。
FLT_FILE_NAME_SHORT	FileNameInformation 參數會接收結構位址，其中包含檔案的簡短 (8.3) 名稱。簡短名稱包含最多8個字元，後面緊接著句號，最多3個字元。檔案的簡短名稱不包含磁碟區名稱、目錄路徑或數據流名稱。

下表描述查詢方法旗標值。只能指定其中一個旗標。

值	意義
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 值，例如下列其中一項：

傳回碼	Description
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 例程中，它可以用於 NULLInstance 參數。這可讓 DriverEntry 例程存取檔名資訊。在此案例中， NULL 實例參數的值會保留供系統使用。

在建立、硬式連結和重新命名作業中，檔名通道可能會使小型篩選驅動程式在預先操作回呼例程中擷取的標準化檔名資訊中，使最終元件失效。如果迷你篩選驅動程式藉由呼叫 FltGetFileNameInformationUnsafe 之類的例程，在預先操作回呼 (PFLT_PRE_OPERATION_CALLBACK) 例程中擷取正規化的檔名資訊，則必須從其後置回呼呼叫 FltGetTunneledName (PFLT_POST_OPERATION_CALLBACK) 例程，以擷取檔案的正確檔名資訊。

如需標準化檔名資訊的詳細資訊，請參閱 FLT_FILE_NAME_INFORMATION。