Funzione FltGetFileNameInformationUnsafe (fltkernel.h)

Articolo
08/07/2023

La routine FltGetFileNameInformationUnsafe restituisce informazioni sul nome per un file o una directory aperta.

Sintassi

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

Parametri

[in] FileObject

Puntatore a un oggetto file per il file o la directory. L'oggetto file deve essere attualmente aperto. Questo parametro è obbligatorio e non può essere impostato su NULL.

[in, optional] Instance

Puntatore di istanza per il chiamante. Questo parametro può essere impostato su NULL.

[in] NameOptions

Valore FLT_FILE_NAME_OPTIONS contenente flag che specificano il formato delle informazioni sul nome da restituire, nonché il metodo di query da utilizzare da Gestione filtri. Questo parametro è obbligatorio e non può essere impostato su NULL.

Nella tabella seguente vengono descritti i valori del flag di formato del nome. È possibile specificare solo uno dei flag. Per altre informazioni su questi formati, vedere FLT_FILE_NAME_INFORMATION.

Valore	Significato
FLT_FILE_NAME_NORMALIZED	Il parametro FileNameInformation riceve l'indirizzo di una struttura contenente il nome normalizzato per il file.
FLT_FILE_NAME_OPENED	Il parametro FileNameInformation riceve l'indirizzo di una struttura contenente il nome utilizzato all'apertura del file.
FLT_FILE_NAME_SHORT	Il parametro FileNameInformation riceve l'indirizzo di una struttura contenente il nome breve (8.3) per il file. Il nome breve è composto da un massimo di 8 caratteri, seguito immediatamente da un punto e da un massimo di 3 caratteri. Il nome breve di un file non include il nome del volume, il percorso della directory o il nome del flusso.

Nella tabella seguente vengono descritti i valori del flag del metodo di query. È possibile specificare solo uno dei flag.

Valore	Significato
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe esegue una query nella cache dei nomi di Gestione filtri per le informazioni sul nome del file. Se il nome non viene trovato nella cache, FltGetFileNameInformationUnsafe esegue una query sul file system e memorizza nella cache il risultato.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe esegue una query nella cache dei nomi di Gestione filtri per le informazioni sul nome del file. FltGetFileNameInformationUnsafe non esegue query sul file system.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe esegue una query nel file system per individuare le informazioni sul nome file. FltGetFileNameInformationUnsafe non esegue query sulla cache dei nomi di Gestione filtri e non memorizza nella cache il risultato della query del file system.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe esegue una query nella cache dei nomi di Gestione filtri per le informazioni sul nome del file. Se il nome non viene trovato nella cache ed è attualmente sicuro, FltGetFileNameInformationUnsafe esegue una query nel file system per le informazioni sul nome del file e memorizza nella cache il risultato.

[out] FileNameInformation

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo di una struttura di FLT_FILE_NAME_INFORMATION allocata dal sistema. FltGetFileNameInformationUnsafe alloca questa struttura dal pool di paging. Quando queste informazioni non sono più necessarie, il chiamante deve rilasciare la struttura chiamando FltReleaseFileNameInformation. Questo parametro è obbligatorio e non può essere impostato su NULL.

Valore restituito

FltGetFileNameInformationUnsafe restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_INVALID_NAME_REQUEST	Oggetto file a cui punta il parametro FileObject non è attualmente aperto. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	È stato passato un valore non valido per il parametro FileNameInformation . Si tratta di un codice di errore.

Commenti

La routine FltGetFileNameInformationUnsafe viene fornita in modo da poter eseguire una query sul nome di un oggetto file all'esterno del contesto di un'operazione di I/O su tale oggetto file; in caso contrario, devi chiamare FltGetFileNameInformation.

A differenza della routine FltGetFileNameInformation , FltGetFileNameInformationUnsafe non protegge il chiamante dai seguenti tipi di circostanze, in cui l'esecuzione di query sul file system per le informazioni sul nome può causare deadlock per i metodi di query diversi da FLT_FILE_NAME_QUERY_CACHE_ONLY:

Nel percorso di I/O di paging.
Quando il campo TopLevelIrp del thread corrente non è NULL. Per altre informazioni, vedere IoGetTopLevelIrp.
Al termine di un'operazione di IRP_MJ_CLEANUP ; ovvero nel percorso post-pulizia, pre-chiusura o post-chiusura (l'oggetto file di destinazione ha il flag FO_CLEANUP_COMPLETE impostato).
In una routine di callback di preoperazione (PFLT_PRE_OPERATION_CALLBACK) o postoperazione (PFLT_POST_OPERATION_CALLBACK) per una delle operazioni seguenti:
- 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
In una routine di callback post-operatorio per IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION.
Quando tutti i controller di accesso sono disabilitati; ovvero, quando KeAreAllApcsDisabled restituisce TRUE.

Per Windows Vista/Server 2008 e versioni successive, se un minifilter non dispone ancora di un'istanza di filtro, ad esempio nella routine DriverEntry , può essere usata NULL per il parametro Instance . Ciò consente alle routine DriverEntry di accedere alle informazioni sul nome file. Ad eccezione di questo caso, un NULL valore per il parametro di istanza è riservato per l'uso del sistema.

In operazioni di creazione, collegamento rigido e ridenominazione, il tunneling dei nomi file può invalidare il componente finale nelle informazioni sul nome file normalizzate recuperate da un driver minifilter in una routine di callback di preoperazione. Se un driver minifilter recupera le informazioni sui nomi di file normalizzati in una routine di callback di preoperazione (PFLT_PRE_OPERATION_CALLBACK) chiamando una routine come FltGetFileNameInformationUnsafe, deve chiamare FltGetTunneledName dalla routine di callback di postoperazione (PFLT_POST_OPERATION_CALLBACK) per recuperare le informazioni corrette sul nome file per il file.

Per altre informazioni sul nome file normalizzato, vedere FLT_FILE_NAME_INFORMATION.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	fltkernel.h (include Fltkernel.h)
Libreria	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (vedere la sezione Osservazioni)