FltCbdqInitialize-Funktion (fltkernel.h)

Artikel
08/07/2023

FltCbdqInitialize initialisiert die Rückrufdatenwarteschlangen-Dispatchtabelle eines Minifiltertreibers.

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 instance Zeiger für die instance, deren Rückrufdatenwarteschlange initialisiert werden soll.

[in, out] Cbdq

Zeiger auf eine Vom Minifiltertreiber zugeordnete Rückrufdatenwarteschlange.

[in] CbdqInsertIo

Zeiger auf eine vom Aufrufer bereitgestellte Rückrufroutine. 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 FltCbdqInitialize initialisiert worden sein.

Cbd

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

InsertContext

Kontextinformationszeiger, der als InsertContext-Parameter an FltCbdqInsertIo übergeben wurde.

[in] CbdqRemoveIo

Zeiger auf eine vom Aufrufer bereitgestellte 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 FltCbdqInitialize initialisiert worden sein.

Cbd

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

[in] CbdqPeekNextIo

Zeiger auf eine vom Aufrufer bereitgestellte Rü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 CbdNULL ist, um einen Zeiger auf den ersten übereinstimmenden E/A-Vorgang in der Warteschlange zu erhalten. Der Minifiltertreiber definiert vollständig die Bedeutung von PeekContext und definiert, wann ein E/A-Vorgang mit einem bestimmten PeekContext übereinstimmt. 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 FltCbdqInitialize initialisiert worden sein.

Cbd

Zeiger auf die Rückrufdatenstruktur, die die Position in der Warteschlange markiert, um mit der Suche nach einer Übereinstimmung mit PeekContext zu beginnen. Wenn CbdNULL ist, beginnt die Suche am Anfang der Warteschlange.

PeekContext

Kontextinformationszeiger, der als PeekContext-Parameter an FltCbdqRemoveNextIo übergeben wurde.

[in] CbdqAcquire

Zeiger auf eine vom Anrufer bereitgestellte Rückrufroutine für die Abrufwarteschlangensperre. Der Filter-Manager ruft diese Routine auf, um die Sperre für die 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 FltCbdqInitialize initialisiert worden sein.

Irql

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

[in] CbdqRelease

Zeiger auf eine vom Aufrufer bereitgestellte Rückrufroutine für die Freigabewarteschlange. Der Filter-Manager ruft diese Routine auf, um die Sperre freizugeben, die er 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 FltCbdqInitialize initialisiert worden sein.

Irql

Dieselbe 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, 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 FltCbdqInitialize initialisiert worden sein.

Cbd

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

Rückgabewert

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

Hinweise

Die neu initialisierte Rückrufdatenwarteschlange befindet sich im Status aktiviert. Dies bedeutet, dass Rückrufdatenstrukturelemente in die Warteschlange eingefügt werden können. Die Warteschlange kann durch Aufrufen von FltCbdqDisable und erneut aktiviert werden, indem FltCbdqEnable aufgerufen wird.

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 gestalten. 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. Verwenden Sie das Makro FLT_IS_IRP_OPERATION , um zu bestimmen, ob eine bestimmte Rückrufdatenstruktur einen IRP-basierten E/A-Vorgang darstellt.

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 FltCbdqInitialize bereitgestellten Dispatchroutinen.

Das System sperrt die Warteschlange automatisch und entsperrt sie bei Bedarf. Minifiltertreiber implementieren keine Sperren in ihren Routinen CbdqInsertIo, CbdqRemoveIo und CbdqPeekNextIo .

Minifiltertreiber können alle Synchronisierungsgrundtypen des Betriebssystems als Sperrmechanismus in ihren Routinen CbdqAcquire und CbdqRelease verwenden, z. B. eine Drehsperre, ein Mutex-Objekt oder eine Ressourcenvariable. Wenn ein Minifiltertreiber eine Drehsperre anstelle eines Mutexs oder einer Ressource zum Schutz der Warteschlange verwendet, kann er die FltCbdqXxx-Routinen unter IRQL <= DISPATCH_LEVEL aufrufen. Wenn ein Mutex oder eine Ressource verwendet wird, muss der Minifiltertreiber unter IRQL <= APC_LEVEL ausgeführt werden, wenn eine dieser Routinen außer FltCbdqInitialize aufgerufen wird.

Der Minifiltertreiber bearbeitet die Warteschlange nicht direkt. Stattdessen werden FltCbdqInsertIo, FltCbdqRemoveIo und FltCbdqRemoveNextIo aufgerufen, um eine Rückrufdatenstruktur hinzuzufügen oder zu entfernen. Diese Routinen rufen wiederum die Rückruffunktionen auf, die der Minifiltertreiber für FltCbdqInitialize bereitgestellt 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 übereinstimmendem 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 von PeekContext und definiert, wann eine Rückrufdatenstruktur mit einem PeekContext-Wert übereinstimmt.
CbdqAcquire	Diese Routine sollte die Warteschlange sperren, sodass kein anderer Thread darauf zugreifen kann. Minifiltertreiber können einen beliebigen Sperrmechanismus verwenden, um die Warteschlange zu sperren. Wenn der Minifiltertreiber die KeAcquireSpinLock-Routine verwendet, kann der Minifiltertreiber den Speicherspeicherort verwenden, auf den der Irql-Parameter der Routine verweist, um den IRQL zu speichern. Andernfalls können Minifiltertreiber diesen Parameter ignorieren.
CbdqRelease	Diese Routine sollte die von CbdqAcquire erstellte Warteschlange entsperren. Wenn der Minifiltertreiber eine Drehsperre verwendet und den IRQL-Wert im Irql-Parameter von CbdqAcquire zurückgegeben hat, übergibt das System diesen Wert im Irql-Parameter von CbdqRelease. Der Minifiltertreiber kann den IRQL verwenden, um die Drehsperre durch Aufrufen von KeReleaseSpinLock zu entsperren. 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(Data, FLT_PREOP_COMPLETE, NULL) aufrufen. Minifiltertreiber müssen die Rückrufdatenstruktur nicht aus der Warteschlange entfernen. Der Filter-Manager ruft automatisch den CbdqRemoveIo der Warteschlange auf, bevor CbdqCompleteCanceledIo aufgerufen wird.