FltCbdqInitialize-Funktion (fltkernel.h)

Artikel
02/06/2025

FltCbdqInitialize initialisiert die Verteilertabelle eines Minifiltertreibers für die Datenwarteschlange.

Syntax

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

Parameter

[in] Instance

Undurchsichtiger Instanzzeiger für die Instanz, deren Rückrufdatenwarteschlange initialisiert werden soll.

[in, out] Cbdq

Zeiger auf eine vom Minifiltertreiber zugewiesene Rückrufdatenwarteschlange.

[in] CbdqInsertIo

Zeiger auf eine vom Aufrufer bereitgestellte Einfügerückungsroutine. Der Filter-Manager ruft diese Routine auf, um die angegebene Rückrufdatenstruktur in die Warteschlange einzufügen. Diese Routine wird wie folgt deklariert:

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Cbd

Zeigen Sie auf die Rückrufdatenstruktur, die in die Warteschlange eingefügt werden soll.

InsertContext

Kontextinformationspunkt, der als InsertContext Parameter an FltCbdqInsertIoübergeben wurde.

[in] CbdqRemoveIo

Zeiger auf eine vom Aufrufer bereitgestellte Remove-Rückrufroutine. Der Filter-Manager ruft diese Routine auf, um die angegebene Rückrufdatenstruktur aus der Warteschlange zu entfernen. Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Cbd

Zeigen Sie auf die Rückrufdatenstruktur, die aus der Warteschlange entfernt werden soll.

[in] CbdqPeekNextIo

Zeiger auf eine vom Aufrufer bereitgestellte Vorschaurückrufroutine. Der Filter-Manager ruft diese Funktion auf, um einen Zeiger auf den nächsten E/A-Vorgang abzurufen, der PeekContext- in der Warteschlange entspricht; oder, wenn CbdNULList, um einen Zeiger auf den ersten übereinstimmenden E/A-Vorgang in der Warteschlange zu erhalten. Der Minifiltertreiber definiert vollständig die Bedeutung PeekContext- und definiert, wann ein E/A-Vorgang einem bestimmten PeekContext-entspricht. Diese Routine wird wie folgt deklariert:

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Cbd

Zeigen Sie auf die Rückrufdatenstruktur, die die Position in der Warteschlange markiert, um mit der Suche nach einer Übereinstimmung mit PeekContext-zu beginnen. Wenn CbdNULList, beginnt die Suche an der Spitze der Warteschlange.

PeekContext

Kontextinformationspunkt, der als PeekContext Parameter an FltCbdqRemoveNextIoübergeben wurde.

[in] CbdqAcquire

Zeiger auf eine von einem Anrufer bereitgestellte Rückrufroutine zum Sperren der Warteschlange. Der Filter-Manager ruft diese Routine auf, um die Sperre in der Warteschlange abzurufen, bevor versucht wird, ein Element aus der Warteschlange einzufügen oder daraus zu entfernen. Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Irql

Zeiger auf eine vom System bereitgestellte Variable, die den aktuellen IRQL empfängt. Die gleiche Variable wird an die entsprechende CbdqRelease Routine übergeben.

[in] CbdqRelease

Zeiger auf eine vom Anrufer bereitgestellte Sperreswarteschlangenrückrufroutine. Der Filter-Manager ruft diese Routine auf, um die Sperre freizugeben, die sie durch Aufrufen der entsprechenden CbdqAcquire Routine erhalten hat. Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Irql

Die gleiche vom System bereitgestellte Variable, die den aktuellen IRQL als Irql Parameter für die entsprechende CbdqAcquire Routine empfangen hat.

[in] CbdqCompleteCanceledIo

Zeiger auf eine vom Aufrufer bereitgestellte Abbruchroutine. Der Filter-Manager ruft diese Routine auf, um dem Minifiltertreiber zu signalisieren, um einen abgebrochenen E/A-Vorgang abzuschließen. Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Zeiger auf die abbruchsichere Rückrufdatenwarteschlange des Minifiltertreibers. Diese Warteschlange muss durch Aufrufen von FltCbdqInitializeinitialisiert worden sein.

Cbd

Zeigen Sie auf die Rückrufdatenstruktur für den abgebrochenen E/A-Vorgang.

Rückgabewert

FltCbdqInitialize gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück.

Bemerkungen

Die neu initialisierte Rückrufdatenwarteschlange befindet sich im aktivierten Zustand, was bedeutet, dass Rückrufdatenstrukturelemente in die Warteschlange eingefügt werden können. Die Warteschlange kann durch Aufrufen von FltCbdqDisable deaktiviert und durch Aufrufen von FltCbdqEnableerneut aktiviert werden.

Minifiltertreiber 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 Minifiltertreiber ihre Warteschlangen abbruchsicher machen; Das System verarbeitet den E/A-Abbruch für die Minifiltertreiber transparent.

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

Minifiltertreiber können jede interne Implementierung für die Warteschlange verwenden. Der Filter-Manager interagiert mit der Warteschlangenimplementierung des Minifiltertreibers ausschließlich über die Von FltCbdqInitializebereitgestellten Verteilerroutinen.

Das System sperrt die Warteschlange bei Bedarf automatisch und entsperrt sie. Minifiltertreiber implementieren keine Sperren innerhalb ihrer CbdqInsertIo, CbdqRemoveIound CbdqPeekNextIo Routinen.

Minifiltertreiber können jeden der Synchronisierungsgrundtypen des Betriebssystems als Sperrmechanismus in ihren CbdqAcquire und CbdqRelease Routinen verwenden, z. B. eine Spin lock, Mutex-Objektoder Ressourcenvariablen. Beachten Sie, dass ein Minifiltertreiber anstelle eines Mutex oder einer Ressource zum Schutz der Warteschlange die FltCbdqXxx Routinen bei IRQL <= DISPATCH_LEVEL aufrufen kann. Wenn ein Mutex oder eine Ressource verwendet wird, muss der Minifiltertreiber bei IRQL <= APC_LEVEL ausgeführt werden, wenn eine dieser Routinen aufgerufen wird, außer FltCbdqInitialize.

Der Minifiltertreiber bearbeitet die Warteschlange nicht direkt. Stattdessen wird FltCbdqInsertIo, FltCbdqRemoveIound FltCbdqRemoveNextIo aufgerufen, um eine Rückrufdatenstruktur hinzuzufügen oder zu entfernen. Diese Routinen rufen wiederum die Rückruffunktionen auf, die der Minifiltertreiber FltCbdqInitializebereitgestellt hat.

Minifiltertreiber sollten die Warteschlangenroutinen wie folgt implementieren.

Cbdq Routine	Implementierung
CbdqInsertIo	Fügen Sie die angegebene Rückrufdatenstruktur in die Warteschlange ein.
CbdqRemoveIo	Entfernen Sie die angegebene Rückrufdatenstruktur aus der Warteschlange.
CbdqPeekNextIo	Diese Routine sollte es dem System ermöglichen, die Rückrufdatenstrukturen mit übereinstimmenden PeekContext- in der Warteschlange zu durchlaufen. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) sollte den ersten übereinstimmenden Eintrag in der Warteschlange zurückgeben, und CbdqPeekNextIo(Cbdq, Cbd, PeekContext) sollte den nächsten übereinstimmenden Eintrag nach der angegebenen Rückrufdatenstruktur in der Warteschlange zurückgeben. Der Minifiltertreiber definiert vollständig die Bedeutung PeekContext- und definiert, wann eine Rückrufdatenstruktur einem PeekContext- wert entspricht.
CbdqAcquire	Diese Routine sollte die Warteschlange sperren, damit kein anderer Thread darauf zugreifen kann. Minifiltertreiber können jeden Sperrmechanismus verwenden, um die Warteschlange zu sperren. Wenn der Minifiltertreiber die KeAcquireSpinLock Routine verwendet, kann der Minifiltertreiber die Speicherposition verwenden, auf die der Irql-Parameter der Routine verweist, um die IRQL zu speichern. Andernfalls können Minifiltertreiber diesen Parameter ignorieren.
CbdqRelease	Diese Routine sollte die Warteschlange entsperren, die von CbdqAcquireerstellt wurde. Wenn der Minifiltertreiber eine Drehsperre verwendet und den IRQL-Wert im Irql Parameter von CbdqAcquirezurückgegeben hat, übergibt das System diesen Wert im Irql Parameter von CbdqRelease. Der Minifiltertreiber kann die IRQL verwenden, um die Drehsperre zu entsperren, indem KeReleaseSpinLockaufgerufen wird. Andernfalls können Minifiltertreiber den Irql Parameter ignorieren.
CbdqCompleteCanceledIo	Diese Routine sollte einen abgebrochenen E/A-Vorgang abschließen. Normalerweise können Minifiltertreiber einfach FltCompletePendedPreOperation-aufrufen (Daten, FLT_PREOP_COMPLETE, NULL-). Minifiltertreiber müssen die Rückrufdatenstruktur nicht dequeue - der Filter-Manager ruft automatisch die CbdqRemoveIo- der Warteschlange auf, bevor sie CbdqCompleteCanceledIoaufrufen.