Funzione FltGetTunneledName (fltkernel.h)

Articolo
08/07/2023

La routine FltGetTunneledName recupera il nome sottoposto a tunnel per un file, dato il nome normalizzato restituito per il file da una chiamata precedente a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation.

Sintassi

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Parametri

[in] CallbackData

Puntatore alla struttura dei dati di callback per l'operazione di I/O (FLT_CALLBACK_DATA). Questo parametro è obbligatorio e non può essere NULL.

[in] FileNameInformation

Puntatore a una struttura FLT_FILE_NAME_INFORMATION contenente informazioni sul nome normalizzate restituite da una chiamata precedente a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation per il file.

[out] RetTunneledFileNameInformation

Puntatore a una variabile allocata dal chiamante che riceve l'indirizzo di una struttura appena allocata contenente il nome del file tunnelato. Se non viene trovato alcun nome tunneled, questa variabile riceve NULL. Questo parametro è obbligatorio e non può essere NULL nell'input.

Valore restituito

FltGetTunneledName restituisce STATUS_SUCCESS se il nome sottoposto a tunnel viene trovato o se non è presente alcun nome tunnelato per il file. In caso contrario, restituisce un valore NTSTATUS, ad esempio quanto segue:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.

Commenti

I file system, ad esempio NTFS e FAT, usano una cache del tunnel per volume per mantenere brevemente i nomi dei file e altri metadati per i file che vengono rinominati, collegati a o eliminati. Il tunneling dei nomi file può causare l'invalidazione delle informazioni sul nome file normalizzate restituite da una chiamata di preoperazione a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation.

Se un driver minifilter recupera le informazioni sul nome del file normalizzato nella routine di callback preoperazione (PFLT_PRE_OPERATION_CALLBACK) per una creazione (IRP_MJ_CREATE), il collegamento rigido (IRP_MJ_SET_INFORMATION con FILE_INFORMATION_CLASS impostato su FileRenameInformation) o l'operazione di ridenominazione (IRP_MJ_SET_INFORMATION con FILE_INFORMATION_CLASS impostata su FileLinkInformation), deve chiamare FltGetTunneledName dalla routine di callback postperazione (PFLT_POST_OPERATION_CALLBACK) per recuperare le informazioni corrette sul nome file per il file.

Solo le informazioni sul nome file normalizzate sono interessate dal tunneling. Gestione filtri non può assicurarsi che il componente finale venga normalizzato fino a quando non si verifica effettivamente l'operazione di creazione, collegamento rigido o ridenominazione, perché il tunneling può causare la modifica di un nome breve in un nome lungo. Pertanto, un driver minifilter deve chiamare FltGetTunneledName dalla routine di callback postoperation per determinare se le informazioni del nome file normalizzate recuperate nella routine di callback di preoperazione sono valide.

Per altre informazioni sul nome file normalizzato, vedere FLT_FILE_NAME_INFORMATION.

I driver minifilter che recuperano solo informazioni sul nome file breve o aperto non devono chiamare FltGetTunneledName.

Dopo aver chiamato FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation nella routine di callback di preoperazione, il driver minifilter deve archiviare il puntatore FileNameInformation restituito nella struttura CompletamentoContext della routine di callback di preoperazione in modo che il callback di postoperazione possa passare questo puntatore nel parametro FileNameInformation a FltGetTunneledNameName.

Nota

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:

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

Se non viene trovato alcun nome tunnelato per il file, il parametro RetTunneledFileNameInformation riceve NULL.

Dopo una chiamata riuscita a FltGetTunneledName, il chiamante è responsabile del rilascio dei puntatori RetTunneledFileNameInformation e FileNameInformation quando non sono più necessari chiamando FltReleaseFileNameInformation.

FltGetTunneledName deve essere chiamato solo dalla routine di callback postperazione di un driver minifilter per IRP_MJ_CREATE o IRP_MJ_SET_INFORMATION. La chiamata a FltGetTunneledName da una routine di callback di postperazione per qualsiasi altro tipo di operazione di I/O, oppure chiamarla da una routine di callback di preoperazione, è un errore di programmazione.

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

Il tunneling file consente la compatibilità con i programmi che si basano sui file system per mantenere le meta-informazioni sui file per un breve periodo di tempo; ad esempio, per il processo di salvataggio sicuro. Il tunneling mantiene l'associazione tra il nome lungo e breve di un file (8,3). Quando un nome file viene rimosso da una directory (rinominare o eliminare), la relativa coppia di nomi brevi e lunghi e il tempo di creazione vengono salvati in una cache del tunnel, chiaveta dal nome rimosso. Quando un nome viene aggiunto a una directory (rinominare o creare), la cache viene eseguita per determinare se sono presenti informazioni da ripristinare. La cache è efficace per ogni istanza di una directory. Se viene eliminata una directory, la cache viene rimossa.

Requisiti

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