Funzione FltGetTunneledName (fltkernel.h)

Articolo
10/30/2024

La routine FltGetTunneledName recupera il nome sottoposto a tunneling per un file, dato il nome normalizzato restituito per il file da una chiamata precedente a FltGetFileNameInformation, FltGetFileNameInformationUnsafeo 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, FltGetFileNameInformationUnsafeo 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 sottoposto a tunneling. Se non viene trovato alcun nome sottoposto a tunneling, questa variabile riceve NULL. Questo parametro è obbligatorio e non può essere NULL all'input.

Valore restituito

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

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

Osservazioni

I file system, ad esempio NTFS e FAT, usano una cache di tunnel per volume per conservare brevemente i nomi di file e altri metadati per i file che vengono rinominati, collegati o eliminati. Il tunneling dei nomi file può causare il componente finale nelle informazioni sul nome file normalizzate restituite da una chiamata di preoperazione a FltGetFileNameInformation, FltGetFileNameInformationUnsafeo FltGetDestinationFileNameInformation da invalidare.

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

Solo le informazioni sul nome file normalizzate sono interessate dal tunneling. Gestione filtri non è in grado di garantire che il componente finale venga normalizzato fino a quando non è stata effettivamente eseguita 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 minifiltro deve chiamare FltGetTunneledName dalla routine di callback di postoperazione per determinare se le informazioni sul nome file normalizzate recuperate nella routine di callback 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, FltGetFileNameInformationUnsafeo FltGetDestinationFileNameInformation nella routine di callback di preoperazione, Il driver minifilter deve archiviare il puntatore FileNameInformation nella struttura del callback di preoperazione della routine di callback CompletionContext in modo che il callback di postoperazione possa passare questo puntatore nel parametro FileNameInformation a FltGetTunneledName.

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( nome, newname)/create( nome)
rename(name, newname)/rename(source, name)

Se non viene trovato alcun nome sottoposto a tunneling per il file, il parametro RetTunneledFileNameInformation riceve NULL.

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

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

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

Il tunneling dei file consente la compatibilità con i programmi che si basano su 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 di un file lungo e breve (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, con chiave con il nome rimosso. Quando un nome viene aggiunto a una directory (rinominare o creare), viene eseguita una ricerca nella cache per determinare se sono presenti informazioni da ripristinare. La cache è efficace per ogni istanza di una directory. Se una directory viene eliminata, la cache viene rimossa.