FltAllocateCallbackData-Funktion (fltkernel.h)

Artikel
08/07/2023

FltAllocateCallbackData weist eine Rückrufdatenstruktur zu, die ein Minifiltertreiber verwenden kann, um eine E/A-Anforderung zu initiieren.

Syntax

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parameter

[in] Instance

Undurchsichtiger instance Zeiger für den Minifiltertreiber instance, der den E/A-Vorgang initiiert. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in, optional] FileObject

Dateiobjektzeiger, der im E/A-Vorgang verwendet werden soll. Dieser Parameter ist optional und kann NULL sein.

[out] RetNewCallbackData

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse der neu zugewiesenen Rückrufdatenstruktur (FLT_CALLBACK_DATA) empfängt.

Rückgabewert

FltAllocateCallbackData gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert wie den folgenden zurück:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData ist beim Versuch, die Rückrufdatenstruktur zuzuweisen, einen Poolzuordnungsfehler aufgetreten. Dies ist ein Fehlercode.

Hinweise

Ein Minifiltertreiber kann FltAllocateCallbackData aufrufen, um eine Rückrufdatenstruktur (FLT_CALLBACK_DATA) für einen vom Minifiltertreiber initiierten E/A-Vorgang zuzuweisen.

Hinweis Die FltAllocateCallbackData-Routine weist nicht den gesamten Arbeitsspeicher zu, der für eine nachfolgende E/A-Anforderung erforderlich sein könnte. Wenn eine E/A-Anforderung, z. B . FltPerformSynchronousIo oder FltPerformAsynchronousIo, zusätzlichen Arbeitsspeicher für eine bestimmte Struktur erfordert, kann die Anforderung auf eine Speicherzuordnung stoßen. Die FltAllocateCallbackDataEx-Routine kann verwendet werden, um dieses potenzielle Problem zu vermeiden, indem Arbeitsspeicher für zusätzliche Strukturen, die in einer E/A-Anforderung verwendet werden sollen, vorab zugewiesen wird. Wenn ein Speicherbelegungsproblem für die RetNewCallbackData-Struktur oder für zusätzliche erforderliche Strukturen vorliegt, kann es am Punkt der Rückrufdatenzuordnung behandelt werden.

Rückrufdatenstrukturen werden aus einem nicht ausgestellten Pool zugeordnet.

Nach dem Initialisieren der Parameter der von FltAllocateCallbackData zurückgegebenen Rückrufdatenstruktur initiiert der Aufrufer den E/A-Vorgang, indem er die Struktur an FltPerformSynchronousIo oder FltPerformAsynchronousIo übergibt. Diese Routinen senden den E/A-Vorgang nur an die Minifiltertreiberinstanzen, die unterhalb der initiierenden instance angefügt sind (im Parameter Instanz angegeben) und an das Dateisystem. Minifiltertreiber, die über den angegebenen instance angefügt sind, empfangen den E/A-Vorgang nicht.

Minifiltertreiber können nur IRP-basierte E/A-Vorgänge initiieren. Sie können keine schnellen E/A- oder FSFilter-Rückrufvorgänge (File System Filter) initiieren.

Minifiltertreiber sollten FltAllocateCallbackData, FltPerformAsynchronousIo und FltPerformSynchronousIo nur für E/A-Vorgänge verwenden, für die Routinen wie die folgenden nicht verwendet werden können:

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Wenn die von FltAllocateCallbackData zugewiesene Rückrufdatenstruktur nicht mehr benötigt wird, ist der Aufrufer für die Freigabe durch Aufrufen von FltFreeCallbackData verantwortlich.