PFLT_NORMALIZE_NAME_COMPONENT_EX funzione di callback (fltkernel.h)

Articolo
02/06/2025

Un driver minifilter che fornisce nomi di file per la cache dei nomi del gestore filtri può registrare una routine di tipo PFLT_NORMALIZE_NAME_COMPONENT_EX come routine di callback del driver minifilter NormalizeNameComponentExCall back.

Sintassi

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

Parametri

[in] Instance

Puntatore a istanze opache per l'istanza del driver minifilter per cui è registrata questa routine di callback.

[in] FileObject

Puntatore all'oggetto file per il file il cui nome viene richiesto o il file che rappresenta la destinazione dell'operazione di IRP_MJ_SET_INFORMATION se è impostato il flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME. Per altre informazioni, vedere il parametro flag di seguito.

[in] ParentDirectory

Puntatore a una struttura UNICODE_STRING che contiene il nome della directory padre per questo componente del nome.

[in] VolumeNameLength

Lunghezza, in byte, del nome della directory padre archiviata nella struttura a cui punta il parametro ParentDirectory.

[in] Component

Puntatore a una struttura UNICODE_STRING che contiene il componente del nome da espandere.

[out] ExpandComponentName

Puntatore a una struttura FILE_NAMES_INFORMATION che riceve le informazioni sul nome del file espanso (normalizzato) per il componente del nome.

[in] ExpandComponentNameLength

Lunghezza, in byte, del buffer a cui punta il parametro ExpandComponentName.

[in] Flags

Contrassegni di normalizzazione dei nomi. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE specifica che il nome da normalizzare fa distinzione tra maiuscole e minuscole. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME specifica che la routine di callback è stata chiamata per il servizio di un FltGetDestinationFileNameInformation chiamata di routine. Se il flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME è impostato, FileObject rappresenta il file o la directory di destinazione dell'operazione di IRP_MJ_SET_INFORMATION. Se il flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME non è impostato, FileObject rappresenta il file o la directory il cui nome viene richiesto.

[in, out] NormalizationContext

Puntatore a informazioni di contesto fornite dal driver minifilter da passare in qualsiasi chiamata successiva a questa routine di callback effettuata per normalizzare i componenti rimanenti nello stesso percorso del nome file.

Valore restituito

Questa routine di callback restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato. Se il componente del nome specificato dal parametro componente non esiste nella directory padre specificata dal parametro ParentDirectory, questa routine di callback deve restituire STATUS_NO_SUCH_FILE. Se questa routine di callback invia una richiesta di IRP_MN_QUERY_DIRECTORY (FileNamesInformation) alla directory padre, il file system restituisce il codice di stato corretto. In questo caso, questo callback può semplicemente restituire il codice di stato restituito dal file system.

Osservazioni

La differenza principale tra la routine di callback NormalizeNameComponentExCallback e la routine di callback NormalizeNameComponentCallback (di tipo PFLT_NORMALIZE_NAME_COMPONENT) è che la routine di callback NormalizeNameComponentExCallback supporta il parametro aggiuntivo FileObject. L'oggetto file (FileObject) può essere utilizzato dal driver minifilter per recuperare la struttura TXN_PARAMETER_BLOCK per l'operazione che fa parte del file o della directory chiamando la routine IoGetTransactionParameterBlock. La struttura TXN_PARAMETER_BLOCK può essere utilizzata dal driver minifilter per inviare richieste di creazione personalizzate nel contesto della transazione a cui partecipa l'oggetto file.

Per registrare questa routine di callback, il driver minifilter archivia l'indirizzo di una routine di tipo PFLT_NORMALIZE_NAME_COMPONENT_EX nel NormalizeNameComponentExCallback membro della struttura FLT_REGISTRATION che il driver minifilter passa come parametro a FltRegisterFilter.

Gestione filtri chiama questa routine di callback per eseguire una query sul driver minifilter per i nomi normalizzati per i componenti nel percorso del nome file i cui nomi sono stati modificati dal driver minifilter. Se il percorso del nome file contiene più componenti di questo tipo, il gestore filtri può chiamare più volte questa routine di callback durante il processo di normalizzazione di tutti i componenti nel percorso. Il driver minifilter può usare il parametro NormalizationContext per passare le informazioni di contesto alle chiamate successive a questa routine di callback.

Se il driver minifilter usa il parametro NormalizationContext, deve anche registrare una routine di callback di pulizia del contesto di normalizzazione. Per altre informazioni, vedere la voce di riferimento per PFLT_NORMALIZE_CONTEXT_CLEANUP.