FltAllocateCallbackData-Funktion (fltkernel.h)

Artikel
02/06/2025

FltAllocateCallbackData weist eine Rückrufdatenstruktur zu, mit der ein Minifiltertreiber eine E/A-Anforderung initiieren kann.

Syntax

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

Parameter

[in] Instance

Undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, die den E/A-Vorgang initiiert. Dieser Parameter ist erforderlich und kann nicht NULL-werden.

[in, optional] FileObject

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

[out] RetNewCallbackData

Zeiger auf eine vom Aufrufer zugewiesene Variable, die die Adresse der neu zugeordneten Rückrufdaten (FLT_CALLBACK_DATA) -Struktur empfängt.

Rückgabewert

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

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

Bemerkungen

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 Speicher zu, der von einer nachfolgenden E/A-Anforderung benötigt werden kann. Wenn eine E/A-Anforderung, z. B. FltPerformSynchronousIo oder FltPerformAsynchronousIo, zusätzlichen Speicher für eine bestimmte Struktur erfordert, kann die Anforderung auf eine Speicherzuweisung stoßen. Die FltAllocateCallbackDataEx- Routine kann verwendet werden, um dieses potenzielle Problem zu vermeiden, indem Speicher vorab zugewiesen wird, damit zusätzliche Strukturen in einer E/A-Anforderung verwendet werden können. Wenn ein Speicherzuordnungsproblem für die RetNewCallbackData Struktur oder zusätzliche erforderliche Strukturen vorliegt, kann es an der Stelle der Rückrufdatenzuordnung behandelt werden.

Rückrufdatenstrukturen werden aus nicht seitengebundenen Pools zugewiesen.

Nach dem Initialisieren der Parameter der Rückrufdatenstruktur, die von FltAllocateCallbackDatazurückgegeben wird, initiiert der Aufrufer den E/A-Vorgang, indem die Struktur an FltPerformSynchronousIo oder FltPerformAsynchronousIoübergeben wird. Diese Routinen senden den E/A-Vorgang nur an die Minifiltertreiberinstanzen, die unterhalb der initiierenden Instanz (im parameter Instance angegeben) und an das Dateisystem angefügt sind. Über der angegebenen Instanz angefügte Minifiltertreiber erhalten den E/A-Vorgang nicht.

Minifiltertreiber können nur IRP-basierte E/A-Vorgänge initiieren. Sie können keine schnellen E/A- oder Dateisystemfiltervorgänge (FSFilter) initiieren.

Minifiltertreiber sollten FltAllocateCallbackData, FltPerformAsynchronousIound 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 zugeordnete Rückrufdatenstruktur nicht mehr benötigt wird, ist der Aufrufer dafür verantwortlich, sie durch Aufrufen FltFreeCallbackDatafreizusprechen.