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 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 di 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 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 è costituito da un massimo di 8 caratteri, seguito immediatamente da un punto e fino a 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 una query sul file system per il nome del file, FltGetFileNameInformation non esegue alcuna operazione. In caso contrario, FltGetFileNameInformation esegue una query sulla 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 sulla 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 ottenere le informazioni sul nome del file. FltGetFileNameInformation non esegue una 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 sulla 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 provider di nomi usano i flag seguenti per specificare le proprietà delle operazioni relative al nome file.

Valore del flag del provider di nomi	Significato
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Un minifiltro del provider di nomi può usare questo flag per specificare che una richiesta di query del nome deve essere reindirizzata a se stessa (minifiltro del provider di nomi) anziché essere soddisfatta dai provider di nomi inferiori nello stack.
FLT_FILE_NAME_DO_NOT_CACHE	Questo flag indica che il nome recuperato da questa query non deve essere memorizzato nella cache. I minifiltri provider di nomi usano questo flag durante l'esecuzione di query intermedie per generare un nome.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Un minifiltro provider di nomi può usare questo flag per specificare che è sicuro 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 di FLT_FILE_NAME_INFORMATION allocata dal sistema contenente le informazioni sul nome 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 è possibile ottenere informazioni sul nome file in una delle circostanze seguenti se la query non può essere soddisfatta dalla cache dei nomi di Filter Manager: 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 di 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 postperation per IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Quando tutti i controller di accesso sono disabilitati; ovvero, quando KeAreAllApcsDisabled restituisce TRUE. FltGetFileNameInformation non è possibile 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 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. -o- Le informazioni sul nome file non vengono trovate nella cache dei nomi quando NameOptions include FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP e non è possibile eseguire query sulle informazioni sul nome file 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 directory padre. Questo errore viene restituito per le query di 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 dispone dei privilegi di attraversamento per l'intero percorso, FltGetFileNameInformation ha esito negativo con questo valore restituito. STATUS_ACCESS_DENIED è un codice di errore. -o- Il file è un file di sistema con accesso negato.

Osservazioni

FltGetFileNameInformation restituisce le informazioni sul nome richieste per il file o la directory che rappresenta la 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, chiamare FltParseFileNameInformation. Per altre informazioni sui formati di nome file, vedere FLT_FILE_NAME_INFORMATION.)

Dopo una chiamata riuscita 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 minifiltri 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 la del protocolloMS-SMB2.

In operazioni di creazione, collegamento rigido e ridenominazione, il tunneling dei nomi file può causare l'invalidazione del componente finale nelle informazioni sul nome file normalizzate recuperate da un driver minifiltro in una routine di callback di preoperazione. Se un driver minifilter recupera le informazioni sul nome file normalizzato in una routine di callback preoperatorio (PFLT_PRE_OPERATION_CALLBACK) chiamando una routine come FltGetFileNameInformation, deve chiamare FltGetTunneledName dalla routine di callback dopo la postperazione (PFLT_POST_OPERATION_CALLBACK) per recuperare le informazioni sul nome file corrette per il file.

Per Windows 8.1 e versioni precedenti, FltGetFileNameInformation può includere un tipo di flusso solo 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 ha ottenuto 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 al file system per compilare il percorso completo. A partire da Windows 8, i file system locali supportano il FileNormalizedNameInformation classe di informazioni sui file ed è necessaria una sola query per ottenere il nome normalizzato. 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 con nome completo 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 nome:

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

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
intestazione	fltkernel.h (include Fltkernel.h)
libreria	FltMgr.lib
dll	Fltmgr.sys
IRQL	<= APC_LEVEL (vedere Valore restituito)