PFLT_NORMALIZE_NAME_COMPONENT_EX Rückruffunktion (fltkernel.h)

Artikel
08/07/2023

Ein Minifiltertreiber, der Dateinamen für den Namencache des Filter-Managers bereitstellt, kann eine Routine vom Typ PFLT_NORMALIZE_NAME_COMPONENT_EX als NormalizeNameComponentExCallback-Rückrufroutine des Minifiltertreibers registrieren.

Syntax

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
)
{...}

Parameter

[in] Instance

Undurchsichtiger instance Zeiger für den Minifiltertreiber instance, für den diese Rückrufroutine registriert ist.

[in] FileObject

Zeiger auf das Dateiobjekt für die Datei, deren Name angefordert wird, oder auf die Datei, die das Ziel des IRP_MJ_SET_INFORMATION Vorgangs ist, wenn das flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME festgelegt ist. Weitere Informationen finden Sie weiter unten im Flags-Parameter .

[in] ParentDirectory

Zeiger auf eine UNICODE_STRING Struktur, die den Namen des übergeordneten Verzeichnisses für diese Namenskomponente enthält.

[in] VolumeNameLength

Länge des übergeordneten Verzeichnisnamens in Byte, der in der Struktur gespeichert ist, auf die der ParentDirectory-Parameter verweist.

[in] Component

Zeiger auf eine UNICODE_STRING-Struktur, die die zu erweiternde Namenskomponente enthält.

[out] ExpandComponentName

Zeiger auf eine FILE_NAMES_INFORMATION-Struktur , die die erweiterten (normalisierten) Dateinameninformationen für die Namenskomponente empfängt.

[in] ExpandComponentNameLength

Länge des Puffers, auf den der Parameter ExpandComponentName verweist, in Byte.

[in] Flags

Namensnormalisierungsflags. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE gibt an, dass bei dem zu normalisierenden Namen die Groß-/Kleinschreibung beachtet wird. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME gibt an, dass die Rückrufroutine aufgerufen wurde, um einen FltGetDestinationFileNameInformation-Routineaufruf zu verarbeiten. Wenn das flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME festgelegt ist, stellt FileObject die Datei/das Verzeichnis dar, die das Ziel des IRP_MJ_SET_INFORMATION-Vorgangs ist. Wenn das flag FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME nicht festgelegt ist, stellt FileObject die Datei/das Verzeichnis dar, deren Name angefordert wird.

[in, out] NormalizationContext

Zeiger auf vom Minifilter vom Treiber bereitgestellte Kontextinformationen, die bei nachfolgenden Aufrufen dieser Rückrufroutine übergeben werden sollen, um die verbleibenden Komponenten im gleichen Dateinamenpfad zu normalisieren.

Rückgabewert

Diese Rückrufroutine gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück. Wenn die namenskomponente, die der Component-Parameter angibt, nicht im übergeordneten Verzeichnis vorhanden ist, das der ParentDirectory-Parameter angibt, sollte diese Rückrufroutine STATUS_NO_SUCH_FILE zurückgeben. Wenn diese Rückrufroutine eine IRP_MN_QUERY_DIRECTORY (FileNamesInformation)-Anforderung an das übergeordnete Verzeichnis ausgibt, gibt das Dateisystem den richtigen status Code zurück. In diesem Fall kann dieser Rückruf einfach den status Code zurückgeben, den das Dateisystem zurückgibt.

Hinweise

Der Hauptunterschied zwischen der Rückrufroutine NormalizeNameComponentExCallback und der Rückrufroutine NormalizeNameComponentCallback (vom Typ PFLT_NORMALIZE_NAME_COMPONENT) besteht darin, dass die Rückrufroutine NormalizeNameComponentExCallback den zusätzlichen FileObject-Parameter unterstützt. Das Dateiobjekt (FileObject) kann vom Minifiltertreiber verwendet werden, um die TXN_PARAMETER_BLOCK-Struktur für den Vorgang abzurufen, an dem die Datei/das Verzeichnis beteiligt ist, indem die IoGetTransactionParameterBlock-Routine aufgerufen wird. Die TXN_PARAMETER_BLOCK-Struktur kann vom Minifiltertreiber verwendet werden, um eigene Erstellungsanforderungen im Kontext der Transaktion ausstellen, an der dieses Dateiobjekt beteiligt ist.

Um diese Rückrufroutine zu registrieren, speichert der Minifiltertreiber die Adresse einer Routine vom Typ PFLT_NORMALIZE_NAME_COMPONENT_EX im NormalizeNameComponentExCallback-Element der FLT_REGISTRATION Struktur, die der Minifiltertreiber als Parameter an FltRegisterFilter übergibt.

Der Filter-Manager ruft diese Rückrufroutine auf, um den Minifiltertreiber nach den normalisierten Namen für Komponenten im Dateinamenpfad abzufragen, deren Namen der Minifiltertreiber geändert hat. Wenn der Dateinamepfad mehr als eine solche Komponente enthält, kann der Filter-Manager diese Rückrufroutine mehrmals aufrufen, um alle Komponenten im Pfad zu normalisieren. Der Minifiltertreiber kann den Parameter NormalizationContext verwenden, um Kontextinformationen an nachfolgende Aufrufe dieser Rückrufroutine zu übergeben.

Wenn der Minifiltertreiber den Parameter NormalizationContext verwendet, sollte er auch eine Rückrufroutine für die Normalisierungskontextbereinigung registrieren. Weitere Informationen finden Sie im Referenzeintrag für PFLT_NORMALIZE_CONTEXT_CLEANUP.