FltCbdqInsertIo-Funktion (fltkernel.h)

Artikel
02/26/2024

FltCbdqInsertIo fügt die Rückrufdatenstruktur für einen E/A-Vorgang in die Rückrufdatenwarteschlange eines Filtertreibers ein.

Syntax

NTSTATUS FLTAPI FltCbdqInsertIo(
  [in, out]      PFLT_CALLBACK_DATA_QUEUE            Cbdq,
  [in]           PFLT_CALLBACK_DATA                  Cbd,
  [in, optional] PFLT_CALLBACK_DATA_QUEUE_IO_CONTEXT Context,
  [in, optional] PVOID                               InsertContext
);

Parameter

[in, out] Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Aufrufers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitialize initialisiert worden sein.

[in] Cbd

Zeiger auf die Rückrufdatenstruktur (FLT_CALLBACK_DATA) für den E/A-Vorgang, der in die Warteschlange eingereiht werden soll. Der Vorgang muss ein IRP-basierter E/A-Vorgang sein.

[in, optional] Context

Vom Aufrufer bereitgestellte Variable, die einen undurchsichtigen Kontextzeiger für die E/A-Anforderung empfängt. Filtertreiber können diesen Zeiger verwenden, um ein bestimmtes Element in der Warteschlange zu identifizieren, sodass es durch Aufrufen von FltCbdqRemoveIo entfernt werden kann. Wenn der Filtertreiber nicht erforderlich ist, um bestimmte E/A-Anforderungen aus der Warteschlange zu entfernen, kann dieser Parameter NULL sein.

[in, optional] InsertContext

Kontextzeiger, der an die CbdqInsertIo-Rückrufroutine des Filtertreibers übergeben werden soll.

Rückgabewert

FltCbdqInsertIo gibt STATUS_SUCCESS zurück, wenn die Rückrufdatenstruktur in die Rückrufdatenwarteschlange eingefügt wurde, oder einen entsprechenden NTSTATUS-Wert wie den folgenden:

Rückgabecode	Beschreibung
STATUS_FLT_CBDQ_DISABLED	Die Rückrufdatenstruktur wurde nicht in die Rückrufdatenwarteschlange eingefügt, da die Warteschlange derzeit deaktiviert ist. Um die Warteschlange erneut zu verwenden, rufen Sie FltCbdqEnable auf. Dies ist ein Fehlercode.

Hinweis

Im Erfolgsfall gibt FltCbdqInsertIo alles zurück, was der InsertIo-Rückruf des Filters zurückgibt. Beispielsweise kann ein Filter entweder STATUS_SUCCESS oder STATUS_PENDING zurückgeben, um den Erfolg anzugeben. Es ist wichtig, dass der Filter unabhängig davon, welchen Wert er verwendet, um den Erfolg anzugeben, selbstkonsistent ist.

Hinweise

FltCbdqInsertIo fügt die angegebene Rückrufdatenstruktur (FLT_CALLBACK_DATA) in die Rückrufdatenwarteschlange eines Filtertreibers ein.

Beachten Sie, dass zwischen einem Filtertreiber, der die Rückrufdaten einfügt, und dem zugehörigen IRP, der abgebrochen wird, eine potenzielle Racebedingung besteht. Dies kann vermieden werden, indem sofort die Abbruchroutine der Warteschlange aufgerufen wird, wenn die IRP bereits abgebrochen wurde.

Filtertreiber können die FltCbdqXxx-Routinen verwenden, um eine Rückrufdatenwarteschlange für IRP-basierte E/A-Vorgänge zu implementieren. Mithilfe dieser Routinen können Filtertreiber ihre Warteschlangen abbruchsicher machen. das System verarbeitet den E/A-Abbruch für die Filtertreiber transparent.

Die FltCbdqXxx-Routinen können nur für IRP-basierte E/A-Vorgänge verwendet werden. Verwenden Sie das Makro FLT_IS_IRP_OPERATION , um zu bestimmen, ob eine bestimmte Rückrufdatenstruktur einen IRP-basierten E/A-Vorgang darstellt.

Eine Rückrufdatenwarteschlange wird durch Aufrufen von FltCbdqInitialize initialisiert. FltCbdqInsertIo verwendet die in der Dispatchtabelle der Warteschlange bereitgestellten Funktionen, um die Warteschlange zu sperren und die Rückrufdatenstruktur in die Warteschlange einzufügen. Der Einfügevorgang selbst wird von der CbdqInsertIo-Routine der Warteschlange ausgeführt.

Ausführliche Informationen zum Erstellen einer Rückrufdatenwarteschlange finden Sie unter FltCbdqInitialize . Verwenden Sie FltCbdqRemoveIo , um eine bestimmte E/A-Anforderung aus der Warteschlange zu entfernen, oder FltCbdqRemoveNextIo , um die nächste verfügbare E/A-Anforderung zu entfernen.

Wenn die Warteschlange durch eine Spinsperre anstelle eines Mutex-Objekts oder einer Ressourcenvariable geschützt ist, kann der Aufrufer von FltCbdqInsertIo unter IRQL <= DISPATCH_LEVEL ausgeführt werden. Wenn ein Mutex oder eine Ressource verwendet wird, muss der Aufrufer unter IRQL <= APC_LEVEL ausgeführt werden.