Funzione FltGetFileNameInformation (fltkernel.h)

Articolo
08/07/2023

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

Sintassi

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

Parametri

[in] CallbackData

Puntatore a una struttura FLT_CALLBACK_DATA , ovvero la struttura dei dati di callback per l'operazione di I/O. Questo parametro è obbligatorio e non può essere NULL.

[in] NameOptions

Valore FLT_FILE_NAME_OPTIONS contenente i flag che specificano il formato delle informazioni sul nome da restituire, nonché il metodo di query che verrà utilizzato da Gestione filtri. Il chiamante deve includere un flag di formato del nome e un flag del metodo di query. I flag aggiuntivi possono essere usati dai driver minifilter del provider dei nomi per specificare le opzioni di query dei nomi. Questo parametro è obbligatorio e non può essere NULL.

Di seguito sono riportati i valori del flag di formato del nome file. È possibile specificare solo uno dei flag seguenti. Per una spiegazione di questi formati, vedere FLT_FILE_NAME_INFORMATION.

Valore del flag formato nome	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. Non valido nel percorso di pre-creazione.

Di seguito sono riportati i valori del flag del metodo di query del nome file. È possibile specificare solo uno dei flag seguenti.

Valore del flag del metodo di query	Significato
FLT_FILE_NAME_QUERY_DEFAULT	Se non è attualmente sicuro eseguire query sul file system per il nome del file, FltGetFileNameInformation non esegue alcuna operazione. In caso contrario, FltGetFileNameInformation 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, FltGetFileNameInformation esegue una query sul file system e memorizza nella cache il risultato.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation esegue una query nella cache dei nomi di Gestione filtri per le informazioni sul nome del file. FltGetFileNameInformation non esegue query sul file system.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation esegue una query sul file system per individuare le informazioni sul nome file. FltGetFileNameInformation 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	FltGetFileNameInformation 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, FltGetFileNameInformation esegue una query sul file system per le informazioni sul nome file e memorizza nella cache il risultato.

I minifiltri del provider dei nomi usano i flag seguenti per specificare le proprietà delle operazioni relative al nome file.

Valore del flag provider dei nomi	Significato
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Un minifilter del provider di nomi può usare questo flag per specificare che una richiesta di query del nome deve essere reindirizzata a se stessa (minifilter del provider di nomi) anziché essere soddisfatta dai provider di nomi più in basso nello stack.
FLT_FILE_NAME_DO_NOT_CACHE	Questo flag indica che il nome recuperato dalla query non deve essere memorizzato nella cache. I minifiltri del provider di nomi usano questo flag durante l'esecuzione di query intermedie per generare un nome.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Un minifilter del provider di nomi può usare questo flag per specificare che è possibile eseguire query sul nome nel percorso di post-creazione anche se è stato restituito STATUS_REPARSE. È responsabilità del chiamante assicurarsi che il campo FileObject-FileName> non sia stato modificato. Non usare questo flag con punti di montaggio o punti simbolici reparse point.

[out] FileNameInformation

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo di una struttura FLT_FILE_NAME_INFORMATION allocata dal sistema contenente le informazioni sul nome del file. FltGetFileNameInformation alloca questa struttura dal pool di paging. Questo parametro è obbligatorio e non può essere NULL.

Valore restituito

Se le informazioni sul nome vengono restituite correttamente, FltGetFileNameInformation restituisce STATUS_SUCCESS. In caso contrario, restituisce un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation non può ottenere informazioni sul nome file in una delle circostanze seguenti se la query non può essere soddisfatta dalla cache dei nomi di Gestione filtri: Nel percorso di I/O di paging. Quando il campo TopLevelIrp del thread corrente non è NULL, perché la ricorsione del file system risultante potrebbe causare deadlock o overflow dello stack. Per altre informazioni su questo problema, 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 (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. FltGetFileNameInformation non può ottenere il nome breve di un file nel percorso di pre-creazione. STATUS_FLT_INVALID_NAME_REQUEST è un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	Restituito quando viene passato un parametro non valido, ad esempio uno dei seguenti: Il parametro FileNameInformation non può essere NULL. Il parametro CallbackData non può essere NULL. STATUS_INVALID_PARAMETER è un codice di errore.
STATUS_FLT_NAME_CACHE_MISS	Le informazioni sul nome file non vengono trovate nella cache dei nomi e NameOptions include FLT_FILE_NAME_QUERY_CACHE_ONLY. -oppure- Le informazioni sul nome file non vengono trovate nella cache dei nomi quando NameOptions include FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP e le informazioni sul nome file non possono essere eseguite query dal file system. Una chiamata aggiuntiva a FltGetFileNameInformation con FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY impostata in NameOptions può restituire le informazioni sul nome del file.
STATUS_NOT_SAME_DEVICE	Il file sottoposto a query durante la pre-creazione si trova in un volume diverso rispetto alla relativa directory padre. Questo errore viene restituito per le query nome normalizzate, in cui il file era una giunzione o un collegamento simbolico risolto in un volume diverso.
STATUS_ACCESS_DENIED	Se l'utente ha aperto il file in base all'ID file ma non ha privilegi di attraversamento per l'intero percorso, FltGetFileNameInformation ha esito negativo con questo valore restituito. STATUS_ACCESS_DENIED è un codice di errore. -oppure- Il file è un file di sistema con accesso negato.

Commenti

FltGetFileNameInformation restituisce le informazioni sul nome richiesto per il file o la directory di destinazione dell'operazione descritta da CallbackData, nel formato specificato. Il file o la directory non devono essere ancora aperti dal file system.

Per un'operazione di pre-creazione, se il membro CallbackData-Iopb-OperationFlags>> contiene il flag bit per bit SL_OPEN_TARGET_DIRECTORY, FltGetFileNameInformation restituisce il nome della directory contenitore (padre) per il file specificato. Questo nome è il percorso effettivo aperto dall'operazione di creazione.

Per analizzare il contenuto della struttura FLT_FILE_NAME_INFORMATION restituita da FltGetFileNameInformation, chiama FltParseFileNameInformation. Per altre informazioni sui formati di nome file, vedere FLT_FILE_NAME_INFORMATION.

Dopo la corretta chiamata a FltGetFileNameInformation, il chiamante è responsabile del rilascio del puntatore restituito nel parametro FileNameInformation quando il puntatore non è più necessario. Il chiamante esegue questa operazione chiamando FltReleaseFileNameInformation.

Il chiamante non deve modificare il contenuto della struttura restituita nel parametro FileNameInformation perché questa struttura viene memorizzata nella cache da Gestione filtri in modo che tutti i driver minifilter possano usarlo.

Se FltGetFileNameInformation viene chiamato nella routine di callback di preoperazione per un'operazione di creazione per recuperare il nome aperto, FltGetFileNameInformation ha esito positivo anche se il percorso del file aperto non esiste nel volume.

Se FltGetFileNameInformation viene chiamato nella routine di callback di preoperazione per un'operazione di creazione per recuperare il nome normalizzato, FltGetFileNameInformation ha esito positivo anche se il componente finale del percorso del file aperto non esiste nel volume.

Nota

Il supporto SMB (Server Message Block) per l'esecuzione di query sui nomi di file normalizzati in un volume remoto varia in base alle diverse versioni di Windows 10. Per informazioni dettagliate, vedere il protocollo MS-SMB2 .

In operazioni di creazione, collegamento rigido e ridenominazione, il tunneling dei nomi di file può causare l'invalidazione del 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 sul nome file normalizzate in una routine di callback di preoperazione (PFLT_PRE_OPERATION_CALLBACK) chiamando una routine come FltGetFileNameInformation, 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 Windows 8.1 e versioni precedenti, FltGetFileNameInformation può includere un tipo di flussosolo quando viene chiamato dal callback di pre-creazione di un filtro. Per distinguere tra il flusso predefinito di un file e i flussi di metadati, questa chiamata deve essere eseguita nell'operazione di pre-creazione. Il tipo di flusso risultante rimarrà valido per tutta la durata del file.

Prima di Windows 8, Gestione filtri ottiene il nome normalizzato per un file o una directory raccogliendo le informazioni sul nome per ogni componente del percorso del file. Questa operazione richiedeva più query nel file system per compilare il percorso completo. A partire da Windows 8, i file system locali supportano la classe di informazioni sul file FileNormalizedNameInformation e per ottenere il nome normalizzato è necessaria una sola query. I file system remoti potrebbero non supportare la classe di informazioni sui file FileNormalizedNameInformation . In questo caso, è comunque necessaria una query per ogni componente del percorso del file per assemblare il nome normalizzato. In determinate condizioni di rete, una query full name può richiedere una quantità significativa di tempo per il completamento.

Per altre informazioni sul nome file normalizzato, vedere FLT_FILE_NAME_INFORMATION.

Nota

Il tunneling dei nomi file influisce solo sulle operazioni di creazione, collegamento rigido e ridenominazione in questo modo. Non influisce su altre operazioni di I/O, ad esempio lettura e scrittura.

Le operazioni abbinate seguenti possono causare il tunneling del nome file:

delete (name)/create(name)
delete (name)/rename(source, name)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

Requisiti

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