PFLT_GENERATE_FILE_NAME Rückruffunktion (fltkernel.h)

Artikel
02/06/2025

Ein Minifiltertreiber, der Dateinamen für den Namenscache des Filter-Managers bereitstellt, kann eine Routine vom Typ PFLT_GENERATE_FILE_NAME als GenerateFileNameCallback-Routine des Minifiltertreibers registrieren.

Syntax

PFLT_GENERATE_FILE_NAME PfltGenerateFileName;

NTSTATUS PfltGenerateFileName(
  [in]           PFLT_INSTANCE Instance,
  [in]           PFILE_OBJECT FileObject,
  [in, optional] PFLT_CALLBACK_DATA CallbackData,
  [in]           FLT_FILE_NAME_OPTIONS NameOptions,
  [out]          PBOOLEAN CacheFileNameInformation,
  [out]          PFLT_NAME_CONTROL FileName
)
{...}

Parameter

[in] Instance

Undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, für die diese Rückrufroutine registriert ist.

[in] FileObject

Ein Zeiger auf ein Dateiobjekt für die Datei, deren Name angefordert wird.

[in, optional] CallbackData

Ein Zeiger auf die Rückrufdatenstruktur für den Vorgang, in dem dieser Name angefordert wird. Dieser Parameter ist NULL-, wenn FltGetFileNameInformationUnsafe- aufgerufen wird, um den Namen der Datei abzurufen.

[in] NameOptions

FLT_FILE_NAME_OPTIONS Wert, der das Namensformat, die Abfragemethode und die Flags für diese Dateinameninformationsabfrage angibt.

[out] CacheFileNameInformation

Ein Zeiger auf einen booleschen Wert, der angibt, ob dieser Name zwischengespeichert werden kann. Auf TRUE- für die Ausgabe festgelegt, wenn der Name zwischengespeichert werden kann; auf FALSE festgelegt andernfalls.

[out] FileName

Ein Zeiger auf einen filter-manager zugewiesenen FLT_NAME_CONTROL Struktur, um den Dateinamen für die Ausgabe zu erhalten.

Rückgabewert

Diese Rückrufroutine gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück.

Bemerkungen

Um diese Rückrufroutine zu registrieren, speichert der Minifiltertreiber die Adresse einer Routine vom Typ PFLT_GENERATE_FILE_NAME im GenerateFileNameCallback Member der FLT_REGISTRATION Struktur, die der Minifiltertreiber als Parameter an FltRegisterFilterübergibt.

Der Filter-Manager ruft diese Rückrufroutine auf, damit der Minifiltertreiber Dateinamenanforderungen von anderen Minifiltertreibern abfangen kann, die sich darüber im Minifilter-Treiberinstanzstapel befinden. Mithilfe dieser Rückrufroutine und der PFLT_NORMALIZE_NAME_COMPONENT Rückrufroutine kann der Minifiltertreiber eigene Dateinameninformationen bereitstellen.

Um zu bestimmen, welches Dateinamenformat angefordert wird, rufen Sie FltGetFileNameFormat für den parameter NameOptions auf.

Vor Windows 8 wird diese Rückrufroutine nur für geöffnete Dateinamen und kurze Dateinamen aufgerufen. Wenn der Filter-Manager eine Anforderung für einen normalisierten Dateinamen empfängt, ruft er diese Rückrufroutine auf, um den geöffneten Dateinamen anzufordern. Anschließend wird der PFLT_NORMALIZE_NAME_COMPONENT Rückruf des Minifiltertreibers aufgerufen, um jede Komponente im Dateinamen zu normalisieren.

Ab Windows 8 wird diese Rückrufroutine auch für normalisierte Namen aufgerufen. Wenn der Filter-Manager eine Anforderung für einen normalisierten Dateinamen empfängt, ruft er diese Rückrufroutine mit FLT_FILE_NAME_NORMALIZED auf, die im parameter NameOptions angegeben ist. Wenn der Minifilter STATUS_SUCCESS aus diesem Rückruf zurückgibt, wird der PFLT_NORMALIZE_NAME_COMPONENT Rückruf des Minifilters nicht aufgerufen. Wenn der Minifilter einen Fehlercode (z. B. STATUS_NOT_SUPPORTED) zurückgibt, ruft der Filter-Manager diese Rückrufroutine erneut auf und fordert den geöffneten Dateinamen an. Der Filter-Manager ruft dann den PFLT_NORMALIZE_NAME_COMPONENT Rückruf des Minifiltertreibers auf, um jede Komponente im Dateinamen zu normalisieren.

Wenn diese Rückrufroutine aufgerufen wird, generiert der Minifiltertreiber basierend auf den Dateinameninformationen des Dateisystems für die Datei eigene Dateinameninformationen. Um die Dateinameninformationen des Dateisystems für eine Datei abzurufen, rufen Sie FltGetFileNameInformation, FltGetFileNameInformationUnsafeoder FltGetDestinationFileNameInformationauf.

Bei geöffneten Dateinamen sollten die generierten Dateinameninformationen Volumeinformationen enthalten. Für eine Remotedatei sollte sie auch Freigabeinformationen enthalten.

Nachfolgend sehen Sie ein Beispiel für einen geöffneten Dateinamen für eine Remotedatei:

\Device\LanManRedirector\MyServer\MyShare\Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

Weitere Informationen zu Dateinamenformaten finden Sie in den Referenzeinträgen für FLT_FILE_NAME_INFORMATION und FltParseFileNameInformation.

Nachdem die Dateinameninformationen generiert wurden, muss der Minifiltertreiber FltCheckAndGrowNameControl- aufrufen, um zu überprüfen, ob die FLT_NAME_CONTROL Struktur, auf die der FileName Parameter verweist, einen Namenspuffer enthält, der groß genug ist, um den generierten Dateinamen zu enthalten. Wenn der Namenspuffer zu klein ist, ersetzt FltCheckAndGrowNameControl ihn durch eine größere. Der Minifiltertreiber speichert dann die Dateinameninformationen im Namenspuffer und gibt zurück.