Funzione FltGetDestinationFileNameInformation (fltkernel.h)

Articolo
12/05/2023

La routine FltGetDestinationFileNameInformation esegue una query sul nome del file per la directory padre della destinazione, quindi costruisce un nome di percorso completo per un file o una directory che viene rinominata o per cui viene creato un collegamento rigido NTFS.

Sintassi

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Parametri

[in] Instance

Puntatore istanza opaca per un'istanza del driver minifilter collegata al volume in cui risiede il file.

[in] FileObject

Puntatore all'oggetto file per il file. Questo parametro è obbligatorio e non può essere NULL.

[in, optional] RootDirectory

Per le operazioni di collegamento: Se il collegamento deve essere creato nella stessa directory del file collegato o se FileName contiene il nome percorso completo per la creazione del collegamento, questo parametro è NULL. In caso contrario, è un handle per la directory in cui deve essere creato il collegamento.

Per le operazioni di ridenominazione: Se il file non viene spostato in una directory diversa o se FileName contiene il nome percorso completo, questo parametro è NULL. In caso contrario, è un handle per la directory in cui risiede il file dopo la ridenominazione.

[in] FileName

Per le operazioni di collegamento: Puntatore a una stringa di caratteri wide contenente il nome da assegnare al collegamento appena creato.

Per le operazioni di ridenominazione: Puntatore a una stringa di caratteri wide contenente il nuovo nome per il file.

[in] FileNameLength

Lunghezza, in byte, della stringa di caratteri wide a cui FileName punta.

[in] NameOptions

Valore FLT_FILE_NAME_OPTIONS contenente flag che specificano il formato delle informazioni sul nome da restituire, il metodo di query da usare e i flag di nome file aggiuntivi. Questo parametro è obbligatorio e non può essere NULL.

Di seguito sono riportati i valori del flag di formato nome. È possibile specificare un solo flag di formato nome. Si noti che FLT_FILE_NAME_SHORT non è un valore di flag valido per questo parametro.

Valore del flag formato nome	Significato
FLT_FILE_NAME_NORMALIZED	Il parametro FileName riceve il nome di destinazione normalizzato per il file.
FLT_FILE_NAME_OPENED	Il parametro FileName riceve il nome di destinazione per il file, in base al nome utilizzato al momento dell'apertura del file. Questo nome file non è normalizzato.

Di seguito sono riportati i valori del flag del metodo di query. È possibile specificare un solo flag di metodo di query.

Valore del flag del metodo query	Significato
FLT_FILE_NAME_QUERY_DEFAULT	Se non è attualmente sicuro eseguire query sul file system per il nome del file di destinazione, FltGetDestinationFileNameInformation non fa nulla. In caso contrario, FltGetDestinationFileNameInformation esegue una query sulla cache dei nomi di Filter Manager per le informazioni sul nome del file per la directory padre della destinazione e quindi aggiunge il nome della destinazione. Se il nome risultante non viene trovato nella cache, FltGetDestinationFileNameInformation esegue query sul file system e memorizza nella cache il risultato.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation esegue una query sulla cache dei nomi di Filter Manager per le informazioni sul nome del file per la directory padre della destinazione e quindi aggiunge il nome della destinazione. Non esegue query sul file system.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation esegue una query sul file system per le informazioni sul nome file della directory padre della destinazione e quindi aggiunge il nome di destinazione. Non esegue query sulla cache dei nomi di Filter Manager e non memorizza nella cache il risultato della query del file system.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation esegue una query sulla cache dei nomi di Filter Manager per le informazioni sul nome del file per la directory padre della destinazione e quindi aggiunge il nome della destinazione. Se il nome non viene trovato nella cache e attualmente è sicuro, FltGetDestinationFileNameInformation esegue una query sul file system per le informazioni sul nome file e memorizza nella cache il risultato.

Di seguito sono riportati i valori del flag del nome file. È possibile specificare qualsiasi combinazione di questi flag. Si noti che FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE non è un flag pertinente per questo parametro poiché FltGetDestinationFileNameInformation non viene usato in un callback post-create.

Valore del flag nome file	Significato
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation indirizza la richiesta di nome all'istanza del filtro chiamante da completare.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation non memorizza nella cache il nome del file recuperato. I minifiltri del provider di nomi usano questo flag perché eseguono query intermedie per generare un nome.

[out] RetFileNameInformation

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 file. FltGetDestinationFileNameInformation alloca questa struttura dal pool di pagine. Questo parametro è obbligatorio e non può essere NULL.

Valore restituito

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

Codice restituito	Descrizione
STATUS_FLT_INVALID_NAME_REQUEST	Questo valore viene restituito per uno dei motivi seguenti: (1) FltGetDestinationFileNameInformation non può ottenere informazioni sul nome file se il campo TopLevelIrp del thread corrente non è NULL, perché la ricorsione del file system risultante potrebbe causare deadlock o overflow dello stack. (2) FLT_FILE_NAME_SHORT è stato specificato per il flag di formato nome nel parametro NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	È stato specificato un valore non valido per il parametro NameOptions . Si tratta di un codice di errore.
STATUS_MOUNT_POINT_NOT_RESOLVED	Il nome del percorso di destinazione contiene un punto di montaggio che si risolve in un volume diverso da quello in cui risiede il file. Poiché un'operazione di creazione di rinomina o collegamento rigido può essere eseguita solo all'interno di un volume e non tra volumi, l'operazione ha esito negativo. Si tratta di un codice di errore.

Commenti

I minifilter chiamano in genere FltGetDestinationFileNameInformation in una routine di callback preoperazione per un'operazione di ridenominazione o creazione di collegamenti rigidi, il che significa che il nome del file di destinazione più probabilmente non esiste. Il nome "destinazione" è:

Per una ridenominazione di un file, il nome del file avrà se la ridenominazione avrà esito positivo. Ad esempio, quando si ridenomina nome1 a nome2, name2 è il nome di destinazione.
Per un'operazione di creazione hard link, il nome aggiunto al file system. Ad esempio, quando si aggiunge il nome del collegamento rigido2 al file esistente denominato name1, name2 è il nome di destinazione.

FltGetDestinationFileNameInformation restituisce le informazioni sul nome del file di destinazione in formato normalizzato o "file aperto". Per altre informazioni su questi formati, vedere la struttura FLT_FILE_NAME_INFORMATION .

Il puntatore a oggetti file passato per il parametro FileObject deve essere il membro FileObject della struttura FLT_RELATED_OBJECTS per l'operazione o il puntatore Data-Iopb-TargetFileObject>> per l'operazione, dove Data è la struttura dei dati di callback per l'operazione (FLT_CALLBACK_DATA). Il puntatore a oggetti file non può essere il membro Data-Iopb-Parameters.SetFileInformation.FileObject>>, perché questo campo non viene usato uniformemente in file system.

Se l'utente ha aperto il file usando l'ID file ma non ha privilegi per l'intero percorso, FltGetDestinationFileNameInformation restituisce solo la parte del percorso per cui l'utente ha privilegi.

Un'operazione di ridenominazione o creazione di collegamenti rigidi può essere eseguita solo all'interno di un volume e non tra volumi. Pertanto, tale operazione non riesce se il nome del percorso di destinazione contiene un punto di montaggio che si risolve in un volume diverso da quello in cui risiede il file. Per altre informazioni sulle operazioni di ridenominazione, vedere la struttura FILE_RENAME_INFORMATION . Per altre informazioni sulle operazioni di creazione a collegamento rigido, vedere le strutture di FILE_LINK_INFORMATION .

Dopo una chiamata riuscita a FltGetDestinationFileNameInformation, il chiamante è responsabile del rilascio del puntatore restituito nel parametro RetFileNameInformation quando non è più necessario chiamando FltReleaseFileNameInformation.

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

In creazione, hard-link e operazioni di ridenominazione, il tunneling dei nomi file può causare l'invalidazione del componente finale nelle informazioni sul nome file normalizzate recuperate da un driver minifilter in una routine di callback preoperazione. Se un driver minifilter recupera le informazioni sul nome file normalizzato in una routine di callback preoperazione (PFLT_PRE_OPERATION_CALLBACK) chiamando una routine come FltGetDestinationFileNameInformation, deve chiamare FltGetTunneledName dalla routine di callback postoperazione per recuperare le informazioni sul nome del file corrette per il file.

Per altre informazioni sul nome file normalizzato, vedere FLT_FILE_NAME_INFORMATION.

Il tunneling dei nomi file influisce solo sulle operazioni create, hard-link e rinominate in questo modo. Non influisce su altre operazioni di I/O, ad esempio lettura e scrittura.

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