FltPerformAsynchronousIo-Funktion (fltkernel.h)

Artikel
02/06/2025

Ein Minifiltertreiber ruft FltPerformAsynchronousIo auf, um einen asynchronen E/A-Vorgang zu initiieren.

Syntax

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

Parameter

[in, out] CallbackData

Zeiger auf eine Rückrufdatenstruktur (FLT_CALLBACK_DATA), die einem vorherigen Aufruf von FltAllocateCallbackData-zugeordnet wurde. Dieser Parameter ist erforderlich und kann nicht NULL-werden. Der Aufrufer ist dafür verantwortlich, diese Struktur freizusprechen, wenn sie nicht mehr benötigt wird, indem FltFreeCallbackDataaufgerufen wird.

[in] CallbackRoutine

Zeigen Sie auf eine PFLT_COMPLETED_ASYNC_IO_CALLBACK-typierte Rückrufroutine, die aufgerufen werden soll, wenn der E/A-Vorgang abgeschlossen ist. Hinweis: Der Filter-Manager ruft diese Routine auf, nachdem er die Postoperation-Rückrufroutinen (PFLT_POST_OPERATION_CALLBACK) aller Minifiltertreiber aufruft, deren Instanzen unterhalb der initiierenden Instanz angefügt sind (im parameter Instance angegeben, um FltAllocateCallbackData). Dieser Parameter ist erforderlich und kann nicht NULL-werden. Der Filter-Manager ruft diese Routine immer auf, auch wenn FltPerformAsynchronousIo fehlschlägt.

[in] CallbackContext

Kontextzeiger, der an die CallbackRoutine Dieser Parameter ist optional und kann NULL-werden.

Rückgabewert

FltPerformAsynchronousIo gibt STATUS_SUCCESS zurück, um anzugeben, dass der E/A-Vorgang vom Dateisystem abgeschlossen wurde, und die Rückrufroutine, auf die CallbackRoutine verweist, aufgerufen wurde. Andernfalls wird ein entsprechender NTSTATUS-Wert zurückgegeben, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE Anforderungen können nicht asynchron ausgeführt werden. Dies ist ein Fehlercode.
STATUS_PENDING	Der vorgang hat STATUS_PENDING zurückgegeben. Der Filter-Manager ruft die Rückrufroutine auf, die CallbackRoutine darauf verweist, wann der E/A-Vorgang abgeschlossen ist. Dieser Code gibt nur an, dass der Vorgang initiiert wurde.
STATUS_FLT_IO_COMPLETE	Der Vorgang wurde durch die Voroperationsrückrufroutine des Minifiltertreibers abgeschlossen, dessen Instanzen unterhalb der initiierenden Instanz angefügt sind.

Bemerkungen

Ein Minifiltertreiber ruft FltPerformAsynchronousIo auf, um einen asynchronen E/A-Vorgang nach dem Aufruf FltAllocateCallbackData zu initiieren, um eine Rückrufdatenstruktur für den Vorgang zuzuweisen.

FltPerformAsynchronousIo sendet den E/A-Vorgang nur an die Minifiltertreiberinstanzen, die unterhalb der initiierenden Instanz angefügt sind (im parameter Instance angegeben an FltAllocateCallbackData) und das Dateisystem. Ü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 FltPerformAsynchronousIo nur für asynchrone E/A-Vorgänge verwenden, für die Routinen wie die folgenden nicht verwendet werden können:

IRP_MJ_CREATE Anforderungen können nicht asynchron ausgeführt werden.

Die Rückrufdatenstruktur (FLT_CALLBACK_DATA) kann jederzeit freigegeben oder wiederverwendet werden, nachdem die Rückrufroutine aufgerufen CallbackRoutine Punkte aufgerufen wurde. Der Aufrufer kann die Rückrufdatenstruktur freigeben, indem FltFreeCallbackData aufgerufen oder durch Aufrufen FltReuseCallbackDatafür die Wiederverwendung vorbereitet wird.

Anmerkung

STATUS_SUCCESS und STATUS_FLT_IO_COMPLETE zeigen an, dass der E/A-Vorgang abgeschlossen wurde, aber nicht den endgültigen Status des E/A-Vorgangs angeben. Um den tatsächlichen Vorgangsstatus zu ermitteln, der von den zugrunde liegenden Minifiltertreibern, Filtertreibern und Dateisystem zurückgegeben wird, sollte die CallbackRoutine- das IoStatus-Element der rückrufdatenstruktur untersuchen, die in der CallbackRoutine's CallbackContext Parameter empfangen wurde.

Da der Filter-Manager immer die Rückrufroutine aufruft, auf die CallbackRoutine verweist, auch wenn FltPerformAsynchronous Io fehlschlägt, kann der Minifiltertreiber die Frei- oder Wiederverwendevorgänge direkt in der Rückrufroutine ausführen.

Der Aufrufer von FltPerformAsynchronousIo kann bei IRQL <= APC_LEVEL ausgeführt werden, wenn das IRP_PAGING_IO Flag im IrpFlags Member der FLT_IO_PARAMETER_BLOCK Struktur für den Vorgang festgelegt ist. (Dieses Kennzeichen ist nur für IRP_MJ_READ-, IRP_MJ_WRITE-, IRP_MJ_QUERY_INFORMATION- und IRP_MJ_SET_INFORMATION vorgänge gültig.) Andernfalls muss der Aufrufer unter IRQL-PASSIVE_LEVEL ausgeführt werden.